diff options
Diffstat (limited to 'Documentation')
1725 files changed, 48846 insertions, 17349 deletions
diff --git a/Documentation/ABI/stable/sysfs-block b/Documentation/ABI/stable/sysfs-block index c57e5b7cb532..1fe9a553c37b 100644 --- a/Documentation/ABI/stable/sysfs-block +++ b/Documentation/ABI/stable/sysfs-block @@ -295,7 +295,7 @@ Description: capable of executing requests targeting different sector ranges in parallel. For instance, single LUN multi-actuator hard-disks will have an independent_access_ranges directory if the device - correctly advertizes the sector ranges of its actuators. + correctly advertises the sector ranges of its actuators. The independent_access_ranges directory contains one directory per access range, with each range described using the sector diff --git a/Documentation/ABI/stable/sysfs-bus-mhi b/Documentation/ABI/stable/sysfs-bus-mhi index 96ccc3385a2b..1a47f9e0cc84 100644 --- a/Documentation/ABI/stable/sysfs-bus-mhi +++ b/Documentation/ABI/stable/sysfs-bus-mhi @@ -1,7 +1,7 @@ What: /sys/bus/mhi/devices/.../serialnumber Date: Sept 2020 KernelVersion: 5.10 -Contact: Bhaumik Bhatt <bbhatt@codeaurora.org> +Contact: mhi@lists.linux.dev Description: The file holds the serial number of the client device obtained using a BHI (Boot Host Interface) register read after at least one attempt to power up the device has been done. If read @@ -12,7 +12,7 @@ Users: Any userspace application or clients interested in device info. What: /sys/bus/mhi/devices/.../oem_pk_hash Date: Sept 2020 KernelVersion: 5.10 -Contact: Bhaumik Bhatt <bbhatt@codeaurora.org> +Contact: mhi@lists.linux.dev Description: The file holds the OEM PK Hash value of the endpoint device obtained using a BHI (Boot Host Interface) register read after at least one attempt to power up the device has been done. If diff --git a/Documentation/ABI/stable/sysfs-class-infiniband b/Documentation/ABI/stable/sysfs-class-infiniband index ebf08c604336..694f23a03a28 100644 --- a/Documentation/ABI/stable/sysfs-class-infiniband +++ b/Documentation/ABI/stable/sysfs-class-infiniband @@ -356,7 +356,7 @@ Description: pkeys/<n>: (RO) Displays the contents of the physical key table n = 0..126 - mcgs/: (RO) Muticast group table + mcgs/: (RO) Multicast group table <m>/gid_idx/0: (RO) Display the GID mapping m = 1..2 diff --git a/Documentation/ABI/stable/sysfs-driver-dma-idxd b/Documentation/ABI/stable/sysfs-driver-dma-idxd index 534b7a3d59fc..825e619250bf 100644 --- a/Documentation/ABI/stable/sysfs-driver-dma-idxd +++ b/Documentation/ABI/stable/sysfs-driver-dma-idxd @@ -84,7 +84,7 @@ What: /sys/bus/dsa/devices/dsa<m>/pasid_enabled Date: Oct 27, 2020 KernelVersion: 5.11.0 Contact: dmaengine@vger.kernel.org -Description: To indicate if PASID (process address space identifier) is +Description: To indicate if user PASID (process address space identifier) is enabled or not for this device. What: /sys/bus/dsa/devices/dsa<m>/state diff --git a/Documentation/ABI/stable/sysfs-driver-mlxreg-io b/Documentation/ABI/stable/sysfs-driver-mlxreg-io index 60953903d007..2cdfd09123da 100644 --- a/Documentation/ABI/stable/sysfs-driver-mlxreg-io +++ b/Documentation/ABI/stable/sysfs-driver-mlxreg-io @@ -662,3 +662,56 @@ Description: This file shows the system reset cause due to AC power failure. Value 1 in file means this is reset cause, 0 - otherwise. The file is read only. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld5_pn +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld5_version +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld5_version_min +Date: August 2023 +KernelVersion: 6.6 +Contact: Vadim Pasternak <vadimp@nvidia.com> +Description: These files show with which CPLD part numbers, version and minor + versions have been burned the 5-th CPLD device equipped on a + system. + + The files are read only. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_cap +Date: August 2023 +KernelVersion: 6.6 +Contact: Vadim Pasternak <vadimp@nvidia.com> +Description: This file indicates the available method of CPLD/FPGA devices + field update through the JTAG chain: + + b00 - field update through LPC bus register memory space. + b01 - Reserved. + b10 - Reserved. + b11 - field update through CPU GPIOs bit-banging. + + The file is read only. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lid_open +Date: August 2023 +KernelVersion: 6.6 +Contact: Vadim Pasternak <vadimp@nvidia.com> +Description: 1 - indicates that system lid is opened, otherwise 0. + + The file is read only. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_long_pwr_pb +Date: August 2023 +KernelVersion: 6.6 +Contact: Vadim Pasternak <vadimp@nvidia.com> +Description: This file if set 1 indicates that system has been reset by + long press of power button. + + The file is read only. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_swb_dc_dc_pwr_fail +Date: August 2023 +KernelVersion: 6.6 +Contact: Vadim Pasternak <vadimp@nvidia.com> +Description: This file shows 1 in case the system reset happened due to the + failure of any DC-DC power converter devices equipped on the + switch board. + + The file is read only. diff --git a/Documentation/ABI/stable/sysfs-platform-wmi-bmof b/Documentation/ABI/stable/sysfs-platform-wmi-bmof index a786504b6027..2881244e3f09 100644 --- a/Documentation/ABI/stable/sysfs-platform-wmi-bmof +++ b/Documentation/ABI/stable/sysfs-platform-wmi-bmof @@ -2,6 +2,6 @@ What: /sys/bus/wmi/devices/05901221-D566-11D1-B2F0-00A0C9062910[-X]/bmof Date: Jun 2017 KernelVersion: 4.13 Description: - Binary MOF metadata used to decribe the details of available ACPI WMI interfaces. + Binary MOF metadata used to describe the details of available ACPI WMI interfaces. See Documentation/wmi/devices/wmi-bmof.rst for details. diff --git a/Documentation/ABI/testing/configfs-usb-gadget-midi2 b/Documentation/ABI/testing/configfs-usb-gadget-midi2 new file mode 100644 index 000000000000..0eac3aaba137 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-midi2 @@ -0,0 +1,54 @@ +What: /config/usb-gadget/gadget/functions/midi2.name +Date: Jul 2023 +KernelVersion: 6.6 +Description: + The attributes: + + ============ =============================================== + process_ump Flag to process UMP Stream messages (0 or 1) + static_block Flag for static blocks (0 or 1) + iface_name MIDI interface name string + ============ =============================================== + +What: /config/usb-gadget/gadget/functions/midi2.name/ep.number +Date: Jul 2023 +KernelVersion: 6.6 +Description: + This group contains a UMP Endpoint configuration. + A new Endpoint starts from 0, and can be up to 3. + + The attributes: + + ============= =============================================== + protocol_caps MIDI protocol capabilities (1, 2 or 3 for both) + protocol Default MIDI protocol (1 or 2) + ep_name UMP Endpoint name string + product_id Product ID string + manufacturer Manufacture ID (24 bit) + family Device family ID (16 bit) + model Device model ID (16 bit) + sw_revision Software Revision (32 bit) + ============= =============================================== + +What: /config/usb-gadget/gadget/functions/midi2.name/ep.number/block.number +Date: Jul 2023 +KernelVersion: 6.6 +Description: + This group contains a UMP Function Block configuration. + A new block starts from 0, and can be up to 31. + + The attributes: + + ================= ============================================== + name Function Block name string + direction 1: input, 2: output, 3: bidirectional + first_group The first UMP Group number (0-15) + num_groups The number of groups in this FB (1-16) + midi1_first_group The first UMP Group number for MIDI 1.0 (0-15) + midi1_num_groups The number of groups for MIDI 1.0 (0-16) + ui_hint 0: unknown, 1: receiver, 2: sender, 3: both + midi_ci_verison Supported MIDI-CI version number (8 bit) + is_midi1 Legacy MIDI 1.0 device (0, 1 or 2) + sysex8_streams Max number of SysEx8 streams (8 bit) + active Active FB flag (0 or 1) + ================= ============================================== diff --git a/Documentation/ABI/testing/debugfs-driver-habanalabs b/Documentation/ABI/testing/debugfs-driver-habanalabs index 85f6d04f528b..042fd125fbc9 100644 --- a/Documentation/ABI/testing/debugfs-driver-habanalabs +++ b/Documentation/ABI/testing/debugfs-driver-habanalabs @@ -1,4 +1,4 @@ -What: /sys/kernel/debug/habanalabs/hl<n>/addr +What: /sys/kernel/debug/accel/<n>/addr Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -8,34 +8,34 @@ Description: Sets the device address to be used for read or write through only when the IOMMU is disabled. The acceptable value is a string that starts with "0x" -What: /sys/kernel/debug/habanalabs/hl<n>/clk_gate +What: /sys/kernel/debug/accel/<n>/clk_gate Date: May 2020 KernelVersion: 5.8 Contact: ogabbay@kernel.org Description: This setting is now deprecated as clock gating is handled solely by the f/w -What: /sys/kernel/debug/habanalabs/hl<n>/command_buffers +What: /sys/kernel/debug/accel/<n>/command_buffers Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Displays a list with information about the currently allocated command buffers -What: /sys/kernel/debug/habanalabs/hl<n>/command_submission +What: /sys/kernel/debug/accel/<n>/command_submission Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Displays a list with information about the currently active command submissions -What: /sys/kernel/debug/habanalabs/hl<n>/command_submission_jobs +What: /sys/kernel/debug/accel/<n>/command_submission_jobs Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Displays a list with detailed information about each JOB (CB) of each active command submission -What: /sys/kernel/debug/habanalabs/hl<n>/data32 +What: /sys/kernel/debug/accel/<n>/data32 Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -50,7 +50,7 @@ Description: Allows the root user to read or write directly through the If the IOMMU is disabled, it also allows the root user to read or write from the host a device VA of a host mapped memory -What: /sys/kernel/debug/habanalabs/hl<n>/data64 +What: /sys/kernel/debug/accel/<n>/data64 Date: Jan 2020 KernelVersion: 5.6 Contact: ogabbay@kernel.org @@ -65,7 +65,7 @@ Description: Allows the root user to read or write 64 bit data directly If the IOMMU is disabled, it also allows the root user to read or write from the host a device VA of a host mapped memory -What: /sys/kernel/debug/habanalabs/hl<n>/data_dma +What: /sys/kernel/debug/accel/<n>/data_dma Date: Apr 2021 KernelVersion: 5.13 Contact: ogabbay@kernel.org @@ -79,11 +79,11 @@ Description: Allows the root user to read from the device's internal a very long time. This interface doesn't support concurrency in the same device. In GAUDI and GOYA, this action can cause undefined behavior - in case the it is done while the device is executing user + in case it is done while the device is executing user workloads. Only supported on GAUDI at this stage. -What: /sys/kernel/debug/habanalabs/hl<n>/device +What: /sys/kernel/debug/accel/<n>/device Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -91,14 +91,14 @@ Description: Enables the root user to set the device to specific state. Valid values are "disable", "enable", "suspend", "resume". User can read this property to see the valid values -What: /sys/kernel/debug/habanalabs/hl<n>/device_release_watchdog_timeout +What: /sys/kernel/debug/accel/<n>/device_release_watchdog_timeout Date: Oct 2022 KernelVersion: 6.2 Contact: ttayar@habana.ai -Description: The watchdog timeout value in seconds for a device relese upon +Description: The watchdog timeout value in seconds for a device release upon certain error cases, after which the device is reset. -What: /sys/kernel/debug/habanalabs/hl<n>/dma_size +What: /sys/kernel/debug/accel/<n>/dma_size Date: Apr 2021 KernelVersion: 5.13 Contact: ogabbay@kernel.org @@ -108,7 +108,7 @@ Description: Specify the size of the DMA transaction when using DMA to read When the write is finished, the user can read the "data_dma" blob -What: /sys/kernel/debug/habanalabs/hl<n>/dump_razwi_events +What: /sys/kernel/debug/accel/<n>/dump_razwi_events Date: Aug 2022 KernelVersion: 5.20 Contact: fkassabri@habana.ai @@ -117,7 +117,7 @@ Description: Dumps all razwi events to dmesg if exist. the routine will clear the status register. Usage: cat dump_razwi_events -What: /sys/kernel/debug/habanalabs/hl<n>/dump_security_violations +What: /sys/kernel/debug/accel/<n>/dump_security_violations Date: Jan 2021 KernelVersion: 5.12 Contact: ogabbay@kernel.org @@ -125,14 +125,14 @@ Description: Dumps all security violations to dmesg. This will also ack all security violations meanings those violations will not be dumped next time user calls this API -What: /sys/kernel/debug/habanalabs/hl<n>/engines +What: /sys/kernel/debug/accel/<n>/engines Date: Jul 2019 KernelVersion: 5.3 Contact: ogabbay@kernel.org Description: Displays the status registers values of the device engines and their derived idle status -What: /sys/kernel/debug/habanalabs/hl<n>/i2c_addr +What: /sys/kernel/debug/accel/<n>/i2c_addr Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -140,7 +140,7 @@ Description: Sets I2C device address for I2C transaction that is generated by the device's CPU, Not available when device is loaded with secured firmware -What: /sys/kernel/debug/habanalabs/hl<n>/i2c_bus +What: /sys/kernel/debug/accel/<n>/i2c_bus Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -148,7 +148,7 @@ Description: Sets I2C bus address for I2C transaction that is generated by the device's CPU, Not available when device is loaded with secured firmware -What: /sys/kernel/debug/habanalabs/hl<n>/i2c_data +What: /sys/kernel/debug/accel/<n>/i2c_data Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -157,7 +157,7 @@ Description: Triggers an I2C transaction that is generated by the device's reading from the file generates a read transaction, Not available when device is loaded with secured firmware -What: /sys/kernel/debug/habanalabs/hl<n>/i2c_len +What: /sys/kernel/debug/accel/<n>/i2c_len Date: Dec 2021 KernelVersion: 5.17 Contact: obitton@habana.ai @@ -165,7 +165,7 @@ Description: Sets I2C length in bytes for I2C transaction that is generated b the device's CPU, Not available when device is loaded with secured firmware -What: /sys/kernel/debug/habanalabs/hl<n>/i2c_reg +What: /sys/kernel/debug/accel/<n>/i2c_reg Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -173,35 +173,35 @@ Description: Sets I2C register id for I2C transaction that is generated by the device's CPU, Not available when device is loaded with secured firmware -What: /sys/kernel/debug/habanalabs/hl<n>/led0 +What: /sys/kernel/debug/accel/<n>/led0 Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Sets the state of the first S/W led on the device, Not available when device is loaded with secured firmware -What: /sys/kernel/debug/habanalabs/hl<n>/led1 +What: /sys/kernel/debug/accel/<n>/led1 Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Sets the state of the second S/W led on the device, Not available when device is loaded with secured firmware -What: /sys/kernel/debug/habanalabs/hl<n>/led2 +What: /sys/kernel/debug/accel/<n>/led2 Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Sets the state of the third S/W led on the device, Not available when device is loaded with secured firmware -What: /sys/kernel/debug/habanalabs/hl<n>/memory_scrub +What: /sys/kernel/debug/accel/<n>/memory_scrub Date: May 2022 KernelVersion: 5.19 Contact: dhirschfeld@habana.ai Description: Allows the root user to scrub the dram memory. The scrubbing value can be set using the debugfs file memory_scrub_val. -What: /sys/kernel/debug/habanalabs/hl<n>/memory_scrub_val +What: /sys/kernel/debug/accel/<n>/memory_scrub_val Date: May 2022 KernelVersion: 5.19 Contact: dhirschfeld@habana.ai @@ -209,7 +209,7 @@ Description: The value to which the dram will be set to when the user scrubs the dram using 'memory_scrub' debugfs file and the scrubbing value when using module param 'memory_scrub' -What: /sys/kernel/debug/habanalabs/hl<n>/mmu +What: /sys/kernel/debug/accel/<n>/mmu Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -217,19 +217,19 @@ Description: Displays the hop values and physical address for a given ASID and virtual address. The user should write the ASID and VA into the file and then read the file to get the result. e.g. to display info about VA 0x1000 for ASID 1 you need to do: - echo "1 0x1000" > /sys/kernel/debug/habanalabs/hl0/mmu + echo "1 0x1000" > /sys/kernel/debug/accel/0/mmu -What: /sys/kernel/debug/habanalabs/hl<n>/mmu_error +What: /sys/kernel/debug/accel/<n>/mmu_error Date: Mar 2021 KernelVersion: 5.12 Contact: fkassabri@habana.ai Description: Check and display page fault or access violation mmu errors for all MMUs specified in mmu_cap_mask. e.g. to display error info for MMU hw cap bit 9, you need to do: - echo "0x200" > /sys/kernel/debug/habanalabs/hl0/mmu_error - cat /sys/kernel/debug/habanalabs/hl0/mmu_error + echo "0x200" > /sys/kernel/debug/accel/0/mmu_error + cat /sys/kernel/debug/accel/0/mmu_error -What: /sys/kernel/debug/habanalabs/hl<n>/monitor_dump +What: /sys/kernel/debug/accel/<n>/monitor_dump Date: Mar 2022 KernelVersion: 5.19 Contact: osharabi@habana.ai @@ -243,7 +243,7 @@ Description: Allows the root user to dump monitors status from the device's This interface doesn't support concurrency in the same device. Only supported on GAUDI. -What: /sys/kernel/debug/habanalabs/hl<n>/monitor_dump_trig +What: /sys/kernel/debug/accel/<n>/monitor_dump_trig Date: Mar 2022 KernelVersion: 5.19 Contact: osharabi@habana.ai @@ -253,14 +253,14 @@ Description: Triggers dump of monitor data. The value to trigger the operatio When the write is finished, the user can read the "monitor_dump" blob -What: /sys/kernel/debug/habanalabs/hl<n>/set_power_state +What: /sys/kernel/debug/accel/<n>/set_power_state Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Sets the PCI power state. Valid values are "1" for D0 and "2" for D3Hot -What: /sys/kernel/debug/habanalabs/hl<n>/skip_reset_on_timeout +What: /sys/kernel/debug/accel/<n>/skip_reset_on_timeout Date: Jun 2021 KernelVersion: 5.13 Contact: ynudelman@habana.ai @@ -268,7 +268,7 @@ Description: Sets the skip reset on timeout option for the device. Value of "0" means device will be reset in case some CS has timed out, otherwise it will not be reset. -What: /sys/kernel/debug/habanalabs/hl<n>/state_dump +What: /sys/kernel/debug/accel/<n>/state_dump Date: Oct 2021 KernelVersion: 5.15 Contact: ynudelman@habana.ai @@ -279,7 +279,7 @@ Description: Gets the state dump occurring on a CS timeout or failure. Writing an integer X discards X state dumps, so that the next read would return X+1-st newest state dump. -What: /sys/kernel/debug/habanalabs/hl<n>/stop_on_err +What: /sys/kernel/debug/accel/<n>/stop_on_err Date: Mar 2020 KernelVersion: 5.6 Contact: ogabbay@kernel.org @@ -287,21 +287,21 @@ Description: Sets the stop-on_error option for the device engines. Value of "0" is for disable, otherwise enable. Relevant only for GOYA and GAUDI. -What: /sys/kernel/debug/habanalabs/hl<n>/timeout_locked +What: /sys/kernel/debug/accel/<n>/timeout_locked Date: Sep 2021 KernelVersion: 5.16 Contact: obitton@habana.ai Description: Sets the command submission timeout value in seconds. -What: /sys/kernel/debug/habanalabs/hl<n>/userptr +What: /sys/kernel/debug/accel/<n>/userptr Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org -Description: Displays a list with information about the currently user +Description: Displays a list with information about the current user pointers (user virtual addresses) that are pinned and mapped to DMA addresses -What: /sys/kernel/debug/habanalabs/hl<n>/userptr_lookup +What: /sys/kernel/debug/accel/<n>/userptr_lookup Date: Oct 2021 KernelVersion: 5.15 Contact: ogabbay@kernel.org @@ -309,7 +309,7 @@ Description: Allows to search for specific user pointers (user virtual addresses) that are pinned and mapped to DMA addresses, and see their resolution to the specific dma address. -What: /sys/kernel/debug/habanalabs/hl<n>/vm +What: /sys/kernel/debug/accel/<n>/vm Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org diff --git a/Documentation/ABI/testing/debugfs-driver-qat b/Documentation/ABI/testing/debugfs-driver-qat new file mode 100644 index 000000000000..b2db010d851e --- /dev/null +++ b/Documentation/ABI/testing/debugfs-driver-qat @@ -0,0 +1,83 @@ +What: /sys/kernel/debug/qat_<device>_<BDF>/fw_counters +Date: November 2023 +KernelVersion: 6.6 +Contact: qat-linux@intel.com +Description: (RO) Read returns the number of requests sent to the FW and the number of responses + received from the FW for each Acceleration Engine + Reported firmware counters:: + + <N>: Number of requests sent from Acceleration Engine N to FW and responses + Acceleration Engine N received from FW + +What: /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/config +Date: November 2023 +KernelVersion: 6.6 +Contact: qat-linux@intel.com +Description: (RW) Read returns value of the Heartbeat update period. + Write to the file changes this period value. + + This period should reflect planned polling interval of device + health status. High frequency Heartbeat monitoring wastes CPU cycles + but minimizes the customer’s system downtime. Also, if there are + large service requests that take some time to complete, high frequency + Heartbeat monitoring could result in false reports of unresponsiveness + and in those cases, period needs to be increased. + + This parameter is effective only for c3xxx, c62x, dh895xcc devices. + 4xxx has this value internally fixed to 200ms. + + Default value is set to 500. Minimal allowed value is 200. + All values are expressed in milliseconds. + +What: /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/queries_failed +Date: November 2023 +KernelVersion: 6.6 +Contact: qat-linux@intel.com +Description: (RO) Read returns the number of times the device became unresponsive. + + Attribute returns value of the counter which is incremented when + status query results negative. + +What: /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/queries_sent +Date: November 2023 +KernelVersion: 6.6 +Contact: qat-linux@intel.com +Description: (RO) Read returns the number of times the control process checked + if the device is responsive. + + Attribute returns value of the counter which is incremented on + every status query. + +What: /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/status +Date: November 2023 +KernelVersion: 6.6 +Contact: qat-linux@intel.com +Description: (RO) Read returns the device health status. + + Returns 0 when device is healthy or -1 when is unresponsive + or the query failed to send. + + The driver does not monitor for Heartbeat. It is left for a user + to poll the status periodically. + +What: /sys/kernel/debug/qat_<device>_<BDF>/pm_status +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: (RO) Read returns power management information specific to the + QAT device. + + This attribute is only available for qat_4xxx devices. + +What: /sys/kernel/debug/qat_<device>_<BDF>/cnv_errors +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: (RO) Read returns, for each Acceleration Engine (AE), the number + of errors and the type of the last error detected by the device + when performing verified compression. + Reported counters:: + + <N>: Number of Compress and Verify (CnV) errors and type + of the last CnV error detected by Acceleration + Engine N. diff --git a/Documentation/ABI/testing/debugfs-tpmi b/Documentation/ABI/testing/debugfs-tpmi new file mode 100644 index 000000000000..597f0475fe6e --- /dev/null +++ b/Documentation/ABI/testing/debugfs-tpmi @@ -0,0 +1,31 @@ +What: /sys/kernel/debug/tpmi-<n>/pfs_dump +Date: November 2023 +KernelVersion: 6.6 +Contact: srinivas.pandruvada@linux.intel.com +Description: +The PFS (PM Feature Structure) table, shows details of each power +management feature. This includes: +tpmi_id, number of entries, entry size, offset, vsec offset, lock status +and disabled status. +Users: Debugging, any user space test suite + +What: /sys/kernel/debug/tpmi-<n>/tpmi-id-<n>/mem_dump +Date: November 2023 +KernelVersion: 6.6 +Contact: srinivas.pandruvada@linux.intel.com +Description: +Shows the memory dump of the MMIO region for a TPMI ID. +Users: Debugging, any user space test suite + +What: /sys/kernel/debug/tpmi-<n>/tpmi-id-<n>/mem_write +Date: November 2023 +KernelVersion: 6.6 +Contact: srinivas.pandruvada@linux.intel.com +Description: +Allows to write at any offset. It doesn't check for Read/Write access +as hardware will not allow to write at read-only memory. This write is +at offset multiples of 4. The format is instance,offset,contents. +Example: +echo 0,0x20,0xff > mem_write +echo 1,64,64 > mem_write +Users: Debugging, any user space test suite diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy index 49db0ff288e5..c2385183826c 100644 --- a/Documentation/ABI/testing/ima_policy +++ b/Documentation/ABI/testing/ima_policy @@ -57,9 +57,9 @@ Description: stored in security.ima xattr. Requires specifying "digest_type=verity" first.) - appraise_flag:= [check_blacklist] - Currently, blacklist check is only for files signed with appended - signature. + appraise_flag:= [check_blacklist] (deprecated) + Setting the check_blacklist flag is no longer necessary. + All appraisal functions set it by default. digest_type:= verity Require fs-verity's file digest instead of the regular IMA file hash. diff --git a/Documentation/ABI/testing/procfs-diskstats b/Documentation/ABI/testing/procfs-diskstats index e58d641443d3..6a719cf2075c 100644 --- a/Documentation/ABI/testing/procfs-diskstats +++ b/Documentation/ABI/testing/procfs-diskstats @@ -8,7 +8,7 @@ Description: == =================================== 1 major number - 2 minor mumber + 2 minor number 3 device name 4 reads completed successfully 5 reads merged diff --git a/Documentation/ABI/testing/sysfs-bus-coreboot b/Documentation/ABI/testing/sysfs-bus-coreboot index 9c5accecc470..8e8d6af24a4c 100644 --- a/Documentation/ABI/testing/sysfs-bus-coreboot +++ b/Documentation/ABI/testing/sysfs-bus-coreboot @@ -21,7 +21,7 @@ What: /sys/bus/coreboot/devices/cbmem-<id>/address Date: August 2022 Contact: Jack Rosenthal <jrosenth@chromium.org> Description: - This is the pyhsical memory address that the CBMEM entry's data + This is the physical memory address that the CBMEM entry's data begins at, in hexadecimal (e.g., ``0x76ffe000``). What: /sys/bus/coreboot/devices/cbmem-<id>/size diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x index 234c33fbdb55..3acf7fc31659 100644 --- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x @@ -31,7 +31,7 @@ Date: November 2014 KernelVersion: 3.19 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> Description: (RW) Used in conjunction with @addr_idx. Specifies the range of - addresses to trigger on. Inclusion or exclusion is specificed + addresses to trigger on. Inclusion or exclusion is specified in the corresponding access type register. What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_single @@ -304,19 +304,19 @@ What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmtsscr Date: September 2015 KernelVersion: 4.4 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (RO) Print the content of the ETM Trace Start/Stop Conrol +Description: (RO) Print the content of the ETM Trace Start/Stop Control register (0x018). The value is read directly from the HW. What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmtecr1 Date: September 2015 KernelVersion: 4.4 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (RO) Print the content of the ETM Enable Conrol #1 +Description: (RO) Print the content of the ETM Enable Control #1 register (0x024). The value is read directly from the HW. What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmtecr2 Date: September 2015 KernelVersion: 4.4 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (RO) Print the content of the ETM Enable Conrol #2 +Description: (RO) Print the content of the ETM Enable Control #2 register (0x01c). The value is read directly from the HW. diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x index 08b1964f27d3..a0425d70d009 100644 --- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x @@ -446,7 +446,7 @@ Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> Description: (Read) Returns the maximum size of the data value, data address, - VMID, context ID and instuction address in the trace unit + VMID, context ID and instruction address in the trace unit (0x1E8). The value is taken directly from the HW. What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr3 diff --git a/Documentation/ABI/testing/sysfs-bus-counter b/Documentation/ABI/testing/sysfs-bus-counter index dc3b3a5c876b..73ac84c0bca7 100644 --- a/Documentation/ABI/testing/sysfs-bus-counter +++ b/Documentation/ABI/testing/sysfs-bus-counter @@ -22,11 +22,11 @@ Description: phase clock. What: /sys/bus/counter/devices/counterX/external_input_phase_clock_select_available -KernelVersion: 6.4 -Contact: linux-iio@vger.kernel.org +KernelVersion: 6.4 +Contact: linux-iio@vger.kernel.org Description: - Discrete set of available values for the respective device - configuration are listed in this file. + Discrete set of available values for the respective device + configuration are listed in this file. What: /sys/bus/counter/devices/counterX/countY/count KernelVersion: 5.2 diff --git a/Documentation/ABI/testing/sysfs-bus-cxl b/Documentation/ABI/testing/sysfs-bus-cxl index 6350dd82b9a9..087f762ebfd5 100644 --- a/Documentation/ABI/testing/sysfs-bus-cxl +++ b/Documentation/ABI/testing/sysfs-bus-cxl @@ -82,7 +82,12 @@ Description: whether it resides in persistent capacity, volatile capacity, or the LSA, is made permanently unavailable by whatever means is appropriate for the media type. This functionality requires - the device to be not be actively decoding any HPA ranges. + the device to be disabled, that is, not actively decoding any + HPA ranges. This permits avoiding explicit global CPU cache + management, relying instead for it to be done when a region + transitions between software programmed and hardware committed + states. If this file is not present, then there is no hardware + support for the operation. What /sys/bus/cxl/devices/memX/security/erase @@ -92,7 +97,13 @@ Contact: linux-cxl@vger.kernel.org Description: (WO) Write a boolean 'true' string value to this attribute to secure erase user data by changing the media encryption keys for - all user data areas of the device. + all user data areas of the device. This functionality requires + the device to be disabled, that is, not actively decoding any + HPA ranges. This permits avoiding explicit global CPU cache + management, relying instead for it to be done when a region + transitions between software programmed and hardware committed + states. If this file is not present, then there is no hardware + support for the operation. What: /sys/bus/cxl/devices/memX/firmware/ diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-events b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events index 505f080d20a1..77de58d03822 100644 --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-events +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events @@ -47,7 +47,7 @@ Description: Per-pmu performance monitoring events specific to the running syste If a <term> is specified alone (without an assigned value), it is implied that 0x1 is assigned to that <term>. - Examples (each of these lines would be in a seperate file): + Examples (each of these lines would be in a separate file): event=0x2abc event=0x423,inv,cmask=0x3 @@ -83,7 +83,7 @@ Description: Perf event scaling factors A string representing a floating point value expressed in scientific notation to be multiplied by the event count - recieved from the kernel to match the unit specified in the + received from the kernel to match the unit specified in the <event>.unit file. Example: diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci index 12e2bf92783f..40f7cd240591 100644 --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci @@ -80,3 +80,163 @@ Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> Description: read only This sysfs file exposes the cpumask which is designated to make HCALLs to retrieve hv-gpci pmu event counter data. + +What: /sys/devices/hv_gpci/interface/processor_bus_topology +Date: July 2023 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: admin read only + This sysfs file exposes the system topology information by making HCALL + H_GET_PERF_COUNTER_INFO. The HCALL is made with counter request value + PROCESSOR_BUS_TOPOLOGY(0xD0). + + * This sysfs file will be created only for power10 and above platforms. + + * User needs root privileges to read data from this sysfs file. + + * This sysfs file will be created, only when the HCALL returns "H_SUCCESS", + "H_AUTHORITY" or "H_PARAMETER" as the return type. + + HCALL with return error type "H_AUTHORITY" can be resolved during + runtime by setting "Enable Performance Information Collection" option. + + * The end user reading this sysfs file must decode the content as per + underlying platform/firmware. + + Possible error codes while reading this sysfs file: + + * "-EPERM" : Partition is not permitted to retrieve performance information, + required to set "Enable Performance Information Collection" option. + + * "-EIO" : Can't retrieve system information because of invalid buffer length/invalid address + or because of some hardware error. Refer to getPerfCountInfo documentation for + more information. + + * "-EFBIG" : System information exceeds PAGE_SIZE. + +What: /sys/devices/hv_gpci/interface/processor_config +Date: July 2023 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: admin read only + This sysfs file exposes the system topology information by making HCALL + H_GET_PERF_COUNTER_INFO. The HCALL is made with counter request value + PROCESSOR_CONFIG(0x90). + + * This sysfs file will be created only for power10 and above platforms. + + * User needs root privileges to read data from this sysfs file. + + * This sysfs file will be created, only when the HCALL returns "H_SUCCESS", + "H_AUTHORITY" or "H_PARAMETER" as the return type. + + HCALL with return error type "H_AUTHORITY" can be resolved during + runtime by setting "Enable Performance Information Collection" option. + + * The end user reading this sysfs file must decode the content as per + underlying platform/firmware. + + Possible error codes while reading this sysfs file: + + * "-EPERM" : Partition is not permitted to retrieve performance information, + required to set "Enable Performance Information Collection" option. + + * "-EIO" : Can't retrieve system information because of invalid buffer length/invalid address + or because of some hardware error. Refer to getPerfCountInfo documentation for + more information. + + * "-EFBIG" : System information exceeds PAGE_SIZE. + +What: /sys/devices/hv_gpci/interface/affinity_domain_via_virtual_processor +Date: July 2023 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: admin read only + This sysfs file exposes the system topology information by making HCALL + H_GET_PERF_COUNTER_INFO. The HCALL is made with counter request value + AFFINITY_DOMAIN_INFORMATION_BY_VIRTUAL_PROCESSOR(0xA0). + + * This sysfs file will be created only for power10 and above platforms. + + * User needs root privileges to read data from this sysfs file. + + * This sysfs file will be created, only when the HCALL returns "H_SUCCESS", + "H_AUTHORITY" or "H_PARAMETER" as the return type. + + HCALL with return error type "H_AUTHORITY" can be resolved during + runtime by setting "Enable Performance Information Collection" option. + + * The end user reading this sysfs file must decode the content as per + underlying platform/firmware. + + Possible error codes while reading this sysfs file: + + * "-EPERM" : Partition is not permitted to retrieve performance information, + required to set "Enable Performance Information Collection" option. + + * "-EIO" : Can't retrieve system information because of invalid buffer length/invalid address + or because of some hardware error. Refer to getPerfCountInfo documentation for + more information. + + * "-EFBIG" : System information exceeds PAGE_SIZE. + +What: /sys/devices/hv_gpci/interface/affinity_domain_via_domain +Date: July 2023 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: admin read only + This sysfs file exposes the system topology information by making HCALL + H_GET_PERF_COUNTER_INFO. The HCALL is made with counter request value + AFFINITY_DOMAIN_INFORMATION_BY_DOMAIN(0xB0). + + * This sysfs file will be created only for power10 and above platforms. + + * User needs root privileges to read data from this sysfs file. + + * This sysfs file will be created, only when the HCALL returns "H_SUCCESS", + "H_AUTHORITY" or "H_PARAMETER" as the return type. + + HCALL with return error type "H_AUTHORITY" can be resolved during + runtime by setting "Enable Performance Information Collection" option. + + * The end user reading this sysfs file must decode the content as per + underlying platform/firmware. + + Possible error codes while reading this sysfs file: + + * "-EPERM" : Partition is not permitted to retrieve performance information, + required to set "Enable Performance Information Collection" option. + + * "-EIO" : Can't retrieve system information because of invalid buffer length/invalid address + or because of some hardware error. Refer to getPerfCountInfo documentation for + more information. + + * "-EFBIG" : System information exceeds PAGE_SIZE. + +What: /sys/devices/hv_gpci/interface/affinity_domain_via_partition +Date: July 2023 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: admin read only + This sysfs file exposes the system topology information by making HCALL + H_GET_PERF_COUNTER_INFO. The HCALL is made with counter request value + AFFINITY_DOMAIN_INFORMATION_BY_PARTITION(0xB1). + + * This sysfs file will be created only for power10 and above platforms. + + * User needs root privileges to read data from this sysfs file. + + * This sysfs file will be created, only when the HCALL returns "H_SUCCESS", + "H_AUTHORITY" or "H_PARAMETER" as the return type. + + HCALL with return error type "H_AUTHORITY" can be resolved during + runtime by setting "Enable Performance Information Collection" option. + + * The end user reading this sysfs file must decode the content as per + underlying platform/firmware. + + Possible error codes while reading this sysfs file: + + * "-EPERM" : Partition is not permitted to retrieve performance information, + required to set "Enable Performance Information Collection" option. + + * "-EIO" : Can't retrieve system information because of invalid buffer length/invalid address + or because of some hardware error. Refer to getPerfCountInfo documentation for + more information. + + * "-EFBIG" : System information exceeds PAGE_SIZE. diff --git a/Documentation/ABI/testing/sysfs-bus-fsi-devices-sbefifo b/Documentation/ABI/testing/sysfs-bus-fsi-devices-sbefifo index 531fe9d6b40a..c7393b4dd2d8 100644 --- a/Documentation/ABI/testing/sysfs-bus-fsi-devices-sbefifo +++ b/Documentation/ABI/testing/sysfs-bus-fsi-devices-sbefifo @@ -5,6 +5,6 @@ Description: Indicates whether or not this SBE device has experienced a timeout; i.e. the SBE did not respond within the time allotted by the driver. A value of 1 indicates that a timeout has - ocurred and no transfers have completed since the timeout. A - value of 0 indicates that no timeout has ocurred, or if one - has, more recent transfers have completed successful. + occurred and no transfers have completed since the timeout. A + value of 0 indicates that no timeout has occurred, or if one + has, more recent transfers have completed successfully. diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480 b/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480 index 42dfc9399d2d..288bc2fa9547 100644 --- a/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480 +++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480 @@ -8,7 +8,7 @@ Description: NONE no device USB USB device is attached UART UART is attached - CHARGER Charger is attaced + CHARGER Charger is attached JIG JIG is attached ======= ====================== diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index 7140e8e7313f..a2854dc9a839 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -2163,3 +2163,19 @@ Contact: linux-iio@vger.kernel.org Description: An example format is 16-bytes, 2-digits-per-byte, HEX-string representing the sensor unique ID number. + +What: /sys/.../events/in_proximity_thresh_either_runningperiod +KernelVersion: 6.6 +Contact: linux-iio@vger.kernel.org +Description: + A running period of time (in seconds) for which + in_proximity_thresh_either_runningcount amount of conditions + must occur before an event is generated. If direction is not + specified then this period applies to both directions. + +What: /sys/.../events/in_proximity_thresh_either_runningcount +KernelVersion: 6.6 +Contact: linux-iio@vger.kernel.org +Description: + Number of conditions that must occur, during a running + period, before an event is generated. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-filter-admv8818 b/Documentation/ABI/testing/sysfs-bus-iio-filter-admv8818 index f6c035752639..31dbb390573f 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-filter-admv8818 +++ b/Documentation/ABI/testing/sysfs-bus-iio-filter-admv8818 @@ -7,6 +7,8 @@ Description: - auto -> Adjust bandpass filter to track changes in input clock rate. - manual -> disable/unregister the clock rate notifier / input clock tracking. + - bypass -> bypass low pass filter, high pass filter and disable/unregister + the clock rate notifier What: /sys/bus/iio/devices/iio:deviceX/filter_mode KernelVersion: diff --git a/Documentation/ABI/testing/sysfs-bus-nfit b/Documentation/ABI/testing/sysfs-bus-nfit index e7282d184a74..ed483a11c58c 100644 --- a/Documentation/ABI/testing/sysfs-bus-nfit +++ b/Documentation/ABI/testing/sysfs-bus-nfit @@ -121,7 +121,7 @@ KernelVersion: v4.7 Contact: nvdimm@lists.linux.dev Description: (RO) ACPI specification 6.2 section 5.2.25.9, defines an - identifier for an NVDIMM, which refelects the id attribute. + identifier for an NVDIMM, which reflects the id attribute. What: /sys/bus/nd/devices/nmemX/nfit/subsystem_vendor diff --git a/Documentation/ABI/testing/sysfs-bus-nvdimm b/Documentation/ABI/testing/sysfs-bus-nvdimm index de8c5a59c77f..64eb8f4c6a41 100644 --- a/Documentation/ABI/testing/sysfs-bus-nvdimm +++ b/Documentation/ABI/testing/sysfs-bus-nvdimm @@ -18,10 +18,12 @@ Description: (RO) Attribute group to describe the magic bits Each attribute under this group defines a bit range of the perf_event_attr.config. Supported attribute is listed below:: + event = "config:0-4" - event ID For example:: - ctl_res_cnt = "event=0x1" + + ctl_res_cnt = "event=0x1" What: /sys/bus/event_source/devices/nmemX/events Date: February 2022 diff --git a/Documentation/ABI/testing/sysfs-bus-papr-pmem b/Documentation/ABI/testing/sysfs-bus-papr-pmem index 4ac0673901e7..34ee8c59ab25 100644 --- a/Documentation/ABI/testing/sysfs-bus-papr-pmem +++ b/Documentation/ABI/testing/sysfs-bus-papr-pmem @@ -8,7 +8,7 @@ Description: more bits set in the dimm-health-bitmap retrieved in response to H_SCM_HEALTH hcall. The details of the bit flags returned in response to this hcall is available - at 'Documentation/powerpc/papr_hcalls.rst' . Below are + at 'Documentation/arch/powerpc/papr_hcalls.rst' . Below are the flags reported in this sysfs file: * "not_armed" @@ -30,7 +30,7 @@ Description: Indicating that contents of the NVDIMM have been scrubbed. * "locked" - Indicating that NVDIMM contents cant + Indicating that NVDIMM contents can't be modified until next power cycle. What: /sys/bus/nd/devices/nmemX/papr/perf_stats diff --git a/Documentation/ABI/testing/sysfs-bus-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt index 76ab3e1fe374..221b6c75ed93 100644 --- a/Documentation/ABI/testing/sysfs-bus-thunderbolt +++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt @@ -1,7 +1,7 @@ What: /sys/bus/thunderbolt/devices/.../domainX/boot_acl Date: Jun 2018 KernelVersion: 4.17 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: Holds a comma separated list of device unique_ids that are allowed to be connected automatically during system startup (e.g boot devices). The list always contains @@ -33,7 +33,7 @@ Description: This attribute tells whether the system supports What: /sys/bus/thunderbolt/devices/.../domainX/iommu_dma_protection Date: Mar 2019 KernelVersion: 4.21 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: This attribute tells whether the system uses IOMMU for DMA protection. Value of 1 means IOMMU is used 0 means it is not (DMA protection is solely based on Thunderbolt @@ -42,7 +42,7 @@ Description: This attribute tells whether the system uses IOMMU What: /sys/bus/thunderbolt/devices/.../domainX/security Date: Sep 2017 KernelVersion: 4.13 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: This attribute holds current Thunderbolt security level set by the system BIOS. Possible values are: @@ -64,7 +64,7 @@ Description: This attribute holds current Thunderbolt security level What: /sys/bus/thunderbolt/devices/.../authorized Date: Sep 2017 KernelVersion: 4.13 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: This attribute is used to authorize Thunderbolt devices after they have been connected. If the device is not authorized, no PCIe devices are available to the system. @@ -98,7 +98,7 @@ Description: This attribute is used to authorize Thunderbolt devices What: /sys/bus/thunderbolt/devices/.../boot Date: Jun 2018 KernelVersion: 4.17 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: This attribute contains 1 if Thunderbolt device was already authorized on boot and 0 otherwise. @@ -113,7 +113,7 @@ Description: This attribute contains the generation of the Thunderbolt What: /sys/bus/thunderbolt/devices/.../key Date: Sep 2017 KernelVersion: 4.13 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: When a devices supports Thunderbolt secure connect it will have this attribute. Writing 32 byte hex string changes authorization to use the secure connection method instead. @@ -123,14 +123,14 @@ Description: When a devices supports Thunderbolt secure connect it will What: /sys/bus/thunderbolt/devices/.../device Date: Sep 2017 KernelVersion: 4.13 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: This attribute contains id of this device extracted from the device DROM. What: /sys/bus/thunderbolt/devices/.../device_name Date: Sep 2017 KernelVersion: 4.13 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: This attribute contains name of this device extracted from the device DROM. @@ -172,21 +172,21 @@ Description: This attribute reports number of TX lanes the device is What: /sys/bus/thunderbolt/devices/.../vendor Date: Sep 2017 KernelVersion: 4.13 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: This attribute contains vendor id of this device extracted from the device DROM. What: /sys/bus/thunderbolt/devices/.../vendor_name Date: Sep 2017 KernelVersion: 4.13 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: This attribute contains vendor name of this device extracted from the device DROM. What: /sys/bus/thunderbolt/devices/.../unique_id Date: Sep 2017 KernelVersion: 4.13 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: This attribute contains unique_id string of this device. This is either read from hardware registers (UUID on newer hardware) or based on UID from the device DROM. @@ -195,7 +195,7 @@ Description: This attribute contains unique_id string of this device. What: /sys/bus/thunderbolt/devices/.../nvm_version Date: Sep 2017 KernelVersion: 4.13 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: If the device has upgradeable firmware the version number is available here. Format: %x.%x, major.minor. If the device is in safe mode reading the file returns @@ -204,7 +204,7 @@ Description: If the device has upgradeable firmware the version What: /sys/bus/thunderbolt/devices/.../nvm_authenticate Date: Sep 2017 KernelVersion: 4.13 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: When new NVM image is written to the non-active NVM area (through non_activeX NVMem device), the authentication procedure is started by writing to @@ -246,7 +246,7 @@ Description: For supported devices, automatically authenticate the new Thunderbo What: /sys/bus/thunderbolt/devices/<xdomain>.<service>/key Date: Jan 2018 KernelVersion: 4.15 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: This contains name of the property directory the XDomain service exposes. This entry describes the protocol in question. Following directories are already reserved by @@ -261,35 +261,35 @@ Description: This contains name of the property directory the XDomain What: /sys/bus/thunderbolt/devices/<xdomain>.<service>/modalias Date: Jan 2018 KernelVersion: 4.15 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: Stores the same MODALIAS value emitted by uevent for the XDomain service. Format: tbtsvc:kSpNvNrN What: /sys/bus/thunderbolt/devices/<xdomain>.<service>/prtcid Date: Jan 2018 KernelVersion: 4.15 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: This contains XDomain protocol identifier the XDomain service supports. What: /sys/bus/thunderbolt/devices/<xdomain>.<service>/prtcvers Date: Jan 2018 KernelVersion: 4.15 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: This contains XDomain protocol version the XDomain service supports. What: /sys/bus/thunderbolt/devices/<xdomain>.<service>/prtcrevs Date: Jan 2018 KernelVersion: 4.15 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: This contains XDomain software version the XDomain service supports. What: /sys/bus/thunderbolt/devices/<xdomain>.<service>/prtcstns Date: Jan 2018 KernelVersion: 4.15 -Contact: thunderbolt-software@lists.01.org +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> Description: This contains XDomain service specific settings as bitmask. Format: %x diff --git a/Documentation/ABI/testing/sysfs-bus-umc b/Documentation/ABI/testing/sysfs-bus-umc deleted file mode 100644 index 948fec412446..000000000000 --- a/Documentation/ABI/testing/sysfs-bus-umc +++ /dev/null @@ -1,28 +0,0 @@ -What: /sys/bus/umc/ -Date: July 2008 -KernelVersion: 2.6.27 -Contact: David Vrabel <david.vrabel@csr.com> -Description: - The Wireless Host Controller Interface (WHCI) - specification describes a PCI-based device with - multiple capabilities; the UWB Multi-interface - Controller (UMC). - - The umc bus presents each of the individual - capabilties as a device. - -What: /sys/bus/umc/devices/.../capability_id -Date: July 2008 -KernelVersion: 2.6.27 -Contact: David Vrabel <david.vrabel@csr.com> -Description: - The ID of this capability, with 0 being the radio - controller capability. - -What: /sys/bus/umc/devices/.../version -Date: July 2008 -KernelVersion: 2.6.27 -Contact: David Vrabel <david.vrabel@csr.com> -Description: - The specification version this capability's hardware - interface complies with. diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index be663258b9b7..a44bfe020061 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -28,40 +28,6 @@ Description: drivers, non-authorized one are not. By default, wired USB devices are authorized. - Certified Wireless USB devices are not authorized - initially and should be (by writing 1) after the - device has been authenticated. - -What: /sys/bus/usb/device/.../wusb_cdid -Date: July 2008 -KernelVersion: 2.6.27 -Contact: David Vrabel <david.vrabel@csr.com> -Description: - For Certified Wireless USB devices only. - - A devices's CDID, as 16 space-separated hex octets. - -What: /sys/bus/usb/device/.../wusb_ck -Date: July 2008 -KernelVersion: 2.6.27 -Contact: David Vrabel <david.vrabel@csr.com> -Description: - For Certified Wireless USB devices only. - - Write the device's connection key (CK) to start the - authentication of the device. The CK is 16 - space-separated hex octets. - -What: /sys/bus/usb/device/.../wusb_disconnect -Date: July 2008 -KernelVersion: 2.6.27 -Contact: David Vrabel <david.vrabel@csr.com> -Description: - For Certified Wireless USB devices only. - - Write a 1 to force the device to disconnect - (equivalent to unplugging a wired USB device). - What: /sys/bus/usb/drivers/.../new_id Date: October 2011 Contact: linux-usb@vger.kernel.org diff --git a/Documentation/ABI/testing/sysfs-class b/Documentation/ABI/testing/sysfs-class index 676530fcf747..906735faa1b8 100644 --- a/Documentation/ABI/testing/sysfs-class +++ b/Documentation/ABI/testing/sysfs-class @@ -1,5 +1,5 @@ What: /sys/class/ -Date: Febuary 2006 +Date: February 2006 Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Description: The /sys/class directory will consist of a group of diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl index 594fda254130..cfc48a87706b 100644 --- a/Documentation/ABI/testing/sysfs-class-cxl +++ b/Documentation/ABI/testing/sysfs-class-cxl @@ -42,7 +42,7 @@ What: /sys/class/cxl/<afu>/mmio_size Date: September 2014 Contact: linuxppc-dev@lists.ozlabs.org Description: read only - Decimal value of the size of the MMIO space that may be mmaped + Decimal value of the size of the MMIO space that may be mmapped by userspace. Users: https://github.com/ibm-capi/libcxl @@ -155,7 +155,7 @@ What: /sys/class/cxl/<afu>m/mmio_size Date: September 2014 Contact: linuxppc-dev@lists.ozlabs.org Description: read only - Decimal value of the size of the MMIO space that may be mmaped + Decimal value of the size of the MMIO space that may be mmapped by userspace. This includes all slave contexts space also. Users: https://github.com/ibm-capi/libcxl diff --git a/Documentation/ABI/testing/sysfs-class-firmware b/Documentation/ABI/testing/sysfs-class-firmware index 978d3d500400..fba87a55f3ca 100644 --- a/Documentation/ABI/testing/sysfs-class-firmware +++ b/Documentation/ABI/testing/sysfs-class-firmware @@ -1,7 +1,7 @@ What: /sys/class/firmware/.../data Date: July 2022 KernelVersion: 5.19 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Russ Weight <russ.weight@linux.dev> Description: The data sysfs file is used for firmware-fallback and for firmware uploads. Cat a firmware image to this sysfs file after you echo 1 to the loading sysfs file. When the firmware @@ -13,7 +13,7 @@ Description: The data sysfs file is used for firmware-fallback and for What: /sys/class/firmware/.../cancel Date: July 2022 KernelVersion: 5.19 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Russ Weight <russ.weight@linux.dev> Description: Write-only. For firmware uploads, write a "1" to this file to request that the transfer of firmware data to the lower-level device be canceled. This request will be rejected (EBUSY) if @@ -23,7 +23,7 @@ Description: Write-only. For firmware uploads, write a "1" to this file to What: /sys/class/firmware/.../error Date: July 2022 KernelVersion: 5.19 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Russ Weight <russ.weight@linux.dev> Description: Read-only. Returns a string describing a failed firmware upload. This string will be in the form of <STATUS>:<ERROR>, where <STATUS> will be one of the status strings described @@ -37,7 +37,7 @@ Description: Read-only. Returns a string describing a failed firmware What: /sys/class/firmware/.../loading Date: July 2022 KernelVersion: 5.19 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Russ Weight <russ.weight@linux.dev> Description: The loading sysfs file is used for both firmware-fallback and for firmware uploads. Echo 1 onto the loading file to indicate you are writing a firmware file to the data sysfs node. Echo @@ -49,7 +49,7 @@ Description: The loading sysfs file is used for both firmware-fallback and What: /sys/class/firmware/.../remaining_size Date: July 2022 KernelVersion: 5.19 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Russ Weight <russ.weight@linux.dev> Description: Read-only. For firmware upload, this file contains the size of the firmware data that remains to be transferred to the lower-level device driver. The size value is initialized to @@ -62,7 +62,7 @@ Description: Read-only. For firmware upload, this file contains the size What: /sys/class/firmware/.../status Date: July 2022 KernelVersion: 5.19 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Russ Weight <russ.weight@linux.dev> Description: Read-only. Returns a string describing the current status of a firmware upload. The string will be one of the following: idle, "receiving", "preparing", "transferring", "programming". @@ -70,7 +70,7 @@ Description: Read-only. Returns a string describing the current status of What: /sys/class/firmware/.../timeout Date: July 2022 KernelVersion: 5.19 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Russ Weight <russ.weight@linux.dev> Description: This file supports the timeout mechanism for firmware fallback. This file has no affect on firmware uploads. For more information on timeouts please see the documentation diff --git a/Documentation/ABI/testing/sysfs-class-firmware-attributes b/Documentation/ABI/testing/sysfs-class-firmware-attributes index 1b3ecae80b3d..9c82c7b42ff8 100644 --- a/Documentation/ABI/testing/sysfs-class-firmware-attributes +++ b/Documentation/ABI/testing/sysfs-class-firmware-attributes @@ -22,6 +22,11 @@ Description: - integer: a range of numerical values - string + HP specific types + ----------------- + - ordered-list - a set of ordered list valid values + + All attribute types support the following values: current_value: @@ -126,6 +131,21 @@ Description: value will not be effective through sysfs until this rule is met. + HP specific class extensions + ------------------------------ + + On HP systems the following additional attributes are available: + + "ordered-list"-type specific properties: + + elements: + A file that can be read to obtain the possible + list of values of the <attr>. Values are separated using + semi-colon (``;``) and listed according to their priority. + An element listed first has the highest priority. Writing + the list in a different order to current_value alters + the priority order for the particular attribute. + What: /sys/class/firmware-attributes/*/authentication/ Date: February 2021 KernelVersion: 5.11 @@ -206,7 +226,7 @@ Description: Drivers may emit a CHANGE uevent when a password is set or unset userspace may check it again. - On Dell and Lenovo systems, if Admin password is set, then all BIOS attributes + On Dell, Lenovo and HP systems, if Admin password is set, then all BIOS attributes require password validation. On Lenovo systems if you change the Admin password the new password is not active until the next boot. @@ -296,6 +316,15 @@ Description: echo "signature" > authentication/Admin/signature echo "password" > authentication/Admin/certificate_to_password + HP specific class extensions + -------------------------------- + + On HP systems the following additional settings are available: + + role: enhanced-bios-auth: + This role is specific to Secure Platform Management (SPM) attribute. + It requires configuring an endorsement (kek) and signing certificate (sk). + What: /sys/class/firmware-attributes/*/attributes/pending_reboot Date: February 2021 @@ -311,7 +340,7 @@ Description: == ========================================= 0 All BIOS attributes setting are current 1 A reboot is necessary to get pending BIOS - attribute changes applied + attribute changes applied == ========================================= Note, userspace applications need to follow below steps for efficient @@ -354,6 +383,36 @@ Description: Note that any changes to this attribute requires a reboot for changes to take effect. +What: /sys/class/firmware-attributes/*/attributes/save_settings +Date: August 2023 +KernelVersion: 6.6 +Contact: Mark Pearson <mpearson-lenovo@squebb.ca> +Description: + On Lenovo platforms there is a limitation in the number of times an attribute can be + saved. This is an architectural limitation and it limits the number of attributes + that can be modified to 48. + A solution for this is instead of the attribute being saved after every modification, + to allow a user to bulk set the attributes, and then trigger a final save. This allows + unlimited attributes. + + Read the attribute to check what save mode is enabled (single or bulk). + E.g: + # cat /sys/class/firmware-attributes/thinklmi/attributes/save_settings + single + + Write the attribute with 'bulk' to enable bulk save mode. + Write the attribute with 'single' to enable saving, after every attribute set. + The default setting is single mode. + E.g: + # echo bulk > /sys/class/firmware-attributes/thinklmi/attributes/save_settings + + When in bulk mode write 'save' to trigger a save of all currently modified attributes. + Note, once a save has been triggered, in bulk mode, attributes can no longer be set and + will return a permissions error. This is to prevent users hitting the 48+ save limitation + (which requires entering the BIOS to clear the error condition) + E.g: + # echo save > /sys/class/firmware-attributes/thinklmi/attributes/save_settings + What: /sys/class/firmware-attributes/*/attributes/debug_cmd Date: July 2021 KernelVersion: 5.14 @@ -364,3 +423,71 @@ Description: use it to enable extra debug attributes or BIOS features for testing purposes. Note that any changes to this attribute requires a reboot for changes to take effect. + + + HP specific class extensions - Secure Platform Manager (SPM) + -------------------------------- + +What: /sys/class/firmware-attributes/*/authentication/SPM/kek +Date: March 2023 +KernelVersion: 5.18 +Contact: "Jorge Lopez" <jorge.lopez2@hp.com> +Description: + 'kek' Key-Encryption-Key is a write-only file that can be used to configure the + RSA public key that will be used by the BIOS to verify + signatures when setting the signing key. When written, + the bytes should correspond to the KEK certificate + (x509 .DER format containing an OU). The size of the + certificate must be less than or equal to 4095 bytes. + +What: /sys/class/firmware-attributes/*/authentication/SPM/sk +Date: March 2023 +KernelVersion: 5.18 +Contact: "Jorge Lopez" <jorge.lopez2@hp.com> +Description: + 'sk' Signature Key is a write-only file that can be used to configure the RSA + public key that will be used by the BIOS to verify signatures + when configuring BIOS settings and security features. When + written, the bytes should correspond to the modulus of the + public key. The exponent is assumed to be 0x10001. + +What: /sys/class/firmware-attributes/*/authentication/SPM/status +Date: March 2023 +KernelVersion: 5.18 +Contact: "Jorge Lopez" <jorge.lopez2@hp.com> +Description: + 'status' is a read-only file that returns ASCII text in JSON format reporting + the status information. + + "State": "not provisioned | provisioned | provisioning in progress", + "Version": "Major.Minor", + "Nonce": <16-bit unsigned number display in base 10>, + "FeaturesInUse": <16-bit unsigned number display in base 10>, + "EndorsementKeyMod": "<256 bytes in base64>", + "SigningKeyMod": "<256 bytes in base64>" + +What: /sys/class/firmware-attributes/*/attributes/Sure_Start/audit_log_entries +Date: March 2023 +KernelVersion: 5.18 +Contact: "Jorge Lopez" <jorge.lopez2@hp.com> +Description: + 'audit_log_entries' is a read-only file that returns the events in the log. + + Audit log entry format + + Byte 0-15: Requested Audit Log entry (Each Audit log is 16 bytes) + Byte 16-127: Unused + +What: /sys/class/firmware-attributes/*/attributes/Sure_Start/audit_log_entry_count +Date: March 2023 +KernelVersion: 5.18 +Contact: "Jorge Lopez" <jorge.lopez2@hp.com> +Description: + 'audit_log_entry_count' is a read-only file that returns the number of existing + audit log events available to be read. Values are separated using comma. (``,``) + + [No of entries],[log entry size],[Max number of entries supported] + + log entry size identifies audit log size for the current BIOS version. + The current size is 16 bytes but it can be up to 128 bytes long in future BIOS + versions. diff --git a/Documentation/ABI/testing/sysfs-class-led b/Documentation/ABI/testing/sysfs-class-led index 2e24ac3bd7ef..b2ff0012c0f2 100644 --- a/Documentation/ABI/testing/sysfs-class-led +++ b/Documentation/ABI/testing/sysfs-class-led @@ -59,6 +59,15 @@ Description: brightness. Reading this file when no hw brightness change event has happened will return an ENODATA error. +What: /sys/class/leds/<led>/color +Date: June 2023 +KernelVersion: 6.5 +Description: + Color of the LED. + + This is a read-only file. Reading this file returns the color + of the LED as a string (e.g: "red", "green", "multicolor"). + What: /sys/class/leds/<led>/trigger Date: March 2006 KernelVersion: 2.6.17 diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia b/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia index c4d46970c1cf..369b4ae8be5f 100644 --- a/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia +++ b/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia @@ -12,3 +12,17 @@ Description: (RW) On the front panel of the Turris Omnia router there is also able to change this setting from software. Format: %i + +What: /sys/class/leds/<led>/device/gamma_correction +Date: August 2023 +KernelVersion: 6.6 +Contact: Marek Behún <kabel@kernel.org> +Description: (RW) Newer versions of the microcontroller firmware of the + Turris Omnia router support gamma correction for the RGB LEDs. + This feature can be enabled/disabled by writing to this file. + + If the feature is not supported because the MCU firmware is too + old, the file always reads as 0, and writing to the file results + in the EOPNOTSUPP error. + + Format: %i diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-netdev b/Documentation/ABI/testing/sysfs-class-led-trigger-netdev index 78b62a23b14a..f6d9d72ce77b 100644 --- a/Documentation/ABI/testing/sysfs-class-led-trigger-netdev +++ b/Documentation/ABI/testing/sysfs-class-led-trigger-netdev @@ -13,7 +13,7 @@ Description: Specifies the duration of the LED blink in milliseconds. Defaults to 50 ms. - With hw_control ON, the interval value MUST be set to the + When offloaded is true, the interval value MUST be set to the default value and cannot be changed. Trying to set any value in this specific mode will return an EINVAL error. @@ -44,8 +44,8 @@ Description: If set to 1, the LED will blink for the milliseconds specified in interval to signal transmission. - With hw_control ON, the blink interval is controlled by hardware - and won't reflect the value set in interval. + When offloaded is true, the blink interval is controlled by + hardware and won't reflect the value set in interval. What: /sys/class/leds/<led>/rx Date: Dec 2017 @@ -59,21 +59,21 @@ Description: If set to 1, the LED will blink for the milliseconds specified in interval to signal reception. - With hw_control ON, the blink interval is controlled by hardware - and won't reflect the value set in interval. + When offloaded is true, the blink interval is controlled by + hardware and won't reflect the value set in interval. -What: /sys/class/leds/<led>/hw_control +What: /sys/class/leds/<led>/offloaded Date: Jun 2023 KernelVersion: 6.5 Contact: linux-leds@vger.kernel.org Description: - Communicate whether the LED trigger modes are driven by hardware - or software fallback is used. + Communicate whether the LED trigger modes are offloaded to + hardware or whether software fallback is used. If 0, the LED is using software fallback to blink. - If 1, the LED is using hardware control to blink and signal the - requested modes. + If 1, the LED blinking in requested mode is offloaded to + hardware. What: /sys/class/leds/<led>/link_10 Date: Jun 2023 diff --git a/Documentation/ABI/testing/sysfs-class-mtd b/Documentation/ABI/testing/sysfs-class-mtd index 3bc7c0a95c92..f77fa4f6d465 100644 --- a/Documentation/ABI/testing/sysfs-class-mtd +++ b/Documentation/ABI/testing/sysfs-class-mtd @@ -39,7 +39,7 @@ KernelVersion: 2.6.29 Contact: linux-mtd@lists.infradead.org Description: Major and minor numbers of the character device corresponding - to the read-only variant of thie MTD device (in + to the read-only variant of the MTD device (in <major>:<minor> format). In this case <minor> will be odd. What: /sys/class/mtd/mtdX/erasesize diff --git a/Documentation/ABI/testing/sysfs-class-net b/Documentation/ABI/testing/sysfs-class-net index 1419103d11f9..ebf21beba846 100644 --- a/Documentation/ABI/testing/sysfs-class-net +++ b/Documentation/ABI/testing/sysfs-class-net @@ -82,7 +82,7 @@ KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org Description: Indicates the current physical link state of the interface. - Posssible values are: + Possible values are: == ===================== 0 physical link is down diff --git a/Documentation/ABI/testing/sysfs-class-net-queues b/Documentation/ABI/testing/sysfs-class-net-queues index 978b76358661..906ff3ca928a 100644 --- a/Documentation/ABI/testing/sysfs-class-net-queues +++ b/Documentation/ABI/testing/sysfs-class-net-queues @@ -39,7 +39,7 @@ Contact: netdev@vger.kernel.org Description: Mask of the CPU(s) currently enabled to participate into the Transmit Packet Steering packet processing flow for this - network device transmit queue. Possible vaules depend on the + network device transmit queue. Possible values depend on the number of available CPU(s) in the system. What: /sys/class/<iface>/queues/tx-<queue>/xps_rxqs diff --git a/Documentation/ABI/testing/sysfs-class-power-wilco b/Documentation/ABI/testing/sysfs-class-power-wilco index 82af180fcaab..083c4641b4c4 100644 --- a/Documentation/ABI/testing/sysfs-class-power-wilco +++ b/Documentation/ABI/testing/sysfs-class-power-wilco @@ -22,7 +22,7 @@ Description: Long Life: Customized charge rate for last longer battery life. On Wilco device this mode is pre-configured in the factory - through EC's private PID. Swiching to a different mode will + through EC's private PID. Switching to a different mode will be denied by Wilco EC when Long Life mode is enabled. What: /sys/class/power_supply/wilco-charger/charge_control_start_threshold diff --git a/Documentation/ABI/testing/sysfs-class-remoteproc b/Documentation/ABI/testing/sysfs-class-remoteproc index 0c9ee55098b8..b2b8e2db2503 100644 --- a/Documentation/ABI/testing/sysfs-class-remoteproc +++ b/Documentation/ABI/testing/sysfs-class-remoteproc @@ -81,7 +81,7 @@ Description: Remote processor coredump configuration collected userspace will directly read from the remote processor's device memory. Extra buffer will not be used to copy the dump. Also recovery process will not proceed until - all data is read by usersapce. + all data is read by userspace. What: /sys/class/remoteproc/.../recovery Date: July 2020 diff --git a/Documentation/ABI/testing/sysfs-class-thermal b/Documentation/ABI/testing/sysfs-class-thermal index 8eee37982b2a..968d89e15e8e 100644 --- a/Documentation/ABI/testing/sysfs-class-thermal +++ b/Documentation/ABI/testing/sysfs-class-thermal @@ -4,7 +4,7 @@ Description: This is given by thermal zone driver as part of registration. E.g: "acpitz" indicates it's an ACPI thermal device. In order to keep it consistent with hwmon sys attribute; this - shouldbe a short, lowercase string, not containing spaces nor + should be a short, lowercase string, not containing spaces nor dashes. RO, Required diff --git a/Documentation/ABI/testing/sysfs-class-uwb_rc b/Documentation/ABI/testing/sysfs-class-uwb_rc deleted file mode 100644 index a7ea169dc4eb..000000000000 --- a/Documentation/ABI/testing/sysfs-class-uwb_rc +++ /dev/null @@ -1,156 +0,0 @@ -What: /sys/class/uwb_rc -Date: July 2008 -KernelVersion: 2.6.27 -Contact: linux-usb@vger.kernel.org -Description: - Interfaces for WiMedia Ultra Wideband Common Radio - Platform (UWB) radio controllers. - - Familiarity with the ECMA-368 'High Rate Ultra - Wideband MAC and PHY Specification' is assumed. - -What: /sys/class/uwb_rc/beacon_timeout_ms -Date: July 2008 -KernelVersion: 2.6.27 -Description: - If no beacons are received from a device for at least - this time, the device will be considered to have gone - and it will be removed. The default is 3 superframes - (~197 ms) as required by the specification. - -What: /sys/class/uwb_rc/uwb<N>/ -Date: July 2008 -KernelVersion: 2.6.27 -Contact: linux-usb@vger.kernel.org -Description: - An individual UWB radio controller. - -What: /sys/class/uwb_rc/uwb<N>/beacon -Date: July 2008 -KernelVersion: 2.6.27 -Contact: linux-usb@vger.kernel.org -Description: - Write: - - <channel> - - to force a specific channel to be used when beaconing, - or, if <channel> is -1, to prohibit beaconing. If - <channel> is 0, then the default channel selection - algorithm will be used. Valid channels depends on the - radio controller's supported band groups. - - Reading returns the currently active channel, or -1 if - the radio controller is not beaconing. - -What: /sys/class/uwb_rc/uwb<N>/ASIE -Date: August 2014 -KernelVersion: 3.18 -Contact: linux-usb@vger.kernel.org -Description: - - The application-specific information element (ASIE) - included in this device's beacon, in space separated - hex octets. - - Reading returns the current ASIE. Writing replaces - the current ASIE with the one written. - -What: /sys/class/uwb_rc/uwb<N>/scan -Date: July 2008 -KernelVersion: 2.6.27 -Contact: linux-usb@vger.kernel.org -Description: - Write: - - <channel> <type> [<bpst offset>] - - to start (or stop) scanning on a channel. <type> is one of: - - == ======================================= - 0 scan - 1 scan outside BP - 2 scan while inactive - 3 scanning disabled - 4 scan (with start time of <bpst offset>) - == ======================================= - -What: /sys/class/uwb_rc/uwb<N>/mac_address -Date: July 2008 -KernelVersion: 2.6.27 -Contact: linux-usb@vger.kernel.org -Description: - The EUI-48, in colon-separated hex octets, for this - radio controller. A write will change the radio - controller's EUI-48 but only do so while the device is - not beaconing or scanning. - -What: /sys/class/uwb_rc/uwb<N>/wusbhc -Date: July 2008 -KernelVersion: 2.6.27 -Contact: linux-usb@vger.kernel.org -Description: - A symlink to the device (if any) of the WUSB Host - Controller PAL using this radio controller. - -What: /sys/class/uwb_rc/uwb<N>/<EUI-48>/ -Date: July 2008 -KernelVersion: 2.6.27 -Contact: linux-usb@vger.kernel.org -Description: - A neighbour UWB device that has either been detected - as part of a scan or is a member of the radio - controllers beacon group. - -What: /sys/class/uwb_rc/uwb<N>/<EUI-48>/BPST -Date: July 2008 -KernelVersion: 2.6.27 -Contact: linux-usb@vger.kernel.org -Description: - The time (using the radio controllers internal 1 ms - interval superframe timer) of the last beacon from - this device was received. - -What: /sys/class/uwb_rc/uwb<N>/<EUI-48>/DevAddr -Date: July 2008 -KernelVersion: 2.6.27 -Contact: linux-usb@vger.kernel.org -Description: - The current DevAddr of this device in colon separated - hex octets. - -What: /sys/class/uwb_rc/uwb<N>/<EUI-48>/EUI_48 -Date: July 2008 -KernelVersion: 2.6.27 -Contact: linux-usb@vger.kernel.org -Description: - - The EUI-48 of this device in colon separated hex - octets. - -What: /sys/class/uwb_rc/uwb<N>/<EUI-48>/IEs -Date: July 2008 -KernelVersion: 2.6.27 -Contact: linux-usb@vger.kernel.org -Description: - The latest IEs included in this device's beacon, in - space separated hex octets with one IE per line. - -What: /sys/class/uwb_rc/uwb<N>/<EUI-48>/LQE -Date: July 2008 -KernelVersion: 2.6.27 -Contact: linux-usb@vger.kernel.org -Description: - Link Quality Estimate - the Signal to Noise Ratio - (SNR) of all packets received from this device in dB. - This gives an estimate on a suitable PHY rate. Refer - to [ECMA-368] section 13.3 for more details. - -What: /sys/class/uwb_rc/uwb<N>/<EUI-48>/RSSI -Date: July 2008 -KernelVersion: 2.6.27 -Contact: linux-usb@vger.kernel.org -Description: - Received Signal Strength Indication - the strength of - the received signal in dB. LQE is a more useful - measure of the radio link quality. diff --git a/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc b/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc deleted file mode 100644 index 55eb55cac92e..000000000000 --- a/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc +++ /dev/null @@ -1,57 +0,0 @@ -What: /sys/class/uwb_rc/uwb<N>/wusbhc/wusb_chid -Date: July 2008 -KernelVersion: 2.6.27 -Contact: David Vrabel <david.vrabel@csr.com> -Description: - Write the CHID (16 space-separated hex octets) for this host controller. - This starts the host controller, allowing it to accept connection from - WUSB devices. - - Set an all zero CHID to stop the host controller. - -What: /sys/class/uwb_rc/uwb<N>/wusbhc/wusb_trust_timeout -Date: July 2008 -KernelVersion: 2.6.27 -Contact: David Vrabel <david.vrabel@csr.com> -Description: - Devices that haven't sent a WUSB packet to the host - within 'wusb_trust_timeout' ms are considered to have - disconnected and are removed. The default value of - 4000 ms is the value required by the WUSB - specification. - - Since this relates to security (specifically, the - lifetime of PTKs and GTKs) it should not be changed - from the default. - -What: /sys/class/uwb_rc/uwb<N>/wusbhc/wusb_phy_rate -Date: August 2009 -KernelVersion: 2.6.32 -Contact: David Vrabel <david.vrabel@csr.com> -Description: - The maximum PHY rate to use for all connected devices. - This is only of limited use for testing and - development as the hardware's automatic rate - adaptation is better then this simple control. - - Refer to [ECMA-368] section 10.3.1.1 for the value to - use. - -What: /sys/class/uwb_rc/uwb<N>/wusbhc/wusb_dnts -Date: June 2013 -KernelVersion: 3.11 -Contact: Thomas Pugliese <thomas.pugliese@gmail.com> -Description: - The device notification time slot (DNTS) count and inverval in - milliseconds that the WUSB host should use. This controls how - often the devices will have the opportunity to send - notifications to the host. - -What: /sys/class/uwb_rc/uwb<N>/wusbhc/wusb_retry_count -Date: June 2013 -KernelVersion: 3.11 -Contact: Thomas Pugliese <thomas.pugliese@gmail.com> -Description: - The number of retries that the WUSB host should attempt - before reporting an error for a bus transaction. The range of - valid values is [0..15], where 0 indicates infinite retries. diff --git a/Documentation/ABI/testing/sysfs-devices-memory b/Documentation/ABI/testing/sysfs-devices-memory index d8b0f80b9e33..a95e0f17c35a 100644 --- a/Documentation/ABI/testing/sysfs-devices-memory +++ b/Documentation/ABI/testing/sysfs-devices-memory @@ -110,3 +110,11 @@ Description: link is created for memory section 9 on node0. /sys/devices/system/node/node0/memory9 -> ../../memory/memory9 + +What: /sys/devices/system/memory/crash_hotplug +Date: Aug 2023 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: + (RO) indicates whether or not the kernel directly supports + modifying the crash elfcorehdr for memory hot un/plug and/or + on/offline changes. diff --git a/Documentation/ABI/testing/sysfs-devices-online b/Documentation/ABI/testing/sysfs-devices-online index f990026c0740..c3359fec2980 100644 --- a/Documentation/ABI/testing/sysfs-devices-online +++ b/Documentation/ABI/testing/sysfs-devices-online @@ -17,4 +17,4 @@ Description: After a successful execution of the bus type's .offline() callback the device cannot be used for any purpose until either it is removed (i.e. device_del() is called for it), or its bus - type's .online() is exeucted successfully. + type's .online() is executed successfully. diff --git a/Documentation/ABI/testing/sysfs-devices-platform-kunpeng_hccs b/Documentation/ABI/testing/sysfs-devices-platform-kunpeng_hccs new file mode 100644 index 000000000000..fdb4e36310fb --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-platform-kunpeng_hccs @@ -0,0 +1,81 @@ +What: /sys/devices/platform/HISI04Bx:00/chipX/all_linked +What: /sys/devices/platform/HISI04Bx:00/chipX/linked_full_lane +What: /sys/devices/platform/HISI04Bx:00/chipX/crc_err_cnt +Date: November 2023 +KernelVersion: 6.6 +Contact: Huisong Li <lihuisong@huawei.org> +Description: + The /sys/devices/platform/HISI04Bx:00/chipX/ directory + contains read-only attributes exposing some summarization + information of all HCCS ports under a specified chip. + The X in 'chipX' indicates the Xth chip on platform. + + There are following attributes in this directory: + + ================= ==== ========================================= + all_linked: (RO) if all enabled ports on this chip are + linked (bool). + linked_full_lane: (RO) if all linked ports on this chip are full + lane (bool). + crc_err_cnt: (RO) total CRC err count for all ports on this + chip. + ================= ==== ========================================= + +What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/all_linked +What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/linked_full_lane +What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/crc_err_cnt +Date: November 2023 +KernelVersion: 6.6 +Contact: Huisong Li <lihuisong@huawei.org> +Description: + The /sys/devices/platform/HISI04Bx:00/chipX/dieY/ directory + contains read-only attributes exposing some summarization + information of all HCCS ports under a specified die. + The Y in 'dieY' indicates the hardware id of the die on chip who + has chip id X. + + There are following attributes in this directory: + + ================= ==== ========================================= + all_linked: (RO) if all enabled ports on this die are + linked (bool). + linked_full_lane: (RO) if all linked ports on this die are full + lane (bool). + crc_err_cnt: (RO) total CRC err count for all ports on this + die. + ================= ==== ========================================= + +What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/hccsN/type +What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/hccsN/lane_mode +What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/hccsN/enable +What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/hccsN/cur_lane_num +What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/hccsN/link_fsm +What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/hccsN/lane_mask +What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/hccsN/crc_err_cnt +Date: November 2023 +KernelVersion: 6.6 +Contact: Huisong Li <lihuisong@huawei.org> +Description: + The /sys/devices/platform/HISI04Bx/chipX/dieX/hccsN/ directory + contains read-only attributes exposing information about + a HCCS port. The N value in 'hccsN' indicates this port id. + The X in 'chipX' indicates the ID of the chip to which the + HCCS port belongs. For example, X ranges from to 'n - 1' if the + chip number on platform is n. + The Y in 'dieY' indicates the hardware id of the die to which + the hccs port belongs. + Note: type, lane_mode and enable are fixed attributes on running + platform. + + The HCCS port have the following attributes: + + ============= ==== ============================================= + type: (RO) port type (string), e.g. HCCS-v1 -> H32 + lane_mode: (RO) the lane mode of this port (string), e.g. x8 + enable: (RO) indicate if this port is enabled (bool). + cur_lane_num: (RO) current lane number of this port. + link_fsm: (RO) link finite state machine of this port. + lane_mask: (RO) current lane mask of this port, every bit + indicates a lane. + crc_err_cnt: (RO) CRC err count on this port. + ============= ==== ============================================= diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index ecd585ca2d50..a1db6db47505 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -354,9 +354,6 @@ Description: Parameters for the CPU cache attributes - ReadWriteAllocate: both writeallocate and readallocate - attributes: - LEGACY used only on IA64 and is same as write_policy - coherency_line_size: the minimum amount of data in bytes that gets transferred from memory to cache @@ -513,17 +510,18 @@ Description: information about CPUs heterogeneity. cpu_capacity: capacity of cpuX. What: /sys/devices/system/cpu/vulnerabilities + /sys/devices/system/cpu/vulnerabilities/gather_data_sampling + /sys/devices/system/cpu/vulnerabilities/itlb_multihit + /sys/devices/system/cpu/vulnerabilities/l1tf + /sys/devices/system/cpu/vulnerabilities/mds /sys/devices/system/cpu/vulnerabilities/meltdown + /sys/devices/system/cpu/vulnerabilities/mmio_stale_data + /sys/devices/system/cpu/vulnerabilities/retbleed + /sys/devices/system/cpu/vulnerabilities/spec_store_bypass /sys/devices/system/cpu/vulnerabilities/spectre_v1 /sys/devices/system/cpu/vulnerabilities/spectre_v2 - /sys/devices/system/cpu/vulnerabilities/spec_store_bypass - /sys/devices/system/cpu/vulnerabilities/l1tf - /sys/devices/system/cpu/vulnerabilities/mds /sys/devices/system/cpu/vulnerabilities/srbds /sys/devices/system/cpu/vulnerabilities/tsx_async_abort - /sys/devices/system/cpu/vulnerabilities/itlb_multihit - /sys/devices/system/cpu/vulnerabilities/mmio_stale_data - /sys/devices/system/cpu/vulnerabilities/retbleed Date: January 2018 Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> Description: Information about CPU vulnerabilities @@ -555,6 +553,7 @@ Description: Control Symmetric Multi Threading (SMT) ================ ========================================= "on" SMT is enabled "off" SMT is disabled + "<N>" SMT is enabled with N threads per core. "forceoff" SMT is force disabled. Cannot be changed. "notsupported" SMT is not supported by the CPU "notimplemented" SMT runtime toggling is not @@ -686,3 +685,11 @@ Description: (RO) the list of CPUs that are isolated and don't participate in load balancing. These CPUs are set by boot parameter "isolcpus=". + +What: /sys/devices/system/cpu/crash_hotplug +Date: Aug 2023 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: + (RO) indicates whether or not the kernel directly supports + modifying the crash elfcorehdr for CPU hot un/plug and/or + on/offline changes. diff --git a/Documentation/ABI/testing/sysfs-driver-ccp b/Documentation/ABI/testing/sysfs-driver-ccp index 7aded9b75553..ee6b787eee7a 100644 --- a/Documentation/ABI/testing/sysfs-driver-ccp +++ b/Documentation/ABI/testing/sysfs-driver-ccp @@ -85,3 +85,21 @@ Description: Possible values: 0: Not enforced 1: Enforced + +What: /sys/bus/pci/devices/<BDF>/bootloader_version +Date: June 2023 +KernelVersion: 6.4 +Contact: mario.limonciello@amd.com +Description: + The /sys/bus/pci/devices/<BDF>/bootloader_version + file reports the firmware version of the AMD AGESA + bootloader. + +What: /sys/bus/pci/devices/<BDF>/tee_version +Date: June 2023 +KernelVersion: 6.4 +Contact: mario.limonciello@amd.com +Description: + The /sys/bus/pci/devices/<BDF>/tee_version + file reports the firmware version of the AMD Trusted + Execution Environment (TEE). diff --git a/Documentation/ABI/testing/sysfs-driver-chromeos-acpi b/Documentation/ABI/testing/sysfs-driver-chromeos-acpi index c308926e1568..d46b1c85840d 100644 --- a/Documentation/ABI/testing/sysfs-driver-chromeos-acpi +++ b/Documentation/ABI/testing/sysfs-driver-chromeos-acpi @@ -1,4 +1,5 @@ What: /sys/bus/platform/devices/GGL0001:*/BINF.2 + /sys/bus/platform/devices/GOOG0016:*/BINF.2 Date: May 2022 KernelVersion: 5.19 Description: @@ -10,6 +11,7 @@ Description: == =============================== What: /sys/bus/platform/devices/GGL0001:*/BINF.3 + /sys/bus/platform/devices/GOOG0016:*/BINF.3 Date: May 2022 KernelVersion: 5.19 Description: @@ -23,6 +25,7 @@ Description: == ===================================== What: /sys/bus/platform/devices/GGL0001:*/CHSW + /sys/bus/platform/devices/GOOG0016:*/CHSW Date: May 2022 KernelVersion: 5.19 Description: @@ -38,6 +41,7 @@ Description: ==== =========================================== What: /sys/bus/platform/devices/GGL0001:*/FMAP + /sys/bus/platform/devices/GOOG0016:*/FMAP Date: May 2022 KernelVersion: 5.19 Description: @@ -45,6 +49,7 @@ Description: processor firmware flashmap. What: /sys/bus/platform/devices/GGL0001:*/FRID + /sys/bus/platform/devices/GOOG0016:*/FRID Date: May 2022 KernelVersion: 5.19 Description: @@ -52,6 +57,7 @@ Description: main processor firmware. What: /sys/bus/platform/devices/GGL0001:*/FWID + /sys/bus/platform/devices/GOOG0016:*/FWID Date: May 2022 KernelVersion: 5.19 Description: @@ -59,6 +65,7 @@ Description: main processor firmware. What: /sys/bus/platform/devices/GGL0001:*/GPIO.X/GPIO.0 + /sys/bus/platform/devices/GOOG0016:*/GPIO.X/GPIO.0 Date: May 2022 KernelVersion: 5.19 Description: @@ -73,6 +80,7 @@ Description: =========== ================================== What: /sys/bus/platform/devices/GGL0001:*/GPIO.X/GPIO.1 + /sys/bus/platform/devices/GOOG0016:*/GPIO.X/GPIO.1 Date: May 2022 KernelVersion: 5.19 Description: @@ -84,6 +92,7 @@ Description: == ======================= What: /sys/bus/platform/devices/GGL0001:*/GPIO.X/GPIO.2 + /sys/bus/platform/devices/GOOG0016:*/GPIO.X/GPIO.2 Date: May 2022 KernelVersion: 5.19 Description: @@ -91,18 +100,21 @@ Description: controller. What: /sys/bus/platform/devices/GGL0001:*/GPIO.X/GPIO.3 + /sys/bus/platform/devices/GOOG0016:*/GPIO.X/GPIO.3 Date: May 2022 KernelVersion: 5.19 Description: Returns name of the GPIO controller. What: /sys/bus/platform/devices/GGL0001:*/HWID + /sys/bus/platform/devices/GOOG0016:*/HWID Date: May 2022 KernelVersion: 5.19 Description: Returns hardware ID for the Chromebook. What: /sys/bus/platform/devices/GGL0001:*/MECK + /sys/bus/platform/devices/GOOG0016:*/MECK Date: May 2022 KernelVersion: 5.19 Description: @@ -113,6 +125,7 @@ Description: present, or if the firmware was unable to read the extended registers, this buffer size can be zero. What: /sys/bus/platform/devices/GGL0001:*/VBNV.0 + /sys/bus/platform/devices/GOOG0016:*/VBNV.0 Date: May 2022 KernelVersion: 5.19 Description: @@ -122,6 +135,7 @@ Description: clock data). What: /sys/bus/platform/devices/GGL0001:*/VBNV.1 + /sys/bus/platform/devices/GOOG0016:*/VBNV.1 Date: May 2022 KernelVersion: 5.19 Description: @@ -129,9 +143,10 @@ Description: storage block. What: /sys/bus/platform/devices/GGL0001:*/VDAT + /sys/bus/platform/devices/GOOG0016:*/VDAT Date: May 2022 KernelVersion: 5.19 Description: Returns the verified boot data block shared between the firmware verification step and the kernel verification step - (binary). + (hex dump). diff --git a/Documentation/ABI/testing/sysfs-driver-ge-achc b/Documentation/ABI/testing/sysfs-driver-ge-achc index a9e7a079190c..c3e77def4b20 100644 --- a/Documentation/ABI/testing/sysfs-driver-ge-achc +++ b/Documentation/ABI/testing/sysfs-driver-ge-achc @@ -5,7 +5,7 @@ Description: Write 1 to this file to update the ACHC microcontroller firmware via the EzPort interface. For this the kernel will load "achc.bin" via the firmware API (so usually from /lib/firmware). The write will block until the FW - has either been flashed successfully or an error occured. + has either been flashed successfully or an error occurred. What: /sys/bus/spi/<dev>/reset Date: Jul 2021 diff --git a/Documentation/ABI/testing/sysfs-driver-habanalabs b/Documentation/ABI/testing/sysfs-driver-habanalabs index 1b98b6503b23..c63ca1ad500d 100644 --- a/Documentation/ABI/testing/sysfs-driver-habanalabs +++ b/Documentation/ABI/testing/sysfs-driver-habanalabs @@ -1,4 +1,4 @@ -What: /sys/class/habanalabs/hl<n>/armcp_kernel_ver +What: /sys/class/accel/accel<n>/device/armcp_kernel_ver Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -6,7 +6,7 @@ Description: Version of the Linux kernel running on the device's CPU. Will be DEPRECATED in Linux kernel version 5.10, and be replaced with cpucp_kernel_ver -What: /sys/class/habanalabs/hl<n>/armcp_ver +What: /sys/class/accel/accel<n>/device/armcp_ver Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -14,7 +14,7 @@ Description: Version of the application running on the device's CPU Will be DEPRECATED in Linux kernel version 5.10, and be replaced with cpucp_ver -What: /sys/class/habanalabs/hl<n>/clk_max_freq_mhz +What: /sys/class/accel/accel<n>/device/clk_max_freq_mhz Date: Jun 2019 KernelVersion: 5.7 Contact: ogabbay@kernel.org @@ -24,58 +24,58 @@ Description: Allows the user to set the maximum clock frequency, in MHz. frequency value of the device clock. This property is valid only for the Gaudi ASIC family -What: /sys/class/habanalabs/hl<n>/clk_cur_freq_mhz +What: /sys/class/accel/accel<n>/device/clk_cur_freq_mhz Date: Jun 2019 KernelVersion: 5.7 Contact: ogabbay@kernel.org Description: Displays the current frequency, in MHz, of the device clock. This property is valid only for the Gaudi ASIC family -What: /sys/class/habanalabs/hl<n>/cpld_ver +What: /sys/class/accel/accel<n>/device/cpld_ver Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Version of the Device's CPLD F/W -What: /sys/class/habanalabs/hl<n>/cpucp_kernel_ver +What: /sys/class/accel/accel<n>/device/cpucp_kernel_ver Date: Oct 2020 KernelVersion: 5.10 Contact: ogabbay@kernel.org Description: Version of the Linux kernel running on the device's CPU -What: /sys/class/habanalabs/hl<n>/cpucp_ver +What: /sys/class/accel/accel<n>/device/cpucp_ver Date: Oct 2020 KernelVersion: 5.10 Contact: ogabbay@kernel.org Description: Version of the application running on the device's CPU -What: /sys/class/habanalabs/hl<n>/device_type +What: /sys/class/accel/accel<n>/device/device_type Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Displays the code name of the device according to its type. The supported values are: "GOYA" -What: /sys/class/habanalabs/hl<n>/eeprom +What: /sys/class/accel/accel<n>/device/eeprom Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: A binary file attribute that contains the contents of the on-board EEPROM -What: /sys/class/habanalabs/hl<n>/fuse_ver +What: /sys/class/accel/accel<n>/device/fuse_ver Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Displays the device's version from the eFuse -What: /sys/class/habanalabs/hl<n>/fw_os_ver +What: /sys/class/accel/accel<n>/device/fw_os_ver Date: Dec 2021 KernelVersion: 5.18 Contact: ogabbay@kernel.org Description: Version of the firmware OS running on the device's CPU -What: /sys/class/habanalabs/hl<n>/hard_reset +What: /sys/class/accel/accel<n>/device/hard_reset Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -83,14 +83,14 @@ Description: Interface to trigger a hard-reset operation for the device. Hard-reset will reset ALL internal components of the device except for the PCI interface and the internal PLLs -What: /sys/class/habanalabs/hl<n>/hard_reset_cnt +What: /sys/class/accel/accel<n>/device/hard_reset_cnt Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Displays how many times the device have undergone a hard-reset operation since the driver was loaded -What: /sys/class/habanalabs/hl<n>/high_pll +What: /sys/class/accel/accel<n>/device/high_pll Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -98,7 +98,7 @@ Description: Allows the user to set the maximum clock frequency for MME, TPC and IC when the power management profile is set to "automatic". This property is valid only for the Goya ASIC family -What: /sys/class/habanalabs/hl<n>/ic_clk +What: /sys/class/accel/accel<n>/device/ic_clk Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -110,27 +110,27 @@ Description: Allows the user to set the maximum clock frequency, in Hz, of frequency value of the IC. This property is valid only for the Goya ASIC family -What: /sys/class/habanalabs/hl<n>/ic_clk_curr +What: /sys/class/accel/accel<n>/device/ic_clk_curr Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Displays the current clock frequency, in Hz, of the Interconnect fabric. This property is valid only for the Goya ASIC family -What: /sys/class/habanalabs/hl<n>/infineon_ver +What: /sys/class/accel/accel<n>/device/infineon_ver Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Version of the Device's power supply F/W code. Relevant only to GOYA and GAUDI -What: /sys/class/habanalabs/hl<n>/max_power +What: /sys/class/accel/accel<n>/device/max_power Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Allows the user to set the maximum power consumption of the device in milliwatts. -What: /sys/class/habanalabs/hl<n>/mme_clk +What: /sys/class/accel/accel<n>/device/mme_clk Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -142,21 +142,21 @@ Description: Allows the user to set the maximum clock frequency, in Hz, of frequency value of the MME. This property is valid only for the Goya ASIC family -What: /sys/class/habanalabs/hl<n>/mme_clk_curr +What: /sys/class/accel/accel<n>/device/mme_clk_curr Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Displays the current clock frequency, in Hz, of the MME compute engine. This property is valid only for the Goya ASIC family -What: /sys/class/habanalabs/hl<n>/pci_addr +What: /sys/class/accel/accel<n>/device/pci_addr Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Displays the PCI address of the device. This is needed so the user would be able to open a device based on its PCI address -What: /sys/class/habanalabs/hl<n>/pm_mng_profile +What: /sys/class/accel/accel<n>/device/pm_mng_profile Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -170,19 +170,19 @@ Description: Power management profile. Values are "auto", "manual". In "auto" ic_clk, mme_clk and tpc_clk. This property is valid only for the Goya ASIC family -What: /sys/class/habanalabs/hl<n>/preboot_btl_ver +What: /sys/class/accel/accel<n>/device/preboot_btl_ver Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Version of the device's preboot F/W code -What: /sys/class/habanalabs/hl<n>/security_enabled +What: /sys/class/accel/accel<n>/device/security_enabled Date: Oct 2022 KernelVersion: 6.1 Contact: obitton@habana.ai Description: Displays the device's security status -What: /sys/class/habanalabs/hl<n>/soft_reset +What: /sys/class/accel/accel<n>/device/soft_reset Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -190,14 +190,14 @@ Description: Interface to trigger a soft-reset operation for the device. Soft-reset will reset only the compute and DMA engines of the device -What: /sys/class/habanalabs/hl<n>/soft_reset_cnt +What: /sys/class/accel/accel<n>/device/soft_reset_cnt Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Displays how many times the device have undergone a soft-reset operation since the driver was loaded -What: /sys/class/habanalabs/hl<n>/status +What: /sys/class/accel/accel<n>/device/status Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -215,13 +215,13 @@ Description: Status of the card: a compute-reset which is executed after a device release (relevant for Gaudi2 only). -What: /sys/class/habanalabs/hl<n>/thermal_ver +What: /sys/class/accel/accel<n>/device/thermal_ver Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Version of the Device's thermal daemon -What: /sys/class/habanalabs/hl<n>/tpc_clk +What: /sys/class/accel/accel<n>/device/tpc_clk Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org @@ -233,20 +233,20 @@ Description: Allows the user to set the maximum clock frequency, in Hz, of frequency value of the TPC. This property is valid only for Goya ASIC family -What: /sys/class/habanalabs/hl<n>/tpc_clk_curr +What: /sys/class/accel/accel<n>/device/tpc_clk_curr Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Displays the current clock frequency, in Hz, of the TPC compute engines. This property is valid only for the Goya ASIC family -What: /sys/class/habanalabs/hl<n>/uboot_ver +What: /sys/class/accel/accel<n>/device/uboot_ver Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Version of the u-boot running on the device's CPU -What: /sys/class/habanalabs/hl<n>/vrm_ver +What: /sys/class/accel/accel<n>/device/vrm_ver Date: Jan 2022 KernelVersion: 5.17 Contact: ogabbay@kernel.org diff --git a/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc b/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc index a8ab58035c95..c12316dfd973 100644 --- a/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc +++ b/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc @@ -17,7 +17,7 @@ Description: Read only. Returns the firmware version of Intel MAX10 What: /sys/bus/.../drivers/intel-m10-bmc/.../mac_address Date: January 2021 KernelVersion: 5.12 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns the first MAC address in a block of sequential MAC addresses assigned to the board that is managed by the Intel MAX10 BMC. It is stored in @@ -28,7 +28,7 @@ Description: Read only. Returns the first MAC address in a block What: /sys/bus/.../drivers/intel-m10-bmc/.../mac_count Date: January 2021 KernelVersion: 5.12 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns the number of sequential MAC addresses assigned to the board managed by the Intel MAX10 BMC. This value is stored in FLASH and is mirrored diff --git a/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc-sec-update b/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc-sec-update index 0a41afe0ab4c..9051695d2211 100644 --- a/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc-sec-update +++ b/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc-sec-update @@ -1,7 +1,7 @@ What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/sr_root_entry_hash Date: Sep 2022 KernelVersion: 5.20 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns the root entry hash for the static region if one is programmed, else it returns the string: "hash not programmed". This file is only @@ -11,7 +11,7 @@ Description: Read only. Returns the root entry hash for the static What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/pr_root_entry_hash Date: Sep 2022 KernelVersion: 5.20 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns the root entry hash for the partial reconfiguration region if one is programmed, else it returns the string: "hash not programmed". This file @@ -21,7 +21,7 @@ Description: Read only. Returns the root entry hash for the partial What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/bmc_root_entry_hash Date: Sep 2022 KernelVersion: 5.20 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns the root entry hash for the BMC image if one is programmed, else it returns the string: "hash not programmed". This file is only visible if the @@ -31,7 +31,7 @@ Description: Read only. Returns the root entry hash for the BMC image What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/sr_canceled_csks Date: Sep 2022 KernelVersion: 5.20 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns a list of indices for canceled code signing keys for the static region. The standard bitmap list format is used (e.g. "1,2-6,9"). @@ -39,7 +39,7 @@ Description: Read only. Returns a list of indices for canceled code What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/pr_canceled_csks Date: Sep 2022 KernelVersion: 5.20 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns a list of indices for canceled code signing keys for the partial reconfiguration region. The standard bitmap list format is used (e.g. "1,2-6,9"). @@ -47,7 +47,7 @@ Description: Read only. Returns a list of indices for canceled code What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/bmc_canceled_csks Date: Sep 2022 KernelVersion: 5.20 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns a list of indices for canceled code signing keys for the BMC. The standard bitmap list format is used (e.g. "1,2-6,9"). @@ -55,7 +55,7 @@ Description: Read only. Returns a list of indices for canceled code What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/flash_count Date: Sep 2022 KernelVersion: 5.20 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns number of times the secure update staging area has been flashed. Format: "%u". diff --git a/Documentation/ABI/testing/sysfs-driver-qat b/Documentation/ABI/testing/sysfs-driver-qat index ef6d6c57105e..bbf329cf0d67 100644 --- a/Documentation/ABI/testing/sysfs-driver-qat +++ b/Documentation/ABI/testing/sysfs-driver-qat @@ -29,6 +29,8 @@ Description: (RW) Reports the current configuration of the QAT device. services * asym;sym: identical to sym;asym * dc: the device is configured for running compression services + * dcc: identical to dc but enables the dc chaining feature, + hash then compression. If this is not required chose dc * sym: the device is configured for running symmetric crypto services * asym: the device is configured for running asymmetric crypto @@ -93,3 +95,49 @@ Description: (RW) This configuration option provides a way to force the device i 0 This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat/rp2srv +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (RW) This attribute provides a way for a user to query a + specific ring pair for the type of service that it is currently + configured for. + + When written to, the value is cached and used to perform the + read operation. Allowed values are in the range 0 to N-1, where + N is the max number of ring pairs supported by a device. This + can be queried using the attribute qat/num_rps. + + A read returns the service associated to the ring pair queried. + + The values are: + + * dc: the ring pair is configured for running compression services + * sym: the ring pair is configured for running symmetric crypto + services + * asym: the ring pair is configured for running asymmetric crypto + services + + Example usage:: + + # echo 1 > /sys/bus/pci/devices/<BDF>/qat/rp2srv + # cat /sys/bus/pci/devices/<BDF>/qat/rp2srv + sym + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat/num_rps +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (RO) Returns the number of ring pairs that a single device has. + + Example usage:: + + # cat /sys/bus/pci/devices/<BDF>/qat/num_rps + 64 + + This attribute is only available for qat_4xxx devices. diff --git a/Documentation/ABI/testing/sysfs-driver-qat_ras b/Documentation/ABI/testing/sysfs-driver-qat_ras new file mode 100644 index 000000000000..176dea1e9c0a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-qat_ras @@ -0,0 +1,41 @@ +What: /sys/bus/pci/devices/<BDF>/qat_ras/errors_correctable +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: (RO) Reports the number of correctable errors detected by the device. + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_ras/errors_nonfatal +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: (RO) Reports the number of non fatal errors detected by the device. + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_ras/errors_fatal +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: (RO) Reports the number of fatal errors detected by the device. + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_ras/reset_error_counters +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: (WO) Write to resets all error counters of a device. + + The following example reports how to reset the counters:: + + # echo 1 > /sys/bus/pci/devices/<BDF>/qat_ras/reset_error_counters + # cat /sys/bus/pci/devices/<BDF>/qat_ras/errors_correctable + 0 + # cat /sys/bus/pci/devices/<BDF>/qat_ras/errors_nonfatal + 0 + # cat /sys/bus/pci/devices/<BDF>/qat_ras/errors_fatal + 0 + + This attribute is only available for qat_4xxx devices. diff --git a/Documentation/ABI/testing/sysfs-driver-qat_rl b/Documentation/ABI/testing/sysfs-driver-qat_rl new file mode 100644 index 000000000000..8c282ae3155d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-qat_rl @@ -0,0 +1,226 @@ +What: /sys/bus/pci/devices/<BDF>/qat_rl/sla_op +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (WO) This attribute is used to perform an operation on an SLA. + The supported operations are: add, update, rm, rm_all, and get. + + Input values must be filled through the associated attribute in + this group before a write to this file. + If the operation completes successfully, the associated + attributes will be updated. + The associated attributes are: cir, pir, srv, rp, and id. + + Supported operations: + + * add: Creates a new SLA with the provided inputs from user. + * Inputs: cir, pir, srv, and rp + * Output: id + + * get: Returns the configuration of the specified SLA in id attribute + * Inputs: id + * Outputs: cir, pir, srv, and rp + + * update: Updates the SLA with new values set in the following attributes + * Inputs: id, cir, and pir + + * rm: Removes the specified SLA in the id attribute. + * Inputs: id + + * rm_all: Removes all the configured SLAs. + * Inputs: None + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_rl/rp +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (RW) When read, reports the current assigned ring pairs for the + queried SLA. + When wrote to, configures the ring pairs associated to a new SLA. + + The value is a 64-bit bit mask and is written/displayed in hex. + Each bit of this mask represents a single ring pair i.e., + bit 1 == ring pair id 0; bit 3 == ring pair id 2. + + Selected ring pairs must to be assigned to a single service, + i.e. the one provided with the srv attribute. The service + assigned to a certain ring pair can be checked by querying + the attribute qat/rp2srv. + + The maximum number of ring pairs is 4 per SLA. + + Applicability in sla_op: + + * WRITE: add operation + * READ: get operation + + Example usage:: + + ## Read + # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id + # cat /sys/bus/pci/devices/<BDF>/qat_rl/rp + 0x5 + + ## Write + # echo 0x5 > /sys/bus/pci/devices/<BDF>/qat_rl/rp + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_rl/id +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (RW) If written to, the value is used to retrieve a particular + SLA and operate on it. + This is valid only for the following operations: update, rm, + and get. + A read of this attribute is only guaranteed to have correct data + after creation of an SLA. + + Applicability in sla_op: + + * WRITE: rm and update operations + * READ: add and get operations + + Example usage:: + + ## Read + ## Set attributes e.g. cir, pir, srv, etc + # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + # cat /sys/bus/pci/devices/<BDF>/qat_rl/id + 4 + + ## Write + # echo 7 > /sys/bus/pci/devices/<BDF>/qat_rl/id + # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + # cat /sys/bus/pci/devices/<BDF>/qat_rl/rp + 0x5 ## ring pair ID 0 and ring pair ID 2 + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_rl/cir +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (RW) Committed information rate (CIR). Rate guaranteed to be + achieved by a particular SLA. The value is expressed in + permille scale, i.e. 1000 refers to the maximum device + throughput for a selected service. + + After sending a "get" to sla_op, this will be populated with the + CIR for that queried SLA. + Write to this file before sending an "add/update" sla_op, to set + the SLA to the specified value. + + Applicability in sla_op: + + * WRITE: add and update operations + * READ: get operation + + Example usage:: + + ## Write + # echo 500 > /sys/bus/pci/devices/<BDF>/qat_rl/cir + # echo "add" /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + + ## Read + # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id + # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + # cat /sys/bus/pci/devices/<BDF>/qat_rl/cir + 500 + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_rl/pir +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (RW) Peak information rate (PIR). The maximum rate that can be + achieved by that particular SLA. An SLA can reach a value + between CIR and PIR when the device is not fully utilized by + requests from other users (assigned to different SLAs). + + After sending a "get" to sla_op, this will be populated with the + PIR for that queried SLA. + Write to this file before sending an "add/update" sla_op, to set + the SLA to the specified value. + + Applicability in sla_op: + + * WRITE: add and update operations + * READ: get operation + + Example usage:: + + ## Write + # echo 750 > /sys/bus/pci/devices/<BDF>/qat_rl/pir + # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + + ## Read + # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id + # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + # cat /sys/bus/pci/devices/<BDF>/qat_rl/pir + 750 + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_rl/srv +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (RW) Service (SRV). Represents the service (sym, asym, dc) + associated to an SLA. + Can be written to or queried to set/show the SRV type for an SLA. + The SRV attribute is used to specify the SRV type before adding + an SLA. After an SLA is configured, reports the service + associated to that SLA. + + Applicability in sla_op: + + * WRITE: add and update operations + * READ: get operation + + Example usage:: + + ## Write + # echo "dc" > /sys/bus/pci/devices/<BDF>/qat_rl/srv + # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + # cat /sys/bus/pci/devices/<BDF>/qat_rl/id + 4 + + ## Read + # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id + # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + # cat /sys/bus/pci/devices/<BDF>/qat_rl/srv + dc + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (RW) This file will return the remaining capability for a + particular service/sla. This is the remaining value that a new + SLA can be set to or a current SLA can be increased with. + + Example usage:: + + # echo "asym" > /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem + # cat /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem + 250 + # echo 250 > /sys/bus/pci/devices/<BDF>/qat_rl/cir + # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + # cat /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem + 0 + + This attribute is only available for qat_4xxx devices. diff --git a/Documentation/ABI/testing/sysfs-driver-tegra-fuse b/Documentation/ABI/testing/sysfs-driver-tegra-fuse index 69f5af632657..b8936fad2ccf 100644 --- a/Documentation/ABI/testing/sysfs-driver-tegra-fuse +++ b/Documentation/ABI/testing/sysfs-driver-tegra-fuse @@ -3,7 +3,7 @@ Date: February 2014 Contact: Peter De Schrijver <pdeschrijver@nvidia.com> Description: read-only access to the efuses on Tegra20, Tegra30, Tegra114 and Tegra124 SoC's from NVIDIA. The efuses contain write once - data programmed at the factory. The data is layed out in 32bit + data programmed at the factory. The data is laid out in 32bit words in LSB first format. Each bit represents a single value as decoded from the fuse registers. Bits order/assignment exactly matches the HW registers, including any unused bits. diff --git a/Documentation/ABI/testing/sysfs-driver-ufs b/Documentation/ABI/testing/sysfs-driver-ufs index d5f44fc5b9dc..0c7efaf62de0 100644 --- a/Documentation/ABI/testing/sysfs-driver-ufs +++ b/Documentation/ABI/testing/sysfs-driver-ufs @@ -994,7 +994,7 @@ Description: This file shows the amount of physical memory needed What: /sys/bus/platform/drivers/ufshcd/*/rpm_lvl What: /sys/bus/platform/devices/*.ufs/rpm_lvl Date: September 2014 -Contact: Subhash Jadavani <subhashj@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This entry could be used to set or show the UFS device runtime power management level. The current driver implementation supports 7 levels with next target states: @@ -1021,7 +1021,7 @@ Description: This entry could be used to set or show the UFS device What: /sys/bus/platform/drivers/ufshcd/*/rpm_target_dev_state What: /sys/bus/platform/devices/*.ufs/rpm_target_dev_state Date: February 2018 -Contact: Subhash Jadavani <subhashj@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This entry shows the target power mode of an UFS device for the chosen runtime power management level. @@ -1030,7 +1030,7 @@ Description: This entry shows the target power mode of an UFS device What: /sys/bus/platform/drivers/ufshcd/*/rpm_target_link_state What: /sys/bus/platform/devices/*.ufs/rpm_target_link_state Date: February 2018 -Contact: Subhash Jadavani <subhashj@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This entry shows the target state of an UFS UIC link for the chosen runtime power management level. @@ -1039,7 +1039,7 @@ Description: This entry shows the target state of an UFS UIC link What: /sys/bus/platform/drivers/ufshcd/*/spm_lvl What: /sys/bus/platform/devices/*.ufs/spm_lvl Date: September 2014 -Contact: Subhash Jadavani <subhashj@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This entry could be used to set or show the UFS device system power management level. The current driver implementation supports 7 levels with next target states: @@ -1066,7 +1066,7 @@ Description: This entry could be used to set or show the UFS device What: /sys/bus/platform/drivers/ufshcd/*/spm_target_dev_state What: /sys/bus/platform/devices/*.ufs/spm_target_dev_state Date: February 2018 -Contact: Subhash Jadavani <subhashj@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This entry shows the target power mode of an UFS device for the chosen system power management level. @@ -1075,7 +1075,7 @@ Description: This entry shows the target power mode of an UFS device What: /sys/bus/platform/drivers/ufshcd/*/spm_target_link_state What: /sys/bus/platform/devices/*.ufs/spm_target_link_state Date: February 2018 -Contact: Subhash Jadavani <subhashj@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This entry shows the target state of an UFS UIC link for the chosen system power management level. @@ -1084,7 +1084,7 @@ Description: This entry shows the target state of an UFS UIC link What: /sys/bus/platform/drivers/ufshcd/*/monitor/monitor_enable What: /sys/bus/platform/devices/*.ufs/monitor/monitor_enable Date: January 2021 -Contact: Can Guo <cang@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This file shows the status of performance monitor enablement and it can be used to start/stop the monitor. When the monitor is stopped, the performance data collected is also cleared. @@ -1092,7 +1092,7 @@ Description: This file shows the status of performance monitor enablement What: /sys/bus/platform/drivers/ufshcd/*/monitor/monitor_chunk_size What: /sys/bus/platform/devices/*.ufs/monitor/monitor_chunk_size Date: January 2021 -Contact: Can Guo <cang@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This file tells the monitor to focus on requests transferring data of specific chunk size (in Bytes). 0 means any chunk size. It can only be changed when monitor is disabled. @@ -1100,7 +1100,7 @@ Description: This file tells the monitor to focus on requests transferring What: /sys/bus/platform/drivers/ufshcd/*/monitor/read_total_sectors What: /sys/bus/platform/devices/*.ufs/monitor/read_total_sectors Date: January 2021 -Contact: Can Guo <cang@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This file shows how many sectors (in 512 Bytes) have been sent from device to host after monitor gets started. @@ -1109,7 +1109,7 @@ Description: This file shows how many sectors (in 512 Bytes) have been What: /sys/bus/platform/drivers/ufshcd/*/monitor/read_total_busy What: /sys/bus/platform/devices/*.ufs/monitor/read_total_busy Date: January 2021 -Contact: Can Guo <cang@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This file shows how long (in micro seconds) has been spent sending data from device to host after monitor gets started. @@ -1118,7 +1118,7 @@ Description: This file shows how long (in micro seconds) has been spent What: /sys/bus/platform/drivers/ufshcd/*/monitor/read_nr_requests What: /sys/bus/platform/devices/*.ufs/monitor/read_nr_requests Date: January 2021 -Contact: Can Guo <cang@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This file shows how many read requests have been sent after monitor gets started. @@ -1127,7 +1127,7 @@ Description: This file shows how many read requests have been sent after What: /sys/bus/platform/drivers/ufshcd/*/monitor/read_req_latency_max What: /sys/bus/platform/devices/*.ufs/monitor/read_req_latency_max Date: January 2021 -Contact: Can Guo <cang@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This file shows the maximum latency (in micro seconds) of read requests after monitor gets started. @@ -1136,7 +1136,7 @@ Description: This file shows the maximum latency (in micro seconds) of What: /sys/bus/platform/drivers/ufshcd/*/monitor/read_req_latency_min What: /sys/bus/platform/devices/*.ufs/monitor/read_req_latency_min Date: January 2021 -Contact: Can Guo <cang@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This file shows the minimum latency (in micro seconds) of read requests after monitor gets started. @@ -1145,7 +1145,7 @@ Description: This file shows the minimum latency (in micro seconds) of What: /sys/bus/platform/drivers/ufshcd/*/monitor/read_req_latency_avg What: /sys/bus/platform/devices/*.ufs/monitor/read_req_latency_avg Date: January 2021 -Contact: Can Guo <cang@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This file shows the average latency (in micro seconds) of read requests after monitor gets started. @@ -1154,7 +1154,7 @@ Description: This file shows the average latency (in micro seconds) of What: /sys/bus/platform/drivers/ufshcd/*/monitor/read_req_latency_sum What: /sys/bus/platform/devices/*.ufs/monitor/read_req_latency_sum Date: January 2021 -Contact: Can Guo <cang@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This file shows the total latency (in micro seconds) of read requests sent after monitor gets started. @@ -1163,7 +1163,7 @@ Description: This file shows the total latency (in micro seconds) of What: /sys/bus/platform/drivers/ufshcd/*/monitor/write_total_sectors What: /sys/bus/platform/devices/*.ufs/monitor/write_total_sectors Date: January 2021 -Contact: Can Guo <cang@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This file shows how many sectors (in 512 Bytes) have been sent from host to device after monitor gets started. @@ -1172,7 +1172,7 @@ Description: This file shows how many sectors (in 512 Bytes) have been sent What: /sys/bus/platform/drivers/ufshcd/*/monitor/write_total_busy What: /sys/bus/platform/devices/*.ufs/monitor/write_total_busy Date: January 2021 -Contact: Can Guo <cang@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This file shows how long (in micro seconds) has been spent sending data from host to device after monitor gets started. @@ -1181,7 +1181,7 @@ Description: This file shows how long (in micro seconds) has been spent What: /sys/bus/platform/drivers/ufshcd/*/monitor/write_nr_requests What: /sys/bus/platform/devices/*.ufs/monitor/write_nr_requests Date: January 2021 -Contact: Can Guo <cang@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This file shows how many write requests have been sent after monitor gets started. @@ -1190,7 +1190,7 @@ Description: This file shows how many write requests have been sent after What: /sys/bus/platform/drivers/ufshcd/*/monitor/write_req_latency_max What: /sys/bus/platform/devices/*.ufs/monitor/write_req_latency_max Date: January 2021 -Contact: Can Guo <cang@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This file shows the maximum latency (in micro seconds) of write requests after monitor gets started. @@ -1199,7 +1199,7 @@ Description: This file shows the maximum latency (in micro seconds) of write What: /sys/bus/platform/drivers/ufshcd/*/monitor/write_req_latency_min What: /sys/bus/platform/devices/*.ufs/monitor/write_req_latency_min Date: January 2021 -Contact: Can Guo <cang@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This file shows the minimum latency (in micro seconds) of write requests after monitor gets started. @@ -1208,7 +1208,7 @@ Description: This file shows the minimum latency (in micro seconds) of write What: /sys/bus/platform/drivers/ufshcd/*/monitor/write_req_latency_avg What: /sys/bus/platform/devices/*.ufs/monitor/write_req_latency_avg Date: January 2021 -Contact: Can Guo <cang@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This file shows the average latency (in micro seconds) of write requests after monitor gets started. @@ -1217,7 +1217,7 @@ Description: This file shows the average latency (in micro seconds) of write What: /sys/bus/platform/drivers/ufshcd/*/monitor/write_req_latency_sum What: /sys/bus/platform/devices/*.ufs/monitor/write_req_latency_sum Date: January 2021 -Contact: Can Guo <cang@codeaurora.org> +Contact: Can Guo <quic_cang@quicinc.com> Description: This file shows the total latency (in micro seconds) of write requests after monitor gets started. @@ -1226,7 +1226,7 @@ Description: This file shows the total latency (in micro seconds) of write What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_presv_us_en What: /sys/bus/platform/devices/*.ufs/device_descriptor/wb_presv_us_en Date: June 2020 -Contact: Asutosh Das <asutoshd@codeaurora.org> +Contact: Asutosh Das <quic_asutoshd@quicinc.com> Description: This entry shows if preserve user-space was configured The file is read only. @@ -1234,7 +1234,7 @@ Description: This entry shows if preserve user-space was configured What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_shared_alloc_units What: /sys/bus/platform/devices/*.ufs/device_descriptor/wb_shared_alloc_units Date: June 2020 -Contact: Asutosh Das <asutoshd@codeaurora.org> +Contact: Asutosh Das <quic_asutoshd@quicinc.com> Description: This entry shows the shared allocated units of WB buffer The file is read only. @@ -1242,7 +1242,7 @@ Description: This entry shows the shared allocated units of WB buffer What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_type What: /sys/bus/platform/devices/*.ufs/device_descriptor/wb_type Date: June 2020 -Contact: Asutosh Das <asutoshd@codeaurora.org> +Contact: Asutosh Das <quic_asutoshd@quicinc.com> Description: This entry shows the configured WB type. 0x1 for shared buffer mode. 0x0 for dedicated buffer mode. @@ -1251,7 +1251,7 @@ Description: This entry shows the configured WB type. What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_buff_cap_adj What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/wb_buff_cap_adj Date: June 2020 -Contact: Asutosh Das <asutoshd@codeaurora.org> +Contact: Asutosh Das <quic_asutoshd@quicinc.com> Description: This entry shows the total user-space decrease in shared buffer mode. The value of this parameter is 3 for TLC NAND when SLC mode @@ -1262,7 +1262,7 @@ Description: This entry shows the total user-space decrease in shared What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_max_alloc_units What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/wb_max_alloc_units Date: June 2020 -Contact: Asutosh Das <asutoshd@codeaurora.org> +Contact: Asutosh Das <quic_asutoshd@quicinc.com> Description: This entry shows the Maximum total WriteBooster Buffer size which is supported by the entire device. @@ -1271,7 +1271,7 @@ Description: This entry shows the Maximum total WriteBooster Buffer size What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_max_wb_luns What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/wb_max_wb_luns Date: June 2020 -Contact: Asutosh Das <asutoshd@codeaurora.org> +Contact: Asutosh Das <quic_asutoshd@quicinc.com> Description: This entry shows the maximum number of luns that can support WriteBooster. @@ -1280,7 +1280,7 @@ Description: This entry shows the maximum number of luns that can support What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_sup_red_type What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/wb_sup_red_type Date: June 2020 -Contact: Asutosh Das <asutoshd@codeaurora.org> +Contact: Asutosh Das <quic_asutoshd@quicinc.com> Description: The supportability of user space reduction mode and preserve user space mode. 00h: WriteBooster Buffer can be configured only in @@ -1295,7 +1295,7 @@ Description: The supportability of user space reduction mode What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_sup_wb_type What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/wb_sup_wb_type Date: June 2020 -Contact: Asutosh Das <asutoshd@codeaurora.org> +Contact: Asutosh Das <quic_asutoshd@quicinc.com> Description: The supportability of WriteBooster Buffer type. === ========================================================== @@ -1310,7 +1310,7 @@ Description: The supportability of WriteBooster Buffer type. What: /sys/bus/platform/drivers/ufshcd/*/flags/wb_enable What: /sys/bus/platform/devices/*.ufs/flags/wb_enable Date: June 2020 -Contact: Asutosh Das <asutoshd@codeaurora.org> +Contact: Asutosh Das <quic_asutoshd@quicinc.com> Description: This entry shows the status of WriteBooster. == ============================ @@ -1323,7 +1323,7 @@ Description: This entry shows the status of WriteBooster. What: /sys/bus/platform/drivers/ufshcd/*/flags/wb_flush_en What: /sys/bus/platform/devices/*.ufs/flags/wb_flush_en Date: June 2020 -Contact: Asutosh Das <asutoshd@codeaurora.org> +Contact: Asutosh Das <quic_asutoshd@quicinc.com> Description: This entry shows if flush is enabled. == ================================= @@ -1336,7 +1336,7 @@ Description: This entry shows if flush is enabled. What: /sys/bus/platform/drivers/ufshcd/*/flags/wb_flush_during_h8 What: /sys/bus/platform/devices/*.ufs/flags/wb_flush_during_h8 Date: June 2020 -Contact: Asutosh Das <asutoshd@codeaurora.org> +Contact: Asutosh Das <quic_asutoshd@quicinc.com> Description: Flush WriteBooster Buffer during hibernate state. == ================================================= @@ -1351,7 +1351,7 @@ Description: Flush WriteBooster Buffer during hibernate state. What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_avail_buf What: /sys/bus/platform/devices/*.ufs/attributes/wb_avail_buf Date: June 2020 -Contact: Asutosh Das <asutoshd@codeaurora.org> +Contact: Asutosh Das <quic_asutoshd@quicinc.com> Description: This entry shows the amount of unused WriteBooster buffer available. @@ -1360,7 +1360,7 @@ Description: This entry shows the amount of unused WriteBooster buffer What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_cur_buf What: /sys/bus/platform/devices/*.ufs/attributes/wb_cur_buf Date: June 2020 -Contact: Asutosh Das <asutoshd@codeaurora.org> +Contact: Asutosh Das <quic_asutoshd@quicinc.com> Description: This entry shows the amount of unused current buffer. The file is read only. @@ -1368,7 +1368,7 @@ Description: This entry shows the amount of unused current buffer. What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_flush_status What: /sys/bus/platform/devices/*.ufs/attributes/wb_flush_status Date: June 2020 -Contact: Asutosh Das <asutoshd@codeaurora.org> +Contact: Asutosh Das <quic_asutoshd@quicinc.com> Description: This entry shows the flush operation status. @@ -1385,7 +1385,7 @@ Description: This entry shows the flush operation status. What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_life_time_est What: /sys/bus/platform/devices/*.ufs/attributes/wb_life_time_est Date: June 2020 -Contact: Asutosh Das <asutoshd@codeaurora.org> +Contact: Asutosh Das <quic_asutoshd@quicinc.com> Description: This entry shows an indication of the WriteBooster Buffer lifetime based on the amount of performed program/erase cycles @@ -1399,7 +1399,7 @@ Description: This entry shows an indication of the WriteBooster Buffer What: /sys/class/scsi_device/*/device/unit_descriptor/wb_buf_alloc_units Date: June 2020 -Contact: Asutosh Das <asutoshd@codeaurora.org> +Contact: Asutosh Das <quic_asutoshd@quicinc.com> Description: This entry shows the configured size of WriteBooster buffer. 0400h corresponds to 4GB. @@ -1437,180 +1437,6 @@ Description: If avail_wb_buff < wb_flush_threshold, it indicates that WriteBooster buffer needs to be flushed, otherwise it is not necessary. -What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/hpb_version -What: /sys/bus/platform/devices/*.ufs/device_descriptor/hpb_version -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: This entry shows the HPB specification version. - The full information about the descriptor can be found in the UFS - HPB (Host Performance Booster) Extension specifications. - Example: version 1.2.3 = 0123h - - The file is read only. - -What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/hpb_control -What: /sys/bus/platform/devices/*.ufs/device_descriptor/hpb_control -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: This entry shows an indication of the HPB control mode. - 00h: Host control mode - 01h: Device control mode - - The file is read only. - -What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/hpb_region_size -What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/hpb_region_size -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: This entry shows the bHPBRegionSize which can be calculated - as in the following (in bytes): - HPB Region size = 512B * 2^bHPBRegionSize - - The file is read only. - -What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/hpb_number_lu -What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/hpb_number_lu -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: This entry shows the maximum number of HPB LU supported by - the device. - 00h: HPB is not supported by the device. - 01h ~ 20h: Maximum number of HPB LU supported by the device - - The file is read only. - -What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/hpb_subregion_size -What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/hpb_subregion_size -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: This entry shows the bHPBSubRegionSize, which can be - calculated as in the following (in bytes) and shall be a multiple of - logical block size: - HPB Sub-Region size = 512B x 2^bHPBSubRegionSize - bHPBSubRegionSize shall not exceed bHPBRegionSize. - - The file is read only. - -What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/hpb_max_active_regions -What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/hpb_max_active_regions -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: This entry shows the maximum number of active HPB regions that - is supported by the device. - - The file is read only. - -What: /sys/class/scsi_device/*/device/unit_descriptor/hpb_lu_max_active_regions -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: This entry shows the maximum number of HPB regions assigned to - the HPB logical unit. - - The file is read only. - -What: /sys/class/scsi_device/*/device/unit_descriptor/hpb_pinned_region_start_offset -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: This entry shows the start offset of HPB pinned region. - - The file is read only. - -What: /sys/class/scsi_device/*/device/unit_descriptor/hpb_number_pinned_regions -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: This entry shows the number of HPB pinned regions assigned to - the HPB logical unit. - - The file is read only. - -What: /sys/class/scsi_device/*/device/hpb_stats/hit_cnt -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: This entry shows the number of reads that changed to HPB read. - - The file is read only. - -What: /sys/class/scsi_device/*/device/hpb_stats/miss_cnt -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: This entry shows the number of reads that cannot be changed to - HPB read. - - The file is read only. - -What: /sys/class/scsi_device/*/device/hpb_stats/rcmd_noti_cnt -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: This entry shows the number of response UPIUs that has - recommendations for activating sub-regions and/or inactivating region. - - The file is read only. - -What: /sys/class/scsi_device/*/device/hpb_stats/rcmd_active_cnt -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: For the HPB device control mode, this entry shows the number of - active sub-regions recommended by response UPIUs. For the HPB host control - mode, this entry shows the number of active sub-regions recommended by the - HPB host control mode heuristic algorithm. - - The file is read only. - -What: /sys/class/scsi_device/*/device/hpb_stats/rcmd_inactive_cnt -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: For the HPB device control mode, this entry shows the number of - inactive regions recommended by response UPIUs. For the HPB host control - mode, this entry shows the number of inactive regions recommended by the - HPB host control mode heuristic algorithm. - - The file is read only. - -What: /sys/class/scsi_device/*/device/hpb_stats/map_req_cnt -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: This entry shows the number of read buffer commands for - activating sub-regions recommended by response UPIUs. - - The file is read only. - -What: /sys/class/scsi_device/*/device/hpb_params/requeue_timeout_ms -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: This entry shows the requeue timeout threshold for write buffer - command in ms. The value can be changed by writing an integer to - this entry. - -What: /sys/bus/platform/drivers/ufshcd/*/attributes/max_data_size_hpb_single_cmd -What: /sys/bus/platform/devices/*.ufs/attributes/max_data_size_hpb_single_cmd -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: This entry shows the maximum HPB data size for using a single HPB - command. - - === ======== - 00h 4KB - 01h 8KB - 02h 12KB - ... - FFh 1024KB - === ======== - - The file is read only. - -What: /sys/bus/platform/drivers/ufshcd/*/flags/hpb_enable -What: /sys/bus/platform/devices/*.ufs/flags/hpb_enable -Date: June 2021 -Contact: Daejun Park <daejun7.park@samsung.com> -Description: This entry shows the status of HPB. - - == ============================ - 0 HPB is not enabled. - 1 HPB is enabled - == ============================ - - The file is read only. - Contact: Daniil Lunev <dlunev@chromium.org> What: /sys/bus/platform/drivers/ufshcd/*/capabilities/ What: /sys/bus/platform/devices/*.ufs/capabilities/ @@ -1648,76 +1474,3 @@ Description: Indicates status of Write Booster. The file is read only. -What: /sys/class/scsi_device/*/device/hpb_param_sysfs/activation_thld -Date: February 2021 -Contact: Avri Altman <avri.altman@wdc.com> -Description: In host control mode, reads are the major source of activation - trials. Once this threshold hs met, the region is added to the - "to-be-activated" list. Since we reset the read counter upon - write, this include sending a rb command updating the region - ppn as well. - -What: /sys/class/scsi_device/*/device/hpb_param_sysfs/normalization_factor -Date: February 2021 -Contact: Avri Altman <avri.altman@wdc.com> -Description: In host control mode, we think of the regions as "buckets". - Those buckets are being filled with reads, and emptied on write. - We use entries_per_srgn - the amount of blocks in a subregion as - our bucket size. This applies because HPB1.0 only handles - single-block reads. Once the bucket size is crossed, we trigger - a normalization work - not only to avoid overflow, but mainly - because we want to keep those counters normalized, as we are - using those reads as a comparative score, to make various decisions. - The normalization is dividing (shift right) the read counter by - the normalization_factor. If during consecutive normalizations - an active region has exhausted its reads - inactivate it. - -What: /sys/class/scsi_device/*/device/hpb_param_sysfs/eviction_thld_enter -Date: February 2021 -Contact: Avri Altman <avri.altman@wdc.com> -Description: Region deactivation is often due to the fact that eviction took - place: A region becomes active at the expense of another. This is - happening when the max-active-regions limit has been crossed. - In host mode, eviction is considered an extreme measure. We - want to verify that the entering region has enough reads, and - the exiting region has much fewer reads. eviction_thld_enter is - the min reads that a region must have in order to be considered - a candidate for evicting another region. - -What: /sys/class/scsi_device/*/device/hpb_param_sysfs/eviction_thld_exit -Date: February 2021 -Contact: Avri Altman <avri.altman@wdc.com> -Description: Same as above for the exiting region. A region is considered to - be a candidate for eviction only if it has fewer reads than - eviction_thld_exit. - -What: /sys/class/scsi_device/*/device/hpb_param_sysfs/read_timeout_ms -Date: February 2021 -Contact: Avri Altman <avri.altman@wdc.com> -Description: In order not to hang on to "cold" regions, we inactivate - a region that has no READ access for a predefined amount of - time - read_timeout_ms. If read_timeout_ms has expired, and the - region is dirty, it is less likely that we can make any use of - HPB reading it so we inactivate it. Still, deactivation has - its overhead, and we may still benefit from HPB reading this - region if it is clean - see read_timeout_expiries. - -What: /sys/class/scsi_device/*/device/hpb_param_sysfs/read_timeout_expiries -Date: February 2021 -Contact: Avri Altman <avri.altman@wdc.com> -Description: If the region read timeout has expired, but the region is clean, - just re-wind its timer for another spin. Do that as long as it - is clean and did not exhaust its read_timeout_expiries threshold. - -What: /sys/class/scsi_device/*/device/hpb_param_sysfs/timeout_polling_interval_ms -Date: February 2021 -Contact: Avri Altman <avri.altman@wdc.com> -Description: The frequency with which the delayed worker that checks the - read_timeouts is awakened. - -What: /sys/class/scsi_device/*/device/hpb_param_sysfs/inflight_map_req -Date: February 2021 -Contact: Avri Altman <avri.altman@wdc.com> -Description: In host control mode the host is the originator of map requests. - To avoid flooding the device with map requests, use a simple throttling - mechanism that limits the number of inflight map requests. diff --git a/Documentation/ABI/testing/sysfs-firmware-acpi b/Documentation/ABI/testing/sysfs-firmware-acpi index 819939d858c9..5249ad5a96d9 100644 --- a/Documentation/ABI/testing/sysfs-firmware-acpi +++ b/Documentation/ABI/testing/sysfs-firmware-acpi @@ -84,7 +84,7 @@ Description: hotplug events associated with the given class of devices and will allow those devices to be ejected with the help of the _EJ0 control method. Unsetting it - effectively disables hotplug for the correspoinding + effectively disables hotplug for the corresponding class of devices. ======== ======================================================= diff --git a/Documentation/ABI/testing/sysfs-firmware-dmi-entries b/Documentation/ABI/testing/sysfs-firmware-dmi-entries index fe0289c87768..b6c23807b804 100644 --- a/Documentation/ABI/testing/sysfs-firmware-dmi-entries +++ b/Documentation/ABI/testing/sysfs-firmware-dmi-entries @@ -2,7 +2,7 @@ What: /sys/firmware/dmi/entries/ Date: February 2011 Contact: Mike Waychison <mikew@google.com> Description: - Many machines' firmware (x86 and ia64) export DMI / + Many machines' firmware (x86 and arm64) export DMI / SMBIOS tables to the operating system. Getting at this information is often valuable to userland, especially in cases where there are OEM extensions used. diff --git a/Documentation/ABI/testing/sysfs-firmware-sgi_uv b/Documentation/ABI/testing/sysfs-firmware-sgi_uv index 12ed843e1d3e..7fe9244b87bb 100644 --- a/Documentation/ABI/testing/sysfs-firmware-sgi_uv +++ b/Documentation/ABI/testing/sysfs-firmware-sgi_uv @@ -102,12 +102,12 @@ Description: conn_port The conn_hub entry contains a value representing the unique - oridinal value of the hub on the other end of the fabric + ordinal value of the hub on the other end of the fabric cable plugged into the port. If the port is disconnected, the value returned will be -1. The conn_port entry contains a value representing the unique - oridinal value of the port on the other end of the fabric cable + ordinal value of the port on the other end of the fabric cable plugged into the port. If the port is disconnected, the value returned will be -1. diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index 8140fc98f5ae..36c3cb547901 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -54,9 +54,9 @@ Description: Controls the in-place-update policy. 0x00 DISABLE disable IPU(=default option in LFS mode) 0x01 FORCE all the time 0x02 SSR if SSR mode is activated - 0x04 UTIL if FS utilization is over threashold + 0x04 UTIL if FS utilization is over threshold 0x08 SSR_UTIL if SSR mode is activated and FS utilization is over - threashold + threshold 0x10 FSYNC activated in fsync path only for high performance flash storages. IPU will be triggered only if the # of dirty pages over min_fsync_blocks. @@ -102,9 +102,9 @@ What: /sys/fs/f2fs/<disk>/max_small_discards Date: November 2013 Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com> Description: Controls the issue rate of discard commands that consist of small - blocks less than 2MB. The candidates to be discarded are cached until - checkpoint is triggered, and issued during the checkpoint. - By default, it is disabled with 0. + blocks less than 2MB. The candidates to be discarded are cached during + checkpoint, and issued by issue_discard thread after checkpoint. + It is enabled by default. What: /sys/fs/f2fs/<disk>/max_ordered_discard Date: October 2022 @@ -117,7 +117,7 @@ Date: December 2021 Contact: "Konstantin Vyshetsky" <vkon@google.com> Description: Controls the number of discards a thread will issue at a time. Higher number will allow the discard thread to finish its work - faster, at the cost of higher latency for incomming I/O. + faster, at the cost of higher latency for incoming I/O. What: /sys/fs/f2fs/<disk>/min_discard_issue_time Date: December 2021 @@ -334,7 +334,7 @@ Description: This indicates how many GC can be failed for the pinned state. 2048 trials is set by default. What: /sys/fs/f2fs/<disk>/extension_list -Date: Feburary 2018 +Date: February 2018 Contact: "Chao Yu" <yuchao0@huawei.com> Description: Used to control configure extension list: - Query: cat /sys/fs/f2fs/<disk>/extension_list diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-damon b/Documentation/ABI/testing/sysfs-kernel-mm-damon index 2744f21b5a6b..b35649a46a2f 100644 --- a/Documentation/ABI/testing/sysfs-kernel-mm-damon +++ b/Documentation/ABI/testing/sysfs-kernel-mm-damon @@ -29,8 +29,10 @@ Description: Writing 'on' or 'off' to this file makes the kdamond starts or file updates contents of schemes stats files of the kdamond. Writing 'update_schemes_tried_regions' to the file updates contents of 'tried_regions' directory of every scheme directory - of this kdamond. Writing 'clear_schemes_tried_regions' to the - file removes contents of the 'tried_regions' directory. + of this 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. What: /sys/kernel/mm/damon/admin/kdamonds/<K>/pid Date: Mar 2022 @@ -149,10 +151,17 @@ Contact: SeongJae Park <sj@kernel.org> Description: Writing to and reading from this file sets and gets the action of the scheme. +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/apply_interval_us +Date: Sep 2023 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing a value to this file sets the action apply interval of + the scheme in microseconds. Reading this file returns the + value. + What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/sz/min Date: Mar 2022 Contact: SeongJae Park <sj@kernel.org> -Description: Writing to and reading from this file sets and gets the mimimum +Description: Writing to and reading from this file sets and gets the minimum size of the scheme's target regions in bytes. What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/sz/max @@ -269,8 +278,10 @@ What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/ Date: Dec 2022 Contact: SeongJae Park <sj@kernel.org> Description: Writing to and reading from this file sets and gets the type of - the memory of the interest. 'anon' for anonymous pages, or - 'memcg' for specific memory cgroup can be written and read. + the memory of the interest. 'anon' for anonymous pages, + 'memcg' for specific memory cgroup, 'addr' for address range + (an open-ended interval), or 'target' for DAMON monitoring + target can be written and read. What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/memcg_path Date: Dec 2022 @@ -279,6 +290,27 @@ Description: If 'memcg' is written to the 'type' file, writing to and reading from this file sets and gets the path to the memory cgroup of the interest. +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/addr_start +Date: Jul 2023 +Contact: SeongJae Park <sj@kernel.org> +Description: If 'addr' is written to the 'type' file, writing to or reading + from this file sets or gets the start address of the address + range for the filter. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/addr_end +Date: Jul 2023 +Contact: SeongJae Park <sj@kernel.org> +Description: If 'addr' is written to the 'type' file, writing to or reading + from this file sets or gets the end address of the address + range for the filter. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/target_idx +Date: Dec 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: If 'target' is written to the 'type' file, writing to or + reading from this file sets or gets the index of the DAMON + monitoring target of the interest. + What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/matching Date: Dec 2022 Contact: SeongJae Park <sj@kernel.org> @@ -317,6 +349,13 @@ Contact: SeongJae Park <sj@kernel.org> Description: Reading this file returns the number of the exceed events of the scheme's quotas. +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/total_bytes +Date: Jul 2023 +Contact: SeongJae Park <sj@kernel.org> +Description: Reading this file returns the total amount of memory that + corresponding DAMON-based Operation Scheme's action has tried + to be applied. + What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/<R>/start Date: Oct 2022 Contact: SeongJae Park <sj@kernel.org> diff --git a/Documentation/ABI/testing/sysfs-memory-page-offline b/Documentation/ABI/testing/sysfs-memory-page-offline index e14703f12fdf..00f4e35f916f 100644 --- a/Documentation/ABI/testing/sysfs-memory-page-offline +++ b/Documentation/ABI/testing/sysfs-memory-page-offline @@ -10,7 +10,7 @@ Description: dropping it if possible. The kernel will then be placed on the bad page list and never be reused. - The offlining is done in kernel specific granuality. + The offlining is done in kernel specific granularity. Normally it's the base page size of the kernel, but this might change. @@ -35,7 +35,7 @@ Description: to access this page assuming it's poisoned by the hardware. - The offlining is done in kernel specific granuality. + The offlining is done in kernel specific granularity. Normally it's the base page size of the kernel, but this might change. diff --git a/Documentation/ABI/testing/sysfs-module b/Documentation/ABI/testing/sysfs-module index 08886367d047..62addab47d0c 100644 --- a/Documentation/ABI/testing/sysfs-module +++ b/Documentation/ABI/testing/sysfs-module @@ -60,3 +60,14 @@ Description: Module taint flags: C staging driver module E unsigned module == ===================== + +What: /sys/module/grant_table/parameters/free_per_iteration +Date: July 2023 +KernelVersion: 6.5 but backported to all supported stable branches +Contact: Xen developer discussion <xen-devel@lists.xenproject.org> +Description: Read and write number of grant entries to attempt to free per iteration. + + Note: Future versions of Xen and Linux may provide a better + interface for controlling the rate of deferred grant reclaim + or may not need it at all. +Users: Qubes OS (https://www.qubes-os.org) diff --git a/Documentation/ABI/testing/sysfs-platform-asus-wmi b/Documentation/ABI/testing/sysfs-platform-asus-wmi index a77a004a1baa..8a7e25bde085 100644 --- a/Documentation/ABI/testing/sysfs-platform-asus-wmi +++ b/Documentation/ABI/testing/sysfs-platform-asus-wmi @@ -98,3 +98,91 @@ Description: Enable an LCD response-time boost to reduce or remove ghosting: * 0 - Disable, * 1 - Enable + +What: /sys/devices/platform/<platform>/charge_mode +Date: Jun 2023 +KernelVersion: 6.5 +Contact: "Luke Jones" <luke@ljones.dev> +Description: + Get the current charging mode being used: + * 1 - Barrel connected charger, + * 2 - USB-C charging + * 3 - Both connected, barrel used for charging + +What: /sys/devices/platform/<platform>/egpu_connected +Date: Jun 2023 +KernelVersion: 6.5 +Contact: "Luke Jones" <luke@ljones.dev> +Description: + Show if the egpu (XG Mobile) is correctly connected: + * 0 - False, + * 1 - True + +What: /sys/devices/platform/<platform>/mini_led_mode +Date: Jun 2023 +KernelVersion: 6.5 +Contact: "Luke Jones" <luke@ljones.dev> +Description: + Change the mini-LED mode: + * 0 - Single-zone, + * 1 - Multi-zone + +What: /sys/devices/platform/<platform>/ppt_pl1_spl +Date: Jun 2023 +KernelVersion: 6.5 +Contact: "Luke Jones" <luke@ljones.dev> +Description: + Set the Package Power Target total of CPU: PL1 on Intel, SPL on AMD. + Shown on Intel+Nvidia or AMD+Nvidia based systems: + + * min=5, max=250 + +What: /sys/devices/platform/<platform>/ppt_pl2_sppt +Date: Jun 2023 +KernelVersion: 6.5 +Contact: "Luke Jones" <luke@ljones.dev> +Description: + Set the Slow Package Power Tracking Limit of CPU: PL2 on Intel, SPPT, + on AMD. Shown on Intel+Nvidia or AMD+Nvidia based systems: + + * min=5, max=250 + +What: /sys/devices/platform/<platform>/ppt_fppt +Date: Jun 2023 +KernelVersion: 6.5 +Contact: "Luke Jones" <luke@ljones.dev> +Description: + Set the Fast Package Power Tracking Limit of CPU. AMD+Nvidia only: + * min=5, max=250 + +What: /sys/devices/platform/<platform>/ppt_apu_sppt +Date: Jun 2023 +KernelVersion: 6.5 +Contact: "Luke Jones" <luke@ljones.dev> +Description: + Set the APU SPPT limit. Shown on full AMD systems only: + * min=5, max=130 + +What: /sys/devices/platform/<platform>/ppt_platform_sppt +Date: Jun 2023 +KernelVersion: 6.5 +Contact: "Luke Jones" <luke@ljones.dev> +Description: + Set the platform SPPT limit. Shown on full AMD systems only: + * min=5, max=130 + +What: /sys/devices/platform/<platform>/nv_dynamic_boost +Date: Jun 2023 +KernelVersion: 6.5 +Contact: "Luke Jones" <luke@ljones.dev> +Description: + Set the dynamic boost limit of the Nvidia dGPU: + * min=5, max=25 + +What: /sys/devices/platform/<platform>/nv_temp_target +Date: Jun 2023 +KernelVersion: 6.5 +Contact: "Luke Jones" <luke@ljones.dev> +Description: + Set the target temperature limit of the Nvidia dGPU: + * min=75, max=87 diff --git a/Documentation/ABI/testing/sysfs-platform-dell-laptop b/Documentation/ABI/testing/sysfs-platform-dell-laptop index 82bcfe9df66e..701529653283 100644 --- a/Documentation/ABI/testing/sysfs-platform-dell-laptop +++ b/Documentation/ABI/testing/sysfs-platform-dell-laptop @@ -15,7 +15,7 @@ KernelVersion: 3.19 Contact: Gabriele Mazzotta <gabriele.mzt@gmail.com>, Pali Rohár <pali@kernel.org> Description: - This file allows to specifiy the on/off threshold value, + This file allows to specify the on/off threshold value, as reported by the ambient light sensor. What: /sys/class/leds/dell::kbd_backlight/start_triggers diff --git a/Documentation/ABI/testing/sysfs-platform-dfl-fme b/Documentation/ABI/testing/sysfs-platform-dfl-fme index d6ab34e81b9b..2d5b78d2cf51 100644 --- a/Documentation/ABI/testing/sysfs-platform-dfl-fme +++ b/Documentation/ABI/testing/sysfs-platform-dfl-fme @@ -90,7 +90,7 @@ KernelVersion: 5.4 Contact: Wu Hao <hao.wu@intel.com> Description: Read-Write. Read this file to get errors detected on FME. Write this file to clear errors logged in fme_errors. Write - fials with -EINVAL if input parsing fails or input error code + fails with -EINVAL if input parsing fails or input error code doesn't match. What: /sys/bus/platform/devices/dfl-fme.0/errors/first_error diff --git a/Documentation/ABI/testing/sysfs-platform-hidma b/Documentation/ABI/testing/sysfs-platform-hidma index fca40a54df59..a80aeda85ef6 100644 --- a/Documentation/ABI/testing/sysfs-platform-hidma +++ b/Documentation/ABI/testing/sysfs-platform-hidma @@ -2,7 +2,7 @@ What: /sys/devices/platform/hidma-*/chid /sys/devices/platform/QCOM8061:*/chid Date: Dec 2015 KernelVersion: 4.4 -Contact: "Sinan Kaya <okaya@codeaurora.org>" +Contact: "Sinan Kaya <okaya@kernel.org>" Description: Contains the ID of the channel within the HIDMA instance. It is used to associate a given HIDMA channel with the diff --git a/Documentation/ABI/testing/sysfs-platform-hidma-mgmt b/Documentation/ABI/testing/sysfs-platform-hidma-mgmt index 3b6c5c9eabdc..0373745b4e18 100644 --- a/Documentation/ABI/testing/sysfs-platform-hidma-mgmt +++ b/Documentation/ABI/testing/sysfs-platform-hidma-mgmt @@ -2,7 +2,7 @@ What: /sys/devices/platform/hidma-mgmt*/chanops/chan*/priority /sys/devices/platform/QCOM8060:*/chanops/chan*/priority Date: Nov 2015 KernelVersion: 4.4 -Contact: "Sinan Kaya <okaya@codeaurora.org>" +Contact: "Sinan Kaya <okaya@kernel.org>" Description: Contains either 0 or 1 and indicates if the DMA channel is a low priority (0) or high priority (1) channel. @@ -11,7 +11,7 @@ What: /sys/devices/platform/hidma-mgmt*/chanops/chan*/weight /sys/devices/platform/QCOM8060:*/chanops/chan*/weight Date: Nov 2015 KernelVersion: 4.4 -Contact: "Sinan Kaya <okaya@codeaurora.org>" +Contact: "Sinan Kaya <okaya@kernel.org>" Description: Contains 0..15 and indicates the weight of the channel among equal priority channels during round robin scheduling. @@ -20,7 +20,7 @@ What: /sys/devices/platform/hidma-mgmt*/chreset_timeout_cycles /sys/devices/platform/QCOM8060:*/chreset_timeout_cycles Date: Nov 2015 KernelVersion: 4.4 -Contact: "Sinan Kaya <okaya@codeaurora.org>" +Contact: "Sinan Kaya <okaya@kernel.org>" Description: Contains the platform specific cycle value to wait after a reset command is issued. If the value is chosen too short, @@ -32,7 +32,7 @@ What: /sys/devices/platform/hidma-mgmt*/dma_channels /sys/devices/platform/QCOM8060:*/dma_channels Date: Nov 2015 KernelVersion: 4.4 -Contact: "Sinan Kaya <okaya@codeaurora.org>" +Contact: "Sinan Kaya <okaya@kernel.org>" Description: Contains the number of dma channels supported by one instance of HIDMA hardware. The value may change from chip to chip. @@ -41,7 +41,7 @@ What: /sys/devices/platform/hidma-mgmt*/hw_version_major /sys/devices/platform/QCOM8060:*/hw_version_major Date: Nov 2015 KernelVersion: 4.4 -Contact: "Sinan Kaya <okaya@codeaurora.org>" +Contact: "Sinan Kaya <okaya@kernel.org>" Description: Version number major for the hardware. @@ -49,7 +49,7 @@ What: /sys/devices/platform/hidma-mgmt*/hw_version_minor /sys/devices/platform/QCOM8060:*/hw_version_minor Date: Nov 2015 KernelVersion: 4.4 -Contact: "Sinan Kaya <okaya@codeaurora.org>" +Contact: "Sinan Kaya <okaya@kernel.org>" Description: Version number minor for the hardware. @@ -57,7 +57,7 @@ What: /sys/devices/platform/hidma-mgmt*/max_rd_xactions /sys/devices/platform/QCOM8060:*/max_rd_xactions Date: Nov 2015 KernelVersion: 4.4 -Contact: "Sinan Kaya <okaya@codeaurora.org>" +Contact: "Sinan Kaya <okaya@kernel.org>" Description: Contains a value between 0 and 31. Maximum number of read transactions that can be issued back to back. @@ -69,7 +69,7 @@ What: /sys/devices/platform/hidma-mgmt*/max_read_request /sys/devices/platform/QCOM8060:*/max_read_request Date: Nov 2015 KernelVersion: 4.4 -Contact: "Sinan Kaya <okaya@codeaurora.org>" +Contact: "Sinan Kaya <okaya@kernel.org>" Description: Size of each read request. The value needs to be a power of two and can be between 128 and 1024. @@ -78,7 +78,7 @@ What: /sys/devices/platform/hidma-mgmt*/max_wr_xactions /sys/devices/platform/QCOM8060:*/max_wr_xactions Date: Nov 2015 KernelVersion: 4.4 -Contact: "Sinan Kaya <okaya@codeaurora.org>" +Contact: "Sinan Kaya <okaya@kernel.org>" Description: Contains a value between 0 and 31. Maximum number of write transactions that can be issued back to back. @@ -91,7 +91,7 @@ What: /sys/devices/platform/hidma-mgmt*/max_write_request /sys/devices/platform/QCOM8060:*/max_write_request Date: Nov 2015 KernelVersion: 4.4 -Contact: "Sinan Kaya <okaya@codeaurora.org>" +Contact: "Sinan Kaya <okaya@kernel.org>" Description: Size of each write request. The value needs to be a power of two and can be between 128 and 1024. diff --git a/Documentation/ABI/testing/sysfs-platform-kim b/Documentation/ABI/testing/sysfs-platform-kim index 6a52d6d2b601..0a38caa62a32 100644 --- a/Documentation/ABI/testing/sysfs-platform-kim +++ b/Documentation/ABI/testing/sysfs-platform-kim @@ -9,7 +9,7 @@ Description: The device name flows down to architecture specific board initialization file from the ATAGS bootloader firmware. The name exposed is read from the user-space - dameon and opens the device when install is requested. + daemon and opens the device when install is requested. What: /sys/devices/platform/kim/baud_rate Date: January 2010 diff --git a/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl index 4c5c02d8f870..65ed3865da62 100644 --- a/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl +++ b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl @@ -84,3 +84,69 @@ Description: The file used to write BlueField boot log with the format "[INFO|WARN|ERR|ASSERT ]<msg>". Log level 'INFO' is used by default if not specified. + +What: /sys/bus/platform/devices/MLNXBF04:00/oob_mac +Date: August 2023 +KernelVersion: 6.5 +Contact: "David Thompson <davthompson@nvidia.com>" +Description: + The "oob_mac" sysfs attribute holds the MAC address for + the out-of-band 1Gbps Ethernet port. This MAC address is + provided on a board-level label. + +What: /sys/bus/platform/devices/MLNXBF04:00/opn +Date: August 2023 +KernelVersion: 6.5 +Contact: "David Thompson <davthompson@nvidia.com>" +Description: + The "opn" sysfs attribute holds the board's part number. + This value is provided on a board-level label. + +What: /sys/bus/platform/devices/MLNXBF04:00/sku +Date: August 2023 +KernelVersion: 6.5 +Contact: "David Thompson <davthompson@nvidia.com>" +Description: + The "sku" sysfs attribute holds the board's SKU number. + This value is provided on a board-level label. + +What: /sys/bus/platform/devices/MLNXBF04:00/modl +Date: August 2023 +KernelVersion: 6.5 +Contact: "David Thompson <davthompson@nvidia.com>" +Description: + The "modl" sysfs attribute holds the board's model number. + This value is provided on a board-level label. + +What: /sys/bus/platform/devices/MLNXBF04:00/sn +Date: August 2023 +KernelVersion: 6.5 +Contact: "David Thompson <davthompson@nvidia.com>" +Description: + The "sn" sysfs attribute holds the board's serial number. + This value is provided on a board-level label. + +What: /sys/bus/platform/devices/MLNXBF04:00/uuid +Date: August 2023 +KernelVersion: 6.5 +Contact: "David Thompson <davthompson@nvidia.com>" +Description: + The "uuid" sysfs attribute holds the board's UUID. + This value is provided by the manufacturing team. + +What: /sys/bus/platform/devices/MLNXBF04:00/rev +Date: August 2023 +KernelVersion: 6.5 +Contact: "David Thompson <davthompson@nvidia.com>" +Description: + The "rev" sysfs attribute holds the board's revision. + This value is provided on a board-level label. + +What: /sys/bus/platform/devices/MLNXBF04:00/mfg_lock +Date: August 2023 +KernelVersion: 6.5 +Contact: "David Thompson <davthompson@nvidia.com>" +Description: + The "mfg_lock" sysfs attribute is write-only. + A successful write to this attribute will latch the + board-level attributes into EEPROM, making them read-only. diff --git a/Documentation/ABI/testing/sysfs-platform-power-on-reason b/Documentation/ABI/testing/sysfs-platform-power-on-reason new file mode 100644 index 000000000000..c3b29dbc64bf --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-power-on-reason @@ -0,0 +1,12 @@ +What: /sys/devices/platform/.../power_on_reason +Date: June 2023 +KernelVersion: 6.5 +Contact: Kamel Bouhara <kamel.bouhara@bootlin.com> +Description: Shows system power on reason. The following strings/reasons can + be read (the list can be extended): + "regular power-up", "RTC wakeup", "watchdog timeout", + "software reset", "reset button action", "CPU clock failure", + "crystal oscillator failure", "brown-out reset", + "unknown reason". + + The file is read only. diff --git a/Documentation/ABI/testing/sysfs-platform-sst-atom b/Documentation/ABI/testing/sysfs-platform-sst-atom index 0154b0fba759..4bb2e6135c2e 100644 --- a/Documentation/ABI/testing/sysfs-platform-sst-atom +++ b/Documentation/ABI/testing/sysfs-platform-sst-atom @@ -4,7 +4,7 @@ KernelVersion: 4.10 Contact: "Sebastien Guiriec" <sebastien.guiriec@intel.com> Description: LPE Firmware version for SST driver on all atom - plaforms (BYT/CHT/Merrifield/BSW). + platforms (BYT/CHT/Merrifield/BSW). If the FW has never been loaded it will display:: "FW not yet loaded" diff --git a/Documentation/ABI/testing/sysfs-wusb_cbaf b/Documentation/ABI/testing/sysfs-wusb_cbaf deleted file mode 100644 index 2969d3694ec0..000000000000 --- a/Documentation/ABI/testing/sysfs-wusb_cbaf +++ /dev/null @@ -1,101 +0,0 @@ -What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_* -Date: August 2008 -KernelVersion: 2.6.27 -Contact: David Vrabel <david.vrabel@csr.com> -Description: - Various files for managing Cable Based Association of - (wireless) USB devices. - - The sequence of operations should be: - - 1. Device is plugged in. - - 2. The connection manager (CM) sees a device with CBA capability. - (the wusb_chid etc. files in /sys/devices/blah/OURDEVICE). - - 3. The CM writes the host name, supported band groups, - and the CHID (host ID) into the wusb_host_name, - wusb_host_band_groups and wusb_chid files. These - get sent to the device and the CDID (if any) for - this host is requested. - - 4. The CM can verify that the device's supported band - groups (wusb_device_band_groups) are compatible - with the host. - - 5. The CM reads the wusb_cdid file. - - 6. The CM looks it up its database. - - - If it has a matching CHID,CDID entry, the device - has been authorized before and nothing further - needs to be done. - - - If the CDID is zero (or the CM doesn't find a - matching CDID in its database), the device is - assumed to be not known. The CM may associate - the host with device by: writing a randomly - generated CDID to wusb_cdid and then a random CK - to wusb_ck (this uploads the new CC to the - device). - - CMD may choose to prompt the user before - associating with a new device. - - 7. Device is unplugged. - - References: - [WUSB-AM] - Association Models Supplement to the - Certified Wireless Universal Serial Bus - Specification, version 1.0. - -What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_chid -Date: August 2008 -KernelVersion: 2.6.27 -Contact: David Vrabel <david.vrabel@csr.com> -Description: - The CHID of the host formatted as 16 space-separated - hex octets. - - Writes fetches device's supported band groups and the - the CDID for any existing association with this host. - -What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_host_name -Date: August 2008 -KernelVersion: 2.6.27 -Contact: David Vrabel <david.vrabel@csr.com> -Description: - A friendly name for the host as a UTF-8 encoded string. - -What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_host_band_groups -Date: August 2008 -KernelVersion: 2.6.27 -Contact: David Vrabel <david.vrabel@csr.com> -Description: - The band groups supported by the host, in the format - defined in [WUSB-AM]. - -What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_device_band_groups -Date: August 2008 -KernelVersion: 2.6.27 -Contact: David Vrabel <david.vrabel@csr.com> -Description: - The band groups supported by the device, in the format - defined in [WUSB-AM]. - -What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_cdid -Date: August 2008 -KernelVersion: 2.6.27 -Contact: David Vrabel <david.vrabel@csr.com> -Description: - The device's CDID formatted as 16 space-separated hex - octets. - -What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_ck -Date: August 2008 -KernelVersion: 2.6.27 -Contact: David Vrabel <david.vrabel@csr.com> -Description: - Write 16 space-separated random, hex octets to - associate with the device. diff --git a/Documentation/Makefile b/Documentation/Makefile index 023fa658a0a8..2f35793acd2a 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -59,6 +59,12 @@ PAPEROPT_letter = -D latex_paper_size=letter KERNELDOC = $(srctree)/scripts/kernel-doc KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) +ifneq ($(wildcard $(srctree)/.config),) +ifeq ($(CONFIG_RUST),y) + # Let Sphinx know we will include rustdoc + ALLSPHINXOPTS += -t rustdoc +endif +endif # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . @@ -95,6 +101,16 @@ htmldocs: @$(srctree)/scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) +# If Rust support is available and .config exists, add rustdoc generated contents. +# If there are any, the errors from this make rustdoc will be displayed but +# won't stop the execution of htmldocs + +ifneq ($(wildcard $(srctree)/.config),) +ifeq ($(CONFIG_RUST),y) + $(Q)$(MAKE) rustdoc || true +endif +endif + texinfodocs: @$(srctree)/scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var))) diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst index c237596f67e3..42e1e78353f3 100644 --- a/Documentation/PCI/pci-error-recovery.rst +++ b/Documentation/PCI/pci-error-recovery.rst @@ -17,7 +17,7 @@ chipsets are able to deal with these errors; these include PCI-E chipsets, and the PCI-host bridges found on IBM Power4, Power5 and Power6-based pSeries boxes. A typical action taken is to disconnect the affected device, halting all I/O to it. The goal of a disconnection is to avoid system -corruption; for example, to halt system memory corruption due to DMA's +corruption; for example, to halt system memory corruption due to DMAs to "wild" addresses. Typically, a reconnection mechanism is also offered, so that the affected PCI device(s) are reset and put back into working condition. The reset phase requires coordination @@ -178,9 +178,9 @@ is STEP 6 (Permanent Failure). complex and not worth implementing. The current powerpc implementation doesn't much care if the device - attempts I/O at this point, or not. I/O's will fail, returning + attempts I/O at this point, or not. I/Os will fail, returning a value of 0xff on read, and writes will be dropped. If more than - EEH_MAX_FAILS I/O's are attempted to a frozen adapter, EEH + EEH_MAX_FAILS I/Os are attempted to a frozen adapter, EEH assumes that the device driver has gone into an infinite loop and prints an error to syslog. A reboot is then required to get the device working again. @@ -204,7 +204,7 @@ instead will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset) .. note:: The following is proposed; no platform implements this yet: - Proposal: All I/O's should be done _synchronously_ from within + Proposal: All I/Os should be done _synchronously_ from within this callback, errors triggered by them will be returned via the normal pci_check_whatever() API, no new error_detected() callback will be issued due to an error happening here. However, @@ -258,7 +258,7 @@ Powerpc platforms implement two levels of slot reset: soft reset(default) and fundamental(optional) reset. Powerpc soft reset consists of asserting the adapter #RST line and then -restoring the PCI BAR's and PCI configuration header to a state +restoring the PCI BARs and PCI configuration header to a state that is equivalent to what it would be after a fresh system power-on followed by power-on BIOS/system firmware initialization. Soft reset is also known as hot-reset. @@ -362,9 +362,9 @@ permanent failure in some way. If the device is hotplug-capable, the operator will probably want to remove and replace the device. Note, however, not all failures are truly "permanent". Some are caused by over-heating, some by a poorly seated card. Many -PCI error events are caused by software bugs, e.g. DMA's to +PCI error events are caused by software bugs, e.g. DMAs to wild addresses or bogus split transactions due to programming -errors. See the discussion in Documentation/powerpc/eeh-pci-error-recovery.rst +errors. See the discussion in Documentation/arch/powerpc/eeh-pci-error-recovery.rst for additional detail on real-life experience of the causes of software errors. @@ -404,7 +404,7 @@ That is, the recovery API only requires that: .. note:: Implementation details for the powerpc platform are discussed in - the file Documentation/powerpc/eeh-pci-error-recovery.rst + the file Documentation/arch/powerpc/eeh-pci-error-recovery.rst As of this writing, there is a growing list of device drivers with patches implementing error recovery. Not all of these patches are in diff --git a/Documentation/PCI/pciebus-howto.rst b/Documentation/PCI/pciebus-howto.rst index f882ff62c51f..a0027e8fb0d0 100644 --- a/Documentation/PCI/pciebus-howto.rst +++ b/Documentation/PCI/pciebus-howto.rst @@ -213,8 +213,12 @@ PCI Config Registers -------------------- Each service driver runs its PCI config operations on its own -capability structure except the PCI Express capability structure, in -which Root Control register and Device Control register are shared -between PME and AER. This patch assumes that all service drivers -will be well behaved and not overwrite other service driver's -configuration settings. +capability structure except the PCI Express capability structure, +that is shared between many drivers including the service drivers. +RMW Capability accessors (pcie_capability_clear_and_set_word(), +pcie_capability_set_word(), and pcie_capability_clear_word()) protect +a selected set of PCI Express Capability Registers (Link Control +Register and Root Control Register). Any change to those registers +should be performed using RMW accessors to avoid problems due to +concurrent updates. For the up-to-date list of protected registers, +see pcie_capability_clear_and_set_word(). diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst index 93d899d53258..414f8a2012d6 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst @@ -181,7 +181,7 @@ operations is carried out at several levels: of this wait (or series of waits, as the case may be) is to permit a concurrent CPU-hotplug operation to complete. #. In the case of RCU-sched, one of the last acts of an outgoing CPU is - to invoke ``rcu_report_dead()``, which reports a quiescent state for + to invoke ``rcutree_report_cpu_dead()``, which reports a quiescent state for that CPU. However, this is likely paranoia-induced redundancy. +-----------------------------------------------------------------------+ diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-registry.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-registry.svg index 7ac6f9269806..63eff867175a 100644 --- a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-registry.svg +++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-registry.svg @@ -566,15 +566,6 @@ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcutree_migrate_callbacks()</text> <text xml:space="preserve" - x="8335.4873" - y="5357.1006" - font-style="normal" - font-weight="bold" - font-size="192" - id="text202-7-9-6-0" - style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_migrate_callbacks()</text> - <text - xml:space="preserve" x="8768.4678" y="6224.9038" font-style="normal" diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-fqs.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-fqs.svg index 7ddc094d7f28..d82a77d03d8c 100644 --- a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-fqs.svg +++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-fqs.svg @@ -1135,7 +1135,7 @@ font-weight="bold" font-size="192" id="text202-7-5-3-27-6-5" - style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_report_dead()</text> + style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcutree_report_cpu_dead()</text> <text xml:space="preserve" x="3745.7725" @@ -1256,7 +1256,7 @@ font-style="normal" y="3679.27" x="-3804.9949" - xml:space="preserve">rcu_cpu_starting()</text> + xml:space="preserve">rcutree_report_cpu_starting()</text> <g style="fill:none;stroke-width:0.025in" id="g3107-7-5-0" diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg index 069f6f8371c2..53e0dc2a2c79 100644 --- a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg +++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg @@ -1448,15 +1448,6 @@ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcutree_migrate_callbacks()</text> <text xml:space="preserve" - x="8335.4873" - y="5357.1006" - font-style="normal" - font-weight="bold" - font-size="192" - id="text202-7-9-6-0" - style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_migrate_callbacks()</text> - <text - xml:space="preserve" x="8768.4678" y="6224.9038" font-style="normal" @@ -3274,7 +3265,7 @@ font-weight="bold" font-size="192" id="text202-7-5-3-27-6-5" - style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_report_dead()</text> + style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcutree_report_cpu_dead()</text> <text xml:space="preserve" x="3745.7725" @@ -3395,7 +3386,7 @@ font-style="normal" y="3679.27" x="-3804.9949" - xml:space="preserve">rcu_cpu_starting()</text> + xml:space="preserve">rcutree_report_cpu_starting()</text> <g style="fill:none;stroke-width:0.025in" id="g3107-7-5-0" diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-hotplug.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-hotplug.svg index 2c9310ba29ba..4fa7506082bf 100644 --- a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-hotplug.svg +++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-hotplug.svg @@ -607,7 +607,7 @@ font-weight="bold" font-size="192" id="text202-7-5-3-27-6" - style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_report_dead()</text> + style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcutree_report_cpu_dead()</text> <text xml:space="preserve" x="3745.7725" @@ -728,7 +728,7 @@ font-style="normal" y="3679.27" x="-3804.9949" - xml:space="preserve">rcu_cpu_starting()</text> + xml:space="preserve">rcutree_report_cpu_starting()</text> <g style="fill:none;stroke-width:0.025in" id="g3107-7-5-0" diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst index f3b605285a87..cccafdaa1f84 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.rst +++ b/Documentation/RCU/Design/Requirements/Requirements.rst @@ -1955,12 +1955,12 @@ if offline CPUs block an RCU grace period for too long. An offline CPU's quiescent state will be reported either: -1. As the CPU goes offline using RCU's hotplug notifier (rcu_report_dead()). +1. As the CPU goes offline using RCU's hotplug notifier (rcutree_report_cpu_dead()). 2. When grace period initialization (rcu_gp_init()) detects a race either with CPU offlining or with a task unblocking on a leaf ``rcu_node`` structure whose CPUs are all offline. -The CPU-online path (rcu_cpu_starting()) should never need to report +The CPU-online path (rcutree_report_cpu_starting()) should never need to report a quiescent state for an offline CPU. However, as a debugging measure, it does emit a warning if a quiescent state was not already reported for that CPU. diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst index bdc4bcc5289f..ed5c9d8c9afe 100644 --- a/Documentation/RCU/listRCU.rst +++ b/Documentation/RCU/listRCU.rst @@ -8,6 +8,15 @@ One of the most common uses of RCU is protecting read-mostly linked lists that all of the required memory ordering is provided by the list macros. This document describes several list-based RCU use cases. +When iterating a list while holding the rcu_read_lock(), writers may +modify the list. The reader is guaranteed to see all of the elements +which were added to the list before they acquired the rcu_read_lock() +and are still on the list when they drop the rcu_read_unlock(). +Elements which are added to, or removed from the list may or may not +be seen. If the writer calls list_replace_rcu(), the reader may see +either the old element or the new element; they will not see both, +nor will they see neither. + Example 1: Read-mostly list: Deferred Destruction ------------------------------------------------- diff --git a/Documentation/RCU/lockdep-splat.rst b/Documentation/RCU/lockdep-splat.rst index 2a5c79db57dc..bcbc4b3c88d7 100644 --- a/Documentation/RCU/lockdep-splat.rst +++ b/Documentation/RCU/lockdep-splat.rst @@ -10,7 +10,7 @@ misuses of the RCU API, most notably using one of the rcu_dereference() family to access an RCU-protected pointer without the proper protection. When such misuse is detected, an lockdep-RCU splat is emitted. -The usual cause of a lockdep-RCU slat is someone accessing an +The usual cause of a lockdep-RCU splat is someone accessing an RCU-protected data structure without either (1) being in the right kind of RCU read-side critical section or (2) holding the right update-side lock. This problem can therefore be serious: it might result in random memory diff --git a/Documentation/RCU/rculist_nulls.rst b/Documentation/RCU/rculist_nulls.rst index 9a734bf54b76..21e40fcc08de 100644 --- a/Documentation/RCU/rculist_nulls.rst +++ b/Documentation/RCU/rculist_nulls.rst @@ -18,7 +18,16 @@ to solve following problem. Without 'nulls', a typical RCU linked list managing objects which are allocated with SLAB_TYPESAFE_BY_RCU kmem_cache can use the following -algorithms: +algorithms. Following examples assume 'obj' is a pointer to such +objects, which is having below type. + +:: + + struct object { + struct hlist_node obj_node; + atomic_t refcnt; + unsigned int key; + }; 1) Lookup algorithm ------------------- @@ -26,11 +35,13 @@ algorithms: :: begin: - rcu_read_lock() + rcu_read_lock(); obj = lockless_lookup(key); if (obj) { - if (!try_get_ref(obj)) // might fail for free objects + if (!try_get_ref(obj)) { // might fail for free objects + rcu_read_unlock(); goto begin; + } /* * Because a writer could delete object, and a writer could * reuse these object before the RCU grace period, we @@ -54,7 +65,7 @@ but a version with an additional memory barrier (smp_rmb()) struct hlist_node *node, *next; for (pos = rcu_dereference((head)->first); pos && ({ next = pos->next; smp_rmb(); prefetch(next); 1; }) && - ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; }); + ({ obj = hlist_entry(pos, typeof(*obj), obj_node); 1; }); pos = rcu_dereference(next)) if (obj->key == key) return obj; @@ -66,10 +77,10 @@ And note the traditional hlist_for_each_entry_rcu() misses this smp_rmb():: struct hlist_node *node; for (pos = rcu_dereference((head)->first); pos && ({ prefetch(pos->next); 1; }) && - ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; }); + ({ obj = hlist_entry(pos, typeof(*obj), obj_node); 1; }); pos = rcu_dereference(pos->next)) - if (obj->key == key) - return obj; + if (obj->key == key) + return obj; return NULL; Quoting Corey Minyard:: @@ -86,7 +97,7 @@ Quoting Corey Minyard:: 2) Insertion algorithm ---------------------- -We need to make sure a reader cannot read the new 'obj->obj_next' value +We need to make sure a reader cannot read the new 'obj->obj_node.next' value and previous value of 'obj->key'. Otherwise, an item could be deleted from a chain, and inserted into another chain. If new chain was empty before the move, 'next' pointer is NULL, and lockless reader can not @@ -129,8 +140,7 @@ very very fast (before the end of RCU grace period) Avoiding extra smp_rmb() ======================== -With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup() -and extra _release() in insert function. +With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup(). For example, if we choose to store the slot number as the 'nulls' end-of-list marker for each slot of the hash table, we can detect @@ -142,6 +152,9 @@ the beginning. If the object was moved to the same chain, then the reader doesn't care: It might occasionally scan the list again without harm. +Note that using hlist_nulls means the type of 'obj_node' field of +'struct object' becomes 'struct hlist_nulls_node'. + 1) lookup algorithm ------------------- @@ -151,7 +164,7 @@ scan the list again without harm. head = &table[slot]; begin: rcu_read_lock(); - hlist_nulls_for_each_entry_rcu(obj, node, head, member) { + hlist_nulls_for_each_entry_rcu(obj, node, head, obj_node) { if (obj->key == key) { if (!try_get_ref(obj)) { // might fail for free objects rcu_read_unlock(); @@ -182,6 +195,9 @@ scan the list again without harm. 2) Insert algorithm ------------------- +Same to the above one, but uses hlist_nulls_add_head_rcu() instead of +hlist_add_head_rcu(). + :: /* diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst index e488c8e557a9..60ce02475142 100644 --- a/Documentation/RCU/whatisRCU.rst +++ b/Documentation/RCU/whatisRCU.rst @@ -59,8 +59,8 @@ experiment with should focus on Section 2. People who prefer to start with example uses should focus on Sections 3 and 4. People who need to understand the RCU implementation should focus on Section 5, then dive into the kernel source code. People who reason best by analogy should -focus on Section 6. Section 7 serves as an index to the docbook API -documentation, and Section 8 is the traditional answer key. +focus on Section 6 and 7. Section 8 serves as an index to the docbook +API documentation, and Section 9 is the traditional answer key. So, start with the section that makes the most sense to you and your preferred method of learning. If you need to know everything about diff --git a/Documentation/accel/qaic/qaic.rst b/Documentation/accel/qaic/qaic.rst index 72a70ab6e3a8..c88502383136 100644 --- a/Documentation/accel/qaic/qaic.rst +++ b/Documentation/accel/qaic/qaic.rst @@ -123,6 +123,16 @@ DRM_IOCTL_QAIC_PART_DEV AIC100 device and can be used for limiting a process to some subset of resources. +DRM_IOCTL_QAIC_DETACH_SLICE_BO + This IOCTL allows userspace to remove the slicing information from a BO that + was originally provided by a call to DRM_IOCTL_QAIC_ATTACH_SLICE_BO. This + is the inverse of DRM_IOCTL_QAIC_ATTACH_SLICE_BO. The BO must be idle for + DRM_IOCTL_QAIC_DETACH_SLICE_BO to be called. After a successful detach slice + operation the BO may have new slicing information attached with a new call + to DRM_IOCTL_QAIC_ATTACH_SLICE_BO. After detach slice, the BO cannot be + executed until after a new attach slice operation. Combining attach slice + and detach slice calls allows userspace to use a BO with multiple workloads. + Userspace Client Isolation ========================== diff --git a/Documentation/accounting/psi.rst b/Documentation/accounting/psi.rst index df6062eb3abb..d455db3e5808 100644 --- a/Documentation/accounting/psi.rst +++ b/Documentation/accounting/psi.rst @@ -178,7 +178,7 @@ Userspace monitor usage example Cgroup2 interface ================= -In a system with a CONFIG_CGROUP=y kernel and the cgroup2 filesystem +In a system with a CONFIG_CGROUPS=y kernel and the cgroup2 filesystem mounted, pressure stall information is also tracked for tasks grouped into cgroups. Each subdirectory in the cgroupfs mountpoint contains cpu.pressure, memory.pressure, and io.pressure files; the format is diff --git a/Documentation/admin-guide/cgroup-v1/memcg_test.rst b/Documentation/admin-guide/cgroup-v1/memcg_test.rst index a402359abb99..1f128458ddea 100644 --- a/Documentation/admin-guide/cgroup-v1/memcg_test.rst +++ b/Documentation/admin-guide/cgroup-v1/memcg_test.rst @@ -62,7 +62,7 @@ Please note that implementation details can be changed. At cancel(), simply usage -= PAGE_SIZE. -Under below explanation, we assume CONFIG_MEM_RES_CTRL_SWAP=y. +Under below explanation, we assume CONFIG_SWAP=y. 4. Anonymous ============ diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst index fabaad3fd9c2..ca7d9402f6be 100644 --- a/Documentation/admin-guide/cgroup-v1/memory.rst +++ b/Documentation/admin-guide/cgroup-v1/memory.rst @@ -92,8 +92,13 @@ Brief summary of control files. memory.oom_control set/show oom controls. memory.numa_stat show the number of memory usage per numa node - memory.kmem.limit_in_bytes This knob is deprecated and writing to - it will return -ENOTSUPP. + memory.kmem.limit_in_bytes Deprecated knob to set and read the kernel + memory hard limit. Kernel hard limit is not + supported since 5.16. Writing any value to + do file will not have any effect same as if + nokmem kernel parameter was specified. + Kernel memory is still charged and reported + by memory.kmem.usage_in_bytes. memory.kmem.usage_in_bytes show current kernel memory allocation memory.kmem.failcnt show the number of kernel memory usage hits limits @@ -197,11 +202,11 @@ are not accounted. We just account pages under usual VM management. RSS pages are accounted at page_fault unless they've already been accounted for earlier. A file page will be accounted for as Page Cache when it's -inserted into inode (radix-tree). While it's mapped into the page tables of +inserted into inode (xarray). While it's mapped into the page tables of processes, duplicate accounting is carefully avoided. An RSS page is unaccounted when it's fully unmapped. A PageCache page is -unaccounted when it's removed from radix-tree. Even if RSS pages are fully +unaccounted when it's removed from xarray. Even if RSS pages are fully unmapped (by kswapd), they may exist as SwapCache in the system until they are really freed. Such SwapCaches are also accounted. A swapped-in page is accounted after adding into swapcache. @@ -546,6 +551,7 @@ memory.stat file includes following statistics: event happens each time a page is unaccounted from the cgroup. swap # of bytes of swap usage + swapcached # of bytes of swap cached in memory dirty # of bytes that are waiting to get written back to the disk. writeback # of bytes of file/anon cache that are queued for syncing to disk. @@ -909,7 +915,7 @@ experiences some pressure. In this situation, only group C will receive the notification, i.e. groups A and B will not receive it. This is done to avoid excessive "broadcasting" of messages, which disturbs the system and which is especially bad if we are low on memory or thrashing. Group B, will receive -notification only if there are no event listers for group C. +notification only if there are no event listeners for group C. There are three optional modes that specify different propagation behavior: diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 4ef890191196..3f85254f3cef 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -210,6 +210,35 @@ cgroup v2 currently supports the following mount options. relying on the original semantics (e.g. specifying bogusly high 'bypass' protection values at higher tree levels). + memory_hugetlb_accounting + Count HugeTLB memory usage towards the cgroup's overall + memory usage for the memory controller (for the purpose of + statistics reporting and memory protetion). This is a new + behavior that could regress existing setups, so it must be + explicitly opted in with this mount option. + + A few caveats to keep in mind: + + * There is no HugeTLB pool management involved in the memory + controller. The pre-allocated pool does not belong to anyone. + Specifically, when a new HugeTLB folio is allocated to + the pool, it is not accounted for from the perspective of the + memory controller. It is only charged to a cgroup when it is + actually used (for e.g at page fault time). Host memory + overcommit management has to consider this when configuring + hard limits. In general, HugeTLB pool management should be + done via other mechanisms (such as the HugeTLB controller). + * Failure to charge a HugeTLB folio to the memory controller + results in SIGBUS. This could happen even if the HugeTLB pool + still has pages available (but the cgroup limit is hit and + reclaim attempt fails). + * Charging HugeTLB memory towards the memory controller affects + memory protection and reclaim dynamics. Any userspace tuning + (of low, min limits for e.g) needs to take this into account. + * HugeTLB pages utilized while this option is not selected + will not be tracked by the memory controller (even if cgroup + v2 is remounted later on). + Organizing Processes and Threads -------------------------------- @@ -364,6 +393,13 @@ constraint, a threaded controller must be able to handle competition between threads in a non-leaf cgroup and its child cgroups. Each threaded controller defines how such competitions are handled. +Currently, the following controllers are threaded and can be enabled +in a threaded cgroup:: + +- cpu +- cpuset +- perf_event +- pids [Un]populated Notification -------------------------- @@ -1045,7 +1081,7 @@ All time durations are in microseconds. - user_usec - system_usec - and the following three when the controller is enabled: + and the following five when the controller is enabled: - nr_periods - nr_throttled @@ -1532,6 +1568,15 @@ PAGE_SIZE multiple when read back. collapsing an existing range of pages. This counter is not present when CONFIG_TRANSPARENT_HUGEPAGE is not set. + thp_swpout (npn) + Number of transparent hugepages which are swapout in one piece + without splitting. + + thp_swpout_fallback (npn) + Number of transparent hugepages which were split before swapout. + Usually because failed to allocate some continuous swap space + for the huge page. + memory.numa_stat A read-only nested-keyed file which exists on non-root cgroups. @@ -2023,7 +2068,7 @@ IO Priority ~~~~~~~~~~~ A single attribute controls the behavior of the I/O priority cgroup policy, -namely the blkio.prio.class attribute. The following values are accepted for +namely the io.prio.class attribute. The following values are accepted for that attribute: no-change @@ -2052,9 +2097,11 @@ The following numerical values are associated with the I/O priority policies: +----------------+---+ | no-change | 0 | +----------------+---+ -| rt-to-be | 2 | +| promote-to-rt | 1 | +----------------+---+ -| all-to-idle | 3 | +| restrict-to-be | 2 | ++----------------+---+ +| idle | 3 | +----------------+---+ The numerical value that corresponds to each I/O priority class is as follows: @@ -2074,7 +2121,7 @@ The algorithm to set the I/O priority class for a request is as follows: - If I/O priority class policy is promote-to-rt, change the request I/O priority class to IOPRIO_CLASS_RT and change the request I/O priority level to 4. -- If I/O priorityt class is not promote-to-rt, translate the I/O priority +- If I/O priority class policy is not promote-to-rt, translate the I/O priority class policy into a number, then change the request I/O priority class into the maximum of the I/O priority class policy number and the numerical I/O priority class. @@ -2226,6 +2273,49 @@ Cpuset Interface Files Its value will be affected by memory nodes hotplug events. + cpuset.cpus.exclusive + A read-write multiple values file which exists on non-root + cpuset-enabled cgroups. + + It lists all the exclusive CPUs that are allowed to be used + to create a new cpuset partition. Its value is not used + unless the cgroup becomes a valid partition root. See the + "cpuset.cpus.partition" section below for a description of what + a cpuset partition is. + + When the cgroup becomes a partition root, the actual exclusive + CPUs that are allocated to that partition are listed in + "cpuset.cpus.exclusive.effective" which may be different + from "cpuset.cpus.exclusive". If "cpuset.cpus.exclusive" + has previously been set, "cpuset.cpus.exclusive.effective" + is always a subset of it. + + Users can manually set it to a value that is different from + "cpuset.cpus". The only constraint in setting it is that the + list of CPUs must be exclusive with respect to its sibling. + + For a parent cgroup, any one of its exclusive CPUs can only + be distributed to at most one of its child cgroups. Having an + exclusive CPU appearing in two or more of its child cgroups is + not allowed (the exclusivity rule). A value that violates the + exclusivity rule will be rejected with a write error. + + The root cgroup is a partition root and all its available CPUs + are in its exclusive CPU set. + + cpuset.cpus.exclusive.effective + A read-only multiple values file which exists on all non-root + cpuset-enabled cgroups. + + This file shows the effective set of exclusive CPUs that + can be used to create a partition root. The content of this + file will always be a subset of "cpuset.cpus" and its parent's + "cpuset.cpus.exclusive.effective" if its parent is not the root + cgroup. It will also be a subset of "cpuset.cpus.exclusive" + if it is set. If "cpuset.cpus.exclusive" is not set, it is + treated to have an implicit value of "cpuset.cpus" in the + formation of local partition. + cpuset.cpus.partition A read-write single value file which exists on non-root cpuset-enabled cgroups. This flag is owned by the parent cgroup @@ -2239,26 +2329,41 @@ Cpuset Interface Files "isolated" Partition root without load balancing ========== ===================================== - The root cgroup is always a partition root and its state - cannot be changed. All other non-root cgroups start out as - "member". + A cpuset partition is a collection of cpuset-enabled cgroups with + a partition root at the top of the hierarchy and its descendants + except those that are separate partition roots themselves and + their descendants. A partition has exclusive access to the + set of exclusive CPUs allocated to it. Other cgroups outside + of that partition cannot use any CPUs in that set. + + There are two types of partitions - local and remote. A local + partition is one whose parent cgroup is also a valid partition + root. A remote partition is one whose parent cgroup is not a + valid partition root itself. Writing to "cpuset.cpus.exclusive" + is optional for the creation of a local partition as its + "cpuset.cpus.exclusive" file will assume an implicit value that + is the same as "cpuset.cpus" if it is not set. Writing the + proper "cpuset.cpus.exclusive" values down the cgroup hierarchy + before the target partition root is mandatory for the creation + of a remote partition. + + Currently, a remote partition cannot be created under a local + partition. All the ancestors of a remote partition root except + the root cgroup cannot be a partition root. + + The root cgroup is always a partition root and its state cannot + be changed. All other non-root cgroups start out as "member". When set to "root", the current cgroup is the root of a new - partition or scheduling domain that comprises itself and all - its descendants except those that are separate partition roots - themselves and their descendants. + partition or scheduling domain. The set of exclusive CPUs is + determined by the value of its "cpuset.cpus.exclusive.effective". - When set to "isolated", the CPUs in that partition root will + When set to "isolated", the CPUs in that partition will be in an isolated state without any load balancing from the scheduler. Tasks placed in such a partition with multiple CPUs should be carefully distributed and bound to each of the individual CPUs for optimal performance. - The value shown in "cpuset.cpus.effective" of a partition root - is the CPUs that the partition root can dedicate to a potential - new child partition root. The new child subtracts available - CPUs from its parent "cpuset.cpus.effective". - A partition root ("root" or "isolated") can be in one of the two possible states - valid or invalid. An invalid partition root is in a degraded state where some state information may @@ -2281,37 +2386,33 @@ Cpuset Interface Files In the case of an invalid partition root, a descriptive string on why the partition is invalid is included within parentheses. - For a partition root to become valid, the following conditions + For a local partition root to be valid, the following conditions must be met. - 1) The "cpuset.cpus" is exclusive with its siblings , i.e. they - are not shared by any of its siblings (exclusivity rule). - 2) The parent cgroup is a valid partition root. - 3) The "cpuset.cpus" is not empty and must contain at least - one of the CPUs from parent's "cpuset.cpus", i.e. they overlap. - 4) The "cpuset.cpus.effective" cannot be empty unless there is + 1) The parent cgroup is a valid partition root. + 2) The "cpuset.cpus.exclusive.effective" file cannot be empty, + though it may contain offline CPUs. + 3) The "cpuset.cpus.effective" cannot be empty unless there is no task associated with this partition. - External events like hotplug or changes to "cpuset.cpus" can - cause a valid partition root to become invalid and vice versa. - Note that a task cannot be moved to a cgroup with empty - "cpuset.cpus.effective". + For a remote partition root to be valid, all the above conditions + except the first one must be met. - For a valid partition root with the sibling cpu exclusivity - rule enabled, changes made to "cpuset.cpus" that violate the - exclusivity rule will invalidate the partition as well as its - sibling partitions with conflicting cpuset.cpus values. So - care must be taking in changing "cpuset.cpus". + External events like hotplug or changes to "cpuset.cpus" or + "cpuset.cpus.exclusive" can cause a valid partition root to + become invalid and vice versa. Note that a task cannot be + moved to a cgroup with empty "cpuset.cpus.effective". A valid non-root parent partition may distribute out all its CPUs - to its child partitions when there is no task associated with it. + to its child local partitions when there is no task associated + with it. - Care must be taken to change a valid partition root to - "member" as all its child partitions, if present, will become + Care must be taken to change a valid partition root to "member" + as all its child local partitions, if present, will become invalid causing disruption to tasks running in those child partitions. These inactivated partitions could be recovered if their parent is switched back to a partition root with a proper - set of "cpuset.cpus". + value in "cpuset.cpus" or "cpuset.cpus.exclusive". Poll and inotify events are triggered whenever the state of "cpuset.cpus.partition" changes. That includes changes caused @@ -2321,6 +2422,11 @@ Cpuset Interface Files to "cpuset.cpus.partition" without the need to do continuous polling. + A user can pre-configure certain CPUs to an isolated state + with load balancing disabled at boot time with the "isolcpus" + kernel boot command line option. If those CPUs are to be put + into a partition, they have to be used in an isolated partition. + Device controller ----------------- diff --git a/Documentation/admin-guide/devices.txt b/Documentation/admin-guide/devices.txt index 06c525e01ea5..839054923530 100644 --- a/Documentation/admin-guide/devices.txt +++ b/Documentation/admin-guide/devices.txt @@ -2691,18 +2691,9 @@ 45 = /dev/ttyMM1 Marvell MPSC - port 1 (obsolete unused) 46 = /dev/ttyCPM0 PPC CPM (SCC or SMC) - port 0 ... - 47 = /dev/ttyCPM5 PPC CPM (SCC or SMC) - port 5 - 50 = /dev/ttyIOC0 Altix serial card - ... - 81 = /dev/ttyIOC31 Altix serial card + 51 = /dev/ttyCPM5 PPC CPM (SCC or SMC) - port 5 82 = /dev/ttyVR0 NEC VR4100 series SIU 83 = /dev/ttyVR1 NEC VR4100 series DSIU - 84 = /dev/ttyIOC84 Altix ioc4 serial card - ... - 115 = /dev/ttyIOC115 Altix ioc4 serial card - 116 = /dev/ttySIOC0 Altix ioc3 serial card - ... - 147 = /dev/ttySIOC31 Altix ioc3 serial card 148 = /dev/ttyPSC0 PPC PSC - port 0 ... 153 = /dev/ttyPSC5 PPC PSC - port 5 @@ -2761,10 +2752,7 @@ 43 = /dev/ttycusmx2 Callout device for ttySMX2 46 = /dev/cucpm0 Callout device for ttyCPM0 ... - 49 = /dev/cucpm5 Callout device for ttyCPM5 - 50 = /dev/cuioc40 Callout device for ttyIOC40 - ... - 81 = /dev/cuioc431 Callout device for ttyIOC431 + 51 = /dev/cucpm5 Callout device for ttyCPM5 82 = /dev/cuvr0 Callout device for ttyVR0 83 = /dev/cuvr1 Callout device for ttyVR1 diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst index 8dc668cc1216..0c526dac8428 100644 --- a/Documentation/admin-guide/dynamic-debug-howto.rst +++ b/Documentation/admin-guide/dynamic-debug-howto.rst @@ -216,13 +216,14 @@ The flags are:: t Include thread ID, or <intr> m Include module name f Include the function name + s Include the source file name l Include line number For ``print_hex_dump_debug()`` and ``print_hex_dump_bytes()``, only the ``p`` flag has meaning, other flags are ignored. -Note the regexp ``^[-+=][flmpt_]+$`` matches a flags specification. -To clear all flags at once, use ``=_`` or ``-flmpt``. +Note the regexp ``^[-+=][fslmpt_]+$`` matches a flags specification. +To clear all flags at once, use ``=_`` or ``-fslmpt``. Debug messages during Boot Process @@ -258,7 +259,7 @@ Debug Messages at Module Initialization Time When ``modprobe foo`` is called, modprobe scans ``/proc/cmdline`` for ``foo.params``, strips ``foo.``, and passes them to the kernel along with -params given in modprobe args or ``/etc/modprob.d/*.conf`` files, +params given in modprobe args or ``/etc/modprobe.d/*.conf`` files, in the following order: 1. parameters given via ``/etc/modprobe.d/*.conf``:: diff --git a/Documentation/admin-guide/efi-stub.rst b/Documentation/admin-guide/efi-stub.rst index b24e7c40d832..090f3a185e18 100644 --- a/Documentation/admin-guide/efi-stub.rst +++ b/Documentation/admin-guide/efi-stub.rst @@ -15,7 +15,7 @@ between architectures is in drivers/firmware/efi/libstub. For arm64, there is no compressed kernel support, so the Image itself masquerades as a PE/COFF image and the EFI stub is linked into the -kernel. The arm64 EFI stub lives in arch/arm64/kernel/efi-entry.S +kernel. The arm64 EFI stub lives in drivers/firmware/efi/libstub/arm64.c and drivers/firmware/efi/libstub/arm64-stub.c. By using the EFI boot stub it's possible to boot a Linux kernel diff --git a/Documentation/admin-guide/hw-vuln/gather_data_sampling.rst b/Documentation/admin-guide/hw-vuln/gather_data_sampling.rst new file mode 100644 index 000000000000..264bfa937f7d --- /dev/null +++ b/Documentation/admin-guide/hw-vuln/gather_data_sampling.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: GPL-2.0 + +GDS - Gather Data Sampling +========================== + +Gather Data Sampling is a hardware vulnerability which allows unprivileged +speculative access to data which was previously stored in vector registers. + +Problem +------- +When a gather instruction performs loads from memory, different data elements +are merged into the destination vector register. However, when a gather +instruction that is transiently executed encounters a fault, stale data from +architectural or internal vector registers may get transiently forwarded to the +destination vector register instead. This will allow a malicious attacker to +infer stale data using typical side channel techniques like cache timing +attacks. GDS is a purely sampling-based attack. + +The attacker uses gather instructions to infer the stale vector register data. +The victim does not need to do anything special other than use the vector +registers. The victim does not need to use gather instructions to be +vulnerable. + +Because the buffers are shared between Hyper-Threads cross Hyper-Thread attacks +are possible. + +Attack scenarios +---------------- +Without mitigation, GDS can infer stale data across virtually all +permission boundaries: + + Non-enclaves can infer SGX enclave data + Userspace can infer kernel data + Guests can infer data from hosts + Guest can infer guest from other guests + Users can infer data from other users + +Because of this, it is important to ensure that the mitigation stays enabled in +lower-privilege contexts like guests and when running outside SGX enclaves. + +The hardware enforces the mitigation for SGX. Likewise, VMMs should ensure +that guests are not allowed to disable the GDS mitigation. If a host erred and +allowed this, a guest could theoretically disable GDS mitigation, mount an +attack, and re-enable it. + +Mitigation mechanism +-------------------- +This issue is mitigated in microcode. The microcode defines the following new +bits: + + ================================ === ============================ + IA32_ARCH_CAPABILITIES[GDS_CTRL] R/O Enumerates GDS vulnerability + and mitigation support. + IA32_ARCH_CAPABILITIES[GDS_NO] R/O Processor is not vulnerable. + IA32_MCU_OPT_CTRL[GDS_MITG_DIS] R/W Disables the mitigation + 0 by default. + IA32_MCU_OPT_CTRL[GDS_MITG_LOCK] R/W Locks GDS_MITG_DIS=0. Writes + to GDS_MITG_DIS are ignored + Can't be cleared once set. + ================================ === ============================ + +GDS can also be mitigated on systems that don't have updated microcode by +disabling AVX. This can be done by setting gather_data_sampling="force" or +"clearcpuid=avx" on the kernel command-line. + +If used, these options will disable AVX use by turning off XSAVE YMM support. +However, the processor will still enumerate AVX support. Userspace that +does not follow proper AVX enumeration to check both AVX *and* XSAVE YMM +support will break. + +Mitigation control on the kernel command line +--------------------------------------------- +The mitigation can be disabled by setting "gather_data_sampling=off" or +"mitigations=off" on the kernel command line. Not specifying either will default +to the mitigation being enabled. Specifying "gather_data_sampling=force" will +use the microcode mitigation when available or disable AVX on affected systems +where the microcode hasn't been updated to include the mitigation. + +GDS System Information +------------------------ +The kernel provides vulnerability status information through sysfs. For +GDS this can be accessed by the following sysfs file: + +/sys/devices/system/cpu/vulnerabilities/gather_data_sampling + +The possible values contained in this file are: + + ============================== ============================================= + Not affected Processor not vulnerable. + Vulnerable Processor vulnerable and mitigation disabled. + Vulnerable: No microcode Processor vulnerable and microcode is missing + mitigation. + Mitigation: AVX disabled, + no microcode Processor is vulnerable and microcode is missing + mitigation. AVX disabled as mitigation. + Mitigation: Microcode Processor is vulnerable and mitigation is in + effect. + Mitigation: Microcode (locked) Processor is vulnerable and mitigation is in + effect and cannot be disabled. + Unknown: Dependent on + hypervisor status Running on a virtual guest processor that is + affected but with no way to know if host + processor is mitigated or vulnerable. + ============================== ============================================= + +GDS Default mitigation +---------------------- +The updated microcode will enable the mitigation by default. The kernel's +default action is to leave the mitigation enabled. diff --git a/Documentation/admin-guide/hw-vuln/index.rst b/Documentation/admin-guide/hw-vuln/index.rst index e0614760a99e..de99caabf65a 100644 --- a/Documentation/admin-guide/hw-vuln/index.rst +++ b/Documentation/admin-guide/hw-vuln/index.rst @@ -13,9 +13,11 @@ are configurable at compile, boot or run time. l1tf mds tsx_async_abort - multihit.rst - special-register-buffer-data-sampling.rst - core-scheduling.rst - l1d_flush.rst - processor_mmio_stale_data.rst - cross-thread-rsb.rst + multihit + special-register-buffer-data-sampling + core-scheduling + l1d_flush + processor_mmio_stale_data + cross-thread-rsb + srso + gather_data_sampling diff --git a/Documentation/admin-guide/hw-vuln/mds.rst b/Documentation/admin-guide/hw-vuln/mds.rst index 48ca0bd85604..48c7b0b72aed 100644 --- a/Documentation/admin-guide/hw-vuln/mds.rst +++ b/Documentation/admin-guide/hw-vuln/mds.rst @@ -102,9 +102,19 @@ The possible values in this file are: * - 'Vulnerable' - The processor is vulnerable, but no mitigation enabled * - 'Vulnerable: Clear CPU buffers attempted, no microcode' - - The processor is vulnerable but microcode is not updated. - - The mitigation is enabled on a best effort basis. See :ref:`vmwerv` + - The processor is vulnerable but microcode is not updated. The + mitigation is enabled on a best effort basis. + + If the processor is vulnerable but the availability of the microcode + based mitigation mechanism is not advertised via CPUID, the kernel + selects a best effort mitigation mode. This mode invokes the mitigation + instructions without a guarantee that they clear the CPU buffers. + + This is done to address virtualization scenarios where the host has the + microcode update applied, but the hypervisor is not yet updated to + expose the CPUID to the guest. If the host has updated microcode the + protection takes effect; otherwise a few CPU cycles are wasted + pointlessly. * - 'Mitigation: Clear CPU buffers' - The processor is vulnerable and the CPU buffer clearing mitigation is enabled. @@ -119,24 +129,6 @@ to the above information: 'SMT Host state unknown' Kernel runs in a VM, Host SMT state unknown ======================== ============================================ -.. _vmwerv: - -Best effort mitigation mode -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - If the processor is vulnerable, but the availability of the microcode based - mitigation mechanism is not advertised via CPUID the kernel selects a best - effort mitigation mode. This mode invokes the mitigation instructions - without a guarantee that they clear the CPU buffers. - - This is done to address virtualization scenarios where the host has the - microcode update applied, but the hypervisor is not yet updated to expose - the CPUID to the guest. If the host has updated microcode the protection - takes effect otherwise a few cpu cycles are wasted pointlessly. - - The state in the mds sysfs file reflects this situation accordingly. - - Mitigation mechanism ------------------------- diff --git a/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst b/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst index c98fd11907cc..1302fd1b55e8 100644 --- a/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst +++ b/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst @@ -225,8 +225,19 @@ The possible values in this file are: * - 'Vulnerable' - The processor is vulnerable, but no mitigation enabled * - 'Vulnerable: Clear CPU buffers attempted, no microcode' - - The processor is vulnerable, but microcode is not updated. The + - The processor is vulnerable but microcode is not updated. The mitigation is enabled on a best effort basis. + + If the processor is vulnerable but the availability of the microcode + based mitigation mechanism is not advertised via CPUID, the kernel + selects a best effort mitigation mode. This mode invokes the mitigation + instructions without a guarantee that they clear the CPU buffers. + + This is done to address virtualization scenarios where the host has the + microcode update applied, but the hypervisor is not yet updated to + expose the CPUID to the guest. If the host has updated microcode the + protection takes effect; otherwise a few CPU cycles are wasted + pointlessly. * - 'Mitigation: Clear CPU buffers' - The processor is vulnerable and the CPU buffer clearing mitigation is enabled. diff --git a/Documentation/admin-guide/hw-vuln/spectre.rst b/Documentation/admin-guide/hw-vuln/spectre.rst index 4d186f599d90..32a8893e5617 100644 --- a/Documentation/admin-guide/hw-vuln/spectre.rst +++ b/Documentation/admin-guide/hw-vuln/spectre.rst @@ -484,11 +484,14 @@ Spectre variant 2 Systems which support enhanced IBRS (eIBRS) enable IBRS protection once at boot, by setting the IBRS bit, and they're automatically protected against - Spectre v2 variant attacks, including cross-thread branch target injections - on SMT systems (STIBP). In other words, eIBRS enables STIBP too. + Spectre v2 variant attacks. - Legacy IBRS systems clear the IBRS bit on exit to userspace and - therefore explicitly enable STIBP for that + On Intel's enhanced IBRS systems, this includes cross-thread branch target + injections on SMT systems (STIBP). In other words, Intel eIBRS enables + STIBP, too. + + AMD Automatic IBRS does not protect userspace, and Legacy IBRS systems clear + the IBRS bit on exit to userspace, therefore both explicitly enable STIBP. The retpoline mitigation is turned on by default on vulnerable CPUs. It can be forced on or off by the administrator diff --git a/Documentation/admin-guide/hw-vuln/srso.rst b/Documentation/admin-guide/hw-vuln/srso.rst new file mode 100644 index 000000000000..e715bfc09879 --- /dev/null +++ b/Documentation/admin-guide/hw-vuln/srso.rst @@ -0,0 +1,160 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Speculative Return Stack Overflow (SRSO) +======================================== + +This is a mitigation for the speculative return stack overflow (SRSO) +vulnerability found on AMD processors. The mechanism is by now the well +known scenario of poisoning CPU functional units - the Branch Target +Buffer (BTB) and Return Address Predictor (RAP) in this case - and then +tricking the elevated privilege domain (the kernel) into leaking +sensitive data. + +AMD CPUs predict RET instructions using a Return Address Predictor (aka +Return Address Stack/Return Stack Buffer). In some cases, a non-architectural +CALL instruction (i.e., an instruction predicted to be a CALL but is +not actually a CALL) can create an entry in the RAP which may be used +to predict the target of a subsequent RET instruction. + +The specific circumstances that lead to this varies by microarchitecture +but the concern is that an attacker can mis-train the CPU BTB to predict +non-architectural CALL instructions in kernel space and use this to +control the speculative target of a subsequent kernel RET, potentially +leading to information disclosure via a speculative side-channel. + +The issue is tracked under CVE-2023-20569. + +Affected processors +------------------- + +AMD Zen, generations 1-4. That is, all families 0x17 and 0x19. Older +processors have not been investigated. + +System information and options +------------------------------ + +First of all, it is required that the latest microcode be loaded for +mitigations to be effective. + +The sysfs file showing SRSO mitigation status is: + + /sys/devices/system/cpu/vulnerabilities/spec_rstack_overflow + +The possible values in this file are: + + * 'Not affected': + + The processor is not vulnerable + +* 'Vulnerable': + + The processor is vulnerable and no mitigations have been applied. + + * 'Vulnerable: No microcode': + + The processor is vulnerable, no microcode extending IBPB + functionality to address the vulnerability has been applied. + + * 'Vulnerable: Safe RET, no microcode': + + The "Safe RET" mitigation (see below) has been applied to protect the + kernel, but the IBPB-extending microcode has not been applied. User + space tasks may still be vulnerable. + + * 'Vulnerable: Microcode, no safe RET': + + Extended IBPB functionality microcode patch has been applied. It does + not address User->Kernel and Guest->Host transitions protection but it + does address User->User and VM->VM attack vectors. + + Note that User->User mitigation is controlled by how the IBPB aspect in + the Spectre v2 mitigation is selected: + + * conditional IBPB: + + where each process can select whether it needs an IBPB issued + around it PR_SPEC_DISABLE/_ENABLE etc, see :doc:`spectre` + + * strict: + + i.e., always on - by supplying spectre_v2_user=on on the kernel + command line + + (spec_rstack_overflow=microcode) + + * 'Mitigation: Safe RET': + + Combined microcode/software mitigation. It complements the + extended IBPB microcode patch functionality by addressing + User->Kernel and Guest->Host transitions protection. + + Selected by default or by spec_rstack_overflow=safe-ret + + * 'Mitigation: IBPB': + + Similar protection as "safe RET" above but employs an IBPB barrier on + privilege domain crossings (User->Kernel, Guest->Host). + + (spec_rstack_overflow=ibpb) + + * 'Mitigation: IBPB on VMEXIT': + + Mitigation addressing the cloud provider scenario - the Guest->Host + transitions only. + + (spec_rstack_overflow=ibpb-vmexit) + + + +In order to exploit vulnerability, an attacker needs to: + + - gain local access on the machine + + - break kASLR + + - find gadgets in the running kernel in order to use them in the exploit + + - potentially create and pin an additional workload on the sibling + thread, depending on the microarchitecture (not necessary on fam 0x19) + + - run the exploit + +Considering the performance implications of each mitigation type, the +default one is 'Mitigation: safe RET' which should take care of most +attack vectors, including the local User->Kernel one. + +As always, the user is advised to keep her/his system up-to-date by +applying software updates regularly. + +The default setting will be reevaluated when needed and especially when +new attack vectors appear. + +As one can surmise, 'Mitigation: safe RET' does come at the cost of some +performance depending on the workload. If one trusts her/his userspace +and does not want to suffer the performance impact, one can always +disable the mitigation with spec_rstack_overflow=off. + +Similarly, 'Mitigation: IBPB' is another full mitigation type employing +an indrect branch prediction barrier after having applied the required +microcode patch for one's system. This mitigation comes also at +a performance cost. + +Mitigation: Safe RET +-------------------- + +The mitigation works by ensuring all RET instructions speculate to +a controlled location, similar to how speculation is controlled in the +retpoline sequence. To accomplish this, the __x86_return_thunk forces +the CPU to mispredict every function return using a 'safe return' +sequence. + +To ensure the safety of this mitigation, the kernel must ensure that the +safe return sequence is itself free from attacker interference. In Zen3 +and Zen4, this is accomplished by creating a BTB alias between the +untraining function srso_alias_untrain_ret() and the safe return +function srso_alias_safe_ret() which results in evicting a potentially +poisoned BTB entry and using that safe one for all function returns. + +In older Zen1 and Zen2, this is accomplished using a reinterpretation +technique similar to Retbleed one: srso_untrain_ret() and +srso_safe_ret(). diff --git a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst index 014167ef8dd1..444f84e22a91 100644 --- a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst +++ b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst @@ -98,7 +98,19 @@ The possible values in this file are: * - 'Vulnerable' - The CPU is affected by this vulnerability and the microcode and kernel mitigation are not applied. * - 'Vulnerable: Clear CPU buffers attempted, no microcode' - - The system tries to clear the buffers but the microcode might not support the operation. + - The processor is vulnerable but microcode is not updated. The + mitigation is enabled on a best effort basis. + + If the processor is vulnerable but the availability of the microcode + based mitigation mechanism is not advertised via CPUID, the kernel + selects a best effort mitigation mode. This mode invokes the mitigation + instructions without a guarantee that they clear the CPU buffers. + + This is done to address virtualization scenarios where the host has the + microcode update applied, but the hypervisor is not yet updated to + expose the CPUID to the guest. If the host has updated microcode the + protection takes effect; otherwise a few CPU cycles are wasted + pointlessly. * - 'Mitigation: Clear CPU buffers' - The microcode has been updated to clear the buffers. TSX is still enabled. * - 'Mitigation: TSX disabled' @@ -106,25 +118,6 @@ The possible values in this file are: * - 'Not affected' - The CPU is not affected by this issue. -.. _ucode_needed: - -Best effort mitigation mode -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If the processor is vulnerable, but the availability of the microcode-based -mitigation mechanism is not advertised via CPUID the kernel selects a best -effort mitigation mode. This mode invokes the mitigation instructions -without a guarantee that they clear the CPU buffers. - -This is done to address virtualization scenarios where the host has the -microcode update applied, but the hypervisor is not yet updated to expose the -CPUID to the guest. If the host has updated microcode the protection takes -effect; otherwise a few CPU cycles are wasted pointlessly. - -The state in the tsx_async_abort sysfs file reflects this situation -accordingly. - - Mitigation mechanism -------------------- diff --git a/Documentation/admin-guide/kdump/kdump.rst b/Documentation/admin-guide/kdump/kdump.rst index a748e7eb4429..5762e7477a0c 100644 --- a/Documentation/admin-guide/kdump/kdump.rst +++ b/Documentation/admin-guide/kdump/kdump.rst @@ -17,7 +17,7 @@ You can use common commands, such as cp, scp or makedumpfile to copy the memory image to a dump file on the local disk, or across the network to a remote system. -Kdump and kexec are currently supported on the x86, x86_64, ppc64, ia64, +Kdump and kexec are currently supported on the x86, x86_64, ppc64, s390x, arm and arm64 architectures. When the system kernel boots, it reserves a small section of memory for @@ -113,7 +113,7 @@ There are two possible methods of using Kdump. 2) Or use the system kernel binary itself as dump-capture kernel and there is no need to build a separate dump-capture kernel. This is possible only with the architectures which support a relocatable kernel. As - of today, i386, x86_64, ppc64, ia64, arm and arm64 architectures support + of today, i386, x86_64, ppc64, arm and arm64 architectures support relocatable kernel. Building a relocatable kernel is advantageous from the point of view that @@ -236,24 +236,6 @@ Dump-capture kernel config options (Arch Dependent, ppc64) Make and install the kernel and its modules. -Dump-capture kernel config options (Arch Dependent, ia64) ----------------------------------------------------------- - -- No specific options are required to create a dump-capture kernel - for ia64, other than those specified in the arch independent section - above. This means that it is possible to use the system kernel - as a dump-capture kernel if desired. - - The crashkernel region can be automatically placed by the system - kernel at runtime. This is done by specifying the base address as 0, - or omitting it all together:: - - crashkernel=256M@0 - - or:: - - crashkernel=256M - Dump-capture kernel config options (Arch Dependent, arm) ---------------------------------------------------------- @@ -348,11 +330,6 @@ Boot into System Kernel On ppc64, use "crashkernel=128M@32M". - On ia64, 256M@256M is a generous value that typically works. - The region may be automatically placed on ia64, see the - dump-capture kernel config option notes above. - If use sparse memory, the size should be rounded to GRANULE boundaries. - On s390x, typically use "crashkernel=xxM". The value of xx is dependent on the memory consumption of the kdump system. In general this is not dependent on the memory size of the production system. @@ -383,10 +360,6 @@ For ppc64: - Use vmlinux -For ia64: - - - Use vmlinux or vmlinuz.gz - For s390x: - Use image or bzImage @@ -428,14 +401,10 @@ to load dump-capture kernel:: --initrd=<initrd-for-dump-capture-kernel> \ --append="root=<root-dev> <arch-specific-options>" -Please note, that --args-linux does not need to be specified for ia64. -It is planned to make this a no-op on that architecture, but for now -it should be omitted - Following are the arch specific command line options to be used while loading dump-capture kernel. -For i386, x86_64 and ia64: +For i386 and x86_64: "1 irqpoll nr_cpus=1 reset_devices" diff --git a/Documentation/admin-guide/kdump/vmcoreinfo.rst b/Documentation/admin-guide/kdump/vmcoreinfo.rst index c18d94fa6470..78e4d2e7ba14 100644 --- a/Documentation/admin-guide/kdump/vmcoreinfo.rst +++ b/Documentation/admin-guide/kdump/vmcoreinfo.rst @@ -141,8 +141,8 @@ nodemask_t The size of a nodemask_t type. Used to compute the number of online nodes. -(page, flags|_refcount|mapping|lru|_mapcount|private|compound_dtor|compound_order|compound_head) -------------------------------------------------------------------------------------------------- +(page, flags|_refcount|mapping|lru|_mapcount|private|compound_order|compound_head) +---------------------------------------------------------------------------------- User-space tools compute their values based on the offset of these variables. The variables are used when excluding unnecessary pages. @@ -325,8 +325,8 @@ NR_FREE_PAGES On linux-2.6.21 or later, the number of free pages is in vm_stat[NR_FREE_PAGES]. Used to get the number of free pages. -PG_lru|PG_private|PG_swapcache|PG_swapbacked|PG_slab|PG_hwpoision|PG_head_mask ------------------------------------------------------------------------------- +PG_lru|PG_private|PG_swapcache|PG_swapbacked|PG_slab|PG_hwpoision|PG_head_mask|PG_hugetlb +----------------------------------------------------------------------------------------- Page attributes. These flags are used to filter various unnecessary for dumping pages. @@ -338,12 +338,6 @@ More page attributes. These flags are used to filter various unnecessary for dumping pages. -HUGETLB_PAGE_DTOR ------------------ - -The HUGETLB_PAGE_DTOR flag denotes hugetlbfs pages. Makedumpfile -excludes these pages. - x86_64 ====== @@ -419,36 +413,6 @@ of a higher page table lookup overhead, and also consumes more page table space per process. Used to check whether PAE was enabled in the crash kernel when converting virtual addresses to physical addresses. -ia64 -==== - -pgdat_list|(pgdat_list, MAX_NUMNODES) -------------------------------------- - -pg_data_t array storing all NUMA nodes information. MAX_NUMNODES -indicates the number of the nodes. - -node_memblk|(node_memblk, NR_NODE_MEMBLKS) ------------------------------------------- - -List of node memory chunks. Filled when parsing the SRAT table to obtain -information about memory nodes. NR_NODE_MEMBLKS indicates the number of -node memory chunks. - -These values are used to compute the number of nodes the crashed kernel used. - -node_memblk_s|(node_memblk_s, start_paddr)|(node_memblk_s, size) ----------------------------------------------------------------- - -The size of a struct node_memblk_s and the offsets of the -node_memblk_s's members. Used to compute the number of nodes. - -PGTABLE_3|PGTABLE_4 -------------------- - -User-space tools need to know whether the crash kernel was in 3-level or -4-level paging mode. Used to distinguish the page table. - ARM64 ===== @@ -624,3 +588,9 @@ Used to get the correct ranges: * VMALLOC_START ~ VMALLOC_END : vmalloc() / ioremap() space. * VMEMMAP_START ~ VMEMMAP_END : vmemmap space, used for struct page array. * KERNEL_LINK_ADDR : start address of Kernel link and BPF + +va_kernel_pa_offset +------------------- + +Indicates the offset between the kernel virtual and physical mappings. +Used to translate virtual to physical addresses. diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index 1ba8f2a44aac..102937bc8443 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -80,7 +80,7 @@ The special case-tolerant group name "all" has a meaning of selecting all CPUs, so that "nohz_full=all" is the equivalent of "nohz_full=0-N". The semantics of "N" and "all" is supported on a level of bitmaps and holds for -all users of bitmap_parse(). +all users of bitmap_parselist(). This document may not be entirely up to date and comprehensive. The command "modinfo -p ${modulename}" shows a current list of all parameters of a loadable @@ -89,10 +89,11 @@ reveal their parameters in /sys/module/${modulename}/parameters/. Some of these parameters may be changed at runtime by the command ``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``. -The parameters listed below are only valid if certain kernel build options were -enabled and if respective hardware is present. The text in square brackets at -the beginning of each description states the restrictions within which a -parameter is applicable:: +The parameters listed below are only valid if certain kernel build options +were enabled and if respective hardware is present. This list should be kept +in alphabetical order. The text in square brackets at the beginning +of each description states the restrictions within which a parameter +is applicable:: ACPI ACPI support is enabled. AGP AGP (Accelerated Graphics Port) is enabled. @@ -127,9 +128,9 @@ parameter is applicable:: KGDB Kernel debugger support is enabled. KVM Kernel Virtual Machine support is enabled. LIBATA Libata driver is enabled - LP Printer support is enabled. LOONGARCH LoongArch architecture is enabled. LOOP Loopback device support is enabled. + LP Printer support is enabled. M68k M68k architecture is enabled. These options have more detailed description inside of Documentation/arch/m68k/kernel-options.rst. @@ -139,10 +140,9 @@ parameter is applicable:: MSI Message Signaled Interrupts (PCI). MTD MTD (Memory Technology Device) support is enabled. NET Appropriate network support is enabled. - NUMA NUMA support is enabled. NFS Appropriate NFS support is enabled. + NUMA NUMA support is enabled. OF Devicetree is enabled. - PV_OPS A paravirtualized kernel is enabled. PARISC The PA-RISC architecture is enabled. PCI PCI bus support is enabled. PCIE PCI Express support is enabled. @@ -151,9 +151,10 @@ parameter is applicable:: PPC PowerPC architecture is enabled. PPT Parallel port support is enabled. PS2 Appropriate PS/2 support is enabled. + PV_OPS A paravirtualized kernel is enabled. RAM RAM disk support is enabled. - RISCV RISCV architecture is enabled. RDT Intel Resource Director Technology. + RISCV RISCV architecture is enabled. S390 S390 architecture is enabled. SCSI Appropriate SCSI support is enabled. A lot of drivers have their options described inside @@ -164,15 +165,15 @@ parameter is applicable:: SH SuperH architecture is enabled. SMP The kernel is an SMP kernel. SPARC Sparc architecture is enabled. - SWSUSP Software suspend (hibernation) is enabled. SUSPEND System suspend states are enabled. + SWSUSP Software suspend (hibernation) is enabled. TPM TPM drivers are enabled. UMS USB Mass Storage support is enabled. USB USB support is enabled. USBHID USB Human Interface Device support is enabled. V4L Video For Linux support is enabled. - VMMIO Driver for memory mapped virtio devices is enabled. VGA The VGA console has been enabled. + VMMIO Driver for memory mapped virtio devices is enabled. VT Virtual terminal support is enabled. WDT Watchdog support is enabled. X86-32 X86-32, aka i386 architecture is enabled. @@ -186,9 +187,9 @@ parameter is applicable:: In addition, the following text indicates that the option:: + BOOT Is a boot loader parameter. BUGS= Relates to possible processor bugs on the said processor. KNL Is a kernel start-up parameter. - BOOT Is a boot loader parameter. Parameters denoted with BOOT are actually interpreted by the boot loader, and have no meaning to the kernel directly. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index a1457995fd41..01c7082ee999 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -418,20 +418,20 @@ arm64.nobti [ARM64] Unconditionally disable Branch Target Identification support - arm64.nopauth [ARM64] Unconditionally disable Pointer Authentication - support + arm64.nomops [ARM64] Unconditionally disable Memory Copy and Memory + Set instructions support arm64.nomte [ARM64] Unconditionally disable Memory Tagging Extension support - arm64.nosve [ARM64] Unconditionally disable Scalable Vector - Extension support + arm64.nopauth [ARM64] Unconditionally disable Pointer Authentication + support arm64.nosme [ARM64] Unconditionally disable Scalable Matrix Extension support - arm64.nomops [ARM64] Unconditionally disable Memory Copy and Memory - Set instructions support + arm64.nosve [ARM64] Unconditionally disable Scalable Vector + Extension support ataflop= [HW,M68k] @@ -553,7 +553,7 @@ others). ccw_timeout_log [S390] - See Documentation/s390/common_io.rst for details. + See Documentation/arch/s390/common_io.rst for details. cgroup_disable= [KNL] Disable a particular controller or optional feature Format: {name of the controller(s) or feature(s) to disable} @@ -580,6 +580,10 @@ named mounts. Specifying both "all" and "named" disables all v1 hierarchies. + cgroup_favordynmods= [KNL] Enable or Disable favordynmods. + Format: { "true" | "false" } + Defaults to the value of CONFIG_CGROUP_FAVOR_DYNMODS. + cgroup.memory= [KNL] Pass options to the cgroup memory controller. Format: <string> nosocket -- Disable socket memory accounting. @@ -598,7 +602,7 @@ Setting checkreqprot to 1 is deprecated. cio_ignore= [S390] - See Documentation/s390/common_io.rst for details. + See Documentation/arch/s390/common_io.rst for details. clearcpuid=X[,X...] [X86] Disable CPUID feature X for the kernel. See @@ -696,7 +700,7 @@ kernel/dma/contiguous.c cma_pernuma=nn[MG] - [ARM64,KNL,CMA] + [KNL,CMA] 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 @@ -706,6 +710,17 @@ which is located in node nid, if the allocation fails, they will fallback to the global default memory area. + numa_cma=<node>:nn[MG][,<node>:nn[MG]] + [KNL,CMA] + Sets the size of kernel numa memory area for + contiguous memory allocations. It will reserve CMA + area for the specified node. + + With numa CMA enabled, DMA users on node nid will + first try to allocate buffer from the numa area + which is located in node nid, if the allocation fails, + they will fallback to the global default memory area. + cmo_free_hint= [PPC] Format: { yes | no } Specify whether pages are marked as being inactive when they are freed. This is used in CMO environments @@ -862,7 +877,7 @@ memory region [offset, offset + size] for that kernel image. If '@offset' is omitted, then a suitable offset is selected automatically. - [KNL, X86-64, ARM64] Select a region under 4G first, and + [KNL, X86-64, ARM64, RISCV] Select a region under 4G first, and fall back to reserve region above 4G when '@offset' hasn't been specified. See Documentation/admin-guide/kdump/kdump.rst for further details. @@ -875,14 +890,14 @@ Documentation/admin-guide/kdump/kdump.rst for an example. crashkernel=size[KMG],high - [KNL, X86-64, ARM64] range could be above 4G. Allow kernel - to allocate physical memory region from top, so could - be above 4G if system have more than 4G ram installed. - Otherwise memory region will be allocated below 4G, if - available. + [KNL, X86-64, ARM64, RISCV] range could be above 4G. + Allow kernel to allocate physical memory region from top, + so could be above 4G if system have more than 4G ram + installed. Otherwise memory region will be allocated + below 4G, if available. It will be ignored if crashkernel=X is specified. crashkernel=size[KMG],low - [KNL, X86-64, ARM64] range under 4G. When crashkernel=X,high + [KNL, X86-64, ARM64, RISCV] range under 4G. When crashkernel=X,high is passed, kernel could allocate physical memory region above 4G, that cause second kernel crash on system that require some amount of low memory, e.g. swiotlb @@ -893,6 +908,7 @@ size is platform dependent. --> x86: max(swiotlb_size_or_default() + 8MiB, 256MiB) --> arm64: 128MiB + --> riscv: 128MiB This one lets the user specify own low range under 4G for second kernel instead. 0: to disable low allocation. @@ -1319,6 +1335,7 @@ earlyprintk=dbgp[debugController#] earlyprintk=pciserial[,force],bus:device.function[,baudrate] earlyprintk=xdbc[xhciController#] + earlyprintk=bios earlyprintk is useful when the kernel crashes before the normal console is initialized. It is not enabled by @@ -1349,6 +1366,8 @@ The sclp output can only be used on s390. + The bios output can only be used on SuperH. + The optional "force" to "pciserial" enables use of a PCI device even when its classcode is not of the UART class. @@ -1437,7 +1456,7 @@ See comment before function elanfreq_setup() in arch/x86/kernel/cpu/cpufreq/elanfreq.c. - elfcorehdr=[size[KMG]@]offset[KMG] [IA64,PPC,SH,X86,S390] + elfcorehdr=[size[KMG]@]offset[KMG] [PPC,SH,X86,S390] 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. @@ -1500,12 +1519,6 @@ floppy= [HW] See Documentation/admin-guide/blockdev/floppy.rst. - force_pal_cache_flush - [IA-64] Avoid check_sal_cache_flush which may hang on - buggy SAL_CACHE_FLUSH implementations. Using this - parameter will force ia64_sal_cache_flush to call - ia64_pal_cache_flush instead of SAL_CACHE_FLUSH. - forcepae [X86-32] Forcefully enable Physical Address Extension (PAE). Many Pentium M systems disable PAE but may have a @@ -1623,6 +1636,26 @@ Format: off | on default: on + gather_data_sampling= + [X86,INTEL] Control the Gather Data Sampling (GDS) + mitigation. + + Gather Data Sampling is a hardware vulnerability which + allows unprivileged speculative access to data which was + previously stored in vector registers. + + This issue is mitigated by default in updated microcode. + The mitigation may have a performance impact but can be + disabled. On systems without the microcode mitigation + disabling AVX serves as a mitigation. + + force: Disable AVX to mitigate systems without + microcode mitigation. No effect if the microcode + mitigation is present. Known to cause crashes in + userspace with buggy AVX enumeration. + + off: Disable GDS mitigation. + gcov_persist= [GCOV] When non-zero (default), profiling data for kernel modules is saved and remains accessible via debugfs, even when the module is unloaded/reloaded. @@ -1861,6 +1894,12 @@ 0 -- machine default 1 -- force brightness inversion + ia32_emulation= [X86-64] + Format: <bool> + When true, allows loading 32-bit programs and executing 32-bit + syscalls, essentially overriding IA32_EMULATION_DEFAULT_DISABLED at + boot time. When false, unconditionally disables IA32 emulation. + icn= [HW,ISDN] Format: <io>[,<membase>[,<icn_id>[,<icn_id2>]]] @@ -2624,7 +2663,7 @@ kvm-intel.flexpriority= [KVM,Intel] Control KVM's use of FlexPriority feature - (TPR shadow). Default is 1 (enabled). Disalbe by KVM if + (TPR shadow). Default is 1 (enabled). Disable by KVM if hardware lacks support for it. kvm-intel.nested= @@ -2881,6 +2920,38 @@ to extract confidential information from the kernel are also disabled. + locktorture.acq_writer_lim= [KNL] + Set the time limit in jiffies for a lock + acquisition. Acquisitions exceeding this limit + will result in a splat once they do complete. + + locktorture.bind_readers= [KNL] + Specify the list of CPUs to which the readers are + to be bound. + + locktorture.bind_writers= [KNL] + Specify the list of CPUs to which the writers are + to be bound. + + locktorture.call_rcu_chains= [KNL] + Specify the number of self-propagating call_rcu() + chains to set up. These are used to ensure that + there is a high probability of an RCU grace period + in progress at any given time. Defaults to 0, + which disables these call_rcu() chains. + + locktorture.long_hold= [KNL] + Specify the duration in milliseconds for the + occasional long-duration lock hold time. Defaults + to 100 milliseconds. Select 0 to disable. + + locktorture.nested_locks= [KNL] + Specify the maximum lock nesting depth that + locktorture is to exercise, up to a limit of 8 + (MAX_NESTED_LOCKS). Specify zero to disable. + Note that this parameter is ineffective on types + of locks that do not support nested acquisition. + locktorture.nreaders_stress= [KNL] Set the number of locking read-acquisition kthreads. Defaults to being automatically set based on the @@ -2896,6 +2967,25 @@ Set time (s) between CPU-hotplug operations, or zero to disable CPU-hotplug testing. + locktorture.rt_boost= [KNL] + Do periodic testing of real-time lock priority + boosting. Select 0 to disable, 1 to boost + only rt_mutex, and 2 to boost unconditionally. + Defaults to 2, which might seem to be an + odd choice, but which should be harmless for + non-real-time spinlocks, due to their disabling + of preemption. Note that non-realtime mutexes + disable boosting. + + locktorture.rt_boost_factor= [KNL] + Number that determines how often and for how + long priority boosting is exercised. This is + scaled down by the number of writers, so that the + number of boosts per unit time remains roughly + constant as the number of writers increases. + On the other hand, the duration of each boost + increases with the number of writers. + locktorture.shuffle_interval= [KNL] Set task-shuffle interval (jiffies). Shuffling tasks allows some CPUs to go into dyntick-idle @@ -2921,6 +3011,10 @@ locktorture.verbose= [KNL] Enable additional printk() statements. + locktorture.writer_fifo= [KNL] + Run the write-side locktorture kthreads at + sched_set_fifo() real-time priority. + logibm.irq= [HW,MOUSE] Logitech Bus Mouse Driver Format: <irq> @@ -3105,7 +3199,7 @@ [KNL,SH] Allow user to override the default size for per-device physically contiguous DMA buffers. - memhp_default_state=online/offline + memhp_default_state=online/offline/online_kernel/online_movable [KNL] Set the initial state for the memory hotplug onlining policy. If not specified, the default value is set according to the @@ -3273,24 +3367,25 @@ Disable all optional CPU mitigations. This improves system performance, but it may also expose users to several CPU vulnerabilities. - Equivalent to: nopti [X86,PPC] - if nokaslr then kpti=0 [ARM64] - nospectre_v1 [X86,PPC] - nobp=0 [S390] - nospectre_v2 [X86,PPC,S390,ARM64] - spectre_v2_user=off [X86] - spec_store_bypass_disable=off [X86,PPC] - ssbd=force-off [ARM64] - nospectre_bhb [ARM64] + Equivalent to: if nokaslr then kpti=0 [ARM64] + gather_data_sampling=off [X86] + kvm.nx_huge_pages=off [X86] l1tf=off [X86] mds=off [X86] - tsx_async_abort=off [X86] - kvm.nx_huge_pages=off [X86] - srbds=off [X86,INTEL] + mmio_stale_data=off [X86] no_entry_flush [PPC] no_uaccess_flush [PPC] - mmio_stale_data=off [X86] + nobp=0 [S390] + nopti [X86,PPC] + nospectre_bhb [ARM64] + nospectre_v1 [X86,PPC] + nospectre_v2 [X86,PPC,S390,ARM64] retbleed=off [X86] + spec_store_bypass_disable=off [X86,PPC] + spectre_v2_user=off [X86] + srbds=off [X86,INTEL] + ssbd=force-off [ARM64] + tsx_async_abort=off [X86] Exceptions: This does not have any effect on @@ -3717,7 +3812,7 @@ nohibernate [HIBERNATION] Disable hibernation and resume. - nohlt [ARM,ARM64,MICROBLAZE,MIPS,SH] Forces the kernel to + nohlt [ARM,ARM64,MICROBLAZE,MIPS,PPC,SH] Forces the kernel to busy wait in do_idle() and not use the arch_cpu_idle() implementation; requires CONFIG_GENERIC_IDLE_POLL_SETUP to be effective. This is useful on platforms where the @@ -3853,10 +3948,10 @@ nosmp [SMP] Tells an SMP kernel to act as a UP kernel, and disable the IO APIC. legacy for "maxcpus=0". - nosmt [KNL,MIPS,S390] Disable symmetric multithreading (SMT). + nosmt [KNL,MIPS,PPC,S390] Disable symmetric multithreading (SMT). Equivalent to smt=1. - [KNL,X86] Disable symmetric multithreading (SMT). + [KNL,X86,PPC] Disable symmetric multithreading (SMT). nosmt=force: Force disable SMT, cannot be undone via the sysfs control file. @@ -4037,20 +4132,6 @@ timeout < 0: reboot immediately Format: <timeout> - panic_print= Bitmask for printing system info when panic happens. - User can chose combination of the following bits: - bit 0: print all tasks info - bit 1: print system memory info - bit 2: print timer info - bit 3: print locks info if CONFIG_LOCKDEP is on - bit 4: print ftrace buffer - bit 5: print all printk messages in buffer - bit 6: print all CPUs backtrace (if available in the arch) - *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 - bigger log buffer with "log_buf_len" along with this. - panic_on_taint= Bitmask for conditionally calling panic() in add_taint() Format: <hex>[,nousertaint] Hexadecimal bitmask representing the set of TAINT flags @@ -4067,6 +4148,20 @@ panic_on_warn=1 panic() instead of WARN(). Useful to cause kdump on a WARN(). + panic_print= Bitmask for printing system info when panic happens. + User can chose combination of the following bits: + bit 0: print all tasks info + bit 1: print system memory info + bit 2: print timer info + bit 3: print locks info if CONFIG_LOCKDEP is on + bit 4: print ftrace buffer + bit 5: print all printk messages in buffer + bit 6: print all CPUs backtrace (if available in the arch) + *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 + bigger log buffer with "log_buf_len" along with this. + parkbd.port= [HW] Parallel port number the keyboard adapter is connected to, default is 0. Format: <parport#> @@ -4186,7 +4281,7 @@ mode 0, bit 1 is for mode 1, and so on. Mode 0 only allowed by default. - pause_on_oops= + pause_on_oops=<int> Halt all CPUs after the first oops has been printed for the specified number of seconds. This is to be used if your oopses keep scrolling off the screen. @@ -4732,6 +4827,13 @@ Set maximum number of finished RCU callbacks to process in one batch. + rcutree.do_rcu_barrier= [KNL] + Request a call to rcu_barrier(). This is + throttled so that userspace tests can safely + hammer on the sysfs variable if they so choose. + If triggered before the RCU grace-period machinery + is fully active, this will error out with EAGAIN. + rcutree.dump_tree= [KNL] Dump the structure of the rcu_node combining tree out at early boot. This is used for diagnostic @@ -4928,6 +5030,15 @@ test until boot completes in order to avoid interference. + rcuscale.kfree_by_call_rcu= [KNL] + In kernels built with CONFIG_RCU_LAZY=y, test + call_rcu() instead of kfree_rcu(). + + rcuscale.kfree_mult= [KNL] + Instead of allocating an object of size kfree_obj, + allocate one of kfree_mult * sizeof(kfree_obj). + Defaults to 1. + rcuscale.kfree_rcu_test= [KNL] Set to measure performance of kfree_rcu() flooding. @@ -4953,6 +5064,12 @@ Number of loops doing rcuscale.kfree_alloc_num number of allocations and frees. + rcuscale.minruntime= [KNL] + Set the minimum test run time in seconds. This + does not affect the data-collection interval, + but instead allows better measurement of things + like CPU consumption. + rcuscale.nreaders= [KNL] Set number of RCU readers. The value -1 selects N, where N is the number of CPUs. A value @@ -4967,7 +5084,7 @@ the same as for rcuscale.nreaders. N, where N is the number of CPUs - rcuscale.perf_type= [KNL] + rcuscale.scale_type= [KNL] Specify the RCU implementation to test. rcuscale.shutdown= [KNL] @@ -4983,6 +5100,11 @@ in microseconds. The default of zero says no holdoff. + rcuscale.writer_holdoff_jiffies= [KNL] + Additional write-side holdoff between grace + periods, but in jiffies. The default of zero + says no holdoff. + rcutorture.fqs_duration= [KNL] Set duration of force_quiescent_state bursts in microseconds. @@ -5264,6 +5386,13 @@ number avoids disturbing real-time workloads, but lengthens grace periods. + rcupdate.rcu_task_lazy_lim= [KNL] + Number of callbacks on a given CPU that will + cancel laziness on that CPU. Use -1 to disable + cancellation of laziness, but be advised that + doing so increases the danger of OOM due to + callback flooding. + rcupdate.rcu_task_stall_info= [KNL] Set initial timeout in jiffies for RCU task stall informational messages, which give some indication @@ -5293,6 +5422,29 @@ A change in value does not take effect until the beginning of the next grace period. + rcupdate.rcu_tasks_lazy_ms= [KNL] + Set timeout in milliseconds RCU Tasks asynchronous + callback batching for call_rcu_tasks(). + A negative value will take the default. A value + of zero will disable batching. Batching is + always disabled for synchronize_rcu_tasks(). + + rcupdate.rcu_tasks_rude_lazy_ms= [KNL] + Set timeout in milliseconds RCU Tasks + Rude asynchronous callback batching for + call_rcu_tasks_rude(). A negative value + will take the default. A value of zero will + disable batching. Batching is always disabled + for synchronize_rcu_tasks_rude(). + + rcupdate.rcu_tasks_trace_lazy_ms= [KNL] + Set timeout in milliseconds RCU Tasks + Trace asynchronous callback batching for + call_rcu_tasks_trace(). A negative value + will take the default. A value of zero will + disable batching. Batching is always disabled + for synchronize_rcu_tasks_trace(). + rcupdate.rcu_self_test= [KNL] Run the RCU early boot self tests @@ -5335,6 +5487,12 @@ test until boot completes in order to avoid interference. + refscale.lookup_instances= [KNL] + Number of data elements to use for the forms of + SLAB_TYPESAFE_BY_RCU testing. A negative number + is negated and multiplied by nr_cpu_ids, while + zero specifies nr_cpu_ids. + refscale.loops= [KNL] Set the number of loops over the synchronization primitive under test. Increasing this number @@ -5468,6 +5626,13 @@ [KNL] Disable ring 3 MONITOR/MWAIT feature on supported CPUs. + riscv_isa_fallback [RISCV] + 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 + replacement properties are not found. See the Kconfig + entry for RISCV_ISA_FALLBACK. + ro [KNL] Mount root device read-only on boot rodata= [KNL] @@ -5501,6 +5666,10 @@ Useful for devices that are detected asynchronously (e.g. USB and MMC devices). + rootwait= [KNL] Maximum time (in seconds) to wait for root device + to show up before attempting to mount the root + filesystem. + rproc_mem=nn[KMG][@address] [KNL,ARM,CMA] Remoteproc physical memory block. Memory area to be used by remote processor image, @@ -5760,6 +5929,13 @@ This feature may be more efficiently disabled using the csdlock_debug- kernel parameter. + smp.panic_on_ipistall= [KNL] + If a csd_lock_timeout extends for more than + the specified number of milliseconds, panic the + system. By default, let CSD-lock acquisition + take as long as they take. Specifying 300,000 + for this value provides a 5-minute timeout. + smsc-ircc2.nopnp [HW] Don't use PNP to discover SMC devices smsc-ircc2.ircc_cfg= [HW] Device configuration I/O port smsc-ircc2.ircc_sir= [HW] SIR base I/O port @@ -5875,6 +6051,17 @@ Not specifying this option is equivalent to spectre_v2_user=auto. + spec_rstack_overflow= + [X86] Control RAS overflow mitigation on AMD Zen CPUs + + off - Disable mitigation + microcode - Enable microcode mitigation only + safe-ret - Enable sw-only safe RET mitigation (default) + ibpb - Enable mitigation by issuing IBPB on + kernel entry + ibpb-vmexit - Issue IBPB only on VMEXIT + (cloud-specific mitigation) + spec_store_bypass_disable= [HW] Control Speculative Store Bypass (SSB) Disable mitigation (Speculative Store Bypass vulnerability) @@ -6243,10 +6430,6 @@ -1: disable all critical trip points in all thermal zones <degrees C>: override all critical trip points - thermal.nocrt= [HW,ACPI] - Set to disable actions on ACPI thermal zone - critical and hot trip points. - thermal.off= [HW,ACPI] 1: disable ACPI thermal control @@ -6308,6 +6491,13 @@ This will guarantee that all the other pcrs are saved. + tpm_tis.interrupts= [HW,TPM] + Enable interrupts for the MMIO based physical layer + for the FIFO interface. By default it is set to false + (0). For more information about TPM hardware interfaces + defined by Trusted Computing Group (TCG) see + https://trustedcomputinggroup.org/resource/pc-client-platform-tpm-profile-ptp-specification/ + tp_printk [FTRACE] Have the tracepoints sent to printk as well as the tracing ring buffer. This is useful for early boot up @@ -6607,7 +6797,7 @@ usbcore.authorized_default= [USB] Default USB device authorization: - (default -1 = authorized except for wireless USB, + (default -1 = authorized (same as 1), 0 = not authorized, 1 = authorized, 2 = authorized if device connected to internal port) @@ -6964,6 +7154,13 @@ disables both lockup detectors. Default is 10 seconds. + workqueue.unbound_cpus= + [KNL,SMP] Specify to constrain one or some CPUs + to use in unbound workqueues. + Format: <cpu-list> + By default, all online CPUs are available for + unbound workqueues. + workqueue.watchdog_thresh= If CONFIG_WQ_WATCHDOG is configured, workqueue can warn stall conditions and dump internal state to @@ -6985,15 +7182,6 @@ threshold repeatedly. They are likely good candidates for using WQ_UNBOUND workqueues instead. - workqueue.disable_numa - By default, all work items queued to unbound - workqueues are affine to the NUMA nodes they're - issued on, which results in better behavior in - general. If NUMA affinity needs to be disabled for - whatever reason, this option can be used. Note - that this also can be controlled per-workqueue for - workqueues visible under /sys/bus/workqueue/. - workqueue.power_efficient Per-cpu workqueues are generally preferred because they show better performance thanks to cache @@ -7009,6 +7197,18 @@ The default value of this parameter is determined by the config option CONFIG_WQ_POWER_EFFICIENT_DEFAULT. + workqueue.default_affinity_scope= + Select the default affinity scope to use for unbound + workqueues. Can be one of "cpu", "smt", "cache", + "numa" and "system". Default is "cache". For more + information, see the Affinity Scopes section in + Documentation/core-api/workqueue.rst. + + This can be changed after boot by writing to the + matching /sys/module/workqueue/parameters file. All + workqueues with the "default" affinity scope will be + updated accordignly. + workqueue.debug_force_rr_cpu Workqueue used to implicitly guarantee that work items queued without explicit CPU specified are put diff --git a/Documentation/admin-guide/laptops/thinkpad-acpi.rst b/Documentation/admin-guide/laptops/thinkpad-acpi.rst index e27a1c3f634e..98d304010170 100644 --- a/Documentation/admin-guide/laptops/thinkpad-acpi.rst +++ b/Documentation/admin-guide/laptops/thinkpad-acpi.rst @@ -53,6 +53,7 @@ detailed description): - Lap mode sensor - Setting keyboard language - WWAN Antenna type + - Auxmac A compatibility table by model and feature is maintained on the web site, http://ibm-acpi.sf.net/. I appreciate any success or failure @@ -1511,6 +1512,25 @@ Currently 2 antenna types are supported as mentioned below: The property is read-only. If the platform doesn't have support the sysfs class is not created. +Auxmac +------ + +sysfs: auxmac + +Some newer Thinkpads have a feature called MAC Address Pass-through. This +feature is implemented by the system firmware to provide a system unique MAC, +that can override a dock or USB ethernet dongle MAC, when connected to a +network. This property enables user-space to easily determine the MAC address +if the feature is enabled. + +The values of this auxiliary MAC are: + + cat /sys/devices/platform/thinkpad_acpi/auxmac + +If the feature is disabled, the value will be 'disabled'. + +This property is read-only. + Adaptive keyboard ----------------- diff --git a/Documentation/admin-guide/media/qcom_camss.rst b/Documentation/admin-guide/media/qcom_camss.rst index a72e17d09cb7..8a8f3ff40105 100644 --- a/Documentation/admin-guide/media/qcom_camss.rst +++ b/Documentation/admin-guide/media/qcom_camss.rst @@ -18,7 +18,7 @@ The driver implements V4L2, Media controller and V4L2 subdev interfaces. Camera sensor using V4L2 subdev interface in the kernel is supported. The driver is implemented using as a reference the Qualcomm Camera Subsystem -driver for Android as found in Code Aurora [#f1]_ [#f2]_. +driver for Android as found in Code Linaro [#f1]_ [#f2]_. Qualcomm Camera Subsystem hardware @@ -181,5 +181,5 @@ Referenced 2018-06-22. References ---------- -.. [#f1] https://source.codeaurora.org/quic/la/kernel/msm-3.10/ -.. [#f2] https://source.codeaurora.org/quic/la/kernel/msm-3.18/ +.. [#f1] https://git.codelinaro.org/clo/la/kernel/msm-3.10/ +.. [#f2] https://git.codelinaro.org/clo/la/kernel/msm-3.18/ diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst index 2d495fa85a0e..da94feb97ed1 100644 --- a/Documentation/admin-guide/mm/damon/usage.rst +++ b/Documentation/admin-guide/mm/damon/usage.rst @@ -20,18 +20,18 @@ DAMON provides below interfaces for different users. you can write and use your personalized DAMON sysfs wrapper programs that reads/writes the sysfs files instead of you. The `DAMON user space tool <https://github.com/awslabs/damo>`_ is one example of such programs. -- *debugfs interface. (DEPRECATED!)* - :ref:`This <debugfs_interface>` is almost identical to :ref:`sysfs interface - <sysfs_interface>`. This is deprecated, so users should move to the - :ref:`sysfs interface <sysfs_interface>`. If you depend on this and cannot - move, please report your usecase to damon@lists.linux.dev and - linux-mm@kvack.org. - *Kernel Space Programming Interface.* :doc:`This </mm/damon/api>` is for kernel space programmers. Using this, users can utilize every feature of DAMON most flexibly and efficiently by writing kernel space DAMON application programs for you. You can even extend DAMON for various address spaces. For detail, please refer to the interface :doc:`document </mm/damon/api>`. +- *debugfs interface. (DEPRECATED!)* + :ref:`This <debugfs_interface>` is almost identical to :ref:`sysfs interface + <sysfs_interface>`. This is deprecated, so users should move to the + :ref:`sysfs interface <sysfs_interface>`. If you depend on this and cannot + move, please report your usecase to damon@lists.linux.dev and + linux-mm@kvack.org. .. _sysfs_interface: @@ -76,7 +76,7 @@ comma (","). :: │ │ │ │ │ │ │ │ ... │ │ │ │ │ │ ... │ │ │ │ │ schemes/nr_schemes - │ │ │ │ │ │ 0/action + │ │ │ │ │ │ 0/action,apply_interval_us │ │ │ │ │ │ │ access_pattern/ │ │ │ │ │ │ │ │ sz/min,max │ │ │ │ │ │ │ │ nr_accesses/min,max @@ -87,7 +87,7 @@ comma (","). :: │ │ │ │ │ │ │ filters/nr_filters │ │ │ │ │ │ │ │ 0/type,matching,memcg_id │ │ │ │ │ │ │ stats/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds - │ │ │ │ │ │ │ tried_regions/ + │ │ │ │ │ │ │ tried_regions/total_bytes │ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age │ │ │ │ │ │ │ │ ... │ │ │ │ │ │ ... @@ -99,20 +99,18 @@ Root The root of the DAMON sysfs interface is ``<sysfs>/kernel/mm/damon/``, and it has one directory named ``admin``. The directory contains the files for -privileged user space programs' control of DAMON. User space tools or deamons +privileged user space programs' control of DAMON. User space tools or daemons having the root permission could use this directory. kdamonds/ --------- -The monitoring-related information including request specifications and results -are called DAMON context. DAMON executes each context with a kernel thread -called kdamond, and multiple kdamonds could run in parallel. - Under the ``admin`` directory, one directory, ``kdamonds``, which has files for -controlling the kdamonds exist. In the beginning, this directory has only one -file, ``nr_kdamonds``. Writing a number (``N``) to the file creates the number -of child directories named ``0`` to ``N-1``. Each directory represents each +controlling the kdamonds (refer to +:ref:`design <damon_design_execution_model_and_data_structures>` for more +details) exists. In the beginning, this directory has only one file, +``nr_kdamonds``. Writing a number (``N``) to the file creates the number of +child directories named ``0`` to ``N-1``. Each directory represents each kdamond. kdamonds/<N>/ @@ -127,14 +125,18 @@ in the state. Writing ``commit`` to the ``state`` file makes kdamond reads the user inputs in the sysfs files except ``state`` file again. Writing ``update_schemes_stats`` to ``state`` file updates the contents of stats files for each DAMON-based operation scheme of the kdamond. For details of the -stats, please refer to :ref:`stats section <sysfs_schemes_stats>`. Writing -``update_schemes_tried_regions`` to ``state`` file updates the DAMON-based -operation scheme action tried regions directory for each DAMON-based operation -scheme of the kdamond. Writing ``clear_schemes_tried_regions`` to ``state`` -file clears the DAMON-based operating scheme action tried regions directory for -each DAMON-based operation scheme of the kdamond. For details of the -DAMON-based operation scheme action tried regions directory, please refer to -:ref:`tried_regions section <sysfs_schemes_tried_regions>`. +stats, please refer to :ref:`stats section <sysfs_schemes_stats>`. + +Writing ``update_schemes_tried_regions`` to ``state`` file updates the +DAMON-based operation scheme action tried regions directory for each +DAMON-based operation scheme of the kdamond. Writing +``update_schemes_tried_bytes`` to ``state`` file updates only +``.../tried_regions/total_bytes`` files. Writing +``clear_schemes_tried_regions`` to ``state`` file clears the DAMON-based +operating scheme action tried regions directory for each DAMON-based operation +scheme of the kdamond. For details of the DAMON-based operation scheme action +tried regions directory, please refer to :ref:`tried_regions section +<sysfs_schemes_tried_regions>`. If the state is ``on``, reading ``pid`` shows the pid of the kdamond thread. @@ -146,9 +148,10 @@ kdamonds/<N>/contexts/ In the beginning, this directory has only one file, ``nr_contexts``. Writing a number (``N``) to the file creates the number of child directories named as -``0`` to ``N-1``. Each directory represents each monitoring context. At the -moment, only one context per kdamond is supported, so only ``0`` or ``1`` can -be written to the file. +``0`` to ``N-1``. Each directory represents each monitoring context (refer to +:ref:`design <damon_design_execution_model_and_data_structures>` for more +details). At the moment, only one context per kdamond is supported, so only +``0`` or ``1`` can be written to the file. .. _sysfs_contexts: @@ -266,8 +269,8 @@ schemes/<N>/ ------------ In each scheme directory, five directories (``access_pattern``, ``quotas``, -``watermarks``, ``filters``, ``stats``, and ``tried_regions``) and one file -(``action``) exist. +``watermarks``, ``filters``, ``stats``, and ``tried_regions``) and two files +(``action`` and ``apply_interval``) exist. The ``action`` file is for setting and getting the scheme's :ref:`action <damon_design_damos_action>`. The keywords that can be written to and read @@ -293,6 +296,9 @@ Note that support of each action depends on the running DAMON operations set - ``stat``: Do nothing but count the statistics. Supported by all operations sets. +The ``apply_interval_us`` file is for setting and getting the scheme's +:ref:`apply_interval <damon_design_damos>` in microseconds. + schemes/<N>/access_pattern/ --------------------------- @@ -359,15 +365,21 @@ number (``N``) to the file creates the number of child directories named ``0`` to ``N-1``. Each directory represents each filter. The filters are evaluated in the numeric order. -Each filter directory contains three files, namely ``type``, ``matcing``, and -``memcg_path``. You can write one of two special keywords, ``anon`` for -anonymous pages, or ``memcg`` for specific memory cgroup filtering. In case of -the memory cgroup filtering, you can specify the memory cgroup of the interest -by writing the path of the memory cgroup from the cgroups mount point to -``memcg_path`` file. You can write ``Y`` or ``N`` to ``matching`` file to -filter out pages that does or does not match to the type, respectively. Then, -the scheme's action will not be applied to the pages that specified to be -filtered out. +Each filter directory contains six files, namely ``type``, ``matcing``, +``memcg_path``, ``addr_start``, ``addr_end``, and ``target_idx``. To ``type`` +file, you can write one of four special keywords: ``anon`` for anonymous pages, +``memcg`` for specific memory cgroup, ``addr`` for specific address range (an +open-ended interval), or ``target`` for specific DAMON monitoring target +filtering. In case of the memory cgroup filtering, you can specify the memory +cgroup of the interest by writing the path of the memory cgroup from the +cgroups mount point to ``memcg_path`` file. In case of the address range +filtering, you can specify the start and end address of the range to +``addr_start`` and ``addr_end`` files, respectively. For the DAMON monitoring +target filtering, you can specify the index of the target between the list of +the DAMON context's monitoring targets list to ``target_idx`` file. You can +write ``Y`` or ``N`` to ``matching`` file to filter out pages that does or does +not match to the type, respectively. Then, the scheme's action will not be +applied to the pages that specified to be filtered out. For example, below restricts a DAMOS action to be applied to only non-anonymous pages of all memory cgroups except ``/having_care_already``.:: @@ -381,8 +393,14 @@ pages of all memory cgroups except ``/having_care_already``.:: echo /having_care_already > 1/memcg_path echo N > 1/matching -Note that filters are currently supported only when ``paddr`` -`implementation <sysfs_contexts>` is being used. +Note that ``anon`` and ``memcg`` filters are currently supported only when +``paddr`` :ref:`implementation <sysfs_contexts>` is being used. + +Also, memory regions that are filtered out by ``addr`` or ``target`` filters +are not counted as the scheme has tried to those, while regions that filtered +out by other type filters are counted as the scheme has tried to. The +difference is applied to :ref:`stats <damos_stats>` and +:ref:`tried regions <sysfs_schemes_tried_regions>`. .. _sysfs_schemes_stats: @@ -397,7 +415,7 @@ be used for online analysis or tuning of the schemes. The statistics can be retrieved by reading the files under ``stats`` directory (``nr_tried``, ``sz_tried``, ``nr_applied``, ``sz_applied``, and ``qt_exceeds``), respectively. The files are not updated in real time, so you -should ask DAMON sysfs interface to updte the content of the files for the +should ask DAMON sysfs interface to update the content of the files for the stats by writing a special keyword, ``update_schemes_stats`` to the relevant ``kdamonds/<N>/state`` file. @@ -406,13 +424,21 @@ stats by writing a special keyword, ``update_schemes_stats`` to the relevant schemes/<N>/tried_regions/ -------------------------- +This directory initially has one file, ``total_bytes``. + When a special keyword, ``update_schemes_tried_regions``, is written to the -relevant ``kdamonds/<N>/state`` file, DAMON creates directories named integer -starting from ``0`` under this directory. Each directory contains files -exposing detailed information about each of the memory region that the -corresponding scheme's ``action`` has tried to be applied under this directory, -during next :ref:`aggregation interval <sysfs_monitoring_attrs>`. The -information includes address range, ``nr_accesses``, and ``age`` of the region. +relevant ``kdamonds/<N>/state`` file, DAMON updates the ``total_bytes`` file so +that reading it returns the total size of the scheme tried regions, and creates +directories named integer starting from ``0`` under this directory. Each +directory contains files exposing detailed information about each of the memory +region that the corresponding scheme's ``action`` has tried to be applied under +this directory, during next :ref:`apply interval <damon_design_damos>` of the +corresponding scheme. The information includes address range, ``nr_accesses``, +and ``age`` of the region. + +Writing ``update_schemes_tried_bytes`` to the relevant ``kdamonds/<N>/state`` +file will only update the ``total_bytes`` file, and will not create the +subdirectories. The directories will be removed when another special keyword, ``clear_schemes_tried_regions``, is written to the relevant @@ -471,6 +497,62 @@ Please note that it's highly recommended to use user space tools like `damo <https://github.com/awslabs/damo>`_ rather than manually reading and writing the files as above. Above is only for an example. +.. _tracepoint: + +Tracepoints for Monitoring Results +================================== + +Users can get the monitoring results via the :ref:`tried_regions +<sysfs_schemes_tried_regions>`. The interface is useful for getting a +snapshot, but it could be inefficient for fully recording all the monitoring +results. For the purpose, two trace points, namely ``damon:damon_aggregated`` +and ``damon:damos_before_apply``, are provided. ``damon:damon_aggregated`` +provides the whole monitoring results, while ``damon:damos_before_apply`` +provides the monitoring results for regions that each DAMON-based Operation +Scheme (:ref:`DAMOS <damon_design_damos>`) is gonna be applied. Hence, +``damon:damos_before_apply`` is more useful for recording internal behavior of +DAMOS, or DAMOS target access +:ref:`pattern <damon_design_damos_access_pattern>` based query-like efficient +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 + # perf record -e damon:damon_aggregated & + # sleep 5 + # kill 9 $(pidof perf) + # echo off > monitor_on + # perf script + kdamond.0 46568 [027] 79357.842179: damon:damon_aggregated: target_id=0 nr_regions=11 122509119488-135708762112: 0 864 + [...] + +Each line of the perf script output represents each monitoring region. The +first five fields are as usual other tracepoint outputs. The sixth field +(``target_id=X``) shows the ide of the monitoring target of the region. The +seventh field (``nr_regions=X``) shows the total number of monitoring regions +for the target. The eighth field (``X-Y:``) shows the start (``X``) and end +(``Y``) addresses of the region in bytes. The ninth field (``X``) shows the +``nr_accesses`` of the region (refer to +:ref:`design <damon_design_region_based_sampling>` for more details of the +counter). Finally the tenth field (``X``) shows the ``age`` of the region +(refer to :ref:`design <damon_design_age_tracking>` for more details of the +counter). + +If the event was ``damon:damos_beofre_apply``, the ``perf script`` output would +be somewhat like below:: + + kdamond.0 47293 [000] 80801.060214: damon:damos_before_apply: ctx_idx=0 scheme_idx=0 target_idx=0 nr_regions=11 121932607488-135128711168: 0 136 + [...] + +Each line of the output represents each monitoring region that each DAMON-based +Operation Scheme was about to be applied at the traced time. The first five +fields are as usual. It shows the index of the DAMON context (``ctx_idx=X``) +of the scheme in the list of the contexts of the context's kdamond, the index +of the scheme (``scheme_idx=X``) in the list of the schemes of the context, in +addition to the output of ``damon_aggregated`` tracepoint. + + .. _debugfs_interface: debugfs Interface (DEPRECATED!) @@ -766,23 +848,3 @@ directory by putting the name of the context to the ``rm_contexts`` file. :: Note that ``mk_contexts``, ``rm_contexts``, and ``monitor_on`` files are in the root directory only. - - -.. _tracepoint: - -Tracepoint for Monitoring Results -================================= - -Users can get the monitoring results via the :ref:`tried_regions -<sysfs_schemes_tried_regions>` or a tracepoint, ``damon:damon_aggregated``. -While the tried regions directory is useful for getting a snapshot, the -tracepoint is useful for getting a full record of the results. 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 - # perf record -e damon:damon_aggregated & - # sleep 5 - # kill 9 $(pidof perf) - # echo off > monitor_on - # perf script diff --git a/Documentation/admin-guide/mm/ksm.rst b/Documentation/admin-guide/mm/ksm.rst index 7626392fe82c..e59231ac6bb7 100644 --- a/Documentation/admin-guide/mm/ksm.rst +++ b/Documentation/admin-guide/mm/ksm.rst @@ -155,10 +155,21 @@ stable_node_chains_prune_millisecs scan. It's a noop if not a single KSM page hit the ``max_page_sharing`` yet. +smart_scan + Historically KSM checked every candidate page for each scan. It did + not take into account historic information. When smart scan is + enabled, pages that have previously not been de-duplicated get + skipped. How often these pages are skipped depends on how often + de-duplication has already been tried and failed. By default this + optimization is enabled. The ``pages_skipped`` metric shows how + effective the setting is. + The effectiveness of KSM and MADV_MERGEABLE is shown in ``/sys/kernel/mm/ksm/``: general_profit how effective is KSM. The calculation is explained below. +pages_scanned + how many pages are being scanned for ksm pages_shared how many shared pages are being used pages_sharing @@ -167,12 +178,21 @@ pages_unshared how many pages unique but repeatedly checked for merging pages_volatile how many pages changing too fast to be placed in a tree +pages_skipped + how many pages did the "smart" page scanning algorithm skip full_scans how many times all mergeable areas have been scanned stable_node_chains the number of KSM pages that hit the ``max_page_sharing`` limit stable_node_dups number of duplicated KSM pages +ksm_zero_pages + how many zero pages that are still mapped into processes were mapped by + KSM when deduplicating. + +When ``use_zero_pages`` is/was enabled, the sum of ``pages_sharing`` + +``ksm_zero_pages`` represents the actual number of pages saved by KSM. +if ``use_zero_pages`` has never been enabled, ``ksm_zero_pages`` is 0. A high ratio of ``pages_sharing`` to ``pages_shared`` indicates good sharing, but a high ratio of ``pages_unshared`` to ``pages_sharing`` @@ -196,21 +216,25 @@ several times, which are unprofitable memory consumed. 1) How to determine whether KSM save memory or consume memory in system-wide range? Here is a simple approximate calculation for reference:: - general_profit =~ pages_sharing * sizeof(page) - (all_rmap_items) * + general_profit =~ ksm_saved_pages * sizeof(page) - (all_rmap_items) * sizeof(rmap_item); - where all_rmap_items can be easily obtained by summing ``pages_sharing``, - ``pages_shared``, ``pages_unshared`` and ``pages_volatile``. + where ksm_saved_pages equals to the sum of ``pages_sharing`` + + ``ksm_zero_pages`` of the system, and all_rmap_items can be easily + obtained by summing ``pages_sharing``, ``pages_shared``, ``pages_unshared`` + and ``pages_volatile``. 2) The KSM profit inner a single process can be similarly obtained by the following approximate calculation:: - process_profit =~ ksm_merging_pages * sizeof(page) - + process_profit =~ ksm_saved_pages * sizeof(page) - ksm_rmap_items * sizeof(rmap_item). - where ksm_merging_pages is shown under the directory ``/proc/<pid>/``, - and ksm_rmap_items is shown in ``/proc/<pid>/ksm_stat``. The process profit - is also shown in ``/proc/<pid>/ksm_stat`` as ksm_process_profit. + where ksm_saved_pages equals to the sum of ``ksm_merging_pages`` and + ``ksm_zero_pages``, both of which are shown under the directory + ``/proc/<pid>/ksm_stat``, and ksm_rmap_items is also shown in + ``/proc/<pid>/ksm_stat``. The process profit is also shown in + ``/proc/<pid>/ksm_stat`` as ksm_process_profit. From the perspective of application, a high ratio of ``ksm_rmap_items`` to ``ksm_merging_pages`` means a bad madvise-applied policy, so developers or diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst b/Documentation/admin-guide/mm/memory-hotplug.rst index 1b02fe5807cc..098f14d83e99 100644 --- a/Documentation/admin-guide/mm/memory-hotplug.rst +++ b/Documentation/admin-guide/mm/memory-hotplug.rst @@ -33,7 +33,7 @@ used to expose persistent memory, other performance-differentiated memory and reserved memory regions as ordinary system RAM to Linux. Linux only supports memory hot(un)plug on selected 64 bit architectures, such as -x86_64, arm64, ppc64, s390x and ia64. +x86_64, arm64, ppc64 and s390x. Memory Hot(Un)Plug Granularity ------------------------------ @@ -75,7 +75,7 @@ Memory hotunplug consists of two phases: (1) Offlining memory blocks (2) Removing the memory from Linux -In the fist phase, memory is "hidden" from the page allocator again, for +In the first phase, memory is "hidden" from the page allocator again, for example, by migrating busy memory to other memory locations and removing all relevant free pages from the page allocator After this phase, the memory is no longer visible in memory statistics of the system. @@ -250,15 +250,15 @@ Observing the State of Memory Blocks The state (online/offline/going-offline) of a memory block can be observed either via:: - % cat /sys/device/system/memory/memoryXXX/state + % cat /sys/devices/system/memory/memoryXXX/state Or alternatively (1/0) via:: - % cat /sys/device/system/memory/memoryXXX/online + % cat /sys/devices/system/memory/memoryXXX/online For an online memory block, the managing zone can be observed via:: - % cat /sys/device/system/memory/memoryXXX/valid_zones + % cat /sys/devices/system/memory/memoryXXX/valid_zones Configuring Memory Hot(Un)Plug ============================== @@ -291,6 +291,14 @@ The following files are currently defined: Availability depends on the CONFIG_ARCH_MEMORY_PROBE kernel configuration option. ``uevent`` read-write: generic udev file for device subsystems. +``crash_hotplug`` read-only: when changes to the system memory map + occur due to hot un/plug of memory, this file contains + '1' if the kernel updates the kdump capture kernel memory + map itself (via elfcorehdr), or '0' if userspace must update + the kdump capture kernel memory map. + + Availability depends on the CONFIG_MEMORY_HOTPLUG kernel + configuration option. ====================== ========================================================= .. note:: @@ -318,7 +326,7 @@ however, a memory block might span memory holes. A memory block spanning memory holes cannot be offlined. For example, assume 1 GiB memory block size. A device for a memory starting at -0x100000000 is ``/sys/device/system/memory/memory4``:: +0x100000000 is ``/sys/devices/system/memory/memory4``:: (0x100000000 / 1Gib = 4) @@ -433,6 +441,18 @@ The following module parameters are currently defined: memory in a way that huge pages in bigger granularity cannot be formed on hotplugged memory. + + With value "force" it could result in memory + wastage due to memmap size limitations. For + example, if the memmap for a memory block + requires 1 MiB, but the pageblock size is 2 + MiB, 1 MiB of hotplugged memory will be wasted. + Note that there are still cases where the + feature cannot be enforced: for example, if the + memmap is smaller than a single page, or if the + architecture does not support the forced mode + in all configurations. + ``online_policy`` read-write: Set the basic policy used for automatic zone selection when onlining memory blocks without specifying a target zone. @@ -669,7 +689,7 @@ when still encountering permanently unmovable pages within ZONE_MOVABLE (-> BUG), memory offlining will keep retrying until it eventually succeeds. When offlining is triggered from user space, the offlining context can be -terminated by sending a fatal signal. A timeout based offlining can easily be +terminated by sending a signal. A timeout based offlining can easily be implemented via:: % timeout $TIMEOUT offline_block | failure_handling diff --git a/Documentation/admin-guide/mm/numa_memory_policy.rst b/Documentation/admin-guide/mm/numa_memory_policy.rst index 46515ad2337f..eca38fa81e0f 100644 --- a/Documentation/admin-guide/mm/numa_memory_policy.rst +++ b/Documentation/admin-guide/mm/numa_memory_policy.rst @@ -109,7 +109,7 @@ VMA Policy * A task may install a new VMA policy on a sub-range of a previously mmap()ed region. When this happens, Linux splits the existing virtual memory area into 2 or 3 VMAs, each with - it's own policy. + its own policy. * By default, VMA policy applies only to pages allocated after the policy is installed. Any pages already faulted into the diff --git a/Documentation/admin-guide/mm/pagemap.rst b/Documentation/admin-guide/mm/pagemap.rst index c8f380271cad..fe17cf210426 100644 --- a/Documentation/admin-guide/mm/pagemap.rst +++ b/Documentation/admin-guide/mm/pagemap.rst @@ -227,3 +227,92 @@ Before Linux 3.11 pagemap bits 55-60 were used for "page-shift" (which is always 12 at most architectures). Since Linux 3.11 their meaning changes after first clear of soft-dirty bits. Since Linux 4.2 they are used for flags unconditionally. + +Pagemap Scan IOCTL +================== + +The ``PAGEMAP_SCAN`` IOCTL on the pagemap file can be used to get or optionally +clear the info about page table entries. The following operations are supported +in this IOCTL: + +- Scan the address range and get the memory ranges matching the provided criteria. + This is performed when the output buffer is specified. +- Write-protect the pages. The ``PM_SCAN_WP_MATCHING`` is used to write-protect + the pages of interest. The ``PM_SCAN_CHECK_WPASYNC`` aborts the operation if + non-Async Write Protected pages are found. The ``PM_SCAN_WP_MATCHING`` can be + used with or without ``PM_SCAN_CHECK_WPASYNC``. +- Both of those operations can be combined into one atomic operation where we can + get and write protect the pages as well. + +Following flags about pages are currently supported: + +- ``PAGE_IS_WPALLOWED`` - Page has async-write-protection enabled +- ``PAGE_IS_WRITTEN`` - Page has been written to from the time it was write protected +- ``PAGE_IS_FILE`` - Page is file backed +- ``PAGE_IS_PRESENT`` - Page is present in the memory +- ``PAGE_IS_SWAPPED`` - Page is in swapped +- ``PAGE_IS_PFNZERO`` - Page has zero PFN +- ``PAGE_IS_HUGE`` - Page is THP or Hugetlb backed + +The ``struct pm_scan_arg`` is used as the argument of the IOCTL. + + 1. The size of the ``struct pm_scan_arg`` must be specified in the ``size`` + field. This field will be helpful in recognizing the structure if extensions + are done later. + 2. The flags can be specified in the ``flags`` field. The ``PM_SCAN_WP_MATCHING`` + and ``PM_SCAN_CHECK_WPASYNC`` are the only added flags at this time. The get + operation is optionally performed depending upon if the output buffer is + provided or not. + 3. The range is specified through ``start`` and ``end``. + 4. The walk can abort before visiting the complete range such as the user buffer + can get full etc. The walk ending address is specified in``end_walk``. + 5. The output buffer of ``struct page_region`` array and size is specified in + ``vec`` and ``vec_len``. + 6. The optional maximum requested pages are specified in the ``max_pages``. + 7. The masks are specified in ``category_mask``, ``category_anyof_mask``, + ``category_inverted`` and ``return_mask``. + +Find pages which have been written and WP them as well:: + + struct pm_scan_arg arg = { + .size = sizeof(arg), + .flags = PM_SCAN_CHECK_WPASYNC | PM_SCAN_CHECK_WPASYNC, + .. + .category_mask = PAGE_IS_WRITTEN, + .return_mask = PAGE_IS_WRITTEN, + }; + +Find pages which have been written, are file backed, not swapped and either +present or huge:: + + struct pm_scan_arg arg = { + .size = sizeof(arg), + .flags = 0, + .. + .category_mask = PAGE_IS_WRITTEN | PAGE_IS_SWAPPED, + .category_inverted = PAGE_IS_SWAPPED, + .category_anyof_mask = PAGE_IS_PRESENT | PAGE_IS_HUGE, + .return_mask = PAGE_IS_WRITTEN | PAGE_IS_SWAPPED | + PAGE_IS_PRESENT | PAGE_IS_HUGE, + }; + +The ``PAGE_IS_WRITTEN`` flag can be considered as a better-performing alternative +of soft-dirty flag. It doesn't get affected by VMA merging of the kernel and hence +the user can find the true soft-dirty pages in case of normal pages. (There may +still be extra dirty pages reported for THP or Hugetlb pages.) + +"PAGE_IS_WRITTEN" category is used with uffd write protect-enabled ranges to +implement memory dirty tracking in userspace: + + 1. The userfaultfd file descriptor is created with ``userfaultfd`` syscall. + 2. The ``UFFD_FEATURE_WP_UNPOPULATED`` and ``UFFD_FEATURE_WP_ASYNC`` features + are set by ``UFFDIO_API`` IOCTL. + 3. The memory range is registered with ``UFFDIO_REGISTER_MODE_WP`` mode + through ``UFFDIO_REGISTER`` IOCTL. + 4. Then any part of the registered memory or the whole memory region must + be write protected using ``PAGEMAP_SCAN`` IOCTL with flag ``PM_SCAN_WP_MATCHING`` + or the ``UFFDIO_WRITEPROTECT`` IOCTL can be used. Both of these perform the + same operation. The former is better in terms of performance. + 5. Now the ``PAGEMAP_SCAN`` IOCTL can be used to either just find pages which + have been written to since they were last marked and/or optionally write protect + the pages as well. diff --git a/Documentation/admin-guide/mm/userfaultfd.rst b/Documentation/admin-guide/mm/userfaultfd.rst index 7c304e432205..203e26da5f92 100644 --- a/Documentation/admin-guide/mm/userfaultfd.rst +++ b/Documentation/admin-guide/mm/userfaultfd.rst @@ -244,6 +244,56 @@ write-protected (so future writes will also result in a WP fault). These ioctls support a mode flag (``UFFDIO_COPY_MODE_WP`` or ``UFFDIO_CONTINUE_MODE_WP`` respectively) to configure the mapping this way. +If the userfaultfd context has ``UFFD_FEATURE_WP_ASYNC`` feature bit set, +any vma registered with write-protection will work in async mode rather +than the default sync mode. + +In async mode, there will be no message generated when a write operation +happens, meanwhile the write-protection will be resolved automatically by +the kernel. It can be seen as a more accurate version of soft-dirty +tracking and it can be different in a few ways: + + - The dirty result will not be affected by vma changes (e.g. vma + merging) because the dirty is only tracked by the pte. + + - It supports range operations by default, so one can enable tracking on + any range of memory as long as page aligned. + + - Dirty information will not get lost if the pte was zapped due to + various reasons (e.g. during split of a shmem transparent huge page). + + - Due to a reverted meaning of soft-dirty (page clean when uffd-wp bit + set; dirty when uffd-wp bit cleared), it has different semantics on + some of the memory operations. For example: ``MADV_DONTNEED`` on + anonymous (or ``MADV_REMOVE`` on a file mapping) will be treated as + dirtying of memory by dropping uffd-wp bit during the procedure. + +The user app can collect the "written/dirty" status by looking up the +uffd-wp bit for the pages being interested in /proc/pagemap. + +The page will not be under track of uffd-wp async mode until the page is +explicitly write-protected by ``ioctl(UFFDIO_WRITEPROTECT)`` with the mode +flag ``UFFDIO_WRITEPROTECT_MODE_WP`` set. Trying to resolve a page fault +that was tracked by async mode userfaultfd-wp is invalid. + +When userfaultfd-wp async mode is used alone, it can be applied to all +kinds of memory. + +Memory Poisioning Emulation +--------------------------- + +In response to a fault (either missing or minor), an action userspace can +take to "resolve" it is to issue a ``UFFDIO_POISON``. This will cause any +future faulters to either get a SIGBUS, or in KVM's case the guest will +receive an MCE as if there were hardware memory poisoning. + +This is used to emulate hardware memory poisoning. Imagine a VM running on a +machine which experiences a real hardware memory error. Later, we live migrate +the VM to another physical machine. Since we want the migration to be +transparent to the guest, we want that same address range to act as if it was +still poisoned, even though it's on a new physical host which ostensibly +doesn't have a memory error in the exact same spot. + QEMU/KVM ======== diff --git a/Documentation/admin-guide/mm/zswap.rst b/Documentation/admin-guide/mm/zswap.rst index c5c2c7dbb155..45b98390e938 100644 --- a/Documentation/admin-guide/mm/zswap.rst +++ b/Documentation/admin-guide/mm/zswap.rst @@ -49,7 +49,7 @@ compressed pool. Design ====== -Zswap receives pages for compression through the Frontswap API and is able to +Zswap receives pages for compression from the swap subsystem and is able to evict pages from its own compressed pool on an LRU basis and write them back to the backing swap device in the case that the compressed pool is full. @@ -70,19 +70,19 @@ means the compression ratio will always be 2:1 or worse (because of half-full zbud pages). The zsmalloc type zpool has a more complex compressed page storage method, and it can achieve greater storage densities. -When a swap page is passed from frontswap to zswap, zswap maintains a mapping +When a swap page is passed from swapout to zswap, zswap maintains a mapping of the swap entry, a combination of the swap type and swap offset, to the zpool handle that references that compressed swap page. This mapping is achieved with a red-black tree per swap type. The swap offset is the search key for the tree nodes. -During a page fault on a PTE that is a swap entry, frontswap calls the zswap -load function to decompress the page into the page allocated by the page fault -handler. +During a page fault on a PTE that is a swap entry, the swapin code calls the +zswap load function to decompress the page into the page allocated by the page +fault handler. Once there are no PTEs referencing a swap page stored in zswap (i.e. the count -in the swap_map goes to 0) the swap code calls the zswap invalidate function, -via frontswap, to free the compressed entry. +in the swap_map goes to 0) the swap code calls the zswap invalidate function +to free the compressed entry. Zswap seeks to be simple in its policies. Sysfs attributes allow for one user controlled policy: diff --git a/Documentation/admin-guide/module-signing.rst b/Documentation/admin-guide/module-signing.rst index 7d7c7c8a545c..a8667a777490 100644 --- a/Documentation/admin-guide/module-signing.rst +++ b/Documentation/admin-guide/module-signing.rst @@ -28,10 +28,10 @@ trusted userspace bits. This facility uses X.509 ITU-T standard certificates to encode the public keys involved. The signatures are not themselves encoded in any industrial standard -type. The facility currently only supports the RSA public key encryption -standard (though it is pluggable and permits others to be used). The possible -hash algorithms that can be used are SHA-1, SHA-224, SHA-256, SHA-384, and -SHA-512 (the algorithm is selected by data in the signature). +type. The built-in facility currently only supports the RSA & NIST P-384 ECDSA +public key signing standard (though it is pluggable and permits others to be +used). The possible hash algorithms that can be used are SHA-2 and SHA-3 of +sizes 256, 384, and 512 (the algorithm is selected by data in the signature). ========================== @@ -81,11 +81,12 @@ This has a number of options available: sign the modules with: =============================== ========================================== - ``CONFIG_MODULE_SIG_SHA1`` :menuselection:`Sign modules with SHA-1` - ``CONFIG_MODULE_SIG_SHA224`` :menuselection:`Sign modules with SHA-224` ``CONFIG_MODULE_SIG_SHA256`` :menuselection:`Sign modules with SHA-256` ``CONFIG_MODULE_SIG_SHA384`` :menuselection:`Sign modules with SHA-384` ``CONFIG_MODULE_SIG_SHA512`` :menuselection:`Sign modules with SHA-512` + ``CONFIG_MODULE_SIG_SHA3_256`` :menuselection:`Sign modules with SHA3-256` + ``CONFIG_MODULE_SIG_SHA3_384`` :menuselection:`Sign modules with SHA3-384` + ``CONFIG_MODULE_SIG_SHA3_512`` :menuselection:`Sign modules with SHA3-512` =============================== ========================================== The algorithm selected here will also be built into the kernel (rather @@ -145,6 +146,10 @@ into vmlinux) using parameters in the:: file (which is also generated if it does not already exist). +One can select between RSA (``MODULE_SIG_KEY_TYPE_RSA``) and ECDSA +(``MODULE_SIG_KEY_TYPE_ECDSA``) to generate either RSA 4k or NIST +P-384 keypair. + It is strongly recommended that you provide your own x509.genkey file. Most notably, in the x509.genkey file, the req_distinguished_name section @@ -266,7 +271,7 @@ for which it has a public key. Otherwise, it will also load modules that are unsigned. Any module for which the kernel has a key, but which proves to have a signature mismatch will not be permitted to load. -Any module that has an unparseable signature will be rejected. +Any module that has an unparsable signature will be rejected. ========================================= diff --git a/Documentation/admin-guide/perf/alibaba_pmu.rst b/Documentation/admin-guide/perf/alibaba_pmu.rst index 11de998bb480..7d840023903f 100644 --- a/Documentation/admin-guide/perf/alibaba_pmu.rst +++ b/Documentation/admin-guide/perf/alibaba_pmu.rst @@ -88,6 +88,11 @@ data bandwidth:: -e ali_drw_27080/hif_rmw/ \ -e ali_drw_27080/cycle/ -- sleep 10 +Example usage of counting all memory read/write bandwidth by metric:: + + perf stat -M ddr_read_bandwidth.all -- sleep 10 + perf stat -M ddr_write_bandwidth.all -- sleep 10 + The average DRAM bandwidth can be calculated as follows: - Read Bandwidth = perf_hif_rd * DDRC_WIDTH * DDRC_Freq / DDRC_Cycle diff --git a/Documentation/admin-guide/perf/ampere_cspmu.rst b/Documentation/admin-guide/perf/ampere_cspmu.rst new file mode 100644 index 000000000000..94f93f5aee6c --- /dev/null +++ b/Documentation/admin-guide/perf/ampere_cspmu.rst @@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================ +Ampere SoC Performance Monitoring Unit (PMU) +============================================ + +Ampere SoC PMU is a generic PMU IP that follows Arm CoreSight PMU architecture. +Therefore, the driver is implemented as a submodule of arm_cspmu driver. At the +first phase it's used for counting MCU events on AmpereOne. + + +MCU PMU events +-------------- + +The PMU driver supports setting filters for "rank", "bank", and "threshold". +Note, that the filters are per PMU instance rather than per event. + + +Example for perf tool use:: + + / # perf list ampere + + ampere_mcu_pmu_0/act_sent/ [Kernel PMU event] + <...> + ampere_mcu_pmu_1/rd_sent/ [Kernel PMU event] + <...> + + / # perf stat -a -e ampere_mcu_pmu_0/act_sent,bank=5,rank=3,threshold=2/,ampere_mcu_pmu_1/rd_sent/ \ + sleep 1 diff --git a/Documentation/admin-guide/perf/index.rst b/Documentation/admin-guide/perf/index.rst index f60be04e4e33..a2e6f2c81146 100644 --- a/Documentation/admin-guide/perf/index.rst +++ b/Documentation/admin-guide/perf/index.rst @@ -22,3 +22,4 @@ Performance monitor support nvidia-pmu meson-ddr-pmu cxl + ampere_cspmu diff --git a/Documentation/admin-guide/pm/intel_idle.rst b/Documentation/admin-guide/pm/intel_idle.rst index b799a43da62e..39bd6ecce7de 100644 --- a/Documentation/admin-guide/pm/intel_idle.rst +++ b/Documentation/admin-guide/pm/intel_idle.rst @@ -170,7 +170,7 @@ and ``idle=nomwait``. If any of them is present in the kernel command line, the ``MWAIT`` instruction is not allowed to be used, so the initialization of ``intel_idle`` will fail. -Apart from that there are four module parameters recognized by ``intel_idle`` +Apart from that there are five module parameters recognized by ``intel_idle`` itself that can be set via the kernel command line (they cannot be updated via sysfs, so that is the only way to change their values). @@ -216,6 +216,21 @@ are ignored). The idle states disabled this way can be enabled (on a per-CPU basis) from user space via ``sysfs``. +The ``ibrs_off`` module parameter is a boolean flag (defaults to +false). If set, it is used to control if IBRS (Indirect Branch Restricted +Speculation) should be turned off when the CPU enters an idle state. +This flag does not affect CPUs that use Enhanced IBRS which can remain +on with little performance impact. + +For some CPUs, IBRS will be selected as mitigation for Spectre v2 and Retbleed +security vulnerabilities by default. Leaving the IBRS mode on while idling may +have a performance impact on its sibling CPU. The IBRS mode will be turned off +by default when the CPU enters into a deep idle state, but not in some +shallower ones. Setting the ``ibrs_off`` module parameter will force the IBRS +mode to off when the CPU is in any one of the available idle states. This may +help performance of a sibling CPU at the expense of a slightly higher wakeup +latency for the idle CPU. + .. _intel-idle-core-and-package-idle-states: diff --git a/Documentation/admin-guide/pstore-blk.rst b/Documentation/admin-guide/pstore-blk.rst index 2d22ead9520e..1bb2a1c292aa 100644 --- a/Documentation/admin-guide/pstore-blk.rst +++ b/Documentation/admin-guide/pstore-blk.rst @@ -76,7 +76,7 @@ kmsg_size ~~~~~~~~~ The chunk size in KB for oops/panic front-end. It **MUST** be a multiple of 4. -It's optional if you do not care oops/panic log. +It's optional if you do not care about the oops/panic log. There are multiple chunks for oops/panic front-end depending on the remaining space except other pstore front-ends. @@ -88,7 +88,7 @@ pmsg_size ~~~~~~~~~ The chunk size in KB for pmsg front-end. It **MUST** be a multiple of 4. -It's optional if you do not care pmsg log. +It's optional if you do not care about the pmsg log. Unlike oops/panic front-end, there is only one chunk for pmsg front-end. @@ -100,7 +100,7 @@ console_size ~~~~~~~~~~~~ The chunk size in KB for console front-end. It **MUST** be a multiple of 4. -It's optional if you do not care console log. +It's optional if you do not care about the console log. Similar to pmsg front-end, there is only one chunk for console front-end. @@ -111,7 +111,7 @@ ftrace_size ~~~~~~~~~~~ The chunk size in KB for ftrace front-end. It **MUST** be a multiple of 4. -It's optional if you do not care console log. +It's optional if you do not care about the ftrace log. Similar to oops front-end, there are multiple chunks for ftrace front-end depending on the count of cpu processors. Each chunk size is equal to diff --git a/Documentation/admin-guide/serial-console.rst b/Documentation/admin-guide/serial-console.rst index 8c8b94e54e26..a3dfc2c66e01 100644 --- a/Documentation/admin-guide/serial-console.rst +++ b/Documentation/admin-guide/serial-console.rst @@ -59,7 +59,7 @@ times. In this case, there are the following two rules: the hardware is not available. The result might be surprising. For example, the following two command -lines have the same result: +lines have the same result:: console=ttyS1,9600 console=tty0 console=tty1 console=tty0 console=ttyS1,9600 console=tty1 diff --git a/Documentation/admin-guide/spkguide.txt b/Documentation/admin-guide/spkguide.txt index 74ea7f391942..0d5965138f8f 100644 --- a/Documentation/admin-guide/spkguide.txt +++ b/Documentation/admin-guide/spkguide.txt @@ -7,7 +7,7 @@ Last modified on Mon Sep 27 14:26:31 2010 Document version 1.3 Copyright (c) 2005 Gene Collins -Copyright (c) 2008 Samuel Thibault +Copyright (c) 2008, 2023 Samuel Thibault Copyright (c) 2009, 2010 the Speakup Team Permission is granted to copy, distribute and/or modify this document @@ -83,8 +83,7 @@ spkout -- Speak Out txprt -- Transport dummy -- Plain text terminal -Note: Speakup does * NOT * support usb connections! Speakup also does * -NOT * support the internal Tripletalk! +Note: Speakup does * NOT * support the internal Tripletalk! Speakup does support two other synthesizers, but because they work in conjunction with other software, they must be loaded as modules after @@ -94,6 +93,12 @@ These are as follows: decpc -- DecTalk PC (not available at boot up) soft -- One of several software synthesizers (not available at boot up) +By default speakup looks for the synthesizer on the ttyS0 serial port. This can +be changed with the device parameter of the modules, for instance for +DoubleTalk LT: + +speakup_ltlk.dev=ttyUSB0 + See the sections on loading modules and software synthesizers later in this manual for further details. It should be noted here that the speakup.synth boot parameter will have no effect if Speakup has been diff --git a/Documentation/admin-guide/sysctl/fs.rst b/Documentation/admin-guide/sysctl/fs.rst index a321b84eccaa..47499a1742bd 100644 --- a/Documentation/admin-guide/sysctl/fs.rst +++ b/Documentation/admin-guide/sysctl/fs.rst @@ -42,16 +42,16 @@ pre-allocation or re-sizing of any kernel data structures. dentry-state ------------ -This file shows the values in ``struct dentry_stat``, as defined in -``linux/include/linux/dcache.h``:: +This file shows the values in ``struct dentry_stat_t``, as defined in +``fs/dcache.c``:: struct dentry_stat_t dentry_stat { - int nr_dentry; - int nr_unused; - int age_limit; /* age in seconds */ - int want_pages; /* pages requested by system */ - int nr_negative; /* # of unused negative dentries */ - int dummy; /* Reserved for future use */ + long nr_dentry; + long nr_unused; + long age_limit; /* age in seconds */ + long want_pages; /* pages requested by system */ + long nr_negative; /* # of unused negative dentries */ + long dummy; /* Reserved for future use */ }; Dentries are dynamically allocated and deallocated. diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 3800fab1619b..6584a1f9bfe3 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -436,7 +436,7 @@ ignore-unaligned-usertrap On architectures where unaligned accesses cause traps, and where this feature is supported (``CONFIG_SYSCTL_ARCH_UNALIGN_NO_WARN``; -currently, ``arc``, ``ia64`` and ``loongarch``), controls whether all +currently, ``arc`` and ``loongarch``), controls whether all unaligned traps are logged. = ============================================================= @@ -445,9 +445,35 @@ unaligned traps are logged. setting. = ============================================================= -See also `unaligned-trap`_ and `unaligned-dump-stack`_. On ``ia64``, -this allows system administrators to override the -``IA64_THREAD_UAC_NOPRINT`` ``prctl`` and avoid logs being flooded. +See also `unaligned-trap`_. + +io_uring_disabled +================= + +Prevents all processes from creating new io_uring instances. Enabling this +shrinks the kernel's attack surface. + += ====================================================================== +0 All processes can create io_uring instances as normal. This is the + default setting. +1 io_uring creation is disabled (io_uring_setup() will fail with + -EPERM) for unprivileged processes not in the io_uring_group group. + Existing io_uring instances can still be used. See the + documentation for io_uring_group for more information. +2 io_uring creation is disabled for all processes. io_uring_setup() + always fails with -EPERM. Existing io_uring instances can still be + used. += ====================================================================== + + +io_uring_group +============== + +When io_uring_disabled is set to 1, a process must either be +privileged (CAP_SYS_ADMIN) or be in the io_uring_group group in order +to create an io_uring instance. If io_uring_group is set to -1 (the +default), only processes with the CAP_SYS_ADMIN capability may create +io_uring instances. kexec_load_disabled @@ -941,16 +967,35 @@ enabled, otherwise writing to this file will return ``-EBUSY``. The default value is 8. -perf_user_access (arm64 only) -================================= +perf_user_access (arm64 and riscv only) +======================================= -Controls user space access for reading perf event counters. When set to 1, -user space can read performance monitor counter registers directly. +Controls user space access for reading perf event counters. + +arm64 +===== The default value is 0 (access disabled). +When set to 1, user space can read performance monitor counter registers +directly. + See Documentation/arch/arm64/perf.rst for more information. +riscv +===== + +When set to 0, user space access is disabled. + +The default value is 1, user space can read performance monitor counter +registers through perf, any direct access without perf intervention will trigger +an illegal instruction. + +When set to 2, which enables legacy mode (user space has direct access to cycle +and insret CSRs only). Note that this legacy value is deprecated and will be +removed once all user space applications are fixed. + +Note that the time CSR is always directly accessible to all modes. pid_max ======= @@ -1134,7 +1179,8 @@ automatically on platforms where it can run (that is, platforms with asymmetric CPU topologies and having an Energy Model available). If your platform happens to meet the requirements for EAS but you do not want to use it, change -this value to 0. +this value to 0. On Non-EAS platforms, write operation fails and +read doesn't return anything. task_delayacct =============== @@ -1490,22 +1536,6 @@ See Documentation/admin-guide/kernel-parameters.rst and Documentation/trace/boottime-trace.rst. -.. _unaligned-dump-stack: - -unaligned-dump-stack (ia64) -=========================== - -When logging unaligned accesses, controls whether the stack is -dumped. - -= =================================================== -0 Do not dump the stack. This is the default setting. -1 Dump the stack. -= =================================================== - -See also `ignore-unaligned-usertrap`_. - - unaligned-trap ============== diff --git a/Documentation/admin-guide/sysctl/net.rst b/Documentation/admin-guide/sysctl/net.rst index 4877563241f3..c7525942f12c 100644 --- a/Documentation/admin-guide/sysctl/net.rst +++ b/Documentation/admin-guide/sysctl/net.rst @@ -71,6 +71,7 @@ two flavors of JITs, the newer eBPF JIT currently supported on: - s390x - riscv64 - riscv32 + - loongarch64 And the older cBPF JIT supported on the following archs: diff --git a/Documentation/admin-guide/sysctl/vm.rst b/Documentation/admin-guide/sysctl/vm.rst index 45ba1f4dc004..c59889de122b 100644 --- a/Documentation/admin-guide/sysctl/vm.rst +++ b/Documentation/admin-guide/sysctl/vm.rst @@ -742,8 +742,8 @@ overcommit_memory This value contains a flag that enables memory overcommitment. -When this flag is 0, the kernel attempts to estimate the amount -of free memory left when userspace requests more memory. +When this flag is 0, the kernel compares the userspace memory request +size against total memory plus swap and rejects obvious overcommits. When this flag is 1, the kernel pretends there is always enough memory until it actually runs out. diff --git a/Documentation/admin-guide/xfs.rst b/Documentation/admin-guide/xfs.rst index 3a9c041d7f6c..b67772cf36d6 100644 --- a/Documentation/admin-guide/xfs.rst +++ b/Documentation/admin-guide/xfs.rst @@ -192,7 +192,7 @@ When mounting an XFS filesystem, the following options are accepted. are any integer multiple of a valid ``sunit`` value. Typically the only time these mount options are necessary if - after an underlying RAID device has had it's geometry + after an underlying RAID device has had its geometry modified, such as adding a new disk to a RAID5 lun and reshaping it. diff --git a/Documentation/arch/arm/arm.rst b/Documentation/arch/arm/arm.rst index 99d660fdf73f..7b41b89dd9bd 100644 --- a/Documentation/arch/arm/arm.rst +++ b/Documentation/arch/arm/arm.rst @@ -141,7 +141,7 @@ ST506 hard drives `*configure` harddrive set to 2). I've got an internal 20MB and a great big external 5.25" FH 64MB drive (who could ever want more :-) ). - I've just got 240K/s off it (a dd with bs=128k); thats about half of what + I've just got 240K/s off it (a dd with bs=128k); that's about half of what RiscOS gets; but it's a heck of a lot better than the 50K/s I was getting last week :-) diff --git a/Documentation/arch/arm/ixp4xx.rst b/Documentation/arch/arm/ixp4xx.rst index a57235616294..17aafc610908 100644 --- a/Documentation/arch/arm/ixp4xx.rst +++ b/Documentation/arch/arm/ixp4xx.rst @@ -78,9 +78,9 @@ IXP4xx provides two methods of accessing PCI memory space: 1) A direct mapped window from 0x48000000 to 0x4bffffff (64MB). To access PCI via this space, we simply ioremap() the BAR into the kernel and we can use the standard read[bwl]/write[bwl] - macros. This is the preffered method due to speed but it + macros. This is the preferred method due to speed but it limits the system to just 64MB of PCI memory. This can be - problamatic if using video cards and other memory-heavy devices. + problematic if using video cards and other memory-heavy devices. 2) If > 64MB of memory space is required, the IXP4xx can be configured to use indirect registers to access PCI This allows diff --git a/Documentation/arch/arm/sunxi/clocks.rst b/Documentation/arch/arm/sunxi/clocks.rst index 23bd03f3e21f..dfe6d4887210 100644 --- a/Documentation/arch/arm/sunxi/clocks.rst +++ b/Documentation/arch/arm/sunxi/clocks.rst @@ -5,7 +5,7 @@ Frequently asked questions about the sunxi clock system This document contains useful bits of information that people tend to ask about the sunxi clock system, as well as accompanying ASCII art when adequate. -Q: Why is the main 24MHz oscillator gatable? Wouldn't that break the +Q: Why is the main 24MHz oscillator gateable? Wouldn't that break the system? A: The 24MHz oscillator allows gating to save power. Indeed, if gated diff --git a/Documentation/arch/arm/swp_emulation.rst b/Documentation/arch/arm/swp_emulation.rst index 6a608a9c3715..bf205e3de36e 100644 --- a/Documentation/arch/arm/swp_emulation.rst +++ b/Documentation/arch/arm/swp_emulation.rst @@ -1,7 +1,7 @@ Software emulation of deprecated SWP instruction (CONFIG_SWP_EMULATE) --------------------------------------------------------------------- -ARMv6 architecture deprecates use of the SWP/SWPB instructions, and recommeds +ARMv6 architecture deprecates use of the SWP/SWPB instructions, and recommends moving to the load-locked/store-conditional instructions LDREX and STREX. ARMv7 multiprocessing extensions introduce the ability to disable these diff --git a/Documentation/arch/arm/tcm.rst b/Documentation/arch/arm/tcm.rst index 1dc6c39220f9..7ce17a248af9 100644 --- a/Documentation/arch/arm/tcm.rst +++ b/Documentation/arch/arm/tcm.rst @@ -71,7 +71,7 @@ in <asm/tcm.h>. Using this interface it is possible to: - Have the remaining TCM RAM added to a special allocation pool with gen_pool_create() and gen_pool_add() - and provice tcm_alloc() and tcm_free() for this + and provide tcm_alloc() and tcm_free() for this memory. Such a heap is great for things like saving device state when shutting off device power domains. diff --git a/Documentation/arch/arm/uefi.rst b/Documentation/arch/arm/uefi.rst index baebe688a006..2b7ad9bd7cd2 100644 --- a/Documentation/arch/arm/uefi.rst +++ b/Documentation/arch/arm/uefi.rst @@ -50,7 +50,7 @@ The stub populates the FDT /chosen node with (and the kernel scans for) the following parameters: ========================== ====== =========================================== -Name Size Description +Name Type Description ========================== ====== =========================================== linux,uefi-system-table 64-bit Physical address of the UEFI System Table. @@ -67,4 +67,6 @@ linux,uefi-mmap-desc-ver 32-bit Version of the mmap descriptor format. kaslr-seed 64-bit Entropy used to randomize the kernel image base address location. + +bootargs String Kernel command line ========================== ====== =========================================== diff --git a/Documentation/arch/arm/vlocks.rst b/Documentation/arch/arm/vlocks.rst index a40a1742110b..737aa8661a21 100644 --- a/Documentation/arch/arm/vlocks.rst +++ b/Documentation/arch/arm/vlocks.rst @@ -155,7 +155,7 @@ the basic algorithm: optimisation. If there are too many CPUs to read the currently_voting array in - one transaction then multiple transations are still required. The + one transaction then multiple transactions are still required. The implementation uses a simple loop of word-sized loads for this case. The number of transactions is still fewer than would be required if bytes were loaded individually. diff --git a/Documentation/arch/arm64/acpi_object_usage.rst b/Documentation/arch/arm64/acpi_object_usage.rst index 1da22200fdf8..06d8a87971ef 100644 --- a/Documentation/arch/arm64/acpi_object_usage.rst +++ b/Documentation/arch/arm64/acpi_object_usage.rst @@ -45,7 +45,7 @@ APMT Signature Reserved (signature == "APMT") **Arm Performance Monitoring Table** - This table describes the properties of PMU support implmented by + This table describes the properties of PMU support implemented by components in the system. BERT Section 18.3 (signature == "BERT") diff --git a/Documentation/arch/arm64/arm-acpi.rst b/Documentation/arch/arm64/arm-acpi.rst index 94274a8d84cf..a46c34fa9604 100644 --- a/Documentation/arch/arm64/arm-acpi.rst +++ b/Documentation/arch/arm64/arm-acpi.rst @@ -99,7 +99,7 @@ to replace the kernel. When a Linux driver or subsystem is first implemented using ACPI, it by definition ends up requiring a specific version of the ACPI specification --- it's baseline. ACPI firmware must continue to work, even though it may +-- its baseline. ACPI firmware must continue to work, even though it may not be optimal, with the earliest kernel version that first provides support for that baseline version of ACPI. There may be a need for additional drivers, but adding new functionality (e.g., CPU power management) should not break diff --git a/Documentation/arch/arm64/cpu-feature-registers.rst b/Documentation/arch/arm64/cpu-feature-registers.rst index 4e4625f2455f..44f9bd78539d 100644 --- a/Documentation/arch/arm64/cpu-feature-registers.rst +++ b/Documentation/arch/arm64/cpu-feature-registers.rst @@ -175,6 +175,8 @@ infrastructure: +------------------------------+---------+---------+ | Name | bits | visible | +------------------------------+---------+---------+ + | SME | [27-24] | y | + +------------------------------+---------+---------+ | MTE | [11-8] | y | +------------------------------+---------+---------+ | SSBS | [7-4] | y | @@ -266,6 +268,8 @@ infrastructure: +------------------------------+---------+---------+ | SHA3 | [35-32] | y | +------------------------------+---------+---------+ + | B16B16 | [27-24] | y | + +------------------------------+---------+---------+ | BF16 | [23-20] | y | +------------------------------+---------+---------+ | BitPerm | [19-16] | y | @@ -288,8 +292,18 @@ infrastructure: +------------------------------+---------+---------+ | Name | bits | visible | +------------------------------+---------+---------+ + | CSSC | [55-52] | y | + +------------------------------+---------+---------+ + | RPRFM | [51-48] | y | + +------------------------------+---------+---------+ + | BC | [23-20] | y | + +------------------------------+---------+---------+ | MOPS | [19-16] | y | +------------------------------+---------+---------+ + | APA3 | [15-12] | y | + +------------------------------+---------+---------+ + | GPA3 | [11-8] | y | + +------------------------------+---------+---------+ | RPRES | [7-4] | y | +------------------------------+---------+---------+ | WFXT | [3-0] | y | diff --git a/Documentation/arch/arm64/elf_hwcaps.rst b/Documentation/arch/arm64/elf_hwcaps.rst index 8c8addb4194c..4b8399ac592b 100644 --- a/Documentation/arch/arm64/elf_hwcaps.rst +++ b/Documentation/arch/arm64/elf_hwcaps.rst @@ -305,6 +305,18 @@ HWCAP2_SMEF16F16 HWCAP2_MOPS Functionality implied by ID_AA64ISAR2_EL1.MOPS == 0b0001. +HWCAP2_HBC + Functionality implied by ID_AA64ISAR2_EL1.BC == 0b0001. + +HWCAP2_SVE_B16B16 + Functionality implied by ID_AA64ZFR0_EL1.B16B16 == 0b0001. + +HWCAP2_LRCPC3 + Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0011. + +HWCAP2_LSE128 + Functionality implied by ID_AA64ISAR0_EL1.Atomic == 0b0011. + 4. Unused AT_HWCAP bits ----------------------- diff --git a/Documentation/arch/arm64/silicon-errata.rst b/Documentation/arch/arm64/silicon-errata.rst index 496cdca5cb99..f47f63bcf67c 100644 --- a/Documentation/arch/arm64/silicon-errata.rst +++ b/Documentation/arch/arm64/silicon-errata.rst @@ -63,6 +63,16 @@ stable kernels. +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A510 | #1902691 | ARM64_ERRATUM_1902691 | +----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A510 | #2051678 | ARM64_ERRATUM_2051678 | ++----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A510 | #2077057 | ARM64_ERRATUM_2077057 | ++----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A510 | #2441009 | ARM64_ERRATUM_2441009 | ++----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A510 | #2658417 | ARM64_ERRATUM_2658417 | ++----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A520 | #2966298 | ARM64_ERRATUM_2966298 | ++----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A53 | #826319 | ARM64_ERRATUM_826319 | +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A53 | #827319 | ARM64_ERRATUM_827319 | @@ -109,14 +119,6 @@ stable kernels. +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A77 | #1508412 | ARM64_ERRATUM_1508412 | +----------------+-----------------+-----------------+-----------------------------+ -| ARM | Cortex-A510 | #2051678 | ARM64_ERRATUM_2051678 | -+----------------+-----------------+-----------------+-----------------------------+ -| ARM | Cortex-A510 | #2077057 | ARM64_ERRATUM_2077057 | -+----------------+-----------------+-----------------+-----------------------------+ -| ARM | Cortex-A510 | #2441009 | ARM64_ERRATUM_2441009 | -+----------------+-----------------+-----------------+-----------------------------+ -| ARM | Cortex-A510 | #2658417 | ARM64_ERRATUM_2658417 | -+----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A710 | #2119858 | ARM64_ERRATUM_2119858 | +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A710 | #2054223 | ARM64_ERRATUM_2054223 | @@ -148,6 +150,9 @@ stable kernels. | ARM | MMU-700 | #2268618,2812531| N/A | +----------------+-----------------+-----------------+-----------------------------+ +----------------+-----------------+-----------------+-----------------------------+ +| ARM | GIC-700 | #2941627 | ARM64_ERRATUM_2941627 | ++----------------+-----------------+-----------------+-----------------------------+ ++----------------+-----------------+-----------------+-----------------------------+ | Broadcom | Brahma-B53 | N/A | ARM64_ERRATUM_845719 | +----------------+-----------------+-----------------+-----------------------------+ | Broadcom | Brahma-B53 | N/A | ARM64_ERRATUM_843419 | @@ -195,6 +200,9 @@ stable kernels. +----------------+-----------------+-----------------+-----------------------------+ | Hisilicon | Hip08 SMMU PMCG | #162001800 | N/A | +----------------+-----------------+-----------------+-----------------------------+ +| Hisilicon | Hip08 SMMU PMCG | #162001900 | N/A | +| | Hip09 SMMU PMCG | | | ++----------------+-----------------+-----------------+-----------------------------+ +----------------+-----------------+-----------------+-----------------------------+ | Qualcomm Tech. | Kryo/Falkor v1 | E1003 | QCOM_FALKOR_ERRATUM_1003 | +----------------+-----------------+-----------------+-----------------------------+ diff --git a/Documentation/arch/arm64/sme.rst b/Documentation/arch/arm64/sme.rst index ba529a1dc606..3d0e53ecac4f 100644 --- a/Documentation/arch/arm64/sme.rst +++ b/Documentation/arch/arm64/sme.rst @@ -322,7 +322,7 @@ The regset data starts with struct user_za_header, containing: VL is supported. * The size and layout of the payload depends on the header fields. The - SME_PT_ZA_*() macros are provided to facilitate access to the data. + ZA_PT_ZA*() macros are provided to facilitate access to the data. * In either case, for SETREGSET it is permissible to omit the payload, in which case the vector length and flags are changed and PSTATE.ZA is set to 0 diff --git a/Documentation/arch/ia64/aliasing.rst b/Documentation/arch/ia64/aliasing.rst deleted file mode 100644 index 36a1e1d4842b..000000000000 --- a/Documentation/arch/ia64/aliasing.rst +++ /dev/null @@ -1,246 +0,0 @@ -================================== -Memory Attribute Aliasing on IA-64 -================================== - -Bjorn Helgaas <bjorn.helgaas@hp.com> - -May 4, 2006 - - -Memory Attributes -================= - - Itanium supports several attributes for virtual memory references. - The attribute is part of the virtual translation, i.e., it is - contained in the TLB entry. The ones of most interest to the Linux - kernel are: - - == ====================== - WB Write-back (cacheable) - UC Uncacheable - WC Write-coalescing - == ====================== - - System memory typically uses the WB attribute. The UC attribute is - used for memory-mapped I/O devices. The WC attribute is uncacheable - like UC is, but writes may be delayed and combined to increase - performance for things like frame buffers. - - The Itanium architecture requires that we avoid accessing the same - page with both a cacheable mapping and an uncacheable mapping[1]. - - The design of the chipset determines which attributes are supported - on which regions of the address space. For example, some chipsets - support either WB or UC access to main memory, while others support - only WB access. - -Memory Map -========== - - Platform firmware describes the physical memory map and the - supported attributes for each region. At boot-time, the kernel uses - the EFI GetMemoryMap() interface. ACPI can also describe memory - devices and the attributes they support, but Linux/ia64 currently - doesn't use this information. - - The kernel uses the efi_memmap table returned from GetMemoryMap() to - learn the attributes supported by each region of physical address - space. Unfortunately, this table does not completely describe the - address space because some machines omit some or all of the MMIO - regions from the map. - - The kernel maintains another table, kern_memmap, which describes the - memory Linux is actually using and the attribute for each region. - This contains only system memory; it does not contain MMIO space. - - The kern_memmap table typically contains only a subset of the system - memory described by the efi_memmap. Linux/ia64 can't use all memory - in the system because of constraints imposed by the identity mapping - scheme. - - The efi_memmap table is preserved unmodified because the original - boot-time information is required for kexec. - -Kernel Identity Mappings -======================== - - Linux/ia64 identity mappings are done with large pages, currently - either 16MB or 64MB, referred to as "granules." Cacheable mappings - are speculative[2], so the processor can read any location in the - page at any time, independent of the programmer's intentions. This - means that to avoid attribute aliasing, Linux can create a cacheable - identity mapping only when the entire granule supports cacheable - access. - - Therefore, kern_memmap contains only full granule-sized regions that - can referenced safely by an identity mapping. - - Uncacheable mappings are not speculative, so the processor will - generate UC accesses only to locations explicitly referenced by - software. This allows UC identity mappings to cover granules that - are only partially populated, or populated with a combination of UC - and WB regions. - -User Mappings -============= - - User mappings are typically done with 16K or 64K pages. The smaller - page size allows more flexibility because only 16K or 64K has to be - homogeneous with respect to memory attributes. - -Potential Attribute Aliasing Cases -================================== - - There are several ways the kernel creates new mappings: - -mmap of /dev/mem ----------------- - - This uses remap_pfn_range(), which creates user mappings. These - mappings may be either WB or UC. If the region being mapped - happens to be in kern_memmap, meaning that it may also be mapped - by a kernel identity mapping, the user mapping must use the same - attribute as the kernel mapping. - - If the region is not in kern_memmap, the user mapping should use - an attribute reported as being supported in the EFI memory map. - - Since the EFI memory map does not describe MMIO on some - machines, this should use an uncacheable mapping as a fallback. - -mmap of /sys/class/pci_bus/.../legacy_mem ------------------------------------------ - - This is very similar to mmap of /dev/mem, except that legacy_mem - only allows mmap of the one megabyte "legacy MMIO" area for a - specific PCI bus. Typically this is the first megabyte of - physical address space, but it may be different on machines with - several VGA devices. - - "X" uses this to access VGA frame buffers. Using legacy_mem - rather than /dev/mem allows multiple instances of X to talk to - different VGA cards. - - The /dev/mem mmap constraints apply. - -mmap of /proc/bus/pci/.../??.? ------------------------------- - - This is an MMIO mmap of PCI functions, which additionally may or - may not be requested as using the WC attribute. - - If WC is requested, and the region in kern_memmap is either WC - or UC, and the EFI memory map designates the region as WC, then - the WC mapping is allowed. - - Otherwise, the user mapping must use the same attribute as the - kernel mapping. - -read/write of /dev/mem ----------------------- - - This uses copy_from_user(), which implicitly uses a kernel - identity mapping. This is obviously safe for things in - kern_memmap. - - There may be corner cases of things that are not in kern_memmap, - but could be accessed this way. For example, registers in MMIO - space are not in kern_memmap, but could be accessed with a UC - mapping. This would not cause attribute aliasing. But - registers typically can be accessed only with four-byte or - eight-byte accesses, and the copy_from_user() path doesn't allow - any control over the access size, so this would be dangerous. - -ioremap() ---------- - - This returns a mapping for use inside the kernel. - - If the region is in kern_memmap, we should use the attribute - specified there. - - If the EFI memory map reports that the entire granule supports - WB, we should use that (granules that are partially reserved - or occupied by firmware do not appear in kern_memmap). - - If the granule contains non-WB memory, but we can cover the - region safely with kernel page table mappings, we can use - ioremap_page_range() as most other architectures do. - - Failing all of the above, we have to fall back to a UC mapping. - -Past Problem Cases -================== - -mmap of various MMIO regions from /dev/mem by "X" on Intel platforms --------------------------------------------------------------------- - - The EFI memory map may not report these MMIO regions. - - These must be allowed so that X will work. This means that - when the EFI memory map is incomplete, every /dev/mem mmap must - succeed. It may create either WB or UC user mappings, depending - on whether the region is in kern_memmap or the EFI memory map. - -mmap of 0x0-0x9FFFF /dev/mem by "hwinfo" on HP sx1000 with VGA enabled ----------------------------------------------------------------------- - - The EFI memory map reports the following attributes: - - =============== ======= ================== - 0x00000-0x9FFFF WB only - 0xA0000-0xBFFFF UC only (VGA frame buffer) - 0xC0000-0xFFFFF WB only - =============== ======= ================== - - This mmap is done with user pages, not kernel identity mappings, - so it is safe to use WB mappings. - - The kernel VGA driver may ioremap the VGA frame buffer at 0xA0000, - which uses a granule-sized UC mapping. This granule will cover some - WB-only memory, but since UC is non-speculative, the processor will - never generate an uncacheable reference to the WB-only areas unless - the driver explicitly touches them. - -mmap of 0x0-0xFFFFF legacy_mem by "X" -------------------------------------- - - If the EFI memory map reports that the entire range supports the - same attributes, we can allow the mmap (and we will prefer WB if - supported, as is the case with HP sx[12]000 machines with VGA - disabled). - - If EFI reports the range as partly WB and partly UC (as on sx[12]000 - machines with VGA enabled), we must fail the mmap because there's no - safe attribute to use. - - If EFI reports some of the range but not all (as on Intel firmware - that doesn't report the VGA frame buffer at all), we should fail the - mmap and force the user to map just the specific region of interest. - -mmap of 0xA0000-0xBFFFF legacy_mem by "X" on HP sx1000 with VGA disabled ------------------------------------------------------------------------- - - The EFI memory map reports the following attributes:: - - 0x00000-0xFFFFF WB only (no VGA MMIO hole) - - This is a special case of the previous case, and the mmap should - fail for the same reason as above. - -read of /sys/devices/.../rom ----------------------------- - - For VGA devices, this may cause an ioremap() of 0xC0000. This - used to be done with a UC mapping, because the VGA frame buffer - at 0xA0000 prevents use of a WB granule. The UC mapping causes - an MCA on HP sx[12]000 chipsets. - - We should use WB page table mappings to avoid covering the VGA - frame buffer. - -Notes -===== - - [1] SDM rev 2.2, vol 2, sec 4.4.1. - [2] SDM rev 2.2, vol 2, sec 4.4.6. diff --git a/Documentation/arch/ia64/efirtc.rst b/Documentation/arch/ia64/efirtc.rst deleted file mode 100644 index fd8328408301..000000000000 --- a/Documentation/arch/ia64/efirtc.rst +++ /dev/null @@ -1,144 +0,0 @@ -========================== -EFI Real Time Clock driver -========================== - -S. Eranian <eranian@hpl.hp.com> - -March 2000 - -1. Introduction -=============== - -This document describes the efirtc.c driver has provided for -the IA-64 platform. - -The purpose of this driver is to supply an API for kernel and user applications -to get access to the Time Service offered by EFI version 0.92. - -EFI provides 4 calls one can make once the OS is booted: GetTime(), -SetTime(), GetWakeupTime(), SetWakeupTime() which are all supported by this -driver. We describe those calls as well the design of the driver in the -following sections. - -2. Design Decisions -=================== - -The original ideas was to provide a very simple driver to get access to, -at first, the time of day service. This is required in order to access, in a -portable way, the CMOS clock. A program like /sbin/hwclock uses such a clock -to initialize the system view of the time during boot. - -Because we wanted to minimize the impact on existing user-level apps using -the CMOS clock, we decided to expose an API that was very similar to the one -used today with the legacy RTC driver (driver/char/rtc.c). However, because -EFI provides a simpler services, not all ioctl() are available. Also -new ioctl()s have been introduced for things that EFI provides but not the -legacy. - -EFI uses a slightly different way of representing the time, noticeably -the reference date is different. Year is the using the full 4-digit format. -The Epoch is January 1st 1998. For backward compatibility reasons we don't -expose this new way of representing time. Instead we use something very -similar to the struct tm, i.e. struct rtc_time, as used by hwclock. -One of the reasons for doing it this way is to allow for EFI to still evolve -without necessarily impacting any of the user applications. The decoupling -enables flexibility and permits writing wrapper code is ncase things change. - -The driver exposes two interfaces, one via the device file and a set of -ioctl()s. The other is read-only via the /proc filesystem. - -As of today we don't offer a /proc/sys interface. - -To allow for a uniform interface between the legacy RTC and EFI time service, -we have created the include/linux/rtc.h header file to contain only the -"public" API of the two drivers. The specifics of the legacy RTC are still -in include/linux/mc146818rtc.h. - - -3. Time of day service -====================== - -The part of the driver gives access to the time of day service of EFI. -Two ioctl()s, compatible with the legacy RTC calls: - - Read the CMOS clock:: - - ioctl(d, RTC_RD_TIME, &rtc); - - Write the CMOS clock:: - - ioctl(d, RTC_SET_TIME, &rtc); - -The rtc is a pointer to a data structure defined in rtc.h which is close -to a struct tm:: - - struct rtc_time { - int tm_sec; - int tm_min; - int tm_hour; - int tm_mday; - int tm_mon; - int tm_year; - int tm_wday; - int tm_yday; - int tm_isdst; - }; - -The driver takes care of converting back an forth between the EFI time and -this format. - -Those two ioctl()s can be exercised with the hwclock command: - -For reading:: - - # /sbin/hwclock --show - Mon Mar 6 15:32:32 2000 -0.910248 seconds - -For setting:: - - # /sbin/hwclock --systohc - -Root privileges are required to be able to set the time of day. - -4. Wakeup Alarm service -======================= - -EFI provides an API by which one can program when a machine should wakeup, -i.e. reboot. This is very different from the alarm provided by the legacy -RTC which is some kind of interval timer alarm. For this reason we don't use -the same ioctl()s to get access to the service. Instead we have -introduced 2 news ioctl()s to the interface of an RTC. - -We have added 2 new ioctl()s that are specific to the EFI driver: - - Read the current state of the alarm:: - - ioctl(d, RTC_WKALM_RD, &wkt) - - Set the alarm or change its status:: - - ioctl(d, RTC_WKALM_SET, &wkt) - -The wkt structure encapsulates a struct rtc_time + 2 extra fields to get -status information:: - - struct rtc_wkalrm { - - unsigned char enabled; /* =1 if alarm is enabled */ - unsigned char pending; /* =1 if alarm is pending */ - - struct rtc_time time; - } - -As of today, none of the existing user-level apps supports this feature. -However writing such a program should be hard by simply using those two -ioctl(). - -Root privileges are required to be able to set the alarm. - -5. References -============= - -Checkout the following Web site for more information on EFI: - -http://developer.intel.com/technology/efi/ diff --git a/Documentation/arch/ia64/err_inject.rst b/Documentation/arch/ia64/err_inject.rst deleted file mode 100644 index 900f71e93a29..000000000000 --- a/Documentation/arch/ia64/err_inject.rst +++ /dev/null @@ -1,1067 +0,0 @@ -======================================== -IPF Machine Check (MC) error inject tool -======================================== - -IPF Machine Check (MC) error inject tool is used to inject MC -errors from Linux. The tool is a test bed for IPF MC work flow including -hardware correctable error handling, OS recoverable error handling, MC -event logging, etc. - -The tool includes two parts: a kernel driver and a user application -sample. The driver provides interface to PAL to inject error -and query error injection capabilities. The driver code is in -arch/ia64/kernel/err_inject.c. The application sample (shown below) -provides a combination of various errors and calls the driver's interface -(sysfs interface) to inject errors or query error injection capabilities. - -The tool can be used to test Intel IPF machine MC handling capabilities. -It's especially useful for people who can not access hardware MC injection -tool to inject error. It's also very useful to integrate with other -software test suits to do stressful testing on IPF. - -Below is a sample application as part of the whole tool. The sample -can be used as a working test tool. Or it can be expanded to include -more features. It also can be a integrated into a library or other user -application to have more thorough test. - -The sample application takes err.conf as error configuration input. GCC -compiles the code. After you install err_inject driver, you can run -this sample application to inject errors. - -Errata: Itanium 2 Processors Specification Update lists some errata against -the pal_mc_error_inject PAL procedure. The following err.conf has been tested -on latest Montecito PAL. - -err.conf:: - - #This is configuration file for err_inject_tool. - #The format of the each line is: - #cpu, loop, interval, err_type_info, err_struct_info, err_data_buffer - #where - # cpu: logical cpu number the error will be inject in. - # loop: times the error will be injected. - # interval: In second. every so often one error is injected. - # err_type_info, err_struct_info: PAL parameters. - # - #Note: All values are hex w/o or w/ 0x prefix. - - - #On cpu2, inject only total 0x10 errors, interval 5 seconds - #corrected, data cache, hier-2, physical addr(assigned by tool code). - #working on Montecito latest PAL. - 2, 10, 5, 4101, 95 - - #On cpu4, inject and consume total 0x10 errors, interval 5 seconds - #corrected, data cache, hier-2, physical addr(assigned by tool code). - #working on Montecito latest PAL. - 4, 10, 5, 4109, 95 - - #On cpu15, inject and consume total 0x10 errors, interval 5 seconds - #recoverable, DTR0, hier-2. - #working on Montecito latest PAL. - 0xf, 0x10, 5, 4249, 15 - -The sample application source code: - -err_injection_tool.c:: - - /* - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, but - * WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or - * NON INFRINGEMENT. See the GNU General Public License for more - * details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - * - * Copyright (C) 2006 Intel Co - * Fenghua Yu <fenghua.yu@intel.com> - * - */ - #include <sys/types.h> - #include <sys/stat.h> - #include <fcntl.h> - #include <stdio.h> - #include <sched.h> - #include <unistd.h> - #include <stdlib.h> - #include <stdarg.h> - #include <string.h> - #include <errno.h> - #include <time.h> - #include <sys/ipc.h> - #include <sys/sem.h> - #include <sys/wait.h> - #include <sys/mman.h> - #include <sys/shm.h> - - #define MAX_FN_SIZE 256 - #define MAX_BUF_SIZE 256 - #define DATA_BUF_SIZE 256 - #define NR_CPUS 512 - #define MAX_TASK_NUM 2048 - #define MIN_INTERVAL 5 // seconds - #define ERR_DATA_BUFFER_SIZE 3 // Three 8-byte. - #define PARA_FIELD_NUM 5 - #define MASK_SIZE (NR_CPUS/64) - #define PATH_FORMAT "/sys/devices/system/cpu/cpu%d/err_inject/" - - int sched_setaffinity(pid_t pid, unsigned int len, unsigned long *mask); - - int verbose; - #define vbprintf if (verbose) printf - - int log_info(int cpu, const char *fmt, ...) - { - FILE *log; - char fn[MAX_FN_SIZE]; - char buf[MAX_BUF_SIZE]; - va_list args; - - sprintf(fn, "%d.log", cpu); - log=fopen(fn, "a+"); - if (log==NULL) { - perror("Error open:"); - return -1; - } - - va_start(args, fmt); - vprintf(fmt, args); - memset(buf, 0, MAX_BUF_SIZE); - vsprintf(buf, fmt, args); - va_end(args); - - fwrite(buf, sizeof(buf), 1, log); - fclose(log); - - return 0; - } - - typedef unsigned long u64; - typedef unsigned int u32; - - typedef union err_type_info_u { - struct { - u64 mode : 3, /* 0-2 */ - err_inj : 3, /* 3-5 */ - err_sev : 2, /* 6-7 */ - err_struct : 5, /* 8-12 */ - struct_hier : 3, /* 13-15 */ - reserved : 48; /* 16-63 */ - } err_type_info_u; - u64 err_type_info; - } err_type_info_t; - - typedef union err_struct_info_u { - struct { - u64 siv : 1, /* 0 */ - c_t : 2, /* 1-2 */ - cl_p : 3, /* 3-5 */ - cl_id : 3, /* 6-8 */ - cl_dp : 1, /* 9 */ - reserved1 : 22, /* 10-31 */ - tiv : 1, /* 32 */ - trigger : 4, /* 33-36 */ - trigger_pl : 3, /* 37-39 */ - reserved2 : 24; /* 40-63 */ - } err_struct_info_cache; - struct { - u64 siv : 1, /* 0 */ - tt : 2, /* 1-2 */ - tc_tr : 2, /* 3-4 */ - tr_slot : 8, /* 5-12 */ - reserved1 : 19, /* 13-31 */ - tiv : 1, /* 32 */ - trigger : 4, /* 33-36 */ - trigger_pl : 3, /* 37-39 */ - reserved2 : 24; /* 40-63 */ - } err_struct_info_tlb; - struct { - u64 siv : 1, /* 0 */ - regfile_id : 4, /* 1-4 */ - reg_num : 7, /* 5-11 */ - reserved1 : 20, /* 12-31 */ - tiv : 1, /* 32 */ - trigger : 4, /* 33-36 */ - trigger_pl : 3, /* 37-39 */ - reserved2 : 24; /* 40-63 */ - } err_struct_info_register; - struct { - u64 reserved; - } err_struct_info_bus_processor_interconnect; - u64 err_struct_info; - } err_struct_info_t; - - typedef union err_data_buffer_u { - struct { - u64 trigger_addr; /* 0-63 */ - u64 inj_addr; /* 64-127 */ - u64 way : 5, /* 128-132 */ - index : 20, /* 133-152 */ - : 39; /* 153-191 */ - } err_data_buffer_cache; - struct { - u64 trigger_addr; /* 0-63 */ - u64 inj_addr; /* 64-127 */ - u64 way : 5, /* 128-132 */ - index : 20, /* 133-152 */ - reserved : 39; /* 153-191 */ - } err_data_buffer_tlb; - struct { - u64 trigger_addr; /* 0-63 */ - } err_data_buffer_register; - struct { - u64 reserved; /* 0-63 */ - } err_data_buffer_bus_processor_interconnect; - u64 err_data_buffer[ERR_DATA_BUFFER_SIZE]; - } err_data_buffer_t; - - typedef union capabilities_u { - struct { - u64 i : 1, - d : 1, - rv : 1, - tag : 1, - data : 1, - mesi : 1, - dp : 1, - reserved1 : 3, - pa : 1, - va : 1, - wi : 1, - reserved2 : 20, - trigger : 1, - trigger_pl : 1, - reserved3 : 30; - } capabilities_cache; - struct { - u64 d : 1, - i : 1, - rv : 1, - tc : 1, - tr : 1, - reserved1 : 27, - trigger : 1, - trigger_pl : 1, - reserved2 : 30; - } capabilities_tlb; - struct { - u64 gr_b0 : 1, - gr_b1 : 1, - fr : 1, - br : 1, - pr : 1, - ar : 1, - cr : 1, - rr : 1, - pkr : 1, - dbr : 1, - ibr : 1, - pmc : 1, - pmd : 1, - reserved1 : 3, - regnum : 1, - reserved2 : 15, - trigger : 1, - trigger_pl : 1, - reserved3 : 30; - } capabilities_register; - struct { - u64 reserved; - } capabilities_bus_processor_interconnect; - } capabilities_t; - - typedef struct resources_s { - u64 ibr0 : 1, - ibr2 : 1, - ibr4 : 1, - ibr6 : 1, - dbr0 : 1, - dbr2 : 1, - dbr4 : 1, - dbr6 : 1, - reserved : 48; - } resources_t; - - - long get_page_size(void) - { - long page_size=sysconf(_SC_PAGESIZE); - return page_size; - } - - #define PAGE_SIZE (get_page_size()==-1?0x4000:get_page_size()) - #define SHM_SIZE (2*PAGE_SIZE*NR_CPUS) - #define SHM_VA 0x2000000100000000 - - int shmid; - void *shmaddr; - - int create_shm(void) - { - key_t key; - char fn[MAX_FN_SIZE]; - - /* cpu0 is always existing */ - sprintf(fn, PATH_FORMAT, 0); - if ((key = ftok(fn, 's')) == -1) { - perror("ftok"); - return -1; - } - - shmid = shmget(key, SHM_SIZE, 0644 | IPC_CREAT); - if (shmid == -1) { - if (errno==EEXIST) { - shmid = shmget(key, SHM_SIZE, 0); - if (shmid == -1) { - perror("shmget"); - return -1; - } - } - else { - perror("shmget"); - return -1; - } - } - vbprintf("shmid=%d", shmid); - - /* connect to the segment: */ - shmaddr = shmat(shmid, (void *)SHM_VA, 0); - if (shmaddr == (void*)-1) { - perror("shmat"); - return -1; - } - - memset(shmaddr, 0, SHM_SIZE); - mlock(shmaddr, SHM_SIZE); - - return 0; - } - - int free_shm() - { - munlock(shmaddr, SHM_SIZE); - shmdt(shmaddr); - semctl(shmid, 0, IPC_RMID); - - return 0; - } - - #ifdef _SEM_SEMUN_UNDEFINED - union semun - { - int val; - struct semid_ds *buf; - unsigned short int *array; - struct seminfo *__buf; - }; - #endif - - u32 mode=1; /* 1: physical mode; 2: virtual mode. */ - int one_lock=1; - key_t key[NR_CPUS]; - int semid[NR_CPUS]; - - int create_sem(int cpu) - { - union semun arg; - char fn[MAX_FN_SIZE]; - int sid; - - sprintf(fn, PATH_FORMAT, cpu); - sprintf(fn, "%s/%s", fn, "err_type_info"); - if ((key[cpu] = ftok(fn, 'e')) == -1) { - perror("ftok"); - return -1; - } - - if (semid[cpu]!=0) - return 0; - - /* clear old semaphore */ - if ((sid = semget(key[cpu], 1, 0)) != -1) - semctl(sid, 0, IPC_RMID); - - /* get one semaphore */ - if ((semid[cpu] = semget(key[cpu], 1, IPC_CREAT | IPC_EXCL)) == -1) { - perror("semget"); - printf("Please remove semaphore with key=0x%lx, then run the tool.\n", - (u64)key[cpu]); - return -1; - } - - vbprintf("semid[%d]=0x%lx, key[%d]=%lx\n",cpu,(u64)semid[cpu],cpu, - (u64)key[cpu]); - /* initialize the semaphore to 1: */ - arg.val = 1; - if (semctl(semid[cpu], 0, SETVAL, arg) == -1) { - perror("semctl"); - return -1; - } - - return 0; - } - - static int lock(int cpu) - { - struct sembuf lock; - - lock.sem_num = cpu; - lock.sem_op = 1; - semop(semid[cpu], &lock, 1); - - return 0; - } - - static int unlock(int cpu) - { - struct sembuf unlock; - - unlock.sem_num = cpu; - unlock.sem_op = -1; - semop(semid[cpu], &unlock, 1); - - return 0; - } - - void free_sem(int cpu) - { - semctl(semid[cpu], 0, IPC_RMID); - } - - int wr_multi(char *fn, unsigned long *data, int size) - { - int fd; - char buf[MAX_BUF_SIZE]; - int ret; - - if (size==1) - sprintf(buf, "%lx", *data); - else if (size==3) - sprintf(buf, "%lx,%lx,%lx", data[0], data[1], data[2]); - else { - fprintf(stderr,"write to file with wrong size!\n"); - return -1; - } - - fd=open(fn, O_RDWR); - if (!fd) { - perror("Error:"); - return -1; - } - ret=write(fd, buf, sizeof(buf)); - close(fd); - return ret; - } - - int wr(char *fn, unsigned long data) - { - return wr_multi(fn, &data, 1); - } - - int rd(char *fn, unsigned long *data) - { - int fd; - char buf[MAX_BUF_SIZE]; - - fd=open(fn, O_RDONLY); - if (fd<0) { - perror("Error:"); - return -1; - } - read(fd, buf, MAX_BUF_SIZE); - *data=strtoul(buf, NULL, 16); - close(fd); - return 0; - } - - int rd_status(char *path, int *status) - { - char fn[MAX_FN_SIZE]; - sprintf(fn, "%s/status", path); - if (rd(fn, (u64*)status)<0) { - perror("status reading error.\n"); - return -1; - } - - return 0; - } - - int rd_capabilities(char *path, u64 *capabilities) - { - char fn[MAX_FN_SIZE]; - sprintf(fn, "%s/capabilities", path); - if (rd(fn, capabilities)<0) { - perror("capabilities reading error.\n"); - return -1; - } - - return 0; - } - - int rd_all(char *path) - { - unsigned long err_type_info, err_struct_info, err_data_buffer; - int status; - unsigned long capabilities, resources; - char fn[MAX_FN_SIZE]; - - sprintf(fn, "%s/err_type_info", path); - if (rd(fn, &err_type_info)<0) { - perror("err_type_info reading error.\n"); - return -1; - } - printf("err_type_info=%lx\n", err_type_info); - - sprintf(fn, "%s/err_struct_info", path); - if (rd(fn, &err_struct_info)<0) { - perror("err_struct_info reading error.\n"); - return -1; - } - printf("err_struct_info=%lx\n", err_struct_info); - - sprintf(fn, "%s/err_data_buffer", path); - if (rd(fn, &err_data_buffer)<0) { - perror("err_data_buffer reading error.\n"); - return -1; - } - printf("err_data_buffer=%lx\n", err_data_buffer); - - sprintf(fn, "%s/status", path); - if (rd("status", (u64*)&status)<0) { - perror("status reading error.\n"); - return -1; - } - printf("status=%d\n", status); - - sprintf(fn, "%s/capabilities", path); - if (rd(fn,&capabilities)<0) { - perror("capabilities reading error.\n"); - return -1; - } - printf("capabilities=%lx\n", capabilities); - - sprintf(fn, "%s/resources", path); - if (rd(fn, &resources)<0) { - perror("resources reading error.\n"); - return -1; - } - printf("resources=%lx\n", resources); - - return 0; - } - - int query_capabilities(char *path, err_type_info_t err_type_info, - u64 *capabilities) - { - char fn[MAX_FN_SIZE]; - err_struct_info_t err_struct_info; - err_data_buffer_t err_data_buffer; - - err_struct_info.err_struct_info=0; - memset(err_data_buffer.err_data_buffer, -1, ERR_DATA_BUFFER_SIZE*8); - - sprintf(fn, "%s/err_type_info", path); - wr(fn, err_type_info.err_type_info); - sprintf(fn, "%s/err_struct_info", path); - wr(fn, 0x0); - sprintf(fn, "%s/err_data_buffer", path); - wr_multi(fn, err_data_buffer.err_data_buffer, ERR_DATA_BUFFER_SIZE); - - // Fire pal_mc_error_inject procedure. - sprintf(fn, "%s/call_start", path); - wr(fn, mode); - - if (rd_capabilities(path, capabilities)<0) - return -1; - - return 0; - } - - int query_all_capabilities() - { - int status; - err_type_info_t err_type_info; - int err_sev, err_struct, struct_hier; - int cap=0; - u64 capabilities; - char path[MAX_FN_SIZE]; - - err_type_info.err_type_info=0; // Initial - err_type_info.err_type_info_u.mode=0; // Query mode; - err_type_info.err_type_info_u.err_inj=0; - - printf("All capabilities implemented in pal_mc_error_inject:\n"); - sprintf(path, PATH_FORMAT ,0); - for (err_sev=0;err_sev<3;err_sev++) - for (err_struct=0;err_struct<5;err_struct++) - for (struct_hier=0;struct_hier<5;struct_hier++) - { - status=-1; - capabilities=0; - err_type_info.err_type_info_u.err_sev=err_sev; - err_type_info.err_type_info_u.err_struct=err_struct; - err_type_info.err_type_info_u.struct_hier=struct_hier; - - if (query_capabilities(path, err_type_info, &capabilities)<0) - continue; - - if (rd_status(path, &status)<0) - continue; - - if (status==0) { - cap=1; - printf("For err_sev=%d, err_struct=%d, struct_hier=%d: ", - err_sev, err_struct, struct_hier); - printf("capabilities 0x%lx\n", capabilities); - } - } - if (!cap) { - printf("No capabilities supported.\n"); - return 0; - } - - return 0; - } - - int err_inject(int cpu, char *path, err_type_info_t err_type_info, - err_struct_info_t err_struct_info, - err_data_buffer_t err_data_buffer) - { - int status; - char fn[MAX_FN_SIZE]; - - log_info(cpu, "err_type_info=%lx, err_struct_info=%lx, ", - err_type_info.err_type_info, - err_struct_info.err_struct_info); - log_info(cpu,"err_data_buffer=[%lx,%lx,%lx]\n", - err_data_buffer.err_data_buffer[0], - err_data_buffer.err_data_buffer[1], - err_data_buffer.err_data_buffer[2]); - sprintf(fn, "%s/err_type_info", path); - wr(fn, err_type_info.err_type_info); - sprintf(fn, "%s/err_struct_info", path); - wr(fn, err_struct_info.err_struct_info); - sprintf(fn, "%s/err_data_buffer", path); - wr_multi(fn, err_data_buffer.err_data_buffer, ERR_DATA_BUFFER_SIZE); - - // Fire pal_mc_error_inject procedure. - sprintf(fn, "%s/call_start", path); - wr(fn,mode); - - if (rd_status(path, &status)<0) { - vbprintf("fail: read status\n"); - return -100; - } - - if (status!=0) { - log_info(cpu, "fail: status=%d\n", status); - return status; - } - - return status; - } - - static int construct_data_buf(char *path, err_type_info_t err_type_info, - err_struct_info_t err_struct_info, - err_data_buffer_t *err_data_buffer, - void *va1) - { - char fn[MAX_FN_SIZE]; - u64 virt_addr=0, phys_addr=0; - - vbprintf("va1=%lx\n", (u64)va1); - memset(&err_data_buffer->err_data_buffer_cache, 0, ERR_DATA_BUFFER_SIZE*8); - - switch (err_type_info.err_type_info_u.err_struct) { - case 1: // Cache - switch (err_struct_info.err_struct_info_cache.cl_id) { - case 1: //Virtual addr - err_data_buffer->err_data_buffer_cache.inj_addr=(u64)va1; - break; - case 2: //Phys addr - sprintf(fn, "%s/virtual_to_phys", path); - virt_addr=(u64)va1; - if (wr(fn,virt_addr)<0) - return -1; - rd(fn, &phys_addr); - err_data_buffer->err_data_buffer_cache.inj_addr=phys_addr; - break; - default: - printf("Not supported cl_id\n"); - break; - } - break; - case 2: // TLB - break; - case 3: // Register file - break; - case 4: // Bus/system interconnect - default: - printf("Not supported err_struct\n"); - break; - } - - return 0; - } - - typedef struct { - u64 cpu; - u64 loop; - u64 interval; - u64 err_type_info; - u64 err_struct_info; - u64 err_data_buffer[ERR_DATA_BUFFER_SIZE]; - } parameters_t; - - parameters_t line_para; - int para; - - static int empty_data_buffer(u64 *err_data_buffer) - { - int empty=1; - int i; - - for (i=0;i<ERR_DATA_BUFFER_SIZE; i++) - if (err_data_buffer[i]!=-1) - empty=0; - - return empty; - } - - int err_inj() - { - err_type_info_t err_type_info; - err_struct_info_t err_struct_info; - err_data_buffer_t err_data_buffer; - int count; - FILE *fp; - unsigned long cpu, loop, interval, err_type_info_conf, err_struct_info_conf; - u64 err_data_buffer_conf[ERR_DATA_BUFFER_SIZE]; - int num; - int i; - char path[MAX_FN_SIZE]; - parameters_t parameters[MAX_TASK_NUM]={}; - pid_t child_pid[MAX_TASK_NUM]; - time_t current_time; - int status; - - if (!para) { - fp=fopen("err.conf", "r"); - if (fp==NULL) { - perror("Error open err.conf"); - return -1; - } - - num=0; - while (!feof(fp)) { - char buf[256]; - memset(buf,0,256); - fgets(buf, 256, fp); - count=sscanf(buf, "%lx, %lx, %lx, %lx, %lx, %lx, %lx, %lx\n", - &cpu, &loop, &interval,&err_type_info_conf, - &err_struct_info_conf, - &err_data_buffer_conf[0], - &err_data_buffer_conf[1], - &err_data_buffer_conf[2]); - if (count!=PARA_FIELD_NUM+3) { - err_data_buffer_conf[0]=-1; - err_data_buffer_conf[1]=-1; - err_data_buffer_conf[2]=-1; - count=sscanf(buf, "%lx, %lx, %lx, %lx, %lx\n", - &cpu, &loop, &interval,&err_type_info_conf, - &err_struct_info_conf); - if (count!=PARA_FIELD_NUM) - continue; - } - - parameters[num].cpu=cpu; - parameters[num].loop=loop; - parameters[num].interval= interval>MIN_INTERVAL - ?interval:MIN_INTERVAL; - parameters[num].err_type_info=err_type_info_conf; - parameters[num].err_struct_info=err_struct_info_conf; - memcpy(parameters[num++].err_data_buffer, - err_data_buffer_conf,ERR_DATA_BUFFER_SIZE*8) ; - - if (num>=MAX_TASK_NUM) - break; - } - } - else { - parameters[0].cpu=line_para.cpu; - parameters[0].loop=line_para.loop; - parameters[0].interval= line_para.interval>MIN_INTERVAL - ?line_para.interval:MIN_INTERVAL; - parameters[0].err_type_info=line_para.err_type_info; - parameters[0].err_struct_info=line_para.err_struct_info; - memcpy(parameters[0].err_data_buffer, - line_para.err_data_buffer,ERR_DATA_BUFFER_SIZE*8) ; - - num=1; - } - - /* Create semaphore: If one_lock, one semaphore for all processors. - Otherwise, one semaphore for each processor. */ - if (one_lock) { - if (create_sem(0)) { - printf("Can not create semaphore...exit\n"); - free_sem(0); - return -1; - } - } - else { - for (i=0;i<num;i++) { - if (create_sem(parameters[i].cpu)) { - printf("Can not create semaphore for cpu%d...exit\n",i); - free_sem(parameters[num].cpu); - return -1; - } - } - } - - /* Create a shm segment which will be used to inject/consume errors on.*/ - if (create_shm()==-1) { - printf("Error to create shm...exit\n"); - return -1; - } - - for (i=0;i<num;i++) { - pid_t pid; - - current_time=time(NULL); - log_info(parameters[i].cpu, "\nBegine at %s", ctime(¤t_time)); - log_info(parameters[i].cpu, "Configurations:\n"); - log_info(parameters[i].cpu,"On cpu%ld: loop=%lx, interval=%lx(s)", - parameters[i].cpu, - parameters[i].loop, - parameters[i].interval); - log_info(parameters[i].cpu," err_type_info=%lx,err_struct_info=%lx\n", - parameters[i].err_type_info, - parameters[i].err_struct_info); - - sprintf(path, PATH_FORMAT, (int)parameters[i].cpu); - err_type_info.err_type_info=parameters[i].err_type_info; - err_struct_info.err_struct_info=parameters[i].err_struct_info; - memcpy(err_data_buffer.err_data_buffer, - parameters[i].err_data_buffer, - ERR_DATA_BUFFER_SIZE*8); - - pid=fork(); - if (pid==0) { - unsigned long mask[MASK_SIZE]; - int j, k; - - void *va1, *va2; - - /* Allocate two memory areas va1 and va2 in shm */ - va1=shmaddr+parameters[i].cpu*PAGE_SIZE; - va2=shmaddr+parameters[i].cpu*PAGE_SIZE+PAGE_SIZE; - - vbprintf("va1=%lx, va2=%lx\n", (u64)va1, (u64)va2); - memset(va1, 0x1, PAGE_SIZE); - memset(va2, 0x2, PAGE_SIZE); - - if (empty_data_buffer(err_data_buffer.err_data_buffer)) - /* If not specified yet, construct data buffer - * with va1 - */ - construct_data_buf(path, err_type_info, - err_struct_info, &err_data_buffer,va1); - - for (j=0;j<MASK_SIZE;j++) - mask[j]=0; - - cpu=parameters[i].cpu; - k = cpu%64; - j = cpu/64; - mask[j] = 1UL << k; - - if (sched_setaffinity(0, MASK_SIZE*8, mask)==-1) { - perror("Error sched_setaffinity:"); - return -1; - } - - for (j=0; j<parameters[i].loop; j++) { - log_info(parameters[i].cpu,"Injection "); - log_info(parameters[i].cpu,"on cpu%ld: #%d/%ld ", - - parameters[i].cpu,j+1, parameters[i].loop); - - /* Hold the lock */ - if (one_lock) - lock(0); - else - /* Hold lock on this cpu */ - lock(parameters[i].cpu); - - if ((status=err_inject(parameters[i].cpu, - path, err_type_info, - err_struct_info, err_data_buffer)) - ==0) { - /* consume the error for "inject only"*/ - memcpy(va2, va1, PAGE_SIZE); - memcpy(va1, va2, PAGE_SIZE); - log_info(parameters[i].cpu, - "successful\n"); - } - else { - log_info(parameters[i].cpu,"fail:"); - log_info(parameters[i].cpu, - "status=%d\n", status); - unlock(parameters[i].cpu); - break; - } - if (one_lock) - /* Release the lock */ - unlock(0); - /* Release lock on this cpu */ - else - unlock(parameters[i].cpu); - - if (j < parameters[i].loop-1) - sleep(parameters[i].interval); - } - current_time=time(NULL); - log_info(parameters[i].cpu, "Done at %s", ctime(¤t_time)); - return 0; - } - else if (pid<0) { - perror("Error fork:"); - continue; - } - child_pid[i]=pid; - } - for (i=0;i<num;i++) - waitpid(child_pid[i], NULL, 0); - - if (one_lock) - free_sem(0); - else - for (i=0;i<num;i++) - free_sem(parameters[i].cpu); - - printf("All done.\n"); - - return 0; - } - - void help() - { - printf("err_inject_tool:\n"); - printf("\t-q: query all capabilities. default: off\n"); - printf("\t-m: procedure mode. 1: physical 2: virtual. default: 1\n"); - printf("\t-i: inject errors. default: off\n"); - printf("\t-l: one lock per cpu. default: one lock for all\n"); - printf("\t-e: error parameters:\n"); - printf("\t\tcpu,loop,interval,err_type_info,err_struct_info[,err_data_buffer[0],err_data_buffer[1],err_data_buffer[2]]\n"); - printf("\t\t cpu: logical cpu number the error will be inject in.\n"); - printf("\t\t loop: times the error will be injected.\n"); - printf("\t\t interval: In second. every so often one error is injected.\n"); - printf("\t\t err_type_info, err_struct_info: PAL parameters.\n"); - printf("\t\t err_data_buffer: PAL parameter. Optional. If not present,\n"); - printf("\t\t it's constructed by tool automatically. Be\n"); - printf("\t\t careful to provide err_data_buffer and make\n"); - printf("\t\t sure it's working with the environment.\n"); - printf("\t Note:no space between error parameters.\n"); - printf("\t default: Take error parameters from err.conf instead of command line.\n"); - printf("\t-v: verbose. default: off\n"); - printf("\t-h: help\n\n"); - printf("The tool will take err.conf file as "); - printf("input to inject single or multiple errors "); - printf("on one or multiple cpus in parallel.\n"); - } - - int main(int argc, char **argv) - { - char c; - int do_err_inj=0; - int do_query_all=0; - int count; - u32 m; - - /* Default one lock for all cpu's */ - one_lock=1; - while ((c = getopt(argc, argv, "m:iqvhle:")) != EOF) - switch (c) { - case 'm': /* Procedure mode. 1: phys 2: virt */ - count=sscanf(optarg, "%x", &m); - if (count!=1 || (m!=1 && m!=2)) { - printf("Wrong mode number.\n"); - help(); - return -1; - } - mode=m; - break; - case 'i': /* Inject errors */ - do_err_inj=1; - break; - case 'q': /* Query */ - do_query_all=1; - break; - case 'v': /* Verbose */ - verbose=1; - break; - case 'l': /* One lock per cpu */ - one_lock=0; - break; - case 'e': /* error arguments */ - /* Take parameters: - * #cpu, loop, interval, err_type_info, err_struct_info[, err_data_buffer] - * err_data_buffer is optional. Recommend not to specify - * err_data_buffer. Better to use tool to generate it. - */ - count=sscanf(optarg, - "%lx, %lx, %lx, %lx, %lx, %lx, %lx, %lx\n", - &line_para.cpu, - &line_para.loop, - &line_para.interval, - &line_para.err_type_info, - &line_para.err_struct_info, - &line_para.err_data_buffer[0], - &line_para.err_data_buffer[1], - &line_para.err_data_buffer[2]); - if (count!=PARA_FIELD_NUM+3) { - line_para.err_data_buffer[0]=-1, - line_para.err_data_buffer[1]=-1, - line_para.err_data_buffer[2]=-1; - count=sscanf(optarg, "%lx, %lx, %lx, %lx, %lx\n", - &line_para.cpu, - &line_para.loop, - &line_para.interval, - &line_para.err_type_info, - &line_para.err_struct_info); - if (count!=PARA_FIELD_NUM) { - printf("Wrong error arguments.\n"); - help(); - return -1; - } - } - para=1; - break; - continue; - break; - case 'h': - help(); - return 0; - default: - break; - } - - if (do_query_all) - query_all_capabilities(); - if (do_err_inj) - err_inj(); - - if (!do_query_all && !do_err_inj) - help(); - - return 0; - } diff --git a/Documentation/arch/ia64/features.rst b/Documentation/arch/ia64/features.rst deleted file mode 100644 index d7226fdcf5f8..000000000000 --- a/Documentation/arch/ia64/features.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. kernel-feat:: $srctree/Documentation/features ia64 diff --git a/Documentation/arch/ia64/fsys.rst b/Documentation/arch/ia64/fsys.rst deleted file mode 100644 index a702d2cc94b6..000000000000 --- a/Documentation/arch/ia64/fsys.rst +++ /dev/null @@ -1,303 +0,0 @@ -=================================== -Light-weight System Calls for IA-64 -=================================== - - Started: 13-Jan-2003 - - Last update: 27-Sep-2003 - - David Mosberger-Tang - <davidm@hpl.hp.com> - -Using the "epc" instruction effectively introduces a new mode of -execution to the ia64 linux kernel. We call this mode the -"fsys-mode". To recap, the normal states of execution are: - - - kernel mode: - Both the register stack and the memory stack have been - switched over to kernel memory. The user-level state is saved - in a pt-regs structure at the top of the kernel memory stack. - - - user mode: - Both the register stack and the kernel stack are in - user memory. The user-level state is contained in the - CPU registers. - - - bank 0 interruption-handling mode: - This is the non-interruptible state which all - interruption-handlers start execution in. The user-level - state remains in the CPU registers and some kernel state may - be stored in bank 0 of registers r16-r31. - -In contrast, fsys-mode has the following special properties: - - - execution is at privilege level 0 (most-privileged) - - - CPU registers may contain a mixture of user-level and kernel-level - state (it is the responsibility of the kernel to ensure that no - security-sensitive kernel-level state is leaked back to - user-level) - - - execution is interruptible and preemptible (an fsys-mode handler - can disable interrupts and avoid all other interruption-sources - to avoid preemption) - - - neither the memory-stack nor the register-stack can be trusted while - in fsys-mode (they point to the user-level stacks, which may - be invalid, or completely bogus addresses) - -In summary, fsys-mode is much more similar to running in user-mode -than it is to running in kernel-mode. Of course, given that the -privilege level is at level 0, this means that fsys-mode requires some -care (see below). - - -How to tell fsys-mode -===================== - -Linux operates in fsys-mode when (a) the privilege level is 0 (most -privileged) and (b) the stacks have NOT been switched to kernel memory -yet. For convenience, the header file <asm-ia64/ptrace.h> provides -three macros:: - - user_mode(regs) - user_stack(task,regs) - fsys_mode(task,regs) - -The "regs" argument is a pointer to a pt_regs structure. The "task" -argument is a pointer to the task structure to which the "regs" -pointer belongs to. user_mode() returns TRUE if the CPU state pointed -to by "regs" was executing in user mode (privilege level 3). -user_stack() returns TRUE if the state pointed to by "regs" was -executing on the user-level stack(s). Finally, fsys_mode() returns -TRUE if the CPU state pointed to by "regs" was executing in fsys-mode. -The fsys_mode() macro is equivalent to the expression:: - - !user_mode(regs) && user_stack(task,regs) - -How to write an fsyscall handler -================================ - -The file arch/ia64/kernel/fsys.S contains a table of fsyscall-handlers -(fsyscall_table). This table contains one entry for each system call. -By default, a system call is handled by fsys_fallback_syscall(). This -routine takes care of entering (full) kernel mode and calling the -normal Linux system call handler. For performance-critical system -calls, it is possible to write a hand-tuned fsyscall_handler. For -example, fsys.S contains fsys_getpid(), which is a hand-tuned version -of the getpid() system call. - -The entry and exit-state of an fsyscall handler is as follows: - -Machine state on entry to fsyscall handler ------------------------------------------- - - ========= =============================================================== - r10 0 - r11 saved ar.pfs (a user-level value) - r15 system call number - r16 "current" task pointer (in normal kernel-mode, this is in r13) - r32-r39 system call arguments - b6 return address (a user-level value) - ar.pfs previous frame-state (a user-level value) - PSR.be cleared to zero (i.e., little-endian byte order is in effect) - - all other registers may contain values passed in from user-mode - ========= =============================================================== - -Required machine state on exit to fsyscall handler --------------------------------------------------- - - ========= =========================================================== - r11 saved ar.pfs (as passed into the fsyscall handler) - r15 system call number (as passed into the fsyscall handler) - r32-r39 system call arguments (as passed into the fsyscall handler) - b6 return address (as passed into the fsyscall handler) - ar.pfs previous frame-state (as passed into the fsyscall handler) - ========= =========================================================== - -Fsyscall handlers can execute with very little overhead, but with that -speed comes a set of restrictions: - - * Fsyscall-handlers MUST check for any pending work in the flags - member of the thread-info structure and if any of the - TIF_ALLWORK_MASK flags are set, the handler needs to fall back on - doing a full system call (by calling fsys_fallback_syscall). - - * Fsyscall-handlers MUST preserve incoming arguments (r32-r39, r11, - r15, b6, and ar.pfs) because they will be needed in case of a - system call restart. Of course, all "preserved" registers also - must be preserved, in accordance to the normal calling conventions. - - * Fsyscall-handlers MUST check argument registers for containing a - NaT value before using them in any way that could trigger a - NaT-consumption fault. If a system call argument is found to - contain a NaT value, an fsyscall-handler may return immediately - with r8=EINVAL, r10=-1. - - * Fsyscall-handlers MUST NOT use the "alloc" instruction or perform - any other operation that would trigger mandatory RSE - (register-stack engine) traffic. - - * Fsyscall-handlers MUST NOT write to any stacked registers because - it is not safe to assume that user-level called a handler with the - proper number of arguments. - - * Fsyscall-handlers need to be careful when accessing per-CPU variables: - unless proper safe-guards are taken (e.g., interruptions are avoided), - execution may be pre-empted and resumed on another CPU at any given - time. - - * Fsyscall-handlers must be careful not to leak sensitive kernel' - information back to user-level. In particular, before returning to - user-level, care needs to be taken to clear any scratch registers - that could contain sensitive information (note that the current - task pointer is not considered sensitive: it's already exposed - through ar.k6). - - * Fsyscall-handlers MUST NOT access user-memory without first - validating access-permission (this can be done typically via - probe.r.fault and/or probe.w.fault) and without guarding against - memory access exceptions (this can be done with the EX() macros - defined by asmmacro.h). - -The above restrictions may seem draconian, but remember that it's -possible to trade off some of the restrictions by paying a slightly -higher overhead. For example, if an fsyscall-handler could benefit -from the shadow register bank, it could temporarily disable PSR.i and -PSR.ic, switch to bank 0 (bsw.0) and then use the shadow registers as -needed. In other words, following the above rules yields extremely -fast system call execution (while fully preserving system call -semantics), but there is also a lot of flexibility in handling more -complicated cases. - -Signal handling -=============== - -The delivery of (asynchronous) signals must be delayed until fsys-mode -is exited. This is accomplished with the help of the lower-privilege -transfer trap: arch/ia64/kernel/process.c:do_notify_resume_user() -checks whether the interrupted task was in fsys-mode and, if so, sets -PSR.lp and returns immediately. When fsys-mode is exited via the -"br.ret" instruction that lowers the privilege level, a trap will -occur. The trap handler clears PSR.lp again and returns immediately. -The kernel exit path then checks for and delivers any pending signals. - -PSR Handling -============ - -The "epc" instruction doesn't change the contents of PSR at all. This -is in contrast to a regular interruption, which clears almost all -bits. Because of that, some care needs to be taken to ensure things -work as expected. The following discussion describes how each PSR bit -is handled. - -======= ======================================================================= -PSR.be Cleared when entering fsys-mode. A srlz.d instruction is used - to ensure the CPU is in little-endian mode before the first - load/store instruction is executed. PSR.be is normally NOT - restored upon return from an fsys-mode handler. In other - words, user-level code must not rely on PSR.be being preserved - across a system call. -PSR.up Unchanged. -PSR.ac Unchanged. -PSR.mfl Unchanged. Note: fsys-mode handlers must not write-registers! -PSR.mfh Unchanged. Note: fsys-mode handlers must not write-registers! -PSR.ic Unchanged. Note: fsys-mode handlers can clear the bit, if needed. -PSR.i Unchanged. Note: fsys-mode handlers can clear the bit, if needed. -PSR.pk Unchanged. -PSR.dt Unchanged. -PSR.dfl Unchanged. Note: fsys-mode handlers must not write-registers! -PSR.dfh Unchanged. Note: fsys-mode handlers must not write-registers! -PSR.sp Unchanged. -PSR.pp Unchanged. -PSR.di Unchanged. -PSR.si Unchanged. -PSR.db Unchanged. The kernel prevents user-level from setting a hardware - breakpoint that triggers at any privilege level other than - 3 (user-mode). -PSR.lp Unchanged. -PSR.tb Lazy redirect. If a taken-branch trap occurs while in - fsys-mode, the trap-handler modifies the saved machine state - such that execution resumes in the gate page at - syscall_via_break(), with privilege level 3. Note: the - taken branch would occur on the branch invoking the - fsyscall-handler, at which point, by definition, a syscall - restart is still safe. If the system call number is invalid, - the fsys-mode handler will return directly to user-level. This - return will trigger a taken-branch trap, but since the trap is - taken _after_ restoring the privilege level, the CPU has already - left fsys-mode, so no special treatment is needed. -PSR.rt Unchanged. -PSR.cpl Cleared to 0. -PSR.is Unchanged (guaranteed to be 0 on entry to the gate page). -PSR.mc Unchanged. -PSR.it Unchanged (guaranteed to be 1). -PSR.id Unchanged. Note: the ia64 linux kernel never sets this bit. -PSR.da Unchanged. Note: the ia64 linux kernel never sets this bit. -PSR.dd Unchanged. Note: the ia64 linux kernel never sets this bit. -PSR.ss Lazy redirect. If set, "epc" will cause a Single Step Trap to - be taken. The trap handler then modifies the saved machine - state such that execution resumes in the gate page at - syscall_via_break(), with privilege level 3. -PSR.ri Unchanged. -PSR.ed Unchanged. Note: This bit could only have an effect if an fsys-mode - handler performed a speculative load that gets NaTted. If so, this - would be the normal & expected behavior, so no special treatment is - needed. -PSR.bn Unchanged. Note: fsys-mode handlers may clear the bit, if needed. - Doing so requires clearing PSR.i and PSR.ic as well. -PSR.ia Unchanged. Note: the ia64 linux kernel never sets this bit. -======= ======================================================================= - -Using fast system calls -======================= - -To use fast system calls, userspace applications need simply call -__kernel_syscall_via_epc(). For example - --- example fgettimeofday() call -- - --- fgettimeofday.S -- - -:: - - #include <asm/asmmacro.h> - - GLOBAL_ENTRY(fgettimeofday) - .prologue - .save ar.pfs, r11 - mov r11 = ar.pfs - .body - - mov r2 = 0xa000000000020660;; // gate address - // found by inspection of System.map for the - // __kernel_syscall_via_epc() function. See - // below for how to do this for real. - - mov b7 = r2 - mov r15 = 1087 // gettimeofday syscall - ;; - br.call.sptk.many b6 = b7 - ;; - - .restore sp - - mov ar.pfs = r11 - br.ret.sptk.many rp;; // return to caller - END(fgettimeofday) - --- end fgettimeofday.S -- - -In reality, getting the gate address is accomplished by two extra -values passed via the ELF auxiliary vector (include/asm-ia64/elf.h) - - * AT_SYSINFO : is the address of __kernel_syscall_via_epc() - * AT_SYSINFO_EHDR : is the address of the kernel gate ELF DSO - -The ELF DSO is a pre-linked library that is mapped in by the kernel at -the gate page. It is a proper ELF shared object so, with a dynamic -loader that recognises the library, you should be able to make calls to -the exported functions within it as with any other shared library. -AT_SYSINFO points into the kernel DSO at the -__kernel_syscall_via_epc() function for historical reasons (it was -used before the kernel DSO) and as a convenience. diff --git a/Documentation/arch/ia64/ia64.rst b/Documentation/arch/ia64/ia64.rst deleted file mode 100644 index b725019a9492..000000000000 --- a/Documentation/arch/ia64/ia64.rst +++ /dev/null @@ -1,49 +0,0 @@ -=========================================== -Linux kernel release for the IA-64 Platform -=========================================== - - These are the release notes for Linux since version 2.4 for IA-64 - platform. This document provides information specific to IA-64 - ONLY, to get additional information about the Linux kernel also - read the original Linux README provided with the kernel. - -Installing the Kernel -===================== - - - IA-64 kernel installation is the same as the other platforms, see - original README for details. - - -Software Requirements -===================== - - Compiling and running this kernel requires an IA-64 compliant GCC - compiler. And various software packages also compiled with an - IA-64 compliant GCC compiler. - - -Configuring the Kernel -====================== - - Configuration is the same, see original README for details. - - -Compiling the Kernel: - - - Compiling this kernel doesn't differ from other platform so read - the original README for details BUT make sure you have an IA-64 - compliant GCC compiler. - -IA-64 Specifics -=============== - - - General issues: - - * Hardly any performance tuning has been done. Obvious targets - include the library routines (IP checksum, etc.). Less - obvious targets include making sure we don't flush the TLB - needlessly, etc. - - * SMP locks cleanup/optimization - - * IA32 support. Currently experimental. It mostly works. diff --git a/Documentation/arch/ia64/index.rst b/Documentation/arch/ia64/index.rst deleted file mode 100644 index 761f2154dfa2..000000000000 --- a/Documentation/arch/ia64/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -================== -IA-64 Architecture -================== - -.. toctree:: - :maxdepth: 1 - - ia64 - aliasing - efirtc - err_inject - fsys - irq-redir - mca - serial - - features diff --git a/Documentation/arch/ia64/irq-redir.rst b/Documentation/arch/ia64/irq-redir.rst deleted file mode 100644 index 6bbbbe4f73ef..000000000000 --- a/Documentation/arch/ia64/irq-redir.rst +++ /dev/null @@ -1,80 +0,0 @@ -============================== -IRQ affinity on IA64 platforms -============================== - -07.01.2002, Erich Focht <efocht@ess.nec.de> - - -By writing to /proc/irq/IRQ#/smp_affinity the interrupt routing can be -controlled. The behavior on IA64 platforms is slightly different from -that described in Documentation/core-api/irq/irq-affinity.rst for i386 systems. - -Because of the usage of SAPIC mode and physical destination mode the -IRQ target is one particular CPU and cannot be a mask of several -CPUs. Only the first non-zero bit is taken into account. - - -Usage examples -============== - -The target CPU has to be specified as a hexadecimal CPU mask. The -first non-zero bit is the selected CPU. This format has been kept for -compatibility reasons with i386. - -Set the delivery mode of interrupt 41 to fixed and route the -interrupts to CPU #3 (logical CPU number) (2^3=0x08):: - - echo "8" >/proc/irq/41/smp_affinity - -Set the default route for IRQ number 41 to CPU 6 in lowest priority -delivery mode (redirectable):: - - echo "r 40" >/proc/irq/41/smp_affinity - -The output of the command:: - - cat /proc/irq/IRQ#/smp_affinity - -gives the target CPU mask for the specified interrupt vector. If the CPU -mask is preceded by the character "r", the interrupt is redirectable -(i.e. lowest priority mode routing is used), otherwise its route is -fixed. - - - -Initialization and default behavior -=================================== - -If the platform features IRQ redirection (info provided by SAL) all -IO-SAPIC interrupts are initialized with CPU#0 as their default target -and the routing is the so called "lowest priority mode" (actually -fixed SAPIC mode with hint). The XTP chipset registers are used as hints -for the IRQ routing. Currently in Linux XTP registers can have three -values: - - - minimal for an idle task, - - normal if any other task runs, - - maximal if the CPU is going to be switched off. - -The IRQ is routed to the CPU with lowest XTP register value, the -search begins at the default CPU. Therefore most of the interrupts -will be handled by CPU #0. - -If the platform doesn't feature interrupt redirection IOSAPIC fixed -routing is used. The target CPUs are distributed in a round robin -manner. IRQs will be routed only to the selected target CPUs. Check -with:: - - cat /proc/interrupts - - - -Comments -======== - -On large (multi-node) systems it is recommended to route the IRQs to -the node to which the corresponding device is connected. -For systems like the NEC AzusA we get IRQ node-affinity for free. This -is because usually the chipsets on each node redirect the interrupts -only to their own CPUs (as they cannot see the XTP registers on the -other nodes). diff --git a/Documentation/arch/ia64/mca.rst b/Documentation/arch/ia64/mca.rst deleted file mode 100644 index 08270bba44a4..000000000000 --- a/Documentation/arch/ia64/mca.rst +++ /dev/null @@ -1,198 +0,0 @@ -============================================================= -An ad-hoc collection of notes on IA64 MCA and INIT processing -============================================================= - -Feel free to update it with notes about any area that is not clear. - ---- - -MCA/INIT are completely asynchronous. They can occur at any time, when -the OS is in any state. Including when one of the cpus is already -holding a spinlock. Trying to get any lock from MCA/INIT state is -asking for deadlock. Also the state of structures that are protected -by locks is indeterminate, including linked lists. - ---- - -The complicated ia64 MCA process. All of this is mandated by Intel's -specification for ia64 SAL, error recovery and unwind, it is not as -if we have a choice here. - -* MCA occurs on one cpu, usually due to a double bit memory error. - This is the monarch cpu. - -* SAL sends an MCA rendezvous interrupt (which is a normal interrupt) - to all the other cpus, the slaves. - -* Slave cpus that receive the MCA interrupt call down into SAL, they - end up spinning disabled while the MCA is being serviced. - -* If any slave cpu was already spinning disabled when the MCA occurred - then it cannot service the MCA interrupt. SAL waits ~20 seconds then - sends an unmaskable INIT event to the slave cpus that have not - already rendezvoused. - -* Because MCA/INIT can be delivered at any time, including when the cpu - is down in PAL in physical mode, the registers at the time of the - event are _completely_ undefined. In particular the MCA/INIT - handlers cannot rely on the thread pointer, PAL physical mode can - (and does) modify TP. It is allowed to do that as long as it resets - TP on return. However MCA/INIT events expose us to these PAL - internal TP changes. Hence curr_task(). - -* If an MCA/INIT event occurs while the kernel was running (not user - space) and the kernel has called PAL then the MCA/INIT handler cannot - assume that the kernel stack is in a fit state to be used. Mainly - because PAL may or may not maintain the stack pointer internally. - Because the MCA/INIT handlers cannot trust the kernel stack, they - have to use their own, per-cpu stacks. The MCA/INIT stacks are - preformatted with just enough task state to let the relevant handlers - do their job. - -* Unlike most other architectures, the ia64 struct task is embedded in - the kernel stack[1]. So switching to a new kernel stack means that - we switch to a new task as well. Because various bits of the kernel - assume that current points into the struct task, switching to a new - stack also means a new value for current. - -* Once all slaves have rendezvoused and are spinning disabled, the - monarch is entered. The monarch now tries to diagnose the problem - and decide if it can recover or not. - -* Part of the monarch's job is to look at the state of all the other - tasks. The only way to do that on ia64 is to call the unwinder, - as mandated by Intel. - -* The starting point for the unwind depends on whether a task is - running or not. That is, whether it is on a cpu or is blocked. The - monarch has to determine whether or not a task is on a cpu before it - knows how to start unwinding it. The tasks that received an MCA or - INIT event are no longer running, they have been converted to blocked - tasks. But (and its a big but), the cpus that received the MCA - rendezvous interrupt are still running on their normal kernel stacks! - -* To distinguish between these two cases, the monarch must know which - tasks are on a cpu and which are not. Hence each slave cpu that - switches to an MCA/INIT stack, registers its new stack using - set_curr_task(), so the monarch can tell that the _original_ task is - no longer running on that cpu. That gives us a decent chance of - getting a valid backtrace of the _original_ task. - -* MCA/INIT can be nested, to a depth of 2 on any cpu. In the case of a - nested error, we want diagnostics on the MCA/INIT handler that - failed, not on the task that was originally running. Again this - requires set_curr_task() so the MCA/INIT handlers can register their - own stack as running on that cpu. Then a recursive error gets a - trace of the failing handler's "task". - -[1] - My (Keith Owens) original design called for ia64 to separate its - struct task and the kernel stacks. Then the MCA/INIT data would be - chained stacks like i386 interrupt stacks. But that required - radical surgery on the rest of ia64, plus extra hard wired TLB - entries with its associated performance degradation. David - Mosberger vetoed that approach. Which meant that separate kernel - stacks meant separate "tasks" for the MCA/INIT handlers. - ---- - -INIT is less complicated than MCA. Pressing the nmi button or using -the equivalent command on the management console sends INIT to all -cpus. SAL picks one of the cpus as the monarch and the rest are -slaves. All the OS INIT handlers are entered at approximately the same -time. The OS monarch prints the state of all tasks and returns, after -which the slaves return and the system resumes. - -At least that is what is supposed to happen. Alas there are broken -versions of SAL out there. Some drive all the cpus as monarchs. Some -drive them all as slaves. Some drive one cpu as monarch, wait for that -cpu to return from the OS then drive the rest as slaves. Some versions -of SAL cannot even cope with returning from the OS, they spin inside -SAL on resume. The OS INIT code has workarounds for some of these -broken SAL symptoms, but some simply cannot be fixed from the OS side. - ---- - -The scheduler hooks used by ia64 (curr_task, set_curr_task) are layer -violations. Unfortunately MCA/INIT start off as massive layer -violations (can occur at _any_ time) and they build from there. - -At least ia64 makes an attempt at recovering from hardware errors, but -it is a difficult problem because of the asynchronous nature of these -errors. When processing an unmaskable interrupt we sometimes need -special code to cope with our inability to take any locks. - ---- - -How is ia64 MCA/INIT different from x86 NMI? - -* x86 NMI typically gets delivered to one cpu. MCA/INIT gets sent to - all cpus. - -* x86 NMI cannot be nested. MCA/INIT can be nested, to a depth of 2 - per cpu. - -* x86 has a separate struct task which points to one of multiple kernel - stacks. ia64 has the struct task embedded in the single kernel - stack, so switching stack means switching task. - -* x86 does not call the BIOS so the NMI handler does not have to worry - about any registers having changed. MCA/INIT can occur while the cpu - is in PAL in physical mode, with undefined registers and an undefined - kernel stack. - -* i386 backtrace is not very sensitive to whether a process is running - or not. ia64 unwind is very, very sensitive to whether a process is - running or not. - ---- - -What happens when MCA/INIT is delivered what a cpu is running user -space code? - -The user mode registers are stored in the RSE area of the MCA/INIT on -entry to the OS and are restored from there on return to SAL, so user -mode registers are preserved across a recoverable MCA/INIT. Since the -OS has no idea what unwind data is available for the user space stack, -MCA/INIT never tries to backtrace user space. Which means that the OS -does not bother making the user space process look like a blocked task, -i.e. the OS does not copy pt_regs and switch_stack to the user space -stack. Also the OS has no idea how big the user space RSE and memory -stacks are, which makes it too risky to copy the saved state to a user -mode stack. - ---- - -How do we get a backtrace on the tasks that were running when MCA/INIT -was delivered? - -mca.c:::ia64_mca_modify_original_stack(). That identifies and -verifies the original kernel stack, copies the dirty registers from -the MCA/INIT stack's RSE to the original stack's RSE, copies the -skeleton struct pt_regs and switch_stack to the original stack, fills -in the skeleton structures from the PAL minstate area and updates the -original stack's thread.ksp. That makes the original stack look -exactly like any other blocked task, i.e. it now appears to be -sleeping. To get a backtrace, just start with thread.ksp for the -original task and unwind like any other sleeping task. - ---- - -How do we identify the tasks that were running when MCA/INIT was -delivered? - -If the previous task has been verified and converted to a blocked -state, then sos->prev_task on the MCA/INIT stack is updated to point to -the previous task. You can look at that field in dumps or debuggers. -To help distinguish between the handler and the original tasks, -handlers have _TIF_MCA_INIT set in thread_info.flags. - -The sos data is always in the MCA/INIT handler stack, at offset -MCA_SOS_OFFSET. You can get that value from mca_asm.h or calculate it -as KERNEL_STACK_SIZE - sizeof(struct pt_regs) - sizeof(struct -ia64_sal_os_state), with 16 byte alignment for all structures. - -Also the comm field of the MCA/INIT task is modified to include the pid -of the original task, for humans to use. For example, a comm field of -'MCA 12159' means that pid 12159 was running when the MCA was -delivered. diff --git a/Documentation/arch/ia64/serial.rst b/Documentation/arch/ia64/serial.rst deleted file mode 100644 index 1de70c305a79..000000000000 --- a/Documentation/arch/ia64/serial.rst +++ /dev/null @@ -1,165 +0,0 @@ -============== -Serial Devices -============== - -Serial Device Naming -==================== - - As of 2.6.10, serial devices on ia64 are named based on the - order of ACPI and PCI enumeration. The first device in the - ACPI namespace (if any) becomes /dev/ttyS0, the second becomes - /dev/ttyS1, etc., and PCI devices are named sequentially - starting after the ACPI devices. - - Prior to 2.6.10, there were confusing exceptions to this: - - - Firmware on some machines (mostly from HP) provides an HCDP - table[1] that tells the kernel about devices that can be used - as a serial console. If the user specified "console=ttyS0" - or the EFI ConOut path contained only UART devices, the - kernel registered the device described by the HCDP as - /dev/ttyS0. - - - If there was no HCDP, we assumed there were UARTs at the - legacy COM port addresses (I/O ports 0x3f8 and 0x2f8), so - the kernel registered those as /dev/ttyS0 and /dev/ttyS1. - - Any additional ACPI or PCI devices were registered sequentially - after /dev/ttyS0 as they were discovered. - - With an HCDP, device names changed depending on EFI configuration - and "console=" arguments. Without an HCDP, device names didn't - change, but we registered devices that might not really exist. - - For example, an HP rx1600 with a single built-in serial port - (described in the ACPI namespace) plus an MP[2] (a PCI device) has - these ports: - - ========== ========== ============ ============ ======= - Type MMIO pre-2.6.10 pre-2.6.10 2.6.10+ - address - (EFI console (EFI console - on builtin) on MP port) - ========== ========== ============ ============ ======= - builtin 0xff5e0000 ttyS0 ttyS1 ttyS0 - MP UPS 0xf8031000 ttyS1 ttyS2 ttyS1 - MP Console 0xf8030000 ttyS2 ttyS0 ttyS2 - MP 2 0xf8030010 ttyS3 ttyS3 ttyS3 - MP 3 0xf8030038 ttyS4 ttyS4 ttyS4 - ========== ========== ============ ============ ======= - -Console Selection -================= - - EFI knows what your console devices are, but it doesn't tell the - kernel quite enough to actually locate them. The DIG64 HCDP - table[1] does tell the kernel where potential serial console - devices are, but not all firmware supplies it. Also, EFI supports - multiple simultaneous consoles and doesn't tell the kernel which - should be the "primary" one. - - So how do you tell Linux which console device to use? - - - If your firmware supplies the HCDP, it is simplest to - configure EFI with a single device (either a UART or a VGA - card) as the console. Then you don't need to tell Linux - anything; the kernel will automatically use the EFI console. - - (This works only in 2.6.6 or later; prior to that you had - to specify "console=ttyS0" to get a serial console.) - - - Without an HCDP, Linux defaults to a VGA console unless you - specify a "console=" argument. - - NOTE: Don't assume that a serial console device will be /dev/ttyS0. - It might be ttyS1, ttyS2, etc. Make sure you have the appropriate - entries in /etc/inittab (for getty) and /etc/securetty (to allow - root login). - -Early Serial Console -==================== - - The kernel can't start using a serial console until it knows where - the device lives. Normally this happens when the driver enumerates - all the serial devices, which can happen a minute or more after the - kernel starts booting. - - 2.6.10 and later kernels have an "early uart" driver that works - very early in the boot process. The kernel will automatically use - this if the user supplies an argument like "console=uart,io,0x3f8", - or if the EFI console path contains only a UART device and the - firmware supplies an HCDP. - -Troubleshooting Serial Console Problems -======================================= - - No kernel output after elilo prints "Uncompressing Linux... done": - - - You specified "console=ttyS0" but Linux changed the device - to which ttyS0 refers. Configure exactly one EFI console - device[3] and remove the "console=" option. - - - The EFI console path contains both a VGA device and a UART. - EFI and elilo use both, but Linux defaults to VGA. Remove - the VGA device from the EFI console path[3]. - - - Multiple UARTs selected as EFI console devices. EFI and - elilo use all selected devices, but Linux uses only one. - Make sure only one UART is selected in the EFI console - path[3]. - - - You're connected to an HP MP port[2] but have a non-MP UART - selected as EFI console device. EFI uses the MP as a - console device even when it isn't explicitly selected. - Either move the console cable to the non-MP UART, or change - the EFI console path[3] to the MP UART. - - Long pause (60+ seconds) between "Uncompressing Linux... done" and - start of kernel output: - - - No early console because you used "console=ttyS<n>". Remove - the "console=" option if your firmware supplies an HCDP. - - - If you don't have an HCDP, the kernel doesn't know where - your console lives until the driver discovers serial - devices. Use "console=uart,io,0x3f8" (or appropriate - address for your machine). - - Kernel and init script output works fine, but no "login:" prompt: - - - Add getty entry to /etc/inittab for console tty. Look for - the "Adding console on ttyS<n>" message that tells you which - device is the console. - - "login:" prompt, but can't login as root: - - - Add entry to /etc/securetty for console tty. - - No ACPI serial devices found in 2.6.17 or later: - - - Turn on CONFIG_PNP and CONFIG_PNPACPI. Prior to 2.6.17, ACPI - serial devices were discovered by 8250_acpi. In 2.6.17, - 8250_acpi was replaced by the combination of 8250_pnp and - CONFIG_PNPACPI. - - - -[1] - http://www.dig64.org/specifications/agreement - The table was originally defined as the "HCDP" for "Headless - Console/Debug Port." The current version is the "PCDP" for - "Primary Console and Debug Port Devices." - -[2] - The HP MP (management processor) is a PCI device that provides - several UARTs. One of the UARTs is often used as a console; the - EFI Boot Manager identifies it as "Acpi(HWP0002,700)/Pci(...)/Uart". - The external connection is usually a 25-pin connector, and a - special dongle converts that to three 9-pin connectors, one of - which is labelled "Console." - -[3] - EFI console devices are configured using the EFI Boot Manager - "Boot option maintenance" menu. You may have to interrupt the - boot sequence to use this menu, and you will have to reset the - box after changing console configuration. diff --git a/Documentation/arch/index.rst b/Documentation/arch/index.rst index 8458b88e9b79..3f9962e45c09 100644 --- a/Documentation/arch/index.rst +++ b/Documentation/arch/index.rst @@ -12,16 +12,15 @@ implementation. arc/index arm/index arm64/index - ia64/index - ../loongarch/index + loongarch/index m68k/index - ../mips/index + mips/index nios2/index openrisc/index parisc/index - ../powerpc/index - ../riscv/index - ../s390/index + powerpc/index + riscv/index + s390/index sh/index sparc/index x86/index diff --git a/Documentation/loongarch/booting.rst b/Documentation/arch/loongarch/booting.rst index 91eccd410478..91eccd410478 100644 --- a/Documentation/loongarch/booting.rst +++ b/Documentation/arch/loongarch/booting.rst diff --git a/Documentation/loongarch/features.rst b/Documentation/arch/loongarch/features.rst index ebacade3ea45..ebacade3ea45 100644 --- a/Documentation/loongarch/features.rst +++ b/Documentation/arch/loongarch/features.rst diff --git a/Documentation/loongarch/index.rst b/Documentation/arch/loongarch/index.rst index c779bfa00c05..c779bfa00c05 100644 --- a/Documentation/loongarch/index.rst +++ b/Documentation/arch/loongarch/index.rst diff --git a/Documentation/loongarch/introduction.rst b/Documentation/arch/loongarch/introduction.rst index 49135d451ced..8c568cfc2107 100644 --- a/Documentation/loongarch/introduction.rst +++ b/Documentation/arch/loongarch/introduction.rst @@ -381,9 +381,9 @@ Documentation of LoongArch ISA: Documentation of LoongArch ELF psABI: - https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.00-CN.pdf (in Chinese) + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.01-CN.pdf (in Chinese) - https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.00-EN.pdf (in English) + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.01-EN.pdf (in English) Linux kernel repository of Loongson and LoongArch: diff --git a/Documentation/loongarch/irq-chip-model.rst b/Documentation/arch/loongarch/irq-chip-model.rst index 7988f4192363..7988f4192363 100644 --- a/Documentation/loongarch/irq-chip-model.rst +++ b/Documentation/arch/loongarch/irq-chip-model.rst diff --git a/Documentation/mips/booting.rst b/Documentation/arch/mips/booting.rst index 7c18a4eab48b..7c18a4eab48b 100644 --- a/Documentation/mips/booting.rst +++ b/Documentation/arch/mips/booting.rst diff --git a/Documentation/mips/features.rst b/Documentation/arch/mips/features.rst index 1973d729b29a..1973d729b29a 100644 --- a/Documentation/mips/features.rst +++ b/Documentation/arch/mips/features.rst diff --git a/Documentation/mips/index.rst b/Documentation/arch/mips/index.rst index 037f85a08fe3..037f85a08fe3 100644 --- a/Documentation/mips/index.rst +++ b/Documentation/arch/mips/index.rst diff --git a/Documentation/mips/ingenic-tcu.rst b/Documentation/arch/mips/ingenic-tcu.rst index 2ce4cb1314dc..2ce4cb1314dc 100644 --- a/Documentation/mips/ingenic-tcu.rst +++ b/Documentation/arch/mips/ingenic-tcu.rst diff --git a/Documentation/arch/openrisc/openrisc_port.rst b/Documentation/arch/openrisc/openrisc_port.rst index 657ac4af7be6..1565b9546e38 100644 --- a/Documentation/arch/openrisc/openrisc_port.rst +++ b/Documentation/arch/openrisc/openrisc_port.rst @@ -106,7 +106,7 @@ History a much improved version with changes all around. 10-04-2004 Matjaz Breskvar (phoenix@bsemi.com) - alot of bugfixes all over. + a lot of bugfixes all over. ethernet support, functional http and telnet servers. running many standard linux apps. @@ -114,7 +114,7 @@ History port to 2.6.x 30-11-2004 Matjaz Breskvar (phoenix@bsemi.com) - lots of bugfixes and enhancments. + lots of bugfixes and enhancements. added opencores framebuffer driver. 09-10-2010 Jonas Bonn (jonas@southpole.se) diff --git a/Documentation/powerpc/associativity.rst b/Documentation/arch/powerpc/associativity.rst index 4d01c7368561..4d01c7368561 100644 --- a/Documentation/powerpc/associativity.rst +++ b/Documentation/arch/powerpc/associativity.rst diff --git a/Documentation/powerpc/booting.rst b/Documentation/arch/powerpc/booting.rst index 11aa440f98cc..11aa440f98cc 100644 --- a/Documentation/powerpc/booting.rst +++ b/Documentation/arch/powerpc/booting.rst diff --git a/Documentation/powerpc/bootwrapper.rst b/Documentation/arch/powerpc/bootwrapper.rst index cdfa2bc8425f..cdfa2bc8425f 100644 --- a/Documentation/powerpc/bootwrapper.rst +++ b/Documentation/arch/powerpc/bootwrapper.rst diff --git a/Documentation/powerpc/cpu_families.rst b/Documentation/arch/powerpc/cpu_families.rst index eb7e60649b43..eb7e60649b43 100644 --- a/Documentation/powerpc/cpu_families.rst +++ b/Documentation/arch/powerpc/cpu_families.rst diff --git a/Documentation/powerpc/cpu_features.rst b/Documentation/arch/powerpc/cpu_features.rst index b7bcdd2f41bb..b7bcdd2f41bb 100644 --- a/Documentation/powerpc/cpu_features.rst +++ b/Documentation/arch/powerpc/cpu_features.rst diff --git a/Documentation/powerpc/cxl.rst b/Documentation/arch/powerpc/cxl.rst index d2d77057610e..d2d77057610e 100644 --- a/Documentation/powerpc/cxl.rst +++ b/Documentation/arch/powerpc/cxl.rst diff --git a/Documentation/powerpc/cxlflash.rst b/Documentation/arch/powerpc/cxlflash.rst index cea67931b3b9..e8f488acfa41 100644 --- a/Documentation/powerpc/cxlflash.rst +++ b/Documentation/arch/powerpc/cxlflash.rst @@ -32,7 +32,7 @@ Introduction responsible for the initialization of the adapter, setting up the special path for user space access, and performing error recovery. It communicates directly the Flash Accelerator Functional Unit (AFU) - as described in Documentation/powerpc/cxl.rst. + as described in Documentation/arch/powerpc/cxl.rst. The cxlflash driver supports two, mutually exclusive, modes of operation at the device (LUN) level: diff --git a/Documentation/powerpc/dawr-power9.rst b/Documentation/arch/powerpc/dawr-power9.rst index 310f2e0cea81..310f2e0cea81 100644 --- a/Documentation/powerpc/dawr-power9.rst +++ b/Documentation/arch/powerpc/dawr-power9.rst diff --git a/Documentation/powerpc/dexcr.rst b/Documentation/arch/powerpc/dexcr.rst index 615a631f51fa..615a631f51fa 100644 --- a/Documentation/powerpc/dexcr.rst +++ b/Documentation/arch/powerpc/dexcr.rst diff --git a/Documentation/powerpc/dscr.rst b/Documentation/arch/powerpc/dscr.rst index 2ab99006014c..f735ec5375d5 100644 --- a/Documentation/powerpc/dscr.rst +++ b/Documentation/arch/powerpc/dscr.rst @@ -6,7 +6,7 @@ DSCR register in powerpc allows user to have some control of prefetch of data stream in the processor. Please refer to the ISA documents or related manual for more detailed information regarding how to use this DSCR to attain this control of the prefetches . This document here provides an overview of kernel -support for DSCR, related kernel objects, it's functionalities and exported +support for DSCR, related kernel objects, its functionalities and exported user interface. (A) Data Structures: diff --git a/Documentation/powerpc/eeh-pci-error-recovery.rst b/Documentation/arch/powerpc/eeh-pci-error-recovery.rst index d6643a91bdf8..d6643a91bdf8 100644 --- a/Documentation/powerpc/eeh-pci-error-recovery.rst +++ b/Documentation/arch/powerpc/eeh-pci-error-recovery.rst diff --git a/Documentation/powerpc/elf_hwcaps.rst b/Documentation/arch/powerpc/elf_hwcaps.rst index 3366e5b18e67..4c896cf077c2 100644 --- a/Documentation/powerpc/elf_hwcaps.rst +++ b/Documentation/arch/powerpc/elf_hwcaps.rst @@ -202,7 +202,7 @@ PPC_FEATURE2_VEC_CRYPTO PPC_FEATURE2_HTM_NOSC System calls fail if called in a transactional state, see - Documentation/powerpc/syscall64-abi.rst + Documentation/arch/powerpc/syscall64-abi.rst PPC_FEATURE2_ARCH_3_00 The processor supports the v3.0B / v3.0C userlevel architecture. Processors @@ -217,11 +217,11 @@ PPC_FEATURE2_DARN PPC_FEATURE2_SCV The scv 0 instruction may be used for system calls, see - Documentation/powerpc/syscall64-abi.rst. + Documentation/arch/powerpc/syscall64-abi.rst. PPC_FEATURE2_HTM_NO_SUSPEND A limited Transactional Memory facility that does not support suspend is - available, see Documentation/powerpc/transactional_memory.rst. + available, see Documentation/arch/powerpc/transactional_memory.rst. PPC_FEATURE2_ARCH_3_1 The processor supports the v3.1 userlevel architecture. Processors diff --git a/Documentation/powerpc/elfnote.rst b/Documentation/arch/powerpc/elfnote.rst index 3ec8d61e9a33..3ec8d61e9a33 100644 --- a/Documentation/powerpc/elfnote.rst +++ b/Documentation/arch/powerpc/elfnote.rst diff --git a/Documentation/powerpc/features.rst b/Documentation/arch/powerpc/features.rst index aeae73df86b0..aeae73df86b0 100644 --- a/Documentation/powerpc/features.rst +++ b/Documentation/arch/powerpc/features.rst diff --git a/Documentation/powerpc/firmware-assisted-dump.rst b/Documentation/arch/powerpc/firmware-assisted-dump.rst index e363fc48529a..e363fc48529a 100644 --- a/Documentation/powerpc/firmware-assisted-dump.rst +++ b/Documentation/arch/powerpc/firmware-assisted-dump.rst diff --git a/Documentation/powerpc/hvcs.rst b/Documentation/arch/powerpc/hvcs.rst index 6808acde672f..6808acde672f 100644 --- a/Documentation/powerpc/hvcs.rst +++ b/Documentation/arch/powerpc/hvcs.rst diff --git a/Documentation/powerpc/imc.rst b/Documentation/arch/powerpc/imc.rst index 633bcee7dc85..633bcee7dc85 100644 --- a/Documentation/powerpc/imc.rst +++ b/Documentation/arch/powerpc/imc.rst diff --git a/Documentation/powerpc/index.rst b/Documentation/arch/powerpc/index.rst index d33b554ca7ba..a50834798454 100644 --- a/Documentation/powerpc/index.rst +++ b/Documentation/arch/powerpc/index.rst @@ -36,6 +36,7 @@ powerpc ultravisor vas-api vcpudispatch_stats + vmemmap_dedup features diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/arch/powerpc/isa-versions.rst index a8d6b6028b3e..a8d6b6028b3e 100644 --- a/Documentation/powerpc/isa-versions.rst +++ b/Documentation/arch/powerpc/isa-versions.rst diff --git a/Documentation/powerpc/kasan.txt b/Documentation/arch/powerpc/kasan.txt index f032b4eaf205..a4f647e4fffa 100644 --- a/Documentation/powerpc/kasan.txt +++ b/Documentation/arch/powerpc/kasan.txt @@ -40,7 +40,7 @@ checks can be delayed until after the MMU is set is up, and we can just not instrument any code that runs with translations off after booting. This is the current approach. -To avoid this limitiation, the KASAN shadow would have to be placed inside the +To avoid this limitation, the KASAN shadow would have to be placed inside the linear mapping, using the same high-bits trick we use for the rest of the linear mapping. This is tricky: diff --git a/Documentation/powerpc/kaslr-booke32.rst b/Documentation/arch/powerpc/kaslr-booke32.rst index 5681c1d1b65b..5681c1d1b65b 100644 --- a/Documentation/powerpc/kaslr-booke32.rst +++ b/Documentation/arch/powerpc/kaslr-booke32.rst diff --git a/Documentation/powerpc/mpc52xx.rst b/Documentation/arch/powerpc/mpc52xx.rst index 5243b1763fad..5243b1763fad 100644 --- a/Documentation/powerpc/mpc52xx.rst +++ b/Documentation/arch/powerpc/mpc52xx.rst diff --git a/Documentation/powerpc/papr_hcalls.rst b/Documentation/arch/powerpc/papr_hcalls.rst index fce8bc793660..80d2c0aadab5 100644 --- a/Documentation/powerpc/papr_hcalls.rst +++ b/Documentation/arch/powerpc/papr_hcalls.rst @@ -22,7 +22,7 @@ privileged operations. Currently there are two PAPR compliant hypervisors: On PPC64 arch a guest kernel running on top of a PAPR hypervisor is called a *pSeries guest*. A pseries guest runs in a supervisor mode (HV=0) and must issue hypercalls to the hypervisor whenever it needs to perform an action -that is hypervisor priviledged [3]_ or for other services managed by the +that is hypervisor privileged [3]_ or for other services managed by the hypervisor. Hence a Hypercall (hcall) is essentially a request by the pseries guest diff --git a/Documentation/powerpc/pci_iov_resource_on_powernv.rst b/Documentation/arch/powerpc/pci_iov_resource_on_powernv.rst index f5a5793e1613..f5a5793e1613 100644 --- a/Documentation/powerpc/pci_iov_resource_on_powernv.rst +++ b/Documentation/arch/powerpc/pci_iov_resource_on_powernv.rst diff --git a/Documentation/powerpc/pmu-ebb.rst b/Documentation/arch/powerpc/pmu-ebb.rst index 4f474758eb55..4f474758eb55 100644 --- a/Documentation/powerpc/pmu-ebb.rst +++ b/Documentation/arch/powerpc/pmu-ebb.rst diff --git a/Documentation/powerpc/ptrace.rst b/Documentation/arch/powerpc/ptrace.rst index 77725d69eb4a..5629edf4d56e 100644 --- a/Documentation/powerpc/ptrace.rst +++ b/Documentation/arch/powerpc/ptrace.rst @@ -15,7 +15,7 @@ that's extendable and that covers both BookE and server processors, so that GDB doesn't need to special-case each of them. We added the following 3 new ptrace requests. -1. PTRACE_PPC_GETHWDEBUGINFO +1. PPC_PTRACE_GETHWDBGINFO ============================ Query for GDB to discover the hardware debug features. The main info to @@ -48,7 +48,7 @@ features will have bits indicating whether there is support for:: #define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10 #define PPC_DEBUG_FEATURE_DATA_BP_ARCH_31 0x20 -2. PTRACE_SETHWDEBUG +2. PPC_PTRACE_SETHWDEBUG Sets a hardware breakpoint or watchpoint, according to the provided structure:: @@ -88,7 +88,7 @@ that the BookE supports. COMEFROM breakpoints available in server processors are not contemplated, but that is out of the scope of this work. ptrace will return an integer (handle) uniquely identifying the breakpoint or -watchpoint just created. This integer will be used in the PTRACE_DELHWDEBUG +watchpoint just created. This integer will be used in the PPC_PTRACE_DELHWDEBUG request to ask for its removal. Return -ENOSPC if the requested breakpoint can't be allocated on the registers. @@ -150,7 +150,7 @@ Some examples of using the structure to: p.addr2 = (uint64_t) end_range; p.condition_value = 0; -3. PTRACE_DELHWDEBUG +3. PPC_PTRACE_DELHWDEBUG Takes an integer which identifies an existing breakpoint or watchpoint (i.e., the value returned from PTRACE_SETHWDEBUG), and deletes the diff --git a/Documentation/powerpc/qe_firmware.rst b/Documentation/arch/powerpc/qe_firmware.rst index 42f5103140c9..a358f152b7e7 100644 --- a/Documentation/powerpc/qe_firmware.rst +++ b/Documentation/arch/powerpc/qe_firmware.rst @@ -232,11 +232,11 @@ For example, to match the 8323, revision 1.0:: 'extended_modes' is a bitfield that defines special functionality which has an impact on the device drivers. Each bit has its own impact and has special instructions for the driver associated with it. This field is stored in -the QE library and available to any driver that calles qe_get_firmware_info(). +the QE library and available to any driver that calls qe_get_firmware_info(). 'vtraps' is an array of 8 words that contain virtual trap values for each virtual traps. As with 'extended_modes', this field is stored in the QE -library and available to any driver that calles qe_get_firmware_info(). +library and available to any driver that calls qe_get_firmware_info(). 'microcode' (type: struct qe_microcode): For each RISC processor there is one 'microcode' structure. The first diff --git a/Documentation/powerpc/syscall64-abi.rst b/Documentation/arch/powerpc/syscall64-abi.rst index 56490c4c0c07..56490c4c0c07 100644 --- a/Documentation/powerpc/syscall64-abi.rst +++ b/Documentation/arch/powerpc/syscall64-abi.rst diff --git a/Documentation/powerpc/transactional_memory.rst b/Documentation/arch/powerpc/transactional_memory.rst index 040a20675fd1..040a20675fd1 100644 --- a/Documentation/powerpc/transactional_memory.rst +++ b/Documentation/arch/powerpc/transactional_memory.rst diff --git a/Documentation/powerpc/ultravisor.rst b/Documentation/arch/powerpc/ultravisor.rst index ba6b1bf1cc44..ba6b1bf1cc44 100644 --- a/Documentation/powerpc/ultravisor.rst +++ b/Documentation/arch/powerpc/ultravisor.rst diff --git a/Documentation/powerpc/vas-api.rst b/Documentation/arch/powerpc/vas-api.rst index bdb50fed903e..a9625a2fa0c6 100644 --- a/Documentation/powerpc/vas-api.rst +++ b/Documentation/arch/powerpc/vas-api.rst @@ -46,7 +46,7 @@ request queue into the application's virtual address space. The application can then submit one or more requests to the engine by using copy/paste instructions and pasting the CRBs to the virtual address (aka paste_address) returned by mmap(). User space can close the -established connection or send window by closing the file descriptior +established connection or send window by closing the file descriptor (close(fd)) or upon the process exit. Note that applications can send several requests with the same window or @@ -240,7 +240,7 @@ issued. This signal returns with the following siginfo struct:: siginfo.si_signo = SIGSEGV; siginfo.si_errno = EFAULT; siginfo.si_code = SEGV_MAPERR; - siginfo.si_addr = CSB adress; + siginfo.si_addr = CSB address; In the case of multi-thread applications, NX send windows can be shared across all threads. For example, a child thread can open a send window, diff --git a/Documentation/powerpc/vcpudispatch_stats.rst b/Documentation/arch/powerpc/vcpudispatch_stats.rst index 5704657a5987..5704657a5987 100644 --- a/Documentation/powerpc/vcpudispatch_stats.rst +++ b/Documentation/arch/powerpc/vcpudispatch_stats.rst diff --git a/Documentation/arch/powerpc/vmemmap_dedup.rst b/Documentation/arch/powerpc/vmemmap_dedup.rst new file mode 100644 index 000000000000..dc4db59fdf87 --- /dev/null +++ b/Documentation/arch/powerpc/vmemmap_dedup.rst @@ -0,0 +1,101 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========== +Device DAX +========== + +The device-dax interface uses the tail deduplication technique explained in +Documentation/mm/vmemmap_dedup.rst + +On powerpc, vmemmap deduplication is only used with radix MMU translation. Also +with a 64K page size, only the devdax namespace with 1G alignment uses vmemmap +deduplication. + +With 2M PMD level mapping, we require 32 struct pages and a single 64K vmemmap +page can contain 1024 struct pages (64K/sizeof(struct page)). Hence there is no +vmemmap deduplication possible. + +With 1G PUD level mapping, we require 16384 struct pages and a single 64K +vmemmap page can contain 1024 struct pages (64K/sizeof(struct page)). Hence we +require 16 64K pages in vmemmap to map the struct page for 1G PUD level mapping. + +Here's how things look like on device-dax after the sections are populated:: + +-----------+ ---virt_to_page---> +-----------+ mapping to +-----------+ + | | | 0 | -------------> | 0 | + | | +-----------+ +-----------+ + | | | 1 | -------------> | 1 | + | | +-----------+ +-----------+ + | | | 2 | ----------------^ ^ ^ ^ ^ ^ + | | +-----------+ | | | | | + | | | 3 | ------------------+ | | | | + | | +-----------+ | | | | + | | | 4 | --------------------+ | | | + | PUD | +-----------+ | | | + | level | | . | ----------------------+ | | + | mapping | +-----------+ | | + | | | . | ------------------------+ | + | | +-----------+ | + | | | 15 | --------------------------+ + | | +-----------+ + | | + | | + | | + +-----------+ + + +With 4K page size, 2M PMD level mapping requires 512 struct pages and a single +4K vmemmap page contains 64 struct pages(4K/sizeof(struct page)). Hence we +require 8 4K pages in vmemmap to map the struct page for 2M pmd level mapping. + +Here's how things look like on device-dax after the sections are populated:: + + +-----------+ ---virt_to_page---> +-----------+ mapping to +-----------+ + | | | 0 | -------------> | 0 | + | | +-----------+ +-----------+ + | | | 1 | -------------> | 1 | + | | +-----------+ +-----------+ + | | | 2 | ----------------^ ^ ^ ^ ^ ^ + | | +-----------+ | | | | | + | | | 3 | ------------------+ | | | | + | | +-----------+ | | | | + | | | 4 | --------------------+ | | | + | PMD | +-----------+ | | | + | level | | 5 | ----------------------+ | | + | mapping | +-----------+ | | + | | | 6 | ------------------------+ | + | | +-----------+ | + | | | 7 | --------------------------+ + | | +-----------+ + | | + | | + | | + +-----------+ + +With 1G PUD level mapping, we require 262144 struct pages and a single 4K +vmemmap page can contain 64 struct pages (4K/sizeof(struct page)). Hence we +require 4096 4K pages in vmemmap to map the struct pages for 1G PUD level +mapping. + +Here's how things look like on device-dax after the sections are populated:: + + +-----------+ ---virt_to_page---> +-----------+ mapping to +-----------+ + | | | 0 | -------------> | 0 | + | | +-----------+ +-----------+ + | | | 1 | -------------> | 1 | + | | +-----------+ +-----------+ + | | | 2 | ----------------^ ^ ^ ^ ^ ^ + | | +-----------+ | | | | | + | | | 3 | ------------------+ | | | | + | | +-----------+ | | | | + | | | 4 | --------------------+ | | | + | PUD | +-----------+ | | | + | level | | . | ----------------------+ | | + | mapping | +-----------+ | | + | | | . | ------------------------+ | + | | +-----------+ | + | | | 4095 | --------------------------+ + | | +-----------+ + | | + | | + | | + +-----------+ diff --git a/Documentation/riscv/acpi.rst b/Documentation/arch/riscv/acpi.rst index 9870a282815b..9870a282815b 100644 --- a/Documentation/riscv/acpi.rst +++ b/Documentation/arch/riscv/acpi.rst diff --git a/Documentation/riscv/boot-image-header.rst b/Documentation/arch/riscv/boot-image-header.rst index d7752533865f..df2ffc173e80 100644 --- a/Documentation/riscv/boot-image-header.rst +++ b/Documentation/arch/riscv/boot-image-header.rst @@ -7,9 +7,6 @@ Boot image header in RISC-V Linux This document only describes the boot image header details for RISC-V Linux. -TODO: - Write a complete booting guide. - The following 64-byte header is present in decompressed Linux kernel image:: u32 code0; /* Executable code */ @@ -31,11 +28,11 @@ header in future. Notes ===== -- This header can also be reused to support EFI stub for RISC-V in future. EFI - specification needs PE/COFF image header in the beginning of the kernel image - in order to load it as an EFI application. In order to support EFI stub, - code0 should be replaced with "MZ" magic string and res3(at offset 0x3c) should - point to the rest of the PE/COFF header. +- This header is also reused to support EFI stub for RISC-V. EFI specification + needs PE/COFF image header in the beginning of the kernel image in order to + load it as an EFI application. In order to support EFI stub, code0 is replaced + with "MZ" magic string and res3(at offset 0x3c) points to the rest of the + PE/COFF header. - version field indicate header version number diff --git a/Documentation/arch/riscv/boot.rst b/Documentation/arch/riscv/boot.rst new file mode 100644 index 000000000000..6077b587a842 --- /dev/null +++ b/Documentation/arch/riscv/boot.rst @@ -0,0 +1,169 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============================================== +RISC-V Kernel Boot Requirements and Constraints +=============================================== + +:Author: Alexandre Ghiti <alexghiti@rivosinc.com> +:Date: 23 May 2023 + +This document describes what the RISC-V kernel expects from bootloaders and +firmware, and also the constraints that any developer must have in mind when +touching the early boot process. For the purposes of this document, the +``early boot process`` refers to any code that runs before the final virtual +mapping is set up. + +Pre-kernel Requirements and Constraints +======================================= + +The RISC-V kernel expects the following of bootloaders and platform firmware: + +Register state +-------------- + +The RISC-V kernel expects: + + * ``$a0`` to contain the hartid of the current core. + * ``$a1`` to contain the address of the devicetree in memory. + +CSR state +--------- + +The RISC-V kernel expects: + + * ``$satp = 0``: the MMU, if present, must be disabled. + +Reserved memory for resident firmware +------------------------------------- + +The RISC-V kernel must not map any resident memory, or memory protected with +PMPs, in the direct mapping, so the firmware must correctly mark those regions +as per the devicetree specification and/or the UEFI specification. + +Kernel location +--------------- + +The RISC-V kernel expects to be placed at a PMD boundary (2MB aligned for rv64 +and 4MB aligned for rv32). Note that the EFI stub will physically relocate the +kernel if that's not the case. + +Hardware description +-------------------- + +The firmware can pass either a devicetree or ACPI tables to the RISC-V kernel. + +The devicetree is either passed directly to the kernel from the previous stage +using the ``$a1`` register, or when booting with UEFI, it can be passed using the +EFI configuration table. + +The ACPI tables are passed to the kernel using the EFI configuration table. In +this case, a tiny devicetree is still created by the EFI stub. Please refer to +"EFI stub and devicetree" section below for details about this devicetree. + +Kernel entry +------------ + +On SMP systems, there are 2 methods to enter the kernel: + +- ``RISCV_BOOT_SPINWAIT``: the firmware releases all harts in the kernel, one hart + wins a lottery and executes the early boot code while the other harts are + parked waiting for the initialization to finish. This method is mostly used to + support older firmwares without SBI HSM extension and M-mode RISC-V kernel. +- ``Ordered booting``: the firmware releases only one hart that will execute the + initialization phase and then will start all other harts using the SBI HSM + extension. The ordered booting method is the preferred booting method for + booting the RISC-V kernel because it can support CPU hotplug and kexec. + +UEFI +---- + +UEFI memory map +~~~~~~~~~~~~~~~ + +When booting with UEFI, the RISC-V kernel will use only the EFI memory map to +populate the system memory. + +The UEFI firmware must parse the subnodes of the ``/reserved-memory`` devicetree +node and abide by the devicetree specification to convert the attributes of +those subnodes (``no-map`` and ``reusable``) into their correct EFI equivalent +(refer to section "3.5.4 /reserved-memory and UEFI" of the devicetree +specification v0.4-rc1). + +RISCV_EFI_BOOT_PROTOCOL +~~~~~~~~~~~~~~~~~~~~~~~ + +When booting with UEFI, the EFI stub requires the boot hartid in order to pass +it to the RISC-V kernel in ``$a1``. The EFI stub retrieves the boot hartid using +one of the following methods: + +- ``RISCV_EFI_BOOT_PROTOCOL`` (**preferred**). +- ``boot-hartid`` devicetree subnode (**deprecated**). + +Any new firmware must implement ``RISCV_EFI_BOOT_PROTOCOL`` as the devicetree +based approach is deprecated now. + +Early Boot Requirements and Constraints +======================================= + +The RISC-V kernel's early boot process operates under the following constraints: + +EFI stub and devicetree +----------------------- + +When booting with UEFI, the devicetree is supplemented (or created) by the EFI +stub with the same parameters as arm64 which are described at the paragraph +"UEFI kernel support on ARM" in Documentation/arch/arm/uefi.rst. + +Virtual mapping installation +---------------------------- + +The installation of the virtual mapping is done in 2 steps in the RISC-V kernel: + +1. ``setup_vm()`` installs a temporary kernel mapping in ``early_pg_dir`` which + allows discovery of the system memory. Only the kernel text/data are mapped + at this point. When establishing this mapping, no allocation can be done + (since the system memory is not known yet), so ``early_pg_dir`` page table is + statically allocated (using only one table for each level). + +2. ``setup_vm_final()`` creates the final kernel mapping in ``swapper_pg_dir`` + and takes advantage of the discovered system memory to create the linear + mapping. When establishing this mapping, the kernel can allocate memory but + cannot access it directly (since the direct mapping is not present yet), so + it uses temporary mappings in the fixmap region to be able to access the + newly allocated page table levels. + +For ``virt_to_phys()`` and ``phys_to_virt()`` to be able to correctly convert +direct mapping addresses to physical addresses, they need to know the start of +the DRAM. This happens after step 1, right before step 2 installs the direct +mapping (see ``setup_bootmem()`` function in arch/riscv/mm/init.c). Any usage of +those macros before the final virtual mapping is installed must be carefully +examined. + +Devicetree mapping via fixmap +----------------------------- + +As the ``reserved_mem`` array is initialized with virtual addresses established +by ``setup_vm()``, and used with the mapping established by +``setup_vm_final()``, the RISC-V kernel uses the fixmap region to map the +devicetree. This ensures that the devicetree remains accessible by both virtual +mappings. + +Pre-MMU execution +----------------- + +A few pieces of code need to run before even the first virtual mapping is +established. These are the installation of the first virtual mapping itself, +patching of early alternatives and the early parsing of the kernel command line. +That code must be very carefully compiled as: + +- ``-fno-pie``: This is needed for relocatable kernels which use ``-fPIE``, + since otherwise, any access to a global symbol would go through the GOT which + is only relocated virtually. +- ``-mcmodel=medany``: Any access to a global symbol must be PC-relative to + avoid any relocations to happen before the MMU is setup. +- *all* instrumentation must also be disabled (that includes KASAN, ftrace and + others). + +As using a symbol from a different compilation unit requires this unit to be +compiled with those flags, we advise, as much as possible, not to use external +symbols. diff --git a/Documentation/riscv/features.rst b/Documentation/arch/riscv/features.rst index c70ef6ac2368..c70ef6ac2368 100644 --- a/Documentation/riscv/features.rst +++ b/Documentation/arch/riscv/features.rst diff --git a/Documentation/riscv/hwprobe.rst b/Documentation/arch/riscv/hwprobe.rst index 19165ebd82ba..a52996b22f75 100644 --- a/Documentation/riscv/hwprobe.rst +++ b/Documentation/arch/riscv/hwprobe.rst @@ -49,7 +49,7 @@ The following keys are defined: privileged ISA, with the following known exceptions (more exceptions may be added, but only if it can be demonstrated that the user ABI is not broken): - * The :fence.i: instruction cannot be directly executed by userspace + * The ``fence.i`` instruction cannot be directly executed by userspace programs (it may still be executed in userspace via a kernel-controlled mechanism such as the vDSO). @@ -87,13 +87,12 @@ The following keys are defined: emulated via software, either in or below the kernel. These accesses are always extremely slow. - * :c:macro:`RISCV_HWPROBE_MISALIGNED_SLOW`: Misaligned accesses are supported - in hardware, but are slower than the cooresponding aligned accesses - sequences. + * :c:macro:`RISCV_HWPROBE_MISALIGNED_SLOW`: Misaligned accesses are slower + than equivalent byte accesses. Misaligned accesses may be supported + directly in hardware, or trapped and emulated by software. - * :c:macro:`RISCV_HWPROBE_MISALIGNED_FAST`: Misaligned accesses are supported - in hardware and are faster than the cooresponding aligned accesses - sequences. + * :c:macro:`RISCV_HWPROBE_MISALIGNED_FAST`: Misaligned accesses are faster + than equivalent byte accesses. * :c:macro:`RISCV_HWPROBE_MISALIGNED_UNSUPPORTED`: Misaligned accesses are not supported at all and will generate a misaligned address fault. diff --git a/Documentation/riscv/index.rst b/Documentation/arch/riscv/index.rst index 81cf6e616476..4dab0cb4b900 100644 --- a/Documentation/riscv/index.rst +++ b/Documentation/arch/riscv/index.rst @@ -6,6 +6,7 @@ RISC-V architecture :maxdepth: 1 acpi + boot boot-image-header vm-layout hwprobe diff --git a/Documentation/riscv/patch-acceptance.rst b/Documentation/arch/riscv/patch-acceptance.rst index 634aa222b410..634aa222b410 100644 --- a/Documentation/riscv/patch-acceptance.rst +++ b/Documentation/arch/riscv/patch-acceptance.rst diff --git a/Documentation/riscv/uabi.rst b/Documentation/arch/riscv/uabi.rst index 8960fac42c40..8960fac42c40 100644 --- a/Documentation/riscv/uabi.rst +++ b/Documentation/arch/riscv/uabi.rst diff --git a/Documentation/riscv/vector.rst b/Documentation/arch/riscv/vector.rst index 165b7ed0ac4f..75dd88a62e1d 100644 --- a/Documentation/riscv/vector.rst +++ b/Documentation/arch/riscv/vector.rst @@ -13,7 +13,7 @@ order to support the use of the RISC-V Vector Extension. Two new prctl() calls are added to allow programs to manage the enablement status for the use of Vector in userspace. The intended usage guideline for these interfaces is to give init systems a way to modify the availability of V -for processes running under its domain. Calling thess interfaces is not +for processes running under its domain. Calling these interfaces is not recommended in libraries routines because libraries should not override policies configured from the parant process. Also, users must noted that these interfaces are not portable to non-Linux, nor non-RISC-V environments, so it is discourage diff --git a/Documentation/riscv/vm-layout.rst b/Documentation/arch/riscv/vm-layout.rst index 5462c84f4723..69ff6da1dbf8 100644 --- a/Documentation/riscv/vm-layout.rst +++ b/Documentation/arch/riscv/vm-layout.rst @@ -133,3 +133,25 @@ RISC-V Linux Kernel SV57 ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | modules, BPF ffffffff80000000 | -2 GB | ffffffffffffffff | 2 GB | kernel __________________|____________|__________________|_________|____________________________________________________________ + + +Userspace VAs +-------------------- +To maintain compatibility with software that relies on the VA space with a +maximum of 48 bits the kernel will, by default, return virtual addresses to +userspace from a 48-bit range (sv48). This default behavior is achieved by +passing 0 into the hint address parameter of mmap. On CPUs with an address space +smaller than sv48, the CPU maximum supported address space will be the default. + +Software can "opt-in" to receiving VAs from another VA space by providing +a hint address to mmap. A hint address passed to mmap will cause the largest +address space that fits entirely into the hint to be used, unless there is no +space left in the address space. If there is no space available in the requested +address space, an address in the next smallest available address space will be +returned. + +For example, in order to obtain 48-bit VA space, a hint address greater than +:code:`1 << 47` must be provided. Note that this is 47 due to sv48 userspace +ending at :code:`1 << 47` and the addresses beyond this are reserved for the +kernel. Similarly, to obtain 57-bit VA space addresses, a hint address greater +than or equal to :code:`1 << 56` must be provided. diff --git a/Documentation/s390/3270.ChangeLog b/Documentation/arch/s390/3270.ChangeLog index ecaf60b6c381..ecaf60b6c381 100644 --- a/Documentation/s390/3270.ChangeLog +++ b/Documentation/arch/s390/3270.ChangeLog diff --git a/Documentation/s390/3270.rst b/Documentation/arch/s390/3270.rst index e09e77954238..467eace91473 100644 --- a/Documentation/s390/3270.rst +++ b/Documentation/arch/s390/3270.rst @@ -116,7 +116,7 @@ Here are the installation steps in detail: as a 3270, not a 3215. 5. Run the 3270 configuration script config3270. It is - distributed in this same directory, Documentation/s390, as + distributed in this same directory, Documentation/arch/s390, as config3270.sh. Inspect the output script it produces, /tmp/mkdev3270, and then run that script. This will create the necessary character special device files and make the necessary @@ -125,7 +125,7 @@ Here are the installation steps in detail: Then notify /sbin/init that /etc/inittab has changed, by issuing the telinit command with the q operand:: - cd Documentation/s390 + cd Documentation/arch/s390 sh config3270.sh sh /tmp/mkdev3270 telinit q diff --git a/Documentation/s390/cds.rst b/Documentation/arch/s390/cds.rst index 7006d8209d2e..bcad2a14244a 100644 --- a/Documentation/s390/cds.rst +++ b/Documentation/arch/s390/cds.rst @@ -39,7 +39,7 @@ some of them are ESA/390 platform specific. Note: In order to write a driver for S/390, you also need to look into the interface - described in Documentation/s390/driver-model.rst. + described in Documentation/arch/s390/driver-model.rst. Note for porting drivers from 2.4: diff --git a/Documentation/s390/common_io.rst b/Documentation/arch/s390/common_io.rst index 846485681ce7..6dcb40cb7145 100644 --- a/Documentation/s390/common_io.rst +++ b/Documentation/arch/s390/common_io.rst @@ -136,5 +136,5 @@ debugfs entries The level of logging can be changed to be more or less verbose by piping to /sys/kernel/debug/s390dbf/cio_*/level a number between 0 and 6; see the - documentation on the S/390 debug feature (Documentation/s390/s390dbf.rst) + documentation on the S/390 debug feature (Documentation/arch/s390/s390dbf.rst) for details. diff --git a/Documentation/s390/config3270.sh b/Documentation/arch/s390/config3270.sh index 515e2f431487..515e2f431487 100644 --- a/Documentation/s390/config3270.sh +++ b/Documentation/arch/s390/config3270.sh diff --git a/Documentation/s390/driver-model.rst b/Documentation/arch/s390/driver-model.rst index ad4bc2dbea43..ad4bc2dbea43 100644 --- a/Documentation/s390/driver-model.rst +++ b/Documentation/arch/s390/driver-model.rst diff --git a/Documentation/s390/features.rst b/Documentation/arch/s390/features.rst index 57c296a9d8f3..57c296a9d8f3 100644 --- a/Documentation/s390/features.rst +++ b/Documentation/arch/s390/features.rst diff --git a/Documentation/s390/index.rst b/Documentation/arch/s390/index.rst index 73c79bf586fd..73c79bf586fd 100644 --- a/Documentation/s390/index.rst +++ b/Documentation/arch/s390/index.rst diff --git a/Documentation/s390/monreader.rst b/Documentation/arch/s390/monreader.rst index 21cdfb699b49..21cdfb699b49 100644 --- a/Documentation/s390/monreader.rst +++ b/Documentation/arch/s390/monreader.rst diff --git a/Documentation/s390/pci.rst b/Documentation/arch/s390/pci.rst index a1a72a47dc96..d5755484d8e7 100644 --- a/Documentation/s390/pci.rst +++ b/Documentation/arch/s390/pci.rst @@ -40,7 +40,7 @@ For example: Change the level of logging to be more or less verbose by piping a number between 0 and 6 to /sys/kernel/debug/s390dbf/pci_*/level. For details, see the documentation on the S/390 debug feature at - Documentation/s390/s390dbf.rst. + Documentation/arch/s390/s390dbf.rst. Sysfs entries ============= diff --git a/Documentation/s390/qeth.rst b/Documentation/arch/s390/qeth.rst index f02fdaa68de0..f02fdaa68de0 100644 --- a/Documentation/s390/qeth.rst +++ b/Documentation/arch/s390/qeth.rst diff --git a/Documentation/s390/s390dbf.rst b/Documentation/arch/s390/s390dbf.rst index af8bdc3629e7..af8bdc3629e7 100644 --- a/Documentation/s390/s390dbf.rst +++ b/Documentation/arch/s390/s390dbf.rst diff --git a/Documentation/s390/text_files.rst b/Documentation/arch/s390/text_files.rst index c94d05d4fa17..c94d05d4fa17 100644 --- a/Documentation/s390/text_files.rst +++ b/Documentation/arch/s390/text_files.rst diff --git a/Documentation/s390/vfio-ap-locking.rst b/Documentation/arch/s390/vfio-ap-locking.rst index 0dfcdb562e21..0dfcdb562e21 100644 --- a/Documentation/s390/vfio-ap-locking.rst +++ b/Documentation/arch/s390/vfio-ap-locking.rst diff --git a/Documentation/s390/vfio-ap.rst b/Documentation/arch/s390/vfio-ap.rst index bb3f4c4e2885..929ee1c1c940 100644 --- a/Documentation/s390/vfio-ap.rst +++ b/Documentation/arch/s390/vfio-ap.rst @@ -422,7 +422,7 @@ Configure the guest's AP resources Configuring the AP resources for a KVM guest will be performed when the VFIO_GROUP_NOTIFY_SET_KVM notifier callback is invoked. The notifier function is called when userspace connects to KVM. The guest's AP resources are -configured via it's APCB by: +configured via its APCB by: * Setting the bits in the APM corresponding to the APIDs assigned to the vfio_ap mediated device via its 'assign_adapter' interface. diff --git a/Documentation/s390/vfio-ccw.rst b/Documentation/arch/s390/vfio-ccw.rst index 37026fa18179..42960b7b0d70 100644 --- a/Documentation/s390/vfio-ccw.rst +++ b/Documentation/arch/s390/vfio-ccw.rst @@ -440,6 +440,6 @@ Reference 1. ESA/s390 Principles of Operation manual (IBM Form. No. SA22-7832) 2. ESA/390 Common I/O Device Commands manual (IBM Form. No. SA22-7204) 3. https://en.wikipedia.org/wiki/Channel_I/O -4. Documentation/s390/cds.rst +4. Documentation/arch/s390/cds.rst 5. Documentation/driver-api/vfio.rst 6. Documentation/driver-api/vfio-mediated-device.rst diff --git a/Documentation/s390/zfcpdump.rst b/Documentation/arch/s390/zfcpdump.rst index a61de7aa8778..a61de7aa8778 100644 --- a/Documentation/s390/zfcpdump.rst +++ b/Documentation/arch/s390/zfcpdump.rst diff --git a/Documentation/arch/sh/index.rst b/Documentation/arch/sh/index.rst index c64776738cf6..01fce7c131f1 100644 --- a/Documentation/arch/sh/index.rst +++ b/Documentation/arch/sh/index.rst @@ -43,12 +43,6 @@ mach-x3proto Busses ====== -SuperHyway ----------- - -.. kernel-doc:: drivers/sh/superhyway/superhyway.c - :export: - Maple ----- diff --git a/Documentation/arch/x86/amd-memory-encryption.rst b/Documentation/arch/x86/amd-memory-encryption.rst index 934310ce7258..07caa8fff852 100644 --- a/Documentation/arch/x86/amd-memory-encryption.rst +++ b/Documentation/arch/x86/amd-memory-encryption.rst @@ -130,4 +130,4 @@ SNP feature support. More details in AMD64 APM[1] Vol 2: 15.34.10 SEV_STATUS MSR -[1] https://www.amd.com/system/files/TechDocs/40332.pdf +[1] https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/programmer-references/24593.pdf diff --git a/Documentation/arch/x86/amd_hsmp.rst b/Documentation/arch/x86/amd_hsmp.rst index 440e4b645a1c..c92bfd55359f 100644 --- a/Documentation/arch/x86/amd_hsmp.rst +++ b/Documentation/arch/x86/amd_hsmp.rst @@ -41,6 +41,24 @@ In-kernel integration: * Locking across callers is taken care by the driver. +HSMP sysfs interface +==================== + +1. Metrics table binary sysfs + +AMD MI300A MCM provides GET_METRICS_TABLE message to retrieve +most of the system management information from SMU in one go. + +The metrics table is made available as hexadecimal sysfs binary file +under per socket sysfs directory created at +/sys/devices/platform/amd_hsmp/socket%d/metrics_bin + +Note: lseek() is not supported as entire metrics table is read. + +Metrics table definitions will be documented as part of Public PPR. +The same is defined in the amd_hsmp.h header. + + An example ========== diff --git a/Documentation/arch/x86/boot.rst b/Documentation/arch/x86/boot.rst index 33520ecdb37a..f5d2f2414de8 100644 --- a/Documentation/arch/x86/boot.rst +++ b/Documentation/arch/x86/boot.rst @@ -1105,7 +1105,7 @@ The kernel command line should not be located below the real-mode code, nor should it be located in high memory. -Sample Boot Configuartion +Sample Boot Configuration ========================= As a sample configuration, assume the following layout of the real @@ -1417,7 +1417,7 @@ execution context provided by the EFI firmware. The function prototype for the handover entry point looks like this:: - efi_main(void *handle, efi_system_table_t *table, struct boot_params *bp) + efi_stub_entry(void *handle, efi_system_table_t *table, struct boot_params *bp) 'handle' is the EFI image handle passed to the boot loader by the EFI firmware, 'table' is the EFI system table - these are the first two diff --git a/Documentation/arch/x86/buslock.rst b/Documentation/arch/x86/buslock.rst index 31ec0ef78086..4c5a4822eeb7 100644 --- a/Documentation/arch/x86/buslock.rst +++ b/Documentation/arch/x86/buslock.rst @@ -32,7 +32,7 @@ mechanisms to detect split locks and bus locks. -------------------------------------- Beginning with the Tremont Atom CPU split lock operations may raise an -Alignment Check (#AC) exception when a split lock operation is attemped. +Alignment Check (#AC) exception when a split lock operation is attempted. #DB exception for bus lock detection ------------------------------------ diff --git a/Documentation/arch/x86/index.rst b/Documentation/arch/x86/index.rst index c73d133fd37c..8ac64d7de4dc 100644 --- a/Documentation/arch/x86/index.rst +++ b/Documentation/arch/x86/index.rst @@ -22,6 +22,7 @@ x86-specific Documentation mtrr pat intel-hfi + shstk iommu intel_txt amd-memory-encryption diff --git a/Documentation/arch/x86/iommu.rst b/Documentation/arch/x86/iommu.rst index 42c7a6faa39a..41fbadfe2221 100644 --- a/Documentation/arch/x86/iommu.rst +++ b/Documentation/arch/x86/iommu.rst @@ -5,7 +5,7 @@ x86 IOMMU Support The architecture specs can be obtained from the below locations. - Intel: http://www.intel.com/content/dam/www/public/us/en/documents/product-specifications/vt-directed-io-spec.pdf -- AMD: https://www.amd.com/system/files/TechDocs/48882_IOMMU.pdf +- AMD: https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/specifications/48882_3_07_PUB.pdf This guide gives a quick cheat sheet for some basic understanding. diff --git a/Documentation/arch/x86/mds.rst b/Documentation/arch/x86/mds.rst index 5d4330be200f..e73fdff62c0a 100644 --- a/Documentation/arch/x86/mds.rst +++ b/Documentation/arch/x86/mds.rst @@ -60,7 +60,7 @@ needed for exploiting MDS requires: data The existence of such a construct in the kernel cannot be excluded with -100% certainty, but the complexity involved makes it extremly unlikely. +100% certainty, but the complexity involved makes it extremely unlikely. There is one exception, which is untrusted BPF. The functionality of untrusted BPF is limited, but it needs to be thoroughly investigated diff --git a/Documentation/arch/x86/resctrl.rst b/Documentation/arch/x86/resctrl.rst index cb05d90111b4..a6279df64a9d 100644 --- a/Documentation/arch/x86/resctrl.rst +++ b/Documentation/arch/x86/resctrl.rst @@ -35,7 +35,7 @@ about the feature from resctrl's info directory. To use the feature mount the file system:: - # mount -t resctrl resctrl [-o cdp[,cdpl2][,mba_MBps]] /sys/fs/resctrl + # mount -t resctrl resctrl [-o cdp[,cdpl2][,mba_MBps][,debug]] /sys/fs/resctrl mount options are: @@ -46,6 +46,9 @@ mount options are: "mba_MBps": Enable the MBA Software Controller(mba_sc) to specify MBA bandwidth in MBps +"debug": + Make debug files accessible. Available debug files are annotated with + "Available only with debug option". L2 and L3 CDP are controlled separately. @@ -124,6 +127,13 @@ related to allocation: "P": Corresponding region is pseudo-locked. No sharing allowed. +"sparse_masks": + Indicates if non-contiguous 1s value in CBM is supported. + + "0": + Only contiguous 1s value in CBM is supported. + "1": + Non-contiguous 1s value in CBM is supported. Memory bandwidth(MB) subdirectory contains the following files with respect to allocation: @@ -299,7 +309,14 @@ All groups contain the following files: "tasks": Reading this file shows the list of all tasks that belong to this group. Writing a task id to the file will add a task to the - group. If the group is a CTRL_MON group the task is removed from + group. Multiple tasks can be added by separating the task ids + with commas. Tasks will be assigned sequentially. Multiple + failures are not supported. A single failure encountered while + attempting to assign a task will cause the operation to abort and + already added tasks before the failure will remain in the group. + Failures will be logged to /sys/fs/resctrl/info/last_cmd_status. + + If the group is a CTRL_MON group the task is removed from whichever previous CTRL_MON group owned the task and also from any MON group that owned the task. If the group is a MON group, then the task must already belong to the CTRL_MON parent of this @@ -342,6 +359,10 @@ When control is enabled all CTRL_MON groups will also contain: file. On successful pseudo-locked region creation the mode will automatically change to "pseudo-locked". +"ctrl_hw_id": + Available only with debug option. The identifier used by hardware + for the control group. On x86 this is the CLOSID. + When monitoring is enabled all MON groups will also contain: "mon_data": @@ -355,6 +376,10 @@ When monitoring is enabled all MON groups will also contain: the sum for all tasks in the CTRL_MON group and all tasks in MON groups. Please see example section for more details on usage. +"mon_hw_id": + Available only with debug option. The identifier used by hardware + for the monitor group. On x86 this is the RMID. + Resource allocation rules ------------------------- @@ -445,12 +470,13 @@ For cache resources we describe the portion of the cache that is available for allocation using a bitmask. The maximum value of the mask is defined by each cpu model (and may be different for different cache levels). It is found using CPUID, but is also provided in the "info" directory of -the resctrl file system in "info/{resource}/cbm_mask". Intel hardware +the resctrl file system in "info/{resource}/cbm_mask". Some Intel hardware requires that these masks have all the '1' bits in a contiguous block. So 0x3, 0x6 and 0xC are legal 4-bit masks with two bits set, but 0x5, 0x9 -and 0xA are not. On a system with a 20-bit mask each bit represents 5% -of the capacity of the cache. You could partition the cache into four -equal parts with masks: 0x1f, 0x3e0, 0x7c00, 0xf8000. +and 0xA are not. Check /sys/fs/resctrl/info/{resource}/sparse_masks +if non-contiguous 1s value is supported. On a system with a 20-bit mask +each bit represents 5% of the capacity of the cache. You could partition +the cache into four equal parts with masks: 0x1f, 0x3e0, 0x7c00, 0xf8000. Memory bandwidth Allocation and monitoring ========================================== diff --git a/Documentation/arch/x86/sgx.rst b/Documentation/arch/x86/sgx.rst index 2bcbffacbed5..d90796adc2ec 100644 --- a/Documentation/arch/x86/sgx.rst +++ b/Documentation/arch/x86/sgx.rst @@ -245,7 +245,7 @@ SGX will likely become unusable because the memory available to SGX is limited. However, while this may be fatal to SGX, the rest of the kernel is unlikely to be impacted and should continue to work. -As a result, when this happpens, user should stop running any new +As a result, when this happens, user should stop running any new SGX workloads, (or just any new workloads), and migrate all valuable workloads. Although a machine reboot can recover all EPC memory, the bug should be reported to Linux developers. diff --git a/Documentation/arch/x86/shstk.rst b/Documentation/arch/x86/shstk.rst new file mode 100644 index 000000000000..60260e809baf --- /dev/null +++ b/Documentation/arch/x86/shstk.rst @@ -0,0 +1,179 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================================================== +Control-flow Enforcement Technology (CET) Shadow Stack +====================================================== + +CET Background +============== + +Control-flow Enforcement Technology (CET) covers several related x86 processor +features that provide protection against control flow hijacking attacks. CET +can protect both applications and the kernel. + +CET introduces shadow stack and indirect branch tracking (IBT). A shadow stack +is a secondary stack allocated from memory which cannot be directly modified by +applications. When executing a CALL instruction, the processor pushes the +return address to both the normal stack and the shadow stack. Upon +function return, the processor pops the shadow stack copy and compares it +to the normal stack copy. If the two differ, the processor raises a +control-protection fault. IBT verifies indirect CALL/JMP targets are intended +as marked by the compiler with 'ENDBR' opcodes. Not all CPU's have both Shadow +Stack and Indirect Branch Tracking. Today in the 64-bit kernel, only userspace +shadow stack and kernel IBT are supported. + +Requirements to use Shadow Stack +================================ + +To use userspace shadow stack you need HW that supports it, a kernel +configured with it and userspace libraries compiled with it. + +The kernel Kconfig option is X86_USER_SHADOW_STACK. When compiled in, shadow +stacks can be disabled at runtime with the kernel parameter: nousershstk. + +To build a user shadow stack enabled kernel, Binutils v2.29 or LLVM v6 or later +are required. + +At run time, /proc/cpuinfo shows CET features if the processor supports +CET. "user_shstk" means that userspace shadow stack is supported on the current +kernel and HW. + +Application Enabling +==================== + +An application's CET capability is marked in its ELF note and can be verified +from readelf/llvm-readelf output:: + + readelf -n <application> | grep -a SHSTK + properties: x86 feature: SHSTK + +The kernel does not process these applications markers directly. Applications +or loaders must enable CET features using the interface described in section 4. +Typically this would be done in dynamic loader or static runtime objects, as is +the case in GLIBC. + +Enabling arch_prctl()'s +======================= + +Elf features should be enabled by the loader using the below arch_prctl's. They +are only supported in 64 bit user applications. These operate on the features +on a per-thread basis. The enablement status is inherited on clone, so if the +feature is enabled on the first thread, it will propagate to all the thread's +in an app. + +arch_prctl(ARCH_SHSTK_ENABLE, unsigned long feature) + Enable a single feature specified in 'feature'. Can only operate on + one feature at a time. + +arch_prctl(ARCH_SHSTK_DISABLE, unsigned long feature) + Disable a single feature specified in 'feature'. Can only operate on + one feature at a time. + +arch_prctl(ARCH_SHSTK_LOCK, unsigned long features) + Lock in features at their current enabled or disabled status. 'features' + is a mask of all features to lock. All bits set are processed, unset bits + are ignored. The mask is ORed with the existing value. So any feature bits + set here cannot be enabled or disabled afterwards. + +arch_prctl(ARCH_SHSTK_UNLOCK, unsigned long features) + Unlock features. 'features' is a mask of all features to unlock. All + bits set are processed, unset bits are ignored. Only works via ptrace. + +arch_prctl(ARCH_SHSTK_STATUS, unsigned long addr) + Copy the currently enabled features to the address passed in addr. The + features are described using the bits passed into the others in + 'features'. + +The return values are as follows. On success, return 0. On error, errno can +be:: + + -EPERM if any of the passed feature are locked. + -ENOTSUPP if the feature is not supported by the hardware or + kernel. + -EINVAL arguments (non existing feature, etc) + -EFAULT if could not copy information back to userspace + +The feature's bits supported are:: + + ARCH_SHSTK_SHSTK - Shadow stack + ARCH_SHSTK_WRSS - WRSS + +Currently shadow stack and WRSS are supported via this interface. WRSS +can only be enabled with shadow stack, and is automatically disabled +if shadow stack is disabled. + +Proc Status +=========== +To check if an application is actually running with shadow stack, the +user can read the /proc/$PID/status. It will report "wrss" or "shstk" +depending on what is enabled. The lines look like this:: + + x86_Thread_features: shstk wrss + x86_Thread_features_locked: shstk wrss + +Implementation of the Shadow Stack +================================== + +Shadow Stack Size +----------------- + +A task's shadow stack is allocated from memory to a fixed size of +MIN(RLIMIT_STACK, 4 GB). In other words, the shadow stack is allocated to +the maximum size of the normal stack, but capped to 4 GB. In the case +of the clone3 syscall, there is a stack size passed in and shadow stack +uses this instead of the rlimit. + +Signal +------ + +The main program and its signal handlers use the same shadow stack. Because +the shadow stack stores only return addresses, a large shadow stack covers +the condition that both the program stack and the signal alternate stack run +out. + +When a signal happens, the old pre-signal state is pushed on the stack. When +shadow stack is enabled, the shadow stack specific state is pushed onto the +shadow stack. Today this is only the old SSP (shadow stack pointer), pushed +in a special format with bit 63 set. On sigreturn this old SSP token is +verified and restored by the kernel. The kernel will also push the normal +restorer address to the shadow stack to help userspace avoid a shadow stack +violation on the sigreturn path that goes through the restorer. + +So the shadow stack signal frame format is as follows:: + + |1...old SSP| - Pointer to old pre-signal ssp in sigframe token format + (bit 63 set to 1) + | ...| - Other state may be added in the future + + +32 bit ABI signals are not supported in shadow stack processes. Linux prevents +32 bit execution while shadow stack is enabled by the allocating shadow stacks +outside of the 32 bit address space. When execution enters 32 bit mode, either +via far call or returning to userspace, a #GP is generated by the hardware +which, will be delivered to the process as a segfault. When transitioning to +userspace the register's state will be as if the userspace ip being returned to +caused the segfault. + +Fork +---- + +The shadow stack's vma has VM_SHADOW_STACK flag set; its PTEs are required +to be read-only and dirty. When a shadow stack PTE is not RO and dirty, a +shadow access triggers a page fault with the shadow stack access bit set +in the page fault error code. + +When a task forks a child, its shadow stack PTEs are copied and both the +parent's and the child's shadow stack PTEs are cleared of the dirty bit. +Upon the next shadow stack access, the resulting shadow stack page fault +is handled by page copy/re-use. + +When a pthread child is created, the kernel allocates a new shadow stack +for the new thread. New shadow stack creation behaves like mmap() with respect +to ASLR behavior. Similarly, on thread exit the thread's shadow stack is +disabled. + +Exec +---- + +On exec, shadow stack features are disabled by the kernel. At which point, +userspace can choose to re-enable, or lock them. diff --git a/Documentation/arch/x86/topology.rst b/Documentation/arch/x86/topology.rst index 7f58010ea86a..08ebf9edbfc1 100644 --- a/Documentation/arch/x86/topology.rst +++ b/Documentation/arch/x86/topology.rst @@ -55,19 +55,19 @@ Package-related topology information in the kernel: The number of dies in a package. This information is retrieved via CPUID. - - cpuinfo_x86.cpu_die_id: + - cpuinfo_x86.topo.die_id: The physical ID of the die. This information is retrieved via CPUID. - - cpuinfo_x86.phys_proc_id: + - cpuinfo_x86.topo.pkg_id: The physical ID of the package. This information is retrieved via CPUID and deduced from the APIC IDs of the cores in the package. Modern systems use this value for the socket. There may be multiple - packages within a socket. This value may differ from cpu_die_id. + packages within a socket. This value may differ from topo.die_id. - - cpuinfo_x86.logical_proc_id: + - cpuinfo_x86.topo.logical_pkg_id: The logical ID of the package. As we do not trust BIOSes to enumerate the packages in a consistent way, we introduced the concept of logical package @@ -79,9 +79,7 @@ Package-related topology information in the kernel: The maximum possible number of packages in the system. Helpful for per package facilities to preallocate per package information. - - cpu_llc_id: - - A per-CPU variable containing: + - cpuinfo_x86.topo.llc_id: - On Intel, the first APIC ID of the list of CPUs sharing the Last Level Cache diff --git a/Documentation/arch/xtensa/atomctl.rst b/Documentation/arch/xtensa/atomctl.rst index 1ecbd0ba9a2e..75d174169430 100644 --- a/Documentation/arch/xtensa/atomctl.rst +++ b/Documentation/arch/xtensa/atomctl.rst @@ -23,7 +23,7 @@ doing a Cached (WB) transaction and use the Memory RCW for un-cached operations. For systems without an coherent cache controller, non-MX, we always -use the memory controllers RCW, thought non-MX controlers likely +use the memory controllers RCW, though non-MX controllers likely support the Internal Operation. CUSTOMER-WARNING: diff --git a/Documentation/block/biovecs.rst b/Documentation/block/biovecs.rst index ddb867e0185b..b9dc0c9dbee4 100644 --- a/Documentation/block/biovecs.rst +++ b/Documentation/block/biovecs.rst @@ -134,6 +134,7 @@ Usage of helpers: bio_for_each_bvec_all() bio_first_bvec_all() bio_first_page_all() + bio_first_folio_all() bio_last_bvec_all() * The following helpers iterate over single-page segment. The passed 'struct diff --git a/Documentation/block/blk-mq.rst b/Documentation/block/blk-mq.rst index 31f52f326971..fc06761b6ea9 100644 --- a/Documentation/block/blk-mq.rst +++ b/Documentation/block/blk-mq.rst @@ -56,7 +56,7 @@ sent to the software queue. Then, after the requests are processed by software queues, they will be placed at the hardware queue, a second stage queue where the hardware has direct access to process those requests. However, if the hardware does not have enough -resources to accept more requests, blk-mq will places requests on a temporary +resources to accept more requests, blk-mq will place requests on a temporary queue, to be sent in the future, when the hardware is able. Software staging queues diff --git a/Documentation/block/data-integrity.rst b/Documentation/block/data-integrity.rst index 07a97aa26668..6a760c0eb192 100644 --- a/Documentation/block/data-integrity.rst +++ b/Documentation/block/data-integrity.rst @@ -209,7 +209,7 @@ will require extra work due to the application tag. sector must be set, and the bio should have all data pages added. It is up to the caller to ensure that the bio does not change while I/O is in progress. - Complete bio with error if prepare failed for some reson. + Complete bio with error if prepare failed for some reason. 5.3 Passing Existing Integrity Metadata diff --git a/Documentation/block/ioprio.rst b/Documentation/block/ioprio.rst index f72b0de65af7..a25c6d5df87b 100644 --- a/Documentation/block/ioprio.rst +++ b/Documentation/block/ioprio.rst @@ -80,9 +80,6 @@ ionice.c tool:: #elif defined(__x86_64__) #define __NR_ioprio_set 251 #define __NR_ioprio_get 252 - #elif defined(__ia64__) - #define __NR_ioprio_set 1274 - #define __NR_ioprio_get 1275 #else #error "Unsupported arch" #endif diff --git a/Documentation/block/ublk.rst b/Documentation/block/ublk.rst index 1713b2890abb..ff74b3ec4a98 100644 --- a/Documentation/block/ublk.rst +++ b/Documentation/block/ublk.rst @@ -238,7 +238,7 @@ The's IO is assigned by a unique tag, which is 1:1 mapping with IO request of ``/dev/ublkb*``. UAPI structure of ``ublksrv_io_desc`` is defined for describing each IO from -the driver. A fixed mmaped area (array) on ``/dev/ublkc*`` is provided for +the driver. A fixed mmapped area (array) on ``/dev/ublkc*`` is provided for exporting IO info to the server; such as IO offset, length, OP/flags and buffer address. Each ``ublksrv_io_desc`` instance can be indexed via queue id and IO tag directly. diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst index 38372a956d65..eb19c945f4d5 100644 --- a/Documentation/bpf/bpf_design_QA.rst +++ b/Documentation/bpf/bpf_design_QA.rst @@ -140,11 +140,6 @@ A: Because if we picked one-to-one relationship to x64 it would have made it more complicated to support on arm64 and other archs. Also it needs div-by-zero runtime check. -Q: Why there is no BPF_SDIV for signed divide operation? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A: Because it would be rarely used. llvm errors in such case and -prints a suggestion to use unsigned divide instead. - Q: Why BPF has implicit prologue and epilogue? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A: Because architectures like sparc have register windows and in general diff --git a/Documentation/bpf/bpf_devel_QA.rst b/Documentation/bpf/bpf_devel_QA.rst index 609b71f5747d..de27e1620821 100644 --- a/Documentation/bpf/bpf_devel_QA.rst +++ b/Documentation/bpf/bpf_devel_QA.rst @@ -635,12 +635,12 @@ test coverage. Q: clang flag for target bpf? ----------------------------- -Q: In some cases clang flag ``-target bpf`` is used but in other cases the +Q: In some cases clang flag ``--target=bpf`` is used but in other cases the default clang target, which matches the underlying architecture, is used. What is the difference and when I should use which? A: Although LLVM IR generation and optimization try to stay architecture -independent, ``-target <arch>`` still has some impact on generated code: +independent, ``--target=<arch>`` still has some impact on generated code: - BPF program may recursively include header file(s) with file scope inline assembly codes. The default target can handle this well, @@ -658,7 +658,7 @@ independent, ``-target <arch>`` still has some impact on generated code: The clang option ``-fno-jump-tables`` can be used to disable switch table generation. -- For clang ``-target bpf``, it is guaranteed that pointer or long / +- For clang ``--target=bpf``, it is guaranteed that pointer or long / unsigned long types will always have a width of 64 bit, no matter whether underlying clang binary or default target (or kernel) is 32 bit. However, when native clang target is used, then it will @@ -668,7 +668,7 @@ independent, ``-target <arch>`` still has some impact on generated code: while the BPF LLVM back end still operates in 64 bit. The native target is mostly needed in tracing for the case of walking ``pt_regs`` or other kernel structures where CPU's register width matters. - Otherwise, ``clang -target bpf`` is generally recommended. + Otherwise, ``clang --target=bpf`` is generally recommended. You should use default target when: @@ -685,7 +685,7 @@ when: into these structures is verified by the BPF verifier and may result in verification failures if the native architecture is not aligned with the BPF architecture, e.g. 64-bit. An example of this is - BPF_PROG_TYPE_SK_MSG require ``-target bpf`` + BPF_PROG_TYPE_SK_MSG require ``--target=bpf`` .. Links diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst index 7cd7c5415a99..e43c2fdafcd7 100644 --- a/Documentation/bpf/btf.rst +++ b/Documentation/bpf/btf.rst @@ -726,8 +726,8 @@ same as the one describe in :ref:`BTF_Type_String`. 4.2 .BTF.ext section -------------------- -The .BTF.ext section encodes func_info and line_info which needs loader -manipulation before loading into the kernel. +The .BTF.ext section encodes func_info, line_info and CO-RE relocations +which needs loader manipulation before loading into the kernel. The specification for .BTF.ext section is defined at ``tools/lib/bpf/btf.h`` and ``tools/lib/bpf/btf.c``. @@ -745,15 +745,20 @@ The current header of .BTF.ext section:: __u32 func_info_len; __u32 line_info_off; __u32 line_info_len; + + /* optional part of .BTF.ext header */ + __u32 core_relo_off; + __u32 core_relo_len; }; It is very similar to .BTF section. Instead of type/string section, it -contains func_info and line_info section. See :ref:`BPF_Prog_Load` for details -about func_info and line_info record format. +contains func_info, line_info and core_relo sub-sections. +See :ref:`BPF_Prog_Load` for details about func_info and line_info +record format. The func_info is organized as below.:: - func_info_rec_size + func_info_rec_size /* __u32 value */ btf_ext_info_sec for section #1 /* func_info for section #1 */ btf_ext_info_sec for section #2 /* func_info for section #2 */ ... @@ -773,7 +778,7 @@ Here, num_info must be greater than 0. The line_info is organized as below.:: - line_info_rec_size + line_info_rec_size /* __u32 value */ btf_ext_info_sec for section #1 /* line_info for section #1 */ btf_ext_info_sec for section #2 /* line_info for section #2 */ ... @@ -787,6 +792,20 @@ kernel API, the ``insn_off`` is the instruction offset in the unit of ``struct bpf_insn``. For ELF API, the ``insn_off`` is the byte offset from the beginning of section (``btf_ext_info_sec->sec_name_off``). +The core_relo is organized as below.:: + + core_relo_rec_size /* __u32 value */ + btf_ext_info_sec for section #1 /* core_relo for section #1 */ + btf_ext_info_sec for section #2 /* core_relo for section #2 */ + +``core_relo_rec_size`` specifies the size of ``bpf_core_relo`` +structure when .BTF.ext is generated. All ``bpf_core_relo`` structures +within a single ``btf_ext_info_sec`` describe relocations applied to +section named by ``btf_ext_info_sec->sec_name_off``. + +See :ref:`Documentation/bpf/llvm_reloc.rst <btf-co-re-relocations>` +for more information on CO-RE relocations. + 4.2 .BTF_ids section -------------------- @@ -990,7 +1009,7 @@ format.:: } g2; int main() { return 0; } int test() { return 0; } - -bash-4.4$ clang -c -g -O2 -target bpf t2.c + -bash-4.4$ clang -c -g -O2 --target=bpf t2.c -bash-4.4$ readelf -S t2.o ...... [ 8] .BTF PROGBITS 0000000000000000 00000247 @@ -1000,7 +1019,7 @@ format.:: [10] .rel.BTF.ext REL 0000000000000000 000007e0 0000000000000040 0000000000000010 16 9 8 ...... - -bash-4.4$ clang -S -g -O2 -target bpf t2.c + -bash-4.4$ clang -S -g -O2 --target=bpf t2.c -bash-4.4$ cat t2.s ...... .section .BTF,"",@progbits diff --git a/Documentation/bpf/cpumasks.rst b/Documentation/bpf/cpumasks.rst index 3139c7c02e79..a22b6ad105fb 100644 --- a/Documentation/bpf/cpumasks.rst +++ b/Documentation/bpf/cpumasks.rst @@ -364,7 +364,7 @@ can be used to query the contents of cpumasks. ---- Some example usages of these querying kfuncs were shown above. We will not -replicate those exmaples here. Note, however, that all of the aforementioned +replicate those examples here. Note, however, that all of the aforementioned kfuncs are tested in `tools/testing/selftests/bpf/progs/cpumask_success.c`_, so please take a look there if you're looking for more examples of how they can be used. diff --git a/Documentation/bpf/graph_ds_impl.rst b/Documentation/bpf/graph_ds_impl.rst index 61274622b71d..06288cc719b3 100644 --- a/Documentation/bpf/graph_ds_impl.rst +++ b/Documentation/bpf/graph_ds_impl.rst @@ -23,7 +23,7 @@ Introduction The BPF map API has historically been the main way to expose data structures of various types for use within BPF programs. Some data structures fit naturally -with the map API (HASH, ARRAY), others less so. Consequentially, programs +with the map API (HASH, ARRAY), others less so. Consequently, programs interacting with the latter group of data structures can be hard to parse for kernel programmers without previous BPF experience. diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst index dbb39e8f9889..aeaeb35e6d4a 100644 --- a/Documentation/bpf/index.rst +++ b/Documentation/bpf/index.rst @@ -12,9 +12,9 @@ that goes into great technical depth about the BPF Architecture. .. toctree:: :maxdepth: 1 - instruction-set verifier libbpf/index + standardization/index btf faq syscall_api diff --git a/Documentation/bpf/libbpf/program_types.rst b/Documentation/bpf/libbpf/program_types.rst index ad4d4d5eecb0..63bb88846e50 100644 --- a/Documentation/bpf/libbpf/program_types.rst +++ b/Documentation/bpf/libbpf/program_types.rst @@ -56,6 +56,16 @@ described in more detail in the footnotes. | | ``BPF_CGROUP_UDP6_RECVMSG`` | ``cgroup/recvmsg6`` | | + +----------------------------------------+----------------------------------+-----------+ | | ``BPF_CGROUP_UDP6_SENDMSG`` | ``cgroup/sendmsg6`` | | +| +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_UNIX_CONNECT`` | ``cgroup/connect_unix`` | | +| +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_UNIX_SENDMSG`` | ``cgroup/sendmsg_unix`` | | +| +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_UNIX_RECVMSG`` | ``cgroup/recvmsg_unix`` | | +| +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_UNIX_GETPEERNAME`` | ``cgroup/getpeername_unix`` | | +| +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_UNIX_GETSOCKNAME`` | ``cgroup/getsockname_unix`` | | +-------------------------------------------+----------------------------------------+----------------------------------+-----------+ | ``BPF_PROG_TYPE_CGROUP_SOCK`` | ``BPF_CGROUP_INET4_POST_BIND`` | ``cgroup/post_bind4`` | | + +----------------------------------------+----------------------------------+-----------+ diff --git a/Documentation/bpf/linux-notes.rst b/Documentation/bpf/linux-notes.rst index 508d009d3bed..00d2693de025 100644 --- a/Documentation/bpf/linux-notes.rst +++ b/Documentation/bpf/linux-notes.rst @@ -45,7 +45,8 @@ On Linux, this integer is a BTF ID. Legacy BPF Packet access instructions ===================================== -As mentioned in the `ISA standard documentation <instruction-set.rst#legacy-bpf-packet-access-instructions>`_, +As mentioned in the `ISA standard documentation +<instruction-set.html#legacy-bpf-packet-access-instructions>`_, Linux has special eBPF instructions for access to packet data that have been carried over from classic BPF to retain the performance of legacy socket filters running in the eBPF interpreter. diff --git a/Documentation/bpf/llvm_reloc.rst b/Documentation/bpf/llvm_reloc.rst index e4a777a6a3a2..44188e219d32 100644 --- a/Documentation/bpf/llvm_reloc.rst +++ b/Documentation/bpf/llvm_reloc.rst @@ -28,7 +28,7 @@ For example, for the following code:: return g1 + g2 + l1 + l2; } -Compiled with ``clang -target bpf -O2 -c test.c``, the following is +Compiled with ``clang --target=bpf -O2 -c test.c``, the following is the code with ``llvm-objdump -dr test.o``:: 0: 18 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 r1 = 0 ll @@ -157,7 +157,7 @@ and ``call`` instructions. For example:: return gfunc(a, b) + lfunc(a, b) + global; } -Compiled with ``clang -target bpf -O2 -c test.c``, we will have +Compiled with ``clang --target=bpf -O2 -c test.c``, we will have following code with `llvm-objdump -dr test.o``:: Disassembly of section .text: @@ -203,7 +203,7 @@ The following is an example to show how R_BPF_64_ABS64 could be generated:: int global() { return 0; } struct t { void *g; } gbl = { global }; -Compiled with ``clang -target bpf -O2 -g -c test.c``, we will see a +Compiled with ``clang --target=bpf -O2 -g -c test.c``, we will see a relocation below in ``.data`` section with command ``llvm-readelf -r test.o``:: @@ -240,3 +240,307 @@ The .BTF/.BTF.ext sections has R_BPF_64_NODYLD32 relocations:: Offset Info Type Symbol's Value Symbol's Name 000000000000002c 0000000200000004 R_BPF_64_NODYLD32 0000000000000000 .text 0000000000000040 0000000200000004 R_BPF_64_NODYLD32 0000000000000000 .text + +.. _btf-co-re-relocations: + +================= +CO-RE Relocations +================= + +From object file point of view CO-RE mechanism is implemented as a set +of CO-RE specific relocation records. These relocation records are not +related to ELF relocations and are encoded in .BTF.ext section. +See :ref:`Documentation/bpf/btf.rst <BTF_Ext_Section>` for more +information on .BTF.ext structure. + +CO-RE relocations are applied to BPF instructions to update immediate +or offset fields of the instruction at load time with information +relevant for target kernel. + +Field to patch is selected basing on the instruction class: + +* For BPF_ALU, BPF_ALU64, BPF_LD `immediate` field is patched; +* For BPF_LDX, BPF_STX, BPF_ST `offset` field is patched; +* BPF_JMP, BPF_JMP32 instructions **should not** be patched. + +Relocation kinds +================ + +There are several kinds of CO-RE relocations that could be split in +three groups: + +* Field-based - patch instruction with field related information, e.g. + change offset field of the BPF_LDX instruction to reflect offset + of a specific structure field in the target kernel. + +* Type-based - patch instruction with type related information, e.g. + change immediate field of the BPF_ALU move instruction to 0 or 1 to + reflect if specific type is present in the target kernel. + +* Enum-based - patch instruction with enum related information, e.g. + change immediate field of the BPF_LD_IMM64 instruction to reflect + value of a specific enum literal in the target kernel. + +The complete list of relocation kinds is represented by the following enum: + +.. code-block:: c + + enum bpf_core_relo_kind { + BPF_CORE_FIELD_BYTE_OFFSET = 0, /* field byte offset */ + BPF_CORE_FIELD_BYTE_SIZE = 1, /* field size in bytes */ + BPF_CORE_FIELD_EXISTS = 2, /* field existence in target kernel */ + BPF_CORE_FIELD_SIGNED = 3, /* field signedness (0 - unsigned, 1 - signed) */ + BPF_CORE_FIELD_LSHIFT_U64 = 4, /* bitfield-specific left bitshift */ + BPF_CORE_FIELD_RSHIFT_U64 = 5, /* bitfield-specific right bitshift */ + BPF_CORE_TYPE_ID_LOCAL = 6, /* type ID in local BPF object */ + BPF_CORE_TYPE_ID_TARGET = 7, /* type ID in target kernel */ + BPF_CORE_TYPE_EXISTS = 8, /* type existence in target kernel */ + BPF_CORE_TYPE_SIZE = 9, /* type size in bytes */ + BPF_CORE_ENUMVAL_EXISTS = 10, /* enum value existence in target kernel */ + BPF_CORE_ENUMVAL_VALUE = 11, /* enum value integer value */ + BPF_CORE_TYPE_MATCHES = 12, /* type match in target kernel */ + }; + +Notes: + +* ``BPF_CORE_FIELD_LSHIFT_U64`` and ``BPF_CORE_FIELD_RSHIFT_U64`` are + supposed to be used to read bitfield values using the following + algorithm: + + .. code-block:: c + + // To read bitfield ``f`` from ``struct s`` + is_signed = relo(s->f, BPF_CORE_FIELD_SIGNED) + off = relo(s->f, BPF_CORE_FIELD_BYTE_OFFSET) + sz = relo(s->f, BPF_CORE_FIELD_BYTE_SIZE) + l = relo(s->f, BPF_CORE_FIELD_LSHIFT_U64) + r = relo(s->f, BPF_CORE_FIELD_RSHIFT_U64) + // define ``v`` as signed or unsigned integer of size ``sz`` + v = *({s|u}<sz> *)((void *)s + off) + v <<= l + v >>= r + +* The ``BPF_CORE_TYPE_MATCHES`` queries matching relation, defined as + follows: + + * for integers: types match if size and signedness match; + * for arrays & pointers: target types are recursively matched; + * for structs & unions: + + * local members need to exist in target with the same name; + + * for each member we recursively check match unless it is already behind a + pointer, in which case we only check matching names and compatible kind; + + * for enums: + + * local variants have to have a match in target by symbolic name (but not + numeric value); + + * size has to match (but enum may match enum64 and vice versa); + + * for function pointers: + + * number and position of arguments in local type has to match target; + * for each argument and the return value we recursively check match. + +CO-RE Relocation Record +======================= + +Relocation record is encoded as the following structure: + +.. code-block:: c + + struct bpf_core_relo { + __u32 insn_off; + __u32 type_id; + __u32 access_str_off; + enum bpf_core_relo_kind kind; + }; + +* ``insn_off`` - instruction offset (in bytes) within a code section + associated with this relocation; + +* ``type_id`` - BTF type ID of the "root" (containing) entity of a + relocatable type or field; + +* ``access_str_off`` - offset into corresponding .BTF string section. + String interpretation depends on specific relocation kind: + + * for field-based relocations, string encodes an accessed field using + a sequence of field and array indices, separated by colon (:). It's + conceptually very close to LLVM's `getelementptr <GEP_>`_ instruction's + arguments for identifying offset to a field. For example, consider the + following C code: + + .. code-block:: c + + struct sample { + int a; + int b; + struct { int c[10]; }; + } __attribute__((preserve_access_index)); + struct sample *s; + + * Access to ``s[0].a`` would be encoded as ``0:0``: + + * ``0``: first element of ``s`` (as if ``s`` is an array); + * ``0``: index of field ``a`` in ``struct sample``. + + * Access to ``s->a`` would be encoded as ``0:0`` as well. + * Access to ``s->b`` would be encoded as ``0:1``: + + * ``0``: first element of ``s``; + * ``1``: index of field ``b`` in ``struct sample``. + + * Access to ``s[1].c[5]`` would be encoded as ``1:2:0:5``: + + * ``1``: second element of ``s``; + * ``2``: index of anonymous structure field in ``struct sample``; + * ``0``: index of field ``c`` in anonymous structure; + * ``5``: access to array element #5. + + * for type-based relocations, string is expected to be just "0"; + + * for enum value-based relocations, string contains an index of enum + value within its enum type; + +* ``kind`` - one of ``enum bpf_core_relo_kind``. + +.. _GEP: https://llvm.org/docs/LangRef.html#getelementptr-instruction + +.. _btf_co_re_relocation_examples: + +CO-RE Relocation Examples +========================= + +For the following C code: + +.. code-block:: c + + struct foo { + int a; + int b; + unsigned c:15; + } __attribute__((preserve_access_index)); + + enum bar { U, V }; + +With the following BTF definitions: + +.. code-block:: + + ... + [2] STRUCT 'foo' size=8 vlen=2 + 'a' type_id=3 bits_offset=0 + 'b' type_id=3 bits_offset=32 + 'c' type_id=4 bits_offset=64 bitfield_size=15 + [3] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED + [4] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none) + ... + [16] ENUM 'bar' encoding=UNSIGNED size=4 vlen=2 + 'U' val=0 + 'V' val=1 + +Field offset relocations are generated automatically when +``__attribute__((preserve_access_index))`` is used, for example: + +.. code-block:: c + + void alpha(struct foo *s, volatile unsigned long *g) { + *g = s->a; + s->a = 1; + } + + 00 <alpha>: + 0: r3 = *(s32 *)(r1 + 0x0) + 00: CO-RE <byte_off> [2] struct foo::a (0:0) + 1: *(u64 *)(r2 + 0x0) = r3 + 2: *(u32 *)(r1 + 0x0) = 0x1 + 10: CO-RE <byte_off> [2] struct foo::a (0:0) + 3: exit + + +All relocation kinds could be requested via built-in functions. +E.g. field-based relocations: + +.. code-block:: c + + void bravo(struct foo *s, volatile unsigned long *g) { + *g = __builtin_preserve_field_info(s->b, 0 /* field byte offset */); + *g = __builtin_preserve_field_info(s->b, 1 /* field byte size */); + *g = __builtin_preserve_field_info(s->b, 2 /* field existence */); + *g = __builtin_preserve_field_info(s->b, 3 /* field signedness */); + *g = __builtin_preserve_field_info(s->c, 4 /* bitfield left shift */); + *g = __builtin_preserve_field_info(s->c, 5 /* bitfield right shift */); + } + + 20 <bravo>: + 4: r1 = 0x4 + 20: CO-RE <byte_off> [2] struct foo::b (0:1) + 5: *(u64 *)(r2 + 0x0) = r1 + 6: r1 = 0x4 + 30: CO-RE <byte_sz> [2] struct foo::b (0:1) + 7: *(u64 *)(r2 + 0x0) = r1 + 8: r1 = 0x1 + 40: CO-RE <field_exists> [2] struct foo::b (0:1) + 9: *(u64 *)(r2 + 0x0) = r1 + 10: r1 = 0x1 + 50: CO-RE <signed> [2] struct foo::b (0:1) + 11: *(u64 *)(r2 + 0x0) = r1 + 12: r1 = 0x31 + 60: CO-RE <lshift_u64> [2] struct foo::c (0:2) + 13: *(u64 *)(r2 + 0x0) = r1 + 14: r1 = 0x31 + 70: CO-RE <rshift_u64> [2] struct foo::c (0:2) + 15: *(u64 *)(r2 + 0x0) = r1 + 16: exit + + +Type-based relocations: + +.. code-block:: c + + void charlie(struct foo *s, volatile unsigned long *g) { + *g = __builtin_preserve_type_info(*s, 0 /* type existence */); + *g = __builtin_preserve_type_info(*s, 1 /* type size */); + *g = __builtin_preserve_type_info(*s, 2 /* type matches */); + *g = __builtin_btf_type_id(*s, 0 /* type id in this object file */); + *g = __builtin_btf_type_id(*s, 1 /* type id in target kernel */); + } + + 88 <charlie>: + 17: r1 = 0x1 + 88: CO-RE <type_exists> [2] struct foo + 18: *(u64 *)(r2 + 0x0) = r1 + 19: r1 = 0xc + 98: CO-RE <type_size> [2] struct foo + 20: *(u64 *)(r2 + 0x0) = r1 + 21: r1 = 0x1 + a8: CO-RE <type_matches> [2] struct foo + 22: *(u64 *)(r2 + 0x0) = r1 + 23: r1 = 0x2 ll + b8: CO-RE <local_type_id> [2] struct foo + 25: *(u64 *)(r2 + 0x0) = r1 + 26: r1 = 0x2 ll + d0: CO-RE <target_type_id> [2] struct foo + 28: *(u64 *)(r2 + 0x0) = r1 + 29: exit + +Enum-based relocations: + +.. code-block:: c + + void delta(struct foo *s, volatile unsigned long *g) { + *g = __builtin_preserve_enum_value(*(enum bar *)U, 0 /* enum literal existence */); + *g = __builtin_preserve_enum_value(*(enum bar *)V, 1 /* enum literal value */); + } + + f0 <delta>: + 30: r1 = 0x1 ll + f0: CO-RE <enumval_exists> [16] enum bar::U = 0 + 32: *(u64 *)(r2 + 0x0) = r1 + 33: r1 = 0x1 ll + 108: CO-RE <enumval_value> [16] enum bar::V = 1 + 35: *(u64 *)(r2 + 0x0) = r1 + 36: exit diff --git a/Documentation/bpf/prog_flow_dissector.rst b/Documentation/bpf/prog_flow_dissector.rst index 4d86780ab0f1..f24270b8b034 100644 --- a/Documentation/bpf/prog_flow_dissector.rst +++ b/Documentation/bpf/prog_flow_dissector.rst @@ -113,7 +113,7 @@ Flags used by ``eth_get_headlen`` to estimate length of all headers for GRO. * ``BPF_FLOW_DISSECTOR_F_STOP_AT_FLOW_LABEL`` - tells BPF flow dissector to stop parsing as soon as it reaches IPv6 flow label; used by - ``___skb_get_hash`` and ``__skb_get_hash_symmetric`` to get flow hash. + ``___skb_get_hash`` to get flow hash. * ``BPF_FLOW_DISSECTOR_F_STOP_AT_ENCAP`` - tells BPF flow dissector to stop parsing as soon as it reaches encapsulated headers; used by routing infrastructure. diff --git a/Documentation/bpf/standardization/abi.rst b/Documentation/bpf/standardization/abi.rst new file mode 100644 index 000000000000..0c2e10eeb89a --- /dev/null +++ b/Documentation/bpf/standardization/abi.rst @@ -0,0 +1,25 @@ +.. contents:: +.. sectnum:: + +=================================================== +BPF ABI Recommended Conventions and Guidelines v1.0 +=================================================== + +This is version 1.0 of an informational document containing recommended +conventions and guidelines for producing portable BPF program binaries. + +Registers and calling convention +================================ + +BPF has 10 general purpose registers and a read-only frame pointer register, +all of which are 64-bits wide. + +The BPF calling convention is defined as: + +* R0: return value from function calls, and exit value for BPF programs +* R1 - R5: arguments for function calls +* R6 - R9: callee saved registers that function calls will preserve +* R10: read-only frame pointer to access stack + +R0 - R5 are scratch registers and BPF programs needs to spill/fill them if +necessary across calls. diff --git a/Documentation/bpf/standardization/index.rst b/Documentation/bpf/standardization/index.rst new file mode 100644 index 000000000000..a50c3baf6345 --- /dev/null +++ b/Documentation/bpf/standardization/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) + +=================== +BPF Standardization +=================== + +This directory contains documents that are being iterated on as part of the BPF +standardization effort with the IETF. See the `IETF BPF Working Group`_ page +for the working group charter, documents, and more. + +.. toctree:: + :maxdepth: 1 + + instruction-set + abi + +.. Links: +.. _IETF BPF Working Group: https://datatracker.ietf.org/wg/bpf/about/ diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst index 6644842cd3ea..245b6defc298 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/standardization/instruction-set.rst @@ -1,39 +1,106 @@ .. contents:: .. sectnum:: -======================================== -eBPF Instruction Set Specification, v1.0 -======================================== +======================================= +BPF Instruction Set Specification, v1.0 +======================================= -This document specifies version 1.0 of the eBPF instruction set. +This document specifies version 1.0 of the BPF instruction set. Documentation conventions ========================= -For brevity, this document uses the type notion "u64", "u32", etc. -to mean an unsigned integer whose width is the specified number of bits, -and "s32", etc. to mean a signed integer of the specified number of bits. - -Registers and calling convention -================================ - -eBPF has 10 general purpose registers and a read-only frame pointer register, -all of which are 64-bits wide. - -The eBPF calling convention is defined as: - -* R0: return value from function calls, and exit value for eBPF programs -* R1 - R5: arguments for function calls -* R6 - R9: callee saved registers that function calls will preserve -* R10: read-only frame pointer to access stack - -R0 - R5 are scratch registers and eBPF programs needs to spill/fill them if -necessary across calls. +For brevity and consistency, this document refers to families +of types using a shorthand syntax and refers to several expository, +mnemonic functions when describing the semantics of instructions. +The range of valid values for those types and the semantics of those +functions are defined in the following subsections. + +Types +----- +This document refers to integer types with the notation `SN` to specify +a type's signedness (`S`) and bit width (`N`), respectively. + +.. table:: Meaning of signedness notation. + + ==== ========= + `S` Meaning + ==== ========= + `u` unsigned + `s` signed + ==== ========= + +.. table:: Meaning of bit-width notation. + + ===== ========= + `N` Bit width + ===== ========= + `8` 8 bits + `16` 16 bits + `32` 32 bits + `64` 64 bits + `128` 128 bits + ===== ========= + +For example, `u32` is a type whose valid values are all the 32-bit unsigned +numbers and `s16` is a types whose valid values are all the 16-bit signed +numbers. + +Functions +--------- +* `htobe16`: Takes an unsigned 16-bit number in host-endian format and + returns the equivalent number as an unsigned 16-bit number in big-endian + format. +* `htobe32`: Takes an unsigned 32-bit number in host-endian format and + returns the equivalent number as an unsigned 32-bit number in big-endian + format. +* `htobe64`: Takes an unsigned 64-bit number in host-endian format and + returns the equivalent number as an unsigned 64-bit number in big-endian + format. +* `htole16`: Takes an unsigned 16-bit number in host-endian format and + returns the equivalent number as an unsigned 16-bit number in little-endian + format. +* `htole32`: Takes an unsigned 32-bit number in host-endian format and + returns the equivalent number as an unsigned 32-bit number in little-endian + format. +* `htole64`: Takes an unsigned 64-bit number in host-endian format and + returns the equivalent number as an unsigned 64-bit number in little-endian + format. +* `bswap16`: Takes an unsigned 16-bit number in either big- or little-endian + format and returns the equivalent number with the same bit width but + opposite endianness. +* `bswap32`: Takes an unsigned 32-bit number in either big- or little-endian + format and returns the equivalent number with the same bit width but + opposite endianness. +* `bswap64`: Takes an unsigned 64-bit number in either big- or little-endian + format and returns the equivalent number with the same bit width but + opposite endianness. + + +Definitions +----------- + +.. glossary:: + + Sign Extend + To `sign extend an` ``X`` `-bit number, A, to a` ``Y`` `-bit number, B ,` means to + + #. Copy all ``X`` bits from `A` to the lower ``X`` bits of `B`. + #. Set the value of the remaining ``Y`` - ``X`` bits of `B` to the value of + the most-significant bit of `A`. + +.. admonition:: Example + + Sign extend an 8-bit number ``A`` to a 16-bit number ``B`` on a big-endian platform: + :: + + A: 10000110 + B: 11111111 10000110 Instruction encoding ==================== -eBPF has two instruction encodings: +BPF has two instruction encodings: * the basic instruction encoding, which uses 64 bits to encode an instruction * the wide instruction encoding, which appends a second 64-bit immediate (i.e., @@ -154,27 +221,30 @@ otherwise identical operations. The 'code' field encodes the operation as below, where 'src' and 'dst' refer to the values of the source and destination registers, respectively. -======== ===== ========================================================== -code value description -======== ===== ========================================================== -BPF_ADD 0x00 dst += src -BPF_SUB 0x10 dst -= src -BPF_MUL 0x20 dst \*= src -BPF_DIV 0x30 dst = (src != 0) ? (dst / src) : 0 -BPF_OR 0x40 dst \|= src -BPF_AND 0x50 dst &= src -BPF_LSH 0x60 dst <<= (src & mask) -BPF_RSH 0x70 dst >>= (src & mask) -BPF_NEG 0x80 dst = ~src -BPF_MOD 0x90 dst = (src != 0) ? (dst % src) : dst -BPF_XOR 0xa0 dst ^= src -BPF_MOV 0xb0 dst = src -BPF_ARSH 0xc0 sign extending dst >>= (src & mask) -BPF_END 0xd0 byte swap operations (see `Byte swap instructions`_ below) -======== ===== ========================================================== +========= ===== ======= ========================================================== +code value offset description +========= ===== ======= ========================================================== +BPF_ADD 0x00 0 dst += src +BPF_SUB 0x10 0 dst -= src +BPF_MUL 0x20 0 dst \*= src +BPF_DIV 0x30 0 dst = (src != 0) ? (dst / src) : 0 +BPF_SDIV 0x30 1 dst = (src != 0) ? (dst s/ src) : 0 +BPF_OR 0x40 0 dst \|= src +BPF_AND 0x50 0 dst &= src +BPF_LSH 0x60 0 dst <<= (src & mask) +BPF_RSH 0x70 0 dst >>= (src & mask) +BPF_NEG 0x80 0 dst = -dst +BPF_MOD 0x90 0 dst = (src != 0) ? (dst % src) : dst +BPF_SMOD 0x90 1 dst = (src != 0) ? (dst s% src) : dst +BPF_XOR 0xa0 0 dst ^= src +BPF_MOV 0xb0 0 dst = src +BPF_MOVSX 0xb0 8/16/32 dst = (s8,s16,s32)src +BPF_ARSH 0xc0 0 :term:`sign extending<Sign Extend>` dst >>= (src & mask) +BPF_END 0xd0 0 byte swap operations (see `Byte swap instructions`_ below) +========= ===== ======= ========================================================== Underflow and overflow are allowed during arithmetic operations, meaning -the 64-bit or 32-bit value will wrap. If eBPF program execution would +the 64-bit or 32-bit value will wrap. If BPF program execution would result in division by zero, the destination register is instead set to zero. If execution would result in modulo by zero, for ``BPF_ALU64`` the value of the destination register is unchanged whereas for ``BPF_ALU`` the upper @@ -198,47 +268,83 @@ where '(u32)' indicates that the upper 32 bits are zeroed. dst = dst ^ imm32 -Also note that the division and modulo operations are unsigned. Thus, for -``BPF_ALU``, 'imm' is first interpreted as an unsigned 32-bit value, whereas -for ``BPF_ALU64``, 'imm' is first sign extended to 64 bits and the result -interpreted as an unsigned 64-bit value. There are no instructions for -signed division or modulo. +Note that most instructions have instruction offset of 0. Only three instructions +(``BPF_SDIV``, ``BPF_SMOD``, ``BPF_MOVSX``) have a non-zero offset. + +The division and modulo operations support both unsigned and signed flavors. + +For unsigned operations (``BPF_DIV`` and ``BPF_MOD``), for ``BPF_ALU``, +'imm' is interpreted as a 32-bit unsigned value. For ``BPF_ALU64``, +'imm' is first :term:`sign extended<Sign Extend>` from 32 to 64 bits, and then +interpreted as a 64-bit unsigned value. + +For signed operations (``BPF_SDIV`` and ``BPF_SMOD``), for ``BPF_ALU``, +'imm' is interpreted as a 32-bit signed value. For ``BPF_ALU64``, 'imm' +is first :term:`sign extended<Sign Extend>` from 32 to 64 bits, and then +interpreted as a 64-bit signed value. + +Note that there are varying definitions of the signed modulo operation +when the dividend or divisor are negative, where implementations often +vary by language such that Python, Ruby, etc. differ from C, Go, Java, +etc. This specification requires that signed modulo use truncated division +(where -13 % 3 == -1) as implemented in C, Go, etc.: + + a % n = a - n * trunc(a / n) + +The ``BPF_MOVSX`` instruction does a move operation with sign extension. +``BPF_ALU | BPF_MOVSX`` :term:`sign extends<Sign Extend>` 8-bit and 16-bit operands into 32 +bit operands, and zeroes the remaining upper 32 bits. +``BPF_ALU64 | BPF_MOVSX`` :term:`sign extends<Sign Extend>` 8-bit, 16-bit, and 32-bit +operands into 64 bit operands. Shift operations use a mask of 0x3F (63) for 64-bit operations and 0x1F (31) for 32-bit operations. Byte swap instructions -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- -The byte swap instructions use an instruction class of ``BPF_ALU`` and a 4-bit -'code' field of ``BPF_END``. +The byte swap instructions use instruction classes of ``BPF_ALU`` and ``BPF_ALU64`` +and a 4-bit 'code' field of ``BPF_END``. The byte swap instructions operate on the destination register only and do not use a separate source register or immediate value. -The 1-bit source operand field in the opcode is used to select what byte -order the operation convert from or to: +For ``BPF_ALU``, the 1-bit source operand field in the opcode is used to +select what byte order the operation converts from or to. For +``BPF_ALU64``, the 1-bit source operand field in the opcode is reserved +and must be set to 0. -========= ===== ================================================= -source value description -========= ===== ================================================= -BPF_TO_LE 0x00 convert between host byte order and little endian -BPF_TO_BE 0x08 convert between host byte order and big endian -========= ===== ================================================= +========= ========= ===== ================================================= +class source value description +========= ========= ===== ================================================= +BPF_ALU BPF_TO_LE 0x00 convert between host byte order and little endian +BPF_ALU BPF_TO_BE 0x08 convert between host byte order and big endian +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. Examples: -``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16 means:: +``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16/32/64 means:: dst = htole16(dst) + dst = htole32(dst) + dst = htole64(dst) -``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 64 means:: +``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 16/32/64 means:: + dst = htobe16(dst) + dst = htobe32(dst) dst = htobe64(dst) +``BPF_ALU64 | BPF_TO_LE | BPF_END`` with imm = 16/32/64 means:: + + dst = bswap16(dst) + dst = bswap32(dst) + dst = bswap64(dst) + Jump instructions ----------------- @@ -249,7 +355,8 @@ The 'code' field encodes the operation as below: ======== ===== === =========================================== ========================================= code value src description notes ======== ===== === =========================================== ========================================= -BPF_JA 0x0 0x0 PC += offset BPF_JMP only +BPF_JA 0x0 0x0 PC += offset BPF_JMP class +BPF_JA 0x0 0x0 PC += imm BPF_JMP32 class 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 @@ -258,7 +365,7 @@ 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 += offset see `Program-local 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 @@ -267,7 +374,7 @@ BPF_JSLT 0xc any PC += offset if dst < src signed BPF_JSLE 0xd any PC += offset if dst <= src signed ======== ===== === =========================================== ========================================= -The eBPF program needs to store the return value into register R0 before doing a +The BPF program needs to store the return value into register R0 before doing a ``BPF_EXIT``. Example: @@ -278,6 +385,19 @@ Example: where 's>=' indicates a signed '>=' comparison. +``BPF_JA | BPF_K | BPF_JMP32`` (0x06) means:: + + gotol +imm + +where 'imm' means the branch offset comes from insn 'imm' field. + +Note that there are two flavors of ``BPF_JA`` instructions. The +``BPF_JMP`` class permits a 16-bit jump offset specified by the 'offset' +field, whereas the ``BPF_JMP32`` class permits a 32-bit jump offset +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. + Helper functions ~~~~~~~~~~~~~~~~ @@ -296,8 +416,8 @@ Program-local functions ~~~~~~~~~~~~~~~~~~~~~~~ Program-local functions are functions exposed by the same BPF program as the caller, and are referenced by offset from the call instruction, similar to -``BPF_JA``. A ``BPF_EXIT`` within the program-local function will return to -the caller. +``BPF_JA``. The offset is encoded in the imm field of the call instruction. +A ``BPF_EXIT`` within the program-local function will return to the caller. Load and store instructions =========================== @@ -320,6 +440,7 @@ The mode modifier is one of: BPF_ABS 0x20 legacy BPF packet access (absolute) `Legacy BPF Packet access instructions`_ BPF_IND 0x40 legacy BPF packet access (indirect) `Legacy BPF Packet access instructions`_ BPF_MEM 0x60 regular load and store operations `Regular load and store operations`_ + BPF_MEMSX 0x80 sign-extension load operations `Sign-extension load operations`_ BPF_ATOMIC 0xc0 atomic operations `Atomic operations`_ ============= ===== ==================================== ============= @@ -350,18 +471,32 @@ instructions that transfer data between a register and memory. ``BPF_MEM | <size> | BPF_LDX`` means:: - dst = *(size *) (src + offset) + dst = *(unsigned size *) (src + offset) + +Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW`` and +'unsigned size' is one of u8, u16, u32 or u64. + +Sign-extension load operations +------------------------------ + +The ``BPF_MEMSX`` mode modifier is used to encode :term:`sign-extension<Sign Extend>` load +instructions that transfer data between a register and memory. + +``BPF_MEMSX | <size> | BPF_LDX`` means:: + + dst = *(signed size *) (src + offset) -Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``. +Where size is one of: ``BPF_B``, ``BPF_H`` or ``BPF_W``, and +'signed size' is one of s8, s16 or s32. Atomic operations ----------------- Atomic operations are operations that operate on memory and can not be interrupted or corrupted by other access to the same memory region -by other eBPF programs or means outside of this specification. +by other BPF programs or means outside of this specification. -All atomic operations supported by eBPF are encoded as store operations +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 @@ -451,7 +586,7 @@ where Maps ~~~~ -Maps are shared memory regions accessible by eBPF programs on some platforms. +Maps are shared memory regions accessible by BPF programs on some platforms. A map can have various semantics as defined in a separate document, and may or may not have a single contiguous memory region, but the 'map_val(map)' is currently only defined for maps that do have a single contiguous memory region. @@ -473,6 +608,6 @@ identified by the given id. Legacy BPF Packet access instructions ------------------------------------- -eBPF previously introduced special instructions for access to packet data that were +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. diff --git a/Documentation/core-api/cachetlb.rst b/Documentation/core-api/cachetlb.rst index 5c0552e78c58..889fc84ccd1b 100644 --- a/Documentation/core-api/cachetlb.rst +++ b/Documentation/core-api/cachetlb.rst @@ -88,13 +88,17 @@ changes occur: This is used primarily during fault processing. -5) ``void update_mmu_cache(struct vm_area_struct *vma, - unsigned long address, pte_t *ptep)`` +5) ``void update_mmu_cache_range(struct vm_fault *vmf, + struct vm_area_struct *vma, unsigned long address, pte_t *ptep, + unsigned int nr)`` - At the end of every page fault, this routine is invoked to - tell the architecture specific code that a translation - now exists at virtual address "address" for address space - "vma->vm_mm", in the software page tables. + At the end of every page fault, this routine is invoked to tell + the architecture specific code that translations now exists + in the software page tables for address space "vma->vm_mm" + at virtual address "address" for "nr" consecutive pages. + + This routine is also invoked in various other places which pass + a NULL "vmf". A port may use this information in any way it so chooses. For example, it could use this event to pre-load TLB @@ -269,7 +273,7 @@ maps this page at its virtual address. If D-cache aliasing is not an issue, these two routines may simply call memcpy/memset directly and do nothing more. - ``void flush_dcache_page(struct page *page)`` + ``void flush_dcache_folio(struct folio *folio)`` This routines must be called when: @@ -277,7 +281,7 @@ maps this page at its virtual address. and / or in high memory b) the kernel is about to read from a page cache page and user space shared/writable mappings of this page potentially exist. Note - that {get,pin}_user_pages{_fast} already call flush_dcache_page + that {get,pin}_user_pages{_fast} already call flush_dcache_folio on any page found in the user address space and thus driver code rarely needs to take this into account. @@ -291,7 +295,7 @@ maps this page at its virtual address. The phrase "kernel writes to a page cache page" means, specifically, that the kernel executes store instructions that dirty data in that - page at the page->virtual mapping of that page. It is important to + page at the kernel virtual mapping of that page. It is important to flush here to handle D-cache aliasing, to make sure these kernel stores are visible to user space mappings of that page. @@ -302,21 +306,22 @@ maps this page at its virtual address. If D-cache aliasing is not an issue, this routine may simply be defined as a nop on that architecture. - There is a bit set aside in page->flags (PG_arch_1) as "architecture + There is a bit set aside in folio->flags (PG_arch_1) as "architecture private". The kernel guarantees that, for pagecache pages, it will clear this bit when such a page first enters the pagecache. - This allows these interfaces to be implemented much more efficiently. - It allows one to "defer" (perhaps indefinitely) the actual flush if - there are currently no user processes mapping this page. See sparc64's - flush_dcache_page and update_mmu_cache implementations for an example - of how to go about doing this. + This allows these interfaces to be implemented much more + efficiently. It allows one to "defer" (perhaps indefinitely) the + actual flush if there are currently no user processes mapping this + page. See sparc64's flush_dcache_folio and update_mmu_cache_range + implementations for an example of how to go about doing this. - The idea is, first at flush_dcache_page() time, if page_file_mapping() - returns a mapping, and mapping_mapped on that mapping returns %false, - just mark the architecture private page flag bit. Later, in - update_mmu_cache(), a check is made of this flag bit, and if set the - flush is done and the flag bit is cleared. + The idea is, first at flush_dcache_folio() time, if + folio_flush_mapping() returns a mapping, and mapping_mapped() on that + mapping returns %false, just mark the architecture private page + flag bit. Later, in update_mmu_cache_range(), a check is made + of this flag bit, and if set the flush is done and the flag bit + is cleared. .. important:: @@ -326,12 +331,6 @@ maps this page at its virtual address. dirty. Again, see sparc64 for examples of how to deal with this. - ``void flush_dcache_folio(struct folio *folio)`` - This function is called under the same circumstances as - flush_dcache_page(). It allows the architecture to - optimise for flushing the entire folio of pages instead - of flushing one page at a time. - ``void copy_to_user_page(struct vm_area_struct *vma, struct page *page, unsigned long user_vaddr, void *dst, void *src, int len)`` ``void copy_from_user_page(struct vm_area_struct *vma, struct page *page, @@ -352,7 +351,7 @@ maps this page at its virtual address. When the kernel needs to access the contents of an anonymous page, it calls this function (currently only - get_user_pages()). Note: flush_dcache_page() deliberately + get_user_pages()). Note: flush_dcache_folio() deliberately doesn't work for an anonymous page. The default implementation is a nop (and should remain so for all coherent architectures). For incoherent architectures, it should flush @@ -369,7 +368,7 @@ maps this page at its virtual address. ``void flush_icache_page(struct vm_area_struct *vma, struct page *page)`` All the functionality of flush_icache_page can be implemented in - flush_dcache_page and update_mmu_cache. In the future, the hope + flush_dcache_folio and update_mmu_cache_range. In the future, the hope is to remove this interface completely. The final category of APIs is for I/O to deliberately aliased address diff --git a/Documentation/core-api/cpu_hotplug.rst b/Documentation/core-api/cpu_hotplug.rst index e6f5bc39cf5c..dcb0e379e5e8 100644 --- a/Documentation/core-api/cpu_hotplug.rst +++ b/Documentation/core-api/cpu_hotplug.rst @@ -40,12 +40,6 @@ Command Line Switches supplied here is lower than the number of physically available CPUs, then those CPUs can not be brought online later. -``additional_cpus=n`` - Use this to limit hotpluggable CPUs. This option sets - ``cpu_possible_mask = cpu_present_mask + additional_cpus`` - - This option is limited to the IA64 architecture. - ``possible_cpus=n`` This option sets ``possible_cpus`` bits in ``cpu_possible_mask``. @@ -395,8 +389,8 @@ multi-instance state the following function is available: * cpuhp_setup_state_multi(state, name, startup, teardown) The @state argument is either a statically allocated state or one of the -constants for dynamically allocated states - CPUHP_PREPARE_DYN, -CPUHP_ONLINE_DYN - depending on the state section (PREPARE, ONLINE) for +constants for dynamically allocated states - CPUHP_BP_PREPARE_DYN, +CPUHP_AP_ONLINE_DYN - depending on the state section (PREPARE, ONLINE) for which a dynamic state should be allocated. The @name argument is used for sysfs output and for instrumentation. The @@ -588,7 +582,7 @@ notifications on online and offline operations:: Setup and teardown a dynamically allocated state in the ONLINE section for notifications on offline operations:: - state = cpuhp_setup_state(CPUHP_ONLINE_DYN, "subsys:offline", NULL, subsys_cpu_offline); + state = cpuhp_setup_state(CPUHP_AP_ONLINE_DYN, "subsys:offline", NULL, subsys_cpu_offline); if (state < 0) return state; .... @@ -597,7 +591,7 @@ for notifications on offline operations:: Setup and teardown a dynamically allocated state in the ONLINE section for notifications on online operations without invoking the callbacks:: - state = cpuhp_setup_state_nocalls(CPUHP_ONLINE_DYN, "subsys:online", subsys_cpu_online, NULL); + state = cpuhp_setup_state_nocalls(CPUHP_AP_ONLINE_DYN, "subsys:online", subsys_cpu_online, NULL); if (state < 0) return state; .... @@ -606,7 +600,7 @@ for notifications on online operations without invoking the callbacks:: Setup, use and teardown a dynamically allocated multi-instance state in the ONLINE section for notifications on online and offline operation:: - state = cpuhp_setup_state_multi(CPUHP_ONLINE_DYN, "subsys:online", subsys_cpu_online, subsys_cpu_offline); + state = cpuhp_setup_state_multi(CPUHP_AP_ONLINE_DYN, "subsys:online", subsys_cpu_online, subsys_cpu_offline); if (state < 0) return state; .... @@ -741,6 +735,24 @@ will receive all events. A script like:: can process the event further. +When changes to the CPUs in the system occur, the sysfs file +/sys/devices/system/cpu/crash_hotplug contains '1' if the kernel +updates the kdump capture kernel list of CPUs itself (via elfcorehdr), +or '0' if userspace must update the kdump capture kernel list of CPUs. + +The availability depends on the CONFIG_HOTPLUG_CPU kernel configuration +option. + +To skip userspace processing of CPU hot un/plug events for kdump +(i.e. the unload-then-reload to obtain a current list of CPUs), this sysfs +file can be used in a udev rule as follows: + + SUBSYSTEM=="cpu", ATTRS{crash_hotplug}=="1", GOTO="kdump_reload_end" + +For a CPU hot un/plug event, if the architecture supports kernel updates +of the elfcorehdr (which contains the list of CPUs), then the rule skips +the unload-then-reload of the kdump capture kernel. + Kernel Inline Documentations Reference ====================================== diff --git a/Documentation/core-api/debugging-via-ohci1394.rst b/Documentation/core-api/debugging-via-ohci1394.rst index 981ad4f89fd3..cb3d3228dfc8 100644 --- a/Documentation/core-api/debugging-via-ohci1394.rst +++ b/Documentation/core-api/debugging-via-ohci1394.rst @@ -23,9 +23,9 @@ Retrieving a full system memory dump is also possible over the FireWire, using data transfer rates in the order of 10MB/s or more. With most FireWire controllers, memory access is limited to the low 4 GB -of physical address space. This can be a problem on IA64 machines where -memory is located mostly above that limit, but it is rarely a problem on -more common hardware such as x86, x86-64 and PowerPC. +of physical address space. This can be a problem on machines where memory is +located mostly above that limit, but it is rarely a problem on more common +hardware such as x86, x86-64 and PowerPC. At least LSI FW643e and FW643e2 controllers are known to support access to physical addresses above 4 GB, but this feature is currently not enabled by diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst index f959c9b53f61..4a460639ab1c 100644 --- a/Documentation/core-api/genericirq.rst +++ b/Documentation/core-api/genericirq.rst @@ -264,7 +264,7 @@ The following control flow is implemented (simplified excerpt):: desc->irq_data.chip->irq_unmask(); desc->status &= ~pending; handle_irq_event(desc->action); - } while (status & pending); + } while (desc->status & pending); desc->status &= ~running; diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index f2bcc5a7ea43..ae92a2571388 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -162,8 +162,10 @@ Base 2 log and power Functions .. kernel-doc:: include/linux/log2.h :internal: -Integer power Functions ------------------------ +Integer log and power Functions +------------------------------- + +.. kernel-doc:: include/linux/int_log.h .. kernel-doc:: lib/math/int_pow.c :export: diff --git a/Documentation/core-api/maple_tree.rst b/Documentation/core-api/maple_tree.rst index 45defcf15da7..96f3d5f076b5 100644 --- a/Documentation/core-api/maple_tree.rst +++ b/Documentation/core-api/maple_tree.rst @@ -175,7 +175,7 @@ will return the previous entry which occurs before the entry at index. mas_find() will find the first entry which exists at or above index on the first call, and the next entry from every subsequent calls. -mas_find_rev() will find the fist entry which exists at or below the last on +mas_find_rev() will find the first entry which exists at or below the last on the first call, and the previous entry from every subsequent calls. If the user needs to yield the lock during an operation, then the maple state diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst index f5dde5bceaea..2d091c873d1e 100644 --- a/Documentation/core-api/mm-api.rst +++ b/Documentation/core-api/mm-api.rst @@ -115,3 +115,28 @@ More Memory Management Functions .. kernel-doc:: include/linux/mmzone.h .. kernel-doc:: mm/util.c :functions: folio_mapping + +.. kernel-doc:: mm/rmap.c +.. kernel-doc:: mm/migrate.c +.. kernel-doc:: mm/mmap.c +.. kernel-doc:: mm/kmemleak.c +.. #kernel-doc:: mm/hmm.c (build warnings) +.. kernel-doc:: mm/memremap.c +.. kernel-doc:: mm/hugetlb.c +.. kernel-doc:: mm/swap.c +.. kernel-doc:: mm/zpool.c +.. kernel-doc:: mm/memcontrol.c +.. #kernel-doc:: mm/memory-tiers.c (build warnings) +.. kernel-doc:: mm/shmem.c +.. kernel-doc:: mm/migrate_device.c +.. #kernel-doc:: mm/nommu.c (duplicates kernel-doc from other files) +.. kernel-doc:: mm/mapping_dirty_helpers.c +.. #kernel-doc:: mm/memory-failure.c (build warnings) +.. kernel-doc:: mm/percpu.c +.. kernel-doc:: mm/maccess.c +.. kernel-doc:: mm/vmscan.c +.. kernel-doc:: mm/memory_hotplug.c +.. kernel-doc:: mm/mmu_notifier.c +.. kernel-doc:: mm/balloon_compaction.c +.. kernel-doc:: mm/huge_memory.c +.. kernel-doc:: mm/io-mapping.c diff --git a/Documentation/core-api/netlink.rst b/Documentation/core-api/netlink.rst index e4a938a05cc9..9f692b02bfe6 100644 --- a/Documentation/core-api/netlink.rst +++ b/Documentation/core-api/netlink.rst @@ -67,10 +67,11 @@ Globals kernel-policy ~~~~~~~~~~~~~ -Defines if the kernel validation policy is per operation (``per-op``) -or for the entire family (``global``). New families should use ``per-op`` -(default) to be able to narrow down the attributes accepted by a specific -command. +Defines whether the kernel validation policy is ``global`` i.e. the same for all +operations of the family, defined for each operation individually - ``per-op``, +or separately for each operation and operation type (do vs dump) - ``split``. +New families should use ``per-op`` (default) to be able to narrow down the +attributes accepted by a specific command. checks ------ diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst index dfe7e75a71de..4451ef501936 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -15,9 +15,10 @@ Integer types If variable is of Type, use printk format specifier: ------------------------------------------------------------ - char %d or %x + signed char %d or %hhx unsigned char %u or %x - short int %d or %x + char %u or %x + short int %d or %hx unsigned short int %u or %x int %d or %x unsigned int %u or %x @@ -27,9 +28,9 @@ Integer types unsigned long long %llu or %llx size_t %zu or %zx ssize_t %zd or %zx - s8 %d or %x + s8 %d or %hhx u8 %u or %x - s16 %d or %x + s16 %d or %hx u16 %u or %x s32 %d or %x u32 %u or %x diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst index a4c9b9d1905f..0046af06531a 100644 --- a/Documentation/core-api/workqueue.rst +++ b/Documentation/core-api/workqueue.rst @@ -1,6 +1,6 @@ -==================================== -Concurrency Managed Workqueue (cmwq) -==================================== +========= +Workqueue +========= :Date: September, 2010 :Author: Tejun Heo <tj@kernel.org> @@ -25,8 +25,8 @@ there is no work item left on the workqueue the worker becomes idle. When a new work item gets queued, the worker begins executing again. -Why cmwq? -========= +Why Concurrency Managed Workqueue? +================================== In the original wq implementation, a multi threaded (MT) wq had one worker thread per CPU and a single threaded (ST) wq had one worker @@ -220,17 +220,16 @@ resources, scheduled and executed. ``max_active`` -------------- -``@max_active`` determines the maximum number of execution contexts -per CPU which can be assigned to the work items of a wq. For example, -with ``@max_active`` of 16, at most 16 work items of the wq can be -executing at the same time per CPU. +``@max_active`` determines the maximum number of execution contexts per +CPU which can be assigned to the work items of a wq. For example, with +``@max_active`` of 16, at most 16 work items of the wq can be executing +at the same time per CPU. This is always a per-CPU attribute, even for +unbound workqueues. -Currently, for a bound wq, the maximum limit for ``@max_active`` is -512 and the default value used when 0 is specified is 256. For an -unbound wq, the limit is higher of 512 and 4 * -``num_possible_cpus()``. These values are chosen sufficiently high -such that they are not the limiting factor while providing protection -in runaway cases. +The maximum limit for ``@max_active`` is 512 and the default value used +when 0 is specified is 256. These values are chosen sufficiently high +such that they are not the limiting factor while providing protection in +runaway cases. The number of active work items of a wq is usually regulated by the users of the wq, more specifically, by how many work items the users @@ -245,7 +244,7 @@ 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_queue()`` should +ST behavior within a given NUMA node. Instead ``alloc_ordered_workqueue()`` should be used to achieve system-wide ST behavior. @@ -348,27 +347,346 @@ Guidelines level of locality in wq operations and work item execution. +Affinity Scopes +=============== + +An unbound workqueue groups CPUs according to its affinity scope to improve +cache locality. For example, if a workqueue is using the default affinity +scope of "cache", it will group CPUs according to last level cache +boundaries. A work item queued on the workqueue will be assigned to a worker +on one of the CPUs which share the last level cache with the issuing CPU. +Once started, the worker may or may not be allowed to move outside the scope +depending on the ``affinity_strict`` setting of the scope. + +Workqueue currently supports the following affinity scopes. + +``default`` + Use the scope in module parameter ``workqueue.default_affinity_scope`` + which is always set to one of the scopes below. + +``cpu`` + CPUs are not grouped. A work item issued on one CPU is processed by a + worker on the same CPU. This makes unbound workqueues behave as per-cpu + workqueues without concurrency management. + +``smt`` + CPUs are grouped according to SMT boundaries. This usually means that the + logical threads of each physical CPU core are grouped together. + +``cache`` + CPUs are grouped according to cache boundaries. Which specific cache + boundary is used is determined by the arch code. L3 is used in a lot of + cases. This is the default affinity scope. + +``numa`` + CPUs are grouped according to NUMA bounaries. + +``system`` + All CPUs are put in the same group. Workqueue makes no effort to process a + work item on a CPU close to the issuing CPU. + +The default affinity scope can be changed with the module parameter +``workqueue.default_affinity_scope`` and a specific workqueue's affinity +scope can be changed using ``apply_workqueue_attrs()``. + +If ``WQ_SYSFS`` is set, the workqueue will have the following affinity scope +related interface files under its ``/sys/devices/virtual/workqueue/WQ_NAME/`` +directory. + +``affinity_scope`` + Read to see the current affinity scope. Write to change. + + When default is the current scope, reading this file will also show the + current effective scope in parentheses, for example, ``default (cache)``. + +``affinity_strict`` + 0 by default indicating that affinity scopes are not strict. When a work + item starts execution, workqueue makes a best-effort attempt to ensure + that the worker is inside its affinity scope, which is called + repatriation. Once started, the scheduler is free to move the worker + anywhere in the system as it sees fit. This enables benefiting from scope + locality while still being able to utilize other CPUs if necessary and + available. + + If set to 1, all workers of the scope are guaranteed always to be in the + scope. This may be useful when crossing affinity scopes has other + implications, for example, in terms of power consumption or workload + isolation. Strict NUMA scope can also be used to match the workqueue + behavior of older kernels. + + +Affinity Scopes and Performance +=============================== + +It'd be ideal if an unbound workqueue's behavior is optimal for vast +majority of use cases without further tuning. Unfortunately, in the current +kernel, there exists a pronounced trade-off between locality and utilization +necessitating explicit configurations when workqueues are heavily used. + +Higher locality leads to higher efficiency where more work is performed for +the same number of consumed CPU cycles. However, higher locality may also +cause lower overall system utilization if the work items are not spread +enough across the affinity scopes by the issuers. The following performance +testing with dm-crypt clearly illustrates this trade-off. + +The tests are run on a CPU with 12-cores/24-threads split across four L3 +caches (AMD Ryzen 9 3900x). CPU clock boost is turned off for consistency. +``/dev/dm-0`` is a dm-crypt device created on NVME SSD (Samsung 990 PRO) and +opened with ``cryptsetup`` with default settings. + + +Scenario 1: Enough issuers and work spread across the machine +------------------------------------------------------------- + +The command used: :: + + $ fio --filename=/dev/dm-0 --direct=1 --rw=randrw --bs=32k --ioengine=libaio \ + --iodepth=64 --runtime=60 --numjobs=24 --time_based --group_reporting \ + --name=iops-test-job --verify=sha512 + +There are 24 issuers, each issuing 64 IOs concurrently. ``--verify=sha512`` +makes ``fio`` generate and read back the content each time which makes +execution locality matter between the issuer and ``kcryptd``. The followings +are the read bandwidths and CPU utilizations depending on different affinity +scope settings on ``kcryptd`` measured over five runs. Bandwidths are in +MiBps, and CPU util in percents. + +.. list-table:: + :widths: 16 20 20 + :header-rows: 1 + + * - Affinity + - Bandwidth (MiBps) + - CPU util (%) + + * - system + - 1159.40 ±1.34 + - 99.31 ±0.02 + + * - cache + - 1166.40 ±0.89 + - 99.34 ±0.01 + + * - cache (strict) + - 1166.00 ±0.71 + - 99.35 ±0.01 + +With enough issuers spread across the system, there is no downside to +"cache", strict or otherwise. All three configurations saturate the whole +machine but the cache-affine ones outperform by 0.6% thanks to improved +locality. + + +Scenario 2: Fewer issuers, enough work for saturation +----------------------------------------------------- + +The command used: :: + + $ fio --filename=/dev/dm-0 --direct=1 --rw=randrw --bs=32k \ + --ioengine=libaio --iodepth=64 --runtime=60 --numjobs=8 \ + --time_based --group_reporting --name=iops-test-job --verify=sha512 + +The only difference from the previous scenario is ``--numjobs=8``. There are +a third of the issuers but is still enough total work to saturate the +system. + +.. list-table:: + :widths: 16 20 20 + :header-rows: 1 + + * - Affinity + - Bandwidth (MiBps) + - CPU util (%) + + * - system + - 1155.40 ±0.89 + - 97.41 ±0.05 + + * - cache + - 1154.40 ±1.14 + - 96.15 ±0.09 + + * - cache (strict) + - 1112.00 ±4.64 + - 93.26 ±0.35 + +This is more than enough work to saturate the system. Both "system" and +"cache" are nearly saturating the machine but not fully. "cache" is using +less CPU but the better efficiency puts it at the same bandwidth as +"system". + +Eight issuers moving around over four L3 cache scope still allow "cache +(strict)" to mostly saturate the machine but the loss of work conservation +is now starting to hurt with 3.7% bandwidth loss. + + +Scenario 3: Even fewer issuers, not enough work to saturate +----------------------------------------------------------- + +The command used: :: + + $ fio --filename=/dev/dm-0 --direct=1 --rw=randrw --bs=32k \ + --ioengine=libaio --iodepth=64 --runtime=60 --numjobs=4 \ + --time_based --group_reporting --name=iops-test-job --verify=sha512 + +Again, the only difference is ``--numjobs=4``. With the number of issuers +reduced to four, there now isn't enough work to saturate the whole system +and the bandwidth becomes dependent on completion latencies. + +.. list-table:: + :widths: 16 20 20 + :header-rows: 1 + + * - Affinity + - Bandwidth (MiBps) + - CPU util (%) + + * - system + - 993.60 ±1.82 + - 75.49 ±0.06 + + * - cache + - 973.40 ±1.52 + - 74.90 ±0.07 + + * - cache (strict) + - 828.20 ±4.49 + - 66.84 ±0.29 + +Now, the tradeoff between locality and utilization is clearer. "cache" shows +2% bandwidth loss compared to "system" and "cache (struct)" whopping 20%. + + +Conclusion and Recommendations +------------------------------ + +In the above experiments, the efficiency advantage of the "cache" affinity +scope over "system" is, while consistent and noticeable, small. However, the +impact is dependent on the distances between the scopes and may be more +pronounced in processors with more complex topologies. + +While the loss of work-conservation in certain scenarios hurts, it is a lot +better than "cache (strict)" and maximizing workqueue utilization is +unlikely to be the common case anyway. As such, "cache" is the default +affinity scope for unbound pools. + +* As there is no one option which is great for most cases, workqueue usages + that may consume a significant amount of CPU are recommended to configure + the workqueues using ``apply_workqueue_attrs()`` and/or enable + ``WQ_SYSFS``. + +* An unbound workqueue with strict "cpu" affinity scope behaves the same as + ``WQ_CPU_INTENSIVE`` per-cpu workqueue. There is no real advanage to the + latter and an unbound workqueue provides a lot more flexibility. + +* Affinity scopes are introduced in Linux v6.5. To emulate the previous + behavior, use strict "numa" affinity scope. + +* The loss of work-conservation in non-strict affinity scopes is likely + originating from the scheduler. There is no theoretical reason why the + kernel wouldn't be able to do the right thing and maintain + work-conservation in most cases. As such, it is possible that future + scheduler improvements may make most of these tunables unnecessary. + + +Examining Configuration +======================= + +Use tools/workqueue/wq_dump.py to examine unbound CPU affinity +configuration, worker pools and how workqueues map to the pools: :: + + $ tools/workqueue/wq_dump.py + Affinity Scopes + =============== + wq_unbound_cpumask=0000000f + + CPU + nr_pods 4 + pod_cpus [0]=00000001 [1]=00000002 [2]=00000004 [3]=00000008 + pod_node [0]=0 [1]=0 [2]=1 [3]=1 + cpu_pod [0]=0 [1]=1 [2]=2 [3]=3 + + SMT + nr_pods 4 + pod_cpus [0]=00000001 [1]=00000002 [2]=00000004 [3]=00000008 + pod_node [0]=0 [1]=0 [2]=1 [3]=1 + cpu_pod [0]=0 [1]=1 [2]=2 [3]=3 + + CACHE (default) + nr_pods 2 + pod_cpus [0]=00000003 [1]=0000000c + pod_node [0]=0 [1]=1 + cpu_pod [0]=0 [1]=0 [2]=1 [3]=1 + + NUMA + nr_pods 2 + pod_cpus [0]=00000003 [1]=0000000c + pod_node [0]=0 [1]=1 + cpu_pod [0]=0 [1]=0 [2]=1 [3]=1 + + SYSTEM + nr_pods 1 + pod_cpus [0]=0000000f + pod_node [0]=-1 + cpu_pod [0]=0 [1]=0 [2]=0 [3]=0 + + Worker Pools + ============ + pool[00] ref= 1 nice= 0 idle/workers= 4/ 4 cpu= 0 + pool[01] ref= 1 nice=-20 idle/workers= 2/ 2 cpu= 0 + pool[02] ref= 1 nice= 0 idle/workers= 4/ 4 cpu= 1 + pool[03] ref= 1 nice=-20 idle/workers= 2/ 2 cpu= 1 + pool[04] ref= 1 nice= 0 idle/workers= 4/ 4 cpu= 2 + pool[05] ref= 1 nice=-20 idle/workers= 2/ 2 cpu= 2 + pool[06] ref= 1 nice= 0 idle/workers= 3/ 3 cpu= 3 + pool[07] ref= 1 nice=-20 idle/workers= 2/ 2 cpu= 3 + pool[08] ref=42 nice= 0 idle/workers= 6/ 6 cpus=0000000f + pool[09] ref=28 nice= 0 idle/workers= 3/ 3 cpus=00000003 + pool[10] ref=28 nice= 0 idle/workers= 17/ 17 cpus=0000000c + pool[11] ref= 1 nice=-20 idle/workers= 1/ 1 cpus=0000000f + pool[12] ref= 2 nice=-20 idle/workers= 1/ 1 cpus=00000003 + pool[13] ref= 2 nice=-20 idle/workers= 1/ 1 cpus=0000000c + + Workqueue CPU -> pool + ===================== + [ workqueue \ CPU 0 1 2 3 dfl] + events percpu 0 2 4 6 + events_highpri percpu 1 3 5 7 + events_long percpu 0 2 4 6 + events_unbound unbound 9 9 10 10 8 + events_freezable percpu 0 2 4 6 + events_power_efficient percpu 0 2 4 6 + events_freezable_power_ percpu 0 2 4 6 + rcu_gp percpu 0 2 4 6 + rcu_par_gp percpu 0 2 4 6 + slub_flushwq percpu 0 2 4 6 + netns ordered 8 8 8 8 8 + ... + +See the command's help message for more info. + + Monitoring ========== Use tools/workqueue/wq_monitor.py to monitor workqueue operations: :: $ tools/workqueue/wq_monitor.py events - total infl CPUtime CPUhog CMwake mayday rescued + total infl CPUtime CPUhog CMW/RPR mayday rescued events 18545 0 6.1 0 5 - - events_highpri 8 0 0.0 0 0 - - events_long 3 0 0.0 0 0 - - - events_unbound 38306 0 0.1 - - - - + events_unbound 38306 0 0.1 - 7 - - events_freezable 0 0 0.0 0 0 - - events_power_efficient 29598 0 0.2 0 0 - - events_freezable_power_ 10 0 0.0 0 0 - - sock_diag_events 0 0 0.0 0 0 - - - total infl CPUtime CPUhog CMwake mayday rescued + total infl CPUtime CPUhog CMW/RPR mayday rescued events 18548 0 6.1 0 5 - - events_highpri 8 0 0.0 0 0 - - events_long 3 0 0.0 0 0 - - - events_unbound 38322 0 0.1 - - - - + events_unbound 38322 0 0.1 - 7 - - events_freezable 0 0 0.0 0 0 - - events_power_efficient 29603 0 0.2 0 0 - - events_freezable_power_ 10 0 0.0 0 0 - - diff --git a/Documentation/crypto/devel-algos.rst b/Documentation/crypto/devel-algos.rst index 3506899ef83e..9b7782f4f6e0 100644 --- a/Documentation/crypto/devel-algos.rst +++ b/Documentation/crypto/devel-algos.rst @@ -235,6 +235,4 @@ Specifics Of Asynchronous HASH Transformation Some of the drivers will want to use the Generic ScatterWalk in case the implementation needs to be fed separate chunks of the scatterlist which -contains the input data. The buffer containing the resulting hash will -always be properly aligned to .cra_alignmask so there is no need to -worry about this. +contains the input data. diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index f4acf9c2e90f..858c77fe7dc4 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -1,5 +1,8 @@ -The Kernel Address Sanitizer (KASAN) -==================================== +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright (C) 2023, Google LLC. + +Kernel Address Sanitizer (KASAN) +================================ Overview -------- @@ -41,8 +44,8 @@ Support Architectures ~~~~~~~~~~~~~ -Generic KASAN is supported on x86_64, arm, arm64, powerpc, riscv, s390, and -xtensa, and the tag-based KASAN modes are supported only on arm64. +Generic KASAN is supported on x86_64, arm, arm64, powerpc, riscv, s390, xtensa, +and loongarch, and the tag-based KASAN modes are supported only on arm64. Compilers ~~~~~~~~~ diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst index 3ae866dcc924..94b6802ab0ab 100644 --- a/Documentation/dev-tools/kcsan.rst +++ b/Documentation/dev-tools/kcsan.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 .. Copyright (C) 2019, Google LLC. -The Kernel Concurrency Sanitizer (KCSAN) -======================================== +Kernel Concurrency Sanitizer (KCSAN) +==================================== The Kernel Concurrency Sanitizer (KCSAN) is a dynamic race detector, which relies on compile-time instrumentation, and uses a watchpoint-based sampling diff --git a/Documentation/dev-tools/kmsan.rst b/Documentation/dev-tools/kmsan.rst index 55fa82212eb2..323eedad53cd 100644 --- a/Documentation/dev-tools/kmsan.rst +++ b/Documentation/dev-tools/kmsan.rst @@ -1,9 +1,9 @@ .. SPDX-License-Identifier: GPL-2.0 .. Copyright (C) 2022, Google LLC. -=================================== -The Kernel Memory Sanitizer (KMSAN) -=================================== +=============================== +Kernel Memory Sanitizer (KMSAN) +=============================== KMSAN is a dynamic error detector aimed at finding uses of uninitialized values. It is based on compiler instrumentation, and is quite similar to the diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index deede972f254..ab376b316c36 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -112,7 +112,7 @@ You can specify multiple tests to skip:: You can also specify a restricted list of tests to run together with a dedicated skiplist:: - $ make TARGETS="bpf breakpoints size timers" SKIP_TARGETS=bpf kselftest + $ make TARGETS="breakpoints size timers" SKIP_TARGETS=size kselftest See the top-level tools/testing/selftests/Makefile for the list of all possible targets. @@ -165,7 +165,7 @@ To see the list of available tests, the `-l` option can be used:: The `-c` option can be used to run all the tests from a test collection, or the `-t` option for specific single tests. Either can be used multiple times:: - $ ./run_kselftest.sh -c bpf -c seccomp -t timers:posix_timers -t timer:nanosleep + $ ./run_kselftest.sh -c size -c seccomp -t timers:posix_timers -t timer:nanosleep For other features see the script usage output, seen with the `-h` option. @@ -210,7 +210,7 @@ option is supported, such as:: tests by using variables specified in `Running a subset of selftests`_ section:: - $ make -C tools/testing/selftests gen_tar TARGETS="bpf" FORMAT=.xz + $ make -C tools/testing/selftests gen_tar TARGETS="size" FORMAT=.xz .. _tar's auto-compress: https://www.gnu.org/software/tar/manual/html_node/gzip.html#auto_002dcompress diff --git a/Documentation/dev-tools/kunit/run_wrapper.rst b/Documentation/dev-tools/kunit/run_wrapper.rst index dafe8eb28d30..19ddf5e07013 100644 --- a/Documentation/dev-tools/kunit/run_wrapper.rst +++ b/Documentation/dev-tools/kunit/run_wrapper.rst @@ -321,3 +321,15 @@ command line arguments: - ``--json``: If set, stores the test results in a JSON format and prints to `stdout` or saves to a file if a filename is specified. + +- ``--filter``: Specifies filters on test attributes, for example, ``speed!=slow``. + Multiple filters can be used by wrapping input in quotes and separating filters + by commas. Example: ``--filter "speed>slow, module=example"``. + +- ``--filter_action``: If set to ``skip``, filtered tests will be shown as skipped + in the output rather than showing no output. + +- ``--list_tests``: If set, lists all tests that will be run. + +- ``--list_tests_attr``: If set, lists all tests that will be run and all of their + attributes. diff --git a/Documentation/dev-tools/kunit/running_tips.rst b/Documentation/dev-tools/kunit/running_tips.rst index 8e8c493f17d1..766f9cdea0fa 100644 --- a/Documentation/dev-tools/kunit/running_tips.rst +++ b/Documentation/dev-tools/kunit/running_tips.rst @@ -262,3 +262,169 @@ other code executed during boot, e.g. # Reset coverage counters before running the test. $ echo 0 > /sys/kernel/debug/gcov/reset $ modprobe kunit-example-test + + +Test Attributes and Filtering +============================= + +Test suites and cases can be marked with test attributes, such as speed of +test. These attributes will later be printed in test output and can be used to +filter test execution. + +Marking Test Attributes +----------------------- + +Tests are marked with an attribute by including a ``kunit_attributes`` object +in the test definition. + +Test cases can be marked using the ``KUNIT_CASE_ATTR(test_name, attributes)`` +macro to define the test case instead of ``KUNIT_CASE(test_name)``. + +.. code-block:: c + + static const struct kunit_attributes example_attr = { + .speed = KUNIT_VERY_SLOW, + }; + + static struct kunit_case example_test_cases[] = { + KUNIT_CASE_ATTR(example_test, example_attr), + }; + +.. note:: + To mark a test case as slow, you can also use ``KUNIT_CASE_SLOW(test_name)``. + This is a helpful macro as the slow attribute is the most commonly used. + +Test suites can be marked with an attribute by setting the "attr" field in the +suite definition. + +.. code-block:: c + + static const struct kunit_attributes example_attr = { + .speed = KUNIT_VERY_SLOW, + }; + + static struct kunit_suite example_test_suite = { + ..., + .attr = example_attr, + }; + +.. note:: + Not all attributes need to be set in a ``kunit_attributes`` object. Unset + attributes will remain uninitialized and act as though the attribute is set + to 0 or NULL. Thus, if an attribute is set to 0, it is treated as unset. + These unset attributes will not be reported and may act as a default value + for filtering purposes. + +Reporting Attributes +-------------------- + +When a user runs tests, attributes will be present in the raw kernel output (in +KTAP format). Note that attributes will be hidden by default in kunit.py output +for all passing tests but the raw kernel output can be accessed using the +``--raw_output`` flag. This is an example of how test attributes for test cases +will be formatted in kernel output: + +.. code-block:: none + + # example_test.speed: slow + ok 1 example_test + +This is an example of how test attributes for test suites will be formatted in +kernel output: + +.. code-block:: none + + KTAP version 2 + # Subtest: example_suite + # module: kunit_example_test + 1..3 + ... + ok 1 example_suite + +Additionally, users can output a full attribute report of tests with their +attributes, using the command line flag ``--list_tests_attr``: + +.. code-block:: bash + + kunit.py run "example" --list_tests_attr + +.. note:: + This report can be accessed when running KUnit manually by passing in the + module_param ``kunit.action=list_attr``. + +Filtering +--------- + +Users can filter tests using the ``--filter`` command line flag when running +tests. As an example: + +.. code-block:: bash + + kunit.py run --filter speed=slow + + +You can also use the following operations on filters: "<", ">", "<=", ">=", +"!=", and "=". Example: + +.. code-block:: bash + + kunit.py run --filter "speed>slow" + +This example will run all tests with speeds faster than slow. Note that the +characters < and > are often interpreted by the shell, so they may need to be +quoted or escaped, as above. + +Additionally, you can use multiple filters at once. Simply separate filters +using commas. Example: + +.. code-block:: bash + + kunit.py run --filter "speed>slow, module=kunit_example_test" + +.. note:: + You can use this filtering feature when running KUnit manually by passing + the filter as a module param: ``kunit.filter="speed>slow, speed<=normal"``. + +Filtered tests will not run or show up in the test output. You can use the +``--filter_action=skip`` flag to skip filtered tests instead. These tests will be +shown in the test output in the test but will not run. To use this feature when +running KUnit manually, use the module param ``kunit.filter_action=skip``. + +Rules of Filtering Procedure +---------------------------- + +Since both suites and test cases can have attributes, there may be conflicts +between attributes during filtering. The process of filtering follows these +rules: + +- Filtering always operates at a per-test level. + +- If a test has an attribute set, then the test's value is filtered on. + +- Otherwise, the value falls back to the suite's value. + +- If neither are set, the attribute has a global "default" value, which is used. + +List of Current Attributes +-------------------------- + +``speed`` + +This attribute indicates the speed of a test's execution (how slow or fast the +test is). + +This attribute is saved as an enum with the following categories: "normal", +"slow", or "very_slow". The assumed default speed for tests is "normal". This +indicates that the test takes a relatively trivial amount of time (less than +1 second), regardless of the machine it is running on. Any test slower than +this could be marked as "slow" or "very_slow". + +The macro ``KUNIT_CASE_SLOW(test_name)`` can be easily used to set the speed +of a test case to "slow". + +``module`` + +This attribute indicates the name of the module associated with the test. + +This attribute is automatically saved as a string and is printed for each suite. +Tests can also be filtered using this attribute. diff --git a/Documentation/dev-tools/ubsan.rst b/Documentation/dev-tools/ubsan.rst index 1be6618e232d..2de7c63415da 100644 --- a/Documentation/dev-tools/ubsan.rst +++ b/Documentation/dev-tools/ubsan.rst @@ -1,5 +1,7 @@ -The Undefined Behavior Sanitizer - UBSAN -======================================== +.. SPDX-License-Identifier: GPL-2.0 + +Undefined Behavior Sanitizer - UBSAN +==================================== UBSAN is a runtime undefined behaviour checker. diff --git a/Documentation/devicetree/bindings/.yamllint b/Documentation/devicetree/bindings/.yamllint index 4abe9f0a1d46..fea5231e1320 100644 --- a/Documentation/devicetree/bindings/.yamllint +++ b/Documentation/devicetree/bindings/.yamllint @@ -1,6 +1,11 @@ extends: relaxed rules: + quoted-strings: + required: only-when-needed + extra-allowed: + - '[$^,[]' + - '^/$' line-length: # 80 chars should be enough, but don't fail if a line is longer max: 110 diff --git a/Documentation/devicetree/bindings/Makefile b/Documentation/devicetree/bindings/Makefile index 8b395893bd85..3e886194b043 100644 --- a/Documentation/devicetree/bindings/Makefile +++ b/Documentation/devicetree/bindings/Makefile @@ -6,7 +6,7 @@ DT_MK_SCHEMA ?= dt-mk-schema DT_SCHEMA_LINT = $(shell which yamllint || \ echo "warning: python package 'yamllint' not installed, skipping" >&2) -DT_SCHEMA_MIN_VERSION = 2022.3 +DT_SCHEMA_MIN_VERSION = 2023.9 PHONY += check_dtschema_version check_dtschema_version: diff --git a/Documentation/devicetree/bindings/arm/amd,pensando.yaml b/Documentation/devicetree/bindings/arm/amd,pensando.yaml new file mode 100644 index 000000000000..e5c2591834a8 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/amd,pensando.yaml @@ -0,0 +1,26 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/amd,pensando.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: AMD Pensando SoC Platforms + +maintainers: + - Brad Larson <blarson@amd.com> + +properties: + $nodename: + const: "/" + compatible: + oneOf: + + - description: Boards with Pensando Elba SoC + items: + - enum: + - amd,pensando-elba-ortano + - const: amd,pensando-elba + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml index 08d59842655c..caab7ceeda45 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -155,6 +155,7 @@ properties: - enum: - bananapi,bpi-m2s - khadas,vim3 + - libretech,aml-a311d-cc - radxa,zero2 - const: amlogic,a311d - const: amlogic,g12b @@ -196,6 +197,7 @@ properties: - hardkernel,odroid-hc4 - haochuangyi,h96-max - khadas,vim3l + - libretech,aml-s905d3-cc - seirobotics,sei610 - const: amlogic,sm1 @@ -203,6 +205,7 @@ properties: items: - enum: - amlogic,ad401 + - amlogic,ad402 - const: amlogic,a1 - description: Boards with the Amlogic C3 C302X/C308L SoC @@ -218,6 +221,14 @@ properties: - amlogic,aq222 - const: amlogic,s4 + - description: Boards with the Amlogic T7 A311D2 SoC + items: + - enum: + - amlogic,an400 + - khadas,vim4 + - const: amlogic,a311d2 + - const: amlogic,t7 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/arm/arm,coresight-cti.yaml b/Documentation/devicetree/bindings/arm/arm,coresight-cti.yaml index d6c84b6e7fe6..2d5545a2b49c 100644 --- a/Documentation/devicetree/bindings/arm/arm,coresight-cti.yaml +++ b/Documentation/devicetree/bindings/arm/arm,coresight-cti.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 # Copyright 2019 Linaro Ltd. %YAML 1.2 --- @@ -92,11 +92,8 @@ properties: maxItems: 1 cpu: - $ref: /schemas/types.yaml#/definitions/phandle description: - Handle to cpu this device is associated with. This must appear in the - base cti node if compatible string arm,coresight-cti-v8-arch is used, - or may appear in a trig-conns child node when appropriate. + Handle to cpu this CTI is associated with. power-domains: maxItems: 1 @@ -113,12 +110,12 @@ properties: description: defines a phandle reference to an associated CoreSight trace device. When the associated trace device is enabled, then the respective CTI - will be enabled. Use in a trig-conns node, or in CTI base node when - compatible string arm,coresight-cti-v8-arch used. If the associated - device has not been registered then the node name will be stored as - the connection name for later resolution. If the associated device is - not a CoreSight device or not registered then the node name will remain - the connection name and automatic enabling will not occur. + will be enabled. Use in CTI base node when compatible string + arm,coresight-cti-v8-arch used. If the associated device has not been + registered then the node name will be stored as the connection name for + later resolution. If the associated device is not a CoreSight device or + not registered then the node name will remain the connection name and + automatic enabling will not occur. # size cells and address cells required if trig-conns node present. "#size-cells": @@ -130,6 +127,8 @@ properties: patternProperties: '^trig-conns@([0-9]+)$': type: object + additionalProperties: false + description: A trigger connections child node which describes the trigger signals between this CTI and another hardware device. This device may be a CPU, @@ -141,6 +140,21 @@ patternProperties: reg: maxItems: 1 + cpu: + description: + Handle to cpu this trigger connection is associated with. + + arm,cs-dev-assoc: + $ref: /schemas/types.yaml#/definitions/phandle + description: + defines a phandle reference to an associated CoreSight trace device. + When the associated trace device is enabled, then the respective CTI + will be enabled. If the associated device has not been registered + then the node name will be stored as the connection name for later + resolution. If the associated device is not a CoreSight device or + not registered then the node name will remain the connection name + and automatic enabling will not occur. + arm,trig-in-sigs: $ref: /schemas/types.yaml#/definitions/uint32-array minItems: 1 diff --git a/Documentation/devicetree/bindings/arm/arm,coresight-dummy-sink.yaml b/Documentation/devicetree/bindings/arm/arm,coresight-dummy-sink.yaml index cb78cfa56702..c960c8e0a9a5 100644 --- a/Documentation/devicetree/bindings/arm/arm,coresight-dummy-sink.yaml +++ b/Documentation/devicetree/bindings/arm/arm,coresight-dummy-sink.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/arm/arm,coresight-dummy-sink.yaml# diff --git a/Documentation/devicetree/bindings/arm/arm,coresight-dummy-source.yaml b/Documentation/devicetree/bindings/arm/arm,coresight-dummy-source.yaml index 5fedaed49a1f..6745b4cc8f1c 100644 --- a/Documentation/devicetree/bindings/arm/arm,coresight-dummy-source.yaml +++ b/Documentation/devicetree/bindings/arm/arm,coresight-dummy-source.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/arm/arm,coresight-dummy-source.yaml# diff --git a/Documentation/devicetree/bindings/arm/arm,embedded-trace-extension.yaml b/Documentation/devicetree/bindings/arm/arm,embedded-trace-extension.yaml index 108460627d9a..f725e6940993 100644 --- a/Documentation/devicetree/bindings/arm/arm,embedded-trace-extension.yaml +++ b/Documentation/devicetree/bindings/arm/arm,embedded-trace-extension.yaml @@ -1,9 +1,9 @@ -# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause # Copyright 2021, Arm Ltd %YAML 1.2 --- -$id: "http://devicetree.org/schemas/arm/arm,embedded-trace-extension.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/arm/arm,embedded-trace-extension.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: ARM Embedded Trace Extensions diff --git a/Documentation/devicetree/bindings/arm/arm,integrator.yaml b/Documentation/devicetree/bindings/arm/arm,integrator.yaml index 98ff5698ae1f..1bdbd1b7ee38 100644 --- a/Documentation/devicetree/bindings/arm/arm,integrator.yaml +++ b/Documentation/devicetree/bindings/arm/arm,integrator.yaml @@ -40,45 +40,6 @@ properties: items: - const: arm,integrator-sp - core-module@10000000: - type: object - description: the root node in the Integrator platforms must contain - a core module child node. They are always at physical address - 0x10000000 in all the Integrator variants. - properties: - compatible: - items: - - const: arm,core-module-integrator - - const: syscon - - const: simple-mfd - reg: - maxItems: 1 - - required: - - compatible - - reg - -patternProperties: - "^syscon@[0-9a-f]+$": - description: All Integrator boards must provide a system controller as a - node in the root of the device tree. - type: object - properties: - compatible: - items: - - enum: - - arm,integrator-ap-syscon - - arm,integrator-cp-syscon - - arm,integrator-sp-syscon - - const: syscon - reg: - maxItems: 1 - - required: - - compatible - - reg - - required: - compatible - core-module@10000000 diff --git a/Documentation/devicetree/bindings/arm/arm,realview.yaml b/Documentation/devicetree/bindings/arm/arm,realview.yaml index 8d3ed2e4ed31..d1bdee98f9af 100644 --- a/Documentation/devicetree/bindings/arm/arm,realview.yaml +++ b/Documentation/devicetree/bindings/arm/arm,realview.yaml @@ -75,43 +75,6 @@ properties: type: object description: All RealView boards must provide a syscon system controller node inside the soc node. - properties: - compatible: - oneOf: - - items: - - const: arm,realview-eb11mp-revb-syscon - - const: arm,realview-eb-syscon - - const: syscon - - const: simple-mfd - - items: - - const: arm,realview-eb11mp-revc-syscon - - const: arm,realview-eb-syscon - - const: syscon - - const: simple-mfd - - items: - - const: arm,realview-eb-syscon - - const: syscon - - const: simple-mfd - - items: - - const: arm,realview-pb1176-syscon - - const: syscon - - const: simple-mfd - - items: - - const: arm,realview-pb11mp-syscon - - const: syscon - - const: simple-mfd - - items: - - const: arm,realview-pba8-syscon - - const: syscon - - const: simple-mfd - - items: - - const: arm,realview-pbx-syscon - - const: syscon - - const: simple-mfd - - required: - - compatible - - reg required: - compatible diff --git a/Documentation/devicetree/bindings/arm/arm,trace-buffer-extension.yaml b/Documentation/devicetree/bindings/arm/arm,trace-buffer-extension.yaml index b1322658063a..87128e7b7d28 100644 --- a/Documentation/devicetree/bindings/arm/arm,trace-buffer-extension.yaml +++ b/Documentation/devicetree/bindings/arm/arm,trace-buffer-extension.yaml @@ -1,9 +1,9 @@ -# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause # Copyright 2021, Arm Ltd %YAML 1.2 --- -$id: "http://devicetree.org/schemas/arm/arm,trace-buffer-extension.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/arm/arm,trace-buffer-extension.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: ARM Trace Buffer Extensions @@ -19,7 +19,8 @@ description: | properties: $nodename: - const: "trbe" + const: trbe + compatible: items: - const: arm,trace-buffer-extension diff --git a/Documentation/devicetree/bindings/arm/arm,versatile-sysreg.yaml b/Documentation/devicetree/bindings/arm/arm,versatile-sysreg.yaml index 491eef1e1b10..3b060c36b90c 100644 --- a/Documentation/devicetree/bindings/arm/arm,versatile-sysreg.yaml +++ b/Documentation/devicetree/bindings/arm/arm,versatile-sysreg.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/arm/arm,versatile-sysreg.yaml# diff --git a/Documentation/devicetree/bindings/arm/arm,versatile.yaml b/Documentation/devicetree/bindings/arm/arm,versatile.yaml index 13e52ba92060..7a3caf6af200 100644 --- a/Documentation/devicetree/bindings/arm/arm,versatile.yaml +++ b/Documentation/devicetree/bindings/arm/arm,versatile.yaml @@ -14,6 +14,14 @@ description: |+ with various pluggable interface boards, in essence the Versatile PB version is a superset of the Versatile AB version. + The root node in the Versatile platforms must contain a core module child + node. They are always at physical address 0x10000000 in all the Versatile + variants. + + When fitted with the IB2 Interface Board, the Versatile AB will present an + optional system controller node which controls the extra peripherals on the + interface board. + properties: $nodename: const: '/' @@ -32,38 +40,6 @@ properties: items: - const: arm,versatile-pb - core-module@10000000: - type: object - description: the root node in the Versatile platforms must contain - a core module child node. They are always at physical address - 0x10000000 in all the Versatile variants. - properties: - compatible: - items: - - const: arm,core-module-versatile - - const: syscon - - const: simple-mfd - reg: - maxItems: 1 - - required: - - compatible - - reg - -patternProperties: - "^syscon@[0-9a-f]+$": - type: object - description: When fitted with the IB2 Interface Board, the Versatile - AB will present an optional system controller node which controls the - extra peripherals on the interface board. - properties: - compatible: - contains: - const: arm,versatile-ib2-syscon - required: - - compatible - - reg - required: - compatible - core-module@10000000 diff --git a/Documentation/devicetree/bindings/arm/arm,vexpress-juno.yaml b/Documentation/devicetree/bindings/arm/arm,vexpress-juno.yaml index cdd65881fcdd..8dd6b6446394 100644 --- a/Documentation/devicetree/bindings/arm/arm,vexpress-juno.yaml +++ b/Documentation/devicetree/bindings/arm/arm,vexpress-juno.yaml @@ -143,7 +143,7 @@ patternProperties: "simple-bus". If the compatible is placed in the "motherboard-bus" node, it is stricter and always has two compatibles. type: object - $ref: '/schemas/simple-bus.yaml' + $ref: /schemas/simple-bus.yaml unevaluatedProperties: false properties: diff --git a/Documentation/devicetree/bindings/arm/aspeed/aspeed,sbc.yaml b/Documentation/devicetree/bindings/arm/aspeed/aspeed,sbc.yaml index c72aab706484..b8c5cacb09bd 100644 --- a/Documentation/devicetree/bindings/arm/aspeed/aspeed,sbc.yaml +++ b/Documentation/devicetree/bindings/arm/aspeed/aspeed,sbc.yaml @@ -2,8 +2,8 @@ # Copyright 2021 Joel Stanley, IBM Corp. %YAML 1.2 --- -$id: "http://devicetree.org/schemas/arm/aspeed/aspeed,sbc.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/arm/aspeed/aspeed,sbc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: ASPEED Secure Boot Controller diff --git a/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml b/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml index e0eff4c05879..749ee54a3ff8 100644 --- a/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml +++ b/Documentation/devicetree/bindings/arm/aspeed/aspeed.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/arm/aspeed/aspeed.yaml# @@ -79,9 +79,12 @@ properties: - facebook,elbert-bmc - facebook,fuji-bmc - facebook,greatlakes-bmc + - facebook,minerva-cmc + - facebook,yosemite4-bmc - ibm,everest-bmc - ibm,rainier-bmc - ibm,tacoma-bmc + - inventec,starscream-bmc - inventec,transformer-bmc - jabil,rbp-bmc - qcom,dc-scm-v1-bmc diff --git a/Documentation/devicetree/bindings/arm/atmel-at91.yaml b/Documentation/devicetree/bindings/arm/atmel-at91.yaml index dfb8fd089197..89d75fbb1de4 100644 --- a/Documentation/devicetree/bindings/arm/atmel-at91.yaml +++ b/Documentation/devicetree/bindings/arm/atmel-at91.yaml @@ -79,6 +79,13 @@ properties: - const: atmel,sama5d2 - const: atmel,sama5 + - description: Microchip SAMA5D29 Curiosity + items: + - const: microchip,sama5d29-curiosity + - const: atmel,sama5d29 + - const: atmel,sama5d2 + - const: atmel,sama5 + - items: - const: atmel,sama5d27 - const: atmel,sama5d2 diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml index 5c3ac97e8728..4cc4e6754681 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml @@ -66,6 +66,7 @@ properties: - description: BCM47094 based boards items: - enum: + - asus,rt-ac3100 - asus,rt-ac88u - dlink,dir-885l - dlink,dir-890l diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm53573.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm53573.yaml new file mode 100644 index 000000000000..81b9a4a641c1 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm53573.yaml @@ -0,0 +1,39 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/bcm/brcm,bcm53573.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM53573 SoCs family + +description: + Broadcom BCM53573 / BCM47189 Wi-Fi SoCs derived from Northstar. + +maintainers: + - Rafał Miłecki <rafal@milecki.pl> + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - description: BCM53573 based boards + items: + - enum: + - tenda,ac6-v1 + - tenda,w15e-v1 + - const: brcm,bcm53573 + + - description: BCM47189 based boards + items: + - enum: + - brcm,bcm947189acdbmr + - luxul,xap-810-v1 + - luxul,xap-1440-v1 + - tenda,ac9 + - const: brcm,bcm47189 + - const: brcm,bcm53573 + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/arm/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml index 9e6a45eea4e5..ffd526363fda 100644 --- a/Documentation/devicetree/bindings/arm/cpus.yaml +++ b/Documentation/devicetree/bindings/arm/cpus.yaml @@ -143,8 +143,10 @@ properties: - arm,cortex-a78ae - arm,cortex-a78c - arm,cortex-a510 + - arm,cortex-a520 - arm,cortex-a710 - arm,cortex-a715 + - arm,cortex-a720 - arm,cortex-m0 - arm,cortex-m0+ - arm,cortex-m1 @@ -158,6 +160,7 @@ properties: - arm,cortex-x1c - arm,cortex-x2 - arm,cortex-x3 + - arm,cortex-x4 - arm,neoverse-e1 - arm,neoverse-n1 - arm,neoverse-n2 @@ -187,6 +190,7 @@ properties: - qcom,kryo280 - qcom,kryo360 - qcom,kryo385 + - qcom,kryo465 - qcom,kryo468 - qcom,kryo485 - qcom,kryo560 @@ -305,7 +309,9 @@ properties: power-domains property. For PSCI based platforms, the name corresponding to the index of the PSCI - PM domain provider, must be "psci". + PM domain provider, must be "psci". For SCMI based platforms, the name + corresponding to the index of an SCMI performance domain provider, must be + "perf". qcom,saw: $ref: /schemas/types.yaml#/definitions/phandle diff --git a/Documentation/devicetree/bindings/arm/firmware/tlm,trusted-foundations.yaml b/Documentation/devicetree/bindings/arm/firmware/tlm,trusted-foundations.yaml index 9d1857c0aa07..e3980b659f63 100644 --- a/Documentation/devicetree/bindings/arm/firmware/tlm,trusted-foundations.yaml +++ b/Documentation/devicetree/bindings/arm/firmware/tlm,trusted-foundations.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) %YAML 1.2 --- -$id: "http://devicetree.org/schemas/arm/firmware/tlm,trusted-foundations.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/arm/firmware/tlm,trusted-foundations.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Trusted Foundations diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index 2510eaa8906d..32b195852a75 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -25,8 +25,11 @@ properties: - description: i.MX23 based Boards items: - enum: + - creative,x-fi3 - fsl,imx23-evk + - fsl,stmp378x-devb - olimex,imx23-olinuxino + - sandisk,sansa_fuze_plus - const: fsl,imx23 - description: i.MX25 Product Development Kit @@ -385,6 +388,12 @@ properties: - const: toradex,apalis_imx6q - const: fsl,imx6q + - description: i.MX6Q Variscite VAR-SOM-MX6 Boards + items: + - const: variscite,mx6customboard + - const: variscite,var-som-imx6q + - const: fsl,imx6q + - description: TQ-Systems TQMa6Q SoM (variant A) on MBa6x items: - const: tq,imx6q-mba6x-a @@ -909,6 +918,7 @@ properties: - fsl,imx8mm-evk # i.MX8MM EVK Board - fsl,imx8mm-evkb # i.MX8MM EVKB Board - gateworks,imx8mm-gw7904 + - gateworks,imx8mm-gw7905-0x # i.MX8MM Gateworks Board - gw,imx8mm-gw71xx-0x # i.MX8MM Gateworks Development Kit - gw,imx8mm-gw72xx-0x # i.MX8MM Gateworks Development Kit - gw,imx8mm-gw73xx-0x # i.MX8MM Gateworks Development Kit @@ -974,7 +984,9 @@ properties: - description: PHYTEC phyCORE-i.MX8MM SoM based boards items: - - const: phytec,imx8mm-phyboard-polis-rdk # phyBOARD-Polis RDK + - enum: + - phytec,imx8mm-phyboard-polis-rdk # phyBOARD-Polis RDK + - phytec,imx8mm-phygate-tauri-l # phyGATE-Tauri-L Gateway - const: phytec,imx8mm-phycore-som # phyCORE-i.MX8MM SoM - const: fsl,imx8mm @@ -1031,10 +1043,11 @@ properties: - beacon,imx8mp-beacon-kit # i.MX8MP Beacon Development Kit - dmo,imx8mp-data-modul-edm-sbc # i.MX8MP eDM SBC - fsl,imx8mp-evk # i.MX8MP EVK Board + - gateworks,imx8mp-gw71xx-2x # i.MX8MP Gateworks Board + - gateworks,imx8mp-gw72xx-2x # i.MX8MP Gateworks Board + - gateworks,imx8mp-gw73xx-2x # i.MX8MP Gateworks Board - gateworks,imx8mp-gw74xx # i.MX8MP Gateworks Board - gateworks,imx8mp-gw7905-2x # i.MX8MP Gateworks Board - - polyhex,imx8mp-debix # Polyhex Debix boards - - polyhex,imx8mp-debix-model-a # Polyhex Debix Model A Board - toradex,verdin-imx8mp # Verdin iMX8M Plus Modules - toradex,verdin-imx8mp-nonwifi # Verdin iMX8M Plus Modules without Wi-Fi / BT - toradex,verdin-imx8mp-wifi # Verdin iMX8M Plus Wi-Fi / BT Modules @@ -1068,6 +1081,20 @@ properties: - const: phytec,imx8mp-phycore-som # phyCORE-i.MX8MP SoM - const: fsl,imx8mp + - description: Polyhex DEBIX i.MX8MP based SBCs + items: + - enum: + - polyhex,imx8mp-debix-model-a # Polyhex Debix Model A Board + - const: polyhex,imx8mp-debix # Polyhex i.MX8MP Debix SBCs + - const: fsl,imx8mp + + - description: Polyhex DEBIX i.MX8MP SOM A based boards + items: + - enum: + - polyhex,imx8mp-debix-som-a-bmb-08 # Polyhex Debix SOM A on SOM A I/O board + - const: polyhex,imx8mp-debix-som-a # Polyhex Debix SOM A + - const: fsl,imx8mp + - description: Toradex Boards with Verdin iMX8M Plus Modules items: - enum: @@ -1220,11 +1247,30 @@ properties: - const: fsl,imxrt1170 - description: + TQMa93xxLA and TQMa93xxCA are two series of feature compatible SOM + using NXP i.MX93 SOC in 11x11 mm package. + TQMa93xxLA is designed to be soldered on different carrier boards. + TQMa93xxCA is a compatible variant using board to board connectors. + All SOM and CPU variants use the same device tree hence only one + compatible is needed. Bootloader disables all features not present + in the assembled SOC. + MBa93xxCA mainboard can be used as starterkit for the SOM + soldered on an adapter board or for the connector variant + MBa93xxLA mainboard is a single board computer using the solderable + SOM variant + items: + - enum: + - tq,imx93-tqma9352-mba93xxca # TQ-Systems GmbH i.MX93 TQMa93xxCA/LA SOM on MBa93xxCA + - tq,imx93-tqma9352-mba93xxla # TQ-Systems GmbH i.MX93 TQMa93xxLA SOM on MBa93xxLA SBC + - const: tq,imx93-tqma9352 # TQ-Systems GmbH i.MX93 TQMa93xxCA/LA SOM + - const: fsl,imx93 + + - description: Freescale Vybrid Platform Device Tree Bindings - For the Vybrid SoC familiy all variants with DDR controller are supported, + For the Vybrid SoC family all variants with DDR controller are supported, which is the VF5xx and VF6xx series. Out of historical reasons, in most - places the kernel uses vf610 to refer to the whole familiy. + places the kernel uses vf610 to refer to the whole family. The compatible string "fsl,vf610m4" is used for the secondary Cortex-M4 core support. items: @@ -1289,6 +1335,16 @@ properties: - fsl,ls1021a-twr - const: fsl,ls1021a + - description: + TQ-Systems TQMLS102xA is a series of socketable SOM featuring + LS102x system-on-chip variants. MBLS102xA mainboard can be used as + starterkit. + items: + - enum: + - tq,ls1021a-tqmls1021a-mbls102xa + - const: tq,ls1021a-tqmls1021a + - const: fsl,ls1021a + - description: LS1028A based Boards items: - enum: @@ -1344,6 +1400,13 @@ properties: - fsl,ls1043a-qds - const: fsl,ls1043a + - description: TQ-Systems LS1043A based Boards + items: + - enum: + - tq,ls1043a-tqmls1043a-mbls10xxa + - const: tq,ls1043a-tqmls1043a + - const: fsl,ls1043a + - description: LS1046A based Boards items: - enum: @@ -1352,6 +1415,13 @@ properties: - fsl,ls1046a-rdb - const: fsl,ls1046a + - description: TQ-Systems LS1046A based Boards + items: + - enum: + - tq,ls1046a-tqmls1046a-mbls10xxa + - const: tq,ls1046a-tqmls1046a + - const: fsl,ls1046a + - description: LS1088A based Boards items: - enum: @@ -1359,6 +1429,13 @@ properties: - fsl,ls1088a-rdb - const: fsl,ls1088a + - description: TQ-Systems LS1088A based Boards + items: + - enum: + - tq,ls1088a-tqmls1088a-mbls10xxa + - const: tq,ls1088a-tqmls1088a + - const: fsl,ls1088a + - description: LS2080A based Boards items: - enum: @@ -1384,7 +1461,7 @@ properties: - fsl,lx2162a-qds - const: fsl,lx2160a - - description: SolidRun LX2160A based Boards + - description: SolidRun LX2160A CEX-7 based Boards items: - enum: - solidrun,clearfog-cx @@ -1392,6 +1469,13 @@ properties: - const: solidrun,lx2160a-cex7 - const: fsl,lx2160a + - description: SolidRun LX2162A SoM based Boards + items: + - enum: + - solidrun,lx2162a-clearfog + - const: solidrun,lx2162a-som + - const: fsl,lx2160a + - description: S32G2 based Boards items: - enum: diff --git a/Documentation/devicetree/bindings/arm/hisilicon/controller/cpuctrl.yaml b/Documentation/devicetree/bindings/arm/hisilicon/controller/cpuctrl.yaml index 528dad4cde3c..4fc208d3995e 100644 --- a/Documentation/devicetree/bindings/arm/hisilicon/controller/cpuctrl.yaml +++ b/Documentation/devicetree/bindings/arm/hisilicon/controller/cpuctrl.yaml @@ -29,6 +29,26 @@ properties: ranges: true +patternProperties: + "^clock@[0-9a-f]+$": + type: object + additionalProperties: false + + properties: + compatible: + const: hisilicon,hix5hd2-clock + + reg: + maxItems: 1 + + "#clock-cells": + const: 1 + + required: + - compatible + - reg + - "#clock-cells" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/arm/intel,socfpga.yaml b/Documentation/devicetree/bindings/arm/intel,socfpga.yaml index 4b4dcf551eb6..2ee0c740eb56 100644 --- a/Documentation/devicetree/bindings/arm/intel,socfpga.yaml +++ b/Documentation/devicetree/bindings/arm/intel,socfpga.yaml @@ -21,6 +21,11 @@ properties: - intel,socfpga-agilex-n6000 - intel,socfpga-agilex-socdk - const: intel,socfpga-agilex + - description: Agilex5 boards + items: + - enum: + - intel,socfpga-agilex5-socdk + - const: intel,socfpga-agilex5 additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/intel-ixp4xx.yaml b/Documentation/devicetree/bindings/arm/intel-ixp4xx.yaml index 553dcbc70e35..d60792b1d995 100644 --- a/Documentation/devicetree/bindings/arm/intel-ixp4xx.yaml +++ b/Documentation/devicetree/bindings/arm/intel-ixp4xx.yaml @@ -16,12 +16,28 @@ properties: oneOf: - items: - enum: + - adieng,coyote + - arcom,vulcan + - dlink,dsm-g600-a + - freecom,fsg-3 + - gateway,7001 + - gateworks,gw2348 + - goramo,multilink-router + - intel,ixdp425 + - intel,ixdpg425 + - iom,nas-100d - linksys,nslu2 + - netgear,wg302v1 + - netgear,wg302v2 + - usr,8200 - welltech,epbx100 + - linksys,wrv54g + - gemtek,gtwx5715 - const: intel,ixp42x - items: - enum: - gateworks,gw2358 + - intel,kixrp435 - const: intel,ixp43x additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,k3-sci-common.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,k3-sci-common.yaml index ff378d5cbd32..4a323e8c785d 100644 --- a/Documentation/devicetree/bindings/arm/keystone/ti,k3-sci-common.yaml +++ b/Documentation/devicetree/bindings/arm/keystone/ti,k3-sci-common.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/arm/keystone/ti,k3-sci-common.yaml# diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml index 86b59de7707e..c24ad0968f3e 100644 --- a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml +++ b/Documentation/devicetree/bindings/arm/keystone/ti,sci.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/arm/keystone/ti,sci.yaml# diff --git a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt index d84105c7c935..9d5d70c98058 100644 --- a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt +++ b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt @@ -21,13 +21,13 @@ The Device Tree node representing this System Controller 0 provides a number of clocks: - a set of core clocks - - a set of gatable clocks + - a set of gateable clocks Those clocks can be referenced by other Device Tree nodes using two cells: - The first cell must be 0 or 1. 0 for the core clocks and 1 for the - gatable clocks. - - The second cell identifies the particular core clock or gatable + gateable clocks. + - The second cell identifies the particular core clock or gateable clocks. The following clocks are available: @@ -38,7 +38,7 @@ The following clocks are available: - 0 3 Core - 0 4 NAND core - 0 5 SDIO core - - Gatable clocks + - Gateable clocks - 1 0 Audio - 1 1 Comm Unit - 1 2 NAND diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml index ae12b1cab9fb..a5999b3afc35 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek.yaml @@ -133,11 +133,22 @@ properties: - 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 @@ -250,6 +261,11 @@ properties: - const: mediatek,mt8365 - items: - enum: + - mediatek,mt8395-evk + - const: mediatek,mt8395 + - const: mediatek,mt8195 + - items: + - enum: - mediatek,mt8516-pumpkin - const: mediatek,mt8516 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mipi0a.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mipi0a.txt index 8be5978f388d..1c671943ce4d 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mipi0a.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mipi0a.txt @@ -16,7 +16,7 @@ The available clocks are defined in dt-bindings/clock/mt*-clk.h. The mipi0a controller also uses the common power domain from Documentation/devicetree/bindings/soc/mediatek/scpsys.txt -The available power doamins are defined in dt-bindings/power/mt*-power.h. +The available power domains are defined in dt-bindings/power/mt*-power.h. Example: diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml index 28ded09d72e3..e7720caf31b3 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml @@ -22,6 +22,7 @@ properties: - mediatek,mt7622-wed - mediatek,mt7981-wed - mediatek,mt7986-wed + - mediatek,mt7988-wed - const: syscon reg: diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vcodecsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vcodecsys.txt index c877bcc1a5c5..f090147b7f1e 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vcodecsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vcodecsys.txt @@ -15,7 +15,7 @@ The available clocks are defined in dt-bindings/clock/mt*-clk.h. The vcodecsys controller also uses the common power domain from Documentation/devicetree/bindings/soc/mediatek/scpsys.txt -The available power doamins are defined in dt-bindings/power/mt*-power.h. +The available power domains are defined in dt-bindings/power/mt*-power.h. Example: diff --git a/Documentation/devicetree/bindings/arm/msm/ssbi.txt b/Documentation/devicetree/bindings/arm/msm/ssbi.txt deleted file mode 100644 index 54fd5ced3401..000000000000 --- a/Documentation/devicetree/bindings/arm/msm/ssbi.txt +++ /dev/null @@ -1,18 +0,0 @@ -* Qualcomm SSBI - -Some Qualcomm MSM devices contain a point-to-point serial bus used to -communicate with a limited range of devices (mostly power management -chips). - -These require the following properties: - -- compatible: "qcom,ssbi" - -- qcom,controller-type - indicates the SSBI bus variant the controller should use to talk - with the slave device. This should be one of "ssbi", "ssbi2", or - "pmic-arbiter". The type chosen is determined by the attached - slave. - -The slave device should be the single child node of the ssbi device -with a compatible field. diff --git a/Documentation/devicetree/bindings/arm/mstar/mstar,l3bridge.yaml b/Documentation/devicetree/bindings/arm/mstar/mstar,l3bridge.yaml index 6816bd68f9cf..a8ac4a2d672d 100644 --- a/Documentation/devicetree/bindings/arm/mstar/mstar,l3bridge.yaml +++ b/Documentation/devicetree/bindings/arm/mstar/mstar,l3bridge.yaml @@ -2,8 +2,8 @@ # Copyright 2020 thingy.jp. %YAML 1.2 --- -$id: "http://devicetree.org/schemas/arm/mstar/mstar,l3bridge.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/arm/mstar/mstar,l3bridge.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: MStar/SigmaStar Armv7 SoC l3bridge diff --git a/Documentation/devicetree/bindings/arm/mstar/mstar,smpctrl.yaml b/Documentation/devicetree/bindings/arm/mstar/mstar,smpctrl.yaml index 599c65980f5d..5739848000b1 100644 --- a/Documentation/devicetree/bindings/arm/mstar/mstar,smpctrl.yaml +++ b/Documentation/devicetree/bindings/arm/mstar/mstar,smpctrl.yaml @@ -2,8 +2,8 @@ # Copyright 2020 thingy.jp. %YAML 1.2 --- -$id: "http://devicetree.org/schemas/arm/mstar/mstar,smpctrl.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/arm/mstar/mstar,smpctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: MStar/SigmaStar Armv7 SoC SMP control registers diff --git a/Documentation/devicetree/bindings/arm/omap/ctrl.txt b/Documentation/devicetree/bindings/arm/omap/ctrl.txt index f35b77920786..0ce6665df4a2 100644 --- a/Documentation/devicetree/bindings/arm/omap/ctrl.txt +++ b/Documentation/devicetree/bindings/arm/omap/ctrl.txt @@ -8,7 +8,7 @@ control module driver itself. See [2] for documentation about clock/clockdomain nodes. -[1] Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt +[1] Documentation/devicetree/bindings/pinctrl/pinctrl-single.yaml [2] Documentation/devicetree/bindings/clock/ti/* Required properties: diff --git a/Documentation/devicetree/bindings/arm/omap/omap.txt b/Documentation/devicetree/bindings/arm/omap/omap.txt index fa8b31660cad..c863ec07cbbb 100644 --- a/Documentation/devicetree/bindings/arm/omap/omap.txt +++ b/Documentation/devicetree/bindings/arm/omap/omap.txt @@ -41,14 +41,6 @@ SoC Type (optional): SoC Families: -- OMAP2 generic - defaults to OMAP2420 - compatible = "ti,omap2" -- OMAP3 generic - compatible = "ti,omap3" -- OMAP4 generic - defaults to OMAP4430 - compatible = "ti,omap4" -- OMAP5 generic - defaults to OMAP5430 - compatible = "ti,omap5" - DRA7 generic - defaults to DRA742 compatible = "ti,dra7" - AM33x generic @@ -58,32 +50,6 @@ SoC Families: SoCs: -- OMAP2420 - compatible = "ti,omap2420", "ti,omap2" -- OMAP2430 - compatible = "ti,omap2430", "ti,omap2" - -- OMAP3430 - compatible = "ti,omap3430", "ti,omap3" - legacy: "ti,omap34xx" - please do not use any more -- AM3517 - compatible = "ti,am3517", "ti,omap3" -- OMAP3630 - compatible = "ti,omap3630", "ti,omap3" - legacy: "ti,omap36xx" - please do not use any more -- AM335x - compatible = "ti,am33xx" - -- OMAP4430 - compatible = "ti,omap4430", "ti,omap4" -- OMAP4460 - compatible = "ti,omap4460", "ti,omap4" - -- OMAP5430 - compatible = "ti,omap5430", "ti,omap5" -- OMAP5432 - compatible = "ti,omap5432", "ti,omap5" - - DRA762 compatible = "ti,dra762", "ti,dra7" @@ -116,65 +82,6 @@ SoCs: Boards (incomplete list of examples): -- OMAP3 BeagleBoard : Low cost community board - compatible = "ti,omap3-beagle", "ti,omap3430", "ti,omap3" - -- OMAP3 BeagleBoard A to B4 : Early BeagleBoard revisions A to B4 with a timer quirk - compatible = "ti,omap3-beagle-ab4", "ti,omap3-beagle", "ti,omap3430", "ti,omap3" - -- OMAP3 Tobi with Overo : Commercial expansion board with daughter board - compatible = "gumstix,omap3-overo-tobi", "gumstix,omap3-overo", "ti,omap3430", "ti,omap3" - -- OMAP4 SDP : Software Development Board - compatible = "ti,omap4-sdp", "ti,omap4430", "ti,omap4" - -- OMAP4 PandaBoard : Low cost community board - compatible = "ti,omap4-panda", "ti,omap4430", "ti,omap4" - -- OMAP4 DuoVero with Parlor : Commercial expansion board with daughter board - compatible = "gumstix,omap4-duovero-parlor", "gumstix,omap4-duovero", "ti,omap4430", "ti,omap4"; - -- OMAP4 VAR-STK-OM44 : Commercial dev kit with VAR-OM44CustomBoard and VAR-SOM-OM44 w/WLAN - compatible = "variscite,var-stk-om44", "variscite,var-som-om44", "ti,omap4460", "ti,omap4"; - -- OMAP4 VAR-DVK-OM44 : Commercial dev kit with VAR-OM44CustomBoard, VAR-SOM-OM44 w/WLAN and LCD touchscreen - compatible = "variscite,var-dvk-om44", "variscite,var-som-om44", "ti,omap4460", "ti,omap4"; - -- OMAP3 EVM : Software Development Board for OMAP35x, AM/DM37x - compatible = "ti,omap3-evm", "ti,omap3630", "ti,omap3" - -- AM335X EVM : Software Development Board for AM335x - compatible = "ti,am335x-evm", "ti,am33xx" - -- AM335X Bone : Low cost community board - compatible = "ti,am335x-bone", "ti,am33xx" - -- AM3359 ICEv2 : Low cost Industrial Communication Engine EVM. - compatible = "ti,am3359-icev2", "ti,am33xx" - -- AM335X OrionLXm : Substation Automation Platform - compatible = "novatech,am335x-lxm", "ti,am33xx" - -- AM335X phyBOARD-WEGA: Single Board Computer dev kit - compatible = "phytec,am335x-wega", "phytec,am335x-phycore-som", "ti,am33xx" - -- AM335X CM-T335 : System On Module, built around the Sitara AM3352/4 - compatible = "compulab,cm-t335", "ti,am33xx" - -- AM335X SBC-T335 : single board computer, built around the Sitara AM3352/4 - compatible = "compulab,sbc-t335", "compulab,cm-t335", "ti,am33xx" - -- AM335X phyCORE-AM335x: Development kit - compatible = "phytec,am335x-pcm-953", "phytec,am335x-phycore-som", "ti,am33xx" - -- AM335x phyBOARD-REGOR: Single Board Computer - compatible = "phytec,am335x-regor", "phytec,am335x-phycore-som", "ti,am33xx" - -- AM335X UC-8100-ME-T: Communication-centric industrial computing platform - compatible = "moxa,uc-8100-me-t", "ti,am33xx"; - -- OMAP5 EVM : Evaluation Module - compatible = "ti,omap5-evm", "ti,omap5" - AM437x CM-T43 compatible = "compulab,am437x-cm-t43", "ti,am4372", "ti,am43" @@ -217,9 +124,3 @@ Boards (incomplete list of examples): - DRA718 EVM: Software Development Board for DRA718 compatible = "ti,dra718-evm", "ti,dra718", "ti,dra722", "ti,dra72", "ti,dra7" - -- DM3730 Logic PD Torpedo + Wireless: Commercial System on Module with WiFi and Bluetooth - compatible = "logicpd,dm3730-torpedo-devkit", "ti,omap3630", "ti,omap3" - -- DM3730 Logic PD SOM-LV: Commercial System on Module with WiFi and Bluetooth - compatible = "logicpd,dm3730-som-lv-devkit", "ti,omap3630", "ti,omap3" diff --git a/Documentation/devicetree/bindings/arm/pmu.yaml b/Documentation/devicetree/bindings/arm/pmu.yaml index e14358bf0b9c..99b5e9530707 100644 --- a/Documentation/devicetree/bindings/arm/pmu.yaml +++ b/Documentation/devicetree/bindings/arm/pmu.yaml @@ -49,9 +49,14 @@ properties: - arm,cortex-a77-pmu - arm,cortex-a78-pmu - arm,cortex-a510-pmu + - arm,cortex-a520-pmu - arm,cortex-a710-pmu + - arm,cortex-a715-pmu + - arm,cortex-a720-pmu - arm,cortex-x1-pmu - arm,cortex-x2-pmu + - arm,cortex-x3-pmu + - arm,cortex-x4-pmu - arm,neoverse-e1-pmu - arm,neoverse-n1-pmu - arm,neoverse-n2-pmu diff --git a/Documentation/devicetree/bindings/arm/psci.yaml b/Documentation/devicetree/bindings/arm/psci.yaml index 0c5381e081bd..cbb012e217ab 100644 --- a/Documentation/devicetree/bindings/arm/psci.yaml +++ b/Documentation/devicetree/bindings/arm/psci.yaml @@ -101,6 +101,7 @@ properties: patternProperties: "^power-domain-": $ref: /schemas/power/power-domain.yaml# + unevaluatedProperties: false type: object description: | diff --git a/Documentation/devicetree/bindings/arm/qcom,coresight-tpda.yaml b/Documentation/devicetree/bindings/arm/qcom,coresight-tpda.yaml index 2ec9b5b24d73..ea3c5db6b52d 100644 --- a/Documentation/devicetree/bindings/arm/qcom,coresight-tpda.yaml +++ b/Documentation/devicetree/bindings/arm/qcom,coresight-tpda.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 # Copyright (c) 2023 Qualcomm Innovation Center, Inc. All rights reserved. %YAML 1.2 --- diff --git a/Documentation/devicetree/bindings/arm/qcom,coresight-tpdm.yaml b/Documentation/devicetree/bindings/arm/qcom,coresight-tpdm.yaml index 5c08342664ea..3bad47b7b02b 100644 --- a/Documentation/devicetree/bindings/arm/qcom,coresight-tpdm.yaml +++ b/Documentation/devicetree/bindings/arm/qcom,coresight-tpdm.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 # Copyright (c) 2023 Qualcomm Innovation Center, Inc. All rights reserved. %YAML 1.2 --- diff --git a/Documentation/devicetree/bindings/arm/qcom-soc.yaml b/Documentation/devicetree/bindings/arm/qcom-soc.yaml index e333ec4a9c5f..97621c92a1ab 100644 --- a/Documentation/devicetree/bindings/arm/qcom-soc.yaml +++ b/Documentation/devicetree/bindings/arm/qcom-soc.yaml @@ -31,7 +31,7 @@ properties: compatible: oneOf: # Preferred naming style for compatibles of SoC components: - - pattern: "^qcom,(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+-.*$" + - pattern: "^qcom,(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+(pro)?-.*$" - pattern: "^qcom,(sa|sc)8[0-9]+[a-z][a-z]?-.*$" # Legacy namings - variations of existing patterns/compatibles are OK, diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index 450f616774e0..7f80f48a0954 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -30,6 +30,7 @@ description: | apq8084 apq8096 ipq4018 + ipq5018 ipq5332 ipq6018 ipq8074 @@ -49,6 +50,7 @@ description: | msm8998 qcs404 qcm2290 + qcm6490 qdu1000 qrb2210 qrb4210 @@ -72,11 +74,13 @@ description: | sdx65 sdx75 sm4250 + sm4450 sm6115 sm6115p sm6125 sm6350 sm6375 + sm7125 sm7225 sm8150 sm8250 @@ -104,6 +108,7 @@ description: | hk10-c2 idp liquid + rdp432-c2 mtp qrd rb2 @@ -186,6 +191,8 @@ properties: - items: - enum: + - longcheer,l9100 + - samsung,a7 - sony,kanuti-tulip - square,apq8039-t2 - const: qcom,msm8939 @@ -341,6 +348,11 @@ properties: - items: - enum: + - qcom,ipq5018-rdp432-c2 + - const: qcom,ipq5018 + + - items: + - enum: - qcom,ipq5332-ap-mi01.2 - qcom,ipq5332-ap-mi01.3 - qcom,ipq5332-ap-mi01.6 @@ -382,6 +394,11 @@ properties: - const: qcom,qrb2210 - const: qcom,qcm2290 + - items: + - enum: + - fairphone,fp5 + - const: qcom,qcm6490 + - description: Qualcomm Technologies, Inc. Distributed Unit 1000 platform items: - enum: @@ -470,6 +487,11 @@ properties: - const: google,lazor-rev8 - const: qcom,sc7180 + - description: Acer Chromebook Spin 513 (rev9) + items: + - const: google,lazor-rev9 + - const: qcom,sc7180 + - description: Acer Chromebook Spin 513 (newest rev) items: - const: google,lazor @@ -491,6 +513,11 @@ properties: - const: google,lazor-rev8-sku2 - const: qcom,sc7180 + - description: Acer Chromebook Spin 513 with KB Backlight (rev9) + items: + - const: google,lazor-rev9-sku2 + - const: qcom,sc7180 + - description: Acer Chromebook Spin 513 with KB Backlight (newest rev) items: - const: google,lazor-sku2 @@ -512,9 +539,16 @@ properties: - const: google,lazor-rev8-sku0 - const: qcom,sc7180 + - description: Acer Chromebook Spin 513 with LTE (rev9) + items: + - const: google,lazor-rev9-sku0 + - const: google,lazor-rev9-sku10 + - const: qcom,sc7180 + - description: Acer Chromebook Spin 513 with LTE (newest rev) items: - const: google,lazor-sku0 + - const: google,lazor-sku10 - const: qcom,sc7180 - description: Acer Chromebook 511 (rev4 - rev8) @@ -526,9 +560,16 @@ properties: - const: google,lazor-rev8-sku4 - const: qcom,sc7180 + - description: Acer Chromebook 511 (rev9) + items: + - const: google,lazor-rev9-sku4 + - const: google,lazor-rev9-sku15 + - const: qcom,sc7180 + - description: Acer Chromebook 511 (newest rev) items: - const: google,lazor-sku4 + - const: google,lazor-sku15 - const: qcom,sc7180 - description: Acer Chromebook 511 without Touchscreen (rev4) @@ -545,9 +586,16 @@ properties: - const: google,lazor-rev8-sku6 - const: qcom,sc7180 + - description: Acer Chromebook 511 without Touchscreen (rev9) + items: + - const: google,lazor-rev9-sku6 + - const: google,lazor-rev9-sku18 + - const: qcom,sc7180 + - description: Acer Chromebook 511 without Touchscreen (newest rev) items: - const: google,lazor-sku6 + - const: google,lazor-sku18 - const: qcom,sc7180 - description: Google Mrbland with AUO panel (rev0) @@ -904,6 +952,11 @@ properties: - items: - enum: + - qcom,sm4450-qrd + - const: qcom,sm4450 + + - items: + - enum: - fxtec,pro1x - const: qcom,sm6115 @@ -931,6 +984,11 @@ properties: - items: - enum: + - xiaomi,joyeuse + - const: qcom,sm7125 + + - items: + - enum: - fairphone,fp4 - const: qcom,sm7225 @@ -1072,6 +1130,7 @@ allOf: - qcom,sm6115 - qcom,sm6125 - qcom,sm6350 + - qcom,sm7125 - qcom,sm7225 - qcom,sm8150 - qcom,sm8250 diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml index ecdb72a519cb..5f7c6c4aad8f 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -196,6 +196,11 @@ properties: - const: firefly,rk3566-roc-pc - const: rockchip,rk3566 + - description: Firefly Station P2 + items: + - const: firefly,rk3568-roc-pc + - const: rockchip,rk3568 + - description: FriendlyElec NanoPi R2 series boards items: - enum: @@ -222,6 +227,11 @@ properties: - friendlyarm,nanopi-r5s - const: rockchip,rk3568 + - description: FriendlyElec NanoPC T6 + items: + - const: friendlyarm,nanopc-t6 + - const: rockchip,rk3588 + - description: GeekBuying GeekBox items: - const: geekbuying,geekbox @@ -650,6 +660,11 @@ properties: - pine64,quartz64-b - const: rockchip,rk3566 + - description: Pine64 QuartzPro64 + items: + - const: pine64,quartzpro64 + - const: rockchip,rk3588 + - description: Pine64 SoQuartz SoM items: - enum: @@ -659,6 +674,11 @@ properties: - const: pine64,soquartz - const: rockchip,rk3566 + - description: Powkiddy RGB30 + items: + - const: powkiddy,rgb30 + - const: rockchip,rk3566 + - description: Radxa Compute Module 3(CM3) items: - enum: @@ -694,6 +714,11 @@ properties: - const: radxa,rock-4c-plus - const: rockchip,rk3399 + - description: Radxa ROCK 4SE + items: + - const: radxa,rock-4se + - const: rockchip,rk3399 + - description: Radxa ROCK Pi E items: - const: radxa,rockpi-e @@ -855,6 +880,16 @@ properties: - const: tronsmart,orion-r68-meta - const: rockchip,rk3368 + - description: Turing RK1 + items: + - const: turing,rk1 + - const: rockchip,rk3588 + + - description: Xunlong Orange Pi 5 Plus + items: + - const: xunlong,orangepi-5-plus + - const: rockchip,rk3588 + - description: Xunlong Orange Pi R1 Plus / LTS items: - enum: @@ -862,6 +897,11 @@ properties: - xunlong,orangepi-r1-plus-lts - const: rockchip,rk3328 + - description: Xunlong Orange Pi 5 + items: + - const: xunlong,orangepi-5 + - const: rockchip,rk3588s + - description: Zkmagic A95X Z2 items: - const: zkmagic,a95x-z2 diff --git a/Documentation/devicetree/bindings/arm/sti.yaml b/Documentation/devicetree/bindings/arm/sti.yaml index 3ca054c64377..842def3e3f2b 100644 --- a/Documentation/devicetree/bindings/arm/sti.yaml +++ b/Documentation/devicetree/bindings/arm/sti.yaml @@ -1,4 +1,4 @@ -# SPDX-License-Identifier: GPL-2.0 +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- $id: http://devicetree.org/schemas/arm/sti.yaml# @@ -13,13 +13,20 @@ properties: $nodename: const: '/' compatible: - items: - - enum: - - st,stih415 - - st,stih416 - - st,stih407 - - st,stih410 - - st,stih418 + oneOf: + - items: + - const: st,stih407-b2120 + - const: st,stih407 + - items: + - enum: + - st,stih410-b2120 + - st,stih410-b2260 + - const: st,stih410 + - items: + - enum: + - st,stih418-b2199 + - st,stih418-b2264 + - const: st,stih418 additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/stm32/st,mlahb.yaml b/Documentation/devicetree/bindings/arm/stm32/st,mlahb.yaml index 2297ad3f4774..d2dce238ff5d 100644 --- a/Documentation/devicetree/bindings/arm/stm32/st,mlahb.yaml +++ b/Documentation/devicetree/bindings/arm/stm32/st,mlahb.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) %YAML 1.2 --- -$id: "http://devicetree.org/schemas/arm/stm32/st,mlahb.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/arm/stm32/st,mlahb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: STMicroelectronics STM32 ML-AHB interconnect diff --git a/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml b/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml index b63ff591ef8f..d083d8ad48b7 100644 --- a/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml +++ b/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) %YAML 1.2 --- -$id: "http://devicetree.org/schemas/arm/stm32/st,stm32-syscon.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/arm/stm32/st,stm32-syscon.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: STMicroelectronics STM32 Platforms System Controller diff --git a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml index 4466b455bffa..df087c81c69e 100644 --- a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml +++ b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml @@ -143,7 +143,10 @@ properties: - description: Octavo OSD32MP15x System-in-Package based boards items: - enum: - - lxa,stm32mp157c-mc1 # Linux Automation MC-1 + - lxa,stm32mp157c-mc1 # Linux Automation MC-1 + - lxa,stm32mp157c-tac-gen1 # Linux Automation TAC (Generation 1) + - lxa,stm32mp157c-tac-gen2 # Linux Automation TAC (Generation 2) + - oct,stm32mp157c-osd32-red # Octavo OSD32MP1 RED board - const: oct,stm32mp15xx-osd32 - enum: - st,stm32mp157 diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml index ee8fdd2da869..11c5ce941dd7 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -51,6 +51,11 @@ properties: - const: allwinner,parrot - const: allwinner,sun8i-a33 + - description: Anbernic RG-Nano + items: + - const: anbernic,rg-nano + - const: allwinner,sun8i-v3s + - description: Amarula A64 Relic items: - const: amarula,a64-relic @@ -151,6 +156,17 @@ properties: - const: roofull,beelink-x2 - const: allwinner,sun8i-h3 + - description: BigTreeTech Manta M4/8P + items: + - const: bigtreetech,cb1-manta + - const: bigtreetech,cb1 + - const: allwinner,sun50i-h616 + + - description: BigTreeTech Pi + items: + - const: bigtreetech,pi + - const: allwinner,sun50i-h616 + - description: Chuwi V7 CW0825 items: - const: chuwi,v7-cw0825 @@ -541,13 +557,13 @@ properties: - const: msi,primo81 - const: allwinner,sun6i-a31s - - description: Emlid Neutis N5 Developper Board + - description: Emlid Neutis N5 Developer Board items: - const: emlid,neutis-n5-devboard - const: emlid,neutis-n5 - const: allwinner,sun50i-h5 - - description: Emlid Neutis N5H3 Developper Board + - description: Emlid Neutis N5H3 Developer Board items: - const: emlid,neutis-n5h3-devboard - const: emlid,neutis-n5h3 @@ -997,4 +1013,9 @@ properties: - const: xunlong,orangepi-zero2 - const: allwinner,sun50i-h616 + - description: Xunlong OrangePi Zero 3 + items: + - const: xunlong,orangepi-zero3 + - const: allwinner,sun50i-h618 + additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,nvec.txt b/Documentation/devicetree/bindings/arm/tegra/nvidia,nvec.txt deleted file mode 100644 index 5ae601e7f51f..000000000000 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,nvec.txt +++ /dev/null @@ -1,21 +0,0 @@ -NVIDIA compliant embedded controller - -Required properties: -- compatible : should be "nvidia,nvec". -- reg : the iomem of the i2c slave controller -- interrupts : the interrupt line of the i2c slave controller -- clock-frequency : the frequency of the i2c bus -- gpios : the gpio used for ec request -- slave-addr: the i2c address of the slave controller -- clocks : Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names : Must include the following entries: - Tegra20/Tegra30: - - div-clk - - fast-clk - Tegra114: - - div-clk -- resets : Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names : Must include the following entries: - - i2c diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-ahb.txt b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-ahb.txt deleted file mode 100644 index 9a4295b54539..000000000000 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-ahb.txt +++ /dev/null @@ -1,17 +0,0 @@ -NVIDIA Tegra AHB - -Required properties: -- compatible : For Tegra20, must contain "nvidia,tegra20-ahb". For - Tegra30, must contain "nvidia,tegra30-ahb". Otherwise, must contain - '"nvidia,<chip>-ahb", "nvidia,tegra30-ahb"' where <chip> is tegra124, - tegra132, or tegra210. -- reg : Should contain 1 register ranges(address and length). For - Tegra20, Tegra30, and Tegra114 chips, the value must be <0x6000c004 - 0x10c>. For Tegra124, Tegra132 and Tegra210 chips, the value should - be be <0x6000c000 0x150>. - -Example (for a Tegra20 chip): - ahb: ahb@6000c004 { - compatible = "nvidia,tegra20-ahb"; - reg = <0x6000c004 0x10c>; /* AHB Arbitration + Gizmo Controller */ - }; diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-flowctrl.txt b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-flowctrl.txt deleted file mode 100644 index a855c1bffc0f..000000000000 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-flowctrl.txt +++ /dev/null @@ -1,18 +0,0 @@ -NVIDIA Tegra Flow Controller - -Required properties: -- compatible: Should contain one of the following: - - "nvidia,tegra20-flowctrl": for Tegra20 - - "nvidia,tegra30-flowctrl": for Tegra30 - - "nvidia,tegra114-flowctrl": for Tegra114 - - "nvidia,tegra124-flowctrl": for Tegra124 - - "nvidia,tegra132-flowctrl", "nvidia,tegra124-flowctrl": for Tegra132 - - "nvidia,tegra210-flowctrl": for Tegra210 -- reg: Should contain one register range (address and length) - -Example: - - flow-controller@60007000 { - compatible = "nvidia,tegra20-flowctrl"; - reg = <0x60007000 0x1000>; - }; diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.yaml b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.yaml deleted file mode 100644 index 89191cfdf619..000000000000 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.yaml +++ /dev/null @@ -1,393 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/arm/tegra/nvidia,tegra20-pmc.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Tegra Power Management Controller (PMC) - -maintainers: - - Thierry Reding <thierry.reding@gmail.com> - - Jonathan Hunter <jonathanh@nvidia.com> - -properties: - compatible: - enum: - - nvidia,tegra20-pmc - - nvidia,tegra30-pmc - - nvidia,tegra114-pmc - - nvidia,tegra124-pmc - - nvidia,tegra210-pmc - - reg: - maxItems: 1 - description: - Offset and length of the register set for the device. - - clock-names: - items: - - const: pclk - - const: clk32k_in - description: - Must includes entries pclk and clk32k_in. - pclk is the Tegra clock of that name and clk32k_in is 32KHz clock - input to Tegra. - - clocks: - maxItems: 2 - description: - Must contain an entry for each entry in clock-names. - See ../clocks/clocks-bindings.txt for details. - - '#clock-cells': - const: 1 - description: - Tegra PMC has clk_out_1, clk_out_2, and clk_out_3. - PMC also has blink control which allows 32Khz clock output to - Tegra blink pad. - Consumer of PMC clock should specify the desired clock by having - the clock ID in its "clocks" phandle cell with pmc clock provider. - See include/dt-bindings/soc/tegra-pmc.h for the list of Tegra PMC - clock IDs. - - '#interrupt-cells': - const: 2 - description: - Specifies number of cells needed to encode an interrupt source. - The value must be 2. - - interrupt-controller: true - - nvidia,invert-interrupt: - $ref: /schemas/types.yaml#/definitions/flag - description: Inverts the PMU interrupt signal. - The PMU is an external Power Management Unit, whose interrupt output - signal is fed into the PMC. This signal is optionally inverted, and - then fed into the ARM GIC. The PMC is not involved in the detection - or handling of this interrupt signal, merely its inversion. - - nvidia,core-power-req-active-high: - $ref: /schemas/types.yaml#/definitions/flag - description: Core power request active-high. - - nvidia,sys-clock-req-active-high: - $ref: /schemas/types.yaml#/definitions/flag - description: System clock request active-high. - - nvidia,combined-power-req: - $ref: /schemas/types.yaml#/definitions/flag - description: combined power request for CPU and Core. - - nvidia,cpu-pwr-good-en: - $ref: /schemas/types.yaml#/definitions/flag - description: - CPU power good signal from external PMIC to PMC is enabled. - - nvidia,suspend-mode: - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1, 2] - description: - The suspend mode that the platform should use. - Mode 0 is for LP0, CPU + Core voltage off and DRAM in self-refresh - Mode 1 is for LP1, CPU voltage off and DRAM in self-refresh - Mode 2 is for LP2, CPU voltage off - - nvidia,cpu-pwr-good-time: - $ref: /schemas/types.yaml#/definitions/uint32 - description: CPU power good time in uSec. - - nvidia,cpu-pwr-off-time: - $ref: /schemas/types.yaml#/definitions/uint32 - description: CPU power off time in uSec. - - nvidia,core-pwr-good-time: - $ref: /schemas/types.yaml#/definitions/uint32-array - description: - <Oscillator-stable-time Power-stable-time> - Core power good time in uSec. - - nvidia,core-pwr-off-time: - $ref: /schemas/types.yaml#/definitions/uint32 - description: Core power off time in uSec. - - nvidia,lp0-vec: - $ref: /schemas/types.yaml#/definitions/uint32-array - description: - <start length> Starting address and length of LP0 vector. - The LP0 vector contains the warm boot code that is executed - by AVP when resuming from the LP0 state. - The AVP (Audio-Video Processor) is an ARM7 processor and - always being the first boot processor when chip is power on - or resume from deep sleep mode. When the system is resumed - from the deep sleep mode, the warm boot code will restore - some PLLs, clocks and then brings up CPU0 for resuming the - system. - - core-supply: - description: - Phandle to voltage regulator connected to the SoC Core power rail. - - core-domain: - type: object - description: | - The vast majority of hardware blocks of Tegra SoC belong to a - Core power domain, which has a dedicated voltage rail that powers - the blocks. - - properties: - operating-points-v2: - description: - Should contain level, voltages and opp-supported-hw property. - The supported-hw is a bitfield indicating SoC speedo or process - ID mask. - - "#power-domain-cells": - const: 0 - - required: - - operating-points-v2 - - "#power-domain-cells" - - additionalProperties: false - - i2c-thermtrip: - type: object - description: - On Tegra30, Tegra114 and Tegra124 if i2c-thermtrip subnode exists, - hardware-triggered thermal reset will be enabled. - - properties: - nvidia,i2c-controller-id: - $ref: /schemas/types.yaml#/definitions/uint32 - description: - ID of I2C controller to send poweroff command to PMU. - Valid values are described in section 9.2.148 - "APBDEV_PMC_SCRATCH53_0" of the Tegra K1 Technical Reference - Manual. - - nvidia,bus-addr: - $ref: /schemas/types.yaml#/definitions/uint32 - description: Bus address of the PMU on the I2C bus. - - nvidia,reg-addr: - $ref: /schemas/types.yaml#/definitions/uint32 - description: PMU I2C register address to issue poweroff command. - - nvidia,reg-data: - $ref: /schemas/types.yaml#/definitions/uint32 - description: Poweroff command to write to PMU. - - nvidia,pinmux-id: - $ref: /schemas/types.yaml#/definitions/uint32 - description: - Pinmux used by the hardware when issuing Poweroff command. - Defaults to 0. Valid values are described in section 12.5.2 - "Pinmux Support" of the Tegra4 Technical Reference Manual. - - required: - - nvidia,i2c-controller-id - - nvidia,bus-addr - - nvidia,reg-addr - - nvidia,reg-data - - additionalProperties: false - - powergates: - type: object - description: | - This node contains a hierarchy of power domain nodes, which should - match the powergates on the Tegra SoC. Each powergate node - represents a power-domain on the Tegra SoC that can be power-gated - by the Tegra PMC. - Hardware blocks belonging to a power domain should contain - "power-domains" property that is a phandle pointing to corresponding - powergate node. - The name of the powergate node should be one of the below. Note that - not every powergate is applicable to all Tegra devices and the following - list shows which powergates are applicable to which devices. - Please refer to Tegra TRM for mode details on the powergate nodes to - use for each power-gate block inside Tegra. - Name Description Devices Applicable - 3d 3D Graphics Tegra20/114/124/210 - 3d0 3D Graphics 0 Tegra30 - 3d1 3D Graphics 1 Tegra30 - aud Audio Tegra210 - dfd Debug Tegra210 - dis Display A Tegra114/124/210 - disb Display B Tegra114/124/210 - heg 2D Graphics Tegra30/114/124/210 - iram Internal RAM Tegra124/210 - mpe MPEG Encode All - nvdec NVIDIA Video Decode Engine Tegra210 - nvjpg NVIDIA JPEG Engine Tegra210 - pcie PCIE Tegra20/30/124/210 - sata SATA Tegra30/124/210 - sor Display interfaces Tegra124/210 - ve2 Video Encode Engine 2 Tegra210 - venc Video Encode Engine All - vdec Video Decode Engine Tegra20/30/114/124 - vic Video Imaging Compositor Tegra124/210 - xusba USB Partition A Tegra114/124/210 - xusbb USB Partition B Tegra114/124/210 - xusbc USB Partition C Tegra114/124/210 - - patternProperties: - "^[a-z0-9]+$": - type: object - additionalProperties: false - - properties: - clocks: - minItems: 1 - maxItems: 8 - description: - Must contain an entry for each clock required by the PMC - for controlling a power-gate. - See ../clocks/clock-bindings.txt document for more details. - - resets: - minItems: 1 - maxItems: 8 - description: - Must contain an entry for each reset required by the PMC - for controlling a power-gate. - See ../reset/reset.txt for more details. - - power-domains: - maxItems: 1 - - '#power-domain-cells': - const: 0 - description: Must be 0. - - required: - - clocks - - resets - - '#power-domain-cells' - - additionalProperties: false - -patternProperties: - "^[a-f0-9]+-[a-f0-9]+$": - type: object - description: - This is a Pad configuration node. On Tegra SOCs a pad is a set of - pins which are configured as a group. The pin grouping is a fixed - attribute of the hardware. The PMC can be used to set pad power state - and signaling voltage. A pad can be either in active or power down mode. - The support for power state and signaling voltage configuration varies - depending on the pad in question. 3.3V and 1.8V signaling voltages - are supported on pins where software controllable signaling voltage - switching is available. - - The pad configuration state nodes are placed under the pmc node and they - are referred to by the pinctrl client properties. For more information - see Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt. - The pad name should be used as the value of the pins property in pin - configuration nodes. - - The following pads are present on Tegra124 and Tegra132 - audio, bb, cam, comp, csia, csb, cse, dsi, dsib, dsic, dsid, hdmi, hsic, - hv, lvds, mipi-bias, nand, pex-bias, pex-clk1, pex-clk2, pex-cntrl, - sdmmc1, sdmmc3, sdmmc4, sys_ddc, uart, usb0, usb1, usb2, usb_bias. - - The following pads are present on Tegra210 - audio, audio-hv, cam, csia, csib, csic, csid, csie, csif, dbg, - debug-nonao, dmic, dp, dsi, dsib, dsic, dsid, emmc, emmc2, gpio, hdmi, - hsic, lvds, mipi-bias, pex-bias, pex-clk1, pex-clk2, pex-cntrl, sdmmc1, - sdmmc3, spi, spi-hv, uart, usb0, usb1, usb2, usb3, usb-bias. - - properties: - pins: - $ref: /schemas/types.yaml#/definitions/string - description: Must contain name of the pad(s) to be configured. - - low-power-enable: - $ref: /schemas/types.yaml#/definitions/flag - description: Configure the pad into power down mode. - - low-power-disable: - $ref: /schemas/types.yaml#/definitions/flag - description: Configure the pad into active mode. - - power-source: - $ref: /schemas/types.yaml#/definitions/uint32 - description: - Must contain either TEGRA_IO_PAD_VOLTAGE_1V8 or - TEGRA_IO_PAD_VOLTAGE_3V3 to select between signaling voltages. - The values are defined in - include/dt-bindings/pinctrl/pinctrl-tegra-io-pad.h. - Power state can be configured on all Tegra124 and Tegra132 - pads. None of the Tegra124 or Tegra132 pads support signaling - voltage switching. - All of the listed Tegra210 pads except pex-cntrl support power - state configuration. Signaling voltage switching is supported - on below Tegra210 pads. - audio, audio-hv, cam, dbg, dmic, gpio, pex-cntrl, sdmmc1, - sdmmc3, spi, spi-hv, and uart. - - required: - - pins - - additionalProperties: false - -required: - - compatible - - reg - - clock-names - - clocks - - '#clock-cells' - -additionalProperties: false - -dependencies: - "nvidia,suspend-mode": ["nvidia,core-pwr-off-time", "nvidia,cpu-pwr-off-time"] - "nvidia,core-pwr-off-time": ["nvidia,core-pwr-good-time"] - "nvidia,cpu-pwr-off-time": ["nvidia,cpu-pwr-good-time"] - -examples: - - | - - #include <dt-bindings/clock/tegra210-car.h> - #include <dt-bindings/pinctrl/pinctrl-tegra-io-pad.h> - #include <dt-bindings/soc/tegra-pmc.h> - - tegra_pmc: pmc@7000e400 { - compatible = "nvidia,tegra210-pmc"; - reg = <0x7000e400 0x400>; - core-supply = <®ulator>; - clocks = <&tegra_car TEGRA210_CLK_PCLK>, <&clk32k_in>; - clock-names = "pclk", "clk32k_in"; - #clock-cells = <1>; - - nvidia,invert-interrupt; - nvidia,suspend-mode = <0>; - nvidia,cpu-pwr-good-time = <0>; - nvidia,cpu-pwr-off-time = <0>; - nvidia,core-pwr-good-time = <4587 3876>; - nvidia,core-pwr-off-time = <39065>; - nvidia,core-power-req-active-high; - nvidia,sys-clock-req-active-high; - - pd_core: core-domain { - operating-points-v2 = <&core_opp_table>; - #power-domain-cells = <0>; - }; - - powergates { - pd_audio: aud { - clocks = <&tegra_car TEGRA210_CLK_APE>, - <&tegra_car TEGRA210_CLK_APB2APE>; - resets = <&tegra_car 198>; - power-domains = <&pd_core>; - #power-domain-cells = <0>; - }; - - pd_xusbss: xusba { - clocks = <&tegra_car TEGRA210_CLK_XUSB_SS>; - resets = <&tegra_car TEGRA210_CLK_XUSB_SS>; - power-domains = <&pd_core>; - #power-domain-cells = <0>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/arm/ti/k3.yaml b/Documentation/devicetree/bindings/arm/ti/k3.yaml index 577eee95c893..03d2a0d79fb0 100644 --- a/Documentation/devicetree/bindings/arm/ti/k3.yaml +++ b/Documentation/devicetree/bindings/arm/ti/k3.yaml @@ -25,6 +25,12 @@ properties: - ti,am62a7-sk - const: ti,am62a7 + - description: K3 AM62P5 SoC and Boards + items: + - enum: + - ti,am62p5-sk + - const: ti,am62p5 + - description: K3 AM625 SoC PHYTEC phyBOARD-Lyra items: - const: phytec,am625-phyboard-lyra-rdk @@ -72,6 +78,13 @@ properties: - const: phytec,am64-phycore-som - const: ti,am642 + - description: K3 AM642 SoC on TQ-Systems TQMaX4XxL SoM + items: + - enum: + - tq,am642-tqma6442l-mbax4xxl # MBaX4XxL base board + - const: tq,am642-tqma6442l + - const: ti,am642 + - description: K3 AM654 SoC items: - enum: diff --git a/Documentation/devicetree/bindings/arm/ti/omap.yaml b/Documentation/devicetree/bindings/arm/ti/omap.yaml new file mode 100644 index 000000000000..b18fc046390a --- /dev/null +++ b/Documentation/devicetree/bindings/arm/ti/omap.yaml @@ -0,0 +1,176 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/ti/omap.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments OMAP SoC architecture + +maintainers: + - Tony Lindgren <tony@atomide.com> + +description: Platforms based on Texas Instruments OMAP SoC architecture. + +properties: + $nodename: + const: '/' + compatible: + oneOf: + + - description: TI OMAP2420 SoC based platforms + items: + - enum: + - nokia,n800 + - nokia,n810 + - nokia,n810-wimax + - ti,omap2420-h4 + - const: ti,omap2420 + - const: ti,omap2 + + - description: TI OMAP2430 SoC based platforms + items: + - enum: + - ti,omap2430-sdp # TI OMAP2430 SDP + - const: ti,omap2430 + - const: ti,omap2 + + - description: TI OMAP3430 SoC based platforms + items: + - enum: + - compulab,omap3-cm-t3530 + - logicpd,dm3730-som-lv-devkit # LogicPD Zoom OMAP35xx SOM-LV Development Kit + - logicpd,dm3730-torpedo-devkit # LogicPD Zoom OMAP35xx Torpedo Development Kit + - nokia,omap3-n900 + - openpandora,omap3-pandora-600mhz + - ti,omap3430-sdp + - ti,omap3-beagle + - ti,omap3-evm # TI OMAP35XX EVM (TMDSEVM3530) + - ti,omap3-ldp # TI OMAP3430 LDP (Zoom1 Labrador) + - timll,omap3-devkit8000 + - const: ti,omap3430 + - const: ti,omap3 + + - description: Early BeagleBoard revisions A to B4 with a timer quirk + items: + - const: ti,omap3-beagle-ab4 + - const: ti,omap3-beagle + - const: ti,omap3430 + - const: ti,omap3 + + - description: Gumstix Overo TI OMAP 3430/3630 boards + expansion boards + items: + - enum: + - gumstix,omap3-overo-alto35 + - gumstix,omap3-overo-chestnut43 + - gumstix,omap3-overo-gallop43 + - gumstix,omap3-overo-palo35 + - gumstix,omap3-overo-palo43 + - gumstix,omap3-overo-summit + - gumstix,omap3-overo-tobi + - gumstix,omap3-overo-tobiduo + - const: gumstix,omap3-overo + - enum: + - ti,omap3430 + - ti,omap3630 + + - description: TI OMAP3630 SoC based platforms + items: + - enum: + - amazon,omap3-echo # Amazon Echo (first generation) + - compulab,omap3-cm-t3730 + - goldelico,gta04 + - lg,omap3-sniper # LG Optimus Black + - logicpd,dm3730-som-lv-devkit # LogicPD Zoom DM3730 SOM-LV Development Kit + - logicpd,dm3730-torpedo-devkit # LogicPD Zoom DM3730 Torpedo + Wireless Development Kit + - nokia,omap3-n9 + - nokia,omap3-n950 + - openpandora,omap3-pandora-1ghz + - ti,omap3-beagle-xm + - ti,omap3-evm-37xx # TI OMAP37XX EVM (TMDSEVM3730) + - ti,omap3-zoom3 + - const: ti,omap3630 + - const: ti,omap3 + + - description: TI AM35 SoC based platforms + items: + - enum: + - compulab,omap3-sbc-t3517 # CompuLab SBC-T3517 with CM-T3517 + - teejet,mt_ventoux + - ti,am3517-craneboard # TI AM3517 CraneBoard (TMDSEVM3517) + - ti,am3517-evm # TI AM3517 EVM (AM3517/05 TMDSEVM3517) + - const: ti,am3517 + - const: ti,omap3 + + - description: TI AM33 based platform + items: + - enum: + - compulab,cm-t335 + - moxa,uc-8100-me-t + - novatech,am335x-lxm + - ti,am335x-bone + - ti,am335x-evm + - ti,am3359-icev2 + - const: ti,am33xx + + - description: Compulab board variants based on TI AM33 + items: + - enum: + - compulab,sbc-t335 + - const: compulab,cm-t335 + - const: ti,am33xx + + - description: Phytec boards based on TI AM33 + items: + - enum: + - phytec,am335x-wega + - phytec,am335x-pcm-953 + - phytec,am335x-regor + - const: phytec,am335x-phycore-som + - const: ti,am33xx + + - description: TI OMAP4430 SoC based platforms + items: + - enum: + - amazon,omap4-kc1 # Amazon Kindle Fire (first generation) + - motorola,droid4 # Motorola Droid 4 XT894 + - motorola,droid-bionic # Motorola Droid Bionic XT875 + - ti,omap4-panda + - ti,omap4-sdp + - const: ti,omap4430 + - const: ti,omap4 + + - description: OMAP4 DuoVero with Parlor expansion board/daughter board + items: + - const: gumstix,omap4-duovero-parlor + - const: gumstix,omap4-duovero + - const: ti,omap4430 + - const: ti,omap4 + + - description: TI OMAP4460 SoC based platforms + items: + - enum: + - epson,embt2ws # Epson Moverio BT-200 + - ti,omap4-panda-es + - const: ti,omap4460 + - const: ti,omap4 + + - description: VAR-OM44 boards + items: + - enum: + - variscite,var-dvk-om44 + - variscite,var-stk-om44 + - const: variscite,var-som-om44 + - const: ti,omap4460 + - const: ti,omap4 + + - description: TI OMAP5 SoC based platforms + items: + - enum: + - compulab,omap5-cm-t54 + - isee,omap5-igep0050 + - ti,omap5-uevm + - const: ti,omap5 + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/ata/nvidia,tegra-ahci.yaml b/Documentation/devicetree/bindings/ata/nvidia,tegra-ahci.yaml index 3c7a2425f3e6..a17297cbefcb 100644 --- a/Documentation/devicetree/bindings/ata/nvidia,tegra-ahci.yaml +++ b/Documentation/devicetree/bindings/ata/nvidia,tegra-ahci.yaml @@ -151,7 +151,7 @@ allOf: - interconnects - power-domains -additionalProperties: true +additionalProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/ata/pata-common.yaml b/Documentation/devicetree/bindings/ata/pata-common.yaml index 2412894a255d..4e867dd4d402 100644 --- a/Documentation/devicetree/bindings/ata/pata-common.yaml +++ b/Documentation/devicetree/bindings/ata/pata-common.yaml @@ -12,7 +12,7 @@ maintainers: description: | This document defines device tree properties common to most Parallel ATA (PATA, also known as IDE) AT attachment storage devices. - It doesn't constitue a device tree binding specification by itself but is + It doesn't constitute a device tree binding specification by itself but is meant to be referenced by device tree bindings. The PATA (IDE) controller-specific device tree bindings are responsible for @@ -38,6 +38,7 @@ patternProperties: ID number 0 and the slave drive will have ID number 1. The PATA port nodes will be named "ide-port". type: object + additionalProperties: false properties: reg: diff --git a/Documentation/devicetree/bindings/bus/brcm,gisb-arb.yaml b/Documentation/devicetree/bindings/bus/brcm,gisb-arb.yaml index b23c3001991e..3aaefdbe361e 100644 --- a/Documentation/devicetree/bindings/bus/brcm,gisb-arb.yaml +++ b/Documentation/devicetree/bindings/bus/brcm,gisb-arb.yaml @@ -43,7 +43,7 @@ properties: brcm,gisb-arb-master-names: $ref: /schemas/types.yaml#/definitions/string-array description: > - String list of the litteral name of the GISB masters. Should match the + String list of the literal name of the GISB masters. Should match the number of bits set in brcm,gisb-master-mask and the order in which they appear from MSB to LSB. diff --git a/Documentation/devicetree/bindings/bus/fsl,imx8qxp-pixel-link-msi-bus.yaml b/Documentation/devicetree/bindings/bus/fsl,imx8qxp-pixel-link-msi-bus.yaml index b568d0ce438d..7e1ffc551046 100644 --- a/Documentation/devicetree/bindings/bus/fsl,imx8qxp-pixel-link-msi-bus.yaml +++ b/Documentation/devicetree/bindings/bus/fsl,imx8qxp-pixel-link-msi-bus.yaml @@ -73,9 +73,6 @@ patternProperties: "^.*@[0-9a-f]+$": description: Devices attached to the bus type: object - properties: - reg: - maxItems: 1 required: - reg diff --git a/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml b/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml index 4157e885c6e7..26362c9006e2 100644 --- a/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml +++ b/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml @@ -7,10 +7,10 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: NVIDIA Tegra ACONNECT Bus description: | - The Tegra ACONNECT bus is an AXI switch which is used to connnect various + The Tegra ACONNECT bus is an AXI switch which is used to connect various components inside the Audio Processing Engine (APE). All CPU accesses to the APE subsystem go through the ACONNECT via an APB to AXI wrapper. All - devices accessed via the ACONNNECT are described by child-nodes. + devices accessed via the ACONNECT are described by child-nodes. maintainers: - Jon Hunter <jonathanh@nvidia.com> diff --git a/Documentation/devicetree/bindings/bus/qcom,ssbi.yaml b/Documentation/devicetree/bindings/bus/qcom,ssbi.yaml new file mode 100644 index 000000000000..693cfa9696b5 --- /dev/null +++ b/Documentation/devicetree/bindings/bus/qcom,ssbi.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/bus/qcom,ssbi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Single-wire Serial Bus Interface (SSBI) + +description: + Some Qualcomm MSM devices contain a point-to-point serial bus used to + communicate with a limited range of devices (mostly power management + chips). + +maintainers: + - Andy Gross <agross@kernel.org> + - Bjorn Andersson <andersson@kernel.org> + +properties: + compatible: + const: qcom,ssbi + + reg: + maxItems: 1 + + qcom,controller-type: + description: + Indicates the SSBI bus variant the controller should use to talk + with the slave device. The type chosen is determined by the attached + slave. + enum: + - ssbi + - ssbi2 + - pmic-arbiter + + pmic: + $ref: /schemas/mfd/qcom-pm8xxx.yaml# + +required: + - compatible + - reg + - qcom,controller-type + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + ssbi@c00000 { + compatible = "qcom,ssbi"; + reg = <0x00c00000 0x1000>; + qcom,controller-type = "pmic-arbiter"; + + pmic { + compatible = "qcom,pm8821"; + interrupt-parent = <&msmgpio>; + interrupts = <76 IRQ_TYPE_LEVEL_LOW>; + #interrupt-cells = <2>; + interrupt-controller; + #address-cells = <1>; + #size-cells = <0>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/cache/andestech,ax45mp-cache.yaml b/Documentation/devicetree/bindings/cache/andestech,ax45mp-cache.yaml new file mode 100644 index 000000000000..d2cbe49f4e15 --- /dev/null +++ b/Documentation/devicetree/bindings/cache/andestech,ax45mp-cache.yaml @@ -0,0 +1,81 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright (C) 2023 Renesas Electronics Corp. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/cache/andestech,ax45mp-cache.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Andestech AX45MP L2 Cache Controller + +maintainers: + - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com> + +description: + A level-2 cache (L2C) is used to improve the system performance by providing + a large amount of cache line entries and reasonable access delays. The L2C + is shared between cores, and a non-inclusive non-exclusive policy is used. + +select: + properties: + compatible: + contains: + enum: + - andestech,ax45mp-cache + + required: + - compatible + +properties: + compatible: + items: + - const: andestech,ax45mp-cache + - const: cache + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + cache-line-size: + const: 64 + + cache-level: + const: 2 + + cache-sets: + const: 1024 + + cache-size: + enum: [131072, 262144, 524288, 1048576, 2097152] + + cache-unified: true + + next-level-cache: true + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + - cache-line-size + - cache-level + - cache-sets + - cache-size + - cache-unified + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + cache-controller@13400000 { + compatible = "andestech,ax45mp-cache", "cache"; + reg = <0x13400000 0x100000>; + interrupts = <508 IRQ_TYPE_LEVEL_HIGH>; + cache-line-size = <64>; + cache-level = <2>; + cache-sets = <1024>; + cache-size = <262144>; + cache-unified; + }; diff --git a/Documentation/devicetree/bindings/cache/qcom,llcc.yaml b/Documentation/devicetree/bindings/cache/qcom,llcc.yaml index 44892aa589fd..580f9a97ddf7 100644 --- a/Documentation/devicetree/bindings/cache/qcom,llcc.yaml +++ b/Documentation/devicetree/bindings/cache/qcom,llcc.yaml @@ -20,6 +20,7 @@ description: | properties: compatible: enum: + - qcom,qdu1000-llcc - qcom,sc7180-llcc - qcom,sc7280-llcc - qcom,sc8180x-llcc @@ -44,6 +45,14 @@ properties: interrupts: maxItems: 1 + nvmem-cells: + items: + - description: Reference to an nvmem node for multi channel DDR + + nvmem-cell-names: + items: + - const: multi-chan-ddr + required: - compatible - reg @@ -92,6 +101,7 @@ allOf: compatible: contains: enum: + - qcom,qdu1000-llcc - qcom,sc8180x-llcc - qcom,sc8280xp-llcc then: diff --git a/Documentation/devicetree/bindings/chrome/google,cros-ec-typec.yaml b/Documentation/devicetree/bindings/chrome/google,cros-ec-typec.yaml index 3b0548c34791..9f9816fbecbc 100644 --- a/Documentation/devicetree/bindings/chrome/google,cros-ec-typec.yaml +++ b/Documentation/devicetree/bindings/chrome/google,cros-ec-typec.yaml @@ -29,10 +29,8 @@ properties: patternProperties: '^connector@[0-9a-f]+$': $ref: /schemas/connector/usb-connector.yaml# - unevaluatedProperties: false - properties: - reg: - maxItems: 1 + required: + - reg required: - compatible diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-osc-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-osc-clk.yaml index 52a7b6e7124c..0052bf1e8a6b 100644 --- a/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-osc-clk.yaml +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-osc-clk.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/clock/allwinner,sun4i-a10-osc-clk.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Allwinner A10 Gatable Oscillator Clock +title: Allwinner A10 Gateable Oscillator Clock maintainers: - Chen-Yu Tsai <wens@csie.org> diff --git a/Documentation/devicetree/bindings/clock/alphascale,acc.txt b/Documentation/devicetree/bindings/clock/alphascale,acc.txt index b3205b21c9d0..c9fb9324c634 100644 --- a/Documentation/devicetree/bindings/clock/alphascale,acc.txt +++ b/Documentation/devicetree/bindings/clock/alphascale,acc.txt @@ -1,7 +1,7 @@ Alphascale Clock Controller -The ACC (Alphascale Clock Controller) is responsible of choising proper -clock source, setting deviders and clock gates. +The ACC (Alphascale Clock Controller) is responsible for choosing proper +clock source, setting dividers and clock gates. Required properties for the ACC node: - compatible: must be "alphascale,asm9260-clock-controller" diff --git a/Documentation/devicetree/bindings/clock/amlogic,gxbb-aoclkc.txt b/Documentation/devicetree/bindings/clock/amlogic,gxbb-aoclkc.txt deleted file mode 100644 index c41f0be5d438..000000000000 --- a/Documentation/devicetree/bindings/clock/amlogic,gxbb-aoclkc.txt +++ /dev/null @@ -1,64 +0,0 @@ -* Amlogic GXBB AO Clock and Reset Unit - -The Amlogic GXBB AO clock controller generates and supplies clock to various -controllers within the Always-On part of the SoC. - -Required Properties: - -- compatible: value should be different for each SoC family as : - - GXBB (S905) : "amlogic,meson-gxbb-aoclkc" - - GXL (S905X, S905D) : "amlogic,meson-gxl-aoclkc" - - GXM (S912) : "amlogic,meson-gxm-aoclkc" - - AXG (A113D, A113X) : "amlogic,meson-axg-aoclkc" - - G12A (S905X2, S905D2, S905Y2) : "amlogic,meson-g12a-aoclkc" - followed by the common "amlogic,meson-gx-aoclkc" -- clocks: list of clock phandle, one for each entry clock-names. -- clock-names: should contain the following: - * "xtal" : the platform xtal - * "mpeg-clk" : the main clock controller mother clock (aka clk81) - * "ext-32k-0" : external 32kHz reference #0 if any (optional) - * "ext-32k-1" : external 32kHz reference #1 if any (optional - gx only) - * "ext-32k-2" : external 32kHz reference #2 if any (optional - gx only) - -- #clock-cells: should be 1. - -Each clock is assigned an identifier and client nodes can use this identifier -to specify the clock which they consume. All available clocks are defined as -preprocessor macros in the dt-bindings/clock/gxbb-aoclkc.h header and can be -used in device tree sources. - -- #reset-cells: should be 1. - -Each reset is assigned an identifier and client nodes can use this identifier -to specify the reset which they consume. All available resets are defined as -preprocessor macros in the dt-bindings/reset/gxbb-aoclkc.h header and can be -used in device tree sources. - -Parent node should have the following properties : -- compatible: "amlogic,meson-gx-ao-sysctrl", "syscon", "simple-mfd" -- reg: base address and size of the AO system control register space. - -Example: AO Clock controller node: - -ao_sysctrl: sys-ctrl@0 { - compatible = "amlogic,meson-gx-ao-sysctrl", "syscon", "simple-mfd"; - reg = <0x0 0x0 0x0 0x100>; - - clkc_AO: clock-controller { - compatible = "amlogic,meson-gxbb-aoclkc", "amlogic,meson-gx-aoclkc"; - #clock-cells = <1>; - #reset-cells = <1>; - clocks = <&xtal>, <&clkc CLKID_CLK81>; - clock-names = "xtal", "mpeg-clk"; - }; - -Example: UART controller node that consumes the clock and reset generated - by the clock controller: - - uart_AO: serial@4c0 { - compatible = "amlogic,meson-uart"; - reg = <0x4c0 0x14>; - interrupts = <0 90 1>; - clocks = <&clkc_AO CLKID_AO_UART1>; - resets = <&clkc_AO RESET_AO_UART1>; - }; diff --git a/Documentation/devicetree/bindings/clock/amlogic,gxbb-aoclkc.yaml b/Documentation/devicetree/bindings/clock/amlogic,gxbb-aoclkc.yaml new file mode 100644 index 000000000000..628e5dd33dd4 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/amlogic,gxbb-aoclkc.yaml @@ -0,0 +1,85 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/amlogic,gxbb-aoclkc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic Always-On Clock Controller + +maintainers: + - Neil Armstrong <neil.armstrong@linaro.org> + +properties: + compatible: + oneOf: + - items: + - enum: + - amlogic,meson-gxbb-aoclkc + - amlogic,meson-gxl-aoclkc + - amlogic,meson-gxm-aoclkc + - amlogic,meson-axg-aoclkc + - const: amlogic,meson-gx-aoclkc + - enum: + - amlogic,meson-axg-aoclkc + - amlogic,meson-g12a-aoclkc + + clocks: + minItems: 2 + maxItems: 5 + + clock-names: + minItems: 2 + items: + - const: xtal + - const: mpeg-clk + - const: ext-32k-0 + - const: ext-32k-1 + - const: ext-32k-2 + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + +required: + - compatible + - clocks + - clock-names + - '#clock-cells' + - '#reset-cells' + +allOf: + - if: + properties: + compatible: + enum: + - amlogic,meson-g12a-aoclkc + + then: + properties: + clocks: + minItems: 2 + maxItems: 3 + + clock-names: + minItems: 2 + maxItems: 3 + + - if: + properties: + compatible: + enum: + - amlogic,meson-gxl-aoclkc + - amlogic,meson-gxm-aoclkc + - amlogic,meson-axg-aoclkc + + then: + properties: + clocks: + maxItems: 2 + + clock-names: + maxItems: 2 + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt b/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt deleted file mode 100644 index 7ccecd5c02c1..000000000000 --- a/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt +++ /dev/null @@ -1,53 +0,0 @@ -* Amlogic GXBB Clock and Reset Unit - -The Amlogic GXBB clock controller generates and supplies clock to various -controllers within the SoC. - -Required Properties: - -- compatible: should be: - "amlogic,gxbb-clkc" for GXBB SoC, - "amlogic,gxl-clkc" for GXL and GXM SoC, - "amlogic,axg-clkc" for AXG SoC. - "amlogic,g12a-clkc" for G12A SoC. - "amlogic,g12b-clkc" for G12B SoC. - "amlogic,sm1-clkc" for SM1 SoC. -- clocks : list of clock phandle, one for each entry clock-names. -- clock-names : should contain the following: - * "xtal": the platform xtal - -- #clock-cells: should be 1. - -Each clock is assigned an identifier and client nodes can use this identifier -to specify the clock which they consume. All available clocks are defined as -preprocessor macros in the dt-bindings/clock/gxbb-clkc.h header and can be -used in device tree sources. - -Parent node should have the following properties : -- compatible: "syscon", "simple-mfd, and "amlogic,meson-gx-hhi-sysctrl" or - "amlogic,meson-axg-hhi-sysctrl" -- reg: base address and size of the HHI system control register space. - -Example: Clock controller node: - -sysctrl: system-controller@0 { - compatible = "amlogic,meson-gx-hhi-sysctrl", "syscon", "simple-mfd"; - reg = <0 0 0 0x400>; - - clkc: clock-controller { - #clock-cells = <1>; - compatible = "amlogic,gxbb-clkc"; - clocks = <&xtal>; - clock-names = "xtal"; - }; -}; - -Example: UART controller node that consumes the clock generated by the clock - controller: - - uart_AO: serial@c81004c0 { - compatible = "amlogic,meson-uart"; - reg = <0xc81004c0 0x14>; - interrupts = <0 90 1>; - clocks = <&clkc CLKID_CLK81>; - }; diff --git a/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.yaml b/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.yaml new file mode 100644 index 000000000000..63246f1cb539 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/amlogic,gxbb-clkc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic Clock Controller + +maintainers: + - Neil Armstrong <neil.armstrong@linaro.org> + +properties: + compatible: + enum: + - amlogic,gxbb-clkc + - amlogic,gxl-clkc + - amlogic,axg-clkc + - amlogic,g12a-clkc + - amlogic,g12b-clkc + - amlogic,sm1-clkc + + clocks: + maxItems: 1 + + clock-names: + const: xtal + + '#clock-cells': + const: 1 + +required: + - compatible + - clocks + - clock-names + - '#clock-cells' + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/clock/amlogic,s4-peripherals-clkc.yaml b/Documentation/devicetree/bindings/clock/amlogic,s4-peripherals-clkc.yaml new file mode 100644 index 000000000000..c229e4f0c1d9 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/amlogic,s4-peripherals-clkc.yaml @@ -0,0 +1,96 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2022-2023 Amlogic, Inc. All rights reserved +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/amlogic,s4-peripherals-clkc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic S4 Peripherals Clock Controller + +maintainers: + - Yu Tu <yu.tu@amlogic.com> + +properties: + compatible: + const: amlogic,s4-peripherals-clkc + + reg: + maxItems: 1 + + clocks: + minItems: 14 + items: + - description: input fixed pll div2 + - description: input fixed pll div2p5 + - description: input fixed pll div3 + - description: input fixed pll div4 + - description: input fixed pll div5 + - description: input fixed pll div7 + - description: input hifi pll + - description: input gp0 pll + - description: input mpll0 + - description: input mpll1 + - description: input mpll2 + - description: input mpll3 + - description: input hdmi pll + - description: input oscillator (usually at 24MHz) + - description: input external 32kHz reference (optional) + + clock-names: + minItems: 14 + items: + - const: fclk_div2 + - const: fclk_div2p5 + - const: fclk_div3 + - const: fclk_div4 + - const: fclk_div5 + - const: fclk_div7 + - const: hifi_pll + - const: gp0_pll + - const: mpll0 + - const: mpll1 + - const: mpll2 + - const: mpll3 + - const: hdmi_pll + - const: xtal + - const: ext_32k + + "#clock-cells": + const: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - "#clock-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/amlogic,s4-peripherals-clkc.h> + + clkc_periphs: clock-controller@fe000000 { + compatible = "amlogic,s4-peripherals-clkc"; + reg = <0xfe000000 0x49c>; + clocks = <&clkc_pll 3>, + <&clkc_pll 13>, + <&clkc_pll 5>, + <&clkc_pll 7>, + <&clkc_pll 9>, + <&clkc_pll 11>, + <&clkc_pll 17>, + <&clkc_pll 15>, + <&clkc_pll 25>, + <&clkc_pll 27>, + <&clkc_pll 29>, + <&clkc_pll 31>, + <&clkc_pll 20>, + <&xtal>; + clock-names = "fclk_div2", "fclk_div2p5", "fclk_div3", "fclk_div4", + "fclk_div5", "fclk_div7", "hifi_pll", "gp0_pll", + "mpll0", "mpll1", "mpll2", "mpll3", "hdmi_pll", "xtal"; + #clock-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/amlogic,s4-pll-clkc.yaml b/Documentation/devicetree/bindings/clock/amlogic,s4-pll-clkc.yaml new file mode 100644 index 000000000000..d8932ec26ca8 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/amlogic,s4-pll-clkc.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2022-2023 Amlogic, Inc. All rights reserved +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/amlogic,s4-pll-clkc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic S4 PLL Clock Controller + +maintainers: + - Yu Tu <yu.tu@amlogic.com> + +properties: + compatible: + const: amlogic,s4-pll-clkc + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: xtal + + "#clock-cells": + const: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - "#clock-cells" + +additionalProperties: false + +examples: + - | + clkc_pll: clock-controller@fe008000 { + compatible = "amlogic,s4-pll-clkc"; + reg = <0xfe008000 0x1e8>; + clocks = <&xtal>; + clock-names = "xtal"; + #clock-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/fsl,imx8-acm.yaml b/Documentation/devicetree/bindings/clock/fsl,imx8-acm.yaml new file mode 100644 index 000000000000..07b9d21719c4 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/fsl,imx8-acm.yaml @@ -0,0 +1,282 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/fsl,imx8-acm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP i.MX8 Audio Clock Mux + +maintainers: + - Shengjiu Wang <shengjiu.wang@nxp.com> + +description: | + NXP i.MX8 Audio Clock Mux is dedicated clock muxing IP + used to control Audio related clock on the SoC. + +properties: + compatible: + enum: + - fsl,imx8dxl-acm + - fsl,imx8qm-acm + - fsl,imx8qxp-acm + + reg: + maxItems: 1 + + power-domains: + minItems: 13 + maxItems: 21 + + '#clock-cells': + const: 1 + description: + The clock consumer should specify the desired clock by having the clock + ID in its "clocks" phandle cell. See include/dt-bindings/clock/imx8-clock.h + for the full list of i.MX8 ACM clock IDs. + + clocks: + minItems: 13 + maxItems: 27 + + clock-names: + minItems: 13 + maxItems: 27 + +required: + - compatible + - reg + - power-domains + - '#clock-cells' + - clocks + - clock-names + +allOf: + - if: + properties: + compatible: + contains: + enum: + - fsl,imx8qxp-acm + then: + properties: + power-domains: + items: + - description: power domain of IMX_SC_R_AUDIO_CLK_0 + - description: power domain of IMX_SC_R_AUDIO_CLK_1 + - description: power domain of IMX_SC_R_MCLK_OUT_0 + - description: power domain of IMX_SC_R_MCLK_OUT_1 + - description: power domain of IMX_SC_R_AUDIO_PLL_0 + - description: power domain of IMX_SC_R_AUDIO_PLL_1 + - description: power domain of IMX_SC_R_ASRC_0 + - description: power domain of IMX_SC_R_ASRC_1 + - description: power domain of IMX_SC_R_ESAI_0 + - description: power domain of IMX_SC_R_SAI_0 + - description: power domain of IMX_SC_R_SAI_1 + - description: power domain of IMX_SC_R_SAI_2 + - description: power domain of IMX_SC_R_SAI_3 + - description: power domain of IMX_SC_R_SAI_4 + - description: power domain of IMX_SC_R_SAI_5 + - description: power domain of IMX_SC_R_SPDIF_0 + - description: power domain of IMX_SC_R_MQS_0 + + clocks: + minItems: 18 + maxItems: 18 + + clock-names: + items: + - const: aud_rec_clk0_lpcg_clk + - const: aud_rec_clk1_lpcg_clk + - const: aud_pll_div_clk0_lpcg_clk + - const: aud_pll_div_clk1_lpcg_clk + - const: ext_aud_mclk0 + - const: ext_aud_mclk1 + - const: esai0_rx_clk + - const: esai0_rx_hf_clk + - const: esai0_tx_clk + - const: esai0_tx_hf_clk + - const: spdif0_rx + - const: sai0_rx_bclk + - const: sai0_tx_bclk + - const: sai1_rx_bclk + - const: sai1_tx_bclk + - const: sai2_rx_bclk + - const: sai3_rx_bclk + - const: sai4_rx_bclk + + - if: + properties: + compatible: + contains: + enum: + - fsl,imx8qm-acm + then: + properties: + power-domains: + items: + - description: power domain of IMX_SC_R_AUDIO_CLK_0 + - description: power domain of IMX_SC_R_AUDIO_CLK_1 + - description: power domain of IMX_SC_R_MCLK_OUT_0 + - description: power domain of IMX_SC_R_MCLK_OUT_1 + - description: power domain of IMX_SC_R_AUDIO_PLL_0 + - description: power domain of IMX_SC_R_AUDIO_PLL_1 + - description: power domain of IMX_SC_R_ASRC_0 + - description: power domain of IMX_SC_R_ASRC_1 + - description: power domain of IMX_SC_R_ESAI_0 + - description: power domain of IMX_SC_R_ESAI_1 + - description: power domain of IMX_SC_R_SAI_0 + - description: power domain of IMX_SC_R_SAI_1 + - description: power domain of IMX_SC_R_SAI_2 + - description: power domain of IMX_SC_R_SAI_3 + - description: power domain of IMX_SC_R_SAI_4 + - description: power domain of IMX_SC_R_SAI_5 + - description: power domain of IMX_SC_R_SAI_6 + - description: power domain of IMX_SC_R_SAI_7 + - description: power domain of IMX_SC_R_SPDIF_0 + - description: power domain of IMX_SC_R_SPDIF_1 + - description: power domain of IMX_SC_R_MQS_0 + + clocks: + minItems: 27 + maxItems: 27 + + clock-names: + items: + - const: aud_rec_clk0_lpcg_clk + - const: aud_rec_clk1_lpcg_clk + - const: aud_pll_div_clk0_lpcg_clk + - const: aud_pll_div_clk1_lpcg_clk + - const: mlb_clk + - const: hdmi_rx_mclk + - const: ext_aud_mclk0 + - const: ext_aud_mclk1 + - const: esai0_rx_clk + - const: esai0_rx_hf_clk + - const: esai0_tx_clk + - const: esai0_tx_hf_clk + - const: esai1_rx_clk + - const: esai1_rx_hf_clk + - const: esai1_tx_clk + - const: esai1_tx_hf_clk + - const: spdif0_rx + - const: spdif1_rx + - const: sai0_rx_bclk + - const: sai0_tx_bclk + - const: sai1_rx_bclk + - const: sai1_tx_bclk + - const: sai2_rx_bclk + - const: sai3_rx_bclk + - const: sai4_rx_bclk + - const: sai5_tx_bclk + - const: sai6_rx_bclk + + - if: + properties: + compatible: + contains: + enum: + - fsl,imx8dxl-acm + then: + properties: + power-domains: + items: + - description: power domain of IMX_SC_R_AUDIO_CLK_0 + - description: power domain of IMX_SC_R_AUDIO_CLK_1 + - description: power domain of IMX_SC_R_MCLK_OUT_0 + - description: power domain of IMX_SC_R_MCLK_OUT_1 + - description: power domain of IMX_SC_R_AUDIO_PLL_0 + - description: power domain of IMX_SC_R_AUDIO_PLL_1 + - description: power domain of IMX_SC_R_ASRC_0 + - description: power domain of IMX_SC_R_SAI_0 + - description: power domain of IMX_SC_R_SAI_1 + - description: power domain of IMX_SC_R_SAI_2 + - description: power domain of IMX_SC_R_SAI_3 + - description: power domain of IMX_SC_R_SPDIF_0 + - description: power domain of IMX_SC_R_MQS_0 + + clocks: + minItems: 13 + maxItems: 13 + + clock-names: + items: + - const: aud_rec_clk0_lpcg_clk + - const: aud_rec_clk1_lpcg_clk + - const: aud_pll_div_clk0_lpcg_clk + - const: aud_pll_div_clk1_lpcg_clk + - const: ext_aud_mclk0 + - const: ext_aud_mclk1 + - const: spdif0_rx + - const: sai0_rx_bclk + - const: sai0_tx_bclk + - const: sai1_rx_bclk + - const: sai1_tx_bclk + - const: sai2_rx_bclk + - const: sai3_rx_bclk + +additionalProperties: false + +examples: + # Clock Control Module node: + - | + #include <dt-bindings/clock/imx8-lpcg.h> + #include <dt-bindings/firmware/imx/rsrc.h> + + clock-controller@59e00000 { + compatible = "fsl,imx8qxp-acm"; + reg = <0x59e00000 0x1d0000>; + #clock-cells = <1>; + power-domains = <&pd IMX_SC_R_AUDIO_CLK_0>, + <&pd IMX_SC_R_AUDIO_CLK_1>, + <&pd IMX_SC_R_MCLK_OUT_0>, + <&pd IMX_SC_R_MCLK_OUT_1>, + <&pd IMX_SC_R_AUDIO_PLL_0>, + <&pd IMX_SC_R_AUDIO_PLL_1>, + <&pd IMX_SC_R_ASRC_0>, + <&pd IMX_SC_R_ASRC_1>, + <&pd IMX_SC_R_ESAI_0>, + <&pd IMX_SC_R_SAI_0>, + <&pd IMX_SC_R_SAI_1>, + <&pd IMX_SC_R_SAI_2>, + <&pd IMX_SC_R_SAI_3>, + <&pd IMX_SC_R_SAI_4>, + <&pd IMX_SC_R_SAI_5>, + <&pd IMX_SC_R_SPDIF_0>, + <&pd IMX_SC_R_MQS_0>; + clocks = <&aud_rec0_lpcg IMX_LPCG_CLK_0>, + <&aud_rec1_lpcg IMX_LPCG_CLK_0>, + <&aud_pll_div0_lpcg IMX_LPCG_CLK_0>, + <&aud_pll_div1_lpcg IMX_LPCG_CLK_0>, + <&clk_ext_aud_mclk0>, + <&clk_ext_aud_mclk1>, + <&clk_esai0_rx_clk>, + <&clk_esai0_rx_hf_clk>, + <&clk_esai0_tx_clk>, + <&clk_esai0_tx_hf_clk>, + <&clk_spdif0_rx>, + <&clk_sai0_rx_bclk>, + <&clk_sai0_tx_bclk>, + <&clk_sai1_rx_bclk>, + <&clk_sai1_tx_bclk>, + <&clk_sai2_rx_bclk>, + <&clk_sai3_rx_bclk>, + <&clk_sai4_rx_bclk>; + clock-names = "aud_rec_clk0_lpcg_clk", + "aud_rec_clk1_lpcg_clk", + "aud_pll_div_clk0_lpcg_clk", + "aud_pll_div_clk1_lpcg_clk", + "ext_aud_mclk0", + "ext_aud_mclk1", + "esai0_rx_clk", + "esai0_rx_hf_clk", + "esai0_tx_clk", + "esai0_tx_hf_clk", + "spdif0_rx", + "sai0_rx_bclk", + "sai0_tx_bclk", + "sai1_rx_bclk", + "sai1_tx_bclk", + "sai2_rx_bclk", + "sai3_rx_bclk", + "sai4_rx_bclk"; + }; diff --git a/Documentation/devicetree/bindings/clock/hix5hd2-clock.txt b/Documentation/devicetree/bindings/clock/hix5hd2-clock.txt deleted file mode 100644 index 4733e58e491b..000000000000 --- a/Documentation/devicetree/bindings/clock/hix5hd2-clock.txt +++ /dev/null @@ -1,30 +0,0 @@ -* Hisilicon Hix5hd2 Clock Controller - -The hix5hd2 clock controller generates and supplies clock to various -controllers within the hix5hd2 SoC. - -Required Properties: - -- compatible: should be "hisilicon,hix5hd2-clock" -- reg: Address and length of the register set -- #clock-cells: Should be <1> - -Each clock is assigned an identifier and client nodes use this identifier -to specify the clock which they consume. - -All these identifier could be found in <dt-bindings/clock/hix5hd2-clock.h>. - -Examples: - clock: clock@f8a22000 { - compatible = "hisilicon,hix5hd2-clock"; - reg = <0xf8a22000 0x1000>; - #clock-cells = <1>; - }; - - uart0: uart@f8b00000 { - compatible = "arm,pl011", "arm,primecell"; - reg = <0xf8b00000 0x1000>; - interrupts = <0 49 4>; - clocks = <&clock HIX5HD2_FIXED_83M>; - clock-names = "apb_pclk"; - }; diff --git a/Documentation/devicetree/bindings/clock/intel,agilex5-clkmgr.yaml b/Documentation/devicetree/bindings/clock/intel,agilex5-clkmgr.yaml new file mode 100644 index 000000000000..d120b0da7f3d --- /dev/null +++ b/Documentation/devicetree/bindings/clock/intel,agilex5-clkmgr.yaml @@ -0,0 +1,40 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/intel,agilex5-clkmgr.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel SoCFPGA Agilex5 clock manager + +maintainers: + - Dinh Nguyen <dinguyen@kernel.org> + +description: + The Intel Agilex5 Clock Manager is an integrated clock controller, which + generates and supplies clock to all the modules. + +properties: + compatible: + const: intel,agilex5-clkmgr + + reg: + maxItems: 1 + + '#clock-cells': + const: 1 + +required: + - compatible + - reg + - '#clock-cells' + +additionalProperties: false + +examples: + - | + clkmgr: clock-controller@10d10000 { + compatible = "intel,agilex5-clkmgr"; + reg = <0x10d10000 0x1000>; + #clock-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/keystone-pll.txt b/Documentation/devicetree/bindings/clock/keystone-pll.txt index 47570d207215..9a3fbc665606 100644 --- a/Documentation/devicetree/bindings/clock/keystone-pll.txt +++ b/Documentation/devicetree/bindings/clock/keystone-pll.txt @@ -14,7 +14,7 @@ Required properties: - #clock-cells : from common clock binding; shall be set to 0. - compatible : shall be "ti,keystone,main-pll-clock" or "ti,keystone,pll-clock" - clocks : parent clock phandle -- reg - pll control0 and pll multipler registers +- reg - pll control0 and pll multiplier registers - reg-names : control, multiplier and post-divider. The multiplier and post-divider registers are applicable only for main pll clock - fixed-postdiv : fixed post divider value. If absent, use clkod register bits diff --git a/Documentation/devicetree/bindings/clock/lpc1850-ccu.txt b/Documentation/devicetree/bindings/clock/lpc1850-ccu.txt index fa97c12014ac..8cf8f0ecdd16 100644 --- a/Documentation/devicetree/bindings/clock/lpc1850-ccu.txt +++ b/Documentation/devicetree/bindings/clock/lpc1850-ccu.txt @@ -68,7 +68,7 @@ soc { "base_ssp0_clk", "base_sdio_clk"; }; - /* A user of CCU brach clocks */ + /* A user of CCU branch clocks */ uart1: serial@40082000 { ... clocks = <&ccu2 CLK_APB0_UART1>, <&ccu1 CLK_CPU_UART1>; diff --git a/Documentation/devicetree/bindings/clock/lpc1850-creg-clk.txt b/Documentation/devicetree/bindings/clock/lpc1850-creg-clk.txt index 6f1c7b4e4d2c..b6b2547a3d17 100644 --- a/Documentation/devicetree/bindings/clock/lpc1850-creg-clk.txt +++ b/Documentation/devicetree/bindings/clock/lpc1850-creg-clk.txt @@ -5,8 +5,8 @@ control registers for two low speed clocks. One of the clocks is a 32 kHz oscillator driver with power up/down and clock gating. Next is a fixed divider that creates a 1 kHz clock from the 32 kHz osc. -These clocks are used by the RTC and the Event Router peripherials. -The 32 kHz can also be routed to other peripherials to enable low +These clocks are used by the RTC and the Event Router peripherals. +The 32 kHz can also be routed to other peripherals to enable low power modes. This binding uses the common clock binding: diff --git a/Documentation/devicetree/bindings/clock/maxim,max9485.txt b/Documentation/devicetree/bindings/clock/maxim,max9485.txt index 61bec1100a94..b8f5c3bbf12b 100644 --- a/Documentation/devicetree/bindings/clock/maxim,max9485.txt +++ b/Documentation/devicetree/bindings/clock/maxim,max9485.txt @@ -12,7 +12,7 @@ requests. Required properties: - compatible: "maxim,max9485" -- clocks: Input clock, must provice 27.000 MHz +- clocks: Input clock, must provide 27.000 MHz - clock-names: Must be set to "xclk" - #clock-cells: From common clock binding; shall be set to 1 diff --git a/Documentation/devicetree/bindings/clock/nvidia,tegra124-car.yaml b/Documentation/devicetree/bindings/clock/nvidia,tegra124-car.yaml index 1b2181f6d440..a9ba21144a56 100644 --- a/Documentation/devicetree/bindings/clock/nvidia,tegra124-car.yaml +++ b/Documentation/devicetree/bindings/clock/nvidia,tegra124-car.yaml @@ -27,7 +27,9 @@ description: | properties: compatible: - const: nvidia,tegra124-car + enum: + - nvidia,tegra124-car + - nvidia,tegra132-car reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/clock/oxnas,stdclk.txt b/Documentation/devicetree/bindings/clock/oxnas,stdclk.txt deleted file mode 100644 index b652f3fb7796..000000000000 --- a/Documentation/devicetree/bindings/clock/oxnas,stdclk.txt +++ /dev/null @@ -1,28 +0,0 @@ -Oxford Semiconductor OXNAS SoC Family Standard Clocks -================================================ - -Please also refer to clock-bindings.txt in this directory for common clock -bindings usage. - -Required properties: -- compatible: For OX810SE, should be "oxsemi,ox810se-stdclk" - For OX820, should be "oxsemi,ox820-stdclk" -- #clock-cells: 1, see below - -Parent node should have the following properties : -- compatible: For OX810SE, should be - "oxsemi,ox810se-sys-ctrl", "syscon", "simple-mfd" - For OX820, should be - "oxsemi,ox820-sys-ctrl", "syscon", "simple-mfd" - -example: - -sys: sys-ctrl@000000 { - compatible = "oxsemi,ox810se-sys-ctrl", "syscon", "simple-mfd"; - reg = <0x000000 0x100000>; - - stdclk: stdclk { - compatible = "oxsemi,ox810se-stdclk"; - #clock-cells = <1>; - }; -}; diff --git a/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6125.yaml b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6125.yaml index 8a210c4c5f82..0a3ef7fd03fa 100644 --- a/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6125.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6125.yaml @@ -29,6 +29,7 @@ properties: - description: Link clock from DP PHY - description: VCO DIV clock from DP PHY - description: AHB config clock from GCC + - description: GPLL0 div source from GCC clock-names: items: @@ -39,6 +40,7 @@ properties: - const: dp_phy_pll_link_clk - const: dp_phy_pll_vco_div_clk - const: cfg_ahb_clk + - const: gcc_disp_gpll0_div_clk_src '#clock-cells': const: 1 @@ -46,6 +48,16 @@ properties: '#power-domain-cells': const: 1 + power-domains: + description: + A phandle and PM domain specifier for the CX power domain. + maxItems: 1 + + required-opps: + description: + A phandle to an OPP node describing the power domain's performance point. + maxItems: 1 + reg: maxItems: 1 @@ -63,23 +75,31 @@ examples: - | #include <dt-bindings/clock/qcom,rpmcc.h> #include <dt-bindings/clock/qcom,gcc-sm6125.h> + #include <dt-bindings/power/qcom-rpmpd.h> clock-controller@5f00000 { compatible = "qcom,sm6125-dispcc"; reg = <0x5f00000 0x20000>; + clocks = <&rpmcc RPM_SMD_XO_CLK_SRC>, <&dsi0_phy 0>, <&dsi0_phy 1>, <&dsi1_phy 1>, <&dp_phy 0>, <&dp_phy 1>, - <&gcc GCC_DISP_AHB_CLK>; + <&gcc GCC_DISP_AHB_CLK>, + <&gcc GCC_DISP_GPLL0_DIV_CLK_SRC>; clock-names = "bi_tcxo", "dsi0_phy_pll_out_byteclk", "dsi0_phy_pll_out_dsiclk", "dsi1_phy_pll_out_dsiclk", "dp_phy_pll_link_clk", "dp_phy_pll_vco_div_clk", - "cfg_ahb_clk"; + "cfg_ahb_clk", + "gcc_disp_gpll0_div_clk_src"; + + required-opps = <&rpmhpd_opp_ret>; + power-domains = <&rpmpd SM6125_VDDCX>; + #clock-cells = <1>; #power-domain-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/clock/qcom,dispcc-sm8x50.yaml b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm8x50.yaml index d6774db257f0..59cc88a52f6b 100644 --- a/Documentation/devicetree/bindings/clock/qcom,dispcc-sm8x50.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm8x50.yaml @@ -82,7 +82,7 @@ additionalProperties: false examples: - | #include <dt-bindings/clock/qcom,rpmh.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> clock-controller@af00000 { compatible = "qcom,sm8250-dispcc"; reg = <0x0af00000 0x10000>; @@ -103,7 +103,7 @@ examples: #clock-cells = <1>; #reset-cells = <1>; #power-domain-cells = <1>; - power-domains = <&rpmhpd SM8250_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; required-opps = <&rpmhpd_opp_low_svs>; }; ... diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-apq8064.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-apq8064.yaml index 09cd7a786871..19211176ee0b 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-apq8064.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-apq8064.yaml @@ -8,7 +8,7 @@ title: Qualcomm Global Clock & Reset Controller on APQ8064/MSM8960 maintainers: - Stephen Boyd <sboyd@kernel.org> - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm global clock control module provides the clocks, resets and power diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-ipq4019.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-ipq4019.yaml index 6ebaef2288fa..fb3957d485f9 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-ipq4019.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-ipq4019.yaml @@ -8,7 +8,7 @@ title: Qualcomm Global Clock & Reset Controller on IPQ4019 maintainers: - Stephen Boyd <sboyd@kernel.org> - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> - Robert Marko <robert.markoo@sartura.hr> description: | diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8074.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8074.yaml index deef398a9872..52e7831a8d6d 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8074.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8074.yaml @@ -8,7 +8,7 @@ title: Qualcomm Global Clock & Reset Controller on IPQ8074 maintainers: - Stephen Boyd <sboyd@kernel.org> - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm global clock control module provides the clocks, resets and power diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8976.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8976.yaml index d2186e25f55f..62d6f1fe1228 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8976.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8976.yaml @@ -8,7 +8,7 @@ title: Qualcomm Global Clock & Reset Controller on MSM8976 maintainers: - Stephen Boyd <sboyd@kernel.org> - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm global clock control module provides the clocks, resets and power diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8996.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8996.yaml index f77036ace31b..97523cc1ecfb 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8996.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8996.yaml @@ -8,7 +8,7 @@ title: Qualcomm Global Clock & Reset Controller on MSM8996 maintainers: - Stephen Boyd <sboyd@kernel.org> - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm global clock control module which provides the clocks, resets and diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8998.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8998.yaml index 3c9729050d6f..58f7fb22c5c4 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8998.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8998.yaml @@ -8,7 +8,7 @@ title: Qualcomm Global Clock & Reset Controller on MSM8998 maintainers: - Stephen Boyd <sboyd@kernel.org> - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm global clock control module provides the clocks, resets and power diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-other.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-other.yaml index ba969e7a57bf..559fc21435c8 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-other.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-other.yaml @@ -8,7 +8,7 @@ title: Qualcomm Global Clock & Reset Controller maintainers: - Stephen Boyd <sboyd@kernel.org> - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm global clock control module provides the clocks, resets and power @@ -19,8 +19,6 @@ description: | include/dt-bindings/reset/qcom,gcc-ipq6018.h include/dt-bindings/clock/qcom,gcc-msm8953.h include/dt-bindings/clock/qcom,gcc-mdm9607.h - include/dt-bindings/clock/qcom,gcc-mdm9615.h - include/dt-bindings/reset/qcom,gcc-mdm9615.h allOf: - $ref: qcom,gcc.yaml# @@ -30,7 +28,6 @@ properties: enum: - qcom,gcc-ipq6018 - qcom,gcc-mdm9607 - - qcom,gcc-mdm9615 required: - compatible diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-qcs404.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-qcs404.yaml index b2256f81b265..7bc6c57e4d11 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-qcs404.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-qcs404.yaml @@ -8,7 +8,7 @@ title: Qualcomm Global Clock & Reset Controller on QCS404 maintainers: - Stephen Boyd <sboyd@kernel.org> - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm global clock control module provides the clocks, resets and power diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sc7180.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sc7180.yaml index 8bf9b6f49550..7aae21a76690 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sc7180.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sc7180.yaml @@ -8,7 +8,7 @@ title: Qualcomm Global Clock & Reset Controller on SC7180 maintainers: - Stephen Boyd <sboyd@kernel.org> - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm global clock control module provides the clocks, resets and power diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sc7280.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sc7280.yaml index ff0b18bbb0fc..c4ca08d9ad5a 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sc7280.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sc7280.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Global Clock & Reset Controller on SC7280 maintainers: - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm global clock control module provides the clocks, resets and power diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sdm845.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sdm845.yaml index 68e1b7822fe0..0595da0e8a42 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sdm845.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sdm845.yaml @@ -8,7 +8,7 @@ title: Qualcomm Global Clock & Reset Controller on SDM670 and SDM845 maintainers: - Stephen Boyd <sboyd@kernel.org> - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm global clock control module provides the clocks, resets and power diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sm8150.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8150.yaml index 3ea0ff37a4cb..58ccb7df847c 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sm8150.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8150.yaml @@ -8,7 +8,7 @@ title: Qualcomm Global Clock & Reset Controller on SM8150 maintainers: - Stephen Boyd <sboyd@kernel.org> - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm global clock control module provides the clocks, resets and power diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sm8250.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8250.yaml index ead6665b9a45..5d77c092be5b 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sm8250.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8250.yaml @@ -8,7 +8,7 @@ title: Qualcomm Global Clock & Reset Controller on SM8250 maintainers: - Stephen Boyd <sboyd@kernel.org> - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm global clock control module provides the clocks, resets and power diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sm8450.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8450.yaml index 9a31981fbeb2..75259f468d54 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sm8450.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8450.yaml @@ -25,7 +25,7 @@ properties: - description: Sleep clock source - description: PCIE 0 Pipe clock source (Optional clock) - description: PCIE 1 Pipe clock source (Optional clock) - - description: PCIE 1 Phy Auxillary clock source (Optional clock) + - description: PCIE 1 Phy Auxiliary clock source (Optional clock) - description: UFS Phy Rx symbol 0 clock source (Optional clock) - description: UFS Phy Rx symbol 1 clock source (Optional clock) - description: UFS Phy Tx symbol 0 clock source (Optional clock) diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc.yaml index 7129fbcf2b6c..788825105f24 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc.yaml @@ -8,7 +8,7 @@ title: Qualcomm Global Clock & Reset Controller Common Properties maintainers: - Stephen Boyd <sboyd@kernel.org> - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Common bindings for Qualcomm global clock control module providing the diff --git a/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml b/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml index a00216b3b15a..f369fa34e00c 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Graphics Clock & Reset Controller maintainers: - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm graphics clock control module provides the clocks, resets and power diff --git a/Documentation/devicetree/bindings/clock/qcom,hfpll.txt b/Documentation/devicetree/bindings/clock/qcom,hfpll.txt index ec02a024424c..5769cbbe76be 100644 --- a/Documentation/devicetree/bindings/clock/qcom,hfpll.txt +++ b/Documentation/devicetree/bindings/clock/qcom,hfpll.txt @@ -12,6 +12,9 @@ PROPERTIES "qcom,hfpll-apq8064", "qcom,hfpll" "qcom,hfpll-msm8974", "qcom,hfpll" "qcom,hfpll-msm8960", "qcom,hfpll" + "qcom,msm8976-hfpll-a53", "qcom,hfpll" + "qcom,msm8976-hfpll-a72", "qcom,hfpll" + "qcom,msm8976-hfpll-cci", "qcom,hfpll" - reg: Usage: required diff --git a/Documentation/devicetree/bindings/clock/qcom,ipq5018-gcc.yaml b/Documentation/devicetree/bindings/clock/qcom,ipq5018-gcc.yaml new file mode 100644 index 000000000000..ef84a0c95f7e --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,ipq5018-gcc.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,ipq5018-gcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller on IPQ5018 + +maintainers: + - Sricharan Ramabadhran <quic_srichara@quicinc.com> + +description: | + Qualcomm global clock control module provides the clocks, resets and power + domains on IPQ5018 + + See also:: + include/dt-bindings/clock/qcom,ipq5018-gcc.h + include/dt-bindings/reset/qcom,ipq5018-gcc.h + +properties: + compatible: + const: qcom,gcc-ipq5018 + + clocks: + items: + - description: Board XO source + - description: Sleep clock source + - description: PCIE20 PHY0 pipe clock source + - description: PCIE20 PHY1 pipe clock source + - description: USB3 PHY pipe clock source + - description: GEPHY RX clock source + - description: GEPHY TX clock source + - description: UNIPHY RX clock source + - description: UNIPHY TX clk source + +required: + - compatible + - clocks + +allOf: + - $ref: qcom,gcc.yaml# + +unevaluatedProperties: false + +examples: + - | + clock-controller@1800000 { + compatible = "qcom,gcc-ipq5018"; + reg = <0x01800000 0x80000>; + clocks = <&xo_board_clk>, + <&sleep_clk>, + <&pcie20_phy0_pipe_clk>, + <&pcie20_phy1_pipe_clk>, + <&usb3_phy0_pipe_clk>, + <&gephy_rx_clk>, + <&gephy_tx_clk>, + <&uniphy_rx_clk>, + <&uniphy_tx_clk>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,kpss-acc-v1.yaml b/Documentation/devicetree/bindings/clock/qcom,kpss-acc-v1.yaml index a466e4e8aacd..57632757d4e6 100644 --- a/Documentation/devicetree/bindings/clock/qcom,kpss-acc-v1.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,kpss-acc-v1.yaml @@ -14,7 +14,7 @@ description: There is one ACC register region per CPU within the KPSS remapped region as well as an alias register region that remaps accesses to the ACC associated with the CPU accessing the region. ACC v1 is currently used as a - clock-controller for enabling the cpu and hanling the aux clocks. + clock-controller for enabling the cpu and handling the aux clocks. properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,lcc.yaml b/Documentation/devicetree/bindings/clock/qcom,lcc.yaml index 8c783823e93c..55985e562a34 100644 --- a/Documentation/devicetree/bindings/clock/qcom,lcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,lcc.yaml @@ -76,6 +76,40 @@ allOf: - clocks - clock-names + - if: + properties: + compatible: + contains: + enum: + - qcom,lcc-mdm9615 + then: + properties: + clocks: + items: + - description: Board CXO source + - description: PLL 4 Vote clock + - description: MI2S codec clock + - description: Mic I2S codec clock + - description: Mic I2S spare clock + - description: Speaker I2S codec clock + - description: Speaker I2S spare clock + - description: PCM codec clock + + clock-names: + items: + - const: cxo + - const: pll4_vote + - const: mi2s_codec_clk + - const: codec_i2s_mic_codec_clk + - const: spare_i2s_mic_codec_clk + - const: codec_i2s_spkr_codec_clk + - const: spare_i2s_spkr_codec_clk + - const: pcm_codec_clk + + required: + - clocks + - clock-names + examples: - | clock-controller@28000000 { diff --git a/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml b/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml index 422f5776a771..aa35a40648ba 100644 --- a/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml @@ -8,7 +8,7 @@ title: Qualcomm Multimedia Clock & Reset Controller maintainers: - Jeffrey Hugo <quic_jhugo@quicinc.com> - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm multimedia clock control module provides the clocks, resets and @@ -297,6 +297,7 @@ allOf: - description: HDMI phy PLL clock - description: DisplayPort phy PLL link clock - description: DisplayPort phy PLL vco clock + - description: Global PLL 0 DIV clock clock-names: items: @@ -309,6 +310,7 @@ allOf: - const: hdmipll - const: dplink - const: dpvco + - const: gpll0_div - if: properties: diff --git a/Documentation/devicetree/bindings/clock/qcom,msm8996-cbf.yaml b/Documentation/devicetree/bindings/clock/qcom,msm8996-cbf.yaml index 3ffe69d8cdd5..0dfbd8c4d465 100644 --- a/Documentation/devicetree/bindings/clock/qcom,msm8996-cbf.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,msm8996-cbf.yaml @@ -15,7 +15,9 @@ description: > properties: compatible: - const: qcom,msm8996-cbf + enum: + - qcom,msm8996-cbf + - qcom,msm8996pro-cbf reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/clock/qcom,msm8998-gpucc.yaml b/Documentation/devicetree/bindings/clock/qcom,msm8998-gpucc.yaml index 2d8897991663..7b271ae210a3 100644 --- a/Documentation/devicetree/bindings/clock/qcom,msm8998-gpucc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,msm8998-gpucc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Graphics Clock & Reset Controller on MSM8998 maintainers: - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm graphics clock control module provides the clocks, resets and power diff --git a/Documentation/devicetree/bindings/clock/qcom,qdu1000-gcc.yaml b/Documentation/devicetree/bindings/clock/qcom,qdu1000-gcc.yaml index 767a9d03aa32..d712b1a87e25 100644 --- a/Documentation/devicetree/bindings/clock/qcom,qdu1000-gcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,qdu1000-gcc.yaml @@ -7,7 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Global Clock & Reset Controller for QDU1000 and QRU1000 maintainers: - - Melody Olvera <quic_molvera@quicinc.com> + - Taniya Das <quic_tdas@quicinc.com> + - Imran Shaik <quic_imrashai@quicinc.com> description: | Qualcomm global clock control module which supports the clocks, resets and diff --git a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml index 267cf8c26823..4eb5e59f6772 100644 --- a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. RPMh Clocks maintainers: - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Resource Power Manager Hardened (RPMh) manages shared resources on @@ -28,6 +28,7 @@ properties: - qcom,sdx55-rpmh-clk - qcom,sdx65-rpmh-clk - qcom,sdx75-rpmh-clk + - qcom,sm4450-rpmh-clk - qcom,sm6350-rpmh-clk - qcom,sm8150-rpmh-clk - qcom,sm8250-rpmh-clk diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-camcc.yaml index 098c8acf4bad..2dfc2a4f1918 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7180-camcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7180-camcc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Camera Clock & Reset Controller on SC7180 maintainers: - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm camera clock control module provides the clocks, resets and power diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-dispcc.yaml index 95ad16d0abc3..1c9ce300a435 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7180-dispcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7180-dispcc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Display Clock & Reset Controller on SC7180 maintainers: - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm display clock control module provides the clocks, resets and power diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-lpasscorecc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-lpasscorecc.yaml index f297694ef8b8..fdfb389083c1 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7180-lpasscorecc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7180-lpasscorecc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm LPASS Core Clock Controller on SC7180 maintainers: - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm LPASS core clock control module provides the clocks and power diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-mss.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-mss.yaml index 1e856a8a996e..873a2f918bac 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7180-mss.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7180-mss.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Modem Clock Controller on SC7180 maintainers: - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm modem clock control module provides the clocks on SC7180. diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7280-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7280-camcc.yaml index b60adbad4590..01feef1cab0a 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7280-camcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7280-camcc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Camera Clock & Reset Controller on SC7280 maintainers: - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm camera clock control module provides the clocks, resets and diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7280-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7280-dispcc.yaml index cfe6594a0a6b..c42b0ef61385 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7280-dispcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7280-dispcc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Display Clock & Reset Controller on SC7280 maintainers: - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm display clock control module provides the clocks, resets and power diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscc.yaml index 97c6bd96e0cb..f44c5c130d2d 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm LPASS Core Clock Controller on SC7280 maintainers: - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm LPASS core clock control module provides the clocks and power diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscorecc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscorecc.yaml index 447cdc447a0c..deee5423d66e 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscorecc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscorecc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm LPASS Core & Audio Clock Controller on SC7280 maintainers: - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm LPASS core and audio clock control module provides the clocks and diff --git a/Documentation/devicetree/bindings/clock/qcom,sdm845-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sdm845-dispcc.yaml index 76b53ce64e40..719844d7ea11 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sdm845-dispcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sdm845-dispcc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Display Clock & Reset Controller on SDM845 maintainers: - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm display clock control module provides the clocks, resets and power diff --git a/Documentation/devicetree/bindings/clock/qcom,sm4450-gcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm4450-gcc.yaml new file mode 100644 index 000000000000..5953c8d92436 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sm4450-gcc.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sm4450-gcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller on SM4450 + +maintainers: + - Ajit Pandey <quic_ajipan@quicinc.com> + - Taniya Das <quic_tdas@quicinc.com> + +description: | + Qualcomm global clock control module provides the clocks, resets and power + domains on SM4450 + + See also:: include/dt-bindings/clock/qcom,sm4450-gcc.h + +properties: + compatible: + const: qcom,sm4450-gcc + + clocks: + items: + - description: Board XO source + - description: Sleep clock source + - description: UFS Phy Rx symbol 0 clock source + - description: UFS Phy Rx symbol 1 clock source + - description: UFS Phy Tx symbol 0 clock source + - description: USB3 Phy wrapper pipe clock source + +required: + - compatible + - clocks + +allOf: + - $ref: qcom,gcc.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@100000 { + compatible = "qcom,sm4450-gcc"; + reg = <0x00100000 0x001f4200>; + clocks = <&rpmhcc RPMH_CXO_CLK>, <&sleep_clk>, + <&ufs_mem_phy 0>, <&ufs_mem_phy 1>, + <&ufs_mem_phy 2>, <&usb_1_qmpphy>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8350-videocc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8350-videocc.yaml index 23505c8c3dbd..46d1d91e3a01 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm8350-videocc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm8350-videocc.yaml @@ -19,7 +19,9 @@ description: | properties: compatible: - const: qcom,sm8350-videocc + enum: + - qcom,sc8280xp-videocc + - qcom,sm8350-videocc clocks: items: @@ -51,7 +53,7 @@ unevaluatedProperties: false examples: - | #include <dt-bindings/clock/qcom,rpmh.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> clock-controller@abf0000 { compatible = "qcom,sm8350-videocc"; @@ -59,7 +61,7 @@ examples: clocks = <&rpmhcc RPMH_CXO_CLK>, <&rpmhcc RPMH_CXO_CLK_A>, <&sleep_clk>; - power-domains = <&rpmhpd SM8350_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; required-opps = <&rpmhpd_opp_low_svs>; #clock-cells = <1>; #reset-cells = <1>; diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml index 87ae74166807..dc3c18e4ead7 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml @@ -13,11 +13,15 @@ description: | Qualcomm camera clock control module provides the clocks, resets and power domains on SM8450. - See also:: include/dt-bindings/clock/qcom,sm8450-camcc.h + See also:: + include/dt-bindings/clock/qcom,sm8450-camcc.h + include/dt-bindings/clock/qcom,sm8550-camcc.h properties: compatible: - const: qcom,sm8450-camcc + enum: + - qcom,sm8450-camcc + - qcom,sm8550-camcc clocks: items: @@ -64,7 +68,7 @@ examples: - | #include <dt-bindings/clock/qcom,gcc-sm8450.h> #include <dt-bindings/clock/qcom,rpmh.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> clock-controller@ade0000 { compatible = "qcom,sm8450-camcc"; reg = <0xade0000 0x20000>; @@ -72,7 +76,7 @@ examples: <&rpmhcc RPMH_CXO_CLK>, <&rpmhcc RPMH_CXO_CLK_A>, <&sleep_clk>; - power-domains = <&rpmhpd SM8450_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; required-opps = <&rpmhpd_opp_low_svs>; #clock-cells = <1>; #reset-cells = <1>; diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8450-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8450-dispcc.yaml index 1dd1f696dcd3..2f22310b08a9 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm8450-dispcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm8450-dispcc.yaml @@ -76,7 +76,7 @@ examples: - | #include <dt-bindings/clock/qcom,gcc-sm8450.h> #include <dt-bindings/clock/qcom,rpmh.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> clock-controller@af00000 { compatible = "qcom,sm8450-dispcc"; reg = <0x0af00000 0x10000>; @@ -91,7 +91,7 @@ examples: #clock-cells = <1>; #reset-cells = <1>; #power-domain-cells = <1>; - power-domains = <&rpmhpd SM8450_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; required-opps = <&rpmhpd_opp_low_svs>; }; ... diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8450-videocc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8450-videocc.yaml index f1c6dd50f184..bad8f019a8d3 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm8450-videocc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm8450-videocc.yaml @@ -64,13 +64,13 @@ examples: - | #include <dt-bindings/clock/qcom,gcc-sm8450.h> #include <dt-bindings/clock/qcom,rpmh.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> videocc: clock-controller@aaf0000 { compatible = "qcom,sm8450-videocc"; reg = <0x0aaf0000 0x10000>; clocks = <&rpmhcc RPMH_CXO_CLK>, <&gcc GCC_VIDEO_AHB_CLK>; - power-domains = <&rpmhpd SM8450_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; required-opps = <&rpmhpd_opp_low_svs>; #clock-cells = <1>; #reset-cells = <1>; diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8550-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8550-dispcc.yaml index ab25f7cbaa2e..c129f8c16b50 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm8550-dispcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm8550-dispcc.yaml @@ -76,7 +76,7 @@ examples: - | #include <dt-bindings/clock/qcom,sm8550-gcc.h> #include <dt-bindings/clock/qcom,rpmh.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> clock-controller@af00000 { compatible = "qcom,sm8550-dispcc"; reg = <0x0af00000 0x10000>; @@ -99,7 +99,7 @@ examples: #clock-cells = <1>; #reset-cells = <1>; #power-domain-cells = <1>; - power-domains = <&rpmhpd SM8550_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; required-opps = <&rpmhpd_opp_low_svs>; }; ... diff --git a/Documentation/devicetree/bindings/clock/qcom,videocc.yaml b/Documentation/devicetree/bindings/clock/qcom,videocc.yaml index 2b07146161b4..6999e36ace1b 100644 --- a/Documentation/devicetree/bindings/clock/qcom,videocc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,videocc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Video Clock & Reset Controller maintainers: - - Taniya Das <tdas@codeaurora.org> + - Taniya Das <quic_tdas@quicinc.com> description: | Qualcomm video clock control module provides the clocks, resets and power @@ -124,7 +124,7 @@ additionalProperties: false examples: - | #include <dt-bindings/clock/qcom,rpmh.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> clock-controller@ab00000 { compatible = "qcom,sdm845-videocc"; reg = <0x0ab00000 0x10000>; @@ -133,7 +133,7 @@ examples: #clock-cells = <1>; #reset-cells = <1>; #power-domain-cells = <1>; - power-domains = <&rpmhpd SM8250_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; required-opps = <&rpmhpd_opp_low_svs>; }; ... diff --git a/Documentation/devicetree/bindings/clock/renesas,5p35023.yaml b/Documentation/devicetree/bindings/clock/renesas,5p35023.yaml new file mode 100644 index 000000000000..42b6f80613f3 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/renesas,5p35023.yaml @@ -0,0 +1,89 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/renesas,5p35023.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas 5p35023 VersaClock 3 programmable I2C clock generator + +maintainers: + - Biju Das <biju.das.jz@bp.renesas.com> + +description: | + The 5P35023 is a VersaClock programmable clock generator and + is designed for low-power, consumer, and high-performance PCI + express applications. The 5P35023 device is a three PLL + architecture design, and each PLL is individually programmable + and allowing for up to 6 unique frequency outputs. + + An internal OTP memory allows the user to store the configuration + in the device. After power up, the user can change the device register + settings through the I2C interface when I2C mode is selected. + + The driver can read a full register map from the DT, and will use that + register map to initialize the attached part (via I2C) when the system + boots. Any configuration not supported by the common clock framework + must be done via the full register map, including optimized settings. + + Link to datasheet: + https://www.renesas.com/us/en/products/clocks-timing/clock-generation/programmable-clocks/5p35023-versaclock-3s-programmable-clock-generator + +properties: + compatible: + enum: + - renesas,5p35023 + + reg: + maxItems: 1 + + '#clock-cells': + description: + The index in the assigned-clocks is mapped to the output clock as below + 0 - REF, 1 - SE1, 2 - SE2, 3 - SE3, 4 - DIFF1, 5 - DIFF2. + const: 1 + + clocks: + maxItems: 1 + + renesas,settings: + description: Optional, complete register map of the device. + Optimized settings for the device must be provided in full + and are written during initialization. + $ref: /schemas/types.yaml#/definitions/uint8-array + maxItems: 37 + +required: + - compatible + - reg + - '#clock-cells' + - clocks + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + versa3: clock-generator@68 { + compatible = "renesas,5p35023"; + reg = <0x68>; + #clock-cells = <1>; + + clocks = <&x1>; + + renesas,settings = [ + 80 00 11 19 4c 02 23 7f 83 19 08 a9 5f 25 24 bf + 00 14 7a e1 00 00 00 00 01 55 59 bb 3f 30 90 b6 + 80 b0 45 c4 95 + ]; + + assigned-clocks = <&versa3 0>, <&versa3 1>, + <&versa3 2>, <&versa3 3>, + <&versa3 4>, <&versa3 5>; + assigned-clock-rates = <24000000>, <11289600>, + <11289600>, <12000000>, + <25000000>, <12288000>; + }; + }; diff --git a/Documentation/devicetree/bindings/clock/renesas,rzg2l-cpg.yaml b/Documentation/devicetree/bindings/clock/renesas,rzg2l-cpg.yaml index fe2fba18ae84..80a8c7114c31 100644 --- a/Documentation/devicetree/bindings/clock/renesas,rzg2l-cpg.yaml +++ b/Documentation/devicetree/bindings/clock/renesas,rzg2l-cpg.yaml @@ -27,6 +27,7 @@ properties: - renesas,r9a07g043-cpg # RZ/G2UL{Type-1,Type-2} and RZ/Five - renesas,r9a07g044-cpg # RZ/G2{L,LC} - renesas,r9a07g054-cpg # RZ/V2L + - renesas,r9a08g045-cpg # RZ/G3S - renesas,r9a09g011-cpg # RZ/V2M reg: diff --git a/Documentation/devicetree/bindings/clock/sprd,sc9863a-clk.yaml b/Documentation/devicetree/bindings/clock/sprd,sc9863a-clk.yaml index 1703e305e6d8..a0658056c330 100644 --- a/Documentation/devicetree/bindings/clock/sprd,sc9863a-clk.yaml +++ b/Documentation/devicetree/bindings/clock/sprd,sc9863a-clk.yaml @@ -66,7 +66,7 @@ then: else: description: | Other SC9863a clock nodes should be the child of a syscon node in - which compatible string shoule be: + which compatible string should be: "sprd,sc9863a-glbregs", "syscon", "simple-mfd" The 'reg' property for the clock node is also required if there is a sub diff --git a/Documentation/devicetree/bindings/clock/starfive,jh7110-ispcrg.yaml b/Documentation/devicetree/bindings/clock/starfive,jh7110-ispcrg.yaml new file mode 100644 index 000000000000..3b8b85be5cd0 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/starfive,jh7110-ispcrg.yaml @@ -0,0 +1,87 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/starfive,jh7110-ispcrg.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive JH7110 Image-Signal-Process Clock and Reset Generator + +maintainers: + - Xingyu Wu <xingyu.wu@starfivetech.com> + +properties: + compatible: + const: starfive,jh7110-ispcrg + + reg: + maxItems: 1 + + clocks: + items: + - description: ISP Top core + - description: ISP Top Axi + - description: NOC ISP Bus + - description: external DVP + + clock-names: + items: + - const: isp_top_core + - const: isp_top_axi + - const: noc_bus_isp_axi + - const: dvp_clk + + resets: + items: + - description: ISP Top core + - description: ISP Top Axi + - description: NOC ISP Bus + + '#clock-cells': + const: 1 + description: + See <dt-bindings/clock/starfive,jh7110-crg.h> for valid indices. + + '#reset-cells': + const: 1 + description: + See <dt-bindings/reset/starfive,jh7110-crg.h> for valid indices. + + power-domains: + maxItems: 1 + description: + ISP domain power + +required: + - compatible + - reg + - clocks + - clock-names + - resets + - '#clock-cells' + - '#reset-cells' + - power-domains + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/starfive,jh7110-crg.h> + #include <dt-bindings/power/starfive,jh7110-pmu.h> + #include <dt-bindings/reset/starfive,jh7110-crg.h> + + ispcrg: clock-controller@19810000 { + compatible = "starfive,jh7110-ispcrg"; + reg = <0x19810000 0x10000>; + clocks = <&syscrg JH7110_SYSCLK_ISP_TOP_CORE>, + <&syscrg JH7110_SYSCLK_ISP_TOP_AXI>, + <&syscrg JH7110_SYSCLK_NOC_BUS_ISP_AXI>, + <&dvp_clk>; + clock-names = "isp_top_core", "isp_top_axi", + "noc_bus_isp_axi", "dvp_clk"; + resets = <&syscrg JH7110_SYSRST_ISP_TOP>, + <&syscrg JH7110_SYSRST_ISP_TOP_AXI>, + <&syscrg JH7110_SYSRST_NOC_BUS_ISP_AXI>; + #clock-cells = <1>; + #reset-cells = <1>; + power-domains = <&pwrc JH7110_PD_ISP>; + }; diff --git a/Documentation/devicetree/bindings/clock/starfive,jh7110-pll.yaml b/Documentation/devicetree/bindings/clock/starfive,jh7110-pll.yaml new file mode 100644 index 000000000000..be8300ce86d0 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/starfive,jh7110-pll.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/starfive,jh7110-pll.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive JH7110 PLL Clock Generator + +description: + These PLLs are high speed, low jitter frequency synthesizers in the JH7110. + Each PLL works in integer mode or fraction mode, with configuration + registers in the sys syscon. So the PLLs node should be a child of + SYS-SYSCON node. + The formula for calculating frequency is + Fvco = Fref * (NI + NF) / M / Q1 + +maintainers: + - Xingyu Wu <xingyu.wu@starfivetech.com> + +properties: + compatible: + const: starfive,jh7110-pll + + clocks: + maxItems: 1 + description: Main Oscillator (24 MHz) + + '#clock-cells': + const: 1 + description: + See <dt-bindings/clock/starfive,jh7110-crg.h> for valid indices. + +required: + - compatible + - clocks + - '#clock-cells' + +additionalProperties: false + +examples: + - | + clock-controller { + compatible = "starfive,jh7110-pll"; + clocks = <&osc>; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/starfive,jh7110-stgcrg.yaml b/Documentation/devicetree/bindings/clock/starfive,jh7110-stgcrg.yaml new file mode 100644 index 000000000000..b64ccd84200a --- /dev/null +++ b/Documentation/devicetree/bindings/clock/starfive,jh7110-stgcrg.yaml @@ -0,0 +1,82 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/starfive,jh7110-stgcrg.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive JH7110 System-Top-Group Clock and Reset Generator + +maintainers: + - Xingyu Wu <xingyu.wu@starfivetech.com> + +properties: + compatible: + const: starfive,jh7110-stgcrg + + reg: + maxItems: 1 + + clocks: + items: + - description: Main Oscillator (24 MHz) + - description: HIFI4 core + - description: STG AXI/AHB + - description: USB (125 MHz) + - description: CPU Bus + - description: HIFI4 Axi + - description: NOC STG Bus + - description: APB Bus + + clock-names: + items: + - const: osc + - const: hifi4_core + - const: stg_axiahb + - const: usb_125m + - const: cpu_bus + - const: hifi4_axi + - const: nocstg_bus + - const: apb_bus + + '#clock-cells': + const: 1 + description: + See <dt-bindings/clock/starfive,jh7110-crg.h> for valid indices. + + '#reset-cells': + const: 1 + description: + See <dt-bindings/reset/starfive,jh7110-crg.h> for valid indices. + +required: + - compatible + - reg + - clocks + - clock-names + - '#clock-cells' + - '#reset-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/starfive,jh7110-crg.h> + + stgcrg: clock-controller@10230000 { + compatible = "starfive,jh7110-stgcrg"; + reg = <0x10230000 0x10000>; + clocks = <&osc>, + <&syscrg JH7110_SYSCLK_HIFI4_CORE>, + <&syscrg JH7110_SYSCLK_STG_AXIAHB>, + <&syscrg JH7110_SYSCLK_USB_125M>, + <&syscrg JH7110_SYSCLK_CPU_BUS>, + <&syscrg JH7110_SYSCLK_HIFI4_AXI>, + <&syscrg JH7110_SYSCLK_NOCSTG_BUS>, + <&syscrg JH7110_SYSCLK_APB_BUS>; + clock-names = "osc", "hifi4_core", + "stg_axiahb", "usb_125m", + "cpu_bus", "hifi4_axi", + "nocstg_bus", "apb_bus"; + #clock-cells = <1>; + #reset-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/starfive,jh7110-syscrg.yaml b/Documentation/devicetree/bindings/clock/starfive,jh7110-syscrg.yaml index 84373ae31644..5ba0a885aa80 100644 --- a/Documentation/devicetree/bindings/clock/starfive,jh7110-syscrg.yaml +++ b/Documentation/devicetree/bindings/clock/starfive,jh7110-syscrg.yaml @@ -27,6 +27,9 @@ properties: - description: External I2S RX left/right channel clock - description: External TDM clock - description: External audio master clock + - description: PLL0 + - description: PLL1 + - description: PLL2 - items: - description: Main Oscillator (24 MHz) @@ -38,6 +41,9 @@ properties: - description: External I2S RX left/right channel clock - description: External TDM clock - description: External audio master clock + - description: PLL0 + - description: PLL1 + - description: PLL2 clock-names: oneOf: @@ -52,6 +58,9 @@ properties: - const: i2srx_lrck_ext - const: tdm_ext - const: mclk_ext + - const: pll0_out + - const: pll1_out + - const: pll2_out - items: - const: osc @@ -63,6 +72,9 @@ properties: - const: i2srx_lrck_ext - const: tdm_ext - const: mclk_ext + - const: pll0_out + - const: pll1_out + - const: pll2_out '#clock-cells': const: 1 @@ -93,12 +105,14 @@ examples: <&gmac1_rgmii_rxin>, <&i2stx_bclk_ext>, <&i2stx_lrck_ext>, <&i2srx_bclk_ext>, <&i2srx_lrck_ext>, - <&tdm_ext>, <&mclk_ext>; + <&tdm_ext>, <&mclk_ext>, + <&pllclk 0>, <&pllclk 1>, <&pllclk 2>; clock-names = "osc", "gmac1_rmii_refin", "gmac1_rgmii_rxin", "i2stx_bclk_ext", "i2stx_lrck_ext", "i2srx_bclk_ext", "i2srx_lrck_ext", - "tdm_ext", "mclk_ext"; + "tdm_ext", "mclk_ext", + "pll0_out", "pll1_out", "pll2_out"; #clock-cells = <1>; #reset-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/clock/starfive,jh7110-voutcrg.yaml b/Documentation/devicetree/bindings/clock/starfive,jh7110-voutcrg.yaml new file mode 100644 index 000000000000..af77bd8c86b1 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/starfive,jh7110-voutcrg.yaml @@ -0,0 +1,90 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/starfive,jh7110-voutcrg.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive JH7110 Video-Output Clock and Reset Generator + +maintainers: + - Xingyu Wu <xingyu.wu@starfivetech.com> + +properties: + compatible: + const: starfive,jh7110-voutcrg + + reg: + maxItems: 1 + + clocks: + items: + - description: Vout Top core + - description: Vout Top Ahb + - description: Vout Top Axi + - description: Vout Top HDMI MCLK + - description: I2STX0 BCLK + - description: external HDMI pixel + + clock-names: + items: + - const: vout_src + - const: vout_top_ahb + - const: vout_top_axi + - const: vout_top_hdmitx0_mclk + - const: i2stx0_bclk + - const: hdmitx0_pixelclk + + resets: + maxItems: 1 + description: Vout Top core + + '#clock-cells': + const: 1 + description: + See <dt-bindings/clock/starfive,jh7110-crg.h> for valid indices. + + '#reset-cells': + const: 1 + description: + See <dt-bindings/reset/starfive,jh7110-crg.h> for valid indices. + + power-domains: + maxItems: 1 + description: + Vout domain power + +required: + - compatible + - reg + - clocks + - clock-names + - resets + - '#clock-cells' + - '#reset-cells' + - power-domains + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/starfive,jh7110-crg.h> + #include <dt-bindings/power/starfive,jh7110-pmu.h> + #include <dt-bindings/reset/starfive,jh7110-crg.h> + + voutcrg: clock-controller@295C0000 { + compatible = "starfive,jh7110-voutcrg"; + reg = <0x295C0000 0x10000>; + clocks = <&syscrg JH7110_SYSCLK_VOUT_SRC>, + <&syscrg JH7110_SYSCLK_VOUT_TOP_AHB>, + <&syscrg JH7110_SYSCLK_VOUT_TOP_AXI>, + <&syscrg JH7110_SYSCLK_VOUT_TOP_HDMITX0_MCLK>, + <&syscrg JH7110_SYSCLK_I2STX0_BCLK>, + <&hdmitx0_pixelclk>; + clock-names = "vout_src", "vout_top_ahb", + "vout_top_axi", "vout_top_hdmitx0_mclk", + "i2stx0_bclk", "hdmitx0_pixelclk"; + resets = <&syscrg JH7110_SYSRST_VOUT_TOP_SRC>; + #clock-cells = <1>; + #reset-cells = <1>; + power-domains = <&pwrc JH7110_PD_VOUT>; + }; diff --git a/Documentation/devicetree/bindings/clock/ti,cdce925.yaml b/Documentation/devicetree/bindings/clock/ti,cdce925.yaml index a4ec8dd5ddf1..95c1c6f8b755 100644 --- a/Documentation/devicetree/bindings/clock/ti,cdce925.yaml +++ b/Documentation/devicetree/bindings/clock/ti,cdce925.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/clock/ti,cdce925.yaml# diff --git a/Documentation/devicetree/bindings/clock/ti,sci-clk.yaml b/Documentation/devicetree/bindings/clock/ti,sci-clk.yaml index 63d976341696..0a9d6a4c4b66 100644 --- a/Documentation/devicetree/bindings/clock/ti,sci-clk.yaml +++ b/Documentation/devicetree/bindings/clock/ti,sci-clk.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/clock/ti,sci-clk.yaml# diff --git a/Documentation/devicetree/bindings/clock/ti/mux.txt b/Documentation/devicetree/bindings/clock/ti/mux.txt index e17425a58621..b33f641f1043 100644 --- a/Documentation/devicetree/bindings/clock/ti/mux.txt +++ b/Documentation/devicetree/bindings/clock/ti/mux.txt @@ -8,7 +8,7 @@ parents, one of which can be selected as output. This clock does not gate or adjust the parent rate via a divider or multiplier. By default the "clocks" property lists the parents in the same order -as they are programmed into the regster. E.g: +as they are programmed into the register. E.g: clocks = <&foo_clock>, <&bar_clock>, <&baz_clock>; diff --git a/Documentation/devicetree/bindings/clock/vf610-clock.txt b/Documentation/devicetree/bindings/clock/vf610-clock.txt index 63f9f1ac3439..109ffa3a5b66 100644 --- a/Documentation/devicetree/bindings/clock/vf610-clock.txt +++ b/Documentation/devicetree/bindings/clock/vf610-clock.txt @@ -9,7 +9,7 @@ Optional properties: - clocks: list of clock identifiers which are external input clocks to the given clock controller. Please refer the next section to find the input clocks for a given controller. -- clock-names: list of names of clocks which are exteral input clocks to the +- clock-names: list of names of clocks which are external input clocks to the given clock controller. Input clocks for top clock controller: diff --git a/Documentation/devicetree/bindings/clock/xlnx,versal-clk.yaml b/Documentation/devicetree/bindings/clock/xlnx,versal-clk.yaml index 5cbb34d0b61b..1ba687d433b1 100644 --- a/Documentation/devicetree/bindings/clock/xlnx,versal-clk.yaml +++ b/Documentation/devicetree/bindings/clock/xlnx,versal-clk.yaml @@ -14,11 +14,16 @@ description: | reads required input clock frequencies from the devicetree and acts as clock provider for all clock consumers of PS clocks. -select: false - properties: compatible: - const: xlnx,versal-clk + oneOf: + - enum: + - xlnx,versal-clk + - xlnx,zynqmp-clk + - items: + - enum: + - xlnx,versal-net-clk + - const: xlnx,versal-clk "#clock-cells": const: 1 @@ -26,16 +31,12 @@ properties: clocks: description: List of clock specifiers which are external input clocks to the given clock controller. - items: - - description: reference clock - - description: alternate reference clock - - description: alternate reference clock for programmable logic + minItems: 3 + maxItems: 8 clock-names: - items: - - const: ref - - const: alt_ref - - const: pl_alt_ref + minItems: 3 + maxItems: 8 required: - compatible @@ -45,6 +46,61 @@ required: additionalProperties: false +allOf: + - if: + properties: + compatible: + contains: + enum: + - xlnx,versal-clk + + then: + properties: + clocks: + items: + - description: reference clock + - description: alternate reference clock + - description: alternate reference clock for programmable logic + + clock-names: + items: + - const: ref + - const: alt_ref + - const: pl_alt_ref + + - if: + properties: + compatible: + contains: + enum: + - xlnx,zynqmp-clk + + then: + properties: + clocks: + minItems: 5 + items: + - description: PS reference clock + - description: reference clock for video system + - description: alternative PS reference clock + - description: auxiliary reference clock + - description: transceiver reference clock + - description: (E)MIO clock source (Optional clock) + - description: GEM emio clock (Optional clock) + - description: Watchdog external clock (Optional clock) + + clock-names: + minItems: 5 + items: + - const: pss_ref_clk + - const: video_clk + - const: pss_alt_ref_clk + - const: aux_ref_clk + - const: gt_crx_ref_clk + - pattern: "^mio_clk[00-77]+.*$" + - pattern: "gem[0-3]+_emio_clk.*$" + - pattern: "swdt[0-1]+_ext_clk.*$" + examples: - | firmware { @@ -59,4 +115,13 @@ examples: }; }; }; + + clock-controller { + #clock-cells = <1>; + compatible = "xlnx,zynqmp-clk"; + clocks = <&pss_ref_clk>, <&video_clk>, <&pss_alt_ref_clk>, + <&aux_ref_clk>, <>_crx_ref_clk>; + clock-names = "pss_ref_clk", "video_clk", "pss_alt_ref_clk", + "aux_ref_clk", "gt_crx_ref_clk"; + }; ... diff --git a/Documentation/devicetree/bindings/clock/xlnx,zynqmp-clk.txt b/Documentation/devicetree/bindings/clock/xlnx,zynqmp-clk.txt deleted file mode 100644 index 391ee1a60bed..000000000000 --- a/Documentation/devicetree/bindings/clock/xlnx,zynqmp-clk.txt +++ /dev/null @@ -1,63 +0,0 @@ --------------------------------------------------------------------------- -Device Tree Clock bindings for the Zynq Ultrascale+ MPSoC controlled using -Zynq MPSoC firmware interface --------------------------------------------------------------------------- -The clock controller is a h/w block of Zynq Ultrascale+ MPSoC clock -tree. It reads required input clock frequencies from the devicetree and acts -as clock provider for all clock consumers of PS clocks. - -See clock_bindings.txt for more information on the generic clock bindings. - -Required properties: - - #clock-cells: Must be 1 - - compatible: Must contain: "xlnx,zynqmp-clk" - - clocks: List of clock specifiers which are external input - clocks to the given clock controller. Please refer - the next section to find the input clocks for a - given controller. - - clock-names: List of clock names which are exteral input clocks - to the given clock controller. Please refer to the - clock bindings for more details. - -Input clocks for zynqmp Ultrascale+ clock controller: - -The Zynq UltraScale+ MPSoC has one primary and four alternative reference clock -inputs. These required clock inputs are: - - pss_ref_clk (PS reference clock) - - video_clk (reference clock for video system ) - - pss_alt_ref_clk (alternative PS reference clock) - - aux_ref_clk - - gt_crx_ref_clk (transceiver reference clock) - -The following strings are optional parameters to the 'clock-names' property in -order to provide an optional (E)MIO clock source: - - swdt0_ext_clk - - swdt1_ext_clk - - gem0_emio_clk - - gem1_emio_clk - - gem2_emio_clk - - gem3_emio_clk - - mio_clk_XX # with XX = 00..77 - - mio_clk_50_or_51 #for the mux clock to gem tsu from 50 or 51 - - -Output clocks are registered based on clock information received -from firmware. Output clocks indexes are mentioned in -include/dt-bindings/clock/xlnx-zynqmp-clk.h. - -------- -Example -------- - -firmware { - zynqmp_firmware: zynqmp-firmware { - compatible = "xlnx,zynqmp-firmware"; - method = "smc"; - zynqmp_clk: clock-controller { - #clock-cells = <1>; - compatible = "xlnx,zynqmp-clk"; - clocks = <&pss_ref_clk>, <&video_clk>, <&pss_alt_ref_clk>, <&aux_ref_clk>, <>_crx_ref_clk>; - clock-names = "pss_ref_clk", "video_clk", "pss_alt_ref_clk","aux_ref_clk", "gt_crx_ref_clk"; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml index 1c4d3eb87763..7c8a3e8430d3 100644 --- a/Documentation/devicetree/bindings/connector/usb-connector.yaml +++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml @@ -30,6 +30,9 @@ properties: - const: samsung,usb-connector-11pin - const: usb-b-connector + reg: + maxItems: 1 + label: description: Symbolic name for the connector. @@ -224,13 +227,13 @@ properties: state as defined in 7.4.2 Sink Electrical Parameters of USB Power Delivery Specification Revision 3.0, Version 1.2. When the property is set, the port requests pSnkStby(2.5W - 5V@500mA) upon entering SNK_DISCOVERY(instead of 3A or the 1.5A, Rp current advertised, during - SNK_DISCOVERY) and the actual currrent limit after reception of PS_Ready for PD link or during + SNK_DISCOVERY) and the actual current limit after reception of PS_Ready for PD link or during SNK_READY for non-pd link. type: boolean dependencies: - sink-vdos-v1: [ 'sink-vdos' ] - sink-vdos: [ 'sink-vdos-v1' ] + sink-vdos-v1: [ sink-vdos ] + sink-vdos: [ sink-vdos-v1 ] required: - compatible @@ -264,7 +267,7 @@ anyOf: - typec-power-opmode - new-source-frs-typec-current -additionalProperties: true +additionalProperties: false examples: # Micro-USB connector with HS lines routed via controller (MUIC). diff --git a/Documentation/devicetree/bindings/cpu/nvidia,tegra186-ccplex-cluster.yaml b/Documentation/devicetree/bindings/cpu/nvidia,tegra186-ccplex-cluster.yaml new file mode 100644 index 000000000000..16a448974561 --- /dev/null +++ b/Documentation/devicetree/bindings/cpu/nvidia,tegra186-ccplex-cluster.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/cpu/nvidia,tegra186-ccplex-cluster.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra186 CCPLEX Cluster + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + const: nvidia,tegra186-ccplex-cluster + + reg: + maxItems: 1 + + nvidia,bpmp: + description: phandle to the BPMP used to query CPU frequency tables + $ref: /schemas/types.yaml#/definitions/phandle + +additionalProperties: false + +required: + - compatible + - reg + - nvidia,bpmp + +examples: + - | + ccplex@e000000 { + compatible = "nvidia,tegra186-ccplex-cluster"; + reg = <0x0e000000 0x400000>; + nvidia,bpmp = <&bpmp>; + }; diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml b/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml index a6b3bb8fdf33..56fc71d6a081 100644 --- a/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml @@ -23,6 +23,7 @@ properties: - enum: - qcom,qcm2290-cpufreq-hw - qcom,sc7180-cpufreq-hw + - qcom,sdm670-cpufreq-hw - qcom,sdm845-cpufreq-hw - qcom,sm6115-cpufreq-hw - qcom,sm6350-cpufreq-hw @@ -36,11 +37,13 @@ properties: - qcom,sa8775p-cpufreq-epss - qcom,sc7280-cpufreq-epss - qcom,sc8280xp-cpufreq-epss + - qcom,sdx75-cpufreq-epss - qcom,sm6375-cpufreq-epss - qcom,sm8250-cpufreq-epss - qcom,sm8350-cpufreq-epss - qcom,sm8450-cpufreq-epss - qcom,sm8550-cpufreq-epss + - qcom,sm8650-cpufreq-epss - const: qcom,cpufreq-epss reg: @@ -49,6 +52,7 @@ properties: - description: Frequency domain 0 register region - description: Frequency domain 1 register region - description: Frequency domain 2 register region + - description: Frequency domain 3 register region reg-names: minItems: 1 @@ -56,6 +60,7 @@ properties: - const: freq-domain0 - const: freq-domain1 - const: freq-domain2 + - const: freq-domain3 clocks: items: @@ -69,7 +74,7 @@ properties: interrupts: minItems: 1 - maxItems: 3 + maxItems: 4 interrupt-names: minItems: 1 @@ -77,6 +82,7 @@ properties: - const: dcvsh-irq-0 - const: dcvsh-irq-1 - const: dcvsh-irq-2 + - const: dcvsh-irq-3 '#freq-domain-cells': const: 1 @@ -125,6 +131,7 @@ allOf: - qcom,qdu1000-cpufreq-epss - qcom,sc7180-cpufreq-hw - qcom,sc8280xp-cpufreq-epss + - qcom,sdm670-cpufreq-hw - qcom,sdm845-cpufreq-hw - qcom,sm6115-cpufreq-hw - qcom,sm6350-cpufreq-hw diff --git a/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml b/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml index 7e1bb992ce90..547265b8b118 100644 --- a/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml +++ b/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml @@ -27,8 +27,12 @@ select: enum: - qcom,apq8064 - qcom,apq8096 + - qcom,ipq5332 + - qcom,ipq6018 - qcom,ipq8064 - qcom,ipq8074 + - qcom,ipq9574 + - qcom,msm8909 - qcom,msm8939 - qcom,msm8960 - qcom,msm8974 @@ -43,7 +47,9 @@ patternProperties: - if: properties: compatible: - const: operating-points-v2-kryo-cpu + enum: + - operating-points-v2-krait-cpu + - operating-points-v2-kryo-cpu then: $ref: /schemas/opp/opp-v2-kryo-cpu.yaml# diff --git a/Documentation/devicetree/bindings/cpufreq/ti-cpufreq.txt b/Documentation/devicetree/bindings/cpufreq/ti-cpufreq.txt deleted file mode 100644 index 1758051798fe..000000000000 --- a/Documentation/devicetree/bindings/cpufreq/ti-cpufreq.txt +++ /dev/null @@ -1,132 +0,0 @@ -TI CPUFreq and OPP bindings -================================ - -Certain TI SoCs, like those in the am335x, am437x, am57xx, and dra7xx -families support different OPPs depending on the silicon variant in use. -The ti-cpufreq driver can use revision and an efuse value from the SoC to -provide the OPP framework with supported hardware information. This is -used to determine which OPPs from the operating-points-v2 table get enabled -when it is parsed by the OPP framework. - -Required properties: --------------------- -In 'cpus' nodes: -- operating-points-v2: Phandle to the operating-points-v2 table to use. - -In 'operating-points-v2' table: -- compatible: Should be - - 'operating-points-v2-ti-cpu' for am335x, am43xx, and dra7xx/am57xx, - omap34xx, omap36xx and am3517 SoCs -- syscon: A phandle pointing to a syscon node representing the control module - register space of the SoC. - -Optional properties: --------------------- -- "vdd-supply", "vbb-supply": to define two regulators for dra7xx -- "cpu0-supply", "vbb-supply": to define two regulators for omap36xx - -For each opp entry in 'operating-points-v2' table: -- opp-supported-hw: Two bitfields indicating: - 1. Which revision of the SoC the OPP is supported by - 2. Which eFuse bits indicate this OPP is available - - A bitwise AND is performed against these values and if any bit - matches, the OPP gets enabled. - -Example: --------- - -/* From arch/arm/boot/dts/am33xx.dtsi */ -cpus { - #address-cells = <1>; - #size-cells = <0>; - cpu@0 { - compatible = "arm,cortex-a8"; - device_type = "cpu"; - reg = <0>; - - operating-points-v2 = <&cpu0_opp_table>; - - clocks = <&dpll_mpu_ck>; - clock-names = "cpu"; - - clock-latency = <300000>; /* From omap-cpufreq driver */ - }; -}; - -/* - * cpu0 has different OPPs depending on SoC revision and some on revisions - * 0x2 and 0x4 have eFuse bits that indicate if they are available or not - */ -cpu0_opp_table: opp-table { - compatible = "operating-points-v2-ti-cpu"; - syscon = <&scm_conf>; - - /* - * The three following nodes are marked with opp-suspend - * because they can not be enabled simultaneously on a - * single SoC. - */ - opp50-300000000 { - opp-hz = /bits/ 64 <300000000>; - opp-microvolt = <950000 931000 969000>; - opp-supported-hw = <0x06 0x0010>; - opp-suspend; - }; - - opp100-275000000 { - opp-hz = /bits/ 64 <275000000>; - opp-microvolt = <1100000 1078000 1122000>; - opp-supported-hw = <0x01 0x00FF>; - opp-suspend; - }; - - opp100-300000000 { - opp-hz = /bits/ 64 <300000000>; - opp-microvolt = <1100000 1078000 1122000>; - opp-supported-hw = <0x06 0x0020>; - opp-suspend; - }; - - opp100-500000000 { - opp-hz = /bits/ 64 <500000000>; - opp-microvolt = <1100000 1078000 1122000>; - opp-supported-hw = <0x01 0xFFFF>; - }; - - opp100-600000000 { - opp-hz = /bits/ 64 <600000000>; - opp-microvolt = <1100000 1078000 1122000>; - opp-supported-hw = <0x06 0x0040>; - }; - - opp120-600000000 { - opp-hz = /bits/ 64 <600000000>; - opp-microvolt = <1200000 1176000 1224000>; - opp-supported-hw = <0x01 0xFFFF>; - }; - - opp120-720000000 { - opp-hz = /bits/ 64 <720000000>; - opp-microvolt = <1200000 1176000 1224000>; - opp-supported-hw = <0x06 0x0080>; - }; - - oppturbo-720000000 { - opp-hz = /bits/ 64 <720000000>; - opp-microvolt = <1260000 1234800 1285200>; - opp-supported-hw = <0x01 0xFFFF>; - }; - - oppturbo-800000000 { - opp-hz = /bits/ 64 <800000000>; - opp-microvolt = <1260000 1234800 1285200>; - opp-supported-hw = <0x06 0x0100>; - }; - - oppnitro-1000000000 { - opp-hz = /bits/ 64 <1000000000>; - opp-microvolt = <1325000 1298500 1351500>; - opp-supported-hw = <0x04 0x0200>; - }; -}; diff --git a/Documentation/devicetree/bindings/crypto/fsl-imx-sahara.yaml b/Documentation/devicetree/bindings/crypto/fsl-imx-sahara.yaml index d531f3af3ea4..41df80bcdcd9 100644 --- a/Documentation/devicetree/bindings/crypto/fsl-imx-sahara.yaml +++ b/Documentation/devicetree/bindings/crypto/fsl-imx-sahara.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/crypto/fsl-imx-sahara.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Freescale SAHARA Cryptographic Accelerator included in some i.MX chips +title: Freescale SAHARA Cryptographic Accelerator maintainers: - Steffen Trumtrar <s.trumtrar@pengutronix.de> @@ -19,19 +19,56 @@ properties: maxItems: 1 interrupts: - maxItems: 1 + items: + - description: SAHARA Interrupt for Host 0 + - description: SAHARA Interrupt for Host 1 + minItems: 1 + + clocks: + items: + - description: Sahara IPG clock + - description: Sahara AHB clock + + clock-names: + items: + - const: ipg + - const: ahb required: - compatible - reg - interrupts + - clocks + - clock-names + +allOf: + - if: + properties: + compatible: + contains: + enum: + - fsl,imx53-sahara + then: + properties: + interrupts: + minItems: 2 + maxItems: 2 + else: + properties: + interrupts: + maxItems: 1 additionalProperties: false examples: - | + #include <dt-bindings/clock/imx27-clock.h> + crypto@10025000 { compatible = "fsl,imx27-sahara"; - reg = < 0x10025000 0x800>; + reg = <0x10025000 0x800>; interrupts = <75>; + clocks = <&clks IMX27_CLK_SAHARA_IPG_GATE>, + <&clks IMX27_CLK_SAHARA_AHB_GATE>; + clock-names = "ipg", "ahb"; }; diff --git a/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml b/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml index 92e1d76e29ee..ca4f7d1cefaa 100644 --- a/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml +++ b/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml @@ -13,6 +13,8 @@ properties: compatible: items: - enum: + - qcom,sa8775p-inline-crypto-engine + - qcom,sm8450-inline-crypto-engine - qcom,sm8550-inline-crypto-engine - const: qcom,inline-crypto-engine diff --git a/Documentation/devicetree/bindings/crypto/qcom,prng.yaml b/Documentation/devicetree/bindings/crypto/qcom,prng.yaml index bb42f4588b40..13070db0f70c 100644 --- a/Documentation/devicetree/bindings/crypto/qcom,prng.yaml +++ b/Documentation/devicetree/bindings/crypto/qcom,prng.yaml @@ -11,9 +11,17 @@ maintainers: properties: compatible: - enum: - - qcom,prng # 8916 etc. - - qcom,prng-ee # 8996 and later using EE + oneOf: + - enum: + - qcom,prng # 8916 etc. + - qcom,prng-ee # 8996 and later using EE + - items: + - enum: + - qcom,sa8775p-trng + - qcom,sc7280-trng + - qcom,sm8450-trng + - qcom,sm8550-trng + - const: qcom,trng reg: maxItems: 1 @@ -28,8 +36,18 @@ properties: required: - compatible - reg - - clocks - - clock-names + +allOf: + - if: + not: + properties: + compatible: + contains: + const: qcom,trng + then: + required: + - clocks + - clock-names additionalProperties: false diff --git a/Documentation/devicetree/bindings/crypto/qcom-qce.yaml b/Documentation/devicetree/bindings/crypto/qcom-qce.yaml index bb828068c3b8..8e665d910e6e 100644 --- a/Documentation/devicetree/bindings/crypto/qcom-qce.yaml +++ b/Documentation/devicetree/bindings/crypto/qcom-qce.yaml @@ -34,6 +34,7 @@ properties: - enum: - qcom,ipq6018-qce - qcom,ipq8074-qce + - qcom,ipq9574-qce - qcom,msm8996-qce - qcom,qcm2290-qce - qcom,sdm845-qce diff --git a/Documentation/devicetree/bindings/crypto/st,stm32-hash.yaml b/Documentation/devicetree/bindings/crypto/st,stm32-hash.yaml index b767ec72a999..ac480765cde0 100644 --- a/Documentation/devicetree/bindings/crypto/st,stm32-hash.yaml +++ b/Documentation/devicetree/bindings/crypto/st,stm32-hash.yaml @@ -20,6 +20,7 @@ properties: - stericsson,ux500-hash - st,stm32f456-hash - st,stm32f756-hash + - st,stm32mp13-hash reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml b/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml index 77ec8bc70bf7..ff10a0838ad6 100644 --- a/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml +++ b/Documentation/devicetree/bindings/crypto/ti,sa2ul.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/crypto/ti,sa2ul.yaml# @@ -66,10 +66,22 @@ patternProperties: required: - compatible - reg - - power-domains - dmas - dma-names +allOf: + - if: + properties: + compatible: + contains: + const: ti,am62-sa3ul + then: + properties: + power-domains: false + else: + required: + - power-domains + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/devfreq/event/rockchip,dfi.yaml b/Documentation/devicetree/bindings/devfreq/event/rockchip,dfi.yaml new file mode 100644 index 000000000000..50d3fabe958d --- /dev/null +++ b/Documentation/devicetree/bindings/devfreq/event/rockchip,dfi.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/devfreq/event/rockchip,dfi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip DFI + +maintainers: + - Sascha Hauer <s.hauer@pengutronix.de> + +properties: + compatible: + enum: + - rockchip,rk3399-dfi + - rockchip,rk3568-dfi + - rockchip,rk3588-dfi + + clocks: + maxItems: 1 + + clock-names: + items: + - const: pclk_ddr_mon + + interrupts: + minItems: 1 + maxItems: 4 + + reg: + maxItems: 1 + + rockchip,pmu: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to the syscon managing the "PMU general register files". + +required: + - compatible + - interrupts + - reg + +if: + properties: + compatible: + contains: + enum: + - rockchip,rk3399-dfi + +then: + required: + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/rk3308-cru.h> + + bus { + #address-cells = <2>; + #size-cells = <2>; + + dfi: dfi@ff630000 { + compatible = "rockchip,rk3399-dfi"; + reg = <0x00 0xff630000 0x00 0x4000>; + interrupts = <GIC_SPI 131 IRQ_TYPE_LEVEL_HIGH 0>; + rockchip,pmu = <&pmugrf>; + clocks = <&cru PCLK_DDR_MON>; + clock-names = "pclk_ddr_mon"; + }; + }; diff --git a/Documentation/devicetree/bindings/devfreq/event/rockchip-dfi.txt b/Documentation/devicetree/bindings/devfreq/event/rockchip-dfi.txt deleted file mode 100644 index 148191b0fc15..000000000000 --- a/Documentation/devicetree/bindings/devfreq/event/rockchip-dfi.txt +++ /dev/null @@ -1,18 +0,0 @@ - -* Rockchip rk3399 DFI device - -Required properties: -- compatible: Must be "rockchip,rk3399-dfi". -- reg: physical base address of each DFI and length of memory mapped region -- rockchip,pmu: phandle to the syscon managing the "pmu general register files" -- clocks: phandles for clock specified in "clock-names" property -- clock-names : the name of clock used by the DFI, must be "pclk_ddr_mon"; - -Example: - dfi: dfi@ff630000 { - compatible = "rockchip,rk3399-dfi"; - reg = <0x00 0xff630000 0x00 0x4000>; - rockchip,pmu = <&pmugrf>; - clocks = <&cru PCLK_DDR_MON>; - clock-names = "pclk_ddr_mon"; - }; diff --git a/Documentation/devicetree/bindings/devfreq/event/samsung,exynos-ppmu.yaml b/Documentation/devicetree/bindings/devfreq/event/samsung,exynos-ppmu.yaml index e300df4b47f3..d27dcb2fef12 100644 --- a/Documentation/devicetree/bindings/devfreq/event/samsung,exynos-ppmu.yaml +++ b/Documentation/devicetree/bindings/devfreq/event/samsung,exynos-ppmu.yaml @@ -18,7 +18,7 @@ description: | each IP (DMC, CPU, RIGHTBUS, LEFTBUS, CAM interface, LCD, G3D, MFC). The Exynos PPMU driver uses the devfreq-event class to provide event data to various devfreq devices. The devfreq devices would use the event data when - derterming the current state of each IP. + determining the current state of each IP. properties: compatible: diff --git a/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt b/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt index 0398aec488ac..923aea25344c 100644 --- a/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt +++ b/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt @@ -12,7 +12,7 @@ Required properties: Required children nodes: Children nodes are encoding available output ports and their connections - to external devices using the OF graph reprensentation (see ../graph.txt). + to external devices using the OF graph representation (see ../graph.txt). At least one port node is required. Optional properties in grandchild nodes: diff --git a/Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml b/Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml index 4a5e5d9d6f90..4509c496731b 100644 --- a/Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml +++ b/Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml @@ -17,6 +17,7 @@ properties: - analogix,anx7808 - analogix,anx7812 - analogix,anx7814 + - analogix,anx7816 - analogix,anx7818 reg: diff --git a/Documentation/devicetree/bindings/display/bridge/fsl,imx93-mipi-dsi.yaml b/Documentation/devicetree/bindings/display/bridge/fsl,imx93-mipi-dsi.yaml new file mode 100644 index 000000000000..d6e51d0cf546 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/fsl,imx93-mipi-dsi.yaml @@ -0,0 +1,115 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/fsl,imx93-mipi-dsi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale i.MX93 specific extensions to Synopsys Designware MIPI DSI + +maintainers: + - Liu Ying <victor.liu@nxp.com> + +description: | + There is a Synopsys Designware MIPI DSI Host Controller and a Synopsys + Designware MIPI DPHY embedded in Freescale i.MX93 SoC. Some configurations + and extensions to them are controlled by i.MX93 media blk-ctrl. + +allOf: + - $ref: snps,dw-mipi-dsi.yaml# + +properties: + compatible: + const: fsl,imx93-mipi-dsi + + clocks: + items: + - description: apb clock + - description: pixel clock + - description: PHY configuration clock + - description: PHY reference clock + + clock-names: + items: + - const: pclk + - const: pix + - const: phy_cfg + - const: phy_ref + + interrupts: + maxItems: 1 + + fsl,media-blk-ctrl: + $ref: /schemas/types.yaml#/definitions/phandle + description: + i.MX93 media blk-ctrl, as a syscon, controls pixel component bit map + configurations from LCDIF display controller to the MIPI DSI host + controller and MIPI DPHY PLL related configurations through PLL SoC + interface. + + power-domains: + maxItems: 1 + +required: + - compatible + - interrupts + - fsl,media-blk-ctrl + - power-domains + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/imx93-clock.h> + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/fsl,imx93-power.h> + + dsi@4ae10000 { + compatible = "fsl,imx93-mipi-dsi"; + reg = <0x4ae10000 0x10000>; + interrupts = <GIC_SPI 177 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk IMX93_CLK_MIPI_DSI_GATE>, + <&clk IMX93_CLK_MEDIA_DISP_PIX>, + <&clk IMX93_CLK_MIPI_PHY_CFG>, + <&clk IMX93_CLK_24M>; + clock-names = "pclk", "pix", "phy_cfg", "phy_ref"; + fsl,media-blk-ctrl = <&media_blk_ctrl>; + power-domains = <&media_blk_ctrl IMX93_MEDIABLK_PD_MIPI_DSI>; + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "raydium,rm67191"; + reg = <0>; + reset-gpios = <&adp5585gpio 6 GPIO_ACTIVE_LOW>; + dsi-lanes = <4>; + video-mode = <2>; + + port { + panel_in: endpoint { + remote-endpoint = <&dsi_out>; + }; + }; + }; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + dsi_to_lcdif: endpoint { + remote-endpoint = <&lcdif_to_dsi>; + }; + }; + + port@1 { + reg = <1>; + + dsi_out: endpoint { + remote-endpoint = <&panel_in>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/bridge/snps,dw-mipi-dsi.yaml b/Documentation/devicetree/bindings/display/bridge/snps,dw-mipi-dsi.yaml index 0b51c64f141a..8747b95ec20d 100644 --- a/Documentation/devicetree/bindings/display/bridge/snps,dw-mipi-dsi.yaml +++ b/Documentation/devicetree/bindings/display/bridge/snps,dw-mipi-dsi.yaml @@ -11,7 +11,7 @@ maintainers: description: | This document defines device tree properties for the Synopsys DesignWare MIPI - DSI host controller. It doesn't constitue a device tree binding specification + DSI host controller. It doesn't constitute a device tree binding specification by itself but is meant to be referenced by platform-specific device tree bindings. diff --git a/Documentation/devicetree/bindings/display/bridge/toshiba,tc358767.yaml b/Documentation/devicetree/bindings/display/bridge/toshiba,tc358767.yaml index 0521261b04a9..ae894d996d21 100644 --- a/Documentation/devicetree/bindings/display/bridge/toshiba,tc358767.yaml +++ b/Documentation/devicetree/bindings/display/bridge/toshiba,tc358767.yaml @@ -49,6 +49,9 @@ properties: description: | OF device-tree gpio specification for RSTX pin(active low system reset) + interrupts: + maxItems: 1 + toshiba,hpd-pin: $ref: /schemas/types.yaml#/definitions/uint32 enum: diff --git a/Documentation/devicetree/bindings/display/cirrus,clps711x-fb.txt b/Documentation/devicetree/bindings/display/cirrus,clps711x-fb.txt index 0ab5f0663611..84c75f849891 100644 --- a/Documentation/devicetree/bindings/display/cirrus,clps711x-fb.txt +++ b/Documentation/devicetree/bindings/display/cirrus,clps711x-fb.txt @@ -1,4 +1,4 @@ -* Currus Logic CLPS711X Framebuffer +* Cirrus Logic CLPS711X Framebuffer Required properties: - compatible: Shall contain "cirrus,ep7209-fb". diff --git a/Documentation/devicetree/bindings/display/ilitek,ili9486.yaml b/Documentation/devicetree/bindings/display/ilitek,ili9486.yaml index 1f8f2182e2f1..9cc1fd0751cd 100644 --- a/Documentation/devicetree/bindings/display/ilitek,ili9486.yaml +++ b/Documentation/devicetree/bindings/display/ilitek,ili9486.yaml @@ -50,10 +50,6 @@ examples: - | #include <dt-bindings/gpio/gpio.h> - backlight: backlight { - compatible = "gpio-backlight"; - gpios = <&gpio 22 GPIO_ACTIVE_HIGH>; - }; spi { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/display/imx/fsl,imx6-hdmi.yaml b/Documentation/devicetree/bindings/display/imx/fsl,imx6-hdmi.yaml index af7fe9c4d196..7979cf07f119 100644 --- a/Documentation/devicetree/bindings/display/imx/fsl,imx6-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/imx/fsl,imx6-hdmi.yaml @@ -87,7 +87,7 @@ required: - interrupts - ports -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/display/lvds-data-mapping.yaml b/Documentation/devicetree/bindings/display/lvds-data-mapping.yaml new file mode 100644 index 000000000000..d68982fe2e9b --- /dev/null +++ b/Documentation/devicetree/bindings/display/lvds-data-mapping.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/lvds-data-mapping.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: LVDS Data Mapping + +maintainers: + - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> + - Thierry Reding <thierry.reding@gmail.com> + +description: | + LVDS is a physical layer specification defined in ANSI/TIA/EIA-644-A. Multiple + incompatible data link layers have been used over time to transmit image data + to LVDS devices. This bindings supports devices compatible with the following + specifications. + + [JEIDA] "Digital Interface Standards for Monitor", JEIDA-59-1999, February + 1999 (Version 1.0), Japan Electronic Industry Development Association (JEIDA) + [LDI] "Open LVDS Display Interface", May 1999 (Version 0.95), National + Semiconductor + [VESA] "VESA Notebook Panel Standard", October 2007 (Version 1.0), Video + Electronics Standards Association (VESA) + + Device compatible with those specifications have been marketed under the + FPD-Link and FlatLink brands. + +properties: + data-mapping: + enum: + - jeida-18 + - jeida-24 + - vesa-24 + description: | + The color signals mapping order. + + LVDS data mappings are defined as follows. + + - "jeida-18" - 18-bit data mapping compatible with the [JEIDA], [LDI] and + [VESA] specifications. Data are transferred as follows on 3 LVDS lanes. + + Slot 0 1 2 3 4 5 6 + ________________ _________________ + Clock \_______________________/ + ______ ______ ______ ______ ______ ______ ______ + DATA0 ><__G0__><__R5__><__R4__><__R3__><__R2__><__R1__><__R0__>< + DATA1 ><__B1__><__B0__><__G5__><__G4__><__G3__><__G2__><__G1__>< + DATA2 ><_CTL2_><_CTL1_><_CTL0_><__B5__><__B4__><__B3__><__B2__>< + + - "jeida-24" - 24-bit data mapping compatible with the [DSIM] and [LDI] + specifications. Data are transferred as follows on 4 LVDS lanes. + + Slot 0 1 2 3 4 5 6 + ________________ _________________ + Clock \_______________________/ + ______ ______ ______ ______ ______ ______ ______ + DATA0 ><__G2__><__R7__><__R6__><__R5__><__R4__><__R3__><__R2__>< + DATA1 ><__B3__><__B2__><__G7__><__G6__><__G5__><__G4__><__G3__>< + DATA2 ><_CTL2_><_CTL1_><_CTL0_><__B7__><__B6__><__B5__><__B4__>< + DATA3 ><_CTL3_><__B1__><__B0__><__G1__><__G0__><__R1__><__R0__>< + + - "vesa-24" - 24-bit data mapping compatible with the [VESA] specification. + Data are transferred as follows on 4 LVDS lanes. + + Slot 0 1 2 3 4 5 6 + ________________ _________________ + Clock \_______________________/ + ______ ______ ______ ______ ______ ______ ______ + DATA0 ><__G0__><__R5__><__R4__><__R3__><__R2__><__R1__><__R0__>< + DATA1 ><__B1__><__B0__><__G5__><__G4__><__G3__><__G2__><__G1__>< + DATA2 ><_CTL2_><_CTL1_><_CTL0_><__B5__><__B4__><__B3__><__B2__>< + DATA3 ><_CTL3_><__B7__><__B6__><__G7__><__G6__><__R7__><__R6__>< + + Control signals are mapped as follows. + + CTL0: HSync + CTL1: VSync + CTL2: Data Enable + CTL3: 0 + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/display/lvds.yaml b/Documentation/devicetree/bindings/display/lvds.yaml index 7cd2ce7e9c33..224db4932011 100644 --- a/Documentation/devicetree/bindings/display/lvds.yaml +++ b/Documentation/devicetree/bindings/display/lvds.yaml @@ -6,83 +6,24 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: LVDS Display Common Properties +allOf: + - $ref: lvds-data-mapping.yaml# + maintainers: - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> - Thierry Reding <thierry.reding@gmail.com> -description: |+ - LVDS is a physical layer specification defined in ANSI/TIA/EIA-644-A. Multiple - incompatible data link layers have been used over time to transmit image data - to LVDS devices. This bindings supports devices compatible with the following - specifications. - - [JEIDA] "Digital Interface Standards for Monitor", JEIDA-59-1999, February - 1999 (Version 1.0), Japan Electronic Industry Development Association (JEIDA) - [LDI] "Open LVDS Display Interface", May 1999 (Version 0.95), National - Semiconductor - [VESA] "VESA Notebook Panel Standard", October 2007 (Version 1.0), Video - Electronics Standards Association (VESA) - - Device compatible with those specifications have been marketed under the - FPD-Link and FlatLink brands. +description: + This binding extends the data mapping defined in lvds-data-mapping.yaml. + It supports reversing the bit order on the formats defined there in order + to accomodate for even more specialized data formats, since a variety of + data formats and layouts is used to drive LVDS displays. properties: - data-mapping: - enum: - - jeida-18 - - jeida-24 - - vesa-24 - description: | - The color signals mapping order. - - LVDS data mappings are defined as follows. - - - "jeida-18" - 18-bit data mapping compatible with the [JEIDA], [LDI] and - [VESA] specifications. Data are transferred as follows on 3 LVDS lanes. - - Slot 0 1 2 3 4 5 6 - ________________ _________________ - Clock \_______________________/ - ______ ______ ______ ______ ______ ______ ______ - DATA0 ><__G0__><__R5__><__R4__><__R3__><__R2__><__R1__><__R0__>< - DATA1 ><__B1__><__B0__><__G5__><__G4__><__G3__><__G2__><__G1__>< - DATA2 ><_CTL2_><_CTL1_><_CTL0_><__B5__><__B4__><__B3__><__B2__>< - - - "jeida-24" - 24-bit data mapping compatible with the [DSIM] and [LDI] - specifications. Data are transferred as follows on 4 LVDS lanes. - - Slot 0 1 2 3 4 5 6 - ________________ _________________ - Clock \_______________________/ - ______ ______ ______ ______ ______ ______ ______ - DATA0 ><__G2__><__R7__><__R6__><__R5__><__R4__><__R3__><__R2__>< - DATA1 ><__B3__><__B2__><__G7__><__G6__><__G5__><__G4__><__G3__>< - DATA2 ><_CTL2_><_CTL1_><_CTL0_><__B7__><__B6__><__B5__><__B4__>< - DATA3 ><_CTL3_><__B1__><__B0__><__G1__><__G0__><__R1__><__R0__>< - - - "vesa-24" - 24-bit data mapping compatible with the [VESA] specification. - Data are transferred as follows on 4 LVDS lanes. - - Slot 0 1 2 3 4 5 6 - ________________ _________________ - Clock \_______________________/ - ______ ______ ______ ______ ______ ______ ______ - DATA0 ><__G0__><__R5__><__R4__><__R3__><__R2__><__R1__><__R0__>< - DATA1 ><__B1__><__B0__><__G5__><__G4__><__G3__><__G2__><__G1__>< - DATA2 ><_CTL2_><_CTL1_><_CTL0_><__B5__><__B4__><__B3__><__B2__>< - DATA3 ><_CTL3_><__B7__><__B6__><__G7__><__G6__><__R7__><__R6__>< - - Control signals are mapped as follows. - - CTL0: HSync - CTL1: VSync - CTL2: Data Enable - CTL3: 0 - data-mirror: type: boolean description: - If set, reverse the bit order described in the data mappings below on all + If set, reverse the bit order described in the data mappings on all data lanes, transmitting bits for slots 6 to 0 instead of 0 to 6. additionalProperties: true diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,dp.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,dp.yaml index ff781f2174a0..2aef1eb32e11 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,dp.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,dp.yaml @@ -21,6 +21,8 @@ description: | properties: compatible: enum: + - mediatek,mt8188-dp-tx + - mediatek,mt8188-edp-tx - mediatek,mt8195-dp-tx - mediatek,mt8195-edp-tx diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.yaml index 12441b937684..537e5304b730 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.yaml @@ -30,6 +30,7 @@ properties: - mediatek,mt8173-dsi - mediatek,mt8183-dsi - mediatek,mt8186-dsi + - mediatek,mt8188-dsi - items: - enum: - mediatek,mt6795-dsi diff --git a/Documentation/devicetree/bindings/display/msm/dp-controller.yaml b/Documentation/devicetree/bindings/display/msm/dp-controller.yaml index 7a7cf3fb3e6d..dbe398f84ffb 100644 --- a/Documentation/devicetree/bindings/display/msm/dp-controller.yaml +++ b/Documentation/devicetree/bindings/display/msm/dp-controller.yaml @@ -28,6 +28,7 @@ properties: - qcom,sm8350-dp - items: - enum: + - qcom,sm8250-dp - qcom,sm8450-dp - qcom,sm8550-dp - const: qcom,sm8350-dp @@ -79,7 +80,8 @@ properties: operating-points-v2: true - opp-table: true + opp-table: + type: object power-domains: maxItems: 1 @@ -112,6 +114,7 @@ properties: port@1: $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: Output endpoint of the controller properties: endpoint: diff --git a/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml b/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml index 01848bdd5873..c6dbab65d5f7 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-controller-main.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/msm/dsi-controller-main.yaml# @@ -27,6 +27,7 @@ properties: - qcom,sdm660-dsi-ctrl - qcom,sdm845-dsi-ctrl - qcom,sm6115-dsi-ctrl + - qcom,sm6125-dsi-ctrl - qcom,sm6350-dsi-ctrl - qcom,sm6375-dsi-ctrl - qcom,sm8150-dsi-ctrl @@ -166,6 +167,10 @@ properties: description: Phandle to vdd regulator device node + refgen-supply: + description: + Phandle to REFGEN regulator device node + vcca-supply: description: Phandle to vdd regulator device node @@ -301,6 +306,7 @@ allOf: contains: enum: - qcom,msm8998-dsi-ctrl + - qcom,sm6125-dsi-ctrl - qcom,sm6350-dsi-ctrl then: properties: diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-10nm.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-10nm.yaml index e6b00d7387ce..69d13867b7cf 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-10nm.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-10nm.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/msm/dsi-phy-10nm.yaml# diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.yaml index a43e11d3b00d..52bbe132e6da 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.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/msm/dsi-phy-14nm.yaml# @@ -19,6 +19,7 @@ properties: - qcom,dsi-phy-14nm-2290 - qcom,dsi-phy-14nm-660 - qcom,dsi-phy-14nm-8953 + - qcom,sm6125-dsi-phy-14nm reg: items: @@ -35,6 +36,16 @@ properties: vcca-supply: description: Phandle to vcca regulator device node. + power-domains: + description: + A phandle and PM domain specifier for an optional power domain. + maxItems: 1 + + required-opps: + description: + A phandle to an OPP node describing the power domain's performance point. + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-20nm.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-20nm.yaml index 9c1f9140c731..7e6687cb002b 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-20nm.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-20nm.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/msm/dsi-phy-20nm.yaml# diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-28nm.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-28nm.yaml index 62fb3e484eb2..288d8babb76a 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-28nm.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-28nm.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/msm/dsi-phy-28nm.yaml# diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-7nm.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-7nm.yaml index 8e9031bbde73..dd6619555a12 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-7nm.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-7nm.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/msm/dsi-phy-7nm.yaml# diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-common.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-common.yaml index 0f6f08890e7e..6b57ce41c95f 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-common.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-common.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/msm/dsi-phy-common.yaml# diff --git a/Documentation/devicetree/bindings/display/msm/gmu.yaml b/Documentation/devicetree/bindings/display/msm/gmu.yaml index d65926b4f054..4e1c25b42908 100644 --- a/Documentation/devicetree/bindings/display/msm/gmu.yaml +++ b/Documentation/devicetree/bindings/display/msm/gmu.yaml @@ -21,7 +21,7 @@ properties: compatible: oneOf: - items: - - pattern: '^qcom,adreno-gmu-6[0-9][0-9]\.[0-9]$' + - pattern: '^qcom,adreno-gmu-[67][0-9][0-9]\.[0-9]$' - const: qcom,adreno-gmu - const: qcom,adreno-gmu-wrapper @@ -64,6 +64,10 @@ properties: iommus: maxItems: 1 + qcom,qmp: + $ref: /schemas/types.yaml#/definitions/phandle + description: Reference to the AOSS side-channel message RAM + operating-points-v2: true opp-table: @@ -217,6 +221,47 @@ allOf: properties: compatible: contains: + enum: + - qcom,adreno-gmu-730.1 + - qcom,adreno-gmu-740.1 + then: + properties: + reg: + items: + - description: Core GMU registers + - description: Resource controller registers + - description: GMU PDC registers + reg-names: + items: + - const: gmu + - const: rscc + - const: gmu_pdc + clocks: + items: + - description: GPU AHB clock + - description: GMU clock + - description: GPU CX clock + - description: GPU AXI clock + - description: GPU MEMNOC clock + - description: GMU HUB clock + - description: GPUSS DEMET clock + clock-names: + items: + - const: ahb + - const: gmu + - const: cxo + - const: axi + - const: memnoc + - const: hub + - const: demet + + required: + - qcom,qmp + + - if: + properties: + compatible: + contains: const: qcom,adreno-gmu-wrapper then: properties: diff --git a/Documentation/devicetree/bindings/display/msm/gpu.yaml b/Documentation/devicetree/bindings/display/msm/gpu.yaml index 58ca8912a8c3..b019db954793 100644 --- a/Documentation/devicetree/bindings/display/msm/gpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/gpu.yaml @@ -15,9 +15,15 @@ properties: oneOf: - description: | The driver is parsing the compat string for Adreno to + figure out the chip-id. + items: + - pattern: '^qcom,adreno-[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]$' + - const: qcom,adreno + - description: | + The driver is parsing the compat string for Adreno to figure out the gpu-id and patch level. items: - - pattern: '^qcom,adreno-[3-6][0-9][0-9]\.[0-9]$' + - pattern: '^qcom,adreno-[3-7][0-9][0-9]\.[0-9]$' - const: qcom,adreno - description: | The driver is parsing the compat string for Imageon to @@ -197,7 +203,7 @@ allOf: properties: compatible: contains: - pattern: '^qcom,adreno-6[0-9][0-9]\.[0-9]$' + pattern: '^qcom,adreno-[67][0-9][0-9]\.[0-9]$' then: # Starting with A6xx, the clocks are usually defined in the GMU node properties: diff --git a/Documentation/devicetree/bindings/display/msm/mdss-common.yaml b/Documentation/devicetree/bindings/display/msm/mdss-common.yaml index ccd7d6417523..f69196e4cc76 100644 --- a/Documentation/devicetree/bindings/display/msm/mdss-common.yaml +++ b/Documentation/devicetree/bindings/display/msm/mdss-common.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/msm/mdss-common.yaml# @@ -77,6 +77,12 @@ properties: items: - description: MDSS_CORE reset + memory-region: + maxItems: 1 + description: + Phandle to a node describing a reserved framebuffer memory region. + For example, the splash memory region set up by the bootloader. + required: - reg - reg-names diff --git a/Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml b/Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml index 2fe032d0e8f8..91c774f106ce 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,mdp5.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/msm/qcom,mdp5.yaml# diff --git a/Documentation/devicetree/bindings/display/msm/qcom,mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,mdss.yaml index db9f07c6142d..0999ea07f47b 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,mdss.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/msm/qcom,mdss.yaml# @@ -11,7 +11,7 @@ maintainers: - Rob Clark <robdclark@gmail.com> description: - This is the bindings documentation for the Mobile Display Subsytem(MDSS) that + This is the bindings documentation for the Mobile Display Subsystem(MDSS) that encapsulates sub-blocks like MDP5, DSI, HDMI, eDP, etc. properties: diff --git a/Documentation/devicetree/bindings/display/msm/qcom,msm8998-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,msm8998-dpu.yaml index 8d3cd46260fb..d5a64c8a921f 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,msm8998-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,msm8998-dpu.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/msm/qcom,msm8998-dpu.yaml# diff --git a/Documentation/devicetree/bindings/display/msm/qcom,msm8998-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,msm8998-mdss.yaml index 3c2b6ed98a56..2d9edab5a30d 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,msm8998-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,msm8998-mdss.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/msm/qcom,msm8998-mdss.yaml# @@ -38,12 +38,16 @@ properties: patternProperties: "^display-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,msm8998-dpu "^dsi@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: items: @@ -52,6 +56,8 @@ patternProperties: "^phy@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,dsi-phy-10nm-8998 diff --git a/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-dpu.yaml index 414f4e7ebdf1..be6cd8adb3b6 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-dpu.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/msm/qcom,qcm2290-dpu.yaml# diff --git a/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-mdss.yaml index 2995b84b2cd4..5ad155612b6c 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-mdss.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/msm/qcom,qcm2290-mdss.yaml# @@ -44,18 +44,24 @@ properties: patternProperties: "^display-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,qcm2290-dpu "^dsi@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,dsi-ctrl-6g-qcm2290 "^phy@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,dsi-phy-14nm-2290 diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sc7180-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sc7180-dpu.yaml index 630b11480496..8137618237ce 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sc7180-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sc7180-dpu.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/msm/qcom,sc7180-dpu.yaml# @@ -15,6 +15,7 @@ properties: compatible: enum: - qcom,sc7180-dpu + - qcom,sm6125-dpu - qcom,sm6350-dpu - qcom,sm6375-dpu @@ -63,7 +64,9 @@ allOf: - if: properties: compatible: - const: qcom,sm6375-dpu + enum: + - qcom,sm6375-dpu + - qcom,sm6125-dpu then: properties: diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sc7180-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sc7180-mdss.yaml index 42ef06edddc4..3432a2407caa 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sc7180-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sc7180-mdss.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/msm/qcom,sc7180-mdss.yaml# @@ -44,18 +44,24 @@ properties: patternProperties: "^display-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sc7180-dpu "^displayport-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sc7180-dp "^dsi@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: items: @@ -64,6 +70,8 @@ patternProperties: "^phy@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,dsi-phy-10nm diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sc7280-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sc7280-dpu.yaml index 26dc073bd19a..b0fbe86219d1 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sc7280-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sc7280-dpu.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/msm/qcom,sc7280-dpu.yaml# diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sc7280-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sc7280-mdss.yaml index 078e1d1a7d2f..bbb727831fca 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sc7280-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sc7280-mdss.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/msm/qcom,sc7280-mdss.yaml# @@ -44,18 +44,24 @@ properties: patternProperties: "^display-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sc7280-dpu "^displayport-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sc7280-dp "^dsi@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: items: @@ -64,12 +70,16 @@ patternProperties: "^edp@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sc7280-edp "^phy@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: enum: diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sc8280xp-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sc8280xp-dpu.yaml index f2c8e16cf067..d19e3bec4600 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sc8280xp-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sc8280xp-dpu.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/msm/qcom,sc8280xp-dpu.yaml# diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sc8280xp-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sc8280xp-mdss.yaml index c239544bc37f..af79406e1604 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sc8280xp-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sc8280xp-mdss.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/msm/qcom,sc8280xp-mdss.yaml# @@ -34,12 +34,16 @@ properties: patternProperties: "^display-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sc8280xp-dpu "^displayport-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: enum: diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sdm845-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sdm845-dpu.yaml index 0f7765d832e7..b917064bdf33 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sdm845-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sdm845-dpu.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/msm/qcom,sdm845-dpu.yaml# diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sdm845-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sdm845-mdss.yaml index 6ecb00920d7f..6e8b69e5ec62 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sdm845-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sdm845-mdss.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/msm/qcom,sdm845-mdss.yaml# @@ -42,18 +42,24 @@ properties: patternProperties: "^display-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sdm845-dpu "^displayport-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sdm845-dp "^dsi@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: items: @@ -62,6 +68,8 @@ patternProperties: "^phy@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,dsi-phy-10nm diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm6115-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm6115-dpu.yaml index bf62c2f5325a..510eb6c19364 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm6115-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm6115-dpu.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/msm/qcom,sm6115-dpu.yaml# diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm6115-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm6115-mdss.yaml index b9f83088f370..dde5c2acead5 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm6115-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm6115-mdss.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/msm/qcom,sm6115-mdss.yaml# @@ -32,12 +32,16 @@ properties: patternProperties: "^display-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sm6115-dpu "^dsi@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: oneOf: @@ -50,6 +54,8 @@ patternProperties: "^phy@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,dsi-phy-14nm-2290 diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm6125-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm6125-mdss.yaml new file mode 100644 index 000000000000..671c2c2aa896 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm6125-mdss.yaml @@ -0,0 +1,219 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,sm6125-mdss.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM6125 Display MDSS + +maintainers: + - Marijn Suijten <marijn.suijten@somainline.org> + +description: + SM6125 MSM Mobile Display Subsystem (MDSS), which encapsulates sub-blocks + like DPU display controller, DSI and DP interfaces etc. + +$ref: /schemas/display/msm/mdss-common.yaml# + +properties: + compatible: + const: qcom,sm6125-mdss + + clocks: + items: + - description: Display AHB clock from gcc + - description: Display AHB clock + - description: Display core clock + + clock-names: + items: + - const: iface + - const: ahb + - const: core + + iommus: + maxItems: 1 + + interconnects: + maxItems: 2 + + interconnect-names: + maxItems: 2 + +patternProperties: + "^display-controller@[0-9a-f]+$": + type: object + additionalProperties: true + + properties: + compatible: + const: qcom,sm6125-dpu + + "^dsi@[0-9a-f]+$": + type: object + additionalProperties: true + + properties: + compatible: + items: + - const: qcom,sm6125-dsi-ctrl + - const: qcom,mdss-dsi-ctrl + + "^phy@[0-9a-f]+$": + type: object + additionalProperties: true + + properties: + compatible: + const: qcom,sm6125-dsi-phy-14nm + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,dispcc-sm6125.h> + #include <dt-bindings/clock/qcom,gcc-sm6125.h> + #include <dt-bindings/clock/qcom,rpmcc.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-subsystem@5e00000 { + compatible = "qcom,sm6125-mdss"; + reg = <0x05e00000 0x1000>; + reg-names = "mdss"; + + interrupts = <GIC_SPI 186 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <1>; + + clocks = <&gcc GCC_DISP_AHB_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>; + clock-names = "iface", + "ahb", + "core"; + + power-domains = <&dispcc MDSS_GDSC>; + + iommus = <&apps_smmu 0x400 0x0>; + + #address-cells = <1>; + #size-cells = <1>; + ranges; + + display-controller@5e01000 { + compatible = "qcom,sm6125-dpu"; + reg = <0x05e01000 0x83208>, + <0x05eb0000 0x2008>; + reg-names = "mdp", "vbif"; + + interrupt-parent = <&mdss>; + interrupts = <0>; + + clocks = <&gcc GCC_DISP_HF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_ROT_CLK>, + <&dispcc DISP_CC_MDSS_MDP_LUT_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>, + <&dispcc DISP_CC_MDSS_VSYNC_CLK>, + <&gcc GCC_DISP_THROTTLE_CORE_CLK>; + clock-names = "bus", + "iface", + "rot", + "lut", + "core", + "vsync", + "throttle"; + assigned-clocks = <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + assigned-clock-rates = <19200000>; + + operating-points-v2 = <&mdp_opp_table>; + power-domains = <&rpmpd SM6125_VDDCX>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dpu_intf1_out: endpoint { + remote-endpoint = <&mdss_dsi0_in>; + }; + }; + }; + }; + + dsi@5e94000 { + compatible = "qcom,sm6125-dsi-ctrl", "qcom,mdss-dsi-ctrl"; + reg = <0x05e94000 0x400>; + reg-names = "dsi_ctrl"; + + interrupt-parent = <&mdss>; + interrupts = <4>; + + clocks = <&dispcc DISP_CC_MDSS_BYTE0_CLK>, + <&dispcc DISP_CC_MDSS_BYTE0_INTF_CLK>, + <&dispcc DISP_CC_MDSS_PCLK0_CLK>, + <&dispcc DISP_CC_MDSS_ESC0_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&gcc GCC_DISP_HF_AXI_CLK>; + clock-names = "byte", + "byte_intf", + "pixel", + "core", + "iface", + "bus"; + assigned-clocks = <&dispcc DISP_CC_MDSS_BYTE0_CLK_SRC>, + <&dispcc DISP_CC_MDSS_PCLK0_CLK_SRC>; + assigned-clock-parents = <&mdss_dsi0_phy 0>, <&mdss_dsi0_phy 1>; + + operating-points-v2 = <&dsi_opp_table>; + power-domains = <&rpmpd SM6125_VDDCX>; + + phys = <&mdss_dsi0_phy>; + phy-names = "dsi"; + + #address-cells = <1>; + #size-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + mdss_dsi0_in: endpoint { + remote-endpoint = <&dpu_intf1_out>; + }; + }; + + port@1 { + reg = <1>; + mdss_dsi0_out: endpoint { + }; + }; + }; + }; + + phy@5e94400 { + compatible = "qcom,sm6125-dsi-phy-14nm"; + reg = <0x05e94400 0x100>, + <0x05e94500 0x300>, + <0x05e94800 0x188>; + reg-names = "dsi_phy", + "dsi_phy_lane", + "dsi_pll"; + + #clock-cells = <1>; + #phy-cells = <0>; + + clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&rpmcc RPM_SMD_XO_CLK_SRC>; + clock-names = "iface", + "ref"; + + required-opps = <&rpmpd_opp_nom>; + power-domains = <&rpmpd SM6125_VDDMX>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm6350-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm6350-mdss.yaml index ed0ad194d4ce..e1dcb453762e 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm6350-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm6350-mdss.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/msm/qcom,sm6350-mdss.yaml# @@ -43,12 +43,16 @@ properties: patternProperties: "^display-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sm6350-dpu "^dsi@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: items: @@ -57,6 +61,8 @@ patternProperties: "^phy@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,dsi-phy-10nm @@ -131,13 +137,6 @@ examples: remote-endpoint = <&dsi0_in>; }; }; - - port@1 { - reg = <1>; - dpu_intf2_out: endpoint { - remote-endpoint = <&dsi1_in>; - }; - }; }; }; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm6375-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm6375-mdss.yaml index 76369a4f7c4d..b15c3950f09d 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm6375-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm6375-mdss.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/msm/qcom,sm6375-mdss.yaml# @@ -43,12 +43,16 @@ properties: patternProperties: "^display-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sm6375-dpu "^dsi@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: items: @@ -57,6 +61,8 @@ patternProperties: "^phy@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sm6375-dsi-phy-7nm @@ -132,13 +138,6 @@ examples: remote-endpoint = <&dsi0_in>; }; }; - - port@1 { - reg = <1>; - dpu_intf2_out: endpoint { - remote-endpoint = <&dsi1_in>; - }; - }; }; }; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8150-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8150-dpu.yaml index 2b3f3fe9bdf7..13146b3f053c 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm8150-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8150-dpu.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/msm/qcom,sm8150-dpu.yaml# diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8150-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8150-mdss.yaml index 5182e958e069..a2a8be7f64a9 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm8150-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8150-mdss.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/msm/qcom,sm8150-mdss.yaml# @@ -47,12 +47,16 @@ properties: patternProperties: "^display-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sm8150-dpu "^dsi@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: items: @@ -61,6 +65,8 @@ patternProperties: "^phy@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,dsi-phy-7nm diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8250-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8250-dpu.yaml index 687c8c170cd4..ffa5047e901f 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm8250-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8250-dpu.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/msm/qcom,sm8250-dpu.yaml# @@ -54,7 +54,7 @@ examples: #include <dt-bindings/clock/qcom,gcc-sm8250.h> #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/interconnect/qcom,sm8250.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> display-controller@ae01000 { compatible = "qcom,sm8250-dpu"; @@ -72,7 +72,7 @@ examples: assigned-clock-rates = <19200000>; operating-points-v2 = <&mdp_opp_table>; - power-domains = <&rpmhpd SM8250_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; interrupt-parent = <&mdss>; interrupts = <0>; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8250-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8250-mdss.yaml index 368d3db0ce96..994975909fea 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm8250-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8250-mdss.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/msm/qcom,sm8250-mdss.yaml# @@ -46,12 +46,16 @@ properties: patternProperties: "^display-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sm8250-dpu "^dsi@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: items: @@ -60,6 +64,8 @@ patternProperties: "^phy@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,dsi-phy-7nm @@ -76,7 +82,7 @@ examples: #include <dt-bindings/clock/qcom,rpmh.h> #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/interconnect/qcom,sm8250.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> display-subsystem@ae00000 { compatible = "qcom,sm8250-mdss"; @@ -121,7 +127,7 @@ examples: assigned-clock-rates = <19200000>; operating-points-v2 = <&mdp_opp_table>; - power-domains = <&rpmhpd SM8250_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; interrupt-parent = <&mdss>; interrupts = <0>; @@ -196,7 +202,7 @@ examples: assigned-clock-parents = <&dsi0_phy 0>, <&dsi0_phy 1>; operating-points-v2 = <&dsi_opp_table>; - power-domains = <&rpmhpd SM8250_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; phys = <&dsi0_phy>; phy-names = "dsi"; @@ -286,7 +292,7 @@ examples: assigned-clock-parents = <&dsi1_phy 0>, <&dsi1_phy 1>; operating-points-v2 = <&dsi_opp_table>; - power-domains = <&rpmhpd SM8250_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; phys = <&dsi1_phy>; phy-names = "dsi"; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8350-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8350-dpu.yaml index 120500395c9a..96ef2d9c3512 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm8350-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8350-dpu.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/msm/qcom,sm8350-dpu.yaml# @@ -51,7 +51,7 @@ examples: #include <dt-bindings/clock/qcom,gcc-sm8350.h> #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/interconnect/qcom,sm8350.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> display-controller@ae01000 { compatible = "qcom,sm8350-dpu"; @@ -76,7 +76,7 @@ examples: assigned-clock-rates = <19200000>; operating-points-v2 = <&mdp_opp_table>; - power-domains = <&rpmhpd SM8350_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; interrupt-parent = <&mdss>; interrupts = <0>; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8350-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8350-mdss.yaml index 79a226e4cc6a..163fc83c1e80 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm8350-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8350-mdss.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/msm/qcom,sm8350-mdss.yaml# @@ -48,12 +48,24 @@ properties: patternProperties: "^display-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sm8350-dpu + "^displayport-controller@[0-9a-f]+$": + type: object + additionalProperties: true + + properties: + compatible: + const: qcom,sm8350-dp + "^dsi@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: items: @@ -62,6 +74,8 @@ patternProperties: "^phy@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sm8350-dsi-phy-5nm @@ -75,7 +89,7 @@ examples: #include <dt-bindings/clock/qcom,rpmh.h> #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/interconnect/qcom,sm8350.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> display-subsystem@ae00000 { compatible = "qcom,sm8350-mdss"; @@ -128,7 +142,7 @@ examples: assigned-clock-rates = <19200000>; operating-points-v2 = <&mdp_opp_table>; - power-domains = <&rpmhpd SM8350_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; interrupt-parent = <&mdss>; interrupts = <0>; @@ -197,7 +211,7 @@ examples: <&mdss_dsi0_phy 1>; operating-points-v2 = <&dsi_opp_table>; - power-domains = <&rpmhpd SM8350_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; phys = <&mdss_dsi0_phy>; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8450-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8450-dpu.yaml index 0d17ece1c453..2a5d3daed0e1 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm8450-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8450-dpu.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/msm/qcom,sm8450-dpu.yaml# @@ -58,7 +58,7 @@ examples: #include <dt-bindings/clock/qcom,gcc-sm8450.h> #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/interconnect/qcom,sm8450.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> display-controller@ae01000 { compatible = "qcom,sm8450-dpu"; @@ -83,7 +83,7 @@ examples: assigned-clock-rates = <19200000>; operating-points-v2 = <&mdp_opp_table>; - power-domains = <&rpmhpd SM8450_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; interrupt-parent = <&mdss>; interrupts = <0>; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8450-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8450-mdss.yaml index f26eb5643aed..001b26e65301 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm8450-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8450-mdss.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/msm/qcom,sm8450-mdss.yaml# @@ -38,12 +38,26 @@ properties: patternProperties: "^display-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sm8450-dpu + "^displayport-controller@[0-9a-f]+$": + type: object + additionalProperties: true + + properties: + compatible: + items: + - const: qcom,sm8450-dp + - const: qcom,sm8350-dp + "^dsi@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: items: @@ -52,6 +66,8 @@ patternProperties: "^phy@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sm8450-dsi-phy-5nm @@ -68,7 +84,7 @@ examples: #include <dt-bindings/clock/qcom,rpmh.h> #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/interconnect/qcom,sm8450.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> display-subsystem@ae00000 { compatible = "qcom,sm8450-mdss"; @@ -122,7 +138,7 @@ examples: assigned-clock-rates = <19200000>; operating-points-v2 = <&mdp_opp_table>; - power-domains = <&rpmhpd SM8450_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; interrupt-parent = <&mdss>; interrupts = <0>; @@ -202,7 +218,7 @@ examples: assigned-clock-parents = <&dsi0_phy 0>, <&dsi0_phy 1>; operating-points-v2 = <&dsi_opp_table>; - power-domains = <&rpmhpd SM8450_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; phys = <&dsi0_phy>; phy-names = "dsi"; @@ -297,7 +313,7 @@ examples: assigned-clock-parents = <&dsi1_phy 0>, <&dsi1_phy 1>; operating-points-v2 = <&dsi_opp_table>; - power-domains = <&rpmhpd SM8450_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; phys = <&dsi1_phy>; phy-names = "dsi"; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8550-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8550-dpu.yaml index ff58a747bb6f..16a541fca66f 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm8550-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8550-dpu.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/msm/qcom,sm8550-dpu.yaml# @@ -57,7 +57,7 @@ examples: #include <dt-bindings/clock/qcom,sm8550-dispcc.h> #include <dt-bindings/clock/qcom,sm8550-gcc.h> #include <dt-bindings/interrupt-controller/arm-gic.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> display-controller@ae01000 { compatible = "qcom,sm8550-dpu"; @@ -82,7 +82,7 @@ examples: assigned-clock-rates = <19200000>; operating-points-v2 = <&mdp_opp_table>; - power-domains = <&rpmhpd SM8550_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; interrupt-parent = <&mdss>; interrupts = <0>; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8550-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8550-mdss.yaml index 887be33ba108..1ea50a2c7c8e 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm8550-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8550-mdss.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/msm/qcom,sm8550-mdss.yaml# @@ -38,12 +38,26 @@ properties: patternProperties: "^display-controller@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sm8550-dpu + "^displayport-controller@[0-9a-f]+$": + type: object + additionalProperties: true + + properties: + compatible: + items: + - const: qcom,sm8550-dp + - const: qcom,sm8350-dp + "^dsi@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: items: @@ -52,6 +66,8 @@ patternProperties: "^phy@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: const: qcom,sm8550-dsi-phy-4nm @@ -68,7 +84,7 @@ examples: #include <dt-bindings/clock/qcom,rpmh.h> #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/interconnect/qcom,sm8550-rpmh.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> display-subsystem@ae00000 { compatible = "qcom,sm8550-mdss"; @@ -122,7 +138,7 @@ examples: assigned-clock-rates = <19200000>; operating-points-v2 = <&mdp_opp_table>; - power-domains = <&rpmhpd SM8550_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; interrupt-parent = <&mdss>; interrupts = <0>; @@ -197,7 +213,7 @@ examples: assigned-clock-parents = <&dsi0_phy 0>, <&dsi0_phy 1>; operating-points-v2 = <&dsi_opp_table>; - power-domains = <&rpmhpd SM8550_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; phys = <&dsi0_phy>; phy-names = "dsi"; @@ -286,7 +302,7 @@ examples: assigned-clock-parents = <&dsi1_phy 0>, <&dsi1_phy 1>; operating-points-v2 = <&dsi_opp_table>; - power-domains = <&rpmhpd SM8550_MMCX>; + power-domains = <&rpmhpd RPMHPD_MMCX>; phys = <&dsi1_phy>; phy-names = "dsi"; diff --git a/Documentation/devicetree/bindings/display/panel/advantech,idk-2121wr.yaml b/Documentation/devicetree/bindings/display/panel/advantech,idk-2121wr.yaml index 67682fe77f10..2e8dbdb5a3d5 100644 --- a/Documentation/devicetree/bindings/display/panel/advantech,idk-2121wr.yaml +++ b/Documentation/devicetree/bindings/display/panel/advantech,idk-2121wr.yaml @@ -19,6 +19,9 @@ description: | second port, therefore the ports must be marked accordingly (with either dual-lvds-odd-pixels or dual-lvds-even-pixels). +allOf: + - $ref: panel-common.yaml# + properties: compatible: items: diff --git a/Documentation/devicetree/bindings/display/panel/himax,hx8394.yaml b/Documentation/devicetree/bindings/display/panel/himax,hx8394.yaml index 1b2a1baa26f9..ffb35288ffbb 100644 --- a/Documentation/devicetree/bindings/display/panel/himax,hx8394.yaml +++ b/Documentation/devicetree/bindings/display/panel/himax,hx8394.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/himax,hx8394.yaml# diff --git a/Documentation/devicetree/bindings/display/panel/ilitek,ili9163.yaml b/Documentation/devicetree/bindings/display/panel/ilitek,ili9163.yaml index 90e323e19edb..3cabbba86581 100644 --- a/Documentation/devicetree/bindings/display/panel/ilitek,ili9163.yaml +++ b/Documentation/devicetree/bindings/display/panel/ilitek,ili9163.yaml @@ -48,10 +48,6 @@ examples: - | #include <dt-bindings/gpio/gpio.h> - backlight: backlight { - compatible = "gpio-backlight"; - gpios = <&gpio 22 GPIO_ACTIVE_HIGH>; - }; spi { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml b/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml index c5d1df680858..e7ab6224b52e 100644 --- a/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml +++ b/Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml @@ -18,6 +18,7 @@ properties: - enum: - bananapi,lhr050h41 - feixin,k101-im2byl02 + - tdo,tl050hdv35 - wanchanglong,w552946aba - const: ilitek,ili9881c diff --git a/Documentation/devicetree/bindings/display/panel/jdi,lpm102a188a.yaml b/Documentation/devicetree/bindings/display/panel/jdi,lpm102a188a.yaml new file mode 100644 index 000000000000..2f4d27a309a7 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/jdi,lpm102a188a.yaml @@ -0,0 +1,94 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/jdi,lpm102a188a.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: JDI LPM102A188A 2560x1800 10.2" DSI Panel + +maintainers: + - Diogo Ivo <diogo.ivo@tecnico.ulisboa.pt> + +description: | + This panel requires a dual-channel DSI host to operate. It supports two modes: + - left-right: each channel drives the left or right half of the screen + - even-odd: each channel drives the even or odd lines of the screen + + Each of the DSI channels controls a separate DSI peripheral. The peripheral + driven by the first link (DSI-LINK1) is considered the primary peripheral + and controls the device. The 'link2' property contains a phandle to the + peripheral driven by the second link (DSI-LINK2). + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: jdi,lpm102a188a + + reg: true + enable-gpios: true + reset-gpios: true + power-supply: true + backlight: true + + ddi-supply: + description: The regulator that provides IOVCC (1.8V). + + link2: + $ref: /schemas/types.yaml#/definitions/phandle + description: | + phandle to the DSI peripheral on the secondary link. Note that the + presence of this property marks the containing node as DSI-LINK1. + +required: + - compatible + - reg + +if: + required: + - link2 +then: + required: + - power-supply + - ddi-supply + - enable-gpios + - reset-gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/gpio/tegra-gpio.h> + + dsia: dsi@54300000 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0x0 0x54300000 0x0 0x00040000>; + + link2: panel@0 { + compatible = "jdi,lpm102a188a"; + reg = <0>; + }; + }; + + dsib: dsi@54400000{ + #address-cells = <1>; + #size-cells = <0>; + reg = <0x0 0x54400000 0x0 0x00040000>; + nvidia,ganged-mode = <&dsia>; + + link1: panel@0 { + compatible = "jdi,lpm102a188a"; + reg = <0>; + power-supply = <&pplcd_vdd>; + ddi-supply = <&pp1800_lcdio>; + enable-gpios = <&gpio TEGRA_GPIO(V, 1) GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio TEGRA_GPIO(V, 2) GPIO_ACTIVE_LOW>; + link2 = <&link2>; + backlight = <&backlight>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/leadtek,ltk050h3146w.yaml b/Documentation/devicetree/bindings/display/panel/leadtek,ltk050h3146w.yaml index 3f6efbb942da..a40ab887ada7 100644 --- a/Documentation/devicetree/bindings/display/panel/leadtek,ltk050h3146w.yaml +++ b/Documentation/devicetree/bindings/display/panel/leadtek,ltk050h3146w.yaml @@ -17,6 +17,7 @@ properties: enum: - leadtek,ltk050h3146w - leadtek,ltk050h3146w-a2 + - leadtek,ltk050h3148w reg: true backlight: true reset-gpios: true diff --git a/Documentation/devicetree/bindings/display/panel/mantix,mlaf057we51-x.yaml b/Documentation/devicetree/bindings/display/panel/mantix,mlaf057we51-x.yaml index a4b8569ab81c..74ff772973d6 100644 --- a/Documentation/devicetree/bindings/display/panel/mantix,mlaf057we51-x.yaml +++ b/Documentation/devicetree/bindings/display/panel/mantix,mlaf057we51-x.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/mantix,mlaf057we51-x.yaml# diff --git a/Documentation/devicetree/bindings/display/panel/newvision,nv3051d.yaml b/Documentation/devicetree/bindings/display/panel/newvision,nv3051d.yaml index 116c1b6030a2..cce775a87f87 100644 --- a/Documentation/devicetree/bindings/display/panel/newvision,nv3051d.yaml +++ b/Documentation/devicetree/bindings/display/panel/newvision,nv3051d.yaml @@ -7,9 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: NewVision NV3051D based LCD panel description: | - The NewVision NV3051D is a driver chip used to drive DSI panels. For now, - this driver only supports the 640x480 panels found in the Anbernic RG353 - based devices. + The NewVision NV3051D is a driver chip used to drive DSI panels. maintainers: - Chris Morgan <macromorgan@hotmail.com> @@ -21,6 +19,7 @@ properties: compatible: items: - enum: + - anbernic,rg351v-panel - anbernic,rg353p-panel - anbernic,rg353v-panel - const: newvision,nv3051d diff --git a/Documentation/devicetree/bindings/display/panel/olimex,lcd-olinuxino.yaml b/Documentation/devicetree/bindings/display/panel/olimex,lcd-olinuxino.yaml index 9f97598efdfa..72463795e4c6 100644 --- a/Documentation/devicetree/bindings/display/panel/olimex,lcd-olinuxino.yaml +++ b/Documentation/devicetree/bindings/display/panel/olimex,lcd-olinuxino.yaml @@ -20,7 +20,7 @@ description: | The panel itself contains: - AT24C16C EEPROM holding panel identification and timing requirements - AR1021 resistive touch screen controller (optional) - - FT5x6 capacitive touch screnn controller (optional) + - FT5x6 capacitive touch screen controller (optional) - GT911/GT928 capacitive touch screen controller (optional) The above chips share same I2C bus. The EEPROM is factory preprogrammed with diff --git a/Documentation/devicetree/bindings/display/panel/orisetech,otm8009a.yaml b/Documentation/devicetree/bindings/display/panel/orisetech,otm8009a.yaml index ad7d3575190e..1e4f140f48b8 100644 --- a/Documentation/devicetree/bindings/display/panel/orisetech,otm8009a.yaml +++ b/Documentation/devicetree/bindings/display/panel/orisetech,otm8009a.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/orisetech,otm8009a.yaml# diff --git a/Documentation/devicetree/bindings/display/panel/panel-common.yaml b/Documentation/devicetree/bindings/display/panel/panel-common.yaml index 5b38dc89cb21..0a57a31f4f3d 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-common.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-common.yaml @@ -12,7 +12,7 @@ maintainers: description: | This document defines device tree properties common to several classes of - display panels. It doesn't constitue a device tree binding specification by + display panels. It doesn't constitute a device tree binding specification by itself but is meant to be referenced by device tree bindings. When referenced from panel device tree bindings the properties defined in this diff --git a/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.yaml b/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.yaml index 4a36aa64c716..f8dc9929e833 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.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/panel-dsi-cm.yaml# diff --git a/Documentation/devicetree/bindings/display/panel/panel-lvds.yaml b/Documentation/devicetree/bindings/display/panel/panel-lvds.yaml index 929fe046d1e7..9f1016551e0b 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-lvds.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-lvds.yaml @@ -40,6 +40,12 @@ properties: items: - enum: - auo,b101ew05 + # Chunghwa Picture Tubes Ltd. 7" WXGA (800x1280) TFT LCD LVDS panel + - chunghwa,claa070wp03xg + # HannStar Display Corp. HSD101PWW2 10.1" WXGA (1280x800) LVDS panel + - hannstar,hsd101pww2 + # Hydis Technologies 7" WXGA (800x1280) TFT LCD LVDS panel + - hydis,hv070wx2-1e0 - tbs,a711-panel - const: panel-lvds diff --git a/Documentation/devicetree/bindings/display/panel/panel-mipi-dbi-spi.yaml b/Documentation/devicetree/bindings/display/panel/panel-mipi-dbi-spi.yaml index 2f0238b770eb..e808215cb39e 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-mipi-dbi-spi.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-mipi-dbi-spi.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/panel-mipi-dbi-spi.yaml# @@ -66,6 +66,7 @@ properties: compatible: items: - enum: + - saef,sftc154b - sainsmart18 - shineworld,lh133k - const: panel-mipi-dbi-spi diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml index 90c04cff8281..73674baea75d 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.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/panel-simple-dsi.yaml# diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple-lvds-dual-ports.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple-lvds-dual-ports.yaml new file mode 100644 index 000000000000..a5a596ff8e75 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/panel-simple-lvds-dual-ports.yaml @@ -0,0 +1,118 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/panel-simple-lvds-dual-ports.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Simple LVDS panels with one power supply and dual LVDS ports + +maintainers: + - Liu Ying <victor.liu@nxp.com> + - Thierry Reding <thierry.reding@gmail.com> + - Sam Ravnborg <sam@ravnborg.org> + +description: | + This binding file is a collection of the LVDS panels that + has dual LVDS ports and requires only a single power-supply. + The first port receives odd pixels, and the second port receives even pixels. + There are optionally a backlight and an enable GPIO. + The panel may use an OF graph binding for the association to the display, + or it may be a direct child node of the display. + + If the panel is more advanced a dedicated binding file is required. + +allOf: + - $ref: panel-common.yaml# + +properties: + + compatible: + enum: + # compatible must be listed in alphabetical order, ordered by compatible. + # The description in the comment is mandatory for each compatible. + + # AU Optronics Corporation 13.3" FHD (1920x1080) TFT LCD panel + - auo,g133han01 + # AU Optronics Corporation 18.5" FHD (1920x1080) TFT LCD panel + - auo,g185han01 + # AU Optronics Corporation 19.0" (1280x1024) TFT LCD panel + - auo,g190ean01 + # Kaohsiung Opto-Electronics Inc. 10.1" WUXGA (1920 x 1200) LVDS TFT LCD panel + - koe,tx26d202vm0bwa + # NLT Technologies, Ltd. 15.6" FHD (1920x1080) LVDS TFT LCD panel + - nlt,nl192108ac18-02d + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: The first sink port. + + properties: + dual-lvds-odd-pixels: + type: boolean + description: The first sink port for odd pixels. + + required: + - dual-lvds-odd-pixels + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: The second sink port. + + properties: + dual-lvds-even-pixels: + type: boolean + description: The second sink port for even pixels. + + required: + - dual-lvds-even-pixels + + required: + - port@0 + - port@1 + + backlight: true + enable-gpios: true + power-supply: true + +additionalProperties: false + +required: + - compatible + - ports + - power-supply + +examples: + - | + panel: panel-lvds { + compatible = "koe,tx26d202vm0bwa"; + power-supply = <&vdd_lcd_reg>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + dual-lvds-odd-pixels; + reg = <0>; + + panel_lvds0_in: endpoint { + remote-endpoint = <&lvds0_out>; + }; + }; + + port@1 { + dual-lvds-even-pixels; + reg = <1>; + + panel_lvds1_in: endpoint { + remote-endpoint = <&lvds1_out>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml index 1d4936fc5182..3ec9ee95045f 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -21,9 +21,9 @@ description: | allOf: - $ref: panel-common.yaml# + - $ref: ../lvds-data-mapping.yaml# properties: - compatible: enum: # compatible must be listed in alphabetical order, ordered by compatible. @@ -65,14 +65,8 @@ properties: - auo,g104sn02 # AU Optronics Corporation 12.1" (1280x800) TFT LCD panel - auo,g121ean01 - # AU Optronics Corporation 13.3" FHD (1920x1080) TFT LCD panel - - auo,g133han01 # AU Optronics Corporation 15.6" (1366x768) TFT LCD panel - auo,g156xtn01 - # AU Optronics Corporation 18.5" FHD (1920x1080) TFT LCD panel - - auo,g185han01 - # AU Optronics Corporation 19.0" (1280x1024) TFT LCD panel - - auo,g190ean01 # AU Optronics Corporation 31.5" FHD (1920x1080) TFT LCD panel - auo,p320hvn03 # AU Optronics Corporation 21.5" FHD (1920x1080) color TFT LCD panel @@ -103,8 +97,6 @@ properties: - cdtech,s070wv95-ct16 # Chefree CH101OLHLWH-002 10.1" (1280x800) color TFT LCD panel - chefree,ch101olhlwh-002 - # Chunghwa Picture Tubes Ltd. 7" WXGA TFT LCD panel - - chunghwa,claa070wp03xg # Chunghwa Picture Tubes Ltd. 10.1" WXGA TFT LCD panel - chunghwa,claa101wa01a # Chunghwa Picture Tubes Ltd. 10.1" WXGA TFT LCD panel @@ -168,8 +160,6 @@ properties: - hannstar,hsd070pww1 # HannStar Display Corp. HSD100PXN1 10.1" XGA LVDS panel - hannstar,hsd100pxn1 - # HannStar Display Corp. HSD101PWW2 10.1" WXGA (1280x800) LVDS panel - - hannstar,hsd101pww2 # Hitachi Ltd. Corporation 9" WVGA (800x480) TFT LCD panel - hit,tx23d38vm0caa # InfoVision Optoelectronics M133NWF4 R0 13.3" FHD (1920x1080) TFT LCD panel @@ -196,6 +186,8 @@ properties: - innolux,n116bge # InnoLux 13.3" FHD (1920x1080) eDP TFT LCD panel - innolux,n125hce-gn1 + # InnoLux 15.6" FHD (1920x1080) TFT LCD panel + - innolux,g156hce-l01 # InnoLux 15.6" WXGA TFT LCD panel - innolux,n156bge-l21 # Innolux P120ZDG-BF1 12.02 inch eDP 2K display panel @@ -206,8 +198,6 @@ properties: - kingdisplay,kd116n21-30nv-a010 # Kaohsiung Opto-Electronics Inc. 5.7" QVGA (320 x 240) TFT LCD panel - koe,tx14d24vm1bpa - # Kaohsiung Opto-Electronics Inc. 10.1" WUXGA (1920 x 1200) LVDS TFT LCD panel - - koe,tx26d202vm0bwa # Kaohsiung Opto-Electronics. TX31D200VM0BAA 12.3" HSXGA LVDS panel - koe,tx31d200vm0baa # Kyocera Corporation 7" WVGA (800x480) transmissive color TFT @@ -240,6 +230,8 @@ properties: - logictechno,lttd800480070-l6wh-rt # Mitsubishi "AA070MC01 7.0" WVGA TFT LCD panel - mitsubishi,aa070mc01-ca1 + # Mitsubishi AA084XE01 8.4" XGA TFT LCD panel + - mitsubishi,aa084xe01 # Multi-Inno Technology Co.,Ltd MI0700S4T-6 7" 800x480 TFT Resistive Touch Module - multi-inno,mi0700s4t-6 # Multi-Inno Technology Co.,Ltd MI0800FT-9 8" 800x600 TFT Resistive Touch Module @@ -256,8 +248,6 @@ properties: - neweast,wjfh116008a # Newhaven Display International 480 x 272 TFT LCD panel - newhaven,nhd-4.3-480272ef-atxl - # NLT Technologies, Ltd. 15.6" FHD (1920x1080) LVDS TFT LCD panel - - nlt,nl192108ac18-02d # New Vision Display 7.0" 800 RGB x 480 TFT LCD panel - nvd,9128 # OKAYA Electric America, Inc. RS800480T-7X0GP 7" WVGA LCD panel @@ -359,6 +349,17 @@ properties: power-supply: true no-hpd: true hpd-gpios: true + data-mapping: true + +if: + not: + properties: + compatible: + contains: + const: innolux,g101ice-l01 +then: + properties: + data-mapping: false additionalProperties: false @@ -378,3 +379,16 @@ examples: }; }; }; + - | + panel_lvds: panel-lvds { + compatible = "innolux,g101ice-l01"; + power-supply = <&vcc_lcd_reg>; + + data-mapping = "jeida-24"; + + port { + panel_in_lvds: endpoint { + remote-endpoint = <<dc_out_lvds>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/raydium,rm68200.yaml b/Documentation/devicetree/bindings/display/panel/raydium,rm68200.yaml index e8ce2315631a..46fe1014ebc4 100644 --- a/Documentation/devicetree/bindings/display/panel/raydium,rm68200.yaml +++ b/Documentation/devicetree/bindings/display/panel/raydium,rm68200.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/raydium,rm68200.yaml# diff --git a/Documentation/devicetree/bindings/display/panel/raydium,rm692e5.yaml b/Documentation/devicetree/bindings/display/panel/raydium,rm692e5.yaml new file mode 100644 index 000000000000..f436ba6738ca --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/raydium,rm692e5.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/raydium,rm692e5.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Raydium RM692E5 based DSI display panels + +maintainers: + - Konrad Dybcio <konradybcio@kernel.org> + +description: + The Raydium RM692E5 is a generic DSI Panel IC used to control + AMOLED panels. + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + items: + - const: fairphone,fp5-rm692e5-boe + - const: raydium,rm692e5 + + dvdd-supply: + description: Digital voltage rail + + vci-supply: + description: Analog voltage rail + + vddio-supply: + description: I/O voltage rail + + reg: true + port: true + +required: + - compatible + - reg + - reset-gpios + - dvdd-supply + - vci-supply + - vddio-supply + - port + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + dsi { + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "fairphone,fp5-rm692e5-boe", "raydium,rm692e5"; + reg = <0>; + + reset-gpios = <&tlmm 44 GPIO_ACTIVE_LOW>; + dvdd-supply = <&vreg_oled_vci>; + vci-supply = <&vreg_l12c>; + vddio-supply = <&vreg_oled_dvdd>; + + port { + panel_in_0: endpoint { + remote-endpoint = <&dsi0_out>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.yaml b/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.yaml index 150e81090af2..97cccd8a8479 100644 --- a/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.yaml +++ b/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.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/rocktech,jh057n00900.yaml# @@ -22,6 +22,8 @@ properties: enum: # Anberic RG353V-V2 5.0" 640x480 TFT LCD panel - anbernic,rg353v-panel-v2 + # Powkiddy RGB30 3.0" 720x720 TFT LCD panel + - powkiddy,rgb30-panel # Rocktech JH057N00900 5.5" 720x1440 TFT LCD panel - rocktech,jh057n00900 # Xingbangda XBD599 5.99" 720x1440 TFT LCD panel diff --git a/Documentation/devicetree/bindings/display/panel/sitronix,st7789v.yaml b/Documentation/devicetree/bindings/display/panel/sitronix,st7789v.yaml index fa6556363cca..ef162b51d010 100644 --- a/Documentation/devicetree/bindings/display/panel/sitronix,st7789v.yaml +++ b/Documentation/devicetree/bindings/display/panel/sitronix,st7789v.yaml @@ -15,17 +15,26 @@ allOf: properties: compatible: - const: sitronix,st7789v + enum: + - edt,et028013dma + - inanbo,t28cp45tn89-v17 + - jasonic,jt240mhqs-hwt-ek-e3 + - sitronix,st7789v reg: true reset-gpios: true power-supply: true backlight: true port: true + rotation: true spi-cpha: true spi-cpol: true + spi-rx-bus-width: + minimum: 0 + maximum: 1 + dc-gpios: maxItems: 1 description: DCX pin, Display data/command selection pin in parallel interface @@ -33,7 +42,6 @@ properties: required: - compatible - reg - - reset-gpios - power-supply unevaluatedProperties: false @@ -52,6 +60,7 @@ examples: reset-gpios = <&pio 6 11 GPIO_ACTIVE_LOW>; backlight = <&pwm_bl>; power-supply = <&power>; + rotation = <180>; spi-max-frequency = <100000>; spi-cpol; spi-cpha; diff --git a/Documentation/devicetree/bindings/display/panel/startek,kd070fhfid015.yaml b/Documentation/devicetree/bindings/display/panel/startek,kd070fhfid015.yaml new file mode 100644 index 000000000000..d817f998cddc --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/startek,kd070fhfid015.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/startek,kd070fhfid015.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Startek Electronic Technology Co. kd070fhfid015 7 inch TFT LCD panel + +maintainers: + - Alexandre Mergnat <amergnat@baylibre.com> + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: startek,kd070fhfid015 + + enable-gpios: true + + iovcc-supply: + description: Reference to the regulator powering the panel IO pins. + + reg: + maxItems: 1 + description: DSI virtual channel + + reset-gpios: true + + port: true + + power-supply: true + +additionalProperties: false + +required: + - compatible + - enable-gpios + - iovcc-supply + - reg + - reset-gpios + - port + - power-supply + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + dsi0 { + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "startek,kd070fhfid015"; + reg = <0>; + enable-gpios = <&pio 67 GPIO_ACTIVE_HIGH>; + reset-gpios = <&pio 20 GPIO_ACTIVE_HIGH>; + iovcc-supply = <&mt6357_vsim1_reg>; + power-supply = <&vsys_lcm_reg>; + + port { + panel_in: endpoint { + remote-endpoint = <&dsi_out>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/visionox,r66451.yaml b/Documentation/devicetree/bindings/display/panel/visionox,r66451.yaml new file mode 100644 index 000000000000..6ba323683921 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/visionox,r66451.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/visionox,r66451.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Visionox R66451 AMOLED DSI Panel + +maintainers: + - Jessica Zhang <quic_jesszhan@quicinc.com> + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: visionox,r66451 + + reg: + maxItems: 1 + description: DSI virtual channel + + vddio-supply: true + vdd-supply: true + port: true + reset-gpios: true + +additionalProperties: false + +required: + - compatible + - reg + - vddio-supply + - vdd-supply + - reset-gpios + - port + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + dsi { + #address-cells = <1>; + #size-cells = <0>; + panel@0 { + compatible = "visionox,r66451"; + reg = <0>; + vddio-supply = <&vreg_l12c_1p8>; + vdd-supply = <&vreg_l13c_3p0>; + + reset-gpios = <&tlmm 24 GPIO_ACTIVE_LOW>; + + port { + panel0_in: endpoint { + remote-endpoint = <&dsi0_out>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/panel/visionox,rm69299.yaml b/Documentation/devicetree/bindings/display/panel/visionox,rm69299.yaml index 444ac2a4772d..fa745a6f4456 100644 --- a/Documentation/devicetree/bindings/display/panel/visionox,rm69299.yaml +++ b/Documentation/devicetree/bindings/display/panel/visionox,rm69299.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,rm69299.yaml# diff --git a/Documentation/devicetree/bindings/display/panel/visionox,vtdr6130.yaml b/Documentation/devicetree/bindings/display/panel/visionox,vtdr6130.yaml index 84562a5b710a..d5a8295106c1 100644 --- a/Documentation/devicetree/bindings/display/panel/visionox,vtdr6130.yaml +++ b/Documentation/devicetree/bindings/display/panel/visionox,vtdr6130.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,vtdr6130.yaml# diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip,dw-mipi-dsi.yaml b/Documentation/devicetree/bindings/display/rockchip/rockchip,dw-mipi-dsi.yaml index 8e8a40879140..ccf79e738fa1 100644 --- a/Documentation/devicetree/bindings/display/rockchip/rockchip,dw-mipi-dsi.yaml +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip,dw-mipi-dsi.yaml @@ -18,6 +18,7 @@ properties: - rockchip,rk3288-mipi-dsi - rockchip,rk3399-mipi-dsi - rockchip,rk3568-mipi-dsi + - rockchip,rv1126-mipi-dsi - const: snps,dw-mipi-dsi interrupts: @@ -77,6 +78,7 @@ allOf: enum: - rockchip,px30-mipi-dsi - rockchip,rk3568-mipi-dsi + - rockchip,rv1126-mipi-dsi then: properties: diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.yaml b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.yaml index df61cb5f5c54..b339b7e708c6 100644 --- a/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.yaml +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.yaml @@ -31,6 +31,7 @@ properties: - rockchip,rk3368-vop - rockchip,rk3399-vop-big - rockchip,rk3399-vop-lit + - rockchip,rv1126-vop reg: minItems: 1 diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip-vop2.yaml b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop2.yaml index fba45091d909..b60b90472d42 100644 --- a/Documentation/devicetree/bindings/display/rockchip/rockchip-vop2.yaml +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop2.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/rockchip/rockchip-vop2.yaml# diff --git a/Documentation/devicetree/bindings/display/sitronix,st7735r.yaml b/Documentation/devicetree/bindings/display/sitronix,st7735r.yaml index 621f27148419..3b0ebc0db8e0 100644 --- a/Documentation/devicetree/bindings/display/sitronix,st7735r.yaml +++ b/Documentation/devicetree/bindings/display/sitronix,st7735r.yaml @@ -54,11 +54,6 @@ examples: - | #include <dt-bindings/gpio/gpio.h> - backlight: backlight { - compatible = "gpio-backlight"; - gpios = <&gpio 44 GPIO_ACTIVE_HIGH>; - }; - spi { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/display/solomon,ssd-common.yaml b/Documentation/devicetree/bindings/display/solomon,ssd-common.yaml new file mode 100644 index 000000000000..3e6998481a75 --- /dev/null +++ b/Documentation/devicetree/bindings/display/solomon,ssd-common.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/solomon,ssd-common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common properties for Solomon OLED Display Controllers + +maintainers: + - Javier Martinez Canillas <javierm@redhat.com> + +properties: + reg: + maxItems: 1 + + reset-gpios: + maxItems: 1 + + # Only required for SPI + dc-gpios: + description: + GPIO connected to the controller's D/C# (Data/Command) pin, + that is needed for 4-wire SPI to tell the controller if the + data sent is for a command register or the display data RAM + maxItems: 1 + + solomon,height: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Height in pixel of the screen driven by the controller. + The default value is controller-dependent. + + solomon,width: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Width in pixel of the screen driven by the controller. + The default value is controller-dependent. + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/display/solomon,ssd1307fb.yaml b/Documentation/devicetree/bindings/display/solomon,ssd1307fb.yaml index 94bb5ef567c6..3afbb52d1b7f 100644 --- a/Documentation/devicetree/bindings/display/solomon,ssd1307fb.yaml +++ b/Documentation/devicetree/bindings/display/solomon,ssd1307fb.yaml @@ -27,38 +27,12 @@ properties: - solomon,ssd1307 - solomon,ssd1309 - reg: - maxItems: 1 - pwms: maxItems: 1 - reset-gpios: - maxItems: 1 - - # Only required for SPI - dc-gpios: - description: - GPIO connected to the controller's D/C# (Data/Command) pin, - that is needed for 4-wire SPI to tell the controller if the - data sent is for a command register or the display data RAM - maxItems: 1 - vbat-supply: description: The supply for VBAT - solomon,height: - $ref: /schemas/types.yaml#/definitions/uint32 - default: 16 - description: - Height in pixel of the screen driven by the controller - - solomon,width: - $ref: /schemas/types.yaml#/definitions/uint32 - default: 96 - description: - Width in pixel of the screen driven by the controller - solomon,page-offset: $ref: /schemas/types.yaml#/definitions/uint32 default: 1 @@ -148,7 +122,7 @@ required: - reg allOf: - - $ref: /schemas/spi/spi-peripheral-props.yaml# + - $ref: solomon,ssd-common.yaml# - if: properties: @@ -157,6 +131,10 @@ allOf: const: sinowealth,sh1106 then: properties: + width: + default: 132 + height: + default: 64 solomon,dclk-div: default: 1 solomon,dclk-frq: @@ -171,6 +149,10 @@ allOf: - solomon,ssd1305 then: properties: + width: + default: 132 + height: + default: 64 solomon,dclk-div: default: 1 solomon,dclk-frq: @@ -185,6 +167,10 @@ allOf: - solomon,ssd1306 then: properties: + width: + default: 128 + height: + default: 64 solomon,dclk-div: default: 1 solomon,dclk-frq: @@ -199,6 +185,10 @@ allOf: - solomon,ssd1307 then: properties: + width: + default: 128 + height: + default: 39 solomon,dclk-div: default: 2 solomon,dclk-frq: @@ -215,6 +205,10 @@ allOf: - solomon,ssd1309 then: properties: + width: + default: 128 + height: + default: 64 solomon,dclk-div: default: 1 solomon,dclk-frq: diff --git a/Documentation/devicetree/bindings/display/solomon,ssd132x.yaml b/Documentation/devicetree/bindings/display/solomon,ssd132x.yaml new file mode 100644 index 000000000000..0aa41bd9ddca --- /dev/null +++ b/Documentation/devicetree/bindings/display/solomon,ssd132x.yaml @@ -0,0 +1,89 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/solomon,ssd132x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Solomon SSD132x OLED Display Controllers + +maintainers: + - Javier Martinez Canillas <javierm@redhat.com> + +properties: + compatible: + - enum: + - solomon,ssd1322 + - solomon,ssd1325 + - solomon,ssd1327 + +required: + - compatible + - reg + +allOf: + - $ref: solomon,ssd-common.yaml# + + - if: + properties: + compatible: + contains: + const: solomon,ssd1322 + then: + properties: + width: + default: 480 + height: + default: 128 + + - if: + properties: + compatible: + contains: + const: solomon,ssd1325 + then: + properties: + width: + default: 128 + height: + default: 80 + + - if: + properties: + compatible: + contains: + const: solomon,ssd1327 + then: + properties: + width: + default: 128 + height: + default: 128 + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + oled@3c { + compatible = "solomon,ssd1327"; + reg = <0x3c>; + reset-gpios = <&gpio2 7>; + }; + + }; + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + oled@0 { + compatible = "solomon,ssd1327"; + reg = <0x0>; + reset-gpios = <&gpio2 7>; + dc-gpios = <&gpio2 8>; + spi-max-frequency = <10000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra124-sor.yaml b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra124-sor.yaml index 70f0e45c71d6..6f2e22471965 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra124-sor.yaml +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra124-sor.yaml @@ -97,7 +97,7 @@ properties: # optional when driving an eDP output nvidia,dpaux: - description: phandle to a DispayPort AUX interface + description: phandle to a DisplayPort AUX interface $ref: /schemas/types.yaml#/definitions/phandle allOf: diff --git a/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml b/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml index b6b402f16161..ae09cd3cbce1 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml +++ b/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml @@ -12,14 +12,18 @@ maintainers: - Tomi Valkeinen <tomi.valkeinen@ti.com> description: | - The AM65x TI Keystone Display SubSystem with two output ports and - two video planes. The first video port supports OLDI and the second - supports DPI format. The fist plane is full video plane with all - features and the second is a "lite plane" without scaling support. + The AM625 and AM65x TI Keystone Display SubSystem with two output + ports and two video planes. In AM65x DSS, the first video port + supports 1 OLDI TX and in AM625 DSS, the first video port output is + internally routed to 2 OLDI TXes. The second video port supports DPI + format. The first plane is full video plane with all features and the + second is a "lite plane" without scaling support. properties: compatible: - const: ti,am65x-dss + enum: + - ti,am625-dss + - ti,am65x-dss reg: description: @@ -80,7 +84,9 @@ properties: port@0: $ref: /schemas/graph.yaml#/properties/port description: - The DSS OLDI output port node form video port 1 + For AM65x DSS, the OLDI output port node from video port 1. + For AM625 DSS, the internal DPI output port node from video + port 1. port@1: $ref: /schemas/graph.yaml#/properties/port diff --git a/Documentation/devicetree/bindings/dma/atmel-xdma.txt b/Documentation/devicetree/bindings/dma/atmel-xdma.txt index 510b7f25ba24..76d649b3a25d 100644 --- a/Documentation/devicetree/bindings/dma/atmel-xdma.txt +++ b/Documentation/devicetree/bindings/dma/atmel-xdma.txt @@ -3,7 +3,8 @@ * XDMA Controller Required properties: - compatible: Should be "atmel,sama5d4-dma", "microchip,sam9x60-dma" or - "microchip,sama7g5-dma". + "microchip,sama7g5-dma" or + "microchip,sam9x7-dma", "atmel,sama5d4-dma". - reg: Should contain DMA registers location and length. - interrupts: Should contain DMA interrupt. - #dma-cells: Must be <1>, used to represent the number of integer cells in diff --git a/Documentation/devicetree/bindings/dma/brcm,bcm2835-dma.txt b/Documentation/devicetree/bindings/dma/brcm,bcm2835-dma.txt deleted file mode 100644 index b6a8cc0978cd..000000000000 --- a/Documentation/devicetree/bindings/dma/brcm,bcm2835-dma.txt +++ /dev/null @@ -1,83 +0,0 @@ -* BCM2835 DMA controller - -The BCM2835 DMA controller has 16 channels in total. -Only the lower 13 channels have an associated IRQ. -Some arbitrary channels are used by the firmware -(1,3,6,7 in the current firmware version). -The channels 0,2 and 3 have special functionality -and should not be used by the driver. - -Required properties: -- compatible: Should be "brcm,bcm2835-dma". -- reg: Should contain DMA registers location and length. -- interrupts: Should contain the DMA interrupts associated - to the DMA channels in ascending order. -- interrupt-names: Should contain the names of the interrupt - in the form "dmaXX". - Use "dma-shared-all" for the common interrupt line - that is shared by all dma channels. -- #dma-cells: Must be <1>, the cell in the dmas property of the - client device represents the DREQ number. -- brcm,dma-channel-mask: Bit mask representing the channels - not used by the firmware in ascending order, - i.e. first channel corresponds to LSB. - -Example: - -dma: dma@7e007000 { - compatible = "brcm,bcm2835-dma"; - reg = <0x7e007000 0xf00>; - interrupts = <1 16>, - <1 17>, - <1 18>, - <1 19>, - <1 20>, - <1 21>, - <1 22>, - <1 23>, - <1 24>, - <1 25>, - <1 26>, - /* dma channel 11-14 share one irq */ - <1 27>, - <1 27>, - <1 27>, - <1 27>, - /* unused shared irq for all channels */ - <1 28>; - interrupt-names = "dma0", - "dma1", - "dma2", - "dma3", - "dma4", - "dma5", - "dma6", - "dma7", - "dma8", - "dma9", - "dma10", - "dma11", - "dma12", - "dma13", - "dma14", - "dma-shared-all"; - - #dma-cells = <1>; - brcm,dma-channel-mask = <0x7f35>; -}; - - -DMA clients connected to the BCM2835 DMA controller must use the format -described in the dma.txt file, using a two-cell specifier for each channel. - -Example: - -bcm2835_i2s: i2s@7e203000 { - compatible = "brcm,bcm2835-i2s"; - reg = < 0x7e203000 0x24>; - clocks = <&clocks BCM2835_CLOCK_PCM>; - - dmas = <&dma 2>, - <&dma 3>; - dma-names = "tx", "rx"; -}; diff --git a/Documentation/devicetree/bindings/dma/brcm,bcm2835-dma.yaml b/Documentation/devicetree/bindings/dma/brcm,bcm2835-dma.yaml new file mode 100644 index 000000000000..c9b9a5490826 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/brcm,bcm2835-dma.yaml @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/brcm,bcm2835-dma.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: BCM2835 DMA controller + +maintainers: + - Nicolas Saenz Julienne <nsaenz@kernel.org> + +description: + The BCM2835 DMA controller has 16 channels in total. Only the lower + 13 channels have an associated IRQ. Some arbitrary channels are used by the + VideoCore firmware (1,3,6,7 in the current firmware version). The channels + 0, 2 and 3 have special functionality and should not be used by the driver. + +allOf: + - $ref: dma-controller.yaml# + +properties: + compatible: + const: brcm,bcm2835-dma + + reg: + maxItems: 1 + + interrupts: + description: + Should contain the DMA interrupts associated to the DMA channels in + ascending order. + minItems: 1 + maxItems: 16 + + interrupt-names: + minItems: 1 + maxItems: 16 + + '#dma-cells': + description: The single cell represents the DREQ number. + const: 1 + + brcm,dma-channel-mask: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Bitmask of available DMA channels in ascending order that are + not reserved by firmware and are available to the + kernel. i.e. first channel corresponds to LSB. + +unevaluatedProperties: false + +required: + - compatible + - reg + - interrupts + - "#dma-cells" + - brcm,dma-channel-mask + +examples: + - | + dma-controller@7e007000 { + compatible = "brcm,bcm2835-dma"; + reg = <0x7e007000 0xf00>; + interrupts = <1 16>, + <1 17>, + <1 18>, + <1 19>, + <1 20>, + <1 21>, + <1 22>, + <1 23>, + <1 24>, + <1 25>, + <1 26>, + /* dma channel 11-14 share one irq */ + <1 27>, + <1 27>, + <1 27>, + <1 27>, + /* unused shared irq for all channels */ + <1 28>; + interrupt-names = "dma0", + "dma1", + "dma2", + "dma3", + "dma4", + "dma5", + "dma6", + "dma7", + "dma8", + "dma9", + "dma10", + "dma11", + "dma12", + "dma13", + "dma14", + "dma-shared-all"; + #dma-cells = <1>; + brcm,dma-channel-mask = <0x7f35>; + }; + +... diff --git a/Documentation/devicetree/bindings/dma/fsl,edma.yaml b/Documentation/devicetree/bindings/dma/fsl,edma.yaml index 5fd8fc604261..437db0c62339 100644 --- a/Documentation/devicetree/bindings/dma/fsl,edma.yaml +++ b/Documentation/devicetree/bindings/dma/fsl,edma.yaml @@ -21,32 +21,41 @@ properties: - enum: - fsl,vf610-edma - fsl,imx7ulp-edma + - fsl,imx8qm-adma + - fsl,imx8qm-edma + - fsl,imx93-edma3 + - fsl,imx93-edma4 - items: - const: fsl,ls1028a-edma - const: fsl,vf610-edma reg: - minItems: 2 + minItems: 1 maxItems: 3 interrupts: - minItems: 2 - maxItems: 17 + minItems: 1 + maxItems: 64 interrupt-names: - minItems: 2 - maxItems: 17 + minItems: 1 + maxItems: 64 "#dma-cells": - const: 2 + enum: + - 2 + - 3 dma-channels: - const: 32 + minItems: 1 + maxItems: 64 clocks: + minItems: 1 maxItems: 2 clock-names: + minItems: 1 maxItems: 2 big-endian: @@ -69,21 +78,52 @@ allOf: properties: compatible: contains: + enum: + - fsl,imx8qm-adma + - fsl,imx8qm-edma + - fsl,imx93-edma3 + - fsl,imx93-edma4 + then: + properties: + "#dma-cells": + const: 3 + # It is not necessary to write the interrupt name for each channel. + # instead, you can simply maintain the sequential IRQ numbers as + # defined for the DMA channels. + interrupt-names: false + clock-names: + items: + - const: dma + clocks: + maxItems: 1 + + - if: + properties: + compatible: + contains: const: fsl,vf610-edma then: properties: + clocks: + minItems: 2 clock-names: items: - const: dmamux0 - const: dmamux1 interrupts: + minItems: 2 maxItems: 2 interrupt-names: items: - const: edma-tx - const: edma-err reg: + minItems: 2 maxItems: 3 + "#dma-cells": + const: 2 + dma-channels: + const: 32 - if: properties: @@ -92,14 +132,22 @@ allOf: const: fsl,imx7ulp-edma then: properties: + clock: + minItems: 2 clock-names: items: - const: dma - const: dmamux0 interrupts: + minItems: 2 maxItems: 17 reg: + minItems: 2 maxItems: 2 + "#dma-cells": + const: 2 + dma-channels: + const: 32 unevaluatedProperties: false @@ -153,3 +201,47 @@ examples: clock-names = "dma", "dmamux0"; clocks = <&pcc2 IMX7ULP_CLK_DMA1>, <&pcc2 IMX7ULP_CLK_DMA_MUX1>; }; + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/imx93-clock.h> + + dma-controller@44000000 { + compatible = "fsl,imx93-edma3"; + reg = <0x44000000 0x200000>; + #dma-cells = <3>; + dma-channels = <31>; + interrupts = <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 96 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 97 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 98 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 99 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 100 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 101 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 102 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 103 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 104 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 105 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 106 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 107 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 108 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 109 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 110 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 111 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 112 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 113 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 114 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 115 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 116 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 117 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 118 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 120 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 121 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 122 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 123 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 124 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 125 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk IMX93_CLK_EDMA1_GATE>; + clock-names = "dma"; + }; diff --git a/Documentation/devicetree/bindings/dma/ingenic,dma.yaml b/Documentation/devicetree/bindings/dma/ingenic,dma.yaml index 37400496e086..d9cca3006e73 100644 --- a/Documentation/devicetree/bindings/dma/ingenic,dma.yaml +++ b/Documentation/devicetree/bindings/dma/ingenic,dma.yaml @@ -68,7 +68,7 @@ properties: $ref: /schemas/types.yaml#/definitions/uint32 description: > Bitmask of channels to reserve for devices that need a specific - channel. These channels will only be assigned when explicitely + channel. These channels will only be assigned when explicitly requested by a client. The primary use for this is channels 0 and 1, which can be configured to have special behaviour for NAND/BCH when using programmable firmware. diff --git a/Documentation/devicetree/bindings/dma/nvidia,tegra20-apbdma.txt b/Documentation/devicetree/bindings/dma/nvidia,tegra20-apbdma.txt index c6908e7c42cc..447fb44e7abe 100644 --- a/Documentation/devicetree/bindings/dma/nvidia,tegra20-apbdma.txt +++ b/Documentation/devicetree/bindings/dma/nvidia,tegra20-apbdma.txt @@ -2,7 +2,7 @@ Required properties: - compatible: Should be "nvidia,<chip>-apbdma" -- reg: Should contain DMA registers location and length. This shuld include +- reg: Should contain DMA registers location and length. This should include all of the per-channel registers. - interrupts: Should contain all of the per-channel DMA interrupts. - clocks: Must contain one entry, for the module clock. diff --git a/Documentation/devicetree/bindings/dma/qcom,bam-dma.yaml b/Documentation/devicetree/bindings/dma/qcom,bam-dma.yaml index f1ddcf672261..3ad0d9b1fbc5 100644 --- a/Documentation/devicetree/bindings/dma/qcom,bam-dma.yaml +++ b/Documentation/devicetree/bindings/dma/qcom,bam-dma.yaml @@ -15,13 +15,19 @@ allOf: properties: compatible: - enum: - # APQ8064, IPQ8064 and MSM8960 - - qcom,bam-v1.3.0 - # MSM8974, APQ8074 and APQ8084 - - qcom,bam-v1.4.0 - # MSM8916 and SDM845 - - qcom,bam-v1.7.0 + oneOf: + - enum: + # APQ8064, IPQ8064 and MSM8960 + - qcom,bam-v1.3.0 + # MSM8974, APQ8074 and APQ8084 + - qcom,bam-v1.4.0 + # MSM8916, SDM630 + - qcom,bam-v1.7.0 + - items: + - enum: + # SDM845, SM6115, SM8150, SM8250 and QCM2290 + - qcom,bam-v1.7.4 + - const: qcom,bam-v1.7.0 clocks: maxItems: 1 @@ -38,7 +44,7 @@ properties: iommus: minItems: 1 - maxItems: 4 + maxItems: 6 num-channels: $ref: /schemas/types.yaml#/definitions/uint32 @@ -48,7 +54,7 @@ properties: qcom,controlled-remotely: type: boolean description: - Indicates that the bam is controlled by remote proccessor i.e. execution + Indicates that the bam is controlled by remote processor i.e. execution environment. qcom,ee: @@ -81,6 +87,15 @@ required: - qcom,ee - reg +anyOf: + - required: + - qcom,powered-remotely + - required: + - qcom,controlled-remotely + - required: + - clocks + - clock-names + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/dma/stericsson,dma40.yaml b/Documentation/devicetree/bindings/dma/stericsson,dma40.yaml index 1e5752b19a49..7b94d24d5ef4 100644 --- a/Documentation/devicetree/bindings/dma/stericsson,dma40.yaml +++ b/Documentation/devicetree/bindings/dma/stericsson,dma40.yaml @@ -148,7 +148,7 @@ properties: memcpy-channels: $ref: /schemas/types.yaml#/definitions/uint32-array description: Array of u32 elements indicating which channels on the DMA - engine are elegible for memcpy transfers + engine are eligible for memcpy transfers required: - "#dma-cells" diff --git a/Documentation/devicetree/bindings/dma/xilinx/xilinx_dma.txt b/Documentation/devicetree/bindings/dma/xilinx/xilinx_dma.txt index d1700a5c36bf..590d1948f202 100644 --- a/Documentation/devicetree/bindings/dma/xilinx/xilinx_dma.txt +++ b/Documentation/devicetree/bindings/dma/xilinx/xilinx_dma.txt @@ -49,6 +49,12 @@ Optional properties for AXI DMA and MCDMA: register as configured in h/w. Takes values {8...26}. If the property is missing or invalid then the default value 23 is used. This is the maximum value that is supported by all IP versions. + +Optional properties for AXI DMA: +- xlnx,axistream-connected: Tells whether DMA is connected to AXI stream IP. +- xlnx,irq-delay: Tells the interrupt delay timeout value. Valid range is from + 0-255. Setting this value to zero disables the delay timer interrupt. + 1 timeout interval = 125 * clock period of SG clock. Optional properties for VDMA: - xlnx,flush-fsync: Tells which channel to Flush on Frame sync. It takes following values: diff --git a/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dma-1.0.yaml b/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dma-1.0.yaml index 23ada8f87526..769ce23aaac2 100644 --- a/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dma-1.0.yaml +++ b/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dma-1.0.yaml @@ -13,6 +13,8 @@ description: | maintainers: - Michael Tretter <m.tretter@pengutronix.de> + - Harini Katakam <harini.katakam@amd.com> + - Radhey Shyam Pandey <radhey.shyam.pandey@amd.com> allOf: - $ref: ../dma-controller.yaml# @@ -65,6 +67,7 @@ required: - interrupts - clocks - clock-names + - xlnx,bus-width additionalProperties: false diff --git a/Documentation/devicetree/bindings/eeprom/at24.yaml b/Documentation/devicetree/bindings/eeprom/at24.yaml index 84af0d5f52aa..98139489d4b5 100644 --- a/Documentation/devicetree/bindings/eeprom/at24.yaml +++ b/Documentation/devicetree/bindings/eeprom/at24.yaml @@ -2,8 +2,8 @@ # Copyright 2019 BayLibre SAS %YAML 1.2 --- -$id: "http://devicetree.org/schemas/eeprom/at24.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/eeprom/at24.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: I2C EEPROMs compatible with Atmel's AT24 @@ -102,6 +102,9 @@ properties: # These are special cases that don't conform to the above pattern. # Each requires a standard at24 model as fallback. - items: + - const: belling,bl24c16a + - const: atmel,24c16 + - items: - enum: - rohm,br24g01 - rohm,br24t01 diff --git a/Documentation/devicetree/bindings/eeprom/at25.yaml b/Documentation/devicetree/bindings/eeprom/at25.yaml index 0e31bb36ebb1..1715b0c9feea 100644 --- a/Documentation/devicetree/bindings/eeprom/at25.yaml +++ b/Documentation/devicetree/bindings/eeprom/at25.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause %YAML 1.2 --- -$id: "http://devicetree.org/schemas/eeprom/at25.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/eeprom/at25.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: SPI EEPROMs or FRAMs compatible with Atmel's AT25 diff --git a/Documentation/devicetree/bindings/extcon/maxim,max77843.yaml b/Documentation/devicetree/bindings/extcon/maxim,max77843.yaml index 128960545640..55800fb0221d 100644 --- a/Documentation/devicetree/bindings/extcon/maxim,max77843.yaml +++ b/Documentation/devicetree/bindings/extcon/maxim,max77843.yaml @@ -23,6 +23,7 @@ properties: connector: $ref: /schemas/connector/usb-connector.yaml# + unevaluatedProperties: false ports: $ref: /schemas/graph.yaml#/properties/ports diff --git a/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.yaml b/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.yaml index 2c8cf6aab19a..6b80518cbf62 100644 --- a/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.yaml +++ b/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. PM8941 USB ID Extcon device maintainers: - - Guru Das Srinagesh <gurus@codeaurora.org> + - Guru Das Srinagesh <quic_gurus@quicinc.com> description: | Some Qualcomm PMICs have a "misc" module that can be used to detect when diff --git a/Documentation/devicetree/bindings/extcon/siliconmitus,sm5502-muic.yaml b/Documentation/devicetree/bindings/extcon/siliconmitus,sm5502-muic.yaml index 7a224b2f0977..7ef2d9bef72d 100644 --- a/Documentation/devicetree/bindings/extcon/siliconmitus,sm5502-muic.yaml +++ b/Documentation/devicetree/bindings/extcon/siliconmitus,sm5502-muic.yaml @@ -27,6 +27,10 @@ properties: description: I2C slave address of the device. Usually 0x25 for SM5502 and SM5703, 0x14 for SM5504. + connector: + $ref: /schemas/connector/usb-connector.yaml# + unevaluatedProperties: false + interrupts: maxItems: 1 diff --git a/Documentation/devicetree/bindings/firmware/arm,scmi.yaml b/Documentation/devicetree/bindings/firmware/arm,scmi.yaml index b138f3d23df8..4591523b51a0 100644 --- a/Documentation/devicetree/bindings/firmware/arm,scmi.yaml +++ b/Documentation/devicetree/bindings/firmware/arm,scmi.yaml @@ -38,6 +38,9 @@ properties: with shmem address(4KB-page, offset) as parameters items: - const: arm,scmi-smc-param + - description: SCMI compliant firmware with Qualcomm SMC/HVC transport + items: + - const: qcom,scmi-smc - description: SCMI compliant firmware with SCMI Virtio transport. The virtio transport only supports a single device. items: @@ -149,8 +152,15 @@ properties: '#clock-cells': const: 1 - required: - - '#clock-cells' + '#power-domain-cells': + const: 1 + + oneOf: + - required: + - '#clock-cells' + + - required: + - '#power-domain-cells' protocol@14: $ref: '#/$defs/protocol-node' @@ -306,6 +316,7 @@ else: enum: - arm,scmi-smc - arm,scmi-smc-param + - qcom,scmi-smc then: required: - arm,smc-id diff --git a/Documentation/devicetree/bindings/firmware/intel,ixp4xx-network-processing-engine.yaml b/Documentation/devicetree/bindings/firmware/intel,ixp4xx-network-processing-engine.yaml index 9a785bbaafb7..e6bed7d93e2d 100644 --- a/Documentation/devicetree/bindings/firmware/intel,ixp4xx-network-processing-engine.yaml +++ b/Documentation/devicetree/bindings/firmware/intel,ixp4xx-network-processing-engine.yaml @@ -2,8 +2,8 @@ # Copyright 2019 Linaro Ltd. %YAML 1.2 --- -$id: "http://devicetree.org/schemas/firmware/intel,ixp4xx-network-processing-engine.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/firmware/intel,ixp4xx-network-processing-engine.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Intel IXP4xx Network Processing Engine diff --git a/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.yaml b/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.yaml index 833c07f1685c..c43d17f6e96b 100644 --- a/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.yaml +++ b/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.yaml @@ -57,8 +57,11 @@ description: | "#address-cells" or "#size-cells" property. The shared memory area for the IPC TX and RX between CPU and BPMP are - predefined and work on top of sysram, which is an SRAM inside the - chip. See ".../sram/sram.yaml" for the bindings. + predefined and work on top of either sysram, which is an SRAM inside the + chip, or in normal SDRAM. + See ".../sram/sram.yaml" for the bindings for the SRAM case. + See "../reserved-memory/nvidia,tegra264-bpmp-shmem.yaml" for bindings for + the SDRAM case. properties: compatible: @@ -81,6 +84,11 @@ properties: minItems: 2 maxItems: 2 + memory-region: + description: phandle to reserved memory region used for IPC between + CPU-NS and BPMP. + maxItems: 1 + "#clock-cells": const: 1 @@ -115,10 +123,15 @@ properties: additionalProperties: false +oneOf: + - required: + - memory-region + - required: + - shmem + required: - compatible - mboxes - - shmem - "#clock-cells" - "#power-domain-cells" - "#reset-cells" @@ -165,8 +178,7 @@ examples: <&mc TEGRA186_MEMORY_CLIENT_BPMPDMAW &emc>; interconnect-names = "read", "write", "dma-mem", "dma-write"; iommus = <&smmu TEGRA186_SID_BPMP>; - mboxes = <&hsp_top0 TEGRA_HSP_MBOX_TYPE_DB - TEGRA_HSP_DB_MASTER_BPMP>; + mboxes = <&hsp_top0 TEGRA_HSP_MBOX_TYPE_DB TEGRA_HSP_DB_MASTER_BPMP>; shmem = <&cpu_bpmp_tx>, <&cpu_bpmp_rx>; #clock-cells = <1>; #power-domain-cells = <1>; @@ -184,3 +196,20 @@ examples: #thermal-sensor-cells = <1>; }; }; + + - | + #include <dt-bindings/mailbox/tegra186-hsp.h> + + bpmp { + compatible = "nvidia,tegra186-bpmp"; + interconnects = <&mc TEGRA186_MEMORY_CLIENT_BPMPR &emc>, + <&mc TEGRA186_MEMORY_CLIENT_BPMPW &emc>, + <&mc TEGRA186_MEMORY_CLIENT_BPMPDMAR &emc>, + <&mc TEGRA186_MEMORY_CLIENT_BPMPDMAW &emc>; + interconnect-names = "read", "write", "dma-mem", "dma-write"; + mboxes = <&hsp_top1 TEGRA_HSP_MBOX_TYPE_DB TEGRA_HSP_DB_MASTER_BPMP>; + memory-region = <&dram_cpu_bpmp_mail>; + #clock-cells = <1>; + #power-domain-cells = <1>; + #reset-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.yaml b/Documentation/devicetree/bindings/firmware/qcom,scm.yaml index bdbee58a542b..0613a37a851a 100644 --- a/Documentation/devicetree/bindings/firmware/qcom,scm.yaml +++ b/Documentation/devicetree/bindings/firmware/qcom,scm.yaml @@ -24,6 +24,7 @@ properties: - qcom,scm-apq8064 - qcom,scm-apq8084 - qcom,scm-ipq4019 + - qcom,scm-ipq5018 - qcom,scm-ipq5332 - qcom,scm-ipq6018 - qcom,scm-ipq806x @@ -56,6 +57,7 @@ properties: - qcom,scm-sm6125 - qcom,scm-sm6350 - qcom,scm-sm6375 + - qcom,scm-sm7150 - qcom,scm-sm8150 - qcom,scm-sm8250 - qcom,scm-sm8350 @@ -89,6 +91,14 @@ properties: protocol to handle sleeping SCM calls. maxItems: 1 + qcom,sdi-enabled: + description: + Indicates that the SDI (Secure Debug Image) has been enabled by TZ + by default and it needs to be disabled. + If not disabled WDT assertion or reboot will cause the board to hang + in the debug mode. + type: boolean + qcom,dload-mode: $ref: /schemas/types.yaml#/definitions/phandle-array items: @@ -176,6 +186,7 @@ allOf: contains: enum: - qcom,scm-qdu1000 + - qcom,scm-sc8280xp - qcom,scm-sm8450 - qcom,scm-sm8550 then: diff --git a/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml b/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml index 910bebe6cfa8..822864488dcb 100644 --- a/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml +++ b/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml @@ -38,6 +38,9 @@ properties: - smc - hvc + "#power-domain-cells": + const: 1 + versal_fpga: $ref: /schemas/fpga/xlnx,versal-fpga.yaml# description: Compatible of the FPGA device. @@ -66,6 +69,17 @@ additionalProperties: false examples: - | + #include <dt-bindings/power/xlnx-zynqmp-power.h> + firmware { + zynqmp_firmware: zynqmp-firmware { + #power-domain-cells = <1>; + }; + }; + + sata { + power-domains = <&zynqmp_firmware PD_SATA>; + }; + versal-firmware { compatible = "xlnx,versal-firmware"; method = "smc"; diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.txt b/Documentation/devicetree/bindings/fpga/fpga-region.txt index 6694ef29a267..528df8a0e6d8 100644 --- a/Documentation/devicetree/bindings/fpga/fpga-region.txt +++ b/Documentation/devicetree/bindings/fpga/fpga-region.txt @@ -63,7 +63,7 @@ FPGA Bridge 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 transparantly handles gating the + * 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 @@ -466,7 +466,7 @@ 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 partion +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 diff --git a/Documentation/devicetree/bindings/fsi/ibm,i2cr-fsi-master.yaml b/Documentation/devicetree/bindings/fsi/ibm,i2cr-fsi-master.yaml new file mode 100644 index 000000000000..442cecdc57cb --- /dev/null +++ b/Documentation/devicetree/bindings/fsi/ibm,i2cr-fsi-master.yaml @@ -0,0 +1,41 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/fsi/ibm,i2cr-fsi-master.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: IBM I2C Responder virtual FSI master + +maintainers: + - Eddie James <eajames@linux.ibm.com> + +description: | + The I2C Responder (I2CR) is a an I2C device that's connected to an FSI CFAM + (see fsi.txt). The I2CR translates I2C bus operations to FSI CFAM reads and + writes or SCOM operations, thereby acting as an FSI master. + +properties: + compatible: + enum: + - ibm,i2cr-fsi-master + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + i2cr@20 { + compatible = "ibm,i2cr-fsi-master"; + reg = <0x20>; + }; + }; diff --git a/Documentation/devicetree/bindings/gpio/adi,ds4520-gpio.yaml b/Documentation/devicetree/bindings/gpio/adi,ds4520-gpio.yaml new file mode 100644 index 000000000000..25b3198c4d3e --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/adi,ds4520-gpio.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/adi,ds4520-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: DS4520 I2C GPIO expander + +maintainers: + - Okan Sahin <okan.sahin@analog.com> + +properties: + compatible: + enum: + - adi,ds4520-gpio + + reg: + maxItems: 1 + + gpio-controller: true + + "#gpio-cells": + const: 2 + + ngpios: + minimum: 1 + maximum: 9 + +required: + - compatible + - reg + - gpio-controller + - "#gpio-cells" + - ngpios + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + gpio@50 { + compatible = "adi,ds4520-gpio"; + reg = <0x50>; + ngpios = <9>; + gpio-controller; + #gpio-cells = <2>; + }; + }; diff --git a/Documentation/devicetree/bindings/gpio/brcm,kona-gpio.txt b/Documentation/devicetree/bindings/gpio/brcm,kona-gpio.txt deleted file mode 100644 index 4a63bc96b687..000000000000 --- a/Documentation/devicetree/bindings/gpio/brcm,kona-gpio.txt +++ /dev/null @@ -1,52 +0,0 @@ -Broadcom Kona Family GPIO -========================= - -This GPIO driver is used in the following Broadcom SoCs: - BCM11130, BCM11140, BCM11351, BCM28145, BCM28155 - -The Broadcom GPIO Controller IP can be configured prior to synthesis to -support up to 8 banks of 32 GPIOs where each bank has its own IRQ. The -GPIO controller only supports edge, not level, triggering of interrupts. - -Required properties -------------------- - -- compatible: "brcm,bcm11351-gpio", "brcm,kona-gpio" -- reg: Physical base address and length of the controller's registers. -- interrupts: The interrupt outputs from the controller. There is one GPIO - interrupt per GPIO bank. The number of interrupts listed depends on the - number of GPIO banks on the SoC. The interrupts must be ordered by bank, - starting with bank 0. There is always a 1:1 mapping between banks and - IRQs. -- #gpio-cells: Should be <2>. The first cell is the pin number, the second - cell is used to specify optional parameters: - - bit 0 specifies polarity (0 for normal, 1 for inverted) - See also "gpio-specifier" in .../devicetree/bindings/gpio/gpio.txt. -- #interrupt-cells: Should be <2>. The first cell is the GPIO number. The - second cell is used to specify flags. The following subset of flags is - supported: - - trigger type (bits[1:0]): - 1 = low-to-high edge triggered. - 2 = high-to-low edge triggered. - 3 = low-to-high or high-to-low edge triggered - Valid values are 1, 2, 3 - See also .../devicetree/bindings/interrupt-controller/interrupts.txt. -- gpio-controller: Marks the device node as a GPIO controller. -- interrupt-controller: Marks the device node as an interrupt controller. - -Example: - gpio: gpio@35003000 { - compatible = "brcm,bcm11351-gpio", "brcm,kona-gpio"; - reg = <0x35003000 0x800>; - interrupts = - <GIC_SPI 106 IRQ_TYPE_LEVEL_HIGH - GIC_SPI 115 IRQ_TYPE_LEVEL_HIGH - GIC_SPI 114 IRQ_TYPE_LEVEL_HIGH - GIC_SPI 113 IRQ_TYPE_LEVEL_HIGH - GIC_SPI 112 IRQ_TYPE_LEVEL_HIGH - GIC_SPI 111 IRQ_TYPE_LEVEL_HIGH>; - #gpio-cells = <2>; - #interrupt-cells = <2>; - gpio-controller; - interrupt-controller; - }; diff --git a/Documentation/devicetree/bindings/gpio/brcm,kona-gpio.yaml b/Documentation/devicetree/bindings/gpio/brcm,kona-gpio.yaml new file mode 100644 index 000000000000..296fdd6b8f38 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/brcm,kona-gpio.yaml @@ -0,0 +1,100 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/brcm,kona-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom Kona family GPIO controller + +description: + The Broadcom GPIO Controller IP can be configured prior to synthesis to + support up to 8 banks of 32 GPIOs where each bank has its own IRQ. The + GPIO controller only supports edge, not level, triggering of interrupts. + +maintainers: + - Ray Jui <rjui@broadcom.com> + +properties: + compatible: + items: + - enum: + - brcm,bcm11351-gpio + - brcm,bcm21664-gpio + - brcm,bcm23550-gpio + - const: brcm,kona-gpio + + reg: + maxItems: 1 + + interrupts: + minItems: 4 + maxItems: 6 + description: + The interrupt outputs from the controller. There is one GPIO interrupt + per GPIO bank. The number of interrupts listed depends on the number of + GPIO banks on the SoC. The interrupts must be ordered by bank, starting + with bank 0. There is always a 1:1 mapping between banks and IRQs. + + '#gpio-cells': + const: 2 + + '#interrupt-cells': + const: 2 + + gpio-controller: true + + interrupt-controller: true + +required: + - compatible + - reg + - interrupts + - '#gpio-cells' + - '#interrupt-cells' + - gpio-controller + - interrupt-controller + +allOf: + - if: + properties: + compatible: + contains: + const: brcm,bcm11351-gpio + then: + properties: + interrupts: + minItems: 6 + - if: + properties: + compatible: + contains: + enum: + - brcm,bcm21664-gpio + - brcm,bcm23550-gpio + then: + properties: + interrupts: + maxItems: 4 + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + gpio@35003000 { + compatible = "brcm,bcm11351-gpio", "brcm,kona-gpio"; + reg = <0x35003000 0x800>; + interrupts = <GIC_SPI 106 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 115 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 114 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 113 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 112 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 111 IRQ_TYPE_LEVEL_HIGH>; + #gpio-cells = <2>; + #interrupt-cells = <2>; + gpio-controller; + interrupt-controller; + }; +... diff --git a/Documentation/devicetree/bindings/gpio/fsl-imx-gpio.yaml b/Documentation/devicetree/bindings/gpio/fsl-imx-gpio.yaml index ae18603697d7..918776d16ef3 100644 --- a/Documentation/devicetree/bindings/gpio/fsl-imx-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/fsl-imx-gpio.yaml @@ -19,10 +19,18 @@ properties: - fsl,imx35-gpio - fsl,imx7d-gpio - items: + - enum: + - fsl,imx27-gpio + - const: fsl,imx21-gpio + - items: - const: fsl,imx35-gpio - const: fsl,imx31-gpio - items: - enum: + - fsl,imx25-gpio + - const: fsl,imx35-gpio + - items: + - enum: - fsl,imx50-gpio - fsl,imx51-gpio - fsl,imx53-gpio @@ -32,10 +40,12 @@ properties: - fsl,imx6sx-gpio - fsl,imx6ul-gpio - fsl,imx7d-gpio + - fsl,imx8dxl-gpio - fsl,imx8mm-gpio - fsl,imx8mn-gpio - fsl,imx8mp-gpio - fsl,imx8mq-gpio + - fsl,imx8qm-gpio - fsl,imx8qxp-gpio - fsl,imxrt1050-gpio - fsl,imxrt1170-gpio diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml b/Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml index fa116148ee90..99febb8ea1b6 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml +++ b/Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml @@ -66,6 +66,7 @@ properties: - ti,tca6408 - ti,tca6416 - ti,tca6424 + - ti,tca9538 - ti,tca9539 - ti,tca9554 diff --git a/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml b/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml index 7c2d152e8617..a27f92950257 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml +++ b/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml @@ -20,6 +20,7 @@ description: | properties: compatible: oneOf: + - const: fsl,imx8ulp-gpio - const: fsl,vf610-gpio - items: - const: fsl,imx7ulp-gpio @@ -27,16 +28,18 @@ properties: - items: - enum: - fsl,imx93-gpio - - fsl,imx8ulp-gpio - - const: fsl,imx7ulp-gpio + - fsl,imx95-gpio + - const: fsl,imx8ulp-gpio reg: - description: The first reg tuple represents the PORT module, the second tuple - represents the GPIO module. + minItems: 1 maxItems: 2 interrupts: - maxItems: 1 + items: + - description: GPIO Trustzone non-secure interrupt number + - description: GPIO Trustzone secure interrupt number + minItems: 1 interrupt-controller: true @@ -59,7 +62,8 @@ properties: - const: port gpio-ranges: - maxItems: 1 + minItems: 1 + maxItems: 4 patternProperties: "^.+-hog(-[0-9]+)?$": @@ -77,6 +81,30 @@ required: - "#gpio-cells" - gpio-controller +allOf: + - if: + properties: + compatible: + contains: + enum: + - fsl,vf610-gpio + - fsl,imx7ulp-gpio + then: + properties: + interrupts: + maxItems: 1 + reg: + items: + - description: PORT register base address + - description: GPIO register base address + else: + properties: + interrupts: + minItems: 2 + reg: + items: + - description: GPIO register base address + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/gpio/gpio-xgene-sb.txt b/Documentation/devicetree/bindings/gpio/gpio-xgene-sb.txt index e90fb987e25f..7ddf292db144 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-xgene-sb.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-xgene-sb.txt @@ -27,7 +27,7 @@ Required properties: - gpio-controller: Marks the device node as a GPIO controller. - interrupts: The EXT_INT_0 parent interrupt resource must be listed first. - interrupt-cells: Should be two. - - first cell is 0-N coresponding for EXT_INT_0 to EXT_INT_N. + - first cell is 0-N corresponding for EXT_INT_0 to EXT_INT_N. - second cell is used to specify flags. - interrupt-controller: Marks the device node as an interrupt controller. - apm,nr-gpios: Optional, specify number of gpios pin. diff --git a/Documentation/devicetree/bindings/gpio/gpio_oxnas.txt b/Documentation/devicetree/bindings/gpio/gpio_oxnas.txt deleted file mode 100644 index 966514744df4..000000000000 --- a/Documentation/devicetree/bindings/gpio/gpio_oxnas.txt +++ /dev/null @@ -1,47 +0,0 @@ -* Oxford Semiconductor OXNAS SoC GPIO Controller - -Please refer to gpio.txt for generic information regarding GPIO bindings. - -Required properties: - - compatible: "oxsemi,ox810se-gpio" or "oxsemi,ox820-gpio" - - reg: Base address and length for the device. - - interrupts: The port interrupt shared by all pins. - - gpio-controller: Marks the port as GPIO controller. - - #gpio-cells: Two. The first cell is the pin number and - the second cell is used to specify the gpio polarity as defined in - defined in <dt-bindings/gpio/gpio.h>: - 0 = GPIO_ACTIVE_HIGH - 1 = GPIO_ACTIVE_LOW - - interrupt-controller: Marks the device node as an interrupt controller. - - #interrupt-cells: Two. The first cell is the GPIO number and second cell - is used to specify the trigger type as defined in - <dt-bindings/interrupt-controller/irq.h>: - IRQ_TYPE_EDGE_RISING - IRQ_TYPE_EDGE_FALLING - IRQ_TYPE_EDGE_BOTH - - gpio-ranges: Interaction with the PINCTRL subsystem, it also specifies the - gpio base and count, should be in the format of numeric-gpio-range as - specified in the gpio.txt file. - -Example: - -gpio0: gpio@0 { - compatible = "oxsemi,ox810se-gpio"; - reg = <0x000000 0x100000>; - interrupts = <21>; - #gpio-cells = <2>; - gpio-controller; - interrupt-controller; - #interrupt-cells = <2>; - gpio-ranges = <&pinctrl 0 0 32>; -}; - -keys { - ... - - button-esc { - label = "ESC"; - linux,code = <1>; - gpios = <&gpio0 12 0>; - }; -}; diff --git a/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.txt b/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.txt deleted file mode 100644 index 8dc41ed99685..000000000000 --- a/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.txt +++ /dev/null @@ -1,38 +0,0 @@ -Intel IXP4xx XScale Networking Processors GPIO - -This GPIO controller is found in the Intel IXP4xx processors. -It supports 16 GPIO lines. - -The interrupt portions of the GPIO controller is hierarchical: -the synchronous edge detector is part of the GPIO block, but the -actual enabling/disabling of the interrupt line is done in the -main IXP4xx interrupt controller which has a 1:1 mapping for -the first 12 GPIO lines to 12 system interrupts. - -The remaining 4 GPIO lines can not be used for receiving -interrupts. - -The interrupt parent of this GPIO controller must be the -IXP4xx interrupt controller. - -Required properties: - -- compatible : Should be - "intel,ixp4xx-gpio" -- reg : Should contain registers location and length -- gpio-controller : marks this as a GPIO controller -- #gpio-cells : Should be 2, see gpio/gpio.txt -- interrupt-controller : marks this as an interrupt controller -- #interrupt-cells : a standard two-cell interrupt, see - interrupt-controller/interrupts.txt - -Example: - -gpio0: gpio@c8004000 { - compatible = "intel,ixp4xx-gpio"; - reg = <0xc8004000 0x1000>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; -}; diff --git a/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.yaml b/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.yaml new file mode 100644 index 000000000000..bfcb1f364c3a --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/intel,ixp4xx-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel IXP4xx XScale Networking Processors GPIO Controller + +description: | + This GPIO controller is found in the Intel IXP4xx + processors. It supports 16 GPIO lines. + The interrupt portions of the GPIO controller is hierarchical. + The synchronous edge detector is part of the GPIO block, but the + actual enabling/disabling of the interrupt line is done in the + main IXP4xx interrupt controller which has a 1-to-1 mapping for + the first 12 GPIO lines to 12 system interrupts. + The remaining 4 GPIO lines can not be used for receiving + interrupts. + The interrupt parent of this GPIO controller must be the + IXP4xx interrupt controller. + GPIO 14 and 15 can be used as clock outputs rather than GPIO, + and this can be enabled by a special flag. + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +properties: + compatible: + const: intel,ixp4xx-gpio + + reg: + maxItems: 1 + + gpio-controller: true + + "#gpio-cells": + const: 2 + + interrupt-controller: true + + "#interrupt-cells": + const: 2 + + intel,ixp4xx-gpio14-clkout: + description: If defined, enables clock output on GPIO 14 + instead of GPIO. + type: boolean + + intel,ixp4xx-gpio15-clkout: + description: If defined, enables clock output on GPIO 15 + instead of GPIO. + type: boolean + +required: + - compatible + - reg + - "#gpio-cells" + - interrupt-controller + - "#interrupt-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + gpio@c8004000 { + compatible = "intel,ixp4xx-gpio"; + reg = <0xc8004000 0x1000>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/loongson,ls-gpio.yaml b/Documentation/devicetree/bindings/gpio/loongson,ls-gpio.yaml index fb86e8ce6349..cf3b1b270aa8 100644 --- a/Documentation/devicetree/bindings/gpio/loongson,ls-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/loongson,ls-gpio.yaml @@ -11,9 +11,22 @@ maintainers: properties: compatible: - enum: - - loongson,ls2k-gpio - - loongson,ls7a-gpio + oneOf: + - enum: + - loongson,ls2k-gpio + - loongson,ls2k0500-gpio0 + - loongson,ls2k0500-gpio1 + - loongson,ls2k2000-gpio0 + - loongson,ls2k2000-gpio1 + - loongson,ls2k2000-gpio2 + - loongson,ls3a5000-gpio + - loongson,ls7a-gpio + - items: + - const: loongson,ls2k1000-gpio + - const: loongson,ls2k-gpio + - items: + - const: loongson,ls7a1000-gpio + - const: loongson,ls7a-gpio reg: maxItems: 1 @@ -49,7 +62,7 @@ examples: #include <dt-bindings/interrupt-controller/irq.h> gpio0: gpio@1fe00500 { - compatible = "loongson,ls2k-gpio"; + compatible = "loongson,ls2k1000-gpio", "loongson,ls2k-gpio"; reg = <0x1fe00500 0x38>; ngpios = <64>; #gpio-cells = <2>; diff --git a/Documentation/devicetree/bindings/gpio/snps,dw-apb-gpio.yaml b/Documentation/devicetree/bindings/gpio/snps,dw-apb-gpio.yaml index b391cc1b4590..eefe7b345286 100644 --- a/Documentation/devicetree/bindings/gpio/snps,dw-apb-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/snps,dw-apb-gpio.yaml @@ -9,7 +9,7 @@ title: Synopsys DesignWare APB GPIO controller description: | Synopsys DesignWare GPIO controllers have a configurable number of ports, each of which are intended to be represented as child nodes with the generic - GPIO-controller properties as desribed in this bindings file. + GPIO-controller properties as described in this bindings file. maintainers: - Hoan Tran <hoan@os.amperecomputing.com> @@ -61,6 +61,10 @@ patternProperties: '#gpio-cells': const: 2 + gpio-line-names: + minItems: 1 + maxItems: 32 + ngpios: default: 32 minimum: 1 diff --git a/Documentation/devicetree/bindings/gpio/st,stmpe-gpio.yaml b/Documentation/devicetree/bindings/gpio/st,stmpe-gpio.yaml index 22c0cae73425..4555f1644a4d 100644 --- a/Documentation/devicetree/bindings/gpio/st,stmpe-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/st,stmpe-gpio.yaml @@ -28,6 +28,10 @@ properties: gpio-controller: true + gpio-line-names: + minItems: 1 + maxItems: 24 + interrupt-controller: true st,norequest-mask: diff --git a/Documentation/devicetree/bindings/gpio/ti,omap-gpio.yaml b/Documentation/devicetree/bindings/gpio/ti,omap-gpio.yaml index bd721c839059..7b75d2f92f1b 100644 --- a/Documentation/devicetree/bindings/gpio/ti,omap-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/ti,omap-gpio.yaml @@ -58,14 +58,14 @@ properties: deprecated: true description: Name of the hwmod associated with the GPIO. Needed on some legacy OMAP - SoCs which have not been converted to the ti,sysc interconnect hierarachy. + SoCs which have not been converted to the ti,sysc interconnect hierarchy. ti,no-reset-on-init: $ref: /schemas/types.yaml#/definitions/flag deprecated: true description: Do not reset on init. Used with ti,hwmods on some legacy OMAP SoCs which - have not been converted to the ti,sysc interconnect hierarachy. + have not been converted to the ti,sysc interconnect hierarchy. patternProperties: "^(.+-hog(-[0-9]+)?)$": diff --git a/Documentation/devicetree/bindings/gpio/x-powers,axp209-gpio.yaml b/Documentation/devicetree/bindings/gpio/x-powers,axp209-gpio.yaml index 1638cfe90f1c..5eeb29bcdd21 100644 --- a/Documentation/devicetree/bindings/gpio/x-powers,axp209-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/x-powers,axp209-gpio.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: GPL-2.0 %YAML 1.2 --- -$id: "http://devicetree.org/schemas/gpio/x-powers,axp209-gpio.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/gpio/x-powers,axp209-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: X-Powers AXP209 GPIO diff --git a/Documentation/devicetree/bindings/gpio/xlnx,zynqmp-gpio-modepin.yaml b/Documentation/devicetree/bindings/gpio/xlnx,zynqmp-gpio-modepin.yaml index 18e61aff2185..56143f1fe84a 100644 --- a/Documentation/devicetree/bindings/gpio/xlnx,zynqmp-gpio-modepin.yaml +++ b/Documentation/devicetree/bindings/gpio/xlnx,zynqmp-gpio-modepin.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: "http://devicetree.org/schemas/gpio/xlnx,zynqmp-gpio-modepin.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/gpio/xlnx,zynqmp-gpio-modepin.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: ZynqMP Mode Pin GPIO controller diff --git a/Documentation/devicetree/bindings/gpio/xylon,logicvc-gpio.yaml b/Documentation/devicetree/bindings/gpio/xylon,logicvc-gpio.yaml index a36aec27069c..59c79a6943ec 100644 --- a/Documentation/devicetree/bindings/gpio/xylon,logicvc-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/xylon,logicvc-gpio.yaml @@ -2,8 +2,8 @@ # Copyright 2019 Bootlin %YAML 1.2 --- -$id: "http://devicetree.org/schemas/gpio/xylon,logicvc-gpio.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/gpio/xylon,logicvc-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Xylon LogiCVC GPIO controller diff --git a/Documentation/devicetree/bindings/hwlock/allwinner,sun6i-a31-hwspinlock.yaml b/Documentation/devicetree/bindings/hwlock/allwinner,sun6i-a31-hwspinlock.yaml index 38478dad8b25..584cce3211c0 100644 --- a/Documentation/devicetree/bindings/hwlock/allwinner,sun6i-a31-hwspinlock.yaml +++ b/Documentation/devicetree/bindings/hwlock/allwinner,sun6i-a31-hwspinlock.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/hwlock/allwinner,sun6i-a31-hwspinlock.yaml# diff --git a/Documentation/devicetree/bindings/hwlock/ti,omap-hwspinlock.yaml b/Documentation/devicetree/bindings/hwlock/ti,omap-hwspinlock.yaml index 0a955c7b9706..5ba60d532fcd 100644 --- a/Documentation/devicetree/bindings/hwlock/ti,omap-hwspinlock.yaml +++ b/Documentation/devicetree/bindings/hwlock/ti,omap-hwspinlock.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/hwlock/ti,omap-hwspinlock.yaml# diff --git a/Documentation/devicetree/bindings/hwmon/adi,adm1177.yaml b/Documentation/devicetree/bindings/hwmon/adi,adm1177.yaml index ca2b47320689..2e45364d0543 100644 --- a/Documentation/devicetree/bindings/hwmon/adi,adm1177.yaml +++ b/Documentation/devicetree/bindings/hwmon/adi,adm1177.yaml @@ -27,7 +27,7 @@ properties: shunt-resistor-micro-ohms: description: - The value of curent sense resistor in microohms. If not provided, + The value of current sense resistor in microohms. If not provided, the current reading and overcurrent alert is disabled. adi,shutdown-threshold-microamp: diff --git a/Documentation/devicetree/bindings/hwmon/adi,axi-fan-control.yaml b/Documentation/devicetree/bindings/hwmon/adi,axi-fan-control.yaml index 0cf3ed6212a6..6751f9b643b4 100644 --- a/Documentation/devicetree/bindings/hwmon/adi,axi-fan-control.yaml +++ b/Documentation/devicetree/bindings/hwmon/adi,axi-fan-control.yaml @@ -11,7 +11,7 @@ maintainers: - Nuno Sá <nuno.sa@analog.com> description: |+ - Bindings for the Analog Devices AXI FAN Control driver. Spefications of the + Bindings for the Analog Devices AXI FAN Control driver. Specifications of the core can be found in: https://wiki.analog.com/resources/fpga/docs/axi_fan_control diff --git a/Documentation/devicetree/bindings/hwmon/adi,ltc2991.yaml b/Documentation/devicetree/bindings/hwmon/adi,ltc2991.yaml new file mode 100644 index 000000000000..011e5b65c79c --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/adi,ltc2991.yaml @@ -0,0 +1,128 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- + +$id: http://devicetree.org/schemas/hwmon/adi,ltc2991.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices LTC2991 Octal I2C Voltage, Current and Temperature Monitor + +maintainers: + - Antoniu Miclaus <antoniu.miclaus@analog.com> + +description: | + The LTC2991 is used to monitor system temperatures, voltages and currents. + Through the I2C serial interface, the eight monitors can individually measure + supply voltages and can be paired for differential measurements of current + sense resistors or temperature sensing transistors. + + Datasheet: + https://www.analog.com/en/products/ltc2991.html + +properties: + compatible: + const: adi,ltc2991 + + reg: + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + vcc-supply: true + +patternProperties: + "^channel@[0-3]$": + type: object + description: + Represents the differential/temperature channels. + + properties: + reg: + description: + The channel number. LTC2991 can monitor 4 currents/temperatures. + items: + minimum: 0 + maximum: 3 + + shunt-resistor-micro-ohms: + description: + The value of curent sense resistor in micro ohms. Pin configuration is + set for differential input pair. + + adi,temperature-enable: + description: + Enables temperature readings. Pin configuration is set for remote + diode temperature measurement. + type: boolean + + required: + - reg + + allOf: + - if: + required: + - shunt-resistor-micro-ohms + then: + properties: + adi,temperature-enable: false + + additionalProperties: false + +required: + - compatible + - reg + - vcc-supply + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + hwmon@48 { + compatible = "adi,ltc2991"; + reg = <0x48>; + vcc-supply = <&vcc>; + }; + }; + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + hwmon@48 { + #address-cells = <1>; + #size-cells = <0>; + + compatible = "adi,ltc2991"; + reg = <0x48>; + vcc-supply = <&vcc>; + + channel@0 { + reg = <0x0>; + shunt-resistor-micro-ohms = <100000>; + }; + + channel@1 { + reg = <0x1>; + shunt-resistor-micro-ohms = <100000>; + }; + + channel@2 { + reg = <0x2>; + adi,temperature-enable; + }; + + channel@3 { + reg = <0x3>; + adi,temperature-enable; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/hwmon/adi,ltc2992.yaml b/Documentation/devicetree/bindings/hwmon/adi,ltc2992.yaml index b39c632956e8..0ad12d245656 100644 --- a/Documentation/devicetree/bindings/hwmon/adi,ltc2992.yaml +++ b/Documentation/devicetree/bindings/hwmon/adi,ltc2992.yaml @@ -46,7 +46,7 @@ patternProperties: shunt-resistor-micro-ohms: description: - The value of curent sense resistor in microohms. + The value of current sense resistor in microohms. required: - compatible diff --git a/Documentation/devicetree/bindings/hwmon/adi,max31827.yaml b/Documentation/devicetree/bindings/hwmon/adi,max31827.yaml index 2dc8b07b4d3b..f60e06ab7d0a 100644 --- a/Documentation/devicetree/bindings/hwmon/adi,max31827.yaml +++ b/Documentation/devicetree/bindings/hwmon/adi,max31827.yaml @@ -32,6 +32,68 @@ properties: Must have values in the interval (1.6V; 3.6V) in order for the device to function correctly. + adi,comp-int: + description: + If present interrupt mode is used. If not present comparator mode is used + (default). + type: boolean + + adi,alarm-pol: + description: + Sets the alarms active state. + - 0 = active low + - 1 = active high + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + + adi,fault-q: + description: + Select how many consecutive temperature faults must occur before + overtemperature or undertemperature faults are indicated in the + corresponding status bits. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [1, 2, 4, 8] + + adi,timeout-enable: + description: + Enables timeout. Bus timeout resets the I2C-compatible interface when SCL + is low for more than 30ms (nominal). + type: boolean + +allOf: + - if: + properties: + compatible: + contains: + const: adi,max31829 + + then: + properties: + adi,alarm-pol: + default: 1 + + else: + properties: + adi,alarm-pol: + default: 0 + + - if: + properties: + compatible: + contains: + const: adi,max31827 + + then: + properties: + adi,fault-q: + default: 1 + + else: + properties: + adi,fault-q: + default: 4 + + required: - compatible - reg @@ -49,6 +111,10 @@ examples: compatible = "adi,max31827"; reg = <0x42>; vref-supply = <®_vdd>; + adi,comp-int; + adi,alarm-pol = <0>; + adi,fault-q = <1>; + adi,timeout-enable; }; }; ... diff --git a/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt b/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt index 3ac02988a1a5..8645cd3b867a 100644 --- a/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt +++ b/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt @@ -45,7 +45,7 @@ Required properties for each child node: - aspeed,fan-tach-ch : should specify the Fan tach input channel. integer value in the range 0 through 15, with 0 indicating Fan tach channel 0 and 15 indicating Fan tach channel 15. - Atleast one Fan tach input channel is required. + At least one Fan tach input channel is required. Examples: diff --git a/Documentation/devicetree/bindings/hwmon/iio-hwmon.yaml b/Documentation/devicetree/bindings/hwmon/iio-hwmon.yaml index c54b5986b365..e5b24782f448 100644 --- a/Documentation/devicetree/bindings/hwmon/iio-hwmon.yaml +++ b/Documentation/devicetree/bindings/hwmon/iio-hwmon.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) %YAML 1.2 --- -$id: "http://devicetree.org/schemas/hwmon/iio-hwmon.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/hwmon/iio-hwmon.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: ADC-attached Hardware Sensor diff --git a/Documentation/devicetree/bindings/hwmon/ina3221.txt b/Documentation/devicetree/bindings/hwmon/ina3221.txt deleted file mode 100644 index fa63b6171407..000000000000 --- a/Documentation/devicetree/bindings/hwmon/ina3221.txt +++ /dev/null @@ -1,54 +0,0 @@ -Texas Instruments INA3221 Device Tree Bindings - -1) ina3221 node - Required properties: - - compatible: Must be "ti,ina3221" - - reg: I2C address - - Optional properties: - - ti,single-shot: This chip has two power modes: single-shot (chip takes one - measurement and then shuts itself down) and continuous ( - chip takes continuous measurements). The continuous mode is - more reliable and suitable for hardware monitor type device, - but the single-shot mode is more power-friendly and useful - for battery-powered device which cares power consumptions - while still needs some measurements occasionally. - If this property is present, the single-shot mode will be - used, instead of the default continuous one for monitoring. - - = The node contains optional child nodes for three channels = - = Each child node describes the information of input source = - - - #address-cells: Required only if a child node is present. Must be 1. - - #size-cells: Required only if a child node is present. Must be 0. - -2) child nodes - Required properties: - - reg: Must be 0, 1 or 2, corresponding to IN1, IN2 or IN3 port of INA3221 - - Optional properties: - - label: Name of the input source - - shunt-resistor-micro-ohms: Shunt resistor value in micro-Ohm - -Example: - -ina3221@40 { - compatible = "ti,ina3221"; - reg = <0x40>; - #address-cells = <1>; - #size-cells = <0>; - - input@0 { - reg = <0x0>; - status = "disabled"; - }; - input@1 { - reg = <0x1>; - shunt-resistor-micro-ohms = <5000>; - }; - input@2 { - reg = <0x2>; - label = "VDD_5V"; - shunt-resistor-micro-ohms = <5000>; - }; -}; diff --git a/Documentation/devicetree/bindings/hwmon/jedec,jc42.yaml b/Documentation/devicetree/bindings/hwmon/jedec,jc42.yaml index 0e49b3901161..bf3332153ad8 100644 --- a/Documentation/devicetree/bindings/hwmon/jedec,jc42.yaml +++ b/Documentation/devicetree/bindings/hwmon/jedec,jc42.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/hwmon/jedec,jc42.yaml# diff --git a/Documentation/devicetree/bindings/hwmon/lltc,ltc4151.yaml b/Documentation/devicetree/bindings/hwmon/lltc,ltc4151.yaml index b1a4c235376e..e62aff670478 100644 --- a/Documentation/devicetree/bindings/hwmon/lltc,ltc4151.yaml +++ b/Documentation/devicetree/bindings/hwmon/lltc,ltc4151.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/hwmon/lltc,ltc4151.yaml# diff --git a/Documentation/devicetree/bindings/hwmon/lm75.yaml b/Documentation/devicetree/bindings/hwmon/lm75.yaml index 8226e3b5d028..0b69897f0c63 100644 --- a/Documentation/devicetree/bindings/hwmon/lm75.yaml +++ b/Documentation/devicetree/bindings/hwmon/lm75.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/hwmon/lm75.yaml# diff --git a/Documentation/devicetree/bindings/hwmon/lm87.txt b/Documentation/devicetree/bindings/hwmon/lm87.txt index e1b79903f204..758ff398b67b 100644 --- a/Documentation/devicetree/bindings/hwmon/lm87.txt +++ b/Documentation/devicetree/bindings/hwmon/lm87.txt @@ -18,7 +18,7 @@ optional properties: in7. Otherwise the pin is set as FAN2 input. - vcc-supply: a Phandle for the regulator supplying power, can be - cofigured to measure 5.0V power supply. Default is 3.3V. + configured to measure 5.0V power supply. Default is 3.3V. Example: diff --git a/Documentation/devicetree/bindings/hwmon/ltq-cputemp.txt b/Documentation/devicetree/bindings/hwmon/ltq-cputemp.txt index 33fd00a987c7..473b34c876dd 100644 --- a/Documentation/devicetree/bindings/hwmon/ltq-cputemp.txt +++ b/Documentation/devicetree/bindings/hwmon/ltq-cputemp.txt @@ -1,4 +1,4 @@ -Lantiq cpu temperatur sensor +Lantiq cpu temperature sensor Requires node properties: - compatible value : diff --git a/Documentation/devicetree/bindings/hwmon/microchip,mcp3021.yaml b/Documentation/devicetree/bindings/hwmon/microchip,mcp3021.yaml index 028d6e570131..f5e104c1b0d0 100644 --- a/Documentation/devicetree/bindings/hwmon/microchip,mcp3021.yaml +++ b/Documentation/devicetree/bindings/hwmon/microchip,mcp3021.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/hwmon/microchip,mcp3021.yaml# diff --git a/Documentation/devicetree/bindings/hwmon/moortec,mr75203.yaml b/Documentation/devicetree/bindings/hwmon/moortec,mr75203.yaml index ae4f68d4e696..56db2292f062 100644 --- a/Documentation/devicetree/bindings/hwmon/moortec,mr75203.yaml +++ b/Documentation/devicetree/bindings/hwmon/moortec,mr75203.yaml @@ -42,7 +42,7 @@ properties: reg: items: - description: PVT common registers - - description: PVT temprature sensor registers + - description: PVT temperature sensor registers - description: PVT process detector registers - description: PVT voltage monitor registers @@ -105,7 +105,7 @@ properties: G coefficient for temperature equation. Default for series 5 = 60000 Default for series 6 = 57400 - multipleOf: 1000 + multipleOf: 100 minimum: 1000 $ref: /schemas/types.yaml#/definitions/uint32 @@ -114,7 +114,7 @@ properties: H coefficient for temperature equation. Default for series 5 = 200000 Default for series 6 = 249400 - multipleOf: 1000 + multipleOf: 100 minimum: 1000 $ref: /schemas/types.yaml#/definitions/uint32 @@ -131,7 +131,7 @@ properties: J coefficient for temperature equation. Default for series 5 = -100 Default for series 6 = 0 - multipleOf: 1000 + multipleOf: 100 maximum: 0 $ref: /schemas/types.yaml#/definitions/int32 diff --git a/Documentation/devicetree/bindings/hwmon/national,lm90.yaml b/Documentation/devicetree/bindings/hwmon/national,lm90.yaml index 7b9d48d6d6da..6e59c8fdef30 100644 --- a/Documentation/devicetree/bindings/hwmon/national,lm90.yaml +++ b/Documentation/devicetree/bindings/hwmon/national,lm90.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/hwmon/national,lm90.yaml# diff --git a/Documentation/devicetree/bindings/hwmon/npcm750-pwm-fan.txt b/Documentation/devicetree/bindings/hwmon/npcm750-pwm-fan.txt index 28f43e929f6d..18095ba87a5a 100644 --- a/Documentation/devicetree/bindings/hwmon/npcm750-pwm-fan.txt +++ b/Documentation/devicetree/bindings/hwmon/npcm750-pwm-fan.txt @@ -1,12 +1,16 @@ -Nuvoton NPCM7xx PWM and Fan Tacho controller device +Nuvoton NPCM PWM and Fan Tacho controller device The Nuvoton BMC NPCM7XX supports 8 Pulse-width modulation (PWM) controller outputs and 16 Fan tachometer controller inputs. +The Nuvoton BMC NPCM8XX supports 12 Pulse-width modulation (PWM) +controller outputs and 16 Fan tachometer controller inputs. + Required properties for pwm-fan node - #address-cells : should be 1. - #size-cells : should be 0. - compatible : "nuvoton,npcm750-pwm-fan" for Poleg NPCM7XX. + : "nuvoton,npcm845-pwm-fan" for Arbel NPCM8XX. - reg : specifies physical base address and size of the registers. - reg-names : must contain: * "pwm" for the PWM registers. @@ -23,7 +27,7 @@ Required properties for pwm-fan node fan subnode format: =================== Under fan subnode can be upto 8 child nodes, each child node representing a fan. -Each fan subnode must have one PWM channel and atleast one Fan tach channel. +Each fan subnode must have one PWM channel and at least one Fan tach channel. For PWM channel can be configured cooling-levels to create cooling device. Cooling device could be bound to a thermal zone for the thermal control. diff --git a/Documentation/devicetree/bindings/hwmon/nxp,mc34vr500.yaml b/Documentation/devicetree/bindings/hwmon/nxp,mc34vr500.yaml index 306f67315835..48d654e52114 100644 --- a/Documentation/devicetree/bindings/hwmon/nxp,mc34vr500.yaml +++ b/Documentation/devicetree/bindings/hwmon/nxp,mc34vr500.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/hwmon/nxp,mc34vr500.yaml# diff --git a/Documentation/devicetree/bindings/hwmon/pmbus/infineon,tda38640.yaml b/Documentation/devicetree/bindings/hwmon/pmbus/infineon,tda38640.yaml new file mode 100644 index 000000000000..ded1c115764b --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/pmbus/infineon,tda38640.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- + +$id: http://devicetree.org/schemas/hwmon/pmbus/infineon,tda38640.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Infineon TDA38640 Synchronous Buck Regulator with SVID and I2C + +maintainers: + - Naresh Solanki <naresh.solanki@9elements.com> + +description: | + The Infineon TDA38640 is a 40A Single-voltage Synchronous Buck + Regulator with SVID and I2C designed for Industrial use. + + Datasheet: https://www.infineon.com/dgdl/Infineon-TDA38640-0000-DataSheet-v02_04-EN.pdf?fileId=8ac78c8c80027ecd018042f2337f00c9 + +properties: + compatible: + enum: + - infineon,tda38640 + + reg: + maxItems: 1 + + infineon,en-pin-fixed-level: + description: + Indicates that the chip EN pin is at fixed level or left + unconnected(has internal pull-down). + type: boolean + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + tda38640@40 { + compatible = "infineon,tda38640"; + reg = <0x40>; + }; + }; diff --git a/Documentation/devicetree/bindings/hwmon/sensirion,sht15.yaml b/Documentation/devicetree/bindings/hwmon/sensirion,sht15.yaml index 80df7182ea28..14ac783c9a5f 100644 --- a/Documentation/devicetree/bindings/hwmon/sensirion,sht15.yaml +++ b/Documentation/devicetree/bindings/hwmon/sensirion,sht15.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/hwmon/sensirion,sht15.yaml# diff --git a/Documentation/devicetree/bindings/hwmon/sensirion,shtc1.yaml b/Documentation/devicetree/bindings/hwmon/sensirion,shtc1.yaml index 159238efa9ed..3d14d5fc96c5 100644 --- a/Documentation/devicetree/bindings/hwmon/sensirion,shtc1.yaml +++ b/Documentation/devicetree/bindings/hwmon/sensirion,shtc1.yaml @@ -13,7 +13,7 @@ description: | The SHTC1, SHTW1 and SHTC3 are digital humidity and temperature sensors designed especially for battery-driven high-volume consumer electronics applications. - For further information refere to Documentation/hwmon/shtc1.rst + For further information refer to Documentation/hwmon/shtc1.rst This binding document describes the binding for the hardware monitor portion of the driver. diff --git a/Documentation/devicetree/bindings/hwmon/starfive,jh71x0-temp.yaml b/Documentation/devicetree/bindings/hwmon/starfive,jh71x0-temp.yaml index f5b34528928d..733cba780186 100644 --- a/Documentation/devicetree/bindings/hwmon/starfive,jh71x0-temp.yaml +++ b/Documentation/devicetree/bindings/hwmon/starfive,jh71x0-temp.yaml @@ -27,8 +27,8 @@ properties: clock-names: items: - - const: "sense" - - const: "bus" + - const: sense + - const: bus '#thermal-sensor-cells': const: 0 @@ -39,8 +39,8 @@ properties: reset-names: items: - - const: "sense" - - const: "bus" + - const: sense + - const: bus required: - compatible diff --git a/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml b/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml index 8648877d2d01..378d1f6aeeb3 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml @@ -26,6 +26,7 @@ properties: - ti,ina226 - ti,ina230 - ti,ina231 + - ti,ina237 - ti,ina238 reg: diff --git a/Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml b/Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml new file mode 100644 index 000000000000..5f10f1207d69 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml @@ -0,0 +1,121 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/hwmon/ti,ina3221.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments INA3221 Current and Voltage Monitor + +maintainers: + - Jean Delvare <jdelvare@suse.com> + - Guenter Roeck <linux@roeck-us.net> + +properties: + compatible: + const: ti,ina3221 + + reg: + maxItems: 1 + + ti,single-shot: + description: | + This chip has two power modes: single-shot (chip takes one measurement + and then shuts itself down) and continuous (chip takes continuous + measurements). The continuous mode is more reliable and suitable for + hardware monitor type device, but the single-shot mode is more power- + friendly and useful for battery-powered device which cares power + consumptions while still needs some measurements occasionally. + + If this property is present, the single-shot mode will be used, instead + of the default continuous one for monitoring. + $ref: /schemas/types.yaml#/definitions/flag + + "#address-cells": + description: Required only if a child node is present. + const: 1 + + "#size-cells": + description: Required only if a child node is present. + const: 0 + +patternProperties: + "^input@[0-2]$": + description: The node contains optional child nodes for three channels. + Each child node describes the information of input source. Input channels + default to enabled in the chip. Unless channels are explicitly disabled + in device-tree, input channels will be enabled. + type: object + additionalProperties: false + properties: + reg: + description: Must be 0, 1 and 2, corresponding to the IN1, IN2 or IN3 + ports of the INA3221, respectively. + enum: [ 0, 1, 2 ] + + label: + description: name of the input source + + shunt-resistor-micro-ohms: + description: shunt resistor value in micro-Ohm + + ti,summation-disable: + description: | + The INA3221 has a critical alert pin that can be controlled by the + summation control function. This function adds the single + shunt-voltage conversions for the desired channels in order to + compare the combined sum to the programmed limit. The Shunt-Voltage + Sum Limit register contains the programmed value that is compared + to the value in the Shunt-Voltage Sum register in order to + determine if the total summed limit is exceeded. If the + shunt-voltage sum limit value is exceeded, the critical alert pin + is asserted. + + For the summation limit to have a meaningful value, it is necessary + to use the same shunt-resistor value on all enabled channels. If + this is not the case or if a channel should not be used for + triggering the critical alert pin, then this property can be used + exclude specific channels from the summation control function. + type: boolean + + required: + - reg + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + power-sensor@40 { + compatible = "ti,ina3221"; + reg = <0x40>; + #address-cells = <1>; + #size-cells = <0>; + + input@0 { + reg = <0x0>; + /* + * Input channels are enabled by default in the device and so + * to disable, must be explicitly disabled in device-tree. + */ + status = "disabled"; + }; + + input@1 { + reg = <0x1>; + shunt-resistor-micro-ohms = <5000>; + }; + + input@2 { + reg = <0x2>; + label = "VDD_5V"; + shunt-resistor-micro-ohms = <5000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/hwmon/ti,tmp102.yaml b/Documentation/devicetree/bindings/hwmon/ti,tmp102.yaml index c5a889e3e27b..7e5b62a0215d 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,tmp102.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,tmp102.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/hwmon/ti,tmp102.yaml# diff --git a/Documentation/devicetree/bindings/hwmon/ti,tmp108.yaml b/Documentation/devicetree/bindings/hwmon/ti,tmp108.yaml index dcbc6fbc3b48..8b5307c875ff 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,tmp108.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,tmp108.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/hwmon/ti,tmp108.yaml# diff --git a/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml b/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml index fde5225ce012..cdd1489e0c54 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml @@ -33,7 +33,7 @@ properties: shunt-resistor-micro-ohms: description: | - If 0, the calibration process will be skiped and the current and power + If 0, the calibration process will be skipped and the current and power measurement engine will not work. Temperature and voltage measurement will continue to work. The shunt value also need to respect: rshunt <= pga-gain * 40 * 1000 * 1000. diff --git a/Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml b/Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml index bce68a326919..ebc8d466c1aa 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml @@ -26,7 +26,7 @@ properties: maxItems: 1 shunt-resistor-micro-ohms: - description: The value of curent sense resistor in microohms. + description: The value of current sense resistor in microohms. default: 255000 minimum: 250000 maximum: 255000 diff --git a/Documentation/devicetree/bindings/i2c/cdns,i2c-r1p10.yaml b/Documentation/devicetree/bindings/i2c/cdns,i2c-r1p10.yaml index ff57c5416ebc..9f1d35ce1fe8 100644 --- a/Documentation/devicetree/bindings/i2c/cdns,i2c-r1p10.yaml +++ b/Documentation/devicetree/bindings/i2c/cdns,i2c-r1p10.yaml @@ -48,6 +48,9 @@ properties: default: 16 enum: [2, 4, 8, 16, 32, 64, 128, 256] + power-domains: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt b/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt deleted file mode 100644 index 548a73cde796..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt +++ /dev/null @@ -1,82 +0,0 @@ -GPIO-based I2C Arbitration Using a Challenge & Response Mechanism -================================================================= -This uses GPIO lines and a challenge & response mechanism to arbitrate who is -the master of an I2C bus in a multimaster situation. - -In many cases using GPIOs to arbitrate is not needed and a design can use -the standard I2C multi-master rules. Using GPIOs is generally useful in -the case where there is a device on the bus that has errata and/or bugs -that makes standard multimaster mode not feasible. - -Note that this scheme works well enough but has some downsides: -* It is nonstandard (not using standard I2C multimaster) -* Having two masters on a bus in general makes it relatively hard to debug - problems (hard to tell if i2c issues were caused by one master, another, or - some device on the bus). - - -Algorithm: - -All masters on the bus have a 'bus claim' line which is an output that the -others can see. These are all active low with pull-ups enabled. We'll -describe these lines as: - -- OUR_CLAIM: output from us signaling to other hosts that we want the bus -- THEIR_CLAIMS: output from others signaling that they want the bus - -The basic algorithm is to assert your line when you want the bus, then make -sure that the other side doesn't want it also. A detailed explanation is best -done with an example. - -Let's say we want to claim the bus. We: -1. Assert OUR_CLAIM. -2. Waits a little bit for the other sides to notice (slew time, say 10 - microseconds). -3. Check THEIR_CLAIMS. If none are asserted then the we have the bus and we are - done. -4. Otherwise, wait for a few milliseconds and see if THEIR_CLAIMS are released. -5. If not, back off, release the claim and wait for a few more milliseconds. -6. Go back to 1 (until retry time has expired). - - -Required properties: -- compatible: i2c-arb-gpio-challenge -- our-claim-gpio: The GPIO that we use to claim the bus. -- their-claim-gpios: The GPIOs that the other sides use to claim the bus. - Note that some implementations may only support a single other master. -- I2C arbitration bus node. See i2c-arb.txt in this directory. - -Optional properties: -- slew-delay-us: microseconds to wait for a GPIO to go high. Default is 10 us. -- wait-retry-us: we'll attempt another claim after this many microseconds. - Default is 3000 us. -- wait-free-us: we'll give up after this many microseconds. Default is 50000 us. - - -Example: - i2c@12ca0000 { - compatible = "acme,some-i2c-device"; - #address-cells = <1>; - #size-cells = <0>; - }; - - i2c-arbitrator { - compatible = "i2c-arb-gpio-challenge"; - - i2c-parent = <&{/i2c@12CA0000}>; - - our-claim-gpio = <&gpf0 3 1>; - their-claim-gpios = <&gpe0 4 1>; - slew-delay-us = <10>; - wait-retry-us = <3000>; - wait-free-us = <50000>; - - i2c-arb { - #address-cells = <1>; - #size-cells = <0>; - - i2c@52 { - // Normal I2C device - }; - }; - }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.yaml b/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.yaml new file mode 100644 index 000000000000..b618b5a3433a --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.yaml @@ -0,0 +1,135 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/i2c-arb-gpio-challenge.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: GPIO-based I2C Arbitration Using a Challenge & Response Mechanism + +maintainers: + - Doug Anderson <dianders@chromium.org> + - Peter Rosin <peda@axentia.se> + +description: | + This uses GPIO lines and a challenge & response mechanism to arbitrate who is + the master of an I2C bus in a multimaster situation. + + In many cases using GPIOs to arbitrate is not needed and a design can use the + standard I2C multi-master rules. Using GPIOs is generally useful in the case + where there is a device on the bus that has errata and/or bugs that makes + standard multimaster mode not feasible. + + Note that this scheme works well enough but has some downsides: + * It is nonstandard (not using standard I2C multimaster) + * Having two masters on a bus in general makes it relatively hard to debug + problems (hard to tell if i2c issues were caused by one master, another, + or some device on the bus). + + Algorithm: + All masters on the bus have a 'bus claim' line which is an output that the + others can see. These are all active low with pull-ups enabled. We'll + describe these lines as: + * OUR_CLAIM: output from us signaling to other hosts that we want the bus + * THEIR_CLAIMS: output from others signaling that they want the bus + + The basic algorithm is to assert your line when you want the bus, then make + sure that the other side doesn't want it also. A detailed explanation is + best done with an example. + + Let's say we want to claim the bus. We: + 1. Assert OUR_CLAIM. + 2. Waits a little bit for the other sides to notice (slew time, say 10 + microseconds). + 3. Check THEIR_CLAIMS. If none are asserted then the we have the bus and we + are done. + 4. Otherwise, wait for a few milliseconds and see if THEIR_CLAIMS are released. + 5. If not, back off, release the claim and wait for a few more milliseconds. + 6. Go back to 1 (until retry time has expired). + +properties: + compatible: + const: i2c-arb-gpio-challenge + + i2c-parent: + $ref: /schemas/types.yaml#/definitions/phandle + description: + The I2C bus that this multiplexer's master-side port is connected to. + + our-claim-gpios: + maxItems: 1 + description: + The GPIO that we use to claim the bus. + + slew-delay-us: + default: 10 + description: + Time to wait for a GPIO to go high. + + their-claim-gpios: + minItems: 1 + maxItems: 8 + description: + The GPIOs that the other sides use to claim the bus. Note that some + implementations may only support a single other master. + + wait-free-us: + default: 50000 + description: + We'll give up after this many microseconds. + + wait-retry-us: + default: 3000 + description: + We'll attempt another claim after this many microseconds. + + i2c-arb: + type: object + $ref: /schemas/i2c/i2c-controller.yaml + unevaluatedProperties: false + description: + I2C arbitration bus node. + +required: + - compatible + - i2c-arb + - our-claim-gpios + - their-claim-gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + i2c-arbitrator { + compatible = "i2c-arb-gpio-challenge"; + i2c-parent = <&i2c_4>; + + our-claim-gpios = <&gpf0 3 GPIO_ACTIVE_LOW>; + their-claim-gpios = <&gpe0 4 GPIO_ACTIVE_LOW>; + slew-delay-us = <10>; + wait-retry-us = <3000>; + wait-free-us = <50000>; + + i2c-arb { + #address-cells = <1>; + #size-cells = <0>; + + sbs-battery@b { + compatible = "sbs,sbs-battery"; + reg = <0xb>; + sbs,poll-retry-count = <1>; + }; + + embedded-controller@1e { + compatible = "google,cros-ec-i2c"; + reg = <0x1e>; + interrupts = <6 IRQ_TYPE_LEVEL_HIGH>; + interrupt-parent = <&gpx1>; + pinctrl-names = "default"; + pinctrl-0 = <&ec_irq>; + wakeup-source; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-arb.txt b/Documentation/devicetree/bindings/i2c/i2c-arb.txt deleted file mode 100644 index 59abf9277bdc..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-arb.txt +++ /dev/null @@ -1,35 +0,0 @@ -Common i2c arbitration bus properties. - -- i2c-arb child node - -Required properties for the i2c-arb child node: -- #address-cells = <1>; -- #size-cells = <0>; - -Optional properties for i2c-arb child node: -- Child nodes conforming to i2c bus binding - - -Example : - - /* - An NXP pca9541 I2C bus master selector at address 0x74 - with a NXP pca8574 GPIO expander attached. - */ - - arb@74 { - compatible = "nxp,pca9541"; - reg = <0x74>; - - i2c-arb { - #address-cells = <1>; - #size-cells = <0>; - - gpio@38 { - compatible = "nxp,pca8574"; - reg = <0x38>; - #gpio-cells = <2>; - gpio-controller; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-atr.yaml b/Documentation/devicetree/bindings/i2c/i2c-atr.yaml new file mode 100644 index 000000000000..1939ab339bfc --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-atr.yaml @@ -0,0 +1,34 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/i2c-atr.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common i2c address translator properties + +maintainers: + - Tomi Valkeinen <tomi.valkeinen@ideasonboard.com> + +description: + An I2C Address Translator (ATR) is a device with an I2C slave parent + ("upstream") port and N I2C master child ("downstream") ports, and + forwards transactions from upstream to the appropriate downstream port + with a modified slave address. The address used on the parent bus is + called the "alias" and is (potentially) different from the physical + slave address of the child bus. Address translation is done by the + hardware. + +properties: + i2c-alias-pool: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: + I2C alias pool is a pool of I2C addresses on the main I2C bus that can be + used to access the remote peripherals on the serializer's I2C bus. The + addresses must be available, not used by any other peripheral. Each + remote peripheral is assigned an alias from the pool, and transactions to + that address will be forwarded to the remote peripheral, with the address + translated to the remote peripheral's real address. This property is not + needed if there are no I2C addressable remote peripherals. + +additionalProperties: true +... diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.yaml b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.yaml index 9f1726d0356b..2d7bb998b0e9 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.yaml @@ -4,21 +4,29 @@ $id: http://devicetree.org/schemas/i2c/i2c-mux-pca954x.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: NXP PCA954x I2C bus switch +title: NXP PCA954x I2C and compatible bus switches maintainers: - Laurent Pinchart <laurent.pinchart@ideasonboard.com> description: - The binding supports NXP PCA954x and PCA984x I2C mux/switch devices. - -allOf: - - $ref: /schemas/i2c/i2c-mux.yaml# + The NXP PCA954x and compatible devices are I2C bus + multiplexer/switches that share the same functionality + and register layout. + The devices usually have 4 or 8 child buses, which are + attached to the parent bus by using the SMBus "Send Byte" + command. properties: compatible: oneOf: - enum: + - maxim,max7356 + - maxim,max7357 + - maxim,max7358 + - maxim,max7367 + - maxim,max7368 + - maxim,max7369 - nxp,pca9540 - nxp,pca9542 - nxp,pca9543 @@ -59,10 +67,34 @@ properties: description: if present, overrides i2c-mux-idle-disconnect $ref: /schemas/mux/mux-controller.yaml#/properties/idle-state + vdd-supply: + description: A voltage regulator supplying power to the chip. On PCA9846 + the regulator supplies power to VDD2 (core logic) and optionally to VDD1. + required: - compatible - reg +allOf: + - $ref: /schemas/i2c/i2c-mux.yaml# + - if: + not: + properties: + compatible: + contains: + enum: + - maxim,max7367 + - maxim,max7369 + - nxp,pca9542 + - nxp,pca9543 + - nxp,pca9544 + - nxp,pca9545 + then: + properties: + interrupts: false + "#interrupt-cells": false + interrupt-controller: false + unevaluatedProperties: false examples: @@ -74,11 +106,13 @@ examples: #size-cells = <0>; i2c-mux@74 { - compatible = "nxp,pca9548"; + compatible = "nxp,pca9545"; #address-cells = <1>; #size-cells = <0>; reg = <0x74>; + vdd-supply = <&p3v3>; + interrupt-parent = <&ipic>; interrupts = <17 IRQ_TYPE_LEVEL_LOW>; interrupt-controller; diff --git a/Documentation/devicetree/bindings/i2c/i2c-mxs.yaml b/Documentation/devicetree/bindings/i2c/i2c-mxs.yaml index 21ae7bce038e..171a41407241 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mxs.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-mxs.yaml @@ -9,6 +9,9 @@ title: Freescale MXS Inter IC (I2C) Controller maintainers: - Shawn Guo <shawnguo@kernel.org> +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml# + properties: compatible: enum: @@ -37,7 +40,7 @@ required: - dmas - dma-names -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/i2c/i2c-sprd.txt b/Documentation/devicetree/bindings/i2c/i2c-sprd.txt index 60b7cda15dd2..7b6b3b8d0d11 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-sprd.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-sprd.txt @@ -10,7 +10,7 @@ Required properties: "source" for I2C source (parent) clock, "enable" for I2C module enable clock. - clocks: Should contain a clock specifier for each entry in clock-names. -- clock-frequency: Constains desired I2C bus clock frequency in Hz. +- clock-frequency: Contains desired I2C bus clock frequency in Hz. - #address-cells: Should be 1 to describe address cells for I2C device address. - #size-cells: Should be 0 means no size cell for I2C device address. diff --git a/Documentation/devicetree/bindings/i2c/nxp,pca9541.txt b/Documentation/devicetree/bindings/i2c/nxp,pca9541.txt deleted file mode 100644 index 42bfc09c8918..000000000000 --- a/Documentation/devicetree/bindings/i2c/nxp,pca9541.txt +++ /dev/null @@ -1,29 +0,0 @@ -* NXP PCA9541 I2C bus master selector - -Required Properties: - - - compatible: Must be "nxp,pca9541" - - - reg: The I2C address of the device. - - The following required properties are defined externally: - - - I2C arbitration bus node. See i2c-arb.txt in this directory. - - -Example: - - i2c-arbitrator@74 { - compatible = "nxp,pca9541"; - reg = <0x74>; - - i2c-arb { - #address-cells = <1>; - #size-cells = <0>; - - eeprom@54 { - compatible = "atmel,24c08"; - reg = <0x54>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/i2c/nxp,pca9541.yaml b/Documentation/devicetree/bindings/i2c/nxp,pca9541.yaml new file mode 100644 index 000000000000..b65c25c1a435 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/nxp,pca9541.yaml @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/nxp,pca9541.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP PCA9541 I2C bus master selector + +maintainers: + - Peter Rosin <peda@axentia.se> + +properties: + compatible: + const: nxp,pca9541 + + reg: + maxItems: 1 + + i2c-arb: + type: object + $ref: /schemas/i2c/i2c-controller.yaml + unevaluatedProperties: false + description: + I2C arbitration bus node. + +required: + - compatible + - reg + - i2c-arb + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + i2c-arbitrator@74 { + compatible = "nxp,pca9541"; + reg = <0x74>; + + i2c-arb { + #address-cells = <1>; + #size-cells = <0>; + + eeprom@54 { + compatible = "atmel,24c08"; + reg = <0x54>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml b/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml index ec79b7270437..042d4dc636ee 100644 --- a/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml +++ b/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml @@ -269,6 +269,7 @@ examples: port { ov7251_ep: endpoint { data-lanes = <0 1>; + link-frequencies = /bits/ 64 <240000000 319200000>; remote-endpoint = <&csiphy3_ep>; }; }; diff --git a/Documentation/devicetree/bindings/i3c/i3c.yaml b/Documentation/devicetree/bindings/i3c/i3c.yaml index fdb4212149e7..d9483fbd2454 100644 --- a/Documentation/devicetree/bindings/i3c/i3c.yaml +++ b/Documentation/devicetree/bindings/i3c/i3c.yaml @@ -55,6 +55,12 @@ properties: May not be supported by all controllers. + mctp-controller: + type: boolean + description: | + Indicates that the system is accessible via this bus as an endpoint for + MCTP over I3C transport. + required: - "#address-cells" - "#size-cells" @@ -135,9 +141,10 @@ patternProperties: minimum: 0x1 maximum: 0xff description: | - Dynamic address to be assigned to this device. This property is only - valid if the I3C device has a static address (first cell of the reg - property != 0). + Dynamic address to be assigned to this device. In case static address is + present (first cell of the reg property != 0), this address is assigned + through SETDASA. If static address is not present, this address is assigned + through SETNEWDA after assigning a temporary address via ENTDAA. required: - reg @@ -163,12 +170,18 @@ examples: pagesize = <0x8>; }; - /* I3C device with a static I2C address. */ + /* I3C device with a static I2C address and assigned address. */ thermal_sensor: sensor@68,39200144004 { reg = <0x68 0x392 0x144004>; assigned-address = <0xa>; }; + /* I3C device with only assigned address. */ + pressure_sensor: sensor@0,39200124004 { + reg = <0x0 0x392 0x124000>; + assigned-address = <0xc>; + }; + /* * I3C device without a static I2C address but requiring * resources described in the DT. diff --git a/Documentation/devicetree/bindings/i3c/mipi-i3c-hci.yaml b/Documentation/devicetree/bindings/i3c/mipi-i3c-hci.yaml index c002afdbfc7c..5dda8cb44cdb 100644 --- a/Documentation/devicetree/bindings/i3c/mipi-i3c-hci.yaml +++ b/Documentation/devicetree/bindings/i3c/mipi-i3c-hci.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) %YAML 1.2 --- -$id: "http://devicetree.org/schemas/i3c/mipi-i3c-hci.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/i3c/mipi-i3c-hci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: MIPI I3C HCI diff --git a/Documentation/devicetree/bindings/iio/accel/fsl,mma7455.yaml b/Documentation/devicetree/bindings/iio/accel/fsl,mma7455.yaml index c8659c5eba2a..cb31e75ba680 100644 --- a/Documentation/devicetree/bindings/iio/accel/fsl,mma7455.yaml +++ b/Documentation/devicetree/bindings/iio/accel/fsl,mma7455.yaml @@ -36,8 +36,8 @@ properties: maxItems: 2 items: enum: - - "INT1" - - "INT2" + - INT1 + - INT2 required: - compatible diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml index 7cc4ddc4e9b7..2aa1f4b063eb 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml @@ -61,7 +61,7 @@ patternProperties: required: - reg - additionalProperties: true + additionalProperties: false allOf: - $ref: /schemas/spi/spi-peripheral-props.yaml# diff --git a/Documentation/devicetree/bindings/iio/adc/allwinner,sun20i-d1-gpadc.yaml b/Documentation/devicetree/bindings/iio/adc/allwinner,sun20i-d1-gpadc.yaml new file mode 100644 index 000000000000..7ef46c90ebc8 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/allwinner,sun20i-d1-gpadc.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/allwinner,sun20i-d1-gpadc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner D1 General Purpose ADC + +maintainers: + - Maksim Kiselev <bigunclemax@gmail.com> + +properties: + compatible: + enum: + - allwinner,sun20i-d1-gpadc + + "#io-channel-cells": + const: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + clocks: + maxItems: 1 + + interrupts: + maxItems: 1 + + reg: + maxItems: 1 + + resets: + maxItems: 1 + +patternProperties: + "^channel@[0-9a-f]+$": + $ref: adc.yaml + type: object + description: + Represents the internal channels of the ADC. + + properties: + reg: + items: + minimum: 0 + maximum: 15 + + required: + - reg + + unevaluatedProperties: false + +required: + - "#io-channel-cells" + - clocks + - compatible + - interrupts + - reg + - resets + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/sun20i-d1-ccu.h> + #include <dt-bindings/reset/sun20i-d1-ccu.h> + #include <dt-bindings/interrupt-controller/irq.h> + + gpadc: adc@2009000 { + compatible = "allwinner,sun20i-d1-gpadc"; + reg = <0x2009000 0x400>; + clocks = <&ccu CLK_BUS_GPADC>; + resets = <&ccu RST_BUS_GPADC>; + interrupts = <73 IRQ_TYPE_LEVEL_HIGH>; + #io-channel-cells = <1>; + + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + reg = <0>; + }; + + channel@1 { + reg = <1>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/adc/atmel,sama9260-adc.yaml b/Documentation/devicetree/bindings/iio/adc/atmel,sama9260-adc.yaml index e6a1f915b542..1f30a8569187 100644 --- a/Documentation/devicetree/bindings/iio/adc/atmel,sama9260-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/atmel,sama9260-adc.yaml @@ -56,8 +56,8 @@ properties: String corresponding to an identifier from atmel,adc-res-names property. If not specified, the highest resolution will be used. enum: - - "lowres" - - "highres" + - lowres + - highres atmel,adc-sleep-mode: $ref: /schemas/types.yaml#/definitions/flag diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml index 2127d639a768..e004659099c1 100644 --- a/Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml +++ b/Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml @@ -78,9 +78,9 @@ patternProperties: ti,datarate: $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 - maximum: 6 + maximum: 7 description: | - Data acquisition rate in samples per second + Data acquisition rate in samples per second for ADS1015, TLA2024 0: 128 1: 250 2: 490 @@ -88,6 +88,17 @@ patternProperties: 4: 1600 (default) 5: 2400 6: 3300 + 7: 3300 + + Data acquisition rate in samples per second for ADS1115 + 0: 8 + 1: 16 + 2: 32 + 3: 64 + 4: 128 (default) + 5: 250 + 6: 475 + 7: 860 required: - reg diff --git a/Documentation/devicetree/bindings/iio/adc/xlnx,zynqmp-ams.yaml b/Documentation/devicetree/bindings/iio/adc/xlnx,zynqmp-ams.yaml index be93c109d6ac..8cbad7e792b6 100644 --- a/Documentation/devicetree/bindings/iio/adc/xlnx,zynqmp-ams.yaml +++ b/Documentation/devicetree/bindings/iio/adc/xlnx,zynqmp-ams.yaml @@ -57,7 +57,7 @@ description: | |27 |FPD Internal voltage measurement, VCC_PSINTFP (supply5). |Voltage |28 |PS Auxiliary voltage measurement (supply6). |Voltage |29 |PL VCCADC voltage measurement (vccams). |Voltage - |30 |Differential analog input signal voltage measurment. |Voltage + |30 |Differential analog input signal voltage measurement. |Voltage |31 |VUser0 voltage measurement (supply7). |Voltage |32 |VUser1 voltage measurement (supply8). |Voltage |33 |VUser2 voltage measurement (supply9). |Voltage diff --git a/Documentation/devicetree/bindings/iio/addac/adi,ad74115.yaml b/Documentation/devicetree/bindings/iio/addac/adi,ad74115.yaml index 72d2e910f206..2a04906531fb 100644 --- a/Documentation/devicetree/bindings/iio/addac/adi,ad74115.yaml +++ b/Documentation/devicetree/bindings/iio/addac/adi,ad74115.yaml @@ -32,7 +32,8 @@ properties: spi-cpol: true - reset-gpios: true + reset-gpios: + maxItems: 1 interrupts: minItems: 1 @@ -216,7 +217,6 @@ properties: description: Whether to enable burnout current for EXT1. adi,ext1-burnout-current-nanoamp: - $ref: /schemas/types.yaml#/definitions/uint32 description: Burnout current in nanoamps to be applied to EXT1. enum: [0, 50, 500, 1000, 10000] @@ -233,7 +233,6 @@ properties: description: Whether to enable burnout current for EXT2. adi,ext2-burnout-current-nanoamp: - $ref: /schemas/types.yaml#/definitions/uint32 description: Burnout current in nanoamps to be applied to EXT2. enum: [0, 50, 500, 1000, 10000] default: 0 @@ -249,7 +248,6 @@ properties: description: Whether to enable burnout current for VIOUT. adi,viout-burnout-current-nanoamp: - $ref: /schemas/types.yaml#/definitions/uint32 description: Burnout current in nanoamps to be applied to VIOUT. enum: [0, 1000, 10000] default: 0 diff --git a/Documentation/devicetree/bindings/iio/cdc/adi,ad7150.yaml b/Documentation/devicetree/bindings/iio/cdc/adi,ad7150.yaml index 2155d3f5666c..3d7074fd17be 100644 --- a/Documentation/devicetree/bindings/iio/cdc/adi,ad7150.yaml +++ b/Documentation/devicetree/bindings/iio/cdc/adi,ad7150.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/iio/cdc/adi,ad7150.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Analog device AD7150 and similar capacitance to digital convertors. +title: Analog device AD7150 and similar capacitance to digital converters. maintainers: - Jonathan Cameron <jic23@kernel.org> diff --git a/Documentation/devicetree/bindings/iio/common.yaml b/Documentation/devicetree/bindings/iio/common.yaml index f845b41d74c4..b3a10af86d76 100644 --- a/Documentation/devicetree/bindings/iio/common.yaml +++ b/Documentation/devicetree/bindings/iio/common.yaml @@ -12,7 +12,7 @@ maintainers: description: | This document defines device tree properties common to several iio - sensors. It doesn't constitue a device tree binding specification by itself but + sensors. It doesn't constitute a device tree binding specification by itself but is meant to be referenced by device tree bindings. When referenced from sensor tree bindings the properties defined in this diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5758.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5758.yaml index 4e508bfcc9d8..5121685337b5 100644 --- a/Documentation/devicetree/bindings/iio/dac/adi,ad5758.yaml +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5758.yaml @@ -78,7 +78,8 @@ properties: - const: -1000 - const: 22000 - reset-gpios: true + reset-gpios: + maxItems: 1 adi,dc-dc-ilim-microamp: enum: [150000, 200000, 250000, 300000, 350000, 400000] diff --git a/Documentation/devicetree/bindings/iio/dac/microchip,mcp4728.yaml b/Documentation/devicetree/bindings/iio/dac/microchip,mcp4728.yaml new file mode 100644 index 000000000000..99831d7f1c16 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/microchip,mcp4728.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- + +$id: http://devicetree.org/schemas/iio/dac/microchip,mcp4728.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip MCP4728 DAC + +maintainers: + - Andrea Collamati <andrea.collamati@gmail.com> + +description: | + MCP4728 is a quad channel, 12-bit voltage output + Digital-to-Analog Converter with non-volatile + memory and I2C compatible Serial Interface. + https://www.microchip.com/en-us/product/mcp4728 + +properties: + compatible: + const: microchip,mcp4728 + + reg: + maxItems: 1 + + vdd-supply: + description: | + Provides both power and acts as the reference supply on the MCP4728 + when Internal Vref is not selected. + +required: + - compatible + - reg + - vdd-supply + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + dac@60 { + compatible = "microchip,mcp4728"; + reg = <0x60>; + vdd-supply = <&vdac_vdd>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/frequency/adi,admv1013.yaml b/Documentation/devicetree/bindings/iio/frequency/adi,admv1013.yaml index fc813bcb6532..f2eb2287ed9e 100644 --- a/Documentation/devicetree/bindings/iio/frequency/adi,admv1013.yaml +++ b/Documentation/devicetree/bindings/iio/frequency/adi,admv1013.yaml @@ -39,6 +39,46 @@ properties: description: Analog voltage regulator. + vcc-drv-supply: + description: + RF Driver voltage regulator. + + vcc2-drv-supply: + description: + RF predriver voltage regulator. + + vcc-vva-supply: + description: + VVA Control Circuit voltage regulator. + + vcc-amp1-supply: + description: + RF Amplifier 1 voltage regulator. + + vcc-amp2-supply: + description: + RF Amplifier 2 voltage regulator. + + vcc-env-supply: + description: + Envelope Detector voltage regulator. + + vcc-bg-supply: + description: + Mixer Chip Band Gap Circuit voltage regulator. + + vcc-bg2-supply: + description: + VGA Chip Band Gap Circuit voltage regulator. + + vcc-mixer-supply: + description: + Mixer voltage regulator. + + vcc-quad-supply: + description: + Quadruppler voltage regulator. + adi,detector-enable: description: Enable the Envelope Detector available at output pins VENV_P and @@ -69,6 +109,16 @@ required: - clocks - clock-names - vcm-supply + - vcc-drv-supply + - vcc2-drv-supply + - vcc-vva-supply + - vcc-amp1-supply + - vcc-amp2-supply + - vcc-env-supply + - vcc-bg-supply + - vcc-bg2-supply + - vcc-mixer-supply + - vcc-quad-supply allOf: - $ref: /schemas/spi/spi-peripheral-props.yaml# @@ -87,6 +137,16 @@ examples: clocks = <&admv1013_lo>; clock-names = "lo_in"; vcm-supply = <&vcm>; + vcc-drv-supply = <&vcc_drv>; + vcc2-drv-supply = <&vcc2_drv>; + vcc-vva-supply = <&vcc_vva>; + vcc-amp1-supply = <&vcc_amp1>; + vcc-amp2-supply = <&vcc_amp2>; + vcc-env-supply = <&vcc_env>; + vcc-bg-supply = <&vcc_bg>; + vcc-bg2-supply = <&vcc_bg2>; + vcc-mixer-supply = <&vcc_mixer>; + vcc-quad-supply = <&vcc_quad>; adi,quad-se-mode = "diff"; adi,detector-enable; }; diff --git a/Documentation/devicetree/bindings/iio/frequency/adi,admv1014.yaml b/Documentation/devicetree/bindings/iio/frequency/adi,admv1014.yaml index ab86daa2c56e..39cc63a11762 100644 --- a/Documentation/devicetree/bindings/iio/frequency/adi,admv1014.yaml +++ b/Documentation/devicetree/bindings/iio/frequency/adi,admv1014.yaml @@ -33,7 +33,7 @@ properties: items: - const: lo_in description: - External clock that provides the Local Oscilator input. + External clock that provides the Local Oscillator input. vcm-supply: description: @@ -103,6 +103,14 @@ required: - clocks - clock-names - vcm-supply + - vcc-if-bb-supply + - vcc-vga-supply + - vcc-vva-supply + - vcc-lna-3p3-supply + - vcc-lna-1p5-supply + - vcc-bg-supply + - vcc-quad-supply + - vcc-mixer-supply allOf: - $ref: /schemas/spi/spi-peripheral-props.yaml# diff --git a/Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml b/Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml index b9b5beac33b2..5b6cde86b5a5 100644 --- a/Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml +++ b/Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml @@ -23,7 +23,8 @@ properties: maxItems: 1 description: Connected to ADC_RDY pin. - reset-gpios: true + reset-gpios: + maxItems: 1 required: - compatible diff --git a/Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml b/Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml index 2958c4ca75b4..167d10bd60af 100644 --- a/Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml +++ b/Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml @@ -23,7 +23,8 @@ properties: maxItems: 1 description: Connected to ADC_RDY pin. - reset-gpios: true + reset-gpios: + maxItems: 1 additionalProperties: false diff --git a/Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml b/Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml index a2bc1fa92da0..79e75a8675cb 100644 --- a/Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml +++ b/Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml @@ -10,7 +10,7 @@ maintainers: - Eugene Zaikonnikov <ez@norophonic.com> description: | - Relative humidity and tempereature sensors on I2C bus + Relative humidity and temperature sensors on I2C bus Datasheets are available at: http://www.ti.com/product/HDC2010/datasheet diff --git a/Documentation/devicetree/bindings/iio/light/rohm,bu27010.yaml b/Documentation/devicetree/bindings/iio/light/rohm,bu27010.yaml new file mode 100644 index 000000000000..bed42d5d0d94 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/rohm,bu27010.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/light/rohm,bu27010.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ROHM BU27010 color sensor + +maintainers: + - Matti Vaittinen <mazziesaccount@gmail.com> + +description: | + The ROHM BU27010 is a sensor with 6 photodiodes (red, green, blue, clear, + IR and flickering detection) with five configurable channels. Red, green + and flickering detection being always available and two out of the rest + three (blue, clear, IR) can be selected to be simultaneously measured. + Typical application is adjusting LCD/OLED backlight of TVs, mobile phones + and tablet PCs. + +properties: + compatible: + const: rohm,bu27010 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + vdd-supply: true + +required: + - compatible + - reg + - vdd-supply + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + light-sensor@38 { + compatible = "rohm,bu27010"; + reg = <0x38>; + vdd-supply = <&vdd>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/pressure/honeywell,mprls0025pa.yaml b/Documentation/devicetree/bindings/iio/pressure/honeywell,mprls0025pa.yaml index c0a923febf13..b31f8120f14e 100644 --- a/Documentation/devicetree/bindings/iio/pressure/honeywell,mprls0025pa.yaml +++ b/Documentation/devicetree/bindings/iio/pressure/honeywell,mprls0025pa.yaml @@ -47,7 +47,7 @@ properties: reset-gpios: description: Optional GPIO for resetting the device. - If not present the device is not resetted during the probe. + If not present the device is not reset during the probe. maxItems: 1 honeywell,pmin-pascal: diff --git a/Documentation/devicetree/bindings/iio/proximity/ams,as3935.yaml b/Documentation/devicetree/bindings/iio/proximity/ams,as3935.yaml index c999994e19e3..9567993ce480 100644 --- a/Documentation/devicetree/bindings/iio/proximity/ams,as3935.yaml +++ b/Documentation/devicetree/bindings/iio/proximity/ams,as3935.yaml @@ -10,7 +10,7 @@ maintainers: - Matt Ranostay <matt.ranostay@konsulko.com> description: - This lightening distance sensor uses an I2C or SPI interface. The + This lightning distance sensor uses an I2C or SPI interface. The binding currently only covers the SPI option. properties: diff --git a/Documentation/devicetree/bindings/iio/proximity/murata,irsd200.yaml b/Documentation/devicetree/bindings/iio/proximity/murata,irsd200.yaml new file mode 100644 index 000000000000..67f5389ece67 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/proximity/murata,irsd200.yaml @@ -0,0 +1,60 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/proximity/murata,irsd200.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Murata IRS-D200 PIR sensor + +maintainers: + - Waqar Hameed <waqar.hameed@axis.com> + +description: + PIR sensor for human detection. + +properties: + compatible: + const: murata,irsd200 + + reg: + items: + - enum: + - 0x48 + - 0x49 + description: | + When the AD pin is connected to GND, the slave address is 0x48. + When the AD pin is connected to VDD, the slave address is 0x49. + + interrupts: + maxItems: 1 + description: + Type should be IRQ_TYPE_EDGE_RISING. + + vdd-supply: + description: + 3.3 V supply voltage. + +required: + - compatible + - reg + - interrupts + - vdd-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + proximity@48 { + compatible = "murata,irsd200"; + reg = <0x48>; + interrupts = <24 IRQ_TYPE_EDGE_RISING>; + vdd-supply = <®ulator_3v3>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/proximity/semtech,sx9310.yaml b/Documentation/devicetree/bindings/iio/proximity/semtech,sx9310.yaml index 5de0bb2180e6..775555d147bf 100644 --- a/Documentation/devicetree/bindings/iio/proximity/semtech,sx9310.yaml +++ b/Documentation/devicetree/bindings/iio/proximity/semtech,sx9310.yaml @@ -15,6 +15,9 @@ description: | Specifications about the devices can be found at: https://www.semtech.com/products/smart-sensing/sar-sensors/sx9310 +allOf: + - $ref: /schemas/iio/iio.yaml# + properties: compatible: enum: @@ -102,7 +105,7 @@ required: - reg - "#io-channel-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/iio/proximity/semtech,sx9324.yaml b/Documentation/devicetree/bindings/iio/proximity/semtech,sx9324.yaml index b3aa2ebf9661..48f221463166 100644 --- a/Documentation/devicetree/bindings/iio/proximity/semtech,sx9324.yaml +++ b/Documentation/devicetree/bindings/iio/proximity/semtech,sx9324.yaml @@ -13,6 +13,9 @@ maintainers: description: | Semtech's SX9324 proximity sensor. +allOf: + - $ref: /schemas/iio/iio.yaml# + properties: compatible: const: semtech,sx9324 @@ -167,7 +170,7 @@ required: - reg - "#io-channel-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/iio/st,st-sensors.yaml b/Documentation/devicetree/bindings/iio/st,st-sensors.yaml index e450821a741d..fff7e3d83a02 100644 --- a/Documentation/devicetree/bindings/iio/st,st-sensors.yaml +++ b/Documentation/devicetree/bindings/iio/st,st-sensors.yaml @@ -97,7 +97,7 @@ properties: interrupts: description: interrupt line(s) connected to the DRDY line(s) and/or the - Intertial interrupt lines INT1 and INT2 if these exist. This means up to + Inertial interrupt lines INT1 and INT2 if these exist. This means up to three interrupts, and the DRDY must be the first one if it exists on the package. The trigger edge of the interrupts is sometimes software configurable in the hardware so the operating system should parse this diff --git a/Documentation/devicetree/bindings/input/azoteq,iqs7222.yaml b/Documentation/devicetree/bindings/input/azoteq,iqs7222.yaml index 9ddba7f2e7aa..5b1769c19b17 100644 --- a/Documentation/devicetree/bindings/input/azoteq,iqs7222.yaml +++ b/Documentation/devicetree/bindings/input/azoteq,iqs7222.yaml @@ -4,14 +4,14 @@ $id: http://devicetree.org/schemas/input/azoteq,iqs7222.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Azoteq IQS7222A/B/C Capacitive Touch Controller +title: Azoteq IQS7222A/B/C/D Capacitive Touch Controller maintainers: - Jeff LaBundy <jeff@labundy.com> description: | - The Azoteq IQS7222A, IQS7222B and IQS7222C are multichannel capacitive touch - controllers that feature additional sensing capabilities. + The Azoteq IQS7222A, IQS7222B, IQS7222C and IQS7222D are multichannel + capacitive touch controllers that feature additional sensing capabilities. Link to datasheets: https://www.azoteq.com/ @@ -21,6 +21,7 @@ properties: - azoteq,iqs7222a - azoteq,iqs7222b - azoteq,iqs7222c + - azoteq,iqs7222d reg: maxItems: 1 @@ -173,6 +174,152 @@ properties: maximum: 3000 description: Specifies the report rate (in ms) during ultra-low-power mode. + touchscreen-size-x: true + touchscreen-size-y: true + touchscreen-inverted-x: true + touchscreen-inverted-y: true + touchscreen-swapped-x-y: true + + trackpad: + type: object + description: Represents all channels associated with the trackpad. + + properties: + azoteq,channel-select: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 12 + items: + minimum: 0 + maximum: 13 + description: + Specifies the order of the channels that participate in the trackpad. + Specify 255 to omit a given channel for the purpose of mapping a non- + rectangular trackpad. + + azoteq,num-rows: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + maximum: 12 + description: Specifies the number of rows that comprise the trackpad. + + azoteq,num-cols: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + maximum: 12 + description: Specifies the number of columns that comprise the trackpad. + + azoteq,top-speed: + $ref: /schemas/types.yaml#/definitions/uint32 + multipleOf: 4 + minimum: 0 + maximum: 1020 + description: + Specifies the speed (in coordinates traveled per conversion) after + which coordinate filtering is no longer applied. + + azoteq,bottom-speed: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: + Specifies the speed (in coordinates traveled per conversion) after + which coordinate filtering is linearly reduced. + + azoteq,use-prox: + type: boolean + description: + Directs the trackpad to respond to the proximity states of the + selected channels instead of their corresponding touch states. + Note the trackpad cannot report granular coordinates during a + state of proximity. + + patternProperties: + "^azoteq,lower-cal-(x|y)$": + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the trackpad's lower starting points. + + "^azoteq,upper-cal-(x|y)$": + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the trackpad's upper starting points. + + "^event-(press|tap|(swipe|flick)-(x|y)-(pos|neg))$": + type: object + $ref: input.yaml# + description: + Represents a press or gesture event reported by the trackpad. Specify + 'linux,code' under the press event to report absolute coordinates. + + properties: + linux,code: true + + azoteq,gesture-angle-tighten: + type: boolean + description: + Limits the tangent of the gesture angle to 0.5 (axial gestures + only). If specified in one direction, the effect is applied in + either direction. + + azoteq,gesture-max-ms: + multipleOf: 16 + minimum: 0 + maximum: 4080 + description: + Specifies the length of time (in ms) within which a tap, swipe + or flick gesture must be completed in order to be acknowledged + by the device. The number specified for any one swipe or flick + gesture applies to all other swipe or flick gestures. + + azoteq,gesture-min-ms: + multipleOf: 16 + minimum: 0 + maximum: 4080 + description: + Specifies the length of time (in ms) for which a tap gesture must + be held in order to be acknowledged by the device. + + azoteq,gesture-dist: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 65535 + description: + Specifies the distance (in coordinates) across which a swipe or + flick gesture must travel in order to be acknowledged by the + device. The number specified for any one swipe or flick gesture + applies to all remaining swipe or flick gestures. + + For tap gestures, this property specifies the distance from the + original point of contact across which the contact is permitted + to travel before the gesture is rejected by the device. + + azoteq,gpio-select: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 3 + items: + minimum: 0 + maximum: 2 + description: | + Specifies one or more GPIO mapped to the event as follows: + 0: GPIO0 + 1: GPIO3 + 2: GPIO4 + + Note that although multiple events can be mapped to a single + GPIO, they must all be of the same type (proximity, touch or + trackpad gesture). + + additionalProperties: false + + required: + - azoteq,channel-select + + additionalProperties: false + patternProperties: "^cycle-[0-9]$": type: object @@ -288,6 +435,10 @@ patternProperties: Activates the reference channel in response to proximity events instead of touch events. + azoteq,counts-filt-enable: + type: boolean + description: Applies counts filtering to the channel. + azoteq,ati-band: $ref: /schemas/types.yaml#/definitions/uint32 enum: [0, 1, 2, 3] @@ -432,12 +583,12 @@ patternProperties: description: | Specifies one or more GPIO mapped to the event as follows: 0: GPIO0 - 1: GPIO3 (IQS7222C only) - 2: GPIO4 (IQS7222C only) + 1: GPIO3 + 2: GPIO4 Note that although multiple events can be mapped to a single GPIO, they must all be of the same type (proximity, touch or - slider gesture). + slider/trackpad gesture). azoteq,thresh: $ref: /schemas/types.yaml#/definitions/uint32 @@ -521,16 +672,16 @@ patternProperties: minimum: 0 maximum: 65535 description: - Specifies the speed of movement after which coordinate filtering is - no longer applied. + Specifies the speed (in coordinates traveled per conversion) after + which coordinate filtering is no longer applied. azoteq,bottom-speed: $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 255 description: - Specifies the speed of movement after which coordinate filtering is - linearly reduced. + Specifies the speed (in coordinates traveled per conversion) after + which coordinate filtering is linearly reduced. azoteq,bottom-beta: $ref: /schemas/types.yaml#/definitions/uint32 @@ -595,10 +746,10 @@ patternProperties: minimum: 0 maximum: 4080 description: - Specifies the distance across which a swipe or flick gesture must - travel in order to be acknowledged by the device. The number spec- - ified for any one swipe or flick gesture applies to all remaining - swipe or flick gestures. + Specifies the distance (in coordinates) across which a swipe or + flick gesture must travel in order to be acknowledged by the + device. The number specified for any one swipe or flick gesture + applies to all remaining swipe or flick gestures. azoteq,gpio-select: $ref: /schemas/types.yaml#/definitions/uint32-array @@ -610,8 +761,8 @@ patternProperties: description: | Specifies one or more GPIO mapped to the event as follows: 0: GPIO0 - 1: GPIO3 (IQS7222C only) - 2: GPIO4 (IQS7222C only) + 1: GPIO3 + 2: GPIO4 Note that although multiple events can be mapped to a single GPIO, they must all be of the same type (proximity, touch or @@ -629,8 +780,8 @@ patternProperties: description: | Represents a GPIO mapped to one or more events as follows: gpio-0: GPIO0 - gpio-1: GPIO3 (IQS7222C only) - gpio-2: GPIO4 (IQS7222C only) + gpio-1: GPIO3 + gpio-2: GPIO4 allOf: - $ref: ../pinctrl/pincfg-node.yaml# @@ -641,11 +792,53 @@ patternProperties: additionalProperties: false allOf: + - $ref: touchscreen/touchscreen.yaml# + - if: properties: compatible: contains: - const: azoteq,iqs7222b + enum: + - azoteq,iqs7222a + - azoteq,iqs7222b + - azoteq,iqs7222c + + then: + properties: + touchscreen-size-x: false + touchscreen-size-y: false + touchscreen-inverted-x: false + touchscreen-inverted-y: false + touchscreen-swapped-x-y: false + + trackpad: false + + patternProperties: + "^channel-([0-9]|1[0-9])$": + properties: + azoteq,counts-filt-enable: false + + - if: + properties: + compatible: + contains: + enum: + - azoteq,iqs7222b + - azoteq,iqs7222c + + then: + patternProperties: + "^channel-([0-9]|1[0-9])$": + properties: + azoteq,ulp-allow: false + + - if: + properties: + compatible: + contains: + enum: + - azoteq,iqs7222b + - azoteq,iqs7222d then: patternProperties: @@ -657,13 +850,22 @@ allOf: properties: azoteq,ref-select: false + "^slider-[0-1]$": false + + - if: + properties: + compatible: + contains: + const: azoteq,iqs7222b + + then: + patternProperties: + "^channel-([0-9]|1[0-9])$": patternProperties: "^event-(prox|touch)$": properties: azoteq,gpio-select: false - "^slider-[0-1]$": false - "^gpio-[0-2]$": false - if: @@ -704,10 +906,6 @@ allOf: else: patternProperties: - "^channel-([0-9]|1[0-9])$": - properties: - azoteq,ulp-allow: false - "^slider-[0-1]$": patternProperties: "^event-(press|tap|(swipe|flick)-(pos|neg))$": diff --git a/Documentation/devicetree/bindings/input/elan,ekth3000.yaml b/Documentation/devicetree/bindings/input/elan,ekth3000.yaml index 2a9bb6ace021..24dc2d69613f 100644 --- a/Documentation/devicetree/bindings/input/elan,ekth3000.yaml +++ b/Documentation/devicetree/bindings/input/elan,ekth3000.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/input/elan,ekth3000.yaml# diff --git a/Documentation/devicetree/bindings/input/elan,ekth6915.yaml b/Documentation/devicetree/bindings/input/elan,ekth6915.yaml index 05e6f2df604c..3e2d216c6432 100644 --- a/Documentation/devicetree/bindings/input/elan,ekth6915.yaml +++ b/Documentation/devicetree/bindings/input/elan,ekth6915.yaml @@ -13,6 +13,9 @@ description: Supports the Elan eKTH6915 touchscreen controller. This touchscreen controller uses the i2c-hid protocol with a reset GPIO. +allOf: + - $ref: /schemas/input/touchscreen/touchscreen.yaml# + properties: compatible: items: @@ -24,6 +27,8 @@ properties: interrupts: maxItems: 1 + panel: true + reset-gpios: description: Reset GPIO; not all touchscreens using eKTH6915 hook this up. diff --git a/Documentation/devicetree/bindings/input/goodix,gt7375p.yaml b/Documentation/devicetree/bindings/input/goodix,gt7375p.yaml index 1edad1da1196..358cb8275bf1 100644 --- a/Documentation/devicetree/bindings/input/goodix,gt7375p.yaml +++ b/Documentation/devicetree/bindings/input/goodix,gt7375p.yaml @@ -14,6 +14,9 @@ description: This touchscreen uses the i2c-hid protocol but has some non-standard power sequencing required. +allOf: + - $ref: /schemas/input/touchscreen/touchscreen.yaml# + properties: compatible: oneOf: @@ -30,6 +33,8 @@ properties: interrupts: maxItems: 1 + panel: true + reset-gpios: true diff --git a/Documentation/devicetree/bindings/input/hid-over-i2c.yaml b/Documentation/devicetree/bindings/input/hid-over-i2c.yaml index 7156b08f7645..138caad96a29 100644 --- a/Documentation/devicetree/bindings/input/hid-over-i2c.yaml +++ b/Documentation/devicetree/bindings/input/hid-over-i2c.yaml @@ -44,6 +44,8 @@ properties: description: HID descriptor address $ref: /schemas/types.yaml#/definitions/uint32 + panel: true + post-power-on-delay-ms: description: Time required by the device after enabling its regulators or powering it on, before it is ready for communication. diff --git a/Documentation/devicetree/bindings/input/ilitek,ili9882t.yaml b/Documentation/devicetree/bindings/input/ilitek,ili9882t.yaml new file mode 100644 index 000000000000..c5d9e0e919f9 --- /dev/null +++ b/Documentation/devicetree/bindings/input/ilitek,ili9882t.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/ilitek,ili9882t.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Ilitek ili9882t touchscreen controller + +maintainers: + - Cong Yang <yangcong5@huaqin.corp-partner.google.com> + +description: + Supports the Ilitek ili9882t touchscreen controller. + This touchscreen controller uses the i2c-hid protocol with a reset GPIO. + +allOf: + - $ref: /schemas/input/touchscreen/touchscreen.yaml# + +properties: + compatible: + const: ilitek,ili9882t + + reg: + const: 0x41 + + interrupts: + maxItems: 1 + + panel: true + + reset-gpios: + maxItems: 1 + description: Reset GPIO. + + vccio-supply: + description: The 1.8V supply to the touchscreen. + +required: + - compatible + - reg + - interrupts + - panel + - vccio-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + touchscreen: touchscreen@41 { + compatible = "ilitek,ili9882t"; + reg = <0x41>; + + interrupt-parent = <&pio>; + interrupts = <12 IRQ_TYPE_LEVEL_LOW>; + + panel = <&panel>; + reset-gpios = <&pio 60 GPIO_ACTIVE_LOW>; + vccio-supply = <&mt6366_vio18_reg>; + }; + }; diff --git a/Documentation/devicetree/bindings/input/qcom,pm8921-keypad.yaml b/Documentation/devicetree/bindings/input/qcom,pm8921-keypad.yaml new file mode 100644 index 000000000000..88764adcd696 --- /dev/null +++ b/Documentation/devicetree/bindings/input/qcom,pm8921-keypad.yaml @@ -0,0 +1,89 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/qcom,pm8921-keypad.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm PM8921 PMIC KeyPad + +maintainers: + - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> + +allOf: + - $ref: input.yaml# + - $ref: matrix-keymap.yaml# + +properties: + compatible: + enum: + - qcom,pm8058-keypad + - qcom,pm8921-keypad + + reg: + maxItems: 1 + + interrupts: + items: + - description: key sense + - description: key stuck + + wakeup-source: + type: boolean + description: use any event on keypad as wakeup event + + linux,keypad-wakeup: + type: boolean + deprecated: true + description: legacy version of the wakeup-source property + + debounce: + description: + Time in microseconds that key must be pressed or + released for state change interrupt to trigger. + $ref: /schemas/types.yaml#/definitions/uint32 + + scan-delay: + $ref: /schemas/types.yaml#/definitions/uint32 + description: time in microseconds to pause between successive scans of the + matrix array + + row-hold: + $ref: /schemas/types.yaml#/definitions/uint32 + description: time in nanoseconds to pause between scans of each row in the + matrix array. + +required: + - compatible + - reg + - interrupts + - linux,keymap + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/input/input.h> + #include <dt-bindings/interrupt-controller/irq.h> + pmic { + #address-cells = <1>; + #size-cells = <0>; + + keypad@148 { + compatible = "qcom,pm8921-keypad"; + reg = <0x148>; + interrupt-parent = <&pmicintc>; + interrupts = <74 IRQ_TYPE_EDGE_RISING>, <75 IRQ_TYPE_EDGE_RISING>; + linux,keymap = < + MATRIX_KEY(0, 0, KEY_VOLUMEUP) + MATRIX_KEY(0, 1, KEY_VOLUMEDOWN) + MATRIX_KEY(0, 2, KEY_CAMERA_FOCUS) + MATRIX_KEY(0, 3, KEY_CAMERA) + >; + keypad,num-rows = <1>; + keypad,num-columns = <5>; + debounce = <15>; + scan-delay = <32>; + row-hold = <91500>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt b/Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt deleted file mode 100644 index 4a9dc6ba96b1..000000000000 --- a/Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt +++ /dev/null @@ -1,90 +0,0 @@ -Qualcomm PM8xxx PMIC Keypad - -PROPERTIES - -- compatible: - Usage: required - Value type: <string> - Definition: must be one of: - "qcom,pm8058-keypad" - "qcom,pm8921-keypad" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: address of keypad control register - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: the first interrupt specifies the key sense interrupt - and the second interrupt specifies the key stuck interrupt. - The format of the specifier is defined by the binding - document describing the node's interrupt parent. - -- linux,keymap: - Usage: required - Value type: <prop-encoded-array> - Definition: the linux keymap. More information can be found in - input/matrix-keymap.txt. - -- linux,keypad-no-autorepeat: - Usage: optional - Value type: <bool> - Definition: don't enable autorepeat feature. - -- wakeup-source: - Usage: optional - Value type: <bool> - Definition: use any event on keypad as wakeup event. - (Legacy property supported: "linux,keypad-wakeup") - -- keypad,num-rows: - Usage: required - Value type: <u32> - Definition: number of rows in the keymap. More information can be found - in input/matrix-keymap.txt. - -- keypad,num-columns: - Usage: required - Value type: <u32> - Definition: number of columns in the keymap. More information can be - found in input/matrix-keymap.txt. - -- debounce: - Usage: optional - Value type: <u32> - Definition: time in microseconds that key must be pressed or release - for key sense interrupt to trigger. - -- scan-delay: - Usage: optional - Value type: <u32> - Definition: time in microseconds to pause between successive scans - of the matrix array. - -- row-hold: - Usage: optional - Value type: <u32> - Definition: time in nanoseconds to pause between scans of each row in - the matrix array. - -EXAMPLE - - keypad@148 { - compatible = "qcom,pm8921-keypad"; - reg = <0x148>; - interrupt-parent = <&pmicintc>; - interrupts = <74 1>, <75 1>; - linux,keymap = < - MATRIX_KEY(0, 0, KEY_VOLUMEUP) - MATRIX_KEY(0, 1, KEY_VOLUMEDOWN) - MATRIX_KEY(0, 2, KEY_CAMERA_FOCUS) - MATRIX_KEY(0, 3, KEY_CAMERA) - >; - keypad,num-rows = <1>; - keypad,num-columns = <5>; - debounce = <15>; - scan-delay = <32>; - row-hold = <91500>; - }; diff --git a/Documentation/devicetree/bindings/input/rmi4/rmi_2d_sensor.txt b/Documentation/devicetree/bindings/input/rmi4/rmi_2d_sensor.txt deleted file mode 100644 index 9afffbdf6e28..000000000000 --- a/Documentation/devicetree/bindings/input/rmi4/rmi_2d_sensor.txt +++ /dev/null @@ -1,56 +0,0 @@ -Synaptics RMI4 2D Sensor Device Binding - -The Synaptics RMI4 core is able to support RMI4 devices using different -transports and different functions. This file describes the device tree -bindings for devices which contain 2D sensors using Function 11 or -Function 12. Complete documentation for transports and other functions -can be found in: -Documentation/devicetree/bindings/input/rmi4. - -RMI4 Function 11 and Function 12 are for 2D touch position sensing. -Additional documentation for F11 can be found at: -http://www.synaptics.com/sites/default/files/511-000136-01-Rev-E-RMI4-Interfacing-Guide.pdf - -Optional Touch Properties: -Description in Documentation/devicetree/bindings/input/touchscreen -- touchscreen-inverted-x -- touchscreen-inverted-y -- touchscreen-swapped-x-y -- touchscreen-x-mm -- touchscreen-y-mm - -Optional Properties: -- syna,clip-x-low: Sets a minimum value for X. -- syna,clip-y-low: Sets a minimum value for Y. -- syna,clip-x-high: Sets a maximum value for X. -- syna,clip-y-high: Sets a maximum value for Y. -- syna,offset-x: Add an offset to X. -- syna,offset-y: Add an offset to Y. -- syna,delta-x-threshold: Set the minimum distance on the X axis required - to generate an interrupt in reduced reporting - mode. -- syna,delta-y-threshold: Set the minimum distance on the Y axis required - to generate an interrupt in reduced reporting - mode. -- syna,sensor-type: Set the sensor type. 1 for touchscreen 2 for touchpad. -- syna,disable-report-mask: Mask for disabling posiiton reporting. Used to - disable reporing absolute position data. -- syna,rezero-wait-ms: Time in miliseconds to wait after issuing a rezero - command. - - -Example of a RMI4 I2C device with F11: -Example: - &i2c1 { - rmi4-i2c-dev@2c { - compatible = "syna,rmi4-i2c"; - - ... - - rmi4-f11@11 { - reg = <0x11>; - touchscreen-inverted-y; - syna,sensor-type = <2>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/input/rmi4/rmi_f01.txt b/Documentation/devicetree/bindings/input/rmi4/rmi_f01.txt deleted file mode 100644 index 079cad2b6843..000000000000 --- a/Documentation/devicetree/bindings/input/rmi4/rmi_f01.txt +++ /dev/null @@ -1,39 +0,0 @@ -Synaptics RMI4 F01 Device Binding - -The Synaptics RMI4 core is able to support RMI4 devices using different -transports and different functions. This file describes the device tree -bindings for devices which contain Function 1. Complete documentation -for transports and other functions can be found in: -Documentation/devicetree/bindings/input/rmi4. - -Additional documentation for F01 can be found at: -http://www.synaptics.com/sites/default/files/511-000136-01-Rev-E-RMI4-Interfacing-Guide.pdf - -Optional Properties: -- syna,nosleep-mode: If set the device will run at full power without sleeping. - nosleep has 3 modes, 0 will not change the default - setting, 1 will disable nosleep (allow sleeping), - and 2 will enable nosleep (disabling sleep). -- syna,wakeup-threshold: Defines the amplitude of the disturbance to the - background capacitance that will cause the - device to wake from dozing. -- syna,doze-holdoff-ms: The delay to wait after the last finger lift and the - first doze cycle. -- syna,doze-interval-ms: The time period that the device sleeps between finger - activity. - - -Example of a RMI4 I2C device with F01: - Example: - &i2c1 { - rmi4-i2c-dev@2c { - compatible = "syna,rmi4-i2c"; - - ... - - rmi4-f01@1 { - reg = <0x1>; - syna,nosleep-mode = <1>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/input/rmi4/rmi_i2c.txt b/Documentation/devicetree/bindings/input/rmi4/rmi_i2c.txt deleted file mode 100644 index dcb012f5b3ee..000000000000 --- a/Documentation/devicetree/bindings/input/rmi4/rmi_i2c.txt +++ /dev/null @@ -1,61 +0,0 @@ -Synaptics RMI4 I2C Device Binding - -The Synaptics RMI4 core is able to support RMI4 devices using different -transports and different functions. This file describes the device tree -bindings for devices using the I2C transport driver. Complete documentation -for other transports and functions can be found in -Documentation/devicetree/bindings/input/rmi4. - -Required Properties: -- compatible: syna,rmi4-i2c -- reg: I2C address -- #address-cells: Set to 1 to indicate that the function child nodes - consist of only on uint32 value. -- #size-cells: Set to 0 to indicate that the function child nodes do not - have a size property. - -Optional Properties: -- interrupts: interrupt which the rmi device is connected to. -See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt - -- syna,reset-delay-ms: The number of milliseconds to wait after resetting the - device. - -- syna,startup-delay-ms: The number of milliseconds to wait after powering on - the device. - -- vdd-supply: VDD power supply. -See ../regulator/regulator.txt - -- vio-supply: VIO power supply -See ../regulator/regulator.txt - -Function Parameters: -Parameters specific to RMI functions are contained in child nodes of the rmi device - node. Documentation for the parameters of each function can be found in: -Documentation/devicetree/bindings/input/rmi4/rmi_f*.txt. - - - -Example: - &i2c1 { - rmi4-i2c-dev@2c { - compatible = "syna,rmi4-i2c"; - reg = <0x2c>; - #address-cells = <1>; - #size-cells = <0>; - interrupt-parent = <&gpio>; - interrupts = <4 2>; - - rmi4-f01@1 { - reg = <0x1>; - syna,nosleep-mode = <1>; - }; - - rmi4-f11@11 { - reg = <0x11>; - touchscreen-inverted-y; - syna,sensor-type = <2>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/input/rmi4/rmi_spi.txt b/Documentation/devicetree/bindings/input/rmi4/rmi_spi.txt deleted file mode 100644 index 632f473db65b..000000000000 --- a/Documentation/devicetree/bindings/input/rmi4/rmi_spi.txt +++ /dev/null @@ -1,56 +0,0 @@ -Synaptics RMI4 SPI Device Binding - -The Synaptics RMI4 core is able to support RMI4 devices using different -transports and different functions. This file describes the device tree -bindings for devices using the SPI transport driver. Complete documentation -for other transports and functions can be found in -Documentation/devicetree/bindings/input/rmi4. - -Required Properties: -- compatible: syna,rmi4-spi -- reg: Chip select address for the device -- #address-cells: Set to 1 to indicate that the function child nodes - consist of only on uint32 value. -- #size-cells: Set to 0 to indicate that the function child nodes do not - have a size property. - -Optional Properties: -- interrupts: interrupt which the rmi device is connected to. -See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt - -- spi-rx-delay-us: microsecond delay after a read transfer. -- spi-tx-delay-us: microsecond delay after a write transfer. - -Function Parameters: -Parameters specific to RMI functions are contained in child nodes of the rmi device - node. Documentation for the parameters of each function can be found in: -Documentation/devicetree/bindings/input/rmi4/rmi_f*.txt. - - - -Example: - spi@7000d800 { - rmi4-spi-dev@0 { - compatible = "syna,rmi4-spi"; - reg = <0x0>; - #address-cells = <1>; - #size-cells = <0>; - spi-max-frequency = <4000000>; - spi-cpha; - spi-cpol; - interrupt-parent = <&gpio>; - interrupts = <TEGRA_GPIO(K, 2) 0x2>; - spi-rx-delay-us = <30>; - - rmi4-f01@1 { - reg = <0x1>; - syna,nosleep-mode = <1>; - }; - - rmi4-f11@11 { - reg = <0x11>; - touchscreen-inverted-y; - syna,sensor-type = <2>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/input/stmpe-keypad.txt b/Documentation/devicetree/bindings/input/stmpe-keypad.txt deleted file mode 100644 index 12bb771d66d4..000000000000 --- a/Documentation/devicetree/bindings/input/stmpe-keypad.txt +++ /dev/null @@ -1,41 +0,0 @@ -* STMPE Keypad - -Required properties: - - compatible : "st,stmpe-keypad" - - linux,keymap : See ./matrix-keymap.txt - -Optional properties: - - debounce-interval : Debouncing interval time in milliseconds - - st,scan-count : Scanning cycles elapsed before key data is updated - - st,no-autorepeat : If specified device will not autorepeat - - keypad,num-rows : See ./matrix-keymap.txt - - keypad,num-columns : See ./matrix-keymap.txt - -Example: - - stmpe_keypad { - compatible = "st,stmpe-keypad"; - - debounce-interval = <64>; - st,scan-count = <8>; - st,no-autorepeat; - - linux,keymap = <0x205006b - 0x4010074 - 0x3050072 - 0x1030004 - 0x502006a - 0x500000a - 0x5008b - 0x706001c - 0x405000b - 0x6070003 - 0x3040067 - 0x303006c - 0x60400e7 - 0x602009e - 0x4020073 - 0x5050002 - 0x4030069 - 0x3020008>; - }; diff --git a/Documentation/devicetree/bindings/input/syna,rmi4.yaml b/Documentation/devicetree/bindings/input/syna,rmi4.yaml new file mode 100644 index 000000000000..b522c8d3ce0d --- /dev/null +++ b/Documentation/devicetree/bindings/input/syna,rmi4.yaml @@ -0,0 +1,273 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/syna,rmi4.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Synaptics RMI4 compliant devices + +maintainers: + - Jason A. Donenfeld <Jason@zx2c4.com> + - Matthias Schiffer <matthias.schiffer@ew.tq-group.com + - Vincent Huang <vincent.huang@tw.synaptics.com> + +description: | + The Synaptics RMI4 (Register Mapped Interface 4) core is able to support RMI4 + devices using different transports (I2C, SPI) and different functions (e.g. + Function 1, 2D sensors using Function 11 or 12). + +properties: + compatible: + enum: + - syna,rmi4-i2c + - syna,rmi4-spi + + reg: + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + interrupts: + maxItems: 1 + + reset-gpios: + maxItems: 1 + description: Active low signal + + spi-cpha: true + spi-cpol: true + + syna,reset-delay-ms: + description: + Delay to wait after resetting the device. + + syna,startup-delay-ms: + description: + Delay to wait after powering on the device. + + vdd-supply: true + vio-supply: true + + rmi4-f01@1: + type: object + additionalProperties: false + description: + Function 1 + + properties: + reg: + maxItems: 1 + + syna,nosleep-mode: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2] + description: + If set the device will run at full power without sleeping. nosleep + has 3 modes, 0 will not change the default setting, 1 will disable + nosleep (allow sleeping), and 2 will enable nosleep (disabling + sleep). + + syna,wakeup-threshold: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Defines the amplitude of the disturbance to the background + capacitance that will cause the device to wake from dozing. + + syna,doze-holdoff-ms: + description: + The delay to wait after the last finger lift and the first doze + cycle. + + syna,doze-interval-ms: + description: + The time period that the device sleeps between finger activity. + + required: + - reg + +patternProperties: + "^rmi4-f1[12]@1[12]$": + type: object + unevaluatedProperties: false + $ref: /schemas/input/touchscreen/touchscreen.yaml# + description: + RMI4 Function 11 and Function 12 are for 2D touch position sensing. + + properties: + reg: + maxItems: 1 + + syna,clip-x-low: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Minimum value for X. + + syna,clip-y-low: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Minimum value for Y. + + syna,clip-x-high: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Maximum value for X. + + syna,clip-y-high: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Maximum value for Y. + + syna,offset-x: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Add an offset to X. + + syna,offset-y: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Add an offset to Y. + + syna,delta-x-threshold: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Minimum distance on the X axis required to generate an interrupt in + reduced reporting mode. + + syna,delta-y-threshold: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Minimum distance on the Y axis required to generate an interrupt in + reduced reporting mode. + + syna,sensor-type: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [1, 2] + description: | + Sensor type: 1 for touchscreen 2 for touchpad. + + syna,disable-report-mask: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Mask for disabling posiiton reporting. Used to disable reporing + absolute position data. + + syna,rezero-wait-ms: + description: + Time to wait after issuing a rezero command. + + required: + - reg + + "^rmi4-f[0-9a-f]+@[0-9a-f]+$": + type: object + additionalProperties: true + + description: + Other functions, not documented yet. + + properties: + reg: + maxItems: 1 + + required: + - reg + +required: + - compatible + - reg + +unevaluatedProperties: false + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + + - if: + properties: + compatible: + contains: + const: syna,rmi4-i2c + then: + properties: + spi-rx-delay-us: false + spi-tx-delay-us: false + else: + properties: + syna,reset-delay-ms: false + syna,startup-delay-ms: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + touchscreen@20 { + compatible = "syna,rmi4-i2c"; + reg = <0x20>; + interrupt-parent = <&gpx1>; + interrupts = <6 IRQ_TYPE_EDGE_FALLING>; + + syna,startup-delay-ms = <100>; + vdd-supply = <&tsp_vdd>; + vio-supply = <&ldo32_reg>; + + pinctrl-0 = <&touch_irq>; + pinctrl-names = "default"; + #address-cells = <1>; + #size-cells = <0>; + + rmi4-f01@1 { + reg = <0x1>; + syna,nosleep-mode = <1>; + }; + + rmi4-f12@12 { + reg = <0x12>; + syna,sensor-type = <1>; + }; + + rmi4-f1a@1a { + reg = <0x1a>; + }; + }; + }; + + - | + #include <dt-bindings/interrupt-controller/irq.h> + + spi { + #address-cells = <1>; + #size-cells = <0>; + + touchscreen@0 { + compatible = "syna,rmi4-spi"; + reg = <0x0>; + interrupt-parent = <&gpx1>; + interrupts = <6 IRQ_TYPE_EDGE_FALLING>; + + spi-max-frequency = <4000000>; + spi-rx-delay-us = <30>; + spi-cpha; + spi-cpol; + + #address-cells = <1>; + #size-cells = <0>; + + rmi4-f01@1 { + reg = <0x1>; + syna,nosleep-mode = <1>; + }; + + rmi4-f11@11 { + reg = <0x11>; + touchscreen-inverted-y; + syna,sensor-type = <2>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/azoteq,iqs7211.yaml b/Documentation/devicetree/bindings/input/touchscreen/azoteq,iqs7211.yaml new file mode 100644 index 000000000000..8cf371b99f19 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/azoteq,iqs7211.yaml @@ -0,0 +1,769 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/touchscreen/azoteq,iqs7211.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Azoteq IQS7210A/7211A/E Trackpad/Touchscreen Controller + +maintainers: + - Jeff LaBundy <jeff@labundy.com> + +description: | + The Azoteq IQS7210A, IQS7211A and IQS7211E trackpad and touchscreen control- + lers employ projected-capacitance sensing and can track two contacts. + + Link to datasheets: https://www.azoteq.com/ + +properties: + compatible: + enum: + - azoteq,iqs7210a + - azoteq,iqs7211a + - azoteq,iqs7211e + + reg: + maxItems: 1 + + irq-gpios: + maxItems: 1 + description: + Specifies the GPIO connected to the device's active-low RDY output. The + pin doubles as the IQS7211E's active-low MCLR input, in which case this + GPIO must be configured as open-drain. + + reset-gpios: + maxItems: 1 + description: + Specifies the GPIO connected to the device's active-low MCLR input. The + device is temporarily held in hardware reset prior to initialization if + this property is present. + + azoteq,forced-comms: + type: boolean + description: + Enables forced communication; to be used with host adapters that cannot + tolerate clock stretching. + + azoteq,forced-comms-default: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + description: + Indicates if the device's OTP memory enables (1) or disables (0) forced + communication by default. Specifying this property can expedite startup + time if the default value is known. + + If this property is not specified, communication is not initiated until + the device asserts its RDY pin shortly after exiting hardware reset. At + that point, forced communication is either enabled or disabled based on + the presence or absence of the 'azoteq,forced-comms' property. + + azoteq,rate-active-ms: + minimum: 0 + maximum: 65535 + description: Specifies the report rate (in ms) during active mode. + + azoteq,rate-touch-ms: + minimum: 0 + maximum: 65535 + description: Specifies the report rate (in ms) during idle-touch mode. + + azoteq,rate-idle-ms: + minimum: 0 + maximum: 65535 + description: Specifies the report rate (in ms) during idle mode. + + azoteq,rate-lp1-ms: + minimum: 0 + maximum: 65535 + description: Specifies the report rate (in ms) during low-power mode 1. + + azoteq,rate-lp2-ms: + minimum: 0 + maximum: 65535 + description: Specifies the report rate (in ms) during low-power mode 2. + + azoteq,timeout-active-ms: + multipleOf: 1000 + minimum: 0 + maximum: 65535000 + description: + Specifies the length of time (in ms) to wait for an event before moving + from active mode to idle or idle-touch modes. + + azoteq,timeout-touch-ms: + multipleOf: 1000 + minimum: 0 + maximum: 65535000 + description: + Specifies the length of time (in ms) to wait for an event before moving + from idle-touch mode to idle mode. + + azoteq,timeout-idle-ms: + multipleOf: 1000 + minimum: 0 + maximum: 65535000 + description: + Specifies the length of time (in ms) to wait for an event before moving + from idle mode to low-power mode 1. + + azoteq,timeout-lp1-ms: + multipleOf: 1000 + minimum: 0 + maximum: 65535000 + description: + Specifies the length of time (in ms) to wait for an event before moving + from low-power mode 1 to low-power mode 2. + + azoteq,timeout-lp2-ms: + multipleOf: 1000 + minimum: 0 + maximum: 60000 + description: + Specifies the rate (in ms) at which the trackpad reference values + are updated during low-power modes 1 and 2. + + azoteq,timeout-ati-ms: + multipleOf: 1000 + minimum: 0 + maximum: 60000 + description: + Specifies the delay (in ms) before the automatic tuning implementation + (ATI) is retried in the event it fails to complete. + + azoteq,timeout-comms-ms: + minimum: 0 + maximum: 65535 + description: + Specifies the delay (in ms) before a communication window is closed. + + azoteq,timeout-press-ms: + multipleOf: 1000 + minimum: 0 + maximum: 60000 + description: + Specifies the length of time (in ms) to wait before automatically + releasing a press event. Specify zero to allow the press state to + persist indefinitely. + + azoteq,fosc-freq: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + description: | + Specifies the device's core clock frequency as follows: + 0: 14 MHz + 1: 18 MHz + + azoteq,fosc-trim: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 15 + description: Specifies the device's core clock frequency trim. + + azoteq,num-contacts: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 2 + default: 0 + description: Specifies the number of contacts reported by the device. + + azoteq,contact-split: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the contact (finger) split factor. + + azoteq,trim-x: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the horizontal trim width. + + azoteq,trim-y: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the vertical trim height. + + trackpad: + type: object + description: Represents all channels associated with the trackpad. + + properties: + azoteq,rx-enable: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 8 + items: + minimum: 0 + maximum: 7 + description: + Specifies the order of the CRx pin(s) associated with the trackpad. + + azoteq,tx-enable: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 12 + items: + minimum: 0 + maximum: 11 + description: + Specifies the order of the CTx pin(s) associated with the trackpad. + + azoteq,channel-select: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 36 + items: + minimum: 0 + maximum: 255 + description: | + Specifies the channels mapped to each cycle in the following order: + Cycle 0, slot 0 + Cycle 0, slot 1 + Cycle 1, slot 0 + Cycle 1, slot 1 + ...and so on. Specify 255 to disable a given slot. + + azoteq,ati-frac-div-fine: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 31 + description: Specifies the trackpad's ATI fine fractional divider. + + azoteq,ati-frac-mult-coarse: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 15 + description: Specifies the trackpad's ATI coarse fractional multiplier. + + azoteq,ati-frac-div-coarse: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 31 + description: Specifies the trackpad's ATI coarse fractional divider. + + azoteq,ati-comp-div: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 31 + description: Specifies the trackpad's ATI compensation divider. + + azoteq,ati-target: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 65535 + description: Specifies the trackpad's ATI target. + + azoteq,touch-enter: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the trackpad's touch entrance factor. + + azoteq,touch-exit: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the trackpad's touch exit factor. + + azoteq,thresh: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the trackpad's stationary touch threshold. + + azoteq,conv-period: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the trackpad's conversion period. + + azoteq,conv-frac: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the trackpad's conversion frequency fraction. + + patternProperties: + "^event-(tap(-double|-triple)?|hold|palm|swipe-(x|y)-(pos|neg)(-hold)?)$": + type: object + $ref: ../input.yaml# + description: + Represents a gesture event reported by the trackpad. In the case of + axial gestures, the duration or distance specified in one direction + applies to both directions along the same axis. + + properties: + linux,code: true + + azoteq,gesture-max-ms: + minimum: 0 + maximum: 65535 + description: Specifies the maximum duration of tap/swipe gestures. + + azoteq,gesture-mid-ms: + minimum: 0 + maximum: 65535 + description: + Specifies the maximum duration between subsequent tap gestures + (IQS7211E only). + + azoteq,gesture-min-ms: + minimum: 0 + maximum: 65535 + description: Specifies the minimum duration of hold gestures. + + azoteq,gesture-dist: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 65535 + description: + Specifies the minimum (swipe) or maximum (tap and hold) distance + a finger may travel to be considered a gesture. + + azoteq,gesture-dist-rep: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 65535 + description: + Specifies the minimum distance a finger must travel to elicit a + repeated swipe gesture (IQS7211E only). + + azoteq,gesture-angle: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 75 + description: + Specifies the maximum angle (in degrees) a finger may travel to + be considered a swipe gesture. + + azoteq,thresh: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 42 + description: Specifies the palm gesture threshold (IQS7211E only). + + additionalProperties: false + + dependencies: + azoteq,rx-enable: ["azoteq,tx-enable"] + azoteq,tx-enable: ["azoteq,rx-enable"] + azoteq,channel-select: ["azoteq,rx-enable"] + + additionalProperties: false + + alp: + type: object + $ref: ../input.yaml# + description: Represents the alternate low-power channel (ALP). + + properties: + azoteq,rx-enable: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 8 + items: + minimum: 0 + maximum: 7 + description: + Specifies the CRx pin(s) associated with the ALP in no particular + order. + + azoteq,tx-enable: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 12 + items: + minimum: 0 + maximum: 11 + description: + Specifies the CTx pin(s) associated with the ALP in no particular + order. + + azoteq,ati-frac-div-fine: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 31 + description: Specifies the ALP's ATI fine fractional divider. + + azoteq,ati-frac-mult-coarse: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 15 + description: Specifies the ALP's ATI coarse fractional multiplier. + + azoteq,ati-frac-div-coarse: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 31 + description: Specifies the ALP's ATI coarse fractional divider. + + azoteq,ati-comp-div: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 31 + description: Specifies the ALP's ATI compensation divider. + + azoteq,ati-target: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 65535 + description: Specifies the ALP's ATI target. + + azoteq,ati-base: + $ref: /schemas/types.yaml#/definitions/uint32 + multipleOf: 8 + minimum: 0 + maximum: 255 + description: Specifies the ALP's ATI base. + + azoteq,ati-mode: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + description: | + Specifies the ALP's ATI mode as follows: + 0: Partial + 1: Full + + azoteq,sense-mode: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + description: | + Specifies the ALP's sensing mode as follows: + 0: Self capacitive + 1: Mutual capacitive + + azoteq,debounce-enter: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the ALP's debounce entrance factor. + + azoteq,debounce-exit: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the ALP's debounce exit factor. + + azoteq,thresh: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 65535 + description: Specifies the ALP's proximity or touch threshold. + + azoteq,conv-period: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the ALP's conversion period. + + azoteq,conv-frac: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the ALP's conversion frequency fraction. + + linux,code: true + + additionalProperties: false + + button: + type: object + description: Represents the inductive or capacitive button. + + properties: + azoteq,ati-frac-div-fine: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 31 + description: Specifies the button's ATI fine fractional divider. + + azoteq,ati-frac-mult-coarse: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 15 + description: Specifies the button's ATI coarse fractional multiplier. + + azoteq,ati-frac-div-coarse: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 31 + description: Specifies the button's ATI coarse fractional divider. + + azoteq,ati-comp-div: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 31 + description: Specifies the button's ATI compensation divider. + + azoteq,ati-target: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 65535 + description: Specifies the button's ATI target. + + azoteq,ati-base: + $ref: /schemas/types.yaml#/definitions/uint32 + multipleOf: 8 + minimum: 0 + maximum: 255 + description: Specifies the button's ATI base. + + azoteq,ati-mode: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + description: | + Specifies the button's ATI mode as follows: + 0: Partial + 1: Full + + azoteq,sense-mode: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2] + description: | + Specifies the button's sensing mode as follows: + 0: Self capacitive + 1: Mutual capacitive + 2: Inductive + + azoteq,touch-enter: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the button's touch entrance factor. + + azoteq,touch-exit: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the button's touch exit factor. + + azoteq,debounce-enter: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the button's debounce entrance factor. + + azoteq,debounce-exit: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the button's debounce exit factor. + + azoteq,thresh: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 65535 + description: Specifies the button's proximity threshold. + + azoteq,conv-period: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the button's conversion period. + + azoteq,conv-frac: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + description: Specifies the button's conversion frequency fraction. + + patternProperties: + "^event-(prox|touch)$": + type: object + $ref: ../input.yaml# + description: + Represents a proximity or touch event reported by the button. + + properties: + linux,code: true + + additionalProperties: false + + additionalProperties: false + + wakeup-source: true + + touchscreen-size-x: true + touchscreen-size-y: true + touchscreen-inverted-x: true + touchscreen-inverted-y: true + touchscreen-swapped-x-y: true + +dependencies: + touchscreen-size-x: ["azoteq,num-contacts"] + touchscreen-size-y: ["azoteq,num-contacts"] + touchscreen-inverted-x: ["azoteq,num-contacts"] + touchscreen-inverted-y: ["azoteq,num-contacts"] + touchscreen-swapped-x-y: ["azoteq,num-contacts"] + +required: + - compatible + - reg + - irq-gpios + +additionalProperties: false + +allOf: + - $ref: touchscreen.yaml# + + - if: + properties: + compatible: + contains: + const: azoteq,iqs7210a + + then: + properties: + alp: + properties: + azoteq,rx-enable: + maxItems: 4 + items: + minimum: 4 + + else: + properties: + azoteq,timeout-press-ms: false + + alp: + properties: + azoteq,ati-mode: false + + button: false + + - if: + properties: + compatible: + contains: + const: azoteq,iqs7211e + + then: + properties: + reset-gpios: false + + trackpad: + properties: + azoteq,tx-enable: + maxItems: 13 + items: + maximum: 12 + + alp: + properties: + azoteq,tx-enable: + maxItems: 13 + items: + maximum: 12 + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/input/input.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + touch@56 { + compatible = "azoteq,iqs7210a"; + reg = <0x56>; + irq-gpios = <&gpio 4 GPIO_ACTIVE_LOW>; + reset-gpios = <&gpio 17 (GPIO_ACTIVE_LOW | + GPIO_PUSH_PULL)>; + azoteq,num-contacts = <2>; + + trackpad { + azoteq,rx-enable = <6>, <5>, <4>, <3>, <2>; + azoteq,tx-enable = <1>, <7>, <8>, <9>, <10>; + }; + + button { + azoteq,sense-mode = <2>; + azoteq,touch-enter = <40>; + azoteq,touch-exit = <36>; + + event-touch { + linux,code = <KEY_HOME>; + }; + }; + + alp { + azoteq,sense-mode = <1>; + linux,code = <KEY_POWER>; + }; + }; + }; + + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/input/input.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + touch@56 { + compatible = "azoteq,iqs7211e"; + reg = <0x56>; + irq-gpios = <&gpio 4 (GPIO_ACTIVE_LOW | + GPIO_OPEN_DRAIN)>; + + trackpad { + event-tap { + linux,code = <KEY_PLAYPAUSE>; + }; + + event-tap-double { + linux,code = <KEY_SHUFFLE>; + }; + + event-tap-triple { + linux,code = <KEY_AGAIN>; + }; + + event-hold { + linux,code = <KEY_STOP>; + }; + + event-palm { + linux,code = <KEY_EXIT>; + }; + + event-swipe-x-pos { + linux,code = <KEY_REWIND>; + }; + + event-swipe-x-pos-hold { + linux,code = <KEY_PREVIOUS>; + }; + + event-swipe-x-neg { + linux,code = <KEY_FASTFORWARD>; + }; + + event-swipe-x-neg-hold { + linux,code = <KEY_NEXT>; + }; + + event-swipe-y-pos { + linux,code = <KEY_VOLUMEUP>; + }; + + event-swipe-y-pos-hold { + linux,code = <KEY_MUTE>; + }; + + event-swipe-y-neg { + linux,code = <KEY_VOLUMEDOWN>; + }; + + event-swipe-y-neg-hold { + linux,code = <KEY_MUTE>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.yaml b/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.yaml index ef4c841387bd..f2808cb4d99d 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.yaml +++ b/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.yaml @@ -93,6 +93,12 @@ properties: minimum: 1 maximum: 255 + threshold: + description: Allows setting the "click"-threshold in the range from 0 to 255. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + touchscreen-size-x: true touchscreen-size-y: true touchscreen-fuzz-x: true diff --git a/Documentation/devicetree/bindings/input/touchscreen/eeti,exc3000.yaml b/Documentation/devicetree/bindings/input/touchscreen/eeti,exc3000.yaml index 007adbc89c14..9dc25d30a0a8 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/eeti,exc3000.yaml +++ b/Documentation/devicetree/bindings/input/touchscreen/eeti,exc3000.yaml @@ -24,6 +24,8 @@ properties: maxItems: 1 reset-gpios: maxItems: 1 + vdd-supply: + description: Power supply regulator for the chip touchscreen-size-x: true touchscreen-size-y: true touchscreen-inverted-x: true diff --git a/Documentation/devicetree/bindings/input/touchscreen/melfas,mms114.yaml b/Documentation/devicetree/bindings/input/touchscreen/melfas,mms114.yaml index fdd02898e249..07f9dd6b1c9c 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/melfas,mms114.yaml +++ b/Documentation/devicetree/bindings/input/touchscreen/melfas,mms114.yaml @@ -52,6 +52,11 @@ properties: touchscreen-swapped-x-y: true touchscreen-max-pressure: true + linux,keycodes: + description: Keycodes for the touch keys + minItems: 1 + maxItems: 15 + additionalProperties: false required: diff --git a/Documentation/devicetree/bindings/input/touchscreen/stmpe.txt b/Documentation/devicetree/bindings/input/touchscreen/stmpe.txt deleted file mode 100644 index 238b51555c04..000000000000 --- a/Documentation/devicetree/bindings/input/touchscreen/stmpe.txt +++ /dev/null @@ -1,108 +0,0 @@ -STMPE Touchscreen ----------------- - -Required properties: - - compatible: "st,stmpe-ts" - -Optional properties: -- st,ave-ctrl : Sample average control - 0 -> 1 sample - 1 -> 2 samples - 2 -> 4 samples - 3 -> 8 samples -- st,touch-det-delay : Touch detect interrupt delay (recommended is 3) - 0 -> 10 us - 1 -> 50 us - 2 -> 100 us - 3 -> 500 us - 4 -> 1 ms - 5 -> 5 ms - 6 -> 10 ms - 7 -> 50 ms -- st,settling : Panel driver settling time (recommended is 2) - 0 -> 10 us - 1 -> 100 us - 2 -> 500 us - 3 -> 1 ms - 4 -> 5 ms - 5 -> 10 ms - 6 -> 50 ms - 7 -> 100 ms -- st,fraction-z : Length of the fractional part in z (recommended is 7) - (fraction-z ([0..7]) = Count of the fractional part) -- st,i-drive : current limit value of the touchscreen drivers - 0 -> 20 mA (typical 35mA max) - 1 -> 50 mA (typical 80 mA max) - -Optional properties common with MFD (deprecated): - - st,sample-time : ADC conversion time in number of clock. - 0 -> 36 clocks - 1 -> 44 clocks - 2 -> 56 clocks - 3 -> 64 clocks - 4 -> 80 clocks (recommended) - 5 -> 96 clocks - 6 -> 124 clocks - - st,mod-12b : ADC Bit mode - 0 -> 10bit ADC - 1 -> 12bit ADC - - st,ref-sel : ADC reference source - 0 -> internal - 1 -> external - - st,adc-freq : ADC Clock speed - 0 -> 1.625 MHz - 1 -> 3.25 MHz - 2 || 3 -> 6.5 MHz - -Node should be child node of stmpe node to which it belongs. - -Note that common ADC settings of stmpe_touchscreen (child) will take precedence -over the settings done in MFD. - -Example: - -stmpe811@41 { - compatible = "st,stmpe811"; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_touch_int>; - #address-cells = <1>; - #size-cells = <0>; - reg = <0x41>; - interrupts = <10 IRQ_TYPE_LEVEL_LOW>; - interrupt-parent = <&gpio4>; - interrupt-controller; - id = <0>; - blocks = <0x5>; - irq-trigger = <0x1>; - /* Common ADC settings */ - /* 3.25 MHz ADC clock speed */ - st,adc-freq = <1>; - /* 12-bit ADC */ - st,mod-12b = <1>; - /* internal ADC reference */ - st,ref-sel = <0>; - /* ADC converstion time: 80 clocks */ - st,sample-time = <4>; - - stmpe_touchscreen { - compatible = "st,stmpe-ts"; - reg = <0>; - /* 8 sample average control */ - st,ave-ctrl = <3>; - /* 5 ms touch detect interrupt delay */ - st,touch-det-delay = <5>; - /* 1 ms panel driver settling time */ - st,settling = <3>; - /* 7 length fractional part in z */ - st,fraction-z = <7>; - /* - * 50 mA typical 80 mA max touchscreen drivers - * current limit value - */ - st,i-drive = <1>; - }; - stmpe_adc { - compatible = "st,stmpe-adc"; - st,norequest-mask = <0x0F>; - }; -}; diff --git a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml index 895592da9626..431c13335c40 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml +++ b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml @@ -10,6 +10,13 @@ maintainers: - Dmitry Torokhov <dmitry.torokhov@gmail.com> properties: + panel: + description: If this touchscreen is integrally connected to a panel, this + is a reference to that panel. The presence of this reference indicates + that the touchscreen should be power sequenced together with the panel + and that they may share power and/or reset signals. + $ref: /schemas/types.yaml#/definitions/phandle + touchscreen-min-x: description: minimum x coordinate reported $ref: /schemas/types.yaml#/definitions/uint32 diff --git a/Documentation/devicetree/bindings/input/touchscreen/tsc2007.txt b/Documentation/devicetree/bindings/input/touchscreen/tsc2007.txt index ed00f61b8c08..210486a3fb11 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/tsc2007.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/tsc2007.txt @@ -6,7 +6,7 @@ Required properties: - ti,x-plate-ohms: X-plate resistance in ohms. Optional properties: -- gpios: the interrupt gpio the chip is connected to (trough the penirq pin). +- gpios: the interrupt gpio the chip is connected to (through the penirq pin). The penirq pin goes to low when the panel is touched. (see GPIO binding[1] for more details). - interrupts: (gpio) interrupt to which the chip is connected diff --git a/Documentation/devicetree/bindings/input/twl4030-pwrbutton.txt b/Documentation/devicetree/bindings/input/twl4030-pwrbutton.txt index f5021214edec..6c201a2ba8ac 100644 --- a/Documentation/devicetree/bindings/input/twl4030-pwrbutton.txt +++ b/Documentation/devicetree/bindings/input/twl4030-pwrbutton.txt @@ -1,7 +1,7 @@ Texas Instruments TWL family (twl4030) pwrbutton module This module is part of the TWL4030. For more details about the whole -chip see Documentation/devicetree/bindings/mfd/twl-family.txt. +chip see Documentation/devicetree/bindings/mfd/ti,twl.yaml. This module provides a simple power button event via an Interrupt. diff --git a/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml b/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml index 5d17bdcfdf70..73f809cdb783 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml @@ -25,14 +25,20 @@ properties: - const: qcom,msm8998-bwmon # BWMON v4 - items: - enum: + - qcom,sc7180-cpu-bwmon - qcom,sc7280-cpu-bwmon - qcom,sc8280xp-cpu-bwmon - qcom,sdm845-cpu-bwmon + - qcom,sm6350-llcc-bwmon + - qcom,sm8250-cpu-bwmon - qcom,sm8550-cpu-bwmon - const: qcom,sdm845-bwmon # BWMON v4, unified register space - items: - enum: + - qcom,sc7180-llcc-bwmon - qcom,sc8280xp-llcc-bwmon + - qcom,sm6350-cpu-bwmon + - qcom,sm8250-llcc-bwmon - qcom,sm8550-llcc-bwmon - const: qcom,sc7280-llcc-bwmon - const: qcom,sc7280-llcc-bwmon # BWMON v5 diff --git a/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml b/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml index 9d0a98d77ae9..21dae0b92819 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml @@ -21,6 +21,7 @@ properties: - enum: - qcom,sc7180-osm-l3 - qcom,sc8180x-osm-l3 + - qcom,sdm670-osm-l3 - qcom,sdm845-osm-l3 - qcom,sm6350-osm-l3 - qcom,sm8150-osm-l3 diff --git a/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml index 4d93ad415e0b..a46497af1fd8 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml @@ -18,9 +18,6 @@ description: | least one RPMh device child node pertaining to their RSC and each provider can map to multiple RPMh resources. -allOf: - - $ref: qcom,rpmh-common.yaml# - properties: reg: maxItems: 1 @@ -91,6 +88,7 @@ properties: - qcom,sm8250-mc-virt - qcom,sm8250-mmss-noc - qcom,sm8250-npu-noc + - qcom,sm8250-qup-virt - qcom,sm8250-system-noc - qcom,sm8350-aggre1-noc - qcom,sm8350-aggre2-noc @@ -107,7 +105,19 @@ properties: required: - compatible - - reg + +allOf: + - $ref: qcom,rpmh-common.yaml# + - if: + not: + properties: + compatible: + enum: + - qcom,sm8250-qup-virt + then: + required: + - reg + unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.yaml index e84e4f33b358..3d06db98e978 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.yaml @@ -35,6 +35,7 @@ properties: - amlogic,meson-sm1-gpio-intc - amlogic,meson-a1-gpio-intc - amlogic,meson-s4-gpio-intc + - amlogic,c3-gpio-intc - const: amlogic,meson-gpio-intc reg: diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml index 39e64c7f6360..0f4a062c9d6f 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml @@ -49,7 +49,7 @@ properties: The 2nd cell contains the interrupt number for the interrupt type. SPI interrupts are in the range [0-987]. PPI interrupts are in the - range [0-15]. Extented SPI interrupts are in the range [0-1023]. + range [0-15]. Extended SPI interrupts are in the range [0-1023]. Extended PPI interrupts are in the range [0-127]. The 3rd cell is the flags, encoded as follows: @@ -106,6 +106,12 @@ properties: $ref: /schemas/types.yaml#/definitions/uint32 maximum: 4096 + dma-noncoherent: + description: + Present if the GIC redistributors permit programming shareability + and cacheability attributes but are connected to a non-coherent + downstream interconnect. + msi-controller: description: Only present if the Message Based Interrupt functionality is @@ -193,6 +199,12 @@ patternProperties: compatible: const: arm,gic-v3-its + dma-noncoherent: + description: + Present if the GIC ITS permits programming shareability and + cacheability attributes but is connected to a non-coherent + downstream interconnect. + msi-controller: true "#msi-cells": diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,versatile-fpga-irq.txt b/Documentation/devicetree/bindings/interrupt-controller/arm,versatile-fpga-irq.txt index 2a1d16bdf834..ea939f54c5eb 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/arm,versatile-fpga-irq.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,versatile-fpga-irq.txt @@ -6,7 +6,7 @@ controllers are OR:ed together and fed to the CPU tile's IRQ input. Each instance can handle up to 32 interrupts. Required properties: -- compatible: "arm,versatile-fpga-irq" or "oxsemi,ox810se-rps-irq" +- compatible: "arm,versatile-fpga-irq" - interrupt-controller: Identifies the node as an interrupt controller - #interrupt-cells: The number of cells to define the interrupts. Must be 1 as the FPGA IRQ controller has no configuration options for interrupt @@ -19,6 +19,8 @@ Required properties: the system till not make it possible for devices to request these interrupts. +The "oxsemi,ox810se-rps-irq" compatible is deprecated. + Example: pic: pic@14000000 { diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt index 0f1af5a1c12e..bdd173056f72 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt @@ -70,7 +70,7 @@ Bank 1: 25: DMA9 26: DMA10 27: DMA11-14 - shared interrupt for DMA 11 to 14 -28: DMAALL - triggers on all dma interrupts (including chanel 15) +28: DMAALL - triggers on all dma interrupts (including channel 15) 29: AUX 30: ARM 31: VPUDMA diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.yaml index c680de1cbd56..786f2426399b 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.yaml @@ -59,7 +59,7 @@ description: > .. 31 ........................ X - The BCM3380 Level 1 / Level 2 interrrupt controller shows up in various forms + The BCM3380 Level 1 / Level 2 interrupt controller shows up in various forms on many BCM338x/BCM63xx chipsets. It has the following properties: - outputs a single interrupt signal to its interrupt controller parent diff --git a/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.yaml b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.yaml index a106ba6e810b..86d61896f591 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.yaml @@ -31,9 +31,11 @@ properties: - qcom,sc7180-pdc - qcom,sc7280-pdc - qcom,sc8280xp-pdc + - qcom,sdm670-pdc - qcom,sdm845-pdc - qcom,sdx55-pdc - qcom,sdx65-pdc + - qcom,sm4450-pdc - qcom,sm6350-pdc - qcom,sm8150-pdc - qcom,sm8250-pdc diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.yaml b/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.yaml index 95033cb514fb..b417341fc8ae 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.yaml @@ -37,6 +37,7 @@ properties: - renesas,intc-ex-r8a77990 # R-Car E3 - renesas,intc-ex-r8a77995 # R-Car D3 - renesas,intc-ex-r8a779a0 # R-Car V3U + - renesas,intc-ex-r8a779f0 # R-Car S4-8 - renesas,intc-ex-r8a779g0 # R-Car V4H - const: renesas,irqc diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,rzg2l-irqc.yaml b/Documentation/devicetree/bindings/interrupt-controller/renesas,rzg2l-irqc.yaml index 33b90e975e33..2ef3081eaaf3 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/renesas,rzg2l-irqc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/renesas,rzg2l-irqc.yaml @@ -19,20 +19,19 @@ description: | - NMI edge select (NMI is not treated as NMI exception and supports fall edge and stand-up edge detection interrupts) -allOf: - - $ref: /schemas/interrupt-controller.yaml# - properties: compatible: items: - enum: + - renesas,r9a07g043u-irqc # RZ/G2UL - renesas,r9a07g044-irqc # RZ/G2{L,LC} - renesas,r9a07g054-irqc # RZ/V2L - const: renesas,rzg2l-irqc '#interrupt-cells': - description: The first cell should contain external interrupt number (IRQ0-7) and the - second cell is used to specify the flag. + description: The first cell should contain a macro RZG2L_{NMI,IRQX} included in the + include/dt-bindings/interrupt-controller/irqc-rzg2l.h and the second + cell is used to specify the flag. const: 2 '#address-cells': @@ -44,7 +43,96 @@ properties: maxItems: 1 interrupts: - maxItems: 41 + minItems: 41 + items: + - description: NMI interrupt + - description: IRQ0 interrupt + - description: IRQ1 interrupt + - description: IRQ2 interrupt + - description: IRQ3 interrupt + - description: IRQ4 interrupt + - description: IRQ5 interrupt + - description: IRQ6 interrupt + - description: IRQ7 interrupt + - description: GPIO interrupt, TINT0 + - description: GPIO interrupt, TINT1 + - description: GPIO interrupt, TINT2 + - description: GPIO interrupt, TINT3 + - description: GPIO interrupt, TINT4 + - description: GPIO interrupt, TINT5 + - description: GPIO interrupt, TINT6 + - description: GPIO interrupt, TINT7 + - description: GPIO interrupt, TINT8 + - description: GPIO interrupt, TINT9 + - description: GPIO interrupt, TINT10 + - description: GPIO interrupt, TINT11 + - description: GPIO interrupt, TINT12 + - description: GPIO interrupt, TINT13 + - description: GPIO interrupt, TINT14 + - description: GPIO interrupt, TINT15 + - description: GPIO interrupt, TINT16 + - description: GPIO interrupt, TINT17 + - description: GPIO interrupt, TINT18 + - description: GPIO interrupt, TINT19 + - description: GPIO interrupt, TINT20 + - description: GPIO interrupt, TINT21 + - description: GPIO interrupt, TINT22 + - description: GPIO interrupt, TINT23 + - description: GPIO interrupt, TINT24 + - description: GPIO interrupt, TINT25 + - description: GPIO interrupt, TINT26 + - description: GPIO interrupt, TINT27 + - description: GPIO interrupt, TINT28 + - description: GPIO interrupt, TINT29 + - description: GPIO interrupt, TINT30 + - description: GPIO interrupt, TINT31 + - description: Bus error interrupt + + interrupt-names: + minItems: 41 + items: + - const: nmi + - const: irq0 + - const: irq1 + - const: irq2 + - const: irq3 + - const: irq4 + - const: irq5 + - const: irq6 + - const: irq7 + - const: tint0 + - const: tint1 + - const: tint2 + - const: tint3 + - const: tint4 + - const: tint5 + - const: tint6 + - const: tint7 + - const: tint8 + - const: tint9 + - const: tint10 + - const: tint11 + - const: tint12 + - const: tint13 + - const: tint14 + - const: tint15 + - const: tint16 + - const: tint17 + - const: tint18 + - const: tint19 + - const: tint20 + - const: tint21 + - const: tint22 + - const: tint23 + - const: tint24 + - const: tint25 + - const: tint26 + - const: tint27 + - const: tint28 + - const: tint29 + - const: tint30 + - const: tint31 + - const: bus-err clocks: maxItems: 2 @@ -72,6 +160,23 @@ required: - power-domains - resets +allOf: + - $ref: /schemas/interrupt-controller.yaml# + + - if: + properties: + compatible: + contains: + const: renesas,r9a07g043u-irqc + then: + properties: + interrupts: + minItems: 42 + interrupt-names: + minItems: 42 + required: + - interrupt-names + unevaluatedProperties: false examples: @@ -80,55 +185,66 @@ examples: #include <dt-bindings/clock/r9a07g044-cpg.h> irqc: interrupt-controller@110a0000 { - compatible = "renesas,r9a07g044-irqc", "renesas,rzg2l-irqc"; - reg = <0x110a0000 0x10000>; - #interrupt-cells = <2>; - #address-cells = <0>; - interrupt-controller; - interrupts = <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 444 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 445 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 446 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 447 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 448 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 449 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 450 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 451 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 452 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 453 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 454 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 455 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 456 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 457 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 458 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 459 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 460 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 461 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 462 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 463 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 464 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 465 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 466 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 467 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 468 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 469 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 470 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 471 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 472 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 473 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 474 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 475 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD R9A07G044_IA55_CLK>, - <&cpg CPG_MOD R9A07G044_IA55_PCLK>; - clock-names = "clk", "pclk"; - power-domains = <&cpg>; - resets = <&cpg R9A07G044_IA55_RESETN>; + compatible = "renesas,r9a07g044-irqc", "renesas,rzg2l-irqc"; + reg = <0x110a0000 0x10000>; + #interrupt-cells = <2>; + #address-cells = <0>; + interrupt-controller; + interrupts = <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 444 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 445 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 446 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 447 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 448 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 449 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 450 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 451 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 452 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 453 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 454 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 455 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 456 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 457 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 458 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 459 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 460 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 461 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 462 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 463 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 464 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 465 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 466 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 467 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 468 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 469 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 470 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 471 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 472 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 473 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 474 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 475 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "nmi", + "irq0", "irq1", "irq2", "irq3", + "irq4", "irq5", "irq6", "irq7", + "tint0", "tint1", "tint2", "tint3", + "tint4", "tint5", "tint6", "tint7", + "tint8", "tint9", "tint10", "tint11", + "tint12", "tint13", "tint14", "tint15", + "tint16", "tint17", "tint18", "tint19", + "tint20", "tint21", "tint22", "tint23", + "tint24", "tint25", "tint26", "tint27", + "tint28", "tint29", "tint30", "tint31"; + clocks = <&cpg CPG_MOD R9A07G044_IA55_CLK>, + <&cpg CPG_MOD R9A07G044_IA55_PCLK>; + clock-names = "clk", "pclk"; + power-domains = <&cpg>; + resets = <&cpg R9A07G044_IA55_RESETN>; }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml b/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml index dc1f28e55266..0c07e8dda445 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml @@ -65,6 +65,8 @@ properties: - items: - enum: - allwinner,sun20i-d1-plic + - sophgo,cv1800b-plic + - sophgo,sg2042-plic - thead,th1520-plic - const: thead,c900-plic - items: diff --git a/Documentation/devicetree/bindings/interrupt-controller/st,sti-irq-syscfg.txt b/Documentation/devicetree/bindings/interrupt-controller/st,sti-irq-syscfg.txt deleted file mode 100644 index 977d7ed3670e..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/st,sti-irq-syscfg.txt +++ /dev/null @@ -1,30 +0,0 @@ -STMicroelectronics STi System Configuration Controlled IRQs ------------------------------------------------------------ - -On STi based systems; External, CTI (Core Sight), PMU (Performance Management), -and PL310 L2 Cache IRQs are controlled using System Configuration registers. -This driver is used to unmask them prior to use. - -Required properties: -- compatible : Should be "st,stih407-irq-syscfg" -- st,syscfg : Phandle to Cortex-A9 IRQ system config registers -- st,irq-device : Array of IRQs to enable - should be 2 in length -- st,fiq-device : Array of FIQs to enable - should be 2 in length - -Optional properties: -- st,invert-ext : External IRQs can be inverted at will. This property inverts - these IRQs using bitwise logic. A number of defines have been - provided for convenience: - ST_IRQ_SYSCFG_EXT_1_INV - ST_IRQ_SYSCFG_EXT_2_INV - ST_IRQ_SYSCFG_EXT_3_INV -Example: - -irq-syscfg { - compatible = "st,stih407-irq-syscfg"; - st,syscfg = <&syscfg_cpu>; - st,irq-device = <ST_IRQ_SYSCFG_PMU_0>, - <ST_IRQ_SYSCFG_PMU_1>; - st,fiq-device = <ST_IRQ_SYSCFG_DISABLED>, - <ST_IRQ_SYSCFG_DISABLED>; -}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/st,stih407-irq-syscfg.yaml b/Documentation/devicetree/bindings/interrupt-controller/st,stih407-irq-syscfg.yaml new file mode 100644 index 000000000000..2b153d7c5421 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/st,stih407-irq-syscfg.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/st,stih407-irq-syscfg.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics STi System Configuration Controlled IRQs + +maintainers: + - Patrice Chotard <patrice.chotard@foss.st.com> + +description: + On STi based systems; External, CTI (Core Sight), PMU (Performance + Management), and PL310 L2 Cache IRQs are controlled using System + Configuration registers. This device is used to unmask them prior to use. + +properties: + compatible: + const: st,stih407-irq-syscfg + + st,syscfg: + description: Phandle to Cortex-A9 IRQ system config registers + $ref: /schemas/types.yaml#/definitions/phandle + + st,irq-device: + description: Array of IRQs to enable. + $ref: /schemas/types.yaml#/definitions/uint32-array + items: + - description: Enable the IRQ of the channel one. + - description: Enable the IRQ of the channel two. + + st,fiq-device: + description: Array of FIQs to enable. + $ref: /schemas/types.yaml#/definitions/uint32-array + items: + - description: Enable the IRQ of the channel one. + - description: Enable the IRQ of the channel two. + + st,invert-ext: + description: External IRQs can be inverted at will. This property inverts + these three IRQs using bitwise logic, each one being encoded respectively + on the first, second and fourth bit. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 1, 2, 3, 4, 5, 6 ] + +required: + - compatible + - st,syscfg + - st,irq-device + - st,fiq-device + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq-st.h> + irq-syscfg { + compatible = "st,stih407-irq-syscfg"; + st,syscfg = <&syscfg_cpu>; + st,irq-device = <ST_IRQ_SYSCFG_PMU_0>, + <ST_IRQ_SYSCFG_PMU_1>; + st,fiq-device = <ST_IRQ_SYSCFG_DISABLED>, + <ST_IRQ_SYSCFG_DISABLED>; + }; +... diff --git a/Documentation/devicetree/bindings/interrupt-controller/thead,c900-aclint-mswi.yaml b/Documentation/devicetree/bindings/interrupt-controller/thead,c900-aclint-mswi.yaml new file mode 100644 index 000000000000..065f2544b63b --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/thead,c900-aclint-mswi.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/thead,c900-aclint-mswi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sophgo sg2042 CLINT Machine-level Software Interrupt Device + +maintainers: + - Inochi Amaoto <inochiama@outlook.com> + +properties: + compatible: + items: + - enum: + - sophgo,sg2042-aclint-mswi + - const: thead,c900-aclint-mswi + + reg: + maxItems: 1 + + interrupts-extended: + minItems: 1 + maxItems: 4095 + +additionalProperties: false + +required: + - compatible + - reg + - interrupts-extended + +examples: + - | + interrupt-controller@94000000 { + compatible = "sophgo,sg2042-aclint-mswi", "thead,c900-aclint-mswi"; + interrupts-extended = <&cpu1intc 3>, + <&cpu2intc 3>, + <&cpu3intc 3>, + <&cpu4intc 3>; + reg = <0x94000000 0x00010000>; + }; +... diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml index 65523d9459d8..3cd5a1822e14 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.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/interrupt-controller/ti,pruss-intc.yaml# diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu.yaml b/Documentation/devicetree/bindings/iommu/arm,smmu.yaml index 3a31a979709b..b1b2cf81b42f 100644 --- a/Documentation/devicetree/bindings/iommu/arm,smmu.yaml +++ b/Documentation/devicetree/bindings/iommu/arm,smmu.yaml @@ -271,6 +271,47 @@ allOf: enum: - qcom,msm8998-smmu-v2 - qcom,sdm630-smmu-v2 + then: + anyOf: + - properties: + clock-names: + items: + - const: bus + clocks: + items: + - description: bus clock required for downstream bus access and for + the smmu ptw + - properties: + clock-names: + items: + - const: iface + - const: mem + - const: mem_iface + clocks: + items: + - description: interface clock required to access smmu's registers + through the TCU's programming interface. + - description: bus clock required for memory access + - description: bus clock required for GPU memory access + - properties: + clock-names: + items: + - const: iface-mm + - const: iface-smmu + - const: bus-smmu + clocks: + items: + - description: interface clock required to access mnoc's registers + through the TCU's programming interface. + - description: interface clock required to access smmu's registers + through the TCU's programming interface. + - description: bus clock required for the smmu ptw + + - if: + properties: + compatible: + contains: + enum: - qcom,sm6375-smmu-v2 then: anyOf: diff --git a/Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml b/Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml index 5b6395bc10e0..ea6b0f5f24de 100644 --- a/Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml +++ b/Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml @@ -78,6 +78,9 @@ properties: - mediatek,mt8173-m4u # generation two - mediatek,mt8183-m4u # generation two - mediatek,mt8186-iommu-mm # generation two + - mediatek,mt8188-iommu-vdo # generation two + - mediatek,mt8188-iommu-vpp # generation two + - mediatek,mt8188-iommu-infra # generation two - mediatek,mt8192-m4u # generation two - mediatek,mt8195-iommu-vdo # generation two - mediatek,mt8195-iommu-vpp # generation two @@ -123,6 +126,7 @@ properties: description: | This is the mtk_m4u_id according to the HW. Specifies the mtk_m4u_id as defined in + dt-binding/memory/mediatek,mt8188-memory-port.h for mt8188, dt-binding/memory/mt2701-larb-port.h for mt2701 and mt7623, dt-binding/memory/mt2712-larb-port.h for mt2712, dt-binding/memory/mt6779-larb-port.h for mt6779, @@ -155,6 +159,8 @@ allOf: - mediatek,mt6795-m4u - mediatek,mt8173-m4u - mediatek,mt8186-iommu-mm + - mediatek,mt8188-iommu-vdo + - mediatek,mt8188-iommu-vpp - mediatek,mt8192-m4u - mediatek,mt8195-iommu-vdo - mediatek,mt8195-iommu-vpp @@ -168,6 +174,8 @@ allOf: compatible: enum: - mediatek,mt8186-iommu-mm + - mediatek,mt8188-iommu-vdo + - mediatek,mt8188-iommu-vpp - mediatek,mt8192-m4u - mediatek,mt8195-iommu-vdo - mediatek,mt8195-iommu-vpp @@ -194,7 +202,9 @@ allOf: properties: compatible: contains: - const: mediatek,mt8195-iommu-infra + enum: + - mediatek,mt8188-iommu-infra + - mediatek,mt8195-iommu-infra then: required: diff --git a/Documentation/devicetree/bindings/iommu/qcom,iommu.yaml b/Documentation/devicetree/bindings/iommu/qcom,iommu.yaml index d9fabdf930d9..a74eb899c381 100644 --- a/Documentation/devicetree/bindings/iommu/qcom,iommu.yaml +++ b/Documentation/devicetree/bindings/iommu/qcom,iommu.yaml @@ -17,11 +17,16 @@ description: | properties: compatible: - items: - - enum: - - qcom,msm8916-iommu - - qcom,msm8953-iommu - - const: qcom,msm-iommu-v1 + oneOf: + - items: + - enum: + - qcom,msm8916-iommu + - qcom,msm8953-iommu + - const: qcom,msm-iommu-v1 + - items: + - enum: + - qcom,msm8976-iommu + - const: qcom,msm-iommu-v2 clocks: items: @@ -64,6 +69,8 @@ patternProperties: enum: - qcom,msm-iommu-v1-ns - qcom,msm-iommu-v1-sec + - qcom,msm-iommu-v2-ns + - qcom,msm-iommu-v2-sec interrupts: maxItems: 1 @@ -71,6 +78,11 @@ patternProperties: reg: maxItems: 1 + qcom,ctx-asid: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + The ASID number associated to the context bank. + required: - compatible - interrupts diff --git a/Documentation/devicetree/bindings/iommu/xen,grant-dma.yaml b/Documentation/devicetree/bindings/iommu/xen,grant-dma.yaml index be1539d234f9..3528b81daa25 100644 --- a/Documentation/devicetree/bindings/iommu/xen,grant-dma.yaml +++ b/Documentation/devicetree/bindings/iommu/xen,grant-dma.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/iommu/xen,grant-dma.yaml# diff --git a/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-kcs-bmc.yaml b/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-kcs-bmc.yaml index 4ff6fabfcb30..129e32c4c774 100644 --- a/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-kcs-bmc.yaml +++ b/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-kcs-bmc.yaml @@ -41,7 +41,7 @@ properties: - description: STR register aspeed,lpc-io-reg: - $ref: '/schemas/types.yaml#/definitions/uint32-array' + $ref: /schemas/types.yaml#/definitions/uint32-array minItems: 1 maxItems: 2 description: | @@ -50,7 +50,7 @@ properties: status address may be optionally provided. aspeed,lpc-interrupts: - $ref: "/schemas/types.yaml#/definitions/uint32-array" + $ref: /schemas/types.yaml#/definitions/uint32-array minItems: 2 maxItems: 2 description: | @@ -63,12 +63,12 @@ properties: kcs_chan: deprecated: true - $ref: '/schemas/types.yaml#/definitions/uint32' + $ref: /schemas/types.yaml#/definitions/uint32 description: The LPC channel number in the controller kcs_addr: deprecated: true - $ref: '/schemas/types.yaml#/definitions/uint32' + $ref: /schemas/types.yaml#/definitions/uint32 description: The host CPU IO map address required: diff --git a/Documentation/devicetree/bindings/ipmi/ipmi-ipmb.yaml b/Documentation/devicetree/bindings/ipmi/ipmi-ipmb.yaml index 3f25cdb4e99b..52647bff31af 100644 --- a/Documentation/devicetree/bindings/ipmi/ipmi-ipmb.yaml +++ b/Documentation/devicetree/bindings/ipmi/ipmi-ipmb.yaml @@ -18,7 +18,7 @@ properties: device_type: items: - - const: "ipmi" + - const: ipmi reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/ipmi/ipmi-smic.yaml b/Documentation/devicetree/bindings/ipmi/ipmi-smic.yaml index c1b4bf95ef99..4bffa3d86128 100644 --- a/Documentation/devicetree/bindings/ipmi/ipmi-smic.yaml +++ b/Documentation/devicetree/bindings/ipmi/ipmi-smic.yaml @@ -20,7 +20,7 @@ properties: device_type: items: - - const: "ipmi" + - const: ipmi reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/leds/backlight/common.yaml b/Documentation/devicetree/bindings/leds/backlight/common.yaml index 3b60afbab68b..e0983e44934c 100644 --- a/Documentation/devicetree/bindings/leds/backlight/common.yaml +++ b/Documentation/devicetree/bindings/leds/backlight/common.yaml @@ -33,4 +33,21 @@ properties: due to restrictions in a specific system, such as mounting conditions. $ref: /schemas/types.yaml#/definitions/uint32 + brightness-levels: + description: + Array of distinct brightness levels. The levels must be in the range + accepted by the underlying LED device. Typically these are in the range + from 0 to 255, but any range starting at 0 will do, as long as they are + accepted by the LED. + The 0 value means a 0% of brightness (darkest/off), while the last value + in the array represents a full 100% brightness (brightest). + If this array is not provided, the driver default mapping is used. + $ref: /schemas/types.yaml#/definitions/uint32-array + + default-brightness-level: + description: + The default brightness level (index into the array defined by the + "brightness-levels" property). + $ref: /schemas/types.yaml#/definitions/uint32 + additionalProperties: true diff --git a/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml index d7b78198abc2..f5554da6bc6c 100644 --- a/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml +++ b/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml @@ -16,6 +16,9 @@ description: can also be used to describe a backlight device controlled by the output of a LED driver. +allOf: + - $ref: common.yaml# + properties: compatible: const: led-backlight @@ -26,25 +29,11 @@ properties: items: maxItems: 1 - brightness-levels: - description: - Array of distinct brightness levels. The levels must be in the range - accepted by the underlying LED devices. This is used to translate a - backlight brightness level into a LED brightness level. If it is not - provided, the identity mapping is used. - $ref: /schemas/types.yaml#/definitions/uint32-array - - default-brightness-level: - description: - The default brightness level (index into the array defined by the - "brightness-levels" property). - $ref: /schemas/types.yaml#/definitions/uint32 - required: - compatible - leds -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/leds/backlight/max8925-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/max8925-backlight.txt deleted file mode 100644 index b4cffdaa4137..000000000000 --- a/Documentation/devicetree/bindings/leds/backlight/max8925-backlight.txt +++ /dev/null @@ -1,10 +0,0 @@ -88pm860x-backlight bindings - -Optional properties: - - maxim,max8925-dual-string: whether support dual string - -Example: - - backlights { - maxim,max8925-dual-string = <0>; - }; diff --git a/Documentation/devicetree/bindings/leds/backlight/mediatek,mt6370-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/mediatek,mt6370-backlight.yaml index 5533b6562d92..16fc98e71233 100644 --- a/Documentation/devicetree/bindings/leds/backlight/mediatek,mt6370-backlight.yaml +++ b/Documentation/devicetree/bindings/leds/backlight/mediatek,mt6370-backlight.yaml @@ -66,7 +66,7 @@ properties: mediatek,bled-ocp-shutdown: description: | - Enable the backlight shutdown when OCP level triggerred. + Enable the backlight shutdown when OCP level triggered. type: boolean mediatek,bled-ocp-microamp: diff --git a/Documentation/devicetree/bindings/leds/backlight/mps,mp3309c.yaml b/Documentation/devicetree/bindings/leds/backlight/mps,mp3309c.yaml new file mode 100644 index 000000000000..4191e33626f5 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/backlight/mps,mp3309c.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/backlight/mps,mp3309c.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MPS MP3309C backlight + +maintainers: + - Flavio Suligoi <f.suligoi@asem.it> + +description: | + The Monolithic Power (MPS) MP3309C is a WLED step-up converter, featuring a + programmable switching frequency to optimize efficiency. + It supports two different dimming modes: + + - analog mode, via I2C commands (default) + - PWM controlled mode. + + The datasheet is available at: + https://www.monolithicpower.com/en/mp3309c.html + +allOf: + - $ref: common.yaml# + +properties: + compatible: + const: mps,mp3309c + + reg: + maxItems: 1 + + pwms: + description: if present, the backlight is controlled in PWM mode. + maxItems: 1 + + enable-gpios: + description: GPIO used to enable the backlight in "analog-i2c" dimming mode. + maxItems: 1 + + mps,overvoltage-protection-microvolt: + description: Overvoltage protection (13.5V, 24V or 35.5V). + enum: [ 13500000, 24000000, 35500000 ] + default: 35500000 + + mps,no-sync-mode: + description: disable synchronous rectification mode + type: boolean + +required: + - compatible + - reg + - max-brightness + - default-brightness + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + /* Backlight with PWM control */ + backlight_pwm: backlight@17 { + compatible = "mps,mp3309c"; + reg = <0x17>; + pwms = <&pwm1 0 3333333 0>; /* 300 Hz --> (1/f) * 1*10^9 */ + max-brightness = <100>; + default-brightness = <80>; + mps,overvoltage-protection-microvolt = <24000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml index 535690288990..b71f6454a4ac 100644 --- a/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml +++ b/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml @@ -11,6 +11,9 @@ maintainers: - Daniel Thompson <daniel.thompson@linaro.org> - Jingoo Han <jingoohan1@gmail.com> +allOf: + - $ref: common.yaml# + properties: compatible: const: pwm-backlight @@ -39,21 +42,6 @@ properties: Delay in ms between disabling the backlight using GPIO and setting PWM value to 0. - brightness-levels: - description: - Array of distinct brightness levels. Typically these are in the range - from 0 to 255, but any range starting at 0 will do. The actual brightness - level (PWM duty cycle) will be interpolated from these values. 0 means a - 0% duty cycle (darkest/off), while the last value in the array represents - a 100% duty cycle (brightest). - $ref: /schemas/types.yaml#/definitions/uint32-array - - default-brightness-level: - description: - The default brightness level (index into the array defined by the - "brightness-levels" property). - $ref: /schemas/types.yaml#/definitions/uint32 - num-interpolated-steps: description: Number of interpolated steps between each value of brightness-levels @@ -69,7 +57,7 @@ required: - compatible - pwms -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/leds/common.yaml b/Documentation/devicetree/bindings/leds/common.yaml index 58b492d00246..c8d0ba5f2327 100644 --- a/Documentation/devicetree/bindings/leds/common.yaml +++ b/Documentation/devicetree/bindings/leds/common.yaml @@ -43,7 +43,7 @@ properties: LED_COLOR_ID available, add a new one. $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 - maximum: 9 + maximum: 14 function-enumerator: description: @@ -83,8 +83,7 @@ properties: - enum: # LED will act as a back-light, controlled by the framebuffer system - backlight - # LED will turn on (but for leds-gpio see "default-state" property in - # Documentation/devicetree/bindings/leds/leds-gpio.yaml) + # LED will turn on (see also "default-state" property) - default-on # LED "double" flashes at a load average based rate - heartbeat @@ -158,6 +157,18 @@ properties: For flash LED controllers with configurable current this property is mandatory for the LEDs in the non-flash modes (e.g. torch or indicator). + max-brightness: + description: + Normally, the maximum brightness is determined by the hardware, and this + property is not required. This property is used to set a software limit. + It could happen that an LED is made so bright that it gets damaged or + causes damage due to restrictions in a specific system, such as mounting + conditions. + Note that this flag is mainly used for PWM-LEDs, where it is not possible + to map brightness to current. Drivers for other controllers should use + led-max-microamp. + $ref: /schemas/types.yaml#definitions/uint32 + panic-indicator: description: This property specifies that the LED should be used, if at all possible, @@ -180,6 +191,8 @@ properties: each of them having its own LED assigned (assuming they are not hardwired). In such cases this property should contain phandle(s) of related source device(s). + Another example is a GPIO line that will be monitored and mirror the + state of the line (with or without inversion flags) to the LED. In many cases LED can be related to more than one device (e.g. one USB LED vs. multiple USB ports). Each source should be represented by a node in the device tree and be referenced by a phandle and a set of phandle diff --git a/Documentation/devicetree/bindings/leds/kinetic,ktd202x.yaml b/Documentation/devicetree/bindings/leds/kinetic,ktd202x.yaml new file mode 100644 index 000000000000..832c030a5acf --- /dev/null +++ b/Documentation/devicetree/bindings/leds/kinetic,ktd202x.yaml @@ -0,0 +1,171 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/kinetic,ktd202x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Kinetic KTD2026/7 RGB/White LED Driver + +maintainers: + - André Apitzsch <git@apitzsch.eu> + +description: | + The KTD2026/7 is a RGB/White LED driver with I2C interface. + + The data sheet can be found at: + https://www.kinet-ic.com/uploads/KTD2026-7-04h.pdf + +properties: + compatible: + enum: + - kinetic,ktd2026 + - kinetic,ktd2027 + + reg: + maxItems: 1 + + vin-supply: + description: Regulator providing power to the "VIN" pin. + + vio-supply: + description: Regulator providing power for pull-up of the I/O lines. + Note that this regulator does not directly connect to KTD2026, but is + needed for the correct operation of the status ("ST") and I2C lines. + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + multi-led: + type: object + $ref: leds-class-multicolor.yaml# + unevaluatedProperties: false + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + patternProperties: + "^led@[0-3]$": + type: object + $ref: common.yaml# + unevaluatedProperties: false + + properties: + reg: + description: Index of the LED. + minimum: 0 + maximum: 3 + + required: + - reg + - color + + required: + - "#address-cells" + - "#size-cells" + +patternProperties: + "^led@[0-3]$": + type: object + $ref: common.yaml# + unevaluatedProperties: false + + properties: + reg: + description: Index of the LED. + minimum: 0 + maximum: 3 + + required: + - reg + +required: + - compatible + - reg + - "#address-cells" + - "#size-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/leds/common.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + led-controller@30 { + compatible = "kinetic,ktd2026"; + reg = <0x30>; + #address-cells = <1>; + #size-cells = <0>; + + vin-supply = <&pm8916_l17>; + vio-supply = <&pm8916_l6>; + + led@0 { + reg = <0>; + function = LED_FUNCTION_STATUS; + color = <LED_COLOR_ID_RED>; + }; + + led@1 { + reg = <1>; + function = LED_FUNCTION_STATUS; + color = <LED_COLOR_ID_GREEN>; + }; + + led@2 { + reg = <2>; + function = LED_FUNCTION_STATUS; + color = <LED_COLOR_ID_BLUE>; + }; + }; + }; + - | + #include <dt-bindings/leds/common.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + led-controller@30 { + compatible = "kinetic,ktd2026"; + reg = <0x30>; + #address-cells = <1>; + #size-cells = <0>; + + vin-supply = <&pm8916_l17>; + vio-supply = <&pm8916_l6>; + + multi-led { + color = <LED_COLOR_ID_RGB>; + function = LED_FUNCTION_STATUS; + + #address-cells = <1>; + #size-cells = <0>; + + led@0 { + reg = <0>; + color = <LED_COLOR_ID_RED>; + }; + + led@1 { + reg = <1>; + color = <LED_COLOR_ID_GREEN>; + }; + + led@2 { + reg = <2>; + color = <LED_COLOR_ID_BLUE>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/leds/leds-an30259a.txt b/Documentation/devicetree/bindings/leds/leds-an30259a.txt deleted file mode 100644 index cbd833906b2b..000000000000 --- a/Documentation/devicetree/bindings/leds/leds-an30259a.txt +++ /dev/null @@ -1,55 +0,0 @@ -* Panasonic AN30259A 3-channel LED driver - -The AN30259A is a LED controller capable of driving three LEDs independently. It supports -constant current output and sloping current output modes. The chip is connected over I2C. - -Required properties: - - compatible: Must be "panasonic,an30259a". - - reg: I2C slave address. - - #address-cells: Must be 1. - - #size-cells: Must be 0. - -Each LED is represented as a sub-node of the panasonic,an30259a node. - -Required sub-node properties: - - reg: Pin that the LED is connected to. Must be 1, 2, or 3. - -Optional sub-node properties: - - function : - see Documentation/devicetree/bindings/leds/common.txt - - color : - see Documentation/devicetree/bindings/leds/common.txt - - label : - see Documentation/devicetree/bindings/leds/common.txt (deprecated) - - linux,default-trigger : - see Documentation/devicetree/bindings/leds/common.txt - -Example: - -#include <dt-bindings/leds/common.h> - -led-controller@30 { - compatible = "panasonic,an30259a"; - reg = <0x30>; - #address-cells = <1>; - #size-cells = <0>; - - led@1 { - reg = <1>; - linux,default-trigger = "heartbeat"; - function = LED_FUNCTION_INDICATOR; - color = <LED_COLOR_ID_RED>; - }; - - led@2 { - reg = <2>; - function = LED_FUNCTION_INDICATOR; - color = <LED_COLOR_ID_GREEN>; - }; - - led@3 { - reg = <3>; - function = LED_FUNCTION_INDICATOR; - color = <LED_COLOR_ID_BLUE>; - }; -}; diff --git a/Documentation/devicetree/bindings/leds/leds-aw2013.yaml b/Documentation/devicetree/bindings/leds/leds-aw2013.yaml index 08f3e1cfc1b1..26238446f2bd 100644 --- a/Documentation/devicetree/bindings/leds/leds-aw2013.yaml +++ b/Documentation/devicetree/bindings/leds/leds-aw2013.yaml @@ -20,9 +20,20 @@ properties: reg: maxItems: 1 + interrupts: + maxItems: 1 + description: Open-drain, low active interrupt pin "INTN". + Used to report completion of operations (power up, LED breath effects). + vcc-supply: description: Regulator providing power to the "VCC" pin. + vio-supply: + description: Regulator providing power for pull-up of the I/O lines. + "VIO1" in the typical application circuit example of the datasheet. + Note that this regulator does not directly connect to AW2013, but is + needed for the correct operation of the interrupt and I2C lines. + "#address-cells": const: 1 @@ -52,6 +63,7 @@ additionalProperties: false examples: - | #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> #include <dt-bindings/leds/common.h> i2c { @@ -61,6 +73,7 @@ examples: led-controller@45 { compatible = "awinic,aw2013"; reg = <0x45>; + interrupts = <42 IRQ_TYPE_LEVEL_LOW>; #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/leds/leds-group-multicolor.yaml b/Documentation/devicetree/bindings/leds/leds-group-multicolor.yaml new file mode 100644 index 000000000000..8ed059a5a724 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-group-multicolor.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/leds-group-multicolor.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Multi-color LED built with monochromatic LEDs + +maintainers: + - Jean-Jacques Hiblot <jjhiblot@traphandler.com> + +description: | + This driver combines several monochromatic LEDs into one multi-color + LED using the multicolor LED class. + +properties: + compatible: + const: leds-group-multicolor + + leds: + description: + An aray of monochromatic leds + $ref: /schemas/types.yaml#/definitions/phandle-array + +required: + - leds + +allOf: + - $ref: leds-class-multicolor.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/leds/common.h> + + monochromatic-leds { + compatible = "gpio-leds"; + + led0: led-0 { + gpios = <&mcu_pio 0 GPIO_ACTIVE_LOW>; + color = <LED_COLOR_ID_RED>; + }; + + led1: led-1 { + gpios = <&mcu_pio 1 GPIO_ACTIVE_HIGH>; + color = <LED_COLOR_ID_GREEN>; + }; + + led2: led-2 { + gpios = <&mcu_pio 2 GPIO_ACTIVE_HIGH>; + color = <LED_COLOR_ID_BLUE>; + }; + }; + + multi-led { + compatible = "leds-group-multicolor"; + color = <LED_COLOR_ID_RGB>; + function = LED_FUNCTION_INDICATOR; + leds = <&led0>, <&led1>, <&led2>; + }; + +... diff --git a/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml b/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml index 058be1fedbc8..e9d4514d0166 100644 --- a/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml +++ b/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml @@ -106,7 +106,7 @@ patternProperties: max-cur: $ref: /schemas/types.yaml#/definitions/uint8 - description: Maximun current at each LED channel. + description: Maximum current at each LED channel. reg: maximum: 8 @@ -129,7 +129,7 @@ patternProperties: max-cur: $ref: /schemas/types.yaml#/definitions/uint8 - description: Maximun current at each LED channel. + description: Maximum current at each LED channel. reg: description: | diff --git a/Documentation/devicetree/bindings/leds/leds-qcom-lpg.yaml b/Documentation/devicetree/bindings/leds/leds-qcom-lpg.yaml index e6f1999cb22f..ea84ad426df1 100644 --- a/Documentation/devicetree/bindings/leds/leds-qcom-lpg.yaml +++ b/Documentation/devicetree/bindings/leds/leds-qcom-lpg.yaml @@ -56,7 +56,7 @@ properties: description: > A list of integer pairs, where each pair represent the dtest line the particular channel should be connected to and the flags denoting how the - value should be outputed, as defined in the datasheet. The number of + value should be outputted, as defined in the datasheet. The number of pairs should be the same as the number of channels. items: items: diff --git a/Documentation/devicetree/bindings/leds/nxp,pca953x.yaml b/Documentation/devicetree/bindings/leds/nxp,pca953x.yaml index edf6f55df685..9610bca57dd5 100644 --- a/Documentation/devicetree/bindings/leds/nxp,pca953x.yaml +++ b/Documentation/devicetree/bindings/leds/nxp,pca953x.yaml @@ -29,6 +29,10 @@ properties: gpio-controller: true + gpio-line-names: + minItems: 1 + maxItems: 16 + '#gpio-cells': const: 2 diff --git a/Documentation/devicetree/bindings/leds/nxp,pca995x.yaml b/Documentation/devicetree/bindings/leds/nxp,pca995x.yaml new file mode 100644 index 000000000000..654915c1f687 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/nxp,pca995x.yaml @@ -0,0 +1,81 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/nxp,pca995x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP PCA995x LED controllers + +maintainers: + - Isai Gaspar <isaiezequiel.gaspar@nxp.com> + - Marek Vasut <marex@denx.de> + +description: + The NXP PCA9952/PCA9955B are programmable LED controllers connected via I2C + that can drive 16 separate lines. Each of them can be individually switched + on and off, and brightness can be controlled via individual PWM. + + Datasheets are available at + https://www.nxp.com/docs/en/data-sheet/PCA9952_PCA9955.pdf + https://www.nxp.com/docs/en/data-sheet/PCA9955B.pdf + +properties: + compatible: + enum: + - nxp,pca9952 + - nxp,pca9955b + + reg: + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + +patternProperties: + "^led@[0-9a-f]+$": + type: object + $ref: common.yaml# + unevaluatedProperties: false + + properties: + reg: + minimum: 0 + maximum: 15 + + required: + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/leds/common.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + led-controller@1 { + compatible = "nxp,pca9955b"; + reg = <0x01>; + #address-cells = <1>; + #size-cells = <0>; + + led@0 { + reg = <0x0>; + color = <LED_COLOR_ID_RED>; + function = LED_FUNCTION_POWER; + }; + + led@2 { + reg = <0x2>; + color = <LED_COLOR_ID_WHITE>; + function = LED_FUNCTION_STATUS; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/leds/panasonic,an30259a.yaml b/Documentation/devicetree/bindings/leds/panasonic,an30259a.yaml new file mode 100644 index 000000000000..e918dceea082 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/panasonic,an30259a.yaml @@ -0,0 +1,84 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/panasonic,an30259a.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Panasonic AN30259A 3-channel LED controller + +maintainers: + - Iskren Chernev <me@iskren.info> + +description: + The AN30259A is a LED controller capable of driving three LEDs independently. + It supports constant current output and sloping current output modes. The chip + is connected over I2C. + +properties: + compatible: + const: panasonic,an30259a + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + +patternProperties: + "^led@[1-3]$": + $ref: common.yaml# + unevaluatedProperties: false + + properties: + reg: + enum: [ 1, 2, 3 ] + +required: + - compatible + - reg + - "#address-cells" + - "#size-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/leds/common.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + led-controller@30 { + compatible = "panasonic,an30259a"; + reg = <0x30>; + #address-cells = <1>; + #size-cells = <0>; + + led@1 { + reg = <1>; + linux,default-trigger = "heartbeat"; + function = LED_FUNCTION_INDICATOR; + color = <LED_COLOR_ID_RED>; + }; + + led@2 { + reg = <2>; + function = LED_FUNCTION_INDICATOR; + color = <LED_COLOR_ID_GREEN>; + }; + + led@3 { + reg = <3>; + function = LED_FUNCTION_INDICATOR; + color = <LED_COLOR_ID_BLUE>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/leds/register-bit-led.yaml b/Documentation/devicetree/bindings/leds/register-bit-led.yaml index ed26ec19ecbd..20930d327ae9 100644 --- a/Documentation/devicetree/bindings/leds/register-bit-led.yaml +++ b/Documentation/devicetree/bindings/leds/register-bit-led.yaml @@ -60,7 +60,7 @@ examples: - | syscon@10000000 { - compatible = "arm,realview-pb1176-syscon", "syscon"; + compatible = "arm,realview-pb1176-syscon", "syscon", "simple-mfd"; reg = <0x10000000 0x1000>; #address-cells = <1>; #size-cells = <1>; diff --git a/Documentation/devicetree/bindings/leds/rohm,bd2606mvv.yaml b/Documentation/devicetree/bindings/leds/rohm,bd2606mvv.yaml index 14700a2e5fea..44dd91aa239d 100644 --- a/Documentation/devicetree/bindings/leds/rohm,bd2606mvv.yaml +++ b/Documentation/devicetree/bindings/leds/rohm,bd2606mvv.yaml @@ -35,7 +35,7 @@ properties: description: GPIO pin to enable/disable the device. patternProperties: - "^led@[0-6]$": + "^led@[0-5]$": type: object $ref: common.yaml# unevaluatedProperties: false @@ -43,7 +43,7 @@ patternProperties: properties: reg: minimum: 0 - maximum: 6 + maximum: 5 required: - reg diff --git a/Documentation/devicetree/bindings/leds/rohm,bd71828-leds.yaml b/Documentation/devicetree/bindings/leds/rohm,bd71828-leds.yaml index 58f0d94c6d71..b7a3ef76cbf4 100644 --- a/Documentation/devicetree/bindings/leds/rohm,bd71828-leds.yaml +++ b/Documentation/devicetree/bindings/leds/rohm,bd71828-leds.yaml @@ -18,8 +18,6 @@ description: | The device has two LED outputs referred as GRNLED and AMBLED in data-sheet. -select: false - properties: compatible: const: rohm,bd71828-leds diff --git a/Documentation/devicetree/bindings/mailbox/brcm,iproc-flexrm-mbox.txt b/Documentation/devicetree/bindings/mailbox/brcm,iproc-flexrm-mbox.txt index 752ae6b00d26..c80065a1eb97 100644 --- a/Documentation/devicetree/bindings/mailbox/brcm,iproc-flexrm-mbox.txt +++ b/Documentation/devicetree/bindings/mailbox/brcm,iproc-flexrm-mbox.txt @@ -29,7 +29,7 @@ Required properties: where N is the value specified by 2nd cell above. If FlexRM does not get required number of completion messages in time specified by this cell then it will inject one MSI interrupt - to CPU provided atleast one completion message is available. + to CPU provided at least one completion message is available. Optional properties: -------------------- diff --git a/Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.yaml index d433e496ec6e..1a2001e58880 100644 --- a/Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.yaml +++ b/Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.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/mailbox/ti,omap-mailbox.yaml# @@ -159,7 +159,7 @@ properties: a corresponding sysc interconnect node. This property is only needed on some legacy OMAP SoCs which have not - yet been converted to the ti,sysc interconnect hierarachy, but is + yet been converted to the ti,sysc interconnect hierarchy, but is otherwise considered obsolete. patternProperties: diff --git a/Documentation/devicetree/bindings/media/amphion,vpu.yaml b/Documentation/devicetree/bindings/media/amphion,vpu.yaml index a9d80eaeeeb6..c0d83d755239 100644 --- a/Documentation/devicetree/bindings/media/amphion,vpu.yaml +++ b/Documentation/devicetree/bindings/media/amphion,vpu.yaml @@ -47,7 +47,7 @@ patternProperties: $ref: ../mailbox/fsl,mu.yaml# - "^vpu_core@[0-9a-f]+$": + "^vpu-core@[0-9a-f]+$": description: Each core correspond a decoder or encoder, need to configure them separately. NXP i.MX8QM SoC has one decoder and two encoder, i.MX8QXP SoC @@ -143,7 +143,7 @@ examples: power-domains = <&pd IMX_SC_R_VPU_MU_2>; }; - vpu_core0: vpu_core@2d080000 { + vpu_core0: vpu-core@2d080000 { compatible = "nxp,imx8q-vpu-decoder"; reg = <0x2d080000 0x10000>; power-domains = <&pd IMX_SC_R_VPU_DEC_0>; @@ -154,7 +154,7 @@ examples: memory-region = <&decoder_boot>, <&decoder_rpc>; }; - vpu_core1: vpu_core@2d090000 { + vpu_core1: vpu-core@2d090000 { compatible = "nxp,imx8q-vpu-encoder"; reg = <0x2d090000 0x10000>; power-domains = <&pd IMX_SC_R_VPU_ENC_0>; @@ -165,7 +165,7 @@ examples: memory-region = <&encoder1_boot>, <&encoder1_rpc>; }; - vpu_core2: vpu_core@2d0a0000 { + vpu_core2: vpu-core@2d0a0000 { reg = <0x2d0a0000 0x10000>; compatible = "nxp,imx8q-vpu-encoder"; power-domains = <&pd IMX_SC_R_VPU_ENC_1>; diff --git a/Documentation/devicetree/bindings/media/cdns,csi2rx.txt b/Documentation/devicetree/bindings/media/cdns,csi2rx.txt deleted file mode 100644 index 6b02a0657ad9..000000000000 --- a/Documentation/devicetree/bindings/media/cdns,csi2rx.txt +++ /dev/null @@ -1,100 +0,0 @@ -Cadence MIPI-CSI2 RX controller -=============================== - -The Cadence MIPI-CSI2 RX controller is a CSI-2 bridge supporting up to 4 CSI -lanes in input, and 4 different pixel streams in output. - -Required properties: - - compatible: must be set to "cdns,csi2rx" and an SoC-specific compatible - - reg: base address and size of the memory mapped region - - clocks: phandles to the clocks driving the controller - - clock-names: must contain: - * sys_clk: main clock - * p_clk: register bank clock - * pixel_if[0-3]_clk: pixel stream output clock, one for each stream - implemented in hardware, between 0 and 3 - -Optional properties: - - phys: phandle to the external D-PHY, phy-names must be provided - - phy-names: must contain "dphy", if the implementation uses an - external D-PHY - -Required subnodes: - - ports: A ports node with one port child node per device input and output - port, in accordance with the video interface bindings defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. The - port nodes are numbered as follows: - - Port Description - ----------------------------- - 0 CSI-2 input - 1 Stream 0 output - 2 Stream 1 output - 3 Stream 2 output - 4 Stream 3 output - - The stream output port nodes are optional if they are not - connected to anything at the hardware level or implemented - in the design.Since there is only one endpoint per port, - the endpoints are not numbered. - - -Example: - -csi2rx: csi-bridge@0d060000 { - compatible = "cdns,csi2rx"; - reg = <0x0d060000 0x1000>; - clocks = <&byteclock>, <&byteclock> - <&coreclock>, <&coreclock>, - <&coreclock>, <&coreclock>; - clock-names = "sys_clk", "p_clk", - "pixel_if0_clk", "pixel_if1_clk", - "pixel_if2_clk", "pixel_if3_clk"; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - - csi2rx_in_sensor: endpoint { - remote-endpoint = <&sensor_out_csi2rx>; - clock-lanes = <0>; - data-lanes = <1 2>; - }; - }; - - port@1 { - reg = <1>; - - csi2rx_out_grabber0: endpoint { - remote-endpoint = <&grabber0_in_csi2rx>; - }; - }; - - port@2 { - reg = <2>; - - csi2rx_out_grabber1: endpoint { - remote-endpoint = <&grabber1_in_csi2rx>; - }; - }; - - port@3 { - reg = <3>; - - csi2rx_out_grabber2: endpoint { - remote-endpoint = <&grabber2_in_csi2rx>; - }; - }; - - port@4 { - reg = <4>; - - csi2rx_out_grabber3: endpoint { - remote-endpoint = <&grabber3_in_csi2rx>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/media/cdns,csi2rx.yaml b/Documentation/devicetree/bindings/media/cdns,csi2rx.yaml new file mode 100644 index 000000000000..30a335b10762 --- /dev/null +++ b/Documentation/devicetree/bindings/media/cdns,csi2rx.yaml @@ -0,0 +1,201 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/cdns,csi2rx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cadence MIPI-CSI2 RX controller + +maintainers: + - Maxime Ripard <mripard@kernel.org> + +description: + The Cadence MIPI-CSI2 RX controller is a CSI-2 bridge supporting up to 4 CSI + lanes in input, and 4 different pixel streams in output. + +properties: + compatible: + items: + - enum: + - starfive,jh7110-csi2rx + - const: cdns,csi2rx + + reg: + maxItems: 1 + + clocks: + items: + - description: CSI2Rx system clock + - description: Gated Register bank clock for APB interface + - description: pixel Clock for Stream interface 0 + - description: pixel Clock for Stream interface 1 + - description: pixel Clock for Stream interface 2 + - description: pixel Clock for Stream interface 3 + + clock-names: + items: + - const: sys_clk + - const: p_clk + - const: pixel_if0_clk + - const: pixel_if1_clk + - const: pixel_if2_clk + - const: pixel_if3_clk + + resets: + items: + - description: CSI2Rx system reset + - description: Gated Register bank reset for APB interface + - description: pixel reset for Stream interface 0 + - description: pixel reset for Stream interface 1 + - description: pixel reset for Stream interface 2 + - description: pixel reset for Stream interface 3 + + reset-names: + items: + - const: sys + - const: reg_bank + - const: pixel_if0 + - const: pixel_if1 + - const: pixel_if2 + - const: pixel_if3 + + phys: + maxItems: 1 + description: MIPI D-PHY + + phy-names: + items: + - const: dphy + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port node, single endpoint describing the CSI-2 transmitter. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + bus-type: + const: 4 + + clock-lanes: + const: 0 + + data-lanes: + minItems: 1 + maxItems: 4 + items: + maximum: 4 + + required: + - data-lanes + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: + Stream 0 Output port node + + port@2: + $ref: /schemas/graph.yaml#/properties/port + description: + Stream 1 Output port node + + port@3: + $ref: /schemas/graph.yaml#/properties/port + description: + Stream 2 Output port node + + port@4: + $ref: /schemas/graph.yaml#/properties/port + description: + Stream 3 Output port node + + required: + - port@0 + +required: + - compatible + - reg + - clocks + - clock-names + - ports + +additionalProperties: false + +examples: + - | + csi@d060000 { + compatible = "starfive,jh7110-csi2rx", "cdns,csi2rx"; + reg = <0x0d060000 0x1000>; + clocks = <&byteclock 7>, <&byteclock 6>, + <&coreclock 8>, <&coreclock 9>, + <&coreclock 10>, <&coreclock 11>; + clock-names = "sys_clk", "p_clk", + "pixel_if0_clk", "pixel_if1_clk", + "pixel_if2_clk", "pixel_if3_clk"; + resets = <&bytereset 9>, <&bytereset 4>, + <&corereset 5>, <&corereset 6>, + <&corereset 7>, <&corereset 8>; + reset-names = "sys", "reg_bank", + "pixel_if0", "pixel_if1", + "pixel_if2", "pixel_if3"; + phys = <&csi_phy>; + phy-names = "dphy"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + csi2rx_in_sensor: endpoint { + remote-endpoint = <&sensor_out_csi2rx>; + clock-lanes = <0>; + data-lanes = <1 2>; + }; + }; + + port@1 { + reg = <1>; + + csi2rx_out_grabber0: endpoint { + remote-endpoint = <&grabber0_in_csi2rx>; + }; + }; + + port@2 { + reg = <2>; + + csi2rx_out_grabber1: endpoint { + remote-endpoint = <&grabber1_in_csi2rx>; + }; + }; + + port@3 { + reg = <3>; + + csi2rx_out_grabber2: endpoint { + remote-endpoint = <&grabber2_in_csi2rx>; + }; + }; + + port@4 { + reg = <4>; + + csi2rx_out_grabber3: endpoint { + remote-endpoint = <&grabber3_in_csi2rx>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/cec/nvidia,tegra114-cec.yaml b/Documentation/devicetree/bindings/media/cec/nvidia,tegra114-cec.yaml index 369c48fd9bf9..a6b73498bc21 100644 --- a/Documentation/devicetree/bindings/media/cec/nvidia,tegra114-cec.yaml +++ b/Documentation/devicetree/bindings/media/cec/nvidia,tegra114-cec.yaml @@ -53,6 +53,5 @@ examples: interrupts = <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>; clocks = <&tegra_car TEGRA124_CLK_CEC>; clock-names = "cec"; - status = "disabled"; hdmi-phandle = <&hdmi>; }; diff --git a/Documentation/devicetree/bindings/media/i2c/ov5695.txt b/Documentation/devicetree/bindings/media/i2c/ov5695.txt deleted file mode 100644 index 640a63717d96..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/ov5695.txt +++ /dev/null @@ -1,41 +0,0 @@ -* Omnivision OV5695 MIPI CSI-2 sensor - -Required Properties: -- compatible: shall be "ovti,ov5695" -- clocks: reference to the xvclk input clock -- clock-names: shall be "xvclk" -- avdd-supply: Analog voltage supply, 2.8 volts -- dovdd-supply: Digital I/O voltage supply, 1.8 volts -- dvdd-supply: Digital core voltage supply, 1.2 volts -- reset-gpios: Low active reset gpio - -The device node shall contain one 'port' child node with an -'endpoint' subnode for its digital output video port, -in accordance with the video interface bindings defined in -Documentation/devicetree/bindings/media/video-interfaces.txt. -The endpoint optional property 'data-lanes' shall be "<1 2>". - -Example: -&i2c7 { - ov5695: camera-sensor@36 { - compatible = "ovti,ov5695"; - reg = <0x36>; - pinctrl-names = "default"; - pinctrl-0 = <&clk_24m_cam>; - - clocks = <&cru SCLK_TESTCLKOUT1>; - clock-names = "xvclk"; - - avdd-supply = <&pp2800_cam>; - dovdd-supply = <&pp1800>; - dvdd-supply = <&pp1250_cam>; - reset-gpios = <&gpio2 5 GPIO_ACTIVE_LOW>; - - port { - wcam_out: endpoint { - remote-endpoint = <&mipi_in_wcam>; - data-lanes = <1 2>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/media/i2c/ov7251.txt b/Documentation/devicetree/bindings/media/i2c/ov7251.txt deleted file mode 100644 index 8281151f7493..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/ov7251.txt +++ /dev/null @@ -1,52 +0,0 @@ -* Omnivision 1/7.5-Inch B&W VGA CMOS Digital Image Sensor - -The Omnivision OV7251 is a 1/7.5-Inch CMOS active pixel digital image sensor -with an active array size of 640H x 480V. It is programmable through a serial -I2C interface. - -Required Properties: -- compatible: Value should be "ovti,ov7251". -- clocks: Reference to the xclk clock. -- clock-names: Should be "xclk". -- clock-frequency: Frequency of the xclk clock. -- enable-gpios: Chip enable GPIO. Polarity is GPIO_ACTIVE_HIGH. This corresponds - to the hardware pin XSHUTDOWN which is physically active low. -- vdddo-supply: Chip digital IO regulator. -- vdda-supply: Chip analog regulator. -- vddd-supply: Chip digital core regulator. - -The device node shall contain one 'port' child node with a single 'endpoint' -subnode for its digital output video port, in accordance with the video -interface bindings defined in -Documentation/devicetree/bindings/media/video-interfaces.txt. - -Example: - - &i2c1 { - ... - - ov7251: camera-sensor@60 { - compatible = "ovti,ov7251"; - reg = <0x60>; - - enable-gpios = <&gpio1 6 GPIO_ACTIVE_HIGH>; - pinctrl-names = "default"; - pinctrl-0 = <&camera_bw_default>; - - clocks = <&clks 200>; - clock-names = "xclk"; - clock-frequency = <24000000>; - - vdddo-supply = <&camera_dovdd_1v8>; - vdda-supply = <&camera_avdd_2v8>; - vddd-supply = <&camera_dvdd_1v2>; - - port { - ov7251_ep: endpoint { - clock-lanes = <1>; - data-lanes = <0>; - remote-endpoint = <&csi0_ep>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov5693.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5693.yaml index 359dc08440a8..6829a4aadd22 100644 --- a/Documentation/devicetree/bindings/media/i2c/ovti,ov5693.yaml +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5693.yaml @@ -5,26 +5,41 @@ $id: http://devicetree.org/schemas/media/i2c/ovti,ov5693.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Omnivision OV5693 CMOS Sensor +title: Omnivision OV5693/OV5695 CMOS Sensors maintainers: - Tommaso Merciai <tommaso.merciai@amarulasolutions.com> description: | - The Omnivision OV5693 is a high performance, 1/4-inch, 5 megapixel, CMOS - image sensor that delivers 2592x1944 at 30fps. It provides full-frame, + The Omnivision OV5693/OV5695 are high performance, 1/4-inch, 5 megapixel, CMOS + image sensors that deliver 2592x1944 at 30fps. It provides full-frame, sub-sampled, and windowed 10-bit MIPI images in various formats via the Serial Camera Control Bus (SCCB) interface. - OV5693 is controlled via I2C and two-wire Serial Camera Control Bus (SCCB). - The sensor output is available via CSI-2 serial data output (up to 2-lane). + OV5693/OV5695 are controlled via I2C and two-wire Serial Camera Control Bus + (SCCB). The sensor output is available via CSI-2 serial data output (up to + 2-lane). allOf: - $ref: /schemas/media/video-interface-devices.yaml# + - if: + properties: + compatible: + contains: + const: ovti,ov5693 + then: + properties: + port: + properties: + endpoint: + required: + - link-frequencies properties: compatible: - const: ovti,ov5693 + enum: + - ovti,ov5693 + - ovti,ov5695 reg: maxItems: 1 @@ -34,6 +49,9 @@ properties: System input clock (aka XVCLK). From 6 to 27 MHz. maxItems: 1 + clock-names: + const: xvclk + dovdd-supply: description: Digital I/O voltage supply, 1.8V. @@ -72,7 +90,6 @@ properties: required: - data-lanes - - link-frequencies required: - compatible diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov7251.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov7251.yaml new file mode 100644 index 000000000000..2e5187acbbb8 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov7251.yaml @@ -0,0 +1,109 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/ovti,ov7251.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: OmniVision OV7251 Image Sensor + +description: + The Omnivision OV7251 is a 1/7.5-Inch CMOS active pixel digital image sensor + with an active array size of 640H x 480V. It is programmable through a serial + I2C interface. + +maintainers: + - Todor Tomov <todor.too@gmail.com> + +properties: + compatible: + const: ovti,ov7251 + + reg: + maxItems: 1 + + clocks: + description: XCLK Input Clock + + clock-names: + const: xclk + + clock-frequency: + description: Frequency of the xclk clock in Hz. + + vdda-supply: + description: Analog voltage supply, 2.8 volts + + vddd-supply: + description: Digital core voltage supply, 1.2 volts + + vdddo-supply: + description: Digital I/O voltage supply, 1.8 volts + + enable-gpios: + maxItems: 1 + description: + Reference to the GPIO connected to the XSHUTDOWN pin, if any. Polarity + is GPIO_ACTIVE_HIGH. + + port: + description: Digital Output Port + $ref: /schemas/graph.yaml#/$defs/port-base + additionalProperties: false + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + maximum: 1 + + data-lanes: + maxItems: 1 + + link-frequencies: true + + required: + - data-lanes + - link-frequencies + +required: + - compatible + - reg + - clocks + - vdddo-supply + - vdda-supply + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + camera@3c { + compatible = "ovti,ov7251"; + reg = <0x3c>; + clocks = <&clks 1>; + clock-frequency = <24000000>; + vdddo-supply = <&ov7251_vdddo_1v8>; + vdda-supply = <&ov7251_vdda_2v8>; + vddd-supply = <&ov7251_vddd_1v5>; + enable-gpios = <&gpio1 19 GPIO_ACTIVE_HIGH>; + + port { + ov7251_ep: endpoint { + remote-endpoint = <&csi0_ep>; + clock-lanes = <1>; + data-lanes = <0>; + link-frequencies = /bits/ 64 <240000000 319200000>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx415.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx415.yaml index ffccf5f3c9e3..642f9b15d359 100644 --- a/Documentation/devicetree/bindings/media/i2c/sony,imx415.yaml +++ b/Documentation/devicetree/bindings/media/i2c/sony,imx415.yaml @@ -54,6 +54,7 @@ properties: port: $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false properties: endpoint: diff --git a/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.yaml b/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.yaml index 19a39d753aad..b68141264c0e 100644 --- a/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.yaml +++ b/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.yaml @@ -143,7 +143,6 @@ examples: mipid02: csi2rx@14 { compatible = "st,st-mipid02"; reg = <0x14>; - status = "okay"; clocks = <&clk_ext_camera_12>; clock-names = "xclk"; VDDE-supply = <&vdd>; diff --git a/Documentation/devicetree/bindings/media/i2c/ti,ds90ub913.yaml b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub913.yaml new file mode 100644 index 000000000000..f6612bb0f667 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub913.yaml @@ -0,0 +1,133 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/ti,ds90ub913.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments DS90UB913 FPD-Link III Serializer + +maintainers: + - Tomi Valkeinen <tomi.valkeinen@ideasonboard.com> + +description: + The TI DS90UB913 is an FPD-Link III video serializer for parallel video. + +properties: + compatible: + enum: + - ti,ds90ub913a-q1 + + '#gpio-cells': + const: 2 + description: + First cell is the GPO pin number, second cell is the flags. The GPO pin + number must be in range of [0, 3]. Note that GPOs 2 and 3 are not + available in external oscillator mode. + + gpio-controller: true + + clocks: + maxItems: 1 + description: + Reference clock connected to the CLKIN pin. + + clock-names: + items: + - const: clkin + + '#clock-cells': + const: 0 + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: Parallel input port + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + required: + - pclk-sample + + port@1: + $ref: /schemas/graph.yaml#/properties/port + unevaluatedProperties: false + description: FPD-Link III output port + + required: + - port@0 + - port@1 + + i2c: + $ref: /schemas/i2c/i2c-controller.yaml# + unevaluatedProperties: false + +required: + - compatible + - '#gpio-cells' + - gpio-controller + - '#clock-cells' + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + serializer { + compatible = "ti,ds90ub913a-q1"; + + gpio-controller; + #gpio-cells = <2>; + + clocks = <&clk_cam_48M>; + clock-names = "clkin"; + + #clock-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + ub913_in: endpoint { + remote-endpoint = <&sensor_out>; + pclk-sample = <1>; + }; + }; + + port@1 { + reg = <1>; + endpoint { + remote-endpoint = <&deser_fpd_in>; + }; + }; + }; + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + sensor@48 { + compatible = "aptina,mt9v111"; + reg = <0x48>; + + clocks = <&fixed_clock>; + + port { + sensor_out: endpoint { + remote-endpoint = <&ub913_in>; + }; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/i2c/ti,ds90ub953.yaml b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub953.yaml new file mode 100644 index 000000000000..2030366994d1 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub953.yaml @@ -0,0 +1,134 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/ti,ds90ub953.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments DS90UB953 FPD-Link III Serializer + +maintainers: + - Tomi Valkeinen <tomi.valkeinen@ideasonboard.com> + +description: + The TI DS90UB953 is an FPD-Link III video serializer for MIPI CSI-2. + +properties: + compatible: + enum: + - ti,ds90ub953-q1 + - ti,ds90ub971-q1 + + '#gpio-cells': + const: 2 + description: + First cell is the GPIO pin number, second cell is the flags. The GPIO pin + number must be in range of [0, 3]. + + gpio-controller: true + + clocks: + maxItems: 1 + description: + Reference clock connected to the CLKIN pin. + + clock-names: + items: + - const: clkin + + '#clock-cells': + const: 0 + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: CSI-2 input port + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + required: + - data-lanes + + port@1: + $ref: /schemas/graph.yaml#/properties/port + unevaluatedProperties: false + description: FPD-Link III output port + + required: + - port@0 + - port@1 + + i2c: + $ref: /schemas/i2c/i2c-controller.yaml# + unevaluatedProperties: false + +required: + - compatible + - '#gpio-cells' + - gpio-controller + - '#clock-cells' + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + serializer { + compatible = "ti,ds90ub953-q1"; + + gpio-controller; + #gpio-cells = <2>; + + #clock-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + ub953_in: endpoint { + clock-lanes = <0>; + data-lanes = <1 2 3 4>; + remote-endpoint = <&sensor_out>; + }; + }; + + port@1 { + reg = <1>; + endpoint { + remote-endpoint = <&deser_fpd_in>; + }; + }; + }; + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + sensor@1a { + compatible = "sony,imx274"; + reg = <0x1a>; + + reset-gpios = <&serializer 0 GPIO_ACTIVE_LOW>; + + clocks = <&serializer>; + clock-names = "inck"; + + port { + sensor_out: endpoint { + remote-endpoint = <&ub953_in>; + }; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml new file mode 100644 index 000000000000..0b71e6f911a8 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml @@ -0,0 +1,428 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/ti,ds90ub960.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments DS90UB9XX Family FPD-Link Deserializer Hubs + +maintainers: + - Tomi Valkeinen <tomi.valkeinen@ideasonboard.com> + +description: + The TI DS90UB9XX devices are FPD-Link video deserializers with I2C and GPIO + forwarding. + +allOf: + - $ref: /schemas/i2c/i2c-atr.yaml# + +properties: + compatible: + enum: + - ti,ds90ub960-q1 + - ti,ds90ub9702-q1 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + description: + Reference clock connected to the REFCLK pin. + + clock-names: + items: + - const: refclk + + powerdown-gpios: + maxItems: 1 + description: + Specifier for the GPIO connected to the PDB pin. + + i2c-alias-pool: + minItems: 1 + maxItems: 32 + + links: + type: object + additionalProperties: false + + properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + ti,manual-strobe: + type: boolean + description: + Enable manual strobe position and EQ level + + patternProperties: + '^link@[0-3]$': + type: object + additionalProperties: false + properties: + reg: + description: The link number + maxItems: 1 + + i2c-alias: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + The I2C address used for the serializer. Transactions to this + address on the I2C bus where the deserializer resides are + forwarded to the serializer. + + ti,rx-mode: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # RAW10 + - 1 # RAW12 HF + - 2 # RAW12 LF + - 3 # CSI2 SYNC + - 4 # CSI2 NON-SYNC + description: + FPD-Link Input Mode. This should reflect the hardware and the + default mode of the connected device. + + ti,cdr-mode: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # FPD-Link III + - 1 # FPD-Link IV + description: + FPD-Link CDR Mode. This should reflect the hardware and the + default mode of the connected device. + + ti,strobe-pos: + $ref: /schemas/types.yaml#/definitions/int32 + minimum: -13 + maximum: 13 + description: Manual strobe position + + ti,eq-level: + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 14 + description: Manual EQ level + + serializer: + type: object + description: FPD-Link Serializer node + + required: + - reg + - i2c-alias + - ti,rx-mode + - serializer + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: FPD-Link input 0 + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + description: + Endpoint for FPD-Link port. If the RX mode for this port is RAW, + hsync-active and vsync-active must be defined. + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: FPD-Link input 1 + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + description: + Endpoint for FPD-Link port. If the RX mode for this port is RAW, + hsync-active and vsync-active must be defined. + + port@2: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: FPD-Link input 2 + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + description: + Endpoint for FPD-Link port. If the RX mode for this port is RAW, + hsync-active and vsync-active must be defined. + + port@3: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: FPD-Link input 3 + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + description: + Endpoint for FPD-Link port. If the RX mode for this port is RAW, + hsync-active and vsync-active must be defined. + + port@4: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: CSI-2 Output 0 + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: + minItems: 1 + maxItems: 4 + link-frequencies: + maxItems: 1 + + required: + - data-lanes + - link-frequencies + + port@5: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: CSI-2 Output 1 + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: + minItems: 1 + maxItems: 4 + link-frequencies: + maxItems: 1 + + required: + - data-lanes + - link-frequencies + + required: + - port@0 + - port@1 + - port@2 + - port@3 + - port@4 + - port@5 + +required: + - compatible + - reg + - clocks + - clock-names + - ports + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + clock-frequency = <400000>; + #address-cells = <1>; + #size-cells = <0>; + + deser@3d { + compatible = "ti,ds90ub960-q1"; + reg = <0x3d>; + + clock-names = "refclk"; + clocks = <&fixed_clock>; + + powerdown-gpios = <&pca9555 7 GPIO_ACTIVE_LOW>; + + i2c-alias-pool = <0x4a 0x4b 0x4c 0x4d 0x4e 0x4f>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + /* Port 0, Camera 0 */ + port@0 { + reg = <0>; + + ub960_fpd3_1_in: endpoint { + remote-endpoint = <&ub953_1_out>; + }; + }; + + /* Port 1, Camera 1 */ + port@1 { + reg = <1>; + + ub960_fpd3_2_in: endpoint { + remote-endpoint = <&ub913_2_out>; + hsync-active = <0>; + vsync-active = <1>; + }; + }; + + /* Port 2, unconnected */ + port@2 { + reg = <2>; + }; + + /* Port 3, unconnected */ + port@3 { + reg = <3>; + }; + + /* Port 4, CSI-2 TX */ + port@4 { + reg = <4>; + ds90ub960_0_csi_out: endpoint { + data-lanes = <1 2 3 4>; + link-frequencies = /bits/ 64 <800000000>; + remote-endpoint = <&csi2_phy0>; + }; + }; + + /* Port 5, unconnected */ + port@5 { + reg = <5>; + }; + }; + + links { + #address-cells = <1>; + #size-cells = <0>; + + /* Link 0 has DS90UB953 serializer and IMX274 sensor */ + + link@0 { + reg = <0>; + i2c-alias = <0x44>; + + ti,rx-mode = <3>; + + serializer1: serializer { + compatible = "ti,ds90ub953-q1"; + + gpio-controller; + #gpio-cells = <2>; + + #clock-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + ub953_1_in: endpoint { + data-lanes = <1 2 3 4>; + remote-endpoint = <&sensor_1_out>; + }; + }; + + port@1 { + reg = <1>; + + ub953_1_out: endpoint { + remote-endpoint = <&ub960_fpd3_1_in>; + }; + }; + }; + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + sensor@1a { + compatible = "sony,imx274"; + reg = <0x1a>; + + reset-gpios = <&serializer1 0 GPIO_ACTIVE_LOW>; + + port { + sensor_1_out: endpoint { + remote-endpoint = <&ub953_1_in>; + }; + }; + }; + }; + }; + }; /* End of link@0 */ + + /* Link 1 has DS90UB913 serializer and MT9V111 sensor */ + + link@1 { + reg = <1>; + i2c-alias = <0x45>; + + ti,rx-mode = <0>; + + serializer2: serializer { + compatible = "ti,ds90ub913a-q1"; + + gpio-controller; + #gpio-cells = <2>; + + clocks = <&clk_cam_48M>; + clock-names = "clkin"; + + #clock-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + ub913_2_in: endpoint { + remote-endpoint = <&sensor_2_out>; + pclk-sample = <1>; + }; + }; + + port@1 { + reg = <1>; + + ub913_2_out: endpoint { + remote-endpoint = <&ub960_fpd3_2_in>; + }; + }; + }; + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + sensor@48 { + compatible = "aptina,mt9v111"; + reg = <0x48>; + + clocks = <&serializer2>; + + port { + sensor_2_out: endpoint { + remote-endpoint = <&ub913_2_in>; + }; + }; + }; + }; + }; + }; /* End of link@1 */ + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/i2c/toshiba,tc358746.yaml b/Documentation/devicetree/bindings/media/i2c/toshiba,tc358746.yaml index b8ba85a2416c..1c476b635b69 100644 --- a/Documentation/devicetree/bindings/media/i2c/toshiba,tc358746.yaml +++ b/Documentation/devicetree/bindings/media/i2c/toshiba,tc358746.yaml @@ -12,7 +12,7 @@ maintainers: description: |- The Toshiba TC358746 converts a parallel video stream into a MIPI CSI-2 stream. The direction can be either parallel-in -> csi-out or csi-in -> - parallel-out The chip is programmable trough I2C and SPI but the SPI + parallel-out The chip is programmable through I2C and SPI but the SPI interface is only supported in parallel-in -> csi-out mode. Note that the current device tree bindings only support the @@ -69,6 +69,7 @@ properties: properties: port@0: $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: Input port properties: @@ -89,6 +90,7 @@ properties: port@1: $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: Output port properties: diff --git a/Documentation/devicetree/bindings/media/i2c/tvp5150.txt b/Documentation/devicetree/bindings/media/i2c/tvp5150.txt index 719b2995dc17..94b908ace53c 100644 --- a/Documentation/devicetree/bindings/media/i2c/tvp5150.txt +++ b/Documentation/devicetree/bindings/media/i2c/tvp5150.txt @@ -53,7 +53,7 @@ Optional Connector Properties: ============================== - sdtv-standards: Set the possible signals to which the hardware tries to lock - instead of using the autodetection mechnism. Please look at + instead of using the autodetection mechanism. Please look at [1] for more information. [1] Documentation/devicetree/bindings/display/connector/analog-tv-connector.yaml. diff --git a/Documentation/devicetree/bindings/media/mediatek,vcodec-decoder.yaml b/Documentation/devicetree/bindings/media/mediatek,vcodec-decoder.yaml index fad59b486d5d..b401c67e3ba0 100644 --- a/Documentation/devicetree/bindings/media/mediatek,vcodec-decoder.yaml +++ b/Documentation/devicetree/bindings/media/mediatek,vcodec-decoder.yaml @@ -21,24 +21,33 @@ properties: - mediatek,mt8183-vcodec-dec reg: - maxItems: 12 + minItems: 11 + maxItems: 11 + + reg-names: + items: + - const: misc + - const: ld + - const: top + - const: cm + - const: ad + - const: av + - const: pp + - const: hwd + - const: hwq + - const: hwb + - const: hwg interrupts: maxItems: 1 clocks: + minItems: 1 maxItems: 8 clock-names: - items: - - const: vcodecpll - - const: univpll_d2 - - const: clk_cci400_sel - - const: vdec_sel - - const: vdecpll - - const: vencpll - - const: venc_lt_sel - - const: vdec_bus_clk_src + minItems: 1 + maxItems: 8 assigned-clocks: true @@ -66,6 +75,10 @@ properties: description: Describes point to scp. + mediatek,vdecsys: + $ref: /schemas/types.yaml#/definitions/phandle + description: Phandle to the vdecsys syscon node. + required: - compatible - reg @@ -73,8 +86,7 @@ required: - clocks - clock-names - iommus - - assigned-clocks - - assigned-clock-parents + - mediatek,vdecsys allOf: - if: @@ -88,6 +100,15 @@ allOf: required: - mediatek,scp + properties: + clocks: + minItems: 1 + maxItems: 1 + + clock-names: + items: + - const: vdec + - if: properties: compatible: @@ -99,6 +120,22 @@ allOf: required: - mediatek,vpu + properties: + clocks: + minItems: 8 + maxItems: 8 + + clock-names: + items: + - const: vcodecpll + - const: univpll_d2 + - const: clk_cci400_sel + - const: vdec_sel + - const: vdecpll + - const: vencpll + - const: venc_lt_sel + - const: vdec_bus_clk_src + additionalProperties: false examples: @@ -109,10 +146,9 @@ examples: #include <dt-bindings/interrupt-controller/irq.h> #include <dt-bindings/power/mt8173-power.h> - vcodec_dec: vcodec@16000000 { + vcodec_dec: vcodec@16020000 { compatible = "mediatek,mt8173-vcodec-dec"; - reg = <0x16000000 0x100>, /*VDEC_SYS*/ - <0x16020000 0x1000>, /*VDEC_MISC*/ + reg = <0x16020000 0x1000>, /*VDEC_MISC*/ <0x16021000 0x800>, /*VDEC_LD*/ <0x16021800 0x800>, /*VDEC_TOP*/ <0x16022000 0x1000>, /*VDEC_CM*/ @@ -133,6 +169,7 @@ examples: <&iommu M4U_PORT_HW_VDEC_VLD_EXT>, <&iommu M4U_PORT_HW_VDEC_VLD2_EXT>; mediatek,vpu = <&vpu>; + mediatek,vdecsys = <&vdecsys>; power-domains = <&scpsys MT8173_POWER_DOMAIN_VDEC>; clocks = <&apmixedsys CLK_APMIXED_VCODECPLL>, <&topckgen CLK_TOP_UNIVPLL_D2>, diff --git a/Documentation/devicetree/bindings/media/mediatek,vcodec-subdev-decoder.yaml b/Documentation/devicetree/bindings/media/mediatek,vcodec-subdev-decoder.yaml index dca9b0c5e106..a500a585c692 100644 --- a/Documentation/devicetree/bindings/media/mediatek,vcodec-subdev-decoder.yaml +++ b/Documentation/devicetree/bindings/media/mediatek,vcodec-subdev-decoder.yaml @@ -36,7 +36,7 @@ description: | controls the information of each hardware independent which include clk/power/irq. There are two workqueues in parent device: lat workqueue and core workqueue. They are used - to lat and core hardware deocder. Lat workqueue need to get input bitstream and lat buffer, + to lat and core hardware decoder. Lat workqueue need to get input bitstream and lat buffer, then enable lat to decode, writing the result to lat buffer, dislabe hardware when lat decode done. Core workqueue need to get lat buffer and output buffer, then enable core to decode, writing the result to output buffer, disable hardware when core decode done. These two diff --git a/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml b/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml index 358019e85d90..326284e151f6 100644 --- a/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml +++ b/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml @@ -59,7 +59,6 @@ allOf: compatible: contains: enum: - - fsl,imx8mq-csi - fsl,imx8mm-csi then: required: diff --git a/Documentation/devicetree/bindings/media/nxp,imx8-isi.yaml b/Documentation/devicetree/bindings/media/nxp,imx8-isi.yaml index 6038b9b5ab36..e4665469a86c 100644 --- a/Documentation/devicetree/bindings/media/nxp,imx8-isi.yaml +++ b/Documentation/devicetree/bindings/media/nxp,imx8-isi.yaml @@ -21,6 +21,7 @@ properties: enum: - fsl,imx8mn-isi - fsl,imx8mp-isi + - fsl,imx93-isi reg: maxItems: 1 @@ -72,7 +73,9 @@ allOf: properties: compatible: contains: - const: fsl,imx8mn-isi + enum: + - fsl,imx8mn-isi + - fsl,imx93-isi then: properties: interrupts: diff --git a/Documentation/devicetree/bindings/media/qcom,msm8916-venus.yaml b/Documentation/devicetree/bindings/media/qcom,msm8916-venus.yaml index 2350bf4b370e..9410f13ca97c 100644 --- a/Documentation/devicetree/bindings/media/qcom,msm8916-venus.yaml +++ b/Documentation/devicetree/bindings/media/qcom,msm8916-venus.yaml @@ -40,7 +40,7 @@ properties: properties: compatible: - const: "venus-decoder" + const: venus-decoder required: - compatible @@ -52,7 +52,7 @@ properties: properties: compatible: - const: "venus-encoder" + const: venus-encoder required: - compatible diff --git a/Documentation/devicetree/bindings/media/qcom,sm8250-venus.yaml b/Documentation/devicetree/bindings/media/qcom,sm8250-venus.yaml index 7915dcd2d99f..f66033ae8b59 100644 --- a/Documentation/devicetree/bindings/media/qcom,sm8250-venus.yaml +++ b/Documentation/devicetree/bindings/media/qcom,sm8250-venus.yaml @@ -106,7 +106,7 @@ examples: #include <dt-bindings/clock/qcom,videocc-sm8250.h> #include <dt-bindings/interconnect/qcom,sm8250.h> #include <dt-bindings/clock/qcom,gcc-sm8250.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> venus: video-codec@aa00000 { compatible = "qcom,sm8250-venus"; @@ -114,7 +114,7 @@ examples: interrupts = <GIC_SPI 174 IRQ_TYPE_LEVEL_HIGH>; power-domains = <&videocc MVS0C_GDSC>, <&videocc MVS0_GDSC>, - <&rpmhpd SM8250_MX>; + <&rpmhpd RPMHPD_MX>; power-domain-names = "venus", "vcodec0", "mx"; clocks = <&gcc GCC_VIDEO_AXI0_CLK>, diff --git a/Documentation/devicetree/bindings/media/renesas,vin.yaml b/Documentation/devicetree/bindings/media/renesas,vin.yaml index 324703bfb1bd..5539d0f8e74d 100644 --- a/Documentation/devicetree/bindings/media/renesas,vin.yaml +++ b/Documentation/devicetree/bindings/media/renesas,vin.yaml @@ -95,7 +95,7 @@ properties: synchronization is selected. default: 1 - field-active-even: true + field-even-active: true bus-width: true @@ -144,7 +144,7 @@ properties: synchronization is selected. default: 1 - field-active-even: true + field-even-active: true bus-width: true diff --git a/Documentation/devicetree/bindings/media/rockchip-isp1.yaml b/Documentation/devicetree/bindings/media/rockchip-isp1.yaml index 0bad7e640148..e466dff8286d 100644 --- a/Documentation/devicetree/bindings/media/rockchip-isp1.yaml +++ b/Documentation/devicetree/bindings/media/rockchip-isp1.yaml @@ -199,6 +199,7 @@ examples: wcam: camera@36 { compatible = "ovti,ov5695"; reg = <0x36>; + clocks = <&cru SCLK_TESTCLKOUT1>; port { wcam_out: endpoint { diff --git a/Documentation/devicetree/bindings/media/samsung,fimc.yaml b/Documentation/devicetree/bindings/media/samsung,fimc.yaml index 79ff6d83a9fd..b3486c38a05b 100644 --- a/Documentation/devicetree/bindings/media/samsung,fimc.yaml +++ b/Documentation/devicetree/bindings/media/samsung,fimc.yaml @@ -57,6 +57,7 @@ properties: patternProperties: "^port@[01]$": $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: Camera A and camera B inputs. diff --git a/Documentation/devicetree/bindings/memory-controllers/ingenic,nemc.yaml b/Documentation/devicetree/bindings/memory-controllers/ingenic,nemc.yaml index a02724221ff3..ee74a362f4ca 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ingenic,nemc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/ingenic,nemc.yaml @@ -39,6 +39,8 @@ properties: patternProperties: ".*@[0-9]+$": type: object + $ref: mc-peripheral-props.yaml# + additionalProperties: true required: - compatible diff --git a/Documentation/devicetree/bindings/memory-controllers/mc-peripheral-props.yaml b/Documentation/devicetree/bindings/memory-controllers/mc-peripheral-props.yaml index 5acfcad12bb7..8d9dae15ade0 100644 --- a/Documentation/devicetree/bindings/memory-controllers/mc-peripheral-props.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/mc-peripheral-props.yaml @@ -34,6 +34,8 @@ required: # The controller specific properties go here. allOf: - $ref: st,stm32-fmc2-ebi-props.yaml# + - $ref: ingenic,nemc-peripherals.yaml# - $ref: intel,ixp4xx-expansion-peripheral-props.yaml# + - $ref: ti,gpmc-child.yaml# additionalProperties: true diff --git a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml index aee7f6cf1300..2381660b324c 100644 --- a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml @@ -67,7 +67,7 @@ properties: minimum: 0 maximum: 31 description: the hardware id of this larb. It's only required when this - hardward id is not consecutive from its M4U point of view. + hardware id is not consecutive from its M4U point of view. required: - compatible diff --git a/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml index 56e62cd0b36a..25f3bb9890ae 100644 --- a/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml @@ -80,6 +80,8 @@ properties: patternProperties: "flash@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: contains: diff --git a/Documentation/devicetree/bindings/memory-controllers/rockchip,rk3399-dmc.yaml b/Documentation/devicetree/bindings/memory-controllers/rockchip,rk3399-dmc.yaml index fb4920397d08..1f58ee99be28 100644 --- a/Documentation/devicetree/bindings/memory-controllers/rockchip,rk3399-dmc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/rockchip,rk3399-dmc.yaml @@ -18,7 +18,7 @@ properties: $ref: /schemas/types.yaml#/definitions/phandle description: Node to get DDR loading. Refer to - Documentation/devicetree/bindings/devfreq/event/rockchip-dfi.txt. + Documentation/devicetree/bindings/devfreq/event/rockchip,dfi.yaml. clocks: maxItems: 1 @@ -152,7 +152,7 @@ properties: $ref: /schemas/types.yaml#/definitions/uint32 description: When the DRAM type is DDR3, this parameter defines the phy side CA line - (incluing command line, address line and clock line) drive strength. + (including command line, address line and clock line) drive strength. default: 40 rockchip,phy_ddr3_dq_drv: @@ -305,7 +305,7 @@ properties: description: Defines the self-refresh power down idle period in which memories are placed into self-refresh power down mode if bus is idle for - srpd_lite_idle nanoseonds. This parameter is for LPDDR4 only. + srpd_lite_idle nanoseconds. This parameter is for LPDDR4 only. rockchip,standby-idle-ns: description: diff --git a/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml b/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml index b049837ee669..c7a8a041da50 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml @@ -130,7 +130,7 @@ patternProperties: bus. The device can be a NAND chip, SRAM device, NOR device or an ASIC. $ref: ti,gpmc-child.yaml - + additionalProperties: true required: - compatible diff --git a/Documentation/devicetree/bindings/memory-controllers/xlnx,versal-ddrmc-edac.yaml b/Documentation/devicetree/bindings/memory-controllers/xlnx,versal-ddrmc-edac.yaml new file mode 100644 index 000000000000..12f8e9f350bc --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/xlnx,versal-ddrmc-edac.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/xlnx,versal-ddrmc-edac.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx Versal DDRMC (Integrated DDR Memory Controller) + +maintainers: + - Shubhrajyoti Datta <shubhrajyoti.datta@amd.com> + - Sai Krishna Potthuri <sai.krishna.potthuri@amd.com> + +description: + The integrated DDR Memory Controllers (DDRMCs) support both DDR4 and LPDDR4/ + 4X memory interfaces. Versal DDR memory controller has an optional ECC support + which correct single bit ECC errors and detect double bit ECC errors. + +properties: + compatible: + const: xlnx,versal-ddrmc + + reg: + items: + - description: DDR Memory Controller registers + - description: NOC registers corresponding to DDR Memory Controller + + reg-names: + items: + - const: base + - const: noc + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - reg-names + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + bus { + #address-cells = <2>; + #size-cells = <2>; + memory-controller@f6150000 { + compatible = "xlnx,versal-ddrmc"; + reg = <0x0 0xf6150000 0x0 0x2000>, <0x0 0xf6070000 0x0 0x20000>; + reg-names = "base", "noc"; + interrupt-parent = <&gic>; + interrupts = <GIC_SPI 147 IRQ_TYPE_LEVEL_HIGH>; + }; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/xlnx,zynq-ddrc-a05.yaml b/Documentation/devicetree/bindings/memory-controllers/xlnx,zynq-ddrc-a05.yaml index 75143db51411..b74ad9a3305c 100644 --- a/Documentation/devicetree/bindings/memory-controllers/xlnx,zynq-ddrc-a05.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/xlnx,zynq-ddrc-a05.yaml @@ -12,7 +12,7 @@ maintainers: description: The Zynq DDR ECC controller has an optional ECC support in half-bus width - (16-bit) configuration. It is cappable of correcting single bit ECC errors + (16-bit) configuration. It is capable of correcting single bit ECC errors and detecting double bit ECC errors. properties: diff --git a/Documentation/devicetree/bindings/mfd/allwinner,sun6i-a31-prcm.yaml b/Documentation/devicetree/bindings/mfd/allwinner,sun6i-a31-prcm.yaml index cf94176fe1eb..8789e3639ff7 100644 --- a/Documentation/devicetree/bindings/mfd/allwinner,sun6i-a31-prcm.yaml +++ b/Documentation/devicetree/bindings/mfd/allwinner,sun6i-a31-prcm.yaml @@ -34,6 +34,9 @@ patternProperties: - allwinner,sun6i-a31-clock-reset - fixed-factor-clock + required: + - compatible + allOf: - if: properties: @@ -55,25 +58,17 @@ patternProperties: "#clock-cells": const: 0 - # Already checked in the main schema - compatible: true - clocks: maxItems: 2 clock-output-names: maxItems: 1 - phandle: true - required: - "#clock-cells" - - compatible - clocks - clock-output-names - additionalProperties: false - - if: properties: compatible: @@ -85,25 +80,17 @@ patternProperties: "#clock-cells": const: 0 - # Already checked in the main schema - compatible: true - clocks: maxItems: 1 clock-output-names: maxItems: 1 - phandle: true - required: - "#clock-cells" - - compatible - clocks - clock-output-names - additionalProperties: false - - if: properties: compatible: @@ -119,9 +106,6 @@ patternProperties: offset of the bit controlling this particular gate in the register. - # Already checked in the main schema - compatible: true - clocks: maxItems: 1 @@ -129,16 +113,11 @@ patternProperties: minItems: 1 maxItems: 32 - phandle: true - required: - "#clock-cells" - - compatible - clocks - clock-output-names - additionalProperties: false - - if: properties: compatible: @@ -150,9 +129,6 @@ patternProperties: "#clock-cells": const: 0 - # Already checked in the main schema - compatible: true - clocks: maxItems: 4 description: > @@ -162,16 +138,11 @@ patternProperties: clock-output-names: maxItems: 1 - phandle: true - required: - "#clock-cells" - - compatible - clocks - clock-output-names - additionalProperties: false - - if: properties: compatible: @@ -183,16 +154,8 @@ patternProperties: "#reset-cells": const: 1 - # Already checked in the main schema - compatible: true - - phandle: true - required: - "#reset-cells" - - compatible - - additionalProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/mfd/allwinner,sun8i-a23-prcm.yaml b/Documentation/devicetree/bindings/mfd/allwinner,sun8i-a23-prcm.yaml index 16c80a7eec49..e51f85519911 100644 --- a/Documentation/devicetree/bindings/mfd/allwinner,sun8i-a23-prcm.yaml +++ b/Documentation/devicetree/bindings/mfd/allwinner,sun8i-a23-prcm.yaml @@ -57,25 +57,17 @@ patternProperties: "#clock-cells": const: 0 - # Already checked in the main schema - compatible: true - clocks: maxItems: 1 clock-output-names: maxItems: 1 - phandle: true - required: - "#clock-cells" - - compatible - clocks - clock-output-names - additionalProperties: false - - if: properties: compatible: @@ -91,9 +83,6 @@ patternProperties: offset of the bit controlling this particular gate in the register. - # Already checked in the main schema - compatible: true - clocks: maxItems: 1 @@ -101,16 +90,11 @@ patternProperties: minItems: 1 maxItems: 32 - phandle: true - required: - "#clock-cells" - - compatible - clocks - clock-output-names - additionalProperties: false - - if: properties: compatible: @@ -122,34 +106,8 @@ patternProperties: "#reset-cells": const: 1 - # Already checked in the main schema - compatible: true - - phandle: true - required: - "#reset-cells" - - compatible - - additionalProperties: false - - - if: - properties: - compatible: - contains: - const: allwinner,sun8i-a23-codec-analog - - then: - properties: - # Already checked in the main schema - compatible: true - - phandle: true - - required: - - compatible - - additionalProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/mfd/arm,dev-platforms-syscon.yaml b/Documentation/devicetree/bindings/mfd/arm,dev-platforms-syscon.yaml new file mode 100644 index 000000000000..46b164ae0831 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/arm,dev-platforms-syscon.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/arm,dev-platforms-syscon.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Arm Ltd Developer Platforms System Controllers + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +description: + The Arm Ltd Integrator, Realview, and Versatile families of developer + platforms are contain various system controller blocks. Often these blocks + are part of a daughterboard or motherboard module. + +properties: + compatible: + oneOf: + - items: + - enum: + - arm,integrator-ap-syscon + - arm,integrator-cp-syscon + - arm,integrator-sp-syscon + - arm,im-pd1-syscon + - const: syscon + - items: + - enum: + - arm,core-module-integrator + - arm,integrator-ap-syscon + - arm,integrator-cp-syscon + - arm,integrator-sp-syscon + - arm,realview-eb-syscon + - arm,realview-pb1176-syscon + - arm,realview-pb11mp-syscon + - arm,realview-pba8-syscon + - arm,realview-pbx-syscon + - arm,versatile-ib2-syscon + - const: syscon + - const: simple-mfd + - items: + - enum: + - arm,realview-eb11mp-revb-syscon + - arm,realview-eb11mp-revc-syscon + - const: arm,realview-eb-syscon + - const: syscon + - const: simple-mfd + + reg: + maxItems: 1 + + ranges: true + + '#address-cells': + const: 1 + + '#size-cells': + const: 1 + +required: + - compatible + - reg + +additionalProperties: + type: object + +... diff --git a/Documentation/devicetree/bindings/mfd/aspeed-lpc.yaml b/Documentation/devicetree/bindings/mfd/aspeed-lpc.yaml index 750996d9a175..5dfe77aca167 100644 --- a/Documentation/devicetree/bindings/mfd/aspeed-lpc.yaml +++ b/Documentation/devicetree/bindings/mfd/aspeed-lpc.yaml @@ -27,7 +27,7 @@ description: as LPC firmware hub cycles, configuration of the LPC-to-AHB mapping, UART management and bus snoop configuration. - * A set of SuperIO[3] scratch registers enableing implementation of e.g. custom + * A set of SuperIO[3] scratch registers enabling implementation of e.g. custom hardware management protocols for handover between the host and baseboard management controller. diff --git a/Documentation/devicetree/bindings/mfd/atmel-flexcom.txt b/Documentation/devicetree/bindings/mfd/atmel-flexcom.txt index 9d837535637b..af692e8833a5 100644 --- a/Documentation/devicetree/bindings/mfd/atmel-flexcom.txt +++ b/Documentation/devicetree/bindings/mfd/atmel-flexcom.txt @@ -6,6 +6,7 @@ at boot time according to the device tree. Required properties: - compatible: Should be "atmel,sama5d2-flexcom" + or "microchip,sam9x7-flexcom", "atmel,sama5d2-flexcom" - reg: Should be the offset/length value for Flexcom dedicated I/O registers (without USART, TWI or SPI registers). - clocks: Should be the Flexcom peripheral clock from PMC. diff --git a/Documentation/devicetree/bindings/mfd/atmel-gpbr.txt b/Documentation/devicetree/bindings/mfd/atmel-gpbr.txt index e8c525569f10..3c989d1760a2 100644 --- a/Documentation/devicetree/bindings/mfd/atmel-gpbr.txt +++ b/Documentation/devicetree/bindings/mfd/atmel-gpbr.txt @@ -6,6 +6,7 @@ Required properties: - compatible: Should be one of the following: "atmel,at91sam9260-gpbr", "syscon" "microchip,sam9x60-gpbr", "syscon" + "microchip,sam9x7-gpbr", "microchip,sam9x60-gpbr", "syscon" - reg: contains offset/length value of the GPBR memory region. diff --git a/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt b/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt index 5f8880cc757e..7de696eefaed 100644 --- a/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt +++ b/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt @@ -8,6 +8,7 @@ Required properties: "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". diff --git a/Documentation/devicetree/bindings/mfd/atmel-matrix.txt b/Documentation/devicetree/bindings/mfd/atmel-matrix.txt index 89d05c64fb01..6e5f83614e83 100644 --- a/Documentation/devicetree/bindings/mfd/atmel-matrix.txt +++ b/Documentation/devicetree/bindings/mfd/atmel-matrix.txt @@ -14,6 +14,7 @@ Required properties: "atmel,at91sam9x5-matrix", "syscon" "atmel,sama5d3-matrix", "syscon" "microchip,sam9x60-matrix", "syscon" + "microchip,sam9x7-matrix", "atmel,at91sam9x5-matrix", "syscon" - reg: Contains offset/length value of the Bus Matrix memory region. diff --git a/Documentation/devicetree/bindings/mfd/atmel-smc.txt b/Documentation/devicetree/bindings/mfd/atmel-smc.txt index 5696d9fcb5dc..fd62add38a79 100644 --- a/Documentation/devicetree/bindings/mfd/atmel-smc.txt +++ b/Documentation/devicetree/bindings/mfd/atmel-smc.txt @@ -10,6 +10,7 @@ Required properties: "atmel,sama5d3-smc", "syscon" "atmel,sama5d2-smc", "syscon" "microchip,sam9x60-smc", "syscon" + "microchip,sam9x7-smc", "atmel,at91sam9260-smc", "syscon" - reg: Contains offset/length value of the SMC memory region. diff --git a/Documentation/devicetree/bindings/mfd/brcm,bcm6318-gpio-sysctl.yaml b/Documentation/devicetree/bindings/mfd/brcm,bcm6318-gpio-sysctl.yaml index 9f9a14af875e..cb480162f967 100644 --- a/Documentation/devicetree/bindings/mfd/brcm,bcm6318-gpio-sysctl.yaml +++ b/Documentation/devicetree/bindings/mfd/brcm,bcm6318-gpio-sysctl.yaml @@ -35,7 +35,7 @@ patternProperties: "^gpio@[0-9a-f]+$": # Child node type: object - $ref: "../gpio/brcm,bcm63xx-gpio.yaml" + $ref: /schemas/gpio/brcm,bcm63xx-gpio.yaml description: GPIO controller for the SoC GPIOs. This child node definition should follow the bindings specified in @@ -44,7 +44,7 @@ patternProperties: "^pinctrl@[0-9a-f]+$": # Child node type: object - $ref: "../pinctrl/brcm,bcm6318-pinctrl.yaml" + $ref: /schemas/pinctrl/brcm,bcm6318-pinctrl.yaml description: Pin controller for the SoC pins. This child node definition should follow the bindings specified in diff --git a/Documentation/devicetree/bindings/mfd/brcm,bcm63268-gpio-sysctl.yaml b/Documentation/devicetree/bindings/mfd/brcm,bcm63268-gpio-sysctl.yaml index 803277dd2725..c14def1b2ad2 100644 --- a/Documentation/devicetree/bindings/mfd/brcm,bcm63268-gpio-sysctl.yaml +++ b/Documentation/devicetree/bindings/mfd/brcm,bcm63268-gpio-sysctl.yaml @@ -35,7 +35,7 @@ patternProperties: "^gpio@[0-9a-f]+$": # Child node type: object - $ref: "../gpio/brcm,bcm63xx-gpio.yaml" + $ref: /schemas/gpio/brcm,bcm63xx-gpio.yaml description: GPIO controller for the SoC GPIOs. This child node definition should follow the bindings specified in @@ -44,7 +44,7 @@ patternProperties: "^pinctrl@[0-9a-f]+$": # Child node type: object - $ref: "../pinctrl/brcm,bcm63268-pinctrl.yaml" + $ref: /schemas/pinctrl/brcm,bcm63268-pinctrl.yaml description: Pin controller for the SoC pins. This child node definition should follow the bindings specified in diff --git a/Documentation/devicetree/bindings/mfd/brcm,bcm6328-gpio-sysctl.yaml b/Documentation/devicetree/bindings/mfd/brcm,bcm6328-gpio-sysctl.yaml index b9a6856ce970..5f48209ed40f 100644 --- a/Documentation/devicetree/bindings/mfd/brcm,bcm6328-gpio-sysctl.yaml +++ b/Documentation/devicetree/bindings/mfd/brcm,bcm6328-gpio-sysctl.yaml @@ -35,7 +35,7 @@ patternProperties: "^gpio@[0-9a-f]+$": # Child node type: object - $ref: "../gpio/brcm,bcm63xx-gpio.yaml" + $ref: /schemas/gpio/brcm,bcm63xx-gpio.yaml description: GPIO controller for the SoC GPIOs. This child node definition should follow the bindings specified in @@ -44,7 +44,7 @@ patternProperties: "^pinctrl@[0-9a-f]+$": # Child node type: object - $ref: "../pinctrl/brcm,bcm6328-pinctrl.yaml" + $ref: /schemas/pinctrl/brcm,bcm6328-pinctrl.yaml description: Pin controller for the SoC pins. This child node definition should follow the bindings specified in diff --git a/Documentation/devicetree/bindings/mfd/brcm,bcm6358-gpio-sysctl.yaml b/Documentation/devicetree/bindings/mfd/brcm,bcm6358-gpio-sysctl.yaml index 4651fe4dde07..f1f4629565d9 100644 --- a/Documentation/devicetree/bindings/mfd/brcm,bcm6358-gpio-sysctl.yaml +++ b/Documentation/devicetree/bindings/mfd/brcm,bcm6358-gpio-sysctl.yaml @@ -35,7 +35,7 @@ patternProperties: "^gpio@[0-9a-f]+$": # Child node type: object - $ref: "../gpio/brcm,bcm63xx-gpio.yaml" + $ref: /schemas/gpio/brcm,bcm63xx-gpio.yaml description: GPIO controller for the SoC GPIOs. This child node definition should follow the bindings specified in @@ -44,7 +44,7 @@ patternProperties: "^pinctrl@[0-9a-f]+$": # Child node type: object - $ref: "../pinctrl/brcm,bcm6358-pinctrl.yaml" + $ref: /schemas/pinctrl/brcm,bcm6358-pinctrl.yaml description: Pin controller for the SoC pins. This child node definition should follow the bindings specified in diff --git a/Documentation/devicetree/bindings/mfd/brcm,bcm6362-gpio-sysctl.yaml b/Documentation/devicetree/bindings/mfd/brcm,bcm6362-gpio-sysctl.yaml index 0330b621fd38..4d594739b382 100644 --- a/Documentation/devicetree/bindings/mfd/brcm,bcm6362-gpio-sysctl.yaml +++ b/Documentation/devicetree/bindings/mfd/brcm,bcm6362-gpio-sysctl.yaml @@ -35,7 +35,7 @@ patternProperties: "^gpio@[0-9a-f]+$": # Child node type: object - $ref: "../gpio/brcm,bcm63xx-gpio.yaml" + $ref: /schemas/gpio/brcm,bcm63xx-gpio.yaml description: GPIO controller for the SoC GPIOs. This child node definition should follow the bindings specified in @@ -44,7 +44,7 @@ patternProperties: "^pinctrl@[0-9a-f]+$": # Child node type: object - $ref: "../pinctrl/brcm,bcm6362-pinctrl.yaml" + $ref: /schemas/pinctrl/brcm,bcm6362-pinctrl.yaml description: Pin controller for the SoC pins. This child node definition should follow the bindings specified in diff --git a/Documentation/devicetree/bindings/mfd/brcm,bcm6368-gpio-sysctl.yaml b/Documentation/devicetree/bindings/mfd/brcm,bcm6368-gpio-sysctl.yaml index 82d3e4415bda..aae83d432880 100644 --- a/Documentation/devicetree/bindings/mfd/brcm,bcm6368-gpio-sysctl.yaml +++ b/Documentation/devicetree/bindings/mfd/brcm,bcm6368-gpio-sysctl.yaml @@ -35,7 +35,7 @@ patternProperties: "^gpio@[0-9a-f]+$": # Child node type: object - $ref: "../gpio/brcm,bcm63xx-gpio.yaml" + $ref: /schemas/gpio/brcm,bcm63xx-gpio.yaml description: GPIO controller for the SoC GPIOs. This child node definition should follow the bindings specified in @@ -44,7 +44,7 @@ patternProperties: "^pinctrl@[0-9a-f]+$": # Child node type: object - $ref: "../pinctrl/brcm,bcm6368-pinctrl.yaml" + $ref: /schemas/pinctrl/brcm,bcm6368-pinctrl.yaml description: Pin controller for the SoC pins. This child node definition should follow the bindings specified in diff --git a/Documentation/devicetree/bindings/mfd/max8925.txt b/Documentation/devicetree/bindings/mfd/max8925.txt deleted file mode 100644 index 4f0dc6638e5e..000000000000 --- a/Documentation/devicetree/bindings/mfd/max8925.txt +++ /dev/null @@ -1,64 +0,0 @@ -* Maxim max8925 Power Management IC - -Required parent device properties: -- compatible : "maxim,max8925" -- reg : the I2C slave address for the max8925 chip -- interrupts : IRQ line for the max8925 chip -- interrupt-controller: describes the max8925 as an interrupt - controller (has its own domain) -- #interrupt-cells : should be 1. - - The cell is the max8925 local IRQ number - -Optional parent device properties: -- maxim,tsc-irq: there are 2 IRQ lines for max8925, one is indicated in - interrupts property, the other is indicated here. - -max8925 consists of a large and varied group of sub-devices: - -Device Supply Names Description ------- ------------ ----------- -max8925-onkey : : On key -max8925-rtc : : RTC -max8925-regulator : : Regulators -max8925-backlight : : Backlight -max8925-touch : : Touchscreen -max8925-power : : Charger - -Example: - - pmic: max8925@3c { - compatible = "maxim,max8925"; - reg = <0x3c>; - interrupts = <1>; - interrupt-parent = <&intcmux4>; - interrupt-controller; - #interrupt-cells = <1>; - maxim,tsc-irq = <0>; - - regulators { - SDV1 { - regulator-min-microvolt = <637500>; - regulator-max-microvolt = <1425000>; - regulator-boot-on; - regulator-always-on; - }; - - LDO1 { - regulator-min-microvolt = <750000>; - regulator-max-microvolt = <3900000>; - regulator-boot-on; - regulator-always-on; - }; - - }; - backlight { - maxim,max8925-dual-string = <0>; - }; - charger { - batt-detect = <0>; - topoff-threshold = <1>; - fast-charge = <7>; - no-temp-support = <0>; - no-insert-detect = <0>; - }; - }; diff --git a/Documentation/devicetree/bindings/mfd/max8998.txt b/Documentation/devicetree/bindings/mfd/max8998.txt deleted file mode 100644 index 4ed52184d081..000000000000 --- a/Documentation/devicetree/bindings/mfd/max8998.txt +++ /dev/null @@ -1,125 +0,0 @@ -* Maxim MAX8998, National/TI LP3974 multi-function device - -The Maxim MAX8998 is a multi-function device which includes voltage/current -regulators, real time clock, battery charging controller and several -other sub-blocks. It is interfaced using an I2C interface. Each sub-block -is addressed by the host system using different i2c slave address. - -PMIC sub-block --------------- - -The PMIC sub-block contains a number of voltage and current regulators, -with controllable parameters and dynamic voltage scaling capability. -In addition, it includes a real time clock and battery charging controller -as well. It is accessible at I2C address 0x66. - -Required properties: -- compatible: Should be one of the following: - - "maxim,max8998" for Maxim MAX8998 - - "national,lp3974" or "ti,lp3974" for National/TI LP3974. -- reg: Specifies the i2c slave address of the pmic block. It should be 0x66. - -Optional properties: -- interrupts: Interrupt specifiers for two interrupt sources. - - First interrupt specifier is for main interrupt. - - Second interrupt specifier is for power-on/-off interrupt. -- max8998,pmic-buck1-dvs-gpios: GPIO specifiers for two host gpios used - for buck 1 dvs. The format of the gpio specifier depends on the gpio - controller. -- max8998,pmic-buck2-dvs-gpio: GPIO specifier for host gpio used - for buck 2 dvs. The format of the gpio specifier depends on the gpio - controller. -- max8998,pmic-buck1-default-dvs-idx: Default voltage setting selected from - the possible 4 options selectable by the dvs gpios. The value of this - property should be 0, 1, 2 or 3. If not specified or out of range, - a default value of 0 is taken. -- max8998,pmic-buck2-default-dvs-idx: Default voltage setting selected from - the possible 2 options selectable by the dvs gpios. The value of this - property should be 0 or 1. If not specified or out of range, a default - value of 0 is taken. -- max8998,pmic-buck-voltage-lock: If present, disallows changing of - preprogrammed buck dvfs voltages. - -Additional properties required if max8998,pmic-buck1-dvs-gpios is defined: -- max8998,pmic-buck1-dvs-voltage: An array of 4 voltage values in microvolts - for buck1 regulator that can be selected using dvs gpio. - -Additional properties required if max8998,pmic-buck2-dvs-gpio is defined: -- max8998,pmic-buck2-dvs-voltage: An array of 2 voltage values in microvolts - for buck2 regulator that can be selected using dvs gpio. - -Regulators: All the regulators of MAX8998 to be instantiated shall be -listed in a child node named 'regulators'. Each regulator is represented -by a child node of the 'regulators' node. - - regulator-name { - /* standard regulator bindings here */ - }; - -Following regulators of the MAX8998 PMIC block are supported. Note that -the 'n' in regulator name, as in LDOn or BUCKn, represents the LDO or BUCK -number as described in MAX8998 datasheet. - - - LDOn - - valid values for n are 2 to 17 - - Example: LDO2, LDO10, LDO17 - - BUCKn - - valid values for n are 1 to 4. - - Example: BUCK1, BUCK2, BUCK3, BUCK4 - - - ENVICHG: Battery Charging Current Monitor Output. This is a fixed - voltage type regulator - - - ESAFEOUT1: (ldo19) - - ESAFEOUT2: (ld020) - - - CHARGER: main battery charger current control - -Standard regulator bindings are used inside regulator subnodes. Check - Documentation/devicetree/bindings/regulator/regulator.txt -for more details. - -Example: - - pmic@66 { - compatible = "maxim,max8998-pmic"; - reg = <0x66>; - interrupt-parent = <&wakeup_eint>; - interrupts = <4 0>, <3 0>; - - /* Buck 1 DVS settings */ - max8998,pmic-buck1-default-dvs-idx = <0>; - max8998,pmic-buck1-dvs-gpios = <&gpx0 0 1 0 0>, /* SET1 */ - <&gpx0 1 1 0 0>; /* SET2 */ - max8998,pmic-buck1-dvs-voltage = <1350000>, <1300000>, - <1000000>, <950000>; - - /* Buck 2 DVS settings */ - max8998,pmic-buck2-default-dvs-idx = <0>; - max8998,pmic-buck2-dvs-gpio = <&gpx0 0 3 0 0>; /* SET3 */ - max8998,pmic-buck2-dvs-voltage = <1350000>, <1300000>; - - /* Regulators to instantiate */ - regulators { - ldo2_reg: LDO2 { - regulator-name = "VDD_ALIVE_1.1V"; - regulator-min-microvolt = <1100000>; - regulator-max-microvolt = <1100000>; - regulator-always-on; - }; - - buck1_reg: BUCK1 { - regulator-name = "VDD_ARM_1.2V"; - regulator-min-microvolt = <950000>; - regulator-max-microvolt = <1350000>; - regulator-always-on; - regulator-boot-on; - }; - - charger_reg: CHARGER { - regulator-name = "CHARGER"; - regulator-min-microamp = <90000>; - regulator-max-microamp = <800000>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/mfd/maxim,max5970.yaml b/Documentation/devicetree/bindings/mfd/maxim,max5970.yaml index da67742c5aa9..0da5cae3852e 100644 --- a/Documentation/devicetree/bindings/mfd/maxim,max5970.yaml +++ b/Documentation/devicetree/bindings/mfd/maxim,max5970.yaml @@ -45,8 +45,13 @@ properties: patternProperties: "^led@[0-3]$": $ref: /schemas/leds/common.yaml# + unevaluatedProperties: false type: object + properties: + reg: + maximum: 3 + additionalProperties: false vss1-supply: diff --git a/Documentation/devicetree/bindings/mfd/maxim,max77693.yaml b/Documentation/devicetree/bindings/mfd/maxim,max77693.yaml index 1b06a77ec798..6a6f222b868f 100644 --- a/Documentation/devicetree/bindings/mfd/maxim,max77693.yaml +++ b/Documentation/devicetree/bindings/mfd/maxim,max77693.yaml @@ -37,6 +37,7 @@ properties: max77693-muic: type: object additionalProperties: false + deprecated: true properties: compatible: @@ -45,6 +46,21 @@ properties: required: - compatible + muic: + type: object + additionalProperties: false + + properties: + compatible: + const: maxim,max77693-muic + + connector: + $ref: /schemas/connector/usb-connector.yaml# + unevaluatedProperties: false + + required: + - compatible + motor-driver: type: object additionalProperties: false @@ -107,6 +123,38 @@ examples: }; }; + muic { + compatible = "maxim,max77693-muic"; + + connector { + compatible = "samsung,usb-connector-11pin", + "usb-b-connector"; + label = "micro-USB"; + type = "micro"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + muic_to_usb: endpoint { + remote-endpoint = <&usb_to_muic>; + }; + }; + + port@3 { + reg = <3>; + + muic_to_mhl: endpoint { + remote-endpoint = <&mhl_to_muic>; + }; + }; + }; + }; + }; + motor-driver { compatible = "maxim,max77693-haptic"; haptic-supply = <&ldo26_reg>; diff --git a/Documentation/devicetree/bindings/mfd/maxim,max8925.yaml b/Documentation/devicetree/bindings/mfd/maxim,max8925.yaml new file mode 100644 index 000000000000..86dd810851ab --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/maxim,max8925.yaml @@ -0,0 +1,145 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/maxim,max8925.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MAX8925 PMIC from Maxim Integrated. + +maintainers: + - Lee Jones <lee@kernel.org> + +properties: + compatible: + const: maxim,max8925 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + "#interrupt-cells": + const: 1 + description: + The cell is the IRQ number + + maxim,tsc-irq: + description: second interrupt from max8925 + $ref: /schemas/types.yaml#/definitions/uint32 + + regulators: + type: object + + patternProperties: + "^SDV[1-3]$|^LDO[1-9]$|^LDO1[0-9]$|^LDO20$": + description: regulator configuration for SDV1-3 and LDO1-20 + $ref: /schemas/regulator/regulator.yaml + unevaluatedProperties: false + + additionalProperties: false + + backlight: + type: object + properties: + maxim,max8925-dual-string: + description: set to 1 to support dual string + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + default: 0 + + additionalProperties: false + + charger: + type: object + properties: + batt-detect: + description: set to 1 if battery detection via ID pin is supported + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + default: 0 + + topoff-threshold: + description: charging current in topoff mode, configures bits 5-6 in CHG_CNTL1 + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 3 + default: 0 + + fast-charge: + description: set charging current in fast mode, configures bits 0-3 in CHG_CNTL1 + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 7 + default: 0 + + no-temp-support: + description: set to 1 if temperature sensing is not supported + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + default: 0 + + no-insert-detect: + description: set to 1 if AC detection is not supported + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + default: 0 + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - interrupt-controller + - "#interrupt-cells" + - regulators + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@3c { + compatible = "maxim,max8925"; + reg = <0x3c>; + interrupts = <1>; + interrupt-parent = <&intcmux4>; + interrupt-controller; + #interrupt-cells = <1>; + maxim,tsc-irq = <0>; + + regulators { + SDV1 { + regulator-min-microvolt = <637500>; + regulator-max-microvolt = <1425000>; + regulator-boot-on; + regulator-always-on; + }; + + LDO1 { + regulator-min-microvolt = <750000>; + regulator-max-microvolt = <3900000>; + regulator-boot-on; + regulator-always-on; + }; + }; + + backlight { + maxim,max8925-dual-string = <0>; + }; + + charger { + batt-detect = <0>; + topoff-threshold = <1>; + fast-charge = <7>; + no-temp-support = <0>; + no-insert-detect = <0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/maxim,max8998.yaml b/Documentation/devicetree/bindings/mfd/maxim,max8998.yaml new file mode 100644 index 000000000000..f3c3f64fd012 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/maxim,max8998.yaml @@ -0,0 +1,324 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/maxim,max8998.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX8998, National/TI LP3974 Power Management IC + +maintainers: + - Krzysztof Kozlowski <krzk@kernel.org> + +description: + The Maxim MAX8998 is a Power Management IC which includes voltage/current + regulators, real time clock, battery charging controller and several other + sub-blocks. It is interfaced using an I2C interface. Each sub-block is + addressed by the host system using different i2c slave address. + +properties: + compatible: + enum: + - maxim,max8998 + - national,lp3974 + - ti,lp3974 + + reg: + maxItems: 1 + + interrupts: + minItems: 1 + items: + - description: Main interrupt + - description: Power-on/-off interrupt + + max8998,pmic-buck1-dvs-gpios: + maxItems: 2 + description: + Two host gpios used for buck1 DVS. + + max8998,pmic-buck2-dvs-gpio: + maxItems: 1 + description: + Host gpio used for buck2 DVS. + + max8998,pmic-buck1-default-dvs-idx: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + default: 0 + description: + Default voltage setting selected from the possible 4 options selectable + by the DVS gpios. + + max8998,pmic-buck2-default-dvs-idx: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + default: 0 + description: + Default voltage setting selected from the possible 2 options selectable + by the DVS GPIOs. + + max8998,pmic-buck-voltage-lock: + type: boolean + description: + If present, disallows changing of preprogrammed buck DVS voltages. + + max8998,pmic-buck1-dvs-voltage: + $ref: /schemas/types.yaml#/definitions/uint32-array + maxItems: 4 + description: + Four voltage values in microvolts for buck1 regulator that can be + selected using DVS GPIO. + + max8998,pmic-buck2-dvs-voltage: + $ref: /schemas/types.yaml#/definitions/uint32-array + maxItems: 2 + description: + Two voltage values in microvolts for buck2 regulator that can be + selected using DVS GPIO. + + regulators: + type: object + additionalProperties: false + + properties: + CHARGER: + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + description: + CHARGER is main battery charger current control, wrongly represented + as regulator. + + properties: + regulator-min-microamp: + minimum: 90000 + maximum: 800000 + + regulator-max-microamp: + minimum: 90000 + maximum: 800000 + + regulator-min-microvolt: false + regulator-max-microvolt: false + + required: + - regulator-name + + patternProperties: + "^(LDO([2-9]|1[0-7])|BUCK[1-4])$": + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + required: + - regulator-name + + "^(EN32KHz-AP|EN32KHz-CP|ENVICHG|ESAFEOUT[12])$": + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + description: | + EN32KHz-AP and EN32KHz-CP are 32768 Hz clocks, wrongly represented as + regulators. + ENVICHG is a Battery Charging Current Monitor Output. + + properties: + regulator-min-microvolt: false + regulator-max-microvolt: false + + required: + - regulator-name + +dependencies: + max8998,pmic-buck1-dvs-gpios: [ "max8998,pmic-buck1-dvs-voltage" ] + max8998,pmic-buck2-dvs-gpio: [ "max8998,pmic-buck2-dvs-voltage" ] + +required: + - compatible + - reg + - regulators + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@66 { + compatible = "national,lp3974"; + reg = <0x66>; + interrupts-extended = <&gpx0 7 IRQ_TYPE_LEVEL_LOW>, + <&gpx2 7 IRQ_TYPE_LEVEL_LOW>; + pinctrl-names = "default"; + pinctrl-0 = <&lp3974_irq>; + + max8998,pmic-buck1-default-dvs-idx = <0>; + max8998,pmic-buck1-dvs-gpios = <&gpx0 5 GPIO_ACTIVE_HIGH>, + <&gpx0 6 GPIO_ACTIVE_HIGH>; + max8998,pmic-buck1-dvs-voltage = <1100000>, <1000000>, + <1100000>, <1000000>; + max8998,pmic-buck2-default-dvs-idx = <0>; + max8998,pmic-buck2-dvs-gpio = <&gpe2 0 GPIO_ACTIVE_HIGH>; + max8998,pmic-buck2-dvs-voltage = <1200000>, <1100000>; + + regulators { + LDO2 { + regulator-name = "VALIVE_1.2V"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-always-on; + }; + + LDO3 { + regulator-name = "VUSB+MIPI_1.1V"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1100000>; + regulator-always-on; + }; + + LDO4 { + regulator-name = "VADC_3.3V"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + }; + + LDO5 { + regulator-name = "VTF_2.8V"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + }; + + LDO6 { + regulator-name = "LDO6"; + regulator-min-microvolt = <2000000>; + regulator-max-microvolt = <2000000>; + }; + + LDO7 { + regulator-name = "VLCD+VMIPI_1.8V"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + }; + + LDO8 { + regulator-name = "VUSB+VDAC_3.3V"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + LDO9 { + regulator-name = "VCC_2.8V"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-always-on; + }; + + LDO10 { + regulator-name = "VPLL_1.1V"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1100000>; + regulator-boot-on; + regulator-always-on; + }; + + LDO11 { + regulator-name = "CAM_AF_3.3V"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + }; + + LDO12 { + regulator-name = "PS_2.8V"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + }; + + LDO13 { + regulator-name = "VHIC_1.2V"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + }; + + LDO14 { + regulator-name = "CAM_I_HOST_1.8V"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + }; + + LDO15 { + regulator-name = "CAM_S_DIG+FM33_CORE_1.2V"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + }; + + LDO16 { + regulator-name = "CAM_S_ANA_2.8V"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + }; + + LDO17 { + regulator-name = "VCC_3.0V_LCD"; + regulator-min-microvolt = <3000000>; + regulator-max-microvolt = <3000000>; + }; + + BUCK1 { + regulator-name = "VINT_1.1V"; + regulator-min-microvolt = <750000>; + regulator-max-microvolt = <1500000>; + regulator-boot-on; + regulator-always-on; + }; + + BUCK2 { + regulator-name = "VG3D_1.1V"; + regulator-min-microvolt = <750000>; + regulator-max-microvolt = <1500000>; + regulator-boot-on; + }; + + BUCK3 { + regulator-name = "VCC_1.8V"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-always-on; + }; + + BUCK4 { + regulator-name = "VMEM_1.2V"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-always-on; + }; + + EN32KHz-AP { + regulator-name = "32KHz AP"; + regulator-always-on; + }; + + EN32KHz-CP { + regulator-name = "32KHz CP"; + }; + + ENVICHG { + regulator-name = "VICHG"; + }; + + ESAFEOUT1 { + regulator-name = "SAFEOUT1"; + }; + + ESAFEOUT2 { + regulator-name = "SAFEOUT2"; + regulator-boot-on; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/mediatek,mt6357.yaml b/Documentation/devicetree/bindings/mfd/mediatek,mt6357.yaml index fc2a53148e1c..37423c2e0fdf 100644 --- a/Documentation/devicetree/bindings/mfd/mediatek,mt6357.yaml +++ b/Documentation/devicetree/bindings/mfd/mediatek,mt6357.yaml @@ -40,6 +40,7 @@ properties: regulators: type: object $ref: /schemas/regulator/mediatek,mt6357-regulator.yaml + unevaluatedProperties: false description: List of MT6357 BUCKs and LDOs regulators. @@ -59,6 +60,7 @@ properties: keys: type: object $ref: /schemas/input/mediatek,pmic-keys.yaml + unevaluatedProperties: false description: MT6357 power and home keys. diff --git a/Documentation/devicetree/bindings/mfd/mt6397.txt b/Documentation/devicetree/bindings/mfd/mt6397.txt index 294693a8906c..10540aa7afa1 100644 --- a/Documentation/devicetree/bindings/mfd/mt6397.txt +++ b/Documentation/devicetree/bindings/mfd/mt6397.txt @@ -22,8 +22,9 @@ compatible: "mediatek,mt6323" for PMIC MT6323 "mediatek,mt6331" for PMIC MT6331 and MT6332 "mediatek,mt6357" for PMIC MT6357 - "mediatek,mt6358" for PMIC MT6358 and MT6366 + "mediatek,mt6358" for PMIC MT6358 "mediatek,mt6359" for PMIC MT6359 + "mediatek,mt6366", "mediatek,mt6358" for PMIC MT6366 "mediatek,mt6397" for PMIC MT6397 Optional subnodes: @@ -40,6 +41,7 @@ Optional subnodes: - compatible: "mediatek,mt6323-regulator" see ../regulator/mt6323-regulator.txt - compatible: "mediatek,mt6358-regulator" + - compatible: "mediatek,mt6366-regulator", "mediatek-mt6358-regulator" see ../regulator/mt6358-regulator.txt - compatible: "mediatek,mt6397-regulator" see ../regulator/mt6397-regulator.txt diff --git a/Documentation/devicetree/bindings/mfd/qcom,pm8008.yaml b/Documentation/devicetree/bindings/mfd/qcom,pm8008.yaml index e6a2387d8650..9e4eed34dae8 100644 --- a/Documentation/devicetree/bindings/mfd/qcom,pm8008.yaml +++ b/Documentation/devicetree/bindings/mfd/qcom,pm8008.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. PM8008 PMIC maintainers: - - Guru Das Srinagesh <gurus@codeaurora.org> + - Guru Das Srinagesh <quic_gurus@quicinc.com> description: | Qualcomm Technologies, Inc. PM8008 is a dedicated camera PMIC that integrates diff --git a/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml b/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml index 8b9a2008a354..9fa568603930 100644 --- a/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml +++ b/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml @@ -41,6 +41,7 @@ properties: - qcom,pm660 - qcom,pm660l - qcom,pm7250b + - qcom,pm7550ba - qcom,pm7325 - qcom,pm8004 - qcom,pm8005 @@ -57,6 +58,7 @@ properties: - qcom,pm8350 - qcom,pm8350b - qcom,pm8350c + - qcom,pm8450 - qcom,pm8550 - qcom,pm8550b - qcom,pm8550ve @@ -70,6 +72,8 @@ properties: - qcom,pm8994 - qcom,pm8998 - qcom,pma8084 + - qcom,pmc8180 + - qcom,pmc8180c - qcom,pmd9635 - qcom,pmi632 - qcom,pmi8950 @@ -88,6 +92,7 @@ properties: - qcom,pms405 - qcom,pmx55 - qcom,pmx65 + - qcom,pmx75 - qcom,smb2351 - const: qcom,spmi-pmic @@ -127,7 +132,7 @@ patternProperties: "^audio-codec@[0-9a-f]+$": type: object - additionalProperties: true # FIXME qcom,pm8916-wcd-analog-codec binding not converted yet + $ref: /schemas/sound/qcom,pm8916-wcd-analog-codec.yaml# "^charger@[0-9a-f]+$": type: object @@ -164,6 +169,10 @@ patternProperties: type: object $ref: /schemas/thermal/qcom,spmi-temp-alarm.yaml# + "^typec@[0-9a-f]+$": + type: object + $ref: /schemas/usb/qcom,pmic-typec.yaml# + "^usb-detect@[0-9a-f]+$": type: object $ref: /schemas/extcon/qcom,pm8941-misc.yaml# @@ -230,13 +239,13 @@ examples: interrupt-controller; #interrupt-cells = <4>; - pmi8998_lsid0: pmic@2 { + pmic@2 { compatible = "qcom,pmi8998", "qcom,spmi-pmic"; reg = <0x2 SPMI_USID>; #address-cells = <1>; #size-cells = <0>; - pmi8998_gpio: gpio@c000 { + gpio@c000 { compatible = "qcom,pmi8998-gpio", "qcom,spmi-gpio"; reg = <0xc000>; gpio-controller; @@ -321,7 +330,7 @@ examples: }; }; - pm6150_gpio: gpio@c000 { + gpio@c000 { compatible = "qcom,pm6150-gpio", "qcom,spmi-gpio"; reg = <0xc000>; gpio-controller; diff --git a/Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml b/Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml index 5ad9d5deaaf8..33c3d023a106 100644 --- a/Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml +++ b/Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml @@ -27,6 +27,7 @@ properties: - qcom,sdm845-tcsr - qcom,sdx55-tcsr - qcom,sdx65-tcsr + - qcom,sm4450-tcsr - qcom,sm8150-tcsr - qcom,sm8450-tcsr - qcom,tcsr-apq8064 diff --git a/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.yaml b/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.yaml index 9c51c1b19067..7fe3875a5996 100644 --- a/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.yaml +++ b/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.yaml @@ -43,13 +43,37 @@ properties: interrupt-controller: true patternProperties: + "gpio@[0-9a-f]+$": + type: object + $ref: /schemas/pinctrl/qcom,pmic-gpio.yaml# + + "keypad@[0-9a-f]+$": + type: object + $ref: /schemas/input/qcom,pm8921-keypad.yaml# + "led@[0-9a-f]+$": type: object $ref: /schemas/leds/qcom,pm8058-led.yaml# + "mpps@[0-9a-f]+$": + type: object + $ref: /schemas/pinctrl/qcom,pmic-mpp.yaml# + + "pwrkey@[0-9a-f]+$": + type: object + $ref: /schemas/input/qcom,pm8921-pwrkey.yaml# + "rtc@[0-9a-f]+$": type: object - $ref: ../rtc/qcom-pm8xxx-rtc.yaml + $ref: /schemas/rtc/qcom-pm8xxx-rtc.yaml# + + "vibrator@[0-9a-f]+$": + type: object + $ref: /schemas/input/qcom,pm8xxx-vib.yaml# + + "xoadc@[0-9a-f]+$": + type: object + $ref: /schemas/iio/adc/qcom,pm8018-adc.yaml# required: - compatible diff --git a/Documentation/devicetree/bindings/mfd/rockchip,rk805.yaml b/Documentation/devicetree/bindings/mfd/rockchip,rk805.yaml index 4992f71b6fc3..44f8188360dd 100644 --- a/Documentation/devicetree/bindings/mfd/rockchip,rk805.yaml +++ b/Documentation/devicetree/bindings/mfd/rockchip,rk805.yaml @@ -42,9 +42,12 @@ properties: rockchip,system-power-controller: type: boolean + deprecated: true description: Telling whether or not this PMIC is controlling the system power. + system-power-controller: true + wakeup-source: type: boolean description: @@ -80,6 +83,7 @@ properties: "^(DCDC_REG[1-4]|LDO_REG[1-3])$": type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false unevaluatedProperties: false allOf: diff --git a/Documentation/devicetree/bindings/mfd/rockchip,rk806.yaml b/Documentation/devicetree/bindings/mfd/rockchip,rk806.yaml index cf2500f2e9a0..3c2b06629b75 100644 --- a/Documentation/devicetree/bindings/mfd/rockchip,rk806.yaml +++ b/Documentation/devicetree/bindings/mfd/rockchip,rk806.yaml @@ -29,6 +29,8 @@ properties: '#gpio-cells': const: 2 + system-power-controller: true + vcc1-supply: description: The input supply for dcdc-reg1. diff --git a/Documentation/devicetree/bindings/mfd/rockchip,rk808.yaml b/Documentation/devicetree/bindings/mfd/rockchip,rk808.yaml index f5908fa01a61..d2ac6fbd5ce6 100644 --- a/Documentation/devicetree/bindings/mfd/rockchip,rk808.yaml +++ b/Documentation/devicetree/bindings/mfd/rockchip,rk808.yaml @@ -37,9 +37,12 @@ properties: rockchip,system-power-controller: type: boolean + deprecated: true description: Telling whether or not this PMIC is controlling the system power. + system-power-controller: true + wakeup-source: type: boolean description: @@ -107,6 +110,7 @@ properties: "^(DCDC_REG[1-4]|LDO_REG[1-8]|SWITCH_REG[1-2])$": type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false unevaluatedProperties: false required: diff --git a/Documentation/devicetree/bindings/mfd/rockchip,rk809.yaml b/Documentation/devicetree/bindings/mfd/rockchip,rk809.yaml index 7fb849ac74a7..839c0521f1e5 100644 --- a/Documentation/devicetree/bindings/mfd/rockchip,rk809.yaml +++ b/Documentation/devicetree/bindings/mfd/rockchip,rk809.yaml @@ -37,9 +37,12 @@ properties: rockchip,system-power-controller: type: boolean + deprecated: true description: Telling whether or not this PMIC is controlling the system power. + system-power-controller: true + wakeup-source: type: boolean description: @@ -86,7 +89,8 @@ properties: patternProperties: "^(LDO_REG[1-9]|DCDC_REG[1-5]|SWITCH_REG[1-2])$": type: object - $ref: ../regulator/regulator.yaml# + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false unevaluatedProperties: false allOf: diff --git a/Documentation/devicetree/bindings/mfd/rockchip,rk817.yaml b/Documentation/devicetree/bindings/mfd/rockchip,rk817.yaml index 269fb85b2027..92b1592e8942 100644 --- a/Documentation/devicetree/bindings/mfd/rockchip,rk817.yaml +++ b/Documentation/devicetree/bindings/mfd/rockchip,rk817.yaml @@ -38,9 +38,12 @@ properties: rockchip,system-power-controller: type: boolean + deprecated: true description: Telling whether or not this PMIC is controlling the system power. + system-power-controller: true + wakeup-source: type: boolean description: diff --git a/Documentation/devicetree/bindings/mfd/rockchip,rk818.yaml b/Documentation/devicetree/bindings/mfd/rockchip,rk818.yaml index b57c4b005cf4..fd4b9de364aa 100644 --- a/Documentation/devicetree/bindings/mfd/rockchip,rk818.yaml +++ b/Documentation/devicetree/bindings/mfd/rockchip,rk818.yaml @@ -37,9 +37,12 @@ properties: rockchip,system-power-controller: type: boolean + deprecated: true description: Telling whether or not this PMIC is controlling the system power. + system-power-controller: true + wakeup-source: type: boolean description: @@ -99,6 +102,7 @@ properties: "^(DCDC_REG[1-4]|DCDC_BOOST|LDO_REG[1-9]|SWITCH_REG|HDMI_SWITCH|OTG_SWITCH)$": type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false unevaluatedProperties: false required: diff --git a/Documentation/devicetree/bindings/mfd/rohm,bd71847-pmic.yaml b/Documentation/devicetree/bindings/mfd/rohm,bd71847-pmic.yaml index 7ab7b2c7f3e6..d783cc4e4e86 100644 --- a/Documentation/devicetree/bindings/mfd/rohm,bd71847-pmic.yaml +++ b/Documentation/devicetree/bindings/mfd/rohm,bd71847-pmic.yaml @@ -130,7 +130,6 @@ dependencies: examples: - | #include <dt-bindings/interrupt-controller/irq.h> - #include <dt-bindings/leds/common.h> i2c { #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/mfd/rohm,bd9576-pmic.yaml b/Documentation/devicetree/bindings/mfd/rohm,bd9576-pmic.yaml index 10f207a38178..b7b323b1a4f2 100644 --- a/Documentation/devicetree/bindings/mfd/rohm,bd9576-pmic.yaml +++ b/Documentation/devicetree/bindings/mfd/rohm,bd9576-pmic.yaml @@ -34,7 +34,7 @@ properties: BD9576 and BD9573 VOUT1 regulator enable state can be individually controlled by a GPIO. This is dictated by state of vout1-en pin during the PMIC startup. If vout1-en is LOW during PMIC startup then the VOUT1 - enable sate is controlled via this pin. Set this property if vout1-en + enable state is controlled via this pin. Set this property if vout1-en is wired to be down at PMIC start-up. type: boolean @@ -61,7 +61,7 @@ properties: rohm,hw-timeout-ms: maxItems: 2 description: - Watchog timeout in milliseconds. If single value is given it is + Watchdog timeout in milliseconds. If single value is given it is the maximum timeout. Eg. if pinging watchdog is not done within this time limit the watchdog will be triggered. If two values are given watchdog is configured in "window mode". Then first value is limit for short-ping diff --git a/Documentation/devicetree/bindings/mfd/st,stmpe.yaml b/Documentation/devicetree/bindings/mfd/st,stmpe.yaml new file mode 100644 index 000000000000..b77cc3f3075d --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/st,stmpe.yaml @@ -0,0 +1,297 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/st,stmpe.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectonics Port Expander (STMPE) + +description: STMicroelectronics Port Expander (STMPE) is a series of slow + bus controllers for various expanded peripherals such as GPIO, keypad, + touchscreen, ADC, PWM or rotator. It can contain one or several different + peripherals connected to SPI or I2C. + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + +properties: + compatible: + enum: + - st,stmpe601 + - st,stmpe801 + - st,stmpe811 + - st,stmpe1600 + - st,stmpe1601 + - st,stmpe2401 + - st,stmpe2403 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + vcc-supply: true + + vio-supply: true + + reset-gpios: + maxItems: 1 + + wakeup-source: true + + st,autosleep-timeout: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 4, 16, 32, 64, 128, 256, 512, 1024 ] + description: Time idle before going to automatic sleep to save power + + st,sample-time: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1, 2, 3, 4, 5, 6 ] + description: | + Sample time per iteration + 0 = 36 clock ticks + 1 = 44 clock ticks + 2 = 56 clock ticks + 3 = 64 clock ticks + 4 = 80 clock ticks - recommended + 5 = 96 clock ticks + 6 = 124 clock ticks + + st,mod-12b: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1 ] + description: ADC bit mode 0 = 10bit ADC, 1 = 12bit ADC + + st,ref-sel: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1 ] + description: ADC reference source 0 = internal, 1 = external + + st,adc-freq: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1, 2, 3 ] + description: | + ADC clock speed + 0 = 1.625 MHz + 1 = 3.25 MHz + 2, 3 = 6.5 MHz + + adc: + type: object + $ref: /schemas/iio/adc/st,stmpe-adc.yaml# + + gpio: + type: object + $ref: /schemas/gpio/st,stmpe-gpio.yaml# + + keyboard-controller: + type: object + $ref: /schemas/input/matrix-keymap.yaml# + + unevaluatedProperties: false + + properties: + compatible: + const: st,stmpe-keypad + + debounce-interval: + description: Debouncing interval in milliseconds + $ref: /schemas/types.yaml#/definitions/uint32 + + st,no-autorepeat: + description: If present, the keys will not autorepeat when pressed + $ref: /schemas/types.yaml#/definitions/flag + + st,scan-count: + description: Scanning cycles elapsed before key data is updated + $ref: /schemas/types.yaml#/definitions/uint32 + + required: + - compatible + - linux,keymap + + pwm: + type: object + $ref: /schemas/pwm/pwm.yaml# + + unevaluatedProperties: false + + properties: + compatible: + const: st,stmpe-pwm + + "#pwm-cells": + const: 2 + + touchscreen: + type: object + $ref: /schemas/input/touchscreen/touchscreen.yaml# + + unevaluatedProperties: false + + properties: + compatible: + const: st,stmpe-ts + + st,ave-ctrl: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1, 2, 3 ] + description: | + Sample average control + 0 = 1 sample + 1 = 2 samples + 2 = 4 samples + 3 = 8 samples + + st,touch-det-delay: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1, 2, 3, 4, 5, 6, 7 ] + description: | + Touch detection delay + 0 = 10 us + 1 = 50 us + 2 = 100 us + 3 = 500 us - recommended + 4 = 1 ms + 5 = 5 ms + 6 = 10 ms + 7 = 50 ms + + st,settling: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1, 2, 3, 4, 5, 6, 7 ] + description: | + Panel driver settling time + 0 = 10 us + 1 = 100 us + 2 = 500 us - recommended + 3 = 1 ms + 4 = 5 ms + 5 = 10 ms + 6 = 50 ms + 7 = 100 ms + + st,fraction-z: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1, 2, 3, 4, 5, 6, 7 ] + description: Length of the fractional part in z, recommended is 7 + (fraction-z ([0..7]) = Count of the fractional part) + + st,i-drive: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1 ] + description: | + current limit value of the touchscreen drivers + 0 = 20 mA (typical 35 mA max) + 1 = 50 mA (typical 80 mA max) + + required: + - compatible + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/input/input.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + port-expander@43 { + compatible = "st,stmpe2401"; + reg = <0x43>; + reset-gpios = <&gpio 13 GPIO_ACTIVE_LOW>; + interrupts = <26 IRQ_TYPE_EDGE_FALLING>; + interrupt-parent = <&gpio>; + vcc-supply = <&db8500_vsmps2_reg>; + vio-supply = <&db8500_vsmps2_reg>; + wakeup-source; + st,autosleep-timeout = <1024>; + + gpio { + compatible = "st,stmpe-gpio"; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + st,norequest-mask = <0xf0f002>; + }; + + keyboard-controller { + compatible = "st,stmpe-keypad"; + debounce-interval = <64>; + st,scan-count = <8>; + st,no-autorepeat; + keypad,num-rows = <8>; + keypad,num-columns = <8>; + linux,keymap = < + MATRIX_KEY(0x00, 0x00, KEY_1) + MATRIX_KEY(0x00, 0x01, KEY_2) + MATRIX_KEY(0x00, 0x02, KEY_3) + MATRIX_KEY(0x00, 0x03, KEY_4) + MATRIX_KEY(0x00, 0x04, KEY_5) + MATRIX_KEY(0x00, 0x05, KEY_6) + MATRIX_KEY(0x00, 0x06, KEY_7) + MATRIX_KEY(0x00, 0x07, KEY_8) + MATRIX_KEY(0x00, 0x08, KEY_9) + MATRIX_KEY(0x00, 0x09, KEY_0) + >; + }; + + pwm { + compatible = "st,stmpe-pwm"; + #pwm-cells = <2>; + }; + }; + + port-expander@41 { + compatible = "st,stmpe811"; + reg = <0x41>; + interrupts = <10 IRQ_TYPE_LEVEL_LOW>; + interrupt-parent = <&gpio>; + st,adc-freq = <1>; + st,mod-12b = <1>; + st,ref-sel = <0>; + st,sample-time = <4>; + + adc { + compatible = "st,stmpe-adc"; + st,norequest-mask = <0x0f>; + #io-channel-cells = <1>; + }; + + gpio { + compatible = "st,stmpe-gpio"; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + }; + + pwm { + compatible = "st,stmpe-pwm"; + #pwm-cells = <2>; + }; + + touchscreen { + compatible = "st,stmpe-ts"; + st,ave-ctrl = <3>; + st,touch-det-delay = <5>; + st,settling = <3>; + st,fraction-z = <7>; + st,i-drive = <1>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/mfd/st,stpmic1.yaml b/Documentation/devicetree/bindings/mfd/st,stpmic1.yaml index 97c61097f9e2..b17ebeb0a42f 100644 --- a/Documentation/devicetree/bindings/mfd/st,stpmic1.yaml +++ b/Documentation/devicetree/bindings/mfd/st,stpmic1.yaml @@ -106,6 +106,7 @@ properties: const: st,stpmic1-regulators ldo3: + $ref: /schemas/regulator/regulator.yaml type: object properties: @@ -128,6 +129,7 @@ properties: additionalProperties: false ldo4: + $ref: /schemas/regulator/regulator.yaml type: object properties: @@ -142,11 +144,14 @@ properties: regulator-name: true regulator-boot-on: true regulator-always-on: true + regulator-min-microvolt: true + regulator-max-microvolt: true regulator-over-current-protection: true additionalProperties: false vref_ddr: + $ref: /schemas/regulator/regulator.yaml type: object properties: @@ -165,6 +170,7 @@ properties: additionalProperties: false boost: + $ref: /schemas/regulator/regulator.yaml type: object properties: @@ -187,10 +193,8 @@ properties: "^(buck[1-4]|ldo[1-6]|vref_ddr|boost|pwr_sw[1-2])-supply$": description: STPMIC1 voltage regulators supplies - "^(buck[1-4]|ldo[1-6]|boost|vref_ddr|pwr_sw[1-2])$": - $ref: ../regulator/regulator.yaml - "^ldo[1-2,5-6]$": + $ref: /schemas/regulator/regulator.yaml type: object properties: @@ -213,6 +217,7 @@ properties: additionalProperties: false "^buck[1-4]$": + $ref: /schemas/regulator/regulator.yaml type: object properties: @@ -237,6 +242,7 @@ properties: additionalProperties: false "^pwr_sw[1-2]$": + $ref: /schemas/regulator/regulator.yaml type: object properties: diff --git a/Documentation/devicetree/bindings/mfd/stericsson,ab8500.yaml b/Documentation/devicetree/bindings/mfd/stericsson,ab8500.yaml index 6c8d42f27fe8..94f9767a927d 100644 --- a/Documentation/devicetree/bindings/mfd/stericsson,ab8500.yaml +++ b/Documentation/devicetree/bindings/mfd/stericsson,ab8500.yaml @@ -313,7 +313,7 @@ properties: - const: audioclk stericsson,earpeice-cmv: - description: Earpeice voltage + description: Earpiece voltage $ref: /schemas/types.yaml#/definitions/uint32 enum: [ 950, 1100, 1270, 1580 ] @@ -337,39 +337,39 @@ properties: with power. ab8500_ldo_aux1: - description: The voltage for the auxilary LDO regulator 1 + description: The voltage for the auxiliary LDO regulator 1 type: object $ref: ../regulator/regulator.yaml# unevaluatedProperties: false ab8500_ldo_aux2: - description: The voltage for the auxilary LDO regulator 2 + description: The voltage for the auxiliary LDO regulator 2 type: object $ref: ../regulator/regulator.yaml# unevaluatedProperties: false ab8500_ldo_aux3: - description: The voltage for the auxilary LDO regulator 3 + description: The voltage for the auxiliary LDO regulator 3 type: object $ref: ../regulator/regulator.yaml# unevaluatedProperties: false ab8500_ldo_aux4: - description: The voltage for the auxilary LDO regulator 4 + description: The voltage for the auxiliary LDO regulator 4 only present on AB8505 type: object $ref: ../regulator/regulator.yaml# unevaluatedProperties: false ab8500_ldo_aux5: - description: The voltage for the auxilary LDO regulator 5 + description: The voltage for the auxiliary LDO regulator 5 only present on AB8505 type: object $ref: ../regulator/regulator.yaml# unevaluatedProperties: false ab8500_ldo_aux6: - description: The voltage for the auxilary LDO regulator 6 + description: The voltage for the auxiliary LDO regulator 6 only present on AB8505 type: object $ref: ../regulator/regulator.yaml# @@ -378,7 +378,7 @@ properties: # There is never any AUX7 regulator which is confusing ab8500_ldo_aux8: - description: The voltage for the auxilary LDO regulator 8 + description: The voltage for the auxiliary LDO regulator 8 only present on AB8505 type: object $ref: ../regulator/regulator.yaml# diff --git a/Documentation/devicetree/bindings/mfd/stericsson,db8500-prcmu.yaml b/Documentation/devicetree/bindings/mfd/stericsson,db8500-prcmu.yaml index 1d4d88f7e82d..cb2a42caabb5 100644 --- a/Documentation/devicetree/bindings/mfd/stericsson,db8500-prcmu.yaml +++ b/Documentation/devicetree/bindings/mfd/stericsson,db8500-prcmu.yaml @@ -72,44 +72,52 @@ properties: main voltage domain for the chip. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_varm: - description: The voltage for the ARM Cortex A-9 CPU. + description: The voltage for the ARM Cortex-A9 CPU. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_vmodem: description: The voltage for the modem subsystem. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_vpll: description: The voltage for the phase locked loop clocks. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_vsmps1: description: Also known as VIO12, is a step-down voltage regulator for 1.2V I/O. SMPS means System Management Power Source. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_vsmps2: description: Also known as VIO18, is a step-down voltage regulator for 1.8V I/O. SMPS means System Management Power Source. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_vsmps3: description: This is a step-down voltage regulator for 0.87 thru 1.875V I/O. SMPS means System Management Power Source. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_vrf1: - description: RF transciever voltage regulator. + description: RF transceiver voltage regulator. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_sva_mmdsp: description: Smart Video Accelerator (SVA) multimedia DSP (MMDSP) @@ -117,18 +125,21 @@ properties: for video encoding and decoding. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_sva_mmdsp_ret: description: Smart Video Accelerator (SVA) multimedia DSP (MMDSP) voltage regulator for retention mode. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_sva_pipe: description: Smart Video Accelerator (SVA) multimedia DSP (MMDSP) voltage regulator for the data pipe. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_sia_mmdsp: description: Smart Image Accelerator (SIA) multimedia DSP (MMDSP) @@ -136,18 +147,21 @@ properties: for image encoding and decoding. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_sia_mmdsp_ret: description: Smart Image Accelerator (SIA) multimedia DSP (MMDSP) voltage regulator for retention mode. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_sia_pipe: description: Smart Image Accelerator (SIA) multimedia DSP (MMDSP) voltage regulator for the data pipe. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_sga: description: Smart Graphics Accelerator (SGA) voltage regulator. @@ -155,6 +169,7 @@ properties: accelerator block. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_b2r2_mcde: description: Blit Blend Rotate and Rescale (B2R2), and Multi-Channel @@ -162,28 +177,33 @@ properties: blocks. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_esram12: description: Embedded Static RAM (ESRAM) 1 and 2 voltage regulator. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_esram12_ret: description: Embedded Static RAM (ESRAM) 1 and 2 voltage regulator for retention mode. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_esram34: description: Embedded Static RAM (ESRAM) 3 and 4 voltage regulator. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false db8500_esram34_ret: description: Embedded Static RAM (ESRAM) 3 and 4 voltage regulator for retention mode. type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/mfd/stmpe.txt b/Documentation/devicetree/bindings/mfd/stmpe.txt deleted file mode 100644 index d4408a417193..000000000000 --- a/Documentation/devicetree/bindings/mfd/stmpe.txt +++ /dev/null @@ -1,42 +0,0 @@ -* ST Microelectronics STMPE Multi-Functional Device - -STMPE is an MFD device which may expose the following inbuilt devices: gpio, -keypad, touchscreen, adc, pwm, rotator. - -Required properties: - - compatible : "st,stmpe[610|801|811|1600|1601|2401|2403]" - - reg : I2C/SPI address of the device - -Optional properties: - - interrupts : The interrupt outputs from the controller - - interrupt-controller : Marks the device node as an interrupt controller - - wakeup-source : Marks the input device as wakable - - st,autosleep-timeout : Valid entries (ms); 4, 16, 32, 64, 128, 256, 512 and 1024 - - irq-gpio : If present, which GPIO to use for event IRQ - -Optional properties for devices with touch and ADC (STMPE811|STMPE610): - - st,sample-time : ADC conversion time in number of clock. - 0 -> 36 clocks 4 -> 80 clocks (recommended) - 1 -> 44 clocks 5 -> 96 clocks - 2 -> 56 clocks 6 -> 124 clocks - 3 -> 64 clocks - - st,mod-12b : ADC Bit mode - 0 -> 10bit ADC 1 -> 12bit ADC - - st,ref-sel : ADC reference source - 0 -> internal 1 -> external - - st,adc-freq : ADC Clock speed - 0 -> 1.625 MHz 2 || 3 -> 6.5 MHz - 1 -> 3.25 MHz - -Example: - - stmpe1601: stmpe1601@40 { - compatible = "st,stmpe1601"; - reg = <0x40>; - interrupts = <26 0x4>; - interrupt-parent = <&gpio6>; - interrupt-controller; - - wakeup-source; - st,autosleep-timeout = <1024>; - }; diff --git a/Documentation/devicetree/bindings/mfd/syscon.yaml b/Documentation/devicetree/bindings/mfd/syscon.yaml index 8103154bbb52..084b5c2a2a3c 100644 --- a/Documentation/devicetree/bindings/mfd/syscon.yaml +++ b/Documentation/devicetree/bindings/mfd/syscon.yaml @@ -49,6 +49,8 @@ properties: - hisilicon,peri-subctrl - hpe,gxp-sysreg - intel,lgm-syscon + - loongson,ls1b-syscon + - loongson,ls1c-syscon - marvell,armada-3700-usb2-host-misc - mediatek,mt8135-pctl-a-syscfg - mediatek,mt8135-pctl-b-syscfg @@ -61,6 +63,7 @@ properties: - rockchip,px30-qos - rockchip,rk3036-qos - rockchip,rk3066-qos + - rockchip,rk3128-qos - rockchip,rk3228-qos - rockchip,rk3288-qos - rockchip,rk3368-qos @@ -69,6 +72,7 @@ properties: - rockchip,rk3588-qos - rockchip,rv1126-qos - starfive,jh7100-sysmain + - ti,am654-dss-oldi-io-ctrl - const: syscon diff --git a/Documentation/devicetree/bindings/mfd/ti,lp87524-q1.yaml b/Documentation/devicetree/bindings/mfd/ti,lp87524-q1.yaml index f6cac4b1079c..ae149eb8593d 100644 --- a/Documentation/devicetree/bindings/mfd/ti,lp87524-q1.yaml +++ b/Documentation/devicetree/bindings/mfd/ti,lp87524-q1.yaml @@ -37,6 +37,7 @@ properties: "^buck[0123]$": type: object $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false required: - buck0 diff --git a/Documentation/devicetree/bindings/mfd/ti,lp87561-q1.yaml b/Documentation/devicetree/bindings/mfd/ti,lp87561-q1.yaml index dc5a29b5ef7d..5167d6eb904a 100644 --- a/Documentation/devicetree/bindings/mfd/ti,lp87561-q1.yaml +++ b/Documentation/devicetree/bindings/mfd/ti,lp87561-q1.yaml @@ -41,6 +41,7 @@ properties: buck3210: type: object $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false required: - buck3210 diff --git a/Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml b/Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml index 012d25111054..eca430edf608 100644 --- a/Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml +++ b/Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml @@ -47,6 +47,7 @@ properties: "^buck(10|23)$": type: object $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false required: - buck10 diff --git a/Documentation/devicetree/bindings/mfd/ti,twl.yaml b/Documentation/devicetree/bindings/mfd/ti,twl.yaml new file mode 100644 index 000000000000..c04d57ba22b4 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/ti,twl.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/ti,twl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments TWL family + +maintainers: + - Andreas Kemnade <andreas@kemnade.info> + +description: | + The TWLs are Integrated Power Management Chips. + Some version might contain much more analog function like + USB transceiver or Audio amplifier. + These chips are connected to an i2c bus. + +properties: + compatible: + description: + TWL4030 for integrated power-management/audio CODEC device used in OMAP3 + based boards + TWL6030/32 for integrated power-management used in OMAP4 based boards + enum: + - ti,twl4030 + - ti,twl6030 + - ti,twl6032 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + "#interrupt-cells": + const: 1 + + "#clock-cells": + const: 1 + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + - interrupt-controller + - "#interrupt-cells" + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@48 { + compatible = "ti,twl6030"; + reg = <0x48>; + interrupts = <39>; /* IRQ_SYS_1N cascaded to gic */ + interrupt-controller; + #interrupt-cells = <1>; + interrupt-parent = <&gic>; + }; + }; + diff --git a/Documentation/devicetree/bindings/mfd/twl-family.txt b/Documentation/devicetree/bindings/mfd/twl-family.txt deleted file mode 100644 index c2f9302965de..000000000000 --- a/Documentation/devicetree/bindings/mfd/twl-family.txt +++ /dev/null @@ -1,46 +0,0 @@ -Texas Instruments TWL family - -The TWLs are Integrated Power Management Chips. -Some version might contain much more analog function like -USB transceiver or Audio amplifier. -These chips are connected to an i2c bus. - - -Required properties: -- compatible : Must be "ti,twl4030"; - For Integrated power-management/audio CODEC device used in OMAP3 - based boards -- compatible : Must be "ti,twl6030"; - For Integrated power-management used in OMAP4 based boards -- interrupts : This i2c device has an IRQ line connected to the main SoC -- interrupt-controller : Since the twl support several interrupts internally, - it is considered as an interrupt controller cascaded to the SoC one. -- #interrupt-cells = <1>; - -Optional node: -- Child nodes contain in the twl. The twl family is made of several variants - that support a different number of features. - The children nodes will thus depend of the capability of the variant. - - -Example: -/* - * Integrated Power Management Chip - * https://www.ti.com/lit/ds/symlink/twl6030.pdf - */ -twl@48 { - compatible = "ti,twl6030"; - reg = <0x48>; - interrupts = <39>; /* IRQ_SYS_1N cascaded to gic */ - interrupt-controller; - #interrupt-cells = <1>; - interrupt-parent = <&gic>; - #address-cells = <1>; - #size-cells = <0>; - - twl_rtc { - compatible = "ti,twl_rtc"; - interrupts = <11>; - reg = <0>; - }; -}; diff --git a/Documentation/devicetree/bindings/mfd/x-powers,axp152.yaml b/Documentation/devicetree/bindings/mfd/x-powers,axp152.yaml index 9ad55746133b..06f1779835a1 100644 --- a/Documentation/devicetree/bindings/mfd/x-powers,axp152.yaml +++ b/Documentation/devicetree/bindings/mfd/x-powers,axp152.yaml @@ -67,7 +67,10 @@ allOf: properties: compatible: contains: - const: x-powers,axp305 + enum: + - x-powers,axp15060 + - x-powers,axp305 + - x-powers,axp313a then: required: diff --git a/Documentation/devicetree/bindings/mips/loongson/ls2k-reset.yaml b/Documentation/devicetree/bindings/mips/loongson/ls2k-reset.yaml index 20b5836efd90..358ac8cd4d1d 100644 --- a/Documentation/devicetree/bindings/mips/loongson/ls2k-reset.yaml +++ b/Documentation/devicetree/bindings/mips/loongson/ls2k-reset.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: "http://devicetree.org/schemas/mips/loongson/ls2k-reset.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/mips/loongson/ls2k-reset.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Loongson 2K1000 PM Controller diff --git a/Documentation/devicetree/bindings/mips/loongson/rs780e-acpi.yaml b/Documentation/devicetree/bindings/mips/loongson/rs780e-acpi.yaml index 7c0f9022202c..3e3a3705e879 100644 --- a/Documentation/devicetree/bindings/mips/loongson/rs780e-acpi.yaml +++ b/Documentation/devicetree/bindings/mips/loongson/rs780e-acpi.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: "http://devicetree.org/schemas/mips/loongson/rs780e-acpi.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/mips/loongson/rs780e-acpi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Loongson RS780E PCH ACPI Controller diff --git a/Documentation/devicetree/bindings/misc/intel,ixp4xx-ahb-queue-manager.yaml b/Documentation/devicetree/bindings/misc/intel,ixp4xx-ahb-queue-manager.yaml index 38ab0499102d..36a9dbdf3f03 100644 --- a/Documentation/devicetree/bindings/misc/intel,ixp4xx-ahb-queue-manager.yaml +++ b/Documentation/devicetree/bindings/misc/intel,ixp4xx-ahb-queue-manager.yaml @@ -2,8 +2,8 @@ # Copyright 2019 Linaro Ltd. %YAML 1.2 --- -$id: "http://devicetree.org/schemas/misc/intel,ixp4xx-ahb-queue-manager.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/misc/intel,ixp4xx-ahb-queue-manager.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Intel IXP4xx AHB Queue Manager diff --git a/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml b/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml index a6c19a6cc99e..3e99801f77d2 100644 --- a/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml +++ b/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml @@ -160,6 +160,12 @@ properties: description: The MIO bank number in which the command and data lines are configured. + iommus: + maxItems: 1 + + power-domains: + maxItems: 1 + dependencies: '#clock-cells': [ clock-output-names ] diff --git a/Documentation/devicetree/bindings/mmc/marvell,xenon-sdhci.yaml b/Documentation/devicetree/bindings/mmc/marvell,xenon-sdhci.yaml index 3ee758886558..3a8e74894ae0 100644 --- a/Documentation/devicetree/bindings/mmc/marvell,xenon-sdhci.yaml +++ b/Documentation/devicetree/bindings/mmc/marvell,xenon-sdhci.yaml @@ -71,8 +71,8 @@ properties: marvell,xenon-phy-type: $ref: /schemas/types.yaml#/definitions/string enum: - - "emmc 5.1 phy" - - "emmc 5.0 phy" + - emmc 5.1 phy + - emmc 5.0 phy description: | Xenon support multiple types of PHYs. To select eMMC 5.1 PHY, set: marvell,xenon-phy-type = "emmc 5.1 phy" eMMC 5.1 PHY is the default diff --git a/Documentation/devicetree/bindings/mmc/mmc-controller.yaml b/Documentation/devicetree/bindings/mmc/mmc-controller.yaml index 86c73fd825fd..58ae298cd2fc 100644 --- a/Documentation/devicetree/bindings/mmc/mmc-controller.yaml +++ b/Documentation/devicetree/bindings/mmc/mmc-controller.yaml @@ -269,7 +269,7 @@ properties: post-power-on-delay-ms: description: It was invented for MMC pwrseq-simple which could be referred to - mmc-pwrseq-simple.txt. But now it\'s reused as a tunable delay + mmc-pwrseq-simple.yaml. But now it\'s reused as a tunable delay waiting for I/O signalling and card power supply to be stable, regardless of whether pwrseq-simple is used. Default to 10ms if no available. diff --git a/Documentation/devicetree/bindings/mmc/mtk-sd.yaml b/Documentation/devicetree/bindings/mmc/mtk-sd.yaml index 46eefdd19a2c..3fffa467e4e1 100644 --- a/Documentation/devicetree/bindings/mmc/mtk-sd.yaml +++ b/Documentation/devicetree/bindings/mmc/mtk-sd.yaml @@ -91,16 +91,6 @@ properties: should switch dat1 pin to GPIO mode. maxItems: 1 - assigned-clocks: - description: - PLL of the source clock. - maxItems: 1 - - assigned-clock-parents: - description: - parent of source clock, used for HS400 mode to get 400Mhz source clock. - maxItems: 1 - hs400-ds-delay: $ref: /schemas/types.yaml#/definitions/uint32 description: diff --git a/Documentation/devicetree/bindings/mmc/npcm,sdhci.yaml b/Documentation/devicetree/bindings/mmc/npcm,sdhci.yaml new file mode 100644 index 000000000000..196fdbfa16ed --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/npcm,sdhci.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/npcm,sdhci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NPCM SDHCI Controller + +maintainers: + - Tomer Maimon <tmaimon77@gmail.com> + +allOf: + - $ref: mmc-controller.yaml# + +properties: + compatible: + enum: + - nuvoton,npcm750-sdhci + - nuvoton,npcm845-sdhci + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +unevaluatedProperties: false + +examples: + - | + mmc@f0840000 { + compatible = "nuvoton,npcm750-sdhci"; + reg = <0xf0840000 0x200>; + interrupts = <0 27 4>; + clocks = <&clk 4>; + }; diff --git a/Documentation/devicetree/bindings/mmc/pxa-mmc.txt b/Documentation/devicetree/bindings/mmc/pxa-mmc.txt index 5f5c2bec2b8c..66a78eae4dc9 100644 --- a/Documentation/devicetree/bindings/mmc/pxa-mmc.txt +++ b/Documentation/devicetree/bindings/mmc/pxa-mmc.txt @@ -9,7 +9,7 @@ Required properties: Optional properties: - marvell,detect-delay-ms: sets the detection delay timeout in ms. -In addition to the properties described in this docuent, the details +In addition to the properties described in this document, the details described in mmc.txt are supported. Examples: diff --git a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml index 7756a8687eaf..94e228787630 100644 --- a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml +++ b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml @@ -59,6 +59,7 @@ properties: - renesas,sdhi-r9a07g043 # RZ/G2UL - renesas,sdhi-r9a07g044 # RZ/G2{L,LC} - renesas,sdhi-r9a07g054 # RZ/V2L + - renesas,sdhi-r9a08g045 # RZ/G3S - renesas,sdhi-r9a09g011 # RZ/V2M - const: renesas,rcar-gen3-sdhi # R-Car Gen3 or RZ/G2 - items: @@ -122,6 +123,7 @@ allOf: - renesas,sdhi-r9a07g043 - renesas,sdhi-r9a07g044 - renesas,sdhi-r9a07g054 + - renesas,sdhi-r9a08g045 - renesas,sdhi-r9a09g011 then: properties: diff --git a/Documentation/devicetree/bindings/mmc/sdhci-atmel.txt b/Documentation/devicetree/bindings/mmc/sdhci-atmel.txt index 69edfd4d3922..a9fb0a91245f 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-atmel.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-atmel.txt @@ -5,11 +5,13 @@ Documentation/devicetree/bindings/mmc/mmc.txt and the properties used by the sdhci-of-at91 driver. Required properties: -- compatible: Must be "atmel,sama5d2-sdhci" or "microchip,sam9x60-sdhci". +- compatible: Must be "atmel,sama5d2-sdhci" or "microchip,sam9x60-sdhci" + or "microchip,sam9x7-sdhci", "microchip,sam9x60-sdhci". - clocks: Phandlers to the clocks. - clock-names: Must be "hclock", "multclk", "baseclk" for "atmel,sama5d2-sdhci". Must be "hclock", "multclk" for "microchip,sam9x60-sdhci". + Must be "hclock", "multclk" for "microchip,sam9x7-sdhci". Optional properties: - assigned-clocks: The same with "multclk". diff --git a/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml b/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml index 6da28e630577..86fae733d9a0 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml +++ b/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml @@ -58,6 +58,7 @@ properties: - qcom,sm8350-sdhci - qcom,sm8450-sdhci - qcom,sm8550-sdhci + - qcom,sm8650-sdhci - const: qcom,sdhci-msm-v5 # for sdcc version 5.0 reg: @@ -69,7 +70,7 @@ properties: maxItems: 4 clocks: - minItems: 3 + minItems: 2 items: - description: Main peripheral bus clock, PCLK/HCLK - AHB Bus clock - description: SDC MMC clock, MCLK @@ -85,10 +86,10 @@ properties: - const: iface - const: core - const: xo - - const: ice - - const: bus - - const: cal - - const: sleep + - enum: [ice, bus, cal, sleep] + - enum: [ice, bus, cal, sleep] + - enum: [ice, bus, cal, sleep] + - enum: [ice, bus, cal, sleep] dma-coherent: true @@ -215,7 +216,7 @@ examples: #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/clock/qcom,gcc-sm8250.h> #include <dt-bindings/clock/qcom,rpmh.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> sdhc_2: mmc@8804000 { compatible = "qcom,sm8250-sdhci", "qcom,sdhci-msm-v5"; @@ -232,7 +233,7 @@ examples: iommus = <&apps_smmu 0x4a0 0x0>; qcom,dll-config = <0x0007642c>; qcom,ddr-config = <0x80040868>; - power-domains = <&rpmhpd SM8250_CX>; + power-domains = <&rpmhpd RPMHPD_CX>; operating-points-v2 = <&sdhc2_opp_table>; diff --git a/Documentation/devicetree/bindings/mmc/starfive,jh7110-mmc.yaml b/Documentation/devicetree/bindings/mmc/starfive,jh7110-mmc.yaml index 51e1b04e799f..553a75195c2e 100644 --- a/Documentation/devicetree/bindings/mmc/starfive,jh7110-mmc.yaml +++ b/Documentation/devicetree/bindings/mmc/starfive,jh7110-mmc.yaml @@ -55,7 +55,6 @@ required: - clocks - clock-names - interrupts - - starfive,sysreg unevaluatedProperties: false @@ -73,5 +72,4 @@ examples: fifo-depth = <32>; fifo-watermark-aligned; data-addr = <0>; - starfive,sysreg = <&sys_syscon 0x14 0x1a 0x7c000000>; }; diff --git a/Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt b/Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt index 57d077c0b7c1..7a0e9dcdc444 100644 --- a/Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt +++ b/Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt @@ -95,7 +95,7 @@ while in suspend. | card | -- CIRQ --> | hsmmc | -- IRQ --> | CPU | ------ ------- ----- -In suspend the fclk is off and the module is disfunctional. Even register reads +In suspend the fclk is off and the module is dysfunctional. Even register reads will fail. A small logic in the host will request fclk restore, when an external event is detected. Once the clock is restored, the host detects the event normally. Since am33xx doesn't have this line it never wakes from diff --git a/Documentation/devicetree/bindings/mtd/amlogic,meson-nand.yaml b/Documentation/devicetree/bindings/mtd/amlogic,meson-nand.yaml index 787ef488dd5b..57b6957c8415 100644 --- a/Documentation/devicetree/bindings/mtd/amlogic,meson-nand.yaml +++ b/Documentation/devicetree/bindings/mtd/amlogic,meson-nand.yaml @@ -50,7 +50,7 @@ patternProperties: const: hw nand-ecc-step-size: - const: 1024 + enum: [512, 1024] nand-ecc-strength: enum: [8, 16, 24, 30, 40, 50, 60] @@ -66,6 +66,10 @@ patternProperties: unevaluatedProperties: false + dependencies: + nand-ecc-strength: [nand-ecc-step-size] + nand-ecc-step-size: [nand-ecc-strength] + required: - compatible diff --git a/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml b/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml index 89959e5c47ba..58f0cea160ef 100644 --- a/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml +++ b/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml @@ -43,8 +43,10 @@ properties: - const: jedec,spi-nor - const: jedec,spi-nor description: - Must also include "jedec,spi-nor" for any SPI NOR flash that can be - identified by the JEDEC READ ID opcode (0x9F). + SPI NOR flashes compatible with the JEDEC SFDP standard or which may be + identified with the READ ID opcode (0x9F) do not deserve a specific + compatible. They should instead only be matched against the generic + "jedec,spi-nor" compatible. reg: minItems: 1 @@ -70,6 +72,21 @@ properties: be used on such systems, to denote the absence of a reliable reset mechanism. + no-wp: + type: boolean + description: + The status register write disable (SRWD) bit in status register, combined + with the WP# signal, provides hardware data protection for the device. When + the SRWD bit is set to 1, and the WP# signal is either driven LOW or hard + strapped to LOW, the status register nonvolatile bits become read-only and + the WRITE STATUS REGISTER operation will not execute. The only way to exit + this hardware-protected mode is to drive WP# HIGH. If the WP# signal of the + flash device is not connected or is wrongly tied to GND (that includes internal + pull-downs) then status register permanently becomes read-only as the SRWD bit + cannot be reset. This boolean flag can be used on such systems to avoid setting + the SRWD bit while writing the status register. WP# signal hard strapped to GND + can be a valid use case. + reset-gpios: description: A GPIO line connected to the RESET (active low) signal of the device. diff --git a/Documentation/devicetree/bindings/mtd/marvell,nand-controller.yaml b/Documentation/devicetree/bindings/mtd/marvell,nand-controller.yaml index a10729bb1840..1ecea848e8b9 100644 --- a/Documentation/devicetree/bindings/mtd/marvell,nand-controller.yaml +++ b/Documentation/devicetree/bindings/mtd/marvell,nand-controller.yaml @@ -16,6 +16,7 @@ properties: - const: marvell,armada-8k-nand-controller - const: marvell,armada370-nand-controller - enum: + - marvell,ac5-nand-controller - marvell,armada370-nand-controller - marvell,pxa3xx-nand-controller - description: legacy bindings diff --git a/Documentation/devicetree/bindings/mtd/microchip,mchp48l640.yaml b/Documentation/devicetree/bindings/mtd/microchip,mchp48l640.yaml index 00882892f47e..0ff32bd00bf6 100644 --- a/Documentation/devicetree/bindings/mtd/microchip,mchp48l640.yaml +++ b/Documentation/devicetree/bindings/mtd/microchip,mchp48l640.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: "http://devicetree.org/schemas/mtd/microchip,mchp48l640.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/mtd/microchip,mchp48l640.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Microchip 48l640 (and similar) serial EERAM diff --git a/Documentation/devicetree/bindings/mtd/nand-controller.yaml b/Documentation/devicetree/bindings/mtd/nand-controller.yaml index 83a4fe4cc29d..28167c0cf271 100644 --- a/Documentation/devicetree/bindings/mtd/nand-controller.yaml +++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml @@ -1,4 +1,4 @@ -# SPDX-License-Identifier: GPL-2.0 +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- $id: http://devicetree.org/schemas/mtd/nand-controller.yaml# diff --git a/Documentation/devicetree/bindings/mtd/oxnas-nand.txt b/Documentation/devicetree/bindings/mtd/oxnas-nand.txt deleted file mode 100644 index 2ba07fc8b79c..000000000000 --- a/Documentation/devicetree/bindings/mtd/oxnas-nand.txt +++ /dev/null @@ -1,41 +0,0 @@ -* Oxford Semiconductor OXNAS NAND Controller - -Please refer to nand-controller.yaml for generic information regarding MTD NAND bindings. - -Required properties: - - compatible: "oxsemi,ox820-nand" - - reg: Base address and length for NAND mapped memory. - -Optional Properties: - - clocks: phandle to the NAND gate clock if needed. - - resets: phandle to the NAND reset control if needed. - -Example: - -nandc: nand-controller@41000000 { - compatible = "oxsemi,ox820-nand"; - reg = <0x41000000 0x100000>; - clocks = <&stdclk CLK_820_NAND>; - resets = <&reset RESET_NAND>; - #address-cells = <1>; - #size-cells = <0>; - - nand@0 { - reg = <0>; - #address-cells = <1>; - #size-cells = <1>; - nand-ecc-mode = "soft"; - nand-ecc-algo = "hamming"; - - partition@0 { - label = "boot"; - reg = <0x00000000 0x00e00000>; - read-only; - }; - - partition@e00000 { - label = "ubi"; - reg = <0x00e00000 0x07200000>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/mtd/partitions/seama.yaml b/Documentation/devicetree/bindings/mtd/partitions/seama.yaml new file mode 100644 index 000000000000..4c1cbf43e81a --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/partitions/seama.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/partitions/seama.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Seattle Image Partitions + +description: The SEAttle iMAge (SEAMA) partition is a type of partition + used for NAND flash devices. This type of flash image is found in some + D-Link routers such as DIR-645, DIR-842, DIR-859, DIR-860L, DIR-885L, + DIR890L and DCH-M225, as well as in WD and NEC routers on the ath79 + (MIPS), Broadcom BCM53xx, and RAMIPS platforms. This partition type + does not have children defined in the device tree, they need to be + detected by software. + +allOf: + - $ref: partition.yaml# + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +properties: + compatible: + const: seama + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + partition@0 { + compatible = "seama"; + reg = <0x0 0x800000>; + label = "firmware"; + }; + }; diff --git a/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml b/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml index 4bfac9186886..7fe0352dff0f 100644 --- a/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml +++ b/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml @@ -158,6 +158,8 @@ allOf: patternProperties: "^ethernet-phy@[0-9a-f]$": type: object + $ref: ethernet-phy.yaml# + unevaluatedProperties: false description: Integrated PHY node diff --git a/Documentation/devicetree/bindings/net/bluetooth/qualcomm-bluetooth.yaml b/Documentation/devicetree/bindings/net/bluetooth/qualcomm-bluetooth.yaml index 56cbb42b5aea..eba2f3026ab0 100644 --- a/Documentation/devicetree/bindings/net/bluetooth/qualcomm-bluetooth.yaml +++ b/Documentation/devicetree/bindings/net/bluetooth/qualcomm-bluetooth.yaml @@ -19,12 +19,14 @@ properties: - qcom,qca2066-bt - qcom,qca6174-bt - qcom,qca9377-bt + - qcom,wcn3988-bt - qcom,wcn3990-bt - qcom,wcn3991-bt - qcom,wcn3998-bt - qcom,qca6390-bt - qcom,wcn6750-bt - qcom,wcn6855-bt + - qcom,wcn7850-bt enable-gpios: maxItems: 1 @@ -57,6 +59,9 @@ properties: vddaon-supply: description: VDD_AON supply regulator handle + vdddig-supply: + description: VDD_DIG supply regulator handle + vddbtcxmx-supply: description: VDD_BT_CXMX supply regulator handle @@ -72,6 +77,9 @@ properties: vddrfa1p2-supply: description: VDD_RFA_1P2 supply regulator handle + vddrfa1p9-supply: + description: VDD_RFA_1P9 supply regulator handle + vddrfa2p2-supply: description: VDD_RFA_2P2 supply regulator handle @@ -111,6 +119,7 @@ allOf: compatible: contains: enum: + - qcom,wcn3988-bt - qcom,wcn3990-bt - qcom,wcn3991-bt - qcom,wcn3998-bt @@ -155,6 +164,22 @@ allOf: - vddrfa0p8-supply - vddrfa1p2-supply - vddrfa1p7-supply + - if: + properties: + compatible: + contains: + enum: + - qcom,wcn7850-bt + then: + required: + - enable-gpios + - swctrl-gpios + - vddio-supply + - vddaon-supply + - vdddig-supply + - vddrfa0p8-supply + - vddrfa1p2-supply + - vddrfa1p9-supply examples: - | diff --git a/Documentation/devicetree/bindings/net/brcm,asp-v2.0.yaml b/Documentation/devicetree/bindings/net/brcm,asp-v2.0.yaml new file mode 100644 index 000000000000..75d8138298fb --- /dev/null +++ b/Documentation/devicetree/bindings/net/brcm,asp-v2.0.yaml @@ -0,0 +1,155 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/brcm,asp-v2.0.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom ASP 2.0 Ethernet controller + +maintainers: + - Justin Chen <justin.chen@broadcom.com> + - Florian Fainelli <florian.fainelli@broadcom.com> + +description: Broadcom Ethernet controller first introduced with 72165 + +properties: + compatible: + oneOf: + - items: + - enum: + - brcm,bcm74165-asp + - const: brcm,asp-v2.1 + - items: + - enum: + - brcm,bcm72165-asp + - const: brcm,asp-v2.0 + + "#address-cells": + const: 1 + "#size-cells": + const: 1 + + reg: + maxItems: 1 + + ranges: true + + interrupts: + minItems: 1 + items: + - description: RX/TX interrupt + - description: Port 0 Wake-on-LAN + - description: Port 1 Wake-on-LAN + + clocks: + maxItems: 1 + + ethernet-ports: + type: object + properties: + "#address-cells": + const: 1 + "#size-cells": + const: 0 + + patternProperties: + "^port@[0-9a-f]+$": + type: object + + $ref: ethernet-controller.yaml# + + unevaluatedProperties: false + + properties: + reg: + maxItems: 1 + description: Port number + + brcm,channel: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + ASP Channel Number + + The depacketizer channel that consumes packets from + the unimac/port. + + required: + - reg + - brcm,channel + + additionalProperties: false + +patternProperties: + "^mdio@[0-9a-f]+$": + type: object + $ref: brcm,unimac-mdio.yaml + + description: + ASP internal UniMAC MDIO bus + +required: + - compatible + - reg + - interrupts + - clocks + - ranges + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + ethernet@9c00000 { + compatible = "brcm,bcm72165-asp", "brcm,asp-v2.0"; + reg = <0x9c00000 0x1fff14>; + interrupts = <GIC_SPI 51 IRQ_TYPE_LEVEL_HIGH>; + ranges = <0x0 0x9c00000 0x1fff14>; + clocks = <&scmi 14>; + #address-cells = <1>; + #size-cells = <1>; + + mdio@c614 { + compatible = "brcm,asp-v2.0-mdio"; + reg = <0xc614 0x8>; + reg-names = "mdio"; + #address-cells = <1>; + #size-cells = <0>; + + phy0: ethernet-phy@1 { + reg = <1>; + }; + }; + + mdio@ce14 { + compatible = "brcm,asp-v2.0-mdio"; + reg = <0xce14 0x8>; + reg-names = "mdio"; + #address-cells = <1>; + #size-cells = <0>; + + phy1: ethernet-phy@1 { + reg = <1>; + }; + }; + + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + brcm,channel = <8>; + phy-mode = "rgmii"; + phy-handle = <&phy0>; + }; + + port@1 { + reg = <1>; + brcm,channel = <9>; + phy-mode = "rgmii"; + phy-handle = <&phy1>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt b/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt index d0935d2afef8..284cddb3118e 100644 --- a/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt +++ b/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt @@ -1,4 +1,4 @@ -* Broadcom Starfighter 2 integrated swich +* Broadcom Starfighter 2 integrated switch See dsa/brcm,bcm7445-switch-v4.0.yaml for the documentation. diff --git a/Documentation/devicetree/bindings/net/brcm,unimac-mdio.yaml b/Documentation/devicetree/bindings/net/brcm,unimac-mdio.yaml index 0be426ee1e44..6684810fcbf0 100644 --- a/Documentation/devicetree/bindings/net/brcm,unimac-mdio.yaml +++ b/Documentation/devicetree/bindings/net/brcm,unimac-mdio.yaml @@ -22,6 +22,8 @@ properties: - brcm,genet-mdio-v3 - brcm,genet-mdio-v4 - brcm,genet-mdio-v5 + - brcm,asp-v2.0-mdio + - brcm,asp-v2.1-mdio - brcm,unimac-mdio reg: diff --git a/Documentation/devicetree/bindings/net/can/allwinner,sun4i-a10-can.yaml b/Documentation/devicetree/bindings/net/can/allwinner,sun4i-a10-can.yaml index 9c494957a07a..e42ea28d6ab4 100644 --- a/Documentation/devicetree/bindings/net/can/allwinner,sun4i-a10-can.yaml +++ b/Documentation/devicetree/bindings/net/can/allwinner,sun4i-a10-can.yaml @@ -21,6 +21,7 @@ properties: - const: allwinner,sun4i-a10-can - const: allwinner,sun4i-a10-can - const: allwinner,sun8i-r40-can + - const: allwinner,sun20i-d1-can reg: maxItems: 1 @@ -37,8 +38,9 @@ properties: if: properties: compatible: - contains: - const: allwinner,sun8i-r40-can + enum: + - allwinner,sun8i-r40-can + - allwinner,sun20i-d1-can then: required: diff --git a/Documentation/devicetree/bindings/net/can/bosch,m_can.yaml b/Documentation/devicetree/bindings/net/can/bosch,m_can.yaml index 67879aab623b..f9ffb963d6b1 100644 --- a/Documentation/devicetree/bindings/net/can/bosch,m_can.yaml +++ b/Documentation/devicetree/bindings/net/can/bosch,m_can.yaml @@ -122,16 +122,15 @@ required: - compatible - reg - reg-names - - interrupts - - interrupt-names - clocks - clock-names - bosch,mram-cfg -additionalProperties: false +unevaluatedProperties: false examples: - | + // Example with interrupts #include <dt-bindings/clock/imx6sx-clock.h> can@20e8000 { compatible = "bosch,m_can"; @@ -149,4 +148,21 @@ examples: }; }; + - | + // Example with timer polling + #include <dt-bindings/clock/imx6sx-clock.h> + can@20e8000 { + compatible = "bosch,m_can"; + reg = <0x020e8000 0x4000>, <0x02298000 0x4000>; + reg-names = "m_can", "message_ram"; + clocks = <&clks IMX6SX_CLK_CANFD>, + <&clks IMX6SX_CLK_CANFD>; + clock-names = "hclk", "cclk"; + bosch,mram-cfg = <0x0 0 0 32 0 0 0 1>; + + can-transceiver { + max-bitrate = <5000000>; + }; + }; + ... diff --git a/Documentation/devicetree/bindings/net/can/cc770.txt b/Documentation/devicetree/bindings/net/can/cc770.txt index 77027bf6460a..042200cf4419 100644 --- a/Documentation/devicetree/bindings/net/can/cc770.txt +++ b/Documentation/devicetree/bindings/net/can/cc770.txt @@ -26,7 +26,7 @@ Optional properties: will be disabled. - bosch,slew-rate : slew rate of the CLKOUT signal. If not specified, - a resonable value will be calculated. + a reasonable value will be calculated. - bosch,disconnect-rx0-input : see data sheet. diff --git a/Documentation/devicetree/bindings/net/can/tcan4x5x.txt b/Documentation/devicetree/bindings/net/can/tcan4x5x.txt index e3501bfa22e9..170e23f0610d 100644 --- a/Documentation/devicetree/bindings/net/can/tcan4x5x.txt +++ b/Documentation/devicetree/bindings/net/can/tcan4x5x.txt @@ -4,7 +4,10 @@ Texas Instruments TCAN4x5x CAN Controller This file provides device node information for the TCAN4x5x interface contains. Required properties: - - compatible: "ti,tcan4x5x" + - compatible: + "ti,tcan4552", "ti,tcan4x5x" + "ti,tcan4553", "ti,tcan4x5x" or + "ti,tcan4x5x" - reg: 0 - #address-cells: 1 - #size-cells: 0 @@ -21,8 +24,10 @@ Optional properties: - reset-gpios: Hardwired output GPIO. If not defined then software reset. - device-state-gpios: Input GPIO that indicates if the device is in - a sleep state or if the device is active. - - device-wake-gpios: Wake up GPIO to wake up the TCAN device. + a sleep state or if the device is active. Not + available with tcan4552/4553. + - device-wake-gpios: Wake up GPIO to wake up the TCAN device. Not + available with tcan4552/4553. Example: tcan4x5x: tcan4x5x@0 { diff --git a/Documentation/devicetree/bindings/net/can/xilinx,can.yaml b/Documentation/devicetree/bindings/net/can/xilinx,can.yaml index 897d2cbda45b..64d57c343e6f 100644 --- a/Documentation/devicetree/bindings/net/can/xilinx,can.yaml +++ b/Documentation/devicetree/bindings/net/can/xilinx,can.yaml @@ -46,6 +46,9 @@ properties: $ref: /schemas/types.yaml#/definitions/uint32 description: CAN Tx mailbox buffer count (CAN FD) + resets: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/net/davicom,dm9000.yaml b/Documentation/devicetree/bindings/net/davicom,dm9000.yaml new file mode 100644 index 000000000000..66a7c6eec767 --- /dev/null +++ b/Documentation/devicetree/bindings/net/davicom,dm9000.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/davicom,dm9000.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Davicom DM9000 Fast Ethernet Controller + +maintainers: + - Paul Cercueil <paul@crapouillou.net> + +properties: + compatible: + const: davicom,dm9000 + + reg: + items: + - description: Address registers + - description: Data registers + + interrupts: + maxItems: 1 + + davicom,no-eeprom: + type: boolean + description: Configuration EEPROM is not available + + davicom,ext-phy: + type: boolean + description: Use external PHY + + reset-gpios: + maxItems: 1 + + vcc-supply: true + +required: + - compatible + - reg + - interrupts + +allOf: + - $ref: /schemas/memory-controllers/mc-peripheral-props.yaml# + - $ref: /schemas/net/ethernet-controller.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + ethernet@a8000000 { + compatible = "davicom,dm9000"; + reg = <0xa8000000 0x2>, <0xa8000002 0x2>; + interrupt-parent = <&gph1>; + interrupts = <1 IRQ_TYPE_LEVEL_HIGH>; + local-mac-address = [00 00 de ad be ef]; + davicom,no-eeprom; + }; diff --git a/Documentation/devicetree/bindings/net/davicom-dm9000.txt b/Documentation/devicetree/bindings/net/davicom-dm9000.txt deleted file mode 100644 index 64c159e9cbf7..000000000000 --- a/Documentation/devicetree/bindings/net/davicom-dm9000.txt +++ /dev/null @@ -1,27 +0,0 @@ -Davicom DM9000 Fast Ethernet controller - -Required properties: -- compatible = "davicom,dm9000"; -- reg : physical addresses and sizes of registers, must contain 2 entries: - first entry : address register, - second entry : data register. -- interrupts : interrupt specifier specific to interrupt controller - -Optional properties: -- davicom,no-eeprom : Configuration EEPROM is not available -- davicom,ext-phy : Use external PHY -- reset-gpios : phandle of gpio that will be used to reset chip during probe -- vcc-supply : phandle of regulator that will be used to enable power to chip - -Example: - - ethernet@18000000 { - compatible = "davicom,dm9000"; - reg = <0x18000000 0x2 0x18000004 0x2>; - interrupt-parent = <&gpn>; - interrupts = <7 4>; - local-mac-address = [00 00 de ad be ef]; - davicom,no-eeprom; - reset-gpios = <&gpf 12 GPIO_ACTIVE_LOW>; - vcc-supply = <ð0_power>; - }; diff --git a/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml b/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml index c745407f2f68..f21bdd0f408d 100644 --- a/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml +++ b/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/net/dsa/brcm,sf2.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Broadcom Starfighter 2 integrated swich +title: Broadcom Starfighter 2 integrated switch maintainers: - Florian Fainelli <f.fainelli@gmail.com> @@ -78,6 +78,7 @@ properties: ports: type: object + additionalProperties: true patternProperties: '^port@[0-9a-f]$': diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.yaml b/Documentation/devicetree/bindings/net/dsa/dsa.yaml index 8d971813bab6..6107189d276a 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa.yaml +++ b/Documentation/devicetree/bindings/net/dsa/dsa.yaml @@ -36,21 +36,12 @@ additionalProperties: true $defs: ethernet-ports: description: A DSA switch without any extra port properties - $ref: '#/' + $ref: '#' patternProperties: "^(ethernet-)?ports$": - type: object - additionalProperties: false - - properties: - '#address-cells': - const: 1 - '#size-cells': - const: 0 - patternProperties: - "^(ethernet-)?port@[0-9]+$": + "^(ethernet-)?port@[0-9a-f]+$": description: Ethernet switch ports $ref: dsa-port.yaml# unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/net/dsa/marvell.txt b/Documentation/devicetree/bindings/net/dsa/marvell.txt index 33726134f5c9..6ec0c181b6db 100644 --- a/Documentation/devicetree/bindings/net/dsa/marvell.txt +++ b/Documentation/devicetree/bindings/net/dsa/marvell.txt @@ -20,7 +20,7 @@ which is at a different MDIO base address in different switch families. 6171, 6172, 6175, 6176, 6185, 6240, 6320, 6321, 6341, 6350, 6351, 6352 - "marvell,mv88e6190" : Switch has base address 0x00. Use with models: - 6163, 6190, 6190X, 6191, 6290, 6390, 6390X + 6190, 6190X, 6191, 6290, 6361, 6390, 6390X - "marvell,mv88e6250" : Switch has base address 0x08 or 0x18. Use with model: 6220, 6250 diff --git a/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml b/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml index e532c6b795f4..1c2444121e60 100644 --- a/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml +++ b/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml @@ -60,7 +60,7 @@ description: | Check out example 6. - - Port 5 can be wired to an external phy. Port 5 becomes a DSA slave. + - Port 5 can be wired to an external phy. Port 5 becomes a DSA user port. For the multi-chip module MT7530, the external phy must be wired TX to TX to gmac1 of the SoC for this to work. Ubiquiti EdgeRouter X SFP is wired @@ -154,10 +154,12 @@ properties: patternProperties: "^(ethernet-)?ports$": type: object + additionalProperties: true patternProperties: - "^(ethernet-)?port@[0-9]+$": + "^(ethernet-)?port@[0-6]$": type: object + additionalProperties: true properties: reg: @@ -184,7 +186,7 @@ $defs: patternProperties: "^(ethernet-)?ports$": patternProperties: - "^(ethernet-)?port@[0-9]+$": + "^(ethernet-)?port@[0-6]$": if: required: [ ethernet ] then: @@ -210,7 +212,7 @@ $defs: patternProperties: "^(ethernet-)?ports$": patternProperties: - "^(ethernet-)?port@[0-9]+$": + "^(ethernet-)?port@[0-6]$": if: required: [ ethernet ] then: diff --git a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml index e51be1ac0362..b3029c64d0d5 100644 --- a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml +++ b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml @@ -38,6 +38,8 @@ properties: Should be a gpio specifier for a reset line. maxItems: 1 + wakeup-source: true + microchip,synclko-125: $ref: /schemas/types.yaml#/definitions/flag description: @@ -49,6 +51,29 @@ properties: Set if the output SYNCLKO clock should be disabled. Do not mix with microchip,synclko-125. + microchip,io-drive-strength-microamp: + description: + IO Pad Drive Strength + enum: [8000, 16000] + default: 16000 + + microchip,hi-drive-strength-microamp: + description: + High Speed Drive Strength. Controls drive strength of GMII / RGMII / + MII / RMII (except TX_CLK/REFCLKI, COL and CRS) and CLKO_25_125 lines. + enum: [2000, 4000, 8000, 12000, 16000, 20000, 24000, 28000] + default: 24000 + + microchip,lo-drive-strength-microamp: + description: + Low Speed Drive Strength. Controls drive strength of TX_CLK / REFCLKI, + COL, CRS, LEDs, PME_N, NTRP_N, SDO and SDI/SDA/MDIO lines. + enum: [2000, 4000, 8000, 12000, 16000, 20000, 24000, 28000] + default: 8000 + + interrupts: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml b/Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml index 8d7e878b84dc..9973d64f15a7 100644 --- a/Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml +++ b/Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml @@ -37,8 +37,9 @@ properties: patternProperties: "^(ethernet-)?ports$": + additionalProperties: true patternProperties: - "^(ethernet-)?port@[0-9]+$": + "^(ethernet-)?port@[0-7]$": allOf: - if: properties: diff --git a/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml b/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml index 4d5f5cc6d031..9432565f4f5d 100644 --- a/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml +++ b/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml @@ -43,6 +43,7 @@ properties: # PHY 1. mdios: type: object + additionalProperties: false properties: '#address-cells': @@ -74,8 +75,9 @@ properties: patternProperties: "^(ethernet-)?ports$": + additionalProperties: true patternProperties: - "^(ethernet-)?port@[0-9]+$": + "^(ethernet-)?port@[0-9]$": allOf: - if: properties: diff --git a/Documentation/devicetree/bindings/net/dsa/qca8k.yaml b/Documentation/devicetree/bindings/net/dsa/qca8k.yaml index df64eebebe18..167398ab253a 100644 --- a/Documentation/devicetree/bindings/net/dsa/qca8k.yaml +++ b/Documentation/devicetree/bindings/net/dsa/qca8k.yaml @@ -73,6 +73,7 @@ $ref: dsa.yaml# patternProperties: "^(ethernet-)?ports$": type: object + additionalProperties: true patternProperties: "^(ethernet-)?port@[0-6]$": type: object diff --git a/Documentation/devicetree/bindings/net/dsa/realtek.yaml b/Documentation/devicetree/bindings/net/dsa/realtek.yaml index cfd69c2604ea..cce692f57b08 100644 --- a/Documentation/devicetree/bindings/net/dsa/realtek.yaml +++ b/Documentation/devicetree/bindings/net/dsa/realtek.yaml @@ -68,6 +68,8 @@ properties: interrupt-controller: type: object + additionalProperties: false + description: | This defines an interrupt controller with an IRQ line (typically a GPIO) that will demultiplex and handle the interrupt from the single diff --git a/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml b/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml index 833d2f68daa1..ea285ef3e64f 100644 --- a/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml +++ b/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml @@ -61,17 +61,11 @@ properties: ethernet-ports: type: object - properties: - '#address-cells': - const: 1 - '#size-cells': - const: 0 - + additionalProperties: true patternProperties: "^(ethernet-)?port@[0-4]$": type: object - description: Ethernet switch ports - + additionalProperties: true properties: pcs-handle: maxItems: 1 diff --git a/Documentation/devicetree/bindings/net/engleder,tsnep.yaml b/Documentation/devicetree/bindings/net/engleder,tsnep.yaml index 82a5d7927ca4..34fd24ff6a71 100644 --- a/Documentation/devicetree/bindings/net/engleder,tsnep.yaml +++ b/Documentation/devicetree/bindings/net/engleder,tsnep.yaml @@ -63,6 +63,7 @@ properties: mdio: type: object $ref: mdio.yaml# + unevaluatedProperties: false description: optional node for embedded MDIO controller required: diff --git a/Documentation/devicetree/bindings/net/ethernet-controller.yaml b/Documentation/devicetree/bindings/net/ethernet-controller.yaml index 6b0d359367da..9f6a5ccbcefe 100644 --- a/Documentation/devicetree/bindings/net/ethernet-controller.yaml +++ b/Documentation/devicetree/bindings/net/ethernet-controller.yaml @@ -66,6 +66,7 @@ properties: - mii - gmii - sgmii + - psgmii - qsgmii - qusgmii - tbi diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml index c1241c8a3b77..8fb2a6ee7e5b 100644 --- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml +++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml @@ -110,7 +110,7 @@ properties: $ref: /schemas/types.yaml#/definitions/flag description: If set, indicates that PHY will disable swap of the - TX/RX lanes. This property allows the PHY to work correcly after + TX/RX lanes. This property allows the PHY to work correctly after e.g. wrong bootstrap configuration caused by issues in PCB layout design. diff --git a/Documentation/devicetree/bindings/net/ethernet-switch.yaml b/Documentation/devicetree/bindings/net/ethernet-switch.yaml index f1b9075dc7fb..72ac67ca3415 100644 --- a/Documentation/devicetree/bindings/net/ethernet-switch.yaml +++ b/Documentation/devicetree/bindings/net/ethernet-switch.yaml @@ -36,7 +36,7 @@ patternProperties: const: 0 patternProperties: - "^(ethernet-)?port@[0-9]+$": + "^(ethernet-)?port@[0-9a-f]+$": type: object description: Ethernet switch ports @@ -53,14 +53,16 @@ oneOf: additionalProperties: true $defs: - base: + ethernet-ports: description: An ethernet switch without any extra port properties $ref: '#' patternProperties: - "^(ethernet-)?port@[0-9]+$": - description: Ethernet switch ports - $ref: ethernet-switch-port.yaml# - unevaluatedProperties: false + "^(ethernet-)?ports$": + patternProperties: + "^(ethernet-)?port@[0-9a-f]+$": + description: Ethernet switch ports + $ref: ethernet-switch-port.yaml# + unevaluatedProperties: false ... diff --git a/Documentation/devicetree/bindings/net/faraday,ftgmac100.yaml b/Documentation/devicetree/bindings/net/faraday,ftgmac100.yaml new file mode 100644 index 000000000000..9bcbacb6640d --- /dev/null +++ b/Documentation/devicetree/bindings/net/faraday,ftgmac100.yaml @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/faraday,ftgmac100.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Faraday Technology FTGMAC100 gigabit ethernet controller + +allOf: + - $ref: ethernet-controller.yaml# + +maintainers: + - Po-Yu Chuang <ratbert@faraday-tech.com> + +properties: + compatible: + oneOf: + - const: faraday,ftgmac100 + - items: + - enum: + - aspeed,ast2400-mac + - aspeed,ast2500-mac + - aspeed,ast2600-mac + - const: faraday,ftgmac100 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 1 + items: + - description: MAC IP clock + - description: RMII RCLK gate for AST2500/2600 + + clock-names: + minItems: 1 + items: + - const: MACCLK + - const: RCLK + + phy-mode: + enum: + - rgmii + - rmii + + phy-handle: true + + use-ncsi: + description: + Use the NC-SI stack instead of an MDIO PHY. Currently assumes + rmii (100bT) but kept as a separate property in case NC-SI grows support + for a gigabit link. + type: boolean + + no-hw-checksum: + description: + Used to disable HW checksum support. Here for backward + compatibility as the driver now should have correct defaults based on + the SoC. + type: boolean + deprecated: true + + mdio: + $ref: /schemas/net/mdio.yaml# + +required: + - compatible + - reg + - interrupts + +unevaluatedProperties: false + +examples: + - | + ethernet@1e660000 { + compatible = "aspeed,ast2500-mac", "faraday,ftgmac100"; + reg = <0x1e660000 0x180>; + interrupts = <2>; + use-ncsi; + }; + + ethernet@1e680000 { + compatible = "aspeed,ast2500-mac", "faraday,ftgmac100"; + reg = <0x1e680000 0x180>; + interrupts = <2>; + + phy-handle = <&phy>; + phy-mode = "rgmii"; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + phy: ethernet-phy@1 { + compatible = "ethernet-phy-ieee802.3-c22"; + reg = <1>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/fsl,fec.yaml b/Documentation/devicetree/bindings/net/fsl,fec.yaml index b494e009326e..8948a11c994e 100644 --- a/Documentation/devicetree/bindings/net/fsl,fec.yaml +++ b/Documentation/devicetree/bindings/net/fsl,fec.yaml @@ -59,6 +59,7 @@ properties: - const: fsl,imx6sx-fec - items: - enum: + - fsl,imx8dxl-fec - fsl,imx8qxp-fec - const: fsl,imx8qm-fec - const: fsl,imx6sx-fec diff --git a/Documentation/devicetree/bindings/net/ftgmac100.txt b/Documentation/devicetree/bindings/net/ftgmac100.txt deleted file mode 100644 index 29234021f601..000000000000 --- a/Documentation/devicetree/bindings/net/ftgmac100.txt +++ /dev/null @@ -1,67 +0,0 @@ -* Faraday Technology FTGMAC100 gigabit ethernet controller - -Required properties: -- compatible: "faraday,ftgmac100" - - Must also contain one of these if used as part of an Aspeed AST2400 - or 2500 family SoC as they have some subtle tweaks to the - implementation: - - - "aspeed,ast2400-mac" - - "aspeed,ast2500-mac" - - "aspeed,ast2600-mac" - -- reg: Address and length of the register set for the device -- interrupts: Should contain ethernet controller interrupt - -Optional properties: -- phy-handle: See ethernet.txt file in the same directory. -- phy-mode: See ethernet.txt file in the same directory. If the property is - absent, "rgmii" is assumed. Supported values are "rgmii*" and "rmii" for - aspeed parts. Other (unknown) parts will accept any value. -- use-ncsi: Use the NC-SI stack instead of an MDIO PHY. Currently assumes - rmii (100bT) but kept as a separate property in case NC-SI grows support - for a gigabit link. -- no-hw-checksum: Used to disable HW checksum support. Here for backward - compatibility as the driver now should have correct defaults based on - the SoC. -- clocks: In accordance with the generic clock bindings. Must describe the MAC - IP clock, and optionally an RMII RCLK gate for the AST2500/AST2600. The - required MAC clock must be the first cell. -- clock-names: - - - "MACCLK": The MAC IP clock - - "RCLK": Clock gate for the RMII RCLK - -Optional subnodes: -- mdio: See mdio.txt file in the same directory. - -Example: - - mac0: ethernet@1e660000 { - compatible = "aspeed,ast2500-mac", "faraday,ftgmac100"; - reg = <0x1e660000 0x180>; - interrupts = <2>; - use-ncsi; - }; - -Example with phy-handle: - - mac1: ethernet@1e680000 { - compatible = "aspeed,ast2500-mac", "faraday,ftgmac100"; - reg = <0x1e680000 0x180>; - interrupts = <2>; - - phy-handle = <&phy>; - phy-mode = "rgmii"; - - mdio { - #address-cells = <1>; - #size-cells = <0>; - - phy: ethernet-phy@1 { - compatible = "ethernet-phy-ieee802.3-c22"; - reg = <1>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/net/loongson,ls1b-gmac.yaml b/Documentation/devicetree/bindings/net/loongson,ls1b-gmac.yaml new file mode 100644 index 000000000000..c4f3224bad38 --- /dev/null +++ b/Documentation/devicetree/bindings/net/loongson,ls1b-gmac.yaml @@ -0,0 +1,114 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/loongson,ls1b-gmac.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Loongson-1B Gigabit Ethernet MAC Controller + +maintainers: + - Keguang Zhang <keguang.zhang@gmail.com> + +description: | + Loongson-1B Gigabit Ethernet MAC Controller is based on + Synopsys DesignWare MAC (version 3.50a). + + Main features + - Dual 10/100/1000Mbps GMAC controllers + - Full-duplex operation (IEEE 802.3x flow control automatic transmission) + - Half-duplex operation (CSMA/CD Protocol and back-pressure support) + - RX Checksum Offload + - TX Checksum insertion + - MII interface + - RGMII interface + +select: + properties: + compatible: + contains: + enum: + - loongson,ls1b-gmac + required: + - compatible + +properties: + compatible: + items: + - enum: + - loongson,ls1b-gmac + - const: snps,dwmac-3.50a + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: stmmaceth + + interrupts: + maxItems: 1 + + interrupt-names: + items: + - const: macirq + + loongson,ls1-syscon: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to the syscon containing some extra configurations + including PHY interface mode. + + phy-mode: + enum: + - mii + - rgmii-id + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + - interrupt-names + - loongson,ls1-syscon + +allOf: + - $ref: snps,dwmac.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/loongson,ls1x-clk.h> + #include <dt-bindings/interrupt-controller/irq.h> + + gmac0: ethernet@1fe10000 { + compatible = "loongson,ls1b-gmac", "snps,dwmac-3.50a"; + reg = <0x1fe10000 0x10000>; + + clocks = <&clkc LS1X_CLKID_AHB>; + clock-names = "stmmaceth"; + + interrupt-parent = <&intc1>; + interrupts = <2 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "macirq"; + + loongson,ls1-syscon = <&syscon>; + + phy-handle = <&phy0>; + phy-mode = "mii"; + snps,pbl = <1>; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + compatible = "snps,dwmac-mdio"; + + phy0: ethernet-phy@0 { + reg = <0x0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/loongson,ls1c-emac.yaml b/Documentation/devicetree/bindings/net/loongson,ls1c-emac.yaml new file mode 100644 index 000000000000..99001b940b83 --- /dev/null +++ b/Documentation/devicetree/bindings/net/loongson,ls1c-emac.yaml @@ -0,0 +1,113 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/loongson,ls1c-emac.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Loongson-1C Ethernet MAC Controller + +maintainers: + - Keguang Zhang <keguang.zhang@gmail.com> + +description: | + Loongson-1C Ethernet MAC Controller is based on + Synopsys DesignWare MAC (version 3.50a). + + Main features + - 10/100Mbps + - Full-duplex operation (IEEE 802.3x flow control automatic transmission) + - Half-duplex operation (CSMA/CD Protocol and back-pressure support) + - IEEE 802.1Q VLAN tag detection for reception frames + - MII interface + - RMII interface + +select: + properties: + compatible: + contains: + enum: + - loongson,ls1c-emac + required: + - compatible + +properties: + compatible: + items: + - enum: + - loongson,ls1c-emac + - const: snps,dwmac-3.50a + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: stmmaceth + + interrupts: + maxItems: 1 + + interrupt-names: + items: + - const: macirq + + loongson,ls1-syscon: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to the syscon containing some extra configurations + including PHY interface mode. + + phy-mode: + enum: + - mii + - rmii + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + - interrupt-names + - loongson,ls1-syscon + +allOf: + - $ref: snps,dwmac.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/loongson,ls1x-clk.h> + #include <dt-bindings/interrupt-controller/irq.h> + + emac: ethernet@1fe10000 { + compatible = "loongson,ls1c-emac", "snps,dwmac-3.50a"; + reg = <0x1fe10000 0x10000>; + + clocks = <&clkc LS1X_CLKID_AHB>; + clock-names = "stmmaceth"; + + interrupt-parent = <&intc1>; + interrupts = <2 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "macirq"; + + loongson,ls1-syscon = <&syscon>; + + phy-handle = <&phy0>; + phy-mode = "mii"; + snps,pbl = <1>; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + compatible = "snps,dwmac-mdio"; + + phy0: ethernet-phy@13 { + reg = <0x13>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/mediatek,net.yaml b/Documentation/devicetree/bindings/net/mediatek,net.yaml index acb2b2ac4fe1..e74502a0afe8 100644 --- a/Documentation/devicetree/bindings/net/mediatek,net.yaml +++ b/Documentation/devicetree/bindings/net/mediatek,net.yaml @@ -19,10 +19,12 @@ properties: enum: - mediatek,mt2701-eth - mediatek,mt7623-eth + - mediatek,mt7621-eth - mediatek,mt7622-eth - mediatek,mt7629-eth - mediatek,mt7981-eth - mediatek,mt7986-eth + - mediatek,mt7988-eth - ralink,rt5350-eth reg: @@ -32,7 +34,7 @@ properties: clock-names: true interrupts: - minItems: 3 + minItems: 1 maxItems: 4 power-domains: @@ -60,6 +62,12 @@ properties: Phandle to the mediatek hifsys controller used to provide various clocks and reset to the system. + mediatek,infracfg: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to the syscon node that handles the path from GMAC to + PHY variants. + mediatek,sgmiisys: $ref: /schemas/types.yaml#/definitions/phandle-array minItems: 1 @@ -121,6 +129,8 @@ allOf: - const: gp1 - const: gp2 + mediatek,infracfg: false + mediatek,pctl: $ref: /schemas/types.yaml#/definitions/phandle description: @@ -135,6 +145,32 @@ allOf: properties: compatible: contains: + enum: + - mediatek,mt7621-eth + then: + properties: + interrupts: + maxItems: 1 + + clocks: + minItems: 2 + maxItems: 2 + + clock-names: + items: + - const: ethif + - const: fe + + mediatek,infracfg: false + + mediatek,wed: false + + mediatek,wed-pcie: false + + - if: + properties: + compatible: + contains: const: mediatek,mt7622-eth then: properties: @@ -159,6 +195,8 @@ allOf: - const: sgmii_ck - const: eth2pll + mediatek,infracfg: false + mediatek,sgmiisys: minItems: 1 maxItems: 1 @@ -204,12 +242,6 @@ allOf: - const: sgmii_ck - const: eth2pll - mediatek,infracfg: - $ref: /schemas/types.yaml#/definitions/phandle - description: - Phandle to the syscon node that handles the path from GMAC to - PHY variants. - mediatek,sgmiisys: minItems: 2 maxItems: 2 @@ -250,6 +282,8 @@ allOf: - const: netsys0 - const: netsys1 + mediatek,infracfg: false + mediatek,sgmiisys: minItems: 2 maxItems: 2 @@ -286,6 +320,67 @@ allOf: - const: netsys0 - const: netsys1 + mediatek,infracfg: false + + mediatek,sgmiisys: + minItems: 2 + maxItems: 2 + + - if: + properties: + compatible: + contains: + const: mediatek,mt7988-eth + then: + properties: + interrupts: + minItems: 4 + + clocks: + minItems: 34 + maxItems: 34 + + clock-names: + items: + - const: crypto + - const: fe + - const: gp2 + - const: gp1 + - const: gp3 + - const: ethwarp_wocpu2 + - const: ethwarp_wocpu1 + - const: ethwarp_wocpu0 + - const: esw + - const: netsys0 + - const: netsys1 + - const: sgmii_tx250m + - const: sgmii_rx250m + - const: sgmii2_tx250m + - const: sgmii2_rx250m + - const: top_usxgmii0_sel + - const: top_usxgmii1_sel + - const: top_sgm0_sel + - const: top_sgm1_sel + - const: top_xfi_phy0_xtal_sel + - const: top_xfi_phy1_xtal_sel + - const: top_eth_gmii_sel + - const: top_eth_refck_50m_sel + - const: top_eth_sys_200m_sel + - const: top_eth_sys_sel + - const: top_eth_xgmii_sel + - const: top_eth_mii_sel + - const: top_netsys_sel + - const: top_netsys_500m_sel + - const: top_netsys_pao_2x_sel + - const: top_netsys_sync_250m_sel + - const: top_netsys_ppefb_250m_sel + - const: top_netsys_warp_sel + - const: wocpu1 + - const: wocpu0 + - const: xgp1 + - const: xgp2 + - const: xgp3 + mediatek,sgmiisys: minItems: 2 maxItems: 2 @@ -293,7 +388,7 @@ allOf: patternProperties: "^mac@[0-1]$": type: object - additionalProperties: false + unevaluatedProperties: false allOf: - $ref: ethernet-controller.yaml# description: @@ -305,14 +400,9 @@ patternProperties: reg: maxItems: 1 - phy-handle: true - - phy-mode: true - required: - reg - compatible - - phy-handle required: - compatible diff --git a/Documentation/devicetree/bindings/net/mediatek-dwmac.yaml b/Documentation/devicetree/bindings/net/mediatek-dwmac.yaml index 5aa320c8af5a..ed9d845f6008 100644 --- a/Documentation/devicetree/bindings/net/mediatek-dwmac.yaml +++ b/Documentation/devicetree/bindings/net/mediatek-dwmac.yaml @@ -129,7 +129,7 @@ properties: type: boolean description: If present, indicates that MAC supports WOL(Wake-On-LAN), and MAC WOL will be enabled. - Otherwise, PHY WOL is perferred. + Otherwise, PHY WOL is preferred. required: - compatible diff --git a/Documentation/devicetree/bindings/net/microchip,lan95xx.yaml b/Documentation/devicetree/bindings/net/microchip,lan95xx.yaml index 0b97e14d947f..accff93d38f8 100644 --- a/Documentation/devicetree/bindings/net/microchip,lan95xx.yaml +++ b/Documentation/devicetree/bindings/net/microchip,lan95xx.yaml @@ -33,7 +33,7 @@ properties: - usb424,9906 # SMSC9505A USB Ethernet Device (HAL) - usb424,9907 # SMSC9500 USB Ethernet Device (Alternate ID) - usb424,9908 # SMSC9500A USB Ethernet Device (Alternate ID) - - usb424,9909 # SMSC9512/9514 USB Hub & Ethernet Devic. ID) + - usb424,9909 # SMSC9512/9514 USB Hub & Ethernet Device ID) - usb424,9e00 # SMSC9500A USB Ethernet Device - usb424,9e01 # SMSC9505A USB Ethernet Device - usb424,9e08 # SMSC LAN89530 USB Ethernet Device @@ -44,6 +44,8 @@ properties: local-mac-address: true mac-address: true + nvmem-cells: true + nvmem-cell-names: true required: - compatible diff --git a/Documentation/devicetree/bindings/net/motorcomm,yt8xxx.yaml b/Documentation/devicetree/bindings/net/motorcomm,yt8xxx.yaml index 157e3bbcaf6f..26688e2302ea 100644 --- a/Documentation/devicetree/bindings/net/motorcomm,yt8xxx.yaml +++ b/Documentation/devicetree/bindings/net/motorcomm,yt8xxx.yaml @@ -52,6 +52,40 @@ properties: for a timer. type: boolean + motorcomm,rx-clk-drv-microamp: + description: | + drive strength of rx_clk rgmii pad. + The YT8531 RGMII LDO voltage supports 1.8V/3.3V, and the LDO voltage can + be configured with hardware pull-up resistors to match the SOC voltage + (usually 1.8V). + The software can read the registers to obtain the LDO voltage and configure + the legal drive strength(curren). + ===================================================== + | voltage | current Available (uA) | + | 1.8v | 1200 2100 2700 2910 3110 3600 3970 4350 | + | 3.3v | 3070 4080 4370 4680 5020 5450 5740 6140 | + ===================================================== + enum: [ 1200, 2100, 2700, 2910, 3070, 3110, 3600, 3970, + 4080, 4350, 4370, 4680, 5020, 5450, 5740, 6140 ] + default: 2910 + + motorcomm,rx-data-drv-microamp: + description: | + drive strength of rx_data/rx_ctl rgmii pad. + The YT8531 RGMII LDO voltage supports 1.8V/3.3V, and the LDO voltage can + be configured with hardware pull-up resistors to match the SOC voltage + (usually 1.8V). + The software can read the registers to obtain the LDO voltage and configure + the legal drive strength(curren). + ===================================================== + | voltage | current Available (uA) | + | 1.8v | 1200 2100 2700 2910 3110 3600 3970 4350 | + | 3.3v | 3070 4080 4370 4680 5020 5450 5740 6140 | + ===================================================== + enum: [ 1200, 2100, 2700, 2910, 3070, 3110, 3600, 3970, + 4080, 4350, 4370, 4680, 5020, 5450, 5740, 6140 ] + default: 2910 + motorcomm,tx-clk-adj-enabled: description: | This configuration is mainly to adapt to VF2 with JH7110 SoC. diff --git a/Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml b/Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml index 8ee2c7d7ff42..86a9c3fc76c8 100644 --- a/Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml +++ b/Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml @@ -24,7 +24,7 @@ allOf: compatible: const: mscc,vsc7514-switch then: - $ref: ethernet-switch.yaml# + $ref: ethernet-switch.yaml#/$defs/ethernet-ports required: - interrupts - interrupt-names @@ -33,28 +33,18 @@ allOf: minItems: 21 reg-names: minItems: 21 - ethernet-ports: - patternProperties: - "^port@[0-9a-f]+$": - $ref: ethernet-switch-port.yaml# - unevaluatedProperties: false - if: properties: compatible: const: mscc,vsc7512-switch then: - $ref: /schemas/net/dsa/dsa.yaml# + $ref: /schemas/net/dsa/dsa.yaml#/$defs/ethernet-ports properties: reg: maxItems: 20 reg-names: maxItems: 20 - ethernet-ports: - patternProperties: - "^port@[0-9a-f]+$": - $ref: /schemas/net/dsa/dsa-port.yaml# - unevaluatedProperties: false properties: compatible: @@ -185,7 +175,7 @@ examples: }; # VSC7512 (DSA) - | - ethernet-switch@1{ + ethernet-switch@1 { compatible = "mscc,vsc7512-switch"; reg = <0x71010000 0x10000>, <0x71030000 0x10000>, @@ -212,22 +202,22 @@ examples: "port7", "port8", "port9", "port10", "qsys", "ana", "s0", "s1", "s2"; - ethernet-ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - ethernet = <&mac_sw>; - phy-handle = <&phy0>; - phy-mode = "internal"; - }; - port@1 { - reg = <1>; - phy-handle = <&phy1>; - phy-mode = "internal"; - }; + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + ethernet = <&mac_sw>; + phy-handle = <&phy0>; + phy-mode = "internal"; + }; + port@1 { + reg = <1>; + phy-handle = <&phy1>; + phy-mode = "internal"; }; }; + }; ... diff --git a/Documentation/devicetree/bindings/net/nfc/marvell,nci.yaml b/Documentation/devicetree/bindings/net/nfc/marvell,nci.yaml index 8e9a95f24c80..89663fdd3eba 100644 --- a/Documentation/devicetree/bindings/net/nfc/marvell,nci.yaml +++ b/Documentation/devicetree/bindings/net/nfc/marvell,nci.yaml @@ -37,13 +37,13 @@ properties: type: boolean description: | For I2C type of connection. Specifies that the chip read event shall be - trigged on falling edge. + triggered on falling edge. i2c-int-rising: type: boolean description: | For I2C type of connection. Specifies that the chip read event shall be - trigged on rising edge. + triggered on rising edge. break-control: type: boolean diff --git a/Documentation/devicetree/bindings/net/nxp,tja11xx.yaml b/Documentation/devicetree/bindings/net/nxp,tja11xx.yaml index ab8867e6939b..85bfa45f5122 100644 --- a/Documentation/devicetree/bindings/net/nxp,tja11xx.yaml +++ b/Documentation/devicetree/bindings/net/nxp,tja11xx.yaml @@ -20,6 +20,7 @@ allOf: patternProperties: "^ethernet-phy@[0-9a-f]+$": type: object + additionalProperties: false description: | Some packages have multiple PHYs. Secondary PHY should be defines as subnode of the first (parent) PHY. diff --git a/Documentation/devicetree/bindings/net/oxnas-dwmac.txt b/Documentation/devicetree/bindings/net/oxnas-dwmac.txt deleted file mode 100644 index 27db496f1ce8..000000000000 --- a/Documentation/devicetree/bindings/net/oxnas-dwmac.txt +++ /dev/null @@ -1,41 +0,0 @@ -* Oxford Semiconductor OXNAS DWMAC Ethernet controller - -The device inherits all the properties of the dwmac/stmmac devices -described in the file stmmac.txt in the current directory with the -following changes. - -Required properties on all platforms: - -- compatible: For the OX820 SoC, it should be : - - "oxsemi,ox820-dwmac" to select glue - - "snps,dwmac-3.512" to select IP version. - For the OX810SE SoC, it should be : - - "oxsemi,ox810se-dwmac" to select glue - - "snps,dwmac-3.512" to select IP version. - -- clocks: Should contain phandles to the following clocks -- clock-names: Should contain the following: - - "stmmaceth" for the host clock - see stmmac.txt - - "gmac" for the peripheral gate clock - -- oxsemi,sys-ctrl: a phandle to the system controller syscon node - -Example : - -etha: ethernet@40400000 { - compatible = "oxsemi,ox820-dwmac", "snps,dwmac-3.512"; - reg = <0x40400000 0x2000>; - interrupts = <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 17 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "macirq", "eth_wake_irq"; - mac-address = [000000000000]; /* Filled in by U-Boot */ - phy-mode = "rgmii"; - - clocks = <&stdclk CLK_820_ETHA>, <&gmacclk>; - clock-names = "gmac", "stmmaceth"; - resets = <&reset RESET_MAC>; - - /* Regmap for sys registers */ - oxsemi,sys-ctrl = <&sys>; - -}; diff --git a/Documentation/devicetree/bindings/net/qca,ar803x.yaml b/Documentation/devicetree/bindings/net/qca,ar803x.yaml index 161d28919316..3acd09f0da86 100644 --- a/Documentation/devicetree/bindings/net/qca,ar803x.yaml +++ b/Documentation/devicetree/bindings/net/qca,ar803x.yaml @@ -75,6 +75,7 @@ properties: description: Initial data for the VDDIO regulator. Set this to 1.5V or 1.8V. $ref: /schemas/regulator/regulator.yaml + unevaluatedProperties: false vddh-regulator: type: object @@ -82,6 +83,7 @@ properties: Dummy subnode to model the external connection of the PHY VDDH regulator to VDDIO. $ref: /schemas/regulator/regulator.yaml + unevaluatedProperties: false unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/net/renesas,ether.yaml b/Documentation/devicetree/bindings/net/renesas,ether.yaml index 06b38c9bc6ec..29355ab98569 100644 --- a/Documentation/devicetree/bindings/net/renesas,ether.yaml +++ b/Documentation/devicetree/bindings/net/renesas,ether.yaml @@ -81,9 +81,8 @@ properties: active-high patternProperties: - "^ethernet-phy@[0-9a-f]$": + "@[0-9a-f]$": type: object - $ref: ethernet-phy.yaml# required: - compatible diff --git a/Documentation/devicetree/bindings/net/renesas,etheravb.yaml b/Documentation/devicetree/bindings/net/renesas,etheravb.yaml index 3f41294f5997..5d074f27d462 100644 --- a/Documentation/devicetree/bindings/net/renesas,etheravb.yaml +++ b/Documentation/devicetree/bindings/net/renesas,etheravb.yaml @@ -109,9 +109,8 @@ properties: enum: [0, 2000] patternProperties: - "^ethernet-phy@[0-9a-f]$": + "@[0-9a-f]$": type: object - $ref: ethernet-phy.yaml# required: - compatible diff --git a/Documentation/devicetree/bindings/net/rockchip-dwmac.yaml b/Documentation/devicetree/bindings/net/rockchip-dwmac.yaml index 176ea5f90251..70bbc4220e2a 100644 --- a/Documentation/devicetree/bindings/net/rockchip-dwmac.yaml +++ b/Documentation/devicetree/bindings/net/rockchip-dwmac.yaml @@ -80,6 +80,7 @@ properties: "output" means GMAC provides the reference clock. $ref: /schemas/types.yaml#/definitions/string enum: [input, output] + default: input rockchip,grf: description: The phandle of the syscon node for the general register file. @@ -91,12 +92,18 @@ properties: $ref: /schemas/types.yaml#/definitions/phandle tx_delay: - description: Delay value for TXD timing. Range value is 0~0x7F, 0x30 as default. + description: Delay value for TXD timing. $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 0x7F + default: 0x30 rx_delay: - description: Delay value for RXD timing. Range value is 0~0x7F, 0x10 as default. + description: Delay value for RXD timing. $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 0x7F + default: 0x10 phy-supply: description: PHY regulator diff --git a/Documentation/devicetree/bindings/net/samsung-sxgbe.txt b/Documentation/devicetree/bindings/net/samsung-sxgbe.txt index 2cff6d8a585a..b9381b761a27 100644 --- a/Documentation/devicetree/bindings/net/samsung-sxgbe.txt +++ b/Documentation/devicetree/bindings/net/samsung-sxgbe.txt @@ -5,10 +5,10 @@ Required properties: - reg: Address and length of the register set for the device - interrupts: Should contain the SXGBE interrupts These interrupts are ordered by fixed and follows variable - trasmit DMA interrupts, receive DMA interrupts and lpi interrupt. + transmit DMA interrupts, receive DMA interrupts and lpi interrupt. index 0 - this is fixed common interrupt of SXGBE and it is always available. - index 1 to 25 - 8 variable trasmit interrupts, variable 16 receive interrupts + index 1 to 25 - 8 variable transmit interrupts, variable 16 receive interrupts and 1 optional lpi interrupt. - phy-mode: String, operation mode of the PHY interface. Supported values are: "sgmii", "xgmii". diff --git a/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt b/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt index ad3c6e109ce1..bb0224a3e826 100644 --- a/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt +++ b/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt @@ -110,7 +110,7 @@ Optional properties: It depends on the SoC configuration. - snps,read-requests: Number of read requests that the AXI port can issue. It depends on the SoC configuration. -- snps,burst-map: Bitmap of allowed AXI burst lengts, with the LSB +- snps,burst-map: Bitmap of allowed AXI burst lengths, with the LSB representing 4, then 8 etc. - snps,txpbl: DMA Programmable burst length for the TX DMA - snps,rxpbl: DMA Programmable burst length for the RX DMA diff --git a/Documentation/devicetree/bindings/net/snps,dwmac.yaml b/Documentation/devicetree/bindings/net/snps,dwmac.yaml index ddf9522a5dc2..5c2769dc689a 100644 --- a/Documentation/devicetree/bindings/net/snps,dwmac.yaml +++ b/Documentation/devicetree/bindings/net/snps,dwmac.yaml @@ -394,6 +394,11 @@ properties: When a PFC frame is received with priorities matching the bitmask, the queue is blocked from transmitting for the pause time specified in the PFC frame. + + snps,coe-unsupported: + type: boolean + description: TX checksum offload is unsupported by the TX queue. + allOf: - if: required: diff --git a/Documentation/devicetree/bindings/net/sti-dwmac.txt b/Documentation/devicetree/bindings/net/sti-dwmac.txt index 42cd075456ab..e16287c06e5e 100644 --- a/Documentation/devicetree/bindings/net/sti-dwmac.txt +++ b/Documentation/devicetree/bindings/net/sti-dwmac.txt @@ -21,7 +21,7 @@ Optional properties: MAC can generate it. - st,tx-retime-src: This specifies which clk is wired up to the mac for retimeing tx lines. This is totally board dependent and can take one of the - posssible values from "txclk", "clk_125" or "clkgen". + possible values from "txclk", "clk_125" or "clkgen". If not passed, the internal clock will be used by default. - sti-ethclk: this is the phy clock. - sti-clkconf: this is an extra sysconfig register, available in new SoCs, diff --git a/Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml b/Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml index b04ac4966608..f07ae3173b03 100644 --- a/Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml +++ b/Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml @@ -86,7 +86,7 @@ properties: const: 0 patternProperties: - "^port@[0-9]+$": + "^port@[12]$": type: object description: CPSW external ports diff --git a/Documentation/devicetree/bindings/net/ti,icss-iep.yaml b/Documentation/devicetree/bindings/net/ti,icss-iep.yaml new file mode 100644 index 000000000000..f5c22d6dcaee --- /dev/null +++ b/Documentation/devicetree/bindings/net/ti,icss-iep.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/ti,icss-iep.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments ICSS Industrial Ethernet Peripheral (IEP) module + +maintainers: + - Md Danish Anwar <danishanwar@ti.com> + +properties: + compatible: + oneOf: + - items: + - enum: + - ti,am642-icss-iep + - ti,j721e-icss-iep + - const: ti,am654-icss-iep + + - const: ti,am654-icss-iep + + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + description: phandle to the IEP source clock + +required: + - compatible + - reg + - clocks + +additionalProperties: false + +examples: + - | + /* AM65x */ + icssg0_iep0: iep@2e000 { + compatible = "ti,am654-icss-iep"; + reg = <0x2e000 0x1000>; + clocks = <&icssg0_iepclk_mux>; + }; diff --git a/Documentation/devicetree/bindings/net/ti,icssg-prueth.yaml b/Documentation/devicetree/bindings/net/ti,icssg-prueth.yaml new file mode 100644 index 000000000000..229c8f32019f --- /dev/null +++ b/Documentation/devicetree/bindings/net/ti,icssg-prueth.yaml @@ -0,0 +1,201 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/ti,icssg-prueth.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments ICSSG PRUSS Ethernet + +maintainers: + - Md Danish Anwar <danishanwar@ti.com> + +description: + Ethernet based on the Programmable Real-Time Unit and Industrial + Communication Subsystem. + +allOf: + - $ref: /schemas/remoteproc/ti,pru-consumer.yaml# + +properties: + compatible: + enum: + - ti,am642-icssg-prueth # for AM64x SoC family + - ti,am654-icssg-prueth # for AM65x SoC family + + sram: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle to MSMC SRAM node + + dmas: + maxItems: 10 + + dma-names: + items: + - const: tx0-0 + - const: tx0-1 + - const: tx0-2 + - const: tx0-3 + - const: tx1-0 + - const: tx1-1 + - const: tx1-2 + - const: tx1-3 + - const: rx0 + - const: rx1 + + ti,mii-g-rt: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle to MII_G_RT module's syscon regmap. + + ti,mii-rt: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle to MII_RT module's syscon regmap + + ti,iep: + $ref: /schemas/types.yaml#/definitions/phandle-array + maxItems: 2 + items: + maxItems: 1 + description: + phandle to IEP (Industrial Ethernet Peripheral) for ICSSG + + interrupts: + maxItems: 2 + description: + Interrupt specifiers to TX timestamp IRQ. + + interrupt-names: + items: + - const: tx_ts0 + - const: tx_ts1 + + ethernet-ports: + type: object + additionalProperties: false + + properties: + '#address-cells': + const: 1 + '#size-cells': + const: 0 + + patternProperties: + ^port@[0-1]$: + type: object + description: ICSSG PRUETH external ports + $ref: ethernet-controller.yaml# + unevaluatedProperties: false + + properties: + reg: + items: + - enum: [0, 1] + description: ICSSG PRUETH port number + + interrupts: + maxItems: 1 + + ti,syscon-rgmii-delay: + items: + - items: + - description: phandle to system controller node + - description: The offset to ICSSG control register + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + phandle to system controller node and register offset + to ICSSG control register for RGMII transmit delay + + ti,half-duplex-capable: + type: boolean + description: + Indicates that the PHY output pin COL is routed to ICSSG GPIO pin + (PRGx_PRU0/1_GPIO10) as input so that the ICSSG MII port is + capable of half duplex operations. + + required: + - reg + anyOf: + - required: + - port@0 + - required: + - port@1 + +required: + - compatible + - sram + - dmas + - dma-names + - ethernet-ports + - ti,mii-g-rt + - interrupts + - interrupt-names + +unevaluatedProperties: false + +examples: + - | + /* Example k3-am654 base board SR2.0, dual-emac */ + pruss2_eth: ethernet { + compatible = "ti,am654-icssg-prueth"; + pinctrl-names = "default"; + pinctrl-0 = <&icssg2_rgmii_pins_default>; + sram = <&msmc_ram>; + + ti,prus = <&pru2_0>, <&rtu2_0>, <&tx_pru2_0>, + <&pru2_1>, <&rtu2_1>, <&tx_pru2_1>; + firmware-name = "ti-pruss/am65x-pru0-prueth-fw.elf", + "ti-pruss/am65x-rtu0-prueth-fw.elf", + "ti-pruss/am65x-txpru0-prueth-fw.elf", + "ti-pruss/am65x-pru1-prueth-fw.elf", + "ti-pruss/am65x-rtu1-prueth-fw.elf", + "ti-pruss/am65x-txpru1-prueth-fw.elf"; + ti,pruss-gp-mux-sel = <2>, /* MII mode */ + <2>, + <2>, + <2>, /* MII mode */ + <2>, + <2>; + dmas = <&main_udmap 0xc300>, /* egress slice 0 */ + <&main_udmap 0xc301>, /* egress slice 0 */ + <&main_udmap 0xc302>, /* egress slice 0 */ + <&main_udmap 0xc303>, /* egress slice 0 */ + <&main_udmap 0xc304>, /* egress slice 1 */ + <&main_udmap 0xc305>, /* egress slice 1 */ + <&main_udmap 0xc306>, /* egress slice 1 */ + <&main_udmap 0xc307>, /* egress slice 1 */ + <&main_udmap 0x4300>, /* ingress slice 0 */ + <&main_udmap 0x4301>; /* ingress slice 1 */ + dma-names = "tx0-0", "tx0-1", "tx0-2", "tx0-3", + "tx1-0", "tx1-1", "tx1-2", "tx1-3", + "rx0", "rx1"; + ti,mii-g-rt = <&icssg2_mii_g_rt>; + ti,iep = <&icssg2_iep0>, <&icssg2_iep1>; + interrupt-parent = <&icssg2_intc>; + interrupts = <24 0 2>, <25 1 3>; + interrupt-names = "tx_ts0", "tx_ts1"; + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + pruss2_emac0: port@0 { + reg = <0>; + phy-handle = <&pruss2_eth0_phy>; + phy-mode = "rgmii-id"; + interrupts-extended = <&icssg2_intc 24>; + ti,syscon-rgmii-delay = <&scm_conf 0x4120>; + /* Filled in by bootloader */ + local-mac-address = [00 00 00 00 00 00]; + }; + + pruss2_emac1: port@1 { + reg = <1>; + phy-handle = <&pruss2_eth1_phy>; + phy-mode = "rgmii-id"; + interrupts-extended = <&icssg2_intc 25>; + ti,syscon-rgmii-delay = <&scm_conf 0x4124>; + /* Filled in by bootloader */ + local-mac-address = [00 00 00 00 00 00]; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.yaml b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.yaml index 67b63f119f64..252207adbc54 100644 --- a/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.yaml +++ b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.yaml @@ -28,6 +28,7 @@ properties: - mediatek,mt76 - mediatek,mt7628-wmac - mediatek,mt7622-wmac + - mediatek,mt7981-wmac - mediatek,mt7986-wmac reg: @@ -71,6 +72,14 @@ properties: ieee80211-freq-limit: true + nvmem-cells: + items: + - description: NVMEM cell with EEPROM + + nvmem-cell-names: + items: + - const: eeprom + mediatek,eeprom-data: $ref: /schemas/types.yaml#/definitions/uint32-array description: @@ -84,6 +93,7 @@ properties: - description: offset containing EEPROM data description: Phandle to a MTD partition + offset containing EEPROM data + deprecated: true big-endian: $ref: /schemas/types.yaml#/definitions/flag @@ -258,7 +268,8 @@ examples: interrupt-parent = <&cpuintc>; interrupts = <6>; - mediatek,mtd-eeprom = <&factory 0x0>; + nvmem-cells = <&eeprom>; + nvmem-cell-names = "eeprom"; }; - | diff --git a/Documentation/devicetree/bindings/net/xilinx_gmii2rgmii.txt b/Documentation/devicetree/bindings/net/xilinx_gmii2rgmii.txt deleted file mode 100644 index 038dda48b8e6..000000000000 --- a/Documentation/devicetree/bindings/net/xilinx_gmii2rgmii.txt +++ /dev/null @@ -1,35 +0,0 @@ -XILINX GMIITORGMII Converter Driver Device Tree Bindings --------------------------------------------------------- - -The Gigabit Media Independent Interface (GMII) to Reduced Gigabit Media -Independent Interface (RGMII) core provides the RGMII between RGMII-compliant -Ethernet physical media devices (PHY) and the Gigabit Ethernet controller. -This core can be used in all three modes of operation(10/100/1000 Mb/s). -The Management Data Input/Output (MDIO) interface is used to configure the -Speed of operation. This core can switch dynamically between the three -Different speed modes by configuring the conveter register through mdio write. - -This converter sits between the ethernet MAC and the external phy. -MAC <==> GMII2RGMII <==> RGMII_PHY - -For more details about mdio please refer phy.txt file in the same directory. - -Required properties: -- compatible : Should be "xlnx,gmii-to-rgmii-1.0" -- reg : The ID number for the phy, usually a small integer -- phy-handle : Should point to the external phy device. - See ethernet.txt file in the same directory. - -Example: - mdio { - #address-cells = <1>; - #size-cells = <0>; - phy: ethernet-phy@0 { - ...... - }; - gmiitorgmii: gmiitorgmii@8 { - compatible = "xlnx,gmii-to-rgmii-1.0"; - reg = <8>; - phy-handle = <&phy>; - }; - }; diff --git a/Documentation/devicetree/bindings/net/xlnx,gmii-to-rgmii.yaml b/Documentation/devicetree/bindings/net/xlnx,gmii-to-rgmii.yaml new file mode 100644 index 000000000000..0f781dac6717 --- /dev/null +++ b/Documentation/devicetree/bindings/net/xlnx,gmii-to-rgmii.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/xlnx,gmii-to-rgmii.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx GMII to RGMII Converter + +maintainers: + - Harini Katakam <harini.katakam@amd.com> + +description: + The Gigabit Media Independent Interface (GMII) to Reduced Gigabit Media + Independent Interface (RGMII) core provides the RGMII between RGMII-compliant + ethernet physical media devices (PHY) and the Gigabit Ethernet controller. + This core can be used in all three modes of operation(10/100/1000 Mb/s). + The Management Data Input/Output (MDIO) interface is used to configure the + speed of operation. This core can switch dynamically between the three + different speed modes by configuring the converter register through mdio write. + The core cannot function without an external phy connected to it. + +properties: + compatible: + const: xlnx,gmii-to-rgmii-1.0 + + reg: + minimum: 0 + maximum: 31 + description: The ID number for the phy. + + phy-handle: + $ref: ethernet-controller.yaml#/properties/phy-handle + +required: + - compatible + - reg + - phy-handle + +unevaluatedProperties: false + +examples: + - | + mdio { + #address-cells = <1>; + #size-cells = <0>; + + phy: ethernet-phy@0 { + reg = <0>; + }; + gmiitorgmii@8 { + compatible = "xlnx,gmii-to-rgmii-1.0"; + reg = <8>; + phy-handle = <&phy>; + }; + }; diff --git a/Documentation/devicetree/bindings/nios2/nios2.txt b/Documentation/devicetree/bindings/nios2/nios2.txt index b95e831bcba3..3e9cabe667b3 100644 --- a/Documentation/devicetree/bindings/nios2/nios2.txt +++ b/Documentation/devicetree/bindings/nios2/nios2.txt @@ -23,7 +23,7 @@ Required properties: - altr,tlb-num-ways: Specifies the number of set-associativity ways in the TLB. - altr,tlb-num-entries: Specifies the number of entries in the TLB. - altr,tlb-ptr-sz: Specifies size of TLB pointer. -- altr,has-mul: Specifies CPU hardware multipy support, should be 1. +- altr,has-mul: Specifies CPU hardware multiply support, should be 1. - altr,has-mmu: Specifies CPU support MMU support, should be 1. - altr,has-initda: Specifies CPU support initda instruction, should be 1. - altr,reset-addr: Specifies CPU reset address diff --git a/Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml b/Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml index 296001e7f498..0928ec408170 100644 --- a/Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml +++ b/Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml @@ -23,7 +23,9 @@ properties: - const: allwinner,sun20i-d1-sid - const: allwinner,sun50i-a64-sid - items: - - const: allwinner,sun50i-a100-sid + - enum: + - allwinner,sun50i-a100-sid + - allwinner,sun50i-h616-sid - const: allwinner,sun50i-a64-sid - const: allwinner,sun50i-h5-sid - const: allwinner,sun50i-h6-sid diff --git a/Documentation/devicetree/bindings/nvmem/fsl,t1023-sfp.yaml b/Documentation/devicetree/bindings/nvmem/fsl,t1023-sfp.yaml new file mode 100644 index 000000000000..df826b40d8ca --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/fsl,t1023-sfp.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/nvmem/fsl,t1023-sfp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP QorIQ eFuse support + +maintainers: + - Richard Alpe <richard@bit42.se> + +description: + Read support for the eFuses (SFP) on NXP QorIQ series SoC's. + +allOf: + - $ref: nvmem.yaml# + +properties: + compatible: + const: fsl,t1023-sfp + + reg: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + efuse@e8000 { + compatible = "fsl,t1023-sfp"; + reg = <0xe8000 0x1000>; + }; +... diff --git a/Documentation/devicetree/bindings/nvmem/layouts/fixed-cell.yaml b/Documentation/devicetree/bindings/nvmem/layouts/fixed-cell.yaml index e698098450e1..ac2381e66027 100644 --- a/Documentation/devicetree/bindings/nvmem/layouts/fixed-cell.yaml +++ b/Documentation/devicetree/bindings/nvmem/layouts/fixed-cell.yaml @@ -11,6 +11,15 @@ maintainers: - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> properties: + compatible: + oneOf: + - const: mac-base + description: > + Cell with base MAC address to be used for calculating extra relative + addresses. + It can be stored in a plain binary format (cell length 6) or as an + ASCII text like "00:11:22:33:44:55" (cell length 17). + reg: maxItems: 1 @@ -25,6 +34,23 @@ properties: description: Size in bit within the address range specified by reg. +allOf: + - if: + 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" + required: - reg diff --git a/Documentation/devicetree/bindings/nvmem/layouts/fixed-layout.yaml b/Documentation/devicetree/bindings/nvmem/layouts/fixed-layout.yaml index c271537d0714..9bd34bd5af30 100644 --- a/Documentation/devicetree/bindings/nvmem/layouts/fixed-layout.yaml +++ b/Documentation/devicetree/bindings/nvmem/layouts/fixed-layout.yaml @@ -44,6 +44,18 @@ examples: #address-cells = <1>; #size-cells = <1>; + mac@100 { + compatible = "mac-base"; + reg = <0x100 0x6>; + #nvmem-cell-cells = <1>; + }; + + mac@110 { + compatible = "mac-base"; + reg = <0x110 0x11>; + #nvmem-cell-cells = <1>; + }; + calibration@4000 { reg = <0x4000 0x100>; }; diff --git a/Documentation/devicetree/bindings/nvmem/layouts/onie,tlv-layout.yaml b/Documentation/devicetree/bindings/nvmem/layouts/onie,tlv-layout.yaml index 714a6538cc7c..ee8ac322332d 100644 --- a/Documentation/devicetree/bindings/nvmem/layouts/onie,tlv-layout.yaml +++ b/Documentation/devicetree/bindings/nvmem/layouts/onie,tlv-layout.yaml @@ -14,7 +14,7 @@ description: infrastructure shall provide a non-volatile memory with a table whose the content is well specified and gives many information about the manufacturer (name, country of manufacture, etc) as well as device caracteristics (serial - number, hardware version, mac addresses, etc). The underlaying device type + number, hardware version, mac addresses, etc). The underlying device type (flash, EEPROM,...) is not specified. The exact location of each value is also dynamic and should be discovered at run time because it depends on the parameters the manufacturer decided to embed. diff --git a/Documentation/devicetree/bindings/nvmem/nvmem.yaml b/Documentation/devicetree/bindings/nvmem/nvmem.yaml index 980244100690..9f921d940142 100644 --- a/Documentation/devicetree/bindings/nvmem/nvmem.yaml +++ b/Documentation/devicetree/bindings/nvmem/nvmem.yaml @@ -49,7 +49,10 @@ properties: patternProperties: "@[0-9a-f]+(,[0-7])?$": type: object - $ref: layouts/fixed-cell.yaml + allOf: + - $ref: layouts/fixed-cell.yaml + - properties: + compatible: false deprecated: true additionalProperties: true diff --git a/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml index 6cd4682a167d..8740938c32eb 100644 --- a/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml +++ b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml @@ -23,11 +23,13 @@ properties: - qcom,ipq8064-qfprom - qcom,ipq8074-qfprom - qcom,ipq9574-qfprom + - qcom,msm8226-qfprom - qcom,msm8916-qfprom - qcom,msm8974-qfprom - qcom,msm8976-qfprom - qcom,msm8996-qfprom - qcom,msm8998-qfprom + - qcom,qcm2290-qfprom - qcom,qcs404-qfprom - qcom,sc7180-qfprom - qcom,sc7280-qfprom diff --git a/Documentation/devicetree/bindings/nvmem/qcom,sec-qfprom.yaml b/Documentation/devicetree/bindings/nvmem/qcom,sec-qfprom.yaml new file mode 100644 index 000000000000..9b133f783d29 --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/qcom,sec-qfprom.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/nvmem/qcom,sec-qfprom.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies Inc, Secure QFPROM Efuse + +maintainers: + - Komal Bajaj <quic_kbajaj@quicinc.com> + +description: + For some of the Qualcomm SoC's, it is possible that the qfprom region is + protected from non-secure access. In such situations, the OS have to use + secure calls to read the region. + +allOf: + - $ref: nvmem.yaml# + +properties: + compatible: + items: + - enum: + - qcom,qdu1000-sec-qfprom + - const: qcom,sec-qfprom + + reg: + items: + - description: The secure qfprom corrected region. + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + soc { + #address-cells = <2>; + #size-cells = <2>; + + efuse@221c8000 { + compatible = "qcom,qdu1000-sec-qfprom", "qcom,sec-qfprom"; + reg = <0 0x221c8000 0 0x1000>; + #address-cells = <1>; + #size-cells = <1>; + + multi_chan_ddr: multi-chan-ddr@12b { + reg = <0x12b 0x1>; + bits = <0 2>; + }; + }; + }; + diff --git a/Documentation/devicetree/bindings/opp/operating-points-v2-ti-cpu.yaml b/Documentation/devicetree/bindings/opp/operating-points-v2-ti-cpu.yaml new file mode 100644 index 000000000000..02d1d2c17129 --- /dev/null +++ b/Documentation/devicetree/bindings/opp/operating-points-v2-ti-cpu.yaml @@ -0,0 +1,92 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/opp/operating-points-v2-ti-cpu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI CPU OPP (Operating Performance Points) + +description: + TI SoCs, like those in the AM335x, AM437x, AM57xx, AM62x, and DRA7xx + families, the CPU frequencies subset and the voltage value of each + OPP vary based on the silicon variant used. The data sheet sections + corresponding to "Operating Performance Points" describe the frequency + and voltage values based on device type and speed bin information + blown in corresponding eFuse bits as referred to by the Technical + Reference Manual. + + This document extends the operating-points-v2 binding by providing + the hardware description for the scheme mentioned above. + +maintainers: + - Nishanth Menon <nm@ti.com> + +allOf: + - $ref: opp-v2-base.yaml# + +properties: + compatible: + const: operating-points-v2-ti-cpu + + syscon: + $ref: /schemas/types.yaml#/definitions/phandle + description: | + points to syscon node representing the control module + register space of the SoC. + + opp-shared: true + +patternProperties: + '^opp(-?[0-9]+)*$': + type: object + additionalProperties: false + + properties: + clock-latency-ns: true + opp-hz: true + opp-microvolt: true + opp-supported-hw: true + opp-suspend: true + turbo-mode: true + + required: + - opp-hz + - opp-supported-hw + +required: + - compatible + - syscon + +additionalProperties: false + +examples: + - | + opp-table { + compatible = "operating-points-v2-ti-cpu"; + syscon = <&scm_conf>; + + opp-300000000 { + opp-hz = /bits/ 64 <300000000>; + opp-microvolt = <1100000 1078000 1122000>; + opp-supported-hw = <0x06 0x0020>; + opp-suspend; + }; + + opp-500000000 { + opp-hz = /bits/ 64 <500000000>; + opp-microvolt = <1100000 1078000 1122000>; + opp-supported-hw = <0x01 0xFFFF>; + }; + + opp-600000000 { + opp-hz = /bits/ 64 <600000000>; + opp-microvolt = <1100000 1078000 1122000>; + opp-supported-hw = <0x06 0x0040>; + }; + + opp-1000000000 { + opp-hz = /bits/ 64 <1000000000>; + opp-microvolt = <1325000 1298500 1351500>; + opp-supported-hw = <0x04 0x0200>; + }; + }; diff --git a/Documentation/devicetree/bindings/opp/opp-v2-base.yaml b/Documentation/devicetree/bindings/opp/opp-v2-base.yaml index 47e6f36b7637..e2f8f7af3cf4 100644 --- a/Documentation/devicetree/bindings/opp/opp-v2-base.yaml +++ b/Documentation/devicetree/bindings/opp/opp-v2-base.yaml @@ -56,7 +56,7 @@ patternProperties: need to be configured and that is left for the implementation specific binding. minItems: 1 - maxItems: 16 + maxItems: 32 items: maxItems: 1 diff --git a/Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml b/Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml index bbbad31ae4ca..fd04d060c1de 100644 --- a/Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml +++ b/Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml @@ -26,7 +26,9 @@ description: | properties: compatible: - const: operating-points-v2-kryo-cpu + enum: + - operating-points-v2-krait-cpu + - operating-points-v2-kryo-cpu nvmem-cells: description: | @@ -47,6 +49,8 @@ patternProperties: opp-microvolt: true + opp-peak-kBps: true + opp-supported-hw: description: | A single 32 bit bitmap value, representing compatible HW. @@ -63,14 +67,22 @@ patternProperties: 5: MSM8996SG, speedbin 1 6: MSM8996SG, speedbin 2 7-31: unused - enum: [0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, - 0x9, 0xd, 0xe, 0xf, - 0x10, 0x20, 0x30, 0x70] + + Bitmap for IPQ806x SoC: + 0: IPQ8062 + 1: IPQ8064/IPQ8066/IPQ8068 + 2: IPQ8065/IPQ8069 + 3-31: unused + + Other platforms use bits directly corresponding to speedbin index. clock-latency-ns: true required-opps: true + patternProperties: + '^opp-microvolt-speed[0-9]+-pvs[0-9]+$': true + required: - opp-hz @@ -256,6 +268,22 @@ examples: }; }; + /* Dummy opp table to give example for named opp-microvolt */ + opp-table-2 { + compatible = "operating-points-v2-krait-cpu"; + nvmem-cells = <&speedbin_efuse>; + + opp-384000000 { + opp-hz = /bits/ 64 <384000000>; + opp-microvolt-speed0-pvs0 = <1000000 950000 1050000>; + opp-microvolt-speed0-pvs1 = <925000 878750 971250>; + opp-microvolt-speed0-pvs2 = <875000 831250 918750>; + opp-microvolt-speed0-pvs3 = <800000 760000 840000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <100000>; + }; + }; + smem { compatible = "qcom,smem"; memory-region = <&smem_mem>; diff --git a/Documentation/devicetree/bindings/opp/ti,omap-opp-supply.yaml b/Documentation/devicetree/bindings/opp/ti,omap-opp-supply.yaml new file mode 100644 index 000000000000..693f22539606 --- /dev/null +++ b/Documentation/devicetree/bindings/opp/ti,omap-opp-supply.yaml @@ -0,0 +1,101 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/opp/ti,omap-opp-supply.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments OMAP compatible OPP supply + +description: + OMAP5, DRA7, and AM57 families of SoCs have Class 0 AVS eFuse + registers, which contain OPP-specific voltage information tailored + for the specific device. This binding provides the information + needed to describe such a hardware values and relate them to program + the primary regulator during an OPP transition. + + Also, some supplies may have an associated vbb-supply, an Adaptive + Body Bias regulator, which must transition in a specific sequence + w.r.t the vdd-supply and clk when making an OPP transition. By + supplying two regulators to the device that will undergo OPP + transitions, we can use the multi-regulator support implemented by + the OPP core to describe both regulators the platform needs. The + OPP core binding Documentation/devicetree/bindings/opp/opp-v2.yaml + provides further information (refer to Example 4 Handling multiple + regulators). + +maintainers: + - Nishanth Menon <nm@ti.com> + +properties: + $nodename: + pattern: '^opp-supply(@[0-9a-f]+)?$' + + compatible: + oneOf: + - description: Basic OPP supply controlling VDD and VBB + const: ti,omap-opp-supply + - description: OMAP5+ optimized voltages in efuse(Class 0) VDD along with + VBB. + const: ti,omap5-opp-supply + - description: OMAP5+ optimized voltages in efuse(class0) VDD but no VBB + const: ti,omap5-core-opp-supply + + reg: + maxItems: 1 + + ti,absolute-max-voltage-uv: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Absolute maximum voltage for the OPP supply in micro-volts. + minimum: 750000 + maximum: 1500000 + + ti,efuse-settings: + description: An array of u32 tuple items providing information about + optimized efuse configuration. + minItems: 1 + $ref: /schemas/types.yaml#/definitions/uint32-matrix + items: + items: + - description: Reference voltage in micro-volts (OPP Voltage) + minimum: 750000 + maximum: 1500000 + multipleOf: 10000 + - description: efuse offset where the optimized voltage is located + multipleOf: 4 + maximum: 256 + +required: + - compatible + - ti,absolute-max-voltage-uv + +allOf: + - if: + not: + properties: + compatible: + contains: + const: ti,omap-opp-supply + then: + required: + - reg + - ti,efuse-settings + +additionalProperties: false + +examples: + - | + opp-supply { + compatible = "ti,omap-opp-supply"; + ti,absolute-max-voltage-uv = <1375000>; + }; + - | + opp-supply@4a003b20 { + compatible = "ti,omap5-opp-supply"; + reg = <0x4a003b20 0x8>; + ti,efuse-settings = + /* uV offset */ + <1060000 0x0>, + <1160000 0x4>, + <1210000 0x8>; + ti,absolute-max-voltage-uv = <1500000>; + }; diff --git a/Documentation/devicetree/bindings/opp/ti-omap5-opp-supply.txt b/Documentation/devicetree/bindings/opp/ti-omap5-opp-supply.txt deleted file mode 100644 index b70d326117cd..000000000000 --- a/Documentation/devicetree/bindings/opp/ti-omap5-opp-supply.txt +++ /dev/null @@ -1,63 +0,0 @@ -Texas Instruments OMAP compatible OPP supply description - -OMAP5, DRA7, and AM57 family of SoCs have Class0 AVS eFuse registers which -contain data that can be used to adjust voltages programmed for some of their -supplies for more efficient operation. This binding provides the information -needed to read these values and use them to program the main regulator during -an OPP transitions. - -Also, some supplies may have an associated vbb-supply which is an Adaptive Body -Bias regulator which much be transitioned in a specific sequence with regards -to the vdd-supply and clk when making an OPP transition. By supplying two -regulators to the device that will undergo OPP transitions we can make use -of the multi regulator binding that is part of the OPP core described here [1] -to describe both regulators needed by the platform. - -[1] Documentation/devicetree/bindings/opp/opp-v2.yaml - -Required Properties for Device Node: -- vdd-supply: phandle to regulator controlling VDD supply -- vbb-supply: phandle to regulator controlling Body Bias supply - (Usually Adaptive Body Bias regulator) - -Required Properties for opp-supply node: -- compatible: Should be one of: - "ti,omap-opp-supply" - basic OPP supply controlling VDD and VBB - "ti,omap5-opp-supply" - OMAP5+ optimized voltages in efuse(class0)VDD - along with VBB - "ti,omap5-core-opp-supply" - OMAP5+ optimized voltages in efuse(class0) VDD - but no VBB. -- reg: Address and length of the efuse register set for the device (mandatory - only for "ti,omap5-opp-supply") -- ti,efuse-settings: An array of u32 tuple items providing information about - optimized efuse configuration. Each item consists of the following: - volt: voltage in uV - reference voltage (OPP voltage) - efuse_offseet: efuse offset from reg where the optimized voltage is stored. -- ti,absolute-max-voltage-uv: absolute maximum voltage for the OPP supply. - -Example: - -/* Device Node (CPU) */ -cpus { - cpu0: cpu@0 { - device_type = "cpu"; - - ... - - vdd-supply = <&vcc>; - vbb-supply = <&abb_mpu>; - }; -}; - -/* OMAP OPP Supply with Class0 registers */ -opp_supply_mpu: opp_supply@4a003b20 { - compatible = "ti,omap5-opp-supply"; - reg = <0x4a003b20 0x8>; - ti,efuse-settings = < - /* uV offset */ - 1060000 0x0 - 1160000 0x4 - 1210000 0x8 - >; - ti,absolute-max-voltage-uv = <1500000>; -}; diff --git a/Documentation/devicetree/bindings/pci/brcm,iproc-pcie.yaml b/Documentation/devicetree/bindings/pci/brcm,iproc-pcie.yaml index 0972868735fc..0e07ab61a48d 100644 --- a/Documentation/devicetree/bindings/pci/brcm,iproc-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/brcm,iproc-pcie.yaml @@ -12,7 +12,6 @@ maintainers: allOf: - $ref: /schemas/pci/pci-bus.yaml# - - $ref: /schemas/interrupt-controller/msi-controller.yaml# properties: compatible: @@ -34,13 +33,6 @@ properties: description: > Base address and length of the PCIe controller I/O register space - interrupt-map: true - - interrupt-map-mask: true - - "#interrupt-cells": - const: 1 - ranges: minItems: 1 maxItems: 2 @@ -54,16 +46,8 @@ properties: items: - const: pcie-phy - bus-range: true - dma-coherent: true - "#address-cells": true - - "#size-cells": true - - device_type: true - brcm,pcie-ob: type: boolean description: > @@ -78,20 +62,24 @@ properties: msi: type: object + $ref: /schemas/interrupt-controller/msi-controller.yaml# + unevaluatedProperties: false + properties: compatible: items: - const: brcm,iproc-msi - msi-parent: true + interrupts: + maxItems: 4 - msi-controller: true + brcm,pcie-msi-inten: + type: boolean + description: + Needs to be present for some older iProc platforms that require the + interrupt enable registers to be set explicitly to enable MSI - brcm,pcie-msi-inten: - type: boolean - description: > - Needs to be present for some older iProc platforms that require the - interrupt enable registers to be set explicitly to enable MSI + msi-parent: true dependencies: brcm,pcie-ob-axi-offset: ["brcm,pcie-ob"] @@ -117,68 +105,69 @@ unevaluatedProperties: false examples: - | - #include <dt-bindings/interrupt-controller/arm-gic.h> - - bus { - #address-cells = <1>; - #size-cells = <1>; - pcie0: pcie@18012000 { - compatible = "brcm,iproc-pcie"; - reg = <0x18012000 0x1000>; - - #interrupt-cells = <1>; - interrupt-map-mask = <0 0 0 0>; - interrupt-map = <0 0 0 0 &gic GIC_SPI 100 IRQ_TYPE_NONE>; - - linux,pci-domain = <0>; - - bus-range = <0x00 0xff>; - - #address-cells = <3>; - #size-cells = <2>; - device_type = "pci"; - ranges = <0x81000000 0 0 0x28000000 0 0x00010000>, - <0x82000000 0 0x20000000 0x20000000 0 0x04000000>; - - phys = <&phy 0 5>; - phy-names = "pcie-phy"; - - brcm,pcie-ob; - brcm,pcie-ob-axi-offset = <0x00000000>; - - msi-parent = <&msi0>; - - /* iProc event queue based MSI */ - msi0: msi { - compatible = "brcm,iproc-msi"; - msi-controller; - interrupt-parent = <&gic>; - interrupts = <GIC_SPI 96 IRQ_TYPE_NONE>, - <GIC_SPI 97 IRQ_TYPE_NONE>, - <GIC_SPI 98 IRQ_TYPE_NONE>, - <GIC_SPI 99 IRQ_TYPE_NONE>; - }; - }; - - pcie1: pcie@18013000 { - compatible = "brcm,iproc-pcie"; - reg = <0x18013000 0x1000>; - - #interrupt-cells = <1>; - interrupt-map-mask = <0 0 0 0>; - interrupt-map = <0 0 0 0 &gic GIC_SPI 106 IRQ_TYPE_NONE>; - - linux,pci-domain = <1>; - - bus-range = <0x00 0xff>; - - #address-cells = <3>; - #size-cells = <2>; - device_type = "pci"; - ranges = <0x81000000 0 0 0x48000000 0 0x00010000>, - <0x82000000 0 0x40000000 0x40000000 0 0x04000000>; - - phys = <&phy 1 6>; - phy-names = "pcie-phy"; - }; + #include <dt-bindings/interrupt-controller/arm-gic.h> + + gic: interrupt-controller { + interrupt-controller; + #interrupt-cells = <3>; + }; + + pcie@18012000 { + compatible = "brcm,iproc-pcie"; + reg = <0x18012000 0x1000>; + + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 0>; + interrupt-map = <0 0 0 0 &gic GIC_SPI 100 IRQ_TYPE_NONE>; + + linux,pci-domain = <0>; + + bus-range = <0x00 0xff>; + + #address-cells = <3>; + #size-cells = <2>; + device_type = "pci"; + ranges = <0x81000000 0 0 0x28000000 0 0x00010000>, + <0x82000000 0 0x20000000 0x20000000 0 0x04000000>; + + phys = <&phy 0 5>; + phy-names = "pcie-phy"; + + brcm,pcie-ob; + brcm,pcie-ob-axi-offset = <0x00000000>; + + msi-parent = <&msi0>; + + /* iProc event queue based MSI */ + msi0: msi { + compatible = "brcm,iproc-msi"; + msi-controller; + interrupt-parent = <&gic>; + interrupts = <GIC_SPI 96 IRQ_TYPE_NONE>, + <GIC_SPI 97 IRQ_TYPE_NONE>, + <GIC_SPI 98 IRQ_TYPE_NONE>, + <GIC_SPI 99 IRQ_TYPE_NONE>; + }; + }; + - | + pcie@18013000 { + compatible = "brcm,iproc-pcie"; + reg = <0x18013000 0x1000>; + + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 0>; + interrupt-map = <0 0 0 0 &gic GIC_SPI 106 IRQ_TYPE_NONE>; + + linux,pci-domain = <1>; + + bus-range = <0x00 0xff>; + + #address-cells = <3>; + #size-cells = <2>; + device_type = "pci"; + ranges = <0x81000000 0 0 0x48000000 0 0x00010000>, + <0x82000000 0 0x40000000 0x40000000 0 0x04000000>; + + phys = <&phy 1 6>; + phy-names = "pcie-phy"; }; diff --git a/Documentation/devicetree/bindings/pci/qcom,pcie-ep.yaml b/Documentation/devicetree/bindings/pci/qcom,pcie-ep.yaml index 811112255d7d..a223ce029cab 100644 --- a/Documentation/devicetree/bindings/pci/qcom,pcie-ep.yaml +++ b/Documentation/devicetree/bindings/pci/qcom,pcie-ep.yaml @@ -11,10 +11,13 @@ maintainers: properties: compatible: - enum: - - qcom,sdx55-pcie-ep - - qcom,sdx65-pcie-ep - - qcom,sm8450-pcie-ep + oneOf: + - enum: + - qcom,sdx55-pcie-ep + - qcom,sm8450-pcie-ep + - items: + - const: qcom,sdx65-pcie-ep + - const: qcom,sdx55-pcie-ep reg: items: @@ -71,6 +74,14 @@ properties: description: GPIO used as WAKE# output signal maxItems: 1 + interconnects: + maxItems: 2 + + interconnect-names: + items: + - const: pcie-mem + - const: cpu-pcie + resets: maxItems: 1 @@ -98,6 +109,8 @@ required: - interrupts - interrupt-names - reset-gpios + - interconnects + - interconnect-names - resets - reset-names - power-domains @@ -110,7 +123,6 @@ allOf: contains: enum: - qcom,sdx55-pcie-ep - - qcom,sdx65-pcie-ep then: properties: clocks: @@ -167,7 +179,9 @@ examples: - | #include <dt-bindings/clock/qcom,gcc-sdx55.h> #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interconnect/qcom,sdx55.h> #include <dt-bindings/interrupt-controller/arm-gic.h> + pcie_ep: pcie-ep@1c00000 { compatible = "qcom,sdx55-pcie-ep"; reg = <0x01c00000 0x3000>, @@ -194,6 +208,9 @@ examples: interrupts = <GIC_SPI 140 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 145 IRQ_TYPE_LEVEL_HIGH>; interrupt-names = "global", "doorbell"; + interconnects = <&system_noc MASTER_PCIE &mc_virt SLAVE_EBI_CH0>, + <&mem_noc MASTER_AMPSS_M0 &system_noc SLAVE_PCIE_0>; + interconnect-names = "pcie-mem", "cpu-pcie"; reset-gpios = <&tlmm 57 GPIO_ACTIVE_LOW>; wake-gpios = <&tlmm 53 GPIO_ACTIVE_LOW>; resets = <&gcc GCC_PCIE_BCR>; diff --git a/Documentation/devicetree/bindings/pci/qcom,pcie.yaml b/Documentation/devicetree/bindings/pci/qcom,pcie.yaml index 81971be4e554..eadba38171e1 100644 --- a/Documentation/devicetree/bindings/pci/qcom,pcie.yaml +++ b/Documentation/devicetree/bindings/pci/qcom,pcie.yaml @@ -29,6 +29,7 @@ properties: - qcom,pcie-msm8996 - qcom,pcie-qcs404 - qcom,pcie-sa8540p + - qcom,pcie-sa8775p - qcom,pcie-sc7280 - qcom,pcie-sc8180x - qcom,pcie-sc8280xp @@ -211,6 +212,7 @@ allOf: compatible: contains: enum: + - qcom,pcie-sa8775p - qcom,pcie-sc7280 - qcom,pcie-sc8180x - qcom,pcie-sc8280xp @@ -748,7 +750,32 @@ allOf: compatible: contains: enum: + - qcom,pcie-sa8775p + then: + properties: + clocks: + minItems: 5 + maxItems: 5 + clock-names: + items: + - const: aux # Auxiliary clock + - const: cfg # Configuration clock + - const: bus_master # Master AXI clock + - const: bus_slave # Slave AXI clock + - const: slave_q2a # Slave Q2A clock + resets: + maxItems: 1 + reset-names: + items: + - const: pci # PCIe core reset + + - if: + properties: + compatible: + contains: + enum: - qcom,pcie-sa8540p + - qcom,pcie-sa8775p - qcom,pcie-sc8280xp then: required: @@ -790,6 +817,7 @@ allOf: contains: enum: - qcom,pcie-msm8996 + - qcom,pcie-sa8775p - qcom,pcie-sc7280 - qcom,pcie-sc8180x - qcom,pcie-sdm845 diff --git a/Documentation/devicetree/bindings/pci/rcar-gen4-pci-ep.yaml b/Documentation/devicetree/bindings/pci/rcar-gen4-pci-ep.yaml new file mode 100644 index 000000000000..fe38f62da066 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/rcar-gen4-pci-ep.yaml @@ -0,0 +1,115 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2022-2023 Renesas Electronics Corp. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/rcar-gen4-pci-ep.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car Gen4 PCIe Endpoint + +maintainers: + - Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com> + +allOf: + - $ref: snps,dw-pcie-ep.yaml# + +properties: + compatible: + items: + - const: renesas,r8a779f0-pcie-ep # R-Car S4-8 + - const: renesas,rcar-gen4-pcie-ep # R-Car Gen4 + + reg: + maxItems: 7 + + reg-names: + items: + - const: dbi + - const: dbi2 + - const: atu + - const: dma + - const: app + - const: phy + - const: addr_space + + interrupts: + maxItems: 3 + + interrupt-names: + items: + - const: dma + - const: sft_ce + - const: app + + clocks: + maxItems: 2 + + clock-names: + items: + - const: core + - const: ref + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + reset-names: + items: + - const: pwr + + max-link-speed: + maximum: 4 + + num-lanes: + maximum: 4 + + max-functions: + maximum: 2 + +required: + - compatible + - reg + - reg-names + - interrupts + - interrupt-names + - clocks + - clock-names + - power-domains + - resets + - reset-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a779f0-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a779f0-sysc.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + pcie0_ep: pcie-ep@e65d0000 { + compatible = "renesas,r8a779f0-pcie-ep", "renesas,rcar-gen4-pcie-ep"; + reg = <0 0xe65d0000 0 0x2000>, <0 0xe65d2000 0 0x1000>, + <0 0xe65d3000 0 0x2000>, <0 0xe65d5000 0 0x1200>, + <0 0xe65d6200 0 0x0e00>, <0 0xe65d7000 0 0x0400>, + <0 0xfe000000 0 0x400000>; + reg-names = "dbi", "dbi2", "atu", "dma", "app", "phy", "addr_space"; + interrupts = <GIC_SPI 417 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 418 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 422 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "dma", "sft_ce", "app"; + clocks = <&cpg CPG_MOD 624>, <&pcie0_clkref>; + clock-names = "core", "ref"; + power-domains = <&sysc R8A779F0_PD_ALWAYS_ON>; + resets = <&cpg 624>; + reset-names = "pwr"; + max-link-speed = <4>; + num-lanes = <2>; + max-functions = /bits/ 8 <2>; + }; + }; diff --git a/Documentation/devicetree/bindings/pci/rcar-gen4-pci-host.yaml b/Documentation/devicetree/bindings/pci/rcar-gen4-pci-host.yaml new file mode 100644 index 000000000000..ffb34339b637 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/rcar-gen4-pci-host.yaml @@ -0,0 +1,127 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2022-2023 Renesas Electronics Corp. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/rcar-gen4-pci-host.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car Gen4 PCIe Host + +maintainers: + - Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com> + +allOf: + - $ref: snps,dw-pcie.yaml# + +properties: + compatible: + items: + - const: renesas,r8a779f0-pcie # R-Car S4-8 + - const: renesas,rcar-gen4-pcie # R-Car Gen4 + + reg: + maxItems: 7 + + reg-names: + items: + - const: dbi + - const: dbi2 + - const: atu + - const: dma + - const: app + - const: phy + - const: config + + interrupts: + maxItems: 4 + + interrupt-names: + items: + - const: msi + - const: dma + - const: sft_ce + - const: app + + clocks: + maxItems: 2 + + clock-names: + items: + - const: core + - const: ref + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + reset-names: + items: + - const: pwr + + max-link-speed: + maximum: 4 + + num-lanes: + maximum: 4 + +required: + - compatible + - reg + - reg-names + - interrupts + - interrupt-names + - clocks + - clock-names + - power-domains + - resets + - reset-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a779f0-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a779f0-sysc.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + pcie: pcie@e65d0000 { + compatible = "renesas,r8a779f0-pcie", "renesas,rcar-gen4-pcie"; + reg = <0 0xe65d0000 0 0x1000>, <0 0xe65d2000 0 0x0800>, + <0 0xe65d3000 0 0x2000>, <0 0xe65d5000 0 0x1200>, + <0 0xe65d6200 0 0x0e00>, <0 0xe65d7000 0 0x0400>, + <0 0xfe000000 0 0x400000>; + reg-names = "dbi", "dbi2", "atu", "dma", "app", "phy", "config"; + interrupts = <GIC_SPI 416 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 417 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 418 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 422 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "msi", "dma", "sft_ce", "app"; + clocks = <&cpg CPG_MOD 624>, <&pcie0_clkref>; + clock-names = "core", "ref"; + power-domains = <&sysc R8A779F0_PD_ALWAYS_ON>; + resets = <&cpg 624>; + reset-names = "pwr"; + max-link-speed = <4>; + num-lanes = <2>; + #address-cells = <3>; + #size-cells = <2>; + bus-range = <0x00 0xff>; + device_type = "pci"; + ranges = <0x01000000 0 0x00000000 0 0xfe000000 0 0x00400000>, + <0x02000000 0 0x30000000 0 0x30000000 0 0x10000000>; + dma-ranges = <0x42000000 0 0x00000000 0 0x00000000 1 0x00000000>; + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0 0 0 1 &gic GIC_SPI 416 IRQ_TYPE_LEVEL_HIGH>, + <0 0 0 2 &gic GIC_SPI 416 IRQ_TYPE_LEVEL_HIGH>, + <0 0 0 3 &gic GIC_SPI 416 IRQ_TYPE_LEVEL_HIGH>, + <0 0 0 4 &gic GIC_SPI 416 IRQ_TYPE_LEVEL_HIGH>; + snps,enable-cdm-check; + }; + }; diff --git a/Documentation/devicetree/bindings/pci/rockchip-dw-pcie.yaml b/Documentation/devicetree/bindings/pci/rockchip-dw-pcie.yaml index a4f61ced5e88..1ae8dcfa072c 100644 --- a/Documentation/devicetree/bindings/pci/rockchip-dw-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/rockchip-dw-pcie.yaml @@ -60,6 +60,61 @@ properties: - const: aux - const: pipe + interrupts: + items: + - description: + Combined system interrupt, which is used to signal the following + interrupts - phy_link_up, dll_link_up, link_req_rst_not, hp_pme, + hp, hp_msi, link_auto_bw, link_auto_bw_msi, bw_mgt, bw_mgt_msi, + edma_wr, edma_rd, dpa_sub_upd, rbar_update, link_eq_req, ep_elbi_app + - description: + Combined PM interrupt, which is used to signal the following + interrupts - linkst_in_l1sub, linkst_in_l1, linkst_in_l2, + linkst_in_l0s, linkst_out_l1sub, linkst_out_l1, linkst_out_l2, + linkst_out_l0s, pm_dstate_update + - description: + Combined message interrupt, which is used to signal the following + interrupts - ven_msg, unlock_msg, ltr_msg, cfg_pme, cfg_pme_msi, + pm_pme, pm_to_ack, pm_turnoff, obff_idle, obff_obff, obff_cpu_active + - description: + Combined legacy interrupt, which is used to signal the following + interrupts - inta, intb, intc, intd + - description: + Combined error interrupt, which is used to signal the following + interrupts - aer_rc_err, aer_rc_err_msi, rx_cpl_timeout, + tx_cpl_timeout, cor_err_sent, nf_err_sent, f_err_sent, cor_err_rx, + nf_err_rx, f_err_rx, radm_qoverflow + + interrupt-names: + items: + - const: sys + - const: pmc + - const: msg + - const: legacy + - const: err + + legacy-interrupt-controller: + description: Interrupt controller node for handling legacy PCI interrupts. + type: object + additionalProperties: false + properties: + "#address-cells": + const: 0 + + "#interrupt-cells": + const: 1 + + interrupt-controller: true + + interrupts: + items: + - description: combined legacy interrupt + required: + - "#address-cells" + - "#interrupt-cells" + - interrupt-controller + - interrupts + msi-map: true num-lanes: true @@ -108,6 +163,7 @@ unevaluatedProperties: false examples: - | + #include <dt-bindings/interrupt-controller/arm-gic.h> bus { #address-cells = <2>; @@ -127,6 +183,12 @@ examples: "aclk_dbi", "pclk", "aux"; device_type = "pci"; + interrupts = <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 159 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 158 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 157 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 156 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "sys", "pmc", "msg", "legacy", "err"; linux,pci-domain = <2>; max-link-speed = <2>; msi-map = <0x2000 &its 0x2000 0x1000>; @@ -140,6 +202,14 @@ examples: reset-names = "pipe"; #address-cells = <3>; #size-cells = <2>; + + legacy-interrupt-controller { + interrupt-controller; + #address-cells = <0>; + #interrupt-cells = <1>; + interrupt-parent = <&gic>; + interrupts = <GIC_SPI 72 IRQ_TYPE_EDGE_RISING>; + }; }; }; ... diff --git a/Documentation/devicetree/bindings/pci/snps,dw-pcie-common.yaml b/Documentation/devicetree/bindings/pci/snps,dw-pcie-common.yaml index d87e13496834..dc05761c5cf9 100644 --- a/Documentation/devicetree/bindings/pci/snps,dw-pcie-common.yaml +++ b/Documentation/devicetree/bindings/pci/snps,dw-pcie-common.yaml @@ -33,11 +33,11 @@ properties: specific for each activated function, while the rest of the sub-spaces are common for all of them (if there are more than one). minItems: 2 - maxItems: 6 + maxItems: 7 reg-names: minItems: 2 - maxItems: 6 + maxItems: 7 interrupts: description: diff --git a/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml b/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml index 8fc2151691a4..bbdb01d22848 100644 --- a/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml +++ b/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml @@ -33,11 +33,11 @@ properties: normal controller functioning. iATU memory IO region is also required if the space is unrolled (IP-core version >= 4.80a). minItems: 2 - maxItems: 5 + maxItems: 7 reg-names: minItems: 2 - maxItems: 5 + maxItems: 7 items: oneOf: - description: diff --git a/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml b/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml index 1a83f0f65f19..022055edbf9e 100644 --- a/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml @@ -25,6 +25,15 @@ select: allOf: - $ref: /schemas/pci/pci-bus.yaml# - $ref: /schemas/pci/snps,dw-pcie-common.yaml# + - if: + not: + required: + - msi-map + then: + properties: + interrupt-names: + contains: + const: msi properties: reg: @@ -33,11 +42,11 @@ properties: are required for the normal controller work. iATU memory IO region is also required if the space is unrolled (IP-core version >= 4.80a). minItems: 2 - maxItems: 5 + maxItems: 7 reg-names: minItems: 2 - maxItems: 5 + maxItems: 7 items: oneOf: - description: @@ -188,14 +197,15 @@ properties: Link Control register). const: bw_mg - description: + Combined Legacy A/B/C/D interrupt signal. See "^int(a|b|c|d)$" for + details. + const: legacy + - description: Vendor-specific IRQ names. Consider using the generic names above for new bindings. oneOf: - description: See native "app" IRQ for details - enum: [ intr ] - allOf: - - contains: - const: msi + enum: [ intr, sys, pmc, msg, err ] additionalProperties: true diff --git a/Documentation/devicetree/bindings/pci/xlnx,nwl-pcie.yaml b/Documentation/devicetree/bindings/pci/xlnx,nwl-pcie.yaml index 897602559b37..426f90a47f35 100644 --- a/Documentation/devicetree/bindings/pci/xlnx,nwl-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/xlnx,nwl-pcie.yaml @@ -118,7 +118,7 @@ examples: compatible = "xlnx,nwl-pcie-2.11"; reg = <0x0 0xfd0e0000 0x0 0x1000>, <0x0 0xfd480000 0x0 0x1000>, - <0x80 0x00000000 0x0 0x1000000>; + <0x80 0x00000000 0x0 0x10000000>; reg-names = "breg", "pcireg", "cfg"; ranges = <0x02000000 0x0 0xe0000000 0x0 0xe0000000 0x0 0x10000000>, <0x43000000 0x00000006 0x0 0x00000006 0x0 0x00000002 0x0>; diff --git a/Documentation/devicetree/bindings/pci/xlnx,xdma-host.yaml b/Documentation/devicetree/bindings/pci/xlnx,xdma-host.yaml new file mode 100644 index 000000000000..0aa00b8e49b3 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/xlnx,xdma-host.yaml @@ -0,0 +1,114 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/xlnx,xdma-host.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx XDMA PL PCIe Root Port Bridge + +maintainers: + - Thippeswamy Havalige <thippeswamy.havalige@amd.com> + +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + +properties: + compatible: + const: xlnx,xdma-host-3.00 + + reg: + maxItems: 1 + + ranges: + maxItems: 2 + + interrupts: + items: + - description: interrupt asserted when miscellaneous interrupt is received. + - description: msi0 interrupt asserted when an MSI is received. + - description: msi1 interrupt asserted when an MSI is received. + + interrupt-names: + items: + - const: misc + - const: msi0 + - const: msi1 + + interrupt-map-mask: + items: + - const: 0 + - const: 0 + - const: 0 + - const: 7 + + interrupt-map: + maxItems: 4 + + "#interrupt-cells": + const: 1 + + interrupt-controller: + description: identifies the node as an interrupt controller + type: object + properties: + interrupt-controller: true + + "#address-cells": + const: 0 + + "#interrupt-cells": + const: 1 + + required: + - interrupt-controller + - "#address-cells" + - "#interrupt-cells" + + additionalProperties: false + +required: + - compatible + - reg + - ranges + - interrupts + - interrupt-map + - interrupt-map-mask + - "#interrupt-cells" + - interrupt-controller + +unevaluatedProperties: false + +examples: + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + pcie@a0000000 { + compatible = "xlnx,xdma-host-3.00"; + reg = <0x0 0xa0000000 0x0 0x10000000>; + ranges = <0x2000000 0x0 0xb0000000 0x0 0xb0000000 0x0 0x1000000>, + <0x43000000 0x5 0x0 0x5 0x0 0x0 0x1000000>; + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + device_type = "pci"; + interrupt-parent = <&gic>; + interrupts = <GIC_SPI 89 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 90 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 91 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "misc", "msi0", "msi1"; + interrupt-map-mask = <0x0 0x0 0x0 0x7>; + interrupt-map = <0 0 0 1 &pcie_intc_0 0>, + <0 0 0 2 &pcie_intc_0 1>, + <0 0 0 3 &pcie_intc_0 2>, + <0 0 0 4 &pcie_intc_0 3>; + pcie_intc_0: interrupt-controller { + #address-cells = <0>; + #interrupt-cells = <1>; + interrupt-controller; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/peci/nuvoton,npcm-peci.yaml b/Documentation/devicetree/bindings/peci/nuvoton,npcm-peci.yaml new file mode 100644 index 000000000000..087e02a9ade3 --- /dev/null +++ b/Documentation/devicetree/bindings/peci/nuvoton,npcm-peci.yaml @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/peci/nuvoton,npcm-peci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nuvoton PECI Bus + +maintainers: + - Tomer Maimon <tmaimon77@gmail.com> + +allOf: + - $ref: peci-controller.yaml# + +properties: + compatible: + enum: + - nuvoton,npcm750-peci + - nuvoton,npcm845-peci + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + description: + Clock source for PECI controller. Should reference the APB clock. + maxItems: 1 + + cmd-timeout-ms: + minimum: 1 + maximum: 1000 + default: 1000 + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/nuvoton,npcm7xx-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + peci-controller@f0100000 { + compatible = "nuvoton,npcm750-peci"; + reg = <0xf0100000 0x200>; + interrupts = <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk NPCM7XX_CLK_APB3>; + cmd-timeout-ms = <1000>; + }; +... diff --git a/Documentation/devicetree/bindings/phy/mediatek,mt7621-pci-phy.yaml b/Documentation/devicetree/bindings/phy/mediatek,mt7621-pci-phy.yaml index b35c4d256e40..99eac888ae03 100644 --- a/Documentation/devicetree/bindings/phy/mediatek,mt7621-pci-phy.yaml +++ b/Documentation/devicetree/bindings/phy/mediatek,mt7621-pci-phy.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/phy/mediatek,mt7621-pci-phy.yaml# diff --git a/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml b/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml index 230a17f24966..2bb91542e984 100644 --- a/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml +++ b/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml @@ -64,7 +64,7 @@ description: | properties: $nodename: - pattern: "^t-phy@[0-9a-f]+$" + pattern: "^t-phy(@[0-9a-f]+)?$" compatible: oneOf: diff --git a/Documentation/devicetree/bindings/phy/nvidia,tegra210-xusb-padctl.yaml b/Documentation/devicetree/bindings/phy/nvidia,tegra210-xusb-padctl.yaml index d16bd6e47f90..e9237c58ce45 100644 --- a/Documentation/devicetree/bindings/phy/nvidia,tegra210-xusb-padctl.yaml +++ b/Documentation/devicetree/bindings/phy/nvidia,tegra210-xusb-padctl.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/phy/nvidia,tegra210-xusb-padctl.yaml# diff --git a/Documentation/devicetree/bindings/phy/phy-hisi-inno-usb2.txt b/Documentation/devicetree/bindings/phy/phy-hisi-inno-usb2.txt index 0d70c8341095..104953e849e7 100644 --- a/Documentation/devicetree/bindings/phy/phy-hisi-inno-usb2.txt +++ b/Documentation/devicetree/bindings/phy/phy-hisi-inno-usb2.txt @@ -14,7 +14,7 @@ Required properties: - #size-cells: Must be 0. The INNO USB2 PHY device should be a child node of peripheral controller that -contains the PHY configuration register, and each device suppports up to 2 PHY +contains the PHY configuration register, and each device supports up to 2 PHY ports which are represented as child nodes of INNO USB2 PHY device. Required properties for PHY port node: diff --git a/Documentation/devicetree/bindings/phy/pistachio-usb-phy.txt b/Documentation/devicetree/bindings/phy/pistachio-usb-phy.txt index afbc7e24a3de..c7970c07ee32 100644 --- a/Documentation/devicetree/bindings/phy/pistachio-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/pistachio-usb-phy.txt @@ -8,7 +8,7 @@ Required properties: - clocks: Must contain an entry for each entry in clock-names. See ../clock/clock-bindings.txt for details. - clock-names: Must include "usb_phy". - - img,cr-top: Must constain a phandle to the CR_TOP syscon node. + - img,cr-top: Must contain a phandle to the CR_TOP syscon node. - img,refclk: Indicates the reference clock source for the USB PHY. See <dt-bindings/phy/phy-pistachio-usb.h> for a list of valid values. diff --git a/Documentation/devicetree/bindings/phy/pxa1928-usb-phy.txt b/Documentation/devicetree/bindings/phy/pxa1928-usb-phy.txt index 660a13ca90b3..da94426aa694 100644 --- a/Documentation/devicetree/bindings/phy/pxa1928-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/pxa1928-usb-phy.txt @@ -4,7 +4,7 @@ Required properties: - compatible: "marvell,pxa1928-usb-phy" or "marvell,pxa1928-hsic-phy" - reg: base address and length of the registers - clocks - A single clock. From common clock binding. -- #phys-cells: should be 0. From commmon phy binding. +- #phys-cells: should be 0. From common phy binding. - resets: reference to the reset controller Example: diff --git a/Documentation/devicetree/bindings/phy/qcom,ipq5332-usb-hsphy.yaml b/Documentation/devicetree/bindings/phy/qcom,ipq5332-usb-hsphy.yaml new file mode 100644 index 000000000000..2671a048c926 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/qcom,ipq5332-usb-hsphy.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/qcom,ipq5332-usb-hsphy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: M31 USB PHY + +maintainers: + - Sricharan Ramabadhran <quic_srichara@quicinc.com> + - Varadarajan Narayanan <quic_varada@quicinc.com> + +description: + USB M31 PHY (https://www.m31tech.com) found in Qualcomm + IPQ5018, IPQ5332 SoCs. + +properties: + compatible: + items: + - const: qcom,ipq5332-usb-hsphy + + "#phy-cells": + const: 0 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: cfg_ahb + + resets: + maxItems: 1 + + vdd-supply: + description: + Phandle to 5V regulator supply to PHY digital circuit. + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,ipq5332-gcc.h> + usb-phy@7b000 { + compatible = "qcom,ipq5332-usb-hsphy"; + reg = <0x0007b000 0x12c>; + + clocks = <&gcc GCC_USB0_PHY_CFG_AHB_CLK>; + clock-names = "cfg_ahb"; + + #phy-cells = <0>; + + resets = <&gcc GCC_QUSB2_0_PHY_BCR>; + + vdd-supply = <®ulator_fixed_5p0>; + }; diff --git a/Documentation/devicetree/bindings/phy/qcom,ipq8074-qmp-pcie-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,ipq8074-qmp-pcie-phy.yaml index 3d42ee3901a1..634cec5d57ea 100644 --- a/Documentation/devicetree/bindings/phy/qcom,ipq8074-qmp-pcie-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,ipq8074-qmp-pcie-phy.yaml @@ -13,287 +13,79 @@ description: QMP PHY controller supports physical layer functionality for a number of controllers on Qualcomm chipsets, such as, PCIe, UFS, and USB. - Note that these bindings are for SoCs up to SC8180X. For newer SoCs, see - qcom,sc8280xp-qmp-pcie-phy.yaml. - properties: compatible: enum: - qcom,ipq6018-qmp-pcie-phy - qcom,ipq8074-qmp-gen3-pcie-phy - qcom,ipq8074-qmp-pcie-phy - - qcom,msm8998-qmp-pcie-phy - - qcom,sc8180x-qmp-pcie-phy - - qcom,sdm845-qhp-pcie-phy - - qcom,sdm845-qmp-pcie-phy - - qcom,sdx55-qmp-pcie-phy - - qcom,sm8250-qmp-gen3x1-pcie-phy - - qcom,sm8250-qmp-gen3x2-pcie-phy - - qcom,sm8250-qmp-modem-pcie-phy - - qcom,sm8450-qmp-gen3x1-pcie-phy - - qcom,sm8450-qmp-gen4x2-pcie-phy reg: items: - description: serdes - "#address-cells": - enum: [ 1, 2 ] - - "#size-cells": - enum: [ 1, 2 ] - - ranges: true - clocks: - minItems: 2 - maxItems: 4 + maxItems: 3 clock-names: - minItems: 2 - maxItems: 4 + items: + - const: aux + - const: cfg_ahb + - const: pipe resets: - minItems: 1 maxItems: 2 reset-names: - minItems: 1 - maxItems: 2 - - vdda-phy-supply: true - - vdda-pll-supply: true - - vddp-ref-clk-supply: true - -patternProperties: - "^phy@[0-9a-f]+$": - type: object - description: single PHY-provider child node - properties: - reg: - minItems: 3 - maxItems: 6 - - clocks: - items: - - description: PIPE clock - - clock-names: - deprecated: true - items: - - const: pipe0 - - "#clock-cells": - const: 0 - - clock-output-names: - maxItems: 1 + items: + - const: phy + - const: common - "#phy-cells": - const: 0 + "#clock-cells": + const: 0 - required: - - reg - - clocks - - "#clock-cells" - - clock-output-names - - "#phy-cells" + clock-output-names: + maxItems: 1 - additionalProperties: false + "#phy-cells": + const: 0 required: - compatible - reg - - "#address-cells" - - "#size-cells" - - ranges - clocks - clock-names - resets - reset-names + - "#clock-cells" + - clock-output-names + - "#phy-cells" additionalProperties: false -allOf: - - if: - properties: - compatible: - contains: - enum: - - qcom,msm8998-qmp-pcie-phy - then: - properties: - clocks: - maxItems: 3 - clock-names: - items: - - const: aux - - const: cfg_ahb - - const: ref - resets: - maxItems: 2 - reset-names: - items: - - const: phy - - const: common - required: - - vdda-phy-supply - - vdda-pll-supply - - - if: - properties: - compatible: - contains: - enum: - - qcom,ipq6018-qmp-pcie-phy - - qcom,ipq8074-qmp-gen3-pcie-phy - - qcom,ipq8074-qmp-pcie-phy - then: - properties: - clocks: - maxItems: 2 - clock-names: - items: - - const: aux - - const: cfg_ahb - resets: - maxItems: 2 - reset-names: - items: - - const: phy - - const: common - - - if: - properties: - compatible: - contains: - enum: - - qcom,sc8180x-qmp-pcie-phy - - qcom,sdm845-qhp-pcie-phy - - qcom,sdm845-qmp-pcie-phy - - qcom,sdx55-qmp-pcie-phy - - qcom,sm8250-qmp-gen3x1-pcie-phy - - qcom,sm8250-qmp-gen3x2-pcie-phy - - qcom,sm8250-qmp-modem-pcie-phy - - qcom,sm8450-qmp-gen3x1-pcie-phy - - qcom,sm8450-qmp-gen4x2-pcie-phy - then: - properties: - clocks: - maxItems: 4 - clock-names: - items: - - const: aux - - const: cfg_ahb - - const: ref - - const: refgen - resets: - maxItems: 1 - reset-names: - items: - - const: phy - required: - - vdda-phy-supply - - vdda-pll-supply - - - if: - properties: - compatible: - contains: - enum: - - qcom,sc8180x-qmp-pcie-phy - - qcom,sm8250-qmp-gen3x2-pcie-phy - - qcom,sm8250-qmp-modem-pcie-phy - - qcom,sm8450-qmp-gen4x2-pcie-phy - then: - patternProperties: - "^phy@[0-9a-f]+$": - properties: - reg: - items: - - description: TX lane 1 - - description: RX lane 1 - - description: PCS - - description: TX lane 2 - - description: RX lane 2 - - description: PCS_MISC - - - if: - properties: - compatible: - contains: - enum: - - qcom,sdm845-qmp-pcie-phy - - qcom,sdx55-qmp-pcie-phy - - qcom,sm8250-qmp-gen3x1-pcie-phy - - qcom,sm8450-qmp-gen3x1-pcie-phy - then: - patternProperties: - "^phy@[0-9a-f]+$": - properties: - reg: - items: - - description: TX - - description: RX - - description: PCS - - description: PCS_MISC - - - if: - properties: - compatible: - contains: - enum: - - qcom,ipq6018-qmp-pcie-phy - - qcom,ipq8074-qmp-pcie-phy - - qcom,msm8998-qmp-pcie-phy - - qcom,sdm845-qhp-pcie-phy - then: - patternProperties: - "^phy@[0-9a-f]+$": - properties: - reg: - items: - - description: TX - - description: RX - - description: PCS - examples: - | - #include <dt-bindings/clock/qcom,gcc-sm8250.h> - phy-wrapper@1c0e000 { - compatible = "qcom,sm8250-qmp-gen3x2-pcie-phy"; - reg = <0x01c0e000 0x1c0>; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0x0 0x01c0e000 0x1000>; - - clocks = <&gcc GCC_PCIE_PHY_AUX_CLK>, - <&gcc GCC_PCIE_1_CFG_AHB_CLK>, - <&gcc GCC_PCIE_WIGIG_CLKREF_EN>, - <&gcc GCC_PCIE1_PHY_REFGEN_CLK>; - clock-names = "aux", "cfg_ahb", "ref", "refgen"; - - resets = <&gcc GCC_PCIE_1_PHY_BCR>; - reset-names = "phy"; + #include <dt-bindings/clock/qcom,gcc-ipq6018.h> + #include <dt-bindings/reset/qcom,gcc-ipq6018.h> - vdda-phy-supply = <&vreg_l10c_0p88>; - vdda-pll-supply = <&vreg_l6b_1p2>; + phy@84000 { + compatible = "qcom,ipq6018-qmp-pcie-phy"; + reg = <0x00084000 0x1000>; - phy@200 { - reg = <0x200 0x170>, - <0x400 0x200>, - <0xa00 0x1f0>, - <0x600 0x170>, - <0x800 0x200>, - <0xe00 0xf4>; + clocks = <&gcc GCC_PCIE0_AUX_CLK>, + <&gcc GCC_PCIE0_AHB_CLK>, + <&gcc GCC_PCIE0_PIPE_CLK>; + clock-names = "aux", + "cfg_ahb", + "pipe"; - clocks = <&gcc GCC_PCIE_1_PIPE_CLK>; + clock-output-names = "gcc_pcie0_pipe_clk_src"; + #clock-cells = <0>; - #clock-cells = <0>; - clock-output-names = "pcie_1_pipe_clk"; + #phy-cells = <0>; - #phy-cells = <0>; - }; + resets = <&gcc GCC_PCIE0_PHY_BCR>, + <&gcc GCC_PCIE0PHY_PHY_BCR>; + reset-names = "phy", + "common"; }; diff --git a/Documentation/devicetree/bindings/phy/qcom,msm8996-qmp-ufs-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,msm8996-qmp-ufs-phy.yaml deleted file mode 100644 index 881ba543fd46..000000000000 --- a/Documentation/devicetree/bindings/phy/qcom,msm8996-qmp-ufs-phy.yaml +++ /dev/null @@ -1,228 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/phy/qcom,msm8996-qmp-ufs-phy.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Qualcomm QMP PHY controller (UFS, MSM8996) - -maintainers: - - Vinod Koul <vkoul@kernel.org> - -description: - QMP PHY controller supports physical layer functionality for a number of - controllers on Qualcomm chipsets, such as, PCIe, UFS, and USB. - - Note that these bindings are for SoCs up to SC8180X. For newer SoCs, see - qcom,sc8280xp-qmp-ufs-phy.yaml. - -properties: - compatible: - enum: - - qcom,msm8996-qmp-ufs-phy - - qcom,msm8998-qmp-ufs-phy - - qcom,sc8180x-qmp-ufs-phy - - qcom,sdm845-qmp-ufs-phy - - qcom,sm6115-qmp-ufs-phy - - qcom,sm6350-qmp-ufs-phy - - qcom,sm8150-qmp-ufs-phy - - qcom,sm8250-qmp-ufs-phy - - qcom,sm8350-qmp-ufs-phy - - qcom,sm8450-qmp-ufs-phy - - reg: - items: - - description: serdes - - "#address-cells": - enum: [ 1, 2 ] - - "#size-cells": - enum: [ 1, 2 ] - - ranges: true - - clocks: - minItems: 1 - maxItems: 3 - - clock-names: - minItems: 1 - maxItems: 3 - - power-domains: - maxItems: 1 - - resets: - maxItems: 1 - - reset-names: - items: - - const: ufsphy - - vdda-phy-supply: true - - vdda-pll-supply: true - - vddp-ref-clk-supply: true - -patternProperties: - "^phy@[0-9a-f]+$": - type: object - description: single PHY-provider child node - properties: - reg: - minItems: 3 - maxItems: 6 - - "#clock-cells": - const: 1 - - "#phy-cells": - const: 0 - - required: - - reg - - "#phy-cells" - - additionalProperties: false - -required: - - compatible - - reg - - "#address-cells" - - "#size-cells" - - ranges - - clocks - - clock-names - - resets - - reset-names - - vdda-phy-supply - - vdda-pll-supply - -additionalProperties: false - -allOf: - - if: - properties: - compatible: - contains: - enum: - - qcom,msm8996-qmp-ufs-phy - then: - properties: - clocks: - maxItems: 1 - clock-names: - items: - - const: ref - - - if: - properties: - compatible: - contains: - enum: - - qcom,msm8998-qmp-ufs-phy - - qcom,sc8180x-qmp-ufs-phy - - qcom,sdm845-qmp-ufs-phy - - qcom,sm6115-qmp-ufs-phy - - qcom,sm6350-qmp-ufs-phy - - qcom,sm8150-qmp-ufs-phy - - qcom,sm8250-qmp-ufs-phy - then: - properties: - clocks: - maxItems: 2 - clock-names: - items: - - const: ref - - const: ref_aux - - - if: - properties: - compatible: - contains: - enum: - - qcom,sm8450-qmp-ufs-phy - then: - properties: - clocks: - maxItems: 3 - clock-names: - items: - - const: ref - - const: ref_aux - - const: qref - - - if: - properties: - compatible: - contains: - enum: - - qcom,msm8998-qmp-ufs-phy - - qcom,sc8180x-qmp-ufs-phy - - qcom,sdm845-qmp-ufs-phy - - qcom,sm6350-qmp-ufs-phy - - qcom,sm8150-qmp-ufs-phy - - qcom,sm8250-qmp-ufs-phy - - qcom,sm8350-qmp-ufs-phy - - qcom,sm8450-qmp-ufs-phy - then: - patternProperties: - "^phy@[0-9a-f]+$": - properties: - reg: - items: - - description: TX lane 1 - - description: RX lane 1 - - description: PCS - - description: TX lane 2 - - description: RX lane 2 - - - if: - properties: - compatible: - contains: - enum: - - qcom,msm8996-qmp-ufs-phy - - qcom,sm6115-qmp-ufs-phy - then: - patternProperties: - "^phy@[0-9a-f]+$": - properties: - reg: - items: - - description: TX - - description: RX - - description: PCS - -examples: - - | - #include <dt-bindings/clock/qcom,gcc-sm8250.h> - #include <dt-bindings/clock/qcom,rpmh.h> - - phy-wrapper@1d87000 { - compatible = "qcom,sm8250-qmp-ufs-phy"; - reg = <0x01d87000 0x1c0>; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0x0 0x01d87000 0x1000>; - - clocks = <&rpmhcc RPMH_CXO_CLK>, <&gcc GCC_UFS_PHY_PHY_AUX_CLK>; - clock-names = "ref", "ref_aux"; - - resets = <&ufs_mem_hc 0>; - reset-names = "ufsphy"; - - vdda-phy-supply = <&vreg_l6b>; - vdda-pll-supply = <&vreg_l3b>; - - phy@400 { - reg = <0x400 0x108>, - <0x600 0x1e0>, - <0xc00 0x1dc>, - <0x800 0x108>, - <0xa00 0x1e0>; - #phy-cells = <0>; - }; - }; diff --git a/Documentation/devicetree/bindings/phy/qcom,msm8996-qmp-usb3-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,msm8996-qmp-usb3-phy.yaml index 4c96dab5b9e3..827109d37041 100644 --- a/Documentation/devicetree/bindings/phy/qcom,msm8996-qmp-usb3-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,msm8996-qmp-usb3-phy.yaml @@ -23,25 +23,16 @@ properties: - qcom,ipq8074-qmp-usb3-phy - qcom,msm8996-qmp-usb3-phy - qcom,msm8998-qmp-usb3-phy - - qcom,sc7180-qmp-usb3-phy - - qcom,sc8180x-qmp-usb3-phy - - qcom,sdm845-qmp-usb3-phy - qcom,sdm845-qmp-usb3-uni-phy - qcom,sdx55-qmp-usb3-uni-phy - qcom,sdx65-qmp-usb3-uni-phy - - qcom,sm8150-qmp-usb3-phy - qcom,sm8150-qmp-usb3-uni-phy - - qcom,sm8250-qmp-usb3-phy - qcom,sm8250-qmp-usb3-uni-phy - - qcom,sm8350-qmp-usb3-phy - qcom,sm8350-qmp-usb3-uni-phy - - qcom,sm8450-qmp-usb3-phy reg: - minItems: 1 items: - description: serdes - - description: DP_COM "#address-cells": enum: [ 1, 2 ] @@ -131,28 +122,6 @@ allOf: compatible: contains: enum: - - qcom,sc7180-qmp-usb3-phy - then: - properties: - clocks: - maxItems: 4 - clock-names: - items: - - const: aux - - const: cfg_ahb - - const: ref - - const: com_aux - resets: - maxItems: 1 - reset-names: - items: - - const: phy - - - if: - properties: - compatible: - contains: - enum: - qcom,sdm845-qmp-usb3-uni-phy then: properties: @@ -202,7 +171,6 @@ allOf: compatible: contains: enum: - - qcom,sm8150-qmp-usb3-phy - qcom,sm8150-qmp-usb3-uni-phy - qcom,sm8250-qmp-usb3-uni-phy - qcom,sm8350-qmp-usb3-uni-phy @@ -228,51 +196,6 @@ allOf: compatible: contains: enum: - - qcom,sm8250-qmp-usb3-phy - - qcom,sm8350-qmp-usb3-phy - then: - properties: - clocks: - maxItems: 3 - clock-names: - items: - - const: aux - - const: ref_clk_src - - const: com_aux - resets: - maxItems: 2 - reset-names: - items: - - const: phy - - const: common - - - if: - properties: - compatible: - contains: - enum: - - qcom,sdm845-qmp-usb3-phy - - qcom,sm8150-qmp-usb3-phy - - qcom,sm8350-qmp-usb3-phy - - qcom,sm8450-qmp-usb3-phy - then: - patternProperties: - "^phy@[0-9a-f]+$": - properties: - reg: - items: - - description: TX lane 1 - - description: RX lane 1 - - description: PCS - - description: TX lane 2 - - description: RX lane 2 - - description: PCS_MISC - - - if: - properties: - compatible: - contains: - enum: - qcom,msm8998-qmp-usb3-phy then: patternProperties: @@ -293,12 +216,9 @@ allOf: enum: - qcom,ipq6018-qmp-usb3-phy - qcom,ipq8074-qmp-usb3-phy - - qcom,sc7180-qmp-usb3-phy - - qcom,sc8180x-qmp-usb3-phy - qcom,sdx55-qmp-usb3-uni-phy - qcom,sdx65-qmp-usb3-uni-phy - qcom,sm8150-qmp-usb3-uni-phy - - qcom,sm8250-qmp-usb3-phy then: patternProperties: "^phy@[0-9a-f]+$": diff --git a/Documentation/devicetree/bindings/phy/qcom,msm8998-qmp-pcie-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,msm8998-qmp-pcie-phy.yaml new file mode 100644 index 000000000000..d05eef0e1ccd --- /dev/null +++ b/Documentation/devicetree/bindings/phy/qcom,msm8998-qmp-pcie-phy.yaml @@ -0,0 +1,97 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/qcom,msm8998-qmp-pcie-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm QMP PHY controller (PCIe, MSM8998) + +maintainers: + - Vinod Koul <vkoul@kernel.org> + +description: + The QMP PHY controller supports physical layer functionality for a number of + controllers on Qualcomm chipsets, such as, PCIe, UFS, and USB. + +properties: + compatible: + const: qcom,msm8998-qmp-pcie-phy + + reg: + items: + - description: serdes + + clocks: + maxItems: 4 + + clock-names: + items: + - const: aux + - const: cfg_ahb + - const: ref + - const: pipe + + resets: + maxItems: 2 + + reset-names: + items: + - const: phy + - const: common + + vdda-phy-supply: true + + vdda-pll-supply: true + + "#clock-cells": + const: 0 + + clock-output-names: + maxItems: 1 + + "#phy-cells": + const: 0 + +required: + - compatible + - reg + - clocks + - clock-names + - resets + - reset-names + - vdda-phy-supply + - vdda-pll-supply + - "#clock-cells" + - clock-output-names + - "#phy-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-msm8998.h> + + phy@1c18000 { + compatible = "qcom,msm8998-qmp-pcie-phy"; + reg = <0x01c06000 0x1000>; + + clocks = <&gcc GCC_PCIE_PHY_AUX_CLK>, + <&gcc GCC_PCIE_0_CFG_AHB_CLK>, + <&gcc GCC_PCIE_CLKREF_CLK>, + <&gcc GCC_PCIE_0_PIPE_CLK>; + clock-names = "aux", + "cfg_ahb", + "ref", + "pipe"; + + clock-output-names = "pcie_0_pipe_clk_src"; + #clock-cells = <0>; + + #phy-cells = <0>; + + resets = <&gcc GCC_PCIE_0_PHY_BCR>, <&gcc GCC_PCIE_PHY_BCR>; + reset-names = "phy", "common"; + + vdda-phy-supply = <&vreg_l1a_0p875>; + vdda-pll-supply = <&vreg_l2a_1p2>; + }; diff --git a/Documentation/devicetree/bindings/phy/qcom,sc7180-qmp-usb3-dp-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,sc7180-qmp-usb3-dp-phy.yaml deleted file mode 100644 index d30734338888..000000000000 --- a/Documentation/devicetree/bindings/phy/qcom,sc7180-qmp-usb3-dp-phy.yaml +++ /dev/null @@ -1,282 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) - -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/phy/qcom,sc7180-qmp-usb3-dp-phy.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Qualcomm QMP USB3 DP PHY controller (SC7180) - -description: - The QMP PHY controller supports physical layer functionality for a number of - controllers on Qualcomm chipsets, such as, PCIe, UFS and USB. - - Note that these bindings are for SoCs up to SC8180X. For newer SoCs, see - qcom,sc8280xp-qmp-usb43dp-phy.yaml. - -maintainers: - - Wesley Cheng <quic_wcheng@quicinc.com> - -properties: - compatible: - oneOf: - - enum: - - qcom,sc7180-qmp-usb3-dp-phy - - qcom,sc8180x-qmp-usb3-dp-phy - - qcom,sdm845-qmp-usb3-dp-phy - - qcom,sm8250-qmp-usb3-dp-phy - - items: - - enum: - - qcom,sc7280-qmp-usb3-dp-phy - - const: qcom,sm8250-qmp-usb3-dp-phy - - reg: - items: - - description: Address and length of PHY's USB serdes block. - - description: Address and length of the DP_COM control block. - - description: Address and length of PHY's DP serdes block. - - reg-names: - items: - - const: usb - - const: dp_com - - const: dp - - "#address-cells": - enum: [ 1, 2 ] - - "#size-cells": - enum: [ 1, 2 ] - - ranges: true - - clocks: - minItems: 3 - maxItems: 4 - - clock-names: - minItems: 3 - maxItems: 4 - - power-domains: - maxItems: 1 - - orientation-switch: - description: Flag the port as possible handler of orientation switching - type: boolean - - resets: - items: - - description: reset of phy block. - - description: phy common block reset. - - reset-names: - items: - - const: phy - - const: common - - vdda-phy-supply: - description: - Phandle to a regulator supply to PHY core block. - - vdda-pll-supply: - description: - Phandle to 1.8V regulator supply to PHY refclk pll block. - - vddp-ref-clk-supply: - description: - Phandle to a regulator supply to any specific refclk pll block. - -# Required nodes: -patternProperties: - "^usb3-phy@[0-9a-f]+$": - type: object - additionalProperties: false - description: - The USB3 PHY. - - properties: - reg: - items: - - description: Address and length of TX. - - description: Address and length of RX. - - description: Address and length of PCS. - - description: Address and length of TX2. - - description: Address and length of RX2. - - description: Address and length of pcs_misc. - - clocks: - items: - - description: pipe clock - - clock-names: - deprecated: true - items: - - const: pipe0 - - clock-output-names: - items: - - const: usb3_phy_pipe_clk_src - - '#clock-cells': - const: 0 - - '#phy-cells': - const: 0 - - required: - - reg - - clocks - - '#clock-cells' - - '#phy-cells' - - "^dp-phy@[0-9a-f]+$": - type: object - additionalProperties: false - description: - The DP PHY. - - properties: - reg: - items: - - description: Address and length of TX. - - description: Address and length of RX. - - description: Address and length of PCS. - - description: Address and length of TX2. - - description: Address and length of RX2. - - '#clock-cells': - const: 1 - - '#phy-cells': - const: 0 - - required: - - reg - - '#clock-cells' - - '#phy-cells' - -required: - - compatible - - reg - - "#address-cells" - - "#size-cells" - - ranges - - clocks - - clock-names - - resets - - reset-names - - vdda-phy-supply - - vdda-pll-supply - -allOf: - - if: - properties: - compatible: - enum: - - qcom,sc7180-qmp-usb3-dp-phy - - qcom,sdm845-qmp-usb3-dp-phy - then: - properties: - clocks: - items: - - description: Phy aux clock - - description: Phy config clock - - description: 19.2 MHz ref clk - - description: Phy common block aux clock - clock-names: - items: - - const: aux - - const: cfg_ahb - - const: ref - - const: com_aux - - - if: - properties: - compatible: - enum: - - qcom,sc8180x-qmp-usb3-dp-phy - then: - properties: - clocks: - items: - - description: Phy aux clock - - description: 19.2 MHz ref clk - - description: Phy common block aux clock - clock-names: - items: - - const: aux - - const: ref - - const: com_aux - - - if: - properties: - compatible: - enum: - - qcom,sm8250-qmp-usb3-dp-phy - then: - properties: - clocks: - items: - - description: Phy aux clock - - description: Board XO source - - description: Phy common block aux clock - clock-names: - items: - - const: aux - - const: ref_clk_src - - const: com_aux - -additionalProperties: false - -examples: - - | - #include <dt-bindings/clock/qcom,gcc-sdm845.h> - usb_1_qmpphy: phy-wrapper@88e9000 { - compatible = "qcom,sdm845-qmp-usb3-dp-phy"; - reg = <0x088e9000 0x18c>, - <0x088e8000 0x10>, - <0x088ea000 0x40>; - reg-names = "usb", "dp_com", "dp"; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0x0 0x088e9000 0x2000>; - - clocks = <&gcc GCC_USB3_PRIM_PHY_AUX_CLK>, - <&gcc GCC_USB_PHY_CFG_AHB2PHY_CLK>, - <&gcc GCC_USB3_PRIM_CLKREF_CLK>, - <&gcc GCC_USB3_PRIM_PHY_COM_AUX_CLK>; - clock-names = "aux", "cfg_ahb", "ref", "com_aux"; - - resets = <&gcc GCC_USB3_PHY_PRIM_BCR>, - <&gcc GCC_USB3_DP_PHY_PRIM_BCR>; - reset-names = "phy", "common"; - - vdda-phy-supply = <&vdda_usb2_ss_1p2>; - vdda-pll-supply = <&vdda_usb2_ss_core>; - - orientation-switch; - - usb3-phy@200 { - reg = <0x200 0x128>, - <0x400 0x200>, - <0xc00 0x218>, - <0x600 0x128>, - <0x800 0x200>, - <0xa00 0x100>; - #clock-cells = <0>; - #phy-cells = <0>; - clocks = <&gcc GCC_USB3_PRIM_PHY_PIPE_CLK>; - clock-output-names = "usb3_phy_pipe_clk_src"; - }; - - dp-phy@88ea200 { - reg = <0xa200 0x200>, - <0xa400 0x200>, - <0xaa00 0x200>, - <0xa600 0x200>, - <0xa800 0x200>; - #clock-cells = <1>; - #phy-cells = <0>; - }; - }; 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 a0407fc79563..2c3d6553a7ba 100644 --- a/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-pcie-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-pcie-phy.yaml @@ -16,11 +16,24 @@ description: properties: compatible: enum: + - qcom,sa8775p-qmp-gen4x2-pcie-phy + - qcom,sa8775p-qmp-gen4x4-pcie-phy + - qcom,sc8180x-qmp-pcie-phy - qcom,sc8280xp-qmp-gen3x1-pcie-phy - qcom,sc8280xp-qmp-gen3x2-pcie-phy - qcom,sc8280xp-qmp-gen3x4-pcie-phy + - qcom,sdm845-qhp-pcie-phy + - qcom,sdm845-qmp-pcie-phy + - qcom,sdx55-qmp-pcie-phy - qcom,sdx65-qmp-gen4x2-pcie-phy + - qcom,sm8150-qmp-gen3x1-pcie-phy + - qcom,sm8150-qmp-gen3x2-pcie-phy + - qcom,sm8250-qmp-gen3x1-pcie-phy + - qcom,sm8250-qmp-gen3x2-pcie-phy + - qcom,sm8250-qmp-modem-pcie-phy - qcom,sm8350-qmp-gen3x1-pcie-phy + - qcom,sm8450-qmp-gen3x1-pcie-phy + - qcom,sm8450-qmp-gen4x2-pcie-phy - qcom,sm8550-qmp-gen3x2-pcie-phy - qcom,sm8550-qmp-gen4x2-pcie-phy @@ -30,7 +43,7 @@ properties: clocks: minItems: 5 - maxItems: 6 + maxItems: 7 clock-names: minItems: 5 @@ -38,9 +51,10 @@ properties: - const: aux - const: cfg_ahb - const: ref - - const: rchng + - enum: [rchng, refgen] - const: pipe - const: pipediv2 + - const: phy_aux power-domains: maxItems: 1 @@ -84,7 +98,6 @@ required: - reg - clocks - clock-names - - power-domains - resets - reset-names - vdda-phy-supply @@ -120,7 +133,18 @@ allOf: compatible: contains: enum: + - qcom,sc8180x-qmp-pcie-phy + - qcom,sdm845-qhp-pcie-phy + - qcom,sdm845-qmp-pcie-phy + - qcom,sdx55-qmp-pcie-phy + - qcom,sm8150-qmp-gen3x1-pcie-phy + - qcom,sm8150-qmp-gen3x2-pcie-phy + - qcom,sm8250-qmp-gen3x1-pcie-phy + - qcom,sm8250-qmp-gen3x2-pcie-phy + - qcom,sm8250-qmp-modem-pcie-phy - qcom,sm8350-qmp-gen3x1-pcie-phy + - qcom,sm8450-qmp-gen3x1-pcie-phy + - qcom,sm8450-qmp-gen3x2-pcie-phy - qcom,sm8550-qmp-gen3x2-pcie-phy - qcom,sm8550-qmp-gen4x2-pcie-phy then: @@ -129,7 +153,16 @@ allOf: maxItems: 5 clock-names: maxItems: 5 - else: + + - if: + properties: + compatible: + contains: + enum: + - qcom,sc8280xp-qmp-gen3x1-pcie-phy + - qcom,sc8280xp-qmp-gen3x2-pcie-phy + - qcom,sc8280xp-qmp-gen3x4-pcie-phy + then: properties: clocks: minItems: 6 @@ -141,6 +174,20 @@ allOf: compatible: contains: enum: + - qcom,sa8775p-qmp-gen4x2-pcie-phy + - qcom,sa8775p-qmp-gen4x4-pcie-phy + then: + properties: + clocks: + minItems: 7 + clock-names: + minItems: 7 + + - if: + properties: + compatible: + contains: + enum: - qcom,sm8550-qmp-gen4x2-pcie-phy then: properties: 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 a1897a7606df..d981d77e82e4 100644 --- a/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-ufs-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-ufs-phy.yaml @@ -16,21 +16,31 @@ description: properties: compatible: enum: + - qcom,msm8996-qmp-ufs-phy + - qcom,msm8998-qmp-ufs-phy - qcom,sa8775p-qmp-ufs-phy + - qcom,sc8180x-qmp-ufs-phy - qcom,sc8280xp-qmp-ufs-phy + - qcom,sdm845-qmp-ufs-phy + - qcom,sm6115-qmp-ufs-phy - qcom,sm6125-qmp-ufs-phy + - qcom,sm6350-qmp-ufs-phy - qcom,sm7150-qmp-ufs-phy + - 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 reg: maxItems: 1 clocks: - minItems: 2 + minItems: 1 maxItems: 3 clock-names: - minItems: 2 + minItems: 1 items: - const: ref - const: ref_aux @@ -75,19 +85,51 @@ allOf: contains: enum: - qcom,sa8775p-qmp-ufs-phy + - qcom,sm8450-qmp-ufs-phy then: properties: clocks: minItems: 3 clock-names: minItems: 3 - else: + + - 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 + - qcom,sm6115-qmp-ufs-phy + - qcom,sm6125-qmp-ufs-phy + - qcom,sm6350-qmp-ufs-phy + - qcom,sm7150-qmp-ufs-phy + - qcom,sm8150-qmp-ufs-phy + - qcom,sm8250-qmp-ufs-phy + - qcom,sm8350-qmp-ufs-phy + - qcom,sm8550-qmp-ufs-phy + then: properties: clocks: maxItems: 2 clock-names: maxItems: 2 + - if: + properties: + compatible: + contains: + enum: + - qcom,msm8996-qmp-ufs-phy + then: + properties: + clocks: + maxItems: 1 + clock-names: + maxItems: 1 + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-usb43dp-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-usb43dp-phy.yaml index ef1c02d8ac88..9af203dc8793 100644 --- a/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-usb43dp-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-usb43dp-phy.yaml @@ -16,8 +16,14 @@ description: properties: compatible: enum: + - qcom,sc7180-qmp-usb3-dp-phy + - qcom,sc7280-qmp-usb3-dp-phy + - qcom,sc8180x-qmp-usb3-dp-phy - qcom,sc8280xp-qmp-usb43dp-phy + - qcom,sdm845-qmp-usb3-dp-phy - qcom,sm6350-qmp-usb3-dp-phy + - qcom,sm8150-qmp-usb3-dp-phy + - qcom,sm8250-qmp-usb3-dp-phy - qcom,sm8350-qmp-usb3-dp-phy - qcom,sm8450-qmp-usb3-dp-phy - qcom,sm8550-qmp-usb3-dp-phy @@ -26,14 +32,17 @@ properties: maxItems: 1 clocks: - maxItems: 4 + minItems: 4 + maxItems: 5 clock-names: + minItems: 4 items: - const: aux - const: ref - const: com_aux - const: usb3_pipe + - const: cfg_ahb power-domains: maxItems: 1 @@ -85,7 +94,6 @@ required: - reg - clocks - clock-names - - power-domains - resets - reset-names - vdda-phy-supply @@ -93,6 +101,40 @@ required: - "#clock-cells" - "#phy-cells" +allOf: + - if: + properties: + compatible: + enum: + - qcom,sc7180-qmp-usb3-dp-phy + - qcom,sdm845-qmp-usb3-dp-phy + then: + properties: + clocks: + maxItems: 5 + clock-names: + maxItems: 5 + else: + properties: + clocks: + maxItems: 4 + clock-names: + maxItems: 4 + + - if: + properties: + compatible: + enum: + - qcom,sc8280xp-qmp-usb43dp-phy + - qcom,sm6350-qmp-usb3-dp-phy + - qcom,sm8550-qmp-usb3-dp-phy + then: + required: + - power-domains + else: + properties: + power-domains: false + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/phy/qcom,snps-eusb2-repeater.yaml b/Documentation/devicetree/bindings/phy/qcom,snps-eusb2-repeater.yaml index 083fda530b48..029569d5fcf3 100644 --- a/Documentation/devicetree/bindings/phy/qcom,snps-eusb2-repeater.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,snps-eusb2-repeater.yaml @@ -15,7 +15,12 @@ description: properties: compatible: - const: qcom,pm8550b-eusb2-repeater + oneOf: + - items: + - enum: + - qcom,pm7550ba-eusb2-repeater + - const: qcom,pm8550b-eusb2-repeater + - const: qcom,pm8550b-eusb2-repeater reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/phy/realtek,usb2phy.yaml b/Documentation/devicetree/bindings/phy/realtek,usb2phy.yaml new file mode 100644 index 000000000000..9911ada39ee7 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/realtek,usb2phy.yaml @@ -0,0 +1,175 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2023 Realtek Semiconductor Corporation +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/realtek,usb2phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Realtek DHC SoCs USB 2.0 PHY + +maintainers: + - Stanley Chang <stanley_chang@realtek.com> + +description: | + Realtek USB 2.0 PHY support the digital home center (DHC) RTD series SoCs. + The USB 2.0 PHY driver is designed to support the XHCI controller. The SoCs + support multiple XHCI controllers. One PHY device node maps to one XHCI + controller. + + RTD1295/RTD1619 SoCs USB + The USB architecture includes three XHCI controllers. + Each XHCI maps to one USB 2.0 PHY and map one USB 3.0 PHY on some + controllers. + XHCI controller#0 -- usb2phy -- phy#0 + |- usb3phy -- phy#0 + XHCI controller#1 -- usb2phy -- phy#0 + XHCI controller#2 -- usb2phy -- phy#0 + |- usb3phy -- phy#0 + + RTD1395 SoCs USB + The USB architecture includes two XHCI controllers. + The controller#0 has one USB 2.0 PHY. The controller#1 includes two USB 2.0 + PHY. + XHCI controller#0 -- usb2phy -- phy#0 + XHCI controller#1 -- usb2phy -- phy#0 + |- phy#1 + + RTD1319/RTD1619b SoCs USB + The USB architecture includes three XHCI controllers. + Each XHCI maps to one USB 2.0 PHY and map one USB 3.0 PHY on controllers#2. + XHCI controller#0 -- usb2phy -- phy#0 + XHCI controller#1 -- usb2phy -- phy#0 + XHCI controller#2 -- usb2phy -- phy#0 + |- usb3phy -- phy#0 + + RTD1319d SoCs USB + The USB architecture includes three XHCI controllers. + Each xhci maps to one USB 2.0 PHY and map one USB 3.0 PHY on controllers#0. + XHCI controller#0 -- usb2phy -- phy#0 + |- usb3phy -- phy#0 + XHCI controller#1 -- usb2phy -- phy#0 + XHCI controller#2 -- usb2phy -- phy#0 + + RTD1312c/RTD1315e SoCs USB + The USB architecture includes three XHCI controllers. + Each XHCI maps to one USB 2.0 PHY. + XHCI controller#0 -- usb2phy -- phy#0 + XHCI controller#1 -- usb2phy -- phy#0 + XHCI controller#2 -- usb2phy -- phy#0 + +properties: + compatible: + enum: + - realtek,rtd1295-usb2phy + - realtek,rtd1312c-usb2phy + - realtek,rtd1315e-usb2phy + - realtek,rtd1319-usb2phy + - realtek,rtd1319d-usb2phy + - realtek,rtd1395-usb2phy + - realtek,rtd1395-usb2phy-2port + - realtek,rtd1619-usb2phy + - realtek,rtd1619b-usb2phy + + reg: + items: + - description: PHY data registers + - description: PHY control registers + + "#phy-cells": + const: 0 + + nvmem-cells: + maxItems: 2 + description: + Phandles to nvmem cell that contains the trimming data. + If unspecified, default value is used. + + nvmem-cell-names: + items: + - const: usb-dc-cal + - const: usb-dc-dis + description: + The following names, which correspond to each nvmem-cells. + usb-dc-cal is the driving level for each phy specified via efuse. + usb-dc-dis is the disconnection level for each phy specified via efuse. + + realtek,inverse-hstx-sync-clock: + description: + For one of the phys of RTD1619b SoC, the synchronous clock of the + high-speed tx must be inverted. + type: boolean + + realtek,driving-level: + description: + Control the magnitude of High speed Dp/Dm output swing (mV). + For a different board or port, the original magnitude maybe not meet + the specification. In this situation we can adjust the value to meet + the specification. + $ref: /schemas/types.yaml#/definitions/uint32 + default: 8 + minimum: 0 + maximum: 31 + + realtek,driving-level-compensate: + description: + For RTD1315e SoC, the driving level can be adjusted by reading the + efuse table. This property provides drive compensation. + If the magnitude of High speed Dp/Dm output swing still not meet the + specification, then we can set this value to meet the specification. + $ref: /schemas/types.yaml#/definitions/int32 + default: 0 + minimum: -8 + maximum: 8 + + realtek,disconnection-compensate: + description: + This adjusts the disconnection level compensation for the different + boards with different disconnection level. + $ref: /schemas/types.yaml#/definitions/int32 + default: 0 + minimum: -8 + maximum: 8 + +required: + - compatible + - reg + - "#phy-cells" + +allOf: + - if: + not: + properties: + compatible: + contains: + enum: + - realtek,rtd1619b-usb2phy + then: + properties: + realtek,inverse-hstx-sync-clock: false + + - if: + not: + properties: + compatible: + contains: + enum: + - realtek,rtd1315e-usb2phy + then: + properties: + realtek,driving-level-compensate: false + +additionalProperties: false + +examples: + - | + usb-phy@13214 { + compatible = "realtek,rtd1619b-usb2phy"; + reg = <0x13214 0x4>, <0x28280 0x4>; + #phy-cells = <0>; + nvmem-cells = <&otp_usb_port0_dc_cal>, <&otp_usb_port0_dc_dis>; + nvmem-cell-names = "usb-dc-cal", "usb-dc-dis"; + + realtek,inverse-hstx-sync-clock; + realtek,driving-level = <0xa>; + realtek,disconnection-compensate = <(-1)>; + }; diff --git a/Documentation/devicetree/bindings/phy/realtek,usb3phy.yaml b/Documentation/devicetree/bindings/phy/realtek,usb3phy.yaml new file mode 100644 index 000000000000..dfe2bb4e59e7 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/realtek,usb3phy.yaml @@ -0,0 +1,107 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2023 Realtek Semiconductor Corporation +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/realtek,usb3phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Realtek DHC SoCs USB 3.0 PHY + +maintainers: + - Stanley Chang <stanley_chang@realtek.com> + +description: | + Realtek USB 3.0 PHY support the digital home center (DHC) RTD series SoCs. + The USB 3.0 PHY driver is designed to support the XHCI controller. The SoCs + support multiple XHCI controllers. One PHY device node maps to one XHCI + controller. + + RTD1295/RTD1619 SoCs USB + The USB architecture includes three XHCI controllers. + Each XHCI maps to one USB 2.0 PHY and map one USB 3.0 PHY on some + controllers. + XHCI controller#0 -- usb2phy -- phy#0 + |- usb3phy -- phy#0 + XHCI controller#1 -- usb2phy -- phy#0 + XHCI controller#2 -- usb2phy -- phy#0 + |- usb3phy -- phy#0 + + RTD1319/RTD1619b SoCs USB + The USB architecture includes three XHCI controllers. + Each XHCI maps to one USB 2.0 PHY and map one USB 3.0 PHY on controllers#2. + XHCI controller#0 -- usb2phy -- phy#0 + XHCI controller#1 -- usb2phy -- phy#0 + XHCI controller#2 -- usb2phy -- phy#0 + |- usb3phy -- phy#0 + + RTD1319d SoCs USB + The USB architecture includes three XHCI controllers. + Each xhci maps to one USB 2.0 PHY and map one USB 3.0 PHY on controllers#0. + XHCI controller#0 -- usb2phy -- phy#0 + |- usb3phy -- phy#0 + XHCI controller#1 -- usb2phy -- phy#0 + XHCI controller#2 -- usb2phy -- phy#0 + +properties: + compatible: + enum: + - realtek,rtd1295-usb3phy + - realtek,rtd1319-usb3phy + - realtek,rtd1319d-usb3phy + - realtek,rtd1619-usb3phy + - realtek,rtd1619b-usb3phy + + reg: + maxItems: 1 + + "#phy-cells": + const: 0 + + nvmem-cells: + maxItems: 1 + description: A phandle to the tx lfps swing trim data provided by + a nvmem device, if unspecified, default values shall be used. + + nvmem-cell-names: + items: + - const: usb_u3_tx_lfps_swing_trim + + realtek,amplitude-control-coarse-tuning: + description: + This adjusts the signal amplitude for normal operation and beacon LFPS. + This value is a parameter for coarse tuning. + For different boards, if the default value is inappropriate, this + property can be assigned to adjust. + $ref: /schemas/types.yaml#/definitions/uint32 + default: 255 + minimum: 0 + maximum: 255 + + realtek,amplitude-control-fine-tuning: + description: + This adjusts the signal amplitude for normal operation and beacon LFPS. + This value is used for fine-tuning parameters. + $ref: /schemas/types.yaml#/definitions/uint32 + default: 65535 + minimum: 0 + maximum: 65535 + +required: + - compatible + - reg + - "#phy-cells" + +additionalProperties: false + +examples: + - | + usb-phy@13e10 { + compatible = "realtek,rtd1319d-usb3phy"; + reg = <0x13e10 0x4>; + #phy-cells = <0>; + + nvmem-cells = <&otp_usb_u3_tx_lfps_swing_trim>; + nvmem-cell-names = "usb_u3_tx_lfps_swing_trim"; + + realtek,amplitude-control-coarse-tuning = <0x77>; + }; diff --git a/Documentation/devicetree/bindings/phy/rockchip,inno-usb2phy.yaml b/Documentation/devicetree/bindings/phy/rockchip,inno-usb2phy.yaml index 0d6b8c28be07..5254413137c6 100644 --- a/Documentation/devicetree/bindings/phy/rockchip,inno-usb2phy.yaml +++ b/Documentation/devicetree/bindings/phy/rockchip,inno-usb2phy.yaml @@ -20,6 +20,7 @@ properties: - rockchip,rk3366-usb2phy - rockchip,rk3399-usb2phy - rockchip,rk3568-usb2phy + - rockchip,rk3588-usb2phy - rockchip,rv1108-usb2phy reg: @@ -56,6 +57,14 @@ properties: description: Muxed interrupt for both ports maxItems: 1 + resets: + maxItems: 2 + + reset-names: + items: + - const: phy + - const: apb + rockchip,usbgrf: $ref: /schemas/types.yaml#/definitions/phandle description: @@ -120,15 +129,21 @@ required: - reg - clock-output-names - "#clock-cells" - - host-port - - otg-port + +anyOf: + - required: + - otg-port + - required: + - host-port allOf: - if: properties: compatible: contains: - const: rockchip,rk3568-usb2phy + enum: + - rockchip,rk3568-usb2phy + - rockchip,rk3588-usb2phy then: properties: diff --git a/Documentation/devicetree/bindings/phy/rockchip,pcie3-phy.yaml b/Documentation/devicetree/bindings/phy/rockchip,pcie3-phy.yaml index 9f2d8d2cc7a5..c4fbffcde6e4 100644 --- a/Documentation/devicetree/bindings/phy/rockchip,pcie3-phy.yaml +++ b/Documentation/devicetree/bindings/phy/rockchip,pcie3-phy.yaml @@ -13,19 +13,18 @@ properties: compatible: enum: - rockchip,rk3568-pcie3-phy + - rockchip,rk3588-pcie3-phy reg: maxItems: 1 clocks: - minItems: 3 + minItems: 1 maxItems: 3 clock-names: - items: - - const: refclk_m - - const: refclk_n - - const: pclk + minItems: 1 + maxItems: 3 data-lanes: description: which lanes (by position) should be mapped to which @@ -61,6 +60,30 @@ required: - rockchip,phy-grf - "#phy-cells" +allOf: + - if: + properties: + compatible: + enum: + - rockchip,rk3588-pcie3-phy + then: + properties: + clocks: + maxItems: 1 + clock-names: + items: + - const: pclk + else: + properties: + clocks: + minItems: 3 + + clock-names: + items: + - const: refclk_m + - const: refclk_n + - const: pclk + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/phy/rockchip,px30-dsi-dphy.yaml b/Documentation/devicetree/bindings/phy/rockchip,px30-dsi-dphy.yaml index 5c35e5ceec0b..46e64fa293d5 100644 --- a/Documentation/devicetree/bindings/phy/rockchip,px30-dsi-dphy.yaml +++ b/Documentation/devicetree/bindings/phy/rockchip,px30-dsi-dphy.yaml @@ -19,6 +19,7 @@ properties: - rockchip,rk3128-dsi-dphy - rockchip,rk3368-dsi-dphy - rockchip,rk3568-dsi-dphy + - rockchip,rv1126-dsi-dphy reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/phy/rockchip-inno-csi-dphy.yaml b/Documentation/devicetree/bindings/phy/rockchip-inno-csi-dphy.yaml index 0e6505e9da50..5ac994b3c0aa 100644 --- a/Documentation/devicetree/bindings/phy/rockchip-inno-csi-dphy.yaml +++ b/Documentation/devicetree/bindings/phy/rockchip-inno-csi-dphy.yaml @@ -10,7 +10,7 @@ maintainers: - Heiko Stuebner <heiko@sntech.de> description: | - The Rockchip SoC has a MIPI CSI D-PHY based on an Innosilicon IP wich + The Rockchip SoC has a MIPI CSI D-PHY based on an Innosilicon IP which connects to the ISP1 (Image Signal Processing unit v1.0) for CSI cameras. properties: diff --git a/Documentation/devicetree/bindings/phy/samsung,usb3-drd-phy.yaml b/Documentation/devicetree/bindings/phy/samsung,usb3-drd-phy.yaml index 5ba55f9f20cc..452e584d9812 100644 --- a/Documentation/devicetree/bindings/phy/samsung,usb3-drd-phy.yaml +++ b/Documentation/devicetree/bindings/phy/samsung,usb3-drd-phy.yaml @@ -29,6 +29,7 @@ properties: - samsung,exynos5420-usbdrd-phy - samsung,exynos5433-usbdrd-phy - samsung,exynos7-usbdrd-phy + - samsung,exynos850-usbdrd-phy clocks: minItems: 2 diff --git a/Documentation/devicetree/bindings/phy/starfive,jh7110-dphy-rx.yaml b/Documentation/devicetree/bindings/phy/starfive,jh7110-dphy-rx.yaml new file mode 100644 index 000000000000..7224cde6fce0 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/starfive,jh7110-dphy-rx.yaml @@ -0,0 +1,71 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/starfive,jh7110-dphy-rx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive SoC JH7110 MIPI D-PHY Rx Controller + +maintainers: + - Jack Zhu <jack.zhu@starfivetech.com> + - Changhuang Liang <changhuang.liang@starfivetech.com> + +description: + StarFive SoCs contain a MIPI CSI D-PHY based on M31 IP, used to + transfer CSI camera data. + +properties: + compatible: + const: starfive,jh7110-dphy-rx + + reg: + maxItems: 1 + + clocks: + items: + - description: config clock + - description: reference clock + - description: escape mode transmit clock + + clock-names: + items: + - const: cfg + - const: ref + - const: tx + + resets: + items: + - description: DPHY_HW reset + - description: DPHY_B09_ALWAYS_ON reset + + power-domains: + maxItems: 1 + + "#phy-cells": + const: 0 + +required: + - compatible + - reg + - clocks + - clock-names + - resets + - power-domains + - "#phy-cells" + +additionalProperties: false + +examples: + - | + phy@19820000 { + compatible = "starfive,jh7110-dphy-rx"; + reg = <0x19820000 0x10000>; + clocks = <&ispcrg 3>, + <&ispcrg 4>, + <&ispcrg 5>; + clock-names = "cfg", "ref", "tx"; + resets = <&ispcrg 2>, + <&ispcrg 3>; + power-domains = <&aon_syscon 1>; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/starfive,jh7110-pcie-phy.yaml b/Documentation/devicetree/bindings/phy/starfive,jh7110-pcie-phy.yaml new file mode 100644 index 000000000000..2e83a6164cd1 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/starfive,jh7110-pcie-phy.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/starfive,jh7110-pcie-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive JH7110 PCIe 2.0 PHY + +maintainers: + - Minda Chen <minda.chen@starfivetech.com> + +properties: + compatible: + const: starfive,jh7110-pcie-phy + + reg: + maxItems: 1 + + "#phy-cells": + const: 0 + + starfive,sys-syscon: + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + - items: + - description: phandle to System Register Controller sys_syscon node. + - description: PHY connect offset of SYS_SYSCONSAIF__SYSCFG register for USB PHY. + description: + The phandle to System Register Controller syscon node and the PHY connect offset + of SYS_SYSCONSAIF__SYSCFG register. Connect PHY to USB3 controller. + + starfive,stg-syscon: + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + - items: + - description: phandle to System Register Controller stg_syscon node. + - description: PHY mode offset of STG_SYSCONSAIF__SYSCFG register. + - description: PHY enable for USB offset of STG_SYSCONSAIF__SYSCFG register. + description: + The phandle to System Register Controller syscon node and the offset + of STG_SYSCONSAIF__SYSCFG register for PCIe PHY. Total 2 regsisters offset. + +required: + - compatible + - reg + - "#phy-cells" + +additionalProperties: false + +examples: + - | + phy@10210000 { + compatible = "starfive,jh7110-pcie-phy"; + reg = <0x10210000 0x10000>; + #phy-cells = <0>; + starfive,sys-syscon = <&sys_syscon 0x18>; + starfive,stg-syscon = <&stg_syscon 0x148 0x1f4>; + }; diff --git a/Documentation/devicetree/bindings/phy/starfive,jh7110-usb-phy.yaml b/Documentation/devicetree/bindings/phy/starfive,jh7110-usb-phy.yaml new file mode 100644 index 000000000000..269e9f9f12b6 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/starfive,jh7110-usb-phy.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/starfive,jh7110-usb-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive JH7110 USB 2.0 PHY + +maintainers: + - Minda Chen <minda.chen@starfivetech.com> + +properties: + compatible: + const: starfive,jh7110-usb-phy + + reg: + maxItems: 1 + + "#phy-cells": + const: 0 + + clocks: + items: + - description: PHY 125m + - description: app 125m + + clock-names: + items: + - const: 125m + - const: app_125m + +required: + - compatible + - reg + - clocks + - clock-names + - "#phy-cells" + +additionalProperties: false + +examples: + - | + phy@10200000 { + compatible = "starfive,jh7110-usb-phy"; + reg = <0x10200000 0x10000>; + clocks = <&syscrg 95>, + <&stgcrg 6>; + clock-names = "125m", "app_125m"; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml b/Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml index 9ea30eaba314..3f16ff14484d 100644 --- a/Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml +++ b/Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml @@ -59,7 +59,7 @@ properties: description: GPIO to signal Type-C cable orientation for lane swap. If GPIO is active, lane 0 and lane 1 of SERDES will be swapped to - achieve the funtionality of an external type-C plug flip mux. + achieve the functionality of an external type-C plug flip mux. typec-dir-debounce-ms: minimum: 100 diff --git a/Documentation/devicetree/bindings/phy/ti-phy.txt b/Documentation/devicetree/bindings/phy/ti-phy.txt index 60c9d0ac75e6..7c7936b89f2c 100644 --- a/Documentation/devicetree/bindings/phy/ti-phy.txt +++ b/Documentation/devicetree/bindings/phy/ti-phy.txt @@ -62,7 +62,7 @@ Deprecated properties: - ctrl-module : phandle of the control module used by PHY driver to power on the PHY. -Recommended properies: +Recommended properties: - syscon-phy-power : phandle/offset pair. Phandle to the system control module and the register offset to power on/off the PHY. diff --git a/Documentation/devicetree/bindings/pinctrl/allwinner,sun4i-a10-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/allwinner,sun4i-a10-pinctrl.yaml index 467016cbb037..450240570314 100644 --- a/Documentation/devicetree/bindings/pinctrl/allwinner,sun4i-a10-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/allwinner,sun4i-a10-pinctrl.yaml @@ -97,7 +97,7 @@ patternProperties: # It's pretty scary, but the basic idea is that: # - One node name can start with either s- or r- for PRCM nodes, # - Then, the name itself can be any repetition of <string>- (to - # accomodate with nodes like uart4-rts-cts-pins), where each + # accommodate with nodes like uart4-rts-cts-pins), where each # string can be either starting with 'p' but in a string longer # than 3, or something that doesn't start with 'p', # - Then, the bank name is optional and will be between pa and pg, diff --git a/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-a1.yaml b/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-a1.yaml index 99080c9eaac3..4e7a456ea4cc 100644 --- a/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-a1.yaml +++ b/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-a1.yaml @@ -15,6 +15,7 @@ allOf: properties: compatible: enum: + - amlogic,c3-periphs-pinctrl - amlogic,meson-a1-periphs-pinctrl - amlogic,meson-s4-periphs-pinctrl @@ -36,6 +37,10 @@ patternProperties: - const: mux - const: gpio + gpio-line-names: + minItems: 62 # A1 + maxItems: 82 # S4 + unevaluatedProperties: type: object $ref: amlogic,meson-pinctrl-common.yaml#/$defs/meson-pins diff --git a/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-common.yaml b/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-common.yaml index a7b29ef0bab6..e707c222a07f 100644 --- a/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-common.yaml +++ b/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-common.yaml @@ -41,6 +41,13 @@ $defs: gpio-ranges: maxItems: 1 + patternProperties: + "^.+-hog(-[0-9]+)?$": + type: object + + required: + - gpio-hog + required: - reg - reg-names 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 7c9c94ec5b7b..0942ea60c6cd 100644 --- a/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-g12a-aobus.yaml +++ b/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-g12a-aobus.yaml @@ -36,6 +36,9 @@ patternProperties: - const: ds - const: gpio + gpio-line-names: + maxItems: 15 + unevaluatedProperties: type: object $ref: amlogic,meson-pinctrl-common.yaml#/$defs/meson-pins 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 4bcb8b60420f..e3c8bde30559 100644 --- a/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-g12a-periphs.yaml +++ b/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-g12a-periphs.yaml @@ -38,6 +38,9 @@ patternProperties: - const: mux - const: ds + gpio-line-names: + maxItems: 85 + unevaluatedProperties: type: object $ref: amlogic,meson-pinctrl-common.yaml#/$defs/meson-pins diff --git a/Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-aobus.yaml b/Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-aobus.yaml index 32d99c9b6afc..c1b03147e8ec 100644 --- a/Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-aobus.yaml +++ b/Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-aobus.yaml @@ -44,6 +44,10 @@ patternProperties: - const: pull - const: gpio + gpio-line-names: + minItems: 11 # GXL + maxItems: 16 # Meson8 + unevaluatedProperties: type: object $ref: amlogic,meson-pinctrl-common.yaml#/$defs/meson-pins diff --git a/Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-cbus.yaml b/Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-cbus.yaml index d0441051f34a..4ec85b8248fa 100644 --- a/Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-cbus.yaml +++ b/Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-cbus.yaml @@ -45,6 +45,10 @@ patternProperties: - const: pull-enable - const: gpio + gpio-line-names: + minItems: 86 # AXG + maxItems: 120 # Meson8 + unevaluatedProperties: type: object $ref: amlogic,meson-pinctrl-common.yaml#/$defs/meson-pins diff --git a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml index bef85c25cdef..37c0a74c7c01 100644 --- a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml @@ -25,30 +25,32 @@ properties: reg: maxItems: 2 -patternProperties: - '^.*$': - if: - type: object - then: - patternProperties: - "^function|groups$": - $ref: /schemas/types.yaml#/definitions/string - enum: [ ACPI, ADC0, ADC1, ADC10, ADC11, ADC12, ADC13, ADC14, ADC15, - ADC2, ADC3, ADC4, ADC5, ADC6, ADC7, ADC8, ADC9, BMCINT, DDCCLK, DDCDAT, - EXTRST, FLACK, FLBUSY, FLWP, GPID, GPID0, GPID2, GPID4, GPID6, GPIE0, - GPIE2, GPIE4, GPIE6, I2C10, I2C11, I2C12, I2C13, I2C14, I2C3, I2C4, - I2C5, I2C6, I2C7, I2C8, I2C9, LPCPD, LPCPME, LPCRST, LPCSMI, MAC1LINK, - MAC2LINK, MDIO1, MDIO2, NCTS1, NCTS2, NCTS3, NCTS4, NDCD1, NDCD2, - NDCD3, NDCD4, NDSR1, NDSR2, NDSR3, NDSR4, NDTR1, NDTR2, NDTR3, NDTR4, - NDTS4, NRI1, NRI2, NRI3, NRI4, NRTS1, NRTS2, NRTS3, OSCCLK, PWM0, - PWM1, PWM2, PWM3, PWM4, PWM5, PWM6, PWM7, RGMII1, RGMII2, RMII1, - RMII2, ROM16, ROM8, ROMCS1, ROMCS2, ROMCS3, ROMCS4, RXD1, RXD2, RXD3, - RXD4, SALT1, SALT2, SALT3, SALT4, SD1, SD2, SGPMCK, SGPMI, SGPMLD, - SGPMO, SGPSCK, SGPSI0, SGPSI1, SGPSLD, SIOONCTRL, SIOPBI, SIOPBO, - SIOPWREQ, SIOPWRGD, SIOS3, SIOS5, SIOSCI, SPI1, SPI1DEBUG, SPI1PASSTHRU, - SPICS1, TIMER3, TIMER4, TIMER5, TIMER6, TIMER7, TIMER8, TXD1, TXD2, - TXD3, TXD4, UART6, USB11D1, USB11H2, USB2D1, USB2H1, USBCKI, VGABIOS_ROM, - VGAHS, VGAVS, VPI18, VPI24, VPI30, VPO12, VPO24, WDTRST1, WDTRST2] +additionalProperties: + $ref: pinmux-node.yaml# + additionalProperties: false + + properties: + pins: true + bias-disable: true + + patternProperties: + "^function|groups$": + enum: [ ACPI, ADC0, ADC1, ADC10, ADC11, ADC12, ADC13, ADC14, ADC15, + ADC2, ADC3, ADC4, ADC5, ADC6, ADC7, ADC8, ADC9, BMCINT, DDCCLK, DDCDAT, + EXTRST, FLACK, FLBUSY, FLWP, GPID, GPID0, GPID2, GPID4, GPID6, GPIE0, + GPIE2, GPIE4, GPIE6, I2C10, I2C11, I2C12, I2C13, I2C14, I2C3, I2C4, + I2C5, I2C6, I2C7, I2C8, I2C9, LPCPD, LPCPME, LPCRST, LPCSMI, MAC1LINK, + MAC2LINK, MDIO1, MDIO2, NCTS1, NCTS2, NCTS3, NCTS4, NDCD1, NDCD2, + NDCD3, NDCD4, NDSR1, NDSR2, NDSR3, NDSR4, NDTR1, NDTR2, NDTR3, NDTR4, + NDTS4, NRI1, NRI2, NRI3, NRI4, NRTS1, NRTS2, NRTS3, OSCCLK, PWM0, + PWM1, PWM2, PWM3, PWM4, PWM5, PWM6, PWM7, RGMII1, RGMII2, RMII1, + RMII2, ROM16, ROM8, ROMCS1, ROMCS2, ROMCS3, ROMCS4, RXD1, RXD2, RXD3, + RXD4, SALT1, SALT2, SALT3, SALT4, SD1, SD2, SGPMCK, SGPMI, SGPMLD, + SGPMO, SGPSCK, SGPSI0, SGPSI1, SGPSLD, SIOONCTRL, SIOPBI, SIOPBO, + SIOPWREQ, SIOPWRGD, SIOS3, SIOS5, SIOSCI, SPI1, SPI1DEBUG, SPI1PASSTHRU, + SPICS1, TIMER3, TIMER4, TIMER5, TIMER6, TIMER7, TIMER8, TXD1, TXD2, + TXD3, TXD4, UART6, USB11D1, USB11H2, USB2D1, USB2H1, USBCKI, VGABIOS_ROM, + VGAHS, VGAVS, VPI18, VPI24, VPI30, VPO12, VPO24, WDTRST1, WDTRST2] allOf: - $ref: pinctrl.yaml# @@ -56,8 +58,6 @@ allOf: required: - compatible -additionalProperties: false - examples: - | syscon: scu@1e6e2000 { diff --git a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml index 14c391f16899..863da5d80826 100644 --- a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml @@ -37,32 +37,34 @@ properties: 0: compatible with "aspeed,ast2500-gfx", "syscon" 1: compatible with "aspeed,ast2500-lhc", "syscon" -patternProperties: - '^.*$': - if: - type: object - then: - patternProperties: - "^function|groups$": - $ref: /schemas/types.yaml#/definitions/string - enum: [ ACPI, ADC0, ADC1, ADC10, ADC11, ADC12, ADC13, ADC14, ADC15, - ADC2, ADC3, ADC4, ADC5, ADC6, ADC7, ADC8, ADC9, BMCINT, DDCCLK, DDCDAT, - ESPI, FWSPICS1, FWSPICS2, GPID0, GPID2, GPID4, GPID6, GPIE0, GPIE2, - GPIE4, GPIE6, I2C10, I2C11, I2C12, I2C13, I2C14, I2C3, I2C4, I2C5, - I2C6, I2C7, I2C8, I2C9, LAD0, LAD1, LAD2, LAD3, LCLK, LFRAME, LPCHC, - LPCPD, LPCPLUS, LPCPME, LPCRST, LPCSMI, LSIRQ, MAC1LINK, MAC2LINK, - MDIO1, MDIO2, NCTS1, NCTS2, NCTS3, NCTS4, NDCD1, NDCD2, NDCD3, NDCD4, - NDSR1, NDSR2, NDSR3, NDSR4, NDTR1, NDTR2, NDTR3, NDTR4, NRI1, NRI2, - NRI3, NRI4, NRTS1, NRTS2, NRTS3, NRTS4, OSCCLK, PEWAKE, PNOR, PWM0, - PWM1, PWM2, PWM3, PWM4, PWM5, PWM6, PWM7, RGMII1, RGMII2, RMII1, - RMII2, RXD1, RXD2, RXD3, RXD4, SALT1, SALT10, SALT11, SALT12, SALT13, - SALT14, SALT2, SALT3, SALT4, SALT5, SALT6, SALT7, SALT8, SALT9, SCL1, - SCL2, SD1, SD2, SDA1, SDA2, SGPS1, SGPS2, SIOONCTRL, SIOPBI, SIOPBO, - SIOPWREQ, SIOPWRGD, SIOS3, SIOS5, SIOSCI, SPI1, SPI1CS1, SPI1DEBUG, - SPI1PASSTHRU, SPI2CK, SPI2CS0, SPI2CS1, SPI2MISO, SPI2MOSI, TIMER3, - TIMER4, TIMER5, TIMER6, TIMER7, TIMER8, TXD1, TXD2, TXD3, TXD4, UART6, - USB11BHID, USB2AD, USB2AH, USB2BD, USB2BH, USBCKI, VGABIOSROM, VGAHS, - VGAVS, VPI24, VPO, WDTRST1, WDTRST2] +additionalProperties: + $ref: pinmux-node.yaml# + additionalProperties: false + + properties: + pins: true + bias-disable: true + + patternProperties: + "^function|groups$": + enum: [ ACPI, ADC0, ADC1, ADC10, ADC11, ADC12, ADC13, ADC14, ADC15, + ADC2, ADC3, ADC4, ADC5, ADC6, ADC7, ADC8, ADC9, BMCINT, DDCCLK, DDCDAT, + ESPI, FWSPICS1, FWSPICS2, GPID0, GPID2, GPID4, GPID6, GPIE0, GPIE2, + GPIE4, GPIE6, I2C10, I2C11, I2C12, I2C13, I2C14, I2C3, I2C4, I2C5, + I2C6, I2C7, I2C8, I2C9, LAD0, LAD1, LAD2, LAD3, LCLK, LFRAME, LPCHC, + LPCPD, LPCPLUS, LPCPME, LPCRST, LPCSMI, LSIRQ, MAC1LINK, MAC2LINK, + MDIO1, MDIO2, NCTS1, NCTS2, NCTS3, NCTS4, NDCD1, NDCD2, NDCD3, NDCD4, + NDSR1, NDSR2, NDSR3, NDSR4, NDTR1, NDTR2, NDTR3, NDTR4, NRI1, NRI2, + NRI3, NRI4, NRTS1, NRTS2, NRTS3, NRTS4, OSCCLK, PEWAKE, PNOR, PWM0, + PWM1, PWM2, PWM3, PWM4, PWM5, PWM6, PWM7, RGMII1, RGMII2, RMII1, + RMII2, RXD1, RXD2, RXD3, RXD4, SALT1, SALT10, SALT11, SALT12, SALT13, + SALT14, SALT2, SALT3, SALT4, SALT5, SALT6, SALT7, SALT8, SALT9, SCL1, + SCL2, SD1, SD2, SDA1, SDA2, SGPS1, SGPS2, SIOONCTRL, SIOPBI, SIOPBO, + SIOPWREQ, SIOPWRGD, SIOS3, SIOS5, SIOSCI, SPI1, SPI1CS1, SPI1DEBUG, + SPI1PASSTHRU, SPI2CK, SPI2CS0, SPI2CS1, SPI2MISO, SPI2MOSI, TIMER3, + TIMER4, TIMER5, TIMER6, TIMER7, TIMER8, TXD1, TXD2, TXD3, TXD4, UART6, + USB11BHID, USB2AD, USB2AH, USB2BD, USB2BH, USBCKI, VGABIOSROM, VGAHS, + VGAVS, VPI24, VPO, WDTRST1, WDTRST2] allOf: - $ref: pinctrl.yaml# @@ -71,8 +73,6 @@ required: - compatible - aspeed,external-nodes -additionalProperties: false - examples: - | #include <dt-bindings/clock/aspeed-clock.h> diff --git a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml index 859a1889dc1e..612464aef98b 100644 --- a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml @@ -23,65 +23,65 @@ properties: compatible: const: aspeed,ast2600-pinctrl -patternProperties: - '^.*$': - if: - type: object - then: - properties: - function: - $ref: /schemas/types.yaml#/definitions/string - enum: [ ADC0, ADC1, ADC10, ADC11, ADC12, ADC13, ADC14, ADC15, ADC2, - ADC3, ADC4, ADC5, ADC6, ADC7, ADC8, ADC9, BMCINT, EMMC, ESPI, ESPIALT, - FSI1, FSI2, FWQSPI, FWSPIABR, FWSPID, FWSPIWP, GPIT0, GPIT1, GPIT2, GPIT3, - GPIT4, GPIT5, GPIT6, GPIT7, GPIU0, GPIU1, GPIU2, GPIU3, GPIU4, GPIU5, - GPIU6, GPIU7, I2C1, I2C10, I2C11, I2C12, I2C13, I2C14, I2C15, I2C16, - I2C2, I2C3, I2C4, I2C5, I2C6, I2C7, I2C8, I2C9, I3C3, I3C4, I3C5, - I3C6, JTAGM, LHPD, LHSIRQ, LPC, LPCHC, LPCPD, LPCPME, LPCSMI, LSIRQ, - MACLINK1, MACLINK2, MACLINK3, MACLINK4, MDIO1, MDIO2, MDIO3, MDIO4, - NCTS1, NCTS2, NCTS3, NCTS4, NDCD1, NDCD2, NDCD3, NDCD4, NDSR1, NDSR2, - NDSR3, NDSR4, NDTR1, NDTR2, NDTR3, NDTR4, NRI1, NRI2, NRI3, NRI4, - NRTS1, NRTS2, NRTS3, NRTS4, OSCCLK, PEWAKE, PWM0, PWM1, PWM10, PWM11, - PWM12, PWM13, PWM14, PWM15, PWM2, PWM3, PWM4, PWM5, PWM6, PWM7, PWM8, - PWM9, RGMII1, RGMII2, RGMII3, RGMII4, RMII1, RMII2, RMII3, RMII4, - RXD1, RXD2, RXD3, RXD4, SALT1, SALT10, SALT11, SALT12, SALT13, SALT14, - SALT15, SALT16, SALT2, SALT3, SALT4, SALT5, SALT6, SALT7, SALT8, - SALT9, SD1, SD2, SGPM1, SGPM2, SGPS1, SGPS2, SIOONCTRL, SIOPBI, SIOPBO, - SIOPWREQ, SIOPWRGD, SIOS3, SIOS5, SIOSCI, SPI1, SPI1ABR, SPI1CS1, SPI1WP, SPI2, - SPI2CS1, SPI2CS2, TACH0, TACH1, TACH10, TACH11, TACH12, TACH13, TACH14, - TACH15, TACH2, TACH3, TACH4, TACH5, TACH6, TACH7, TACH8, TACH9, THRU0, - THRU1, THRU2, THRU3, TXD1, TXD2, TXD3, TXD4, UART10, UART11, UART12, - UART13, UART6, UART7, UART8, UART9, USBAD, USBADP, USB2AH, USB2AHP, - USB2BD, USB2BH, VB, VGAHS, VGAVS, WDTRST1, WDTRST2, WDTRST3, WDTRST4 ] - - groups: - $ref: /schemas/types.yaml#/definitions/string - enum: [ ADC0, ADC1, ADC10, ADC11, ADC12, ADC13, ADC14, ADC15, ADC2, - ADC3, ADC4, ADC5, ADC6, ADC7, ADC8, ADC9, BMCINT, EMMCG1, EMMCG4, - EMMCG8, ESPI, ESPIALT, FSI1, FSI2, FWQSPI, FWSPIABR, FWSPID, FWSPIWP, - GPIT0, GPIT1, GPIT2, GPIT3, GPIT4, GPIT5, GPIT6, GPIT7, GPIU0, GPIU1, - GPIU2, GPIU3, GPIU4, GPIU5, GPIU6, GPIU7, HVI3C3, HVI3C4, I2C1, I2C10, - I2C11, I2C12, I2C13, I2C14, I2C15, I2C16, I2C2, I2C3, I2C4, I2C5, - I2C6, I2C7, I2C8, I2C9, I3C3, I3C4, I3C5, I3C6, JTAGM, LHPD, LHSIRQ, - LPC, LPCHC, LPCPD, LPCPME, LPCSMI, LSIRQ, MACLINK1, MACLINK2, MACLINK3, - MACLINK4, MDIO1, MDIO2, MDIO3, MDIO4, NCTS1, NCTS2, NCTS3, NCTS4, - NDCD1, NDCD2, NDCD3, NDCD4, NDSR1, NDSR2, NDSR3, NDSR4, NDTR1, NDTR2, - NDTR3, NDTR4, NRI1, NRI2, NRI3, NRI4, NRTS1, NRTS2, NRTS3, NRTS4, - OSCCLK, PEWAKE, PWM0, PWM1, PWM10G0, PWM10G1, PWM11G0, PWM11G1, PWM12G0, - PWM12G1, PWM13G0, PWM13G1, PWM14G0, PWM14G1, PWM15G0, PWM15G1, PWM2, - PWM3, PWM4, PWM5, PWM6, PWM7, PWM8G0, PWM8G1, PWM9G0, PWM9G1, QSPI1, - QSPI2, RGMII1, RGMII2, RGMII3, RGMII4, RMII1, RMII2, RMII3, RMII4, - RXD1, RXD2, RXD3, RXD4, SALT1, SALT10G0, SALT10G1, SALT11G0, SALT11G1, - SALT12G0, SALT12G1, SALT13G0, SALT13G1, SALT14G0, SALT14G1, SALT15G0, - SALT15G1, SALT16G0, SALT16G1, SALT2, SALT3, SALT4, SALT5, SALT6, - SALT7, SALT8, SALT9G0, SALT9G1, SD1, SD2, SD3, SGPM1, SGPM2, SGPS1, SGPS2, - SIOONCTRL, SIOPBI, SIOPBO, SIOPWREQ, SIOPWRGD, SIOS3, SIOS5, SIOSCI, SPI1, - SPI1ABR, SPI1CS1, SPI1WP, SPI2, SPI2CS1, SPI2CS2, TACH0, TACH1, TACH10, TACH11, - TACH12, TACH13, TACH14, TACH15, TACH2, TACH3, TACH4, TACH5, TACH6, - TACH7, TACH8, TACH9, THRU0, THRU1, THRU2, THRU3, TXD1, TXD2, TXD3, - TXD4, UART10, UART11, UART12G0, UART12G1, UART13G0, UART13G1, UART6, - UART7, UART8, UART9, USBA, USBB, VB, VGAHS, VGAVS, WDTRST1, WDTRST2, - WDTRST3, WDTRST4] +additionalProperties: + $ref: pinmux-node.yaml# + additionalProperties: false + + properties: + function: + enum: [ ADC0, ADC1, ADC10, ADC11, ADC12, ADC13, ADC14, ADC15, ADC2, + ADC3, ADC4, ADC5, ADC6, ADC7, ADC8, ADC9, BMCINT, EMMC, ESPI, ESPIALT, + FSI1, FSI2, FWQSPI, FWSPIABR, FWSPID, FWSPIWP, GPIT0, GPIT1, GPIT2, GPIT3, + GPIT4, GPIT5, GPIT6, GPIT7, GPIU0, GPIU1, GPIU2, GPIU3, GPIU4, GPIU5, + GPIU6, GPIU7, I2C1, I2C10, I2C11, I2C12, I2C13, I2C14, I2C15, I2C16, + I2C2, I2C3, I2C4, I2C5, I2C6, I2C7, I2C8, I2C9, I3C3, I3C4, I3C5, + I3C6, JTAGM, LHPD, LHSIRQ, LPC, LPCHC, LPCPD, LPCPME, LPCSMI, LSIRQ, + MACLINK1, MACLINK2, MACLINK3, MACLINK4, MDIO1, MDIO2, MDIO3, MDIO4, + NCTS1, NCTS2, NCTS3, NCTS4, NDCD1, NDCD2, NDCD3, NDCD4, NDSR1, NDSR2, + NDSR3, NDSR4, NDTR1, NDTR2, NDTR3, NDTR4, NRI1, NRI2, NRI3, NRI4, + NRTS1, NRTS2, NRTS3, NRTS4, OSCCLK, PEWAKE, PWM0, PWM1, PWM10, PWM11, + PWM12, PWM13, PWM14, PWM15, PWM2, PWM3, PWM4, PWM5, PWM6, PWM7, PWM8, + PWM9, RGMII1, RGMII2, RGMII3, RGMII4, RMII1, RMII2, RMII3, RMII4, + RXD1, RXD2, RXD3, RXD4, SALT1, SALT10, SALT11, SALT12, SALT13, SALT14, + SALT15, SALT16, SALT2, SALT3, SALT4, SALT5, SALT6, SALT7, SALT8, + SALT9, SD1, SD2, SGPM1, SGPM2, SGPS1, SGPS2, SIOONCTRL, SIOPBI, SIOPBO, + SIOPWREQ, SIOPWRGD, SIOS3, SIOS5, SIOSCI, SPI1, SPI1ABR, SPI1CS1, SPI1WP, SPI2, + SPI2CS1, SPI2CS2, TACH0, TACH1, TACH10, TACH11, TACH12, TACH13, TACH14, + TACH15, TACH2, TACH3, TACH4, TACH5, TACH6, TACH7, TACH8, TACH9, THRU0, + THRU1, THRU2, THRU3, TXD1, TXD2, TXD3, TXD4, UART10, UART11, UART12, + UART13, UART6, UART7, UART8, UART9, USBAD, USBADP, USB2AH, USB2AHP, + USB2BD, USB2BH, VB, VGAHS, VGAVS, WDTRST1, WDTRST2, WDTRST3, WDTRST4 ] + + groups: + enum: [ ADC0, ADC1, ADC10, ADC11, ADC12, ADC13, ADC14, ADC15, ADC2, + ADC3, ADC4, ADC5, ADC6, ADC7, ADC8, ADC9, BMCINT, EMMCG1, EMMCG4, + EMMCG8, ESPI, ESPIALT, FSI1, FSI2, FWQSPI, FWSPIABR, FWSPID, FWSPIWP, + GPIT0, GPIT1, GPIT2, GPIT3, GPIT4, GPIT5, GPIT6, GPIT7, GPIU0, GPIU1, + GPIU2, GPIU3, GPIU4, GPIU5, GPIU6, GPIU7, HVI3C3, HVI3C4, I2C1, I2C10, + I2C11, I2C12, I2C13, I2C14, I2C15, I2C16, I2C2, I2C3, I2C4, I2C5, + I2C6, I2C7, I2C8, I2C9, I3C3, I3C4, I3C5, I3C6, JTAGM, LHPD, LHSIRQ, + LPC, LPCHC, LPCPD, LPCPME, LPCSMI, LSIRQ, MACLINK1, MACLINK2, MACLINK3, + MACLINK4, MDIO1, MDIO2, MDIO3, MDIO4, NCTS1, NCTS2, NCTS3, NCTS4, + NDCD1, NDCD2, NDCD3, NDCD4, NDSR1, NDSR2, NDSR3, NDSR4, NDTR1, NDTR2, + NDTR3, NDTR4, NRI1, NRI2, NRI3, NRI4, NRTS1, NRTS2, NRTS3, NRTS4, + OSCCLK, PEWAKE, PWM0, PWM1, PWM10G0, PWM10G1, PWM11G0, PWM11G1, PWM12G0, + PWM12G1, PWM13G0, PWM13G1, PWM14G0, PWM14G1, PWM15G0, PWM15G1, PWM2, + PWM3, PWM4, PWM5, PWM6, PWM7, PWM8G0, PWM8G1, PWM9G0, PWM9G1, QSPI1, + QSPI2, RGMII1, RGMII2, RGMII3, RGMII4, RMII1, RMII2, RMII3, RMII4, + RXD1, RXD2, RXD3, RXD4, SALT1, SALT10G0, SALT10G1, SALT11G0, SALT11G1, + SALT12G0, SALT12G1, SALT13G0, SALT13G1, SALT14G0, SALT14G1, SALT15G0, + SALT15G1, SALT16G0, SALT16G1, SALT2, SALT3, SALT4, SALT5, SALT6, + SALT7, SALT8, SALT9G0, SALT9G1, SD1, SD2, SD3, SGPM1, SGPM2, SGPS1, SGPS2, + SIOONCTRL, SIOPBI, SIOPBO, SIOPWREQ, SIOPWRGD, SIOS3, SIOS5, SIOSCI, SPI1, + SPI1ABR, SPI1CS1, SPI1WP, SPI2, SPI2CS1, SPI2CS2, TACH0, TACH1, TACH10, TACH11, + TACH12, TACH13, TACH14, TACH15, TACH2, TACH3, TACH4, TACH5, TACH6, + TACH7, TACH8, TACH9, THRU0, THRU1, THRU2, THRU3, TXD1, TXD2, TXD3, + TXD4, UART10, UART11, UART12G0, UART12G1, UART13G0, UART13G1, UART6, + UART7, UART8, UART9, USBA, USBB, VB, VGAHS, VGAVS, WDTRST1, WDTRST2, + WDTRST3, WDTRST4] + + pins: true + bias-disable: true allOf: - $ref: pinctrl.yaml# @@ -89,8 +89,6 @@ allOf: required: - compatible -additionalProperties: false - examples: - | syscon: scu@1e6e2000 { diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm11351-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/brcm,bcm11351-pinctrl.txt deleted file mode 100644 index e047a198db38..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm11351-pinctrl.txt +++ /dev/null @@ -1,461 +0,0 @@ -Broadcom BCM281xx Pin Controller - -This is a pin controller for the Broadcom BCM281xx SoC family, which includes -BCM11130, BCM11140, BCM11351, BCM28145, and BCM28155 SoCs. - -=== Pin Controller Node === - -Required Properties: - -- compatible: Must be "brcm,bcm11351-pinctrl" -- reg: Base address of the PAD Controller register block and the size - of the block. - -For example, the following is the bare minimum node: - - pinctrl@35004800 { - compatible = "brcm,bcm11351-pinctrl"; - reg = <0x35004800 0x430>; - }; - -As a pin controller device, in addition to the required properties, this node -should also contain the pin configuration nodes that client devices reference, -if any. - -=== Pin Configuration Node === - -Each pin configuration node is a sub-node of the pin controller node and is a -container of an arbitrary number of subnodes, called pin group nodes in this -document. - -Please refer to the pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the definition of a -"pin configuration node". - -=== Pin Group Node === - -A pin group node specifies the desired pin mux and/or pin configuration for an -arbitrary number of pins. The name of the pin group node is optional and not -used. - -A pin group node only affects the properties specified in the node, and has no -effect on any properties that are omitted. - -The pin group node accepts a subset of the generic pin config properties. For -details generic pin config properties, please refer to pinctrl-bindings.txt -and <include/linux/pinctrl/pinconfig-generic.h>. - -Each pin controlled by this pin controller belong to one of three types: -Standard, I2C, and HDMI. Each type accepts a different set of pin config -properties. A list of pins and their types is provided below. - -Required Properties (applicable to all pins): - -- pins: Multiple strings. Specifies the name(s) of one or more pins to - be configured by this node. - -Optional Properties (for standard pins): - -- function: String. Specifies the pin mux selection. Values - must be one of: "alt1", "alt2", "alt3", "alt4" -- input-schmitt-enable: No arguments. Enable schmitt-trigger mode. -- input-schmitt-disable: No arguments. Disable schmitt-trigger mode. -- bias-pull-up: No arguments. Pull up on pin. -- bias-pull-down: No arguments. Pull down on pin. -- bias-disable: No arguments. Disable pin bias. -- slew-rate: Integer. Meaning depends on configured pin mux: - *_SCL or *_SDA: - 0: Standard(100kbps)& Fast(400kbps) mode - 1: Highspeed (3.4Mbps) mode - IC_DM or IC_DP: - 0: normal slew rate - 1: fast slew rate - Otherwise: - 0: fast slew rate - 1: normal slew rate -- input-enable: No arguments. Enable input (does not affect - output.) -- input-disable: No arguments. Disable input (does not affect - output.) -- drive-strength: Integer. Drive strength in mA. Valid values are - 2, 4, 6, 8, 10, 12, 14, 16 mA. - -Optional Properties (for I2C pins): - -- function: String. Specifies the pin mux selection. Values - must be one of: "alt1", "alt2", "alt3", "alt4" -- bias-pull-up: Integer. Pull up strength in Ohm. There are 3 - pull-up resistors (1.2k, 1.8k, 2.7k) available - in parallel for I2C pins, so the valid values - are: 568, 720, 831, 1080, 1200, 1800, 2700 Ohm. -- bias-disable: No arguments. Disable pin bias. -- slew-rate: Integer. Meaning depends on configured pin mux: - *_SCL or *_SDA: - 0: Standard(100kbps)& Fast(400kbps) mode - 1: Highspeed (3.4Mbps) mode - IC_DM or IC_DP: - 0: normal slew rate - 1: fast slew rate - Otherwise: - 0: fast slew rate - 1: normal slew rate -- input-enable: No arguments. Enable input (does not affect - output.) -- input-disable: No arguments. Disable input (does not affect - output.) - -Optional Properties (for HDMI pins): - -- function: String. Specifies the pin mux selection. Values - must be one of: "alt1", "alt2", "alt3", "alt4" -- slew-rate: Integer. Controls slew rate. - 0: Standard(100kbps)& Fast(400kbps) mode - 1: Highspeed (3.4Mbps) mode -- input-enable: No arguments. Enable input (does not affect - output.) -- input-disable: No arguments. Disable input (does not affect - output.) - -Example: -// pin controller node -pinctrl@35004800 { - compatible = "brcm,bcm11351-pinctrl"; - reg = <0x35004800 0x430>; - - // pin configuration node - dev_a_default: dev_a_active { - //group node defining 1 standard pin - grp_1 { - pins = "std_pin1"; - function = "alt1"; - input-schmitt-enable; - bias-disable; - slew-rate = <1>; - drive-strength = <4>; - }; - - // group node defining 2 I2C pins - grp_2 { - pins = "i2c_pin1", "i2c_pin2"; - function = "alt2"; - bias-pull-up = <720>; - input-enable; - }; - - // group node defining 2 HDMI pins - grp_3 { - pins = "hdmi_pin1", "hdmi_pin2"; - function = "alt3"; - slew-rate = <1>; - }; - - // other pin group nodes - ... - }; - - // other pin configuration nodes - ... -}; - -In the example above, "dev_a_active" is a pin configuration node with a number -of sub-nodes. In the pin group node "grp_1", one pin, "std_pin1", is defined in -the "pins" property. Thus, the remaining properties in the "grp_1" node applies -only to this pin, including the following settings: - - setting pinmux to "alt1" - - enabling schmitt-trigger (hystersis) mode - - disabling pin bias - - setting the slew-rate to 1 - - setting the drive strength to 4 mA -Note that neither "input-enable" nor "input-disable" was specified - the pinctrl -subsystem will therefore leave this property unchanged from whatever state it -was in before applying these changes. - -The "pins" property in the pin group node "grp_2" specifies two pins - -"i2c_pin1" and "i2c_pin2"; the remaining properties in this pin group node, -therefore, applies to both of these pins. The properties include: - - setting pinmux to "alt2" - - setting pull-up resistance to 720 Ohm (ie. enabling 1.2k and 1.8k resistors - in parallel) - - enabling both pins' input -"slew-rate" is not specified in this pin group node, so the slew-rate for these -pins are left as-is. - -Finally, "grp_3" defines two HDMI pins. The following properties are applied to -both pins: - - setting pinmux to "alt3" - - setting slew-rate to 1; for HDMI pins, this corresponds to the 3.4 Mbps - Highspeed mode -The input is neither enabled or disabled, and is left untouched. - -=== Pin Names and Type === - -The following are valid pin names and their pin types: - - "adcsync", Standard - "bat_rm", Standard - "bsc1_scl", I2C - "bsc1_sda", I2C - "bsc2_scl", I2C - "bsc2_sda", I2C - "classgpwr", Standard - "clk_cx8", Standard - "clkout_0", Standard - "clkout_1", Standard - "clkout_2", Standard - "clkout_3", Standard - "clkreq_in_0", Standard - "clkreq_in_1", Standard - "cws_sys_req1", Standard - "cws_sys_req2", Standard - "cws_sys_req3", Standard - "digmic1_clk", Standard - "digmic1_dq", Standard - "digmic2_clk", Standard - "digmic2_dq", Standard - "gpen13", Standard - "gpen14", Standard - "gpen15", Standard - "gpio00", Standard - "gpio01", Standard - "gpio02", Standard - "gpio03", Standard - "gpio04", Standard - "gpio05", Standard - "gpio06", Standard - "gpio07", Standard - "gpio08", Standard - "gpio09", Standard - "gpio10", Standard - "gpio11", Standard - "gpio12", Standard - "gpio13", Standard - "gpio14", Standard - "gps_pablank", Standard - "gps_tmark", Standard - "hdmi_scl", HDMI - "hdmi_sda", HDMI - "ic_dm", Standard - "ic_dp", Standard - "kp_col_ip_0", Standard - "kp_col_ip_1", Standard - "kp_col_ip_2", Standard - "kp_col_ip_3", Standard - "kp_row_op_0", Standard - "kp_row_op_1", Standard - "kp_row_op_2", Standard - "kp_row_op_3", Standard - "lcd_b_0", Standard - "lcd_b_1", Standard - "lcd_b_2", Standard - "lcd_b_3", Standard - "lcd_b_4", Standard - "lcd_b_5", Standard - "lcd_b_6", Standard - "lcd_b_7", Standard - "lcd_g_0", Standard - "lcd_g_1", Standard - "lcd_g_2", Standard - "lcd_g_3", Standard - "lcd_g_4", Standard - "lcd_g_5", Standard - "lcd_g_6", Standard - "lcd_g_7", Standard - "lcd_hsync", Standard - "lcd_oe", Standard - "lcd_pclk", Standard - "lcd_r_0", Standard - "lcd_r_1", Standard - "lcd_r_2", Standard - "lcd_r_3", Standard - "lcd_r_4", Standard - "lcd_r_5", Standard - "lcd_r_6", Standard - "lcd_r_7", Standard - "lcd_vsync", Standard - "mdmgpio0", Standard - "mdmgpio1", Standard - "mdmgpio2", Standard - "mdmgpio3", Standard - "mdmgpio4", Standard - "mdmgpio5", Standard - "mdmgpio6", Standard - "mdmgpio7", Standard - "mdmgpio8", Standard - "mphi_data_0", Standard - "mphi_data_1", Standard - "mphi_data_2", Standard - "mphi_data_3", Standard - "mphi_data_4", Standard - "mphi_data_5", Standard - "mphi_data_6", Standard - "mphi_data_7", Standard - "mphi_data_8", Standard - "mphi_data_9", Standard - "mphi_data_10", Standard - "mphi_data_11", Standard - "mphi_data_12", Standard - "mphi_data_13", Standard - "mphi_data_14", Standard - "mphi_data_15", Standard - "mphi_ha0", Standard - "mphi_hat0", Standard - "mphi_hat1", Standard - "mphi_hce0_n", Standard - "mphi_hce1_n", Standard - "mphi_hrd_n", Standard - "mphi_hwr_n", Standard - "mphi_run0", Standard - "mphi_run1", Standard - "mtx_scan_clk", Standard - "mtx_scan_data", Standard - "nand_ad_0", Standard - "nand_ad_1", Standard - "nand_ad_2", Standard - "nand_ad_3", Standard - "nand_ad_4", Standard - "nand_ad_5", Standard - "nand_ad_6", Standard - "nand_ad_7", Standard - "nand_ale", Standard - "nand_cen_0", Standard - "nand_cen_1", Standard - "nand_cle", Standard - "nand_oen", Standard - "nand_rdy_0", Standard - "nand_rdy_1", Standard - "nand_wen", Standard - "nand_wp", Standard - "pc1", Standard - "pc2", Standard - "pmu_int", Standard - "pmu_scl", I2C - "pmu_sda", I2C - "rfst2g_mtsloten3g", Standard - "rgmii_0_rx_ctl", Standard - "rgmii_0_rxc", Standard - "rgmii_0_rxd_0", Standard - "rgmii_0_rxd_1", Standard - "rgmii_0_rxd_2", Standard - "rgmii_0_rxd_3", Standard - "rgmii_0_tx_ctl", Standard - "rgmii_0_txc", Standard - "rgmii_0_txd_0", Standard - "rgmii_0_txd_1", Standard - "rgmii_0_txd_2", Standard - "rgmii_0_txd_3", Standard - "rgmii_1_rx_ctl", Standard - "rgmii_1_rxc", Standard - "rgmii_1_rxd_0", Standard - "rgmii_1_rxd_1", Standard - "rgmii_1_rxd_2", Standard - "rgmii_1_rxd_3", Standard - "rgmii_1_tx_ctl", Standard - "rgmii_1_txc", Standard - "rgmii_1_txd_0", Standard - "rgmii_1_txd_1", Standard - "rgmii_1_txd_2", Standard - "rgmii_1_txd_3", Standard - "rgmii_gpio_0", Standard - "rgmii_gpio_1", Standard - "rgmii_gpio_2", Standard - "rgmii_gpio_3", Standard - "rtxdata2g_txdata3g1", Standard - "rtxen2g_txdata3g2", Standard - "rxdata3g0", Standard - "rxdata3g1", Standard - "rxdata3g2", Standard - "sdio1_clk", Standard - "sdio1_cmd", Standard - "sdio1_data_0", Standard - "sdio1_data_1", Standard - "sdio1_data_2", Standard - "sdio1_data_3", Standard - "sdio4_clk", Standard - "sdio4_cmd", Standard - "sdio4_data_0", Standard - "sdio4_data_1", Standard - "sdio4_data_2", Standard - "sdio4_data_3", Standard - "sim_clk", Standard - "sim_data", Standard - "sim_det", Standard - "sim_resetn", Standard - "sim2_clk", Standard - "sim2_data", Standard - "sim2_det", Standard - "sim2_resetn", Standard - "sri_c", Standard - "sri_d", Standard - "sri_e", Standard - "ssp_extclk", Standard - "ssp0_clk", Standard - "ssp0_fs", Standard - "ssp0_rxd", Standard - "ssp0_txd", Standard - "ssp2_clk", Standard - "ssp2_fs_0", Standard - "ssp2_fs_1", Standard - "ssp2_fs_2", Standard - "ssp2_fs_3", Standard - "ssp2_rxd_0", Standard - "ssp2_rxd_1", Standard - "ssp2_txd_0", Standard - "ssp2_txd_1", Standard - "ssp3_clk", Standard - "ssp3_fs", Standard - "ssp3_rxd", Standard - "ssp3_txd", Standard - "ssp4_clk", Standard - "ssp4_fs", Standard - "ssp4_rxd", Standard - "ssp4_txd", Standard - "ssp5_clk", Standard - "ssp5_fs", Standard - "ssp5_rxd", Standard - "ssp5_txd", Standard - "ssp6_clk", Standard - "ssp6_fs", Standard - "ssp6_rxd", Standard - "ssp6_txd", Standard - "stat_1", Standard - "stat_2", Standard - "sysclken", Standard - "traceclk", Standard - "tracedt00", Standard - "tracedt01", Standard - "tracedt02", Standard - "tracedt03", Standard - "tracedt04", Standard - "tracedt05", Standard - "tracedt06", Standard - "tracedt07", Standard - "tracedt08", Standard - "tracedt09", Standard - "tracedt10", Standard - "tracedt11", Standard - "tracedt12", Standard - "tracedt13", Standard - "tracedt14", Standard - "tracedt15", Standard - "txdata3g0", Standard - "txpwrind", Standard - "uartb1_ucts", Standard - "uartb1_urts", Standard - "uartb1_urxd", Standard - "uartb1_utxd", Standard - "uartb2_urxd", Standard - "uartb2_utxd", Standard - "uartb3_ucts", Standard - "uartb3_urts", Standard - "uartb3_urxd", Standard - "uartb3_utxd", Standard - "uartb4_ucts", Standard - "uartb4_urts", Standard - "uartb4_urxd", Standard - "uartb4_utxd", Standard - "vc_cam1_scl", I2C - "vc_cam1_sda", I2C - "vc_cam2_scl", I2C - "vc_cam2_sda", I2C - "vc_cam3_scl", I2C - "vc_cam3_sda", I2C diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm11351-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm11351-pinctrl.yaml new file mode 100644 index 000000000000..90c275295199 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm11351-pinctrl.yaml @@ -0,0 +1,259 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/brcm,bcm11351-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM281xx pin controller + +maintainers: + - Florian Fainelli <florian.fainelli@broadcom.com> + - Ray Jui <rjui@broadcom.com> + - Scott Branden <sbranden@broadcom.com> + +allOf: + - $ref: pinctrl.yaml# + +properties: + compatible: + const: brcm,bcm11351-pinctrl + + reg: + maxItems: 1 + +patternProperties: + '-pins$': + type: object + additionalProperties: false + + patternProperties: + '-grp[0-9]$': + type: object + unevaluatedProperties: false + + properties: + pins: + description: + Specifies the name(s) of one or more pins to be configured by + this node. + items: + enum: [ adcsync, bat_rm, bsc1_scl, bsc1_sda, bsc2_scl, bsc2_sda, + classgpwr, clk_cx8, clkout_0, clkout_1, clkout_2, + clkout_3, clkreq_in_0, clkreq_in_1, cws_sys_req1, + cws_sys_req2, cws_sys_req3, digmic1_clk, digmic1_dq, + digmic2_clk, digmic2_dq, gpen13, gpen14, gpen15, gpio00, + gpio01, gpio02, gpio03, gpio04, gpio05, gpio06, gpio07, + gpio08, gpio09, gpio10, gpio11, gpio12, gpio13, gpio14, + gps_pablank, gps_tmark, hdmi_scl, hdmi_sda, ic_dm, ic_dp, + kp_col_ip_0, kp_col_ip_1, kp_col_ip_2, kp_col_ip_3, + kp_row_op_0, kp_row_op_1, kp_row_op_2, kp_row_op_3, + lcd_b_0, lcd_b_1, lcd_b_2, lcd_b_3, lcd_b_4, lcd_b_5, + lcd_b_6, lcd_b_7, lcd_g_0, lcd_g_1, lcd_g_2, lcd_g_3, + lcd_g_4, lcd_g_5, lcd_g_6, lcd_g_7, lcd_hsync, lcd_oe, + lcd_pclk, lcd_r_0, lcd_r_1, lcd_r_2, lcd_r_3, lcd_r_4, + lcd_r_5, lcd_r_6, lcd_r_7, lcd_vsync, mdmgpio0, mdmgpio1, + mdmgpio2, mdmgpio3, mdmgpio4, mdmgpio5, mdmgpio6, + mdmgpio7, mdmgpio8, mphi_data_0, mphi_data_1, mphi_data_2, + mphi_data_3, mphi_data_4, mphi_data_5, mphi_data_6, + mphi_data_7, mphi_data_8, mphi_data_9, mphi_data_10, + mphi_data_11, mphi_data_12, mphi_data_13, mphi_data_14, + mphi_data_15, mphi_ha0, mphi_hat0, mphi_hat1, mphi_hce0_n, + mphi_hce1_n, mphi_hrd_n, mphi_hwr_n, mphi_run0, mphi_run1, + mtx_scan_clk, mtx_scan_data, nand_ad_0, nand_ad_1, + nand_ad_2, nand_ad_3, nand_ad_4, nand_ad_5, nand_ad_6, + nand_ad_7, nand_ale, nand_cen_0, nand_cen_1, nand_cle, + nand_oen, nand_rdy_0, nand_rdy_1, nand_wen, nand_wp, pc1, + pc2, pmu_int, pmu_scl, pmu_sda, rfst2g_mtsloten3g, + rgmii_0_rx_ctl, rgmii_0_rxc, rgmii_0_rxd_0, rgmii_0_rxd_1, + rgmii_0_rxd_2, rgmii_0_rxd_3, rgmii_0_tx_ctl, rgmii_0_txc, + rgmii_0_txd_0, rgmii_0_txd_1, rgmii_0_txd_2, + rgmii_0_txd_3, rgmii_1_rx_ctl, rgmii_1_rxc, rgmii_1_rxd_0, + rgmii_1_rxd_1, rgmii_1_rxd_2, rgmii_1_rxd_3, + rgmii_1_tx_ctl, rgmii_1_txc, rgmii_1_txd_0, rgmii_1_txd_1, + rgmii_1_txd_2, rgmii_1_txd_3, rgmii_gpio_0, rgmii_gpio_1, + rgmii_gpio_2, rgmii_gpio_3, rtxdata2g_txdata3g1, + rtxen2g_txdata3g2, rxdata3g0, rxdata3g1, rxdata3g2, + sdio1_clk, sdio1_cmd, sdio1_data_0, sdio1_data_1, + sdio1_data_2, sdio1_data_3, sdio4_clk, sdio4_cmd, + sdio4_data_0, sdio4_data_1, sdio4_data_2, sdio4_data_3, + sim_clk, sim_data, sim_det, sim_resetn, sim2_clk, + sim2_data, sim2_det, sim2_resetn, sri_c, sri_d, sri_e, + ssp_extclk, ssp0_clk, ssp0_fs, ssp0_rxd, ssp0_txd, + ssp2_clk, ssp2_fs_0, ssp2_fs_1, ssp2_fs_2, ssp2_fs_3, + ssp2_rxd_0, ssp2_rxd_1, ssp2_txd_0, ssp2_txd_1, ssp3_clk, + ssp3_fs, ssp3_rxd, ssp3_txd, ssp4_clk, ssp4_fs, ssp4_rxd, + ssp4_txd, ssp5_clk, ssp5_fs, ssp5_rxd, ssp5_txd, ssp6_clk, + ssp6_fs, ssp6_rxd, ssp6_txd, stat_1, stat_2, sysclken, + traceclk, tracedt00, tracedt01, tracedt02, tracedt03, + tracedt04, tracedt05, tracedt06, tracedt07, tracedt08 + tracedt09, tracedt10, tracedt11, tracedt12, tracedt13 + tracedt14, tracedt15, txdata3g0, txpwrind, uartb1_ucts, + uartb1_urts, uartb1_urxd, uartb1_utxd, uartb2_urxd, + uartb2_utxd, uartb3_ucts, uartb3_urts, uartb3_urxd, + uartb3_utxd, uartb4_ucts, uartb4_urts, uartb4_urxd, + uartb4_utxd, vc_cam1_scl, vc_cam1_sda, vc_cam2_scl, + vc_cam2_sda, vc_cam3_scl, vc_cam3_sda ] + + function: + description: + Specifies the pin mux selection. + enum: [ alt1, alt2, alt3, alt4 ] + + slew-rate: + description: | + Meaning depends on configured pin mux: + *_scl or *_sda: + 0: Standard (100 kbps) & Fast (400 kbps) mode + 1: Highspeed (3.4 Mbps) mode + ic_dm or ic_dp: + 0: normal slew rate + 1: fast slew rate + Otherwise: + 0: fast slew rate + 1: normal slew rate + + bias-disable: true + input-disable: true + input-enable: true + + required: + - pins + + allOf: + - $ref: pincfg-node.yaml# + + # Optional properties for standard pins + - if: + properties: + pins: + contains: + enum: [ adcsync, bat_rm, classgpwr, clk_cx8, clkout_0, + clkout_1, clkout_2, clkout_3, clkreq_in_0, + clkreq_in_1, cws_sys_req1, cws_sys_req2, + cws_sys_req3, digmic1_clk, digmic1_dq, digmic2_clk, + digmic2_dq, gpen13, gpen14, gpen15, gpio00, gpio01, + gpio02, gpio03, gpio04, gpio05, gpio06, gpio07, + gpio08, gpio09, gpio10, gpio11, gpio12, gpio13, + gpio14, gps_pablank, gps_tmark, ic_dm, ic_dp, + kp_col_ip_0, kp_col_ip_1, kp_col_ip_2, kp_col_ip_3, + kp_row_op_0, kp_row_op_1, kp_row_op_2, kp_row_op_3, + lcd_b_0, lcd_b_1, lcd_b_2, lcd_b_3, lcd_b_4, lcd_b_5, + lcd_b_6, lcd_b_7, lcd_g_0, lcd_g_1, lcd_g_2, lcd_g_3, + lcd_g_4, lcd_g_5, lcd_g_6, lcd_g_7, lcd_hsync, + lcd_oe, lcd_pclk, lcd_r_0, lcd_r_1, lcd_r_2, + lcd_r_3, lcd_r_4, lcd_r_5, lcd_r_6, lcd_r_7, + lcd_vsync, mdmgpio0, mdmgpio1, mdmgpio2, mdmgpio3, + mdmgpio4, mdmgpio5, mdmgpio6, mdmgpio7, mdmgpio8, + mphi_data_0, mphi_data_1, mphi_data_2, mphi_data_3, + mphi_data_4, mphi_data_5, mphi_data_6, mphi_data_7, + mphi_data_8, mphi_data_9, mphi_data_10, + mphi_data_11, mphi_data_12, mphi_data_13, + mphi_data_14, mphi_data_15, mphi_ha0, mphi_hat0, + mphi_hat1, mphi_hce0_n, mphi_hce1_n, mphi_hrd_n, + mphi_hwr_n, mphi_run0, mphi_run1, mtx_scan_clk, + mtx_scan_data, nand_ad_0, nand_ad_1, nand_ad_2, + nand_ad_3, nand_ad_4, nand_ad_5, nand_ad_6, + nand_ad_7, nand_ale, nand_cen_0, nand_cen_1, + nand_cle, nand_oen, nand_rdy_0, nand_rdy_1, + nand_wen, nand_wp, pc1, pc2, pmu_int, + rfst2g_mtsloten3g, rgmii_0_rx_ctl, rgmii_0_rxc, + rgmii_0_rxd_0, rgmii_0_rxd_1, rgmii_0_rxd_2, + rgmii_0_rxd_3, rgmii_0_tx_ctl, rgmii_0_txc, + rgmii_0_txd_0, rgmii_0_txd_1, rgmii_0_txd_2, + rgmii_0_txd_3, rgmii_1_rx_ctl, rgmii_1_rxc, + rgmii_1_rxd_0, rgmii_1_rxd_1, rgmii_1_rxd_2, + rgmii_1_rxd_3, rgmii_1_tx_ctl, rgmii_1_txc, + rgmii_1_txd_0, rgmii_1_txd_1, rgmii_1_txd_2, + rgmii_1_txd_3, rgmii_gpio_0, rgmii_gpio_1, + rgmii_gpio_2, rgmii_gpio_3, rtxdata2g_txdata3g1, + rtxen2g_txdata3g2, rxdata3g0, rxdata3g1, rxdata3g2, + sdio1_clk, sdio1_cmd, sdio1_data_0, sdio1_data_1, + sdio1_data_2, sdio1_data_3, sdio4_clk, sdio4_cmd, + sdio4_data_0, sdio4_data_1, sdio4_data_2, + sdio4_data_3, sim_clk, sim_data, sim_det, + sim_resetn, sim2_clk, sim2_data, sim2_det, + sim2_resetn, sri_c, sri_d, sri_e, ssp_extclk, + ssp0_clk, ssp0_fs, ssp0_rxd, ssp0_txd, ssp2_clk, + ssp2_fs_0, ssp2_fs_1, ssp2_fs_2, ssp2_fs_3, + ssp2_rxd_0, ssp2_rxd_1, ssp2_txd_0, ssp2_txd_1, + ssp3_clk, ssp3_fs, ssp3_rxd, ssp3_txd, ssp4_clk, + ssp4_fs, ssp4_rxd, ssp4_txd, ssp5_clk, ssp5_fs, + ssp5_rxd, ssp5_txd, ssp6_clk, ssp6_fs, ssp6_rxd, + ssp6_txd, stat_1, stat_2, sysclken, traceclk, + tracedt00, tracedt01, tracedt02, tracedt03, + tracedt04, tracedt05, tracedt06, tracedt07, + tracedt08, tracedt09, tracedt10, tracedt11, + tracedt12, tracedt13, tracedt14, tracedt15, + txdata3g0, txpwrind, uartb1_ucts, uartb1_urts, + uartb1_urxd, uartb1_utxd, uartb2_urxd, uartb2_utxd, + uartb3_ucts, uartb3_urts, uartb3_urxd, uartb3_utxd, + uartb4_ucts, uartb4_urts, uartb4_urxd, uartb4_utxd ] + then: + properties: + drive-strength: + enum: [ 2, 4, 6, 8, 10, 12, 14, 16 ] + + bias-disable: true + bias-pull-up: true + bias-pull-down: true + input-schmitt-enable: true + input-schmitt-disable: true + + # Optional properties for I2C pins + - if: + properties: + pins: + contains: + enum: [ bsc1_scl, bsc1_sda, bsc2_scl, bsc2_sda, pmu_scl, + pmu_sda, vc_cam1_scl, vc_cam1_sda, vc_cam2_scl, + vc_cam2_sda, vc_cam3_scl, vc_cam3_sda ] + then: + properties: + bias-pull-up: + description: + There are 3 pull-up resistors (1.2k, 1.8k, 2.7k) available + in parallel for I2C pins. + enum: [ 568, 720, 831, 1080, 1200, 1800, 2700 ] + + bias-disable: true + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + pinctrl@35004800 { + compatible = "brcm,bcm11351-pinctrl"; + reg = <0x35004800 0x430>; + + dev-a-active-pins { + /* group node defining 1 standard pin */ + std-grp0 { + pins = "gpio00"; + function = "alt1"; + input-schmitt-enable; + bias-disable; + slew-rate = <1>; + drive-strength = <4>; + }; + + /* group node defining 2 I2C pins */ + i2c-grp0 { + pins = "bsc1_scl", "bsc1_sda"; + function = "alt2"; + bias-pull-up = <720>; + input-enable; + }; + + /* group node defining 2 HDMI pins */ + hdmi-grp0 { + pins = "hdmi_scl", "hdmi_sda"; + function = "alt3"; + slew-rate = <1>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pinctrl/canaan,k210-fpioa.yaml b/Documentation/devicetree/bindings/pinctrl/canaan,k210-fpioa.yaml index 739a08f00467..beb769e887c7 100644 --- a/Documentation/devicetree/bindings/pinctrl/canaan,k210-fpioa.yaml +++ b/Documentation/devicetree/bindings/pinctrl/canaan,k210-fpioa.yaml @@ -11,7 +11,7 @@ maintainers: description: The Canaan Kendryte K210 SoC Fully Programmable IO Array (FPIOA) - controller allows assiging any of 256 possible functions to any of + controller allows assigning any of 256 possible functions to any of 48 IO pins of the SoC. Pin function configuration is performed on a per-pin basis. diff --git a/Documentation/devicetree/bindings/pinctrl/cypress,cy8c95x0.yaml b/Documentation/devicetree/bindings/pinctrl/cypress,cy8c95x0.yaml index 222d57541b65..7f30ec2f1e54 100644 --- a/Documentation/devicetree/bindings/pinctrl/cypress,cy8c95x0.yaml +++ b/Documentation/devicetree/bindings/pinctrl/cypress,cy8c95x0.yaml @@ -51,6 +51,10 @@ properties: description: Optional power supply. + reset-gpios: + description: GPIO connected to the XRES pin + maxItems: 1 + patternProperties: '-pins$': type: object diff --git a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml index 35723966b70a..890961826c6f 100644 --- a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml @@ -135,7 +135,6 @@ additionalProperties: - $ref: pinmux-node.yaml# properties: - phandle: true function: true groups: true pins: true @@ -147,8 +146,6 @@ additionalProperties: additionalProperties: false - type: object - properties: - phandle: true additionalProperties: type: object allOf: @@ -156,7 +153,6 @@ additionalProperties: - $ref: pinmux-node.yaml# properties: - phandle: true function: true groups: true pins: true diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt6779-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt6779-pinctrl.yaml index 7f0e2d6cd6d9..3bbc00df5548 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt6779-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt6779-pinctrl.yaml @@ -159,7 +159,7 @@ patternProperties: mediatek,pull-up-adv: description: | - Pull up setings for 2 pull resistors, R0 and R1. User can + Pull up settings for 2 pull resistors, R0 and R1. User can configure those special pins. Valid arguments are described as below: 0: (R1, R0) = (0, 0) which means R1 disabled and R0 disabled. diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt6795-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt6795-pinctrl.yaml index 601d86aecdd4..68e91c05f122 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt6795-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt6795-pinctrl.yaml @@ -130,7 +130,7 @@ patternProperties: mediatek,pull-up-adv: description: | - Pull up setings for 2 pull resistors, R0 and R1. User can + Pull up settings for 2 pull resistors, R0 and R1. User can configure those special pins. Valid arguments are described as below: 0: (R1, R0) = (0, 0) which means R1 disabled and R0 disabled. diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt7981-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt7981-pinctrl.yaml index 10717cee9058..74d52a741f6f 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt7981-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt7981-pinctrl.yaml @@ -386,7 +386,7 @@ patternProperties: mediatek,pull-up-adv: description: | Valid arguments for 'mediatek,pull-up-adv' are '0', '1', '2', '3' - Pull up setings for 2 pull resistors, R0 and R1. Valid arguments + Pull up settings for 2 pull resistors, R0 and R1. Valid arguments are described as below: 0: (R1, R0) = (0, 0) which means R1 disabled and R0 disabled. 1: (R1, R0) = (0, 1) which means R1 disabled and R0 enabled. @@ -398,7 +398,7 @@ patternProperties: mediatek,pull-down-adv: description: | Valid arguments for 'mediatek,pull-up-adv' are '0', '1', '2', '3' - Pull down setings for 2 pull resistors, R0 and R1. Valid arguments + Pull down settings for 2 pull resistors, R0 and R1. Valid arguments are described as below: 0: (R1, R0) = (0, 0) which means R1 disabled and R0 disabled. 1: (R1, R0) = (0, 1) which means R1 disabled and R0 enabled. diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt7986-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt7986-pinctrl.yaml index 0f615ada290a..5ad65135fe1c 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt7986-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt7986-pinctrl.yaml @@ -332,7 +332,7 @@ patternProperties: mediatek,pull-up-adv: description: | Valid arguments for 'mediatek,pull-up-adv' are '0', '1', '2', '3' - Pull up setings for 2 pull resistors, R0 and R1. Valid arguments + Pull up settings for 2 pull resistors, R0 and R1. Valid arguments are described as below: 0: (R1, R0) = (0, 0) which means R1 disabled and R0 disabled. 1: (R1, R0) = (0, 1) which means R1 disabled and R0 enabled. @@ -344,7 +344,7 @@ patternProperties: mediatek,pull-down-adv: description: | Valid arguments for 'mediatek,pull-up-adv' are '0', '1', '2', '3' - Pull down setings for 2 pull resistors, R0 and R1. Valid arguments + Pull down settings for 2 pull resistors, R0 and R1. Valid arguments are described as below: 0: (R1, R0) = (0, 0) which means R1 disabled and R0 disabled. 1: (R1, R0) = (0, 1) which means R1 disabled and R0 enabled. diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt8183-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt8183-pinctrl.yaml index ff24cf29eea7..8507bd15f243 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt8183-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt8183-pinctrl.yaml @@ -143,7 +143,7 @@ patternProperties: mediatek,pull-up-adv: description: | - Pull up setings for 2 pull resistors, R0 and R1. User can + Pull up settings for 2 pull resistors, R0 and R1. User can configure those special pins. Valid arguments are described as below: 0: (R1, R0) = (0, 0) which means R1 disabled and R0 disabled. diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt8365-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt8365-pinctrl.yaml index 61b33b5416f5..7b43e7857281 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt8365-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt8365-pinctrl.yaml @@ -149,7 +149,7 @@ patternProperties: deprecated: true description: | DEPRECATED: Please use bias-pull-up instead. - Pull up setings for 2 pull resistors, R0 and R1. User can + Pull up settings for 2 pull resistors, R0 and R1. User can configure those special pins. Valid arguments are described as below: 0: (R1, R0) = (0, 0) which means R1 disabled and R0 disabled. diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra114-pinmux.yaml b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra114-pinmux.yaml index 065dedb3573a..1690c0ef553a 100644 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra114-pinmux.yaml +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra114-pinmux.yaml @@ -22,8 +22,6 @@ properties: patternProperties: "^pinmux(-[a-z0-9-_]+)?$": type: object - properties: - phandle: true # pin groups additionalProperties: diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.yaml b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.yaml index f924652bef0d..9b7368bd3862 100644 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.yaml +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.yaml @@ -32,8 +32,6 @@ properties: patternProperties: "^pinmux(-[a-z0-9-_]+)?$": type: object - properties: - phandle: true # pin groups additionalProperties: diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra194-pinmux.yaml b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra194-pinmux.yaml index 60a4bdf01bf2..87b6f4f42f25 100644 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra194-pinmux.yaml +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra194-pinmux.yaml @@ -23,8 +23,6 @@ properties: patternProperties: "^pinmux(-[a-z0-9-_]+)?$": type: object - properties: - phandle: true # pin groups additionalProperties: diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra20-pinmux.yaml b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra20-pinmux.yaml index 432ea40209a8..63cd743a30e0 100644 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra20-pinmux.yaml +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra20-pinmux.yaml @@ -24,8 +24,6 @@ properties: patternProperties: "^pinmux(-[a-z0-9-_]+)?$": type: object - properties: - phandle: true # pin groups additionalProperties: diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra210-pinmux.yaml b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra210-pinmux.yaml index 28ae2e6d0cbc..e99387a6da5e 100644 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra210-pinmux.yaml +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra210-pinmux.yaml @@ -22,8 +22,6 @@ properties: patternProperties: "^pinmux(-[a-z0-9-_]+)?$": type: object - properties: - phandle: true # pin groups additionalProperties: diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra30-pinmux.yaml b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra30-pinmux.yaml index c0eda7848767..36c8f3301a8f 100644 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra30-pinmux.yaml +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra30-pinmux.yaml @@ -22,8 +22,6 @@ properties: patternProperties: "^pinmux(-[a-z0-9-_]+)?$": type: object - properties: - phandle: true # pin groups additionalProperties: diff --git a/Documentation/devicetree/bindings/pinctrl/oxnas,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/oxnas,pinctrl.txt deleted file mode 100644 index b1159434f593..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/oxnas,pinctrl.txt +++ /dev/null @@ -1,56 +0,0 @@ -* Oxford Semiconductor OXNAS SoC Family Pin Controller - -Please refer to pinctrl-bindings.txt, ../gpio/gpio.txt, and -../interrupt-controller/interrupts.txt for generic information regarding -pin controller, GPIO, and interrupt bindings. - -OXNAS 'pin configuration node' is a node of a group of pins which can be -used for a specific device or function. This node represents configurations of -pins, optional function, and optional mux related configuration. - -Required properties for pin controller node: - - compatible: "oxsemi,ox810se-pinctrl" or "oxsemi,ox820-pinctrl" - - oxsemi,sys-ctrl: a phandle to the system controller syscon node - -Required properties for pin configuration sub-nodes: - - pins: List of pins to which the configuration applies. - -Optional properties for pin configuration sub-nodes: ----------------------------------------------------- - - function: Mux function for the specified pins. - - bias-pull-up: Enable weak pull-up. - -Example: - -pinctrl: pinctrl { - compatible = "oxsemi,ox810se-pinctrl"; - - /* Regmap for sys registers */ - oxsemi,sys-ctrl = <&sys>; - - pinctrl_uart2: pinctrl_uart2 { - uart2a { - pins = "gpio31"; - function = "fct3"; - }; - uart2b { - pins = "gpio32"; - function = "fct3"; - }; - }; -}; - -uart2: serial@900000 { - compatible = "ns16550a"; - reg = <0x900000 0x100000>; - clocks = <&sysclk>; - interrupts = <29>; - reg-shift = <0>; - fifo-size = <16>; - reg-io-width = <1>; - current-speed = <115200>; - no-loopback-test; - resets = <&reset 22>; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_uart2>; -}; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-max77620.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-max77620.txt index 511fc234558b..28fbca180068 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-max77620.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-max77620.txt @@ -38,7 +38,7 @@ Valid values for function properties are: gpio, lpm-control-in, fps-out, 32k-out, sd0-dvs-in, sd1-dvs-in, reference-out -Theres is also customised properties for the GPIO1, GPIO2 and GPIO3. These +There are also customised properties for the GPIO1, GPIO2 and GPIO3. These customised properties are required to configure FPS configuration parameters of these GPIOs. Please refer <devicetree/bindings/mfd/max77620.txt> for more detail of Flexible Power Sequence (FPS). diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-rk805.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-rk805.txt index 939cb5b6ffea..6ad49e51c72e 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-rk805.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-rk805.txt @@ -40,7 +40,7 @@ on default. Valid values for function properties are: gpio. -Theres is also not customised properties for any GPIO. +There are also not customised properties for any GPIO. Example: -------- diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt deleted file mode 100644 index bfd222b05495..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt +++ /dev/null @@ -1,262 +0,0 @@ -One-register-per-pin type device tree based pinctrl driver - -Required properties: -- compatible : "pinctrl-single" or "pinconf-single". - "pinctrl-single" means that pinconf isn't supported. - "pinconf-single" means that generic pinconf is supported. - -- reg : offset and length of the register set for the mux registers - -- #pinctrl-cells : number of cells in addition to the index, set to 1 - or 2 for pinctrl-single,pins and set to 2 for pinctrl-single,bits - -- pinctrl-single,register-width : pinmux register access width in bits - -- pinctrl-single,function-mask : mask of allowed pinmux function bits - in the pinmux register - -Optional properties: -- pinctrl-single,function-off : function off mode for disabled state if - available and same for all registers; if not specified, disabling of - pin functions is ignored - -- pinctrl-single,bit-per-mux : boolean to indicate that one register controls - more than one pin, for which "pinctrl-single,function-mask" property specifies - position mask of pin. - -- pinctrl-single,drive-strength : array of value that are used to configure - drive strength in the pinmux register. They're value of drive strength - current and drive strength mask. - - /* drive strength current, mask */ - pinctrl-single,power-source = <0x30 0xf0>; - -- pinctrl-single,bias-pullup : array of value that are used to configure the - input bias pullup in the pinmux register. - - /* input, enabled pullup bits, disabled pullup bits, mask */ - pinctrl-single,bias-pullup = <0 1 0 1>; - -- pinctrl-single,bias-pulldown : array of value that are used to configure the - input bias pulldown in the pinmux register. - - /* input, enabled pulldown bits, disabled pulldown bits, mask */ - pinctrl-single,bias-pulldown = <2 2 0 2>; - - * Two bits to control input bias pullup and pulldown: User should use - pinctrl-single,bias-pullup & pinctrl-single,bias-pulldown. One bit means - pullup, and the other one bit means pulldown. - * Three bits to control input bias enable, pullup and pulldown. User should - use pinctrl-single,bias-pullup & pinctrl-single,bias-pulldown. Input bias - enable bit should be included in pullup or pulldown bits. - * Although driver could set PIN_CONFIG_BIAS_DISABLE, there's no property as - pinctrl-single,bias-disable. Because pinctrl single driver could implement - it by calling pulldown, pullup disabled. - -- pinctrl-single,input-schmitt : array of value that are used to configure - input schmitt in the pinmux register. In some silicons, there're two input - schmitt value (rising-edge & falling-edge) in the pinmux register. - - /* input schmitt value, mask */ - pinctrl-single,input-schmitt = <0x30 0x70>; - -- pinctrl-single,input-schmitt-enable : array of value that are used to - configure input schmitt enable or disable in the pinmux register. - - /* input, enable bits, disable bits, mask */ - pinctrl-single,input-schmitt-enable = <0x30 0x40 0 0x70>; - -- pinctrl-single,low-power-mode : array of value that are used to configure - low power mode of this pin. For some silicons, the low power mode will - control the output of the pin when the pad including the pin enter low - power mode. - /* low power mode value, mask */ - pinctrl-single,low-power-mode = <0x288 0x388>; - -- pinctrl-single,gpio-range : list of value that are used to configure a GPIO - range. They're value of subnode phandle, pin base in pinctrl device, pin - number in this range, GPIO function value of this GPIO range. - The number of parameters is depend on #pinctrl-single,gpio-range-cells - property. - - /* pin base, nr pins & gpio function */ - pinctrl-single,gpio-range = <&range 0 3 0>, <&range 3 9 1>; - -- interrupt-controller : standard interrupt controller binding if using - interrupts for wake-up events for example. In this case pinctrl-single - is set up as a chained interrupt controller and the wake-up interrupts - can be requested by the drivers using request_irq(). - -- #interrupt-cells : standard interrupt binding if using interrupts - -This driver assumes that there is only one register for each pin (unless the -pinctrl-single,bit-per-mux is set), and uses the common pinctrl bindings as -specified in the pinctrl-bindings.txt document in this directory. - -The pin configuration nodes for pinctrl-single are specified as pinctrl -register offset and values using pinctrl-single,pins. Only the bits specified -in pinctrl-single,function-mask are updated. - -When #pinctrl-cells = 1, then setting a pin for a device could be done with: - - pinctrl-single,pins = <0xdc 0x118>; - -Where 0xdc is the offset from the pinctrl register base address for the device -pinctrl register, and 0x118 contains the desired value of the pinctrl register. - -When #pinctrl-cells = 2, then setting a pin for a device could be done with: - - pinctrl-single,pins = <0xdc 0x30 0x07>; - -Where 0x30 is the pin configuration value and 0x07 is the pin mux mode value. -These two values are OR'd together to produce the value stored at offset 0xdc. -See the device example and static board pins example below for more information. - -In case when one register changes more than one pin's mux the -pinctrl-single,bits need to be used which takes three parameters: - - pinctrl-single,bits = <0xdc 0x18 0xff>; - -Where 0xdc is the offset from the pinctrl register base address for the -device pinctrl register, 0x18 is the desired value, and 0xff is the sub mask to -be used when applying this change to the register. - - -Optional sub-node: In case some pins could be configured as GPIO in the pinmux -register, those pins could be defined as a GPIO range. This sub-node is required -by pinctrl-single,gpio-range property. - -Required properties in sub-node: -- #pinctrl-single,gpio-range-cells : the number of parameters after phandle in - pinctrl-single,gpio-range property. - - range: gpio-range { - #pinctrl-single,gpio-range-cells = <3>; - }; - - -Example: - -/* SoC common file */ - -/* first controller instance for pins in core domain */ -pmx_core: pinmux@4a100040 { - compatible = "pinctrl-single"; - reg = <0x4a100040 0x0196>; - #address-cells = <1>; - #size-cells = <0>; - #interrupt-cells = <1>; - interrupt-controller; - pinctrl-single,register-width = <16>; - pinctrl-single,function-mask = <0xffff>; -}; - -/* second controller instance for pins in wkup domain */ -pmx_wkup: pinmux@4a31e040 { - compatible = "pinctrl-single"; - reg = <0x4a31e040 0x0038>; - #address-cells = <1>; - #size-cells = <0>; - #interrupt-cells = <1>; - interrupt-controller; - pinctrl-single,register-width = <16>; - pinctrl-single,function-mask = <0xffff>; -}; - -control_devconf0: pinmux@48002274 { - compatible = "pinctrl-single"; - reg = <0x48002274 4>; /* Single register */ - #address-cells = <1>; - #size-cells = <0>; - pinctrl-single,bit-per-mux; - pinctrl-single,register-width = <32>; - pinctrl-single,function-mask = <0x5F>; -}; - -/* third controller instance for pins in gpio domain */ -pmx_gpio: pinmux@d401e000 { - compatible = "pinconf-single"; - reg = <0xd401e000 0x0330>; - #address-cells = <1>; - #size-cells = <1>; - ranges; - - pinctrl-single,register-width = <32>; - pinctrl-single,function-mask = <7>; - - /* sparse GPIO range could be supported */ - pinctrl-single,gpio-range = <&range 0 3 0>, <&range 3 9 1>, - <&range 12 1 0>, <&range 13 29 1>, - <&range 43 1 0>, <&range 44 49 1>, - <&range 94 1 1>, <&range 96 2 1>; - - range: gpio-range { - #pinctrl-single,gpio-range-cells = <3>; - }; -}; - - -/* board specific .dts file */ - -&pmx_core { - - /* - * map all board specific static pins enabled by the pinctrl driver - * itself during the boot (or just set them up in the bootloader) - */ - pinctrl-names = "default"; - pinctrl-0 = <&board_pins>; - - board_pins: pinmux_board_pins { - pinctrl-single,pins = < - 0x6c 0xf - 0x6e 0xf - 0x70 0xf - 0x72 0xf - >; - }; - - uart0_pins: pinmux_uart0_pins { - pinctrl-single,pins = < - 0x208 0 /* UART0_RXD (IOCFG138) */ - 0x20c 0 /* UART0_TXD (IOCFG139) */ - >; - pinctrl-single,bias-pulldown = <0 2 2>; - pinctrl-single,bias-pullup = <0 1 1>; - }; - - /* map uart2 pins */ - uart2_pins: pinmux_uart2_pins { - pinctrl-single,pins = < - 0xd8 0x118 - 0xda 0 - 0xdc 0x118 - 0xde 0 - >; - }; -}; - -&control_devconf0 { - mcbsp1_pins: pinmux_mcbsp1_pins { - pinctrl-single,bits = < - 0x00 0x18 0x18 /* FSR/CLKR signal from FSX/CLKX pin */ - >; - }; - - mcbsp2_clks_pins: pinmux_mcbsp2_clks_pins { - pinctrl-single,bits = < - 0x00 0x40 0x40 /* McBSP2 CLKS from McBSP_CLKS pin */ - >; - }; - -}; - -&uart1 { - pinctrl-names = "default"; - pinctrl-0 = <&uart0_pins>; -}; - -&uart2 { - pinctrl-names = "default"; - pinctrl-0 = <&uart2_pins>; -}; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-single.yaml b/Documentation/devicetree/bindings/pinctrl/pinctrl-single.yaml new file mode 100644 index 000000000000..45a307d3ce16 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-single.yaml @@ -0,0 +1,207 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/pinctrl-single.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic Pin Controller with a Single Register for One or More Pins + +maintainers: + - Tony Lindgren <tony@atomide.com> + +description: + Some pin controller devices use a single register for one or more pins. The + range of pin control registers can vary from one to many for each controller + instance. Some SoCs from Altera, Broadcom, HiSilicon, Ralink, and TI have this + kind of pin controller instances. + +properties: + compatible: + oneOf: + - enum: + - pinctrl-single + - pinconf-single + - items: + - enum: + - ti,am437-padconf + - ti,am654-padconf + - ti,dra7-padconf + - ti,omap2420-padconf + - ti,omap2430-padconf + - ti,omap3-padconf + - ti,omap4-padconf + - ti,omap5-padconf + - const: pinctrl-single + + reg: + maxItems: 1 + + interrupt-controller: true + + '#interrupt-cells': + const: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + '#pinctrl-cells': + description: + Number of cells. Usually 2, consisting of register offset, pin configuration + value, and pinmux mode. Some controllers may use 1 for just offset and value. + enum: [ 1, 2 ] + + pinctrl-single,bit-per-mux: + description: Optional flag to indicate register controls more than one pin + type: boolean + + pinctrl-single,function-mask: + description: Mask of the allowed register bits + $ref: /schemas/types.yaml#/definitions/uint32 + + pinctrl-single,function-off: + description: Optional function off mode for disabled state + $ref: /schemas/types.yaml#/definitions/uint32 + + pinctrl-single,register-width: + description: Width of pin specific bits in the register + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 8, 16, 32 ] + + pinctrl-single,gpio-range: + description: Optional list of pin base, nr pins & gpio function + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + - items: + - description: phandle of a gpio-range node + - description: pin base + - description: number of pins + - description: gpio function + + '#gpio-range-cells': + description: No longer needed, may exist in older files for gpio-ranges + deprecated: true + const: 3 + + gpio-range: + description: Optional node for gpio range cells + type: object + additionalProperties: false + properties: + '#pinctrl-single,gpio-range-cells': + description: Number of gpio range cells + const: 3 + $ref: /schemas/types.yaml#/definitions/uint32 + +patternProperties: + '-pins(-[0-9]+)?$|-pin$': + description: + Pin group node name using naming ending in -pins followed by an optional + instance number + type: object + additionalProperties: false + + properties: + pinctrl-single,pins: + description: + Array of pins as described in pinmux-node.yaml for pinctrl-pin-array + $ref: /schemas/types.yaml#/definitions/uint32-array + + pinctrl-single,bits: + description: Register bit configuration for pinctrl-single,bit-per-mux + $ref: /schemas/types.yaml#/definitions/uint32-array + items: + - description: register offset + - description: value + - description: pin bitmask in the register + + pinctrl-single,bias-pullup: + description: Optional bias pull up configuration + $ref: /schemas/types.yaml#/definitions/uint32-array + items: + - description: input + - description: enabled pull up bits + - description: disabled pull up bits + - description: bias pull up mask + + pinctrl-single,bias-pulldown: + description: Optional bias pull down configuration + $ref: /schemas/types.yaml#/definitions/uint32-array + items: + - description: input + - description: enabled pull down bits + - description: disabled pull down bits + - description: bias pull down mask + + pinctrl-single,drive-strength: + description: Optional drive strength configuration + $ref: /schemas/types.yaml#/definitions/uint32-array + items: + - description: drive strength current + - description: drive strength mask + + pinctrl-single,input-schmitt: + description: Optional input schmitt configuration + $ref: /schemas/types.yaml#/definitions/uint32-array + items: + - description: input + - description: enable bits + - description: disable bits + - description: input schmitt mask + + pinctrl-single,low-power-mode: + description: Optional low power mode configuration + $ref: /schemas/types.yaml#/definitions/uint32-array + items: + - description: low power mode value + - description: low power mode mask + + pinctrl-single,slew-rate: + description: Optional slew rate configuration + $ref: /schemas/types.yaml#/definitions/uint32-array + items: + - description: slew rate + - description: slew rate mask + +allOf: + - $ref: pinctrl.yaml# + +required: + - compatible + - reg + - pinctrl-single,register-width + +additionalProperties: false + +examples: + - | + soc { + #address-cells = <1>; + #size-cells = <1>; + + pinmux@4a100040 { + compatible = "pinctrl-single"; + reg = <0x4a100040 0x0196>; + #address-cells = <1>; + #size-cells = <0>; + #pinctrl-cells = <2>; + #interrupt-cells = <1>; + interrupt-controller; + pinctrl-single,register-width = <16>; + pinctrl-single,function-mask = <0xffff>; + pinctrl-single,gpio-range = <&range 0 3 0>; + range: gpio-range { + #pinctrl-single,gpio-range-cells = <3>; + }; + + uart2-pins { + pinctrl-single,pins = + <0xd8 0x118>, + <0xda 0>, + <0xdc 0x118>, + <0xde 0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml index 8aaf50181cef..3f8ad07c7cfd 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml @@ -26,6 +26,7 @@ properties: - qcom,pm6350-gpio - qcom,pm7250b-gpio - qcom,pm7325-gpio + - qcom,pm7550ba-gpio - qcom,pm8005-gpio - qcom,pm8008-gpio - qcom,pm8018-gpio @@ -53,6 +54,8 @@ properties: - qcom,pm8994-gpio - qcom,pm8998-gpio - qcom,pma8084-gpio + - qcom,pmc8180-gpio + - qcom,pmc8180c-gpio - qcom,pmi632-gpio - qcom,pmi8950-gpio - qcom,pmi8994-gpio @@ -68,6 +71,7 @@ properties: - qcom,pms405-gpio - qcom,pmx55-gpio - qcom,pmx65-gpio + - qcom,pmx75-gpio - enum: - qcom,spmi-gpio @@ -172,6 +176,7 @@ allOf: compatible: contains: enum: + - qcom,pm7550ba-gpio - qcom,pm8226-gpio - qcom,pm8350b-gpio - qcom,pm8550ve-gpio @@ -301,6 +306,7 @@ allOf: contains: enum: - qcom,pmx65-gpio + - qcom,pmx75-gpio then: properties: gpio-line-names: @@ -413,6 +419,7 @@ $defs: - gpio1-gpio9 for pm6350 - gpio1-gpio12 for pm7250b - gpio1-gpio10 for pm7325 + - gpio1-gpio8 for pm7550ba - gpio1-gpio4 for pm8005 - gpio1-gpio2 for pm8008 - gpio1-gpio6 for pm8018 @@ -456,6 +463,7 @@ $defs: - gpio1-gpio11 for pmx55 (holes on gpio3, gpio7, gpio10 and gpio11) - gpio1-gpio16 for pmx65 + - gpio1-gpio16 for pmx75 items: pattern: "^gpio([0-9]+)$" diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sa8775p-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sa8775p-tlmm.yaml index e608a4f1bcae..e119a226a4b1 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sa8775p-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sa8775p-tlmm.yaml @@ -87,7 +87,7 @@ $defs: emac0_mdc, emac0_mdio, emac0_ptp_aux, emac0_ptp_pps, emac1_mcg0, emac1_mcg1, emac1_mcg2, emac1_mcg3, emac1_mdc, emac1_mdio, emac1_ptp_aux, emac1_ptp_pps, gcc_gp1, gcc_gp2, gcc_gp3, - gcc_gp4, gcc_gp5, hs0_mi2s, hs1_mi2s, hs2_mi2s, ibi_i3c, + gcc_gp4, gcc_gp5, gpio, hs0_mi2s, hs1_mi2s, hs2_mi2s, ibi_i3c, jitter_bist, mdp0_vsync0, mdp0_vsync1, mdp0_vsync2, mdp0_vsync3, mdp0_vsync4, mdp0_vsync5, mdp0_vsync6, mdp0_vsync7, mdp0_vsync8, mdp1_vsync0, mdp1_vsync1, mdp1_vsync2, mdp1_vsync3, mdp1_vsync4, diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-lpass-lpi-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-lpass-lpi-pinctrl.yaml index fa51fa9536f7..00c5a00e35fc 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-lpass-lpi-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-lpass-lpi-pinctrl.yaml @@ -17,11 +17,6 @@ properties: compatible: const: qcom,sc7280-lpass-lpi-pinctrl - qcom,adsp-bypass-mode: - description: - Tells ADSP is in bypass mode. - type: boolean - reg: maxItems: 2 diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-lpass-lpi-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-lpass-lpi-pinctrl.yaml new file mode 100644 index 000000000000..abac3311fc55 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-lpass-lpi-pinctrl.yaml @@ -0,0 +1,135 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,sm6115-lpass-lpi-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM6115 SoC LPASS LPI TLMM + +maintainers: + - Konrad Dybcio <konradybcio@kernel.org> + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in the Low Power Audio SubSystem + (LPASS) Low Power Island (LPI) of Qualcomm SM6115 SoC. + +properties: + compatible: + const: qcom,sm6115-lpass-lpi-pinctrl + + reg: + items: + - description: LPASS LPI TLMM Control and Status registers + - description: LPASS LPI MCC registers + + clocks: + items: + - description: LPASS Audio voting clock + + clock-names: + items: + - const: audio + + gpio-controller: true + + "#gpio-cells": + description: Specifying the pin number and flags, as defined in + include/dt-bindings/gpio/gpio.h + const: 2 + + gpio-ranges: + maxItems: 1 + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-sm6115-lpass-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sm6115-lpass-state" + additionalProperties: false + +$defs: + qcom-sm6115-lpass-state: + type: object + description: + Pinctrl node's client devices use subnodes for desired pin configuration. + Client device subnodes use below standard properties. + $ref: /schemas/pinctrl/pincfg-node.yaml + + properties: + pins: + description: + List of gpio pins affected by the properties specified in this + subnode. + items: + pattern: "^gpio([0-9]|1[0-8])$" + + function: + enum: [ dmic01_clk, dmic01_data, dmic23_clk, dmic23_data, gpio, i2s1_clk, + i2s1_data, i2s1_ws, i2s2_clk, i2s2_data, i2s2_ws, i2s3_clk, + i2s3_data, i2s3_ws, qua_mi2s_data, qua_mi2s_sclk, qua_mi2s_ws, + swr_rx_clk, swr_rx_data, swr_tx_clk, swr_tx_data, wsa_mclk ] + description: + Specify the alternative function to be configured for the specified + pins. + + drive-strength: + enum: [2, 4, 6, 8, 10, 12, 14, 16] + default: 2 + description: + Selects the drive strength for the specified pins, in mA. + + slew-rate: + enum: [0, 1, 2, 3] + default: 0 + description: | + 0: No adjustments + 1: Higher Slew rate (faster edges) + 2: Lower Slew rate (slower edges) + 3: Reserved (No adjustments) + + bias-bus-hold: true + bias-pull-down: true + bias-pull-up: true + bias-disable: true + input-enable: true + output-high: true + output-low: true + + required: + - pins + - function + + additionalProperties: false + +allOf: + - $ref: pinctrl.yaml# + +required: + - compatible + - reg + - clocks + - clock-names + - gpio-controller + - "#gpio-cells" + - gpio-ranges + +additionalProperties: false + +examples: + - | + #include <dt-bindings/sound/qcom,q6afe.h> + + lpass_tlmm: pinctrl@a7c0000 { + compatible = "qcom,sm6115-lpass-lpi-pinctrl"; + reg = <0x0a7c0000 0x20000>, + <0x0a950000 0x10000>; + clocks = <&q6afecc LPASS_HW_DCODEC_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>; + clock-names = "audio"; + + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&lpass_tlmm 0 0 19>; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm8350-lpass-lpi-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm8350-lpass-lpi-pinctrl.yaml new file mode 100644 index 000000000000..2e65ae08dd21 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8350-lpass-lpi-pinctrl.yaml @@ -0,0 +1,143 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,sm8350-lpass-lpi-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM8350 SoC LPASS LPI TLMM + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in the Low Power Audio SubSystem + (LPASS) Low Power Island (LPI) of Qualcomm SM8350 SoC. + +properties: + compatible: + const: qcom,sm8350-lpass-lpi-pinctrl + + reg: + items: + - description: LPASS LPI TLMM Control and Status registers + - description: LPASS LPI MCC registers + + clocks: + items: + - description: LPASS Core voting clock + - description: LPASS Audio voting clock + + clock-names: + items: + - const: core + - const: audio + + gpio-controller: true + + "#gpio-cells": + description: Specifying the pin number and flags, as defined in + include/dt-bindings/gpio/gpio.h + const: 2 + + gpio-ranges: + maxItems: 1 + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-sm8350-lpass-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sm8350-lpass-state" + additionalProperties: false + +$defs: + qcom-sm8350-lpass-state: + type: object + description: + Pinctrl node's client devices use subnodes for desired pin configuration. + Client device subnodes use below standard properties. + $ref: /schemas/pinctrl/pincfg-node.yaml + + properties: + pins: + description: + List of gpio pins affected by the properties specified in this + subnode. + items: + pattern: "^gpio([0-9]|1[0-9]|2[0-2])$" + + function: + enum: [ dmic1_clk, dmic1_data, dmic2_clk, dmic2_data, dmic3_clk, + dmic3_data, dmic4_clk, dmic4_data, ext_mclk1_a, ext_mclk1_b, + ext_mclk1_c, ext_mclk1_d, ext_mclk1_e, gpio, i2s0_clk, + i2s0_data, i2s0_ws, i2s1_clk, i2s1_data, i2s1_ws, i2s2_clk, + i2s2_data, i2s2_ws, i2s3_clk, i2s3_data, i2s3_ws, i2s4_clk, + i2s4_data, i2s4_ws, slimbus_clk, slimbus_data, swr_rx_clk, + swr_rx_data, swr_tx_clk, swr_tx_data, wsa_swr_clk, + wsa_swr_data, wsa2_swr_clk, wsa2_swr_data ] + description: + Specify the alternative function to be configured for the specified + pins. + + drive-strength: + enum: [2, 4, 6, 8, 10, 12, 14, 16] + default: 2 + description: + Selects the drive strength for the specified pins, in mA. + + slew-rate: + enum: [0, 1, 2, 3] + default: 0 + description: | + 0: No adjustments + 1: Higher Slew rate (faster edges) + 2: Lower Slew rate (slower edges) + 3: Reserved (No adjustments) + + bias-bus-hold: true + bias-pull-down: true + bias-pull-up: true + bias-disable: true + input-enable: true + output-high: true + output-low: true + + required: + - pins + - function + + additionalProperties: false + +allOf: + - $ref: pinctrl.yaml# + +required: + - compatible + - reg + - clocks + - clock-names + - gpio-controller + - "#gpio-cells" + - gpio-ranges + +additionalProperties: false + +examples: + - | + #include <dt-bindings/sound/qcom,q6afe.h> + + lpass_tlmm: pinctrl@33c0000 { + compatible = "qcom,sm8350-lpass-lpi-pinctrl"; + reg = <0x033c0000 0x20000>, + <0x03550000 0x10000>; + + clocks = <&q6afecc LPASS_HW_MACRO_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>, + <&q6afecc LPASS_HW_DCODEC_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>; + clock-names = "core", "audio"; + + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&lpass_tlmm 0 0 15>; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,pfc.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,pfc.yaml index 0fc3c0f52c19..181cd1676c0a 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,pfc.yaml +++ b/Documentation/devicetree/bindings/pinctrl/renesas,pfc.yaml @@ -107,7 +107,6 @@ additionalProperties: Client device subnodes use below standard properties. properties: - phandle: true function: true groups: true pins: true @@ -127,9 +126,6 @@ additionalProperties: additionalProperties: false - type: object - properties: - phandle: true - additionalProperties: $ref: "#/additionalProperties/anyOf/0" diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rza1-ports.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,rza1-ports.yaml index 83800fcf0ce4..2bd7d47d0fdb 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,rza1-ports.yaml +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rza1-ports.yaml @@ -108,7 +108,6 @@ additionalProperties: Integers values in "pinmux" argument list are assembled as: ((PORT * 16 + PIN) | MUX_FUNC << 16) - phandle: true input-enable: true output-enable: true @@ -118,9 +117,6 @@ additionalProperties: additionalProperties: false - type: object - properties: - phandle: true - additionalProperties: $ref: "#/additionalProperties/anyOf/0" diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.yaml index 37173a64fed2..8271e7b2c162 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.yaml @@ -37,40 +37,37 @@ properties: gpio-ranges: maxItems: 1 -patternProperties: - "^.*$": - if: - type: object - then: - allOf: - - $ref: pincfg-node.yaml# - - $ref: pinmux-node.yaml# +additionalProperties: + type: object + + allOf: + - $ref: pincfg-node.yaml# + - $ref: pinmux-node.yaml# + + description: + The child nodes of the pin controller designate pins to be used for + specific peripheral functions or as GPIO. + + A pin multiplexing sub-node describes how to configure a set of + (or a single) pin in some desired alternate function mode. + The values for the pinmux properties are a combination of port name, + pin number and the desired function index. Use the RZA2_PINMUX macro + located in include/dt-bindings/pinctrl/r7s9210-pinctrl.h to easily + define these. + For assigning GPIO pins, use the macro RZA2_PIN also in + to express the desired port pin. + + properties: + pinmux: description: - The child nodes of the pin controller designate pins to be used for - specific peripheral functions or as GPIO. + Values are constructed from GPIO port number, pin number, and + alternate function configuration number using the RZA2_PINMUX() + helper macro in r7s9210-pinctrl.h. - A pin multiplexing sub-node describes how to configure a set of - (or a single) pin in some desired alternate function mode. - The values for the pinmux properties are a combination of port name, - pin number and the desired function index. Use the RZA2_PINMUX macro - located in include/dt-bindings/pinctrl/r7s9210-pinctrl.h to easily - define these. - For assigning GPIO pins, use the macro RZA2_PIN also in - to express the desired port pin. + required: + - pinmux - properties: - phandle: true - - pinmux: - description: - Values are constructed from GPIO port number, pin number, and - alternate function configuration number using the RZA2_PINMUX() - helper macro in r7s9210-pinctrl.h. - - required: - - pinmux - - additionalProperties: false + additionalProperties: false allOf: - $ref: pinctrl.yaml# @@ -82,8 +79,6 @@ required: - '#gpio-cells' - gpio-ranges -additionalProperties: false - examples: - | #include <dt-bindings/pinctrl/r7s9210-pinctrl.h> diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml index 9ce1a07fc015..145c5442f268 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml @@ -83,7 +83,6 @@ additionalProperties: Client device subnodes use below standard properties. properties: - phandle: true pinmux: description: Values are constructed from GPIO port number, pin number, and @@ -106,9 +105,6 @@ additionalProperties: line-name: true - type: object - properties: - phandle: true - additionalProperties: $ref: "#/additionalProperties/anyOf/0" diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rzn1-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,rzn1-pinctrl.yaml index 19d4d2facfb4..816688580e33 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,rzn1-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rzn1-pinctrl.yaml @@ -74,7 +74,6 @@ additionalProperties: offset by 10. Additional identifiers are provided to specify the MDIO source peripheral. - phandle: true bias-disable: true bias-pull-up: description: Pull up the pin with 50 kOhm @@ -91,9 +90,6 @@ additionalProperties: $ref: "#/additionalProperties/anyOf/0" - type: object - properties: - phandle: true - additionalProperties: $ref: "#/additionalProperties/anyOf/0" diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rzv2m-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,rzv2m-pinctrl.yaml index c87161f2954f..cb81a17bd0b1 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,rzv2m-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rzv2m-pinctrl.yaml @@ -63,7 +63,6 @@ additionalProperties: Client device subnodes use below standard properties. properties: - phandle: true pinmux: description: Values are constructed from GPIO port number, pin number, and @@ -87,9 +86,6 @@ additionalProperties: line-name: true - type: object - properties: - phandle: true - additionalProperties: $ref: "#/additionalProperties/anyOf/0" diff --git a/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.yaml index a6f34df82e90..880da721a927 100644 --- a/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.yaml @@ -32,7 +32,6 @@ additionalProperties: - $ref: pinmux-node.yaml# properties: - phandle: true function: true groups: true pins: true @@ -49,7 +48,6 @@ additionalProperties: - $ref: pinmux-node.yaml# properties: - phandle: true function: true groups: true pins: true diff --git a/Documentation/devicetree/bindings/pinctrl/sprd,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/sprd,pinctrl.txt index b1cea7a3a071..779b8ef0f6e6 100644 --- a/Documentation/devicetree/bindings/pinctrl/sprd,pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/sprd,pinctrl.txt @@ -8,7 +8,7 @@ to configure for some global common configuration, such as domain pad driving level, system control select and so on ("domain pad driving level": One pin can output 3.0v or 1.8v, depending on the related domain pad driving selection, if the related domain pad -slect 3.0v, then the pin can output 3.0v. "system control" is used +select 3.0v, then the pin can output 3.0v. "system control" is used to choose one function (like: UART0) for which system, since we have several systems (AP/CP/CM4) on one SoC.). diff --git a/Documentation/devicetree/bindings/pinctrl/ti,omap-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/ti,omap-pinctrl.txt deleted file mode 100644 index 88c80273da91..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/ti,omap-pinctrl.txt +++ /dev/null @@ -1,13 +0,0 @@ -OMAP Pinctrl definitions - -Required properties: -- compatible : Should be one of: - "ti,omap2420-padconf" - OMAP2420 compatible pinctrl - "ti,omap2430-padconf" - OMAP2430 compatible pinctrl - "ti,omap3-padconf" - OMAP3 compatible pinctrl - "ti,omap4-padconf" - OMAP4 compatible pinctrl - "ti,omap5-padconf" - OMAP5 compatible pinctrl - "ti,dra7-padconf" - DRA7 compatible pinctrl - "ti,am437-padconf" - AM437x compatible pinctrl - -See Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt for further details. diff --git a/Documentation/devicetree/bindings/pinctrl/xlnx,zynqmp-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/xlnx,zynqmp-pinctrl.yaml index 24ad0614e61b..01b6f2b57843 100644 --- a/Documentation/devicetree/bindings/pinctrl/xlnx,zynqmp-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/xlnx,zynqmp-pinctrl.yaml @@ -273,6 +273,10 @@ patternProperties: slew-rate: enum: [0, 1] + output-enable: + description: + This will internally disable the tri-state for MIO pins. + drive-strength: description: Selects the drive strength for MIO pins, in mA. diff --git a/Documentation/devicetree/bindings/pmem/pmem-region.txt b/Documentation/devicetree/bindings/pmem/pmem-region.txt index 5cfa4f016a00..cd79975e85ec 100644 --- a/Documentation/devicetree/bindings/pmem/pmem-region.txt +++ b/Documentation/devicetree/bindings/pmem/pmem-region.txt @@ -19,7 +19,7 @@ Required properties: - compatible = "pmem-region" - reg = <base, size>; - The reg property should specificy an address range that is + The reg property should specify an address range that is translatable to a system physical address range. This address range should be mappable as normal system memory would be (i.e cacheable). @@ -30,7 +30,7 @@ Required properties: node implies no special relationship between the two ranges. Optional properties: - - Any relevant NUMA assocativity properties for the target platform. + - Any relevant NUMA associativity properties for the target platform. - volatile; This property indicates that this region is actually backed by non-persistent memory. This lets the OS know that it diff --git a/Documentation/devicetree/bindings/power/amlogic,meson-sec-pwrc.yaml b/Documentation/devicetree/bindings/power/amlogic,meson-sec-pwrc.yaml index eab21bb2050a..dab3d92bc273 100644 --- a/Documentation/devicetree/bindings/power/amlogic,meson-sec-pwrc.yaml +++ b/Documentation/devicetree/bindings/power/amlogic,meson-sec-pwrc.yaml @@ -12,7 +12,7 @@ maintainers: - Jianxin Pan <jianxin.pan@amlogic.com> description: |+ - Secure Power Domains used in Meson A1/C1/S4 SoCs, and should be the child node + Secure Power Domains used in Meson A1/C1/S4 & C3/T7 SoCs, and should be the child node of secure-monitor. properties: @@ -20,6 +20,8 @@ properties: enum: - amlogic,meson-a1-pwrc - amlogic,meson-s4-pwrc + - amlogic,c3-pwrc + - amlogic,t7-pwrc "#power-domain-cells": const: 1 diff --git a/Documentation/devicetree/bindings/power/mediatek,power-controller.yaml b/Documentation/devicetree/bindings/power/mediatek,power-controller.yaml index c9acef80f452..8985e2df8a56 100644 --- a/Documentation/devicetree/bindings/power/mediatek,power-controller.yaml +++ b/Documentation/devicetree/bindings/power/mediatek,power-controller.yaml @@ -31,6 +31,7 @@ properties: - mediatek,mt8188-power-controller - mediatek,mt8192-power-controller - mediatek,mt8195-power-controller + - mediatek,mt8365-power-controller '#power-domain-cells': const: 1 @@ -88,6 +89,7 @@ $defs: "include/dt-bindings/power/mediatek,mt8188-power.h" - for MT8188 type power domain. "include/dt-bindings/power/mt8192-power.h" - for MT8192 type power domain. "include/dt-bindings/power/mt8195-power.h" - for MT8195 type power domain. + "include/dt-bindings/power/mediatek,mt8365-power.h" - for MT8365 type power domain. maxItems: 1 clocks: @@ -115,6 +117,10 @@ $defs: $ref: /schemas/types.yaml#/definitions/phandle description: phandle to the device containing the INFRACFG register range. + mediatek,infracfg-nao: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to the device containing the INFRACFG-NAO register range. + mediatek,smi: $ref: /schemas/types.yaml#/definitions/phandle description: phandle to the device containing the SMI register range. diff --git a/Documentation/devicetree/bindings/power/power-domain.yaml b/Documentation/devicetree/bindings/power/power-domain.yaml index d1235e562041..8fdb529d560b 100644 --- a/Documentation/devicetree/bindings/power/power-domain.yaml +++ b/Documentation/devicetree/bindings/power/power-domain.yaml @@ -13,8 +13,9 @@ maintainers: description: |+ System on chip designs are often divided into multiple PM domains that can be - used for power gating of selected IP blocks for power saving by reduced leakage - current. + used for power gating of selected IP blocks for power saving by reduced + leakage current. Moreover, in some cases the similar PM domains may also be + capable of scaling performance for a group of IP blocks. This device tree binding can be used to bind PM domain consumer devices with their PM domains provided by PM domain providers. A PM domain provider can be @@ -25,7 +26,7 @@ description: |+ properties: $nodename: - pattern: "^(power-controller|power-domain)([@-].*)?$" + pattern: "^(power-controller|power-domain|performance-domain)([@-].*)?$" domain-idle-states: $ref: /schemas/types.yaml#/definitions/phandle-array @@ -44,11 +45,11 @@ properties: operating-points-v2: description: - Phandles to the OPP tables of power domains provided by a power domain - provider. If the provider provides a single power domain only or all - the power domains provided by the provider have identical OPP tables, - then this shall contain a single phandle. Refer to ../opp/opp-v2-base.yaml - for more information. + Phandles to the OPP tables of power domains that are capable of scaling + performance, provided by a power domain provider. If the provider provides + a single power domain only or all the power domains provided by the + provider have identical OPP tables, then this shall contain a single + phandle. Refer to ../opp/opp-v2-base.yaml for more information. "#power-domain-cells": description: diff --git a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml index f9c211a9a938..da9c5846f4e1 100644 --- a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml +++ b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml @@ -15,41 +15,52 @@ description: properties: compatible: - enum: - - qcom,mdm9607-rpmpd - - qcom,msm8226-rpmpd - - qcom,msm8909-rpmpd - - qcom,msm8916-rpmpd - - qcom,msm8939-rpmpd - - qcom,msm8953-rpmpd - - qcom,msm8976-rpmpd - - qcom,msm8994-rpmpd - - qcom,msm8996-rpmpd - - qcom,msm8998-rpmpd - - qcom,qcm2290-rpmpd - - qcom,qcs404-rpmpd - - qcom,qdu1000-rpmhpd - - qcom,sa8155p-rpmhpd - - qcom,sa8540p-rpmhpd - - qcom,sa8775p-rpmhpd - - qcom,sdm660-rpmpd - - qcom,sc7180-rpmhpd - - qcom,sc7280-rpmhpd - - qcom,sc8180x-rpmhpd - - qcom,sc8280xp-rpmhpd - - qcom,sdm670-rpmhpd - - qcom,sdm845-rpmhpd - - qcom,sdx55-rpmhpd - - qcom,sdx65-rpmhpd - - qcom,sm6115-rpmpd - - qcom,sm6125-rpmpd - - qcom,sm6350-rpmhpd - - qcom,sm6375-rpmpd - - qcom,sm8150-rpmhpd - - qcom,sm8250-rpmhpd - - qcom,sm8350-rpmhpd - - qcom,sm8450-rpmhpd - - qcom,sm8550-rpmhpd + oneOf: + - enum: + - qcom,mdm9607-rpmpd + - qcom,msm8226-rpmpd + - qcom,msm8909-rpmpd + - qcom,msm8916-rpmpd + - qcom,msm8917-rpmpd + - qcom,msm8939-rpmpd + - qcom,msm8953-rpmpd + - qcom,msm8976-rpmpd + - qcom,msm8994-rpmpd + - qcom,msm8996-rpmpd + - qcom,msm8998-rpmpd + - qcom,qcm2290-rpmpd + - qcom,qcs404-rpmpd + - qcom,qdu1000-rpmhpd + - qcom,qm215-rpmpd + - qcom,sa8155p-rpmhpd + - qcom,sa8540p-rpmhpd + - qcom,sa8775p-rpmhpd + - qcom,sc7180-rpmhpd + - qcom,sc7280-rpmhpd + - qcom,sc8180x-rpmhpd + - qcom,sc8280xp-rpmhpd + - qcom,sc8380xp-rpmhpd + - qcom,sdm660-rpmpd + - qcom,sdm670-rpmhpd + - qcom,sdm845-rpmhpd + - qcom,sdx55-rpmhpd + - qcom,sdx65-rpmhpd + - qcom,sdx75-rpmhpd + - qcom,sm6115-rpmpd + - qcom,sm6125-rpmpd + - qcom,sm6350-rpmhpd + - qcom,sm6375-rpmpd + - qcom,sm7150-rpmhpd + - qcom,sm8150-rpmhpd + - qcom,sm8250-rpmhpd + - qcom,sm8350-rpmhpd + - qcom,sm8450-rpmhpd + - qcom,sm8550-rpmhpd + - qcom,sm8650-rpmhpd + - items: + - enum: + - qcom,msm8937-rpmpd + - const: qcom,msm8917-rpmpd '#power-domain-cells': const: 1 diff --git a/Documentation/devicetree/bindings/power/renesas,sysc-rmobile.yaml b/Documentation/devicetree/bindings/power/renesas,sysc-rmobile.yaml index 559718997de7..fba6914ec40d 100644 --- a/Documentation/devicetree/bindings/power/renesas,sysc-rmobile.yaml +++ b/Documentation/devicetree/bindings/power/renesas,sysc-rmobile.yaml @@ -58,7 +58,7 @@ $defs: pd-node: type: object description: - PM domain node representing a PM domain. This node hould be named by + PM domain node representing a PM domain. This node should be named by the real power area name, and thus its name should be unique. properties: diff --git a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml index 45d66c775115..a4b437fce37c 100644 --- a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml +++ b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.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/power/reset/gpio-poweroff.yaml# @@ -18,6 +18,9 @@ description: > Finally the operating system assumes the power off failed if the system is still running after waiting some time (timeout-ms). +allOf: + - $ref: restart-handler.yaml# + properties: compatible: const: gpio-poweroff @@ -40,6 +43,9 @@ properties: default: 100 description: Delay to wait after driving gpio inactive + priority: + default: 0 + timeout-ms: default: 3000 description: Time to wait before assuming the power off sequence failed. diff --git a/Documentation/devicetree/bindings/power/reset/gpio-restart.yaml b/Documentation/devicetree/bindings/power/reset/gpio-restart.yaml index d3d18e0f5db3..53535de0d41c 100644 --- a/Documentation/devicetree/bindings/power/reset/gpio-restart.yaml +++ b/Documentation/devicetree/bindings/power/reset/gpio-restart.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/power/reset/gpio-restart.yaml# diff --git a/Documentation/devicetree/bindings/power/reset/restart-handler.yaml b/Documentation/devicetree/bindings/power/reset/restart-handler.yaml index f2ffdd29d52a..965a834a3dbe 100644 --- a/Documentation/devicetree/bindings/power/reset/restart-handler.yaml +++ b/Documentation/devicetree/bindings/power/reset/restart-handler.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/power/reset/restart-handler.yaml# diff --git a/Documentation/devicetree/bindings/power/reset/syscon-poweroff.yaml b/Documentation/devicetree/bindings/power/reset/syscon-poweroff.yaml index 3412fe7e1e80..d342b113fca2 100644 --- a/Documentation/devicetree/bindings/power/reset/syscon-poweroff.yaml +++ b/Documentation/devicetree/bindings/power/reset/syscon-poweroff.yaml @@ -15,6 +15,9 @@ description: |+ defined by the register map pointed by syscon reference plus the offset with the value and mask defined in the poweroff node. Default will be little endian mode, 32 bit access only. + The SYSCON register map is normally retrieved from the parental dt-node. So + the SYSCON poweroff node should be represented as a sub-node of a "syscon", + "simple-mfd" node. properties: compatible: @@ -30,7 +33,10 @@ properties: regmap: $ref: /schemas/types.yaml#/definitions/phandle - description: Phandle to the register map node. + deprecated: true + description: + Phandle to the register map node. This property is deprecated in favor of + the syscon-poweroff node being a child of a system controller node. value: $ref: /schemas/types.yaml#/definitions/uint32 @@ -38,7 +44,6 @@ properties: required: - compatible - - regmap - offset additionalProperties: false @@ -56,7 +61,6 @@ examples: - | poweroff { compatible = "syscon-poweroff"; - regmap = <®mapnode>; offset = <0x0>; mask = <0x7a>; }; diff --git a/Documentation/devicetree/bindings/power/supply/bq256xx.yaml b/Documentation/devicetree/bindings/power/supply/bq256xx.yaml index 4fe9c3705265..a76afe3ca299 100644 --- a/Documentation/devicetree/bindings/power/supply/bq256xx.yaml +++ b/Documentation/devicetree/bindings/power/supply/bq256xx.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) # Copyright (C) 2020 Texas Instruments Incorporated %YAML 1.2 --- diff --git a/Documentation/devicetree/bindings/power/supply/max8925_battery.txt b/Documentation/devicetree/bindings/power/supply/max8925_battery.txt deleted file mode 100644 index d7e3e0c0f71d..000000000000 --- a/Documentation/devicetree/bindings/power/supply/max8925_battery.txt +++ /dev/null @@ -1,18 +0,0 @@ -max8925-battery bindings -~~~~~~~~~~~~~~~~ - -Optional properties : - - batt-detect: whether support battery detect - - topoff-threshold: set charging current in topoff mode - - fast-charge: set charging current in fast mode - - no-temp-support: whether support temperature protection detect - - no-insert-detect: whether support insert detect - -Example: - charger { - batt-detect = <0>; - topoff-threshold = <1>; - fast-charge = <7>; - no-temp-support = <0>; - no-insert-detect = <0>; - }; diff --git a/Documentation/devicetree/bindings/power/supply/maxim,max17040.yaml b/Documentation/devicetree/bindings/power/supply/maxim,max17040.yaml index 2627cd3eed83..377cbb2c2c1f 100644 --- a/Documentation/devicetree/bindings/power/supply/maxim,max17040.yaml +++ b/Documentation/devicetree/bindings/power/supply/maxim,max17040.yaml @@ -55,6 +55,14 @@ properties: interrupts: maxItems: 1 + io-channels: + items: + - description: battery temperature + + io-channel-names: + items: + - const: temp + wakeup-source: type: boolean description: | @@ -95,3 +103,26 @@ examples: wakeup-source; }; }; + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + fuel-gauge@36 { + compatible = "maxim,max17043"; + reg = <0x36>; + + interrupt-parent = <&gpio>; + interrupts = <144 IRQ_TYPE_EDGE_FALLING>; + + monitored-battery = <&battery>; + power-supplies = <&charger>; + + io-channels = <&adc 8>; + io-channel-names = "temp"; + + maxim,alert-low-soc-level = <10>; + wakeup-source; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/mitsumi,mm8013.yaml b/Documentation/devicetree/bindings/power/supply/mitsumi,mm8013.yaml new file mode 100644 index 000000000000..6865640cbdfa --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/mitsumi,mm8013.yaml @@ -0,0 +1,38 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/mitsumi,mm8013.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mitsumi MM8013 fuel gauge + +maintainers: + - Konrad Dybcio <konradybcio@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: mitsumi,mm8013 + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + fuel-gauge@55 { + compatible = "mitsumi,mm8013"; + reg = <0x55>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/qcom,pm8916-bms-vm.yaml b/Documentation/devicetree/bindings/power/supply/qcom,pm8916-bms-vm.yaml new file mode 100644 index 000000000000..ad764e69ab57 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/qcom,pm8916-bms-vm.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/qcom,pm8916-bms-vm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Voltage Mode BMS + +maintainers: + - Nikita Travkin <nikita@trvn.ru> + +description: + Voltage Mode BMS is a hardware block found in some Qualcomm PMICs + such as pm8916. This block performs battery voltage monitoring. + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: qcom,pm8916-bms-vm + + reg: + maxItems: 1 + + interrupts: + items: + - description: BMS FSM left S3 mode + - description: BMS FSM entered S2 mode + - description: OCV measured in S3 mode + - description: OCV below threshold + - description: FIFO update done + - description: BMS FSM switched state + + interrupt-names: + items: + - const: cv_leave + - const: cv_enter + - const: ocv_good + - const: ocv_thr + - const: fifo + - const: state_chg + + monitored-battery: true + + power-supplies: true + +required: + - compatible + - reg + - interrupts + - interrupt-names + - monitored-battery + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + pmic { + #address-cells = <1>; + #size-cells = <0>; + + battery@4000 { + compatible = "qcom,pm8916-bms-vm"; + reg = <0x4000>; + interrupts = <0x0 0x40 0 IRQ_TYPE_EDGE_RISING>, + <0x0 0x40 1 IRQ_TYPE_EDGE_RISING>, + <0x0 0x40 2 IRQ_TYPE_EDGE_RISING>, + <0x0 0x40 3 IRQ_TYPE_EDGE_RISING>, + <0x0 0x40 4 IRQ_TYPE_EDGE_RISING>, + <0x0 0x40 5 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "cv_leave", + "cv_enter", + "ocv_good", + "ocv_thr", + "fifo", + "state_chg"; + + monitored-battery = <&battery>; + power-supplies = <&pm8916_charger>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/qcom,pm8916-lbc.yaml b/Documentation/devicetree/bindings/power/supply/qcom,pm8916-lbc.yaml new file mode 100644 index 000000000000..cdf14e5ed119 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/qcom,pm8916-lbc.yaml @@ -0,0 +1,128 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/qcom,pm8916-lbc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Linear Battery Charger + +maintainers: + - Nikita Travkin <nikita@trvn.ru> + +description: + Linear Battery Charger hardware block, found in some Qualcomm PMICs + such as pm8916. Implements a simple, autonomous CC/CV charger. + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: qcom,pm8916-lbc + + reg: + items: + - description: Charger + - description: Battery + - description: USB + - description: MISC + + reg-names: + items: + - const: chgr + - const: bat_if + - const: usb + - const: misc + + interrupts: + items: + - description: Battery detection + - description: Fast charging + - description: Charging failed + - description: Charging done + - description: Battery present + - description: Battery temperature OK + - description: USB coarse detection + - description: USB IN valid + - description: Charger gone + - description: Overtemperature + + interrupt-names: + items: + - const: vbat_det + - const: fast_chg + - const: chg_fail + - const: chg_done + - const: bat_pres + - const: temp_ok + - const: coarse_det + - const: usb_vbus + - const: chg_gone + - const: overtemp + + qcom,fast-charge-safe-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 4000000 + maximum: 4775000 + description: + Maximum safe battery voltage in uV; May be pre-set by bootloader, + in which case, setting this will harmlessly fail. + + qcom,fast-charge-safe-current: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 90000 + maximum: 1440000 + description: + Maximum safe battery charge current in uA; May be pre-set by + bootloader, in which case setting this will harmlessly fail. + + monitored-battery: true + +required: + - compatible + - reg + - interrupts + - interrupt-names + - qcom,fast-charge-safe-voltage + - qcom,fast-charge-safe-current + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + pmic { + #address-cells = <1>; + #size-cells = <0>; + + charger@1000 { + compatible = "qcom,pm8916-lbc"; + reg = <0x1000>, <0x1200>, <0x1300>, <0x1600>; + reg-names = "chgr", "bat_if", "usb", "misc"; + + interrupts = <0x0 0x10 0 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x10 5 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x10 6 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x10 7 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x12 0 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x12 1 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x13 0 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x13 1 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x13 2 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x13 4 IRQ_TYPE_EDGE_BOTH>; + interrupt-names = "vbat_det", + "fast_chg", + "chg_fail", + "chg_done", + "bat_pres", + "temp_ok", + "coarse_det", + "usb_vbus", + "chg_gone", + "overtemp"; + monitored-battery = <&battery>; + + qcom,fast-charge-safe-current = <900000>; + qcom,fast-charge-safe-voltage = <4300000>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/sbs,sbs-manager.yaml b/Documentation/devicetree/bindings/power/supply/sbs,sbs-manager.yaml index 99f506d6b0a0..2e21846463ba 100644 --- a/Documentation/devicetree/bindings/power/supply/sbs,sbs-manager.yaml +++ b/Documentation/devicetree/bindings/power/supply/sbs,sbs-manager.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/power/supply/sbs,sbs-manager.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: SBS compliant manger +title: SBS compliant manager maintainers: - Sebastian Reichel <sre@kernel.org> @@ -47,6 +47,12 @@ patternProperties: "^i2c@[1-4]$": type: object $ref: /schemas/i2c/i2c-controller.yaml# + unevaluatedProperties: false + + properties: + reg: + minimum: 1 + maximum: 4 examples: - | diff --git a/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-battery.txt b/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-battery.txt deleted file mode 100644 index ee125cb0e46d..000000000000 --- a/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-battery.txt +++ /dev/null @@ -1,34 +0,0 @@ -AB85000 PMIC contains a node, which contains shared -information about the battery connected to the PMIC. -The node has no compatible property. - -Properties of this node are: - -thermistor-on-batctrl: - A boolean value indicating thermistor interface to battery - - Note: - 'btemp' and 'batctrl' are the pins interfaced for battery temperature - measurement, 'btemp' signal is used when NTC(negative temperature - coefficient) resister is interfaced external to battery whereas - 'batctrl' pin is used when NTC resister is internal to battery. - - Example: - ab8500_battery: ab8500_battery { - thermistor-on-batctrl; - }; - indicates: NTC resister is internal to battery, 'batctrl' is used - for thermal measurement. - - The absence of property 'thermal-on-batctrl' indicates - NTC resister is external to battery and 'btemp' signal is used - for thermal measurement. - -battery-type: - This shall be the battery manufacturing technology type, - allowed types are: - "UNKNOWN" "NiMH" "LION" "LIPO" "LiFe" "NiCd" "LiMn" - Example: - ab8500_battery: ab8500_battery { - stericsson,battery-type = "LIPO"; - } diff --git a/Documentation/devicetree/bindings/power/xlnx,zynqmp-genpd.txt b/Documentation/devicetree/bindings/power/xlnx,zynqmp-genpd.txt deleted file mode 100644 index 54b9f9d0f90f..000000000000 --- a/Documentation/devicetree/bindings/power/xlnx,zynqmp-genpd.txt +++ /dev/null @@ -1,34 +0,0 @@ ------------------------------------------------------------ -Device Tree Bindings for the Xilinx Zynq MPSoC PM domains ------------------------------------------------------------ -The binding for zynqmp-power-controller follow the common -generic PM domain binding[1]. - -[1] Documentation/devicetree/bindings/power/power-domain.yaml - -== Zynq MPSoC Generic PM Domain Node == - -Required property: - - Below property should be in zynqmp-firmware node. - - #power-domain-cells: Number of cells in a PM domain specifier. Must be 1. - -Power domain ID indexes are mentioned in -include/dt-bindings/power/xlnx-zynqmp-power.h. - -------- -Example -------- - -firmware { - zynqmp_firmware: zynqmp-firmware { - ... - #power-domain-cells = <1>; - ... - }; -}; - -sata { - ... - power-domains = <&zynqmp_firmware 28>; - ... -}; diff --git a/Documentation/devicetree/bindings/powerpc/fsl/cpus.txt b/Documentation/devicetree/bindings/powerpc/fsl/cpus.txt index 801c66069121..4787db8de23f 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/cpus.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/cpus.txt @@ -28,6 +28,6 @@ PROPERTIES Snoop ID Port Mapping registers, which are part of the CoreNet Coherency fabric (CCF), provide a CoreNet Coherency Subdomain ID/CoreNet Snoop ID to cpu mapping functions. Certain bits from - these registers should be set if the coresponding CPU should be + these registers should be set if the corresponding CPU should be snooped. This property defines a bitmask which selects the bit that should be set if this cpu should be snooped. diff --git a/Documentation/devicetree/bindings/powerpc/fsl/dcsr.txt b/Documentation/devicetree/bindings/powerpc/fsl/dcsr.txt index 4b01e1afafda..62744afb5b75 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/dcsr.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/dcsr.txt @@ -185,10 +185,10 @@ PROPERTIES with distinct functionality. The first register range describes the CoreNet Debug Controller - functionalty to perform transaction and transaction attribute matches. + functionality to perform transaction and transaction attribute matches. The second register range describes the CoreNet Debug Controller - functionalty to trigger event notifications and debug traces. + functionality to trigger event notifications and debug traces. EXAMPLE dcsr-corenet { diff --git a/Documentation/devicetree/bindings/powerpc/fsl/raideng.txt b/Documentation/devicetree/bindings/powerpc/fsl/raideng.txt index 4ad29b9ac2ac..ea902bc5873d 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/raideng.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/raideng.txt @@ -60,7 +60,7 @@ Optional property: - fsl,liodn: Specifies the LIODN to be used for Job Ring. This property is normally set by firmware. Value is of 12-bits which is the LIODN number for this JR. - This property is used by the IOMMU (PAMU) to distinquish + This property is used by the IOMMU (PAMU) to distinguish transactions from this JR and than be able to do address translation & protection accordingly. diff --git a/Documentation/devicetree/bindings/powerpc/nintendo/gamecube.txt b/Documentation/devicetree/bindings/powerpc/nintendo/gamecube.txt index b558585b1aaf..3826bd1219d1 100644 --- a/Documentation/devicetree/bindings/powerpc/nintendo/gamecube.txt +++ b/Documentation/devicetree/bindings/powerpc/nintendo/gamecube.txt @@ -42,7 +42,7 @@ Nintendo GameCube device tree - compatible : should be "nintendo,flipper-pic" -1.c) The Digital Signal Procesor (DSP) node +1.c) The Digital Signal Processor (DSP) node Represents the digital signal processor interface, designed to offload audio related tasks. diff --git a/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt b/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt index 3ff6ebbb4998..6f69a9dfe198 100644 --- a/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt +++ b/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt @@ -53,7 +53,7 @@ Nintendo Wii device tree - compatible : should be "nintendo,flipper-pic" - interrupt-controller -1.c) The Digital Signal Procesor (DSP) node +1.c) The Digital Signal Processor (DSP) node Represents the digital signal processor interface, designed to offload audio related tasks. diff --git a/Documentation/devicetree/bindings/pps/pps-gpio.txt b/Documentation/devicetree/bindings/pps/pps-gpio.txt deleted file mode 100644 index 9012a2a02e14..000000000000 --- a/Documentation/devicetree/bindings/pps/pps-gpio.txt +++ /dev/null @@ -1,30 +0,0 @@ -Device-Tree Bindings for a PPS Signal on GPIO - -These properties describe a PPS (pulse-per-second) signal connected to -a GPIO pin. - -Required properties: -- compatible: should be "pps-gpio" -- gpios: one PPS GPIO in the format described by ../gpio/gpio.txt - -Additional required properties for the PPS ECHO functionality: -- echo-gpios: one PPS ECHO GPIO in the format described by ../gpio/gpio.txt -- echo-active-ms: duration in ms of the active portion of the echo pulse - -Optional properties: -- assert-falling-edge: when present, assert is indicated by a falling edge - (instead of by a rising edge) - -Example: - pps { - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_pps>; - - gpios = <&gpio1 26 GPIO_ACTIVE_HIGH>; - assert-falling-edge; - - echo-gpios = <&gpio1 27 GPIO_ACTIVE_HIGH>; - echo-active-ms = <100>; - - compatible = "pps-gpio"; - }; diff --git a/Documentation/devicetree/bindings/pps/pps-gpio.yaml b/Documentation/devicetree/bindings/pps/pps-gpio.yaml new file mode 100644 index 000000000000..fd4adfa8d2d4 --- /dev/null +++ b/Documentation/devicetree/bindings/pps/pps-gpio.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pps/pps-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: PPS Signal via GPIO + +maintainers: + - Fabio Estevam <festevam@gmail.com> + +properties: + compatible: + const: pps-gpio + + gpios: + description: The GPIO that provides the PPS signal. + maxItems: 1 + + echo-gpios: + description: The GPIO that provides the PPS ECHO signal. + maxItems: 1 + + echo-active-ms: + description: Duration in ms of the active portion of the echo pulse. + + assert-falling-edge: + description: Indicates a falling edge assert, when present. Rising edge if absent. + type: boolean + +required: + - compatible + - gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + pps { + compatible = "pps-gpio"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_pps>; + gpios = <&gpio1 26 GPIO_ACTIVE_HIGH>; + assert-falling-edge; + echo-gpios = <&gpio1 27 GPIO_ACTIVE_HIGH>; + echo-active-ms = <100>; + }; diff --git a/Documentation/devicetree/bindings/pwm/brcm,kona-pwm.txt b/Documentation/devicetree/bindings/pwm/brcm,kona-pwm.txt deleted file mode 100644 index c42eecfc81ed..000000000000 --- a/Documentation/devicetree/bindings/pwm/brcm,kona-pwm.txt +++ /dev/null @@ -1,21 +0,0 @@ -Broadcom Kona PWM controller device tree bindings - -This controller has 6 channels. - -Required Properties : -- compatible: should contain "brcm,kona-pwm" -- reg: physical base address and length of the controller's registers -- clocks: phandle + clock specifier pair for the external clock -- #pwm-cells: Should be 3. See pwm.yaml in this directory for a - description of the cells format. - -Refer to clocks/clock-bindings.txt for generic clock consumer properties. - -Example: - -pwm: pwm@3e01a000 { - compatible = "brcm,bcm11351-pwm", "brcm,kona-pwm"; - reg = <0x3e01a000 0xc4>; - clocks = <&pwm_clk>; - #pwm-cells = <3>; -}; diff --git a/Documentation/devicetree/bindings/pwm/brcm,kona-pwm.yaml b/Documentation/devicetree/bindings/pwm/brcm,kona-pwm.yaml new file mode 100644 index 000000000000..e86c8053b366 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/brcm,kona-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/brcm,kona-pwm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom Kona family PWM controller + +description: + This controller has 6 channels. + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +allOf: + - $ref: pwm.yaml# + +properties: + compatible: + items: + - enum: + - brcm,bcm11351-pwm + - const: brcm,kona-pwm + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + '#pwm-cells': + const: 3 + +required: + - compatible + - reg + - clocks + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/bcm281xx.h> + + pwm@3e01a000 { + compatible = "brcm,bcm11351-pwm", "brcm,kona-pwm"; + reg = <0x3e01a000 0xcc>; + clocks = <&slave_ccu BCM281XX_SLAVE_CCU_PWM>; + #pwm-cells = <3>; + }; +... diff --git a/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml b/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml index f2d1dc7e7b3f..65bfb492b3a4 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml +++ b/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml @@ -32,6 +32,7 @@ properties: - rockchip,rk3308-pwm - rockchip,rk3568-pwm - rockchip,rk3588-pwm + - rockchip,rv1126-pwm - const: rockchip,rk3328-pwm reg: diff --git a/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml b/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml index fe603fb1b2cc..2162f661ed5a 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml +++ b/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml @@ -20,12 +20,17 @@ description: |+ properties: compatible: - enum: - - samsung,s3c2410-pwm # 16-bit, S3C24xx - - samsung,s3c6400-pwm # 32-bit, S3C64xx - - samsung,s5p6440-pwm # 32-bit, S5P64x0 - - samsung,s5pc100-pwm # 32-bit, S5PC100, S5PV210, Exynos4210 rev0 SoCs - - samsung,exynos4210-pwm # 32-bit, Exynos + oneOf: + - enum: + - samsung,s3c2410-pwm # 16-bit, S3C24xx + - samsung,s3c6400-pwm # 32-bit, S3C64xx + - samsung,s5p6440-pwm # 32-bit, S5P64x0 + - samsung,s5pc100-pwm # 32-bit, S5PC100, S5PV210, Exynos4210 rev0 SoCs + - samsung,exynos4210-pwm # 32-bit, Exynos + - items: + - enum: + - samsung,exynosautov9-pwm + - const: samsung,exynos4210-pwm reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/pwm/snps,dw-apb-timers-pwm2.yaml b/Documentation/devicetree/bindings/pwm/snps,dw-apb-timers-pwm2.yaml index 9aabdb373afa..4d0b5964443d 100644 --- a/Documentation/devicetree/bindings/pwm/snps,dw-apb-timers-pwm2.yaml +++ b/Documentation/devicetree/bindings/pwm/snps,dw-apb-timers-pwm2.yaml @@ -18,7 +18,7 @@ description: The IP block has a version register so this can be used for detection instead of having to encode the IP version number in the device tree - comaptible. + compatible. allOf: - $ref: pwm.yaml# diff --git a/Documentation/devicetree/bindings/regulator/active-semi,act8846.yaml b/Documentation/devicetree/bindings/regulator/active-semi,act8846.yaml index 3725348bb235..02f45b5834d0 100644 --- a/Documentation/devicetree/bindings/regulator/active-semi,act8846.yaml +++ b/Documentation/devicetree/bindings/regulator/active-semi,act8846.yaml @@ -28,75 +28,37 @@ properties: the VSEL pin is assumed to be low. type: boolean - regulators: - type: object - additionalProperties: false + inl1-supply: + description: Handle to the INL1 input supply (REG5-7) - properties: - REG1: - type: object - $ref: /schemas/regulator/regulator.yaml# - unevaluatedProperties: false + inl2-supply: + description: Handle to the INL2 input supply (REG8-9) - properties: - vp1-supply: - description: Handle to the VP1 input supply + inl3-supply: + description: Handle to the INL3 input supply (REG10-12) - REG2: - type: object - $ref: /schemas/regulator/regulator.yaml# - unevaluatedProperties: false + vp1-supply: + description: Handle to the VP1 input supply (REG1) - properties: - vp2-supply: - description: Handle to the VP2 input supply + vp2-supply: + description: Handle to the VP2 input supply (REG2) - REG3: - type: object - $ref: /schemas/regulator/regulator.yaml# - unevaluatedProperties: false + vp3-supply: + description: Handle to the VP3 input supply (REG3) - properties: - vp3-supply: - description: Handle to the VP3 input supply - - REG4: - type: object - $ref: /schemas/regulator/regulator.yaml# - unevaluatedProperties: false + vp4-supply: + description: Handle to the VP4 input supply (REG4) - properties: - vp4-supply: - description: Handle to the VP4 input supply + regulators: + type: object + additionalProperties: false patternProperties: - "^REG[5-7]$": + "^REG([1-9]|1[0-2])$": type: object $ref: /schemas/regulator/regulator.yaml# unevaluatedProperties: false - properties: - inl1-supply: - description: Handle to the INL1 input supply - - "^REG[8-9]$": - type: object - $ref: /schemas/regulator/regulator.yaml# - unevaluatedProperties: false - - properties: - inl2-supply: - description: Handle to the INL2 input supply - - "^REG1[0-2]$": - type: object - $ref: /schemas/regulator/regulator.yaml# - unevaluatedProperties: false - - properties: - inl3-supply: - description: Handle to the INL3 input supply - additionalProperties: false required: diff --git a/Documentation/devicetree/bindings/regulator/adi,max77503-regulator.yaml b/Documentation/devicetree/bindings/regulator/adi,max77503-regulator.yaml new file mode 100644 index 000000000000..aa581e550be2 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/adi,max77503-regulator.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright (c) 2023 Analog Devices, Inc. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/adi,max77503-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices MAX77503 Buck Converter + +maintainers: + - Gokhan Celik <Gokhan.Celik@analog.com> + +description: | + The Analog Devices MAX77503 is a single channel 14V input, 1.5A + high-efficiency buck converter. This converter has 94% efficiency + for 2-Cell/3-Cell battery applications. + +allOf: + - $ref: regulator.yaml# + +properties: + compatible: + enum: + - adi,max77503 + + reg: + description: I2C address of the device + items: + - enum: [0x1e, 0x24, 0x37] + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + regulator@1e { + compatible = "adi,max77503"; + reg = <0x1e>; + + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <5000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/adi,max77857.yaml b/Documentation/devicetree/bindings/regulator/adi,max77857.yaml new file mode 100644 index 000000000000..d1fa74aca721 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/adi,max77857.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2022 Analog Devices Inc. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/adi,max77857.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices MAX77857 Buck-Boost Converter + +maintainers: + - Ibrahim Tilki <Ibrahim.Tilki@analog.com> + - Okan Sahin <Okan.Sahin@analog.com> + +description: Analog Devices MAX77857 Buck-Boost Converter + +properties: + compatible: + enum: + - adi,max77831 + - adi,max77857 + - adi,max77859 + - adi,max77859a + + reg: + description: I2C address of the device + items: + - enum: [0x66, 0x67, 0x6E, 0x6F] + + interrupts: + maxItems: 1 + + adi,switch-frequency-hz: + description: Switching frequency of the Buck-Boost converter in Hz. + items: + - enum: [1200000, 1500000, 1800000, 2100000] + + adi,rtop-ohms: + description: Top feedback resistor value in ohms for external feedback. + minimum: 150000 + maximum: 330000 + + adi,rbot-ohms: + description: Bottom feedback resistor value in ohms for external feedback. + +dependencies: + adi,rtop-ohms: [ 'adi,rbot-ohms' ] + adi,rbot-ohms: [ 'adi,rtop-ohms' ] + +required: + - compatible + - reg + +allOf: + - $ref: regulator.yaml# + - if: + properties: + compatible: + contains: + enum: + - adi,max77831 + + then: + properties: + adi,switch-frequency-hz: + items: + enum: [1200000, 1500000, 1800000] + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + regulator@66 { + reg = <0x66>; + compatible = "adi,max77857"; + interrupt-parent = <&gpio>; + interrupts = <26 IRQ_TYPE_EDGE_FALLING>; + + adi,rtop-ohms = <312000>; + adi,rbot-ohms = <12000>; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/awinic,aw37503.yaml b/Documentation/devicetree/bindings/regulator/awinic,aw37503.yaml new file mode 100644 index 000000000000..c92a881ed60e --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/awinic,aw37503.yaml @@ -0,0 +1,78 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/awinic,aw37503.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Awinic AW37503 Voltage Regulator + +maintainers: + - Alec Li <like@awinic.com> + +description: + The AW37503 are dual voltage regulator, designed to support positive/negative + supply for driving TFT-LCD panels. It support software-configurable output + switching and monitoring. The output voltages can be programmed via an I2C + compatible interface. + +properties: + compatible: + const: awinic,aw37503 + + 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. + + required: + - regulator-name + +required: + - compatible + - reg + - outp + - outn + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + regulator@3e { + compatible = "awinic,aw37503"; + reg = <0x3e>; + + outp { + regulator-name = "outp"; + regulator-boot-on; + regulator-always-on; + enable-gpios = <&gpio 17 GPIO_ACTIVE_LOW>; + }; + + outn { + regulator-name = "outn"; + regulator-boot-on; + regulator-always-on; + enable-gpios = <&gpio 27 GPIO_ACTIVE_LOW>; + }; + }; + }; +... + diff --git a/Documentation/devicetree/bindings/regulator/da9210.txt b/Documentation/devicetree/bindings/regulator/da9210.txt deleted file mode 100644 index 58065ca9e3b4..000000000000 --- a/Documentation/devicetree/bindings/regulator/da9210.txt +++ /dev/null @@ -1,29 +0,0 @@ -* Dialog Semiconductor DA9210 Multi-phase 12A DCDC BUCK Converter - -Required properties: - -- compatible: must be "dlg,da9210" -- reg: the i2c slave address of the regulator. It should be 0x68. - -Optional properties: - -- interrupts: a reference to the DA9210 interrupt, if available. - -Any standard regulator properties can be used to configure the single da9210 -DCDC. - -Example: - - da9210@68 { - compatible = "dlg,da9210"; - reg = <0x68>; - - interrupt-parent = <...>; - interrupts = <...>; - - regulator-min-microvolt = <300000>; - regulator-max-microvolt = <1570000>; - regulator-min-microamp = <1600000>; - regulator-max-microamp = <4600000>; - regulator-boot-on; - }; diff --git a/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml b/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml index dc626517c2ad..13b3f75f8e5e 100644 --- a/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml +++ b/Documentation/devicetree/bindings/regulator/dlg,da9121.yaml @@ -95,11 +95,6 @@ properties: Properties for a single BUCK regulator properties: - regulator-name: - pattern: "^BUCK([1-2])$" - description: | - BUCK2 present in DA9122, DA9220, DA9131, DA9132 only - regulator-initial-mode: enum: [ 0, 1, 2, 3 ] description: Defined in include/dt-bindings/regulator/dlg,da9121-regulator.h @@ -122,6 +117,23 @@ required: - reg - regulators +allOf: + - if: + properties: + compatible: + not: + contains: + enum: + - dlg,da9122 + - dlg,da9131 + - dlg,da9132 + - dlg,da9220 + then: + properties: + regulators: + properties: + buck2: false + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/regulator/dlg,da9210.yaml b/Documentation/devicetree/bindings/regulator/dlg,da9210.yaml new file mode 100644 index 000000000000..81f23de36de4 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/dlg,da9210.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/dlg,da9210.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Dialog Semiconductor DA9210 Multi-Phase 12A DC-DC Buck Converter + +maintainers: + - Support Opensource <support.opensource@diasemi.com> + +allOf: + - $ref: regulator.yaml# + +properties: + compatible: + const: dlg,da9210 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + regulator@68 { + compatible = "dlg,da9210"; + reg = <0x68>; + + interrupt-parent = <&irqc0>; + interrupts = <2 IRQ_TYPE_LEVEL_LOW>; + + regulator-min-microvolt = <300000>; + regulator-max-microvolt = <1570000>; + regulator-min-microamp = <1600000>; + regulator-max-microamp = <4600000>; + regulator-boot-on; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/dlg,slg51000.yaml b/Documentation/devicetree/bindings/regulator/dlg,slg51000.yaml new file mode 100644 index 000000000000..bad140418e49 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/dlg,slg51000.yaml @@ -0,0 +1,132 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/dlg,slg51000.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Dialog Semiconductor SLG51000 Voltage Regulator + +maintainers: + - Eric Jeong <eric.jeong.opensource@diasemi.com> + - Support Opensource <support.opensource@diasemi.com> + +properties: + compatible: + const: dlg,slg51000 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + dlg,cs-gpios: + maxItems: 1 + description: + GPIO for chip select + + vin3-supply: + description: + Input supply for ldo3, required if regulator is enabled + + vin4-supply: + description: + Input supply for ldo4, required if regulator is enabled + + vin5-supply: + description: + Input supply for ldo5, required if regulator is enabled + + vin6-supply: + description: + Input supply for ldo6, required if regulator is enabled + + vin7-supply: + description: + Input supply for ldo7, required if regulator is enabled + + regulators: + type: object + additionalProperties: false + + patternProperties: + "^ldo[1-7]$": + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + enable-gpios: + maxItems: 1 + + required: + - regulator-name + +required: + - compatible + - reg + - regulators + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/regulator/dlg,da9121-regulator.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@75 { + compatible = "dlg,slg51000"; + reg = <0x75>; + dlg,cs-gpios = <&tlmm 69 GPIO_ACTIVE_HIGH>; + vin5-supply = <&vreg_s1f_1p2>; + vin6-supply = <&vreg_s1f_1p2>; + + regulators { + ldo1 { + regulator-name = "slg51000_b_ldo1"; + regulator-min-microvolt = <2400000>; + regulator-max-microvolt = <3300000>; + }; + + ldo2 { + regulator-name = "slg51000_b_ldo2"; + regulator-min-microvolt = <2400000>; + regulator-max-microvolt = <3300000>; + }; + + ldo3 { + regulator-name = "slg51000_b_ldo3"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3750000>; + }; + + ldo4 { + regulator-name = "slg51000_b_ldo4"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3750000>; + }; + + ldo5 { + regulator-name = "slg51000_b_ldo5"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <1200000>; + }; + + ldo6 { + regulator-name = "slg51000_b_ldo6"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <1200000>; + }; + + ldo7 { + regulator-name = "slg51000_b_ldo7"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3750000>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml index ac0281b1cceb..ce7751b9129c 100644 --- a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml @@ -100,6 +100,11 @@ properties: vin-supply: description: Input supply phandle. + interrupts: + maxItems: 1 + description: + Interrupt signaling a critical under-voltage event. + required: - compatible - regulator-name diff --git a/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml b/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml index 05f72391185e..7394c0a339c5 100644 --- a/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml +++ b/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml @@ -43,6 +43,7 @@ properties: "^OUT[1-4]$": type: object $ref: regulator.yaml# + unevaluatedProperties: false additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/maxim,max77826.yaml b/Documentation/devicetree/bindings/regulator/maxim,max77826.yaml index 78c0b63243f7..6d6bbfbd26d4 100644 --- a/Documentation/devicetree/bindings/regulator/maxim,max77826.yaml +++ b/Documentation/devicetree/bindings/regulator/maxim,max77826.yaml @@ -30,10 +30,12 @@ properties: "^LDO([1-9]|1[0-5])$": type: object $ref: regulator.yaml# + unevaluatedProperties: false "^BUCK|BUCKBOOST$": type: object $ref: regulator.yaml# + unevaluatedProperties: false additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/mediatek,mt6358-regulator.yaml b/Documentation/devicetree/bindings/regulator/mediatek,mt6358-regulator.yaml new file mode 100644 index 000000000000..c50402fcba72 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/mediatek,mt6358-regulator.yaml @@ -0,0 +1,250 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/mediatek,mt6358-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek MT6358 Regulator + +maintainers: + - Zhiyong Tao <zhiyong.tao@mediatek.com> + +description: + Regulator node of the PMIC. This node should under the PMIC's device node. + All voltage regulators provided by the PMIC are described as sub-nodes of + this node. + +properties: + compatible: + oneOf: + - const: mediatek,mt6358-regulator + - items: + - const: mediatek,mt6366-regulator + - const: mediatek,mt6358-regulator + + vsys-ldo1-supply: + description: Supply for LDOs vfe28, vxo22, vcn28, vaux18, vaud28, vsim1, vusb, vbif28 + vsys-ldo2-supply: + description: Supply for LDOs vldo28 (MT6358 only), vio28, vmc, vmch, vsim2 + vsys-ldo3-supply: + description: Supply for LDOs vcn33, vcama[12] (MT6358 only), vemc, vibr + vsys-vcore-supply: + description: Supply for buck regulator vcore + vsys-vdram1-supply: + description: Supply for buck regulator vdram1 + vsys-vgpu-supply: + description: Supply for buck regulator vgpu + vsys-vmodem-supply: + description: Supply for buck regulator vmodem + vsys-vpa-supply: + description: Supply for buck regulator vpa + vsys-vproc11-supply: + description: Supply for buck regulator vproc11 + vsys-vproc12-supply: + description: Supply for buck regulator vproc12 + vsys-vs1-supply: + description: Supply for buck regulator vs1 + vsys-vs2-supply: + description: Supply for buck regulator vs2 + vs1-ldo1-supply: + description: + Supply for LDOs vrf18, vefuse, vcn18, vcamio (MT6358 only), vio18, vm18 (MT6366 only) + vs2-ldo1-supply: + description: Supply for LDOs vdram2, vmddr (MT6366 only) + vs2-ldo2-supply: + description: Supply for LDOs vrf12, va12 + vs2-ldo3-supply: + description: + Supply for LDOs vsram-core (MT6366 only), vsram-gpu, vsram-others, vsram-proc11, vsram-proc12 + vs2-ldo4-supply: + description: Supply for LDO vcamd + +patternProperties: + "^(buck_)?v(core|dram1|gpu|modem|pa|proc1[12]|s[12])$": + description: Buck regulators + type: object + $ref: regulator.yaml# + properties: + regulator-allowed-modes: + description: | + Buck regulatpr operating modes allowed. Valid values below. + Users should use the macros from dt-bindings/regulator/mediatek,mt6397-regulator.h + 0 (MT6397_BUCK_MODE_AUTO): Auto PFM/PWM mode + 1 (MT6397_BUCK_MODE_FORCE_PWM): Forced PWM mode + items: + enum: [0, 1] + unevaluatedProperties: false + + "^(ldo_)?v(a|rf)12$": + description: LDOs with fixed 1.2V output and 0~100/10mV tuning + type: object + $ref: regulator.yaml# + properties: + regulator-allowed-modes: false + unevaluatedProperties: false + + "^(ldo_)?v((aux|cn|io|rf)18|camio)$": + description: + LDOs with fixed 1.8V output and 0~100/10mV tuning (vcn18 on MT6366 has variable output) + type: object + $ref: regulator.yaml# + properties: + regulator-allowed-modes: false + unevaluatedProperties: false + + "^(ldo_)?vxo22$": + description: LDOs with fixed 2.2V output and 0~100/10mV tuning + type: object + $ref: regulator.yaml# + properties: + regulator-allowed-modes: false + unevaluatedProperties: false + + "^(ldo_)?v(aud|bif|cn|fe|io)28$": + description: LDOs with fixed 2.8V output and 0~100/10mV tuning + type: object + $ref: regulator.yaml# + properties: + regulator-allowed-modes: false + unevaluatedProperties: false + + "^(ldo_)?vusb$": + description: LDOs with fixed 3.0V output and 0~100/10mV tuning + type: object + $ref: regulator.yaml# + properties: + regulator-allowed-modes: false + unevaluatedProperties: false + + "^(ldo_)?vsram[_-](core|gpu|others|proc1[12])$": + description: LDOs with variable output + type: object + $ref: regulator.yaml# + properties: + regulator-allowed-modes: false + unevaluatedProperties: false + + "^(ldo_)?v(cama[12]|camd|cn33|dram2|efuse|emc|ibr|ldo28|m18|mc|mch|mddr|sim[12])$": + description: LDOs with variable output and 0~100/10mV tuning + type: object + $ref: regulator.yaml# + properties: + regulator-allowed-modes: false + unevaluatedProperties: false + +required: + - compatible + +additionalProperties: false + +allOf: + - if: + properties: + compatible: + const: mediatek,mt6358-regulator + then: + patternProperties: + # Old regulator node name scheme (with prefix and underscores) only + # ([^y-] is used to avoid matching -supply + "^(?<!buck_)(?<!ldo_)v.*[^y-](?!-supply)$": false + "^ldo_vsram-": false + # vsram_core regulator doesn't exist on MT6358 + "^ldo_vsram[-_]core$": false + + properties: + # vm18 and vmddr regulators don't exist on MT6358 + ldo_vm18: false + ldo_vmddr: false + + - if: + properties: + compatible: + contains: + const: mediatek,mt6366-regulator + then: + patternProperties: + # Prefer cleaned up regulator node names + "^(buck|ldo)_": false + # Don't allow underscores + "^vsram_": false + # vcam* regulators don't exist on MT6366 + "^vcam": false + + properties: + # vldo28 regulator doesn't exist on MT6366 + vldo28: false + # vs2_ldo4 supply pin doesn't exist on MT6366 + vs2-ldo4-supply: false + +examples: + - | + #include <dt-bindings/regulator/mediatek,mt6397-regulator.h> + + regulator { + compatible = "mediatek,mt6358-regulator"; + + buck_vgpu { + regulator-name = "vgpu"; + regulator-min-microvolt = <625000>; + regulator-max-microvolt = <900000>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <200>; + regulator-allowed-modes = <MT6397_BUCK_MODE_AUTO + MT6397_BUCK_MODE_FORCE_PWM>; + }; + + ldo_vsram_gpu { + regulator-name = "vsram_gpu"; + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <1000000>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <240>; + }; + }; + + - | + #include <dt-bindings/regulator/mediatek,mt6397-regulator.h> + + regulator { + compatible = "mediatek,mt6366-regulator", "mediatek,mt6358-regulator"; + + vdram1 { + regulator-name = "pp1125_emi_vdd2"; + regulator-min-microvolt = <1125000>; + regulator-max-microvolt = <1125000>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <0>; + regulator-allowed-modes = <MT6397_BUCK_MODE_AUTO + MT6397_BUCK_MODE_FORCE_PWM>; + regulator-always-on; + }; + + vproc11 { + regulator-name = "ppvar_dvdd_proc_bc_mt6366"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <1200000>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <200>; + regulator-allowed-modes = <MT6397_BUCK_MODE_AUTO + MT6397_BUCK_MODE_FORCE_PWM>; + regulator-always-on; + }; + + vmddr { + regulator-name = "pm0750_emi_vmddr"; + regulator-min-microvolt = <700000>; + regulator-max-microvolt = <750000>; + regulator-enable-ramp-delay = <325>; + regulator-always-on; + }; + + vsram-proc11 { + regulator-name = "pp0900_dvdd_sram_bc"; + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <1120000>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <240>; + regulator-always-on; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/mps,mp5416.yaml b/Documentation/devicetree/bindings/regulator/mps,mp5416.yaml index 2e720d152890..0221397eb51e 100644 --- a/Documentation/devicetree/bindings/regulator/mps,mp5416.yaml +++ b/Documentation/devicetree/bindings/regulator/mps,mp5416.yaml @@ -29,10 +29,12 @@ properties: patternProperties: "^buck[1-4]$": $ref: regulator.yaml# + unevaluatedProperties: false type: object "^ldo[1-4]$": $ref: regulator.yaml# + unevaluatedProperties: false type: object additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/mps,mpq2286.yaml b/Documentation/devicetree/bindings/regulator/mps,mpq2286.yaml new file mode 100644 index 000000000000..1296f9b30862 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/mps,mpq2286.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/mps,mpq2286.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Monolithic Power System MPQ2286 PMIC + +maintainers: + - Saravanan Sekar <saravanan@linumiz.com> + +properties: + compatible: + enum: + - mps,mpq2286 + + reg: + maxItems: 1 + + regulators: + type: object + + properties: + buck: + type: object + $ref: regulator.yaml# + + unevaluatedProperties: false + + additionalProperties: false + +required: + - compatible + - reg + - regulators + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@3 { + compatible = "mps,mpq2286"; + reg = <0x3>; + + regulators { + buck { + regulator-name = "buck"; + regulator-min-microvolt = <1600000>; + regulator-max-microvolt = <1800000>; + regulator-boot-on; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/mps,mpq7920.yaml b/Documentation/devicetree/bindings/regulator/mps,mpq7920.yaml index f3fcfc8be72f..6de5b027f990 100644 --- a/Documentation/devicetree/bindings/regulator/mps,mpq7920.yaml +++ b/Documentation/devicetree/bindings/regulator/mps,mpq7920.yaml @@ -21,7 +21,6 @@ properties: regulators: type: object - $ref: regulator.yaml# description: | list of regulators provided by this controller, must be named @@ -39,11 +38,13 @@ properties: ldortc: type: object $ref: regulator.yaml# + unevaluatedProperties: false patternProperties: "^ldo[1-4]$": type: object $ref: regulator.yaml# + unevaluatedProperties: false "^buck[1-4]$": type: object diff --git a/Documentation/devicetree/bindings/regulator/mt6358-regulator.txt b/Documentation/devicetree/bindings/regulator/mt6358-regulator.txt deleted file mode 100644 index b6384306db5c..000000000000 --- a/Documentation/devicetree/bindings/regulator/mt6358-regulator.txt +++ /dev/null @@ -1,350 +0,0 @@ -MediaTek MT6358 Regulator - -All voltage regulators provided by the MT6358 PMIC are described as the -subnodes of the MT6358 regulators node. Each regulator is named according -to its regulator type, buck_<name> and ldo_<name>. The definition for each -of these nodes is defined using the standard binding for regulators at -Documentation/devicetree/bindings/regulator/regulator.txt. - -The valid names for regulators are:: -BUCK: - buck_vdram1, buck_vcore, buck_vpa, buck_vproc11, buck_vproc12, buck_vgpu, - buck_vs2, buck_vmodem, buck_vs1 -LDO: - ldo_vdram2, ldo_vsim1, ldo_vibr, ldo_vrf12, ldo_vio18, ldo_vusb, ldo_vcamio, - ldo_vcamd, ldo_vcn18, ldo_vfe28, ldo_vsram_proc11, ldo_vcn28, ldo_vsram_others, - ldo_vsram_gpu, ldo_vxo22, ldo_vefuse, ldo_vaux18, ldo_vmch, ldo_vbif28, - ldo_vsram_proc12, ldo_vcama1, ldo_vemc, ldo_vio28, ldo_va12, ldo_vrf18, - ldo_vcn33, ldo_vcama2, ldo_vmc, ldo_vldo28, ldo_vaud28, ldo_vsim2 - -Example: - - pmic { - compatible = "mediatek,mt6358"; - - mt6358regulator: mt6358regulator { - compatible = "mediatek,mt6358-regulator"; - - mt6358_vdram1_reg: buck_vdram1 { - regulator-compatible = "buck_vdram1"; - regulator-name = "vdram1"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <2087500>; - regulator-ramp-delay = <12500>; - regulator-enable-ramp-delay = <0>; - regulator-always-on; - }; - - mt6358_vcore_reg: buck_vcore { - regulator-name = "vcore"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <200>; - regulator-always-on; - }; - - mt6358_vpa_reg: buck_vpa { - regulator-name = "vpa"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <3650000>; - regulator-ramp-delay = <50000>; - regulator-enable-ramp-delay = <250>; - }; - - mt6358_vproc11_reg: buck_vproc11 { - regulator-name = "vproc11"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <200>; - regulator-always-on; - }; - - mt6358_vproc12_reg: buck_vproc12 { - regulator-name = "vproc12"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <200>; - regulator-always-on; - }; - - mt6358_vgpu_reg: buck_vgpu { - regulator-name = "vgpu"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <200>; - }; - - mt6358_vs2_reg: buck_vs2 { - regulator-name = "vs2"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <2087500>; - regulator-ramp-delay = <12500>; - regulator-enable-ramp-delay = <0>; - regulator-always-on; - }; - - mt6358_vmodem_reg: buck_vmodem { - regulator-name = "vmodem"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <900>; - regulator-always-on; - }; - - mt6358_vs1_reg: buck_vs1 { - regulator-name = "vs1"; - regulator-min-microvolt = <1000000>; - regulator-max-microvolt = <2587500>; - regulator-ramp-delay = <12500>; - regulator-enable-ramp-delay = <0>; - regulator-always-on; - }; - - mt6358_vdram2_reg: ldo_vdram2 { - regulator-name = "vdram2"; - regulator-min-microvolt = <600000>; - regulator-max-microvolt = <1800000>; - regulator-enable-ramp-delay = <3300>; - }; - - mt6358_vsim1_reg: ldo_vsim1 { - regulator-name = "vsim1"; - regulator-min-microvolt = <1700000>; - regulator-max-microvolt = <3100000>; - regulator-enable-ramp-delay = <540>; - }; - - mt6358_vibr_reg: ldo_vibr { - regulator-name = "vibr"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3300000>; - regulator-enable-ramp-delay = <60>; - }; - - mt6358_vrf12_reg: ldo_vrf12 { - compatible = "regulator-fixed"; - regulator-name = "vrf12"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <1200000>; - regulator-enable-ramp-delay = <120>; - }; - - mt6358_vio18_reg: ldo_vio18 { - compatible = "regulator-fixed"; - regulator-name = "vio18"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - regulator-enable-ramp-delay = <2700>; - regulator-always-on; - }; - - mt6358_vusb_reg: ldo_vusb { - regulator-name = "vusb"; - regulator-min-microvolt = <3000000>; - regulator-max-microvolt = <3100000>; - regulator-enable-ramp-delay = <270>; - regulator-always-on; - }; - - mt6358_vcamio_reg: ldo_vcamio { - compatible = "regulator-fixed"; - regulator-name = "vcamio"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vcamd_reg: ldo_vcamd { - regulator-name = "vcamd"; - regulator-min-microvolt = <900000>; - regulator-max-microvolt = <1800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vcn18_reg: ldo_vcn18 { - compatible = "regulator-fixed"; - regulator-name = "vcn18"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vfe28_reg: ldo_vfe28 { - compatible = "regulator-fixed"; - regulator-name = "vfe28"; - regulator-min-microvolt = <2800000>; - regulator-max-microvolt = <2800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vsram_proc11_reg: ldo_vsram_proc11 { - regulator-name = "vsram_proc11"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <240>; - regulator-always-on; - }; - - mt6358_vcn28_reg: ldo_vcn28 { - compatible = "regulator-fixed"; - regulator-name = "vcn28"; - regulator-min-microvolt = <2800000>; - regulator-max-microvolt = <2800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vsram_others_reg: ldo_vsram_others { - regulator-name = "vsram_others"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <240>; - regulator-always-on; - }; - - mt6358_vsram_gpu_reg: ldo_vsram_gpu { - regulator-name = "vsram_gpu"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <240>; - }; - - mt6358_vxo22_reg: ldo_vxo22 { - compatible = "regulator-fixed"; - regulator-name = "vxo22"; - regulator-min-microvolt = <2200000>; - regulator-max-microvolt = <2200000>; - regulator-enable-ramp-delay = <120>; - regulator-always-on; - }; - - mt6358_vefuse_reg: ldo_vefuse { - regulator-name = "vefuse"; - regulator-min-microvolt = <1700000>; - regulator-max-microvolt = <1900000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vaux18_reg: ldo_vaux18 { - compatible = "regulator-fixed"; - regulator-name = "vaux18"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vmch_reg: ldo_vmch { - regulator-name = "vmch"; - regulator-min-microvolt = <2900000>; - regulator-max-microvolt = <3300000>; - regulator-enable-ramp-delay = <60>; - }; - - mt6358_vbif28_reg: ldo_vbif28 { - compatible = "regulator-fixed"; - regulator-name = "vbif28"; - regulator-min-microvolt = <2800000>; - regulator-max-microvolt = <2800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vsram_proc12_reg: ldo_vsram_proc12 { - regulator-name = "vsram_proc12"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <240>; - regulator-always-on; - }; - - mt6358_vcama1_reg: ldo_vcama1 { - regulator-name = "vcama1"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <3000000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vemc_reg: ldo_vemc { - regulator-name = "vemc"; - regulator-min-microvolt = <2900000>; - regulator-max-microvolt = <3300000>; - regulator-enable-ramp-delay = <60>; - regulator-always-on; - }; - - mt6358_vio28_reg: ldo_vio28 { - compatible = "regulator-fixed"; - regulator-name = "vio28"; - regulator-min-microvolt = <2800000>; - regulator-max-microvolt = <2800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_va12_reg: ldo_va12 { - compatible = "regulator-fixed"; - regulator-name = "va12"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <1200000>; - regulator-enable-ramp-delay = <270>; - regulator-always-on; - }; - - mt6358_vrf18_reg: ldo_vrf18 { - compatible = "regulator-fixed"; - regulator-name = "vrf18"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - regulator-enable-ramp-delay = <120>; - }; - - mt6358_vcn33_reg: ldo_vcn33 { - regulator-name = "vcn33"; - regulator-min-microvolt = <3300000>; - regulator-max-microvolt = <3500000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vcama2_reg: ldo_vcama2 { - regulator-name = "vcama2"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <3000000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vmc_reg: ldo_vmc { - regulator-name = "vmc"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <3300000>; - regulator-enable-ramp-delay = <60>; - }; - - mt6358_vldo28_reg: ldo_vldo28 { - regulator-name = "vldo28"; - regulator-min-microvolt = <2800000>; - regulator-max-microvolt = <3000000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vaud28_reg: ldo_vaud28 { - compatible = "regulator-fixed"; - regulator-name = "vaud28"; - regulator-min-microvolt = <2800000>; - regulator-max-microvolt = <2800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vsim2_reg: ldo_vsim2 { - regulator-name = "vsim2"; - regulator-min-microvolt = <1700000>; - regulator-max-microvolt = <3100000>; - regulator-enable-ramp-delay = <540>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/regulator/onnn,fan53880.yaml b/Documentation/devicetree/bindings/regulator/onnn,fan53880.yaml index eb61e04ef852..b5181719daa1 100644 --- a/Documentation/devicetree/bindings/regulator/onnn,fan53880.yaml +++ b/Documentation/devicetree/bindings/regulator/onnn,fan53880.yaml @@ -48,10 +48,12 @@ properties: "^LDO[1-4]$": type: object $ref: regulator.yaml# + unevaluatedProperties: false "^BUCK|BOOST$": type: object $ref: regulator.yaml# + unevaluatedProperties: false additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/pfuze100.yaml b/Documentation/devicetree/bindings/regulator/pfuze100.yaml index e384e4953f0a..0eda44752cdd 100644 --- a/Documentation/devicetree/bindings/regulator/pfuze100.yaml +++ b/Documentation/devicetree/bindings/regulator/pfuze100.yaml @@ -68,18 +68,22 @@ properties: "^sw([1-4]|[1-4][a-c]|[1-4][a-c][a-c])$": $ref: regulator.yaml# type: object + unevaluatedProperties: false "^vgen[1-6]$": $ref: regulator.yaml# type: object + unevaluatedProperties: false "^vldo[1-4]$": $ref: regulator.yaml# type: object + unevaluatedProperties: false "^(vsnvs|vref|vrefddr|swbst|coin|v33|vccsd)$": $ref: regulator.yaml# type: object + unevaluatedProperties: false additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/qcom,rpm-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,rpm-regulator.yaml index 8a08698e3484..b4eb4001eb3d 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,rpm-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,rpm-regulator.yaml @@ -49,7 +49,7 @@ patternProperties: ".*-supply$": description: Input supply phandle(s) for this node - "^((s|l|lvs)[0-9]*)|(s[1-2][a-b])|(ncp)|(mvs)|(usb-switch)|(hdmi-switch)$": + "^((s|l|lvs)[0-9]*|s[1-2][a-b]|ncp|mvs|usb-switch|hdmi-switch)$": description: List of regulators and its properties $ref: regulator.yaml# unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml index b9498504ad79..acd37f28ef53 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml @@ -50,9 +50,11 @@ description: | For PM8550, smps1 - smps6, ldo1 - ldo17, bob1 - bob2 For PM8998, smps1 - smps13, ldo1 - ldo28, lvs1 - lvs2 For PMI8998, bob + For PMC8380, smps1 - smps8, ldo1 - lodo3 For PMR735A, smps1 - smps3, ldo1 - ldo7 For PMX55, smps1 - smps7, ldo1 - ldo16 For PMX65, smps1 - smps8, ldo1 - ldo21 + For PMX75, smps1 - smps10, ldo1 - ldo21 properties: compatible: @@ -77,6 +79,7 @@ properties: - qcom,pm8998-rpmh-regulators - qcom,pmc8180-rpmh-regulators - qcom,pmc8180c-rpmh-regulators + - qcom,pmc8380-rpmh-regulators - qcom,pmg1110-rpmh-regulators - qcom,pmi8998-rpmh-regulators - qcom,pmm8155au-rpmh-regulators @@ -84,13 +87,14 @@ properties: - qcom,pmr735a-rpmh-regulators - qcom,pmx55-rpmh-regulators - qcom,pmx65-rpmh-regulators + - qcom,pmx75-rpmh-regulators qcom,pmic-id: description: | RPMh resource name suffix used for the regulators found on this PMIC. $ref: /schemas/types.yaml#/definitions/string - enum: [a, b, c, d, e, f, g, h, k] + enum: [a, b, c, d, e, f, g, h, i, j, k, l, m, n] qcom,always-wait-for-ack: description: | @@ -109,6 +113,7 @@ properties: bob: type: object $ref: regulator.yaml# + unevaluatedProperties: false description: BOB regulator node. dependencies: regulator-allow-set-load: [ regulator-allowed-modes ] @@ -117,6 +122,7 @@ patternProperties: "^(smps|ldo|lvs|bob)[0-9]+$": type: object $ref: regulator.yaml# + unevaluatedProperties: false description: smps/ldo regulator nodes(s). dependencies: regulator-allow-set-load: [ regulator-allowed-modes ] @@ -364,6 +370,16 @@ allOf: properties: compatible: enum: + - qcom,pmc8380-rpmh-regulators + then: + patternProperties: + "^vdd-l[1-3]-supply$": true + "^vdd-s[1-8]-supply$": true + + - if: + properties: + compatible: + enum: - qcom,pmg1110-rpmh-regulators then: properties: @@ -424,10 +440,28 @@ allOf: vdd-l11-l13-supply: true patternProperties: "^vdd-l[1347]-supply$": true - "^vdd-l1[0245789]-supply$": true + "^vdd-l1[024579]-supply$": true "^vdd-l2[01]-supply$": true "^vdd-s[1-8]-supply$": true + - if: + properties: + compatible: + enum: + - qcom,pmx75-rpmh-regulators + then: + properties: + vdd-l2-l18-supply: true + vdd-l4-l16-supply: true + vdd-l5-l6-supply: true + vdd-l8-l9-supply: true + vdd-l11-l13-supply: true + vdd-l20-l21-supply: true + patternProperties: + "^vdd-l[137]-supply$": true + "^vdd-l1[024579]-supply$": true + "^vdd-s([1-9]|10)-supply$": true + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/regulator/qcom,sdm845-refgen-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,sdm845-refgen-regulator.yaml new file mode 100644 index 000000000000..f02f97d4fdd2 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/qcom,sdm845-refgen-regulator.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/qcom,sdm845-refgen-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. REFGEN Regulator + +maintainers: + - Konrad Dybcio <konradybcio@kernel.org> + +description: + The REFGEN (reference voltage generator) regulator provides reference + voltage for on-chip IPs (like PHYs) on some Qualcomm SoCs. + +allOf: + - $ref: regulator.yaml# + +properties: + compatible: + oneOf: + - items: + - enum: + - qcom,sc7180-refgen-regulator + - qcom,sc8180x-refgen-regulator + - qcom,sm8150-refgen-regulator + - const: qcom,sdm845-refgen-regulator + + - items: + - enum: + - qcom,sc7280-refgen-regulator + - qcom,sc8280xp-refgen-regulator + - qcom,sm6350-refgen-regulator + - qcom,sm6375-refgen-regulator + - qcom,sm8350-refgen-regulator + - const: qcom,sm8250-refgen-regulator + + - enum: + - qcom,sdm845-refgen-regulator + - qcom,sm8250-refgen-regulator + + reg: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + regulator@162f000 { + compatible = "qcom,sm8250-refgen-regulator"; + reg = <0x0162f000 0x84>; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml index a8ca8e0b27f8..9ea8ac0786ac 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml @@ -110,6 +110,7 @@ patternProperties: "^((s|l|lvs|5vs)[0-9]*)|(boost-bypass)|(bob)$": description: List of regulators and its properties $ref: regulator.yaml# + unevaluatedProperties: false additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml index bdf34c2de96b..7a1b7d2abbd4 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml @@ -17,12 +17,15 @@ properties: - qcom,pm660l-regulators - qcom,pm8004-regulators - qcom,pm8005-regulators + - qcom,pm8019-regulators - qcom,pm8226-regulators - qcom,pm8841-regulators + - qcom,pm8909-regulators - qcom,pm8916-regulators - qcom,pm8941-regulators - qcom,pm8950-regulators - qcom,pm8994-regulators + - qcom,pma8084-regulators - qcom,pmi8994-regulators - qcom,pmp8074-regulators - qcom,pms405-regulators @@ -32,7 +35,7 @@ properties: $ref: /schemas/types.yaml#/definitions/phandle patternProperties: - "^(5vs[1-2]|(l|s)[1-9][0-9]?|lvs[1-3])$": + "^(5vs[1-2]|(l|s)[1-9][0-9]?|lvs[1-4])$": description: List of regulators and its properties type: object $ref: regulator.yaml# @@ -181,6 +184,25 @@ allOf: compatible: contains: enum: + - qcom,pm8019-regulators + then: + properties: + vdd_l1-supply: true + vdd_l2_l3-supply: true + vdd_l4_l5_l6-supply: true + vdd_l7_l8_l11-supply: true + vdd_l9-supply: true + vdd_l10-supply: true + vdd_l12-supply: true + vdd_l13_l14-supply: true + patternProperties: + "^vdd_s[1-4]-supply$": true + + - if: + properties: + compatible: + contains: + enum: - qcom,pm8226-regulators then: properties: @@ -211,6 +233,24 @@ allOf: compatible: contains: enum: + - qcom,pm8909-regulators + then: + properties: + vdd_s1-supply: true + vdd_s2-supply: true + vdd_l1-supply: true + vdd_l2_l5-supply: true + vdd_l3_l6_l10-supply: true + vdd_l4_l7-supply: true + vdd_l8_l11_l15_l18-supply: true + vdd_l9_l12_l14_l17-supply: true + vdd_l13-supply: true + + - if: + properties: + compatible: + contains: + enum: - qcom,pm8916-regulators then: properties: @@ -300,6 +340,32 @@ allOf: compatible: contains: enum: + - qcom,pma8084-regulators + then: + properties: + vdd_l1_l11-supply: true + vdd_l2_l3_l4_l27-supply: true + vdd_l5_l7-supply: true + vdd_l6_l12_l14_l15_l26-supply: true + vdd_l8-supply: true + vdd_l9_l10_l13_l20_l23_l24-supply: true + vdd_l16_l25-supply: true + vdd_l17-supply: true + vdd_l18-supply: true + vdd_l19-supply: true + vdd_l21-supply: true + vdd_l22-supply: true + vdd_lvs1_2-supply: true + vdd_lvs3_4-supply: true + vdd_5vs1-supply: true + patternProperties: + "^vdd_s([1-9]|1[0-2])-supply$": true + + - if: + properties: + compatible: + contains: + enum: - qcom,pmi8994-regulators then: properties: diff --git a/Documentation/devicetree/bindings/regulator/regulator-max77620.txt b/Documentation/devicetree/bindings/regulator/regulator-max77620.txt index 1c4bfe786736..bcf788897e44 100644 --- a/Documentation/devicetree/bindings/regulator/regulator-max77620.txt +++ b/Documentation/devicetree/bindings/regulator/regulator-max77620.txt @@ -35,7 +35,7 @@ information for that regulator. The definition for each of these nodes is defined using the standard binding for regulators found at <Documentation/devicetree/bindings/regulator/regulator.txt>. -Theres are also additional properties for SD/LDOs. These additional properties +There are also additional properties for SD/LDOs. These additional properties are required to configure FPS configuration parameters for SDs and LDOs. Please refer <devicetree/bindings/mfd/max77620.txt> for more detail of Flexible Power Sequence (FPS). diff --git a/Documentation/devicetree/bindings/regulator/regulator.yaml b/Documentation/devicetree/bindings/regulator/regulator.yaml index e158c2d3d3f9..9daf0fc2465f 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/regulator.yaml @@ -126,7 +126,7 @@ properties: regulator-oc-error-microamp: description: Set over current error limit. This is a limit where part of - the hardware propably is malfunctional and damage prevention is requested. + the hardware probably is malfunctional and damage prevention is requested. Zero can be passed to disable error detection and value '1' indicates that detection should be enabled but limit setting can be omitted. @@ -146,7 +146,7 @@ properties: regulator-ov-error-microvolt: description: Set over voltage error limit. This is a limit where part of - the hardware propably is malfunctional and damage prevention is requested + the hardware probably is malfunctional and damage prevention is requested Zero can be passed to disable error detection and value '1' indicates that detection should be enabled but limit setting can be omitted. Limit is given as microvolt offset from voltage set to regulator. @@ -168,7 +168,7 @@ properties: regulator-uv-error-microvolt: description: Set under voltage error limit. This is a limit where part of - the hardware propably is malfunctional and damage prevention is requested + the hardware probably is malfunctional and damage prevention is requested Zero can be passed to disable error detection and value '1' indicates that detection should be enabled but limit setting can be omitted. Limit is given as microvolt offset from voltage set to regulator. @@ -189,7 +189,7 @@ properties: regulator-temp-error-kelvin: description: Set over temperature error limit. This is a limit where part of - the hardware propably is malfunctional and damage prevention is requested + the hardware probably is malfunctional and damage prevention is requested Zero can be passed to disable error detection and value '1' indicates that detection should be enabled but limit setting can be omitted. diff --git a/Documentation/devicetree/bindings/regulator/richtek,rt4831-regulator.yaml b/Documentation/devicetree/bindings/regulator/richtek,rt4831-regulator.yaml index d9c23333e157..cd06e957b9db 100644 --- a/Documentation/devicetree/bindings/regulator/richtek,rt4831-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/richtek,rt4831-regulator.yaml @@ -29,6 +29,7 @@ patternProperties: "^DSV(LCM|P|N)$": type: object $ref: regulator.yaml# + unevaluatedProperties: false description: Properties for single Display Bias Voltage regulator. diff --git a/Documentation/devicetree/bindings/regulator/richtek,rt5190a-regulator.yaml b/Documentation/devicetree/bindings/regulator/richtek,rt5190a-regulator.yaml index edb411be0390..89341fdaa3af 100644 --- a/Documentation/devicetree/bindings/regulator/richtek,rt5190a-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/richtek,rt5190a-regulator.yaml @@ -11,7 +11,7 @@ maintainers: description: | The RT5190A integrates 1 channel buck controller, 3 channels high efficiency - synchronous buck converters, 1 LDO, I2C control interface and peripherial + synchronous buck converters, 1 LDO, I2C control interface and peripheral logical control. It also supports mute AC OFF depop sound and quick setting storage while diff --git a/Documentation/devicetree/bindings/regulator/richtek,rt5739.yaml b/Documentation/devicetree/bindings/regulator/richtek,rt5739.yaml index 358297dd3fb7..e95e046e9ed6 100644 --- a/Documentation/devicetree/bindings/regulator/richtek,rt5739.yaml +++ b/Documentation/devicetree/bindings/regulator/richtek,rt5739.yaml @@ -21,6 +21,7 @@ allOf: properties: compatible: enum: + - richtek,rt5733 - richtek,rt5739 reg: diff --git a/Documentation/devicetree/bindings/regulator/richtek,rtmv20-regulator.yaml b/Documentation/devicetree/bindings/regulator/richtek,rtmv20-regulator.yaml index 446ec5127d1f..fec3d396ca50 100644 --- a/Documentation/devicetree/bindings/regulator/richtek,rtmv20-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/richtek,rtmv20-regulator.yaml @@ -121,6 +121,7 @@ properties: description: load switch current regulator description. type: object $ref: regulator.yaml# + unevaluatedProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/regulator/richtek,rtq2208.yaml b/Documentation/devicetree/bindings/regulator/richtek,rtq2208.yaml new file mode 100644 index 000000000000..609c06615bdc --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/richtek,rtq2208.yaml @@ -0,0 +1,197 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/richtek,rtq2208.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Richtek RTQ2208 SubPMIC Regulator + +maintainers: + - Alina Yu <alina_yu@richtek.com> + +description: | + RTQ2208 is a highly integrated power converter that offers functional safety dual + multi-configurable synchronous buck converters and two LDOs. + + Bucks support "regulator-allowed-modes" and "regulator-mode". The former defines the permitted + switching operation in normal mode; the latter defines the operation in suspend to RAM mode. + + No matter the RTQ2208 is configured to normal or suspend to RAM mode, there are two switching + operation modes for all buck rails, automatic power saving mode (Auto mode) and forced continuous + conduction mode (FCCM). + + The definition of modes is in the datasheet which is available in below link + and their meaning is:: + 0 - Auto mode for power saving, which reducing the switching frequency at light load condition + to maintain high frequency. + 1 - FCCM to meet the strict voltage regulation accuracy, which keeping constant switching frequency. + + Datasheet will be available soon at + https://www.richtek.com/assets/Products + +properties: + compatible: + enum: + - richtek,rtq2208 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + richtek,mtp-sel-high: + type: boolean + description: + vout register selection based on this boolean value. + false - Using DVS0 register setting to adjust vout + true - Using DVS1 register setting to adjust vout + + regulators: + type: object + additionalProperties: false + + patternProperties: + "^buck-[a-h]$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: + description for buck-[a-h] regulator. + + properties: + regulator-allowed-modes: + description: + two buck modes in different switching accuracy. + 0 - Auto mode + 1 - FCCM + items: + enum: [0, 1] + + "^ldo[1-2]$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: + regulator description for ldo[1-2]. + +required: + - compatible + - reg + - regulators + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@10 { + compatible = "richtek,rtq2208"; + reg = <0x10>; + interrupts-extended = <&gpio26 0 IRQ_TYPE_LEVEL_LOW>; + richtek,mtp-sel-high; + + regulators { + buck-a { + regulator-min-microvolt = <400000>; + regulator-max-microvolt = <2050000>; + regulator-allowed-modes = <0 1>; + regulator-always-on; + regulator-state-mem { + regulator-on-in-suspend; + regulator-mode = <1>; + }; + }; + buck-b { + regulator-min-microvolt = <400000>; + regulator-max-microvolt = <2050000>; + regulator-allowed-modes = <0 1>; + regulator-always-on; + regulator-state-mem { + regulator-on-in-suspend; + regulator-mode = <1>; + }; + }; + buck-c { + regulator-min-microvolt = <400000>; + regulator-max-microvolt = <2050000>; + regulator-allowed-modes = <0 1>; + regulator-always-on; + regulator-state-mem { + regulator-on-in-suspend; + regulator-mode = <1>; + }; + }; + buck-d { + regulator-min-microvolt = <400000>; + regulator-max-microvolt = <2050000>; + regulator-allowed-modes = <0 1>; + regulator-always-on; + regulator-state-mem { + regulator-on-in-suspend; + regulator-mode = <1>; + }; + }; + buck-e { + regulator-min-microvolt = <400000>; + regulator-max-microvolt = <2050000>; + regulator-allowed-modes = <0 1>; + regulator-always-on; + regulator-state-mem { + regulator-on-in-suspend; + regulator-mode = <1>; + }; + }; + buck-f { + regulator-min-microvolt = <400000>; + regulator-max-microvolt = <2050000>; + regulator-allowed-modes = <0 1>; + regulator-always-on; + regulator-state-mem { + regulator-on-in-suspend; + regulator-mode = <1>; + }; + }; + buck-g { + regulator-min-microvolt = <400000>; + regulator-max-microvolt = <2050000>; + regulator-allowed-modes = <0 1>; + regulator-always-on; + regulator-state-mem { + regulator-on-in-suspend; + regulator-mode = <1>; + }; + }; + buck-h { + regulator-min-microvolt = <400000>; + regulator-max-microvolt = <2050000>; + regulator-allowed-modes = <0 1>; + regulator-always-on; + regulator-state-mem { + regulator-on-in-suspend; + regulator-mode = <1>; + }; + }; + ldo1 { + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-always-on; + regulator-state-mem { + regulator-on-in-suspend; + }; + }; + ldo2 { + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + regulator-state-mem { + regulator-on-in-suspend; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/richtek,rtq6752-regulator.yaml b/Documentation/devicetree/bindings/regulator/richtek,rtq6752-regulator.yaml index e6e5a9a7d940..ef62c618de67 100644 --- a/Documentation/devicetree/bindings/regulator/richtek,rtq6752-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/richtek,rtq6752-regulator.yaml @@ -35,6 +35,7 @@ properties: "^(p|n)avdd$": type: object $ref: regulator.yaml# + unevaluatedProperties: false description: | regulator description for pavdd and navdd. diff --git a/Documentation/devicetree/bindings/regulator/slg51000.txt b/Documentation/devicetree/bindings/regulator/slg51000.txt deleted file mode 100644 index aa0733e49b90..000000000000 --- a/Documentation/devicetree/bindings/regulator/slg51000.txt +++ /dev/null @@ -1,88 +0,0 @@ -* Dialog Semiconductor SLG51000 Voltage Regulator - -Required properties: -- compatible : Should be "dlg,slg51000" for SLG51000 -- reg : Specifies the I2C slave address. -- xxx-supply: Input voltage supply regulator for ldo3 to ldo7. - These entries are required if regulators are enabled for a device. - An absence of these properties can cause the regulator registration to fail. - If some of input supply is powered through battery or always-on supply then - also it is required to have these parameters with proper node handle of always - on power supply. - vin3-supply: Input supply for ldo3 - vin4-supply: Input supply for ldo4 - vin5-supply: Input supply for ldo5 - vin6-supply: Input supply for ldo6 - vin7-supply: Input supply for ldo7 - -Optional properties: -- interrupt-parent : Specifies the reference to the interrupt controller. -- interrupts : IRQ line information. -- dlg,cs-gpios : Specify a valid GPIO for chip select - -Sub-nodes: -- regulators : This node defines the settings for the regulators. - The content of the sub-node is defined by the standard binding - for regulators; see regulator.txt. - - The SLG51000 regulators are bound using their names listed below: - ldo1 - ldo2 - ldo3 - ldo4 - ldo5 - ldo6 - ldo7 - -Optional properties for regulators: -- enable-gpios : Specify a valid GPIO for platform control of the regulator. - -Example: - pmic: slg51000@75 { - compatible = "dlg,slg51000"; - reg = <0x75>; - - regulators { - ldo1 { - regulator-name = "ldo1"; - regulator-min-microvolt = <2400000>; - regulator-max-microvolt = <3300000>; - }; - - ldo2 { - regulator-name = "ldo2"; - regulator-min-microvolt = <2400000>; - regulator-max-microvolt = <3300000>; - }; - - ldo3 { - regulator-name = "ldo3"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3750000>; - }; - - ldo4 { - regulator-name = "ldo4"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3750000>; - }; - - ldo5 { - regulator-name = "ldo5"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1200000>; - }; - - ldo6 { - regulator-name = "ldo6"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1200000>; - }; - - ldo7 { - regulator-name = "ldo7"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3750000>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/regulator/st,stm32mp1-pwr-reg.yaml b/Documentation/devicetree/bindings/regulator/st,stm32mp1-pwr-reg.yaml index 7d53cfa2c288..c9586d277f41 100644 --- a/Documentation/devicetree/bindings/regulator/st,stm32mp1-pwr-reg.yaml +++ b/Documentation/devicetree/bindings/regulator/st,stm32mp1-pwr-reg.yaml @@ -25,8 +25,8 @@ properties: patternProperties: "^(reg11|reg18|usb33)$": type: object - $ref: regulator.yaml# + unevaluatedProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/regulator/vctrl.txt b/Documentation/devicetree/bindings/regulator/vctrl.txt index 601328d7fdbb..e940377cfd69 100644 --- a/Documentation/devicetree/bindings/regulator/vctrl.txt +++ b/Documentation/devicetree/bindings/regulator/vctrl.txt @@ -21,7 +21,7 @@ Optional properties: margin from the expected value for a given control voltage. On larger voltage decreases this can occur undesiredly since the output voltage does not adjust - inmediately to changes in the control voltage. To + immediately to changes in the control voltage. To avoid this situation the vctrl driver breaks down larger voltage decreases into multiple steps, where each step is within the OVP threshold. diff --git a/Documentation/devicetree/bindings/regulator/wlf,arizona.yaml b/Documentation/devicetree/bindings/regulator/wlf,arizona.yaml index 011819c10988..11e378648b3f 100644 --- a/Documentation/devicetree/bindings/regulator/wlf,arizona.yaml +++ b/Documentation/devicetree/bindings/regulator/wlf,arizona.yaml @@ -29,11 +29,13 @@ properties: Initial data for the LDO1 regulator. $ref: regulator.yaml# type: object + unevaluatedProperties: false micvdd: description: Initial data for the MICVDD regulator. $ref: regulator.yaml# type: object + unevaluatedProperties: false additionalProperties: true diff --git a/Documentation/devicetree/bindings/remoteproc/fsl,imx-rproc.yaml b/Documentation/devicetree/bindings/remoteproc/fsl,imx-rproc.yaml index 0c3910f152d1..30632efdad8b 100644 --- a/Documentation/devicetree/bindings/remoteproc/fsl,imx-rproc.yaml +++ b/Documentation/devicetree/bindings/remoteproc/fsl,imx-rproc.yaml @@ -20,7 +20,9 @@ properties: - fsl,imx7ulp-cm4 - fsl,imx8mm-cm4 - fsl,imx8mn-cm7 + - fsl,imx8mn-cm7-mmio - fsl,imx8mp-cm7 + - fsl,imx8mp-cm7-mmio - fsl,imx8mq-cm4 - fsl,imx8qm-cm4 - fsl,imx8qxp-cm4 @@ -70,6 +72,11 @@ properties: description: Specify CPU entry address for SCU enabled processor. + fsl,iomuxc-gpr: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to IOMUXC GPR block which provide access to CM7 CPUWAIT bit. + fsl,resource-id: $ref: /schemas/types.yaml#/definitions/uint32 description: @@ -79,6 +86,19 @@ properties: required: - compatible +allOf: + - if: + properties: + compatible: + not: + contains: + enum: + - fsl,imx8mn-cm7-mmio + - fsl,imx8mp-cm7-mmio + then: + properties: + fsl,iomuxc-gpr: false + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml index 643ee787a81f..a2b0079de039 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml @@ -26,6 +26,7 @@ properties: - qcom,sdm660-adsp-pas - qcom,sdm845-adsp-pas - qcom,sdm845-cdsp-pas + - qcom,sdm845-slpi-pas reg: maxItems: 1 @@ -44,8 +45,13 @@ properties: maxItems: 1 description: Reference to the reserved-memory for the Hexagon core + firmware-name: + maxItems: 1 + description: Firmware name for the Hexagon core + required: - compatible + - memory-region unevaluatedProperties: false @@ -63,6 +69,7 @@ allOf: - qcom,msm8998-adsp-pas - qcom,sdm845-adsp-pas - qcom,sdm845-cdsp-pas + - qcom,sdm845-slpi-pas then: properties: clocks: @@ -104,6 +111,7 @@ allOf: - qcom,msm8998-slpi-pas - qcom,sdm845-adsp-pas - qcom,sdm845-cdsp-pas + - qcom,sdm845-slpi-pas then: properties: interrupts: @@ -160,6 +168,22 @@ allOf: - if: properties: compatible: + enum: + - qcom,sdm845-slpi-pas + then: + properties: + power-domains: + items: + - description: LCX power domain + - description: LMX power domain + power-domain-names: + items: + - const: lcx + - const: lmx + + - if: + properties: + compatible: contains: enum: - qcom,msm8226-adsp-pil diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,glink-edge.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,glink-edge.yaml index 7b43ad3daa56..e78a89c9ec41 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,glink-edge.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,glink-edge.yaml @@ -14,9 +14,6 @@ description: related to the remote processor. properties: - $nodename: - const: glink-edge - apr: $ref: /schemas/soc/qcom/qcom,apr.yaml# required: diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,glink-rpm-edge.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,glink-rpm-edge.yaml index f5a044e20c4e..884158bccd50 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,glink-rpm-edge.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,glink-rpm-edge.yaml @@ -84,7 +84,7 @@ examples: - | #include <dt-bindings/interrupt-controller/arm-gic.h> - rpm-glink { + glink-edge { compatible = "qcom,glink-rpm"; interrupts = <GIC_SPI 168 IRQ_TYPE_EDGE_RISING>; mboxes = <&apcs_glb 0>; diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,msm8996-mss-pil.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,msm8996-mss-pil.yaml index c1ac6ca1e759..0643faae2c39 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,msm8996-mss-pil.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,msm8996-mss-pil.yaml @@ -19,6 +19,7 @@ properties: enum: - qcom,msm8996-mss-pil - qcom,msm8998-mss-pil + - qcom,sdm660-mss-pil - qcom,sdm845-mss-pil reg: @@ -215,13 +216,12 @@ allOf: - description: GCC MSS IFACE clock - description: GCC MSS BUS clock - description: GCC MSS MEM clock - - description: RPMH XO clock + - description: RPM XO clock - description: GCC MSS GPLL0 clock - description: GCC MSS SNOC_AXI clock - description: GCC MSS MNOC_AXI clock - - description: RPMH PNOC clock - - description: GCC MSS PRNG clock - - description: RPMH QDSS clock + - description: RPM PNOC clock + - description: RPM QDSS clock clock-names: items: - const: iface @@ -245,7 +245,9 @@ allOf: - if: properties: compatible: - const: qcom,msm8998-mss-pil + enum: + - qcom,msm8998-mss-pil + - qcom,sdm660-mss-pil then: properties: clocks: diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,pas-common.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,pas-common.yaml index 171ef85de193..63a82e7a8bf8 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,pas-common.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,pas-common.yaml @@ -82,7 +82,6 @@ required: - clock-names - interrupts - interrupt-names - - memory-region - qcom,smem-states - qcom,smem-state-names diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,qcs404-pas.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,qcs404-pas.yaml index 5efa0e5c0439..eb868a7ff4cd 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,qcs404-pas.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,qcs404-pas.yaml @@ -42,7 +42,7 @@ properties: smd-edge: false memory-region: - minItems: 1 + maxItems: 1 description: Reference to the reserved-memory for the Hexagon core firmware-name: @@ -52,6 +52,7 @@ properties: required: - compatible - reg + - memory-region allOf: - $ref: /schemas/remoteproc/qcom,pas-common.yaml# diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,rpm-proc.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,rpm-proc.yaml new file mode 100644 index 000000000000..7afafde17a38 --- /dev/null +++ b/Documentation/devicetree/bindings/remoteproc/qcom,rpm-proc.yaml @@ -0,0 +1,171 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/remoteproc/qcom,rpm-proc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Resource Power Manager (RPM) Processor/Subsystem + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Konrad Dybcio <konrad.dybcio@linaro.org> + - Stephan Gerhold <stephan@gerhold.net> + +description: | + Resource Power Manager (RPM) subsystem found in various Qualcomm platforms: + + +--------------------------------------------+ + | RPM subsystem (qcom,rpm-proc) | + | | + reset | +---------------+ +-----+ +-----+ | + --------->| | | MPM | | CPR | ... | + IPC interrupts | | ARM Cortex-M3 |--- +-----+ +-----+ | + ----------------->| | | | | | + | +---------------+ |---------------------- | + | +---------------+ | | + | | Code RAM |--| +------------------+ | + | +---------------+ | | | | + | +---------------+ |--| Message RAM | | + | | Data RAM |--| | | | + | +---------------+ | +------------------+ | + +--------------------|-----------------------+ + v + NoC + + The firmware running on the processor inside the RPM subsystem allows each + component in the system to vote for state of the system resources, such as + clocks, regulators and bus frequencies. It implements multiple separate + communication interfaces that are described in subnodes, e.g. SMD and MPM: + + +------------------------------+ + | ARM Cortex-M3 | + | | +------------------------------+ + | +--------------------------+ | | Message RAM | + | | RPM firmware | | | | + IPC IRQ 0 | | +----------------------+ | | | +--------------------------+ | + -------------->| SMD server |<------->| SMD data structures | | + | | | +--------------+ | | | | | +--------------+ | | + | | | | rpm_requests | ... | | | | | | rpm_requests | ... | | + | | | +--------------+ | | | | | +--------------+ | | + IPC IRQ 1 | | +----------------------+ | | | +--------------------------+ | + -------------->| MPM virtualization |<--------| MPM register copy (vMPM) | | + | | +----------------------+ | | | +--------------------------+ | + | | ... | | | | ... | + | +--------------------|-----+ | +------------------------------+ + +----------------------|-------+ + v + +--------------+ + | MPM Hardware | + +--------------+ + + The services provided by the firmware are only available after the firmware + has been loaded and the processor has been released from reset. Usually this + happens early in the boot process before the operating system is started. + +properties: + compatible: + items: + - enum: + - qcom,apq8084-rpm-proc + - qcom,ipq6018-rpm-proc + - qcom,ipq9574-rpm-proc + - qcom,mdm9607-rpm-proc + - qcom,msm8226-rpm-proc + - qcom,msm8610-rpm-proc + - qcom,msm8909-rpm-proc + - qcom,msm8916-rpm-proc + - qcom,msm8917-rpm-proc + - qcom,msm8936-rpm-proc + - qcom,msm8937-rpm-proc + - qcom,msm8952-rpm-proc + - qcom,msm8953-rpm-proc + - qcom,msm8974-rpm-proc + - qcom,msm8976-rpm-proc + - qcom,msm8994-rpm-proc + - qcom,msm8996-rpm-proc + - qcom,msm8998-rpm-proc + - qcom,qcm2290-rpm-proc + - qcom,qcs404-rpm-proc + - qcom,sdm660-rpm-proc + - qcom,sm6115-rpm-proc + - qcom,sm6125-rpm-proc + - qcom,sm6375-rpm-proc + - const: qcom,rpm-proc + + smd-edge: + $ref: /schemas/remoteproc/qcom,smd-edge.yaml# + description: + Qualcomm Shared Memory subnode which represents communication edge, + channels and devices related to the RPM subsystem. + + glink-edge: + $ref: /schemas/remoteproc/qcom,glink-rpm-edge.yaml# + description: + Qualcomm G-Link subnode which represents communication edge, + channels and devices related to the RPM subsystem. + + interrupt-controller: + type: object + $ref: /schemas/interrupt-controller/qcom,mpm.yaml# + description: + MSM Power Manager (MPM) interrupt controller that monitors interrupts + when the system is asleep. + + master-stats: + $ref: /schemas/soc/qcom/qcom,rpm-master-stats.yaml# + description: + Subsystem-level low-power mode statistics provided by RPM. + +required: + - compatible + +oneOf: + - required: + - smd-edge + - required: + - glink-edge + +additionalProperties: false + +examples: + # SMD + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + remoteproc { + compatible = "qcom,msm8916-rpm-proc", "qcom,rpm-proc"; + + smd-edge { + interrupts = <GIC_SPI 168 IRQ_TYPE_EDGE_RISING>; + qcom,ipc = <&apcs 8 0>; + qcom,smd-edge = <15>; + + rpm-requests { + compatible = "qcom,rpm-msm8916"; + qcom,smd-channels = "rpm_requests"; + /* ... */ + }; + }; + }; + # GLINK + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + remoteproc { + compatible = "qcom,qcm2290-rpm-proc", "qcom,rpm-proc"; + + glink-edge { + compatible = "qcom,glink-rpm"; + interrupts = <GIC_SPI 194 IRQ_TYPE_EDGE_RISING>; + qcom,rpm-msg-ram = <&rpm_msg_ram>; + mboxes = <&apcs_glb 0>; + + rpm-requests { + compatible = "qcom,rpm-qcm2290"; + qcom,glink-channels = "rpm_requests"; + /* ... */ + }; + }; + }; diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,sc7180-pas.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,sc7180-pas.yaml index 5cefd2c58593..689d5d535331 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,sc7180-pas.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,sc7180-pas.yaml @@ -51,7 +51,7 @@ properties: - const: mss memory-region: - minItems: 1 + maxItems: 1 description: Reference to the reserved-memory for the Hexagon core qcom,qmp: @@ -67,6 +67,7 @@ properties: required: - compatible - reg + - memory-region allOf: - $ref: /schemas/remoteproc/qcom,pas-common.yaml# diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,sc8180x-pas.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,sc8180x-pas.yaml index c1f8dd8d0e4c..4744a37b2b5d 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,sc8180x-pas.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,sc8180x-pas.yaml @@ -38,7 +38,7 @@ properties: smd-edge: false memory-region: - minItems: 1 + maxItems: 1 description: Reference to the reserved-memory for the Hexagon core firmware-name: @@ -48,6 +48,7 @@ properties: required: - compatible - reg + - memory-region allOf: - $ref: /schemas/remoteproc/qcom,pas-common.yaml# diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,sc8280xp-pas.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,sc8280xp-pas.yaml index f6fbc531dc28..96d53baf6e00 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,sc8280xp-pas.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,sc8280xp-pas.yaml @@ -38,7 +38,7 @@ properties: smd-edge: false memory-region: - minItems: 1 + maxItems: 1 description: Reference to the reserved-memory for the Hexagon core firmware-name: @@ -48,6 +48,7 @@ properties: required: - compatible - reg + - memory-region allOf: - $ref: /schemas/remoteproc/qcom,pas-common.yaml# diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,sdx55-pas.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,sdx55-pas.yaml index c66e298462c7..5d463272165f 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,sdx55-pas.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,sdx55-pas.yaml @@ -46,7 +46,7 @@ properties: - const: mss memory-region: - minItems: 1 + maxItems: 1 description: Reference to the reserved-memory for the Hexagon core qcom,qmp: @@ -62,6 +62,7 @@ properties: required: - compatible - reg + - memory-region allOf: - $ref: /schemas/remoteproc/qcom,pas-common.yaml# diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,sm6115-pas.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,sm6115-pas.yaml index f5d1fa9f45f1..028287235912 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,sm6115-pas.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,sm6115-pas.yaml @@ -15,10 +15,19 @@ description: properties: compatible: - enum: - - qcom,sm6115-adsp-pas - - qcom,sm6115-cdsp-pas - - qcom,sm6115-mpss-pas + oneOf: + - enum: + - qcom,sm6115-adsp-pas + - qcom,sm6115-cdsp-pas + - qcom,sm6115-mpss-pas + + - items: + - const: qcom,qcm2290-adsp-pas + - const: qcom,sm6115-adsp-pas + + - items: + - const: qcom,qcm2290-mpss-pas + - const: qcom,sm6115-mpss-pas reg: maxItems: 1 @@ -32,7 +41,7 @@ properties: - const: xo memory-region: - minItems: 1 + maxItems: 1 description: Reference to the reserved-memory for the Hexagon core smd-edge: false @@ -44,15 +53,17 @@ properties: required: - compatible - reg + - memory-region allOf: - $ref: /schemas/remoteproc/qcom,pas-common.yaml# - if: properties: compatible: - enum: - - qcom,sm6115-adsp-pas - - qcom,sm6115-cdsp-pas + contains: + enum: + - qcom,sm6115-adsp-pas + - qcom,sm6115-cdsp-pas then: properties: interrupts: @@ -69,9 +80,10 @@ allOf: - if: properties: compatible: - enum: - - qcom,sm6115-cdsp-pas - - qcom,sm6115-mpss-pas + contains: + enum: + - qcom,sm6115-cdsp-pas + - qcom,sm6115-mpss-pas then: properties: power-domains: @@ -84,8 +96,9 @@ allOf: - if: properties: compatible: - enum: - - qcom,sm6115-adsp-pas + contains: + enum: + - qcom,sm6115-adsp-pas then: properties: power-domains: diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,sm6350-pas.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,sm6350-pas.yaml index fee02fa800b5..f7e40fb166da 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,sm6350-pas.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,sm6350-pas.yaml @@ -36,7 +36,7 @@ properties: description: Reference to the AOSS side-channel message RAM. memory-region: - minItems: 1 + maxItems: 1 description: Reference to the reserved-memory for the Hexagon core smd-edge: false @@ -48,6 +48,7 @@ properties: required: - compatible - reg + - memory-region allOf: - $ref: /schemas/remoteproc/qcom,pas-common.yaml# diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,sm8150-pas.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,sm8150-pas.yaml index 2c085ac2c3fb..238c6e5e67c5 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,sm8150-pas.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,sm8150-pas.yaml @@ -40,7 +40,7 @@ properties: description: Reference to the AOSS side-channel message RAM. memory-region: - minItems: 1 + maxItems: 1 description: Reference to the reserved-memory for the Hexagon core smd-edge: false @@ -52,6 +52,7 @@ properties: required: - compatible - reg + - memory-region allOf: - $ref: /schemas/remoteproc/qcom,pas-common.yaml# diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,sm8350-pas.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,sm8350-pas.yaml index af24f9a3cdf1..53cea8e53a31 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,sm8350-pas.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,sm8350-pas.yaml @@ -43,7 +43,7 @@ properties: smd-edge: false memory-region: - minItems: 1 + maxItems: 1 description: Reference to the reserved-memory for the Hexagon core firmware-name: @@ -53,6 +53,7 @@ properties: required: - compatible - reg + - memory-region allOf: - $ref: /schemas/remoteproc/qcom,pas-common.yaml# @@ -139,7 +140,7 @@ examples: #include <dt-bindings/clock/qcom,rpmh.h> #include <dt-bindings/interrupt-controller/irq.h> #include <dt-bindings/mailbox/qcom-ipcc.h> - #include <dt-bindings/power/qcom-rpmpd.h> + #include <dt-bindings/power/qcom,rpmhpd.h> remoteproc@30000000 { compatible = "qcom,sm8450-adsp-pas"; @@ -160,8 +161,8 @@ examples: memory-region = <&adsp_mem>; - power-domains = <&rpmhpd SM8450_LCX>, - <&rpmhpd SM8450_LMX>; + power-domains = <&rpmhpd RPMHPD_LCX>, + <&rpmhpd RPMHPD_LMX>; power-domain-names = "lcx", "lmx"; qcom,qmp = <&aoss_qmp>; diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,sm8550-pas.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,sm8550-pas.yaml index fe216aa531ed..58120829fb06 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,sm8550-pas.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,sm8550-pas.yaml @@ -53,6 +53,7 @@ properties: required: - compatible - reg + - memory-region allOf: - $ref: /schemas/remoteproc/qcom,pas-common.yaml# diff --git a/Documentation/devicetree/bindings/remoteproc/renesas,rcar-rproc.yaml b/Documentation/devicetree/bindings/remoteproc/renesas,rcar-rproc.yaml index 4bea679a0f61..5c280117dc93 100644 --- a/Documentation/devicetree/bindings/remoteproc/renesas,rcar-rproc.yaml +++ b/Documentation/devicetree/bindings/remoteproc/renesas,rcar-rproc.yaml @@ -31,7 +31,7 @@ properties: remoteproc device. This is variable and describes the memories shared with the remote processor (e.g. remoteproc firmware and carveouts, rpmsg vrings, ...). - (see ../reserved-memory/reserved-memory.yaml) + (see reserved-memory/reserved-memory.yaml in dtschema project) required: - compatible diff --git a/Documentation/devicetree/bindings/remoteproc/ti,k3-dsp-rproc.yaml b/Documentation/devicetree/bindings/remoteproc/ti,k3-dsp-rproc.yaml index f16e90380df1..9768db8663eb 100644 --- a/Documentation/devicetree/bindings/remoteproc/ti,k3-dsp-rproc.yaml +++ b/Documentation/devicetree/bindings/remoteproc/ti,k3-dsp-rproc.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/remoteproc/ti,k3-dsp-rproc.yaml# diff --git a/Documentation/devicetree/bindings/remoteproc/ti,k3-r5f-rproc.yaml b/Documentation/devicetree/bindings/remoteproc/ti,k3-r5f-rproc.yaml index fcc3db97fe8f..a492f74a8608 100644 --- a/Documentation/devicetree/bindings/remoteproc/ti,k3-r5f-rproc.yaml +++ b/Documentation/devicetree/bindings/remoteproc/ti,k3-r5f-rproc.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/remoteproc/ti,k3-r5f-rproc.yaml# @@ -102,7 +102,7 @@ patternProperties: caches. Each of the TCMs can be enabled or disabled independently and either of them can be configured to appear at that R5F's address 0x0. - The cores do not use an MMU, but has a Region Address Translater + The cores do not use an MMU, but has a Region Address Translator (RAT) module that is accessible only from the R5Fs for providing translations between 32-bit CPU addresses into larger system bus addresses. Cache and memory access settings are provided through a diff --git a/Documentation/devicetree/bindings/remoteproc/ti,omap-remoteproc.yaml b/Documentation/devicetree/bindings/remoteproc/ti,omap-remoteproc.yaml index 1fdc2741c36e..94eb2033e79c 100644 --- a/Documentation/devicetree/bindings/remoteproc/ti,omap-remoteproc.yaml +++ b/Documentation/devicetree/bindings/remoteproc/ti,omap-remoteproc.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/remoteproc/ti,omap-remoteproc.yaml# diff --git a/Documentation/devicetree/bindings/remoteproc/ti,pru-consumer.yaml b/Documentation/devicetree/bindings/remoteproc/ti,pru-consumer.yaml index 35f0bb38f7b2..2811334515d1 100644 --- a/Documentation/devicetree/bindings/remoteproc/ti,pru-consumer.yaml +++ b/Documentation/devicetree/bindings/remoteproc/ti,pru-consumer.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/remoteproc/ti,pru-consumer.yaml# diff --git a/Documentation/devicetree/bindings/remoteproc/ti,pru-rproc.yaml b/Documentation/devicetree/bindings/remoteproc/ti,pru-rproc.yaml index cd55d80137f7..baccd98754a9 100644 --- a/Documentation/devicetree/bindings/remoteproc/ti,pru-rproc.yaml +++ b/Documentation/devicetree/bindings/remoteproc/ti,pru-rproc.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/remoteproc/ti,pru-rproc.yaml# diff --git a/Documentation/devicetree/bindings/remoteproc/xlnx,zynqmp-r5fss.yaml b/Documentation/devicetree/bindings/remoteproc/xlnx,zynqmp-r5fss.yaml index 9f677367dd9f..78aac69f1060 100644 --- a/Documentation/devicetree/bindings/remoteproc/xlnx,zynqmp-r5fss.yaml +++ b/Documentation/devicetree/bindings/remoteproc/xlnx,zynqmp-r5fss.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/remoteproc/xlnx,zynqmp-r5fss.yaml# diff --git a/Documentation/devicetree/bindings/reserved-memory/framebuffer.yaml b/Documentation/devicetree/bindings/reserved-memory/framebuffer.yaml deleted file mode 100644 index 851ec24d6142..000000000000 --- a/Documentation/devicetree/bindings/reserved-memory/framebuffer.yaml +++ /dev/null @@ -1,52 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/reserved-memory/framebuffer.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: /reserved-memory framebuffer node - -maintainers: - - devicetree-spec@vger.kernel.org - -allOf: - - $ref: reserved-memory.yaml - -properties: - compatible: - const: framebuffer - description: > - This indicates a region of memory meant to be used as a framebuffer for - a set of display devices. It can be used by an operating system to keep - the framebuffer from being overwritten and use it as the backing memory - for a display device (such as simple-framebuffer). - -unevaluatedProperties: false - -examples: - - | - / { - compatible = "foo"; - model = "foo"; - #address-cells = <1>; - #size-cells = <1>; - - chosen { - framebuffer { - compatible = "simple-framebuffer"; - memory-region = <&fb>; - }; - }; - - reserved-memory { - #address-cells = <1>; - #size-cells = <1>; - ranges; - - fb: framebuffer@80000000 { - compatible = "framebuffer"; - reg = <0x80000000 0x007e9000>; - }; - }; - }; -... diff --git a/Documentation/devicetree/bindings/reserved-memory/memory-region.yaml b/Documentation/devicetree/bindings/reserved-memory/memory-region.yaml deleted file mode 100644 index 592f180e6b0d..000000000000 --- a/Documentation/devicetree/bindings/reserved-memory/memory-region.yaml +++ /dev/null @@ -1,40 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/reserved-memory/memory-region.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Reserved Memory Region - -maintainers: - - devicetree-spec@vger.kernel.org - -description: | - Regions in the /reserved-memory node may be referenced by other device - nodes by adding a memory-region property to the device node. - -select: true - -properties: - memory-region: - $ref: /schemas/types.yaml#/definitions/phandle-array - description: > - Phandle to a /reserved-memory child node assigned to the device. - - memory-region-names: - $ref: /schemas/types.yaml#/definitions/string-array - description: > - A list of names, one for each corresponding entry in the - memory-region property - -additionalProperties: true - -examples: - - | - fb0: video@12300000 { - /* ... */ - reg = <0x12300000 0x1000>; - memory-region = <&display_reserved>; - }; - -... diff --git a/Documentation/devicetree/bindings/reserved-memory/nvidia,tegra264-bpmp-shmem.yaml b/Documentation/devicetree/bindings/reserved-memory/nvidia,tegra264-bpmp-shmem.yaml new file mode 100644 index 000000000000..f9b2f0fdc282 --- /dev/null +++ b/Documentation/devicetree/bindings/reserved-memory/nvidia,tegra264-bpmp-shmem.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reserved-memory/nvidia,tegra264-bpmp-shmem.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Tegra CPU-NS - BPMP IPC reserved memory + +maintainers: + - Peter De Schrijver <pdeschrijver@nvidia.com> + +description: | + Define a memory region used for communication between CPU-NS and BPMP. + Typically this node is created by the bootloader as the physical address + has to be known to both CPU-NS and BPMP for correct IPC operation. + The memory region is defined using a child node under /reserved-memory. + The sub-node is named shmem@<address>. + +allOf: + - $ref: reserved-memory.yaml + +properties: + compatible: + const: nvidia,tegra264-bpmp-shmem + + reg: + description: The physical address and size of the shared SDRAM region + +unevaluatedProperties: false + +required: + - compatible + - reg + - no-map + +examples: + - | + reserved-memory { + #address-cells = <2>; + #size-cells = <2>; + dram_cpu_bpmp_mail: shmem@f1be0000 { + compatible = "nvidia,tegra264-bpmp-shmem"; + reg = <0x0 0xf1be0000 0x0 0x2000>; + no-map; + }; + }; +... diff --git a/Documentation/devicetree/bindings/reserved-memory/qcom,rmtfs-mem.yaml b/Documentation/devicetree/bindings/reserved-memory/qcom,rmtfs-mem.yaml index bab982f00485..46407e9c1d4f 100644 --- a/Documentation/devicetree/bindings/reserved-memory/qcom,rmtfs-mem.yaml +++ b/Documentation/devicetree/bindings/reserved-memory/qcom,rmtfs-mem.yaml @@ -26,6 +26,17 @@ properties: description: > identifier of the client to use this region for buffers + qcom,use-guard-pages: + type: boolean + description: > + Indicates that the firmware, or hardware, does not gracefully handle + memory protection of this region when placed adjacent to other protected + memory regions, and that padding around the used portion of the memory + region is necessary. + + When this is set, the first and last page should be left unused, and the + effective size of the region will thereby shrink with two pages. + qcom,vmid: $ref: /schemas/types.yaml#/definitions/uint32-array description: > diff --git a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt index 1810701a8509..8ce72996d500 100644 --- a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt +++ b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt @@ -1 +1 @@ -This file has been moved to reserved-memory.yaml. +This file has been moved to reserved-memory.yaml in the dtschema repository. diff --git a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml deleted file mode 100644 index c680e397cfd2..000000000000 --- a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml +++ /dev/null @@ -1,181 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/reserved-memory/reserved-memory.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: /reserved-memory Child Node Common - -maintainers: - - devicetree-spec@vger.kernel.org - -description: > - Reserved memory is specified as a node under the /reserved-memory node. The - operating system shall exclude reserved memory from normal usage one can - create child nodes describing particular reserved (excluded from normal use) - memory regions. Such memory regions are usually designed for the special - usage by various device drivers. - - Each child of the reserved-memory node specifies one or more regions - of reserved memory. Each child node may either use a 'reg' property to - specify a specific range of reserved memory, or a 'size' property with - optional constraints to request a dynamically allocated block of - memory. - - Following the generic-names recommended practice, node names should - reflect the purpose of the node (ie. "framebuffer" or "dma-pool"). - Unit address (@<address>) should be appended to the name if the node - is a static allocation. - -properties: - reg: true - - size: - oneOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - $ref: /schemas/types.yaml#/definitions/uint64 - description: > - Length based on parent's \#size-cells. Size in bytes of memory to - reserve. - - alignment: - oneOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - $ref: /schemas/types.yaml#/definitions/uint64 - description: > - Length based on parent's \#size-cells. Address boundary for - alignment of allocation. - - alloc-ranges: - $ref: /schemas/types.yaml#/definitions/uint32-array - description: > - Address and Length pairs. Specifies regions of memory that are - acceptable to allocate from. - - iommu-addresses: - $ref: /schemas/types.yaml#/definitions/phandle-array - description: > - A list of phandle and specifier pairs that describe static IO virtual - address space mappings and carveouts associated with a given reserved - memory region. The phandle in the first cell refers to the device for - which the mapping or carveout is to be created. - - The specifier consists of an address/size pair and denotes the IO - virtual address range of the region for the given device. The exact - format depends on the values of the "#address-cells" and "#size-cells" - properties of the device referenced via the phandle. - - When used in combination with a "reg" property, an IOVA mapping is to - be established for this memory region. One example where this can be - useful is to create an identity mapping for physical memory that the - firmware has configured some hardware to access (such as a bootsplash - framebuffer). - - If no "reg" property is specified, the "iommu-addresses" property - defines carveout regions in the IOVA space for the given device. This - can be useful if a certain memory region should not be mapped through - the IOMMU. - - no-map: - type: boolean - description: > - Indicates the operating system must not create a virtual mapping - of the region as part of its standard mapping of system memory, - nor permit speculative access to it under any circumstances other - than under the control of the device driver using the region. - - reusable: - type: boolean - description: > - The operating system can use the memory in this region with the - limitation that the device driver(s) owning the region need to be - able to reclaim it back. Typically that means that the operating - system can use that region to store volatile or cached data that - can be otherwise regenerated or migrated elsewhere. - -allOf: - - if: - required: - - no-map - - then: - not: - required: - - reusable - - - if: - required: - - reusable - - then: - not: - required: - - no-map - -oneOf: - - oneOf: - - required: - - reg - - - required: - - size - - - oneOf: - # IOMMU reservations - - required: - - iommu-addresses - - # IOMMU mappings - - required: - - reg - - iommu-addresses - -additionalProperties: true - -examples: - - | - / { - compatible = "foo"; - model = "foo"; - - #address-cells = <2>; - #size-cells = <2>; - - reserved-memory { - #address-cells = <2>; - #size-cells = <2>; - ranges; - - adsp_resv: reservation-adsp { - /* - * Restrict IOVA mappings for ADSP buffers to the 512 MiB region - * from 0x40000000 - 0x5fffffff. Anything outside is reserved by - * the ADSP for I/O memory and private memory allocations. - */ - iommu-addresses = <&adsp 0x0 0x00000000 0x00 0x40000000>, - <&adsp 0x0 0x60000000 0xff 0xa0000000>; - }; - - fb: framebuffer@90000000 { - reg = <0x0 0x90000000 0x0 0x00800000>; - iommu-addresses = <&dc0 0x0 0x90000000 0x0 0x00800000>; - }; - }; - - bus@0 { - #address-cells = <1>; - #size-cells = <1>; - ranges = <0x0 0x0 0x0 0x40000000>; - - adsp: adsp@2990000 { - reg = <0x2990000 0x2000>; - memory-region = <&adsp_resv>; - }; - - dc0: display@15200000 { - reg = <0x15200000 0x10000>; - memory-region = <&fb>; - }; - }; - }; -... diff --git a/Documentation/devicetree/bindings/reserved-memory/shared-dma-pool.yaml b/Documentation/devicetree/bindings/reserved-memory/shared-dma-pool.yaml deleted file mode 100644 index 457de0920cd1..000000000000 --- a/Documentation/devicetree/bindings/reserved-memory/shared-dma-pool.yaml +++ /dev/null @@ -1,97 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/reserved-memory/shared-dma-pool.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: /reserved-memory DMA pool - -maintainers: - - devicetree-spec@vger.kernel.org - -allOf: - - $ref: reserved-memory.yaml - -properties: - compatible: - oneOf: - - const: shared-dma-pool - description: > - This indicates a region of memory meant to be used as a shared - pool of DMA buffers for a set of devices. It can be used by an - operating system to instantiate the necessary pool management - subsystem if necessary. - - - const: restricted-dma-pool - description: > - This indicates a region of memory meant to be used as a pool - of restricted DMA buffers for a set of devices. The memory - region would be the only region accessible to those devices. - When using this, the no-map and reusable properties must not - be set, so the operating system can create a virtual mapping - that will be used for synchronization. The main purpose for - restricted DMA is to mitigate the lack of DMA access control - on systems without an IOMMU, which could result in the DMA - accessing the system memory at unexpected times and/or - unexpected addresses, possibly leading to data leakage or - corruption. The feature on its own provides a basic level of - protection against the DMA overwriting buffer contents at - unexpected times. However, to protect against general data - leakage and system memory corruption, the system needs to - provide way to lock down the memory access, e.g., MPU. Note - that since coherent allocation needs remapping, one must set - up another device coherent pool by shared-dma-pool and use - dma_alloc_from_dev_coherent instead for atomic coherent - allocation. - - linux,cma-default: - type: boolean - description: > - If this property is present, then Linux will use the region for - the default pool of the contiguous memory allocator. - - linux,dma-default: - type: boolean - description: > - If this property is present, then Linux will use the region for - the default pool of the consistent DMA allocator. - -if: - properties: - compatible: - contains: - const: restricted-dma-pool -then: - properties: - no-map: false - reusable: false - -unevaluatedProperties: false - -examples: - - | - reserved-memory { - #address-cells = <1>; - #size-cells = <1>; - ranges; - - /* global autoconfigured region for contiguous allocations */ - linux,cma { - compatible = "shared-dma-pool"; - reusable; - size = <0x4000000>; - alignment = <0x2000>; - linux,cma-default; - }; - - display_reserved: framebuffer@78000000 { - reg = <0x78000000 0x800000>; - }; - - restricted_dma_reserved: restricted-dma-pool@50000000 { - compatible = "restricted-dma-pool"; - reg = <0x50000000 0x4000000>; - }; - }; - -... diff --git a/Documentation/devicetree/bindings/reset/altr,rst-mgr.yaml b/Documentation/devicetree/bindings/reset/altr,rst-mgr.yaml index 4379cec6b35a..761c70cf9ddf 100644 --- a/Documentation/devicetree/bindings/reset/altr,rst-mgr.yaml +++ b/Documentation/devicetree/bindings/reset/altr,rst-mgr.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Altera SOCFPGA Reset Manager maintainers: - - Dinh Nguyen <dinguyen@altera.com> + - Dinh Nguyen <dinguyen@kernel.org> properties: compatible: @@ -32,9 +32,17 @@ properties: required: - compatible - reg - - altr,modrst-offset - '#reset-cells' +if: + properties: + compatible: + contains: + const: altr,stratix10-rst-mgr +then: + properties: + altr,modrst-offset: false + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/reset/ti,sci-reset.yaml b/Documentation/devicetree/bindings/reset/ti,sci-reset.yaml index dcf9206e12be..e10eb98eddad 100644 --- a/Documentation/devicetree/bindings/reset/ti,sci-reset.yaml +++ b/Documentation/devicetree/bindings/reset/ti,sci-reset.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/reset/ti,sci-reset.yaml# diff --git a/Documentation/devicetree/bindings/reset/ti,tps380x-reset.yaml b/Documentation/devicetree/bindings/reset/ti,tps380x-reset.yaml index f436f2cf1df7..6063784f0352 100644 --- a/Documentation/devicetree/bindings/reset/ti,tps380x-reset.yaml +++ b/Documentation/devicetree/bindings/reset/ti,tps380x-reset.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/reset/ti,tps380x-reset.yaml# diff --git a/Documentation/devicetree/bindings/reset/ti-syscon-reset.txt b/Documentation/devicetree/bindings/reset/ti-syscon-reset.txt index 86945502ccb5..61a0ff33e89f 100644 --- a/Documentation/devicetree/bindings/reset/ti-syscon-reset.txt +++ b/Documentation/devicetree/bindings/reset/ti-syscon-reset.txt @@ -43,7 +43,7 @@ Required properties: Cell #6 : bit position of the reset in the reset status register Cell #7 : Flags used to control reset behavior, - availible flags defined in the DT include + available flags defined in the DT include file <dt-bindings/reset/ti-syscon.h> SysCon Reset Consumer Nodes diff --git a/Documentation/devicetree/bindings/reset/xlnx,zynqmp-reset.yaml b/Documentation/devicetree/bindings/reset/xlnx,zynqmp-reset.yaml index 0d50f6a54af3..49db66801429 100644 --- a/Documentation/devicetree/bindings/reset/xlnx,zynqmp-reset.yaml +++ b/Documentation/devicetree/bindings/reset/xlnx,zynqmp-reset.yaml @@ -32,6 +32,7 @@ properties: enum: - xlnx,zynqmp-reset - xlnx,versal-reset + - xlnx,versal-net-reset "#reset-cells": const: 1 diff --git a/Documentation/devicetree/bindings/riscv/cpus.yaml b/Documentation/devicetree/bindings/riscv/cpus.yaml index 38c0b5213736..f392e367d673 100644 --- a/Documentation/devicetree/bindings/riscv/cpus.yaml +++ b/Documentation/devicetree/bindings/riscv/cpus.yaml @@ -47,6 +47,7 @@ properties: - sifive,u74-mc - thead,c906 - thead,c910 + - thead,c920 - const: riscv - items: - enum: @@ -91,6 +92,7 @@ properties: interrupt-controller: type: object + additionalProperties: false description: Describes the CPU's local interrupt controller properties: diff --git a/Documentation/devicetree/bindings/riscv/extensions.yaml b/Documentation/devicetree/bindings/riscv/extensions.yaml index cc1f546fdbdc..c91ab0e46648 100644 --- a/Documentation/devicetree/bindings/riscv/extensions.yaml +++ b/Documentation/devicetree/bindings/riscv/extensions.yaml @@ -128,6 +128,12 @@ properties: changes to interrupts as frozen at commit ccbddab ("Merge pull request #42 from riscv/jhauser-2023-RC4") of riscv-aia. + - const: smstateen + description: | + The standard Smstateen extension for controlling access to CSRs + added by other RISC-V extensions in H/S/VS/U/VU modes and as + ratified at commit a28bfae (Ratified (#7)) of riscv-state-enable. + - const: ssaia description: | The standard Ssaia supervisor-level extension for the advanced @@ -212,6 +218,12 @@ properties: ratified in the 20191213 version of the unprivileged ISA specification. + - const: zicond + description: + The standard Zicond extension for conditional arithmetic and + conditional-select/move operations as ratified in commit 95cf1f9 + ("Add changes requested by Ved during signoff") of riscv-zicond. + - const: zicsr description: | The standard Zicsr extension for control and status register diff --git a/Documentation/devicetree/bindings/riscv/sophgo.yaml b/Documentation/devicetree/bindings/riscv/sophgo.yaml new file mode 100644 index 000000000000..86748c5390be --- /dev/null +++ b/Documentation/devicetree/bindings/riscv/sophgo.yaml @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/riscv/sophgo.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sophgo SoC-based boards + +maintainers: + - Chao Wei <chao.wei@sophgo.com> + - Chen Wang <unicorn_wang@outlook.com> + +description: + Sophgo SoC-based boards + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - items: + - enum: + - milkv,duo + - const: sophgo,cv1800b + - items: + - enum: + - milkv,pioneer + - const: sophgo,sg2042 + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/riscv/thead.yaml b/Documentation/devicetree/bindings/riscv/thead.yaml index e62f6821372e..301912dcd290 100644 --- a/Documentation/devicetree/bindings/riscv/thead.yaml +++ b/Documentation/devicetree/bindings/riscv/thead.yaml @@ -17,6 +17,10 @@ properties: const: '/' compatible: oneOf: + - description: BeagleV Ahead single board computer + items: + - const: beagle,beaglev-ahead + - const: thead,th1520 - description: Sipeed Lichee Pi 4A board for the Sipeed Lichee Module 4A items: - enum: diff --git a/Documentation/devicetree/bindings/rng/amlogic,meson-rng.yaml b/Documentation/devicetree/bindings/rng/amlogic,meson-rng.yaml index 457a6e43d810..afa52af442a7 100644 --- a/Documentation/devicetree/bindings/rng/amlogic,meson-rng.yaml +++ b/Documentation/devicetree/bindings/rng/amlogic,meson-rng.yaml @@ -14,6 +14,7 @@ properties: compatible: enum: - amlogic,meson-rng + - amlogic,meson-s4-rng reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/rng/omap_rng.yaml b/Documentation/devicetree/bindings/rng/omap_rng.yaml index ccf54fae8302..c0ac4f68ea54 100644 --- a/Documentation/devicetree/bindings/rng/omap_rng.yaml +++ b/Documentation/devicetree/bindings/rng/omap_rng.yaml @@ -30,8 +30,8 @@ properties: clocks: minItems: 1 items: - - description: EIP150 gatable clock - - description: Main gatable clock + - description: EIP150 gateable clock + - description: Main gateable clock clock-names: minItems: 1 diff --git a/Documentation/devicetree/bindings/rng/st,stm32-rng.yaml b/Documentation/devicetree/bindings/rng/st,stm32-rng.yaml index 187b172d0cca..717f6b321f88 100644 --- a/Documentation/devicetree/bindings/rng/st,stm32-rng.yaml +++ b/Documentation/devicetree/bindings/rng/st,stm32-rng.yaml @@ -15,7 +15,9 @@ maintainers: properties: compatible: - const: st,stm32-rng + enum: + - st,stm32-rng + - st,stm32mp13-rng reg: maxItems: 1 @@ -30,11 +32,27 @@ properties: type: boolean description: If set enable the clock detection management + st,rng-lock-conf: + type: boolean + description: If set, the RNG configuration in RNG_CR, RNG_HTCR and + RNG_NSCR will be locked. + required: - compatible - reg - clocks +allOf: + - if: + properties: + compatible: + contains: + enum: + - st,stm32-rng + then: + properties: + st,rng-lock-conf: false + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/rtc/atmel,at91rm9200-rtc.yaml b/Documentation/devicetree/bindings/rtc/atmel,at91rm9200-rtc.yaml index 4d2bef15fb7a..c8bb2eef442d 100644 --- a/Documentation/devicetree/bindings/rtc/atmel,at91rm9200-rtc.yaml +++ b/Documentation/devicetree/bindings/rtc/atmel,at91rm9200-rtc.yaml @@ -14,13 +14,17 @@ maintainers: properties: compatible: - enum: - - atmel,at91rm9200-rtc - - atmel,at91sam9x5-rtc - - atmel,sama5d4-rtc - - atmel,sama5d2-rtc - - microchip,sam9x60-rtc - - microchip,sama7g5-rtc + oneOf: + - enum: + - atmel,at91rm9200-rtc + - atmel,at91sam9x5-rtc + - atmel,sama5d4-rtc + - atmel,sama5d2-rtc + - microchip,sam9x60-rtc + - microchip,sama7g5-rtc + - items: + - const: microchip,sam9x7-rtc + - const: microchip,sam9x60-rtc reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/rtc/intersil,isl12022.yaml b/Documentation/devicetree/bindings/rtc/intersil,isl12022.yaml new file mode 100644 index 000000000000..c2d1441ef273 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/intersil,isl12022.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/intersil,isl12022.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intersil ISL12022 Real-time Clock + +maintainers: + - Alexandre Belloni <alexandre.belloni@bootlin.com> + +properties: + compatible: + const: isil,isl12022 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + '#clock-cells': + const: 0 + + isil,battery-trip-levels-microvolt: + description: + The battery voltages at which the first alarm and second alarm + should trigger (normally ~85% and ~75% of nominal V_BAT). + items: + - enum: [2125000, 2295000, 2550000, 2805000, 3060000, 4250000, 4675000] + - enum: [1875000, 2025000, 2250000, 2475000, 2700000, 3750000, 4125000] + +required: + - compatible + - reg + +allOf: + - $ref: rtc.yaml# + # If #clock-cells is present, interrupts must not be present + - if: + required: + - '#clock-cells' + then: + properties: + interrupts: false + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + rtc@6f { + compatible = "isil,isl12022"; + reg = <0x6f>; + interrupts-extended = <&gpio1 5 IRQ_TYPE_LEVEL_LOW>; + isil,battery-trip-levels-microvolt = <2550000>, <2250000>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt b/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt deleted file mode 100644 index 85be53a42180..000000000000 --- a/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt +++ /dev/null @@ -1,38 +0,0 @@ -* Maxim DS3231 Real Time Clock - -Required properties: -- compatible: Should contain "maxim,ds3231". -- reg: I2C address for chip. - -Optional property: -- #clock-cells: Should be 1. -- clock-output-names: - overwrite the default clock names "ds3231_clk_sqw" and "ds3231_clk_32khz". - -Each clock is assigned an identifier and client nodes can use this identifier -to specify the clock which they consume. Following indices are allowed: - - 0: square-wave output on the SQW pin - - 1: square-wave output on the 32kHz pin - -- interrupts: rtc alarm/event interrupt. When this property is selected, - clock on the SQW pin cannot be used. - -Example: - -ds3231: ds3231@51 { - compatible = "maxim,ds3231"; - reg = <0x68>; - #clock-cells = <1>; -}; - -device1 { -... - clocks = <&ds3231 0>; -... -}; - -device2 { -... - clocks = <&ds3231 1>; -... -}; diff --git a/Documentation/devicetree/bindings/rtc/nxp,pcf2127.yaml b/Documentation/devicetree/bindings/rtc/nxp,pcf2127.yaml index bcb230027622..2d9fe5a75b06 100644 --- a/Documentation/devicetree/bindings/rtc/nxp,pcf2127.yaml +++ b/Documentation/devicetree/bindings/rtc/nxp,pcf2127.yaml @@ -18,6 +18,7 @@ properties: - nxp,pca2129 - nxp,pcf2127 - nxp,pcf2129 + - nxp,pcf2131 reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/rtc/rtc-cmos.txt b/Documentation/devicetree/bindings/rtc/rtc-cmos.txt index b94b35f3600b..7d7b5f6bda65 100644 --- a/Documentation/devicetree/bindings/rtc/rtc-cmos.txt +++ b/Documentation/devicetree/bindings/rtc/rtc-cmos.txt @@ -10,7 +10,7 @@ Optional properties: - ctrl-reg : Contains the initial value of the control register also called "Register B". - freq-reg : Contains the initial value of the frequency register also - called "Regsiter A". + called "Register A". "Register A" and "B" are usually initialized by the firmware (BIOS for instance). If this is not done, it can be performed by the driver. diff --git a/Documentation/devicetree/bindings/rtc/st,m48t86.yaml b/Documentation/devicetree/bindings/rtc/st,m48t86.yaml new file mode 100644 index 000000000000..e3e12fa23380 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/st,m48t86.yaml @@ -0,0 +1,38 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/st,m48t86.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ST M48T86 / Dallas DS12887 RTC with SRAM + +maintainers: + - Alexandre Belloni <alexandre.belloni@bootlin.com> + +allOf: + - $ref: rtc.yaml + +properties: + compatible: + enum: + - st,m48t86 + + reg: + items: + - description: index register + - description: data register + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + rtc@10800000 { + compatible = "st,m48t86"; + reg = <0x10800000 0x1>, <0x11700000 0x1>; + }; + +... diff --git a/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml b/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml index 9af77f21bb7f..2a65f31ac5a0 100644 --- a/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml +++ b/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml @@ -45,8 +45,6 @@ properties: - isil,isl1208 # Intersil ISL1218 Low Power RTC with Battery Backed SRAM - isil,isl1218 - # Intersil ISL12022 Real-time Clock - - isil,isl12022 # Real Time Clock Module with I2C-Bus - microcrystal,rv3029 # Real Time Clock diff --git a/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml b/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml index 01ec45b3b406..2e189e548327 100644 --- a/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml +++ b/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml @@ -33,6 +33,7 @@ properties: - amlogic,meson8b-uart - amlogic,meson-gx-uart - amlogic,meson-s4-uart + - amlogic,meson-a1-uart - const: amlogic,meson-ao-uart - description: Always-on power domain UART controller on G12A SoCs items: @@ -46,10 +47,15 @@ properties: - amlogic,meson8b-uart - amlogic,meson-gx-uart - amlogic,meson-s4-uart + - amlogic,meson-a1-uart - description: Everything-Else power domain UART controller on G12A SoCs items: - const: amlogic,meson-g12a-uart - const: amlogic,meson-gx-uart + - description: UART controller on S4 compatible SoCs + items: + - const: amlogic,t7-uart + - const: amlogic,meson-s4-uart reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/serial/atmel,at91-usart.yaml b/Documentation/devicetree/bindings/serial/atmel,at91-usart.yaml index 30b2131b5860..65cb2e5c5eee 100644 --- a/Documentation/devicetree/bindings/serial/atmel,at91-usart.yaml +++ b/Documentation/devicetree/bindings/serial/atmel,at91-usart.yaml @@ -16,7 +16,6 @@ properties: - enum: - atmel,at91rm9200-usart - atmel,at91sam9260-usart - - microchip,sam9x60-usart - items: - const: atmel,at91rm9200-dbgu - const: atmel,at91rm9200-usart @@ -24,6 +23,9 @@ properties: - const: atmel,at91sam9260-dbgu - const: atmel,at91sam9260-usart - items: + - const: microchip,sam9x60-usart + - const: atmel,at91sam9260-usart + - items: - const: microchip,sam9x60-dbgu - const: microchip,sam9x60-usart - const: atmel,at91sam9260-dbgu diff --git a/Documentation/devicetree/bindings/serial/cavium-uart.txt b/Documentation/devicetree/bindings/serial/cavium-uart.txt deleted file mode 100644 index 87a6c375cd44..000000000000 --- a/Documentation/devicetree/bindings/serial/cavium-uart.txt +++ /dev/null @@ -1,19 +0,0 @@ -* Universal Asynchronous Receiver/Transmitter (UART) - -- compatible: "cavium,octeon-3860-uart" - - Compatibility with all cn3XXX, cn5XXX and cn6XXX SOCs. - -- reg: The base address of the UART register bank. - -- interrupts: A single interrupt specifier. - -- current-speed: Optional, the current bit rate in bits per second. - -Example: - uart1: serial@1180000000c00 { - compatible = "cavium,octeon-3860-uart","ns16550"; - reg = <0x11800 0x00000c00 0x0 0x400>; - current-speed = <115200>; - interrupts = <0 35>; - }; diff --git a/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml b/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml index 93062403276b..3a5b59f5d3e3 100644 --- a/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml +++ b/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml @@ -25,11 +25,15 @@ properties: - fsl,imxrt1050-lpuart - items: - enum: - - fsl,imx93-lpuart - fsl,imx8ulp-lpuart - const: fsl,imx7ulp-lpuart - items: - enum: + - fsl,imx93-lpuart + - const: fsl,imx8ulp-lpuart + - const: fsl,imx7ulp-lpuart + - items: + - enum: - fsl,imx8qm-lpuart - fsl,imx8dxl-lpuart - const: fsl,imx8qxp-lpuart diff --git a/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.txt b/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.txt deleted file mode 100644 index f709304036c2..000000000000 --- a/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.txt +++ /dev/null @@ -1,73 +0,0 @@ -NVIDIA Tegra20/Tegra30 high speed (DMA based) UART controller driver. - -Required properties: -- compatible : should be, - "nvidia,tegra20-hsuart" for Tegra20, - "nvidia,tegra30-hsuart" for Tegra30, - "nvidia,tegra186-hsuart" for Tegra186, - "nvidia,tegra194-hsuart" for Tegra194. - -- reg: Should contain UART controller registers location and length. -- interrupts: Should contain UART controller interrupts. -- clocks: Must contain one entry, for the module clock. - See ../clocks/clock-bindings.txt for details. -- resets : Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names : Must include the following entries: - - serial -- dmas : Must contain an entry for each entry in dma-names. - See ../dma/dma.txt for details. -- dma-names : Must include the following entries: - - rx - - tx - -Optional properties: -- nvidia,enable-modem-interrupt: Enable modem interrupts. Should be enable - only if all 8 lines of UART controller are pinmuxed. -- nvidia,adjust-baud-rates: List of entries providing percentage of baud rate - adjustment within a range. - Each entry contains sets of 3 values. Range low/high and adjusted rate. - <range_low range_high adjusted_rate> - When baud rate set on controller falls within the range mentioned in this - field, baud rate will be adjusted by percentage mentioned here. - Ex: <9600 115200 200> - Increase baud rate by 2% when set baud rate falls within range 9600 to 115200 - -Baud Rate tolerance: - Standard UART devices are expected to have tolerance for baud rate error by - -4 to +4 %. All Tegra devices till Tegra210 had this support. However, - Tegra186 chip has a known hardware issue. UART Rx baud rate tolerance level - is 0% to +4% in 1-stop config. Otherwise, the received data will have - corruption/invalid framing errors. Parker errata suggests adjusting baud - rate to be higher than the deviations observed in Tx. - - Tx deviation of connected device can be captured over scope (or noted from - its spec) for valid range and Tegra baud rate has to be set above actual - Tx baud rate observed. To do this we use nvidia,adjust-baud-rates - - As an example, consider there is deviation observed in Tx for baud rates as - listed below. - 0 to 9600 has 1% deviation - 9600 to 115200 2% deviation - This slight deviation is expcted and Tegra UART is expected to handle it. Due - to the issue stated above, baud rate on Tegra UART should be set equal to or - above deviation observed for avoiding frame errors. - Property should be set like this - nvidia,adjust-baud-rates = <0 9600 100>, - <9600 115200 200>; - -Example: - -serial@70006000 { - compatible = "nvidia,tegra30-hsuart", "nvidia,tegra20-hsuart"; - reg = <0x70006000 0x40>; - reg-shift = <2>; - interrupts = <0 36 0x04>; - nvidia,enable-modem-interrupt; - clocks = <&tegra_car 6>; - resets = <&tegra_car 6>; - reset-names = "serial"; - dmas = <&apbdma 8>, <&apbdma 8>; - dma-names = "rx", "tx"; - nvidia,adjust-baud-rates = <1000000 4000000 136>; /* 1.36% shift */ -}; diff --git a/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.yaml b/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.yaml new file mode 100644 index 000000000000..04d55fecf47c --- /dev/null +++ b/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.yaml @@ -0,0 +1,125 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/serial/nvidia,tegra20-hsuart.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra20/Tegra30 high speed (DMA based) UART controller driver + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + oneOf: + - enum: + - nvidia,tegra20-hsuart + - nvidia,tegra30-hsuart + - nvidia,tegra186-hsuart + - nvidia,tegra194-hsuart + - items: + - const: nvidia,tegra124-hsuart + - const: nvidia,tegra30-hsuart + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: module clock + + resets: + items: + - description: module reset + + reset-names: + items: + - const: serial + + dmas: + items: + - description: DMA channel used for reception + - description: DMA channel used for transmission + + dma-names: + items: + - const: rx + - const: tx + + nvidia,enable-modem-interrupt: + $ref: /schemas/types.yaml#/definitions/flag + description: Enable modem interrupts. Should be enable only if all 8 lines of UART controller + are pinmuxed. + + nvidia,adjust-baud-rates: + $ref: /schemas/types.yaml#/definitions/uint32-matrix + description: | + List of entries providing percentage of baud rate adjustment within a range. Each entry + contains a set of 3 values: range low/high and adjusted rate. When the baud rate set on the + controller falls within the range mentioned in this field, the baud rate will be adjusted by + percentage mentioned here. + + Example: <9600 115200 200> + + Increase baud rate by 2% when set baud rate falls within range 9600 to 115200. + + Standard UART devices are expected to have tolerance for baud rate error by -4 to +4 %. All + Tegra devices till Tegra210 had this support. However, Tegra186 chip has a known hardware + issue. UART RX baud rate tolerance level is 0% to +4% in 1-stop config. Otherwise, the + received data will have corruption/invalid framing errors. Parker errata suggests adjusting + baud rate to be higher than the deviations observed in TX. + + TX deviation of connected device can be captured over scope (or noted from its spec) for + valid range and Tegra baud rate has to be set above actual TX baud rate observed. To do this + we use nvidia,adjust-baud-rates. + + As an example, consider there is deviation observed in TX for baud rates as listed below. 0 + to 9600 has 1% deviation 9600 to 115200 2% deviation. This slight deviation is expcted and + Tegra UART is expected to handle it. Due to the issue stated above, baud rate on Tegra UART + should be set equal to or above deviation observed for avoiding frame errors. Property + should be set like this: + + nvidia,adjust-baud-rates = <0 9600 100>, + <9600 115200 200>; + items: + items: + - description: range lower bound + - description: range upper bound + - description: adjustment (in permyriad, i.e. 0.01%) + +allOf: + - $ref: serial.yaml + +unevaluatedProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - resets + - reset-names + - dmas + - dma-names + +examples: + - | + #include <dt-bindings/clock/tegra30-car.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + serial@70006000 { + compatible = "nvidia,tegra30-hsuart"; + reg = <0x70006000 0x40>; + interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>; + nvidia,enable-modem-interrupt; + clocks = <&tegra_car TEGRA30_CLK_UARTA>; + resets = <&tegra_car 6>; + reset-names = "serial"; + dmas = <&apbdma 8>, <&apbdma 8>; + dma-names = "rx", "tx"; + nvidia,adjust-baud-rates = <1000000 4000000 136>; /* 1.36% shift */ + }; diff --git a/Documentation/devicetree/bindings/serial/nxp,lpc1850-uart.txt b/Documentation/devicetree/bindings/serial/nxp,lpc1850-uart.txt deleted file mode 100644 index 04e23e63ee4f..000000000000 --- a/Documentation/devicetree/bindings/serial/nxp,lpc1850-uart.txt +++ /dev/null @@ -1,28 +0,0 @@ -* NXP LPC1850 UART - -Required properties: -- compatible : "nxp,lpc1850-uart", "ns16550a". -- reg : offset and length of the register set for the device. -- interrupts : should contain uart interrupt. -- clocks : phandle to the input clocks. -- clock-names : required elements: "uartclk", "reg". - -Optional properties: -- dmas : Two or more DMA channel specifiers following the - convention outlined in bindings/dma/dma.txt -- dma-names : Names for the dma channels, if present. There must - be at least one channel named "tx" for transmit - and named "rx" for receive. - -Since it's also possible to also use the of_serial.c driver all -parameters from 8250.txt also apply but are optional. - -Example: -uart0: serial@40081000 { - compatible = "nxp,lpc1850-uart", "ns16550a"; - reg = <0x40081000 0x1000>; - reg-shift = <2>; - interrupts = <24>; - clocks = <&ccu2 CLK_APB0_UART0>, <&ccu1 CLK_CPU_UART0>; - clock-names = "uartclk", "reg"; -}; diff --git a/Documentation/devicetree/bindings/serial/nxp,sc16is7xx.txt b/Documentation/devicetree/bindings/serial/nxp,sc16is7xx.txt index 0fa8e3e43bf8..1a7e4bff0456 100644 --- a/Documentation/devicetree/bindings/serial/nxp,sc16is7xx.txt +++ b/Documentation/devicetree/bindings/serial/nxp,sc16is7xx.txt @@ -23,6 +23,9 @@ Optional properties: 1 = active low. - irda-mode-ports: An array that lists the indices of the port that should operate in IrDA mode. +- nxp,modem-control-line-ports: An array that lists the indices of the port that + should have shared GPIO lines configured as + modem control lines. Example: sc16is750: sc16is750@51 { @@ -35,6 +38,26 @@ Example: #gpio-cells = <2>; }; + sc16is752: sc16is752@53 { + compatible = "nxp,sc16is752"; + reg = <0x53>; + clocks = <&clk20m>; + interrupt-parent = <&gpio3>; + interrupts = <7 IRQ_TYPE_EDGE_FALLING>; + nxp,modem-control-line-ports = <1>; /* Port 1 as modem control lines */ + gpio-controller; /* Port 0 as GPIOs */ + #gpio-cells = <2>; + }; + + sc16is752: sc16is752@54 { + compatible = "nxp,sc16is752"; + reg = <0x54>; + clocks = <&clk20m>; + interrupt-parent = <&gpio3>; + interrupts = <7 IRQ_TYPE_EDGE_FALLING>; + nxp,modem-control-line-ports = <0 1>; /* Ports 0 and 1 as modem control lines */ + }; + * spi as bus Required properties: @@ -59,6 +82,9 @@ Optional properties: 1 = active low. - irda-mode-ports: An array that lists the indices of the port that should operate in IrDA mode. +- nxp,modem-control-line-ports: An array that lists the indices of the port that + should have shared GPIO lines configured as + modem control lines. Example: sc16is750: sc16is750@0 { @@ -70,3 +96,23 @@ Example: gpio-controller; #gpio-cells = <2>; }; + + sc16is752: sc16is752@1 { + compatible = "nxp,sc16is752"; + reg = <1>; + clocks = <&clk20m>; + interrupt-parent = <&gpio3>; + interrupts = <7 IRQ_TYPE_EDGE_FALLING>; + nxp,modem-control-line-ports = <1>; /* Port 1 as modem control lines */ + gpio-controller; /* Port 0 as GPIOs */ + #gpio-cells = <2>; + }; + + sc16is752: sc16is752@2 { + compatible = "nxp,sc16is752"; + reg = <2>; + clocks = <&clk20m>; + interrupt-parent = <&gpio3>; + interrupts = <7 IRQ_TYPE_EDGE_FALLING>; + nxp,modem-control-line-ports = <0 1>; /* Ports 0 and 1 as modem control lines */ + }; diff --git a/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.yaml b/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.yaml index 3862411c77b5..17c553123f96 100644 --- a/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.yaml +++ b/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.yaml @@ -117,7 +117,6 @@ properties: required: - compatible - reg - - interrupts unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/serial/st-asc.txt b/Documentation/devicetree/bindings/serial/st-asc.txt index 75d877f5968f..a1b9b6f3490a 100644 --- a/Documentation/devicetree/bindings/serial/st-asc.txt +++ b/Documentation/devicetree/bindings/serial/st-asc.txt @@ -8,7 +8,7 @@ Required properties: Optional properties: - st,hw-flow-ctrl bool flag to enable hardware flow control. -- st,force-m1 bool flat to force asc to be in Mode-1 recommeded +- st,force-m1 bool flat to force asc to be in Mode-1 recommended for high bit rates (above 19.2K) Example: serial@fe440000{ diff --git a/Documentation/devicetree/bindings/soc/amlogic/amlogic,meson-gx-hhi-sysctrl.yaml b/Documentation/devicetree/bindings/soc/amlogic/amlogic,meson-gx-hhi-sysctrl.yaml new file mode 100644 index 000000000000..16977e4e4357 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/amlogic/amlogic,meson-gx-hhi-sysctrl.yaml @@ -0,0 +1,160 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/amlogic/amlogic,meson-gx-hhi-sysctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic Meson System Control registers + +maintainers: + - Neil Armstrong <neil.armstrong@linaro.org> + +properties: + compatible: + items: + - enum: + - amlogic,meson-gx-hhi-sysctrl + - amlogic,meson-gx-ao-sysctrl + - amlogic,meson-axg-hhi-sysctrl + - amlogic,meson-axg-ao-sysctrl + - const: simple-mfd + - const: syscon + + reg: + maxItems: 1 + + clock-controller: + type: object + + power-controller: + $ref: /schemas/power/amlogic,meson-ee-pwrc.yaml + + pinctrl: + type: object + + phy: + type: object + +allOf: + - if: + properties: + compatible: + enum: + - amlogic,meson-gx-hhi-sysctrl + - amlogic,meson-axg-hhi-sysctrl + then: + properties: + clock-controller: + $ref: /schemas/clock/amlogic,gxbb-clkc.yaml# + + required: + - power-controller + + - if: + properties: + compatible: + enum: + - amlogic,meson-gx-ao-sysctrl + - amlogic,meson-axg-ao-sysctrl + then: + properties: + clock-controller: + $ref: /schemas/clock/amlogic,gxbb-aoclkc.yaml# + + power-controller: false + phy: false + + - if: + properties: + compatible: + enum: + - amlogic,meson-gx-hhi-sysctrl + then: + properties: + phy: false + + - if: + properties: + compatible: + enum: + - amlogic,meson-axg-hhi-sysctrl + then: + properties: + phy: + oneOf: + - $ref: /schemas/phy/amlogic,g12a-mipi-dphy-analog.yaml + - $ref: /schemas/phy/amlogic,meson-axg-mipi-pcie-analog.yaml + +required: + - compatible + - reg + - clock-controller + +additionalProperties: false + +examples: + - | + bus@c883c000 { + compatible = "simple-bus"; + reg = <0xc883c000 0x2000>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0xc883c000 0x2000>; + + sysctrl: system-controller@0 { + compatible = "amlogic,meson-gx-hhi-sysctrl", "simple-mfd", "syscon"; + reg = <0 0x400>; + + clock-controller { + compatible = "amlogic,gxbb-clkc"; + #clock-cells = <1>; + clocks = <&xtal>; + clock-names = "xtal"; + }; + + power-controller { + compatible = "amlogic,meson-gxbb-pwrc"; + #power-domain-cells = <1>; + amlogic,ao-sysctrl = <&sysctrl_AO>; + + resets = <&reset_viu>, + <&reset_venc>, + <&reset_vcbus>, + <&reset_bt656>, + <&reset_dvin>, + <&reset_rdma>, + <&reset_venci>, + <&reset_vencp>, + <&reset_vdac>, + <&reset_vdi6>, + <&reset_vencl>, + <&reset_vid_lock>; + reset-names = "viu", "venc", "vcbus", "bt656", "dvin", + "rdma", "venci", "vencp", "vdac", "vdi6", + "vencl", "vid_lock"; + clocks = <&clk_vpu>, <&clk_vapb>; + clock-names = "vpu", "vapb"; + }; + }; + }; + + bus@c8100000 { + compatible = "simple-bus"; + reg = <0xc8100000 0x100000>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0xc8100000 0x100000>; + + sysctrl_AO: system-controller@0 { + compatible = "amlogic,meson-gx-ao-sysctrl", "simple-mfd", "syscon"; + reg = <0 0x100>; + + clock-controller { + compatible = "amlogic,meson-gxbb-aoclkc", "amlogic,meson-gx-aoclkc"; + #clock-cells = <1>; + #reset-cells = <1>; + clocks = <&xtal>, <&clk81>; + clock-names = "xtal", "mpeg-clk"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/aspeed/uart-routing.yaml b/Documentation/devicetree/bindings/soc/aspeed/uart-routing.yaml index 6876407124dc..51aaf34acb32 100644 --- a/Documentation/devicetree/bindings/soc/aspeed/uart-routing.yaml +++ b/Documentation/devicetree/bindings/soc/aspeed/uart-routing.yaml @@ -3,8 +3,8 @@ # # Copyright (c) 2021 Aspeed Technology Inc. %YAML 1.2 --- -$id: "http://devicetree.org/schemas/soc/aspeed/uart-routing.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/soc/aspeed/uart-routing.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Aspeed UART Routing Controller diff --git a/Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-scc-qmc.yaml b/Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-scc-qmc.yaml index ec888f48cac8..e802e25923aa 100644 --- a/Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-scc-qmc.yaml +++ b/Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-scc-qmc.yaml @@ -64,6 +64,7 @@ patternProperties: description: A channel managed by this controller type: object + additionalProperties: false properties: reg: @@ -100,6 +101,32 @@ patternProperties: Channel assigned Rx time-slots within the Rx time-slots routed by the TSA to this cell. + compatible: + items: + - enum: + - fsl,mpc885-scc-qmc-hdlc + - fsl,mpc866-scc-qmc-hdlc + - const: fsl,cpm1-scc-qmc-hdlc + - const: fsl,qmc-hdlc + + fsl,framer: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle to the framer node. The framer is in charge of an E1/T1 line + interface connected to the TDM bus. It can be used to get the E1/T1 line + status such as link up/down. + + allOf: + - if: + properties: + compatible: + not: + contains: + const: fsl,qmc-hdlc + then: + properties: + fsl,framer: false + required: - reg - fsl,tx-ts-mask @@ -137,7 +164,7 @@ examples: channel@16 { /* Ch16 : First 4 even TS from all routed from TSA */ reg = <16>; - fsl,mode = "transparent"; + fsl,operational-mode = "transparent"; fsl,reverse-data; fsl,tx-ts-mask = <0x00000000 0x000000aa>; fsl,rx-ts-mask = <0x00000000 0x000000aa>; @@ -146,7 +173,7 @@ examples: channel@17 { /* Ch17 : First 4 odd TS from all routed from TSA */ reg = <17>; - fsl,mode = "transparent"; + fsl,operational-mode = "transparent"; fsl,reverse-data; fsl,tx-ts-mask = <0x00000000 0x00000055>; fsl,rx-ts-mask = <0x00000000 0x00000055>; @@ -154,9 +181,13 @@ examples: channel@19 { /* Ch19 : 8 TS (TS 8..15) from all routed from TSA */ + compatible = "fsl,mpc885-scc-qmc-hdlc", + "fsl,cpm1-scc-qmc-hdlc", + "fsl,qmc-hdlc"; reg = <19>; - fsl,mode = "hdlc"; + fsl,operational-mode = "hdlc"; fsl,tx-ts-mask = <0x00000000 0x0000ff00>; fsl,rx-ts-mask = <0x00000000 0x0000ff00>; + fsl,framer = <&framer>; }; }; diff --git a/Documentation/devicetree/bindings/soc/intel/intel,hps-copy-engine.yaml b/Documentation/devicetree/bindings/soc/intel/intel,hps-copy-engine.yaml index 8634865015cd..ceb81646fe75 100644 --- a/Documentation/devicetree/bindings/soc/intel/intel,hps-copy-engine.yaml +++ b/Documentation/devicetree/bindings/soc/intel/intel,hps-copy-engine.yaml @@ -2,8 +2,8 @@ # Copyright (C) 2022, Intel Corporation %YAML 1.2 --- -$id: "http://devicetree.org/schemas/soc/intel/intel,hps-copy-engine.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/soc/intel/intel,hps-copy-engine.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Intel HPS Copy Engine diff --git a/Documentation/devicetree/bindings/soc/litex/litex,soc-controller.yaml b/Documentation/devicetree/bindings/soc/litex/litex,soc-controller.yaml index ecae9fa8561b..a64406ca17b5 100644 --- a/Documentation/devicetree/bindings/soc/litex/litex,soc-controller.yaml +++ b/Documentation/devicetree/bindings/soc/litex/litex,soc-controller.yaml @@ -2,8 +2,8 @@ # Copyright 2020 Antmicro <www.antmicro.com> %YAML 1.2 --- -$id: "http://devicetree.org/schemas/soc/litex/litex,soc-controller.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/soc/litex/litex,soc-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: LiteX SoC Controller driver diff --git a/Documentation/devicetree/bindings/soc/loongson/loongson,ls2k-pmc.yaml b/Documentation/devicetree/bindings/soc/loongson/loongson,ls2k-pmc.yaml new file mode 100644 index 000000000000..510f6cb0f084 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/loongson/loongson,ls2k-pmc.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/loongson/loongson,ls2k-pmc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Loongson-2 Power Manager controller + +maintainers: + - Yinbo Zhu <zhuyinbo@loongson.cn> + +properties: + compatible: + oneOf: + - items: + - const: loongson,ls2k0500-pmc + - const: syscon + - items: + - enum: + - loongson,ls2k1000-pmc + - loongson,ls2k2000-pmc + - const: loongson,ls2k0500-pmc + - const: syscon + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + loongson,suspend-address: + $ref: /schemas/types.yaml#/definitions/uint64 + description: + The "loongson,suspend-address" is a deep sleep state (Suspend To + RAM) firmware entry address which was jumped from kernel and it's + value was dependent on specific platform firmware code. In + addition, the PM need according to it to indicate that current + SoC whether support Suspend To RAM. + + syscon-poweroff: + $ref: /schemas/power/reset/syscon-poweroff.yaml# + type: object + description: + Node for power off method + + syscon-reboot: + $ref: /schemas/power/reset/syscon-reboot.yaml# + type: object + description: + Node for reboot method + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + power-management@1fe27000 { + compatible = "loongson,ls2k1000-pmc", "loongson,ls2k0500-pmc", "syscon"; + reg = <0x1fe27000 0x58>; + interrupt-parent = <&liointc1>; + interrupts = <11 IRQ_TYPE_LEVEL_LOW>; + loongson,suspend-address = <0x0 0x1c000500>; + + syscon-reboot { + compatible = "syscon-reboot"; + offset = <0x30>; + mask = <0x1>; + }; + + syscon-poweroff { + compatible = "syscon-poweroff"; + regmap = <&pmc>; + offset = <0x14>; + mask = <0x3c00>; + value = <0x3c00>; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/mediatek/mediatek,mt7986-wo-ccif.yaml b/Documentation/devicetree/bindings/soc/mediatek/mediatek,mt7986-wo-ccif.yaml index 8e6ba2ec8a43..3b212f26abc5 100644 --- a/Documentation/devicetree/bindings/soc/mediatek/mediatek,mt7986-wo-ccif.yaml +++ b/Documentation/devicetree/bindings/soc/mediatek/mediatek,mt7986-wo-ccif.yaml @@ -12,7 +12,7 @@ maintainers: description: The MediaTek wo-ccif provides a configuration interface for WED WO - controller used to perfrom offload rx packet processing (e.g. 802.11 + controller used to perform offload rx packet processing (e.g. 802.11 aggregation packet reordering or rx header translation) on MT7986 soc. properties: @@ -20,6 +20,7 @@ properties: items: - enum: - mediatek,mt7986-wo-ccif + - mediatek,mt7988-wo-ccif - const: syscon reg: diff --git a/Documentation/devicetree/bindings/soc/mediatek/mtk-svs.yaml b/Documentation/devicetree/bindings/soc/mediatek/mtk-svs.yaml index f21eb907ee90..7eda63d5682f 100644 --- a/Documentation/devicetree/bindings/soc/mediatek/mtk-svs.yaml +++ b/Documentation/devicetree/bindings/soc/mediatek/mtk-svs.yaml @@ -22,6 +22,7 @@ properties: compatible: enum: - mediatek,mt8183-svs + - mediatek,mt8188-svs - mediatek,mt8192-svs reg: diff --git a/Documentation/devicetree/bindings/soc/microchip/microchip,mpfs-sys-controller.yaml b/Documentation/devicetree/bindings/soc/microchip/microchip,mpfs-sys-controller.yaml index 04ffee3a7c59..365a9fed5914 100644 --- a/Documentation/devicetree/bindings/soc/microchip/microchip,mpfs-sys-controller.yaml +++ b/Documentation/devicetree/bindings/soc/microchip/microchip,mpfs-sys-controller.yaml @@ -12,7 +12,7 @@ maintainers: description: | PolarFire SoC devices include a microcontroller acting as the system controller, which provides "services" to the main processor and to the FPGA fabric. These - services include hardware rng, reprogramming of the FPGA and verfification of the + services include hardware rng, reprogramming of the FPGA and verification of the eNVM contents etc. More information on these services can be found online, at https://onlinedocs.microchip.com/pr/GUID-1409CF11-8EF9-4C24-A94E-70979A688632-en-US-1/index.html diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml index 9dc8e48c8af4..d1c7c2be865f 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml @@ -77,7 +77,7 @@ patternProperties: description: The AOSS side channel also provides the controls for three cooling devices, these are expressed as subnodes of the QMP node. The name of the node is - used to identify the resource and must therefor be "cx", "mx" or "ebi". + used to identify the resource and must therefore be "cx", "mx" or "ebi". properties: "#cooling-cells": diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml index 8a4b7ba3aaf6..7b031ef09669 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml @@ -52,6 +52,8 @@ properties: iommus: maxItems: 1 + dma-coherent: true + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml index 6440dc801387..bceb479f74c5 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml @@ -38,15 +38,9 @@ properties: patternProperties: '^connector@\d$': $ref: /schemas/connector/usb-connector.yaml# - - properties: - reg: true - required: - reg - unevaluatedProperties: false - required: - compatible diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml index 65c02a7fef80..2fa725b8af5d 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml @@ -34,22 +34,27 @@ properties: - qcom,rpm-apq8084 - qcom,rpm-ipq6018 - qcom,rpm-ipq9574 + - qcom,rpm-mdm9607 - qcom,rpm-msm8226 + - qcom,rpm-msm8610 - qcom,rpm-msm8909 - qcom,rpm-msm8916 + - qcom,rpm-msm8917 - qcom,rpm-msm8936 + - qcom,rpm-msm8937 + - qcom,rpm-msm8952 - qcom,rpm-msm8953 - qcom,rpm-msm8974 - qcom,rpm-msm8976 - qcom,rpm-msm8994 - qcom,rpm-msm8996 - qcom,rpm-msm8998 + - qcom,rpm-qcm2290 + - qcom,rpm-qcs404 - qcom,rpm-sdm660 - qcom,rpm-sm6115 - qcom,rpm-sm6125 - qcom,rpm-sm6375 - - qcom,rpm-qcm2290 - - qcom,rpm-qcs404 clock-controller: $ref: /schemas/clock/qcom,rpmcc.yaml# @@ -81,12 +86,18 @@ if: contains: enum: - qcom,rpm-apq8084 + - qcom,rpm-mdm9607 - qcom,rpm-msm8226 + - qcom,rpm-msm8610 + - qcom,rpm-msm8909 - qcom,rpm-msm8916 + - qcom,rpm-msm8917 - qcom,rpm-msm8936 + - qcom,rpm-msm8937 + - qcom,rpm-msm8952 + - qcom,rpm-msm8953 - qcom,rpm-msm8974 - qcom,rpm-msm8976 - - qcom,rpm-msm8953 - qcom,rpm-msm8994 then: properties: @@ -109,10 +120,10 @@ examples: #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/interrupt-controller/irq.h> - smd { - compatible = "qcom,smd"; + remoteproc { + compatible = "qcom,msm8916-rpm-proc", "qcom,rpm-proc"; - rpm { + smd-edge { interrupts = <GIC_SPI 168 IRQ_TYPE_EDGE_RISING>; qcom,ipc = <&apcs 8 0>; qcom,smd-edge = <15>; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smd.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,smd.yaml index 063e595c12f7..4819ce90d206 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,smd.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smd.yaml @@ -15,6 +15,12 @@ description: The Qualcomm Shared Memory Driver is a FIFO based communication channel for sending data between the various subsystems in Qualcomm platforms. + Using the top-level SMD node is deprecated. Instead, the SMD edges are defined + directly below the device node representing the respective remote subsystem + or remote processor. + +deprecated: true + properties: compatible: const: qcom,smd @@ -37,6 +43,7 @@ examples: # The following example represents a smd node, with one edge representing the # "rpm" subsystem. For the "rpm" subsystem we have a device tied to the # "rpm_request" channel. + # NOTE: This is deprecated, represent the RPM using "qcom,rpm-proc" instead. - | #include <dt-bindings/interrupt-controller/arm-gic.h> diff --git a/Documentation/devicetree/bindings/soc/renesas/renesas,rzg2l-sysc.yaml b/Documentation/devicetree/bindings/soc/renesas/renesas,rzg2l-sysc.yaml index 398663d21ab1..4386b2c3fa4d 100644 --- a/Documentation/devicetree/bindings/soc/renesas/renesas,rzg2l-sysc.yaml +++ b/Documentation/devicetree/bindings/soc/renesas/renesas,rzg2l-sysc.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: "http://devicetree.org/schemas/soc/renesas/renesas,rzg2l-sysc.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/soc/renesas/renesas,rzg2l-sysc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Renesas RZ/{G2L,V2L} System Controller (SYSC) @@ -23,6 +23,7 @@ properties: - renesas,r9a07g043-sysc # RZ/G2UL and RZ/Five - renesas,r9a07g044-sysc # RZ/G2{L,LC} - renesas,r9a07g054-sysc # RZ/V2L + - renesas,r9a08g045-sysc # RZ/G3S reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/soc/renesas/renesas.yaml b/Documentation/devicetree/bindings/soc/renesas/renesas.yaml index 53b95f348f8e..16ca3ff7b1ae 100644 --- a/Documentation/devicetree/bindings/soc/renesas/renesas.yaml +++ b/Documentation/devicetree/bindings/soc/renesas/renesas.yaml @@ -302,7 +302,7 @@ properties: - description: R-Car E3 (R8A77990) items: - enum: - - renesas,ebisu # Ebisu (RTP0RC77990SEB0010S) + - renesas,ebisu # Ebisu (RTP0RC77990SEB0010S), Ebisu-4D (RTP0RC77990SEB0020S) - const: renesas,r8a77990 - description: R-Car D3 (R8A77995) @@ -335,6 +335,13 @@ properties: - const: renesas,spider-cpu - const: renesas,r8a779f0 + - description: R-Car S4-8 (R8A779F4) + items: + - enum: + - renesas,s4sk # R-Car S4 Starter Kit board (Y-ASK-RCAR-S4-1000BASE-T#WS12) + - const: renesas,r8a779f4 + - const: renesas,r8a779f0 + - description: R-Car V4H (R8A779G0) items: - enum: @@ -474,6 +481,25 @@ properties: - renesas,rzv2mevk2 # RZ/V2M Eval Board v2.0 - const: renesas,r9a09g011 + - description: RZ/G3S (R9A08G045) + items: + - enum: + - renesas,r9a08g045s33 # PCIe support + - const: renesas,r9a08g045 + + - description: RZ/G3S SMARC Module (SoM) + items: + - const: renesas,rzg3s-smarcm # RZ/G3S SMARC Module (SoM) + - const: renesas,r9a08g045s33 # PCIe support + - const: renesas,r9a08g045 + + - description: RZ SMARC Carrier-II Evaluation Kit + items: + - const: renesas,smarc2-evk # RZ SMARC Carrier-II EVK + - const: renesas,rzg3s-smarcm # RZ/G3S SMARC SoM + - const: renesas,r9a08g045s33 # PCIe support + - const: renesas,r9a08g045 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/soc/starfive/starfive,jh7110-syscon.yaml b/Documentation/devicetree/bindings/soc/starfive/starfive,jh7110-syscon.yaml new file mode 100644 index 000000000000..0039319e91fe --- /dev/null +++ b/Documentation/devicetree/bindings/soc/starfive/starfive,jh7110-syscon.yaml @@ -0,0 +1,93 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/starfive/starfive,jh7110-syscon.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive JH7110 SoC system controller + +maintainers: + - William Qiu <william.qiu@starfivetech.com> + +description: + The StarFive JH7110 SoC system controller provides register information such + as offset, mask and shift to configure related modules such as MMC and PCIe. + +properties: + compatible: + oneOf: + - items: + - const: starfive,jh7110-sys-syscon + - const: syscon + - const: simple-mfd + - items: + - enum: + - starfive,jh7110-aon-syscon + - starfive,jh7110-stg-syscon + - const: syscon + + reg: + maxItems: 1 + + clock-controller: + $ref: /schemas/clock/starfive,jh7110-pll.yaml# + type: object + + "#power-domain-cells": + const: 1 + +required: + - compatible + - reg + +allOf: + - if: + properties: + compatible: + contains: + const: starfive,jh7110-sys-syscon + then: + required: + - clock-controller + else: + properties: + clock-controller: false + - if: + properties: + compatible: + contains: + const: starfive,jh7110-aon-syscon + then: + required: + - "#power-domain-cells" + else: + properties: + "#power-domain-cells": false + +additionalProperties: false + +examples: + - | + syscon@10240000 { + compatible = "starfive,jh7110-stg-syscon", "syscon"; + reg = <0x10240000 0x1000>; + }; + + syscon@13030000 { + compatible = "starfive,jh7110-sys-syscon", "syscon", "simple-mfd"; + reg = <0x13030000 0x1000>; + + clock-controller { + compatible = "starfive,jh7110-pll"; + clocks = <&osc>; + #clock-cells = <1>; + }; + }; + + syscon@17010000 { + compatible = "starfive,jh7110-aon-syscon", "syscon"; + reg = <0x17010000 0x1000>; + #power-domain-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/soc/sti/st,sti-syscon.yaml b/Documentation/devicetree/bindings/soc/sti/st,sti-syscon.yaml new file mode 100644 index 000000000000..5f97d9ff17fb --- /dev/null +++ b/Documentation/devicetree/bindings/soc/sti/st,sti-syscon.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/sti/st,sti-syscon.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics STi platform sysconfig + +maintainers: + - Patrice Chotard <patrice.chotard@foss.st.com> + +description: | + Binding for the various sysconfig nodes used within the STi + platform device-tree to point to some common configuration + registers used by other nodes. + +properties: + compatible: + items: + - enum: + - st,stih407-core-syscfg + - st,stih407-flash-syscfg + - st,stih407-front-syscfg + - st,stih407-lpm-syscfg + - st,stih407-rear-syscfg + - st,stih407-sbc-reg-syscfg + - st,stih407-sbc-syscfg + - const: syscon + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + syscfg_sbc: syscon@9620000 { + compatible = "st,stih407-sbc-syscfg", "syscon"; + reg = <0x9620000 0x1000>; + }; + +... diff --git a/Documentation/devicetree/bindings/soc/tegra/nvidia,nvec.yaml b/Documentation/devicetree/bindings/soc/tegra/nvidia,nvec.yaml new file mode 100644 index 000000000000..d5261ce3a619 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/tegra/nvidia,nvec.yaml @@ -0,0 +1,84 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/tegra/nvidia,nvec.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA compliant embedded controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + const: nvidia,nvec + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 1 + items: + - description: divider clock + - description: fast clock + + clock-names: + minItems: 1 + items: + - const: div-clk + - const: fast-clk + + resets: + items: + - description: module reset + + reset-names: + items: + - const: i2c + + clock-frequency: true + + request-gpios: + description: phandle to the GPIO used for EC request + + slave-addr: + $ref: /schemas/types.yaml#/definitions/uint32 + description: I2C address of the slave controller + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - resets + - reset-names + - clock-frequency + - request-gpios + - slave-addr + +examples: + - | + #include <dt-bindings/clock/tegra20-car.h> + #include <dt-bindings/gpio/tegra-gpio.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + i2c@7000c500 { + compatible = "nvidia,nvec"; + reg = <0x7000c500 0x100>; + interrupts = <GIC_SPI 92 IRQ_TYPE_LEVEL_HIGH>; + clock-frequency = <80000>; + request-gpios = <&gpio TEGRA_GPIO(V, 2) GPIO_ACTIVE_HIGH>; + slave-addr = <138>; + clocks = <&tegra_car TEGRA20_CLK_I2C3>, + <&tegra_car TEGRA20_CLK_PLL_P_OUT3>; + clock-names = "div-clk", "fast-clk"; + resets = <&tegra_car 67>; + reset-names = "i2c"; + }; diff --git a/Documentation/devicetree/bindings/soc/tegra/nvidia,tegra20-ahb.yaml b/Documentation/devicetree/bindings/soc/tegra/nvidia,tegra20-ahb.yaml new file mode 100644 index 000000000000..2f7269a26b8e --- /dev/null +++ b/Documentation/devicetree/bindings/soc/tegra/nvidia,tegra20-ahb.yaml @@ -0,0 +1,40 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/tegra/nvidia,tegra20-ahb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +title: NVIDIA Tegra AHB + +properties: + compatible: + oneOf: + - enum: + - nvidia,tegra20-ahb + - nvidia,tegra30-ahb + - items: + - enum: + - nvidia,tegra114-ahb + - nvidia,tegra124-ahb + - nvidia,tegra210-ahb + - const: nvidia,tegra30-ahb + + reg: + maxItems: 1 + +additionalProperties: false + +required: + - compatible + - reg + +examples: + - | + ahb@6000c004 { + compatible = "nvidia,tegra20-ahb"; + reg = <0x6000c004 0x10c>; /* AHB Arbitration + Gizmo Controller */ + }; diff --git a/Documentation/devicetree/bindings/soc/tegra/nvidia,tegra20-flowctrl.yaml b/Documentation/devicetree/bindings/soc/tegra/nvidia,tegra20-flowctrl.yaml new file mode 100644 index 000000000000..705544b7f98f --- /dev/null +++ b/Documentation/devicetree/bindings/soc/tegra/nvidia,tegra20-flowctrl.yaml @@ -0,0 +1,41 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/tegra/nvidia,tegra20-flowctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra Flow Controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + oneOf: + - enum: + - nvidia,tegra20-flowctrl + - nvidia,tegra30-flowctrl + - nvidia,tegra114-flowctrl + - nvidia,tegra124-flowctrl + - nvidia,tegra210-flowctrl + + - items: + - const: nvidia,tegra132-flowctrl + - const: nvidia,tegra124-flowctrl + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + flow-controller@60007000 { + compatible = "nvidia,tegra20-flowctrl"; + reg = <0x60007000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/soc/tegra/nvidia,tegra20-pmc.yaml b/Documentation/devicetree/bindings/soc/tegra/nvidia,tegra20-pmc.yaml new file mode 100644 index 000000000000..b86f6f53ca95 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/tegra/nvidia,tegra20-pmc.yaml @@ -0,0 +1,416 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/tegra/nvidia,tegra20-pmc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Tegra Power Management Controller (PMC) + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jonathan Hunter <jonathanh@nvidia.com> + +properties: + compatible: + enum: + - nvidia,tegra20-pmc + - nvidia,tegra30-pmc + - nvidia,tegra114-pmc + - nvidia,tegra124-pmc + - nvidia,tegra210-pmc + + reg: + maxItems: 1 + + clock-names: + items: + # Tegra clock of the same name + - const: pclk + # 32 KHz clock input + - const: clk32k_in + + clocks: + maxItems: 2 + + '#clock-cells': + const: 1 + description: | + Tegra PMC has clk_out_1, clk_out_2, and clk_out_3. PMC also has blink + control which allows 32Khz clock output to Tegra blink pad. + + Consumer of PMC clock should specify the desired clock by having the + clock ID in its "clocks" phandle cell with PMC clock provider. See + include/dt-bindings/soc/tegra-pmc.h for the list of Tegra PMC clock IDs. + + '#interrupt-cells': + const: 2 + description: Specifies number of cells needed to encode an interrupt + source. + + interrupt-controller: true + + nvidia,invert-interrupt: + $ref: /schemas/types.yaml#/definitions/flag + description: Inverts the PMU interrupt signal. The PMU is an external Power + Management Unit, whose interrupt output signal is fed into the PMC. This + signal is optionally inverted, and then fed into the ARM GIC. The PMC is + not involved in the detection or handling of this interrupt signal, + merely its inversion. + + nvidia,core-power-req-active-high: + $ref: /schemas/types.yaml#/definitions/flag + description: core power request active-high + + nvidia,sys-clock-req-active-high: + $ref: /schemas/types.yaml#/definitions/flag + description: system clock request active-high + + nvidia,combined-power-req: + $ref: /schemas/types.yaml#/definitions/flag + description: combined power request for CPU and core + + nvidia,cpu-pwr-good-en: + $ref: /schemas/types.yaml#/definitions/flag + description: CPU power good signal from external PMIC to PMC is enabled + + nvidia,suspend-mode: + $ref: /schemas/types.yaml#/definitions/uint32 + description: the suspend mode that the platform should use + oneOf: + - description: LP0, CPU + Core voltage off and DRAM in self-refresh + const: 0 + - description: LP1, CPU voltage off and DRAM in self-refresh + const: 1 + - description: LP2, CPU voltage off + const: 2 + + nvidia,cpu-pwr-good-time: + $ref: /schemas/types.yaml#/definitions/uint32 + description: CPU power good time in microseconds + + nvidia,cpu-pwr-off-time: + $ref: /schemas/types.yaml#/definitions/uint32 + description: CPU power off time in microseconds + + nvidia,core-pwr-good-time: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: core power good time in microseconds + items: + - description: oscillator stable time + - description: power stable time + + nvidia,core-pwr-off-time: + $ref: /schemas/types.yaml#/definitions/uint32 + description: core power off time in microseconds + + nvidia,lp0-vec: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: | + Starting address and length of LP0 vector. The LP0 vector contains the + warm boot code that is executed by AVP when resuming from the LP0 state. + The AVP (Audio-Video Processor) is an ARM7 processor and always being + the first boot processor when chip is power on or resume from deep sleep + mode. When the system is resumed from the deep sleep mode, the warm boot + code will restore some PLLs, clocks and then brings up CPU0 for resuming + the system. + items: + - description: starting address of LP0 vector + - description: length of LP0 vector + + core-supply: + description: phandle to voltage regulator connected to the SoC core power + rail + + core-domain: + type: object + description: The vast majority of hardware blocks of Tegra SoC belong to a + core power domain, which has a dedicated voltage rail that powers the + blocks. + additionalProperties: false + properties: + operating-points-v2: + description: Should contain level, voltages and opp-supported-hw + property. The supported-hw is a bitfield indicating SoC speedo or + process ID mask. + + "#power-domain-cells": + const: 0 + + required: + - operating-points-v2 + - "#power-domain-cells" + + i2c-thermtrip: + type: object + description: On Tegra30, Tegra114 and Tegra124 if i2c-thermtrip subnode + exists, hardware-triggered thermal reset will be enabled. + additionalProperties: false + properties: + nvidia,i2c-controller-id: + $ref: /schemas/types.yaml#/definitions/uint32 + description: ID of I2C controller to send poweroff command to PMU. + Valid values are described in section 9.2.148 "APBDEV_PMC_SCRATCH53_0" + of the Tegra K1 Technical Reference Manual. + + nvidia,bus-addr: + $ref: /schemas/types.yaml#/definitions/uint32 + description: bus address of the PMU on the I2C bus + + nvidia,reg-addr: + $ref: /schemas/types.yaml#/definitions/uint32 + description: PMU I2C register address to issue poweroff command + + nvidia,reg-data: + $ref: /schemas/types.yaml#/definitions/uint32 + description: power-off command to write to PMU + + nvidia,pinmux-id: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Pinmux used by the hardware when issuing power-off command. + Defaults to 0. Valid values are described in section 12.5.2 "Pinmux + Support" of the Tegra4 Technical Reference Manual. + + required: + - nvidia,i2c-controller-id + - nvidia,bus-addr + - nvidia,reg-addr + - nvidia,reg-data + + powergates: + type: object + additionalProperties: false + description: | + This node contains a hierarchy of power domain nodes, which should match + the powergates on the Tegra SoC. Each powergate node represents a power- + domain on the Tegra SoC that can be power-gated by the Tegra PMC. + + Hardware blocks belonging to a power domain should contain "power-domains" + property that is a phandle pointing to corresponding powergate node. + + The name of the powergate node should be one of the below. Note that not + every powergate is applicable to all Tegra devices and the following list + shows which powergates are applicable to which devices. + + Please refer to Tegra TRM for mode details on the powergate nodes to use + for each power-gate block inside Tegra. + + Name Description Devices Applicable + -------------------------------------------------------------- + 3d 3D Graphics Tegra20/114/124/210 + 3d0 3D Graphics 0 Tegra30 + 3d1 3D Graphics 1 Tegra30 + aud Audio Tegra210 + dfd Debug Tegra210 + dis Display A Tegra114/124/210 + disb Display B Tegra114/124/210 + heg 2D Graphics Tegra30/114/124/210 + iram Internal RAM Tegra124/210 + mpe MPEG Encode All + nvdec NVIDIA Video Decode Engine Tegra210 + nvjpg NVIDIA JPEG Engine Tegra210 + pcie PCIE Tegra20/30/124/210 + sata SATA Tegra30/124/210 + sor Display interfaces Tegra124/210 + ve2 Video Encode Engine 2 Tegra210 + venc Video Encode Engine All + vdec Video Decode Engine Tegra20/30/114/124 + vic Video Imaging Compositor Tegra124/210 + xusba USB Partition A Tegra114/124/210 + xusbb USB Partition B Tegra114/124/210 + xusbc USB Partition C Tegra114/124/210 + + patternProperties: + "^[a-z0-9]+$": + type: object + additionalProperties: false + properties: + clocks: + minItems: 1 + maxItems: 10 + + resets: + minItems: 1 + maxItems: 8 + + power-domains: + maxItems: 1 + + '#power-domain-cells': + const: 0 + description: Must be 0. + + required: + - clocks + - resets + - '#power-domain-cells' + + pinmux: + type: object + additionalProperties: + type: object + description: | + This is a pad configuration node. On Tegra SoCs a pad is a set of pins + which are configured as a group. The pin grouping is a fixed attribute + of the hardware. The PMC can be used to set pad power state and + signaling voltage. A pad can be either in active or power down mode. + The support for power state and signaling voltage configuration varies + depending on the pad in question. 3.3V and 1.8V signaling voltages are + supported on pins where software controllable signaling voltage + switching is available. + + The pad configuration state nodes are placed under the pmc node and + they are referred to by the pinctrl client properties. For more + information see: + + Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt + + The pad name should be used as the value of the pins property in pin + configuration nodes. + + The following pads are present on Tegra124 and Tegra132: + + audio, bb, cam, comp, csia, csb, cse, dsi, dsib, dsic, dsid, hdmi, + hsic, hv, lvds, mipi-bias, nand, pex-bias, pex-clk1, pex-clk2, + pex-cntrl, sdmmc1, sdmmc3, sdmmc4, sys_ddc, uart, usb0, usb1, usb2, + usb_bias + + The following pads are present on Tegra210: + + audio, audio-hv, cam, csia, csib, csic, csid, csie, csif, dbg, + debug-nonao, dmic, dp, dsi, dsib, dsic, dsid, emmc, emmc2, gpio, + hdmi, hsic, lvds, mipi-bias, pex-bias, pex-clk1, pex-clk2, pex-cntrl, + sdmmc1, sdmmc3, spi, spi-hv, uart, usb0, usb1, usb2, usb3, usb-bias + additionalProperties: false + properties: + pins: + $ref: /schemas/types.yaml#/definitions/string-array + description: Must contain name of the pad(s) to be configured. + + low-power-enable: + $ref: /schemas/types.yaml#/definitions/flag + description: Configure the pad into power down mode. + + low-power-disable: + $ref: /schemas/types.yaml#/definitions/flag + description: Configure the pad into active mode. + + power-source: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Must contain either TEGRA_IO_PAD_VOLTAGE_1V8 or + TEGRA_IO_PAD_VOLTAGE_3V3 to select between signaling voltages. The + values are defined in: + + include/dt-bindings/pinctrl/pinctrl-tegra-io-pad.h + + Power state can be configured on all Tegra124 and Tegra132 pads. + None of the Tegra124 or Tegra132 pads support signaling voltage + switching. All of the listed Tegra210 pads except pex-cntrl support + power state configuration. Signaling voltage switching is supported + on the following Tegra210 pads: + + audio, audio-hv, cam, dbg, dmic, gpio, pex-cntrl, sdmmc1, sdmmc3, + spi, spi-hv, uart + + required: + - pins + +required: + - compatible + - reg + - clock-names + - clocks + - '#clock-cells' + +allOf: + - if: + properties: + compatible: + contains: + const: nvidia,tegra124-pmc + then: + properties: + pinmux: + additionalProperties: + type: object + properties: + pins: + items: + enum: [ audio, bb, cam, comp, csia, csb, cse, dsi, dsib, + dsic, dsid, hdmi, hsic, hv, lvds, mipi-bias, nand, + pex-bias, pex-clk1, pex-clk2, pex-cntrl, sdmmc1, + sdmmc3, sdmmc4, sys_ddc, uart, usb0, usb1, usb2, + usb_bias ] + + - if: + properties: + compatible: + contains: + const: nvidia,tegra210-pmc + then: + properties: + pinmux: + additionalProperties: + type: object + properties: + pins: + items: + enum: [ audio, audio-hv, cam, csia, csib, csic, csid, csie, + csif, dbg, debug-nonao, dmic, dp, dsi, dsib, dsic, + dsid, emmc, emmc2, gpio, hdmi, hsic, lvds, mipi-bias, + pex-bias, pex-clk1, pex-clk2, pex-cntrl, sdmmc1, + sdmmc3, spi, spi-hv, uart, usb0, usb1, usb2, usb3, + usb-bias ] + +additionalProperties: false + +dependencies: + "nvidia,suspend-mode": ["nvidia,core-pwr-off-time", "nvidia,cpu-pwr-off-time"] + "nvidia,core-pwr-off-time": ["nvidia,core-pwr-good-time"] + "nvidia,cpu-pwr-off-time": ["nvidia,cpu-pwr-good-time"] + +examples: + - | + #include <dt-bindings/clock/tegra210-car.h> + #include <dt-bindings/pinctrl/pinctrl-tegra-io-pad.h> + #include <dt-bindings/soc/tegra-pmc.h> + + pmc@7000e400 { + compatible = "nvidia,tegra210-pmc"; + reg = <0x7000e400 0x400>; + core-supply = <®ulator>; + clocks = <&tegra_car TEGRA210_CLK_PCLK>, <&clk32k_in>; + clock-names = "pclk", "clk32k_in"; + #clock-cells = <1>; + + nvidia,invert-interrupt; + nvidia,suspend-mode = <0>; + nvidia,cpu-pwr-good-time = <0>; + nvidia,cpu-pwr-off-time = <0>; + nvidia,core-pwr-good-time = <4587 3876>; + nvidia,core-pwr-off-time = <39065>; + nvidia,core-power-req-active-high; + nvidia,sys-clock-req-active-high; + + pd_core: core-domain { + operating-points-v2 = <&core_opp_table>; + #power-domain-cells = <0>; + }; + + powergates { + pd_audio: aud { + clocks = <&tegra_car TEGRA210_CLK_APE>, + <&tegra_car TEGRA210_CLK_APB2APE>; + resets = <&tegra_car 198>; + power-domains = <&pd_core>; + #power-domain-cells = <0>; + }; + + pd_xusbss: xusba { + clocks = <&tegra_car TEGRA210_CLK_XUSB_SS>; + resets = <&tegra_car TEGRA210_CLK_XUSB_SS>; + power-domains = <&pd_core>; + #power-domain-cells = <0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml index 22cf9002fee7..158186610c53 100644 --- a/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml +++ b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml @@ -2,8 +2,8 @@ # Copyright (C) 2020 Texas Instruments Incorporated - http://www.ti.com/ %YAML 1.2 --- -$id: "http://devicetree.org/schemas/soc/ti/k3-ringacc.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/soc/ti/k3-ringacc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Texas Instruments K3 NavigatorSS Ring Accelerator @@ -34,18 +34,22 @@ properties: - const: ti,am654-navss-ringacc reg: + minItems: 4 items: - description: real time registers regions - description: fifos registers regions - description: proxy gcfg registers regions - description: proxy target registers regions + - description: configuration registers region reg-names: + minItems: 4 items: - const: rt - const: fifos - const: proxy_gcfg - const: proxy_target + - const: cfg msi-parent: true @@ -80,8 +84,9 @@ examples: reg = <0x0 0x3c000000 0x0 0x400000>, <0x0 0x38000000 0x0 0x400000>, <0x0 0x31120000 0x0 0x100>, - <0x0 0x33000000 0x0 0x40000>; - reg-names = "rt", "fifos", "proxy_gcfg", "proxy_target"; + <0x0 0x33000000 0x0 0x40000>, + <0x0 0x31080000 0x0 0x40000>; + reg-names = "rt", "fifos", "proxy_gcfg", "proxy_target", "cfg"; ti,num-rings = <818>; ti,sci-rm-range-gp-rings = <0x2>; /* GP ring range */ ti,sci = <&dmsc>; diff --git a/Documentation/devicetree/bindings/soc/ti/sci-pm-domain.yaml b/Documentation/devicetree/bindings/soc/ti/sci-pm-domain.yaml index 5df7688a1e1c..a750035d6234 100644 --- a/Documentation/devicetree/bindings/soc/ti/sci-pm-domain.yaml +++ b/Documentation/devicetree/bindings/soc/ti/sci-pm-domain.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/soc/ti/sci-pm-domain.yaml# diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-sound-card.yaml b/Documentation/devicetree/bindings/sound/amlogic,axg-sound-card.yaml index bf1234550343..5db718e4d0e7 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-sound-card.yaml +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-sound-card.yaml @@ -9,6 +9,9 @@ title: Amlogic AXG sound card maintainers: - Jerome Brunet <jbrunet@baylibre.com> +allOf: + - $ref: sound-card-common.yaml# + properties: compatible: const: amlogic,axg-sound-card @@ -17,23 +20,12 @@ properties: $ref: /schemas/types.yaml#/definitions/phandle-array description: list of auxiliary devices - audio-routing: - $ref: /schemas/types.yaml#/definitions/non-unique-string-array - 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. - audio-widgets: $ref: /schemas/types.yaml#/definitions/non-unique-string-array description: A list off component DAPM widget. Each entry is a pair of strings, the first being the widget type, the second being the widget name - model: - $ref: /schemas/types.yaml#/definitions/string - description: User specified audio sound card name - patternProperties: "^dai-link-[0-9]+$": type: object @@ -108,7 +100,6 @@ patternProperties: - sound-dai required: - - model - dai-link-0 unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml b/Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml index b358fd601ed3..d4277d342e69 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml +++ b/Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml @@ -9,6 +9,9 @@ title: Amlogic GX sound card maintainers: - Jerome Brunet <jbrunet@baylibre.com> +allOf: + - $ref: sound-card-common.yaml# + properties: compatible: items: @@ -18,14 +21,6 @@ properties: $ref: /schemas/types.yaml#/definitions/phandle-array description: list of auxiliary devices - audio-routing: - $ref: /schemas/types.yaml#/definitions/non-unique-string-array - minItems: 2 - 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. - audio-widgets: $ref: /schemas/types.yaml#/definitions/non-unique-string-array minItems: 2 @@ -33,10 +28,6 @@ properties: A list off component DAPM widget. Each entry is a pair of strings, the first being the widget type, the second being the widget name - model: - $ref: /schemas/types.yaml#/definitions/string - description: User specified audio sound card name - patternProperties: "^dai-link-[0-9]+$": type: object @@ -86,7 +77,7 @@ required: - model - dai-link-0 -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/audio-graph-card2.yaml b/Documentation/devicetree/bindings/sound/audio-graph-card2.yaml index 3de7b36829da..d3ce4de449d5 100644 --- a/Documentation/devicetree/bindings/sound/audio-graph-card2.yaml +++ b/Documentation/devicetree/bindings/sound/audio-graph-card2.yaml @@ -39,22 +39,4 @@ required: additionalProperties: false -examples: - - | - sound { - compatible = "audio-graph-card2"; - - links = <&cpu_port>; - }; - - cpu { - compatible = "cpu-driver"; - - cpu_port: port { cpu_ep: endpoint { remote-endpoint = <&codec_ep>; }; }; - }; - - codec { - compatible = "codec-driver"; - - port { codec_ep: endpoint { remote-endpoint = <&cpu_ep>; }; }; - }; +... diff --git a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml index fa9f9a853365..60b5e3fd1115 100644 --- a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml +++ b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml @@ -13,19 +13,17 @@ select: false definitions: port-base: - $ref: /schemas/graph.yaml#/$defs/port-base + allOf: + - $ref: /schemas/graph.yaml#/$defs/port-base + - $ref: /schemas/sound/dai-params.yaml# properties: - convert-rate: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-rate - convert-channels: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-channels - convert-sample-format: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-format mclk-fs: $ref: simple-card.yaml#/definitions/mclk-fs endpoint-base: - $ref: /schemas/graph.yaml#/$defs/endpoint-base + allOf: + - $ref: /schemas/graph.yaml#/$defs/endpoint-base + - $ref: /schemas/sound/dai-params.yaml# properties: mclk-fs: $ref: simple-card.yaml#/definitions/mclk-fs @@ -68,12 +66,6 @@ definitions: - pdm - msb - lsb - convert-rate: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-rate - convert-channels: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-channels - convert-sample-format: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-format dai-tdm-slot-num: description: Number of slots in use. diff --git a/Documentation/devicetree/bindings/sound/audio-graph.yaml b/Documentation/devicetree/bindings/sound/audio-graph.yaml index ed31e04ff6a6..71f52f7e55f6 100644 --- a/Documentation/devicetree/bindings/sound/audio-graph.yaml +++ b/Documentation/devicetree/bindings/sound/audio-graph.yaml @@ -9,6 +9,9 @@ title: Audio Graph maintainers: - Kuninori Morimoto <kuninori.morimoto.gx@renesas.com> +allOf: + - $ref: /schemas/sound/dai-params.yaml# + properties: dais: $ref: /schemas/types.yaml#/definitions/phandle-array @@ -30,12 +33,6 @@ properties: widget ("Microphone", "Line", "Headphone", "Speaker"), the second being the machine specific name for the widget. $ref: /schemas/types.yaml#/definitions/non-unique-string-array - convert-rate: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-rate - convert-channels: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-channels - convert-sample-format: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-format pa-gpios: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/audio-iio-aux.yaml b/Documentation/devicetree/bindings/sound/audio-iio-aux.yaml new file mode 100644 index 000000000000..d3cc1ea4a175 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/audio-iio-aux.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/audio-iio-aux.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Audio IIO auxiliary + +maintainers: + - Herve Codina <herve.codina@bootlin.com> + +description: + Auxiliary device based on Industrial I/O device channels + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + const: audio-iio-aux + + io-channels: + description: + Industrial I/O device channels used + + io-channel-names: + description: + Industrial I/O channel names related to io-channels. + These names are used to provides sound controls, widgets and routes names. + + snd-control-invert-range: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: | + A list of 0/1 flags defining whether or not the related channel is + inverted + items: + enum: [0, 1] + default: 0 + description: | + Invert the sound control value compared to the IIO channel raw value. + - 1: The related sound control value is inverted meaning that the + minimum sound control value correspond to the maximum IIO channel + raw value and the maximum sound control value correspond to the + minimum IIO channel raw value. + - 0: The related sound control value is not inverted meaning that the + minimum (resp maximum) sound control value correspond to the + minimum (resp maximum) IIO channel raw value. + +required: + - compatible + - io-channels + - io-channel-names + +unevaluatedProperties: false + +examples: + - | + iio-aux { + compatible = "audio-iio-aux"; + io-channels = <&iio 0>, <&iio 1>, <&iio 2>, <&iio 3>; + io-channel-names = "CH0", "CH1", "CH2", "CH3"; + /* Invert CH1 and CH2 */ + snd-control-invert-range = <0 1 1 0>; + }; diff --git a/Documentation/devicetree/bindings/sound/awinic,aw87390.yaml b/Documentation/devicetree/bindings/sound/awinic,aw87390.yaml new file mode 100644 index 000000000000..ba9d8767c5d5 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/awinic,aw87390.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/awinic,aw87390.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Awinic Aw87390 Audio Amplifier + +maintainers: + - Weidong Wang <wangweidong.a@awinic.com> + +description: + The awinic aw87390 is specifically designed to improve + the musical output dynamic range, enhance the overall + sound quallity, which is a new high efficiency, low + noise, constant large volume, 6th Smart K audio amplifier. + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + const: awinic,aw87390 + + reg: + maxItems: 1 + + "#sound-dai-cells": + const: 0 + + awinic,audio-channel: + description: + It is used to distinguish multiple PA devices, so that different + configurations can be loaded to different PA devices + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 7 + +required: + - compatible + - reg + - "#sound-dai-cells" + - awinic,audio-channel + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + audio-codec@58 { + compatible = "awinic,aw87390"; + reg = <0x58>; + #sound-dai-cells = <0>; + awinic,audio-channel = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/awinic,aw88395.yaml b/Documentation/devicetree/bindings/sound/awinic,aw88395.yaml index 35eef7d818a2..ac5f2e0f42cb 100644 --- a/Documentation/devicetree/bindings/sound/awinic,aw88395.yaml +++ b/Documentation/devicetree/bindings/sound/awinic,aw88395.yaml @@ -14,12 +14,12 @@ description: digital Smart K audio amplifier with an integrated 10.25V smart boost convert. -allOf: - - $ref: dai-common.yaml# - properties: compatible: - const: awinic,aw88395 + enum: + - awinic,aw88395 + - awinic,aw88261 + - awinic,aw88399 reg: maxItems: 1 @@ -30,11 +30,36 @@ properties: reset-gpios: maxItems: 1 + awinic,audio-channel: + description: + It is used to distinguish multiple PA devices, so that different + configurations can be loaded to different PA devices + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 7 + + awinic,sync-flag: + description: + Flag bit used to keep the phase synchronized in the case of multiple PA + $ref: /schemas/types.yaml#/definitions/flag + required: - compatible - reg - '#sound-dai-cells' - - reset-gpios + - awinic,audio-channel + +allOf: + - $ref: dai-common.yaml# + - if: + properties: + compatible: + contains: + enum: + - awinic,aw88261 + then: + properties: + reset-gpios: false unevaluatedProperties: false @@ -49,5 +74,7 @@ examples: reg = <0x34>; #sound-dai-cells = <0>; reset-gpios = <&gpio 10 GPIO_ACTIVE_LOW>; + awinic,audio-channel = <0>; + awinic,sync-flag; }; }; diff --git a/Documentation/devicetree/bindings/sound/axentia,tse850-pcm5142.txt b/Documentation/devicetree/bindings/sound/axentia,tse850-pcm5142.txt index 9d049d4bfd58..b6cc5f6f78c2 100644 --- a/Documentation/devicetree/bindings/sound/axentia,tse850-pcm5142.txt +++ b/Documentation/devicetree/bindings/sound/axentia,tse850-pcm5142.txt @@ -29,7 +29,7 @@ The schematics explaining the gpios are as follows: IN2 +---o--+------------+--o---+ OUT2 loop2 relays -The 'loop1' gpio pin controlls two relays, which are either in loop position, +The 'loop1' gpio pin controls two relays, which are either in loop position, meaning that input and output are directly connected, or they are in mixer position, meaning that the signal is passed through the 'Sum' mixer. Similarly for 'loop2'. diff --git a/Documentation/devicetree/bindings/sound/cirrus,cs42l43.yaml b/Documentation/devicetree/bindings/sound/cirrus,cs42l43.yaml new file mode 100644 index 000000000000..7f9d8c7a635a --- /dev/null +++ b/Documentation/devicetree/bindings/sound/cirrus,cs42l43.yaml @@ -0,0 +1,313 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/cirrus,cs42l43.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cirrus Logic CS42L43 Audio CODEC + +maintainers: + - patches@opensource.cirrus.com + +description: | + The CS42L43 is an audio CODEC with integrated MIPI SoundWire interface + (Version 1.2.1 compliant), I2C, SPI, and I2S/TDM interfaces designed + for portable applications. It provides a high dynamic range, stereo + DAC for headphone output, two integrated Class D amplifiers for + loudspeakers, and two ADCs for wired headset microphone input or + stereo line input. PDM inputs are provided for digital microphones. + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + enum: + - cirrus,cs42l43 + + reg: + maxItems: 1 + + vdd-p-supply: + description: + Power supply for the high voltage interface. + + vdd-a-supply: + description: + Power supply for internal analog circuits. + + vdd-d-supply: + description: + Power supply for internal digital circuits. Can be internally supplied. + + vdd-io-supply: + description: + Power supply for external interface and internal digital logic. + + vdd-cp-supply: + description: + Power supply for the amplifier 3 and 4 charge pump. + + vdd-amp-supply: + description: + Power supply for amplifier 1 and 2. + + reset-gpios: + maxItems: 1 + + interrupt-controller: true + + "#interrupt-cells": + const: 2 + + interrupts: + maxItems: 1 + + "#sound-dai-cells": + const: 1 + + clocks: + items: + - description: Synchronous audio clock provided on mclk_in. + + clock-names: + const: mclk + + cirrus,bias-low: + type: boolean + description: + Select a 1.8V headset micbias rather than 2.8V. + + cirrus,bias-sense-microamp: + description: + Current at which the headset micbias sense clamp will engage, 0 to + disable. + enum: [ 0, 14, 24, 43, 52, 61, 71, 90, 99 ] + default: 14 + + cirrus,bias-ramp-ms: + description: + Time in milliseconds the hardware allows for the headset micbias to + ramp up. + enum: [ 10, 40, 90, 170 ] + default: 170 + + cirrus,detect-us: + description: + Time in microseconds the type detection will run for. Long values will + cause more audible effects, but give more accurate detection. + enum: [ 20, 100, 1000, 10000, 50000, 75000, 100000, 200000 ] + default: 1000 + + cirrus,button-automute: + type: boolean + description: + Enable the hardware automuting of decimator 1 when a headset button is + pressed. + + cirrus,buttons-ohms: + description: + Impedance in Ohms for each headset button, these should be listed in + ascending order. + minItems: 1 + maxItems: 6 + + cirrus,tip-debounce-ms: + description: + Software debounce on tip sense triggering in milliseconds. + default: 0 + + cirrus,tip-invert: + type: boolean + description: + Indicates tip detect polarity, inverted implies open-circuit whilst the + jack is inserted. + + cirrus,tip-disable-pullup: + type: boolean + description: + Indicates if the internal pullup on the tip detect should be disabled. + + cirrus,tip-fall-db-ms: + description: + Time in milliseconds a falling edge on the tip detect should be hardware + debounced for. Note the falling edge is considered after the invert. + enum: [ 0, 125, 250, 500, 750, 1000, 1250, 1500 ] + default: 500 + + cirrus,tip-rise-db-ms: + description: + Time in milliseconds a rising edge on the tip detect should be hardware + debounced for. Note the rising edge is considered after the invert. + enum: [ 0, 125, 250, 500, 750, 1000, 1250, 1500 ] + default: 500 + + cirrus,use-ring-sense: + type: boolean + description: + Indicates if the ring sense should be used. + + cirrus,ring-invert: + type: boolean + description: + Indicates ring detect polarity, inverted implies open-circuit whilst the + jack is inserted. + + cirrus,ring-disable-pullup: + type: boolean + description: + Indicates if the internal pullup on the ring detect should be disabled. + + cirrus,ring-fall-db-ms: + description: + Time in milliseconds a falling edge on the ring detect should be hardware + debounced for. Note the falling edge is considered after the invert. + enum: [ 0, 125, 250, 500, 750, 1000, 1250, 1500 ] + default: 500 + + cirrus,ring-rise-db-ms: + description: + Time in milliseconds a rising edge on the ring detect should be hardware + debounced for. Note the rising edge is considered after the invert. + enum: [ 0, 125, 250, 500, 750, 1000, 1250, 1500 ] + default: 500 + + pinctrl: + type: object + $ref: /schemas/pinctrl/pinctrl.yaml# + additionalProperties: false + + properties: + gpio-controller: true + + "#gpio-cells": + const: 2 + + gpio-ranges: + items: + - description: A phandle to the CODEC pinctrl node + minimum: 0 + - const: 0 + - const: 0 + - const: 3 + + patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/cirrus-cs42l43-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/cirrus-cs42l43-state" + additionalProperties: false + + spi: + type: object + $ref: /schemas/spi/spi-controller.yaml# + unevaluatedProperties: false + +$defs: + cirrus-cs42l43-state: + type: object + + allOf: + - $ref: /schemas/pinctrl/pincfg-node.yaml# + - $ref: /schemas/pinctrl/pinmux-node.yaml# + + oneOf: + - required: [ groups ] + - required: [ pins ] + + additionalProperties: false + + properties: + groups: + enum: [ gpio1, gpio2, gpio3, asp, pdmout2, pdmout1, i2c, spi ] + + pins: + enum: [ gpio1, gpio2, gpio3, + asp_dout, asp_fsync, asp_bclk, + pdmout2_clk, pdmout2_data, pdmout1_clk, pdmout1_data, + i2c_sda, i2c_scl, + spi_miso, spi_sck, spi_ssb ] + + function: + enum: [ gpio, spdif, irq, mic-shutter, spk-shutter ] + + drive-strength: + description: Set drive strength in mA + enum: [ 1, 2, 4, 8, 9, 10, 12, 16 ] + + input-debounce: + description: Set input debounce in uS + enum: [ 0, 85 ] + +required: + - compatible + - reg + - vdd-p-supply + - vdd-a-supply + - vdd-io-supply + - vdd-cp-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + cs42l43: codec@1a { + compatible = "cirrus,cs42l43"; + reg = <0x1a>; + + vdd-p-supply = <&vdd5v0>; + vdd-a-supply = <&vdd1v8>; + vdd-io-supply = <&vdd1v8>; + vdd-cp-supply = <&vdd1v8>; + vdd-amp-supply = <&vdd5v0>; + + reset-gpios = <&gpio 0>; + + interrupt-controller; + #interrupt-cells = <2>; + interrupt-parent = <&gpio>; + interrupts = <56 IRQ_TYPE_LEVEL_LOW>; + + #sound-dai-cells = <1>; + + clocks = <&clks 0>; + clock-names = "mclk"; + + cs42l43_pins: pinctrl { + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&cs42l43_pins 0 0 3>; + + pinctrl-names = "default"; + pinctrl-0 = <&pinsettings>; + + pinsettings: default-state { + shutter-pins { + groups = "gpio3"; + function = "mic-shutter"; + }; + }; + }; + + spi { + #address-cells = <1>; + #size-cells = <0>; + + cs-gpios = <&cs42l43_pins 1 0>; + + sensor@0 { + compatible = "bosch,bme680"; + reg = <0>; + spi-max-frequency = <1400000>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/cs35l35.txt b/Documentation/devicetree/bindings/sound/cs35l35.txt index 7915897f8a81..e84f30c5c39b 100644 --- a/Documentation/devicetree/bindings/sound/cs35l35.txt +++ b/Documentation/devicetree/bindings/sound/cs35l35.txt @@ -110,7 +110,7 @@ Optional Monitor Signal Format sub-node: See Sections 4.8.2 through 4.8.4 Serial-Port Control in the Datasheet - -cirrus,monitor-signal-format : Sub-node for the Monitor Signaling Formating + -cirrus,monitor-signal-format : Sub-node for the Monitor Signaling Formatting on the I2S Port. Each of the 3 8 bit values in the array contain the settings for depth, location, and frame. diff --git a/Documentation/devicetree/bindings/sound/cs35l36.txt b/Documentation/devicetree/bindings/sound/cs35l36.txt index 912bd162b477..d34117b8558e 100644 --- a/Documentation/devicetree/bindings/sound/cs35l36.txt +++ b/Documentation/devicetree/bindings/sound/cs35l36.txt @@ -33,7 +33,7 @@ Optional properties: one amplifier in the system. If more than one it is best to Hi-Z the ASP port to prevent bus contention on the output signal - - cirrus,boost-ctl-select : Boost conerter control source selection. + - cirrus,boost-ctl-select : Boost converter control source selection. Selects the source of the BST_CTL target VBST voltage for the boost converter to generate. 0x00 - Control Port Value diff --git a/Documentation/devicetree/bindings/sound/cs53l30.txt b/Documentation/devicetree/bindings/sound/cs53l30.txt index 4dbfb8274cd9..dc256adb35a2 100644 --- a/Documentation/devicetree/bindings/sound/cs53l30.txt +++ b/Documentation/devicetree/bindings/sound/cs53l30.txt @@ -30,7 +30,7 @@ Optional properties: * frame using two different ways: * 1) Normal I2S mode on two data pins -- each SDOUT * carries 2-channel data in the same time. - * 2) TDM mode on one signle data pin -- SDOUT1 carries + * 2) TDM mode on one single data pin -- SDOUT1 carries * 4-channel data per frame. Example: diff --git a/Documentation/devicetree/bindings/sound/dai-params.yaml b/Documentation/devicetree/bindings/sound/dai-params.yaml index f5fb71f9b603..cd8508175564 100644 --- a/Documentation/devicetree/bindings/sound/dai-params.yaml +++ b/Documentation/devicetree/bindings/sound/dai-params.yaml @@ -11,15 +11,14 @@ maintainers: select: false -$defs: - - dai-channels: +properties: + convert-channels: description: Number of audio channels used by DAI $ref: /schemas/types.yaml#/definitions/uint32 minimum: 1 maximum: 32 - dai-sample-format: + convert-sample-format: description: Audio sample format used by DAI $ref: /schemas/types.yaml#/definitions/string enum: @@ -29,12 +28,10 @@ $defs: - s24_3le - s32_le - dai-sample-rate: + convert-rate: description: Audio sample rate used by DAI $ref: /schemas/types.yaml#/definitions/uint32 minimum: 8000 maximum: 192000 -properties: {} - additionalProperties: true diff --git a/Documentation/devicetree/bindings/sound/dialog,da7219.yaml b/Documentation/devicetree/bindings/sound/dialog,da7219.yaml index bb5af48ab1e1..19137abdba3e 100644 --- a/Documentation/devicetree/bindings/sound/dialog,da7219.yaml +++ b/Documentation/devicetree/bindings/sound/dialog,da7219.yaml @@ -74,7 +74,7 @@ properties: $ref: /schemas/types.yaml#/definitions/uint32 dlg,mic-amp-in-sel: - enum: ["diff", "se_p", "se_n"] + enum: [diff, se_p, se_n] description: Mic input source type. @@ -89,6 +89,7 @@ properties: da7219_aad: type: object + additionalProperties: false description: Configuration of advanced accessory detection. properties: @@ -123,7 +124,7 @@ properties: $ref: /schemas/types.yaml#/definitions/uint32 dlg,jack-ins-det-pty: - enum: ["low", "high"] + enum: [low, high] description: Polarity for jack insertion detection. $ref: /schemas/types.yaml#/definitions/string diff --git a/Documentation/devicetree/bindings/sound/fsl,easrc.yaml b/Documentation/devicetree/bindings/sound/fsl,easrc.yaml index bdde68a1059c..a680d7aff237 100644 --- a/Documentation/devicetree/bindings/sound/fsl,easrc.yaml +++ b/Documentation/devicetree/bindings/sound/fsl,easrc.yaml @@ -14,7 +14,13 @@ properties: pattern: "^easrc@.*" compatible: - const: fsl,imx8mn-easrc + oneOf: + - enum: + - fsl,imx8mn-easrc + - items: + - enum: + - fsl,imx8mp-easrc + - const: fsl,imx8mn-easrc reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/fsl,esai.txt b/Documentation/devicetree/bindings/sound/fsl,esai.txt index 0a2480aeecf0..90112ca1ff42 100644 --- a/Documentation/devicetree/bindings/sound/fsl,esai.txt +++ b/Documentation/devicetree/bindings/sound/fsl,esai.txt @@ -44,7 +44,7 @@ Required properties: - fsl,esai-synchronous: This is a boolean property. If present, indicating that ESAI would work in the synchronous mode, which means all the settings for Receiving would be - duplicated from Transmition related registers. + duplicated from Transmission related registers. Optional properties: diff --git a/Documentation/devicetree/bindings/sound/fsl,micfil.yaml b/Documentation/devicetree/bindings/sound/fsl,micfil.yaml index 4b99a18c79a0..b7e605835639 100644 --- a/Documentation/devicetree/bindings/sound/fsl,micfil.yaml +++ b/Documentation/devicetree/bindings/sound/fsl,micfil.yaml @@ -56,6 +56,9 @@ properties: - const: clkext3 minItems: 2 + "#sound-dai-cells": + const: 0 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/sound/fsl,qmc-audio.yaml b/Documentation/devicetree/bindings/sound/fsl,qmc-audio.yaml index ff5cd9241941..b522ed7dcc51 100644 --- a/Documentation/devicetree/bindings/sound/fsl,qmc-audio.yaml +++ b/Documentation/devicetree/bindings/sound/fsl,qmc-audio.yaml @@ -33,6 +33,7 @@ patternProperties: description: A DAI managed by this controller type: object + additionalProperties: false properties: reg: diff --git a/Documentation/devicetree/bindings/sound/fsl,rpmsg.yaml b/Documentation/devicetree/bindings/sound/fsl,rpmsg.yaml index e847611a85f7..188f38baddec 100644 --- a/Documentation/devicetree/bindings/sound/fsl,rpmsg.yaml +++ b/Documentation/devicetree/bindings/sound/fsl,rpmsg.yaml @@ -17,6 +17,9 @@ description: | such as SAI, MICFIL, .etc through building rpmsg channels between Cortex-A and Cortex-M. +allOf: + - $ref: sound-card-common.yaml# + properties: compatible: enum: @@ -25,10 +28,7 @@ properties: - fsl,imx8mm-rpmsg-audio - fsl,imx8mp-rpmsg-audio - fsl,imx8ulp-rpmsg-audio - - model: - $ref: /schemas/types.yaml#/definitions/string - description: User specified audio sound card name + - fsl,imx93-rpmsg-audio clocks: items: @@ -65,13 +65,6 @@ properties: $ref: /schemas/types.yaml#/definitions/phandle description: The phandle to a node of audio codec - audio-routing: - $ref: /schemas/types.yaml#/definitions/non-unique-string-array - 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. - fsl,enable-lpa: $ref: /schemas/types.yaml#/definitions/flag description: enable low power audio path. @@ -100,9 +93,8 @@ properties: required: - compatible - - model -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/google,sc7180-trogdor.yaml b/Documentation/devicetree/bindings/sound/google,sc7180-trogdor.yaml index 666a95ac22c8..bac940553965 100644 --- a/Documentation/devicetree/bindings/sound/google,sc7180-trogdor.yaml +++ b/Documentation/devicetree/bindings/sound/google,sc7180-trogdor.yaml @@ -7,29 +7,21 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Google SC7180-Trogdor ASoC sound card driver maintainers: - - Rohit kumar <rohitkr@codeaurora.org> + - Rohit kumar <quic_rohkumar@quicinc.com> - Cheng-Yi Chiang <cychiang@chromium.org> description: This binding describes the SC7180 sound card which uses LPASS for audio. +allOf: + - $ref: sound-card-common.yaml# + properties: compatible: enum: - google,sc7180-trogdor - google,sc7180-coachz - audio-routing: - $ref: /schemas/types.yaml#/definitions/non-unique-string-array - 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. - - model: - $ref: /schemas/types.yaml#/definitions/string - description: User specified audio sound card name - "#address-cells": const: 1 @@ -86,11 +78,10 @@ patternProperties: required: - compatible - - model - "#address-cells" - "#size-cells" -additionalProperties: false +unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/sound/google,sc7280-herobrine.yaml b/Documentation/devicetree/bindings/sound/google,sc7280-herobrine.yaml index 0b1a01a4c14e..ec4b6e547ca6 100644 --- a/Documentation/devicetree/bindings/sound/google,sc7280-herobrine.yaml +++ b/Documentation/devicetree/bindings/sound/google,sc7280-herobrine.yaml @@ -13,22 +13,14 @@ maintainers: description: This binding describes the SC7280 sound card which uses LPASS for audio. +allOf: + - $ref: sound-card-common.yaml# + properties: compatible: enum: - google,sc7280-herobrine - audio-routing: - $ref: /schemas/types.yaml#/definitions/non-unique-string-array - 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. - - model: - $ref: /schemas/types.yaml#/definitions/string - description: User specified audio sound card name - "#address-cells": const: 1 @@ -97,11 +89,10 @@ patternProperties: required: - compatible - - model - "#address-cells" - "#size-cells" -additionalProperties: false +unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/sound/gtm601.txt b/Documentation/devicetree/bindings/sound/gtm601.txt deleted file mode 100644 index efa32a486c4a..000000000000 --- a/Documentation/devicetree/bindings/sound/gtm601.txt +++ /dev/null @@ -1,19 +0,0 @@ -GTM601 UMTS modem audio interface CODEC - -This device has no configuration interface. The sample rate and channels are -based on the compatible string - "option,gtm601" = 8kHz mono - "broadmobi,bm818" = 48KHz stereo - -Required properties: - - - compatible : one of - "option,gtm601" - "broadmobi,bm818" - - -Example: - -codec: gtm601_codec { - compatible = "option,gtm601"; -}; diff --git a/Documentation/devicetree/bindings/sound/imx-audio-card.yaml b/Documentation/devicetree/bindings/sound/imx-audio-card.yaml index b6f5d486600e..f7ad5ea2491e 100644 --- a/Documentation/devicetree/bindings/sound/imx-audio-card.yaml +++ b/Documentation/devicetree/bindings/sound/imx-audio-card.yaml @@ -9,23 +9,14 @@ title: NXP i.MX audio sound card. maintainers: - Shengjiu Wang <shengjiu.wang@nxp.com> +allOf: + - $ref: sound-card-common.yaml# + properties: compatible: enum: - fsl,imx-audio-card - model: - $ref: /schemas/types.yaml#/definitions/string - description: User specified audio sound card name - - audio-routing: - $ref: /schemas/types.yaml#/definitions/non-unique-string-array - 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. Valid names could be power supplies, - MicBias of codec and the jacks on the board. - patternProperties: ".*-dai-link$": description: @@ -84,9 +75,8 @@ patternProperties: required: - compatible - - model -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/max9892x.txt b/Documentation/devicetree/bindings/sound/max9892x.txt deleted file mode 100644 index 98cb9ba5b328..000000000000 --- a/Documentation/devicetree/bindings/sound/max9892x.txt +++ /dev/null @@ -1,44 +0,0 @@ -Maxim Integrated MAX98925/MAX98926/MAX98927 Speaker Amplifier - -This device supports I2C. - -Required properties: - - - compatible : should be one of the following - - "maxim,max98925" - - "maxim,max98926" - - "maxim,max98927" - - - vmon-slot-no : slot number used to send voltage information - or in inteleave mode this will be used as - interleave slot. - MAX98925/MAX98926 slot range : 0 ~ 30, Default : 0 - MAX98927 slot range : 0 ~ 15, Default : 0 - - - imon-slot-no : slot number used to send current information - MAX98925/MAX98926 slot range : 0 ~ 30, Default : 0 - MAX98927 slot range : 0 ~ 15, Default : 0 - - - interleave-mode : When using two MAX9892X in a system it is - possible to create ADC data that that will - overflow the frame size. Digital Audio Interleave - mode provides a means to output VMON and IMON data - from two devices on a single DOUT line when running - smaller frames sizes such as 32 BCLKS per LRCLK or - 48 BCLKS per LRCLK. - Range : 0 (off), 1 (on), Default : 0 - - - reg : the I2C address of the device for I2C - -Optional properties: - - reset-gpios : GPIO to reset the device - -Example: - -codec: max98927@3a { - compatible = "maxim,max98927"; - vmon-slot-no = <0>; - imon-slot-no = <1>; - interleave-mode = <0>; - reg = <0x3a>; -}; diff --git a/Documentation/devicetree/bindings/sound/maxim,max98925.yaml b/Documentation/devicetree/bindings/sound/maxim,max98925.yaml new file mode 100644 index 000000000000..32fd86204a7a --- /dev/null +++ b/Documentation/devicetree/bindings/sound/maxim,max98925.yaml @@ -0,0 +1,98 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/maxim,max98925.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated MAX98925/MAX98926/MAX98927 speaker amplifier + +maintainers: + - Ryan Lee <ryans.lee@maximintegrated.com> + +properties: + compatible: + enum: + - maxim,max98925 + - maxim,max98926 + - maxim,max98927 + + reg: + maxItems: 1 + + reset-gpios: + maxItems: 1 + + '#sound-dai-cells': + const: 0 + + vmon-slot-no: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 30 + default: 0 + description: + Slot number used to send voltage information or in inteleave mode this + will be used as interleave slot. + + imon-slot-no: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 30 + default: 0 + description: + Slot number used to send current information. + + maxim,interleave-mode: + type: boolean + description: + When using two MAX9892X in a system it is possible to create ADC data + that will overflow the frame size. When enabled, the Digital Audio + Interleave mode provides a means to output VMON and IMON data from two + devices on a single DOUT line when running smaller frames sizes such as + 32 BCLKS per LRCLK or 48 BCLKS per LRCLK. + +required: + - compatible + - reg + +allOf: + - $ref: dai-common.yaml# + - if: + properties: + compatible: + contains: + enum: + - maxim,max98927 + then: + properties: + vmon-slot-no: + minimum: 0 + maximum: 15 + + imon-slot-no: + minimum: 0 + maximum: 15 + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + #include <dt-bindings/gpio/gpio.h> + audio-codec@3a { + compatible = "maxim,max98927"; + reg = <0x3a>; + #sound-dai-cells = <0>; + + pinctrl-0 = <&speaker_default>; + pinctrl-names = "default"; + + reset-gpios = <&tlmm 69 GPIO_ACTIVE_LOW>; + + vmon-slot-no = <1>; + imon-slot-no = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/mediatek,mt7986-afe.yaml b/Documentation/devicetree/bindings/sound/mediatek,mt7986-afe.yaml new file mode 100644 index 000000000000..398efdfe00f5 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mediatek,mt7986-afe.yaml @@ -0,0 +1,160 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/mediatek,mt7986-afe.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek AFE PCM controller for MT7986 + +maintainers: + - Maso Huang <maso.huang@mediatek.com> + +properties: + compatible: + oneOf: + - const: mediatek,mt7986-afe + - items: + - enum: + - mediatek,mt7981-afe + - mediatek,mt7988-afe + - const: mediatek,mt7986-afe + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 5 + items: + - description: audio bus clock + - description: audio 26M clock + - description: audio intbus clock + - description: audio hopping clock + - description: audio pll clock + - description: mux for pcm_mck + - description: audio i2s/pcm mck + + clock-names: + minItems: 5 + items: + - const: bus_ck + - const: 26m_ck + - const: l_ck + - const: aud_ck + - const: eg2_ck + - const: sel + - const: i2s_m + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +allOf: + - if: + properties: + compatible: + contains: + const: mediatek,mt7986-afe + then: + properties: + clocks: + items: + - description: audio bus clock + - description: audio 26M clock + - description: audio intbus clock + - description: audio hopping clock + - description: audio pll clock + clock-names: + items: + - const: bus_ck + - const: 26m_ck + - const: l_ck + - const: aud_ck + - const: eg2_ck + + - if: + properties: + compatible: + contains: + const: mediatek,mt7981-afe + then: + properties: + clocks: + items: + - description: audio bus clock + - description: audio 26M clock + - description: audio intbus clock + - description: audio hopping clock + - description: audio pll clock + - description: mux for pcm_mck + clock-names: + items: + - const: bus_ck + - const: 26m_ck + - const: l_ck + - const: aud_ck + - const: eg2_ck + - const: sel + + - if: + properties: + compatible: + contains: + const: mediatek,mt7988-afe + then: + properties: + clocks: + items: + - description: audio bus clock + - description: audio 26M clock + - description: audio intbus clock + - description: audio hopping clock + - description: audio pll clock + - description: mux for pcm_mck + - description: audio i2s/pcm mck + clock-names: + items: + - const: bus_ck + - const: 26m_ck + - const: l_ck + - const: aud_ck + - const: eg2_ck + - const: sel + - const: i2s_m + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/clock/mt7986-clk.h> + + afe@11210000 { + compatible = "mediatek,mt7986-afe"; + reg = <0x11210000 0x9000>; + interrupts = <GIC_SPI 106 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&infracfg_ao CLK_INFRA_AUD_BUS_CK>, + <&infracfg_ao CLK_INFRA_AUD_26M_CK>, + <&infracfg_ao CLK_INFRA_AUD_L_CK>, + <&infracfg_ao CLK_INFRA_AUD_AUD_CK>, + <&infracfg_ao CLK_INFRA_AUD_EG2_CK>; + clock-names = "bus_ck", + "26m_ck", + "l_ck", + "aud_ck", + "eg2_ck"; + assigned-clocks = <&topckgen CLK_TOP_A1SYS_SEL>, + <&topckgen CLK_TOP_AUD_L_SEL>, + <&topckgen CLK_TOP_A_TUNER_SEL>; + assigned-clock-parents = <&topckgen CLK_TOP_APLL2_D4>, + <&apmixedsys CLK_APMIXED_APLL2>, + <&topckgen CLK_TOP_APLL2_D4>; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/mediatek,mt7986-wm8960.yaml b/Documentation/devicetree/bindings/sound/mediatek,mt7986-wm8960.yaml new file mode 100644 index 000000000000..09247ceea3f7 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mediatek,mt7986-wm8960.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/mediatek,mt7986-wm8960.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek MT7986 sound card with WM8960 codec + +maintainers: + - Maso Huang <maso.huang@mediatek.com> + +allOf: + - $ref: sound-card-common.yaml# + +properties: + compatible: + const: mediatek,mt7986-wm8960-sound + + platform: + type: object + additionalProperties: false + properties: + sound-dai: + description: The phandle of MT7986 platform. + maxItems: 1 + required: + - sound-dai + + codec: + type: object + additionalProperties: false + properties: + sound-dai: + description: The phandle of wm8960 codec. + maxItems: 1 + required: + - sound-dai + +unevaluatedProperties: false + +required: + - compatible + - audio-routing + - platform + - codec + +examples: + - | + sound { + compatible = "mediatek,mt7986-wm8960-sound"; + model = "mt7986-wm8960"; + audio-routing = + "Headphone", "HP_L", + "Headphone", "HP_R", + "LINPUT1", "AMIC", + "RINPUT1", "AMIC"; + + platform { + sound-dai = <&afe>; + }; + + codec { + sound-dai = <&wm8960>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/mediatek,mt8188-afe.yaml b/Documentation/devicetree/bindings/sound/mediatek,mt8188-afe.yaml index e6cb711ece77..77af276ed2a2 100644 --- a/Documentation/devicetree/bindings/sound/mediatek,mt8188-afe.yaml +++ b/Documentation/devicetree/bindings/sound/mediatek,mt8188-afe.yaml @@ -25,6 +25,12 @@ properties: reset-names: const: audiosys + memory-region: + maxItems: 1 + description: | + Shared memory region for AFE memif. A "shared-dma-pool". + See dtschema reserved-memory/shared-dma-pool.yaml for details. + mediatek,topckgen: $ref: /schemas/types.yaml#/definitions/phandle description: The phandle of the mediatek topckgen controller @@ -135,7 +141,7 @@ patternProperties: maxItems: 16 description: This is a list of channel IDs which should be disabled. - By default, all data received from ETDM pins will be outputed to + By default, all data received from ETDM pins will be outputted to memory. etdm in supports disable_out in direct mode(w/o interconn), so user can disable the specified channels by the property. uniqueItems: true @@ -176,6 +182,7 @@ examples: interrupts = <GIC_SPI 822 IRQ_TYPE_LEVEL_HIGH 0>; resets = <&watchdog 14>; reset-names = "audiosys"; + memory-region = <&snd_dma_mem_reserved>; mediatek,topckgen = <&topckgen>; mediatek,infracfg = <&infracfg_ao>; power-domains = <&spm 13>; //MT8188_POWER_DOMAIN_AUDIO diff --git a/Documentation/devicetree/bindings/sound/mediatek,mt8188-mt6359.yaml b/Documentation/devicetree/bindings/sound/mediatek,mt8188-mt6359.yaml index 05e532b5d50a..4c8c95057ef7 100644 --- a/Documentation/devicetree/bindings/sound/mediatek,mt8188-mt6359.yaml +++ b/Documentation/devicetree/bindings/sound/mediatek,mt8188-mt6359.yaml @@ -9,23 +9,20 @@ title: MediaTek MT8188 ASoC sound card maintainers: - Trevor Wu <trevor.wu@mediatek.com> +allOf: + - $ref: sound-card-common.yaml# + properties: compatible: enum: - mediatek,mt8188-mt6359-evb - mediatek,mt8188-nau8825 - - model: - $ref: /schemas/types.yaml#/definitions/string - description: User specified audio sound card name + - mediatek,mt8188-rt5682s audio-routing: - $ref: /schemas/types.yaml#/definitions/non-unique-string-array description: - A list of the connections between audio components. Each entry is a - sink/source pair of strings. Valid names could be the input or output - widgets of audio components, power supplies, MicBias of codec and the - software switch. + Valid names could be the input or output widgets of audio components, + power supplies, MicBias of codec and the software switch. mediatek,platform: $ref: /schemas/types.yaml#/definitions/phandle @@ -86,7 +83,7 @@ patternProperties: required: - link-name -additionalProperties: false +unevaluatedProperties: false required: - compatible @@ -96,6 +93,7 @@ examples: - | sound { compatible = "mediatek,mt8188-mt6359-evb"; + model = "MT6359-EVB"; mediatek,platform = <&afe>; pinctrl-names = "default"; pinctrl-0 = <&aud_pins_default>; diff --git a/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt b/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt index 560762e0a168..f548e6a58240 100644 --- a/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt +++ b/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt @@ -1,7 +1,7 @@ Mediatek AFE PCM controller for mt2701 Required properties: -- compatible: should be one of the followings. +- compatible: should be one of the following. - "mediatek,mt2701-audio" - "mediatek,mt7622-audio" - interrupts: should contain AFE and ASYS interrupts diff --git a/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml b/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml index d80083df03eb..bdf7b0960533 100644 --- a/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml +++ b/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml @@ -17,6 +17,7 @@ properties: enum: - mediatek,mt8186-mt6366-rt1019-rt5682s-sound - mediatek,mt8186-mt6366-rt5682s-max98360-sound + - mediatek,mt8186-mt6366-rt5650-sound mediatek,platform: $ref: /schemas/types.yaml#/definitions/phandle diff --git a/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml b/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml index d5adf07d46e0..5c8dba2b3a81 100644 --- a/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml +++ b/Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml @@ -111,7 +111,7 @@ patternProperties: $ref: /schemas/types.yaml#/definitions/uint32 description: | etdm modules can share the same external clock pin. Specify - which etdm clock source is required by this etdm in moudule. + which etdm clock source is required by this etdm in module. enum: - 0 # etdm1_in - 1 # etdm2_in @@ -122,7 +122,7 @@ patternProperties: $ref: /schemas/types.yaml#/definitions/uint32 description: | etdm modules can share the same external clock pin. Specify - which etdm clock source is required by this etdm out moudule. + which etdm clock source is required by this etdm out module. enum: - 0 # etdm1_in - 1 # etdm2_in diff --git a/Documentation/devicetree/bindings/sound/nau8821.txt b/Documentation/devicetree/bindings/sound/nau8821.txt deleted file mode 100644 index 7c84e7c7327a..000000000000 --- a/Documentation/devicetree/bindings/sound/nau8821.txt +++ /dev/null @@ -1,55 +0,0 @@ -Nuvoton NAU88L21 audio codec - -This device supports I2C only. - -Required properties: - - compatible : Must be "nuvoton,nau8821" - - - reg : the I2C address of the device. This is either 0x1B (CSB=0) or 0x54 (CSB=1). - -Optional properties: - - nuvoton,jkdet-enable: Enable jack detection via JKDET pin. - - nuvoton,jkdet-pull-enable: Enable JKDET pin pull. If set - pin pull enabled, - otherwise pin in high impedance state. - - nuvoton,jkdet-pull-up: Pull-up JKDET pin. If set then JKDET pin is pull up, otherwise pull down. - - nuvoton,jkdet-polarity: JKDET pin polarity. 0 - active high, 1 - active low. - - - nuvoton,vref-impedance: VREF Impedance selection - 0 - Open - 1 - 25 kOhm - 2 - 125 kOhm - 3 - 2.5 kOhm - - - nuvoton,micbias-voltage: Micbias voltage level. - 0 - VDDA - 1 - VDDA - 2 - VDDA * 1.1 - 3 - VDDA * 1.2 - 4 - VDDA * 1.3 - 5 - VDDA * 1.4 - 6 - VDDA * 1.53 - 7 - VDDA * 1.53 - - - nuvoton,jack-insert-debounce: number from 0 to 7 that sets debounce time to 2^(n+2) ms - - nuvoton,jack-eject-debounce: number from 0 to 7 that sets debounce time to 2^(n+2) ms - - - nuvoton,dmic-clk-threshold: the ADC threshold of DMIC clock. - - nuvoton,key_enable: Headset button detection switch. - -Example: - - headset: nau8821@1b { - compatible = "nuvoton,nau8821"; - reg = <0x1b>; - interrupt-parent = <&gpio>; - interrupts = <23 IRQ_TYPE_LEVEL_LOW>; - nuvoton,jkdet-enable; - nuvoton,jkdet-pull-enable; - nuvoton,jkdet-pull-up; - nuvoton,jkdet-polarity = <GPIO_ACTIVE_LOW>; - nuvoton,vref-impedance = <2>; - nuvoton,micbias-voltage = <6>; - nuvoton,jack-insert-debounce = <7>; - nuvoton,jack-eject-debounce = <7>; - nuvoton,dmic-clk-threshold = 3072000; - }; diff --git a/Documentation/devicetree/bindings/sound/nuvoton,nau8821.yaml b/Documentation/devicetree/bindings/sound/nuvoton,nau8821.yaml new file mode 100644 index 000000000000..3e54abd4ca74 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nuvoton,nau8821.yaml @@ -0,0 +1,132 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nuvoton,nau8821.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NAU88L21 audio codec + +maintainers: + - Seven Lee <wtli@nuvoton.com> + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + const: nuvoton,nau8821 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + nuvoton,jkdet-enable: + description: Enable jack detection via JKDET pin. + type: boolean + + nuvoton,jkdet-pull-enable: + description: Enable JKDET pin pull. If set - pin pull enabled, + otherwise pin in high impedance state. + type: boolean + + nuvoton,jkdet-pull-up: + description: Pull-up JKDET pin. If set then JKDET pin is pull up, + otherwise pull down. + type: boolean + + nuvoton,key-enable: + description: handles key press detection. + type: boolean + + nuvoton,jkdet-polarity: + description: JKDET pin polarity. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # active high + - 1 # active low + default: 1 + + nuvoton,micbias-voltage: + description: MICBIAS output level select. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # VDDA + - 1 # VDDA * 1 + - 2 # VDDA * 1.1 + - 3 # VDDA * 1.2 + - 4 # VDDA * 1.3 + - 5 # VDDA * 1.4 + - 6 # VDDA * 1.53 + - 7 # VDDA * 1.53 + default: 6 + + nuvoton,vref-impedance: + description: VMID Tie-off impedance select. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # open + - 1 # 25KOhms + - 2 # 125KOhms + - 3 # 2.5KOhms + default: 2 + + nuvoton,jack-insert-debounce: + description: number from 0 to 7 that sets debounce time to 2^(n+2)ms. + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 7 + default: 7 + + nuvoton,jack-eject-debounce: + description: number from 0 to 7 that sets debounce time to 2^(n+2)ms. + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 7 + default: 0 + + nuvoton,dmic-clk-threshold: + description: DMIC clock speed expected value. Unit is Hz. + $ref: /schemas/types.yaml#/definitions/uint32 + default: 3072000 + + nuvoton,left-input-single-end: + description: Enable left input with single-ended settings if set. + For the headset mic application, the single-ended control is + just limited to the left adc for design demand. + type: boolean + + '#sound-dai-cells': + const: 0 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + codec@1b { + compatible = "nuvoton,nau8821"; + reg = <0x1b>; + interrupt-parent = <&gpio>; + interrupts = <23 IRQ_TYPE_LEVEL_LOW>; + nuvoton,jkdet-enable; + nuvoton,jkdet-pull-enable; + nuvoton,jkdet-pull-up; + nuvoton,key-enable; + nuvoton,left-input-single-end; + nuvoton,jkdet-polarity = <GPIO_ACTIVE_LOW>; + nuvoton,micbias-voltage = <6>; + nuvoton,vref-impedance = <2>; + nuvoton,jack-insert-debounce = <7>; + nuvoton,jack-eject-debounce = <0>; + nuvoton,dmic-clk-threshold = <3072000>; + #sound-dai-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/nuvoton,nau8822.yaml b/Documentation/devicetree/bindings/sound/nuvoton,nau8822.yaml index 65105402a53d..cb8182bbc491 100644 --- a/Documentation/devicetree/bindings/sound/nuvoton,nau8822.yaml +++ b/Documentation/devicetree/bindings/sound/nuvoton,nau8822.yaml @@ -21,6 +21,15 @@ properties: reg: maxItems: 1 + "#sound-dai-cells": + const: 0 + + clocks: + maxItems: 1 + + clock-names: + const: mclk + nuvoton,spk-btl: description: If set, configure the two loudspeaker outputs as a Bridge Tied Load output @@ -31,6 +40,9 @@ required: - compatible - reg +allOf: + - $ref: dai-common.yaml# + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max9808x.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max9808x.yaml index fc89dbd6bf24..c29d7942915c 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max9808x.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max9808x.yaml @@ -35,12 +35,12 @@ properties: items: enum: # Board Connectors - - "Int Spk" - - "Headphone Jack" - - "Earpiece" - - "Headset Mic" - - "Internal Mic 1" - - "Internal Mic 2" + - Int Spk + - Headphone Jack + - Earpiece + - Headset Mic + - Internal Mic 1 + - Internal Mic 2 # CODEC Pins - HPL diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5631.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5631.yaml index a04487002e88..0c8067c3b056 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5631.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5631.yaml @@ -31,10 +31,10 @@ properties: items: enum: # Board Connectors - - "Int Spk" - - "Headphone Jack" - - "Mic Jack" - - "Int Mic" + - Int Spk + - Headphone Jack + - Mic Jack + - Int Mic # CODEC Pins - MIC1 diff --git a/Documentation/devicetree/bindings/sound/nxp,tfa9879.yaml b/Documentation/devicetree/bindings/sound/nxp,tfa9879.yaml new file mode 100644 index 000000000000..df26248573ad --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nxp,tfa9879.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nxp,tfa9879.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP TFA9879 class-D audio amplifier + +maintainers: + - Peter Rosin <peda@axentia.se> + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + const: nxp,tfa9879 + + reg: + maxItems: 1 + + "#sound-dai-cells": + const: 0 + +required: + - compatible + - reg + - '#sound-dai-cells' + +unevaluatedProperties: false + +examples: + - | + i2c1 { + #address-cells = <1>; + #size-cells = <0>; + amplifier@6c { + compatible = "nxp,tfa9879"; + reg = <0x6c>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_i2c1>; + #sound-dai-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/option,gtm601.yaml b/Documentation/devicetree/bindings/sound/option,gtm601.yaml new file mode 100644 index 000000000000..ff813d97fc59 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/option,gtm601.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/option,gtm601.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: GTM601 UMTS modem audio interface CODEC + +maintainers: + - kernel@puri.sm + +description: > + This device has no configuration interface. The sample rate and channels are + based on the compatible string + +properties: + compatible: + oneOf: + - description: Broadmobi BM818 (48Khz stereo) + items: + - const: broadmobi,bm818 + - const: option,gtm601 + - description: GTM601 (8kHz mono) + const: option,gtm601 + + '#sound-dai-cells': + const: 0 + +required: + - compatible + +allOf: + - $ref: dai-common.yaml# + +additionalProperties: false + +examples: + - | + codec { + compatible = "option,gtm601"; + #sound-dai-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/sound/pcm512x.txt b/Documentation/devicetree/bindings/sound/pcm512x.txt index 3aae3b41bd8e..77006a4aec4a 100644 --- a/Documentation/devicetree/bindings/sound/pcm512x.txt +++ b/Documentation/devicetree/bindings/sound/pcm512x.txt @@ -1,12 +1,12 @@ -PCM512x audio CODECs +PCM512x and TAS575x audio CODECs/amplifiers These devices support both I2C and SPI (configured with pin strapping -on the board). +on the board). The TAS575x devices only support I2C. Required properties: - - compatible : One of "ti,pcm5121", "ti,pcm5122", "ti,pcm5141" or - "ti,pcm5142" + - compatible : One of "ti,pcm5121", "ti,pcm5122", "ti,pcm5141", + "ti,pcm5142", "ti,tas5754" or "ti,tas5756" - reg : the I2C address of the device for I2C, the chip select number for SPI. @@ -25,6 +25,7 @@ Optional properties: through <6>. The device will be configured for clock input on the given pll-in pin and PLL output on the given pll-out pin. An external connection from the pll-out pin to the SCLK pin is assumed. + Caution: the TAS-desvices only support gpios 1,2 and 3 Examples: diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml index 6cc8f86c7531..3a559bd07a79 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml @@ -8,7 +8,7 @@ title: Qualcomm Technologies Inc. LPASS CPU dai driver maintainers: - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> - - Rohit kumar <rohitkr@codeaurora.org> + - Rohit kumar <quic_rohkumar@quicinc.com> description: | Qualcomm Technologies Inc. SOC Low-Power Audio SubSystem (LPASS) that consist diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml index 4156981fe02b..962701e9eb42 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml @@ -13,6 +13,7 @@ properties: compatible: enum: - qcom,sc7280-lpass-tx-macro + - qcom,sm6115-lpass-tx-macro - qcom,sm8250-lpass-tx-macro - qcom,sm8450-lpass-tx-macro - qcom,sm8550-lpass-tx-macro @@ -101,6 +102,23 @@ allOf: properties: compatible: enum: + - qcom,sm6115-lpass-tx-macro + then: + properties: + clocks: + minItems: 4 + maxItems: 4 + clock-names: + items: + - const: mclk + - const: npl + - const: dcodec + - const: fsgen + + - if: + properties: + compatible: + enum: - qcom,sm8550-lpass-tx-macro then: properties: diff --git a/Documentation/devicetree/bindings/sound/qcom,msm8916-wcd-analog.txt b/Documentation/devicetree/bindings/sound/qcom,msm8916-wcd-analog.txt deleted file mode 100644 index e7d17dda55db..000000000000 --- a/Documentation/devicetree/bindings/sound/qcom,msm8916-wcd-analog.txt +++ /dev/null @@ -1,101 +0,0 @@ -msm8916 analog audio CODEC - -Bindings for codec Analog IP which is integrated in pmic pm8916, - -## Bindings for codec core on pmic: - -Required properties - - compatible = "qcom,pm8916-wcd-analog-codec"; - - reg: represents the slave base address provided to the peripheral. - - interrupts: List of interrupts in given SPMI peripheral. - - interrupt-names: Names specified to above list of interrupts in same - order. List of supported interrupt names are: - "cdc_spk_cnp_int" - Speaker click and pop interrupt. - "cdc_spk_clip_int" - Speaker clip interrupt. - "cdc_spk_ocp_int" - Speaker over current protect interrupt. - "mbhc_ins_rem_det1" - jack insert removal detect interrupt 1. - "mbhc_but_rel_det" - button release interrupt. - "mbhc_but_press_det" - button press event - "mbhc_ins_rem_det" - jack insert removal detect interrupt. - "mbhc_switch_int" - multi button headset interrupt. - "cdc_ear_ocp_int" - Earphone over current protect interrupt. - "cdc_hphr_ocp_int" - Headphone R over current protect interrupt. - "cdc_hphl_ocp_det" - Headphone L over current protect interrupt. - "cdc_ear_cnp_int" - earphone cnp interrupt. - "cdc_hphr_cnp_int" - hphr click and pop interrupt. - "cdc_hphl_cnp_int" - hphl click and pop interrupt. - - - clocks: Handle to mclk. - - clock-names: should be "mclk" - - vdd-cdc-io-supply: phandle to VDD_CDC_IO regulator DT node. - - vdd-cdc-tx-rx-cx-supply: phandle to VDD_CDC_TX/RX/CX regulator DT node. - - vdd-micbias-supply: phandle of VDD_MICBIAS supply's regulator DT node. - -Optional Properties: - - qcom,mbhc-vthreshold-low: Array of 5 threshold voltages in mV for 5 buttons - detection on headset when the mbhc is powered up - by internal current source, this is a low power. - - qcom,mbhc-vthreshold-high: Array of 5 thresold voltages in mV for 5 buttons - detection on headset when mbhc is powered up - from micbias. -- qcom,micbias-lvl: Voltage (mV) for Mic Bias -- qcom,hphl-jack-type-normally-open: boolean, present if hphl pin on jack is a - NO (Normally Open). If not specified, then - its assumed that hphl pin on jack is NC - (Normally Closed). -- qcom,gnd-jack-type-normally-open: boolean, present if gnd pin on jack is - NO (Normally Open). If not specified, then - its assumed that gnd pin on jack is NC - (Normally Closed). -- qcom,micbias1-ext-cap: boolean, present if micbias1 has external capacitor - connected. -- qcom,micbias2-ext-cap: boolean, present if micbias2 has external capacitor - connected. - -Example: - -spmi_bus { - ... - audio-codec@f000{ - compatible = "qcom,pm8916-wcd-analog-codec"; - reg = <0xf000 0x200>; - reg-names = "pmic-codec-core"; - clocks = <&gcc GCC_CODEC_DIGCODEC_CLK>; - clock-names = "mclk"; - qcom,mbhc-vthreshold-low = <75 150 237 450 500>; - qcom,mbhc-vthreshold-high = <75 150 237 450 500>; - interrupt-parent = <&spmi_bus>; - interrupts = <0x1 0xf0 0x0 IRQ_TYPE_NONE>, - <0x1 0xf0 0x1 IRQ_TYPE_NONE>, - <0x1 0xf0 0x2 IRQ_TYPE_NONE>, - <0x1 0xf0 0x3 IRQ_TYPE_NONE>, - <0x1 0xf0 0x4 IRQ_TYPE_NONE>, - <0x1 0xf0 0x5 IRQ_TYPE_NONE>, - <0x1 0xf0 0x6 IRQ_TYPE_NONE>, - <0x1 0xf0 0x7 IRQ_TYPE_NONE>, - <0x1 0xf1 0x0 IRQ_TYPE_NONE>, - <0x1 0xf1 0x1 IRQ_TYPE_NONE>, - <0x1 0xf1 0x2 IRQ_TYPE_NONE>, - <0x1 0xf1 0x3 IRQ_TYPE_NONE>, - <0x1 0xf1 0x4 IRQ_TYPE_NONE>, - <0x1 0xf1 0x5 IRQ_TYPE_NONE>; - interrupt-names = "cdc_spk_cnp_int", - "cdc_spk_clip_int", - "cdc_spk_ocp_int", - "mbhc_ins_rem_det1", - "mbhc_but_rel_det", - "mbhc_but_press_det", - "mbhc_ins_rem_det", - "mbhc_switch_int", - "cdc_ear_ocp_int", - "cdc_hphr_ocp_int", - "cdc_hphl_ocp_det", - "cdc_ear_cnp_int", - "cdc_hphr_cnp_int", - "cdc_hphl_cnp_int"; - vdd-cdc-io-supply = <&pm8916_l5>; - vdd-cdc-tx-rx-cx-supply = <&pm8916_l5>; - vdd-micbias-supply = <&pm8916_l13>; - #sound-dai-cells = <1>; - }; -}; diff --git a/Documentation/devicetree/bindings/sound/qcom,pm8916-wcd-analog-codec.yaml b/Documentation/devicetree/bindings/sound/qcom,pm8916-wcd-analog-codec.yaml new file mode 100644 index 000000000000..94e7a1860977 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,pm8916-wcd-analog-codec.yaml @@ -0,0 +1,153 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,pm8916-wcd-analog-codec.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm PM8916 WCD Analog Audio Codec + +maintainers: + - Konrad Dybcio <konradybcio@kernel.org> + +description: + The analog WCD audio codec found on Qualcomm PM8916 PMIC. + +properties: + compatible: + const: qcom,pm8916-wcd-analog-codec + + reg: + maxItems: 1 + + interrupts: + maxItems: 14 + + interrupt-names: + items: + - const: cdc_spk_cnp_int + - const: cdc_spk_clip_int + - const: cdc_spk_ocp_int + - const: mbhc_ins_rem_det1 + - const: mbhc_but_rel_det + - const: mbhc_but_press_det + - const: mbhc_ins_rem_det + - const: mbhc_switch_int + - const: cdc_ear_ocp_int + - const: cdc_hphr_ocp_int + - const: cdc_hphl_ocp_det + - const: cdc_ear_cnp_int + - const: cdc_hphr_cnp_int + - const: cdc_hphl_cnp_int + + vdd-cdc-io-supply: + description: 1.8V buck supply + + vdd-cdc-tx-rx-cx-supply: + description: 1.8V SIDO buck supply + + vdd-micbias-supply: + description: micbias supply + + qcom,mbhc-vthreshold-low: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: + Array of 5 threshold voltages in mV for 5-button detection on + headset when MBHC is powered by an internal current source. + minItems: 5 + maxItems: 5 + + qcom,mbhc-vthreshold-high: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: + Array of 5 threshold voltages in mV for 5-button detection on + headset when MBHC is powered from micbias. + minItems: 5 + maxItems: 5 + + qcom,micbias-lvl: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Voltage (mV) for Mic Bias + + qcom,hphl-jack-type-normally-open: + type: boolean + description: + True if the HPHL pin on the jack is NO (Normally Open), false if it's + NC (Normally Closed). + + qcom,gnd-jack-type-normally-open: + type: boolean + description: + True if the GND pin on the jack is NO (Normally Open), false if it's + NC (Normally Closed). + + qcom,micbias1-ext-cap: + type: boolean + description: + True if micbias1 has an external capacitor. + + qcom,micbias2-ext-cap: + type: boolean + description: + True if micbias2 has an external capacitor. + + "#sound-dai-cells": + const: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/spmi/spmi.h> + + pmic@1 { + compatible = "qcom,pm8916", "qcom,spmi-pmic"; + reg = <0x1 SPMI_USID>; + #address-cells = <1>; + #size-cells = <0>; + + audio-codec@f000 { + compatible = "qcom,pm8916-wcd-analog-codec"; + reg = <0xf000>; + qcom,mbhc-vthreshold-low = <75 150 237 450 500>; + qcom,mbhc-vthreshold-high = <75 150 237 450 500>; + interrupt-parent = <&spmi_bus>; + interrupts = <0x1 0xf0 0x0 IRQ_TYPE_NONE>, + <0x1 0xf0 0x1 IRQ_TYPE_NONE>, + <0x1 0xf0 0x2 IRQ_TYPE_NONE>, + <0x1 0xf0 0x3 IRQ_TYPE_NONE>, + <0x1 0xf0 0x4 IRQ_TYPE_NONE>, + <0x1 0xf0 0x5 IRQ_TYPE_NONE>, + <0x1 0xf0 0x6 IRQ_TYPE_NONE>, + <0x1 0xf0 0x7 IRQ_TYPE_NONE>, + <0x1 0xf1 0x0 IRQ_TYPE_NONE>, + <0x1 0xf1 0x1 IRQ_TYPE_NONE>, + <0x1 0xf1 0x2 IRQ_TYPE_NONE>, + <0x1 0xf1 0x3 IRQ_TYPE_NONE>, + <0x1 0xf1 0x4 IRQ_TYPE_NONE>, + <0x1 0xf1 0x5 IRQ_TYPE_NONE>; + interrupt-names = "cdc_spk_cnp_int", + "cdc_spk_clip_int", + "cdc_spk_ocp_int", + "mbhc_ins_rem_det1", + "mbhc_but_rel_det", + "mbhc_but_press_det", + "mbhc_ins_rem_det", + "mbhc_switch_int", + "cdc_ear_ocp_int", + "cdc_hphr_ocp_int", + "cdc_hphl_ocp_det", + "cdc_ear_cnp_int", + "cdc_hphr_cnp_int", + "cdc_hphl_cnp_int"; + vdd-cdc-io-supply = <&pm8916_l5>; + vdd-cdc-tx-rx-cx-supply = <&pm8916_l5>; + vdd-micbias-supply = <&pm8916_l13>; + #sound-dai-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml b/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml index 262de7a60a73..e082a4fe095d 100644 --- a/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml @@ -25,6 +25,7 @@ properties: - qcom,apq8016-sbc-sndcard - qcom,msm8916-qdsp6-sndcard - qcom,qrb5165-rb5-sndcard + - qcom,sc7180-qdsp6-sndcard - qcom,sc8280xp-sndcard - qcom,sdm845-sndcard - qcom,sm8250-sndcard diff --git a/Documentation/devicetree/bindings/sound/realtek,rt5616.yaml b/Documentation/devicetree/bindings/sound/realtek,rt5616.yaml new file mode 100644 index 000000000000..248320804e5f --- /dev/null +++ b/Documentation/devicetree/bindings/sound/realtek,rt5616.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/realtek,rt5616.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Realtek rt5616 ALSA SoC audio codec driver + +description: | + Pins on the device (for linking into audio routes) for RT5616: + + * IN1P + * IN2P + * IN2N + * LOUTL + * LOUTR + * HPOL + * HPOR + +maintainers: + - Bard Liao <bardliao@realtek.com> + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + const: realtek,rt5616 + + reg: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + audio-codec@1b { + compatible = "realtek,rt5616"; + reg = <0x1b>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt index b731f16aea84..dfd768b1ad7d 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt @@ -94,7 +94,7 @@ see "Example: simple sound card for Asynchronous mode" [xx]ch [yy]ch ------> [CTU] --------> -CTU can convert [xx]ch to [yy]ch, or exchange outputed channel. +CTU can convert [xx]ch to [yy]ch, or exchange outputted channel. CTU conversion needs matrix settings. For more detail information, see below diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml index 8a821dec9526..13a5a0a10fe6 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml @@ -9,6 +9,20 @@ title: Renesas R-Car Sound Driver maintainers: - Kuninori Morimoto <kuninori.morimoto.gx@renesas.com> +definitions: + port-def: + $ref: audio-graph-port.yaml#/definitions/port-base + unevaluatedProperties: false + patternProperties: + "^endpoint(@[0-9a-f]+)?": + $ref: audio-graph-port.yaml#/definitions/endpoint-base + properties: + playback: + $ref: /schemas/types.yaml#/definitions/phandle-array + capture: + $ref: /schemas/types.yaml#/definitions/phandle-array + unevaluatedProperties: false + properties: compatible: @@ -77,6 +91,12 @@ properties: it must be 1 if your system has audio_clkout0/1/2/3 enum: [0, 1] + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + clock-frequency: description: for audio_clkout0/1/2/3 @@ -103,35 +123,9 @@ properties: description: List of necessary clock names. # details are defined below - ports: - $ref: audio-graph-port.yaml#/definitions/port-base - unevaluatedProperties: false - patternProperties: - '^port(@[0-9a-f]+)?$': - $ref: audio-graph-port.yaml#/definitions/port-base - unevaluatedProperties: false - patternProperties: - "^endpoint(@[0-9a-f]+)?": - $ref: audio-graph-port.yaml#/definitions/endpoint-base - properties: - playback: - $ref: /schemas/types.yaml#/definitions/phandle-array - capture: - $ref: /schemas/types.yaml#/definitions/phandle-array - unevaluatedProperties: false - + # ports is below port: - $ref: audio-graph-port.yaml#/definitions/port-base - unevaluatedProperties: false - patternProperties: - "^endpoint(@[0-9a-f]+)?": - $ref: audio-graph-port.yaml#/definitions/endpoint-base - properties: - playback: - $ref: /schemas/types.yaml#/definitions/phandle-array - capture: - $ref: /schemas/types.yaml#/definitions/phandle-array - unevaluatedProperties: false + $ref: "#/definitions/port-def" rcar_sound,dvc: description: DVC subnode. @@ -248,8 +242,9 @@ properties: - interrupts additionalProperties: false +patternProperties: # For DAI base - rcar_sound,dai: + 'rcar_sound,dai(@[0-9a-f]+)?$': description: DAI subnode. type: object patternProperties: @@ -269,6 +264,13 @@ properties: - capture additionalProperties: false + 'ports(@[0-9a-f]+)?$': + $ref: audio-graph-port.yaml#/definitions/port-base + unevaluatedProperties: false + patternProperties: + '^port(@[0-9a-f]+)?$': + $ref: "#/definitions/port-def" + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/sound/richtek,rtq9128.yaml b/Documentation/devicetree/bindings/sound/richtek,rtq9128.yaml new file mode 100644 index 000000000000..d54686a19ab7 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/richtek,rtq9128.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/richtek,rtq9128.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Richtek RTQ9128 Automative Audio Power Amplifier + +maintainers: + - ChiYuan Huang <cy_huang@richtek.com> + +description: + The RTQ9128 is a ultra-low output noise, high-efficiency, four-channel + class-D audio power amplifier and delivering 4x75W into 4OHm at 10% + THD+N from a 25V supply in automotive applications. + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + enum: + - richtek,rtq9128 + + reg: + maxItems: 1 + + enable-gpios: + maxItems: 1 + + richtek,tdm-input-data2-select: + type: boolean + description: + By default, if TDM mode is used, TDM data input will select 'DATA1' pin + as the data source. This option will configure TDM data input source from + 'DATA1' to 'DATA2' pin. + + '#sound-dai-cells': + const: 0 + +required: + - compatible + - reg + - '#sound-dai-cells' + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + speaker@1a { + compatible = "richtek,rtq9128"; + reg = <0x1a>; + enable-gpios = <&gpio 26 GPIO_ACTIVE_HIGH>; + #sound-dai-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/rockchip,rk3288-hdmi-analog.txt b/Documentation/devicetree/bindings/sound/rockchip,rk3288-hdmi-analog.txt index e5430d1d34e4..73577ac1b89c 100644 --- a/Documentation/devicetree/bindings/sound/rockchip,rk3288-hdmi-analog.txt +++ b/Documentation/devicetree/bindings/sound/rockchip,rk3288-hdmi-analog.txt @@ -12,7 +12,7 @@ Required properties: source. For this driver the first string should always be "Analog". -Optionnal properties: +Optional properties: - rockchip,hp-en-gpios = The phandle of the GPIO that power up/down the headphone (when the analog output is an headphone). - rockchip,hp-det-gpios = The phandle of the GPIO that detects the headphone diff --git a/Documentation/devicetree/bindings/sound/rockchip-spdif.yaml b/Documentation/devicetree/bindings/sound/rockchip-spdif.yaml index 4f51b2fa82db..c3c989ef2a2c 100644 --- a/Documentation/devicetree/bindings/sound/rockchip-spdif.yaml +++ b/Documentation/devicetree/bindings/sound/rockchip-spdif.yaml @@ -26,6 +26,7 @@ properties: - const: rockchip,rk3568-spdif - items: - enum: + - rockchip,rk3128-spdif - rockchip,rk3188-spdif - rockchip,rk3288-spdif - rockchip,rk3308-spdif diff --git a/Documentation/devicetree/bindings/sound/rt5616.txt b/Documentation/devicetree/bindings/sound/rt5616.txt deleted file mode 100644 index 540a4bf252e4..000000000000 --- a/Documentation/devicetree/bindings/sound/rt5616.txt +++ /dev/null @@ -1,32 +0,0 @@ -RT5616 audio CODEC - -This device supports I2C only. - -Required properties: - -- compatible : "realtek,rt5616". - -- reg : The I2C address of the device. - -Optional properties: - -- clocks: The phandle of the master clock to the CODEC. - -- clock-names: Should be "mclk". - -Pins on the device (for linking into audio routes) for RT5616: - - * IN1P - * IN2P - * IN2N - * LOUTL - * LOUTR - * HPOL - * HPOR - -Example: - -rt5616: codec@1b { - compatible = "realtek,rt5616"; - reg = <0x1b>; -}; diff --git a/Documentation/devicetree/bindings/sound/rt5663.txt b/Documentation/devicetree/bindings/sound/rt5663.txt index 2a55e9133408..24a6dab28f25 100644 --- a/Documentation/devicetree/bindings/sound/rt5663.txt +++ b/Documentation/devicetree/bindings/sound/rt5663.txt @@ -28,7 +28,7 @@ Optional properties: If the value is 0, it means the impedance sensing is not supported. - "realtek,impedance_sensing_table" The matrix rows of the impedance sensing table are consisted by impedance - minimum, impedance maximun, volume, DC offset w/o and w/ mic of each L and + minimum, impedance maximum, volume, DC offset w/o and w/ mic of each L and R channel accordingly. Example is shown as following. < 0 300 7 0xffd160 0xffd1c0 0xff8a10 0xff8ab0 301 65535 4 0xffe470 0xffe470 0xffb8e0 0xffb8e0> diff --git a/Documentation/devicetree/bindings/sound/samsung,aries-wm8994.yaml b/Documentation/devicetree/bindings/sound/samsung,aries-wm8994.yaml index 447e013f6e17..5ea0819a261a 100644 --- a/Documentation/devicetree/bindings/sound/samsung,aries-wm8994.yaml +++ b/Documentation/devicetree/bindings/sound/samsung,aries-wm8994.yaml @@ -9,6 +9,9 @@ title: Samsung Aries audio complex with WM8994 codec maintainers: - Jonathan Bakker <xc-racer2@live.ca> +allOf: + - $ref: sound-card-common.yaml# + properties: compatible: enum: @@ -17,10 +20,6 @@ properties: # Without FM radio and modem slave - samsung,fascinate4g-wm8994 - model: - $ref: /schemas/types.yaml#/definitions/string - description: The user-visible name of this sound complex. - cpu: type: object additionalProperties: false @@ -46,6 +45,7 @@ properties: samsung,audio-routing: $ref: /schemas/types.yaml#/definitions/non-unique-string-array + deprecated: true description: | List of the connections between audio components; each entry is a pair of strings, the first being the @@ -56,6 +56,7 @@ properties: or FM In For samsung,fascinate4g-wm8994: HP, SPK, RCV, LINE, Main Mic, or HeadsetMic + Deprecated, use audio-routing. extcon: description: Extcon phandle for dock detection @@ -87,10 +88,9 @@ properties: required: - compatible - - model - cpu - codec - - samsung,audio-routing + - audio-routing - extcon - main-micbias-supply - headset-micbias-supply @@ -98,7 +98,7 @@ required: - headset-detect-gpios - headset-key-gpios -additionalProperties: false +unevaluatedProperties: false examples: - | @@ -121,7 +121,7 @@ examples: headset-detect-gpios = <&gph0 6 GPIO_ACTIVE_HIGH>; headset-key-gpios = <&gph3 6 GPIO_ACTIVE_HIGH>; - samsung,audio-routing = + audio-routing = "HP", "HPOUT1L", "HP", "HPOUT1R", diff --git a/Documentation/devicetree/bindings/sound/samsung,midas-audio.yaml b/Documentation/devicetree/bindings/sound/samsung,midas-audio.yaml index 31095913e330..6ec80f529d84 100644 --- a/Documentation/devicetree/bindings/sound/samsung,midas-audio.yaml +++ b/Documentation/devicetree/bindings/sound/samsung,midas-audio.yaml @@ -9,14 +9,13 @@ title: Samsung Midas audio complex with WM1811 codec maintainers: - Sylwester Nawrocki <s.nawrocki@samsung.com> +allOf: + - $ref: sound-card-common.yaml# + properties: compatible: const: samsung,midas-audio - model: - $ref: /schemas/types.yaml#/definitions/string - description: The user-visible name of this sound complex. - cpu: type: object additionalProperties: false @@ -38,6 +37,7 @@ properties: - sound-dai samsung,audio-routing: + deprecated: true $ref: /schemas/types.yaml#/definitions/non-unique-string-array description: | List of the connections between audio components; each entry is @@ -45,6 +45,7 @@ properties: being the connection's source; valid names for sources and sinks are the WM1811's pins (as documented in its binding), and the jacks on the board: HP, SPK, Main Mic, Sub Mic, Headset Mic. + Deprecated, use audio-routing. mic-bias-supply: description: Supply for the micbias on the Main microphone @@ -62,14 +63,13 @@ properties: required: - compatible - - model - cpu - codec - - samsung,audio-routing + - audio-routing - mic-bias-supply - submic-bias-supply -additionalProperties: false +unevaluatedProperties: false examples: - | @@ -84,7 +84,7 @@ examples: mic-bias-supply = <&mic_bias_reg>; submic-bias-supply = <&submic_bias_reg>; - samsung,audio-routing = + audio-routing = "HP", "HPOUT1L", "HP", "HPOUT1R", diff --git a/Documentation/devicetree/bindings/sound/samsung,odroid.yaml b/Documentation/devicetree/bindings/sound/samsung,odroid.yaml index c6751c40e63f..b77284e3e26a 100644 --- a/Documentation/devicetree/bindings/sound/samsung,odroid.yaml +++ b/Documentation/devicetree/bindings/sound/samsung,odroid.yaml @@ -10,6 +10,9 @@ maintainers: - Krzysztof Kozlowski <krzk@kernel.org> - Sylwester Nawrocki <s.nawrocki@samsung.com> +allOf: + - $ref: sound-card-common.yaml# + properties: compatible: oneOf: @@ -24,10 +27,6 @@ properties: - const: samsung,odroid-xu4-audio deprecated: true - model: - $ref: /schemas/types.yaml#/definitions/string - description: The user-visible name of this sound complex. - assigned-clock-parents: true assigned-clock-rates: true assigned-clocks: true @@ -52,6 +51,7 @@ properties: samsung,audio-routing: $ref: /schemas/types.yaml#/definitions/non-unique-string-array + deprecated: true description: | List of the connections between audio components; each entry is a pair of strings, the first being the @@ -61,6 +61,7 @@ properties: For Odroid X2: "Headphone Jack", "Mic Jack", "DMIC" For Odroid U3, XU3: "Headphone Jack", "Speakers" For Odroid XU4: no entries + Deprecated, use audio-routing. samsung,audio-widgets: $ref: /schemas/types.yaml#/definitions/non-unique-string-array @@ -70,18 +71,17 @@ properties: required: - compatible - - model - cpu - codec -additionalProperties: false +unevaluatedProperties: false examples: - | sound { compatible = "hardkernel,odroid-xu3-audio"; model = "Odroid-XU3"; - samsung,audio-routing = + audio-routing = "Headphone Jack", "HPL", "Headphone Jack", "HPR", "IN1", "Mic Jack", diff --git a/Documentation/devicetree/bindings/sound/samsung,tm2.yaml b/Documentation/devicetree/bindings/sound/samsung,tm2.yaml index 491e08019c04..760592599143 100644 --- a/Documentation/devicetree/bindings/sound/samsung,tm2.yaml +++ b/Documentation/devicetree/bindings/sound/samsung,tm2.yaml @@ -10,6 +10,9 @@ maintainers: - Krzysztof Kozlowski <krzk@kernel.org> - Sylwester Nawrocki <s.nawrocki@samsung.com> +allOf: + - $ref: sound-card-common.yaml# + properties: compatible: const: samsung,tm2-audio @@ -32,6 +35,8 @@ properties: being the connection's source; valid names for sources and sinks are the WM5110's and MAX98504's pins and the jacks on the board: HP, SPK, Main Mic, Sub Mic, Third Mic, Headset Mic. + Deprecated, use audio-routing. + deprecated: true $ref: /schemas/types.yaml#/definitions/non-unique-string-array i2s-controller: @@ -44,20 +49,15 @@ properties: mic-bias-gpios: description: GPIO pin that enables the Main Mic bias regulator. - model: - description: The user-visible name of this sound complex. - $ref: /schemas/types.yaml#/definitions/string - required: - compatible - audio-amplifier - audio-codec - - samsung,audio-routing + - audio-routing - i2s-controller - mic-bias-gpios - - model -additionalProperties: false +unevaluatedProperties: false examples: - | @@ -70,7 +70,7 @@ examples: audio-amplifier = <&max98504>; mic-bias-gpios = <&gpr3 2 GPIO_ACTIVE_HIGH>; model = "wm5110"; - samsung,audio-routing = "HP", "HPOUT1L", + audio-routing = "HP", "HPOUT1L", "HP", "HPOUT1R", "SPK", "SPKOUT", "SPKOUT", "HPOUT2L", diff --git a/Documentation/devicetree/bindings/sound/serial-midi.yaml b/Documentation/devicetree/bindings/sound/serial-midi.yaml index 4afc29376efc..f6a807329a5a 100644 --- a/Documentation/devicetree/bindings/sound/serial-midi.yaml +++ b/Documentation/devicetree/bindings/sound/serial-midi.yaml @@ -20,7 +20,7 @@ description: parent serial device. If the standard MIDI baud of 31.25 kBaud is needed (as would be the case if interfacing with arbitrary external MIDI devices), configure the clocks of the parent serial device so that a requested baud of 38.4 kBaud - resuts in the standard MIDI baud rate, and set the 'current-speed' property to 38400 (default) + results in the standard MIDI baud rate, and set the 'current-speed' property to 38400 (default) properties: compatible: diff --git a/Documentation/devicetree/bindings/sound/simple-card.yaml b/Documentation/devicetree/bindings/sound/simple-card.yaml index b05e05c81cc4..59ac2d1d1ccf 100644 --- a/Documentation/devicetree/bindings/sound/simple-card.yaml +++ b/Documentation/devicetree/bindings/sound/simple-card.yaml @@ -148,6 +148,15 @@ definitions: required: - sound-dai + additional-devs: + type: object + description: + Additional devices used by the simple audio card. + patternProperties: + '^iio-aux(-.+)?$': + type: object + $ref: audio-iio-aux.yaml# + properties: compatible: contains: @@ -187,6 +196,8 @@ properties: $ref: "#/definitions/mclk-fs" simple-audio-card,aux-devs: $ref: "#/definitions/aux-devs" + simple-audio-card,additional-devs: + $ref: "#/definitions/additional-devs" simple-audio-card,convert-rate: $ref: "#/definitions/convert-rate" simple-audio-card,convert-channels: @@ -360,6 +371,48 @@ examples: }; # -------------------- +# route audio to/from a codec through an amplifier +# designed with a potentiometer driven by IIO: +# -------------------- + - | + sound { + compatible = "simple-audio-card"; + + simple-audio-card,aux-devs = <&_in>, <&_out>; + simple-audio-card,routing = + "CODEC LEFTIN", "AMP_IN LEFT OUT", + "CODEC RIGHTIN", "AMP_IN RIGHT OUT", + "AMP_OUT LEFT IN", "CODEC LEFTOUT", + "AMP_OUT RIGHT IN", "CODEC RIGHTOUT"; + + simple-audio-card,additional-devs { + amp_out: iio-aux-out { + compatible = "audio-iio-aux"; + io-channels = <&pot_out 0>, <&pot_out 1>; + io-channel-names = "LEFT", "RIGHT"; + snd-control-invert-range = <1 1>; + sound-name-prefix = "AMP_OUT"; + }; + + amp_in: iio_aux-in { + compatible = "audio-iio-aux"; + io-channels = <&pot_in 0>, <&pot_in 1>; + io-channel-names = "LEFT", "RIGHT"; + sound-name-prefix = "AMP_IN"; + }; + }; + + simple-audio-card,cpu { + sound-dai = <&cpu>; + }; + + simple-audio-card,codec { + sound-dai = <&codec>; + clocks = <&clocks>; + }; + }; + +# -------------------- # Sampling Rate Conversion # -------------------- - | diff --git a/Documentation/devicetree/bindings/sound/snps,designware-i2s.yaml b/Documentation/devicetree/bindings/sound/snps,designware-i2s.yaml index a970fd264b21..a48d040b0a4f 100644 --- a/Documentation/devicetree/bindings/sound/snps,designware-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/snps,designware-i2s.yaml @@ -17,6 +17,9 @@ properties: - const: snps,designware-i2s - enum: - snps,designware-i2s + - starfive,jh7110-i2stx0 + - starfive,jh7110-i2stx1 + - starfive,jh7110-i2srx reg: maxItems: 1 @@ -29,15 +32,36 @@ properties: maxItems: 1 clocks: - description: Sampling rate reference clock - maxItems: 1 + items: + - description: Sampling rate reference clock + - description: APB clock + - description: Audio master clock + - description: Inner audio master clock source + - description: External audio master clock source + - description: Bit clock + - description: Left/right channel clock + - description: External bit clock + - description: External left/right channel clock + minItems: 1 clock-names: - const: i2sclk + items: + - const: i2sclk + - const: apb + - const: mclk + - const: mclk_inner + - const: mclk_ext + - const: bclk + - const: lrck + - const: bclk_ext + - const: lrck_ext + minItems: 1 resets: items: - description: Optional controller resets + - description: controller reset of Sampling rate + minItems: 1 dmas: items: @@ -51,6 +75,17 @@ properties: - const: rx minItems: 1 + starfive,syscon: + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + - items: + - description: phandle to System Register Controller sys_syscon node. + - description: I2S-rx enabled control offset of SYS_SYSCONSAIF__SYSCFG register. + - description: I2S-rx enabled control mask + description: + The phandle to System Register Controller syscon node and the I2S-rx(ADC) + enabled control offset and mask of SYS_SYSCONSAIF__SYSCFG register. + allOf: - $ref: dai-common.yaml# - if: @@ -66,6 +101,73 @@ allOf: properties: "#sound-dai-cells": const: 0 + - if: + properties: + compatible: + contains: + const: snps,designware-i2s + then: + properties: + clocks: + maxItems: 1 + clock-names: + maxItems: 1 + resets: + maxItems: 1 + else: + properties: + resets: + minItems: 2 + maxItems: 2 + - if: + properties: + compatible: + contains: + const: starfive,jh7110-i2stx0 + then: + properties: + clocks: + minItems: 5 + maxItems: 5 + clock-names: + minItems: 5 + maxItems: 5 + required: + - resets + - if: + properties: + compatible: + contains: + const: starfive,jh7110-i2stx1 + then: + properties: + clocks: + minItems: 9 + maxItems: 9 + clock-names: + minItems: 9 + maxItems: 9 + required: + - resets + - if: + properties: + compatible: + contains: + const: starfive,jh7110-i2srx + then: + properties: + clocks: + minItems: 9 + maxItems: 9 + clock-names: + minItems: 9 + maxItems: 9 + required: + - resets + - starfive,syscon + else: + properties: + starfive,syscon: false required: - compatible diff --git a/Documentation/devicetree/bindings/sound/sound-card-common.yaml b/Documentation/devicetree/bindings/sound/sound-card-common.yaml new file mode 100644 index 000000000000..3a941177f684 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/sound-card-common.yaml @@ -0,0 +1,27 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/sound-card-common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Board Sound Card Common Properties + +maintainers: + - Mark Brown <broonie@kernel.org> + +properties: + audio-routing: + $ref: /schemas/types.yaml#/definitions/non-unique-string-array + 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. + + model: + $ref: /schemas/types.yaml#/definitions/string + description: User specified audio sound card name + +required: + - model + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/sound/sprd-pcm.txt b/Documentation/devicetree/bindings/sound/sprd-pcm.txt index 4b23e84b2e57..fbbcade2181d 100644 --- a/Documentation/devicetree/bindings/sound/sprd-pcm.txt +++ b/Documentation/devicetree/bindings/sound/sprd-pcm.txt @@ -1,4 +1,4 @@ -* Spreadtrum DMA platfrom bindings +* Spreadtrum DMA platform bindings Required properties: - compatible: Should be "sprd,pcm-platform". diff --git a/Documentation/devicetree/bindings/sound/st,stm32-sai.yaml b/Documentation/devicetree/bindings/sound/st,stm32-sai.yaml index 56d206f97a96..59df8a832310 100644 --- a/Documentation/devicetree/bindings/sound/st,stm32-sai.yaml +++ b/Documentation/devicetree/bindings/sound/st,stm32-sai.yaml @@ -63,7 +63,7 @@ patternProperties: additionalProperties: false description: Two subnodes corresponding to SAI sub-block instances A et B - can be defined. Subnode can be omitted for unsused sub-block. + can be defined. Subnode can be omitted for unused sub-block. properties: compatible: diff --git a/Documentation/devicetree/bindings/sound/starfive,jh7110-pwmdac.yaml b/Documentation/devicetree/bindings/sound/starfive,jh7110-pwmdac.yaml new file mode 100644 index 000000000000..e2b4db6aa2fb --- /dev/null +++ b/Documentation/devicetree/bindings/sound/starfive,jh7110-pwmdac.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/starfive,jh7110-pwmdac.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive JH7110 PWM-DAC Controller + +description: + The PWM-DAC Controller uses PWM square wave generators plus RC filters to + form a DAC for audio play in StarFive JH7110 SoC. This audio play controller + supports 16 bit audio format, up to 48K sampling frequency, up to left and + right dual channels. + +maintainers: + - Hal Feng <hal.feng@starfivetech.com> + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + const: starfive,jh7110-pwmdac + + reg: + maxItems: 1 + + clocks: + items: + - description: PWMDAC APB + - description: PWMDAC CORE + + clock-names: + items: + - const: apb + - const: core + + resets: + maxItems: 1 + description: PWMDAC APB + + dmas: + maxItems: 1 + description: TX DMA Channel + + dma-names: + const: tx + + "#sound-dai-cells": + const: 0 + +required: + - compatible + - reg + - clocks + - clock-names + - resets + - dmas + - dma-names + - "#sound-dai-cells" + +additionalProperties: false + +examples: + - | + pwmdac@100b0000 { + compatible = "starfive,jh7110-pwmdac"; + reg = <0x100b0000 0x1000>; + clocks = <&syscrg 157>, + <&syscrg 158>; + clock-names = "apb", "core"; + resets = <&syscrg 96>; + dmas = <&dma 22>; + dma-names = "tx"; + #sound-dai-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/sound/tas5805m.yaml b/Documentation/devicetree/bindings/sound/tas5805m.yaml index 63edf52f061c..12c41974274e 100644 --- a/Documentation/devicetree/bindings/sound/tas5805m.yaml +++ b/Documentation/devicetree/bindings/sound/tas5805m.yaml @@ -37,6 +37,8 @@ properties: generated from TI's PPC3 tool. $ref: /schemas/types.yaml#/definitions/string +additionalProperties: false + examples: - | i2c { @@ -52,5 +54,4 @@ examples: ti,dsp-config-name = "mono_pbtl_48khz"; }; }; - -additionalProperties: true +... diff --git a/Documentation/devicetree/bindings/sound/tfa9879.txt b/Documentation/devicetree/bindings/sound/tfa9879.txt deleted file mode 100644 index 1620e6848436..000000000000 --- a/Documentation/devicetree/bindings/sound/tfa9879.txt +++ /dev/null @@ -1,23 +0,0 @@ -NXP TFA9879 class-D audio amplifier - -Required properties: - -- compatible : "nxp,tfa9879" - -- reg : the I2C address of the device - -- #sound-dai-cells : must be 0. - -Example: - -&i2c1 { - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_i2c1>; - - amp: amp@6c { - #sound-dai-cells = <0>; - compatible = "nxp,tfa9879"; - reg = <0x6c>; - }; -}; - diff --git a/Documentation/devicetree/bindings/sound/ti,j721e-cpb-ivi-audio.yaml b/Documentation/devicetree/bindings/sound/ti,j721e-cpb-ivi-audio.yaml index 859d369c71e2..5b2874a80a4d 100644 --- a/Documentation/devicetree/bindings/sound/ti,j721e-cpb-ivi-audio.yaml +++ b/Documentation/devicetree/bindings/sound/ti,j721e-cpb-ivi-audio.yaml @@ -13,7 +13,7 @@ maintainers: description: | The Infotainment board plugs into the Common Processor Board, the support of the - extension board is extending the CPB audio support, decribed in: + extension board is extending the CPB audio support, described in: sound/ti,j721e-cpb-audio.txt The audio support on the Infotainment Expansion Board consists of McASP0 diff --git a/Documentation/devicetree/bindings/sound/ti,pcm3168a.yaml b/Documentation/devicetree/bindings/sound/ti,pcm3168a.yaml index b6a4360ab845..0b4f003989a4 100644 --- a/Documentation/devicetree/bindings/sound/ti,pcm3168a.yaml +++ b/Documentation/devicetree/bindings/sound/ti,pcm3168a.yaml @@ -60,6 +60,7 @@ properties: ports: $ref: audio-graph-port.yaml#/definitions/port-base + unevaluatedProperties: false properties: port@0: $ref: audio-graph-port.yaml# diff --git a/Documentation/devicetree/bindings/sound/ti,tas2781.yaml b/Documentation/devicetree/bindings/sound/ti,tas2781.yaml index 8d60e4e236d6..a69e6c223308 100644 --- a/Documentation/devicetree/bindings/sound/ti,tas2781.yaml +++ b/Documentation/devicetree/bindings/sound/ti,tas2781.yaml @@ -29,7 +29,7 @@ properties: reg: description: I2C address, in multiple tas2781s case, all the i2c address - aggreate as one Audio Device to support multiple audio slots. + aggregate as one Audio Device to support multiple audio slots. maxItems: 8 minItems: 1 items: diff --git a/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml b/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml index c16e1760cf85..f3274bcc4c05 100644 --- a/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml +++ b/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml @@ -32,7 +32,7 @@ properties: reg: maxItems: 1 description: | - I2C addresss of the device can be one of these 0x4c, 0x4d, 0x4e or 0x4f + I2C address of the device can be one of these 0x4c, 0x4d, 0x4e or 0x4f reset-gpios: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8904.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8904.yaml new file mode 100644 index 000000000000..329260cf0fa0 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/wlf,wm8904.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/wlf,wm8904.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Wolfson WM8904/WM8912 audio codecs + +maintainers: + - patches@opensource.cirrus.com + +description: | + Pins on the device (for linking into audio routes): + IN1L, IN1R, IN2L, IN2R, IN3L, IN3R, HPOUTL, HPOUTR, LINEOUTL, LINEOUTR, + MICBIAS + +properties: + compatible: + enum: + - wlf,wm8904 + - wlf,wm8912 + + reg: + maxItems: 1 + + "#sound-dai-cells": + const: 0 + + clocks: + maxItems: 1 + + clock-names: + const: mclk + + AVDD-supply: true + CPVDD-supply: true + DBVDD-supply: true + DCVDD-supply: true + MICVDD-supply: true + +required: + - compatible + - reg + - clocks + - clock-names + - AVDD-supply + - CPVDD-supply + - DBVDD-supply + - DCVDD-supply + - MICVDD-supply + +allOf: + - $ref: dai-common.yaml# + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + codec@1a { + compatible = "wlf,wm8904"; + reg = <0x1a>; + clocks = <&pck0>; + clock-names = "mclk"; + AVDD-supply = <®_1p8v>; + CPVDD-supply = <®_1p8v>; + DBVDD-supply = <®_1p8v>; + DCVDD-supply = <®_1p8v>; + MICVDD-supply = <®_1p8v>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8960.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8960.yaml index ee8eba7f0104..62e62c335d07 100644 --- a/Documentation/devicetree/bindings/sound/wlf,wm8960.yaml +++ b/Documentation/devicetree/bindings/sound/wlf,wm8960.yaml @@ -26,6 +26,21 @@ properties: '#sound-dai-cells': const: 0 + AVDD-supply: + description: Analogue supply. + + DBVDD-supply: + description: Digital Buffer Supply. + + DCVDD-supply: + description: Digital Core Supply. + + SPKVDD1-supply: + description: Supply for speaker drivers 1. + + SPKVDD2-supply: + description: Supply for speaker drivers 2. + wlf,capless: type: boolean description: @@ -84,5 +99,10 @@ examples: wlf,hp-cfg = <3 2 3>; wlf,gpio-cfg = <1 3>; wlf,shared-lrclk; + DCVDD-supply = <®_audio>; + DBVDD-supply = <®_audio>; + AVDD-supply = <®_audio>; + SPKVDD1-supply = <®_audio>; + SPKVDD2-supply = <®_audio>; }; }; diff --git a/Documentation/devicetree/bindings/sound/wm8782.txt b/Documentation/devicetree/bindings/sound/wm8782.txt index 256cdec6ec4d..1a28f3280972 100644 --- a/Documentation/devicetree/bindings/sound/wm8782.txt +++ b/Documentation/devicetree/bindings/sound/wm8782.txt @@ -8,10 +8,17 @@ Required properties: - Vdda-supply : phandle to a regulator for the analog power supply (2.7V - 5.5V) - Vdd-supply : phandle to a regulator for the digital power supply (2.7V - 3.6V) +Optional properties: + + - wlf,fsampen: + FSAMPEN pin value, 0 for low, 1 for high, 2 for disconnected. + Defaults to 0 if left unspecified. + Example: wm8782: stereo-adc { compatible = "wlf,wm8782"; Vdda-supply = <&vdda_supply>; Vdd-supply = <&vdd_supply>; + wlf,fsampen = <2>; /* 192KHz */ }; diff --git a/Documentation/devicetree/bindings/sound/wm8904.txt b/Documentation/devicetree/bindings/sound/wm8904.txt deleted file mode 100644 index 66bf261423b9..000000000000 --- a/Documentation/devicetree/bindings/sound/wm8904.txt +++ /dev/null @@ -1,33 +0,0 @@ -WM8904 audio CODEC - -This device supports I2C only. - -Required properties: - - compatible: "wlf,wm8904" or "wlf,wm8912" - - reg: the I2C address of the device. - - clock-names: "mclk" - - clocks: reference to - <Documentation/devicetree/bindings/clock/clock-bindings.txt> - -Pins on the device (for linking into audio routes): - - * IN1L - * IN1R - * IN2L - * IN2R - * IN3L - * IN3R - * HPOUTL - * HPOUTR - * LINEOUTL - * LINEOUTR - * MICBIAS - -Examples: - -codec: wm8904@1a { - compatible = "wlf,wm8904"; - reg = <0x1a>; - clocks = <&pck0>; - clock-names = "mclk"; -}; diff --git a/Documentation/devicetree/bindings/soundwire/qcom,soundwire.yaml b/Documentation/devicetree/bindings/soundwire/qcom,soundwire.yaml index fb44b89a754e..3591c8c49bfe 100644 --- a/Documentation/devicetree/bindings/soundwire/qcom,soundwire.yaml +++ b/Documentation/devicetree/bindings/soundwire/qcom,soundwire.yaml @@ -159,7 +159,7 @@ properties: qcom,ports-hstart: $ref: /schemas/types.yaml#/definitions/uint8-array description: - Identifying lowerst numbered coloum in SoundWire Frame, + Identifying lowerst numbered column in SoundWire Frame, i.e. left edge of the Transport sub-frame for each port. Out ports followed by In ports. Value of 0xff indicates that this option is not implemented @@ -176,7 +176,7 @@ properties: qcom,ports-hstop: $ref: /schemas/types.yaml#/definitions/uint8-array description: - Identifying highest numbered coloum in SoundWire Frame, + Identifying highest numbered column in SoundWire Frame, i.e. the right edge of the Transport sub-frame for each port. Out ports followed by In ports. Value of 0xff indicates that this option is not implemented @@ -209,17 +209,6 @@ properties: label: maxItems: 1 -patternProperties: - "^.*@[0-9a-f],[0-9a-f]$": - type: object - additionalProperties: true - description: - Child nodes for a standalone audio codec or speaker amplifier IC. - It has RX and TX Soundwire secondary devices. - properties: - compatible: - pattern: "^sdw[0-9a-f]{1}[0-9a-f]{4}[0-9a-f]{4}[0-9a-f]{2}$" - required: - compatible - reg @@ -240,7 +229,10 @@ oneOf: - required: - qcom,ports-sinterval -additionalProperties: false +allOf: + - $ref: soundwire-controller.yaml# + +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml b/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml index a6f34bdd1d3c..e1ab3f523ad6 100644 --- a/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml +++ b/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml @@ -46,6 +46,8 @@ properties: patternProperties: "^.*@[0-9a-f]+": type: object + additionalProperties: true + properties: reg: items: diff --git a/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml b/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml index 28b8ace63044..3b47b68b92cb 100644 --- a/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml +++ b/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml @@ -68,6 +68,8 @@ properties: patternProperties: "^.*@[0-9a-f]+": type: object + additionalProperties: true + properties: reg: items: diff --git a/Documentation/devicetree/bindings/spi/arm,pl022-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/arm,pl022-peripheral-props.yaml new file mode 100644 index 000000000000..bb8b6863b109 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/arm,pl022-peripheral-props.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/arm,pl022-peripheral-props.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Peripheral-specific properties for Arm PL022 SPI controller + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +select: false + +properties: + pl022,interface: + description: SPI interface type + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # SPI + - 1 # Texas Instruments Synchronous Serial Frame Format + - 2 # Microwire (Half Duplex) + + pl022,com-mode: + description: Specifies the transfer mode + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # interrupt mode + - 1 # polling mode + - 2 # DMA mode + default: 1 + + pl022,rx-level-trig: + description: Rx FIFO watermark level + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 4 + + pl022,tx-level-trig: + description: Tx FIFO watermark level + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 4 + + pl022,ctrl-len: + description: Microwire interface - Control length + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0x03 + maximum: 0x1f + + pl022,wait-state: + description: Microwire interface - Wait state + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + + pl022,duplex: + description: Microwire interface - Full/Half duplex + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + +additionalProperties: true +... diff --git a/Documentation/devicetree/bindings/spi/brcm,bcm2835-aux-spi.txt b/Documentation/devicetree/bindings/spi/brcm,bcm2835-aux-spi.txt index 9887b0724759..d7668f41b03b 100644 --- a/Documentation/devicetree/bindings/spi/brcm,bcm2835-aux-spi.txt +++ b/Documentation/devicetree/bindings/spi/brcm,bcm2835-aux-spi.txt @@ -1,4 +1,4 @@ -Broadcom BCM2835 auxiliar SPI1/2 controller +Broadcom BCM2835 auxiliary SPI1/2 controller The BCM2835 contains two forms of SPI master controller, one known simply as SPI0, and the other known as the "Universal SPI Master"; part of the @@ -9,7 +9,7 @@ Required properties: - reg: Should contain register location and length for the spi block - interrupts: Should contain shared interrupt of the aux block - clocks: The clock feeding the SPI controller - needs to - point to the auxiliar clock driver of the bcm2835, + point to the auxiliary clock driver of the bcm2835, as this clock will enable the output gate for the specific clock. - cs-gpios: the cs-gpios (native cs is NOT supported) diff --git a/Documentation/devicetree/bindings/spi/brcm,bcm63xx-spi.yaml b/Documentation/devicetree/bindings/spi/brcm,bcm63xx-spi.yaml new file mode 100644 index 000000000000..fa03cdd68e70 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/brcm,bcm63xx-spi.yaml @@ -0,0 +1,71 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/brcm,bcm63xx-spi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM6348/BCM6358 SPI controller + +maintainers: + - Jonas Gorski <jonas.gorski@gmail.com> + +description: | + Broadcom "Low Speed" SPI controller found in many older MIPS based Broadband + SoCs. + + This controller has a limitation that can not keep the chip select line active + between the SPI transfers within the same SPI message. This can terminate the + transaction to some SPI devices prematurely. The issue can be worked around by + the controller's prepend mode. + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + oneOf: + - items: + - enum: + - brcm,bcm6368-spi + - brcm,bcm6362-spi + - brcm,bcm63268-spi + - const: brcm,bcm6358-spi + - enum: + - brcm,bcm6348-spi + - brcm,bcm6358-spi + + reg: + maxItems: 1 + + clocks: + items: + - description: SPI master reference clock + + clock-names: + items: + - const: spi + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + +unevaluatedProperties: false + +examples: + - | + spi@10000800 { + compatible = "brcm,bcm6368-spi", "brcm,bcm6358-spi"; + reg = <0x10000800 0x70c>; + interrupts = <1>; + clocks = <&clkctl 9>; + clock-names = "spi"; + num-cs = <5>; + #address-cells = <1>; + #size-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.yaml b/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.yaml index 28222aae3077..45975f40d943 100644 --- a/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.yaml +++ b/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.yaml @@ -12,7 +12,7 @@ maintainers: description: | The Broadcom SPI controller is a SPI master found on various SOCs, including - BRCMSTB (BCM7XXX), Cygnus, NSP and NS2. The Broadcom Master SPI hw IP consits + BRCMSTB (BCM7XXX), Cygnus, NSP and NS2. The Broadcom Master SPI hw IP consists of: MSPI : SPI master controller can read and write to a SPI slave device BSPI : Broadcom SPI in combination with the MSPI hw IP provides acceleration @@ -20,7 +20,7 @@ description: | io with 3-byte and 4-byte addressing support. Supported Broadcom SoCs have one instance of MSPI+BSPI controller IP. - MSPI master can be used wihout BSPI. BRCMSTB SoCs have an additional instance + MSPI master can be used without BSPI. BRCMSTB SoCs have an additional instance of a MSPI master without the BSPI to use with non flash slave devices that use SPI protocol. diff --git a/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml b/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml index 4f15f9a0cc34..cca81f89e252 100644 --- a/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml +++ b/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml @@ -86,7 +86,17 @@ properties: maxItems: 1 clocks: - maxItems: 1 + minItems: 1 + maxItems: 3 + + clock-names: + oneOf: + - items: + - const: ref + - items: + - const: ref + - const: ahb + - const: apb cdns,fifo-depth: description: diff --git a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml index 2f593c7225e5..14cac0e6e0a1 100644 --- a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml +++ b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml @@ -23,6 +23,13 @@ properties: - const: fsl,imx51-ecspi - const: fsl,imx53-ecspi - items: + - enum: + - fsl,imx25-cspi + - fsl,imx50-cspi + - fsl,imx51-cspi + - fsl,imx53-cspi + - const: fsl,imx35-cspi + - items: - const: fsl,imx8mp-ecspi - const: fsl,imx6ul-ecspi - items: diff --git a/Documentation/devicetree/bindings/spi/loongson,ls2k-spi.yaml b/Documentation/devicetree/bindings/spi/loongson,ls2k-spi.yaml new file mode 100644 index 000000000000..de9d32feadf5 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/loongson,ls2k-spi.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/loongson,ls2k-spi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Loongson SPI controller + +maintainers: + - Yinbo Zhu <zhuyinbo@loongson.cn> + +allOf: + - $ref: /schemas/spi/spi-controller.yaml# + +properties: + compatible: + oneOf: + - enum: + - loongson,ls2k1000-spi + - items: + - enum: + - loongson,ls2k0500-spi + - const: loongson,ls2k1000-spi + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - clocks + +unevaluatedProperties: false + +examples: + - | + spi0: spi@1fff0220{ + compatible = "loongson,ls2k1000-spi"; + reg = <0x1fff0220 0x10>; + clocks = <&clk 17>; + #address-cells = <1>; + #size-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra114-spi.txt b/Documentation/devicetree/bindings/spi/nvidia,tegra114-spi.txt deleted file mode 100644 index db8e0d71c5bc..000000000000 --- a/Documentation/devicetree/bindings/spi/nvidia,tegra114-spi.txt +++ /dev/null @@ -1,61 +0,0 @@ -NVIDIA Tegra114 SPI controller. - -Required properties: -- compatible : For Tegra114, must contain "nvidia,tegra114-spi". - Otherwise, must contain '"nvidia,<chip>-spi", "nvidia,tegra114-spi"' where - <chip> is tegra124, tegra132, or tegra210. -- reg: Should contain SPI registers location and length. -- interrupts: Should contain SPI interrupts. -- clock-names : Must include the following entries: - - spi -- resets : Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names : Must include the following entries: - - spi -- dmas : Must contain an entry for each entry in clock-names. - See ../dma/dma.txt for details. -- dma-names : Must include the following entries: - - rx - - tx -- clocks : Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. - -Recommended properties: -- spi-max-frequency: Definition as per - Documentation/devicetree/bindings/spi/spi-bus.txt -Optional properties: -- nvidia,tx-clk-tap-delay: Delays the clock going out to the external device - with this tap value. This property is used to tune the outgoing data from - Tegra SPI master with respect to outgoing Tegra SPI master clock. - Tap values vary based on the platform design trace lengths from Tegra SPI - to corresponding slave devices. Valid tap values are from 0 thru 63. -- nvidia,rx-clk-tap-delay: Delays the clock coming in from the external device - with this tap value. This property is used to adjust the Tegra SPI master - clock with respect to the data from the SPI slave device. - Tap values vary based on the platform design trace lengths from Tegra SPI - to corresponding slave devices. Valid tap values are from 0 thru 63. - -Example: - -spi@7000d600 { - compatible = "nvidia,tegra114-spi"; - reg = <0x7000d600 0x200>; - interrupts = <0 82 0x04>; - spi-max-frequency = <25000000>; - #address-cells = <1>; - #size-cells = <0>; - clocks = <&tegra_car 44>; - clock-names = "spi"; - resets = <&tegra_car 44>; - reset-names = "spi"; - dmas = <&apbdma 16>, <&apbdma 16>; - dma-names = "rx", "tx"; - <spi-client>@<bus_num> { - ... - ... - nvidia,rx-clk-tap-delay = <0>; - nvidia,tx-clk-tap-delay = <16>; - ... - }; - -}; diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra114-spi.yaml b/Documentation/devicetree/bindings/spi/nvidia,tegra114-spi.yaml new file mode 100644 index 000000000000..58222ffa53d7 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/nvidia,tegra114-spi.yaml @@ -0,0 +1,100 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/nvidia,tegra114-spi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra114 SPI controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + oneOf: + - const: nvidia,tegra114-spi + - items: + - enum: + - nvidia,tegra210-spi + - nvidia,tegra124-spi + - const: nvidia,tegra114-spi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: SPI module clock + + clock-names: + items: + - const: spi + + resets: + items: + - description: SPI module reset + + reset-names: + items: + - const: spi + + dmas: + items: + - description: DMA channel for the reception FIFO + - description: DMA channel for the transmission FIFO + + dma-names: + items: + - const: rx + - const: tx + + spi-max-frequency: + description: Maximum SPI clocking speed of the controller in Hz. + $ref: /schemas/types.yaml#/definitions/uint32 + +allOf: + - $ref: spi-controller.yaml + +unevaluatedProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - resets + - reset-names + - dmas + - dma-names + +examples: + - | + spi@7000d600 { + compatible = "nvidia,tegra114-spi"; + reg = <0x7000d600 0x200>; + interrupts = <0 82 0x04>; + clocks = <&tegra_car 44>; + clock-names = "spi"; + resets = <&tegra_car 44>; + reset-names = "spi"; + dmas = <&apbdma 16>, <&apbdma 16>; + dma-names = "rx", "tx"; + + spi-max-frequency = <25000000>; + + #address-cells = <1>; + #size-cells = <0>; + + flash@0 { + compatible = "jedec,spi-nor"; + reg = <0>; + spi-max-frequency = <20000000>; + nvidia,rx-clk-tap-delay = <0>; + nvidia,tx-clk-tap-delay = <16>; + }; + }; diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra20-sflash.txt b/Documentation/devicetree/bindings/spi/nvidia,tegra20-sflash.txt deleted file mode 100644 index c212491929b5..000000000000 --- a/Documentation/devicetree/bindings/spi/nvidia,tegra20-sflash.txt +++ /dev/null @@ -1,37 +0,0 @@ -NVIDIA Tegra20 SFLASH controller. - -Required properties: -- compatible : should be "nvidia,tegra20-sflash". -- reg: Should contain SFLASH registers location and length. -- interrupts: Should contain SFLASH interrupts. -- clocks : Must contain one entry, for the module clock. - See ../clocks/clock-bindings.txt for details. -- resets : Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names : Must include the following entries: - - spi -- dmas : Must contain an entry for each entry in clock-names. - See ../dma/dma.txt for details. -- dma-names : Must include the following entries: - - rx - - tx - -Recommended properties: -- spi-max-frequency: Definition as per - Documentation/devicetree/bindings/spi/spi-bus.txt - -Example: - -spi@7000c380 { - compatible = "nvidia,tegra20-sflash"; - reg = <0x7000c380 0x80>; - interrupts = <0 39 0x04>; - spi-max-frequency = <25000000>; - #address-cells = <1>; - #size-cells = <0>; - clocks = <&tegra_car 43>; - resets = <&tegra_car 43>; - reset-names = "spi"; - dmas = <&apbdma 11>, <&apbdma 11>; - dma-names = "rx", "tx"; -}; diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra20-sflash.yaml b/Documentation/devicetree/bindings/spi/nvidia,tegra20-sflash.yaml new file mode 100644 index 000000000000..e245bad85a25 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/nvidia,tegra20-sflash.yaml @@ -0,0 +1,81 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/nvidia,tegra20-sflash.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra20 SFLASH controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + const: nvidia,tegra20-sflash + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: module clock + + resets: + items: + - description: module reset + + reset-names: + items: + - const: spi + + dmas: + items: + - description: DMA channel used for reception + - description: DMA channel used for transmission + + dma-names: + items: + - const: rx + - const: tx + + spi-max-frequency: + description: Maximum SPI clocking speed of the controller in Hz. + $ref: /schemas/types.yaml#/definitions/uint32 + +allOf: + - $ref: spi-controller.yaml + +unevaluatedProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - resets + - reset-names + - dmas + - dma-names + +examples: + - | + #include <dt-bindings/clock/tegra20-car.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + spi@7000c380 { + compatible = "nvidia,tegra20-sflash"; + reg = <0x7000c380 0x80>; + interrupts = <GIC_SPI 39 IRQ_TYPE_LEVEL_HIGH>; + spi-max-frequency = <25000000>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&tegra_car TEGRA20_CLK_SPI>; + resets = <&tegra_car 43>; + reset-names = "spi"; + dmas = <&apbdma 11>, <&apbdma 11>; + dma-names = "rx", "tx"; + }; diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra20-slink.txt b/Documentation/devicetree/bindings/spi/nvidia,tegra20-slink.txt deleted file mode 100644 index 40d80b93e327..000000000000 --- a/Documentation/devicetree/bindings/spi/nvidia,tegra20-slink.txt +++ /dev/null @@ -1,37 +0,0 @@ -NVIDIA Tegra20/Tegra30 SLINK controller. - -Required properties: -- compatible : should be "nvidia,tegra20-slink", "nvidia,tegra30-slink". -- reg: Should contain SLINK registers location and length. -- interrupts: Should contain SLINK interrupts. -- clocks : Must contain one entry, for the module clock. - See ../clocks/clock-bindings.txt for details. -- resets : Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names : Must include the following entries: - - spi -- dmas : Must contain an entry for each entry in clock-names. - See ../dma/dma.txt for details. -- dma-names : Must include the following entries: - - rx - - tx - -Recommended properties: -- spi-max-frequency: Definition as per - Documentation/devicetree/bindings/spi/spi-bus.txt - -Example: - -spi@7000d600 { - compatible = "nvidia,tegra20-slink"; - reg = <0x7000d600 0x200>; - interrupts = <0 82 0x04>; - spi-max-frequency = <25000000>; - #address-cells = <1>; - #size-cells = <0>; - clocks = <&tegra_car 44>; - resets = <&tegra_car 44>; - reset-names = "spi"; - dmas = <&apbdma 16>, <&apbdma 16>; - dma-names = "rx", "tx"; -}; diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra20-slink.yaml b/Documentation/devicetree/bindings/spi/nvidia,tegra20-slink.yaml new file mode 100644 index 000000000000..291c25ec015d --- /dev/null +++ b/Documentation/devicetree/bindings/spi/nvidia,tegra20-slink.yaml @@ -0,0 +1,90 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/nvidia,tegra20-slink.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra20/30 SLINK controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + enum: + - nvidia,tegra20-slink + - nvidia,tegra30-slink + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: module clock + + resets: + items: + - description: module reset + + reset-names: + items: + - const: spi + + dmas: + items: + - description: DMA channel used for reception + - description: DMA channel used for transmission + + dma-names: + items: + - const: rx + - const: tx + + operating-points-v2: + $ref: /schemas/types.yaml#/definitions/phandle + + power-domains: + items: + - description: phandle to the core power domain + + spi-max-frequency: + description: Maximum SPI clocking speed of the controller in Hz. + $ref: /schemas/types.yaml#/definitions/uint32 + +allOf: + - $ref: spi-controller.yaml + +unevaluatedProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - resets + - reset-names + - dmas + - dma-names + +examples: + - | + #include <dt-bindings/clock/tegra20-car.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + spi@7000d600 { + compatible = "nvidia,tegra20-slink"; + reg = <0x7000d600 0x200>; + interrupts = <GIC_SPI 82 IRQ_TYPE_LEVEL_HIGH>; + spi-max-frequency = <25000000>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&tegra_car TEGRA20_CLK_SBC2>; + resets = <&tegra_car 44>; + reset-names = "spi"; + dmas = <&apbdma 16>, <&apbdma 16>; + dma-names = "rx", "tx"; + }; diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml b/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml index 9ae1611175f2..48e97e240265 100644 --- a/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml +++ b/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml @@ -50,6 +50,7 @@ properties: patternProperties: "@[0-9a-f]+$": type: object + additionalProperties: true properties: spi-rx-bus-width: diff --git a/Documentation/devicetree/bindings/spi/omap-spi.yaml b/Documentation/devicetree/bindings/spi/omap-spi.yaml index 352affa4b7f8..ff4d361707bd 100644 --- a/Documentation/devicetree/bindings/spi/omap-spi.yaml +++ b/Documentation/devicetree/bindings/spi/omap-spi.yaml @@ -68,7 +68,7 @@ properties: dma-names: description: List of DMA request names. These strings correspond 1:1 with - the DMA sepecifiers listed in dmas. The string names is to be + the DMA specifiers listed in dmas. The string names is to be "rxN" and "txN" for RX and TX requests, respectively. Where N is the chip select number. minItems: 1 diff --git a/Documentation/devicetree/bindings/spi/qcom,spi-qup.yaml b/Documentation/devicetree/bindings/spi/qcom,spi-qup.yaml index 93f14dd01afc..88be13268962 100644 --- a/Documentation/devicetree/bindings/spi/qcom,spi-qup.yaml +++ b/Documentation/devicetree/bindings/spi/qcom,spi-qup.yaml @@ -44,9 +44,17 @@ properties: - const: tx - const: rx + interconnects: + maxItems: 1 + interrupts: maxItems: 1 + operating-points-v2: true + + power-domains: + maxItems: 1 + reg: maxItems: 1 @@ -62,7 +70,9 @@ unevaluatedProperties: false examples: - | #include <dt-bindings/clock/qcom,gcc-msm8996.h> + #include <dt-bindings/interconnect/qcom,msm8996.h> #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/qcom-rpmpd.h> spi@7575000 { compatible = "qcom,spi-qup-v2.2.1"; @@ -76,6 +86,9 @@ examples: pinctrl-1 = <&blsp1_spi1_sleep>; dmas = <&blsp1_dma 12>, <&blsp1_dma 13>; dma-names = "tx", "rx"; + power-domains = <&rpmpd MSM8996_VDDCX>; + operating-points-v2 = <&spi_opp_table>; + interconnects = <&pnoc MASTER_BLSP_1 &bimc SLAVE_EBI_CH0>; #address-cells = <1>; #size-cells = <0>; }; diff --git a/Documentation/devicetree/bindings/spi/renesas,rzv2m-csi.yaml b/Documentation/devicetree/bindings/spi/renesas,rzv2m-csi.yaml index e59183e53690..bed829837df1 100644 --- a/Documentation/devicetree/bindings/spi/renesas,rzv2m-csi.yaml +++ b/Documentation/devicetree/bindings/spi/renesas,rzv2m-csi.yaml @@ -39,6 +39,12 @@ properties: power-domains: maxItems: 1 + renesas,csi-no-ss: + type: boolean + description: + The CSI Slave Selection (SS) pin won't be used to enable transmission and + reception. Only available when in target mode. + required: - compatible - reg @@ -50,6 +56,9 @@ required: - '#address-cells' - '#size-cells' +dependencies: + renesas,csi-no-ss: [ spi-slave ] + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/spi/rockchip-sfc.yaml b/Documentation/devicetree/bindings/spi/rockchip-sfc.yaml index 339fb39529f3..ac1503de0478 100644 --- a/Documentation/devicetree/bindings/spi/rockchip-sfc.yaml +++ b/Documentation/devicetree/bindings/spi/rockchip-sfc.yaml @@ -47,6 +47,8 @@ properties: patternProperties: "^flash@[0-3]$": type: object + additionalProperties: true + properties: reg: minimum: 0 diff --git a/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml b/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml index a47cb144b09f..6348a387a21c 100644 --- a/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml +++ b/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml @@ -160,6 +160,8 @@ properties: patternProperties: "^.*@[0-9a-f]+$": type: object + additionalProperties: true + properties: reg: minimum: 0 diff --git a/Documentation/devicetree/bindings/spi/spi-bcm63xx.txt b/Documentation/devicetree/bindings/spi/spi-bcm63xx.txt deleted file mode 100644 index 1c16f6692613..000000000000 --- a/Documentation/devicetree/bindings/spi/spi-bcm63xx.txt +++ /dev/null @@ -1,33 +0,0 @@ -Binding for Broadcom BCM6348/BCM6358 SPI controller - -Required properties: -- compatible: must contain one of "brcm,bcm6348-spi", "brcm,bcm6358-spi". -- reg: Base address and size of the controllers memory area. -- interrupts: Interrupt for the SPI block. -- clocks: phandle of the SPI clock. -- clock-names: has to be "spi". -- #address-cells: <1>, as required by generic SPI binding. -- #size-cells: <0>, also as required by generic SPI binding. - -Optional properties: -- num-cs: some controllers have less than 8 cs signals. Defaults to 8 - if absent. - -Child nodes as per the generic SPI binding. - -Example: - - spi@10000800 { - compatible = "brcm,bcm6368-spi", "brcm,bcm6358-spi"; - reg = <0x10000800 0x70c>; - - interrupts = <1>; - - clocks = <&clkctl 9>; - clock-names = "spi"; - - num-cs = <5>; - - #address-cells = <1>; - #size-cells = <0>; - }; diff --git a/Documentation/devicetree/bindings/spi/spi-cadence.yaml b/Documentation/devicetree/bindings/spi/spi-cadence.yaml index b7552739b554..d4b61b0e8301 100644 --- a/Documentation/devicetree/bindings/spi/spi-cadence.yaml +++ b/Documentation/devicetree/bindings/spi/spi-cadence.yaml @@ -49,6 +49,12 @@ properties: enum: [ 0, 1 ] default: 0 + power-domains: + maxItems: 1 + + label: + description: Descriptive name of the SPI controller. + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml index e91425012319..727c5346b8ce 100644 --- a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml +++ b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml @@ -63,6 +63,9 @@ properties: maximum: 2 default: 1 + power-domains: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml b/Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml index a813c971ecf6..7fd591145480 100644 --- a/Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml +++ b/Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml @@ -45,6 +45,9 @@ properties: - const: fspi_en - const: fspi + power-domains: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml index 782a014b63a7..15938f81fdce 100644 --- a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml +++ b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml @@ -113,8 +113,14 @@ properties: minItems: 2 maxItems: 4 + st,spi-midi-ns: + description: | + Only for STM32H7, (Master Inter-Data Idleness) minimum time + delay in nanoseconds inserted between two consecutive data frames. + # The controller specific properties go here. allOf: + - $ref: arm,pl022-peripheral-props.yaml# - $ref: cdns,qspi-nor-peripheral-props.yaml# - $ref: samsung,spi-peripheral-props.yaml# - $ref: nvidia,tegra210-quad-peripheral-props.yaml# diff --git a/Documentation/devicetree/bindings/spi/spi-pl022.yaml b/Documentation/devicetree/bindings/spi/spi-pl022.yaml index 91e540a92faf..7f174b7d0a26 100644 --- a/Documentation/devicetree/bindings/spi/spi-pl022.yaml +++ b/Documentation/devicetree/bindings/spi/spi-pl022.yaml @@ -11,6 +11,7 @@ maintainers: allOf: - $ref: spi-controller.yaml# + - $ref: /schemas/arm/primecell.yaml# # We need a select here so we don't match all nodes with 'arm,primecell' select: @@ -73,57 +74,6 @@ properties: resets: maxItems: 1 -patternProperties: - "^[a-zA-Z][a-zA-Z0-9,+\\-._]{0,63}@[0-9a-f]+$": - type: object - # SPI slave nodes must be children of the SPI master node and can - # contain the following properties. - properties: - pl022,interface: - description: SPI interface type - $ref: /schemas/types.yaml#/definitions/uint32 - enum: - - 0 # SPI - - 1 # Texas Instruments Synchronous Serial Frame Format - - 2 # Microwire (Half Duplex) - - pl022,com-mode: - description: Specifies the transfer mode - $ref: /schemas/types.yaml#/definitions/uint32 - enum: - - 0 # interrupt mode - - 1 # polling mode - - 2 # DMA mode - default: 1 - - pl022,rx-level-trig: - description: Rx FIFO watermark level - $ref: /schemas/types.yaml#/definitions/uint32 - minimum: 0 - maximum: 4 - - pl022,tx-level-trig: - description: Tx FIFO watermark level - $ref: /schemas/types.yaml#/definitions/uint32 - minimum: 0 - maximum: 4 - - pl022,ctrl-len: - description: Microwire interface - Control length - $ref: /schemas/types.yaml#/definitions/uint32 - minimum: 0x03 - maximum: 0x1f - - pl022,wait-state: - description: Microwire interface - Wait state - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1] - - pl022,duplex: - description: Microwire interface - Full/Half duplex - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1] - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml b/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml index 9ca1a843c820..ae0f082bd377 100644 --- a/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml +++ b/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml @@ -18,15 +18,6 @@ maintainers: allOf: - $ref: spi-controller.yaml# - - if: - properties: - compatible: - contains: - const: st,stm32f4-spi - - then: - properties: - st,spi-midi-ns: false properties: compatible: @@ -59,17 +50,6 @@ properties: - const: rx - const: tx -patternProperties: - "^[a-zA-Z][a-zA-Z0-9,+\\-._]{0,63}@[0-9a-f]+$": - type: object - # SPI slave nodes must be children of the SPI master node and can - # contain the following properties. - properties: - st,spi-midi-ns: - description: | - Only for STM32H7, (Master Inter-Data Idleness) minimum time - delay in nanoseconds inserted between two consecutive data frames. - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/sram/qcom,ocmem.yaml b/Documentation/devicetree/bindings/sram/qcom,ocmem.yaml index 4bbf6db0b6bd..61c784ef7b51 100644 --- a/Documentation/devicetree/bindings/sram/qcom,ocmem.yaml +++ b/Documentation/devicetree/bindings/sram/qcom,ocmem.yaml @@ -15,7 +15,9 @@ description: | properties: compatible: - const: qcom,msm8974-ocmem + enum: + - qcom,msm8226-ocmem # v1.1.0 + - qcom,msm8974-ocmem # v1.4.0 reg: items: @@ -28,11 +30,13 @@ properties: - const: mem clocks: + minItems: 1 items: - description: Core clock - description: Interface clock clock-names: + minItems: 1 items: - const: core - const: iface @@ -58,6 +62,26 @@ required: additionalProperties: false +allOf: + - if: + properties: + compatible: + contains: + enum: + - qcom,msm8974-ocmem + then: + properties: + clocks: + minItems: 2 + clock-names: + minItems: 2 + else: + properties: + clocks: + minItems: 1 + clock-names: + minItems: 1 + patternProperties: "-sram@[0-9a-f]+$": type: object diff --git a/Documentation/devicetree/bindings/thermal/fsl,scu-thermal.yaml b/Documentation/devicetree/bindings/thermal/fsl,scu-thermal.yaml index 3721c8c8ec64..e02d04d4f71e 100644 --- a/Documentation/devicetree/bindings/thermal/fsl,scu-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/fsl,scu-thermal.yaml @@ -18,7 +18,9 @@ allOf: properties: compatible: items: - - const: fsl,imx8qxp-sc-thermal + - enum: + - fsl,imx8dxl-sc-thermal + - fsl,imx8qxp-sc-thermal - const: fsl,imx-sc-thermal '#thermal-sensor-cells': diff --git a/Documentation/devicetree/bindings/thermal/imx-thermal.yaml b/Documentation/devicetree/bindings/thermal/imx-thermal.yaml index 3aecea77869f..808d987bd8d1 100644 --- a/Documentation/devicetree/bindings/thermal/imx-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/imx-thermal.yaml @@ -60,6 +60,9 @@ properties: clocks: maxItems: 1 + "#thermal-sensor-cells": + const: 0 + required: - compatible - interrupts @@ -67,6 +70,9 @@ required: - nvmem-cells - nvmem-cell-names +allOf: + - $ref: thermal-sensor.yaml# + additionalProperties: false examples: @@ -104,5 +110,6 @@ examples: nvmem-cells = <&tempmon_calib>, <&tempmon_temp_grade>; nvmem-cell-names = "calib", "temp_grade"; clocks = <&clks IMX6SX_CLK_PLL3_USB_OTG>; + #thermal-sensor-cells = <0>; }; }; diff --git a/Documentation/devicetree/bindings/thermal/loongson,ls2k-thermal.yaml b/Documentation/devicetree/bindings/thermal/loongson,ls2k-thermal.yaml new file mode 100644 index 000000000000..7538469997f9 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/loongson,ls2k-thermal.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/loongson,ls2k-thermal.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Thermal sensors on Loongson-2 SoCs + +maintainers: + - zhanghongchen <zhanghongchen@loongson.cn> + - Yinbo Zhu <zhuyinbo@loongson.cn> + +properties: + compatible: + oneOf: + - enum: + - loongson,ls2k1000-thermal + - items: + - enum: + - loongson,ls2k2000-thermal + - const: loongson,ls2k1000-thermal + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + thermal: thermal-sensor@1fe01500 { + compatible = "loongson,ls2k1000-thermal"; + reg = <0x1fe01500 0x30>; + interrupt-parent = <&liointc0>; + interrupts = <7 IRQ_TYPE_LEVEL_LOW>; + }; diff --git a/Documentation/devicetree/bindings/thermal/mediatek,lvts-thermal.yaml b/Documentation/devicetree/bindings/thermal/mediatek,lvts-thermal.yaml index fe9ae4c425c0..e6665af52ee6 100644 --- a/Documentation/devicetree/bindings/thermal/mediatek,lvts-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/mediatek,lvts-thermal.yaml @@ -18,6 +18,7 @@ description: | properties: compatible: enum: + - mediatek,mt7988-lvts-ap - mediatek,mt8192-lvts-ap - mediatek,mt8192-lvts-mcu - mediatek,mt8195-lvts-ap diff --git a/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.txt b/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.txt deleted file mode 100644 index aea4a2a178b9..000000000000 --- a/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.txt +++ /dev/null @@ -1,238 +0,0 @@ -Tegra124 SOCTHERM thermal management system - -The SOCTHERM IP block contains thermal sensors, support for polled -or interrupt-based thermal monitoring, CPU and GPU throttling based -on temperature trip points, and handling external overcurrent -notifications. It is also used to manage emergency shutdown in an -overheating situation. - -Required properties : -- compatible : For Tegra124, must contain "nvidia,tegra124-soctherm". - For Tegra132, must contain "nvidia,tegra132-soctherm". - For Tegra210, must contain "nvidia,tegra210-soctherm". -- reg : Should contain at least 2 entries for each entry in reg-names: - - SOCTHERM register set - - Tegra CAR register set: Required for Tegra124 and Tegra210. - - CCROC register set: Required for Tegra132. -- reg-names : Should contain at least 2 entries: - - soctherm-reg - - car-reg - - ccroc-reg -- interrupts : Defines the interrupt used by SOCTHERM -- clocks : Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names : Must include the following entries: - - tsensor - - soctherm -- resets : Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names : Must include the following entries: - - soctherm -- #thermal-sensor-cells : Should be 1. For a description of this property, see - Documentation/devicetree/bindings/thermal/thermal-sensor.yaml. - See <dt-bindings/thermal/tegra124-soctherm.h> for a list of valid values - when referring to thermal sensors. -- throttle-cfgs: A sub-node which is a container of configuration for each - hardware throttle events. These events can be set as cooling devices. - * throttle events: Sub-nodes must be named as "light" or "heavy". - Properties: - - nvidia,priority: Each throttles has its own throttle settings, so the - SW need to set priorities for various throttle, the HW arbiter can select - the final throttle settings. - Bigger value indicates higher priority, In general, higher priority - translates to lower target frequency. SW needs to ensure that critical - thermal alarms are given higher priority, and ensure that there is - no race if priority of two vectors is set to the same value. - The range of this value is 1~100. - - nvidia,cpu-throt-percent: This property is for Tegra124 and Tegra210. - It is the throttling depth of pulse skippers, it's the percentage - throttling. - - nvidia,cpu-throt-level: This property is only for Tegra132, it is the - level of pulse skippers, which used to throttle clock frequencies. It - indicates cpu clock throttling depth, and the depth can be programmed. - Must set as following values: - TEGRA_SOCTHERM_THROT_LEVEL_LOW, TEGRA_SOCTHERM_THROT_LEVEL_MED - TEGRA_SOCTHERM_THROT_LEVEL_HIGH, TEGRA_SOCTHERM_THROT_LEVEL_NONE - - nvidia,gpu-throt-level: This property is for Tegra124 and Tegra210. - It is the level of pulse skippers, which used to throttle clock - frequencies. It indicates gpu clock throttling depth and can be - programmed to any of the following values which represent a throttling - percentage: - TEGRA_SOCTHERM_THROT_LEVEL_NONE (0%) - TEGRA_SOCTHERM_THROT_LEVEL_LOW (50%), - TEGRA_SOCTHERM_THROT_LEVEL_MED (75%), - TEGRA_SOCTHERM_THROT_LEVEL_HIGH (85%). - - #cooling-cells: Should be 1. This cooling device only support on/off state. - For a description of this property see: - Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml - - Optional properties: The following properties are T210 specific and - valid only for OCx throttle events. - - nvidia,count-threshold: Specifies the number of OC events that are - required for triggering an interrupt. Interrupts are not triggered if - the property is missing. A value of 0 will interrupt on every OC alarm. - - nvidia,polarity-active-low: Configures the polarity of the OC alaram - signal. If present, this means assert low, otherwise assert high. - - nvidia,alarm-filter: Number of clocks to filter event. When the filter - expires (which means the OC event has not occurred for a long time), - the counter is cleared and filter is rearmed. Default value is 0. - - nvidia,throttle-period-us: Specifies the number of uSec for which - throttling is engaged after the OC event is deasserted. Default value - is 0. - -Optional properties: -- nvidia,thermtrips : When present, this property specifies the temperature at - which the soctherm hardware will assert the thermal trigger signal to the - Power Management IC, which can be configured to reset or shutdown the device. - It is an array of pairs where each pair represents a tsensor id followed by a - temperature in milli Celcius. In the absence of this property the critical - trip point will be used for thermtrip temperature. - -Note: -- the "critical" type trip points will be used to set the temperature at which -the SOC_THERM hardware will assert a thermal trigger if the "nvidia,thermtrips" -property is missing. When the thermtrips property is present, the breach of a -critical trip point is reported back to the thermal framework to implement -software shutdown. - -- the "hot" type trip points will be set to SOC_THERM hardware as the throttle -temperature. Once the temperature of this thermal zone is higher -than it, it will trigger the HW throttle event. - -Example : - - soctherm@700e2000 { - compatible = "nvidia,tegra124-soctherm"; - reg = <0x0 0x700e2000 0x0 0x600 /* SOC_THERM reg_base */ - 0x0 0x60006000 0x0 0x400 /* CAR reg_base */ - reg-names = "soctherm-reg", "car-reg"; - interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&tegra_car TEGRA124_CLK_TSENSOR>, - <&tegra_car TEGRA124_CLK_SOC_THERM>; - clock-names = "tsensor", "soctherm"; - resets = <&tegra_car 78>; - reset-names = "soctherm"; - - #thermal-sensor-cells = <1>; - - nvidia,thermtrips = <TEGRA124_SOCTHERM_SENSOR_CPU 102500 - TEGRA124_SOCTHERM_SENSOR_GPU 103000>; - - throttle-cfgs { - /* - * When the "heavy" cooling device triggered, - * the HW will skip cpu clock's pulse in 85% depth, - * skip gpu clock's pulse in 85% level - */ - throttle_heavy: heavy { - nvidia,priority = <100>; - nvidia,cpu-throt-percent = <85>; - nvidia,gpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_HIGH>; - - #cooling-cells = <1>; - }; - - /* - * When the "light" cooling device triggered, - * the HW will skip cpu clock's pulse in 50% depth, - * skip gpu clock's pulse in 50% level - */ - throttle_light: light { - nvidia,priority = <80>; - nvidia,cpu-throt-percent = <50>; - nvidia,gpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_LOW>; - - #cooling-cells = <1>; - }; - - /* - * If these two devices are triggered in same time, the HW throttle - * arbiter will select the highest priority as the final throttle - * settings to skip cpu pulse. - */ - - throttle_oc1: oc1 { - nvidia,priority = <50>; - nvidia,polarity-active-low; - nvidia,count-threshold = <100>; - nvidia,alarm-filter = <5100000>; - nvidia,throttle-period-us = <0>; - nvidia,cpu-throt-percent = <75>; - nvidia,gpu-throt-level = - <TEGRA_SOCTHERM_THROT_LEVEL_MED>; - }; - }; - }; - -Example: referring to Tegra132's "reg", "reg-names" and "throttle-cfgs" : - - soctherm@700e2000 { - compatible = "nvidia,tegra132-soctherm"; - reg = <0x0 0x700e2000 0x0 0x600 /* SOC_THERM reg_base */ - 0x0 0x70040000 0x0 0x200>; /* CCROC reg_base */; - reg-names = "soctherm-reg", "ccroc-reg"; - - throttle-cfgs { - /* - * When the "heavy" cooling device triggered, - * the HW will skip cpu clock's pulse in HIGH level - */ - throttle_heavy: heavy { - nvidia,priority = <100>; - nvidia,cpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_HIGH>; - - #cooling-cells = <1>; - }; - - /* - * When the "light" cooling device triggered, - * the HW will skip cpu clock's pulse in MED level - */ - throttle_light: light { - nvidia,priority = <80>; - nvidia,cpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_MED>; - - #cooling-cells = <1>; - }; - - /* - * If these two devices are triggered in same time, the HW throttle - * arbiter will select the highest priority as the final throttle - * settings to skip cpu pulse. - */ - - }; - }; - -Example: referring to thermal sensors : - - thermal-zones { - cpu { - polling-delay-passive = <1000>; - polling-delay = <1000>; - - thermal-sensors = - <&soctherm TEGRA124_SOCTHERM_SENSOR_CPU>; - - trips { - cpu_shutdown_trip: shutdown-trip { - temperature = <102500>; - hysteresis = <1000>; - type = "critical"; - }; - - cpu_throttle_trip: throttle-trip { - temperature = <100000>; - hysteresis = <1000>; - type = "hot"; - }; - }; - - cooling-maps { - map0 { - trip = <&cpu_throttle_trip>; - cooling-device = <&throttle_heavy 1 1>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.yaml b/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.yaml new file mode 100644 index 000000000000..b0237d236021 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.yaml @@ -0,0 +1,385 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/nvidia,tegra124-soctherm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra124 SOCTHERM Thermal Management System + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +description: The SOCTHERM IP block contains thermal sensors, support for + polled or interrupt-based thermal monitoring, CPU and GPU throttling based + on temperature trip points, and handling external overcurrent notifications. + It is also used to manage emergency shutdown in an overheating situation. + +properties: + compatible: + enum: + - nvidia,tegra124-soctherm + - nvidia,tegra132-soctherm + - nvidia,tegra210-soctherm + + reg: + maxItems: 2 + + reg-names: + maxItems: 2 + + interrupts: + items: + - description: module interrupt + - description: EDP interrupt + + interrupt-names: + items: + - const: thermal + - const: edp + + clocks: + items: + - description: thermal sensor clock + - description: module clock + + clock-names: + items: + - const: tsensor + - const: soctherm + + resets: + items: + - description: module reset + + reset-names: + items: + - const: soctherm + + "#thermal-sensor-cells": + const: 1 + + throttle-cfgs: + $ref: thermal-cooling-devices.yaml + description: A sub-node which is a container of configuration for each + hardware throttle events. These events can be set as cooling devices. + Throttle event sub-nodes must be named as "light" or "heavy". + unevaluatedProperties: false + patternProperties: + "^(light|heavy|oc1)$": + type: object + additionalProperties: false + + properties: + "#cooling-cells": + const: 2 + + nvidia,priority: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + maximum: 100 + description: Each throttles has its own throttle settings, so the + SW need to set priorities for various throttle, the HW arbiter + can select the final throttle settings. Bigger value indicates + higher priority, In general, higher priority translates to lower + target frequency. SW needs to ensure that critical thermal + alarms are given higher priority, and ensure that there is no + race if priority of two vectors is set to the same value. + + nvidia,cpu-throt-percent: + description: This property is for Tegra124 and Tegra210. It is the + throttling depth of pulse skippers, it's the percentage + throttling. + minimum: 0 + maximum: 100 + + nvidia,cpu-throt-level: + $ref: /schemas/types.yaml#/definitions/uint32 + description: This property is only for Tegra132, it is the level + of pulse skippers, which used to throttle clock frequencies. It + indicates cpu clock throttling depth, and the depth can be + programmed. + enum: + # none (TEGRA_SOCTHERM_THROT_LEVEL_NONE) + - 0 + # low (TEGRA_SOCTHERM_THROT_LEVEL_LOW) + - 1 + # medium (TEGRA_SOCTHERM_THROT_LEVEL_MED) + - 2 + # high (TEGRA_SOCTHERM_THROT_LEVEL_HIGH) + - 3 + + nvidia,gpu-throt-level: + $ref: /schemas/types.yaml#/definitions/uint32 + description: This property is for Tegra124 and Tegra210. It is the + level of pulse skippers, which used to throttle clock + frequencies. It indicates gpu clock throttling depth and can be + programmed to any of the following values which represent a + throttling percentage. + enum: + # none (0%, TEGRA_SOCTHERM_THROT_LEVEL_NONE) + - 0 + # low (50%, TEGRA_SOCTHERM_THROT_LEVEL_LOW) + - 1 + # medium (75%, TEGRA_SOCTHERM_THROT_LEVEL_MED) + - 2 + # high (85%, TEGRA_SOCTHERM_THROT_LEVEL_HIGH) + - 3 + + # optional + # Tegra210 specific and valid only for OCx throttle events + nvidia,count-threshold: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Specifies the number of OC events that are required + for triggering an interrupt. Interrupts are not triggered if the + property is missing. A value of 0 will interrupt on every OC + alarm. + + nvidia,polarity-active-low: + $ref: /schemas/types.yaml#/definitions/flag + description: Configures the polarity of the OC alaram signal. If + present, this means assert low, otherwise assert high. + + nvidia,alarm-filter: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Number of clocks to filter event. When the filter + expires (which means the OC event has not occurred for a long + time), the counter is cleared and filter is rearmed. + default: 0 + + nvidia,throttle-period-us: + description: Specifies the number of microseconds for which + throttling is engaged after the OC event is deasserted. + default: 0 + + # optional + nvidia,thermtrips: + $ref: /schemas/types.yaml#/definitions/uint32-matrix + description: | + When present, this property specifies the temperature at which the + SOCTHERM hardware will assert the thermal trigger signal to the Power + Management IC, which can be configured to reset or shutdown the device. + It is an array of pairs where each pair represents a tsensor ID followed + by a temperature in milli Celcius. In the absence of this property the + critical trip point will be used for thermtrip temperature. + + Note: + - the "critical" type trip points will be used to set the temperature at + which the SOCTHERM hardware will assert a thermal trigger if the + "nvidia,thermtrips" property is missing. When the thermtrips property + is present, the breach of a critical trip point is reported back to + the thermal framework to implement software shutdown. + + - the "hot" type trip points will be set to SOCTHERM hardware as the + throttle temperature. Once the temperature of this thermal zone is + higher than it, it will trigger the HW throttle event. + items: + items: + - description: sensor ID + oneOf: + - description: CPU sensor + const: 0 + - description: MEM sensor + const: 1 + - description: GPU sensor + const: 2 + - description: PLLX sensor + const: 3 + - description: temperature threshold (in millidegree Celsius) + +required: + - compatible + - reg + - reg-names + - interrupts + - interrupt-names + - clocks + - clock-names + - resets + - reset-names + - "#thermal-sensor-cells" + +allOf: + - $ref: thermal-sensor.yaml + - if: + properties: + compatible: + contains: + enum: + - nvidia,tegra124-soctherm + - nvidia,tegra210-soctherm + then: + properties: + reg: + items: + - description: SOCTHERM register set + - description: clock and reset controller registers + + reg-names: + items: + - const: soctherm-reg + - const: car-reg + + else: + properties: + reg: + items: + - description: SOCTHERM register set + - description: CCROC registers + + reg-names: + items: + - const: soctherm-reg + - const: ccroc-reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/tegra124-car.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/thermal/tegra124-soctherm.h> + + soctherm@700e2000 { + compatible = "nvidia,tegra124-soctherm"; + reg = <0x700e2000 0x600>, /* SOC_THERM reg_base */ + <0x60006000 0x400>; /* CAR reg_base */ + reg-names = "soctherm-reg", "car-reg"; + interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 51 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "thermal", "edp"; + clocks = <&tegra_car TEGRA124_CLK_TSENSOR>, + <&tegra_car TEGRA124_CLK_SOC_THERM>; + clock-names = "tsensor", "soctherm"; + resets = <&tegra_car 78>; + reset-names = "soctherm"; + + #thermal-sensor-cells = <1>; + + nvidia,thermtrips = <TEGRA124_SOCTHERM_SENSOR_CPU 102500>, + <TEGRA124_SOCTHERM_SENSOR_GPU 103000>; + + throttle-cfgs { + /* + * When the "heavy" cooling device triggered, + * the HW will skip cpu clock's pulse in 85% depth, + * skip gpu clock's pulse in 85% level + */ + heavy { + nvidia,priority = <100>; + nvidia,cpu-throt-percent = <85>; + nvidia,gpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_HIGH>; + + #cooling-cells = <2>; + }; + + /* + * When the "light" cooling device triggered, + * the HW will skip cpu clock's pulse in 50% depth, + * skip gpu clock's pulse in 50% level + */ + light { + nvidia,priority = <80>; + nvidia,cpu-throt-percent = <50>; + nvidia,gpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_LOW>; + + #cooling-cells = <2>; + }; + + /* + * If these two devices are triggered in same time, the HW throttle + * arbiter will select the highest priority as the final throttle + * settings to skip cpu pulse. + */ + + oc1 { + nvidia,priority = <50>; + nvidia,polarity-active-low; + nvidia,count-threshold = <100>; + nvidia,alarm-filter = <5100000>; + nvidia,throttle-period-us = <0>; + nvidia,cpu-throt-percent = <75>; + nvidia,gpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_MED>; + }; + }; + }; + + # referring to Tegra132's "reg", "reg-names" and "throttle-cfgs" + - | + thermal-sensor@700e2000 { + compatible = "nvidia,tegra132-soctherm"; + reg = <0x700e2000 0x600>, /* SOC_THERM reg_base */ + <0x70040000 0x200>; /* CCROC reg_base */ + reg-names = "soctherm-reg", "ccroc-reg"; + interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 51 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "thermal", "edp"; + clocks = <&tegra_car TEGRA124_CLK_TSENSOR>, + <&tegra_car TEGRA124_CLK_SOC_THERM>; + clock-names = "tsensor", "soctherm"; + resets = <&tegra_car 78>; + reset-names = "soctherm"; + #thermal-sensor-cells = <1>; + + throttle-cfgs { + /* + * When the "heavy" cooling device triggered, + * the HW will skip cpu clock's pulse in HIGH level + */ + heavy { + nvidia,priority = <100>; + nvidia,cpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_HIGH>; + + #cooling-cells = <2>; + }; + + /* + * When the "light" cooling device triggered, + * the HW will skip cpu clock's pulse in MED level + */ + light { + nvidia,priority = <80>; + nvidia,cpu-throt-level = <TEGRA_SOCTHERM_THROT_LEVEL_MED>; + + #cooling-cells = <2>; + }; + + /* + * If these two devices are triggered in same time, the HW throttle + * arbiter will select the highest priority as the final throttle + * settings to skip cpu pulse. + */ + }; + }; + + # referring to thermal sensors + - | + thermal-zones { + cpu-thermal { + polling-delay-passive = <1000>; + polling-delay = <1000>; + + thermal-sensors = <&soctherm TEGRA124_SOCTHERM_SENSOR_CPU>; + + trips { + cpu_shutdown_trip: shutdown-trip { + temperature = <102500>; + hysteresis = <1000>; + type = "critical"; + }; + + cpu_throttle_trip: throttle-trip { + temperature = <100000>; + hysteresis = <1000>; + type = "hot"; + }; + }; + + cooling-maps { + map0 { + trip = <&cpu_throttle_trip>; + cooling-device = <&throttle_heavy 1 1>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/thermal/qcom-lmh.yaml b/Documentation/devicetree/bindings/thermal/qcom-lmh.yaml index 92762efc2120..5ff72ce5c887 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-lmh.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-lmh.yaml @@ -8,7 +8,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Limits Management Hardware(LMh) maintainers: - - Thara Gopinath <thara.gopinath@linaro.org> + - Thara Gopinath <thara.gopinath@gmail.com> description: Limits Management Hardware(LMh) is a hardware infrastructure on some diff --git a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml index 27e9e16e6455..437b74732886 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml @@ -51,6 +51,7 @@ properties: - qcom,msm8996-tsens - qcom,msm8998-tsens - qcom,qcm2290-tsens + - qcom,sa8775p-tsens - qcom,sc7180-tsens - qcom,sc7280-tsens - qcom,sc8180x-tsens diff --git a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml index 4f3acdc4dec0..4a8dabc48170 100644 --- a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml +++ b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml @@ -8,7 +8,7 @@ $schema: http://devicetree.org/meta-schemas/base.yaml# title: Thermal zone maintainers: - - Amit Kucheria <amitk@kernel.org> + - Daniel Lezcano <daniel.lezcano@linaro.org> description: | Thermal management is achieved in devicetree by describing the sensor hardware diff --git a/Documentation/devicetree/bindings/timer/cirrus,ep9301-timer.yaml b/Documentation/devicetree/bindings/timer/cirrus,ep9301-timer.yaml new file mode 100644 index 000000000000..e463e11e259d --- /dev/null +++ b/Documentation/devicetree/bindings/timer/cirrus,ep9301-timer.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/cirrus,ep9301-timer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cirrus Logic EP93xx timer + +maintainers: + - Alexander Sverdlin <alexander.sverdlin@gmail.com> + - Nikita Shubin <nikita.shubin@maquefel.me> + +properties: + compatible: + oneOf: + - const: cirrus,ep9301-timer + - items: + - enum: + - cirrus,ep9302-timer + - cirrus,ep9307-timer + - cirrus,ep9312-timer + - cirrus,ep9315-timer + - const: cirrus,ep9301-timer + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + timer@80810000 { + compatible = "cirrus,ep9301-timer"; + reg = <0x80810000 0x100>; + interrupt-parent = <&vic1>; + interrupts = <19>; + }; +... diff --git a/Documentation/devicetree/bindings/timer/fsl,imxgpt.yaml b/Documentation/devicetree/bindings/timer/fsl,imxgpt.yaml index dbe1267af06a..e2607377cbae 100644 --- a/Documentation/devicetree/bindings/timer/fsl,imxgpt.yaml +++ b/Documentation/devicetree/bindings/timer/fsl,imxgpt.yaml @@ -36,7 +36,9 @@ properties: - fsl,imxrt1170-gpt - const: fsl,imx6dl-gpt - items: - - const: fsl,imx6ul-gpt + - enum: + - fsl,imx6ul-gpt + - fsl,imx7d-gpt - const: fsl,imx6sx-gpt reg: @@ -46,14 +48,18 @@ properties: maxItems: 1 clocks: + minItems: 2 items: - description: SoC GPT ipg clock - description: SoC GPT per clock + - description: SoC GPT osc per clock clock-names: + minItems: 2 items: - const: ipg - const: per + - const: osc_per required: - compatible @@ -62,6 +68,29 @@ required: - clocks - clock-names +allOf: + - if: + properties: + compatible: + contains: + enum: + - fsl,imx6dl-gpt + - fsl,imx6q-gpt + then: + properties: + clocks: + minItems: 2 + maxItems: 3 + clock-names: + minItems: 2 + maxItems: 3 + else: + properties: + clocks: + maxItems: 2 + clock-names: + maxItems: 2 + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml b/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml index 2d14610888a7..585b5f5217c4 100644 --- a/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml +++ b/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml @@ -8,7 +8,7 @@ title: Ingenic SoCs Timer/Counter Unit (TCU) description: | For a description of the TCU hardware and drivers, have a look at - Documentation/mips/ingenic-tcu.rst. + Documentation/arch/mips/ingenic-tcu.rst. maintainers: - Paul Cercueil <paul@crapouillou.net> diff --git a/Documentation/devicetree/bindings/timer/oxsemi,rps-timer.txt b/Documentation/devicetree/bindings/timer/oxsemi,rps-timer.txt deleted file mode 100644 index d191612539e8..000000000000 --- a/Documentation/devicetree/bindings/timer/oxsemi,rps-timer.txt +++ /dev/null @@ -1,17 +0,0 @@ -Oxford Semiconductor OXNAS SoCs Family RPS Timer -================================================ - -Required properties: -- compatible: Should be "oxsemi,ox810se-rps-timer" or "oxsemi,ox820-rps-timer" -- reg : Specifies base physical address and size of the registers. -- interrupts : The interrupts of the two timers -- clocks : The phandle of the timer clock source - -example: - -timer0: timer@200 { - compatible = "oxsemi,ox810se-rps-timer"; - reg = <0x200 0x40>; - clocks = <&rpsclk>; - interrupts = <4 5>; -}; diff --git a/Documentation/devicetree/bindings/timer/renesas,rz-mtu3.yaml b/Documentation/devicetree/bindings/timer/renesas,rz-mtu3.yaml index bffdab0b0185..3931054b42fb 100644 --- a/Documentation/devicetree/bindings/timer/renesas,rz-mtu3.yaml +++ b/Documentation/devicetree/bindings/timer/renesas,rz-mtu3.yaml @@ -11,8 +11,8 @@ maintainers: description: | This hardware block consists of eight 16-bit timer channels and one - 32- bit timer channel. It supports the following specifications: - - Pulse input/output: 28 lines max. + 32-bit timer channel. It supports the following specifications: + - Pulse input/output: 28 lines max - Pulse input 3 lines - Count clock 11 clocks for each channel (14 clocks for MTU0, 12 clocks for MTU2, and 10 clocks for MTU5, four clocks for MTU1-MTU2 combination @@ -23,11 +23,11 @@ description: | - Input capture function (noise filter setting available) - Counter-clearing operation - Simultaneous writing to multiple timer counters (TCNT) - (excluding MTU8). + (excluding MTU8) - Simultaneous clearing on compare match or input capture - (excluding MTU8). + (excluding MTU8) - Simultaneous input and output to registers in synchronization with - counter operations (excluding MTU8). + counter operations (excluding MTU8) - Up to 12-phase PWM output in combination with synchronous operation (excluding MTU8) - [MTU0 MTU3, MTU4, MTU6, MTU7, and MTU8] @@ -40,26 +40,26 @@ description: | - [MTU3, MTU4, MTU6, and MTU7] - Through interlocked operation of MTU3/4 and MTU6/7, the positive and negative signals in six phases (12 phases in total) can be output in - complementary PWM and reset-synchronized PWM operation. + complementary PWM and reset-synchronized PWM operation - In complementary PWM mode, values can be transferred from buffer registers to temporary registers at crests and troughs of the timer- counter values or when the buffer registers (TGRD registers in MTU4 - and MTU7) are written to. - - Double-buffering selectable in complementary PWM mode. + and MTU7) are written to + - Double-buffering selectable in complementary PWM mode - [MTU3 and MTU4] - Through interlocking with MTU0, a mode for driving AC synchronous motors (brushless DC motors) by using complementary PWM output and reset-synchronized PWM output is settable and allows the selection - of two types of waveform output (chopping or level). + of two types of waveform output (chopping or level) - [MTU5] - - Capable of operation as a dead-time compensation counter. + - Capable of operation as a dead-time compensation counter - [MTU0/MTU5, MTU1, MTU2, and MTU8] - 32-bit phase counting mode specifiable by combining MTU1 and MTU2 and - through interlocked operation with MTU0/MTU5 and MTU8. + through interlocked operation with MTU0/MTU5 and MTU8 - Interrupt-skipping function - In complementary PWM mode, interrupts on crests and troughs of counter values and triggers to start conversion by the A/D converter can be - skipped. + skipped - Interrupt sources: 43 sources. - Buffer operation: - Automatic transfer of register data (transfer from the buffer @@ -68,9 +68,9 @@ description: | - A/D converter start triggers can be generated - A/D converter start request delaying function enables A/D converter to be started with any desired timing and to be synchronized with - PWM output. + PWM output - Low power consumption function - - The MTU3a can be placed in the module-stop state. + - The MTU3a can be placed in the module-stop state There are two phase counting modes. 16-bit phase counting mode in which MTU1 and MTU2 operate independently, and cascade connection 32-bit phase @@ -109,6 +109,7 @@ properties: compatible: items: - enum: + - renesas,r9a07g043-mtu3 # RZ/{G2UL,Five} - renesas,r9a07g044-mtu3 # RZ/G2{L,LC} - renesas,r9a07g054-mtu3 # RZ/V2L - const: renesas,rz-mtu3 @@ -169,27 +170,27 @@ properties: - const: tgib0 - const: tgic0 - const: tgid0 - - const: tgiv0 + - const: tciv0 - const: tgie0 - const: tgif0 - const: tgia1 - const: tgib1 - - const: tgiv1 - - const: tgiu1 + - const: tciv1 + - const: tciu1 - const: tgia2 - const: tgib2 - - const: tgiv2 - - const: tgiu2 + - const: tciv2 + - const: tciu2 - const: tgia3 - const: tgib3 - const: tgic3 - const: tgid3 - - const: tgiv3 + - const: tciv3 - const: tgia4 - const: tgib4 - const: tgic4 - const: tgid4 - - const: tgiv4 + - const: tciv4 - const: tgiu5 - const: tgiv5 - const: tgiw5 @@ -197,18 +198,18 @@ properties: - const: tgib6 - const: tgic6 - const: tgid6 - - const: tgiv6 + - const: tciv6 - const: tgia7 - const: tgib7 - const: tgic7 - const: tgid7 - - const: tgiv7 + - const: tciv7 - const: tgia8 - const: tgib8 - const: tgic8 - const: tgid8 - - const: tgiv8 - - const: tgiu8 + - const: tciv8 + - const: tciu8 clocks: maxItems: 1 @@ -285,16 +286,16 @@ examples: <GIC_SPI 211 IRQ_TYPE_EDGE_RISING>, <GIC_SPI 212 IRQ_TYPE_EDGE_RISING>, <GIC_SPI 213 IRQ_TYPE_EDGE_RISING>; - interrupt-names = "tgia0", "tgib0", "tgic0", "tgid0", "tgiv0", "tgie0", + interrupt-names = "tgia0", "tgib0", "tgic0", "tgid0", "tciv0", "tgie0", "tgif0", - "tgia1", "tgib1", "tgiv1", "tgiu1", - "tgia2", "tgib2", "tgiv2", "tgiu2", - "tgia3", "tgib3", "tgic3", "tgid3", "tgiv3", - "tgia4", "tgib4", "tgic4", "tgid4", "tgiv4", + "tgia1", "tgib1", "tciv1", "tciu1", + "tgia2", "tgib2", "tciv2", "tciu2", + "tgia3", "tgib3", "tgic3", "tgid3", "tciv3", + "tgia4", "tgib4", "tgic4", "tgid4", "tciv4", "tgiu5", "tgiv5", "tgiw5", - "tgia6", "tgib6", "tgic6", "tgid6", "tgiv6", - "tgia7", "tgib7", "tgic7", "tgid7", "tgiv7", - "tgia8", "tgib8", "tgic8", "tgid8", "tgiv8", "tgiu8"; + "tgia6", "tgib6", "tgic6", "tgid6", "tciv6", + "tgia7", "tgib7", "tgic7", "tgid7", "tciv7", + "tgia8", "tgib8", "tgic8", "tgid8", "tciv8", "tciu8"; clocks = <&cpg CPG_MOD R9A07G044_MTU_X_MCK_MTU3>; power-domains = <&cpg>; resets = <&cpg R9A07G044_MTU_X_PRESET_MTU3>; diff --git a/Documentation/devicetree/bindings/timer/sifive,clint.yaml b/Documentation/devicetree/bindings/timer/sifive,clint.yaml index a0185e15a42f..e8be6c470364 100644 --- a/Documentation/devicetree/bindings/timer/sifive,clint.yaml +++ b/Documentation/devicetree/bindings/timer/sifive,clint.yaml @@ -37,6 +37,7 @@ properties: - items: - enum: - allwinner,sun20i-d1-clint + - sophgo,cv1800b-clint - thead,th1520-clint - const: thead,c900-clint - items: diff --git a/Documentation/devicetree/bindings/timer/snps,arc-timer.txt b/Documentation/devicetree/bindings/timer/snps,arc-timer.txt index 147ef3e74452..b02ab0af10ce 100644 --- a/Documentation/devicetree/bindings/timer/snps,arc-timer.txt +++ b/Documentation/devicetree/bindings/timer/snps,arc-timer.txt @@ -1,7 +1,7 @@ Synopsys ARC Local Timer with Interrupt Capabilities - Found on all ARC CPUs (ARC700/ARCHS) - Can be optionally programmed to interrupt on Limit -- Two idential copies TIMER0 and TIMER1 exist in ARC cores and historically +- Two identical copies TIMER0 and TIMER1 exist in ARC cores and historically TIMER0 used as clockevent provider (true for all ARC cores) TIMER1 used for clocksource (mandatory for ARC700, optional for ARC HS) diff --git a/Documentation/devicetree/bindings/timer/thead,c900-aclint-mtimer.yaml b/Documentation/devicetree/bindings/timer/thead,c900-aclint-mtimer.yaml new file mode 100644 index 000000000000..fbd235650e52 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/thead,c900-aclint-mtimer.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/thead,c900-aclint-mtimer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sophgo CLINT Timer + +maintainers: + - Inochi Amaoto <inochiama@outlook.com> + +properties: + compatible: + items: + - enum: + - sophgo,sg2042-aclint-mtimer + - const: thead,c900-aclint-mtimer + + reg: + maxItems: 1 + + interrupts-extended: + minItems: 1 + maxItems: 4095 + +additionalProperties: false + +required: + - compatible + - reg + - interrupts-extended + +examples: + - | + timer@ac000000 { + compatible = "sophgo,sg2042-aclint-mtimer", "thead,c900-aclint-mtimer"; + interrupts-extended = <&cpu1intc 7>, + <&cpu2intc 7>, + <&cpu3intc 7>, + <&cpu4intc 7>; + reg = <0xac000000 0x00010000>; + }; +... diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index ba2bfb547909..9a1443ec3aaa 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -119,6 +119,10 @@ properties: - fsl,mpr121 # 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 # Honeywell Humidicon HIH-6130 humidity/temperature sensor @@ -147,8 +151,6 @@ properties: - infineon,slb9645tt # Infineon SLB9673 I2C TPM 2.0 - infineon,slb9673 - # Infineon TDA38640 Voltage Regulator - - infineon,tda38640 # Infineon TLV493D-A1B6 I2C 3D Magnetic Sensor - infineon,tlv493d-a1b6 # Infineon Multi-phase Digital VR Controller xdpe11280 @@ -193,13 +195,13 @@ properties: - maxim,max1237 # Temperature Sensor, I2C interface - maxim,max1619 - # 10-bit 10 kOhm linear programable voltage divider + # 10-bit 10 kOhm linear programmable voltage divider - maxim,max5481 - # 10-bit 50 kOhm linear programable voltage divider + # 10-bit 50 kOhm linear programmable voltage divider - maxim,max5482 - # 10-bit 10 kOhm linear programable variable resistor + # 10-bit 10 kOhm linear programmable variable resistor - maxim,max5483 - # 10-bit 50 kOhm linear programable variable resistor + # 10-bit 50 kOhm linear programmable variable resistor - maxim,max5484 # PECI-to-I2C translator for PECI-to-SMBus/I2C protocol conversion - maxim,max6621 @@ -228,7 +230,7 @@ properties: # MEMSIC magnetometer - memsic,mmc35240 # MEMSIC 3-axis accelerometer - - memsic,mx4005 + - memsic,mxc4005 # MEMSIC 2-axis 8-bit digital accelerometer - memsic,mxc6225 # MEMSIC 2-axis 8-bit digital accelerometer @@ -291,8 +293,6 @@ properties: - miramems,da311 # Temperature sensor with integrated fan control - national,lm63 - # I2C TEMP SENSOR - - national,lm75 # Serial Interface ACPI-Compatible Microprocessor System Hardware Monitor - national,lm80 # Serial Interface ACPI-Compatible Microprocessor System Hardware Monitor @@ -315,6 +315,8 @@ properties: - plx,pex8648 # Pulsedlight LIDAR range-finding sensor - pulsedlight,lidar-lite-v2 + # Renesas HS3001 Temperature and Relative Humidity Sensors + - renesas,hs3001 # Renesas ISL29501 time-of-flight sensor - renesas,isl29501 # Rohm DH2228FV diff --git a/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml b/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml index bdfa86a0cc98..462ead5a1cec 100644 --- a/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml +++ b/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml @@ -29,6 +29,7 @@ properties: - qcom,sa8775p-ufshc - qcom,sc8280xp-ufshc - qcom,sdm845-ufshc + - qcom,sm6115-ufshc - qcom,sm6350-ufshc - qcom,sm8150-ufshc - qcom,sm8250-ufshc @@ -79,6 +80,11 @@ properties: minItems: 1 maxItems: 2 + reg-names: + items: + - const: std + - const: ice + required-opps: maxItems: 1 @@ -134,6 +140,8 @@ allOf: reg: minItems: 1 maxItems: 1 + reg-names: + maxItems: 1 - if: properties: @@ -162,6 +170,10 @@ allOf: reg: minItems: 2 maxItems: 2 + reg-names: + minItems: 2 + required: + - reg-names - if: properties: @@ -190,6 +202,37 @@ allOf: reg: minItems: 1 maxItems: 1 + reg-names: + maxItems: 1 + + - if: + properties: + compatible: + contains: + enum: + - qcom,sm6115-ufshc + then: + properties: + clocks: + minItems: 8 + maxItems: 8 + clock-names: + items: + - const: core_clk + - const: bus_aggr_clk + - const: iface_clk + - const: core_clk_unipro + - const: ref_clk + - const: tx_lane0_sync_clk + - const: rx_lane0_sync_clk + - const: ice_core_clk + reg: + minItems: 2 + maxItems: 2 + reg-names: + minItems: 2 + required: + - reg-names # TODO: define clock bindings for qcom,msm8994-ufshc @@ -274,5 +317,6 @@ examples: <0 0>, <0 0>, <0 0>; + qcom,ice = <&ice>; }; }; diff --git a/Documentation/devicetree/bindings/ufs/ufs-common.yaml b/Documentation/devicetree/bindings/ufs/ufs-common.yaml index 47a4e9e1a775..985ea8f64de8 100644 --- a/Documentation/devicetree/bindings/ufs/ufs-common.yaml +++ b/Documentation/devicetree/bindings/ufs/ufs-common.yaml @@ -20,11 +20,25 @@ properties: items: - description: Minimum frequency for given clock in Hz - description: Maximum frequency for given clock in Hz + deprecated: true description: | + Preferred is operating-points-v2. + Array of <min max> operating frequencies in Hz stored in the same order - as the clocks property. If this property is not defined or a value in the - array is "0" then it is assumed that the frequency is set by the parent - clock or a fixed rate clock source. + as the clocks property. If either this property or operating-points-v2 is + not defined or a value in the array is "0" then it is assumed that the + frequency is set by the parent clock or a fixed rate clock source. + + operating-points-v2: + description: + Preferred over freq-table-hz. + If present, each OPP must contain array of frequencies stored in the same + order for each clock. If clock frequency in the array is "0" then it is + assumed that the frequency is set by the parent clock or a fixed rate + clock source. + + opp-table: + type: object interrupts: maxItems: 1 @@ -74,9 +88,24 @@ properties: Specifies max. load that can be drawn from VCCQ2 supply. dependencies: - freq-table-hz: [ 'clocks' ] + freq-table-hz: [ clocks ] + operating-points-v2: [ clocks, clock-names ] required: - interrupts +allOf: + - if: + required: + - freq-table-hz + then: + properties: + operating-points-v2: false + - if: + required: + - operating-points-v2 + then: + properties: + freq-table-hz: false + additionalProperties: true diff --git a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.yaml b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.yaml index 782402800d4a..1394557517b1 100644 --- a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.yaml +++ b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.yaml @@ -34,6 +34,7 @@ properties: - fsl,imx23-usb - fsl,imx25-usb - fsl,imx28-usb + - fsl,imx35-usb - fsl,imx50-usb - fsl,imx51-usb - fsl,imx53-usb @@ -76,11 +77,11 @@ properties: clocks: minItems: 1 - maxItems: 2 + maxItems: 3 clock-names: minItems: 1 - maxItems: 2 + maxItems: 3 dr_mode: true @@ -167,7 +168,7 @@ properties: at RTL is 0, so this property only affects siTD. If this property is not set, the max packet size is 1023 bytes, and - if the total of packet size for pervious transactions are more than + if the total of packet size for previous transactions are more than 256 bytes, it can't accept any transactions within this frame. The use case is single transaction, but higher frame rate. @@ -292,6 +293,18 @@ properties: minimum: 0x0 maximum: 0xf + fsl,picophy-rise-fall-time-adjust: + description: + HS Transmitter Rise/Fall Time Adjustment. Adjust the rise/fall times + of the high-speed transmitter waveform. It has no unit. The rise/fall + time will be increased or decreased by a certain percentage relative + to design default time. (0:-10%; 1:design default; 2:+15%; 3:+20%) + Details can refer to TXRISETUNE0 bit of USBNC_n_PHY_CFG1. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 3 + default: 1 + usb-phy: description: phandle for the PHY device. Use "phys" instead. $ref: /schemas/types.yaml#/definitions/phandle diff --git a/Documentation/devicetree/bindings/usb/cypress,cypd4226.yaml b/Documentation/devicetree/bindings/usb/cypress,cypd4226.yaml index 75eec4a9a020..89fc9a434d05 100644 --- a/Documentation/devicetree/bindings/usb/cypress,cypd4226.yaml +++ b/Documentation/devicetree/bindings/usb/cypress,cypd4226.yaml @@ -43,10 +43,8 @@ properties: patternProperties: '^connector@[01]$': $ref: /schemas/connector/usb-connector.yaml# - unevaluatedProperties: false - properties: - reg: - maxItems: 1 + required: + - reg required: - compatible diff --git a/Documentation/devicetree/bindings/usb/cypress,hx3.yaml b/Documentation/devicetree/bindings/usb/cypress,hx3.yaml new file mode 100644 index 000000000000..47add0d85fb8 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/cypress,hx3.yaml @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/cypress,hx3.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cypress HX3 USB 3.0 hub controller family + +maintainers: + - Benjamin Bara <benjamin.bara@skidata.com> + +allOf: + - $ref: usb-device.yaml# + +properties: + compatible: + enum: + - usb4b4,6504 + - usb4b4,6506 + + reg: true + + reset-gpios: + items: + - description: GPIO specifier for RESETN pin. + + vdd-supply: + description: + 1V2 power supply (VDD_EFUSE, AVDD12, DVDD12). + + vdd2-supply: + description: + 3V3 power supply (AVDD33, VDD_IO). + + peer-hub: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle to the peer hub on the controller. + +required: + - compatible + - reg + - peer-hub + - vdd-supply + - vdd2-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + usb { + dr_mode = "host"; + #address-cells = <1>; + #size-cells = <0>; + + /* 2.0 hub on port 1 */ + hub_2_0: hub@1 { + compatible = "usb4b4,6504"; + reg = <1>; + peer-hub = <&hub_3_0>; + reset-gpios = <&gpio1 11 GPIO_ACTIVE_LOW>; + vdd-supply = <®_1v2_usb>; + vdd2-supply = <®_3v3_usb>; + }; + + /* 3.0 hub on port 2 */ + hub_3_0: hub@2 { + compatible = "usb4b4,6506"; + reg = <2>; + peer-hub = <&hub_2_0>; + reset-gpios = <&gpio1 11 GPIO_ACTIVE_LOW>; + vdd-supply = <®_1v2_usb>; + vdd2-supply = <®_3v3_usb>; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml b/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml index 3fb4feb6d3d9..9ea1e4cd0709 100644 --- a/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml @@ -52,7 +52,7 @@ properties: fsl,permanently-attached: type: boolean description: - Indicates if the device atached to a downstream port is + Indicates if the device attached to a downstream port is permanently attached. fsl,disable-port-power-control: diff --git a/Documentation/devicetree/bindings/usb/generic-ehci.yaml b/Documentation/devicetree/bindings/usb/generic-ehci.yaml index b956bb5fada7..87986c45be88 100644 --- a/Documentation/devicetree/bindings/usb/generic-ehci.yaml +++ b/Documentation/devicetree/bindings/usb/generic-ehci.yaml @@ -38,6 +38,7 @@ properties: - allwinner,sun8i-a83t-ehci - allwinner,sun8i-h3-ehci - allwinner,sun8i-r40-ehci + - allwinner,sun8i-v3s-ehci - allwinner,sun9i-a80-ehci - allwinner,sun20i-d1-ehci - aspeed,ast2400-ehci @@ -67,6 +68,7 @@ properties: - const: generic-ehci - items: - enum: + - atmel,at91sam9g45-ehci - cavium,octeon-6335-ehci - ibm,usb-ehci-440epx - ibm,usb-ehci-460ex diff --git a/Documentation/devicetree/bindings/usb/generic-ohci.yaml b/Documentation/devicetree/bindings/usb/generic-ohci.yaml index be268e23ca79..b9576015736b 100644 --- a/Documentation/devicetree/bindings/usb/generic-ohci.yaml +++ b/Documentation/devicetree/bindings/usb/generic-ohci.yaml @@ -25,6 +25,7 @@ properties: - allwinner,sun8i-a83t-ohci - allwinner,sun8i-h3-ohci - allwinner,sun8i-r40-ohci + - allwinner,sun8i-v3s-ohci - allwinner,sun9i-a80-ohci - allwinner,sun20i-d1-ohci - brcm,bcm3384-ohci diff --git a/Documentation/devicetree/bindings/usb/genesys,gl850g.yaml b/Documentation/devicetree/bindings/usb/genesys,gl850g.yaml index cc4cf92b70d1..d0927f6768a4 100644 --- a/Documentation/devicetree/bindings/usb/genesys,gl850g.yaml +++ b/Documentation/devicetree/bindings/usb/genesys,gl850g.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/genesys,gl850g.yaml# @@ -17,6 +17,7 @@ properties: enum: - usb5e3,608 - usb5e3,610 + - usb5e3,620 reg: true diff --git a/Documentation/devicetree/bindings/usb/msm-hsusb.txt b/Documentation/devicetree/bindings/usb/msm-hsusb.txt index 8654a3ec23e4..afc30e98b123 100644 --- a/Documentation/devicetree/bindings/usb/msm-hsusb.txt +++ b/Documentation/devicetree/bindings/usb/msm-hsusb.txt @@ -53,7 +53,7 @@ Optional properties: - dr_mode: One of "host", "peripheral" or "otg". Defaults to "otg" - switch-gpio: A phandle + gpio-specifier pair. Some boards are using Dual - SPDT USB Switch, witch is cotrolled by GPIO to de/multiplex + SPDT USB Switch, witch is controlled by GPIO to de/multiplex D+/D- USB lines between connectors. - qcom,phy-init-sequence: PHY configuration sequence values. This is related to Device diff --git a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml index ae24dac78d9a..67591057f234 100644 --- a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml @@ -14,6 +14,7 @@ properties: items: - enum: - qcom,ipq4019-dwc3 + - qcom,ipq5332-dwc3 - qcom,ipq6018-dwc3 - qcom,ipq8064-dwc3 - qcom,ipq8074-dwc3 @@ -82,15 +83,6 @@ properties: minItems: 1 maxItems: 9 - assigned-clocks: - items: - - description: Phandle and clock specifier of MOCK_UTMI_CLK. - - description: Phandle and clock specifoer of MASTER_CLK. - - assigned-clock-rates: - items: - - description: Must be 19.2MHz (19200000). - - description: Must be >= 60 MHz in HS mode, >= 125 MHz in SS mode. resets: maxItems: 1 @@ -246,6 +238,7 @@ allOf: compatible: contains: enum: + - qcom,ipq5332-dwc3 - qcom,msm8994-dwc3 - qcom,qcs404-dwc3 then: @@ -290,15 +283,23 @@ allOf: then: properties: clocks: - minItems: 6 + minItems: 5 + maxItems: 6 clock-names: - items: - - const: cfg_noc - - const: core - - const: iface - - const: sleep - - const: mock_utmi - - const: bus + oneOf: + - items: + - const: cfg_noc + - const: core + - const: iface + - const: sleep + - const: mock_utmi + - const: bus + - items: + - const: cfg_noc + - const: core + - const: sleep + - const: mock_utmi + - const: bus - if: properties: @@ -410,6 +411,7 @@ allOf: compatible: contains: enum: + - qcom,ipq5332-dwc3 - qcom,sdm660-dwc3 then: properties: diff --git a/Documentation/devicetree/bindings/usb/realtek,rts5411.yaml b/Documentation/devicetree/bindings/usb/realtek,rts5411.yaml index 9309f003cd07..f0784d2e86da 100644 --- a/Documentation/devicetree/bindings/usb/realtek,rts5411.yaml +++ b/Documentation/devicetree/bindings/usb/realtek,rts5411.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/realtek,rts5411.yaml# diff --git a/Documentation/devicetree/bindings/usb/richtek,rt1719.yaml b/Documentation/devicetree/bindings/usb/richtek,rt1719.yaml index 4ced2f68e2a9..07bec1fe6ebf 100644 --- a/Documentation/devicetree/bindings/usb/richtek,rt1719.yaml +++ b/Documentation/devicetree/bindings/usb/richtek,rt1719.yaml @@ -10,7 +10,7 @@ maintainers: - ChiYuan Huang <cy_huang@richtek.com> description: | - The RT1719 is a sink-only USB Type-C contoller that complies with the latest + The RT1719 is a sink-only USB Type-C controller that complies with the latest USB Type-C and PD standards. It does the USB Type-C detection including attach and orientation. It integrates the physical layer of the USB BMC power delivery protocol to allow up to 100W of power. The BMC PD block enables full diff --git a/Documentation/devicetree/bindings/usb/rockchip,dwc3.yaml b/Documentation/devicetree/bindings/usb/rockchip,dwc3.yaml index 291844c8f3e1..c983dfe0f629 100644 --- a/Documentation/devicetree/bindings/usb/rockchip,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/rockchip,dwc3.yaml @@ -15,7 +15,7 @@ description: Phy documentation is provided in the following places. USB2.0 PHY - Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.yaml + Documentation/devicetree/bindings/phy/rockchip,inno-usb2phy.yaml Type-C PHY Documentation/devicetree/bindings/phy/phy-rockchip-typec.txt diff --git a/Documentation/devicetree/bindings/usb/samsung,exynos-dwc3.yaml b/Documentation/devicetree/bindings/usb/samsung,exynos-dwc3.yaml index 42ceaf13cd5d..1ade99e85ba8 100644 --- a/Documentation/devicetree/bindings/usb/samsung,exynos-dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/samsung,exynos-dwc3.yaml @@ -15,6 +15,7 @@ properties: - samsung,exynos5250-dwusb3 - samsung,exynos5433-dwusb3 - samsung,exynos7-dwusb3 + - samsung,exynos850-dwusb3 '#address-cells': const: 1 @@ -72,7 +73,7 @@ allOf: properties: compatible: contains: - const: samsung,exynos54333-dwusb3 + const: samsung,exynos5433-dwusb3 then: properties: clocks: @@ -82,8 +83,8 @@ allOf: items: - const: aclk - const: susp_clk - - const: pipe_pclk - const: phyclk + - const: pipe_pclk - if: properties: @@ -101,6 +102,21 @@ allOf: - const: usbdrd30_susp_clk - const: usbdrd30_axius_clk + - if: + properties: + compatible: + contains: + const: samsung,exynos850-dwusb3 + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + items: + - const: bus_early + - const: ref + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/usb/samsung-hsotg.txt b/Documentation/devicetree/bindings/usb/samsung-hsotg.txt deleted file mode 100644 index 0388634598ce..000000000000 --- a/Documentation/devicetree/bindings/usb/samsung-hsotg.txt +++ /dev/null @@ -1,38 +0,0 @@ -Samsung High Speed USB OTG controller ------------------------------ - -The Samsung HSOTG IP can be found on Samsung SoCs, from S3C6400 onwards. -It gives functionality of OTG-compliant USB 2.0 host and device with -support for USB 2.0 high-speed (480Mbps) and full-speed (12 Mbps) -operation. - -Currently only device mode is supported. - -Binding details ------ - -Required properties: -- compatible: "samsung,s3c6400-hsotg" should be used for all currently - supported SoC, -- interrupts: specifier of interrupt signal of interrupt controller, - according to bindings of interrupt controller, -- clocks: contains an array of clock specifiers: - - first entry: OTG clock -- clock-names: contains array of clock names: - - first entry: must be "otg" -- vusb_d-supply: phandle to voltage regulator of digital section, -- vusb_a-supply: phandle to voltage regulator of analog section. - -Example ------ - - hsotg@12480000 { - compatible = "samsung,s3c6400-hsotg"; - reg = <0x12480000 0x20000>; - interrupts = <0 71 0>; - clocks = <&clock 305>; - clock-names = "otg"; - vusb_d-supply = <&vusb_reg>; - vusb_a-supply = <&vusbdac_reg>; - }; - diff --git a/Documentation/devicetree/bindings/usb/ti,tps6598x.yaml b/Documentation/devicetree/bindings/usb/ti,tps6598x.yaml index 5497a60cddbc..6ab674dea4c6 100644 --- a/Documentation/devicetree/bindings/usb/ti,tps6598x.yaml +++ b/Documentation/devicetree/bindings/usb/ti,tps6598x.yaml @@ -32,11 +32,14 @@ properties: items: - const: irq + connector: + $ref: /schemas/connector/usb-connector.yaml# + required: - compatible - reg -additionalProperties: true +additionalProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/usb/ti,usb8041.yaml b/Documentation/devicetree/bindings/usb/ti,usb8041.yaml index 88ea6c952c66..c2e29bd61e11 100644 --- a/Documentation/devicetree/bindings/usb/ti,usb8041.yaml +++ b/Documentation/devicetree/bindings/usb/ti,usb8041.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/ti,usb8041.yaml# diff --git a/Documentation/devicetree/bindings/usb/vialab,vl817.yaml b/Documentation/devicetree/bindings/usb/vialab,vl817.yaml index 23a13e1d5c7a..76db9071b352 100644 --- a/Documentation/devicetree/bindings/usb/vialab,vl817.yaml +++ b/Documentation/devicetree/bindings/usb/vialab,vl817.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/vialab,vl817.yaml# diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index af60bf1a6664..309b94c328c8 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -59,6 +59,8 @@ patternProperties: description: AD Holdings Plc. "^adi,.*": description: Analog Devices, Inc. + "^adieng,.*": + description: ADI Engineering, Inc. "^advantech,.*": description: Advantech Corporation "^aeroflexgaisler,.*": @@ -127,6 +129,8 @@ patternProperties: description: Arasan Chip Systems "^archermind,.*": description: ArcherMind Technology (Nanjing) Co., Ltd. + "^arcom,.*": + description: Arcom Controllers "^arctic,.*": description: Arctic Sand "^arcx,.*": @@ -190,8 +194,12 @@ patternProperties: description: Compass Electronics Group, LLC "^beagle,.*": description: BeagleBoard.org Foundation + "^belling,.*": + description: Shanghai Belling Co., Ltd. "^bhf,.*": description: Beckhoff Automation GmbH & Co. KG + "^bigtreetech,.*": + description: Shenzhen BigTree Tech Co., LTD "^bitmain,.*": description: Bitmain Technologies "^blutek,.*": @@ -482,6 +490,8 @@ patternProperties: description: FocalTech Systems Co.,Ltd "^forlinx,.*": description: Baoding Forlinx Embedded Technology Co., Ltd. + "^freecom,.*": + description: Freecom Gmbh "^frida,.*": description: Shenzhen Frida LCD Co., Ltd. "^friendlyarm,.*": @@ -494,6 +504,8 @@ patternProperties: description: FX Technology Ltd. "^gardena,.*": description: GARDENA GmbH + "^gateway,.*": + description: Gateway Communications "^gateworks,.*": description: Gateworks Corporation "^gcw,.*": @@ -508,6 +520,8 @@ patternProperties: description: GE Fanuc Intelligent Platforms Embedded Systems, Inc. "^gemei,.*": description: Gemei Digital Technology Co., Ltd. + "^gemtek,.*": + description: Gemtek Technology Co., Ltd. "^genesys,.*": description: Genesys Logic, Inc. "^geniatech,.*": @@ -528,6 +542,8 @@ patternProperties: description: Shenzhen Huiding Technology Co., Ltd. "^google,.*": description: Google, Inc. + "^goramo,.*": + description: Goramo Gorecki "^gplus,.*": description: GPLUS "^grinn,.*": @@ -617,6 +633,8 @@ patternProperties: description: Imagination Technologies Ltd. "^imi,.*": description: Integrated Micro-Electronics Inc. + "^inanbo,.*": + description: Shenzhen INANBO Electronic Technology Co., Ltd. "^incircuit,.*": description: In-Circuit GmbH "^indiedroid,.*": @@ -675,6 +693,8 @@ patternProperties: description: iWave Systems Technologies Pvt. Ltd. "^jadard,.*": description: Jadard Technology Inc. + "^jasonic,.*": + description: Jasonic Technology Ltd. "^jdi,.*": description: Japan Display Inc. "^jedec,.*": @@ -799,6 +819,8 @@ patternProperties: description: Mantix Display Technology Co.,Ltd. "^mapleboard,.*": description: Mapleboard.org + "^marantec,.*": + description: Marantec electronics GmbH "^marvell,.*": description: Marvell Technology Group Ltd. "^maxbotix,.*": @@ -857,6 +879,8 @@ patternProperties: description: MikroElektronika d.o.o. "^mikrotik,.*": description: MikroTik + "^milkv,.*": + description: MilkV Technology Co., Ltd "^miniand,.*": description: Miniand Tech "^minix,.*": @@ -865,6 +889,8 @@ patternProperties: description: MiraMEMS Sensing Technology Co., Ltd. "^mitsubishi,.*": description: Mitsubishi Electric Corporation + "^mitsumi,.*": + description: Mitsumi Electric Co., Ltd. "^mixel,.*": description: Mixel, Inc. "^miyoo,.*": @@ -1075,6 +1101,8 @@ patternProperties: description: Powertip Tech. Corp. "^powervr,.*": description: PowerVR (deprecated, use img) + "^powkiddy,.*": + description: Powkiddy "^primux,.*": description: Primux Trading, S.L. "^probox2,.*": @@ -1151,6 +1179,8 @@ patternProperties: description: Shenzhen Roofull Technology Co, Ltd "^roseapplepi,.*": description: RoseapplePi.org + "^saef,.*": + description: Saef Technology Limited "^samsung,.*": description: Samsung Semiconductor "^samtec,.*": @@ -1265,6 +1295,8 @@ patternProperties: description: Solomon Systech Limited "^sony,.*": description: Sony Corporation + "^sophgo,.*": + description: Sophgo Technology Inc. "^sourceparts,.*": description: Source Parts Inc. "^spansion,.*": @@ -1412,6 +1444,8 @@ patternProperties: description: Truly Semiconductors Limited "^tsd,.*": description: Theobroma Systems Design und Consulting GmbH + "^turing,.*": + description: Turing Machines, Inc. "^tyan,.*": description: Tyan Computer Corporation "^u-blox,.*": @@ -1436,6 +1470,8 @@ patternProperties: description: United Radiant Technology Corporation "^usi,.*": description: Universal Scientific Industrial Co., Ltd. + "^usr,.*": + description: U.S. Robotics Corporation "^utoo,.*": description: Aigo Digital Technology Co., Ltd. "^v3,.*": diff --git a/Documentation/devicetree/bindings/watchdog/amlogic,meson-gxbb-wdt.yaml b/Documentation/devicetree/bindings/watchdog/amlogic,meson-gxbb-wdt.yaml index f5cc7aa1b93b..443e2e7ab467 100644 --- a/Documentation/devicetree/bindings/watchdog/amlogic,meson-gxbb-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/amlogic,meson-gxbb-wdt.yaml @@ -17,6 +17,7 @@ properties: compatible: enum: - amlogic,meson-gxbb-wdt + - amlogic,t7-wdt reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/watchdog/atmel,at91rm9200-wdt.yaml b/Documentation/devicetree/bindings/watchdog/atmel,at91rm9200-wdt.yaml new file mode 100644 index 000000000000..7af3571d89f2 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/atmel,at91rm9200-wdt.yaml @@ -0,0 +1,33 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/watchdog/atmel,at91rm9200-wdt.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Atmel AT91RM9200 System Timer Watchdog + +maintainers: + - Nicolas Ferre <nicolas.ferre@microchip.com> + +allOf: + - $ref: watchdog.yaml# + +properties: + compatible: + const: atmel,at91rm9200-wdt + + reg: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + watchdog@fffffd00 { + compatible = "atmel,at91rm9200-wdt"; + reg = <0xfffffd00 0x10>; + }; diff --git a/Documentation/devicetree/bindings/watchdog/atmel-at91rm9200-wdt.txt b/Documentation/devicetree/bindings/watchdog/atmel-at91rm9200-wdt.txt deleted file mode 100644 index d4d86cf8f9eb..000000000000 --- a/Documentation/devicetree/bindings/watchdog/atmel-at91rm9200-wdt.txt +++ /dev/null @@ -1,9 +0,0 @@ -Atmel AT91RM9200 System Timer Watchdog - -Required properties: -- compatible: must be "atmel,at91sam9260-wdt". - -Example: - watchdog@fffffd00 { - compatible = "atmel,at91rm9200-wdt"; - }; diff --git a/Documentation/devicetree/bindings/watchdog/cnxt,cx92755-wdt.yaml b/Documentation/devicetree/bindings/watchdog/cnxt,cx92755-wdt.yaml new file mode 100644 index 000000000000..1844d7e026fe --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/cnxt,cx92755-wdt.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/watchdog/cnxt,cx92755-wdt.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Conexant Digicolor SoCs Watchdog timer + +description: | + The watchdog functionality in Conexant Digicolor SoCs relies on the so called + "Agent Communication" block. This block includes the eight programmable system + timer counters. The first timer (called "Timer A") is the only one that can be + used as watchdog. + +allOf: + - $ref: watchdog.yaml# + +maintainers: + - Baruch Siach <baruch@tkos.co.il> + +properties: + compatible: + const: cnxt,cx92755-wdt + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - clocks + +unevaluatedProperties: false + +examples: + - | + watchdog@f0000fc0 { + compatible = "cnxt,cx92755-wdt"; + reg = <0xf0000fc0 0x8>; + clocks = <&main_clk>; + timeout-sec = <15>; + }; diff --git a/Documentation/devicetree/bindings/watchdog/da9062-wdt.txt b/Documentation/devicetree/bindings/watchdog/da9062-wdt.txt deleted file mode 100644 index 354314d854ef..000000000000 --- a/Documentation/devicetree/bindings/watchdog/da9062-wdt.txt +++ /dev/null @@ -1,34 +0,0 @@ -* Dialog Semiconductor DA9062/61 Watchdog Timer - -Required properties: - -- compatible: should be one of the following valid compatible string lines: - "dlg,da9061-watchdog", "dlg,da9062-watchdog" - "dlg,da9062-watchdog" - -Optional properties: -- dlg,use-sw-pm: Add this property to disable the watchdog during suspend. - Only use this option if you can't use the watchdog automatic suspend - function during a suspend (see register CONTROL_B). -- dlg,wdt-sd: Set what happens on watchdog timeout. If this bit is set the - watchdog timeout triggers SHUTDOWN, if cleared the watchdog triggers - POWERDOWN. Can be 0 or 1. Only use this option if you want to change the - default chip's OTP setting for WATCHDOG_SD bit. If this property is NOT - set the WATCHDOG_SD bit and on timeout watchdog behavior will match the - chip's OTP settings. - -Example: DA9062 - - pmic0: da9062@58 { - watchdog { - compatible = "dlg,da9062-watchdog"; - }; - }; - -Example: DA9061 using a fall-back compatible for the DA9062 watchdog driver - - pmic0: da9061@58 { - watchdog { - compatible = "dlg,da9061-watchdog", "dlg,da9062-watchdog"; - }; - }; diff --git a/Documentation/devicetree/bindings/watchdog/digicolor-wdt.txt b/Documentation/devicetree/bindings/watchdog/digicolor-wdt.txt deleted file mode 100644 index a882967e17d4..000000000000 --- a/Documentation/devicetree/bindings/watchdog/digicolor-wdt.txt +++ /dev/null @@ -1,25 +0,0 @@ -Conexant Digicolor SoCs Watchdog timer - -The watchdog functionality in Conexant Digicolor SoCs relies on the so called -"Agent Communication" block. This block includes the eight programmable system -timer counters. The first timer (called "Timer A") is the only one that can be -used as watchdog. - -Required properties: - -- compatible : Should be "cnxt,cx92755-wdt" -- reg : Specifies base physical address and size of the registers -- clocks : phandle; specifies the clock that drives the timer - -Optional properties: - -- timeout-sec : Contains the watchdog timeout in seconds - -Example: - - watchdog@f0000fc0 { - compatible = "cnxt,cx92755-wdt"; - reg = <0xf0000fc0 0x8>; - clocks = <&main_clk>; - timeout-sec = <15>; - }; diff --git a/Documentation/devicetree/bindings/watchdog/dlg,da9062-watchdog.yaml b/Documentation/devicetree/bindings/watchdog/dlg,da9062-watchdog.yaml new file mode 100644 index 000000000000..f058628bb632 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/dlg,da9062-watchdog.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/watchdog/dlg,da9062-watchdog.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Dialog Semiconductor DA9062/61 Watchdog Timer + +maintainers: + - Steve Twiss <stwiss.opensource@diasemi.com> + +allOf: + - $ref: watchdog.yaml# + +properties: + compatible: + enum: + - dlg,da9061-watchdog + - dlg,da9062-watchdog + + dlg,use-sw-pm: + type: boolean + description: + Add this property to disable the watchdog during suspend. + Only use this option if you can't use the watchdog automatic suspend + function during a suspend (see register CONTROL_B). + + dlg,wdt-sd: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + description: + Set what happens on watchdog timeout. If this bit is set the + watchdog timeout triggers SHUTDOWN, if cleared the watchdog triggers + POWERDOWN. Can be 0 or 1. Only use this option if you want to change the + default chip's OTP setting for WATCHDOG_SD bit. If this property is NOT + set the WATCHDOG_SD bit and on timeout watchdog behavior will match the + chip's OTP settings. + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + watchdog { + compatible = "dlg,da9062-watchdog"; + dlg,use-sw-pm; + dlg,wdt-sd = <1>; + }; diff --git a/Documentation/devicetree/bindings/watchdog/fsl,scu-wdt.yaml b/Documentation/devicetree/bindings/watchdog/fsl,scu-wdt.yaml index 47701248cd8d..8b7aa922249b 100644 --- a/Documentation/devicetree/bindings/watchdog/fsl,scu-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/fsl,scu-wdt.yaml @@ -18,7 +18,9 @@ allOf: properties: compatible: items: - - const: fsl,imx8qxp-sc-wdt + - enum: + - fsl,imx8dxl-sc-wdt + - fsl,imx8qxp-sc-wdt - const: fsl,imx-sc-wdt required: diff --git a/Documentation/devicetree/bindings/watchdog/loongson,ls1x-wdt.yaml b/Documentation/devicetree/bindings/watchdog/loongson,ls1x-wdt.yaml new file mode 100644 index 000000000000..81690d4b62a6 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/loongson,ls1x-wdt.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/watchdog/loongson,ls1x-wdt.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Loongson-1 Watchdog Timer + +maintainers: + - Keguang Zhang <keguang.zhang@gmail.com> + +allOf: + - $ref: watchdog.yaml# + +properties: + compatible: + enum: + - loongson,ls1b-wdt + - loongson,ls1c-wdt + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - clocks + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/loongson,ls1x-clk.h> + watchdog: watchdog@1fe5c060 { + compatible = "loongson,ls1b-wdt"; + reg = <0x1fe5c060 0xc>; + + clocks = <&clkc LS1X_CLKID_APB>; + }; diff --git a/Documentation/devicetree/bindings/watchdog/marvell,cn10624-wdt.yaml b/Documentation/devicetree/bindings/watchdog/marvell,cn10624-wdt.yaml new file mode 100644 index 000000000000..1b583f232e53 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/marvell,cn10624-wdt.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/watchdog/marvell,cn10624-wdt.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell Global Timer (GTI) system watchdog + +maintainers: + - Bharat Bhushan <bbhushan2@marvell.com> + +allOf: + - $ref: watchdog.yaml# + +properties: + compatible: + oneOf: + - enum: + - marvell,cn9670-wdt + - marvell,cn10624-wdt + + - items: + - enum: + - marvell,cn9880-wdt + - marvell,cnf9535-wdt + - const: marvell,cn9670-wdt + + - items: + - enum: + - marvell,cn10308-wdt + - marvell,cnf10518-wdt + - const: marvell,cn10624-wdt + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: refclk + + marvell,wdt-timer-index: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 63 + description: + An SoC have many timers (up to 64), firmware can reserve one or more timer + for some other use case and configures one of the global timer as watchdog + timer. Firmware will update this field with the timer number configured + as watchdog timer. + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + soc { + #address-cells = <2>; + #size-cells = <2>; + + watchdog@802000040000 { + compatible = "marvell,cn9670-wdt"; + reg = <0x00008020 0x00040000 0x00000000 0x00020000>; + interrupts = <GIC_SPI 38 IRQ_TYPE_EDGE_RISING>; + clocks = <&sclk>; + clock-names = "refclk"; + marvell,wdt-timer-index = <63>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml b/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml index 6d0fe6abd06a..5046dfa55f13 100644 --- a/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml @@ -18,6 +18,7 @@ properties: - items: - enum: - qcom,kpss-wdt-ipq4019 + - qcom,apss-wdt-ipq5018 - qcom,apss-wdt-ipq5332 - qcom,apss-wdt-ipq9574 - qcom,apss-wdt-msm8994 diff --git a/Documentation/devicetree/bindings/watchdog/ti,rti-wdt.yaml b/Documentation/devicetree/bindings/watchdog/ti,rti-wdt.yaml index fc553211e42d..62ddc284a524 100644 --- a/Documentation/devicetree/bindings/watchdog/ti,rti-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/ti,rti-wdt.yaml @@ -34,6 +34,20 @@ properties: power-domains: maxItems: 1 + memory-region: + maxItems: 1 + description: + Contains the watchdog reserved memory. It is optional. + In the reserved memory, the specified values, which are + PON_REASON_SOF_NUM(0xBBBBCCCC), PON_REASON_MAGIC_NUM(0xDDDDDDDD), + and PON_REASON_EOF_NUM(0xCCCCBBBB), are pre-stored at the first + 3 * 4 bytes to tell that last boot was caused by watchdog reset. + Once the PON reason is captured by driver(rti_wdt.c), the driver + is supposed to wipe the whole memory region. Surely, if this + property is set, at least 12 bytes reserved memory starting from + specific memory address(0xa220000) should be set. More please + refer to example. + required: - compatible - reg @@ -47,7 +61,18 @@ examples: /* * RTI WDT in main domain on J721e SoC. Assigned clocks are used to * select the source clock for the watchdog, forcing it to tick with - * a 32kHz clock in this case. + * a 32kHz clock in this case. Add a reserved memory(optional) to keep + * the watchdog reset cause persistent, which was be written in 12 bytes + * starting from 0xa2200000 by RTI Watchdog Firmware, then make it + * possible to get watchdog reset cause in driver. + * + * Reserved memory should be defined as follows: + * reserved-memory { + * wdt_reset_memory_region: wdt-memory@a2200000 { + * reg = <0x00 0xa2200000 0x00 0x1000>; + * no-map; + * }; + * } */ #include <dt-bindings/soc/ti,sci_pm_domain.h> @@ -58,4 +83,5 @@ examples: power-domains = <&k3_pds 252 TI_SCI_PD_EXCLUSIVE>; assigned-clocks = <&k3_clks 252 1>; assigned-clock-parents = <&k3_clks 252 5>; + memory-region = <&wdt_reset_memory_region>; }; diff --git a/Documentation/devicetree/bindings/watchdog/toshiba,visconti-wdt.yaml b/Documentation/devicetree/bindings/watchdog/toshiba,visconti-wdt.yaml index 51d03d5b08ad..3e9fd49d935e 100644 --- a/Documentation/devicetree/bindings/watchdog/toshiba,visconti-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/toshiba,visconti-wdt.yaml @@ -2,8 +2,8 @@ # Copyright 2020 Toshiba Electronic Devices & Storage Corporation %YAML 1.2 --- -$id: "http://devicetree.org/schemas/watchdog/toshiba,visconti-wdt.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/watchdog/toshiba,visconti-wdt.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Toshiba Visconti SoCs PIUWDT Watchdog timer diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst index 4a381d20f2b4..0a6cf19a1459 100644 --- a/Documentation/devicetree/bindings/writing-schema.rst +++ b/Documentation/devicetree/bindings/writing-schema.rst @@ -159,11 +159,14 @@ It is possible to run both in a single command:: make dt_binding_check dtbs_check It is also possible to run checks with a subset of matching schema files by -setting the ``DT_SCHEMA_FILES`` variable to a specific schema file or pattern. +setting the ``DT_SCHEMA_FILES`` variable to 1 or more specific schema files or +patterns (partial match of a fixed string). Each file or pattern should be +separated by ':'. :: make dt_binding_check DT_SCHEMA_FILES=trivial-devices.yaml + make dt_binding_check DT_SCHEMA_FILES=trivial-devices.yaml:rtc.yaml make dt_binding_check DT_SCHEMA_FILES=/gpio/ make dtbs_check DT_SCHEMA_FILES=trivial-devices.yaml diff --git a/Documentation/doc-guide/contributing.rst b/Documentation/doc-guide/contributing.rst index d4793826ad9a..662c7a840cd5 100644 --- a/Documentation/doc-guide/contributing.rst +++ b/Documentation/doc-guide/contributing.rst @@ -138,6 +138,10 @@ times, but it's highly important. If we can actually eliminate warnings from the documentation build, then we can start expecting developers to avoid adding new ones. +In addition to warnings from the regular documentation build, you can also +run ``make refcheckdocs`` to find references to nonexistent documentation +files. + Languishing kerneldoc comments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 1dcbd7332476..6ad72ac6861b 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -151,9 +151,9 @@ named ``Return``. line breaks, so if you try to format some text nicely, as in:: * Return: - * 0 - OK - * -EINVAL - invalid argument - * -ENOMEM - out of memory + * %0 - OK + * %-EINVAL - invalid argument + * %-ENOMEM - out of memory this will all run together and produce:: @@ -163,8 +163,8 @@ named ``Return``. ReST list, e. g.:: * Return: - * * 0 - OK to runtime suspend the device - * * -EBUSY - Device should not be runtime suspended + * * %0 - OK to runtime suspend the device + * * %-EBUSY - Device should not be runtime suspended #) If the descriptive text you provide has lines that begin with some phrase followed by a colon, each of those phrases will be taken diff --git a/Documentation/driver-api/80211/mac80211.rst b/Documentation/driver-api/80211/mac80211.rst index 67d2e58b45e4..e38a220401f5 100644 --- a/Documentation/driver-api/80211/mac80211.rst +++ b/Documentation/driver-api/80211/mac80211.rst @@ -120,7 +120,7 @@ functions/definitions ieee80211_rx ieee80211_rx_ni ieee80211_rx_irqsafe - ieee80211_tx_status + ieee80211_tx_status_skb ieee80211_tx_status_ni ieee80211_tx_status_irqsafe ieee80211_rts_get diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst index 7671b531ba1a..d78b7c328ff7 100644 --- a/Documentation/driver-api/basics.rst +++ b/Documentation/driver-api/basics.rst @@ -15,8 +15,8 @@ Driver device table :no-identifiers: pci_device_id -Delaying, scheduling, and timer routines ----------------------------------------- +Delaying and scheduling routines +-------------------------------- .. kernel-doc:: include/linux/sched.h :internal: @@ -33,16 +33,16 @@ Delaying, scheduling, and timer routines .. kernel-doc:: include/linux/completion.h :internal: -.. kernel-doc:: kernel/time/timer.c - :export: - -Wait queues and Wake events ---------------------------- +Time and timer routines +----------------------- -.. kernel-doc:: include/linux/wait.h +.. kernel-doc:: include/linux/jiffies.h :internal: -.. kernel-doc:: kernel/sched/wait.c +.. kernel-doc:: kernel/time/time.c + :export: + +.. kernel-doc:: kernel/time/timer.c :export: High-resolution timers @@ -57,6 +57,15 @@ High-resolution timers .. kernel-doc:: kernel/time/hrtimer.c :export: +Wait queues and Wake events +--------------------------- + +.. kernel-doc:: include/linux/wait.h + :internal: + +.. kernel-doc:: kernel/sched/wait.c + :export: + Internal Functions ------------------ diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index f92a32d095d9..0c153d79ccc4 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -5,14 +5,30 @@ The dma-buf subsystem provides the framework for sharing buffers for hardware (DMA) access across multiple device drivers and subsystems, and for synchronizing asynchronous hardware access. -This is used, for example, by drm "prime" multi-GPU support, but is of -course not limited to GPU use cases. - -The three main components of this are: (1) dma-buf, representing a -sg_table and exposed to userspace as a file descriptor to allow passing -between devices, (2) fence, which provides a mechanism to signal when -one device has finished access, and (3) reservation, which manages the -shared or exclusive fence(s) associated with the buffer. +As an example, it is used extensively by the DRM subsystem to exchange +buffers between processes, contexts, library APIs within the same +process, and also to exchange buffers with other subsystems such as +V4L2. + +This document describes the way in which kernel subsystems can use and +interact with the three main primitives offered by dma-buf: + + - dma-buf, representing a sg_table and exposed to userspace as a file + descriptor to allow passing between processes, subsystems, devices, + etc; + - dma-fence, providing a mechanism to signal when an asynchronous + hardware operation has completed; and + - dma-resv, which manages a set of dma-fences for a particular dma-buf + allowing implicit (kernel-ordered) synchronization of work to + preserve the illusion of coherent access + + +Userspace API principles and use +-------------------------------- + +For more details on how to design your subsystem's API for dma-buf use, please +see Documentation/userspace-api/dma-buf-alloc-exchange.rst. + Shared DMA Buffers ------------------ diff --git a/Documentation/driver-api/dpll.rst b/Documentation/driver-api/dpll.rst new file mode 100644 index 000000000000..e3d593841aa7 --- /dev/null +++ b/Documentation/driver-api/dpll.rst @@ -0,0 +1,551 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============================== +The Linux kernel dpll subsystem +=============================== + +DPLL +==== + +PLL - Phase Locked Loop is an electronic circuit which syntonizes clock +signal of a device with an external clock signal. Effectively enabling +device to run on the same clock signal beat as provided on a PLL input. + +DPLL - Digital Phase Locked Loop is an integrated circuit which in +addition to plain PLL behavior incorporates a digital phase detector +and may have digital divider in the loop. As a result, the frequency on +DPLL's input and output may be configurable. + +Subsystem +========= + +The main purpose of dpll subsystem is to provide general interface +to configure devices that use any kind of Digital PLL and could use +different sources of input signal to synchronize to, as well as +different types of outputs. +The main interface is NETLINK_GENERIC based protocol with an event +monitoring multicast group defined. + +Device object +============= + +Single dpll device object means single Digital PLL circuit and bunch of +connected pins. +It reports the supported modes of operation and current status to the +user in response to the `do` request of netlink command +``DPLL_CMD_DEVICE_GET`` and list of dplls registered in the subsystem +with `dump` netlink request of the same command. +Changing the configuration of dpll device is done with `do` request of +netlink ``DPLL_CMD_DEVICE_SET`` command. +A device handle is ``DPLL_A_ID``, it shall be provided to get or set +configuration of particular device in the system. It can be obtained +with a ``DPLL_CMD_DEVICE_GET`` `dump` request or +a ``DPLL_CMD_DEVICE_ID_GET`` `do` request, where the one must provide +attributes that result in single device match. + +Pin object +========== + +A pin is amorphic object which represents either input or output, it +could be internal component of the device, as well as externally +connected. +The number of pins per dpll vary, but usually multiple pins shall be +provided for a single dpll device. +Pin's properties, capabilities and status is provided to the user in +response to `do` request of netlink ``DPLL_CMD_PIN_GET`` command. +It is also possible to list all the pins that were registered in the +system with `dump` request of ``DPLL_CMD_PIN_GET`` command. +Configuration of a pin can be changed by `do` request of netlink +``DPLL_CMD_PIN_SET`` command. +Pin handle is a ``DPLL_A_PIN_ID``, it shall be provided to get or set +configuration of particular pin in the system. It can be obtained with +``DPLL_CMD_PIN_GET`` `dump` request or ``DPLL_CMD_PIN_ID_GET`` `do` +request, where user provides attributes that result in single pin match. + +Pin selection +============= + +In general, selected pin (the one which signal is driving the dpll +device) can be obtained from ``DPLL_A_PIN_STATE`` attribute, and only +one pin shall be in ``DPLL_PIN_STATE_CONNECTED`` state for any dpll +device. + +Pin selection can be done either manually or automatically, depending +on hardware capabilities and active dpll device work mode +(``DPLL_A_MODE`` attribute). The consequence is that there are +differences for each mode in terms of available pin states, as well as +for the states the user can request for a dpll device. + +In manual mode (``DPLL_MODE_MANUAL``) the user can request or receive +one of following pin states: + +- ``DPLL_PIN_STATE_CONNECTED`` - the pin is used to drive dpll device +- ``DPLL_PIN_STATE_DISCONNECTED`` - the pin is not used to drive dpll + device + +In automatic mode (``DPLL_MODE_AUTOMATIC``) the user can request or +receive one of following pin states: + +- ``DPLL_PIN_STATE_SELECTABLE`` - the pin shall be considered as valid + input for automatic selection algorithm +- ``DPLL_PIN_STATE_DISCONNECTED`` - the pin shall be not considered as + a valid input for automatic selection algorithm + +In automatic mode (``DPLL_MODE_AUTOMATIC``) the user can only receive +pin state ``DPLL_PIN_STATE_CONNECTED`` once automatic selection +algorithm locks a dpll device with one of the inputs. + +Shared pins +=========== + +A single pin object can be attached to multiple dpll devices. +Then there are two groups of configuration knobs: + +1) Set on a pin - the configuration affects all dpll devices pin is + registered to (i.e., ``DPLL_A_PIN_FREQUENCY``), +2) Set on a pin-dpll tuple - the configuration affects only selected + dpll device (i.e., ``DPLL_A_PIN_PRIO``, ``DPLL_A_PIN_STATE``, + ``DPLL_A_PIN_DIRECTION``). + +MUX-type pins +============= + +A pin can be MUX-type, it aggregates child pins and serves as a pin +multiplexer. One or more pins are registered with MUX-type instead of +being directly registered to a dpll device. +Pins registered with a MUX-type pin provide user with additional nested +attribute ``DPLL_A_PIN_PARENT_PIN`` for each parent they were registered +with. +If a pin was registered with multiple parent pins, they behave like a +multiple output multiplexer. In this case output of a +``DPLL_CMD_PIN_GET`` would contain multiple pin-parent nested +attributes with current state related to each parent, like:: + + 'pin': [{{ + 'clock-id': 282574471561216, + 'module-name': 'ice', + 'capabilities': 4, + 'id': 13, + 'parent-pin': [ + {'parent-id': 2, 'state': 'connected'}, + {'parent-id': 3, 'state': 'disconnected'} + ], + 'type': 'synce-eth-port' + }}] + +Only one child pin can provide its signal to the parent MUX-type pin at +a time, the selection is done by requesting change of a child pin state +on desired parent, with the use of ``DPLL_A_PIN_PARENT`` nested +attribute. Example of netlink `set state on parent pin` message format: + + ========================== ============================================= + ``DPLL_A_PIN_ID`` child pin id + ``DPLL_A_PIN_PARENT_PIN`` nested attribute for requesting configuration + related to parent pin + ``DPLL_A_PIN_PARENT_ID`` parent pin id + ``DPLL_A_PIN_STATE`` requested pin state on parent + ========================== ============================================= + +Pin priority +============ + +Some devices might offer a capability of automatic pin selection mode +(enum value ``DPLL_MODE_AUTOMATIC`` of ``DPLL_A_MODE`` attribute). +Usually, automatic selection is performed on the hardware level, which +means only pins directly connected to the dpll can be used for automatic +input pin selection. +In automatic selection mode, the user cannot manually select a input +pin for the device, instead the user shall provide all directly +connected pins with a priority ``DPLL_A_PIN_PRIO``, the device would +pick a highest priority valid signal and use it to control the DPLL +device. Example of netlink `set priority on parent pin` message format: + + ============================ ============================================= + ``DPLL_A_PIN_ID`` configured pin id + ``DPLL_A_PIN_PARENT_DEVICE`` nested attribute for requesting configuration + related to parent dpll device + ``DPLL_A_PIN_PARENT_ID`` parent dpll device id + ``DPLL_A_PIN_PRIO`` requested pin prio on parent dpll + ============================ ============================================= + +Child pin of MUX-type pin is not capable of automatic input pin selection, +in order to configure active input of a MUX-type pin, the user needs to +request desired pin state of the child pin on the parent pin, +as described in the ``MUX-type pins`` chapter. + +Phase offset measurement and adjustment +======================================== + +Device may provide ability to measure a phase difference between signals +on a pin and its parent dpll device. If pin-dpll phase offset measurement +is supported, it shall be provided with ``DPLL_A_PIN_PHASE_OFFSET`` +attribute for each parent dpll device. + +Device may also provide ability to adjust a signal phase on a pin. +If pin phase adjustment is supported, minimal and maximal values that pin +handle shall be provide to the user on ``DPLL_CMD_PIN_GET`` respond +with ``DPLL_A_PIN_PHASE_ADJUST_MIN`` and ``DPLL_A_PIN_PHASE_ADJUST_MAX`` +attributes. Configured phase adjust value is provided with +``DPLL_A_PIN_PHASE_ADJUST`` attribute of a pin, and value change can be +requested with the same attribute with ``DPLL_CMD_PIN_SET`` command. + + =============================== ====================================== + ``DPLL_A_PIN_ID`` configured pin id + ``DPLL_A_PIN_PHASE_ADJUST_MIN`` attr minimum value of phase adjustment + ``DPLL_A_PIN_PHASE_ADJUST_MAX`` attr maximum value of phase adjustment + ``DPLL_A_PIN_PHASE_ADJUST`` attr configured value of phase + adjustment on parent dpll device + ``DPLL_A_PIN_PARENT_DEVICE`` nested attribute for requesting + configuration on given parent dpll + device + ``DPLL_A_PIN_PARENT_ID`` parent dpll device id + ``DPLL_A_PIN_PHASE_OFFSET`` attr measured phase difference + between a pin and parent dpll device + =============================== ====================================== + +All phase related values are provided in pico seconds, which represents +time difference between signals phase. The negative value means that +phase of signal on pin is earlier in time than dpll's signal. Positive +value means that phase of signal on pin is later in time than signal of +a dpll. + +Phase adjust (also min and max) values are integers, but measured phase +offset values are fractional with 3-digit decimal places and shell be +divided with ``DPLL_PIN_PHASE_OFFSET_DIVIDER`` to get integer part and +modulo divided to get fractional part. + +Configuration commands group +============================ + +Configuration commands are used to get information about registered +dpll devices (and pins), as well as set configuration of device or pins. +As dpll devices must be abstracted and reflect real hardware, +there is no way to add new dpll device via netlink from user space and +each device should be registered by its driver. + +All netlink commands require ``GENL_ADMIN_PERM``. This is to prevent +any spamming/DoS from unauthorized userspace applications. + +List of netlink commands with possible attributes +================================================= + +Constants identifying command types for dpll device uses a +``DPLL_CMD_`` prefix and suffix according to command purpose. +The dpll device related attributes use a ``DPLL_A_`` prefix and +suffix according to attribute purpose. + + ==================================== ================================= + ``DPLL_CMD_DEVICE_ID_GET`` command to get device ID + ``DPLL_A_MODULE_NAME`` attr module name of registerer + ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier + (EUI-64), as defined by the + IEEE 1588 standard + ``DPLL_A_TYPE`` attr type of dpll device + ==================================== ================================= + + ==================================== ================================= + ``DPLL_CMD_DEVICE_GET`` command to get device info or + dump list of available devices + ``DPLL_A_ID`` attr unique dpll device ID + ``DPLL_A_MODULE_NAME`` attr module name of registerer + ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier + (EUI-64), as defined by the + IEEE 1588 standard + ``DPLL_A_MODE`` attr selection mode + ``DPLL_A_MODE_SUPPORTED`` attr available selection modes + ``DPLL_A_LOCK_STATUS`` attr dpll device lock status + ``DPLL_A_TEMP`` attr device temperature info + ``DPLL_A_TYPE`` attr type of dpll device + ==================================== ================================= + + ==================================== ================================= + ``DPLL_CMD_DEVICE_SET`` command to set dpll device config + ``DPLL_A_ID`` attr internal dpll device index + ``DPLL_A_MODE`` attr selection mode to configure + ==================================== ================================= + +Constants identifying command types for pins uses a +``DPLL_CMD_PIN_`` prefix and suffix according to command purpose. +The pin related attributes use a ``DPLL_A_PIN_`` prefix and suffix +according to attribute purpose. + + ==================================== ================================= + ``DPLL_CMD_PIN_ID_GET`` command to get pin ID + ``DPLL_A_PIN_MODULE_NAME`` attr module name of registerer + ``DPLL_A_PIN_CLOCK_ID`` attr Unique Clock Identifier + (EUI-64), as defined by the + IEEE 1588 standard + ``DPLL_A_PIN_BOARD_LABEL`` attr pin board label provided + by registerer + ``DPLL_A_PIN_PANEL_LABEL`` attr pin panel label provided + by registerer + ``DPLL_A_PIN_PACKAGE_LABEL`` attr pin package label provided + by registerer + ``DPLL_A_PIN_TYPE`` attr type of a pin + ==================================== ================================= + + ==================================== ================================== + ``DPLL_CMD_PIN_GET`` command to get pin info or dump + list of available pins + ``DPLL_A_PIN_ID`` attr unique a pin ID + ``DPLL_A_PIN_MODULE_NAME`` attr module name of registerer + ``DPLL_A_PIN_CLOCK_ID`` attr Unique Clock Identifier + (EUI-64), as defined by the + IEEE 1588 standard + ``DPLL_A_PIN_BOARD_LABEL`` attr pin board label provided + by registerer + ``DPLL_A_PIN_PANEL_LABEL`` attr pin panel label provided + by registerer + ``DPLL_A_PIN_PACKAGE_LABEL`` attr pin package label provided + by registerer + ``DPLL_A_PIN_TYPE`` attr type of a pin + ``DPLL_A_PIN_FREQUENCY`` attr current frequency of a pin + ``DPLL_A_PIN_FREQUENCY_SUPPORTED`` nested attr provides supported + frequencies + ``DPLL_A_PIN_ANY_FREQUENCY_MIN`` attr minimum value of frequency + ``DPLL_A_PIN_ANY_FREQUENCY_MAX`` attr maximum value of frequency + ``DPLL_A_PIN_PHASE_ADJUST_MIN`` attr minimum value of phase + adjustment + ``DPLL_A_PIN_PHASE_ADJUST_MAX`` attr maximum value of phase + adjustment + ``DPLL_A_PIN_PHASE_ADJUST`` attr configured value of phase + adjustment on parent device + ``DPLL_A_PIN_PARENT_DEVICE`` nested attr for each parent device + the pin is connected with + ``DPLL_A_PIN_PARENT_ID`` attr parent dpll device id + ``DPLL_A_PIN_PRIO`` attr priority of pin on the + dpll device + ``DPLL_A_PIN_STATE`` attr state of pin on the parent + dpll device + ``DPLL_A_PIN_DIRECTION`` attr direction of a pin on the + parent dpll device + ``DPLL_A_PIN_PHASE_OFFSET`` attr measured phase difference + between a pin and parent dpll + ``DPLL_A_PIN_PARENT_PIN`` nested attr for each parent pin + the pin is connected with + ``DPLL_A_PIN_PARENT_ID`` attr parent pin id + ``DPLL_A_PIN_STATE`` attr state of pin on the parent + pin + ``DPLL_A_PIN_CAPABILITIES`` attr bitmask of pin capabilities + ==================================== ================================== + + ==================================== ================================= + ``DPLL_CMD_PIN_SET`` command to set pins configuration + ``DPLL_A_PIN_ID`` attr unique a pin ID + ``DPLL_A_PIN_FREQUENCY`` attr requested frequency of a pin + ``DPLL_A_PIN_PHASE_ADJUST`` attr requested value of phase + adjustment on parent device + ``DPLL_A_PIN_PARENT_DEVICE`` nested attr for each parent dpll + device configuration request + ``DPLL_A_PIN_PARENT_ID`` attr parent dpll device id + ``DPLL_A_PIN_DIRECTION`` attr requested direction of a pin + ``DPLL_A_PIN_PRIO`` attr requested priority of pin on + the dpll device + ``DPLL_A_PIN_STATE`` attr requested state of pin on + the dpll device + ``DPLL_A_PIN_PARENT_PIN`` nested attr for each parent pin + configuration request + ``DPLL_A_PIN_PARENT_ID`` attr parent pin id + ``DPLL_A_PIN_STATE`` attr requested state of pin on + parent pin + ==================================== ================================= + +Netlink dump requests +===================== + +The ``DPLL_CMD_DEVICE_GET`` and ``DPLL_CMD_PIN_GET`` commands are +capable of dump type netlink requests, in which case the response is in +the same format as for their ``do`` request, but every device or pin +registered in the system is returned. + +SET commands format +=================== + +``DPLL_CMD_DEVICE_SET`` - to target a dpll device, the user provides +``DPLL_A_ID``, which is unique identifier of dpll device in the system, +as well as parameter being configured (``DPLL_A_MODE``). + +``DPLL_CMD_PIN_SET`` - to target a pin user must provide a +``DPLL_A_PIN_ID``, which is unique identifier of a pin in the system. +Also configured pin parameters must be added. +If ``DPLL_A_PIN_FREQUENCY`` is configured, this affects all the dpll +devices that are connected with the pin, that is why frequency attribute +shall not be enclosed in ``DPLL_A_PIN_PARENT_DEVICE``. +Other attributes: ``DPLL_A_PIN_PRIO``, ``DPLL_A_PIN_STATE`` or +``DPLL_A_PIN_DIRECTION`` must be enclosed in +``DPLL_A_PIN_PARENT_DEVICE`` as their configuration relates to only one +of parent dplls, targeted by ``DPLL_A_PIN_PARENT_ID`` attribute which is +also required inside that nest. +For MUX-type pins the ``DPLL_A_PIN_STATE`` attribute is configured in +similar way, by enclosing required state in ``DPLL_A_PIN_PARENT_PIN`` +nested attribute and targeted parent pin id in ``DPLL_A_PIN_PARENT_ID``. + +In general, it is possible to configure multiple parameters at once, but +internally each parameter change will be invoked separately, where order +of configuration is not guaranteed by any means. + +Configuration pre-defined enums +=============================== + +.. kernel-doc:: include/uapi/linux/dpll.h + +Notifications +============= + +dpll device can provide notifications regarding status changes of the +device, i.e. lock status changes, input/output changes or other alarms. +There is one multicast group that is used to notify user-space apps via +netlink socket: ``DPLL_MCGRP_MONITOR`` + +Notifications messages: + + ============================== ===================================== + ``DPLL_CMD_DEVICE_CREATE_NTF`` dpll device was created + ``DPLL_CMD_DEVICE_DELETE_NTF`` dpll device was deleted + ``DPLL_CMD_DEVICE_CHANGE_NTF`` dpll device has changed + ``DPLL_CMD_PIN_CREATE_NTF`` dpll pin was created + ``DPLL_CMD_PIN_DELETE_NTF`` dpll pin was deleted + ``DPLL_CMD_PIN_CHANGE_NTF`` dpll pin has changed + ============================== ===================================== + +Events format is the same as for the corresponding get command. +Format of ``DPLL_CMD_DEVICE_`` events is the same as response of +``DPLL_CMD_DEVICE_GET``. +Format of ``DPLL_CMD_PIN_`` events is same as response of +``DPLL_CMD_PIN_GET``. + +Device driver implementation +============================ + +Device is allocated by dpll_device_get() call. Second call with the +same arguments will not create new object but provides pointer to +previously created device for given arguments, it also increases +refcount of that object. +Device is deallocated by dpll_device_put() call, which first +decreases the refcount, once refcount is cleared the object is +destroyed. + +Device should implement set of operations and register device via +dpll_device_register() at which point it becomes available to the +users. Multiple driver instances can obtain reference to it with +dpll_device_get(), as well as register dpll device with their own +ops and priv. + +The pins are allocated separately with dpll_pin_get(), it works +similarly to dpll_device_get(). Function first creates object and then +for each call with the same arguments only the object refcount +increases. Also dpll_pin_put() works similarly to dpll_device_put(). + +A pin can be registered with parent dpll device or parent pin, depending +on hardware needs. Each registration requires registerer to provide set +of pin callbacks, and private data pointer for calling them: + +- dpll_pin_register() - register pin with a dpll device, +- dpll_pin_on_pin_register() - register pin with another MUX type pin. + +Notifications of adding or removing dpll devices are created within +subsystem itself. +Notifications about registering/deregistering pins are also invoked by +the subsystem. +Notifications about status changes either of dpll device or a pin are +invoked in two ways: + +- after successful change was requested on dpll subsystem, the subsystem + calls corresponding notification, +- requested by device driver with dpll_device_change_ntf() or + dpll_pin_change_ntf() when driver informs about the status change. + +The device driver using dpll interface is not required to implement all +the callback operation. Nevertheless, there are few required to be +implemented. +Required dpll device level callback operations: + +- ``.mode_get``, +- ``.lock_status_get``. + +Required pin level callback operations: + +- ``.state_on_dpll_get`` (pins registered with dpll device), +- ``.state_on_pin_get`` (pins registered with parent pin), +- ``.direction_get``. + +Every other operation handler is checked for existence and +``-EOPNOTSUPP`` is returned in case of absence of specific handler. + +The simplest implementation is in the OCP TimeCard driver. The ops +structures are defined like this: + +.. code-block:: c + + static const struct dpll_device_ops dpll_ops = { + .lock_status_get = ptp_ocp_dpll_lock_status_get, + .mode_get = ptp_ocp_dpll_mode_get, + .mode_supported = ptp_ocp_dpll_mode_supported, + }; + + static const struct dpll_pin_ops dpll_pins_ops = { + .frequency_get = ptp_ocp_dpll_frequency_get, + .frequency_set = ptp_ocp_dpll_frequency_set, + .direction_get = ptp_ocp_dpll_direction_get, + .direction_set = ptp_ocp_dpll_direction_set, + .state_on_dpll_get = ptp_ocp_dpll_state_get, + }; + +The registration part is then looks like this part: + +.. code-block:: c + + clkid = pci_get_dsn(pdev); + bp->dpll = dpll_device_get(clkid, 0, THIS_MODULE); + if (IS_ERR(bp->dpll)) { + err = PTR_ERR(bp->dpll); + dev_err(&pdev->dev, "dpll_device_alloc failed\n"); + goto out; + } + + err = dpll_device_register(bp->dpll, DPLL_TYPE_PPS, &dpll_ops, bp); + if (err) + goto out; + + for (i = 0; i < OCP_SMA_NUM; i++) { + bp->sma[i].dpll_pin = dpll_pin_get(clkid, i, THIS_MODULE, &bp->sma[i].dpll_prop); + if (IS_ERR(bp->sma[i].dpll_pin)) { + err = PTR_ERR(bp->dpll); + goto out_dpll; + } + + err = dpll_pin_register(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops, + &bp->sma[i]); + if (err) { + dpll_pin_put(bp->sma[i].dpll_pin); + goto out_dpll; + } + } + +In the error path we have to rewind every allocation in the reverse order: + +.. code-block:: c + + while (i) { + --i; + dpll_pin_unregister(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops, &bp->sma[i]); + dpll_pin_put(bp->sma[i].dpll_pin); + } + dpll_device_put(bp->dpll); + +More complex example can be found in Intel's ICE driver or nVidia's mlx5 driver. + +SyncE enablement +================ +For SyncE enablement it is required to allow control over dpll device +for a software application which monitors and configures the inputs of +dpll device in response to current state of a dpll device and its +inputs. +In such scenario, dpll device input signal shall be also configurable +to drive dpll with signal recovered from the PHY netdevice. +This is done by exposing a pin to the netdevice - attaching pin to the +netdevice itself with +``netdev_dpll_pin_set(struct net_device *dev, struct dpll_pin *dpll_pin)``. +Exposed pin id handle ``DPLL_A_PIN_ID`` is then identifiable by the user +as it is attached to rtnetlink respond to get ``RTM_NEWLINK`` command in +nested attribute ``IFLA_DPLL_PIN``. diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index 8be086b3f829..c5f99d834ec5 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -322,10 +322,8 @@ IOMAP devm_platform_ioremap_resource_byname() devm_platform_get_and_ioremap_resource() devm_iounmap() - pcim_iomap() - pcim_iomap_regions() : do request_region() and iomap() on multiple BARs - pcim_iomap_table() : array of mapped addresses indexed by BAR - pcim_iounmap() + + Note: For the PCI devices the specific pcim_*() functions may be used, see below. IRQ devm_free_irq() @@ -392,8 +390,16 @@ PCI devm_pci_alloc_host_bridge() : managed PCI host bridge allocation devm_pci_remap_cfgspace() : ioremap PCI configuration space devm_pci_remap_cfg_resource() : ioremap PCI configuration space resource + pcim_enable_device() : after success, all PCI ops become managed + pcim_iomap() : do iomap() on a single BAR + pcim_iomap_regions() : do request_region() and iomap() on multiple BARs + pcim_iomap_regions_request_all() : do request_region() on all and iomap() on multiple BARs + pcim_iomap_table() : array of mapped addresses indexed by BAR + pcim_iounmap() : do iounmap() on a single BAR + pcim_iounmap_regions() : do iounmap() and release_region() on multiple BARs pcim_pin_device() : keep PCI device enabled after release + pcim_set_mwi() : enable Memory-Write-Invalidate PCI transaction PHY devm_usb_get_phy() diff --git a/Documentation/driver-api/gpio/consumer.rst b/Documentation/driver-api/gpio/consumer.rst index de6fc79ad6f0..3e588b9d678c 100644 --- a/Documentation/driver-api/gpio/consumer.rst +++ b/Documentation/driver-api/gpio/consumer.rst @@ -29,6 +29,10 @@ warnings. These stubs are used for two use cases: will use it under other compile-time configurations. In this case the consumer must make sure not to call into these functions, or the user will be met with console warnings that may be perceived as intimidating. + Combining truly optional GPIOLIB usage with calls to + ``[devm_]gpiod_get_optional()`` is a *bad idea*, and will result in weird + error messages. Use the ordinary getter functions with optional GPIOLIB: + some open coding of error handling should be expected when you do this. All the functions that work with the descriptor-based GPIO interface are prefixed with ``gpiod_``. The ``gpio_`` prefix is used for the legacy diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 1e16a40da3ba..f549a68951d7 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -114,6 +114,7 @@ available subsections can be seen below. zorro hte/index wmi + dpll .. only:: subproject and html diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst index 683bd460e222..3d52dfdfa9fd 100644 --- a/Documentation/driver-api/infrastructure.rst +++ b/Documentation/driver-api/infrastructure.rst @@ -8,12 +8,24 @@ The Basic Device Driver-Model Structures :internal: :no-identifiers: device_link_state +.. kernel-doc:: include/linux/device/bus.h + :identifiers: bus_type bus_notifier_event + +.. kernel-doc:: include/linux/device/class.h + :identifiers: class + +.. kernel-doc:: include/linux/device/driver.h + :identifiers: probe_type device_driver + Device Drivers Base ------------------- .. kernel-doc:: drivers/base/init.c :internal: +.. kernel-doc:: include/linux/device/driver.h + :no-identifiers: probe_type device_driver + .. kernel-doc:: drivers/base/driver.c :export: @@ -23,6 +35,9 @@ Device Drivers Base .. kernel-doc:: drivers/base/syscore.c :export: +.. kernel-doc:: include/linux/device/class.h + :no-identifiers: class + .. kernel-doc:: drivers/base/class.c :export: @@ -41,6 +56,9 @@ Device Drivers Base .. kernel-doc:: drivers/base/platform.c :export: +.. kernel-doc:: include/linux/device/bus.h + :no-identifiers: bus_type bus_notifier_event + .. kernel-doc:: drivers/base/bus.c :export: diff --git a/Documentation/driver-api/interconnect.rst b/Documentation/driver-api/interconnect.rst index 5ed4f57a6bac..a92d0f277a1f 100644 --- a/Documentation/driver-api/interconnect.rst +++ b/Documentation/driver-api/interconnect.rst @@ -113,3 +113,28 @@ through dot to generate diagrams in many graphical formats:: $ cat /sys/kernel/debug/interconnect/interconnect_graph | \ dot -Tsvg > interconnect_graph.svg + +The ``test-client`` directory provides interfaces for issuing BW requests to +any arbitrary path. Note that for safety reasons, this feature is disabled by +default without a Kconfig to enable it. Enabling it requires code changes to +``#define INTERCONNECT_ALLOW_WRITE_DEBUGFS``. Example usage:: + + cd /sys/kernel/debug/interconnect/test-client/ + + # Configure node endpoints for the path from CPU to DDR on + # qcom/sm8550. + echo chm_apps > src_node + echo ebi > dst_node + + # Get path between src_node and dst_node. This is only + # necessary after updating the node endpoints. + echo 1 > get + + # Set desired BW to 1GBps avg and 2GBps peak. + echo 1000000 > avg_bw + echo 2000000 > peak_bw + + # Vote for avg_bw and peak_bw on the latest path from "get". + # Voting for multiple paths is possible by repeating this + # process for different nodes endpoints. + echo 1 > commit diff --git a/Documentation/driver-api/libata.rst b/Documentation/driver-api/libata.rst index 311af516a3fd..5da27a749246 100644 --- a/Documentation/driver-api/libata.rst +++ b/Documentation/driver-api/libata.rst @@ -32,22 +32,6 @@ register blocks. :c:type:`struct ata_port_operations <ata_port_operations>` ---------------------------------------------------------- -Disable ATA port -~~~~~~~~~~~~~~~~ - -:: - - void (*port_disable) (struct ata_port *); - - -Called from :c:func:`ata_bus_probe` error path, as well as when unregistering -from the SCSI module (rmmod, hot unplug). This function should do -whatever needs to be done to take the port out of use. In most cases, -:c:func:`ata_port_disable` can be used as this hook. - -Called from :c:func:`ata_bus_probe` on a failed probe. Called from -:c:func:`ata_scsi_release`. - Post-IDENTIFY device configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -274,14 +258,6 @@ Exception and probe handling (EH) :: - void (*eng_timeout) (struct ata_port *ap); - void (*phy_reset) (struct ata_port *ap); - - -Deprecated. Use ``->error_handler()`` instead. - -:: - void (*freeze) (struct ata_port *ap); void (*thaw) (struct ata_port *ap); @@ -364,8 +340,7 @@ SATA phy read/write u32 val); -Read and write standard SATA phy registers. Currently only used if -``->phy_reset`` hook called the :c:func:`sata_phy_reset` helper function. +Read and write standard SATA phy registers. sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE. Init and shutdown @@ -536,13 +511,12 @@ to return without deallocating the qc. This leads us to :c:func:`ata_scsi_error` is the current ``transportt->eh_strategy_handler()`` for libata. As discussed above, this will be entered in two cases - -timeout and ATAPI error completion. This function calls low level libata -driver's :c:func:`eng_timeout` callback, the standard callback for which is -:c:func:`ata_eng_timeout`. It checks if a qc is active and calls -:c:func:`ata_qc_timeout` on the qc if so. Actual error handling occurs in -:c:func:`ata_qc_timeout`. +timeout and ATAPI error completion. This function will check if a qc is active +and has not failed yet. Such a qc will be marked with AC_ERR_TIMEOUT such that +EH will know to handle it later. Then it calls low level libata driver's +:c:func:`error_handler` callback. -If EH is invoked for timeout, :c:func:`ata_qc_timeout` stops BMDMA and +When the :c:func:`error_handler` callback is invoked it stops BMDMA and completes the qc. Note that as we're currently in EH, we cannot call scsi_done. As described in SCSI EH doc, a recovered scmd should be either retried with :c:func:`scsi_queue_insert` or finished with diff --git a/Documentation/driver-api/media/cec-core.rst b/Documentation/driver-api/media/cec-core.rst index ae0d20798edc..f1ffdec388f3 100644 --- a/Documentation/driver-api/media/cec-core.rst +++ b/Documentation/driver-api/media/cec-core.rst @@ -109,9 +109,11 @@ your driver: int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable); int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); - void (*adap_configured)(struct cec_adapter *adap, bool configured); + void (*adap_unconfigured)(struct cec_adapter *adap); int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, u32 signal_free_time, struct cec_msg *msg); + void (*adap_nb_transmit_canceled)(struct cec_adapter *adap, + const struct cec_msg *msg); void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); void (*adap_free)(struct cec_adapter *adap); @@ -122,8 +124,8 @@ your driver: ... }; -The seven low-level ops deal with various aspects of controlling the CEC adapter -hardware: +These low-level ops deal with various aspects of controlling the CEC adapter +hardware. They are all called with the mutex adap->lock held. To enable/disable the hardware:: @@ -179,14 +181,12 @@ can receive directed messages to that address. Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID. -Called when the adapter is fully configured or unconfigured:: +Called when the adapter is unconfigured:: - void (*adap_configured)(struct cec_adapter *adap, bool configured); + void (*adap_unconfigured)(struct cec_adapter *adap); -If configured == true, then the adapter is fully configured, i.e. all logical -addresses have been successfully claimed. If configured == false, then the -adapter is unconfigured. If the driver has to take specific actions after -(un)configuration, then that can be done through this optional callback. +The adapter is unconfigured. If the driver has to take specific actions after +unconfiguration, then that can be done through this optional callback. To transmit a new message:: @@ -207,6 +207,19 @@ The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to microseconds (one data bit period is 2.4 ms). +To pass on the result of a canceled non-blocking transmit:: + + void (*adap_nb_transmit_canceled)(struct cec_adapter *adap, + const struct cec_msg *msg); + +This optional callback can be used to obtain the result of a canceled +non-blocking transmit with sequence number msg->sequence. This is +called if the transmit was aborted, the transmit timed out (i.e. the +hardware never signaled that the transmit finished), or the transmit +was successful, but the wait for the expected reply was either aborted +or it timed out. + + To log the current CEC hardware status:: void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); @@ -372,7 +385,8 @@ Implementing the High-Level CEC Adapter --------------------------------------- The low-level operations drive the hardware, the high-level operations are -CEC protocol driven. The following high-level callbacks are available: +CEC protocol driven. The high-level callbacks are called without the adap->lock +mutex being held. The following high-level callbacks are available: .. code-block:: none @@ -384,9 +398,19 @@ CEC protocol driven. The following high-level callbacks are available: ... /* High-level CEC message callback */ + void (*configured)(struct cec_adapter *adap); int (*received)(struct cec_adapter *adap, struct cec_msg *msg); }; +Called when the adapter is configured:: + + void (*configured)(struct cec_adapter *adap); + +The adapter is fully configured, i.e. all logical addresses have been +successfully claimed. If the driver has to take specific actions after +configuration, then that can be done through this optional callback. + + The received() callback allows the driver to optionally handle a newly received CEC message:: diff --git a/Documentation/driver-api/media/dtv-common.rst b/Documentation/driver-api/media/dtv-common.rst index f8b2c4dc8170..207a22bcaf4a 100644 --- a/Documentation/driver-api/media/dtv-common.rst +++ b/Documentation/driver-api/media/dtv-common.rst @@ -3,15 +3,6 @@ Digital TV Common functions --------------------------- -Math functions -~~~~~~~~~~~~~~ - -Provide some commonly-used math functions, usually required in order to -estimate signal strength and signal to noise measurements in dB. - -.. kernel-doc:: include/media/dvb_math.h - - DVB devices ~~~~~~~~~~~ diff --git a/Documentation/driver-api/media/v4l2-cci.rst b/Documentation/driver-api/media/v4l2-cci.rst new file mode 100644 index 000000000000..dd297a40ed20 --- /dev/null +++ b/Documentation/driver-api/media/v4l2-cci.rst @@ -0,0 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 CCI kAPI +^^^^^^^^^^^^^ +.. kernel-doc:: include/media/v4l2-cci.h diff --git a/Documentation/driver-api/media/v4l2-core.rst b/Documentation/driver-api/media/v4l2-core.rst index 1a8c4a5f256b..239045ecc8f4 100644 --- a/Documentation/driver-api/media/v4l2-core.rst +++ b/Documentation/driver-api/media/v4l2-core.rst @@ -22,6 +22,7 @@ Video4Linux devices v4l2-mem2mem v4l2-async v4l2-fwnode + v4l2-cci v4l2-rect v4l2-tuner v4l2-common diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst index 602dadaa81d8..e56b50b3f203 100644 --- a/Documentation/driver-api/media/v4l2-subdev.rst +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -157,6 +157,9 @@ below. Using one or the other registration method only affects the probing process, the run-time bridge-subdevice interaction is in both cases the same. +Registering synchronous sub-devices +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + In the **synchronous** case a device (bridge) driver needs to register the :c:type:`v4l2_subdev` with the v4l2_device: @@ -175,10 +178,12 @@ You can unregister a sub-device using: :c:func:`v4l2_device_unregister_subdev <v4l2_device_unregister_subdev>` (:c:type:`sd <v4l2_subdev>`). - Afterwards the subdev module can be unloaded and :c:type:`sd <v4l2_subdev>`->dev == ``NULL``. +Registering asynchronous sub-devices +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + In the **asynchronous** case subdevice probing can be invoked independently of the bridge driver availability. The subdevice driver then has to verify whether all the requirements for a successful probing are satisfied. This can include a @@ -190,64 +195,89 @@ performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices registered this way are stored in a global list of subdevices, ready to be picked up by bridge drivers. -Bridge drivers in turn have to register a notifier object. This is -performed using the :c:func:`v4l2_async_nf_register` call. To -unregister the notifier the driver has to call -:c:func:`v4l2_async_nf_unregister`. The former of the two functions -takes two arguments: a pointer to struct :c:type:`v4l2_device` and a -pointer to struct :c:type:`v4l2_async_notifier`. +Asynchronous sub-device notifiers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Bridge drivers in turn have to register a notifier object. This is performed +using the :c:func:`v4l2_async_nf_register` call. To unregister the notifier the +driver has to call :c:func:`v4l2_async_nf_unregister`. Before releasing memory +of an unregister notifier, it must be cleaned up by calling +:c:func:`v4l2_async_nf_cleanup`. Before registering the notifier, bridge drivers must do two things: first, the -notifier must be initialized using the :c:func:`v4l2_async_nf_init`. -Second, bridge drivers can then begin to form a list of subdevice descriptors -that the bridge device needs for its operation. Several functions are available -to add subdevice descriptors to a notifier, depending on the type of device and -the needs of the driver. - -:c:func:`v4l2_async_nf_add_fwnode_remote` and -:c:func:`v4l2_async_nf_add_i2c` are for bridge and ISP drivers for -registering their async sub-devices with the notifier. - -:c:func:`v4l2_async_register_subdev_sensor` is a helper function for -sensor drivers registering their own async sub-device, but it also registers a -notifier and further registers async sub-devices for lens and flash devices -found in firmware. The notifier for the sub-device is unregistered with the -async sub-device. - -These functions allocate an async sub-device descriptor which is of type struct -:c:type:`v4l2_async_subdev` embedded in a driver-specific struct. The &struct -:c:type:`v4l2_async_subdev` shall be the first member of this struct: +notifier must be initialized using the :c:func:`v4l2_async_nf_init`. Second, +bridge drivers can then begin to form a list of async connection descriptors +that the bridge device needs for its +operation. :c:func:`v4l2_async_nf_add_fwnode`, +:c:func:`v4l2_async_nf_add_fwnode_remote` and :c:func:`v4l2_async_nf_add_i2c` + +Async connection descriptors describe connections to external sub-devices the +drivers for which are not yet probed. Based on an async connection, a media data +or ancillary link may be created when the related sub-device becomes +available. There may be one or more async connections to a given sub-device but +this is not known at the time of adding the connections to the notifier. Async +connections are bound as matching async sub-devices are found, one by one. + +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 +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 +a path via async sub-devices and notifiers to a notifier that is not an +asynchronous sub-device notifier. + +Asynchronous sub-device registration helper for camera sensor drivers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:c:func:`v4l2_async_register_subdev_sensor` is a helper function for sensor +drivers registering their own async connection, but it also registers a notifier +and further registers async connections for lens and flash devices found in +firmware. The notifier for the sub-device is unregistered and cleaned up with +the async sub-device, using :c:func:`v4l2_async_unregister_subdev`. + +Asynchronous sub-device notifier example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These functions allocate an async connection descriptor which is of type struct +:c:type:`v4l2_async_connection` embedded in a driver-specific struct. The &struct +:c:type:`v4l2_async_connection` shall be the first member of this struct: .. code-block:: c - struct my_async_subdev { - struct v4l2_async_subdev asd; + struct my_async_connection { + struct v4l2_async_connection asc; ... }; - struct my_async_subdev *my_asd; + struct my_async_connection *my_asc; struct fwnode_handle *ep; ... - my_asd = v4l2_async_nf_add_fwnode_remote(¬ifier, ep, - struct my_async_subdev); + my_asc = v4l2_async_nf_add_fwnode_remote(¬ifier, ep, + struct my_async_connection); fwnode_handle_put(ep); - if (IS_ERR(asd)) - return PTR_ERR(asd); + if (IS_ERR(my_asc)) + return PTR_ERR(my_asc); + +Asynchronous sub-device notifier callbacks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The V4L2 core will then use these descriptors to match asynchronously -registered subdevices to them. If a match is detected the ``.bound()`` -notifier callback is called. After all subdevices have been located the -.complete() callback is called. When a subdevice is removed from the -system the .unbind() method is called. All three callbacks are optional. +The V4L2 core will then use these connection descriptors to match asynchronously +registered subdevices to them. If a match is detected the ``.bound()`` notifier +callback is called. After all connections have been bound the .complete() +callback is called. When a connection is removed from the system the +``.unbind()`` method is called. All three callbacks are optional. Drivers can store any type of custom data in their driver-specific -:c:type:`v4l2_async_subdev` wrapper. If any of that data requires special +:c:type:`v4l2_async_connection` wrapper. If any of that data requires special handling when the structure is freed, drivers must implement the ``.destroy()`` notifier callback. The framework will call it right before freeing the -:c:type:`v4l2_async_subdev`. +:c:type:`v4l2_async_connection`. Calling subdev operations ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/driver-api/pps.rst b/Documentation/driver-api/pps.rst index 2d6b99766ee8..78dded03e5d8 100644 --- a/Documentation/driver-api/pps.rst +++ b/Documentation/driver-api/pps.rst @@ -200,11 +200,17 @@ Generators Sometimes one needs to be able not only to catch PPS signals but to produce them also. For example, running a distributed simulation, which requires -computers' clock to be synchronized very tightly. One way to do this is to -invent some complicated hardware solutions but it may be neither necessary -nor affordable. The cheap way is to load a PPS generator on one of the -computers (master) and PPS clients on others (slaves), and use very simple -cables to deliver signals using parallel ports, for example. +computers' clock to be synchronized very tightly. + + +Parallel port generator +------------------------ + +One way to do this is to invent some complicated hardware solutions but it +may be neither necessary nor affordable. The cheap way is to load a PPS +generator on one of the computers (master) and PPS clients on others +(slaves), and use very simple cables to deliver signals using parallel +ports, for example. Parallel port cable pinout:: diff --git a/Documentation/driver-api/pwm.rst b/Documentation/driver-api/pwm.rst index 3fdc95f7a1d1..bb264490a87a 100644 --- a/Documentation/driver-api/pwm.rst +++ b/Documentation/driver-api/pwm.rst @@ -111,13 +111,13 @@ channel that was exported. The following properties will then be available: duty_cycle The active time of the PWM signal (read/write). - Value is in nanoseconds and must be less than the period. + Value is in nanoseconds and must be less than or equal to the period. polarity Changes the polarity of the PWM signal (read/write). Writes to this property only work if the PWM chip supports changing - the polarity. The polarity can only be changed if the PWM is not - enabled. Value is the string "normal" or "inversed". + the polarity. + Value is the string "normal" or "inversed". enable Enable/disable the PWM signal (read/write). diff --git a/Documentation/driver-api/s390-drivers.rst b/Documentation/driver-api/s390-drivers.rst index 5158577bc29b..8c0845c4eee7 100644 --- a/Documentation/driver-api/s390-drivers.rst +++ b/Documentation/driver-api/s390-drivers.rst @@ -27,7 +27,7 @@ not strictly considered I/O devices. They are considered here as well, although they are not the focus of this document. Some additional information can also be found in the kernel source under -Documentation/s390/driver-model.rst. +Documentation/arch/s390/driver-model.rst. The css bus =========== @@ -38,7 +38,7 @@ into several categories: * Standard I/O subchannels, for use by the system. They have a child device on the ccw bus and are described below. * I/O subchannels bound to the vfio-ccw driver. See - Documentation/s390/vfio-ccw.rst. + Documentation/arch/s390/vfio-ccw.rst. * Message subchannels. No Linux driver currently exists. * CHSC subchannels (at most one). The chsc subchannel driver can be used to send asynchronous chsc commands. diff --git a/Documentation/driver-api/thermal/intel_dptf.rst b/Documentation/driver-api/thermal/intel_dptf.rst index 9ab4316322a1..8fb8c5b2d685 100644 --- a/Documentation/driver-api/thermal/intel_dptf.rst +++ b/Documentation/driver-api/thermal/intel_dptf.rst @@ -164,6 +164,16 @@ ABI. ``power_limit_1_tmax_us`` (RO) Maximum powercap sysfs constraint_1_time_window_us for Intel RAPL +``power_floor_status`` (RO) + When set to 1, the power floor of the system in the current + configuration has been reached. It needs to be reconfigured to allow + power to be reduced any further. + +``power_floor_enable`` (RW) + When set to 1, enable reading and notification of the power floor + status. Notifications are triggered for the power_floor_status + attribute value changes. + :file:`/sys/bus/pci/devices/0000\:00\:04.0/` ``tcc_offset_degree_celsius`` (RW) @@ -315,3 +325,57 @@ DPTF Fan Control ---------------------------------------- Refer to Documentation/admin-guide/acpi/fan_performance_states.rst + +Workload Type Hints +---------------------------------------- + +The firmware in Meteor Lake processor generation is capable of identifying +workload type and passing hints regarding it to the OS. A special sysfs +interface is provided to allow user space to obtain workload type hints from +the firmware and control the rate at which they are provided. + +User space can poll attribute "workload_type_index" for the current hint or +can receive a notification whenever the value of this attribute is updated. + +file:`/sys/bus/pci/devices/0000:00:04.0/workload_hint/` +Segment 0, bus 0, device 4, function 0 is reserved for the processor thermal +device on all Intel client processors. So, the above path doesn't change +based on the processor generation. + +``workload_hint_enable`` (RW) + Enable firmware to send workload type hints to user space. + +``notification_delay_ms`` (RW) + Minimum delay in milliseconds before firmware will notify OS. This is + for the rate control of notifications. This delay is between changing + the workload type prediction in the firmware and notifying the OS about + the change. The default delay is 1024 ms. The delay of 0 is invalid. + The delay is rounded up to the nearest power of 2 to simplify firmware + programming of the delay value. The read of notification_delay_ms + attribute shows the effective value used. + +``workload_type_index`` (RO) + Predicted workload type index. User space can get notification of + change via existing sysfs attribute change notification mechanism. + + The supported index values and their meaning for the Meteor Lake + processor generation are as follows: + + 0 - Idle: System performs no tasks, power and idle residency are + consistently low for long periods of time. + + 1 – Battery Life: Power is relatively low, but the processor may + still be actively performing a task, such as video playback for + a long period of time. + + 2 – Sustained: Power level that is relatively high for a long period + of time, with very few to no periods of idleness, which will + eventually exhaust RAPL Power Limit 1 and 2. + + 3 – Bursty: Consumes a relatively constant average amount of power, but + periods of relative idleness are interrupted by bursts of + activity. The bursts are relatively short and the periods of + relative idleness between them typically prevent RAPL Power + Limit 1 from being exhausted. + + 4 – Unknown: Can't classify. diff --git a/Documentation/driver-api/tty/tty_buffer.rst b/Documentation/driver-api/tty/tty_buffer.rst index a39d4781e0d2..4b5ca1776d4f 100644 --- a/Documentation/driver-api/tty/tty_buffer.rst +++ b/Documentation/driver-api/tty/tty_buffer.rst @@ -15,10 +15,13 @@ Flip Buffer Management ====================== .. kernel-doc:: drivers/tty/tty_buffer.c - :identifiers: tty_prepare_flip_string tty_insert_flip_string_fixed_flag - tty_insert_flip_string_flags __tty_insert_flip_char + :identifiers: tty_prepare_flip_string tty_flip_buffer_push tty_ldisc_receive_buf +.. kernel-doc:: include/linux/tty_flip.h + :identifiers: tty_insert_flip_string_fixed_flag tty_insert_flip_string_flags + tty_insert_flip_char + ---- Other Functions diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst index 2c94ff2f4385..fb41768696ec 100644 --- a/Documentation/driver-api/usb/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -420,6 +420,12 @@ USBDEVFS_CONNECTINFO know the devnum value already, it's the DDD value of the device file name. +USBDEVFS_GET_SPEED + Returns the speed of the device. The speed is returned as a + nummerical value in accordance with enum usb_device_speed + + File modification time is not updated by this request. + USBDEVFS_GETDRIVER Returns the name of the kernel driver bound to a given interface (a string). Parameter is a pointer to this structure, which is @@ -771,8 +777,7 @@ Speed may be: ======= ====================================================== 1.5 Mbit/s for low speed USB 12 Mbit/s for full speed USB - 480 Mbit/s for high speed USB (added for USB 2.0); - also used for Wireless USB, which has no fixed speed + 480 Mbit/s for high speed USB (added for USB 2.0) 5000 Mbit/s for SuperSpeed USB (added for USB 3.0) ======= ====================================================== diff --git a/Documentation/driver-api/vfio.rst b/Documentation/driver-api/vfio.rst index 68abc089d6dd..633d11c7fa71 100644 --- a/Documentation/driver-api/vfio.rst +++ b/Documentation/driver-api/vfio.rst @@ -239,6 +239,137 @@ group and can access them as follows:: /* Gratuitous device reset and go... */ ioctl(device, VFIO_DEVICE_RESET); +IOMMUFD and vfio_iommu_type1 +---------------------------- + +IOMMUFD is the new user API to manage I/O page tables from userspace. +It intends to be the portal of delivering advanced userspace DMA +features (nested translation [5]_, PASID [6]_, etc.) while also providing +a backwards compatibility interface for existing VFIO_TYPE1v2_IOMMU use +cases. Eventually the vfio_iommu_type1 driver, as well as the legacy +vfio container and group model is intended to be deprecated. + +The IOMMUFD backwards compatibility interface can be enabled two ways. +In the first method, the kernel can be configured with +CONFIG_IOMMUFD_VFIO_CONTAINER, in which case the IOMMUFD subsystem +transparently provides the entire infrastructure for the VFIO +container and IOMMU backend interfaces. The compatibility mode can +also be accessed if the VFIO container interface, ie. /dev/vfio/vfio is +simply symlink'd to /dev/iommu. Note that at the time of writing, the +compatibility mode is not entirely feature complete relative to +VFIO_TYPE1v2_IOMMU (ex. DMA mapping MMIO) and does not attempt to +provide compatibility to the VFIO_SPAPR_TCE_IOMMU interface. Therefore +it is not generally advisable at this time to switch from native VFIO +implementations to the IOMMUFD compatibility interfaces. + +Long term, VFIO users should migrate to device access through the cdev +interface described below, and native access through the IOMMUFD +provided interfaces. + +VFIO Device cdev +---------------- + +Traditionally user acquires a device fd via VFIO_GROUP_GET_DEVICE_FD +in a VFIO group. + +With CONFIG_VFIO_DEVICE_CDEV=y the user can now acquire a device fd +by directly opening a character device /dev/vfio/devices/vfioX where +"X" is the number allocated uniquely by VFIO for registered devices. +cdev interface does not support noiommu devices, so user should use +the legacy group interface if noiommu is wanted. + +The cdev only works with IOMMUFD. Both VFIO drivers and applications +must adapt to the new cdev security model which requires using +VFIO_DEVICE_BIND_IOMMUFD to claim DMA ownership before starting to +actually use the device. Once BIND succeeds then a VFIO device can +be fully accessed by the user. + +VFIO device cdev doesn't rely on VFIO group/container/iommu drivers. +Hence those modules can be fully compiled out in an environment +where no legacy VFIO application exists. + +So far SPAPR does not support IOMMUFD yet. So it cannot support device +cdev either. + +vfio device cdev access is still bound by IOMMU group semantics, ie. there +can be only one DMA owner for the group. Devices belonging to the same +group can not be bound to multiple iommufd_ctx or shared between native +kernel and vfio bus driver or other driver supporting the driver_managed_dma +flag. A violation of this ownership requirement will fail at the +VFIO_DEVICE_BIND_IOMMUFD ioctl, which gates full device access. + +Device cdev Example +------------------- + +Assume user wants to access PCI device 0000:6a:01.0:: + + $ ls /sys/bus/pci/devices/0000:6a:01.0/vfio-dev/ + vfio0 + +This device is therefore represented as vfio0. The user can verify +its existence:: + + $ ls -l /dev/vfio/devices/vfio0 + crw------- 1 root root 511, 0 Feb 16 01:22 /dev/vfio/devices/vfio0 + $ cat /sys/bus/pci/devices/0000:6a:01.0/vfio-dev/vfio0/dev + 511:0 + $ ls -l /dev/char/511\:0 + lrwxrwxrwx 1 root root 21 Feb 16 01:22 /dev/char/511:0 -> ../vfio/devices/vfio0 + +Then provide the user with access to the device if unprivileged +operation is desired:: + + $ chown user:user /dev/vfio/devices/vfio0 + +Finally the user could get cdev fd by:: + + cdev_fd = open("/dev/vfio/devices/vfio0", O_RDWR); + +An opened cdev_fd doesn't give the user any permission of accessing +the device except binding the cdev_fd to an iommufd. After that point +then the device is fully accessible including attaching it to an +IOMMUFD IOAS/HWPT to enable userspace DMA:: + + struct vfio_device_bind_iommufd bind = { + .argsz = sizeof(bind), + .flags = 0, + }; + struct iommu_ioas_alloc alloc_data = { + .size = sizeof(alloc_data), + .flags = 0, + }; + struct vfio_device_attach_iommufd_pt attach_data = { + .argsz = sizeof(attach_data), + .flags = 0, + }; + struct iommu_ioas_map map = { + .size = sizeof(map), + .flags = IOMMU_IOAS_MAP_READABLE | + IOMMU_IOAS_MAP_WRITEABLE | + IOMMU_IOAS_MAP_FIXED_IOVA, + .__reserved = 0, + }; + + iommufd = open("/dev/iommu", O_RDWR); + + bind.iommufd = iommufd; + ioctl(cdev_fd, VFIO_DEVICE_BIND_IOMMUFD, &bind); + + ioctl(iommufd, IOMMU_IOAS_ALLOC, &alloc_data); + attach_data.pt_id = alloc_data.out_ioas_id; + ioctl(cdev_fd, VFIO_DEVICE_ATTACH_IOMMUFD_PT, &attach_data); + + /* Allocate some space and setup a DMA mapping */ + map.user_va = (int64_t)mmap(0, 1024 * 1024, PROT_READ | PROT_WRITE, + MAP_PRIVATE | MAP_ANONYMOUS, 0, 0); + map.iova = 0; /* 1MB starting at 0x0 from device view */ + map.length = 1024 * 1024; + map.ioas_id = alloc_data.out_ioas_id;; + + ioctl(iommufd, IOMMU_IOAS_MAP, &map); + + /* Other device operations as stated in "VFIO Usage Example" */ + VFIO User API ------------------------------------------------------------------------------- @@ -279,6 +410,7 @@ similar to a file operations structure:: struct iommufd_ctx *ictx, u32 *out_device_id); void (*unbind_iommufd)(struct vfio_device *vdev); int (*attach_ioas)(struct vfio_device *vdev, u32 *pt_id); + void (*detach_ioas)(struct vfio_device *vdev); int (*open_device)(struct vfio_device *vdev); void (*close_device)(struct vfio_device *vdev); ssize_t (*read)(struct vfio_device *vdev, char __user *buf, @@ -315,9 +447,10 @@ container_of(). - The [un]bind_iommufd callbacks are issued when the device is bound to and unbound from iommufd. - - The attach_ioas callback is issued when the device is attached to an - IOAS managed by the bound iommufd. The attached IOAS is automatically - detached when the device is unbound from iommufd. + - The [de]attach_ioas callback is issued when the device is attached to + and detached from an IOAS managed by the bound iommufd. However, the + attached IOAS can also be automatically detached when the device is + unbound from iommufd. - The read/write/mmap callbacks implement the device region access defined by the device's own VFIO_DEVICE_GET_REGION_INFO ioctl. @@ -564,3 +697,11 @@ This implementation has some specifics: \-0d.1 00:1e.0 PCI bridge: Intel Corporation 82801 PCI Bridge (rev 90) + +.. [5] Nested translation is an IOMMU feature which supports two stage + address translations. This improves the address translation efficiency + in IOMMU virtualization. + +.. [6] PASID stands for Process Address Space ID, introduced by PCI + Express. It is a prerequisite for Shared Virtual Addressing (SVA) + and Scalable I/O Virtualization (Scalable IOV). diff --git a/Documentation/fault-injection/fault-injection.rst b/Documentation/fault-injection/fault-injection.rst index b64809514b0f..70380a2a01b4 100644 --- a/Documentation/fault-injection/fault-injection.rst +++ b/Documentation/fault-injection/fault-injection.rst @@ -243,7 +243,7 @@ proc entries Error Injectable Functions -------------------------- -This part is for the kenrel developers considering to add a function to +This part is for the kernel developers considering to add a function to ALLOW_ERROR_INJECTION() macro. Requirements for the Error Injectable Functions diff --git a/Documentation/fb/deferred_io.rst b/Documentation/fb/deferred_io.rst index 7300cff255a3..7fc1933b06d9 100644 --- a/Documentation/fb/deferred_io.rst +++ b/Documentation/fb/deferred_io.rst @@ -9,7 +9,7 @@ works: - userspace app like Xfbdev mmaps framebuffer - deferred IO and driver sets up fault and page_mkwrite handlers -- userspace app tries to write to mmaped vaddress +- userspace app tries to write to mmapped vaddress - we get pagefault and reach fault handler - fault handler finds and returns physical page - we get page_mkwrite where we add this page to a list diff --git a/Documentation/fb/sm712fb.rst b/Documentation/fb/sm712fb.rst index 994dad3b0238..8e000f80b5bc 100644 --- a/Documentation/fb/sm712fb.rst +++ b/Documentation/fb/sm712fb.rst @@ -31,5 +31,5 @@ Missing Features ================ (alias TODO list) - * 2D acceleratrion + * 2D acceleration * dual-head support diff --git a/Documentation/fb/sstfb.rst b/Documentation/fb/sstfb.rst index 42466ff49c58..88d5a52b13d8 100644 --- a/Documentation/fb/sstfb.rst +++ b/Documentation/fb/sstfb.rst @@ -73,7 +73,7 @@ Module insertion the device will be /dev/fb0. You can check this by doing a cat /proc/fb. You can find a copy of con2fb in tools/ directory. if you don't have another fb device, this step is superfluous, - as the console subsystem automagicaly binds ttys to the fb. + as the console subsystem automagically binds ttys to the fb. #. switch to the virtual console you just mapped. "tadaaa" ... Module removal diff --git a/Documentation/features/core/cBPF-JIT/arch-support.txt b/Documentation/features/core/cBPF-JIT/arch-support.txt index 0a1f5bb7eeb9..937840080de7 100644 --- a/Documentation/features/core/cBPF-JIT/arch-support.txt +++ b/Documentation/features/core/cBPF-JIT/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | TODO | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/core/eBPF-JIT/arch-support.txt b/Documentation/features/core/eBPF-JIT/arch-support.txt index 6c0f3d759e6a..7434b43c2ff8 100644 --- a/Documentation/features/core/eBPF-JIT/arch-support.txt +++ b/Documentation/features/core/eBPF-JIT/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/core/generic-idle-thread/arch-support.txt b/Documentation/features/core/generic-idle-thread/arch-support.txt index 0b94099cf6ac..0735cb5367b4 100644 --- a/Documentation/features/core/generic-idle-thread/arch-support.txt +++ b/Documentation/features/core/generic-idle-thread/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | ok | - | ia64: | ok | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/core/jump-labels/arch-support.txt b/Documentation/features/core/jump-labels/arch-support.txt index 94d9dece580f..ccada815569f 100644 --- a/Documentation/features/core/jump-labels/arch-support.txt +++ b/Documentation/features/core/jump-labels/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/core/thread-info-in-task/arch-support.txt b/Documentation/features/core/thread-info-in-task/arch-support.txt index 9c5d39eebef2..2afeb6bf6e64 100644 --- a/Documentation/features/core/thread-info-in-task/arch-support.txt +++ b/Documentation/features/core/thread-info-in-task/arch-support.txt @@ -1,7 +1,7 @@ # # Feature name: thread-info-in-task # Kconfig: THREAD_INFO_IN_TASK -# description: arch makes use of the core kernel facility to embedd thread_info in task_struct +# description: arch makes use of the core kernel facility to embed thread_info in task_struct # ----------------------- | arch |status| @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/core/tracehook/arch-support.txt b/Documentation/features/core/tracehook/arch-support.txt index aed5679da651..a72330e25542 100644 --- a/Documentation/features/core/tracehook/arch-support.txt +++ b/Documentation/features/core/tracehook/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | ok | - | ia64: | ok | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/debug/KASAN/arch-support.txt b/Documentation/features/debug/KASAN/arch-support.txt index bf0124fae643..39c6e78c0cbe 100644 --- a/Documentation/features/debug/KASAN/arch-support.txt +++ b/Documentation/features/debug/KASAN/arch-support.txt @@ -12,8 +12,7 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | - | loongarch: | TODO | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | TODO | diff --git a/Documentation/features/debug/debug-vm-pgtable/arch-support.txt b/Documentation/features/debug/debug-vm-pgtable/arch-support.txt index 9ec5d13f4939..bbf029f095cb 100644 --- a/Documentation/features/debug/debug-vm-pgtable/arch-support.txt +++ b/Documentation/features/debug/debug-vm-pgtable/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/debug/gcov-profile-all/arch-support.txt b/Documentation/features/debug/gcov-profile-all/arch-support.txt index dc4014f7e1f8..63494bddc263 100644 --- a/Documentation/features/debug/gcov-profile-all/arch-support.txt +++ b/Documentation/features/debug/gcov-profile-all/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | ok | diff --git a/Documentation/features/debug/kcov/arch-support.txt b/Documentation/features/debug/kcov/arch-support.txt index ffcc9f2b1d74..4449e1f55cd8 100644 --- a/Documentation/features/debug/kcov/arch-support.txt +++ b/Documentation/features/debug/kcov/arch-support.txt @@ -12,8 +12,7 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | - | loongarch: | TODO | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/debug/kgdb/arch-support.txt b/Documentation/features/debug/kgdb/arch-support.txt index 958498f9f2a4..f287f16ce0ec 100644 --- a/Documentation/features/debug/kgdb/arch-support.txt +++ b/Documentation/features/debug/kgdb/arch-support.txt @@ -12,8 +12,7 @@ | arm64: | ok | | csky: | TODO | | hexagon: | ok | - | ia64: | TODO | - | loongarch: | TODO | + | loongarch: | ok | | m68k: | TODO | | microblaze: | ok | | mips: | ok | diff --git a/Documentation/features/debug/kmemleak/arch-support.txt b/Documentation/features/debug/kmemleak/arch-support.txt index 4e205ef70363..f45149cfa313 100644 --- a/Documentation/features/debug/kmemleak/arch-support.txt +++ b/Documentation/features/debug/kmemleak/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | ok | diff --git a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt index bcc29d3aba9a..02febc883588 100644 --- a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt +++ b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt @@ -12,8 +12,7 @@ | arm64: | TODO | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | - | loongarch: | TODO | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | TODO | diff --git a/Documentation/features/debug/kprobes/arch-support.txt b/Documentation/features/debug/kprobes/arch-support.txt index 8a77d62a42c5..1ea27aedd098 100644 --- a/Documentation/features/debug/kprobes/arch-support.txt +++ b/Documentation/features/debug/kprobes/arch-support.txt @@ -12,8 +12,7 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | ok | - | loongarch: | TODO | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/debug/kretprobes/arch-support.txt b/Documentation/features/debug/kretprobes/arch-support.txt index cf4723c5ac55..022be42e64f9 100644 --- a/Documentation/features/debug/kretprobes/arch-support.txt +++ b/Documentation/features/debug/kretprobes/arch-support.txt @@ -12,8 +12,7 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | ok | - | loongarch: | TODO | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/debug/optprobes/arch-support.txt b/Documentation/features/debug/optprobes/arch-support.txt index 83a4639a5c0a..92f5d0f444fa 100644 --- a/Documentation/features/debug/optprobes/arch-support.txt +++ b/Documentation/features/debug/optprobes/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | TODO | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/debug/stackprotector/arch-support.txt b/Documentation/features/debug/stackprotector/arch-support.txt index 71cd4ba18f7d..de8f43f2e5d6 100644 --- a/Documentation/features/debug/stackprotector/arch-support.txt +++ b/Documentation/features/debug/stackprotector/arch-support.txt @@ -12,8 +12,7 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | - | loongarch: | TODO | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/debug/uprobes/arch-support.txt b/Documentation/features/debug/uprobes/arch-support.txt index d53f2f94fbda..0c698003ce9c 100644 --- a/Documentation/features/debug/uprobes/arch-support.txt +++ b/Documentation/features/debug/uprobes/arch-support.txt @@ -12,8 +12,7 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | - | loongarch: | TODO | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/debug/user-ret-profiler/arch-support.txt b/Documentation/features/debug/user-ret-profiler/arch-support.txt index 059110a5fa6e..3e431767581d 100644 --- a/Documentation/features/debug/user-ret-profiler/arch-support.txt +++ b/Documentation/features/debug/user-ret-profiler/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | TODO | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/io/dma-contiguous/arch-support.txt b/Documentation/features/io/dma-contiguous/arch-support.txt index bfe0921a3853..3c6ce35d704f 100644 --- a/Documentation/features/io/dma-contiguous/arch-support.txt +++ b/Documentation/features/io/dma-contiguous/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | ok | diff --git a/Documentation/features/locking/cmpxchg-local/arch-support.txt b/Documentation/features/locking/cmpxchg-local/arch-support.txt index 68329e96dffa..2c3a4b91f16d 100644 --- a/Documentation/features/locking/cmpxchg-local/arch-support.txt +++ b/Documentation/features/locking/cmpxchg-local/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/locking/lockdep/arch-support.txt b/Documentation/features/locking/lockdep/arch-support.txt index ddb945278589..b6b00469f7d0 100644 --- a/Documentation/features/locking/lockdep/arch-support.txt +++ b/Documentation/features/locking/lockdep/arch-support.txt @@ -12,14 +12,13 @@ | arm64: | ok | | csky: | ok | | hexagon: | ok | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | ok | | mips: | ok | | nios2: | TODO | | openrisc: | ok | - | parisc: | TODO | + | parisc: | ok | | powerpc: | ok | | riscv: | ok | | s390: | ok | diff --git a/Documentation/features/locking/queued-rwlocks/arch-support.txt b/Documentation/features/locking/queued-rwlocks/arch-support.txt index 5deb845477e4..b286a5fff283 100644 --- a/Documentation/features/locking/queued-rwlocks/arch-support.txt +++ b/Documentation/features/locking/queued-rwlocks/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/locking/queued-spinlocks/arch-support.txt b/Documentation/features/locking/queued-spinlocks/arch-support.txt index 2d3961bfef5d..22f2990392ff 100644 --- a/Documentation/features/locking/queued-spinlocks/arch-support.txt +++ b/Documentation/features/locking/queued-spinlocks/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/perf/kprobes-event/arch-support.txt b/Documentation/features/perf/kprobes-event/arch-support.txt index 641a7d2ff2a3..713a69fcd697 100644 --- a/Documentation/features/perf/kprobes-event/arch-support.txt +++ b/Documentation/features/perf/kprobes-event/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | ok | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/perf/perf-regs/arch-support.txt b/Documentation/features/perf/perf-regs/arch-support.txt index 33866eb242c1..09431518b0e8 100644 --- a/Documentation/features/perf/perf-regs/arch-support.txt +++ b/Documentation/features/perf/perf-regs/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/perf/perf-stackdump/arch-support.txt b/Documentation/features/perf/perf-stackdump/arch-support.txt index c8e4c7c65012..f9db4dd8ef79 100644 --- a/Documentation/features/perf/perf-stackdump/arch-support.txt +++ b/Documentation/features/perf/perf-stackdump/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/sched/membarrier-sync-core/arch-support.txt b/Documentation/features/sched/membarrier-sync-core/arch-support.txt index 23260ca44946..d96b778b87ed 100644 --- a/Documentation/features/sched/membarrier-sync-core/arch-support.txt +++ b/Documentation/features/sched/membarrier-sync-core/arch-support.txt @@ -35,7 +35,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/sched/numa-balancing/arch-support.txt b/Documentation/features/sched/numa-balancing/arch-support.txt index 532cc67cdf92..984601c7c479 100644 --- a/Documentation/features/sched/numa-balancing/arch-support.txt +++ b/Documentation/features/sched/numa-balancing/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | .. | | hexagon: | .. | - | ia64: | TODO | | loongarch: | ok | | m68k: | .. | | microblaze: | .. | diff --git a/Documentation/features/seccomp/seccomp-filter/arch-support.txt b/Documentation/features/seccomp/seccomp-filter/arch-support.txt index 3a7237b989cd..13feb679649e 100644 --- a/Documentation/features/seccomp/seccomp-filter/arch-support.txt +++ b/Documentation/features/seccomp/seccomp-filter/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | ok | | microblaze: | TODO | diff --git a/Documentation/features/time/arch-tick-broadcast/arch-support.txt b/Documentation/features/time/arch-tick-broadcast/arch-support.txt index 9bffac80019e..ccba965e8d07 100644 --- a/Documentation/features/time/arch-tick-broadcast/arch-support.txt +++ b/Documentation/features/time/arch-tick-broadcast/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/time/clockevents/arch-support.txt b/Documentation/features/time/clockevents/arch-support.txt index 625160048f68..4d4bfac52970 100644 --- a/Documentation/features/time/clockevents/arch-support.txt +++ b/Documentation/features/time/clockevents/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | ok | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | ok | diff --git a/Documentation/features/time/context-tracking/arch-support.txt b/Documentation/features/time/context-tracking/arch-support.txt index 72bc5bad0348..891be9f61903 100644 --- a/Documentation/features/time/context-tracking/arch-support.txt +++ b/Documentation/features/time/context-tracking/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/time/irq-time-acct/arch-support.txt b/Documentation/features/time/irq-time-acct/arch-support.txt index ceb036610d09..3d10075a8a8a 100644 --- a/Documentation/features/time/irq-time-acct/arch-support.txt +++ b/Documentation/features/time/irq-time-acct/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | .. | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/time/virt-cpuacct/arch-support.txt b/Documentation/features/time/virt-cpuacct/arch-support.txt index c063dffd5261..21f11d47ef72 100644 --- a/Documentation/features/time/virt-cpuacct/arch-support.txt +++ b/Documentation/features/time/virt-cpuacct/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | ok | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/vm/ELF-ASLR/arch-support.txt b/Documentation/features/vm/ELF-ASLR/arch-support.txt index 15164f36f224..57406c0d5353 100644 --- a/Documentation/features/vm/ELF-ASLR/arch-support.txt +++ b/Documentation/features/vm/ELF-ASLR/arch-support.txt @@ -1,6 +1,7 @@ # # Feature name: ELF-ASLR # Kconfig: ARCH_HAS_ELF_RANDOMIZE +# Kconfig: ARCH_WANT_DEFAULT_TOPDOWN_MMAP_LAYOUT # description: arch randomizes the stack, heap and binary images of ELF binaries # ----------------------- @@ -10,10 +11,9 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | csky: | TODO | + | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | - | loongarch: | TODO | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/vm/PG_uncached/arch-support.txt b/Documentation/features/vm/PG_uncached/arch-support.txt index 5acd64b97dba..5a7508b8c967 100644 --- a/Documentation/features/vm/PG_uncached/arch-support.txt +++ b/Documentation/features/vm/PG_uncached/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | TODO | | csky: | TODO | | hexagon: | TODO | - | ia64: | ok | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/vm/THP/arch-support.txt b/Documentation/features/vm/THP/arch-support.txt index 9dd7d75d0465..b4a5ce16940d 100644 --- a/Documentation/features/vm/THP/arch-support.txt +++ b/Documentation/features/vm/THP/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | .. | | hexagon: | .. | - | ia64: | TODO | | loongarch: | ok | | m68k: | .. | | microblaze: | .. | diff --git a/Documentation/features/vm/TLB/arch-support.txt b/Documentation/features/vm/TLB/arch-support.txt index 7f049c251a79..8fd22073a847 100644 --- a/Documentation/features/vm/TLB/arch-support.txt +++ b/Documentation/features/vm/TLB/arch-support.txt @@ -9,10 +9,9 @@ | alpha: | TODO | | arc: | TODO | | arm: | TODO | - | arm64: | N/A | + | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | .. | | microblaze: | .. | diff --git a/Documentation/features/vm/huge-vmap/arch-support.txt b/Documentation/features/vm/huge-vmap/arch-support.txt index 34647d9bdca4..2d6de7b04538 100644 --- a/Documentation/features/vm/huge-vmap/arch-support.txt +++ b/Documentation/features/vm/huge-vmap/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/vm/ioremap_prot/arch-support.txt b/Documentation/features/vm/ioremap_prot/arch-support.txt index a24149e59d73..1638c2cb17f1 100644 --- a/Documentation/features/vm/ioremap_prot/arch-support.txt +++ b/Documentation/features/vm/ioremap_prot/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/vm/pte_special/arch-support.txt b/Documentation/features/vm/pte_special/arch-support.txt index d2b22a06945e..3f777f8b67d5 100644 --- a/Documentation/features/vm/pte_special/arch-support.txt +++ b/Documentation/features/vm/pte_special/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/filesystems/9p.rst b/Documentation/filesystems/9p.rst index 1b5f0cc3e4ca..1e0e0bb6fdf9 100644 --- a/Documentation/filesystems/9p.rst +++ b/Documentation/filesystems/9p.rst @@ -79,7 +79,7 @@ Options cache=mode specifies a caching policy. By default, no caches are used. The mode can be specified as a bitmask or by using one of the - prexisting common 'shortcuts'. + preexisting common 'shortcuts'. The bitmask is described below: (unspecified bits are reserved) ========== ==================================================== diff --git a/Documentation/filesystems/afs.rst b/Documentation/filesystems/afs.rst index ca062a7f8ee2..f15ba388bbde 100644 --- a/Documentation/filesystems/afs.rst +++ b/Documentation/filesystems/afs.rst @@ -44,7 +44,7 @@ options:: CONFIG_AF_RXRPC - The RxRPC protocol transport CONFIG_RXKAD - The RxRPC Kerberos security handler - CONFIG_AFS - The AFS filesystem + CONFIG_AFS_FS - The AFS filesystem Additionally, the following can be turned on to aid debugging:: diff --git a/Documentation/filesystems/befs.rst b/Documentation/filesystems/befs.rst index 79f9740d76ff..a22f603b2938 100644 --- a/Documentation/filesystems/befs.rst +++ b/Documentation/filesystems/befs.rst @@ -106,8 +106,8 @@ iocharset=xxx Use xxx as the name of the NLS translation table. debug The driver will output debugging information to the syslog. ============= =========================================================== -How to Get Lastest Version -========================== +How to Get Latest Version +========================= The latest version is currently available at: <http://befs-driver.sourceforge.net/> diff --git a/Documentation/filesystems/btrfs.rst b/Documentation/filesystems/btrfs.rst index 992eddb0e11b..a81db8f54d68 100644 --- a/Documentation/filesystems/btrfs.rst +++ b/Documentation/filesystems/btrfs.rst @@ -37,7 +37,6 @@ For more information please refer to the documentation site or wiki https://btrfs.readthedocs.io - https://btrfs.wiki.kernel.org that maintains information about administration tasks, frequently asked questions, use cases, mount options, comprehensible changelogs, features, diff --git a/Documentation/filesystems/caching/cachefiles.rst b/Documentation/filesystems/caching/cachefiles.rst index fc7abf712315..e04a27bdbe19 100644 --- a/Documentation/filesystems/caching/cachefiles.rst +++ b/Documentation/filesystems/caching/cachefiles.rst @@ -416,7 +416,7 @@ process is the target of an operation by some other process (SIGKILL for example). The subjective security holds the active security properties of a process, and -may be overridden. This is not seen externally, and is used whan a process +may be overridden. This is not seen externally, and is used when a process acts upon another object, for example SIGKILLing another process or opening a file. diff --git a/Documentation/filesystems/caching/netfs-api.rst b/Documentation/filesystems/caching/netfs-api.rst index 1d18e9def183..665b27f1556e 100644 --- a/Documentation/filesystems/caching/netfs-api.rst +++ b/Documentation/filesystems/caching/netfs-api.rst @@ -59,7 +59,7 @@ A filesystem would typically have a volume cookie for each superblock. The filesystem then acquires a cookie for each file within that volume using an object key. Object keys are binary blobs and only need to be unique within -their parent volume. The cache backend is reponsible for rendering the binary +their parent volume. The cache backend is responsible for rendering the binary blob into something it can use and may employ hash tables, trees or whatever to improve its ability to find an object. This is transparent to the network filesystem. @@ -91,7 +91,7 @@ actually required and it can use the fscache I/O API directly. Volume Registration =================== -The first step for a network filsystem is to acquire a volume cookie for the +The first step for a network filesystem is to acquire a volume cookie for the volume it wants to access:: struct fscache_volume * @@ -119,7 +119,7 @@ is provided. If the coherency data doesn't match, the entire cache volume will be invalidated. This function can return errors such as EBUSY if the volume key is already in -use by an acquired volume or ENOMEM if an allocation failure occured. It may +use by an acquired volume or ENOMEM if an allocation failure occurred. It may also return a NULL volume cookie if fscache is not enabled. It is safe to pass a NULL cookie to any function that takes a volume cookie. This will cause that function to do nothing. diff --git a/Documentation/filesystems/ceph.rst b/Documentation/filesystems/ceph.rst index 76ce938e7024..085f309ece60 100644 --- a/Documentation/filesystems/ceph.rst +++ b/Documentation/filesystems/ceph.rst @@ -57,6 +57,16 @@ a snapshot on any subdirectory (and its nested contents) in the system. Snapshot creation and deletion are as simple as 'mkdir .snap/foo' and 'rmdir .snap/foo'. +Snapshot names have two limitations: + +* They can not start with an underscore ('_'), as these names are reserved + for internal usage by the MDS. +* They can not exceed 240 characters in size. This is because the MDS makes + use of long snapshot names internally, which follow the format: + `_<SNAPSHOT-NAME>_<INODE-NUMBER>`. Since filenames in general can't have + more than 255 characters, and `<node-id>` takes 13 characters, the long + snapshot names can take as much as 255 - 1 - 1 - 13 = 240. + Ceph also provides some recursive accounting on directories for nested files and bytes. That is, a 'getfattr -d foo' on any directory in the system will reveal the total number of nested regular files and diff --git a/Documentation/filesystems/configfs.rst b/Documentation/filesystems/configfs.rst index 8c9342ed6d25..ac22138de6a4 100644 --- a/Documentation/filesystems/configfs.rst +++ b/Documentation/filesystems/configfs.rst @@ -253,7 +253,7 @@ to be used. If binary attribute is readable and the config_item provides a ct_item_ops->read_bin_attribute() method, that method will be called whenever userspace asks for a read(2) on the attribute. The converse -will happen for write(2). The reads/writes are bufferred so only a +will happen for write(2). The reads/writes are buffered so only a single read/write will occur; the attributes' need not concern itself with it. diff --git a/Documentation/filesystems/dax.rst b/Documentation/filesystems/dax.rst index c04609d8ee24..719e90f1988e 100644 --- a/Documentation/filesystems/dax.rst +++ b/Documentation/filesystems/dax.rst @@ -291,7 +291,7 @@ The DAX code does not work correctly on architectures which have virtually mapped caches such as ARM, MIPS and SPARC. Calling :c:func:`get_user_pages()` on a range of user memory that has been -mmaped from a `DAX` file will fail when there are no 'struct page' to describe +mmapped from a `DAX` file will fail when there are no 'struct page' to describe those pages. This problem has been addressed in some device drivers by adding optional struct page support for pages under the control of the driver (see `CONFIG_NVDIMM_PFN` in ``drivers/nvdimm`` for an example of diff --git a/Documentation/filesystems/devpts.rst b/Documentation/filesystems/devpts.rst index a03248ddfb4c..b6324ab1960d 100644 --- a/Documentation/filesystems/devpts.rst +++ b/Documentation/filesystems/devpts.rst @@ -5,8 +5,8 @@ The Devpts Filesystem ===================== Each mount of the devpts filesystem is now distinct such that ptys -and their indicies allocated in one mount are independent from ptys -and their indicies in all other mounts. +and their indices allocated in one mount are independent from ptys +and their indices in all other mounts. All mounts of the devpts filesystem now create a ``/dev/pts/ptmx`` node with permissions ``0000``. diff --git a/Documentation/filesystems/erofs.rst b/Documentation/filesystems/erofs.rst index 4654ee57c1d5..57c6ae23b3fc 100644 --- a/Documentation/filesystems/erofs.rst +++ b/Documentation/filesystems/erofs.rst @@ -58,12 +58,14 @@ Here are the main features of EROFS: - Support extended attributes as an option; + - Support a bloom filter that speeds up negative extended attribute lookups; + - Support POSIX.1e ACLs by using extended attributes; - Support transparent data compression as an option: - LZ4 and MicroLZMA algorithms can be used on a per-file basis; In addition, - inplace decompression is also supported to avoid bounce compressed buffers - and page cache thrashing. + LZ4, MicroLZMA and DEFLATE algorithms can be used on a per-file basis; In + addition, inplace decompression is also supported to avoid bounce compressed + buffers and unnecessary page cache thrashing. - Support chunk-based data deduplication and rolling-hash compressed data deduplication; @@ -197,7 +199,7 @@ may not. All metadatas can be now observed in two different spaces (views): | | |__________________| 64 bytes - Xattrs, extents, data inline are followed by the corresponding inode with + Xattrs, extents, data inline are placed after the corresponding inode with proper alignment, and they could be optional for different data mappings. _currently_ total 5 data layouts are supported: @@ -268,6 +270,38 @@ details.) By the way, chunk-based files are all uncompressed for now. +Long extended attribute name prefixes +------------------------------------- +There are use cases where extended attributes with different values can have +only a few common prefixes (such as overlayfs xattrs). The predefined prefixes +work inefficiently in both image size and runtime performance in such cases. + +The long xattr name prefixes feature is introduced to address this issue. The +overall idea is that, apart from the existing predefined prefixes, the xattr +entry could also refer to user-specified long xattr name prefixes, e.g. +"trusted.overlay.". + +When referring to a long xattr name prefix, the highest bit (bit 7) of +erofs_xattr_entry.e_name_index is set, while the lower bits (bit 0-6) as a whole +represent the index of the referred long name prefix among all long name +prefixes. Therefore, only the trailing part of the name apart from the long +xattr name prefix is stored in erofs_xattr_entry.e_name, which could be empty if +the full xattr name matches exactly as its long xattr name prefix. + +All long xattr prefixes are stored one by one in the packed inode as long as +the packed inode is valid, or in the meta inode otherwise. The +xattr_prefix_count (of the on-disk superblock) indicates the total number of +long xattr name prefixes, while (xattr_prefix_start * 4) indicates the start +offset of long name prefixes in the packed/meta inode. Note that, long extended +attribute name prefixes are disabled if xattr_prefix_count is 0. + +Each long name prefix is stored in the format: ALIGN({__le16 len, data}, 4), +where len represents the total size of the data part. The data part is actually +represented by 'struct erofs_xattr_long_prefix', where base_index represents the +index of the predefined xattr name prefix, e.g. EROFS_XATTR_INDEX_TRUSTED for +"trusted.overlay." long name prefix, while the infix string keeps the string +after stripping the short prefix, e.g. "overlay." for the example above. + Data compression ---------------- EROFS implements fixed-sized output compression which generates fixed-sized diff --git a/Documentation/filesystems/ext4/super.rst b/Documentation/filesystems/ext4/super.rst index 0152888cac29..a1eb4a11a1d0 100644 --- a/Documentation/filesystems/ext4/super.rst +++ b/Documentation/filesystems/ext4/super.rst @@ -772,7 +772,7 @@ The ``s_default_mount_opts`` field is any combination of the following: * - 0x0010 - Do not support 32-bit UIDs. (EXT4_DEFM_UID16) * - 0x0020 - - All data and metadata are commited to the journal. + - All data and metadata are committed to the journal. (EXT4_DEFM_JMODE_DATA) * - 0x0040 - All data are flushed to the disk before metadata are committed to the diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index 9359978a5af2..d32c6209685d 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -359,7 +359,7 @@ errors=%s Specify f2fs behavior on critical errors. This supports modes: ====================== =============== =============== ======== mode continue remount-ro panic ====================== =============== =============== ======== - access ops normal noraml N/A + access ops normal normal N/A syscall errors -EIO -EROFS N/A mount option rw ro N/A pending dir write keep keep N/A @@ -480,7 +480,7 @@ Note: please refer to the manpage of dump.f2fs(8) to get full option list. sload.f2fs ---------- -The sload.f2fs gives a way to insert files and directories in the exisiting disk +The sload.f2fs gives a way to insert files and directories in the existing disk image. This tool is useful when building f2fs images given compiled files. Note: please refer to the manpage of sload.f2fs(8) to get full option list. @@ -792,7 +792,7 @@ Allocating disk space as a method of optimally implementing that function. However, once F2FS receives ioctl(fd, F2FS_IOC_SET_PIN_FILE) in prior to -fallocate(fd, DEFAULT_MODE), it allocates on-disk block addressess having +fallocate(fd, DEFAULT_MODE), it allocates on-disk block addresses having zero or random data, which is useful to the below scenario where: 1. create(fd) diff --git a/Documentation/filesystems/files.rst b/Documentation/filesystems/files.rst index bcf84459917f..9e38e4c221ca 100644 --- a/Documentation/filesystems/files.rst +++ b/Documentation/filesystems/files.rst @@ -62,7 +62,7 @@ the fdtable structure - be held. 4. To look up the file structure given an fd, a reader - must use either lookup_fd_rcu() or files_lookup_fd_rcu() APIs. These + must use either lookup_fdget_rcu() or files_lookup_fdget_rcu() APIs. These take care of barrier requirements due to lock-free lookup. An example:: @@ -70,43 +70,22 @@ the fdtable structure - struct file *file; rcu_read_lock(); - file = lookup_fd_rcu(fd); - if (file) { - ... - } - .... + file = lookup_fdget_rcu(fd); rcu_read_unlock(); - -5. Handling of the file structures is special. Since the look-up - of the fd (fget()/fget_light()) are lock-free, it is possible - that look-up may race with the last put() operation on the - file structure. This is avoided using atomic_long_inc_not_zero() - on ->f_count:: - - rcu_read_lock(); - file = files_lookup_fd_rcu(files, fd); if (file) { - if (atomic_long_inc_not_zero(&file->f_count)) - *fput_needed = 1; - else - /* Didn't get the reference, someone's freed */ - file = NULL; + ... + fput(file); } - rcu_read_unlock(); .... - return file; - - atomic_long_inc_not_zero() detects if refcounts is already zero or - goes to zero during increment. If it does, we fail - fget()/fget_light(). -6. Since both fdtable and file structures can be looked up +5. Since both fdtable and file structures can be looked up lock-free, they must be installed using rcu_assign_pointer() API. If they are looked up lock-free, rcu_dereference() must be used. However it is advisable to use files_fdtable() - and lookup_fd_rcu()/files_lookup_fd_rcu() which take care of these issues. + and lookup_fdget_rcu()/files_lookup_fdget_rcu() which take care of these + issues. -7. While updating, the fdtable pointer must be looked up while +6. While updating, the fdtable pointer must be looked up while holding files->file_lock. If ->file_lock is dropped, then another thread expand the files thereby creating a new fdtable and making the earlier fdtable pointer stale. @@ -126,3 +105,19 @@ the fdtable structure - Since locate_fd() can drop ->file_lock (and reacquire ->file_lock), the fdtable pointer (fdt) must be loaded after locate_fd(). +On newer kernels rcu based file lookup has been switched to rely on +SLAB_TYPESAFE_BY_RCU instead of call_rcu(). It isn't sufficient anymore +to just acquire a reference to the file in question under rcu using +atomic_long_inc_not_zero() since the file might have already been +recycled and someone else might have bumped the reference. In other +words, callers might see reference count bumps from newer users. For +this is reason it is necessary to verify that the pointer is the same +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 +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 +fdtable. diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index eccd327e6df5..1b84f818e574 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -261,9 +261,9 @@ DIRECT_KEY policies The Adiantum encryption mode (see `Encryption modes and usage`_) is suitable for both contents and filenames encryption, and it accepts -long IVs --- long enough to hold both an 8-byte logical block number -and a 16-byte per-file nonce. Also, the overhead of each Adiantum key -is greater than that of an AES-256-XTS key. +long IVs --- long enough to hold both an 8-byte data unit index and a +16-byte per-file nonce. Also, the overhead of each Adiantum key is +greater than that of an AES-256-XTS key. Therefore, to improve performance and save memory, for Adiantum a "direct key" configuration is supported. When the user has enabled @@ -300,8 +300,8 @@ IV_INO_LBLK_32 policies IV_INO_LBLK_32 policies work like IV_INO_LBLK_64, except that for IV_INO_LBLK_32, the inode number is hashed with SipHash-2-4 (where the -SipHash key is derived from the master key) and added to the file -logical block number mod 2^32 to produce a 32-bit IV. +SipHash key is derived from the master key) and added to the file data +unit index mod 2^32 to produce a 32-bit IV. This format is optimized for use with inline encryption hardware compliant with the eMMC v5.2 standard, which supports only 32 IV bits @@ -332,83 +332,181 @@ Encryption modes and usage fscrypt allows one encryption mode to be specified for file contents and one encryption mode to be specified for filenames. Different directory trees are permitted to use different encryption modes. + +Supported modes +--------------- + Currently, the following pairs of encryption modes are supported: - AES-256-XTS for contents and AES-256-CTS-CBC for filenames -- AES-128-CBC for contents and AES-128-CTS-CBC for filenames +- AES-256-XTS for contents and AES-256-HCTR2 for filenames - Adiantum for both contents and filenames -- AES-256-XTS for contents and AES-256-HCTR2 for filenames (v2 policies only) -- SM4-XTS for contents and SM4-CTS-CBC for filenames (v2 policies only) - -If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair. - -AES-128-CBC was added only for low-powered embedded devices with -crypto accelerators such as CAAM or CESA that do not support XTS. To -use AES-128-CBC, CONFIG_CRYPTO_ESSIV and CONFIG_CRYPTO_SHA256 (or -another SHA-256 implementation) must be enabled so that ESSIV can be -used. - -Adiantum is a (primarily) stream cipher-based mode that is fast even -on CPUs without dedicated crypto instructions. It's also a true -wide-block mode, unlike XTS. It can also eliminate the need to derive -per-file encryption keys. However, it depends on the security of two -primitives, XChaCha12 and AES-256, rather than just one. See the -paper "Adiantum: length-preserving encryption for entry-level -processors" (https://eprint.iacr.org/2018/720.pdf) for more details. -To use Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled. Also, fast -implementations of ChaCha and NHPoly1305 should be enabled, e.g. -CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM. - -AES-256-HCTR2 is another true wide-block encryption mode that is intended for -use on CPUs with dedicated crypto instructions. AES-256-HCTR2 has the property -that a bitflip in the plaintext changes the entire ciphertext. This property -makes it desirable for filename encryption since initialization vectors are -reused within a directory. For more details on AES-256-HCTR2, see the paper -"Length-preserving encryption with HCTR2" -(https://eprint.iacr.org/2021/1441.pdf). To use AES-256-HCTR2, -CONFIG_CRYPTO_HCTR2 must be enabled. Also, fast implementations of XCTR and -POLYVAL should be enabled, e.g. CRYPTO_POLYVAL_ARM64_CE and -CRYPTO_AES_ARM64_CE_BLK for ARM64. - -SM4 is a Chinese block cipher that is an alternative to AES. It has -not seen as much security review as AES, and it only has a 128-bit key -size. It may be useful in cases where its use is mandated. -Otherwise, it should not be used. For SM4 support to be available, it -also needs to be enabled in the kernel crypto API. - -New encryption modes can be added relatively easily, without changes -to individual filesystems. However, authenticated encryption (AE) -modes are not currently supported because of the difficulty of dealing -with ciphertext expansion. +- AES-128-CBC-ESSIV for contents and AES-128-CTS-CBC for filenames +- SM4-XTS for contents and SM4-CTS-CBC for filenames + +Authenticated encryption modes are not currently supported because of +the difficulty of dealing with ciphertext expansion. Therefore, +contents encryption uses a block cipher in `XTS mode +<https://en.wikipedia.org/wiki/Disk_encryption_theory#XTS>`_ or +`CBC-ESSIV mode +<https://en.wikipedia.org/wiki/Disk_encryption_theory#Encrypted_salt-sector_initialization_vector_(ESSIV)>`_, +or a wide-block cipher. Filenames encryption uses a +block cipher in `CTS-CBC mode +<https://en.wikipedia.org/wiki/Ciphertext_stealing>`_ or a wide-block +cipher. + +The (AES-256-XTS, AES-256-CTS-CBC) pair is the recommended default. +It is also the only option that is *guaranteed* to always be supported +if the kernel supports fscrypt at all; see `Kernel config options`_. + +The (AES-256-XTS, AES-256-HCTR2) pair is also a good choice that +upgrades the filenames encryption to use a wide-block cipher. (A +*wide-block cipher*, also called a tweakable super-pseudorandom +permutation, has the property that changing one bit scrambles the +entire result.) As described in `Filenames encryption`_, a wide-block +cipher is the ideal mode for the problem domain, though CTS-CBC is the +"least bad" choice among the alternatives. For more information about +HCTR2, see `the HCTR2 paper <https://eprint.iacr.org/2021/1441.pdf>`_. + +Adiantum is recommended on systems where AES is too slow due to lack +of hardware acceleration for AES. Adiantum is a wide-block cipher +that uses XChaCha12 and AES-256 as its underlying components. Most of +the work is done by XChaCha12, which is much faster than AES when AES +acceleration is unavailable. For more information about Adiantum, see +`the Adiantum paper <https://eprint.iacr.org/2018/720.pdf>`_. + +The (AES-128-CBC-ESSIV, AES-128-CTS-CBC) pair exists only to support +systems whose only form of AES acceleration is an off-CPU crypto +accelerator such as CAAM or CESA that does not support XTS. + +The remaining mode pairs are the "national pride ciphers": + +- (SM4-XTS, SM4-CTS-CBC) + +Generally speaking, these ciphers aren't "bad" per se, but they +receive limited security review compared to the usual choices such as +AES and ChaCha. They also don't bring much new to the table. It is +suggested to only use these ciphers where their use is mandated. + +Kernel config options +--------------------- + +Enabling fscrypt support (CONFIG_FS_ENCRYPTION) automatically pulls in +only the basic support from the crypto API needed to use AES-256-XTS +and AES-256-CTS-CBC encryption. For optimal performance, it is +strongly recommended to also enable any available platform-specific +kconfig options that provide acceleration for the algorithm(s) you +wish to use. Support for any "non-default" encryption modes typically +requires extra kconfig options as well. + +Below, some relevant options are listed by encryption mode. Note, +acceleration options not listed below may be available for your +platform; refer to the kconfig menus. File contents encryption can +also be configured to use inline encryption hardware instead of the +kernel crypto API (see `Inline encryption support`_); in that case, +the file contents mode doesn't need to supported in the kernel crypto +API, but the filenames mode still does. + +- AES-256-XTS and AES-256-CTS-CBC + - Recommended: + - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK + - x86: CONFIG_CRYPTO_AES_NI_INTEL + +- AES-256-HCTR2 + - Mandatory: + - CONFIG_CRYPTO_HCTR2 + - Recommended: + - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK + - arm64: CONFIG_CRYPTO_POLYVAL_ARM64_CE + - x86: CONFIG_CRYPTO_AES_NI_INTEL + - x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI + +- Adiantum + - Mandatory: + - CONFIG_CRYPTO_ADIANTUM + - Recommended: + - arm32: CONFIG_CRYPTO_CHACHA20_NEON + - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON + - arm64: CONFIG_CRYPTO_CHACHA20_NEON + - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON + - x86: CONFIG_CRYPTO_CHACHA20_X86_64 + - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2 + - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2 + +- AES-128-CBC-ESSIV and AES-128-CTS-CBC: + - Mandatory: + - CONFIG_CRYPTO_ESSIV + - CONFIG_CRYPTO_SHA256 or another SHA-256 implementation + - Recommended: + - AES-CBC acceleration + +fscrypt also uses HMAC-SHA512 for key derivation, so enabling SHA-512 +acceleration is recommended: + +- SHA-512 + - Recommended: + - arm64: CONFIG_CRYPTO_SHA512_ARM64_CE + - x86: CONFIG_CRYPTO_SHA512_SSSE3 Contents encryption ------------------- -For file contents, each filesystem block is encrypted independently. -Starting from Linux kernel 5.5, encryption of filesystems with block -size less than system's page size is supported. - -Each block's IV is set to the logical block number within the file as -a little endian number, except that: - -- With CBC mode encryption, ESSIV is also used. Specifically, each IV - is encrypted with AES-256 where the AES-256 key is the SHA-256 hash - of the file's data encryption key. - -- With `DIRECT_KEY policies`_, the file's nonce is appended to the IV. - Currently this is only allowed with the Adiantum encryption mode. - -- With `IV_INO_LBLK_64 policies`_, the logical block number is limited - to 32 bits and is placed in bits 0-31 of the IV. The inode number - (which is also limited to 32 bits) is placed in bits 32-63. - -- With `IV_INO_LBLK_32 policies`_, the logical block number is limited - to 32 bits and is placed in bits 0-31 of the IV. The inode number - is then hashed and added mod 2^32. - -Note that because file logical block numbers are included in the IVs, -filesystems must enforce that blocks are never shifted around within -encrypted files, e.g. via "collapse range" or "insert range". +For contents encryption, each file's contents is divided into "data +units". Each data unit is encrypted independently. The IV for each +data unit incorporates the zero-based index of the data unit within +the file. This ensures that each data unit within a file is encrypted +differently, which is essential to prevent leaking information. + +Note: the encryption depending on the offset into the file means that +operations like "collapse range" and "insert range" that rearrange the +extent mapping of files are not supported on encrypted files. + +There are two cases for the sizes of the data units: + +* Fixed-size data units. This is how all filesystems other than UBIFS + work. A file's data units are all the same size; the last data unit + is zero-padded if needed. By default, the data unit size is equal + to the filesystem block size. On some filesystems, users can select + a sub-block data unit size via the ``log2_data_unit_size`` field of + the encryption policy; see `FS_IOC_SET_ENCRYPTION_POLICY`_. + +* Variable-size data units. This is what UBIFS does. Each "UBIFS + data node" is treated as a crypto data unit. Each contains variable + length, possibly compressed data, zero-padded to the next 16-byte + boundary. Users cannot select a sub-block data unit size on UBIFS. + +In the case of compression + encryption, the compressed data is +encrypted. UBIFS compression works as described above. f2fs +compression works a bit differently; it compresses a number of +filesystem blocks into a smaller number of filesystem blocks. +Therefore a f2fs-compressed file still uses fixed-size data units, and +it is encrypted in a similar way to a file containing holes. + +As mentioned in `Key hierarchy`_, the default encryption setting uses +per-file keys. In this case, the IV for each data unit is simply the +index of the data unit in the file. However, users can select an +encryption setting that does not use per-file keys. For these, some +kind of file identifier is incorporated into the IVs as follows: + +- With `DIRECT_KEY policies`_, the data unit index is placed in bits + 0-63 of the IV, and the file's nonce is placed in bits 64-191. + +- With `IV_INO_LBLK_64 policies`_, the data unit index is placed in + bits 0-31 of the IV, and the file's inode number is placed in bits + 32-63. This setting is only allowed when data unit indices and + inode numbers fit in 32 bits. + +- With `IV_INO_LBLK_32 policies`_, the file's inode number is hashed + and added to the data unit index. The resulting value is truncated + to 32 bits and placed in bits 0-31 of the IV. This setting is only + allowed when data unit indices and inode numbers fit in 32 bits. + +The byte order of the IV is always little endian. + +If the user selects FSCRYPT_MODE_AES_128_CBC for the contents mode, an +ESSIV layer is automatically included. In this case, before the IV is +passed to AES-128-CBC, it is encrypted with AES-256 where the AES-256 +key is the SHA-256 hash of the file's contents encryption key. Filenames encryption -------------------- @@ -477,7 +575,8 @@ follows:: __u8 contents_encryption_mode; __u8 filenames_encryption_mode; __u8 flags; - __u8 __reserved[4]; + __u8 log2_data_unit_size; + __u8 __reserved[3]; __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; }; @@ -493,7 +592,14 @@ This structure must be initialized as follows: be set to constants from ``<linux/fscrypt.h>`` which identify the encryption modes to use. If unsure, use FSCRYPT_MODE_AES_256_XTS (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS - (4) for ``filenames_encryption_mode``. + (4) for ``filenames_encryption_mode``. For details, see `Encryption + modes and usage`_. + + v1 encryption policies only support three combinations of modes: + (FSCRYPT_MODE_AES_256_XTS, FSCRYPT_MODE_AES_256_CTS), + (FSCRYPT_MODE_AES_128_CBC, FSCRYPT_MODE_AES_128_CTS), and + (FSCRYPT_MODE_ADIANTUM, FSCRYPT_MODE_ADIANTUM). v2 policies support + all combinations documented in `Supported modes`_. - ``flags`` contains optional flags from ``<linux/fscrypt.h>``: @@ -512,6 +618,29 @@ This structure must be initialized as follows: The DIRECT_KEY, IV_INO_LBLK_64, and IV_INO_LBLK_32 flags are mutually exclusive. +- ``log2_data_unit_size`` is the log2 of the data unit size in bytes, + or 0 to select the default data unit size. The data unit size is + the granularity of file contents encryption. For example, setting + ``log2_data_unit_size`` to 12 causes file contents be passed to the + underlying encryption algorithm (such as AES-256-XTS) in 4096-byte + data units, each with its own IV. + + Not all filesystems support setting ``log2_data_unit_size``. ext4 + and f2fs support it since Linux v6.7. On filesystems that support + it, the supported nonzero values are 9 through the log2 of the + filesystem block size, inclusively. The default value of 0 selects + the filesystem block size. + + The main use case for ``log2_data_unit_size`` is for selecting a + data unit size smaller than the filesystem block size for + compatibility with inline encryption hardware that only supports + smaller data unit sizes. ``/sys/block/$disk/queue/crypto/`` may be + useful for checking which data unit sizes are supported by a + particular system's inline encryption hardware. + + Leave this field zeroed unless you are certain you need it. Using + an unnecessarily small data unit size reduces performance. + - For v2 encryption policies, ``__reserved`` must be zeroed. - For v1 encryption policies, ``master_key_descriptor`` specifies how @@ -1005,8 +1134,8 @@ The caller must zero all input fields, then fill in ``key_spec``: On success, 0 is returned and the kernel fills in the output fields: - ``status`` indicates whether the key is absent, present, or - incompletely removed. Incompletely removed means that the master - secret has been removed, but some files are still in use; i.e., + incompletely removed. Incompletely removed means that removal has + been initiated, but some files are still in use; i.e., `FS_IOC_REMOVE_ENCRYPTION_KEY`_ returned 0 but set the informational status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY. diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst index cb845e8e5435..13e4b18e5dbb 100644 --- a/Documentation/filesystems/fsverity.rst +++ b/Documentation/filesystems/fsverity.rst @@ -326,6 +326,8 @@ the file has fs-verity enabled. This can perform better than FS_IOC_GETFLAGS and FS_IOC_MEASURE_VERITY because it doesn't require opening the file, and opening verity files can be expensive. +.. _accessing_verity_files: + Accessing verity files ====================== diff --git a/Documentation/filesystems/gfs2-glocks.rst b/Documentation/filesystems/gfs2-glocks.rst index d14f230f0b12..8a5842929b60 100644 --- a/Documentation/filesystems/gfs2-glocks.rst +++ b/Documentation/filesystems/gfs2-glocks.rst @@ -20,8 +20,7 @@ The gl_holders list contains all the queued lock requests (not just the holders) associated with the glock. If there are any held locks, then they will be contiguous entries at the head of the list. Locks are granted in strictly the order that they -are queued, except for those marked LM_FLAG_PRIORITY which are -used only during recovery, and even then only for journal locks. +are queued. There are three lock states that users of the glock layer can request, namely shared (SH), deferred (DF) and exclusive (EX). Those translate @@ -78,7 +77,7 @@ The minimum hold time for each lock is the time after a remote lock grant for which we ignore remote demote requests. This is in order to prevent a situation where locks are being bounced around the cluster from node to node with none of the nodes making any progress. This -tends to show up most with shared mmaped files which are being written +tends to show up most with shared mmapped files which are being written to by multiple nodes. By delaying the demotion in response to a remote callback, that gives the userspace program time to make some progress before the pages are unmapped. diff --git a/Documentation/filesystems/idmappings.rst b/Documentation/filesystems/idmappings.rst index ad6d21640576..ac0af679e61e 100644 --- a/Documentation/filesystems/idmappings.rst +++ b/Documentation/filesystems/idmappings.rst @@ -36,7 +36,7 @@ and write down the mappings it will generate:: From a mathematical viewpoint ``U`` and ``K`` are well-ordered sets and an idmapping is an order isomorphism from ``U`` into ``K``. So ``U`` and ``K`` are order isomorphic. In fact, ``U`` and ``K`` are always well-ordered subsets of -the set of all possible ids useable on a given system. +the set of all possible ids usable on a given system. Looking at this mathematically briefly will help us highlight some properties that make it easier to understand how we can translate between idmappings. For @@ -47,7 +47,7 @@ example, we know that the inverse idmapping is an order isomorphism as well:: k10002 -> u24 Given that we are dealing with order isomorphisms plus the fact that we're -dealing with subsets we can embedd idmappings into each other, i.e. we can +dealing with subsets we can embed idmappings into each other, i.e. we can sensibly translate between different idmappings. For example, assume we've been given the three idmappings:: @@ -60,7 +60,7 @@ and id ``k11000`` which has been generated by the first idmapping by mapping Because we're dealing with order isomorphic subsets it is meaningful to ask what id ``k11000`` corresponds to in the second or third idmapping. The -straightfoward algorithm to use is to apply the inverse of the first idmapping, +straightforward algorithm to use is to apply the inverse of the first idmapping, mapping ``k11000`` up to ``u1000``. Afterwards, we can map ``u1000`` down using either the second idmapping mapping or third idmapping mapping. The second idmapping would map ``u1000`` down to ``21000``. The third idmapping would map @@ -146,9 +146,10 @@ For the rest of this document we will prefix all userspace ids with ``u`` and all kernel ids with ``k``. Ranges of idmappings will be prefixed with ``r``. So an idmapping will be written as ``u0:k10000:r10000``. -For example, the id ``u1000`` is an id in the upper idmapset or "userspace -idmapset" starting with ``u1000``. And it is mapped to ``k11000`` which is a -kernel id in the lower idmapset or "kernel idmapset" starting with ``k10000``. +For example, within this idmapping, the id ``u1000`` is an id in the upper +idmapset or "userspace idmapset" starting with ``u0``. And it is mapped to +``k11000`` which is a kernel id in the lower idmapset or "kernel idmapset" +starting with ``k10000``. A kernel id is always created by an idmapping. Such idmappings are associated with user namespaces. Since we mainly care about how idmappings work we're not @@ -367,12 +368,19 @@ So with the second step the kernel guarantees that a valid userspace id can be written to disk. If it can't the kernel will refuse the creation request to not even remotely risk filesystem corruption. -The astute reader will have realized that this is simply a varation of the +The astute reader will have realized that this is simply a variation of the crossmapping algorithm we mentioned above in a previous section. First, the kernel maps the caller's userspace id down into a kernel id according to the caller's idmapping and then maps that kernel id up according to the filesystem's idmapping. +From the implementation point it's worth mentioning how idmappings are represented. +All idmappings are taken from the corresponding user namespace. + + - caller's idmapping (usually taken from ``current_user_ns()``) + - filesystem's idmapping (``sb->s_user_ns``) + - mount's idmapping (``mnt_idmap(vfsmnt)``) + Let's see some examples with caller/filesystem idmapping but without mount idmappings. This will exhibit some problems we can hit. After that we will revisit/reconsider these examples, this time using mount idmappings, to see how @@ -458,7 +466,7 @@ the kernel id that was created in the caller's idmapping. This has mainly two consequences. First, that we can't allow a caller to ultimately write to disk with another -userspace id. We could only do this if we were to mount the whole fileystem +userspace id. We could only do this if we were to mount the whole filesystem with the caller's or another idmapping. But that solution is limited to a few filesystems and not very flexible. But this is a use-case that is pretty important in containerized workloads. @@ -589,7 +597,7 @@ on their work machine. In both cases changing ownership recursively has grave implications. The most obvious one is that ownership is changed globally and permanently. In the home -directory case this change in ownership would even need to happen everytime the +directory case this change in ownership would even need to happen every time the user switches from their home to their work machine. For really large sets of files this becomes increasingly costly. @@ -662,7 +670,7 @@ use the ``vfsuid_into_kuid()`` and ``vfsgid_into_kgid()`` helpers. To illustrate why this helper currently exists, consider what happens when we change ownership of an inode from an idmapped mount. After we generated a ``vfsuid_t`` or ``vfsgid_t`` based on the mount idmapping we later commit to -this ``vfsuid_t`` or ``vfsgid_t`` to become the new filesytem wide ownership. +this ``vfsuid_t`` or ``vfsgid_t`` to become the new filesystem wide ownership. Thus, we are turning the ``vfsuid_t`` or ``vfsgid_t`` into a global ``kuid_t`` or ``kgid_t``. And this can be done by using ``vfsuid_into_kuid()`` and ``vfsgid_into_kgid()``. diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index eb252fc972aa..09cade7eaefc 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -122,6 +122,7 @@ Documentation for filesystem implementations. virtiofs vfat xfs-delayed-logging-design + xfs-maintainer-entry-profile xfs-self-describing-metadata xfs-online-fsck-design zonefs diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index ed148919e11a..7be2900806c8 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -85,13 +85,14 @@ prototypes:: struct dentry *dentry, struct fileattr *fa); int (*fileattr_get)(struct dentry *dentry, struct fileattr *fa); struct posix_acl * (*get_acl)(struct mnt_idmap *, struct dentry *, int); + struct offset_ctx *(*get_offset_ctx)(struct inode *inode); locking rules: all may block -============== ============================================= +============== ================================================== ops i_rwsem(inode) -============== ============================================= +============== ================================================== lookup: shared create: exclusive link: exclusive (both) @@ -115,7 +116,8 @@ atomic_open: shared (exclusive if O_CREAT is set in open flags) tmpfile: no fileattr_get: no or exclusive fileattr_set: exclusive -============== ============================================= +get_offset_ctx no +============== ================================================== Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem @@ -374,10 +376,17 @@ invalidate_lock before invalidating page cache in truncate / hole punch path (and thus calling into ->invalidate_folio) to block races between page cache invalidation and page cache filling functions (fault, read, ...). -->release_folio() is called when the kernel is about to try to drop the -buffers from the folio in preparation for freeing it. It returns false to -indicate that the buffers are (or may be) freeable. If ->release_folio is -NULL, the kernel assumes that the fs has no private interest in the buffers. +->release_folio() is called when the MM wants to make a change to the +folio that would invalidate the filesystem's private data. For example, +it may be about to be removed from the address_space or split. The folio +is locked and not under writeback. It may be dirty. The gfp parameter +is not usually used for allocation, but rather to indicate what the +filesystem may do to attempt to free the private data. The filesystem may +return false to indicate that the folio's private data cannot be freed. +If it returns true, it should have already removed the private data from +the folio. If a filesystem does not provide a ->release_folio method, +the pagecache will assume that private data is buffer_heads and call +try_to_free_buffers(). ->free_folio() is called when the kernel has dropped the folio from the page cache. @@ -509,7 +518,6 @@ prototypes:: ssize_t (*read_iter) (struct kiocb *, struct iov_iter *); ssize_t (*write_iter) (struct kiocb *, struct iov_iter *); int (*iopoll) (struct kiocb *kiocb, bool spin); - int (*iterate) (struct file *, struct dir_context *); int (*iterate_shared) (struct file *, struct dir_context *); __poll_t (*poll) (struct file *, struct poll_table_struct *); long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); @@ -551,9 +559,8 @@ mutex or just to use i_size_read() instead. Note: this does not protect the file->f_pos against concurrent modifications since this is something the userspace has to take care about. -->iterate() is called with i_rwsem exclusive. - -->iterate_shared() is called with i_rwsem at least shared. +->iterate_shared() is called with i_rwsem held for reading, and with the +file f_pos_lock held exclusively ->fasync() is responsible for maintaining the FASYNC bit in filp->f_flags. Most instances call fasync_helper(), which does that maintenance, so it's @@ -628,26 +635,29 @@ vm_operations_struct prototypes:: - void (*open)(struct vm_area_struct*); - void (*close)(struct vm_area_struct*); - vm_fault_t (*fault)(struct vm_area_struct*, struct vm_fault *); + void (*open)(struct vm_area_struct *); + void (*close)(struct vm_area_struct *); + vm_fault_t (*fault)(struct vm_fault *); + vm_fault_t (*huge_fault)(struct vm_fault *, unsigned int order); + vm_fault_t (*map_pages)(struct vm_fault *, pgoff_t start, pgoff_t end); vm_fault_t (*page_mkwrite)(struct vm_area_struct *, struct vm_fault *); vm_fault_t (*pfn_mkwrite)(struct vm_area_struct *, struct vm_fault *); int (*access)(struct vm_area_struct *, unsigned long, void*, int, int); locking rules: -============= ========= =========================== +============= ========== =========================== ops mmap_lock PageLocked(page) -============= ========= =========================== -open: yes -close: yes -fault: yes can return with page locked -map_pages: read -page_mkwrite: yes can return with page locked -pfn_mkwrite: yes -access: yes -============= ========= =========================== +============= ========== =========================== +open: write +close: read/write +fault: read can return with page locked +huge_fault: maybe-read +map_pages: maybe-read +page_mkwrite: read can return with page locked +pfn_mkwrite: read +access: read +============= ========== =========================== ->fault() is called when a previously not present pte is about to be faulted in. The filesystem must find and return the page associated with the passed in @@ -657,11 +667,18 @@ then ensure the page is not already truncated (invalidate_lock will block subsequent truncate), and then return with VM_FAULT_LOCKED, and the page locked. The VM will unlock the page. +->huge_fault() is called when there is no PUD or PMD entry present. This +gives the filesystem the opportunity to install a PUD or PMD sized page. +Filesystems can also use the ->fault method to return a PMD sized page, +so implementing this function may not be necessary. In particular, +filesystems should not call filemap_fault() from ->huge_fault(). +The mmap_lock may not be held when this method is called. + ->map_pages() is called when VM asks to map easy accessible pages. Filesystem should find and map pages associated with offsets from "start_pgoff" till "end_pgoff". ->map_pages() is called with the RCU lock held and must not block. If it's not possible to reach a page without blocking, -filesystem should skip it. Filesystem should use do_set_pte() to setup +filesystem should skip it. Filesystem should use set_pte_range() to setup page table entry. Pointer to entry associated with the page is passed in "pte" field in vm_fault structure. Pointers to entries for other offsets should be calculated relative to "pte". diff --git a/Documentation/filesystems/netfs_library.rst b/Documentation/filesystems/netfs_library.rst index 73a4176144b3..48b95d04f72d 100644 --- a/Documentation/filesystems/netfs_library.rst +++ b/Documentation/filesystems/netfs_library.rst @@ -155,7 +155,7 @@ conflicting writes or track dirty data and needs to put the acquired folio if an error occurs after calling the helper. The helpers manage the read request, calling back into the network filesystem -through the suppplied table of operations. Waits will be performed as +through the supplied table of operations. Waits will be performed as necessary before returning for helpers that are meant to be synchronous. If an error occurs, the ->free_request() will be called to clean up the diff --git a/Documentation/filesystems/nfs/client-identifier.rst b/Documentation/filesystems/nfs/client-identifier.rst index a94c7a9748d7..4804441155f5 100644 --- a/Documentation/filesystems/nfs/client-identifier.rst +++ b/Documentation/filesystems/nfs/client-identifier.rst @@ -131,7 +131,7 @@ deployments, this construction is usually adequate. Often, however, the node name by itself is not adequately unique, and can change unexpectedly. Problematic situations include: - - NFS-root (diskless) clients, where the local DCHP server (or + - NFS-root (diskless) clients, where the local DHCP server (or equivalent) does not provide a unique host name. - "Containers" within a single Linux host. If each container has diff --git a/Documentation/filesystems/nfs/exporting.rst b/Documentation/filesystems/nfs/exporting.rst index 3d97b8d8f735..198d805d611c 100644 --- a/Documentation/filesystems/nfs/exporting.rst +++ b/Documentation/filesystems/nfs/exporting.rst @@ -215,3 +215,36 @@ following flags are defined: This flag causes nfsd to close any open files for this inode _before_ calling into the vfs to do an unlink or a rename that would replace an existing file. + + EXPORT_OP_REMOTE_FS - Backing storage for this filesystem is remote + PF_LOCAL_THROTTLE exists for loopback NFSD, where a thread needs to + write to one bdi (the final bdi) in order to free up writes queued + to another bdi (the client bdi). Such threads get a private balance + of dirty pages so that dirty pages for the client bdi do not imact + the daemon writing to the final bdi. For filesystems whose durable + storage is not local (such as exported NFS filesystems), this + constraint has negative consequences. EXPORT_OP_REMOTE_FS enables + an export to disable writeback throttling. + + EXPORT_OP_NOATOMIC_ATTR - Filesystem does not update attributes atomically + EXPORT_OP_NOATOMIC_ATTR indicates that the exported filesystem + cannot provide the semantics required by the "atomic" boolean in + NFSv4's change_info4. This boolean indicates to a client whether the + returned before and after change attributes were obtained atomically + with the respect to the requested metadata operation (UNLINK, + OPEN/CREATE, MKDIR, etc). + + EXPORT_OP_FLUSH_ON_CLOSE - Filesystem flushes file data on close(2) + On most filesystems, inodes can remain under writeback after the + file is closed. NFSD relies on client activity or local flusher + threads to handle writeback. Certain filesystems, such as NFS, flush + all of an inode's dirty data on last close. Exports that behave this + way should set EXPORT_OP_FLUSH_ON_CLOSE so that NFSD knows to skip + waiting for writeback when closing such files. + + EXPORT_OP_ASYNC_LOCK - Indicates a capable filesystem to do async lock + requests from lockd. Only set EXPORT_OP_ASYNC_LOCK if the filesystem has + it's own ->lock() functionality as core posix_lock_file() implementation + has no async lock request handling yet. For more information about how to + indicate an async lock request from a ->lock() file_operations struct, see + fs/locks.c and comment for the function vfs_lock_file(). diff --git a/Documentation/filesystems/nfs/rpc-cache.rst b/Documentation/filesystems/nfs/rpc-cache.rst index bb164eea969b..339efd75016a 100644 --- a/Documentation/filesystems/nfs/rpc-cache.rst +++ b/Documentation/filesystems/nfs/rpc-cache.rst @@ -78,7 +78,7 @@ Creating a Cache include taking references to shared objects. void update(struct cache_head \*orig, struct cache_head \*new) - Set the 'content' fileds in 'new' from 'orig'. + Set the 'content' fields in 'new' from 'orig'. int cache_show(struct seq_file \*m, struct cache_detail \*cd, struct cache_head \*h) Optional. Used to provide a /proc file that lists the diff --git a/Documentation/filesystems/nfs/rpc-server-gss.rst b/Documentation/filesystems/nfs/rpc-server-gss.rst index ccaea9e7cea2..5c1a1c58fc27 100644 --- a/Documentation/filesystems/nfs/rpc-server-gss.rst +++ b/Documentation/filesystems/nfs/rpc-server-gss.rst @@ -29,7 +29,7 @@ The Linux kernel, at the moment, supports only the KRB5 mechanism, and depends on GSSAPI extensions that are KRB5 specific. GSSAPI is a complex library, and implementing it completely in kernel is -unwarranted. However GSSAPI operations are fundementally separable in 2 +unwarranted. However GSSAPI operations are fundamentally separable in 2 parts: - initial context establishment diff --git a/Documentation/filesystems/nilfs2.rst b/Documentation/filesystems/nilfs2.rst index 6c49f04e9e0a..e3a5c8977f2c 100644 --- a/Documentation/filesystems/nilfs2.rst +++ b/Documentation/filesystems/nilfs2.rst @@ -231,7 +231,7 @@ file structures (nilfs_finfo), and per block structures (nilfs_binfo):: The logs include regular files, directory files, symbolic link files -and several meta data files. The mata data files are the files used +and several meta data files. The meta data files are the files used to maintain file system meta data. The current version of NILFS2 uses the following meta data files:: diff --git a/Documentation/filesystems/ntfs3.rst b/Documentation/filesystems/ntfs3.rst index f0cf05cad2ba..2b86a9b3a6de 100644 --- a/Documentation/filesystems/ntfs3.rst +++ b/Documentation/filesystems/ntfs3.rst @@ -112,7 +112,7 @@ this table marked with no it means default is without **no**. Todo list ========= - Full journaling support over JBD. Currently journal replaying is supported - which is not necessarily as effectice as JBD would be. + which is not necessarily as effective as JBD would be. References ========== diff --git a/Documentation/filesystems/orangefs.rst b/Documentation/filesystems/orangefs.rst index 463e37694250..931159e61796 100644 --- a/Documentation/filesystems/orangefs.rst +++ b/Documentation/filesystems/orangefs.rst @@ -274,7 +274,7 @@ then contains: of kcalloced memory. This memory is used as an array of pointers to each of the pages in the IO buffer through a call to get_user_pages. * desc_array - a pointer to ``desc_count * (sizeof(struct orangefs_bufmap_desc))`` - bytes of kcalloced memory. This memory is further intialized: + bytes of kcalloced memory. This memory is further initialized: user_desc is the kernel's copy of the IO buffer's ORANGEFS_dev_map_desc structure. user_desc->ptr points to the IO buffer. diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index eb7d2c88ddec..5b93268e400f 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -195,7 +195,7 @@ handle it in two different ways: 1. return EXDEV error: this error is returned by rename(2) when trying to move a file or directory across filesystem boundaries. Hence - applications are usually prepared to hande this error (mv(1) for example + applications are usually prepared to handle this error (mv(1) for example recursively copies the directory tree). This is the default behavior. 2. If the "redirect_dir" feature is enabled, then the directory will be @@ -235,7 +235,7 @@ Mount options: Redirects are not created and not followed. - "redirect_dir=off": If "redirect_always_follow" is enabled in the kernel/module config, - this "off" traslates to "follow", otherwise it translates to "nofollow". + this "off" translates to "follow", otherwise it translates to "nofollow". When the NFS export feature is enabled, every copied up directory is indexed by the file handle of the lower inode and a file handle of the @@ -339,6 +339,18 @@ The specified lower directories will be stacked beginning from the rightmost one and going left. In the above example lower1 will be the top, lower2 the middle and lower3 the bottom layer. +Note: directory names containing colons can be provided as lower layer by +escaping the colons with a single backslash. For example: + + mount -t overlay overlay -olowerdir=/a\:lower\:\:dir /merged + +Since kernel version v6.5, directory names containing colons can also +be provided as lower layer using the fsconfig syscall from new mount api: + + fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir", "/a:lower::dir", 0); + +In the latter case, colons in lower layer directory names will be escaped +as an octal characters (\072) when displayed in /proc/self/mountinfo. Metadata only copy up --------------------- @@ -405,6 +417,53 @@ when a "metacopy" file in one of the lower layers above it, has a "redirect" to the absolute path of the "lower data" file in the "data-only" lower layer. +fs-verity support +---------------------- + +During metadata copy up of a lower file, if the source file has +fs-verity enabled and overlay verity support is enabled, then the +digest of the lower file is added to the "trusted.overlay.metacopy" +xattr. This is then used to verify the content of the lower file +each the time the metacopy file is opened. + +When a layer containing verity xattrs is used, it means that any such +metacopy file in the upper layer is guaranteed to match the content +that was in the lower at the time of the copy-up. If at any time +(during a mount, after a remount, etc) such a file in the lower is +replaced or modified in any way, access to the corresponding file in +overlayfs will result in EIO errors (either on open, due to overlayfs +digest check, or from a later read due to fs-verity) and a detailed +error is printed to the kernel logs. For more details of how fs-verity +file access works, see :ref:`Documentation/filesystems/fsverity.rst +<accessing_verity_files>`. + +Verity can be used as a general robustness check to detect accidental +changes in the overlayfs directories in use. But, with additional care +it can also give more powerful guarantees. For example, if the upper +layer is fully trusted (by using dm-verity or something similar), then +an untrusted lower layer can be used to supply validated file content +for all metacopy files. If additionally the untrusted lower +directories are specified as "Data-only", then they can only supply +such file content, and the entire mount can be trusted to match the +upper layer. + +This feature is controlled by the "verity" mount option, which +supports these values: + +- "off": + The metacopy digest is never generated or used. This is the + default if verity option is not specified. +- "on": + Whenever a metacopy files specifies an expected digest, the + corresponding data file must match the specified digest. When + generating a metacopy file the verity digest will be set in it + based on the source file (if it has one). +- "require": + Same as "on", but additionally all metacopy files must specify a + digest (or EIO is returned on open). This means metadata copy up + will only be used if the data file has fs-verity enabled, + otherwise a full copy-up is used. + Sharing and copying layers -------------------------- @@ -610,6 +669,31 @@ can be useful in case the underlying disk is copied and the UUID of this copy is changed. This is only applicable if all lower/upper/work directories are on the same filesystem, otherwise it will fallback to normal behaviour. + +UUID and fsid +------------- + +The UUID of overlayfs instance itself and the fsid reported by statfs(2) are +controlled by the "uuid" mount option, which supports these values: + +- "null": + UUID of overlayfs is null. fsid is taken from upper most filesystem. +- "off": + UUID of overlayfs is null. fsid is taken from upper most filesystem. + UUID of underlying layers is ignored. +- "on": + UUID of overlayfs is generated and used to report a unique fsid. + UUID is stored in xattr "trusted.overlay.uuid", making overlayfs fsid + unique and persistent. This option requires an overlayfs with upper + filesystem that supports xattrs. +- "auto": (default) + UUID is taken from xattr "trusted.overlay.uuid" if it exists. + Upgrade to "uuid=on" on first time mount of new overlay filesystem that + meets the prerequites. + Downgrade to "uuid=null" for existing overlay filesystems that were never + mounted with "uuid=on". + + Volatile mount -------------- diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst index d2d684ae7798..d69f59700a23 100644 --- a/Documentation/filesystems/porting.rst +++ b/Documentation/filesystems/porting.rst @@ -177,7 +177,7 @@ settles down a bit. **mandatory** s_export_op is now required for exporting a filesystem. -isofs, ext2, ext3, resierfs, fat +isofs, ext2, ext3, reiserfs, fat can be used as examples of very different filesystems. --- @@ -470,7 +470,7 @@ has been taken to VFS and filesystems need to provide a non-NULL **mandatory** If you implement your own ->llseek() you must handle SEEK_HOLE and -SEEK_DATA. You can hanle this by returning -EINVAL, but it would be nicer to +SEEK_DATA. You can handle this by returning -EINVAL, but it would be nicer to support it in some way. The generic handler assumes that the entire file is data and there is a virtual hole at the end of the file. So if the provided offset is less than i_size and SEEK_DATA is specified, return the same offset. @@ -517,7 +517,7 @@ The witch is dead! Well, 2/3 of it, anyway. ->d_revalidate() and ->create() doesn't take ``struct nameidata *``; unlike the previous two, it gets "is it an O_EXCL or equivalent?" boolean argument. Note that -local filesystems can ignore tha argument - they are guaranteed that the +local filesystems can ignore this argument - they are guaranteed that the object doesn't exist. It's remote/distributed ones that might care... --- @@ -537,7 +537,7 @@ vfs_readdir() is gone; switch to iterate_dir() instead **mandatory** -->readdir() is gone now; switch to ->iterate() +->readdir() is gone now; switch to ->iterate_shared() **mandatory** @@ -693,24 +693,19 @@ parallel now. --- -**recommended** +**mandatory** -->iterate_shared() is added; it's a parallel variant of ->iterate(). +->iterate_shared() is added. Exclusion on struct file level is still provided (as well as that between it and lseek on the same struct file), but if your directory has been opened several times, you can get these called in parallel. Exclusion between that method and all directory-modifying ones is still provided, of course. -Often enough ->iterate() can serve as ->iterate_shared() without any -changes - it is a read-only operation, after all. If you have any -per-inode or per-dentry in-core data structures modified by ->iterate(), -you might need something to serialize the access to them. If you -do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for -that; look for in-tree examples. - -Old method is only used if the new one is absent; eventually it will -be removed. Switch while you still can; the old one won't stay. +If you have any per-inode or per-dentry in-core data structures modified +by ->iterate_shared(), you might need something to serialize the access +to them. If you do dcache pre-seeding, you'll need to switch to +d_alloc_parallel() for that; look for in-tree examples. --- @@ -930,9 +925,9 @@ should be done by looking at FMODE_LSEEK in file->f_mode. filldir_t (readdir callbacks) calling conventions have changed. Instead of returning 0 or -E... it returns bool now. false means "no more" (as -E... used to) and true - "keep going" (as 0 in old calling conventions). Rationale: -callers never looked at specific -E... values anyway. ->iterate() and -->iterate_shared() instance require no changes at all, all filldir_t ones in -the tree converted. +callers never looked at specific -E... values anyway. -> iterate_shared() +instances require no changes at all, all filldir_t ones in the tree +converted. --- @@ -943,3 +938,117 @@ file pointer instead of struct dentry pointer. d_tmpfile() is similarly changed to simplify callers. The passed file is in a non-open state and on success must be opened before returning (e.g. by calling finish_open_simple()). + +--- + +**mandatory** + +Calling convention for ->huge_fault has changed. It now takes a page +order instead of an enum page_entry_size, and it may be called without the +mmap_lock held. All in-tree users have been audited and do not seem to +depend on the mmap_lock being held, but out of tree users should verify +for themselves. If they do need it, they can return VM_FAULT_RETRY to +be called with the mmap_lock held. + +--- + +**mandatory** + +The order of opening block devices and matching or creating superblocks has +changed. + +The old logic opened block devices first and then tried to find a +suitable superblock to reuse based on the block device pointer. + +The new logic tries to find a suitable superblock first based on the device +number, and opening the block device afterwards. + +Since opening block devices cannot happen under s_umount because of lock +ordering requirements s_umount is now dropped while opening block devices and +reacquired before calling fill_super(). + +In the old logic concurrent mounters would find the superblock on the list of +superblocks for the filesystem type. Since the first opener of the block device +would hold s_umount they would wait until the superblock became either born or +was discarded due to initialization failure. + +Since the new logic drops s_umount concurrent mounters could grab s_umount and +would spin. Instead they are now made to wait using an explicit wait-wake +mechanism without having to hold s_umount. + +--- + +**mandatory** + +The holder of a block device is now the superblock. + +The holder of a block device used to be the file_system_type which wasn't +particularly useful. It wasn't possible to go from block device to owning +superblock without matching on the device pointer stored in the superblock. +This mechanism would only work for a single device so the block layer couldn't +find the owning superblock of any additional devices. + +In the old mechanism reusing or creating a superblock for a racing mount(2) and +umount(2) relied on the file_system_type as the holder. This was severly +underdocumented however: + +(1) Any concurrent mounter that managed to grab an active reference on an + existing superblock was made to wait until the superblock either became + ready or until the superblock was removed from the list of superblocks of + the filesystem type. If the superblock is ready the caller would simple + reuse it. + +(2) If the mounter came after deactivate_locked_super() but before + the superblock had been removed from the list of superblocks of the + filesystem type the mounter would wait until the superblock was shutdown, + reuse the block device and allocate a new superblock. + +(3) If the mounter came after deactivate_locked_super() and after + the superblock had been removed from the list of superblocks of the + filesystem type the mounter would reuse the block device and allocate a new + superblock (the bd_holder point may still be set to the filesystem type). + +Because the holder of the block device was the file_system_type any concurrent +mounter could open the block devices of any superblock of the same +file_system_type without risking seeing EBUSY because the block device was +still in use by another superblock. + +Making the superblock the owner of the block device changes this as the holder +is now a unique superblock and thus block devices associated with it cannot be +reused by concurrent mounters. So a concurrent mounter in (2) could suddenly +see EBUSY when trying to open a block device whose holder was a different +superblock. + +The new logic thus waits until the superblock and the devices are shutdown in +->kill_sb(). Removal of the superblock from the list of superblocks of the +filesystem type is now moved to a later point when the devices are closed: + +(1) Any concurrent mounter managing to grab an active reference on an existing + superblock is made to wait until the superblock is either ready or until + the superblock and all devices are shutdown in ->kill_sb(). If the + superblock is ready the caller will simply reuse it. + +(2) If the mounter comes after deactivate_locked_super() but before + the superblock has been removed from the list of superblocks of the + filesystem type the mounter is made to wait until the superblock and the + devices are shut down in ->kill_sb() and the superblock is removed from the + list of superblocks of the filesystem type. The mounter will allocate a new + superblock and grab ownership of the block device (the bd_holder pointer of + the block device will be set to the newly allocated superblock). + +(3) This case is now collapsed into (2) as the superblock is left on the list + of superblocks of the filesystem type until all devices are shutdown in + ->kill_sb(). In other words, if the superblock isn't on the list of + superblock of the filesystem type anymore then it has given up ownership of + all associated block devices (the bd_holder pointer is NULL). + +As this is a VFS level change it has no practical consequences for filesystems +other than that all of them must use one of the provided kill_litter_super(), +kill_anon_super(), or kill_block_super() helpers. + +--- + +**mandatory** + +Lock ordering has been changed so that s_umount ranks above open_mutex again. +All places where s_umount was taken under open_mutex have been fixed up. diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 7897a7dafcbc..49ef12df631b 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -461,6 +461,7 @@ Memory Area, or VMA) there is a series of lines such as the following:: Private_Dirty: 0 kB Referenced: 892 kB Anonymous: 0 kB + KSM: 0 kB LazyFree: 0 kB AnonHugePages: 0 kB ShmemPmdMapped: 0 kB @@ -501,18 +502,21 @@ accessed. a mapping associated with a file may contain anonymous pages: when MAP_PRIVATE and a page is modified, the file page is replaced by a private anonymous copy. +"KSM" reports how many of the pages are KSM pages. Note that KSM-placed zeropages +are not included, only actual KSM pages. + "LazyFree" shows the amount of memory which is marked by madvise(MADV_FREE). The memory isn't freed immediately with madvise(). It's freed in memory pressure if the memory is clean. Please note that the printed value might be lower than the real value due to optimizations used in the current implementation. If this is not desirable please file a bug report. -"AnonHugePages" shows the ammount of memory backed by transparent hugepage. +"AnonHugePages" shows the amount of memory backed by transparent hugepage. -"ShmemPmdMapped" shows the ammount of shared (shmem/tmpfs) memory backed by +"ShmemPmdMapped" shows the amount of shared (shmem/tmpfs) memory backed by huge pages. -"Shared_Hugetlb" and "Private_Hugetlb" show the ammounts of memory backed by +"Shared_Hugetlb" and "Private_Hugetlb" show the amounts of memory backed by hugetlbfs page which is *not* counted in "RSS" or "PSS" field for historical reasons. And these are not included in {Shared,Private}_{Clean,Dirty} field. @@ -561,11 +565,12 @@ encoded manner. The codes are the following: mm mixed map area hg huge page advise flag nh no huge page advise flag - mg mergable advise flag + mg mergeable advise flag bt arm64 BTI guarded page mt arm64 MTE allocation tags are enabled um userfaultfd missing tracking uw userfaultfd wr-protect tracking + ss shadow stack page == ======================================= Note that there is no guarantee that every flag and associated mnemonic will @@ -684,9 +689,15 @@ files are there, and which are missing. File Content ============ =============================================================== apm Advanced power management info + bootconfig Kernel command line obtained from boot config, + and, if there were kernel parameters from the + boot loader, a "# Parameters from bootloader:" + line followed by a line containing those + parameters prefixed by "# ". (5.5) buddyinfo Kernel memory allocator information (see text) (2.5) bus Directory containing bus specific information - cmdline Kernel command line + cmdline Kernel command line, both from bootloader and embedded + in the kernel image cpuinfo Info about the CPU devices Available devices (block and character) dma Used DMS channels @@ -1081,7 +1092,7 @@ Writeback AnonPages Non-file backed pages mapped into userspace page tables Mapped - files which have been mmaped, such as libraries + files which have been mmapped, such as libraries Shmem Total memory used by shared memory (shmem) and tmpfs KReclaimable @@ -2229,7 +2240,7 @@ are not related to tasks. Chapter 5: Filesystem behavior ============================== -Originally, before the advent of pid namepsace, procfs was a global file +Originally, before the advent of pid namespace, procfs was a global file system. It means that there was only one procfs instance in the system. When pid namespace was added, a separate procfs instance was mounted in diff --git a/Documentation/filesystems/qnx6.rst b/Documentation/filesystems/qnx6.rst index 523b798f04e7..560f3d470422 100644 --- a/Documentation/filesystems/qnx6.rst +++ b/Documentation/filesystems/qnx6.rst @@ -135,7 +135,7 @@ inode. Character and block special devices do not exist in QNX as those files are handled by the QNX kernel/drivers and created in /dev independent of the -underlaying filesystem. +underlying filesystem. Long filenames -------------- diff --git a/Documentation/filesystems/seq_file.rst b/Documentation/filesystems/seq_file.rst index a6726082a7c2..1e1713d00010 100644 --- a/Documentation/filesystems/seq_file.rst +++ b/Documentation/filesystems/seq_file.rst @@ -130,7 +130,7 @@ called SEQ_START_TOKEN; it can be used if you wish to instruct your show() function (described below) to print a header at the top of the output. SEQ_START_TOKEN should only be used if the offset is zero, however. SEQ_START_TOKEN has no special meaning to the core seq_file -code. It is provided as a convenience for a start() funciton to +code. It is provided as a convenience for a start() function to communicate with the next() and show() functions. The next function to implement is called, amazingly, next(); its job is to @@ -217,7 +217,7 @@ between the calls to start() and stop(), so holding a lock during that time is a reasonable thing to do. The seq_file code will also avoid taking any other locks while the iterator is active. -The iterater value returned by start() or next() is guaranteed to be +The iterator value returned by start() or next() is guaranteed to be passed to a subsequent next() or stop() call. This allows resources such as locks that were taken to be reliably released. There is *no* guarantee that the iterator will be passed to show(), though in practice diff --git a/Documentation/filesystems/tmpfs.rst b/Documentation/filesystems/tmpfs.rst index f18f46be5c0c..56a26c843dbe 100644 --- a/Documentation/filesystems/tmpfs.rst +++ b/Documentation/filesystems/tmpfs.rst @@ -21,8 +21,8 @@ explained further below, some of which can be reconfigured dynamically on the fly using a remount ('mount -o remount ...') of the filesystem. A tmpfs filesystem can be resized but it cannot be resized to a size below its current usage. tmpfs also supports POSIX ACLs, and extended attributes for the -trusted.* and security.* namespaces. ramfs does not use swap and you cannot -modify any parameter for a ramfs filesystem. The size limit of a ramfs +trusted.*, security.* and user.* namespaces. ramfs does not use swap and you +cannot modify any parameter for a ramfs filesystem. The size limit of a ramfs filesystem is how much memory you have available, and so care must be taken if used so to not run out of memory. @@ -84,8 +84,6 @@ nr_inodes The maximum number of inodes for this instance. The default is half of the number of your physical RAM pages, or (on a machine with highmem) the number of lowmem RAM pages, whichever is the lower. -noswap Disables swap. Remounts must respect the original settings. - By default swap is enabled. ========= ============================================================ These parameters accept a suffix k, m or g for kilo, mega and giga and @@ -99,36 +97,65 @@ mount with such options, since it allows any user with write access to use up all the memory on the machine; but enhances the scalability of that instance in a system with many CPUs making intensive use of it. +If nr_inodes is not 0, that limited space for inodes is also used up by +extended attributes: "df -i"'s IUsed and IUse% increase, IFree decreases. + +tmpfs blocks may be swapped out, when there is a shortage of memory. +tmpfs has a mount option to disable its use of swap: + +====== =========================================================== +noswap Disables swap. Remounts must respect the original settings. + By default swap is enabled. +====== =========================================================== + tmpfs also supports Transparent Huge Pages which requires a kernel configured with CONFIG_TRANSPARENT_HUGEPAGE and with huge supported for your system (has_transparent_hugepage(), which is architecture specific). The mount options for this are: -====== ============================================================ -huge=0 never: disables huge pages for the mount -huge=1 always: enables huge pages for the mount -huge=2 within_size: only allocate huge pages if the page will be - fully within i_size, also respect fadvise()/madvise() hints. -huge=3 advise: only allocate huge pages if requested with - fadvise()/madvise() -====== ============================================================ - -There is a sysfs file which you can also use to control system wide THP -configuration for all tmpfs mounts, the file is: - -/sys/kernel/mm/transparent_hugepage/shmem_enabled - -This sysfs file is placed on top of THP sysfs directory and so is registered -by THP code. It is however only used to control all tmpfs mounts with one -single knob. Since it controls all tmpfs mounts it should only be used either -for emergency or testing purposes. The values you can set for shmem_enabled are: - -== ============================================================ --1 deny: disables huge on shm_mnt and all mounts, for - emergency use --2 force: enables huge on shm_mnt and all mounts, w/o needing - option, for testing -== ============================================================ +================ ============================================================== +huge=never Do not allocate huge pages. This is the default. +huge=always Attempt to allocate huge page every time a new page is needed. +huge=within_size Only allocate huge page if it will be fully within i_size. + Also respect madvise(2) hints. +huge=advise Only allocate huge page if requested with madvise(2). +================ ============================================================== + +See also Documentation/admin-guide/mm/transhuge.rst, which describes the +sysfs file /sys/kernel/mm/transparent_hugepage/shmem_enabled: which can +be used to deny huge pages on all tmpfs mounts in an emergency, or to +force huge pages on all tmpfs mounts for testing. + +tmpfs also supports quota with the following mount options + +======================== ================================================= +quota User and group quota accounting and enforcement + is enabled on the mount. Tmpfs is using hidden + system quota files that are initialized on mount. +usrquota User quota accounting and enforcement is enabled + on the mount. +grpquota Group quota accounting and enforcement is enabled + on the mount. +usrquota_block_hardlimit Set global user quota block hard limit. +usrquota_inode_hardlimit Set global user quota inode hard limit. +grpquota_block_hardlimit Set global group quota block hard limit. +grpquota_inode_hardlimit Set global group quota inode hard limit. +======================== ================================================= + +None of the quota related mount options can be set or changed on remount. + +Quota limit parameters accept a suffix k, m or g for kilo, mega and giga +and can't be changed on remount. Default global quota limits are taking +effect for any and all user/group/project except root the first time the +quota entry for user/group/project id is being accessed - typically the +first time an inode with a particular id ownership is being created after +the mount. In other words, instead of the limits being initialized to zero, +they are initialized with the particular value provided with these mount +options. The limits can be changed for any user/group id at any time as they +normally can be. + +Note that tmpfs quotas do not support user namespaces so no uid/gid +translation is done if quotas are enabled inside user namespaces. tmpfs has a mount option to set the NUMA memory allocation policy for all files in that instance (if CONFIG_NUMA is enabled) - which can be diff --git a/Documentation/filesystems/ubifs-authentication.rst b/Documentation/filesystems/ubifs-authentication.rst index 5210aed2afbc..3d85ee88719a 100644 --- a/Documentation/filesystems/ubifs-authentication.rst +++ b/Documentation/filesystems/ubifs-authentication.rst @@ -130,7 +130,7 @@ marked as dirty are written to the flash to update the persisted index. Journal ~~~~~~~ -To avoid wearing out the flash, the index is only persisted (*commited*) when +To avoid wearing out the flash, the index is only persisted (*committed*) when certain conditions are met (eg. ``fsync(2)``). The journal is used to record any changes (in form of inode nodes, data nodes etc.) between commits of the index. During mount, the journal is read from the flash and replayed diff --git a/Documentation/filesystems/vfat.rst b/Documentation/filesystems/vfat.rst index 760a4d83fdf9..b289c4449cd0 100644 --- a/Documentation/filesystems/vfat.rst +++ b/Documentation/filesystems/vfat.rst @@ -50,7 +50,7 @@ VFAT MOUNT OPTIONS Normally utime(2) checks current process is owner of the file, or it has CAP_FOWNER capability. But FAT filesystem doesn't have uid/gid on disk, so normal - check is too unflexible. With this option you can + check is too inflexible. With this option you can relax it. **codepage=###** diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index cb2a97e49872..99acc2e98673 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -260,9 +260,11 @@ filesystem. The following members are defined: void (*evict_inode) (struct inode *); void (*put_super) (struct super_block *); int (*sync_fs)(struct super_block *sb, int wait); - int (*freeze_super) (struct super_block *); + int (*freeze_super) (struct super_block *sb, + enum freeze_holder who); int (*freeze_fs) (struct super_block *); - int (*thaw_super) (struct super_block *); + int (*thaw_super) (struct super_block *sb, + enum freeze_wholder who); int (*unfreeze_fs) (struct super_block *); int (*statfs) (struct dentry *, struct kstatfs *); int (*remount_fs) (struct super_block *, int *, char *); @@ -515,6 +517,7 @@ As of kernel 2.6.22, the following members are defined: int (*fileattr_set)(struct mnt_idmap *idmap, struct dentry *dentry, struct fileattr *fa); int (*fileattr_get)(struct dentry *dentry, struct fileattr *fa); + struct offset_ctx *(*get_offset_ctx)(struct inode *inode); }; Again, all methods are called without any locks being held, unless @@ -675,7 +678,10 @@ otherwise noted. called on ioctl(FS_IOC_SETFLAGS) and ioctl(FS_IOC_FSSETXATTR) to change miscellaneous file flags and attributes. Callers hold i_rwsem exclusive. If unset, then fall back to f_op->ioctl(). - +``get_offset_ctx`` + called to get the offset context for a directory inode. A + filesystem must define this operation to use + simple_offset_dir_operations. The Address Space Object ======================== @@ -761,7 +767,7 @@ is an error during writeback, they expect that error to be reported when a file sync request is made. After an error has been reported on one request, subsequent requests on the same file descriptor should return 0, unless further writeback errors have occurred since the previous file -syncronization. +synchronization. Ideally, the kernel would report errors only on file descriptions on which writes were done that subsequently failed to be written back. The @@ -1074,7 +1080,6 @@ This describes how the VFS can manipulate an open file. As of kernel ssize_t (*read_iter) (struct kiocb *, struct iov_iter *); ssize_t (*write_iter) (struct kiocb *, struct iov_iter *); int (*iopoll)(struct kiocb *kiocb, bool spin); - int (*iterate) (struct file *, struct dir_context *); int (*iterate_shared) (struct file *, struct dir_context *); __poll_t (*poll) (struct file *, struct poll_table_struct *); long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); @@ -1126,12 +1131,8 @@ otherwise noted. ``iopoll`` called when aio wants to poll for completions on HIPRI iocbs -``iterate`` - called when the VFS needs to read the directory contents - ``iterate_shared`` - called when the VFS needs to read the directory contents when - filesystem supports concurrent dir iterators + called when the VFS needs to read the directory contents ``poll`` called by the VFS when a process wants to check if there is diff --git a/Documentation/filesystems/xfs-maintainer-entry-profile.rst b/Documentation/filesystems/xfs-maintainer-entry-profile.rst new file mode 100644 index 000000000000..32b6ac4ca9d6 --- /dev/null +++ b/Documentation/filesystems/xfs-maintainer-entry-profile.rst @@ -0,0 +1,194 @@ +XFS Maintainer Entry Profile +============================ + +Overview +-------- +XFS is a well known high-performance filesystem in the Linux kernel. +The aim of this project is to provide and maintain a robust and +performant filesystem. + +Patches are generally merged to the for-next branch of the appropriate +git repository. +After a testing period, the for-next branch is merged to the master +branch. + +Kernel code are merged to the xfs-linux tree[0]. +Userspace code are merged to the xfsprogs tree[1]. +Test cases are merged to the xfstests tree[2]. +Ondisk format documentation are merged to the xfs-documentation tree[3]. + +All patchsets involving XFS *must* be cc'd in their entirety to the mailing +list linux-xfs@vger.kernel.org. + +Roles +----- +There are eight key roles in the XFS project. +A person can take on multiple roles, and a role can be filled by +multiple people. +Anyone taking on a role is advised to check in with themselves and +others on a regular basis about burnout. + +- **Outside Contributor**: Anyone who sends a patch but is not involved + in the XFS project on a regular basis. + These folks are usually people who work on other filesystems or + elsewhere in the kernel community. + +- **Developer**: Someone who is familiar with the XFS codebase enough to + write new code, documentation, and tests. + + Developers can often be found in the IRC channel mentioned by the ``C:`` + entry in the kernel MAINTAINERS file. + +- **Senior Developer**: A developer who is very familiar with at least + some part of the XFS codebase and/or other subsystems in the kernel. + These people collectively decide the long term goals of the project + and nudge the community in that direction. + They should help prioritize development and review work for each release + cycle. + + Senior developers tend to be more active participants in the IRC channel. + +- **Reviewer**: Someone (most likely also a developer) who reads code + submissions to decide: + + 0. Is the idea behind the contribution sound? + 1. Does the idea fit the goals of the project? + 2. Is the contribution designed correctly? + 3. Is the contribution polished? + 4. Can the contribution be tested effectively? + + Reviewers should identify themselves with an ``R:`` entry in the kernel + and fstests MAINTAINERS files. + +- **Testing Lead**: This person is responsible for setting the test + coverage goals of the project, negotiating with developers to decide + on new tests for new features, and making sure that developers and + release managers execute on the testing. + + The testing lead should identify themselves with an ``M:`` entry in + the XFS section of the fstests MAINTAINERS file. + +- **Bug Triager**: Someone who examines incoming bug reports in just + enough detail to identify the person to whom the report should be + forwarded. + + The bug triagers should identify themselves with a ``B:`` entry in + the kernel MAINTAINERS file. + +- **Release Manager**: This person merges reviewed patchsets into an + integration branch, tests the result locally, pushes the branch to a + public git repository, and sends pull requests further upstream. + The release manager is not expected to work on new feature patchsets. + If a developer and a reviewer fail to reach a resolution on some point, + the release manager must have the ability to intervene to try to drive a + resolution. + + The release manager should identify themselves with an ``M:`` entry in + the kernel MAINTAINERS file. + +- **Community Manager**: This person calls and moderates meetings of as many + XFS participants as they can get when mailing list discussions prove + insufficient for collective decisionmaking. + They may also serve as liaison between managers of the organizations + sponsoring work on any part of XFS. + +- **LTS Maintainer**: Someone who backports and tests bug fixes from + uptream to the LTS kernels. + There tend to be six separate LTS trees at any given time. + + The maintainer for a given LTS release should identify themselves with an + ``M:`` entry in the MAINTAINERS file for that LTS tree. + Unmaintained LTS kernels should be marked with status ``S: Orphan`` in that + same file. + +Submission Checklist Addendum +----------------------------- +Please follow these additional rules when submitting to XFS: + +- Patches affecting only the filesystem itself should be based against + the latest -rc or the for-next branch. + These patches will be merged back to the for-next branch. + +- Authors of patches touching other subsystems need to coordinate with + the maintainers of XFS and the relevant subsystems to decide how to + proceed with a merge. + +- Any patchset changing XFS should be cc'd in its entirety to linux-xfs. + Do not send partial patchsets; that makes analysis of the broader + context of the changes unnecessarily difficult. + +- Anyone making kernel changes that have corresponding changes to the + userspace utilities should send the userspace changes as separate + patchsets immediately after the kernel patchsets. + +- Authors of bug fix patches are expected to use fstests[2] to perform + an A/B test of the patch to determine that there are no regressions. + When possible, a new regression test case should be written for + fstests. + +- Authors of new feature patchsets must ensure that fstests will have + appropriate functional and input corner-case test cases for the new + feature. + +- When implementing a new feature, it is strongly suggested that the + developers write a design document to answer the following questions: + + * **What** problem is this trying to solve? + + * **Who** will benefit from this solution, and **where** will they + access it? + + * **How** will this new feature work? This should touch on major data + structures and algorithms supporting the solution at a higher level + than code comments. + + * **What** userspace interfaces are necessary to build off of the new + features? + + * **How** will this work be tested to ensure that it solves the + problems laid out in the design document without causing new + problems? + + The design document should be committed in the kernel documentation + directory. + It may be omitted if the feature is already well known to the + community. + +- Patchsets for the new tests should be submitted as separate patchsets + immediately after the kernel and userspace code patchsets. + +- Changes to the on-disk format of XFS must be described in the ondisk + format document[3] and submitted as a patchset after the fstests + patchsets. + +- Patchsets implementing bug fixes and further code cleanups should put + the bug fixes at the beginning of the series to ease backporting. + +Key Release Cycle Dates +----------------------- +Bug fixes may be sent at any time, though the release manager may decide to +defer a patch when the next merge window is close. + +Code submissions targeting the next merge window should be sent between +-rc1 and -rc6. +This gives the community time to review the changes, to suggest other changes, +and for the author to retest those changes. + +Code submissions also requiring changes to fs/iomap and targeting the +next merge window should be sent between -rc1 and -rc4. +This allows the broader kernel community adequate time to test the +infrastructure changes. + +Review Cadence +-------------- +In general, please wait at least one week before pinging for feedback. +To find reviewers, either consult the MAINTAINERS file, or ask +developers that have Reviewed-by tags for XFS changes to take a look and +offer their opinion. + +References +---------- +| [0] https://git.kernel.org/pub/scm/fs/xfs/xfs-linux.git/ +| [1] https://git.kernel.org/pub/scm/fs/xfs/xfsprogs-dev.git/ +| [2] https://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git/ +| [3] https://git.kernel.org/pub/scm/fs/xfs/xfs-documentation.git/ diff --git a/Documentation/filesystems/xfs-online-fsck-design.rst b/Documentation/filesystems/xfs-online-fsck-design.rst index 791ab264b77e..a0678101a7d0 100644 --- a/Documentation/filesystems/xfs-online-fsck-design.rst +++ b/Documentation/filesystems/xfs-online-fsck-design.rst @@ -293,7 +293,7 @@ The seven phases are as follows: Before starting repairs, the summary counters are checked and any necessary repairs are performed so that subsequent repairs will not fail the resource reservation step due to wildly incorrect summary counters. - Unsuccesful repairs are requeued as long as forward progress on repairs is + Unsuccessful repairs are requeued as long as forward progress on repairs is made somewhere in the filesystem. Free space in the filesystem is trimmed at the end of phase 4 if the filesystem is clean. @@ -542,7 +542,7 @@ ondisk structure. Inspiration for quota and file link count repair strategies were drawn from sections 2.12 ("Online Index Operations") through 2.14 ("Incremental View -Maintenace") of G. Graefe, `"Concurrent Queries and Updates in Summary Views +Maintenance") of G. Graefe, `"Concurrent Queries and Updates in Summary Views and Their Indexes" <http://www.odbms.org/wp-content/uploads/2014/06/Increment-locks.pdf>`_, 2011. @@ -605,7 +605,7 @@ functionality. The cron job does not have this protection. - **Fuzz Kiddiez**: There are many people now who seem to think that running - automated fuzz testing of ondisk artifacts to find mischevious behavior and + automated fuzz testing of ondisk artifacts to find mischievous behavior and spraying exploit code onto the public mailing list for instant zero-day disclosure is somehow of some social benefit. In the view of this author, the benefit is realized only when the fuzz @@ -1351,7 +1351,7 @@ If the leaf information exceeds a single filesystem block, a dabtree (also rooted at block 0) is created to map hashes of the attribute names to leaf blocks in the attr fork. -Checking an extended attribute structure is not so straightfoward due to the +Checking an extended attribute structure is not so straightforward due to the lack of separation between attr blocks and index blocks. Scrub must read each block mapped by the attr fork and ignore the non-leaf blocks: @@ -1401,7 +1401,7 @@ If the free space has been separated and the second partition grows again beyond one block, then a dabtree is used to map hashes of dirent names to directory data blocks. -Checking a directory is pretty straightfoward: +Checking a directory is pretty straightforward: 1. Walk the dabtree in the second partition (if present) to ensure that there are no irregularities in the blocks or dabtree mappings that do not point to @@ -1524,7 +1524,7 @@ Only online fsck has this requirement of total consistency of AG metadata, and should be relatively rare as compared to filesystem change operations. Online fsck coordinates with transaction chains as follows: -* For each AG, maintain a count of intent items targetting that AG. +* For each AG, maintain a count of intent items targeting that AG. The count should be bumped whenever a new item is added to the chain. The count should be dropped when the filesystem has locked the AG header buffers and finished the work. @@ -1585,7 +1585,7 @@ The transaction sequence looks like this: 2. The second transaction contains a physical update to the free space btrees of AG 3 to release the former BMBT block and a second physical update to the free space btrees of AG 7 to release the unmapped file space. - Observe that the the physical updates are resequenced in the correct order + Observe that the physical updates are resequenced in the correct order when possible. Attached to the transaction is a an extent free done (EFD) log item. The EFD contains a pointer to the EFI logged in transaction #1 so that log @@ -2102,7 +2102,7 @@ quicksort and a heapsort subalgorithm in the spirit of kernel. To sort records in a reasonably short amount of time, ``xfarray`` takes advantage of the binary subpartitioning offered by quicksort, but it also uses -heapsort to hedge aginst performance collapse if the chosen quicksort pivots +heapsort to hedge against performance collapse if the chosen quicksort pivots are poor. Both algorithms are (in general) O(n * lg(n)), but there is a wide performance gulf between the two implementations. @@ -2566,8 +2566,8 @@ old metadata blocks: The transaction rolling in steps 2c and 3 represent a weakness in the repair algorithm, because a log flush and a crash before the end of the reap step can result in space leaking. -Online repair functions minimize the chances of this occuring by using very -large transactions, which each can accomodate many thousands of block freeing +Online repair functions minimize the chances of this occurring by using very +large transactions, which each can accommodate many thousands of block freeing instructions. Repair moves on to reaping the old blocks, which will be presented in a subsequent :ref:`section<reaping>` after a few case studies of bulk loading. @@ -5090,7 +5090,7 @@ This scan after validation of all filesystem metadata (except for the summary counters) as phase 6. The scan starts by calling ``FS_IOC_GETFSMAP`` to scan the filesystem space map to find areas that are allocated to file data fork extents. -Gaps betweeen data fork extents that are smaller than 64k are treated as if +Gaps between data fork extents that are smaller than 64k are treated as if they were data fork extents to reduce the command setup overhead. When the space map scan accumulates a region larger than 32MB, a media verification request is sent to the disk as a directio read of the raw block diff --git a/Documentation/filesystems/zonefs.rst b/Documentation/filesystems/zonefs.rst index 394b9f15dce0..c22124c2213d 100644 --- a/Documentation/filesystems/zonefs.rst +++ b/Documentation/filesystems/zonefs.rst @@ -378,7 +378,7 @@ The attributes defined are as follows. sequential zone files. Failure to do so can result in write errors. * **max_active_seq_files**: This attribute reports the maximum number of sequential zone files that are in an active state, that is, sequential zone - files that are partially writen (not empty nor full) or that have a zone that + files that are partially written (not empty nor full) or that have a zone that is explicitly open (which happens only if the *explicit-open* mount option is used). This number is always equal to the maximum number of active zones that the device supports. A value of 0 means that the mounted device has no limit diff --git a/Documentation/firmware-guide/acpi/chromeos-acpi-device.rst b/Documentation/firmware-guide/acpi/chromeos-acpi-device.rst index f37fc90ce340..89419e116413 100644 --- a/Documentation/firmware-guide/acpi/chromeos-acpi-device.rst +++ b/Documentation/firmware-guide/acpi/chromeos-acpi-device.rst @@ -5,9 +5,8 @@ Chrome OS ACPI Device ===================== Hardware functionality specific to Chrome OS is exposed through a Chrome OS ACPI device. -The plug and play ID of a Chrome OS ACPI device is GGL0001. GGL is a valid PNP ID of Google. -PNP ID can be used with the ACPI devices according to the guidelines. The following ACPI -objects are supported: +The plug and play ID of a Chrome OS ACPI device is GGL0001 and the hardware ID is +GOOG0016. The following ACPI objects are supported: .. flat-table:: Supported ACPI Objects :widths: 1 2 diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst index 56d9913a3370..d79f69390991 100644 --- a/Documentation/firmware-guide/acpi/enumeration.rst +++ b/Documentation/firmware-guide/acpi/enumeration.rst @@ -64,6 +64,49 @@ If the driver needs to perform more complex initialization like getting and configuring GPIOs it can get its ACPI handle and extract this information from ACPI tables. +ACPI device objects +=================== + +Generally speaking, there are two categories of devices in a system in which +ACPI is used as an interface between the platform firmware and the OS: Devices +that can be discovered and enumerated natively, through a protocol defined for +the specific bus that they are on (for example, configuration space in PCI), +without the platform firmware assistance, and devices that need to be described +by the platform firmware so that they can be discovered. Still, for any device +known to the platform firmware, regardless of which category it falls into, +there can be a corresponding ACPI device object in the ACPI Namespace in which +case the Linux kernel will create a struct acpi_device object based on it for +that device. + +Those struct acpi_device objects are never used for binding drivers to natively +discoverable devices, because they are represented by other types of device +objects (for example, struct pci_dev for PCI devices) that are bound to by +device drivers (the corresponding struct acpi_device object is then used as +an additional source of information on the configuration of the given device). +Moreover, the core ACPI device enumeration code creates struct platform_device +objects for the majority of devices that are discovered and enumerated with the +help of the platform firmware and those platform device objects can be bound to +by platform drivers in direct analogy with the natively enumerable devices +case. Therefore it is logically inconsistent and so generally invalid to bind +drivers to struct acpi_device objects, including drivers for devices that are +discovered with the help of the platform firmware. + +Historically, ACPI drivers that bound directly to struct acpi_device objects +were implemented for some devices enumerated with the help of the platform +firmware, but this is not recommended for any new drivers. As explained above, +platform device objects are created for those devices as a rule (with a few +exceptions that are not relevant here) and so platform drivers should be used +for handling them, even though the corresponding ACPI device objects are the +only source of device configuration information in that case. + +For every device having a corresponding struct acpi_device object, the pointer +to it is returned by the ACPI_COMPANION() macro, so it is always possible to +get to the device configuration information stored in the ACPI device object +this way. Accordingly, struct acpi_device can be regarded as a part of the +interface between the kernel and the ACPI Namespace, whereas device objects of +other types (for example, struct pci_dev or struct platform_device) are used +for interacting with the rest of the system. + DMA support =========== diff --git a/Documentation/firmware-guide/acpi/osi.rst b/Documentation/firmware-guide/acpi/osi.rst index 784850adfcb6..868a0a40bb76 100644 --- a/Documentation/firmware-guide/acpi/osi.rst +++ b/Documentation/firmware-guide/acpi/osi.rst @@ -55,7 +55,7 @@ quirk, a bug, or a bug-fix. However this was discovered to be abused by other BIOS vendors to change completely unrelated code on completely unrelated systems. This prompted -an evaluation of all of it's uses. This uncovered that they aren't needed +an evaluation of all of its uses. This uncovered that they aren't needed for any of the original reasons. As such, the kernel will not respond to any custom Linux-* strings by default. diff --git a/Documentation/gpu/amdgpu/display/mpo-overview.rst b/Documentation/gpu/amdgpu/display/mpo-overview.rst index 0499aa92d08d..59a4f54a3ac7 100644 --- a/Documentation/gpu/amdgpu/display/mpo-overview.rst +++ b/Documentation/gpu/amdgpu/display/mpo-overview.rst @@ -178,7 +178,7 @@ Multiple Display MPO AMDGPU supports display MPO when using multiple displays; however, this feature behavior heavily relies on the compositor implementation. Keep in mind that -usespace can define different policies. For example, some OSes can use MPO to +userspace can define different policies. For example, some OSes can use MPO to protect the plane that handles the video playback; notice that we don't have many limitations for a single display. Nonetheless, this manipulation can have many more restrictions for a multi-display scenario. The below example shows a diff --git a/Documentation/gpu/amdgpu/driver-misc.rst b/Documentation/gpu/amdgpu/driver-misc.rst index be131e963d87..e40e15f89fd3 100644 --- a/Documentation/gpu/amdgpu/driver-misc.rst +++ b/Documentation/gpu/amdgpu/driver-misc.rst @@ -11,27 +11,45 @@ via sysfs product_name ------------ -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_device.c +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_fru_eeprom.c :doc: product_name product_number -------------- -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_device.c - :doc: product_name +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_fru_eeprom.c + :doc: product_number serial_number ------------- -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_device.c +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_fru_eeprom.c :doc: serial_number +fru_id +------------- + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_fru_eeprom.c + :doc: fru_id + +manufacturer +------------- + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_fru_eeprom.c + :doc: manufacturer + unique_id --------- .. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c :doc: unique_id +board_info +---------- + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_device.c + :doc: board_info + Accelerated Processing Units (APU) Info --------------------------------------- diff --git a/Documentation/gpu/amdgpu/flashing.rst b/Documentation/gpu/amdgpu/flashing.rst new file mode 100644 index 000000000000..bd745c42a538 --- /dev/null +++ b/Documentation/gpu/amdgpu/flashing.rst @@ -0,0 +1,33 @@ +======================= + dGPU firmware flashing +======================= + +IFWI +---- +Flashing the dGPU integrated firmware image (IFWI) is supported by GPUs that +use the PSP to orchestrate the update (Navi3x or newer GPUs). +For supported GPUs, `amdgpu` will export a series of sysfs files that can be +used for the flash process. + +The IFWI flash process is: + +1. Ensure the IFWI image is intended for the dGPU on the system. +2. "Write" the IFWI image to the sysfs file `psp_vbflash`. This will stage the IFWI in memory. +3. "Read" from the `psp_vbflash` sysfs file to initiate the flash process. +4. Poll the `psp_vbflash_status` sysfs file to determine when the flash process completes. + +USB-C PD F/W +------------ +On GPUs that support flashing an updated USB-C PD firmware image, the process +is done using the `usbc_pd_fw` sysfs file. + +* Reading the file will provide the current firmware version. +* Writing the name of a firmware payload stored in `/lib/firmware/amdgpu` to the sysfs file will initiate the flash process. + +The firmware payload stored in `/lib/firmware/amdgpu` can be named any name +as long as it doesn't conflict with other existing binaries that are used by +`amdgpu`. + +sysfs files +----------- +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_psp.c diff --git a/Documentation/gpu/amdgpu/index.rst b/Documentation/gpu/amdgpu/index.rst index 03c2966cae79..912e699fd373 100644 --- a/Documentation/gpu/amdgpu/index.rst +++ b/Documentation/gpu/amdgpu/index.rst @@ -10,6 +10,7 @@ Next (GCN), Radeon DNA (RDNA), and Compute DNA (CDNA) architectures. module-parameters driver-core display/index + flashing xgmi ras thermal diff --git a/Documentation/gpu/amdgpu/thermal.rst b/Documentation/gpu/amdgpu/thermal.rst index 5e27e4eb3959..2f6166f81e6a 100644 --- a/Documentation/gpu/amdgpu/thermal.rst +++ b/Documentation/gpu/amdgpu/thermal.rst @@ -64,6 +64,36 @@ gpu_metrics .. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c :doc: gpu_metrics +fan_curve +--------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: fan_curve + +acoustic_limit_rpm_threshold +---------------------------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: acoustic_limit_rpm_threshold + +acoustic_target_rpm_threshold +----------------------------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: acoustic_target_rpm_threshold + +fan_target_temperature +---------------------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: fan_target_temperature + +fan_minimum_pwm +--------------- + +.. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c + :doc: fan_minimum_pwm + GFXOFF ====== diff --git a/Documentation/gpu/automated_testing.rst b/Documentation/gpu/automated_testing.rst new file mode 100644 index 000000000000..240e29d5ba68 --- /dev/null +++ b/Documentation/gpu/automated_testing.rst @@ -0,0 +1,160 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +========================================= +Automated testing of the DRM subsystem +========================================= + +Introduction +============ + +Making sure that changes to the core or drivers don't introduce regressions can +be very time-consuming when lots of different hardware configurations need to +be tested. Moreover, it isn't practical for each person interested in this +testing to have to acquire and maintain what can be a considerable amount of +hardware. + +Also, it is desirable for developers to check for regressions in their code by +themselves, instead of relying on the maintainers to find them and then +reporting back. + +There are facilities in gitlab.freedesktop.org to automatically test Mesa that +can be used as well for testing the DRM subsystem. This document explains how +people interested in testing it can use this shared infrastructure to save +quite some time and effort. + + +Relevant files +============== + +drivers/gpu/drm/ci/gitlab-ci.yml +-------------------------------- + +This is the root configuration file for GitLab CI. Among other less interesting +bits, it specifies the specific version of the scripts to be used. There are +some variables that can be modified to change the behavior of the pipeline: + +DRM_CI_PROJECT_PATH + Repository that contains the Mesa software infrastructure for CI + +DRM_CI_COMMIT_SHA + A particular revision to use from that repository + +UPSTREAM_REPO + URL to git repository containing the target branch + +TARGET_BRANCH + Branch to which this branch is to be merged into + +IGT_VERSION + Revision of igt-gpu-tools being used, from + https://gitlab.freedesktop.org/drm/igt-gpu-tools + +drivers/gpu/drm/ci/testlist.txt +------------------------------- + +IGT tests to be run on all drivers (unless mentioned in a driver's \*-skips.txt +file, see below). + +drivers/gpu/drm/ci/${DRIVER_NAME}-${HW_REVISION}-fails.txt +---------------------------------------------------------- + +Lists the known failures for a given driver on a specific hardware revision. + +drivers/gpu/drm/ci/${DRIVER_NAME}-${HW_REVISION}-flakes.txt +----------------------------------------------------------- + +Lists the tests that for a given driver on a specific hardware revision are +known to behave unreliably. These tests won't cause a job to fail regardless of +the result. They will still be run. + +Each new flake entry must be associated with a link to the email reporting the +bug to the author of the affected driver, the board name or Device Tree name of +the board, the first kernel version affected, and an approximation of the +failure rate. + +They should be provided under the following format:: + + # Bug Report: $LORE_OR_PATCHWORK_URL + # Board Name: broken-board.dtb + # Version: 6.6-rc1 + # Failure Rate: 100 + flaky-test + +drivers/gpu/drm/ci/${DRIVER_NAME}-${HW_REVISION}-skips.txt +----------------------------------------------------------- + +Lists the tests that won't be run for a given driver on a specific hardware +revision. These are usually tests that interfere with the running of the test +list due to hanging the machine, causing OOM, taking too long, etc. + + +How to enable automated testing on your tree +============================================ + +1. Create a Linux tree in https://gitlab.freedesktop.org/ if you don't have one +yet + +2. In your kernel repo's configuration (eg. +https://gitlab.freedesktop.org/janedoe/linux/-/settings/ci_cd), change the +CI/CD configuration file from .gitlab-ci.yml to +drivers/gpu/drm/ci/gitlab-ci.yml. + +3. Request to be added to the drm/ci-ok group so that your user has the +necessary privileges to run the CI on https://gitlab.freedesktop.org/drm/ci-ok + +4. Next time you push to this repository, you will see a CI pipeline being +created (eg. https://gitlab.freedesktop.org/janedoe/linux/-/pipelines) + +5. The various jobs will be run and when the pipeline is finished, all jobs +should be green unless a regression has been found. + + +How to update test expectations +=============================== + +If your changes to the code fix any tests, you will have to remove one or more +lines from one or more of the files in +drivers/gpu/drm/ci/${DRIVER_NAME}_*_fails.txt, for each of the test platforms +affected by the change. + + +How to expand coverage +====================== + +If your code changes make it possible to run more tests (by solving reliability +issues, for example), you can remove tests from the flakes and/or skips lists, +and then the expected results if there are any known failures. + +If there is a need for updating the version of IGT being used (maybe you have +added more tests to it), update the IGT_VERSION variable at the top of the +gitlab-ci.yml file. + + +How to test your changes to the scripts +======================================= + +For testing changes to the scripts in the drm-ci repo, change the +DRM_CI_PROJECT_PATH and DRM_CI_COMMIT_SHA variables in +drivers/gpu/drm/ci/gitlab-ci.yml to match your fork of the project (eg. +janedoe/drm-ci). This fork needs to be in https://gitlab.freedesktop.org/. + + +How to incorporate external fixes in your testing +================================================= + +Often, regressions in other trees will prevent testing changes local to the +tree under test. These fixes will be automatically merged in during the build +jobs from a branch in the target tree that is named as +${TARGET_BRANCH}-external-fixes. + +If the pipeline is not in a merge request and a branch with the same name +exists in the local tree, commits from that branch will be merged in as well. + + +How to deal with automated testing labs that may be down +======================================================== + +If a hardware farm is down and thus causing pipelines to fail that would +otherwise pass, one can disable all jobs that would be submitted to that farm +by editing the file at +https://gitlab.freedesktop.org/gfx-ci/lab-status/-/blob/main/lab-status.yml. diff --git a/Documentation/gpu/driver-uapi.rst b/Documentation/gpu/driver-uapi.rst index 4411e6919a3d..c08bcbb95fb3 100644 --- a/Documentation/gpu/driver-uapi.rst +++ b/Documentation/gpu/driver-uapi.rst @@ -6,3 +6,14 @@ drm/i915 uAPI ============= .. kernel-doc:: include/uapi/drm/i915_drm.h + +drm/nouveau uAPI +================ + +VM_BIND / EXEC uAPI +------------------- + +.. kernel-doc:: drivers/gpu/drm/nouveau/nouveau_exec.c + :doc: Overview + +.. kernel-doc:: include/uapi/drm/nouveau_drm.h diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst index 3a52f48215a3..45a12e552091 100644 --- a/Documentation/gpu/drivers.rst +++ b/Documentation/gpu/drivers.rst @@ -18,6 +18,7 @@ GPU Driver Documentation xen-front afbc komeda-kms + panfrost .. only:: subproject and html diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index b8ab05e42dbb..b748b8ae70b2 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -378,7 +378,7 @@ SCDC Helper Functions Reference HDMI Infoframes Helper Reference ================================ -Strictly speaking this is not a DRM helper library but generally useable +Strictly speaking this is not a DRM helper library but generally usable by any driver interfacing with HDMI outputs like v4l or alsa drivers. But it nicely fits into the overall topic of mode setting helper libraries and hence is also included here. diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index c92d425cb2dd..270d320407c7 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -66,11 +66,11 @@ Composition Properties`_ and related chapters. For the output routing the first step is encoders (represented by :c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those are really just internal artifacts of the helper libraries used to implement KMS -drivers. Besides that they make it unecessarily more complicated for userspace +drivers. Besides that they make it unnecessarily more complicated for userspace to figure out which connections between a CRTC and a connector are possible, and what kind of cloning is supported, they serve no purpose in the userspace API. Unfortunately encoders have been exposed to userspace, hence can't remove them -at this point. Futhermore the exposed restrictions are often wrongly set by +at this point. Furthermore the exposed restrictions are often wrongly set by drivers, and in many cases not powerful enough to express the real restrictions. A CRTC can be connected to multiple encoders, and for an active CRTC there must be at least one encoder. @@ -260,7 +260,7 @@ Taken all together there's two consequences for the atomic design: drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct drm_connector_state <drm_connector_state>` for connectors. These are the only objects with userspace-visible and settable state. For internal state drivers - can subclass these structures through embeddeding, or add entirely new state + can subclass these structures through embedding, or add entirely new state structures for their globally shared hardware functions, see :c:type:`struct drm_private_state<drm_private_state>`. @@ -360,6 +360,8 @@ Format Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c :export: +.. _kms_dumb_buffer_objects: + Dumb Buffer Objects =================== diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index a79fd3549ff8..602010cb6894 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -466,6 +466,42 @@ DRM MM Range Allocator Function References .. kernel-doc:: drivers/gpu/drm/drm_mm.c :export: +DRM GPUVM +========= + +Overview +-------- + +.. kernel-doc:: drivers/gpu/drm/drm_gpuvm.c + :doc: Overview + +Split and Merge +--------------- + +.. kernel-doc:: drivers/gpu/drm/drm_gpuvm.c + :doc: Split and Merge + +Locking +------- + +.. kernel-doc:: drivers/gpu/drm/drm_gpuvm.c + :doc: Locking + +Examples +-------- + +.. kernel-doc:: drivers/gpu/drm/drm_gpuvm.c + :doc: Examples + +DRM GPUVM Function References +----------------------------- + +.. kernel-doc:: include/drm/drm_gpuvm.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_gpuvm.c + :export: + DRM Buddy Allocator =================== @@ -481,8 +517,10 @@ DRM Cache Handling and Fast WC memcpy() .. kernel-doc:: drivers/gpu/drm/drm_cache.c :export: +.. _drm_sync_objects: + DRM Sync Objects -=========================== +================ .. kernel-doc:: drivers/gpu/drm/drm_syncobj.c :doc: Overview @@ -493,6 +531,18 @@ DRM Sync Objects .. kernel-doc:: drivers/gpu/drm/drm_syncobj.c :export: +DRM Execution context +===================== + +.. kernel-doc:: drivers/gpu/drm/drm_exec.c + :doc: Overview + +.. kernel-doc:: include/drm/drm_exec.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_exec.c + :export: + GPU Scheduler ============= diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 65fb3036a580..370d820be248 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -285,6 +285,83 @@ for GPU1 and GPU2 from different vendors, and a third handler for mmapped regular files. Threads cause additional pain with signal handling as well. +Device reset +============ + +The GPU stack is really complex and is prone to errors, from hardware bugs, +faulty applications and everything in between the many layers. Some errors +require resetting the device in order to make the device usable again. This +section describes the expectations for DRM and usermode drivers when a +device resets and how to propagate the reset status. + +Device resets can not be disabled without tainting the kernel, which can lead to +hanging the entire kernel through shrinkers/mmu_notifiers. Userspace role in +device resets is to propagate the message to the application and apply any +special policy for blocking guilty applications, if any. Corollary is that +debugging a hung GPU context require hardware support to be able to preempt such +a GPU context while it's stopped. + +Kernel Mode Driver +------------------ + +The KMD is responsible for checking if the device needs a reset, and to perform +it as needed. Usually a hang is detected when a job gets stuck executing. KMD +should keep track of resets, because userspace can query any time about the +reset status for a specific context. This is needed to propagate to the rest of +the stack that a reset has happened. Currently, this is implemented by each +driver separately, with no common DRM interface. Ideally this should be properly +integrated at DRM scheduler to provide a common ground for all drivers. After a +reset, KMD should reject new command submissions for affected contexts. + +User Mode Driver +---------------- + +After command submission, UMD should check if the submission was accepted or +rejected. After a reset, KMD should reject submissions, and UMD can issue an +ioctl to the KMD to check the reset status, and this can be checked more often +if the UMD requires it. After detecting a reset, UMD will then proceed to report +it to the application using the appropriate API error code, as explained in the +section below about robustness. + +Robustness +---------- + +The only way to try to keep a graphical API context working after a reset is if +it complies with the robustness aspects of the graphical API that it is using. + +Graphical APIs provide ways to applications to deal with device resets. However, +there is no guarantee that the app will use such features correctly, and a +userspace that doesn't support robust interfaces (like a non-robust +OpenGL context or API without any robustness support like libva) leave the +robustness handling entirely to the userspace driver. There is no strong +community consensus on what the userspace driver should do in that case, +since all reasonable approaches have some clear downsides. + +OpenGL +~~~~~~ + +Apps using OpenGL should use the available robust interfaces, like the +extension ``GL_ARB_robustness`` (or ``GL_EXT_robustness`` for OpenGL ES). This +interface tells if a reset has happened, and if so, all the context state is +considered lost and the app proceeds by creating new ones. There's no consensus +on what to do to if robustness is not in use. + +Vulkan +~~~~~~ + +Apps using Vulkan should check for ``VK_ERROR_DEVICE_LOST`` for submissions. +This error code means, among other things, that a device reset has happened and +it needs to recreate the contexts to keep going. + +Reporting causes of resets +-------------------------- + +Apart from propagating the reset through the stack so apps can recover, it's +really useful for driver developers to learn more about what caused the reset in +the first place. DRM devices should make use of devcoredump to store relevant +information about the reset, so this information can be added to user bug +reports. + .. _drm_driver_ioctl: IOCTL Support on Device Nodes @@ -450,12 +527,12 @@ VBlank event handling The DRM core exposes two vertical blank related ioctls: -DRM_IOCTL_WAIT_VBLANK +:c:macro:`DRM_IOCTL_WAIT_VBLANK` This takes a struct drm_wait_vblank structure as its argument, and it is used to block or request a signal when a specified vblank event occurs. -DRM_IOCTL_MODESET_CTL +:c:macro:`DRM_IOCTL_MODESET_CTL` This was only used for user-mode-settind drivers around modesetting changes to allow the kernel to update the vblank interrupt after mode setting, since on many devices the vertical blank counter is @@ -478,11 +555,18 @@ The index is used in cases where a densely packed identifier for a CRTC is needed, for instance a bitmask of CRTC's. The member possible_crtcs of struct drm_mode_get_plane is an example. -DRM_IOCTL_MODE_GETRESOURCES populates a structure with an array of CRTC ID's, -and the CRTC index is its position in this array. +:c:macro:`DRM_IOCTL_MODE_GETRESOURCES` populates a structure with an array of +CRTC ID's, and the CRTC index is its position in this array. .. kernel-doc:: include/uapi/drm/drm.h :internal: .. kernel-doc:: include/uapi/drm/drm_mode.h :internal: + + +dma-buf interoperability +======================== + +Please see Documentation/userspace-api/dma-buf-alloc-exchange.rst for +information on how dma-buf is integrated and exposed within DRM. diff --git a/Documentation/gpu/drm-usage-stats.rst b/Documentation/gpu/drm-usage-stats.rst index fe35a291ff3e..7aca5c7a7b1d 100644 --- a/Documentation/gpu/drm-usage-stats.rst +++ b/Documentation/gpu/drm-usage-stats.rst @@ -8,7 +8,7 @@ DRM drivers can choose to export partly standardised text output via the `fops->show_fdinfo()` as part of the driver specific file operations registered in the `struct drm_driver` object registered with the DRM core. -One purpose of this output is to enable writing as generic as practicaly +One purpose of this output is to enable writing as generic as practically feasible `top(1)` like userspace monitoring tools. Given the differences between various DRM drivers the specification of the @@ -119,7 +119,7 @@ drm-engine-<keystr> tag and shall contain the maximum frequency for the given engine. Taken together with drm-cycles-<keystr>, this can be used to calculate percentage utilization of the engine, whereas drm-engine-<keystr> only reflects time active without considering what frequency the engine is operating as a -percentage of it's maximum frequency. +percentage of its maximum frequency. Memory ^^^^^^ @@ -169,3 +169,4 @@ Driver specific implementations ------------------------------- :ref:`i915-usage-stats` +:ref:`panfrost-usage-stats` diff --git a/Documentation/gpu/drm-vm-bind-async.rst b/Documentation/gpu/drm-vm-bind-async.rst new file mode 100644 index 000000000000..3d709d02099c --- /dev/null +++ b/Documentation/gpu/drm-vm-bind-async.rst @@ -0,0 +1,309 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR MIT) + +==================== +Asynchronous VM_BIND +==================== + +Nomenclature: +============= + +* ``VRAM``: On-device memory. Sometimes referred to as device local memory. + +* ``gpu_vm``: A virtual GPU address space. Typically per process, but + can be shared by multiple processes. + +* ``VM_BIND``: An operation or a list of operations to modify a gpu_vm using + an IOCTL. The operations include mapping and unmapping system- or + VRAM memory. + +* ``syncobj``: A container that abstracts synchronization objects. The + synchronization objects can be either generic, like dma-fences or + driver specific. A syncobj typically indicates the type of the + underlying synchronization object. + +* ``in-syncobj``: Argument to a VM_BIND IOCTL, the VM_BIND operation waits + for these before starting. + +* ``out-syncobj``: Argument to a VM_BIND_IOCTL, the VM_BIND operation + signals these when the bind operation is complete. + +* ``dma-fence``: A cross-driver synchronization object. A basic + understanding of dma-fences is required to digest this + document. Please refer to the ``DMA Fences`` section of the + :doc:`dma-buf doc </driver-api/dma-buf>`. + +* ``memory fence``: A synchronization object, different from a dma-fence. + A memory fence uses the value of a specified memory location to determine + signaled status. A memory fence can be awaited and signaled by both + the GPU and CPU. Memory fences are sometimes referred to as + user-fences, userspace-fences or gpu futexes and do not necessarily obey + the dma-fence rule of signaling within a "reasonable amount of time". + The kernel should thus avoid waiting for memory fences with locks held. + +* ``long-running workload``: A workload that may take more than the + current stipulated dma-fence maximum signal delay to complete and + which therefore needs to set the gpu_vm or the GPU execution context in + a certain mode that disallows completion dma-fences. + +* ``exec function``: An exec function is a function that revalidates all + affected gpu_vmas, submits a GPU command batch and registers the + dma_fence representing the GPU command's activity with all affected + dma_resvs. For completeness, although not covered by this document, + it's worth mentioning that an exec function may also be the + revalidation worker that is used by some drivers in compute / + long-running mode. + +* ``bind context``: A context identifier used for the VM_BIND + operation. VM_BIND operations that use the same bind context can be + assumed, where it matters, to complete in order of submission. No such + assumptions can be made for VM_BIND operations using separate bind contexts. + +* ``UMD``: User-mode driver. + +* ``KMD``: Kernel-mode driver. + + +Synchronous / Asynchronous VM_BIND operation +============================================ + +Synchronous VM_BIND +___________________ +With Synchronous VM_BIND, the VM_BIND operations all complete before the +IOCTL returns. A synchronous VM_BIND takes neither in-fences nor +out-fences. Synchronous VM_BIND may block and wait for GPU operations; +for example swap-in or clearing, or even previous binds. + +Asynchronous VM_BIND +____________________ +Asynchronous VM_BIND accepts both in-syncobjs and out-syncobjs. While the +IOCTL may return immediately, the VM_BIND operations wait for the in-syncobjs +before modifying the GPU page-tables, and signal the out-syncobjs when +the modification is done in the sense that the next exec function that +awaits for the out-syncobjs will see the change. Errors are reported +synchronously. +In low-memory situations the implementation may block, performing the +VM_BIND synchronously, because there might not be enough memory +immediately available for preparing the asynchronous operation. + +If the VM_BIND IOCTL takes a list or an array of operations as an argument, +the in-syncobjs needs to signal before the first operation starts to +execute, and the out-syncobjs signal after the last operation +completes. Operations in the operation list can be assumed, where it +matters, to complete in order. + +Since asynchronous VM_BIND operations may use dma-fences embedded in +out-syncobjs and internally in KMD to signal bind completion, any +memory fences given as VM_BIND in-fences need to be awaited +synchronously before the VM_BIND ioctl returns, since dma-fences, +required to signal in a reasonable amount of time, can never be made +to depend on memory fences that don't have such a restriction. + +The purpose of an Asynchronous VM_BIND operation is for user-mode +drivers to be able to pipeline interleaved gpu_vm modifications and +exec functions. For long-running workloads, such pipelining of a bind +operation is not allowed and any in-fences need to be awaited +synchronously. The reason for this is twofold. First, any memory +fences gated by a long-running workload and used as in-syncobjs for the +VM_BIND operation will need to be awaited synchronously anyway (see +above). Second, any dma-fences used as in-syncobjs for VM_BIND +operations for long-running workloads will not allow for pipelining +anyway since long-running workloads don't allow for dma-fences as +out-syncobjs, so while theoretically possible the use of them is +questionable and should be rejected until there is a valuable use-case. +Note that this is not a limitation imposed by dma-fence rules, but +rather a limitation imposed to keep KMD implementation simple. It does +not affect using dma-fences as dependencies for the long-running +workload itself, which is allowed by dma-fence rules, but rather for +the VM_BIND operation only. + +An asynchronous VM_BIND operation may take substantial time to +complete and signal the out_fence. In particular if the operation is +deeply pipelined behind other VM_BIND operations and workloads +submitted using exec functions. In that case, UMD might want to avoid a +subsequent VM_BIND operation to be queued behind the first one if +there are no explicit dependencies. In order to circumvent such a queue-up, a +VM_BIND implementation may allow for VM_BIND contexts to be +created. For each context, VM_BIND operations will be guaranteed to +complete in the order they were submitted, but that is not the case +for VM_BIND operations executing on separate VM_BIND contexts. Instead +KMD will attempt to execute such VM_BIND operations in parallel but +leaving no guarantee that they will actually be executed in +parallel. There may be internal implicit dependencies that only KMD knows +about, for example page-table structure changes. A way to attempt +to avoid such internal dependencies is to have different VM_BIND +contexts use separate regions of a VM. + +Also for VM_BINDS for long-running gpu_vms the user-mode driver should typically +select memory fences as out-fences since that gives greater flexibility for +the kernel mode driver to inject other operations into the bind / +unbind operations. Like for example inserting breakpoints into batch +buffers. The workload execution can then easily be pipelined behind +the bind completion using the memory out-fence as the signal condition +for a GPU semaphore embedded by UMD in the workload. + +There is no difference in the operations supported or in +multi-operation support between asynchronous VM_BIND and synchronous VM_BIND. + +Multi-operation VM_BIND IOCTL error handling and interrupts +=========================================================== + +The VM_BIND operations of the IOCTL may error for various reasons, for +example due to lack of resources to complete and due to interrupted +waits. +In these situations UMD should preferably restart the IOCTL after +taking suitable action. +If UMD has over-committed a memory resource, an -ENOSPC error will be +returned, and UMD may then unbind resources that are not used at the +moment and rerun the IOCTL. On -EINTR, UMD should simply rerun the +IOCTL and on -ENOMEM user-space may either attempt to free known +system memory resources or fail. In case of UMD deciding to fail a +bind operation, due to an error return, no additional action is needed +to clean up the failed operation, and the VM is left in the same state +as it was before the failing IOCTL. +Unbind operations are guaranteed not to return any errors due to +resource constraints, but may return errors due to, for example, +invalid arguments or the gpu_vm being banned. +In the case an unexpected error happens during the asynchronous bind +process, the gpu_vm will be banned, and attempts to use it after banning +will return -ENOENT. + +Example: The Xe VM_BIND uAPI +============================ + +Starting with the VM_BIND operation struct, the IOCTL call can take +zero, one or many such operations. A zero number means only the +synchronization part of the IOCTL is carried out: an asynchronous +VM_BIND updates the syncobjects, whereas a sync VM_BIND waits for the +implicit dependencies to be fulfilled. + +.. code-block:: c + + struct drm_xe_vm_bind_op { + /** + * @obj: GEM object to operate on, MBZ for MAP_USERPTR, MBZ for UNMAP + */ + __u32 obj; + + /** @pad: MBZ */ + __u32 pad; + + union { + /** + * @obj_offset: Offset into the object for MAP. + */ + __u64 obj_offset; + + /** @userptr: user virtual address for MAP_USERPTR */ + __u64 userptr; + }; + + /** + * @range: Number of bytes from the object to bind to addr, MBZ for UNMAP_ALL + */ + __u64 range; + + /** @addr: Address to operate on, MBZ for UNMAP_ALL */ + __u64 addr; + + /** + * @tile_mask: Mask for which tiles to create binds for, 0 == All tiles, + * only applies to creating new VMAs + */ + __u64 tile_mask; + + /* Map (parts of) an object into the GPU virtual address range. + #define XE_VM_BIND_OP_MAP 0x0 + /* Unmap a GPU virtual address range */ + #define XE_VM_BIND_OP_UNMAP 0x1 + /* + * Map a CPU virtual address range into a GPU virtual + * address range. + */ + #define XE_VM_BIND_OP_MAP_USERPTR 0x2 + /* Unmap a gem object from the VM. */ + #define XE_VM_BIND_OP_UNMAP_ALL 0x3 + /* + * Make the backing memory of an address range resident if + * possible. Note that this doesn't pin backing memory. + */ + #define XE_VM_BIND_OP_PREFETCH 0x4 + + /* Make the GPU map readonly. */ + #define XE_VM_BIND_FLAG_READONLY (0x1 << 16) + /* + * Valid on a faulting VM only, do the MAP operation immediately rather + * than deferring the MAP to the page fault handler. + */ + #define XE_VM_BIND_FLAG_IMMEDIATE (0x1 << 17) + /* + * When the NULL flag is set, the page tables are setup with a special + * bit which indicates writes are dropped and all reads return zero. In + * the future, the NULL flags will only be valid for XE_VM_BIND_OP_MAP + * operations, the BO handle MBZ, and the BO offset MBZ. This flag is + * intended to implement VK sparse bindings. + */ + #define XE_VM_BIND_FLAG_NULL (0x1 << 18) + /** @op: Operation to perform (lower 16 bits) and flags (upper 16 bits) */ + __u32 op; + + /** @mem_region: Memory region to prefetch VMA to, instance not a mask */ + __u32 region; + + /** @reserved: Reserved */ + __u64 reserved[2]; + }; + + +The VM_BIND IOCTL argument itself, looks like follows. Note that for +synchronous VM_BIND, the num_syncs and syncs fields must be zero. Here +the ``exec_queue_id`` field is the VM_BIND context discussed previously +that is used to facilitate out-of-order VM_BINDs. + +.. code-block:: c + + struct drm_xe_vm_bind { + /** @extensions: Pointer to the first extension struct, if any */ + __u64 extensions; + + /** @vm_id: The ID of the VM to bind to */ + __u32 vm_id; + + /** + * @exec_queue_id: exec_queue_id, must be of class DRM_XE_ENGINE_CLASS_VM_BIND + * and exec queue must have same vm_id. If zero, the default VM bind engine + * is used. + */ + __u32 exec_queue_id; + + /** @num_binds: number of binds in this IOCTL */ + __u32 num_binds; + + /* If set, perform an async VM_BIND, if clear a sync VM_BIND */ + #define XE_VM_BIND_IOCTL_FLAG_ASYNC (0x1 << 0) + + /** @flag: Flags controlling all operations in this ioctl. */ + __u32 flags; + + union { + /** @bind: used if num_binds == 1 */ + struct drm_xe_vm_bind_op bind; + + /** + * @vector_of_binds: userptr to array of struct + * drm_xe_vm_bind_op if num_binds > 1 + */ + __u64 vector_of_binds; + }; + + /** @num_syncs: amount of syncs to wait for or to signal on completion. */ + __u32 num_syncs; + + /** @pad2: MBZ */ + __u32 pad2; + + /** @syncs: pointer to struct drm_xe_sync array */ + __u64 syncs; + + /** @reserved: Reserved */ + __u64 reserved[2]; + }; diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 60ea21734902..0ca1550fd9dc 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -267,19 +267,22 @@ i915 driver. Intel GPU Basics ---------------- -An Intel GPU has multiple engines. There are several engine types. - -- RCS engine is for rendering 3D and performing compute, this is named - `I915_EXEC_RENDER` in user space. -- BCS is a blitting (copy) engine, this is named `I915_EXEC_BLT` in user - space. -- VCS is a video encode and decode engine, this is named `I915_EXEC_BSD` - in user space -- VECS is video enhancement engine, this is named `I915_EXEC_VEBOX` in user - space. -- The enumeration `I915_EXEC_DEFAULT` does not refer to specific engine; - instead it is to be used by user space to specify a default rendering - engine (for 3D) that may or may not be the same as RCS. +An Intel GPU has multiple engines. There are several engine types: + +- Render Command Streamer (RCS). An engine for rendering 3D and + performing compute. +- Blitting Command Streamer (BCS). An engine for performing blitting and/or + copying operations. +- Video Command Streamer. An engine used for video encoding and decoding. Also + sometimes called 'BSD' in hardware documentation. +- Video Enhancement Command Streamer (VECS). An engine for video enhancement. + Also sometimes called 'VEBOX' in hardware documentation. +- Compute Command Streamer (CCS). An engine that has access to the media and + GPGPU pipelines, but not the 3D pipeline. +- Graphics Security Controller (GSCCS). A dedicated engine for internal + communication with GSC controller on security related tasks like + High-bandwidth Digital Content Protection (HDCP), Protected Xe Path (PXP), + and HuC firmware authentication. The Intel GPU family is a family of integrated GPU's using Unified Memory Access. For having the GPU "do work", user space will feed the @@ -304,10 +307,10 @@ reads of following commands. Actions issued between different contexts and the only way to synchronize across contexts (even from the same file descriptor) is through the use of fences. At least as far back as Gen4, also have that a context carries with it a GPU HW context; -the HW context is essentially (most of atleast) the state of a GPU. +the HW context is essentially (most of at least) the state of a GPU. In addition to the ordering guarantees, the kernel will restore GPU state via HW context when commands are issued to a context, this saves -user space the need to restore (most of atleast) the GPU state at the +user space the need to restore (most of at least) the GPU state at the start of each batchbuffer. The non-deprecated ioctls to submit batchbuffer work can pass that ID (in the lower bits of drm_i915_gem_execbuffer2::rsvd1) to identify what context to use with the command. diff --git a/Documentation/gpu/implementation_guidelines.rst b/Documentation/gpu/implementation_guidelines.rst new file mode 100644 index 000000000000..138e637dcc6b --- /dev/null +++ b/Documentation/gpu/implementation_guidelines.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR MIT) + +=========================================================== +Misc DRM driver uAPI- and feature implementation guidelines +=========================================================== + +.. toctree:: + + drm-vm-bind-async diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst index eee5996acf2c..37e383ccf73f 100644 --- a/Documentation/gpu/index.rst +++ b/Documentation/gpu/index.rst @@ -17,6 +17,8 @@ GPU Driver Developer's Guide backlight vga-switcheroo vgaarbiter + automated_testing + implementation_guidelines todo rfc/index diff --git a/Documentation/gpu/kms-properties.csv b/Documentation/gpu/kms-properties.csv index 07ed22ea3bd6..0f9590834829 100644 --- a/Documentation/gpu/kms-properties.csv +++ b/Documentation/gpu/kms-properties.csv @@ -17,7 +17,7 @@ Owner Module/Drivers,Group,Property Name,Type,Property Values,Object attached,De ,Virtual GPU,“suggested X”,RANGE,"Min=0, Max=0xffffffff",Connector,property to suggest an X offset for a connector ,,“suggested Y”,RANGE,"Min=0, Max=0xffffffff",Connector,property to suggest an Y offset for a connector ,Optional,"""aspect ratio""",ENUM,"{ ""None"", ""4:3"", ""16:9"" }",Connector,TDB -i915,Generic,"""Broadcast RGB""",ENUM,"{ ""Automatic"", ""Full"", ""Limited 16:235"" }",Connector,"When this property is set to Limited 16:235 and CTM is set, the hardware will be programmed with the result of the multiplication of CTM by the limited range matrix to ensure the pixels normaly in the range 0..1.0 are remapped to the range 16/255..235/255." +i915,Generic,"""Broadcast RGB""",ENUM,"{ ""Automatic"", ""Full"", ""Limited 16:235"" }",Connector,"When this property is set to Limited 16:235 and CTM is set, the hardware will be programmed with the result of the multiplication of CTM by the limited range matrix to ensure the pixels normally in the range 0..1.0 are remapped to the range 16/255..235/255." ,,“audio”,ENUM,"{ ""force-dvi"", ""off"", ""auto"", ""on"" }",Connector,TBD ,SDVO-TV,“mode”,ENUM,"{ ""NTSC_M"", ""NTSC_J"", ""NTSC_443"", ""PAL_B"" } etc.",Connector,TBD ,,"""left_margin""",RANGE,"Min=0, Max= SDVO dependent",Connector,TBD diff --git a/Documentation/gpu/komeda-kms.rst b/Documentation/gpu/komeda-kms.rst index eb693c857e2d..633a016563ae 100644 --- a/Documentation/gpu/komeda-kms.rst +++ b/Documentation/gpu/komeda-kms.rst @@ -328,7 +328,7 @@ of course we’d better share as much as possible between different products. To achieve this, split the komeda device into two layers: CORE and CHIP. - CORE: for common features and capabilities handling. -- CHIP: for register programing and HW specific feature (limitation) handling. +- CHIP: for register programming and HW specific feature (limitation) handling. CORE can access CHIP by three chip function structures: @@ -481,7 +481,7 @@ Build komeda to be a Linux module driver Now we have two level devices: - komeda_dev: describes the real display hardware. -- komeda_kms_dev: attachs or connects komeda_dev to DRM-KMS. +- komeda_kms_dev: attaches or connects komeda_dev to DRM-KMS. All komeda operations are supplied or operated by komeda_dev or komeda_kms_dev, the module driver is only a simple wrapper to pass the Linux command diff --git a/Documentation/gpu/msm-crash-dump.rst b/Documentation/gpu/msm-crash-dump.rst index 240ef200f76c..9509cc4224f4 100644 --- a/Documentation/gpu/msm-crash-dump.rst +++ b/Documentation/gpu/msm-crash-dump.rst @@ -23,7 +23,7 @@ module The module that generated the crashdump. time - The kernel time at crash formated as seconds.microseconds. + The kernel time at crash formatted as seconds.microseconds. comm Comm string for the binary that generated the fault. diff --git a/Documentation/gpu/panfrost.rst b/Documentation/gpu/panfrost.rst new file mode 100644 index 000000000000..b80e41f4b2c5 --- /dev/null +++ b/Documentation/gpu/panfrost.rst @@ -0,0 +1,40 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +========================= + drm/Panfrost Mali Driver +========================= + +.. _panfrost-usage-stats: + +Panfrost DRM client usage stats implementation +============================================== + +The drm/Panfrost driver implements the DRM client usage stats specification as +documented in :ref:`drm-client-usage-stats`. + +Example of the output showing the implemented key value pairs and entirety of +the currently possible format options: + +:: + pos: 0 + flags: 02400002 + mnt_id: 27 + ino: 531 + drm-driver: panfrost + drm-client-id: 14 + drm-engine-fragment: 1846584880 ns + drm-cycles-fragment: 1424359409 + drm-maxfreq-fragment: 799999987 Hz + drm-curfreq-fragment: 799999987 Hz + drm-engine-vertex-tiler: 71932239 ns + drm-cycles-vertex-tiler: 52617357 + drm-maxfreq-vertex-tiler: 799999987 Hz + drm-curfreq-vertex-tiler: 799999987 Hz + drm-total-memory: 290 MiB + drm-shared-memory: 0 MiB + drm-active-memory: 226 MiB + drm-resident-memory: 36496 KiB + drm-purgeable-memory: 128 KiB + +Possible `drm-engine-` key names are: `fragment`, and `vertex-tiler`. +`drm-curfreq-` values convey the current operating frequency for that engine. diff --git a/Documentation/gpu/rfc/i915_scheduler.rst b/Documentation/gpu/rfc/i915_scheduler.rst index d630f15ab795..c237ebc024cd 100644 --- a/Documentation/gpu/rfc/i915_scheduler.rst +++ b/Documentation/gpu/rfc/i915_scheduler.rst @@ -37,7 +37,7 @@ i915 with the DRM scheduler is: * Watchdog hooks into DRM scheduler * Lots of complexity of the GuC backend can be pulled out once integrated with DRM scheduler (e.g. state machine gets - simplier, locking gets simplier, etc...) + simpler, locking gets simpler, etc...) * Execlists backend will minimum required to hook in the DRM scheduler * Legacy interface * Features like timeslicing / preemption / virtual engines would @@ -135,9 +135,13 @@ Add I915_CONTEXT_ENGINES_EXT_PARALLEL_SUBMIT and drm_i915_context_engines_parallel_submit to the uAPI to implement this extension. +.. c:namespace-push:: rfc + .. kernel-doc:: include/uapi/drm/i915_drm.h :functions: i915_context_engines_parallel_submit +.. c:namespace-pop:: + Extend execbuf2 IOCTL to support submitting N BBs in a single IOCTL ------------------------------------------------------------------- Contexts that have been configured with the 'set_parallel' extension can only diff --git a/Documentation/gpu/rfc/i915_vm_bind.rst b/Documentation/gpu/rfc/i915_vm_bind.rst index 9a1dcdf2799e..0b3b525ac620 100644 --- a/Documentation/gpu/rfc/i915_vm_bind.rst +++ b/Documentation/gpu/rfc/i915_vm_bind.rst @@ -90,7 +90,7 @@ submission, they need only one dma-resv fence list updated. Thus, the fast path (where required mappings are already bound) submission latency is O(1) w.r.t the number of VM private BOs. -VM_BIND locking hirarchy +VM_BIND locking hierarchy ------------------------- The locking design here supports the older (execlist based) execbuf mode, the newer VM_BIND mode, the VM_BIND mode with GPU page faults and possible future diff --git a/Documentation/gpu/rfc/xe.rst b/Documentation/gpu/rfc/xe.rst index 2516fe141db6..c29113a0ac30 100644 --- a/Documentation/gpu/rfc/xe.rst +++ b/Documentation/gpu/rfc/xe.rst @@ -67,14 +67,8 @@ platforms. When the time comes for Xe, the protection will be lifted on Xe and kept in i915. -Xe driver will be protected with both STAGING Kconfig and force_probe. Changes in -the uAPI are expected while the driver is behind these protections. STAGING will -be removed when the driver uAPI gets to a mature state where we can guarantee the -‘no regression’ rule. Then force_probe will be lifted only for future platforms -that will be productized with Xe driver, but not with i915. - -Xe – Pre-Merge Goals -==================== +Xe – Pre-Merge Goals - Work-in-Progress +======================================= Drm_scheduler ------------- @@ -94,41 +88,6 @@ 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. -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. - -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. - ASYNC VM_BIND ------------- Although having a common DRM level IOCTL for VM_BIND is not a requirement to get @@ -138,8 +97,8 @@ 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 a sample API should be documented here or in -a separate document pointed to by this document. +various flavors, error handling and sample API suggestions are documented in +:doc:`The ASYNC VM_BIND document </gpu/drm-vm-bind-async>`. Userptr integration and vm_bind ------------------------------- @@ -212,6 +171,14 @@ 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. +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 +================================ + Dev_coredump ------------ @@ -229,7 +196,37 @@ 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. -Xe – uAPI high level overview -============================= +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. -...Warning: To be done in follow up patches after/when/where the main consensus in various items are individually reached. +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 68bdafa0284f..03fe5d1247be 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -49,14 +49,18 @@ converted over. Modern compositors like Wayland or Surfaceflinger on Android really want an atomic modeset interface, so this is all about the bright future. -There is a conversion guide for atomic and all you need is a GPU for a -non-converted driver (again virtual HW drivers for KVM are still all -suitable). +There is a conversion guide for atomic [1]_ and all you need is a GPU for a +non-converted driver. The "Atomic mode setting design overview" series [2]_ +[3]_ at LWN.net can also be helpful. As part of this drivers also need to convert to universal plane (which means exposing primary & cursor as proper plane objects). But that's much easier to do by directly using the new atomic helper driver callbacks. + .. [1] https://blog.ffwll.ch/2014/11/atomic-modeset-support-for-kms-drivers.html + .. [2] https://lwn.net/Articles/653071/ + .. [3] https://lwn.net/Articles/653466/ + Contact: Daniel Vetter, respective driver maintainers Level: Advanced @@ -65,7 +69,7 @@ Clean up the clipped coordination confusion around planes --------------------------------------------------------- We have a helper to get this right with drm_plane_helper_check_update(), but -it's not consistently used. This should be fixed, preferrably in the atomic +it's not consistently used. This should be fixed, preferably in the atomic helpers (and drivers then moved over to clipped coordinates). Probably the helper should also be moved from drm_plane_helper.c to the atomic helpers, to avoid confusion - the other helpers in that file are all deprecated legacy @@ -181,13 +185,13 @@ reversed. To solve this we need one standard per-object locking mechanism, which is dma_resv_lock(). This lock needs to be called as the outermost lock, with all -other driver specific per-object locks removed. The problem is tha rolling out +other driver specific per-object locks removed. The problem is that rolling out the actual change to the locking contract is a flag day, due to struct dma_buf buffer sharing. Level: Expert -Convert logging to drm_* functions with drm_device paramater +Convert logging to drm_* functions with drm_device parameter ------------------------------------------------------------ For drivers which could have multiple instances, it is necessary to @@ -244,7 +248,7 @@ Level: Advanced Benchmark and optimize blitting and format-conversion function -------------------------------------------------------------- -Drawing to dispay memory quickly is crucial for many applications' +Drawing to display memory quickly is crucial for many applications' performance. On at least x86-64, sys_imageblit() is significantly slower than @@ -319,15 +323,6 @@ Contact: Daniel Vetter, Noralf Tronnes Level: Advanced -struct drm_gem_object_funcs ---------------------------- - -GEM objects can now have a function table instead of having the callbacks on the -DRM driver struct. This is now the preferred way. Callbacks in drivers have been -converted, except for struct drm_driver.gem_prime_mmap. - -Level: Intermediate - connector register/unregister fixes ----------------------------------- @@ -452,6 +447,44 @@ Contact: Thomas Zimmermann <tzimmermann@suse.de> Level: Starter +Remove driver dependencies on FB_DEVICE +--------------------------------------- + +A number of fbdev drivers provide attributes via sysfs and therefore depend +on CONFIG_FB_DEVICE to be selected. Review each driver and attempt to make +any dependencies on CONFIG_FB_DEVICE optional. At the minimum, the respective +code in the driver could be conditionalized via ifdef CONFIG_FB_DEVICE. Not +all drivers might be able to drop CONFIG_FB_DEVICE. + +Contact: Thomas Zimmermann <tzimmermann@suse.de> + +Level: Starter + +Clean up checks for already prepared/enabled in panels +------------------------------------------------------ + +In a whole pile of panel drivers, we have code to make the +prepare/unprepare/enable/disable callbacks behave as no-ops if they've already +been called. To get some idea of the duplicated code, try:: + + git grep 'if.*>prepared' -- drivers/gpu/drm/panel + git grep 'if.*>enabled' -- drivers/gpu/drm/panel + +In the patch ("drm/panel: Check for already prepared/enabled in drm_panel") +we've moved this check to the core. Now we can most definitely remove the +check from the individual panels and save a pile of code. + +In adition to removing the check from the individual panels, it is believed +that even the core shouldn't need this check and that should be considered +an error if other code ever relies on this check. The check in the core +currently prints a warning whenever something is relying on this check with +dev_warn(). After a little while, we likely want to promote this to a +WARN(1) to help encourage folks not to rely on this behavior. + +Contact: Douglas Anderson <dianders@chromium.org> + +Level: Starter/Intermediate + Core refactorings ================= @@ -749,16 +782,16 @@ existing hardware. The new driver's call-back functions are filled from existing fbdev code. More complex fbdev drivers can be refactored step-by-step into a DRM -driver with the help of the DRM fbconv helpers. [1] These helpers provide +driver with the help of the DRM fbconv helpers [4]_. These helpers provide the transition layer between the DRM core infrastructure and the fbdev driver interface. Create a new DRM driver on top of the fbconv helpers, copy over the fbdev driver, and hook it up to the DRM code. Examples for -several fbdev drivers are available at [1] and a tutorial of this process -available at [2]. The result is a primitive DRM driver that can run X11 -and Weston. +several fbdev drivers are available in Thomas Zimmermann's fbconv tree +[4]_, as well as a tutorial of this process [5]_. The result is a primitive +DRM driver that can run X11 and Weston. - - [1] https://gitlab.freedesktop.org/tzimmermann/linux/tree/fbconv - - [2] https://gitlab.freedesktop.org/tzimmermann/linux/blob/fbconv/drivers/gpu/drm/drm_fbconv_helper.c + .. [4] https://gitlab.freedesktop.org/tzimmermann/linux/tree/fbconv + .. [5] https://gitlab.freedesktop.org/tzimmermann/linux/blob/fbconv/drivers/gpu/drm/drm_fbconv_helper.c Contact: Thomas Zimmermann <tzimmermann@suse.de> diff --git a/Documentation/hid/hidintro.rst b/Documentation/hid/hidintro.rst new file mode 100644 index 000000000000..73523e315ebd --- /dev/null +++ b/Documentation/hid/hidintro.rst @@ -0,0 +1,524 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================================== +Introduction to HID report descriptors +====================================== + +This chapter is meant to give a broad overview of what HID report +descriptors are, and of how a casual (non-kernel) programmer can deal +with HID devices that are not working well with Linux. + +.. contents:: + :local: + :depth: 2 + +.. toctree:: + :maxdepth: 2 + + hidreport-parsing + + +Introduction +============ + +HID stands for Human Interface Device, and can be whatever device you +are using to interact with a computer, be it a mouse, a touchpad, a +tablet, a microphone. + +Many HID devices work out the box, even if their hardware is different. +For example, mice can have any number of buttons; they may have a +wheel; movement sensitivity differs between different models, and so +on. Nonetheless, most of the time everything just works, without the +need to have specialized code in the kernel for every mouse model +developed since 1970. + +This is because modern HID devices do advertise their capabilities +through the *HID report descriptor*, a fixed set of bytes describing +exactly what *HID reports* may be sent between the device and the host +and the meaning of each individual bit in those reports. For example, +a HID Report Descriptor may specify that "in a report with ID 3 the +bits from 8 to 15 is the delta x coordinate of a mouse". + +The HID report itself then merely carries the actual data values +without any extra meta information. Note that HID reports may be sent +from the device ("Input Reports", i.e. input events), to the device +("Output Reports" to e.g. change LEDs) or used for device configuration +("Feature reports"). A device may support one or more HID reports. + +The HID subsystem is in charge of parsing the HID report descriptors, +and converts HID events into normal input device interfaces (see +Documentation/hid/hid-transport.rst). Devices may misbehave because the +HID report descriptor provided by the device is wrong, or because it +needs to be dealt with in a special way, or because some special +device or interaction mode is not handled by the default code. + +The format of HID report descriptors is described by two documents, +available from the `USB Implementers Forum <https://www.usb.org/>`_ +`HID web page <https://www.usb.org/hid>`_ address: + + * the `HID USB Device Class Definition + <https://www.usb.org/document-library/device-class-definition-hid-111>`_ (HID Spec from now on) + * the `HID Usage Tables <https://usb.org/document-library/hid-usage-tables-14>`_ (HUT from now on) + +The HID subsystem can deal with different transport drivers +(USB, I2C, Bluetooth, etc.). See Documentation/hid/hid-transport.rst. + +Parsing HID report descriptors +============================== + +The current list of HID devices can be found at ``/sys/bus/hid/devices/``. +For each device, say ``/sys/bus/hid/devices/0003\:093A\:2510.0002/``, +one can read the corresponding report descriptor:: + + $ hexdump -C /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor + 00000000 05 01 09 02 a1 01 09 01 a1 00 05 09 19 01 29 03 |..............).| + 00000010 15 00 25 01 75 01 95 03 81 02 75 05 95 01 81 01 |..%.u.....u.....| + 00000020 05 01 09 30 09 31 09 38 15 81 25 7f 75 08 95 03 |...0.1.8..%.u...| + 00000030 81 06 c0 c0 |....| + 00000034 + +Optional: the HID report descriptor can be read also by +directly accessing the hidraw driver [#hidraw]_. + +The basic structure of HID report descriptors is defined in the HID +spec, while HUT "defines constants that can be interpreted by an +application to identify the purpose and meaning of a data field in a +HID report". Each entry is defined by at least two bytes, where the +first one defines what type of value is following and is described in +the HID spec, while the second one carries the actual value and is +described in the HUT. + +HID report descriptors can, in principle, be painstakingly parsed by +hand, byte by byte. + +A short introduction on how to do this is sketched in +Documentation/hid/hidreport-parsing.rst; you only need to understand it +if you need to patch HID report descriptors. + +In practice you should not parse HID report descriptors by hand; rather, +you should use an existing parser. Among all the available ones + + * the online `USB Descriptor and Request Parser + <http://eleccelerator.com/usbdescreqparser/>`_; + * `hidrdd <https://github.com/abend0c1/hidrdd>`_, + that provides very detailed and somewhat verbose descriptions + (verbosity can be useful if you are not familiar with HID report + descriptors); + * `hid-tools <https://gitlab.freedesktop.org/libevdev/hid-tools>`_, + a complete utility set that allows, among other things, + to record and replay the raw HID reports and to debug + and replay HID devices. + It is being actively developed by the Linux HID subsystem maintainers. + +Parsing the mouse HID report descriptor with `hid-tools +<https://gitlab.freedesktop.org/libevdev/hid-tools>`_ leads to +(explanations interposed):: + + $ ./hid-decode /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor + # device 0:0 + # 0x05, 0x01, // Usage Page (Generic Desktop) 0 + # 0x09, 0x02, // Usage (Mouse) 2 + # 0xa1, 0x01, // Collection (Application) 4 + # 0x09, 0x01, // Usage (Pointer) 6 + # 0xa1, 0x00, // Collection (Physical) 8 + # 0x05, 0x09, // Usage Page (Button) 10 + +what follows is a button :: + + # 0x19, 0x01, // Usage Minimum (1) 12 + # 0x29, 0x03, // Usage Maximum (3) 14 + +first button is button number 1, last button is button number 3 :: + + # 0x15, 0x00, // Logical Minimum (0) 16 + # 0x25, 0x01, // Logical Maximum (1) 18 + +each button can send values from 0 up to including 1 +(i.e. they are binary buttons) :: + + # 0x75, 0x01, // Report Size (1) 20 + +each button is sent as exactly one bit :: + + # 0x95, 0x03, // Report Count (3) 22 + +and there are three of those bits (matching the three buttons) :: + + # 0x81, 0x02, // Input (Data,Var,Abs) 24 + +it's actual Data (not constant padding), they represent +a single variable (Var) and their values are Absolute (not relative); +See HID spec Sec. 6.2.2.5 "Input, Output, and Feature Items" :: + + # 0x75, 0x05, // Report Size (5) 26 + +five additional padding bits, needed to reach a byte :: + + # 0x95, 0x01, // Report Count (1) 28 + +those five bits are repeated only once :: + + # 0x81, 0x01, // Input (Cnst,Arr,Abs) 30 + +and take Constant (Cnst) values i.e. they can be ignored. :: + + # 0x05, 0x01, // Usage Page (Generic Desktop) 32 + # 0x09, 0x30, // Usage (X) 34 + # 0x09, 0x31, // Usage (Y) 36 + # 0x09, 0x38, // Usage (Wheel) 38 + +The mouse has also two physical positions (Usage (X), Usage (Y)) +and a wheel (Usage (Wheel)) :: + + # 0x15, 0x81, // Logical Minimum (-127) 40 + # 0x25, 0x7f, // Logical Maximum (127) 42 + +each of them can send values ranging from -127 up to including 127 :: + + # 0x75, 0x08, // Report Size (8) 44 + +which is represented by eight bits :: + + # 0x95, 0x03, // Report Count (3) 46 + +and there are three of those eight bits, matching X, Y and Wheel. :: + + # 0x81, 0x06, // Input (Data,Var,Rel) 48 + +This time the data values are Relative (Rel), i.e. they represent +the change from the previously sent report (event) :: + + # 0xc0, // End Collection 50 + # 0xc0, // End Collection 51 + # + R: 52 05 01 09 02 a1 01 09 01 a1 00 05 09 19 01 29 03 15 00 25 01 75 01 95 03 81 02 75 05 95 01 81 01 05 01 09 30 09 31 09 38 15 81 25 7f 75 08 95 03 81 06 c0 c0 + N: device 0:0 + I: 3 0001 0001 + + +This Report Descriptor tells us that the mouse input will be +transmitted using four bytes: the first one for the buttons (three +bits used, five for padding), the last three for the mouse X, Y and +wheel changes, respectively. + +Indeed, for any event, the mouse will send a *report* of four bytes. +We can check the values sent by resorting e.g. to the `hid-recorder` +tool, from `hid-tools <https://gitlab.freedesktop.org/libevdev/hid-tools>`_: +The sequence of bytes sent by clicking and releasing button 1, then button 2, then button 3 is:: + + $ sudo ./hid-recorder /dev/hidraw1 + + .... + output of hid-decode + .... + + # Button: 1 0 0 | # | X: 0 | Y: 0 | Wheel: 0 + E: 000000.000000 4 01 00 00 00 + # Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0 + E: 000000.183949 4 00 00 00 00 + # Button: 0 1 0 | # | X: 0 | Y: 0 | Wheel: 0 + E: 000001.959698 4 02 00 00 00 + # Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0 + E: 000002.103899 4 00 00 00 00 + # Button: 0 0 1 | # | X: 0 | Y: 0 | Wheel: 0 + E: 000004.855799 4 04 00 00 00 + # Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0 + E: 000005.103864 4 00 00 00 00 + +This example shows that when button 2 is clicked, +the bytes ``02 00 00 00`` are sent, and the immediately subsequent +event (``00 00 00 00``) is the release of button 2 (no buttons are +pressed, remember that the data values are *absolute*). + +If instead one clicks and holds button 1, then clicks and holds button +2, releases button 1, and finally releases button 2, the reports are:: + + # Button: 1 0 0 | # | X: 0 | Y: 0 | Wheel: 0 + E: 000044.175830 4 01 00 00 00 + # Button: 1 1 0 | # | X: 0 | Y: 0 | Wheel: 0 + E: 000045.975997 4 03 00 00 00 + # Button: 0 1 0 | # | X: 0 | Y: 0 | Wheel: 0 + E: 000047.407930 4 02 00 00 00 + # Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0 + E: 000049.199919 4 00 00 00 00 + +where with ``03 00 00 00`` both buttons are pressed, and with the +subsequent ``02 00 00 00`` button 1 is released while button 2 is still +active. + +Output, Input and Feature Reports +--------------------------------- + +HID devices can have Input Reports, like in the mouse example, Output +Reports, and Feature Reports. "Output" means that the information is +sent to the device. For example, a joystick with force feedback will +have some output; the led of a keyboard would need an output as well. +"Input" means that data come from the device. + +"Feature"s are not meant to be consumed by the end user and define +configuration options for the device. They can be queried from the host; +when declared as *Volatile* they should be changed by the host. + + +Collections, Report IDs and Evdev events +======================================== + +A single device can logically group data into different independent +sets, called a *Collection*. Collections can be nested and there are +different types of collections (see the HID spec 6.2.2.6 +"Collection, End Collection Items" for details). + +Different reports are identified by means of different *Report ID* +fields, i.e. a number identifying the structure of the immediately +following report. +Whenever a Report ID is needed it is transmitted as the first byte of +any report. A device with only one supported HID report (like the mouse +example above) may omit the report ID. + +Consider the following HID report descriptor:: + + 05 01 09 02 A1 01 85 01 05 09 19 01 29 05 15 00 + 25 01 95 05 75 01 81 02 95 01 75 03 81 01 05 01 + 09 30 09 31 16 00 F8 26 FF 07 75 0C 95 02 81 06 + 09 38 15 80 25 7F 75 08 95 01 81 06 05 0C 0A 38 + 02 15 80 25 7F 75 08 95 01 81 06 C0 05 01 09 02 + A1 01 85 02 05 09 19 01 29 05 15 00 25 01 95 05 + 75 01 81 02 95 01 75 03 81 01 05 01 09 30 09 31 + 16 00 F8 26 FF 07 75 0C 95 02 81 06 09 38 15 80 + 25 7F 75 08 95 01 81 06 05 0C 0A 38 02 15 80 25 + 7F 75 08 95 01 81 06 C0 05 01 09 07 A1 01 85 05 + 05 07 15 00 25 01 09 29 09 3E 09 4B 09 4E 09 E3 + 09 E8 09 E8 09 E8 75 01 95 08 81 02 95 00 81 01 + C0 05 0C 09 01 A1 01 85 06 15 00 25 01 75 01 95 + 01 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 81 + 06 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 81 + 06 C0 05 0C 09 01 A1 01 85 03 09 05 15 00 26 FF + 00 75 08 95 02 B1 02 C0 + +After parsing it (try to parse it on your own using the suggested +tools!) one can see that the device presents two ``Mouse`` Application +Collections (with reports identified by Reports IDs 1 and 2, +respectively), a ``Keypad`` Application Collection (whose report is +identified by the Report ID 5) and two ``Consumer Controls`` Application +Collections, (with Report IDs 6 and 3, respectively). Note, however, +that a device can have different Report IDs for the same Application +Collection. + +The data sent will begin with the Report ID byte, and will be followed +by the corresponding information. For example, the data transmitted for +the last consumer control:: + + 0x05, 0x0C, // Usage Page (Consumer) + 0x09, 0x01, // Usage (Consumer Control) + 0xA1, 0x01, // Collection (Application) + 0x85, 0x03, // Report ID (3) + 0x09, 0x05, // Usage (Headphone) + 0x15, 0x00, // Logical Minimum (0) + 0x26, 0xFF, 0x00, // Logical Maximum (255) + 0x75, 0x08, // Report Size (8) + 0x95, 0x02, // Report Count (2) + 0xB1, 0x02, // Feature (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile) + 0xC0, // End Collection + +will be of three bytes: the first for the Report ID (3), the next two +for the headphone, with two (``Report Count (2)``) bytes +(``Report Size (8)``), each ranging from 0 (``Logical Minimum (0)``) +to 255 (``Logical Maximum (255)``). + +All the Input data sent by the device should be translated into +corresponding Evdev events, so that the remaining part of the stack can +know what is going on, e.g. the bit for the first button translates into +the ``EV_KEY/BTN_LEFT`` evdev event and relative X movement translates +into the ``EV_REL/REL_X`` evdev event". + +Events +====== + +In Linux, one ``/dev/input/event*`` is created for each ``Application +Collection``. Going back to the mouse example, and repeating the +sequence where one clicks and holds button 1, then clicks and holds +button 2, releases button 1, and finally releases button 2, one gets:: + + $ sudo libinput record /dev/input/event1 + # libinput record + version: 1 + ndevices: 1 + libinput: + version: "1.23.0" + git: "unknown" + system: + os: "opensuse-tumbleweed:20230619" + kernel: "6.3.7-1-default" + dmi: "dmi:bvnHP:bvrU77Ver.01.05.00:bd03/24/2022:br5.0:efr20.29:svnHP:pnHPEliteBook64514inchG9NotebookPC:pvr:rvnHP:rn89D2:rvrKBCVersion14.1D.00:cvnHP:ct10:cvr:sku5Y3J1EA#ABZ:" + devices: + - node: /dev/input/event1 + evdev: + # Name: PixArt HP USB Optical Mouse + # ID: bus 0x3 vendor 0x3f0 product 0x94a version 0x111 + # Supported Events: + # Event type 0 (EV_SYN) + # Event type 1 (EV_KEY) + # Event code 272 (BTN_LEFT) + # Event code 273 (BTN_RIGHT) + # Event code 274 (BTN_MIDDLE) + # Event type 2 (EV_REL) + # Event code 0 (REL_X) + # Event code 1 (REL_Y) + # Event code 8 (REL_WHEEL) + # Event code 11 (REL_WHEEL_HI_RES) + # Event type 4 (EV_MSC) + # Event code 4 (MSC_SCAN) + # Properties: + name: "PixArt HP USB Optical Mouse" + id: [3, 1008, 2378, 273] + codes: + 0: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] # EV_SYN + 1: [272, 273, 274] # EV_KEY + 2: [0, 1, 8, 11] # EV_REL + 4: [4] # EV_MSC + properties: [] + hid: [ + 0x05, 0x01, 0x09, 0x02, 0xa1, 0x01, 0x09, 0x01, 0xa1, 0x00, 0x05, 0x09, 0x19, 0x01, 0x29, 0x03, + 0x15, 0x00, 0x25, 0x01, 0x95, 0x08, 0x75, 0x01, 0x81, 0x02, 0x05, 0x01, 0x09, 0x30, 0x09, 0x31, + 0x09, 0x38, 0x15, 0x81, 0x25, 0x7f, 0x75, 0x08, 0x95, 0x03, 0x81, 0x06, 0xc0, 0xc0 + ] + udev: + properties: + - ID_INPUT=1 + - ID_INPUT_MOUSE=1 + - LIBINPUT_DEVICE_GROUP=3/3f0/94a:usb-0000:05:00.3-2 + quirks: + events: + # Current time is 12:31:56 + - evdev: + - [ 0, 0, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) + - [ 0, 0, 1, 272, 1] # EV_KEY / BTN_LEFT 1 + - [ 0, 0, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +0ms + - evdev: + - [ 1, 207892, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) + - [ 1, 207892, 1, 273, 1] # EV_KEY / BTN_RIGHT 1 + - [ 1, 207892, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +1207ms + - evdev: + - [ 2, 367823, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) + - [ 2, 367823, 1, 272, 0] # EV_KEY / BTN_LEFT 0 + - [ 2, 367823, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +1160ms + # Current time is 12:32:00 + - evdev: + - [ 3, 247617, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) + - [ 3, 247617, 1, 273, 0] # EV_KEY / BTN_RIGHT 0 + - [ 3, 247617, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +880ms + +Note: if ``libinput record`` is not available on your system try using +``evemu-record``. + +When something does not work +============================ + +There can be a number of reasons why a device does not behave +correctly. For example + +* The HID report descriptor provided by the HID device may be wrong + because e.g. + + * it does not follow the standard, so that the kernel + will not able to make sense of the HID report descriptor; + * the HID report descriptor *does not match* what is actually + sent by the device (this can be verified by reading the raw HID + data); +* the HID report descriptor may need some "quirks" (see later on). + +As a consequence, a ``/dev/input/event*`` may not be created +for each Application Collection, and/or the events +there may not match what you would expect. + + +Quirks +------ + +There are some known peculiarities of HID devices that the kernel +knows how to fix - these are called the HID quirks and a list of those +is available in `include/linux/hid.h`. + +Should this be the case, it should be enough to add the required quirk +in the kernel, for the HID device at hand. This can be done in the file +`drivers/hid/hid-quirks.c`. How to do it should be relatively +straightforward after looking into the file. + +The list of currently defined quirks, from `include/linux/hid.h`, is + +.. kernel-doc:: include/linux/hid.h + :doc: HID quirks + +Quirks for USB devices can be specified while loading the usbhid module, +see ``modinfo usbhid``, although the proper fix should go into +hid-quirks.c and **be submitted upstream**. +See Documentation/process/submitting-patches.rst for guidelines on how +to submit a patch. Quirks for other busses need to go into hid-quirks.c. + +Fixing HID report descriptors +----------------------------- + +Should you need to patch HID report descriptors the easiest way is to +resort to eBPF, as described in Documentation/hid/hid-bpf.rst. + +Basically, you can change any byte of the original HID report +descriptor. The examples in samples/hid should be a good starting point +for your code, see e.g. `samples/hid/hid_mouse.bpf.c`:: + + SEC("fmod_ret/hid_bpf_rdesc_fixup") + int BPF_PROG(hid_rdesc_fixup, struct hid_bpf_ctx *hctx) + { + .... + data[39] = 0x31; + data[41] = 0x30; + return 0; + } + +Of course this can be also done within the kernel source code, see e.g. +`drivers/hid/hid-aureal.c` or `drivers/hid/hid-samsung.c` for a slightly +more complex file. + +Check Documentation/hid/hidreport-parsing.rst if you need any help +navigating the HID manuals and understanding the exact meaning of +the HID report descriptor hex numbers. + +Whatever solution you come up with, please remember to **submit the +fix to the HID maintainers**, so that it can be directly integrated in +the kernel and that particular HID device will start working for +everyone else. See Documentation/process/submitting-patches.rst for +guidelines on how to do this. + + +Modifying the transmitted data on the fly +----------------------------------------- + +Using eBPF it is also possible to modify the data exchanged with the +device. See again the examples in `samples/hid`. + +Again, **please post your fix**, so that it can be integrated in the +kernel! + +Writing a specialized driver +---------------------------- + +This should really be your last resort. + + +.. rubric:: Footnotes + +.. [#hidraw] read hidraw: see Documentation/hid/hidraw.rst and + file `samples/hidraw/hid-example.c` for an example. + The output of ``hid-example`` would be, for the same mouse:: + + $ sudo ./hid-example + Report Descriptor Size: 52 + Report Descriptor: + 5 1 9 2 a1 1 9 1 a1 0 5 9 19 1 29 3 15 0 25 1 75 1 95 3 81 2 75 5 95 1 81 1 5 1 9 30 9 31 9 38 15 81 25 7f 75 8 95 3 81 6 c0 c0 + + Raw Name: PixArt USB Optical Mouse + Raw Phys: usb-0000:05:00.4-2.3/input0 + Raw Info: + bustype: 3 (USB) + vendor: 0x093a + product: 0x2510 + ... diff --git a/Documentation/hid/hidreport-parsing.rst b/Documentation/hid/hidreport-parsing.rst new file mode 100644 index 000000000000..1d3c17f29f2b --- /dev/null +++ b/Documentation/hid/hidreport-parsing.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================== +Manual parsing of HID report descriptors +======================================== + +Consider again the mouse HID report descriptor +introduced in Documentation/hid/hidintro.rst:: + + $ hexdump -C /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor + 00000000 05 01 09 02 a1 01 09 01 a1 00 05 09 19 01 29 03 |..............).| + 00000010 15 00 25 01 75 01 95 03 81 02 75 05 95 01 81 01 |..%.u.....u.....| + 00000020 05 01 09 30 09 31 09 38 15 81 25 7f 75 08 95 03 |...0.1.8..%.u...| + 00000030 81 06 c0 c0 |....| + 00000034 + +and try to parse it by hand. + +Start with the first number, 0x05: it carries 2 bits for the +length of the item, 2 bits for the type of the item and 4 bits for the +function:: + + +----------+ + | 00000101 | + +----------+ + ^^ + ---- Length of data (see HID spec 6.2.2.2) + ^^ + ------ Type of the item (see HID spec 6.2.2.2, then jump to 6.2.2.7) + ^^^^ + --------- Function of the item (see HID spec 6.2.2.7, then HUT Sec 3) + +In our case, the length is 1 byte, the type is ``Global`` and the +function is ``Usage Page``, thus for parsing the value 0x01 in the second byte +we need to refer to HUT Sec 3. + +The second number is the actual data, and its meaning can be found in +the HUT. We have a ``Usage Page``, thus we need to refer to HUT +Sec. 3, "Usage Pages"; from there, one sees that ``0x01`` stands for +``Generic Desktop Page``. + +Moving now to the second two bytes, and following the same scheme, +``0x09`` (i.e. ``00001001``) will be followed by one byte (``01``) +and is a ``Local`` item (``10``). Thus, the meaning of the remaining four bits +(``0000``) is given in the HID spec Sec. 6.2.2.8 "Local Items", so that +we have a ``Usage``. From HUT, Sec. 4, "Generic Desktop Page", we see that +0x02 stands for ``Mouse``. + +The following numbers can be parsed in the same way. diff --git a/Documentation/hid/index.rst b/Documentation/hid/index.rst index b2028f382f11..af02cf7cfa82 100644 --- a/Documentation/hid/index.rst +++ b/Documentation/hid/index.rst @@ -7,6 +7,7 @@ Human Interface Devices (HID) .. toctree:: :maxdepth: 1 + hidintro hiddev hidraw hid-sensor diff --git a/Documentation/hwmon/adt7475.rst b/Documentation/hwmon/adt7475.rst index ef3ea1ea9bc1..f90f769d82d6 100644 --- a/Documentation/hwmon/adt7475.rst +++ b/Documentation/hwmon/adt7475.rst @@ -90,7 +90,7 @@ ADT7476: ADT7490: * 6 voltage inputs - * 1 Imon input (not implemented) + * 1 Imon input * PECI support (not implemented) * 2 GPIO pins (not implemented) * system acoustics optimizations (not implemented) @@ -107,6 +107,7 @@ in2 VCC (4) VCC (4) VCC (4) VCC (3) in3 5VIN (20) 5VIN (20) in4 12VIN (21) 12VIN (21) in5 VTT (8) +in6 Imon (19) ==== =========== =========== ========= ========== Special Features diff --git a/Documentation/hwmon/aquacomputer_d5next.rst b/Documentation/hwmon/aquacomputer_d5next.rst index 94dc2d93d180..cb073c79479c 100644 --- a/Documentation/hwmon/aquacomputer_d5next.rst +++ b/Documentation/hwmon/aquacomputer_d5next.rst @@ -16,6 +16,8 @@ Supported devices: * Aquacomputer Aquastream XT watercooling pump * Aquacomputer Aquastream Ultimate watercooling pump * Aquacomputer Poweradjust 3 fan controller +* Aquacomputer High Flow USB flow meter +* Aquacomputer MPS Flow devices Author: Aleksa Savic @@ -73,6 +75,11 @@ It also exposes pressure and flow speed readings. The Poweradjust 3 controller exposes a single external temperature sensor. +The High Flow USB exposes an internal and external temperature sensor, and a flow meter. + +The MPS Flow devices expose the same entries as the High Flow USB because they have +the same USB product ID and report sensors equivalently. + Depending on the device, not all sysfs and debugfs entries will be available. Writing to virtual temperature sensors is not currently supported. diff --git a/Documentation/hwmon/asus_ec_sensors.rst b/Documentation/hwmon/asus_ec_sensors.rst index 7e3cd5b6686f..0bf99ba406dd 100644 --- a/Documentation/hwmon/asus_ec_sensors.rst +++ b/Documentation/hwmon/asus_ec_sensors.rst @@ -15,6 +15,7 @@ Supported boards: * ROG CROSSHAIR VIII HERO * ROG CROSSHAIR VIII IMPACT * ROG CROSSHAIR X670E HERO + * ROG CROSSHAIR X670E GENE * ROG MAXIMUS XI HERO * ROG MAXIMUS XI HERO (WI-FI) * ROG STRIX B550-E GAMING diff --git a/Documentation/hwmon/hs3001.rst b/Documentation/hwmon/hs3001.rst new file mode 100644 index 000000000000..9f59dfc212d9 --- /dev/null +++ b/Documentation/hwmon/hs3001.rst @@ -0,0 +1,37 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver HS3001 +==================== + +Supported chips: + + * Renesas HS3001, HS3002, HS3003, HS3004 + + Prefix: 'hs3001' + + Addresses scanned: - + + Datasheet: https://www.renesas.com/us/en/document/dst/hs300x-datasheet?r=417401 + +Author: + + - Andre Werner <andre.werner@systec-electronic.com> + +Description +----------- + +This driver implements support for the Renesas HS3001 chips, a humidity +and temperature family. Temperature is measured in degrees celsius, relative +humidity is expressed as a percentage. In the sysfs interface, all values are +scaled by 1000, i.e. the value for 31.5 degrees celsius is 31500. + +The device communicates with the I2C protocol. Sensors have the I2C +address 0x44 by default. + +sysfs-Interface +--------------- + +=================== ================= +temp1_input: temperature input +humidity1_input: humidity input +=================== ================= diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index 042e1cf9501b..72f4e6065bae 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -78,6 +78,7 @@ Hardware Monitoring Kernel Drivers gxp-fan-ctrl hih6130 hp-wmi-sensors + hs3001 ibmaem ibm-cffps ibmpowernv @@ -120,6 +121,7 @@ Hardware Monitoring Kernel Drivers ltc2947 ltc2978 ltc2990 + ltc2991 ltc3815 ltc4151 ltc4215 @@ -177,6 +179,7 @@ Hardware Monitoring Kernel Drivers peci-cputemp peci-dimmtemp pmbus + powerz powr1220 pxe1610 pwm-fan @@ -195,7 +198,6 @@ Hardware Monitoring Kernel Drivers shtc1 sis5595 sl28cpld - smm665 smpro-hwmon smsc47b397 smsc47m192 diff --git a/Documentation/hwmon/ltc2991.rst b/Documentation/hwmon/ltc2991.rst new file mode 100644 index 000000000000..15d8b4d7e471 --- /dev/null +++ b/Documentation/hwmon/ltc2991.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver ltc2991 +===================== + +Supported chips: + + * Analog Devices LTC2991 + + Prefix: 'ltc2991' + + Addresses scanned: I2C 0x48 - 0x4f + + Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/2991ff.pdf + +Authors: + + - Antoniu Miclaus <antoniu.miclaus@analog.com> + + +Description +----------- + +This driver supports hardware monitoring for Analog Devices LTC2991 Octal I2C +Voltage, Current and Temperature Monitor. + +The LTC2991 is used to monitor system temperatures, voltages and currents. +Through the I2C serial interface, the eight monitors can individually measure +supply voltages and can be paired for differential measurements of current sense +resistors or temperature sensing transistors. Additional measurements include +internal temperatureand internal VCC. + + +sysfs-Interface +--------------- + +The following attributes are supported. Limits are read-only. + +=============== ================= +inX_input: voltage input +currX_input: current input +tempX_input: temperature input +=============== ================= diff --git a/Documentation/hwmon/max31827.rst b/Documentation/hwmon/max31827.rst index b0971d05b8a4..9a1055a007cf 100644 --- a/Documentation/hwmon/max31827.rst +++ b/Documentation/hwmon/max31827.rst @@ -73,8 +73,8 @@ the conversion frequency to 1 conv/s. The conversion time varies depending on the resolution. The conversion time doubles with every bit of increased resolution. For 10 bit resolution 35ms are needed, while for 12 bit resolution (default) 140ms. When chip is in shutdown mode and a read operation is -requested, one-shot is triggered, the device waits for 140 (conversion time) + 1 -(error) ms, and only after that is the temperature value register read. +requested, one-shot is triggered, the device waits for 140 (conversion time) ms, +and only after that is the temperature value register read. The LSB of the temperature values is 0.0625 degrees Celsius, but the values of the temperatures are displayed in milli-degrees. This means, that some data is diff --git a/Documentation/hwmon/nct6683.rst b/Documentation/hwmon/nct6683.rst index 2e1408d174bd..3e7f6ee779c2 100644 --- a/Documentation/hwmon/nct6683.rst +++ b/Documentation/hwmon/nct6683.rst @@ -62,5 +62,6 @@ Intel DH87RL NCT6683D EC firmware version 1.0 build 04/03/13 Intel DH87MC NCT6683D EC firmware version 1.0 build 04/03/13 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 =============== =============================================== diff --git a/Documentation/hwmon/nct6775.rst b/Documentation/hwmon/nct6775.rst index 5ba8276aad4b..9d7a10de61a7 100644 --- a/Documentation/hwmon/nct6775.rst +++ b/Documentation/hwmon/nct6775.rst @@ -80,7 +80,13 @@ Supported chips: Datasheet: Available from Nuvoton upon request + * Nuvoton NCT6796D-S/NCT6799D-R + Prefix: 'nct6799' + + Addresses scanned: ISA address retrieved from Super I/O registers + + Datasheet: Available from Nuvoton upon request Authors: @@ -277,4 +283,7 @@ will not reflect a usable value. It often reports unreasonably high temperatures, and in some cases the reported temperature declines if the actual temperature increases (similar to the raw PECI temperature value - see PECI specification for details). CPUTIN should therefore be ignored on ASUS -boards. The CPU temperature on ASUS boards is reported from PECI 0. +boards. The CPU temperature on ASUS boards is reported from PECI 0 or TSI 0. + +NCT6796D-S and NCT6799D-R chips are very similar and their chip_id indicates +they are different versions. This driver treats them the same way. diff --git a/Documentation/hwmon/pmbus-core.rst b/Documentation/hwmon/pmbus-core.rst index cff93adf6e42..1eaf2b015837 100644 --- a/Documentation/hwmon/pmbus-core.rst +++ b/Documentation/hwmon/pmbus-core.rst @@ -345,7 +345,7 @@ PMBUS_NO_CAPABILITY Some PMBus chips don't respond with valid data when reading the CAPABILITY register. For such chips, this flag should be set so that the PMBus core -driver doesn't use CAPABILITY to determine it's behavior. +driver doesn't use CAPABILITY to determine its behavior. PMBUS_READ_STATUS_AFTER_FAILED_CHECK diff --git a/Documentation/hwmon/pmbus.rst b/Documentation/hwmon/pmbus.rst index 7ecfec6ca2db..eb1569bfa676 100644 --- a/Documentation/hwmon/pmbus.rst +++ b/Documentation/hwmon/pmbus.rst @@ -163,7 +163,7 @@ Emerson DS1200 power modules might look as follows:: .driver = { .name = "ds1200", }, - .probe_new = ds1200_probe, + .probe = ds1200_probe, .id_table = ds1200_id, }; diff --git a/Documentation/hwmon/powerz.rst b/Documentation/hwmon/powerz.rst new file mode 100644 index 000000000000..317084e0b76b --- /dev/null +++ b/Documentation/hwmon/powerz.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver POWERZ +==================== + +Supported chips: + + * ChargerLAB POWER-Z KM003C + + Prefix: 'powerz' + + Addresses scanned: - + +Author: + + - Thomas Weißschuh <linux@weissschuh.net> + +Description +----------- + +This driver implements support for the ChargerLAB POWER-Z USB-C power testing +family. + +The device communicates with the custom protocol over USB. + +The channel labels exposed via hwmon match the labels used by the on-device +display and the official POWER-Z PC software. + +As current can flow in both directions through the tester the sign of the +channel "curr1_input" (label "IBUS") indicates the direction. diff --git a/Documentation/hwmon/sch5627.rst b/Documentation/hwmon/sch5627.rst index ecb4fc84d045..8639dff234fc 100644 --- a/Documentation/hwmon/sch5627.rst +++ b/Documentation/hwmon/sch5627.rst @@ -33,3 +33,13 @@ The hardware monitoring part of the SMSC SCH5627 is accessed by talking through an embedded microcontroller. An application note describing the protocol for communicating with the microcontroller is available upon request. Please mail me if you want a copy. + + +Controlling fan speed +--------------------- + +The SCH5627 allows for partially controlling the fan speed. If a temperature +channel excedes tempX_max, all fans are forced to maximum speed. The same is not +true for tempX_crit, presumably some other measures to cool down the system are +take in this case. +In which way the value of fanX_min affects the fan speed is currently unknown. diff --git a/Documentation/hwmon/smm665.rst b/Documentation/hwmon/smm665.rst deleted file mode 100644 index 481e69d8bf39..000000000000 --- a/Documentation/hwmon/smm665.rst +++ /dev/null @@ -1,187 +0,0 @@ -Kernel driver smm665 -==================== - -Supported chips: - - * Summit Microelectronics SMM465 - - Prefix: 'smm465' - - Addresses scanned: - - - Datasheet: - - http://www.summitmicro.com/prod_select/summary/SMM465/SMM465DS.pdf - - * Summit Microelectronics SMM665, SMM665B - - Prefix: 'smm665' - - Addresses scanned: - - - Datasheet: - - http://www.summitmicro.com/prod_select/summary/SMM665/SMM665B_2089_20.pdf - - * Summit Microelectronics SMM665C - - Prefix: 'smm665c' - - Addresses scanned: - - - Datasheet: - - http://www.summitmicro.com/prod_select/summary/SMM665C/SMM665C_2125.pdf - - * Summit Microelectronics SMM764 - - Prefix: 'smm764' - - Addresses scanned: - - - Datasheet: - - http://www.summitmicro.com/prod_select/summary/SMM764/SMM764_2098.pdf - - * Summit Microelectronics SMM766, SMM766B - - Prefix: 'smm766' - - Addresses scanned: - - - Datasheets: - - http://www.summitmicro.com/prod_select/summary/SMM766/SMM766_2086.pdf - - http://www.summitmicro.com/prod_select/summary/SMM766B/SMM766B_2122.pdf - -Author: Guenter Roeck <linux@roeck-us.net> - - -Module Parameters ------------------ - -* vref: int - Default: 1250 (mV) - - Reference voltage on VREF_ADC pin in mV. It should not be necessary to set - this parameter unless a non-default reference voltage is used. - - -Description ------------ - -[From datasheet] The SMM665 is an Active DC Output power supply Controller -that monitors, margins and cascade sequences power. The part monitors six -power supply channels as well as VDD, 12V input, two general-purpose analog -inputs and an internal temperature sensor using a 10-bit ADC. - -Each monitored channel has its own high and low limits, plus a critical -limit. - -Support for SMM465, SMM764, and SMM766 has been implemented but is untested. - - -Usage Notes ------------ - -This driver does not probe for devices, since there is no register which -can be safely used to identify the chip. You will have to instantiate -the devices explicitly. When instantiating the device, you have to specify -its configuration register address. - -Example: the following will load the driver for an SMM665 at address 0x57 -on I2C bus #1:: - - $ modprobe smm665 - $ echo smm665 0x57 > /sys/bus/i2c/devices/i2c-1/new_device - - -Sysfs entries -------------- - -This driver uses the values in the datasheet to convert ADC register values -into the values specified in the sysfs-interface document. All attributes are -read only. - -Min, max, lcrit, and crit values are used by the chip to trigger external signals -and/or other activity. Triggered signals can include HEALTHY, RST, Power Off, -or Fault depending on the chip configuration. The driver reports values as lcrit -or crit if exceeding the limits triggers RST, Power Off, or Fault, and as min or -max otherwise. For details please see the SMM665 datasheet. - -For SMM465 and SMM764, values for Channel E and F are reported but undefined. - -======================= ======================================================= -in1_input 12V input voltage (mV) -in2_input 3.3V (VDD) input voltage (mV) -in3_input Channel A voltage (mV) -in4_input Channel B voltage (mV) -in5_input Channel C voltage (mV) -in6_input Channel D voltage (mV) -in7_input Channel E voltage (mV) -in8_input Channel F voltage (mV) -in9_input AIN1 voltage (mV) -in10_input AIN2 voltage (mV) - -in1_min 12v input minimum voltage (mV) -in2_min 3.3V (VDD) input minimum voltage (mV) -in3_min Channel A minimum voltage (mV) -in4_min Channel B minimum voltage (mV) -in5_min Channel C minimum voltage (mV) -in6_min Channel D minimum voltage (mV) -in7_min Channel E minimum voltage (mV) -in8_min Channel F minimum voltage (mV) -in9_min AIN1 minimum voltage (mV) -in10_min AIN2 minimum voltage (mV) - -in1_max 12v input maximum voltage (mV) -in2_max 3.3V (VDD) input maximum voltage (mV) -in3_max Channel A maximum voltage (mV) -in4_max Channel B maximum voltage (mV) -in5_max Channel C maximum voltage (mV) -in6_max Channel D maximum voltage (mV) -in7_max Channel E maximum voltage (mV) -in8_max Channel F maximum voltage (mV) -in9_max AIN1 maximum voltage (mV) -in10_max AIN2 maximum voltage (mV) - -in1_lcrit 12v input critical minimum voltage (mV) -in2_lcrit 3.3V (VDD) input critical minimum voltage (mV) -in3_lcrit Channel A critical minimum voltage (mV) -in4_lcrit Channel B critical minimum voltage (mV) -in5_lcrit Channel C critical minimum voltage (mV) -in6_lcrit Channel D critical minimum voltage (mV) -in7_lcrit Channel E critical minimum voltage (mV) -in8_lcrit Channel F critical minimum voltage (mV) -in9_lcrit AIN1 critical minimum voltage (mV) -in10_lcrit AIN2 critical minimum voltage (mV) - -in1_crit 12v input critical maximum voltage (mV) -in2_crit 3.3V (VDD) input critical maximum voltage (mV) -in3_crit Channel A critical maximum voltage (mV) -in4_crit Channel B critical maximum voltage (mV) -in5_crit Channel C critical maximum voltage (mV) -in6_crit Channel D critical maximum voltage (mV) -in7_crit Channel E critical maximum voltage (mV) -in8_crit Channel F critical maximum voltage (mV) -in9_crit AIN1 critical maximum voltage (mV) -in10_crit AIN2 critical maximum voltage (mV) - -in1_crit_alarm 12v input critical alarm -in2_crit_alarm 3.3V (VDD) input critical alarm -in3_crit_alarm Channel A critical alarm -in4_crit_alarm Channel B critical alarm -in5_crit_alarm Channel C critical alarm -in6_crit_alarm Channel D critical alarm -in7_crit_alarm Channel E critical alarm -in8_crit_alarm Channel F critical alarm -in9_crit_alarm AIN1 critical alarm -in10_crit_alarm AIN2 critical alarm - -temp1_input Chip temperature -temp1_min Minimum chip temperature -temp1_max Maximum chip temperature -temp1_crit Critical chip temperature -temp1_crit_alarm Temperature critical alarm -======================= ======================================================= diff --git a/Documentation/i2c/i2c-address-translators.rst b/Documentation/i2c/i2c-address-translators.rst new file mode 100644 index 000000000000..b22ce9f41ecf --- /dev/null +++ b/Documentation/i2c/i2c-address-translators.rst @@ -0,0 +1,96 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================= +I2C Address Translators +======================= + +Author: Luca Ceresoli <luca@lucaceresoli.net> +Author: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com> + +Description +----------- + +An I2C Address Translator (ATR) is a device with an I2C slave parent +("upstream") port and N I2C master child ("downstream") ports, and +forwards transactions from upstream to the appropriate downstream port +with a modified slave address. The address used on the parent bus is +called the "alias" and is (potentially) different from the physical +slave address of the child bus. Address translation is done by the +hardware. + +An ATR looks similar to an i2c-mux except: + - the address on the parent and child busses can be different + - there is normally no need to select the child port; the alias used on the + parent bus implies it + +The ATR functionality can be provided by a chip with many other features. +The kernel i2c-atr provides a helper to implement an ATR within a driver. + +The ATR creates a new I2C "child" adapter on each child bus. Adding +devices on the child bus ends up in invoking the driver code to select +an available alias. Maintaining an appropriate pool of available aliases +and picking one for each new device is up to the driver implementer. The +ATR maintains a table of currently assigned alias and uses it to modify +all I2C transactions directed to devices on the child buses. + +A typical example follows. + +Topology:: + + Slave X @ 0x10 + .-----. | + .-----. | |---+---- B + | CPU |--A--| ATR | + `-----' | |---+---- C + `-----' | + Slave Y @ 0x10 + +Alias table: + +A, B and C are three physical I2C busses, electrically independent from +each other. The ATR receives the transactions initiated on bus A and +propagates them on bus B or bus C or none depending on the device address +in the transaction and based on the alias table. + +Alias table: + +.. table:: + + =============== ===== + Client Alias + =============== ===== + X (bus B, 0x10) 0x20 + Y (bus C, 0x10) 0x30 + =============== ===== + +Transaction: + + - Slave X driver requests a transaction (on adapter B), slave address 0x10 + - ATR driver finds slave X is on bus B and has alias 0x20, rewrites + messages with address 0x20, forwards to adapter A + - Physical I2C transaction on bus A, slave address 0x20 + - ATR chip detects transaction on address 0x20, finds it in table, + propagates transaction on bus B with address translated to 0x10, + keeps clock streched on bus A waiting for reply + - Slave X chip (on bus B) detects transaction at its own physical + address 0x10 and replies normally + - ATR chip stops clock stretching and forwards reply on bus A, + with address translated back to 0x20 + - ATR driver receives the reply, rewrites messages with address 0x10 + as they were initially + - Slave X driver gets back the msgs[], with reply and address 0x10 + +Usage: + + 1. In the driver (typically in the probe function) add an ATR by + calling i2c_atr_new() passing attach/detach callbacks + 2. When the attach callback is called pick an appropriate alias, + configure it in the chip and return the chosen alias in the + alias_id parameter + 3. When the detach callback is called, deconfigure the alias from + the chip and put the alias back in the pool for later usage + +I2C ATR functions and data structures +------------------------------------- + +.. kernel-doc:: include/linux/i2c-atr.h diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst index 6270f1fd7d4e..2b213d4ce89c 100644 --- a/Documentation/i2c/index.rst +++ b/Documentation/i2c/index.rst @@ -18,6 +18,7 @@ Introduction i2c-topology muxes/i2c-mux-gpio i2c-sysfs + i2c-address-translators Writing device drivers ====================== diff --git a/Documentation/i2c/writing-clients.rst b/Documentation/i2c/writing-clients.rst index b7d3ae7458f8..41ddc10f1ac7 100644 --- a/Documentation/i2c/writing-clients.rst +++ b/Documentation/i2c/writing-clients.rst @@ -46,7 +46,7 @@ driver model device node, and its I2C address. }, .id_table = foo_idtable, - .probe_new = foo_probe, + .probe = foo_probe, .remove = foo_remove, /* if device autodetection is needed: */ .class = I2C_CLASS_SOMETHING, diff --git a/Documentation/input/devices/iforce-protocol.rst b/Documentation/input/devices/iforce-protocol.rst index 8634beac3fdb..52c1e0dd0ab7 100644 --- a/Documentation/input/devices/iforce-protocol.rst +++ b/Documentation/input/devices/iforce-protocol.rst @@ -49,7 +49,7 @@ OP DATA == ==== The 2B, LEN and CS fields have disappeared, probably because USB handles -frames and data corruption is handled or unsignificant. +frames and data corruption is handled or insignificant. First, I describe effects that are sent by the device to the computer diff --git a/Documentation/input/devices/pxrc.rst b/Documentation/input/devices/pxrc.rst index ca11f646bae8..5a86df4ad079 100644 --- a/Documentation/input/devices/pxrc.rst +++ b/Documentation/input/devices/pxrc.rst @@ -5,7 +5,7 @@ pxrc - PhoenixRC Flight Controller Adapter :Author: Marcus Folkesson <marcus.folkesson@gmail.com> This driver let you use your own RC controller plugged into the -adapter that comes with PhoenixRC [1]_ or other compatible adapters. +adapter that comes with PhoenixRC or other compatible adapters. The adapter supports 7 analog channels and 1 digital input switch. @@ -41,7 +41,7 @@ Manual Testing ============== To test this driver's functionality you may use `input-event` which is part of -the `input layer utilities` suite [2]_. +the `input layer utilities` suite [1]_. For example:: @@ -53,5 +53,4 @@ To print all input events from input `devnr`. References ========== -.. [1] http://www.phoenix-sim.com/ -.. [2] https://www.kraxel.org/cgit/input/ +.. [1] https://www.kraxel.org/cgit/input/ diff --git a/Documentation/input/multi-touch-protocol.rst b/Documentation/input/multi-touch-protocol.rst index 1085cbee4ee7..47d3dcb5d44b 100644 --- a/Documentation/input/multi-touch-protocol.rst +++ b/Documentation/input/multi-touch-protocol.rst @@ -383,7 +383,7 @@ Finger Tracking --------------- The process of finger tracking, i.e., to assign a unique trackingID to each -initiated contact on the surface, is a Euclidian Bipartite Matching +initiated contact on the surface, is a Euclidean Bipartite Matching problem. At each event synchronization, the set of actual contacts is matched to the set of contacts from the previous synchronization. A full implementation can be found in [#f3]_. diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst index 858ed5d80def..0135905c0aa3 100644 --- a/Documentation/kbuild/kconfig-language.rst +++ b/Documentation/kbuild/kconfig-language.rst @@ -573,6 +573,32 @@ above, leading to: bool "Support for foo hardware" depends on ARCH_FOO_VENDOR || COMPILE_TEST +Optional dependencies +~~~~~~~~~~~~~~~~~~~~~ + +Some drivers are able to optionally use a feature from another module +or build cleanly with that module disabled, but cause a link failure +when trying to use that loadable module from a built-in driver. + +The most common way to express this optional dependency in Kconfig logic +uses the slightly counterintuitive:: + + config FOO + tristate "Support for foo hardware" + depends on BAR || !BAR + +This means that there is either a dependency on BAR that disallows +the combination of FOO=y with BAR=m, or BAR is completely disabled. +For a more formalized approach if there are multiple drivers that have +the same dependency, a helper symbol can be used, like:: + + config FOO + tristate "Support for foo hardware" + depends on BAR_OPTIONAL + + config BAR_OPTIONAL + def_tristate BAR || !BAR + Kconfig recursive dependency limitations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/kbuild/kconfig.rst b/Documentation/kbuild/kconfig.rst index 5967c79c3baa..c946eb44bd13 100644 --- a/Documentation/kbuild/kconfig.rst +++ b/Documentation/kbuild/kconfig.rst @@ -10,6 +10,8 @@ The xconfig ('qconf'), menuconfig ('mconf'), and nconfig ('nconf') programs also have embedded help text. Be sure to check that for navigation, search, and other general help text. +The gconfig ('gconf') program has limited help text. + General ------- @@ -54,6 +56,15 @@ KCONFIG_OVERWRITECONFIG If you set KCONFIG_OVERWRITECONFIG in the environment, Kconfig will not break symlinks when .config is a symlink to somewhere else. +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. + `CONFIG_` --------- If you set `CONFIG_` in the environment, Kconfig will prefix all symbols @@ -210,6 +221,10 @@ Searching in menuconfig: 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. + ---------------------------------------------------------------------- User interface options for 'menuconfig' @@ -262,6 +277,10 @@ Searching in nconfig: 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. + NCONFIG_MODE ------------ This mode shows all sub-menus in one large tree. diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst index c3851fe1900d..b1d97fafddcf 100644 --- a/Documentation/kbuild/llvm.rst +++ b/Documentation/kbuild/llvm.rst @@ -25,50 +25,38 @@ objects <https://www.aosabook.org/en/llvm.html>`_. Clang is a front-end to LLVM that supports C and the GNU C extensions required by the kernel, and is pronounced "klang," not "see-lang." -Clang ------ - -The compiler used can be swapped out via ``CC=`` command line argument to ``make``. -``CC=`` should be set when selecting a config and during a build. :: - - make CC=clang defconfig - - make CC=clang +Building with LLVM +------------------ -Cross Compiling ---------------- +Invoke ``make`` via:: -A single Clang compiler binary will typically contain all supported backends, -which can help simplify cross compiling. :: - - make ARCH=arm64 CC=clang CROSS_COMPILE=aarch64-linux-gnu- + make LLVM=1 -``CROSS_COMPILE`` is not used to prefix the Clang compiler binary, instead -``CROSS_COMPILE`` is used to set a command line flag: ``--target=<triple>``. For -example: :: +to compile for the host target. For cross compiling:: - clang --target=aarch64-linux-gnu foo.c + make LLVM=1 ARCH=arm64 -LLVM Utilities --------------- +The LLVM= argument +------------------ -LLVM has substitutes for GNU binutils utilities. They can be enabled individually. -The full list of supported make variables:: +LLVM has substitutes for GNU binutils utilities. They can be enabled +individually. The full list of supported make variables:: make CC=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \ OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump READELF=llvm-readelf \ HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar HOSTLD=ld.lld -To simplify the above command, Kbuild supports the ``LLVM`` variable:: - - make LLVM=1 +``LLVM=1`` expands to the above. If your LLVM tools are not available in your PATH, you can supply their location using the LLVM variable with a trailing slash:: make LLVM=/path/to/llvm/ -which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc. +which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc. The +following may also be used:: + + PATH=/path/to/llvm:$PATH make LLVM=1 If your LLVM tools have a version suffix and you want to test with that explicit version rather than the unsuffixed executables like ``LLVM=1``, you @@ -78,31 +66,72 @@ can pass the suffix using the ``LLVM`` variable:: which will use ``clang-14``, ``ld.lld-14``, etc. +To support combinations of out of tree paths with version suffixes, we +recommend:: + + PATH=/path/to/llvm/:$PATH make LLVM=-14 + ``LLVM=0`` is not the same as omitting ``LLVM`` altogether, it will behave like -``LLVM=1``. If you only wish to use certain LLVM utilities, use their respective -make variables. +``LLVM=1``. If you only wish to use certain LLVM utilities, use their +respective make variables. + +The same value used for ``LLVM=`` should be set for each invocation of ``make`` +if configuring and building via distinct commands. ``LLVM=`` should also be set +as an environment variable when running scripts that will eventually run +``make``. -The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to -disable it. +Cross Compiling +--------------- -Omitting CROSS_COMPILE +A single Clang compiler binary (and corresponding LLVM utilities) will +typically contain all supported back ends, which can help simplify cross +compiling especially when ``LLVM=1`` is used. If you use only LLVM tools, +``CROSS_COMPILE`` or target-triple-prefixes become unnecessary. Example:: + + make LLVM=1 ARCH=arm64 + +As an example of mixing LLVM and GNU utilities, for a target like ``ARCH=s390`` +which does not yet have ``ld.lld`` or ``llvm-objcopy`` support, you could +invoke ``make`` via:: + + make LLVM=1 ARCH=s390 LD=s390x-linux-gnu-ld.bfd \ + OBJCOPY=s390x-linux-gnu-objcopy + +This example will invoke ``s390x-linux-gnu-ld.bfd`` as the linker and +``s390x-linux-gnu-objcopy``, so ensure those are reachable in your ``$PATH``. + +``CROSS_COMPILE`` is not used to prefix the Clang compiler binary (or +corresponding LLVM utilities) as is the case for GNU utilities when ``LLVM=1`` +is not set. + +The LLVM_IAS= argument ---------------------- -As explained above, ``CROSS_COMPILE`` is used to set ``--target=<triple>``. +Clang can assemble assembler code. You can pass ``LLVM_IAS=0`` to disable this +behavior and have Clang invoke the corresponding non-integrated assembler +instead. Example:: + + make LLVM=1 LLVM_IAS=0 + +``CROSS_COMPILE`` is necessary when cross compiling and ``LLVM_IAS=0`` +is used in order to set ``--prefix=`` for the compiler to find the +corresponding non-integrated assembler (typically, you don't want to use the +system assembler when targeting another architecture). Example:: -If ``CROSS_COMPILE`` is not specified, the ``--target=<triple>`` is inferred -from ``ARCH``. + make LLVM=1 ARCH=arm LLVM_IAS=0 CROSS_COMPILE=arm-linux-gnueabi- -That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessary. -For example, to cross-compile the arm64 kernel:: +Ccache +------ - make ARCH=arm64 LLVM=1 +``ccache`` can be used with ``clang`` to improve subsequent builds, (though +KBUILD_BUILD_TIMESTAMP_ should be set to a deterministic value between builds +in order to avoid 100% cache misses, see Reproducible_builds_ for more info): -If ``LLVM_IAS=0`` is specified, ``CROSS_COMPILE`` is also used to derive -``--prefix=<path>`` to search for the GNU assembler and linker. :: + KBUILD_BUILD_TIMESTAMP='' make LLVM=1 CC="ccache clang" - make ARCH=arm64 LLVM=1 LLVM_IAS=0 CROSS_COMPILE=aarch64-linux-gnu- +.. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp +.. _Reproducible_builds: reproducible-builds.html#timestamps Supported Architectures ----------------------- @@ -135,14 +164,17 @@ yet. Bug reports are always welcome at the issue tracker below! * - hexagon - Maintained - ``LLVM=1`` + * - loongarch + - Maintained + - ``LLVM=1`` * - mips - Maintained - ``LLVM=1`` * - powerpc - Maintained - - ``CC=clang`` + - ``LLVM=1`` * - riscv - - Maintained + - Supported - ``LLVM=1`` * - s390 - Maintained @@ -171,7 +203,11 @@ Getting Help Getting LLVM ------------- -We provide prebuilt stable versions of LLVM on `kernel.org <https://kernel.org/pub/tools/llvm/>`_. +We provide prebuilt stable versions of LLVM on `kernel.org +<https://kernel.org/pub/tools/llvm/>`_. These have been optimized with profile +data for building Linux kernels, which should improve kernel build times +relative to other distributions of LLVM. + Below are links that may be useful for building LLVM from source or procuring it through a distribution's package manager. diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index e67eb261c9b0..47a29a36b12b 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -53,7 +53,7 @@ knowledge about the kernel Makefiles, plus detailed knowledge about the public interface for kbuild. *Arch developers* are people who work on an entire architecture, such -as sparc or ia64. Arch developers need to know about the arch Makefile +as sparc or x86. Arch developers need to know about the arch Makefile as well as kbuild Makefiles. *Kbuild developers* are people who work on the kernel build system itself. diff --git a/Documentation/livepatch/reliable-stacktrace.rst b/Documentation/livepatch/reliable-stacktrace.rst index d56bb706172f..8d950f3ffedd 100644 --- a/Documentation/livepatch/reliable-stacktrace.rst +++ b/Documentation/livepatch/reliable-stacktrace.rst @@ -40,7 +40,7 @@ Principally, the reliable stacktrace function must ensure that either: .. note:: In some cases it is legitimate to omit specific functions from the trace, but all other functions must be reported. These cases are described in - futher detail below. + further detail below. Secondly, the reliable stacktrace function must be robust to cases where the stack or other unwind state is corrupt or otherwise unreliable. The diff --git a/Documentation/locking/lockdep-design.rst b/Documentation/locking/lockdep-design.rst index 82f36cab61bd..56b90eea2731 100644 --- a/Documentation/locking/lockdep-design.rst +++ b/Documentation/locking/lockdep-design.rst @@ -29,7 +29,7 @@ the validator will shoot a splat if incorrect. A lock-class's behavior is constructed by its instances collectively: when the first instance of a lock-class is used after bootup the class gets registered, then all (subsequent) instances will be mapped to the -class and hence their usages and dependecies will contribute to those of +class and hence their usages and dependencies will contribute to those of the class. A lock-class does not go away when a lock instance does, but it can be removed if the memory space of the lock class (static or dynamic) is reclaimed, this happens for example when a module is @@ -105,7 +105,7 @@ exact case is for the lock as of the reporting time. +--------------+-------------+--------------+ The character '-' suggests irq is disabled because if otherwise the -charactor '?' would have been shown instead. Similar deduction can be +character '?' would have been shown instead. Similar deduction can be applied for '+' too. Unused locks (e.g., mutexes) cannot be part of the cause of an error. diff --git a/Documentation/locking/locktorture.rst b/Documentation/locking/locktorture.rst index 7f56fc0d7c31..3e763f77a620 100644 --- a/Documentation/locking/locktorture.rst +++ b/Documentation/locking/locktorture.rst @@ -113,7 +113,7 @@ stutter without pausing. shuffle_interval - The number of seconds to keep the test threads affinitied + The number of seconds to keep the test threads affinitized to a particular subset of the CPUs, defaults to 3 seconds. Used in conjunction with test_no_idle_hz. diff --git a/Documentation/locking/locktypes.rst b/Documentation/locking/locktypes.rst index 9933faad4771..80c914f6eae7 100644 --- a/Documentation/locking/locktypes.rst +++ b/Documentation/locking/locktypes.rst @@ -500,7 +500,7 @@ caveats also apply to bit spinlocks. Some bit spinlocks are replaced with regular spinlock_t for PREEMPT_RT using conditional (#ifdef'ed) code changes at the usage site. In contrast, usage-site changes are not needed for the spinlock_t substitution. -Instead, conditionals in header files and the core locking implemementation +Instead, conditionals in header files and the core locking implementation enable the compiler to do the substitution transparently. diff --git a/Documentation/maintainer/configure-git.rst b/Documentation/maintainer/configure-git.rst index ec0ddfb9cdd3..0a36831814ea 100644 --- a/Documentation/maintainer/configure-git.rst +++ b/Documentation/maintainer/configure-git.rst @@ -1,35 +1,31 @@ -.. _configuregit: - -Configure Git -============= +Configuring Git +=============== This chapter describes maintainer level git configuration. -Tagged branches used in :ref:`Documentation/maintainer/pull-requests.rst -<pullrequests>` should be signed with the developers public GPG key. Signed -tags can be created by passing the ``-u`` flag to ``git tag``. However, -since you would *usually* use the same key for the same project, you can -set it once with -:: +Tagged branches used in pull requests (see +Documentation/maintainer/pull-requests.rst) should be signed with the +developers public GPG key. Signed tags can be created by passing +``-u <key-id>`` to ``git tag``. However, since you would *usually* use the same +key for the project, you can set it in the configuration and use the ``-s`` +flag. To set the default ``key-id`` use:: git config user.signingkey "keyname" -Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand: -:: +Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand:: [user] name = Jane Developer email = jd@domain.org signingkey = jd@domain.org -You may need to tell ``git`` to use ``gpg2`` -:: +You may need to tell ``git`` to use ``gpg2``:: [gpg] program = /path/to/gpg2 -You may also like to tell ``gpg`` which ``tty`` to use (add to your shell rc file) -:: +You may also like to tell ``gpg`` which ``tty`` to use (add to your shell +rc file):: export GPG_TTY=$(tty) @@ -37,20 +33,18 @@ You may also like to tell ``gpg`` which ``tty`` to use (add to your shell rc fil Creating commit links to lore.kernel.org ---------------------------------------- -The web site http://lore.kernel.org is meant as a grand archive of all mail +The web site https://lore.kernel.org is meant as a grand archive of all mail list traffic concerning or influencing the kernel development. Storing archives of patches here is a recommended practice, and when a maintainer applies a patch to a subsystem tree, it is a good idea to provide a Link: tag with a reference back to the lore archive so that people that browse the commit history can find related discussions and rationale behind a certain change. -The link tag will look like this: +The link tag will look like this:: Link: https://lore.kernel.org/r/<message-id> This can be configured to happen automatically any time you issue ``git am`` -by adding the following hook into your git: - -.. code-block:: none +by adding the following hook into your git:: $ git config am.messageid true $ cat >.git/hooks/applypatch-msg <<'EOF' diff --git a/Documentation/maintainer/feature-and-driver-maintainers.rst b/Documentation/maintainer/feature-and-driver-maintainers.rst new file mode 100644 index 000000000000..f04cc183e1de --- /dev/null +++ b/Documentation/maintainer/feature-and-driver-maintainers.rst @@ -0,0 +1,155 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== +Feature and driver maintainers +============================== + +The term "maintainer" spans a very wide range of levels of engagement +from people handling patches and pull requests as almost a full time job +to people responsible for a small feature or a driver. + +Unlike most of the chapter, this section is meant for the latter (more +populous) group. It provides tips and describes the expectations and +responsibilities of maintainers of a small(ish) section of the code. + +Drivers and alike most often do not have their own mailing lists and +git trees but instead send and review patches on the list of a larger +subsystem. + +Responsibilities +================ + +The amount of maintenance work is usually proportional to the size +and popularity of the code base. Small features and drivers should +require relatively small amount of care and feeding. Nonetheless +when the work does arrive (in form of patches which need review, +user bug reports etc.) it has to be acted upon promptly. +Even when a particular driver only sees one patch a month, or a quarter, +a subsystem could well have a hundred such drivers. Subsystem +maintainers cannot afford to wait a long time to hear from reviewers. + +The exact expectations on the response time will vary by subsystem. +The patch review SLA the subsystem had set for itself can sometimes +be found in the subsystem documentation. Failing that as a rule of thumb +reviewers should try to respond quicker than what is the usual patch +review delay of the subsystem maintainer. The resulting expectations +may range from two working days for fast-paced subsystems (e.g. networking) +to as long as a few weeks in slower moving parts of the kernel. + +Mailing list participation +-------------------------- + +Linux kernel uses mailing lists as the primary form of communication. +Maintainers must be subscribed and follow the appropriate subsystem-wide +mailing list. Either by subscribing to the whole list or using more +modern, selective setup like +`lei <https://people.kernel.org/monsieuricon/lore-lei-part-1-getting-started>`_. + +Maintainers must know how to communicate on the list (plain text, no invasive +legal footers, no top posting, etc.) + +Reviews +------- + +Maintainers must review *all* patches touching exclusively their drivers, +no matter how trivial. If the patch is a tree wide change and modifies +multiple drivers - whether to provide a review is left to the maintainer. + +When there are multiple maintainers for a piece of code an ``Acked-by`` +or ``Reviewed-by`` tag (or review comments) from a single maintainer is +enough to satisfy this requirement. + +If the review process or validation for a particular change will take longer +than the expected review timeline for the subsystem, maintainer should +reply to the submission indicating that the work is being done, and when +to expect full results. + +Refactoring and core changes +---------------------------- + +Occasionally core code needs to be changed to improve the maintainability +of the kernel as a whole. Maintainers are expected to be present and +help guide and test changes to their code to fit the new infrastructure. + +Bug reports +----------- + +Maintainers must ensure severe problems in their code reported to them +are resolved in a timely manner: regressions, kernel crashes, kernel warnings, +compilation errors, lockups, data loss, and other bugs of similar scope. + +Maintainers furthermore should respond to reports about other kinds of +bugs as well, if the report is of reasonable quality or indicates a +problem that might be severe -- especially if they have *Supported* +status of the codebase in the MAINTAINERS file. + +Selecting the maintainer +======================== + +The previous section described the expectations of the maintainer, +this section provides guidance on selecting one and describes common +misconceptions. + +The author +---------- + +Most natural and common choice of a maintainer is the author of the code. +The author is intimately familiar with the code, so it is the best person +to take care of it on an ongoing basis. + +That said, being a maintainer is an active role. The MAINTAINERS file +is not a list of credits (in fact a separate CREDITS file exists), +it is a list of those who will actively help with the code. +If the author does not have the time, interest or ability to maintain +the code, a different maintainer must be selected. + +Multiple maintainers +-------------------- + +Modern best practices dictate that there should be at least two maintainers +for any piece of code, no matter how trivial. It spreads the burden, helps +people take vacations and prevents burnout, trains new members of +the community etc. etc. Even when there is clearly one perfect candidate, +another maintainer should be found. + +Maintainers must be human, therefore, it is not acceptable to add a mailing +list or a group email as a maintainer. Trust and understanding are the +foundation of kernel maintenance and one cannot build trust with a mailing +list. Having a mailing list *in addition* to humans is perfectly fine. + +Corporate structures +-------------------- + +To an outsider the Linux kernel may resemble a hierarchical organization +with Linus as the CEO. While the code flows in a hierarchical fashion, +the corporate template does not apply here. Linux is an anarchy held +together by (rarely expressed) mutual respect, trust and convenience. + +All that is to say that managers almost never make good maintainers. +The maintainer position more closely matches an on-call rotation +than a position of power. + +The following characteristics of a person selected as a maintainer +are clear red flags: + + - unknown to the community, never sent an email to the list before + - did not author any of the code + - (when development is contracted) works for a company which paid + for the development rather than the company which did the work + +Non compliance +============== + +Subsystem maintainers may remove inactive maintainers from the MAINTAINERS +file. If the maintainer was a significant author or played an important +role in the development of the code, they should be moved to the CREDITS file. + +Removing an inactive maintainer should not be seen as a punitive action. +Having an inactive maintainer has a real cost as all developers have +to remember to include the maintainers in discussions and subsystem +maintainers spend brain power figuring out how to solicit feedback. + +Subsystem maintainers may remove code for lacking maintenance. + +Subsystem maintainers may refuse accepting code from companies +which repeatedly neglected their maintainership duties. diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst index 3e03283c144e..eeee27f8b18c 100644 --- a/Documentation/maintainer/index.rst +++ b/Documentation/maintainer/index.rst @@ -9,6 +9,7 @@ additions to this manual. .. toctree:: :maxdepth: 2 + feature-and-driver-maintainers configure-git rebasing-and-merging pull-requests diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index cfd37f31077f..7ad4bfc2cc03 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -101,7 +101,8 @@ to do something different in the near future. ../doc-guide/maintainer-profile ../nvdimm/maintainer-entry-profile - ../riscv/patch-acceptance + ../arch/riscv/patch-acceptance ../driver-api/media/maintainer-entry-profile ../driver-api/vfio-pci-device-specific-driver-acceptance ../nvme/feature-and-quirk-policy + ../filesystems/xfs-maintainer-entry-profile diff --git a/Documentation/maintainer/pull-requests.rst b/Documentation/maintainer/pull-requests.rst index e072de60ccb0..00b200facf67 100644 --- a/Documentation/maintainer/pull-requests.rst +++ b/Documentation/maintainer/pull-requests.rst @@ -1,5 +1,3 @@ -.. _pullrequests: - Creating Pull Requests ====================== @@ -41,7 +39,7 @@ named ``char-misc-next``, you would be using the following command:: that will create a signed tag called ``char-misc-4.15-rc1`` based on the last commit in the ``char-misc-next`` branch, and sign it with your gpg key -(see :ref:`Documentation/maintainer/configure-git.rst <configuregit>`). +(see Documentation/maintainer/configure-git.rst). Linus will only accept pull requests based on a signed tag. Other maintainers may differ. diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index 06e14efd8662..d414e145f912 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -396,6 +396,10 @@ Memory barriers come in four basic varieties: (2) Address-dependency barriers (historical). + [!] This section is marked as HISTORICAL: For more up-to-date + information, including how compiler transformations related to pointer + comparisons can sometimes cause problems, see + Documentation/RCU/rcu_dereference.rst. An address-dependency barrier is a weaker form of read barrier. In the case where two loads are performed such that the second depends on the @@ -556,6 +560,9 @@ There are certain things that the Linux kernel memory barriers do not guarantee: ADDRESS-DEPENDENCY BARRIERS (HISTORICAL) ---------------------------------------- +[!] This section is marked as HISTORICAL: For more up-to-date information, +including how compiler transformations related to pointer comparisons can +sometimes cause problems, see Documentation/RCU/rcu_dereference.rst. As of v4.15 of the Linux kernel, an smp_mb() was added to READ_ONCE() for DEC Alpha, which means that about the only people who need to pay attention diff --git a/Documentation/mm/arch_pgtable_helpers.rst b/Documentation/mm/arch_pgtable_helpers.rst index af3891f895b0..c82e3ee20e51 100644 --- a/Documentation/mm/arch_pgtable_helpers.rst +++ b/Documentation/mm/arch_pgtable_helpers.rst @@ -46,7 +46,11 @@ PTE Page Table Helpers +---------------------------+--------------------------------------------------+ | pte_mkclean | Creates a clean PTE | +---------------------------+--------------------------------------------------+ -| pte_mkwrite | Creates a writable PTE | +| pte_mkwrite | Creates a writable PTE of the type specified by | +| | the VMA. | ++---------------------------+--------------------------------------------------+ +| pte_mkwrite_novma | Creates a writable PTE, of the conventional type | +| | of writable. | +---------------------------+--------------------------------------------------+ | pte_wrprotect | Creates a write protected PTE | +---------------------------+--------------------------------------------------+ @@ -118,7 +122,11 @@ PMD Page Table Helpers +---------------------------+--------------------------------------------------+ | pmd_mkclean | Creates a clean PMD | +---------------------------+--------------------------------------------------+ -| pmd_mkwrite | Creates a writable PMD | +| pmd_mkwrite | Creates a writable PMD of the type specified by | +| | the VMA. | ++---------------------------+--------------------------------------------------+ +| pmd_mkwrite_novma | Creates a writable PMD, of the conventional type | +| | of writable. | +---------------------------+--------------------------------------------------+ | pmd_wrprotect | Creates a write protected PMD | +---------------------------+--------------------------------------------------+ diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst index 4bfdf1d30c4a..1f7e0586b5fa 100644 --- a/Documentation/mm/damon/design.rst +++ b/Documentation/mm/damon/design.rst @@ -154,6 +154,8 @@ The monitoring overhead of this mechanism will arbitrarily increase as the size of the target workload grows. +.. _damon_design_region_based_sampling: + Region Based Sampling ~~~~~~~~~~~~~~~~~~~~~ @@ -163,9 +165,10 @@ assumption (pages in a region have the same access frequencies) is kept, only one page in the region is required to be checked. Thus, for each ``sampling interval``, DAMON randomly picks one page in each region, waits for one ``sampling interval``, checks whether the page is accessed meanwhile, and -increases the access frequency of the region if so. Therefore, the monitoring -overhead is controllable by setting the number of regions. DAMON allows users -to set the minimum and the maximum number of regions for the trade-off. +increases the access frequency counter of the region if so. The counter is +called ``nr_regions`` of the region. Therefore, the monitoring overhead is +controllable by setting the number of regions. DAMON allows users to set the +minimum and the maximum number of regions for the trade-off. This scheme, however, cannot preserve the quality of the output if the assumption is not guaranteed. @@ -190,6 +193,8 @@ In this way, DAMON provides its best-effort quality and minimal overhead while keeping the bounds users set for their trade-off. +.. _damon_design_age_tracking: + Age Tracking ~~~~~~~~~~~~ @@ -254,7 +259,8 @@ works, DAMON provides a feature called Data Access Monitoring-based Operation Schemes (DAMOS). It lets users specify their desired schemes at a high level. For such specifications, DAMON starts monitoring, finds regions having the access pattern of interest, and applies the user-desired operation actions -to the regions as soon as found. +to the regions, for every user-specified time interval called +``apply_interval``. .. _damon_design_damos_action: @@ -380,12 +386,24 @@ number of filters for each scheme. Each filter specifies the type of target memory, and whether it should exclude the memory of the type (filter-out), or all except the memory of the type (filter-in). -As of this writing, anonymous page type and memory cgroup type are supported by -the feature. Some filter target types can require additional arguments. For -example, the memory cgroup filter type asks users to specify the file path of -the memory cgroup for the filter. Hence, users can apply specific schemes to -only anonymous pages, non-anonymous pages, pages of specific cgroups, all pages -excluding those of specific cgroups, and any combination of those. +Currently, anonymous page, memory cgroup, address range, and DAMON monitoring +target type filters are supported by the feature. Some filter target types +require additional arguments. The memory cgroup filter type asks users to +specify the file path of the memory cgroup for the filter. The address range +type asks the start and end addresses of the range. The DAMON monitoring +target type asks the index of the target from the context's monitoring targets +list. Hence, users can apply specific schemes to only anonymous pages, +non-anonymous pages, pages of specific cgroups, all pages excluding those of +specific cgroups, pages in specific address range, pages in specific DAMON +monitoring targets, and any combination of those. + +To handle filters efficiently, the address range and DAMON monitoring target +type filters are handled by the core layer, while others are handled by +operations set. If a memory region is filtered by a core layer-handled filter, +it is not counted as the scheme has tried to the region. In contrast, if a +memory regions is filtered by an operations set layer-handled filter, it is +counted as the scheme has tried. The difference in accounting leads to changes +in the statistics. Application Programming Interface @@ -459,3 +477,15 @@ modules for proactive reclamation and LRU lists manipulation are provided. For more detail, please read the usage documents for those (:doc:`/admin-guide/mm/damon/reclaim` and :doc:`/admin-guide/mm/damon/lru_sort`). + + +.. _damon_design_execution_model_and_data_structures: + +Execution Model and Data Structures +=================================== + +The monitoring-related information including the monitoring request +specification and DAMON-based operation schemes are stored in a data structure +called DAMON ``context``. DAMON executes each context with a kernel thread +called ``kdamond``. Multiple kdamonds could run in parallel, for different +types of monitoring. diff --git a/Documentation/mm/frontswap.rst b/Documentation/mm/frontswap.rst deleted file mode 100644 index c892412988af..000000000000 --- a/Documentation/mm/frontswap.rst +++ /dev/null @@ -1,264 +0,0 @@ -========= -Frontswap -========= - -Frontswap provides a "transcendent memory" interface for swap pages. -In some environments, dramatic performance savings may be obtained because -swapped pages are saved in RAM (or a RAM-like device) instead of a swap disk. - -.. _Transcendent memory in a nutshell: https://lwn.net/Articles/454795/ - -Frontswap is so named because it can be thought of as the opposite of -a "backing" store for a swap device. The storage is assumed to be -a synchronous concurrency-safe page-oriented "pseudo-RAM device" conforming -to the requirements of transcendent memory (such as Xen's "tmem", or -in-kernel compressed memory, aka "zcache", or future RAM-like devices); -this pseudo-RAM device is not directly accessible or addressable by the -kernel and is of unknown and possibly time-varying size. The driver -links itself to frontswap by calling frontswap_register_ops to set the -frontswap_ops funcs appropriately and the functions it provides must -conform to certain policies as follows: - -An "init" prepares the device to receive frontswap pages associated -with the specified swap device number (aka "type"). A "store" will -copy the page to transcendent memory and associate it with the type and -offset associated with the page. A "load" will copy the page, if found, -from transcendent memory into kernel memory, but will NOT remove the page -from transcendent memory. An "invalidate_page" will remove the page -from transcendent memory and an "invalidate_area" will remove ALL pages -associated with the swap type (e.g., like swapoff) and notify the "device" -to refuse further stores with that swap type. - -Once a page is successfully stored, a matching load on the page will normally -succeed. So when the kernel finds itself in a situation where it needs -to swap out a page, it first attempts to use frontswap. If the store returns -success, the data has been successfully saved to transcendent memory and -a disk write and, if the data is later read back, a disk read are avoided. -If a store returns failure, transcendent memory has rejected the data, and the -page can be written to swap as usual. - -Note that if a page is stored and the page already exists in transcendent memory -(a "duplicate" store), either the store succeeds and the data is overwritten, -or the store fails AND the page is invalidated. This ensures stale data may -never be obtained from frontswap. - -If properly configured, monitoring of frontswap is done via debugfs in -the `/sys/kernel/debug/frontswap` directory. The effectiveness of -frontswap can be measured (across all swap devices) with: - -``failed_stores`` - how many store attempts have failed - -``loads`` - how many loads were attempted (all should succeed) - -``succ_stores`` - how many store attempts have succeeded - -``invalidates`` - how many invalidates were attempted - -A backend implementation may provide additional metrics. - -FAQ -=== - -* Where's the value? - -When a workload starts swapping, performance falls through the floor. -Frontswap significantly increases performance in many such workloads by -providing a clean, dynamic interface to read and write swap pages to -"transcendent memory" that is otherwise not directly addressable to the kernel. -This interface is ideal when data is transformed to a different form -and size (such as with compression) or secretly moved (as might be -useful for write-balancing for some RAM-like devices). Swap pages (and -evicted page-cache pages) are a great use for this kind of slower-than-RAM- -but-much-faster-than-disk "pseudo-RAM device". - -Frontswap with a fairly small impact on the kernel, -provides a huge amount of flexibility for more dynamic, flexible RAM -utilization in various system configurations: - -In the single kernel case, aka "zcache", pages are compressed and -stored in local memory, thus increasing the total anonymous pages -that can be safely kept in RAM. Zcache essentially trades off CPU -cycles used in compression/decompression for better memory utilization. -Benchmarks have shown little or no impact when memory pressure is -low while providing a significant performance improvement (25%+) -on some workloads under high memory pressure. - -"RAMster" builds on zcache by adding "peer-to-peer" transcendent memory -support for clustered systems. Frontswap pages are locally compressed -as in zcache, but then "remotified" to another system's RAM. This -allows RAM to be dynamically load-balanced back-and-forth as needed, -i.e. when system A is overcommitted, it can swap to system B, and -vice versa. RAMster can also be configured as a memory server so -many servers in a cluster can swap, dynamically as needed, to a single -server configured with a large amount of RAM... without pre-configuring -how much of the RAM is available for each of the clients! - -In the virtual case, the whole point of virtualization is to statistically -multiplex physical resources across the varying demands of multiple -virtual machines. This is really hard to do with RAM and efforts to do -it well with no kernel changes have essentially failed (except in some -well-publicized special-case workloads). -Specifically, the Xen Transcendent Memory backend allows otherwise -"fallow" hypervisor-owned RAM to not only be "time-shared" between multiple -virtual machines, but the pages can be compressed and deduplicated to -optimize RAM utilization. And when guest OS's are induced to surrender -underutilized RAM (e.g. with "selfballooning"), sudden unexpected -memory pressure may result in swapping; frontswap allows those pages -to be swapped to and from hypervisor RAM (if overall host system memory -conditions allow), thus mitigating the potentially awful performance impact -of unplanned swapping. - -A KVM implementation is underway and has been RFC'ed to lkml. And, -using frontswap, investigation is also underway on the use of NVM as -a memory extension technology. - -* Sure there may be performance advantages in some situations, but - what's the space/time overhead of frontswap? - -If CONFIG_FRONTSWAP is disabled, every frontswap hook compiles into -nothingness and the only overhead is a few extra bytes per swapon'ed -swap device. If CONFIG_FRONTSWAP is enabled but no frontswap "backend" -registers, there is one extra global variable compared to zero for -every swap page read or written. If CONFIG_FRONTSWAP is enabled -AND a frontswap backend registers AND the backend fails every "store" -request (i.e. provides no memory despite claiming it might), -CPU overhead is still negligible -- and since every frontswap fail -precedes a swap page write-to-disk, the system is highly likely -to be I/O bound and using a small fraction of a percent of a CPU -will be irrelevant anyway. - -As for space, if CONFIG_FRONTSWAP is enabled AND a frontswap backend -registers, one bit is allocated for every swap page for every swap -device that is swapon'd. This is added to the EIGHT bits (which -was sixteen until about 2.6.34) that the kernel already allocates -for every swap page for every swap device that is swapon'd. (Hugh -Dickins has observed that frontswap could probably steal one of -the existing eight bits, but let's worry about that minor optimization -later.) For very large swap disks (which are rare) on a standard -4K pagesize, this is 1MB per 32GB swap. - -When swap pages are stored in transcendent memory instead of written -out to disk, there is a side effect that this may create more memory -pressure that can potentially outweigh the other advantages. A -backend, such as zcache, must implement policies to carefully (but -dynamically) manage memory limits to ensure this doesn't happen. - -* OK, how about a quick overview of what this frontswap patch does - in terms that a kernel hacker can grok? - -Let's assume that a frontswap "backend" has registered during -kernel initialization; this registration indicates that this -frontswap backend has access to some "memory" that is not directly -accessible by the kernel. Exactly how much memory it provides is -entirely dynamic and random. - -Whenever a swap-device is swapon'd frontswap_init() is called, -passing the swap device number (aka "type") as a parameter. -This notifies frontswap to expect attempts to "store" swap pages -associated with that number. - -Whenever the swap subsystem is readying a page to write to a swap -device (c.f swap_writepage()), frontswap_store is called. Frontswap -consults with the frontswap backend and if the backend says it does NOT -have room, frontswap_store returns -1 and the kernel swaps the page -to the swap device as normal. Note that the response from the frontswap -backend is unpredictable to the kernel; it may choose to never accept a -page, it could accept every ninth page, or it might accept every -page. But if the backend does accept a page, the data from the page -has already been copied and associated with the type and offset, -and the backend guarantees the persistence of the data. In this case, -frontswap sets a bit in the "frontswap_map" for the swap device -corresponding to the page offset on the swap device to which it would -otherwise have written the data. - -When the swap subsystem needs to swap-in a page (swap_readpage()), -it first calls frontswap_load() which checks the frontswap_map to -see if the page was earlier accepted by the frontswap backend. If -it was, the page of data is filled from the frontswap backend and -the swap-in is complete. If not, the normal swap-in code is -executed to obtain the page of data from the real swap device. - -So every time the frontswap backend accepts a page, a swap device read -and (potentially) a swap device write are replaced by a "frontswap backend -store" and (possibly) a "frontswap backend loads", which are presumably much -faster. - -* Can't frontswap be configured as a "special" swap device that is - just higher priority than any real swap device (e.g. like zswap, - or maybe swap-over-nbd/NFS)? - -No. First, the existing swap subsystem doesn't allow for any kind of -swap hierarchy. Perhaps it could be rewritten to accommodate a hierarchy, -but this would require fairly drastic changes. Even if it were -rewritten, the existing swap subsystem uses the block I/O layer which -assumes a swap device is fixed size and any page in it is linearly -addressable. Frontswap barely touches the existing swap subsystem, -and works around the constraints of the block I/O subsystem to provide -a great deal of flexibility and dynamicity. - -For example, the acceptance of any swap page by the frontswap backend is -entirely unpredictable. This is critical to the definition of frontswap -backends because it grants completely dynamic discretion to the -backend. In zcache, one cannot know a priori how compressible a page is. -"Poorly" compressible pages can be rejected, and "poorly" can itself be -defined dynamically depending on current memory constraints. - -Further, frontswap is entirely synchronous whereas a real swap -device is, by definition, asynchronous and uses block I/O. The -block I/O layer is not only unnecessary, but may perform "optimizations" -that are inappropriate for a RAM-oriented device including delaying -the write of some pages for a significant amount of time. Synchrony is -required to ensure the dynamicity of the backend and to avoid thorny race -conditions that would unnecessarily and greatly complicate frontswap -and/or the block I/O subsystem. That said, only the initial "store" -and "load" operations need be synchronous. A separate asynchronous thread -is free to manipulate the pages stored by frontswap. For example, -the "remotification" thread in RAMster uses standard asynchronous -kernel sockets to move compressed frontswap pages to a remote machine. -Similarly, a KVM guest-side implementation could do in-guest compression -and use "batched" hypercalls. - -In a virtualized environment, the dynamicity allows the hypervisor -(or host OS) to do "intelligent overcommit". For example, it can -choose to accept pages only until host-swapping might be imminent, -then force guests to do their own swapping. - -There is a downside to the transcendent memory specifications for -frontswap: Since any "store" might fail, there must always be a real -slot on a real swap device to swap the page. Thus frontswap must be -implemented as a "shadow" to every swapon'd device with the potential -capability of holding every page that the swap device might have held -and the possibility that it might hold no pages at all. This means -that frontswap cannot contain more pages than the total of swapon'd -swap devices. For example, if NO swap device is configured on some -installation, frontswap is useless. Swapless portable devices -can still use frontswap but a backend for such devices must configure -some kind of "ghost" swap device and ensure that it is never used. - -* Why this weird definition about "duplicate stores"? If a page - has been previously successfully stored, can't it always be - successfully overwritten? - -Nearly always it can, but no, sometimes it cannot. Consider an example -where data is compressed and the original 4K page has been compressed -to 1K. Now an attempt is made to overwrite the page with data that -is non-compressible and so would take the entire 4K. But the backend -has no more space. In this case, the store must be rejected. Whenever -frontswap rejects a store that would overwrite, it also must invalidate -the old data and ensure that it is no longer accessible. Since the -swap subsystem then writes the new data to the read swap device, -this is the correct course of action to ensure coherency. - -* Why does the frontswap patch create the new include file swapfile.h? - -The frontswap code depends on some swap-subsystem-internal data -structures that have, over the years, moved back and forth between -static and global. This seemed a reasonable compromise: Define -them as global but declare them in a new include file that isn't -included by the large number of source files that include swap.h. - -Dan Magenheimer, last updated April 9, 2012 diff --git a/Documentation/mm/highmem.rst b/Documentation/mm/highmem.rst index c964e0848702..9d92e3f2b3d6 100644 --- a/Documentation/mm/highmem.rst +++ b/Documentation/mm/highmem.rst @@ -51,11 +51,14 @@ Temporary Virtual Mappings The kernel contains several ways of creating temporary mappings. The following list shows them in order of preference of use. -* kmap_local_page(). This function is used to require short term mappings. - It can be invoked from any context (including interrupts) but the mappings - can only be used in the context which acquired them. - - This function should always be used, whereas kmap_atomic() and kmap() have +* kmap_local_page(), kmap_local_folio() - These functions are used to create + short term mappings. They can be invoked from any context (including + interrupts) but the mappings can only be used in the context which acquired + them. The only differences between them consist in the first taking a pointer + to a struct page and the second taking a pointer to struct folio and the byte + offset within the folio which identifies the page. + + These functions should always be used, whereas kmap_atomic() and kmap() have been deprecated. These mappings are thread-local and CPU-local, meaning that the mapping @@ -72,17 +75,17 @@ list shows them in order of preference of use. maps of the outgoing task are saved and those of the incoming one are restored. - kmap_local_page() always returns a valid virtual address and it is assumed - that kunmap_local() will never fail. + kmap_local_page(), as well as kmap_local_folio() always returns valid virtual + kernel addresses and it is assumed that kunmap_local() will never fail. - On CONFIG_HIGHMEM=n kernels and for low memory pages this returns the + On CONFIG_HIGHMEM=n kernels and for low memory pages they return the virtual address of the direct mapping. Only real highmem pages are temporarily mapped. Therefore, users may call a plain page_address() for pages which are known to not come from ZONE_HIGHMEM. However, it is - always safe to use kmap_local_page() / kunmap_local(). + always safe to use kmap_local_{page,folio}() / kunmap_local(). - While it is significantly faster than kmap(), for the highmem case it - comes with restrictions about the pointers validity. Contrary to kmap() + While they are significantly faster than kmap(), for the highmem case they + come with restrictions about the pointers validity. Contrary to kmap() mappings, the local mappings are only valid in the context of the caller and cannot be handed to other contexts. This implies that users must be absolutely sure to keep the use of the return address local to the @@ -91,7 +94,7 @@ list shows them in order of preference of use. Most code can be designed to use thread local mappings. User should therefore try to design their code to avoid the use of kmap() by mapping pages in the same thread the address will be used and prefer - kmap_local_page(). + kmap_local_page() or kmap_local_folio(). Nesting kmap_local_page() and kmap_atomic() mappings is allowed to a certain extent (up to KMAP_TYPE_NR) but their invocations have to be strictly ordered @@ -206,4 +209,5 @@ Functions ========= .. kernel-doc:: include/linux/highmem.h +.. kernel-doc:: mm/highmem.c .. kernel-doc:: include/linux/highmem-internal.h diff --git a/Documentation/mm/hmm.rst b/Documentation/mm/hmm.rst index 9aa512c3a12c..0595098a74d9 100644 --- a/Documentation/mm/hmm.rst +++ b/Documentation/mm/hmm.rst @@ -163,16 +163,7 @@ use:: It will trigger a page fault on missing or read-only entries if write access is requested (see below). Page faults use the generic mm page fault code path just -like a CPU page fault. - -Both functions copy CPU page table entries into their pfns array argument. Each -entry in that array corresponds to an address in the virtual range. HMM -provides a set of flags to help the driver identify special CPU page table -entries. - -Locking within the sync_cpu_device_pagetables() callback is the most important -aspect the driver must respect in order to keep things properly synchronized. -The usage pattern is:: +like a CPU page fault. The usage pattern is:: int driver_populate_range(...) { @@ -417,7 +408,7 @@ entries. Any attempt to access the swap entry results in a fault which is resovled by replacing the entry with the original mapping. A driver gets notified that the mapping has been changed by MMU notifiers, after which point it will no longer have exclusive access to the page. Exclusive access is -guranteed to last until the driver drops the page lock and page reference, at +guaranteed to last until the driver drops the page lock and page reference, at which point any CPU faults on the page may proceed as described. Memory cgroup (memcg) and rss accounting diff --git a/Documentation/mm/hugetlbfs_reserv.rst b/Documentation/mm/hugetlbfs_reserv.rst index d9c2b0f01dcd..4914fbf07966 100644 --- a/Documentation/mm/hugetlbfs_reserv.rst +++ b/Documentation/mm/hugetlbfs_reserv.rst @@ -271,12 +271,12 @@ to the global reservation count (resv_huge_pages). Freeing Huge Pages ================== -Huge page freeing is performed by the routine free_huge_page(). This routine -is the destructor for hugetlbfs compound pages. As a result, it is only -passed a pointer to the page struct. When a huge page is freed, reservation -accounting may need to be performed. This would be the case if the page was -associated with a subpool that contained reserves, or the page is being freed -on an error path where a global reserve count must be restored. +Huge pages are freed by free_huge_folio(). It is only passed a pointer +to the folio as it is called from the generic MM code. When a huge page +is freed, reservation accounting may need to be performed. This would +be the case if the page was associated with a subpool that contained +reserves, or the page is being freed on an error path where a global +reserve count must be restored. The page->private field points to any subpool associated with the page. If the PagePrivate flag is set, it indicates the global reserve count should @@ -525,7 +525,7 @@ However, there are several instances where errors are encountered after a huge page is allocated but before it is instantiated. In this case, the page allocation has consumed the reservation and made the appropriate subpool, reservation map and global count adjustments. If the page is freed at this -time (before instantiation and clearing of PagePrivate), then free_huge_page +time (before instantiation and clearing of PagePrivate), then free_huge_folio will increment the global reservation count. However, the reservation map indicates the reservation was consumed. This resulting inconsistent state will cause the 'leak' of a reserved huge page. The global reserve count will diff --git a/Documentation/mm/hwpoison.rst b/Documentation/mm/hwpoison.rst index ba48a441feed..483b72aa7c11 100644 --- a/Documentation/mm/hwpoison.rst +++ b/Documentation/mm/hwpoison.rst @@ -48,7 +48,7 @@ of applications. KVM support requires a recent qemu-kvm release. For the KVM use there was need for a new signal type so that KVM can inject the machine check into the guest with the proper address. This in theory allows other applications to handle -memory failures too. The expection is that near all applications +memory failures too. The expectation is that most applications won't do that, but some very specialized ones might. Failure recovery modes diff --git a/Documentation/mm/index.rst b/Documentation/mm/index.rst index 5a94a921ea40..31d2ac306438 100644 --- a/Documentation/mm/index.rst +++ b/Documentation/mm/index.rst @@ -44,7 +44,6 @@ above structured documentation, or deleted if it has served its purpose. balance damon/index free_page_reporting - frontswap hmm hwpoison hugetlbfs_reserv diff --git a/Documentation/mm/overcommit-accounting.rst b/Documentation/mm/overcommit-accounting.rst index a4895d6fc1c2..e2263477f6d5 100644 --- a/Documentation/mm/overcommit-accounting.rst +++ b/Documentation/mm/overcommit-accounting.rst @@ -8,8 +8,7 @@ The Linux kernel supports the following overcommit handling modes Heuristic overcommit handling. Obvious overcommits of address space are refused. Used for a typical system. It ensures a seriously wild allocation fails while allowing overcommit to - reduce swap usage. root is allowed to allocate slightly more - memory in this mode. This is the default. + reduce swap usage. This is the default. 1 Always overcommit. Appropriate for some scientific diff --git a/Documentation/mm/page_migration.rst b/Documentation/mm/page_migration.rst index e35af7805be5..f1ce67a26615 100644 --- a/Documentation/mm/page_migration.rst +++ b/Documentation/mm/page_migration.rst @@ -180,7 +180,7 @@ The following events (counters) can be used to monitor page migration. 4. THP_MIGRATION_FAIL: A THP could not be migrated nor it could be split. 5. THP_MIGRATION_SPLIT: A THP was migrated, but not as such: first, the THP had - to be split. After splitting, a migration retry was used for it's sub-pages. + to be split. After splitting, a migration retry was used for its sub-pages. THP_MIGRATION_* events also update the appropriate PGMIGRATE_SUCCESS or PGMIGRATE_FAIL events. For example, a THP migration failure will cause both diff --git a/Documentation/mm/page_tables.rst b/Documentation/mm/page_tables.rst index 7840c1891751..be47b192a596 100644 --- a/Documentation/mm/page_tables.rst +++ b/Documentation/mm/page_tables.rst @@ -152,3 +152,130 @@ Page table handling code that wishes to be architecture-neutral, such as the virtual memory manager, will need to be written so that it traverses all of the currently five levels. This style should also be preferred for architecture-specific code, so as to be robust to future changes. + + +MMU, TLB, and Page Faults +========================= + +The `Memory Management Unit (MMU)` is a hardware component that handles virtual +to physical address translations. It may use relatively small caches in hardware +called `Translation Lookaside Buffers (TLBs)` and `Page Walk Caches` to speed up +these translations. + +When CPU accesses a memory location, it provides a virtual address to the MMU, +which checks if there is the existing translation in the TLB or in the Page +Walk Caches (on architectures that support them). If no translation is found, +MMU uses the page walks to determine the physical address and create the map. + +The dirty bit for a page is set (i.e., turned on) when the page is written to. +Each page of memory has associated permission and dirty bits. The latter +indicate that the page has been modified since it was loaded into memory. + +If nothing prevents it, eventually the physical memory can be accessed and the +requested operation on the physical frame is performed. + +There are several reasons why the MMU can't find certain translations. It could +happen because the CPU is trying to access memory that the current task is not +permitted to, or because the data is not present into physical memory. + +When these conditions happen, the MMU triggers page faults, which are types of +exceptions that signal the CPU to pause the current execution and run a special +function to handle the mentioned exceptions. + +There are common and expected causes of page faults. These are triggered by +process management optimization techniques called "Lazy Allocation" and +"Copy-on-Write". Page faults may also happen when frames have been swapped out +to persistent storage (swap partition or file) and evicted from their physical +locations. + +These techniques improve memory efficiency, reduce latency, and minimize space +occupation. This document won't go deeper into the details of "Lazy Allocation" +and "Copy-on-Write" because these subjects are out of scope as they belong to +Process Address Management. + +Swapping differentiates itself from the other mentioned techniques because it's +undesirable since it's performed as a means to reduce memory under heavy +pressure. + +Swapping can't work for memory mapped by kernel logical addresses. These are a +subset of the kernel virtual space that directly maps a contiguous range of +physical memory. Given any logical address, its physical address is determined +with simple arithmetic on an offset. Accesses to logical addresses are fast +because they avoid the need for complex page table lookups at the expenses of +frames not being evictable and pageable out. + +If the kernel fails to make room for the data that must be present in the +physical frames, the kernel invokes the out-of-memory (OOM) killer to make room +by terminating lower priority processes until pressure reduces under a safe +threshold. + +Additionally, page faults may be also caused by code bugs or by maliciously +crafted addresses that the CPU is instructed to access. A thread of a process +could use instructions to address (non-shared) memory which does not belong to +its own address space, or could try to execute an instruction that want to write +to a read-only location. + +If the above-mentioned conditions happen in user-space, the kernel sends a +`Segmentation Fault` (SIGSEGV) signal to the current thread. That signal usually +causes the termination of the thread and of the process it belongs to. + +This document is going to simplify and show an high altitude view of how the +Linux kernel handles these page faults, creates tables and tables' entries, +check if memory is present and, if not, requests to load data from persistent +storage or from other devices, and updates the MMU and its caches. + +The first steps are architecture dependent. Most architectures jump to +`do_page_fault()`, whereas the x86 interrupt handler is defined by the +`DEFINE_IDTENTRY_RAW_ERRORCODE()` macro which calls `handle_page_fault()`. + +Whatever the routes, all architectures end up to the invocation of +`handle_mm_fault()` which, in turn, (likely) ends up calling +`__handle_mm_fault()` to carry out the actual work of allocating the page +tables. + +The unfortunate case of not being able to call `__handle_mm_fault()` means +that the virtual address is pointing to areas of physical memory which are not +permitted to be accessed (at least from the current context). This +condition resolves to the kernel sending the above-mentioned SIGSEGV signal +to the process and leads to the consequences already explained. + +`__handle_mm_fault()` carries out its work by calling several functions to +find the entry's offsets of the upper layers of the page tables and allocate +the tables that it may need. + +The functions that look for the offset have names like `*_offset()`, where the +"*" is for pgd, p4d, pud, pmd, pte; instead the functions to allocate the +corresponding tables, layer by layer, are called `*_alloc`, using the +above-mentioned convention to name them after the corresponding types of tables +in the hierarchy. + +The page table walk may end at one of the middle or upper layers (PMD, PUD). + +Linux supports larger page sizes than the usual 4KB (i.e., the so called +`huge pages`). When using these kinds of larger pages, higher level pages can +directly map them, with no need to use lower level page entries (PTE). Huge +pages contain large contiguous physical regions that usually span from 2MB to +1GB. They are respectively mapped by the PMD and PUD page entries. + +The huge pages bring with them several benefits like reduced TLB pressure, +reduced page table overhead, memory allocation efficiency, and performance +improvement for certain workloads. However, these benefits come with +trade-offs, like wasted memory and allocation challenges. + +At the very end of the walk with allocations, if it didn't return errors, +`__handle_mm_fault()` finally calls `handle_pte_fault()`, which via `do_fault()` +performs one of `do_read_fault()`, `do_cow_fault()`, `do_shared_fault()`. +"read", "cow", "shared" give hints about the reasons and the kind of fault it's +handling. + +The actual implementation of the workflow is very complex. Its design allows +Linux to handle page faults in a way that is tailored to the specific +characteristics of each architecture, while still sharing a common overall +structure. + +To conclude this high altitude view of how Linux handles page faults, let's +add that the page faults handler can be disabled and enabled respectively with +`pagefault_disable()` and `pagefault_enable()`. + +Several code path make use of the latter two functions because they need to +disable traps into the page faults handler, mostly to prevent deadlocks. diff --git a/Documentation/mm/split_page_table_lock.rst b/Documentation/mm/split_page_table_lock.rst index a834fad9de12..e4f6972eb6c0 100644 --- a/Documentation/mm/split_page_table_lock.rst +++ b/Documentation/mm/split_page_table_lock.rst @@ -58,7 +58,7 @@ Support of split page table lock by an architecture =================================================== There's no need in special enabling of PTE split page table lock: everything -required is done by pgtable_pte_page_ctor() and pgtable_pte_page_dtor(), which +required is done by pagetable_pte_ctor() and pagetable_pte_dtor(), which must be called on PTE table allocation / freeing. Make sure the architecture doesn't use slab allocator for page table @@ -68,8 +68,8 @@ This field shares storage with page->ptl. PMD split lock only makes sense if you have more than two page table levels. -PMD split lock enabling requires pgtable_pmd_page_ctor() call on PMD table -allocation and pgtable_pmd_page_dtor() on freeing. +PMD split lock enabling requires pagetable_pmd_ctor() call on PMD table +allocation and pagetable_pmd_dtor() on freeing. Allocation usually happens in pmd_alloc_one(), freeing in pmd_free() and pmd_free_tlb(), but make sure you cover all PMD table allocation / freeing @@ -77,7 +77,7 @@ paths: i.e X86_PAE preallocate few PMDs on pgd_alloc(). With everything in place you can set CONFIG_ARCH_ENABLE_SPLIT_PMD_PTLOCK. -NOTE: pgtable_pte_page_ctor() and pgtable_pmd_page_ctor() can fail -- it must +NOTE: pagetable_pte_ctor() and pagetable_pmd_ctor() can fail -- it must be handled properly. page->ptl @@ -97,7 +97,7 @@ trick: split lock with enabled DEBUG_SPINLOCK or DEBUG_LOCK_ALLOC, but costs one more cache line for indirect access; -The spinlock_t allocated in pgtable_pte_page_ctor() for PTE table and in -pgtable_pmd_page_ctor() for PMD table. +The spinlock_t allocated in pagetable_pte_ctor() for PTE table and in +pagetable_pmd_ctor() for PMD table. Please, never access page->ptl directly -- use appropriate helper. diff --git a/Documentation/mm/unevictable-lru.rst b/Documentation/mm/unevictable-lru.rst index d5ac8511eb67..67f1338440a5 100644 --- a/Documentation/mm/unevictable-lru.rst +++ b/Documentation/mm/unevictable-lru.rst @@ -463,7 +463,7 @@ can request that a region of memory be mlocked by supplying the MAP_LOCKED flag to the mmap() call. There is one important and subtle difference here, though. mmap() + mlock() will fail if the range cannot be faulted in (e.g. because mm_populate fails) and returns with ENOMEM while mmap(MAP_LOCKED) will not fail. -The mmaped area will still have properties of the locked area - pages will not +The mmapped area will still have properties of the locked area - pages will not get swapped out - but major page faults to fault memory in might still happen. Furthermore, any mmap() call or brk() call that expands the heap by a task diff --git a/Documentation/mm/vmemmap_dedup.rst b/Documentation/mm/vmemmap_dedup.rst index a4b12ff906c4..593ede6d314b 100644 --- a/Documentation/mm/vmemmap_dedup.rst +++ b/Documentation/mm/vmemmap_dedup.rst @@ -1,3 +1,4 @@ + .. SPDX-License-Identifier: GPL-2.0 ========================================= @@ -10,14 +11,14 @@ HugeTLB This section is to explain how HugeTLB Vmemmap Optimization (HVO) works. The ``struct page`` structures are used to describe a physical page frame. By -default, there is a one-to-one mapping from a page frame to it's corresponding +default, there is a one-to-one mapping from a page frame to its corresponding ``struct page``. HugeTLB pages consist of multiple base page size pages and is supported by many architectures. See Documentation/admin-guide/mm/hugetlbpage.rst for more details. On the x86-64 architecture, HugeTLB pages of size 2MB and 1GB are currently supported. Since the base page size on x86 is 4KB, a 2MB HugeTLB page -consists of 512 base pages and a 1GB HugeTLB page consists of 4096 base pages. +consists of 512 base pages and a 1GB HugeTLB page consists of 262144 base pages. For each base page, there is a corresponding ``struct page``. Within the HugeTLB subsystem, only the first 4 ``struct page`` are used to @@ -210,6 +211,7 @@ the device (altmap). The following page sizes are supported in DAX: PAGE_SIZE (4K on x86_64), PMD_SIZE (2M on x86_64) and PUD_SIZE (1G on x86_64). +For powerpc equivalent details see Documentation/arch/powerpc/vmemmap_dedup.rst The differences with HugeTLB are relatively minor. diff --git a/Documentation/mm/zsmalloc.rst b/Documentation/mm/zsmalloc.rst index a3c26d587752..76902835e68e 100644 --- a/Documentation/mm/zsmalloc.rst +++ b/Documentation/mm/zsmalloc.rst @@ -263,3 +263,8 @@ is heavy internal fragmentation and zspool compaction is unable to relocate objects and release zspages. In these cases, it is recommended to decrease the limit on the size of the zspage chains (as specified by the CONFIG_ZSMALLOC_CHAIN_SIZE option). + +Functions +========= + +.. kernel-doc:: mm/zsmalloc.c diff --git a/Documentation/netlink/genetlink-c.yaml b/Documentation/netlink/genetlink-c.yaml index 57d1c1c4918f..c58f7153fcf8 100644 --- a/Documentation/netlink/genetlink-c.yaml +++ b/Documentation/netlink/genetlink-c.yaml @@ -13,6 +13,11 @@ $defs: type: [ string, integer ] pattern: ^[0-9A-Za-z_]+( - 1)?$ minimum: 0 + len-or-limit: + # literal int or limit based on fixed-width type e.g. u8-min, u16-max, etc. + type: [ string, integer ] + pattern: ^[su](8|16|32|64)-(min|max)$ + minimum: 0 # Schema for specs title: Protocol @@ -26,10 +31,6 @@ properties: type: string doc: type: string - version: - description: Generic Netlink family version. Default is 1. - type: integer - minimum: 1 protocol: description: Schema compatibility level. Default is "genetlink". enum: [ genetlink, genetlink-c ] @@ -41,11 +42,17 @@ properties: description: Name of the define for the family name. type: string c-version-name: - description: Name of the define for the verion of the family. + description: Name of the define for the version of the family. type: string max-by-define: description: Makes the number of attributes and commands be specified by a define, not an enum value. type: boolean + cmd-max-name: + description: Name of the define for the last operation in the list. + type: string + cmd-cnt-name: + description: The explicit name for constant holding the count of operations (last operation + 1). + type: string # End genetlink-c definitions: @@ -142,13 +149,14 @@ properties: type: array items: type: object - required: [ name, type ] + required: [ name ] additionalProperties: False properties: name: type: string type: &attr-type - enum: [ unused, pad, flag, binary, u8, u16, u32, u64, s32, s64, + enum: [ unused, pad, flag, binary, + uint, sint, u8, u16, u32, u64, s32, s64, string, nest, array-nest, nest-type-value ] doc: description: Documentation of the attribute. @@ -187,13 +195,19 @@ properties: type: string min: description: Min value for an integer attribute. - type: integer + $ref: '#/$defs/len-or-limit' + max: + description: Max value for an integer attribute. + $ref: '#/$defs/len-or-limit' min-len: description: Min length for a binary attribute. $ref: '#/$defs/len-or-define' max-len: description: Max length for a string or a binary attribute. $ref: '#/$defs/len-or-define' + exact-len: + description: Exact length for a string or a binary attribute. + $ref: '#/$defs/len-or-define' sub-type: *attr-type display-hint: &display-hint description: | @@ -215,6 +229,18 @@ properties: not: required: [ name-prefix ] + # type property is only required if not in subset definition + if: + properties: + subset-of: + not: + type: string + then: + properties: + attributes: + items: + required: [ type ] + operations: description: Operations supported by the protocol. type: object @@ -274,7 +300,12 @@ properties: description: Kernel attribute validation flags. type: array items: - enum: [ strict, dump ] + enum: [ strict, dump, dump-strict ] + config-cond: + description: | + Name of the kernel config option gating the presence of + the operation, without the 'CONFIG_' prefix. + type: string do: &subop-type description: Main command handler. type: object diff --git a/Documentation/netlink/genetlink-legacy.yaml b/Documentation/netlink/genetlink-legacy.yaml index 43b769c98fb2..938703088306 100644 --- a/Documentation/netlink/genetlink-legacy.yaml +++ b/Documentation/netlink/genetlink-legacy.yaml @@ -13,6 +13,11 @@ $defs: type: [ string, integer ] pattern: ^[0-9A-Za-z_]+( - 1)?$ minimum: 0 + len-or-limit: + # literal int or limit based on fixed-width type e.g. u8-min, u16-max, etc. + type: [ string, integer ] + pattern: ^[su](8|16|32|64)-(min|max)$ + minimum: 0 # Schema for specs title: Protocol @@ -26,10 +31,6 @@ properties: type: string doc: type: string - version: - description: Generic Netlink family version. Default is 1. - type: integer - minimum: 1 protocol: description: Schema compatibility level. Default is "genetlink". enum: [ genetlink, genetlink-c, genetlink-legacy ] # Trim @@ -41,11 +42,17 @@ properties: description: Name of the define for the family name. type: string c-version-name: - description: Name of the define for the verion of the family. + description: Name of the define for the version of the family. type: string max-by-define: description: Makes the number of attributes and commands be specified by a define, not an enum value. type: boolean + cmd-max-name: + description: Name of the define for the last operation in the list. + type: string + cmd-cnt-name: + description: The explicit name for constant holding the count of operations (last operation + 1). + type: string # End genetlink-c # Start genetlink-legacy kernel-policy: @@ -53,6 +60,10 @@ properties: Defines if the input policy in the kernel is global, per-operation, or split per operation type. Default is split. enum: [ split, per-op, global ] + version: + description: Generic Netlink family version. Default is 1. + type: integer + minimum: 1 # End genetlink-legacy definitions: @@ -180,14 +191,15 @@ properties: type: array items: type: object - required: [ name, type ] + required: [ name ] additionalProperties: False properties: name: type: string type: &attr-type description: The netlink attribute type - enum: [ unused, pad, flag, binary, u8, u16, u32, u64, s32, s64, + enum: [ unused, pad, flag, binary, bitfield32, + uint, sint, u8, u16, u32, u64, s32, s64, string, nest, array-nest, nest-type-value ] doc: description: Documentation of the attribute. @@ -226,13 +238,19 @@ properties: type: string min: description: Min value for an integer attribute. - type: integer + $ref: '#/$defs/len-or-limit' + max: + description: Max value for an integer attribute. + $ref: '#/$defs/len-or-limit' min-len: description: Min length for a binary attribute. $ref: '#/$defs/len-or-define' max-len: description: Max length for a string or a binary attribute. $ref: '#/$defs/len-or-define' + exact-len: + description: Exact length for a string or a binary attribute. + $ref: '#/$defs/len-or-define' sub-type: *attr-type display-hint: *display-hint # Start genetlink-c @@ -254,6 +272,18 @@ properties: not: required: [ name-prefix ] + # type property is only required if not in subset definition + if: + properties: + subset-of: + not: + type: string + then: + properties: + attributes: + items: + required: [ type ] + operations: description: Operations supported by the protocol. type: object @@ -316,12 +346,17 @@ properties: description: Command flags. type: array items: - enum: [ admin-perm ] + enum: [ admin-perm, uns-admin-perm ] dont-validate: description: Kernel attribute validation flags. type: array items: - enum: [ strict, dump ] + enum: [ strict, dump, dump-strict ] + config-cond: + description: | + Name of the kernel config option gating the presence of + the operation, without the 'CONFIG_' prefix. + type: string # Start genetlink-legacy fixed-header: *fixed-header # End genetlink-legacy diff --git a/Documentation/netlink/genetlink.yaml b/Documentation/netlink/genetlink.yaml index 1cbb448d2f1c..3283bf458ff1 100644 --- a/Documentation/netlink/genetlink.yaml +++ b/Documentation/netlink/genetlink.yaml @@ -13,6 +13,11 @@ $defs: type: [ string, integer ] pattern: ^[0-9A-Za-z_]+( - 1)?$ minimum: 0 + len-or-limit: + # literal int or limit based on fixed-width type e.g. u8-min, u16-max, etc. + type: [ string, integer ] + pattern: ^[su](8|16|32|64)-(min|max)$ + minimum: 0 # Schema for specs title: Protocol @@ -26,10 +31,6 @@ properties: type: string doc: type: string - version: - description: Generic Netlink family version. Default is 1. - type: integer - minimum: 1 protocol: description: Schema compatibility level. Default is "genetlink". enum: [ genetlink ] @@ -115,13 +116,14 @@ properties: type: array items: type: object - required: [ name, type ] + required: [ name ] additionalProperties: False properties: name: type: string type: &attr-type - enum: [ unused, pad, flag, binary, u8, u16, u32, u64, s32, s64, + enum: [ unused, pad, flag, binary, + uint, sint, u8, u16, u32, u64, s32, s64, string, nest, array-nest, nest-type-value ] doc: description: Documentation of the attribute. @@ -160,13 +162,19 @@ properties: type: string min: description: Min value for an integer attribute. - type: integer + $ref: '#/$defs/len-or-limit' + max: + description: Max value for an integer attribute. + $ref: '#/$defs/len-or-limit' min-len: description: Min length for a binary attribute. $ref: '#/$defs/len-or-define' max-len: description: Max length for a string or a binary attribute. $ref: '#/$defs/len-or-define' + exact-len: + description: Exact length for a string or a binary attribute. + $ref: '#/$defs/len-or-define' sub-type: *attr-type display-hint: &display-hint description: | @@ -184,6 +192,18 @@ properties: not: required: [ name-prefix ] + # type property is only required if not in subset definition + if: + properties: + subset-of: + not: + type: string + then: + properties: + attributes: + items: + required: [ type ] + operations: description: Operations supported by the protocol. type: object @@ -243,7 +263,12 @@ properties: description: Kernel attribute validation flags. type: array items: - enum: [ strict, dump ] + enum: [ strict, dump, dump-strict ] + config-cond: + description: | + Name of the kernel config option gating the presence of + the operation, without the 'CONFIG_' prefix. + type: string do: &subop-type description: Main command handler. type: object diff --git a/Documentation/netlink/netlink-raw.yaml b/Documentation/netlink/netlink-raw.yaml new file mode 100644 index 000000000000..775cce8c548a --- /dev/null +++ b/Documentation/netlink/netlink-raw.yaml @@ -0,0 +1,431 @@ +# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) +%YAML 1.2 +--- +$id: http://kernel.org/schemas/netlink/netlink-raw.yaml# +$schema: https://json-schema.org/draft-07/schema + +# Common defines +$defs: + uint: + type: integer + minimum: 0 + len-or-define: + type: [ string, integer ] + pattern: ^[0-9A-Za-z_]+( - 1)?$ + minimum: 0 + +# Schema for specs +title: Protocol +description: Specification of a raw netlink protocol +type: object +required: [ name, doc, attribute-sets, operations ] +additionalProperties: False +properties: + name: + description: Name of the netlink family. + type: string + doc: + type: string + protocol: + description: Schema compatibility level. + enum: [ netlink-raw ] # Trim + # Start netlink-raw + protonum: + description: Protocol number to use for netlink-raw + type: integer + # End netlink-raw + uapi-header: + description: Path to the uAPI header, default is linux/${family-name}.h + type: string + # Start genetlink-c + c-family-name: + description: Name of the define for the family name. + type: string + c-version-name: + description: Name of the define for the version of the family. + type: string + max-by-define: + description: Makes the number of attributes and commands be specified by a define, not an enum value. + type: boolean + cmd-max-name: + description: Name of the define for the last operation in the list. + type: string + cmd-cnt-name: + description: The explicit name for constant holding the count of operations (last operation + 1). + type: string + # End genetlink-c + # Start genetlink-legacy + kernel-policy: + description: | + Defines if the input policy in the kernel is global, per-operation, or split per operation type. + Default is split. + enum: [ split, per-op, global ] + # End genetlink-legacy + + definitions: + description: List of type and constant definitions (enums, flags, defines). + type: array + items: + type: object + required: [ type, name ] + additionalProperties: False + properties: + name: + type: string + header: + description: For C-compatible languages, header which already defines this value. + type: string + type: + enum: [ const, enum, flags, struct ] # Trim + doc: + type: string + # For const + value: + description: For const - the value. + type: [ string, integer ] + # For enum and flags + value-start: + description: For enum or flags the literal initializer for the first value. + type: [ string, integer ] + entries: + description: For enum or flags array of values. + type: array + items: + oneOf: + - type: string + - type: object + required: [ name ] + additionalProperties: False + properties: + name: + type: string + value: + type: integer + doc: + type: string + render-max: + description: Render the max members for this enum. + type: boolean + # Start genetlink-c + enum-name: + description: Name for enum, if empty no name will be used. + type: [ string, "null" ] + name-prefix: + description: For enum the prefix of the values, optional. + type: string + # End genetlink-c + # Start genetlink-legacy + members: + description: List of struct members. Only scalars and strings members allowed. + type: array + items: + type: object + required: [ name, type ] + additionalProperties: False + properties: + name: + type: string + type: + description: The netlink attribute type + enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary ] + len: + $ref: '#/$defs/len-or-define' + byte-order: + enum: [ little-endian, big-endian ] + doc: + description: Documentation for the struct member attribute. + type: string + enum: + description: Name of the enum type used for the attribute. + type: string + enum-as-flags: + description: | + Treat the enum as flags. In most cases enum is either used as flags or as values. + Sometimes, however, both forms are necessary, in which case header contains the enum + form while specific attributes may request to convert the values into a bitfield. + type: boolean + display-hint: &display-hint + description: | + Optional format indicator that is intended only for choosing + the right formatting mechanism when displaying values of this + type. + enum: [ hex, mac, fddi, ipv4, ipv6, uuid ] + # End genetlink-legacy + + attribute-sets: + description: Definition of attribute spaces for this family. + type: array + items: + description: Definition of a single attribute space. + type: object + required: [ name, attributes ] + additionalProperties: False + properties: + name: + description: | + Name used when referring to this space in other definitions, not used outside of the spec. + type: string + name-prefix: + description: | + Prefix for the C enum name of the attributes. Default family[name]-set[name]-a- + type: string + enum-name: + description: Name for the enum type of the attribute. + type: string + doc: + description: Documentation of the space. + type: string + subset-of: + description: | + Name of another space which this is a logical part of. Sub-spaces can be used to define + a limited group of attributes which are used in a nest. + type: string + # Start genetlink-c + attr-cnt-name: + description: The explicit name for constant holding the count of attributes (last attr + 1). + type: string + attr-max-name: + description: The explicit name for last member of attribute enum. + type: string + # End genetlink-c + attributes: + description: List of attributes in the space. + type: array + items: + type: object + required: [ name ] + additionalProperties: False + properties: + name: + type: string + type: &attr-type + description: The netlink attribute type + enum: [ unused, pad, flag, binary, u8, u16, u32, u64, s32, s64, + string, nest, array-nest, nest-type-value ] + doc: + description: Documentation of the attribute. + type: string + value: + description: Value for the enum item representing this attribute in the uAPI. + $ref: '#/$defs/uint' + type-value: + description: Name of the value extracted from the type of a nest-type-value attribute. + type: array + items: + type: string + byte-order: + enum: [ little-endian, big-endian ] + multi-attr: + type: boolean + nested-attributes: + description: Name of the space (sub-space) used inside the attribute. + type: string + enum: + description: Name of the enum type used for the attribute. + type: string + enum-as-flags: + description: | + Treat the enum as flags. In most cases enum is either used as flags or as values. + Sometimes, however, both forms are necessary, in which case header contains the enum + form while specific attributes may request to convert the values into a bitfield. + type: boolean + checks: + description: Kernel input validation. + type: object + additionalProperties: False + properties: + flags-mask: + description: Name of the flags constant on which to base mask (unsigned scalar types only). + type: string + min: + description: Min value for an integer attribute. + type: integer + min-len: + description: Min length for a binary attribute. + $ref: '#/$defs/len-or-define' + max-len: + description: Max length for a string or a binary attribute. + $ref: '#/$defs/len-or-define' + exact-len: + description: Exact length for a string or a binary attribute. + $ref: '#/$defs/len-or-define' + sub-type: *attr-type + display-hint: *display-hint + # Start genetlink-c + name-prefix: + type: string + # End genetlink-c + # Start genetlink-legacy + struct: + description: Name of the struct type used for the attribute. + type: string + # End genetlink-legacy + + # Make sure name-prefix does not appear in subsets (subsets inherit naming) + dependencies: + name-prefix: + not: + required: [ subset-of ] + subset-of: + not: + required: [ name-prefix ] + + # type property is only required if not in subset definition + if: + properties: + subset-of: + not: + type: string + then: + properties: + attributes: + items: + required: [ type ] + + operations: + description: Operations supported by the protocol. + type: object + required: [ list ] + additionalProperties: False + properties: + enum-model: + description: | + The model of assigning values to the operations. + "unified" is the recommended model where all message types belong + to a single enum. + "directional" has the messages sent to the kernel and from the kernel + enumerated separately. + enum: [ unified, directional ] # Trim + name-prefix: + description: | + Prefix for the C enum name of the command. The name is formed by concatenating + the prefix with the upper case name of the command, with dashes replaced by underscores. + type: string + enum-name: + description: Name for the enum type with commands. + type: string + async-prefix: + description: Same as name-prefix but used to render notifications and events to separate enum. + type: string + async-enum: + description: Name for the enum type with notifications/events. + type: string + # Start genetlink-legacy + fixed-header: &fixed-header + description: | + Name of the structure defining the optional fixed-length protocol + header. This header is placed in a message after the netlink and + genetlink headers and before any attributes. + type: string + # End genetlink-legacy + list: + description: List of commands + type: array + items: + type: object + additionalProperties: False + required: [ name, doc ] + properties: + name: + description: Name of the operation, also defining its C enum value in uAPI. + type: string + doc: + description: Documentation for the command. + type: string + value: + description: Value for the enum in the uAPI. + $ref: '#/$defs/uint' + attribute-set: + description: | + Attribute space from which attributes directly in the requests and replies + to this command are defined. + type: string + flags: &cmd_flags + description: Command flags. + type: array + items: + enum: [ admin-perm ] + dont-validate: + description: Kernel attribute validation flags. + type: array + items: + enum: [ strict, dump ] + # Start genetlink-legacy + fixed-header: *fixed-header + # End genetlink-legacy + do: &subop-type + description: Main command handler. + type: object + additionalProperties: False + properties: + request: &subop-attr-list + description: Definition of the request message for a given command. + type: object + additionalProperties: False + properties: + attributes: + description: | + Names of attributes from the attribute-set (not full attribute + definitions, just names). + type: array + items: + type: string + # Start genetlink-legacy + value: + description: | + ID of this message if value for request and response differ, + i.e. requests and responses have different message enums. + $ref: '#/$defs/uint' + # End genetlink-legacy + reply: *subop-attr-list + pre: + description: Hook for a function to run before the main callback (pre_doit or start). + type: string + post: + description: Hook for a function to run after the main callback (post_doit or done). + type: string + dump: *subop-type + notify: + description: Name of the command sharing the reply type with this notification. + type: string + event: + type: object + additionalProperties: False + properties: + attributes: + description: Explicit list of the attributes for the notification. + type: array + items: + type: string + mcgrp: + description: Name of the multicast group generating given notification. + type: string + mcast-groups: + description: List of multicast groups. + type: object + required: [ list ] + additionalProperties: False + properties: + list: + description: List of groups. + type: array + items: + type: object + required: [ name ] + additionalProperties: False + properties: + name: + description: | + The name for the group, used to form the define and the value of the define. + type: string + # Start genetlink-c + c-define-name: + description: Override for the name of the define in C uAPI. + type: string + # End genetlink-c + flags: *cmd_flags + # Start netlink-raw + value: + description: Value of the netlink multicast group in the uAPI. + type: integer + # End netlink-raw diff --git a/Documentation/netlink/specs/devlink.yaml b/Documentation/netlink/specs/devlink.yaml index 5d46ca966979..c6ba4889575a 100644 --- a/Documentation/netlink/specs/devlink.yaml +++ b/Documentation/netlink/specs/devlink.yaml @@ -6,6 +6,171 @@ protocol: genetlink-legacy doc: Partial family for Devlink. +definitions: + - + type: enum + name: sb-pool-type + entries: + - + name: ingress + - + name: egress + - + type: enum + name: port-type + entries: + - + name: notset + - + name: auto + - + name: eth + - + name: ib + - + type: enum + name: port-flavour + entries: + - + name: physical + - + name: cpu + - + name: dsa + - + name: pci_pf + - + name: pci_vf + - + name: virtual + - + name: unused + - + name: pci_sf + - + type: enum + name: port-fn-state + entries: + - + name: inactive + - + name: active + - + type: enum + name: port-fn-opstate + entries: + - + name: detached + - + name: attached + - + type: enum + name: port-fn-attr-cap + entries: + - + name: roce-bit + - + name: migratable-bit + - + type: enum + name: sb-threshold-type + entries: + - + name: static + - + name: dynamic + - + type: enum + name: eswitch-mode + entries: + - + name: legacy + - + name: switchdev + - + type: enum + name: eswitch-inline-mode + entries: + - + name: none + - + name: link + - + name: network + - + name: transport + - + type: enum + name: eswitch-encap-mode + entries: + - + name: none + - + name: basic + - + type: enum + name: dpipe-match-type + entries: + - + name: field-exact + - + type: enum + name: dpipe-action-type + entries: + - + name: field-modify + - + type: enum + name: dpipe-field-mapping-type + entries: + - + name: none + - + name: ifindex + - + type: enum + name: resource-unit + entries: + - + name: entry + - + type: enum + name: reload-action + entries: + - + name: driver-reinit + value: 1 + - + name: fw-activate + - + type: enum + name: param-cmode + entries: + - + name: runtime + - + name: driverinit + - + name: permanent + - + type: enum + name: flash-overwrite + entries: + - + name: settings-bit + - + name: identifiers-bit + - + type: enum + name: trap-action + entries: + - + name: drop + - + name: trap + - + name: mirror + attribute-sets: - name: devlink @@ -21,13 +186,294 @@ attribute-sets: - name: port-index type: u32 + - + name: port-type + type: u16 + enum: port-type + + # TODO: fill in the attributes in between + + - + name: port-split-count + type: u32 + value: 9 + + # TODO: fill in the attributes in between + + - + name: sb-index + type: u32 + value: 11 + + # TODO: fill in the attributes in between + + - + name: sb-pool-index + type: u16 + value: 17 + - + name: sb-pool-type + type: u8 + enum: sb-pool-type + - + name: sb-pool-size + type: u32 + - + name: sb-pool-threshold-type + type: u8 + enum: sb-threshold-type + - + name: sb-threshold + type: u32 + - + name: sb-tc-index + type: u16 + value: 22 # TODO: fill in the attributes in between - + name: eswitch-mode + type: u16 + value: 25 + enum: eswitch-mode + + - + name: eswitch-inline-mode + type: u16 + enum: eswitch-inline-mode + - + name: dpipe-tables + type: nest + nested-attributes: dl-dpipe-tables + - + name: dpipe-table + type: nest + multi-attr: true + nested-attributes: dl-dpipe-table + - + name: dpipe-table-name + type: string + - + name: dpipe-table-size + type: u64 + - + name: dpipe-table-matches + type: nest + nested-attributes: dl-dpipe-table-matches + - + name: dpipe-table-actions + type: nest + nested-attributes: dl-dpipe-table-actions + - + name: dpipe-table-counters-enabled + type: u8 + - + name: dpipe-entries + type: nest + nested-attributes: dl-dpipe-entries + - + name: dpipe-entry + type: nest + multi-attr: true + nested-attributes: dl-dpipe-entry + - + name: dpipe-entry-index + type: u64 + - + name: dpipe-entry-match-values + type: nest + nested-attributes: dl-dpipe-entry-match-values + - + name: dpipe-entry-action-values + type: nest + nested-attributes: dl-dpipe-entry-action-values + - + name: dpipe-entry-counter + type: u64 + - + name: dpipe-match + type: nest + multi-attr: true + nested-attributes: dl-dpipe-match + - + name: dpipe-match-value + type: nest + multi-attr: true + nested-attributes: dl-dpipe-match-value + - + name: dpipe-match-type + type: u32 + enum: dpipe-match-type + - + name: dpipe-action + type: nest + multi-attr: true + nested-attributes: dl-dpipe-action + - + name: dpipe-action-value + type: nest + multi-attr: true + nested-attributes: dl-dpipe-action-value + - + name: dpipe-action-type + type: u32 + enum: dpipe-action-type + - + name: dpipe-value + type: binary + - + name: dpipe-value-mask + type: binary + - + name: dpipe-value-mapping + type: u32 + - + name: dpipe-headers + type: nest + nested-attributes: dl-dpipe-headers + - + name: dpipe-header + type: nest + multi-attr: true + nested-attributes: dl-dpipe-header + - + name: dpipe-header-name + type: string + - + name: dpipe-header-id + type: u32 + - + name: dpipe-header-fields + type: nest + nested-attributes: dl-dpipe-header-fields + - + name: dpipe-header-global + type: u8 + - + name: dpipe-header-index + type: u32 + - + name: dpipe-field + type: nest + multi-attr: true + nested-attributes: dl-dpipe-field + - + name: dpipe-field-name + type: string + - + name: dpipe-field-id + type: u32 + - + name: dpipe-field-bitwidth + type: u32 + - + name: dpipe-field-mapping-type + type: u32 + enum: dpipe-field-mapping-type + - + name: pad + type: pad + - + name: eswitch-encap-mode + type: u8 + value: 62 + enum: eswitch-encap-mode + - + name: resource-list + type: nest + nested-attributes: dl-resource-list + - + name: resource + type: nest + multi-attr: true + nested-attributes: dl-resource + - + name: resource-name + type: string + - + name: resource-id + type: u64 + - + name: resource-size + type: u64 + - + name: resource-size-new + type: u64 + - + name: resource-size-valid + type: u8 + - + name: resource-size-min + type: u64 + - + name: resource-size-max + type: u64 + - + name: resource-size-gran + type: u64 + - + name: resource-unit + type: u8 + enum: resource-unit + - + name: resource-occ + type: u64 + - + name: dpipe-table-resource-id + type: u64 + - + name: dpipe-table-resource-units + type: u64 + - + name: port-flavour + type: u16 + enum: port-flavour + + # TODO: fill in the attributes in between + + - + name: param-name + type: string + value: 81 + + # TODO: fill in the attributes in between + + - + name: param-type + type: u8 + value: 83 + + # TODO: fill in the attributes in between + + - + name: param-value-cmode + type: u8 + enum: param-cmode + value: 87 + - + name: region-name + type: string + + # TODO: fill in the attributes in between + + - + name: region-snapshot-id + type: u32 + value: 92 + + # TODO: fill in the attributes in between + + - + name: region-chunk-addr + type: u64 + value: 96 + - + name: region-chunk-len + type: u64 + - name: info-driver-name type: string - value: 98 - name: info-serial-number type: string @@ -56,23 +502,143 @@ attribute-sets: # TODO: fill in the attributes in between - + name: fmsg + type: nest + nested-attributes: dl-fmsg + value: 106 + - + name: fmsg-obj-nest-start + type: flag + - + name: fmsg-pair-nest-start + type: flag + - + name: fmsg-arr-nest-start + type: flag + - + name: fmsg-nest-end + type: flag + - + name: fmsg-obj-name + type: string + + # TODO: fill in the attributes in between + + - + name: health-reporter-name + type: string + value: 115 + + # TODO: fill in the attributes in between + + - + name: health-reporter-graceful-period + type: u64 + value: 120 + - + name: health-reporter-auto-recover + type: u8 + - + name: flash-update-file-name + type: string + - + name: flash-update-component + type: string + + # TODO: fill in the attributes in between + + - + name: port-pci-pf-number + type: u16 + value: 127 + + # TODO: fill in the attributes in between + + - + name: trap-name + type: string + value: 130 + - + name: trap-action + type: u8 + enum: trap-action + + # TODO: fill in the attributes in between + + - + name: trap-group-name + type: string + value: 135 + + - name: reload-failed type: u8 - value: 136 # TODO: fill in the attributes in between - - name: reload-action + name: netns-fd + type: u32 + value: 138 + - + name: netns-pid + type: u32 + - + name: netns-id + type: u32 + + # TODO: fill in the attributes in between + + - + name: health-reporter-auto-dump type: u8 - value: 153 + value: 141 + - + name: trap-policer-id + type: u32 + - + name: trap-policer-rate + type: u64 + - + name: trap-policer-burst + type: u64 + - + name: port-function + type: nest + nested-attributes: dl-port-function # TODO: fill in the attributes in between - + name: port-controller-number + type: u32 + value: 150 + + # TODO: fill in the attributes in between + + - + name: flash-update-overwrite-mask + type: bitfield32 + enum: flash-overwrite + enum-as-flags: True + value: 152 + - + name: reload-action + type: u8 + enum: reload-action + - + name: reload-actions-performed + type: bitfield32 + enum: reload-action + enum-as-flags: True + - + name: reload-limits + type: bitfield32 + enum: reload-action + enum-as-flags: True + - name: dev-stats type: nest - value: 156 nested-attributes: dl-dev-stats - name: reload-stats @@ -103,60 +669,360 @@ attribute-sets: type: nest multi-attr: true nested-attributes: dl-reload-act-stats + + # TODO: fill in the attributes in between + + - + name: port-pci-sf-number + type: u32 + value: 164 + + # TODO: fill in the attributes in between + + - + name: rate-tx-share + type: u64 + value: 166 + - + name: rate-tx-max + type: u64 + - + name: rate-node-name + type: string + - + name: rate-parent-node-name + type: string + + # TODO: fill in the attributes in between + + - + name: linecard-index + type: u32 + value: 171 + + # TODO: fill in the attributes in between + + - + name: linecard-type + type: string + value: 173 + + # TODO: fill in the attributes in between + + - + name: selftests + type: nest + value: 176 + nested-attributes: dl-selftest-id + - + name: rate-tx-priority + type: u32 + - + name: rate-tx-weight + type: u32 + - + name: region-direct + type: flag + - name: dl-dev-stats subset-of: devlink attributes: - name: reload-stats - type: nest - name: remote-reload-stats - type: nest - name: dl-reload-stats subset-of: devlink attributes: - name: reload-action-info - type: nest - name: dl-reload-act-info subset-of: devlink attributes: - name: reload-action - type: u8 - name: reload-action-stats - type: nest - name: dl-reload-act-stats subset-of: devlink attributes: - name: reload-stats-entry - type: nest - name: dl-reload-stats-entry subset-of: devlink attributes: - name: reload-stats-limit - type: u8 - name: reload-stats-value - type: u32 - name: dl-info-version subset-of: devlink attributes: - name: info-version-name - type: string - name: info-version-value - type: string + - + name: dl-port-function + name-prefix: devlink-port-fn-attr- + attr-max-name: devlink-port-function-attr-max + attributes: + - + name-prefix: devlink-port-function-attr- + name: hw-addr + type: binary + value: 1 + - + name: state + type: u8 + enum: port-fn-state + - + name: opstate + type: u8 + enum: port-fn-opstate + - + name: caps + type: bitfield32 + enum: port-fn-attr-cap + enum-as-flags: True + + - + name: dl-dpipe-tables + subset-of: devlink + attributes: + - + name: dpipe-table + + - + name: dl-dpipe-table + subset-of: devlink + attributes: + - + name: dpipe-table-name + - + name: dpipe-table-size + - + name: dpipe-table-name + - + name: dpipe-table-size + - + name: dpipe-table-matches + - + name: dpipe-table-actions + - + name: dpipe-table-counters-enabled + - + name: dpipe-table-resource-id + - + name: dpipe-table-resource-units + + - + name: dl-dpipe-table-matches + subset-of: devlink + attributes: + - + name: dpipe-match + + - + name: dl-dpipe-table-actions + subset-of: devlink + attributes: + - + name: dpipe-action + + - + name: dl-dpipe-entries + subset-of: devlink + attributes: + - + name: dpipe-entry + + - + name: dl-dpipe-entry + subset-of: devlink + attributes: + - + name: dpipe-entry-index + - + name: dpipe-entry-match-values + - + name: dpipe-entry-action-values + - + name: dpipe-entry-counter + + - + name: dl-dpipe-entry-match-values + subset-of: devlink + attributes: + - + name: dpipe-match-value + + - + name: dl-dpipe-entry-action-values + subset-of: devlink + attributes: + - + name: dpipe-action-value + + - + name: dl-dpipe-match + subset-of: devlink + attributes: + - + name: dpipe-match-type + - + name: dpipe-header-id + - + name: dpipe-header-global + - + name: dpipe-header-index + - + name: dpipe-field-id + + - + name: dl-dpipe-match-value + subset-of: devlink + attributes: + - + name: dpipe-match + - + name: dpipe-value + - + name: dpipe-value-mask + - + name: dpipe-value-mapping + + - + name: dl-dpipe-action + subset-of: devlink + attributes: + - + name: dpipe-action-type + - + name: dpipe-header-id + - + name: dpipe-header-global + - + name: dpipe-header-index + - + name: dpipe-field-id + + - + name: dl-dpipe-action-value + subset-of: devlink + attributes: + - + name: dpipe-action + - + name: dpipe-value + - + name: dpipe-value-mask + - + name: dpipe-value-mapping + + - + name: dl-dpipe-headers + subset-of: devlink + attributes: + - + name: dpipe-header + + - + name: dl-dpipe-header + subset-of: devlink + attributes: + - + name: dpipe-header-name + - + name: dpipe-header-id + - + name: dpipe-header-global + - + name: dpipe-header-fields + + - + name: dl-dpipe-header-fields + subset-of: devlink + attributes: + - + name: dpipe-field + + - + name: dl-dpipe-field + subset-of: devlink + attributes: + - + name: dpipe-field-name + - + name: dpipe-field-id + - + name: dpipe-field-bitwidth + - + name: dpipe-field-mapping-type + + - + name: dl-resource + subset-of: devlink + attributes: + # - + # name: resource-list + # This is currently unsupported due to circular dependency + - + name: resource-name + - + name: resource-id + - + name: resource-size + - + name: resource-size-new + - + name: resource-size-valid + - + name: resource-size-min + - + name: resource-size-max + - + name: resource-size-gran + - + name: resource-unit + - + name: resource-occ + + - + name: dl-resource-list + subset-of: devlink + attributes: + - + name: resource + + - + name: dl-fmsg + subset-of: devlink + attributes: + - + name: fmsg-obj-nest-start + - + name: fmsg-pair-nest-start + - + name: fmsg-arr-nest-start + - + name: fmsg-nest-end + - + name: fmsg-obj-name + + - + name: dl-selftest-id + name-prefix: devlink-attr-selftest-id- + attributes: + - + name: flash + type: flag operations: enum-model: directional @@ -165,8 +1031,10 @@ operations: name: get doc: Get devlink instances. attribute-set: devlink - + dont-validate: [ strict, dump ] do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit request: value: 1 attributes: &dev-id-attrs @@ -178,23 +1046,616 @@ operations: - bus-name - dev-name - reload-failed - - reload-action - dev-stats dump: reply: *get-reply - # TODO: fill in the operations in between + - + name: port-get + doc: Get devlink port instances. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + value: 5 + attributes: &port-id-attrs + - bus-name + - dev-name + - port-index + reply: + value: 7 + attributes: *port-id-attrs + dump: + request: + attributes: *dev-id-attrs + reply: + value: 3 # due to a bug, port dump returns DEVLINK_CMD_NEW + attributes: *port-id-attrs + - + name: port-set + doc: Set devlink port instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - port-index + - port-type + - port-function + + - + name: port-new + doc: Create devlink port instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - port-index + - port-flavour + - port-pci-pf-number + - port-pci-sf-number + - port-controller-number + reply: + value: 7 + attributes: *port-id-attrs + + - + name: port-del + doc: Delete devlink port instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + attributes: *port-id-attrs + + - + name: port-split + doc: Split devlink port instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - port-index + - port-split-count + + - + name: port-unsplit + doc: Unplit devlink port instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + attributes: *port-id-attrs + + - + name: sb-get + doc: Get shared buffer instances. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + value: 11 + attributes: &sb-id-attrs + - bus-name + - dev-name + - sb-index + reply: &sb-get-reply + value: 13 + attributes: *sb-id-attrs + dump: + request: + attributes: *dev-id-attrs + reply: *sb-get-reply + + - + name: sb-pool-get + doc: Get shared buffer pool instances. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + value: 15 + attributes: &sb-pool-id-attrs + - bus-name + - dev-name + - sb-index + - sb-pool-index + reply: &sb-pool-get-reply + value: 17 + attributes: *sb-pool-id-attrs + dump: + request: + attributes: *dev-id-attrs + reply: *sb-pool-get-reply + + - + name: sb-pool-set + doc: Set shared buffer pool instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - sb-index + - sb-pool-index + - sb-pool-threshold-type + - sb-pool-size + + - + name: sb-port-pool-get + doc: Get shared buffer port-pool combinations and threshold. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + value: 19 + attributes: &sb-port-pool-id-attrs + - bus-name + - dev-name + - port-index + - sb-index + - sb-pool-index + reply: &sb-port-pool-get-reply + value: 21 + attributes: *sb-port-pool-id-attrs + dump: + request: + attributes: *dev-id-attrs + reply: *sb-port-pool-get-reply + + - + name: sb-port-pool-set + doc: Set shared buffer port-pool combinations and threshold. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - port-index + - sb-index + - sb-pool-index + - sb-threshold + + - + name: sb-tc-pool-bind-get + doc: Get shared buffer port-TC to pool bindings and threshold. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + value: 23 + attributes: &sb-tc-pool-bind-id-attrs + - bus-name + - dev-name + - port-index + - sb-index + - sb-pool-type + - sb-tc-index + reply: &sb-tc-pool-bind-get-reply + value: 25 + attributes: *sb-tc-pool-bind-id-attrs + dump: + request: + attributes: *dev-id-attrs + reply: *sb-tc-pool-bind-get-reply + + - + name: sb-tc-pool-bind-set + doc: Set shared buffer port-TC to pool bindings and threshold. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - port-index + - sb-index + - sb-pool-index + - sb-pool-type + - sb-tc-index + - sb-threshold + + - + name: sb-occ-snapshot + doc: Take occupancy snapshot of shared buffer. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + value: 27 + attributes: + - bus-name + - dev-name + - sb-index + + - + name: sb-occ-max-clear + doc: Clear occupancy watermarks of shared buffer. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - sb-index + + - + name: eswitch-get + doc: Get eswitch attributes. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: *dev-id-attrs + reply: + value: 29 + attributes: &eswitch-attrs + - bus-name + - dev-name + - eswitch-mode + - eswitch-inline-mode + - eswitch-encap-mode + + - + name: eswitch-set + doc: Set eswitch attributes. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: *eswitch-attrs + + - + name: dpipe-table-get + doc: Get dpipe table attributes. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - dpipe-table-name + reply: + value: 31 + attributes: + - bus-name + - dev-name + - dpipe-tables + + - + name: dpipe-entries-get + doc: Get dpipe entries attributes. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - dpipe-table-name + reply: + attributes: + - bus-name + - dev-name + - dpipe-entries + + - + name: dpipe-headers-get + doc: Get dpipe headers attributes. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + reply: + attributes: + - bus-name + - dev-name + - dpipe-headers + + - + name: dpipe-table-counters-set + doc: Set dpipe counter attributes. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - dpipe-table-name + - dpipe-table-counters-enabled + + - + name: resource-set + doc: Set resource attributes. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - resource-id + - resource-size + + - + name: resource-dump + doc: Get resource attributes. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + reply: + value: 36 + attributes: + - bus-name + - dev-name + - resource-list + + - + name: reload + doc: Reload devlink. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - reload-action + - reload-limits + - netns-pid + - netns-fd + - netns-id + reply: + attributes: + - bus-name + - dev-name + - reload-actions-performed + + - + name: param-get + doc: Get param instances. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: ¶m-id-attrs + - bus-name + - dev-name + - param-name + reply: ¶m-get-reply + attributes: *param-id-attrs + dump: + request: + attributes: *dev-id-attrs + reply: *param-get-reply + + - + name: param-set + doc: Set param instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - param-name + - param-type + # param-value-data is missing here as the type is variable + - param-value-cmode + + - + name: region-get + doc: Get region instances. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit-port-optional + post: devlink-nl-post-doit + request: + value: 42 + attributes: ®ion-id-attrs + - bus-name + - dev-name + - port-index + - region-name + reply: ®ion-get-reply + value: 42 + attributes: *region-id-attrs + dump: + request: + attributes: *dev-id-attrs + reply: *region-get-reply + + - + name: region-new + doc: Create region snapshot. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port-optional + post: devlink-nl-post-doit + request: + value: 44 + attributes: ®ion-snapshot-id-attrs + - bus-name + - dev-name + - port-index + - region-name + - region-snapshot-id + reply: + value: 44 + attributes: *region-snapshot-id-attrs + + - + name: region-del + doc: Delete region snapshot. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port-optional + post: devlink-nl-post-doit + request: + attributes: *region-snapshot-id-attrs + + - + name: region-read + doc: Read region data. + attribute-set: devlink + dont-validate: [ dump-strict ] + flags: [ admin-perm ] + dump: + request: + attributes: + - bus-name + - dev-name + - port-index + - region-name + - region-snapshot-id + - region-direct + - region-chunk-addr + - region-chunk-len + reply: + value: 46 + attributes: + - bus-name + - dev-name + - port-index + - region-name + + - + name: port-param-get + doc: Get port param instances. + attribute-set: devlink + dont-validate: [ strict, dump-strict ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + attributes: *port-id-attrs + reply: + attributes: *port-id-attrs + dump: + reply: + attributes: *port-id-attrs + + - + name: port-param-set + doc: Set port param instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + attributes: *port-id-attrs - name: info-get doc: Get device information, like driver name, hardware and firmware versions etc. attribute-set: devlink - + dont-validate: [ strict, dump ] do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit request: value: 51 attributes: *dev-id-attrs - reply: + reply: &info-get-reply value: 51 attributes: - bus-name @@ -204,3 +1665,389 @@ operations: - info-version-fixed - info-version-running - info-version-stored + dump: + reply: *info-get-reply + + - + name: health-reporter-get + doc: Get health reporter instances. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit-port-optional + post: devlink-nl-post-doit + request: + attributes: &health-reporter-id-attrs + - bus-name + - dev-name + - port-index + - health-reporter-name + reply: &health-reporter-get-reply + attributes: *health-reporter-id-attrs + dump: + request: + attributes: *port-id-attrs + reply: *health-reporter-get-reply + + - + name: health-reporter-set + doc: Set health reporter instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port-optional + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - port-index + - health-reporter-name + - health-reporter-graceful-period + - health-reporter-auto-recover + - health-reporter-auto-dump + + - + name: health-reporter-recover + doc: Recover health reporter instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port-optional + post: devlink-nl-post-doit + request: + attributes: *health-reporter-id-attrs + + - + name: health-reporter-diagnose + doc: Diagnose health reporter instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port-optional + post: devlink-nl-post-doit + request: + attributes: *health-reporter-id-attrs + + - + name: health-reporter-dump-get + doc: Dump health reporter instances. + attribute-set: devlink + dont-validate: [ dump-strict ] + flags: [ admin-perm ] + dump: + request: + attributes: *health-reporter-id-attrs + reply: + value: 56 + attributes: + - fmsg + + - + name: health-reporter-dump-clear + doc: Clear dump of health reporter instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port-optional + post: devlink-nl-post-doit + request: + attributes: *health-reporter-id-attrs + + - + name: flash-update + doc: Flash update devlink instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - flash-update-file-name + - flash-update-component + - flash-update-overwrite-mask + + - + name: trap-get + doc: Get trap instances. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + value: 61 + attributes: &trap-id-attrs + - bus-name + - dev-name + - trap-name + reply: &trap-get-reply + value: 63 + attributes: *trap-id-attrs + dump: + request: + attributes: *dev-id-attrs + reply: *trap-get-reply + + - + name: trap-set + doc: Set trap instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - trap-name + - trap-action + + - + name: trap-group-get + doc: Get trap group instances. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + value: 65 + attributes: &trap-group-id-attrs + - bus-name + - dev-name + - trap-group-name + reply: &trap-group-get-reply + value: 67 + attributes: *trap-group-id-attrs + dump: + request: + attributes: *dev-id-attrs + reply: *trap-group-get-reply + + - + name: trap-group-set + doc: Set trap group instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - trap-group-name + - trap-action + - trap-policer-id + + - + name: trap-policer-get + doc: Get trap policer instances. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + value: 69 + attributes: &trap-policer-id-attrs + - bus-name + - dev-name + - trap-policer-id + reply: &trap-policer-get-reply + value: 71 + attributes: *trap-policer-id-attrs + dump: + request: + attributes: *dev-id-attrs + reply: *trap-policer-get-reply + + - + name: trap-policer-set + doc: Get trap policer instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - trap-policer-id + - trap-policer-rate + - trap-policer-burst + + - + name: health-reporter-test + doc: Test health reporter instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port-optional + post: devlink-nl-post-doit + request: + value: 73 + attributes: *health-reporter-id-attrs + + - + name: rate-get + doc: Get rate instances. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + value: 74 + attributes: &rate-id-attrs + - bus-name + - dev-name + - port-index + - rate-node-name + reply: &rate-get-reply + value: 76 + attributes: *rate-id-attrs + dump: + request: + attributes: *dev-id-attrs + reply: *rate-get-reply + + - + name: rate-set + doc: Set rate instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - rate-node-name + - rate-tx-share + - rate-tx-max + - rate-tx-priority + - rate-tx-weight + - rate-parent-node-name + + - + name: rate-new + doc: Create rate instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - rate-node-name + - rate-tx-share + - rate-tx-max + - rate-tx-priority + - rate-tx-weight + - rate-parent-node-name + + - + name: rate-del + doc: Delete rate instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - rate-node-name + + - + name: linecard-get + doc: Get line card instances. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + value: 78 + attributes: &linecard-id-attrs + - bus-name + - dev-name + - linecard-index + reply: &linecard-get-reply + value: 80 + attributes: *linecard-id-attrs + dump: + request: + attributes: *dev-id-attrs + reply: *linecard-get-reply + + - + name: linecard-set + doc: Set line card instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - linecard-index + - linecard-type + + - + name: selftests-get + doc: Get device selftest instances. + attribute-set: devlink + dont-validate: [ strict, dump ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + value: 82 + attributes: *dev-id-attrs + reply: &selftests-get-reply + value: 82 + attributes: *dev-id-attrs + dump: + reply: *selftests-get-reply + + - + name: selftests-run + doc: Run device selftest instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - selftests diff --git a/Documentation/netlink/specs/dpll.yaml b/Documentation/netlink/specs/dpll.yaml new file mode 100644 index 000000000000..cf8abe1c0550 --- /dev/null +++ b/Documentation/netlink/specs/dpll.yaml @@ -0,0 +1,510 @@ +# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) + +name: dpll + +doc: DPLL subsystem. + +definitions: + - + type: enum + name: mode + doc: | + working modes a dpll can support, differentiates if and how dpll selects + one of its inputs to syntonize with it, valid values for DPLL_A_MODE + attribute + entries: + - + name: manual + doc: input can be only selected by sending a request to dpll + value: 1 + - + name: automatic + doc: highest prio input pin auto selected by dpll + render-max: true + - + type: enum + name: lock-status + doc: | + provides information of dpll device lock status, valid values for + DPLL_A_LOCK_STATUS attribute + entries: + - + name: unlocked + doc: | + dpll was not yet locked to any valid input (or forced by setting + DPLL_A_MODE to DPLL_MODE_DETACHED) + value: 1 + - + name: locked + doc: | + dpll is locked to a valid signal, but no holdover available + - + name: locked-ho-acq + doc: | + dpll is locked and holdover acquired + - + name: holdover + doc: | + dpll is in holdover state - lost a valid lock or was forced + by disconnecting all the pins (latter possible only + when dpll lock-state was already DPLL_LOCK_STATUS_LOCKED_HO_ACQ, + 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: const + name: temp-divider + value: 1000 + doc: | + temperature divider allowing userspace to calculate the + temperature as float with three digit decimal precision. + Value of (DPLL_A_TEMP / DPLL_TEMP_DIVIDER) is integer part of + temperature value. + Value of (DPLL_A_TEMP % DPLL_TEMP_DIVIDER) is fractional part of + temperature value. + - + type: enum + name: type + doc: type of dpll, valid values for DPLL_A_TYPE attribute + entries: + - + name: pps + doc: dpll produces Pulse-Per-Second signal + value: 1 + - + name: eec + doc: dpll drives the Ethernet Equipment Clock + render-max: true + - + type: enum + name: pin-type + doc: | + defines possible types of a pin, valid values for DPLL_A_PIN_TYPE + attribute + entries: + - + name: mux + doc: aggregates another layer of selectable pins + value: 1 + - + name: ext + doc: external input + - + name: synce-eth-port + doc: ethernet port PHY's recovered clock + - + name: int-oscillator + doc: device internal oscillator + - + name: gnss + doc: GNSS recovered clock + render-max: true + - + type: enum + name: pin-direction + doc: | + defines possible direction of a pin, valid values for + DPLL_A_PIN_DIRECTION attribute + entries: + - + name: input + doc: pin used as a input of a signal + value: 1 + - + name: output + doc: pin used to output the signal + render-max: true + - + type: const + name: pin-frequency-1-hz + value: 1 + - + type: const + name: pin-frequency-10-khz + value: 10000 + - + type: const + name: pin-frequency-77_5-khz + value: 77500 + - + type: const + name: pin-frequency-10-mhz + value: 10000000 + - + type: enum + name: pin-state + doc: | + defines possible states of a pin, valid values for + DPLL_A_PIN_STATE attribute + entries: + - + name: connected + doc: pin connected, active input of phase locked loop + value: 1 + - + name: disconnected + doc: pin disconnected, not considered as a valid input + - + name: selectable + doc: pin enabled for automatic input selection + render-max: true + - + type: flags + name: pin-capabilities + doc: | + defines possible capabilities of a pin, valid flags on + DPLL_A_PIN_CAPABILITIES attribute + entries: + - + name: direction-can-change + doc: pin direction can be changed + - + name: priority-can-change + doc: pin priority can be changed + - + name: state-can-change + doc: pin state can be changed + - + type: const + name: phase-offset-divider + value: 1000 + doc: | + phase offset divider allows userspace to calculate a value of + measured signal phase difference between a pin and dpll device + as a fractional value with three digit decimal precision. + Value of (DPLL_A_PHASE_OFFSET / DPLL_PHASE_OFFSET_DIVIDER) is an + integer part of a measured phase offset value. + Value of (DPLL_A_PHASE_OFFSET % DPLL_PHASE_OFFSET_DIVIDER) is a + fractional part of a measured phase offset value. + +attribute-sets: + - + name: dpll + enum-name: dpll_a + attributes: + - + name: id + type: u32 + - + name: module-name + type: string + - + name: pad + type: pad + - + name: clock-id + type: u64 + - + name: mode + type: u32 + enum: mode + - + name: mode-supported + type: u32 + enum: mode + multi-attr: true + - + name: lock-status + type: u32 + enum: lock-status + - + name: temp + type: s32 + - + name: type + type: u32 + enum: type + - + name: pin + enum-name: dpll_a_pin + attributes: + - + name: id + type: u32 + - + name: parent-id + type: u32 + - + name: module-name + type: string + - + name: pad + type: pad + - + name: clock-id + type: u64 + - + name: board-label + type: string + - + name: panel-label + type: string + - + name: package-label + type: string + - + name: type + type: u32 + enum: pin-type + - + name: direction + type: u32 + enum: pin-direction + - + name: frequency + type: u64 + - + name: frequency-supported + type: nest + multi-attr: true + nested-attributes: frequency-range + - + name: frequency-min + type: u64 + - + name: frequency-max + type: u64 + - + name: prio + type: u32 + - + name: state + type: u32 + enum: pin-state + - + name: capabilities + type: u32 + - + name: parent-device + type: nest + multi-attr: true + nested-attributes: pin-parent-device + - + name: parent-pin + type: nest + multi-attr: true + nested-attributes: pin-parent-pin + - + name: phase-adjust-min + type: s32 + - + name: phase-adjust-max + type: s32 + - + name: phase-adjust + type: s32 + - + name: phase-offset + type: s64 + - + name: pin-parent-device + subset-of: pin + attributes: + - + name: parent-id + - + name: direction + - + name: prio + - + name: state + - + name: phase-offset + - + name: pin-parent-pin + subset-of: pin + attributes: + - + name: parent-id + - + name: state + - + name: frequency-range + subset-of: pin + attributes: + - + name: frequency-min + - + name: frequency-max + +operations: + enum-name: dpll_cmd + list: + - + name: device-id-get + doc: | + Get id of dpll device that matches given attributes + attribute-set: dpll + flags: [ admin-perm ] + + do: + pre: dpll-lock-doit + post: dpll-unlock-doit + request: + attributes: + - module-name + - clock-id + - type + reply: + attributes: + - id + + - + name: device-get + doc: | + Get list of DPLL devices (dump) or attributes of a single dpll device + attribute-set: dpll + flags: [ admin-perm ] + + do: + pre: dpll-pre-doit + post: dpll-post-doit + request: + attributes: + - id + reply: &dev-attrs + attributes: + - id + - module-name + - mode + - mode-supported + - lock-status + - temp + - clock-id + - type + + dump: + pre: dpll-lock-dumpit + post: dpll-unlock-dumpit + reply: *dev-attrs + + - + name: device-set + doc: Set attributes for a DPLL device + attribute-set: dpll + flags: [ admin-perm ] + + do: + pre: dpll-pre-doit + post: dpll-post-doit + request: + attributes: + - id + - + name: device-create-ntf + doc: Notification about device appearing + notify: device-get + mcgrp: monitor + - + name: device-delete-ntf + doc: Notification about device disappearing + notify: device-get + mcgrp: monitor + - + name: device-change-ntf + doc: Notification about device configuration being changed + notify: device-get + mcgrp: monitor + - + name: pin-id-get + doc: | + Get id of a pin that matches given attributes + attribute-set: pin + flags: [ admin-perm ] + + do: + pre: dpll-lock-doit + post: dpll-unlock-doit + request: + attributes: + - module-name + - clock-id + - board-label + - panel-label + - package-label + - type + reply: + attributes: + - id + + - + name: pin-get + doc: | + Get list of pins and its attributes. + - dump request without any attributes given - list all the pins in the + system + - dump request with target dpll - list all the pins registered with + a given dpll device + - do request with target dpll and target pin - single pin attributes + attribute-set: pin + flags: [ admin-perm ] + + do: + pre: dpll-pin-pre-doit + post: dpll-pin-post-doit + request: + attributes: + - id + reply: &pin-attrs + attributes: + - id + - board-label + - panel-label + - package-label + - type + - frequency + - frequency-supported + - capabilities + - parent-device + - parent-pin + - phase-adjust-min + - phase-adjust-max + - phase-adjust + + dump: + pre: dpll-lock-dumpit + post: dpll-unlock-dumpit + request: + attributes: + - id + reply: *pin-attrs + + - + name: pin-set + doc: Set attributes of a target pin + attribute-set: pin + flags: [ admin-perm ] + + do: + pre: dpll-pin-pre-doit + post: dpll-pin-post-doit + request: + attributes: + - id + - frequency + - direction + - prio + - state + - parent-device + - parent-pin + - phase-adjust + - + name: pin-create-ntf + doc: Notification about pin appearing + notify: pin-get + mcgrp: monitor + - + name: pin-delete-ntf + doc: Notification about pin disappearing + notify: pin-get + mcgrp: monitor + - + name: pin-change-ntf + doc: Notification about pin configuration being changed + notify: pin-get + mcgrp: monitor + +mcast-groups: + list: + - + name: monitor diff --git a/Documentation/netlink/specs/ethtool.yaml b/Documentation/netlink/specs/ethtool.yaml index 837b565577ca..5c7a65b009b4 100644 --- a/Documentation/netlink/specs/ethtool.yaml +++ b/Documentation/netlink/specs/ethtool.yaml @@ -818,13 +818,10 @@ attribute-sets: attributes: - name: hist-bkt-low - type: u32 - name: hist-bkt-hi - type: u32 - name: hist-val - type: u64 - name: stats attributes: diff --git a/Documentation/netlink/specs/fou.yaml b/Documentation/netlink/specs/fou.yaml index 3e13826a3fdf..0af5ab842c04 100644 --- a/Documentation/netlink/specs/fou.yaml +++ b/Documentation/netlink/specs/fou.yaml @@ -107,16 +107,16 @@ operations: flags: [ admin-perm ] do: - request: &select_attrs + request: &select_attrs attributes: - - af - - ifindex - - port - - peer_port - - local_v4 - - peer_v4 - - local_v6 - - peer_v6 + - af + - ifindex + - port + - peer_port + - local_v4 + - peer_v4 + - local_v6 + - peer_v6 - name: get diff --git a/Documentation/netlink/specs/handshake.yaml b/Documentation/netlink/specs/handshake.yaml index 6d89e30f5fd5..b934cc513e3d 100644 --- a/Documentation/netlink/specs/handshake.yaml +++ b/Documentation/netlink/specs/handshake.yaml @@ -34,16 +34,16 @@ attribute-sets: attributes: - name: cert - type: u32 + type: s32 - name: privkey - type: u32 + type: s32 - name: accept attributes: - name: sockfd - type: u32 + type: s32 - name: handler-class type: u32 @@ -79,7 +79,7 @@ attribute-sets: type: u32 - name: sockfd - type: u32 + type: s32 - name: remote-auth type: u32 diff --git a/Documentation/netlink/specs/mptcp.yaml b/Documentation/netlink/specs/mptcp.yaml new file mode 100644 index 000000000000..49f90cfb4698 --- /dev/null +++ b/Documentation/netlink/specs/mptcp.yaml @@ -0,0 +1,393 @@ +# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) + +name: mptcp_pm +protocol: genetlink-legacy +doc: Multipath TCP. + +c-family-name: mptcp-pm-name +c-version-name: mptcp-pm-ver +max-by-define: true +kernel-policy: per-op +cmd-cnt-name: --mptcp-pm-cmd-after-last + +definitions: + - + type: enum + name: event-type + enum-name: mptcp-event-type + name-prefix: mptcp-event- + entries: + - + name: unspec + doc: unused event + - + name: created + doc: + token, family, saddr4 | saddr6, daddr4 | daddr6, sport, dport + A new MPTCP connection has been created. It is the good time to + allocate memory and send ADD_ADDR if needed. Depending on the + traffic-patterns it can take a long time until the + MPTCP_EVENT_ESTABLISHED is sent. + - + name: established + doc: + token, family, saddr4 | saddr6, daddr4 | daddr6, sport, dport + A MPTCP connection is established (can start new subflows). + - + name: closed + doc: + token + A MPTCP connection has stopped. + - + name: announced + value: 6 + doc: + token, rem_id, family, daddr4 | daddr6 [, dport] + A new address has been announced by the peer. + - + name: removed + doc: + token, rem_id + An address has been lost by the peer. + - + name: sub-established + value: 10 + doc: + token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 | daddr6, sport, + dport, backup, if_idx [, error] + A new subflow has been established. 'error' should not be set. + - + name: sub-closed + doc: + token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 | daddr6, sport, + dport, backup, if_idx [, error] + A subflow has been closed. An error (copy of sk_err) could be set if an + error has been detected for this subflow. + - + name: sub-priority + value: 13 + doc: + token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 | daddr6, sport, + dport, backup, if_idx [, error] + The priority of a subflow has changed. 'error' should not be set. + - + name: listener-created + value: 15 + doc: + family, sport, saddr4 | saddr6 + A new PM listener is created. + - + name: listener-closed + doc: + family, sport, saddr4 | saddr6 + A PM listener is closed. + +attribute-sets: + - + name: address + name-prefix: mptcp-pm-addr-attr- + attributes: + - + name: unspec + type: unused + value: 0 + - + name: family + type: u16 + - + name: id + type: u8 + - + name: addr4 + type: u32 + byte-order: big-endian + - + name: addr6 + type: binary + checks: + exact-len: 16 + - + name: port + type: u16 + byte-order: big-endian + - + name: flags + type: u32 + - + name: if-idx + type: s32 + - + name: subflow-attribute + name-prefix: mptcp-subflow-attr- + attributes: + - + name: unspec + type: unused + value: 0 + - + name: token-rem + type: u32 + - + name: token-loc + type: u32 + - + name: relwrite-seq + type: u32 + - + name: map-seq + type: u64 + - + name: map-sfseq + type: u32 + - + name: ssn-offset + type: u32 + - + name: map-datalen + type: u16 + - + name: flags + type: u32 + - + name: id-rem + type: u8 + - + name: id-loc + type: u8 + - + name: pad + type: pad + - + name: endpoint + name-prefix: mptcp-pm-endpoint- + attributes: + - + name: addr + type: nest + nested-attributes: address + - + name: attr + name-prefix: mptcp-pm-attr- + attr-cnt-name: --mptcp-attr-after-last + attributes: + - + name: unspec + type: unused + value: 0 + - + name: addr + type: nest + nested-attributes: address + - + name: rcv-add-addrs + type: u32 + - + name: subflows + type: u32 + - + name: token + type: u32 + - + name: loc-id + type: u8 + - + name: addr-remote + type: nest + nested-attributes: address + - + name: event-attr + enum-name: mptcp-event-attr + name-prefix: mptcp-attr- + attributes: + - + name: unspec + type: unused + value: 0 + - + name: token + type: u32 + - + name: family + type: u16 + - + name: loc-id + type: u8 + - + name: rem-id + type: u8 + - + name: saddr4 + type: u32 + byte-order: big-endian + - + name: saddr6 + type: binary + checks: + min-len: 16 + - + name: daddr4 + type: u32 + byte-order: big-endian + - + name: daddr6 + type: binary + checks: + min-len: 16 + - + name: sport + type: u16 + byte-order: big-endian + - + name: dport + type: u16 + byte-order: big-endian + - + name: backup + type: u8 + - + name: error + type: u8 + - + name: flags + type: u16 + - + name: timeout + type: u32 + - + name: if_idx + type: u32 + - + name: reset-reason + type: u32 + - + name: reset-flags + type: u32 + - + name: server-side + type: u8 + +operations: + list: + - + name: unspec + doc: unused + value: 0 + - + name: add-addr + doc: Add endpoint + attribute-set: endpoint + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: &add-addr-attrs + request: + attributes: + - addr + - + name: del-addr + doc: Delete endpoint + attribute-set: endpoint + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: *add-addr-attrs + - + name: get-addr + doc: Get endpoint information + attribute-set: endpoint + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: &get-addr-attrs + request: + attributes: + - addr + reply: + attributes: + - addr + dump: + reply: + attributes: + - addr + - + name: flush-addrs + doc: flush addresses + attribute-set: endpoint + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: *add-addr-attrs + - + name: set-limits + doc: Set protocol limits + attribute-set: attr + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: &mptcp-limits + request: + attributes: + - rcv-add-addrs + - subflows + - + name: get-limits + doc: Get protocol limits + attribute-set: attr + dont-validate: [ strict ] + do: &mptcp-get-limits + request: + attributes: + - rcv-add-addrs + - subflows + reply: + attributes: + - rcv-add-addrs + - subflows + - + name: set-flags + doc: Change endpoint flags + attribute-set: attr + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: &mptcp-set-flags + request: + attributes: + - addr + - token + - addr-remote + - + name: announce + doc: announce new sf + attribute-set: attr + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: &announce-add + request: + attributes: + - addr + - token + - + name: remove + doc: announce removal + attribute-set: attr + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: + request: + attributes: + - token + - loc-id + - + name: subflow-create + doc: todo + attribute-set: attr + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: &sf-create + request: + attributes: + - addr + - token + - addr-remote + - + name: subflow-destroy + doc: todo + attribute-set: attr + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: *sf-create diff --git a/Documentation/netlink/specs/netdev.yaml b/Documentation/netlink/specs/netdev.yaml index b99e7ffef7a1..14511b13f305 100644 --- a/Documentation/netlink/specs/netdev.yaml +++ b/Documentation/netlink/specs/netdev.yaml @@ -14,7 +14,7 @@ definitions: - name: basic doc: - XDP feautues set supported by all drivers + XDP features set supported by all drivers (XDP_ABORTED, XDP_DROP, XDP_PASS, XDP_TX) - name: redirect @@ -42,6 +42,19 @@ definitions: doc: This feature informs if netdev implements non-linear XDP buffer support in ndo_xdp_xmit callback. + - + type: flags + name: xdp-rx-metadata + render-max: true + entries: + - + name: timestamp + doc: + Device is capable of exposing receive HW timestamp via bpf_xdp_metadata_rx_timestamp(). + - + name: hash + doc: + Device is capable of exposing receive packet hash via bpf_xdp_metadata_rx_hash(). attribute-sets: - @@ -61,7 +74,18 @@ attribute-sets: doc: Bitmask of enabled xdp-features. type: u64 enum: xdp-act - enum-as-flags: true + - + name: xdp-zc-max-segs + doc: max fragment count supported by ZC driver + type: u32 + checks: + min: 1 + - + name: xdp-rx-metadata-features + doc: Bitmask of supported XDP receive metadata features. + See Documentation/networking/xdp-rx-metadata.rst for more details. + type: u64 + enum: xdp-rx-metadata operations: list: @@ -77,6 +101,8 @@ operations: attributes: - ifindex - xdp-features + - xdp-zc-max-segs + - xdp-rx-metadata-features dump: reply: *dev-all - diff --git a/Documentation/netlink/specs/nfsd.yaml b/Documentation/netlink/specs/nfsd.yaml new file mode 100644 index 000000000000..05acc73e2e33 --- /dev/null +++ b/Documentation/netlink/specs/nfsd.yaml @@ -0,0 +1,89 @@ +# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) + +name: nfsd +protocol: genetlink +uapi-header: linux/nfsd_netlink.h + +doc: NFSD configuration over generic netlink. + +attribute-sets: + - + name: rpc-status + attributes: + - + name: xid + type: u32 + byte-order: big-endian + - + name: flags + type: u32 + - + name: prog + type: u32 + - + name: version + type: u8 + - + name: proc + type: u32 + - + name: service_time + type: s64 + - + name: pad + type: pad + - + name: saddr4 + type: u32 + byte-order: big-endian + display-hint: ipv4 + - + name: daddr4 + type: u32 + byte-order: big-endian + display-hint: ipv4 + - + name: saddr6 + type: binary + display-hint: ipv6 + - + name: daddr6 + type: binary + display-hint: ipv6 + - + name: sport + type: u16 + byte-order: big-endian + - + name: dport + type: u16 + byte-order: big-endian + - + name: compound-ops + type: u32 + multi-attr: true + +operations: + list: + - + name: rpc-status-get + doc: dump pending nfsd rpc + attribute-set: rpc-status + dump: + pre: nfsd-nl-rpc-status-get-start + post: nfsd-nl-rpc-status-get-done + reply: + attributes: + - xid + - flags + - prog + - version + - proc + - service_time + - saddr4 + - daddr4 + - saddr6 + - daddr6 + - sport + - dport + - compound-ops diff --git a/Documentation/netlink/specs/ovs_vport.yaml b/Documentation/netlink/specs/ovs_vport.yaml index 17336455bec1..f65ce62cd60d 100644 --- a/Documentation/netlink/specs/ovs_vport.yaml +++ b/Documentation/netlink/specs/ovs_vport.yaml @@ -82,6 +82,10 @@ attribute-sets: enum-name: ovs-vport-attr attributes: - + name: unspec + type: unused + value: 0 + - name: port-no type: u32 - @@ -121,9 +125,34 @@ operations: name-prefix: ovs-vport-cmd- list: - + name: new + doc: Create a new OVS vport + attribute-set: vport + fixed-header: ovs-header + do: + request: + attributes: + - name + - type + - upcall-pid + - dp-ifindex + - ifindex + - options + - + name: del + doc: Delete existing OVS vport from a data path + attribute-set: vport + fixed-header: ovs-header + do: + request: + attributes: + - dp-ifindex + - port-no + - type + - name + - name: get doc: Get / dump OVS vport configuration and state - value: 3 attribute-set: vport fixed-header: ovs-header do: &vport-get-op diff --git a/Documentation/netlink/specs/rt_addr.yaml b/Documentation/netlink/specs/rt_addr.yaml new file mode 100644 index 000000000000..cbee1cedb177 --- /dev/null +++ b/Documentation/netlink/specs/rt_addr.yaml @@ -0,0 +1,179 @@ +# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) + +name: rt-addr +protocol: netlink-raw +protonum: 0 + +doc: + Address configuration over rtnetlink. + +definitions: + - + name: ifaddrmsg + type: struct + members: + - + name: ifa-family + type: u8 + - + name: ifa-prefixlen + type: u8 + - + name: ifa-flags + type: u8 + enum: ifa-flags + enum-as-flags: true + - + name: ifa-scope + type: u8 + - + name: ifa-index + type: u32 + - + name: ifa-cacheinfo + type: struct + members: + - + name: ifa-prefered + type: u32 + - + name: ifa-valid + type: u32 + - + name: cstamp + type: u32 + - + name: tstamp + type: u32 + + - + name: ifa-flags + type: flags + entries: + - + name: secondary + - + name: nodad + - + name: optimistic + - + name: dadfailed + - + name: homeaddress + - + name: deprecated + - + name: tentative + - + name: permanent + - + name: managetempaddr + - + name: noprefixroute + - + name: mcautojoin + - + name: stable-privacy + +attribute-sets: + - + name: addr-attrs + attributes: + - + name: ifa-address + type: binary + display-hint: ipv4 + - + name: ifa-local + type: binary + display-hint: ipv4 + - + name: ifa-label + type: string + - + name: ifa-broadcast + type: binary + display-hint: ipv4 + - + name: ifa-anycast + type: binary + - + name: ifa-cacheinfo + type: binary + struct: ifa-cacheinfo + - + name: ifa-multicast + type: binary + - + name: ifa-flags + type: u32 + enum: ifa-flags + enum-as-flags: true + - + name: ifa-rt-priority + type: u32 + - + name: ifa-target-netnsid + type: binary + - + name: ifa-proto + type: u8 + + +operations: + fixed-header: ifaddrmsg + enum-model: directional + list: + - + name: newaddr + doc: Add new address + attribute-set: addr-attrs + do: + request: + value: 20 + attributes: &ifaddr-all + - ifa-family + - ifa-flags + - ifa-prefixlen + - ifa-scope + - ifa-index + - ifa-address + - ifa-label + - ifa-local + - ifa-cacheinfo + - + name: deladdr + doc: Remove address + attribute-set: addr-attrs + do: + request: + value: 21 + attributes: + - ifa-family + - ifa-flags + - ifa-prefixlen + - ifa-scope + - ifa-index + - ifa-address + - ifa-local + - + name: getaddr + doc: Dump address information. + attribute-set: addr-attrs + dump: + request: + value: 22 + attributes: + - ifa-index + reply: + value: 20 + attributes: *ifaddr-all + +mcast-groups: + list: + - + name: rtnlgrp-ipv4-ifaddr + value: 5 + - + name: rtnlgrp-ipv6-ifaddr + value: 9 diff --git a/Documentation/netlink/specs/rt_link.yaml b/Documentation/netlink/specs/rt_link.yaml new file mode 100644 index 000000000000..d86a68f8475c --- /dev/null +++ b/Documentation/netlink/specs/rt_link.yaml @@ -0,0 +1,1432 @@ +# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) + +name: rt-link +protocol: netlink-raw +protonum: 0 + +doc: + Link configuration over rtnetlink. + +definitions: + - + name: ifinfo-flags + type: flags + entries: + - + name: up + - + name: broadcast + - + name: debug + - + name: loopback + - + name: point-to-point + - + name: no-trailers + - + name: running + - + name: no-arp + - + name: promisc + - + name: all-multi + - + name: master + - + name: slave + - + name: multicast + - + name: portsel + - + name: auto-media + - + name: dynamic + - + name: lower-up + - + name: dormant + - + name: echo + + - + name: rtgenmsg + type: struct + members: + - + name: family + type: u8 + - + name: ifinfomsg + type: struct + members: + - + name: ifi-family + type: u8 + - + name: padding + type: u8 + - + name: ifi-type + type: u16 + - + name: ifi-index + type: s32 + - + name: ifi-flags + type: u32 + enum: ifinfo-flags + enum-as-flags: true + - + name: ifi-change + type: u32 + - + name: ifla-cacheinfo + type: struct + members: + - + name: max-reasm-len + type: u32 + - + name: tstamp + type: u32 + - + name: reachable-time + type: s32 + - + name: retrans-time + type: u32 + - + name: rtnl-link-stats + type: struct + members: + - + name: rx-packets + type: u32 + - + name: tx-packets + type: u32 + - + name: rx-bytes + type: u32 + - + name: tx-bytes + type: u32 + - + name: rx-errors + type: u32 + - + name: tx-errors + type: u32 + - + name: rx-dropped + type: u32 + - + name: tx-dropped + type: u32 + - + name: multicast + type: u32 + - + name: collisions + type: u32 + - + name: rx-length-errors + type: u32 + - + name: rx-over-errors + type: u32 + - + name: rx-crc-errors + type: u32 + - + name: rx-frame-errors + type: u32 + - + name: rx-fifo-errors + type: u32 + - + name: rx-missed-errors + type: u32 + - + name: tx-aborted-errors + type: u32 + - + name: tx-carrier-errors + type: u32 + - + name: tx-fifo-errors + type: u32 + - + name: tx-heartbeat-errors + type: u32 + - + name: tx-window-errors + type: u32 + - + name: rx-compressed + type: u32 + - + name: tx-compressed + type: u32 + - + name: rx-nohandler + type: u32 + - + name: rtnl-link-stats64 + type: struct + members: + - + name: rx-packets + type: u64 + - + name: tx-packets + type: u64 + - + name: rx-bytes + type: u64 + - + name: tx-bytes + type: u64 + - + name: rx-errors + type: u64 + - + name: tx-errors + type: u64 + - + name: rx-dropped + type: u64 + - + name: tx-dropped + type: u64 + - + name: multicast + type: u64 + - + name: collisions + type: u64 + - + name: rx-length-errors + type: u64 + - + name: rx-over-errors + type: u64 + - + name: rx-crc-errors + type: u64 + - + name: rx-frame-errors + type: u64 + - + name: rx-fifo-errors + type: u64 + - + name: rx-missed-errors + type: u64 + - + name: tx-aborted-errors + type: u64 + - + name: tx-carrier-errors + type: u64 + - + name: tx-fifo-errors + type: u64 + - + name: tx-heartbeat-errors + type: u64 + - + name: tx-window-errors + type: u64 + - + name: rx-compressed + type: u64 + - + name: tx-compressed + type: u64 + - + name: rx-nohandler + type: u64 + - + name: rx-otherhost-dropped + type: u64 + - + name: rtnl-link-ifmap + type: struct + members: + - + name: mem-start + type: u64 + - + name: mem-end + type: u64 + - + name: base-addr + type: u64 + - + name: irq + type: u16 + - + name: dma + type: u8 + - + name: port + type: u8 + - + name: ipv4-devconf + type: struct + members: + - + name: forwarding + type: u32 + - + name: mc-forwarding + type: u32 + - + name: proxy-arp + type: u32 + - + name: accept-redirects + type: u32 + - + name: secure-redirects + type: u32 + - + name: send-redirects + type: u32 + - + name: shared-media + type: u32 + - + name: rp-filter + type: u32 + - + name: accept-source-route + type: u32 + - + name: bootp-relay + type: u32 + - + name: log-martians + type: u32 + - + name: tag + type: u32 + - + name: arpfilter + type: u32 + - + name: medium-id + type: u32 + - + name: noxfrm + type: u32 + - + name: nopolicy + type: u32 + - + name: force-igmp-version + type: u32 + - + name: arp-announce + type: u32 + - + name: arp-ignore + type: u32 + - + name: promote-secondaries + type: u32 + - + name: arp-accept + type: u32 + - + name: arp-notify + type: u32 + - + name: accept-local + type: u32 + - + name: src-vmark + type: u32 + - + name: proxy-arp-pvlan + type: u32 + - + name: route-localnet + type: u32 + - + name: igmpv2-unsolicited-report-interval + type: u32 + - + name: igmpv3-unsolicited-report-interval + type: u32 + - + name: ignore-routes-with-linkdown + type: u32 + - + name: drop-unicast-in-l2-multicast + type: u32 + - + name: drop-gratuitous-arp + type: u32 + - + name: bc-forwarding + type: u32 + - + name: arp-evict-nocarrier + type: u32 + - + name: ipv6-devconf + type: struct + members: + - + name: forwarding + type: u32 + - + name: hoplimit + type: u32 + - + name: mtu6 + type: u32 + - + name: accept-ra + type: u32 + - + name: accept-redirects + type: u32 + - + name: autoconf + type: u32 + - + name: dad-transmits + type: u32 + - + name: rtr-solicits + type: u32 + - + name: rtr-solicit-interval + type: u32 + - + name: rtr-solicit-delay + type: u32 + - + name: use-tempaddr + type: u32 + - + name: temp-valid-lft + type: u32 + - + name: temp-prefered-lft + type: u32 + - + name: regen-max-retry + type: u32 + - + name: max-desync-factor + type: u32 + - + name: max-addresses + type: u32 + - + name: force-mld-version + type: u32 + - + name: accept-ra-defrtr + type: u32 + - + name: accept-ra-pinfo + type: u32 + - + name: accept-ra-rtr-pref + type: u32 + - + name: rtr-probe-interval + type: u32 + - + name: accept-ra-rt-info-max-plen + type: u32 + - + name: proxy-ndp + type: u32 + - + name: optimistic-dad + type: u32 + - + name: accept-source-route + type: u32 + - + name: mc-forwarding + type: u32 + - + name: disable-ipv6 + type: u32 + - + name: accept-dad + type: u32 + - + name: force-tllao + type: u32 + - + name: ndisc-notify + type: u32 + - + name: mldv1-unsolicited-report-interval + type: u32 + - + name: mldv2-unsolicited-report-interval + type: u32 + - + name: suppress-frag-ndisc + type: u32 + - + name: accept-ra-from-local + type: u32 + - + name: use-optimistic + type: u32 + - + name: accept-ra-mtu + type: u32 + - + name: stable-secret + type: u32 + - + name: use-oif-addrs-only + type: u32 + - + name: accept-ra-min-hop-limit + type: u32 + - + name: ignore-routes-with-linkdown + type: u32 + - + name: drop-unicast-in-l2-multicast + type: u32 + - + name: drop-unsolicited-na + type: u32 + - + name: keep-addr-on-down + type: u32 + - + name: rtr-solicit-max-interval + type: u32 + - + name: seg6-enabled + type: u32 + - + name: seg6-require-hmac + type: u32 + - + name: enhanced-dad + type: u32 + - + name: addr-gen-mode + type: u8 + - + name: disable-policy + type: u32 + - + name: accept-ra-rt-info-min-plen + type: u32 + - + name: ndisc-tclass + type: u32 + - + name: rpl-seg-enabled + type: u32 + - + name: ra-defrtr-metric + type: u32 + - + name: ioam6-enabled + type: u32 + - + name: ioam6-id + type: u32 + - + name: ioam6-id-wide + type: u32 + - + name: ndisc-evict-nocarrier + type: u32 + - + name: accept-untracked-na + type: u32 + - + name: ifla-icmp6-stats + type: struct + members: + - + name: inmsgs + type: u64 + - + name: inerrors + type: u64 + - + name: outmsgs + type: u64 + - + name: outerrors + type: u64 + - + name: csumerrors + type: u64 + - + name: ratelimithost + type: u64 + - + name: ifla-inet6-stats + type: struct + members: + - + name: inpkts + type: u64 + - + name: inoctets + type: u64 + - + name: indelivers + type: u64 + - + name: outforwdatagrams + type: u64 + - + name: outpkts + type: u64 + - + name: outoctets + type: u64 + - + name: inhdrerrors + type: u64 + - + name: intoobigerrors + type: u64 + - + name: innoroutes + type: u64 + - + name: inaddrerrors + type: u64 + - + name: inunknownprotos + type: u64 + - + name: intruncatedpkts + type: u64 + - + name: indiscards + type: u64 + - + name: outdiscards + type: u64 + - + name: outnoroutes + type: u64 + - + name: reasmtimeout + type: u64 + - + name: reasmreqds + type: u64 + - + name: reasmoks + type: u64 + - + name: reasmfails + type: u64 + - + name: fragoks + type: u64 + - + name: fragfails + type: u64 + - + name: fragcreates + type: u64 + - + name: inmcastpkts + type: u64 + - + name: outmcastpkts + type: u64 + - + name: inbcastpkts + type: u64 + - + name: outbcastpkts + type: u64 + - + name: inmcastoctets + type: u64 + - + name: outmcastoctets + type: u64 + - + name: inbcastoctets + type: u64 + - + name: outbcastoctets + type: u64 + - + name: csumerrors + type: u64 + - + name: noectpkts + type: u64 + - + name: ect1-pkts + type: u64 + - + name: ect0-pkts + type: u64 + - + name: cepkts + type: u64 + - + name: reasm-overlaps + type: u64 + - name: br-boolopt-multi + type: struct + members: + - + name: optval + type: u32 + - + name: optmask + type: u32 + - + name: if_stats_msg + type: struct + members: + - + name: family + type: u8 + - + name: pad1 + type: u8 + - + name: pad2 + type: u16 + - + name: ifindex + type: u32 + - + name: filter-mask + type: u32 + + +attribute-sets: + - + name: link-attrs + name-prefix: ifla- + attributes: + - + name: address + type: binary + display-hint: mac + - + name: broadcast + type: binary + display-hint: mac + - + name: ifname + type: string + - + name: mtu + type: u32 + - + name: link + type: u32 + - + name: qdisc + type: string + - + name: stats + type: binary + struct: rtnl-link-stats + - + name: cost + type: string + - + name: priority + type: string + - + name: master + type: u32 + - + name: wireless + type: string + - + name: protinfo + type: string + - + name: txqlen + type: u32 + - + name: map + type: binary + struct: rtnl-link-ifmap + - + name: weight + type: u32 + - + name: operstate + type: u8 + - + name: linkmode + type: u8 + - + name: linkinfo + type: nest + nested-attributes: linkinfo-attrs + - + name: net-ns-pid + type: u32 + - + name: ifalias + type: string + - + name: num-vf + type: u32 + - + name: vfinfo-list + type: nest + nested-attributes: vfinfo-attrs + - + name: stats64 + type: binary + struct: rtnl-link-stats64 + - + name: vf-ports + type: nest + nested-attributes: vf-ports-attrs + - + name: port-self + type: nest + nested-attributes: port-self-attrs + - + name: af-spec + type: nest + nested-attributes: af-spec-attrs + - + name: group + type: u32 + - + name: net-ns-fd + type: u32 + - + name: ext-mask + type: u32 + - + name: promiscuity + type: u32 + - + name: num-tx-queues + type: u32 + - + name: num-rx-queues + type: u32 + - + name: carrier + type: u8 + - + name: phys-port-id + type: binary + - + name: carrier-changes + type: u32 + - + name: phys-switch-id + type: binary + - + name: link-netnsid + type: s32 + - + name: phys-port-name + type: string + - + name: proto-down + type: u8 + - + name: gso-max-segs + type: u32 + - + name: gso-max-size + type: u32 + - + name: pad + type: pad + - + name: xdp + type: nest + nested-attributes: xdp-attrs + - + name: event + type: u32 + - + name: new-netnsid + type: s32 + - + name: target-netnsid + type: s32 + - + name: carrier-up-count + type: u32 + - + name: carrier-down-count + type: u32 + - + name: new-ifindex + type: s32 + - + name: min-mtu + type: u32 + - + name: max-mtu + type: u32 + - + name: prop-list + type: nest + nested-attributes: link-attrs + - + name: alt-ifname + type: string + multi-attr: true + - + name: perm-address + type: binary + display-hint: mac + - + name: proto-down-reason + type: string + - + name: parent-dev-name + type: string + - + name: parent-dev-bus-name + type: string + - + name: gro-max-size + type: u32 + - + name: tso-max-size + type: u32 + - + name: tso-max-segs + type: u32 + - + name: allmulti + type: u32 + - + name: devlink-port + type: binary + - + name: gso-ipv4-max-size + type: u32 + - + name: gro-ipv4-max-size + type: u32 + - + name: af-spec-attrs + attributes: + - + name: "inet" + type: nest + value: 2 + nested-attributes: ifla-attrs + - + name: "inet6" + type: nest + value: 10 + nested-attributes: ifla6-attrs + - + name: "mctp" + type: nest + value: 45 + nested-attributes: mctp-attrs + - + name: vfinfo-attrs + attributes: [] + - + name: vf-ports-attrs + attributes: [] + - + name: port-self-attrs + attributes: [] + - + name: linkinfo-attrs + attributes: + - + name: kind + type: string + - + name: data + type: binary + # kind specific nest, e.g. linkinfo-bridge-attrs + - + name: xstats + type: binary + - + name: slave-kind + type: string + - + name: slave-data + type: binary + # kind specific nest + - + name: linkinfo-bridge-attrs + attributes: + - + name: forward-delay + type: u32 + - + name: hello-time + type: u32 + - + name: max-age + type: u32 + - + name: ageing-time + type: u32 + - + name: stp-state + type: u32 + - + name: priority + type: u16 + - + name: vlan-filtering + type: u8 + - + name: vlan-protocol + type: u16 + - + name: group-fwd-mask + type: u16 + - + name: root-id + type: binary + - + name: bridge-id + type: binary + - + name: root-port + type: u16 + - + name: root-path-cost + type: u32 + - + name: topology-change + type: u8 + - + name: topology-change-detected + type: u8 + - + name: hello-timer + type: u64 + - + name: tcn-timer + type: u64 + - + name: topology-change-timer + type: u64 + - + name: gc-timer + type: u64 + - + name: group-addr + type: binary + - + name: fdb-flush + type: binary + - + name: mcast-router + type: u8 + - + name: mcast-snooping + type: u8 + - + name: mcast-query-use-ifaddr + type: u8 + - + name: mcast-querier + type: u8 + - + name: mcast-hash-elasticity + type: u32 + - + name: mcast-hash-max + type: u32 + - + name: mcast-last-member-cnt + type: u32 + - + name: mcast-startup-query-cnt + type: u32 + - + name: mcast-last-member-intvl + type: u64 + - + name: mcast-membership-intvl + type: u64 + - + name: mcast-querier-intvl + type: u64 + - + name: mcast-query-intvl + type: u64 + - + name: mcast-query-response-intvl + type: u64 + - + name: mcast-startup-query-intvl + type: u64 + - + name: nf-call-iptables + type: u8 + - + name: nf-call-ip6-tables + type: u8 + - + name: nf-call-arptables + type: u8 + - + name: vlan-default-pvid + type: u16 + - + name: pad + type: pad + - + name: vlan-stats-enabled + type: u8 + - + name: mcast-stats-enabled + type: u8 + - + name: mcast-igmp-version + type: u8 + - + name: mcast-mld-version + type: u8 + - + name: vlan-stats-per-port + type: u8 + - + name: multi-boolopt + type: binary + struct: br-boolopt-multi + - + name: mcast-querier-state + type: binary + - + name: xdp-attrs + attributes: + - + name: fd + type: s32 + - + name: attached + type: u8 + - + name: flags + type: u32 + - + name: prog-id + type: u32 + - + name: drv-prog-id + type: u32 + - + name: skb-prog-id + type: u32 + - + name: hw-prog-id + type: u32 + - + name: expected-fd + type: s32 + - + name: ifla-attrs + attributes: + - + name: conf + type: binary + struct: ipv4-devconf + - + name: ifla6-attrs + attributes: + - + name: flags + type: u32 + - + name: conf + type: binary + struct: ipv6-devconf + - + name: stats + type: binary + struct: ifla-inet6-stats + - + name: mcast + type: binary + - + name: cacheinfo + type: binary + struct: ifla-cacheinfo + - + name: icmp6-stats + type: binary + struct: ifla-icmp6-stats + - + name: token + type: binary + - + name: addr-gen-mode + type: u8 + - + name: ra-mtu + type: u32 + - + name: mctp-attrs + attributes: + - + name: mctp-net + type: u32 + - + name: stats-attrs + name-prefix: ifla-stats- + attributes: + - + name: link-64 + type: binary + struct: rtnl-link-stats64 + - + name: link-xstats + type: binary + - + name: link-xstats-slave + type: binary + - + name: link-offload-xstats + type: nest + nested-attributes: link-offload-xstats + - + name: af-spec + type: binary + - + name: link-offload-xstats + attributes: + - + name: cpu-hit + type: binary + - + name: hw-s-info + type: array-nest + nested-attributes: hw-s-info-one + - + name: l3-stats + type: binary + - + name: hw-s-info-one + attributes: + - + name: request + type: u8 + - + name: used + type: u8 + +operations: + enum-model: directional + list: + - + name: newlink + doc: Create a new link. + attribute-set: link-attrs + fixed-header: ifinfomsg + do: + request: + value: 16 + attributes: &link-new-attrs + - ifi-index + - ifname + - net-ns-pid + - net-ns-fd + - target-netnsid + - link-netnsid + - linkinfo + - group + - num-tx-queues + - num-rx-queues + - address + - broadcast + - mtu + - txqlen + - operstate + - linkmode + - group + - gso-max-size + - gso-max-segs + - gro-max-size + - gso-ipv4-max-size + - gro-ipv4-max-size + - af-spec + - + name: dellink + doc: Delete an existing link. + attribute-set: link-attrs + fixed-header: ifinfomsg + do: + request: + value: 17 + attributes: + - ifi-index + - ifname + - + name: getlink + doc: Get / dump information about a link. + attribute-set: link-attrs + fixed-header: ifinfomsg + do: + request: + value: 18 + attributes: + - ifi-index + - ifname + - alt-ifname + - ext-mask + - target-netnsid + reply: + value: 16 + attributes: &link-all-attrs + - ifi-family + - ifi-type + - ifi-index + - ifi-flags + - ifi-change + - address + - broadcast + - ifname + - mtu + - link + - qdisc + - stats + - cost + - priority + - master + - wireless + - protinfo + - txqlen + - map + - weight + - operstate + - linkmode + - linkinfo + - net-ns-pid + - ifalias + - num-vf + - vfinfo-list + - stats64 + - vf-ports + - port-self + - af-spec + - group + - net-ns-fd + - ext-mask + - promiscuity + - num-tx-queues + - num-rx-queues + - carrier + - phys-port-id + - carrier-changes + - phys-switch-id + - link-netnsid + - phys-port-name + - proto-down + - gso-max-segs + - gso-max-size + - pad + - xdp + - event + - new-netnsid + - if-netnsid + - target-netnsid + - carrier-up-count + - carrier-down-count + - new-ifindex + - min-mtu + - max-mtu + - prop-list + - alt-ifname + - perm-address + - proto-down-reason + - parent-dev-name + - parent-dev-bus-name + - gro-max-size + - tso-max-size + - tso-max-segs + - allmulti + - devlink-port + - gso-ipv4-max-size + - gro-ipv4-max-size + dump: + request: + value: 18 + attributes: + - target-netnsid + - ext-mask + - master + - linkinfo + reply: + value: 16 + attributes: *link-all-attrs + - + name: setlink + doc: Set information about a link. + attribute-set: link-attrs + fixed-header: ifinfomsg + do: + request: + value: 19 + attributes: *link-all-attrs + - + name: getstats + doc: Get / dump link stats. + attribute-set: stats-attrs + fixed-header: if_stats_msg + do: + request: + value: 94 + attributes: + - ifindex + reply: + value: 92 + attributes: &link-stats-attrs + - family + - ifindex + - filter-mask + - link-64 + - link-xstats + - link-xstats-slave + - link-offload-xstats + - af-spec + dump: + request: + value: 94 + reply: + value: 92 + attributes: *link-stats-attrs + +mcast-groups: + list: + - + name: rtnlgrp-link + value: 1 + - + name: rtnlgrp-stats + value: 36 diff --git a/Documentation/netlink/specs/rt_route.yaml b/Documentation/netlink/specs/rt_route.yaml new file mode 100644 index 000000000000..f4368be0caed --- /dev/null +++ b/Documentation/netlink/specs/rt_route.yaml @@ -0,0 +1,327 @@ +# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) + +name: rt-route +protocol: netlink-raw +protonum: 0 + +doc: + Route configuration over rtnetlink. + +definitions: + - + name: rtm-type + name-prefix: rtn- + type: enum + entries: + - unspec + - unicast + - local + - broadcast + - anycast + - multicast + - blackhole + - unreachable + - prohibit + - throw + - nat + - xresolve + - + name: rtmsg + type: struct + members: + - + name: rtm-family + type: u8 + - + name: rtm-dst-len + type: u8 + - + name: rtm-src-len + type: u8 + - + name: rtm-tos + type: u8 + - + name: rtm-table + type: u8 + - + name: rtm-protocol + type: u8 + - + name: rtm-scope + type: u8 + - + name: rtm-type + type: u8 + enum: rtm-type + - + name: rtm-flags + type: u32 + - + name: rta-cacheinfo + type: struct + members: + - + name: rta-clntref + type: u32 + - + name: rta-lastuse + type: u32 + - + name: rta-expires + type: u32 + - + name: rta-error + type: u32 + - + name: rta-used + type: u32 + +attribute-sets: + - + name: route-attrs + attributes: + - + name: rta-dst + type: binary + display-hint: ipv4 + - + name: rta-src + type: binary + display-hint: ipv4 + - + name: rta-iif + type: u32 + - + name: rta-oif + type: u32 + - + name: rta-gateway + type: binary + display-hint: ipv4 + - + name: rta-priority + type: u32 + - + name: rta-prefsrc + type: binary + display-hint: ipv4 + - + name: rta-metrics + type: nest + nested-attributes: rta-metrics + - + name: rta-multipath + type: binary + - + name: rta-protoinfo # not used + type: binary + - + name: rta-flow + type: u32 + - + name: rta-cacheinfo + type: binary + struct: rta-cacheinfo + - + name: rta-session # not used + type: binary + - + name: rta-mp-algo # not used + type: binary + - + name: rta-table + type: u32 + - + name: rta-mark + type: u32 + - + name: rta-mfc-stats + type: binary + - + name: rta-via + type: binary + - + name: rta-newdst + type: binary + - + name: rta-pref + type: u8 + - + name: rta-encap-type + type: u16 + - + name: rta-encap + type: binary # tunnel specific nest + - + name: rta-expires + type: u32 + - + name: rta-pad + type: binary + - + name: rta-uid + type: u32 + - + name: rta-ttl-propagate + type: u8 + - + name: rta-ip-proto + type: u8 + - + name: rta-sport + type: u16 + - + name: rta-dport + type: u16 + - + name: rta-nh-id + type: u32 + - + name: rta-metrics + attributes: + - + name: rtax-unspec + type: unused + value: 0 + - + name: rtax-lock + type: u32 + - + name: rtax-mtu + type: u32 + - + name: rtax-window + type: u32 + - + name: rtax-rtt + type: u32 + - + name: rtax-rttvar + type: u32 + - + name: rtax-ssthresh + type: u32 + - + name: rtax-cwnd + type: u32 + - + name: rtax-advmss + type: u32 + - + name: rtax-reordering + type: u32 + - + name: rtax-hoplimit + type: u32 + - + name: rtax-initcwnd + type: u32 + - + name: rtax-features + type: u32 + - + name: rtax-rto-min + type: u32 + - + name: rtax-initrwnd + type: u32 + - + name: rtax-quickack + type: u32 + - + name: rtax-cc-algo + type: string + - + name: rtax-fastopen-no-cookie + type: u32 + +operations: + enum-model: directional + list: + - + name: getroute + doc: Dump route information. + attribute-set: route-attrs + fixed-header: rtmsg + do: + request: + value: 26 + attributes: + - rtm-family + - rta-src + - rtm-src-len + - rta-dst + - rtm-dst-len + - rta-iif + - rta-oif + - rta-ip-proto + - rta-sport + - rta-dport + - rta-mark + - rta-uid + reply: + value: 24 + attributes: &all-route-attrs + - rtm-family + - rtm-dst-len + - rtm-src-len + - rtm-tos + - rtm-table + - rtm-protocol + - rtm-scope + - rtm-type + - rtm-flags + - rta-dst + - rta-src + - rta-iif + - rta-oif + - rta-gateway + - rta-priority + - rta-prefsrc + - rta-metrics + - rta-multipath + - rta-flow + - rta-cacheinfo + - rta-table + - rta-mark + - rta-mfc-stats + - rta-via + - rta-newdst + - rta-pref + - rta-encap-type + - rta-encap + - rta-expires + - rta-pad + - rta-uid + - rta-ttl-propagate + - rta-ip-proto + - rta-sport + - rta-dport + - rta-nh-id + dump: + request: + value: 26 + attributes: + - rtm-family + reply: + value: 24 + attributes: *all-route-attrs + - + name: newroute + doc: Create a new route + attribute-set: route-attrs + fixed-header: rtmsg + do: + request: + value: 24 + attributes: *all-route-attrs + - + name: delroute + doc: Delete an existing route + attribute-set: route-attrs + fixed-header: rtmsg + do: + request: + value: 25 + attributes: *all-route-attrs diff --git a/Documentation/networking/af_xdp.rst b/Documentation/networking/af_xdp.rst index 1cc35de336a4..dceeb0d763aa 100644 --- a/Documentation/networking/af_xdp.rst +++ b/Documentation/networking/af_xdp.rst @@ -462,8 +462,92 @@ XDP_OPTIONS getsockopt Gets options from an XDP socket. The only one supported so far is XDP_OPTIONS_ZEROCOPY which tells you if zero-copy is on or not. +Multi-Buffer Support +==================== + +With multi-buffer support, programs using AF_XDP sockets can receive +and transmit packets consisting of multiple buffers both in copy and +zero-copy mode. For example, a packet can consist of two +frames/buffers, one with the header and the other one with the data, +or a 9K Ethernet jumbo frame can be constructed by chaining together +three 4K frames. + +Some definitions: + +* A packet consists of one or more frames + +* A descriptor in one of the AF_XDP rings always refers to a single + frame. In the case the packet consists of a single frame, the + descriptor refers to the whole packet. + +To enable multi-buffer support for an AF_XDP socket, use the new bind +flag XDP_USE_SG. If this is not provided, all multi-buffer packets +will be dropped just as before. Note that the XDP program loaded also +needs to be in multi-buffer mode. This can be accomplished by using +"xdp.frags" as the section name of the XDP program used. + +To represent a packet consisting of multiple frames, a new flag called +XDP_PKT_CONTD is introduced in the options field of the Rx and Tx +descriptors. If it is true (1) the packet continues with the next +descriptor and if it is false (0) it means this is the last descriptor +of the packet. Why the reverse logic of end-of-packet (eop) flag found +in many NICs? Just to preserve compatibility with non-multi-buffer +applications that have this bit set to false for all packets on Rx, +and the apps set the options field to zero for Tx, as anything else +will be treated as an invalid descriptor. + +These are the semantics for producing packets onto AF_XDP Tx ring +consisting of multiple frames: + +* When an invalid descriptor is found, all the other + descriptors/frames of this packet are marked as invalid and not + completed. The next descriptor is treated as the start of a new + packet, even if this was not the intent (because we cannot guess + the intent). As before, if your program is producing invalid + descriptors you have a bug that must be fixed. + +* Zero length descriptors are treated as invalid descriptors. + +* For copy mode, the maximum supported number of frames in a packet is + equal to CONFIG_MAX_SKB_FRAGS + 1. If it is exceeded, all + descriptors accumulated so far are dropped and treated as + invalid. To produce an application that will work on any system + regardless of this config setting, limit the number of frags to 18, + as the minimum value of the config is 17. + +* For zero-copy mode, the limit is up to what the NIC HW + supports. Usually at least five on the NICs we have checked. We + consciously chose to not enforce a rigid limit (such as + CONFIG_MAX_SKB_FRAGS + 1) for zero-copy mode, as it would have + resulted in copy actions under the hood to fit into what limit the + NIC supports. Kind of defeats the purpose of zero-copy mode. How to + probe for this limit is explained in the "probe for multi-buffer + support" section. + +On the Rx path in copy-mode, the xsk core copies the XDP data into +multiple descriptors, if needed, and sets the XDP_PKT_CONTD flag as +detailed before. Zero-copy mode works the same, though the data is not +copied. When the application gets a descriptor with the XDP_PKT_CONTD +flag set to one, it means that the packet consists of multiple buffers +and it continues with the next buffer in the following +descriptor. When a descriptor with XDP_PKT_CONTD == 0 is received, it +means that this is the last buffer of the packet. AF_XDP guarantees +that only a complete packet (all frames in the packet) is sent to the +application. If there is not enough space in the AF_XDP Rx ring, all +frames of the packet will be dropped. + +If application reads a batch of descriptors, using for example the libxdp +interfaces, it is not guaranteed that the batch will end with a full +packet. It might end in the middle of a packet and the rest of the +buffers of that packet will arrive at the beginning of the next batch, +since the libxdp interface does not read the whole ring (unless you +have an enormous batch size or a very small ring size). + +An example program each for Rx and Tx multi-buffer support can be found +later in this document. + Usage -===== +----- In order to use AF_XDP sockets two parts are needed. The user-space application and the XDP program. For a complete setup and @@ -541,6 +625,131 @@ like this: But please use the libbpf functions as they are optimized and ready to use. Will make your life easier. +Usage Multi-Buffer Rx +--------------------- + +Here is a simple Rx path pseudo-code example (using libxdp interfaces +for simplicity). Error paths have been excluded to keep it short: + +.. code-block:: c + + void rx_packets(struct xsk_socket_info *xsk) + { + static bool new_packet = true; + u32 idx_rx = 0, idx_fq = 0; + static char *pkt; + + int rcvd = xsk_ring_cons__peek(&xsk->rx, opt_batch_size, &idx_rx); + + xsk_ring_prod__reserve(&xsk->umem->fq, rcvd, &idx_fq); + + for (int i = 0; i < rcvd; i++) { + struct xdp_desc *desc = xsk_ring_cons__rx_desc(&xsk->rx, idx_rx++); + char *frag = xsk_umem__get_data(xsk->umem->buffer, desc->addr); + bool eop = !(desc->options & XDP_PKT_CONTD); + + if (new_packet) + pkt = frag; + else + add_frag_to_pkt(pkt, frag); + + if (eop) + process_pkt(pkt); + + new_packet = eop; + + *xsk_ring_prod__fill_addr(&xsk->umem->fq, idx_fq++) = desc->addr; + } + + xsk_ring_prod__submit(&xsk->umem->fq, rcvd); + xsk_ring_cons__release(&xsk->rx, rcvd); + } + +Usage Multi-Buffer Tx +--------------------- + +Here is an example Tx path pseudo-code (using libxdp interfaces for +simplicity) ignoring that the umem is finite in size, and that we +eventually will run out of packets to send. Also assumes pkts.addr +points to a valid location in the umem. + +.. code-block:: c + + void tx_packets(struct xsk_socket_info *xsk, struct pkt *pkts, + int batch_size) + { + u32 idx, i, pkt_nb = 0; + + xsk_ring_prod__reserve(&xsk->tx, batch_size, &idx); + + for (i = 0; i < batch_size;) { + u64 addr = pkts[pkt_nb].addr; + u32 len = pkts[pkt_nb].size; + + do { + struct xdp_desc *tx_desc; + + tx_desc = xsk_ring_prod__tx_desc(&xsk->tx, idx + i++); + tx_desc->addr = addr; + + if (len > xsk_frame_size) { + tx_desc->len = xsk_frame_size; + tx_desc->options = XDP_PKT_CONTD; + } else { + tx_desc->len = len; + tx_desc->options = 0; + pkt_nb++; + } + len -= tx_desc->len; + addr += xsk_frame_size; + + if (i == batch_size) { + /* Remember len, addr, pkt_nb for next iteration. + * Skipped for simplicity. + */ + break; + } + } while (len); + } + + xsk_ring_prod__submit(&xsk->tx, i); + } + +Probing for Multi-Buffer Support +-------------------------------- + +To discover if a driver supports multi-buffer AF_XDP in SKB or DRV +mode, use the XDP_FEATURES feature of netlink in linux/netdev.h to +query for NETDEV_XDP_ACT_RX_SG support. This is the same flag as for +querying for XDP multi-buffer support. If XDP supports multi-buffer in +a driver, then AF_XDP will also support that in SKB and DRV mode. + +To discover if a driver supports multi-buffer AF_XDP in zero-copy +mode, use XDP_FEATURES and first check the NETDEV_XDP_ACT_XSK_ZEROCOPY +flag. If it is set, it means that at least zero-copy is supported and +you should go and check the netlink attribute +NETDEV_A_DEV_XDP_ZC_MAX_SEGS in linux/netdev.h. An unsigned integer +value will be returned stating the max number of frags that are +supported by this device in zero-copy mode. These are the possible +return values: + +1: Multi-buffer for zero-copy is not supported by this device, as max + one fragment supported means that multi-buffer is not possible. + +>=2: Multi-buffer is supported in zero-copy mode for this device. The + returned number signifies the max number of frags supported. + +For an example on how these are used through libbpf, please take a +look at tools/testing/selftests/bpf/xskxceiver.c. + +Multi-Buffer Support for Zero-Copy Drivers +------------------------------------------ + +Zero-copy drivers usually use the batched APIs for Rx and Tx +processing. Note that the Tx batch API guarantees that it will provide +a batch of Tx descriptors that ends with full packet at the end. This +to facilitate extending a zero-copy driver with multi-buffer support. + Sample application ================== diff --git a/Documentation/networking/ax25.rst b/Documentation/networking/ax25.rst index f060cfb1445a..605e72c6c877 100644 --- a/Documentation/networking/ax25.rst +++ b/Documentation/networking/ax25.rst @@ -7,9 +7,9 @@ AX.25 To use the amateur radio protocols within Linux you will need to get a suitable copy of the AX.25 Utilities. More detailed information about AX.25, NET/ROM and ROSE, associated programs and utilities can be -found on http://www.linux-ax25.org. +found on https://linux-ax25.in-berlin.de. -There is an active mailing list for discussing Linux amateur radio matters +There is a mailing list for discussing Linux amateur radio matters called linux-hams@vger.kernel.org. To subscribe to it, send a message to majordomo@vger.kernel.org with the words "subscribe linux-hams" in the body of the message, the subject field is ignored. You don't need to be diff --git a/Documentation/networking/bonding.rst b/Documentation/networking/bonding.rst index 28925e19622d..f7a73421eb76 100644 --- a/Documentation/networking/bonding.rst +++ b/Documentation/networking/bonding.rst @@ -1636,7 +1636,7 @@ your init script:: ----------------------------------------- This section applies to distros which use /etc/network/interfaces file -to describe network interface configuration, most notably Debian and it's +to describe network interface configuration, most notably Debian and its derivatives. The ifup and ifdown commands on Debian don't support bonding out of diff --git a/Documentation/networking/device_drivers/appletalk/cops.rst b/Documentation/networking/device_drivers/appletalk/cops.rst deleted file mode 100644 index 964ba80599a9..000000000000 --- a/Documentation/networking/device_drivers/appletalk/cops.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -======================================== -The COPS LocalTalk Linux driver (cops.c) -======================================== - -By Jay Schulist <jschlst@samba.org> - -This driver has two modes and they are: Dayna mode and Tangent mode. -Each mode corresponds with the type of card. It has been found -that there are 2 main types of cards and all other cards are -the same and just have different names or only have minor differences -such as more IO ports. As this driver is tested it will -become more clear exactly what cards are supported. - -Right now these cards are known to work with the COPS driver. The -LT-200 cards work in a somewhat more limited capacity than the -DL200 cards, which work very well and are in use by many people. - -TANGENT driver mode: - - Tangent ATB-II, Novell NL-1000, Daystar Digital LT-200 - -DAYNA driver mode: - - Dayna DL2000/DaynaTalk PC (Half Length), COPS LT-95, - - Farallon PhoneNET PC III, Farallon PhoneNET PC II - -Other cards possibly supported mode unknown though: - - Dayna DL2000 (Full length) - -The COPS driver defaults to using Dayna mode. To change the driver's -mode if you built a driver with dual support use board_type=1 or -board_type=2 for Dayna or Tangent with insmod. - -Operation/loading of the driver -=============================== - -Use modprobe like this: /sbin/modprobe cops.o (IO #) (IRQ #) -If you do not specify any options the driver will try and use the IO = 0x240, -IRQ = 5. As of right now I would only use IRQ 5 for the card, if autoprobing. - -To load multiple COPS driver Localtalk cards you can do one of the following:: - - insmod cops io=0x240 irq=5 - insmod -o cops2 cops io=0x260 irq=3 - -Or in lilo.conf put something like this:: - - append="ether=5,0x240,lt0 ether=3,0x260,lt1" - -Then bring up the interface with ifconfig. It will look something like this:: - - lt0 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-F7-00-00-00-00-00-00-00-00 - inet addr:192.168.1.2 Bcast:192.168.1.255 Mask:255.255.255.0 - UP BROADCAST RUNNING NOARP MULTICAST MTU:600 Metric:1 - RX packets:0 errors:0 dropped:0 overruns:0 frame:0 - TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 coll:0 - -Netatalk Configuration -====================== - -You will need to configure atalkd with something like the following to make -it work with the cops.c driver. - -* For single LTalk card use:: - - dummy -seed -phase 2 -net 2000 -addr 2000.10 -zone "1033" - lt0 -seed -phase 1 -net 1000 -addr 1000.50 -zone "1033" - -* For multiple cards, Ethernet and LocalTalk:: - - eth0 -seed -phase 2 -net 3000 -addr 3000.20 -zone "1033" - lt0 -seed -phase 1 -net 1000 -addr 1000.50 -zone "1033" - -* For multiple LocalTalk cards, and an Ethernet card. - -* Order seems to matter here, Ethernet last:: - - lt0 -seed -phase 1 -net 1000 -addr 1000.10 -zone "LocalTalk1" - lt1 -seed -phase 1 -net 2000 -addr 2000.20 -zone "LocalTalk2" - eth0 -seed -phase 2 -net 3000 -addr 3000.30 -zone "EtherTalk" diff --git a/Documentation/networking/device_drivers/appletalk/index.rst b/Documentation/networking/device_drivers/appletalk/index.rst deleted file mode 100644 index c196baeb0856..000000000000 --- a/Documentation/networking/device_drivers/appletalk/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) - -AppleTalk Device Drivers -======================== - -Contents: - -.. toctree:: - :maxdepth: 2 - - cops - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` diff --git a/Documentation/networking/device_drivers/ethernet/amd/pds_vfio_pci.rst b/Documentation/networking/device_drivers/ethernet/amd/pds_vfio_pci.rst new file mode 100644 index 000000000000..7a6bc848a2b2 --- /dev/null +++ b/Documentation/networking/device_drivers/ethernet/amd/pds_vfio_pci.rst @@ -0,0 +1,79 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. note: can be edited and viewed with /usr/bin/formiko-vim + +========================================================== +PCI VFIO driver for the AMD/Pensando(R) DSC adapter family +========================================================== + +AMD/Pensando Linux VFIO PCI Device Driver +Copyright(c) 2023 Advanced Micro Devices, Inc. + +Overview +======== + +The ``pds-vfio-pci`` module is a PCI driver that supports Live Migration +capable Virtual Function (VF) devices in the DSC hardware. + +Using the device +================ + +The pds-vfio-pci device is enabled via multiple configuration steps and +depends on the ``pds_core`` driver to create and enable SR-IOV Virtual +Function devices. + +Shown below are the steps to bind the driver to a VF and also to the +associated auxiliary device created by the ``pds_core`` driver. This +example assumes the pds_core and pds-vfio-pci modules are already +loaded. + +.. code-block:: bash + :name: example-setup-script + + #!/bin/bash + + PF_BUS="0000:60" + PF_BDF="0000:60:00.0" + VF_BDF="0000:60:00.1" + + # Prevent non-vfio VF driver from probing the VF device + echo 0 > /sys/class/pci_bus/$PF_BUS/device/$PF_BDF/sriov_drivers_autoprobe + + # Create single VF for Live Migration via pds_core + echo 1 > /sys/bus/pci/drivers/pds_core/$PF_BDF/sriov_numvfs + + # Allow the VF to be bound to the pds-vfio-pci driver + echo "pds-vfio-pci" > /sys/class/pci_bus/$PF_BUS/device/$VF_BDF/driver_override + + # Bind the VF to the pds-vfio-pci driver + echo "$VF_BDF" > /sys/bus/pci/drivers/pds-vfio-pci/bind + +After performing the steps above, a file in /dev/vfio/<iommu_group> +should have been created. + + +Enabling the driver +=================== + +The driver is enabled via the standard kernel configuration system, +using the make command:: + + make oldconfig/menuconfig/etc. + +The driver is located in the menu structure at: + + -> Device Drivers + -> VFIO Non-Privileged userspace driver framework + -> VFIO support for PDS PCI devices + +Support +======= + +For general Linux networking support, please use the netdev mailing +list, which is monitored by Pensando personnel:: + + netdev@vger.kernel.org + +For more specific support needs, please use the Pensando driver support +email:: + + drivers@pensando.io diff --git a/Documentation/networking/device_drivers/ethernet/google/gve.rst b/Documentation/networking/device_drivers/ethernet/google/gve.rst index 6d73ee78f3d7..31d621bca82e 100644 --- a/Documentation/networking/device_drivers/ethernet/google/gve.rst +++ b/Documentation/networking/device_drivers/ethernet/google/gve.rst @@ -52,6 +52,15 @@ Descriptor Formats GVE supports two descriptor formats: GQI and DQO. These two formats have entirely different descriptors, which will be described below. +Addressing Mode +------------------ +GVE supports two addressing modes: QPL and RDA. +QPL ("queue-page-list") mode communicates data through a set of +pre-registered pages. + +For RDA ("raw DMA addressing") mode, the set of pages is dynamic. +Therefore, the packet buffers can be anywhere in guest memory. + Registers --------- All registers are MMIO. diff --git a/Documentation/networking/device_drivers/ethernet/index.rst b/Documentation/networking/device_drivers/ethernet/index.rst index 94ecb67c0885..43de285b8a92 100644 --- a/Documentation/networking/device_drivers/ethernet/index.rst +++ b/Documentation/networking/device_drivers/ethernet/index.rst @@ -16,6 +16,7 @@ Contents: altera/altera_tse amd/pds_core amd/pds_vdpa + amd/pds_vfio_pci aquantia/atlantic chelsio/cxgb cirrus/cs89x0 @@ -31,6 +32,7 @@ Contents: intel/e1000 intel/e1000e intel/fm10k + intel/idpf intel/igb intel/igbvf intel/ixgbe diff --git a/Documentation/networking/device_drivers/ethernet/intel/idpf.rst b/Documentation/networking/device_drivers/ethernet/intel/idpf.rst new file mode 100644 index 000000000000..adb16e2abd21 --- /dev/null +++ b/Documentation/networking/device_drivers/ethernet/intel/idpf.rst @@ -0,0 +1,160 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +========================================================================== +idpf Linux* Base Driver for the Intel(R) Infrastructure Data Path Function +========================================================================== + +Intel idpf Linux driver. +Copyright(C) 2023 Intel Corporation. + +.. contents:: + +The idpf driver serves as both the Physical Function (PF) and Virtual Function +(VF) driver for the Intel(R) Infrastructure Data Path Function. + +Driver information can be obtained using ethtool, lspci, and ip. + +For questions related to hardware requirements, refer to the documentation +supplied with your Intel adapter. All hardware requirements listed apply to use +with Linux. + + +Identifying Your Adapter +======================== +For information on how to identify your adapter, and for the latest Intel +network drivers, refer to the Intel Support website: +http://www.intel.com/support + + +Additional Features and Configurations +====================================== + +ethtool +------- +The driver utilizes the ethtool interface for driver configuration and +diagnostics, as well as displaying statistical information. The latest ethtool +version is required for this functionality. If you don't have one yet, you can +obtain it at: +https://kernel.org/pub/software/network/ethtool/ + + +Viewing Link Messages +--------------------- +Link messages will not be displayed to the console if the distribution is +restricting system messages. In order to see network driver link messages on +your console, set dmesg to eight by entering the following:: + + # dmesg -n 8 + +.. note:: + This setting is not saved across reboots. + + +Jumbo Frames +------------ +Jumbo Frames support is enabled by changing the Maximum Transmission Unit (MTU) +to a value larger than the default value of 1500. + +Use the ip command to increase the MTU size. For example, enter the following +where <ethX> is the interface number:: + + # ip link set mtu 9000 dev <ethX> + # ip link set up dev <ethX> + +.. note:: + The maximum MTU setting for jumbo frames is 9706. This corresponds to the + maximum jumbo frame size of 9728 bytes. + +.. note:: + This driver will attempt to use multiple page sized buffers to receive + each jumbo packet. This should help to avoid buffer starvation issues when + allocating receive packets. + +.. note:: + Packet loss may have a greater impact on throughput when you use jumbo + frames. If you observe a drop in performance after enabling jumbo frames, + enabling flow control may mitigate the issue. + + +Performance Optimization +======================== +Driver defaults are meant to fit a wide variety of workloads, but if further +optimization is required, we recommend experimenting with the following +settings. + + +Interrupt Rate Limiting +----------------------- +This driver supports an adaptive interrupt throttle rate (ITR) mechanism that +is tuned for general workloads. The user can customize the interrupt rate +control for specific workloads, via ethtool, adjusting the number of +microseconds between interrupts. + +To set the interrupt rate manually, you must disable adaptive mode:: + + # ethtool -C <ethX> adaptive-rx off adaptive-tx off + +For lower CPU utilization: + - Disable adaptive ITR and lower Rx and Tx interrupts. The examples below + affect every queue of the specified interface. + + - Setting rx-usecs and tx-usecs to 80 will limit interrupts to about + 12,500 interrupts per second per queue:: + + # ethtool -C <ethX> adaptive-rx off adaptive-tx off rx-usecs 80 + tx-usecs 80 + +For reduced latency: + - Disable adaptive ITR and ITR by setting rx-usecs and tx-usecs to 0 + using ethtool:: + + # ethtool -C <ethX> adaptive-rx off adaptive-tx off rx-usecs 0 + tx-usecs 0 + +Per-queue interrupt rate settings: + - The following examples are for queues 1 and 3, but you can adjust other + queues. + + - To disable Rx adaptive ITR and set static Rx ITR to 10 microseconds or + about 100,000 interrupts/second, for queues 1 and 3:: + + # ethtool --per-queue <ethX> queue_mask 0xa --coalesce adaptive-rx off + rx-usecs 10 + + - To show the current coalesce settings for queues 1 and 3:: + + # ethtool --per-queue <ethX> queue_mask 0xa --show-coalesce + + + +Virtualized Environments +------------------------ +In addition to the other suggestions in this section, the following may be +helpful to optimize performance in VMs. + + - Using the appropriate mechanism (vcpupin) in the VM, pin the CPUs to + individual LCPUs, making sure to use a set of CPUs included in the + device's local_cpulist: /sys/class/net/<ethX>/device/local_cpulist. + + - Configure as many Rx/Tx queues in the VM as available. (See the idpf driver + documentation for the number of queues supported.) For example:: + + # ethtool -L <virt_interface> rx <max> tx <max> + + +Support +======= +For general information, go to the Intel support website at: +http://www.intel.com/support/ + +If an issue is identified with the released source code on a supported kernel +with a supported adapter, email the specific information related to the issue +to intel-wired-lan@lists.osuosl.org. + + +Trademarks +========== +Intel is a trademark or registered trademark of Intel Corporation or its +subsidiaries in the United States and/or other countries. + +* Other names and brands may be claimed as the property of others. diff --git a/Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst b/Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst index bfd233cfac35..1e196cb9ce25 100644 --- a/Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst +++ b/Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst @@ -332,3 +332,11 @@ Setup HTB offload # tc class add dev <interface> parent 1: classid 1:1 htb rate 10Gbit prio 1 # tc class add dev <interface> parent 1: classid 1:2 htb rate 10Gbit prio 7 + +4. Create tc classes with same priorities and different quantum:: + + # tc class add dev <interface> parent 1: classid 1:1 htb rate 10Gbit prio 2 quantum 409600 + + # tc class add dev <interface> parent 1: classid 1:2 htb rate 10Gbit prio 2 quantum 188416 + + # tc class add dev <interface> parent 1: classid 1:3 htb rate 10Gbit prio 2 quantum 32768 diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/counters.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/counters.rst index a395df9c2751..f69ee1ebee01 100644 --- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/counters.rst +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/counters.rst @@ -346,6 +346,24 @@ the software port. - The number of receive packets with CQE compression on ring i [#accel]_. - Acceleration + * - `rx[i]_arfs_add` + - The number of aRFS flow rules added to the device for direct RQ steering + on ring i [#accel]_. + - Acceleration + + * - `rx[i]_arfs_request_in` + - Number of flow rules that have been requested to move into ring i for + direct RQ steering [#accel]_. + - Acceleration + + * - `rx[i]_arfs_request_out` + - Number of flow rules that have been requested to move out of ring i [#accel]_. + - Acceleration + + * - `rx[i]_arfs_expired` + - Number of flow rules that have been expired and removed [#accel]_. + - Acceleration + * - `rx[i]_arfs_err` - Number of flow rules that failed to be added to the flow table. - Error @@ -445,11 +463,6 @@ the software port. context. - Error - * - `rx[i]_xsk_arfs_err` - - aRFS (accelerated Receive Flow Steering) does not occur in the XSK RQ - context, so this counter should never increment. - - Error - * - `rx[i]_xdp_tx_xmit` - The number of packets forwarded back to the port due to XDP program `XDP_TX` action (bouncing). these packets are not counted by other @@ -683,6 +696,12 @@ the software port. time protocol. - Error + * - `ptp_cq[i]_late_cqe` + - Number of times a CQE has been delivered on the PTP timestamping CQ when + the CQE was not expected since a certain amount of time had elapsed where + the device typically ensures not posting the CQE. + - Error + .. [#ring_global] The corresponding ring and global counters do not share the same name (i.e. do not follow the common naming scheme). diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst deleted file mode 100644 index a4edf908b707..000000000000 --- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst +++ /dev/null @@ -1,313 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 OR Linux-OpenIB -.. include:: <isonum.txt> - -======= -Devlink -======= - -:Copyright: |copy| 2023, NVIDIA CORPORATION & AFFILIATES. All rights reserved. - -Contents -======== - -- `Info`_ -- `Parameters`_ -- `Health reporters`_ - -Info -==== - -The devlink info reports the running and stored firmware versions on device. -It also prints the device PSID which represents the HCA board type ID. - -User command example:: - - $ devlink dev info pci/0000:00:06.0 - pci/0000:00:06.0: - driver mlx5_core - versions: - fixed: - fw.psid MT_0000000009 - running: - fw.version 16.26.0100 - stored: - fw.version 16.26.0100 - -Parameters -========== - -flow_steering_mode: Device flow steering mode ---------------------------------------------- -The flow steering mode parameter controls the flow steering mode of the driver. -Two modes are supported: - -1. 'dmfs' - Device managed flow steering. -2. 'smfs' - Software/Driver managed flow steering. - -In DMFS mode, the HW steering entities are created and managed through the -Firmware. -In SMFS mode, the HW steering entities are created and managed though by -the driver directly into hardware without firmware intervention. - -SMFS mode is faster and provides better rule insertion rate compared to default DMFS mode. - -User command examples: - -- Set SMFS flow steering mode:: - - $ devlink dev param set pci/0000:06:00.0 name flow_steering_mode value "smfs" cmode runtime - -- Read device flow steering mode:: - - $ devlink dev param show pci/0000:06:00.0 name flow_steering_mode - pci/0000:06:00.0: - name flow_steering_mode type driver-specific - values: - cmode runtime value smfs - -enable_roce: RoCE enablement state ----------------------------------- -If the device supports RoCE disablement, RoCE enablement state controls device -support for RoCE capability. Otherwise, the control occurs in the driver stack. -When RoCE is disabled at the driver level, only raw ethernet QPs are supported. - -To change RoCE enablement state, a user must change the driverinit cmode value -and run devlink reload. - -User command examples: - -- Disable RoCE:: - - $ devlink dev param set pci/0000:06:00.0 name enable_roce value false cmode driverinit - $ devlink dev reload pci/0000:06:00.0 - -- Read RoCE enablement state:: - - $ devlink dev param show pci/0000:06:00.0 name enable_roce - pci/0000:06:00.0: - name enable_roce type generic - values: - cmode driverinit value true - -esw_port_metadata: Eswitch port metadata state ----------------------------------------------- -When applicable, disabling eswitch metadata can increase packet rate -up to 20% depending on the use case and packet sizes. - -Eswitch port metadata state controls whether to internally tag packets with -metadata. Metadata tagging must be enabled for multi-port RoCE, failover -between representors and stacked devices. -By default metadata is enabled on the supported devices in E-switch. -Metadata is applicable only for E-switch in switchdev mode and -users may disable it when NONE of the below use cases will be in use: - -1. HCA is in Dual/multi-port RoCE mode. -2. VF/SF representor bonding (Usually used for Live migration) -3. Stacked devices - -When metadata is disabled, the above use cases will fail to initialize if -users try to enable them. - -- Show eswitch port metadata:: - - $ devlink dev param show pci/0000:06:00.0 name esw_port_metadata - pci/0000:06:00.0: - name esw_port_metadata type driver-specific - values: - cmode runtime value true - -- Disable eswitch port metadata:: - - $ devlink dev param set pci/0000:06:00.0 name esw_port_metadata value false cmode runtime - -- Change eswitch mode to switchdev mode where after choosing the metadata value:: - - $ devlink dev eswitch set pci/0000:06:00.0 mode switchdev - -hairpin_num_queues: Number of hairpin queues --------------------------------------------- -We refer to a TC NIC rule that involves forwarding as "hairpin". - -Hairpin queues are mlx5 hardware specific implementation for hardware -forwarding of such packets. - -- Show the number of hairpin queues:: - - $ devlink dev param show pci/0000:06:00.0 name hairpin_num_queues - pci/0000:06:00.0: - name hairpin_num_queues type driver-specific - values: - cmode driverinit value 2 - -- Change the number of hairpin queues:: - - $ devlink dev param set pci/0000:06:00.0 name hairpin_num_queues value 4 cmode driverinit - -hairpin_queue_size: Size of the hairpin queues ----------------------------------------------- -Control the size of the hairpin queues. - -- Show the size of the hairpin queues:: - - $ devlink dev param show pci/0000:06:00.0 name hairpin_queue_size - pci/0000:06:00.0: - name hairpin_queue_size type driver-specific - values: - cmode driverinit value 1024 - -- Change the size (in packets) of the hairpin queues:: - - $ devlink dev param set pci/0000:06:00.0 name hairpin_queue_size value 512 cmode driverinit - -Health reporters -================ - -tx reporter ------------ -The tx reporter is responsible for reporting and recovering of the following two error scenarios: - -- tx timeout - Report on kernel tx timeout detection. - Recover by searching lost interrupts. -- tx error completion - Report on error tx completion. - Recover by flushing the tx queue and reset it. - -tx reporter also support on demand diagnose callback, on which it provides -real time information of its send queues status. - -User commands examples: - -- Diagnose send queues status:: - - $ devlink health diagnose pci/0000:82:00.0 reporter tx - -.. note:: - This command has valid output only when interface is up, otherwise the command has empty output. - -- Show number of tx errors indicated, number of recover flows ended successfully, - is autorecover enabled and graceful period from last recover:: - - $ devlink health show pci/0000:82:00.0 reporter tx - -rx reporter ------------ -The rx reporter is responsible for reporting and recovering of the following two error scenarios: - -- rx queues' initialization (population) timeout - Population of rx queues' descriptors on ring initialization is done - in napi context via triggering an irq. In case of a failure to get - the minimum amount of descriptors, a timeout would occur, and - descriptors could be recovered by polling the EQ (Event Queue). -- rx completions with errors (reported by HW on interrupt context) - Report on rx completion error. - Recover (if needed) by flushing the related queue and reset it. - -rx reporter also supports on demand diagnose callback, on which it -provides real time information of its receive queues' status. - -- Diagnose rx queues' status and corresponding completion queue:: - - $ devlink health diagnose pci/0000:82:00.0 reporter rx - -NOTE: This command has valid output only when interface is up. Otherwise, the command has empty output. - -- Show number of rx errors indicated, number of recover flows ended successfully, - is autorecover enabled, and graceful period from last recover:: - - $ devlink health show pci/0000:82:00.0 reporter rx - -fw reporter ------------ -The fw reporter implements `diagnose` and `dump` callbacks. -It follows symptoms of fw error such as fw syndrome by triggering -fw core dump and storing it into the dump buffer. -The fw reporter diagnose command can be triggered any time by the user to check -current fw status. - -User commands examples: - -- Check fw heath status:: - - $ devlink health diagnose pci/0000:82:00.0 reporter fw - -- Read FW core dump if already stored or trigger new one:: - - $ devlink health dump show pci/0000:82:00.0 reporter fw - -.. note:: - This command can run only on the PF which has fw tracer ownership, - running it on other PF or any VF will return "Operation not permitted". - -fw fatal reporter ------------------ -The fw fatal reporter implements `dump` and `recover` callbacks. -It follows fatal errors indications by CR-space dump and recover flow. -The CR-space dump uses vsc interface which is valid even if the FW command -interface is not functional, which is the case in most FW fatal errors. -The recover function runs recover flow which reloads the driver and triggers fw -reset if needed. -On firmware error, the health buffer is dumped into the dmesg. The log -level is derived from the error's severity (given in health buffer). - -User commands examples: - -- Run fw recover flow manually:: - - $ devlink health recover pci/0000:82:00.0 reporter fw_fatal - -- Read FW CR-space dump if already stored or trigger new one:: - - $ devlink health dump show pci/0000:82:00.1 reporter fw_fatal - -.. note:: - This command can run only on PF. - -vnic reporter -------------- -The vnic reporter implements only the `diagnose` callback. -It is responsible for querying the vnic diagnostic counters from fw and displaying -them in realtime. - -Description of the vnic counters: - -- total_q_under_processor_handle - number of queues in an error state due to - an async error or errored command. -- send_queue_priority_update_flow - number of QP/SQ priority/SL update events. -- cq_overrun - 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 - overrun. -- quota_exceeded_command - number of commands issued and failed due to quota exceeded. -- invalid_command - number of commands issued and failed dues to any reason other than quota - exceeded. -- nic_receive_steering_discard - number of packets that completed RX flow - steering but were discarded due to a mismatch in flow table. -- generated_pkt_steering_fail - number of packets generated by the VNIC experiencing unexpected steering - failure (at any point in steering flow). -- handled_pkt_steering_fail - number of packets handled by the VNIC experiencing unexpected steering - failure (at any point in steering flow owned by the VNIC, including the FDB - for the eswitch owner). - -User commands examples: - -- Diagnose PF/VF vnic counters:: - - $ devlink health diagnose pci/0000:82:00.1 reporter vnic - -- Diagnose representor vnic counters (performed by supplying devlink port of the - representor, which can be obtained via devlink port command):: - - $ devlink health diagnose pci/0000:82:00.1/65537 reporter vnic - -.. note:: - This command can run over all interfaces such as PF/VF and representor ports. diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/index.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/index.rst index 3fdcd6b61ccf..581a91caa579 100644 --- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/index.rst +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/index.rst @@ -13,7 +13,6 @@ Contents: :maxdepth: 2 kconfig - devlink switchdev tracepoints counters diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/kconfig.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/kconfig.rst index 43b1f7e87ec4..20d3b7e87049 100644 --- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/kconfig.rst +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/kconfig.rst @@ -36,7 +36,7 @@ Enabling the driver and kconfig options **CONFIG_MLX5_CORE_EN_DCB=(y/n)**: -| Enables `Data Center Bridging (DCB) Support <https://community.mellanox.com/s/article/howto-auto-config-pfc-and-ets-on-connectx-4-via-lldp-dcbx>`_. +| Enables `Data Center Bridging (DCB) Support <https://enterprise-support.nvidia.com/s/article/howto-auto-config-pfc-and-ets-on-connectx-4-via-lldp-dcbx>`_. **CONFIG_MLX5_CORE_IPOIB=(y/n)** @@ -59,15 +59,15 @@ Enabling the driver and kconfig options **CONFIG_MLX5_EN_ARFS=(y/n)** | Enables Hardware-accelerated receive flow steering (arfs) support, and ntuple filtering. -| https://community.mellanox.com/s/article/howto-configure-arfs-on-connectx-4 +| https://enterprise-support.nvidia.com/s/article/howto-configure-arfs-on-connectx-4 **CONFIG_MLX5_EN_IPSEC=(y/n)** -| Enables `IPSec XFRM cryptography-offload acceleration <https://support.mellanox.com/s/article/ConnectX-6DX-Bluefield-2-IPsec-HW-Full-Offload-Configuration-Guide>`_. +| Enables :ref:`IPSec XFRM cryptography-offload acceleration <xfrm_device>`. -**CONFIG_MLX5_EN_MACSEC=(y/n)** +**CONFIG_MLX5_MACSEC=(y/n)** | Build support for MACsec cryptography-offload acceleration in the NIC. @@ -87,8 +87,8 @@ Enabling the driver and kconfig options | Ethernet SRIOV E-Switch support in ConnectX NIC. E-Switch provides internal SRIOV packet steering | and switching for the enabled VFs and PF in two available modes: -| 1) `Legacy SRIOV mode (L2 mac vlan steering based) <https://community.mellanox.com/s/article/howto-configure-sr-iov-for-connectx-4-connectx-5-with-kvm--ethernet-x>`_. -| 2) `Switchdev mode (eswitch offloads) <https://www.mellanox.com/related-docs/prod_software/ASAP2_Hardware_Offloading_for_vSwitches_User_Manual_v4.4.pdf>`_. +| 1) `Legacy SRIOV mode (L2 mac vlan steering based) <https://enterprise-support.nvidia.com/s/article/HowTo-Configure-SR-IOV-for-ConnectX-4-ConnectX-5-ConnectX-6-with-KVM-Ethernet>`_. +| 2) :ref:`Switchdev mode (eswitch offloads) <switchdev>`. **CONFIG_MLX5_FPGA=(y/n)** @@ -101,13 +101,13 @@ Enabling the driver and kconfig options **CONFIG_MLX5_INFINIBAND=(y/n/m)** (module mlx5_ib.ko) -| Provides low-level InfiniBand/RDMA and `RoCE <https://community.mellanox.com/s/article/recommended-network-configuration-examples-for-roce-deployment>`_ support. +| Provides low-level InfiniBand/RDMA and `RoCE <https://enterprise-support.nvidia.com/s/article/recommended-network-configuration-examples-for-roce-deployment>`_ support. **CONFIG_MLX5_MPFS=(y/n)** | Ethernet Multi-Physical Function Switch (MPFS) support in ConnectX NIC. -| MPFs is required for when `Multi-Host <http://www.mellanox.com/page/multihost>`_ configuration is enabled to allow passing +| MPFs is required for when `Multi-Host <https://www.nvidia.com/en-us/networking/multi-host/>`_ configuration is enabled to allow passing | user configured unicast MAC addresses to the requesting PF. diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/switchdev.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/switchdev.rst index 6e3f5ee8b0d0..b617e93d7c2c 100644 --- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/switchdev.rst +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/switchdev.rst @@ -190,6 +190,26 @@ explicitly enable the VF migratable capability. mlx5 driver support devlink port function attr mechanism to setup migratable capability. (refer to Documentation/networking/devlink/devlink-port.rst) +IPsec crypto capability setup +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +User who wants mlx5 PCI VFs to be able to perform IPsec crypto offloading need +to explicitly enable the VF ipsec_crypto capability. Enabling IPsec capability +for VFs is supported starting with ConnectX6dx devices and above. When a VF has +IPsec capability enabled, any IPsec offloading is blocked on the PF. + +mlx5 driver support devlink port function attr mechanism to setup ipsec_crypto +capability. (refer to Documentation/networking/devlink/devlink-port.rst) + +IPsec packet capability setup +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +User who wants mlx5 PCI VFs to be able to perform IPsec packet offloading need +to explicitly enable the VF ipsec_packet capability. Enabling IPsec capability +for VFs is supported starting with ConnectX6dx devices and above. When a VF has +IPsec capability enabled, any IPsec offloading is blocked on the PF. + +mlx5 driver support devlink port function attr mechanism to setup ipsec_packet +capability. (refer to Documentation/networking/devlink/devlink-port.rst) + SF state setup -------------- diff --git a/Documentation/networking/device_drivers/ethernet/neterion/s2io.rst b/Documentation/networking/device_drivers/ethernet/neterion/s2io.rst index c5673ec4559b..d731b5a98561 100644 --- a/Documentation/networking/device_drivers/ethernet/neterion/s2io.rst +++ b/Documentation/networking/device_drivers/ethernet/neterion/s2io.rst @@ -64,8 +64,8 @@ c. Multi-buffer receive mode. Scattering of packet across multiple IBM xSeries). d. MSI/MSI-X. Can be enabled on platforms which support this feature - (IA64, Xeon) resulting in noticeable performance improvement(up to 7% - on certain platforms). + resulting in noticeable performance improvement (up to 7% on certain + platforms). e. Statistics. Comprehensive MAC-level and software statistics displayed using "ethtool -S" option. diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index 601eacaf12f3..2f0285a5bc80 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -8,7 +8,6 @@ Contents: .. toctree:: :maxdepth: 2 - appletalk/index atm/index cable/index can/index diff --git a/Documentation/networking/devlink/devlink-port.rst b/Documentation/networking/devlink/devlink-port.rst index 3da590953ce8..e33ad2401ad7 100644 --- a/Documentation/networking/devlink/devlink-port.rst +++ b/Documentation/networking/devlink/devlink-port.rst @@ -128,6 +128,12 @@ Users may also set the RoCE capability of the function using Users may also set the function as migratable using '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. + +Users may also set the IPsec packet capability of the function using +`devlink port function set ipsec_packet` command. + Function attributes =================== @@ -240,6 +246,55 @@ Attach VF to the VM. Start the VM. Perform live migration. +IPsec crypto capability setup +----------------------------- +When user enables IPsec crypto capability for a VF, user application can offload +XFRM state crypto operation (Encrypt/Decrypt) to this VF. + +When IPsec crypto capability is disabled (default) for a VF, the XFRM state is +processed in software by the kernel. + +- Get IPsec crypto capability of the VF device:: + + $ devlink port show pci/0000:06:00.0/2 + pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1 + function: + hw_addr 00:00:00:00:00:00 ipsec_crypto disabled + +- Set IPsec crypto capability of the VF device:: + + $ devlink port function set pci/0000:06:00.0/2 ipsec_crypto enable + + $ devlink port show pci/0000:06:00.0/2 + pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1 + function: + hw_addr 00:00:00:00:00:00 ipsec_crypto enabled + +IPsec packet capability setup +----------------------------- +When user enables IPsec packet capability for a VF, user application can offload +XFRM state and policy crypto operation (Encrypt/Decrypt) to this VF, as well as +IPsec encapsulation. + +When IPsec packet capability is disabled (default) for a VF, the XFRM state and +policy is processed in software by the kernel. + +- Get IPsec packet capability of the VF device:: + + $ devlink port show pci/0000:06:00.0/2 + pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1 + function: + hw_addr 00:00:00:00:00:00 ipsec_packet disabled + +- Set IPsec packet capability of the VF device:: + + $ devlink port function set pci/0000:06:00.0/2 ipsec_packet enable + + $ devlink port show pci/0000:06:00.0/2 + pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1 + function: + hw_addr 00:00:00:00:00:00 ipsec_packet enabled + Subfunction ============ @@ -321,9 +376,9 @@ API allows to configure following rate object's parameters: Allows for usage of Weighted Fair Queuing arbitration scheme among siblings. This arbitration scheme can be used simultaneously with the strict priority. As a node is configured with a higher rate it gets more - BW relative to it's siblings. Values are relative like a percentage + BW relative to its siblings. Values are relative like a percentage points, they basically tell how much BW should node take relative to - it's siblings. + its siblings. ``parent`` Parent node name. Parent node rate limits are considered as additional limits @@ -343,7 +398,7 @@ Arbitration flow from the high level: #. If group of nodes have the same priority perform WFQ arbitration on that subgroup. Use ``tx_weight`` as a parameter for this arbitration. -#. Select the winner node, and continue arbitration flow among it's children, +#. Select the winner node, and continue arbitration flow among its children, until leaf node is reached, and the winner is established. #. If all the nodes from the highest priority sub-group are satisfied, or diff --git a/Documentation/networking/devlink/i40e.rst b/Documentation/networking/devlink/i40e.rst new file mode 100644 index 000000000000..d3cb5bb5197e --- /dev/null +++ b/Documentation/networking/devlink/i40e.rst @@ -0,0 +1,59 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +i40e devlink support +==================== + +This document describes the devlink features implemented by the ``i40e`` +device driver. + +Info versions +============= + +The ``i40e`` driver reports the following versions + +.. list-table:: devlink info versions implemented + :widths: 5 5 5 90 + + * - Name + - Type + - Example + - Description + * - ``board.id`` + - fixed + - K15190-000 + - The Product Board Assembly (PBA) identifier of the board. + * - ``fw.mgmt`` + - running + - 9.130 + - 2-digit version number of the management firmware that controls the + PHY, link, etc. + * - ``fw.mgmt.api`` + - running + - 1.15 + - 2-digit version number of the API exported over the AdminQ by the + management firmware. Used by the driver to identify what commands + are supported. + * - ``fw.mgmt.build`` + - running + - 73618 + - Build number of the source for the management firmware. + * - ``fw.undi`` + - running + - 1.3429.0 + - Version of the Option ROM containing the UEFI driver. The version is + reported in ``major.minor.patch`` format. The major version is + incremented whenever a major breaking change occurs, or when the + minor version would overflow. The minor version is incremented for + non-breaking changes and reset to 1 when the major version is + incremented. The patch version is normally 0 but is incremented when + a fix is delivered as a patch against an older base Option ROM. + * - ``fw.psid.api`` + - running + - 9.30 + - Version defining the format of the flash contents. + * - ``fw.bundle_id`` + - running + - 0x8000e5f3 + - Unique identifier of the firmware image file that was loaded onto + the device. Also referred to as the EETRACK identifier of the NVM. diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst index b49749e2b9a6..e14d7a701b72 100644 --- a/Documentation/networking/devlink/index.rst +++ b/Documentation/networking/devlink/index.rst @@ -18,6 +18,34 @@ netlink commands. Drivers are encouraged to use the devlink instance lock for their own needs. +Drivers need to be cautious when taking devlink instance lock and +taking RTNL lock at the same time. Devlink instance lock needs to be taken +first, only after that RTNL lock could be taken. + +Nested instances +---------------- + +Some objects, like linecards or port functions, could have another +devlink instances created underneath. In that case, drivers should make +sure to respect following rules: + + - Lock ordering should be maintained. If driver needs to take instance + lock of both nested and parent instances at the same time, devlink + instance lock of the parent instance should be taken first, only then + instance lock of the nested instance could be taken. + - Driver should use object-specific helpers to setup the + nested relationship: + + - ``devl_nested_devlink_set()`` - called to setup devlink -> nested + devlink relationship (could be user for multiple nested instances. + - ``devl_port_fn_devlink_set()`` - called to setup port function -> + nested devlink relationship. + - ``devlink_linecard_nested_dl_set()`` - called to setup linecard -> + nested devlink relationship. + +The nested devlink info is exposed to the userspace over object-specific +attributes of devlink netlink. + Interface documentation ----------------------- @@ -52,6 +80,7 @@ parameters, info versions, and other features it supports. bnxt etas_es58x hns3 + i40e ionic ice mlx4 diff --git a/Documentation/networking/devlink/mlx5.rst b/Documentation/networking/devlink/mlx5.rst index 202798d6501e..702f204a3dbd 100644 --- a/Documentation/networking/devlink/mlx5.rst +++ b/Documentation/networking/devlink/mlx5.rst @@ -18,6 +18,11 @@ Parameters * - ``enable_roce`` - driverinit - Type: Boolean + + If the device supports RoCE disablement, RoCE enablement state controls + device support for RoCE capability. Otherwise, the control occurs in the + driver stack. When RoCE is disabled at the driver level, only raw + ethernet QPs are supported. * - ``io_eq_size`` - driverinit - The range is between 64 and 4096. @@ -48,6 +53,9 @@ parameters. * ``smfs`` Software managed flow steering. In SMFS mode, the HW steering entities are created and manage through the driver without firmware intervention. + + SMFS mode is faster and provides better rule insertion rate compared to + default DMFS mode. * - ``fdb_large_groups`` - u32 - driverinit @@ -71,7 +79,24 @@ parameters. deprecated. Default: disabled + * - ``esw_port_metadata`` + - Boolean + - runtime + - When applicable, disabling eswitch metadata can increase packet rate up + to 20% depending on the use case and packet sizes. + + Eswitch port metadata state controls whether to internally tag packets + with metadata. Metadata tagging must be enabled for multi-port RoCE, + failover between representors and stacked devices. By default metadata is + enabled on the supported devices in E-switch. Metadata is applicable only + for E-switch in switchdev mode and users may disable it when NONE of the + below use cases will be in use: + 1. HCA is in Dual/multi-port RoCE mode. + 2. VF/SF representor bonding (Usually used for Live migration) + 3. Stacked devices + When metadata is disabled, the above use cases will fail to initialize if + users try to enable them. * - ``hairpin_num_queues`` - u32 - driverinit @@ -104,3 +129,160 @@ The ``mlx5`` driver reports the following versions * - ``fw.version`` - stored, running - Three digit major.minor.subminor firmware version number. + +Health reporters +================ + +tx reporter +----------- +The tx reporter is responsible for reporting and recovering of the following three error scenarios: + +- tx timeout + Report on kernel tx timeout detection. + Recover by searching lost interrupts. +- tx error completion + Report on error tx completion. + Recover by flushing the tx queue and reset it. +- tx PTP port timestamping CQ unhealthy + Report too many CQEs never delivered on port ts CQ. + Recover by flushing and re-creating all PTP channels. + +tx reporter also support on demand diagnose callback, on which it provides +real time information of its send queues status. + +User commands examples: + +- Diagnose send queues status:: + + $ devlink health diagnose pci/0000:82:00.0 reporter tx + +.. note:: + This command has valid output only when interface is up, otherwise the command has empty output. + +- Show number of tx errors indicated, number of recover flows ended successfully, + is autorecover enabled and graceful period from last recover:: + + $ devlink health show pci/0000:82:00.0 reporter tx + +rx reporter +----------- +The rx reporter is responsible for reporting and recovering of the following two error scenarios: + +- rx queues' initialization (population) timeout + Population of rx queues' descriptors on ring initialization is done + in napi context via triggering an irq. In case of a failure to get + the minimum amount of descriptors, a timeout would occur, and + descriptors could be recovered by polling the EQ (Event Queue). +- rx completions with errors (reported by HW on interrupt context) + Report on rx completion error. + Recover (if needed) by flushing the related queue and reset it. + +rx reporter also supports on demand diagnose callback, on which it +provides real time information of its receive queues' status. + +- Diagnose rx queues' status and corresponding completion queue:: + + $ devlink health diagnose pci/0000:82:00.0 reporter rx + +.. note:: + This command has valid output only when interface is up. Otherwise, the command has empty output. + +- Show number of rx errors indicated, number of recover flows ended successfully, + is autorecover enabled, and graceful period from last recover:: + + $ devlink health show pci/0000:82:00.0 reporter rx + +fw reporter +----------- +The fw reporter implements `diagnose` and `dump` callbacks. +It follows symptoms of fw error such as fw syndrome by triggering +fw core dump and storing it into the dump buffer. +The fw reporter diagnose command can be triggered any time by the user to check +current fw status. + +User commands examples: + +- Check fw heath status:: + + $ devlink health diagnose pci/0000:82:00.0 reporter fw + +- Read FW core dump if already stored or trigger new one:: + + $ devlink health dump show pci/0000:82:00.0 reporter fw + +.. note:: + This command can run only on the PF which has fw tracer ownership, + running it on other PF or any VF will return "Operation not permitted". + +fw fatal reporter +----------------- +The fw fatal reporter implements `dump` and `recover` callbacks. +It follows fatal errors indications by CR-space dump and recover flow. +The CR-space dump uses vsc interface which is valid even if the FW command +interface is not functional, which is the case in most FW fatal errors. +The recover function runs recover flow which reloads the driver and triggers fw +reset if needed. +On firmware error, the health buffer is dumped into the dmesg. The log +level is derived from the error's severity (given in health buffer). + +User commands examples: + +- Run fw recover flow manually:: + + $ devlink health recover pci/0000:82:00.0 reporter fw_fatal + +- Read FW CR-space dump if already stored or trigger new one:: + + $ devlink health dump show pci/0000:82:00.1 reporter fw_fatal + +.. note:: + This command can run only on PF. + +vnic reporter +------------- +The vnic reporter implements only the `diagnose` callback. +It is responsible for querying the vnic diagnostic counters from fw and displaying +them in realtime. + +Description of the vnic counters: + +- total_q_under_processor_handle + number of queues in an error state due to + an async error or errored command. +- send_queue_priority_update_flow + number of QP/SQ priority/SL update events. +- cq_overrun + 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 + overrun. +- quota_exceeded_command + number of commands issued and failed due to quota exceeded. +- invalid_command + number of commands issued and failed dues to any reason other than quota + exceeded. +- nic_receive_steering_discard + number of packets that completed RX flow + steering but were discarded due to a mismatch in flow table. +- generated_pkt_steering_fail + number of packets generated by the VNIC experiencing unexpected steering + failure (at any point in steering flow). +- handled_pkt_steering_fail + number of packets handled by the VNIC experiencing unexpected steering + failure (at any point in steering flow owned by the VNIC, including the FDB + for the eswitch owner). + +User commands examples: + +- Diagnose PF/VF vnic counters:: + + $ devlink health diagnose pci/0000:82:00.1 reporter vnic + +- Diagnose representor vnic counters (performed by supplying devlink port of the + representor, which can be obtained via devlink port command):: + + $ devlink health diagnose pci/0000:82:00.1/65537 reporter vnic + +.. note:: + This command can run over all interfaces such as PF/VF and representor ports. diff --git a/Documentation/networking/dsa/b53.rst b/Documentation/networking/dsa/b53.rst index b41637cdb82b..1cb3ff648f88 100644 --- a/Documentation/networking/dsa/b53.rst +++ b/Documentation/networking/dsa/b53.rst @@ -52,7 +52,7 @@ VLAN programming would basically change the CPU port's default PVID and make it untagged, undesirable. In difference to the configuration described in :ref:`dsa-vlan-configuration` -the default VLAN 1 has to be removed from the slave interface configuration in +the default VLAN 1 has to be removed from the user interface configuration in single port and gateway configuration, while there is no need to add an extra VLAN configuration in the bridge showcase. @@ -68,13 +68,13 @@ By default packages are tagged with vid 1: ip link add link eth0 name eth0.2 type vlan id 2 ip link add link eth0 name eth0.3 type vlan id 3 - # The master interface needs to be brought up before the slave ports. + # The conduit interface needs to be brought up before the user ports. ip link set eth0 up ip link set eth0.1 up ip link set eth0.2 up ip link set eth0.3 up - # bring up the slave interfaces + # bring up the user interfaces ip link set wan up ip link set lan1 up ip link set lan2 up @@ -113,11 +113,11 @@ bridge # tag traffic on CPU port ip link add link eth0 name eth0.1 type vlan id 1 - # The master interface needs to be brought up before the slave ports. + # The conduit interface needs to be brought up before the user ports. ip link set eth0 up ip link set eth0.1 up - # bring up the slave interfaces + # bring up the user interfaces ip link set wan up ip link set lan1 up ip link set lan2 up @@ -149,12 +149,12 @@ gateway ip link add link eth0 name eth0.1 type vlan id 1 ip link add link eth0 name eth0.2 type vlan id 2 - # The master interface needs to be brought up before the slave ports. + # The conduit interface needs to be brought up before the user ports. ip link set eth0 up ip link set eth0.1 up ip link set eth0.2 up - # bring up the slave interfaces + # bring up the user interfaces ip link set wan up ip link set lan1 up ip link set lan2 up diff --git a/Documentation/networking/dsa/bcm_sf2.rst b/Documentation/networking/dsa/bcm_sf2.rst index dee234039e1e..d2571435696f 100644 --- a/Documentation/networking/dsa/bcm_sf2.rst +++ b/Documentation/networking/dsa/bcm_sf2.rst @@ -67,7 +67,7 @@ MDIO indirect accesses ---------------------- Due to a limitation in how Broadcom switches have been designed, external -Broadcom switches connected to a SF2 require the use of the DSA slave MDIO bus +Broadcom switches connected to a SF2 require the use of the DSA user MDIO bus in order to properly configure them. By default, the SF2 pseudo-PHY address, and an external switch pseudo-PHY address will both be snooping for incoming MDIO transactions, since they are at the same address (30), resulting in some kind of diff --git a/Documentation/networking/dsa/configuration.rst b/Documentation/networking/dsa/configuration.rst index d2934c40f0f1..6cc4ded3cc23 100644 --- a/Documentation/networking/dsa/configuration.rst +++ b/Documentation/networking/dsa/configuration.rst @@ -31,38 +31,38 @@ at https://www.kernel.org/pub/linux/utils/net/iproute2/ Through DSA every port of a switch is handled like a normal linux Ethernet interface. The CPU port is the switch port connected to an Ethernet MAC chip. -The corresponding linux Ethernet interface is called the master interface. -All other corresponding linux interfaces are called slave interfaces. +The corresponding linux Ethernet interface is called the conduit interface. +All other corresponding linux interfaces are called user interfaces. -The slave interfaces depend on the master interface being up in order for them -to send or receive traffic. Prior to kernel v5.12, the state of the master +The user interfaces depend on the conduit interface being up in order for them +to send or receive traffic. Prior to kernel v5.12, the state of the conduit interface had to be managed explicitly by the user. Starting with kernel v5.12, the behavior is as follows: -- when a DSA slave interface is brought up, the master interface is +- when a DSA user interface is brought up, the conduit interface is automatically brought up. -- when the master interface is brought down, all DSA slave interfaces are +- when the conduit interface is brought down, all DSA user interfaces are automatically brought down. In this documentation the following Ethernet interfaces are used: *eth0* - the master interface + the conduit interface *eth1* - another master interface + another conduit interface *lan1* - a slave interface + a user interface *lan2* - another slave interface + another user interface *lan3* - a third slave interface + a third user interface *wan* - A slave interface dedicated for upstream traffic + A user interface dedicated for upstream traffic Further Ethernet interfaces can be configured similar. The configured IPs and networks are: @@ -96,11 +96,11 @@ without using a VLAN based configuration. ip addr add 192.0.2.5/30 dev lan2 ip addr add 192.0.2.9/30 dev lan3 - # For kernels earlier than v5.12, the master interface needs to be - # brought up manually before the slave ports. + # For kernels earlier than v5.12, the conduit interface needs to be + # brought up manually before the user ports. ip link set eth0 up - # bring up the slave interfaces + # bring up the user interfaces ip link set lan1 up ip link set lan2 up ip link set lan3 up @@ -108,11 +108,11 @@ without using a VLAN based configuration. *bridge* .. code-block:: sh - # For kernels earlier than v5.12, the master interface needs to be - # brought up manually before the slave ports. + # For kernels earlier than v5.12, the conduit interface needs to be + # brought up manually before the user ports. ip link set eth0 up - # bring up the slave interfaces + # bring up the user interfaces ip link set lan1 up ip link set lan2 up ip link set lan3 up @@ -134,11 +134,11 @@ without using a VLAN based configuration. *gateway* .. code-block:: sh - # For kernels earlier than v5.12, the master interface needs to be - # brought up manually before the slave ports. + # For kernels earlier than v5.12, the conduit interface needs to be + # brought up manually before the user ports. ip link set eth0 up - # bring up the slave interfaces + # bring up the user interfaces ip link set wan up ip link set lan1 up ip link set lan2 up @@ -178,14 +178,14 @@ configuration. ip link add link eth0 name eth0.2 type vlan id 2 ip link add link eth0 name eth0.3 type vlan id 3 - # For kernels earlier than v5.12, the master interface needs to be - # brought up manually before the slave ports. + # For kernels earlier than v5.12, the conduit interface needs to be + # brought up manually before the user ports. ip link set eth0 up ip link set eth0.1 up ip link set eth0.2 up ip link set eth0.3 up - # bring up the slave interfaces + # bring up the user interfaces ip link set lan1 up ip link set lan2 up ip link set lan3 up @@ -221,12 +221,12 @@ configuration. # tag traffic on CPU port ip link add link eth0 name eth0.1 type vlan id 1 - # For kernels earlier than v5.12, the master interface needs to be - # brought up manually before the slave ports. + # For kernels earlier than v5.12, the conduit interface needs to be + # brought up manually before the user ports. ip link set eth0 up ip link set eth0.1 up - # bring up the slave interfaces + # bring up the user interfaces ip link set lan1 up ip link set lan2 up ip link set lan3 up @@ -261,13 +261,13 @@ configuration. ip link add link eth0 name eth0.1 type vlan id 1 ip link add link eth0 name eth0.2 type vlan id 2 - # For kernels earlier than v5.12, the master interface needs to be - # brought up manually before the slave ports. + # For kernels earlier than v5.12, the conduit interface needs to be + # brought up manually before the user ports. ip link set eth0 up ip link set eth0.1 up ip link set eth0.2 up - # bring up the slave interfaces + # bring up the user interfaces ip link set wan up ip link set lan1 up ip link set lan2 up @@ -380,22 +380,22 @@ affinities according to the available CPU ports. Secondly, it is possible to perform load balancing between CPU ports on a per packet basis, rather than statically assigning user ports to CPU ports. -This can be achieved by placing the DSA masters under a LAG interface (bonding +This can be achieved by placing the DSA conduits under a LAG interface (bonding or team). DSA monitors this operation and creates a mirror of this software LAG -on the CPU ports facing the physical DSA masters that constitute the LAG slave +on the CPU ports facing the physical DSA conduits that constitute the LAG slave devices. To make use of multiple CPU ports, the firmware (device tree) description of -the switch must mark all the links between CPU ports and their DSA masters +the switch must mark all the links between CPU ports and their DSA conduits using the ``ethernet`` reference/phandle. At startup, only a single CPU port -and DSA master will be used - the numerically first port from the firmware +and DSA conduit will be used - the numerically first port from the firmware description which has an ``ethernet`` property. It is up to the user to -configure the system for the switch to use other masters. +configure the system for the switch to use other conduits. DSA uses the ``rtnl_link_ops`` mechanism (with a "dsa" ``kind``) to allow -changing the DSA master of a user port. The ``IFLA_DSA_MASTER`` u32 netlink -attribute contains the ifindex of the master device that handles each slave -device. The DSA master must be a valid candidate based on firmware node +changing the DSA conduit of a user port. The ``IFLA_DSA_CONDUIT`` u32 netlink +attribute contains the ifindex of the conduit device that handles each user +device. The DSA conduit must be a valid candidate based on firmware node information, or a LAG interface which contains only slaves which are valid candidates. @@ -403,7 +403,7 @@ Using iproute2, the following manipulations are possible: .. code-block:: sh - # See the DSA master in current use + # See the DSA conduit in current use ip -d link show dev swp0 (...) dsa master eth0 @@ -414,7 +414,7 @@ Using iproute2, the following manipulations are possible: ip link set swp2 type dsa master eth1 ip link set swp3 type dsa master eth0 - # CPU ports in LAG, using explicit assignment of the DSA master + # CPU ports in LAG, using explicit assignment of the DSA conduit ip link add bond0 type bond mode balance-xor && ip link set bond0 up ip link set eth1 down && ip link set eth1 master bond0 ip link set swp0 type dsa master bond0 @@ -426,7 +426,7 @@ Using iproute2, the following manipulations are possible: (...) dsa master bond0 - # CPU ports in LAG, relying on implicit migration of the DSA master + # CPU ports in LAG, relying on implicit migration of the DSA conduit ip link add bond0 type bond mode balance-xor && ip link set bond0 up ip link set eth0 down && ip link set eth0 master bond0 ip link set eth1 down && ip link set eth1 master bond0 @@ -435,24 +435,24 @@ Using iproute2, the following manipulations are possible: dsa master bond0 Notice that in the case of CPU ports under a LAG, the use of the -``IFLA_DSA_MASTER`` netlink attribute is not strictly needed, but rather, DSA -reacts to the ``IFLA_MASTER`` attribute change of its present master (``eth0``) +``IFLA_DSA_CONDUIT`` netlink attribute is not strictly needed, but rather, DSA +reacts to the ``IFLA_MASTER`` attribute change of its present conduit (``eth0``) and migrates all user ports to the new upper of ``eth0``, ``bond0``. Similarly, when ``bond0`` is destroyed using ``RTM_DELLINK``, DSA migrates the user ports -that were assigned to this interface to the first physical DSA master which is +that were assigned to this interface to the first physical DSA conduit which is eligible, based on the firmware description (it effectively reverts to the startup configuration). In a setup with more than 2 physical CPU ports, it is therefore possible to mix -static user to CPU port assignment with LAG between DSA masters. It is not -possible to statically assign a user port towards a DSA master that has any -upper interfaces (this includes LAG devices - the master must always be the LAG +static user to CPU port assignment with LAG between DSA conduits. It is not +possible to statically assign a user port towards a DSA conduit that has any +upper interfaces (this includes LAG devices - the conduit must always be the LAG in this case). -Live changing of the DSA master (and thus CPU port) affinity of a user port is +Live changing of the DSA conduit (and thus CPU port) affinity of a user port is permitted, in order to allow dynamic redistribution in response to traffic. -Physical DSA masters are allowed to join and leave at any time a LAG interface -used as a DSA master; however, DSA will reject a LAG interface as a valid -candidate for being a DSA master unless it has at least one physical DSA master +Physical DSA conduits are allowed to join and leave at any time a LAG interface +used as a DSA conduit; however, DSA will reject a LAG interface as a valid +candidate for being a DSA conduit unless it has at least one physical DSA conduit as a slave device. diff --git a/Documentation/networking/dsa/dsa.rst b/Documentation/networking/dsa/dsa.rst index a94ddf83348a..7b2e69cd7ef0 100644 --- a/Documentation/networking/dsa/dsa.rst +++ b/Documentation/networking/dsa/dsa.rst @@ -25,7 +25,7 @@ presence of a management port connected to an Ethernet controller capable of receiving Ethernet frames from the switch. This is a very common setup for all kinds of Ethernet switches found in Small Home and Office products: routers, gateways, or even top-of-rack switches. This host Ethernet controller will -be later referred to as "master" and "cpu" in DSA terminology and code. +be later referred to as "conduit" and "cpu" in DSA terminology and code. The D in DSA stands for Distributed, because the subsystem has been designed with the ability to configure and manage cascaded switches on top of each other @@ -35,7 +35,7 @@ of multiple switches connected to each other is called a "switch tree". For each front-panel port, DSA creates specialized network devices which are used as controlling and data-flowing endpoints for use by the Linux networking -stack. These specialized network interfaces are referred to as "slave" network +stack. These specialized network interfaces are referred to as "user" network interfaces in DSA terminology and code. The ideal case for using DSA is when an Ethernet switch supports a "switch tag" @@ -56,12 +56,16 @@ Note that DSA does not currently create network interfaces for the "cpu" and - the "cpu" port is the Ethernet switch facing side of the management controller, and as such, would create a duplication of feature, since you - would get two interfaces for the same conduit: master netdev, and "cpu" netdev + would get two interfaces for the same conduit: conduit netdev, and "cpu" netdev - the "dsa" port(s) are just conduits between two or more switches, and as such cannot really be used as proper network interfaces either, only the downstream, or the top-most upstream interface makes sense with that model +NB: for the past 15 years, the DSA subsystem had been making use of the terms +"master" (rather than "conduit") and "slave" (rather than "user"). These terms +have been removed from the DSA codebase and phased out of the uAPI. + Switch tagging protocols ------------------------ @@ -80,14 +84,14 @@ methods of the ``struct dsa_device_ops`` structure, which are detailed below. Tagging protocols generally fall in one of three categories: 1. The switch-specific frame header is located before the Ethernet header, - shifting to the right (from the perspective of the DSA master's frame + shifting to the right (from the perspective of the DSA conduit's frame parser) the MAC DA, MAC SA, EtherType and the entire L2 payload. 2. The switch-specific frame header is located before the EtherType, keeping - the MAC DA and MAC SA in place from the DSA master's perspective, but + the MAC DA and MAC SA in place from the DSA conduit's perspective, but shifting the 'real' EtherType and L2 payload to the right. 3. The switch-specific frame header is located at the tail of the packet, keeping all frame headers in place and not altering the view of the packet - that the DSA master's frame parser has. + that the DSA conduit's frame parser has. A tagging protocol may tag all packets with switch tags of the same length, or the tag length might vary (for example packets with PTP timestamps might @@ -95,7 +99,7 @@ require an extended switch tag, or there might be one tag length on TX and a different one on RX). Either way, the tagging protocol driver must populate the ``struct dsa_device_ops::needed_headroom`` and/or ``struct dsa_device_ops::needed_tailroom`` with the length in octets of the longest switch frame header/trailer. The DSA -framework will automatically adjust the MTU of the master interface to +framework will automatically adjust the MTU of the conduit interface to accommodate for this extra size in order for DSA user ports to support the standard MTU (L2 payload length) of 1500 octets. The ``needed_headroom`` and ``needed_tailroom`` properties are also used to request from the network stack, @@ -140,18 +144,18 @@ adding or removing the ``ETH_P_EDSA`` EtherType and some padding octets). It is possible to construct cascaded setups of DSA switches even if their tagging protocols are not compatible with one another. In this case, there are no DSA links in this fabric, and each switch constitutes a disjoint DSA switch -tree. The DSA links are viewed as simply a pair of a DSA master (the out-facing +tree. The DSA links are viewed as simply a pair of a DSA conduit (the out-facing port of the upstream DSA switch) and a CPU port (the in-facing port of the downstream DSA switch). The tagging protocol of the attached DSA switch tree can be viewed through the -``dsa/tagging`` sysfs attribute of the DSA master:: +``dsa/tagging`` sysfs attribute of the DSA conduit:: cat /sys/class/net/eth0/dsa/tagging If the hardware and driver are capable, the tagging protocol of the DSA switch tree can be changed at runtime. This is done by writing the new tagging -protocol name to the same sysfs device attribute as above (the DSA master and +protocol name to the same sysfs device attribute as above (the DSA conduit and all attached switch ports must be down while doing this). It is desirable that all tagging protocols are testable with the ``dsa_loop`` @@ -159,7 +163,7 @@ mockup driver, which can be attached to any network interface. The goal is that any network interface should be capable of transmitting the same packet in the same way, and the tagger should decode the same received packet in the same way regardless of the driver used for the switch control path, and the driver used -for the DSA master. +for the DSA conduit. The transmission of a packet goes through the tagger's ``xmit`` function. The passed ``struct sk_buff *skb`` has ``skb->data`` pointing at @@ -183,44 +187,44 @@ virtual DSA user network interface corresponding to the physical front-facing switch port that the packet was received on. Since tagging protocols in category 1 and 2 break software (and most often also -hardware) packet dissection on the DSA master, features such as RPS (Receive -Packet Steering) on the DSA master would be broken. The DSA framework deals +hardware) packet dissection on the DSA conduit, features such as RPS (Receive +Packet Steering) on the DSA conduit would be broken. The DSA framework deals with this by hooking into the flow dissector and shifting the offset at which -the IP header is to be found in the tagged frame as seen by the DSA master. +the IP header is to be found in the tagged frame as seen by the DSA conduit. This behavior is automatic based on the ``overhead`` value of the tagging protocol. If not all packets are of equal size, the tagger can implement the ``flow_dissect`` method of the ``struct dsa_device_ops`` and override this default behavior by specifying the correct offset incurred by each individual RX packet. Tail taggers do not cause issues to the flow dissector. -Checksum offload should work with category 1 and 2 taggers when the DSA master +Checksum offload should work with category 1 and 2 taggers when the DSA conduit driver declares NETIF_F_HW_CSUM in vlan_features and looks at csum_start and csum_offset. For those cases, DSA will shift the checksum start and offset by -the tag size. If the DSA master driver still uses the legacy NETIF_F_IP_CSUM +the tag size. If the DSA conduit driver still uses the legacy NETIF_F_IP_CSUM or NETIF_F_IPV6_CSUM in vlan_features, the offload might only work if the offload hardware already expects that specific tag (perhaps due to matching -vendors). DSA slaves inherit those flags from the master port, and it is up to +vendors). DSA user ports inherit those flags from the conduit, and it is up to the driver to correctly fall back to software checksum when the IP header is not where the hardware expects. If that check is ineffective, the packets might go to the network without a proper checksum (the checksum field will have the pseudo IP header sum). For category 3, when the offload hardware does not already expect the switch tag in use, the checksum must be calculated before any -tag is inserted (i.e. inside the tagger). Otherwise, the DSA master would +tag is inserted (i.e. inside the tagger). Otherwise, the DSA conduit would include the tail tag in the (software or hardware) checksum calculation. Then, when the tag gets stripped by the switch during transmission, it will leave an incorrect IP checksum in place. Due to various reasons (most common being category 1 taggers being associated -with DSA-unaware masters, mangling what the master perceives as MAC DA), the -tagging protocol may require the DSA master to operate in promiscuous mode, to +with DSA-unaware conduits, mangling what the conduit perceives as MAC DA), the +tagging protocol may require the DSA conduit to operate in promiscuous mode, to receive all frames regardless of the value of the MAC DA. This can be done by -setting the ``promisc_on_master`` property of the ``struct dsa_device_ops``. -Note that this assumes a DSA-unaware master driver, which is the norm. +setting the ``promisc_on_conduit`` property of the ``struct dsa_device_ops``. +Note that this assumes a DSA-unaware conduit driver, which is the norm. -Master network devices ----------------------- +Conduit network devices +----------------------- -Master network devices are regular, unmodified Linux network device drivers for +Conduit network devices are regular, unmodified Linux network device drivers for the CPU/management Ethernet interface. Such a driver might occasionally need to know whether DSA is enabled (e.g.: to enable/disable specific offload features), but the DSA subsystem has been proven to work with industry standard drivers: @@ -232,14 +236,14 @@ Ethernet switch. Networking stack hooks ---------------------- -When a master netdev is used with DSA, a small hook is placed in the +When a conduit netdev is used with DSA, a small hook is placed in the networking stack is in order to have the DSA subsystem process the Ethernet switch specific tagging protocol. DSA accomplishes this by registering a specific (and fake) Ethernet type (later becoming ``skb->protocol``) with the networking stack, this is also known as a ``ptype`` or ``packet_type``. A typical Ethernet Frame receive sequence looks like this: -Master network device (e.g.: e1000e): +Conduit network device (e.g.: e1000e): 1. Receive interrupt fires: @@ -269,16 +273,16 @@ Master network device (e.g.: e1000e): - inspect and strip switch tag protocol to determine originating port - locate per-port network device - - invoke ``eth_type_trans()`` with the DSA slave network device + - invoke ``eth_type_trans()`` with the DSA user network device - invoked ``netif_receive_skb()`` -Past this point, the DSA slave network devices get delivered regular Ethernet +Past this point, the DSA user network devices get delivered regular Ethernet frames that can be processed by the networking stack. -Slave network devices ---------------------- +User network devices +-------------------- -Slave network devices created by DSA are stacked on top of their master network +User network devices created by DSA are stacked on top of their conduit network device, each of these network interfaces will be responsible for being a controlling and data-flowing end-point for each front-panel port of the switch. These interfaces are specialized in order to: @@ -289,31 +293,31 @@ These interfaces are specialized in order to: Wake-on-LAN, register dumps... - manage external/internal PHY: link, auto-negotiation, etc. -These slave network devices have custom net_device_ops and ethtool_ops function +These user network devices have custom net_device_ops and ethtool_ops function pointers which allow DSA to introduce a level of layering between the networking stack/ethtool and the switch driver implementation. -Upon frame transmission from these slave network devices, DSA will look up which +Upon frame transmission from these user network devices, DSA will look up which switch tagging protocol is currently registered with these network devices and invoke a specific transmit routine which takes care of adding the relevant switch tag in the Ethernet frames. -These frames are then queued for transmission using the master network device +These frames are then queued for transmission using the conduit network device ``ndo_start_xmit()`` function. Since they contain the appropriate switch tag, the Ethernet switch will be able to process these incoming frames from the management interface and deliver them to the physical switch port. When using multiple CPU ports, it is possible to stack a LAG (bonding/team) -device between the DSA slave devices and the physical DSA masters. The LAG -device is thus also a DSA master, but the LAG slave devices continue to be DSA -masters as well (just with no user port assigned to them; this is needed for -recovery in case the LAG DSA master disappears). Thus, the data path of the LAG -DSA master is used asymmetrically. On RX, the ``ETH_P_XDSA`` handler, which -calls ``dsa_switch_rcv()``, is invoked early (on the physical DSA master; -LAG slave). Therefore, the RX data path of the LAG DSA master is not used. -On the other hand, TX takes place linearly: ``dsa_slave_xmit`` calls -``dsa_enqueue_skb``, which calls ``dev_queue_xmit`` towards the LAG DSA master. -The latter calls ``dev_queue_xmit`` towards one physical DSA master or the +device between the DSA user devices and the physical DSA conduits. The LAG +device is thus also a DSA conduit, but the LAG slave devices continue to be DSA +conduits as well (just with no user port assigned to them; this is needed for +recovery in case the LAG DSA conduit disappears). Thus, the data path of the LAG +DSA conduit is used asymmetrically. On RX, the ``ETH_P_XDSA`` handler, which +calls ``dsa_switch_rcv()``, is invoked early (on the physical DSA conduit; +LAG slave). Therefore, the RX data path of the LAG DSA conduit is not used. +On the other hand, TX takes place linearly: ``dsa_user_xmit`` calls +``dsa_enqueue_skb``, which calls ``dev_queue_xmit`` towards the LAG DSA conduit. +The latter calls ``dev_queue_xmit`` towards one physical DSA conduit or the other, and in both cases, the packet exits the system through a hardware path towards the switch. @@ -352,11 +356,11 @@ perspective:: || swp0 | | swp1 | | swp2 | | swp3 || ++------+-+------+-+------+-+------++ -Slave MDIO bus --------------- +User MDIO bus +------------- -In order to be able to read to/from a switch PHY built into it, DSA creates a -slave MDIO bus which allows a specific switch driver to divert and intercept +In order to be able to read to/from a switch PHY built into it, DSA creates an +user MDIO bus which allows a specific switch driver to divert and intercept MDIO reads/writes towards specific PHY addresses. In most MDIO-connected switches, these functions would utilize direct or indirect PHY addressing mode to return standard MII registers from the switch builtin PHYs, allowing the PHY @@ -364,7 +368,7 @@ library and/or to return link status, link partner pages, auto-negotiation results, etc. For Ethernet switches which have both external and internal MDIO buses, the -slave MII bus can be utilized to mux/demux MDIO reads and writes towards either +user MII bus can be utilized to mux/demux MDIO reads and writes towards either internal or external MDIO devices this switch might be connected to: internal PHYs, external PHYs, or even external switches. @@ -381,10 +385,10 @@ DSA data structures are defined in ``include/net/dsa.h`` as well as - ``dsa_platform_data``: platform device configuration data which can reference a collection of dsa_chip_data structures if multiple switches are cascaded, - the master network device this switch tree is attached to needs to be + the conduit network device this switch tree is attached to needs to be referenced -- ``dsa_switch_tree``: structure assigned to the master network device under +- ``dsa_switch_tree``: structure assigned to the conduit network device under ``dsa_ptr``, this structure references a dsa_platform_data structure as well as the tagging protocol supported by the switch tree, and which receive/transmit function hooks should be invoked, information about the directly attached @@ -392,7 +396,7 @@ DSA data structures are defined in ``include/net/dsa.h`` as well as referenced to address individual switches in the tree. - ``dsa_switch``: structure describing a switch device in the tree, referencing - a ``dsa_switch_tree`` as a backpointer, slave network devices, master network + a ``dsa_switch_tree`` as a backpointer, user network devices, conduit network device, and a reference to the backing``dsa_switch_ops`` - ``dsa_switch_ops``: structure referencing function pointers, see below for a @@ -404,7 +408,7 @@ Design limitations Lack of CPU/DSA network devices ------------------------------- -DSA does not currently create slave network devices for the CPU or DSA ports, as +DSA does not currently create user network devices for the CPU or DSA ports, as described before. This might be an issue in the following cases: - inability to fetch switch CPU port statistics counters using ethtool, which @@ -419,7 +423,7 @@ described before. This might be an issue in the following cases: Common pitfalls using DSA setups -------------------------------- -Once a master network device is configured to use DSA (dev->dsa_ptr becomes +Once a conduit network device is configured to use DSA (dev->dsa_ptr becomes non-NULL), and the switch behind it expects a tagging protocol, this network interface can only exclusively be used as a conduit interface. Sending packets directly through this interface (e.g.: opening a socket using this interface) @@ -440,7 +444,7 @@ DSA currently leverages the following subsystems: MDIO/PHY library ---------------- -Slave network devices exposed by DSA may or may not be interfacing with PHY +User network devices exposed by DSA may or may not be interfacing with PHY devices (``struct phy_device`` as defined in ``include/linux/phy.h)``, but the DSA subsystem deals with all possible combinations: @@ -450,7 +454,7 @@ subsystem deals with all possible combinations: - special, non-autonegotiated or non MDIO-managed PHY devices: SFPs, MoCA; a.k.a fixed PHYs -The PHY configuration is done by the ``dsa_slave_phy_setup()`` function and the +The PHY configuration is done by the ``dsa_user_phy_setup()`` function and the logic basically looks like this: - if Device Tree is used, the PHY device is looked up using the standard @@ -463,7 +467,7 @@ logic basically looks like this: and connected transparently using the special fixed MDIO bus driver - finally, if the PHY is built into the switch, as is very common with - standalone switch packages, the PHY is probed using the slave MII bus created + standalone switch packages, the PHY is probed using the user MII bus created by DSA @@ -472,7 +476,7 @@ SWITCHDEV DSA directly utilizes SWITCHDEV when interfacing with the bridge layer, and more specifically with its VLAN filtering portion when configuring VLANs on top -of per-port slave network devices. As of today, the only SWITCHDEV objects +of per-port user network devices. As of today, the only SWITCHDEV objects supported by DSA are the FDB and VLAN objects. Devlink @@ -589,8 +593,8 @@ is torn down when the first switch unregisters. It is mandatory for DSA switch drivers to implement the ``shutdown()`` callback of their respective bus, and call ``dsa_switch_shutdown()`` from it (a minimal version of the full teardown performed by ``dsa_unregister_switch()``). -The reason is that DSA keeps a reference on the master net device, and if the -driver for the master device decides to unbind on shutdown, DSA's reference +The reason is that DSA keeps a reference on the conduit net device, and if the +driver for the conduit device decides to unbind on shutdown, DSA's reference will block that operation from finalizing. Either ``dsa_switch_shutdown()`` or ``dsa_unregister_switch()`` must be called, @@ -615,7 +619,7 @@ Switch configuration tag formats. - ``change_tag_protocol``: when the default tagging protocol has compatibility - problems with the master or other issues, the driver may support changing it + problems with the conduit or other issues, the driver may support changing it at runtime, either through a device tree property or through sysfs. In that case, further calls to ``get_tag_protocol`` should report the protocol in current use. @@ -643,22 +647,22 @@ Switch configuration PHY cannot be found. In this case, probing of the DSA switch continues without that particular port. -- ``port_change_master``: method through which the affinity (association used +- ``port_change_conduit``: method through which the affinity (association used for traffic termination purposes) between a user port and a CPU port can be changed. By default all user ports from a tree are assigned to the first available CPU port that makes sense for them (most of the times this means the user ports of a tree are all assigned to the same CPU port, except for H topologies as described in commit 2c0b03258b8b). The ``port`` argument - represents the index of the user port, and the ``master`` argument represents - the new DSA master ``net_device``. The CPU port associated with the new - master can be retrieved by looking at ``struct dsa_port *cpu_dp = - master->dsa_ptr``. Additionally, the master can also be a LAG device where - all the slave devices are physical DSA masters. LAG DSA masters also have a - valid ``master->dsa_ptr`` pointer, however this is not unique, but rather a - duplicate of the first physical DSA master's (LAG slave) ``dsa_ptr``. In case - of a LAG DSA master, a further call to ``port_lag_join`` will be emitted + represents the index of the user port, and the ``conduit`` argument represents + the new DSA conduit ``net_device``. The CPU port associated with the new + conduit can be retrieved by looking at ``struct dsa_port *cpu_dp = + conduit->dsa_ptr``. Additionally, the conduit can also be a LAG device where + all the slave devices are physical DSA conduits. LAG DSA also have a + valid ``conduit->dsa_ptr`` pointer, however this is not unique, but rather a + duplicate of the first physical DSA conduit's (LAG slave) ``dsa_ptr``. In case + of a LAG DSA conduit, a further call to ``port_lag_join`` will be emitted separately for the physical CPU ports associated with the physical DSA - masters, requesting them to create a hardware LAG associated with the LAG + conduits, requesting them to create a hardware LAG associated with the LAG interface. PHY devices and link management @@ -670,16 +674,16 @@ PHY devices and link management should return a 32-bit bitmask of "flags" that is private between the switch driver and the Ethernet PHY driver in ``drivers/net/phy/\*``. -- ``phy_read``: Function invoked by the DSA slave MDIO bus when attempting to read +- ``phy_read``: Function invoked by the DSA user MDIO bus when attempting to read the switch port MDIO registers. If unavailable, return 0xffff for each read. For builtin switch Ethernet PHYs, this function should allow reading the link status, auto-negotiation results, link partner pages, etc. -- ``phy_write``: Function invoked by the DSA slave MDIO bus when attempting to write +- ``phy_write``: Function invoked by the DSA user MDIO bus when attempting to write to the switch port MDIO registers. If unavailable return a negative error code. -- ``adjust_link``: Function invoked by the PHY library when a slave network device +- ``adjust_link``: Function invoked by the PHY library when a user network device is attached to a PHY device. This function is responsible for appropriately configuring the switch port link parameters: speed, duplex, pause based on what the ``phy_device`` is providing. @@ -698,14 +702,14 @@ Ethtool operations typically return statistics strings, private flags strings, etc. - ``get_ethtool_stats``: ethtool function used to query per-port statistics and - return their values. DSA overlays slave network devices general statistics: + return their values. DSA overlays user network devices general statistics: RX/TX counters from the network device, with switch driver specific statistics per port - ``get_sset_count``: ethtool function used to query the number of statistics items - ``get_wol``: ethtool function used to obtain Wake-on-LAN settings per-port, this - function may for certain implementations also query the master network device + function may for certain implementations also query the conduit network device Wake-on-LAN settings if this interface needs to participate in Wake-on-LAN - ``set_wol``: ethtool function used to configure Wake-on-LAN settings per-port, @@ -747,13 +751,13 @@ Power management should resume all Ethernet switch activities and re-configure the switch to be in a fully active state -- ``port_enable``: function invoked by the DSA slave network device ndo_open +- ``port_enable``: function invoked by the DSA user network device ndo_open function when a port is administratively brought up, this function should fully enable a given switch port. DSA takes care of marking the port with ``BR_STATE_BLOCKING`` if the port is a bridge member, or ``BR_STATE_FORWARDING`` if it was not, and propagating these changes down to the hardware -- ``port_disable``: function invoked by the DSA slave network device ndo_close +- ``port_disable``: function invoked by the DSA user network device ndo_close function when a port is administratively brought down, this function should fully disable a given switch port. DSA takes care of marking the port with ``BR_STATE_DISABLED`` and propagating changes to the hardware if this port is diff --git a/Documentation/networking/dsa/lan9303.rst b/Documentation/networking/dsa/lan9303.rst index e3c820db28ad..ab81b4e0139e 100644 --- a/Documentation/networking/dsa/lan9303.rst +++ b/Documentation/networking/dsa/lan9303.rst @@ -4,7 +4,7 @@ LAN9303 Ethernet switch driver The LAN9303 is a three port 10/100 Mbps ethernet switch with integrated phys for the two external ethernet ports. The third port is an RMII/MII interface to a -host master network interface (e.g. fixed link). +host conduit network interface (e.g. fixed link). Driver details diff --git a/Documentation/networking/dsa/sja1105.rst b/Documentation/networking/dsa/sja1105.rst index e0219c1452ab..8ab60eef07d4 100644 --- a/Documentation/networking/dsa/sja1105.rst +++ b/Documentation/networking/dsa/sja1105.rst @@ -79,7 +79,7 @@ The hardware tags all traffic internally with a port-based VLAN (pvid), or it decodes the VLAN information from the 802.1Q tag. Advanced VLAN classification is not possible. Once attributed a VLAN tag, frames are checked against the port's membership rules and dropped at ingress if they don't match any VLAN. -This behavior is available when switch ports are enslaved to a bridge with +This behavior is available when switch ports join a bridge with ``vlan_filtering 1``. Normally the hardware is not configurable with respect to VLAN awareness, but @@ -122,7 +122,7 @@ on egress. Using ``vlan_filtering=1``, the behavior is the other way around: offloaded flows can be steered to TX queues based on the VLAN PCP, but the DSA net devices are no longer able to do that. To inject frames into a hardware TX queue with VLAN awareness active, it is necessary to create a VLAN -sub-interface on the DSA master port, and send normal (0x8100) VLAN-tagged +sub-interface on the DSA conduit port, and send normal (0x8100) VLAN-tagged towards the switch, with the VLAN PCP bits set appropriately. Management traffic (having DMAC 01-80-C2-xx-xx-xx or 01-19-1B-xx-xx-xx) is the @@ -389,7 +389,7 @@ MDIO bus and PHY management The SJA1105 does not have an MDIO bus and does not perform in-band AN either. Therefore there is no link state notification coming from the switch device. A board would need to hook up the PHYs connected to the switch to any other -MDIO bus available to Linux within the system (e.g. to the DSA master's MDIO +MDIO bus available to Linux within the system (e.g. to the DSA conduit's MDIO bus). Link state management then works by the driver manually keeping in sync (over SPI commands) the MAC link speed with the settings negotiated by the PHY. diff --git a/Documentation/networking/filter.rst b/Documentation/networking/filter.rst index f69da5074860..7d8c5380492f 100644 --- a/Documentation/networking/filter.rst +++ b/Documentation/networking/filter.rst @@ -650,8 +650,8 @@ before a conversion to the new layout is being done behind the scenes! Currently, the classic BPF format is being used for JITing on most 32-bit architectures, whereas x86-64, aarch64, s390x, powerpc64, -sparc64, arm32, riscv64, riscv32 perform JIT compilation from eBPF -instruction set. +sparc64, arm32, riscv64, riscv32, loongarch64 perform JIT compilation +from eBPF instruction set. Testing ------- diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 5b75c3f7a137..683eb42309cc 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -59,7 +59,6 @@ Contents: gtp ila ioam6-sysctl - ipddp ip_dynaddr ipsec ip-sysctl @@ -107,6 +106,7 @@ Contents: sysfs-tagging tc-actions-env-rules tc-queue-filters + tcp_ao tcp-thin team timestamping diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst index 4a010a7cde7f..4dfe0d9a57bb 100644 --- a/Documentation/networking/ip-sysctl.rst +++ b/Documentation/networking/ip-sysctl.rst @@ -321,6 +321,7 @@ tcp_abort_on_overflow - BOOLEAN option can harm clients of your server. tcp_adv_win_scale - INTEGER + Obsolete since linux-6.6 Count buffering overhead as bytes/2^tcp_adv_win_scale (if tcp_adv_win_scale > 0) or bytes-bytes/2^(-tcp_adv_win_scale), if it is <= 0. @@ -744,6 +745,13 @@ tcp_comp_sack_nr - INTEGER Default : 44 +tcp_backlog_ack_defer - BOOLEAN + If set, user thread processing socket backlog tries sending + one ACK for the whole queue. This helps to avoid potential + long latencies at end of a TCP socket syscall. + + Default : true + tcp_slow_start_after_idle - BOOLEAN If set, provide RFC2861 behavior and time out the congestion window after an idle period. An idle period is defined at @@ -1175,6 +1183,19 @@ tcp_plb_cong_thresh - INTEGER Default: 128 +tcp_pingpong_thresh - INTEGER + The number of estimated data replies sent for estimated incoming data + requests that must happen before TCP considers that a connection is a + "ping-pong" (request-response) connection for which delayed + acknowledgments can provide benefits. + + This threshold is 1 by default, but some applications may need a higher + threshold for optimal performance. + + Possible Values: 1 - 255 + + Default: 1 + UDP variables ============= @@ -2287,6 +2308,14 @@ accept_ra_min_hop_limit - INTEGER Default: 1 +accept_ra_min_lft - INTEGER + Minimum acceptable lifetime value in Router Advertisement. + + RA sections with a lifetime less than this value shall be + ignored. Zero lifetimes stay unaffected. + + Default: 0 + accept_ra_pinfo - BOOLEAN Learn Prefix Information in Router Advertisement. @@ -2295,6 +2324,17 @@ accept_ra_pinfo - BOOLEAN - enabled if accept_ra is enabled. - disabled if accept_ra is disabled. +ra_honor_pio_life - BOOLEAN + Whether to use RFC4862 Section 5.5.3e to determine the valid + lifetime of an address matching a prefix sent in a Router + Advertisement Prefix Information Option. + + - If enabled, the PIO valid lifetime will always be honored. + - If disabled, RFC4862 section 5.5.3e is used to determine + the valid lifetime of the address. + + Default: 0 (disabled) + accept_ra_rt_info_min_plen - INTEGER Minimum prefix length of Route Information in RA. @@ -2462,12 +2502,18 @@ use_tempaddr - INTEGER * -1 (for point-to-point devices and loopback devices) temp_valid_lft - INTEGER - valid lifetime (in seconds) for temporary addresses. + valid lifetime (in seconds) for temporary addresses. If less than the + minimum required lifetime (typically 5 seconds), temporary addresses + will not be created. Default: 172800 (2 days) temp_prefered_lft - INTEGER - Preferred lifetime (in seconds) for temporary addresses. + Preferred lifetime (in seconds) for temporary addresses. If + temp_prefered_lft is less than the minimum required lifetime (typically + 5 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. Default: 86400 (1 day) diff --git a/Documentation/networking/ipddp.rst b/Documentation/networking/ipddp.rst deleted file mode 100644 index be7091b77927..000000000000 --- a/Documentation/networking/ipddp.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -========================================================= -AppleTalk-IP Decapsulation and AppleTalk-IP Encapsulation -========================================================= - -Documentation ipddp.c - -This file is written by Jay Schulist <jschlst@samba.org> - -Introduction ------------- - -AppleTalk-IP (IPDDP) is the method computers connected to AppleTalk -networks can use to communicate via IP. AppleTalk-IP is simply IP datagrams -inside AppleTalk packets. - -Through this driver you can either allow your Linux box to communicate -IP over an AppleTalk network or you can provide IP gatewaying functions -for your AppleTalk users. - -You can currently encapsulate or decapsulate AppleTalk-IP on LocalTalk, -EtherTalk and PPPTalk. The only limit on the protocol is that of what -kernel AppleTalk layer and drivers are available. - -Each mode requires its own user space software. - -Compiling AppleTalk-IP Decapsulation/Encapsulation -================================================== - -AppleTalk-IP decapsulation needs to be compiled into your kernel. You -will need to turn on AppleTalk-IP driver support. Then you will need to -select ONE of the two options; IP to AppleTalk-IP encapsulation support or -AppleTalk-IP to IP decapsulation support. If you compile the driver -statically you will only be able to use the driver for the function you have -enabled in the kernel. If you compile the driver as a module you can -select what mode you want it to run in via a module loading param. -ipddp_mode=1 for AppleTalk-IP encapsulation and ipddp_mode=2 for -AppleTalk-IP to IP decapsulation. - -Basic instructions for user space tools -======================================= - -I will briefly describe the operation of the tools, but you will -need to consult the supporting documentation for each set of tools. - -Decapsulation - You will need to download a software package called -MacGate. In this distribution there will be a tool called MacRoute -which enables you to add routes to the kernel for your Macs by hand. -Also the tool MacRegGateWay is included to register the -proper IP Gateway and IP addresses for your machine. Included in this -distribution is a patch to netatalk-1.4b2+asun2.0a17.2 (available from -ftp.u.washington.edu/pub/user-supported/asun/) this patch is optional -but it allows automatic adding and deleting of routes for Macs. (Handy -for locations with large Mac installations) - -Encapsulation - You will need to download a software daemon called ipddpd. -This software expects there to be an AppleTalk-IP gateway on the network. -You will also need to add the proper routes to route your Linux box's IP -traffic out the ipddp interface. - -Common Uses of ipddp.c ----------------------- -Of course AppleTalk-IP decapsulation and encapsulation, but specifically -decapsulation is being used most for connecting LocalTalk networks to -IP networks. Although it has been used on EtherTalk networks to allow -Macs that are only able to tunnel IP over EtherTalk. - -Encapsulation has been used to allow a Linux box stuck on a LocalTalk -network to use IP. It should work equally well if you are stuck on an -EtherTalk only network. - -Further Assistance -------------------- -You can contact me (Jay Schulist <jschlst@samba.org>) with any -questions regarding decapsulation or encapsulation. Bradford W. Johnson -<johns393@maroon.tc.umn.edu> originally wrote the ipddp.c driver for IP -encapsulation in AppleTalk. diff --git a/Documentation/networking/mptcp-sysctl.rst b/Documentation/networking/mptcp-sysctl.rst index 213510698014..69975ce25a02 100644 --- a/Documentation/networking/mptcp-sysctl.rst +++ b/Documentation/networking/mptcp-sysctl.rst @@ -25,6 +25,17 @@ add_addr_timeout - INTEGER (seconds) Default: 120 +close_timeout - INTEGER (seconds) + Set the make-after-break timeout: in absence of any close or + shutdown syscall, MPTCP sockets will maintain the status + unchanged for such time, after the last subflow removal, before + moving to TCP_CLOSE. + + The default value matches TCP_TIMEWAIT_LEN. This is a per-namespace + sysctl. + + Default: 60 + checksum_enabled - BOOLEAN Control whether DSS checksum can be enabled. @@ -74,3 +85,11 @@ stale_loss_cnt - INTEGER This is a per-namespace sysctl. Default: 4 + +scheduler - STRING + Select the scheduler of your choice. + + Support for selection of different schedulers. This is a per-namespace + sysctl. + + Default: "default" diff --git a/Documentation/networking/msg_zerocopy.rst b/Documentation/networking/msg_zerocopy.rst index b3ea96af9b49..78fb70e748b7 100644 --- a/Documentation/networking/msg_zerocopy.rst +++ b/Documentation/networking/msg_zerocopy.rst @@ -7,7 +7,8 @@ Intro ===== The MSG_ZEROCOPY flag enables copy avoidance for socket send calls. -The feature is currently implemented for TCP and UDP sockets. +The feature is currently implemented for TCP, UDP and VSOCK (with +virtio transport) sockets. Opportunity and Caveats @@ -174,7 +175,9 @@ read_notification() call in the previous snippet. A notification is encoded in the standard error format, sock_extended_err. The level and type fields in the control data are protocol family -specific, IP_RECVERR or IPV6_RECVERR. +specific, IP_RECVERR or IPV6_RECVERR (for TCP or UDP socket). +For VSOCK socket, cmsg_level will be SOL_VSOCK and cmsg_type will be +VSOCK_RECVERR. Error origin is the new type SO_EE_ORIGIN_ZEROCOPY. ee_errno is zero, as explained before, to avoid blocking read and write system calls on @@ -235,12 +238,15 @@ Implementation Loopback -------- +For TCP and UDP: Data sent to local sockets can be queued indefinitely if the receive process does not read its socket. Unbound notification latency is not acceptable. For this reason all packets generated with MSG_ZEROCOPY that are looped to a local socket will incur a deferred copy. This includes looping onto packet sockets (e.g., tcpdump) and tun devices. +For VSOCK: +Data path sent to local sockets is the same as for non-local sockets. Testing ======= @@ -254,3 +260,6 @@ instance when run with msg_zerocopy.sh between a veth pair across namespaces, the test will not show any improvement. For testing, the loopback restriction can be temporarily relaxed by making skb_orphan_frags_rx identical to skb_orphan_frags. + +For VSOCK type of socket example can be found in +tools/testing/vsock/vsock_test_zerocopy.c. diff --git a/Documentation/networking/napi.rst b/Documentation/networking/napi.rst index a7a047742e93..7bf7b95c4f7a 100644 --- a/Documentation/networking/napi.rst +++ b/Documentation/networking/napi.rst @@ -65,15 +65,16 @@ argument - drivers can process completions for any number of Tx packets but should only process up to ``budget`` number of Rx packets. Rx processing is usually much more expensive. -In other words, it is recommended to ignore the budget argument when -performing TX buffer reclamation to ensure that the reclamation is not -arbitrarily bounded; however, it is required to honor the budget argument -for RX processing. +In other words for Rx processing the ``budget`` argument limits how many +packets driver can process in a single poll. Rx specific APIs like page +pool or XDP cannot be used at all when ``budget`` is 0. +skb Tx processing should happen regardless of the ``budget``, but if +the argument is 0 driver cannot call any XDP (or page pool) APIs. .. warning:: - The ``budget`` argument may be 0 if core tries to only process Tx completions - and no Rx packets. + The ``budget`` argument may be 0 if core tries to only process + skb Tx completions and no Rx or XDP packets. The poll method returns the amount of work done. If the driver still has outstanding work to do (e.g. ``budget`` was exhausted) diff --git a/Documentation/networking/netconsole.rst b/Documentation/networking/netconsole.rst index dd0518e002f6..390730a74332 100644 --- a/Documentation/networking/netconsole.rst +++ b/Documentation/networking/netconsole.rst @@ -13,6 +13,8 @@ IPv6 support by Cong Wang <xiyou.wangcong@gmail.com>, Jan 1 2013 Extended console support by Tejun Heo <tj@kernel.org>, May 1 2015 +Release prepend support by Breno Leitao <leitao@debian.org>, Jul 7 2023 + Please send bug reports to Matt Mackall <mpm@selenic.com> Satyam Sharma <satyam.sharma@gmail.com>, and Cong Wang <xiyou.wangcong@gmail.com> @@ -34,10 +36,11 @@ Sender and receiver configuration: It takes a string configuration parameter "netconsole" in the following format:: - netconsole=[+][src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr] + netconsole=[+][r][src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr] where + if present, enable extended console support + r if present, prepend kernel version (release) to the message src-port source for UDP packets (defaults to 6665) src-ip source IP to use (interface address) dev network interface (eth0) @@ -96,9 +99,6 @@ Dynamic reconfiguration: Dynamic reconfigurability is a useful addition to netconsole that enables remote logging targets to be dynamically added, removed, or have their parameters reconfigured at runtime from a configfs-based userspace interface. -[ Note that the parameters of netconsole targets that were specified/created -from the boot/module option are not exposed via this interface, and hence -cannot be modified dynamically. ] To include this feature, select CONFIG_NETCONSOLE_DYNAMIC when building the netconsole module (or kernel, if netconsole is built-in). @@ -125,6 +125,7 @@ The interface exposes these parameters of a netconsole target to userspace: ============== ================================= ============ enabled Is this target currently enabled? (read-write) extended Extended mode enabled (read-write) + release Prepend kernel release to message (read-write) dev_name Local network interface name (read-write) local_port Source UDP port to use (read-write) remote_port Remote agent's UDP port (read-write) @@ -151,6 +152,25 @@ You can also update the local interface dynamically. This is especially useful if you want to use interfaces that have newly come up (and may not have existed when netconsole was loaded / initialized). +Netconsole targets defined at boot time (or module load time) with the +`netconsole=` param are assigned the name `cmdline<index>`. For example, the +first target in the parameter is named `cmdline0`. You can control and modify +these targets by creating configfs directories with the matching name. + +Let's suppose you have two netconsole targets defined at boot time:: + + netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc;4444@10.0.0.1/eth1,9353@10.0.0.3/12:34:56:78:9a:bc + +You can modify these targets in runtime by creating the following targets:: + + mkdir cmdline0 + cat cmdline0/remote_ip + 10.0.0.2 + + mkdir cmdline1 + cat cmdline1/remote_ip + 10.0.0.3 + Extended console: ================= @@ -165,6 +185,11 @@ following format which is the same as /dev/kmsg:: <level>,<sequnum>,<timestamp>,<contflag>;<message text> +If 'r' (release) feature is enabled, the kernel release version is +prepended to the start of the message. Example:: + + 6.4.0,6,444,501151268,-;netconsole: network logging started + Non printable characters in <message text> are escaped using "\xff" notation. If the message contains optional dictionary, verbatim newline is used as the delimiter. diff --git a/Documentation/networking/nf_conntrack-sysctl.rst b/Documentation/networking/nf_conntrack-sysctl.rst index 8b1045c3b59e..c383a394c665 100644 --- a/Documentation/networking/nf_conntrack-sysctl.rst +++ b/Documentation/networking/nf_conntrack-sysctl.rst @@ -178,10 +178,10 @@ nf_conntrack_sctp_timeout_established - INTEGER (seconds) Default is set to (hb_interval * path_max_retrans + rto_max) nf_conntrack_sctp_timeout_shutdown_sent - INTEGER (seconds) - default 0.3 + default 3 nf_conntrack_sctp_timeout_shutdown_recd - INTEGER (seconds) - default 0.3 + default 3 nf_conntrack_sctp_timeout_shutdown_ack_sent - INTEGER (seconds) default 3 diff --git a/Documentation/networking/packet_mmap.rst b/Documentation/networking/packet_mmap.rst index c5da1a5d93de..30a3be3c48f3 100644 --- a/Documentation/networking/packet_mmap.rst +++ b/Documentation/networking/packet_mmap.rst @@ -755,7 +755,7 @@ AF_PACKET TPACKET_V3 example ============================ AF_PACKET's TPACKET_V3 ring buffer can be configured to use non-static frame -sizes by doing it's own memory management. It is based on blocks where polling +sizes by doing its own memory management. It is based on blocks where polling works on a per block basis instead of per ring as in TPACKET_V2 and predecessor. It is said that TPACKET_V3 brings the following benefits: diff --git a/Documentation/networking/page_pool.rst b/Documentation/networking/page_pool.rst index 873efd97f822..60993cb56b32 100644 --- a/Documentation/networking/page_pool.rst +++ b/Documentation/networking/page_pool.rst @@ -4,22 +4,8 @@ Page Pool API ============= -The page_pool allocator is optimized for the XDP mode that uses one frame -per-page, but it can fallback on the regular page allocator APIs. - -Basic use involves replacing alloc_pages() calls with the -page_pool_alloc_pages() call. Drivers should use page_pool_dev_alloc_pages() -replacing dev_alloc_pages(). - -API keeps track of in-flight pages, in order to let API user know -when it is safe to free a page_pool object. Thus, API users -must run page_pool_release_page() when a page is leaving the page_pool or -call page_pool_put_page() where appropriate in order to maintain correct -accounting. - -API user must call page_pool_put_page() once on a page, as it -will either recycle the page, or in case of refcnt > 1, it will -release the DMA mapping and in-flight state accounting. +.. kernel-doc:: include/net/page_pool/helpers.h + :doc: page_pool allocator Architecture overview ===================== @@ -64,87 +50,70 @@ This lockless guarantee naturally comes from running under a NAPI softirq. The protection doesn't strictly have to be NAPI, any guarantee that allocating a page will cause no race conditions is enough. -* page_pool_create(): Create a pool. - * flags: PP_FLAG_DMA_MAP, PP_FLAG_DMA_SYNC_DEV - * order: 2^order pages on allocation - * pool_size: size of the ptr_ring - * nid: preferred NUMA node for allocation - * dev: struct device. Used on DMA operations - * dma_dir: DMA direction - * max_len: max DMA sync memory size - * offset: DMA address offset - -* page_pool_put_page(): The outcome of this depends on the page refcnt. If the - driver bumps the refcnt > 1 this will unmap the page. If the page refcnt is 1 - the allocator owns the page and will try to recycle it in one of the pool - caches. If PP_FLAG_DMA_SYNC_DEV is set, the page will be synced for_device - using dma_sync_single_range_for_device(). - -* page_pool_put_full_page(): Similar to page_pool_put_page(), but will DMA sync - for the entire memory area configured in area pool->max_len. - -* page_pool_recycle_direct(): Similar to page_pool_put_full_page() but caller - must guarantee safe context (e.g NAPI), since it will recycle the page - directly into the pool fast cache. - -* page_pool_release_page(): Unmap the page (if mapped) and account for it on - in-flight counters. - -* page_pool_dev_alloc_pages(): Get a page from the page allocator or page_pool - caches. - -* page_pool_get_dma_addr(): Retrieve the stored DMA address. - -* page_pool_get_dma_dir(): Retrieve the stored DMA direction. - -* page_pool_put_page_bulk(): Tries to refill a number of pages into the - ptr_ring cache holding ptr_ring producer lock. If the ptr_ring is full, - page_pool_put_page_bulk() will release leftover pages to the page allocator. - page_pool_put_page_bulk() is suitable to be run inside the driver NAPI tx - completion loop for the XDP_REDIRECT use case. - Please note the caller must not use data area after running - page_pool_put_page_bulk(), as this function overwrites it. - -* page_pool_get_stats(): Retrieve statistics about the page_pool. This API - is only available if the kernel has been configured with - ``CONFIG_PAGE_POOL_STATS=y``. A pointer to a caller allocated ``struct - page_pool_stats`` structure is passed to this API which is filled in. The - caller can then report those stats to the user (perhaps via ethtool, - debugfs, etc.). See below for an example usage of this API. +.. kernel-doc:: net/core/page_pool.c + :identifiers: page_pool_create + +.. kernel-doc:: include/net/page_pool/types.h + :identifiers: struct page_pool_params + +.. kernel-doc:: include/net/page_pool/helpers.h + :identifiers: page_pool_put_page page_pool_put_full_page + page_pool_recycle_direct page_pool_free_va + page_pool_dev_alloc_pages page_pool_dev_alloc_frag + page_pool_dev_alloc page_pool_dev_alloc_va + page_pool_get_dma_addr page_pool_get_dma_dir + +.. kernel-doc:: net/core/page_pool.c + :identifiers: page_pool_put_page_bulk page_pool_get_stats + +DMA sync +-------- +Driver is always responsible for syncing the pages for the CPU. +Drivers may choose to take care of syncing for the device as well +or set the ``PP_FLAG_DMA_SYNC_DEV`` flag to request that pages +allocated from the page pool are already synced for the device. + +If ``PP_FLAG_DMA_SYNC_DEV`` is set, the driver must inform the core what portion +of the buffer has to be synced. This allows the core to avoid syncing the entire +page when the drivers knows that the device only accessed a portion of the page. + +Most drivers will reserve headroom in front of the frame. This part +of the buffer is not touched by the device, so to avoid syncing +it drivers can set the ``offset`` field in struct page_pool_params +appropriately. + +For pages recycled on the XDP xmit and skb paths the page pool will +use the ``max_len`` member of struct page_pool_params to decide how +much of the page needs to be synced (starting at ``offset``). +When directly freeing pages in the driver (page_pool_put_page()) +the ``dma_sync_size`` argument specifies how much of the buffer needs +to be synced. + +If in doubt set ``offset`` to 0, ``max_len`` to ``PAGE_SIZE`` and +pass -1 as ``dma_sync_size``. That combination of arguments is always +correct. + +Note that the syncing parameters are for the entire page. +This is important to remember when using fragments (``PP_FLAG_PAGE_FRAG``), +where allocated buffers may be smaller than a full page. +Unless the driver author really understands page pool internals +it's recommended to always use ``offset = 0``, ``max_len = PAGE_SIZE`` +with fragmented page pools. Stats API and structures ------------------------ If the kernel is configured with ``CONFIG_PAGE_POOL_STATS=y``, the API -``page_pool_get_stats()`` and structures described below are available. It -takes a pointer to a ``struct page_pool`` and a pointer to a ``struct -page_pool_stats`` allocated by the caller. +page_pool_get_stats() and structures described below are available. +It takes a pointer to a ``struct page_pool`` and a pointer to a struct +page_pool_stats allocated by the caller. -The API will fill in the provided ``struct page_pool_stats`` with +The API will fill in the provided struct page_pool_stats with statistics about the page_pool. -The stats structure has the following fields:: - - struct page_pool_stats { - struct page_pool_alloc_stats alloc_stats; - struct page_pool_recycle_stats recycle_stats; - }; - - -The ``struct page_pool_alloc_stats`` has the following fields: - * ``fast``: successful fast path allocations - * ``slow``: slow path order-0 allocations - * ``slow_high_order``: slow path high order allocations - * ``empty``: ptr ring is empty, so a slow path allocation was forced. - * ``refill``: an allocation which triggered a refill of the cache - * ``waive``: pages obtained from the ptr ring that cannot be added to - the cache due to a NUMA mismatch. - -The ``struct page_pool_recycle_stats`` has the following fields: - * ``cached``: recycling placed page in the page pool cache - * ``cache_full``: page pool cache was full - * ``ring``: page placed into the ptr ring - * ``ring_full``: page released from page pool because the ptr ring was full - * ``released_refcnt``: page released (and not recycled) because refcnt > 1 +.. kernel-doc:: include/net/page_pool/types.h + :identifiers: struct page_pool_recycle_stats + struct page_pool_alloc_stats + struct page_pool_stats Coding examples =============== @@ -194,7 +163,7 @@ NAPI poller if XDP_DROP: page_pool_recycle_direct(page_pool, page); } else (packet_is_skb) { - page_pool_release_page(page_pool, page); + skb_mark_for_recycle(skb); new_page = page_pool_dev_alloc_pages(page_pool); } } diff --git a/Documentation/networking/phy.rst b/Documentation/networking/phy.rst index b7ac4c64cf67..1283240d7620 100644 --- a/Documentation/networking/phy.rst +++ b/Documentation/networking/phy.rst @@ -323,6 +323,10 @@ Some of the interface modes are described below: contrast with the 1000BASE-X phy mode used for Clause 38 and 39 PMDs, this interface mode has different autonegotiation and only supports full duplex. +``PHY_INTERFACE_MODE_PSGMII`` + This is the Penta SGMII mode, it is similar to QSGMII but it combines 5 + SGMII lines into a single link compared to 4 on QSGMII. + Pause frames / flow control =========================== diff --git a/Documentation/networking/pktgen.rst b/Documentation/networking/pktgen.rst index 1225f0f63ff0..c945218946e1 100644 --- a/Documentation/networking/pktgen.rst +++ b/Documentation/networking/pktgen.rst @@ -178,6 +178,7 @@ Examples:: IPSEC # IPsec encapsulation (needs CONFIG_XFRM) NODE_ALLOC # node specific memory allocation NO_TIMESTAMP # disable timestamping + SHARED # enable shared SKB pgset 'flag ![name]' Clear a flag to determine behaviour. Note that you might need to use single quote in interactive mode, so that your shell wouldn't expand @@ -288,6 +289,16 @@ To avoid breaking existing testbed scripts for using AH type and tunnel mode, you can use "pgset spi SPI_VALUE" to specify which transformation mode to employ. +Disable shared SKB +================== +By default, SKBs sent by pktgen are shared (user count > 1). +To test with non-shared SKBs, remove the "SHARED" flag by simply setting:: + + pg_set "flag !SHARED" + +However, if the "clone_skb" or "burst" parameters are configured, the skb +still needs to be held by pktgen for further access. Hence the skb must be +shared. Current commands and configuration options ========================================== @@ -357,6 +368,7 @@ Current commands and configuration options IPSEC NODE_ALLOC NO_TIMESTAMP + SHARED spi (ipsec) diff --git a/Documentation/networking/representors.rst b/Documentation/networking/representors.rst index ee1f5cd54496..decb39c19b9e 100644 --- a/Documentation/networking/representors.rst +++ b/Documentation/networking/representors.rst @@ -162,9 +162,11 @@ How are representors identified? The representor netdevice should *not* directly refer to a PCIe device (e.g. through ``net_dev->dev.parent`` / ``SET_NETDEV_DEV()``), either of the representee or of the switchdev function. -Instead, it should implement the ``ndo_get_devlink_port()`` netdevice op, which -the kernel uses to provide the ``phys_switch_id`` and ``phys_port_name`` sysfs -nodes. (Some legacy drivers implement ``ndo_get_port_parent_id()`` and +Instead, the driver should use the ``SET_NETDEV_DEVLINK_PORT`` macro to +assign a devlink port instance to the netdevice before registering the +netdevice; the kernel uses the devlink port to provide the ``phys_switch_id`` +and ``phys_port_name`` sysfs nodes. +(Some legacy drivers implement ``ndo_get_port_parent_id()`` and ``ndo_get_phys_port_name()`` directly, but this is deprecated.) See :ref:`Documentation/networking/devlink/devlink-port.rst <devlink_port>` for the details of this API. diff --git a/Documentation/networking/scaling.rst b/Documentation/networking/scaling.rst index 92c9fb46d6a2..03ae19a689fc 100644 --- a/Documentation/networking/scaling.rst +++ b/Documentation/networking/scaling.rst @@ -105,6 +105,48 @@ a separate CPU. For interrupt handling, HT has shown no benefit in initial tests, so limit the number of queues to the number of CPU cores in the system. +Dedicated RSS contexts +~~~~~~~~~~~~~~~~~~~~~~ + +Modern NICs support creating multiple co-existing RSS configurations +which are selected based on explicit matching rules. This can be very +useful when application wants to constrain the set of queues receiving +traffic for e.g. a particular destination port or IP address. +The example below shows how to direct all traffic to TCP port 22 +to queues 0 and 1. + +To create an additional RSS context use:: + + # ethtool -X eth0 hfunc toeplitz context new + New RSS context is 1 + +Kernel reports back the ID of the allocated context (the default, always +present RSS context has ID of 0). The new context can be queried and +modified using the same APIs as the default context:: + + # ethtool -x eth0 context 1 + RX flow hash indirection table for eth0 with 13 RX ring(s): + 0: 0 1 2 3 4 5 6 7 + 8: 8 9 10 11 12 0 1 2 + [...] + # ethtool -X eth0 equal 2 context 1 + # ethtool -x eth0 context 1 + RX flow hash indirection table for eth0 with 13 RX ring(s): + 0: 0 1 0 1 0 1 0 1 + 8: 0 1 0 1 0 1 0 1 + [...] + +To make use of the new context direct traffic to it using an n-tuple +filter:: + + # ethtool -N eth0 flow-type tcp6 dst-port 22 context 1 + Added rule with ID 1023 + +When done, remove the context and the rule:: + + # ethtool -N eth0 delete 1023 + # ethtool -X eth0 context 1 delete + RPS: Receive Packet Steering ============================ diff --git a/Documentation/networking/sfp-phylink.rst b/Documentation/networking/sfp-phylink.rst index 55b65f607a64..8054d33f449f 100644 --- a/Documentation/networking/sfp-phylink.rst +++ b/Documentation/networking/sfp-phylink.rst @@ -200,10 +200,12 @@ this documentation. when the in-band link state changes - otherwise the link will never come up. - The :c:func:`validate` method should mask the supplied supported mask, - and ``state->advertising`` with the supported ethtool link modes. - These are the new ethtool link modes, so bitmask operations must be - used. For an example, see ``drivers/net/ethernet/marvell/mvneta.c``. + The :c:func:`mac_get_caps` method is optional, and if provided should + return the phylink MAC capabilities that are supported for the passed + ``interface`` mode. In general, there is no need to implement this method. + Phylink will use these capabilities in combination with permissible + capabilities for ``interface`` to determine the allowable ethtool link + modes. The :c:func:`mac_link_state` method is used to read the link state from the MAC, and report back the settings that the MAC is currently diff --git a/Documentation/networking/tcp_ao.rst b/Documentation/networking/tcp_ao.rst new file mode 100644 index 000000000000..cfa5bf1cc542 --- /dev/null +++ b/Documentation/networking/tcp_ao.rst @@ -0,0 +1,444 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================================== +TCP Authentication Option Linux implementation (RFC5925) +======================================================== + +TCP Authentication Option (TCP-AO) provides a TCP extension aimed at verifying +segments between trusted peers. It adds a new TCP header option with +a Message Authentication Code (MAC). MACs are produced from the content +of a TCP segment using a hashing function with a password known to both peers. +The intent of TCP-AO is to deprecate TCP-MD5 providing better security, +key rotation and support for variety of hashing algorithms. + +1. Introduction +=============== + +.. table:: Short and Limited Comparison of TCP-AO and TCP-MD5 + + +----------------------+------------------------+-----------------------+ + | | TCP-MD5 | TCP-AO | + +======================+========================+=======================+ + |Supported hashing |MD5 |Must support HMAC-SHA1 | + |algorithms |(cryptographically weak)|(chosen-prefix attacks)| + | | |and CMAC-AES-128 (only | + | | |side-channel attacks). | + | | |May support any hashing| + | | |algorithm. | + +----------------------+------------------------+-----------------------+ + |Length of MACs (bytes)|16 |Typically 12-16. | + | | |Other variants that fit| + | | |TCP header permitted. | + +----------------------+------------------------+-----------------------+ + |Number of keys per |1 |Many | + |TCP connection | | | + +----------------------+------------------------+-----------------------+ + |Possibility to change |Non-practical (both |Supported by protocol | + |an active key |peers have to change | | + | |them during MSL) | | + +----------------------+------------------------+-----------------------+ + |Protection against |No |Yes: ignoring them | + |ICMP 'hard errors' | |by default on | + | | |established connections| + +----------------------+------------------------+-----------------------+ + |Protection against |No |Yes: pseudo-header | + |traffic-crossing | |includes TCP ports. | + |attack | | | + +----------------------+------------------------+-----------------------+ + |Protection against |No |Sequence Number | + |replayed TCP segments | |Extension (SNE) and | + | | |Initial Sequence | + | | |Numbers (ISNs) | + +----------------------+------------------------+-----------------------+ + |Supports |Yes |No. ISNs+SNE are needed| + |Connectionless Resets | |to correctly sign RST. | + +----------------------+------------------------+-----------------------+ + |Standards |RFC 2385 |RFC 5925, RFC 5926 | + +----------------------+------------------------+-----------------------+ + + +1.1 Frequently Asked Questions (FAQ) with references to RFC 5925 +---------------------------------------------------------------- + +Q: Can either SendID or RecvID be non-unique for the same 4-tuple +(srcaddr, srcport, dstaddr, dstport)? + +A: No [3.1]:: + + >> The IDs of MKTs MUST NOT overlap where their TCP connection + identifiers overlap. + +Q: Can Master Key Tuple (MKT) for an active connection be removed? + +A: No, unless it's copied to Transport Control Block (TCB) [3.1]:: + + It is presumed that an MKT affecting a particular connection cannot + be destroyed during an active connection -- or, equivalently, that + its parameters are copied to an area local to the connection (i.e., + instantiated) and so changes would affect only new connections. + +Q: If an old MKT needs to be deleted, how should it be done in order +to not remove it for an active connection? (As it can be still in use +at any moment later) + +A: Not specified by RFC 5925, seems to be a problem for key management +to ensure that no one uses such MKT before trying to remove it. + +Q: Can an old MKT exist forever and be used by another peer? + +A: It can, it's a key management task to decide when to remove an old key [6.1]:: + + Deciding when to start using a key is a performance issue. Deciding + when to remove an MKT is a security issue. Invalid MKTs are expected + to be removed. TCP-AO provides no mechanism to coordinate their removal, + as we consider this a key management operation. + +also [6.1]:: + + The only way to avoid reuse of previously used MKTs is to remove the MKT + when it is no longer considered permitted. + +Linux TCP-AO will try its best to prevent you from removing a key that's +being used, considering it a key management failure. But sine keeping +an outdated key may become a security issue and as a peer may +unintentionally prevent the removal of an old key by always setting +it as RNextKeyID - a forced key removal mechanism is provided, where +userspace has to supply KeyID to use instead of the one that's being removed +and the kernel will atomically delete the old key, even if the peer is +still requesting it. There are no guarantees for force-delete as the peer +may yet not have the new key - the TCP connection may just break. +Alternatively, one may choose to shut down the socket. + +Q: What happens when a packet is received on a new connection with no known +MKT's RecvID? + +A: RFC 5925 specifies that by default it is accepted with a warning logged, but +the behaviour can be configured by the user [7.5.1.a]:: + + If the segment is a SYN, then this is the first segment of a new + connection. Find the matching MKT for this segment, using the segment's + socket pair and its TCP-AO KeyID, matched against the MKT's TCP connection + identifier and the MKT's RecvID. + + i. If there is no matching MKT, remove TCP-AO from the segment. + Proceed with further TCP handling of the segment. + NOTE: this presumes that connections that do not match any MKT + should be silently accepted, as noted in Section 7.3. + +[7.3]:: + + >> A TCP-AO implementation MUST allow for configuration of the behavior + of segments with TCP-AO but that do not match an MKT. The initial default + of this configuration SHOULD be to silently accept such connections. + If this is not the desired case, an MKT can be included to match such + connections, or the connection can indicate that TCP-AO is required. + Alternately, the configuration can be changed to discard segments with + the AO option not matching an MKT. + +[10.2.b]:: + + Connections not matching any MKT do not require TCP-AO. Further, incoming + segments with TCP-AO are not discarded solely because they include + the option, provided they do not match any MKT. + +Note that Linux TCP-AO implementation differs in this aspect. Currently, TCP-AO +segments with unknown key signatures are discarded with warnings logged. + +Q: Does the RFC imply centralized kernel key management in any way? +(i.e. that a key on all connections MUST be rotated at the same time?) + +A: Not specified. MKTs can be managed in userspace, the only relevant part to +key changes is [7.3]:: + + >> All TCP segments MUST be checked against the set of MKTs for matching + TCP connection identifiers. + +Q: What happens when RNextKeyID requested by a peer is unknown? Should +the connection be reset? + +A: It should not, no action needs to be performed [7.5.2.e]:: + + ii. If they differ, determine whether the RNextKeyID MKT is ready. + + 1. If the MKT corresponding to the segment’s socket pair and RNextKeyID + is not available, no action is required (RNextKeyID of a received + segment needs to match the MKT’s SendID). + +Q: How current_key is set and when does it change? It is a user-triggered +change, or is it by a request from the remote peer? Is it set by the user +explicitly, or by a matching rule? + +A: current_key is set by RNextKeyID [6.1]:: + + Rnext_key is changed only by manual user intervention or MKT management + protocol operation. It is not manipulated by TCP-AO. Current_key is updated + by TCP-AO when processing received TCP segments as discussed in the segment + processing description in Section 7.5. Note that the algorithm allows + the current_key to change to a new MKT, then change back to a previously + used MKT (known as "backing up"). This can occur during an MKT change when + segments are received out of order, and is considered a feature of TCP-AO, + because reordering does not result in drops. + +[7.5.2.e.ii]:: + + 2. If the matching MKT corresponding to the segment’s socket pair and + RNextKeyID is available: + + a. Set current_key to the RNextKeyID MKT. + +Q: If both peers have multiple MKTs matching the connection's socket pair +(with different KeyIDs), how should the sender/receiver pick KeyID to use? + +A: Some mechanism should pick the "desired" MKT [3.3]:: + + Multiple MKTs may match a single outgoing segment, e.g., when MKTs + are being changed. Those MKTs cannot have conflicting IDs (as noted + elsewhere), and some mechanism must determine which MKT to use for each + given outgoing segment. + + >> An outgoing TCP segment MUST match at most one desired MKT, indicated + by the segment’s socket pair. The segment MAY match multiple MKTs, provided + that exactly one MKT is indicated as desired. Other information in + the segment MAY be used to determine the desired MKT when multiple MKTs + match; such information MUST NOT include values in any TCP option fields. + +Q: Can TCP-MD5 connection migrate to TCP-AO (and vice-versa): + +A: No [1]:: + + TCP MD5-protected connections cannot be migrated to TCP-AO because TCP MD5 + does not support any changes to a connection’s security algorithm + once established. + +Q: If all MKTs are removed on a connection, can it become a non-TCP-AO signed +connection? + +A: [7.5.2] doesn't have the same choice as SYN packet handling in [7.5.1.i] +that would allow accepting segments without a sign (which would be insecure). +While switching to non-TCP-AO connection is not prohibited directly, it seems +what the RFC means. Also, there's a requirement for TCP-AO connections to +always have one current_key [3.3]:: + + TCP-AO requires that every protected TCP segment match exactly one MKT. + +[3.3]:: + + >> An incoming TCP segment including TCP-AO MUST match exactly one MKT, + indicated solely by the segment’s socket pair and its TCP-AO KeyID. + +[4.4]:: + + One or more MKTs. These are the MKTs that match this connection’s + socket pair. + +Q: Can a non-TCP-AO connection become a TCP-AO-enabled one? + +A: No: for already established non-TCP-AO connection it would be impossible +to switch using TCP-AO as the traffic key generation requires the initial +sequence numbers. Paraphrasing, starting using TCP-AO would require +re-establishing the TCP connection. + +2. In-kernel MKTs database vs database in userspace +=================================================== + +Linux TCP-AO support is implemented using ``setsockopt()s``, in a similar way +to TCP-MD5. It means that a userspace application that wants to use TCP-AO +should perform ``setsockopt()`` on a TCP socket when it wants to add, +remove or rotate MKTs. This approach moves the key management responsibility +to userspace as well as decisions on corner cases, i.e. what to do if +the peer doesn't respect RNextKeyID; moving more code to userspace, especially +responsible for the policy decisions. Besides, it's flexible and scales well +(with less locking needed than in the case of an in-kernel database). One also +should keep in mind that mainly intended users are BGP processes, not any +random applications, which means that compared to IPsec tunnels, +no transparency is really needed and modern BGP daemons already have +``setsockopt()s`` for TCP-MD5 support. + +.. table:: Considered pros and cons of the approaches + + +----------------------+------------------------+-----------------------+ + | | ``setsockopt()`` | in-kernel DB | + +======================+========================+=======================+ + | Extendability | ``setsockopt()`` | Netlink messages are | + | | commands should be | simple and extendable | + | | extendable syscalls | | + +----------------------+------------------------+-----------------------+ + | Required userspace | BGP or any application | could be transparent | + | changes | that wants TCP-AO needs| as tunnels, providing | + | | to perform | something like | + | | ``setsockopt()s`` | ``ip tcpao add key`` | + | | and do key management | (delete/show/rotate) | + +----------------------+------------------------+-----------------------+ + |MKTs removal or adding| harder for userspace | harder for kernel | + +----------------------+------------------------+-----------------------+ + | Dump-ability | ``getsockopt()`` | Netlink .dump() | + | | | callback | + +----------------------+------------------------+-----------------------+ + | Limits on kernel | equal | + | resources/memory | | + +----------------------+------------------------+-----------------------+ + | Scalability | contention on | contention on | + | | ``TCP_LISTEN`` sockets | the whole database | + +----------------------+------------------------+-----------------------+ + | Monitoring & warnings| ``TCP_DIAG`` | same Netlink socket | + +----------------------+------------------------+-----------------------+ + | Matching of MKTs | half-problem: only | hard | + | | listen sockets | | + +----------------------+------------------------+-----------------------+ + + +3. uAPI +======= + +Linux provides a set of ``setsockopt()s`` and ``getsockopt()s`` that let +userspace manage TCP-AO on a per-socket basis. In order to add/delete MKTs +``TCP_AO_ADD_KEY`` and ``TCP_AO_DEL_KEY`` TCP socket options must be used +It is not allowed to add a key on an established non-TCP-AO connection +as well as to remove the last key from TCP-AO connection. + +``setsockopt(TCP_AO_DEL_KEY)`` command may specify ``tcp_ao_del::current_key`` ++ ``tcp_ao_del::set_current`` and/or ``tcp_ao_del::rnext`` ++ ``tcp_ao_del::set_rnext`` which makes such delete "forced": it +provides userspace a way to delete a key that's being used and atomically set +another one instead. This is not intended for normal use and should be used +only when the peer ignores RNextKeyID and keeps requesting/using an old key. +It provides a way to force-delete a key that's not trusted but may break +the TCP-AO connection. + +The usual/normal key-rotation can be performed with ``setsockopt(TCP_AO_INFO)``. +It also provides a uAPI to change per-socket TCP-AO settings, such as +ignoring ICMPs, as well as clear per-socket TCP-AO packet counters. +The corresponding ``getsockopt(TCP_AO_INFO)`` can be used to get those +per-socket TCP-AO settings. + +Another useful command is ``getsockopt(TCP_AO_GET_KEYS)``. One can use it +to list all MKTs on a TCP socket or use a filter to get keys for a specific +peer and/or sndid/rcvid, VRF L3 interface or get current_key/rnext_key. + +To repair TCP-AO connections ``setsockopt(TCP_AO_REPAIR)`` is available, +provided that the user previously has checkpointed/dumped the socket with +``getsockopt(TCP_AO_REPAIR)``. + +A tip here for scaled TCP_LISTEN sockets, that may have some thousands TCP-AO +keys, is: use filters in ``getsockopt(TCP_AO_GET_KEYS)`` and asynchronous +delete with ``setsockopt(TCP_AO_DEL_KEY)``. + +Linux TCP-AO also provides a bunch of segment counters that can be helpful +with troubleshooting/debugging issues. Every MKT has good/bad counters +that reflect how many packets passed/failed verification. +Each TCP-AO socket has the following counters: +- for good segments (properly signed) +- for bad segments (failed TCP-AO verification) +- for segments with unknown keys +- for segments where an AO signature was expected, but wasn't found +- for the number of ignored ICMPs + +TCP-AO per-socket counters are also duplicated with per-netns counters, +exposed with SNMP. Those are ``TCPAOGood``, ``TCPAOBad``, ``TCPAOKeyNotFound``, +``TCPAORequired`` and ``TCPAODroppedIcmps``. + +RFC 5925 very permissively specifies how TCP port matching can be done for +MKTs:: + + TCP connection identifier. A TCP socket pair, i.e., a local IP + address, a remote IP address, a TCP local port, and a TCP remote port. + Values can be partially specified using ranges (e.g., 2-30), masks + (e.g., 0xF0), wildcards (e.g., "*"), or any other suitable indication. + +Currently Linux TCP-AO implementation doesn't provide any TCP port matching. +Probably, port ranges are the most flexible for uAPI, but so far +not implemented. + +4. ``setsockopt()`` vs ``accept()`` race +======================================== + +In contrast with TCP-MD5 established connection which has just one key, +TCP-AO connections may have many keys, which means that accepted connections +on a listen socket may have any amount of keys as well. As copying all those +keys on a first properly signed SYN would make the request socket bigger, that +would be undesirable. Currently, the implementation doesn't copy keys +to request sockets, but rather look them up on the "parent" listener socket. + +The result is that when userspace removes TCP-AO keys, that may break +not-yet-established connections on request sockets as well as not removing +keys from sockets that were already established, but not yet ``accept()``'ed, +hanging in the accept queue. + +The reverse is valid as well: if userspace adds a new key for a peer on +a listener socket, the established sockets in accept queue won't +have the new keys. + +At this moment, the resolution for the two races: +``setsockopt(TCP_AO_ADD_KEY)`` vs ``accept()`` +and ``setsockopt(TCP_AO_DEL_KEY)`` vs ``accept()`` is delegated to userspace. +This means that it's expected that userspace would check the MKTs on the socket +that was returned by ``accept()`` to verify that any key rotation that +happened on listen socket is reflected on the newly established connection. + +This is a similar "do-nothing" approach to TCP-MD5 from the kernel side and +may be changed later by introducing new flags to ``tcp_ao_add`` +and ``tcp_ao_del``. + +Note that this race is rare for it needs TCP-AO key rotation to happen +during the 3-way handshake for the new TCP connection. + +5. Interaction with TCP-MD5 +=========================== + +A TCP connection can not migrate between TCP-AO and TCP-MD5 options. The +established sockets that have either AO or MD5 keys are restricted for +adding keys of the other option. + +For listening sockets the picture is different: BGP server may want to receive +both TCP-AO and (deprecated) TCP-MD5 clients. As a result, both types of keys +may be added to TCP_CLOSED or TCP_LISTEN sockets. It's not allowed to add +different types of keys for the same peer. + +6. SNE Linux implementation +=========================== + +RFC 5925 [6.2] describes the algorithm of how to extend TCP sequence numbers +with SNE. In short: TCP has to track the previous sequence numbers and set +sne_flag when the current SEQ number rolls over. The flag is cleared when +both current and previous SEQ numbers cross 0x7fff, which is 32Kb. + +In times when sne_flag is set, the algorithm compares SEQ for each packet with +0x7fff and if it's higher than 32Kb, it assumes that the packet should be +verified with SNE before the increment. As a result, there's +this [0; 32Kb] window, when packets with (SNE - 1) can be accepted. + +Linux implementation simplifies this a bit: as the network stack already tracks +the first SEQ byte that ACK is wanted for (snd_una) and the next SEQ byte that +is wanted (rcv_nxt) - that's enough information for a rough estimation +on where in the 4GB SEQ number space both sender and receiver are. +When they roll over to zero, the corresponding SNE gets incremented. + +tcp_ao_compute_sne() is called for each TCP-AO segment. It compares SEQ numbers +from the segment with snd_una or rcv_nxt and fits the result into a 2GB window around them, +detecting SEQ numbers rolling over. That simplifies the code a lot and only +requires SNE numbers to be stored on every TCP-AO socket. + +The 2GB window at first glance seems much more permissive compared to +RFC 5926. But that is only used to pick the correct SNE before/after +a rollover. It allows more TCP segment replays, but yet all regular +TCP checks in tcp_sequence() are applied on the verified segment. +So, it trades a bit more permissive acceptance of replayed/retransmitted +segments for the simplicity of the algorithm and what seems better behaviour +for large TCP windows. + +7. Links +======== + +RFC 5925 The TCP Authentication Option + https://www.rfc-editor.org/rfc/pdfrfc/rfc5925.txt.pdf + +RFC 5926 Cryptographic Algorithms for the TCP Authentication Option (TCP-AO) + https://www.rfc-editor.org/rfc/pdfrfc/rfc5926.txt.pdf + +Draft "SHA-2 Algorithm for the TCP Authentication Option (TCP-AO)" + https://datatracker.ietf.org/doc/html/draft-nayak-tcp-sha2-03 + +RFC 2385 Protection of BGP Sessions via the TCP MD5 Signature Option + https://www.rfc-editor.org/rfc/pdfrfc/rfc2385.txt.pdf + +:Author: Dmitry Safonov <dima@arista.com> diff --git a/Documentation/networking/xdp-rx-metadata.rst b/Documentation/networking/xdp-rx-metadata.rst index 25ce72af81c2..205696780b78 100644 --- a/Documentation/networking/xdp-rx-metadata.rst +++ b/Documentation/networking/xdp-rx-metadata.rst @@ -105,6 +105,13 @@ bpf_tail_call Adding programs that access metadata kfuncs to the ``BPF_MAP_TYPE_PROG_ARRAY`` is currently not supported. +Supported Devices +================= + +It is possible to query which kfunc the particular netdev implements via +netlink. See ``xdp-rx-metadata-features`` attribute set in +``Documentation/netlink/specs/netdev.yaml``. + Example ======= diff --git a/Documentation/networking/xfrm_device.rst b/Documentation/networking/xfrm_device.rst index 83abdfef4ec3..535077cbeb07 100644 --- a/Documentation/networking/xfrm_device.rst +++ b/Documentation/networking/xfrm_device.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 +.. _xfrm_device: =============================================== XFRM device - offloading the IPsec computations diff --git a/Documentation/power/energy-model.rst b/Documentation/power/energy-model.rst index ef341be2882b..13225965c9a4 100644 --- a/Documentation/power/energy-model.rst +++ b/Documentation/power/energy-model.rst @@ -87,9 +87,9 @@ CONFIG_ENERGY_MODEL must be enabled to use the EM framework. Registration of 'advanced' EM ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'advanced' EM gets it's name due to the fact that the driver is allowed +The 'advanced' EM gets its name due to the fact that the driver is allowed to provide more precised power model. It's not limited to some implemented math -formula in the framework (like it's in 'simple' EM case). It can better reflect +formula in the framework (like it is in 'simple' EM case). It can better reflect the real power measurements performed for each performance state. Thus, this registration method should be preferred in case considering EM static power (leakage) is important. diff --git a/Documentation/process/7.AdvancedTopics.rst b/Documentation/process/7.AdvancedTopics.rst index bf7cbfb4caa5..43291704338e 100644 --- a/Documentation/process/7.AdvancedTopics.rst +++ b/Documentation/process/7.AdvancedTopics.rst @@ -146,6 +146,7 @@ pull. The git request-pull command can be helpful in this regard; it will format the request as other developers expect, and will also check to be sure that you have remembered to push those changes to the public server. +.. _development_advancedtopics_reviews: Reviewing patches ----------------- @@ -167,6 +168,12 @@ comments as questions rather than criticisms. Asking "how does the lock get released in this path?" will always work better than stating "the locking here is wrong." +Another technique that is useful in case of a disagreement is to ask for others +to chime in. If a discussion reaches a stalemate after a few exchanges, +then call for opinions of other reviewers or maintainers. Often those in +agreement with a reviewer remain silent unless called upon. +The opinion of multiple people carries exponentially more weight. + Different developers will review code from different points of view. Some are mostly concerned with coding style and whether code lines have trailing white space. Others will focus primarily on whether the change implemented @@ -176,3 +183,14 @@ security issues, duplication of code found elsewhere, adequate documentation, adverse effects on performance, user-space ABI changes, etc. All types of review, if they lead to better code going into the kernel, are welcome and worthwhile. + +There is no strict requirement to use specific tags like ``Reviewed-by``. +In fact reviews in plain English are more informative and encouraged +even when a tag is provided, e.g. "I looked at aspects A, B and C of this +submission and it looks good to me." +Some form of a review message or reply is obviously necessary otherwise +maintainers will not know that the reviewer has looked at the patch at all! + +Last but not least patch review may become a negative process, focused +on pointing out problems. Please throw in a compliment once in a while, +particularly for newbies! diff --git a/Documentation/process/backporting.rst b/Documentation/process/backporting.rst new file mode 100644 index 000000000000..e1a6ea0a1e8a --- /dev/null +++ b/Documentation/process/backporting.rst @@ -0,0 +1,604 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== +Backporting and conflict resolution +=================================== + +:Author: Vegard Nossum <vegard.nossum@oracle.com> + +.. contents:: + :local: + :depth: 3 + :backlinks: none + +Introduction +============ + +Some developers may never really have to deal with backporting patches, +merging branches, or resolving conflicts in their day-to-day work, so +when a merge conflict does pop up, it can be daunting. Luckily, +resolving conflicts is a skill like any other, and there are many useful +techniques you can use to make the process smoother and increase your +confidence in the result. + +This document aims to be a comprehensive, step-by-step guide to +backporting and conflict resolution. + +Applying the patch to a tree +============================ + +Sometimes the patch you are backporting already exists as a git commit, +in which case you just cherry-pick it directly using +``git cherry-pick``. However, if the patch comes from an email, as it +often does for the Linux kernel, you will need to apply it to a tree +using ``git am``. + +If you've ever used ``git am``, you probably already know that it is +quite picky about the patch applying perfectly to your source tree. In +fact, you've probably had nightmares about ``.rej`` files and trying to +edit the patch to make it apply. + +It is strongly recommended to instead find an appropriate base version +where the patch applies cleanly and *then* cherry-pick it over to your +destination tree, as this will make git output conflict markers and let +you resolve conflicts with the help of git and any other conflict +resolution tools you might prefer to use. For example, if you want to +apply a patch that just arrived on LKML to an older stable kernel, you +can apply it to the most recent mainline kernel and then cherry-pick it +to your older stable branch. + +It's generally better to use the exact same base as the one the patch +was generated from, but it doesn't really matter that much as long as it +applies cleanly and isn't too far from the original base. The only +problem with applying the patch to the "wrong" base is that it may pull +in more unrelated changes in the context of the diff when cherry-picking +it to the older branch. + +A good reason to prefer ``git cherry-pick`` over ``git am`` is that git +knows the precise history of an existing commit, so it will know when +code has moved around and changed the line numbers; this in turn makes +it less likely to apply the patch to the wrong place (which can result +in silent mistakes or messy conflicts). + +If you are using `b4`_. and you are applying the patch directly from an +email, you can use ``b4 am`` with the options ``-g``/``--guess-base`` +and ``-3``/``--prep-3way`` to do some of this automatically (see the +`b4 presentation`_ for more information). However, the rest of this +article will assume that you are doing a plain ``git cherry-pick``. + +.. _b4: https://people.kernel.org/monsieuricon/introducing-b4-and-patch-attestation +.. _b4 presentation: https://youtu.be/mF10hgVIx9o?t=2996 + +Once you have the patch in git, you can go ahead and cherry-pick it into +your source tree. Don't forget to cherry-pick with ``-x`` if you want a +written record of where the patch came from! + +Note that if you are submiting a patch for stable, the format is +slightly different; the first line after the subject line needs tobe +either:: + + commit <upstream commit> upstream + +or:: + + [ Upstream commit <upstream commit> ] + +Resolving conflicts +=================== + +Uh-oh; the cherry-pick failed with a vaguely threatening message:: + + CONFLICT (content): Merge conflict + +What to do now? + +In general, conflicts appear when the context of the patch (i.e., the +lines being changed and/or the lines surrounding the changes) doesn't +match what's in the tree you are trying to apply the patch *to*. + +For backports, what likely happened was that the branch you are +backporting from contains patches not in the branch you are backporting +to. However, the reverse is also possible. In any case, the result is a +conflict that needs to be resolved. + +If your attempted cherry-pick fails with a conflict, git automatically +edits the files to include so-called conflict markers showing you where +the conflict is and how the two branches have diverged. Resolving the +conflict typically means editing the end result in such a way that it +takes into account these other commits. + +Resolving the conflict can be done either by hand in a regular text +editor or using a dedicated conflict resolution tool. + +Many people prefer to use their regular text editor and edit the +conflict directly, as it may be easier to understand what you're doing +and to control the final result. There are definitely pros and cons to +each method, and sometimes there's value in using both. + +We will not cover using dedicated merge tools here beyond providing some +pointers to various tools that you could use: + +- `Emacs Ediff mode <https://www.emacswiki.org/emacs/EdiffMode>`__ +- `vimdiff/gvimdiff <https://linux.die.net/man/1/vimdiff>`__ +- `KDiff3 <http://kdiff3.sourceforge.net/>`__ +- `TortoiseMerge <https://tortoisesvn.net/TortoiseMerge.html>`__ +- `Meld <https://meldmerge.org/help/>`__ +- `P4Merge <https://www.perforce.com/products/helix-core-apps/merge-diff-tool-p4merge>`__ +- `Beyond Compare <https://www.scootersoftware.com/>`__ +- `IntelliJ <https://www.jetbrains.com/help/idea/resolve-conflicts.html>`__ +- `VSCode <https://code.visualstudio.com/docs/editor/versioncontrol>`__ + +To configure git to work with these, see ``git mergetool --help`` or +the official `git-mergetool documentation`_. + +.. _git-mergetool documentation: https://git-scm.com/docs/git-mergetool + +Prerequisite patches +-------------------- + +Most conflicts happen because the branch you are backporting to is +missing some patches compared to the branch you are backporting *from*. +In the more general case (such as merging two independent branches), +development could have happened on either branch, or the branches have +simply diverged -- perhaps your older branch had some other backports +applied to it that themselves needed conflict resolutions, causing a +divergence. + +It's important to always identify the commit or commits that caused the +conflict, as otherwise you cannot be confident in the correctness of +your resolution. As an added bonus, especially if the patch is in an +area you're not that famliar with, the changelogs of these commits will +often give you the context to understand the code and potential problems +or pitfalls with your conflict resolution. + +git log +~~~~~~~ + +A good first step is to look at ``git log`` for the file that has the +conflict -- this is usually sufficient when there aren't a lot of +patches to the file, but may get confusing if the file is big and +frequently patched. You should run ``git log`` on the range of commits +between your currently checked-out branch (``HEAD``) and the parent of +the patch you are picking (``<commit>``), i.e.:: + + git log HEAD..<commit>^ -- <path> + +Even better, if you want to restrict this output to a single function +(because that's where the conflict appears), you can use the following +syntax:: + + git log -L:'\<function\>':<path> HEAD..<commit>^ + +.. note:: + The ``\<`` and ``\>`` around the function name ensure that the + matches are anchored on a word boundary. This is important, as this + part is actually a regex and git only follows the first match, so + if you use ``-L:thread_stack:kernel/fork.c`` it may only give you + results for the function ``try_release_thread_stack_to_cache`` even + though there are many other functions in that file containing the + string ``thread_stack`` in their names. + +Another useful option for ``git log`` is ``-G``, which allows you to +filter on certain strings appearing in the diffs of the commits you are +listing:: + + git log -G'regex' HEAD..<commit>^ -- <path> + +This can also be a handy way to quickly find when something (e.g. a +function call or a variable) was changed, added, or removed. The search +string is a regular expression, which means you can potentially search +for more specific things like assignments to a specific struct member:: + + git log -G'\->index\>.*=' + +git blame +~~~~~~~~~ + +Another way to find prerequisite commits (albeit only the most recent +one for a given conflict) is to run ``git blame``. In this case, you +need to run it against the parent commit of the patch you are +cherry-picking and the file where the conflict appared, i.e.:: + + git blame <commit>^ -- <path> + +This command also accepts the ``-L`` argument (for restricting the +output to a single function), but in this case you specify the filename +at the end of the command as usual:: + + git blame -L:'\<function\>' <commit>^ -- <path> + +Navigate to the place where the conflict occurred. The first column of +the blame output is the commit ID of the patch that added a given line +of code. + +It might be a good idea to ``git show`` these commits and see if they +look like they might be the source of the conflict. Sometimes there will +be more than one of these commits, either because multiple commits +changed different lines of the same conflict area *or* because multiple +subsequent patches changed the same line (or lines) multiple times. In +the latter case, you may have to run ``git blame`` again and specify the +older version of the file to look at in order to dig further back in +the history of the file. + +Prerequisite vs. incidental patches +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Having found the patch that caused the conflict, you need to determine +whether it is a prerequisite for the patch you are backporting or +whether it is just incidental and can be skipped. An incidental patch +would be one that touches the same code as the patch you are +backporting, but does not change the semantics of the code in any +material way. For example, a whitespace cleanup patch is completely +incidental -- likewise, a patch that simply renames a function or a +variable would be incidental as well. On the other hand, if the function +being changed does not even exist in your current branch then this would +not be incidental at all and you need to carefully consider whether the +patch adding the function should be cherry-picked first. + +If you find that there is a necessary prerequisite patch, then you need +to stop and cherry-pick that instead. If you've already resolved some +conflicts in a different file and don't want to do it again, you can +create a temporary copy of that file. + +To abort the current cherry-pick, go ahead and run +``git cherry-pick --abort``, then restart the cherry-picking process +with the commit ID of the prerequisite patch instead. + +Understanding conflict markers +------------------------------ + +Combined diffs +~~~~~~~~~~~~~~ + +Let's say you've decided against picking (or reverting) additional +patches and you just want to resolve the conflict. Git will have +inserted conflict markers into your file. Out of the box, this will look +something like:: + + <<<<<<< HEAD + this is what's in your current tree before cherry-picking + ======= + this is what the patch wants it to be after cherry-picking + >>>>>>> <commit>... title + +This is what you would see if you opened the file in your editor. +However, if you were to run ``git diff`` without any arguments, the +output would look something like this:: + + $ git diff + [...] + ++<<<<<<<< HEAD + +this is what's in your current tree before cherry-picking + ++======== + + this is what the patch wants it to be after cherry-picking + ++>>>>>>>> <commit>... title + +When you are resolving a conflict, the behavior of ``git diff`` differs +from its normal behavior. Notice the two columns of diff markers +instead of the usual one; this is a so-called "`combined diff`_", here +showing the 3-way diff (or diff-of-diffs) between + +#. the current branch (before cherry-picking) and the current working + directory, and +#. the current branch (before cherry-picking) and the file as it looks + after the original patch has been applied. + +.. _combined diff: https://git-scm.com/docs/diff-format#_combined_diff_format + + +Better diffs +~~~~~~~~~~~~ + +3-way combined diffs include all the other changes that happened to the +file between your current branch and the branch you are cherry-picking +from. While this is useful for spotting other changes that you need to +take into account, this also makes the output of ``git diff`` somewhat +intimidating and difficult to read. You may instead prefer to run +``git diff HEAD`` (or ``git diff --ours``) which shows only the diff +between the current branch before cherry-picking and the current working +directory. It looks like this:: + + $ git diff HEAD + [...] + +<<<<<<<< HEAD + this is what's in your current tree before cherry-picking + +======== + +this is what the patch wants it to be after cherry-picking + +>>>>>>>> <commit>... title + +As you can see, this reads just like any other diff and makes it clear +which lines are in the current branch and which lines are being added +because they are part of the merge conflict or the patch being +cherry-picked. + +Merge styles and diff3 +~~~~~~~~~~~~~~~~~~~~~~ + +The default conflict marker style shown above is known as the ``merge`` +style. There is also another style available, known as the ``diff3`` +style, which looks like this:: + + <<<<<<< HEAD + this is what is in your current tree before cherry-picking + ||||||| parent of <commit> (title) + this is what the patch expected to find there + ======= + this is what the patch wants it to be after being applied + >>>>>>> <commit> (title) + +As you can see, this has 3 parts instead of 2, and includes what git +expected to find there but didn't. It is *highly recommended* to use +this conflict style as it makes it much clearer what the patch actually +changed; i.e., it allows you to compare the before-and-after versions +of the file for the commit you are cherry-picking. This allows you to +make better decisions about how to resolve the conflict. + +To change conflict marker styles, you can use the following command:: + + git config merge.conflictStyle diff3 + +There is a third option, ``zdiff3``, introduced in `Git 2.35`_, +which has the same 3 sections as ``diff3``, but where common lines have +been trimmed off, making the conflict area smaller in some cases. + +.. _Git 2.35: https://github.blog/2022-01-24-highlights-from-git-2-35/ + +Iterating on conflict resolutions +--------------------------------- + +The first step in any conflict resolution process is to understand the +patch you are backporting. For the Linux kernel this is especially +important, since an incorrect change can lead to the whole system +crashing -- or worse, an undetected security vulnerability. + +Understanding the patch can be easy or difficult depending on the patch +itself, the changelog, and your familiarity with the code being changed. +However, a good question for every change (or every hunk of the patch) +might be: "Why is this hunk in the patch?" The answers to these +questions will inform your conflict resolution. + +Resolution process +~~~~~~~~~~~~~~~~~~ + +Sometimes the easiest thing to do is to just remove all but the first +part of the conflict, leaving the file essentially unchanged, and apply +the changes by hand. Perhaps the patch is changing a function call +argument from ``0`` to ``1`` while a conflicting change added an +entirely new (and insignificant) parameter to the end of the parameter +list; in that case, it's easy enough to change the argument from ``0`` +to ``1`` by hand and leave the rest of the arguments alone. This +technique of manually applying changes is mostly useful if the conflict +pulled in a lot of unrelated context that you don't really need to care +about. + +For particularly nasty conflicts with many conflict markers, you can use +``git add`` or ``git add -i`` to selectively stage your resolutions to +get them out of the way; this also lets you use ``git diff HEAD`` to +always see what remains to be resolved or ``git diff --cached`` to see +what your patch looks like so far. + +Dealing with file renames +~~~~~~~~~~~~~~~~~~~~~~~~~ + +One of the most annoying things that can happen while backporting a +patch is discovering that one of the files being patched has been +renamed, as that typically means git won't even put in conflict markers, +but will just throw up its hands and say (paraphrased): "Unmerged path! +You do the work..." + +There are generally a few ways to deal with this. If the patch to the +renamed file is small, like a one-line change, the easiest thing is to +just go ahead and apply the change by hand and be done with it. On the +other hand, if the change is big or complicated, you definitely don't +want to do it by hand. + +As a first pass, you can try something like this, which will lower the +rename detection threshold to 30% (by default, git uses 50%, meaning +that two files need to have at least 50% in common for it to consider +an add-delete pair to be a potential rename):: + + git cherry-pick -strategy=recursive -Xrename-threshold=30 + +Sometimes the right thing to do will be to also backport the patch that +did the rename, but that's definitely not the most common case. Instead, +what you can do is to temporarily rename the file in the branch you're +backporting to (using ``git mv`` and committing the result), restart the +attempt to cherry-pick the patch, rename the file back (``git mv`` and +committing again), and finally squash the result using ``git rebase -i`` +(see the `rebase tutorial`_) so it appears as a single commit when you +are done. + +.. _rebase tutorial: https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec + +Gotchas +------- + +Function arguments +~~~~~~~~~~~~~~~~~~ + +Pay attention to changing function arguments! It's easy to gloss over +details and think that two lines are the same but actually they differ +in some small detail like which variable was passed as an argument +(especially if the two variables are both a single character that look +the same, like i and j). + +Error handling +~~~~~~~~~~~~~~ + +If you cherry-pick a patch that includes a ``goto`` statement (typically +for error handling), it is absolutely imperative to double check that +the target label is still correct in the branch you are backporting to. +The same goes for added ``return``, ``break``, and ``continue`` +statements. + +Error handling is typically located at the bottom of the function, so it +may not be part of the conflict even though could have been changed by +other patches. + +A good way to ensure that you review the error paths is to always use +``git diff -W`` and ``git show -W`` (AKA ``--function-context``) when +inspecting your changes. For C code, this will show you the whole +function that's being changed in a patch. One of the things that often +go wrong during backports is that something else in the function changed +on either of the branches that you're backporting from or to. By +including the whole function in the diff you get more context and can +more easily spot problems that might otherwise go unnoticed. + +Refactored code +~~~~~~~~~~~~~~~ + +Something that happens quite often is that code gets refactored by +"factoring out" a common code sequence or pattern into a helper +function. When backporting patches to an area where such a refactoring +has taken place, you effectively need to do the reverse when +backporting: a patch to a single location may need to be applied to +multiple locations in the backported version. (One giveaway for this +scenario is that a function was renamed -- but that's not always the +case.) + +To avoid incomplete backports, it's worth trying to figure out if the +patch fixes a bug that appears in more than one place. One way to do +this would be to use ``git grep``. (This is actually a good idea to do +in general, not just for backports.) If you do find that the same kind +of fix would apply to other places, it's also worth seeing if those +places exist upstream -- if they don't, it's likely the patch may need +to be adjusted. ``git log`` is your friend to figure out what happened +to these areas as ``git blame`` won't show you code that has been +removed. + +If you do find other instances of the same pattern in the upstream tree +and you're not sure whether it's also a bug, it may be worth asking the +patch author. It's not uncommon to find new bugs during backporting! + +Verifying the result +==================== + +colordiff +--------- + +Having committed a conflict-free new patch, you can now compare your +patch to the original patch. It is highly recommended that you use a +tool such as `colordiff`_ that can show two files side by side and color +them according to the changes between them:: + + colordiff -yw -W 200 <(git diff -W <upstream commit>^-) <(git diff -W HEAD^-) | less -SR + +.. _colordiff: https://www.colordiff.org/ + +Here, ``-y`` means to do a side-by-side comparison; ``-w`` ignores +whitespace, and ``-W 200`` sets the width of the output (as otherwise it +will use 130 by default, which is often a bit too little). + +The ``rev^-`` syntax is a handy shorthand for ``rev^..rev``, essentially +giving you just the diff for that single commit; also see +the official `git rev-parse documentation`_. + +.. _git rev-parse documentation: https://git-scm.com/docs/git-rev-parse#_other_rev_parent_shorthand_notations + +Again, note the inclusion of ``-W`` for ``git diff``; this ensures that +you will see the full function for any function that has changed. + +One incredibly important thing that colordiff does is to highlight lines +that are different. For example, if an error-handling ``goto`` has +changed labels between the original and backported patch, colordiff will +show these side-by-side but highlighted in a different color. Thus, it +is easy to see that the two ``goto`` statements are jumping to different +labels. Likewise, lines that were not modified by either patch but +differ in the context will also be highlighted and thus stand out during +a manual inspection. + +Of course, this is just a visual inspection; the real test is building +and running the patched kernel (or program). + +Build testing +------------- + +We won't cover runtime testing here, but it can be a good idea to build +just the files touched by the patch as a quick sanity check. For the +Linux kernel you can build single files like this, assuming you have the +``.config`` and build environment set up correctly:: + + make path/to/file.o + +Note that this won't discover linker errors, so you should still do a +full build after verifying that the single file compiles. By compiling +the single file first you can avoid having to wait for a full build *in +case* there are compiler errors in any of the files you've changed. + +Runtime testing +--------------- + +Even a successful build or boot test is not necessarily enough to rule +out a missing dependency somewhere. Even though the chances are small, +there could be code changes where two independent changes to the same +file result in no conflicts, no compile-time errors, and runtime errors +only in exceptional cases. + +One concrete example of this was a pair of patches to the system call +entry code where the first patch saved/restored a register and a later +patch made use of the same register somewhere in the middle of this +sequence. Since there was no overlap between the changes, one could +cherry-pick the second patch, have no conflicts, and believe that +everything was fine, when in fact the code was now scribbling over an +unsaved register. + +Although the vast majority of errors will be caught during compilation +or by superficially exercising the code, the only way to *really* verify +a backport is to review the final patch with the same level of scrutiny +as you would (or should) give to any other patch. Having unit tests and +regression tests or other types of automatic testing can help increase +the confidence in the correctness of a backport. + +Submitting backports to stable +============================== + +As the stable maintainers try to cherry-pick mainline fixes onto their +stable kernels, they may send out emails asking for backports when when +encountering conflicts, see e.g. +<https://lore.kernel.org/stable/2023101528-jawed-shelving-071a@gregkh/>. +These emails typically include the exact steps you need to cherry-pick +the patch to the correct tree and submit the patch. + +One thing to make sure is that your changelog conforms to the expected +format:: + + <original patch title> + + [ Upstream commit <mainline rev> ] + + <rest of the original changelog> + [ <summary of the conflicts and their resolutions> ] + Signed-off-by: <your name and email> + +The "Upstream commit" line is sometimes slightly different depending on +the stable version. Older version used this format:: + + commit <mainline rev> upstream. + +It is most common to indicate the kernel version the patch applies to +in the email subject line (using e.g. +``git send-email --subject-prefix='PATCH 6.1.y'``), but you can also put +it in the Signed-off-by:-area or below the ``---`` line. + +The stable maintainers expect separate submissions for each active +stable version, and each submission should also be tested separately. + +A few final words of advice +=========================== + +1) Approach the backporting process with humility. +2) Understand the patch you are backporting; this means reading both + the changelog and the code. +3) Be honest about your confidence in the result when submitting the + patch. +4) Ask relevant maintainers for explicit acks. + +Examples +======== + +The above shows roughly the idealized process of backporting a patch. +For a more concrete example, see this video tutorial where two patches +are backported from mainline to stable: +`Backporting Linux Kernel Patches`_. + +.. _Backporting Linux Kernel Patches: https://youtu.be/sBR7R1V2FeA diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst index 9739b88463a5..a05e8401de1c 100644 --- a/Documentation/process/botching-up-ioctls.rst +++ b/Documentation/process/botching-up-ioctls.rst @@ -208,7 +208,7 @@ Not every problem needs a new ioctl: it's much quicker to push a driver-private interface than engaging in lengthy discussions for a more generic solution. And occasionally doing a private interface to spearhead a new concept is what's required. But in the - end, once the generic interface comes around you'll end up maintainer two + end, once the generic interface comes around you'll end up maintaining two interfaces. Indefinitely. * Consider other interfaces than ioctls. A sysfs attribute is much better for diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 5561dae94f85..bb96ca0f774b 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -31,8 +31,8 @@ you probably needn't concern yourself with pcmciautils. ====================== =============== ======================================== GNU C 5.1 gcc --version Clang/LLVM (optional) 11.0.0 clang --version -Rust (optional) 1.68.2 rustc --version -bindgen (optional) 0.56.0 bindgen --version +Rust (optional) 1.73.0 rustc --version +bindgen (optional) 0.65.1 bindgen --version GNU make 3.82 make --version bash 4.2 bash --version binutils 2.25 ld -v @@ -482,7 +482,7 @@ E2fsprogs JFSutils -------- -- <http://jfs.sourceforge.net/> +- <https://jfs.sourceforge.net/> Reiserfsprogs ------------- @@ -503,7 +503,7 @@ Pcmciautils Quota-tools ----------- -- <http://sourceforge.net/projects/linuxquota/> +- <https://sourceforge.net/projects/linuxquota/> Intel P6 microcode @@ -524,7 +524,7 @@ FUSE mcelog ------ -- <http://www.mcelog.org/> +- <https://www.mcelog.org/> cpio ---- @@ -544,7 +544,8 @@ PPP NFS-utils --------- -- <http://sourceforge.net/project/showfiles.php?group_id=14> +- <https://sourceforge.net/project/showfiles.php?group_id=14> +- <https://nfs.sourceforge.net/> Iptables -------- @@ -559,12 +560,7 @@ Ip-route2 OProfile -------- -- <http://oprofile.sf.net/download/> - -NFS-Utils ---------- - -- <http://nfs.sourceforge.net/> +- <https://oprofile.sf.net/download/> Kernel documentation ******************** diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index f91b8441f2ef..1f7f3e6c9cda 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -77,7 +77,7 @@ kzalloc() can be replaced with kcalloc(). If no 2-factor form is available, the saturate-on-overflow helpers should be used:: - bar = vmalloc(array_size(count, size)); + bar = dma_alloc_coherent(dev, array_size(count, size), &dma, GFP_KERNEL); Another common case to avoid is calculating the size of a structure with a trailing array of others structures, as in:: diff --git a/Documentation/process/embargoed-hardware-issues.rst b/Documentation/process/embargoed-hardware-issues.rst index df978127f2d7..31000f075707 100644 --- a/Documentation/process/embargoed-hardware-issues.rst +++ b/Documentation/process/embargoed-hardware-issues.rst @@ -25,15 +25,15 @@ Contact The Linux kernel hardware security team is separate from the regular Linux kernel security team. -The team only handles the coordination of embargoed hardware security -issues. Reports of pure software security bugs in the Linux kernel are not +The team only handles developing fixes for embargoed hardware security +issues. Reports of pure software security bugs in the Linux kernel are not handled by this team and the reporter will be guided to contact the regular Linux kernel security team (:ref:`Documentation/admin-guide/ <securitybugs>`) instead. The team can be contacted by email at <hardware-security@kernel.org>. This -is a private list of security officers who will help you to coordinate an -issue according to our documented process. +is a private list of security officers who will help you to coordinate a +fix according to our documented process. The list is encrypted and email to the list can be sent by either PGP or S/MIME encrypted and must be signed with the reporter's PGP key or S/MIME @@ -132,11 +132,11 @@ other hardware could be affected. The hardware security team will provide an incident-specific encrypted mailing-list which will be used for initial discussion with the reporter, -further disclosure and coordination. +further disclosure, and coordination of fixes. The hardware security team will provide the disclosing party a list of developers (domain experts) who should be informed initially about the -issue after confirming with the developers that they will adhere to this +issue after confirming with the developers that they will adhere to this Memorandum of Understanding and the documented process. These developers form the initial response team and will be responsible for handling the issue after initial contact. The hardware security team is supporting the @@ -209,13 +209,18 @@ five work days this is taken as silent acknowledgement. After acknowledgement or resolution of an objection the expert is disclosed by the incident team and brought into the development process. +List participants may not communicate about the issue outside of the +private mailing list. List participants may not use any shared resources +(e.g. employer build farms, CI systems, etc) when working on patches. + Coordinated release """"""""""""""""""" The involved parties will negotiate the date and time where the embargo ends. At that point the prepared mitigations are integrated into the -relevant kernel trees and published. +relevant kernel trees and published. There is no pre-notification process: +fixes are published in public and available to everyone at the same time. While we understand that hardware security issues need coordinated embargo time, the embargo time should be constrained to the minimum time which is @@ -251,10 +256,10 @@ an involved disclosed party. The current ambassadors list: IBM Z Christian Borntraeger <borntraeger@de.ibm.com> Intel Tony Luck <tony.luck@intel.com> Qualcomm Trilok Soni <tsoni@codeaurora.org> + RISC-V Palmer Dabbelt <palmer@dabbelt.com> Samsung Javier González <javier.gonz@samsung.com> Microsoft James Morris <jamorris@linux.microsoft.com> - VMware Xen Andrew Cooper <andrew.cooper3@citrix.com> Canonical John Johansen <john.johansen@canonical.com> @@ -263,10 +268,8 @@ an involved disclosed party. The current ambassadors list: Red Hat Josh Poimboeuf <jpoimboe@redhat.com> SUSE Jiri Kosina <jkosina@suse.cz> - Amazon Google Kees Cook <keescook@chromium.org> - GCC LLVM Nick Desaulniers <ndesaulniers@google.com> ============= ======================================================== diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index b501cd977053..a1daa309b58d 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -66,12 +66,13 @@ lack of a better place. :maxdepth: 1 applying-patches + backporting adding-syscalls magic-number volatile-considered-harmful botching-up-ioctls clang-format - ../riscv/patch-acceptance + ../arch/riscv/patch-acceptance ../core-api/unaligned-memory-access .. only:: subproject and html diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index 46f927aae6eb..8660493b91d0 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -29,7 +29,7 @@ All documents are cataloged with the following fields: the document's The documents on each section of this document are ordered by its published date, from the newest to the oldest. The maintainer(s) should - periodically retire resources as they become obsolte or outdated; with + periodically retire resources as they become obsolete or outdated; with the exception of foundational books. Docs at the Linux Kernel tree @@ -118,6 +118,15 @@ Published books :ISBN: 978-0672329463 :Notes: Foundational book + * Title: **Practical Linux System Administration: A Guide to Installation, Configuration, and Management, 1st Edition** + + :Author: Kenneth Hess + :Publisher: O'Reilly Media + :Date: May, 2023 + :Pages: 246 + :ISBN: 978-1098109035 + :Notes: System administration + .. _ldd3_published: * Title: **Linux Device Drivers, 3rd Edition** diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst index 9992bfd7eaa3..976391cec528 100644 --- a/Documentation/process/maintainer-handbooks.rst +++ b/Documentation/process/maintainer-handbooks.rst @@ -17,5 +17,6 @@ Contents: maintainer-netdev maintainer-soc + maintainer-soc-clean-dts maintainer-tip maintainer-kvm-x86 diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst index 2397b31c0198..7feacc20835e 100644 --- a/Documentation/process/maintainer-netdev.rst +++ b/Documentation/process/maintainer-netdev.rst @@ -98,7 +98,7 @@ If you aren't subscribed to netdev and/or are simply unsure if repository link above for any new networking-related commits. You may also check the following website for the current status: - http://vger.kernel.org/~davem/net-next.html + https://netdev.bots.linux.dev/net-next.html The ``net`` tree continues to collect fixes for the vX.Y content, and is fed back to Linus at regular (~weekly) intervals. Meaning that the @@ -120,7 +120,37 @@ queue for netdev: https://patchwork.kernel.org/project/netdevbpf/list/ The "State" field will tell you exactly where things are at with your -patch. Patches are indexed by the ``Message-ID`` header of the emails +patch: + +================== ============================================================= +Patch state Description +================== ============================================================= +New, Under review pending review, patch is in the maintainer’s queue for + review; the two states are used interchangeably (depending on + the exact co-maintainer handling patchwork at the time) +Accepted patch was applied to the appropriate networking tree, this is + usually set automatically by the pw-bot +Needs ACK waiting for an ack from an area expert or testing +Changes requested patch has not passed the review, new revision is expected + with appropriate code and commit message changes +Rejected patch has been rejected and new revision is not expected +Not applicable patch is expected to be applied outside of the networking + subsystem +Awaiting upstream patch should be reviewed and handled by appropriate + sub-maintainer, who will send it on to the networking trees; + patches set to ``Awaiting upstream`` in netdev's patchwork + will usually remain in this state, whether the sub-maintainer + requested changes, accepted or rejected the patch +Deferred patch needs to be reposted later, usually due to dependency + or because it was posted for a closed tree +Superseded new version of the patch was posted, usually set by the + pw-bot +RFC not to be applied, usually not in maintainer’s review queue, + pw-bot can automatically set patches to this state based + on subject tags +================== ============================================================= + +Patches are indexed by the ``Message-ID`` header of the emails which carried them so if you have trouble finding your patch append the value of ``Message-ID`` to the URL above. @@ -155,7 +185,7 @@ must match the MAINTAINERS entry) and a handful of senior reviewers. Bot records its activity here: - https://patchwork.hopto.org/pw-bot.html + https://netdev.bots.linux.dev/pw-bot.html Review timelines ~~~~~~~~~~~~~~~~ @@ -167,6 +197,8 @@ Asking the maintainer for status updates on your patch is a good way to ensure your patch is ignored or pushed to the bottom of the priority list. +.. _Changes requested: + Changes requested ~~~~~~~~~~~~~~~~~ @@ -359,6 +391,10 @@ Make sure you address all the feedback in your new posting. Do not post a new version of the code if the discussion about the previous version is still ongoing, unless directly instructed by a reviewer. +The new version of patches should be posted as a separate thread, +not as a reply to the previous posting. Change log should include a link +to the previous posting (see :ref:`Changes requested`). + Testing ------- @@ -405,6 +441,21 @@ in a way which would break what would normally be considered uAPI. new ``netdevsim`` features must be accompanied by selftests under ``tools/testing/selftests/``. +Reviewer guidance +----------------- + +Reviewing other people's patches on the list is highly encouraged, +regardless of the level of expertise. For general guidance and +helpful tips please see :ref:`development_advancedtopics_reviews`. + +It's safe to assume that netdev maintainers know the community and the level +of expertise of the reviewers. The reviewers should not be concerned about +their comments impeding or derailing the patch flow. + +Less experienced reviewers are highly encouraged to do more in-depth +review of submissions and not focus exclusively on trivial or subjective +matters like code formatting, tags etc. + Testimonials / feedback ----------------------- diff --git a/Documentation/process/maintainer-soc-clean-dts.rst b/Documentation/process/maintainer-soc-clean-dts.rst new file mode 100644 index 000000000000..1b32430d0cfc --- /dev/null +++ b/Documentation/process/maintainer-soc-clean-dts.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================== +SoC Platforms with DTS Compliance Requirements +============================================== + +Overview +-------- + +SoC platforms or subarchitectures should follow all the rules from +Documentation/process/maintainer-soc.rst. This document referenced in +MAINTAINERS impose additional requirements listed below. + +Strict DTS DT Schema and dtc Compliance +--------------------------------------- + +No changes to the SoC platform Devicetree sources (DTS files) should introduce +new ``make dtbs_check W=1`` warnings. Warnings in a new board DTS, which are +results of issues in an included DTSI file, are considered existing, not new +warnings. The platform maintainers have automation in place which should point +out any new warnings. + +If a commit introducing new warnings gets accepted somehow, the resulting +issues shall be fixed in reasonable time (e.g. within one release) or the +commit reverted. diff --git a/Documentation/process/maintainer-soc.rst b/Documentation/process/maintainer-soc.rst index 49f08289d62c..12637530d68f 100644 --- a/Documentation/process/maintainer-soc.rst +++ b/Documentation/process/maintainer-soc.rst @@ -133,8 +133,8 @@ with the dt-bindings that describe the ABI. Please read the section more information on the validation of devicetrees. For new platforms, or additions to existing ones, ``make dtbs_check`` should not -add any new warnings. For RISC-V, as it has the advantage of being a newer -architecture, ``make dtbs_check W=1`` is required to not add any new warnings. +add any new warnings. For RISC-V and Samsung SoC, ``make dtbs_check W=1`` is +required to not add any new warnings. If in any doubt about a devicetree change, reach out to the devicetree maintainers. diff --git a/Documentation/process/researcher-guidelines.rst b/Documentation/process/researcher-guidelines.rst index 9fcfed3c350b..d159cd4f5e5b 100644 --- a/Documentation/process/researcher-guidelines.rst +++ b/Documentation/process/researcher-guidelines.rst @@ -44,6 +44,33 @@ explicit agreement of, and full disclosure to, the individual developers involved. Developers cannot be interacted with/experimented on without consent; this, too, is standard research ethics. +Surveys +======= + +Research often takes the form of surveys sent to maintainers or +contributors. As a general rule, though, the kernel community derives +little value from these surveys. The kernel development process works +because every developer benefits from their participation, even working +with others who have different goals. Responding to a survey, though, is a +one-way demand placed on busy developers with no corresponding benefit to +themselves or to the kernel community as a whole. For this reason, this +method of research is discouraged. + +Kernel community members already receive far too much email and are likely +to perceive survey requests as just another demand on their time. Sending +such requests deprives the community of valuable contributor time and is +unlikely to yield a statistically useful response. + +As an alternative, researchers should consider attending developer events, +hosting sessions where the research project and its benefits to the +participants can be explained, and interacting directly with the community +there. The information received will be far richer than that obtained from +an email survey, and the community will gain from the ability to learn from +your insights as well. + +Patches +======= + To help clarify: sending patches to developers *is* interacting with them, but they have already consented to receiving *good faith contributions*. Sending intentionally flawed/vulnerable patches or diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst index 82e29837d589..5a6993795bd2 100644 --- a/Documentation/process/security-bugs.rst +++ b/Documentation/process/security-bugs.rst @@ -63,31 +63,28 @@ information submitted to the security list and any followup discussions of the report are treated confidentially even after the embargo has been lifted, in perpetuity. -Coordination ------------- - -Fixes for sensitive bugs, such as those that might lead to privilege -escalations, may need to be coordinated with the private -<linux-distros@vs.openwall.org> mailing list so that distribution vendors -are well prepared to issue a fixed kernel upon public disclosure of the -upstream fix. Distros will need some time to test the proposed patch and -will generally request at least a few days of embargo, and vendor update -publication prefers to happen Tuesday through Thursday. When appropriate, -the security team can assist with this coordination, or the reporter can -include linux-distros from the start. In this case, remember to prefix -the email Subject line with "[vs]" as described in the linux-distros wiki: -<http://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists> +Coordination with other groups +------------------------------ + +The kernel security team strongly recommends that reporters of potential +security issues NEVER contact the "linux-distros" mailing list until +AFTER discussing it with the kernel security team. Do not Cc: both +lists at once. You may contact the linux-distros mailing list after a +fix has been agreed on and you fully understand the requirements that +doing so will impose on you and the kernel community. + +The different lists have different goals and the linux-distros rules do +not contribute to actually fixing any potential security problems. CVE assignment -------------- -The security team does not normally 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 ahead of public disclosure, they will need to contact the private -linux-distros list, described above. When such a CVE identifier is known -before a patch is provided, it is desirable to mention it in the commit -message if the reporter agrees. +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. Non-disclosure agreements ------------------------- diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index 51df1197d5ab..41f1e07abfdf 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -6,30 +6,29 @@ Everything you ever wanted to know about Linux -stable releases Rules on what kind of patches are accepted, and which ones are not, into the "-stable" tree: + - It or an equivalent fix must already exist in Linus' tree (upstream). - It must be obviously correct and tested. - It cannot be bigger than 100 lines, with context. - - It must fix only one thing. - - It must fix a real bug that bothers people (not a, "This could be a - problem..." type thing). - - It must fix a problem that causes a build error (but not for things - marked CONFIG_BROKEN), an oops, a hang, data corruption, a real - security issue, or some "oh, that's not good" issue. In short, something - critical. - - Serious issues as reported by a user of a distribution kernel may also - be considered if they fix a notable performance or interactivity issue. - As these fixes are not as obvious and have a higher risk of a subtle - regression they should only be submitted by a distribution kernel - maintainer and include an addendum linking to a bugzilla entry if it - exists and additional information on the user-visible impact. - - New device IDs and quirks are also accepted. - - No "theoretical race condition" issues, unless an explanation of how the - race can be exploited is also provided. - - It cannot contain any "trivial" fixes in it (spelling changes, - whitespace cleanups, etc). - It must follow the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` rules. - - It or an equivalent fix must already exist in Linus' tree (upstream). + - It must either fix a real bug that bothers people or just add a device ID. + To elaborate on the former: + + - It fixes a problem like an oops, a hang, data corruption, a real security + issue, a hardware quirk, a build error (but not for things marked + CONFIG_BROKEN), or some "oh, that's not good" issue. + - Serious issues as reported by a user of a distribution kernel may also + be considered if they fix a notable performance or interactivity issue. + As these fixes are not as obvious and have a higher risk of a subtle + regression they should only be submitted by a distribution kernel + maintainer and include an addendum linking to a bugzilla entry if it + exists and additional information on the user-visible impact. + - No "This could be a problem..." type of things like a "theoretical race + condition", unless an explanation of how the bug can be exploited is also + provided. + - No "trivial" fixes without benefit for users (spelling changes, whitespace + cleanups, etc). Procedure for submitting patches to the -stable tree @@ -41,111 +40,142 @@ Procedure for submitting patches to the -stable tree process but should follow the procedures in :ref:`Documentation/process/security-bugs.rst <securitybugs>`. -For all other submissions, choose one of the following procedures ------------------------------------------------------------------ +There are three options to submit a change to -stable trees: + + 1. Add a 'stable tag' to the description of a patch you then submit for + mainline inclusion. + 2. Ask the stable team to pick up a patch already mainlined. + 3. Submit a patch to the stable team that is equivalent to a change already + mainlined. + +The sections below describe each of the options in more detail. + +:ref:`option_1` is **strongly** preferred, it is the easiest and most common. +:ref:`option_2` is mainly meant for changes where backporting was not considered +at the time of submission. :ref:`option_3` is an alternative to the two earlier +options for cases where a mainlined patch needs adjustments to apply in older +series (for example due to API changes). + +When using option 2 or 3 you can ask for your change to be included in specific +stable series. When doing so, ensure the fix or an equivalent is applicable, +submitted, or already present in all newer stable trees still supported. This is +meant to prevent regressions that users might later encounter on updating, if +e.g. a fix merged for 5.19-rc1 would be backported to 5.10.y, but not to 5.15.y. .. _option_1: Option 1 ******** -To have the patch automatically included in the stable tree, add the tag +To have a patch you submit for mainline inclusion later automatically picked up +for stable trees, add the tag .. code-block:: none Cc: stable@vger.kernel.org -in the sign-off area. Once the patch is merged it will be applied to -the stable tree without anything else needing to be done by the author -or subsystem maintainer. +in the sign-off area. Once the patch is mainlined it will be applied to the +stable tree without anything else needing to be done by the author or +subsystem maintainer. -.. _option_2: +To sent additional instructions to the stable team, use a shell-style inline +comment: -Option 2 -******** + * To specify any additional patch prerequisites for cherry picking use the + following format in the sign-off area: -After the patch has been merged to Linus' tree, send an email to -stable@vger.kernel.org containing the subject of the patch, the commit ID, -why you think it should be applied, and what kernel version you wish it to -be applied to. + .. code-block:: none -.. _option_3: + Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle + Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle + Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic + Cc: <stable@vger.kernel.org> # 3.3.x + Signed-off-by: Ingo Molnar <mingo@elte.hu> -Option 3 -******** + The tag sequence has the meaning of: -Send the patch, after verifying that it follows the above rules, to -stable@vger.kernel.org. You must note the upstream commit ID in the -changelog of your submission, as well as the kernel version you wish -it to be applied to. + .. code-block:: none -:ref:`option_1` is **strongly** preferred, is the easiest and most common. -:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed -worthy at the time it is applied to a public git tree (for instance, because -it deserves more regression testing first). :ref:`option_3` is especially -useful if the original upstream patch needs to be backported (for example -the backport needs some special handling due to e.g. API changes). + git cherry-pick a1f84a3 + git cherry-pick 1b9508f + git cherry-pick fd21073 + git cherry-pick <this commit> -Note that for :ref:`option_3`, if the patch deviates from the original -upstream patch (for example because it had to be backported) this must be very -clearly documented and justified in the patch description. + * For patches that may have kernel version prerequisites specify them using + the following format in the sign-off area: -The upstream commit ID must be specified with a separate line above the commit -text, like this: + .. code-block:: none -.. code-block:: none + Cc: <stable@vger.kernel.org> # 3.3.x - commit <sha1> upstream. + The tag has the meaning of: -or alternatively: + .. code-block:: none -.. code-block:: none + git cherry-pick <this commit> - [ Upstream commit <sha1> ] + For each "-stable" tree starting with the specified version. -Additionally, some patches submitted via :ref:`option_1` may have additional -patch prerequisites which can be cherry-picked. This can be specified in the -following format in the sign-off area: + Note, such tagging is unnecessary if the stable team can derive the + appropriate versions from Fixes: tags. -.. code-block:: none + * To delay pick up of patches, use the following format: - Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle - Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle - Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic - Cc: <stable@vger.kernel.org> # 3.3.x - Signed-off-by: Ingo Molnar <mingo@elte.hu> + .. code-block:: none -The tag sequence has the meaning of: + Cc: <stable@vger.kernel.org> # after 4 weeks in mainline -.. code-block:: none + * For any other requests, just add a note to the stable tag. This for example + can be used to point out known problems: - git cherry-pick a1f84a3 - git cherry-pick 1b9508f - git cherry-pick fd21073 - git cherry-pick <this commit> + .. code-block:: none + + Cc: <stable@vger.kernel.org> # see patch description, needs adjustments for <= 6.3 + +.. _option_2: + +Option 2 +******** + +If the patch already has been merged to mainline, send an email to +stable@vger.kernel.org containing the subject of the patch, the commit ID, +why you think it should be applied, and what kernel versions you wish it to +be applied to. + +.. _option_3: -Also, some patches may have kernel version prerequisites. This can be -specified in the following format in the sign-off area: +Option 3 +******** + +Send the patch, after verifying that it follows the above rules, to +stable@vger.kernel.org and mention the kernel versions you wish it to be applied +to. When doing so, you must note the upstream commit ID in the changelog of your +submission with a separate line above the commit text, like this: .. code-block:: none - Cc: <stable@vger.kernel.org> # 3.3.x + commit <sha1> upstream. -The tag has the meaning of: +or alternatively: .. code-block:: none - git cherry-pick <this commit> + [ Upstream commit <sha1> ] + +If the submitted patch deviates from the original upstream patch (for example +because it had to be adjusted for the older API), this must be very clearly +documented and justified in the patch description. -For each "-stable" tree starting with the specified version. -Following the submission: +Following the submission +------------------------ - - The sender will receive an ACK when the patch has been accepted into the - queue, or a NAK if the patch is rejected. This response might take a few - days, according to the developer's schedules. - - If accepted, the patch will be added to the -stable queue, for review by - other developers and by the relevant subsystem maintainer. +The sender will receive an ACK when the patch has been accepted into the +queue, or a NAK if the patch is rejected. This response might take a few +days, according to the schedules of the stable team members. + +If accepted, the patch will be added to the -stable queue, for review by other +developers and by the relevant subsystem maintainer. Review cycle @@ -174,6 +204,7 @@ Review cycle security kernel team, and not go through the normal review cycle. Contact the kernel security team for more details on this procedure. + Trees ----- diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index efac910e2659..86d346bcb8ef 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -327,6 +327,8 @@ politely and address the problems they have pointed out. When sending a next version, add a ``patch changelog`` to the cover letter or to individual patches explaining difference against previous submission (see :ref:`the_canonical_patch_format`). +Notify people that commented on your patch about new versions by adding them to +the patches CC list. See Documentation/process/email-clients.rst for recommendations on email clients and mailing list etiquette. @@ -366,10 +368,10 @@ busy people and may not get to your patch right away. Once upon a time, patches used to disappear into the void without comment, but the development process works more smoothly than that now. You should -receive comments within a week or so; if that does not happen, make sure -that you have sent your patches to the right place. Wait for a minimum of -one week before resubmitting or pinging reviewers - possibly longer during -busy times like merge windows. +receive comments within a few weeks (typically 2-3); if that does not +happen, make sure that you have sent your patches to the right place. +Wait for a minimum of one week before resubmitting or pinging reviewers +- possibly longer during busy times like merge windows. It's also ok to resend the patch or the patch series after a couple of weeks with the word "RESEND" added to the subject line:: diff --git a/Documentation/rust/general-information.rst b/Documentation/rust/general-information.rst index 49029ee82e55..081397827a7e 100644 --- a/Documentation/rust/general-information.rst +++ b/Documentation/rust/general-information.rst @@ -29,7 +29,7 @@ target with the same invocation used for compilation, e.g.:: To read the docs locally in your web browser, run e.g.:: - xdg-open rust/doc/kernel/index.html + xdg-open Documentation/output/rust/rustdoc/kernel/index.html To learn about how to write the documentation, please see coding-guidelines.rst. diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst index 4ae8c66b94fa..965f2db529e0 100644 --- a/Documentation/rust/index.rst +++ b/Documentation/rust/index.rst @@ -6,6 +6,33 @@ Rust Documentation related to Rust within the kernel. To start using Rust in the kernel, please read the quick-start.rst guide. + +The Rust experiment +------------------- + +The Rust support was merged in v6.1 into mainline in order to help in +determining whether Rust as a language was suitable for the kernel, i.e. worth +the tradeoffs. + +Currently, the Rust support is primarily intended for kernel developers and +maintainers interested in the Rust support, so that they can start working on +abstractions and drivers, as well as helping the development of infrastructure +and tools. + +If you are an end user, please note that there are currently no in-tree +drivers/modules suitable or intended for production use, and that the Rust +support is still in development/experimental, especially for certain kernel +configurations. + + +.. only:: rustdoc and html + + You can also browse `rustdoc documentation <rustdoc/kernel/index.html>`_. + +.. only:: not rustdoc and html + + This documentation does not include rustdoc generated information. + .. toctree:: :maxdepth: 1 diff --git a/Documentation/rust/quick-start.rst b/Documentation/rust/quick-start.rst index a8931512ed98..f382914f4191 100644 --- a/Documentation/rust/quick-start.rst +++ b/Documentation/rust/quick-start.rst @@ -38,7 +38,9 @@ and run:: rustup override set $(scripts/min-tool-version.sh rustc) -Otherwise, fetch a standalone installer from: +This will configure your working directory to use the correct version of +``rustc`` without affecting your default toolchain. If you are not using +``rustup``, fetch a standalone installer from: https://forge.rust-lang.org/infra/other-installation-methods.html#standalone @@ -56,16 +58,17 @@ If ``rustup`` is being used, run:: The components are installed per toolchain, thus upgrading the Rust compiler version later on requires re-adding the component. -Otherwise, if a standalone installer is used, the Rust repository may be cloned -into the installation folder of the toolchain:: +Otherwise, if a standalone installer is used, the Rust source tree may be +downloaded into the toolchain's installation folder:: - git clone --recurse-submodules \ - --branch $(scripts/min-tool-version.sh rustc) \ - https://github.com/rust-lang/rust \ - $(rustc --print sysroot)/lib/rustlib/src/rust + curl -L "https://static.rust-lang.org/dist/rust-src-$(scripts/min-tool-version.sh rustc).tar.gz" | + tar -xzf - -C "$(rustc --print sysroot)/lib" \ + "rust-src-$(scripts/min-tool-version.sh rustc)/rust-src/lib/" \ + --strip-components=3 In this case, upgrading the Rust compiler version later on requires manually -updating this clone. +updating the source tree (this can be done by removing ``$(rustc --print +sysroot)/lib/rustlib/src/rust`` then rerunning the above command). libclang @@ -98,7 +101,24 @@ the ``bindgen`` tool. A particular version is required. Install it via (note that this will download and build the tool from source):: - cargo install --locked --version $(scripts/min-tool-version.sh bindgen) bindgen + cargo install --locked --version $(scripts/min-tool-version.sh bindgen) bindgen-cli + +``bindgen`` needs to find a suitable ``libclang`` in order to work. If it is +not found (or a different ``libclang`` than the one found should be used), +the process can be tweaked using the environment variables understood by +``clang-sys`` (the Rust bindings crate that ``bindgen`` uses to access +``libclang``): + +* ``LLVM_CONFIG_PATH`` can be pointed to an ``llvm-config`` executable. + +* Or ``LIBCLANG_PATH`` can be pointed to a ``libclang`` shared library + or to the directory containing it. + +* Or ``CLANG_PATH`` can be pointed to a ``clang`` executable. + +For details, please see ``clang-sys``'s documentation at: + + https://github.com/KyleMayes/clang-sys#environment-variables Requirements: Developing @@ -179,7 +199,9 @@ be used with many editors to enable syntax highlighting, completion, go to definition, and other features. ``rust-analyzer`` needs a configuration file, ``rust-project.json``, which -can be generated by the ``rust-analyzer`` Make target. +can be generated by the ``rust-analyzer`` Make target:: + + make LLVM=1 rust-analyzer Configuration diff --git a/Documentation/scheduler/completion.rst b/Documentation/scheduler/completion.rst index 9f039b4f4b09..f19aca2062bd 100644 --- a/Documentation/scheduler/completion.rst +++ b/Documentation/scheduler/completion.rst @@ -157,7 +157,7 @@ A typical usage scenario is:: /* run non-dependent code */ /* do setup */ - wait_for_completion(&setup_done); complete(setup_done); + wait_for_completion(&setup_done); complete(&setup_done); This is not implying any particular order between wait_for_completion() and the call to complete() - if the call to complete() happened before the call diff --git a/Documentation/scheduler/sched-arch.rst b/Documentation/scheduler/sched-arch.rst index 505cd27f9a92..ed07efea7d02 100644 --- a/Documentation/scheduler/sched-arch.rst +++ b/Documentation/scheduler/sched-arch.rst @@ -10,7 +10,7 @@ Context switch By default, the switch_to arch function is called with the runqueue locked. This is usually not a problem unless switch_to may need to take the runqueue lock. This is usually due to a wake up operation in -the context switch. See arch/ia64/include/asm/switch_to.h for an example. +the context switch. To request the scheduler call switch_to with the runqueue unlocked, you must `#define __ARCH_WANT_UNLOCKED_CTXSW` in a header file @@ -68,7 +68,5 @@ Possible arch/ problems Possible arch problems I found (and either tried to fix or didn't): -ia64 - is safe_halt call racy vs interrupts? (does it sleep?) (See #4a) - sparc - IRQs on at this point(?), change local_irq_save to _disable. - TODO: needs secondary CPUs to disable preempt (See #1) diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst index f166b182ff95..41ed2ceafc92 100644 --- a/Documentation/scheduler/sched-bwc.rst +++ b/Documentation/scheduler/sched-bwc.rst @@ -186,7 +186,7 @@ average usage, albeit over a longer time window than a single period. This also limits the burst ability to no more than 1ms per cpu. This provides better more predictable user experience for highly threaded applications with small quota limits on high core count machines. It also eliminates the -propensity to throttle these applications while simultanously using less than +propensity to throttle these applications while simultaneously using less than quota amounts of cpu. Another way to say this, is that by allowing the unused portion of a slice to remain valid across periods we have decreased the possibility of wastefully expiring quota on cpu-local silos that don't need a diff --git a/Documentation/scheduler/sched-capacity.rst b/Documentation/scheduler/sched-capacity.rst index e2c1cf743158..de414b33dd2a 100644 --- a/Documentation/scheduler/sched-capacity.rst +++ b/Documentation/scheduler/sched-capacity.rst @@ -39,14 +39,15 @@ per Hz, leading to:: ------------------- Two different capacity values are used within the scheduler. A CPU's -``capacity_orig`` is its maximum attainable capacity, i.e. its maximum -attainable performance level. A CPU's ``capacity`` is its ``capacity_orig`` to -which some loss of available performance (e.g. time spent handling IRQs) is -subtracted. +``original capacity`` is its maximum attainable capacity, i.e. its maximum +attainable performance level. This original capacity is returned by +the function arch_scale_cpu_capacity(). A CPU's ``capacity`` is its ``original +capacity`` to which some loss of available performance (e.g. time spent +handling IRQs) is subtracted. Note that a CPU's ``capacity`` is solely intended to be used by the CFS class, -while ``capacity_orig`` is class-agnostic. The rest of this document will use -the term ``capacity`` interchangeably with ``capacity_orig`` for the sake of +while ``original capacity`` is class-agnostic. The rest of this document will use +the term ``capacity`` interchangeably with ``original capacity`` for the sake of brevity. 1.3 Platform examples diff --git a/Documentation/scheduler/sched-design-CFS.rst b/Documentation/scheduler/sched-design-CFS.rst index 03db55504515..f68919800f05 100644 --- a/Documentation/scheduler/sched-design-CFS.rst +++ b/Documentation/scheduler/sched-design-CFS.rst @@ -94,7 +94,7 @@ other HZ detail. Thus the CFS scheduler has no notion of "timeslices" in the way the previous scheduler had, and has no heuristics whatsoever. There is only one central tunable (you have to switch on CONFIG_SCHED_DEBUG): - /sys/kernel/debug/sched/min_granularity_ns + /sys/kernel/debug/sched/base_slice_ns which can be used to tune the scheduler from "desktop" (i.e., low latencies) to "server" (i.e., good batching) workloads. It defaults to a setting suitable diff --git a/Documentation/scheduler/sched-energy.rst b/Documentation/scheduler/sched-energy.rst index 8fbce5e767d9..70e2921ef725 100644 --- a/Documentation/scheduler/sched-energy.rst +++ b/Documentation/scheduler/sched-energy.rst @@ -82,7 +82,7 @@ through the arch_scale_cpu_capacity() callback. The rest of platform knowledge used by EAS is directly read from the Energy Model (EM) framework. The EM of a platform is composed of a power cost table per 'performance domain' in the system (see Documentation/power/energy-model.rst -for futher details about performance domains). +for further details about performance domains). The scheduler manages references to the EM objects in the topology code when the scheduling domains are built, or re-built. For each root domain (rd), the @@ -281,7 +281,7 @@ mechanism called 'over-utilization'. From a general standpoint, the use-cases where EAS can help the most are those involving a light/medium CPU utilization. Whenever long CPU-bound tasks are being run, they will require all of the available CPU capacity, and there isn't -much that can be done by the scheduler to save energy without severly harming +much that can be done by the scheduler to save energy without severely harming throughput. In order to avoid hurting performance with EAS, CPUs are flagged as 'over-utilized' as soon as they are used at more than 80% of their compute capacity. As long as no CPUs are over-utilized in a root domain, load balancing @@ -359,32 +359,9 @@ in milli-Watts or in an 'abstract scale'. 6.3 - Energy Model complexity ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The task wake-up path is very latency-sensitive. When the EM of a platform is -too complex (too many CPUs, too many performance domains, too many performance -states, ...), the cost of using it in the wake-up path can become prohibitive. -The energy-aware wake-up algorithm has a complexity of: - - C = Nd * (Nc + Ns) - -with: Nd the number of performance domains; Nc the number of CPUs; and Ns the -total number of OPPs (ex: for two perf. domains with 4 OPPs each, Ns = 8). - -A complexity check is performed at the root domain level, when scheduling -domains are built. EAS will not start on a root domain if its C happens to be -higher than the completely arbitrary EM_MAX_COMPLEXITY threshold (2048 at the -time of writing). - -If you really want to use EAS but the complexity of your platform's Energy -Model is too high to be used with a single root domain, you're left with only -two possible options: - - 1. split your system into separate, smaller, root domains using exclusive - cpusets and enable EAS locally on each of them. This option has the - benefit to work out of the box but the drawback of preventing load - balance between root domains, which can result in an unbalanced system - overall; - 2. submit patches to reduce the complexity of the EAS wake-up algorithm, - hence enabling it to cope with larger EMs in reasonable time. +EAS does not impose any complexity limit on the number of PDs/OPPs/CPUs but +restricts the number of CPUs to EM_MAX_NUM_CPUS to prevent overflows during +the energy estimation. 6.4 - Schedutil governor diff --git a/Documentation/scheduler/sched-rt-group.rst b/Documentation/scheduler/sched-rt-group.rst index 655a096ec8fb..d685609ed3d7 100644 --- a/Documentation/scheduler/sched-rt-group.rst +++ b/Documentation/scheduler/sched-rt-group.rst @@ -39,10 +39,10 @@ Most notable: 1.1 The problem --------------- -Realtime scheduling is all about determinism, a group has to be able to rely on +Real-time scheduling is all about determinism, a group has to be able to rely on the amount of bandwidth (eg. CPU time) being constant. In order to schedule -multiple groups of realtime tasks, each group must be assigned a fixed portion -of the CPU time available. Without a minimum guarantee a realtime group can +multiple groups of real-time tasks, each group must be assigned a fixed portion +of the CPU time available. Without a minimum guarantee a real-time group can obviously fall short. A fuzzy upper limit is of no use since it cannot be relied upon. Which leaves us with just the single fixed portion. @@ -50,14 +50,14 @@ relied upon. Which leaves us with just the single fixed portion. ---------------- CPU time is divided by means of specifying how much time can be spent running -in a given period. We allocate this "run time" for each realtime group which -the other realtime groups will not be permitted to use. +in a given period. We allocate this "run time" for each real-time group which +the other real-time groups will not be permitted to use. -Any time not allocated to a realtime group will be used to run normal priority +Any time not allocated to a real-time group will be used to run normal priority tasks (SCHED_OTHER). Any allocated run time not used will also be picked up by SCHED_OTHER. -Let's consider an example: a frame fixed realtime renderer must deliver 25 +Let's consider an example: a frame fixed real-time renderer must deliver 25 frames a second, which yields a period of 0.04s per frame. Now say it will also have to play some music and respond to input, leaving it with around 80% CPU time dedicated for the graphics. We can then give this group a run time of 0.8 @@ -70,7 +70,7 @@ needs only about 3% CPU time to do so, it can do with a 0.03 * 0.005s = of 0.00015s. The remaining CPU time will be used for user input and other tasks. Because -realtime tasks have explicitly allocated the CPU time they need to perform +real-time tasks have explicitly allocated the CPU time they need to perform their tasks, buffer underruns in the graphics or audio can be eliminated. NOTE: the above example is not fully implemented yet. We still @@ -87,18 +87,20 @@ lack an EDF scheduler to make non-uniform periods usable. The system wide settings are configured under the /proc virtual file system: /proc/sys/kernel/sched_rt_period_us: - The scheduling period that is equivalent to 100% CPU bandwidth + The scheduling period that is equivalent to 100% CPU bandwidth. /proc/sys/kernel/sched_rt_runtime_us: - A global limit on how much time realtime scheduling may use. Even without - CONFIG_RT_GROUP_SCHED enabled, this will limit time reserved to realtime - processes. With CONFIG_RT_GROUP_SCHED it signifies the total bandwidth - available to all realtime groups. + A global limit on how much time real-time scheduling may use. This is always + less or equal to the period_us, as it denotes the time allocated from the + period_us for the real-time tasks. Even without CONFIG_RT_GROUP_SCHED enabled, + this will limit time reserved to real-time processes. With + CONFIG_RT_GROUP_SCHED=y it signifies the total bandwidth available to all + real-time groups. * Time is specified in us because the interface is s32. This gives an operating range from 1us to about 35 minutes. * sched_rt_period_us takes values from 1 to INT_MAX. - * sched_rt_runtime_us takes values from -1 to (INT_MAX - 1). + * sched_rt_runtime_us takes values from -1 to sched_rt_period_us. * A run time of -1 specifies runtime == period, ie. no limit. @@ -108,7 +110,7 @@ The system wide settings are configured under the /proc virtual file system: The default values for sched_rt_period_us (1000000 or 1s) and sched_rt_runtime_us (950000 or 0.95s). This gives 0.05s to be used by SCHED_OTHER (non-RT tasks). These defaults were chosen so that a run-away -realtime tasks will not lock up the machine but leave a little time to recover +real-time tasks will not lock up the machine but leave a little time to recover it. By setting runtime to -1 you'd get the old behaviour back. By default all bandwidth is assigned to the root group and new groups get the @@ -116,10 +118,10 @@ period from /proc/sys/kernel/sched_rt_period_us and a run time of 0. If you want to assign bandwidth to another group, reduce the root group's bandwidth and assign some or all of the difference to another group. -Realtime group scheduling means you have to assign a portion of total CPU -bandwidth to the group before it will accept realtime tasks. Therefore you will -not be able to run realtime tasks as any user other than root until you have -done that, even if the user has the rights to run processes with realtime +Real-time group scheduling means you have to assign a portion of total CPU +bandwidth to the group before it will accept real-time tasks. Therefore you will +not be able to run real-time tasks as any user other than root until you have +done that, even if the user has the rights to run processes with real-time priority! diff --git a/Documentation/scsi/ChangeLog.lpfc b/Documentation/scsi/ChangeLog.lpfc index d16e6874d223..ccc48b8359bf 100644 --- a/Documentation/scsi/ChangeLog.lpfc +++ b/Documentation/scsi/ChangeLog.lpfc @@ -427,7 +427,7 @@ Changes from 20041207 to 20041213 * Changed version number to 8.0.17 * Fix sparse warnings by adding __iomem markers to lpfc_compat.h. * Fix some sparse warnings -- 0 used as NULL pointer. - * Make sure there's a space between every if and it's (. + * Make sure there's a space between every if and its (. * Fix some overly long lines and make sure hard tabs are used for indentation. * Remove all trailing whitespace. diff --git a/Documentation/scsi/scsi_mid_low_api.rst b/Documentation/scsi/scsi_mid_low_api.rst index 6fa3a6279501..022198c51350 100644 --- a/Documentation/scsi/scsi_mid_low_api.rst +++ b/Documentation/scsi/scsi_mid_low_api.rst @@ -1190,11 +1190,11 @@ Members of interest: - pointer to scsi_device object that this command is associated with. resid - - an LLD should set this signed integer to the requested + - an LLD should set this unsigned integer to the requested transfer length (i.e. 'request_bufflen') less the number of bytes that are actually transferred. 'resid' is preset to 0 so an LLD can ignore it if it cannot detect - underruns (overruns should be rare). If possible an LLD + underruns (overruns should not be reported). An LLD should set 'resid' prior to invoking 'done'. The most interesting case is data transfers from a SCSI target device (e.g. READs) that underrun. diff --git a/Documentation/security/digsig.rst b/Documentation/security/digsig.rst index f6a8902d3ef7..de035f282196 100644 --- a/Documentation/security/digsig.rst +++ b/Documentation/security/digsig.rst @@ -82,7 +82,7 @@ The signing and key management utilities evm-utils provide functionality to generate signatures, to load keys into the kernel keyring. Keys can be in PEM or converted to the kernel format. When the key is added to the kernel keyring, the keyid defines the name -of the key: 5D2B05FC633EE3E8 in the example bellow. +of the key: 5D2B05FC633EE3E8 in the example below. Here is example output of the keyctl utility:: diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst index 6ed8d2fa6f9e..59f8fc106cb0 100644 --- a/Documentation/security/index.rst +++ b/Documentation/security/index.rst @@ -6,6 +6,7 @@ Security Documentation :maxdepth: 1 credentials + snp-tdx-threat-model IMA-templates keys/index lsm diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst index 811b905b56bf..326b8a973828 100644 --- a/Documentation/security/keys/core.rst +++ b/Documentation/security/keys/core.rst @@ -869,7 +869,7 @@ The keyctl syscall functions are: - ``char *hashname`` specifies the NUL terminated string identifying the hash used from the kernel crypto API and applied for the KDF - operation. The KDF implemenation complies with SP800-56A as well + operation. The KDF implementation complies with SP800-56A as well as with SP800-108 (the counter KDF). - ``char *otherinfo`` specifies the OtherInfo data as documented in diff --git a/Documentation/security/secrets/coco.rst b/Documentation/security/secrets/coco.rst index 087e2d1ae38b..a1210db8ec07 100644 --- a/Documentation/security/secrets/coco.rst +++ b/Documentation/security/secrets/coco.rst @@ -34,7 +34,7 @@ be use it for its own purposes. During the VM's launch, the virtual machine manager may inject a secret to that area. In AMD SEV and SEV-ES this is performed using the -``KVM_SEV_LAUNCH_SECRET`` command (see [sev]_). The strucutre of the injected +``KVM_SEV_LAUNCH_SECRET`` command (see [sev]_). The structure of the injected Guest Owner secret data should be a GUIDed table of secret values; the binary format is described in ``drivers/virt/coco/efi_secret/efi_secret.c`` under "Structure of the EFI secret area". diff --git a/Documentation/security/snp-tdx-threat-model.rst b/Documentation/security/snp-tdx-threat-model.rst new file mode 100644 index 000000000000..ec66f2ed80c9 --- /dev/null +++ b/Documentation/security/snp-tdx-threat-model.rst @@ -0,0 +1,253 @@ +====================================================== +Confidential Computing in Linux for x86 virtualization +====================================================== + +.. contents:: :local: + +By: Elena Reshetova <elena.reshetova@intel.com> and Carlos Bilbao <carlos.bilbao@amd.com> + +Motivation +========== + +Kernel developers working on confidential computing for virtualized +environments in x86 operate under a set of assumptions regarding the Linux +kernel threat model that differ from the traditional view. Historically, +the Linux threat model acknowledges attackers residing in userspace, as +well as a limited set of external attackers that are able to interact with +the kernel through various networking or limited HW-specific exposed +interfaces (USB, thunderbolt). The goal of this document is to explain +additional attack vectors that arise in the confidential computing space +and discuss the proposed protection mechanisms for the Linux kernel. + +Overview and terminology +======================== + +Confidential Computing (CoCo) is a broad term covering a wide range of +security technologies that aim to protect the confidentiality and integrity +of data in use (vs. data at rest or data in transit). At its core, CoCo +solutions provide a Trusted Execution Environment (TEE), where secure data +processing can be performed and, as a result, they are typically further +classified into different subtypes depending on the SW that is intended +to be run in TEE. This document focuses on a subclass of CoCo technologies +that are targeting virtualized environments and allow running Virtual +Machines (VM) inside TEE. From now on in this document will be referring +to this subclass of CoCo as 'Confidential Computing (CoCo) for the +virtualized environments (VE)'. + +CoCo, in the virtualization context, refers to a set of HW and/or SW +technologies that allow for stronger security guarantees for the SW running +inside a CoCo VM. Namely, confidential computing allows its users to +confirm the trustworthiness of all SW pieces to include in its reduced +Trusted Computing Base (TCB) given its ability to attest the state of these +trusted components. + +While the concrete implementation details differ between technologies, all +available mechanisms aim to provide increased confidentiality and +integrity for the VM's guest memory and execution state (vCPU registers), +more tightly controlled guest interrupt injection, as well as some +additional mechanisms to control guest-host page mapping. More details on +the x86-specific solutions can be found in +:doc:`Intel Trust Domain Extensions (TDX) </arch/x86/tdx>` and +`AMD Memory Encryption <https://www.amd.com/system/files/techdocs/sev-snp-strengthening-vm-isolation-with-integrity-protection-and-more.pdf>`_. + +The basic CoCo guest layout includes the host, guest, the interfaces that +communicate guest and host, a platform capable of supporting CoCo VMs, and +a trusted intermediary between the guest VM and the underlying platform +that acts as a security manager. The host-side virtual machine monitor +(VMM) typically consists of a subset of traditional VMM features and +is still in charge of the guest lifecycle, i.e. create or destroy a CoCo +VM, manage its access to system resources, etc. However, since it +typically stays out of CoCo VM TCB, its access is limited to preserve the +security objectives. + +In the following diagram, the "<--->" lines represent bi-directional +communication channels or interfaces between the CoCo security manager and +the rest of the components (data flow for guest, host, hardware) :: + + +-------------------+ +-----------------------+ + | CoCo guest VM |<---->| | + +-------------------+ | | + | Interfaces | | CoCo security manager | + +-------------------+ | | + | Host VMM |<---->| | + +-------------------+ | | + | | + +--------------------+ | | + | CoCo platform |<--->| | + +--------------------+ +-----------------------+ + +The specific details of the CoCo security manager vastly diverge between +technologies. For example, in some cases, it will be implemented in HW +while in others it may be pure SW. + +Existing Linux kernel threat model +================================== + +The overall components of the current Linux kernel threat model are:: + + +-----------------------+ +-------------------+ + | |<---->| Userspace | + | | +-------------------+ + | External attack | | Interfaces | + | vectors | +-------------------+ + | |<---->| Linux Kernel | + | | +-------------------+ + +-----------------------+ +-------------------+ + | Bootloader/BIOS | + +-------------------+ + +-------------------+ + | HW platform | + +-------------------+ + +There is also communication between the bootloader and the kernel during +the boot process, but this diagram does not represent it explicitly. The +"Interfaces" box represents the various interfaces that allow +communication between kernel and userspace. This includes system calls, +kernel APIs, device drivers, etc. + +The existing Linux kernel threat model typically assumes execution on a +trusted HW platform with all of the firmware and bootloaders included on +its TCB. The primary attacker resides in the userspace, and all of the data +coming from there is generally considered untrusted, unless userspace is +privileged enough to perform trusted actions. In addition, external +attackers are typically considered, including those with access to enabled +external networks (e.g. Ethernet, Wireless, Bluetooth), exposed hardware +interfaces (e.g. USB, Thunderbolt), and the ability to modify the contents +of disks offline. + +Regarding external attack vectors, it is interesting to note that in most +cases external attackers will try to exploit vulnerabilities in userspace +first, but that it is possible for an attacker to directly target the +kernel; particularly if the host has physical access. Examples of direct +kernel attacks include the vulnerabilities CVE-2019-19524, CVE-2022-0435 +and CVE-2020-24490. + +Confidential Computing threat model and its security objectives +=============================================================== + +Confidential Computing adds a new type of attacker to the above list: a +potentially misbehaving host (which can also include some part of a +traditional VMM or all of it), which is typically placed outside of the +CoCo VM TCB due to its large SW attack surface. It is important to note +that this doesn’t imply that the host or VMM are intentionally +malicious, but that there exists a security value in having a small CoCo +VM TCB. This new type of adversary may be viewed as a more powerful type +of external attacker, as it resides locally on the same physical machine +(in contrast to a remote network attacker) and has control over the guest +kernel communication with most of the HW:: + + +------------------------+ + | CoCo guest VM | + +-----------------------+ | +-------------------+ | + | |<--->| | Userspace | | + | | | +-------------------+ | + | External attack | | | Interfaces | | + | vectors | | +-------------------+ | + | |<--->| | Linux Kernel | | + | | | +-------------------+ | + +-----------------------+ | +-------------------+ | + | | Bootloader/BIOS | | + +-----------------------+ | +-------------------+ | + | |<--->+------------------------+ + | | | Interfaces | + | | +------------------------+ + | CoCo security |<--->| Host/Host-side VMM | + | manager | +------------------------+ + | | +------------------------+ + | |<--->| CoCo platform | + +-----------------------+ +------------------------+ + +While traditionally the host has unlimited access to guest data and can +leverage this access to attack the guest, the CoCo systems mitigate such +attacks by adding security features like guest data confidentiality and +integrity protection. This threat model assumes that those features are +available and intact. + +The **Linux kernel CoCo VM security objectives** can be summarized as follows: + +1. Preserve the confidentiality and integrity of CoCo guest's private +memory and registers. + +2. Prevent privileged escalation from a host into a CoCo guest Linux kernel. +While it is true that the host (and host-side VMM) requires some level of +privilege to create, destroy, or pause the guest, part of the goal of +preventing privileged escalation is to ensure that these operations do not +provide a pathway for attackers to gain access to the guest's kernel. + +The above security objectives result in two primary **Linux kernel CoCo +VM assets**: + +1. Guest kernel execution context. +2. Guest kernel private memory. + +The host retains full control over the CoCo guest resources, and can deny +access to them at any time. Examples of resources include CPU time, memory +that the guest can consume, network bandwidth, etc. Because of this, the +host Denial of Service (DoS) attacks against CoCo guests are beyond the +scope of this threat model. + +The **Linux CoCo VM attack surface** is any interface exposed from a CoCo +guest Linux kernel towards an untrusted host that is not covered by the +CoCo technology SW/HW protection. This includes any possible +side-channels, as well as transient execution side channels. Examples of +explicit (not side-channel) interfaces include accesses to port I/O, MMIO +and DMA interfaces, access to PCI configuration space, VMM-specific +hypercalls (towards Host-side VMM), access to shared memory pages, +interrupts allowed to be injected into the guest kernel by the host, as +well as CoCo technology-specific hypercalls, if present. Additionally, the +host in a CoCo system typically controls the process of creating a CoCo +guest: it has a method to load into a guest the firmware and bootloader +images, the kernel image together with the kernel command line. All of this +data should also be considered untrusted until its integrity and +authenticity is established via attestation. + +The table below shows a threat matrix for the CoCo guest Linux kernel but +does not discuss potential mitigation strategies. The matrix refers to +CoCo-specific versions of the guest, host and platform. + +.. list-table:: CoCo Linux guest kernel threat matrix + :widths: auto + :align: center + :header-rows: 1 + + * - Threat name + - Threat description + + * - Guest malicious configuration + - A misbehaving host modifies one of the following guest's + configuration: + + 1. Guest firmware or bootloader + + 2. Guest kernel or module binaries + + 3. Guest command line parameters + + This allows the host to break the integrity of the code running + inside a CoCo guest, and violates the CoCo security objectives. + + * - CoCo guest data attacks + - A misbehaving host retains full control of the CoCo guest's data + in-transit between the guest and the host-managed physical or + virtual devices. This allows any attack against confidentiality, + integrity or freshness of such data. + + * - Malformed runtime input + - A misbehaving host injects malformed input via any communication + interface used by the guest's kernel code. If the code is not + prepared to handle this input correctly, this can result in a host + --> guest kernel privilege escalation. This includes traditional + side-channel and/or transient execution attack vectors. + + * - Malicious runtime input + - A misbehaving host injects a specific input value via any + communication interface used by the guest's kernel code. The + difference with the previous attack vector (malformed runtime input) + is that this input is not malformed, but its value is crafted to + impact the guest's kernel security. Examples of such inputs include + providing a malicious time to the guest or the entropy to the guest + random number generator. Additionally, the timing of such events can + be an attack vector on its own, if it results in a particular guest + kernel action (i.e. processing of a host-injected interrupt). + resistant to supplied host input. + diff --git a/Documentation/sound/cards/audigy-mixer.rst b/Documentation/sound/cards/audigy-mixer.rst index ea66b50a2b03..7ebaacb6df3d 100644 --- a/Documentation/sound/cards/audigy-mixer.rst +++ b/Documentation/sound/cards/audigy-mixer.rst @@ -46,157 +46,158 @@ FX-bus name='PCM Front Playback Volume',index=0 ---------------------------------------- -This control is used to attenuate samples for left and right front PCM FX-bus +This control is used to attenuate samples from left and right front PCM FX-bus accumulators. ALSA uses accumulators 8 and 9 for left and right front PCM -samples for 5.1 playback. The result samples are forwarded to the front DAC PCM -slots of the Philips DAC. +samples for 5.1 playback. The result samples are forwarded to the front speakers. name='PCM Surround Playback Volume',index=0 ------------------------------------------- -This control is used to attenuate samples for left and right surround PCM FX-bus +This control is used to attenuate samples from left and right surround PCM FX-bus accumulators. ALSA uses accumulators 2 and 3 for left and right surround PCM -samples for 5.1 playback. The result samples are forwarded to the surround DAC PCM -slots of the Philips DAC. +samples for 5.1 playback. The result samples are forwarded to the surround (rear) +speakers. + +name='PCM Side Playback Volume',index=0 +--------------------------------------- +This control is used to attenuate samples from left and right side PCM FX-bus +accumulators. ALSA uses accumulators 14 and 15 for left and right side PCM +samples for 7.1 playback. The result samples are forwarded to the side speakers. name='PCM Center Playback Volume',index=0 ----------------------------------------- -This control is used to attenuate samples for center PCM FX-bus accumulator. -ALSA uses accumulator 6 for center PCM sample for 5.1 playback. The result sample -is forwarded to the center DAC PCM slot of the Philips DAC. +This control is used to attenuate samples from center PCM FX-bus accumulator. +ALSA uses accumulator 6 for center PCM samples for 5.1 playback. The result +samples are forwarded to the center speaker. name='PCM LFE Playback Volume',index=0 -------------------------------------- This control is used to attenuate sample for LFE PCM FX-bus accumulator. -ALSA uses accumulator 7 for LFE PCM sample for 5.1 playback. The result sample -is forwarded to the LFE DAC PCM slot of the Philips DAC. +ALSA uses accumulator 7 for LFE PCM samples for 5.1 playback. The result +samples are forwarded to the subwoofer. name='PCM Playback Volume',index=0 ---------------------------------- -This control is used to attenuate samples for left and right PCM FX-bus +This control is used to attenuate samples from left and right PCM FX-bus accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples for -stereo playback. The result samples are forwarded to the front DAC PCM slots -of the Philips DAC. +stereo playback. The result samples are forwarded to the front speakers. name='PCM Capture Volume',index=0 --------------------------------- -This control is used to attenuate samples for left and right PCM FX-bus -accumulator. ALSA uses accumulators 0 and 1 for left and right PCM. -The result is forwarded to the ADC capture FIFO (thus to the standard capture -PCM device). +This control is used to attenuate samples from left and right PCM FX-bus +accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples for +stereo playback. The result is forwarded to the standard capture PCM device. name='Music Playback Volume',index=0 ------------------------------------ -This control is used to attenuate samples for left and right MIDI FX-bus +This control is used to attenuate samples from left and right MIDI FX-bus accumulators. ALSA uses accumulators 4 and 5 for left and right MIDI samples. -The result samples are forwarded to the front DAC PCM slots of the AC97 codec. +The result samples are forwarded to the virtual stereo mixer. name='Music Capture Volume',index=0 ----------------------------------- -These controls are used to attenuate samples for left and right MIDI FX-bus -accumulator. ALSA uses accumulators 4 and 5 for left and right PCM. -The result is forwarded to the ADC capture FIFO (thus to the standard capture -PCM device). +These controls are used to attenuate samples from left and right MIDI FX-bus +accumulator. ALSA uses accumulators 4 and 5 for left and right MIDI samples. +The result is forwarded to the standard capture PCM device. name='Mic Playback Volume',index=0 ---------------------------------- -This control is used to attenuate samples for left and right Mic input. -For Mic input is used AC97 codec. The result samples are forwarded to -the front DAC PCM slots of the Philips DAC. Samples are forwarded to Mic -capture FIFO (device 1 - 16bit/8KHz mono) too without volume control. +This control is used to attenuate samples from left and right Mic input of +the AC97 codec. The result samples are forwarded to the virtual stereo mixer. name='Mic Capture Volume',index=0 --------------------------------- -This control is used to attenuate samples for left and right Mic input. -The result is forwarded to the ADC capture FIFO (thus to the standard capture -PCM device). +This control is used to attenuate samples from left and right Mic input of +the AC97 codec. The result is forwarded to the standard capture PCM device. + +The original samples are also forwarded to the Mic capture PCM device (device 1; +16bit/8KHz mono) without volume control. name='Audigy CD Playback Volume',index=0 ---------------------------------------- This control is used to attenuate samples from left and right IEC958 TTL digital inputs (usually used by a CDROM drive). The result samples are -forwarded to the front DAC PCM slots of the Philips DAC. +forwarded to the virtual stereo mixer. name='Audigy CD Capture Volume',index=0 --------------------------------------- This control is used to attenuate samples from left and right IEC958 TTL -digital inputs (usually used by a CDROM drive). The result samples are -forwarded to the ADC capture FIFO (thus to the standard capture PCM device). +digital inputs (usually used by a CDROM drive). The result is forwarded +to the standard capture PCM device. name='IEC958 Optical Playback Volume',index=0 --------------------------------------------- This control is used to attenuate samples from left and right IEC958 optical -digital input. The result samples are forwarded to the front DAC PCM slots -of the Philips DAC. +digital input. The result samples are forwarded to the virtual stereo mixer. name='IEC958 Optical Capture Volume',index=0 -------------------------------------------- This control is used to attenuate samples from left and right IEC958 optical -digital inputs. The result samples are forwarded to the ADC capture FIFO -(thus to the standard capture PCM device). +digital inputs. The result is forwarded to the standard capture PCM device. name='Line2 Playback Volume',index=0 ------------------------------------ This control is used to attenuate samples from left and right I2S ADC -inputs (on the AudigyDrive). The result samples are forwarded to the front -DAC PCM slots of the Philips DAC. +inputs (on the AudigyDrive). The result samples are forwarded to the virtual +stereo mixer. name='Line2 Capture Volume',index=1 ----------------------------------- This control is used to attenuate samples from left and right I2S ADC -inputs (on the AudigyDrive). The result samples are forwarded to the ADC -capture FIFO (thus to the standard capture PCM device). +inputs (on the AudigyDrive). The result is forwarded to the standard capture +PCM device. name='Analog Mix Playback Volume',index=0 ----------------------------------------- This control is used to attenuate samples from left and right I2S ADC -inputs from Philips ADC. The result samples are forwarded to the front -DAC PCM slots of the Philips DAC. This contains mix from analog sources -like CD, Line In, Aux, .... +inputs from Philips ADC. The result samples are forwarded to the virtual +stereo mixer. This contains mix from analog sources like CD, Line In, Aux, .... name='Analog Mix Capture Volume',index=1 ---------------------------------------- This control is used to attenuate samples from left and right I2S ADC -inputs Philips ADC. The result samples are forwarded to the ADC -capture FIFO (thus to the standard capture PCM device). +inputs Philips ADC. The result is forwarded to the standard capture PCM device. name='Aux2 Playback Volume',index=0 ----------------------------------- This control is used to attenuate samples from left and right I2S ADC -inputs (on the AudigyDrive). The result samples are forwarded to the front -DAC PCM slots of the Philips DAC. +inputs (on the AudigyDrive). The result samples are forwarded to the virtual +stereo mixer. name='Aux2 Capture Volume',index=1 ---------------------------------- This control is used to attenuate samples from left and right I2S ADC -inputs (on the AudigyDrive). The result samples are forwarded to the ADC -capture FIFO (thus to the standard capture PCM device). +inputs (on the AudigyDrive). The result is forwarded to the standard capture +PCM device. name='Front Playback Volume',index=0 ------------------------------------ -All stereo signals are mixed together and mirrored to surround, center and LFE. -This control is used to attenuate samples for left and right front speakers of -this mix. +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the front speakers. name='Surround Playback Volume',index=0 --------------------------------------- -All stereo signals are mixed together and mirrored to surround, center and LFE. -This control is used to attenuate samples for left and right surround speakers of -this mix. +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the surround (rear) speakers. + +name='Side Playback Volume',index=0 +----------------------------------- +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the side speakers. name='Center Playback Volume',index=0 ------------------------------------- -All stereo signals are mixed together and mirrored to surround, center and LFE. -This control is used to attenuate sample for center speaker of this mix. +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the center speaker. name='LFE Playback Volume',index=0 ---------------------------------- -All stereo signals are mixed together and mirrored to surround, center and LFE. -This control is used to attenuate sample for LFE speaker of this mix. +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the subwoofer. name='Tone Control - Switch',index=0 ------------------------------------ -This control turns the tone control on or off. The samples for front, rear -and center / LFE outputs are affected. +This control turns the tone control on or off. The samples forwarded to +the speaker outputs are affected. name='Tone Control - Bass',index=0 ---------------------------------- @@ -212,8 +213,7 @@ The closest value to pure signal is 20. name='Master Playback Volume',index=0 ------------------------------------- -This control is used to attenuate samples for front, surround, center and -LFE outputs. +This control is used to attenuate samples forwarded to the speaker outputs. name='IEC958 Optical Raw Playback Switch',index=0 ------------------------------------------------- @@ -303,69 +303,4 @@ The channel mapping is following: MANUALS/PATENTS =============== -ftp://opensource.creative.com/pub/doc -------------------------------------- - -Note that the site is defunct, but the documents are available -from various other locations. - -LM4545.pdf - AC97 Codec - -m2049.pdf - The EMU10K1 Digital Audio Processor - -hog63.ps - FX8010 - A DSP Chip Architecture for Audio Effects - - -WIPO Patents ------------- - -WO 9901813 (A1) - Audio Effects Processor with multiple asynchronous streams - (Jan. 14, 1999) - -WO 9901814 (A1) - Processor with Instruction Set for Audio Effects (Jan. 14, 1999) - -WO 9901953 (A1) - Audio Effects Processor having Decoupled Instruction - Execution and Audio Data Sequencing (Jan. 14, 1999) - - -US Patents (https://www.uspto.gov/) ------------------------------------ - -US 5925841 - Digital Sampling Instrument employing cache memory (Jul. 20, 1999) - -US 5928342 - Audio Effects Processor integrated on a single chip - with a multiport memory onto which multiple asynchronous - digital sound samples can be concurrently loaded - (Jul. 27, 1999) - -US 5930158 - Processor with Instruction Set for Audio Effects (Jul. 27, 1999) - -US 6032235 - Memory initialization circuit (Tram) (Feb. 29, 2000) - -US 6138207 - Interpolation looping of audio samples in cache connected to - system bus with prioritization and modification of bus transfers - in accordance with loop ends and minimum block sizes - (Oct. 24, 2000) - -US 6151670 - Method for conserving memory storage using a - pool of short term memory registers - (Nov. 21, 2000) - -US 6195715 - Interrupt control for multiple programs communicating with - a common interrupt by associating programs to GP registers, - defining interrupt register, polling GP registers, and invoking - callback routine associated with defined interrupt register - (Feb. 27, 2001) +See sb-live-mixer.rst. diff --git a/Documentation/sound/cards/emu-mixer.rst b/Documentation/sound/cards/emu-mixer.rst new file mode 100644 index 000000000000..d87a6338d3d8 --- /dev/null +++ b/Documentation/sound/cards/emu-mixer.rst @@ -0,0 +1,226 @@ +================================================== +E-MU Digital Audio System mixer / default DSP code +================================================== + +This document covers the E-MU 0404/1010/1212/1616/1820 PCI/PCI-e/CardBus +cards. + +These cards use regular EMU10K2 (SoundBlaster Audigy) chips, but with an +alternative front-end geared towards semi-professional studio recording. + +This document is based on audigy-mixer.rst. + + +Hardware compatibility +====================== + +The EMU10K2 chips have a very short capture FIFO, which makes recording +unreliable if the card's PCI bus requests are not handled with the +appropriate priority. +This is the case on more modern motherboards, where the PCI bus is only a +secondary peripheral, rather than the actual arbiter of device access. +In particular, I got recording glitches during simultaneous playback on an +Intel DP55 board (memory controller in the CPU), but had success with an +Intel DP45 board (memory controller in the north bridge). + +The PCI Express variants of these cards (which have a PCI bridge on board, +but are otherwise identical) may be less problematic. + + +Driver capabilities +=================== + +This driver supports only 16-bit 44.1/48 kHz operation. The multi-channel +device (see emu10k1-jack.rst) additionally supports 24-bit capture. + +A patchset to enhance the driver is available from `a GitHub repository +<https://github.com/ossilator/linux/tree/ossis-emu10k1>`_. +Its multi-channel device supports 24-bit for both playback and capture, +and also supports full 88.2/96/176.4/192 kHz operation. +It is not going to be upstreamed due to a fundamental disagreement about +what constitutes a good user experience. + + +Digital mixer controls +====================== + +Note that the controls work as attenuators: the maximum value is the neutral +position leaving the signal unchanged. Note that if the same destination is +mentioned in multiple controls, the signal is accumulated and can be clipped +(set to maximal or minimal value without checking for overflow). + +Explanation of used abbreviations: + +DAC + digital to analog converter +ADC + analog to digital converter +LFE + low frequency effects (used as subwoofer signal) +IEC958 + S/PDIF +FX-bus + the EMU10K2 chip has an effect bus containing 64 accumulators. + Each of the synthesizer voices can feed its output to these accumulators + and the DSP microcontroller can operate with the resulting sum. + +name='Clock Source',index=0 +--------------------------- +This control allows switching the word clock between interally generated +44.1 or 48 kHz, or a number of external sources. + +Note: the sources for the 1616 CardBus card are unclear. Please report your +findings. + +name='Clock Fallback',index=0 +----------------------------- +This control determines the internal clock which the card switches to when +the selected external clock source is/becomes invalid. + +name='DAC1 0202 14dB PAD',index=0, etc. +--------------------------------------- +Output attenuation controls. Not available on 0404 cards. + +name='ADC1 14dB PAD 0202',index=0, etc. +--------------------------------------- +Input attenuation controls. Not available on 0404 cards. + +name='Optical Output Mode',index=0 +---------------------------------- +Switches the TOSLINK output port between S/PDIF and ADAT. +Not available on 0404 cards (fixed to S/PDIF). + +name='Optical Input Mode',index=0 +--------------------------------- +Switches the TOSLINK input port between S/PDIF and ADAT. +Not available on 0404 cards (fixed to S/PDIF). + +name='PCM Front Playback Volume',index=0 +---------------------------------------- +This control is used to attenuate samples from left and right front PCM FX-bus +accumulators. ALSA uses accumulators 8 and 9 for left and right front PCM +samples for 5.1 playback. The result samples are forwarded to the DSP 0 & 1 +playback channels. + +name='PCM Surround Playback Volume',index=0 +------------------------------------------- +This control is used to attenuate samples from left and right surround PCM FX-bus +accumulators. ALSA uses accumulators 2 and 3 for left and right surround PCM +samples for 5.1 playback. The result samples are forwarded to the DSP 2 & 3 +playback channels. + +name='PCM Side Playback Volume',index=0 +--------------------------------------- +This control is used to attenuate samples from left and right side PCM FX-bus +accumulators. ALSA uses accumulators 14 and 15 for left and right side PCM +samples for 7.1 playback. The result samples are forwarded to the DSP 6 & 7 +playback channels. + +name='PCM Center Playback Volume',index=0 +----------------------------------------- +This control is used to attenuate samples from the center PCM FX-bus accumulator. +ALSA uses accumulator 6 for center PCM samples for 5.1 playback. The result samples +are forwarded to the DSP 4 playback channel. + +name='PCM LFE Playback Volume',index=0 +-------------------------------------- +This control is used to attenuate samples from the LFE PCM FX-bus accumulator. +ALSA uses accumulator 7 for LFE PCM samples for 5.1 playback. The result samples +are forwarded to the DSP 5 playback channel. + +name='PCM Playback Volume',index=0 +---------------------------------- +This control is used to attenuate samples from left and right PCM FX-bus +accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples for +stereo playback. The result samples are forwarded to the virtual stereo mixer. + +name='PCM Capture Volume',index=0 +--------------------------------- +This control is used to attenuate samples from left and right PCM FX-bus +accumulators. ALSA uses accumulators 0 and 1 for left and right PCM. +The result is forwarded to the standard capture PCM device. + +name='Music Playback Volume',index=0 +------------------------------------ +This control is used to attenuate samples from left and right MIDI FX-bus +accumulators. ALSA uses accumulators 4 and 5 for left and right MIDI samples. +The result samples are forwarded to the virtual stereo mixer. + +name='Music Capture Volume',index=0 +----------------------------------- +These controls are used to attenuate samples from left and right MIDI FX-bus +accumulator. ALSA uses accumulators 4 and 5 for left and right MIDI samples. +The result is forwarded to the standard capture PCM device. + +name='Front Playback Volume',index=0 +------------------------------------ +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the DSP 0 & 1 playback channels. + +name='Surround Playback Volume',index=0 +--------------------------------------- +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the DSP 2 & 3 playback channels. + +name='Side Playback Volume',index=0 +----------------------------------- +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the DSP 6 & 7 playback channels. + +name='Center Playback Volume',index=0 +------------------------------------- +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the DSP 4 playback channel. + +name='LFE Playback Volume',index=0 +---------------------------------- +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the DSP 5 playback channel. + +name='Tone Control - Switch',index=0 +------------------------------------ +This control turns the tone control on or off. The samples forwarded to +the DSP playback channels are affected. + +name='Tone Control - Bass',index=0 +---------------------------------- +This control sets the bass intensity. There is no neutral value!! +When the tone control code is activated, the samples are always modified. +The closest value to pure signal is 20. + +name='Tone Control - Treble',index=0 +------------------------------------ +This control sets the treble intensity. There is no neutral value!! +When the tone control code is activated, the samples are always modified. +The closest value to pure signal is 20. + +name='Master Playback Volume',index=0 +------------------------------------- +This control is used to attenuate samples for all DSP playback channels. + +name='EMU Capture Volume',index=0 +---------------------------------- +This control is used to attenuate samples from the DSP 0 & 1 capture channels. +The result is forwarded to the standard capture PCM device. + +name='DAC Left',index=0, etc. +----------------------------- +Select the source for the given physical audio output. These may be physical +inputs, playback channels (DSP xx, specified as a decimal number), or silence. + +name='DSP x',index=0 +-------------------- +Select the source for the given capture channel (specified as a hexadecimal +digit). Same options as for the physical audio outputs. + + +PCM stream related controls +=========================== + +These controls are described in audigy-mixer.rst. + + +MANUALS/PATENTS +=============== + +See sb-live-mixer.rst. diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst index 49c1f2f688f8..e68bbb13c384 100644 --- a/Documentation/sound/cards/index.rst +++ b/Documentation/sound/cards/index.rst @@ -8,6 +8,7 @@ Card-Specific Information cmipci sb-live-mixer audigy-mixer + emu-mixer emu10k1-jack via82xx-mixer audiophile-usb diff --git a/Documentation/sound/cards/sb-live-mixer.rst b/Documentation/sound/cards/sb-live-mixer.rst index 4dd9bfe01bd8..27667f58aae1 100644 --- a/Documentation/sound/cards/sb-live-mixer.rst +++ b/Documentation/sound/cards/sb-live-mixer.rst @@ -61,61 +61,61 @@ FX-bus ``name='Wave Playback Volume',index=0`` --------------------------------------- -This control is used to attenuate samples for left and right PCM FX-bus +This control is used to attenuate samples from left and right PCM FX-bus accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples. The result samples are forwarded to the front DAC PCM slots of the AC97 codec. ``name='Wave Surround Playback Volume',index=0`` ------------------------------------------------ -This control is used to attenuate samples for left and right PCM FX-bus +This control is used to attenuate samples from left and right PCM FX-bus accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples. The result samples are forwarded to the rear I2S DACs. These DACs operates separately (they are not inside the AC97 codec). ``name='Wave Center Playback Volume',index=0`` ---------------------------------------------- -This control is used to attenuate samples for left and right PCM FX-bus +This control is used to attenuate samples from left and right PCM FX-bus accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples. The result is mixed to mono signal (single channel) and forwarded to the ??rear?? right DAC PCM slot of the AC97 codec. ``name='Wave LFE Playback Volume',index=0`` ------------------------------------------- -This control is used to attenuate samples for left and right PCM FX-bus +This control is used to attenuate samples from left and right PCM FX-bus accumulators. ALSA uses accumulators 0 and 1 for left and right PCM. The result is mixed to mono signal (single channel) and forwarded to the ??rear?? left DAC PCM slot of the AC97 codec. ``name='Wave Capture Volume',index=0``, ``name='Wave Capture Switch',index=0`` ------------------------------------------------------------------------------ -These controls are used to attenuate samples for left and right PCM FX-bus +These controls are used to attenuate samples from left and right PCM FX-bus accumulator. ALSA uses accumulators 0 and 1 for left and right PCM. The result is forwarded to the ADC capture FIFO (thus to the standard capture PCM device). ``name='Synth Playback Volume',index=0`` ---------------------------------------- -This control is used to attenuate samples for left and right MIDI FX-bus +This control is used to attenuate samples from left and right MIDI FX-bus accumulators. ALSA uses accumulators 4 and 5 for left and right MIDI samples. The result samples are forwarded to the front DAC PCM slots of the AC97 codec. ``name='Synth Capture Volume',index=0``, ``name='Synth Capture Switch',index=0`` -------------------------------------------------------------------------------- -These controls are used to attenuate samples for left and right MIDI FX-bus -accumulator. ALSA uses accumulators 4 and 5 for left and right PCM. +These controls are used to attenuate samples from left and right MIDI FX-bus +accumulator. ALSA uses accumulators 4 and 5 for left and right MIDI samples. The result is forwarded to the ADC capture FIFO (thus to the standard capture PCM device). ``name='Surround Playback Volume',index=0`` ------------------------------------------- -This control is used to attenuate samples for left and right rear PCM FX-bus +This control is used to attenuate samples from left and right rear PCM FX-bus accumulators. ALSA uses accumulators 2 and 3 for left and right rear PCM samples. The result samples are forwarded to the rear I2S DACs. These DACs operate separately (they are not inside the AC97 codec). ``name='Surround Capture Volume',index=0``, ``name='Surround Capture Switch',index=0`` -------------------------------------------------------------------------------------- -These controls are used to attenuate samples for left and right rear PCM FX-bus +These controls are used to attenuate samples from left and right rear PCM FX-bus accumulators. ALSA uses accumulators 2 and 3 for left and right rear PCM samples. The result is forwarded to the ADC capture FIFO (thus to the standard capture PCM device). @@ -134,7 +134,7 @@ to the ??rear?? left DAC PCM slot of the AC97 codec. ``name='AC97 Playback Volume',index=0`` --------------------------------------- -This control is used to attenuate samples for left and right front ADC PCM slots +This control is used to attenuate samples from left and right front ADC PCM slots of the AC97 codec. The result samples are forwarded to the front DAC PCM slots of the AC97 codec. @@ -145,7 +145,7 @@ slots of the AC97 codec. ``name='AC97 Capture Volume',index=0`` -------------------------------------- -This control is used to attenuate samples for left and right front ADC PCM slots +This control is used to attenuate samples from left and right front ADC PCM slots of the AC97 codec. The result is forwarded to the ADC capture FIFO (thus to the standard capture PCM device). diff --git a/Documentation/sound/designs/midi-2.0.rst b/Documentation/sound/designs/midi-2.0.rst index 27d0d3dea1b0..086487ca7ab1 100644 --- a/Documentation/sound/designs/midi-2.0.rst +++ b/Documentation/sound/designs/midi-2.0.rst @@ -74,8 +74,8 @@ topology based on those information. When the device is older and doesn't respond to the new UMP inquiries, the driver falls back and builds the topology based on Group Terminal Block (GTB) information from the USB descriptor. Some device might be screwed up by the -unexpected UMP command; in such a case, pass `midi2_probe=0` option to -snd-usb-audio driver for skipping the UMP v1.1 inquiries. +unexpected UMP command; in such a case, pass `midi2_ump_probe=0` +option to snd-usb-audio driver for skipping the UMP v1.1 inquiries. When the MIDI 2.0 device is probed, the kernel creates a rawmidi device for each UMP Endpoint of the device. Its device name is @@ -376,3 +376,191 @@ Sequencer API Extensions name and attributes accordingly, and notifies the changes via the announcement to the ALSA sequencer system port, similarly like the normal port change notification. + + +MIDI2 USB Gadget Function Driver +================================ + +The latest kernel contains the support for USB MIDI 2.0 gadget +function driver, which can be used for prototyping and debugging MIDI +2.0 features. + +`CONFIG_USB_GADGET`, `CONFIG_USB_CONFIGFS` and +`CONFIG_USB_CONFIGFS_F_MIDI2` need to be enabled for the MIDI2 gadget +driver. + +In addition, for using a gadget driver, you need a working UDC driver. +In the example below, we use `dummy_hcd` driver (enabled via +`CONFIG_USB_DUMMY_HCD`) that is available on PC and VM for debugging +purpose. There are other UDC drivers depending on the platform, and +those can be used for a real device, instead, too. + +At first, on a system to run the gadget, load `libcomposite` module:: + + % modprobe libcomposite + +and you'll have `usb_gadget` subdirectory under configfs space +(typically `/sys/kernel/config` on modern OS). Then create a gadget +instance and add configurations there, for example:: + + % cd /sys/kernel/config + % mkdir usb_gadget/g1 + + % cd usb_gadget/g1 + % mkdir configs/c.1 + % mkdir functions/midi2.usb0 + + % echo 0x0004 > idProduct + % echo 0x17b3 > idVendor + % mkdir strings/0x409 + % echo "ACME Enterprises" > strings/0x409/manufacturer + % echo "ACMESynth" > strings/0x409/product + % echo "ABCD12345" > strings/0x409/serialnumber + + % mkdir configs/c.1/strings/0x409 + % echo "Monosynth" > configs/c.1/strings/0x409/configuration + % echo 120 > configs/c.1/MaxPower + +At this point, there must be a subdirectory `ep.0`, and that is the +configuration for a UMP Endpoint. You can fill the Endpoint +information like:: + + % echo "ACMESynth" > functions/midi2.usb0/iface_name + % echo "ACMESynth" > functions/midi2.usb0/ep.0/ep_name + % echo "ABCD12345" > functions/midi2.usb0/ep.0/product_id + % echo 0x0123 > functions/midi2.usb0/ep.0/family + % echo 0x4567 > functions/midi2.usb0/ep.0/model + % echo 0x123456 > functions/midi2.usb0/ep.0/manufacturer + % echo 0x12345678 > functions/midi2.usb0/ep.0/sw_revision + +The default MIDI protocol can be set either 1 or 2:: + + % echo 2 > functions/midi2.usb0/ep.0/protocol + +And, you can find a subdirectory `block.0` under this Endpoint +subdirectory. This defines the Function Block information:: + + % echo "Monosynth" > functions/midi2.usb0/ep.0/block.0/name + % echo 0 > functions/midi2.usb0/ep.0/block.0/first_group + % echo 1 > functions/midi2.usb0/ep.0/block.0/num_groups + +Finally, link the configuration and enable it:: + + % ln -s functions/midi2.usb0 configs/c.1 + % echo dummy_udc.0 > UDC + +where `dummy_udc.0` is an example case and it differs depending on the +system. You can find the UDC instances in `/sys/class/udc` and pass +the found name instead:: + + % ls /sys/class/udc + dummy_udc.0 + +Now, the MIDI 2.0 gadget device is enabled, and the gadget host +creates a new sound card instance containing a UMP rawmidi device by +`f_midi2` driver:: + + % cat /proc/asound/cards + .... + 1 [Gadget ]: f_midi2 - MIDI 2.0 Gadget + MIDI 2.0 Gadget + +And on the connected host, a similar card should appear, too, but with +the card and device names given in the configfs above:: + + % cat /proc/asound/cards + .... + 2 [ACMESynth ]: USB-Audio - ACMESynth + ACME Enterprises ACMESynth at usb-dummy_hcd.0-1, high speed + +You can play a MIDI file on the gadget side:: + + % aplaymidi -p 20:1 to_host.mid + +and this will appear as an input from a MIDI device on the connected +host:: + + % aseqdump -p 20:0 -u 2 + +Vice versa, a playback on the connected host will work as an input on +the gadget, too. + +Each Function Block may have different direction and UI-hint, +specified via `direction` and `ui_hint` attributes. +Passing `1` is for input-only, `2` for out-only and `3` for +bidirectional (the default value). For example:: + + % echo 2 > functions/midi2.usb0/ep.0/block.0/direction + % echo 2 > functions/midi2.usb0/ep.0/block.0/ui_hint + +When you need more than one Function Blocks, you can create +subdirectories `block.1`, `block.2`, etc dynamically, and configure +them in the configuration procedure above before linking. +For example, to create a second Function Block for a keyboard:: + + % mkdir functions/midi2.usb0/ep.0/block.1 + % echo "Keyboard" > functions/midi2.usb0/ep.0/block.1/name + % echo 1 > functions/midi2.usb0/ep.0/block.1/first_group + % echo 1 > functions/midi2.usb0/ep.0/block.1/num_groups + % echo 1 > functions/midi2.usb0/ep.0/block.1/direction + % echo 1 > functions/midi2.usb0/ep.0/block.1/ui_hint + +The `block.*` subdirectories can be removed dynamically, too (except +for `block.0` which is persistent). + +For assigning a Function Block for MIDI 1.0 I/O, set up in `is_midi1` +attribute. 1 is for MIDI 1.0, and 2 is for MIDI 1.0 with low speed +connection:: + + % echo 2 > functions/midi2.usb0/ep.0/block.1/is_midi1 + +For disabling the processing of UMP Stream messages in the gadget +driver, pass `0` to `process_ump` attribute in the top-level config:: + + % echo 0 > functions/midi2.usb0/process_ump + +The MIDI 1.0 interface at altset 0 is supported by the gadget driver, +too. When MIDI 1.0 interface is selected by the connected host, the +UMP I/O on the gadget is translated from/to USB MIDI 1.0 packets +accordingly while the gadget driver keeps communicating with the +user-space over UMP rawmidi. + +MIDI 1.0 ports are set up from the config in each Function Block. +For example:: + + % echo 0 > functions/midi2.usb0/ep.0/block.0/midi1_first_group + % echo 1 > functions/midi2.usb0/ep.0/block.0/midi1_num_groups + +The configuration above will enable the Group 1 (the index 0) for MIDI +1.0 interface. Note that those groups must be in the groups defined +for the Function Block itself. + +The gadget driver supports more than one UMP Endpoints, too. +Similarly like the Function Blocks, you can create a new subdirectory +`ep.1` (but under the card top-level config) to enable a new Endpoint:: + + % mkdir functions/midi2.usb0/ep.1 + +and create a new Function Block there. For example, to create 4 +Groups for the Function Block of this new Endpoint:: + + % mkdir functions/midi2.usb0/ep.1/block.0 + % echo 4 > functions/midi2.usb0/ep.1/block.0/num_groups + +Now, you'll have 4 rawmidi devices in total: the first two are UMP +rawmidi devices for Endpoint 0 and Endpoint 1, and other two for the +legacy MIDI 1.0 rawmidi devices corresponding to both EP 0 and EP 1. + +The current altsetting on the gadget can be informed via a control +element "Operation Mode" with `RAWMIDI` iface. e.g. you can read it +via `amixer` program running on the gadget host like:: + + % amixer -c1 cget iface=RAWMIDI,name='Operation Mode' + ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0 + : values=2 + +The value (shown in the second returned line with `: values=`) +indicates 1 for MIDI 1.0 (altset 0), 2 for MIDI 2.0 (altset 1) and 0 +for unset. + +As of now, the configurations can't be changed after binding. diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index 4335c98b3d82..cd421856409e 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -2018,8 +2018,8 @@ sleeping poll threads, etc. This callback is also atomic by default. -copy_user, copy_kernel and fill_silence ops -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +copy and fill_silence ops +~~~~~~~~~~~~~~~~~~~~~~~~~ These callbacks are not mandatory, and can be omitted in most cases. These callbacks are used when the hardware buffer cannot be in the @@ -3444,8 +3444,8 @@ external hardware buffer in interrupts (or in tasklets, preferably). The first case works fine if the external hardware buffer is large enough. This method doesn't need any extra buffers and thus is more -efficient. You need to define the ``copy_user`` and ``copy_kernel`` -callbacks for the data transfer, in addition to the ``fill_silence`` +efficient. You need to define the ``copy`` callback +for the data transfer, in addition to the ``fill_silence`` callback for playback. However, there is a drawback: it cannot be mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM. @@ -3458,22 +3458,22 @@ Another case is when the chip uses a PCI memory-map region for the buffer instead of the host memory. In this case, mmap is available only on certain architectures like the Intel one. In non-mmap mode, the data cannot be transferred as in the normal way. Thus you need to define the -``copy_user``, ``copy_kernel`` and ``fill_silence`` callbacks as well, +``copy`` and ``fill_silence`` callbacks as well, as in the cases above. Examples are found in ``rme32.c`` and ``rme96.c``. -The implementation of the ``copy_user``, ``copy_kernel`` and +The implementation of the ``copy`` and ``silence`` callbacks depends upon whether the hardware supports -interleaved or non-interleaved samples. The ``copy_user`` callback is +interleaved or non-interleaved samples. The ``copy`` callback is defined like below, a bit differently depending on whether the direction is playback or capture:: - static int playback_copy_user(struct snd_pcm_substream *substream, + static int playback_copy(struct snd_pcm_substream *substream, int channel, unsigned long pos, - void __user *src, unsigned long count); - static int capture_copy_user(struct snd_pcm_substream *substream, + struct iov_iter *src, unsigned long count); + static int capture_copy(struct snd_pcm_substream *substream, int channel, unsigned long pos, - void __user *dst, unsigned long count); + struct iov_iter *dst, unsigned long count); In the case of interleaved samples, the second argument (``channel``) is not used. The third argument (``pos``) specifies the position in bytes. @@ -3490,18 +3490,17 @@ of data (``count``) at the specified pointer (``src``) to the specified offset (``pos``) in the hardware buffer. When coded like memcpy-like way, the copy would look like:: - my_memcpy_from_user(my_buffer + pos, src, count); + my_memcpy_from_iter(my_buffer + pos, src, count); For the capture direction, you copy the given amount of data (``count``) at the specified offset (``pos``) in the hardware buffer to the specified pointer (``dst``):: - my_memcpy_to_user(dst, my_buffer + pos, count); + my_memcpy_to_iter(dst, my_buffer + pos, count); -Here the functions are named ``from_user`` and ``to_user`` because -it's the user-space buffer that is passed to these callbacks. That -is, the callback is supposed to copy data from/to the user-space -directly to/from the hardware buffer. +The given ``src`` or ``dst`` a struct iov_iter pointer containing the +pointer and the size. Use the existing helpers to copy or access the +data as defined in ``linux/uio.h``. Careful readers might notice that these callbacks receive the arguments in bytes, not in frames like other callbacks. It's because @@ -3519,25 +3518,6 @@ the given user-space buffer, but only for the given channel. For details, please check ``isa/gus/gus_pcm.c`` or ``pci/rme9652/rme9652.c`` as examples. -The above callbacks are the copies from/to the user-space buffer. There -are some cases where we want to copy from/to the kernel-space buffer -instead. In such a case, the ``copy_kernel`` callback is called. It'd -look like:: - - static int playback_copy_kernel(struct snd_pcm_substream *substream, - int channel, unsigned long pos, - void *src, unsigned long count); - static int capture_copy_kernel(struct snd_pcm_substream *substream, - int channel, unsigned long pos, - void *dst, unsigned long count); - -As found easily, the only difference is that the buffer pointer is -without a ``__user`` prefix; that is, a kernel-buffer pointer is passed -in the fourth argument. Correspondingly, the implementation would be -a version without the user-copy, such as:: - - my_memcpy(my_buffer + pos, src, count); - Usually for the playback, another callback ``fill_silence`` is defined. It's implemented in a similar way as the copy callbacks above:: @@ -3545,10 +3525,10 @@ above:: static int silence(struct snd_pcm_substream *substream, int channel, unsigned long pos, unsigned long count); -The meanings of arguments are the same as in the ``copy_user`` and -``copy_kernel`` callbacks, although there is no buffer pointer +The meanings of arguments are the same as in the ``copy`` callback, +although there is no buffer pointer argument. In the case of interleaved samples, the channel argument has -no meaning, as for the ``copy_*`` callbacks. +no meaning, as for the ``copy`` callback. The role of the ``fill_silence`` callback is to set the given amount (``count``) of silence data at the specified offset (``pos``) in the diff --git a/Documentation/sound/soc/codec-to-codec.rst b/Documentation/sound/soc/codec-to-codec.rst index 4eaa9a0c41fc..0418521b6e03 100644 --- a/Documentation/sound/soc/codec-to-codec.rst +++ b/Documentation/sound/soc/codec-to-codec.rst @@ -70,7 +70,8 @@ file: .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF | SND_SOC_DAIFMT_CBM_CFM, .ignore_suspend = 1, - .params = &dsp_codec_params, + .c2c_params = &dsp_codec_params, + .num_c2c_params = 1, }, { .name = "DSP-CODEC", @@ -81,12 +82,13 @@ file: .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF | SND_SOC_DAIFMT_CBM_CFM, .ignore_suspend = 1, - .params = &dsp_codec_params, + .c2c_params = &dsp_codec_params, + .num_c2c_params = 1, }, Above code snippet is motivated from sound/soc/samsung/speyside.c. -Note the "params" callback which lets the dapm know that this +Note the "c2c_params" callback which lets the dapm know that this dai_link is a codec to codec connection. In dapm core a route is created between cpu_dai playback widget diff --git a/Documentation/sound/soc/dpcm.rst b/Documentation/sound/soc/dpcm.rst index 77f67ded53de..2d7ad1d91504 100644 --- a/Documentation/sound/soc/dpcm.rst +++ b/Documentation/sound/soc/dpcm.rst @@ -368,7 +368,8 @@ The machine driver sets some additional parameters to the DAI link i.e. .codec_name = "modem", .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF | SND_SOC_DAIFMT_CBM_CFM, - .params = &dai_params, + .c2c_params = &dai_params, + .num_c2c_params = 1, } < ... more DAI links here ... > diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py index ca8ac9e59ded..4eb150bf509c 100644 --- a/Documentation/sphinx/cdomain.py +++ b/Documentation/sphinx/cdomain.py @@ -93,7 +93,7 @@ def markup_ctype_refs(match): # RE_expr = re.compile(r':c:(expr|texpr):`([^\`]+)`') def markup_c_expr(match): - return '\ ``' + match.group(2) + '``\ ' + return '\\ ``' + match.group(2) + '``\\ ' # # Parse Sphinx 3.x C markups, replacing them by backward-compatible ones @@ -151,7 +151,7 @@ class CObject(Base_CObject): def handle_func_like_macro(self, sig, signode): u"""Handles signatures of function-like macros. - If the objtype is 'function' and the the signature ``sig`` is a + If the objtype is 'function' and the signature ``sig`` is a function-like macro, the name of the macro is returned. Otherwise ``False`` is returned. """ @@ -178,7 +178,7 @@ class CObject(Base_CObject): if len(arglist[0].split(" ")) > 1: return False - # This is a function-like macro, it's arguments are typeless! + # This is a function-like macro, its arguments are typeless! signode += addnodes.desc_name(fullname, fullname) paramlist = addnodes.desc_parameterlist() signode += paramlist diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py index b5feb5b1d905..49797c55479c 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -138,7 +138,7 @@ class KernelCmd(Directive): code_block += "\n " + l lines = code_block + "\n\n" - line_regex = re.compile("^\.\. LINENO (\S+)\#([0-9]+)$") + line_regex = re.compile(r"^\.\. LINENO (\S+)\#([0-9]+)$") ln = 0 n = 0 f = fname diff --git a/Documentation/sphinx/kernel_feat.py b/Documentation/sphinx/kernel_feat.py index 27b701ed3681..b5fa2f0542a5 100644 --- a/Documentation/sphinx/kernel_feat.py +++ b/Documentation/sphinx/kernel_feat.py @@ -104,7 +104,7 @@ class KernelFeat(Directive): lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env) - line_regex = re.compile("^\.\. FILE (\S+)$") + line_regex = re.compile(r"^\.\. FILE (\S+)$") out_lines = "" diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 9395892c7ba3..7acf09963daa 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -130,7 +130,7 @@ class KernelDocDirective(Directive): result = ViewList() lineoffset = 0; - line_regex = re.compile("^\.\. LINENO ([0-9]+)$") + line_regex = re.compile(r"^\.\. LINENO ([0-9]+)$") for line in lines: match = line_regex.search(line) if match: @@ -138,7 +138,7 @@ class KernelDocDirective(Directive): lineoffset = int(match.group(1)) - 1 # we must eat our comments since the upset the markup else: - doc = env.srcdir + "/" + env.docname + ":" + str(self.lineno) + doc = str(env.srcdir) + "/" + env.docname + ":" + str(self.lineno) result.append(line, doc + ": " + filename, lineoffset) lineoffset += 1 diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py index cefdbb7e7523..13e885bbd499 100644 --- a/Documentation/sphinx/kfigure.py +++ b/Documentation/sphinx/kfigure.py @@ -309,7 +309,7 @@ def convert_image(img_node, translator, src_fname=None): if dst_fname: # the builder needs not to copy one more time, so pop it if exists. translator.builder.images.pop(img_node['uri'], None) - _name = dst_fname[len(translator.builder.outdir) + 1:] + _name = dst_fname[len(str(translator.builder.outdir)) + 1:] if isNewer(dst_fname, src_fname): kernellog.verbose(app, diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py index 328b3631a585..dcad0fff4723 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -77,7 +77,7 @@ class MaintainersInclude(Include): line = line.rstrip() # Linkify all non-wildcard refs to ReST files in Documentation/. - pat = '(Documentation/([^\s\?\*]*)\.rst)' + pat = r'(Documentation/([^\s\?\*]*)\.rst)' m = re.search(pat, line) if m: # maintainers.rst is in a subdirectory, so include "../". @@ -90,11 +90,11 @@ class MaintainersInclude(Include): output = "| %s" % (line.replace("\\", "\\\\")) # Look for and record field letter to field name mappings: # R: Designated *reviewer*: FullName <address@domain> - m = re.search("\s(\S):\s", line) + m = re.search(r"\s(\S):\s", line) if m: field_letter = m.group(1) if field_letter and not field_letter in fields: - m = re.search("\*([^\*]+)\*", line) + m = re.search(r"\*([^\*]+)\*", line) if m: fields[field_letter] = m.group(1) elif subsystems: @@ -112,7 +112,7 @@ class MaintainersInclude(Include): field_content = "" # Collapse whitespace in subsystem name. - heading = re.sub("\s+", " ", line) + heading = re.sub(r"\s+", " ", line) output = output + "%s\n%s" % (heading, "~" * len(heading)) field_prev = "" else: diff --git a/Documentation/spi/spi-lm70llp.rst b/Documentation/spi/spi-lm70llp.rst index 0144e12d95bb..2f20e5b405e6 100644 --- a/Documentation/spi/spi-lm70llp.rst +++ b/Documentation/spi/spi-lm70llp.rst @@ -69,7 +69,7 @@ Interpreting this circuit, when the LM70 SI/O line is High (or tristate and not grounded by the host via D7), the transistor conducts and switches the collector to zero, which is reflected on pin 13 of the DB25 parport connector. When SI/O is Low (driven by the LM70 or the host) on the other -hand, the transistor is cut off and the voltage tied to it's collector is +hand, the transistor is cut off and the voltage tied to its collector is reflected on pin 13 as a High level. So: the getmiso inline routine in this driver takes this fact into account, diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst index b67a1b65855b..930dc23998a0 100644 --- a/Documentation/subsystem-apis.rst +++ b/Documentation/subsystem-apis.rst @@ -10,6 +10,20 @@ is taken directly from the kernel source, with supplemental material added as needed (or at least as we managed to add it — probably *not* all that is needed). +Core subsystems +--------------- + +.. toctree:: + :maxdepth: 1 + + core-api/index + driver-api/index + mm/index + power/index + scheduler/index + timers/index + locking/index + Human interfaces ---------------- @@ -21,6 +35,19 @@ Human interfaces sound/index gpu/index fb/index + leds/index + +Networking interfaces +--------------------- + +.. toctree:: + :maxdepth: 1 + + networking/index + netlabel/index + infiniband/index + isdn/index + mhi/index Storage interfaces ------------------ @@ -39,22 +66,12 @@ Storage interfaces .. toctree:: :maxdepth: 1 - driver-api/index - core-api/index - locking/index accounting/index cpu-freq/index fpga/index i2c/index iio/index - isdn/index - infiniband/index - leds/index - netlabel/index - networking/index pcmcia/index - power/index - timers/index spi/index w1/index watchdog/index @@ -63,12 +80,9 @@ Storage interfaces accel/index security/index crypto/index - mm/index bpf/index usb/index PCI/index misc-devices/index - scheduler/index - mhi/index peci/index wmi/index diff --git a/Documentation/tools/rtla/rtla-timerlat-hist.rst b/Documentation/tools/rtla/rtla-timerlat-hist.rst index 057db78d4095..03b7f3deb069 100644 --- a/Documentation/tools/rtla/rtla-timerlat-hist.rst +++ b/Documentation/tools/rtla/rtla-timerlat-hist.rst @@ -36,11 +36,11 @@ EXAMPLE In the example below, **rtla timerlat hist** is set to run for *10* minutes, in the cpus *0-4*, *skipping zero* only lines. Moreover, **rtla timerlat hist** will change the priority of the *timerlat* threads to run under -*SCHED_DEADLINE* priority, with a *10us* runtime every *1ms* period. The +*SCHED_DEADLINE* priority, with a *100us* runtime every *1ms* period. The *1ms* period is also passed to the *timerlat* tracer. Auto-analysis is disabled to reduce overhead :: - [root@alien ~]# timerlat hist -d 10m -c 0-4 -P d:100us:1ms -p 1ms --no-aa + [root@alien ~]# timerlat hist -d 10m -c 0-4 -P d:100us:1ms -p 1000 --no-aa # RTLA timerlat histogram # Time unit is microseconds (us) # Duration: 0 00:10:00 diff --git a/Documentation/tools/rtla/rtla-timerlat-top.rst b/Documentation/tools/rtla/rtla-timerlat-top.rst index 1b7cf4e3eafe..ab6cb60c9083 100644 --- a/Documentation/tools/rtla/rtla-timerlat-top.rst +++ b/Documentation/tools/rtla/rtla-timerlat-top.rst @@ -117,7 +117,7 @@ syscall in a btrfs file system. The raw trace is saved in the **timerlat_trace.txt** file for further analysis. Note that **rtla timerlat** was dispatched without changing *timerlat* tracer -threads' priority. That is generally not needed because these threads hava +threads' priority. That is generally not needed because these threads have priority *FIFO:95* by default, which is a common priority used by real-time kernel developers to analyze scheduling delays. diff --git a/Documentation/trace/coresight/coresight-etm4x-reference.rst b/Documentation/trace/coresight/coresight-etm4x-reference.rst index 70e34b8c81c1..89ac4e6fc96f 100644 --- a/Documentation/trace/coresight/coresight-etm4x-reference.rst +++ b/Documentation/trace/coresight/coresight-etm4x-reference.rst @@ -675,7 +675,7 @@ Bit assignments shown below:- reconstructed using only conditional branches. There is currently no support in Perf for supplying modified binaries to the decoder, so this - feature is only inteded to be used for debugging purposes or with a 3rd party tool. + feature is only intended to be used for debugging purposes or with a 3rd party tool. Choosing this option will result in a significant increase in the amount of trace generated - possible danger of overflows, or fewer instructions covered. Note, that this option also diff --git a/Documentation/trace/events.rst b/Documentation/trace/events.rst index f5fcb8e1218f..759907c20e75 100644 --- a/Documentation/trace/events.rst +++ b/Documentation/trace/events.rst @@ -219,6 +219,20 @@ the function "security_prepare_creds" and less than the end of that function. The ".function" postfix can only be attached to values of size long, and can only be compared with "==" or "!=". +Cpumask fields or scalar fields that encode a CPU number can be filtered using +a user-provided cpumask in cpulist format. The format is as follows:: + + CPUS{$cpulist} + +Operators available to cpumask filtering are: + +& (intersection), ==, != + +For example, this will filter events that have their .target_cpu field present +in the given cpumask:: + + target_cpu & CPUS{17-42} + 5.2 Setting filters ------------------- @@ -915,7 +929,7 @@ functions can be used. To create a kprobe event, an empty or partially empty kprobe event should first be created using kprobe_event_gen_cmd_start(). The name -of the event and the probe location should be specfied along with one +of the event and the probe location should be specified along with one or args each representing a probe field should be supplied to this function. Before calling kprobe_event_gen_cmd_start(), the user should create and initialize a dynevent_cmd object using @@ -995,7 +1009,7 @@ The basic idea is simple and amounts to providing a general-purpose layer that can be used to generate trace event commands. The generated command strings can then be passed to the command-parsing and event creation code that already exists in the trace event -subystem for creating the corresponding trace events. +subsystem for creating the corresponding trace events. In a nutshell, the way it works is that the higher-level interface code creates a struct dynevent_cmd object, then uses a couple @@ -1068,7 +1082,7 @@ to add an operator between the pair (here none) and a separator to be appended onto the end of the arg pair (here ';'). There's also a dynevent_str_add() function that can be used to simply -add a string as-is, with no spaces, delimeters, or arg check. +add a string as-is, with no spaces, delimiters, or arg check. Any number of dynevent_*_add() calls can be made to build up the string (until its length surpasses cmd->maxlen). When all the arguments have diff --git a/Documentation/trace/fprobe.rst b/Documentation/trace/fprobe.rst index 40dd2fbce861..196f52386aaa 100644 --- a/Documentation/trace/fprobe.rst +++ b/Documentation/trace/fprobe.rst @@ -91,9 +91,9 @@ The prototype of the entry/exit callback function are as follows: .. code-block:: c - int entry_callback(struct fprobe *fp, unsigned long entry_ip, struct pt_regs *regs, void *entry_data); + int entry_callback(struct fprobe *fp, unsigned long entry_ip, unsigned long ret_ip, struct pt_regs *regs, void *entry_data); - void exit_callback(struct fprobe *fp, unsigned long entry_ip, struct pt_regs *regs, void *entry_data); + void exit_callback(struct fprobe *fp, unsigned long entry_ip, unsigned long ret_ip, struct pt_regs *regs, void *entry_data); Note that the @entry_ip is saved at function entry and passed to exit handler. If the entry callback function returns !0, the corresponding exit callback will be cancelled. @@ -108,12 +108,16 @@ If the entry callback function returns !0, the corresponding exit callback will Note that this may not be the actual entry address of the function but the address where the ftrace is instrumented. +@ret_ip + This is the return address that the traced function will return to, + somewhere in the caller. This can be used at both entry and exit. + @regs This is the `pt_regs` data structure at the entry and exit. Note that the instruction pointer of @regs may be different from the @entry_ip in the entry_handler. If you need traced instruction pointer, you need to use @entry_ip. On the other hand, in the exit_handler, the instruction - pointer of @regs is set to the currect return address. + pointer of @regs is set to the current return address. @entry_data This is a local storage to share the data between entry and exit handlers. diff --git a/Documentation/trace/fprobetrace.rst b/Documentation/trace/fprobetrace.rst index 7297f9478459..8e9bebcf0a2e 100644 --- a/Documentation/trace/fprobetrace.rst +++ b/Documentation/trace/fprobetrace.rst @@ -79,9 +79,9 @@ automatically set by the given name. :: f:fprobes/myprobe vfs_read count=count pos=pos It also chooses the fetch type from BTF information. For example, in the above -example, the ``count`` is unsigned long, and the ``pos`` is a pointer. Thus, both -are converted to 64bit unsigned long, but only ``pos`` has "%Lx" print-format as -below :: +example, the ``count`` is unsigned long, and the ``pos`` is a pointer. Thus, +both are converted to 64bit unsigned long, but only ``pos`` has "%Lx" +print-format as below :: # cat events/fprobes/myprobe/format name: myprobe @@ -105,9 +105,47 @@ is expanded to all function arguments of the function or the tracepoint. :: # cat dynamic_events f:fprobes/myprobe vfs_read file=file buf=buf count=count pos=pos -BTF also affects the ``$retval``. If user doesn't set any type, the retval type is -automatically picked from the BTF. If the function returns ``void``, ``$retval`` -is rejected. +BTF also affects the ``$retval``. If user doesn't set any type, the retval +type is automatically picked from the BTF. If the function returns ``void``, +``$retval`` is rejected. + +You can access the data fields of a data structure using allow operator ``->`` +(for pointer type) and dot operator ``.`` (for data structure type.):: + +# echo 't sched_switch preempt prev_pid=prev->pid next_pid=next->pid' >> dynamic_events + +The field access operators, ``->`` and ``.`` can be combined for accessing deeper +members and other structure members pointed by the member. e.g. ``foo->bar.baz->qux`` +If there is non-name union member, you can directly access it as the C code does. +For example:: + + struct { + union { + int a; + int b; + }; + } *foo; + +To access ``a`` and ``b``, use ``foo->a`` and ``foo->b`` in this case. + +This data field access is available for the return value via ``$retval``, +e.g. ``$retval->name``. + +For these BTF arguments and fields, ``:string`` and ``:ustring`` change the +behavior. If these are used for BTF argument or field, it checks whether +the BTF type of the argument or the data field is ``char *`` or ``char []``, +or not. If not, it rejects applying the string types. Also, with the BTF +support, you don't need a memory dereference operator (``+0(PTR)``) for +accessing the string pointed by a ``PTR``. It automatically adds the memory +dereference operator according to the BTF type. e.g. :: + +# echo 't sched_switch prev->comm:string' >> dynamic_events +# echo 'f getname_flags%return $retval->name:string' >> dynamic_events + +The ``prev->comm`` is an embedded char array in the data structure, and +``$retval->name`` is a char pointer in the data structure. But in both +cases, you can use ``:string`` type to get the string. + Usage examples -------------- @@ -161,10 +199,10 @@ parameters. This means you can access any field values in the task structure pointed by the ``prev`` and ``next`` arguments. For example, usually ``task_struct::start_time`` is not traced, but with this -traceprobe event, you can trace it as below. +traceprobe event, you can trace that field as below. :: - # echo 't sched_switch comm=+1896(next):string start_time=+1728(next):u64' > dynamic_events + # echo 't sched_switch comm=next->comm:string next->start_time' > dynamic_events # head -n 20 trace | tail # TASK-PID CPU# ||||| TIMESTAMP FUNCTION # | | | ||||| | | @@ -176,13 +214,3 @@ traceprobe event, you can trace it as below. <idle>-0 [000] d..3. 5606.690317: sched_switch: (__probestub_sched_switch+0x4/0x10) comm="kworker/0:1" usage=1 start_time=137000000 kworker/0:1-14 [000] d..3. 5606.690339: sched_switch: (__probestub_sched_switch+0x4/0x10) comm="swapper/0" usage=2 start_time=0 <idle>-0 [000] d..3. 5606.692368: sched_switch: (__probestub_sched_switch+0x4/0x10) comm="kworker/0:1" usage=1 start_time=137000000 - -Currently, to find the offset of a specific field in the data structure, -you need to build kernel with debuginfo and run `perf probe` command with -`-D` option. e.g. -:: - - # perf probe -D "__probestub_sched_switch next->comm:string next->start_time" - p:probe/__probestub_sched_switch __probestub_sched_switch+0 comm=+1896(%cx):string start_time=+1728(%cx):u64 - -And replace the ``%cx`` with the ``next``. diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index f606c5bd1c0d..23572f6697c0 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -2725,7 +2725,7 @@ It is default disabled. The return value of each traced function can be displayed after an equal sign "=". When encountering system call failures, it -can be verfy helpful to quickly locate the function that first +can be very helpful to quickly locate the function that first returns an error code. - hide: echo nofuncgraph-retval > trace_options diff --git a/Documentation/trace/hwlat_detector.rst b/Documentation/trace/hwlat_detector.rst index de94b499b0bc..11b749c2a8bd 100644 --- a/Documentation/trace/hwlat_detector.rst +++ b/Documentation/trace/hwlat_detector.rst @@ -14,7 +14,7 @@ originally written for use by the "RT" patch since the Real Time kernel is highly latency sensitive. SMIs are not serviced by the Linux kernel, which means that it does not -even know that they are occuring. SMIs are instead set up by BIOS code +even know that they are occurring. SMIs are instead set up by BIOS code and are serviced by BIOS code, usually for "critical" events such as management of thermal sensors and fans. Sometimes though, SMIs are used for other tasks and those tasks can spend an inordinate amount of time in the diff --git a/Documentation/trace/kprobes.rst b/Documentation/trace/kprobes.rst index fc7ce76eab65..f825970a1495 100644 --- a/Documentation/trace/kprobes.rst +++ b/Documentation/trace/kprobes.rst @@ -315,7 +315,6 @@ architectures: - i386 (Supports jump optimization) - x86_64 (AMD-64, EM64T) (Supports jump optimization) - ppc64 -- ia64 (Does not support probes on instruction slot1.) - sparc64 (Return probes not yet implemented.) - arm - ppc diff --git a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl index e24c009789a0..048dc0dbce64 100644 --- a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl +++ b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl @@ -107,14 +107,14 @@ GetOptions( ); # Defaults for dynamically discovered regex's -my $regex_direct_begin_default = 'order=([0-9]*) may_writepage=([0-9]*) gfp_flags=([A-Z_|]*)'; +my $regex_direct_begin_default = 'order=([0-9]*) gfp_flags=([A-Z_|]*)'; my $regex_direct_end_default = 'nr_reclaimed=([0-9]*)'; my $regex_kswapd_wake_default = 'nid=([0-9]*) order=([0-9]*)'; my $regex_kswapd_sleep_default = 'nid=([0-9]*)'; -my $regex_wakeup_kswapd_default = 'nid=([0-9]*) zid=([0-9]*) order=([0-9]*) gfp_flags=([A-Z_|]*)'; -my $regex_lru_isolate_default = 'isolate_mode=([0-9]*) classzone_idx=([0-9]*) order=([0-9]*) nr_requested=([0-9]*) nr_scanned=([0-9]*) nr_skipped=([0-9]*) nr_taken=([0-9]*) lru=([a-z_]*)'; +my $regex_wakeup_kswapd_default = 'nid=([0-9]*) order=([0-9]*) gfp_flags=([A-Z_|]*)'; +my $regex_lru_isolate_default = 'classzone=([0-9]*) order=([0-9]*) nr_requested=([0-9]*) nr_scanned=([0-9]*) nr_skipped=([0-9]*) nr_taken=([0-9]*) lru=([a-z_]*)'; my $regex_lru_shrink_inactive_default = 'nid=([0-9]*) nr_scanned=([0-9]*) nr_reclaimed=([0-9]*) nr_dirty=([0-9]*) nr_writeback=([0-9]*) nr_congested=([0-9]*) nr_immediate=([0-9]*) nr_activate_anon=([0-9]*) nr_activate_file=([0-9]*) nr_ref_keep=([0-9]*) nr_unmap_fail=([0-9]*) priority=([0-9]*) flags=([A-Z_|]*)'; -my $regex_lru_shrink_active_default = 'lru=([A-Z_]*) nr_scanned=([0-9]*) nr_rotated=([0-9]*) priority=([0-9]*)'; +my $regex_lru_shrink_active_default = 'lru=([A-Z_]*) nr_taken=([0-9]*) nr_active=([0-9]*) nr_deactivated=([0-9]*) nr_referenced=([0-9]*) priority=([0-9]*) flags=([A-Z_|]*)' ; my $regex_writepage_default = 'page=([0-9a-f]*) pfn=([0-9]*) flags=([A-Z_|]*)'; # Dyanically discovered regex @@ -184,8 +184,7 @@ sub generate_traceevent_regex { $regex_direct_begin = generate_traceevent_regex( "vmscan/mm_vmscan_direct_reclaim_begin", $regex_direct_begin_default, - "order", "may_writepage", - "gfp_flags"); + "order", "gfp_flags"); $regex_direct_end = generate_traceevent_regex( "vmscan/mm_vmscan_direct_reclaim_end", $regex_direct_end_default, @@ -201,11 +200,11 @@ $regex_kswapd_sleep = generate_traceevent_regex( $regex_wakeup_kswapd = generate_traceevent_regex( "vmscan/mm_vmscan_wakeup_kswapd", $regex_wakeup_kswapd_default, - "nid", "zid", "order", "gfp_flags"); + "nid", "order", "gfp_flags"); $regex_lru_isolate = generate_traceevent_regex( "vmscan/mm_vmscan_lru_isolate", $regex_lru_isolate_default, - "isolate_mode", "classzone_idx", "order", + "classzone", "order", "nr_requested", "nr_scanned", "nr_skipped", "nr_taken", "lru"); $regex_lru_shrink_inactive = generate_traceevent_regex( @@ -218,11 +217,10 @@ $regex_lru_shrink_inactive = generate_traceevent_regex( $regex_lru_shrink_active = generate_traceevent_regex( "vmscan/mm_vmscan_lru_shrink_active", $regex_lru_shrink_active_default, - "nid", "zid", - "lru", - "nr_scanned", "nr_rotated", "priority"); + "nid", "nr_taken", "nr_active", "nr_deactivated", "nr_referenced", + "priority", "flags"); $regex_writepage = generate_traceevent_regex( - "vmscan/mm_vmscan_writepage", + "vmscan/mm_vmscan_write_folio", $regex_writepage_default, "page", "pfn", "flags"); @@ -371,7 +369,7 @@ EVENT_PROCESS: print " $regex_wakeup_kswapd\n"; next; } - my $order = $3; + my $order = $2; $perprocesspid{$process_pid}->{MM_VMSCAN_WAKEUP_KSWAPD_PERORDER}[$order]++; } elsif ($tracepoint eq "mm_vmscan_lru_isolate") { $details = $6; @@ -381,18 +379,14 @@ EVENT_PROCESS: print " $regex_lru_isolate/o\n"; next; } - my $isolate_mode = $1; - my $nr_scanned = $5; - my $file = $8; - - # To closer match vmstat scanning statistics, only count isolate_both - # and isolate_inactive as scanning. isolate_active is rotation - # isolate_inactive == 1 - # isolate_active == 2 - # isolate_both == 3 - if ($isolate_mode != 2) { + my $nr_scanned = $4; + my $lru = $7; + + # To closer match vmstat scanning statistics, only count + # inactive lru as scanning + if ($lru =~ /inactive_/) { $perprocesspid{$process_pid}->{HIGH_NR_SCANNED} += $nr_scanned; - if ($file =~ /_file/) { + if ($lru =~ /_file/) { $perprocesspid{$process_pid}->{HIGH_NR_FILE_SCANNED} += $nr_scanned; } else { $perprocesspid{$process_pid}->{HIGH_NR_ANON_SCANNED} += $nr_scanned; diff --git a/Documentation/trace/rv/da_monitor_synthesis.rst b/Documentation/trace/rv/da_monitor_synthesis.rst index 0dbdcd1e62b9..0a92729c8a9b 100644 --- a/Documentation/trace/rv/da_monitor_synthesis.rst +++ b/Documentation/trace/rv/da_monitor_synthesis.rst @@ -1,7 +1,7 @@ Deterministic Automata Monitor Synthesis ======================================== -The starting point for the application of runtime verification (RV) technics +The starting point for the application of runtime verification (RV) techniques is the *specification* or *modeling* of the desired (or undesired) behavior of the system under scrutiny. diff --git a/Documentation/trace/rv/monitor_wwnr.rst b/Documentation/trace/rv/monitor_wwnr.rst index 80f1777b85aa..9f739030f826 100644 --- a/Documentation/trace/rv/monitor_wwnr.rst +++ b/Documentation/trace/rv/monitor_wwnr.rst @@ -26,7 +26,7 @@ definition:: | running | -+ +-------------+ -This model is borken, the reason is that a task can be running +This model is broken, the reason is that a task can be running in the processor without being set as RUNNABLE. Think about a task about to sleep:: diff --git a/Documentation/trace/rv/runtime-verification.rst b/Documentation/trace/rv/runtime-verification.rst index c46b6149470e..dae78dfa7cdc 100644 --- a/Documentation/trace/rv/runtime-verification.rst +++ b/Documentation/trace/rv/runtime-verification.rst @@ -31,7 +31,7 @@ In Linux terms, the runtime verification monitors are encapsulated inside the *RV monitor* abstraction. A *RV monitor* includes a reference model of the system, a set of instances of the monitor (per-cpu monitor, per-task monitor, and so on), and the helper functions that glue the monitor to the system via -trace, as depicted bellow:: +trace, as depicted below:: Linux +---- RV Monitor ----------------------------------+ Formal Realm | | Realm diff --git a/Documentation/trace/uprobetracer.rst b/Documentation/trace/uprobetracer.rst index 122d15572fd5..01f6a780fb04 100644 --- a/Documentation/trace/uprobetracer.rst +++ b/Documentation/trace/uprobetracer.rst @@ -55,7 +55,7 @@ Synopsis of uprobe_tracer (\*1) only for return probe. (\*2) this is useful for fetching a field of data structures. - (\*3) Unlike kprobe event, "u" prefix will just be ignored, becuse uprobe + (\*3) Unlike kprobe event, "u" prefix will just be ignored, because uprobe events can access only user-space memory. Types diff --git a/Documentation/trace/user_events.rst b/Documentation/trace/user_events.rst index e7b07313550a..d8f12442aaa6 100644 --- a/Documentation/trace/user_events.rst +++ b/Documentation/trace/user_events.rst @@ -14,6 +14,11 @@ Programs can view status of the events via /sys/kernel/tracing/user_events_status and can both register and write data out via /sys/kernel/tracing/user_events_data. +Programs can also use /sys/kernel/tracing/dynamic_events to register and +delete user based events via the u: prefix. The format of the command to +dynamic_events is the same as the ioctl with the u: prefix applied. This +requires CAP_PERFMON due to the event persisting, otherwise -EPERM is returned. + Typically programs will register a set of events that they wish to expose to tools that can read trace_events (such as ftrace and perf). The registration process tells the kernel which address and bit to reflect if any tool has @@ -45,7 +50,7 @@ This command takes a packed struct user_reg as an argument:: /* Input: Enable size in bytes at address */ __u8 enable_size; - /* Input: Flags for future use, set to 0 */ + /* Input: Flags to use, if any */ __u16 flags; /* Input: Address to update when enabled */ @@ -69,7 +74,7 @@ The struct user_reg requires all the above inputs to be set appropriately. This must be 4 (32-bit) or 8 (64-bit). 64-bit values are only allowed to be used on 64-bit kernels, however, 32-bit can be used on all kernels. -+ flags: The flags to use, if any. For the initial version this must be 0. ++ flags: The flags to use, if any. Callers should first attempt to use flags and retry without flags to ensure support for lower versions of the kernel. If a flag is not supported -EINVAL is returned. @@ -80,6 +85,13 @@ The struct user_reg requires all the above inputs to be set appropriately. + name_args: The name and arguments to describe the event, see command format for details. +The following flags are currently supported. + ++ USER_EVENT_REG_PERSIST: The event will not delete upon the last reference + closing. Callers may use this if an event should exist even after the + process closes or unregisters the event. Requires CAP_PERFMON otherwise + -EPERM is returned. + Upon successful registration the following is set. + write_index: The index to use for this file descriptor that represents this @@ -93,7 +105,7 @@ or perf record -e user_events:[name] when attaching/recording. **NOTE:** The event subsystem name by default is "user_events". Callers should not assume it will always be "user_events". Operators reserve the right in the -future to change the subsystem name per-process to accomodate event isolation. +future to change the subsystem name per-process to accommodate event isolation. Command Format ^^^^^^^^^^^^^^ @@ -141,7 +153,10 @@ event (in both user and kernel space). User programs should use a separate file to request deletes than the one used for registration due to this. **NOTE:** By default events will auto-delete when there are no references left -to the event. Flags in the future may change this logic. +to the event. If programs do not want auto-delete, they must use the +USER_EVENT_REG_PERSIST flag when registering the event. Once that flag is used +the event exists until DIAG_IOCSDEL is invoked. Both register and delete of an +event that persists requires CAP_PERFMON, otherwise -EPERM is returned. Unregistering ------------- diff --git a/Documentation/translations/it_IT/riscv/patch-acceptance.rst b/Documentation/translations/it_IT/riscv/patch-acceptance.rst index edf67252b3fb..2d7afb1f6959 100644 --- a/Documentation/translations/it_IT/riscv/patch-acceptance.rst +++ b/Documentation/translations/it_IT/riscv/patch-acceptance.rst @@ -1,6 +1,6 @@ .. include:: ../disclaimer-ita.rst -:Original: :doc:`../../../riscv/patch-acceptance` +:Original: :doc:`../../../arch/riscv/patch-acceptance` :Translator: Federico Vaga <federico.vaga@vaga.pv.it> arch/riscv linee guida alla manutenzione per gli sviluppatori diff --git a/Documentation/translations/sp_SP/process/contribution-maturity-model.rst b/Documentation/translations/sp_SP/process/contribution-maturity-model.rst new file mode 100644 index 000000000000..cc052ae8183d --- /dev/null +++ b/Documentation/translations/sp_SP/process/contribution-maturity-model.rst @@ -0,0 +1,120 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/contribution-maturity-model.rst +:Translator: Avadhut Naik <avadhut.naik@amd.com> + +==================================================== +Modelo de Madurez de Contribución al Kernel de Linux +==================================================== + + +Los Antecedentes +================ + +Como parte de la cumbre de mantenedores del kernel de Linux 2021, hubo +una `discusión <https://lwn.net/Articles/870581/>`_ sobre los desafíos +en el reclutamiento de mantenedores del kernel, así como la sucesión de +los mantenedores. Algunas de las conclusiones de esa discusión incluyeron +que las empresas que forman parte de la comunidad del kernel de Linux +necesitan permitir que los ingenieros sean mantenedores como parte de su +trabajo, para que puedan convertirse en lideres respetados y finalmente, +en mantenedores del kernel. Para apoyar una fuente solida de talento, se +debe permitir y alentar a los desarrolladores a asumir contribuciones +upstream, como revisar los parches de otras personas, reestructurar la +infraestructura del kernel y escribir documentación. + +Con ese fin, Technical Advisory Board (TAB) de la Fundación Linux propone +este Modelo de Madurez de Contribución al Kernel de Linux. Estas +expectativas comunes para la participación con la comunidad upstream +tienen como objetivo aumentar la influencia de los desarrolladores +individuales, aumentar la colaboración de las organizaciones y mejorar +la salud general del ecosistema del kernel de Linux. + +El TAB insta a las organizaciones a evaluar continuamente su modelo de +madurez de Código Abierto y comprometerse a realizar mejoras para +alinearse con este modelo. Para ser eficaz, esta evaluación debe +incorporar la reacción de toda la organización, incluyendo la gerencia +y los desarrolladores en todos los niveles de antigüedad. En el espíritu +de Código Abierto, alentamos a las organizaciones a publicar sus +evaluaciones y planes para mejorar su participación con la comunidad +upstream. + +Nivel 0 +======= + +* A los ingenieros de software no se les permite contribuir con parches + al kernel de Linux. + +Nivel 1 +======= + +* A los ingenieros de software se les permite contribuir con parches al + kernel de Linux, ya sea como parte de sus responsabilidades de trabajo + o en su propio tiempo. + +Nivel 2 +======= + +* Se espera que los ingenieros de software contribuyan al kernel de Linux + como parte de sus responsabilidades de trabajo. +* Se proporcionará apoyo a los ingenieros de software para asistir a + conferencias relacionadas con Linux como parte de su trabajo. +* Las contribuciones de código upstream de un ingeniero de software se + considerarán en la promoción y las revisiones de rendimiento. + +Nivel 3 +======= + +* Se espera que los ingenieros de software revisen los parches (incluidos + los parches escritos por ingenieros de otras empresas) como parte de + sus responsabilidades de trabajo. +* Contribuir con presentaciones o ponencias a conferencias relacionadas + con Linux o académicas (como las organizadas por la Fundación Linux, + Usenix, ACM, etc.), se consideran parte del trabajo de un ingeniero. +* Las contribuciones a la comunidad de un ingeniero de software se + considerarán en la promoción y las revisiones de rendimiento. +* Las organizaciones informarán regularmente sobre las métricas de sus + contribuciones de código abierto y harán un seguimiento de estas + métricas a lo largo del tiempo. Estas métricas pueden publicarse + solo internamente dentro de la organización, o a discreción de la + organización, algunas o todas pueden publicarse externamente. Las + métricas que se sugieren encarecidamente incluyen: + + * El número de contribuciones al kernel upstream por equipo u + organización (por ejemplo, todas las personas que reportan a un + gerente o director o vicepresidente). + * El porcentaje de desarrolladores del kernel que han realizado + contribuciones upstream relativo al total de desarrolladores + del kernel en la organización. + * El intervalo de tiempo entre los kernels utilizados en los servidores + y/o productos de la organización y la fecha de publicación del kernel + upstream en el que se basa el kernel interno. + * El número de commits fuera del árbol de desarrollo presentes en los + kernels internos. + +Nivel 4 +======= + +* Se anima a los ingenieros de software a pasar una parte de su tiempo de + trabajo centrado en el Trabajo Ascendente, que se define como revisar + parches, servir en los comités de programas, mejorar la infraestructura + del proyecto central como escribir o mantener pruebas, reducir la deuda + de tecnología upstream, escribir documentación, etc. +* Los ingenieros de software son apoyados para ayudar a organizar + conferencias relacionadas con Linux. +* Las organizaciones considerarán los comentarios de los miembros de la + comunidad en las revisiones oficiales de rendimiento. + +Nivel 5 +======= + +* El desarrollo del kernel upstream se considera un puesto de trabajo + formal, con al menos un tercio del tiempo del ingeniero pasado a hacer + el Trabajo Ascendente. +* Las organizaciones buscarán activamente las reacciones de los miembros + de la comunidad como un factor en las revisiones oficiales de + rendimiento. +* Las organizaciones informarán regularmente internamente sobre la ratio + de trabajo upstream a trabajo enfocado en perseguir directamente los + objetivos comerciales. diff --git a/Documentation/translations/sp_SP/process/embargoed-hardware-issues.rst b/Documentation/translations/sp_SP/process/embargoed-hardware-issues.rst new file mode 100644 index 000000000000..c261b428b3f0 --- /dev/null +++ b/Documentation/translations/sp_SP/process/embargoed-hardware-issues.rst @@ -0,0 +1,341 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/embargoed-hardware-issues.rst +:Translator: Avadhut Naik <avadhut.naik@amd.com> + +Problemas de hardware embargados +================================ + +Alcance +------- + +Los problemas de hardware que resultan en problemas de seguridad son una +categoría diferente de errores de seguridad que los errores de software +puro que solo afectan al kernel de Linux. + +Los problemas de hardware como Meltdown, Spectre, L1TF, etc. deben +tratarse de manera diferente porque usualmente afectan a todos los +sistemas operativos (“OS”) y, por lo tanto, necesitan coordinación entre +vendedores diferentes de OS, distribuciones, vendedores de hardware y +otras partes. Para algunos de los problemas, las mitigaciones de software +pueden depender de actualizaciones de microcódigo o firmware, los cuales +necesitan una coordinación adicional. + +.. _Contacto: + +Contacto +-------- + +El equipo de seguridad de hardware del kernel de Linux es separado del +equipo regular de seguridad del kernel de Linux. + +El equipo solo maneja la coordinación de los problemas de seguridad de +hardware embargados. Los informes de errores de seguridad de software puro +en el kernel de Linux no son manejados por este equipo y el "reportero" +(quien informa del error) será guiado a contactar el equipo de seguridad +del kernel de Linux (:doc:`errores de seguridad <security-bugs>`) en su +lugar. + +El equipo puede contactar por correo electrónico en +<hardware-security@kernel.org>. Esta es una lista privada de oficiales de +seguridad que lo ayudarán a coordinar un problema de acuerdo con nuestro +proceso documentado. + +La lista esta encriptada y el correo electrónico a la lista puede ser +enviado por PGP o S/MIME encriptado y debe estar firmado con la llave de +PGP del reportero o el certificado de S/MIME. La llave de PGP y el +certificado de S/MIME de la lista están disponibles en las siguientes +URLs: + + - PGP: https://www.kernel.org/static/files/hardware-security.asc + - S/MIME: https://www.kernel.org/static/files/hardware-security.crt + +Si bien los problemas de seguridad del hardware a menudo son manejados por +el vendedor de hardware afectado, damos la bienvenida al contacto de +investigadores o individuos que hayan identificado una posible falla de +hardware. + +Oficiales de seguridad de hardware +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +El equipo actual de oficiales de seguridad de hardware: + + - Linus Torvalds (Linux Foundation Fellow) + - Greg Kroah-Hartman (Linux Foundation Fellow) + - Thomas Gleixner (Linux Foundation Fellow) + +Operación de listas de correo +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Las listas de correo encriptadas que se utilizan en nuestro proceso están +alojados en la infraestructura de IT de la Fundación Linux. Al proporcionar +este servicio, los miembros del personal de operaciones de IT de la +Fundación Linux técnicamente tienen la capacidad de acceder a la +información embargada, pero están obligados a la confidencialidad por su +contrato de trabajo. El personal de IT de la Fundación Linux también es +responsable para operar y administrar el resto de la infraestructura de +kernel.org. + +El actual director de infraestructura de proyecto de IT de la Fundación +Linux es Konstantin Ryabitsev. + +Acuerdos de no divulgación +-------------------------- + +El equipo de seguridad de hardware del kernel de Linux no es un organismo +formal y, por lo tanto, no puede firmar cualquier acuerdo de no +divulgación. La comunidad del kernel es consciente de la naturaleza +delicada de tales problemas y ofrece un Memorando de Entendimiento en su +lugar. + +Memorando de Entendimiento +-------------------------- + +La comunidad del kernel de Linux tiene una comprensión profunda del +requisito de mantener los problemas de seguridad de hardware bajo embargo +para la coordinación entre diferentes vendedores de OS, distribuidores, +vendedores de hardware y otras partes. + +La comunidad del kernel de Linux ha manejado con éxito los problemas de +seguridad del hardware en el pasado y tiene los mecanismos necesarios para +permitir el desarrollo compatible con la comunidad bajo restricciones de +embargo. + +La comunidad del kernel de Linux tiene un equipo de seguridad de hardware +dedicado para el contacto inicial, el cual supervisa el proceso de manejo +de tales problemas bajo las reglas de embargo. + +El equipo de seguridad de hardware identifica a los desarrolladores +(expertos en dominio) que formarán el equipo de respuesta inicial para un +problema en particular. El equipo de respuesta inicial puede involucrar +más desarrolladores (expertos en dominio) para abordar el problema de la +mejor manera técnica. + +Todos los desarrolladores involucrados se comprometen a adherirse a las +reglas del embargo y a mantener confidencial la información recibida. La +violación de la promesa conducirá a la exclusión inmediata del problema +actual y la eliminación de todas las listas de correo relacionadas. +Además, el equipo de seguridad de hardware también excluirá al +delincuente de problemas futuros. El impacto de esta consecuencia es un +elemento de disuasión altamente efectivo en nuestra comunidad. En caso de +que ocurra una violación, el equipo de seguridad de hardware informará a +las partes involucradas inmediatamente. Si usted o alguien tiene +conocimiento de una posible violación, por favor, infórmelo inmediatamente +a los oficiales de seguridad de hardware. + +Proceso +^^^^^^^ + +Debido a la naturaleza distribuida globalmente del desarrollo del kernel +de Linux, las reuniones cara a cara hacen imposible abordar los +problemas de seguridad del hardware. Las conferencias telefónicas son +difíciles de coordinar debido a las zonas horarias y otros factores y +solo deben usarse cuando sea absolutamente necesario. El correo +electrónico encriptado ha demostrado ser el método de comunicación más +efectivo y seguro para estos tipos de problemas. + +Inicio de la divulgación +"""""""""""""""""""""""" + +La divulgación comienza contactado al equipo de seguridad de hardware del +kernel de Linux por correo electrónico. Este contacto inicial debe +contener una descripción del problema y una lista de cualquier hardware +afectado conocido. Si su organización fabrica o distribuye el hardware +afectado, le animamos a considerar también que otro hardware podría estar +afectado. + +El equipo de seguridad de hardware proporcionará una lista de correo +encriptada específica para el incidente que se utilizará para la discusión +inicial con el reportero, la divulgación adicional y la coordinación. + +El equipo de seguridad de hardware proporcionará a la parte reveladora una +lista de desarrolladores (expertos de dominios) a quienes se debe informar +inicialmente sobre el problema después de confirmar con los +desarrolladores que se adherirán a este Memorando de Entendimiento y al +proceso documentado. Estos desarrolladores forman el equipo de respuesta +inicial y serán responsables de manejar el problema después del contacto +inicial. El equipo de seguridad de hardware apoyará al equipo de +respuesta, pero no necesariamente involucrandose en el proceso de desarrollo +de mitigación. + +Si bien los desarrolladores individuales pueden estar cubiertos por un +acuerdo de no divulgación a través de su empleador, no pueden firmar +acuerdos individuales de no divulgación en su papel de desarrolladores +del kernel de Linux. Sin embargo, aceptarán adherirse a este proceso +documentado y al Memorando de Entendimiento. + +La parte reveladora debe proporcionar una lista de contactos para todas +las demás entidades ya que han sido, o deberían ser, informadas sobre el +problema. Esto sirve para varios propósitos: + + - La lista de entidades divulgadas permite la comunicación en toda la + industria, por ejemplo, otros vendedores de OS, vendedores de HW, etc. + + - Las entidades divulgadas pueden ser contactadas para nombrar a expertos + que deben participar en el desarrollo de la mitigación. + + - Si un experto que se requiere para manejar un problema es empleado por + una entidad cotizada o un miembro de una entidad cotizada, los equipos + de respuesta pueden solicitar la divulgación de ese experto a esa + entidad. Esto asegura que el experto también forme parte del equipo de + respuesta de la entidad. + +Divulgación +""""""""""" + +La parte reveladora proporcionará información detallada al equipo de +respuesta inicial a través de la lista de correo encriptada especifica. + +Según nuestra experiencia, la documentación técnica de estos problemas +suele ser un punto de partida suficiente y es mejor hacer aclaraciones +técnicas adicionales a través del correo electrónico. + +Desarrollo de la mitigación +""""""""""""""""""""""""""" + +El equipo de respuesta inicial configura una lista de correo encriptada o +reutiliza una existente si es apropiada. + +El uso de una lista de correo está cerca del proceso normal de desarrollo +de Linux y se ha utilizado con éxito en el desarrollo de mitigación para +varios problemas de seguridad de hardware en el pasado. + +La lista de correo funciona en la misma manera que el desarrollo normal de +Linux. Los parches se publican, discuten y revisan y, si se acuerda, se +aplican a un repositorio git no público al que solo pueden acceder los +desarrolladores participantes a través de una conexión segura. El +repositorio contiene la rama principal de desarrollo en comparación con +el kernel principal y las ramas backport para versiones estables del +kernel según sea necesario. + +El equipo de respuesta inicial identificará a más expertos de la +comunidad de desarrolladores del kernel de Linux según sea necesario. La +incorporación de expertos puede ocurrir en cualquier momento del proceso +de desarrollo y debe manejarse de manera oportuna. + +Si un experto es empleado por o es miembro de una entidad en la lista de +divulgación proporcionada por la parte reveladora, entonces se solicitará +la participación de la entidad pertinente. + +Si no es así, entonces se informará a la parte reveladora sobre la +participación de los expertos. Los expertos están cubiertos por el +Memorando de Entendimiento y se solicita a la parte reveladora que +reconozca la participación. En caso de que la parte reveladora tenga una +razón convincente para objetar, entonces esta objeción debe plantearse +dentro de los cinco días laborables y resolverse con el equipo de +incidente inmediatamente. Si la parte reveladora no reacciona dentro de +los cinco días laborables, esto se toma como un reconocimiento silencioso. + +Después del reconocimiento o la resolución de una objeción, el experto es +revelado por el equipo de incidente y se incorpora al proceso de +desarrollo. + +Lanzamiento coordinado +"""""""""""""""""""""" + +Las partes involucradas negociarán la fecha y la hora en la que termina el +embargo. En ese momento, las mitigaciones preparadas se integran en los +árboles de kernel relevantes y se publican. + +Si bien entendemos que los problemas de seguridad del hardware requieren +un tiempo de embargo coordinado, el tiempo de embargo debe limitarse al +tiempo mínimo que se requiere para que todas las partes involucradas +desarrollen, prueben y preparen las mitigaciones. Extender el tiempo de +embargo artificialmente para cumplir con las fechas de discusión de la +conferencia u otras razones no técnicas está creando más trabajo y carga +para los desarrolladores y los equipos de respuesta involucrados, ya que +los parches necesitan mantenerse actualizados para seguir el desarrollo en +curso del kernel upstream, lo cual podría crear cambios conflictivos. + +Asignación de CVE +""""""""""""""""" + +Ni el equipo de seguridad de hardware ni el equipo de respuesta inicial +asignan CVEs, ni se requieren para el proceso de desarrollo. Si los CVEs +son proporcionados por la parte reveladora, pueden usarse con fines de +documentación. + +Embajadores del proceso +----------------------- + +Para obtener asistencia con este proceso, hemos establecido embajadores +en varias organizaciones, que pueden responder preguntas o proporcionar +orientación sobre el proceso de reporte y el manejo posterior. Los +embajadores no están involucrados en la divulgación de un problema en +particular, a menos que lo solicite un equipo de respuesta o una parte +revelada involucrada. La lista de embajadores actuales: + + ============= ======================================================== + AMD Tom Lendacky <thomas.lendacky@amd.com> + Ampere Darren Hart <darren@os.amperecomputing.com> + ARM Catalin Marinas <catalin.marinas@arm.com> + IBM Power Anton Blanchard <anton@linux.ibm.com> + IBM Z Christian Borntraeger <borntraeger@de.ibm.com> + Intel Tony Luck <tony.luck@intel.com> + Qualcomm Trilok Soni <tsoni@codeaurora.org> + Samsung Javier González <javier.gonz@samsung.com> + + Microsoft James Morris <jamorris@linux.microsoft.com> + Xen Andrew Cooper <andrew.cooper3@citrix.com> + + Canonical John Johansen <john.johansen@canonical.com> + Debian Ben Hutchings <ben@decadent.org.uk> + Oracle Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> + Red Hat Josh Poimboeuf <jpoimboe@redhat.com> + SUSE Jiri Kosina <jkosina@suse.cz> + + Google Kees Cook <keescook@chromium.org> + + LLVM Nick Desaulniers <ndesaulniers@google.com> + ============= ======================================================== + +Si quiere que su organización se añada a la lista de embajadores, por +favor póngase en contacto con el equipo de seguridad de hardware. El +embajador nominado tiene que entender y apoyar nuestro proceso +completamente y está idealmente bien conectado en la comunidad del kernel +de Linux. + +Listas de correo encriptadas +---------------------------- + +Usamos listas de correo encriptadas para la comunicación. El principio de +funcionamiento de estas listas es que el correo electrónico enviado a la +lista se encripta con la llave PGP de la lista o con el certificado S/MIME +de la lista. El software de lista de correo descifra el correo electrónico +y lo vuelve a encriptar individualmente para cada suscriptor con la llave +PGP del suscriptor o el certificado S/MIME. Los detalles sobre el software +de la lista de correo y la configuración que se usa para asegurar la +seguridad de las listas y la protección de los datos se pueden encontrar +aquí: https://korg.wiki.kernel.org/userdoc/remail. + +Llaves de lista +^^^^^^^^^^^^^^^ + +Para el contacto inicial, consulte :ref:`Contacto`. Para las listas de +correo especificas de incidentes, la llave y el certificado S/MIME se +envían a los suscriptores por correo electrónico desde la lista +especifica. + +Suscripción a listas específicas de incidentes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +La suscripción es manejada por los equipos de respuesta. Las partes +reveladas que quieren participar en la comunicación envían una lista de +suscriptores potenciales al equipo de respuesta para que el equipo de +respuesta pueda validar las solicitudes de suscripción. + +Cada suscriptor necesita enviar una solicitud de suscripción al equipo de +respuesta por correo electrónico. El correo electrónico debe estar firmado +con la llave PGP del suscriptor o el certificado S/MIME. Si se usa una +llave PGP, debe estar disponible desde un servidor de llave publica y esta +idealmente conectada a la red de confianza PGP del kernel de Linux. Véase +también: https://www.kernel.org/signature.html. + +El equipo de respuesta verifica que la solicitud del suscriptor sea válida +y añade al suscriptor a la lista. Después de la suscripción, el suscriptor +recibirá un correo electrónico de la lista que está firmado con la llave +PGP de la lista o el certificado S/MIME de la lista. El cliente de correo +electrónico del suscriptor puede extraer la llave PGP o el certificado +S/MIME de la firma, de modo que el suscriptor pueda enviar correo +electrónico encriptado a la lista. diff --git a/Documentation/translations/sp_SP/process/index.rst b/Documentation/translations/sp_SP/process/index.rst index 0bdeb1eb4403..d6f3ccfb160e 100644 --- a/Documentation/translations/sp_SP/process/index.rst +++ b/Documentation/translations/sp_SP/process/index.rst @@ -20,3 +20,7 @@ programming-language deprecated adding-syscalls + researcher-guidelines + contribution-maturity-model + security-bugs + embargoed-hardware-issues diff --git a/Documentation/translations/sp_SP/process/researcher-guidelines.rst b/Documentation/translations/sp_SP/process/researcher-guidelines.rst new file mode 100644 index 000000000000..462b3290b7b8 --- /dev/null +++ b/Documentation/translations/sp_SP/process/researcher-guidelines.rst @@ -0,0 +1,150 @@ +.. SPDX-License-Identifier: GPL-2.0 + +:Original: :ref:`Documentation/process/researcher-guidelines.rst` +:Translator: Avadhut Naik <avadhut.naik@amd.com> + +Directrices para Investigadores +++++++++++++++++++++++++++++++++ + +La comunidad del kernel de Linux da la bienvenida a la investigación +transparente sobre el kernel de Linux, las actividades involucradas +en su producción, otros subproductos de su desarrollo. Linux se +beneficia mucho de este tipo de investigación, y la mayoría de los +aspectos de Linux son impulsados por investigación en una forma u otra. + +La comunidad agradece mucho si los investigadores pueden compartir +los hallazgos preliminares antes de hacer públicos sus resultados, +especialmente si tal investigación involucra seguridad. Involucrarse +temprano ayuda a mejorar la calidad de investigación y la capacidad +de Linux para mejorar a partir de ella. En cualquier caso, se recomienda +compartir copias de acceso abierto de la investigación publicada con +la comunidad. + +Este documento busca clarificar lo que la comunidad del kernel de Linux +considera practicas aceptables y no aceptables al llevar a cabo +investigación de este tipo. Por lo menos, dicha investigación y +actividades afines deben seguir las reglas estándar de ética de la +investigación. Para más información sobre la ética de la investigación +en general, ética en la tecnología y la investigación de las comunidades +de desarrolladores en particular, ver: + + +* `Historia de la Ética en la Investigación <https://www.unlv.edu/research/ORI-HSR/history-ethics>`_ +* `Ética de la IEEE <https://www.ieee.org/about/ethics/index.html>`_ +* `Perspectivas de Desarrolladores e Investigadores sobre la Ética de los Experimentos en Proyectos de Código Abierto <https://arxiv.org/pdf/2112.13217.pdf>`_ + +La comunidad del kernel de Linux espera que todos los que interactúan con +el proyecto están participando en buena fe para mejorar Linux. La +investigación sobre cualquier artefacto disponible públicamente (incluido, +pero no limitado a código fuente) producido por la comunidad del kernel +de Linux es bienvenida, aunque la investigación sobre los desarrolladores +debe ser claramente opcional. + +La investigación pasiva que se basa completamente en fuentes disponibles +públicamente, incluidas las publicaciones en listas de correo públicas y +las contribuciones a los repositorios públicos, es claramente permitida. +Aunque, como con cualquier investigación, todavía se debe seguir la ética +estándar. + +La investigación activa sobre el comportamiento de los desarrolladores, +sin embargo, debe hacerse con el acuerdo explícito y la divulgación +completa a los desarrolladores individuales involucrados. No se puede +interactuar / experimentar con los desarrolladores sin consentimiento; +esto también es ética de investigación estándar. + +Para ayudar a aclarar: enviar parches a los desarrolladores es interactuar +con ellos, pero ya han dado su consentimiento para recibir contribuciones +en buena fe. No se ha dado consentimiento para enviar parches intencionalmente +defectuosos / vulnerables o contribuir con la información engañosa a las +discusiones. Dicha comunicación puede ser perjudicial al desarrollador (por +ejemplo, agotar el tiempo, el esfuerzo, y la moral) y perjudicial para el +proyecto al erosionar la confianza de toda la comunidad de desarrolladores en +el colaborador (y la organización del colaborador en conjunto), socavando +los esfuerzos para proporcionar reacciones constructivas a los colaboradores +y poniendo a los usuarios finales en riesgo de fallas de software. + +La participación en el desarrollo de Linux en sí mismo por parte de +investigadores, como con cualquiera, es bienvenida y alentada. La +investigación del código de Linux es una práctica común, especialmente +cuando se trata de desarrollar o ejecutar herramientas de análisis que +producen resultados procesables. + +Cuando se interactúa con la comunidad de desarrolladores, enviar un +parche ha sido tradicionalmente la mejor manera para hacer un impacto. +Linux ya tiene muchos errores conocidos – lo que es mucho más útil es +tener soluciones verificadas. Antes de contribuir, lea cuidadosamente +la documentación adecuada. + +* Documentation/process/development-process.rst +* Documentation/process/submitting-patches.rst +* Documentation/admin-guide/reporting-issues.rst +* Documentation/process/security-bugs.rst + +Entonces envíe un parche (incluyendo un registro de confirmación con +todos los detalles enumerados abajo) y haga un seguimiento de cualquier +comentario de otros desarrolladores. + +* ¿Cuál es el problema específico que se ha encontrado? +* ¿Como podría llegar al problema en un sistema en ejecución? +* ¿Qué efecto tendría encontrar el problema en el sistema? +* ¿Como se encontró el problema? Incluya específicamente detalles sobre + cualquier prueba, programas de análisis estáticos o dinámicos, y cualquier + otra herramienta o método utilizado para realizar el trabajo. +* ¿En qué versión de Linux se encontró el problema? Se prefiere usar la + versión más reciente o una rama reciente de linux-next (ver + Documentation/process/howto.rst). +* ¿Que se cambió para solucionar el problema y por qué se cree es correcto? +* ¿Como se probó el cambio para la complicación y el tiempo de ejecución? +* ¿Qué confirmación previa corrige este cambio? Esto debería ir en un “Fixes:” + etiqueta como se describe en la documentación. +* ¿Quién más ha revisado este parche? Esto debería ir con la adecuada “Reviewed-by” + etiqueta; Vea abajo. + +Por ejemplo (en inglés, pues es en las listas):: + + From: Author <author@email> + Subject: [PATCH] drivers/foo_bar: Add missing kfree() + + The error path in foo_bar driver does not correctly free the allocated + struct foo_bar_info. This can happen if the attached foo_bar device + rejects the initialization packets sent during foo_bar_probe(). This + would result in a 64 byte slab memory leak once per device attach, + wasting memory resources over time. + + This flaw was found using an experimental static analysis tool we are + developing, LeakMagic[1], which reported the following warning when + analyzing the v5.15 kernel release: + + path/to/foo_bar.c:187: missing kfree() call? + + Add the missing kfree() to the error path. No other references to + this memory exist outside the probe function, so this is the only + place it can be freed. + + x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC + 11.2 show no new warnings, and LeakMagic no longer warns about this + code path. As we don't have a FooBar device to test with, no runtime + testing was able to be performed. + + [1] https://url/to/leakmagic/details + + Reported-by: Researcher <researcher@email> + Fixes: aaaabbbbccccdddd ("Introduce support for FooBar") + Signed-off-by: Author <author@email> + Reviewed-by: Reviewer <reviewer@email> + +Si usted es un colaborador por primera vez, se recomienda que el parche en +si sea examinado por otros en privado antes de ser publicado en listas +públicas. (Esto es necesario si se le ha dicho explícitamente que sus parches +necesitan una revisión interna más cuidadosa.) Se espera que estas personas +tengan su etiqueta “Reviewed-by” incluida en el parche resultante. Encontrar +otro desarrollador con conocimiento de las contribuciones a Linux, especialmente +dentro de su propia organización, y tener su ayuda con las revisiones antes de +enviarlas a las listas de correo publico tiende a mejorar significativamente la +calidad de los parches resultantes, y reduce así la carga de otros desarrolladores. + +Si no se puede encontrar a nadie para revisar internamente los parches y necesita +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: +<tech-board@lists.linux-foundation.org>. diff --git a/Documentation/translations/sp_SP/process/security-bugs.rst b/Documentation/translations/sp_SP/process/security-bugs.rst new file mode 100644 index 000000000000..d07c7e579b52 --- /dev/null +++ b/Documentation/translations/sp_SP/process/security-bugs.rst @@ -0,0 +1,103 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/security-bugs.rst +:Translator: Avadhut Naik <avadhut.naik@amd.com> + +Errores de seguridad +==================== + +Los desarrolladores del kernel de Linux se toman la seguridad muy en +serio. Como tal, nos gustaría saber cuándo se encuentra un error de +seguridad para que pueda ser corregido y divulgado lo más rápido posible. +Por favor, informe sobre los errores de seguridad al equipo de seguridad +del kernel de Linux. + +Contacto +-------- + +El equipo de seguridad del kernel de Linux puede ser contactado por correo +electrónico en <security@kernel.org>. Esta es una lista privada de +oficiales de seguridad que ayudarán a verificar el informe del error y +desarrollarán y publicarán una corrección. Si ya tiene una corrección, por +favor, inclúyala con su informe, ya que eso puede acelerar considerablemente +el proceso. Es posible que el equipo de seguridad traiga ayuda adicional +de mantenedores del área para comprender y corregir la vulnerabilidad de +seguridad. + +Como ocurre con cualquier error, cuanta más información se proporcione, +más fácil será diagnosticarlo y corregirlo. Por favor, revise el +procedimiento descrito en 'Documentation/admin-guide/reporting-issues.rst' +si no tiene claro que información es útil. Cualquier código de explotación +es muy útil y no será divulgado sin el consentimiento del "reportero" (el +que envia el error) a menos que ya se haya hecho público. + +Por favor, envíe correos electrónicos en texto plano sin archivos +adjuntos cuando sea posible. Es mucho más difícil tener una discusión +citada en contexto sobre un tema complejo si todos los detalles están +ocultos en archivos adjuntos. Piense en ello como un +:doc:`envío de parche regular <submitting-patches>` (incluso si no tiene +un parche todavía) describa el problema y el impacto, enumere los pasos +de reproducción, y sígalo con una solución propuesta, todo en texto plano. + + +Divulgación e información embargada +----------------------------------- + +La lista de seguridad no es un canal de divulgación. Para eso, ver +Coordinación debajo. Una vez que se ha desarrollado una solución robusta, +comienza el proceso de lanzamiento. Las soluciones para errores conocidos +públicamente se lanzan inmediatamente. + +Aunque nuestra preferencia es lanzar soluciones para errores no divulgados +públicamente tan pronto como estén disponibles, esto puede postponerse a +petición del reportero o una parte afectada por hasta 7 días calendario +desde el inicio del proceso de lanzamiento, con una extensión excepcional +a 14 días de calendario si se acuerda que la criticalidad del error requiere +más tiempo. La única razón válida para aplazar la publicación de una +solución es para acomodar la logística de QA y los despliegues a gran +escala que requieren coordinación de lanzamiento. + +Si bien la información embargada puede compartirse con personas de +confianza para desarrollar una solución, dicha información no se publicará +junto con la solución o en cualquier otro canal de divulgación sin el +permiso del reportero. Esto incluye, pero no se limita al informe original +del error y las discusiones de seguimiento (si las hay), exploits, +información sobre CVE o la identidad del reportero. + +En otras palabras, nuestro único interés es solucionar los errores. Toda +otra información presentada a la lista de seguridad y cualquier discusión +de seguimiento del informe se tratan confidencialmente incluso después de +que se haya levantado el embargo, en perpetuidad. + +Coordinación con otros grupos +----------------------------- + +El equipo de seguridad del kernel recomienda encarecidamente que los +reporteros de posibles problemas de seguridad NUNCA contacten la lista +de correo “linux-distros” hasta DESPUES de discutirlo con el equipo de +seguridad del kernel. No Cc: ambas listas a la vez. Puede ponerse en +contacto con la lista de correo linux-distros después de que se haya +acordado una solución y comprenda completamente los requisitos que al +hacerlo le impondrá a usted y la comunidad del kernel. + +Las diferentes listas tienen diferentes objetivos y las reglas de +linux-distros no contribuyen en realidad a solucionar ningún problema de +seguridad potencial. + +Asignación de CVE +----------------- + +El equipo de seguridad no asigna CVEs, ni los requerimos para informes o +correcciones, ya que esto puede complicar innecesariamente el proceso y +puede retrasar el manejo de errores. Si un reportero desea que se le +asigne un identificador CVE, debe buscar uno por sí mismo, por ejemplo, +poniéndose en contacto directamente con MITRE. Sin embargo, en ningún +caso se retrasará la inclusión de un parche para esperar a que llegue un +identificador CVE. + +Acuerdos de no divulgación +-------------------------- + +El equipo de seguridad del kernel de Linux no es un organismo formal y, +por lo tanto, no puede firmar cualquier acuerdo de no divulgación. diff --git a/Documentation/translations/zh_CN/arch/index.rst b/Documentation/translations/zh_CN/arch/index.rst index 6fa0cb671009..71186d9df7c9 100644 --- a/Documentation/translations/zh_CN/arch/index.rst +++ b/Documentation/translations/zh_CN/arch/index.rst @@ -8,17 +8,16 @@ .. toctree:: :maxdepth: 2 - ../mips/index + mips/index arm64/index - ../riscv/index + ../arch/riscv/index openrisc/index parisc/index - ../loongarch/index + loongarch/index TODOList: * arm/index -* ia64/index * m68k/index * nios2/index * powerpc/index diff --git a/Documentation/translations/zh_CN/loongarch/booting.rst b/Documentation/translations/zh_CN/arch/loongarch/booting.rst index fb6440c438f0..d2f55872904e 100644 --- a/Documentation/translations/zh_CN/loongarch/booting.rst +++ b/Documentation/translations/zh_CN/arch/loongarch/booting.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/loongarch/booting.rst +:Original: Documentation/arch/loongarch/booting.rst :翻译: diff --git a/Documentation/translations/zh_CN/loongarch/features.rst b/Documentation/translations/zh_CN/arch/loongarch/features.rst index 3886e635ec06..82bfac180bdc 100644 --- a/Documentation/translations/zh_CN/loongarch/features.rst +++ b/Documentation/translations/zh_CN/arch/loongarch/features.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/loongarch/features.rst +:Original: Documentation/arch/loongarch/features.rst :Translator: Huacai Chen <chenhuacai@loongson.cn> .. kernel-feat:: $srctree/Documentation/features loongarch diff --git a/Documentation/translations/zh_CN/loongarch/index.rst b/Documentation/translations/zh_CN/arch/loongarch/index.rst index 0273a08342f7..4bd24f5ffed1 100644 --- a/Documentation/translations/zh_CN/loongarch/index.rst +++ b/Documentation/translations/zh_CN/arch/loongarch/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/loongarch/index.rst +:Original: Documentation/arch/loongarch/index.rst :Translator: Huacai Chen <chenhuacai@loongson.cn> ================= diff --git a/Documentation/translations/zh_CN/loongarch/introduction.rst b/Documentation/translations/zh_CN/arch/loongarch/introduction.rst index 470c38ae2caf..59d6bf33050c 100644 --- a/Documentation/translations/zh_CN/loongarch/introduction.rst +++ b/Documentation/translations/zh_CN/arch/loongarch/introduction.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/loongarch/introduction.rst +:Original: Documentation/arch/loongarch/introduction.rst :Translator: Huacai Chen <chenhuacai@loongson.cn> ============= @@ -344,9 +344,9 @@ LoongArch指令集架构的文档： LoongArch的ELF psABI文档： - https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.00-CN.pdf （中文版） + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.01-CN.pdf （中文版） - https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.00-EN.pdf （英文版） + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.01-EN.pdf （英文版） Loongson与LoongArch的Linux内核源码仓库： diff --git a/Documentation/translations/zh_CN/loongarch/irq-chip-model.rst b/Documentation/translations/zh_CN/arch/loongarch/irq-chip-model.rst index fb5d23b49ed5..f1e9ab18206c 100644 --- a/Documentation/translations/zh_CN/loongarch/irq-chip-model.rst +++ b/Documentation/translations/zh_CN/arch/loongarch/irq-chip-model.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/loongarch/irq-chip-model.rst +:Original: Documentation/arch/loongarch/irq-chip-model.rst :Translator: Huacai Chen <chenhuacai@loongson.cn> ================================== diff --git a/Documentation/translations/zh_CN/mips/booting.rst b/Documentation/translations/zh_CN/arch/mips/booting.rst index e0bbd3f20862..485b57e0ca0b 100644 --- a/Documentation/translations/zh_CN/mips/booting.rst +++ b/Documentation/translations/zh_CN/arch/mips/booting.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/mips/booting.rst +:Original: Documentation/arch/mips/booting.rst :翻译: diff --git a/Documentation/translations/zh_CN/mips/features.rst b/Documentation/translations/zh_CN/arch/mips/features.rst index b61dab06ceaf..da1b956e4a40 100644 --- a/Documentation/translations/zh_CN/mips/features.rst +++ b/Documentation/translations/zh_CN/arch/mips/features.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/mips/features.rst +:Original: Documentation/arch/mips/features.rst :翻译: diff --git a/Documentation/translations/zh_CN/mips/index.rst b/Documentation/translations/zh_CN/arch/mips/index.rst index 192c6adbb72e..2a34217119ea 100644 --- a/Documentation/translations/zh_CN/mips/index.rst +++ b/Documentation/translations/zh_CN/arch/mips/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/mips/index.rst +:Original: Documentation/arch/mips/index.rst :翻译: diff --git a/Documentation/translations/zh_CN/mips/ingenic-tcu.rst b/Documentation/translations/zh_CN/arch/mips/ingenic-tcu.rst index ddbe149c517b..3d599a36b571 100644 --- a/Documentation/translations/zh_CN/mips/ingenic-tcu.rst +++ b/Documentation/translations/zh_CN/arch/mips/ingenic-tcu.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/mips/ingenic-tcu.rst +:Original: Documentation/arch/mips/ingenic-tcu.rst :翻译: diff --git a/Documentation/translations/zh_CN/riscv/boot-image-header.rst b/Documentation/translations/zh_CN/arch/riscv/boot-image-header.rst index 0234c28a7114..779b5172fe24 100644 --- a/Documentation/translations/zh_CN/riscv/boot-image-header.rst +++ b/Documentation/translations/zh_CN/arch/riscv/boot-image-header.rst @@ -1,6 +1,6 @@ -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/riscv/boot-image-header.rst +:Original: Documentation/arch/riscv/boot-image-header.rst :翻译: diff --git a/Documentation/translations/zh_CN/riscv/index.rst b/Documentation/translations/zh_CN/arch/riscv/index.rst index 131e405aa857..3b041c116169 100644 --- a/Documentation/translations/zh_CN/riscv/index.rst +++ b/Documentation/translations/zh_CN/arch/riscv/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/riscv/index.rst +:Original: Documentation/arch/riscv/index.rst :翻译: diff --git a/Documentation/translations/zh_CN/riscv/patch-acceptance.rst b/Documentation/translations/zh_CN/arch/riscv/patch-acceptance.rst index d180d24717bf..c8eb230ca8ee 100644 --- a/Documentation/translations/zh_CN/riscv/patch-acceptance.rst +++ b/Documentation/translations/zh_CN/arch/riscv/patch-acceptance.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/riscv/patch-acceptance.rst +:Original: Documentation/arch/riscv/patch-acceptance.rst :翻译: diff --git a/Documentation/translations/zh_CN/riscv/vm-layout.rst b/Documentation/translations/zh_CN/arch/riscv/vm-layout.rst index 91884e2dfff8..4b9f4dcf6c19 100644 --- a/Documentation/translations/zh_CN/riscv/vm-layout.rst +++ b/Documentation/translations/zh_CN/arch/riscv/vm-layout.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/riscv/vm-layout.rst +:Original: Documentation/arch/riscv/vm-layout.rst :翻译: diff --git a/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst b/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst index 4772a900c37a..bc0d7ea6d834 100644 --- a/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst +++ b/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst @@ -49,12 +49,6 @@ CPU热拔插支持的一个更新颖的用途是它在SMP的暂停恢复支持 限制内核将支持的CPU总量。如果这里提供的数量低于实际可用的CPU数量，那么其他CPU 以后就不能上线了。 -``additional_cpus=n`` - 使用它来限制可热插拔的CPU。该选项设置 - ``cpu_possible_mask = cpu_present_mask + additional_cpus`` - - 这个选项只限于IA64架构。 - ``possible_cpus=n`` 这个选项设置 ``cpu_possible_mask`` 中的 ``possible_cpus`` 位。 diff --git a/Documentation/translations/zh_CN/core-api/workqueue.rst b/Documentation/translations/zh_CN/core-api/workqueue.rst index 6c1b5ec31d75..7fac6f75d078 100644 --- a/Documentation/translations/zh_CN/core-api/workqueue.rst +++ b/Documentation/translations/zh_CN/core-api/workqueue.rst @@ -202,7 +202,7 @@ workqueue将自动创建与属性相匹配的后备工作者池。调节并发 同的排序属性。 在目前的实现中，上述配置只保证了特定NUMA节点内的ST行为。相反， -``alloc_ordered_queue()`` 应该被用来实现全系统的ST行为。 +``alloc_ordered_workqueue()`` 应该被用来实现全系统的ST行为。 执行场景示例 diff --git a/Documentation/translations/zh_CN/dev-tools/kasan.rst b/Documentation/translations/zh_CN/dev-tools/kasan.rst index 05ef904dbcfb..8fdb20c9665b 100644 --- a/Documentation/translations/zh_CN/dev-tools/kasan.rst +++ b/Documentation/translations/zh_CN/dev-tools/kasan.rst @@ -42,7 +42,7 @@ KASAN有三种模式: 体系架构 ~~~~~~~~ -在x86_64、arm、arm64、powerpc、riscv、s390和xtensa上支持通用KASAN， +在x86_64、arm、arm64、powerpc、riscv、s390、xtensa和loongarch上支持通用KASAN， 而基于标签的KASAN模式只在arm64上支持。 编译器 diff --git a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst index af65e7e93c02..69e7e4cb2002 100644 --- a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst +++ b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst @@ -3,7 +3,7 @@ .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/dev-tools/testing-overview.rst -:Translator: 胡皓文 Hu Haowen <src.res@email.cn> +:Translator: 胡皓文 Hu Haowen <src.res.211@gmail.com> ============ 内核测试指南 diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index 299704c0818d..6ccec9657cc6 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -52,12 +52,9 @@ core-api/index driver-api/index + subsystem-apis 内核中的锁 <locking/index> -TODOList: - -* subsystem-apis - 开发工具和流程 -------------- diff --git a/Documentation/translations/zh_CN/maintainer/maintainer-entry-profile.rst b/Documentation/translations/zh_CN/maintainer/maintainer-entry-profile.rst index a1ee99c4786e..0f5acfb1012e 100644 --- a/Documentation/translations/zh_CN/maintainer/maintainer-entry-profile.rst +++ b/Documentation/translations/zh_CN/maintainer/maintainer-entry-profile.rst @@ -89,4 +89,4 @@ ../doc-guide/maintainer-profile ../../../nvdimm/maintainer-entry-profile - ../../../riscv/patch-acceptance + ../../../arch/riscv/patch-acceptance diff --git a/Documentation/translations/zh_CN/mm/frontswap.rst b/Documentation/translations/zh_CN/mm/frontswap.rst deleted file mode 100644 index 434975390b48..000000000000 --- a/Documentation/translations/zh_CN/mm/frontswap.rst +++ /dev/null @@ -1,196 +0,0 @@ -:Original: Documentation/mm/frontswap.rst - -:翻译: - - 司延腾 Yanteng Si <siyanteng@loongson.cn> - -:校译: - -========= -Frontswap -========= - -Frontswap为交换页提供了一个 “transcendent memory” 的接口。在一些环境中，由 -于交换页被保存在RAM（或类似RAM的设备）中，而不是交换磁盘，因此可以获得巨大的性能 -节省（提高）。 - -.. _Transcendent memory in a nutshell: https://lwn.net/Articles/454795/ - -Frontswap之所以这么命名，是因为它可以被认为是与swap设备的“back”存储相反。存 -储器被认为是一个同步并发安全的面向页面的“伪RAM设备”，符合transcendent memory -（如Xen的“tmem”，或内核内压缩内存，又称“zcache”，或未来的类似RAM的设备）的要 -求；这个伪RAM设备不能被内核直接访问或寻址，其大小未知且可能随时间变化。驱动程序通过 -调用frontswap_register_ops将自己与frontswap链接起来，以适当地设置frontswap_ops -的功能，它提供的功能必须符合某些策略，如下所示: - -一个 “init” 将设备准备好接收与指定的交换设备编号（又称“类型”）相关的frontswap -交换页。一个 “store” 将把该页复制到transcendent memory，并与该页的类型和偏移 -量相关联。一个 “load” 将把该页，如果找到的话，从transcendent memory复制到内核 -内存，但不会从transcendent memory中删除该页。一个 “invalidate_page” 将从 -transcendent memory中删除该页，一个 “invalidate_area” 将删除所有与交换类型 -相关的页（例如，像swapoff）并通知 “device” 拒绝进一步存储该交换类型。 - -一旦一个页面被成功存储，在该页面上的匹配加载通常会成功。因此，当内核发现自己处于需 -要交换页面的情况时，它首先尝试使用frontswap。如果存储的结果是成功的，那么数据就已 -经成功的保存到了transcendent memory中，并且避免了磁盘写入，如果后来再读回数据， -也避免了磁盘读取。如果存储返回失败，transcendent memory已经拒绝了该数据，且该页 -可以像往常一样被写入交换空间。 - -请注意，如果一个页面被存储，而该页面已经存在于transcendent memory中（一个 “重复” -的存储），要么存储成功，数据被覆盖，要么存储失败，该页面被废止。这确保了旧的数据永远 -不会从frontswap中获得。 - -如果配置正确，对frontswap的监控是通过 `/sys/kernel/debug/frontswap` 目录下的 -debugfs完成的。frontswap的有效性可以通过以下方式测量（在所有交换设备中）: - -``failed_stores`` - 有多少次存储的尝试是失败的 - -``loads`` - 尝试了多少次加载（应该全部成功） - -``succ_stores`` - 有多少次存储的尝试是成功的 - -``invalidates`` - 尝试了多少次作废 - -后台实现可以提供额外的指标。 - -经常问到的问题 -============== - -* 价值在哪里? - -当一个工作负载开始交换时，性能就会下降。Frontswap通过提供一个干净的、动态的接口来 -读取和写入交换页到 “transcendent memory”，从而大大增加了许多这样的工作负载的性 -能，否则内核是无法直接寻址的。当数据被转换为不同的形式和大小（比如压缩）或者被秘密 -移动（对于一些类似RAM的设备来说，这可能对写平衡很有用）时，这个接口是理想的。交换 -页（和被驱逐的页面缓存页）是这种比RAM慢但比磁盘快得多的“伪RAM设备”的一大用途。 - -Frontswap对内核的影响相当小，为各种系统配置中更动态、更灵活的RAM利用提供了巨大的 -灵活性： - -在单一内核的情况下，又称“zcache”，页面被压缩并存储在本地内存中，从而增加了可以安 -全保存在RAM中的匿名页面总数。Zcache本质上是用压缩/解压缩的CPU周期换取更好的内存利 -用率。Benchmarks测试显示，当内存压力较低时，几乎没有影响，而在高内存压力下的一些 -工作负载上，则有明显的性能改善（25%以上）。 - -“RAMster” 在zcache的基础上增加了对集群系统的 “peer-to-peer” transcendent memory -的支持。Frontswap页面像zcache一样被本地压缩，但随后被“remotified” 到另一个系 -统的RAM。这使得RAM可以根据需要动态地来回负载平衡，也就是说，当系统A超载时，它可以 -交换到系统B，反之亦然。RAMster也可以被配置成一个内存服务器，因此集群中的许多服务器 -可以根据需要动态地交换到配置有大量内存的单一服务器上......而不需要预先配置每个客户 -有多少内存可用 - -在虚拟情况下，虚拟化的全部意义在于统计地将物理资源在多个虚拟机的不同需求之间进行复 -用。对于RAM来说，这真的很难做到，而且在不改变内核的情况下，要做好这一点的努力基本上 -是失败的（除了一些广为人知的特殊情况下的工作负载）。具体来说，Xen Transcendent Memory -后端允许管理器拥有的RAM “fallow”，不仅可以在多个虚拟机之间进行“time-shared”， -而且页面可以被压缩和重复利用，以优化RAM的利用率。当客户操作系统被诱导交出未充分利用 -的RAM时（如 “selfballooning”），突然出现的意外内存压力可能会导致交换；frontswap -允许这些页面被交换到管理器RAM中或从管理器RAM中交换（如果整体主机系统内存条件允许）， -从而减轻计划外交换可能带来的可怕的性能影响。 - -一个KVM的实现正在进行中，并且已经被RFC'ed到lkml。而且，利用frontswap，对NVM作为 -内存扩展技术的调查也在进行中。 - -* 当然，在某些情况下可能有性能上的优势，但frontswap的空间/时间开销是多少？ - -如果 CONFIG_FRONTSWAP 被禁用，每个 frontswap 钩子都会编译成空，唯一的开销是每 -个 swapon'ed swap 设备的几个额外字节。如果 CONFIG_FRONTSWAP 被启用，但没有 -frontswap的 “backend” 寄存器，每读或写一个交换页就会有一个额外的全局变量，而不 -是零。如果 CONFIG_FRONTSWAP 被启用，并且有一个frontswap的backend寄存器，并且 -后端每次 “store” 请求都失败（即尽管声称可能，但没有提供内存），CPU 的开销仍然可以 -忽略不计 - 因为每次frontswap失败都是在交换页写到磁盘之前，系统很可能是 I/O 绑定 -的，无论如何使用一小部分的 CPU 都是不相关的。 - -至于空间，如果CONFIG_FRONTSWAP被启用，并且有一个frontswap的backend注册，那么 -每个交换设备的每个交换页都会被分配一个比特。这是在内核已经为每个交换设备的每个交换 -页分配的8位（在2.6.34之前是16位）上增加的。(Hugh Dickins观察到，frontswap可能 -会偷取现有的8个比特，但是我们以后再来担心这个小的优化问题)。对于标准的4K页面大小的 -非常大的交换盘（这很罕见），这是每32GB交换盘1MB开销。 - -当交换页存储在transcendent memory中而不是写到磁盘上时，有一个副作用，即这可能会 -产生更多的内存压力，有可能超过其他的优点。一个backend，比如zcache，必须实现策略 -来仔细（但动态地）管理内存限制，以确保这种情况不会发生。 - -* 好吧，那就用内核骇客能理解的术语来快速概述一下这个frontswap补丁的作用如何？ - -我们假设在内核初始化过程中，一个frontswap 的 “backend” 已经注册了；这个注册表 -明这个frontswap 的 “backend” 可以访问一些不被内核直接访问的“内存”。它到底提 -供了多少内存是完全动态和随机的。 - -每当一个交换设备被交换时，就会调用frontswap_init()，把交换设备的编号（又称“类 -型”）作为一个参数传给它。这就通知了frontswap，以期待 “store” 与该号码相关的交 -换页的尝试。 - -每当交换子系统准备将一个页面写入交换设备时（参见swap_writepage()），就会调用 -frontswap_store。Frontswap与frontswap backend协商，如果backend说它没有空 -间，frontswap_store返回-1，内核就会照常把页换到交换设备上。注意，来自frontswap -backend的响应对内核来说是不可预测的；它可能选择从不接受一个页面，可能接受每九个 -页面，也可能接受每一个页面。但是如果backend确实接受了一个页面，那么这个页面的数 -据已经被复制并与类型和偏移量相关联了，而且backend保证了数据的持久性。在这种情况 -下，frontswap在交换设备的“frontswap_map” 中设置了一个位，对应于交换设备上的 -页面偏移量，否则它就会将数据写入该设备。 - -当交换子系统需要交换一个页面时（swap_readpage()），它首先调用frontswap_load()， -检查frontswap_map，看这个页面是否早先被frontswap backend接受。如果是，该页 -的数据就会从frontswap后端填充，换入就完成了。如果不是，正常的交换代码将被执行， -以便从真正的交换设备上获得这一页的数据。 - -所以每次frontswap backend接受一个页面时，交换设备的读取和（可能）交换设备的写 -入都被 “frontswap backend store” 和（可能）“frontswap backend loads” -所取代，这可能会快得多。 - -* frontswap不能被配置为一个 “特殊的” 交换设备，它的优先级要高于任何真正的交换 - 设备（例如像zswap，或者可能是swap-over-nbd/NFS）？ - -首先，现有的交换子系统不允许有任何种类的交换层次结构。也许它可以被重写以适应层次 -结构，但这将需要相当大的改变。即使它被重写，现有的交换子系统也使用了块I/O层，它 -假定交换设备是固定大小的，其中的任何页面都是可线性寻址的。Frontswap几乎没有触 -及现有的交换子系统，而是围绕着块I/O子系统的限制，提供了大量的灵活性和动态性。 - -例如，frontswap backend对任何交换页的接受是完全不可预测的。这对frontswap backend -的定义至关重要，因为它赋予了backend完全动态的决定权。在zcache中，人们无法预 -先知道一个页面的可压缩性如何。可压缩性 “差” 的页面会被拒绝，而 “差” 本身也可 -以根据当前的内存限制动态地定义。 - -此外，frontswap是完全同步的，而真正的交换设备，根据定义，是异步的，并且使用 -块I/O。块I/O层不仅是不必要的，而且可能进行 “优化”，这对面向RAM的设备来说是 -不合适的，包括将一些页面的写入延迟相当长的时间。同步是必须的，以确保后端的动 -态性，并避免棘手的竞争条件，这将不必要地大大增加frontswap和/或块I/O子系统的 -复杂性。也就是说，只有最初的 “store” 和 “load” 操作是需要同步的。一个独立 -的异步线程可以自由地操作由frontswap存储的页面。例如，RAMster中的 “remotification” -线程使用标准的异步内核套接字，将压缩的frontswap页面移动到远程机器。同样， -KVM的客户方实现可以进行客户内压缩，并使用 “batched” hypercalls。 - -在虚拟化环境中，动态性允许管理程序（或主机操作系统）做“intelligent overcommit”。 -例如，它可以选择只接受页面，直到主机交换可能即将发生，然后强迫客户机做他们 -自己的交换。 - -transcendent memory规格的frontswap有一个坏处。因为任何 “store” 都可 -能失败，所以必须在一个真正的交换设备上有一个真正的插槽来交换页面。因此， -frontswap必须作为每个交换设备的 “影子” 来实现，它有可能容纳交换设备可能 -容纳的每一个页面，也有可能根本不容纳任何页面。这意味着frontswap不能包含比 -swap设备总数更多的页面。例如，如果在某些安装上没有配置交换设备，frontswap -就没有用。无交换设备的便携式设备仍然可以使用frontswap，但是这种设备的 -backend必须配置某种 “ghost” 交换设备，并确保它永远不会被使用。 - - -* 为什么会有这种关于 “重复存储” 的奇怪定义？如果一个页面以前被成功地存储过， - 难道它不能总是被成功地覆盖吗？ - -几乎总是可以的，不，有时不能。考虑一个例子，数据被压缩了，原来的4K页面被压 -缩到了1K。现在，有人试图用不可压缩的数据覆盖该页，因此会占用整个4K。但是 -backend没有更多的空间了。在这种情况下，这个存储必须被拒绝。每当frontswap -拒绝一个会覆盖的存储时，它也必须使旧的数据作废，并确保它不再被访问。因为交 -换子系统会把新的数据写到读交换设备上，这是确保一致性的正确做法。 - -* 为什么frontswap补丁会创建新的头文件swapfile.h？ - -frontswap代码依赖于一些swap子系统内部的数据结构，这些数据结构多年来一直 -在静态和全局之间来回移动。这似乎是一个合理的妥协：将它们定义为全局，但在一 -个新的包含文件中声明它们，该文件不被包含swap.h的大量源文件所包含。 - -Dan Magenheimer，最后更新于2012年4月9日 diff --git a/Documentation/translations/zh_CN/mm/hugetlbfs_reserv.rst b/Documentation/translations/zh_CN/mm/hugetlbfs_reserv.rst index b7a0544224ad..20947f8bd065 100644 --- a/Documentation/translations/zh_CN/mm/hugetlbfs_reserv.rst +++ b/Documentation/translations/zh_CN/mm/hugetlbfs_reserv.rst @@ -219,7 +219,7 @@ vma_commit_reservation()之间，预留映射有可能被改变。如果hugetlb_ 释放巨页 ======== -巨页释放是由函数free_huge_page()执行的。这个函数是hugetlbfs复合页的析构器。因此，它只传 +巨页释放是由函数free_huge_folio()执行的。这个函数是hugetlbfs复合页的析构器。因此，它只传 递一个指向页面结构体的指针。当一个巨页被释放时，可能需要进行预留计算。如果该页与包含保 留的子池相关联，或者该页在错误路径上被释放，必须恢复全局预留计数，就会出现这种情况。 @@ -296,7 +296,7 @@ COW和预留 调用代码执行全局检查和分配，以确定是否有足够的巨页使操作成功。 2) - a) 如果操作能够成功，regi_add()将被调用，以实际修改先前传递给regi_chg()的相同范围 + a) 如果操作能够成功，region_add()将被调用，以实际修改先前传递给region_chg()的相同范围 [f, t]的预留映射。 b) 如果操作不能成功，region_abort被调用，在相同的范围[f, t]内中止操作。 @@ -307,7 +307,7 @@ COW和预留 如上所述，region_chg()确定该范围内当前没有在映射中表示的页面的数量。region_add()返回添加 到映射中的范围内的页数。在大多数情况下， region_add() 的返回值与 region_chg() 的返回值相 同。然而，在共享映射的情况下，有可能在调用 region_chg() 和 region_add() 之间对预留映射进 -行更改。在这种情况下，regi_add()的返回值将与regi_chg()的返回值不符。在这种情况下，全局计数 +行更改。在这种情况下，region_add()的返回值将与region_chg()的返回值不符。在这种情况下，全局计数 和子池计数很可能是不正确的，需要调整。检查这种情况并进行适当的调整是调用者的责任。 函数region_del()被调用以从预留映射中移除区域。 @@ -387,7 +387,7 @@ region_count()在解除私有巨页映射时被调用。在私有映射中，预 然而，有几种情况是，在一个巨页被分配后，但在它被实例化之前，就遇到了错误。在这种情况下， 页面分配已经消耗了预留，并进行了适当的子池、预留映射和全局计数调整。如果页面在这个时候被释放 -（在实例化和清除PagePrivate之前），那么free_huge_page将增加全局预留计数。然而，预留映射 +（在实例化和清除PagePrivate之前），那么free_huge_folio将增加全局预留计数。然而，预留映射 显示报留被消耗了。这种不一致的状态将导致预留的巨页的 “泄漏” 。全局预留计数将比它原本的要高， 并阻止分配一个预先分配的页面。 diff --git a/Documentation/translations/zh_CN/mm/index.rst b/Documentation/translations/zh_CN/mm/index.rst index 2f53e37b8049..b950dd118be7 100644 --- a/Documentation/translations/zh_CN/mm/index.rst +++ b/Documentation/translations/zh_CN/mm/index.rst @@ -42,7 +42,6 @@ Linux内存管理文档 damon/index free_page_reporting ksm - frontswap hmm hwpoison hugetlbfs_reserv diff --git a/Documentation/translations/zh_CN/mm/split_page_table_lock.rst b/Documentation/translations/zh_CN/mm/split_page_table_lock.rst index 4fb7aa666037..a2c288670a24 100644 --- a/Documentation/translations/zh_CN/mm/split_page_table_lock.rst +++ b/Documentation/translations/zh_CN/mm/split_page_table_lock.rst @@ -56,16 +56,16 @@ Hugetlb特定的辅助函数: 架构对分页表锁的支持 ==================== -没有必要特别启用PTE分页表锁：所有需要的东西都由pgtable_pte_page_ctor() -和pgtable_pte_page_dtor()完成，它们必须在PTE表分配/释放时被调用。 +没有必要特别启用PTE分页表锁：所有需要的东西都由pagetable_pte_ctor() +和pagetable_pte_dtor()完成，它们必须在PTE表分配/释放时被调用。 确保架构不使用slab分配器来分配页表：slab使用page->slab_cache来分配其页 面。这个区域与page->ptl共享存储。 PMD分页锁只有在你有两个以上的页表级别时才有意义。 -启用PMD分页锁需要在PMD表分配时调用pgtable_pmd_page_ctor()，在释放时调 -用pgtable_pmd_page_dtor()。 +启用PMD分页锁需要在PMD表分配时调用pagetable_pmd_ctor()，在释放时调 +用pagetable_pmd_dtor()。 分配通常发生在pmd_alloc_one()中，释放发生在pmd_free()和pmd_free_tlb() 中，但要确保覆盖所有的PMD表分配/释放路径：即X86_PAE在pgd_alloc()中预先 @@ -73,7 +73,7 @@ PMD分页锁只有在你有两个以上的页表级别时才有意义。 一切就绪后，你可以设置CONFIG_ARCH_ENABLE_SPLIT_PMD_PTLOCK。 -注意：pgtable_pte_page_ctor()和pgtable_pmd_page_ctor()可能失败--必 +注意：pagetable_pte_ctor()和pagetable_pmd_ctor()可能失败--必 须正确处理。 page->ptl @@ -90,7 +90,7 @@ page->ptl用于访问分割页表锁，其中'page'是包含该表的页面struc 的指针并动态分配它。这允许在启用DEBUG_SPINLOCK或DEBUG_LOCK_ALLOC的 情况下使用分页锁，但由于间接访问而多花了一个缓存行。 -PTE表的spinlock_t分配在pgtable_pte_page_ctor()中，PMD表的spinlock_t -分配在pgtable_pmd_page_ctor()中。 +PTE表的spinlock_t分配在pagetable_pte_ctor()中，PMD表的spinlock_t +分配在pagetable_pmd_ctor()中。 请不要直接访问page->ptl - -使用适当的辅助函数。 diff --git a/Documentation/translations/zh_CN/scheduler/sched-arch.rst b/Documentation/translations/zh_CN/scheduler/sched-arch.rst index ce3f39d9b3cb..b2ac3c743a3a 100644 --- a/Documentation/translations/zh_CN/scheduler/sched-arch.rst +++ b/Documentation/translations/zh_CN/scheduler/sched-arch.rst @@ -20,8 +20,7 @@ ========== 1. 运行队列锁 默认情况下，switch_to arch函数在调用时锁定了运行队列。这通常不是一个问题，除非 -switch_to可能需要获取运行队列锁。这通常是由于上下文切换中的唤醒操作造成的。见 -arch/ia64/include/asm/switch_to.h的例子。 +switch_to可能需要获取运行队列锁。这通常是由于上下文切换中的唤醒操作造成的。 为了要求调度器在运行队列解锁的情况下调用switch_to，你必须在头文件 中`#define __ARCH_WANT_UNLOCKED_CTXSW`(通常是定义switch_to的那个文件）。 @@ -68,7 +67,5 @@ arch/x86/kernel/process.c有轮询和睡眠空闲函数的例子。 我发现的可能的arch问题（并试图解决或没有解决）。: -ia64 - safe_halt的调用与中断相比，是否很荒谬？ (它睡眠了吗) (参考 #4a) - sparc - 在这一点上，IRQ是开着的（？），把local_irq_save改为_disable。 - 待办事项: 需要第二个CPU来禁用抢占 (参考 #1) diff --git a/Documentation/translations/zh_CN/subsystem-apis.rst b/Documentation/translations/zh_CN/subsystem-apis.rst new file mode 100644 index 000000000000..47780bb0772f --- /dev/null +++ b/Documentation/translations/zh_CN/subsystem-apis.rst @@ -0,0 +1,110 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ./disclaimer-zh_CN.rst + +:Original: Documentation/subsystem-apis.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +============== +内核子系统文档 +============== + +这些书籍从内核开发者的角度，详细介绍了特定内核子系统 +的如何工作。这里的大部分信息直接取自内核源代码，并 +根据需要添加了补充材料（或者至少是我们设法添加的 - 可 +能 *不是* 所有的材料都有需要）。 + +核心子系统 +---------- + +.. toctree:: + :maxdepth: 1 + + core-api/index + driver-api/index + mm/index + power/index + scheduler/index + locking/index + +TODOList: + +* timers/index + +人机接口 +-------- + +.. toctree:: + :maxdepth: 1 + + sound/index + +TODOList: + +* input/index +* hid/index +* gpu/index +* fb/index + +网络接口 +-------- + +.. toctree:: + :maxdepth: 1 + + infiniband/index + +TODOList: + +* networking/index +* netlabel/index +* isdn/index +* mhi/index + +存储接口 +-------- + +.. toctree:: + :maxdepth: 1 + + filesystems/index + +TODOList: + +* block/index +* cdrom/index +* scsi/index +* target/index + +**Fixme**: 这里还需要更多的分类组织工作。 + +.. toctree:: + :maxdepth: 1 + + accounting/index + cpu-freq/index + iio/index + virt/index + PCI/index + peci/index + +TODOList: + +* fpga/index +* i2c/index +* leds/index +* pcmcia/index +* spi/index +* w1/index +* watchdog/index +* hwmon/index +* accel/index +* security/index +* crypto/index +* bpf/index +* usb/index +* misc-devices/index +* wmi/index diff --git a/Documentation/translations/zh_TW/IRQ.txt b/Documentation/translations/zh_TW/IRQ.txt index 73d435a0d1e7..fd78ca720298 100644 --- a/Documentation/translations/zh_TW/IRQ.txt +++ b/Documentation/translations/zh_TW/IRQ.txt @@ -7,7 +7,7 @@ help. Contact the Chinese maintainer if this translation is outdated or if there is a problem with the translation. Maintainer: Eric W. Biederman <ebiederman@xmission.com> -Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> +Traditional Chinese maintainer: Hu Haowen <src.res.211@gmail.com> --------------------------------------------------------------------- Documentation/core-api/irq/index.rst 的繁體中文翻譯 @@ -16,9 +16,9 @@ Documentation/core-api/irq/index.rst 的繁體中文翻譯 者翻譯存在問題，請聯繫繁體中文版維護者。 英文版維護者： Eric W. Biederman <ebiederman@xmission.com> -繁體中文版維護者： 胡皓文 Hu Haowen <src.res@email.cn> -繁體中文版翻譯者： 胡皓文 Hu Haowen <src.res@email.cn> -繁體中文版校譯者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版維護者： 胡皓文 Hu Haowen <src.res.211@gmail.com> +繁體中文版翻譯者： 胡皓文 Hu Haowen <src.res.211@gmail.com> +繁體中文版校譯者： 胡皓文 Hu Haowen <src.res.211@gmail.com> 以下爲正文 diff --git a/Documentation/translations/zh_TW/admin-guide/README.rst b/Documentation/translations/zh_TW/admin-guide/README.rst index 6ce97edbab37..4cb581f5994a 100644 --- a/Documentation/translations/zh_TW/admin-guide/README.rst +++ b/Documentation/translations/zh_TW/admin-guide/README.rst @@ -7,18 +7,18 @@ :譯者: 吳想成 Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> -Linux內核5.x版本 <http://kernel.org/> +Linux內核6.x版本 <http://kernel.org/> ========================================= -以下是Linux版本5的發行註記。仔細閱讀它們， +以下是Linux版本6的發行註記。仔細閱讀它們， 它們會告訴你這些都是什麼，解釋如何安裝內核，以及遇到問題時該如何做。 什麼是Linux？ --------------- - Linux是Unix作業系統的克隆版本，由Linus Torvalds在一個鬆散的網絡黑客 + Linux是Unix操作系統的克隆版本，由Linus Torvalds在一個鬆散的網絡黑客 （Hacker，無貶義）團隊的幫助下從頭開始編寫。它旨在實現兼容POSIX和 單一UNIX規範。 @@ -28,7 +28,7 @@ Linux內核5.x版本 <http://kernel.org/> Linux在GNU通用公共許可證，版本2（GNU GPLv2）下分發，詳見隨附的COPYING文件。 -它能在什麼樣的硬體上運行？ +它能在什麼樣的硬件上運行？ ----------------------------- 雖然Linux最初是爲32位的x86 PC機（386或更高版本）開發的，但今天它也能運行在 @@ -40,16 +40,16 @@ Linux內核5.x版本 <http://kernel.org/> 單元（PMMU）和一個移植的GNU C編譯器（gcc；GNU Compiler Collection，GCC的一 部分）。Linux也被移植到許多沒有PMMU的體系架構中，儘管功能顯然受到了一定的 限制。 - Linux也被移植到了其自己上。現在可以將內核作爲用戶空間應用程式運行——這被 + Linux也被移植到了其自己上。現在可以將內核作爲用戶空間應用程序運行——這被 稱爲用戶模式Linux（UML）。 文檔 ----- -網際網路上和書籍上都有大量的電子文檔，既有Linux專屬文檔，也有與一般UNIX問題相關 +因特網上和書籍上都有大量的電子文檔，既有Linux專屬文檔，也有與一般UNIX問題相關 的文檔。我建議在任何Linux FTP站點上查找LDP（Linux文檔項目）書籍的文檔子目錄。 本自述文件並不是關於系統的文檔：有更好的可用資源。 - - 網際網路上和書籍上都有大量的（電子）文檔，既有Linux專屬文檔，也有與普通 + - 因特網上和書籍上都有大量的（電子）文檔，既有Linux專屬文檔，也有與普通 UNIX問題相關的文檔。我建議在任何有LDP（Linux文檔項目）書籍的Linux FTP 站點上查找文檔子目錄。本自述文件並不是關於系統的文檔：有更好的可用資源。 @@ -58,33 +58,33 @@ Linux內核5.x版本 <http://kernel.org/> :ref:`Documentation/process/changes.rst <changes>` 文件，它包含了升級內核 可能會導致的問題的相關信息。 -安裝內核原始碼 +安裝內核源代碼 --------------- - - 如果您要安裝完整的原始碼，請把內核tar檔案包放在您有權限的目錄中（例如您 + - 如果您要安裝完整的源代碼，請把內核tar檔案包放在您有權限的目錄中（例如您 的主目錄）並將其解包:: - xz -cd linux-5.x.tar.xz | tar xvf - + xz -cd linux-6.x.tar.xz | tar xvf - - 將「X」替換成最新內核的版本號。 + 將“X”替換成最新內核的版本號。 - 【不要】使用 /usr/src/linux 目錄！這裡有一組庫頭文件使用的內核頭文件 + 【不要】使用 /usr/src/linux 目錄！這裏有一組庫頭文件使用的內核頭文件 （通常是不完整的）。它們應該與庫匹配，而不是被內核的變化搞得一團糟。 - - 您還可以通過打補丁在5.x版本之間升級。補丁以xz格式分發。要通過打補丁進行 - 安裝，請獲取所有較新的補丁文件，進入內核原始碼（linux-5.x）的目錄並 + - 您還可以通過打補丁在6.x版本之間升級。補丁以xz格式分發。要通過打補丁進行 + 安裝，請獲取所有較新的補丁文件，進入內核源代碼（linux-6.x）的目錄並 執行:: - xz -cd ../patch-5.x.xz | patch -p1 + xz -cd ../patch-6.x.xz | patch -p1 - 請【按順序】替換所有大於當前原始碼樹版本的「x」，這樣就可以了。您可能想要 + 請【按順序】替換所有大於當前源代碼樹版本的“x”，這樣就可以了。您可能想要 刪除備份文件（文件名類似xxx~ 或 xxx.orig)，並確保沒有失敗的補丁（文件名 類似xxx# 或 xxx.rej）。如果有，不是你就是我犯了錯誤。 - 與5.x內核的補丁不同，5.x.y內核（也稱爲穩定版內核）的補丁不是增量的，而是 - 直接應用於基本的5.x內核。例如，如果您的基本內核是5.0，並且希望應用5.0.3 - 補丁，則不應先應用5.0.1和5.0.2的補丁。類似地，如果您運行的是5.0.2內核， - 並且希望跳轉到5.0.3，那麼在應用5.0.3補丁之前，必須首先撤銷5.0.2補丁 + 與6.x內核的補丁不同，6.x.y內核（也稱爲穩定版內核）的補丁不是增量的，而是 + 直接應用於基本的6.x內核。例如，如果您的基本內核是6.0，並且希望應用6.0.3 + 補丁，則不應先應用6.0.1和6.0.2的補丁。類似地，如果您運行的是6.0.2內核， + 並且希望跳轉到6.0.3，那麼在應用6.0.3補丁之前，必須首先撤銷6.0.2補丁 （即patch -R）。更多關於這方面的內容，請閱讀 :ref:`Documentation/process/applying-patches.rst <applying_patches>` 。 @@ -93,7 +93,7 @@ Linux內核5.x版本 <http://kernel.org/> linux/scripts/patch-kernel linux - 上面命令中的第一個參數是內核原始碼的位置。補丁是在當前目錄應用的，但是 + 上面命令中的第一個參數是內核源代碼的位置。補丁是在當前目錄應用的，但是 可以將另一個目錄指定爲第二個參數。 - 確保沒有過時的 .o 文件和依賴項:: @@ -101,30 +101,30 @@ Linux內核5.x版本 <http://kernel.org/> cd linux make mrproper - 現在您應該已經正確安裝了原始碼。 + 現在您應該已經正確安裝了源代碼。 -軟體要求 +軟件要求 --------- - 編譯和運行5.x內核需要各種軟體包的最新版本。請參考 + 編譯和運行6.x內核需要各種軟件包的最新版本。請參考 :ref:`Documentation/process/changes.rst <changes>` - 來了解最低版本要求以及如何升級軟體包。請注意，使用過舊版本的這些包可能會 + 來了解最低版本要求以及如何升級軟件包。請注意，使用過舊版本的這些包可能會 導致很難追蹤的間接錯誤，因此不要以爲在生成或操作過程中出現明顯問題時可以 只更新包。 爲內核建立目錄 --------------- - 編譯內核時，默認情況下所有輸出文件都將與內核原始碼放在一起。使用 + 編譯內核時，默認情況下所有輸出文件都將與內核源代碼放在一起。使用 ``make O=output/dir`` 選項可以爲輸出文件（包括 .config）指定備用位置。 例如:: - kernel source code: /usr/src/linux-5.x + kernel source code: /usr/src/linux-6.x build directory: /home/name/build/kernel 要配置和構建內核，請使用:: - cd /usr/src/linux-5.x + cd /usr/src/linux-6.x make O=/home/name/build/kernel menuconfig make O=/home/name/build/kernel sudo make O=/home/name/build/kernel modules_install install @@ -136,7 +136,7 @@ Linux內核5.x版本 <http://kernel.org/> 即使只升級一個小版本，也不要跳過此步驟。每個版本中都會添加新的配置選項， 如果配置文件沒有按預定設置，就會出現奇怪的問題。如果您想以最少的工作量 - 將現有配置升級到新版本，請使用 ``makeoldconfig`` ，它只會詢問您新配置 + 將現有配置升級到新版本，請使用 ``make oldconfig`` ，它只會詢問您新配置 選項的答案。 - 其他配置命令包括:: @@ -164,17 +164,17 @@ Linux內核5.x版本 <http://kernel.org/> "make ${PLATFORM}_defconfig" 使用arch/$arch/configs/${PLATFORM}_defconfig中 的默認選項值創建一個./.config文件。 - 用「makehelp」來獲取您體系架構中所有可用平台的列表。 + 用“make help”來獲取您體系架構中所有可用平臺的列表。 "make allyesconfig" - 通過儘可能將選項值設置爲「y」，創建一個 + 通過儘可能將選項值設置爲“y”，創建一個 ./.config文件。 "make allmodconfig" - 通過儘可能將選項值設置爲「m」，創建一個 + 通過儘可能將選項值設置爲“m”，創建一個 ./.config文件。 - "make allnoconfig" 通過儘可能將選項值設置爲「n」，創建一個 + "make allnoconfig" 通過儘可能將選項值設置爲“n”，創建一個 ./.config文件。 "make randconfig" 通過隨機設置選項值來創建./.config文件。 @@ -182,7 +182,7 @@ Linux內核5.x版本 <http://kernel.org/> "make localmodconfig" 基於當前配置和加載的模塊（lsmod）創建配置。禁用 已加載的模塊不需要的任何模塊選項。 - 要爲另一台計算機創建localmodconfig，請將該計算機 + 要爲另一臺計算機創建localmodconfig，請將該計算機 的lsmod存儲到一個文件中，並將其作爲lsmod參數傳入。 此外，通過在參數LMC_KEEP中指定模塊的路徑，可以將 @@ -200,9 +200,10 @@ Linux內核5.x版本 <http://kernel.org/> "make localyesconfig" 與localmodconfig類似，只是它會將所有模塊選項轉換 爲內置（=y）。你可以同時通過LMC_KEEP保留模塊。 - "make kvmconfig" 爲kvm客體內核支持啓用其他選項。 + "make kvm_guest.config" + 爲kvm客戶機內核支持啓用其他選項。 - "make xenconfig" 爲xen dom0客體內核支持啓用其他選項。 + "make xen.config" 爲xen dom0客戶機內核支持啓用其他選項。 "make tinyconfig" 配置儘可能小的內核。 @@ -218,10 +219,10 @@ Linux內核5.x版本 <http://kernel.org/> 這種情況下，數學仿真永遠不會被使用。內核會稍微大一點，但不管 是否有數學協處理器，都可以在不同的機器上工作。 - - 「kernel hacking」配置細節通常會導致更大或更慢的內核（或兩者 + - “kernel hacking”配置細節通常會導致更大或更慢的內核（或兩者 兼而有之），甚至可以通過配置一些例程來主動嘗試破壞壞代碼以發現 內核問題，從而降低內核的穩定性（kmalloc()）。因此，您可能應該 - 用於研究「開發」、「實驗」或「調試」特性相關問題。 + 用於研究“開發”、“實驗”或“調試”特性相關問題。 編譯內核 --------- @@ -229,10 +230,8 @@ Linux內核5.x版本 <http://kernel.org/> - 確保您至少有gcc 5.1可用。 有關更多信息，請參閱 :ref:`Documentation/process/changes.rst <changes>` 。 - 請注意，您仍然可以使用此內核運行a.out用戶程序。 - - 執行 ``make`` 來創建壓縮內核映像。如果您安裝了lilo以適配內核makefile， - 那麼也可以進行 ``makeinstall`` ，但是您可能需要先檢查特定的lilo設置。 + 那麼也可以進行 ``make install`` ，但是您可能需要先檢查特定的lilo設置。 實際安裝必須以root身份執行，但任何正常構建都不需要。 無須徒然使用root身份。 @@ -242,8 +241,8 @@ Linux內核5.x版本 <http://kernel.org/> - 詳細的內核編譯/生成輸出： 通常，內核構建系統在相當安靜的模式下運行（但不是完全安靜）。但是有時您或 - 其他內核開發人員需要看到編譯、連結或其他命令的執行過程。爲此，可使用 - 「verbose（詳細）」構建模式。 + 其他內核開發人員需要看到編譯、鏈接或其他命令的執行過程。爲此，可使用 + “verbose（詳細）”構建模式。 向 ``make`` 命令傳遞 ``V=1`` 來實現，例如:: make V=1 all @@ -255,15 +254,15 @@ Linux內核5.x版本 <http://kernel.org/> 與工作內核版本號相同的新內核，請在進行 ``make modules_install`` 安裝 之前備份modules目錄。 - 或者，在編譯之前，使用內核配置選項「LOCALVERSION」向常規內核版本附加 - 一個唯一的後綴。LOCALVERSION可以在「General Setup」菜單中設置。 + 或者，在編譯之前，使用內核配置選項“LOCALVERSION”向常規內核版本附加 + 一個唯一的後綴。LOCALVERSION可以在“General Setup”菜單中設置。 - 爲了引導新內核，您需要將內核映像（例如編譯後的 .../linux/arch/x86/boot/bzImage）複製到常規可引導內核的位置。 - 不再支持在沒有LILO等啓動裝載程序幫助的情況下直接從軟盤引導內核。 - 如果從硬碟引導Linux，很可能使用LILO，它使用/etc/lilo.conf文件中 + 如果從硬盤引導Linux，很可能使用LILO，它使用/etc/lilo.conf文件中 指定的內核映像文件。內核映像文件通常是/vmlinuz、/boot/vmlinuz、 /bzImage或/boot/bzImage。使用新內核前，請保存舊映像的副本，並複製 新映像覆蓋舊映像。然後您【必須重新運行LILO】來更新加載映射！否則， @@ -284,68 +283,13 @@ Linux內核5.x版本 <http://kernel.org/> 若遇到問題 ----------- - - 如果您發現了一些可能由於內核缺陷所導致的問題，請檢查MAINTAINERS（維護者） - 文件看看是否有人與令您遇到麻煩的內核部分相關。如果無人在此列出，那麼第二 - 個最好的方案就是把它們發給我（torvalds@linux-foundation.org），也可能發送 - 到任何其他相關的郵件列表或新聞組。 - - - 在所有的缺陷報告中，【請】告訴我們您在說什麼內核，如何復現問題，以及您的 - 設置是什麼的（使用您的常識）。如果問題是新的，請告訴我；如果問題是舊的， - 請嘗試告訴我您什麼時候首次注意到它。 - - - 如果缺陷導致如下消息:: - - unable to handle kernel paging request at address C0000010 - Oops: 0002 - EIP: 0010:XXXXXXXX - eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx - esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx - ds: xxxx es: xxxx fs: xxxx gs: xxxx - Pid: xx, process nr: xx - xx xx xx xx xx xx xx xx xx xx - - 或者類似的內核調試信息顯示在屏幕上或在系統日誌里，請【如實】複製它。 - 可能對你來說轉儲（dump）看起來不可理解，但它確實包含可能有助於調試問題的 - 信息。轉儲上方的文本也很重要：它說明了內核轉儲代碼的原因（在上面的示例中， - 是由於內核指針錯誤）。更多關於如何理解轉儲的信息，請參見 - Documentation/admin-guide/bug-hunting.rst。 - - - 如果使用 CONFIG_KALLSYMS 編譯內核，則可以按原樣發送轉儲，否則必須使用 - ``ksymoops`` 程序來理解轉儲（但通常首選使用CONFIG_KALLSYMS編譯）。 - 此實用程序可從 - https://www.kernel.org/pub/linux/utils/kernel/ksymoops/ 下載。 - 或者，您可以手動執行轉儲查找： - - - 在調試像上面這樣的轉儲時，如果您可以查找EIP值的含義，這將非常有幫助。 - 十六進位值本身對我或其他任何人都沒有太大幫助：它會取決於特定的內核設置。 - 您應該做的是從EIP行獲取十六進位值（忽略 ``0010:`` ），然後在內核名字列表 - 中查找它，以查看哪個內核函數包含有問題的地址。 - - 要找到內核函數名，您需要找到與顯示症狀的內核相關聯的系統二進位文件。就是 - 文件「linux/vmlinux」。要提取名字列表並將其與內核崩潰中的EIP進行匹配， - 請執行:: - - nm vmlinux | sort | less - - 這將爲您提供一個按升序排序的內核地址列表，從中很容易找到包含有問題的地址 - 的函數。請注意，內核調試消息提供的地址不一定與函數地址完全匹配（事實上， - 這是不可能的），因此您不能只「grep」列表：不過列表將爲您提供每個內核函數 - 的起點，因此通過查找起始地址低於你正在搜索的地址，但後一個函數的高於的 - 函數，你會找到您想要的。實際上，在您的問題報告中加入一些「上下文」可能是 - 一個好主意，給出相關的上下幾行。 - - 如果您由於某些原因無法完成上述操作（如您使用預編譯的內核映像或類似的映像）， - 請儘可能多地告訴我您的相關設置信息，這會有所幫助。有關詳細信息請閱讀 - 『Documentation/admin-guide/reporting-issues.rst』。 - - - 或者，您可以在正在運行的內核上使用gdb（只讀的；即不能更改值或設置斷點）。 - 爲此，請首先使用-g編譯內核；適當地編輯arch/x86/Makefile，然後執行 ``make - clean`` 。您還需要啓用CONFIG_PROC_FS（通過 ``make config`` ）。 - - 使用新內核重新啓動後，執行 ``gdb vmlinux /proc/kcore`` 。現在可以使用所有 - 普通的gdb命令。查找系統崩潰點的命令是 ``l *0xXXXXXXXX`` （將xxx替換爲EIP - 值）。 - - 用gdb無法調試一個當前未運行的內核是由於gdb（錯誤地）忽略了編譯內核的起始 - 偏移量。 +如果您發現了一些可能由於內核缺陷所導致的問題，請參閱： +Documentation/translations/zh_CN/admin-guide/reporting-issues.rst 。 + +想要理解內核錯誤報告，請參閱： +Documentation/translations/zh_CN/admin-guide/bug-hunting.rst 。 + +更多用GDB調試內核的信息，請參閱： +Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst +和 Documentation/dev-tools/kgdb.rst 。 diff --git a/Documentation/translations/zh_TW/admin-guide/bootconfig.rst b/Documentation/translations/zh_TW/admin-guide/bootconfig.rst new file mode 100644 index 000000000000..abac5aa60f67 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/bootconfig.rst @@ -0,0 +1,294 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/bootconfig.rst + +:譯者: 吳想成 Wu XiangCheng <bobwxc@email.cn> + +======== +引導配置 +======== + +:作者: Masami Hiramatsu <mhiramat@kernel.org> + +概述 +==== + +引導配置擴展了現有的內核命令行，以一種更有效率的方式在引導內核時進一步支持 +鍵值數據。這允許管理員傳遞一份結構化關鍵字的配置文件。 + +配置文件語法 +============ + +引導配置文件的語法採用非常簡單的鍵值結構。每個關鍵字由點連接的單詞組成，鍵 +和值由 ``=`` 連接。值以分號（ ``;`` ）或換行符（ ``\n`` ）結尾。數組值中每 +個元素由逗號（ ``,`` ）分隔。:: + + KEY[.WORD[...]] = VALUE[, VALUE2[...]][;] + +與內核命令行語法不同，逗號和 ``=`` 周圍允許有空格。 + +關鍵字只允許包含字母、數字、連字符（ ``-`` ）和下劃線（ ``_`` ）。值可包含 +可打印字符和空格，但分號（ ``;`` ）、換行符（ ``\n`` ）、逗號（ ``,`` ）、 +井號（ ``#`` ）和右大括號（ ``}`` ）等分隔符除外。 + +如果你需要在值中使用這些分隔符，可以用雙引號（ ``"VALUE"`` ）或單引號 +（ ``'VALUE'`` ）括起來。注意，引號無法轉義。 + +鍵的值可以爲空或不存在。這些鍵用於檢查該鍵是否存在（類似布爾值）。 + +鍵值語法 +-------- + +引導配置文件語法允許用戶通過大括號合併鍵名部分相同的關鍵字。例如:: + + foo.bar.baz = value1 + foo.bar.qux.quux = value2 + +也可以寫成:: + + foo.bar { + baz = value1 + qux.quux = value2 + } + +或者更緊湊一些，寫成:: + + foo.bar { baz = value1; qux.quux = value2 } + +在這兩種樣式中，引導解析時相同的關鍵字都會自動合併。因此可以追加類似的樹或 +鍵值。 + +相同關鍵字的值 +-------------- + +禁止兩個或多個值或數組共享同一個關鍵字。例如:: + + foo = bar, baz + foo = qux # !錯誤! 我們不可以重定義相同的關鍵字 + +如果你想要更新值，必須顯式使用覆蓋操作符 ``:=`` 。例如:: + + foo = bar, baz + foo := qux + +這樣 ``foo`` 關鍵字的值就變成了 ``qux`` 。這對於通過添加（部分）自定義引導 +配置來覆蓋默認值非常有用，免於解析默認引導配置。 + +如果你想對現有關鍵字追加值作爲數組成員，可以使用 ``+=`` 操作符。例如:: + + foo = bar, baz + foo += qux + +這樣， ``foo`` 關鍵字就同時擁有了 ``bar`` ， ``baz`` 和 ``qux`` 。 + +此外，父關鍵字下可同時存在值和子關鍵字。 +例如，下列配置是可行的。:: + + foo = value1 + foo.bar = value2 + foo := value3 # 這會更新foo的值。 + +注意，裸值不能直接放進結構化關鍵字中，必須在大括號外定義它。例如:: + + foo { + bar = value1 + bar { + baz = value2 + qux = value3 + } + } + +同時，關鍵字下值節點的順序是固定的。如果值和子關鍵字同時存在，值永遠是該關 +鍵字的第一個子節點。因此如果用戶先指定子關鍵字，如:: + + foo.bar = value1 + foo = value2 + +則在程序（和/proc/bootconfig）中，它會按如下顯示:: + + foo = value2 + foo.bar = value1 + +註釋 +---- + +配置語法接受shell腳本風格的註釋。註釋以井號（ ``#`` ）開始，到換行符 +（ ``\n`` ）結束。 + +:: + + # comment line + foo = value # value is set to foo. + bar = 1, # 1st element + 2, # 2nd element + 3 # 3rd element + +會被解析爲:: + + foo = value + bar = 1, 2, 3 + +注意你不能把註釋放在值和分隔符（ ``,`` 或 ``;`` ）之間。如下配置語法是錯誤的:: + + key = 1 # comment + ,2 + + +/proc/bootconfig +================ + +/proc/bootconfig是引導配置的用戶空間接口。與/proc/cmdline不同，此文件內容以 +鍵值列表樣式顯示。 +每個鍵值對一行，樣式如下:: + + KEY[.WORDS...] = "[VALUE]"[,"VALUE2"...] + + +用引導配置引導內核 +================== + +用引導配置引導內核有兩種方法：將引導配置附加到initrd鏡像或直接嵌入內核中。 + +*initrd: initial RAM disk，初始內存磁盤* + +將引導配置附加到initrd +---------------------- + +由於默認情況下引導配置文件是用initrd加載的，因此它將被添加到initrd（initramfs） +鏡像文件的末尾，其中包含填充、大小、校驗值和12字節幻數，如下所示:: + + [initrd][bootconfig][padding][size(le32)][checksum(le32)][#BOOTCONFIG\n] + +大小和校驗值爲小端序存放的32位無符號值。 + +當引導配置被加到initrd鏡像時，整個文件大小會對齊到4字節。空字符（ ``\0`` ） +會填補對齊空隙。因此 ``size`` 就是引導配置文件的長度+填充的字節。 + +Linux內核在內存中解碼initrd鏡像的最後部分以獲取引導配置數據。由於這種“揹負式” +的方法，只要引導加載器傳遞了正確的initrd文件大小，就無需更改或更新引導加載器 +和內核鏡像本身。如果引導加載器意外傳遞了更長的大小，內核將無法找到引導配置數 +據。 + +Linux內核在tools/bootconfig下提供了 ``bootconfig`` 命令來完成此操作，管理員 +可以用它從initrd鏡像中刪除或追加配置文件。你可以用以下命令來構建它:: + + # make -C tools/bootconfig + +要向initrd鏡像添加你的引導配置文件，請按如下命令操作（舊數據會自動移除）:: + + # tools/bootconfig/bootconfig -a your-config /boot/initrd.img-X.Y.Z + +要從鏡像中移除配置，可以使用-d選項:: + + # tools/bootconfig/bootconfig -d /boot/initrd.img-X.Y.Z + +然後在內核命令行上添加 ``bootconfig`` 告訴內核去initrd文件末尾尋找內核配置。 + +將引導配置嵌入內核 +------------------ + +如果你不能使用initrd，也可以通過Kconfig選項將引導配置文件嵌入內核中。在此情 +況下，你需要用以下選項重新編譯內核:: + + CONFIG_BOOT_CONFIG_EMBED=y + CONFIG_BOOT_CONFIG_EMBED_FILE="/引導配置/文件/的/路徑" + +``CONFIG_BOOT_CONFIG_EMBED_FILE`` 需要從源碼樹或對象樹開始的引導配置文件的 +絕對/相對路徑。內核會將其嵌入作爲默認引導配置。 + +與將引導配置附加到initrd一樣，你也需要在內核命令行上添加 ``bootconfig`` 告訴 +內核去啓用內嵌的引導配置。 + +注意，即使你已經設置了此選項，仍可用附加到initrd的其他引導配置覆蓋內嵌的引導 +配置。 + +通過引導配置傳遞內核參數 +======================== + +除了內核命令行，引導配置也可以用於傳遞內核參數。所有 ``kernel`` 關鍵字下的鍵 +值對都將直接傳遞給內核命令行。此外， ``init`` 下的鍵值對將通過命令行傳遞給 +init進程。參數按以下順序與用戶給定的內核命令行字符串相連，因此命令行參數可以 +覆蓋引導配置參數（這取決於子系統如何處理參數，但通常前面的參數將被後面的參數 +覆蓋）:: + + [bootconfig params][cmdline params] -- [bootconfig init params][cmdline init params] + +如果引導配置文件給出的kernel/init參數是:: + + kernel { + root = 01234567-89ab-cdef-0123-456789abcd + } + init { + splash + } + +這將被複制到內核命令行字符串中，如下所示:: + + root="01234567-89ab-cdef-0123-456789abcd" -- splash + +如果用戶給出的其他命令行是:: + + ro bootconfig -- quiet + +則最後的內核命令行如下:: + + root="01234567-89ab-cdef-0123-456789abcd" ro bootconfig -- splash quiet + + +配置文件的限制 +============== + +當前最大的配置大小是32KB，關鍵字總數（不是鍵值條目）必須少於1024個節點。 +注意：這不是條目數而是節點數，條目必須消耗超過2個節點（一個關鍵字和一個值）。 +所以從理論上講最多512個鍵值對。如果關鍵字平均包含3個單詞，則可有256個鍵值對。 +在大多數情況下，配置項的數量將少於100個條目，小於8KB，因此這應該足夠了。如果 +節點數超過1024，解析器將返回錯誤，即使文件大小小於32KB。（請注意，此最大尺寸 +不包括填充的空字符。） +無論如何，因爲 ``bootconfig`` 命令在附加啓動配置到initrd映像時會驗證它，用戶 +可以在引導之前注意到它。 + + +引導配置API +=========== + +用戶可以查詢或遍歷鍵值對，也可以查找（前綴）根關鍵字節點，並在查找該節點下的 +鍵值。 + +如果您有一個關鍵字字符串，則可以直接使用 xbc_find_value() 查詢該鍵的值。如果 +你想知道引導配置裏有哪些關鍵字，可以使用 xbc_for_each_key_value() 迭代鍵值對。 +請注意，您需要使用 xbc_array_for_each_value() 訪問數組的值，例如:: + + vnode = NULL; + xbc_find_value("key.word", &vnode); + if (vnode && xbc_node_is_array(vnode)) + xbc_array_for_each_value(vnode, value) { + printk("%s ", value); + } + +如果您想查找具有前綴字符串的鍵，可以使用 xbc_find_node() 通過前綴字符串查找 +節點，然後用 xbc_node_for_each_key_value() 迭代前綴節點下的鍵。 + +但最典型的用法是獲取前綴下的命名值或前綴下的命名數組，例如:: + + root = xbc_find_node("key.prefix"); + value = xbc_node_find_value(root, "option", &vnode); + ... + xbc_node_for_each_array_value(root, "array-option", value, anode) { + ... + } + +這將訪問值“key.prefix.option”的值和“key.prefix.array-option”的數組。 + +鎖是不需要的，因爲在初始化之後配置只讀。如果需要修改，必須複製所有數據和關鍵字。 + + +函數與結構體 +============ + +相關定義的kernel-doc參見： + + - include/linux/bootconfig.h + - lib/bootconfig.c + diff --git a/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst b/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst index 41a39aebb8d6..3f10a9f8f223 100644 --- a/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst +++ b/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst @@ -7,7 +7,7 @@ :譯者: 吳想成 Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> 二分（bisect）缺陷 +++++++++++++++++++ @@ -17,14 +17,14 @@ 引言 ===== -始終嘗試由來自kernel.org的原始碼構建的最新內核。如果您沒有信心這樣做，請將 +始終嘗試由來自kernel.org的源代碼構建的最新內核。如果您沒有信心這樣做，請將 錯誤報告給您的發行版供應商，而不是內核開發人員。 找到缺陷（bug）並不總是那麼容易，不過仍然得去找。如果你找不到它，不要放棄。 -儘可能多的向相關維護人員報告您發現的信息。請參閱MAINTAINERS文件以了解您所 +儘可能多的向相關維護人員報告您發現的信息。請參閱MAINTAINERS文件以瞭解您所 關注的子系統的維護人員。 -在提交錯誤報告之前，請閱讀「Documentation/admin-guide/reporting-issues.rst」。 +在提交錯誤報告之前，請閱讀“Documentation/admin-guide/reporting-issues.rst”。 設備未出現（Devices not appearing） ==================================== @@ -38,7 +38,7 @@ 操作步驟： -- 從git原始碼構建內核 +- 從git源代碼構建內核 - 以此開始二分 [#f1]_:: $ git bisect start @@ -76,7 +76,7 @@ 如需進一步參考，請閱讀： - ``git-bisect`` 的手冊頁 -- `Fighting regressions with git bisect（用git bisect解決回歸） +- `Fighting regressions with git bisect（用git bisect解決迴歸） <https://www.kernel.org/pub/software/scm/git/docs/git-bisect-lk2009.html>`_ - `Fully automated bisecting with "git bisect run"（使用git bisect run 來全自動二分） <https://lwn.net/Articles/317154>`_ diff --git a/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst b/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst index 4d813aec77d2..631fd2650929 100644 --- a/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst +++ b/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst @@ -7,7 +7,7 @@ :譯者: 吳想成 Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> 追蹤缺陷 ========= @@ -48,8 +48,8 @@ [<c1549f43>] ? sysenter_past_esp+0x40/0x6a ---[ end trace 6ebc60ef3981792f ]--- -這樣的堆棧跟蹤提供了足夠的信息來識別內核原始碼中發生錯誤的那一行。根據問題的 -嚴重性，它還可能包含 **「Oops」** 一詞，比如:: +這樣的堆棧跟蹤提供了足夠的信息來識別內核源代碼中發生錯誤的那一行。根據問題的 +嚴重性，它還可能包含 **“Oops”** 一詞，比如:: BUG: unable to handle kernel NULL pointer dereference at (null) IP: [<c06969d4>] iret_exc+0x7d0/0xa59 @@ -58,17 +58,17 @@ ... 儘管有 **Oops** 或其他類型的堆棧跟蹤，但通常需要找到出問題的行來識別和處理缺 -陷。在本章中，我們將參考「Oops」來了解需要分析的各種堆棧跟蹤。 +陷。在本章中，我們將參考“Oops”來了解需要分析的各種堆棧跟蹤。 如果內核是用 ``CONFIG_DEBUG_INFO`` 編譯的，那麼可以使用文件： `scripts/decode_stacktrace.sh` 。 -連結的模塊 +鏈接的模塊 ----------- -受到汙染或正在加載/卸載的模塊用「（…）」標記，汙染標誌在 -`Documentation/admin-guide/tainted-kernels.rst` 文件中進行了描述，「正在被加 -載」用「+」標註，「正在被卸載」用「-」標註。 +受到污染或正在加載/卸載的模塊用“（…）”標記，污染標誌在 +`Documentation/admin-guide/tainted-kernels.rst` 文件中進行了描述，“正在被加 +載”用“+”標註，“正在被卸載”用“-”標註。 Oops消息在哪？ @@ -81,19 +81,19 @@ syslog文件，通常是 ``/var/log/messages`` （取決於 ``/etc/syslog.conf`` 有時 ``klogd`` 會掛掉，這種情況下您可以運行 ``dmesg > file`` 從內核緩衝區 讀取數據並保存它。或者您可以 ``cat /proc/kmsg > file`` ，但是您必須適時 -中斷以停止傳輸，因爲 ``kmsg`` 是一個「永無止境的文件」。 +中斷以停止傳輸，因爲 ``kmsg`` 是一個“永無止境的文件”。 -如果機器嚴重崩潰，無法輸入命令或磁碟不可用，那還有三個選項： +如果機器嚴重崩潰，無法輸入命令或磁盤不可用，那還有三個選項： (1) 手動複製屏幕上的文本，並在機器重新啓動後輸入。很難受，但這是突然崩潰下 - 唯一的選擇。或者你可以用數位相機拍下屏幕——雖然不那麼好，但總比什麼都沒 - 有好。如果消息滾動超出控制台頂部，使用更高解析度（例如 ``vga=791`` ） - 引導啓動將允許您閱讀更多文本。（警告：這需要 ``vesafb`` ，因此對「早期」 + 唯一的選擇。或者你可以用數碼相機拍下屏幕——雖然不那麼好，但總比什麼都沒 + 有好。如果消息滾動超出控制檯頂部，使用更高分辨率（例如 ``vga=791`` ） + 引導啓動將允許您閱讀更多文本。（警告：這需要 ``vesafb`` ，因此對“早期” 的Oppses沒有幫助） (2) 從串口終端啓動（參見 :ref:`Documentation/admin-guide/serial-console.rst <serial_console>` ）， - 在另一台機器上運行數據機然後用你喜歡的通信程序捕獲輸出。 + 在另一臺機器上運行調制解調器然後用你喜歡的通信程序捕獲輸出。 Minicom運行良好。 (3) 使用Kdump（參閱 Documentation/admin-guide/kdump/kdump.rst ），使用 @@ -103,7 +103,7 @@ syslog文件，通常是 ``/var/log/messages`` （取決於 ``/etc/syslog.conf`` 找到缺陷位置 ------------- -如果你能指出缺陷在內核原始碼中的位置，則報告缺陷的效果會非常好。這有兩種方法。 +如果你能指出缺陷在內核源代碼中的位置，則報告缺陷的效果會非常好。這有兩種方法。 通常來說使用 ``gdb`` 會比較容易，不過內核需要用調試信息來預編譯。 gdb @@ -187,7 +187,7 @@ GNU 調試器（GNU debugger， ``gdb`` ）是從 ``vmlinux`` 文件中找出OOP objdump ^^^^^^^^ -要調試內核，請使用objdump並從崩潰輸出中查找十六進位偏移，以找到有效的代碼/匯 +要調試內核，請使用objdump並從崩潰輸出中查找十六進制偏移，以找到有效的代碼/匯 編行。如果沒有調試符號，您將看到所示例程的彙編程序代碼，但是如果內核有調試 符號，C代碼也將可見（調試符號可以在內核配置菜單的hacking項中啓用）。例如:: @@ -197,7 +197,7 @@ objdump 您需要處於內核樹的頂層以便此獲得您的C文件。 -如果您無法訪問原始碼，仍然可以使用以下方法調試一些崩潰轉儲（如Dave Miller的 +如果您無法訪問源代碼，仍然可以使用以下方法調試一些崩潰轉儲（如Dave Miller的 示例崩潰轉儲輸出所示）:: EIP is at +0x14/0x4c0 @@ -234,9 +234,9 @@ objdump 報告缺陷 --------- -一旦你通過定位缺陷找到了其發生的地方，你可以嘗試自己修復它或者向上游報告它。 +一旦你通過定位缺陷找到了其發生的地方，你可以嘗試自己修復它或者向上遊報告它。 -爲了向上游報告，您應該找出用於開發受影響代碼的郵件列表。這可以使用 ``get_maintainer.pl`` 。 +爲了向上遊報告，您應該找出用於開發受影響代碼的郵件列表。這可以使用 ``get_maintainer.pl`` 。 例如，您在gspca的sonixj.c文件中發現一個缺陷，則可以通過以下方法找到它的維護者:: @@ -251,7 +251,7 @@ objdump 請注意它將指出： -- 最後接觸原始碼的開發人員（如果這是在git樹中完成的）。在上面的例子中是Tejun +- 最後接觸源代碼的開發人員（如果這是在git樹中完成的）。在上面的例子中是Tejun 和Bhaktipriya（在這個特定的案例中，沒有人真正參與這個文件的開發）； - 驅動維護人員（Hans Verkuil）； - 子系統維護人員（Mauro Carvalho Chehab）； diff --git a/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst b/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst index bdc1a22046cf..6961006b4a2d 100644 --- a/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst +++ b/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst @@ -2,15 +2,15 @@ .. include:: ../disclaimer-zh_TW.rst -:Translator: 胡皓文 Hu Haowen <src.res@email.cn> +:Translator: 胡皓文 Hu Haowen <src.res.211@gmail.com> 清除 WARN_ONCE -------------- -WARN_ONCE / WARN_ON_ONCE / printk_once 僅僅列印一次消息. +WARN_ONCE / WARN_ON_ONCE / printk_once 僅僅打印一次消息. echo 1 > /sys/kernel/debug/clear_warn_once -可以清除這種狀態並且再次允許列印一次告警信息，這對於運行測試集後重現問題 +可以清除這種狀態並且再次允許打印一次告警信息，這對於運行測試集後重現問題 很有用。 diff --git a/Documentation/translations/zh_TW/admin-guide/cpu-load.rst b/Documentation/translations/zh_TW/admin-guide/cpu-load.rst index be087cef1967..cc046f3b7ffa 100644 --- a/Documentation/translations/zh_TW/admin-guide/cpu-load.rst +++ b/Documentation/translations/zh_TW/admin-guide/cpu-load.rst @@ -2,7 +2,7 @@ .. include:: ../disclaimer-zh_TW.rst -:Translator: 胡皓文 Hu Haowen <src.res@email.cn> +:Translator: 胡皓文 Hu Haowen <src.res.211@gmail.com> ======== CPU 負載 @@ -20,13 +20,13 @@ Linux通過``/proc/stat``和``/proc/uptime``導出各種信息，用戶空間工 ... -這裡系統認爲在默認採樣周期內有10.01%的時間工作在用戶空間，2.92%的時 +這裏系統認爲在默認採樣週期內有10.01%的時間工作在用戶空間，2.92%的時 間用在系統空間，總體上有81.63%的時間是空閒的。 大多數情況下``/proc/stat``的信息幾乎真實反映了系統信息，然而，由於內 核採集這些數據的方式/時間的特點，有時這些信息根本不可靠。 -那麼這些信息是如何被搜集的呢？每當時間中斷觸發時，內核查看此刻運行的 +那麼這些信息是如何被蒐集的呢？每當時間中斷觸發時，內核查看此刻運行的 進程類型，並增加與此類型/狀態進程對應的計數器的值。這種方法的問題是 在兩次時間中斷之間系統（進程）能夠在多種狀態之間切換多次，而計數器只 增加最後一種狀態下的計數。 @@ -34,7 +34,7 @@ Linux通過``/proc/stat``和``/proc/uptime``導出各種信息，用戶空間工 舉例 --- -假設系統有一個進程以如下方式周期性地占用cpu:: +假設系統有一個進程以如下方式週期性地佔用cpu:: 兩個時鐘中斷之間的時間線 |-----------------------| @@ -46,7 +46,7 @@ Linux通過``/proc/stat``和``/proc/uptime``導出各種信息，用戶空間工 在上面的情況下，根據``/proc/stat``的信息（由於當系統處於空閒狀態時， 時間中斷經常會發生）系統的負載將會是0 -大家能夠想像內核的這種行爲會發生在許多情況下，這將導致``/proc/stat`` +大家能夠想象內核的這種行爲會發生在許多情況下，這將導致``/proc/stat`` 中存在相當古怪的信息:: /* gcc -o hog smallhog.c */ diff --git a/Documentation/translations/zh_TW/admin-guide/cputopology.rst b/Documentation/translations/zh_TW/admin-guide/cputopology.rst new file mode 100644 index 000000000000..5c46d1b3b065 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/cputopology.rst @@ -0,0 +1,97 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/cputopology.rst + +:翻譯: + + 唐藝舟 Tang Yizhou <tangyeechou@gmail.com> + +========================== +如何通過sysfs將CPU拓撲導出 +========================== + +CPU拓撲信息通過sysfs導出。顯示的項（屬性）和某些架構的/proc/cpuinfo輸出相似。它們位於 +/sys/devices/system/cpu/cpuX/topology/。請閱讀ABI文件： +Documentation/ABI/stable/sysfs-devices-system-cpu。 + +drivers/base/topology.c是體系結構中性的，它導出了這些屬性。然而，die、cluster、book、 +draw這些層次結構相關的文件僅在體系結構提供了下文描述的宏的條件下被創建。 + +對於支持這個特性的體系結構，它必須在include/asm-XXX/topology.h中定義這些宏中的一部分:: + + #define topology_physical_package_id(cpu) + #define topology_die_id(cpu) + #define topology_cluster_id(cpu) + #define topology_core_id(cpu) + #define topology_book_id(cpu) + #define topology_drawer_id(cpu) + #define topology_sibling_cpumask(cpu) + #define topology_core_cpumask(cpu) + #define topology_cluster_cpumask(cpu) + #define topology_die_cpumask(cpu) + #define topology_book_cpumask(cpu) + #define topology_drawer_cpumask(cpu) + +``**_id macros`` 的類型是int。 +``**_cpumask macros`` 的類型是 ``(const) struct cpumask *`` 。後者和恰當的 +``**_siblings`` sysfs屬性對應（除了topology_sibling_cpumask()，它和thread_siblings +對應）。 + +爲了在所有體系結構上保持一致，include/linux/topology.h提供了上述所有宏的默認定義，以防 +它們未在include/asm-XXX/topology.h中定義: + +1) topology_physical_package_id: -1 +2) topology_die_id: -1 +3) topology_cluster_id: -1 +4) topology_core_id: 0 +5) topology_book_id: -1 +6) topology_drawer_id: -1 +7) topology_sibling_cpumask: 僅入參CPU +8) topology_core_cpumask: 僅入參CPU +9) topology_cluster_cpumask: 僅入參CPU +10) topology_die_cpumask: 僅入參CPU +11) topology_book_cpumask: 僅入參CPU +12) topology_drawer_cpumask: 僅入參CPU + +此外，CPU拓撲信息由/sys/devices/system/cpu提供，包含下述文件。輸出對應的內部數據源放在 +方括號（"[]"）中。 + + =========== ================================================================== + kernel_max: 內核配置允許的最大CPU下標值。[NR_CPUS-1] + + offline: 由於熱插拔移除或者超過內核允許的CPU上限（上文描述的kernel_max） + 導致未上線的CPU。[~cpu_online_mask + cpus >= NR_CPUS] + + online: 在線的CPU，可供調度使用。[cpu_online_mask] + + possible: 已被分配資源的CPU，如果它們CPU實際存在，可以上線。 + [cpu_possible_mask] + + present: 被系統識別實際存在的CPU。[cpu_present_mask] + =========== ================================================================== + +上述輸出的格式和cpulist_parse()兼容[參見 <linux/cpumask.h>]。下面給些例子。 + +在本例中，系統中有64個CPU，但是CPU 32-63超過了kernel_max值，因爲NR_CPUS配置項是32， +取值範圍被限制爲0..31。此外注意CPU2和4-31未上線，但是可以上線，因爲它們同時存在於 +present和possible:: + + kernel_max: 31 + offline: 2,4-31,32-63 + online: 0-1,3 + possible: 0-31 + present: 0-31 + +在本例中，NR_CPUS配置項是128，但內核啓動時設置possible_cpus=144。系統中有4個CPU， +CPU2被手動設置下線（也是唯一一個可以上線的CPU）:: + + kernel_max: 127 + offline: 2,4-127,128-143 + online: 0-1,3 + possible: 0-127 + present: 0-3 + +閱讀Documentation/core-api/cpu_hotplug.rst可瞭解開機參數possible_cpus=NUM，同時還 +可以瞭解各種cpumask的信息。 + diff --git a/Documentation/translations/zh_TW/admin-guide/index.rst b/Documentation/translations/zh_TW/admin-guide/index.rst index 293c20245783..aba8939351e0 100644 --- a/Documentation/translations/zh_TW/admin-guide/index.rst +++ b/Documentation/translations/zh_TW/admin-guide/index.rst @@ -3,13 +3,14 @@ .. include:: ../disclaimer-zh_TW.rst :Original: :doc:`../../../admin-guide/index` -:Translator: 胡皓文 Hu Haowen <src.res@email.cn> +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + 胡皓文 Hu Haowen <src.res.211@gmail.com> Linux 內核用戶和管理員指南 ========================== 下面是一組隨時間添加到內核中的面向用戶的文檔的集合。到目前爲止，還沒有一個 -整體的順序或組織 - 這些材料不是一個單一的，連貫的文件！幸運的話，情況會隨著 +整體的順序或組織 - 這些材料不是一個單一的，連貫的文件！幸運的話，情況會隨着 時間的推移而迅速改善。 這個初始部分包含總體信息，包括描述內核的README， 關於內核參數的文檔等。 @@ -21,15 +22,15 @@ Linux 內核用戶和管理員指南 Todolist: - kernel-parameters - devices - sysctl/index +* kernel-parameters +* devices +* sysctl/index 本節介紹CPU漏洞及其緩解措施。 Todolist: - hw-vuln/index +* hw-vuln/index 下面的一組文檔，針對的是試圖跟蹤問題和bug的用戶。 @@ -37,6 +38,7 @@ Todolist: :maxdepth: 1 reporting-issues + reporting-regressions security-bugs bug-hunting bug-bisect @@ -45,18 +47,17 @@ Todolist: Todolist: - reporting-bugs - ramoops - dynamic-debug-howto - kdump/index - perf/index +* ramoops +* dynamic-debug-howto +* kdump/index +* perf/index -這是應用程式開發人員感興趣的章節的開始。可以在這裡找到涵蓋內核ABI各個 +這是應用程序開發人員感興趣的章節的開始。可以在這裏找到涵蓋內核ABI各個 方面的文檔。 Todolist: - sysfs-rules +* sysfs-rules 本手冊的其餘部分包括各種指南，介紹如何根據您的喜好配置內核的特定行爲。 @@ -64,67 +65,67 @@ Todolist: .. toctree:: :maxdepth: 1 + bootconfig clearing-warn-once cpu-load + cputopology + lockup-watchdogs unicode + sysrq + mm/index Todolist: - acpi/index - aoe/index - auxdisplay/index - bcache - binderfs - binfmt-misc - blockdev/index - bootconfig - braille-console - btmrvl - cgroup-v1/index - cgroup-v2 - cifs/index - cputopology - dell_rbu - device-mapper/index - edid - efi-stub - ext4 - nfs/index - gpio/index - highuid - hw_random - initrd - iostats - java - jfs - kernel-per-CPU-kthreads - laptops/index - lcd-panel-cgram - ldm - lockup-watchdogs - LSM/index - md - media/index - mm/index - module-signing - mono - namespaces/index - numastat - parport - perf-security - pm/index - pnp - rapidio - ras - rtc - serial-console - svga - sysrq - thunderbolt - ufs - vga-softcursor - video-output - xfs +* acpi/index +* aoe/index +* auxdisplay/index +* bcache +* binderfs +* binfmt-misc +* blockdev/index +* braille-console +* btmrvl +* cgroup-v1/index +* cgroup-v2 +* cifs/index +* dell_rbu +* device-mapper/index +* edid +* efi-stub +* ext4 +* nfs/index +* gpio/index +* highuid +* hw_random +* initrd +* iostats +* java +* jfs +* kernel-per-CPU-kthreads +* laptops/index +* lcd-panel-cgram +* ldm +* LSM/index +* md +* media/index +* module-signing +* mono +* namespaces/index +* numastat +* parport +* perf-security +* pm/index +* pnp +* rapidio +* ras +* rtc +* serial-console +* svga +* thunderbolt +* ufs +* vga-softcursor +* video-output +* xfs .. only:: subproject and html diff --git a/Documentation/translations/zh_TW/admin-guide/init.rst b/Documentation/translations/zh_TW/admin-guide/init.rst index 32cdf134948f..be6e34f5f7fa 100644 --- a/Documentation/translations/zh_TW/admin-guide/init.rst +++ b/Documentation/translations/zh_TW/admin-guide/init.rst @@ -7,10 +7,10 @@ :譯者: 吳想成 Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> -解釋「No working init found.」啓動掛起消息 -========================================== +解釋“No working init found.”啓動掛起消息 +========================================= :作者: @@ -18,41 +18,41 @@ Cristian Souza <cristianmsbr at gmail period com> -本文檔提供了加載初始化二進位（init binary）失敗的一些高層級原因（大致按執行 +本文檔提供了加載初始化二進制（init binary）失敗的一些高層級原因（大致按執行 順序列出）。 -1) **無法掛載根文件系統Unable to mount root FS** ：請設置「debug」內核參數（在 +1) **無法掛載根文件系統Unable to mount root FS** ：請設置“debug”內核參數（在 引導加載程序bootloader配置文件或CONFIG_CMDLINE）以獲取更詳細的內核消息。 -2) **初始化二進位不存在於根文件系統上init binary doesn't exist on rootfs** ： +2) **初始化二進制不存在於根文件系統上init binary doesn't exist on rootfs** ： 確保您的根文件系統類型正確（並且 ``root=`` 內核參數指向正確的分區）；擁有 - 所需的驅動程序，例如SCSI或USB等存儲硬體；文件系統（ext3、jffs2等）是內建的 + 所需的驅動程序，例如SCSI或USB等存儲硬件；文件系統（ext3、jffs2等）是內建的 （或者作爲模塊由initrd預加載）。 -3) **控制台設備損壞Broken console device** ： ``console= setup`` 中可能存在 - 衝突 --> 初始控制台不可用（initial console unavailable）。例如，由於串行 - IRQ問題（如缺少基於中斷的配置）導致的某些串行控制台不可靠。嘗試使用不同的 +3) **控制檯設備損壞Broken console device** ： ``console= setup`` 中可能存在 + 衝突 --> 初始控制檯不可用（initial console unavailable）。例如，由於串行 + IRQ問題（如缺少基於中斷的配置）導致的某些串行控制檯不可靠。嘗試使用不同的 ``console= device`` 或像 ``netconsole=`` 。 -4) **二進位存在但依賴項不可用Binary exists but dependencies not available** ： - 例如初始化二進位的必需庫依賴項，像 ``/lib/ld-linux.so.2`` 丟失或損壞。使用 +4) **二進制存在但依賴項不可用Binary exists but dependencies not available** ： + 例如初始化二進制的必需庫依賴項，像 ``/lib/ld-linux.so.2`` 丟失或損壞。使用 ``readelf -d <INIT>|grep NEEDED`` 找出需要哪些庫。 -5) **無法加載二進位Binary cannot be loaded** ：請確保二進位的體系結構與您的 - 硬體匹配。例如i386不匹配x86_64，或者嘗試在ARM硬體上加載x86。如果您嘗試在 - 此處加載非二進位文件（shell腳本？），您應該確保腳本在其工作頭（shebang +5) **無法加載二進制Binary cannot be loaded** ：請確保二進制的體系結構與您的 + 硬件匹配。例如i386不匹配x86_64，或者嘗試在ARM硬件上加載x86。如果您嘗試在 + 此處加載非二進制文件（shell腳本？），您應該確保腳本在其工作頭（shebang header）行 ``#!/...`` 中指定能正常工作的解釋器（包括其庫依賴項）。在處理 - 腳本之前，最好先測試一個簡單的非腳本二進位文件，比如 ``/bin/sh`` ，並確認 + 腳本之前，最好先測試一個簡單的非腳本二進制文件，比如 ``/bin/sh`` ，並確認 它能成功執行。要了解更多信息，請將代碼添加到 ``init/main.c`` 以顯示 kernel_execve()的返回值。 -當您發現新的失敗原因時，請擴展本解釋（畢竟加載初始化二進位是一個 **關鍵** 且 +當您發現新的失敗原因時，請擴展本解釋（畢竟加載初始化二進制是一個 **關鍵** 且 艱難的過渡步驟，需要儘可能無痛地進行），然後向LKML提交一個補丁。 待辦事項： - 通過一個可以存儲 ``kernel_execve()`` 結果值的結構體數組實現各種 - ``run_init_process()`` 調用，並在失敗時通過疊代 **所有** 結果來記錄一切 + ``run_init_process()`` 調用，並在失敗時通過迭代 **所有** 結果來記錄一切 （非常重要的可用性修復）。 -- 試著使實現本身在一般情況下更有幫助，例如在受影響的地方提供額外的錯誤消息。 +- 試着使實現本身在一般情況下更有幫助，例如在受影響的地方提供額外的錯誤消息。 diff --git a/Documentation/translations/zh_TW/admin-guide/lockup-watchdogs.rst b/Documentation/translations/zh_TW/admin-guide/lockup-watchdogs.rst new file mode 100644 index 000000000000..f65b0c96e8e3 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/lockup-watchdogs.rst @@ -0,0 +1,67 @@ +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/lockup-watchdogs.rst +:Translator: Hailong Liu <liu.hailong6@zte.com.cn> + +.. _tw_lockup-watchdogs: + + +================================================= +Softlockup與hardlockup檢測機制(又名:nmi_watchdog) +================================================= + +Linux中內核實現了一種用以檢測系統發生softlockup和hardlockup的看門狗機制。 + +Softlockup是一種會引發系統在內核態中一直循環超過20秒（詳見下面“實現”小節）導致 +其他任務沒有機會得到運行的BUG。一旦檢測到'softlockup'發生，默認情況下系統會打 +印當前堆棧跟蹤信息並進入鎖定狀態。也可配置使其在檢測到'softlockup'後進入panic +狀態；通過sysctl命令設置“kernel.softlockup_panic”、使用內核啓動參數 +“softlockup_panic”（詳見Documentation/admin-guide/kernel-parameters.rst）以及使 +能內核編譯選項“BOOTPARAM_SOFTLOCKUP_PANIC”都可實現這種配置。 + +而'hardlockup'是一種會引發系統在內核態一直循環超過10秒鐘（詳見"實現"小節）導致其 +他中斷沒有機會運行的缺陷。與'softlockup'情況類似，除了使用sysctl命令設置 +'hardlockup_panic'、使能內核選項“BOOTPARAM_HARDLOCKUP_PANIC”以及使用內核參數 +"nmi_watchdog"(詳見:”Documentation/admin-guide/kernel-parameters.rst“)外，一旦檢 +測到'hardlockup'默認情況下系統打印當前堆棧跟蹤信息，然後進入鎖定狀態。 + +這個panic選項也可以與panic_timeout結合使用（這個panic_timeout是通過稍具迷惑性的 +sysctl命令"kernel.panic"來設置），使系統在panic指定時間後自動重啓。 + +實現 +==== + +Softlockup和hardlockup分別建立在hrtimer(高精度定時器)和perf兩個子系統上而實現。 +這也就意味着理論上任何架構只要實現了這兩個子系統就支持這兩種檢測機制。 + +Hrtimer用於週期性產生中斷並喚醒watchdog線程；NMI perf事件則以”watchdog_thresh“ +(編譯時默認初始化爲10秒，也可通過”watchdog_thresh“這個sysctl接口來進行配置修改) +爲間隔週期產生以檢測 hardlockups。如果一個CPU在這個時間段內沒有檢測到hrtimer中 +斷髮生，'hardlockup 檢測器'(即NMI perf事件處理函數)將會視系統配置而選擇產生內核 +警告或者直接panic。 + +而watchdog線程本質上是一個高優先級內核線程，每調度一次就對時間戳進行一次更新。 +如果時間戳在2*watchdog_thresh(這個是softlockup的觸發門限)這段時間都未更新,那麼 +"softlocup 檢測器"(內部hrtimer定時器回調函數)會將相關的調試信息打印到系統日誌中， +然後如果系統配置了進入panic流程則進入panic，否則內核繼續執行。 + +Hrtimer定時器的週期是2*watchdog_thresh/5，也就是說在hardlockup被觸發前hrtimer有 +2~3次機會產生時鐘中斷。 + +如上所述,內核相當於爲系統管理員提供了一個可調節hrtimer定時器和perf事件週期長度 +的調節旋鈕。如何通過這個旋鈕爲特定使用場景配置一個合理的週期值要對lockups檢測的 +響應速度和lockups檢測開銷這二者之間進行權衡。 + +默認情況下所有在線cpu上都會運行一個watchdog線程。不過在內核配置了”NO_HZ_FULL“的 +情況下watchdog線程默認只會運行在管家(housekeeping)cpu上，而”nohz_full“啓動參數指 +定的cpu上則不會有watchdog線程運行。試想，如果我們允許watchdog線程在”nohz_full“指 +定的cpu上運行，這些cpu上必須得運行時鐘定時器來激發watchdog線程調度；這樣一來就會 +使”nohz_full“保護用戶程序免受內核干擾的功能失效。當然，副作用就是”nohz_full“指定 +的cpu即使在內核產生了lockup問題我們也無法檢測到。不過，至少我們可以允許watchdog +線程在管家(non-tickless)核上繼續運行以便我們能繼續正常的監測這些cpus上的lockups +事件。 + +不論哪種情況都可以通過sysctl命令kernel.watchdog_cpumask來對沒有運行watchdog線程 +的cpu集合進行調節。對於nohz_full而言,如果nohz_full cpu上有異常掛住的情況，通過 +這種方式打開這些cpu上的watchdog進行調試可能會有所作用。 + diff --git a/Documentation/translations/zh_TW/admin-guide/mm/damon/index.rst b/Documentation/translations/zh_TW/admin-guide/mm/damon/index.rst new file mode 100644 index 000000000000..a472eb3c708b --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/mm/damon/index.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/mm/damon/index.rst + +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +:校譯: + +============ +監測數據訪問 +============ + +:doc:`DAMON </mm/damon/index>` 允許輕量級的數據訪問監測。使用DAMON， +用戶可以分析他們系統的內存訪問模式，並優化它們。 + +.. toctree:: + :maxdepth: 2 + + start + usage + reclaim + lru_sort + + + + + diff --git a/Documentation/translations/zh_TW/admin-guide/mm/damon/lru_sort.rst b/Documentation/translations/zh_TW/admin-guide/mm/damon/lru_sort.rst new file mode 100644 index 000000000000..1ffc4b6b1d12 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/mm/damon/lru_sort.rst @@ -0,0 +1,264 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/mm/damon/lru_sort.rst + +:翻譯: + + 臧雷剛 Leigang Zang <zangleigang@hisilicon.com> + +:校譯: + +================== +基於DAMON的LRU排序 +================== + +基於DAMON的LRU排序是一個靜態的內核模塊，旨在用於以主動的、輕量級的數據訪問模型 +爲基礎的頁面優先級處理的LRU鏈表上，以使得LRU上的數據訪問模型更爲可信。 + +哪裏需要主動的LRU排序 +===================== + +在一個大型系統中，以頁爲粒度的訪問檢測會有比較顯著的開銷，LRU通常不會主動去排序， +而是對部分特殊事件進行部分的、響應式的排序，例如：特殊的用戶請求，系統調用或者 +內存壓力。這導致，在有些場景下，LRU不能夠完美的作爲一個可信的數據訪問模型，比如 +在內存壓力下對目標內存進行回收。 + +因爲DAMON能夠儘可能準確的識別數據訪問模型，同時只引起用戶指定範圍的開銷，主動的 +執行DAMON_LRU_SORT讓LRU變得更爲可信是有益的，而且這隻需要較少和可控的開銷。 + +這是如何工作的 +============== + +DAMON_LRU_SORT使用DAMON尋找熱頁（範圍內的頁面訪問頻率高於用戶指定的閾值）和冷頁 +（範圍內的頁面在超過用戶指定的時間無訪問），並提高熱頁和降低冷頁在LRU中的優先級。 +爲了避免在排序過程佔用更多的CPU計算資源，可以設置一個CPU佔用時間的約束值。在約 +束下，分別提升或者降低更多的熱頁和冷頁。系統管理員也可以配置三個內存水位以控制 +在何種條件下自動激活或者停止這種機制。 + +冷熱閾值和CPU約束的默認值是比較保守的。這意味着，在默認參數下，模塊可以廣泛且無 +負作用的使用在常見環境中，同時在只消耗一小部分CPU時間的情況下，給有內存壓力的系 +統提供一定水平的冷熱識別。 + +接口：模塊參數 +============== + +使用此特性，你首先需要確認你的系統中運行的內核在編譯時啓用了 +``CONFIG_DAMON_LRU_SORT=y``. + +爲了讓系統管理員打開或者關閉並且調節指定的系統，DAMON_LRU_SORT設計了模塊參數。 +這意味着，你可以添加 ``damon_lru_sort.<parameter>=<value>`` 到內核的啓動命令行 +參數，或者在 ``/sys/modules/damon_lru_sort/parameters/<parameter>`` 寫入正確的 +值。 + +下邊是每個參數的描述 + +enabled +------- + +打開或者關閉DAMON_LRU_SORT. + +你可以通過設置這個參數爲 ``Y`` 來打開DAMON_LRU_SORT。設置爲 ``N`` 關閉 +DAMON_LRU_SORT。注意，在基於水位的激活的情況下，DAMON_LRU_SORT有可能不會真正去 +監測或者做LRU排序。對這種情況，參考下方關於水位的描述。 + +commit_inputs +------------- + +讓DAMON_LRU_SORT再次讀取輸入參數，除了 ``enabled`` 。 + +在DAMON_LRU_SORT運行時，新的輸入參數默認不會被應用。一旦這個參數被設置爲 ``Y`` +，DAMON_LRU_SORT會再次讀取除了 ``enabled`` 之外的參數。讀取完成後，這個參數會被 +設置爲 ``N`` 。如果在讀取時發現有無效參數，DAMON_LRU_SORT會被關閉。 + +hot_thres_access_freq +--------------------- + +熱點內存區域的訪問頻率閾值，千分比。 + +如果一個內存區域的訪問頻率大於等於這個值，DAMON_LRU_SORT把這個區域看作熱區，並 +在LRU上把這個區域標記爲已訪問，因些在內存壓力下這部分內存不會被回收。默認爲50%。 + +cold_min_age +------------ + +用於識別冷內存區域的時間閾值，單位是微秒。 + +如果一個內存區域在這個時間內未被訪問過，DAMON_LRU_SORT把這個區域看作冷區，並在 +LRU上把這個區域標記爲未訪問，因此在內存壓力下這些內存會首先被回收。默認值爲120 +秒。 + +quota_ms +-------- + +嘗試LRU鏈表排序的時間限制，單位是毫秒。 + +DAMON_LRU_SORT在一個時間窗口內（quota_reset_interval_ms）內最多嘗試這麼長時間來 +對LRU進行排序。這個可以用來作爲CPU計算資源的約束。如果值爲0，則表示無限制。 + +默認10毫秒。 + +quota_reset_interval_ms +----------------------- + +配額計時重置週期，毫秒。 + +配額計時重置週期。即，在quota_reset_interval_ms毫秒內，DAMON_LRU_SORT對LRU進行 +排序不會超過quota_ms或者quota_sz。 + +默認1秒。 + +wmarks_interval +--------------- + +水位的檢查週期，單位是微秒。 + +當DAMON_LRU_SORT使能但是由於水位而不活躍時檢查水位前最小的等待時間。默認值5秒。 + +wmarks_high +----------- + +空閒內存高水位，千分比。 + +如果空閒內存水位高於這個值，DAMON_LRU_SORT停止工作，不做任何事，除了週期性的檢 +查水位。默認200(20%)。 + +wmarks_mid +---------- + +空閒內存中間水位，千分比。 + +如果空閒內存水位在這個值與低水位之間，DAMON_LRU_SORT開始工作，開始檢測並對LRU鏈 +表進行排序。默認150(15%)。 + +wmarks_low +---------- + +空閒內存低水位，千分比。 + +如果空閒內存小於這個值，DAMON_LRU_SORT不再工作，不做任何事，除了週期性的檢查水 +線。默認50(5%)。 + +sample_interval +--------------- + +監測的採樣週期，微秒。 + +DAMON對冷內存監測的採樣週期。更多細節請參考DAMON文檔 (:doc:`usage`) 。默認5 +毫秒。 + +aggr_interval +------------- + +監測的收集週期，微秒。 + +DAMON對冷內存進行收集的時間週期。更多細節請參考DAMON文檔 (:doc:`usage`) 。默認 +100毫秒。 + +min_nr_regions +-------------- + +最小監測區域數量。 + +對冷內存區域監測的最小數量。這個值可以作爲監測質量的下限。不過，這個值設置的過 +大會增加開銷。更多細節請參考DAMON文檔 (:doc:`usage`) 。默認值爲10。 + +max_nr_regions +-------------- + +最大監測區域數量。 + +對冷內存區域監測的最大數量。這個值可以作爲監測質量的上限。然而，這個值設置的過 +低會導致監測結果變差。更多細節請參考DAMON文檔 (:doc:`usage`) 。默認值爲1000。 + +monitor_region_start +-------------------- + +目標內存區域的起始物理地址。 + +DAMON_LRU_SORT要處理的目標內存區域的起始物理地址。默認，使用系統最大內存。 + +monitor_region_end +------------------ + +目標內存區域的結束物理地址。 + +DAMON_LRU_SORT要處理的目標內存區域的結束物理地址。默認，使用系統最大內存。 + +kdamond_pid +----------- + +DAMON線程的PID。 + +如果DAMON_LRU_SORT是使能的，這個表示任務線程的PID。其它情況爲-1。 + +nr_lru_sort_tried_hot_regions +----------------------------- + +被嘗試進行LRU排序的熱內存區域的數量。 + +bytes_lru_sort_tried_hot_regions +-------------------------------- + +被嘗試進行LRU排序的熱內存區域的大小（字節）。 + +nr_lru_sorted_hot_regions +------------------------- + +成功進行LRU排序的熱內存區域的數量。 + +bytes_lru_sorted_hot_regions +---------------------------- + +成功進行LRU排序的熱內存區域的大小（字節）。 + +nr_hot_quota_exceeds +-------------------- + +熱區域時間約束超過限制的次數。 + +nr_lru_sort_tried_cold_regions +------------------------------ + +被嘗試進行LRU排序的冷內存區域的數量。 + +bytes_lru_sort_tried_cold_regions +--------------------------------- + +被嘗試進行LRU排序的冷內存區域的大小（字節）。 + +nr_lru_sorted_cold_regions +-------------------------- + +成功進行LRU排序的冷內存區域的數量。 + +bytes_lru_sorted_cold_regions +----------------------------- + +成功進行LRU排序的冷內存區域的大小（字節）。 + +nr_cold_quota_exceeds +--------------------- + +冷區域時間約束超過限制的次數。 + +Example +======= + +如下是一個運行時的命令示例，使DAMON_LRU_SORT查找訪問頻率超過50%的區域並對其進行 +LRU的優先級的提升，同時降低那些超過120秒無人訪問的內存區域的優先級。優先級的處 +理被限制在最多1%的CPU以避免DAMON_LRU_SORT消費過多CPU時間。在系統空閒內存超過50% +時DAMON_LRU_SORT停止工作，並在低於40%時重新開始工作。如果DAMON_RECLAIM沒有取得 +進展且空閒內存低於20%，再次讓DAMON_LRU_SORT停止工作，以此回退到以LRU鏈表爲基礎 +以頁面爲單位的內存回收上。 :: + + # cd /sys/modules/damon_lru_sort/parameters + # echo 500 > hot_thres_access_freq + # echo 120000000 > cold_min_age + # echo 10 > quota_ms + # echo 1000 > quota_reset_interval_ms + # echo 500 > wmarks_high + # echo 400 > wmarks_mid + # echo 200 > wmarks_low + # echo Y > enabled + diff --git a/Documentation/translations/zh_TW/admin-guide/mm/damon/reclaim.rst b/Documentation/translations/zh_TW/admin-guide/mm/damon/reclaim.rst new file mode 100644 index 000000000000..efed29c40e44 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/mm/damon/reclaim.rst @@ -0,0 +1,229 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/mm/damon/reclaim.rst + +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +:校譯: + +=============== +基於DAMON的回收 +=============== + +基於DAMON的回收（DAMON_RECLAIM）是一個靜態的內核模塊，旨在用於輕度內存壓力下的主動和輕 +量級的回收。它的目的不是取代基於LRU列表的頁面回收，而是有選擇地用於不同程度的內存壓力和要 +求。 + +哪些地方需要主動回收？ +====================== + +在一般的內存超量使用（over-committed systems，虛擬化相關術語）的系統上，主動回收冷頁 +有助於節省內存和減少延遲高峯，這些延遲是由直接回收進程或kswapd的CPU消耗引起的，同時只產 +生最小的性能下降 [1]_ [2]_ 。 + +基於空閒頁報告 [3]_ 的內存過度承諾的虛擬化系統就是很好的例子。在這樣的系統中，客戶機 +向主機報告他們的空閒內存，而主機則將報告的內存重新分配給其他客戶。因此，系統的內存得到了充 +分的利用。然而，客戶可能不那麼節省內存，主要是因爲一些內核子系統和用戶空間應用程序被設計爲 +使用盡可能多的內存。然後，客戶機可能只向主機報告少量的內存是空閒的，導致系統的內存利用率下降。 +在客戶中運行主動回收可以緩解這個問題。 + +它是如何工作的？ +================ + +DAMON_RECLAIM找到在特定時間內沒有被訪問的內存區域並分頁。爲了避免它在分頁操作中消耗過多 +的CPU，可以配置一個速度限制。在這個速度限制下，它首先分頁出那些沒有被訪問過的內存區域。系 +統管理員還可以配置在什麼情況下這個方案應該自動激活和停用三個內存壓力水位。 + +接口: 模塊參數 +============== + +要使用這個功能，你首先要確保你的系統運行在一個以 ``CONFIG_DAMON_RECLAIM=y`` 構建的內 +核上。 + +爲了讓系統管理員啓用或禁用它，併爲給定的系統進行調整，DAMON_RECLAIM利用了模塊參數。也就 +是說，你可以把 ``damon_reclaim.<parameter>=<value>`` 放在內核啓動命令行上，或者把 +適當的值寫入 ``/sys/module/damon_reclaim/parameters/<parameter>`` 文件。 + +下面是每個參數的描述。 + +enabled +------- + +啓用或禁用DAMON_RECLAIM。 + +你可以通過把這個參數的值設置爲 ``Y`` 來啓用DAMON_RCLAIM，把它設置爲 ``N`` 可以禁用 +DAMON_RECLAIM。注意，由於基於水位的激活條件，DAMON_RECLAIM不能進行真正的監測和回收。 +這一點請參考下面關於水位參數的描述。 + +min_age +------- + +識別冷內存區域的時間閾值，單位是微秒。 + +如果一個內存區域在這個時間或更長的時間內沒有被訪問，DAMON_RECLAIM會將該區域識別爲冷的， +並回收它。 + +默認爲120秒。 + +quota_ms +-------- + +回收的時間限制，以毫秒爲單位。 + +DAMON_RECLAIM 試圖在一個時間窗口（quota_reset_interval_ms）內只使用到這個時間，以 +嘗試回收冷頁。這可以用來限制DAMON_RECLAIM的CPU消耗。如果該值爲零，則該限制被禁用。 + +默認爲10ms。 + +quota_sz +-------- + +回收的內存大小限制，單位爲字節。 + +DAMON_RECLAIM 收取在一個時間窗口（quota_reset_interval_ms）內試圖回收的內存量，並 +使其不超過這個限制。這可以用來限制CPU和IO的消耗。如果該值爲零，則限制被禁用。 + +默認情況下是128 MiB。 + +quota_reset_interval_ms +----------------------- + +時間/大小配額收取重置間隔，單位爲毫秒。 + +時間（quota_ms）和大小（quota_sz）的配額的目標重置間隔。也就是說，DAMON_RECLAIM在 +嘗試回收‘不’超過quota_ms毫秒或quota_sz字節的內存。 + +默認爲1秒。 + +wmarks_interval +--------------- + +當DAMON_RECLAIM被啓用但由於其水位規則而不活躍時，在檢查水位之前的最小等待時間。 + +wmarks_high +----------- + +高水位的可用內存率（每千字節）。 + +如果系統的可用內存（以每千字節爲單位）高於這個數值，DAMON_RECLAIM就會變得不活躍，所以 +它什麼也不做，只是定期檢查水位。 + +wmarks_mid +---------- + +中間水位的可用內存率（每千字節）。 + +如果系統的空閒內存（以每千字節爲單位）在這個和低水位線之間，DAMON_RECLAIM就會被激活， +因此開始監測和回收。 + +wmarks_low +---------- + +低水位的可用內存率（每千字節）。 + +如果系統的空閒內存（以每千字節爲單位）低於這個數值，DAMON_RECLAIM就會變得不活躍，所以 +它除了定期檢查水位外什麼都不做。在這種情況下，系統會退回到基於LRU列表的頁面粒度回收邏輯。 + +sample_interval +--------------- + +監測的採樣間隔，單位是微秒。 + +DAMON用於監測冷內存的採樣間隔。更多細節請參考DAMON文檔 (:doc:`usage`) 。 + +aggr_interval +------------- + +監測的聚集間隔，單位是微秒。 + +DAMON對冷內存監測的聚集間隔。更多細節請參考DAMON文檔 (:doc:`usage`)。 + +min_nr_regions +-------------- + +監測區域的最小數量。 + +DAMON用於冷內存監測的最小監測區域數。這可以用來設置監測質量的下限。但是，設 +置的太高可能會導致監測開銷的增加。更多細節請參考DAMON文檔 (:doc:`usage`) 。 + +max_nr_regions +-------------- + +監測區域的最大數量。 + +DAMON用於冷內存監測的最大監測區域數。這可以用來設置監測開銷的上限值。但是， +設置得太低可能會導致監測質量不好。更多細節請參考DAMON文檔 (:doc:`usage`) 。 + +monitor_region_start +-------------------- + +目標內存區域的物理地址起點。 + +DAMON_RECLAIM將對其進行工作的內存區域的起始物理地址。也就是說，DAMON_RECLAIM +將在這個區域中找到冷的內存區域並進行回收。默認情況下，該區域使用最大系統內存區。 + +monitor_region_end +------------------ + +目標內存區域的結束物理地址。 + +DAMON_RECLAIM將對其進行工作的內存區域的末端物理地址。也就是說，DAMON_RECLAIM將 +在這個區域內找到冷的內存區域並進行回收。默認情況下，該區域使用最大系統內存區。 + +kdamond_pid +----------- + +DAMON線程的PID。 + +如果DAMON_RECLAIM被啓用，這將成爲工作線程的PID。否則，爲-1。 + +nr_reclaim_tried_regions +------------------------ + +試圖通過DAMON_RECLAIM回收的內存區域的數量。 + +bytes_reclaim_tried_regions +--------------------------- + +試圖通過DAMON_RECLAIM回收的內存區域的總字節數。 + +nr_reclaimed_regions +-------------------- + +通過DAMON_RECLAIM成功回收的內存區域的數量。 + +bytes_reclaimed_regions +----------------------- + +通過DAMON_RECLAIM成功回收的內存區域的總字節數。 + +nr_quota_exceeds +---------------- + +超過時間/空間配額限制的次數。 + +例子 +==== + +下面的運行示例命令使DAMON_RECLAIM找到30秒或更長時間沒有訪問的內存區域並“回收”？ +爲了避免DAMON_RECLAIM在分頁操作中消耗過多的CPU時間，回收被限制在每秒1GiB以內。 +它還要求DAMON_RECLAIM在系統的可用內存率超過50%時不做任何事情，但如果它低於40%時 +就開始真正的工作。如果DAMON_RECLAIM沒有取得進展，因此空閒內存率低於20%，它會要求 +DAMON_RECLAIM再次什麼都不做，這樣我們就可以退回到基於LRU列表的頁面粒度回收了:: + + # cd /sys/module/damon_reclaim/parameters + # echo 30000000 > min_age + # echo $((1 * 1024 * 1024 * 1024)) > quota_sz + # echo 1000 > quota_reset_interval_ms + # echo 500 > wmarks_high + # echo 400 > wmarks_mid + # echo 200 > wmarks_low + # echo Y > enabled + +.. [1] https://research.google/pubs/pub48551/ +.. [2] https://lwn.net/Articles/787611/ +.. [3] https://www.kernel.org/doc/html/latest/mm/free_page_reporting.html + diff --git a/Documentation/translations/zh_TW/admin-guide/mm/damon/start.rst b/Documentation/translations/zh_TW/admin-guide/mm/damon/start.rst new file mode 100644 index 000000000000..1822956be0e0 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/mm/damon/start.rst @@ -0,0 +1,125 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/mm/damon/start.rst + +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +:校譯: + +======== +入門指南 +======== + +本文通過演示DAMON的默認用戶空間工具，簡要地介紹瞭如何使用DAMON。請注意，爲了簡潔 +起見，本文檔只描述了它的部分功能。更多細節請參考該工具的使用文檔。 +`doc <https://github.com/awslabs/damo/blob/next/USAGE.md>`_ . + + +前提條件 +======== + +內核 +---- + +首先，你要確保你當前系統中跑的內核構建時選定了這個功能選項 ``CONFIG_DAMON_*=y``. + + +用戶空間工具 +------------ + +在演示中，我們將使用DAMON的默認用戶空間工具，稱爲DAMON Operator（DAMO）。它可以在 +https://github.com/awslabs/damo找到。下面的例子假設DAMO在你的$PATH上。當然，但 +這並不是強制性的。 + +因爲DAMO使用了DAMON的sysfs接口（詳情請參考:doc:`usage`），你應該確保 +:doc:`sysfs </filesystems/sysfs>` 被掛載。 + +記錄數據訪問模式 +================ + +下面的命令記錄了一個程序的內存訪問模式，並將監測結果保存到文件中。 :: + + $ git clone https://github.com/sjp38/masim + $ cd masim; make; ./masim ./configs/zigzag.cfg & + $ sudo damo record -o damon.data $(pidof masim) + +命令的前兩行下載了一個人工內存訪問生成器程序並在後臺運行。生成器將重複地逐一訪問兩個 +100 MiB大小的內存區域。你可以用你的真實工作負載來代替它。最後一行要求 ``damo`` 將 +訪問模式記錄在 ``damon.data`` 文件中。 + + +將記錄的模式可視化 +================== + +你可以在heatmap中直觀地看到這種模式，顯示哪個內存區域（X軸）何時被訪問（Y軸）以及訪 +問的頻率（數字）。:: + + $ sudo damo report heats --heatmap stdout + 22222222222222222222222222222222222222211111111111111111111111111111111111111100 + 44444444444444444444444444444444444444434444444444444444444444444444444444443200 + 44444444444444444444444444444444444444433444444444444444444444444444444444444200 + 33333333333333333333333333333333333333344555555555555555555555555555555555555200 + 33333333333333333333333333333333333344444444444444444444444444444444444444444200 + 22222222222222222222222222222222222223355555555555555555555555555555555555555200 + 00000000000000000000000000000000000000288888888888888888888888888888888888888400 + 00000000000000000000000000000000000000288888888888888888888888888888888888888400 + 33333333333333333333333333333333333333355555555555555555555555555555555555555200 + 88888888888888888888888888888888888888600000000000000000000000000000000000000000 + 88888888888888888888888888888888888888600000000000000000000000000000000000000000 + 33333333333333333333333333333333333333444444444444444444444444444444444444443200 + 00000000000000000000000000000000000000288888888888888888888888888888888888888400 + [...] + # access_frequency: 0 1 2 3 4 5 6 7 8 9 + # x-axis: space (139728247021568-139728453431248: 196.848 MiB) + # y-axis: time (15256597248362-15326899978162: 1 m 10.303 s) + # resolution: 80x40 (2.461 MiB and 1.758 s for each character) + +你也可以直觀地看到工作集的大小分佈，按大小排序。:: + + $ sudo damo report wss --range 0 101 10 + # <percentile> <wss> + # target_id 18446632103789443072 + # avr: 107.708 MiB + 0 0 B | | + 10 95.328 MiB |**************************** | + 20 95.332 MiB |**************************** | + 30 95.340 MiB |**************************** | + 40 95.387 MiB |**************************** | + 50 95.387 MiB |**************************** | + 60 95.398 MiB |**************************** | + 70 95.398 MiB |**************************** | + 80 95.504 MiB |**************************** | + 90 190.703 MiB |********************************************************* | + 100 196.875 MiB |***********************************************************| + +在上述命令中使用 ``--sortby`` 選項，可以顯示工作集的大小是如何按時間順序變化的。:: + + $ sudo damo report wss --range 0 101 10 --sortby time + # <percentile> <wss> + # target_id 18446632103789443072 + # avr: 107.708 MiB + 0 3.051 MiB | | + 10 190.703 MiB |***********************************************************| + 20 95.336 MiB |***************************** | + 30 95.328 MiB |***************************** | + 40 95.387 MiB |***************************** | + 50 95.332 MiB |***************************** | + 60 95.320 MiB |***************************** | + 70 95.398 MiB |***************************** | + 80 95.398 MiB |***************************** | + 90 95.340 MiB |***************************** | + 100 95.398 MiB |***************************** | + + +數據訪問模式感知的內存管理 +========================== + +以下三個命令使每一個大小>=4K的內存區域在你的工作負載中沒有被訪問>=60秒，就會被換掉。 :: + + $ echo "#min-size max-size min-acc max-acc min-age max-age action" > test_scheme + $ echo "4K max 0 0 60s max pageout" >> test_scheme + $ damo schemes -c test_scheme <pid of your workload> + diff --git a/Documentation/translations/zh_TW/admin-guide/mm/damon/usage.rst b/Documentation/translations/zh_TW/admin-guide/mm/damon/usage.rst new file mode 100644 index 000000000000..6dee719a32ea --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/mm/damon/usage.rst @@ -0,0 +1,592 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/mm/damon/usage.rst + +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +:校譯: + +======== +詳細用法 +======== + +DAMON 爲不同的用戶提供了下面這些接口。 + +- *DAMON用戶空間工具。* + `這 <https://github.com/awslabs/damo>`_ 爲有這特權的人， 如系統管理員，希望有一個剛好 + 可以工作的人性化界面。 + 使用它，用戶可以以人性化的方式使用DAMON的主要功能。不過，它可能不會爲特殊情況進行高度調整。 + 它同時支持虛擬和物理地址空間的監測。更多細節，請參考它的 `使用文檔 + <https://github.com/awslabs/damo/blob/next/USAGE.md>`_。 +- *sysfs接口。* + :ref:`這 <sysfs_interface>` 是爲那些希望更高級的使用DAMON的特權用戶空間程序員準備的。 + 使用它，用戶可以通過讀取和寫入特殊的sysfs文件來使用DAMON的主要功能。因此，你可以編寫和使 + 用你個性化的DAMON sysfs包裝程序，代替你讀/寫sysfs文件。 `DAMON用戶空間工具 + <https://github.com/awslabs/damo>`_ 就是這種程序的一個例子 它同時支持虛擬和物理地址 + 空間的監測。注意，這個界面只提供簡單的監測結果 :ref:`統計 <damos_stats>`。對於詳細的監測 + 結果，DAMON提供了一個:ref:`跟蹤點 <tracepoint>`。 +- *debugfs interface.* + :ref:`這 <debugfs_interface>` 幾乎與:ref:`sysfs interface <sysfs_interface>` 接 + 口相同。這將在下一個LTS內核發佈後被移除，所以用戶應該轉移到 + :ref:`sysfs interface <sysfs_interface>`。 +- *內核空間編程接口。* + :doc:`這 </mm/damon/api>` 這是爲內核空間程序員準備的。使用它，用戶可以通過爲你編寫內 + 核空間的DAMON應用程序，最靈活有效地利用DAMON的每一個功能。你甚至可以爲各種地址空間擴展DAMON。 + 詳細情況請參考接口 :doc:`文件 </mm/damon/api>`。 + +sysfs接口 +========= +DAMON的sysfs接口是在定義 ``CONFIG_DAMON_SYSFS`` 時建立的。它在其sysfs目錄下創建多 +個目錄和文件， ``<sysfs>/kernel/mm/damon/`` 。你可以通過對該目錄下的文件進行寫入和 +讀取來控制DAMON。 + +對於一個簡短的例子，用戶可以監測一個給定工作負載的虛擬地址空間，如下所示:: + + # cd /sys/kernel/mm/damon/admin/ + # echo 1 > kdamonds/nr_kdamonds && echo 1 > kdamonds/0/contexts/nr_contexts + # echo vaddr > kdamonds/0/contexts/0/operations + # echo 1 > kdamonds/0/contexts/0/targets/nr_targets + # echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid_target + # echo on > kdamonds/0/state + +文件層次結構 +------------ + +DAMON sysfs接口的文件層次結構如下圖所示。在下圖中，父子關係用縮進表示，每個目錄有 +``/`` 後綴，每個目錄中的文件用逗號（","）分開。 :: + + /sys/kernel/mm/damon/admin + │ kdamonds/nr_kdamonds + │ │ 0/state,pid + │ │ │ contexts/nr_contexts + │ │ │ │ 0/operations + │ │ │ │ │ monitoring_attrs/ + │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us + │ │ │ │ │ │ nr_regions/min,max + │ │ │ │ │ targets/nr_targets + │ │ │ │ │ │ 0/pid_target + │ │ │ │ │ │ │ regions/nr_regions + │ │ │ │ │ │ │ │ 0/start,end + │ │ │ │ │ │ │ │ ... + │ │ │ │ │ │ ... + │ │ │ │ │ schemes/nr_schemes + │ │ │ │ │ │ 0/action + │ │ │ │ │ │ │ access_pattern/ + │ │ │ │ │ │ │ │ sz/min,max + │ │ │ │ │ │ │ │ nr_accesses/min,max + │ │ │ │ │ │ │ │ age/min,max + │ │ │ │ │ │ │ quotas/ms,bytes,reset_interval_ms + │ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil + │ │ │ │ │ │ │ watermarks/metric,interval_us,high,mid,low + │ │ │ │ │ │ │ stats/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds + │ │ │ │ │ │ │ tried_regions/ + │ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age + │ │ │ │ │ │ │ │ ... + │ │ │ │ │ │ ... + │ │ │ │ ... + │ │ ... + +根 +-- + +DAMON sysfs接口的根是 ``<sysfs>/kernel/mm/damon/`` ，它有一個名爲 ``admin`` 的 +目錄。該目錄包含特權用戶空間程序控制DAMON的文件。擁有根權限的用戶空間工具或deamons可以 +使用這個目錄。 + +kdamonds/ +--------- + +與監測相關的信息包括請求規格和結果被稱爲DAMON上下文。DAMON用一個叫做kdamond的內核線程 +執行每個上下文，多個kdamonds可以並行運行。 + +在 ``admin`` 目錄下，有一個目錄，即``kdamonds``，它有控制kdamonds的文件存在。在開始 +時，這個目錄只有一個文件，``nr_kdamonds``。向該文件寫入一個數字（``N``），就會創建名爲 +``0`` 到 ``N-1`` 的子目錄數量。每個目錄代表每個kdamond。 + +kdamonds/<N>/ +------------- + +在每個kdamond目錄中，存在兩個文件（``state`` 和 ``pid`` ）和一個目錄( ``contexts`` )。 + +讀取 ``state`` 時，如果kdamond當前正在運行，則返回 ``on`` ，如果沒有運行則返回 ``off`` 。 +寫入 ``on`` 或 ``off`` 使kdamond處於狀態。向 ``state`` 文件寫 ``update_schemes_stats`` ， +更新kdamond的每個基於DAMON的操作方案的統計文件的內容。關於統計信息的細節，請參考 +:ref:`stats section <sysfs_schemes_stats>`. 將 ``update_schemes_tried_regions`` 寫到 +``state`` 文件，爲kdamond的每個基於DAMON的操作方案，更新基於DAMON的操作方案動作的嘗試區域目錄。 +將`clear_schemes_tried_regions`寫入`state`文件，清除kdamond的每個基於DAMON的操作方案的動作 +嘗試區域目錄。 關於基於DAMON的操作方案動作嘗試區域目錄的細節，請參考:ref:tried_regions 部分 +<sysfs_schemes_tried_regions>`。 + +如果狀態爲 ``on``，讀取 ``pid`` 顯示kdamond線程的pid。 + +``contexts`` 目錄包含控制這個kdamond要執行的監測上下文的文件。 + +kdamonds/<N>/contexts/ +---------------------- + +在開始時，這個目錄只有一個文件，即 ``nr_contexts`` 。向該文件寫入一個數字( ``N`` )，就會創 +建名爲``0`` 到 ``N-1`` 的子目錄數量。每個目錄代表每個監測背景。目前，每個kdamond只支持 +一個上下文，所以只有 ``0`` 或 ``1`` 可以被寫入文件。 + +contexts/<N>/ +------------- + +在每個上下文目錄中，存在一個文件(``operations``)和三個目錄(``monitoring_attrs``, +``targets``, 和 ``schemes``)。 + +DAMON支持多種類型的監測操作，包括對虛擬地址空間和物理地址空間的監測。你可以通過向文件 +中寫入以下關鍵詞之一，並從文件中讀取，來設置和獲取DAMON將爲上下文使用何種類型的監測操作。 + + - vaddr: 監測特定進程的虛擬地址空間 + - paddr: 監視系統的物理地址空間 + +contexts/<N>/monitoring_attrs/ +------------------------------ + +用於指定監測屬性的文件，包括所需的監測質量和效率，都在 ``monitoring_attrs`` 目錄中。 +具體來說，這個目錄下有兩個目錄，即 ``intervals`` 和 ``nr_regions`` 。 + +在 ``intervals`` 目錄下，存在DAMON的採樣間隔(``sample_us``)、聚集間隔(``aggr_us``) +和更新間隔(``update_us``)三個文件。你可以通過寫入和讀出這些文件來設置和獲取微秒級的值。 + +在 ``nr_regions`` 目錄下，有兩個文件分別用於DAMON監測區域的下限和上限（``min`` 和 ``max`` ）， +這兩個文件控制着監測的開銷。你可以通過向這些文件的寫入和讀出來設置和獲取這些值。 + +關於間隔和監測區域範圍的更多細節，請參考設計文件 (:doc:`/mm/damon/design`)。 + +contexts/<N>/targets/ +--------------------- + +在開始時，這個目錄只有一個文件 ``nr_targets`` 。向該文件寫入一個數字(``N``)，就可以創建 +名爲 ``0`` 到 ``N-1`` 的子目錄的數量。每個目錄代表每個監測目標。 + +targets/<N>/ +------------ + +在每個目標目錄中，存在一個文件(``pid_target``)和一個目錄(``regions``)。 + +如果你把 ``vaddr`` 寫到 ``contexts/<N>/operations`` 中，每個目標應該是一個進程。你 +可以通過將進程的pid寫到 ``pid_target`` 文件中來指定DAMON的進程。 + +targets/<N>/regions +------------------- + +當使用 ``vaddr`` 監測操作集時（ ``vaddr`` 被寫入 ``contexts/<N>/operations`` 文 +件），DAMON自動設置和更新監測目標區域，這樣就可以覆蓋目標進程的整個內存映射。然而，用戶可 +能希望將初始監測區域設置爲特定的地址範圍。 + +相反，當使用 ``paddr`` 監測操作集時，DAMON不會自動設置和更新監測目標區域（ ``paddr`` +被寫入 ``contexts/<N>/operations`` 中）。因此，在這種情況下，用戶應該自己設置監測目標 +區域。 + +在這種情況下，用戶可以按照自己的意願明確設置初始監測目標區域，將適當的值寫入該目錄下的文件。 + +開始時，這個目錄只有一個文件， ``nr_regions`` 。向該文件寫入一個數字(``N``)，就可以創 +建名爲 ``0`` 到 ``N-1`` 的子目錄。每個目錄代表每個初始監測目標區域。 + +regions/<N>/ +------------ + +在每個區域目錄中，你會發現兩個文件（ ``start`` 和 ``end`` ）。你可以通過向文件寫入 +和從文件中讀出，分別設置和獲得初始監測目標區域的起始和結束地址。 + +每個區域不應該與其他區域重疊。 目錄“N”的“結束”應等於或小於目錄“N+1”的“開始”。 + +contexts/<N>/schemes/ +--------------------- + +對於一版的基於DAMON的數據訪問感知的內存管理優化，用戶通常希望系統對特定訪問模式的內存區 +域應用內存管理操作。DAMON從用戶那裏接收這種形式化的操作方案，並將這些方案應用於目標內存 +區域。用戶可以通過讀取和寫入這個目錄下的文件來獲得和設置這些方案。 + +在開始時，這個目錄只有一個文件，``nr_schemes``。向該文件寫入一個數字(``N``)，就可以 +創建名爲``0``到``N-1``的子目錄的數量。每個目錄代表每個基於DAMON的操作方案。 + +schemes/<N>/ +------------ + +在每個方案目錄中，存在五個目錄(``access_pattern``、``quotas``、``watermarks``、 +``stats`` 和 ``tried_regions``)和一個文件(``action``)。 + +``action`` 文件用於設置和獲取你想應用於具有特定訪問模式的內存區域的動作。可以寫入文件 +和從文件中讀取的關鍵詞及其含義如下。 + + - ``willneed``: 對有 ``MADV_WILLNEED`` 的區域調用 ``madvise()`` 。 + - ``cold``: 對具有 ``MADV_COLD`` 的區域調用 ``madvise()`` 。 + - ``pageout``: 爲具有 ``MADV_PAGEOUT`` 的區域調用 ``madvise()`` 。 + - ``hugepage``: 爲帶有 ``MADV_HUGEPAGE`` 的區域調用 ``madvise()`` 。 + - ``nohugepage``: 爲帶有 ``MADV_NOHUGEPAGE`` 的區域調用 ``madvise()``。 + - ``lru_prio``: 在其LRU列表上對區域進行優先排序。 + - ``lru_deprio``: 對區域的LRU列表進行降低優先處理。 + - ``stat``: 什麼都不做，只計算統計數據 + +schemes/<N>/access_pattern/ +--------------------------- + +每個基於DAMON的操作方案的目標訪問模式由三個範圍構成，包括以字節爲單位的區域大小、每個 +聚合區間的監測訪問次數和區域年齡的聚合區間數。 + +在 ``access_pattern`` 目錄下，存在三個目錄（ ``sz``, ``nr_accesses``, 和 ``age`` ）， +每個目錄有兩個文件（``min`` 和 ``max`` ）。你可以通過向 ``sz``, ``nr_accesses``, 和 +``age`` 目錄下的 ``min`` 和 ``max`` 文件分別寫入和讀取來設置和獲取給定方案的訪問模式。 + +schemes/<N>/quotas/ +------------------- + +每個 ``動作`` 的最佳 ``目標訪問模式`` 取決於工作負載，所以不容易找到。更糟糕的是，將某些動作 +的方案設置得過於激進會造成嚴重的開銷。爲了避免這種開銷，用戶可以爲每個方案限制時間和大小配額。 +具體來說，用戶可以要求DAMON儘量只使用特定的時間（``時間配額``）來應用動作，並且在給定的時間間 +隔（``重置間隔``）內，只對具有目標訪問模式的內存區域應用動作，而不使用特定數量（``大小配額``）。 + +當預計超過配額限制時，DAMON會根據 ``目標訪問模式`` 的大小、訪問頻率和年齡，對找到的內存區域 +進行優先排序。爲了進行個性化的優先排序，用戶可以爲這三個屬性設置權重。 + +在 ``quotas`` 目錄下，存在三個文件（``ms``, ``bytes``, ``reset_interval_ms``）和一個 +目錄(``weights``)，其中有三個文件(``sz_permil``, ``nr_accesses_permil``, 和 +``age_permil``)。 + +你可以設置以毫秒爲單位的 ``時間配額`` ，以字節爲單位的 ``大小配額`` ，以及以毫秒爲單位的 ``重 +置間隔`` ，分別向這三個文件寫入數值。你還可以通過向 ``weights`` 目錄下的三個文件寫入數值來設 +置大小、訪問頻率和年齡的優先權，單位爲千分之一。 + +schemes/<N>/watermarks/ +----------------------- + +爲了便於根據系統狀態激活和停用每個方案，DAMON提供了一個稱爲水位的功能。該功能接收五個值，稱爲 +``度量`` 、``間隔`` 、``高`` 、``中`` 、``低`` 。``度量值`` 是指可以測量的系統度量值，如 +自由內存比率。如果系統的度量值 ``高`` 於memoent的高值或 ``低`` 於低值，則該方案被停用。如果 +該值低於 ``中`` ，則該方案被激活。 + +在水位目錄下，存在五個文件(``metric``, ``interval_us``,``high``, ``mid``, and ``low``) +用於設置每個值。你可以通過向這些文件的寫入來分別設置和獲取這五個值。 + +可以寫入 ``metric`` 文件的關鍵詞和含義如下。 + + - none: 忽略水位 + - free_mem_rate: 系統的自由內存率（千分比）。 + +``interval`` 應以微秒爲單位寫入。 + +schemes/<N>/stats/ +------------------ + +DAMON統計每個方案被嘗試應用的區域的總數量和字節數，每個方案被成功應用的區域的兩個數字，以及 +超過配額限制的總數量。這些統計數據可用於在線分析或調整方案。 + +可以通過讀取 ``stats`` 目錄下的文件(``nr_tried``, ``sz_tried``, ``nr_applied``, +``sz_applied``, 和 ``qt_exceeds``)）分別檢索這些統計數據。這些文件不是實時更新的，所以 +你應該要求DAMON sysfs接口通過在相關的 ``kdamonds/<N>/state`` 文件中寫入一個特殊的關鍵字 +``update_schemes_stats`` 來更新統計信息的文件內容。 + +schemes/<N>/tried_regions/ +-------------------------- + +當一個特殊的關鍵字 ``update_schemes_tried_regions`` 被寫入相關的 ``kdamonds/<N>/state`` +文件時，DAMON會在這個目錄下創建從 ``0`` 開始命名的整數目錄。每個目錄包含的文件暴露了關於每個 +內存區域的詳細信息，在下一個 :ref:`聚集區間 <sysfs_monitoring_attrs>`，相應的方案的 ``動作`` +已經嘗試在這個目錄下應用。這些信息包括地址範圍、``nr_accesses`` 以及區域的 ``年齡`` 。 + +當另一個特殊的關鍵字 ``clear_schemes_tried_regions`` 被寫入相關的 ``kdamonds/<N>/state`` +文件時，這些目錄將被刪除。 + +tried_regions/<N>/ +------------------ + +在每個區域目錄中，你會發現四個文件(``start``, ``end``, ``nr_accesses``, and ``age``)。 +讀取這些文件將顯示相應的基於DAMON的操作方案 ``動作`` 試圖應用的區域的開始和結束地址、``nr_accesses`` +和 ``年齡`` 。 + +用例 +~~~~ + +下面的命令應用了一個方案：”如果一個大小爲[4KiB, 8KiB]的內存區域在[10, 20]的聚合時間間隔內 +顯示出每一個聚合時間間隔[0, 5]的訪問量，請分頁該區域。對於分頁，每秒最多隻能使用10ms，而且每 +秒分頁不能超過1GiB。在這一限制下，首先分頁出具有較長年齡的內存區域。另外，每5秒鐘檢查一次系統 +的可用內存率，當可用內存率低於50%時開始監測和分頁，但如果可用內存率大於60%，或低於30%，則停 +止監測。“ :: + + # cd <sysfs>/kernel/mm/damon/admin + # # populate directories + # echo 1 > kdamonds/nr_kdamonds; echo 1 > kdamonds/0/contexts/nr_contexts; + # echo 1 > kdamonds/0/contexts/0/schemes/nr_schemes + # cd kdamonds/0/contexts/0/schemes/0 + # # set the basic access pattern and the action + # echo 4096 > access_pattern/sz/min + # echo 8192 > access_pattern/sz/max + # echo 0 > access_pattern/nr_accesses/min + # echo 5 > access_pattern/nr_accesses/max + # echo 10 > access_pattern/age/min + # echo 20 > access_pattern/age/max + # echo pageout > action + # # set quotas + # echo 10 > quotas/ms + # echo $((1024*1024*1024)) > quotas/bytes + # echo 1000 > quotas/reset_interval_ms + # # set watermark + # echo free_mem_rate > watermarks/metric + # echo 5000000 > watermarks/interval_us + # echo 600 > watermarks/high + # echo 500 > watermarks/mid + # echo 300 > watermarks/low + +請注意，我們強烈建議使用用戶空間的工具，如 `damo <https://github.com/awslabs/damo>`_ ， +而不是像上面那樣手動讀寫文件。以上只是一個例子。 + +debugfs接口 +=========== + +.. note:: + + DAMON debugfs接口將在下一個LTS內核發佈後被移除，所以用戶應該轉移到 + :ref:`sysfs接口<sysfs_interface>`。 + +DAMON導出了八個文件, ``attrs``, ``target_ids``, ``init_regions``, +``schemes``, ``monitor_on``, ``kdamond_pid``, ``mk_contexts`` 和 +``rm_contexts`` under its debugfs directory, ``<debugfs>/damon/``. + + +屬性 +---- + +用戶可以通過讀取和寫入 ``attrs`` 文件獲得和設置 ``採樣間隔`` 、 ``聚集間隔`` 、 ``更新間隔`` +以及監測目標區域的最小/最大數量。要詳細瞭解監測屬性，請參考 `:doc:/mm/damon/design` 。例如， +下面的命令將這些值設置爲5ms、100ms、1000ms、10和1000，然後再次檢查:: + + # cd <debugfs>/damon + # echo 5000 100000 1000000 10 1000 > attrs + # cat attrs + 5000 100000 1000000 10 1000 + + +目標ID +------ + +一些類型的地址空間支持多個監測目標。例如，虛擬內存地址空間的監測可以有多個進程作爲監測目標。用戶 +可以通過寫入目標的相關id值來設置目標，並通過讀取 ``target_ids`` 文件來獲得當前目標的id。在監 +測虛擬地址空間的情況下，這些值應該是監測目標進程的pid。例如，下面的命令將pid爲42和4242的進程設 +爲監測目標，並再次檢查:: + + # cd <debugfs>/damon + # echo 42 4242 > target_ids + # cat target_ids + 42 4242 + +用戶還可以通過在文件中寫入一個特殊的關鍵字 "paddr\n" 來監測系統的物理內存地址空間。因爲物理地 +址空間監測不支持多個目標，讀取文件會顯示一個假值，即 ``42`` ，如下圖所示:: + + # cd <debugfs>/damon + # echo paddr > target_ids + # cat target_ids + 42 + +請注意，設置目標ID並不啓動監測。 + + +初始監測目標區域 +---------------- + +在虛擬地址空間監測的情況下，DAMON自動設置和更新監測的目標區域，這樣就可以覆蓋目標進程的整個 +內存映射。然而，用戶可能希望將監測區域限制在特定的地址範圍內，如堆、棧或特定的文件映射區域。 +或者，一些用戶可以知道他們工作負載的初始訪問模式，因此希望爲“自適應區域調整”設置最佳初始區域。 + +相比之下，DAMON在物理內存監測的情況下不會自動設置和更新監測目標區域。因此，用戶應該自己設置 +監測目標區域。 + +在這種情況下，用戶可以通過在 ``init_regions`` 文件中寫入適當的值，明確地設置他們想要的初 +始監測目標區域。輸入應該是一個由三個整數組成的隊列，用空格隔開，代表一個區域的形式如下:: + + <target idx> <start address> <end address> + +目標idx應該是 ``target_ids`` 文件中目標的索引，從 ``0`` 開始，區域應該按照地址順序傳遞。 +例如，下面的命令將設置幾個地址範圍， ``1-100`` 和 ``100-200`` 作爲pid 42的初始監測目標 +區域，這是 ``target_ids`` 中的第一個（索引 ``0`` ），另外幾個地址範圍， ``20-40`` 和 +``50-100`` 作爲pid 4242的地址，這是 ``target_ids`` 中的第二個（索引 ``1`` ）:: + + # cd <debugfs>/damon + # cat target_ids + 42 4242 + # echo "0 1 100 \ + 0 100 200 \ + 1 20 40 \ + 1 50 100" > init_regions + +請注意，這只是設置了初始的監測目標區域。在虛擬內存監測的情況下，DAMON會在一個 ``更新間隔`` +後自動更新區域的邊界。因此，在這種情況下，如果用戶不希望更新的話，應該把 ``更新間隔`` 設 +置得足夠大。 + + +方案 +---- + +對於通常的基於DAMON的數據訪問感知的內存管理優化，用戶只是希望系統對特定訪問模式的內存區域應用內 +存管理操作。DAMON從用戶那裏接收這種形式化的操作方案，並將這些方案應用到目標進程中。 + +用戶可以通過讀取和寫入 ``scheme`` debugfs文件來獲得和設置這些方案。讀取該文件還可以顯示每個 +方案的統計數據。在文件中，每一個方案都應該在每一行中以下列形式表示出來:: + + <target access pattern> <action> <quota> <watermarks> + +你可以通過簡單地在文件中寫入一個空字符串來禁用方案。 + +目標訪問模式 +~~~~~~~~~~~~ + +``<目標訪問模式>`` 是由三個範圍構成的，形式如下:: + + min-size max-size min-acc max-acc min-age max-age + +具體來說，區域大小的字節數（ `min-size` 和 `max-size` ），訪問頻率的每聚合區間的監測訪問次 +數（ `min-acc` 和 `max-acc` ），區域年齡的聚合區間數（ `min-age` 和 `max-age` ）都被指定。 +請注意，這些範圍是封閉區間。 + +動作 +~~~~ + +``<action>`` 是一個預定義的內存管理動作的整數，DAMON將應用於具有目標訪問模式的區域。支持 +的數字和它們的含義如下:: + + - 0: Call ``madvise()`` for the region with ``MADV_WILLNEED`` + - 1: Call ``madvise()`` for the region with ``MADV_COLD`` + - 2: Call ``madvise()`` for the region with ``MADV_PAGEOUT`` + - 3: Call ``madvise()`` for the region with ``MADV_HUGEPAGE`` + - 4: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE`` + - 5: Do nothing but count the statistics + +配額 +~~~~ + +每個 ``動作`` 的最佳 ``目標訪問模式`` 取決於工作負載，所以不容易找到。更糟糕的是，將某個 +動作的方案設置得過於激進會導致嚴重的開銷。爲了避免這種開銷，用戶可以通過下面表格中的 ``<quota>`` +來限制方案的時間和大小配額:: + + <ms> <sz> <reset interval> <priority weights> + +這使得DAMON在 ``<reset interval>`` 毫秒內，儘量只用 ``<ms>`` 毫秒的時間對 ``目標訪 +問模式`` 的內存區域應用動作，並在 ``<reset interval>`` 內只對最多<sz>字節的內存區域應 +用動作。將 ``<ms>`` 和 ``<sz>`` 都設置爲零，可以禁用配額限制。 + +當預計超過配額限制時，DAMON會根據 ``目標訪問模式`` 的大小、訪問頻率和年齡，對發現的內存 +區域進行優先排序。爲了實現個性化的優先級，用戶可以在 ``<優先級權重>`` 中設置這三個屬性的 +權重，具體形式如下:: + + <size weight> <access frequency weight> <age weight> + +水位 +~~~~ + +有些方案需要根據系統特定指標的當前值來運行，如自由內存比率。對於這種情況，用戶可以爲該條 +件指定水位。:: + + <metric> <check interval> <high mark> <middle mark> <low mark> + +``<metric>`` 是一個預定義的整數，用於要檢查的度量。支持的數字和它們的含義如下。 + + - 0: 忽視水位 + - 1: 系統空閒內存率 (千分比) + +每隔 ``<檢查間隔>`` 微秒檢查一次公制的值。 + +如果該值高於 ``<高標>`` 或低於 ``<低標>`` ，該方案被停用。如果該值低於 ``<中標>`` ， +該方案將被激活。 + +統計數據 +~~~~~~~~ + +它還統計每個方案被嘗試應用的區域的總數量和字節數，每個方案被成功應用的區域的兩個數量，以 +及超過配額限制的總數量。這些統計數據可用於在線分析或調整方案。 + +統計數據可以通過讀取方案文件來顯示。讀取該文件將顯示你在每一行中輸入的每個 ``方案`` ， +統計的五個數字將被加在每一行的末尾。 + +例子 +~~~~ + +下面的命令應用了一個方案：”如果一個大小爲[4KiB, 8KiB]的內存區域在[10, 20]的聚合時間 +間隔內顯示出每一個聚合時間間隔[0, 5]的訪問量，請分頁出該區域。對於分頁，每秒最多隻能使 +用10ms，而且每秒分頁不能超過1GiB。在這一限制下，首先分頁出具有較長年齡的內存區域。另外， +每5秒鐘檢查一次系統的可用內存率，當可用內存率低於50%時開始監測和分頁，但如果可用內存率 +大於60%，或低於30%，則停止監測“:: + + # cd <debugfs>/damon + # scheme="4096 8192 0 5 10 20 2" # target access pattern and action + # scheme+=" 10 $((1024*1024*1024)) 1000" # quotas + # scheme+=" 0 0 100" # prioritization weights + # scheme+=" 1 5000000 600 500 300" # watermarks + # echo "$scheme" > schemes + + +開關 +---- + +除非你明確地啓動監測，否則如上所述的文件設置不會產生效果。你可以通過寫入和讀取 ``monitor_on`` +文件來啓動、停止和檢查監測的當前狀態。寫入 ``on`` 該文件可以啓動對有屬性的目標的監測。寫入 +``off`` 該文件則停止這些目標。如果每個目標進程被終止，DAMON也會停止。下面的示例命令開啓、關 +閉和檢查DAMON的狀態:: + + # cd <debugfs>/damon + # echo on > monitor_on + # echo off > monitor_on + # cat monitor_on + off + +請注意，當監測開啓時，你不能寫到上述的debugfs文件。如果你在DAMON運行時寫到這些文件，將會返 +回一個錯誤代碼，如 ``-EBUSY`` 。 + + +監測線程PID +----------- + +DAMON通過一個叫做kdamond的內核線程來進行請求監測。你可以通過讀取 ``kdamond_pid`` 文件獲 +得該線程的 ``pid`` 。當監測被 ``關閉`` 時，讀取該文件不會返回任何信息:: + + # cd <debugfs>/damon + # cat monitor_on + off + # cat kdamond_pid + none + # echo on > monitor_on + # cat kdamond_pid + 18594 + + +使用多個監測線程 +---------------- + +每個監測上下文都會創建一個 ``kdamond`` 線程。你可以使用 ``mk_contexts`` 和 ``rm_contexts`` +文件爲多個 ``kdamond`` 需要的用例創建和刪除監測上下文。 + +將新上下文的名稱寫入 ``mk_contexts`` 文件，在 ``DAMON debugfs`` 目錄上創建一個該名稱的目錄。 +該目錄將有該上下文的 ``DAMON debugfs`` 文件:: + + # cd <debugfs>/damon + # ls foo + # ls: cannot access 'foo': No such file or directory + # echo foo > mk_contexts + # ls foo + # attrs init_regions kdamond_pid schemes target_ids + +如果不再需要上下文，你可以通過把上下文的名字放到 ``rm_contexts`` 文件中來刪除它和相應的目錄:: + + # echo foo > rm_contexts + # ls foo + # ls: cannot access 'foo': No such file or directory + +注意， ``mk_contexts`` 、 ``rm_contexts`` 和 ``monitor_on`` 文件只在根目錄下。 + + +監測結果的監測點 +================ + +DAMON通過一個tracepoint ``damon:damon_aggregated`` 提供監測結果. 當監測開啓時，你可 +以記錄追蹤點事件，並使用追蹤點支持工具如perf顯示結果。比如說:: + + # echo on > monitor_on + # perf record -e damon:damon_aggregated & + # sleep 5 + # kill 9 $(pidof perf) + # echo off > monitor_on + # perf script + diff --git a/Documentation/translations/zh_TW/admin-guide/mm/index.rst b/Documentation/translations/zh_TW/admin-guide/mm/index.rst new file mode 100644 index 000000000000..0b04d925b68c --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/mm/index.rst @@ -0,0 +1,50 @@ +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/mm/index.rst + +:翻譯: + + 徐鑫 xu xin <xu.xin16@zte.com.cn> + + +======== +內存管理 +======== + +Linux內存管理子系統，顧名思義，是負責系統中的內存管理。它包括了虛擬內存與請求 +分頁的實現，內核內部結構和用戶空間程序的內存分配、將文件映射到進程地址空間以 +及許多其他很酷的事情。 + +Linux內存管理是一個具有許多可配置設置的複雜系統, 且這些設置中的大多數都可以通 +過 ``/proc`` 文件系統獲得，並且可以使用 ``sysctl`` 進行查詢和調整。這些API接 +口被描述在Documentation/admin-guide/sysctl/vm.rst文件和 `man 5 proc`_ 中。 + +.. _man 5 proc: http://man7.org/linux/man-pages/man5/proc.5.html + +Linux內存管理有它自己的術語，如果你還不熟悉它，請考慮閱讀下面參考： +Documentation/admin-guide/mm/concepts.rst. + +在此目錄下，我們詳細描述瞭如何與Linux內存管理中的各種機制交互。 + +.. toctree:: + :maxdepth: 1 + + damon/index + ksm + +Todolist: +* concepts +* cma_debugfs +* hugetlbpage +* idle_page_tracking +* memory-hotplug +* nommu-mmap +* numa_memory_policy +* numaperf +* pagemap +* soft-dirty +* swap_numa +* transhuge +* userfaultfd +* zswap + diff --git a/Documentation/translations/zh_TW/admin-guide/mm/ksm.rst b/Documentation/translations/zh_TW/admin-guide/mm/ksm.rst new file mode 100644 index 000000000000..1b4944b3cf61 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/mm/ksm.rst @@ -0,0 +1,199 @@ +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/mm/ksm.rst + +:翻譯: + + 徐鑫 xu xin <xu.xin16@zte.com.cn> + + +============ +內核同頁合併 +============ + + +概述 +==== + +KSM是一種能節省內存的數據去重功能，由CONFIG_KSM=y啓用，並在2.6.32版本時被添 +加到Linux內核。詳見 ``mm/ksm.c`` 的實現，以及http://lwn.net/Articles/306704 +和https://lwn.net/Articles/330589 + +KSM最初目的是爲了與KVM（即著名的內核共享內存）一起使用而開發的，通過共享虛擬機 +之間的公共數據，將更多虛擬機放入物理內存。但它對於任何會生成多個相同數據實例的 +應用程序都是很有用的。 + +KSM的守護進程ksmd會定期掃描那些已註冊的用戶內存區域，查找內容相同的頁面，這些 +頁面可以被單個寫保護頁面替換（如果進程以後想要更新其內容，將自動複製）。使用： +引用:`sysfs intraface <ksm_sysfs>` 接口來配置KSM守護程序在單個過程中所掃描的頁 +數以及兩個過程之間的間隔時間。 + +KSM只合並匿名（私有）頁面，從不合並頁緩存（文件）頁面。KSM的合併頁面最初只能被 +鎖定在內核內存中，但現在可以就像其他用戶頁面一樣被換出（但當它們被交換回來時共 +享會被破壞: ksmd必須重新發現它們的身份並再次合併）。 + +以madvise控制KSM +================ + +KSM僅在特定的地址空間區域時運行，即應用程序通過使用如下所示的madvise(2)系統調 +用來請求某塊地址成爲可能的合併候選者的地址空間:: + + int madvise(addr, length, MADV_MERGEABLE) + +應用程序當然也可以通過調用:: + + int madvise(addr, length, MADV_UNMERGEABLE) + +來取消該請求，並恢復爲非共享頁面：此時KSM將去除合併在該範圍內的任何合併頁。注意： +這個去除合併的調用可能突然需要的內存量超過實際可用的內存量-那麼可能會出現EAGAIN +失敗，但更可能會喚醒OOM killer。 + +如果KSM未被配置到正在運行的內核中，則madvise MADV_MERGEABLE 和 MADV_UNMERGEABLE +的調用只會以EINVAL 失敗。如果正在運行的內核是用CONFIG_KSM=y方式構建的，那麼這些 +調用通常會成功：即使KSM守護程序當前沒有運行，MADV_MERGEABLE 仍然會在KSM守護程序 +啓動時註冊範圍，即使該範圍不能包含KSM實際可以合併的任何頁面，即使MADV_UNMERGEABLE +應用於從未標記爲MADV_MERGEABLE的範圍。 + +如果一塊內存區域必須被拆分爲至少一個新的MADV_MERGEABLE區域或MADV_UNMERGEABLE區域， +當該進程將超過 ``vm.max_map_count`` 的設定，則madvise可能返回ENOMEM。（請參閱文檔 +Documentation/admin-guide/sysctl/vm.rst）。 + +與其他madvise調用一樣，它們在用戶地址空間的映射區域上使用：如果指定的範圍包含未 +映射的間隙（儘管在中間的映射區域工作），它們將報告ENOMEM，如果沒有足夠的內存用於 +內部結構，則可能會因EAGAIN而失敗。 + +KSM守護進程sysfs接口 +==================== + +KSM守護進程可以由``/sys/kernel/mm/ksm/`` 中的sysfs文件控制，所有人都可以讀取，但 +只能由root用戶寫入。各接口解釋如下： + + +pages_to_scan + ksmd進程進入睡眠前要掃描的頁數。 + 例如， ``echo 100 > /sys/kernel/mm/ksm/pages_to_scan`` + + 默認值：100（該值被選擇用於演示目的） + +sleep_millisecs + ksmd在下次掃描前應休眠多少毫秒 + 例如， ``echo 20 > /sys/kernel/mm/ksm/sleep_millisecs`` + + 默認值：20（該值被選擇用於演示目的） + +merge_across_nodes + 指定是否可以合併來自不同NUMA節點的頁面。當設置爲0時，ksm僅合併在物理上位 + 於同一NUMA節點的內存區域中的頁面。這降低了訪問共享頁面的延遲。在有明顯的 + NUMA距離上，具有更多節點的系統可能受益於設置該值爲0時的更低延遲。而對於 + 需要對內存使用量最小化的較小系統來說，設置該值爲1（默認設置）則可能會受 + 益於更大共享頁面。在決定使用哪種設置之前，您可能希望比較系統在每種設置下 + 的性能。 ``merge_across_nodes`` 僅當系統中沒有ksm共享頁面時，才能被更改設 + 置：首先將接口`run` 設置爲2從而對頁進行去合併，然後在修改 + ``merge_across_nodes`` 後再將‘run’又設置爲1，以根據新設置來重新合併。 + + 默認值：1（如早期的發佈版本一樣合併跨站點） + +run + * 設置爲0可停止ksmd運行，但保留合併頁面， + * 設置爲1可運行ksmd，例如， ``echo 1 > /sys/kernel/mm/ksm/run`` ， + * 設置爲2可停止ksmd運行，並且對所有目前已合併的頁進行去合併，但保留可合併 + 區域以供下次運行。 + + 默認值：0（必須設置爲1才能激活KSM，除非禁用了CONFIG_SYSFS） + +use_zero_pages + 指定是否應當特殊處理空頁（即那些僅含zero的已分配頁）。當該值設置爲1時， + 空頁與內核零頁合併，而不是像通常情況下那樣空頁自身彼此合併。這可以根據 + 工作負載的不同，在具有着色零頁的架構上可以提高性能。啓用此設置時應小心， + 因爲它可能會降低某些工作負載的KSM性能，比如，當待合併的候選頁面的校驗和 + 與空頁面的校驗和恰好匹配的時候。此設置可隨時更改，僅對那些更改後再合併 + 的頁面有效。 + + 默認值：0（如同早期版本的KSM正常表現） + +max_page_sharing + 單個KSM頁面允許的最大共享站點數。這將強制執行重複數據消除限制，以避免涉 + 及遍歷共享KSM頁面的虛擬映射的虛擬內存操作的高延遲。最小值爲2，因爲新創 + 建的KSM頁面將至少有兩個共享者。該值越高，KSM合併內存的速度越快，去重 + 因子也越高，但是對於任何給定的KSM頁面，虛擬映射的最壞情況遍歷的速度也會 + 越慢。減慢了這種遍歷速度就意味着在交換、壓縮、NUMA平衡和頁面遷移期間， + 某些虛擬內存操作將有更高的延遲，從而降低這些虛擬內存操作調用者的響應能力。 + 其他任務如果不涉及執行虛擬映射遍歷的VM操作，其任務調度延遲不受此參數的影 + 響，因爲這些遍歷本身是調度友好的。 + +stable_node_chains_prune_millisecs + 指定KSM檢查特定頁面的元數據的頻率（即那些達到過時信息數據去重限制標準的 + 頁面）單位是毫秒。較小的毫秒值將以更低的延遲來釋放KSM元數據，但它們將使 + ksmd在掃描期間使用更多CPU。如果還沒有一個KSM頁面達到 ``max_page_sharing`` + 標準，那就沒有什麼用。 + +KSM與MADV_MERGEABLE的工作有效性體現於 ``/sys/kernel/mm/ksm/`` 路徑下的接口： + +pages_shared + 表示多少共享頁正在被使用 +pages_sharing + 表示還有多少站點正在共享這些共享頁，即節省了多少 +pages_unshared + 表示有多少頁是唯一的，但被反覆檢查以進行合併 +pages_volatile + 表示有多少頁因變化太快而無法放在tree中 +full_scans + 表示所有可合併區域已掃描多少次 +stable_node_chains + 達到 ``max_page_sharing`` 限制的KSM頁數 +stable_node_dups + 重複的KSM頁數 + +比值 ``pages_sharing/pages_shared`` 的最大值受限制於 ``max_page_sharing`` +的設定。要想增加該比值，則相應地要增加 ``max_page_sharing`` 的值。 + +監測KSM的收益 +============= + +KSM可以通過合併相同的頁面來節省內存，但也會消耗額外的內存，因爲它需要生成一些rmap_items +來保存每個掃描頁面的簡要rmap信息。其中有些頁面可能會被合併，但有些頁面在被檢查幾次 +後可能無法被合併，這些都是無益的內存消耗。 + +1) 如何確定KSM在全系統範圍內是節省內存還是消耗內存？這裏有一個簡單的近似計算方法供參考:: + + general_profit =~ pages_sharing * sizeof(page) - (all_rmap_items) * + sizeof(rmap_item); + + 其中all_rmap_items可以通過對 ``pages_sharing`` 、 ``pages_shared`` 、 ``pages_unshared`` + 和 ``pages_volatile`` 的求和而輕鬆獲得。 + +2) 單一進程中KSM的收益也可以通過以下近似的計算得到:: + + process_profit =~ ksm_merging_pages * sizeof(page) - + ksm_rmap_items * sizeof(rmap_item). + + 其中ksm_merging_pages顯示在 ``/proc/<pid>/`` 目錄下，而ksm_rmap_items + 顯示在 ``/proc/<pid>/ksm_stat`` 。 + +從應用的角度來看， ``ksm_rmap_items`` 和 ``ksm_merging_pages`` 的高比例意 +味着不好的madvise-applied策略，所以開發者或管理員必須重新考慮如何改變madvis策 +略。舉個例子供參考，一個頁面的大小通常是4K，而rmap_item的大小在32位CPU架構上分 +別是32B，在64位CPU架構上是64B。所以如果 ``ksm_rmap_items/ksm_merging_pages`` +的比例在64位CPU上超過64，或者在32位CPU上超過128，那麼應用程序的madvise策略應 +該被放棄，因爲ksm收益大約爲零或負值。 + +監控KSM事件 +=========== + +在/proc/vmstat中有一些計數器，可以用來監控KSM事件。KSM可能有助於節省內存，這是 +一種權衡，因爲它可能會在KSM COW或複製中的交換上遭受延遲。這些事件可以幫助用戶評估 +是否或如何使用KSM。例如，如果cow_ksm增加得太快，用戶可以減少madvise(, , MADV_MERGEABLE) +的範圍。 + +cow_ksm + 在每次KSM頁面觸發寫時拷貝（COW）時都會被遞增，當用戶試圖寫入KSM頁面時， + 我們必須做一個拷貝。 + +ksm_swpin_copy + 在換入時，每次KSM頁被複制時都會被遞增。請注意，KSM頁在換入時可能會被複 + 制，因爲do_swap_page()不能做所有的鎖，而需要重組一個跨anon_vma的KSM頁。 + +-- +Izik Eidus, +Hugh Dickins, 2009年11月17日。 + diff --git a/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst b/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst index 27638e199f13..fe5a5a07d51a 100644 --- a/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst +++ b/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst @@ -1,13 +1,6 @@ .. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) -.. - If you want to distribute this text under CC-BY-4.0 only, please use 'The - Linux kernel developers' for author attribution and link this as source: - https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst -.. - Note: Only the content of this RST file as found in the Linux kernel sources - is available under CC-BY-4.0, as versions of this text that were processed - (for example by the kernel's build system) might contain content taken from - files which use a more restrictive license. +.. See the bottom of this file for additional redistribution information. + .. include:: ../disclaimer-zh_TW.rst @@ -16,7 +9,7 @@ :譯者: 吳想成 Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> 報告問題 @@ -26,14 +19,16 @@ 簡明指南（亦即 太長不看） ========================== -您面臨的是否爲同系列穩定版或長期支持內核的普通內核的回歸？是否仍然受支持？ +您面臨的是否爲同系列穩定版或長期支持內核的普通內核的迴歸？是否仍然受支持？ 請搜索 `LKML內核郵件列表 <https://lore.kernel.org/lkml/>`_ 和 `Linux穩定版郵件列表 <https://lore.kernel.org/stable/>`_ 存檔中匹配的報告並 加入討論。如果找不到匹配的報告，請安裝該系列的最新版本。如果它仍然出現問題， -報告給穩定版郵件列表（stable@vger.kernel.org）。 +請報告給穩定版郵件列表（stable@vger.kernel.org）並抄送回歸郵件列表 +（regressions@lists.linux.dev）；理想情況下，還可以抄送維護者和相關子系統的 +郵件列表。 在所有其他情況下，請儘可能猜測是哪個內核部分導致了問題。查看MAINTAINERS文件， -了解開發人員希望如何得知問題，大多數情況下，報告問題都是通過電子郵件和抄送 +瞭解開發人員希望如何得知問題，大多數情況下，報告問題都是通過電子郵件和抄送 相關郵件列表進行的。檢查報告目的地的存檔中是否已有匹配的報告；也請搜索 `LKML <https://lore.kernel.org/lkml/>`_ 和網絡。如果找不到可加入的討論，請 安裝 `最新的主線內核 <https://kernel.org/>`_ 。如果仍存在問題，請發送報告。 @@ -45,21 +40,22 @@ **通用提醒** ：當安裝和測試上述內核時，請確保它是普通的（即：沒有補丁，也沒 有使用附加模塊）。還要確保它是在一個正常的環境中構建和運行，並且在問題發生 -之前沒有被汙染（tainted）。 +之前沒有被污染（tainted）。 -在編寫報告時，要涵蓋與問題相關的所有信息，如使用的內核和發行版。在碰見回歸時， -嘗試給出引入它的更改的提交ID，二分可以找到它。如果您同時面臨Linux內核的多個 -問題，請分別報告每個問題。 +當你同時面臨Linux內核的多個問題時，請分別報告。在編寫報告時，要涵蓋與問題 +相關的所有信息，如使用的內核和發行版。如果碰見迴歸，請把報告抄送回歸郵件列表 +（regressions@lists.linux.dev）。也請試試用二分法找出源頭；如果成功找到，請 +在報告中寫上它的提交ID並抄送sign-off-by鏈中的所有人。 一旦報告發出，請回答任何出現的問題，並儘可能地提供幫助。這包括通過不時重新 -測試新版本並發送狀態更新來推動進展。 +測試新版本併發送狀態更新來推動進展。 如何向內核維護人員報告問題的逐步指南 ===================================== -上面的簡明指南概述了如何向Linux內核開發人員報告問題。對於已經熟悉向自由和開 -源軟體（FLOSS）項目報告問題的人來說，這可能是他們所需要的全部內容。對於其他 +上面的簡明指南概述瞭如何向Linux內核開發人員報告問題。對於已經熟悉向自由和開 +源軟件（FLOSS）項目報告問題的人來說，這可能是他們所需要的全部內容。對於其他 人，本部分更爲詳細，並一步一步地描述。爲了便於閱讀，它仍然儘量簡潔，並省略 了許多細節；這些在逐步指南後的參考章節中進行了描述，該章節更詳細地解釋了每 個步驟。 @@ -68,16 +64,16 @@ 儘早意識到看起來像Linux內核毛病的問題可能實際上是由其他原因引起的。這些步驟 可以確保你最終不會覺得在這一過程中投入的時間是浪費： - * 您是否面臨硬體或軟體供應商提供的Linux內核的問題？那麼基本上您最好停止閱讀 + * 您是否面臨硬件或軟件供應商提供的Linux內核的問題？那麼基本上您最好停止閱讀 本文檔，轉而向您的供應商報告問題，除非您願意自己安裝最新的Linux版本。尋找 和解決問題往往需要後者。 - * 使用您喜愛的網絡搜尋引擎對現有報告進行粗略搜索；此外，請檢查 + * 使用您喜愛的網絡搜索引擎對現有報告進行粗略搜索；此外，請檢查 `Linux內核郵件列表（LKML） <https://lore.kernel.org/lkml/>`_ 的存檔。如果 找到匹配的報告，請加入討論而不是發送新報告。 - * 看看你正在處理的問題是否爲回歸問題、安全問題或非常嚴重的問題：這些都是需 - 要在接下來的一些步驟中特別處理的「高優先級問題」。 + * 看看你正在處理的問題是否爲迴歸問題、安全問題或非常嚴重的問題：這些都是需 + 要在接下來的一些步驟中特別處理的“高優先級問題”。 * 確保不是內核環境導致了您面臨的問題。 @@ -86,15 +82,15 @@ * 確保您的系統不會通過動態構建額外的內核模塊來增強其內核，像DKMS這樣的解決 方案可能在您不知情的情況下就在本地進行了這樣的工作。 - * 當問題發生時，檢查您的內核是否被「汙染」，因爲使內核設置這個標誌的事件可能 + * 當問題發生時，檢查您的內核是否被“污染”，因爲使內核設置這個標誌的事件可能 會導致您面臨的問題。 * 粗略地寫下如何重現這個問題。如果您同時處理多個問題，請爲每個問題單獨寫注 釋，並確保它們在新啓動的系統上獨立出現。這是必要的，因爲每個問題都需要分 別報告給內核開發人員，除非它們嚴重糾纏在一起。 - * 如果您正面臨穩定版或長期支持版本線的回歸（例如從5.10.4更新到5.10.5時出現 - 故障），請查看後文「報告穩定版和長期支持內核線的回歸」小節。 + * 如果您正面臨穩定版或長期支持版本線的迴歸（例如從5.10.4更新到5.10.5時出現 + 故障），請查看後文“報告穩定版和長期支持內核線的迴歸”小節。 * 定位可能引起問題的驅動程序或內核子系統。找出其開發人員期望的報告的方式和 位置。注意：大多數情況下不會是 bugzilla.kernel.org，因爲問題通常需要通 @@ -105,61 +101,62 @@ 在完成這些準備之後，你將進入主要部分： - * 除非您已經在運行最新的「主線」Linux內核，否則最好在報告流程前安裝它。在某些 - 情況下，使用最新的「穩定版」Linux進行測試和報告也是可以接受的替代方案；在 + * 除非您已經在運行最新的“主線”Linux內核，否則最好在報告流程前安裝它。在某些 + 情況下，使用最新的“穩定版”Linux進行測試和報告也是可以接受的替代方案；在 合併窗口期間，這實際上可能是最好的方法，但在開發階段最好還是暫停幾天。無論 - 你選擇什麼版本，最好使用「普通」構建。忽略這些建議會大大增加您的報告被拒絕 + 你選擇什麼版本，最好使用“普通”構建。忽略這些建議會大大增加您的報告被拒絕 或忽略的風險。 - * 確保您剛剛安裝的內核在運行時不會「汙染」自己。 + * 確保您剛剛安裝的內核在運行時不會“污染”自己。 * 在您剛剛安裝的內核中復現這個問題。如果它沒有出現，請查看下方只發生在 穩定版和長期支持內核的問題的說明。 - * 優化你的筆記：試著找到並寫出最直接的復現問題的方法。確保最終結果包含所有 + * 優化你的筆記：試着找到並寫出最直接的復現問題的方法。確保最終結果包含所有 重要的細節，同時讓第一次聽說的人容易閱讀和理解。如果您在此過程中學到了一 些東西，請考慮再次搜索關於該問題的現有報告。 - * 如果失敗涉及「panic」、「Oops」、「warning」或「BUG」，請考慮解碼內核日誌以查找觸 + * 如果失敗涉及“panic”、“Oops”、“warning”或“BUG”，請考慮解碼內核日誌以查找觸 發錯誤的代碼行。 - * 如果您的問題是回歸問題，請儘可能縮小引入問題時的範圍。 + * 如果您的問題是迴歸問題，請儘可能縮小引入問題時的範圍。 * 通過詳細描述問題來開始編寫報告。記得包括以下條目：您爲復現而安裝的最新內 核版本、使用的Linux發行版以及關於如何復現該問題的說明。如果可能，將內核 - 構建配置（.config）和 ``dmesg`` 的輸出放在網上的某個地方，並連結到它。包 + 構建配置（.config）和 ``dmesg`` 的輸出放在網上的某個地方，並鏈接到它。包 含或上傳所有其他可能相關的信息，如Oops的輸出/截圖或來自 ``lspci`` 的輸出 。一旦你寫完了這個主要部分，請在上方插入一個正常長度的段落快速概述問題和 影響。再在此之上添加一個簡單描述問題的句子，以得到人們的閱讀。現在給出一 個更短的描述性標題或主題。然後就可以像MAINTAINERS文件告訴你的那樣發送或 - 提交報告了，除非你在處理一個「高優先級問題」：它們需要按照下面「高優先級問 - 題的特殊處理」所述特別關照。 + 提交報告了，除非你在處理一個“高優先級問題”：它們需要按照下面“高優先級問 + 題的特殊處理”所述特別關照。 * 等待別人的反應，繼續推進事情，直到你能夠接受這樣或那樣的結果。因此，請公 開和及時地回應任何詢問。測試提出的修復。積極地測試：至少重新測試每個新主 線版本的首個候選版本（RC），並報告你的結果。如果出現拖延，就友好地提醒一 - 下。如果你沒有得到任何幫助或者未能滿意，請試著自己幫助自己。 + 下。如果你沒有得到任何幫助或者未能滿意，請試着自己幫助自己。 -報告穩定版和長期支持內核線的回歸 +報告穩定版和長期支持內核線的迴歸 ---------------------------------- -如果您發現了穩定版或長期支持內核版本線中的回歸問題並按上述流程跳到這裡，那麼 +如果您發現了穩定版或長期支持內核版本線中的迴歸問題並按上述流程跳到這裏，那麼 請閱讀本小節。即例如您在從5.10.4更新到5.10.5時出現了問題（從5.9.15到5.10.5則 -不是）。開發人員希望儘快修復此類回歸，因此有一個簡化流程來報告它們： +不是）。開發人員希望儘快修復此類迴歸，因此有一個簡化流程來報告它們： * 檢查內核開發人員是否仍然維護你關心的Linux內核版本線：去 `kernel.org 的首頁 - <https://kernel.org/>`_ ，確保此特定版本線的最新版沒有「[EOL]」標記。 + <https://kernel.org/>`_ ，確保此特定版本線的最新版沒有“[EOL]”標記。 * 檢查 `Linux穩定版郵件列表 <https://lore.kernel.org/stable/>`_ 中的現有報告。 - * 從特定的版本線安裝最新版本作爲純淨內核。確保這個內核沒有被汙染，並且仍然 - 存在問題，因爲問題可能已經在那裡被修復了。如果您第一次發現供應商內核的問題， + * 從特定的版本線安裝最新版本作爲純淨內核。確保這個內核沒有被污染，並且仍然 + 存在問題，因爲問題可能已經在那裏被修復了。如果您第一次發現供應商內核的問題， 請檢查已知最新版本的普通構建是否可以正常運行。 - * 向Linux穩定版郵件列表發送一個簡短的問題報告(stable@vger.kernel.org)。大致 - 描述問題，並解釋如何復現。講清楚首個出現問題的版本和最後一個工作正常的版本。 - 然後等待進一步的指示。 + * 向Linux穩定版郵件列表發送一個簡短的問題報告（stable@vger.kernel.org）並抄送 + Linux迴歸郵件列表（regressions@lists.linux.dev）；如果你懷疑是由某子系統 + 引起的，請抄送其維護人員和子系統郵件列表。大致描述問題，並解釋如何復現。 + 講清楚首個出現問題的版本和最後一個工作正常的版本。然後等待進一步的指示。 下面的參考章節部分詳細解釋了這些步驟中的每一步。 @@ -167,14 +164,14 @@ 報告只發生在較舊內核版本線的問題 ---------------------------------- -若您嘗試了上述的最新主線內核，但未能在那裡復現問題，那麼本小節適用於您；以下 +若您嘗試了上述的最新主線內核，但未能在那裏復現問題，那麼本小節適用於您；以下 流程有助於使問題在仍然支持的穩定版或長期支持版本線，或者定期基於最新穩定版或 長期支持內核的供應商內核中得到修復。如果是這種情況，請執行以下步驟： * 請做好準備，接下來的幾個步驟可能無法在舊版本中解決問題：修復可能太大或太 - 冒險，無法移植到那裡。 + 冒險，無法移植到那裏。 - * 執行前節「報告穩定版和長期支持內核線的回歸」中的前三個步驟。 + * 執行前節“報告穩定版和長期支持內核線的迴歸”中的前三個步驟。 * 在Linux內核版本控制系統中搜索修復主線問題的更改，因爲它的提交消息可能會 告訴你修復是否已經計劃好了支持。如果你沒有找到，搜索適當的郵件列表，尋找 @@ -219,14 +216,14 @@ 確保您使用的是上游Linux內核 ---------------------------- - *您是否面臨硬體或軟體供應商提供的Linux內核的問題？那麼基本上您最好停止閱 + *您是否面臨硬件或軟件供應商提供的Linux內核的問題？那麼基本上您最好停止閱 讀本文檔，轉而向您的供應商報告問題，除非您願意自己安裝最新的Linux版本。 尋找和解決問題往往需要後者。* -與大多數程式設計師一樣，Linux內核開發人員不喜歡花時間處理他們維護的原始碼中根本 -不會發生的問題的報告。這只會浪費每個人的時間，尤其是你的時間。不幸的是，當 +與大多數程序員一樣，Linux內核開發人員不喜歡花時間處理他們維護的源代碼中根本 +不會發生的問題的報告。這隻會浪費每個人的時間，尤其是你的時間。不幸的是，當 涉及到內核時，這樣的情況很容易發生，並且常常導致雙方氣餒。這是因爲幾乎所有預 -裝在設備（台式機、筆記本電腦、智慧型手機、路由器等）上的Linux內核，以及大多數 +裝在設備（臺式機、筆記本電腦、智能手機、路由器等）上的Linux內核，以及大多數 由Linux發行商提供的內核，都與由kernel.org發行的官方Linux內核相距甚遠：從Linux 開發的角度來看，這些供應商提供的內核通常是古老的或者經過了大量修改，通常兩點 兼具。 @@ -235,19 +232,19 @@ 可能已經由Linux內核開發人員在數月或數年前修復；此外，供應商的修改和增強可能 會導致您面臨的問題，即使它們看起來很小或者完全不相關。這就是爲什麼您應該向 供應商報告這些內核的問題。它的開發者應該查看報告，如果它是一個上游問題，直接 -於上游修復或將報告轉發到那裡。在實踐中，這有時行不通。因此，您可能需要考慮 +於上游修復或將報告轉發到那裏。在實踐中，這有時行不通。因此，您可能需要考慮 通過自己安裝最新的Linux內核內核來繞過供應商。如果如果您選擇此方法，那麼本指 南後面的步驟將解釋如何在排除了其他可能導致您的問題的原因後執行此操作。 -注意前段使用的詞語是「大多數」，因爲有時候開發人員實際上願意處理供應商內核出現 +注意前段使用的詞語是“大多數”，因爲有時候開發人員實際上願意處理供應商內核出現 的問題報告。他們是否這麼做很大程度上取決於開發人員和相關問題。如果發行版只 根據最近的Linux版本對內核進行了較小修改，那麼機會就比較大；例如對於Debian GNU/Linux Sid或Fedora Rawhide所提供的主線內核。一些開發人員還將接受基於最新 穩定內核的發行版內核問題報告，只要它改動不大；例如Arch Linux、常規Fedora版本 和openSUSE Turboweed。但是請記住，您最好使用主線Linux，並避免在此流程中使用 -穩定版內核，如「安裝一個新的內核進行測試」一節中所詳述。 +穩定版內核，如“安裝一個新的內核進行測試”一節中所詳述。 -當然，您可以忽略所有這些建議，並向上游Linux開發人員報告舊的或經過大量修改的 +當然，您可以忽略所有這些建議，並向上遊Linux開發人員報告舊的或經過大量修改的 供應商內核的問題。但是注意，這樣的報告經常被拒絕或忽視，所以自行小心考慮一下。 不過這還是比根本不報告問題要好：有時候這樣的報告會直接或間接地幫助解決之後的 問題。 @@ -256,64 +253,61 @@ GNU/Linux Sid或Fedora Rawhide所提供的主線內核。一些開發人員還 搜索現有報告（第一部分） ------------------------- - *使用您喜愛的網絡搜尋引擎對現有報告進行粗略搜索；此外，請檢查Linux內核 + *使用您喜愛的網絡搜索引擎對現有報告進行粗略搜索；此外，請檢查Linux內核 郵件列表（LKML）的存檔。如果找到匹配的報告，請加入討論而不是發送新報告。* 報告一個別人已經提出的問題，對每個人來說都是浪費時間，尤其是作爲報告人的你。 所以徹底檢查是否有人已經報告了這個問題，這對你自己是有利的。在流程中的這一步， -可以只執行一個粗略的搜索：一旦您知道您的問題需要報告到哪裡，稍後的步驟將告訴 +可以只執行一個粗略的搜索：一旦您知道您的問題需要報告到哪裏，稍後的步驟將告訴 您如何詳細搜索。儘管如此，不要倉促完成這一步，它可以節省您的時間和減少麻煩。 -只需先用你最喜歡的搜尋引擎在網際網路上搜索。然後再搜索Linux內核郵件列表（LKML） +只需先用你最喜歡的搜索引擎在互聯網上搜索。然後再搜索Linux內核郵件列表（LKML） 存檔。 -如果搜索結果實在太多，可以考慮讓你的搜尋引擎將搜索時間範圍限制在過去的一個 -月或一年。而且無論你在哪裡搜索，一定要用恰當的搜索關鍵詞；也要變化幾次關鍵 -詞。同時，試著從別人的角度看問題：這將幫助你想出其他的關鍵詞。另外，一定不 +如果搜索結果實在太多，可以考慮讓你的搜索引擎將搜索時間範圍限制在過去的一個 +月或一年。而且無論你在哪裏搜索，一定要用恰當的搜索關鍵詞；也要變化幾次關鍵 +詞。同時，試着從別人的角度看問題：這將幫助你想出其他的關鍵詞。另外，一定不 要同時使用過多的關鍵詞。記住搜索時要同時嘗試包含和不包含內核驅動程序的名稱 -或受影響的硬體組件的名稱等信息。但其確切的品牌名稱（比如說「華碩紅魔 Radeon -RX 5700 XT Gaming OC」）往往幫助不大，因爲它太具體了。相反，嘗試搜索術語，如 -型號（Radeon 5700 或 Radeon 5000）和核心代號（「Navi」或「Navi10」），以及包含 -和不包含其製造商（「AMD」）。 +或受影響的硬件組件的名稱等信息。但其確切的品牌名稱（比如說“華碩紅魔 Radeon +RX 5700 XT Gaming OC”）往往幫助不大，因爲它太具體了。相反，嘗試搜索術語，如 +型號（Radeon 5700 或 Radeon 5000）和核心代號（“Navi”或“Navi10”），以及包含 +和不包含其製造商（“AMD”）。 如果你發現了關於你的問題的現有報告，請加入討論，因爲你可能會提供有價值的額 外信息。這一點很重要，即使是在修復程序已經準備好或處於最後階段，因爲開發人 -員可能會尋找能夠提供額外信息或測試建議修復程序的人。跳到「發布報告後的責任」 -一節，了解有關如何正確參與的細節。 +員可能會尋找能夠提供額外信息或測試建議修復程序的人。跳到“發佈報告後的責任” +一節，瞭解有關如何正確參與的細節。 注意，搜索 `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ 網站可能 也是一個好主意，因爲這可能會提供有價值的見解或找到匹配的報告。如果您發現後者， -請記住：大多數子系統都希望在不同的位置報告，如下面「你需要將問題報告到何處」 +請記住：大多數子系統都希望在不同的位置報告，如下面“你需要將問題報告到何處” 一節中所述。因此本應處理這個問題的開發人員甚至可能不知道bugzilla的工單。所以 請檢查工單中的問題是否已經按照本文檔所述得到報告，如果沒有，請考慮這樣做。 高優先級的問題？ ----------------- - *看看你正在處理的問題是否是回歸問題、安全問題或非常嚴重的問題：這些都是 - 需要在接下來的一些步驟中特別處理的「高優先級問題」。* + *看看你正在處理的問題是否是迴歸問題、安全問題或非常嚴重的問題：這些都是 + 需要在接下來的一些步驟中特別處理的“高優先級問題”。* Linus Torvalds和主要的Linux內核開發人員希望看到一些問題儘快得到解決，因此在 -報告過程中有一些「高優先級問題」的處理略有不同。有三種情況符合條件:回歸、安全 +報告過程中有一些“高優先級問題”的處理略有不同。有三種情況符合條件:迴歸、安全 問題和非常嚴重的問題。 -如果在舊版本的Linux內核中工作的東西不能在新版本的Linux內核中工作，或者某種 -程度上在新版本的Linux內核中工作得更差，那麼你就需要處理「回歸」。因此，當一個 -在Linux 5.7中表現良好的WiFi驅動程序在5.8中表現不佳或根本不能工作時，這是一 -種回歸。如果應用程式在新的內核中出現不穩定的現象，這也是一種回歸，這可能是 -由於內核和用戶空間之間的接口（如procfs和sysfs）發生不兼容的更改造成的。顯著 -的性能降低或功耗增加也可以稱爲回歸。但是請記住:新內核需要使用與舊內核相似的 -配置來構建（參見下面如何實現這一點）。這是因爲內核開發人員在實現新特性時有 -時無法避免不兼容性；但是爲了避免回歸，這些特性必須在構建配置期間顯式地啓用。 +如果某個應用程序或實際用例在原先的Linux內核上運行良好，但在使用類似配置編譯的 +較新版本上效果更差、或者根本不能用，那麼你就需要處理迴歸問題。 +Documentation/admin-guide/reporting-regressions.rst 對此進行了更詳細的解釋。 +它還提供了很多你可能想知道的關於迴歸的其他信息；例如，它解釋瞭如何將您的問題 +添加到迴歸跟蹤列表中，以確保它不會被忽略。 什麼是安全問題留給您自己判斷。在繼續之前，請考慮閱讀 -「Documentation/translations/zh_TW/admin-guide/security-bugs.rst」， -因爲它提供了如何最恰當地處理安全問題的額外細節。 +Documentation/translations/zh_CN/admin-guide/security-bugs.rst ， +因爲它提供瞭如何最恰當地處理安全問題的額外細節。 -當發生了完全無法接受的糟糕事情時，此問題就是一個「非常嚴重的問題」。例如， -Linux內核破壞了它處理的數據或損壞了它運行的硬體。當內核突然顯示錯誤消息 -（「kernel panic」）並停止工作，或者根本沒有任何停止信息時，您也在處理一個嚴重 -的問題。注意：不要混淆「panic」（內核停止自身的致命錯誤）和「Oops」（可恢復錯誤）， +當發生了完全無法接受的糟糕事情時，此問題就是一個“非常嚴重的問題”。例如， +Linux內核破壞了它處理的數據或損壞了它運行的硬件。當內核突然顯示錯誤消息 +（“kernel panic”）並停止工作，或者根本沒有任何停止信息時，您也在處理一個嚴重 +的問題。注意：不要混淆“panic”（內核停止自身的致命錯誤）和“Oops”（可恢復錯誤）， 因爲顯示後者之後內核仍然在運行。 @@ -325,22 +319,22 @@ Linux內核破壞了它處理的數據或損壞了它運行的硬體。當內核 看起來很像內核問題的問題有時是由構建或運行時環境引起的。很難完全排除這種問 題，但你應該儘量減少這種問題： - * 構建內核時，請使用經過驗證的工具，因爲編譯器或二進位文件中的錯誤可能會導 + * 構建內核時，請使用經過驗證的工具，因爲編譯器或二進制文件中的錯誤可能會導 致內核出現錯誤行爲。 * 確保您的計算機組件在其設計規範內運行；這對處理器、內存和主板尤爲重要。因 此，當面臨潛在的內核問題時，停止低電壓或超頻。 - * 儘量確保不是硬體故障導致了你的問題。例如，內存損壞會導致大量的問題，這些 + * 儘量確保不是硬件故障導致了你的問題。例如，內存損壞會導致大量的問題，這些 問題會表現爲看起來像內核問題。 * 如果你正在處理一個文件系統問題，你可能需要用 ``fsck`` 檢查一下文件系統， 因爲它可能會以某種方式被損壞，從而導致無法預期的內核行爲。 - * 在處理回歸問題時，要確保沒有在更新內核的同時發生了其他變化。例如，這個問 - 題可能是由同時更新的其他軟體引起的。也有可能是在你第一次重啓進入新內核時， - 某個硬體巧合地壞了。更新系統 BIOS 或改變 BIOS 設置中的某些內容也會導致 - 一些看起來很像內核回歸的問題。 + * 在處理迴歸問題時，要確保沒有在更新內核的同時發生了其他變化。例如，這個問 + 題可能是由同時更新的其他軟件引起的。也有可能是在你第一次重啓進入新內核時， + 某個硬件巧合地壞了。更新系統 BIOS 或改變 BIOS 設置中的某些內容也會導致 + 一些看起來很像內核迴歸的問題。 爲緊急情況做好準備 @@ -349,8 +343,8 @@ Linux內核破壞了它處理的數據或損壞了它運行的硬體。當內核 *創建一個全新的備份，並將系統修復和還原工具放在手邊* 我得提醒您，您正在和計算機打交道，計算機有時會出現意想不到的事情，尤其是當 -您折騰其作業系統的內核等關鍵部件時。而這就是你在這個過程中要做的事情。因此， -一定要創建一個全新的備份；還要確保你手頭有修復或重裝作業系統的所有工具， +您折騰其操作系統的內核等關鍵部件時。而這就是你在這個過程中要做的事情。因此， +一定要創建一個全新的備份；還要確保你手頭有修復或重裝操作系統的所有工具， 以及恢復備份所需的一切。 @@ -366,67 +360,67 @@ Linux內核破壞了它處理的數據或損壞了它運行的硬體。當內核 的任何模塊。然後重新啓動再繼續。 注意，你可能不知道你的系統正在使用這些解決方案之一：當你安裝 Nvidia 專有圖 -形驅動程序、VirtualBox 或其他需要 Linux 內核以外的模塊支持的軟體時，它們通 -常會靜默設置。這就是爲什麼你可能需要卸載這些軟體的軟體包，以擺脫任何第三方 +形驅動程序、VirtualBox 或其他需要 Linux 內核以外的模塊支持的軟件時，它們通 +常會靜默設置。這就是爲什麼你可能需要卸載這些軟件的軟件包，以擺脫任何第三方 內核模塊。 -檢測「汙染」標誌 +檢查“污染”標誌 ---------------- - *當問題發生時，檢查您的內核是否被「汙染」，因爲使內核設置這個標誌的事件可 + *當問題發生時，檢查您的內核是否被“污染”，因爲使內核設置這個標誌的事件可 能會導致您面臨的問題。* -當某些可能會導致看起來完全不相關的後續錯誤的事情發生時，內核會用「汙染 -（taint）」標誌標記自己。如果您的內核受到汙染，那麼您面臨的可能是這樣的錯誤。 +當某些可能會導致看起來完全不相關的後續錯誤的事情發生時，內核會用“污染 +（taint）”標誌標記自己。如果您的內核受到污染，那麼您面臨的可能是這樣的錯誤。 因此在投入更多時間到這個過程中之前，儘早排除此情況可能對你有好處。這是這個 -步驟出現在這裡的唯一原因，因爲這個過程稍後會告訴您安裝最新的主線內核；然後 -您將需要再次檢查汙染標誌，因爲當它出問題的時候內核報告會關注它。 +步驟出現在這裏的唯一原因，因爲這個過程稍後會告訴您安裝最新的主線內核；然後 +您將需要再次檢查污染標誌，因爲當它出問題的時候內核報告會關注它。 -在正在運行的系統上檢查內核是否汙染非常容易：如果 ``cat /proc/sys/kernel/tainted`` -返回「0」，那麼內核沒有被汙染，一切正常。在某些情況下無法檢查該文件；這就是 -爲什麼當內核報告內部問題（「kernel bug」）、可恢復錯誤（「kernel Oops」）或停止 -操作前不可恢復的錯誤（「kernel panic」）時，它也會提到汙染狀態。當其中一個錯 -誤發生時，查看列印的錯誤消息的頂部，搜索以「CPU:」開頭的行。如果發現問題時內 -核未被汙染，那麼它應該以「Not infected」結束；如果你看到「Tainted:」且後跟一些 -空格和字母，那就被汙染了。 +在正在運行的系統上檢查內核是否污染非常容易：如果 ``cat /proc/sys/kernel/tainted`` +返回“0”，那麼內核沒有被污染，一切正常。在某些情況下無法檢查該文件；這就是 +爲什麼當內核報告內部問題（“kernel bug”）、可恢復錯誤（“kernel Oops”）或停止 +操作前不可恢復的錯誤（“kernel panic”）時，它也會提到污染狀態。當其中一個錯 +誤發生時，查看打印的錯誤消息的頂部，搜索以“CPU:”開頭的行。如果發現問題時內 +核未被污染，那麼它應該以“Not infected”結束；如果你看到“Tainted:”且後跟一些 +空格和字母，那就被污染了。 -如果你的內核被汙染了，請閱讀「Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst」 -以找出原因。設法消除汙染因素。通常是由以下三種因素之一引起的： +如果你的內核被污染了，請閱讀 Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst +以找出原因。設法消除污染因素。通常是由以下三種因素之一引起的： - 1. 發生了一個可恢復的錯誤（「kernel Oops」），內核汙染了自己，因爲內核知道在 + 1. 發生了一個可恢復的錯誤（“kernel Oops”），內核污染了自己，因爲內核知道在 此之後它可能會出現奇怪的行爲錯亂。在這種情況下，檢查您的內核或系統日誌， 並尋找以下列文字開頭的部分:: Oops: 0000 [#1] SMP - 如方括號中的「#1」所示，這是自啓動以來的第一次Oops。每個Oops和此後發生的 + 如方括號中的“#1”所示，這是自啓動以來的第一次Oops。每個Oops和此後發生的 任何其他問題都可能是首個Oops的後續問題，即使這兩個問題看起來完全不相關。 通過消除首個Oops的原因並在之後復現該問題，可以排除這種情況。有時僅僅 重新啓動就足夠了，有時更改配置後重新啓動可以消除Oops。但是在這個流程中 不要花費太多時間在這一點上，因爲引起Oops的原因可能已經在您稍後將按流程 安裝的新Linux內核版本中修復了。 - 2. 您的系統使用的軟體安裝了自己的內核模塊，例如Nvidia的專有圖形驅動程序或 - VirtualBox。當內核從外部源（即使它們是開源的）加載此類模塊時，它會汙染 + 2. 您的系統使用的軟件安裝了自己的內核模塊，例如Nvidia的專有圖形驅動程序或 + VirtualBox。當內核從外部源（即使它們是開源的）加載此類模塊時，它會污染 自己：它們有時會在不相關的內核區域導致錯誤，從而可能導致您面臨的問題。 因此，當您想要向Linux內核開發人員報告問題時，您必須阻止這些模塊加載。 - 大多數情況下最簡單的方法是：臨時卸載這些軟體，包括它們可能已經安裝的任 + 大多數情況下最簡單的方法是：臨時卸載這些軟件，包括它們可能已經安裝的任 何模塊。之後重新啓動。 - 3. 當內核加載駐留在Linux內核原始碼staging樹中的模塊時，它也會汙染自身。這 + 3. 當內核加載駐留在Linux內核源代碼staging樹中的模塊時，它也會污染自身。這 是一個特殊的區域，代碼（主要是驅動程序）還沒有達到正常Linux內核的質量 - 標準。當您報告此種模塊的問題時，內核受到汙染顯然是沒有問題的；只需確保 - 問題模塊是造成汙染的唯一原因。如果問題發生在一個不相關的區域，重新啓動 + 標準。當您報告此種模塊的問題時，內核受到污染顯然是沒有問題的；只需確保 + 問題模塊是造成污染的唯一原因。如果問題發生在一個不相關的區域，重新啓動 並通過指定 ``foo.blacklist=1`` 作爲內核參數臨時阻止該模塊被加載（用有 - 問題的模塊名替換「foo」）。 + 問題的模塊名替換“foo”）。 記錄如何重現問題 ------------------ *粗略地寫下如何重現這個問題。如果您同時處理多個問題，請爲每個問題單獨寫 - 注釋，並確保它們在新啓動的系統上獨立出現。這是必要的，因爲每個問題都需 + 註釋，並確保它們在新啓動的系統上獨立出現。這是必要的，因爲每個問題都需 要分別報告給內核開發人員，除非它們嚴重糾纏在一起。* 如果你同時處理多個問題，必須分別報告每個問題，因爲它們可能由不同的開發人員 @@ -438,20 +432,20 @@ Linux內核破壞了它處理的數據或損壞了它運行的硬體。當內核 注意：報告只發生過一次的問題往往是沒有結果的，因爲它們可能是由於宇宙輻射導 致的位翻轉。所以你應該嘗試通過重現問題來排除這種情況，然後再繼續。如果你有 -足夠的經驗來區分由於硬體故障引起的一次性錯誤和難以重現的罕見內核問題，可以 +足夠的經驗來區分由於硬件故障引起的一次性錯誤和難以重現的罕見內核問題，可以 忽略這個建議。 -穩定版或長期支持內核的回歸？ +穩定版或長期支持內核的迴歸？ ----------------------------- - *如果您正面臨穩定版或長期支持版本線的回歸（例如從5.10.4更新到5.10.5時出現 - 故障），請查看後文「報告穩定版和長期支持內核線的回歸」小節。* + *如果您正面臨穩定版或長期支持版本線的迴歸（例如從5.10.4更新到5.10.5時出現 + 故障），請查看後文“報告穩定版和長期支持內核線的迴歸”小節。* -穩定版和長期支持內核版本線中的回歸是Linux開發人員非常希望解決的問題，這樣的 -問題甚至比主線開發分支中的回歸更不應出現，因爲它們會很快影響到很多人。開發人員 -希望儘快了解此類問題，因此有一個簡化流程來報告這些問題。注意，使用更新內核版 -本線的回歸（比如從5.9.15切換到5.10.5時出現故障）不符合條件。 +穩定版和長期支持內核版本線中的迴歸是Linux開發人員非常希望解決的問題，這樣的 +問題甚至比主線開發分支中的迴歸更不應出現，因爲它們會很快影響到很多人。開發人員 +希望儘快瞭解此類問題，因此有一個簡化流程來報告這些問題。注意，使用更新內核版 +本線的迴歸（比如從5.9.15切換到5.10.5時出現故障）不符合條件。 你需要將問題報告到何處 @@ -462,9 +456,9 @@ Linux內核破壞了它處理的數據或損壞了它運行的硬體。當內核 過郵件發送給維護人員和公共郵件列表。* 將報告發送給合適的人是至關重要的，因爲Linux內核是一個大項目，大多數開發人員 -只熟悉其中的一小部分。例如，相當多的程式設計師只關心一個驅動程序，比如一個WiFi -晶片驅動程序；它的開發人員可能對疏遠的或不相關的「子系統」（如TCP堆棧、 -PCIe/PCI子系統、內存管理或文件系統）的內部知識了解很少或完全不了解。 +只熟悉其中的一小部分。例如，相當多的程序員只關心一個驅動程序，比如一個WiFi +芯片驅動程序；它的開發人員可能對疏遠的或不相關的“子系統”（如TCP堆棧、 +PCIe/PCI子系統、內存管理或文件系統）的內部知識瞭解很少或完全不瞭解。 問題在於：Linux內核缺少一個，可以簡單地將問題歸檔並讓需要了解它的開發人員了 解它的，中心化缺陷跟蹤器。這就是爲什麼你必須找到正確的途徑來自己報告問題。 @@ -476,10 +470,10 @@ PCIe/PCI子系統、內存管理或文件系統）的內部知識了解很少或 爲了說明如何使用 :ref:`MAINTAINERS <maintainers>` 文件，讓我們假設您的筆記 本電腦中的WiFi在更新內核後突然出現了錯誤行爲。這種情況下可能是WiFi驅動的問 -題。顯然，它也可能由於驅動基於的某些代碼，但除非你懷疑有這樣的東西會附著在 -驅動程序上。如果真的是其他的問題，驅動程序的開發人員會讓合適的人參與進來。 +題。顯然，它也可能由於驅動基於的某些代碼，但除非你懷疑有這樣的東西會附着在 +驅動程序上。如果真的是其他的問題，驅動程序的開發人員會讓合適的人蔘與進來。 -遺憾的是，沒有通用且簡單的辦法來檢查哪個代碼驅動了特定硬體組件。 +遺憾的是，沒有通用且簡單的辦法來檢查哪個代碼驅動了特定硬件組件。 在WiFi驅動出現問題的情況下，你可能想查看 ``lspci -k`` 的輸出，因爲它列出了 PCI/PCIe總線上的設備和驅動它的內核模塊:: @@ -492,19 +486,19 @@ PCI/PCIe總線上的設備和驅動它的內核模塊:: Kernel modules: ath10k_pci [...] -但如果你的WiFi晶片通過USB或其他內部總線連接，這種方法就行不通了。在這種情況 +但如果你的WiFi芯片通過USB或其他內部總線連接，這種方法就行不通了。在這種情況 下，您可能需要檢查您的WiFi管理器或 ``ip link`` 的輸出。尋找有問題的網絡接口 -的名稱，它可能類似於「wlp58s0」。此名稱可以用來找到驅動它的模塊:: +的名稱，它可能類似於“wlp58s0”。此名稱可以用來找到驅動它的模塊:: [user@something ~]$ realpath --relative-to=/sys/module//sys/class/net/wlp58s0/device/driver/module ath10k_pci 如果這些技巧不能進一步幫助您，請嘗試在網上搜索如何縮小相關驅動程序或子系統 -的範圍。如果你不確定是哪一個：試著猜一下，即使你猜得不好，也會有人會幫助你 +的範圍。如果你不確定是哪一個：試着猜一下，即使你猜得不好，也會有人會幫助你 的。 一旦您知道了相應的驅動程序或子系統，您就希望在MAINTAINERS文件中搜索它。如果 -是「ath10k_pci」，您不會找到任何東西，因爲名稱太具體了。有時你需要在網上尋找 +是“ath10k_pci”，您不會找到任何東西，因爲名稱太具體了。有時你需要在網上尋找 幫助；但在此之前，請嘗試使用一個稍短或修改過的名稱來搜索MAINTAINERS文件，因 爲這樣你可能會發現類似這樣的東西:: @@ -516,23 +510,23 @@ PCI/PCIe總線上的設備和驅動它的內核模塊:: SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kvalo/ath.git Files: drivers/net/wireless/ath/ath10k/ -注意：如果您閱讀在Linux原始碼樹的根目錄中找到的原始維護者文件，則行描述將是 -縮寫。例如，「Mail:（郵件）」將是「M:」，「Mailing list:（郵件列表）」將是「L」， -「Status:（狀態）」將是「S:」。此文件頂部有一段解釋了這些和其他縮寫。 +注意：如果您閱讀在Linux源代碼樹的根目錄中找到的原始維護者文件，則行描述將是 +縮寫。例如，“Mail:（郵件）”將是“M:”，“Mailing list:（郵件列表）”將是“L”， +“Status:（狀態）”將是“S:”。此文件頂部有一段解釋了這些和其他縮寫。 -首先查看「Status」狀態行。理想情況下，它應該得到「Supported（支持）」或 -「Maintained（維護）」。如果狀態爲「Obsolete（過時的）」，那麼你在使用一些過時的 -方法，需要轉換到新的解決方案上。有時候，只有在感到有動力時，才會有人爲代碼 -提供「Odd Fixes」。如果碰見「Orphan」，你就完全不走運了，因爲再也沒有人關心代碼 -了，只剩下這些選項:準備好與問題共存，自己修復它，或者找一個願意修復它的程式設計師。 +首先查看“Status”狀態行。理想情況下，它應該得到“Supported（支持）”或 +“Maintained（維護）”。如果狀態爲“Obsolete（過時的）”，那麼你在使用一些過時的 +方法，需要轉換到新的解決方案上。有時候，只有在感到有動力時，纔會有人爲代碼 +提供“Odd Fixes”。如果碰見“Orphan”，你就完全不走運了，因爲再也沒有人關心代碼 +了，只剩下這些選項:準備好與問題共存，自己修復它，或者找一個願意修復它的程序員。 -檢查狀態後，尋找以「bug:」開頭的一行：它將告訴你在哪裡可以找到子系統特定的缺 +檢查狀態後，尋找以“bug:”開頭的一行：它將告訴你在哪裏可以找到子系統特定的缺 陷跟蹤器來提交你的問題。上面的例子沒有此行。大多數部分都是這樣，因爲 Linux 內核的開發完全是由郵件驅動的。很少有子系統使用缺陷跟蹤器，且其中只有一部分 依賴於 bugzilla.kernel.org。 -在這種以及其他很多情況下，你必須尋找以「Mail:」開頭的行。這些行提到了特定代碼 -的維護者的名字和電子郵件地址。也可以查找以「Mailing list:」開頭的行，它告訴你 +在這種以及其他很多情況下，你必須尋找以“Mail:”開頭的行。這些行提到了特定代碼 +的維護者的名字和電子郵件地址。也可以查找以“Mailing list:”開頭的行，它告訴你 開發代碼的公共郵件列表。你的報告之後需要通過郵件發到這些地址。另外，對於所有 通過電子郵件發送的問題報告，一定要抄送 Linux Kernel Mailing List（LKML） <linux-kernel@vger.kernel.org>。在以後通過郵件發送問題報告時，不要遺漏任何 @@ -544,8 +538,8 @@ PCI/PCIe總線上的設備和驅動它的內核模塊:: ~~~~~~~~~~~~~~~~~~~~ 對於手頭有Linux源碼的人來說，有第二個可以找到合適的報告地點的選擇：腳本 -「scripts/get_maintainer.pl」，它嘗試找到所有要聯繫的人。它會查詢MAINTAINERS -文件，並需要用相關原始碼的路徑來調用。對於編譯成模塊的驅動程序，經常可以用 +“scripts/get_maintainer.pl”，它嘗試找到所有要聯繫的人。它會查詢MAINTAINERS +文件，並需要用相關源代碼的路徑來調用。對於編譯成模塊的驅動程序，經常可以用 這樣的命令找到:: $ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kernel/!!; s!filename:!!; s!\.ko\(\|\.xz\)!!' @@ -561,13 +555,13 @@ PCI/PCIe總線上的設備和驅動它的內核模塊:: netdev@vger.kernel.org (open list:NETWORKING DRIVERS) linux-kernel@vger.kernel.org (open list) -不要把你的報告發給所有的人。發送給維護者，腳本稱之爲「supporter:」；另外抄送 +不要把你的報告發給所有的人。發送給維護者，腳本稱之爲“supporter:”；另外抄送 代碼最相關的郵件列表，以及 Linux 內核郵件列表（LKML）。在此例中，你需要將報 -告發送給 「Some Human <shuman@example.com>」 ，並抄送 -「ath10k@lists.infradead.org」和「linux-kernel@vger.kernel.org」。 +告發送給 “Some Human <shuman@example.com>” ，並抄送 +“ath10k@lists.infradead.org”和“linux-kernel@vger.kernel.org”。 -注意：如果你用 git 克隆了 Linux 原始碼，你可能需要用--git 再次調用 -get_maintainer.pl。腳本會查看提交歷史，以找到最近哪些人參與了相關代碼的編寫， +注意：如果你用 git 克隆了 Linux 源代碼，你可能需要用--git 再次調用 +get_maintainer.pl。腳本會查看提交歷史，以找到最近哪些人蔘與了相關代碼的編寫， 因爲他們可能會提供幫助。但要小心使用這些結果，因爲它很容易讓你誤入歧途。 例如，這種情況常常會發生在很少被修改的地方（比如老舊的或未維護的驅動程序）： 有時這樣的代碼會在樹級清理期間被根本不關心此驅動程序的開發者修改。 @@ -580,73 +574,74 @@ get_maintainer.pl。腳本會查看提交歷史，以找到最近哪些人參與 如果找到匹配的報告，請加入討論而不是發送新報告。* 如前所述：報告一個別人已經提出的問題，對每個人來說都是浪費時間，尤其是作爲報告 -人的你。這就是爲什麼你應該再次搜索現有的報告。現在你已經知道問題需要報告到哪裡。 +人的你。這就是爲什麼你應該再次搜索現有的報告。現在你已經知道問題需要報告到哪裏。 如果是郵件列表，那麼一般在 `lore.kernel.org <https://lore.kernel.org/>`_ 可以 找到相應存檔。 但有些列表運行在其他地方。例如前面步驟中當例子的ath10k WiFi驅動程序就是這種 -情況。但是你通常可以在網上很容易地找到這些列表的檔案。例如搜索「archive -ath10k@lists.infradead.org」，將引導您到ath10k郵件列表的信息頁，該頁面頂部連結 +情況。但是你通常可以在網上很容易地找到這些列表的檔案。例如搜索“archive +ath10k@lists.infradead.org”，將引導您到ath10k郵件列表的信息頁，該頁面頂部鏈接 到其 `列表存檔 <https://lists.infradead.org/pipermail/ath10k/>`_ 。遺憾的是， -這個列表和其他一些列表缺乏搜索其存檔的功能。在這種情況下可以使用常規的網際網路 -搜尋引擎，並添加類似「site:lists.infadead.org/pipermail/ath10k/」這 -樣的搜索條件，這會把結果限制在該連結中的檔案。 +這個列表和其他一些列表缺乏搜索其存檔的功能。在這種情況下可以使用常規的互聯網 +搜索引擎，並添加類似“site:lists.infadead.org/pipermail/ath10k/”這 +樣的搜索條件，這會把結果限制在該鏈接中的檔案。 -也請進一步搜索網絡、LKML和bugzilla.kernel.org網站。 +也請進一步搜索網絡、LKML和bugzilla.kernel.org網站。如果你的報告需要發送到缺陷 +跟蹤器中，那麼您可能還需要檢查子系統的郵件列表存檔，因爲可能有人只在那裏報告了它。 -有關如何搜索以及在找到匹配報告時如何操作的詳細信息，請參閱上面的「搜索現有報告 -（第一部分）」。 +有關如何搜索以及在找到匹配報告時如何操作的詳細信息，請參閱上面的“搜索現有報告 +（第一部分）”。 -不要急著完成報告過程的這一步：花30到60分鐘甚至更多的時間可以爲你和其他人節省 / +不要急着完成報告過程的這一步：花30到60分鐘甚至更多的時間可以爲你和其他人節省 / 減少相當多的時間和麻煩。 安裝一個新的內核進行測試 -------------------------- - *除非您已經在運行最新的「主線」Linux內核，否則最好在報告流程前安裝它。在 - 某些情況下，使用最新的「穩定版」Linux進行測試和報告也是可以接受的替代方案； + *除非您已經在運行最新的“主線”Linux內核，否則最好在報告流程前安裝它。在 + 某些情況下，使用最新的“穩定版”Linux進行測試和報告也是可以接受的替代方案； 在合併窗口期間，這實際上可能是最好的方法，但在開發階段最好還是暫停幾天。 - 無論你選擇什麼版本，最好使用「普通」構建。忽略這些建議會大大增加您的報告 + 無論你選擇什麼版本，最好使用“普通”構建。忽略這些建議會大大增加您的報告 被拒絕或忽略的風險。* -正如第一步的詳細解釋中所提到的：與大多數程式設計師一樣，與大多數程式設計師一樣，Linux -內核開發人員不喜歡花時間處理他們維護的原始碼中根本不會發生的問題的報告。這隻 +正如第一步的詳細解釋中所提到的：與大多數程序員一樣，與大多數程序員一樣，Linux +內核開發人員不喜歡花時間處理他們維護的源代碼中根本不會發生的問題的報告。這隻 會浪費每個人的時間，尤其是你的時間。這就是爲什麼在報告問題之前，您必須先確認 問題仍然存在於最新的上游代碼中，這符合每個人的利益。您可以忽略此建議，但如前 所述：這樣做會極大地增加問題報告被拒絕或被忽略的風險。 -內核「最新上游」的範圍通常指： +內核“最新上游”的範圍通常指： * 安裝一個主線內核；最新的穩定版內核也可以是一個選擇，但大多數時候都最好避免。 - 長期支持內核（有時稱爲「LTS內核」）不適合此流程。下一小節將更詳細地解釋所有 + 長期支持內核（有時稱爲“LTS內核”）不適合此流程。下一小節將更詳細地解釋所有 這些。 * 下一小節描述獲取和安裝這樣一個內核的方法。它還指出了使用預編譯內核是可以的， - 但普通的內核更好，這意味著：它是直接使用從 `kernel.org <https://kernel.org/>`_ - 獲得的Linux原始碼構建並且沒有任何方式修改或增強。 + 但普通的內核更好，這意味着：它是直接使用從 `kernel.org <https://kernel.org/>`_ + 獲得的Linux源代碼構建並且沒有任何方式修改或增強。 選擇適合測試的版本 ~~~~~~~~~~~~~~~~~~~~ -前往 `kernel.org <https://kernel.org/>`_ 來決定使用哪個版本。忽略那個寫著 -「Latest release最新版本」的巨大黃色按鈕，往下看有一個表格。在表格的頂部，你會 -看到一行以「mainline」開頭的字樣，大多數情況下它會指向一個版本號類似「5.8-rc2」 -的預發布版本。如果是這樣的話，你將需要使用這個主線內核進行測試。不要讓「rc」 -嚇到你，這些「開發版內核」實際上非常可靠——而且你已經按照上面的指示做了備份， +前往 `kernel.org <https://kernel.org/>`_ 來決定使用哪個版本。忽略那個寫着 +“Latest release最新版本”的巨大黃色按鈕，往下看有一個表格。在表格的頂部，你會 +看到一行以“mainline”開頭的字樣，大多數情況下它會指向一個版本號類似“5.8-rc2” +的預發佈版本。如果是這樣的話，你將需要使用這個主線內核進行測試。不要讓“rc” +嚇到你，這些“開發版內核”實際上非常可靠——而且你已經按照上面的指示做了備份， 不是嗎？ -大概每九到十周，「mainline」可能會給你指出一個版本號類似「5.7」的正式版本。如果 -碰見這種情況，請考慮暫停報告過程，直到下一個版本的第一個預發布（5.8-rc1）出 -現在 `kernel.org <https://kernel.org/>`_ 上。這是因爲 Linux 的開發周期正在 -兩周的「合併窗口」內。大部分的改動和所有干擾性的改動都會在這段時間內被合併到 +大概每九到十週，“mainline”可能會給你指出一個版本號類似“5.7”的正式版本。如果 +碰見這種情況，請考慮暫停報告過程，直到下一個版本的第一個預發佈（5.8-rc1）出 +現在 `kernel.org <https://kernel.org/>`_ 上。這是因爲 Linux 的開發週期正在 +兩週的“合併窗口”內。大部分的改動和所有干擾性的改動都會在這段時間內被合併到 下一個版本中。在此期間使用主線是比較危險的。內核開發者通常也很忙，可能沒有 多餘的時間來處理問題報告。這也是很有可能在合併窗口中應用了許多修改來修復你 -所面臨的問題；這就是爲什麼你很快就得用一個新的內核版本重新測試，就像下面「發 -布報告後的責任」一節中所述的那樣。 +所面臨的問題；這就是爲什麼你很快就得用一個新的內核版本重新測試，就像下面“發 +布報告後的責任”一節中所述的那樣。 -這就是爲什麼要等到合併窗口結束後才去做。但是如果你處理的是一些不應該等待的 +這就是爲什麼要等到合併窗口結束後纔去做。但是如果你處理的是一些不應該等待的 東西，則無需這樣做。在這種情況下，可以考慮通過 git 獲取最新的主線內核（見下 文），或者使用 kernel.org 上提供的最新穩定版本。如果 mainline 因爲某些原因 不無法正常工作，那麼使用它也是可以接受的。總的來說：用它來重現問題也比完全 @@ -657,7 +652,7 @@ ath10k@lists.infradead.org」，將引導您到ath10k郵件列表的信息頁， 需要先在主線修復，然後才能得到回傳，這可能需要幾天或幾周。另一個原因是：您 希望的修復對於回傳來說可能太難或太冒險；因此再次報告問題不太可能改變任何事情。 -這些方面也部分表明了爲什麼長期支持內核（有時稱爲「LTS內核」）不適合報告流程： +這些方面也部分表明了爲什麼長期支持內核（有時稱爲“LTS內核”）不適合報告流程： 它們與當前代碼的距離太遠。因此，先去測試主線，然後再按流程走：如果主線沒有 出現問題，流程將指導您如何在舊版本線中修復它。 @@ -669,31 +664,31 @@ ath10k@lists.infradead.org」，將引導您到ath10k郵件列表的信息頁， **使用預編譯的內核** ：這往往是最快速、最簡單、最安全的方法——尤其是在你不熟 悉 Linux 內核的情況下。問題是：發行商或附加存儲庫提供的大多數版本都是從修改 -過的Linux原始碼構建的。因此它們不是普通的，通常不適合於測試和問題報告：這些 +過的Linux源代碼構建的。因此它們不是普通的，通常不適合於測試和問題報告：這些 更改可能會導致您面臨的問題或以某種方式影響問題。 但是如果您使用的是流行的Linux發行版，那麼您就很幸運了：對於大部分的發行版， 您可以在網上找到包含最新主線或穩定版本Linux內核包的存儲庫。使用這些是完全可 -以的，只要從存儲庫的描述中確認它們是普通的或者至少接近普通。此外，請確保軟體 -包包含kernel.org上提供的最新版本內核。如果這些軟體包的時間超過一周，那麼它們 -可能就不合適了，因爲新的主線和穩定版內核通常至少每周發布一次。 +以的，只要從存儲庫的描述中確認它們是普通的或者至少接近普通。此外，請確保軟件 +包包含kernel.org上提供的最新版本內核。如果這些軟件包的時間超過一週，那麼它們 +可能就不合適了，因爲新的主線和穩定版內核通常至少每週發佈一次。 請注意，您以後可能需要手動構建自己的內核：有時這是調試或測試修復程序所必需的， 如後文所述。還要注意，預編譯的內核可能缺少在出現panic、Oops、warning或BUG時 -解碼內核列印的消息所需的調試符號；如果您計劃解碼這些消息，最好自己編譯內核 -（有關詳細信息，請參閱本小節結尾和「解碼失敗信息」小節）。 +解碼內核打印的消息所需的調試符號；如果您計劃解碼這些消息，最好自己編譯內核 +（有關詳細信息，請參閱本小節結尾和“解碼失敗信息”小節）。 **使用git** ：熟悉 git 的開發者和有經驗的 Linux 用戶通常最好直接從 `kernel.org 上的官方開發倉庫 <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_ -中獲取最新的 Linux 內核原始碼。這些很可能比最新的主線預發布版本更新一些。不 -用擔心：它們和正式的預發布版本一樣可靠，除非內核的開發周期目前正處於合併窗 +中獲取最新的 Linux 內核源代碼。這些很可能比最新的主線預發佈版本更新一些。不 +用擔心：它們和正式的預發佈版本一樣可靠，除非內核的開發週期目前正處於合併窗 口中。不過即便如此，它們也是相當可靠的。 **常規方法** ：不熟悉 git 的人通常最好從 `kernel.org <https://kernel.org/>`_ 下載源碼的tar 存檔包。 -如何實際構建一個內核並不在這裡描述，因爲許多網站已經解釋了必要的步驟。如果 +如何實際構建一個內核並不在這裏描述，因爲許多網站已經解釋了必要的步驟。如果 你是新手，可以考慮按照那些建議使用 ``make localmodconfig`` 來做，它將嘗試獲 取你當前內核的配置，然後根據你的系統進行一些調整。這樣做並不能使編譯出來的 內核更好，但可以更快地編譯。 @@ -702,19 +697,19 @@ ath10k@lists.infradead.org」，將引導您到ath10k郵件列表的信息頁， 啓用 CONFIG_KALLSYMS 選項。此外，還可以啓用 CONFIG_DEBUG_KERNEL 和 CONFIG_DEBUG_INFO；後者是相關選項，但只有啓用前者才能開啓。請注意， CONFIG_DEBUG_INFO 會需要更多儲存空間來構建內核。但這是值得的，因爲這些選項將 -允許您稍後精確定位觸發問題的確切代碼行。下面的「解碼失敗信息」一節對此進行了更 +允許您稍後精確定位觸發問題的確切代碼行。下面的“解碼失敗信息”一節對此進行了更 詳細的解釋。 但請記住：始終記錄遇到的問題，以防難以重現。發送未解碼的報告總比不報告要好。 -檢查「汙染」標誌 +檢查“污染”標誌 ---------------- - *確保您剛剛安裝的內核在運行時不會「汙染」自己。* + *確保您剛剛安裝的內核在運行時不會“污染”自己。* 正如上面已經詳細介紹過的：當發生一些可能會導致一些看起來完全不相關的後續錯 -誤的事情時，內核會設置一個「汙染」標誌。這就是爲什麼你需要檢查你剛剛安裝的內 +誤的事情時，內核會設置一個“污染”標誌。這就是爲什麼你需要檢查你剛剛安裝的內 核是否有設置此標誌。如果有的話，幾乎在任何情況下你都需要在報告問題之前先消 除它。詳細的操作方法請看上面的章節。 @@ -729,43 +724,43 @@ CONFIG_DEBUG_INFO 會需要更多儲存空間來構建內核。但這是值得 可以考慮使用此版本線，放棄報告問題。但是請記住，只要它沒有在 `kernel.org <https://kernel.org/>`_ 的穩定版和長期版（以及由這些版本衍生出來的廠商內核） 中得到修復，其他用戶可能仍然會受到它的困擾。如果你喜歡使用其中的一個，或 -者只是想幫助它們的用戶，請前往下面的「報告只發生在較舊內核版本線的問題」一節。 +者只是想幫助它們的用戶，請前往下面的“報告只發生在較舊內核版本線的問題”一節。 優化復現問題的描述 -------------------- - *優化你的筆記：試著找到並寫出最直接的復現問題的方法。確保最終結果包含所 + *優化你的筆記：試着找到並寫出最直接的復現問題的方法。確保最終結果包含所 有重要的細節，同時讓第一次聽說的人容易閱讀和理解。如果您在此過程中學到 了一些東西，請考慮再次搜索關於該問題的現有報告。* 過於複雜的報告會讓別人很難理解。因此請儘量找到一個可以直接描述、易於以書面 形式理解的再現方法。包含所有重要的細節，但同時也要儘量保持簡短。 -在這在前面的步驟中，你很可能已經了解了一些關於你所面臨的問題的點。利用這些 +在這在前面的步驟中，你很可能已經瞭解了一些關於你所面臨的問題的點。利用這些 知識，再次搜索可以轉而加入的現有報告。 解碼失敗信息 ------------- - *如果失敗涉及「panic」、「Oops」、「warning」或「BUG」，請考慮解碼內核日誌以查找 + *如果失敗涉及“panic”、“Oops”、“warning”或“BUG”，請考慮解碼內核日誌以查找 觸發錯誤的代碼行。* -當內核檢測到內部問題時，它會記錄一些有關已執行代碼的信息。這使得在原始碼中精 +當內核檢測到內部問題時，它會記錄一些有關已執行代碼的信息。這使得在源代碼中精 確定位觸發問題的行並顯示如何調用它成爲可能。但只有在配置內核時啓用了 CONFIG_DEBUG_INFO 和 CONFIG_KALLSYMS選項時，這種方法才起效。如果已啓用此選項， -請考慮解碼內核日誌中的信息。這將使我們更容易理解是什麼導致了「panic」、「Oops」、 -「warning」或「BUG」，從而增加了有人提供修復的機率。 +請考慮解碼內核日誌中的信息。這將使我們更容易理解是什麼導致了“panic”、“Oops”、 +“warning”或“BUG”，從而增加了有人提供修復的幾率。 -解碼可以通過Linux原始碼樹中的腳本來完成。如果您運行的內核是之前自己編譯的， +解碼可以通過Linux源代碼樹中的腳本來完成。如果您運行的內核是之前自己編譯的， 這樣這樣調用它:: [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh ./linux-5.10.5/vmlinux /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/ 如果您運行的是打包好的普通內核，則可能需要安裝帶有調試符號的相應包。然後按以下 -方式調用腳本（如果發行版未打包，則可能需要從Linux原始碼獲取）:: +方式調用腳本（如果發行版未打包，則可能需要從Linux源代碼獲取）:: [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh \ /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/ @@ -778,10 +773,10 @@ CONFIG_DEBUG_INFO 和 CONFIG_KALLSYMS選項時，這種方法才起效。如果 [ 68.387301] RIP: 0010:test_module_init (/home/username/linux-5.10.5/test-module/test-module.c:16) test_module -在本例中，執行的代碼是從文件「~/linux-5.10.5/test-module/test-module.c」構建的， +在本例中，執行的代碼是從文件“~/linux-5.10.5/test-module/test-module.c”構建的， 錯誤出現在第16行的指令中。 -該腳本也會如此解碼以「Call trace」開頭的部分中提到的地址，該部分顯示出現問題的 +該腳本也會如此解碼以“Call trace”開頭的部分中提到的地址，該部分顯示出現問題的 函數的路徑。此外，腳本還會顯示內核正在執行的代碼部分的彙編輸出。 注意，如果你沒法做到這一點，只需跳過這一步，並在報告中說明原因。如果你幸運的 @@ -790,60 +785,60 @@ CONFIG_DEBUG_INFO 和 CONFIG_KALLSYMS選項時，這種方法才起效。如果 別擔心，如果您碰到的情況需要這樣做，開發人員會告訴您該怎麼做。 -對回歸的特別關照 +對迴歸的特別關照 ----------------- - *如果您的問題是回歸問題，請儘可能縮小引入問題時的範圍。* + *如果您的問題是迴歸問題，請儘可能縮小引入問題時的範圍。* Linux 首席開發者 Linus Torvalds 認爲 Linux 內核永遠不應惡化，這就是爲什麼他 -認爲回歸是不可接受的，並希望看到它們被迅速修復。這就是爲什麼引入了回歸的改 -動導致的問題若無法通過其他方式快速解決，通常會被迅速撤銷。因此，報告回歸有 -點像「王炸」，會迅速得到修復。但要做到這一點，需要知道導致回歸的變化。通常情 +認爲迴歸是不可接受的，並希望看到它們被迅速修復。這就是爲什麼引入了迴歸的改 +動導致的問題若無法通過其他方式快速解決，通常會被迅速撤銷。因此，報告迴歸有 +點像“王炸”，會迅速得到修復。但要做到這一點，需要知道導致迴歸的變化。通常情 況下，要由報告者來追查罪魁禍首，因爲維護者往往沒有時間或手頭設置不便來自行 重現它。 -有一個叫做「二分」的過程可以來尋找變化，這在 -「Documentation/translations/zh_TW/admin-guide/bug-bisect.rst」文檔中進行了詳細 +有一個叫做“二分”的過程可以來尋找變化，這在 +Documentation/translations/zh_CN/admin-guide/bug-bisect.rst 文檔中進行了詳細 的描述，這個過程通常需要你構建十到二十個內核鏡像，每次都嘗試在構建下一個鏡像 -之前重現問題。是的，這需要花費一些時間，但不用擔心，它比大多數人想像的要快得多。 -多虧了「binary search二進位搜索」，這將引導你在原始碼管理系統中找到導致回歸的提交。 +之前重現問題。是的，這需要花費一些時間，但不用擔心，它比大多數人想象的要快得多。 +多虧了“binary search二分搜索”，這將引導你在源代碼管理系統中找到導致迴歸的提交。 一旦你找到它，就在網上搜索其主題、提交ID和縮短的提交ID（提交ID的前12個字符）。 如果有的話，這將引導您找到關於它的現有報告。 需要注意的是，二分法需要一點竅門，不是每個人都懂得訣竅，也需要相當多的努力， 不是每個人都願意投入。儘管如此，還是強烈建議自己進行一次二分。如果你真的 -不能或者不想走這條路，至少要找出是哪個主線內核引入的回歸。比如說從 5.5.15 +不能或者不想走這條路，至少要找出是哪個主線內核引入的迴歸。比如說從 5.5.15 切換到 5.8.4 的時候出現了一些問題，那麼至少可以嘗試一下相近的所有的主線版本 （5.6、5.7 和 5.8）來檢查它是什麼時候出現的。除非你想在一個穩定版或長期支持 -內核中找到一個回歸，否則要避免測試那些編號有三段的版本（5.6.12、5.7.8），因 -爲那會使結果難以解釋，可能會讓你的測試變得無用。一旦你找到了引入回歸的主要 +內核中找到一個迴歸，否則要避免測試那些編號有三段的版本（5.6.12、5.7.8），因 +爲那會使結果難以解釋，可能會讓你的測試變得無用。一旦你找到了引入迴歸的主要 版本，就可以放心地繼續報告了。但請記住：在不知道罪魁禍首的情況下，開發人員 是否能夠提供幫助取決於手頭的問題。有時他們可能會從報告中確認是什麼出現了問 題，並能修復它；有時他們可能無法提供幫助，除非你進行二分。 -當處理回歸問題時，請確保你所面臨的問題真的是由內核引起的，而不是由其他東西 +當處理迴歸問題時，請確保你所面臨的問題真的是由內核引起的，而不是由其他東西 引起的，如上文所述。 -在整個過程中，請記住：只有當舊內核和新內核的配置相似時，問題才算回歸。最好 -的方法是：把配置文件（``.config``）從舊的工作內核直接複製到你嘗試的每個新內 -核版本。之後運行 ``make oldnoconfig`` 來調整它以適應新版本的需要，而不啓用 -任何新的功能，因爲那些功能也可能導致回歸。 +在整個過程中，請記住：只有當舊內核和新內核的配置相似時，問題纔算迴歸。這可以 +通過 ``make olddefconfig`` 來實現，詳細解釋參見 +Documentation/admin-guide/reporting-regressions.rst ；它還提供了大量其他您 +可能希望瞭解的有關回歸的信息。 -撰寫並發送報告 +撰寫併發送報告 --------------- *通過詳細描述問題來開始編寫報告。記得包括以下條目：您爲復現而安裝的最新 內核版本、使用的Linux發行版以及關於如何復現該問題的說明。如果可能，將內 - 核構建配置（.config）和 ``dmesg`` 的輸出放在網上的某個地方，並連結到它。 + 核構建配置（.config）和 ``dmesg`` 的輸出放在網上的某個地方，並鏈接到它。 包含或上傳所有其他可能相關的信息，如Oops的輸出/截圖或來自 ``lspci`` 的輸出。一旦你寫完了這個主要部分，請在上方插入一個正常長度的段落快速概 述問題和影響。再在此之上添加一個簡單描述問題的句子，以得到人們的閱讀。 現在給出一個更短的描述性標題或主題。然後就可以像MAINTAINERS文件告訴你的 - 那樣發送或提交報告了，除非你在處理一個「高優先級問題」：它們需要按照下面 - 「高優先級問題的特殊處理」所述特別關照。* + 那樣發送或提交報告了，除非你在處理一個“高優先級問題”：它們需要按照下面 + “高優先級問題的特殊處理”所述特別關照。* -現在你已經準備好了一切，是時候寫你的報告了。上文前言中連結的三篇文檔對如何 +現在你已經準備好了一切，是時候寫你的報告了。上文前言中鏈接的三篇文檔對如何 寫報告做了部分解釋。這就是爲什麼本文將只提到一些基本的內容以及 Linux 內核特 有的東西。 @@ -855,7 +850,7 @@ Linux 首席開發者 Linus Torvalds 認爲 Linux 內核永遠不應惡化，這 每份報告都應提及的事項 ~~~~~~~~~~~~~~~~~~~~~~~~ -詳細描述你的問題是如何發生在你安裝的新純淨內核上的。試著包含你之前寫的和優 +詳細描述你的問題是如何發生在你安裝的新純淨內核上的。試着包含你之前寫的和優 化過的分步說明，概述你和其他人如何重現這個問題；在極少數無法重現的情況下， 儘量描述你做了什麼來觸發它。 @@ -864,19 +859,19 @@ Linux 首席開發者 Linus Torvalds 認爲 Linux 內核永遠不應惡化，這 * ``cat /proc/version`` 的輸出，其中包含 Linux 內核版本號和構建時的編譯器。 - * 機器正在運行的 Linux 發行版（ ``hostnamectl | grep 「Operating System「`` ） + * 機器正在運行的 Linux 發行版（ ``hostnamectl | grep “Operating System“`` ） - * CPU 和作業系統的架構（ ``uname -mi`` ） + * CPU 和操作系統的架構（ ``uname -mi`` ） - * 如果您正在處理回歸，並進行了二分，請提及導致回歸的變更的主題和提交ID。 + * 如果您正在處理迴歸，並進行了二分，請提及導致迴歸的變更的主題和提交ID。 -許多情況下，讓讀你報告的人多了解兩件事也是明智之舉： +許多情況下，讓讀你報告的人多瞭解兩件事也是明智之舉： - * 用於構建 Linux 內核的配置（「.config」文件） + * 用於構建 Linux 內核的配置（“.config”文件） - * 內核的信息，你從 ``dmesg`` 得到的信息寫到一個文件里。確保它以像「Linux + * 內核的信息，你從 ``dmesg`` 得到的信息寫到一個文件裏。確保它以像“Linux version 5.8-1 (foobar@example.com) (gcc (GCC) 10.2.1, GNU ld version - 2.34) #1 SMP Mon Aug 3 14:54:37 UTC 2020」這樣的行開始，如果沒有，那麼第 + 2.34) #1 SMP Mon Aug 3 14:54:37 UTC 2020”這樣的行開始，如果沒有，那麼第 一次啓動階段的重要信息已經被丟棄了。在這種情況下，可以考慮使用 ``journalctl -b 0 -k`` ；或者你也可以重啓，重現這個問題，然後調用 ``dmesg`` 。 @@ -887,39 +882,39 @@ Linux 首席開發者 Linus Torvalds 認爲 Linux 內核永遠不應惡化，這 * 將文件上傳到某個公開的地方（你的網站，公共文件粘貼服務，在 `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ 上創建的工單……）， - 並在你的報告中放上連結。理想情況下請使用允許這些文件保存很多年的地方，因 + 並在你的報告中放上鍊接。理想情況下請使用允許這些文件保存很多年的地方，因 爲它們可能在很多年後對別人有用；例如 5 年或 10 年後，一個開發者正在修改 一些代碼，而這些代碼正是爲了修復你的問題。 - * 把文件放在一邊，然後說明你會在他人回復時再單獨發送。只要記得報告發出去後， + * 把文件放在一邊，然後說明你會在他人回覆時再單獨發送。只要記得報告發出去後， 真正做到這一點就可以了。;-) 提供這些東西可能是明智的 ~~~~~~~~~~~~~~~~~~~~~~~~~~ -根據問題的不同，你可能需要提供更多的背景數據。這裡有一些關於提供什麼比較好 +根據問題的不同，你可能需要提供更多的背景數據。這裏有一些關於提供什麼比較好 的建議： - * 如果你處理的是內核的「warning」、「OOPS」或「panic」，請包含它。如果你不能複製 - 粘貼它，試著用netconsole網絡終端遠程跟蹤或者至少拍一張屏幕的照片。 + * 如果你處理的是內核的“warning”、“OOPS”或“panic”，請包含它。如果你不能複製 + 粘貼它，試着用netconsole網絡終端遠程跟蹤或者至少拍一張屏幕的照片。 - * 如果問題可能與你的電腦硬體有關，請說明你使用的是什麼系統。例如，如果你的 - 顯卡有問題，請提及它的製造商，顯卡的型號，以及使用的晶片。如果是筆記本電 - 腦，請提及它的型號名稱，但儘量確保意義明確。例如「戴爾 XPS 13」就不很明確， + * 如果問題可能與你的電腦硬件有關，請說明你使用的是什麼系統。例如，如果你的 + 顯卡有問題，請提及它的製造商，顯卡的型號，以及使用的芯片。如果是筆記本電 + 腦，請提及它的型號名稱，但儘量確保意義明確。例如“戴爾 XPS 13”就不很明確， 因爲它可能是 2012 年的那款，那款除了看起來和現在銷售的沒有什麼不同之外， 兩者沒有任何共同之處。因此，在這種情況下，要加上準確的型號，例如 2019 - 年內推出的 XPS 13 型號爲「9380」或「7390」。像「聯想 Thinkpad T590」這樣的名字 + 年內推出的 XPS 13 型號爲“9380”或“7390”。像“聯想 Thinkpad T590”這樣的名字 也有些含糊不清：這款筆記本有帶獨立顯卡和不帶的子型號，所以要儘量找到準確 的型號名稱或註明主要部件。 - * 說明正在使用的相關軟體。如果你在加載模塊時遇到了問題，你要說明正在使用的 + * 說明正在使用的相關軟件。如果你在加載模塊時遇到了問題，你要說明正在使用的 kmod、systemd 和 udev 的版本。如果其中一個 DRM 驅動出現問題，你要說明 libdrm 和 Mesa 的版本；還要說明你的 Wayland 合成器或 X-Server 及其驅動。 如果你有文件系統問題，請註明相應的文件系統實用程序的版本（e2fsprogs, btrfs-progs, xfsprogs……）。 * 從內核中收集可能有用的額外信息。例如， ``lspci -nn`` 的輸出可以幫助別人 - 識別你使用的硬體。如果你的硬體有問題，你甚至可以給出 ``sudo lspci -vvv`` + 識別你使用的硬件。如果你的硬件有問題，你甚至可以給出 ``sudo lspci -vvv`` 的結果，因爲它提供了組件是如何配置的信息。對於一些問題，可能最好包含 ``/proc/cpuinfo`` ， ``/proc/ioports`` ， ``/proc/iomem`` ， ``/proc/modules`` 或 ``/proc/scsi/scsi`` 等文件的內容。一些子系統還提 @@ -936,7 +931,7 @@ Linux 首席開發者 Linus Torvalds 認爲 Linux 內核永遠不應惡化，這 ~~~~~~~~~~~~~~~~~~~~~~ 現在你已經準備好了報告的詳細部分，讓我們進入最重要的部分：開頭幾句。現在到 -報告的最前面，在你剛才寫的部分之前加上類似「The detailed description:」（詳細 +報告的最前面，在你剛纔寫的部分之前加上類似“The detailed description:”（詳細 描述）這樣的內容，並在最前面插入兩個新行。現在寫一個正常長度的段落，大致概 述這個問題。去掉所有枯燥的細節，把重點放在讀者需要知道的關鍵部分，以讓人了 解這是怎麼回事；如果你認爲這個缺陷影響了很多用戶，就提一下這點來吸引大家關 @@ -946,10 +941,10 @@ Linux 首席開發者 Linus Torvalds 認爲 Linux 內核永遠不應惡化，這 要更加抽象，爲報告寫一個更短的主題/標題。 現在你已經寫好了這部分，請花點時間來優化它，因爲它是你的報告中最重要的部分： -很多人會先讀這部分，然後才會決定是否值得花時間閱讀其他部分。 +很多人會先讀這部分，然後纔會決定是否值得花時間閱讀其他部分。 現在就像 :ref:`MAINTAINERS <maintainers>` 維護者文件告訴你的那樣發送或提交 -報告，除非它是前面概述的那些「高優先級問題」之一：在這種情況下，請先閱讀下一 +報告，除非它是前面概述的那些“高優先級問題”之一：在這種情況下，請先閱讀下一 小節，然後再發送報告。 高優先級問題的特殊處理 @@ -960,11 +955,19 @@ Linux 首席開發者 Linus Torvalds 認爲 Linux 內核永遠不應惡化，這 **非常嚴重的缺陷** ：確保在主題或工單標題以及第一段中明顯標出 severeness （非常嚴重的）。 -**回歸** ：如果問題是一個回歸，請在郵件的主題或缺陷跟蹤器的標題中添加 -[REGRESSION]。如果您沒有進行二分，請至少註明您測試的最新主線版本（比如 5.7） -和出現問題的最新版本（比如 5.8）。如果您成功地進行了二分，請註明導致回歸 -的提交ID和主題。也請添加該變更的作者到你的報告中；如果您需要將您的缺陷提交 -到缺陷跟蹤器中，請將報告以私人郵件的形式轉發給他，並註明報告提交地點。 +**迴歸** ：報告的主題應以“[REGRESSION]”開頭。 + +如果您成功用二分法定位了問題，請使用引入迴歸之更改的標題作爲主題的第二部分。 +請在報告中寫明“罪魁禍首”的提交ID。如果未能成功二分，請在報告中講明最後一個 +正常工作的版本（例如5.7）和最先發生問題的版本（例如5.8-rc1）。 + +通過郵件發送報告時，請抄送Linux迴歸郵件列表（regressions@lists.linux.dev）。 +如果報告需要提交到某個web追蹤器，請繼續提交；並在提交後，通過郵件將報告轉發 +至迴歸列表；抄送相關子系統的維護人員和郵件列表。請確保報告是內聯轉發的，不要 +把它作爲附件。另外請在頂部添加一個簡短的說明，在那裏寫上工單的網址。 + +在郵寄或轉發報告時，如果成功二分，需要將“罪魁禍首”的作者添加到收件人中；同時 +抄送signed-off-by鏈中的每個人，您可以在提交消息的末尾找到。 **安全問題** ：對於這種問題，你將必須評估：如果細節被公開披露，是否會對其他 用戶產生短期風險。如果不會，只需按照所述繼續報告問題。如果有此風險，你需要 @@ -972,47 +975,47 @@ Linux 首席開發者 Linus Torvalds 認爲 Linux 內核永遠不應惡化，這 * 如果 MAINTAINERS 文件指示您通過郵件報告問題，請不要抄送任何公共郵件列表。 - * 如果你應該在缺陷跟蹤器中提交問題，請確保將工單標記爲「私有」或「安全問題」。 + * 如果你應該在缺陷跟蹤器中提交問題，請確保將工單標記爲“私有”或“安全問題”。 如果缺陷跟蹤器沒有提供保持報告私密性的方法，那就別想了，把你的報告以私人 郵件的形式發送給維護者吧。 -在這兩種情況下，都一定要將報告發到 MAINTAINERS 文件中「安全聯絡」部分列出的 +在這兩種情況下，都一定要將報告發到 MAINTAINERS 文件中“安全聯絡”部分列出的 地址。理想的情況是在發送報告的時候直接抄送他們。如果您在缺陷跟蹤器中提交了 -報告，請將報告的文本轉發到這些地址；但請在報告的頂部加上注釋，表明您提交了 -報告，並附上工單連結。 +報告，請將報告的文本轉發到這些地址；但請在報告的頂部加上註釋，表明您提交了 +報告，並附上工單鏈接。 -更多信息請參見「Documentation/translations/zh_TW/admin-guide/security-bugs.rst」。 +更多信息請參見 Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。 -發布報告後的責任 +發佈報告後的責任 ------------------ *等待別人的反應，繼續推進事情，直到你能夠接受這樣或那樣的結果。因此，請 公開和及時地回應任何詢問。測試提出的修復。積極地測試：至少重新測試每個 新主線版本的首個候選版本（RC），並報告你的結果。如果出現拖延，就友好地 - 提醒一下。如果你沒有得到任何幫助或者未能滿意，請試著自己幫助自己。* + 提醒一下。如果你沒有得到任何幫助或者未能滿意，請試着自己幫助自己。* 如果你的報告非常優秀，而且你真的很幸運，那麼某個開發者可能會立即發現導致問 題的原因；然後他們可能會寫一個補丁來修復、測試它，並直接發送給主線集成，同 -時標記它以便以後回溯到需要它的穩定版和長期支持內核。那麼你需要做的就是回復 -一句「Thank you very much」（非常感謝），然後在發布後換上修復好的版本。 +時標記它以便以後回溯到需要它的穩定版和長期支持內核。那麼你需要做的就是回覆 +一句“Thank you very much”（非常感謝），然後在發佈後換上修復好的版本。 -但這種理想狀況很少發生。這就是爲什麼你把報告拿出來之後工作才開始。你要做的 -事情要視情況而定，但通常會是下面列出的事情。但在深入研究細節之前，這裡有幾 +但這種理想狀況很少發生。這就是爲什麼你把報告拿出來之後工作纔開始。你要做的 +事情要視情況而定，但通常會是下面列出的事情。但在深入研究細節之前，這裏有幾 件重要的事情，你需要記住這部分的過程。 關於進一步互動的一般建議 ~~~~~~~~~~~~~~~~~~~~~~~~~~ -**總是公開回復** ：當你在缺陷跟蹤器中提交問題時，一定要在那裡回復，不要私下 -聯繫任何開發者。對於郵件報告，在回復您收到的任何郵件時，總是使用「全部回復」 +**總是公開回復** ：當你在缺陷跟蹤器中提交問題時，一定要在那裏回覆，不要私下 +聯繫任何開發者。對於郵件報告，在回覆您收到的任何郵件時，總是使用“全部回覆” 功能。這包括帶有任何你可能想要添加到你的報告中的額外數據的郵件：進入郵件應 -用程序「已發送」文件夾，並在郵件上使用「全部回復」來回復報告。這種方法可以確保 -公共郵件列表和其他所有參與者都能及時了解情況；它還能保持郵件線程的完整性， +用程序“已發送”文件夾，並在郵件上使用“全部回覆”來回復報告。這種方法可以確保 +公共郵件列表和其他所有參與者都能及時瞭解情況；它還能保持郵件線程的完整性， 這對於郵件列表將所有相關郵件歸爲一類是非常重要的。 -只有兩種情況不適合在缺陷跟蹤器或「全部回復」中發表評論： +只有兩種情況不適合在缺陷跟蹤器或“全部回覆”中發表評論： * 有人讓你私下發東西。 @@ -1022,32 +1025,32 @@ Linux 首席開發者 Linus Torvalds 認爲 Linux 內核永遠不應惡化，這 **在請求解釋或幫助之前先研究一下** ：在這部分過程中，有人可能會告訴你用尚未 掌握的技能做一些事情。例如你可能會被要求使用一些你從未聽說過的測試工具；或 -者你可能會被要求在 Linux 內核原始碼上應用一個補丁來測試它是否有幫助。在某些 -情況下，發個回復詢問如何做就可以了。但在走這條路之前，儘量通過在網際網路上搜 +者你可能會被要求在 Linux 內核源代碼上應用一個補丁來測試它是否有幫助。在某些 +情況下，發個回覆詢問如何做就可以了。但在走這條路之前，儘量通過在互聯網上搜 索自行找到答案；或者考慮在其他地方詢問建議。比如詢問朋友，或者到你平時常去 的聊天室或論壇發帖諮詢。 **要有耐心** ：如果你真的很幸運，你可能會在幾個小時內收到對你的報告的答覆。 但大多數情況下會花費更多的時間，因爲維護者分散在全球各地，因此可能在不同的 -時區——在那裡他們已經享受著遠離鍵盤的夜晚。 +時區——在那裏他們已經享受着遠離鍵盤的夜晚。 一般來說，內核開發者需要一到五個工作日來回復報告。有時會花費更長的時間，因 爲他們可能正忙於合併窗口、其他工作、參加開發者會議，或者只是在享受一個漫長 的暑假。 -「高優先級的問題」（見上面的解釋）例外：維護者應該儘快解決這些問題；這就是爲 +“高優先級的問題”（見上面的解釋）例外：維護者應該儘快解決這些問題；這就是爲 什麼你應該最多等待一個星期（如果是緊急的事情，則只需兩天），然後再發送友好 的提醒。 -有時維護者可能沒有及時回復；有時候可能會出現分歧，例如一個問題是否符合回歸 +有時維護者可能沒有及時回覆；有時候可能會出現分歧，例如一個問題是否符合迴歸 的條件。在這種情況下，在郵件列表上提出你的顧慮，並請求其他人公開或私下回復 如何繼續推進。如果失敗了，可能應該讓更高級別的維護者介入。如果是 WiFi 驅動， 那就是無線維護者；如果沒有更高級別的維護者，或者其他一切努力都失敗了，那 這可能是一種罕見的、可以讓 Linus Torvalds 參與進來的情況。 -**主動測試** ：每當一個新的主線內核版本的第一個預發布版本（rc1）發布的時候， +**主動測試** ：每當一個新的主線內核版本的第一個預發佈版本（rc1）發佈的時候， 去檢查一下這個問題是否得到了解決，或者是否有什麼重要的變化。在工單中或在 -回復報告的郵件中提及結果（確保所有參與討論的人都被抄送）。這將表明你的承諾 +回覆報告的郵件中提及結果（確保所有參與討論的人都被抄送）。這將表明你的承諾 和你願意幫忙。如果問題持續存在，它也會提醒開發者確保他們不會忘記它。其他一 些不定期的重新測試（例如用rc3、rc5 和最終版本）也是一個好主意，但只有在相關 的東西發生變化或者你正在寫什麼東西的時候才報告你的結果。 @@ -1057,10 +1060,10 @@ Linux 首席開發者 Linus Torvalds 認爲 Linux 內核永遠不應惡化，這 查詢和測試請求 ~~~~~~~~~~~~~~~ -如果你的報告得到了回復則需履行以下責任： +如果你的報告得到了回覆則需履行以下責任： **檢查與你打交道的人** ：大多數情況下，會是維護者或特定代碼區域的開發人員對 -你的報告做出回應。但由於問題通常是公開報告的，所以回復的可能是任何人——包括 +你的報告做出回應。但由於問題通常是公開報告的，所以回覆的可能是任何人——包括 那些想要幫忙的人，但最後可能會用他們的問題或請求引導你完全偏離軌道。這很少 發生，但這是快速上網搜搜看你正在與誰互動是明智之舉的許多原因之一。通過這樣 做，你也可以知道你的報告是否被正確的人聽到，因爲如果討論沒有導致滿意的問題 @@ -1086,63 +1089,63 @@ Linux 首席開發者 Linus Torvalds 認爲 Linux 內核永遠不應惡化，這 報告到達時，維護者剛剛離開鍵盤一段時間，或者有更重要的事情要處理。在寫提醒 信的時候，要善意地問一下，是否還需要你這邊提供什麼來讓事情推進下去。如果報 告是通過郵件發出來的，那就在郵件的第一行回覆你的初始郵件（見上文），其中包 -括下方的原始報告的完整引用：這是少數幾種情況下，這樣的「TOFU」（Text Over, +括下方的原始報告的完整引用：這是少數幾種情況下，這樣的“TOFU”（Text Over, Fullquote Under文字在上，完整引用在下）是正確的做法，因爲這樣所有的收件人都 會以適當的順序立即讓細節到手頭上來。 -在提醒之後，再等三周的回覆。如果你仍然沒有得到適當的反饋，你首先應該重新考 +在提醒之後，再等三週的回覆。如果你仍然沒有得到適當的反饋，你首先應該重新考 慮你的方法。你是否可能嘗試接觸了錯誤的人？是不是報告也許令人反感或者太混亂， 以至於人們決定完全遠離它？排除這些因素的最好方法是：把報告給一兩個熟悉 FLOSS 問題報告的人看，詢問他們的意見。同時徵求他們關於如何繼續推進的建議。 -這可能意味著：準備一份更好的報告，讓這些人在你發出去之前對它進行審查。這樣 +這可能意味着：準備一份更好的報告，讓這些人在你發出去之前對它進行審查。這樣 的方法完全可以；只需說明這是關於這個問題的第二份改進的報告，並附上第一份報 -告的連結。 +告的鏈接。 如果報告是恰當的，你可以發送第二封提醒信；在其中詢問爲什麼報告沒有得到任何 -回復。第二封提醒郵件的好時機是在新 Linux 內核版本的首個預發布版本（'rc1'） -發布後不久，因爲無論如何你都應該在那個時候重新測試並提供狀態更新（見上文）。 +回覆。第二封提醒郵件的好時機是在新 Linux 內核版本的首個預發佈版本（'rc1'） +發佈後不久，因爲無論如何你都應該在那個時候重新測試並提供狀態更新（見上文）。 -如果第二次提醒的結果又在一周內沒有任何反應，可以嘗試聯繫上級維護者詢問意見： +如果第二次提醒的結果又在一週內沒有任何反應，可以嘗試聯繫上級維護者詢問意見： 即使再忙的維護者在這時候也至少應該發過某種確認。 記住要做好失望的準備：理想狀況下維護者最好對每一個問題報告做出回應，但他們 -只有義務解決之前列出的「高優先級問題」。所以，如果你得到的回覆是「謝謝你的報告， -我目前有更重要的問題要處理，在可預見的未來沒有時間去研究這個問題」，那請不 +只有義務解決之前列出的“高優先級問題”。所以，如果你得到的回覆是“謝謝你的報告， +我目前有更重要的問題要處理，在可預見的未來沒有時間去研究這個問題”，那請不 要太沮喪。 也有可能在缺陷跟蹤器或列表中進行了一些討論之後，什麼都沒有發生，提醒也無助 於激勵大家進行修復。這種情況可能是毀滅性的，但在 Linux 內核開發中確實會發生。 -這些和其他得不到幫助的原因在本文結尾處的「爲什麼有些問題在被報告後沒有得到 -任何回應或者仍然沒有修復」中進行了解釋。 +這些和其他得不到幫助的原因在本文結尾處的“爲什麼有些問題在被報告後沒有得到 +任何回應或者仍然沒有修復”中進行了解釋。 如果你沒有得到任何幫助或問題最終沒有得到解決，不要沮喪：Linux 內核是 FLOSS， -因此你仍然可以自己幫助自己。例如，你可以試著找到其他受影響的人，和他們一 +因此你仍然可以自己幫助自己。例如，你可以試着找到其他受影響的人，和他們一 起合作來解決這個問題。這樣的團隊可以一起準備一份新的報告，提到團隊有多少人， 爲什麼你們認爲這是應該得到解決的事情。也許你們還可以一起縮小確切原因或引 -入回歸的變化，這往往會使修復更容易。而且如果運氣好的話，團隊中可能會有懂點 -編程的人，也許能寫出一個修複方案。 +入迴歸的變化，這往往會使修復更容易。而且如果運氣好的話，團隊中可能會有懂點 +編程的人，也許能寫出一個修復方案。 -「報告穩定版和長期支持內核線的回歸」的參考 +“報告穩定版和長期支持內核線的迴歸”的參考 ------------------------------------------ -本小節提供了在穩定版和長期支持內核線中面對回歸時需要執行的步驟的詳細信息。 +本小節提供了在穩定版和長期支持內核線中面對迴歸時需要執行的步驟的詳細信息。 確保特定版本線仍然受支持 ~~~~~~~~~~~~~~~~~~~~~~~~~ *檢查內核開發人員是否仍然維護你關心的Linux內核版本線：去 kernel.org 的 - 首頁，確保此特定版本線的最新版沒有「[EOL]」標記。* + 首頁，確保此特定版本線的最新版沒有“[EOL]”標記。* 大多數內核版本線只支持三個月左右，因爲延長維護時間會帶來相當多的工作。因此， 每年只會選擇一個版本來支持至少兩年（通常是六年）。這就是爲什麼你需要檢查 內核開發者是否還支持你關心的版本線。 -注意，如果 `kernel.org <https://kernel.org/>`_ 在首頁上列出了兩個「穩定」版本， +注意，如果 `kernel.org <https://kernel.org/>`_ 在首頁上列出了兩個“穩定”版本， 你應該考慮切換到較新的版本，而忘掉較舊的版本：對它的支持可能很快就會結束。 -然後，它將被標記爲「生命周期結束」（EOL）。達到這個程度的版本線仍然會在 -`kernel.org <https://kernel.org/>`_ 首頁上被顯示一兩周，但不適合用於測試和 +然後，它將被標記爲“生命週期結束”（EOL）。達到這個程度的版本線仍然會在 +`kernel.org <https://kernel.org/>`_ 首頁上被顯示一兩週，但不適合用於測試和 報告。 搜索穩定版郵件列表 @@ -1158,57 +1161,63 @@ FLOSS 問題報告的人看，詢問他們的意見。同時徵求他們關於 用最新版本復現問題 ~~~~~~~~~~~~~~~~~~~ - *從特定的版本線安裝最新版本作爲純淨內核。確保這個內核沒有被汙染，並且仍 - 然存在問題，因爲問題可能已經在那裡被修復了。* + *從特定的版本線安裝最新版本作爲純淨內核。確保這個內核沒有被污染，並且仍 + 然存在問題，因爲問題可能已經在那裏被修復了。* 在投入更多時間到這個過程中之前，你要檢查這個問題是否在你關注的版本線的最新 -版本中已經得到了修復。這個內核需要是純淨的，在問題發生之前不應該被汙染，正 +版本中已經得到了修復。這個內核需要是純淨的，在問題發生之前不應該被污染，正 如上面已經在測試主線的過程中詳細介紹過的一樣。 -您是否是第一次注意到供應商內核的回歸？供應商的更改可能會發生變化。你需要重新 +您是否是第一次注意到供應商內核的迴歸？供應商的更改可能會發生變化。你需要重新 檢查排除來這個問題。當您從5.10.4-vendor.42更新到5.10.5-vendor.43時，記錄損壞 的信息。然後在測試了前一段中所述的最新5.10版本之後，檢查Linux 5.10.4的普通版本 -是否也可以正常工作。如果問題在那裡出現，那就不符合上游回歸的條件，您需要切換 +是否也可以正常工作。如果問題在那裏出現，那就不符合上游迴歸的條件，您需要切換 回主逐步指南來報告問題。 -報告回歸 +報告迴歸 ~~~~~~~~~~ - *向Linux穩定版郵件列表發送一個簡短的問題報告(stable@vger.kernel.org)。 - 大致描述問題，並解釋如何復現。講清楚首個出現問題的版本和最後一個工作正常 - 的版本。然後等待進一步的指示。* + *向Linux穩定版郵件列表發送一個簡短的問題報告(stable@vger.kernel.org)並 + 抄送Linux迴歸郵件列表（regressions@lists.linux.dev）；如果你懷疑是由某 + 子系統引起的，請抄送其維護人員和子系統郵件列表。大致描述問題，並解釋如 + 何復現。講清楚首個出現問題的版本和最後一個工作正常的版本。然後等待進一 + 步的指示。* -當報告在穩定版或長期支持內核線內發生的回歸（例如在從5.10.4更新到5.10.5時）， -一份簡短的報告足以快速報告問題。因此只需要粗略的描述。 +當報告在穩定版或長期支持內核線內發生的迴歸（例如在從5.10.4更新到5.10.5時）， +一份簡短的報告足以快速報告問題。因此只需向穩定版和迴歸郵件列表發送粗略的描述； +不過如果你懷疑某子系統導致此問題的話，請一併抄送其維護人員和子系統郵件列表， +這會加快進程。 -但是請注意，如果您能夠指明引入問題的確切版本，這將對開發人員有很大幫助。因此 -如果有時間的話，請嘗試使用普通內核找到該版本。讓我們假設發行版發布Linux內核 +請注意，如果您能夠指明引入問題的確切版本，這將對開發人員有很大幫助。因此 +如果有時間的話，請嘗試使用普通內核找到該版本。讓我們假設發行版發佈Linux內核 5.10.5到5.10.8的更新時發生了故障。那麼按照上面的指示，去檢查該版本線中的最新 內核，比如5.10.9。如果問題出現，請嘗試普通5.10.5，以確保供應商應用的補丁不會 干擾。如果問題沒有出現，那麼嘗試5.10.7，然後直到5.10.8或5.10.6（取決於結果） 找到第一個引入問題的版本。在報告中寫明這一點，並指出5.10.9仍然存在故障。 -前一段基本粗略地概述了「二分」方法。一旦報告出來，您可能會被要求做一個正確的 +前一段基本粗略地概述了“二分”方法。一旦報告出來，您可能會被要求做一個正確的 報告，因爲它允許精確地定位導致問題的確切更改（然後很容易被恢復以快速修復問題）。 -因此如果時間允許，考慮立即進行適當的二分。有關如何詳細信息，請參閱「對回歸的 -特別關照」部分和文檔「Documentation/translations/zh_TW/admin-guide/bug-bisect.rst」。 +因此如果時間允許，考慮立即進行適當的二分。有關如何詳細信息，請參閱“對迴歸的 +特別關照”部分和文檔 Documentation/translations/zh_CN/admin-guide/bug-bisect.rst 。 +如果成功二分的話，請將“罪魁禍首”的作者添加到收件人中；同時抄送所有在 +signed-off-by鏈中的人，您可以在提交消息的末尾找到。 -「報告僅在舊內核版本線中發生的問題」的參考 ------------------------------------------- +“報告僅在舊內核版本線中發生的問題”的參考 +---------------------------------------- -本節詳細介紹了如果無法用主線內核重現問題，但希望在舊版本線（又稱穩定版內核和 +本節詳細介紹瞭如果無法用主線內核重現問題，但希望在舊版本線（又稱穩定版內核和 長期支持內核）中修復問題時需要採取的步驟。 有些修復太複雜 ~~~~~~~~~~~~~~~ *請做好準備，接下來的幾個步驟可能無法在舊版本中解決問題：修復可能太大或 - 太冒險，無法移植到那裡。* + 太冒險，無法移植到那裏。* 即使是微小的、看似明顯的代碼變化，有時也會帶來新的、完全意想不到的問題。穩 定版和長期支持內核的維護者非常清楚這一點，因此他們只對這些內核進行符合 -「Documentation/translations/zh_TW/process/stable-kernel-rules.rst」中所列出的 +Documentation/translations/zh_CN/process/stable-kernel-rules.rst 中所列出的 規則的修改。 複雜或有風險的修改不符合條件，因此只能應用於主線。其他的修復很容易被回溯到 @@ -1220,7 +1229,7 @@ FLOSS 問題報告的人看，詢問他們的意見。同時徵求他們關於 通用準備 ~~~~~~~~~~ - *執行上面「報告僅在舊內核版本線中發生的問題」一節中的前三個步驟。* + *執行上面“報告僅在舊內核版本線中發生的問題”一節中的前三個步驟。* 您需要執行本指南另一節中已經描述的幾個步驟。這些步驟將讓您： @@ -1242,21 +1251,21 @@ FLOSS 問題報告的人看，詢問他們的意見。同時徵求他們關於 在許多情況下，你所處理的問題會發生在主線上，但已在主線上得到了解決。修正它 的提交也需要被回溯才能解決這個問題。這就是爲什麼你要搜索它或任何相關討論。 - * 首先嘗試在存放 Linux 內核原始碼的 Git 倉庫中找到修復。你可以通過 + * 首先嚐試在存放 Linux 內核源代碼的 Git 倉庫中找到修復。你可以通過 `kernel.org 上的網頁 <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_ 或 `GitHub 上的鏡像 <https://github.com/torvalds/linux>`_ 來實現；如果你 有一個本地克隆，你也可以在命令行用 ``git log --grep=<pattern>`` 來搜索。 - 如果你找到了修復，請查看提交消息的尾部是否包含了類似這樣的「穩定版標籤」： + 如果你找到了修復，請查看提交消息的尾部是否包含了類似這樣的“穩定版標籤”： Cc: <stable@vger.kernel.org> # 5.4+ 像上面這行，開發者標記了安全修復可以回傳到 5.4 及以後的版本。大多數情況 - 下，它會在兩周內被應用到那裡，但有時需要更長的時間。 + 下，它會在兩週內被應用到那裏，但有時需要更長的時間。 * 如果提交沒有告訴你任何東西，或者你找不到修復，請再找找關於這個問題的討論。 - 用你最喜歡的搜尋引擎搜索網絡，以及 `Linux kernel developers mailing + 用你最喜歡的搜索引擎搜索網絡，以及 `Linux kernel developers mailing list 內核開發者郵件列表 <https://lore.kernel.org/lkml/>`_ 的檔案。也可以 閱讀上面的 `定位導致問題的內核區域` 一節，然後按照說明找到導致問題的子系 統：它的缺陷跟蹤器或郵件列表存檔中可能有你要找的答案。 @@ -1286,41 +1295,41 @@ FLOSS 問題報告的人看，詢問他們的意見。同時徵求他們關於 爲什麼有些問題在報告後沒有任何回應或仍未解決？ =============================================== -當向 Linux 開發者報告問題時，要注意只有「高優先級的問題」（回歸、安全問題、嚴 +當向 Linux 開發者報告問題時，要注意只有“高優先級的問題”（迴歸、安全問題、嚴 重問題）才一定會得到解決。如果維護者或其他人都失敗了，Linus Torvalds 他自己 會確保這一點。他們和其他內核開發者也會解決很多其他問題。但是要知道，有時他 們也會不能或不願幫忙；有時甚至沒有人發報告給他們。 最好的解釋就是那些內核開發者常常是在業餘時間爲 Linux 內核做出貢獻。內核中的 -不少驅動程序都是由這樣的程式設計師編寫的，往往只是因爲他們想讓自己的硬體可以在 -自己喜歡的作業系統上使用。 +不少驅動程序都是由這樣的程序員編寫的，往往只是因爲他們想讓自己的硬件可以在 +自己喜歡的操作系統上使用。 -這些程式設計師大多數時候會很樂意修復別人報告的問題。但是沒有人可以強迫他們這樣 +這些程序員大多數時候會很樂意修復別人報告的問題。但是沒有人可以強迫他們這樣 做，因爲他們是自願貢獻的。 還有一些情況下，這些開發者真的很想解決一個問題，但卻不能解決：有時他們缺乏 -硬體編程文檔來解決問題。這種情況往往由於公開的文檔太簡陋，或者驅動程序是通 +硬件編程文檔來解決問題。這種情況往往由於公開的文檔太簡陋，或者驅動程序是通 過逆向工程編寫的。 -業餘開發者遲早也會不再關心某驅動。也許他們的測試硬體壞了，被更高級的玩意取 -代了，或者是太老了以至於只能在計算機博物館裡找到。有時開發者根本就不關心他 +業餘開發者遲早也會不再關心某驅動。也許他們的測試硬件壞了，被更高級的玩意取 +代了，或者是太老了以至於只能在計算機博物館裏找到。有時開發者根本就不關心他 們的代碼和 Linux 了，因爲在他們的生活中一些不同的東西變得更重要了。在某些情 況下，沒有人願意接手維護者的工作——也沒有人可以被強迫，因爲對 Linux 內核的貢 獻是自願的。然而被遺棄的驅動程序仍然存在於內核中：它們對人們仍然有用，刪除 -它們可能導致回歸。 +它們可能導致迴歸。 對於那些爲 Linux 內核工作而獲得報酬的開發者來說，情況並沒有什麼不同。這些人 現在貢獻了大部分的變更。但是他們的僱主遲早也會停止關注他們的代碼或者讓程序 -員專注於其他事情。例如，硬體廠商主要通過銷售新硬體來賺錢；因此，他們中的不 +員專注於其他事情。例如，硬件廠商主要通過銷售新硬件來賺錢；因此，他們中的不 少人並沒有投入太多時間和精力來維護他們多年前就停止銷售的東西的 Linux 內核驅 動。企業級 Linux 發行商往往持續維護的時間比較長，但在新版本中往往會把對老舊 -和稀有硬體的支持放在一邊，以限制範圍。一旦公司拋棄了一些代碼，往往由業餘貢 +和稀有硬件的支持放在一邊，以限制範圍。一旦公司拋棄了一些代碼，往往由業餘貢 獻者接手，但正如上面提到的：他們遲早也會放下代碼。 優先級是一些問題沒有被修復的另一個原因，因爲維護者相當多的時候是被迫設置這 些優先級的，因爲在 Linux 上工作的時間是有限的。對於業餘時間或者僱主給予他們 的開發人員用於上游內核維護工作的時間也是如此。有時維護人員也會被報告淹沒， -即使一個驅動程序幾乎完美地工作。爲了不被完全纏住，程式設計師可能別無選擇，只能 +即使一個驅動程序幾乎完美地工作。爲了不被完全纏住，程序員可能別無選擇，只能 對問題報告進行優先級排序而拒絕其中的一些報告。 不過這些都不用太過擔心，很多驅動都有積極的維護者，他們對儘可能多的解決問題 @@ -1330,8 +1339,32 @@ FLOSS 問題報告的人看，詢問他們的意見。同時徵求他們關於 結束語 ======= -與其他免費/自由&開源軟體（Free/Libre & Open Source Software，FLOSS）相比， -向 Linux 內核開發者報告問題是很難的：這個文檔的長度和複雜性以及字裡行間的內 +與其他免費/自由&開源軟件（Free/Libre & Open Source Software，FLOSS）相比， +向 Linux 內核開發者報告問題是很難的：這個文檔的長度和複雜性以及字裏行間的內 涵都說明了這一點。但目前就是這樣了。這篇文字的主要作者希望通過記錄現狀來爲 以後改善這種狀況打下一些基礎。 + +.. + end-of-content +.. + This English version of this document is maintained by Thorsten Leemhuis + <linux@leemhuis.info>. If you spot a typo or small mistake, feel free to + let him know directly and he'll fix it. For translation problems, please + contact with translators. You are free to do the same in a mostly informal + way if you want to contribute changes to the text, but for copyright + reasons please CC linux-doc@vger.kernel.org and "sign-off" your + contribution as Documentation/process/submitting-patches.rst outlines in + the section "Sign your work - the Developer's Certificate of Origin". +.. + This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top + of the file. If you want to distribute this text under CC-BY-4.0 only, + please use "The Linux kernel developers" for author attribution and link + this as source: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst +.. + Note: Only the content of this RST file as found in the Linux kernel sources + is available under CC-BY-4.0, as versions of this text that were processed + (for example by the kernel's build system) might contain content taken from + files which use a more restrictive license. + diff --git a/Documentation/translations/zh_TW/admin-guide/reporting-regressions.rst b/Documentation/translations/zh_TW/admin-guide/reporting-regressions.rst new file mode 100644 index 000000000000..d7dcb2a26564 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/reporting-regressions.rst @@ -0,0 +1,371 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) +.. 【重分發信息參見本文件結尾】 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/reporting-regressions.rst + +:譯者: + + 吳想成 Wu XiangCheng <bobwxc@email.cn> + + +============ +報告迴歸問題 +============ + +“*我們拒絕出現迴歸*”是Linux內核開發的首要規則；Linux的發起者和領軍開發者Linus +Torvalds立下了此規則並確保它被落實。 + +本文檔描述了這條規則對用戶的意義，以及Linux內核開發模型如何確保解決所有被報告 +的迴歸；關於內核開發者如何處理的方面參見 Documentation/process/handling-regressions.rst 。 + + +本文重點（亦即“太長不看”） +========================== + +#. 如果某程序在原先的Linux內核上運行良好，但在較新版本上效果更差、或者根本不 + 能用，那麼你就碰見迴歸問題了。注意，新內核需要使用類似配置編譯；更多相關細 + 節參見下方。 + +#. 按照 Documentation/translations/zh_CN/admin-guide/reporting-issues.rst 中 + 所說的報告你的問題，該文檔已經包含了所有關於迴歸的重要方面，爲了方便起見也 + 複製到了下面。兩個重點：在報告主題中使用“[REGRESSION]”開頭並抄送或轉發到 + `迴歸郵件列表 <https://lore.kernel.org/regressions/>`_ + （regressions@lists.linux.dev）。 + +#. 可選但是建議：在發送或轉發報告時，指明該回歸發生的起點，以便Linux內核迴歸 + 追蹤機器人“regzbot”可以追蹤此問題:: + + #regzbot introduced v5.13..v5.14-rc1 + + +與用戶相關的所有Linux內核迴歸細節 +================================= + + +基本重點 +-------- + + +什麼是“迴歸”以及什麼是“無迴歸規則”？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +如果某程序/實例在原先的Linux內核上運行良好，但在較新版本上效果更差、或者根本 +不能用，那麼你就碰見迴歸問題了。“無迴歸規則”不允許出現這種情況。如果偶然發 +生了，導致問題的開發者應當迅速修復問題。 + +也就是說，若Linux 5.13中的WiFi驅動程序運行良好，但是在5.14版本上卻不能用、速 +度明顯變慢或出現錯誤，那就出現了迴歸。如果某正常工作的應用程序突然在新內核上 +出現不穩定，這也是迴歸；這些問題可能是由於procfs、sysfs或Linux提供給用戶空間 +軟件的許多其他接口之一的變化。但請記住，前述例子中的5.14需要使用類似於5.13的 +配置構建。這可以用 ``make olddefconfig`` 實現，詳細解釋見下。 + +注意本節第一句話中的“實例”：即使開發者需要遵循“無迴歸”規則，但仍可自由地改 +變內核的任何方面，甚至是導出到用戶空間的API或ABI，只要別破壞現有的應用程序或 +用例。 + +還需注意，“無迴歸”規則只限制內核提供給用戶空間的接口。它不適用於內核內部接 +口，比如一些外部開發的驅動程序用來插入鉤子到內核的模塊API。 + +如何報告迴歸？ +~~~~~~~~~~~~~~ + +只需按照 Documentation/translations/zh_CN/admin-guide/reporting-issues.rst 中 +所說的報告你的問題，該文檔已經包含了要點。下面幾點概述了一下只在迴歸中重要的 +方面： + + * 在檢查可加入討論的現有報告時，別忘了搜索 `Linux迴歸郵件列表 + <https://lore.kernel.org/regressions/>`_ 和 `regzbot網頁界面 + <https://linux-regtracking.leemhuis.info/regzbot/>`_ 。 + + * 在報告主題的開頭加上“[REGRESSION]”。 + + * 在你的報告中明確最後一個正常工作的內核版本和首個出問題的版本。如若可能， + 用二分法嘗試找出導致迴歸的變更，更多細節見下。 + + * 記得把報告發到Linux迴歸郵件列表（regressions@lists.linux.dev）。 + + * 如果通過郵件報告迴歸，請抄送回歸列表。 + + * 如果你使用某些缺陷追蹤器報告迴歸，請通過郵件轉發已提交的報告到迴歸列表， + 並抄送維護者以及出問題的相關子系統的郵件列表。 + + 如果是穩定版或長期支持版系列（如v5.15.3…v5.15.5）的迴歸，請記得抄送 + `Linux穩定版郵件列表 <https://lore.kernel.org/stable/>`_ （stable@vger.kernel.org）。 + + 如果你成功地執行了二分，請抄送肇事提交的信息中所有簽了“Signed-off-by:”的人。 + +在抄送你的報告到列表時，也請記得通知前述的Linux內核迴歸追蹤機器人。只需在郵件 +中包含如下片段:: + + #regzbot introduced: v5.13..v5.14-rc1 + +Regzbot會就將你的郵件視爲在某個特定版本區間的迴歸報告。上例中即linux v5.13仍 +然正常，而Linux 5.14-rc1是首個您遇到問題的版本。如果你執行了二分以查找導致回 +歸的提交，請使用指定肇事提交的id代替:: + + #regzbot introduced: 1f2e3d4c5d + +添加這樣的“regzbot命令”對你是有好處的，它會確保報告不會被忽略。如果你省略了 +它，Linux內核的迴歸跟蹤者會把你的迴歸告訴regzbot，只要你發送了一個副本到迴歸 +郵件列表。但是迴歸跟蹤者只有一個人，有時不得不休息或甚至偶爾享受可以遠離電腦 +的時光（聽起來很瘋狂）。因此，依賴此人手動將回歸添加到 `已追蹤且尚未解決的 +Linux內核迴歸列表 <https://linux-regtracking.leemhuis.info/regzbot/>`_ 和 +regzbot發送的每週迴歸報告，可能會出現延遲。 這樣的延誤會導致Linus Torvalds +在決定“繼續開發還是發佈新版本？”時忽略嚴重的迴歸。 + +真的修復了所有的迴歸嗎？ +~~~~~~~~~~~~~~~~~~~~~~~~ + +幾乎所有都是，只要引起問題的變更（肇事提交）被可靠定位。也有些迴歸可以不用這 +樣，但通常是必須的。 + +誰需要找出迴歸的根本原因？ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +受影響代碼區域的開發者應該自行嘗試定位問題所在。但僅靠他們的努力往往是不可 +能做到的，很多問題只發生在開發者的無法接觸的其他特定外部環境中——例如特定的 +硬件平臺、固件、Linux發行版、系統的配置或應用程序。這就是爲什麼最終往往是報 +告者定位肇事提交；有時用戶甚至需要再運行額外測試以查明確切的根本原因。開發 +者應該提供建議和可能的幫助，以使普通用戶更容易完成該流程。 + +如何找到罪魁禍首？ +~~~~~~~~~~~~~~~~~~ + +如 Documentation/translations/zh_CN/admin-guide/reporting-issues.rst （簡要） +和 Documentation/translations/zh_CN/admin-guide/bug-bisect.rst （詳細）中所 +述，執行二分。聽起來工作量很大，但大部分情況下很快就能找到罪魁禍首。如果這很 +困難或可靠地重現問題很耗時，請考慮與其他受影響的用戶合作，一起縮小搜索範圍。 + +當出現迴歸時我可以向誰尋求建議？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +發送郵件到迴歸郵件列表（regressions@lists.linux.dev）同時抄送Linux內核的迴歸 +跟蹤者（regressions@leemhuis.info）;如果問題需要保密處理，可以省略列表。 + + +關於迴歸的更多細節 +------------------ + + +“無迴歸規則”的目標是什麼？ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +用戶應該放心升級內核版本，而不必擔心有程序可能崩潰。這符合內核開發者的利益， +可以使更新有吸引力：他們不希望用戶停留在停止維護或超過一年半的穩定/長期Linux +版本系列上。這也符合所有人的利益，因爲 `那些系列可能含有已知的缺陷、安全問題 +或其他後續版本已經修復的問題 +<http://www.kroah.com/log/blog/2018/08/24/what-stable-kernel-should-i-use/>`_ 。 +此外，內核開發者希望使用戶測試最新的預發行版或常規發行版變得簡單而有吸引力。 +這同樣符合所有人的利益，如果新版本出來後很快就有相關報告，會使追蹤和修復問題 +更容易。 + +實際中“無迴歸”規則真的可行嗎？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +這不是句玩笑話，請見Linux創建者和主要開發人員Linus Torvalds在郵件列表中的許 +多發言，其中一些在 Documentation/process/handling-regressions.rst 中被引用。 + +此規則的例外情況極爲罕見；之前當開發者認爲某個特定的情況有必要援引例外時， +基本都被證明錯了。 + +誰來確保“無迴歸”被落實？ +~~~~~~~~~~~~~~~~~~~~~~~~ + +照看和支撐樹的子系統維護者應該關心這一點——例如，Linus Torvalds之於主線， +Greg Kroah-Hartman等人之於各種穩定/長期系列。 + +他們都得到了別人的幫助，以確保迴歸報告不會被遺漏。其中之一是Thorsten +Leemhuis，他目前擔任Linux內核的“迴歸跟蹤者”；爲了做好這項工作，他使用了 +regzbot——Linux內核迴歸跟蹤機器人。所以這就是爲什麼要抄送或轉發你的報告到 +迴歸郵件列表來通知這些人，已經最好在你的郵件中包含“regzbot命令”來立即追蹤它。 + +迴歸通常多久能修復？ +~~~~~~~~~~~~~~~~~~~~ + +開發者應該儘快修復任何被報告的迴歸，以提供及時爲受影響的用戶提供解決方案，並 +防止更多用戶遇到問題；然而，開發人員需要花足夠的時間和注意力確保迴歸修復不會 +造成額外的損害。 + +因此，答案取決於各種因素，如迴歸的影響、存在時長或出現於哪個Linux版本系列。 +但最終，大多數的迴歸應該在兩週內修復。 + +當問題可以通過升級某些軟件解決時，是迴歸嗎？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +基本都是。如果開發人員告訴您其他情況，請諮詢上述迴歸跟蹤者。 + +當新內核變慢或能耗增加，是迴歸嗎？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +是的，但有一些差別。在微型基準測試中變慢5%不太可能被視爲迴歸，除非它也會對 +廣泛基準測試的結果產生超過1%的影響。如果有疑問，請尋求建議。 + +當更新Linux時外部內核模塊崩潰了，是迴歸嗎？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +不，因爲“無迴歸”規則僅限於Linux內核提供給用戶空間的接口和服務。因此，它不包括 +構建或運行外部開發的內核模塊，因爲它們在內核空間中運行與掛進內核使用的內部接 +口偶爾會變化。 + +如何處理安全修復引起的迴歸？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在極爲罕見的情況下，安全問題無法在不引起迴歸的情況下修復；這些修復都被放棄了， +因爲它們終究會引起問題。幸運的是這種兩難境地基本都可以避免，受影響區域的主要 +開發者以及Linus Torvalds本人通常都會努力在不引入迴歸的情況下解決安全問題。 + +如果你仍然面臨此種情況，請查看郵件列表檔案是否有人盡力避免過迴歸。如果沒有， +請報告它；如有疑問，請如上所述尋求建議。 + +當修復迴歸時不可避免會引入另一個，如何處理？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +很遺憾這種事確實會出現，但幸運的是並不經常出現；如果發生了，受影響代碼區的資 +深開發者應當調查該問題以找到避免迴歸的解決方法，至少避免它們的影響。如果你遇 +到這樣的情況，如上所述：檢查之前的討論是否有人已經盡了最大努力，如有疑問請尋 +求建議。 + +小提示：如果人們在每個開發週期中定期給出主線預發佈（即v5.15-rc1或-rc3）以供 +測試，則可以避免這種情況。爲了更好地解釋，可以設想一個在Linux v5.14和v5.15-rc1 +之間集成的更改，該更改導致了迴歸，但同時是應用於5.15-rc1的其他改進的強依賴。 +如果有人在5.15發佈之前就發現並報告了這個問題，那麼所有更改都可以直接撤銷，從 +而解決迴歸問題。而就在幾天或幾周後，此解決方案變成了不可能，因爲一些軟件可能 +已經開始依賴於後續更改之一：撤銷所有更改將導致上述用戶軟件出現迴歸，這是不可 +接受的。 + +若我所依賴的功能在數月前被移除了，是迴歸嗎？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +是的，但如前節所述，通常很難修復此類迴歸。因此需要逐案處理。這也是定期測試主 +線預發佈對所有人有好處的另一個原因。 + +如果我似乎是唯一受影響的人，是否仍適用“無迴歸”規則？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +適用，但僅限於實際使用：Linux開發人員希望能夠自由地取消那些只能在閣樓和博物 +館中找到的硬件的支持。 + +請注意，有時爲了取得進展，不得不出現迴歸——後者也是防止Linux停滯不前所必需 +的。因此如果迴歸所影響的用戶很少，那麼爲了他們和其他人更大的利益，還是讓事情 +過去吧。尤其是存在某種規避迴歸的簡單方法，例如更新一些軟件或者使用專門爲此目 +的創建的內核參數。 + +迴歸規則是否也適用於staging樹中的代碼？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +不，參見 `適用於所有staging代碼配置選項的幫助文本 +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/staging/Kconfig>`_ ， +其早已聲明:: + + 請注意：這些驅動正在積極開發中，可能無法正常工作，並可能包含會在不久的 + 將來發生變化的用戶接口。 + +雖然staging開發人員通常堅持“無迴歸”的原則，但有時爲了取得進展也會違背它。這就 +是爲什麼當staging樹的WiFi驅動被基本推倒重來時，有些用戶不得不處理迴歸（通常可 +以忽略）。 + +爲什麼較新版本必須“使用相似配置編譯”？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +因爲Linux內核開發人員有時會集成已知的會導致迴歸的變更，但使它們成爲可選的，並 +在內核的默認配置下禁用它們。這一技巧允許進步，否則“無迴歸”規則將導致停滯。 + +例如，試想一個新的可以阻止惡意軟件濫用某個內核的接口的安全特性，同時又需要滿足 +另一個很罕見的應用程序。上述的方法可使兩方都滿意：使用這些應用程序的人可以關閉 +新的安全功能，而其他不會遇到麻煩的人可以啓用它。 + +如何創建與舊內核相似的配置？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +用一個已知良好的內核啓動機器，並用 ``make olddefconfig`` 配置新版的Linux。這 +會讓內核的構建腳本從正在運行的內核中摘錄配置文件（“.config”文件），作爲即將編 +譯的新版本的基礎配置；同時將所有新的配置選項設爲默認值，以禁用可能導致迴歸的 +新功能。 + +如何報告在預編譯的普通內核中發現的迴歸？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +您需要確保新的內核是用與舊版相似的配置編譯（見上文），因爲那些構建它們的人可 +能啓用了一些已知的與新內核不兼容的特性。如有疑問，請向內核的提供者報告問題並 +尋求建議。 + + +用“regzbot”追蹤迴歸的更多信息 +----------------------------- + +什麼是迴歸追蹤？爲啥我需要關心它？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +像“無迴歸”這樣的規則需要有人來確保它們被遵守，否則會被有意/無意打破。歷史證 +明瞭這一點對於Linux內核開發也適用。這就是爲什麼Linux內核的迴歸跟蹤者Thorsten +Leemhuis，，和另一些人盡力關注所有的迴歸直到他們解決。他們從未爲此獲得報酬， +因此這項工作是在盡最大努力的基礎上完成的。 + +爲什麼/如何使用機器人追蹤Linux內核迴歸？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +由於Linux內核開發過程的分佈式和鬆散結構，完全手動跟蹤迴歸已經被證明是相當困難 +的。因此Linux內核的迴歸跟蹤者開發了regzbot來促進這項工作，其長期目標是儘可能爲 +所有相關人員自動化迴歸跟蹤。 + +Regzbot通過監視跟蹤的迴歸報告的回覆來工作。此外，它還查找用“Link:”標籤引用這 +些報告的補丁；對這些補丁的回覆也會被跟蹤。結合這些數據，可以很好地瞭解當前修 +復過程的狀態。 + +如何查看regzbot當前追蹤的迴歸？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +參見 `regzbot在線 <https://linux-regtracking.leemhuis.info/regzbot/>`_ 。 + +何種問題可以由regzbot追蹤？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +該機器人只爲了跟蹤迴歸，因此請不要讓regzbot涉及常規問題。但是對於Linux內核的 +迴歸跟蹤者來說，讓regzbot跟蹤嚴重問題也可以，如有關掛起、損壞數據或內部錯誤 +（Panic、Oops、BUG（）、warning…）的報告。 + +如何修改被追蹤迴歸的相關信息？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在直接或間接回復報告郵件時使用“regzbot命令”即可。最簡單的方法是：在“已發送”文 +件夾或郵件列表存檔中找到報告，然後使用郵件客戶端的“全部回覆”功能對其進行回覆。 +在該郵件中的獨立段落中可使用以下命令之一（即使用空行將這些命令中的一個或多個與 +其餘郵件文本分隔開）。 + + * 更新迴歸引入起點，例如在執行二分之後:: + + #regzbot introduced: 1f2e3d4c5d + + * 設置或更新標題:: + + #regzbot title: foo + + * 監視討論或bugzilla.kernel.org上有關討論或修復的工單:: + + #regzbot monitor: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + #regzbot monitor: https://bugzilla.kernel.org/show_bug.cgi?id=123456789 + + * 標記一個有更多相關細節的地方，例如有關但主題不同的郵件列表帖子或缺陷追蹤器中的工單:: + + #regzbot link: https://bugzilla.kernel.org/show_bug.cgi?id=123456789 + + * 標記迴歸已失效:: + + #regzbot invalid: wasn't a regression, problem has always existed + +Regzbot還支持其他一些主要由開發人員或迴歸追蹤人員使用的命令。命令的更多細節請 +參考 `入門指南 <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/getting_started.md>`_ +和 `參考手冊 <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/reference.md>`_ 。 + +.. + 正文結束 +.. + 如本文件開頭所述，本文以GPL-2.0+或CC-BY-4.0許可發行。如您想僅在CC-BY-4.0許 + 可下重分發本文，請用“Linux內核開發者”作爲作者，並用如下鏈接作爲來源： + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst +.. + 注意：本RST文件內容只有在來自Linux內核源代碼時是使用CC-BY-4.0許可的，因爲經 + 過處理的版本（如經內核的構建系統）可能包含來自使用更嚴格許可證的文件的內容。 + diff --git a/Documentation/translations/zh_TW/admin-guide/security-bugs.rst b/Documentation/translations/zh_TW/admin-guide/security-bugs.rst index 15f8e9005071..c0e9fc247695 100644 --- a/Documentation/translations/zh_TW/admin-guide/security-bugs.rst +++ b/Documentation/translations/zh_TW/admin-guide/security-bugs.rst @@ -7,7 +7,7 @@ :譯者: 吳想成 Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> 安全缺陷 ========= @@ -19,17 +19,17 @@ Linux內核開發人員非常重視安全性。因此我們想知道何時發現 ----- 可以通過電子郵件<security@kernel.org>聯繫Linux內核安全團隊。這是一個安全人員 -的私有列表，他們將幫助驗證錯誤報告並開發和發布修復程序。如果您已經有了一個 +的私有列表，他們將幫助驗證錯誤報告並開發和發佈修復程序。如果您已經有了一個 修復，請將其包含在您的報告中，這樣可以大大加快進程。安全團隊可能會從區域維護 -人員那裡獲得額外的幫助，以理解和修復安全漏洞。 +人員那裏獲得額外的幫助，以理解和修復安全漏洞。 與任何缺陷一樣，提供的信息越多，診斷和修復就越容易。如果您不清楚哪些信息有用， -請查看「Documentation/translations/zh_TW/admin-guide/reporting-issues.rst」中 +請查看“Documentation/translations/zh_CN/admin-guide/reporting-issues.rst”中 概述的步驟。任何利用漏洞的攻擊代碼都非常有用，未經報告者同意不會對外發布，除 非已經公開。 -請儘可能發送無附件的純文本電子郵件。如果所有的細節都藏在附件里，那麼就很難對 -一個複雜的問題進行上下文引用的討論。把它想像成一個 +請儘可能發送無附件的純文本電子郵件。如果所有的細節都藏在附件裏，那麼就很難對 +一個複雜的問題進行上下文引用的討論。把它想象成一個 :doc:`常規的補丁提交 <../process/submitting-patches>` （即使你還沒有補丁）： 描述問題和影響，列出復現步驟，然後給出一個建議的解決方案，所有這些都是純文本的。 @@ -38,15 +38,15 @@ Linux內核開發人員非常重視安全性。因此我們想知道何時發現 安全列表不是公開渠道。爲此，請參見下面的協作。 -一旦開發出了健壯的補丁，發布過程就開始了。對公開的缺陷的修復會立即發布。 +一旦開發出了健壯的補丁，發佈過程就開始了。對公開的缺陷的修復會立即發佈。 -儘管我們傾向於在未公開缺陷的修復可用時即發布補丁，但應報告者或受影響方的請求， -這可能會被推遲到發布過程開始後的7日內，如果根據缺陷的嚴重性需要更多的時間， -則可額外延長到14天。推遲發布修復的唯一有效原因是爲了適應QA的邏輯和需要發布 +儘管我們傾向於在未公開缺陷的修復可用時即發佈補丁，但應報告者或受影響方的請求， +這可能會被推遲到發佈過程開始後的7日內，如果根據缺陷的嚴重性需要更多的時間， +則可額外延長到14天。推遲發佈修復的唯一有效原因是爲了適應QA的邏輯和需要發佈 協調的大規模部署。 雖然可能與受信任的個人共享受限信息以開發修復，但未經報告者許可，此類信息不會 -與修復程序一起發布或發布在任何其他披露渠道上。這包括但不限於原始錯誤報告和 +與修復程序一起發佈或發佈在任何其他披露渠道上。這包括但不限於原始錯誤報告和 後續討論（如有）、漏洞、CVE信息或報告者的身份。 換句話說，我們唯一感興趣的是修復缺陷。提交給安全列表的所有其他資料以及對報告 @@ -57,10 +57,10 @@ Linux內核開發人員非常重視安全性。因此我們想知道何時發現 對敏感缺陷（例如那些可能導致權限提升的缺陷）的修復可能需要與私有郵件列表 <linux-distros@vs.openwall.org>進行協調，以便分發供應商做好準備，在公開披露 -上游補丁時發布一個已修復的內核。發行版將需要一些時間來測試建議的補丁，通常 -會要求至少幾天的限制，而供應商更新發布更傾向於周二至周四。若合適，安全團隊 +上游補丁時發佈一個已修復的內核。發行版將需要一些時間來測試建議的補丁，通常 +會要求至少幾天的限制，而供應商更新發布更傾向於週二至週四。若合適，安全團隊 可以協助這種協調，或者報告者可以從一開始就包括linux發行版。在這種情況下，請 -記住在電子郵件主題行前面加上「[vs]」，如linux發行版wiki中所述： +記住在電子郵件主題行前面加上“[vs]”，如linux發行版wiki中所述： <http://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists>。 CVE分配 diff --git a/Documentation/translations/zh_TW/admin-guide/sysrq.rst b/Documentation/translations/zh_TW/admin-guide/sysrq.rst new file mode 100644 index 000000000000..4a08db00a495 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/sysrq.rst @@ -0,0 +1,281 @@ +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/sysrq.rst + +:翻譯: + + 黃軍華 Junhua Huang <huang.junhua@zte.com.cn> + +:校譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +.. _tw_admin-guide_sysrq: + +Linux 魔法系統請求鍵駭客 +======================== + +針對 sysrq.c 的文檔說明 + +什麼是魔法 SysRq 鍵？ +~~~~~~~~~~~~~~~~~~~~~ + +它是一個你可以輸入的具有魔法般的組合鍵。 +無論內核在做什麼，內核都會響應 SysRq 鍵的輸入，除非內核完全卡死。 + +如何使能魔法 SysRq 鍵？ +~~~~~~~~~~~~~~~~~~~~~~~ + +在配置內核時，我們需要設置 'Magic SysRq key (CONFIG_MAGIC_SYSRQ)' 爲 'Y'。 +當運行一個編譯進 sysrq 功能的內核時，/proc/sys/kernel/sysrq 控制着被 +SysRq 鍵調用的功能許可。這個文件的默認值由 CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE +配置符號設定，文件本身默認設置爲 1。以下是 /proc/sys/kernel/sysrq 中可能的 +值列表： + + - 0 - 完全不使能 SysRq 鍵 + - 1 - 使能 SysRq 鍵的全部功能 + - >1 - 對於允許的 SysRq 鍵功能的比特掩碼（參見下面更詳細的功能描述）:: + + 2 = 0x2 - 使能對控制檯日誌記錄級別的控制 + 4 = 0x4 - 使能對鍵盤的控制 (SAK, unraw) + 8 = 0x8 - 使能對進程的調試導出等 + 16 = 0x10 - 使能同步命令 + 32 = 0x20 - 使能重新掛載只讀 + 64 = 0x40 - 使能對進程的信號操作 (term, kill, oom-kill) + 128 = 0x80 - 允許重啓、斷電 + 256 = 0x100 - 允許讓所有實時任務變普通任務 + +你可以通過如下命令把值設置到這個文件中:: + + echo "number" >/proc/sys/kernel/sysrq + +這裏被寫入的 number 可以是 10 進制數，或者是帶着 0x 前綴的 16 進制數。 +CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE 必須是以 16 進制數寫入。 + +注意，``/proc/sys/kernel/sysrq`` 的值隻影響通過鍵盤觸發 SySRq 的調用，對於 +通過 ``/proc/sysrq-trigger`` 的任何操作調用都是允許的 +（通過具有系統權限的用戶）。 + +如何使用魔法 SysRq 鍵？ +~~~~~~~~~~~~~~~~~~~~~~~ + +在 x86 架構上 + 你可以按下鍵盤組合鍵 :kbd:`ALT-SysRq-<command key>`。 + + .. note:: + 一些鍵盤可能沒有標識 'SySRq' 鍵。'SySRq' 鍵也被當做 'Print Screen'鍵。 + 同時有些鍵盤無法處理同時按下這麼多鍵，因此你可以先按下鍵盤 :kbd:`Alt` 鍵， + 然後按下鍵盤 :kbd:`SysRq` 鍵，再釋放鍵盤 :kbd:`SysRq` 鍵，之後按下鍵盤上命令鍵 + :kbd:`<command key>`，最後釋放所有鍵。 + +在 SPARC 架構上 + 你可以按下鍵盤組合鍵 :kbd:`ALT-STOP-<command key>` 。 + +在串行控制檯（只針對 PC 類型的標準串口） + 你可以發一個 ``BREAK`` ，然後在 5 秒內發送一個命令鍵， + 發送 ``BREAK`` 兩次將被翻譯爲一個正常的 BREAK 操作。 + +在 PowerPC 架構上 + 按下鍵盤組合鍵 :kbd:`ALT - Print Screen` （或者 :kbd:`F13`） - :kbd:`<命令鍵>` 。 + :kbd:`Print Screen` （或者 :kbd:`F13`） - :kbd:`<命令鍵>` 或許也能實現。 + +在其他架構上 + 如果你知道其他架構的組合鍵，請告訴我，我可以把它們添加到這部分。 + +在所有架構上 + 寫一個字符到 /proc/sysrq-trigger 文件，例如:: + + echo t > /proc/sysrq-trigger + +這個命令鍵 :kbd:`<command key>` 是區分大小寫的。 + +什麼是命令鍵？ +~~~~~~~~~~~~~~ + +=========== ================================================================ +命令鍵 功能 +=========== ================================================================ +``b`` 將立即重啓系統，不會同步或者卸載磁盤。 + +``c`` 將執行系統 crash，如果配置了系統 crashdump，將執行 crashdump。 + +``d`` 顯示所有持有的鎖。 + +``e`` 發送 SIGTERM 信號給所有進程，除了 init 進程。 + +``f`` 將調用 oom killer 殺掉一個過度佔用內存的進程，如果什麼任務都沒殺， + 也不會 panic。 + +``g`` kgdb 使用（內核調試器）。 + +``h`` 將會顯示幫助。（實際上除了這裏列舉的鍵，其他的都將顯示幫助， + 但是 ``h`` 容易記住）:-) + +``i`` 發送 SIGKILL 給所有進程，除了 init 進程。 + +``j`` 強制性的 “解凍它” - 用於被 FIFREEZE ioctl 操作凍住的文件系統。 + +``k`` 安全訪問祕鑰(SAK)殺掉在當前虛擬控制檯的所有程序，注意：參考 + 下面 SAK 節重要論述。 + +``l`` 顯示所有活動 cpu 的棧回溯。 + +``m`` 將導出當前內存信息到你的控制檯。 + +``n`` 用於使所有實時任務變成普通任務。 + +``o`` 將關閉系統（如果配置和支持的話）。 + +``p`` 將導出當前寄存器和標誌位到控制檯。 + +``q`` 將導出每個 cpu 上所有已裝備的高精度定時器（不是完整的 + time_list 文件顯示的 timers）和所有時鐘事件設備的詳細信息。 + +``r`` 關閉鍵盤的原始模式，設置爲轉換模式。 + +``s`` 將嘗試同步所有的已掛載文件系統。 + +``t`` 將導出當前所有任務列表和它們的信息到控制檯。 + +``u`` 將嘗試重新掛載已掛載文件系統爲只讀。 + +``v`` 強制恢復幀緩存控制檯。 +``v`` 觸發 ETM 緩存導出 [ARM 架構特有] + +``w`` 導出處於不可中斷狀態（阻塞）的任務。 + +``x`` 在 ppc/powerpc 架構上用於 xmon 接口。 + 在 sparc64 架構上用於顯示全局的 PMU（性能監控單元）寄存器。 + 在 MIPS 架構上導出所有的 tlb 條目。 + +``y`` 顯示全局 cpu 寄存器 [SPARC-64 架構特有] + +``z`` 導出 ftrace 緩存信息 + +``0``-``9`` 設置控制檯日誌級別，該級別控制什麼樣的內核信息將被打印到你的 + 控制檯。（比如 ``0`` ，將使得只有緊急信息，像 PANICs or OOPSes + 才能到你的控制檯。） +=========== ================================================================ + +好了，我能用他們做什麼呢？ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +嗯，當你的 X 服務端或者 svgalib 程序崩潰，unraw(r) 非原始模式命令鍵是非常 +方便的。 + +sak(k)（安全訪問祕鑰）在你嘗試登陸的同時，又想確保當前控制檯沒有可以獲取你的 +密碼的特洛伊木馬程序運行時是有用的。它會殺掉給定控制檯的所有程序，這樣你 +就可以確認當前的登陸提示程序是實際來自 init 進程的程序，而不是某些特洛伊 +木馬程序。 + +.. important:: + + 在其實際的形式中，在兼容 C2 安全標準的系統上，它不是一個真正的 SAK， + 它也不應該誤認爲此。 + +似乎其他人發現其可以作爲（系統終端聯機鍵）當你想退出一個程序， +同時不會讓你切換控制檯的方法。（比如，X 服務端或者 svgalib 程序） + +``reboot(b)`` 是個好方法，當你不能關閉機器時，它等同於按下"復位"按鈕。 + +``crash(c)`` 可以用於手動觸發一個 crashdump，當系統卡住時。 +注意當 crashdump 機制不可用時，這個只是觸發一個內核 crash。 + +``sync(s)`` 在拔掉可移動介質之前，或者在使用不提供優雅關機的 +救援 shell 之後很方便 -- 它將確保你的數據被安全地寫入磁盤。注意，在你看到 +屏幕上出現 "OK" 和 "Done" 之前，同步還沒有發生。 + +``umount(u)`` 可以用來標記文件系統正常卸載，從正在運行的系統角度來看，它們將 +被重新掛載爲只讀。這個重新掛載動作直到你看到 "OK" 和 "Done" 信息出現在屏幕上 +纔算完成。 + +日誌級別 ``0`` - ``9`` 用於當你的控制檯被大量的內核信息衝擊，你不想看見的時候。 +選擇 ``0`` 將禁止除了最緊急的內核信息外的所有的內核信息輸出到控制檯。（但是如果 +syslogd/klogd 進程是運行的，它們仍將被記錄。） + +``term(e)`` 和 ``kill(i)`` 用於當你有些有點失控的進程，你無法通過其他方式殺掉 +它們的時候，特別是它正在創建其他進程。 + +"just thaw ``it(j)`` " 用於當你的系統由於一個 FIFREEZE ioctl 調用而產生的文件 +系統凍結，而導致的不響應時。 + +有的時候 SysRq 鍵在使用它之後，看起來像是“卡住”了，我能做些什麼？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +這也會發生在我這，我發現輕敲鍵盤兩側的 shift、alt 和 control 鍵，然後再次敲擊 +一個無效的 SysRq 鍵序列可以解決問題。（比如，像鍵盤組合鍵 :kbd:`alt-sysrq-z` ） +切換到另一個虛擬控制檯（鍵盤操作 :kbd:`ALT+Fn` ），然後再切回來應該也有幫助。 + +我敲擊了 SysRq 鍵，但像是什麼都沒發生，發生了什麼錯誤？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +有一些鍵盤對於 SysRq 鍵設置了不同的鍵值，而不是提前定義的 99 +(查看在 ``include/uapi/linux/input-event-codes.h`` 文件中 ``KEY_SYSRQ`` 的定義) +或者就根本沒有 SysRq 鍵。在這些場景下，執行 ``showkey -s`` 命令來找到一個合適 +的掃描碼序列，然後使用 ``setkeycodes <sequence> 99`` 命令映射這個序列值到通用 +的 SysRq 鍵編碼上（比如 ``setkeycodes e05b 99`` ）。最好將這個命令放在啓動腳本 +中。 +哦，順便說一句，你十秒鐘不輸入任何東西就將退出 “showkey”。 + +我想添加一個 SysRq 鍵事件到一個模塊中，如何去做呢？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +爲了註冊一個基礎函數到這個表中，首先你必須包含 ``include/linux/sysrq.h`` 頭 +文件，這個頭文件定義了你所需要的所有東西。然後你必須創建一個 ``sysrq_key_op`` +結構體，然後初始化它，使用如下內容，A） 你將使用的這個鍵的處理函數， B） 一個 +help_msg 字符串，在 SysRq 鍵打印幫助信息時將打印出來，C） 一個 action_msg 字 +符串，就在你的處理函數調用前打印出來。你的處理函數必須符合在 'sysrq.h' 文件中 +的函數原型。 + +在 ``sysrq_key_op`` 結構體被創建後，你可以調用內核函數 +``register_sysrq_key(int key, const struct sysrq_key_op *op_p);``， +該函數在表中的 'key' 對應位置內容是空的情況下，將通過 ``op_p`` 指針註冊這個操作 +函數到表中 'key' 對應位置上。在模塊卸載的時候，你必須調用 +``unregister_sysrq_key(int key, const struct sysrq_key_op *op_p)`` 函數，該函數 +只有在當前該鍵對應的處理函數被註冊到了 'key' 對應位置時，纔會移除 'op_p' 指針 +對應的鍵值操作函數。這是爲了防止在你註冊之後，該位置被改寫的情況。 + +魔法 SysRq 鍵系統的工作原理是將鍵對應操作函數註冊到鍵的操作查找表， +該表定義在 'drivers/tty/sysrq.c' 文件中。 +該鍵表有許多在編譯時候就註冊進去的操作函數，但是是可變的。 +並且有兩個函數作爲操作該表的接口被導出:: + + register_sysrq_key 和 unregister_sysrq_key. + +當然，永遠不要在表中留下無效指針，即，當你的模塊存在調用 register_sysrq_key() +函數，它一定要調用 unregister_sysrq_key() 來清除它使用過的 SysRq 鍵表條目。 +表中的空指針是安全的。:) + +如果對於某種原因，在 handle_sysrq 調用的處理函數中，你認爲有必要調用 +handle_sysrq 函數時，你必須意識到當前你處於一個鎖中（你同時也處於一箇中斷處理 +函數中，這意味着不能睡眠）。所以這時你必須使用 ``__handle_sysrq_nolock`` 替代。 + +當我敲擊一個 SysRq 組合鍵時，只有標題打印出現在控制檯？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +SysRq 鍵的輸出和所有其他控制檯輸出一樣，受制於控制檯日誌級別控制。 +這意味着，如果內核以發行版內核中常見的 "quiet" 方式啓動，則輸出可能不會出現在實際 +的控制檯上，即使它會出現在 dmesg 緩存中，也可以通過 dmesg 命令和 ``/proc/kmsg`` +文件的消費訪問到。作爲一個特例，來自 sysrq 命令的標題行將被傳遞給所有控制檯 +使用者，就好像當前日誌級別是最大的一樣。如果只發出標題頭，則幾乎可以肯定內核日誌 +級別太低。如果你需要控制檯上的輸出，那麼你將需要臨時提高控制檯日誌級別，通過使用 +鍵盤組合鍵 :kbd:`alt-sysrq-8` 或者:: + + echo 8 > /proc/sysrq-trigger + +在觸發了你感興趣的 SysRq 鍵命令後，記得恢復日誌級別到正常情況。 + +我有很多問題時，可以請教誰？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +請教在內核郵件列表上的人，郵箱： + linux-kernel@vger.kernel.org + +致謝 +~~~~ + +- Mydraal <vulpyne@vulpyne.net> 撰寫了該文件 +- Adam Sulmicki <adam@cfar.umd.edu> 進行了更新 +- Jeremy M. Dolan <jmd@turbogeek.org> 在 2001/01/28 10:15:59 進行了更新 +- Crutcher Dunnavant <crutcher+kernel@datastacks.com> 添加鍵註冊部分 + diff --git a/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst b/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst index d7b3c4276417..47629f6b05de 100644 --- a/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst +++ b/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst @@ -7,29 +7,29 @@ :譯者: 吳想成 Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> -受汙染的內核 +受污染的內核 ------------- -當發生一些在稍後調查問題時可能相關的事件時，內核會將自己標記爲「受汙染 -（tainted）」的。不用太過擔心，大多數情況下運行受汙染的內核沒有問題；這些信息 -主要在有人想調查某個問題時才有意義的，因爲問題的真正原因可能是導致內核受汙染 -的事件。這就是爲什麼來自受汙染內核的缺陷報告常常被開發人員忽略，因此請嘗試用 -未受汙染的內核重現問題。 +當發生一些在稍後調查問題時可能相關的事件時，內核會將自己標記爲“受污染 +（tainted）”的。不用太過擔心，大多數情況下運行受污染的內核沒有問題；這些信息 +主要在有人想調查某個問題時纔有意義的，因爲問題的真正原因可能是導致內核受污染 +的事件。這就是爲什麼來自受污染內核的缺陷報告常常被開發人員忽略，因此請嘗試用 +未受污染的內核重現問題。 -請注意，即使在您消除導致汙染的原因（亦即卸載專有內核模塊）之後，內核仍將保持 -汙染狀態，以表示內核仍然不可信。這也是爲什麼內核在注意到內部問題（「kernel -bug」）、可恢復錯誤（「kernel oops」）或不可恢復錯誤（「kernel panic」）時會列印 -受汙染狀態，並將有關此的調試信息寫入日誌 ``dmesg`` 輸出。也可以通過 -``/proc/`` 中的文件在運行時檢查受汙染的狀態。 +請注意，即使在您消除導致污染的原因（亦即卸載專有內核模塊）之後，內核仍將保持 +污染狀態，以表示內核仍然不可信。這也是爲什麼內核在注意到內部問題（“kernel +bug”）、可恢復錯誤（“kernel oops”）或不可恢復錯誤（“kernel panic”）時會打印 +受污染狀態，並將有關此的調試信息寫入日誌 ``dmesg`` 輸出。也可以通過 +``/proc/`` 中的文件在運行時檢查受污染的狀態。 -BUG、Oops或Panics消息中的汙染標誌 +BUG、Oops或Panics消息中的污染標誌 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -在頂部以「CPU:」開頭的一行中可以找到受汙染的狀態；內核是否受到汙染和原因會顯示 -在進程ID（「PID:」）和觸發事件命令的縮寫名稱（「Comm:」）之後:: +在頂部以“CPU:”開頭的一行中可以找到受污染的狀態；內核是否受到污染和原因會顯示 +在進程ID（“PID:”）和觸發事件命令的縮寫名稱（“Comm:”）之後:: BUG: unable to handle kernel NULL pointer dereference at 0000000000000000 Oops: 0002 [#1] SMP PTI @@ -38,27 +38,27 @@ BUG、Oops或Panics消息中的汙染標誌 RIP: 0010:my_oops_init+0x13/0x1000 [kpanic] [...] -如果內核在事件發生時沒有被汙染，您將在那裡看到「Not-tainted:」；如果被汙染，那 -麼它將是「Tainted:」以及字母或空格。在上面的例子中，它看起來是這樣的:: +如果內核在事件發生時沒有被污染，您將在那裏看到“Not-tainted:”；如果被污染，那 +麼它將是“Tainted:”以及字母或空格。在上面的例子中，它看起來是這樣的:: Tainted: P W O 下表解釋了這些字符的含義。在本例中，由於加載了專有模塊（ ``P`` ），出現了 警告（ ``W`` ），並且加載了外部構建的模塊（ ``O`` ），所以內核早些時候受到 -了汙染。要解碼其他字符，請使用下表。 +了污染。要解碼其他字符，請使用下表。 -解碼運行時的汙染狀態 +解碼運行時的污染狀態 ~~~~~~~~~~~~~~~~~~~~~ -在運行時，您可以通過讀取 ``cat /proc/sys/kernel/tainted`` 來查詢受汙染狀態。 -如果返回 ``0`` ，則內核沒有受到汙染；任何其他數字都表示受到汙染的原因。解碼 +在運行時，您可以通過讀取 ``cat /proc/sys/kernel/tainted`` 來查詢受污染狀態。 +如果返回 ``0`` ，則內核沒有受到污染；任何其他數字都表示受到污染的原因。解碼 這個數字的最簡單方法是使用腳本 ``tools/debugging/kernel-chktaint`` ，您的 發行版可能會將其作爲名爲 ``linux-tools`` 或 ``kernel-tools`` 的包的一部分提 供；如果沒有，您可以從 `git.kernel.org <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/tools/debugging/kernel-chktaint>`_ 網站下載此腳本並用 ``sh kernel-chktaint`` 執行，它會在上面引用的日誌中有類似 -語句的機器上列印這樣的內容:: +語句的機器上打印這樣的內容:: Kernel is Tainted for following reasons: * Proprietary module was loaded (#0) @@ -69,19 +69,19 @@ BUG、Oops或Panics消息中的汙染標誌 a more details explanation of the various taint flags. Raw taint value as int/string: 4609/'P W O ' -你也可以試著自己解碼這個數字。如果內核被汙染的原因只有一個，那麼這很簡單， +你也可以試着自己解碼這個數字。如果內核被污染的原因只有一個，那麼這很簡單， 在本例中您可以通過下表找到數字。如果你需要解碼有多個原因的數字，因爲它是一 -個位域（bitfield），其中每個位表示一個特定類型的汙染的存在或不存在，最好讓 +個位域（bitfield），其中每個位表示一個特定類型的污染的存在或不存在，最好讓 前面提到的腳本來處理。但是如果您需要快速看一下，可以使用這個shell命令來檢查 設置了哪些位:: $ for i in $(seq 18); do echo $(($i-1)) $(($(cat /proc/sys/kernel/tainted)>>($i-1)&1));done -汙染狀態代碼表 +污染狀態代碼表 ~~~~~~~~~~~~~~~ === ===== ====== ======================================================== - 位 日誌 數字 內核被汙染的原因 + 位 日誌 數字 內核被污染的原因 === ===== ====== ======================================================== 0 G/P 1 已加載專用模塊 1 _/F 2 模塊被強制加載 @@ -89,23 +89,23 @@ BUG、Oops或Panics消息中的汙染標誌 3 _/R 8 模塊被強制卸載 4 _/M 16 處理器報告了機器檢測異常（MCE） 5 _/B 32 引用了錯誤的頁或某些意外的頁標誌 - 6 _/U 64 用戶空間應用程式請求的汙染 + 6 _/U 64 用戶空間應用程序請求的污染 7 _/D 128 內核最近死機了，即曾出現OOPS或BUG 8 _/A 256 ACPI表被用戶覆蓋 9 _/W 512 內核發出警告 10 _/C 1024 已加載staging驅動程序 - 11 _/I 2048 已應用平台固件缺陷的解決方案 - 12 _/O 4096 已加載外部構建（「樹外」）模塊 + 11 _/I 2048 已應用平臺固件缺陷的解決方案 + 12 _/O 4096 已加載外部構建（“樹外”）模塊 13 _/E 8192 已加載未簽名的模塊 14 _/L 16384 發生軟鎖定 15 _/K 32768 內核已實時打補丁 - 16 _/X 65536 備用汙染，爲發行版定義並使用 + 16 _/X 65536 備用污染，爲發行版定義並使用 17 _/T 131072 內核是用結構隨機化插件構建的 === ===== ====== ======================================================== -註：字符 ``_`` 表示空白，以便於閱讀表。 +注：字符 ``_`` 表示空白，以便於閱讀表。 -汙染的更詳細解釋 +污染的更詳細解釋 ~~~~~~~~~~~~~~~~~ 0) ``G`` 加載的所有模塊都有GPL或兼容許可證， ``P`` 加載了任何專有模塊。 @@ -115,14 +115,14 @@ BUG、Oops或Panics消息中的汙染標誌 1) ``F`` 任何模塊被 ``insmod -f`` 強制加載， ``' '`` 所有模塊正常加載。 - 2) ``S`` 內核運行在不合規範的處理器或系統上：硬體已運行在不受支持的配置中， - 因此無法保證正確執行。內核將被汙染，例如： + 2) ``S`` 內核運行在不合規範的處理器或系統上：硬件已運行在不受支持的配置中， + 因此無法保證正確執行。內核將被污染，例如： - 在x86上：PAE是通過intel CPU（如Pentium M）上的forcepae強制執行的，這些 CPU不報告PAE，但可能有功能實現，SMP內核在非官方支持的SMP Athlon CPU上 運行，MSR被暴露到用戶空間中。 - 在arm上：在某些CPU（如Keystone 2）上運行的內核，沒有啓用某些內核特性。 - - 在arm64上：CPU之間存在不匹配的硬體特性，引導加載程序以不同的模式引導CPU。 + - 在arm64上：CPU之間存在不匹配的硬件特性，引導加載程序以不同的模式引導CPU。 - 某些驅動程序正在被用在不受支持的體系結構上（例如x86_64以外的其他系統 上的scsi/snic，非x86/x86_64/itanium上的scsi/ips，已經損壞了arm64上 irqchip/irq-gic的固件設置…）。 @@ -131,22 +131,22 @@ BUG、Oops或Panics消息中的汙染標誌 4) ``M`` 任何處理器報告了機器檢測異常， ``' '`` 未發生機器檢測異常。 - 5) ``B`` 頁面釋放函數發現錯誤的頁面引用或某些意外的頁面標誌。這表示硬體問題 - 或內核錯誤；日誌中應該有其他信息指示發生此汙染的原因。 + 5) ``B`` 頁面釋放函數發現錯誤的頁面引用或某些意外的頁面標誌。這表示硬件問題 + 或內核錯誤；日誌中應該有其他信息指示發生此污染的原因。 - 6) ``U`` 用戶或用戶應用程式特意請求設置受汙染標誌，否則應爲 ``' '`` 。 + 6) ``U`` 用戶或用戶應用程序特意請求設置受污染標誌，否則應爲 ``' '`` 。 7) ``D`` 內核最近死機了，即出現了OOPS或BUG。 8) ``A`` ACPI表被重寫。 - 9) ``W`` 內核之前已發出過警告（儘管有些警告可能會設置更具體的汙染標誌）。 + 9) ``W`` 內核之前已發出過警告（儘管有些警告可能會設置更具體的污染標誌）。 10) ``C`` 已加載staging驅動程序。 - 11) ``I`` 內核正在處理平台固件（BIOS或類似軟體）中的嚴重錯誤。 + 11) ``I`` 內核正在處理平臺固件（BIOS或類似軟件）中的嚴重錯誤。 - 12) ``O`` 已加載外部構建（「樹外」）模塊。 + 12) ``O`` 已加載外部構建（“樹外”）模塊。 13) ``E`` 在支持模塊簽名的內核中加載了未簽名的模塊。 @@ -154,8 +154,8 @@ BUG、Oops或Panics消息中的汙染標誌 15) ``K`` 內核已經實時打了補丁。 - 16) ``X`` 備用汙染，由Linux發行版定義和使用。 + 16) ``X`` 備用污染，由Linux發行版定義和使用。 17) ``T`` 內核構建時使用了randstruct插件，它可以有意生成非常不尋常的內核結構 - 布局（甚至是性能病態的布局），這在調試時非常有用。於構建時設置。 + 佈局（甚至是性能病態的佈局），這在調試時非常有用。於構建時設置。 diff --git a/Documentation/translations/zh_TW/admin-guide/unicode.rst b/Documentation/translations/zh_TW/admin-guide/unicode.rst index 720875be5ef8..a2b48b5d0a64 100644 --- a/Documentation/translations/zh_TW/admin-guide/unicode.rst +++ b/Documentation/translations/zh_TW/admin-guide/unicode.rst @@ -7,7 +7,7 @@ :譯者: 吳想成 Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> Unicode（統一碼）支持 ====================== @@ -37,15 +37,15 @@ IBMPC_MAP IBM code page 437 ESC ( U USER_MAP User defined ESC ( K =============== =============================== ================ -特別是 ESC ( U 不再是「直通字體」，因爲字體可能與IBM字符集完全不同。 +特別是 ESC ( U 不再是“直通字體”，因爲字體可能與IBM字符集完全不同。 例如，即使加載了一個Latin-1字體，也允許使用塊圖形（block graphics）。 請注意，儘管這些代碼與ISO 2022類似，但這些代碼及其用途都與ISO 2022不匹配； Linux有兩個八位代碼（G0和G1），而ISO 2022有四個七位代碼（G0-G3）。 -根據Unicode標準/ISO 10646，U+F000到U+F8FF被保留用於作業系統範圍內的分配 -（Unicode標準將其稱爲「團體區域（Corporate Zone）」，因爲這對於Linux是不準確 -的，所以我們稱之爲「Linux區域」）。選擇U+F000作爲起點，因爲它允許直接映射 +根據Unicode標準/ISO 10646，U+F000到U+F8FF被保留用於操作系統範圍內的分配 +（Unicode標準將其稱爲“團體區域（Corporate Zone）”，因爲這對於Linux是不準確 +的，所以我們稱之爲“Linux區域”）。選擇U+F000作爲起點，因爲它允許直接映射 區域以2的大倍數開始（以防需要1024或2048個字符的字體）。這就留下U+E000到 U+EFFF作爲最終用戶區。 @@ -87,7 +87,7 @@ U+F813 KEYBOARD SYMBOL SOLID APPLE 克林貢（Klingon）語支持 ------------------------ -1996年，Linux是世界上第一個添加對人工語言克林貢支持的作業系統，克林貢是由 +1996年，Linux是世界上第一個添加對人工語言克林貢支持的操作系統，克林貢是由 Marc Okrand爲《星際迷航》電視連續劇創造的。這種編碼後來被徵募Unicode註冊表 （ConScript Unicode Registry，CSUR）採用，並建議（但最終被拒絕）納入Unicode 平面一。不過，它仍然是Linux區域中的Linux/CSUR私有分配。 diff --git a/Documentation/translations/zh_TW/arch/arm/Booting b/Documentation/translations/zh_TW/arch/arm/Booting new file mode 100644 index 000000000000..a5375f262de2 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/arm/Booting @@ -0,0 +1,176 @@ +Chinese translated version of Documentation/arch/arm/booting.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Russell King <linux@arm.linux.org.uk> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/arch/arm/booting.rst 的中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 +譯存在問題，請聯繫中文版維護者。 + +英文版維護者： Russell King <linux@arm.linux.org.uk> +中文版維護者： 傅煒 Fu Wei <tekkamanninja@gmail.com> +中文版翻譯者： 傅煒 Fu Wei <tekkamanninja@gmail.com> +中文版校譯者： 傅煒 Fu Wei <tekkamanninja@gmail.com> + +以下爲正文 +--------------------------------------------------------------------- + + 啓動 ARM Linux + ============== + +作者：Russell King +日期：2002年5月18日 + +以下文檔適用於 2.4.18-rmk6 及以上版本。 + +爲了啓動 ARM Linux，你需要一個引導裝載程序（boot loader）， +它是一個在主內核啓動前運行的一個小程序。引導裝載程序需要初始化各種 +設備，並最終調用 Linux 內核，將信息傳遞給內核。 + +從本質上講，引導裝載程序應提供（至少）以下功能： + +1、設置和初始化 RAM。 +2、初始化一個串口。 +3、檢測機器的類型（machine type）。 +4、設置內核標籤列表（tagged list）。 +5、調用內核映像。 + + +1、設置和初始化 RAM +------------------- + +現有的引導加載程序: 強制 +新開發的引導加載程序: 強制 + +引導裝載程序應該找到並初始化系統中所有內核用於保持系統變量數據的 RAM。 +這個操作的執行是設備依賴的。（它可能使用內部算法來自動定位和計算所有 +RAM，或可能使用對這個設備已知的 RAM 信息，還可能使用任何引導裝載程序 +設計者想到的匹配方法。） + + +2、初始化一個串口 +----------------------------- + +現有的引導加載程序: 可選、建議 +新開發的引導加載程序: 可選、建議 + +引導加載程序應該初始化並使能一個目標板上的串口。這允許內核串口驅動 +自動檢測哪個串口用於內核控制檯。(一般用於調試或與目標板通信。) + +作爲替代方案，引導加載程序也可以通過標籤列表傳遞相關的'console=' +選項給內核以指定某個串口，而串口數據格式的選項在以下文檔中描述： + + Documentation/admin-guide/kernel-parameters.rst。 + + +3、檢測機器類型 +-------------------------- + +現有的引導加載程序: 可選 +新開發的引導加載程序: 強制 + +引導加載程序應該通過某些方式檢測自身所處的機器類型。這是一個硬件 +代碼或通過查看所連接的硬件用某些算法得到，這些超出了本文檔的範圍。 +引導加載程序最終必須能提供一個 MACH_TYPE_xxx 值給內核。 +(詳見 linux/arch/arm/tools/mach-types )。 + +4、設置啓動數據 +------------------ + +現有的引導加載程序: 可選、強烈建議 +新開發的引導加載程序: 強制 + +引導加載程序必須提供標籤列表或者 dtb 映像以傳遞配置數據給內核。啓動 +數據的物理地址通過寄存器 r2 傳遞給內核。 + +4a、設置內核標籤列表 +-------------------------------- + +bootloader 必須創建和初始化內核標籤列表。一個有效的標籤列表以 +ATAG_CORE 標籤開始，並以 ATAG_NONE 標籤結束。ATAG_CORE 標籤可以是 +空的，也可以是非空。一個空 ATAG_CORE 標籤其 size 域設置爲 +‘2’(0x00000002)。ATAG_NONE 標籤的 size 域必須設置爲零。 + +在列表中可以保存任意數量的標籤。對於一個重複的標籤是追加到之前標籤 +所攜帶的信息之後，還是會覆蓋原來的信息，是未定義的。某些標籤的行爲 +是前者，其他是後者。 + +bootloader 必須傳遞一個系統內存的位置和最小值，以及根文件系統位置。 +因此，最小的標籤列表如下所示： + + +-----------+ +基地址 -> | ATAG_CORE | | + +-----------+ | + | ATAG_MEM | | 地址增長方向 + +-----------+ | + | ATAG_NONE | | + +-----------+ v + +標籤列表應該保存在系統的 RAM 中。 + +標籤列表必須置於內核自解壓和 initrd'bootp' 程序都不會覆蓋的內存區。 +建議放在 RAM 的頭 16KiB 中。 + +4b、設置設備樹 +------------------------- + +bootloader 必須以 64bit 地址對齊的形式加載一個設備樹映像(dtb)到系統 +RAM 中，並用啓動數據初始化它。dtb 格式在文檔 +https://www.devicetree.org/specifications/ 中。內核將會在 +dtb 物理地址處查找 dtb 魔數值（0xd00dfeed），以確定 dtb 是否已經代替 +標籤列表被傳遞進來。 + +bootloader 必須傳遞一個系統內存的位置和最小值，以及根文件系統位置。 +dtb 必須置於內核自解壓不會覆蓋的內存區。建議將其放置於 RAM 的頭 16KiB +中。但是不可將其放置於“0”物理地址處，因爲內核認爲：r2 中爲 0，意味着 +沒有標籤列表和 dtb 傳遞過來。 + +5、調用內核映像 +--------------------------- + +現有的引導加載程序: 強制 +新開發的引導加載程序: 強制 + +調用內核映像 zImage 有兩個選擇。如果 zImge 保存在 flash 中，且是爲了 +在 flash 中直接運行而被正確鏈接的。這樣引導加載程序就可以在 flash 中 +直接調用 zImage。 + +zImage 也可以被放在系統 RAM（任意位置）中被調用。注意：內核使用映像 +基地址的前 16KB RAM 空間來保存頁表。建議將映像置於 RAM 的 32KB 處。 + +對於以上任意一種情況，都必須符合以下啓動狀態： + +- 停止所有 DMA 設備，這樣內存數據就不會因爲虛假網絡包或磁盤數據而被破壞。 + 這可能可以節省你許多的調試時間。 + +- CPU 寄存器配置 + r0 = 0， + r1 = （在上面 3 中獲取的）機器類型碼。 + r2 = 標籤列表在系統 RAM 中的物理地址，或 + 設備樹塊(dtb)在系統 RAM 中的物理地址 + +- CPU 模式 + 所有形式的中斷必須被禁止 (IRQs 和 FIQs) + CPU 必須處於 SVC 模式。(對於 Angel 調試有特例存在) + +- 緩存，MMUs + MMU 必須關閉。 + 指令緩存開啓或關閉都可以。 + 數據緩存必須關閉。 + +- 引導加載程序應該通過直接跳轉到內核映像的第一條指令來調用內核映像。 + + 對於支持 ARM 指令集的 CPU，跳入內核入口時必須處在 ARM 狀態，即使 + 對於 Thumb-2 內核也是如此。 + + 對於僅支持 Thumb 指令集的 CPU，比如 Cortex-M 系列的 CPU，跳入 + 內核入口時必須處於 Thumb 狀態。 + diff --git a/Documentation/translations/zh_TW/arch/arm/kernel_user_helpers.txt b/Documentation/translations/zh_TW/arch/arm/kernel_user_helpers.txt new file mode 100644 index 000000000000..4c0bff97af31 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/arm/kernel_user_helpers.txt @@ -0,0 +1,285 @@ +Chinese translated version of Documentation/arch/arm/kernel_user_helpers.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Nicolas Pitre <nicolas.pitre@linaro.org> + Dave Martin <dave.martin@linaro.org> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/arch/arm/kernel_user_helpers.rst 的中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 +譯存在問題，請聯繫中文版維護者。 +英文版維護者： Nicolas Pitre <nicolas.pitre@linaro.org> + Dave Martin <dave.martin@linaro.org> +中文版維護者： 傅煒 Fu Wei <tekkamanninja@gmail.com> +中文版翻譯者： 傅煒 Fu Wei <tekkamanninja@gmail.com> +中文版校譯者： 宋冬生 Dongsheng Song <dongshneg.song@gmail.com> + 傅煒 Fu Wei <tekkamanninja@gmail.com> + + +以下爲正文 +--------------------------------------------------------------------- +內核提供的用戶空間輔助代碼 +========================= + +在內核內存空間的固定地址處，有一個由內核提供並可從用戶空間訪問的代碼 +段。它用於向用戶空間提供因在許多 ARM CPU 中未實現的特性和/或指令而需 +內核提供幫助的某些操作。這些代碼直接在用戶模式下執行的想法是爲了獲得 +最佳效率，但那些與內核計數器聯繫過於緊密的部分，則被留給了用戶庫實現。 +事實上，此代碼甚至可能因不同的 CPU 而異，這取決於其可用的指令集或它 +是否爲 SMP 系統。換句話說，內核保留在不作出警告的情況下根據需要更改 +這些代碼的權利。只有本文檔描述的入口及其結果是保證穩定的。 + +這與完全成熟的 VDSO 實現不同（但兩者並不衝突），儘管如此，VDSO 可阻止 +某些通過常量高效跳轉到那些代碼段的彙編技巧。且由於那些代碼段在返回用戶 +代碼前僅使用少量的代碼週期，則一個 VDSO 間接遠程調用將會在這些簡單的 +操作上增加一個可測量的開銷。 + +在對那些擁有原生支持的新型處理器進行代碼優化時，僅在已爲其他操作使用 +了類似的新增指令，而導致二進制結果已與早期 ARM 處理器不兼容的情況下， +用戶空間才應繞過這些輔助代碼，並在內聯函數中實現這些操作（無論是通過 +編譯器在代碼中直接放置，還是作爲庫函數調用實現的一部分）。也就是說， +如果你編譯的代碼不會爲了其他目的使用新指令，則不要僅爲了避免使用這些 +內核輔助代碼，導致二進制程序無法在早期處理器上運行。 + +新的輔助代碼可能隨着時間的推移而增加，所以新內核中的某些輔助代碼在舊 +內核中可能不存在。因此，程序必須在對任何輔助代碼調用假設是安全之前， +檢測 __kuser_helper_version 的值（見下文）。理想情況下，這種檢測應該 +只在進程啓動時執行一次；如果內核版本不支持所需輔助代碼，則該進程可儘早 +中止執行。 + +kuser_helper_version +-------------------- + +位置: 0xffff0ffc + +參考聲明: + + extern int32_t __kuser_helper_version; + +定義: + + 這個區域包含了當前運行內核實現的輔助代碼版本號。用戶空間可以通過讀 + 取此版本號以確定特定的輔助代碼是否存在。 + +使用範例: + +#define __kuser_helper_version (*(int32_t *)0xffff0ffc) + +void check_kuser_version(void) +{ + if (__kuser_helper_version < 2) { + fprintf(stderr, "can't do atomic operations, kernel too old\n"); + abort(); + } +} + +注意: + + 用戶空間可以假設這個域的值不會在任何單個進程的生存期內改變。也就 + 是說，這個域可以僅在庫的初始化階段或進程啓動階段讀取一次。 + +kuser_get_tls +------------- + +位置: 0xffff0fe0 + +參考原型: + + void * __kuser_get_tls(void); + +輸入: + + lr = 返回地址 + +輸出: + + r0 = TLS 值 + +被篡改的寄存器: + + 無 + +定義: + + 獲取之前通過 __ARM_NR_set_tls 系統調用設置的 TLS 值。 + +使用範例: + +typedef void * (__kuser_get_tls_t)(void); +#define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0) + +void foo() +{ + void *tls = __kuser_get_tls(); + printf("TLS = %p\n", tls); +} + +注意: + + - 僅在 __kuser_helper_version >= 1 時，此輔助代碼存在 + （從內核版本 2.6.12 開始）。 + +kuser_cmpxchg +------------- + +位置: 0xffff0fc0 + +參考原型: + + int __kuser_cmpxchg(int32_t oldval, int32_t newval, volatile int32_t *ptr); + +輸入: + + r0 = oldval + r1 = newval + r2 = ptr + lr = 返回地址 + +輸出: + + r0 = 成功代碼 (零或非零) + C flag = 如果 r0 == 0 則置 1，如果 r0 != 0 則清零。 + +被篡改的寄存器: + + r3, ip, flags + +定義: + + 僅在 *ptr 爲 oldval 時原子保存 newval 於 *ptr 中。 + 如果 *ptr 被改變，則返回值爲零，否則爲非零值。 + 如果 *ptr 被改變，則 C flag 也會被置 1，以實現調用代碼中的彙編 + 優化。 + +使用範例: + +typedef int (__kuser_cmpxchg_t)(int oldval, int newval, volatile int *ptr); +#define __kuser_cmpxchg (*(__kuser_cmpxchg_t *)0xffff0fc0) + +int atomic_add(volatile int *ptr, int val) +{ + int old, new; + + do { + old = *ptr; + new = old + val; + } while(__kuser_cmpxchg(old, new, ptr)); + + return new; +} + +注意: + + - 這個例程已根據需要包含了內存屏障。 + + - 僅在 __kuser_helper_version >= 2 時，此輔助代碼存在 + （從內核版本 2.6.12 開始）。 + +kuser_memory_barrier +-------------------- + +位置: 0xffff0fa0 + +參考原型: + + void __kuser_memory_barrier(void); + +輸入: + + lr = 返回地址 + +輸出: + + 無 + +被篡改的寄存器: + + 無 + +定義: + + 應用於任何需要內存屏障以防止手動數據修改帶來的一致性問題，以及 + __kuser_cmpxchg 中。 + +使用範例: + +typedef void (__kuser_dmb_t)(void); +#define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0) + +注意: + + - 僅在 __kuser_helper_version >= 3 時，此輔助代碼存在 + （從內核版本 2.6.15 開始）。 + +kuser_cmpxchg64 +--------------- + +位置: 0xffff0f60 + +參考原型: + + int __kuser_cmpxchg64(const int64_t *oldval, + const int64_t *newval, + volatile int64_t *ptr); + +輸入: + + r0 = 指向 oldval + r1 = 指向 newval + r2 = 指向目標值 + lr = 返回地址 + +輸出: + + r0 = 成功代碼 (零或非零) + C flag = 如果 r0 == 0 則置 1，如果 r0 != 0 則清零。 + +被篡改的寄存器: + + r3, lr, flags + +定義: + + 僅在 *ptr 等於 *oldval 指向的 64 位值時，原子保存 *newval + 指向的 64 位值於 *ptr 中。如果 *ptr 被改變，則返回值爲零， + 否則爲非零值。 + + 如果 *ptr 被改變，則 C flag 也會被置 1，以實現調用代碼中的彙編 + 優化。 + +使用範例: + +typedef int (__kuser_cmpxchg64_t)(const int64_t *oldval, + const int64_t *newval, + volatile int64_t *ptr); +#define __kuser_cmpxchg64 (*(__kuser_cmpxchg64_t *)0xffff0f60) + +int64_t atomic_add64(volatile int64_t *ptr, int64_t val) +{ + int64_t old, new; + + do { + old = *ptr; + new = old + val; + } while(__kuser_cmpxchg64(&old, &new, ptr)); + + return new; +} + +注意: + + - 這個例程已根據需要包含了內存屏障。 + + - 由於這個過程的代碼長度（此輔助代碼跨越 2 個常規的 kuser “槽”）， + 因此 0xffff0f80 不被作爲有效的入口點。 + + - 僅在 __kuser_helper_version >= 5 時，此輔助代碼存在 + （從內核版本 3.1 開始）。 + diff --git a/Documentation/translations/zh_TW/arch/arm64/amu.rst b/Documentation/translations/zh_TW/arch/arm64/amu.rst index f947a6c7369f..1b451eae2bee 100644 --- a/Documentation/translations/zh_TW/arch/arm64/amu.rst +++ b/Documentation/translations/zh_TW/arch/arm64/amu.rst @@ -5,7 +5,7 @@ :Original: :ref:`Documentation/arch/arm64/amu.rst <amu_index>` Translator: Bailu Lin <bailu.lin@vivo.com> - Hu Haowen <src.res@email.cn> + Hu Haowen <src.res.211@gmail.com> ================================== AArch64 Linux 中擴展的活動監控單元 @@ -28,11 +28,11 @@ AArch64 Linux 中擴展的活動監控單元 AMUv1 架構實現了一個由4個固定的64位事件計數器組成的計數器組。 - - CPU 周期計數器：同 CPU 的頻率增長 + - CPU 週期計數器：同 CPU 的頻率增長 - 常量計數器：同固定的系統時鐘頻率增長 - 淘汰指令計數器: 同每次架構指令執行增長 - - 內存停頓周期計數器：計算由在時鐘域內的最後一級緩存中未命中而引起 - 的指令調度停頓周期數 + - 內存停頓週期計數器：計算由在時鐘域內的最後一級緩存中未命中而引起 + 的指令調度停頓週期數 當處於 WFI 或者 WFE 狀態時，計數器不會增長。 diff --git a/Documentation/translations/zh_TW/arch/arm64/booting.txt b/Documentation/translations/zh_TW/arch/arm64/booting.txt index 24817b8b70cd..be0de91ecebd 100644 --- a/Documentation/translations/zh_TW/arch/arm64/booting.txt +++ b/Documentation/translations/zh_TW/arch/arm64/booting.txt @@ -10,7 +10,7 @@ or if there is a problem with the translation. M: Will Deacon <will.deacon@arm.com> zh_CN: Fu Wei <wefu@redhat.com> -zh_TW: Hu Haowen <src.res@email.cn> +zh_TW: Hu Haowen <src.res.211@gmail.com> C: 55f058e7574c3615dea4615573a19bdb258696c6 --------------------------------------------------------------------- Documentation/arch/arm64/booting.rst 的中文翻譯 @@ -23,7 +23,7 @@ Documentation/arch/arm64/booting.rst 的中文翻譯 中文版維護者： 傅煒 Fu Wei <wefu@redhat.com> 中文版翻譯者： 傅煒 Fu Wei <wefu@redhat.com> 中文版校譯者： 傅煒 Fu Wei <wefu@redhat.com> -繁體中文版校譯者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版校譯者： 胡皓文 Hu Haowen <src.res.211@gmail.com> 本文翻譯提交時的 Git 檢出點爲： 55f058e7574c3615dea4615573a19bdb258696c6 以下爲正文 @@ -41,8 +41,8 @@ AArch64 異常模型由多個異常級（EL0 - EL3）組成，對於 EL0 和 EL1 有對應的安全和非安全模式。EL2 是系統管理級，且僅存在於非安全模式下。 EL3 是最高特權級，且僅存在於安全模式下。 -基於本文檔的目的，我們將簡單地使用『引導裝載程序』（『boot loader』） -這個術語來定義在將控制權交給 Linux 內核前 CPU 上執行的所有軟體。 +基於本文檔的目的，我們將簡單地使用‘引導裝載程序’（‘boot loader’） +這個術語來定義在將控制權交給 Linux 內核前 CPU 上執行的所有軟件。 這可能包含安全監控和系統管理代碼，或者它可能只是一些用於準備最小啓動 環境的指令。 @@ -74,7 +74,7 @@ RAM，或可能使用對這個設備已知的 RAM 信息，還可能是引導裝 數據塊將在使能緩存的情況下以 2MB 粒度被映射，故其不能被置於必須以特定 屬性映射的2M區域內。 -註： v4.2 之前的版本同時要求設備樹數據塊被置於從內核映像以下 +注： v4.2 之前的版本同時要求設備樹數據塊被置於從內核映像以下 text_offset 字節處算起第一個 512MB 內。 3、解壓內核映像 @@ -106,7 +106,7 @@ AArch64 內核當前沒有提供自解壓代碼，因此如果使用了壓縮內 u32 res5; /* 保留 （用於 PE COFF 偏移） */ -映像頭注釋： +映像頭註釋： - 自 v3.17 起，除非另有說明，所有域都是小端模式。 @@ -143,7 +143,7 @@ AArch64 內核當前沒有提供自解壓代碼，因此如果使用了壓縮內 字節處，並從該處被調用。2MB 對齊基址和內核映像起始地址之間的區域對於 內核來說沒有特殊意義，且可能被用於其他目的。 從映像起始地址算起，最少必須準備 image_size 字節的空閒內存供內核使用。 -註： v4.6 之前的版本無法使用內核映像物理偏移以下的內存，所以當時建議 +注： v4.6 之前的版本無法使用內核映像物理偏移以下的內存，所以當時建議 將映像儘量放置在靠近系統內存起始的地方。 任何提供給內核的內存（甚至在映像起始地址之前），若未從內核中標記爲保留 @@ -151,7 +151,7 @@ AArch64 內核當前沒有提供自解壓代碼，因此如果使用了壓縮內 在跳轉入內核前，必須符合以下狀態： -- 停止所有 DMA 設備，這樣內存數據就不會因爲虛假網絡包或磁碟數據而 +- 停止所有 DMA 設備，這樣內存數據就不會因爲虛假網絡包或磁盤數據而 被破壞。這可能可以節省你許多的調試時間。 - 主 CPU 通用寄存器設置 @@ -175,7 +175,7 @@ AArch64 內核當前沒有提供自解壓代碼，因此如果使用了壓縮內 而不通過虛擬地址操作維護構架緩存的系統緩存（不推薦），必須被配置且 禁用。 - *譯者註：對於 PoC 以及緩存相關內容，請參考 ARMv8 構架參考手冊 + *譯者注：對於 PoC 以及緩存相關內容，請參考 ARMv8 構架參考手冊 ARM DDI 0487A - 架構計時器 @@ -189,7 +189,7 @@ AArch64 內核當前沒有提供自解壓代碼，因此如果使用了壓縮內 接收。 - 系統寄存器 - 在進入內核映像的異常級中，所有構架中可寫的系統寄存器必須通過軟體 + 在進入內核映像的異常級中，所有構架中可寫的系統寄存器必須通過軟件 在一個更高的異常級別下初始化，以防止在 未知 狀態下運行。 對於擁有 GICv3 中斷控制器並以 v3 模式運行的系統： @@ -214,14 +214,14 @@ AArch64 內核當前沒有提供自解壓代碼，因此如果使用了壓縮內 引導裝載程序必須在每個 CPU 處於以下狀態時跳入內核入口： - 主 CPU 必須直接跳入內核映像的第一條指令。通過此 CPU 傳遞的設備樹 - 數據塊必須在每個 CPU 節點中包含一個 『enable-method』 屬性，所 + 數據塊必須在每個 CPU 節點中包含一個 ‘enable-method’ 屬性，所 支持的 enable-method 請見下文。 引導裝載程序必須生成這些設備樹屬性，並在跳入內核入口之前將其插入 數據塊。 -- enable-method 爲 「spin-table」 的 CPU 必須在它們的 CPU - 節點中包含一個 『cpu-release-addr』 屬性。這個屬性標識了一個 +- enable-method 爲 “spin-table” 的 CPU 必須在它們的 CPU + 節點中包含一個 ‘cpu-release-addr’ 屬性。這個屬性標識了一個 64 位自然對齊且初始化爲零的內存位置。 這些 CPU 必須在內存保留區（通過設備樹中的 /memreserve/ 域傳遞 @@ -231,15 +231,15 @@ AArch64 內核當前沒有提供自解壓代碼，因此如果使用了壓縮內 時，CPU 必須跳入此值所指向的地址。此值爲一個單獨的 64 位小端值， 因此 CPU 須在跳轉前將所讀取的值轉換爲其本身的端模式。 -- enable-method 爲 「psci」 的 CPU 保持在內核外（比如，在 +- enable-method 爲 “psci” 的 CPU 保持在內核外（比如，在 memory 節點中描述爲內核空間的內存區外，或在通過設備樹 /memreserve/ 域中描述爲內核保留區的空間中）。內核將會發起在 ARM 文檔（編號 - ARM DEN 0022A：用於 ARM 上的電源狀態協調接口系統軟體）中描述的 + ARM DEN 0022A：用於 ARM 上的電源狀態協調接口系統軟件）中描述的 CPU_ON 調用來將 CPU 帶入內核。 *譯者注: ARM DEN 0022A 已更新到 ARM DEN 0022C。 - 設備樹必須包含一個 『psci』 節點，請參考以下文檔： + 設備樹必須包含一個 ‘psci’ 節點，請參考以下文檔： Documentation/devicetree/bindings/arm/psci.yaml diff --git a/Documentation/translations/zh_TW/arch/arm64/elf_hwcaps.rst b/Documentation/translations/zh_TW/arch/arm64/elf_hwcaps.rst index fca3c6ff7b93..d2c1c2f23812 100644 --- a/Documentation/translations/zh_TW/arch/arm64/elf_hwcaps.rst +++ b/Documentation/translations/zh_TW/arch/arm64/elf_hwcaps.rst @@ -5,7 +5,7 @@ :Original: :ref:`Documentation/arch/arm64/elf_hwcaps.rst <elf_hwcaps_index>` Translator: Bailu Lin <bailu.lin@vivo.com> - Hu Haowen <src.res@email.cn> + Hu Haowen <src.res.211@gmail.com> ================ ARM64 ELF hwcaps @@ -17,11 +17,11 @@ ARM64 ELF hwcaps 1. 簡介 ------- -有些硬體或軟體功能僅在某些 CPU 實現上和/或在具體某個內核配置上可用，但 +有些硬件或軟件功能僅在某些 CPU 實現上和/或在具體某個內核配置上可用，但 對於處於 EL0 的用戶空間代碼沒有可用的架構發現機制。內核通過在輔助向量表 公開一組稱爲 hwcaps 的標誌而把這些功能暴露給用戶空間。 -用戶空間軟體可以通過獲取輔助向量的 AT_HWCAP 或 AT_HWCAP2 條目來測試功能， +用戶空間軟件可以通過獲取輔助向量的 AT_HWCAP 或 AT_HWCAP2 條目來測試功能， 並測試是否設置了相關標誌，例如:: bool floating_point_is_present(void) @@ -33,7 +33,7 @@ ARM64 ELF hwcaps return false; } -如果軟體依賴於 hwcap 描述的功能，在嘗試使用該功能前則應檢查相關的 hwcap +如果軟件依賴於 hwcap 描述的功能，在嘗試使用該功能前則應檢查相關的 hwcap 標誌以驗證該功能是否存在。 不能通過其他方式探查這些功能。當一個功能不可用時，嘗試使用它可能導致不可 @@ -44,8 +44,8 @@ ARM64 ELF hwcaps ---------------- 大多數 hwcaps 旨在說明通過架構 ID 寄存器(處於 EL0 的用戶空間代碼無法訪問) -描述的功能的存在。這些 hwcap 通過 ID 寄存器欄位定義，並且應根據 ARM 體系 -結構參考手冊（ARM ARM）中定義的欄位來解釋說明。 +描述的功能的存在。這些 hwcap 通過 ID 寄存器字段定義，並且應根據 ARM 體系 +結構參考手冊（ARM ARM）中定義的字段來解釋說明。 這些 hwcaps 以下面的形式描述:: diff --git a/Documentation/translations/zh_TW/arch/arm64/hugetlbpage.rst b/Documentation/translations/zh_TW/arch/arm64/hugetlbpage.rst index 10feb329dfb8..a17858c978d6 100644 --- a/Documentation/translations/zh_TW/arch/arm64/hugetlbpage.rst +++ b/Documentation/translations/zh_TW/arch/arm64/hugetlbpage.rst @@ -5,7 +5,7 @@ :Original: :ref:`Documentation/arch/arm64/hugetlbpage.rst <hugetlbpage_index>` Translator: Bailu Lin <bailu.lin@vivo.com> - Hu Haowen <src.res@email.cn> + Hu Haowen <src.res.211@gmail.com> ===================== ARM64中的 HugeTLBpage diff --git a/Documentation/translations/zh_TW/arch/arm64/index.rst b/Documentation/translations/zh_TW/arch/arm64/index.rst index 68befee14b99..a62b5f06b66c 100644 --- a/Documentation/translations/zh_TW/arch/arm64/index.rst +++ b/Documentation/translations/zh_TW/arch/arm64/index.rst @@ -4,7 +4,7 @@ :Original: :ref:`Documentation/arch/arm64/index.rst <arm64_index>` :Translator: Bailu Lin <bailu.lin@vivo.com> - Hu Haowen <src.res@email.cn> + Hu Haowen <src.res.211@gmail.com> .. _tw_arm64_index: diff --git a/Documentation/translations/zh_TW/arch/arm64/legacy_instructions.txt b/Documentation/translations/zh_TW/arch/arm64/legacy_instructions.txt index 3c915df9836c..7d1f0593d7ca 100644 --- a/Documentation/translations/zh_TW/arch/arm64/legacy_instructions.txt +++ b/Documentation/translations/zh_TW/arch/arm64/legacy_instructions.txt @@ -11,7 +11,7 @@ or if there is a problem with the translation. Maintainer: Punit Agrawal <punit.agrawal@arm.com> Suzuki K. Poulose <suzuki.poulose@arm.com> Chinese maintainer: Fu Wei <wefu@redhat.com> -Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> +Traditional Chinese maintainer: Hu Haowen <src.res.211@gmail.com> --------------------------------------------------------------------- Documentation/arch/arm64/legacy_instructions.rst 的中文翻譯 @@ -26,12 +26,12 @@ Documentation/arch/arm64/legacy_instructions.rst 的中文翻譯 中文版維護者： 傅煒 Fu Wei <wefu@redhat.com> 中文版翻譯者： 傅煒 Fu Wei <wefu@redhat.com> 中文版校譯者： 傅煒 Fu Wei <wefu@redhat.com> -繁體中文版校譯者：胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版校譯者：胡皓文 Hu Haowen <src.res.211@gmail.com> 以下爲正文 --------------------------------------------------------------------- Linux 內核在 arm64 上的移植提供了一個基礎框架，以支持構架中正在被淘汰或已廢棄指令的模擬執行。 -這個基礎框架的代碼使用未定義指令鉤子（hooks）來支持模擬。如果指令存在，它也允許在硬體中啓用該指令。 +這個基礎框架的代碼使用未定義指令鉤子（hooks）來支持模擬。如果指令存在，它也允許在硬件中啓用該指令。 模擬模式可通過寫 sysctl 節點（/proc/sys/abi）來控制。 不同的執行方式及 sysctl 節點的相應值，解釋如下： @@ -42,18 +42,18 @@ Linux 內核在 arm64 上的移植提供了一個基礎框架，以支持構架 * Emulate（模擬） 值： 1 - 使用軟體模擬方式。爲解決軟體遷移問題，這種模擬指令模式的使用是被跟蹤的，並會發出速率限制警告。 + 使用軟件模擬方式。爲解決軟件遷移問題，這種模擬指令模式的使用是被跟蹤的，並會發出速率限制警告。 它是那些構架中正在被淘汰的指令，如 CP15 barriers（隔離指令），的默認處理方式。 -* Hardware Execution（硬體執行） +* Hardware Execution（硬件執行） 值： 2 - 雖然標記爲正在被淘汰，但一些實現可能提供硬體執行這些指令的使能/禁用操作。 - 使用硬體執行一般會有更好的性能，但將無法收集運行時對正被淘汰指令的使用統計數據。 + 雖然標記爲正在被淘汰，但一些實現可能提供硬件執行這些指令的使能/禁用操作。 + 使用硬件執行一般會有更好的性能，但將無法收集運行時對正被淘汰指令的使用統計數據。 默認執行模式依賴於指令在構架中狀態。正在被淘汰的指令應該以模擬（Emulate）作爲默認模式， 而已廢棄的指令必須默認使用未定義（Undef）模式 -注意：指令模擬可能無法應對所有情況。更多詳情請參考單獨的指令注釋。 +注意：指令模擬可能無法應對所有情況。更多詳情請參考單獨的指令註釋。 受支持的遺留指令 ------------- @@ -71,7 +71,7 @@ Linux 內核在 arm64 上的移植提供了一個基礎框架，以支持構架 節點: /proc/sys/abi/setend 狀態: 正被淘汰，不推薦使用 默認執行方式: Emulate (1)* -註：爲了使能這個特性，系統中的所有 CPU 必須在 EL0 支持混合字節序。 +注：爲了使能這個特性，系統中的所有 CPU 必須在 EL0 支持混合字節序。 如果一個新的 CPU （不支持混合字節序） 在使能這個特性後被熱插入系統， 在應用中可能會出現不可預期的結果。 diff --git a/Documentation/translations/zh_TW/arch/arm64/memory.txt b/Documentation/translations/zh_TW/arch/arm64/memory.txt index 2437380a26d8..e41c518e71c6 100644 --- a/Documentation/translations/zh_TW/arch/arm64/memory.txt +++ b/Documentation/translations/zh_TW/arch/arm64/memory.txt @@ -10,7 +10,7 @@ or if there is a problem with the translation. Maintainer: Catalin Marinas <catalin.marinas@arm.com> Chinese maintainer: Fu Wei <wefu@redhat.com> -Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> +Traditional Chinese maintainer: Hu Haowen <src.res.211@gmail.com> --------------------------------------------------------------------- Documentation/arch/arm64/memory.rst 的中文翻譯 @@ -24,21 +24,21 @@ Documentation/arch/arm64/memory.rst 的中文翻譯 中文版維護者： 傅煒 Fu Wei <wefu@redhat.com> 中文版翻譯者： 傅煒 Fu Wei <wefu@redhat.com> 中文版校譯者： 傅煒 Fu Wei <wefu@redhat.com> -繁體中文版校譯者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版校譯者： 胡皓文 Hu Haowen <src.res.211@gmail.com> 以下爲正文 --------------------------------------------------------------------- - Linux 在 AArch64 中的內存布局 + Linux 在 AArch64 中的內存佈局 =========================== 作者: Catalin Marinas <catalin.marinas@arm.com> -本文檔描述 AArch64 Linux 內核所使用的虛擬內存布局。此構架可以實現 +本文檔描述 AArch64 Linux 內核所使用的虛擬內存佈局。此構架可以實現 頁大小爲 4KB 的 4 級轉換表和頁大小爲 64KB 的 3 級轉換表。 AArch64 Linux 使用 3 級或 4 級轉換表，其頁大小配置爲 4KB，對於用戶和內核 分別都有 39-bit (512GB) 或 48-bit (256TB) 的虛擬地址空間。 -對於頁大小爲 64KB的配置，僅使用 2 級轉換表，有 42-bit (4TB) 的虛擬地址空間，但內存布局相同。 +對於頁大小爲 64KB的配置，僅使用 2 級轉換表，有 42-bit (4TB) 的虛擬地址空間，但內存佈局相同。 用戶地址空間的 63:48 位爲 0，而內核地址空間的相應位爲 1。TTBRx 的 選擇由虛擬地址的 63 位給出。swapper_pg_dir 僅包含內核（全局）映射， @@ -46,7 +46,7 @@ AArch64 Linux 使用 3 級或 4 級轉換表，其頁大小配置爲 4KB，對 TTBR1 中，且從不寫入 TTBR0。 -AArch64 Linux 在頁大小爲 4KB，並使用 3 級轉換表時的內存布局： +AArch64 Linux 在頁大小爲 4KB，並使用 3 級轉換表時的內存佈局： 起始地址 結束地址 大小 用途 ----------------------------------------------------------------------- @@ -54,7 +54,7 @@ AArch64 Linux 在頁大小爲 4KB，並使用 3 級轉換表時的內存布局 ffffff8000000000 ffffffffffffffff 512GB 內核空間 -AArch64 Linux 在頁大小爲 4KB，並使用 4 級轉換表時的內存布局： +AArch64 Linux 在頁大小爲 4KB，並使用 4 級轉換表時的內存佈局： 起始地址 結束地址 大小 用途 ----------------------------------------------------------------------- @@ -62,7 +62,7 @@ AArch64 Linux 在頁大小爲 4KB，並使用 4 級轉換表時的內存布局 ffff000000000000 ffffffffffffffff 256TB 內核空間 -AArch64 Linux 在頁大小爲 64KB，並使用 2 級轉換表時的內存布局： +AArch64 Linux 在頁大小爲 64KB，並使用 2 級轉換表時的內存佈局： 起始地址 結束地址 大小 用途 ----------------------------------------------------------------------- @@ -70,7 +70,7 @@ AArch64 Linux 在頁大小爲 64KB，並使用 2 級轉換表時的內存布局 fffffc0000000000 ffffffffffffffff 4TB 內核空間 -AArch64 Linux 在頁大小爲 64KB，並使用 3 級轉換表時的內存布局： +AArch64 Linux 在頁大小爲 64KB，並使用 3 級轉換表時的內存佈局： 起始地址 結束地址 大小 用途 ----------------------------------------------------------------------- @@ -78,7 +78,7 @@ AArch64 Linux 在頁大小爲 64KB，並使用 3 級轉換表時的內存布局 ffff000000000000 ffffffffffffffff 256TB 內核空間 -更詳細的內核虛擬內存布局，請參閱內核啓動信息。 +更詳細的內核虛擬內存佈局，請參閱內核啓動信息。 4KB 頁大小的轉換表查找： diff --git a/Documentation/translations/zh_TW/arch/arm64/perf.rst b/Documentation/translations/zh_TW/arch/arm64/perf.rst index 3b39997a52eb..405d5f66964f 100644 --- a/Documentation/translations/zh_TW/arch/arm64/perf.rst +++ b/Documentation/translations/zh_TW/arch/arm64/perf.rst @@ -5,7 +5,7 @@ :Original: :ref:`Documentation/arch/arm64/perf.rst <perf_index>` Translator: Bailu Lin <bailu.lin@vivo.com> - Hu Haowen <src.res@email.cn> + Hu Haowen <src.res.211@gmail.com> ============= Perf 事件屬性 @@ -59,7 +59,7 @@ EL2（VHE 內核 或 non-VHE 虛擬機監控器）。 KVM 客戶機可能運行在 EL0（用戶空間）和 EL1（內核）。 -由於宿主機和客戶機之間重疊的異常級別，我們不能僅僅依靠 PMU 的硬體異 +由於宿主機和客戶機之間重疊的異常級別，我們不能僅僅依靠 PMU 的硬件異 常過濾機制-因此我們必須啓用/禁用對於客戶機進入和退出的計數。而這在 VHE 和 non-VHE 系統上表現不同。 diff --git a/Documentation/translations/zh_TW/arch/arm64/silicon-errata.txt b/Documentation/translations/zh_TW/arch/arm64/silicon-errata.txt index 66c3a3506458..70371807ca83 100644 --- a/Documentation/translations/zh_TW/arch/arm64/silicon-errata.txt +++ b/Documentation/translations/zh_TW/arch/arm64/silicon-errata.txt @@ -10,7 +10,7 @@ or if there is a problem with the translation. M: Will Deacon <will.deacon@arm.com> zh_CN: Fu Wei <wefu@redhat.com> -zh_TW: Hu Haowen <src.res@email.cn> +zh_TW: Hu Haowen <src.res.211@gmail.com> C: 1926e54f115725a9248d0c4c65c22acaf94de4c4 --------------------------------------------------------------------- Documentation/arch/arm64/silicon-errata.rst 的中文翻譯 @@ -23,44 +23,44 @@ Documentation/arch/arm64/silicon-errata.rst 的中文翻譯 中文版維護者： 傅煒 Fu Wei <wefu@redhat.com> 中文版翻譯者： 傅煒 Fu Wei <wefu@redhat.com> 中文版校譯者： 傅煒 Fu Wei <wefu@redhat.com> -繁體中文版校譯者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版校譯者： 胡皓文 Hu Haowen <src.res.211@gmail.com> 本文翻譯提交時的 Git 檢出點爲： 1926e54f115725a9248d0c4c65c22acaf94de4c4 以下爲正文 --------------------------------------------------------------------- - 晶片勘誤和軟體補救措施 + 芯片勘誤和軟件補救措施 ================== 作者: Will Deacon <will.deacon@arm.com> 日期: 2015年11月27日 -一個不幸的現實：硬體經常帶有一些所謂的「瑕疵（errata）」，導致其在 -某些特定情況下會違背構架定義的行爲。就基於 ARM 的硬體而言，這些瑕疵 +一個不幸的現實：硬件經常帶有一些所謂的“瑕疵（errata）”，導致其在 +某些特定情況下會違背構架定義的行爲。就基於 ARM 的硬件而言，這些瑕疵 大體可分爲以下幾類： A 類：無可行補救措施的嚴重缺陷。 B 類：有可接受的補救措施的重大或嚴重缺陷。 C 類：在正常操作中不會顯現的小瑕疵。 -更多資訊，請在 infocenter.arm.com （需註冊）中查閱「軟體開發者勘誤 -筆記」（「Software Developers Errata Notice」）文檔。 +更多資訊，請在 infocenter.arm.com （需註冊）中查閱“軟件開發者勘誤 +筆記”（“Software Developers Errata Notice”）文檔。 -對於 Linux 而言，B 類缺陷可能需要作業系統的某些特別處理。例如，避免 +對於 Linux 而言，B 類缺陷可能需要操作系統的某些特別處理。例如，避免 一個特殊的代碼序列，或是以一種特定的方式配置處理器。在某種不太常見的 情況下，爲將 A 類缺陷當作 C 類處理，可能需要用類似的手段。這些手段被 -統稱爲「軟體補救措施」，且僅在少數情況需要（例如，那些需要一個運行在 +統稱爲“軟件補救措施”，且僅在少數情況需要（例如，那些需要一個運行在 非安全異常級的補救措施 *並且* 能被 Linux 觸發的情況）。 -對於尚在討論中的可能對未受瑕疵影響的系統產生干擾的軟體補救措施，有一個 -相應的內核配置（Kconfig）選項被加在 「內核特性（Kernel Features）」-> -「基於可選方法框架的 ARM 瑕疵補救措施（ARM errata workarounds via +對於尚在討論中的可能對未受瑕疵影響的系統產生干擾的軟件補救措施，有一個 +相應的內核配置（Kconfig）選項被加在 “內核特性（Kernel Features）”-> +“基於可選方法框架的 ARM 瑕疵補救措施（ARM errata workarounds via the alternatives framework）"。這些選項被默認開啓，若探測到受影響的CPU， 補丁將在運行時被使用。至於對系統運行影響較小的補救措施，內核配置選項 -並不存在，且代碼以某種規避瑕疵的方式被構造（帶注釋爲宜）。 +並不存在，且代碼以某種規避瑕疵的方式被構造（帶註釋爲宜）。 -這種做法對於在任意內核原始碼樹中準確地判斷出哪個瑕疵已被軟體方法所補救 -稍微有點麻煩，所以在 Linux 內核中此文件作爲軟體補救措施的註冊表， -並將在新的軟體補救措施被提交和向後移植（backported）到穩定內核時被更新。 +這種做法對於在任意內核源代碼樹中準確地判斷出哪個瑕疵已被軟件方法所補救 +稍微有點麻煩，所以在 Linux 內核中此文件作爲軟件補救措施的註冊表， +並將在新的軟件補救措施被提交和向後移植（backported）到穩定內核時被更新。 | 實現者 | 受影響的組件 | 勘誤編號 | 內核配置 | +----------------+-----------------+-----------------+-------------------------+ diff --git a/Documentation/translations/zh_TW/arch/arm64/tagged-pointers.txt b/Documentation/translations/zh_TW/arch/arm64/tagged-pointers.txt index b7f683f20ed1..9812d99549ba 100644 --- a/Documentation/translations/zh_TW/arch/arm64/tagged-pointers.txt +++ b/Documentation/translations/zh_TW/arch/arm64/tagged-pointers.txt @@ -10,7 +10,7 @@ or if there is a problem with the translation. Maintainer: Will Deacon <will.deacon@arm.com> Chinese maintainer: Fu Wei <wefu@redhat.com> -Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> +Traditional Chinese maintainer: Hu Haowen <src.res.211@gmail.com> --------------------------------------------------------------------- Documentation/arch/arm64/tagged-pointers.rst 的中文翻譯 @@ -22,7 +22,7 @@ Documentation/arch/arm64/tagged-pointers.rst 的中文翻譯 中文版維護者： 傅煒 Fu Wei <wefu@redhat.com> 中文版翻譯者： 傅煒 Fu Wei <wefu@redhat.com> 中文版校譯者： 傅煒 Fu Wei <wefu@redhat.com> -繁體中文版校譯者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版校譯者： 胡皓文 Hu Haowen <src.res.211@gmail.com> 以下爲正文 --------------------------------------------------------------------- @@ -36,14 +36,14 @@ Documentation/arch/arm64/tagged-pointers.rst 的中文翻譯 AArch64 Linux 中的潛在用途。 內核提供的地址轉換表配置使通過 TTBR0 完成的虛擬地址轉換（即用戶空間 -映射），其虛擬地址的最高 8 位（63:56）會被轉換硬體所忽略。這種機制 -讓這些位可供應用程式自由使用，其注意事項如下： +映射），其虛擬地址的最高 8 位（63:56）會被轉換硬件所忽略。這種機制 +讓這些位可供應用程序自由使用，其注意事項如下： (1) 內核要求所有傳遞到 EL1 的用戶空間地址帶有 0x00 標記。 - 這意味著任何攜帶用戶空間虛擬地址的系統調用（syscall） + 這意味着任何攜帶用戶空間虛擬地址的系統調用（syscall） 參數 *必須* 在陷入內核前使它們的最高字節被清零。 - (2) 非零標記在傳遞信號時不被保存。這意味著在應用程式中利用了 + (2) 非零標記在傳遞信號時不被保存。這意味着在應用程序中利用了 標記的信號處理函數無法依賴 siginfo_t 的用戶空間虛擬 地址所攜帶的包含其內部域信息的標記。此規則的一個例外是 當信號是在調試觀察點的異常處理程序中產生的，此時標記的 @@ -53,5 +53,5 @@ AArch64 Linux 中的潛在用途。 的高字節，C 編譯器很可能無法判斷它們是不同的。 此構架會阻止對帶標記的 PC 指針的利用，因此在異常返回時，其高字節 -將被設置成一個爲 「55」 的擴展符。 +將被設置成一個爲 “55” 的擴展符。 diff --git a/Documentation/translations/zh_TW/arch/index.rst b/Documentation/translations/zh_TW/arch/index.rst new file mode 100644 index 000000000000..7c0490589465 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/index.rst @@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0 + +處理器體系結構 +============== + +以下文檔提供了具體架構實現的編程細節。 + +.. toctree:: + :maxdepth: 2 + + mips/index + arm64/index + openrisc/index + parisc/index + loongarch/index + +TODOList: + +* arm/index +* m68k/index +* nios2/index +* powerpc/index +* s390/index +* sh/index +* sparc/index +* x86/index +* xtensa/index +* ../riscv/index + diff --git a/Documentation/translations/zh_TW/arch/loongarch/booting.rst b/Documentation/translations/zh_TW/arch/loongarch/booting.rst new file mode 100644 index 000000000000..88291090cea1 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/loongarch/booting.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/loongarch/booting.rst + +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +==================== +啓動 Linux/LoongArch +==================== + +:作者: 司延騰 <siyanteng@loongson.cn> +:日期: 2022年11月18日 + +BootLoader傳遞給內核的信息 +========================== + +LoongArch支持ACPI和FDT啓動，需要傳遞給內核的信息包括memmap、initrd、cmdline、可 +選的ACPI/FDT表等。 + +內核在 `kernel_entry` 入口處被傳遞以下參數: + + - a0 = efi_boot: `efi_boot` 是一個標誌，表示這個啓動環境是否完全符合UEFI + 的要求。 + + - a1 = cmdline: `cmdline` 是一個指向內核命令行的指針。 + + - a2 = systemtable: `systemtable` 指向EFI的系統表，在這個階段涉及的所有 + 指針都是物理地址。 + +Linux/LoongArch內核鏡像文件頭 +============================= + +內核鏡像是EFI鏡像。作爲PE文件，它們有一個64字節的頭部結構體，如下所示:: + + u32 MZ_MAGIC /* "MZ", MS-DOS 頭 */ + u32 res0 = 0 /* 保留 */ + u64 kernel_entry /* 內核入口點 */ + u64 _end - _text /* 內核鏡像有效大小 */ + u64 load_offset /* 加載內核鏡像相對內存起始地址的偏移量 */ + u64 res1 = 0 /* 保留 */ + u64 res2 = 0 /* 保留 */ + u64 res3 = 0 /* 保留 */ + u32 LINUX_PE_MAGIC /* 魔術數 */ + u32 pe_header - _head /* 到PE頭的偏移量 */ + diff --git a/Documentation/translations/zh_TW/arch/loongarch/features.rst b/Documentation/translations/zh_TW/arch/loongarch/features.rst new file mode 100644 index 000000000000..b64e430f55ae --- /dev/null +++ b/Documentation/translations/zh_TW/arch/loongarch/features.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/loongarch/features.rst +:Translator: Huacai Chen <chenhuacai@loongson.cn> + +.. kernel-feat:: $srctree/Documentation/features loongarch + diff --git a/Documentation/translations/zh_TW/arch/loongarch/index.rst b/Documentation/translations/zh_TW/arch/loongarch/index.rst new file mode 100644 index 000000000000..7281e050fe1c --- /dev/null +++ b/Documentation/translations/zh_TW/arch/loongarch/index.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/loongarch/index.rst +:Translator: Huacai Chen <chenhuacai@loongson.cn> + +================= +LoongArch體系結構 +================= + +.. toctree:: + :maxdepth: 2 + :numbered: + + introduction + booting + irq-chip-model + + features + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` + diff --git a/Documentation/translations/zh_TW/arch/loongarch/introduction.rst b/Documentation/translations/zh_TW/arch/loongarch/introduction.rst new file mode 100644 index 000000000000..a5603f9b0a1b --- /dev/null +++ b/Documentation/translations/zh_TW/arch/loongarch/introduction.rst @@ -0,0 +1,354 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/loongarch/introduction.rst +:Translator: Huacai Chen <chenhuacai@loongson.cn> + +============= +LoongArch介紹 +============= + +LoongArch是一種新的RISC ISA，在一定程度上類似於MIPS和RISC-V。LoongArch指令集 +包括一個精簡32位版（LA32R）、一個標準32位版（LA32S）、一個64位版（LA64）。 +LoongArch定義了四個特權級（PLV0~PLV3），其中PLV0是最高特權級，用於內核；而PLV3 +是最低特權級，用於應用程序。本文檔介紹了LoongArch的寄存器、基礎指令集、虛擬內 +存以及其他一些主題。 + +寄存器 +====== + +LoongArch的寄存器包括通用寄存器（GPRs）、浮點寄存器（FPRs）、向量寄存器（VRs） +和用於特權模式（PLV0）的控制狀態寄存器（CSRs）。 + +通用寄存器 +---------- + +LoongArch包括32個通用寄存器（ ``$r0`` ~ ``$r31`` ），LA32中每個寄存器爲32位寬， +LA64中每個寄存器爲64位寬。 ``$r0`` 的內容總是固定爲0，而其他寄存器在體系結構層面 +沒有特殊功能。（ ``$r1`` 算是一個例外，在BL指令中固定用作鏈接返回寄存器。） + +內核使用了一套LoongArch寄存器約定，定義在LoongArch ELF psABI規範中，詳細描述參見 +:ref:`參考文獻 <loongarch-references-zh_TW>`: + +================= =============== =================== ========== +寄存器名 別名 用途 跨調用保持 +================= =============== =================== ========== +``$r0`` ``$zero`` 常量0 不使用 +``$r1`` ``$ra`` 返回地址 否 +``$r2`` ``$tp`` TLS/線程信息指針 不使用 +``$r3`` ``$sp`` 棧指針 是 +``$r4``-``$r11`` ``$a0``-``$a7`` 參數寄存器 否 +``$r4``-``$r5`` ``$v0``-``$v1`` 返回值 否 +``$r12``-``$r20`` ``$t0``-``$t8`` 臨時寄存器 否 +``$r21`` ``$u0`` 每CPU變量基地址 不使用 +``$r22`` ``$fp`` 幀指針 是 +``$r23``-``$r31`` ``$s0``-``$s8`` 靜態寄存器 是 +================= =============== =================== ========== + +.. note:: + 注意： ``$r21`` 寄存器在ELF psABI中保留未使用，但是在Linux內核用於保 + 存每CPU變量基地址。該寄存器沒有ABI命名，不過在內核中稱爲 ``$u0`` 。在 + 一些遺留代碼中有時可能見到 ``$v0`` 和 ``$v1`` ，它們是 ``$a0`` 和 + ``$a1`` 的別名，屬於已經廢棄的用法。 + +浮點寄存器 +---------- + +當系統中存在FPU時，LoongArch有32個浮點寄存器（ ``$f0`` ~ ``$f31`` ）。在LA64 +的CPU核上，每個寄存器均爲64位寬。 + +浮點寄存器的使用約定與LoongArch ELF psABI規範的描述相同： + +================= ================== =================== ========== +寄存器名 別名 用途 跨調用保持 +================= ================== =================== ========== +``$f0``-``$f7`` ``$fa0``-``$fa7`` 參數寄存器 否 +``$f0``-``$f1`` ``$fv0``-``$fv1`` 返回值 否 +``$f8``-``$f23`` ``$ft0``-``$ft15`` 臨時寄存器 否 +``$f24``-``$f31`` ``$fs0``-``$fs7`` 靜態寄存器 是 +================= ================== =================== ========== + +.. note:: + 注意：在一些遺留代碼中有時可能見到 ``$fv0`` 和 ``$fv1`` ，它們是 + ``$fa0`` 和 ``$fa1`` 的別名，屬於已經廢棄的用法。 + + +向量寄存器 +---------- + +LoongArch現有兩種向量擴展： + +- 128位向量擴展LSX（全稱Loongson SIMD eXtention）， +- 256位向量擴展LASX（全稱Loongson Advanced SIMD eXtention）。 + +LSX使用 ``$v0`` ~ ``$v31`` 向量寄存器，而LASX則使用 ``$x0`` ~ ``$x31`` 。 + +浮點寄存器和向量寄存器是複用的，比如：在一個實現了LSX和LASX的核上， ``$x0`` 的 +低128位與 ``$v0`` 共用， ``$v0`` 的低64位與 ``$f0`` 共用，其他寄存器依此類推。 + +控制狀態寄存器 +-------------- + +控制狀態寄存器只能在特權模式（PLV0）下訪問: + +================= ==================================== ========== +地址 全稱描述 簡稱 +================= ==================================== ========== +0x0 當前模式信息 CRMD +0x1 異常前模式信息 PRMD +0x2 擴展部件使能 EUEN +0x3 雜項控制 MISC +0x4 異常配置 ECFG +0x5 異常狀態 ESTAT +0x6 異常返回地址 ERA +0x7 出錯(Faulting)虛擬地址 BADV +0x8 出錯(Faulting)指令字 BADI +0xC 異常入口地址 EENTRY +0x10 TLB索引 TLBIDX +0x11 TLB表項高位 TLBEHI +0x12 TLB表項低位0 TLBELO0 +0x13 TLB表項低位1 TLBELO1 +0x18 地址空間標識符 ASID +0x19 低半地址空間頁全局目錄基址 PGDL +0x1A 高半地址空間頁全局目錄基址 PGDH +0x1B 頁全局目錄基址 PGD +0x1C 頁表遍歷控制低半部分 PWCL +0x1D 頁表遍歷控制高半部分 PWCH +0x1E STLB頁大小 STLBPS +0x1F 縮減虛地址配置 RVACFG +0x20 CPU編號 CPUID +0x21 特權資源配置信息1 PRCFG1 +0x22 特權資源配置信息2 PRCFG2 +0x23 特權資源配置信息3 PRCFG3 +0x30+n (0≤n≤15) 數據保存寄存器 SAVEn +0x40 定時器編號 TID +0x41 定時器配置 TCFG +0x42 定時器值 TVAL +0x43 計時器補償 CNTC +0x44 定時器中斷清除 TICLR +0x60 LLBit相關控制 LLBCTL +0x80 實現相關控制1 IMPCTL1 +0x81 實現相關控制2 IMPCTL2 +0x88 TLB重填異常入口地址 TLBRENTRY +0x89 TLB重填異常出錯(Faulting)虛地址 TLBRBADV +0x8A TLB重填異常返回地址 TLBRERA +0x8B TLB重填異常數據保存 TLBRSAVE +0x8C TLB重填異常表項低位0 TLBRELO0 +0x8D TLB重填異常表項低位1 TLBRELO1 +0x8E TLB重填異常表項高位 TLBEHI +0x8F TLB重填異常前模式信息 TLBRPRMD +0x90 機器錯誤控制 MERRCTL +0x91 機器錯誤信息1 MERRINFO1 +0x92 機器錯誤信息2 MERRINFO2 +0x93 機器錯誤異常入口地址 MERRENTRY +0x94 機器錯誤異常返回地址 MERRERA +0x95 機器錯誤異常數據保存 MERRSAVE +0x98 高速緩存標籤 CTAG +0x180+n (0≤n≤3) 直接映射配置窗口n DMWn +0x200+2n (0≤n≤31) 性能監測配置n PMCFGn +0x201+2n (0≤n≤31) 性能監測計數器n PMCNTn +0x300 內存讀寫監視點整體控制 MWPC +0x301 內存讀寫監視點整體狀態 MWPS +0x310+8n (0≤n≤7) 內存讀寫監視點n配置1 MWPnCFG1 +0x311+8n (0≤n≤7) 內存讀寫監視點n配置2 MWPnCFG2 +0x312+8n (0≤n≤7) 內存讀寫監視點n配置3 MWPnCFG3 +0x313+8n (0≤n≤7) 內存讀寫監視點n配置4 MWPnCFG4 +0x380 取指監視點整體控制 FWPC +0x381 取指監視點整體狀態 FWPS +0x390+8n (0≤n≤7) 取指監視點n配置1 FWPnCFG1 +0x391+8n (0≤n≤7) 取指監視點n配置2 FWPnCFG2 +0x392+8n (0≤n≤7) 取指監視點n配置3 FWPnCFG3 +0x393+8n (0≤n≤7) 取指監視點n配置4 FWPnCFG4 +0x500 調試寄存器 DBG +0x501 調試異常返回地址 DERA +0x502 調試數據保存 DSAVE +================= ==================================== ========== + +ERA，TLBRERA，MERRERA和DERA有時也分別稱爲EPC，TLBREPC，MERREPC和DEPC。 + +基礎指令集 +========== + +指令格式 +-------- + +LoongArch的指令字長爲32位，一共有9種基本指令格式（以及一些變體）: + +=========== ========================== +格式名稱 指令構成 +=========== ========================== +2R Opcode + Rj + Rd +3R Opcode + Rk + Rj + Rd +4R Opcode + Ra + Rk + Rj + Rd +2RI8 Opcode + I8 + Rj + Rd +2RI12 Opcode + I12 + Rj + Rd +2RI14 Opcode + I14 + Rj + Rd +2RI16 Opcode + I16 + Rj + Rd +1RI21 Opcode + I21L + Rj + I21H +I26 Opcode + I26L + I26H +=========== ========================== + +Opcode是指令操作碼，Rj和Rk是源操作數（寄存器），Rd是目標操作數（寄存器），Ra是 +4R-type格式特有的附加操作數（寄存器）。I8/I12/I14/I16/I21/I26分別是8位/12位/14位/ +16位/21位/26位的立即數。其中較長的21位和26位立即數在指令字中被分割爲高位部分與低位 +部分，所以你們在這裏的格式描述中能夠看到I21L/I21H和I26L/I26H這樣帶後綴的表述。 + +指令列表 +-------- + +爲了簡便起見，我們在此只羅列一下指令名稱（助記符），需要詳細信息請閱讀 +:ref:`參考文獻 <loongarch-references-zh_TW>` 中的文檔。 + +1. 算術運算指令:: + + ADD.W SUB.W ADDI.W ADD.D SUB.D ADDI.D + SLT SLTU SLTI SLTUI + AND OR NOR XOR ANDN ORN ANDI ORI XORI + MUL.W MULH.W MULH.WU DIV.W DIV.WU MOD.W MOD.WU + MUL.D MULH.D MULH.DU DIV.D DIV.DU MOD.D MOD.DU + PCADDI PCADDU12I PCADDU18I + LU12I.W LU32I.D LU52I.D ADDU16I.D + +2. 移位運算指令:: + + SLL.W SRL.W SRA.W ROTR.W SLLI.W SRLI.W SRAI.W ROTRI.W + SLL.D SRL.D SRA.D ROTR.D SLLI.D SRLI.D SRAI.D ROTRI.D + +3. 位域操作指令:: + + EXT.W.B EXT.W.H CLO.W CLO.D SLZ.W CLZ.D CTO.W CTO.D CTZ.W CTZ.D + BYTEPICK.W BYTEPICK.D BSTRINS.W BSTRINS.D BSTRPICK.W BSTRPICK.D + REVB.2H REVB.4H REVB.2W REVB.D REVH.2W REVH.D BITREV.4B BITREV.8B BITREV.W BITREV.D + MASKEQZ MASKNEZ + +4. 分支轉移指令:: + + BEQ BNE BLT BGE BLTU BGEU BEQZ BNEZ B BL JIRL + +5. 訪存讀寫指令:: + + LD.B LD.BU LD.H LD.HU LD.W LD.WU LD.D ST.B ST.H ST.W ST.D + LDX.B LDX.BU LDX.H LDX.HU LDX.W LDX.WU LDX.D STX.B STX.H STX.W STX.D + LDPTR.W LDPTR.D STPTR.W STPTR.D + PRELD PRELDX + +6. 原子操作指令:: + + LL.W SC.W LL.D SC.D + AMSWAP.W AMSWAP.D AMADD.W AMADD.D AMAND.W AMAND.D AMOR.W AMOR.D AMXOR.W AMXOR.D + AMMAX.W AMMAX.D AMMIN.W AMMIN.D + +7. 柵障指令:: + + IBAR DBAR + +8. 特殊指令:: + + SYSCALL BREAK CPUCFG NOP IDLE ERTN(ERET) DBCL(DBGCALL) RDTIMEL.W RDTIMEH.W RDTIME.D + ASRTLE.D ASRTGT.D + +9. 特權指令:: + + CSRRD CSRWR CSRXCHG + IOCSRRD.B IOCSRRD.H IOCSRRD.W IOCSRRD.D IOCSRWR.B IOCSRWR.H IOCSRWR.W IOCSRWR.D + CACOP TLBP(TLBSRCH) TLBRD TLBWR TLBFILL TLBCLR TLBFLUSH INVTLB LDDIR LDPTE + +虛擬內存 +======== + +LoongArch可以使用直接映射虛擬內存和分頁映射虛擬內存。 + +直接映射虛擬內存通過CSR.DMWn（n=0~3）來進行配置，虛擬地址（VA）和物理地址（PA） +之間有簡單的映射關係:: + + VA = PA + 固定偏移 + +分頁映射的虛擬地址（VA）和物理地址（PA）有任意的映射關係，這種關係記錄在TLB和頁 +表中。LoongArch的TLB包括一個全相聯的MTLB（Multiple Page Size TLB，多樣頁大小TLB） +和一個組相聯的STLB（Single Page Size TLB，單一頁大小TLB）。 + +缺省狀態下，LA32的整個虛擬地址空間配置如下： + +============ =========================== =========================== +區段名 地址範圍 屬性 +============ =========================== =========================== +``UVRANGE`` ``0x00000000 - 0x7FFFFFFF`` 分頁映射, 可緩存, PLV0~3 +``KPRANGE0`` ``0x80000000 - 0x9FFFFFFF`` 直接映射, 非緩存, PLV0 +``KPRANGE1`` ``0xA0000000 - 0xBFFFFFFF`` 直接映射, 可緩存, PLV0 +``KVRANGE`` ``0xC0000000 - 0xFFFFFFFF`` 分頁映射, 可緩存, PLV0 +============ =========================== =========================== + +用戶態（PLV3）只能訪問UVRANGE，對於直接映射的KPRANGE0和KPRANGE1，將虛擬地址的第 +30~31位清零就等於物理地址。例如：物理地址0x00001000對應的非緩存直接映射虛擬地址 +是0x80001000，而其可緩存直接映射虛擬地址是0xA0001000。 + +缺省狀態下，LA64的整個虛擬地址空間配置如下： + +============ ====================== ================================== +區段名 地址範圍 屬性 +============ ====================== ================================== +``XUVRANGE`` ``0x0000000000000000 - 分頁映射, 可緩存, PLV0~3 + 0x3FFFFFFFFFFFFFFF`` +``XSPRANGE`` ``0x4000000000000000 - 直接映射, 可緩存 / 非緩存, PLV0 + 0x7FFFFFFFFFFFFFFF`` +``XKPRANGE`` ``0x8000000000000000 - 直接映射, 可緩存 / 非緩存, PLV0 + 0xBFFFFFFFFFFFFFFF`` +``XKVRANGE`` ``0xC000000000000000 - 分頁映射, 可緩存, PLV0 + 0xFFFFFFFFFFFFFFFF`` +============ ====================== ================================== + +用戶態（PLV3）只能訪問XUVRANGE，對於直接映射的XSPRANGE和XKPRANGE，將虛擬地址的第 +60~63位清零就等於物理地址，而其緩存屬性是通過虛擬地址的第60~61位配置的（0表示強序 +非緩存，1表示一致可緩存，2表示弱序非緩存）。 + +目前，我們僅用XKPRANGE來進行直接映射，XSPRANGE保留給以後用。 + +此處給出一個直接映射的例子：物理地址0x00000000_00001000的強序非緩存直接映射虛擬地址 +（在XKPRANGE中）是0x80000000_00001000，其一致可緩存直接映射虛擬地址（在XKPRANGE中） +是0x90000000_00001000，而其弱序非緩存直接映射虛擬地址（在XKPRANGE中）是0xA0000000_ +00001000。 + +Loongson與LoongArch的關係 +========================= + +LoongArch是一種RISC指令集架構（ISA），不同於現存的任何一種ISA，而Loongson（即龍 +芯）是一個處理器家族。龍芯包括三個系列：Loongson-1（龍芯1號）是32位處理器系列， +Loongson-2（龍芯2號）是低端64位處理器系列，而Loongson-3（龍芯3號）是高端64位處理 +器系列。舊的龍芯處理器基於MIPS架構，而新的龍芯處理器基於LoongArch架構。以龍芯3號 +爲例：龍芯3A1000/3B1500/3A2000/3A3000/3A4000都是兼容MIPS的，而龍芯3A5000（以及將 +來的型號）都是基於LoongArch的。 + +.. _loongarch-references-zh_TW: + +參考文獻 +======== + +Loongson官方網站（龍芯中科技術股份有限公司）： + + http://www.loongson.cn/ + +Loongson與LoongArch的開發者網站（軟件與文檔資源）： + + http://www.loongnix.cn/ + + https://github.com/loongson/ + + https://loongson.github.io/LoongArch-Documentation/ + +LoongArch指令集架構的文檔： + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.02-CN.pdf （中文版） + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.02-EN.pdf （英文版） + +LoongArch的ELF psABI文檔： + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.01-CN.pdf （中文版） + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.01-EN.pdf （英文版） + +Loongson與LoongArch的Linux內核源碼倉庫： + + https://git.kernel.org/pub/scm/linux/kernel/git/chenhuacai/linux-loongson.git + diff --git a/Documentation/translations/zh_TW/arch/loongarch/irq-chip-model.rst b/Documentation/translations/zh_TW/arch/loongarch/irq-chip-model.rst new file mode 100644 index 000000000000..dbe9595bbf16 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/loongarch/irq-chip-model.rst @@ -0,0 +1,158 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/loongarch/irq-chip-model.rst +:Translator: Huacai Chen <chenhuacai@loongson.cn> + +================================== +LoongArch的IRQ芯片模型（層級關係） +================================== + +目前，基於LoongArch的處理器（如龍芯3A5000）只能與LS7A芯片組配合工作。LoongArch計算機 +中的中斷控制器（即IRQ芯片）包括CPUINTC（CPU Core Interrupt Controller）、LIOINTC（ +Legacy I/O Interrupt Controller）、EIOINTC（Extended I/O Interrupt Controller）、 +HTVECINTC（Hyper-Transport Vector Interrupt Controller）、PCH-PIC（LS7A芯片組的主中 +斷控制器）、PCH-LPC（LS7A芯片組的LPC中斷控制器）和PCH-MSI（MSI中斷控制器）。 + +CPUINTC是一種CPU內部的每個核本地的中斷控制器，LIOINTC/EIOINTC/HTVECINTC是CPU內部的 +全局中斷控制器（每個芯片一個，所有核共享），而PCH-PIC/PCH-LPC/PCH-MSI是CPU外部的中 +斷控制器（在配套芯片組裏面）。這些中斷控制器（或者說IRQ芯片）以一種層次樹的組織形式 +級聯在一起，一共有兩種層級關係模型（傳統IRQ模型和擴展IRQ模型）。 + +傳統IRQ模型 +=========== + +在這種模型裏面，IPI（Inter-Processor Interrupt）和CPU本地時鐘中斷直接發送到CPUINTC， +CPU串口（UARTs）中斷髮送到LIOINTC，而其他所有設備的中斷則分別發送到所連接的PCH-PIC/ +PCH-LPC/PCH-MSI，然後被HTVECINTC統一收集，再發送到LIOINTC，最後到達CPUINTC:: + + +-----+ +---------+ +-------+ + | IPI | --> | CPUINTC | <-- | Timer | + +-----+ +---------+ +-------+ + ^ + | + +---------+ +-------+ + | LIOINTC | <-- | UARTs | + +---------+ +-------+ + ^ + | + +-----------+ + | HTVECINTC | + +-----------+ + ^ ^ + | | + +---------+ +---------+ + | PCH-PIC | | PCH-MSI | + +---------+ +---------+ + ^ ^ ^ + | | | + +---------+ +---------+ +---------+ + | PCH-LPC | | Devices | | Devices | + +---------+ +---------+ +---------+ + ^ + | + +---------+ + | Devices | + +---------+ + +擴展IRQ模型 +=========== + +在這種模型裏面，IPI（Inter-Processor Interrupt）和CPU本地時鐘中斷直接發送到CPUINTC， +CPU串口（UARTs）中斷髮送到LIOINTC，而其他所有設備的中斷則分別發送到所連接的PCH-PIC/ +PCH-LPC/PCH-MSI，然後被EIOINTC統一收集，再直接到達CPUINTC:: + + +-----+ +---------+ +-------+ + | IPI | --> | CPUINTC | <-- | Timer | + +-----+ +---------+ +-------+ + ^ ^ + | | + +---------+ +---------+ +-------+ + | EIOINTC | | LIOINTC | <-- | UARTs | + +---------+ +---------+ +-------+ + ^ ^ + | | + +---------+ +---------+ + | PCH-PIC | | PCH-MSI | + +---------+ +---------+ + ^ ^ ^ + | | | + +---------+ +---------+ +---------+ + | PCH-LPC | | Devices | | Devices | + +---------+ +---------+ +---------+ + ^ + | + +---------+ + | Devices | + +---------+ + +ACPI相關的定義 +============== + +CPUINTC:: + + ACPI_MADT_TYPE_CORE_PIC; + struct acpi_madt_core_pic; + enum acpi_madt_core_pic_version; + +LIOINTC:: + + ACPI_MADT_TYPE_LIO_PIC; + struct acpi_madt_lio_pic; + enum acpi_madt_lio_pic_version; + +EIOINTC:: + + ACPI_MADT_TYPE_EIO_PIC; + struct acpi_madt_eio_pic; + enum acpi_madt_eio_pic_version; + +HTVECINTC:: + + ACPI_MADT_TYPE_HT_PIC; + struct acpi_madt_ht_pic; + enum acpi_madt_ht_pic_version; + +PCH-PIC:: + + ACPI_MADT_TYPE_BIO_PIC; + struct acpi_madt_bio_pic; + enum acpi_madt_bio_pic_version; + +PCH-MSI:: + + ACPI_MADT_TYPE_MSI_PIC; + struct acpi_madt_msi_pic; + enum acpi_madt_msi_pic_version; + +PCH-LPC:: + + ACPI_MADT_TYPE_LPC_PIC; + struct acpi_madt_lpc_pic; + enum acpi_madt_lpc_pic_version; + +參考文獻 +======== + +龍芯3A5000的文檔： + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-3A5000-usermanual-1.02-CN.pdf (中文版) + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-3A5000-usermanual-1.02-EN.pdf (英文版) + +龍芯LS7A芯片組的文檔： + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-7A1000-usermanual-2.00-CN.pdf (中文版) + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-7A1000-usermanual-2.00-EN.pdf (英文版) + +.. note:: + - CPUINTC：即《龍芯架構參考手冊卷一》第7.4節所描述的CSR.ECFG/CSR.ESTAT寄存器及其 + 中斷控制邏輯； + - LIOINTC：即《龍芯3A5000處理器使用手冊》第11.1節所描述的“傳統I/O中斷”； + - EIOINTC：即《龍芯3A5000處理器使用手冊》第11.2節所描述的“擴展I/O中斷”； + - HTVECINTC：即《龍芯3A5000處理器使用手冊》第14.3節所描述的“HyperTransport中斷”； + - PCH-PIC/PCH-MSI：即《龍芯7A1000橋片用戶手冊》第5章所描述的“中斷控制器”； + - PCH-LPC：即《龍芯7A1000橋片用戶手冊》第24.3節所描述的“LPC中斷”。 + diff --git a/Documentation/translations/zh_TW/arch/mips/booting.rst b/Documentation/translations/zh_TW/arch/mips/booting.rst new file mode 100644 index 000000000000..7e104abf5a51 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/mips/booting.rst @@ -0,0 +1,35 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/mips/booting.rst + +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +.. _tw_booting: + +BMIPS設備樹引導 +------------------------ + + 一些bootloaders只支持在內核鏡像開始地址處的單一入口點。而其它 + bootloaders將跳轉到ELF的開始地址處。兩種方案都支持的；因爲 + CONFIG_BOOT_RAW=y and CONFIG_NO_EXCEPT_FILL=y, 所以第一條指令 + 會立即跳轉到kernel_entry()入口處執行。 + + 與arch/arm情況(b)類似，dt感知的引導加載程序需要設置以下寄存器: + + a0 : 0 + + a1 : 0xffffffff + + a2 : RAM中指向設備樹塊的物理指針(在chapterII中定義)。 + 設備樹可以位於前512MB物理地址空間(0x00000000 - + 0x1fffffff)的任何位置，以64位邊界對齊。 + + 傳統bootloaders不會使用這樣的約定，並且它們不傳入DT塊。 + 在這種情況下，Linux將通過選中CONFIG_DT_*查找DTB。 + + 以上約定只在32位系統中定義，因爲目前沒有任何64位的BMIPS實現。 + diff --git a/Documentation/translations/zh_TW/arch/mips/features.rst b/Documentation/translations/zh_TW/arch/mips/features.rst new file mode 100644 index 000000000000..f69410420035 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/mips/features.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/mips/features.rst + +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +.. _tw_features: + +.. kernel-feat:: $srctree/Documentation/features mips + diff --git a/Documentation/translations/zh_TW/arch/mips/index.rst b/Documentation/translations/zh_TW/arch/mips/index.rst new file mode 100644 index 000000000000..4b7d28806489 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/mips/index.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/mips/index.rst + +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +=========================== +MIPS特性文檔 +=========================== + +.. toctree:: + :maxdepth: 2 + :numbered: + + booting + ingenic-tcu + + features + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` + diff --git a/Documentation/translations/zh_TW/arch/mips/ingenic-tcu.rst b/Documentation/translations/zh_TW/arch/mips/ingenic-tcu.rst new file mode 100644 index 000000000000..4385c0f3e9cd --- /dev/null +++ b/Documentation/translations/zh_TW/arch/mips/ingenic-tcu.rst @@ -0,0 +1,73 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/mips/ingenic-tcu.rst + +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +.. _tw_ingenic-tcu: + +=============================================== +君正 JZ47xx SoC定時器/計數器硬件單元 +=============================================== + +君正 JZ47xx SoC中的定時器/計數器單元(TCU)是一個多功能硬件塊。它有多達 +8個通道，可以用作計數器，計時器，或脈衝寬度調製器。 + +- JZ4725B, JZ4750, JZ4755 只有６個TCU通道。其它SoC都有８個通道。 + +- JZ4725B引入了一個獨立的通道，稱爲操作系統計時器(OST)。這是一個32位可 + 編程定時器。在JZ4760B及以上型號上，它是64位的。 + +- 每個TCU通道都有自己的時鐘源，可以通過 TCSR 寄存器設置通道的父級時鐘 + 源（pclk、ext、rtc）、開關以及分頻。 + + - 看門狗和OST硬件模塊在它們的寄存器空間中也有相同形式的TCSR寄存器。 + - 用於關閉/開啓的 TCU 寄存器也可以關閉/開啓看門狗和 OST 時鐘。 + +- 每個TCU通道在兩種模式的其中一種模式下運行： + + - 模式 TCU1：通道無法在睡眠模式下運行，但更易於操作。 + - 模式 TCU2：通道可以在睡眠模式下運行，但操作比 TCU1 通道複雜一些。 + +- 每個 TCU 通道的模式取決於使用的SoC： + + - 在最老的SoC（高於JZ4740），八個通道都運行在TCU1模式。 + - 在 JZ4725B，通道5運行在TCU2,其它通道則運行在TCU1。 + - 在最新的SoC（JZ4750及之後），通道1-2運行在TCU2，其它通道則運行 + 在TCU1。 + +- 每個通道都可以生成中斷。有些通道共享一條中斷線，而有些沒有，其在SoC型 + 號之間的變更： + + - 在很老的SoC（JZ4740及更低），通道0和通道1有它們自己的中斷線；通 + 道2-7共享最後一條中斷線。 + - 在 JZ4725B，通道0有它自己的中斷線；通道1-5共享一條中斷線；OST + 使用最後一條中斷線。 + - 在比較新的SoC（JZ4750及以後），通道5有它自己的中斷線；通 + 道0-4和（如果是8通道）6-7全部共享一條中斷線；OST使用最後一條中 + 斷線。 + +實現 +==== + +TCU硬件的功能分佈在多個驅動程序： + +============== =================================== +時鐘 drivers/clk/ingenic/tcu.c +中斷 drivers/irqchip/irq-ingenic-tcu.c +定時器 drivers/clocksource/ingenic-timer.c +OST drivers/clocksource/ingenic-ost.c +脈衝寬度調製器 drivers/pwm/pwm-jz4740.c +看門狗 drivers/watchdog/jz4740_wdt.c +============== =================================== + +因爲可以從相同的寄存器控制屬於不同驅動程序和框架的TCU的各種功能，所以 +所有這些驅動程序都通過相同的控制總線通用接口訪問它們的寄存器。 + +有關TCU驅動程序的設備樹綁定的更多信息，請參閱: +Documentation/devicetree/bindings/timer/ingenic,tcu.yaml. + diff --git a/Documentation/translations/zh_TW/arch/openrisc/index.rst b/Documentation/translations/zh_TW/arch/openrisc/index.rst new file mode 100644 index 000000000000..7585960783fc --- /dev/null +++ b/Documentation/translations/zh_TW/arch/openrisc/index.rst @@ -0,0 +1,33 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/openrisc/index.rst + +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +.. _tw_openrisc_index: + +================= +OpenRISC 體系架構 +================= + +.. toctree:: + :maxdepth: 2 + + openrisc_port + todo + +Todolist: + features + + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` + diff --git a/Documentation/translations/zh_TW/arch/openrisc/openrisc_port.rst b/Documentation/translations/zh_TW/arch/openrisc/openrisc_port.rst new file mode 100644 index 000000000000..422fe9f7a3f2 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/openrisc/openrisc_port.rst @@ -0,0 +1,128 @@ +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/openrisc/openrisc_port.rst + +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +.. _tw_openrisc_port: + +============== +OpenRISC Linux +============== + +這是Linux對OpenRISC類微處理器的移植；具體來說，最早移植目標是32位 +OpenRISC 1000系列（或1k）。 + +關於OpenRISC處理器和正在進行中的開發的信息: + + ======= ============================= + 網站 https://openrisc.io + 郵箱 openrisc@lists.librecores.org + ======= ============================= + +--------------------------------------------------------------------- + +OpenRISC工具鏈和Linux的構建指南 +=============================== + +爲了構建和運行Linux for OpenRISC，你至少需要一個基本的工具鏈，或許 +還需要架構模擬器。 這裏概述了準備就位這些部分的步驟。 + +1) 工具鏈 + +工具鏈二進制文件可以從openrisc.io或我們的github發佈頁面獲得。不同 +工具鏈的構建指南可以在openrisc.io或Stafford的工具鏈構建和發佈腳本 +中找到。 + + ====== ================================================= + 二進制 https://github.com/openrisc/or1k-gcc/releases + 工具鏈 https://openrisc.io/software + 構建 https://github.com/stffrdhrn/or1k-toolchain-build + ====== ================================================= + +2) 構建 + +像往常一樣構建Linux內核:: + + make ARCH=openrisc CROSS_COMPILE="or1k-linux-" defconfig + make ARCH=openrisc CROSS_COMPILE="or1k-linux-" + +3) 在FPGA上運行（可選) + +OpenRISC社區通常使用FuseSoC來管理構建和編程SoC到FPGA中。 下面是用 +OpenRISC SoC對De0 Nano開發板進行編程的一個例子。 在構建過程中， +FPGA RTL是從FuseSoC IP核庫中下載的代碼，並使用FPGA供應商工具構建。 +二進制文件用openocd加載到電路板上。 + +:: + + git clone https://github.com/olofk/fusesoc + cd fusesoc + sudo pip install -e . + + fusesoc init + fusesoc build de0_nano + fusesoc pgm de0_nano + + openocd -f interface/altera-usb-blaster.cfg \ + -f board/or1k_generic.cfg + + telnet localhost 4444 + > init + > halt; load_image vmlinux ; reset + +4) 在模擬器上運行（可選） + +QEMU是一個處理器仿真器，我們推薦它來模擬OpenRISC平臺。 請按照QEMU網 +站上的OpenRISC說明，讓Linux在QEMU上運行。 你可以自己構建QEMU，但你的 +Linux發行版可能提供了支持OpenRISC的二進制包。 + + ============= ====================================================== + qemu openrisc https://wiki.qemu.org/Documentation/Platforms/OpenRISC + ============= ====================================================== + +--------------------------------------------------------------------- + +術語表 +====== + +代碼中使用了以下符號約定以將範圍限制在幾個特定處理器實現上： + +========= ======================= +openrisc: OpenRISC類型處理器 +or1k: OpenRISC 1000系列處理器 +or1200: OpenRISC 1200處理器 +========= ======================= + +--------------------------------------------------------------------- + +歷史 +==== + +2003-11-18 Matjaz Breskvar (phoenix@bsemi.com) + 將linux初步移植到OpenRISC或32架構。 + 所有的核心功能都實現了，並且可以使用。 + +2003-12-08 Matjaz Breskvar (phoenix@bsemi.com) + 徹底改變TLB失誤處理。 + 重寫異常處理。 + 在默認的initrd中實現了sash-3.6的所有功能。 + 大幅改進的版本。 + +2004-04-10 Matjaz Breskvar (phoenix@bsemi.com) + 大量的bug修復。 + 支持以太網，http和telnet服務器功能。 + 可以運行許多標準的linux應用程序。 + +2004-06-26 Matjaz Breskvar (phoenix@bsemi.com) + 移植到2.6.x。 + +2004-11-30 Matjaz Breskvar (phoenix@bsemi.com) + 大量的bug修復和增強功能。 + 增加了opencores framebuffer驅動。 + +2010-10-09 Jonas Bonn (jonas@southpole.se) + 重大重寫，使其與上游的Linux 2.6.36看齊。 + diff --git a/Documentation/translations/zh_TW/arch/openrisc/todo.rst b/Documentation/translations/zh_TW/arch/openrisc/todo.rst new file mode 100644 index 000000000000..df261b9e3002 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/openrisc/todo.rst @@ -0,0 +1,24 @@ +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/openrisc/todo.rst + +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +.. _tw_openrisc_todo.rst: + +======== +待辦事項 +======== + +OpenRISC Linux的移植已經完全投入使用，並且從 2.6.35 開始就一直在上游同步。 +然而，還有一些剩餘的項目需要在未來幾個月內完成。 下面是一個即將進行調查的已知 +不盡完美的項目列表，即我們的待辦事項列表。 + +- 實現其餘的DMA API……dma_map_sg等。 + +- 完成重命名清理工作……代碼中提到了or32，這是架構的一個老名字。 我們 + 已經確定的名字是or1k，這個改變正在以緩慢積累的方式進行。 目前，or32相當 + 於or1k。 + diff --git a/Documentation/translations/zh_TW/arch/parisc/debugging.rst b/Documentation/translations/zh_TW/arch/parisc/debugging.rst new file mode 100644 index 000000000000..c9ee804aebbd --- /dev/null +++ b/Documentation/translations/zh_TW/arch/parisc/debugging.rst @@ -0,0 +1,46 @@ +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/parisc/debugging.rst + +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +.. _tw_parisc_debugging: + +================= +調試PA-RISC +================= + +好吧，這裏有一些關於調試linux/parisc的較底層部分的信息。 + + +1. 絕對地址 +===================== + +很多彙編代碼目前運行在實模式下，這意味着會使用絕對地址，而不是像內核其他 +部分那樣使用虛擬地址。要將絕對地址轉換爲虛擬地址，你可以在System.map中查 +找，添加__PAGE_OFFSET（目前是0x10000000）。 + + +2. HPMCs +======== + +當實模式的代碼試圖訪問不存在的內存時，會出現HPMC（high priority machine +check）而不是內核oops。若要調試HPMC，請嘗試找到系統響應程序/請求程序地址。 +系統請求程序地址應該與（某）處理器的HPA（I/O範圍內的高地址）相匹配；系統響應程 +序地址是實模式代碼試圖訪問的地址。 + +系統響應程序地址的典型值是大於__PAGE_OFFSET （0x10000000）的地址，這意味着 +在實模式試圖訪問它之前，虛擬地址沒有被翻譯成物理地址。 + + +3. 有趣的Q位 +============ + +某些非常關鍵的代碼必須清除PSW中的Q位。當Q位被清除時，CPU不會更新中斷處理 +程序所讀取的寄存器，以找出機器被中斷的位置——所以如果你在清除Q位的指令和再 +次設置Q位的RFI之間遇到中斷，你不知道它到底發生在哪裏。如果你幸運的話，IAOQ +會指向清除Q位的指令，如果你不幸運的話，它會指向任何地方。通常Q位的問題會 +表現爲無法解釋的系統掛起或物理內存越界。 + diff --git a/Documentation/translations/zh_TW/arch/parisc/index.rst b/Documentation/translations/zh_TW/arch/parisc/index.rst new file mode 100644 index 000000000000..35941bf68c88 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/parisc/index.rst @@ -0,0 +1,32 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/parisc/index.rst + +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +.. _tw_parisc_index: + +==================== +PA-RISC體系架構 +==================== + +.. toctree:: + :maxdepth: 2 + + debugging + registers + +Todolist: + + features + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` + diff --git a/Documentation/translations/zh_TW/arch/parisc/registers.rst b/Documentation/translations/zh_TW/arch/parisc/registers.rst new file mode 100644 index 000000000000..695acb21134a --- /dev/null +++ b/Documentation/translations/zh_TW/arch/parisc/registers.rst @@ -0,0 +1,157 @@ +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/parisc/registers.rst + +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +.. _tw_parisc_registers: + +========================= +Linux/PA-RISC的寄存器用法 +========================= + +[ 用星號表示目前尚未實現的計劃用途。 ] + +ABI約定的通用寄存器 +=================== + +控制寄存器 +---------- + +============================ ================================= +CR 0 (恢復計數器) 用於ptrace +CR 1-CR 7(無定義) 未使用 +CR 8 (Protection ID) 每進程值* +CR 9, 12, 13 (PIDS) 未使用 +CR10 (CCR) FPU延遲保存* +CR11 按照ABI的規定（SAR） +CR14 (中斷向量) 初始化爲 fault_vector +CR15 (EIEM) 所有位初始化爲1* +CR16 (間隔計時器) 讀取週期數/寫入開始時間間隔計時器 +CR17-CR22 中斷參數 +CR19 中斷指令寄存器 +CR20 中斷空間寄存器 +CR21 中斷偏移量寄存器 +CR22 中斷 PSW +CR23 (EIRR) 讀取未決中斷/寫入清除位 +CR24 (TR 0) 內核空間頁目錄指針 +CR25 (TR 1) 用戶空間頁目錄指針 +CR26 (TR 2) 不使用 +CR27 (TR 3) 線程描述符指針 +CR28 (TR 4) 不使用 +CR29 (TR 5) 不使用 +CR30 (TR 6) 當前 / 0 +CR31 (TR 7) 臨時寄存器，在不同地方使用 +============================ ================================= + +空間寄存器（內核模式） +---------------------- + +======== ============================== +SR0 臨時空間寄存器 +SR4-SR7 設置爲0 +SR1 臨時空間寄存器 +SR2 內核不應該破壞它 +SR3 用於用戶空間訪問（當前進程） +======== ============================== + +空間寄存器（用戶模式） +---------------------- + +======== ============================ +SR0 臨時空間寄存器 +SR1 臨時空間寄存器 +SR2 保存Linux gateway page的空間 +SR3 在內核中保存用戶地址空間的值 +SR4-SR7 定義了用戶/內核的短地址空間 +======== ============================ + + +處理器狀態字 +------------ + +====================== ================================================ +W （64位地址） 0 +E （小尾端） 0 +S （安全間隔計時器） 0 +T （產生分支陷阱） 0 +H （高特權級陷阱） 0 +L （低特權級陷阱） 0 +N （撤銷下一條指令） 被C代碼使用 +X （數據存儲中斷禁用） 0 +B （產生分支） 被C代碼使用 +C （代碼地址轉譯） 1, 在執行實模式代碼時爲0 +V （除法步長校正） 被C代碼使用 +M （HPMC 掩碼） 0, 在執行HPMC操作*時爲1 +C/B （進/借 位） 被C代碼使用 +O （有序引用） 1* +F （性能監視器） 0 +R （回收計數器陷阱） 0 +Q （收集中斷狀態） 1 （在rfi之前的代碼中爲0） +P （保護標識符） 1* +D （數據地址轉譯） 1, 在執行實模式代碼時爲0 +I （外部中斷掩碼） 由cli()/sti()宏使用。 +====================== ================================================ + +“隱形”寄存器（影子寄存器） +--------------------------- + +============= =================== +PSW W 默認值 0 +PSW E 默認值 0 +影子寄存器 被中斷處理代碼使用 +TOC啓用位 1 +============= =================== + +---------------------------------------------------------- + +PA-RISC架構定義了7個寄存器作爲“影子寄存器”。這些寄存器在 +RETURN FROM INTERRUPTION AND RESTORE指令中使用，通過消 +除中斷處理程序中對一般寄存器（GR）的保存和恢復的需要來減 +少狀態保存和恢復時間。影子寄存器是GRs 1, 8, 9, 16, 17, +24和25。 + +------------------------------------------------------------------------- + +寄存器使用說明，最初由John Marvin提供，並由Randolph Chung提供一些補充說明。 + +對於通用寄存器: + +r1,r2,r19-r26,r28,r29 & r31可以在不保存它們的情況下被使用。當然，如果你 +關心它們，在調用另一個程序之前，你也需要保存它們。上面的一些寄存器確實 +有特殊的含義，你應該注意一下: + + r1: + addil指令是硬性規定將其結果放在r1中，所以如果你使用這條指令要 + 注意這點。 + + r2: + 這就是返回指針。一般來說，你不想使用它，因爲你需要這個指針來返 + 回給你的調用者。然而，它與這組寄存器組合在一起，因爲調用者不能 + 依賴你返回時的值是相同的，也就是說，你可以將r2複製到另一個寄存 + 器，並在作廢r2後通過該寄存器返回，這應該不會給調用程序帶來問題。 + + r19-r22: + 這些通常被認爲是臨時寄存器。 + 請注意，在64位中它們是arg7-arg4。 + + r23-r26: + 這些是arg3-arg0，也就是說，如果你不再關心傳入的值，你可以使用 + 它們。 + + r28,r29: + 這倆是ret0和ret1。它們是你傳入返回值的地方。r28是主返回值。當返回 + 小結構體時，r29也可以用來將數據傳回給調用程序。 + + r30: + 棧指針 + + r31: + ble指令將返回指針放在這裏。 + + + r3-r18,r27,r30需要被保存和恢復。r3-r18只是一般用途的寄存器。 + r27是數據指針，用來使對全局變量的引用更容易。r30是棧指針。 + diff --git a/Documentation/translations/zh_TW/cpu-freq/core.rst b/Documentation/translations/zh_TW/cpu-freq/core.rst index 3d890c2f2a61..4f98d1e9f34b 100644 --- a/Documentation/translations/zh_TW/cpu-freq/core.rst +++ b/Documentation/translations/zh_TW/cpu-freq/core.rst @@ -1,13 +1,15 @@ .. SPDX-License-Identifier: GPL-2.0 - .. include:: ../disclaimer-zh_TW.rst -:Original: :doc:`../../../cpu-freq/core` -:Translator: Yanteng Si <siyanteng@loongson.cn> - Hu Haowen <src.res@email.cn> +:Original: Documentation/cpu-freq/core.rst + +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> -.. _tw_core.rst: +:校譯: + 唐藝舟 Tang Yizhou <tangyeechou@gmail.com> ==================================== CPUFreq核心和CPUFreq通知器的通用說明 @@ -29,10 +31,10 @@ CPUFreq核心和CPUFreq通知器的通用說明 ====================== cpufreq核心代碼位於drivers/cpufreq/cpufreq.c中。這些cpufreq代碼爲CPUFreq架構的驅 -動程序（那些操作硬體切換頻率的代碼）以及 "通知器 "提供了一個標準化的接口。 -這些是設備驅動程序或需要了解策略變化的其它內核部分（如 ACPI 熱量管理）或所有頻率更改（除 -計時代碼外），甚至需要強制確定速度限制的通知器（如 ARM 架構上的 LCD 驅動程序）。 -此外， 內核 "常數" loops_per_jiffy會根據頻率變化而更新。 +動程序（那些執行硬件頻率切換的代碼）以及 "通知器" 提供了一個標準化的接口。 +包括設備驅動程序；需要了解策略變化（如 ACPI 熱量管理），或所有頻率變化（如計時代碼）， +甚至需要強制限制爲指定頻率（如 ARM 架構上的 LCD 驅動程序）的其它內核組件。 +此外，內核 "常數" loops_per_jiffy 會根據頻率變化而更新。 cpufreq策略的引用計數由 cpufreq_cpu_get 和 cpufreq_cpu_put 來完成，以確保 cpufreq 驅 動程序被正確地註冊到核心中，並且驅動程序在 cpufreq_put_cpu 被調用之前不會被卸載。這也保證 @@ -41,10 +43,10 @@ cpufreq策略的引用計數由 cpufreq_cpu_get 和 cpufreq_cpu_put 來完成， 2. CPUFreq 通知器 ==================== -CPUFreq通知器符合標準的內核通知器接口。 +CPUFreq通知器遵循標準的內核通知器接口。 關於通知器的細節請參閱 linux/include/linux/notifier.h。 -這裡有兩個不同的CPUfreq通知器 - 策略通知器和轉換通知器。 +這裏有兩個不同的CPUfreq通知器 - 策略通知器和轉換通知器。 2.1 CPUFreq策略通知器 @@ -62,27 +64,27 @@ CPUFreq通知器符合標準的內核通知器接口。 2.2 CPUFreq轉換通知器 -------------------------------- -當CPUfreq驅動切換CPU核心頻率時，策略中的每個在線CPU都會收到兩次通知，這些變化沒有任何外部干 +當CPUfreq驅動切換CPU核心頻率時，策略中的每個在線CPU都會收到兩次通知，這些變化沒有任何外部幹 預。 第二個參數指定階段 - CPUFREQ_PRECHANGE or CPUFREQ_POSTCHANGE. 第三個參數是一個包含如下值的結構體cpufreq_freqs： -===== ==================== -cpu 受影響cpu的編號 +====== =============================== +policy 指向struct cpufreq_policy的指針 old 舊頻率 new 新頻率 flags cpufreq驅動的標誌 -===== ==================== +====== =============================== 3. 含有Operating Performance Point (OPP)的CPUFreq表的生成 ================================================================== 關於OPP的細節請參閱 Documentation/power/opp.rst dev_pm_opp_init_cpufreq_table - - 這個功能提供了一個隨時可用的轉換程序，用來將OPP層關於可用頻率的內部信息翻譯成一種容易提供給 - cpufreq的格式。 + 這個函數提供了一個隨時可用的轉換例程，用來將OPP層關於可用頻率的內部信息翻譯成一種 + cpufreq易於處理的格式。 .. Warning:: @@ -101,7 +103,7 @@ dev_pm_opp_init_cpufreq_table - .. note:: - 該函數只有在CONFIG_PM_OPP之外還啓用了CONFIG_CPU_FREQ時才可用。 + 該函數只有在CONFIG_PM_OPP之外還啓用了CONFIG_CPU_FREQ時纔可用。 dev_pm_opp_free_cpufreq_table 釋放dev_pm_opp_init_cpufreq_table分配的表。 diff --git a/Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst b/Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst index 2bb8197cd320..add3de2d4523 100644 --- a/Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst +++ b/Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst @@ -2,12 +2,15 @@ .. include:: ../disclaimer-zh_TW.rst -:Original: :doc:`../../../cpu-freq/cpu-drivers` -:Translator: Yanteng Si <siyanteng@loongson.cn> - Hu Haowen <src.res@email.cn> +:Original: Documentation/cpu-freq/cpu-drivers.rst -.. _tw_cpu-drivers.rst: +:翻譯: + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +:校譯: + + 唐藝舟 Tang Yizhou <tangyeechou@gmail.com> ======================================= 如何實現一個新的CPUFreq處理器驅動程序？ @@ -37,15 +40,15 @@ 1. 怎麼做？ =========== -如此，你剛剛得到了一個全新的CPU/晶片組及其數據手冊，並希望爲這個CPU/晶片組添加cpufreq -支持？很好，這裡有一些至關重要的提示： +如果，你剛剛得到了一個全新的CPU/芯片組及其數據手冊，並希望爲這個CPU/芯片組添加cpufreq +支持？很好，這裏有一些至關重要的提示： 1.1 初始化 ---------- -首先，在__initcall_level_7 (module_init())或更靠後的函數中檢查這個內核是否 -運行在正確的CPU和正確的晶片組上。如果是，則使用cpufreq_register_driver()向 +首先，在 __initcall level 7 (module_init())或更靠後的函數中檢查這個內核是否 +運行在正確的CPU和正確的芯片組上。如果是，則使用cpufreq_register_driver()向 CPUfreq核心層註冊一個cpufreq_driver結構體。 結構體cpufreq_driver應該包含什麼成員? @@ -59,11 +62,11 @@ CPUfreq核心層註冊一個cpufreq_driver結構體。 .setpolicy 或 .fast_switch 或 .target 或 .target_index - 差異見 下文。 -並且可選擇 +其它可選成員 - .flags - cpufreq核的提示。 + .flags - 給cpufreq核心的提示。 - .driver_data - cpufreq驅動程序的特定數據。 + .driver_data - cpufreq驅動程序的特有數據。 .get_intermediate 和 target_intermediate - 用於在改變CPU頻率時切換到穩定 的頻率。 @@ -72,18 +75,18 @@ CPUfreq核心層註冊一個cpufreq_driver結構體。 .bios_limit - 返回HW/BIOS對CPU的最大頻率限制值。 - .exit - 一個指向per-policy清理函數的指針，該函數在cpu熱插拔過程的CPU_POST_DEAD + .exit - 一個指向per-policy清理函數的指針，該函數在CPU熱插拔過程的CPU_POST_DEAD 階段被調用。 .suspend - 一個指向per-policy暫停函數的指針，該函數在關中斷且在該策略的調節器停止 後被調用。 - .resume - 一個指向per-policy恢復函數的指針，該函數在關中斷且在調節器再一次開始前被 + .resume - 一個指向per-policy恢復函數的指針，該函數在關中斷且在調節器再一次啓動前被 調用。 .ready - 一個指向per-policy準備函數的指針，該函數在策略完全初始化之後被調用。 - .attr - 一個指向NULL結尾的"struct freq_attr"列表的指針，該函數允許導出值到 + .attr - 一個指向NULL結尾的"struct freq_attr"列表的指針，該列表允許導出值到 sysfs。 .boost_enabled - 如果設置，則啓用提升(boost)頻率。 @@ -94,95 +97,93 @@ CPUfreq核心層註冊一個cpufreq_driver結構體。 1.2 Per-CPU 初始化 ------------------ -每當一個新的CPU被註冊到設備模型中，或者在cpufreq驅動註冊自己之後，如果此CPU的cpufreq策 -略不存在，則會調用per-policy的初始化函數cpufreq_driver.init。請注意，.init()和.exit()程序 -只對策略調用一次，而不是對策略管理的每個CPU調用一次。它需要一個 ``struct cpufreq_policy +每當一個新的CPU被註冊到設備模型中，或者當cpufreq驅動註冊自身之後，如果此CPU的cpufreq策 +略不存在，則會調用per-policy的初始化函數cpufreq_driver.init。請注意，.init()和.exit()例程 +只爲某個策略調用一次，而不是對該策略管理的每個CPU調用一次。它需要一個 ``struct cpufreq_policy *policy`` 作爲參數。現在該怎麼做呢？ 如果有必要，請在你的CPU上激活CPUfreq功能支持。 -然後，驅動程序必須填寫以下數值: +然後，驅動程序必須填寫以下值: +-----------------------------------+--------------------------------------+ -|policy->cpuinfo.min_freq 和 | | -|policy->cpuinfo.max_freq | 該CPU支持的最低和最高頻率（kHz） | -| | | -| | | +|policy->cpuinfo.min_freq和 | 該CPU支持的最低和最高頻率（kHz） | +|policy->cpuinfo.max_freq | | +| | | +-----------------------------------+--------------------------------------+ -|policy->cpuinfo.transition_latency | | -| | CPU在兩個頻率之間切換所需的時間，以 | -| | 納秒爲單位（如適用，否則指定 | -| | CPUFREQ_ETERNAL） | +|policy->cpuinfo.transition_latency | CPU在兩個頻率之間切換所需的時間，以 | +| | 納秒爲單位（如不適用，設定爲 | +| | CPUFREQ_ETERNAL） | +| | | +-----------------------------------+--------------------------------------+ -|policy->cur | 該CPU當前的工作頻率(如適用) | -| | | +|policy->cur | 該CPU當前的工作頻率(如適用) | +| | | +-----------------------------------+--------------------------------------+ -|policy->min, | | -|policy->max, | | -|policy->policy and, if necessary, | | -|policy->governor | 必須包含該cpu的 「默認策略」。稍後 | -| | 會用這些值調用 | -| | cpufreq_driver.verify and either | -| | cpufreq_driver.setpolicy or | -| | cpufreq_driver.target/target_index | -| | | +|policy->min, | 必須包含該CPU的"默認策略"。稍後 | +|policy->max, | 會用這些值調用 | +|policy->policy and, if necessary, | cpufreq_driver.verify和下面函數 | +|policy->governor | 之一：cpufreq_driver.setpolicy或 | +| | cpufreq_driver.target/target_index | +| | | +-----------------------------------+--------------------------------------+ -|policy->cpus | 用與這個CPU一起做DVFS的(在線+離線) | -| | CPU(即與它共享時鐘/電壓軌)的掩碼更新 | -| | 這個 | -| | | +|policy->cpus | 該policy通過DVFS框架影響的全部CPU | +| | (即與本CPU共享"時鐘/電壓"對)構成 | +| | 掩碼(同時包含在線和離線CPU)，用掩碼 | +| | 更新本字段 | +| | | +-----------------------------------+--------------------------------------+ -對於設置其中的一些值(cpuinfo.min[max]_freq, policy->min[max])，頻率表助手可能會有幫 +對於設置其中的一些值(cpuinfo.min[max]_freq, policy->min[max])，頻率表輔助函數可能會有幫 助。關於它們的更多信息，請參見第2節。 1.3 驗證 -------- -當用戶決定設置一個新的策略(由 「policy,governor,min,max組成」)時，必須對這個策略進行驗證， +當用戶決定設置一個新的策略(由"policy,governor,min,max組成")時，必須對這個策略進行驗證， 以便糾正不兼容的值。爲了驗證這些值，cpufreq_verify_within_limits(``struct cpufreq_policy *policy``, ``unsigned int min_freq``, ``unsigned int max_freq``)函數可能會有幫助。 -關於頻率表助手的詳細內容請參見第2節。 +關於頻率表輔助函數的詳細內容請參見第2節。 您需要確保至少有一個有效頻率（或工作範圍）在 policy->min 和 policy->max 範圍內。如果有必 -要，先增加policy->max，只有在沒有辦法的情況下，才減少policy->min。 +要，先增大policy->max，只有在沒有解決方案的情況下，才減小policy->min。 1.4 target 或 target_index 或 setpolicy 或 fast_switch? ------------------------------------------------------- -大多數cpufreq驅動甚至大多數cpu頻率升降算法只允許將CPU頻率設置爲預定義的固定值。對於這些，你 +大多數cpufreq驅動甚至大多數CPU頻率升降算法只允許將CPU頻率設置爲預定義的固定值。對於這些，你 可以使用->target()，->target_index()或->fast_switch()回調。 -有些cpufreq功能的處理器可以自己在某些限制之間切換頻率。這些應使用->setpolicy()回調。 +有些具有硬件調頻能力的處理器可以自行依據某些限制來切換CPU頻率。它們應使用->setpolicy()回調。 1.5. target/target_index ------------------------ -target_index調用有兩個參數：``struct cpufreq_policy * policy``和``unsigned int`` -索引(於列出的頻率表)。 +target_index調用有兩個參數： ``struct cpufreq_policy * policy`` 和 ``unsigned int`` +索引(用於索引頻率表項)。 -當調用這裡時，CPUfreq驅動必須設置新的頻率。實際頻率必須由freq_table[index].frequency決定。 +當調用這裏時，CPUfreq驅動必須設置新的頻率。實際頻率必須由freq_table[index].frequency決定。 -它應該總是在錯誤的情況下恢復到之前的頻率(即policy->restore_freq)，即使我們之前切換到中間頻率。 +在發生錯誤的情況下總是應該恢復到之前的頻率(即policy->restore_freq)，即使我們已經切換到了 +中間頻率。 已棄用 ---------- -目標調用有三個參數。``struct cpufreq_policy * policy``, unsigned int target_frequency, +target調用有三個參數。``struct cpufreq_policy * policy``, unsigned int target_frequency, unsigned int relation. -CPUfreq驅動在調用這裡時必須設置新的頻率。實際的頻率必須使用以下規則來確定。 +CPUfreq驅動在調用這裏時必須設置新的頻率。實際的頻率必須使用以下規則來確定。 -- 緊跟 "目標頻率"。 +- 儘量貼近"目標頻率"。 - policy->min <= new_freq <= policy->max (這必須是有效的!!!) - 如果 relation==CPUFREQ_REL_L，嘗試選擇一個高於或等於 target_freq 的 new_freq。("L代表 最低，但不能低於") - 如果 relation==CPUFREQ_REL_H，嘗試選擇一個低於或等於 target_freq 的 new_freq。("H代表 最高，但不能高於") -這裡，頻率表助手可能會幫助你--詳見第2節。 +這裏，頻率表輔助函數可能會幫助你 -- 詳見第2節。 1.6. fast_switch ---------------- @@ -196,51 +197,52 @@ CPUfreq驅動在調用這裡時必須設置新的頻率。實際的頻率必須 1.7 setpolicy ------------- -setpolicy調用只需要一個``struct cpufreq_policy * policy``作爲參數。需要將處理器內或晶片組內動態頻 +setpolicy調用只需要一個 ``struct cpufreq_policy * policy`` 作爲參數。需要將處理器內或芯片組內動態頻 率切換的下限設置爲policy->min，上限設置爲policy->max，如果支持的話，當policy->policy爲 -CPUFREQ_POLICY_PERFORMANCE時選擇面向性能的設置，當CPUFREQ_POLICY_POWERSAVE時選擇面向省電的設置。 +CPUFREQ_POLICY_PERFORMANCE時選擇面向性能的設置，爲CPUFREQ_POLICY_POWERSAVE時選擇面向省電的設置。 也可以查看drivers/cpufreq/longrun.c中的參考實現。 1.8 get_intermediate 和 target_intermediate -------------------------------------------- -僅適用於 target_index() 和 CPUFREQ_ASYNC_NOTIFICATION 未設置的驅動。 +僅適用於未設置 target_index() 和 CPUFREQ_ASYNC_NOTIFICATION 的驅動。 -get_intermediate應該返回一個平台想要切換到的穩定的中間頻率，target_intermediate()應該將CPU設置爲 -該頻率，然後再跳轉到'index'對應的頻率。核心會負責發送通知，驅動不必在target_intermediate()或 -target_index()中處理。 +get_intermediate應該返回一個平臺想要切換到的穩定的中間頻率，target_intermediate()應該將CPU設置爲 +該頻率，然後再跳轉到'index'對應的頻率。cpufreq核心會負責發送通知，驅動不必在 +target_intermediate()或target_index()中處理它們。 -在驅動程序不想因爲某個目標頻率切換到中間頻率的情況下，它們可以從get_intermediate()中返回'0'。在這種情況 -下，核心將直接調用->target_index()。 +在驅動程序不想爲某個目標頻率切換到中間頻率的情況下，它們可以讓get_intermediate()返回'0'。 +在這種情況下，cpufreq核心將直接調用->target_index()。 -注意：->target_index()應該在失敗的情況下恢復到policy->restore_freq，因爲core會爲此發送通知。 +注意：->target_index()應該在發生失敗的情況下將頻率恢復到policy->restore_freq， +因爲cpufreq核心會爲此發送通知。 -2. 頻率表助手 -============= +2. 頻率表輔助函數 +================= -由於大多數cpufreq處理器只允許被設置爲幾個特定的頻率，因此，一個帶有一些函數的 「頻率表」可能會輔助處理器驅動 -程序的一些工作。這樣的 "頻率表" 由一個cpufreq_frequency_table條目構成的數組組成，"driver_data" 中包 -含了驅動程序的具體數值，"frequency" 中包含了相應的頻率，並設置了標誌。在表的最後，需要添加一個 -cpufreq_frequency_table條目，頻率設置爲CPUFREQ_TABLE_END。而如果想跳過表中的一個條目，則將頻率設置爲 -CPUFREQ_ENTRY_INVALID。這些條目不需要按照任何特定的順序排序，但如果它們是cpufreq 核心會對它們進行快速的DVFS， +由於大多數支持cpufreq的處理器只允許被設置爲幾個特定的頻率，因此，"頻率表"和一些相關函數可能會輔助處理器驅動 +程序的一些工作。這樣的"頻率表"是一個由struct cpufreq_frequency_table的條目構成的數組，"driver_data"成員包 +含驅動程序的專用值，"frequency"成員包含了相應的頻率，此外還有標誌成員。在表的最後，需要添加一個 +cpufreq_frequency_table條目，頻率設置爲CPUFREQ_TABLE_END。如果想跳過表中的一個條目，則將頻率設置爲 +CPUFREQ_ENTRY_INVALID。這些條目不需要按照任何特定的順序排序，如果排序了，cpufreq核心執行DVFS會更快一點， 因爲搜索最佳匹配會更快。 -如果策略在其policy->freq_table欄位中包含一個有效的指針，cpufreq表就會被核心自動驗證。 +如果在policy->freq_table字段中包含一個有效的頻率表指針，頻率表就會被cpufreq核心自動驗證。 cpufreq_frequency_table_verify()保證至少有一個有效的頻率在policy->min和policy->max範圍內，並且所有其他 -標準都被滿足。這對->verify調用很有幫助。 +準則都被滿足。這對->verify調用很有幫助。 -cpufreq_frequency_table_target()是對應於->target階段的頻率表助手。只要把數值傳遞給這個函數，這個函數就會返 +cpufreq_frequency_table_target()是對應於->target階段的頻率表輔助函數。只要把值傳遞給這個函數，這個函數就會返 回包含CPU要設置的頻率的頻率表條目。 -以下宏可以作爲cpufreq_frequency_table的疊代器。 +以下宏可以作爲cpufreq_frequency_table的迭代器。 cpufreq_for_each_entry(pos, table) - 遍歷頻率表的所有條目。 cpufreq_for_each_valid_entry(pos, table) - 該函數遍歷所有條目，不包括CPUFREQ_ENTRY_INVALID頻率。 -使用參數 "pos"-一個``cpufreq_frequency_table * `` 作爲循環變量，使用參數 "table"-作爲你想疊代 -的``cpufreq_frequency_table * `` 。 +使用參數"pos" -- 一個 ``cpufreq_frequency_table *`` 作爲循環指針，使用參數"table" -- 作爲你想迭代 +的 ``cpufreq_frequency_table *`` 。 例如:: @@ -251,6 +253,6 @@ cpufreq_for_each_valid_entry(pos, table) - 該函數遍歷所有條目，不包 pos->frequency = ... } -如果你需要在driver_freq_table中處理pos的位置，不要減去指針，因爲它的代價相當高。相反，使用宏 +如果你需要在driver_freq_table中處理pos的位置，不要做指針減法，因爲它的代價相當高。作爲替代，使用宏 cpufreq_for_each_entry_idx() 和 cpufreq_for_each_valid_entry_idx() 。 diff --git a/Documentation/translations/zh_TW/cpu-freq/cpufreq-stats.rst b/Documentation/translations/zh_TW/cpu-freq/cpufreq-stats.rst index d80bfed50e8c..01ec8c837fe9 100644 --- a/Documentation/translations/zh_TW/cpu-freq/cpufreq-stats.rst +++ b/Documentation/translations/zh_TW/cpu-freq/cpufreq-stats.rst @@ -2,18 +2,21 @@ .. include:: ../disclaimer-zh_TW.rst -:Original: :doc:`../../../cpu-freq/cpufreq-stats` -:Translator: Yanteng Si <siyanteng@loongson.cn> - Hu Haowen <src.res@email.cn> +:Original: Documentation/cpu-freq/cpufreq-stats.rst -.. _tw_cpufreq-stats.rst: +:翻譯: + 司延騰 Yanteng Si <siyanteng@loongson.cn> + +:校譯: + + 唐藝舟 Tang Yizhou <tangyeechou@gmail.com> ========================================== sysfs CPUFreq Stats的一般說明 ========================================== -用戶信息 +爲使用者準備的信息 作者: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> @@ -28,17 +31,16 @@ sysfs CPUFreq Stats的一般說明 1. 簡介 =============== -cpufreq-stats是一個爲每個CPU提供CPU頻率統計的驅動。 -這些統計數據在/sysfs中以一堆只讀接口的形式提供。這個接口（在配置好後）將出現在 -/sysfs（<sysfs root>/devices/system/cpu/cpuX/cpufreq/stats/）中cpufreq下的一個單 -獨的目錄中，提供給每個CPU。 -各種統計數據將在此目錄下形成只讀文件。 +cpufreq-stats是一種爲每個CPU提供CPU頻率統計的驅動。 +這些統計數據以/sysfs中一系列只讀接口的形式呈現。cpufreq-stats接口（若已配置）將爲每個CPU生成 +/sysfs（<sysfs root>/devices/system/cpu/cpuX/cpufreq/stats/）中cpufreq目錄下的stats目錄。 +各項統計數據將在stats目錄下形成對應的只讀文件。 -此驅動是獨立於任何可能運行在你所用CPU上的特定cpufreq_driver而設計的。因此，它將與所有 -cpufreq_driver一起工作。 +此驅動是以獨立於任何可能運行在你所用CPU上的特定cpufreq_driver的方式設計的。因此，它將能和任何 +cpufreq_driver協同工作。 -2. 提供的統計數據(舉例說明) +2. 已提供的統計數據(有例子) ===================================== cpufreq stats提供了以下統計數據（在下面詳細解釋）。 @@ -47,8 +49,8 @@ cpufreq stats提供了以下統計數據（在下面詳細解釋）。 - total_trans - trans_table -所有的統計數據將從統計驅動被載入的時間（或統計被重置的時間）開始，到某一統計數據被讀取的時間爲止。 -顯然，統計驅動不會有任何關於統計驅動載入之前的頻率轉換信息。 +所有統計數據來自以下時間範圍：從統計驅動被加載的時間（或統計數據被重置的時間）開始，到某一統計數據被讀取的時間爲止。 +顯然，統計驅動不會保存它被加載之前的任何頻率轉換信息。 :: @@ -63,14 +65,14 @@ cpufreq stats提供了以下統計數據（在下面詳細解釋）。 - **reset** -只寫屬性，可用於重置統計計數器。這對於評估不同調節器下的系統行爲非常有用，且無需重啓。 +只寫屬性，可用於重置統計計數器。這對於評估不同調節器的系統行爲非常有用，且無需重啓。 - **time_in_state** -此項給出了這個CPU所支持的每個頻率所花費的時間。cat輸出的每一行都會有"<frequency> -<time>"對，表示這個CPU在<frequency>上花費了<time>個usertime單位的時間。這裡的 -usertime單位是10mS（類似於/proc中輸出的其他時間）。 +此文件給出了在本CPU支持的每個頻率上分別花費的時間。cat輸出的每一行都是一個"<frequency> +<time>"對，表示這個CPU在<frequency>上花費了<time>個usertime單位的時間。輸出的每一行對應 +一個CPU支持的頻率。這裏usertime單位是10mS（類似於/proc導出的其它時間）。 :: @@ -84,7 +86,7 @@ usertime單位是10mS（類似於/proc中輸出的其他時間）。 - **total_trans** -給出了這個CPU上頻率轉換的總次數。cat的輸出將有一個單一的計數，這就是頻率轉換的總數。 +此文件給出了這個CPU頻率轉換的總次數。cat的輸出是一個計數值，它就是頻率轉換的總次數。 :: @@ -93,10 +95,10 @@ usertime單位是10mS（類似於/proc中輸出的其他時間）。 - **trans_table** -這將提供所有CPU頻率轉換的細粒度信息。這裡的cat輸出是一個二維矩陣，其中一個條目<i, j>（第 +本文件提供所有CPU頻率轉換的細粒度信息。這裏的cat輸出是一個二維矩陣，其中一個條目<i, j>（第 i行，第j列）代表從Freq_i到Freq_j的轉換次數。Freq_i行和Freq_j列遵循驅動最初提供給cpufreq -核的頻率表的排序順序，因此可以排序（升序或降序）或不排序。 這裡的輸出也包含了每行每列的實際 -頻率值，以便更好地閱讀。 +核心的頻率表的排列順序，因此可以已排序（升序或降序）或未排序。這裏的輸出也包含了實際 +頻率值，分別按行和按列顯示，以便更好地閱讀。 如果轉換表大於PAGE_SIZE，讀取時將返回一個-EFBIG錯誤。 @@ -114,7 +116,7 @@ i行，第j列）代表從Freq_i到Freq_j的轉換次數。Freq_i行和Freq_j列 3. 配置cpufreq-stats ============================ -要在你的內核中配置cpufreq-stats:: +按以下方式在你的內核中配置cpufreq-stats:: Config Main Menu Power management options (ACPI, APM) ---> @@ -123,7 +125,7 @@ i行，第j列）代表從Freq_i到Freq_j的轉換次數。Freq_i行和Freq_j列 [*] CPU frequency translation statistics -"CPU Frequency scaling" (CONFIG_CPU_FREQ) 應該被啓用以配置cpufreq-stats。 +"CPU Frequency scaling" (CONFIG_CPU_FREQ) 應該被啓用，以支持配置cpufreq-stats。 "CPU frequency translation statistics" (CONFIG_CPU_FREQ_STAT)提供了包括 time_in_state、total_trans和trans_table的統計數據。 diff --git a/Documentation/translations/zh_TW/cpu-freq/index.rst b/Documentation/translations/zh_TW/cpu-freq/index.rst index 1a8e680f95ed..a9df16870b21 100644 --- a/Documentation/translations/zh_TW/cpu-freq/index.rst +++ b/Documentation/translations/zh_TW/cpu-freq/index.rst @@ -2,12 +2,13 @@ .. include:: ../disclaimer-zh_TW.rst -:Original: :doc:`../../../cpu-freq/index` -:Translator: Yanteng Si <siyanteng@loongson.cn> - Hu Haowen <src.res@email.cn> +:Original: Documentation/cpu-freq/index.rst -.. _tw_index.rst: +:翻譯: + + 司延騰 Yanteng Si <siyanteng@loongson.cn> +.. _tw_index.rst: ======================================================= Linux CPUFreq - Linux(TM)內核中的CPU頻率和電壓升降代碼 @@ -28,10 +29,10 @@ Author: Dominik Brodowski <linux@brodo.de> 郵件列表 ------------ -這裡有一個 CPU 頻率變化的 CVS 提交和通用列表，您可以在這裡報告bug、問題或提交補丁。要發 +這裏有一個 CPU 頻率變化的 CVS 提交和通用列表，您可以在這裏報告bug、問題或提交補丁。要發 布消息，請發送電子郵件到 linux-pm@vger.kernel.org。 -連結 +鏈接 ----- FTP檔案: * ftp://ftp.linux.org.uk/pub/linux/cpufreq/ diff --git a/Documentation/translations/zh_TW/dev-tools/gcov.rst b/Documentation/translations/zh_TW/dev-tools/gcov.rst new file mode 100644 index 000000000000..ce1c9a97de16 --- /dev/null +++ b/Documentation/translations/zh_TW/dev-tools/gcov.rst @@ -0,0 +1,265 @@ +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/dev-tools/gcov.rst +:Translator: 趙軍奎 Bernard Zhao <bernard@vivo.com> + +在Linux內核裏使用gcov做代碼覆蓋率檢查 +===================================== + +gcov分析核心支持在Linux內核中啓用GCC的覆蓋率測試工具 gcov_ ，Linux內核 +運行時的代碼覆蓋率數據會以gcov兼容的格式導出到“gcov”debugfs目錄中，可 +以通過gcov的 ``-o`` 選項（如下示例）獲得指定文件的代碼運行覆蓋率統計數據 +（需要跳轉到內核編譯路徑下並且要有root權限）:: + + # cd /tmp/linux-out + # gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c + +這將在當前目錄中創建帶有執行計數註釋的源代碼文件。 +在獲得這些統計文件後，可以使用圖形化的gcov前端工具（比如 lcov_ ），來實現 +自動化處理Linux內核的覆蓋率運行數據，同時生成易於閱讀的HTML格式文件。 + +可能的用途: + +* 調試（用來判斷每一行的代碼是否已經運行過） +* 測試改進（如何修改測試代碼，儘可能地覆蓋到沒有運行過的代碼） +* 內核最小化配置（對於某一個選項配置，如果關聯的代碼從來沒有運行過， + 是否還需要這個配置） + +.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html +.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php + + +準備 +---- + +內核打開如下配置:: + + CONFIG_DEBUG_FS=y + CONFIG_GCOV_KERNEL=y + +獲取整個內核的覆蓋率數據，還需要打開:: + + CONFIG_GCOV_PROFILE_ALL=y + +需要注意的是，整個內核開啓覆蓋率統計會造成內核鏡像文件尺寸的增大， +同時內核運行也會變慢一些。 +另外，並不是所有的架構都支持整個內核開啓覆蓋率統計。 + +代碼運行覆蓋率數據只在debugfs掛載完成後纔可以訪問:: + + mount -t debugfs none /sys/kernel/debug + + +定製化 +------ + +如果要單獨針對某一個路徑或者文件進行代碼覆蓋率統計，可以在內核相應路 +徑的Makefile中增加如下的配置: + +- 單獨統計單個文件（例如main.o）:: + + GCOV_PROFILE_main.o := y + +- 單獨統計某一個路徑:: + + GCOV_PROFILE := y + +如果要在整個內核的覆蓋率統計（開啓CONFIG_GCOV_PROFILE_ALL）中單獨排除 +某一個文件或者路徑，可以使用如下的方法:: + + GCOV_PROFILE_main.o := n + +和:: + + GCOV_PROFILE := n + +此機制僅支持鏈接到內核鏡像或編譯爲內核模塊的文件。 + + +相關文件 +-------- + +gcov功能需要在debugfs中創建如下文件: + +``/sys/kernel/debug/gcov`` + gcov相關功能的根路徑 + +``/sys/kernel/debug/gcov/reset`` + 全局復位文件:向該文件寫入數據後會將所有的gcov統計數據清0 + +``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda`` + gcov工具可以識別的覆蓋率統計數據文件，向該文件寫入數據後 + 會將本文件的gcov統計數據清0 + +``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno`` + gcov工具需要的軟連接文件（指向編譯時生成的信息統計文件），這個文件是 + 在gcc編譯時如果配置了選項 ``-ftest-coverage`` 時生成的。 + + +針對模塊的統計 +-------------- + +內核中的模塊會動態的加載和卸載，模塊卸載時對應的數據會被清除掉。 +gcov提供了一種機制，通過保留相關數據的副本來收集這部分卸載模塊的覆蓋率數據。 +模塊卸載後這些備份數據在debugfs中會繼續存在。 +一旦這個模塊重新加載，模塊關聯的運行統計會被初始化成debugfs中備份的數據。 + +可以通過對內核參數gcov_persist的修改來停用gcov對模塊的備份機制:: + + gcov_persist = 0 + +在運行時，用戶還可以通過寫入模塊的數據文件或者寫入gcov復位文件來丟棄已卸 +載模塊的數據。 + + +編譯機和測試機分離 +------------------ + +gcov的內核分析插樁支持內核的編譯和運行是在同一臺機器上，也可以編譯和運 +行是在不同的機器上。 +如果內核編譯和運行是不同的機器，那麼需要額外的準備工作，這取決於gcov工具 +是在哪裏使用的: + +.. _gcov-test_zh: + +a) 若gcov運行在測試機上 + + 測試機上面gcov工具的版本必須要跟內核編譯機器使用的gcc版本相兼容， + 同時下面的文件要從編譯機拷貝到測試機上: + + 從源代碼中: + - 所有的C文件和頭文件 + + 從編譯目錄中: + - 所有的C文件和頭文件 + - 所有的.gcda文件和.gcno文件 + - 所有目錄的鏈接 + + 特別需要注意，測試機器上面的目錄結構跟編譯機器上面的目錄機構必須 + 完全一致。 + 如果文件是軟鏈接，需要替換成真正的目錄文件（這是由make的當前工作 + 目錄變量CURDIR引起的）。 + +.. _gcov-build_zh: + +b) 若gcov運行在編譯機上 + + 測試用例運行結束後，如下的文件需要從測試機中拷貝到編譯機上: + + 從sysfs中的gcov目錄中: + - 所有的.gcda文件 + - 所有的.gcno文件軟鏈接 + + 這些文件可以拷貝到編譯機的任意目錄下，gcov使用-o選項指定拷貝的 + 目錄。 + + 比如一個是示例的目錄結構如下:: + + /tmp/linux: 內核源碼目錄 + /tmp/out: 內核編譯文件路徑（make O=指定） + /tmp/coverage: 從測試機器上面拷貝的數據文件路徑 + + [user@build] cd /tmp/out + [user@build] gcov -o /tmp/coverage/tmp/out/init main.c + + +關於編譯器的注意事項 +-------------------- + +GCC和LLVM gcov工具不一定兼容。 +如果編譯器是GCC，使用 gcov_ 來處理.gcno和.gcda文件，如果是Clang編譯器， +則使用 llvm-cov_ 。 + +.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html +.. _llvm-cov: https://llvm.org/docs/CommandGuide/llvm-cov.html + +GCC和Clang gcov之間的版本差異由Kconfig處理的。 +kconfig會根據編譯工具鏈的檢查自動選擇合適的gcov格式。 + +問題定位 +-------- + +可能出現的問題1 + 編譯到鏈接階段報錯終止 + +問題原因 + 分析標誌指定在了源文件但是沒有鏈接到主內核，或者客製化了鏈接程序 + +解決方法 + 通過在相應的Makefile中使用 ``GCOV_PROFILE := n`` + 或者 ``GCOV_PROFILE_basename.o := n`` 來將鏈接報錯的文件排除掉 + +可能出現的問題2 + 從sysfs複製的文件顯示爲空或不完整 + +問題原因 + 由於seq_file的工作方式，某些工具（例如cp或tar）可能無法正確地從 + sysfs複製文件。 + +解決方法 + 使用 ``cat`` 讀取 ``.gcda`` 文件，使用 ``cp -d`` 複製鏈接，或者使用附錄B + 中所示的機制。 + + +附錄A：collect_on_build.sh +-------------------------- + +用於在編譯機上收集覆蓋率元文件的示例腳本 +（見 :ref:`編譯機和測試機分離 a. <gcov-test_zh>` ） + +.. code-block:: sh + + #!/bin/bash + + KSRC=$1 + KOBJ=$2 + DEST=$3 + + if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then + echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2 + exit 1 + fi + + KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) + KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) + + find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \ + -perm /u+r,g+r | tar cfz $DEST -P -T - + + if [ $? -eq 0 ] ; then + echo "$DEST successfully created, copy to test system and unpack with:" + echo " tar xfz $DEST -P" + else + echo "Could not create file $DEST" + fi + + +附錄B：collect_on_test.sh +------------------------- + +用於在測試機上收集覆蓋率數據文件的示例腳本 +（見 :ref:`編譯機和測試機分離 b. <gcov-build_zh>` ） + +.. code-block:: sh + + #!/bin/bash -e + + DEST=$1 + GCDA=/sys/kernel/debug/gcov + + if [ -z "$DEST" ] ; then + echo "Usage: $0 <output.tar.gz>" >&2 + exit 1 + fi + + TEMPDIR=$(mktemp -d) + echo Collecting data.. + find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \; + find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \; + find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \; + tar czf $DEST -C $TEMPDIR sys + rm -rf $TEMPDIR + + echo "$DEST successfully created, copy to build system and unpack with:" + echo " tar xfz $DEST" + diff --git a/Documentation/translations/zh_TW/dev-tools/gdb-kernel-debugging.rst b/Documentation/translations/zh_TW/dev-tools/gdb-kernel-debugging.rst new file mode 100644 index 000000000000..c881e8872b19 --- /dev/null +++ b/Documentation/translations/zh_TW/dev-tools/gdb-kernel-debugging.rst @@ -0,0 +1,168 @@ +.. highlight:: none + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/dev-tools/gdb-kernel-debugging.rst +:Translator: 高超 gao chao <gaochao49@huawei.com> + +通過gdb調試內核和模塊 +===================== + +Kgdb內核調試器、QEMU等虛擬機管理程序或基於JTAG的硬件接口，支持在運行時使用gdb +調試Linux內核及其模塊。Gdb提供了一個強大的python腳本接口，內核也提供了一套 +輔助腳本以簡化典型的內核調試步驟。本文檔爲如何啓用和使用這些腳本提供了一個簡要的教程。 +此教程基於QEMU/KVM虛擬機，但文中示例也適用於其他gdb stub。 + + +環境配置要求 +------------ + +- gdb 7.2+ (推薦版本: 7.4+) 且開啓python支持 (通常發行版上都已支持) + +設置 +---- + +- 創建一個QEMU/KVM的linux虛擬機（詳情請參考 www.linux-kvm.org 和 www.qemu.org ）。 + 對於交叉開發，https://landley.net/aboriginal/bin 提供了一些鏡像和工具鏈， + 可以幫助搭建交叉開發環境。 + +- 編譯內核時開啓CONFIG_GDB_SCRIPTS，關閉CONFIG_DEBUG_INFO_REDUCED。 + 如果架構支持CONFIG_FRAME_POINTER，請保持開啓。 + +- 在guest環境上安裝該內核。如有必要，通過在內核command line中添加“nokaslr”來關閉KASLR。 + 此外，QEMU允許通過-kernel、-append、-initrd這些命令行選項直接啓動內核。 + 但這通常僅在不依賴內核模塊時纔有效。有關此模式的更多詳細信息，請參閱QEMU文檔。 + 在這種情況下，如果架構支持KASLR，應該在禁用CONFIG_RANDOMIZE_BASE的情況下構建內核。 + +- 啓用QEMU/KVM的gdb stub，可以通過如下方式實現 + + - 在VM啓動時，通過在QEMU命令行中添加“-s”參數 + + 或 + + - 在運行時通過從QEMU監視控制檯發送“gdbserver” + +- 切換到/path/to/linux-build(內核源碼編譯)目錄 + +- 啓動gdb：gdb vmlinux + + 注意：某些發行版可能會將gdb腳本的自動加載限制在已知的安全目錄中。 + 如果gdb報告拒絕加載vmlinux-gdb.py（相關命令找不到），請將:: + + add-auto-load-safe-path /path/to/linux-build + + 添加到~/.gdbinit。更多詳細信息，請參閱gdb幫助信息。 + +- 連接到已啓動的guest環境:: + + (gdb) target remote :1234 + + +使用Linux提供的gdb腳本的示例 +---------------------------- + +- 加載模塊（以及主內核）符號:: + + (gdb) lx-symbols + loading vmlinux + scanning for modules in /home/user/linux/build + loading @0xffffffffa0020000: /home/user/linux/build/net/netfilter/xt_tcpudp.ko + loading @0xffffffffa0016000: /home/user/linux/build/net/netfilter/xt_pkttype.ko + loading @0xffffffffa0002000: /home/user/linux/build/net/netfilter/xt_limit.ko + loading @0xffffffffa00ca000: /home/user/linux/build/net/packet/af_packet.ko + loading @0xffffffffa003c000: /home/user/linux/build/fs/fuse/fuse.ko + ... + loading @0xffffffffa0000000: /home/user/linux/build/drivers/ata/ata_generic.ko + +- 對一些尚未加載的模塊中的函數函數設置斷點，例如:: + + (gdb) b btrfs_init_sysfs + Function "btrfs_init_sysfs" not defined. + Make breakpoint pending on future shared library load? (y or [n]) y + Breakpoint 1 (btrfs_init_sysfs) pending. + +- 繼續執行:: + + (gdb) c + +- 加載模塊並且能觀察到正在加載的符號以及斷點命中:: + + loading @0xffffffffa0034000: /home/user/linux/build/lib/libcrc32c.ko + loading @0xffffffffa0050000: /home/user/linux/build/lib/lzo/lzo_compress.ko + loading @0xffffffffa006e000: /home/user/linux/build/lib/zlib_deflate/zlib_deflate.ko + loading @0xffffffffa01b1000: /home/user/linux/build/fs/btrfs/btrfs.ko + + Breakpoint 1, btrfs_init_sysfs () at /home/user/linux/fs/btrfs/sysfs.c:36 + 36 btrfs_kset = kset_create_and_add("btrfs", NULL, fs_kobj); + +- 查看內核的日誌緩衝區:: + + (gdb) lx-dmesg + [ 0.000000] Initializing cgroup subsys cpuset + [ 0.000000] Initializing cgroup subsys cpu + [ 0.000000] Linux version 3.8.0-rc4-dbg+ (... + [ 0.000000] Command line: root=/dev/sda2 resume=/dev/sda1 vga=0x314 + [ 0.000000] e820: BIOS-provided physical RAM map: + [ 0.000000] BIOS-e820: [mem 0x0000000000000000-0x000000000009fbff] usable + [ 0.000000] BIOS-e820: [mem 0x000000000009fc00-0x000000000009ffff] reserved + .... + +- 查看當前task struct結構體的字段（僅x86和arm64支持）:: + + (gdb) p $lx_current().pid + $1 = 4998 + (gdb) p $lx_current().comm + $2 = "modprobe\000\000\000\000\000\000\000" + +- 對當前或指定的CPU使用per-cpu函數:: + + (gdb) p $lx_per_cpu("runqueues").nr_running + $3 = 1 + (gdb) p $lx_per_cpu("runqueues", 2).nr_running + $4 = 0 + +- 使用container_of查看更多hrtimers信息:: + + (gdb) set $next = $lx_per_cpu("hrtimer_bases").clock_base[0].active.next + (gdb) p *$container_of($next, "struct hrtimer", "node") + $5 = { + node = { + node = { + __rb_parent_color = 18446612133355256072, + rb_right = 0x0 <irq_stack_union>, + rb_left = 0x0 <irq_stack_union> + }, + expires = { + tv64 = 1835268000000 + } + }, + _softexpires = { + tv64 = 1835268000000 + }, + function = 0xffffffff81078232 <tick_sched_timer>, + base = 0xffff88003fd0d6f0, + state = 1, + start_pid = 0, + start_site = 0xffffffff81055c1f <hrtimer_start_range_ns+20>, + start_comm = "swapper/2\000\000\000\000\000\000" + } + + +命令和輔助調試功能列表 +---------------------- + +命令和輔助調試功能可能會隨着時間的推移而改進，此文顯示的是初始版本的部分示例:: + + (gdb) apropos lx + function lx_current -- Return current task + function lx_module -- Find module by name and return the module variable + function lx_per_cpu -- Return per-cpu variable + function lx_task_by_pid -- Find Linux task by PID and return the task_struct variable + function lx_thread_info -- Calculate Linux thread_info from task variable + lx-dmesg -- Print Linux kernel log buffer + lx-lsmod -- List currently loaded modules + lx-symbols -- (Re-)load symbols of Linux kernel and currently loaded modules + +可以通過“help <command-name>”或“help function <function-name>”命令 +獲取指定命令或指定調試功能的更多詳細信息。 + diff --git a/Documentation/translations/zh_TW/dev-tools/index.rst b/Documentation/translations/zh_TW/dev-tools/index.rst new file mode 100644 index 000000000000..0d38e5f80e54 --- /dev/null +++ b/Documentation/translations/zh_TW/dev-tools/index.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/dev-tools/index.rst +:Translator: 趙軍奎 Bernard Zhao <bernard@vivo.com> + +============ +內核開發工具 +============ + +本文檔是有關內核開發工具文檔的合集。 +目前這些文檔已經整理在一起，不需要再花費額外的精力。 +歡迎任何補丁。 + +有關測試專用工具的簡要概述，參見 +Documentation/translations/zh_TW/dev-tools/testing-overview.rst + +.. class:: toc-title + + 目錄 + +.. toctree:: + :maxdepth: 2 + + testing-overview + sparse + gcov + kasan + gdb-kernel-debugging + +Todolist: + + - coccinelle + - kcov + - ubsan + - kmemleak + - kcsan + - kfence + - kgdb + - kselftest + - kunit/index + diff --git a/Documentation/translations/zh_TW/dev-tools/kasan.rst b/Documentation/translations/zh_TW/dev-tools/kasan.rst new file mode 100644 index 000000000000..979eb84bc58f --- /dev/null +++ b/Documentation/translations/zh_TW/dev-tools/kasan.rst @@ -0,0 +1,463 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/dev-tools/kasan.rst +:Translator: 萬家兵 Wan Jiabing <wanjiabing@vivo.com> + +內核地址消毒劑(KASAN) +===================== + +概述 +---- + +Kernel Address SANitizer(KASAN)是一種動態內存安全錯誤檢測工具，主要功能是 +檢查內存越界訪問和使用已釋放內存的問題。 + +KASAN有三種模式: + +1. 通用KASAN +2. 基於軟件標籤的KASAN +3. 基於硬件標籤的KASAN + +用CONFIG_KASAN_GENERIC啓用的通用KASAN，是用於調試的模式，類似於用戶空 +間的ASan。這種模式在許多CPU架構上都被支持，但它有明顯的性能和內存開銷。 + +基於軟件標籤的KASAN或SW_TAGS KASAN，通過CONFIG_KASAN_SW_TAGS啓用， +可以用於調試和自我測試，類似於用戶空間HWASan。這種模式只支持arm64，但其 +適度的內存開銷允許在內存受限的設備上用真實的工作負載進行測試。 + +基於硬件標籤的KASAN或HW_TAGS KASAN，用CONFIG_KASAN_HW_TAGS啓用，被 +用作現場內存錯誤檢測器或作爲安全緩解的模式。這種模式只在支持MTE（內存標籤 +擴展）的arm64 CPU上工作，但它的內存和性能開銷很低，因此可以在生產中使用。 + +關於每種KASAN模式的內存和性能影響的細節，請參見相應的Kconfig選項的描述。 + +通用模式和基於軟件標籤的模式通常被稱爲軟件模式。基於軟件標籤的模式和基於 +硬件標籤的模式被稱爲基於標籤的模式。 + +支持 +---- + +體系架構 +~~~~~~~~ + +在x86_64、arm、arm64、powerpc、riscv、s390、xtensa和loongarch上支持通用KASAN， +而基於標籤的KASAN模式只在arm64上支持。 + +編譯器 +~~~~~~ + +軟件KASAN模式使用編譯時工具在每個內存訪問之前插入有效性檢查，因此需要一個 +提供支持的編譯器版本。基於硬件標籤的模式依靠硬件來執行這些檢查，但仍然需要 +一個支持內存標籤指令的編譯器版本。 + +通用KASAN需要GCC 8.3.0版本或更高版本，或者內核支持的任何Clang版本。 + +基於軟件標籤的KASAN需要GCC 11+或者內核支持的任何Clang版本。 + +基於硬件標籤的KASAN需要GCC 10+或Clang 12+。 + +內存類型 +~~~~~~~~ + +通用KASAN支持在所有的slab、page_alloc、vmap、vmalloc、堆棧和全局內存 +中查找錯誤。 + +基於軟件標籤的KASAN支持slab、page_alloc、vmalloc和堆棧內存。 + +基於硬件標籤的KASAN支持slab、page_alloc和不可執行的vmalloc內存。 + +對於slab，兩種軟件KASAN模式都支持SLUB和SLAB分配器，而基於硬件標籤的 +KASAN只支持SLUB。 + +用法 +---- + +要啓用KASAN，請使用以下命令配置內核:: + + CONFIG_KASAN=y + +同時在 ``CONFIG_KASAN_GENERIC`` (啓用通用KASAN模式)， ``CONFIG_KASAN_SW_TAGS`` +(啓用基於硬件標籤的KASAN模式)，和 ``CONFIG_KASAN_HW_TAGS`` (啓用基於硬件標籤 +的KASAN模式)之間進行選擇。 + +對於軟件模式，還可以在 ``CONFIG_KASAN_OUTLINE`` 和 ``CONFIG_KASAN_INLINE`` +之間進行選擇。outline和inline是編譯器插樁類型。前者產生較小的二進制文件， +而後者快2倍。 + +要將受影響的slab對象的alloc和free堆棧跟蹤包含到報告中，請啓用 +``CONFIG_STACKTRACE`` 。要包括受影響物理頁面的分配和釋放堆棧跟蹤的話， +請啓用 ``CONFIG_PAGE_OWNER`` 並使用 ``page_owner=on`` 進行引導。 + +啓動參數 +~~~~~~~~ + +KASAN受到通用 ``panic_on_warn`` 命令行參數的影響。當它被啓用時，KASAN +在打印出錯誤報告後會使內核恐慌。 + +默認情況下，KASAN只對第一個無效的內存訪問打印錯誤報告。使用 +``kasan_multi_shot``，KASAN對每一個無效的訪問都打印一份報告。這會禁用 +了KASAN報告的 ``panic_on_warn``。 + +另外，獨立於 ``panic_on_warn`` 、 ``kasan.fault=`` boot參數可以用 +來控制恐慌和報告行爲。 + +- ``kasan.fault=report`` 或 ``=panic`` 控制是否只打印KASAN report或 + 同時使內核恐慌（默認： ``report`` ）。即使 ``kasan_multi_shot`` 被 + 啓用，恐慌也會發生。 + +基於軟件和硬件標籤的KASAN模式（見下面關於各種模式的部分）支持改變堆棧跟 +蹤收集行爲： + +- ``kasan.stacktrace=off`` 或 ``=on`` 禁用或啓用分配和釋放堆棧痕 + 跡的收集（默認： ``on`` ）。 + +- ``kasan.stack_ring_size=<number of entries>`` 指定堆棧環的條 + 目數（默認： ``32768`` ）。 + +基於硬件標籤的KASAN模式是爲了在生產中作爲一種安全緩解措施使用。因此，它 +支持額外的啓動參數，允許完全禁用KASAN或控制其功能。 + +- ``kasan=off`` 或 ``=on`` 控制KASAN是否被啓用（默認： ``on`` ）。 + +- ``kasan.mode=sync``, ``=async`` or ``=asymm`` 控制KASAN是否 + 被配置爲同步、異步或非對稱的執行模式（默認： ``同步`` ）。 + 同步模式：當標籤檢查異常發生時，會立即檢測到不良訪問。 + 異步模式：不良訪問的檢測是延遲的。當標籤檢查異常發生時，信息被存儲在硬 + 件中（對於arm64來說是在TFSR_EL1寄存器中）。內核週期性地檢查硬件，並\ + 且只在這些檢查中報告標籤異常。 + 非對稱模式：讀取時同步檢測不良訪問，寫入時異步檢測。 + +- ``kasan.vmalloc=off`` or ``=on`` 禁用或啓用vmalloc分配的標記（默認： ``on`` ）。 + +錯誤報告 +~~~~~~~~ + +典型的KASAN報告如下所示:: + + ================================================================== + BUG: KASAN: slab-out-of-bounds in kmalloc_oob_right+0xa8/0xbc [test_kasan] + Write of size 1 at addr ffff8801f44ec37b by task insmod/2760 + + CPU: 1 PID: 2760 Comm: insmod Not tainted 4.19.0-rc3+ #698 + Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.10.2-1 04/01/2014 + Call Trace: + dump_stack+0x94/0xd8 + print_address_description+0x73/0x280 + kasan_report+0x144/0x187 + __asan_report_store1_noabort+0x17/0x20 + kmalloc_oob_right+0xa8/0xbc [test_kasan] + kmalloc_tests_init+0x16/0x700 [test_kasan] + do_one_initcall+0xa5/0x3ae + do_init_module+0x1b6/0x547 + load_module+0x75df/0x8070 + __do_sys_init_module+0x1c6/0x200 + __x64_sys_init_module+0x6e/0xb0 + do_syscall_64+0x9f/0x2c0 + entry_SYSCALL_64_after_hwframe+0x44/0xa9 + RIP: 0033:0x7f96443109da + RSP: 002b:00007ffcf0b51b08 EFLAGS: 00000202 ORIG_RAX: 00000000000000af + RAX: ffffffffffffffda RBX: 000055dc3ee521a0 RCX: 00007f96443109da + RDX: 00007f96445cff88 RSI: 0000000000057a50 RDI: 00007f9644992000 + RBP: 000055dc3ee510b0 R08: 0000000000000003 R09: 0000000000000000 + R10: 00007f964430cd0a R11: 0000000000000202 R12: 00007f96445cff88 + R13: 000055dc3ee51090 R14: 0000000000000000 R15: 0000000000000000 + + Allocated by task 2760: + save_stack+0x43/0xd0 + kasan_kmalloc+0xa7/0xd0 + kmem_cache_alloc_trace+0xe1/0x1b0 + kmalloc_oob_right+0x56/0xbc [test_kasan] + kmalloc_tests_init+0x16/0x700 [test_kasan] + do_one_initcall+0xa5/0x3ae + do_init_module+0x1b6/0x547 + load_module+0x75df/0x8070 + __do_sys_init_module+0x1c6/0x200 + __x64_sys_init_module+0x6e/0xb0 + do_syscall_64+0x9f/0x2c0 + entry_SYSCALL_64_after_hwframe+0x44/0xa9 + + Freed by task 815: + save_stack+0x43/0xd0 + __kasan_slab_free+0x135/0x190 + kasan_slab_free+0xe/0x10 + kfree+0x93/0x1a0 + umh_complete+0x6a/0xa0 + call_usermodehelper_exec_async+0x4c3/0x640 + ret_from_fork+0x35/0x40 + + The buggy address belongs to the object at ffff8801f44ec300 + which belongs to the cache kmalloc-128 of size 128 + The buggy address is located 123 bytes inside of + 128-byte region [ffff8801f44ec300, ffff8801f44ec380) + The buggy address belongs to the page: + page:ffffea0007d13b00 count:1 mapcount:0 mapping:ffff8801f7001640 index:0x0 + flags: 0x200000000000100(slab) + raw: 0200000000000100 ffffea0007d11dc0 0000001a0000001a ffff8801f7001640 + raw: 0000000000000000 0000000080150015 00000001ffffffff 0000000000000000 + page dumped because: kasan: bad access detected + + Memory state around the buggy address: + ffff8801f44ec200: fc fc fc fc fc fc fc fc fb fb fb fb fb fb fb fb + ffff8801f44ec280: fb fb fb fb fb fb fb fb fc fc fc fc fc fc fc fc + >ffff8801f44ec300: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 03 + ^ + ffff8801f44ec380: fc fc fc fc fc fc fc fc fb fb fb fb fb fb fb fb + ffff8801f44ec400: fb fb fb fb fb fb fb fb fc fc fc fc fc fc fc fc + ================================================================== + +報告標題總結了發生的錯誤類型以及導致該錯誤的訪問類型。緊隨其後的是錯誤訪問的 +堆棧跟蹤、所訪問內存分配位置的堆棧跟蹤（對於訪問了slab對象的情況）以及對象 +被釋放的位置的堆棧跟蹤（對於訪問已釋放內存的問題報告）。接下來是對訪問的 +slab對象的描述以及關於訪問的內存頁的信息。 + +最後，報告展示了訪問地址周圍的內存狀態。在內部，KASAN單獨跟蹤每個內存顆粒的 +內存狀態，根據KASAN模式分爲8或16個對齊字節。報告的內存狀態部分中的每個數字 +都顯示了圍繞訪問地址的其中一個內存顆粒的狀態。 + +對於通用KASAN，每個內存顆粒的大小爲8個字節。每個顆粒的狀態被編碼在一個影子字節 +中。這8個字節可以是可訪問的，部分訪問的，已釋放的或成爲Redzone的一部分。KASAN +對每個影子字節使用以下編碼:00表示對應內存區域的所有8個字節都可以訪問；數字N +(1 <= N <= 7)表示前N個字節可訪問，其他(8 - N)個字節不可訪問；任何負值都表示 +無法訪問整個8字節。KASAN使用不同的負值來區分不同類型的不可訪問內存，如redzones +或已釋放的內存（參見 mm/kasan/kasan.h）。 + +在上面的報告中，箭頭指向影子字節 ``03`` ，表示訪問的地址是部分可訪問的。 + +對於基於標籤的KASAN模式，報告最後的部分顯示了訪問地址周圍的內存標籤 +(參考 `實施細則`_ 章節)。 + +請注意，KASAN錯誤標題（如 ``slab-out-of-bounds`` 或 ``use-after-free`` ） +是儘量接近的:KASAN根據其擁有的有限信息打印出最可能的錯誤類型。錯誤的實際類型 +可能會有所不同。 + +通用KASAN還報告兩個輔助調用堆棧跟蹤。這些堆棧跟蹤指向代碼中與對象交互但不直接 +出現在錯誤訪問堆棧跟蹤中的位置。目前，這包括 call_rcu() 和排隊的工作隊列。 + +實施細則 +-------- + +通用KASAN +~~~~~~~~~ + +軟件KASAN模式使用影子內存來記錄每個內存字節是否可以安全訪問，並使用編譯時工具 +在每次內存訪問之前插入影子內存檢查。 + +通用KASAN將1/8的內核內存專用於其影子內存（16TB以覆蓋x86_64上的128TB），並使用 +具有比例和偏移量的直接映射將內存地址轉換爲其相應的影子地址。 + +這是將地址轉換爲其相應影子地址的函數:: + + static inline void *kasan_mem_to_shadow(const void *addr) + { + return (void *)((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT) + + KASAN_SHADOW_OFFSET; + } + +在這裏 ``KASAN_SHADOW_SCALE_SHIFT = 3`` 。 + +編譯時工具用於插入內存訪問檢查。編譯器在每次訪問大小爲1、2、4、8或16的內存之前 +插入函數調用( ``__asan_load*(addr)`` , ``__asan_store*(addr)``)。這些函數通過 +檢查相應的影子內存來檢查內存訪問是否有效。 + +使用inline插樁，編譯器不進行函數調用，而是直接插入代碼來檢查影子內存。此選項 +顯著地增大了內核體積，但與outline插樁內核相比，它提供了x1.1-x2的性能提升。 + +通用KASAN是唯一一種通過隔離延遲重新使用已釋放對象的模式 +（參見 mm/kasan/quarantine.c 以瞭解實現）。 + +基於軟件標籤的KASAN模式 +~~~~~~~~~~~~~~~~~~~~~~~ + +基於軟件標籤的KASAN使用軟件內存標籤方法來檢查訪問有效性。目前僅針對arm64架構實現。 + +基於軟件標籤的KASAN使用arm64 CPU的頂部字節忽略(TBI)特性在內核指針的頂部字節中 +存儲一個指針標籤。它使用影子內存來存儲與每個16字節內存單元相關的內存標籤(因此， +它將內核內存的1/16專用於影子內存)。 + +在每次內存分配時，基於軟件標籤的KASAN都會生成一個隨機標籤，用這個標籤標記分配 +的內存，並將相同的標籤嵌入到返回的指針中。 + +基於軟件標籤的KASAN使用編譯時工具在每次內存訪問之前插入檢查。這些檢查確保正在 +訪問的內存的標籤等於用於訪問該內存的指針的標籤。如果標籤不匹配，基於軟件標籤 +的KASAN會打印錯誤報告。 + +基於軟件標籤的KASAN也有兩種插樁模式（outline，發出回調來檢查內存訪問；inline， +執行內聯的影子內存檢查）。使用outline插樁模式，會從執行訪問檢查的函數打印錯誤 +報告。使用inline插樁，編譯器會發出 ``brk`` 指令，並使用專用的 ``brk`` 處理程序 +來打印錯誤報告。 + +基於軟件標籤的KASAN使用0xFF作爲匹配所有指針標籤（不檢查通過帶有0xFF指針標籤 +的指針進行的訪問）。值0xFE當前保留用於標記已釋放的內存區域。 + + +基於硬件標籤的KASAN模式 +~~~~~~~~~~~~~~~~~~~~~~~ + +基於硬件標籤的KASAN在概念上類似於軟件模式，但它是使用硬件內存標籤作爲支持而 +不是編譯器插樁和影子內存。 + +基於硬件標籤的KASAN目前僅針對arm64架構實現，並且基於ARMv8.5指令集架構中引入 +的arm64內存標記擴展(MTE)和最高字節忽略(TBI)。 + +特殊的arm64指令用於爲每次內存分配指定內存標籤。相同的標籤被指定給指向這些分配 +的指針。在每次內存訪問時，硬件確保正在訪問的內存的標籤等於用於訪問該內存的指針 +的標籤。如果標籤不匹配，則會生成故障並打印報告。 + +基於硬件標籤的KASAN使用0xFF作爲匹配所有指針標籤（不檢查通過帶有0xFF指針標籤的 +指針進行的訪問）。值0xFE當前保留用於標記已釋放的內存區域。 + +如果硬件不支持MTE（ARMv8.5之前），則不會啓用基於硬件標籤的KASAN。在這種情況下， +所有KASAN引導參數都將被忽略。 + +請注意，啓用CONFIG_KASAN_HW_TAGS始終會導致啓用內核中的TBI。即使提供了 +``kasan.mode=off`` 或硬件不支持MTE（但支持TBI）。 + +基於硬件標籤的KASAN只報告第一個發現的錯誤。之後，MTE標籤檢查將被禁用。 + +影子內存 +-------- + +本節的內容只適用於軟件KASAN模式。 + +內核將內存映射到地址空間的幾個不同部分。內核虛擬地址的範圍很大：沒有足夠的真實 +內存來支持內核可以訪問的每個地址的真實影子區域。因此，KASAN只爲地址空間的某些 +部分映射真實的影子。 + +默認行爲 +~~~~~~~~ + +默認情況下，體系結構僅將實際內存映射到用於線性映射的陰影區域（以及可能的其他 +小區域）。對於所有其他區域 —— 例如vmalloc和vmemmap空間 —— 一個只讀頁面被映射 +到陰影區域上。這個只讀的影子頁面聲明所有內存訪問都是允許的。 + +這給模塊帶來了一個問題：它們不存在於線性映射中，而是存在於專用的模塊空間中。 +通過連接模塊分配器，KASAN臨時映射真實的影子內存以覆蓋它們。例如，這允許檢測 +對模塊全局變量的無效訪問。 + +這也造成了與 ``VMAP_STACK`` 的不兼容：如果堆棧位於vmalloc空間中，它將被分配 +只讀頁面的影子內存，並且內核在嘗試爲堆棧變量設置影子數據時會出錯。 + +CONFIG_KASAN_VMALLOC +~~~~~~~~~~~~~~~~~~~~ + +使用 ``CONFIG_KASAN_VMALLOC`` ，KASAN可以以更大的內存使用爲代價覆蓋vmalloc +空間。目前，這在arm64、x86、riscv、s390和powerpc上受支持。 + +這通過連接到vmalloc和vmap並動態分配真實的影子內存來支持映射。 + +vmalloc空間中的大多數映射都很小，需要不到一整頁的陰影空間。因此，爲每個映射 +分配一個完整的影子頁面將是一種浪費。此外，爲了確保不同的映射使用不同的影子 +頁面，映射必須與 ``KASAN_GRANULE_SIZE * PAGE_SIZE`` 對齊。 + +相反，KASAN跨多個映射共享後備空間。當vmalloc空間中的映射使用影子區域的特定 +頁面時，它會分配一個後備頁面。此頁面稍後可以由其他vmalloc映射共享。 + +KASAN連接到vmap基礎架構以懶清理未使用的影子內存。 + +爲了避免交換映射的困難，KASAN預測覆蓋vmalloc空間的陰影區域部分將不會被早期 +的陰影頁面覆蓋，但是將不會被映射。這將需要更改特定於arch的代碼。 + +這允許在x86上支持 ``VMAP_STACK`` ，並且可以簡化對沒有固定模塊區域的架構的支持。 + +對於開發者 +---------- + +忽略訪問 +~~~~~~~~ + +軟件KASAN模式使用編譯器插樁來插入有效性檢查。此類檢測可能與內核的某些部分 +不兼容，因此需要禁用。 + +內核的其他部分可能會訪問已分配對象的元數據。通常，KASAN會檢測並報告此類訪問， +但在某些情況下（例如，在內存分配器中），這些訪問是有效的。 + +對於軟件KASAN模式，要禁用特定文件或目錄的檢測，請將 ``KASAN_SANITIZE`` 添加 +到相應的內核Makefile中: + +- 對於單個文件(例如，main.o):: + + KASAN_SANITIZE_main.o := n + +- 對於一個目錄下的所有文件:: + + KASAN_SANITIZE := n + +對於軟件KASAN模式，要在每個函數的基礎上禁用檢測，請使用KASAN特定的 +``__no_sanitize_address`` 函數屬性或通用的 ``noinstr`` 。 + +請注意，禁用編譯器插樁（基於每個文件或每個函數）會使KASAN忽略在軟件KASAN模式 +的代碼中直接發生的訪問。當訪問是間接發生的（通過調用檢測函數）或使用沒有編譯器 +插樁的基於硬件標籤的模式時，它沒有幫助。 + +對於軟件KASAN模式，要在當前任務的一部分內核代碼中禁用KASAN報告，請使用 +``kasan_disable_current()``/``kasan_enable_current()`` 部分註釋這部分代碼。 +這也會禁用通過函數調用發生的間接訪問的報告。 + +對於基於標籤的KASAN模式，要禁用訪問檢查，請使用 ``kasan_reset_tag()`` 或 +``page_kasan_tag_reset()`` 。請注意，通過 ``page_kasan_tag_reset()`` +臨時禁用訪問檢查需要通過 ``page_kasan_tag`` / ``page_kasan_tag_set`` 保 +存和恢復每頁KASAN標籤。 + +測試 +~~~~ + +有一些KASAN測試可以驗證KASAN是否正常工作並可以檢測某些類型的內存損壞。 +測試由兩部分組成: + +1. 與KUnit測試框架集成的測試。使用 ``CONFIG_KASAN_KUNIT_TEST`` 啓用。 +這些測試可以通過幾種不同的方式自動運行和部分驗證；請參閱下面的說明。 + +2. 與KUnit不兼容的測試。使用 ``CONFIG_KASAN_MODULE_TEST`` 啓用並且只能作爲模塊 +運行。這些測試只能通過加載內核模塊並檢查內核日誌以獲取KASAN報告來手動驗證。 + +如果檢測到錯誤，每個KUnit兼容的KASAN測試都會打印多個KASAN報告之一，然後測試打印 +其編號和狀態。 + +當測試通過:: + + ok 28 - kmalloc_double_kzfree + +當由於 ``kmalloc`` 失敗而導致測試失敗時:: + + # kmalloc_large_oob_right: ASSERTION FAILED at lib/test_kasan.c:163 + Expected ptr is not null, but is + not ok 4 - kmalloc_large_oob_right + +當由於缺少KASAN報告而導致測試失敗時:: + + # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:974 + KASAN failure expected in "kfree_sensitive(ptr)", but none occurred + not ok 44 - kmalloc_double_kzfree + + +最後打印所有KASAN測試的累積狀態。成功:: + + ok 1 - kasan + +或者，如果其中一項測試失敗:: + + not ok 1 - kasan + +有幾種方法可以運行與KUnit兼容的KASAN測試。 + +1. 可加載模塊 + + 啓用 ``CONFIG_KUNIT`` 後，KASAN-KUnit測試可以構建爲可加載模塊，並通過使用 + ``insmod`` 或 ``modprobe`` 加載 ``test_kasan.ko`` 來運行。 + +2. 內置 + + 通過內置 ``CONFIG_KUNIT`` ，也可以內置KASAN-KUnit測試。在這種情況下， + 測試將在啓動時作爲後期初始化調用運行。 + +3. 使用kunit_tool + + 通過內置 ``CONFIG_KUNIT`` 和 ``CONFIG_KASAN_KUNIT_TEST`` ，還可以使用 + ``kunit_tool`` 以更易讀的方式查看KUnit測試結果。這不會打印通過測試 + 的KASAN報告。有關 ``kunit_tool`` 更多最新信息，請參閱 + `KUnit文檔 <https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html>`_ 。 + +.. _KUnit: https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html + diff --git a/Documentation/translations/zh_TW/sparse.txt b/Documentation/translations/zh_TW/dev-tools/sparse.rst index c9acb2c926cb..11d64709d6a4 100644 --- a/Documentation/translations/zh_TW/sparse.txt +++ b/Documentation/translations/zh_TW/dev-tools/sparse.rst @@ -6,7 +6,7 @@ communicating in English you can also ask the Chinese maintainer for help. Contact the Chinese maintainer if this translation is outdated or if there is a problem with the translation. -Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> +Traditional Chinese maintainer: Hu Haowen <src.res.211@gmail.com> --------------------------------------------------------------------- Documentation/dev-tools/sparse.rst 的繁體中文翻譯 @@ -14,8 +14,8 @@ Documentation/dev-tools/sparse.rst 的繁體中文翻譯 交流有困難的話，也可以向繁體中文版維護者求助。如果本翻譯更新不及時或 者翻譯存在問題，請聯繫繁體中文版維護者。 -繁體中文版維護者： 胡皓文 Hu Haowen <src.res@email.cn> -繁體中文版翻譯者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版維護者： 胡皓文 Hu Haowen <src.res.211@gmail.com> +繁體中文版翻譯者： 胡皓文 Hu Haowen <src.res.211@gmail.com> 以下爲正文 --------------------------------------------------------------------- @@ -27,7 +27,7 @@ Copyright 2006 Bob Copeland <me@bobcopeland.com> 使用 sparse 工具做類型檢查 ~~~~~~~~~~~~~~~~~~~~~~~~~~ -"__bitwise" 是一種類型屬性，所以你應該這樣使用它： +"__bitwise" 是一種類型屬性，所以你應該這樣使用它:: typedef int __bitwise pm_request_t; @@ -47,7 +47,7 @@ Copyright 2006 Bob Copeland <me@bobcopeland.com> 坦白來說，你並不需要使用枚舉類型。上面那些實際都可以濃縮成一個特殊的"int __bitwise"類型。 -所以更簡單的辦法只要這樣做： +所以更簡單的辦法只要這樣做:: typedef int __bitwise pm_request_t; @@ -66,11 +66,11 @@ __bitwise"類型。 你可以從 Sparse 的主頁獲取最新的發布版本： - http://www.kernel.org/pub/linux/kernel/people/josh/sparse/ + https://www.kernel.org/pub/software/devel/sparse/dist/ 或者，你也可以使用 git 克隆最新的 sparse 開發版本： - git://git.kernel.org/pub/scm/linux/kernel/git/josh/sparse.git + git://git.kernel.org/pub/scm/devel/sparse/sparse.git 一旦你下載了源碼，只要以普通用戶身份運行： diff --git a/Documentation/translations/zh_TW/dev-tools/testing-overview.rst b/Documentation/translations/zh_TW/dev-tools/testing-overview.rst new file mode 100644 index 000000000000..fb3f691f46c3 --- /dev/null +++ b/Documentation/translations/zh_TW/dev-tools/testing-overview.rst @@ -0,0 +1,162 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/dev-tools/testing-overview.rst +:Translator: 胡皓文 Hu Haowen <src.res.211@gmail.com> + +============ +內核測試指南 +============ + +有許多不同的工具可以用於測試Linux內核，因此瞭解什麼時候使用它們可能 +很困難。本文檔粗略概述了它們之間的區別，並闡釋了它們是怎樣糅合在一起 +的。 + +編寫和運行測試 +============== + +大多數內核測試都是用kselftest或KUnit框架之一編寫的。它們都讓運行測試 +更加簡化，併爲編寫新測試提供幫助。 + +如果你想驗證內核的行爲——尤其是內核的特定部分——那你就要使用kUnit或 +kselftest。 + +KUnit和kselftest的區別 +---------------------- + +.. note:: + 由於本文段中部分術語尚無較好的對應中文釋義，可能導致與原文含義 + 存在些許差異，因此建議讀者結合原文 + （Documentation/dev-tools/testing-overview.rst）輔助閱讀。 + 如對部分翻譯有異議或有更好的翻譯意見，歡迎聯繫譯者進行修訂。 + +KUnit（Documentation/dev-tools/kunit/index.rst）是用於“白箱”測 +試的一個完整的內核內部系統：因爲測試代碼是內核的一部分，所以它能夠訪 +問用戶空間不能訪問到的內部結構和功能。 + +因此，KUnit測試最好針對內核中較小的、自包含的部分，以便能夠獨立地測 +試。“單元”測試的概念亦是如此。 + +比如，一個KUnit測試可能測試一個單獨的內核功能（甚至通過一個函數測試 +一個單一的代碼路徑，例如一個錯誤處理案例），而不是整個地測試一個特性。 + +這也使得KUnit測試構建和運行非常地快，從而能夠作爲開發流程的一部分被 +頻繁地運行。 + +有關更詳細的介紹，請參閱KUnit測試代碼風格指南 +Documentation/dev-tools/kunit/style.rst + +kselftest（Documentation/dev-tools/kselftest.rst），相對來說，大量用 +於用戶空間，並且通常測試用戶空間的腳本或程序。 + +這使得編寫複雜的測試，或者需要操作更多全局系統狀態的測試更加容易（諸 +如生成進程之類）。然而，從kselftest直接調用內核函數是不行的。這也就 +意味着只有通過某種方式（如系統調用、驅動設備、文件系統等）導出到了用 +戶空間的內核功能才能使用kselftest來測試。爲此，有些測試包含了一個伴 +生的內核模塊用於導出更多的信息和功能。不過，對於基本上或者完全在內核 +中運行的測試，KUnit可能是更佳工具。 + +kselftest也因此非常適合於全部功能的測試，因爲這些功能會將接口暴露到 +用戶空間，從而能夠被測試，而不是展現實現細節。“system”測試和 +“end-to-end”測試亦是如此。 + +比如，一個新的系統調用應該伴隨有新的kselftest測試。 + +代碼覆蓋率工具 +============== + +支持兩種不同代碼之間的覆蓋率測量工具。它們可以用來驗證一項測試執行的 +確切函數或代碼行。這有助於決定內核被測試了多少，或用來查找合適的測試 +中沒有覆蓋到的極端情況。 + +Documentation/translations/zh_CN/dev-tools/gcov.rst 是GCC的覆蓋率測試 +工具，能用於獲取內核的全局或每個模塊的覆蓋率。與KCOV不同的是，這個工具 +不記錄每個任務的覆蓋率。覆蓋率數據可以通過debugfs讀取，並通過常規的 +gcov工具進行解釋。 + +Documentation/dev-tools/kcov.rst 是能夠構建在內核之中，用於在每個任務 +的層面捕捉覆蓋率的一個功能。因此，它對於模糊測試和關於代碼執行期間信 +息的其它情況非常有用，比如在一個單一系統調用裏使用它就很有用。 + +動態分析工具 +============ + +內核也支持許多動態分析工具，用以檢測正在運行的內核中出現的多種類型的 +問題。這些工具通常每個去尋找一類不同的缺陷，比如非法內存訪問，數據競 +爭等併發問題，或整型溢出等其他未定義行爲。 + +如下所示： + +* kmemleak檢測可能的內存泄漏。參閱 + Documentation/dev-tools/kmemleak.rst +* KASAN檢測非法內存訪問，如數組越界和釋放後重用（UAF）。參閱 + Documentation/dev-tools/kasan.rst +* UBSAN檢測C標準中未定義的行爲，如整型溢出。參閱 + Documentation/dev-tools/ubsan.rst +* KCSAN檢測數據競爭。參閱 Documentation/dev-tools/kcsan.rst +* KFENCE是一個低開銷的內存問題檢測器，比KASAN更快且能被用於批量構建。 + 參閱 Documentation/dev-tools/kfence.rst +* lockdep是一個鎖定正確性檢測器。參閱 + Documentation/locking/lockdep-design.rst +* 除此以外，在內核中還有一些其它的調試工具，大多數能在 + lib/Kconfig.debug 中找到。 + +這些工具傾向於對內核進行整體測試，並且不像kselftest和KUnit一樣“傳遞”。 +它們可以通過在啓用這些工具時運行內核測試以與kselftest或KUnit結合起來： +之後你就能確保這些錯誤在測試過程中都不會發生了。 + +一些工具與KUnit和kselftest集成，並且在檢測到問題時會自動打斷測試。 + +靜態分析工具 +============ + +除了測試運行中的內核，我們還可以使用**靜態分析**工具直接分析內核的源代 +碼（**在編譯時**）。內核中常用的工具允許人們檢查整個源代碼樹或其中的特 +定文件。它們使得在開發過程中更容易發現和修復問題。 + + Sparse可以通過執行類型檢查、鎖檢查、值範圍檢查來幫助測試內核，此外還 + 可以在檢查代碼時報告各種錯誤和警告。關於如何使用它的細節，請參閱 + Documentation/translations/zh_CN/dev-tools/sparse.rst。 + + Smatch擴展了Sparse，並提供了對編程邏輯錯誤的額外檢查，如開關語句中 + 缺少斷點，錯誤檢查中未使用的返回值，忘記在錯誤路徑的返回中設置錯誤代 + 碼等。Smatch也有針對更嚴重問題的測試，如整數溢出、空指針解除引用和內 + 存泄漏。見項目頁面http://smatch.sourceforge.net/。 + + Coccinelle是我們可以使用的另一個靜態分析器。Coccinelle經常被用來 + 幫助源代碼的重構和並行演化，但它也可以幫助避免常見代碼模式中出現的某 + 些錯誤。可用的測試類型包括API測試、內核迭代器的正確使用測試、自由操 + 作的合理性檢查、鎖定行爲的分析，以及已知的有助於保持內核使用一致性的 + 進一步測試。詳情請見Documentation/dev-tools/coccinelle.rst。 + + 不過要注意的是，靜態分析工具存在**假陽性**的問題。在試圖修復錯誤和警 + 告之前，需要仔細評估它們。 + +何時使用Sparse和Smatch +---------------------- + +Sparse做類型檢查，例如驗證註釋的變量不會導致無符號的錯誤，檢測 +``__user`` 指針使用不當的地方，以及分析符號初始化器的兼容性。 + +Smatch進行流程分析，如果允許建立函數數據庫，它還會進行跨函數分析。 +Smatch試圖回答一些問題，比如這個緩衝區是在哪裏分配的？它有多大？這 +個索引可以由用戶控制嗎？這個變量比那個變量大嗎？ + +一般來說，在Smatch中寫檢查比在Sparse中寫檢查要容易。儘管如此， +Sparse和Smatch的檢查還是有一些重疊的地方。 + +Smatch和Coccinelle的強項 +------------------------ + +Coccinelle可能是最容易寫檢查的。它在預處理器之前工作，所以用Coccinelle +檢查宏中的錯誤更容易。Coccinelle還能爲你創建補丁，這是其他工具無法做到的。 + +例如，用Coccinelle你可以從 ``kmalloc_array(x, size, GFP_KERNEL)`` +到 ``kmalloc_array(x, size, GFP_KERNEL)`` 進行大規模轉換，這真的很 +有用。如果你只是創建一個Smatch警告，並試圖把轉換的工作推給維護者，他們會很 +惱火。你將不得不爲每個警告爭論是否真的可以溢出。 + +Coccinelle不對變量值進行分析，而這正是Smatch的強項。另一方面，Coccinelle +允許你用簡單的方法做簡單的事情。 + diff --git a/Documentation/translations/zh_TW/disclaimer-zh_TW.rst b/Documentation/translations/zh_TW/disclaimer-zh_TW.rst index f4cf87d03dc5..0d0ffb1ca4e8 100644 --- a/Documentation/translations/zh_TW/disclaimer-zh_TW.rst +++ b/Documentation/translations/zh_TW/disclaimer-zh_TW.rst @@ -7,5 +7,5 @@ .. note:: 如果您發現本文檔與原始文件有任何不同或者有翻譯問題，請聯繫該文件的譯者， - 或者發送電子郵件給胡皓文以獲取幫助：<src.res@email.cn>。 + 或者發送電子郵件給胡皓文以獲取幫助：<src.res.211@gmail.com>。 diff --git a/Documentation/translations/zh_TW/filesystems/debugfs.rst b/Documentation/translations/zh_TW/filesystems/debugfs.rst index 270dd94fddf1..78e2e08af95e 100644 --- a/Documentation/translations/zh_TW/filesystems/debugfs.rst +++ b/Documentation/translations/zh_TW/filesystems/debugfs.rst @@ -2,7 +2,7 @@ .. include:: ../disclaimer-zh_TW.rst -:Original: :doc:`../../../filesystems/debugfs` +:Original: Documentation/filesystems/debugfs.rst ======= Debugfs @@ -11,20 +11,19 @@ Debugfs 譯者 :: - 中文版維護者：羅楚成 Chucheng Luo <luochucheng@vivo.com> - 中文版翻譯者：羅楚成 Chucheng Luo <luochucheng@vivo.com> - 中文版校譯者: 羅楚成 Chucheng Luo <luochucheng@vivo.com> - 繁體中文版校譯者: 胡皓文 Hu Haowen <src.res@email.cn> + 中文版維護者： 羅楚成 Chucheng Luo <luochucheng@vivo.com> + 中文版翻譯者： 羅楚成 Chucheng Luo <luochucheng@vivo.com> + 中文版校譯者: 羅楚成 Chucheng Luo <luochucheng@vivo.com> + 繁體中文版校譯者: 胡皓文 Hu Haowen <src.res.211@gmail.com> 版權所有2020 羅楚成 <luochucheng@vivo.com> -版權所有2021 胡皓文 Hu Haowen <src.res@email.cn> Debugfs是內核開發人員在用戶空間獲取信息的簡單方法。與/proc不同，proc只提供進程 -信息。也不像sysfs,具有嚴格的「每個文件一個值「的規則。debugfs根本沒有規則,開發 -人員可以在這裡放置他們想要的任何信息。debugfs文件系統也不能用作穩定的ABI接口。 +信息。也不像sysfs,具有嚴格的“每個文件一個值“的規則。debugfs根本沒有規則,開發 +人員可以在這裏放置他們想要的任何信息。debugfs文件系統也不能用作穩定的ABI接口。 從理論上講，debugfs導出文件的時候沒有任何約束。但是[1]實際情況並不總是那麼 簡單。即使是debugfs接口，也最好根據需要進行設計,並儘量保持接口不變。 @@ -34,8 +33,8 @@ Debugfs通常使用以下命令安裝:: mount -t debugfs none /sys/kernel/debug （或等效的/etc/fstab行）。 -debugfs根目錄默認僅可由root用戶訪問。要更改對文件樹的訪問，請使用「 uid」，「 gid」 -和「 mode」掛載選項。請注意，debugfs API僅按照GPL協議導出到模塊。 +debugfs根目錄默認僅可由root用戶訪問。要更改對文件樹的訪問，請使用“ uid”，“ gid” +和“ mode”掛載選項。請注意，debugfs API僅按照GPL協議導出到模塊。 使用debugfs的代碼應包含<linux/debugfs.h>。然後，首先是創建至少一個目錄來保存 一組debugfs文件:: @@ -54,8 +53,8 @@ debugfs根目錄默認僅可由root用戶訪問。要更改對文件樹的訪問 struct dentry *parent, void *data, const struct file_operations *fops); -在這裡，name是要創建的文件的名稱，mode描述了訪問文件應具有的權限，parent指向 -應該保存文件的目錄，data將存儲在產生的inode結構體的i_private欄位中，而fops是 +在這裏，name是要創建的文件的名稱，mode描述了訪問文件應具有的權限，parent指向 +應該保存文件的目錄，data將存儲在產生的inode結構體的i_private字段中，而fops是 一組文件操作函數，這些函數中實現文件操作的具體行爲。至少，read（）和/或 write（）操作應提供；其他可以根據需要包括在內。同樣的，返回值將是指向創建文件 的dentry指針，錯誤時返回ERR_PTR（-ERROR），系統不支持debugfs時返回值爲ERR_PTR @@ -81,7 +80,7 @@ file_size是初始文件大小。其他參數跟函數debugfs_create_file的相 struct dentry *parent, u64 *value); 這些文件支持讀取和寫入給定值。如果某個文件不支持寫入，只需根據需要設置mode -參數位。這些文件中的值以十進位表示；如果需要使用十六進位，可以使用以下函數 +參數位。這些文件中的值以十進制表示；如果需要使用十六進制，可以使用以下函數 替代:: void debugfs_create_x8(const char *name, umode_t mode, @@ -93,7 +92,7 @@ file_size是初始文件大小。其他參數跟函數debugfs_create_file的相 void debugfs_create_x64(const char *name, umode_t mode, struct dentry *parent, u64 *value); -這些功能只有在開發人員知道導出值的大小的時候才有用。某些數據類型在不同的架構上 +這些功能只有在開發人員知道導出值的大小的時候纔有用。某些數據類型在不同的架構上 有不同的寬度，這樣會使情況變得有些複雜。在這種特殊情況下可以使用以下函數:: void debugfs_create_size_t(const char *name, umode_t mode, @@ -101,7 +100,7 @@ file_size是初始文件大小。其他參數跟函數debugfs_create_file的相 不出所料，此函數將創建一個debugfs文件來表示類型爲size_t的變量。 -同樣地，也有導出無符號長整型變量的函數，分別以十進位和十六進位表示如下:: +同樣地，也有導出無符號長整型變量的函數，分別以十進制和十六進制表示如下:: struct dentry *debugfs_create_ulong(const char *name, umode_t mode, struct dentry *parent, @@ -125,7 +124,7 @@ file_size是初始文件大小。其他參數跟函數debugfs_create_file的相 讀取此文件將獲得atomic_t值，寫入此文件將設置atomic_t值。 -另一個選擇是通過以下結構體和函數導出一個任意二進位數據塊:: +另一個選擇是通過以下結構體和函數導出一個任意二進制數據塊:: struct debugfs_blob_wrapper { void *data; @@ -136,10 +135,10 @@ file_size是初始文件大小。其他參數跟函數debugfs_create_file的相 struct dentry *parent, struct debugfs_blob_wrapper *blob); -讀取此文件將返回由指針指向debugfs_blob_wrapper結構體的數據。一些驅動使用「blobs」 -作爲一種返回幾行（靜態）格式化文本的簡單方法。這個函數可用於導出二進位信息，但 +讀取此文件將返回由指針指向debugfs_blob_wrapper結構體的數據。一些驅動使用“blobs” +作爲一種返回幾行（靜態）格式化文本的簡單方法。這個函數可用於導出二進制信息，但 似乎在主線中沒有任何代碼這樣做。請注意，使用debugfs_create_blob（）命令創建的 -所有文件是只讀的。 +所有文件是隻讀的。 如果您要轉儲一個寄存器塊（在開發過程中經常會這麼做，但是這樣的調試代碼很少上傳 到主線中。Debugfs提供兩個函數：一個用於創建僅寄存器文件，另一個把一個寄存器塊 @@ -163,7 +162,7 @@ file_size是初始文件大小。其他參數跟函數debugfs_create_file的相 void debugfs_print_regs32(struct seq_file *s, struct debugfs_reg32 *regs, int nregs, void __iomem *base, char *prefix); -「base」參數可能爲0，但您可能需要使用__stringify構建reg32數組，實際上有許多寄存器 +“base”參數可能爲0，但您可能需要使用__stringify構建reg32數組，實際上有許多寄存器 名稱（宏）是寄存器塊在基址上的字節偏移量。 如果要在debugfs中轉儲u32數組，可以使用以下函數創建文件:: @@ -172,7 +171,7 @@ file_size是初始文件大小。其他參數跟函數debugfs_create_file的相 struct dentry *parent, u32 *array, u32 elements); -「array」參數提供數據，而「elements」參數爲數組中元素的數量。注意：數組創建後，數組 +“array”參數提供數據，而“elements”參數爲數組中元素的數量。注意：數組創建後，數組 大小無法更改。 有一個函數來創建與設備相關的seq_file:: @@ -183,8 +182,8 @@ file_size是初始文件大小。其他參數跟函數debugfs_create_file的相 int (*read_fn)(struct seq_file *s, void *data)); -「dev」參數是與此debugfs文件相關的設備，並且「read_fn」是一個函數指針，這個函數在 -列印seq_file內容的時候被回調。 +“dev”參數是與此debugfs文件相關的設備，並且“read_fn”是一個函數指針，這個函數在 +打印seq_file內容的時候被回調。 還有一些其他的面向目錄的函數:: @@ -199,7 +198,7 @@ file_size是初始文件大小。其他參數跟函數debugfs_create_file的相 調用debugfs_rename()將爲現有的debugfs文件重命名，可能同時切換目錄。 new_name 函數調用之前不能存在；返回值爲old_dentry，其中包含更新的信息。可以使用 -debugfs_create_symlink（）創建符號連結。 +debugfs_create_symlink（）創建符號鏈接。 所有debugfs用戶必須考慮的一件事是： @@ -219,6 +218,6 @@ dentry值可以爲NULL或錯誤值，在這種情況下，不會有任何文件 如果將對應頂層目錄的dentry傳遞給以上函數，則該目錄下的整個層次結構將會被刪除。 -注釋： +註釋： [1] http://lwn.net/Articles/309298/ diff --git a/Documentation/translations/zh_TW/filesystems/index.rst b/Documentation/translations/zh_TW/filesystems/index.rst index 4e5dde0dca3c..d7f9d61f654c 100644 --- a/Documentation/translations/zh_TW/filesystems/index.rst +++ b/Documentation/translations/zh_TW/filesystems/index.rst @@ -4,7 +4,7 @@ :Original: :ref:`Documentation/filesystems/index.rst <filesystems_index>` :Translator: Wang Wenhu <wenhu.wang@vivo.com> - Hu Haowen <src.res@email.cn> + Hu Haowen <src.res.211@gmail.com> .. _tw_filesystems_index: @@ -12,7 +12,7 @@ Linux Kernel中的文件系統 ======================== -這份正在開發的手冊或許在未來某個輝煌的日子裡以易懂的形式將Linux虛擬\ +這份正在開發的手冊或許在未來某個輝煌的日子裏以易懂的形式將Linux虛擬\ 文件系統（VFS）層以及基於其上的各種文件系統如何工作呈現給大家。當前\ 可以看到下面的內容。 diff --git a/Documentation/translations/zh_TW/filesystems/sysfs.txt b/Documentation/translations/zh_TW/filesystems/sysfs.txt index 280824cc7e5d..ebe90651fc3b 100644 --- a/Documentation/translations/zh_TW/filesystems/sysfs.txt +++ b/Documentation/translations/zh_TW/filesystems/sysfs.txt @@ -22,7 +22,7 @@ Documentation/filesystems/sysfs.rst 的中文翻譯 中文版維護者： 傅煒 Fu Wei <tekkamanninja@gmail.com> 中文版翻譯者： 傅煒 Fu Wei <tekkamanninja@gmail.com> 中文版校譯者： 傅煒 Fu Wei <tekkamanninja@gmail.com> -繁體中文版校譯者：胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版校譯者：胡皓文 Hu Haowen <src.res.211@gmail.com> 以下爲正文 @@ -61,7 +61,7 @@ Documentation/core-api/kobject.rst 文檔以獲得更多關於 kobject 接口的 任何 kobject 在系統中註冊，就會有一個目錄在 sysfs 中被創建。這個 目錄是作爲該 kobject 的父對象所在目錄的子目錄創建的，以準確地傳遞 -內核的對象層次到用戶空間。sysfs 中的頂層目錄代表著內核對象層次的 +內核的對象層次到用戶空間。sysfs 中的頂層目錄代表着內核對象層次的 共同祖先；例如：某些對象屬於某個子系統。 Sysfs 在與其目錄關聯的 kernfs_node 對象中內部保存一個指向實現 @@ -198,7 +198,7 @@ Sysfs 將會爲每次讀寫操作調用一次這個方法。這使得這些方 不會不太高。 這使得用戶空間可以局部地讀和任意的向前搜索整個文件。如果用戶空間 - 向後搜索到零或使用『0』偏移執行一個pread(2)操作，show()方法將 + 向後搜索到零或使用‘0’偏移執行一個pread(2)操作，show()方法將 再次被調用，以重新填充緩存。 - 在寫方面（write(2)），sysfs 希望在第一次寫操作時得到整個緩衝區。 @@ -253,7 +253,7 @@ static DEVICE_ATTR(name, S_IRUGO, show_name, store_name); （注意：真正的實現不允許用戶空間設置設備名。） -頂層目錄布局 +頂層目錄佈局 ~~~~~~~~~~~~ sysfs 目錄的安排顯示了內核數據結構之間的關係。 @@ -272,23 +272,23 @@ fs/ devices/ 包含了一個設備樹的文件系統表示。他直接映射了內部的內核 設備樹，反映了設備的層次結構。 -bus/ 包含了內核中各種總線類型的平面目錄布局。每個總線目錄包含兩個 +bus/ 包含了內核中各種總線類型的平面目錄佈局。每個總線目錄包含兩個 子目錄: devices/ drivers/ -devices/ 包含了系統中出現的每個設備的符號連結，他們指向 root/ 下的 +devices/ 包含了系統中出現的每個設備的符號鏈接，他們指向 root/ 下的 設備目錄。 -drivers/ 包含了每個已爲特定總線上的設備而掛載的驅動程序的目錄(這裡 +drivers/ 包含了每個已爲特定總線上的設備而掛載的驅動程序的目錄(這裏 假定驅動沒有跨越多個總線類型)。 fs/ 包含了一個爲文件系統設立的目錄。現在每個想要導出屬性的文件系統必須 在 fs/ 下創建自己的層次結構(參見Documentation/filesystems/fuse.rst)。 dev/ 包含兩個子目錄： char/ 和 block/。在這兩個子目錄中，有以 -<major>:<minor> 格式命名的符號連結。這些符號連結指向 sysfs 目錄 +<major>:<minor> 格式命名的符號鏈接。這些符號鏈接指向 sysfs 目錄 中相應的設備。/sys/dev 提供一個通過一個 stat(2) 操作結果，查找 設備 sysfs 接口快捷的方法。 diff --git a/Documentation/translations/zh_TW/filesystems/tmpfs.rst b/Documentation/translations/zh_TW/filesystems/tmpfs.rst index 8d753a34785b..aed61cc3064d 100644 --- a/Documentation/translations/zh_TW/filesystems/tmpfs.rst +++ b/Documentation/translations/zh_TW/filesystems/tmpfs.rst @@ -4,8 +4,7 @@ :Original: Documentation/filesystems/tmpfs.rst -Translated by Wang Qing <wangqing@vivo.com> -and Hu Haowen <src.res@email.cn> +translated by Wang Qing<wangqing@vivo.com> ===== Tmpfs @@ -13,18 +12,18 @@ Tmpfs Tmpfs是一個將所有文件都保存在虛擬內存中的文件系統。 -tmpfs中的所有內容都是臨時的，也就是說沒有任何文件會在硬碟上創建。 +tmpfs中的所有內容都是臨時的，也就是說沒有任何文件會在硬盤上創建。 如果卸載tmpfs實例，所有保存在其中的文件都會丟失。 -tmpfs將所有文件保存在內核緩存中，隨著文件內容增長或縮小可以將不需要的 -頁面swap出去。它具有最大限制，可以通過「mount -o remount ...」調整。 +tmpfs將所有文件保存在內核緩存中，隨着文件內容增長或縮小可以將不需要的 +頁面swap出去。它具有最大限制，可以通過“mount -o remount ...”調整。 和ramfs（創建tmpfs的模板）相比，tmpfs包含交換和限制檢查。和tmpfs相似的另 -一個東西是RAM磁碟（/dev/ram*），可以在物理RAM中模擬固定大小的硬碟，並在 +一個東西是RAM磁盤（/dev/ram*），可以在物理RAM中模擬固定大小的硬盤，並在 此之上創建一個普通的文件系統。Ramdisks無法swap，因此無法調整它們的大小。 由於tmpfs完全保存於頁面緩存和swap中，因此所有tmpfs頁面將在/proc/meminfo -中顯示爲「Shmem」，而在free(1)中顯示爲「Shared」。請注意，這些計數還包括 +中顯示爲“Shmem”，而在free(1)中顯示爲“Shared”。請注意，這些計數還包括 共享內存(shmem，請參閱ipcs(1))。獲得計數的最可靠方法是使用df(1)和du(1)。 tmpfs具有以下用途： @@ -45,7 +44,7 @@ tmpfs具有以下用途： tmpfs的前身(shm fs)才能使用SYSV共享內存) 3) 很多人（包括我）都覺的在/tmp和/var/tmp上掛載非常方便，並具有較大的 - swap分區。目前循環掛載tmpfs可以正常工作，所以大多數發布都應當可以 + swap分區。目前循環掛載tmpfs可以正常工作，所以大多數發佈都應當可以 使用mkinitrd通過/tmp訪問/tmp。 4) 也許還有更多我不知道的地方:-) @@ -58,11 +57,11 @@ size tmpfs實例分配的字節數限制。默認值是不swap時物理RAM 如果tmpfs實例過大，機器將死鎖，因爲OOM處理將無法釋放該內存。 nr_blocks 與size相同，但以PAGE_SIZE爲單位。 nr_inodes tmpfs實例的最大inode個數。默認值是物理內存頁數的一半，或者 - (有高端內存的機器)低端內存RAM的頁數，二者以較低者為準。 + (有高端內存的機器)低端內存RAM的頁數，二者以較低者爲準。 ========= =========================================================== 這些參數接受後綴k，m或g表示千，兆和千兆字節，可以在remount時更改。 -size參數也接受後綴％用來限制tmpfs實例占用物理RAM的百分比： +size參數也接受後綴％用來限制tmpfs實例佔用物理RAM的百分比： 未指定size或nr_blocks時，默認值爲size=50％ 如果nr_blocks=0（或size=0），block個數將不受限制；如果nr_inodes=0， @@ -71,26 +70,26 @@ inode個數將不受限制。這樣掛載通常是不明智的，因爲它允許 場景下的訪問。 tmpfs具有爲所有文件設置NUMA內存分配策略掛載選項(如果啓用了CONFIG_NUMA), -可以通過「mount -o remount ...」調整 +可以通過“mount -o remount ...”調整 ======================== ========================= mpol=default 採用進程分配策略 (請參閱 set_mempolicy(2)) mpol=prefer:Node 傾向從給定的節點分配 -mpol=bind:NodeList 只允許從指定的鍊表分配 +mpol=bind:NodeList 只允許從指定的鏈表分配 mpol=interleave 傾向於依次從每個節點分配 mpol=interleave:NodeList 依次從每個節點分配 mpol=local 優先本地節點分配內存 ======================== ========================= -NodeList格式是以逗號分隔的十進位數字表示大小和範圍，最大和最小範圍是用- -分隔符的十進位數來表示。例如，mpol=bind0-3,5,7,9-15 +NodeList格式是以逗號分隔的十進制數字表示大小和範圍，最大和最小範圍是用- +分隔符的十進制數來表示。例如，mpol=bind0-3,5,7,9-15 帶有有效NodeList的內存策略將按指定格式保存，在創建文件時使用。當任務在該 文件系統上創建文件時，會使用到掛載時的內存策略NodeList選項，如果設置的話， 由調用任務的cpuset[請參見Documentation/admin-guide/cgroup-v1/cpusets.rst] 以及下面列出的可選標誌約束。如果NodeLists爲設置爲空集，則文件的內存策略將 -恢復爲「默認」策略。 +恢復爲“默認”策略。 NUMA內存分配策略有可選標誌，可以用於模式結合。在掛載tmpfs時指定這些可選 標誌可以在NodeList之前生效。 @@ -107,12 +106,12 @@ Documentation/admin-guide/mm/numa_memory_policy.rst列出所有可用的內存 請注意，如果內核不支持NUMA，那麼使用mpol選項掛載tmpfs將會失敗；nodelist指定不 在線的節點也會失敗。如果您的系統依賴於此，但內核會運行不帶NUMA功能(也許是安全 revocery內核)，或者具有較少的節點在線，建議從自動模式中省略mpol選項掛載選項。 -可以在以後通過「mount -o remount,mpol=Policy:NodeList MountPoint」添加到掛載點。 +可以在以後通過“mount -o remount,mpol=Policy:NodeList MountPoint”添加到掛載點。 要指定初始根目錄，可以使用如下掛載選項： ==== ==================== -模式 權限用八進位數字表示 +模式 權限用八進制數字表示 uid 用戶ID gid 組ID ==== ==================== @@ -129,7 +128,7 @@ inode32 使用32位inode 在32位內核上，默認是inode32，掛載時指定inode64會被拒絕。 在64位內核上，默認配置是CONFIG_TMPFS_INODE64。inode64避免了單個設備上可能有多個 -具有相同inode編號的文件；比如32位應用程式使用glibc如果長期訪問tmpfs，一旦達到33 +具有相同inode編號的文件；比如32位應用程序使用glibc如果長期訪問tmpfs，一旦達到33 位inode編號，就有EOVERFLOW失敗的危險，無法打開大於2GiB的文件，並返回EINVAL。 所以'mount -t tmpfs -o size=10G,nr_inodes=10k,mode=700 tmpfs /mytmpfs'將在 diff --git a/Documentation/translations/zh_TW/filesystems/virtiofs.rst b/Documentation/translations/zh_TW/filesystems/virtiofs.rst index 2b05e84375dd..6150ad964e78 100644 --- a/Documentation/translations/zh_TW/filesystems/virtiofs.rst +++ b/Documentation/translations/zh_TW/filesystems/virtiofs.rst @@ -10,8 +10,7 @@ 中文版維護者： 王文虎 Wang Wenhu <wenhu.wang@vivo.com> 中文版翻譯者： 王文虎 Wang Wenhu <wenhu.wang@vivo.com> 中文版校譯者： 王文虎 Wang Wenhu <wenhu.wang@vivo.com> - 中文版校譯者： 王文虎 Wang Wenhu <wenhu.wang@vivo.com> - 繁體中文版校譯者：胡皓文 Hu Haowen <src.res@email.cn> + 繁體中文版校譯者：胡皓文 Hu Haowen <src.res.211@gmail.com> =========================================== virtiofs: virtio-fs 主機<->客機共享文件系統 @@ -21,7 +20,7 @@ virtiofs: virtio-fs 主機<->客機共享文件系統 介紹 ==== -Linux的virtiofs文件系統實現了一個半虛擬化VIRTIO類型「virtio-fs」設備的驅動，通過該\ +Linux的virtiofs文件系統實現了一個半虛擬化VIRTIO類型“virtio-fs”設備的驅動，通過該\ 類型設備實現客機<->主機文件系統共享。它允許客機掛載一個已經導出到主機的目錄。 客機通常需要訪問主機或者遠程系統上的文件。使用場景包括：在新客機安裝時讓文件對其\ @@ -42,12 +41,12 @@ Linux的virtiofs文件系統實現了一個半虛擬化VIRTIO類型「virtio-fs guest# mount -t virtiofs myfs /mnt -請查閱 https://virtio-fs.gitlab.io/ 了解配置QEMU和virtiofsd守護程序的詳細信息。 +請查閱 https://virtio-fs.gitlab.io/ 瞭解配置QEMU和virtiofsd守護程序的詳細信息。 內幕 ==== 由於virtio-fs設備將FUSE協議用於文件系統請求，因此Linux的virtiofs文件系統與FUSE文\ -件系統客戶端緊密集成在一起。客機充當FUSE客戶端而主機充當FUSE伺服器，內核與用戶空\ +件系統客戶端緊密集成在一起。客機充當FUSE客戶端而主機充當FUSE服務器，內核與用戶空\ 間之間的/dev/fuse接口由virtio-fs設備接口代替。 FUSE請求被置於虛擬隊列中由主機處理。主機填充緩衝區中的響應部分，而客機處理請求的完成部分。 @@ -55,7 +54,7 @@ FUSE請求被置於虛擬隊列中由主機處理。主機填充緩衝區中的 將/dev/fuse映射到虛擬隊列需要解決/dev/fuse和虛擬隊列之間語義上的差異。每次讀取\ /dev/fuse設備時，FUSE客戶端都可以選擇要傳輸的請求，從而可以使某些請求優先於其他\ 請求。虛擬隊列有其隊列語義，無法更改已入隊請求的順序。在虛擬隊列已滿的情況下尤 -其關鍵，因爲此時不可能加入高優先級的請求。爲了解決此差異，virtio-fs設備採用「hiprio」\ +其關鍵，因爲此時不可能加入高優先級的請求。爲了解決此差異，virtio-fs設備採用“hiprio”\ （高優先級）虛擬隊列，專門用於有別於普通請求的高優先級請求。 diff --git a/Documentation/translations/zh_TW/gpio.txt b/Documentation/translations/zh_TW/gpio.txt index b93788a2628b..555e4b11a5c7 100644 --- a/Documentation/translations/zh_TW/gpio.txt +++ b/Documentation/translations/zh_TW/gpio.txt @@ -8,7 +8,7 @@ or if there is a problem with the translation. Maintainer: Grant Likely <grant.likely@secretlab.ca> Linus Walleij <linus.walleij@linaro.org> -Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> +Traditional Chinese maintainer: Hu Haowen <src.res.211@gmail.com> --------------------------------------------------------------------- Documentation/admin-guide/gpio 的繁體中文翻譯 @@ -18,9 +18,9 @@ Documentation/admin-guide/gpio 的繁體中文翻譯 英文版維護者： Grant Likely <grant.likely@secretlab.ca> Linus Walleij <linus.walleij@linaro.org> -繁體中文版維護者： 胡皓文 Hu Haowen <src.res@email.cn> -繁體中文版翻譯者： 胡皓文 Hu Haowen <src.res@email.cn> -繁體中文版校譯者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版維護者： 胡皓文 Hu Haowen <src.res.211@gmail.com> +繁體中文版翻譯者： 胡皓文 Hu Haowen <src.res.211@gmail.com> +繁體中文版校譯者： 胡皓文 Hu Haowen <src.res.211@gmail.com> 以下爲正文 --------------------------------------------------------------------- diff --git a/Documentation/translations/zh_TW/index.rst b/Documentation/translations/zh_TW/index.rst index e7c83868e780..563ac9bfc66b 100644 --- a/Documentation/translations/zh_TW/index.rst +++ b/Documentation/translations/zh_TW/index.rst @@ -15,159 +15,116 @@ .. note:: 內核文檔繁體中文版的翻譯工作正在進行中。如果您願意並且有時間參與這項工 - 作，歡迎提交補丁給胡皓文 <src.res@email.cn>。 + 作，歡迎提交補丁給胡皓文 <src.res.211@gmail.com>。 -許可證文檔 ----------- - -下面的文檔介紹了Linux內核原始碼的許可證（GPLv2）、如何在原始碼樹中正確標記 -單個文件的許可證、以及指向完整許可證文本的連結。 - -Documentation/translations/zh_TW/process/license-rules.rst +與Linux 內核社區一起工作 +------------------------ -用戶文檔 --------- - -下面的手冊是爲內核用戶編寫的——即那些試圖讓它在給定系統上以最佳方式工作的 -用戶。 +與內核開發社區進行協作並將工作推向上游的基本指南。 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - admin-guide/index + process/development-process + process/submitting-patches + 行爲準則 <process/code-of-conduct> + 完整開發流程文檔 <process/index> TODOList: -* kbuild/index +* maintainer/index -固件相關文檔 ------------- +內部API文檔 +----------- -下列文檔描述了內核需要的平台固件相關信息。 +開發人員使用的內核內部交互接口手冊。 TODOList: -* firmware-guide/index -* devicetree/index - -應用程式開發人員文檔 --------------------- - -用戶空間API手冊涵蓋了描述應用程式開發人員可見內核接口方面的文檔。 - -TODOlist: - -* userspace-api/index +* core-api/index +* driver-api/index +* 內核中的鎖 <locking/index> +* subsystem-apis -內核開發簡介 ------------- +開發工具和流程 +-------------- -這些手冊包含有關如何開發內核的整體信息。內核社區非常龐大，一年下來有數千名 -開發人員做出貢獻。與任何大型社區一樣，知道如何完成任務將使得更改合併的過程 -變得更加容易。 +爲所有內核開發人員提供有用信息的各種其他手冊。 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - process/index + process/license-rules + dev-tools/index TODOList: -* dev-tools/index * doc-guide/index +* dev-tools/testing-overview * kernel-hacking/index +* rust/index * trace/index -* maintainer/index * fault-injection/index * livepatch/index -* rust/index -內核API文檔 ------------ +面向用戶的文檔 +-------------- -以下手冊從內核開發人員的角度詳細介紹了特定的內核子系統是如何工作的。這裡的 -大部分信息都是直接從內核原始碼獲取的，並根據需要添加補充材料（或者至少是在 -我們設法添加的時候——可能不是所有的都是有需要的）。 +下列手冊針對 +希望內核在給定系統上以最佳方式工作的*用戶*， +和查找內核用戶空間API信息的程序開發人員。 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - cpu-freq/index - filesystems/index + admin-guide/index + admin-guide/reporting-issues.rst TODOList: -* driver-api/index -* core-api/index -* locking/index -* accounting/index -* block/index -* cdrom/index -* ide/index -* fb/index -* fpga/index -* hid/index -* i2c/index -* iio/index -* isdn/index -* infiniband/index -* leds/index -* netlabel/index -* networking/index -* pcmcia/index -* power/index -* target/index -* timers/index -* spi/index -* w1/index -* watchdog/index -* virt/index -* input/index -* hwmon/index -* gpu/index -* security/index -* sound/index -* crypto/index -* mm/index -* bpf/index -* usb/index -* PCI/index -* scsi/index -* misc-devices/index -* scheduler/index -* mhi/index - -體系結構無關文檔 ----------------- +* userspace-api/index +* 內核構建系統 <kbuild/index> +* 用戶空間工具 <tools/index> -TODOList: +也可參考獨立於內核文檔的 `Linux 手冊頁 <https://www.kernel.org/doc/man-pages/>`_ 。 -* asm-annotations +固件相關文檔 +------------ -特定體系結構文檔 ----------------- +下列文檔描述了內核需要的平臺固件相關信息。 -.. toctree:: - :maxdepth: 2 +TODOList: - arch/arm64/index +* devicetree/index +* firmware-guide/index -TODOList: +體系結構文檔 +------------ + +.. toctree:: + :maxdepth: 1 -* arch + arch/index 其他文檔 -------- -有幾份未排序的文檔似乎不適合放在文檔的其他部分，或者可能需要進行一些調整和/或 +有幾份未分類的文檔似乎不適合放在文檔的其他部分，或者可能需要進行一些調整和/或 轉換爲reStructureText格式，也有可能太舊。 TODOList: * staging/index -* watch_queue -目錄和表格 +術語表 +------ + +TODOList: + +* glossary + + +索引和表格 ---------- * :ref:`genindex` diff --git a/Documentation/translations/zh_TW/io_ordering.txt b/Documentation/translations/zh_TW/io_ordering.txt index 1e99206c8421..03f86840c139 100644 --- a/Documentation/translations/zh_TW/io_ordering.txt +++ b/Documentation/translations/zh_TW/io_ordering.txt @@ -6,7 +6,7 @@ communicating in English you can also ask the Chinese maintainer for help. Contact the Chinese maintainer if this translation is outdated or if there is a problem with the translation. -Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> +Traditional Chinese maintainer: Hu Haowen <src.res.211@gmail.com> --------------------------------------------------------------------- Documentation/driver-api/io_ordering.rst 的繁體中文翻譯 @@ -14,9 +14,9 @@ Documentation/driver-api/io_ordering.rst 的繁體中文翻譯 交流有困難的話，也可以向繁體中文版維護者求助。如果本翻譯更新不及時或 者翻譯存在問題，請聯繫繁體中文版維護者。 -繁體中文版維護者： 胡皓文 Hu Haowen <src.res@email.cn> -繁體中文版翻譯者： 胡皓文 Hu Haowen <src.res@email.cn> -繁體中文版校譯者： 胡皓文 Hu Haowen <src.res@email.cn> +繁體中文版維護者： 胡皓文 Hu Haowen <src.res.211@gmail.com> +繁體中文版翻譯者： 胡皓文 Hu Haowen <src.res.211@gmail.com> +繁體中文版校譯者： 胡皓文 Hu Haowen <src.res.211@gmail.com> 以下爲正文 diff --git a/Documentation/translations/zh_TW/process/1.Intro.rst b/Documentation/translations/zh_TW/process/1.Intro.rst index ca2b931be6c5..6e754ac48964 100644 --- a/Documentation/translations/zh_TW/process/1.Intro.rst +++ b/Documentation/translations/zh_TW/process/1.Intro.rst @@ -11,7 +11,7 @@ :校譯: 吳想成 Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> .. _tw_development_process_intro: @@ -22,12 +22,12 @@ -------- 本節的其餘部分涵蓋了內核開發的過程，以及開發人員及其僱主在這方面可能遇到的 -各種問題。有很多原因使內核代碼應被合併到正式的（「主線」）內核中，包括對用戶 +各種問題。有很多原因使內核代碼應被合併到正式的（“主線”）內核中，包括對用戶 的自動可用性、多種形式的社區支持以及影響內核開發方向的能力。提供給Linux內核 的代碼必須在與GPL兼容的許可證下可用。 -:ref:`tw_development_process` 介紹了開發過程、內核發布周期和合併窗口的機制。 -涵蓋了補丁開發、審查和合併周期中的各個階段。還有一些關於工具和郵件列表的討論？ +:ref:`tw_development_process` 介紹了開發過程、內核發佈週期和合並窗口的機制。 +涵蓋了補丁開發、審查和合並週期中的各個階段。還有一些關於工具和郵件列表的討論？ 鼓勵希望開始內核開發的開發人員跟蹤並修復缺陷以作爲初步練習。 @@ -38,39 +38,39 @@ 陷阱。也涵蓋了對補丁的一些要求，並且介紹了一些工具，這些工具有助於確保內核 補丁是正確的。 -:ref:`tw_development_posting` 描述發布補丁以供評審的過程。爲了讓開發社區能 +:ref:`tw_development_posting` 描述發佈補丁以供評審的過程。爲了讓開發社區能 認真對待，補丁必須被正確格式化和描述，並且必須發送到正確的地方。遵循本節中的 建議有助於確保您的工作能被較好地接納。 -:ref:`tw_development_followthrough` 介紹了發布補丁之後發生的事情；工作在這時 +:ref:`tw_development_followthrough` 介紹了發佈補丁之後發生的事情；工作在這時 還遠遠沒有完成。與審閱者一起工作是開發過程中的一個重要部分；本節提供了一些 關於如何在這個重要階段避免問題的提示。當補丁被合併到主線中時，開發人員要注意 不要假定任務已經完成。 -:ref:`tw_development_advancedtopics` 介紹了兩個「高級」主題：使用Git管理補丁 -和查看其他人發布的補丁。 +:ref:`tw_development_advancedtopics` 介紹了兩個“高級”主題：使用Git管理補丁 +和查看其他人發佈的補丁。 :ref:`tw_development_conclusion` 總結了有關內核開發的更多信息，附帶有相關資源 -連結。 +鏈接。 這個文檔是關於什麼的 -------------------- Linux內核有超過800萬行代碼，每個版本的貢獻者超過1000人，是現存最大、最活躍的 -免費軟體項目之一。從1991年開始，這個內核已經發展成爲一個最好的作業系統組件， -運行在袖珍數位音樂播放器、桌上型電腦、現存最大的超級計算機以及所有類型的系統上。 +免費軟件項目之一。從1991年開始，這個內核已經發展成爲一個最好的操作系統組件， +運行在袖珍數字音樂播放器、臺式電腦、現存最大的超級計算機以及所有類型的系統上。 它是一種適用於幾乎任何情況的健壯、高效和可擴展的解決方案。 -隨著Linux的發展，希望參與其開發的開發人員（和公司）的數量也在增加。硬體供應商 +隨着Linux的發展，希望參與其開發的開發人員（和公司）的數量也在增加。硬件供應商 希望確保Linux能夠很好地支持他們的產品，使這些產品對Linux用戶具有吸引力。嵌入 式系統供應商使用Linux作爲集成產品的組件，希望Linux能夠儘可能地勝任手頭的任務。 -分銷商和其他基於Linux的軟體供應商切實關心Linux內核的功能、性能和可靠性。最終 +分銷商和其他基於Linux的軟件供應商切實關心Linux內核的功能、性能和可靠性。最終 用戶也常常希望修改Linux，使之能更好地滿足他們的需求。 Linux最引人注目的特性之一是這些開發人員可以訪問它；任何具備必要技能的人都可以 -改進Linux並影響其開發方向。專有產品不能提供這種開放性，這是自由軟體的一個特點。 -如果有什麼不同的話，那就是內核比大多數其他自由軟體項目更開放。一個典型的三個 -月內核開發周期可以涉及1000多個開發人員，他們爲100多個不同的公司（或者根本不 +改進Linux並影響其開發方向。專有產品不能提供這種開放性，這是自由軟件的一個特點。 +如果有什麼不同的話，那就是內核比大多數其他自由軟件項目更開放。一個典型的三個 +月內核開發週期可以涉及1000多個開發人員，他們爲100多個不同的公司（或者根本不 隸屬公司）工作。 與內核開發社區合作並不是特別困難。但儘管如此，仍有許多潛在的貢獻者在嘗試做 @@ -79,7 +79,7 @@ Linux最引人注目的特性之一是這些開發人員可以訪問它；任何 過程與專有的開發模式有很大的不同也就不足爲奇了。 對於新開發人員來說，內核的開發過程可能會讓人感到奇怪和恐懼，但這背後有充分的 -理由和堅實的經驗。一個不了解內核社區工作方式的開發人員（或者更糟的是，他們 +理由和堅實的經驗。一個不瞭解內核社區工作方式的開發人員（或者更糟的是，他們 試圖拋棄或規避之）會得到令人沮喪的體驗。開發社區在幫助那些試圖學習的人的同時， 沒有時間幫助那些不願意傾聽或不關心開發過程的人。 @@ -102,20 +102,20 @@ Andrew Morton, Andrew Price, Tsugikazu Shibata 和 Jochen Voß 。 -------------------- 有些公司和開發人員偶爾會想，爲什麼他們要費心學習如何與內核社區合作，並將代碼 -放入主線內核（「主線」是由Linus Torvalds維護的內核，Linux發行商將其用作基礎）。 +放入主線內核（“主線”是由Linus Torvalds維護的內核，Linux發行商將其用作基礎）。 在短期內，貢獻代碼看起來像是一種可以避免的開銷；維護獨立代碼並直接支持用戶 -似乎更容易。事實上，保持代碼獨立（「樹外」）是在經濟上是錯誤的。 +似乎更容易。事實上，保持代碼獨立（“樹外”）是在經濟上是錯誤的。 爲了說明樹外代碼成本，下面給出內核開發過程的一些相關方面；本文稍後將更詳細地 討論其中的大部分內容。請考慮： - 所有Linux用戶都可以使用合併到主線內核中的代碼。它將自動出現在所有啓用它的 - 發行版上。無需驅動程序磁碟、額外下載，也不需要爲多個發行版的多個版本提供 + 發行版上。無需驅動程序磁盤、額外下載，也不需要爲多個發行版的多個版本提供 支持；這一切將方便所有開發人員和用戶。併入主線解決了大量的分發和支持問題。 - 當內核開發人員努力維護一個穩定的用戶空間接口時，內核內部API處於不斷變化之中。 不維持穩定的內部接口是一個慎重的設計決策；它允許在任何時候進行基本的改進， - 並產出更高質量的代碼。但該策略導致結果是，若要使用新的內核，任何樹外代碼都 + 併產出更高質量的代碼。但該策略導致結果是，若要使用新的內核，任何樹外代碼都 需要持續的維護。維護樹外代碼會需要大量的工作才能使代碼保持正常運行。 相反，位於主線中的代碼不需要這樣做，因爲基本規則要求進行API更改的任何開發 @@ -140,60 +140,60 @@ Andrew Morton, Andrew Price, Tsugikazu Shibata 和 Jochen Voß 。 - 代碼的貢獻是使整個流程工作的根本。通過貢獻代碼，您可以向內核添加新功能，並 提供其他內核開發人員使用的功能和示例。如果您已經爲Linux開發了代碼（或者正在 - 考慮這樣做），那麼您顯然對這個平台的持續成功感興趣；貢獻代碼是確保成功的 + 考慮這樣做），那麼您顯然對這個平臺的持續成功感興趣；貢獻代碼是確保成功的 最好方法之一。 -上述所有理由都適用於任何樹外內核代碼，包括以專有的、僅二進位形式分發的代碼。 -然而，在考慮任何類型的純二進位內核代碼分布之前，還需要考慮其他因素。包括： +上述所有理由都適用於任何樹外內核代碼，包括以專有的、僅二進制形式分發的代碼。 +然而，在考慮任何類型的純二進制內核代碼分佈之前，還需要考慮其他因素。包括： - 圍繞專有內核模塊分發的法律問題其實較爲模糊；相當多的內核版權所有者認爲， - 大多數僅二進位的模塊是內核的派生產品，因此，它們的分發違反了GNU通用公共 + 大多數僅二進制的模塊是內核的派生產品，因此，它們的分發違反了GNU通用公共 許可證（下面將詳細介紹）。本文作者不是律師，本文檔中的任何內容都不可能被 - 視爲法律建議。封閉原始碼模塊的真實法律地位只能由法院決定。但不管怎樣，困擾 + 視爲法律建議。封閉源代碼模塊的真實法律地位只能由法院決定。但不管怎樣，困擾 這些模塊的不確定性仍然存在。 -- 二進位模塊大大增加了調試內核問題的難度，以至於大多數內核開發人員甚至都不會 - 嘗試。因此，只分發二進位模塊將使您的用戶更難從社區獲得支持。 +- 二進制模塊大大增加了調試內核問題的難度，以至於大多數內核開發人員甚至都不會 + 嘗試。因此，只分發二進制模塊將使您的用戶更難從社區獲得支持。 -- 對於僅二進位的模塊的發行者來說，支持也更加困難，他們必須爲他們希望支持的 +- 對於僅二進制的模塊的發行者來說，支持也更加困難，他們必須爲他們希望支持的 每個發行版和每個內核版本提供不同版本的模塊。爲了提供較爲全面的覆蓋範圍， 可能需要一個模塊的幾十個構建，並且每次升級內核時，您的用戶都必須單獨升級 這些模塊。 -- 上面提到的關於代碼評審的所有問題都更加存在於封閉原始碼中。由於該代碼根本 +- 上面提到的關於代碼評審的所有問題都更加存在於封閉源代碼中。由於該代碼根本 不可得，因此社區無法對其進行審查，毫無疑問，它將存在嚴重問題。 尤其是嵌入式系統的製造商，可能會傾向於忽視本節中所說的大部分內容；因爲他們 -相信自己正在商用一種使用凍結內核版本的獨立產品，在發布後不需要再進行開發。 +相信自己正在商用一種使用凍結內核版本的獨立產品，在發佈後不需要再進行開發。 這個論點忽略了廣泛的代碼審查的價值以及允許用戶向產品添加功能的價值。但這些 -產品的商業壽命有限，之後必須發布新版本的產品。在這一點上，代碼在主線上並得到 -良好維護的供應商將能夠更好地占位，以使新產品快速上市。 +產品的商業壽命有限，之後必須發佈新版本的產品。在這一點上，代碼在主線上並得到 +良好維護的供應商將能夠更好地佔位，以使新產品快速上市。 許可 ---- 代碼是根據一些許可證提供給Linux內核的，但是所有代碼都必須與GNU通用公共許可 證（GPLV2）的版本2兼容，該版本是覆蓋整個內核分發的許可證。在實踐中，這意味 -著所有代碼貢獻都由GPLv2（可選地，語言允許在更高版本的GPL下分發）或3子句BSD +着所有代碼貢獻都由GPLv2（可選地，語言允許在更高版本的GPL下分發）或3子句BSD 許可（New BSD License，譯者注）覆蓋。任何不包含在兼容許可證中的貢獻都不會 被接受到內核中。 貢獻給內核的代碼不需要（或請求）版權分配。合併到主線內核中的所有代碼都保留 其原始所有權；因此，內核現在擁有數千個所有者。 -這種所有權結構也暗示著，任何改變內核許可的嘗試都註定會失敗。很少有實際情況 +這種所有權結構也暗示着，任何改變內核許可的嘗試都註定會失敗。很少有實際情況 可以獲得所有版權所有者的同意（或者從內核中刪除他們的代碼）。因此，尤其是在 可預見的將來，許可證不大可能遷移到GPL的版本3。 -所有貢獻給內核的代碼都必須是合法的免費軟體。因此，不接受匿名（或化名）貢獻 -者的代碼。所有貢獻者都需要在他們的代碼上「sign off（簽發）」，聲明代碼可以 -在GPL下與內核一起分發。無法提供未被其所有者許可爲免費軟體的代碼，或可能爲 +所有貢獻給內核的代碼都必須是合法的免費軟件。因此，不接受匿名（或化名）貢獻 +者的代碼。所有貢獻者都需要在他們的代碼上“sign off（簽發）”，聲明代碼可以 +在GPL下與內核一起分發。無法提供未被其所有者許可爲免費軟件的代碼，或可能爲 內核造成版權相關問題的代碼（例如，由缺乏適當保護的反向工程工作派生的代碼） 不能被接受。 有關版權問題的提問在Linux開發郵件列表中很常見。這樣的問題通常會得到不少答案， -但請記住，回答這些問題的人不是律師，不能提供法律諮詢。如果您有關於Linux原始碼 -的法律問題，沒有什麼可以代替諮詢了解這一領域的律師。依賴從技術郵件列表中獲得 +但請記住，回答這些問題的人不是律師，不能提供法律諮詢。如果您有關於Linux源代碼 +的法律問題，沒有什麼可以代替諮詢瞭解這一領域的律師。依賴從技術郵件列表中獲得 的答案是一件冒險的事情。 diff --git a/Documentation/translations/zh_TW/process/2.Process.rst b/Documentation/translations/zh_TW/process/2.Process.rst index 9d465df1f6c3..49385d65c216 100644 --- a/Documentation/translations/zh_TW/process/2.Process.rst +++ b/Documentation/translations/zh_TW/process/2.Process.rst @@ -11,7 +11,7 @@ :校譯: 吳想成 Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> .. _tw_development_process: @@ -26,8 +26,8 @@ 總覽 ---- -內核開發人員使用一個鬆散的基於時間的發布過程，每兩到三個月發布一次新的主要 -內核版本。最近的發布歷史記錄如下： +內核開發人員使用一個鬆散的基於時間的發佈過程，每兩到三個月發佈一次新的主要 +內核版本。最近的發佈歷史記錄如下： ====== ================= 5.0 2019年3月3日 @@ -42,33 +42,33 @@ 版本包含大約13000個變更集，變更了幾十萬行代碼。因此，5.x是Linux內核開發的前 沿；內核使用滾動開發模型，不斷集成重大變化。 -對於每個版本的補丁合併，遵循一個相對簡單的規則。在每個開發周期的開頭，「合併 -窗口」被打開。這時，被認爲足夠穩定（並且被開發社區接受）的代碼被合併到主線內 -核中。在這段時間內，新開發周期的大部分變更（以及所有主要變更）將以接近每天 -1000次變更（「補丁」或「變更集」）的速度合併。 +對於每個版本的補丁合併，遵循一個相對簡單的規則。在每個開發週期的開頭，“合併 +窗口”被打開。這時，被認爲足夠穩定（並且被開發社區接受）的代碼被合併到主線內 +核中。在這段時間內，新開發週期的大部分變更（以及所有主要變更）將以接近每天 +1000次變更（“補丁”或“變更集”）的速度合併。 （順便說一句，值得注意的是，合併窗口期間集成的更改並不是憑空產生的；它們是經 提前收集、測試和分級的。稍後將詳細描述該過程的工作方式。） -合併窗口持續大約兩周。在這段時間結束時，LinusTorvalds將聲明窗口已關閉，並 -釋放第一個「rc」內核。例如，對於目標爲5.6的內核，在合併窗口結束時發生的釋放 +合併窗口持續大約兩週。在這段時間結束時，Linus Torvalds將聲明窗口已關閉，並 +釋放第一個“rc”內核。例如，對於目標爲5.6的內核，在合併窗口結束時發生的釋放 將被稱爲5.6-rc1。-rc1 版本是一個信號，表示合併新特性的時間已經過去，穩定下一 個內核的時間已經到來。 在接下來的6到10周內，只有修復問題的補丁才應該提交給主線。有時會允許更大的 更改，但這種情況很少發生；試圖在合併窗口外合併新功能的開發人員往往受不到 友好的接待。一般來說，如果您錯過了給定特性的合併窗口，最好的做法是等待下一 -個開發周期。（偶爾會對未支持硬體的驅動程序進行例外；如果它們不改變已有代碼， -則不會導致回歸，應該可以隨時被安全地加入）。 +個開發週期。（偶爾會對未支持硬件的驅動程序進行例外；如果它們不改變已有代碼， +則不會導致迴歸，應該可以隨時被安全地加入）。 -隨著修復程序進入主線，補丁速度將隨著時間的推移而變慢。Linus大約每周發布一次 -新的-rc內核；在內核被認爲足夠穩定並最終發布前，一般會達到-rc6到-rc9之間。 +隨着修復程序進入主線，補丁速度將隨着時間的推移而變慢。Linus大約每週發佈一次 +新的-rc內核；在內核被認爲足夠穩定並最終發佈前，一般會達到-rc6到-rc9之間。 然後，整個過程又重新開始了。 -例如，這裡是5.4的開發周期進行情況（2019年）: +例如，這裏是5.4的開發週期進行情況（2019年）: ============== ============================== - 九月 15 5.3 穩定版發布 + 九月 15 5.3 穩定版發佈 九月 30 5.4-rc1 合併窗口關閉 十月 6 5.4-rc2 十月 13 5.4-rc3 @@ -77,26 +77,26 @@ 十一月 3 5.4-rc6 十一月 10 5.4-rc7 十一月 17 5.4-rc8 - 十一月 24 5.4 穩定版發布 + 十一月 24 5.4 穩定版發佈 ============== ============================== -開發人員如何決定何時結束開發周期並創建穩定版本？最重要的指標是以前版本的 -回歸列表。不歡迎出現任何錯誤，但是那些破壞了以前能工作的系統的錯誤被認爲是 -特別嚴重的。因此，導致回歸的補丁是不受歡迎的，很可能在穩定期內刪除。 +開發人員如何決定何時結束開發週期並創建穩定版本？最重要的指標是以前版本的 +迴歸列表。不歡迎出現任何錯誤，但是那些破壞了以前能工作的系統的錯誤被認爲是 +特別嚴重的。因此，導致迴歸的補丁是不受歡迎的，很可能在穩定期內刪除。 -開發人員的目標是在穩定發布之前修復所有已知的回歸。在現實世界中，這種完美是 +開發人員的目標是在穩定發佈之前修復所有已知的迴歸。在現實世界中，這種完美是 很難實現的；在這種規模的項目中，變數太多了。需要說明的是，延遲最終版本只會 -使問題變得更糟；等待下一個合併窗口的更改將變多，導致下次出現更多的回歸錯誤。 -因此，大多數5.x內核都有一些已知的回歸錯誤，不過，希望沒有一個是嚴重的。 +使問題變得更糟；等待下一個合併窗口的更改將變多，導致下次出現更多的迴歸錯誤。 +因此，大多數5.x內核都有一些已知的迴歸錯誤，不過，希望沒有一個是嚴重的。 -一旦一個穩定的版本發布，它的持續維護工作就被移交給「穩定團隊」，目前由 -Greg Kroah-Hartman領導。穩定團隊將使用5.x.y編號方案不定期地發布穩定版本的 +一旦一個穩定的版本發佈，它的持續維護工作就被移交給“穩定團隊”，目前由 +Greg Kroah-Hartman領導。穩定團隊將使用5.x.y編號方案不定期地發佈穩定版本的 更新。要合入更新版本，補丁必須（1）修復一個重要的缺陷，且（2）已經合併到 -下一個開發版本主線中。內核通常會在其初始版本後的一個以上的開發周期內收到 +下一個開發版本主線中。內核通常會在其初始版本後的一個以上的開發週期內收到 穩定版更新。例如，5.2內核的歷史如下（2019年）： ============== =============================== - 七月 7 5.2 穩定版發布 + 七月 7 5.2 穩定版發佈 七月 13 5.2.1 七月 21 5.2.2 七月 26 5.2.3 @@ -108,7 +108,7 @@ Greg Kroah-Hartman領導。穩定團隊將使用5.x.y編號方案不定期地發 5.2.21是5.2版本的最終穩定更新。 -有些內核被指定爲「長期」內核；它們將得到更長時間的支持。在本文中，當前的長期 +有些內核被指定爲“長期”內核；它們將得到更長時間的支持。在本文中，當前的長期 內核及其維護者是： ====== ================================ ================ @@ -121,9 +121,9 @@ Greg Kroah-Hartman領導。穩定團隊將使用5.x.y編號方案不定期地發 ====== ================================ ================ 長期支持內核的選擇純粹是維護人員是否有需求和時間來維護該版本的問題。 -目前還沒有爲即將發布的任何特定版本提供長期支持的已知計劃。 +目前還沒有爲即將發佈的任何特定版本提供長期支持的已知計劃。 -補丁的生命周期 +補丁的生命週期 -------------- 補丁不會直接從開發人員的鍵盤進入主線內核。相反，有一個稍微複雜（如果有些非 @@ -140,7 +140,7 @@ Greg Kroah-Hartman領導。穩定團隊將使用5.x.y編號方案不定期地發 是在不涉及社區的情況下完成的，但是如果可能的話，最好是在公開的情況下完成 這項工作；這樣可以節省很多稍後再重新設計的時間。 -- 早期評審。補丁被發布到相關的郵件列表中，列表中的開發人員會回復他們可能有 +- 早期評審。補丁被髮布到相關的郵件列表中，列表中的開發人員會回覆他們可能有 的任何評論。如果一切順利的話，這個過程應該會發現補丁的任何主要問題。 - 更廣泛的評審。當補丁接近準備好納入主線時，它應該被相關的子系統維護人員 @@ -153,48 +153,48 @@ Greg Kroah-Hartman領導。穩定團隊將使用5.x.y編號方案不定期地發 如果您的補丁得到了需要更改的反饋，那麼您應該進行這些更改，或者解釋爲何 不應該進行這些更改。如果您的補丁沒有評審意見，也沒有被其相應的子系統或 驅動程序維護者接受，那麼您應該堅持不懈地將補丁更新到當前內核使其可被正常 - 應用，並不斷地發送它以供審查和合併。 + 應用，並不斷地發送它以供審查和合並。 - 合併到主線。最終，一個成功的補丁將被合併到由LinusTorvalds管理的主線存儲庫 中。此時可能會出現更多的評論和/或問題；對開發人員來說應對這些問題並解決 出現的任何問題仍很重要。 -- 穩定版發布。大量用戶可能受此補丁影響，因此可能再次出現新的問題。 +- 穩定版發佈。大量用戶可能受此補丁影響，因此可能再次出現新的問題。 - 長期維護。雖然開發人員在合併代碼後可能會忘記代碼，但這種行爲往往會給開發 社區留下不良印象。合併代碼消除了一些維護負擔，因爲其他人將修復由API更改 引起的問題。但是，如果代碼要長期保持可用，原始開發人員應該繼續爲代碼負責。 -內核開發人員（或他們的僱主）犯的最大錯誤之一是試圖將流程簡化爲一個「合併到 -主線」步驟。這種方法總是會讓所有相關人員感到沮喪。 +內核開發人員（或他們的僱主）犯的最大錯誤之一是試圖將流程簡化爲一個“合併到 +主線”步驟。這種方法總是會讓所有相關人員感到沮喪。 補丁如何進入內核 ---------------- -只有一個人可以將補丁合併到主線內核存儲庫中：LinusTorvalds。但是，在進入 +只有一個人可以將補丁合併到主線內核存儲庫中：Linus Torvalds。但是，在進入 2.6.38內核的9500多個補丁中，只有112個（大約1.3%）是由Linus自己直接選擇的。 內核項目已經發展到一個沒有一個開發人員可以在沒有支持的情況下檢查和選擇每個 補丁的規模。內核開發人員處理這種增長的方式是使用圍繞信任鏈構建的助理系統。 內核代碼庫在邏輯上被分解爲一組子系統：網絡、特定體系結構支持、內存管理、視 頻設備等。大多數子系統都有一個指定的維護人員，其總體負責該子系統中的代碼。 -這些子系統維護者（鬆散地）是他們所管理的內核部分的「守門員」；他們（通常） +這些子系統維護者（鬆散地）是他們所管理的內核部分的“守門員”；他們（通常） 會接受一個補丁以包含到主線內核中。 -子系統維護人員每個人都管理著自己版本的內核原始碼樹，通常（並非總是）使用Git。 +子系統維護人員每個人都管理着自己版本的內核源代碼樹，通常（並非總是）使用Git。 Git等工具（以及Quilt或Mercurial等相關工具）允許維護人員跟蹤補丁列表，包括作者 信息和其他元數據。在任何給定的時間，維護人員都可以確定他或她的存儲庫中的哪 些補丁在主線中找不到。 -當合併窗口打開時，頂級維護人員將要求Linus從存儲庫中「拉出」他們爲合併選擇 +當合並窗口打開時，頂級維護人員將要求Linus從存儲庫中“拉出”他們爲合併選擇 的補丁。如果Linus同意，補丁流將流向他的存儲庫，成爲主線內核的一部分。 Linus對拉取中接收到的特定補丁的關注程度各不相同。很明顯，有時他看起來很 -關注。但是一般來說，Linus相信子系統維護人員不會向上游發送壞補丁。 +關注。但是一般來說，Linus相信子系統維護人員不會向上遊發送壞補丁。 -子系統維護人員反過來也可以從其他維護人員那裡獲取補丁。例如，網絡樹是由首先 +子系統維護人員反過來也可以從其他維護人員那裏獲取補丁。例如，網絡樹是由首先 在專用於網絡設備驅動程序、無線網絡等的樹中積累的補丁構建的。此存儲鏈可以 -任意長，但很少超過兩個或三個連結。由於鏈中的每個維護者都信任那些管理較低 -級別樹的維護者，所以這個過程稱爲「信任鏈」。 +任意長，但很少超過兩個或三個鏈接。由於鏈中的每個維護者都信任那些管理較低 +級別樹的維護者，所以這個過程稱爲“信任鏈”。 顯然，在這樣的系統中，獲取內核補丁取決於找到正確的維護者。直接向Linus發送 補丁通常不是正確的方法。 @@ -204,30 +204,30 @@ Next 樹 子系統樹鏈引導補丁流到內核，但它也提出了一個有趣的問題：如果有人想查看爲 下一個合併窗口準備的所有補丁怎麼辦？開發人員將感興趣的是，還有什麼其他的 -更改有待解決，以了解是否存在需要擔心的衝突；例如，更改核心內核函數原型的 +更改有待解決，以瞭解是否存在需要擔心的衝突；例如，更改核心內核函數原型的 修補程序將與使用該函數舊形式的任何其他修補程序衝突。審查人員和測試人員希望 在所有這些變更到達主線內核之前，能夠訪問它們的集成形式的變更。您可以從所有 相關的子系統樹中提取更改，但這將是一項複雜且容易出錯的工作。 -解決方案以-next樹的形式出現，在這裡子系統樹被收集以供測試和審查。這些樹中 -由Andrew Morton維護的較老的一個，被稱爲「-mm」（用於內存管理，創建時爲此）。 +解決方案以-next樹的形式出現，在這裏子系統樹被收集以供測試和審查。這些樹中 +由Andrew Morton維護的較老的一個，被稱爲“-mm”（用於內存管理，創建時爲此）。 -mm 樹集成了一長串子系統樹中的補丁；它還包含一些旨在幫助調試的補丁。 除此之外，-mm 還包含大量由Andrew直接選擇的補丁。這些補丁可能已經發布在郵件 列表上，或者它們可能應用於內核中未指定子系統樹的部分。同時，-mm 作爲最後 手段的子系統樹；如果沒有其他明顯的路徑可以讓補丁進入主線，那麼它很可能最 終選擇-mm 樹。累積在-mm 中的各種補丁最終將被轉發到適當的子系統樹，或者直接 -發送到Linus。在典型的開發周期中，大約5-10%的補丁通過-mm 進入主線。 +發送到Linus。在典型的開發週期中，大約5-10%的補丁通過-mm 進入主線。 -當前-mm 補丁可在「mmotm」（-mm of the moment）目錄中找到： +當前-mm 補丁可在“mmotm”（-mm of the moment）目錄中找到： https://www.ozlabs.org/~akpm/mmotm/ 然而，使用MMOTM樹可能會十分令人頭疼；它甚至可能無法編譯。 -下一個周期補丁合併的主要樹是linux-next，由Stephen Rothwell 維護。根據設計 +下一個週期補丁合併的主要樹是linux-next，由Stephen Rothwell 維護。根據設計 linux-next 是下一個合併窗口關閉後主線的快照。linux-next樹在Linux-kernel 和 -Linux-next 郵件列表中發布，可從以下位置下載： +Linux-next 郵件列表中發佈，可從以下位置下載： https://www.kernel.org/pub/linux/kernel/next/ @@ -237,7 +237,7 @@ Linux-next 已經成爲內核開發過程中不可或缺的一部分；在一個 Staging 樹 ---------- -內核原始碼樹包含drivers/staging/目錄，其中有許多驅動程序或文件系統的子目錄 +內核源代碼樹包含drivers/staging/目錄，其中有許多驅動程序或文件系統的子目錄 正在被添加到內核樹中。它們在仍然需要更多的修正的時候可以保留在driver/staging/ 目錄中；一旦完成，就可以將它們移到內核中。這是一種跟蹤不符合Linux內核編碼或 質量標準的驅動程序的方法，人們可能希望使用它們並跟蹤開發。 @@ -251,7 +251,7 @@ Greg Kroah Hartman 目前負責維護staging 樹。仍需要修正的驅動程 Staging 是一種讓新的驅動程序進入主線的相對容易的方法，它們會幸運地引起其他 開發人員的注意，並迅速改進。然而，進入staging並不是故事的結尾；staging中 沒有看到常規進展的代碼最終將被刪除。經銷商也傾向於相對不願意使用staging驅動 -程序。因此，在成爲一個合適的主線驅動的路上，staging 僅是一個中轉站。 +程序。因此，在成爲一個合適的主線驅動的路上，staging 僅是一箇中轉站。 工具 ---- @@ -260,9 +260,9 @@ Staging 是一種讓新的驅動程序進入主線的相對容易的方法，它 能力。如果沒有適當強大的工具，整個系統將無法在任何地方正常工作。關於如何使用 這些工具的教程遠遠超出了本文檔的範圍，但還是用一點篇幅介紹一些關鍵點。 -到目前爲止，內核社區使用的主要原始碼管理系統是git。Git是在自由軟體社區中開發 -的許多分布式版本控制系統之一。它非常適合內核開發，因爲它在處理大型存儲庫和 -大量補丁時性能非常好。它也以難以學習和使用而著稱，儘管隨著時間的推移它變得 +到目前爲止，內核社區使用的主要源代碼管理系統是git。Git是在自由軟件社區中開發 +的許多分佈式版本控制系統之一。它非常適合內核開發，因爲它在處理大型存儲庫和 +大量補丁時性能非常好。它也以難以學習和使用而著稱，儘管隨着時間的推移它變得 更好了。對於內核開發人員來說，對Git的某種熟悉幾乎是一種要求；即使他們不將它 用於自己的工作，他們也需要Git來跟上其他開發人員（以及主線）正在做的事情。 @@ -270,7 +270,7 @@ Staging 是一種讓新的驅動程序進入主線的相對容易的方法，它 https://git-scm.com/ -此頁面包含了文檔和教程的連結。 +此頁面包含了文檔和教程的鏈接。 在不使用git的內核開發人員中，最流行的選擇幾乎肯定是Mercurial： @@ -282,16 +282,16 @@ Mercurial與Git共享許多特性，但它提供了一個界面，許多人覺 https://savannah.nongnu.org/projects/quilt -Quilt 是一個補丁管理系統，而不是原始碼管理系統。它不會隨著時間的推移跟蹤歷史； +Quilt 是一個補丁管理系統，而不是源代碼管理系統。它不會隨着時間的推移跟蹤歷史； 相反，它面向根據不斷發展的代碼庫跟蹤一組特定的更改。一些主要的子系統維護人員 -使用Quilt來管理打算向上游移動的補丁。對於某些樹的管理（例如-mm），quilt 是 +使用Quilt來管理打算向上遊移動的補丁。對於某些樹的管理（例如-mm），quilt 是 最好的工具。 郵件列表 -------- 大量的Linux內核開發工作是通過郵件列表完成的。如果不加入至少一個某個列表， -就很難成爲社區中的一個「全功能」成員。但是，Linux郵件列表對開發人員來說也是 +就很難成爲社區中的一個“全功能”成員。但是，Linux郵件列表對開發人員來說也是 一個潛在的危險，他們可能會被一堆電子郵件淹沒、違反Linux列表上使用的約定， 或者兩者兼而有之。 @@ -316,14 +316,14 @@ redhat.com/mailman/listinfo。 - 不要回復挑事的人。如果有人試圖激起憤怒，請忽略他們。 -- 當回復Linux內核電子郵件（或其他列表上的電子郵件）時，請爲所有相關人員保留 +- 當回覆Linux內核電子郵件（或其他列表上的電子郵件）時，請爲所有相關人員保留 Cc: 抄送頭。如果沒有確實的理由（如明確的請求），則不應刪除收件人。一定要 確保你要回復的人在抄送列表中。這個慣例也使你不必在回覆郵件時明確要求被抄送。 - 在提出問題之前，搜索列表存檔（和整個網絡）。有些開發人員可能會對那些顯然 沒有完成家庭作業的人感到不耐煩。 -- 避免頂部回復（把你的答案放在你要回復的引文上面的做法）。這會讓你的回答更難 +- 避免頂部回覆（把你的答案放在你要回復的引文上面的做法）。這會讓你的回答更難 理解，印象也很差。 - 在正確的郵件列表發問。linux-kernel 可能是通用的討論場所，但它不是尋找所有 @@ -332,7 +332,7 @@ redhat.com/mailman/listinfo。 最後一點——找到正確的郵件列表——是開發人員常出錯的地方。在linux-kernel上 提出與網絡相關的問題的人幾乎肯定會收到一個禮貌的建議，轉到netdev列表上提出， 因爲這是大多數網絡開發人員經常出現的列表。還有其他列表可用於scsi、video4linux、 -ide、filesystem等子系統。查找郵件列表的最佳位置是與內核原始碼一起打包的 +ide、filesystem等子系統。查找郵件列表的最佳位置是與內核源代碼一起打包的 MAINTAINERS文件。 開始內核開發 @@ -344,7 +344,7 @@ MAINTAINERS文件。 公司通常希望聘請知名的開發人員來啓動開發團隊。實際上，這是一種有效的技術。 但它也往往是昂貴的，而且對增加有經驗的內核開發人員的數量沒有多大幫助。考 慮到時間投入，可以讓內部開發人員加快Linux內核的開發速度。利用這段時間可以 -讓僱主擁有一批既了解內核又了解公司的開發人員，還可以幫助培訓其他人。從中期 +讓僱主擁有一批既瞭解內核又瞭解公司的開發人員，還可以幫助培訓其他人。從中期 來看，這通常是更有利可圖的方法。 可以理解的是，單個開發人員往往對起步感到茫然。從一個大型項目開始可能會很 @@ -353,17 +353,17 @@ MAINTAINERS文件。 這會分散整個開發社區的注意力，因此，它們越來越被人不看重。希望向社區介紹 自己的新開發人員將無法通過這些方式獲得他們期待的反響。 -Andrew Morton 爲有抱負的內核開發人員提供了如下建議 +Andrew Morton 爲有抱負的內核開發人員提供瞭如下建議 :: - 所有內核開發者的第一個項目肯定應該是「確保內核在您可以操作的所有 - 機器上始終完美運行」。通常的方法是和其他人一起解決問題（這可能需 + 所有內核開發者的第一個項目肯定應該是“確保內核在您可以操作的所有 + 機器上始終完美運行”。通常的方法是和其他人一起解決問題（這可能需 要堅持！），但就是如此——這是內核開發的一部分。 (http://lwn.net/Articles/283982/) -在沒有明顯問題需要解決的情況下，通常建議開發人員查看當前的回歸和開放缺陷 +在沒有明顯問題需要解決的情況下，通常建議開發人員查看當前的迴歸和開放缺陷 列表。從來都不缺少需要解決的問題；通過解決這些問題，開發人員將從該過程獲得 經驗，同時與開發社區的其他成員建立相互尊重。 diff --git a/Documentation/translations/zh_TW/process/3.Early-stage.rst b/Documentation/translations/zh_TW/process/3.Early-stage.rst index 076873ca0905..a6959e6350f4 100644 --- a/Documentation/translations/zh_TW/process/3.Early-stage.rst +++ b/Documentation/translations/zh_TW/process/3.Early-stage.rst @@ -11,7 +11,7 @@ :校譯: 吳想成 Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> .. _tw_development_early_stage: @@ -26,13 +26,13 @@ -------- 與任何工程項目一樣，成功的內核改善從清晰描述要解決的問題開始。在某些情況 -下，這個步驟很容易：例如當某個特定硬體需要驅動程序時。不過，在其他情況下， +下，這個步驟很容易：例如當某個特定硬件需要驅動程序時。不過，在其他情況下， 很容易將實際問題與建議的解決方案混在一起，這可能會導致麻煩。 -舉個例子：幾年前，Linux音頻的開發人員尋求一種方法來運行應用程式，而不會因 +舉個例子：幾年前，Linux音頻的開發人員尋求一種方法來運行應用程序，而不會因 系統延遲過大而導致退出或其他問題。他們得到的解決方案是一個連接到Linux安全 -模塊（LSM）框架中的內核模塊；這個模塊可以配置爲允許特定的應用程式訪問實時 -調度程序。這個模塊被實現並發到linux-kernel郵件列表，在那裡它立即遇到了麻煩。 +模塊（LSM）框架中的內核模塊；這個模塊可以配置爲允許特定的應用程序訪問實時 +調度程序。這個模塊被實現併發到linux-kernel郵件列表，在那裏它立即遇到了麻煩。 對於音頻開發人員來說，這個安全模塊足以解決他們當前的問題。但是，對於更廣泛的 內核社區來說，這被視爲對LSM框架的濫用（LSM框架並不打算授予他們原本不具備的 @@ -41,15 +41,15 @@ 然而，音頻社區無法超越他們實施的特定解決方案來看問題；他們不願意接受替代方案。 由此產生的分歧使這些開發人員對整個內核開發過程感到失望；其中一個開發人員返回 -到audio列表並發布了以下內容： +到audio列表併發布了以下內容： 有很多非常好的Linux內核開發人員，但他們往往會被一羣傲慢的傻瓜所壓倒。 - 試圖向這些人傳達用戶需求是浪費時間。他們太「聰明」了，根本聽不到少數 + 試圖向這些人傳達用戶需求是浪費時間。他們太“聰明”了，根本聽不到少數 人的話。 （http://lwn.net/Articles/131776/） -實際情況卻是不同的；與特定模塊相比，內核開發人員更關心系統穩定性、長期維護 +實際情況卻是不同的；與特定模塊相比，內核開發人員更關心繫統穩定性、長期維護 以及找到問題的正確解決方案。這個故事的寓意是把重點放在問題上——而不是具體的 解決方案上——並在開始編寫代碼之前與開發社區討論這個問題。 @@ -72,7 +72,7 @@ - 很可能問題是由內核以您不理解的方式解決的。Linux內核很大，具有許多不明顯 的特性和功能。並不是所有的內核功能都像人們所希望的那樣有文檔記錄，而且很 - 容易遺漏一些東西。某作者發布了一個完整的驅動程序，重複了一個其不 + 容易遺漏一些東西。某作者發佈了一個完整的驅動程序，重複了一個其不 知道的現有驅動程序。重新發明現有輪子的代碼不僅浪費，而且不會被接受到主線 內核中。 @@ -83,7 +83,7 @@ 可能願意幫助創建這個解決方案。 在內核開發社區的多年經驗給了我們一個明確的教訓：閉門設計和開發的內核代碼總是 -有一些問題，這些問題只有在代碼發布到社區中時才會被發現。有時這些問題很嚴重， +有一些問題，這些問題只有在代碼發佈到社區中時纔會被發現。有時這些問題很嚴重， 需要數月或數年的努力才能使代碼達到內核社區的標準。例如： - 設計並實現了單處理器系統的DeviceScape網絡棧。只有使其適合於多處理器系統， @@ -103,16 +103,16 @@ 找誰交流？ ---------- -當開發人員決定公開他們的計劃時，下一個問題是：我們從哪裡開始？答案是找到正確 +當開發人員決定公開他們的計劃時，下一個問題是：我們從哪裏開始？答案是找到正確 的郵件列表和正確的維護者。對於郵件列表，最好的方法是在維護者(MAINTAINERS)文件 -中查找要發布的相關位置。如果有一個合適的子系統列表，那麼其上發布通常比在 -linux-kernel上發布更可取；您更有可能接觸到在相關子系統中具有專業知識的開發 +中查找要發佈的相關位置。如果有一個合適的子系統列表，那麼其上發佈通常比在 +linux-kernel上發佈更可取；您更有可能接觸到在相關子系統中具有專業知識的開發 人員，並且環境可能具支持性。 找到維護人員可能會有點困難。同樣，維護者文件是開始的地方。但是，該文件往往不 -是最新的，並且並非所有子系統都在那裡顯示。實際上，維護者文件中列出的人員可能 +是最新的，並且並非所有子系統都在那裏顯示。實際上，維護者文件中列出的人員可能 不是當前實際擔任該角色的人員。因此，當對聯繫誰有疑問時，一個有用的技巧是使用 -git（尤其是「git-log」）查看感興趣的子系統中當前活動的用戶。看看誰在寫補丁、 +git（尤其是“git-log”）查看感興趣的子系統中當前活動的用戶。看看誰在寫補丁、 誰會在這些補丁上加上Signed-off-by行簽名（如有）。這些人將是幫助新開發項目的 最佳人選。 @@ -123,7 +123,7 @@ git（尤其是「git-log」）查看感興趣的子系統中當前活動的用 .../scripts/get_maintainer.pl -當給定「-f」選項時，此腳本將返回指定文件或目錄的當前維護者。如果在命令行上 +當給定“-f”選項時，此腳本將返回指定文件或目錄的當前維護者。如果在命令行上 給出了一個補丁，它將列出可能接收補丁副本的維護人員。有許多選項可以調節 get_maintainer.pl搜索維護者的嚴格程度；請小心使用更激進的選項，因爲最終結果 可能會包括對您正在修改的代碼沒有真正興趣的開發人員。 @@ -134,17 +134,17 @@ get_maintainer.pl搜索維護者的嚴格程度；請小心使用更激進的選 何時郵寄？ ---------- -如果可能的話，在早期階段發布你的計劃只會更有幫助。描述正在解決的問題以及已經 +如果可能的話，在早期階段發佈你的計劃只會更有幫助。描述正在解決的問題以及已經 制定的關於如何實施的任何計劃。您可以提供的任何信息都可以幫助開發社區爲項目 提供有用的輸入。 在這個階段可能發生的一件令人沮喪的事情不是得到反對意見，而是很少或根本沒有 反饋。令人傷心的事實是：（1）內核開發人員往往很忙；（2）不缺少有宏偉計劃但 代碼（甚至代碼設想）很少的人去支持他們；（3）沒有人有義務審查或評論別人發表 -的想法。除此之外，高層級的設計常常隱藏著一些問題，這些問題只有在有人真正嘗試 -實現這些設計時才會被發現；因此，內核開發人員寧願看到代碼。 +的想法。除此之外，高層級的設計常常隱藏着一些問題，這些問題只有在有人真正嘗試 +實現這些設計時纔會被發現；因此，內核開發人員寧願看到代碼。 -如果發布請求評論（RFC）並沒得到什麼有用的評論，不要以爲這意味著無人對此項目 +如果發佈請求評論（RFC）並沒得到什麼有用的評論，不要以爲這意味着無人對此項目 有興趣，同時你也不能假設你的想法沒有問題。在這種情況下，最好的做法是繼續進 行，把你的進展隨時通知社區。 @@ -152,12 +152,12 @@ get_maintainer.pl搜索維護者的嚴格程度；請小心使用更激進的選 ----------------------- 如果您的工作是在公司環境中完成的，就像大多數Linux內核工作一樣；顯然，在您將 -公司的計劃或代碼發布到公共郵件列表之前，必須獲得有適當權利經理的許可。發布 -不確定是否兼容GPL的代碼尤其會帶來問題；公司的管理層和法律人員越早能夠就發布 +公司的計劃或代碼發佈到公共郵件列表之前，必須獲得有適當權利經理的許可。發佈 +不確定是否兼容GPL的代碼尤其會帶來問題；公司的管理層和法律人員越早能夠就發佈 內核開發項目達成一致，對參與的每個人都越好。 一些讀者可能會認爲他們的核心工作是爲了支持還沒有正式承認存在的產品。將僱主 -的計劃公布在公共郵件列表上可能不是一個可行的選擇。在這種情況下，有必要考慮 +的計劃公佈在公共郵件列表上可能不是一個可行的選擇。在這種情況下，有必要考慮 保密是否真的是必要的；通常不需要把開發計劃關在門內。 的確，有些情況下一家公司在開發過程的早期無法合法地披露其計劃。擁有經驗豐富 diff --git a/Documentation/translations/zh_TW/process/4.Coding.rst b/Documentation/translations/zh_TW/process/4.Coding.rst index 7fc0344ed16b..7a4e01eabd81 100644 --- a/Documentation/translations/zh_TW/process/4.Coding.rst +++ b/Documentation/translations/zh_TW/process/4.Coding.rst @@ -11,7 +11,7 @@ :校譯: 吳想成 Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> .. _tw_development_coding: @@ -19,7 +19,7 @@ ====================== 雖然一個堅實的、面向社區的設計過程有很多值得說道的，但是任何內核開發項目工作 -的證明都反映在代碼中。它是將由其他開發人員檢查併合並（或不合併）到主線樹中 +的證明都反映在代碼中。它是將由其他開發人員檢查併合並（或不合並）到主線樹中 的代碼。所以這段代碼的質量決定了項目的最終成功。 本節將檢查編碼過程。我們將從內核開發人員常犯的幾種錯誤開始。然後重點將轉移 @@ -32,7 +32,7 @@ ******** 內核長期以來都有其標準的代碼風格，如 -:ref:`Documentation/translations/zh_TW/process/coding-style.rst <tw_codingstyle>` +:ref:`Documentation/translations/zh_CN/process/coding-style.rst <tw_codingstyle>` 中所述。在多數時候，該文檔中描述的準則至多被認爲是建議性的。因此，內核中存在 大量不符合代碼風格準則的代碼。這種代碼的存在會給內核開發人員帶來兩方面的危害。 @@ -42,7 +42,7 @@ 開發人員能夠快速理解其中的任何部分。所以再也經不起奇怪格式的代碼的折騰了。 內核的代碼風格偶爾會與僱主的強制風格發生衝突。在這種情況下，必須在代碼合併 -之前遵從內核代碼風格。將代碼放入內核意味著以多種方式放棄一定程度的控制權—— +之前遵從內核代碼風格。將代碼放入內核意味着以多種方式放棄一定程度的控制權—— 包括控制代碼樣式。 另一個危害是認爲已經在內核中的代碼迫切需要修復代碼樣式。開發者可能會開始編寫 @@ -70,21 +70,21 @@ 簡單點，先考慮一個調用時始終只有一個參數且總爲零的函數。我們可以保留這個參數， 以在需要使用它時提供的額外靈活性。不過，在那時實現了這個額外參數的代碼很有 可能以某種從未被注意到的微妙方式被破壞——因爲它從未被使用過。或者當需要額外 -的靈活性時，它並未以符合程式設計師當初期望的方式來實現。內核開發人員通常會提交 +的靈活性時，它並未以符合程序員當初期望的方式來實現。內核開發人員通常會提交 補丁來刪除未使用的參數；一般來說，一開始就不應該添加這些參數。 -隱藏硬體訪問的抽象層——通常爲了允許大量的驅動程序兼容多個作業系統——尤其不受 +隱藏硬件訪問的抽象層——通常爲了允許大量的驅動程序兼容多個操作系統——尤其不受 歡迎。這樣的層使代碼變得模糊，可能會造成性能損失；它們不屬於Linux內核。 另一方面，如果您發現自己從另一個內核子系統複製了大量的代碼，那麼是時候 -了解一下：是否需要將這些代碼中的部分提取到單獨的庫中，或者在更高的層次上 +瞭解一下：是否需要將這些代碼中的部分提取到單獨的庫中，或者在更高的層次上 實現這些功能。在整個內核中複製相同的代碼沒有價值。 #ifdef 和預處理 *************** -C預處理器似乎給一些C程式設計師帶來了強大的誘惑，他們認爲它是一種將大量靈活性加入 -原始碼中的方法。但是預處理器不是C，大量使用它會導致代碼對其他人來說更難閱讀， +C預處理器似乎給一些C程序員帶來了強大的誘惑，他們認爲它是一種將大量靈活性加入 +源代碼中的方法。但是預處理器不是C，大量使用它會導致代碼對其他人來說更難閱讀， 對編譯器來說更難檢查正確性。使用了大量預處理器幾乎總是代碼需要一些 清理工作的標誌。 @@ -100,23 +100,23 @@ C預處理器宏存在許多危險性，包括可能對具有副作用且沒有 內聯函數 ******** -不過，內聯函數本身也存在風險。程式設計師可以傾心於避免函數調用和用內聯函數填充源 +不過，內聯函數本身也存在風險。程序員可以傾心於避免函數調用和用內聯函數填充源 文件所固有的效率。然而，這些功能實際上會降低性能。因爲它們的代碼在每個調用站 -點都被複製一遍，所以最終會增加編譯內核的大小。此外，這也對處理器的內存緩存 +點都被複制一遍，所以最終會增加編譯內核的大小。此外，這也對處理器的內存緩存 造成壓力，從而大大降低執行速度。通常內聯函數應該非常小，而且相對較少。畢竟 函數調用的成本並不高；大量創建內聯函數是過早優化的典型例子。 -一般來說，內核程式設計師會自冒風險忽略緩存效果。在數據結構課程開頭中的經典 -時間/空間權衡通常不適用於當代硬體。空間 *就是* 時間，因爲一個大的程序比一個 +一般來說，內核程序員會自冒風險忽略緩存效果。在數據結構課程開頭中的經典 +時間/空間權衡通常不適用於當代硬件。空間 *就是* 時間，因爲一個大的程序比一個 更緊湊的程序運行得慢。 較新的編譯器越來越激進地決定一個給定函數是否應該內聯。因此，隨意放置使用 -「inline」關鍵字可能不僅僅是過度的，也可能是無用的。 +“inline”關鍵字可能不僅僅是過度的，也可能是無用的。 鎖 ** -2006年5月，「deviceescape」網絡堆棧在前呼後擁下以GPL發布，並被納入主線內核。 +2006年5月，“deviceescape”網絡堆棧在前呼後擁下以GPL發佈，並被納入主線內核。 這是一個受歡迎的消息；Linux中對無線網絡的支持充其量被認爲是不合格的，而 Deviceescape堆棧承諾修復這種情況。然而直到2007年6月（2.6.22），這段代碼才真 正進入主線。發生了什麼？ @@ -125,25 +125,25 @@ Deviceescape堆棧承諾修復這種情況。然而直到2007年6月（2.6.22） 設計。在合併這個網絡堆棧（現在稱爲mac80211）之前，需要對其進行一個鎖方案的 改造。 -曾經，Linux內核代碼可以在不考慮多處理器系統所帶來的並發性問題的情況下進行 +曾經，Linux內核代碼可以在不考慮多處理器系統所帶來的併發性問題的情況下進行 開發。然而現在，這個文檔就是在雙核筆記本電腦上寫的。即使在單處理器系統上， -爲提高響應能力所做的工作也會提高內核內的並發性水平。編寫內核代碼而不考慮鎖 +爲提高響應能力所做的工作也會提高內核內的併發性水平。編寫內核代碼而不考慮鎖 的日子早已遠去。 -可以由多個線程並發訪問的任何資源（數據結構、硬體寄存器等）必須由鎖保護。新 +可以由多個線程併發訪問的任何資源（數據結構、硬件寄存器等）必須由鎖保護。新 的代碼應該謹記這一要求；事後修改鎖是一項相當困難的任務。內核開發人員應該花 -時間充分了解可用的鎖原語，以便爲工作選擇正確的工具。對並發性缺乏關注的代碼 +時間充分了解可用的鎖原語，以便爲工作選擇正確的工具。對併發性缺乏關注的代碼 很難進入主線。 -回歸 +迴歸 **** -最後一個值得一提的危險是回歸：它可能會引起導致現有用戶的某些東西中斷的改變 -（這也可能會帶來很大的改進）。這種變化被稱爲「回歸」，回歸已經成爲主線內核 -最不受歡迎的問題。除了少數例外情況，如果回歸不能及時修正，會導致回歸的修改 -將被取消。最好首先避免回歸發生。 +最後一個值得一提的危險是迴歸：它可能會引起導致現有用戶的某些東西中斷的改變 +（這也可能會帶來很大的改進）。這種變化被稱爲“迴歸”，迴歸已經成爲主線內核 +最不受歡迎的問題。除了少數例外情況，如果迴歸不能及時修正，會導致迴歸的修改 +將被取消。最好首先避免迴歸發生。 -人們常常爭論，如果回歸帶來的功能遠超過產生的問題，那麼回歸是否爲可接受的。 +人們常常爭論，如果迴歸帶來的功能遠超過產生的問題，那麼迴歸是否爲可接受的。 如果它破壞了一個系統卻爲十個系統帶來新的功能，爲何不改改態度呢？2007年7月， Linus對這個問題給出了最佳答案: @@ -154,7 +154,7 @@ Linus對這個問題給出了最佳答案: （http://lwn.net/Articles/243460/） -特別不受歡迎的一種回歸類型是用戶空間ABI的任何變化。一旦接口被導出到用戶空間， +特別不受歡迎的一種迴歸類型是用戶空間ABI的任何變化。一旦接口被導出到用戶空間， 就必須無限期地支持它。這一事實使得用戶空間接口的創建特別具有挑戰性：因爲它們 不能以不兼容的方式進行更改，所以必須一次就對。因此，用戶空間接口總是需要大量 的思考、清晰的文檔和廣泛的審查。 @@ -171,19 +171,19 @@ Linus對這個問題給出了最佳答案: 第一步是注意編譯器產生的警告。當前版本的GCC可以檢測（並警告）大量潛在錯誤。 通常，這些警告都指向真正的問題。提交以供審閱的代碼一般不會產生任何編譯器警告。 -在消除警告時，注意了解真正的原因，並儘量避免僅「修復」使警告消失而不解決其原因。 +在消除警告時，注意瞭解真正的原因，並儘量避免僅“修復”使警告消失而不解決其原因。 -請注意，並非所有編譯器警告都默認啓用。使用「make KCFLAGS=-W」構建內核以 +請注意，並非所有編譯器警告都默認啓用。使用“make KCFLAGS=-W”構建內核以 獲得完整集合。 -內核提供了幾個配置選項，可以打開調試功能；大多數配置選項位於「kernel hacking」 +內核提供了幾個配置選項，可以打開調試功能；大多數配置選項位於“kernel hacking” 子菜單中。對於任何用於開發或測試目的的內核，都應該啓用其中幾個選項。特別是， 您應該打開： - FRAME_WARN 獲取大於給定數量的堆棧幀的警告。 這些警告生成的輸出可能比較冗長，但您不必擔心來自內核其他部分的警告。 - - DEBUG_OBJECTS 將添加代碼以跟蹤內核創建的各種對象的生命周期，並在出現問題 + - DEBUG_OBJECTS 將添加代碼以跟蹤內核創建的各種對象的生命週期，並在出現問題 時發出警告。如果你要添加創建（和導出）關於其自己的複雜對象的子系統，請 考慮打開對象調試基礎結構的支持。 @@ -195,34 +195,34 @@ Linus對這個問題給出了最佳答案: 還有很多其他調試選項，其中一些將在下面討論。其中一些有顯著的性能影響，不應 一直使用。在學習可用選項上花費一些時間，可能會在短期內得到許多回報。 -其中一個較重的調試工具是鎖檢查器或「lockdep」。該工具將跟蹤系統中每個鎖 +其中一個較重的調試工具是鎖檢查器或“lockdep”。該工具將跟蹤系統中每個鎖 （spinlock或mutex）的獲取和釋放、獲取鎖的相對順序、當前中斷環境等等。然後， 它可以確保總是以相同的順序獲取鎖，相同的中斷假設適用於所有情況等等。換句話 說，lockdep可以找到許多導致系統死鎖的場景。在部署的系統中，這種問題可能會 很痛苦（對於開發人員和用戶而言）；LockDep允許提前以自動方式發現問題。具有 -任何類型的非普通鎖的代碼在提交合併前應在啓用lockdep的情況下運行測試。 +任何類型的非普通鎖的代碼在提交合並前應在啓用lockdep的情況下運行測試。 -作爲一個勤奮的內核程式設計師，毫無疑問，您將檢查任何可能失敗的操作（如內存分配） +作爲一個勤奮的內核程序員，毫無疑問，您將檢查任何可能失敗的操作（如內存分配） 的返回狀態。然而，事實上，最終的故障復現路徑可能完全沒有經過測試。未測試的 代碼往往會出問題；如果所有這些錯誤處理路徑都被執行了幾次，那麼您可能對代碼 更有信心。 內核提供了一個可以做到這一點的錯誤注入框架，特別是在涉及內存分配的情況下。 啓用故障注入後，內存分配的可配置失敗的百分比；這些失敗可以限定在特定的代碼 -範圍內。在啓用了故障注入的情況下運行，程式設計師可以看到當情況惡化時代碼如何響 +範圍內。在啓用了故障注入的情況下運行，程序員可以看到當情況惡化時代碼如何響 應。有關如何使用此工具的詳細信息，請參閱 Documentation/fault-injection/fault-injection.rst。 -「sparse」靜態分析工具可以發現其他類型的錯誤。sparse可以警告程式設計師用戶空間 +“sparse”靜態分析工具可以發現其他類型的錯誤。sparse可以警告程序員用戶空間 和內核空間地址之間的混淆、大端序與小端序的混淆、在需要一組位標誌的地方傳遞 -整數值等等。sparse必須單獨安裝(如果您的分發伺服器沒有將其打包， +整數值等等。sparse必須單獨安裝(如果您的分發服務器沒有將其打包， 可以在 https://sparse.wiki.kernel.org/index.php/Main_page 找到）, -然後可以通過在make命令中添加「C=1」在代碼上運行它。 +然後可以通過在make命令中添加“C=1”在代碼上運行它。 -「Coccinelle」工具 :ref:`http://coccinelle.lip6.fr/ <devtools_coccinelle>` -能夠發現各種潛在的編碼問題；它還可以爲這些問題提出修複方案。在 -scripts/coccinelle目錄下已經打包了相當多的內核「語義補丁」；運行 -「make coccicheck」將運行這些語義補丁並報告發現的任何問題。有關詳細信息，請參閱 +“Coccinelle”工具 :ref:`http://coccinelle.lip6.fr/ <devtools_coccinelle>` +能夠發現各種潛在的編碼問題；它還可以爲這些問題提出修復方案。在 +scripts/coccinelle目錄下已經打包了相當多的內核“語義補丁”；運行 +“make coccicheck”將運行這些語義補丁並報告發現的任何問題。有關詳細信息，請參閱 :ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>` @@ -247,7 +247,7 @@ scripts/coccinelle目錄下已經打包了相當多的內核「語義補丁」 任何添加新用戶空間接口的代碼——包括新的sysfs或/proc文件——都應該包含該接口 的文檔，該文檔使用戶空間開發人員能夠知道他們在使用什麼。請參閱 -Documentation/ABI/README，了解如何此文檔格式以及需要提供哪些信息。 +Documentation/ABI/README，瞭解如何此文檔格式以及需要提供哪些信息。 文檔 :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>` 描述了內核的所有引導時間參數。任何添加新參數的補丁都應該向該文檔添加適當的 @@ -256,27 +256,27 @@ Documentation/ABI/README，了解如何此文檔格式以及需要提供哪些 任何新的配置選項都必須附有幫助文本，幫助文本需清楚地解釋這些選項以及用戶可能 希望何時使用它們。 -許多子系統的內部API信息通過專門格式化的注釋進行記錄；這些注釋可以通過 -「kernel-doc」腳本以多種方式提取和格式化。如果您在具有kerneldoc注釋的子系統中 +許多子系統的內部API信息通過專門格式化的註釋進行記錄；這些註釋可以通過 +“kernel-doc”腳本以多種方式提取和格式化。如果您在具有kerneldoc註釋的子系統中 工作，則應該維護它們，並根據需要爲外部可用的功能添加它們。即使在沒有如此記錄 -的領域中，爲將來添加kerneldoc注釋也沒有壞處；實際上，這對於剛開始開發內核的人 -來說是一個有用的活動。這些注釋的格式以及如何創建kerneldoc模板的一些信息可以在 +的領域中，爲將來添加kerneldoc註釋也沒有壞處；實際上，這對於剛開始開發內核的人 +來說是一個有用的活動。這些註釋的格式以及如何創建kerneldoc模板的一些信息可以在 :ref:`Documentation/doc-guide/ <doc_guide>` 上找到。 -任何閱讀大量現有內核代碼的人都會注意到，注釋的缺失往往是最值得注意的。同時， -對新代碼的要求比過去更高；合併未注釋的代碼將更加困難。這就是說，人們並不期望 -詳細注釋的代碼。代碼本身應該是自解釋的，注釋闡釋了更微妙的方面。 +任何閱讀大量現有內核代碼的人都會注意到，註釋的缺失往往是最值得注意的。同時， +對新代碼的要求比過去更高；合併未註釋的代碼將更加困難。這就是說，人們並不期望 +詳細註釋的代碼。代碼本身應該是自解釋的，註釋闡釋了更微妙的方面。 -某些事情應該總是被注釋。使用內存屏障時，應附上一行文字，解釋爲什麼需要設置內存 +某些事情應該總是被註釋。使用內存屏障時，應附上一行文字，解釋爲什麼需要設置內存 屏障。數據結構的鎖規則通常需要在某個地方解釋。一般來說，主要數據結構需要全面 的文檔。應該指出代碼中分立的位之間不明顯的依賴性。任何可能誘使代碼管理人進行 -錯誤的「清理」的事情都需要一個注釋來說明爲什麼要這樣做。等等。 +錯誤的“清理”的事情都需要一個註釋來說明爲什麼要這樣做。等等。 內部API更改 ----------- -內核提供給用戶空間的二進位接口不能被破壞，除非逼不得已。而內核的內部編程接口 +內核提供給用戶空間的二進制接口不能被破壞，除非逼不得已。而內核的內部編程接口 是高度流動的，當需要時可以更改。如果你發現自己不得不處理一個內核API，或者僅 僅因爲它不滿足你的需求導致無法使用特定的功能，這可能是API需要改變的一個標誌。 作爲內核開發人員，您有權進行此類更改。 @@ -287,7 +287,7 @@ Documentation/ABI/README，了解如何此文檔格式以及需要提供哪些 另一個要點是，更改內部API的開發人員通常要負責修復內核樹中被更改破壞的任何代碼。 對於一個廣泛使用的函數，這個責任可以導致成百上千的變化，其中許多變化可能與其他 -開發人員正在做的工作相衝突。不用說，這可能是一項大工程，所以最好確保理由是 +開發人員正在做的工作相沖突。不用說，這可能是一項大工程，所以最好確保理由是 可靠的。請注意，coccinelle工具可以幫助進行廣泛的API更改。 在進行不兼容的API更改時，應儘可能確保編譯器捕獲未更新的代碼。這將幫助您確保找 diff --git a/Documentation/translations/zh_TW/process/5.Posting.rst b/Documentation/translations/zh_TW/process/5.Posting.rst index 280a8832ecc0..d398dda427aa 100644 --- a/Documentation/translations/zh_TW/process/5.Posting.rst +++ b/Documentation/translations/zh_TW/process/5.Posting.rst @@ -11,31 +11,31 @@ :校譯: 吳想成 Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> .. _tw_development_posting: -發布補丁 +發佈補丁 ======== 您的工作遲早會準備好提交給社區進行審查，並最終包含到主線內核中。毫不稀奇， -內核開發社區已經發展出一套用於發布補丁的約定和過程；遵循這些約定和過程將使 +內核開發社區已經發展出一套用於發佈補丁的約定和過程；遵循這些約定和過程將使 參與其中的每個人的生活更加輕鬆。本文檔試圖描述這些約定的部分細節；更多信息 也可在以下文檔中找到 -:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` -和 :ref:`Documentation/translations/zh_TW/process/submit-checklist.rst <tw_submitchecklist>`。 +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <tw_submittingpatches>` +和 :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <tw_submitchecklist>`。 -何時郵寄 +何時寄送 -------- -在補丁完全「準備好」之前，避免發布補丁是一種持續的誘惑。對於簡單的補丁，這 +在補丁完全“準備好”之前，避免發佈補丁是一種持續的誘惑。對於簡單的補丁，這 不是問題。但是如果正在完成的工作很複雜，那麼在工作完成之前從社區獲得反饋就 -可以獲得很多好處。因此，您應該考慮發布正在進行的工作，甚至維護一個可用的Git +可以獲得很多好處。因此，您應該考慮發佈正在進行的工作，甚至維護一個可用的Git 樹，以便感興趣的開發人員可以隨時趕上您的工作。 -當發布中有尚未準備好被包含的代碼，最好在發布中說明。還應提及任何有待完成的 +當發佈中有尚未準備好被包含的代碼，最好在發佈中說明。還應提及任何有待完成的 主要工作和任何已知問題。很少有人會願意看那些被認爲是半生不熟的補丁，但是 -那些願意的人會帶著他們的點子來一起幫助你把工作推向正確的方向。 +那些願意的人會帶着他們的點子來一起幫助你把工作推向正確的方向。 創建補丁之前 ------------ @@ -50,20 +50,20 @@ - 您的更改是否具有性能影響？如果是這樣，您應該運行基準測試來顯示您的變更的 影響（或好處）；結果的摘要應該包含在補丁中。 - - 確保您有權發布代碼。如果這項工作是爲僱主完成的，僱主對這項工作具有所有權， - 並且必須同意根據GPL對其進行發布。 + - 確保您有權發佈代碼。如果這項工作是爲僱主完成的，僱主對這項工作具有所有權， + 並且必須同意根據GPL對其進行發佈。 -一般來說，在發布代碼之前進行一些額外的思考，幾乎總是能在短時間內得到回報。 +一般來說，在發佈代碼之前進行一些額外的思考，幾乎總是能在短時間內得到回報。 補丁準備 -------- -準備補丁發布的工作量可能很驚人，但在此嘗試節省時間通常是不明智的，即使在短期 +準備補丁發佈的工作量可能很驚人，但在此嘗試節省時間通常是不明智的，即使在短期 內亦然。 必須針對內核的特定版本準備補丁。一般來說，補丁應該基於Linus的Git樹中的當前 -主線。當以主線爲基礎時，請從一個衆所周知的發布點開始——如穩定版本或 -rc -版本發布點——而不是在一個任意的主線分支點。 +主線。當以主線爲基礎時，請從一個衆所周知的發佈點開始——如穩定版本或 -rc +版本發佈點——而不是在一個任意的主線分支點。 也可能需要針對-mm、linux-next或子系統樹生成版本，以便於更廣泛的測試和審查。 根據補丁的區域以及其他地方的情況，針對其他樹建立的補丁可能需要大量的工作來 @@ -73,12 +73,12 @@ 分割補丁是一門藝術；一些開發人員花了很長時間來弄清楚如何按照社區期望的方式來 分割。不過，這些經驗法則也許有幫助： - - 您發布的補丁系列幾乎肯定不會是開發過程中版本控制系統中的一系列更改。相反， + - 您發佈的補丁系列幾乎肯定不會是開發過程中版本控制系統中的一系列更改。相反， 需要對您所做更改的最終形式加以考慮，然後以有意義的方式進行拆分。開發人員對 離散的、自包含的更改感興趣，而不是您創造這些更改的原始路徑。 - - 每個邏輯上獨立的變更都應該格式化爲單獨的補丁。這些更改可以是小的（如「向 - 此結構體添加欄位」）或大的（如添加一個重要的新驅動程序），但它們在概念上 + - 每個邏輯上獨立的變更都應該格式化爲單獨的補丁。這些更改可以是小的（如“向 + 此結構體添加字段”）或大的（如添加一個重要的新驅動程序），但它們在概念上 應該是小的，並且可以在一行內簡述。每個補丁都應該做一個特定的、可以單獨 檢查並驗證它所做的事情的更改。 @@ -88,34 +88,34 @@ - 每個補丁都應該能創建一個可以正確地構建和運行的內核；如果補丁系列在中間被 斷開，那麼結果仍應是一個正常工作的內核。部分應用一系列補丁是使用 - 「git bisct」工具查找回歸的一個常見場景；如果結果是一個損壞的內核，那麼將使 + “git bisct”工具查找回歸的一個常見場景；如果結果是一個損壞的內核，那麼將使 那些從事追蹤問題的高尚工作的開發人員和用戶的生活更加艱難。 - 不要過分分割。一位開發人員曾經將一組針對單個文件的編輯分成500個單獨的補丁 - 發布，這並沒有使他成爲內核郵件列表中最受歡迎的人。一個補丁可以相當大， + 發佈，這並沒有使他成爲內核郵件列表中最受歡迎的人。一個補丁可以相當大， 只要它仍然包含一個單一的 *邏輯* 變更。 - 用一系列補丁添加一個全新的基礎設施，但是該設施在系列中的最後一個補丁啓用 整個變更之前不能使用，這看起來很誘人。如果可能的話，應該避免這種誘惑； - 如果這個系列增加了回歸，那麼二分法將指出最後一個補丁是導致問題的補丁， + 如果這個系列增加了迴歸，那麼二分法將指出最後一個補丁是導致問題的補丁， 即使真正的bug在其他地方。只要有可能，添加新代碼的補丁程序應該立即激活該 代碼。 -創建完美補丁系列的工作可能是一個令人沮喪的過程，在完成「真正的工作」之後需要 +創建完美補丁系列的工作可能是一個令人沮喪的過程，在完成“真正的工作”之後需要 花費大量的時間和思考。但是如果做得好，花費的時間就是值得的。 補丁格式和更改日誌 ------------------ -所以現在你有了一系列完美的補丁可以發布，但是這項工作還沒有完成。每個補丁都 +所以現在你有了一系列完美的補丁可以發佈，但是這項工作還沒有完成。每個補丁都 需要被格式化成一條消息，以快速而清晰地將其目的傳達到世界其他地方。爲此， 每個補丁將由以下部分組成： - - 可選的「From」行，表明補丁作者。只有當你通過電子郵件發送別人的補丁時，這一行 - 才是必須的，但是爲防止疑問加上它也不會有什麼壞處。 + - 可選的“From”行，表明補丁作者。只有當你通過電子郵件發送別人的補丁時，這一行 + 纔是必須的，但是爲防止疑問加上它也不會有什麼壞處。 - 一行描述，說明補丁的作用。對於在沒有其他上下文的情況下看到該消息的讀者來說， - 該消息應足以確定修補程序的範圍；此行將顯示在「short form（簡短格式）」變更 + 該消息應足以確定修補程序的範圍；此行將顯示在“short form（簡短格式）”變更 日誌中。此消息通常需要先加上子系統名稱前綴，然後是補丁的目的。例如： :: @@ -144,17 +144,17 @@ 一般來說，你越把自己放在每個閱讀你變更日誌的人的位置上，變更日誌（和內核 作爲一個整體）就越好。 -不消說，變更日誌是將變更提交到版本控制系統時使用的文本。接下來將是： +不需要說，變更日誌是將變更提交到版本控制系統時使用的文本。接下來將是： - - 補丁本身，採用統一的（「-u」）補丁格式。使用「-p」選項來diff將使函數名與 + - 補丁本身，採用統一的（“-u”）補丁格式。使用“-p”選項來diff將使函數名與 更改相關聯，從而使結果補丁更容易被其他人讀取。 您應該避免在補丁中包括與更改不相關文件（例如，構建過程生成的文件或編輯器 -備份文件）。文檔目錄中的「dontdiff」文件在這方面有幫助；使用「-X」選項將 +備份文件）。文檔目錄中的“dontdiff”文件在這方面有幫助；使用“-X”選項將 其傳遞給diff。 上面提到的標籤（tag）用於描述各種開發人員如何與這個補丁的開發相關聯。 -:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <tw_submittingpatches>` 文檔中對它們進行了詳細描述；下面是一個簡短的總結。每一行的格式如下： :: @@ -165,14 +165,14 @@ - Signed-off-by: 這是一個開發人員的證明，證明他或她有權提交補丁以包含到內核 中。這表明同意開發者來源認證協議，其全文見 - :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` + :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <tw_submittingpatches>` 如果沒有合適的簽字，則不能合併到主線中。 - Co-developed-by: 聲明補丁是由多個開發人員共同創建的；當幾個人在一個補丁上 工作時，它用於給出共同作者（除了 From: 所給出的作者之外）。由於 Co-developed-by: 表示作者身份，所以每個共同開發人，必須緊跟在相關合作作者 的Signed-off-by之後。具體內容和示例見以下文件 - :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` + :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <tw_submittingpatches>` - Acked-by: 表示另一個開發人員（通常是相關代碼的維護人員）同意補丁適合包含 在內核中。 @@ -180,7 +180,7 @@ - Tested-by: 聲明某人已經測試了補丁並確認它可以工作。 - Reviewed-by: 表示某開發人員已經審查了補丁的正確性；有關詳細信息，請參閱 - :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` + :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <tw_submittingpatches>` - Reported-by: 指定報告此補丁修復的問題的用戶；此標記用於表示感謝。 @@ -188,16 +188,16 @@ 在補丁中添加標籤時要小心：只有Cc:才適合在沒有指定人員明確許可的情況下添加。 -發送補丁 +寄送補丁 -------- -在寄出補丁之前，您還需要注意以下幾點： +在寄送補丁之前，您還需要注意以下幾點： - 您確定您的郵件發送程序不會損壞補丁嗎？被郵件客戶端更改空白或修飾了行的補丁 無法被另一端接受，並且通常不會進行任何詳細檢查。如果有任何疑問，先把補丁寄 給你自己，讓你自己確定它是完好無損的。 - :ref:`Documentation/translations/zh_TW/process/email-clients.rst <tw_email_clients>` + :ref:`Documentation/translations/zh_CN/process/email-clients.rst <tw_email_clients>` 提供了一些有用的提示，可以讓特定的郵件客戶端正常發送補丁。 - 你確定你的補丁沒有荒唐的錯誤嗎？您應該始終通過scripts/checkpatch.pl檢查 @@ -209,12 +209,12 @@ 引用補丁的部分。相反，只需將補丁直接放到您的消息中。 寄出補丁時，重要的是將副本發送給任何可能感興趣的人。與其他一些項目不同，內核 -鼓勵人們甚至錯誤地發送過多的副本；不要假定相關人員會看到您在郵件列表中的發布。 +鼓勵人們甚至錯誤地發送過多的副本；不要假定相關人員會看到您在郵件列表中的發佈。 尤其是，副本應發送至： - 受影響子系統的維護人員。如前所述，維護人員文件是查找這些人員的首選地方。 - - 其他在同一領域工作的開發人員，尤其是那些現在可能在那裡工作的開發人員。使用 + - 其他在同一領域工作的開發人員，尤其是那些現在可能在那裏工作的開發人員。使用 git查看還有誰修改了您正在處理的文件，這很有幫助。 - 如果您對某錯誤報告或功能請求做出響應，也可以抄送原始發送人。 @@ -223,7 +223,7 @@ - 如果您正在修復一個缺陷，請考慮該修復是否應進入下一個穩定更新。如果是這樣， 補丁副本也應發到stable@vger.kernel.org 。另外，在補丁本身的標籤中添加一個 - 「Cc: stable@vger.kernel.org」；這將使穩定版團隊在修復進入主線時收到通知。 + “Cc: stable@vger.kernel.org”；這將使穩定版團隊在修復進入主線時收到通知。 當爲一個補丁選擇接收者時，最好清楚你認爲誰最終會接受這個補丁並將其合併。雖然 可以將補丁直接發給Linus Torvalds並讓他合併，但通常情況下不會這樣做。Linus很 @@ -236,7 +236,7 @@ [PATCH nn/mm] subsys: one-line description of the patch -其中「nn」是補丁的序號，「mm」是系列中補丁的總數，「subsys」是受影響子系統的 +其中“nn”是補丁的序號，“mm”是系列中補丁的總數，“subsys”是受影響子系統的 名稱。當然，一個單獨的補丁可以省略nn/mm。 如果您有一系列重要的補丁，那麼通常發送一個簡介作爲第〇部分。不過，這個約定 diff --git a/Documentation/translations/zh_TW/process/6.Followthrough.rst b/Documentation/translations/zh_TW/process/6.Followthrough.rst index 4af782742db3..bcc885ae1b8e 100644 --- a/Documentation/translations/zh_TW/process/6.Followthrough.rst +++ b/Documentation/translations/zh_TW/process/6.Followthrough.rst @@ -11,20 +11,20 @@ :校譯: 吳想成 Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> .. _tw_development_followthrough: 跟進 ==== -此時，您已經遵循了到目前爲止給出的指導方針，並且，隨著您自己的工程技能的增加， +此時，您已經遵循了到目前爲止給出的指導方針，並且，隨着您自己的工程技能的增加， 已經發布了一系列完美的補丁。即使是經驗豐富的內核開發人員也能犯的最大錯誤之一 -是，認爲他們的工作現在已經完成了。事實上，發布補丁意味著進入流程的下一個階段， +是，認爲他們的工作現在已經完成了。事實上，發佈補丁意味着進入流程的下一個階段， 可能還需要做很多工作。 -一個補丁在首次發布時就非常出色、沒有改進的餘地，這是很罕見的。內核開發流程已 -認識到這一事實，因此它非常注重對已發布代碼的改進。作爲代碼的作者，您應該與 +一個補丁在首次發佈時就非常出色、沒有改進的餘地，這是很罕見的。內核開發流程已 +認識到這一事實，因此它非常注重對已發佈代碼的改進。作爲代碼的作者，您應該與 內核社區合作，以確保您的代碼符合內核的質量標準。如果不參與這個過程，很可能會 無法將補丁合併到主線中。 @@ -41,7 +41,7 @@ 調整到大量的重寫——都來自於對Linux的理解，即從現在起十年後，Linux仍將 在開發中。 - - 代碼審查是一項艱苦的工作，這是一項相對吃力不討好的工作；人們記得誰編寫了 + - 代碼審查是一項艱苦的工作，這是一項相對喫力不討好的工作；人們記得誰編寫了 內核代碼，但對於那些審查它的人來說，幾乎沒有什麼長久的名聲。因此，審閱 人員可能會變得暴躁，尤其是當他們看到同樣的錯誤被一遍又一遍地犯下時。如果 你得到了一個看起來憤怒、侮辱或完全冒犯你的評論，請抑制以同樣方式回應的衝動。 @@ -54,7 +54,7 @@ 所有這些歸根結底就是，當審閱者向您發送評論時，您需要注意他們正在進行的技術 評論。不要讓他們的表達方式或你自己的驕傲阻止此事。當你在一個補丁上得到評論 -時，花點時間去理解評論人想說什麼。如果可能的話，請修覆審閱者要求您修復的內 +時，花點時間去理解評論人想說什麼。如果可能的話，請修復審閱者要求您修復的內 容。然後回覆審閱者：謝謝他們，並描述你將如何回答他們的問題。 請注意，您不必同意審閱者建議的每個更改。如果您認爲審閱者誤解了您的代碼，請 @@ -65,19 +65,19 @@ 是錯誤的，或者你甚至沒有解決正確的問題。 Andrew Morton建議，每一個不會導致代碼更改的審閱評論都應該產生一個額外的代碼 -注釋；這可以幫助未來的審閱人員避免第一次出現的問題。 +註釋；這可以幫助未來的審閱人員避免第一次出現的問題。 一個致命的錯誤是忽視評論，希望它們會消失。它們不會走的。如果您在沒有對之前 收到的評論做出響應的情況下重新發布代碼，那麼很可能會發現補丁毫無用處。 -說到重新發布代碼：請記住，審閱者不會記住您上次發布的代碼的所有細節。因此， +說到重新發布代碼：請記住，審閱者不會記住您上次發佈的代碼的所有細節。因此， 提醒審閱人員以前提出的問題以及您如何處理這些問題總是一個好主意；補丁變更 日誌是提供此類信息的好地方。審閱者不必搜索列表檔案來熟悉上次所說的內容； 如果您幫助他們直接開始，當他們重新查看您的代碼時，心情會更好。 -如果你已經試著做正確的事情，但事情仍然沒有進展呢？大多數技術上的分歧都可以 +如果你已經試着做正確的事情，但事情仍然沒有進展呢？大多數技術上的分歧都可以 通過討論來解決，但有時人們仍需要做出決定。如果你真的認爲這個決定對你不利， -你可以試著向有更高權力的人上訴。對於本文，更高權力的人是 Andrew Morton 。 +你可以試着向有更高權力的人上訴。對於本文，更高權力的人是 Andrew Morton 。 Andrew 在內核開發社區中非常受尊敬；他經常爲似乎被絕望阻塞的事情清障。儘管 如此，不應輕易就直接找 Andrew ，也不應在所有其他替代方案都被嘗試之前找他。 當然，記住，他也可能不同意你的意見。 @@ -95,7 +95,7 @@ Andrew 在內核開發社區中非常受尊敬；他經常爲似乎被絕望阻 包含在子系統樹中可以提高補丁的可見性。現在，使用該樹的其他開發人員將默認獲 得補丁。子系統樹通常也爲Linux提供支持，使其內容對整個開發社區可見。在這一點 -上，您很可能會從一組新的審閱者那裡得到更多的評論；這些評論需要像上一輪那樣 +上，您很可能會從一組新的審閱者那裏得到更多的評論；這些評論需要像上一輪那樣 得到回應。 在這時也會發生點什麼，這取決於你的補丁的性質，是否與其他人正在做的工作發生 @@ -114,23 +114,23 @@ Andrew 在內核開發社區中非常受尊敬；他經常爲似乎被絕望阻 這種誘惑，您仍然需要對有問題或建議的開發人員作出響應。 不過，更重要的是：將代碼包含在主線中會將代碼交給更多的一些測試人員。即使您 -爲尚未可用的硬體提供了驅動程序，您也會驚訝於有多少人會將您的代碼構建到內核 +爲尚未可用的硬件提供了驅動程序，您也會驚訝於有多少人會將您的代碼構建到內核 中。當然，如果有測試人員，也可能會有錯誤報告。 -最糟糕的錯誤報告是回歸。如果你的補丁導致回歸，你會發現多到讓你不舒服的眼睛盯 -著你；回歸需要儘快修復。如果您不願意或無法修復回歸（其他人都不會爲您修復）， +最糟糕的錯誤報告是迴歸。如果你的補丁導致迴歸，你會發現多到讓你不舒服的眼睛盯 +着你；迴歸需要儘快修復。如果您不願意或無法修復迴歸（其他人都不會爲您修復）， 那麼在穩定期內，您的補丁幾乎肯定會被移除。除了否定您爲使補丁進入主線所做的 -所有工作之外，如果由於未能修復回歸而取消補丁，很可能會使將來的工作更難被合併。 +所有工作之外，如果由於未能修復迴歸而取消補丁，很可能會使將來的工作更難被合併。 -在處理完任何回歸之後，可能還有其他普通缺陷需要處理。穩定期是修復這些錯誤並 -確保代碼在主線內核版本中的首次發布儘可能可靠的最好機會。所以，請回應錯誤 +在處理完任何迴歸之後，可能還有其他普通缺陷需要處理。穩定期是修復這些錯誤並 +確保代碼在主線內核版本中的首次發佈儘可能可靠的最好機會。所以，請回應錯誤 報告，並儘可能解決問題。這就是穩定期的目的；一旦解決了舊補丁的任何問題，就 可以開始盡情創建新補丁。 別忘了，還有其他節點也可能會創建缺陷報告：下一個主線穩定版本，當著名的發行 商選擇包含您補丁的內核版本時等等。繼續響應這些報告是您工作的基本素養。但是 如果這不能提供足夠的動機，那麼也需要考慮：開發社區會記住那些在合併後對代碼 -失去興趣的開發人員。下一次你發布補丁時，他們會以你以後不會持續維護它爲前提 +失去興趣的開發人員。下一次你發佈補丁時，他們會以你以後不會持續維護它爲前提 來評估它。 其他可能發生的事情 @@ -141,15 +141,15 @@ Andrew 在內核開發社區中非常受尊敬；他經常爲似乎被絕望阻 維護人員（確保包含一個正確的From:行，這樣屬性是正確的，並添加一個您自己的 signoff ），或者回復一個 Acked-by: 讓原始發送者向上發送它。 -如果您不同意補丁，請禮貌地回復，解釋原因。如果可能的話，告訴作者需要做哪些 -更改才能讓您接受補丁。合併代碼的編寫者和維護者所反對的補丁的確存在著一定的 +如果您不同意補丁，請禮貌地回覆，解釋原因。如果可能的話，告訴作者需要做哪些 +更改才能讓您接受補丁。合併代碼的編寫者和維護者所反對的補丁的確存在着一定的 阻力，但僅此而已。如果你被認爲不必要的阻礙了好的工作，那麼這些補丁最終會 繞過你並進入主線。在Linux內核中，沒有人對任何代碼擁有絕對的否決權。可能除 了Linus。 -在非常罕見的情況下，您可能會看到完全不同的東西：另一個開發人員發布了針對您 -的問題的不同解決方案。在這時，兩個補丁之一可能不會被合併，「我的補丁首先 -發布」不被認爲是一個令人信服的技術論據。如果有別人的補丁取代了你的補丁而進 +在非常罕見的情況下，您可能會看到完全不同的東西：另一個開發人員發佈了針對您 +的問題的不同解決方案。在這時，兩個補丁之一可能不會被合併，“我的補丁首先 +發佈”不被認爲是一個令人信服的技術論據。如果有別人的補丁取代了你的補丁而進 入了主線，那麼只有一種方法可以回應你：很高興你的問題解決了，請繼續工作吧。 以這種方式把某人的工作推到一邊可能導致傷心和氣餒，但是社區會記住你的反應， 即使很久以後他們已經忘記了誰的補丁真正被合併。 diff --git a/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst b/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst index 4fbc104a37ca..db74d8ca3f3b 100644 --- a/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst +++ b/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst @@ -11,7 +11,7 @@ :校譯: 吳想成 Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> .. _tw_development_advancedtopics: @@ -24,14 +24,14 @@ 使用Git管理補丁 --------------- -內核使用分布式版本控制始於2002年初，當時Linus首次開始使用專有的Bitkeeper應用 -程序。雖然BitKeeper存在爭議，但它所體現的軟體版本管理方法卻肯定不是。分布式 +內核使用分佈式版本控制始於2002年初，當時Linus首次開始使用專有的Bitkeeper應用 +程序。雖然BitKeeper存在爭議，但它所體現的軟件版本管理方法卻肯定不是。分佈式 版本控制可以立即加速內核開發項目。現在有好幾種免費的BitKeeper替代品。 但無論好壞，內核項目都已經選擇了Git作爲其工具。 -使用Git管理補丁可以使開發人員的生活更加輕鬆，尤其是隨著補丁數量的增長。Git也 +使用Git管理補丁可以使開發人員的生活更加輕鬆，尤其是隨着補丁數量的增長。Git也 有其粗糙的邊角和一定的危險性，它是一個年輕和強大的工具，仍然在其開發人員完善 -中。本文檔不會試圖教會讀者如何使用git；這會是個巨長的文檔。相反，這裡的重點 +中。本文檔不會試圖教會讀者如何使用git；這會是個巨長的文檔。相反，這裏的重點 將是Git如何特別適合內核開發過程。想要加快用Git速度的開發人員可以在以下網站上 找到更多信息： @@ -42,22 +42,22 @@ 同時網上也能找到各種各樣的教程。 在嘗試使用它生成補丁供他人使用之前，第一要務是閱讀上述網頁，對Git的工作方式 -有一個紮實的了解。使用Git的開發人員應能進行拉取主線存儲庫的副本，查詢修訂 -歷史，提交對樹的更改，使用分支等操作。了解Git用於重寫歷史的工具（如rebase） -也很有用。Git有自己的術語和概念；Git的新用戶應該了解引用、遠程分支、索引、 -快進合併、推拉、游離頭等。一開始可能有點嚇人，但這些概念不難通過一點學習來 +有一個紮實的瞭解。使用Git的開發人員應能進行拉取主線存儲庫的副本，查詢修訂 +歷史，提交對樹的更改，使用分支等操作。瞭解Git用於重寫歷史的工具（如rebase） +也很有用。Git有自己的術語和概念；Git的新用戶應該瞭解引用、遠程分支、索引、 +快進合併、推拉、遊離頭等。一開始可能有點嚇人，但這些概念不難通過一點學習來 理解。 使用git生成通過電子郵件提交的補丁是提高速度的一個很好的練習。 -當您準備好開始建立Git樹供其他人查看時，無疑需要一個可以從中拉取的伺服器。 -如果您有一個可以訪問網際網路的系統，那麼使用git-daemon設置這樣的伺服器相對 +當您準備好開始建立Git樹供其他人查看時，無疑需要一個可以從中拉取的服務器。 +如果您有一個可以訪問因特網的系統，那麼使用git-daemon設置這樣的服務器相對 簡單。同時，免費的公共託管網站（例如github）也開始出現在網絡上。成熟的開發 人員可以在kernel.org上獲得一個帳戶，但這些帳戶並不容易得到；更多有關信息， 請參閱 https://kernel.org/faq/ 。 -正常的Git工作流程涉及到許多分支的使用。每一條開發線都可以分爲單獨的「主題 -分支」，並獨立維護。Git的分支很容易使用，沒有理由不使用它們。而且，在任何 +正常的Git工作流程涉及到許多分支的使用。每一條開發線都可以分爲單獨的“主題 +分支”，並獨立維護。Git的分支很容易使用，沒有理由不使用它們。而且，在任何 情況下，您都不應該在任何您打算讓其他人從中拉取的分支中進行開發。應該小心地 創建公開可用的分支；當開發分支處於完整狀態並已準備好時(而不是之前）才合併 開發分支的補丁。 @@ -72,10 +72,10 @@ Git提供了一些強大的工具，可以讓您重寫開發歷史。一個不 簡單癡迷。重寫歷史將重寫該歷史中包含的更改，將經過測試（希望如此）的內核樹 變爲未經測試的內核樹。除此之外，如果開發人員沒有共享項目歷史，他們就無法 輕鬆地協作；如果您重寫了其他開發人員拉入他們存儲庫的歷史，您將使這些開發 -人員的生活更加困難。因此，這裡有一個簡單的經驗法則：被導出到其他地方的歷史 +人員的生活更加困難。因此，這裏有一個簡單的經驗法則：被導出到其他地方的歷史 在此後通常被認爲是不可變的。 -因此，一旦將一組更改推送到公開可用的伺服器上，就不應該重寫這些更改。如果您 +因此，一旦將一組更改推送到公開可用的服務器上，就不應該重寫這些更改。如果您 嘗試強制進行無法快進合併的更改（即不共享同一歷史記錄的更改），Git將嘗試強制 執行此規則。這可能覆蓋檢查，有時甚至需要重寫導出的樹。在樹之間移動變更集以 避免linux-next中的衝突就是一個例子。但這種行爲應該是罕見的。這就是爲什麼 @@ -86,9 +86,9 @@ Git提供了一些強大的工具，可以讓您重寫開發歷史。一個不 對於一個私有的分支，rebasing 可能是一個很容易跟上另一棵樹的方法，但是一旦 一棵樹被導出到外界，rebasing就不可取了。一旦發生這種情況，就必須進行完全 合併（merge）。合併有時是很有意義的，但是過於頻繁的合併會不必要地擾亂歷史。 -在這種情況下建議的做法是不要頻繁合併，通常只在特定的發布點（如主線-rc發布） +在這種情況下建議的做法是不要頻繁合併，通常只在特定的發佈點（如主線-rc發佈） 合併。如果您對特定的更改感到緊張，則可以始終在私有分支中執行測試合併。在 -這種情況下，git「rerere」工具很有用；它能記住合併衝突是如何解決的，這樣您 +這種情況下，git“rerere”工具很有用；它能記住合併衝突是如何解決的，這樣您 就不必重複相同的工作。 關於Git這樣的工具的一個最大的反覆抱怨是：補丁從一個存儲庫到另一個存儲庫的 @@ -98,36 +98,36 @@ Git提供了一些強大的工具，可以讓您重寫開發歷史。一個不 :: - 你可以給我發補丁，但當我從你那裡拉取一個Git補丁時，我需要知道你清楚 + 你可以給我發補丁，但當我從你那裏拉取一個Git補丁時，我需要知道你清楚 自己在做什麼，我需要能夠相信事情而 *無需* 手動檢查每個單獨的更改。 （http://lwn.net/Articles/224135/）。 -爲了避免這種情況，請確保給定分支中的所有補丁都與相關主題緊密相關；「驅動程序 -修復」分支不應更改核心內存管理代碼。而且，最重要的是，不要使用Git樹來繞過 -審查過程。不時的將樹的摘要發布到相關的列表中，在合適時候請求linux-next中 +爲了避免這種情況，請確保給定分支中的所有補丁都與相關主題緊密相關；“驅動程序 +修復”分支不應更改核心內存管理代碼。而且，最重要的是，不要使用Git樹來繞過 +審查過程。不時的將樹的摘要發佈到相關的列表中，在合適時候請求linux-next中 包含該樹。 如果其他人開始發送補丁以包含到您的樹中，不要忘記審閱它們。還要確保您維護正確 -的作者信息； git 「am」工具在這方面做得最好，但是如果補丁通過第三方轉發給您， -您可能需要在補丁中添加「From:」行。 +的作者信息； git “am”工具在這方面做得最好，但是如果補丁通過第三方轉發給您， +您可能需要在補丁中添加“From:”行。 請求拉取時，請務必提供所有相關信息：樹的位置、要拉取的分支以及拉取將導致的 更改。在這方面 git request-pull 命令非常有用；它將按照其他開發人員所期望的 -格式化請求，並檢查以確保您已記得將這些更改推送到公共伺服器。 +格式化請求，並檢查以確保您已記得將這些更改推送到公共服務器。 審閱補丁 -------- -一些讀者顯然會反對將本節與「高級主題」放在一起，因爲即使是剛開始的內核開發人員 -也應該審閱補丁。當然，沒有比查看其他人發布的代碼更好的方法來學習如何在內核環境 +一些讀者顯然會反對將本節與“高級主題”放在一起，因爲即使是剛開始的內核開發人員 +也應該審閱補丁。當然，沒有比查看其他人發佈的代碼更好的方法來學習如何在內核環境 中編程了。此外，審閱者永遠供不應求；通過審閱代碼，您可以對整個流程做出重大貢獻。 審查代碼可能是一副令人生畏的圖景，特別是對一個新的內核開發人員來說，他們 -可能會對公開詢問代碼感到緊張，而這些代碼是由那些有更多經驗的人發布的。不過， +可能會對公開詢問代碼感到緊張，而這些代碼是由那些有更多經驗的人發佈的。不過， 即使是最有經驗的開發人員編寫的代碼也可以得到改進。也許對（所有）審閱者最好 -的建議是：把審閱評論當成問題而不是批評。詢問「在這條路徑中如何釋放鎖？」 -總是比說「這裡的鎖是錯誤的」更好。 +的建議是：把審閱評論當成問題而不是批評。詢問“在這條路徑中如何釋放鎖？” +總是比說“這裏的鎖是錯誤的”更好。 不同的開發人員將從不同的角度審查代碼。部分人會主要關注代碼風格以及代碼行是 否有尾隨空格。其他人會主要關注補丁作爲一個整體實現的變更是否對內核有好處。 diff --git a/Documentation/translations/zh_TW/process/8.Conclusion.rst b/Documentation/translations/zh_TW/process/8.Conclusion.rst index 044fcc118bef..a0c00741f912 100644 --- a/Documentation/translations/zh_TW/process/8.Conclusion.rst +++ b/Documentation/translations/zh_TW/process/8.Conclusion.rst @@ -10,20 +10,20 @@ :校譯: 吳想成 Wu XiangCheng <bobwxc@email.cn> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> .. _tw_development_conclusion: 更多信息 ======== -關於Linux內核開發和相關主題的信息來源很多。首先是在內核原始碼分發中找到的 +關於Linux內核開發和相關主題的信息來源很多。首先是在內核源代碼分發中找到的 文檔目錄。頂級 -:ref:`Documentation/translations/zh_TW/process/howto.rst <tw_process_howto>` +:ref:`Documentation/translations/zh_CN/process/howto.rst <tw_process_howto>` 文件是一個重要的起點； -:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <tw_submittingpatches>` 也是所有內核開發人員都應該閱讀的內容。許多內部內核API都是使用kerneldoc機制 -記錄的；「make htmldocs」或「make pdfdocs」可用於以HTML或PDF格式生成這些文檔 +記錄的；“make htmldocs”或“make pdfdocs”可用於以HTML或PDF格式生成這些文檔 （儘管某些發行版提供的tex版本會遇到內部限制，無法正確處理文檔）。 不同的網站在各個細節層次上討論內核開發。本文作者想謙虛地建議用 https://lwn.net/ @@ -35,7 +35,7 @@ https://kernelnewbies.org/ -當然，也不應該忘記 https://kernel.org/ ，這是內核發布信息的最終位置。 +當然，也不應該忘記 https://kernel.org/ ，這是內核發佈信息的最終位置。 關於內核開發有很多書： @@ -47,7 +47,7 @@ 《深入理解Linux內核》(Daniel Bovet和Marco Cesati） 然而，所有這些書都有一個共同的缺點：它們上架時就往往有些過時，而且已經上架 -一段時間了。不過，在那裡還是可以找到相當多的好信息。 +一段時間了。不過，在那裏還是可以找到相當多的好信息。 有關git的文檔，請訪問： @@ -61,7 +61,7 @@ 祝賀所有通過這篇冗長的文檔的人。希望它能夠幫助您理解Linux內核是如何開發的， 以及您如何參與這個過程。 -最後，重要的是參與。任何開源軟體項目都不會超過其貢獻者投入其中的總和。Linux +最後，重要的是參與。任何開源軟件項目都不會超過其貢獻者投入其中的總和。Linux 內核的發展速度和以前一樣快，因爲它得到了大量開發人員的幫助，他們都在努力使它 變得更好。內核是一個最成功的例子，說明了當成千上萬的人爲了一個共同的目標一起 工作時，可以做出什麼。 diff --git a/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst b/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst index 949d831aaf6c..48df918000e9 100644 --- a/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst +++ b/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst @@ -4,38 +4,38 @@ :Original: :ref:`Documentation/process/code-of-conduct-interpretation.rst <code_of_conduct_interpretation>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res@email.cn> + Hu Haowen <src.res.211@gmail.com> .. _tw_code_of_conduct_interpretation: -Linux內核貢獻者契約行為準則解釋 +Linux內核貢獻者契約行爲準則解釋 =============================== :ref:`tw_code_of_conduct` 準則是一個通用文檔，旨在爲幾乎所有開源社區提供一套規則。 每個開源社區都是獨一無二的，Linux內核也不例外。因此，本文描述了Linux內核社區中 -如何解釋它。我們也不希望這種解釋隨著時間的推移是靜態的，並將根據需要進行調整。 +如何解釋它。我們也不希望這種解釋隨着時間的推移是靜態的，並將根據需要進行調整。 -與開發軟體的「傳統」方法相比，Linux內核開發工作是一個非常個人化的過程。你的貢獻 +與開發軟件的“傳統”方法相比，Linux內核開發工作是一個非常個人化的過程。你的貢獻 和背後的想法將被仔細審查，往往導致批判和批評。審查將幾乎總是需要改進，材料才 能包括在內核中。要知道這是因爲所有相關人員都希望看到Linux整體成功的最佳解決方 -案。這個開發過程已經被證明可以創建有史以來最健壯的作業系統內核，我們不想做任何 +案。這個開發過程已經被證明可以創建有史以來最健壯的操作系統內核，我們不想做任何 事情來導致提交質量和最終結果的下降。 維護者 ------ -行為準則多次使用「維護者」一詞。在內核社區中，「維護者」是負責子系統、驅動程序或 -文件的任何人，並在內核原始碼樹的維護者文件中列出。 +行爲準則多次使用“維護者”一詞。在內核社區中，“維護者”是負責子系統、驅動程序或 +文件的任何人，並在內核源代碼樹的維護者文件中列出。 責任 ---- -《行為準則》提到了維護人員的權利和責任，這需要進一步澄清。 +《行爲準則》提到了維護人員的權利和責任，這需要進一步澄清。 首先，最重要的是，有一個合理的期望是由維護人員通過實例來領導。 也就是說，我們的社區是廣闊的，對維護者沒有新的要求，他們單方面處理其他人在 -他們活躍的社區的行爲。這一責任由我們所有人承擔，最終《行為準則》記錄了最終的 +他們活躍的社區的行爲。這一責任由我們所有人承擔，最終《行爲準則》記錄了最終的 上訴路徑，以防有關行爲問題的問題懸而未決。 維護人員應該願意在出現問題時提供幫助，並在需要時與社區中的其他人合作。如果您 @@ -43,10 +43,10 @@ Linux內核貢獻者契約行為準則解釋 除非您願意，否則不會將其視爲違規報告。如果您不確定是否該聯繫TAB 或任何其他維 護人員，請聯繫我們的衝突調解人 Mishi Choudhary <mishi@linux.com>。 -最後，「善待對方」才是每個人的最終目標。我們知道每個人都是人，有時我們都會失敗， -但我們所有人的首要目標應該是努力友好地解決問題。執行行為準則將是最後的選擇。 +最後，“善待對方”纔是每個人的最終目標。我們知道每個人都是人，有時我們都會失敗， +但我們所有人的首要目標應該是努力友好地解決問題。執行行爲準則將是最後的選擇。 -我們的目標是創建一個強大的、技術先進的作業系統，以及所涉及的技術複雜性，這自 +我們的目標是創建一個強大的、技術先進的操作系統，以及所涉及的技術複雜性，這自 然需要專業知識和決策。 所需的專業知識因貢獻領域而異。它主要由上下文和技術複雜性決定，其次由貢獻者和 @@ -55,58 +55,58 @@ Linux內核貢獻者契約行為準則解釋 專家的期望和決策都要經過討論，但在最後，爲了取得進展，必須能夠做出決策。這一 特權掌握在維護人員和項目領導的手中，預計將善意使用。 -因此，設定專業知識期望、作出決定和拒絕不適當的貢獻不被視爲違反行為準則。 +因此，設定專業知識期望、作出決定和拒絕不適當的貢獻不被視爲違反行爲準則。 雖然維護人員一般都歡迎新來者，但他們幫助（新）貢獻者克服障礙的能力有限，因此 -他們必須確定優先事項。這也不應被視爲違反了行為準則。內核社區意識到這一點，並 +他們必須確定優先事項。這也不應被視爲違反了行爲準則。內核社區意識到這一點，並 以各種形式提供入門級節目，如 kernelnewbies.org 。 範圍 ---- -Linux內核社區主要在一組公共電子郵件列表上進行交互，這些列表分布在由多個不同 -公司或個人控制的多個不同伺服器上。所有這些列表都在內核原始碼樹中的 +Linux內核社區主要在一組公共電子郵件列表上進行交互，這些列表分佈在由多個不同 +公司或個人控制的多個不同服務器上。所有這些列表都在內核源代碼樹中的 MAINTAINERS 文件中定義。發送到這些郵件列表的任何電子郵件都被視爲包含在行爲 準則中。 使用 kernel.org bugzilla和其他子系統bugzilla 或bug跟蹤工具的開發人員應該遵循 -行為準則的指導原則。Linux內核社區沒有「官方」項目電子郵件地址或「官方」社交媒體 -地址。使用kernel.org電子郵件帳戶執行的任何活動必須遵循爲kernel.org發布的行爲 +行爲準則的指導原則。Linux內核社區沒有“官方”項目電子郵件地址或“官方”社交媒體 +地址。使用kernel.org電子郵件帳戶執行的任何活動必須遵循爲kernel.org發佈的行爲 準則，就像任何使用公司電子郵件帳戶的個人必須遵循該公司的特定規則一樣。 -行為準則並不禁止在郵件列表消息、內核更改日誌消息或代碼注釋中繼續包含名稱、 +行爲準則並不禁止在郵件列表消息、內核更改日誌消息或代碼註釋中繼續包含名稱、 電子郵件地址和相關注釋。 -其他論壇中的互動包括在適用於上述論壇的任何規則中，通常不包括在行為準則中。 +其他論壇中的互動包括在適用於上述論壇的任何規則中，通常不包括在行爲準則中。 除了在極端情況下可考慮的例外情況。 -提交給內核的貢獻應該使用適當的語言。在行為準則之前已經存在的內容現在不會被 +提交給內核的貢獻應該使用適當的語言。在行爲準則之前已經存在的內容現在不會被 視爲違反。然而，不適當的語言可以被視爲一個bug；如果任何相關方提交補丁， 這樣的bug將被更快地修復。當前屬於用戶/內核API的一部分的表達式，或者反映已 -發布標準或規範中使用的術語的表達式，不被視爲bug。 +發佈標準或規範中使用的術語的表達式，不被視爲bug。 執行 ---- -行為準則中列出的地址屬於行為準則委員會。https://kernel.org/code-of-conduct.html +行爲準則中列出的地址屬於行爲準則委員會。https://kernel.org/code-of-conduct.html 列出了在任何給定時間接收這些電子郵件的確切成員。成員不能訪問在加入委員會之前 或離開委員會之後所做的報告。 -最初的行為準則委員會由TAB的志願者以及作爲中立第三方的專業調解人組成。委員會 +最初的行爲準則委員會由TAB的志願者以及作爲中立第三方的專業調解人組成。委員會 的首要任務是建立文件化的流程，並將其公開。 如果報告人不希望將整個委員會納入投訴或關切，可直接聯繫委員會的任何成員，包括 調解人。 -行為準則委員會根據流程審查案例（見上文），並根據需要和適當與TAB協商，例如請求 +行爲準則委員會根據流程審查案例（見上文），並根據需要和適當與TAB協商，例如請求 和接收有關內核社區的信息。 委員會做出的任何決定都將提交到表中，以便在必要時與相關維護人員一起執行。行爲 準則委員會的決定可以通過三分之二的投票推翻。 -每季度，行為準則委員會和標籤將提供一份報告，概述行為準則委員會收到的匿名報告 +每季度，行爲準則委員會和標籤將提供一份報告，概述行爲準則委員會收到的匿名報告 及其狀態，以及任何否決決定的細節，包括完整和可識別的投票細節。 -我們希望在啓動期之後爲行為準則委員會人員配備建立一個不同的流程。發生此情況時， +我們希望在啓動期之後爲行爲準則委員會人員配備建立一個不同的流程。發生此情況時， 將使用該信息更新此文檔。 diff --git a/Documentation/translations/zh_TW/process/code-of-conduct.rst b/Documentation/translations/zh_TW/process/code-of-conduct.rst index 716e5843b6e9..a7a31de03526 100644 --- a/Documentation/translations/zh_TW/process/code-of-conduct.rst +++ b/Documentation/translations/zh_TW/process/code-of-conduct.rst @@ -4,11 +4,11 @@ :Original: :ref:`Documentation/process/code-of-conduct.rst <code_of_conduct>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res@email.cn> + Hu Haowen <src.res.211@gmail.com> .. _tw_code_of_conduct: -貢獻者契約行為準則 +貢獻者契約行爲準則 ++++++++++++++++++ 我們的誓言 @@ -35,7 +35,7 @@ * 使用性意味的語言或意象以及不受歡迎的性注意或者更過分的行爲 * 煽動、侮辱/貶損評論以及個人或政治攻擊 * 公開或私下騷擾 -* 未經明確許可，發布他人的私人信息，如物理或電子地址。 +* 未經明確許可，發佈他人的私人信息，如物理或電子地址。 * 在專業場合被合理認爲不適當的其他行爲 我們的責任 @@ -44,29 +44,29 @@ 維護人員負責澄清可接受行爲的標準，並應針對任何不可接受行爲採取適當和公平的 糾正措施。 -維護人員有權和責任刪除、編輯或拒絕與本行為準則不一致的評論、承諾、代碼、 +維護人員有權和責任刪除、編輯或拒絕與本行爲準則不一致的評論、承諾、代碼、 wiki編輯、問題和其他貢獻，或暫時或永久禁止任何貢獻者從事他們認爲不適當、 威脅、冒犯或有害的其他行爲。 範圍 ==== -當個人代表項目或其社區時，本行為準則既適用於項目空間，也適用於公共空間。 +當個人代表項目或其社區時，本行爲準則既適用於項目空間，也適用於公共空間。 代表一個項目或社區的例子包括使用一個正式的項目電子郵件地址，通過一個正式 -的社交媒體帳戶發布，或者在在線或離線事件中擔任指定的代表。項目維護人員可以 +的社交媒體帳戶發佈，或者在在線或離線事件中擔任指定的代表。項目維護人員可以 進一步定義和澄清項目的表示。 執行 ==== -如有濫用、騷擾或其他不可接受的行爲，可聯繫行為準則委員會<conduct@kernel.org>。 -所有投訴都將接受審查和調查，並將得到必要和適當的答覆。行為準則委員會有義務 -對事件報告人保密。具體執行政策的進一步細節可單獨公布。 +如有濫用、騷擾或其他不可接受的行爲，可聯繫行爲準則委員會<conduct@kernel.org>。 +所有投訴都將接受審查和調查，並將得到必要和適當的答覆。行爲準則委員會有義務 +對事件報告人保密。具體執行政策的進一步細節可單獨公佈。 歸屬 ==== -本行為準則改編自《貢獻者契約》，版本1.4，可從 +本行爲準則改編自《貢獻者契約》，版本1.4，可從 https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 獲取。 解釋 diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst index 61e614aad6a7..5749363de421 100644 --- a/Documentation/translations/zh_TW/process/coding-style.rst +++ b/Documentation/translations/zh_TW/process/coding-style.rst @@ -2,42 +2,44 @@ .. include:: ../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/process/coding-style.rst <codingstyle>` +:Original: Documentation/process/coding-style.rst .. _tw_codingstyle: -譯者:: +:譯者: + - 張樂 Zhang Le <r0bertz@gentoo.org> + - Andy Deng <theandy.deng@gmail.com> + - 吳想成 <bobwxc@email.cn> - 中文版維護者： 張樂 Zhang Le <r0bertz@gentoo.org> - 中文版翻譯者： 張樂 Zhang Le <r0bertz@gentoo.org> - 中文版校譯者： 王聰 Wang Cong <xiyou.wangcong@gmail.com> - wheelz <kernel.zeng@gmail.com> - 管旭東 Xudong Guan <xudong.guan@gmail.com> - Li Zefan <lizf@cn.fujitsu.com> - Wang Chen <wangchen@cn.fujitsu.com> - Hu Haowen <src.res@email.cn> +:校譯: + - 王聰 Wang Cong <xiyou.wangcong@gmail.com> + - wheelz <kernel.zeng@gmail.com> + - 管旭東 Xudong Guan <xudong.guan@gmail.com> + - Li Zefan <lizf@cn.fujitsu.com> + - Wang Chen <wangchen@cn.fujitsu.com> + - Hu Haowen <src.res.211@gmail.com> Linux 內核代碼風格 -========================= +================== 這是一個簡短的文檔，描述了 linux 內核的首選代碼風格。代碼風格是因人而異的， 而且我不願意把自己的觀點強加給任何人，但這就像我去做任何事情都必須遵循的原則 -那樣，我也希望在絕大多數事上保持這種的態度。請 (在寫代碼時) 至少考慮一下這裡 +那樣，我也希望在絕大多數事上保持這種的態度。請 (在寫代碼時) 至少考慮一下這裏 的代碼風格。 -首先，我建議你列印一份 GNU 代碼規範，然後不要讀。燒了它，這是一個具有重大象徵 +首先，我建議你打印一份 GNU 代碼規範，然後不要讀。燒了它，這是一個具有重大象徵 性意義的動作。 不管怎樣，現在我們開始： 1) 縮進 --------------- +------- -制表符是 8 個字符，所以縮進也是 8 個字符。有些異端運動試圖將縮進變爲 4 (甚至 +製表符是 8 個字符，所以縮進也是 8 個字符。有些異端運動試圖將縮進變爲 4 (甚至 2！) 字符深，這幾乎相當於嘗試將圓周率的值定義爲 3。 -理由：縮進的全部意義就在於清楚的定義一個控制塊起止於何處。尤其是當你盯著你的 +理由：縮進的全部意義就在於清楚的定義一個控制塊起止於何處。尤其是當你盯着你的 屏幕連續看了 20 小時之後，你將會發現大一點的縮進會使你更容易分辨縮進。 現在，有些人會抱怨 8 個字符的縮進會使代碼向右邊移動的太遠，在 80 個字符的終端 @@ -69,39 +71,60 @@ Linux 內核代碼風格 break; } -不要把多個語句放在一行里，除非你有什麼東西要隱藏： +不要把多個語句放在一行裏，除非你有什麼東西要隱藏： .. code-block:: c if (condition) do_this; do_something_everytime; -也不要在一行里放多個賦值語句。內核代碼風格超級簡單。就是避免可能導致別人誤讀 +不要使用逗號來避免使用大括號： + +.. code-block:: c + + if (condition) + do_this(), do_that(); + +使用大括號包裹多語句： + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } + +也不要在一行裏放多個賦值語句。內核代碼風格超級簡單。就是避免可能導致別人誤讀 的表達式。 -除了注釋、文檔和 Kconfig 之外，不要使用空格來縮進，前面的例子是例外，是有意爲 +除了註釋、文檔和 Kconfig 之外，不要使用空格來縮進，前面的例子是例外，是有意爲 之。 選用一個好的編輯器，不要在行尾留空格。 2) 把長的行和字符串打散 ------------------------------- +----------------------- 代碼風格的意義就在於使用平常使用的工具來維持代碼的可讀性和可維護性。 每一行的長度的限制是 80 列，我們強烈建議您遵守這個慣例。 長於 80 列的語句要打散成有意義的片段。除非超過 80 列能顯著增加可讀性，並且不 -會隱藏信息。子片段要明顯短於母片段，並明顯靠右。這同樣適用於有著很長參數列表 -的函數頭。然而，絕對不要打散對用戶可見的字符串，例如 printk 信息，因爲這樣就 +會隱藏信息。 + +子片段要明顯短於母片段，並明顯靠右。一種非常常用的樣式是將子體與函數左括號對齊。 + +這同樣適用於有着很長參數列表的函數頭。 + +然而，絕對不要打散對用戶可見的字符串，例如 printk 信息，因爲這樣就 很難對它們 grep。 3) 大括號和空格的放置 ------------------------------- +--------------------- -C 語言風格中另外一個常見問題是大括號的放置。和縮進大小不同，選擇或棄用某种放 +C 語言風格中另外一個常見問題是大括號的放置。和縮進大小不同，選擇或棄用某種放 置策略並沒有多少技術上的原因，不過首選的方式，就像 Kernighan 和 Ritchie 展示 給我們的，是把起始大括號放在行尾，而把結束大括號放在行首，所以： @@ -135,12 +158,12 @@ C 語言風格中另外一個常見問題是大括號的放置。和縮進大小 body of function } -全世界的異端可能會抱怨這個不一致性是... 呃... 不一致的，不過所有思維健全的人 +全世界的異端可能會抱怨這個不一致性是……呃……不一致，不過所有思維健全的人 都知道 (a) K&R 是 **正確的** 並且 (b) K&R 是正確的。此外，不管怎樣函數都是特 殊的 (C 函數是不能嵌套的)。 -注意結束大括號獨自占據一行，除非它後面跟著同一個語句的剩餘部分，也就是 do 語 -句中的 "while" 或者 if 語句中的 "else"，像這樣： +注意結束大括號獨自佔據一行，除非它後面跟着同一個語句的剩餘部分，也就是 do 語 +句中的 ``while`` 或者 if 語句中的 ``else`` ，像這樣： .. code-block:: c @@ -164,7 +187,7 @@ C 語言風格中另外一個常見問題是大括號的放置。和縮進大小 也請注意這種大括號的放置方式也能使空 (或者差不多空的) 行的數量最小化，同時不 失可讀性。因此，由於你的屏幕上的新行是不可再生資源 (想想 25 行的終端屏幕)，你 -將會有更多的空行來放置注釋。 +將會有更多的空行來放置註釋。 當只有一個單獨的語句的時候，不用加不必要的大括號。 @@ -194,12 +217,12 @@ C 語言風格中另外一個常見問題是大括號的放置。和縮進大小 } 3.1) 空格 -******************** +********* Linux 內核的空格使用方式 (主要) 取決於它是用於函數還是關鍵字。(大多數) 關鍵字 後要加一個空格。值得注意的例外是 sizeof, typeof, alignof 和 __attribute__，這 -些關鍵字某些程度上看起來更像函數 (它們在 Linux 里也常常伴隨小括號而使用，儘管 -在 C 里這樣的小括號不是必需的，就像 ``struct fileinfo info;`` 聲明過後的 +些關鍵字某些程度上看起來更像函數 (它們在 Linux 裏也常常伴隨小括號而使用，儘管 +在 C 裏這樣的小括號不是必需的，就像 ``struct fileinfo info;`` 聲明過後的 ``sizeof info``)。 所以在這些關鍵字之後放一個空格:: @@ -213,7 +236,7 @@ Linux 內核的空格使用方式 (主要) 取決於它是用於函數還是關 s = sizeof(struct file); -不要在小括號里的表達式兩側加空格。這是一個 **反例** ： +不要在小括號裏的表達式兩側加空格。這是一個 **反例** ： .. code-block:: c @@ -257,10 +280,10 @@ Linux 內核的空格使用方式 (主要) 取決於它是用於函數還是關 4) 命名 ------------------------------- +------- -C 是一個簡樸的語言，你的命名也應該這樣。和 Modula-2 和 Pascal 程式設計師不同， -C 程式設計師不使用類似 ThisVariableIsATemporaryCounter 這樣華麗的名字。C 程式設計師會 +C 是一個簡樸的語言，你的命名也應該這樣。和 Modula-2 和 Pascal 程序員不同， +C 程序員不使用類似 ThisVariableIsATemporaryCounter 這樣華麗的名字。C 程序員會 稱那個變量爲 ``tmp`` ，這樣寫起來會更容易，而且至少不會令其難於理解。 不過，雖然混用大小寫的名字是不提倡使用的，但是全局變量還是需要一個具描述性的 @@ -271,23 +294,42 @@ C 程式設計師不使用類似 ThisVariableIsATemporaryCounter 這樣華麗的 ``count_active_users()`` 或者類似的名字，你不應該叫它 ``cntuser()`` 。 在函數名中包含函數類型 (所謂的匈牙利命名法) 是腦子出了問題——編譯器知道那些類 -型而且能夠檢查那些類型，這樣做只能把程式設計師弄糊塗了。難怪微軟總是製造出有問題 -的程序。 +型而且能夠檢查那些類型，這樣做只能把程序員弄糊塗了。 本地變量名應該簡短，而且能夠表達相關的含義。如果你有一些隨機的整數型的循環計 數器，它應該被稱爲 ``i`` 。叫它 ``loop_counter`` 並無益處，如果它沒有被誤解的 可能的話。類似的， ``tmp`` 可以用來稱呼任意類型的臨時變量。 如果你怕混淆了你的本地變量名，你就遇到另一個問題了，叫做函數增長荷爾蒙失衡綜 -合症。請看第六章 (函數)。 +合徵。請看第六章 (函數)。 +對於符號名稱和文檔，避免引入新的“master/slave”（或獨立於“master”的“slave”） +和“blacklist/whitelist”。 + +“master/slave”推薦替換爲： + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader/follower' + 'director/performer' + +“blacklist/whitelist”推薦替換爲： + 'denylist/allowlist' + 'blocklist/passlist' + +引入新用法的例外情況是：維護用戶空間ABI/API，或更新現有（截至2020年）硬件或 +協議規範的代碼時要求這些術語。對於新規範，儘可能將術語的規範用法轉換爲內核 +編碼標準。 + +.. warning:: + 以上主從、黑白名單規則不適用於中文文檔，請勿更改中文術語！ 5) Typedef ------------ +---------- 不要使用類似 ``vps_t`` 之類的東西。 -對結構體和指針使用 typedef 是一個 **錯誤** 。當你在代碼里看到： +對結構體和指針使用 typedef 是一個 **錯誤** 。當你在代碼裏看到： .. code-block:: c @@ -312,13 +354,13 @@ C 程式設計師不使用類似 ThisVariableIsATemporaryCounter 這樣華麗的 .. note:: - 不透明性和 "訪問函數" 本身是不好的。我們使用 pte_t 等類型的原因在於真 + 不透明性和“訪問函數”本身是不好的。我們使用 pte_t 等類型的原因在於真 的是完全沒有任何共用的可訪問信息。 (b) 清楚的整數類型，如此，這層抽象就可以 **幫助** 消除到底是 ``int`` 還是 ``long`` 的混淆。 - u8/u16/u32 是完全沒有問題的 typedef，不過它們更符合類別 (d) 而不是這裡。 + u8/u16/u32 是完全沒有問題的 typedef，不過它們更符合類別 (d) 而不是這裏。 .. note:: @@ -345,30 +387,30 @@ C 程式設計師不使用類似 ThisVariableIsATemporaryCounter 這樣華麗的 (e) 可以在用戶空間安全使用的類型。 - 在某些用戶空間可見的結構體裡，我們不能要求 C99 類型而且不能用上面提到的 + 在某些用戶空間可見的結構體裏，我們不能要求 C99 類型而且不能用上面提到的 ``u32`` 類型。因此，我們在與用戶空間共享的所有結構體中使用 __u32 和類似 的類型。 可能還有其他的情況，不過基本的規則是 **永遠不要** 使用 typedef，除非你可以明 確的應用上述某個規則中的一個。 -總的來說，如果一個指針或者一個結構體裡的元素可以合理的被直接訪問到，那麼它們 +總的來說，如果一個指針或者一個結構體裏的元素可以合理的被直接訪問到，那麼它們 就不應該是一個 typedef。 6) 函數 ------------------------------- +------- 函數應該簡短而漂亮，並且只完成一件事情。函數應該可以一屏或者兩屏顯示完 (我們 都知道 ISO/ANSI 屏幕大小是 80x24)，只做一件事情，而且把它做好。 一個函數的最大長度是和該函數的複雜度和縮進級數成反比的。所以，如果你有一個理 論上很簡單的只有一個很長 (但是簡單) 的 case 語句的函數，而且你需要在每個 case -里做很多很小的事情，這樣的函數儘管很長，但也是可以的。 +裏做很多很小的事情，這樣的函數儘管很長，但也是可以的。 不過，如果你有一個複雜的函數，而且你懷疑一個天分不是很高的高中一年級學生可能 甚至搞不清楚這個函數的目的，你應該嚴格遵守前面提到的長度限制。使用輔助函數， -並爲之取個具描述性的名字 (如果你覺得它們的性能很重要的話，可以讓編譯器內聯它 +併爲之取個具描述性的名字 (如果你覺得它們的性能很重要的話，可以讓編譯器內聯它 們，這樣的效果往往會比你寫一個複雜函數的效果要好。) 函數的另外一個衡量標準是本地變量的數量。此數量不應超過 5－10 個，否則你的函數 @@ -376,7 +418,7 @@ C 程式設計師不使用類似 ThisVariableIsATemporaryCounter 這樣華麗的 的同時跟蹤 7 個不同的事物，如果再增多的話，就會糊塗了。即便你聰穎過人，你也可 能會記不清你 2 個星期前做過的事情。 -在源文件里，使用空行隔開不同的函數。如果該函數需要被導出，它的 **EXPORT** 宏 +在源文件裏，使用空行隔開不同的函數。如果該函數需要被導出，它的 **EXPORT** 宏 應該緊貼在它的結束大括號之下。比如： .. code-block:: c @@ -387,12 +429,46 @@ C 程式設計師不使用類似 ThisVariableIsATemporaryCounter 這樣華麗的 } EXPORT_SYMBOL(system_is_up); -在函數原型中，包含函數名和它們的數據類型。雖然 C 語言裡沒有這樣的要求，在 -Linux 里這是提倡的做法，因爲這樣可以很簡單的給讀者提供更多的有價值的信息。 +6.1) 函數原型 +************* + +在函數原型中包含參數名和它們的數據類型。雖然 C 語言裏沒有這樣的要求，但在 +Linux 裏這是提倡的做法，因爲這樣可以很簡單的給讀者提供更多的有價值的信息。 +不要在函數聲明裏使用 ``extern`` 關鍵字，因爲這會導致代碼行變長，並且不是嚴格 +必需的。 + +寫函數原型時，請保持 `元素順序規則 <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_ 。 +例如下列函數聲明:: + + __init void * __must_check action(enum magic value, size_t size, u8 count, + char *fmt, ...) __printf(4, 5) __malloc; + +推薦的函數原型元素順序是： + +- 儲存類型（下方的 ``static __always_inline`` ，注意 ``__always_inline`` + 技術上來講是個屬性但被當做 ``inline`` ） +- 儲存類型屬性（上方的 ``__init`` ——即節聲明，但也像 ``__cold`` ） +- 返回類型（上方的 ``void *`` ） +- 返回類型屬性（上方的 ``__must_check`` ） +- 函數名（上方的 ``action`` ） +- 函數參數（上方的 ``(enum magic value, size_t size, u8 count, char *fmt, ...)`` ， + 注意必須寫上參數名） +- 函數參數屬性（上方的 ``__printf(4, 5)`` ） +- 函數行爲屬性（上方的 ``__malloc`` ） + +請注意，對於函數 **定義** （即實際函數體），編譯器不允許在函數參數之後添加函 +數參數屬性。在這種情況下，它們應該跟隨存儲類型屬性（例如，與上面的 **聲明** +示例相比，請注意下面的 ``__printf(4, 5)`` 的位置發生了變化）:: + + static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value, + size_t size, u8 count, char *fmt, ...) __malloc + { + ... + } 7) 集中的函數退出途徑 ------------------------------- +--------------------- 雖然被某些人聲稱已經過時，但是 goto 語句的等價物還是經常被編譯器所使用，具體 形式是無條件跳轉指令。 @@ -436,7 +512,7 @@ Linux 里這是提倡的做法，因爲這樣可以很簡單的給讀者提供 return result; } -一個需要注意的常見錯誤是 ``一個 err 錯誤`` ，就像這樣： +一個需要注意的常見錯誤是 ``單 err 錯誤`` ，就像這樣： .. code-block:: c @@ -459,22 +535,22 @@ Linux 里這是提倡的做法，因爲這樣可以很簡單的給讀者提供 理想情況下，你應該模擬錯誤來測試所有退出路徑。 -8) 注釋 ------------------------------- +8) 註釋 +------- -注釋是好的，不過有過度注釋的危險。永遠不要在注釋里解釋你的代碼是如何運作的： +註釋是好的，不過有過度註釋的危險。永遠不要在註釋裏解釋你的代碼是如何運作的： 更好的做法是讓別人一看你的代碼就可以明白，解釋寫的很差的代碼是浪費時間。 -一般的，你想要你的注釋告訴別人你的代碼做了什麼，而不是怎麼做的。也請你不要把 -注釋放在一個函數體內部：如果函數複雜到你需要獨立的注釋其中的一部分，你很可能 +一般來說你用註釋告訴別人你的代碼做了什麼，而不是怎麼做的。也請你不要把 +註釋放在一個函數體內部：如果函數複雜到你需要獨立的註釋其中的一部分，你很可能 需要回到第六章看一看。你可以做一些小注釋來註明或警告某些很聰明 (或者槽糕) 的 -做法，但不要加太多。你應該做的，是把注釋放在函數的頭部，告訴人們它做了什麼， +做法，但不要加太多。你應該做的，是把註釋放在函數的頭部，告訴人們它做了什麼， 也可以加上它做這些事情的原因。 -當注釋內核 API 函數時，請使用 kernel-doc 格式。請看 -Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 +當註釋內核 API 函數時，請使用 kernel-doc 格式。詳見 +Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。 -長 (多行) 注釋的首選風格是： +長 (多行) 註釋的首選風格是： .. code-block:: c @@ -487,7 +563,7 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 * with beginning and ending almost-blank lines. */ -對於在 net/ 和 drivers/net/ 的文件，首選的長 (多行) 注釋風格有些不同。 +對於在 net/ 和 drivers/net/ 的文件，首選的長 (多行) 註釋風格有些不同。 .. code-block:: c @@ -498,23 +574,24 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 * but there is no initial almost-blank line. */ -注釋數據也是很重要的，不管是基本類型還是衍生類型。爲了方便實現這一點，每一行 +註釋數據也是很重要的，不管是基本類型還是衍生類型。爲了方便實現這一點，每一行 應只聲明一個數據 (不要使用逗號來一次聲明多個數據)。這樣你就有空間來爲每個數據 寫一段小注釋來解釋它們的用途了。 9) 你已經把事情弄糟了 ------------------------------- +--------------------- -這沒什麼，我們都是這樣。可能你的使用了很長時間 Unix 的朋友已經告訴你 -``GNU emacs`` 能自動幫你格式化 C 原始碼，而且你也注意到了，確實是這樣，不過它 +這沒什麼，我們都是這樣。可能你長期使用 Unix 的朋友已經告訴你 +``GNU emacs`` 能自動幫你格式化 C 源代碼，而且你也注意到了，確實是這樣，不過它 所使用的默認值和我們想要的相去甚遠 (實際上，甚至比隨機打的還要差——無數個猴子 -在 GNU emacs 里打字永遠不會創造出一個好程序) (譯註：Infinite Monkey Theorem) +在 GNU emacs 裏打字永遠不會創造出一個好程序) +*(譯註：Infinite Monkey Theorem)* 所以你要麼放棄 GNU emacs，要麼改變它讓它使用更合理的設定。要採用後一個方案， -你可以把下面這段粘貼到你的 .emacs 文件里。 +你可以把下面這段粘貼到你的 .emacs 文件裏。 -.. code-block:: none +.. code-block:: elisp (defun c-lineup-arglist-tabs-only (ignored) "Line up argument lists by tabs, not spaces" @@ -533,7 +610,7 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 (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) @@ -565,24 +642,29 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 這會讓 emacs 在 ``~/src/linux-trees`` 下的 C 源文件獲得更好的內核代碼風格。 -不過就算你嘗試讓 emacs 正確的格式化代碼失敗了，也並不意味著你失去了一切：還可 +不過就算你嘗試讓 emacs 正確的格式化代碼失敗了，也並不意味着你失去了一切：還可 以用 ``indent`` 。 不過，GNU indent 也有和 GNU emacs 一樣有問題的設定，所以你需要給它一些命令選 項。不過，這還不算太糟糕，因爲就算是 GNU indent 的作者也認同 K&R 的權威性 (GNU 的人並不是壞人，他們只是在這個問題上被嚴重的誤導了)，所以你只要給 indent 指定選項 ``-kr -i8`` (代表 ``K&R，8 字符縮進``)，或使用 ``scripts/Lindent`` -這樣就可以以最時髦的方式縮進原始碼。 +這樣就可以以最時髦的方式縮進源代碼。 -``indent`` 有很多選項，特別是重新格式化注釋的時候，你可能需要看一下它的手冊。 +``indent`` 有很多選項，特別是重新格式化註釋的時候，你可能需要看一下它的手冊。 不過記住： ``indent`` 不能修正壞的編程習慣。 +請注意，您還可以使用 ``clang-format`` 工具幫助您處理這些規則，快速自動重新格 +式化部分代碼，並審閱整個文件以發現代碼風格錯誤、打字錯誤和可能的改進。它還可 +以方便地排序 ``#include`` ，對齊變量/宏，重排文本和其他類似任務。 +詳見 Documentation/process/clang-format.rst 。 + 10) Kconfig 配置文件 ------------------------------- +-------------------- -對於遍布源碼樹的所有 Kconfig* 配置文件來說，它們縮進方式有所不同。緊挨著 -``config`` 定義的行，用一個制表符縮進，然而 help 信息的縮進則額外增加 2 個空 +對於遍佈源碼樹的所有 Kconfig* 配置文件來說，它們縮進方式有所不同。緊挨着 +``config`` 定義的行，用一個製表符縮進，然而 help 信息的縮進則額外增加 2 個空 格。舉個例子:: config AUDIT @@ -594,7 +676,7 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 logging of avc messages output). Does not do system-call auditing without CONFIG_AUDITSYSCALL. -而那些危險的功能 (比如某些文件系統的寫支持) 應該在它們的提示字符串里顯著的聲 +而那些危險的功能 (比如某些文件系統的寫支持) 應該在它們的提示字符串裏顯著的聲 明這一點:: config ADFS_FS_RW @@ -602,17 +684,17 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 depends on ADFS_FS ... -要查看配置文件的完整文檔，請看 Documentation/kbuild/kconfig-language.rst。 +要查看配置文件的完整文檔，請看 Documentation/kbuild/kconfig-language.rst 。 11) 數據結構 ------------------------------- +------------ -如果一個數據結構，在創建和銷毀它的單線執行環境之外可見，那麼它必須要有一個引 -用計數器。內核里沒有垃圾收集 (並且內核之外的垃圾收集慢且效率低下)，這意味著你 +如果一個數據結構，在創建和銷燬它的單線執行環境之外可見，那麼它必須要有一個引 +用計數器。內核裏沒有垃圾收集 (並且內核之外的垃圾收集慢且效率低下)，這意味着你 絕對需要記錄你對這種數據結構的使用情況。 -引用計數意味著你能夠避免上鎖，並且允許多個用戶並行訪問這個數據結構——而不需要 +引用計數意味着你能夠避免上鎖，並且允許多個用戶並行訪問這個數據結構——而不需要 擔心這個數據結構僅僅因爲暫時不被使用就消失了，那些用戶可能不過是沉睡了一陣或 者做了一些其他事情而已。 @@ -626,13 +708,13 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 mm_count)，和文件系統 (``struct super_block``: s_count 和 s_active) 中找到。 記住：如果另一個執行線索可以找到你的數據結構，但這個數據結構沒有引用計數器， -這裡幾乎肯定是一個 bug。 +這裏幾乎肯定是一個 bug。 12) 宏，枚舉和RTL ------------------------------- +----------------- -用於定義常量的宏的名字及枚舉里的標籤需要大寫。 +用於定義常量的宏的名字及枚舉裏的標籤需要大寫。 .. code-block:: c @@ -642,9 +724,9 @@ mm_count)，和文件系統 (``struct super_block``: s_count 和 s_active) 中 宏的名字請用大寫字母，不過形如函數的宏的名字可以用小寫字母。 -一般的，如果能寫成內聯函數就不要寫成像函數的宏。 +通常如果能寫成內聯函數就不要寫成像函數的宏。 -含有多個語句的宏應該被包含在一個 do-while 代碼塊里： +含有多個語句的宏應該被包含在一個 do-while 代碼塊裏： .. code-block:: c @@ -667,7 +749,7 @@ mm_count)，和文件系統 (``struct super_block``: s_count 和 s_active) 中 } while (0) **非常** 不好。它看起來像一個函數，不過卻能導致 ``調用`` 它的函數退出；不要打 -亂讀者大腦里的語法分析器。 +亂讀者大腦裏的語法分析器。 2) 依賴於一個固定名字的本地變量的宏： @@ -689,7 +771,7 @@ mm_count)，和文件系統 (``struct super_block``: s_count 和 s_active) 中 #define CONSTANT 0x4000 #define CONSTEXP (CONSTANT | 3) -5) 在宏里定義類似函數的本地變量時命名衝突： +5) 在宏裏定義類似函數的本地變量時命名衝突： .. code-block:: c @@ -700,45 +782,46 @@ mm_count)，和文件系統 (``struct super_block``: s_count 和 s_active) 中 (ret); \ }) -ret 是本地變量的通用名字 - __foo_ret 更不容易與一個已存在的變量衝突。 +ret 是本地變量的通用名字—— __foo_ret 更不容易與一個已存在的變量衝突。 -cpp 手冊對宏的講解很詳細。gcc internals 手冊也詳細講解了 RTL，內核里的彙編語 +cpp 手冊對宏的講解很詳細。gcc internals 手冊也詳細講解了 RTL，內核裏的彙編語 言經常用到它。 -13) 列印內核消息 ------------------------------- +13) 打印內核消息 +---------------- -內核開發者應該是受過良好教育的。請一定注意內核信息的拼寫，以給人以好的印象。 +內核開發者應該看起來有文化。請一定注意內核信息的拼寫，以給人良好的印象。 不要用不規範的單詞比如 ``dont``，而要用 ``do not`` 或者 ``don't`` 。保證這些信 -息簡單明了,無歧義。 +息簡單明瞭、無歧義。 內核信息不必以英文句號結束。 -在小括號里列印數字 (%d) 沒有任何價值，應該避免這樣做。 +在小括號裏打印數字 (%d) 沒有任何價值，應該避免這樣做。 -<linux/device.h> 里有一些驅動模型診斷宏，你應該使用它們，以確保信息對應於正確 +<linux/device.h> 裏有一些驅動模型診斷宏，你應該使用它們，以確保信息對應於正確 的設備和驅動，並且被標記了正確的消息級別。這些宏有：dev_err(), dev_warn(), dev_info() 等等。對於那些不和某個特定設備相關連的信息，<linux/printk.h> 定義 了 pr_notice(), pr_info(), pr_warn(), pr_err() 和其他。 寫出好的調試信息可以是一個很大的挑戰；一旦你寫出後，這些信息在遠程除錯時能提 -供極大的幫助。然而列印調試信息的處理方式同列印非調試信息不同。其他 pr_XXX() -函數能無條件地列印，pr_debug() 卻不；默認情況下它不會被編譯，除非定義了 DEBUG +供極大的幫助。然而打印調試信息的處理方式同打印非調試信息不同。其他 pr_XXX() +函數能無條件地打印，pr_debug() 卻不；默認情況下它不會被編譯，除非定義了 DEBUG 或設定了 CONFIG_DYNAMIC_DEBUG。實際這同樣是爲了 dev_dbg()，一個相關約定是在一 個已經開啓了 DEBUG 時，使用 VERBOSE_DEBUG 來添加 dev_vdbg()。 -許多子系統擁有 Kconfig 調試選項來開啓 -DDEBUG 在對應的 Makefile 裡面；在其他 -情況下，特殊文件使用 #define DEBUG。當一條調試信息需要被無條件列印時，例如， +許多子系統擁有 Kconfig 調試選項來開啓對應 Makefile 裏面的 -DDEBUG；在其他 +情況下，特殊文件使用 #define DEBUG。當一條調試信息需要被無條件打印時，例如， 如果已經包含一個調試相關的 #ifdef 條件，printk(KERN_DEBUG ...) 就可被使用。 14) 分配內存 ------------------------------- +------------ 內核提供了下面的一般用途的內存分配函數： kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() 和 vzalloc()。 -請參考 API 文檔以獲取有關它們的詳細信息。 +請參考 API 文檔以獲取有關它們的詳細信息： +Documentation/translations/zh_CN/core-api/memory-allocation.rst 。 傳遞結構體大小的首選形式是這樣的： @@ -765,17 +848,19 @@ kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() 和 vzalloc()。 p = kcalloc(n, sizeof(...), ...); -兩種形式檢查分配大小 n * sizeof(...) 的溢出，如果溢出返回 NULL。 +兩種形式都會檢查分配 n * sizeof(...) 大小時內存的溢出，如果溢出返回 NULL。 +在沒有 __GFP_NOWARN 的情況下使用時，這些通用分配函數都會在失敗時發起堆棧轉儲， +因此當返回NULL時，沒有必要發出額外的失敗消息。 15) 內聯弊病 ------------------------------- +------------ 有一個常見的誤解是 ``內聯`` 是 gcc 提供的可以讓代碼運行更快的一個選項。雖然使 用內聯函數有時候是恰當的 (比如作爲一種替代宏的方式，請看第十二章)，不過很多情 況下不是這樣。inline 的過度使用會使內核變大，從而使整個系統運行速度變慢。 -因爲體積大內核會占用更多的指令高速緩存，而且會導致 pagecache 的可用內存減少。 -想像一下，一次 pagecache 未命中就會導致一次磁碟尋址，將耗時 5 毫秒。5 毫秒的 +因爲體積大內核會佔用更多的指令高速緩存，而且會導致 pagecache 的可用內存減少。 +想象一下，一次 pagecache 未命中就會導致一次磁盤尋址，將耗時 5 毫秒。5 毫秒的 時間內 CPU 能執行很多很多指令。 一個基本的原則是如果一個函數有 3 行以上，就不要把它變成內聯函數。這個原則的一 @@ -790,7 +875,7 @@ inline gcc 也可以自動使其內聯。而且其他用戶可能會要求移除 16) 函數返回值及命名 ------------------------------- +-------------------- 函數可以返回多種不同類型的值，最常見的一種是表明函數執行成功或者失敗的值。這樣 的一個值可以表示爲一個錯誤代碼整數 (-Exxx＝失敗，0＝成功) 或者一個 ``成功`` @@ -801,7 +886,7 @@ inline gcc 也可以自動使其內聯。而且其他用戶可能會要求移除 產生這種 bug，請遵循下面的慣例:: 如果函數的名字是一個動作或者強制性的命令，那麼這個函數應該返回錯誤代 - 碼整數。如果是一個判斷，那麼函數應該返回一個 "成功" 布爾值。 + 碼整數。如果是一個判斷，那麼函數應該返回一個“成功”布爾值。 比如， ``add work`` 是一個命令，所以 add_work() 在成功時返回 0，在失敗時返回 -EBUSY。類似的，因爲 ``PCI device present`` 是一個判斷，所以 pci_dev_present() @@ -810,13 +895,35 @@ inline gcc 也可以自動使其內聯。而且其他用戶可能會要求移除 所有 EXPORTed 函數都必須遵守這個慣例，所有的公共函數也都應該如此。私有 (static) 函數不需要如此，但是我們也推薦這樣做。 -返回值是實際計算結果而不是計算是否成功的標誌的函數不受此慣例的限制。一般的， +返回值是實際計算結果而不是計算是否成功的標誌的函數不受此慣例的限制。通常 他們通過返回一些正常值範圍之外的結果來表示出錯。典型的例子是返回指針的函數， 他們使用 NULL 或者 ERR_PTR 機制來報告錯誤。 +17) 使用布爾類型 +---------------- + +Linux內核布爾（bool）類型是C99 _Bool類型的別名。布爾值只能爲0或1，而對布爾的 +隱式或顯式轉換將自動將值轉換爲true或false。在使用布爾類型時 **不需要** 構造， +它會消除一類錯誤。 + +使用布爾值時，應使用true和false定義，而不是1和0。 -17) 不要重新發明內核宏 ------------------------------- +布爾函數返回類型和堆棧變量總是可以在適當的時候使用。鼓勵使用布爾來提高可讀性， +並且布爾值在存儲時通常比“int”更好。 + +如果緩存行佈局或值的大小很重要，請不要使用布爾，因爲其大小和對齊方式根據編譯 +的體系結構而不同。針對對齊和大小進行優化的結構體不應使用布爾。 + +如果一個結構體有多個true/false值，請考慮將它們合併爲具有1比特成員的位域，或使 +用適當的固定寬度類型，如u8。 + +類似地，對於函數參數，多個true/false值可以合併爲單個按位的“標誌”參數，如果調 +用點具有裸true/false常量，“標誌”參數通常是更具可讀性的替代方法。 + +總之，在結構體和參數中有限地使用布爾可以提高可讀性。 + +18) 不要重新發明內核宏 +---------------------- 頭文件 include/linux/kernel.h 包含了一些宏，你應該使用它們，而不要自己寫一些 它們的變種。比如，如果你需要計算一個數組的長度，使用這個宏 @@ -832,15 +939,15 @@ inline gcc 也可以自動使其內聯。而且其他用戶可能會要求移除 #define sizeof_field(t, f) (sizeof(((t*)0)->f)) 還有可以做嚴格的類型檢查的 min() 和 max() 宏，如果你需要可以使用它們。你可以 -自己看看那個頭文件里還定義了什麼你可以拿來用的東西，如果有定義的話，你就不應 -在你的代碼里自己重新定義。 +自己看看那個頭文件裏還定義了什麼你可以拿來用的東西，如果有定義的話，你就不應 +在你的代碼裏自己重新定義。 -18) 編輯器模式行和其他需要羅嗦的事情 --------------------------------------------------- +19) 編輯器模式行和其他需要羅嗦的事情 +------------------------------------ -有一些編輯器可以解釋嵌入在源文件里的由一些特殊標記標明的配置信息。比如，emacs -能夠解釋被標記成這樣的行： +有一些編輯器可以解釋嵌入在源文件裏的由一些特殊標記標明的配置信息。比如，emacs +能夠解析被標記成這樣的行： .. code-block:: c @@ -856,23 +963,23 @@ inline gcc 也可以自動使其內聯。而且其他用戶可能會要求移除 End: */ -Vim 能夠解釋這樣的標記： +Vim 能夠解析這樣的標記： .. code-block:: c /* vim:set sw=8 noet */ -不要在原始碼中包含任何這樣的內容。每個人都有他自己的編輯器配置，你的源文件不 +不要在源代碼中包含任何這樣的內容。每個人都有他自己的編輯器配置，你的源文件不 應該覆蓋別人的配置。這包括有關縮進和模式配置的標記。人們可以使用他們自己定製 的模式，或者使用其他可以產生正確的縮進的巧妙方法。 -19) 內聯彙編 ------------------------------- +20) 內聯彙編 +------------ -在特定架構的代碼中，你可能需要內聯彙編與 CPU 和平台相關功能連接。需要這麼做時 +在特定架構的代碼中，你可能需要內聯彙編與 CPU 和平臺相關功能連接。需要這麼做時 就不要猶豫。然而，當 C 可以完成工作時，不要平白無故地使用內聯彙編。在可能的情 -況下，你可以並且應該用 C 和硬體溝通。 +況下，你可以並且應該用 C 和硬件溝通。 請考慮去寫捆綁通用位元 (wrap common bits) 的內聯彙編的簡單輔助函數，別去重複 地寫下只有細微差異內聯彙編。記住內聯彙編可以使用 C 參數。 @@ -883,9 +990,9 @@ Vim 能夠解釋這樣的標記： 你可能需要把彙編語句標記爲 volatile，用來阻止 GCC 在沒發現任何副作用後就把它 移除了。你不必總是這樣做，儘管，這不必要的舉動會限制優化。 -在寫一個包含多條指令的單個內聯彙編語句時，把每條指令用引號分割而且各占一行， -除了最後一條指令外，在每個指令結尾加上 \n\t，讓彙編輸出時可以正確地縮進下一條 -指令： +在寫一個包含多條指令的單個內聯彙編語句時，把每條指令用引號分割而且各佔一行， +除了最後一條指令外，在每個指令結尾加上 ``\n\t`` ，讓彙編輸出時可以正確地縮進 +下一條指令： .. code-block:: c @@ -894,10 +1001,10 @@ Vim 能夠解釋這樣的標記： : /* outputs */ : /* inputs */ : /* clobbers */); -20) 條件編譯 ------------------------------- +21) 條件編譯 +------------ -只要可能，就不要在 .c 文件裡面使用預處理條件 (#if, #ifdef)；這樣做讓代碼更難 +只要可能，就不要在 .c 文件裏面使用預處理條件 (#if, #ifdef)；這樣做會讓代碼更難 閱讀並且更難去跟蹤邏輯。替代方案是，在頭文件中用預處理條件提供給那些 .c 文件 使用，再給 #else 提供一個空樁 (no-op stub) 版本，然後在 .c 文件內無條件地調用 那些 (定義在頭文件內的) 函數。這樣做，編譯器會避免爲樁函數 (stub) 的調用生成 @@ -908,8 +1015,8 @@ Vim 能夠解釋這樣的標記： 條件到這個輔助函數內。 如果你有一個在特定配置中，可能變成未使用的函數或變量，編譯器會警告它定義了但 -未使用，把它標記爲 __maybe_unused 而不是將它包含在一個預處理條件中。(然而，如 -果一個函數或變量總是未使用，就直接刪除它。) +未使用，請把它標記爲 __maybe_unused 而不是將它包含在一個預處理條件中。(然而， +如果一個函數或變量總是未使用，就直接刪除它。) 在代碼中，儘可能地使用 IS_ENABLED 宏來轉化某個 Kconfig 標記爲 C 的布爾 表達式，並在一般的 C 條件中使用它： @@ -926,7 +1033,7 @@ Vim 能夠解釋這樣的標記： 不存在時，你還是必須去用 #ifdef。 在任何有意義的 #if 或 #ifdef 塊的末尾 (超過幾行的)，在 #endif 同一行的後面寫下 -註解，注釋這個條件表達式。例如： +註解，註釋這個條件表達式。例如： .. code-block:: c @@ -935,24 +1042,46 @@ Vim 能夠解釋這樣的標記： #endif /* CONFIG_SOMETHING */ -附錄 I) 參考 -------------------- +附錄 I) 參考資料 +---------------- -The C Programming Language, 第二版 +The C Programming Language, 2nd Edition 作者：Brian W. Kernighan 和 Denni M. Ritchie. Prentice Hall, Inc., 1988. -ISBN 0-13-110362-8 (軟皮), 0-13-110370-9 (硬皮). +ISBN 0-13-110362-8 (平裝), 0-13-110370-9 (精裝). + +.. note:: + + 《C程序設計語言（第2版）》 + 作者：[美] Brian W. Kernighan / [美] Dennis M. Ritchie + 譯者：徐寶文 / 李志 / 尤晉元（審校） + 出版社：機械工業出版社，2019 + ISBN：9787111617945 The Practice of Programming 作者：Brian W. Kernighan 和 Rob Pike. Addison-Wesley, Inc., 1999. ISBN 0-201-61586-X. +.. note:: + + 《程序設計實踐》 + 作者：[美] Brian W. Kernighan / [美] Rob Pike + 出版社：機械工業出版社，2005 + ISBN：9787111091578 + + 《程序設計實踐》 + 作者：[美] Brian W. Kernighan / Rob Pike + 譯者：裘宗燕 + 出版社：機械工業出版社，2000 + ISBN：9787111075738 + GNU 手冊 - 遵循 K&R 標準和此文本 - cpp, gcc, gcc internals and indent, 都可以從 https://www.gnu.org/manual/ 找到 WG14 是 C 語言的國際標準化工作組，URL: http://www.open-std.org/JTC1/SC22/WG14/ -Kernel process/coding-style.rst，作者 greg@kroah.com 發表於 OLS 2002： +內核文檔 Documentation/process/coding-style.rst， +作者 greg@kroah.com 發表於 OLS 2002： http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/translations/zh_TW/process/development-process.rst b/Documentation/translations/zh_TW/process/development-process.rst index 45e6385647cd..7d803d3db89e 100644 --- a/Documentation/translations/zh_TW/process/development-process.rst +++ b/Documentation/translations/zh_TW/process/development-process.rst @@ -4,7 +4,7 @@ :Original: :ref:`Documentation/process/development-process.rst <development_process_main>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res@email.cn> + Hu Haowen <src.res.211@gmail.com> .. _tw_development_process_main: @@ -26,5 +26,5 @@ 7.AdvancedTopics 8.Conclusion -本文檔的目的是幫助開發人員（及其經理）以最小的挫折感與開發社區合作。它試圖記錄這個社區如何以一種不熟悉Linux內核開發（或者實際上是自由軟體開發）的人可以訪問的方式工作。雖然這裡有一些技術資料，但這是一個面向過程的討論，不需要深入了解內核編程就可以理解。 +本文檔的目的是幫助開發人員（及其經理）以最小的挫折感與開發社區合作。它試圖記錄這個社區如何以一種不熟悉Linux內核開發（或者實際上是自由軟件開發）的人可以訪問的方式工作。雖然這裏有一些技術資料，但這是一個面向過程的討論，不需要深入瞭解內核編程就可以理解。 diff --git a/Documentation/translations/zh_TW/process/email-clients.rst b/Documentation/translations/zh_TW/process/email-clients.rst index 4ba543d06f3b..55e10d3fc28a 100644 --- a/Documentation/translations/zh_TW/process/email-clients.rst +++ b/Documentation/translations/zh_TW/process/email-clients.rst @@ -1,20 +1,21 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. _tw_email_clients: +.. SPDX-License-Identifier: GPL-2.0-or-later .. include:: ../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/process/email-clients.rst <email_clients>` +.. _tw_email_clients: -譯者:: +:Original: Documentation/process/email-clients.rst - 中文版維護者： 賈威威 Harry Wei <harryxiyou@gmail.com> - 中文版翻譯者： 賈威威 Harry Wei <harryxiyou@gmail.com> - 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> - 中文版校譯者： Yinglin Luan <synmyth@gmail.com> - Xiaochen Wang <wangxiaochen0@gmail.com> - yaxinsn <yaxinsn@163.com> - Hu Haowen <src.res@email.cn> +:譯者: + - 賈威威 Harry Wei <harryxiyou@gmail.com> + - 時奎亮 Alex Shi <alexs@kernel.org> + - 吳想成 Wu XiangCheng <bobwxc@email.cn> + +:校譯: + - Yinglin Luan <synmyth@gmail.com> + - Xiaochen Wang <wangxiaochen0@gmail.com> + - yaxinsn <yaxinsn@163.com> + - Hu Haowen <src.res.211@gmail.com> Linux郵件客戶端配置信息 ======================= @@ -30,30 +31,35 @@ Git 改日誌。如果工作正常，再將補丁發送到相應的郵件列表。 -普通配置 +通用配置 -------- + Linux內核補丁是通過郵件被提交的，最好把補丁作爲郵件體的內嵌文本。有些維護者 接收附件，但是附件的內容格式應該是"text/plain"。然而，附件一般是不贊成的， 因爲這會使補丁的引用部分在評論過程中變的很困難。 +同時也強烈建議在補丁或其他郵件的正文中使用純文本格式。https://useplaintext.email +有助於瞭解如何配置你喜歡的郵件客戶端，並在您還沒有首選的情況下列出一些推薦的 +客戶端。 + 用來發送Linux內核補丁的郵件客戶端在發送補丁時應該處於文本的原始狀態。例如， -他們不能改變或者刪除制表符或者空格，甚至是在每一行的開頭或者結尾。 +他們不能改變或者刪除製表符或者空格，甚至是在每一行的開頭或者結尾。 不要通過"format=flowed"模式發送補丁。這樣會引起不可預期以及有害的斷行。 不要讓你的郵件客戶端進行自動換行。這樣也會破壞你的補丁。 -郵件客戶端不能改變文本的字符集編碼方式。要發送的補丁只能是ASCII或者UTF-8編碼方式， -如果你使用UTF-8編碼方式發送郵件，那麼你將會避免一些可能發生的字符集問題。 +郵件客戶端不能改變文本的字符集編碼方式。要發送的補丁只能是ASCII或者UTF-8編碼 +方式，如果你使用UTF-8編碼方式發送郵件，那麼你將會避免一些可能發生的字符集問題。 -郵件客戶端應該形成並且保持 References: 或者 In-Reply-To: 標題，那麼 -郵件話題就不會中斷。 +郵件客戶端應該生成並且保持“References:”或者“In-Reply-To:”郵件頭，這樣郵件會話 +就不會中斷。 -複製粘帖(或者剪貼粘帖)通常不能用於補丁，因爲制表符會轉換爲空格。使用xclipboard, xclip -或者xcutsel也許可以，但是最好測試一下或者避免使用複製粘帖。 +複製粘帖(或者剪貼粘帖)通常不能用於補丁，因爲製表符會轉換爲空格。使用xclipboard, +xclip或者xcutsel也許可以，但是最好測試一下或者避免使用複製粘帖。 -不要在使用PGP/GPG署名的郵件中包含補丁。這樣會使得很多腳本不能讀取和適用於你的補丁。 -（這個問題應該是可以修復的） +不要在使用PGP/GPG簽名的郵件中包含補丁。這樣會使得很多腳本不能讀取和適用於你的 +補丁。（這個問題應該是可以修復的） 在給內核郵件列表發送補丁之前，給自己發送一個補丁是個不錯的主意，保存接收到的 郵件，將補丁用'patch'命令打上，如果成功了，再給內核郵件列表發送。 @@ -61,100 +67,135 @@ Linux內核補丁是通過郵件被提交的，最好把補丁作爲郵件體的 一些郵件客戶端提示 ------------------ -這裡給出一些詳細的MUA配置提示，可以用於給Linux內核發送補丁。這些並不意味是 -所有的軟體包配置總結。 + +這裏給出一些詳細的MUA配置提示，可以用於給Linux內核發送補丁。這些並不意味是 +所有的軟件包配置總結。 說明： -TUI = 以文本爲基礎的用戶接口 -GUI = 圖形界面用戶接口 + +- TUI = 以文本爲基礎的用戶接口 +- GUI = 圖形界面用戶接口 Alpine (TUI) -~~~~~~~~~~~~ +************ 配置選項： -在"Sending Preferences"部分： -- "Do Not Send Flowed Text"必須開啓 -- "Strip Whitespace Before Sending"必須關閉 +在 :menuselection:`Sending Preferences` 菜單： + +- :menuselection:`Do Not Send Flowed Text` 必須開啓 +- :menuselection:`Strip Whitespace Before Sending` 必須關閉 + +當寫郵件時，光標應該放在補丁會出現的地方，然後按下 :kbd:`CTRL-R` 組合鍵，使指 +定的補丁文件嵌入到郵件中。 -當寫郵件時，光標應該放在補丁會出現的地方，然後按下CTRL-R組合鍵，使指定的 -補丁文件嵌入到郵件中。 +Claws Mail (GUI) +**************** + +可以用，有人用它成功地發過補丁。 + +用 :menuselection:`Message-->Insert File` (:kbd:`CTRL-I`) 或外置編輯器插入補丁。 + +若要在Claws編輯窗口重修改插入的補丁，需關閉 +:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` +的 `Auto wrapping` 。 Evolution (GUI) -~~~~~~~~~~~~~~~ +*************** -一些開發者成功的使用它發送補丁 +一些開發者成功的使用它發送補丁。 -當選擇郵件選項：Preformat - 從Format->Heading->Preformatted (Ctrl-7)或者工具欄 +撰寫郵件時： +從 :menuselection:`格式-->段落樣式-->預格式化` (:kbd:`CTRL-7`) +或工具欄選擇 :menuselection:`預格式化` ； 然後使用： - Insert->Text File... (Alt-n x)插入補丁文件。 +:menuselection:`插入-->文本文件...` (:kbd:`ALT-N x`) 插入補丁文件。 -你還可以"diff -Nru old.c new.c | xclip"，選擇Preformat，然後使用中間鍵進行粘帖。 +你還可以 ``diff -Nru old.c new.c | xclip`` ，選擇 :menuselection:`預格式化` ， +然後使用鼠標中鍵進行粘帖。 Kmail (GUI) -~~~~~~~~~~~ +*********** 一些開發者成功的使用它發送補丁。 -默認設置不爲HTML格式是合適的；不要啓用它。 +默認撰寫設置禁用HTML格式是合適的；不要啓用它。 + +當書寫一封郵件的時候，在選項下面不要選擇自動換行。唯一的缺點就是你在郵件中輸 +入的任何文本都不會被自動換行，因此你必須在發送補丁之前手動換行。最簡單的方法 +就是啓用自動換行來書寫郵件，然後把它保存爲草稿。一旦你在草稿中再次打開它，它 +已經全部自動換行了，那麼你的郵件雖然沒有選擇自動換行，但是還不會失去已有的自 +動換行。 -當書寫一封郵件的時候，在選項下面不要選擇自動換行。唯一的缺點就是你在郵件中輸入的任何文本 -都不會被自動換行，因此你必須在發送補丁之前手動換行。最簡單的方法就是啓用自動換行來書寫郵件， -然後把它保存爲草稿。一旦你在草稿中再次打開它，它已經全部自動換行了，那麼你的郵件雖然沒有 -選擇自動換行，但是還不會失去已有的自動換行。 +在郵件的底部，插入補丁之前，放上常用的補丁定界符：三個連字符(``---``)。 -在郵件的底部，插入補丁之前，放上常用的補丁定界符：三個連字號(---)。 +然後在 :menuselection:`信件` 菜單，選擇 :menuselection:`插入文本文件` ，接 +着選取你的補丁文件。還有一個額外的選項，你可以通過它配置你的創建新郵件工具欄， +加上 :menuselection:`插入文本文件` 圖標。 -然後在"Message"菜單條目，選擇插入文件，接著選取你的補丁文件。還有一個額外的選項，你可以 -通過它配置你的郵件建立工具欄菜單，還可以帶上"insert file"圖標。 +將編輯器窗口拉到足夠寬避免折行。對於KMail 1.13.5 (KDE 4.5.4)，它會在發送郵件 +時對編輯器窗口中顯示折行的地方自動換行。在選項菜單中取消自動換行仍不能解決。 +因此，如果你的補丁中有非常長的行，必須在發送之前把編輯器窗口拉得非常寬。 +參見：https://bugs.kde.org/show_bug.cgi?id=174034 -你可以安全地通過GPG標記附件，但是內嵌補丁最好不要使用GPG標記它們。作爲內嵌文本的簽發補丁， -當從GPG中提取7位編碼時會使他們變的更加複雜。 +你可以安全地用GPG簽名附件，但是內嵌補丁最好不要使用GPG簽名它們。作爲內嵌文本 +插入的簽名補丁將使其難以從7-bit編碼中提取。 -如果你非要以附件的形式發送補丁，那麼就右鍵點擊附件，然後選中屬性，突出"Suggest automatic -display"，這樣內嵌附件更容易讓讀者看到。 +如果你非要以附件的形式發送補丁，那麼就右鍵點擊附件，然後選擇 +:menuselection:`屬性` ，打開 :menuselection:`建議自動顯示` ，使附件內聯更容 +易讓讀者看到。 -當你要保存將要發送的內嵌文本補丁，你可以從消息列表窗格選擇包含補丁的郵件，然後右擊選擇 -"save as"。你可以使用一個沒有更改的包含補丁的郵件，如果它是以正確的形式組成。當你正真在它 -自己的窗口之下察看，那時沒有選項可以保存郵件--已經有一個這樣的bug被匯報到了kmail的bugzilla -並且希望這將會被處理。郵件是以只針對某個用戶可讀寫的權限被保存的，所以如果你想把郵件複製到其他地方， -你不得不把他們的權限改爲組或者整體可讀。 +當你要保存將要發送的內嵌文本補丁，你可以從消息列表窗格選擇包含補丁的郵件，然 +後右鍵選擇 :menuselection:`另存爲` 。如果整個電子郵件的組成正確，您可直接將 +其作爲補丁使用。電子郵件以當前用戶可讀寫權限保存，因此您必須 ``chmod`` ，以 +使其在複製到別處時用戶組和其他人可讀。 Lotus Notes (GUI) -~~~~~~~~~~~~~~~~~ +***************** 不要使用它。 +IBM Verse (Web GUI) +******************* + +同上條。 + Mutt (TUI) -~~~~~~~~~~ +********** -很多Linux開發人員使用mutt客戶端，所以證明它肯定工作的非常漂亮。 +很多Linux開發人員使用mutt客戶端，這證明它肯定工作得非常漂亮。 -Mutt不自帶編輯器，所以不管你使用什麼編輯器都不應該帶有自動斷行。大多數編輯器都帶有 -一個"insert file"選項，它可以通過不改變文件內容的方式插入文件。 +Mutt不自帶編輯器，所以不管你使用什麼編輯器，不自動斷行就行。大多數編輯器都有 +:menuselection:`插入文件` 選項，它可以在不改變文件內容的情況下插入文件。 + +用 ``vim`` 作爲mutt的編輯器:: -'vim'作爲mutt的編輯器： set editor="vi" - 如果使用xclip，敲入以下命令 +如果使用xclip，敲入以下命令:: + :set paste - 按中鍵之前或者shift-insert或者使用 + +然後再按中鍵或者shift-insert或者使用:: + :r filename -如果想要把補丁作爲內嵌文本。 -(a)ttach工作的很好，不帶有"set paste"。 +把補丁插入爲內嵌文本。 +在未設置 ``set paste`` 時(a)ttach工作的很好。 你可以通過 ``git format-patch`` 生成補丁，然後用 Mutt發送它們:: - $ mutt -H 0001-some-bug-fix.patch + $ mutt -H 0001-some-bug-fix.patch 配置選項： + 它應該以默認設置的形式工作。 -然而，把"send_charset"設置爲"us-ascii::utf-8"也是一個不錯的主意。 +然而，把 ``send_charset`` 設置一下也是一個不錯的主意:: -Mutt 是高度可配置的。 這裡是個使用mutt通過 Gmail 發送的補丁的最小配置:: + set send_charset="us-ascii:utf-8" + +Mutt 是高度可配置的。 這裏是個使用mutt通過 Gmail 發送的補丁的最小配置:: # .muttrc # ================ IMAP ==================== @@ -181,72 +222,108 @@ Mutt 是高度可配置的。 這裡是個使用mutt通過 Gmail 發送的補丁 set from = "username@gmail.com" set use_from = yes -Mutt文檔含有更多信息: +Mutt文檔含有更多信息： - http://dev.mutt.org/trac/wiki/UseCases/Gmail + https://gitlab.com/muttmua/mutt/-/wikis/UseCases/Gmail - http://dev.mutt.org/doc/manual.html + http://www.mutt.org/doc/manual/ Pine (TUI) -~~~~~~~~~~ +********** Pine過去有一些空格刪減問題，但是這些現在應該都被修復了。 -如果可以，請使用alpine(pine的繼承者) +如果可以，請使用alpine（pine的繼承者）。 配置選項： -- 最近的版本需要消除流程文本 -- "no-strip-whitespace-before-send"選項也是需要的。 + +- 最近的版本需要 ``quell-flowed-text`` +- ``no-strip-whitespace-before-send`` 選項也是需要的。 Sylpheed (GUI) -~~~~~~~~~~~~~~ +************** - 內嵌文本可以很好的工作（或者使用附件）。 - 允許使用外部的編輯器。 -- 對於目錄較多時非常慢。 +- 收件箱較多時非常慢。 - 如果通過non-SSL連接，無法使用TLS SMTP授權。 -- 在組成窗口中有一個很有用的ruler bar。 -- 給地址本中添加地址就不會正確的了解顯示名。 +- 撰寫窗口的標尺很有用。 +- 將地址添加到通訊簿時無法正確理解顯示的名稱。 Thunderbird (GUI) -~~~~~~~~~~~~~~~~~ +***************** + +Thunderbird是Outlook的克隆版本，它很容易損壞文本，但也有一些方法強制修正。 + +在完成修改後（包括安裝擴展），您需要重新啓動Thunderbird。 + +- 允許使用外部編輯器： + + 使用Thunderbird發補丁最簡單的方法是使用擴展來打開您最喜歡的外部編輯器。 + + 下面是一些能夠做到這一點的擴展樣例。 + + - “External Editor Revived” + + https://github.com/Frederick888/external-editor-revived + + https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor-revived/ + + 它需要安裝“本地消息主機（native messaging host）”。 + 參見以下文檔: + https://github.com/Frederick888/external-editor-revived/wiki + + - “External Editor” + + https://github.com/exteditor/exteditor + + 下載並安裝此擴展，然後打開 :menuselection:`新建消息` 窗口, 用 + :menuselection:`查看-->工具欄-->自定義...` 給它增加一個按鈕，直接點擊此 + 按鈕即可使用外置編輯器。 + + 請注意，“External Editor”要求你的編輯器不能fork，換句話說，編輯器必須在 + 關閉前不返回。你可能需要傳遞額外的參數或修改編輯器設置。最值得注意的是， + 如果您使用的是gvim，那麼您必須將 :menuselection:`external editor` 設置的 + 編輯器字段設置爲 ``/usr/bin/gvim --nofork"`` （假設可執行文件在 + ``/usr/bin`` ），以傳遞 ``-f`` 參數。如果您正在使用其他編輯器，請閱讀其 + 手冊瞭解如何處理。 -默認情況下，thunderbird很容易損壞文本，但是還有一些方法可以強制它變得更好。 +若要修正內部編輯器，請執行以下操作： -- 在用戶帳號設置里，組成和尋址，不要選擇"Compose messages in HTML format"。 +- 修改你的Thunderbird設置，不要使用 ``format=flowed`` ！ + 回到主窗口，按照 + :menuselection:`主菜單-->首選項-->常規-->配置編輯器...` + 打開Thunderbird的配置編輯器。 -- 編輯你的Thunderbird配置設置來使它不要拆行使用：user_pref("mailnews.wraplength", 0); + - 將 ``mailnews.send_plaintext_flowed`` 設爲 ``false`` -- 編輯你的Thunderbird配置設置，使它不要使用"format=flowed"格式：user_pref("mailnews. - send_plaintext_flowed", false); + - 將 ``mailnews.wraplength`` 從 ``72`` 改爲 ``0`` -- 你需要使Thunderbird變爲預先格式方式： - 如果默認情況下你書寫的是HTML格式，那不是很難。僅僅從標題欄的下拉框中選擇"Preformat"格式。 - 如果默認情況下你書寫的是文本格式，你不得把它改爲HTML格式（僅僅作爲一次性的）來書寫新的消息， - 然後強制使它回到文本格式，否則它就會拆行。要實現它，在寫信的圖標上使用shift鍵來使它變爲HTML - 格式，然後標題欄的下拉框中選擇"Preformat"格式。 +- 不要寫HTML郵件！ + 回到主窗口，打開 + :menuselection:`主菜單-->賬戶設置-->你的@郵件.地址-->通訊錄/編寫&地址簿` ， + 關掉 ``以HTML格式編寫消息`` 。 -- 允許使用外部的編輯器： - 針對Thunderbird打補丁最簡單的方法就是使用一個"external editor"擴展，然後使用你最喜歡的 - $EDITOR來讀取或者合併補丁到文本中。要實現它，可以下載並且安裝這個擴展，然後添加一個使用它的 - 按鍵View->Toolbars->Customize...最後當你書寫信息的時候僅僅點擊它就可以了。 +- 只用純文本格式查看郵件！ + 回到主窗口， :menuselection:`主菜單-->查看-->消息體爲-->純文本` ！ TkRat (GUI) -~~~~~~~~~~~ +*********** 可以使用它。使用"Insert file..."或者外部的編輯器。 Gmail (Web GUI) -~~~~~~~~~~~~~~~ +*************** 不要使用它發送補丁。 -Gmail網頁客戶端自動地把制表符轉換爲空格。 +Gmail網頁客戶端自動地把製表符轉換爲空格。 -雖然制表符轉換爲空格問題可以被外部編輯器解決，同時它還會使用回車換行把每行拆分爲78個字符。 +雖然製表符轉換爲空格問題可以被外部編輯器解決，但它同時還會使用回車換行把每行 +拆分爲78個字符。 -另一個問題是Gmail還會把任何不是ASCII的字符的信息改爲base64編碼。它把東西變的像歐洲人的名字。 +另一個問題是Gmail還會把任何含有非ASCII的字符的消息改用base64編碼，如歐洲人的 +名字。 - ### diff --git a/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst b/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst index fbde3e26eda5..b9f6ab7b6666 100644 --- a/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst +++ b/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst @@ -4,19 +4,19 @@ :Original: :ref:`Documentation/process/embargoed-hardware-issues.rst <embargoed_hardware_issues>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res@email.cn> + Hu Haowen <src.res.211@gmail.com> -被限制的硬體問題 +被限制的硬件問題 ================ 範圍 ---- -導致安全問題的硬體問題與只影響Linux內核的純軟體錯誤是不同的安全錯誤類別。 +導致安全問題的硬件問題與隻影響Linux內核的純軟件錯誤是不同的安全錯誤類別。 -必須區別對待諸如熔毀(Meltdown)、Spectre、L1TF等硬體問題，因爲它們通常會影響 -所有作業系統（「OS」），因此需要在不同的OS供應商、發行版、硬體供應商和其他各方 -之間進行協調。對於某些問題，軟體緩解可能依賴於微碼或固件更新，這需要進一步的 +必須區別對待諸如熔燬(Meltdown)、Spectre、L1TF等硬件問題，因爲它們通常會影響 +所有操作系統（“OS”），因此需要在不同的OS供應商、發行版、硬件供應商和其他各方 +之間進行協調。對於某些問題，軟件緩解可能依賴於微碼或固件更新，這需要進一步的 協調。 .. _tw_Contact: @@ -24,9 +24,9 @@ 接觸 ---- -Linux內核硬體安全小組獨立於普通的Linux內核安全小組。 +Linux內核硬件安全小組獨立於普通的Linux內核安全小組。 -該小組只負責協調被限制的硬體安全問題。Linux內核中純軟體安全漏洞的報告不由該 +該小組只負責協調被限制的硬件安全問題。Linux內核中純軟件安全漏洞的報告不由該 小組處理，報告者將被引導至常規Linux內核安全小組(:ref:`Documentation/admin-guide/ <securitybugs>`)聯繫。 @@ -37,13 +37,13 @@ Linux內核硬體安全小組獨立於普通的Linux內核安全小組。 者的PGP密鑰或S/MIME證書籤名。該列表的PGP密鑰和S/MIME證書可從 https://www.kernel.org/.... 獲得。 -雖然硬體安全問題通常由受影響的硬體供應商處理，但我們歡迎發現潛在硬體缺陷的研究 +雖然硬件安全問題通常由受影響的硬件供應商處理，但我們歡迎發現潛在硬件缺陷的研究 人員或個人與我們聯繫。 -硬體安全官 +硬件安全官 ^^^^^^^^^^ -目前的硬體安全官小組: +目前的硬件安全官小組: - Linus Torvalds（Linux基金會院士） - Greg Kroah Hartman（Linux基金會院士） @@ -62,50 +62,50 @@ Linux基金會目前的IT基礎設施安全總監是 Konstantin Ryabitsev。 保密協議 -------- -Linux內核硬體安全小組不是正式的機構，因此無法簽訂任何保密協議。核心社區意識到 +Linux內核硬件安全小組不是正式的機構，因此無法簽訂任何保密協議。核心社區意識到 這些問題的敏感性，並提供了一份諒解備忘錄。 諒解備忘錄 ---------- -Linux內核社區深刻理解在不同作業系統供應商、發行商、硬體供應商和其他各方之間 -進行協調時，保持硬體安全問題處於限制狀態的要求。 +Linux內核社區深刻理解在不同操作系統供應商、發行商、硬件供應商和其他各方之間 +進行協調時，保持硬件安全問題處於限制狀態的要求。 -Linux內核社區在過去已經成功地處理了硬體安全問題，並且有必要的機制允許在限制 +Linux內核社區在過去已經成功地處理了硬件安全問題，並且有必要的機制允許在限制 限制下進行符合社區的開發。 -Linux內核社區有一個專門的硬體安全小組負責初始聯繫，並監督在限制規則下處理 +Linux內核社區有一個專門的硬件安全小組負責初始聯繫，並監督在限制規則下處理 此類問題的過程。 -硬體安全小組確定開發人員（領域專家），他們將組成特定問題的初始響應小組。最初 +硬件安全小組確定開發人員（領域專家），他們將組成特定問題的初始響應小組。最初 的響應小組可以引入更多的開發人員（領域專家）以最佳的技術方式解決這個問題。 所有相關開發商承諾遵守限制規定，並對收到的信息保密。違反承諾將導致立即從當前 -問題中排除，並從所有相關郵件列表中刪除。此外，硬體安全小組還將把違反者排除在 +問題中排除，並從所有相關郵件列表中刪除。此外，硬件安全小組還將把違反者排除在 未來的問題之外。這一後果的影響在我們社區是一種非常有效的威懾。如果發生違規 -情況，硬體安全小組將立即通知相關方。如果您或任何人發現潛在的違規行爲，請立即 -向硬體安全人員報告。 +情況，硬件安全小組將立即通知相關方。如果您或任何人發現潛在的違規行爲，請立即 +向硬件安全人員報告。 流程 ^^^^ -由於Linux內核開發的全球分布式特性，面對面的會議幾乎不可能解決硬體安全問題。 +由於Linux內核開發的全球分佈式特性，面對面的會議幾乎不可能解決硬件安全問題。 由於時區和其他因素，電話會議很難協調，只能在絕對必要時使用。加密電子郵件已被 證明是解決此類問題的最有效和最安全的通信方法。 開始披露 """""""" -披露內容首先通過電子郵件聯繫Linux內核硬體安全小組。此初始聯繫人應包含問題的 -描述和任何已知受影響硬體的列表。如果您的組織製造或分發受影響的硬體，我們建議 -您也考慮哪些其他硬體可能會受到影響。 +披露內容首先通過電子郵件聯繫Linux內核硬件安全小組。此初始聯繫人應包含問題的 +描述和任何已知受影響硬件的列表。如果您的組織製造或分發受影響的硬件，我們建議 +您也考慮哪些其他硬件可能會受到影響。 -硬體安全小組將提供一個特定於事件的加密郵件列表，用於與報告者進行初步討論、 +硬件安全小組將提供一個特定於事件的加密郵件列表，用於與報告者進行初步討論、 進一步披露和協調。 -硬體安全小組將向披露方提供一份開發人員（領域專家）名單，在與開發人員確認他們 +硬件安全小組將向披露方提供一份開發人員（領域專家）名單，在與開發人員確認他們 將遵守本諒解備忘錄和文件化流程後，應首先告知開發人員有關該問題的信息。這些開發 -人員組成初始響應小組，並在初始接觸後負責處理問題。硬體安全小組支持響應小組， +人員組成初始響應小組，並在初始接觸後負責處理問題。硬件安全小組支持響應小組， 但不一定參與緩解開發過程。 雖然個別開發人員可能通過其僱主受到保密協議的保護，但他們不能以Linux內核開發 @@ -113,7 +113,7 @@ Linux內核社區有一個專門的硬體安全小組負責初始聯繫，並監 披露方應提供已經或應該被告知該問題的所有其他實體的聯繫人名單。這有幾個目的: - - 披露的實體列表允許跨行業通信，例如其他作業系統供應商、硬體供應商等。 + - 披露的實體列表允許跨行業通信，例如其他操作系統供應商、硬件供應商等。 - 可聯繫已披露的實體，指定應參與緩解措施開發的專家。 @@ -133,10 +133,10 @@ Linux內核社區有一個專門的硬體安全小組負責初始聯繫，並監 初始響應小組設置加密郵件列表，或在適當的情況下重新修改現有郵件列表。 -使用郵件列表接近於正常的Linux開發過程，並且在過去已經成功地用於爲各種硬體安全 +使用郵件列表接近於正常的Linux開發過程，並且在過去已經成功地用於爲各種硬件安全 問題開發緩解措施。 -郵件列表的操作方式與正常的Linux開發相同。發布、討論和審查修補程序，如果同意， +郵件列表的操作方式與正常的Linux開發相同。發佈、討論和審查修補程序，如果同意， 則應用於非公共git存儲庫，參與開發人員只能通過安全連接訪問該存儲庫。存儲庫包含 針對主線內核的主開發分支，並根據需要爲穩定的內核版本提供向後移植分支。 @@ -155,9 +155,9 @@ Linux內核社區有一個專門的硬體安全小組負責初始聯繫，並監 """""""" 有關各方將協商限制結束的日期和時間。此時，準備好的緩解措施集成到相關的內核樹中 -並發布。 +併發布。 -雖然我們理解硬體安全問題需要協調限制時間，但限制時間應限制在所有有關各方制定、 +雖然我們理解硬件安全問題需要協調限制時間，但限制時間應限制在所有有關各方制定、 測試和準備緩解措施所需的最短時間內。人爲地延長限制時間以滿足會議討論日期或其他 非技術原因，會給相關的開發人員和響應小組帶來了更多的工作和負擔，因爲補丁需要 保持最新，以便跟蹤正在進行的上游內核開發，這可能會造成衝突的更改。 @@ -165,7 +165,7 @@ Linux內核社區有一個專門的硬體安全小組負責初始聯繫，並監 CVE分配 """"""" -硬體安全小組和初始響應小組都不分配CVE，開發過程也不需要CVE。如果CVE是由披露方 +硬件安全小組和初始響應小組都不分配CVE，開發過程也不需要CVE。如果CVE是由披露方 提供的，則可用於文檔中。 流程專使 @@ -196,22 +196,22 @@ CVE分配 Google Kees Cook <keescook@chromium.org> ============= ======================================================== -如果要將您的組織添加到專使名單中，請與硬體安全小組聯繫。被提名的專使必須完全 +如果要將您的組織添加到專使名單中，請與硬件安全小組聯繫。被提名的專使必須完全 理解和支持我們的過程，並且在Linux內核社區中很容易聯繫。 加密郵件列表 ------------ 我們使用加密郵件列表進行通信。這些列表的工作原理是，發送到列表的電子郵件使用 -列表的PGP密鑰或列表的/MIME證書進行加密。郵件列表軟體對電子郵件進行解密，並 +列表的PGP密鑰或列表的/MIME證書進行加密。郵件列表軟件對電子郵件進行解密，並 使用訂閱者的PGP密鑰或S/MIME證書爲每個訂閱者分別對其進行重新加密。有關郵件列表 -軟體和用於確保列表安全和數據保護的設置的詳細信息，請訪問: +軟件和用於確保列表安全和數據保護的設置的詳細信息，請訪問: https://www.kernel.org/.... 關鍵點 ^^^^^^ -初次接觸見 :ref:`tw_Contact`. 對於特定於事件的郵件列表，密鑰和S/MIME證書通過 +初次接觸見 :ref:`zh_Contact`. 對於特定於事件的郵件列表，密鑰和S/MIME證書通過 特定列表發送的電子郵件傳遞給訂閱者。 訂閱事件特定列表 @@ -220,8 +220,8 @@ https://www.kernel.org/.... 訂閱由響應小組處理。希望參與通信的披露方將潛在訂戶的列表發送給響應組，以便 響應組可以驗證訂閱請求。 -每個訂戶都需要通過電子郵件向響應小組發送訂閱請求。電子郵件必須使用訂閱伺服器 -的PGP密鑰或S/MIME證書籤名。如果使用PGP密鑰，則必須從公鑰伺服器獲得該密鑰， +每個訂戶都需要通過電子郵件向響應小組發送訂閱請求。電子郵件必須使用訂閱服務器 +的PGP密鑰或S/MIME證書籤名。如果使用PGP密鑰，則必須從公鑰服務器獲得該密鑰， 並且理想情況下該密鑰連接到Linux內核的PGP信任網。另請參見: https://www.kernel.org/signature.html. diff --git a/Documentation/translations/zh_TW/process/howto.rst b/Documentation/translations/zh_TW/process/howto.rst index ea2f468d3e58..306f5b77b4b8 100644 --- a/Documentation/translations/zh_TW/process/howto.rst +++ b/Documentation/translations/zh_TW/process/howto.rst @@ -16,7 +16,7 @@ 鍾宇 TripleX Chung <xxx.phy@gmail.com> 陳琦 Maggie Chen <chenqi@beyondsoft.com> 王聰 Wang Cong <xiyou.wangcong@gmail.com> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> 如何參與Linux內核開發 ===================== diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst index c5c59b4fd595..6a0d98b2f9ee 100644 --- a/Documentation/translations/zh_TW/process/index.rst +++ b/Documentation/translations/zh_TW/process/index.rst @@ -9,15 +9,16 @@ :Original: :ref:`Documentation/process/index.rst <process_index>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res@email.cn> + Hu Haowen <src.res.211@gmail.com> .. _tw_process_index: +======================== 與Linux 內核社區一起工作 ======================== 你想成爲Linux內核開發人員嗎？歡迎之至！在學習許多關於內核的技術知識的同時， -了解我們社區的工作方式也很重要。閱讀這些文檔可以讓您以更輕鬆的、麻煩更少的 +瞭解我們社區的工作方式也很重要。閱讀這些文檔可以讓您以更輕鬆的、麻煩更少的 方式將更改合併到內核。 以下是每位開發人員都應閱讀的基本指南： @@ -49,7 +50,7 @@ management-style embargoed-hardware-issues -這些是一些總體性技術指南，由於不大好分類而放在這裡： +這些是一些總體性技術指南，由於不大好分類而放在這裏： .. toctree:: :maxdepth: 1 diff --git a/Documentation/translations/zh_TW/process/kernel-driver-statement.rst b/Documentation/translations/zh_TW/process/kernel-driver-statement.rst index 8f225379b12c..e967089d2e1f 100644 --- a/Documentation/translations/zh_TW/process/kernel-driver-statement.rst +++ b/Documentation/translations/zh_TW/process/kernel-driver-statement.rst @@ -1,12 +1,12 @@ .. SPDX-License-Identifier: GPL-2.0 -.. _zh_process_statement_driver: +.. _tw_process_statement_driver: .. include:: ../disclaimer-zh_TW.rst :Original: :ref:`Documentation/process/kernel-driver-statement.rst <process_statement_driver>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res@email.cn> + Hu Haowen <src.res.211@gmail.com> 內核驅動聲明 ------------ diff --git a/Documentation/translations/zh_TW/process/kernel-enforcement-statement.rst b/Documentation/translations/zh_TW/process/kernel-enforcement-statement.rst index 99e21d22800d..2861f4a15721 100644 --- a/Documentation/translations/zh_TW/process/kernel-enforcement-statement.rst +++ b/Documentation/translations/zh_TW/process/kernel-enforcement-statement.rst @@ -6,7 +6,7 @@ :Original: :ref:`Documentation/process/kernel-enforcement-statement.rst <process_statement_kernel>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res@email.cn> + Hu Haowen <src.res.211@gmail.com> Linux 內核執行聲明 ------------------ diff --git a/Documentation/translations/zh_TW/process/license-rules.rst b/Documentation/translations/zh_TW/process/license-rules.rst index ad2b80f97123..2c43bcf2ac79 100644 --- a/Documentation/translations/zh_TW/process/license-rules.rst +++ b/Documentation/translations/zh_TW/process/license-rules.rst @@ -1,12 +1,10 @@ .. SPDX-License-Identifier: GPL-2.0 -.. SPDX-License-Identifier: GPL-2.0 - .. include:: ../disclaimer-zh_TW.rst :Original: :ref:`Documentation/process/license-rules.rst <kernel_licensing>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res@email.cn> + Hu Haowen <src.res.211@gmail.com> .. _tw_kernel_licensing: @@ -17,10 +15,10 @@ Linux內核根據LICENSES/preferred/GPL-2.0中提供的GNU通用公共許可證 （GPL-2.0）的條款提供，並在LICENSES/exceptions/Linux-syscall-note中顯式 描述了例外的系統調用，如COPYING文件中所述。 -此文檔文件提供了如何對每個源文件進行注釋以使其許可證清晰明確的說明。 +此文檔文件提供瞭如何對每個源文件進行註釋以使其許可證清晰明確的說明。 它不會取代內核的許可證。 -內核原始碼作爲一個整體適用於COPYING文件中描述的許可證，但是單個源文件可以 +內核源代碼作爲一個整體適用於COPYING文件中描述的許可證，但是單個源文件可以 具有不同的與GPL-20兼容的許可證:: GPL-1.0+ : GNU通用公共許可證v1.0或更高版本 @@ -34,18 +32,18 @@ Linux內核根據LICENSES/preferred/GPL-2.0中提供的GNU通用公共許可證 MIT等許可。 用戶空間API（UAPI）頭文件描述了用戶空間程序與內核的接口，這是一種特殊情況。 -根據內核COPYING文件中的注釋，syscall接口是一個明確的邊界，它不會將GPL要求 -擴展到任何使用它與內核通信的軟體。由於UAPI頭文件必須包含在創建在Linux內核 +根據內核COPYING文件中的註釋，syscall接口是一個明確的邊界，它不會將GPL要求 +擴展到任何使用它與內核通信的軟件。由於UAPI頭文件必須包含在創建在Linux內核 上運行的可執行文件的任何源文件中，因此此例外必須記錄在特別的許可證表述中。 -表達源文件許可證的常用方法是將匹配的樣板文本添加到文件的頂部注釋中。由於 -格式，拼寫錯誤等，這些「樣板」很難通過那些在上下文中使用的驗證許可證合規性 +表達源文件許可證的常用方法是將匹配的樣板文本添加到文件的頂部註釋中。由於 +格式，拼寫錯誤等，這些“樣板”很難通過那些在上下文中使用的驗證許可證合規性 的工具。 -樣板文本的替代方法是在每個源文件中使用軟體包數據交換（SPDX）許可證標識符。 +樣板文本的替代方法是在每個源文件中使用軟件包數據交換（SPDX）許可證標識符。 SPDX許可證標識符是機器可解析的，並且是用於提供文件內容的許可證的精確縮寫。 SPDX許可證標識符由Linux 基金會的SPDX 工作組管理，並得到了整個行業，工具 -供應商和法律團隊的合作夥伴的一致同意。有關詳細信息，請參閱 +供應商和法律團隊的合作伙伴的一致同意。有關詳細信息，請參閱 https://spdx.org/ Linux內核需要所有源文件中的精確SPDX標識符。內核中使用的有效標識符在 @@ -58,7 +56,7 @@ https://spdx.org/licenses/ 上的官方SPDX許可證列表中檢索，並附帶 1.安置: - 內核文件中的SPDX許可證標識符應添加到可包含注釋的文件中的第一行。對於大多 + 內核文件中的SPDX許可證標識符應添加到可包含註釋的文件中的第一行。對於大多 數文件，這是第一行，除了那些在第一行中需要'#!PATH_TO_INTERPRETER'的腳本。 對於這些腳本，SPDX標識符進入第二行。 @@ -66,7 +64,7 @@ https://spdx.org/licenses/ 上的官方SPDX許可證列表中檢索，並附帶 2. 風格: - SPDX許可證標識符以注釋的形式添加。注釋樣式取決於文件類型:: + SPDX許可證標識符以註釋的形式添加。註釋樣式取決於文件類型:: C source: // SPDX-License-Identifier: <SPDX License Expression> C header: /* SPDX-License-Identifier: <SPDX License Expression> */ @@ -75,20 +73,20 @@ https://spdx.org/licenses/ 上的官方SPDX許可證列表中檢索，並附帶 .rst: .. SPDX-License-Identifier: <SPDX License Expression> .dts{i}: // SPDX-License-Identifier: <SPDX License Expression> - 如果特定工具無法處理標準注釋樣式，則應使用工具接受的相應注釋機制。這是在 - C 頭文件中使用「/\*\*/」樣式注釋的原因。過去在使用生成的.lds文件中觀察到 - 構建被破壞，其中'ld'無法解析C++注釋。現在已經解決了這個問題，但仍然有較 - 舊的彙編程序工具無法處理C++樣式的注釋。 + 如果特定工具無法處理標準註釋樣式，則應使用工具接受的相應註釋機制。這是在 + C 頭文件中使用“/\*\*/”樣式註釋的原因。過去在使用生成的.lds文件中觀察到 + 構建被破壞，其中'ld'無法解析C++註釋。現在已經解決了這個問題，但仍然有較 + 舊的彙編程序工具無法處理C++樣式的註釋。 | 3. 句法: <SPDX許可證表達式>是SPDX許可證列表中的SPDX短格式許可證標識符，或者在許可 - 證例外適用時由「WITH」分隔的兩個SPDX短格式許可證標識符的組合。當應用多個許 - 可證時，表達式由分隔子表達式的關鍵字「AND」，「OR」組成，並由「（」，「）」包圍。 + 證例外適用時由“WITH”分隔的兩個SPDX短格式許可證標識符的組合。當應用多個許 + 可證時，表達式由分隔子表達式的關鍵字“AND”，“OR”組成，並由“（”，“）”包圍。 - 帶有「或更高」選項的[L]GPL等許可證的許可證標識符通過使用「+」來表示「或更高」 + 帶有“或更高”選項的[L]GPL等許可證的許可證標識符通過使用“+”來表示“或更高” 選項來構建。:: // SPDX-License-Identifier: GPL-2.0+ @@ -230,7 +228,7 @@ https://spdx.org/licenses/ 上的官方SPDX許可證列表中檢索，並附帶 元標籤: - 「其他」許可證的元標籤要求與 `優先許可`_ 的要求相同。 + “其他”許可證的元標籤要求與 `優先許可`_ 的要求相同。 文件格式示例:: @@ -267,8 +265,8 @@ https://spdx.org/licenses/ 上的官方SPDX許可證列表中檢索，並附帶 LICENSES/exceptions/GCC-exception-2.0 - 包含GCC'連結例外'，它允許獨立於其許可證的任何二進位文件與標記有此例外的 - 文件的編譯版本連結。這是從GPL不兼容原始碼創建可運行的可執行文件所必需的。 + 包含GCC'鏈接例外'，它允許獨立於其許可證的任何二進制文件與標記有此例外的 + 文件的編譯版本鏈接。這是從GPL不兼容源代碼創建可運行的可執行文件所必需的。 _`例外元標記`: @@ -333,11 +331,11 @@ https://spdx.org/licenses/ 上的官方SPDX許可證列表中檢索，並附帶 _`模塊許可` ----------------- - 可加載內核模塊還需要MODULE_LICENSE（）標記。此標記既不替代正確的原始碼 + 可加載內核模塊還需要MODULE_LICENSE（）標記。此標記既不替代正確的源代碼 許可證信息（SPDX-License-Identifier），也不以任何方式表示或確定提供模塊 - 原始碼的確切許可證。 + 源代碼的確切許可證。 - 此標記的唯一目的是提供足夠的信息，該模塊是否是自由軟體或者是內核模塊加 + 此標記的唯一目的是提供足夠的信息，該模塊是否是自由軟件或者是內核模塊加 載器和用戶空間工具的專有模塊。 MODULE_LICENSE（）的有效許可證字符串是: @@ -365,9 +363,9 @@ _`模塊許可` 只能通過相應的源文件中的許可證信息來確定。 "Proprietary" 該模塊屬於專有許可。此字符串僅用於專有的第三 - 方模塊，不能用於在內核樹中具有原始碼的模塊。 - 以這種方式標記的模塊在加載時會使用'P'標記汙 - 染內核，並且內核模塊加載器拒絕將這些模塊連結 + 方模塊，不能用於在內核樹中具有源代碼的模塊。 + 以這種方式標記的模塊在加載時會使用'P'標記污 + 染內核，並且內核模塊加載器拒絕將這些模塊鏈接 到使用EXPORT_SYMBOL_GPL（）導出的符號。 ============================= ============================================= diff --git a/Documentation/translations/zh_TW/process/magic-number.rst b/Documentation/translations/zh_TW/process/magic-number.rst index c9e3db12c3f9..5657d5cd18d4 100644 --- a/Documentation/translations/zh_TW/process/magic-number.rst +++ b/Documentation/translations/zh_TW/process/magic-number.rst @@ -12,7 +12,7 @@ 中文版維護者： 賈威威 Jia Wei Wei <harryxiyou@gmail.com> 中文版翻譯者： 賈威威 Jia Wei Wei <harryxiyou@gmail.com> 中文版校譯者： 賈威威 Jia Wei Wei <harryxiyou@gmail.com> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> Linux 魔術數 ============ diff --git a/Documentation/translations/zh_TW/process/management-style.rst b/Documentation/translations/zh_TW/process/management-style.rst index dce248470063..f3913e3c159d 100644 --- a/Documentation/translations/zh_TW/process/management-style.rst +++ b/Documentation/translations/zh_TW/process/management-style.rst @@ -4,7 +4,7 @@ :Original: :ref:`Documentation/process/management-style.rst <managementstyle>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res@email.cn> + Hu Haowen <src.res.211@gmail.com> .. _tw_managementstyle: @@ -16,20 +16,20 @@ Linux內核管理風格 主要是爲了避免反覆回答 [#cnf1]_ 相同（或類似）的問題。 管理風格是非常個人化的，比簡單的編碼風格規則更難以量化，因此本文檔可能與實 -際情況有關，也可能與實際情況無關。起初它是一個玩笑，但這並不意味著它可能不 +際情況有關，也可能與實際情況無關。起初它是一個玩笑，但這並不意味着它可能不 是真的。你得自己決定。 -順便說一句，在談到「核心管理者」時，主要是技術負責人，而不是在公司內部進行傳 -統管理的人。如果你簽署了採購訂單或者對你的團隊的預算有任何了解，你幾乎肯定 +順便說一句，在談到“核心管理者”時，主要是技術負責人，而不是在公司內部進行傳 +統管理的人。如果你簽署了採購訂單或者對你的團隊的預算有任何瞭解，你幾乎肯定 不是一個核心管理者。這些建議可能適用於您，也可能不適用於您。 -首先，我建議你購買「高效人的七個習慣」，而不是閱讀它。燒了它，這是一個偉大的 +首先，我建議你購買“高效人的七個習慣”，而不是閱讀它。燒了它，這是一個偉大的 象徵性姿態。 .. [#cnf1] 本文件並不是通過回答問題，而是通過讓提問者痛苦地明白，我們不知道 答案是什麼。 -不管怎樣，這裡是： +不管怎樣，這裏是： .. _tw_decisions: @@ -39,14 +39,14 @@ Linux內核管理風格 每個人都認爲管理者做決定，而且決策很重要。決定越大越痛苦，管理者就必須越高級。 這很明顯，但事實並非如此。 -遊戲的名字是 **避免** 做出決定。尤其是，如果有人告訴你「選擇（a）或（b）， -我們真的需要你來做決定」，你就是陷入麻煩的管理者。你管理的人比你更了解細節， +最重要的是 **避免** 做出決定。尤其是，如果有人告訴你“選擇（a）或（b）， +我們真的需要你來做決定”，你就是陷入麻煩的管理者。你管理的人比你更瞭解細節， 所以如果他們來找你做技術決策，你完蛋了。你顯然沒有能力爲他們做這個決定。 -（推論：如果你管理的人不比你更了解細節，你也會被搞砸，儘管原因完全不同。 +（推論：如果你管理的人不比你更瞭解細節，你也會被搞砸，儘管原因完全不同。 也就是說，你的工作是錯的，他們應該管理你的才智） -所以遊戲的名字是 **避免** 做出決定，至少是那些大而痛苦的決定。做一些小的 +所以最重要的是 **避免** 做出決定，至少是那些大而痛苦的決定。做一些小的 和非結果性的決定是很好的，並且使您看起來好像知道自己在做什麼，所以內核管理者 需要做的是將那些大的和痛苦的決定變成那些沒有人真正關心的小事情。 @@ -61,7 +61,7 @@ Linux內核管理風格 逃離的角落。走投無路的老鼠可能很危險——走投無路的管理者真可憐。 事實證明，由於沒有人會愚蠢到讓內核管理者承擔巨大的財政責任，所以通常很容易 -回溯。既然你不可能浪費掉你無法償還的巨額資金，你唯一可以回溯的就是技術決策， +回溯。既然你不可能浪費掉你無法償還的鉅額資金，你唯一可以回溯的就是技術決策， 而回溯很容易：只要告訴大家你是個不稱職的傻瓜，說對不起，然後撤銷你去年讓別 人所做的毫無價值的工作。突然間，你一年前做的決定不在是一個重大的決定，因爲 它很容易被推翻。 @@ -72,7 +72,7 @@ Linux內核管理風格 確實很難。 - 如果有人告訴你，你去年所做的工作終究是不值得的，那麼對那些可憐的低級工 程師來說也是很困難的，雖然實際的 **工作** 很容易刪除，但你可能已經不可 - 挽回地失去了工程師的信任。記住：「不可撤銷」是我們一開始就試圖避免的， + 挽回地失去了工程師的信任。記住：“不可撤銷”是我們一開始就試圖避免的， 而你的決定終究是一個重大的決定。 令人欣慰的是，這兩個原因都可以通過預先承認你沒有任何線索，提前告訴人們你的 @@ -80,19 +80,19 @@ Linux內核管理風格 的權利，並讓人們 **意識** 到這一點。當你 **還沒有** 做過真正愚蠢的事情的時 候，承認自己是愚蠢的要容易得多。 -然後，當它真的被證明是愚蠢的時候，人們就轉動他們的眼珠說「哎呀，下次不要了」。 +然後，當它真的被證明是愚蠢的時候，人們就轉動他們的眼珠說“哎呀，下次不要了”。 這種對不稱職的先發制人的承認，也可能使真正做這項工作的人也會三思是否值得做。 畢竟，如果他們不確定這是否是一個好主意，你肯定不應該通過向他們保證他們所做 的工作將會進入（內核）鼓勵他們。在他們開始一項巨大的努力之前，至少讓他們三 思而後行。 -記住：他們最好比你更了解細節，而且他們通常認爲他們對每件事都有答案。作爲一 +記住：他們最好比你更瞭解細節，而且他們通常認爲他們對每件事都有答案。作爲一 個管理者，你能做的最好的事情不是灌輸自信，而是對他們所做的事情進行健康的批 判性思考。 -順便說一句，另一種避免做出決定的方法是看起來很可憐的抱怨 「我們不能兩者兼 -得嗎？」 相信我，它是有效的。如果不清楚哪種方法更好，他們最終會弄清楚的。 +順便說一句，另一種避免做出決定的方法是看起來很可憐的抱怨 “我們不能兩者兼 +得嗎？” 相信我，它是有效的。如果不清楚哪種方法更好，他們最終會弄清楚的。 最終的答案可能是兩個團隊都會因爲這種情況而感到沮喪，以至於他們放棄了。 這聽起來像是一個失敗，但這通常是一個跡象，表明兩個項目都有問題，而參與其中 @@ -102,7 +102,7 @@ Linux內核管理風格 2）人 ----- -大多數人都是白癡，做一名管理者意味著你必須處理好這件事，也許更重要的是, +大多數人都是白癡，做一名管理者意味着你必須處理好這件事，也許更重要的是, **他們** 必須處理好你。 事實證明，雖然很容易糾正技術錯誤，但不容易糾正人格障礙。你只能和他們的和 @@ -110,16 +110,16 @@ Linux內核管理風格 但是，爲了做好作爲內核管理者的準備，最好記住不要燒掉任何橋樑，不要轟炸任何 無辜的村民，也不要疏遠太多的內核開發人員。事實證明，疏遠人是相當容易的，而 -親近一個疏遠的人是很難的。因此，「疏遠」立即屬於「不可逆」的範疇，並根據 +親近一個疏遠的人是很難的。因此，“疏遠”立即屬於“不可逆”的範疇，並根據 :ref:`tw_decisions` 成爲絕不可以做的事情。 -這裡只有幾個簡單的規則： +這裏只有幾個簡單的規則： (1) 不要叫人笨蛋（至少不要在公共場合） (2) 學習如何在忘記規則(1)時道歉 -問題在於 #1 很容易去做，因爲你可以用數百萬種不同的方式說「你是一個笨蛋」 [#cnf2]_ -有時甚至沒有意識到，而且幾乎總是帶著一種白熱化的信念，認爲你是對的。 +問題在於 #1 很容易去做，因爲你可以用數百萬種不同的方式說“你是一個笨蛋” [#cnf2]_ +有時甚至沒有意識到，而且幾乎總是帶着一種白熱化的信念，認爲你是對的。 你越確信自己是對的（讓我們面對現實吧，你可以把幾乎所有人都稱爲壞人，而且你 經常是對的），事後道歉就越難。 @@ -127,12 +127,12 @@ Linux內核管理風格 要解決此問題，您實際上只有兩個選項： - 非常擅長道歉 - - 把「愛」均勻地散開，沒有人會真正感覺到自己被不公平地瞄準了。讓它有足夠的 + - 把“愛”均勻地散開，沒有人會真正感覺到自己被不公平地瞄準了。讓它有足夠的 創造性，他們甚至可能會覺得好笑。 選擇永遠保持禮貌是不存在的。沒有人會相信一個如此明顯地隱藏了他們真實性格的人。 -.. [#cnf2] 保羅·西蒙演唱了「離開愛人的50種方法」，因爲坦率地說，「告訴開發者 +.. [#cnf2] 保羅·西蒙演唱了“離開愛人的50種方法”，因爲坦率地說，“告訴開發者 他們是D*CKHEAD" 的100萬種方法都無法確認。但我確信他已經這麼想了。 3）人2 - 好人 @@ -148,8 +148,8 @@ Linux內核管理風格 特別是，他們能夠爲你做決定，這就是遊戲的全部內容。 所以當你發現一個比你聰明的人時，就順其自然吧。你的管理職責在很大程度上變成 -了「聽起來像是個好主意——去嘗試吧」，或者「聽起來不錯，但是XXX呢？」「。第二個版 -本尤其是一個很好的方法，要麼學習一些關於「XXX」的新東西，要麼通過指出一些聰明 +了“聽起來像是個好主意——去嘗試吧”，或者“聽起來不錯，但是XXX呢？”“。第二個版 +本尤其是一個很好的方法，要麼學習一些關於“XXX”的新東西，要麼通過指出一些聰明 人沒有想到的東西來顯得更具管理性。無論哪種情況，你都會贏。 要注意的一件事是認識到一個領域的偉大不一定會轉化爲其他領域。所以你可能會向 @@ -172,22 +172,22 @@ Linux內核管理風格 他們也可能是能夠解決問題的人。因爲，讓我們面對現實吧，肯定不是你。 承擔責任也是你首先成爲管理者的原因。這是讓人們信任你，讓你獲得潛在的榮耀的 -一部分，因爲你就是那個會說「我搞砸了」的人。如果你已經遵循了以前的規則，你現 +一部分，因爲你就是那個會說“我搞砸了”的人。如果你已經遵循了以前的規則，你現 在已經很擅長說了。 5）應避免的事情 --------------- -有一件事人們甚至比被稱爲「笨蛋」更討厭，那就是在一個神聖的聲音中被稱爲「笨蛋」。 +有一件事人們甚至比被稱爲“笨蛋”更討厭，那就是在一個神聖的聲音中被稱爲“笨蛋”。 第一個你可以道歉，第二個你不會真正得到機會。即使你做得很好，他們也可能不再 傾聽。 -我們都認爲自己比別人強，這意味著當別人裝腔作勢時，這會讓我們很惱火。你也許 +我們都認爲自己比別人強，這意味着當別人裝腔作勢時，這會讓我們很惱火。你也許 在道德和智力上比你周圍的每個人都優越，但不要試圖太明顯，除非你真的打算激怒 某人 [#cnf3]_ 同樣，不要對事情太客氣或太微妙。禮貌很容易落得落花流水，把問題隱藏起來， -正如他們所說，「在網際網路上，沒人能聽到你的含蓄。」用一個鈍器把這一點錘進去， +正如他們所說，“在互聯網上，沒人能聽到你的含蓄。”用一個鈍器把這一點錘進去， 因爲你不能真的依靠別人來獲得你的觀點。 一些幽默可以幫助緩和直率和道德化。過度到荒謬的地步，可以灌輸一個觀點，而不 @@ -203,8 +203,8 @@ Linux內核管理風格 既然你的主要責任似乎是爲別人的錯誤承擔責任，並且讓別人痛苦地明白你是不稱職 的，那麼顯而易見的問題之一就變成了爲什麼首先要這樣做。 -首先，雖然你可能會或可能不會聽到十幾歲女孩（或男孩，讓我們不要在這裡評判或 -性別歧視）敲你的更衣室門，你會得到一個巨大的個人成就感爲「負責」。別介意你真 +首先，雖然你可能會或可能不會聽到十幾歲女孩（或男孩，讓我們不要在這裏評判或 +性別歧視）敲你的更衣室門，你會得到一個巨大的個人成就感爲“負責”。別介意你真 的在領導別人，你要跟上別人，儘可能快地追趕他們。每個人都會認爲你是負責人。 如果你可以做到這個， 這是個偉大的工作！ diff --git a/Documentation/translations/zh_TW/process/programming-language.rst b/Documentation/translations/zh_TW/process/programming-language.rst index 144bdaf81a41..e33389676eed 100644 --- a/Documentation/translations/zh_TW/process/programming-language.rst +++ b/Documentation/translations/zh_TW/process/programming-language.rst @@ -4,7 +4,7 @@ :Original: :ref:`Documentation/process/programming-language.rst <programming_language>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res@email.cn> + Hu Haowen <src.res.211@gmail.com> .. _tw_programming_language: diff --git a/Documentation/translations/zh_TW/process/stable-api-nonsense.rst b/Documentation/translations/zh_TW/process/stable-api-nonsense.rst index 22caa5b8d422..6839d25bb22a 100644 --- a/Documentation/translations/zh_TW/process/stable-api-nonsense.rst +++ b/Documentation/translations/zh_TW/process/stable-api-nonsense.rst @@ -12,50 +12,50 @@ 中文版維護者： 鍾宇 TripleX Chung <xxx.phy@gmail.com> 中文版翻譯者： 鍾宇 TripleX Chung <xxx.phy@gmail.com> 中文版校譯者： 李陽 Li Yang <leoyang.li@nxp.com> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> Linux 內核驅動接口 ================== -寫作本文檔的目的，是爲了解釋爲什麼Linux既沒有二進位內核接口，也沒有穩定 -的內核接口。這裡所說的內核接口，是指內核里的接口，而不是內核和用戶空間 -的接口。內核到用戶空間的接口，是提供給應用程式使用的系統調用，系統調用 -在歷史上幾乎沒有過變化，將來也不會有變化。我有一些老應用程式是在0.9版本 -或者更早版本的內核上編譯的，在使用2.6版本內核的Linux發布上依然用得很好 -。用戶和應用程式作者可以將這個接口看成是穩定的。 +寫作本文檔的目的，是爲了解釋爲什麼Linux既沒有二進制內核接口，也沒有穩定 +的內核接口。這裏所說的內核接口，是指內核裏的接口，而不是內核和用戶空間 +的接口。內核到用戶空間的接口，是提供給應用程序使用的系統調用，系統調用 +在歷史上幾乎沒有過變化，將來也不會有變化。我有一些老應用程序是在0.9版本 +或者更早版本的內核上編譯的，在使用2.6版本內核的Linux發佈上依然用得很好 +。用戶和應用程序作者可以將這個接口看成是穩定的。 執行綱要 -------- 你也許以爲自己想要穩定的內核接口，但是你不清楚你要的實際上不是它。你需 -要的其實是穩定的驅動程序，而你只有將驅動程序放到公版內核的原始碼樹里， -才有可能達到這個目的。而且這樣做還有很多其它好處，正是因爲這些好處使得 -Linux能成爲強壯，穩定，成熟的作業系統，這也是你最開始選擇Linux的原因。 +要的其實是穩定的驅動程序，而你只有將驅動程序放到公版內核的源代碼樹裏， +纔有可能達到這個目的。而且這樣做還有很多其它好處，正是因爲這些好處使得 +Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選擇Linux的原因。 入門 ----- -只有那些寫驅動程序的「怪人」才會擔心內核接口的改變，對廣大用戶來說，既 +只有那些寫驅動程序的“怪人”纔會擔心內核接口的改變，對廣大用戶來說，既 看不到內核接口，也不需要去關心它。 首先，我不打算討論關於任何非GPL許可的內核驅動的法律問題，這些非GPL許可 -的驅動程序包括不公開原始碼，隱藏原始碼，二進位或者是用原始碼包裝，或者 -是其它任何形式的不能以GPL許可公開原始碼的驅動程序。如果有法律問題，請咨 -詢律師，我只是一個程式設計師，所以我只打算探討技術問題（不是小看法律問題， +的驅動程序包括不公開源代碼，隱藏源代碼，二進制或者是用源代碼包裝，或者 +是其它任何形式的不能以GPL許可公開源代碼的驅動程序。如果有法律問題，請諮 +詢律師，我只是一個程序員，所以我只打算探討技術問題（不是小看法律問題， 法律問題很實際，並且需要一直關注）。 -既然只談技術問題，我們就有了下面兩個主題：二進位內核接口和穩定的內核源 -代碼接口。這兩個問題是互相關聯的，讓我們先解決掉二進位接口的問題。 +既然只談技術問題，我們就有了下面兩個主題：二進制內核接口和穩定的內核源 +代碼接口。這兩個問題是互相關聯的，讓我們先解決掉二進制接口的問題。 -二進位內核接口 +二進制內核接口 -------------- -假如我們有一個穩定的內核原始碼接口，那麼自然而然的，我們就擁有了穩定的 -二進位接口，是這樣的嗎？錯。讓我們看看關於Linux內核的幾點事實： +假如我們有一個穩定的內核源代碼接口，那麼自然而然的，我們就擁有了穩定的 +二進制接口，是這樣的嗎？錯。讓我們看看關於Linux內核的幾點事實： - - 取決於所用的C編譯器的版本，不同的內核數據結構里的結構體的對齊方 + - 取決於所用的C編譯器的版本，不同的內核數據結構裏的結構體的對齊方 式會有差別，代碼中不同函數的表現形式也不一樣（函數是不是被inline 編譯取決於編譯器行爲）。不同的函數的表現形式並不重要，但是數據 結構內部的對齊方式很關鍵。 @@ -69,33 +69,33 @@ Linux能成爲強壯，穩定，成熟的作業系統，這也是你最開始選 項。 - Linux可以在很多的不同體系結構的處理器上運行。在某個體系結構上編 - 譯好的二進位驅動程序，不可能在另外一個體系結構上正確的運行。 + 譯好的二進制驅動程序，不可能在另外一個體繫結構上正確的運行。 對於一個特定的內核，滿足這些條件並不難，使用同一個C編譯器和同樣的內核配 -置選項來編譯驅動程序模塊就可以了。這對於給一個特定Linux發布的特定版本提 -供驅動程序，是完全可以滿足需求的。但是如果你要給不同發布的不同版本都發 -布一個驅動程序，就需要在每個發布上用不同的內核設置參數都編譯一次內核， -這簡直跟噩夢一樣。而且還要注意到，每個Linux發布還提供不同的Linux內核， -這些內核都針對不同的硬體類型進行了優化（有很多種不同的處理器，還有不同 -的內核設置選項）。所以每發布一次驅動程序，都需要提供很多不同版本的內核 +置選項來編譯驅動程序模塊就可以了。這對於給一個特定Linux發佈的特定版本提 +供驅動程序，是完全可以滿足需求的。但是如果你要給不同發佈的不同版本都發 +佈一個驅動程序，就需要在每個發佈上用不同的內核設置參數都編譯一次內核， +這簡直跟噩夢一樣。而且還要注意到，每個Linux發佈還提供不同的Linux內核， +這些內核都針對不同的硬件類型進行了優化（有很多種不同的處理器，還有不同 +的內核設置選項）。所以每發佈一次驅動程序，都需要提供很多不同版本的內核 模塊。 -相信我，如果你真的要採取這種發布方式，一定會慢慢瘋掉，我很久以前就有過 +相信我，如果你真的要採取這種發佈方式，一定會慢慢瘋掉，我很久以前就有過 深刻的教訓... -穩定的內核原始碼接口 +穩定的內核源代碼接口 -------------------- -如果有人不將他的內核驅動程序，放入公版內核的原始碼樹，而又想讓驅動程序 +如果有人不將他的內核驅動程序，放入公版內核的源代碼樹，而又想讓驅動程序 一直保持在最新的內核中可用，那麼這個話題將會變得沒完沒了。 內核開發是持續而且快節奏的，從來都不會慢下來。內核開發人員在當前接口中 找到bug，或者找到更好的實現方式。一旦發現這些，他們就很快會去修改當前的 -接口。修改接口意味著，函數名可能會改變，結構體可能被擴充或者刪減，函數 +接口。修改接口意味着，函數名可能會改變，結構體可能被擴充或者刪減，函數 的參數也可能發生改變。一旦接口被修改，內核中使用這些接口的地方需要同時 修正，這樣才能保證所有的東西繼續工作。 -舉一個例子，內核的USB驅動程序接口在USB子系統的整個生命周期中，至少經歷 +舉一個例子，內核的USB驅動程序接口在USB子系統的整個生命週期中，至少經歷 了三次重寫。這些重寫解決以下問題： - 把數據流從同步模式改成非同步模式，這個改動減少了一些驅動程序的 @@ -104,11 +104,11 @@ Linux能成爲強壯，穩定，成熟的作業系統，這也是你最開始選 - 修改了USB核心代碼中爲USB驅動分配數據包內存的方式，所有的驅動都 需要提供更多的參數給USB核心，以修正了很多已經被記錄在案的死鎖。 -這和一些封閉原始碼的作業系統形成鮮明的對比，在那些作業系統上，不得不額 +這和一些封閉源代碼的操作系統形成鮮明的對比，在那些操作系統上，不得不額 外的維護舊的USB接口。這導致了一個可能性，新的開發者依然會不小心使用舊的 -接口，以不恰當的方式編寫代碼，進而影響到作業系統的穩定性。 +接口，以不恰當的方式編寫代碼，進而影響到操作系統的穩定性。 在上面的例子中，所有的開發者都同意這些重要的改動，在這樣的情況下修改代 -價很低。如果Linux保持一個穩定的內核原始碼接口，那麼就得創建一個新的接口 +價很低。如果Linux保持一個穩定的內核源代碼接口，那麼就得創建一個新的接口 ；舊的，有問題的接口必須一直維護，給Linux USB開發者帶來額外的工作。既然 所有的Linux USB驅動的作者都是利用自己的時間工作，那麼要求他們去做毫無意 義的免費額外工作，是不可能的。 @@ -126,28 +126,28 @@ Linux能成爲強壯，穩定，成熟的作業系統，這也是你最開始選 要做什麼 -------- -如果你寫了一個Linux內核驅動，但是它還不在Linux原始碼樹里，作爲一個開發 -者，你應該怎麼做？爲每個發布的每個版本提供一個二進位驅動，那簡直是一個 +如果你寫了一個Linux內核驅動，但是它還不在Linux源代碼樹裏，作爲一個開發 +者，你應該怎麼做？爲每個發佈的每個版本提供一個二進制驅動，那簡直是一個 噩夢，要跟上永遠處於變化之中的內核接口，也是一件辛苦活。 -很簡單，讓你的驅動進入內核原始碼樹（要記得我們在談論的是以GPL許可發行 +很簡單，讓你的驅動進入內核源代碼樹（要記得我們在談論的是以GPL許可發行 的驅動，如果你的代碼不符合GPL，那麼祝你好運，你只能自己解決這個問題了， -你這個吸血鬼<把Andrew和Linus對吸血鬼的定義連結到這裡>）。當你的代碼加入 -公版內核原始碼樹之後，如果一個內核接口改變，你的驅動會直接被修改接口的 +你這個吸血鬼<把Andrew和Linus對吸血鬼的定義鏈接到這裏>）。當你的代碼加入 +公版內核源代碼樹之後，如果一個內核接口改變，你的驅動會直接被修改接口的 那個人修改。保證你的驅動永遠都可以編譯通過，並且一直工作，你幾乎不需要 做什麼事情。 -把驅動放到內核原始碼樹里會有很多的好處： +把驅動放到內核源代碼樹裏會有很多的好處： - 驅動的質量會提升，而維護成本（對原始作者來說）會下降。 - 其他人會給驅動添加新特性。 - 其他人會找到驅動中的bug並修復。 - 其他人會在驅動中找到性能優化的機會。 - 當外部的接口的改變需要修改驅動程序的時候，其他人會修改驅動程序 - - 不需要聯繫任何發行商，這個驅動會自動的隨著所有的Linux發布一起發 + - 不需要聯繫任何發行商，這個驅動會自動的隨着所有的Linux發佈一起發 布。 -和別的作業系統相比，Linux爲更多不同的設備提供現成的驅動，而且能在更多不 -同體系結構的處理器上支持這些設備。這個經過考驗的開發模式，必然是錯不了 +和別的操作系統相比，Linux爲更多不同的設備提供現成的驅動，而且能在更多不 +同體繫結構的處理器上支持這些設備。這個經過考驗的開發模式，必然是錯不了 的 :) 感謝 diff --git a/Documentation/translations/zh_TW/process/stable-kernel-rules.rst b/Documentation/translations/zh_TW/process/stable-kernel-rules.rst index 9bb0d9b4f3ac..bd82a8ff3969 100644 --- a/Documentation/translations/zh_TW/process/stable-kernel-rules.rst +++ b/Documentation/translations/zh_TW/process/stable-kernel-rules.rst @@ -15,12 +15,12 @@ 中文版校譯者： - 李陽 Li Yang <leoyang.li@nxp.com> - Kangkai Yin <e12051@motorola.com> - - 胡皓文 Hu Haowen <src.res@email.cn> + - 胡皓文 Hu Haowen <src.res.211@gmail.com> -所有你想知道的事情 - 關於linux穩定版發布 +所有你想知道的事情 - 關於linux穩定版發佈 ======================================== -關於Linux 2.6穩定版發布，所有你想知道的事情。 +關於Linux 2.6穩定版發佈，所有你想知道的事情。 關於哪些類型的補丁可以被接收進入穩定版代碼樹，哪些不可以的規則： ---------------------------------------------------------------- @@ -28,39 +28,39 @@ - 必須是顯而易見的正確，並且經過測試的。 - 連同上下文，不能大於100行。 - 必須只修正一件事情。 - - 必須修正了一個給大家帶來麻煩的真正的bug（不是「這也許是一個問題...」 + - 必須修正了一個給大家帶來麻煩的真正的bug（不是“這也許是一個問題...” 那樣的東西）。 - 必須修正帶來如下後果的問題：編譯錯誤（對被標記爲CONFIG_BROKEN的例外）， - 內核崩潰，掛起，數據損壞，真正的安全問題，或者一些類似「哦，這不 - 好」的問題。簡短的說，就是一些致命的問題。 - - 沒有「理論上的競爭條件」，除非能給出競爭條件如何被利用的解釋。 - - 不能存在任何的「瑣碎的」修正（拼寫修正，去掉多餘空格之類的）。 + 內核崩潰，掛起，數據損壞，真正的安全問題，或者一些類似“哦，這不 + 好”的問題。簡短的說，就是一些致命的問題。 + - 沒有“理論上的競爭條件”，除非能給出競爭條件如何被利用的解釋。 + - 不能存在任何的“瑣碎的”修正（拼寫修正，去掉多餘空格之類的）。 - 必須被相關子系統的維護者接受。 - - 必須遵循Documentation/translations/zh_TW/process/submitting-patches.rst里的規則。 + - 必須遵循Documentation/translations/zh_CN/process/submitting-patches.rst裏的規則。 向穩定版代碼樹提交補丁的過程： ------------------------------ - 在確認了補丁符合以上的規則後，將補丁發送到stable@vger.kernel.org。 - - 如果補丁被接受到隊列里，發送者會收到一個ACK回復，如果沒有被接受，收 - 到的是NAK回復。回復需要幾天的時間，這取決於開發者的時間安排。 - - 被接受的補丁會被加到穩定版本隊列里，等待其他開發者的審查。 + - 如果補丁被接受到隊列裏，發送者會收到一個ACK回覆，如果沒有被接受，收 + 到的是NAK回覆。回覆需要幾天的時間，這取決於開發者的時間安排。 + - 被接受的補丁會被加到穩定版本隊列裏，等待其他開發者的審查。 - 安全方面的補丁不要發到這個列表，應該發送到security@kernel.org。 -審查周期： +審查週期： ---------- - - 當穩定版的維護者決定開始一個審查周期，補丁將被發送到審查委員會，以 + - 當穩定版的維護者決定開始一個審查週期，補丁將被髮送到審查委員會，以 及被補丁影響的領域的維護者（除非提交者就是該領域的維護者）並且抄送 到linux-kernel郵件列表。 - - 審查委員會有48小時的時間，用來決定給該補丁回復ACK還是NAK。 + - 審查委員會有48小時的時間，用來決定給該補丁回覆ACK還是NAK。 - 如果委員會中有成員拒絕這個補丁，或者linux-kernel列表上有人反對這個 補丁，並提出維護者和審查委員會之前沒有意識到的問題，補丁會從隊列中 丟棄。 - - 在審查周期結束的時候，那些得到ACK回應的補丁將會被加入到最新的穩定版 - 發布中，一個新的穩定版發布就此產生。 - - 安全性補丁將從內核安全小組那裡直接接收到穩定版代碼樹中，而不是通過 - 通常的審查周期。請聯繫內核安全小組以獲得關於這個過程的更多細節。 + - 在審查週期結束的時候，那些得到ACK回應的補丁將會被加入到最新的穩定版 + 發佈中，一個新的穩定版發佈就此產生。 + - 安全性補丁將從內核安全小組那裏直接接收到穩定版代碼樹中，而不是通過 + 通常的審查週期。請聯繫內核安全小組以獲得關於這個過程的更多細節。 審查委員會： ------------ diff --git a/Documentation/translations/zh_TW/process/submit-checklist.rst b/Documentation/translations/zh_TW/process/submit-checklist.rst index ff2f89cba83f..942962d1e2f4 100644 --- a/Documentation/translations/zh_TW/process/submit-checklist.rst +++ b/Documentation/translations/zh_TW/process/submit-checklist.rst @@ -2,108 +2,114 @@ .. include:: ../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/process/submit-checklist.rst <submitchecklist>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res@email.cn> +:Original: Documentation/process/submit-checklist.rst +:Translator: + - Alex Shi <alexs@kernel.org> + - Wu XiangCheng <bobwxc@email.cn> + - Hu Haowen <src.res.211@gmail.com> .. _tw_submitchecklist: -Linux內核補丁提交清單 -~~~~~~~~~~~~~~~~~~~~~ +Linux內核補丁提交檢查單 +~~~~~~~~~~~~~~~~~~~~~~~ 如果開發人員希望看到他們的內核補丁提交更快地被接受，那麼他們應該做一些基本 的事情。 -這些都是在 -:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` +這些都是在 Documentation/translations/zh_CN/process/submitting-patches.rst 和其他有關提交Linux內核補丁的文檔中提供的。 -1) 如果使用工具，則包括定義/聲明該工具的文件。不要依賴於其他頭文件拉入您使用 +1) 如果使用工具，則包括定義/聲明該工具的文件。不要依賴其他頭文件來引入您使用 的頭文件。 2) 乾淨的編譯： - a) 使用適用或修改的 ``CONFIG`` 選項 ``=y``、``=m`` 和 ``=n`` 。沒有GCC - 警告/錯誤，沒有連結器警告/錯誤。 + a) 使用合適的 ``CONFIG`` 選項 ``=y``、``=m`` 和 ``=n`` 。沒有 ``gcc`` + 警告/錯誤，沒有鏈接器警告/錯誤。 - b) 通過allnoconfig、allmodconfig + b) 通過 ``allnoconfig`` 、 ``allmodconfig`` c) 使用 ``O=builddir`` 時可以成功編譯 -3) 通過使用本地交叉編譯工具或其他一些構建場在多個CPU體系結構上構建。 + d) 任何 Doucmentation/ 下的變更都能成功構建且不引入新警告/錯誤。 + 用 ``make htmldocs`` 或 ``make pdfdocs`` 檢驗構建情況並修復問題。 + +3) 通過使用本地交叉編譯工具或其他一些構建設施在多個CPU體系結構上構建。 4) PPC64是一種很好的交叉編譯檢查體系結構，因爲它傾向於對64位的數使用無符號 長整型。 -5) 如下所述 :ref:`Documentation/translations/zh_TW/process/coding-style.rst <tw_codingstyle>`. - 檢查您的補丁是否爲常規樣式。在提交（ ``scripts/check patch.pl`` ）之前， - 使用補丁樣式檢查器檢查是否有輕微的衝突。您應該能夠處理您的補丁中存在的所有 +5) 按 Documentation/translations/zh_CN/process/coding-style.rst 所述檢查您的 + 補丁是否爲常規樣式。在提交之前使用補丁樣式檢查器 ``scripts/checkpatch.pl`` + 檢查是否有輕微的衝突。您應該能夠處理您的補丁中存在的所有 違規行爲。 -6) 任何新的或修改過的 ``CONFIG`` 選項都不會弄髒配置菜單，並默認爲關閉，除非 - 它們符合 ``Documentation/kbuild/kconfig-language.rst`` 中記錄的異常條件, - 菜單屬性：默認值. +6) 任何新的或修改過的 ``CONFIG`` 選項都不應搞亂配置菜單，並默認爲關閉，除非 + 它們符合 ``Documentation/kbuild/kconfig-language.rst`` 菜單屬性：默認值中 + 記錄的例外條件。 7) 所有新的 ``kconfig`` 選項都有幫助文本。 -8) 已仔細審查了相關的 ``Kconfig`` 組合。這很難用測試來糾正——腦力在這裡是有 +8) 已仔細審查了相關的 ``Kconfig`` 組合。這很難用測試來糾正——腦力在這裏是有 回報的。 -9) 用 sparse 檢查乾淨。 +9) 通過 sparse 清查。 + （參見 Documentation/translations/zh_CN/dev-tools/sparse.rst ） 10) 使用 ``make checkstack`` 和 ``make namespacecheck`` 並修復他們發現的任何 問題。 .. note:: - ``checkstack`` 並沒有明確指出問題，但是任何一個在堆棧上使用超過512 + ``checkstack`` 並不會明確指出問題，但是任何一個在堆棧上使用超過512 字節的函數都可以進行更改。 -11) 包括 :ref:`kernel-doc <kernel_doc>` 內核文檔以記錄全局內核API。（靜態函數 - 不需要，但也可以。）使用 ``make htmldocs`` 或 ``make pdfdocs`` 檢查 - :ref:`kernel-doc <kernel_doc>` 並修復任何問題。 +11) 包括 :ref:`kernel-doc <kernel_doc_zh>` 內核文檔以記錄全局內核API。（靜態 + 函數不需要，但也可以。）使用 ``make htmldocs`` 或 ``make pdfdocs`` 檢查 + :ref:`kernel-doc <kernel_doc_zh>` 並修復任何問題。 -12) 通過以下選項同時啓用的測試 ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, +12) 通過以下選項同時啓用的測試： ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, - ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` - -13) 已經過構建和運行時測試，包括有或沒有 ``CONFIG_SMP``, ``CONFIG_PREEMPT``. + ``CONFIG_PROVE_RCU`` 和 ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` 。 -14) 如果補丁程序影響IO/磁碟等：使用或不使用 ``CONFIG_LBDAF`` 進行測試。 +13) 在 ``CONFIG_SMP``, ``CONFIG_PREEMPT`` 開啓和關閉的情況下都進行構建和運行 + 時測試。 -15) 所有代碼路徑都已在啓用所有lockdep功能的情況下運行。 +14) 所有代碼路徑都已在啓用所有死鎖檢測（lockdep）功能的情況下運行。 -16) 所有新的/proc條目都記錄在 ``Documentation/`` +15) 所有新的 ``/proc`` 條目都記錄在 ``Documentation/`` -17) 所有新的內核引導參數都記錄在 +16) 所有新的內核引導參數都記錄在 Documentation/admin-guide/kernel-parameters.rst 中。 -18) 所有新的模塊參數都記錄在 ``MODULE_PARM_DESC()`` +17) 所有新的模塊參數都記錄在 ``MODULE_PARM_DESC()`` -19) 所有新的用戶空間接口都記錄在 ``Documentation/ABI/`` 中。有關詳細信息， +18) 所有新的用戶空間接口都記錄在 ``Documentation/ABI/`` 中。有關詳細信息， 請參閱 ``Documentation/ABI/README`` 。更改用戶空間接口的補丁應該抄送 linux-api@vger.kernel.org。 -20) 已通過至少注入slab和page分配失敗進行檢查。請參閱 ``Documentation/fault-injection/`` +19) 已通過至少注入slab和page分配失敗進行檢查。請參閱 ``Documentation/fault-injection/`` 。 如果新代碼是實質性的，那麼添加子系統特定的故障注入可能是合適的。 -21) 新添加的代碼已經用 ``gcc -W`` 編譯（使用 ``make EXTRA-CFLAGS=-W`` ）。這 - 將產生大量噪聲，但對於查找諸如「警告：有符號和無符號之間的比較」之類的錯誤 +20) 新添加的代碼已經用 ``gcc -W`` 編譯（使用 ``make EXTRA-CFLAGS=-W`` ）。這 + 將產生大量噪聲，但對於查找諸如“警告：有符號和無符號之間的比較”之類的錯誤 很有用。 -22) 在它被合併到-mm補丁集中之後進行測試，以確保它仍然與所有其他排隊的補丁以 +21) 在它被合併到-mm補丁集中之後進行測試，以確保它仍然與所有其他排隊的補丁以 及VM、VFS和其他子系統中的各種更改一起工作。 -23) 所有內存屏障例如 ``barrier()``, ``rmb()``, ``wmb()`` 都需要原始碼中的注 +22) 所有內存屏障（例如 ``barrier()``, ``rmb()``, ``wmb()`` ）都需要源代碼注 釋來解釋它們正在執行的操作及其原因的邏輯。 -24) 如果補丁添加了任何ioctl，那麼也要更新 ``Documentation/userspace-api/ioctl/ioctl-number.rst`` +23) 如果補丁添加了任何ioctl，那麼也要更新 + ``Documentation/userspace-api/ioctl/ioctl-number.rst`` 。 -25) 如果修改後的原始碼依賴或使用與以下 ``Kconfig`` 符號相關的任何內核API或 +24) 如果修改後的源代碼依賴或使用與以下 ``Kconfig`` 符號相關的任何內核API或 功能，則在禁用相關 ``Kconfig`` 符號和/或 ``=m`` （如果該選項可用）的情況 下測試以下多個構建[並非所有這些都同時存在，只是它們的各種/隨機組合]： - ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, - ``CONFIG_NET``, ``CONFIG_INET=n`` (但是後者伴隨 ``CONFIG_NET=y``). + ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, + ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, + ``CONFIG_NET``, ``CONFIG_INET=n`` （但是最後一個需要 ``CONFIG_NET=y`` ）。 diff --git a/Documentation/translations/zh_TW/process/submitting-patches.rst b/Documentation/translations/zh_TW/process/submitting-patches.rst index 3f77ef5d48a0..8272b3218b54 100644 --- a/Documentation/translations/zh_TW/process/submitting-patches.rst +++ b/Documentation/translations/zh_TW/process/submitting-patches.rst @@ -1,229 +1,199 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. _tw_submittingpatches: +.. SPDX-License-Identifier: GPL-2.0-or-later .. include:: ../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` +.. _tw_submittingpatches: -譯者:: +:Original: Documentation/process/submitting-patches.rst - 中文版維護者： 鍾宇 TripleX Chung <xxx.phy@gmail.com> - 中文版翻譯者： 鍾宇 TripleX Chung <xxx.phy@gmail.com> - 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> - 中文版校譯者： 李陽 Li Yang <leoyang.li@nxp.com> - 王聰 Wang Cong <xiyou.wangcong@gmail.com> - 胡皓文 Hu Haowen <src.res@email.cn> +:譯者: + - 鍾宇 TripleX Chung <xxx.phy@gmail.com> + - 時奎亮 Alex Shi <alexs@kernel.org> + - 吳想成 Wu XiangCheng <bobwxc@email.cn> +:校譯: + - 李陽 Li Yang <leoyang.li@nxp.com> + - 王聰 Wang Cong <xiyou.wangcong@gmail.com> + - 胡皓文 Hu Haowen <src.res.211@gmail.com> -如何讓你的改動進入內核 -====================== -對於想要將改動提交到 Linux 內核的個人或者公司來說，如果不熟悉「規矩」， -提交的流程會讓人畏懼。本文檔收集了一系列建議，這些建議可以大大的提高你 +提交補丁：如何讓你的改動進入內核 +================================ + +對於想要將改動提交到 Linux 內核的個人或者公司來說，如果不熟悉“規矩”， +提交的流程會讓人畏懼。本文檔包含了一系列建議，可以大大提高你 的改動被接受的機會. -以下文檔含有大量簡潔的建議， 具體請見： -:ref:`Documentation/process <development_process_main>` -同樣，:ref:`Documentation/translations/zh_TW/process/submit-checklist.rst <tw_submitchecklist>` -給出在提交代碼前需要檢查的項目的列表。 +本文檔以較爲簡潔的行文給出了大量建議。關於內核開發流程如何進行的詳細信息， +參見： Documentation/translations/zh_CN/process/development-process.rst 。 +Documentation/translations/zh_CN/process/submit-checklist.rst 給出了一系列 +提交補丁之前要檢查的事項。設備樹相關的補丁，請參閱 +Documentation/devicetree/bindings/submitting-patches.rst 。 -其中許多步驟描述了Git版本控制系統的默認行爲；如果您使用Git來準備補丁， -您將發現它爲您完成的大部分機械工作，儘管您仍然需要準備和記錄一組合理的 -補丁。一般來說，使用git將使您作爲內核開發人員的生活更輕鬆。 +本文檔假設您正在使用 ``git`` 準備你的補丁。如果您不熟悉 ``git`` ，最好學習 +如何使用它，這將使您作爲內核開發人員的生活變得更加輕鬆。 +部分子系統和維護人員的樹有一些關於其工作流程和要求的額外信息，請參閱 +Documentation/process/maintainer-handbooks.rst 。 -0) 獲取當前源碼樹 ------------------ +獲取當前源碼樹 +-------------- -如果您沒有一個可以使用當前內核原始碼的存儲庫，請使用git獲取一個。您將要 -從主線存儲庫開始，它可以通過以下方式獲取:: +如果您手頭沒有當前內核源代碼的存儲庫，請使用 ``git`` 獲取一份。您需要先獲取 +主線存儲庫，它可以通過以下命令拉取:: - git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git -但是，請注意，您可能不希望直接針對主線樹進行開發。大多數子系統維護人員運 +但是，請注意，您可能不想直接針對主線樹進行開發。大多數子系統維護人員運 行自己的樹，並希望看到針對這些樹準備的補丁。請參見MAINTAINERS文件中子系 -統的 **T:** 項以查找該樹，或者簡單地詢問維護者該樹是否未在其中列出。 - -仍然可以通過tarballs下載內核版本（如下一節所述），但這是進行內核開發的 -一種困難的方式。 - -1) "diff -up" -------------- - -使用 "diff -up" 或者 "diff -uprN" 來創建補丁。 - -所有內核的改動，都是以補丁的形式呈現的，補丁由 diff(1) 生成。創建補丁的 -時候，要確認它是以 "unified diff" 格式創建的，這種格式由 diff(1) 的 '-u' -參數生成。而且，請使用 '-p' 參數，那樣會顯示每個改動所在的C函數，使得 -產生的補丁容易讀得多。補丁應該基於內核原始碼樹的根目錄，而不是裡邊的任 -何子目錄。 - -爲一個單獨的文件創建補丁，一般來說這樣做就夠了:: - - SRCTREE=linux - MYFILE=drivers/net/mydriver.c - - cd $SRCTREE - cp $MYFILE $MYFILE.orig - vi $MYFILE # make your change - cd .. - diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch - -爲多個文件創建補丁，你可以解開一個沒有修改過的內核原始碼樹，然後和你自 -己的代碼樹之間做 diff 。例如:: - - MYSRC=/devel/linux - - tar xvfz linux-3.19.tar.gz - mv linux-3.19 linux-3.19-vanilla - diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ - linux-3.19-vanilla $MYSRC > /tmp/patch - -"dontdiff" 是內核在編譯的時候產生的文件的列表，列表中的文件在 diff(1) -產生的補丁里會被跳過。 - -確定你的補丁里沒有包含任何不屬於這次補丁提交的額外文件。記得在用diff(1) -生成補丁之後，審閱一次補丁，以確保準確。 - -如果你的改動很散亂，你應該研究一下如何將補丁分割成獨立的部分，將改動分 -割成一系列合乎邏輯的步驟。這樣更容易讓其他內核開發者審核，如果你想你的 -補丁被接受，這是很重要的。請參閱： -:ref:`tw_split_changes` - -如果你用 ``git`` , ``git rebase -i`` 可以幫助你這一點。如果你不用 ``git``, -``quilt`` <https://savannah.nongnu.org/projects/quilt> 另外一個流行的選擇。 +統的 **T:** 項以查找該樹，或者直接詢問維護者該樹是否未在其中列出。 .. _tw_describe_changes: -2) 描述你的改動 ---------------- +描述你的改動 +------------ 描述你的問題。無論您的補丁是一行錯誤修復還是5000行新功能，都必須有一個潛在 -的問題激勵您完成這項工作。讓審稿人相信有一個問題值得解決，讓他們讀完第一段 -是有意義的。 +的問題激勵您完成這項工作。說服審閱者相信有一個問題值得解決，讓他們讀完第一段 +後就能明白這一點。 描述用戶可見的影響。直接崩潰和鎖定是相當有說服力的，但並不是所有的錯誤都那麼 -明目張胆。即使在代碼審查期間發現了這個問題，也要描述一下您認爲它可能對用戶產 +明目張膽。即使在代碼審閱期間發現了這個問題，也要描述一下您認爲它可能對用戶產 生的影響。請記住，大多數Linux安裝運行的內核來自二級穩定樹或特定於供應商/產品 的樹，只從上游精選特定的補丁，因此請包含任何可以幫助您將更改定位到下游的內容： -觸發的場景、DMESG的摘錄、崩潰描述、性能回歸、延遲尖峯、鎖定等。 +觸發的場景、DMESG的摘錄、崩潰描述、性能迴歸、延遲尖峯、鎖定等。 -量化優化和權衡。如果您聲稱在性能、內存消耗、堆棧占用空間或二進位大小方面有所 -改進，請包括支持它們的數字。但也要描述不明顯的成本。優化通常不是免費的，而是 -在CPU、內存和可讀性之間進行權衡；或者，探索性的工作，在不同的工作負載之間進 +質量優化和權衡。如果您聲稱在性能、內存消耗、堆棧佔用空間或二進制大小方面有所 +改進，請包括支持它們的數據。但也要描述不明顯的成本。優化通常不是零成本的，而是 +在CPU、內存和可讀性之間進行權衡；或者，做探索性的工作，在不同的工作負載之間進 行權衡。請描述優化的預期缺點，以便審閱者可以權衡成本和收益。 -一旦問題建立起來，就要詳細地描述一下您實際在做什麼。對於審閱者來說，用簡單的 -英語描述代碼的變化是很重要的，以驗證代碼的行爲是否符合您的意願。 +提出問題之後，就要詳細地描述一下您實際在做的技術細節。對於審閱者來說，用簡練的 +英語描述代碼的變化是很重要的，以驗證代碼的行爲是否符合您的意圖。 -如果您將補丁描述寫在一個表單中，這個表單可以很容易地作爲「提交日誌」放入Linux -的原始碼管理系統git中，那麼維護人員將非常感謝您。見 :ref:`tw_explicit_in_reply_to`. +如果您將補丁描述寫成“標準格式”，可以很容易地作爲“提交日誌”放入Linux的源代 +碼管理系統 ``git`` 中，那麼維護人員將非常感謝您。 +參見 :ref:`zh_the_canonical_patch_format` 。 每個補丁只解決一個問題。如果你的描述開始變長，這就表明你可能需要拆分你的補丁。 -請見 :ref:`tw_split_changes` +請見 :ref:`zh_split_changes` 。 -提交或重新提交修補程序或修補程序系列時，請包括完整的修補程序說明和理由。不要 +提交或重新提交補丁或補丁系列時，請包括完整的補丁說明和理由。不要 只說這是補丁（系列）的第幾版。不要期望子系統維護人員引用更早的補丁版本或引用 URL來查找補丁描述並將其放入補丁中。也就是說，補丁（系列）及其描述應該是獨立的。 -這對維護人員和審查人員都有好處。一些評審者可能甚至沒有收到補丁的早期版本。 +這對維護人員和審閱者都有好處。一些審閱者可能甚至沒有收到補丁的早期版本。 -描述你在命令語氣中的變化，例如「make xyzzy do frotz」而不是「[這個補丁]make -xyzzy do frotz」或「[我]changed xyzzy to do frotz」，就好像你在命令代碼庫改變 +用祈使句描述你的變更，例如“make xyzzy do frotz”而不是“[This patch]make +xyzzy do frotz”或“[I]changed xyzzy to do frotz”，就好像你在命令代碼庫改變 它的行爲一樣。 -如果修補程序修復了一個記錄的bug條目，請按編號和URL引用該bug條目。如果補丁來 -自郵件列表討論，請給出郵件列表存檔的URL；使用帶有 ``Message-ID`` 的 -https://lore.kernel.org/ 重定向，以確保連結不會過時。 - -但是，在沒有外部資源的情況下，儘量讓你的解釋可理解。除了提供郵件列表存檔或 -bug的URL之外，還要總結需要提交補丁的相關討論要點。 - -如果您想要引用一個特定的提交，不要只引用提交的 SHA-1 ID。還請包括提交的一行 -摘要，以便於審閱者了解它是關於什麼的。例如:: +如果您想要引用一個特定的提交，不要只引用提交的SHA-1 ID。還請包括提交的一行 +摘要，以便於審閱者瞭解它是關於什麼的。例如:: Commit e21d2170f36602ae2708 ("video: remove unnecessary platform_set_drvdata()") removed the unnecessary platform_set_drvdata(), but left the variable "dev" unused, delete it. -您還應該確保至少使用前12位 SHA-1 ID. 內核存儲庫包含*許多*對象，使與較短的ID +您還應該確保至少使用前12位SHA-1 ID。內核存儲庫包含 *許多* 對象，使較短的ID 發生衝突的可能性很大。記住，即使現在不會與您的六個字符ID發生衝突，這種情況 -可能五年後改變。 +也可能在五年後改變。 + +如果該變更的相關討論或背景信息可以在網上查閱，請加上“Link:”標籤指向它。例如 +你的補丁修復了一個缺陷，需要添加一個帶有URL的標籤指向郵件列表存檔或缺陷跟蹤器 +的相關報告；如果該補丁是由一些早先郵件列表討論或網絡上的記錄引起的，請指向它。 + +當鏈接到郵件列表存檔時，請首選lore.kernel.org郵件存檔服務。用郵件中的 +``Message-ID`` 頭（去掉尖括號）可以創建鏈接URL。例如:: + + Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + +請檢查該鏈接以確保可用且指向正確的郵件。 + +不過，在沒有外部資源的情況下，也要儘量讓你的解釋可理解。除了提供郵件列表存檔或 +缺陷的URL之外，還要需要總結該補丁的相關討論要點。 -如果修補程序修復了特定提交中的錯誤，例如，使用 ``git bisct`` ，請使用帶有前 -12個字符SHA-1 ID 的"Fixes:"標記和單行摘要。爲了簡化不要將標記拆分爲多個， -行、標記不受分析腳本「75列換行」規則的限制。例如:: +如果補丁修復了特定提交中的錯誤，例如使用 ``git bisct`` 發現了一個問題，請使用 +帶有前12個字符SHA-1 ID的“Fixes:”標籤和單行摘要。爲了簡化解析腳本，不要將該 +標籤拆分爲多行，標籤不受“75列換行”規則的限制。例如:: - Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") -下列 ``git config`` 設置可以添加讓 ``git log``, ``git show`` 漂亮的顯示格式:: +下列 ``git config`` 設置可以讓 ``git log``, ``git show`` 增加上述風格的顯示格式:: [core] abbrev = 12 [pretty] fixes = Fixes: %h (\"%s\") +使用示例:: + + $ git log -1 --pretty=fixes 54a4f0239f2e + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + .. _tw_split_changes: -3) 拆分你的改動 ---------------- +拆分你的改動 +------------ -將每個邏輯更改分隔成一個單獨的補丁。 +將每個 **邏輯更改** 拆分成一個單獨的補丁。 -例如，如果你的改動里同時有bug修正和性能優化，那麼把這些改動拆分到兩個或 -者更多的補丁文件中。如果你的改動包含對API的修改，並且修改了驅動程序來適 -應這些新的API，那麼把這些修改分成兩個補丁。 +例如，如果你的改動裏同時有bug修正和性能優化，那麼把這些改動拆分到兩個或 +者更多的補丁文件中。如果你的改動包含對API的修改，並且增加了一個使用該新API +的驅動，那麼把這些修改分成兩個補丁。 另一方面，如果你將一個單獨的改動做成多個補丁文件，那麼將它們合併成一個 -單獨的補丁文件。這樣一個邏輯上單獨的改動只被包含在一個補丁文件里。 +單獨的補丁文件。這樣一個邏輯上單獨的改動只被包含在一個補丁文件裏。 -如果有一個補丁依賴另外一個補丁來完成它的改動，那沒問題。簡單的在你的補 -丁描述里指出「這個補丁依賴某補丁」就好了。 +需要記住的一點是，每個補丁的更改都應易於理解，以便審閱者驗證。每個補丁都應該 +對其價值進行闡述。 -在將您的更改劃分爲一系列補丁時，要特別注意確保內核在系列中的每個補丁之後 -都能正常構建和運行。使用 ``git bisect`` 來追蹤問題的開發者可能會在任何時 -候分割你的補丁系列；如果你在中間引入錯誤，他們不會感謝你。 +如果有一個補丁依賴另外一個補丁來完成它的改動，那沒問題。直接在你的補 +丁描述裏指出 **“這個補丁依賴某補丁”** 就好了。 -如果你不能將補丁濃縮成更少的文件，那麼每次大約發送出15個，然後等待審查 +在將您的更改劃分爲一系列補丁時，要特別注意確保內核在應用系列中的每個補丁之後 +都能正常構建和運行。使用 ``git bisect`` 來追蹤問題的開發者可能會在任何地方分 +割你的補丁系列；如果你在中間引入錯誤，他們不會感謝你。 + +如果你不能將補丁系列濃縮得更小，那麼每次大約發送出15個補丁，然後等待審閱 和集成。 -4) 檢查你的更改風格 -------------------- +檢查你的更改風格 +---------------- -檢查您的補丁是否存在基本樣式衝突，詳細信息可在 -:ref:`Documentation/translations/zh_TW/process/coding-style.rst <tw_codingstyle>` -中找到。如果不這樣做，只會浪費審稿人的時間，並且會導致你的補丁被拒絕，甚至 +檢查您的補丁是否違反了基本樣式規定，詳細信息參見 +Documentation/translations/zh_CN/process/coding-style.rst +中找到。如果不這樣做，只會浪費審閱者的時間，並且會導致你的補丁被拒絕，甚至 可能沒有被閱讀。 一個重要的例外是在將代碼從一個文件移動到另一個文件時——在這種情況下，您不應 該在移動代碼的同一個補丁中修改移動的代碼。這清楚地描述了移動代碼和您的更改 -的行爲。這大大有助於審查實際差異，並允許工具更好地跟蹤代碼本身的歷史。 +的行爲。這大大有助於審閱實際差異，並允許工具更好地跟蹤代碼本身的歷史。 在提交之前，使用補丁樣式檢查程序檢查補丁（scripts/check patch.pl）。不過， 請注意，樣式檢查程序應該被視爲一個指南，而不是作爲人類判斷的替代品。如果您 -的代碼看起來更好，但有違規行爲，那麼最好不要使用它。 +的代碼看起來更好，但有違規行爲，那麼最好別管它。 檢查者報告三個級別： - ERROR：很可能出錯的事情 - - WARNING：需要仔細審查的事項 + - WARNING：需要仔細審閱的事項 - CHECK：需要思考的事情 您應該能夠判斷您的補丁中存在的所有違規行爲。 -5) 選擇補丁收件人 ------------------ +選擇補丁收件人 +-------------- -您應該總是在任何補丁上複製相應的子系統維護人員，以獲得他們維護的代碼；查看 -維護人員文件和原始碼修訂歷史記錄，以了解這些維護人員是誰。腳本 -scripts/get_Maintainer.pl在這個步驟中非常有用。如果您找不到正在工作的子系統 +您應該總是知會任何補丁相應代碼的子系統維護人員；查看 +維護人員文件和源代碼修訂歷史記錄，以瞭解這些維護人員是誰。腳本 +scripts/get_maintainer.pl在這個步驟中非常有用。如果您找不到正在工作的子系統 的維護人員，那麼Andrew Morton（akpm@linux-foundation.org）將充當最後的維護 人員。 -您通常還應該選擇至少一個郵件列表來接收補丁集的。linux-kernel@vger.kernel.org -作爲最後一個解決辦法的列表，但是這個列表上的體積已經引起了許多開發人員的拒絕。 -在MAINTAINERS文件中查找子系統特定的列表；您的補丁可能會在那裡得到更多的關注。 +您通常還應該選擇至少一個郵件列表來接收補丁集的副本。linux-kernel@vger.kernel.org +是所有補丁的默認列表，但是這個列表的流量已經導致了許多開發人員不再看它。 +在MAINTAINERS文件中查找子系統特定的列表；您的補丁可能會在那裏得到更多的關注。 不過，請不要發送垃圾郵件到無關的列表。 許多與內核相關的列表託管在vger.kernel.org上；您可以在 @@ -232,188 +202,170 @@ http://vger.kernel.org/vger-lists.html 上找到它們的列表。不過，也 不要一次發送超過15個補丁到vger郵件列表！！！！ -Linus Torvalds 是決定改動能否進入 Linux 內核的最終裁決者。他的 e-mail -地址是 <torvalds@linux-foundation.org> 。他收到的 e-mail 很多，所以一般 -的說，最好別給他發 e-mail。 +Linus Torvalds是決定改動能否進入 Linux 內核的最終裁決者。他的郵件地址是 +torvalds@linux-foundation.org 。他收到的郵件很多，所以一般來說最好 **別** +給他發郵件。 -如果您有修復可利用安全漏洞的補丁，請將該補丁發送到 security@kernel.org。對於 -嚴重的bug，可以考慮短期暫停以允許分銷商向用戶發布補丁；在這種情況下，顯然不應 -將補丁發送到任何公共列表。 +如果您有修復可利用安全漏洞的補丁，請將該補丁發送到 security@kernel.org 。對於 +嚴重的bug，可以考慮短期禁令以允許分銷商（有時間）向用戶發佈補丁；在這種情況下， +顯然不應將補丁發送到任何公共列表。 +參見 Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。 -修復已發布內核中嚴重錯誤的補丁程序應該指向穩定版維護人員，方法是放這樣的一行:: +修復已發佈內核中嚴重錯誤的補丁程序應該抄送給穩定版維護人員，方法是把以下列行 +放進補丁的籤準區（注意，不是電子郵件收件人）:: - Cc: stable@vger.kernel.org + Cc: stable@vger.kernel.org -進入補丁的簽准區（注意，不是電子郵件收件人）。除了這個文件之外，您還應該閱讀 -:ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` +除了本文件之外，您還應該閱讀 +Documentation/translations/zh_CN/process/stable-kernel-rules.rst 。 -但是，請注意，一些子系統維護人員希望得出他們自己的結論，即哪些補丁應該被放到 -穩定的樹上。尤其是網絡維護人員，不希望看到單個開發人員在補丁中添加像上面這樣 -的行。 - -如果更改影響到用戶和內核接口，請向手冊頁維護人員（如維護人員文件中所列）發送 +如果更改影響到用戶側內核接口，請向手冊頁維護人員（如維護人員文件中所列）發送 手冊頁補丁，或至少發送更改通知，以便一些信息進入手冊頁。還應將用戶空間API -更改複製到 linux-api@vger.kernel.org。 +更改抄送到 linux-api@vger.kernel.org 。 + -6) 沒有 MIME 編碼，沒有連結，沒有壓縮，沒有附件，只有純文本 ------------------------------------------------------------ +不要MIME編碼，不要鏈接，不要壓縮，不要附件，只要純文本 +------------------------------------------------------ Linus 和其他的內核開發者需要閱讀和評論你提交的改動。對於內核開發者來說 -，可以「引用」你的改動很重要，使用一般的 e-mail 工具，他們就可以在你的 +，可以“引用”你的改動很重要，使用一般的郵件工具，他們就可以在你的 代碼的任何位置添加評論。 -因爲這個原因，所有的提交的補丁都是 e-mail 中「內嵌」的。 +因爲這個原因，所有的提交的補丁都是郵件中“內嵌”的。最簡單（和推薦）的方法就 +是使用 ``git send-email`` 。https://git-send-email.io 有 ``git send-email`` +的交互式教程。 + +如果你選擇不用 ``git send-email`` ： .. warning:: - 如果你使用剪切-粘貼你的補丁，小心你的編輯器的自動換行功能破壞你的補丁 -不要將補丁作爲 MIME 編碼的附件，不管是否壓縮。很多流行的 e-mail 軟體不 -是任何時候都將 MIME 編碼的附件當作純文本發送的，這會使得別人無法在你的 -代碼中加評論。另外，MIME 編碼的附件會讓 Linus 多花一點時間來處理，這就 -降低了你的改動被接受的可能性。 + 如果你使用剪切-粘貼你的補丁，小心你的編輯器的自動換行功能破壞你的補丁 -例外：如果你的郵遞員弄壞了補丁，那麼有人可能會要求你使用mime重新發送補丁 +不要將補丁作爲MIME編碼的附件，不管是否壓縮。很多流行的郵件軟件不 +是任何時候都將MIME編碼的附件當作純文本發送的，這會使得別人無法在你的 +代碼中加評論。另外，MIME編碼的附件會讓Linus多花一點時間來處理，這就 +降低了你的改動被接受的可能性。 -請參閱 :ref:`Documentation/translations/zh_TW/process/email-clients.rst <tw_email_clients>` -以獲取有關配置電子郵件客戶端以使其不受影響地發送修補程序的提示。 +例外：如果你的郵路損壞了補丁，那麼有人可能會要求你使用MIME重新發送補丁。 -7) e-mail 的大小 ----------------- +請參閱 Documentation/translations/zh_CN/process/email-clients.rst +以獲取有關配置電子郵件客戶端以使其不受影響地發送補丁的提示。 -大的改動對郵件列表不合適，對某些維護者也不合適。如果你的補丁，在不壓縮 -的情況下，超過了300kB，那麼你最好將補丁放在一個能通過 internet 訪問的服 -務器上，然後用指向你的補丁的 URL 替代。但是請注意，如果您的補丁超過了 -300kb，那麼它幾乎肯定需要被破壞。 +回覆審閱意見 +------------ -8）回複評審意見 ---------------- +你的補丁幾乎肯定會得到審閱者對補丁改進方法的評論（以回覆郵件的形式）。您必須 +對這些評論作出回應；讓補丁被忽略的一個好辦法就是忽略審閱者的意見。直接回復郵 +件來回應意見即可。不會導致代碼更改的意見或問題幾乎肯定會帶來註釋或變更日誌的 +改變，以便下一個審閱者更好地瞭解正在發生的事情。 -你的補丁幾乎肯定會得到評審者對補丁改進方法的評論。您必須對這些評論作出 -回應；讓補丁被忽略的一個好辦法就是忽略審閱者的意見。不會導致代碼更改的 -意見或問題幾乎肯定會帶來注釋或變更日誌的改變，以便下一個評審者更好地了解 -正在發生的事情。 +一定要告訴審閱者你在做什麼改變，並感謝他們的時間。代碼審閱是一個累人且耗時的 +過程，審閱者有時會變得暴躁。即使在這種情況下，也要禮貌地回應並解決他們指出的 +問題。當發送下一版時，在封面郵件或獨立補丁里加上 ``patch changelog`` 說明與 +前一版本的不同之處（參見 :ref:`zh_the_canonical_patch_format` ）。 -一定要告訴審稿人你在做什麼改變，並感謝他們的時間。代碼審查是一個累人且 -耗時的過程，審查人員有時會變得暴躁。即使在這種情況下，也要禮貌地回應並 -解決他們指出的問題。 +.. _tw_resend_reminders: -9）不要洩氣或不耐煩 -------------------- +不要泄氣或不耐煩 +---------------- -提交更改後，請耐心等待。審閱者是忙碌的人，可能無法立即訪問您的修補程序。 +提交更改後，請耐心等待。審閱者是大忙人，可能無法立即審閱您的補丁。 -曾幾何時，補丁曾在沒有評論的情況下消失在空白中，但開發過程比現在更加順利。 -您應該在一周左右的時間內收到評論；如果沒有收到評論，請確保您已將補丁發送 -到正確的位置。在重新提交或聯繫審閱者之前至少等待一周-在諸如合併窗口之類的 +曾幾何時，補丁曾在沒收到評論的情況下消失在虛空中，但現在開發過程應該更加順利了。 +您應該在一週左右的時間內收到評論；如果沒有收到評論，請確保您已將補丁發送 +到正確的位置。在重新提交或聯繫審閱者之前至少等待一週——在諸如合併窗口之類的 繁忙時間可能更長。 -10）主題中包含 PATCH --------------------- - -由於到linus和linux內核的電子郵件流量很高，通常會在主題行前面加上[PATCH] -前綴. 這使Linus和其他內核開發人員更容易將補丁與其他電子郵件討論區分開。 +在等了幾個星期後，用帶RESEND的主題重發補丁也是可以的:: -11）簽署你的作品-開發者原始認證 -------------------------------- + [PATCH Vx RESEND] sub/sys: Condensed patch summary -爲了加強對誰做了何事的追蹤，尤其是對那些透過好幾層的維護者的補丁，我們 -建議在發送出去的補丁上加一個 「sign-off」 的過程。 +當你發佈補丁（系列）修改版的時候，不要加上“RESEND”——“RESEND”只適用於重 +新提交之前未經修改的補丁（系列）。 -"sign-off" 是在補丁的注釋的最後的簡單的一行文字，認證你編寫了它或者其他 -人有權力將它作爲開放原始碼的補丁傳遞。規則很簡單：如果你能認證如下信息: - -開發者來源證書 1.1 -^^^^^^^^^^^^^^^^^^ - -對於本項目的貢獻，我認證如下信息： +主題中包含 PATCH +---------------- - （a）這些貢獻是完全或者部分的由我創建，我有權利以文件中指出 - 的開放原始碼許可證提交它；或者 - （b）這些貢獻基於以前的工作，據我所知，這些以前的工作受恰當的開放 - 原始碼許可證保護，而且，根據許可證，我有權提交修改後的貢獻， - 無論是完全還是部分由我創造，這些貢獻都使用同一個開放原始碼許可證 - （除非我被允許用其它的許可證），正如文件中指出的；或者 - （c）這些貢獻由認證（a），（b）或者（c）的人直接提供給我，而 - 且我沒有修改它。 - （d）我理解並同意這個項目和貢獻是公開的，貢獻的記錄（包括我 - 一起提交的個人記錄，包括 sign-off ）被永久維護並且可以和這個項目 - 或者開放原始碼的許可證同步地再發行。 +由於到Linus和linux-kernel的電子郵件流量很高，通常會在主題行前面加上[PATCH] +前綴。這使Linus和其他內核開發人員更容易將補丁與其他電子郵件討論區分開。 -那麼加入這樣一行:: +``git send-email`` 會自動爲你加上。 - Signed-off-by: Random J Developer <random@developer.example.org> +簽署你的作品——開發者來源認證 +------------------------------ -使用你的真名（抱歉，不能使用假名或者匿名。） +爲了加強對誰做了何事的追蹤，尤其是對那些透過好幾層維護者才最終到達的補丁，我 +們在通過郵件發送的補丁上引入了“簽署（sign-off）”流程。 -有人在最後加上標籤。現在這些東西會被忽略，但是你可以這樣做，來標記公司 -內部的過程，或者只是指出關於 sign-off 的一些特殊細節。 +“簽署”是在補丁註釋最後的一行簡單文字，認證你編寫了它或者其他 +人有權力將它作爲開放源代碼的補丁傳遞。規則很簡單：如果你能認證如下信息: -如果您是子系統或分支維護人員，有時需要稍微修改收到的補丁，以便合併它們， -因爲樹和提交者中的代碼不完全相同。如果你嚴格遵守規則（c），你應該要求提交者 -重新發布，但這完全是在浪費時間和精力。規則（b）允許您調整代碼，但是更改一個 -提交者的代碼並讓他認可您的錯誤是非常不禮貌的。要解決此問題，建議在最後一個 -由簽名行和您的行之間添加一行，指示更改的性質。雖然這並不是強制性的，但似乎 -在描述前加上您的郵件和/或姓名（全部用方括號括起來），這足以讓人注意到您對最 -後一分鐘的更改負有責任。例如:: +開發者來源認證 1.1 +^^^^^^^^^^^^^^^^^^ - Signed-off-by: Random J Developer <random@developer.example.org> - [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] - Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org> +對於本項目的貢獻，我認證如下信息： -如果您維護一個穩定的分支機構，同時希望對作者進行致謝、跟蹤更改、合併修復並 -保護提交者不受投訴，那麼這種做法尤其有用。請注意，在任何情況下都不能更改作者 -的ID（From 頭），因爲它是出現在更改日誌中的標識。 + (a) 這些貢獻是完全或者部分的由我創建，我有權利以文件中指出 + 的開放源代碼許可證提交它；或者 -對回合（back-porters）的特別說明：在提交消息的頂部（主題行之後）插入一個補丁 -的起源指示似乎是一種常見且有用的實踐，以便於跟蹤。例如，下面是我們在3.x穩定 -版本中看到的內容:: + (b) 這些貢獻基於以前的工作，據我所知，這些以前的工作受恰當的開放 + 源代碼許可證保護，而且，根據文件中指出的許可證，我有權提交修改後的貢獻， + 無論是完全還是部分由我創造，這些貢獻都使用同一個開放源代碼許可證 + （除非我被允許用其它的許可證）；或者 - Date: Tue Oct 7 07:26:38 2014 -0400 + (c) 這些貢獻由認證（a），（b）或者（c）的人直接提供給我，而 + 且我沒有修改它。 - libata: Un-break ATA blacklist + (d) 我理解並同意這個項目和貢獻是公開的，貢獻的記錄（包括我 + 一起提交的個人記錄，包括sign-off）被永久維護並且可以和這個項目 + 或者開放源代碼的許可證同步地再發行。 - commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. +那麼加入這樣一行:: -還有， 這裡是一個舊版內核中的一個回合補丁:: + Signed-off-by: Random J Developer <random@developer.example.org> - Date: Tue May 13 22:12:27 2008 +0200 +使用你的真名（抱歉，不能使用假名或者匿名。）如果使用 ``git commit -s`` 的話 +將會自動完成。撤銷也應當包含“Signed-off-by”， ``git revert -s`` 會幫你搞定。 - wireless, airo: waitbusy() won't delay +有些人會在最後加上額外的標籤。現在這些東西會被忽略，但是你可以這樣做，來標記 +公司內部的過程，或者只是指出關於簽署的一些特殊細節。 - [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] +作者簽署之後的任何其他簽署（Signed-off-by:'s）均來自處理和傳遞補丁的人員，但 +未參與其開發。簽署鏈應當反映補丁傳播到維護者並最終傳播到Linus所經過的 **真實** +路徑，首個簽署指明單個作者的主要作者身份。 -12）何時使用Acked-by:，CC:，和Co-Developed by: ----------------------------------------------- +何時使用Acked-by:，CC:，和Co-Developed by: +------------------------------------------ -Singed-off-by: 標記表示簽名者參與了補丁的開發，或者他/她在補丁的傳遞路徑中。 +Singed-off-by: 標籤表示簽名者參與了補丁的開發，或者他/她在補丁的傳遞路徑中。 -如果一個人沒有直接參與補丁的準備或處理，但希望表示並記錄他們對補丁的批准， -那麼他們可以要求在補丁的變更日誌中添加一個 Acked-by: +如果一個人沒有直接參與補丁的準備或處理，但希望表示並記錄他們對補丁的批准/贊成， +那麼他們可以要求在補丁的變更日誌中添加一個Acked-by:。 -Acked-by：通常由受影響代碼的維護者使用，當該維護者既沒有貢獻也沒有轉發補丁時。 +Acked-by: 通常由受影響代碼的維護者使用，當該維護者既沒有貢獻也沒有轉發補丁時。 -Acked-by: 不像簽字人那樣正式。這是一個記錄，確認人至少審查了補丁，並表示接受。 -因此，補丁合併有時會手動將Acker的「Yep，looks good to me」轉換爲 Acked-By：（但 +Acked-by: 不像簽署那樣正式。這是一個記錄，確認人至少審閱了補丁，並表示接受。 +因此，補丁合併有時會手動將Acker的“Yep，looks good to me”轉換爲 Acked-By:（但 請注意，通常最好要求一個明確的Ack）。 Acked-by：不一定表示對整個補丁的確認。例如，如果一個補丁影響多個子系統，並且 -有一個：來自一個子系統維護者，那麼這通常表示只確認影響維護者代碼的部分。這裡 -應該仔細判斷。如有疑問，應參考郵件列表檔案中的原始討論。 +有一個來自某個子系統維護者的Acked-By:，那麼這通常表示只確認影響維護者代碼的部 +分。這裏應該仔細判斷。如有疑問，應參考郵件列表存檔中的原始討論。 -如果某人有機會對補丁進行評論，但沒有提供此類評論，您可以選擇在補丁中添加 ``Cc:`` -這是唯一一個標籤，它可以在沒有被它命名的人顯式操作的情況下添加，但它應該表明 -這個人是在補丁上抄送的。討論中包含了潛在利益相關方。 +如果某人本應有機會對補丁進行評論，但沒有提供此類評論，您可以選擇在補丁中添加 +``Cc:`` 這是唯一可以在沒有被該人明確同意的情況下添加的標籤——但它應該表明 +這個人是在補丁上抄送的。此標籤記錄了討論中包含的潛在利益相關方。 Co-developed-by: 聲明補丁是由多個開發人員共同創建的；當幾個人在一個補丁上工 -作時，它用於將屬性賦予共同作者（除了 From: 所賦予的作者之外）。因爲 -Co-developed-by: 表示作者身份，所以每個共同開發人：必須緊跟在相關合作作者的 -簽名之後。標準的簽核程序要求：標記的簽核順序應儘可能反映補丁的時間歷史，而不 -管作者是通過 From ：還是由 Co-developed-by: 共同開發的。值得注意的是，最後一 -個簽字人：必須始終是提交補丁的開發人員。 +作時，它用於給出共同作者（除了From:所給出的作者之外）。因爲Co-developed-by: +表示作者身份，所以每個Co-developed-by:必須緊跟在相關合作作者的簽署之後。標準 +簽署程序要求Singed-off-by:標籤的順序應儘可能反映補丁的時間歷史，無論作者是通 +過From:還是Co-developed-by:表明。值得注意的是，最後一個Singed-off-by:必須是 +提交補丁的開發人員。 -注意，當作者也是電子郵件標題「發件人：」行中列出的人時，「From: 」 標記是可選的。 +注意，如果From:作者也是電子郵件標題的From:行中列出的人，則From:標籤是可選的。 -作者提交的補丁程序示例:: +被From:作者提交的補丁示例:: <changelog> @@ -423,7 +375,7 @@ Co-developed-by: 表示作者身份，所以每個共同開發人：必須緊跟 Signed-off-by: Second Co-Author <second@coauthor.example.org> Signed-off-by: From Author <from@author.example.org> -合作開發者提交的補丁示例:: +被合作開發者提交的補丁示例:: From: From Author <from@author.example.org> @@ -436,106 +388,115 @@ Co-developed-by: 表示作者身份，所以每個共同開發人：必須緊跟 Signed-off-by: Submitting Co-Author <sub@coauthor.example.org> -13）使用報告人：、測試人：、審核人：、建議人：、修復人： --------------------------------------------------------- +使用Reported-by:、Tested-by:、Reviewed-by:、Suggested-by:和Fixes: +----------------------------------------------------------------- Reported-by: 給那些發現錯誤並報告錯誤的人致謝，它希望激勵他們在將來再次幫助 -我們。請注意，如果bug是以私有方式報告的，那麼在使用Reported-by標記之前，請 -先請求權限。 +我們。請注意，如果bug是以私有方式報告的，那麼在使用Reported-by標籤之前，請 +先請求許可。此標籤是爲Bug設計的；請不要將其用於感謝功能請求。 -Tested-by: 標記表示補丁已由指定的人（在某些環境中）成功測試。這個標籤通知 -維護人員已經執行了一些測試，爲將來的補丁提供了一種定位測試人員的方法，並確 -保測試人員的信譽。 +Tested-by: 標籤表示補丁已由指定的人（在某些環境中）成功測試。這個標籤通知 +維護人員已經執行了一些測試，爲將來的補丁提供了一種定位測試人員的方法，並彰顯測試人員的功勞。 -Reviewed-by：相反，根據審查人的聲明，表明該補丁已被審查並被認爲是可接受的： +Reviewed-by：根據審閱者的監督聲明，表明該補丁已被審閱並被認爲是可接受的： -審查人的監督聲明 +審閱者的監督聲明 ^^^^^^^^^^^^^^^^ -通過提供我的 Reviewed-by，我聲明： +通過提供我的Reviewed-by:標籤，我聲明： - (a) 我已經對這個補丁進行了一次技術審查，以評估它是否適合被包含到 + (a) 我已經對這個補丁進行了一次技術審閱，以評估它是否適合被包含到 主線內核中。 (b) 與補丁相關的任何問題、顧慮或問題都已反饋給提交者。我對提交者對 我的評論的回應感到滿意。 - (c) 雖然這一提交可能會改進一些東西，但我相信，此時，（1）對內核 + (c) 雖然這一提交可能仍可被改進，但我相信，此時，（1）對內核 進行了有價值的修改，（2）沒有包含爭論中涉及的已知問題。 - (d) 雖然我已經審查了補丁並認爲它是健全的，但我不會（除非另有明確 - 說明）作出任何保證或保證它將在任何給定情況下實現其規定的目的 + (d) 雖然我已經審閱了補丁並認爲它是健全的，但我不會（除非另有明確 + 說明）作出任何保證或擔保它會在任何給定情況下實現其規定的目的 或正常運行。 -Reviewed-by 是一種觀點聲明，即補丁是對內核的適當修改，沒有任何遺留的嚴重技術 -問題。任何感興趣的審閱者（完成工作的人）都可以爲一個補丁提供一個 Review-by -標籤。此標籤用於向審閱者提供致謝，並通知維護者已在修補程序上完成的審閱程度。 -Reviewed-by: 當由已知了解主題區域並執行徹底檢查的審閱者提供時，通常會增加 +Reviewed-by是一種觀點聲明，即補丁是對內核的適當修改，沒有任何遺留的嚴重技術 +問題。任何感興趣的審閱者（完成工作的人）都可以爲一個補丁提供一個Reviewed-by +標籤。此標籤用於向審閱者提供致謝，並通知維護者補丁的審閱進度。 +當Reviewed-by:標籤由已知了解主題區域並執行徹底檢查的審閱者提供時，通常會增加 補丁進入內核的可能性。 +一旦從測試人員或審閱者的“Tested-by”和“Reviewed-by”標籤出現在郵件列表中， +作者應在發送下一個版本時將其添加到適用的補丁中。但是，如果補丁在以下版本中發 +生了實質性更改，這些標籤可能不再適用，因此應該刪除。通常，在補丁更改日誌中 +（在 ``---`` 分隔符之後）應該提到刪除某人的測試者或審閱者標籤。 + Suggested-by: 表示補丁的想法是由指定的人提出的，並確保將此想法歸功於指定的 -人。請注意，未經許可，不得添加此標籤，特別是如果該想法未在公共論壇上發布。 -這就是說，如果我們勤快地致謝我們的創意者，他們很有希望在未來得到鼓舞，再次 +人。請注意，未經許可，不得添加此標籤，特別是如果該想法未在公共論壇上發佈。 +也就是說，如果我們勤快地致謝創意提供者，他們將受到鼓舞，很有希望在未來再次 幫助我們。 -Fixes: 指示補丁在以前的提交中修復了一個問題。它可以很容易地確定錯誤的來源， -這有助於檢查錯誤修復。這個標記還幫助穩定內核團隊確定應該接收修復的穩定內核 -版本。這是指示補丁修復的錯誤的首選方法。請參閱 :ref:`tw_describe_changes` -描述您的更改以了解更多詳細信息。 +Fixes: 指示補丁修復了之前提交的一個問題。它可以便於確定錯誤的來源，這有助於 +檢查錯誤修復。這個標籤還幫助穩定內核團隊確定應該接收修復的穩定內核版本。這是 +指示補丁修復的錯誤的首選方法。請參閱 :ref:`zh_describe_changes` 瞭解更多信息。 + +.. note:: + + 附加Fixes:標籤不會改變穩定內核規則流程，也不改變所有穩定版補丁抄送 + stable@vger.kernel.org的要求。有關更多信息，請閱讀 + Documentation/translations/zh_CN/process/stable-kernel-rules.rst 。 .. _tw_the_canonical_patch_format: -12）標準補丁格式 ----------------- +標準補丁格式 +------------ 本節描述如何格式化補丁本身。請注意，如果您的補丁存儲在 ``Git`` 存儲庫中，則 -可以使用 ``git format-patch`` 進行正確的補丁格式設置。但是，這些工具無法創建 +可以使用 ``git format-patch`` 進行正確的補丁格式化。但是，這些工具無法創建 必要的文本，因此請務必閱讀下面的說明。 -標準的補丁，標題行是:: +標準的補丁標題行是:: Subject: [PATCH 001/123] 子系統:一句話概述 -標準補丁的信體存在如下部分： +標準補丁的信體包含如下部分： - - 一個 "from" 行指出補丁作者。後跟空行（僅當發送修補程序的人不是作者時才需要）。 + - 一個 ``from`` 行指出補丁作者。後跟空行（僅當發送補丁的人不是作者時才需要）。 - - 解釋的正文，行以75列包裝，這將被複製到永久變更日誌來描述這個補丁。 + - 說明文字，每行最長75列，這將被複制到永久變更日誌來描述這個補丁。 - 一個空行 - - 上面描述的「Signed-off-by」 行，也將出現在更改日誌中。 + - 上述的 ``Signed-off-by:`` 行，也將出現在更改日誌中。 - 只包含 ``---`` 的標記線。 - - 任何其他不適合放在變更日誌的注釋。 + - 任何其他不適合放在變更日誌的註釋。 - 實際補丁（ ``diff`` 輸出）。 -標題行的格式，使得對標題行按字母序排序非常的容易 - 很多 e-mail 客戶端都 -可以支持 - 因爲序列號是用零填充的，所以按數字排序和按字母排序是一樣的。 +標題行的格式，使得對標題行按字母序排序非常的容易——很多郵件客戶端都 +可以支持——因爲序列號是用零填充的，所以按數字排序和按字母排序是一樣的。 -e-mail 標題中的「子系統」標識哪個內核子系統將被打補丁。 +郵件標題中的“子系統”標識哪個內核子系統將被打補丁。 -e-mail 標題中的「一句話概述」扼要的描述 e-mail 中的補丁。「一句話概述」 -不應該是一個文件名。對於一個補丁系列（「補丁系列」指一系列的多個相關補 -丁），不要對每個補丁都使用同樣的「一句話概述」。 +郵件標題中的“一句話概述”扼要的描述郵件中的補丁。“一句話概述” +不應該是一個文件名。對於一個補丁系列（“補丁系列”指一系列的多個相關補 +丁），不要對每個補丁都使用同樣的“一句話概述”。 -記住 e-mail 的「一句話概述」會成爲該補丁的全局唯一標識。它會蔓延到 git -的改動記錄里。然後「一句話概述」會被用在開發者的討論里，用來指代這個補 -丁。用戶將希望通過 google 來搜索"一句話概述"來找到那些討論這個補丁的文 +記住郵件的“一句話概述”會成爲該補丁的全局唯一標識。它會進入 ``git`` +的改動記錄裏。然後“一句話概述”會被用在開發者的討論裏，用來指代這個補 +丁。用戶將希望通過搜索引擎搜索“一句話概述”來找到那些討論這個補丁的文 章。當人們在兩三個月後使用諸如 ``gitk`` 或 ``git log --oneline`` 之類 的工具查看數千個補丁時，也會很快看到它。 出於這些原因，概述必須不超過70-75個字符，並且必須描述補丁的更改以及爲 -什麼需要補丁。既要簡潔又要描述性很有挑戰性，但寫得好的概述應該這樣做。 +什麼需要補丁。既要簡潔又要描述性很有挑戰性，但寫得好的概述應該這樣。 -概述的前綴可以用方括號括起來：「Subject: [PATCH <tag>...] <概述>」。標記 +概述的前綴可以用方括號括起來：“Subject: [PATCH <tag>...] <概述>”。標記 不被視爲概述的一部分，而是描述應該如何處理補丁。如果補丁的多個版本已發 -送出來以響應評審（即「v1，v2，v3」）或「rfc」，以指示評審請求，那麼通用標記 -可能包括版本描述符。如果一個補丁系列中有四個補丁，那麼各個補丁可以這樣 -編號：1/4、2/4、3/4、4/4。這可以確保開發人員了解補丁應用的順序，並且他們 +送出來以響應評審（即“v1，v2，v3”）則必須包含版本號，或包含“RFC”以指示 +評審請求。如果一個補丁系列中有四個補丁，那麼各個補丁可以這樣編號：1/4、2/4、 +3/4、4/4。這可以確保開發人員瞭解補丁應用的順序，且 已經查看或應用了補丁系列中的所有補丁。 一些標題的例子:: @@ -543,95 +504,134 @@ e-mail 標題中的「一句話概述」扼要的描述 e-mail 中的補丁。 Subject: [patch 2/5] ext2: improve scalability of bitmap searching Subject: [PATCHv2 001/207] x86: fix eflags tracking -"From" 行是信體裡的最上面一行，具有如下格式： +``From`` 行是信體裏的最上面一行，具有如下格式:: + From: Patch Author <author@example.com> -"From" 行指明在永久改動日誌里，誰會被確認爲作者。如果沒有 "From" 行，那 -麼郵件頭裡的 "From: " 行會被用來決定改動日誌中的作者。 +``From`` 行指明在永久改動日誌裏，誰會被確認爲作者。如果沒有 ``From`` 行，那 +麼郵件頭裏的 ``From:`` 行會被用來決定改動日誌中的作者。 -說明的主題將會被提交到永久的原始碼改動日誌里，因此對那些早已經不記得和 -這個補丁相關的討論細節的有能力的讀者來說，是有意義的。包括補丁程序定位 -錯誤的（內核日誌消息、OOPS消息等）症狀，對於搜索提交日誌以尋找適用補丁的人 -尤其有用。如果一個補丁修復了一個編譯失敗，那麼可能不需要包含所有編譯失敗； +說明文字將會被提交到永久的源代碼改動日誌裏，因此應針對那些早已經不記得和這 +個補丁相關的討論細節的讀者。包括補丁處理的故障症狀（內核日誌消息、oops消息 +等），這對於可能正在搜索提交日誌以查找適用補丁的人特別有用。文本應該寫得如 +此詳細，以便在數週、數月甚至數年後閱讀時，能夠爲讀者提供所需的細節信息，以 +掌握創建補丁的 **原因** 。 + +如果一個補丁修復了一個編譯失敗，那麼可能不需要包含 *所有* 編譯失敗； 只要足夠讓搜索補丁的人能夠找到它就行了。與概述一樣，既要簡潔又要描述性。 -"---" 標記行對於補丁處理工具要找到哪裡是改動日誌信息的結束，是不可缺少 +``---`` 標記行對於補丁處理工具要找到哪裏是改動日誌信息的結束，是不可缺少 的。 -對於 "---" 標記之後的額外註解，一個好的用途就是用來寫 diffstat，用來顯 -示修改了什麼文件和每個文件都增加和刪除了多少行。diffstat 對於比較大的補 -丁特別有用。其餘那些只是和時刻或者開發者相關的註解，不合適放到永久的改 -動日誌里的，也應該放這裡。 -使用 diffstat的選項 "-p 1 -w 70" 這樣文件名就會從內核原始碼樹的目錄開始 -，不會占用太寬的空間（很容易適合80列的寬度，也許會有一些縮進。） +對於 ``---`` 標記之後的額外註解，一個好的用途就是用來寫 ``diffstat`` ，用來顯 +示修改了什麼文件和每個文件都增加和刪除了多少行。 ``diffstat`` 對於比較大的補 +丁特別有用。 +使用 ``diffstat`` 的選項 ``-p 1 -w 70`` 這樣文件名就會從內核源代碼樹的目錄開始 +，不會佔用太寬的空間（很容易適合80列的寬度，也許會有一些縮進。） +（ ``git`` 默認會生成合適的diffstat。） -在後面的參考資料中能看到適當的補丁格式的更多細節。 +其餘那些只適用於當時或者與維護者相關的註解，不合適放到永久的改動日誌裏的，也 +應該放這裏。較好的例子就是 ``補丁更改記錄`` ，記錄了v1和v2版本補丁之間的差異。 -.. _tw_explicit_in_reply_to: +請將此信息放在將變更日誌與補丁的其餘部分分隔開的 ``---`` 行 **之後** 。版本 +信息不是提交到git樹的變更日誌的一部分。只是供審閱人員使用的附加信息。如果將 +其放置在提交標記上方，則需要手動交互才能將其刪除。如果它位於分隔線以下，則在 +應用補丁時會自動剝離:: -15) 明確回覆郵件頭(In-Reply-To) -------------------------------- + <commit message> + ... + Signed-off-by: Author <author@mail> + --- + V2 -> V3: Removed redundant helper function + V1 -> V2: Cleaned up coding style and addressed review comments -手動添加回復補丁的的標題頭(In-Reply_To:) 是有幫助的（例如，使用 ``git send-email`` ） -將補丁與以前的相關討論關聯起來，例如，將bug修復程序連結到電子郵件和bug報告。 -但是，對於多補丁系列，最好避免在回復時使用連結到該系列的舊版本。這樣， -補丁的多個版本就不會成爲電子郵件客戶端中無法管理的引用序列。如果連結有用， -可以使用 https://lore.kernel.org/ 重定向器（例如，在封面電子郵件文本中） -連結到補丁系列的早期版本。 + path/to/file | 5+++-- + ... + +在後面的參考資料中能看到正確補丁格式的更多細節。 -16) 發送git pull請求 --------------------- +.. _tw_backtraces: -如果您有一系列補丁，那麼讓維護人員通過git pull操作將它們直接拉入子系統存儲 -庫可能是最方便的。但是，請注意，從開發人員那裡獲取補丁比從郵件列表中獲取補 -丁需要更高的信任度。因此，許多子系統維護人員不願意接受請求，特別是來自新的 -未知開發人員的請求。如果有疑問，您可以在封面郵件中使用pull 請求作爲補丁系列 -正常發布的一個選項，讓維護人員可以選擇使用其中之一。 +提交消息中的回溯（Backtraces） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +回溯有助於記錄導致問題的調用鏈。然而，並非所有回溯都有幫助。例如，早期引導調 +用鏈是獨特而明顯的。而逐字複製完整的dmesg輸出則會增加時間戳、模塊列表、寄存 +器和堆棧轉儲等分散注意力的信息。 + +因此，最有用的回溯應該從轉儲中提取相關信息，以更容易集中在真實問題上。下面是 +一個剪裁良好的回溯示例:: + + unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) + at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) + Call Trace: + mba_wrmsr + update_domains + rdtgroup_mkdir + +.. _tw_explicit_in_reply_to: + +明確回覆郵件頭（In-Reply-To） +----------------------------- + +手動添加回復補丁的的郵件頭（In-Reply_To:）是有用的（例如，使用 ``git send-email`` ）， +可以將補丁與以前的相關討論關聯起來，例如，將bug補丁鏈接到電子郵件和bug報告。 +但是，對於多補丁系列，最好避免在回覆時使用鏈接到該系列的舊版本。這樣， +補丁的多個版本就不會成爲電子郵件客戶端中無法管理的引用樹。如果鏈接有用， +可以使用 https://lore.kernel.org/ 重定向器（例如，在封面電子郵件文本中） +鏈接到補丁系列的早期版本。 -pull 請求的主題行中應該有[Git Pull]。請求本身應該在一行中包含存儲庫名稱和 -感興趣的分支；它應該看起來像:: +給出基礎樹信息 +-------------- - Please pull from +當其他開發人員收到您的補丁並開始審閱時，知道應該將您的工作放到代碼樹歷史記錄 +中的什麼位置通常很有用。這對於自動化持續集成流水（CI）特別有用，這些流水線試 +圖運行一系列測試，以便在維護人員開始審閱之前確定提交的質量。 - git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus +如果您使用 ``git format-patch`` 生成補丁，則可以通過 ``--base`` 標誌在提交中 +自動包含基礎樹信息。使用此選項最簡單、最方便的方法是配合主題分支:: - to get these changes: + $ git checkout -t -b my-topical-branch master + Branch 'my-topical-branch' set up to track local branch 'master'. + Switched to a new branch 'my-topical-branch' + [perform your edits and commits] -pull 請求還應該包含一條整體消息，說明請求中將包含什麼，一個補丁本身的 ``Git shortlog`` -以及一個顯示補丁系列整體效果的 ``diffstat`` 。當然，將所有這些信息收集在一起 -的最簡單方法是讓 ``git`` 使用 ``git request-pull`` 命令爲您完成這些工作。 + $ git format-patch --base=auto --cover-letter -o outgoing/ master + outgoing/0000-cover-letter.patch + outgoing/0001-First-Commit.patch + outgoing/... -一些維護人員（包括Linus）希望看到來自已簽名提交的請求；這增加了他們對你的 -請求信心。特別是，在沒有簽名標籤的情況下，Linus 不會從像 Github 這樣的公共 -託管站點拉請求。 +當你編輯 ``outgoing/0000-cover-letter.patch`` 時，您會注意到在它的最底部有一 +行 ``base-commit:`` 尾註，它爲審閱者和CI工具提供了足夠的信息以正確執行 +``git am`` 而不必擔心衝突:: -創建此類簽名的第一步是生成一個 GNRPG 密鑰，並由一個或多個核心內核開發人員對 -其進行簽名。這一步對新開發人員來說可能很困難，但沒有辦法繞過它。參加會議是 -找到可以簽署您的密鑰的開發人員的好方法。 + $ git checkout -b patch-review [base-commit-id] + Switched to a new branch 'patch-review' + $ git am patches.mbox + Applying: First Commit + Applying: ... -一旦您在Git 中準備了一個您希望有人拉的補丁系列，就用 ``git tag -s`` 創建一 -個簽名標記。這將創建一個新標記，標識該系列中的最後一次提交，並包含用您的私 -鑰創建的簽名。您還可以將changelog樣式的消息添加到標記中；這是一個描述拉請求 -整體效果的理想位置。 +有關此選項的更多信息，請參閱 ``man git-format-patch`` 。 -如果維護人員將要從中提取的樹不是您正在使用的存儲庫，請不要忘記將已簽名的標記 -顯式推送到公共樹。 +.. note:: -生成拉請求時，請使用已簽名的標記作爲目標。這樣的命令可以實現:: + ``--base`` 功能是在2.9.0版git中引入的。 - git request-pull master git://my.public.tree/linux.git my-signed-tag +如果您不使用git格式化補丁，仍然可以包含相同的 ``base-commit`` 尾註，以指示您 +的工作所基於的樹的提交哈希。你應該在封面郵件或系列的第一個補丁中添加它，它應 +該放在 ``---`` 行的下面或所有其他內容之後，即只在你的電子郵件簽名之前。 參考文獻 -------- -Andrew Morton, "The perfect patch" (tpp). +Andrew Morton，“完美的補丁”（tpp） <https://www.ozlabs.org/~akpm/stuff/tpp.txt> -Jeff Garzik, "Linux kernel patch submission format". +Jeff Garzik，“Linux內核補丁提交格式” <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> -Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". +Greg Kroah-Hartman，“如何惹惱內核子系統維護人員” <http://www.kroah.com/log/linux/maintainer.html> <http://www.kroah.com/log/linux/maintainer-02.html> @@ -644,17 +644,16 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". <http://www.kroah.com/log/linux/maintainer-06.html> -NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! +不！！！別再發巨型補丁炸彈給linux-kernel@vger.kernel.org的人們了！ <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net> -Kernel Documentation/process/coding-style.rst: - :ref:`Documentation/translations/zh_TW/process/coding-style.rst <tw_codingstyle>` +內核 Documentation/translations/zh_CN/process/coding-style.rst -Linus Torvalds's mail on the canonical patch format: +Linus Torvalds關於標準補丁格式的郵件 <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org> -Andi Kleen, "On submitting kernel patches" - Some strategies to get difficult or controversial changes in. +Andi Kleen，“提交補丁之路” + 一些幫助合入困難或有爭議的變更的策略。 http://halobates.de/on-submitting-patches.pdf diff --git a/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst b/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst index 097fe80352cb..a609620affb0 100644 --- a/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst +++ b/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst @@ -17,22 +17,22 @@ 中文版校譯者： 張漢輝 Eugene Teo <eugeneteo@kernel.sg> 楊瑞 Dave Young <hidave.darkstar@gmail.com> 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> - 胡皓文 Hu Haowen <src.res@email.cn> + 胡皓文 Hu Haowen <src.res.211@gmail.com> -爲什麼不應該使用「volatile」類型 -================================ +爲什麼不應該使用“volatile”類型 +============================== -C程式設計師通常認爲volatile表示某個變量可以在當前執行的線程之外被改變；因此，在內核 -中用到共享數據結構時，常常會有C程式設計師喜歡使用volatile這類變量。換句話說，他們經 +C程序員通常認爲volatile表示某個變量可以在當前執行的線程之外被改變；因此，在內核 +中用到共享數據結構時，常常會有C程序員喜歡使用volatile這類變量。換句話說，他們經 常會把volatile類型看成某種簡易的原子變量，當然它們不是。在內核中使用volatile幾 乎總是錯誤的；本文檔將解釋爲什麼這樣。 理解volatile的關鍵是知道它的目的是用來消除優化，實際上很少有人真正需要這樣的應 -用。在內核中，程式設計師必須防止意外的並發訪問破壞共享的數據結構，這其實是一個完全 -不同的任務。用來防止意外並發訪問的保護措施，可以更加高效的避免大多數優化相關的 +用。在內核中，程序員必須防止意外的併發訪問破壞共享的數據結構，這其實是一個完全 +不同的任務。用來防止意外併發訪問的保護措施，可以更加高效的避免大多數優化相關的 問題。 -像volatile一樣，內核提供了很多原語來保證並發訪問時的數據安全（自旋鎖, 互斥量,內 +像volatile一樣，內核提供了很多原語來保證併發訪問時的數據安全（自旋鎖, 互斥量,內 存屏障等等），同樣可以防止意外的優化。如果可以正確使用這些內核原語，那麼就沒有 必要再使用volatile。如果仍然必須使用volatile，那麼幾乎可以肯定在代碼的某處有一 個bug。在正確設計的內核代碼中，volatile能帶來的僅僅是使事情變慢。 @@ -46,8 +46,8 @@ C程式設計師通常認爲volatile表示某個變量可以在當前執行的 如果所有的代碼都遵循加鎖規則，當持有the_lock的時候，不可能意外的改變shared_data的 值。任何可能訪問該數據的其他代碼都會在這個鎖上等待。自旋鎖原語跟內存屏障一樣—— 它 -們顯式的用來書寫成這樣 —— 意味著數據訪問不會跨越它們而被優化。所以本來編譯器認爲 -它知道在shared_data裡面將有什麼，但是因爲spin_lock()調用跟內存屏障一樣，會強制編 +們顯式的用來書寫成這樣 —— 意味着數據訪問不會跨越它們而被優化。所以本來編譯器認爲 +它知道在shared_data裏面將有什麼，但是因爲spin_lock()調用跟內存屏障一樣，會強制編 譯器忘記它所知道的一切。那麼在訪問這些數據時不會有優化的問題。 如果shared_data被聲名爲volatile，鎖操作將仍然是必須的。就算我們知道沒有其他人正在 @@ -55,13 +55,13 @@ C程式設計師通常認爲volatile表示某個變量可以在當前執行的 shared_data不是volatile的。在處理共享數據的時候，適當的鎖操作可以不再需要 volatile —— 並且是有潛在危害的。 -volatile的存儲類型最初是爲那些內存映射的I/O寄存器而定義。在內核里，寄存器訪問也應 -該被鎖保護，但是人們也不希望編譯器「優化」臨界區內的寄存器訪問。內核里I/O的內存訪問 +volatile的存儲類型最初是爲那些內存映射的I/O寄存器而定義。在內核裏，寄存器訪問也應 +該被鎖保護，但是人們也不希望編譯器“優化”臨界區內的寄存器訪問。內核裏I/O的內存訪問 是通過訪問函數完成的；不贊成通過指針對I/O內存的直接訪問，並且不是在所有體系架構上 都能工作。那些訪問函數正是爲了防止意外優化而寫的，因此，再說一次，volatile類型不 是必需的。 -另一種引起用戶可能使用volatile的情況是當處理器正忙著等待一個變量的值。正確執行一 +另一種引起用戶可能使用volatile的情況是當處理器正忙着等待一個變量的值。正確執行一 個忙等待的方法是:: while (my_variable != what_i_want) @@ -74,14 +74,14 @@ cpu_relax()調用會降低CPU的能量消耗或者讓位於超線程雙處理器 - 在一些體系架構的系統上，允許直接的I/0內存訪問，那麼前面提到的訪問函數可以使用 volatile。基本上，每一個訪問函數調用它自己都是一個小的臨界區域並且保證了按照 - 程式設計師期望的那樣發生訪問操作。 + 程序員期望的那樣發生訪問操作。 - 某些會改變內存的內聯彙編代碼雖然沒有什麼其他明顯的附作用，但是有被GCC刪除的可 能性。在彙編聲明中加上volatile關鍵字可以防止這種刪除操作。 - Jiffies變量是一種特殊情況，雖然每次引用它的時候都可以有不同的值，但讀jiffies 變量時不需要任何特殊的加鎖保護。所以jiffies變量可以使用volatile，但是不贊成 - 其他跟jiffies相同類型變量使用volatile。Jiffies被認爲是一種「愚蠢的遺留物" + 其他跟jiffies相同類型變量使用volatile。Jiffies被認爲是一種“愚蠢的遺留物" （Linus的話）因爲解決這個問題比保持現狀要麻煩的多。 - 由於某些I/0設備可能會修改連續一致的內存,所以有時,指向連續一致內存的數據結構 @@ -92,9 +92,9 @@ cpu_relax()調用會降低CPU的能量消耗或者讓位於超線程雙處理器 bug並且需要對這樣的代碼額外仔細檢查。那些試圖使用volatile的開發人員需要退一步想想 他們真正想實現的是什麼。 -非常歡迎刪除volatile變量的補丁 － 只要證明這些補丁完整的考慮了並發問題。 +非常歡迎刪除volatile變量的補丁 － 只要證明這些補丁完整的考慮了併發問題。 -注釋 +註釋 ---- [1] https://lwn.net/Articles/233481/ diff --git a/Documentation/usb/authorization.rst b/Documentation/usb/authorization.rst index 9e53909d04c2..150a14970e95 100644 --- a/Documentation/usb/authorization.rst +++ b/Documentation/usb/authorization.rst @@ -33,12 +33,9 @@ Remove the lock down:: $ echo 1 > /sys/bus/usb/devices/usbX/authorized_default -By default, Wired USB devices are authorized by default to -connect. Wireless USB hosts deauthorize by default all new connected -devices (this is so because we need to do an authentication phase -before authorizing). Writing "2" to the authorized_default attribute -causes kernel to only authorize by default devices connected to internal -USB ports. +By default, all USB devices are authorized. Writing "2" to the +authorized_default attribute causes the kernel to authorize by default +only devices connected to internal USB ports. Example system lockdown (lame) diff --git a/Documentation/usb/gadget-testing.rst b/Documentation/usb/gadget-testing.rst index 2fca40443dc9..394cd226bfae 100644 --- a/Documentation/usb/gadget-testing.rst +++ b/Documentation/usb/gadget-testing.rst @@ -27,6 +27,7 @@ provided by gadgets. 18. UVC function 19. PRINTER function 20. UAC1 function (new API) + 21. MIDI2 function 1. ACM function @@ -965,3 +966,156 @@ e.g.:: $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \ aplay -D default:CARD=OdroidU3 + + +21. MIDI2 function +================== + +The function is provided by usb_f_midi2.ko module. +It will create a virtual ALSA card containing a UMP rawmidi device +where the UMP packet is looped back. In addition, a legacy rawmidi +device is created. The UMP rawmidi is bound with ALSA sequencer +clients, too. + +Function-specific configfs interface +------------------------------------ + +The function name to use when creating the function directory is "midi2". +The midi2 function provides these attributes in its function directory +as the card top-level information: + + ============= ================================================= + process_ump Bool flag to process UMP Stream messages (0 or 1) + static_block Bool flag for static blocks (0 or 1) + iface_name Optional interface name string + ============= ================================================= + +The directory contains a subdirectory "ep.0", and this provides the +attributes for a UMP Endpoint (which is a pair of USB MIDI Endpoints): + + ============= ================================================= + protocol_caps MIDI protocol capabilities; + 1: MIDI 1.0, 2: MIDI 2.0, or 3: both protocols + protocol Default MIDI protocol (either 1 or 2) + ep_name UMP Endpoint name string + product_id Product ID string + manufacturer Manufacture ID number (24 bit) + family Device family ID number (16 bit) + model Device model ID number (16 bit) + sw_revision Software revision (32 bit) + ============= ================================================= + +Each Endpoint subdirectory contains a subdirectory "block.0", which +represents the Function Block for Block 0 information. +Its attributes are: + + ================= =============================================== + name Function Block name string + direction Direction of this FB + 1: input, 2: output, or 3: bidirectional + first_group The first UMP Group number (0-15) + num_groups The number of groups in this FB (1-16) + midi1_first_group The first UMP Group number for MIDI 1.0 (0-15) + midi1_num_groups The number of groups for MIDI 1.0 (0-16) + ui_hint UI-hint of this FB + 0: unknown, 1: receiver, 2: sender, 3: both + midi_ci_verison Supported MIDI-CI version number (8 bit) + is_midi1 Legacy MIDI 1.0 device (0-2) + 0: MIDI 2.0 device, + 1: MIDI 1.0 without restriction, or + 2: MIDI 1.0 with low speed + sysex8_streams Max number of SysEx8 streams (8 bit) + active Bool flag for FB activity (0 or 1) + ================= =============================================== + +If multiple Function Blocks are required, you can add more Function +Blocks by creating subdirectories "block.<num>" with the corresponding +Function Block number (1, 2, ....). The FB subdirectories can be +dynamically removed, too. Note that the Function Block numbers must be +continuous. + +Similarly, if you multiple UMP Endpoints are required, you can add +more Endpoints by creating subdirectories "ep.<num>". The number must +be continuous. + +For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 0 +to `process_ump` flag. Then the whole UMP v1.1 requests are ignored. + +Testing the MIDI2 function +-------------------------- + +On the device: run the gadget, and running:: + + $ cat /proc/asound/cards + +will show a new sound card containing a MIDI2 device. + +OTOH, on the host:: + + $ cat /proc/asound/cards + +will show a new sound card containing either MIDI1 or MIDI2 device, +depending on the USB audio driver configuration. + +On both, when ALSA sequencer is enabled on the host, you can find the +UMP MIDI client such as "MIDI 2.0 Gadget". + +As the driver simply loops back the data, there is no need for a real +device just for testing. + +For testing a MIDI input from the gadget to the host (e.g. emulating a +MIDI keyboard), you can send a MIDI stream like the following. + +On the gadget:: + + $ aconnect -o + .... + client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1] + 0 'MIDI 2.0 ' + 1 'Group 1 (MIDI 2.0 Gadget I/O)' + $ aplaymidi -p 20:1 to_host.mid + +On the host:: + + $ aconnect -i + .... + client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2] + 0 'MIDI 2.0 ' + 1 'Group 1 (MIDI 2.0 Gadget I/O)' + $ arecordmidi -p 24:1 from_gadget.mid + +If you have a UMP-capable application, you can use the UMP port to +send/receive the raw UMP packets, too. For example, aseqdump program +with UMP support can receive from UMP port. On the host:: + + $ aseqdump -u 2 -p 24:1 + Waiting for data. Press Ctrl+C to end. + Source Group Event Ch Data + 24:1 Group 0, Program change 0, program 0, Bank select 0:0 + 24:1 Group 0, Channel pressure 0, value 0x80000000 + +For testing a MIDI output to the gadget to the host (e.g. emulating a +MIDI synth), it'll be just other way round. + +On the gadget:: + + $ arecordmidi -p 20:1 from_host.mid + +On the host:: + + $ aplaymidi -p 24:1 to_gadget.mid + +The access to MIDI 1.0 on altset 0 on the host is supported, and it's +translated from/to UMP packets on the gadget. It's bound to only +Function Block 0. + +The current operation mode can be observed in ALSA control element +"Operation Mode" for SND_CTL_IFACE_RAWMIDI. For example:: + + $ amixer -c1 contents + numid=1,iface=RAWMIDI,name='Operation Mode' + ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0 + : values=2 + +where 0 = unused, 1 = MIDI 1.0 (altset 0), 2 = MIDI 2.0 (altset 1). +The example above shows it's running in 2, i.e. MIDI 2.0. diff --git a/Documentation/usb/gadget_uvc.rst b/Documentation/usb/gadget_uvc.rst index 62bd81ba3dd1..bf78fba3ce23 100644 --- a/Documentation/usb/gadget_uvc.rst +++ b/Documentation/usb/gadget_uvc.rst @@ -126,7 +126,7 @@ might do: create_frame 1920 1080 uncompressed yuyv The only uncompressed format currently supported is YUYV, which is detailed at -Documentation/userspace-api/media/v4l/pixfmt-packed.yuv.rst. +Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst. Color Matching Descriptors ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -168,7 +168,7 @@ Header linking The UVC specification requires that Format and Frame descriptors be preceded by Headers detailing things such as the number and cumulative size of the different -Format descriptors that follow. This and similar operations are acheived in +Format descriptors that follow. This and similar operations are achieved in configfs by linking between the configfs item representing the header and the config items representing those other descriptors, in this manner: diff --git a/Documentation/userspace-api/dma-buf-alloc-exchange.rst b/Documentation/userspace-api/dma-buf-alloc-exchange.rst new file mode 100644 index 000000000000..fdff19fce13e --- /dev/null +++ b/Documentation/userspace-api/dma-buf-alloc-exchange.rst @@ -0,0 +1,389 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright 2021-2023 Collabora Ltd. + +======================== +Exchanging pixel buffers +======================== + +As originally designed, the Linux graphics subsystem had extremely limited +support for sharing pixel-buffer allocations between processes, devices, and +subsystems. Modern systems require extensive integration between all three +classes; this document details how applications and kernel subsystems should +approach this sharing for two-dimensional image data. + +It is written with reference to the DRM subsystem for GPU and display devices, +V4L2 for media devices, and also to Vulkan, EGL and Wayland, for userspace +support, however any other subsystems should also follow this design and advice. + + +Glossary of terms +================= + +.. glossary:: + + image: + Conceptually a two-dimensional array of pixels. The pixels may be stored + in one or more memory buffers. Has width and height in pixels, pixel + format and modifier (implicit or explicit). + + row: + A span along a single y-axis value, e.g. from co-ordinates (0,100) to + (200,100). + + scanline: + Synonym for row. + + column: + A span along a single x-axis value, e.g. from co-ordinates (100,0) to + (100,100). + + memory buffer: + A piece of memory for storing (parts of) pixel data. Has stride and size + in bytes and at least one handle in some API. May contain one or more + planes. + + plane: + A two-dimensional array of some or all of an image's color and alpha + channel values. + + pixel: + A picture element. Has a single color value which is defined by one or + more color channels values, e.g. R, G and B, or Y, Cb and Cr. May also + have an alpha value as an additional channel. + + pixel data: + Bytes or bits that represent some or all of the color/alpha channel values + of a pixel or an image. The data for one pixel may be spread over several + planes or memory buffers depending on format and modifier. + + color value: + A tuple of numbers, representing a color. Each element in the tuple is a + color channel value. + + color channel: + One of the dimensions in a color model. For example, RGB model has + channels R, G, and B. Alpha channel is sometimes counted as a color + channel as well. + + pixel format: + A description of how pixel data represents the pixel's color and alpha + values. + + modifier: + A description of how pixel data is laid out in memory buffers. + + alpha: + A value that denotes the color coverage in a pixel. Sometimes used for + translucency instead. + + stride: + A value that denotes the relationship between pixel-location co-ordinates + and byte-offset values. Typically used as the byte offset between two + pixels at the start of vertically-consecutive tiling blocks. For linear + layouts, the byte offset between two vertically-adjacent pixels. For + non-linear formats the stride must be computed in a consistent way, which + usually is done as-if the layout was linear. + + pitch: + Synonym for stride. + + +Formats and modifiers +===================== + +Each buffer must have an underlying format. This format describes the color +values provided for each pixel. Although each subsystem has its own format +descriptions (e.g. V4L2 and fbdev), the ``DRM_FORMAT_*`` tokens should be reused +wherever possible, as they are the standard descriptions used for interchange. +These tokens are described in the ``drm_fourcc.h`` file, which is a part of +DRM's uAPI. + +Each ``DRM_FORMAT_*`` token describes the translation between a pixel +co-ordinate in an image, and the color values for that pixel contained within +its memory buffers. The number and type of color channels are described: +whether they are RGB or YUV, integer or floating-point, the size of each channel +and their locations within the pixel memory, and the relationship between color +planes. + +For example, ``DRM_FORMAT_ARGB8888`` describes a format in which each pixel has +a single 32-bit value in memory. Alpha, red, green, and blue, color channels are +available at 8-bit precision per channel, ordered respectively from most to +least significant bits in little-endian storage. ``DRM_FORMAT_*`` is not +affected by either CPU or device endianness; the byte pattern in memory is +always as described in the format definition, which is usually little-endian. + +As a more complex example, ``DRM_FORMAT_NV12`` describes a format in which luma +and chroma YUV samples are stored in separate planes, where the chroma plane is +stored at half the resolution in both dimensions (i.e. one U/V chroma +sample is stored for each 2x2 pixel grouping). + +Format modifiers describe a translation mechanism between these per-pixel memory +samples, and the actual memory storage for the buffer. The most straightforward +modifier is ``DRM_FORMAT_MOD_LINEAR``, describing a scheme in which each plane +is laid out row-sequentially, from the top-left to the bottom-right corner. +This is considered the baseline interchange format, and most convenient for CPU +access. + +Modern hardware employs much more sophisticated access mechanisms, typically +making use of tiled access and possibly also compression. For example, the +``DRM_FORMAT_MOD_VIVANTE_TILED`` modifier describes memory storage where pixels +are stored in 4x4 blocks arranged in row-major ordering, i.e. the first tile in +a plane stores pixels (0,0) to (3,3) inclusive, and the second tile in a plane +stores pixels (4,0) to (7,3) inclusive. + +Some modifiers may modify the number of planes required for an image; for +example, the ``I915_FORMAT_MOD_Y_TILED_CCS`` modifier adds a second plane to RGB +formats in which it stores data about the status of every tile, notably +including whether the tile is fully populated with pixel data, or can be +expanded from a single solid color. + +These extended layouts are highly vendor-specific, and even specific to +particular generations or configurations of devices per-vendor. For this reason, +support of modifiers must be explicitly enumerated and negotiated by all users +in order to ensure a compatible and optimal pipeline, as discussed below. + + +Dimensions and size +=================== + +Each pixel buffer must be accompanied by logical pixel dimensions. This refers +to the number of unique samples which can be extracted from, or stored to, the +underlying memory storage. For example, even though a 1920x1080 +``DRM_FORMAT_NV12`` buffer has a luma plane containing 1920x1080 samples for the Y +component, and 960x540 samples for the U and V components, the overall buffer is +still described as having dimensions of 1920x1080. + +The in-memory storage of a buffer is not guaranteed to begin immediately at the +base address of the underlying memory, nor is it guaranteed that the memory +storage is tightly clipped to either dimension. + +Each plane must therefore be described with an ``offset`` in bytes, which will be +added to the base address of the memory storage before performing any per-pixel +calculations. This may be used to combine multiple planes into a single memory +buffer; for example, ``DRM_FORMAT_NV12`` may be stored in a single memory buffer +where the luma plane's storage begins immediately at the start of the buffer +with an offset of 0, and the chroma plane's storage follows within the same buffer +beginning from the byte offset for that plane. + +Each plane must also have a ``stride`` in bytes, expressing the offset in memory +between two contiguous row. For example, a ``DRM_FORMAT_MOD_LINEAR`` buffer +with dimensions of 1000x1000 may have been allocated as if it were 1024x1000, in +order to allow for aligned access patterns. In this case, the buffer will still +be described with a width of 1000, however the stride will be ``1024 * bpp``, +indicating that there are 24 pixels at the positive extreme of the x axis whose +values are not significant. + +Buffers may also be padded further in the y dimension, simply by allocating a +larger area than would ordinarily be required. For example, many media decoders +are not able to natively output buffers of height 1080, but instead require an +effective height of 1088 pixels. In this case, the buffer continues to be +described as having a height of 1080, with the memory allocation for each buffer +being increased to account for the extra padding. + + +Enumeration +=========== + +Every user of pixel buffers must be able to enumerate a set of supported formats +and modifiers, described together. Within KMS, this is achieved with the +``IN_FORMATS`` property on each DRM plane, listing the supported DRM formats, and +the modifiers supported for each format. In userspace, this is supported through +the `EGL_EXT_image_dma_buf_import_modifiers`_ extension entrypoints for EGL, the +`VK_EXT_image_drm_format_modifier`_ extension for Vulkan, and the +`zwp_linux_dmabuf_v1`_ extension for Wayland. + +Each of these interfaces allows users to query a set of supported +format+modifier combinations. + + +Negotiation +=========== + +It is the responsibility of userspace to negotiate an acceptable format+modifier +combination for its usage. This is performed through a simple intersection of +lists. For example, if a user wants to use Vulkan to render an image to be +displayed on a KMS plane, it must: + + - query KMS for the ``IN_FORMATS`` property for the given plane + - query Vulkan for the supported formats for its physical device, making sure + to pass the ``VkImageUsageFlagBits`` and ``VkImageCreateFlagBits`` + corresponding to the intended rendering use + - intersect these formats to determine the most appropriate one + - for this format, intersect the lists of supported modifiers for both KMS and + Vulkan, to obtain a final list of acceptable modifiers for that format + +This intersection must be performed for all usages. For example, if the user +also wishes to encode the image to a video stream, it must query the media API +it intends to use for encoding for the set of modifiers it supports, and +additionally intersect against this list. + +If the intersection of all lists is an empty list, it is not possible to share +buffers in this way, and an alternate strategy must be considered (e.g. using +CPU access routines to copy data between the different uses, with the +corresponding performance cost). + +The resulting modifier list is unsorted; the order is not significant. + + +Allocation +========== + +Once userspace has determined an appropriate format, and corresponding list of +acceptable modifiers, it must allocate the buffer. As there is no universal +buffer-allocation interface available at either kernel or userspace level, the +client makes an arbitrary choice of allocation interface such as Vulkan, GBM, or +a media API. + +Each allocation request must take, at a minimum: the pixel format, a list of +acceptable modifiers, and the buffer's width and height. Each API may extend +this set of properties in different ways, such as allowing allocation in more +than two dimensions, intended usage patterns, etc. + +The component which allocates the buffer will make an arbitrary choice of what +it considers the 'best' modifier within the acceptable list for the requested +allocation, any padding required, and further properties of the underlying +memory buffers such as whether they are stored in system or device-specific +memory, whether or not they are physically contiguous, and their cache mode. +These properties of the memory buffer are not visible to userspace, however the +``dma-heaps`` API is an effort to address this. + +After allocation, the client must query the allocator to determine the actual +modifier selected for the buffer, as well as the per-plane offset and stride. +Allocators are not permitted to vary the format in use, to select a modifier not +provided within the acceptable list, nor to vary the pixel dimensions other than +the padding expressed through offset, stride, and size. + +Communicating additional constraints, such as alignment of stride or offset, +placement within a particular memory area, etc, is out of scope of dma-buf, +and is not solved by format and modifier tokens. + + +Import +====== + +To use a buffer within a different context, device, or subsystem, the user +passes these parameters (format, modifier, width, height, and per-plane offset +and stride) to an importing API. + +Each memory buffer is referred to by a buffer handle, which may be unique or +duplicated within an image. For example, a ``DRM_FORMAT_NV12`` buffer may have +the luma and chroma buffers combined into a single memory buffer by use of the +per-plane offset parameters, or they may be completely separate allocations in +memory. For this reason, each import and allocation API must provide a separate +handle for each plane. + +Each kernel subsystem has its own types and interfaces for buffer management. +DRM uses GEM buffer objects (BOs), V4L2 has its own references, etc. These types +are not portable between contexts, processes, devices, or subsystems. + +To address this, ``dma-buf`` handles are used as the universal interchange for +buffers. Subsystem-specific operations are used to export native buffer handles +to a ``dma-buf`` file descriptor, and to import those file descriptors into a +native buffer handle. dma-buf file descriptors can be transferred between +contexts, processes, devices, and subsystems. + +For example, a Wayland media player may use V4L2 to decode a video frame into a +``DRM_FORMAT_NV12`` buffer. This will result in two memory planes (luma and +chroma) being dequeued by the user from V4L2. These planes are then exported to +one dma-buf file descriptor per plane, these descriptors are then sent along +with the metadata (format, modifier, width, height, per-plane offset and stride) +to the Wayland server. The Wayland server will then import these file +descriptors as an EGLImage for use through EGL/OpenGL (ES), a VkImage for use +through Vulkan, or a KMS framebuffer object; each of these import operations +will take the same metadata and convert the dma-buf file descriptors into their +native buffer handles. + +Having a non-empty intersection of supported modifiers does not guarantee that +import will succeed into all consumers; they may have constraints beyond those +implied by modifiers which must be satisfied. + + +Implicit modifiers +================== + +The concept of modifiers post-dates all of the subsystems mentioned above. As +such, it has been retrofitted into all of these APIs, and in order to ensure +backwards compatibility, support is needed for drivers and userspace which do +not (yet) support modifiers. + +As an example, GBM is used to allocate buffers to be shared between EGL for +rendering and KMS for display. It has two entrypoints for allocating buffers: +``gbm_bo_create`` which only takes the format, width, height, and a usage token, +and ``gbm_bo_create_with_modifiers`` which extends this with a list of modifiers. + +In the latter case, the allocation is as discussed above, being provided with a +list of acceptable modifiers that the implementation can choose from (or fail if +it is not possible to allocate within those constraints). In the former case +where modifiers are not provided, the GBM implementation must make its own +choice as to what is likely to be the 'best' layout. Such a choice is entirely +implementation-specific: some will internally use tiled layouts which are not +CPU-accessible if the implementation decides that is a good idea through +whatever heuristic. It is the implementation's responsibility to ensure that +this choice is appropriate. + +To support this case where the layout is not known because there is no awareness +of modifiers, a special ``DRM_FORMAT_MOD_INVALID`` token has been defined. This +pseudo-modifier declares that the layout is not known, and that the driver +should use its own logic to determine what the underlying layout may be. + +.. note:: + + ``DRM_FORMAT_MOD_INVALID`` is a non-zero value. The modifier value zero is + ``DRM_FORMAT_MOD_LINEAR``, which is an explicit guarantee that the image + has the linear layout. Care and attention should be taken to ensure that + zero as a default value is not mixed up with either no modifier or the linear + modifier. Also note that in some APIs the invalid modifier value is specified + with an out-of-band flag, like in ``DRM_IOCTL_MODE_ADDFB2``. + +There are four cases where this token may be used: + - during enumeration, an interface may return ``DRM_FORMAT_MOD_INVALID``, either + as the sole member of a modifier list to declare that explicit modifiers are + not supported, or as part of a larger list to declare that implicit modifiers + may be used + - during allocation, a user may supply ``DRM_FORMAT_MOD_INVALID``, either as the + sole member of a modifier list (equivalent to not supplying a modifier list + at all) to declare that explicit modifiers are not supported and must not be + used, or as part of a larger list to declare that an allocation using implicit + modifiers is acceptable + - in a post-allocation query, an implementation may return + ``DRM_FORMAT_MOD_INVALID`` as the modifier of the allocated buffer to declare + that the underlying layout is implementation-defined and that an explicit + modifier description is not available; per the above rules, this may only be + returned when the user has included ``DRM_FORMAT_MOD_INVALID`` as part of the + list of acceptable modifiers, or not provided a list + - when importing a buffer, the user may supply ``DRM_FORMAT_MOD_INVALID`` as the + buffer modifier (or not supply a modifier) to indicate that the modifier is + unknown for whatever reason; this is only acceptable when the buffer has + not been allocated with an explicit modifier + +It follows from this that for any single buffer, the complete chain of operations +formed by the producer and all the consumers must be either fully implicit or fully +explicit. For example, if a user wishes to allocate a buffer for use between +GPU, display, and media, but the media API does not support modifiers, then the +user **must not** allocate the buffer with explicit modifiers and attempt to +import the buffer into the media API with no modifier, but either perform the +allocation using implicit modifiers, or allocate the buffer for media use +separately and copy between the two buffers. + +As one exception to the above, allocations may be 'upgraded' from implicit +to explicit modifiers. For example, if the buffer is allocated with +``gbm_bo_create`` (taking no modifiers), the user may then query the modifier with +``gbm_bo_get_modifier`` and then use this modifier as an explicit modifier token +if a valid modifier is returned. + +When allocating buffers for exchange between different users and modifiers are +not available, implementations are strongly encouraged to use +``DRM_FORMAT_MOD_LINEAR`` for their allocation, as this is the universal baseline +for exchange. However, it is not guaranteed that this will result in the correct +interpretation of buffer content, as implicit modifier operation may still be +subject to driver-specific heuristics. + +Any new users - userspace programs and protocols, kernel subsystems, etc - +wishing to exchange buffers must offer interoperability through dma-buf file +descriptors for memory planes, DRM format tokens to describe the format, DRM +format modifiers to describe the layout in memory, at least width and height for +dimensions, and at least offset and stride for each memory plane. + +.. _zwp_linux_dmabuf_v1: https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml +.. _VK_EXT_image_drm_format_modifier: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_image_drm_format_modifier.html +.. _EGL_EXT_image_dma_buf_import_modifiers: https://registry.khronos.org/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index 72a65db0c498..031df47a7c19 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -22,6 +22,7 @@ place where this information is gathered. unshare spec_ctrl accelerators/ocxl + dma-buf-alloc-exchange ebpf/index ELF ioctl/index diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst index d8cd8cd9ce25..2e3822677061 100644 --- a/Documentation/userspace-api/landlock.rst +++ b/Documentation/userspace-api/landlock.rst @@ -8,13 +8,13 @@ Landlock: unprivileged access control ===================================== :Author: Mickaël Salaün -:Date: October 2022 +:Date: October 2023 The goal of Landlock is to enable to restrict ambient rights (e.g. global -filesystem access) for a set of processes. Because Landlock is a stackable -LSM, it makes possible to create safe security sandboxes as new security layers -in addition to the existing system-wide access-controls. This kind of sandbox -is expected to help mitigate the security impact of bugs or +filesystem or network access) for a set of processes. Because Landlock +is a stackable LSM, it makes possible to create safe security sandboxes as new +security layers in addition to the existing system-wide access-controls. This +kind of sandbox is expected to help mitigate the security impact of bugs or unexpected/malicious behaviors in user space applications. Landlock empowers any process, including unprivileged ones, to securely restrict themselves. @@ -28,20 +28,34 @@ appropriately <kernel_support>`. Landlock rules ============== -A Landlock rule describes an action on an object. An object is currently a -file hierarchy, and the related filesystem actions are defined with `access -rights`_. A set of rules is aggregated in a ruleset, which can then restrict +A Landlock rule describes an action on an object which the process intends to +perform. A set of rules is aggregated in a ruleset, which can then restrict the thread enforcing it, and its future children. +The two existing types of rules are: + +Filesystem rules + For these rules, the object is a file hierarchy, + and the related filesystem actions are defined with + `filesystem access rights`. + +Network rules (since ABI v4) + For these rules, the object is a TCP port, + and the related actions are defined with `network access rights`. + Defining and enforcing a security policy ---------------------------------------- -We first need to define the ruleset that will contain our rules. For this -example, the ruleset will contain rules that only allow read actions, but write -actions will be denied. The ruleset then needs to handle both of these kind of -actions. This is required for backward and forward compatibility (i.e. the -kernel and user space may not know each other's supported restrictions), hence -the need to be explicit about the denied-by-default access rights. +We first need to define the ruleset that will contain our rules. + +For this example, the ruleset will contain rules that only allow filesystem +read actions and establish a specific TCP connection. Filesystem write +actions and other TCP actions will be denied. + +The ruleset then needs to handle both these kinds of actions. This is +required for backward and forward compatibility (i.e. the kernel and user +space may not know each other's supported restrictions), hence the need +to be explicit about the denied-by-default access rights. .. code-block:: c @@ -62,6 +76,9 @@ the need to be explicit about the denied-by-default access rights. LANDLOCK_ACCESS_FS_MAKE_SYM | LANDLOCK_ACCESS_FS_REFER | LANDLOCK_ACCESS_FS_TRUNCATE, + .handled_access_net = + LANDLOCK_ACCESS_NET_BIND_TCP | + LANDLOCK_ACCESS_NET_CONNECT_TCP, }; Because we may not know on which kernel version an application will be @@ -70,9 +87,7 @@ 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 the ``LANDLOCK_ACCESS_FS_REFER`` or ``LANDLOCK_ACCESS_FS_TRUNCATE`` -access rights, which are only supported starting with the second and third -version of the ABI. +remove access rights which are only supported in higher versions of the ABI. .. code-block:: c @@ -92,6 +107,12 @@ version of the ABI. case 2: /* Removes LANDLOCK_ACCESS_FS_TRUNCATE for ABI < 3 */ ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_TRUNCATE; + __attribute__((fallthrough)); + case 3: + /* Removes network support for ABI < 4 */ + ruleset_attr.handled_access_net &= + ~(LANDLOCK_ACCESS_NET_BIND_TCP | + LANDLOCK_ACCESS_NET_CONNECT_TCP); } This enables to create an inclusive ruleset that will contain our rules. @@ -143,10 +164,23 @@ for the ruleset creation, by filtering access rights according to the Landlock ABI version. In this example, this is not required because all of the requested ``allowed_access`` rights are already available in ABI 1. -We now have a ruleset with one rule allowing read access to ``/usr`` while -denying all other handled accesses for the filesystem. The next step is to -restrict the current thread from gaining more privileges (e.g. thanks to a SUID -binary). +For network access-control, we can add a set of rules that allow to use a port +number for a specific action: HTTPS connections. + +.. code-block:: c + + struct landlock_net_port_attr net_port = { + .allowed_access = LANDLOCK_ACCESS_NET_CONNECT_TCP, + .port = 443, + }; + + err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_NET_PORT, + &net_port, 0); + +The next step is to restrict the current thread from gaining more privileges +(e.g. through a SUID binary). We now have a ruleset with the first rule +allowing read access to ``/usr`` while denying all other handled accesses for +the filesystem, and a second rule allowing HTTPS connections. .. code-block:: c @@ -355,7 +389,7 @@ Access rights ------------- .. kernel-doc:: include/uapi/linux/landlock.h - :identifiers: fs_access + :identifiers: fs_access net_access Creating a new ruleset ---------------------- @@ -374,6 +408,7 @@ Extending a ruleset .. kernel-doc:: include/uapi/linux/landlock.h :identifiers: landlock_rule_type landlock_path_beneath_attr + landlock_net_port_attr Enforcing a ruleset ------------------- @@ -387,9 +422,9 @@ Current limitations Filesystem topology modification -------------------------------- -As for file renaming and linking, a sandboxed thread cannot modify its -filesystem topology, whether via :manpage:`mount(2)` or -:manpage:`pivot_root(2)`. However, :manpage:`chroot(2)` calls are not denied. +Threads sandboxed with filesystem restrictions cannot modify filesystem +topology, whether via :manpage:`mount(2)` or :manpage:`pivot_root(2)`. +However, :manpage:`chroot(2)` calls are not denied. Special filesystems ------------------- @@ -451,6 +486,14 @@ always allowed when using a kernel that only supports the first or second ABI. Starting with the Landlock ABI version 3, it is now possible to securely control truncation thanks to the new ``LANDLOCK_ACCESS_FS_TRUNCATE`` access right. +Network support (ABI < 4) +------------------------- + +Starting with the Landlock ABI version 4, it is now possible to restrict TCP +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. + .. _kernel_support: Kernel support @@ -469,6 +512,12 @@ still enable it by adding ``lsm=landlock,[...]`` to Documentation/admin-guide/kernel-parameters.rst thanks to the bootloader configuration. +To be able to explicitly allow TCP operations (e.g., adding a network rule with +``LANDLOCK_ACCESS_NET_BIND_TCP``), the kernel must support TCP +(``CONFIG_INET=y``). Otherwise, sys_landlock_add_rule() returns an +``EAFNOSUPPORT`` error, which can safely be ignored because this kind of TCP +operation is already not possible. + Questions and answers ===================== diff --git a/Documentation/userspace-api/media/v4l/dev-decoder.rst b/Documentation/userspace-api/media/v4l/dev-decoder.rst index 675bc2c3c6b8..ef8e8cf31f90 100644 --- a/Documentation/userspace-api/media/v4l/dev-decoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-decoder.rst @@ -277,7 +277,7 @@ Initialization other fields follow standard semantics. - * **Return fields:** + * **Returned fields:** ``sizeimage`` adjusted size of ``OUTPUT`` buffers. @@ -311,7 +311,7 @@ Initialization ``memory`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` the actual number of buffers allocated. @@ -339,7 +339,7 @@ Initialization ``format`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` adjusted to the number of allocated buffers. @@ -410,7 +410,7 @@ Capture Setup ``type`` a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. - * **Return fields:** + * **Returned fields:** ``width``, ``height`` frame buffer resolution for the decoded frames. @@ -443,7 +443,7 @@ Capture Setup ``target`` set to ``V4L2_SEL_TGT_COMPOSE``. - * **Return fields:** + * **Returned fields:** ``r.left``, ``r.top``, ``r.width``, ``r.height`` the visible rectangle; it must fit within the frame buffer resolution @@ -552,7 +552,7 @@ Capture Setup frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``; read-only on hardware without additional compose/scaling capabilities. - * **Return fields:** + * **Returned fields:** ``r.left``, ``r.top``, ``r.width``, ``r.height`` the visible rectangle; it must fit within the frame buffer resolution @@ -629,7 +629,7 @@ Capture Setup ``memory`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` actual number of buffers allocated. @@ -668,7 +668,7 @@ Capture Setup a format representing the maximum framebuffer resolution to be accommodated by newly allocated buffers. - * **Return fields:** + * **Returned fields:** ``count`` adjusted to the number of allocated buffers. diff --git a/Documentation/userspace-api/media/v4l/dev-encoder.rst b/Documentation/userspace-api/media/v4l/dev-encoder.rst index aa338b9624b0..6c523c69bdce 100644 --- a/Documentation/userspace-api/media/v4l/dev-encoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-encoder.rst @@ -115,8 +115,8 @@ Querying Capabilities 4. The client may use :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` to detect supported frame intervals for a given format and resolution, passing the desired pixel - format in :c:type:`v4l2_frmsizeenum` ``pixel_format`` and the resolution - in :c:type:`v4l2_frmsizeenum` ``width`` and :c:type:`v4l2_frmsizeenum` + format in :c:type:`v4l2_frmivalenum` ``pixel_format`` and the resolution + in :c:type:`v4l2_frmivalenum` ``width`` and :c:type:`v4l2_frmivalenum` ``height``. * Values returned by :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` for a coded pixel @@ -163,7 +163,7 @@ Initialization other fields follow standard semantics. - * **Return fields:** + * **Returned fields:** ``sizeimage`` adjusted size of ``CAPTURE`` buffers. @@ -189,7 +189,7 @@ Initialization other fields follow standard semantics. - * **Return fields:** + * **Returned fields:** ``pixelformat`` raw format supported for the coded format currently selected on @@ -215,7 +215,7 @@ Initialization other fields follow standard semantics. - * **Return fields:** + * **Returned fields:** ``width``, ``height`` may be adjusted to match encoder minimums, maximums and alignment @@ -233,7 +233,7 @@ Initialization :c:func:`VIDIOC_S_PARM`. This also sets the coded frame interval on the ``CAPTURE`` queue to the same value. - * ** Required fields:** + * **Required fields:** ``type`` a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. @@ -245,7 +245,7 @@ Initialization the desired frame interval; the encoder may adjust it to match hardware requirements. - * **Return fields:** + * **Returned fields:** ``parm.output.timeperframe`` the adjusted frame interval. @@ -284,7 +284,7 @@ Initialization the case for off-line encoding. Support for this feature is signalled by the :ref:`V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL <fmtdesc-flags>` format flag. - * ** Required fields:** + * **Required fields:** ``type`` a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. @@ -296,7 +296,7 @@ Initialization the desired coded frame interval; the encoder may adjust it to match hardware requirements. - * **Return fields:** + * **Returned fields:** ``parm.capture.timeperframe`` the adjusted frame interval. @@ -339,7 +339,7 @@ Initialization rectangle and may be subject to adjustment to match codec and hardware constraints. - * **Return fields:** + * **Returned fields:** ``r.left``, ``r.top``, ``r.width``, ``r.height`` visible rectangle adjusted by the encoder. @@ -387,7 +387,7 @@ Initialization other fields follow standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` actual number of buffers allocated. @@ -420,7 +420,7 @@ Initialization other fields follow standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` adjusted to the number of allocated buffers. diff --git a/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst b/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst index 4a26646eeec5..35ed05f2695e 100644 --- a/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst @@ -180,7 +180,7 @@ Initialization ``memory`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` actual number of buffers allocated. @@ -208,7 +208,7 @@ Initialization follows standard semantics. ``V4L2_MEMORY_USERPTR`` is not supported for ``CAPTURE`` buffers. - * **Return fields:** + * **Returned fields:** ``count`` adjusted to allocated number of buffers, in case the codec requires diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst index 81e60f4002c8..786127b1e206 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst @@ -3293,7 +3293,7 @@ AV1 Frame Restoration Type. .. c:type:: v4l2_av1_loop_restoration -AV1 Loop Restauration as described in section 6.10.15 "Loop restoration params +AV1 Loop Restoration as described in section 6.10.15 "Loop restoration params semantics" of :ref:`av1`. .. cssclass:: longtable diff --git a/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst b/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst index 541836074f94..0686413b16b2 100644 --- a/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst @@ -237,7 +237,7 @@ Fish Eye sensor: :: camera projectors. As we have another field for "Laser Power" we introduced "LED Power" for extra emitter. -The "Laser mode" __u32 fiels has been split into: :: +The "Laser mode" __u32 fields has been split into: :: 1 __u8 Emitter mode 2 __u8 RFU byte 3 __u16 LED Power diff --git a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst index 58f6ae25b2e7..296ad2025e8d 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst @@ -275,6 +275,19 @@ please make a proposal on the linux-media mailing list. Decoder's implementation can be found here, `aspeed_codec <https://github.com/AspeedTech-BMC/aspeed_codec/>`__ + * .. _V4L2-PIX-FMT-MT2110T: + + - ``V4L2_PIX_FMT_MT2110T`` + - 'MT2110T' + - This format is two-planar 10-Bit tile mode and having similitude with + ``V4L2_PIX_FMT_MM21`` in term of alignment and tiling. Used for VP9, AV1 + and HEVC. + * .. _V4L2-PIX-FMT-MT2110R: + + - ``V4L2_PIX_FMT_MT2110R`` + - 'MT2110R' + - This format is two-planar 10-Bit raster mode and having similitude with + ``V4L2_PIX_FMT_MM21`` in term of alignment and tiling. Used for AVC. .. raw:: latex \normalsize diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst index 2d6e3bbdd040..72677a280cd6 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst @@ -58,6 +58,9 @@ the subdevice exposes, drivers return the ENOSPC error code and adjust the value of the ``num_routes`` field. Application should then reserve enough memory for all the route entries and call ``VIDIOC_SUBDEV_G_ROUTING`` again. +On a successful ``VIDIOC_SUBDEV_G_ROUTING`` call the driver updates the +``num_routes`` field to reflect the actual number of routes returned. + .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_subdev_routing @@ -138,9 +141,7 @@ ENOSPC EINVAL The sink or source pad identifiers reference a non-existing pad, or reference - pads of different types (ie. the sink_pad identifiers refers to a source pad) - or the sink or source stream identifiers reference a non-existing stream on - the sink or source pad. + pads of different types (ie. the sink_pad identifiers refers to a source pad). E2BIG The application provided ``num_routes`` for ``VIDIOC_SUBDEV_S_ROUTING`` is diff --git a/Documentation/userspace-api/netlink/genetlink-legacy.rst b/Documentation/userspace-api/netlink/genetlink-legacy.rst index 802875a37a27..70a77387f6c4 100644 --- a/Documentation/userspace-api/netlink/genetlink-legacy.rst +++ b/Documentation/userspace-api/netlink/genetlink-legacy.rst @@ -8,11 +8,22 @@ This document describes the many additional quirks and properties required to describe older Generic Netlink families which form the ``genetlink-legacy`` protocol level. -The spec is a work in progress, some of the quirks are just documented -for future reference. +Specification +============= -Specification (defined) -======================= +Globals +------- + +Attributes listed directly at the root level of the spec file. + +version +~~~~~~~ + +Generic Netlink family version, default is 1. + +``version`` has historically been used to introduce family changes +which may break backwards compatibility. Since compatibility breaking changes +are generally not allowed ``version`` is very rarely used. Attribute type nests -------------------- @@ -156,16 +167,27 @@ it will be allocated 3 for the request (``a`` is the previous operation with a request section and the value of 2) and 8 for response (``c`` is the previous operation in the "from-kernel" direction). -Other quirks (todo) -=================== +Other quirks +============ Structures ---------- Legacy families can define C structures both to be used as the contents of an attribute and as a fixed message header. Structures are defined in -``definitions`` and referenced in operations or attributes. Note that -structures defined in YAML are implicitly packed according to C +``definitions`` and referenced in operations or attributes. + +members +~~~~~~~ + + - ``name`` - The attribute name of the struct member + - ``type`` - One of the scalar types ``u8``, ``u16``, ``u32``, ``u64``, ``s8``, + ``s16``, ``s32``, ``s64``, ``string``, ``binary`` or ``bitfield32``. + - ``byte-order`` - ``big-endian`` or ``little-endian`` + - ``doc``, ``enum``, ``enum-as-flags``, ``display-hint`` - Same as for + :ref:`attribute definitions <attribute_properties>` + +Note that structures defined in YAML are implicitly packed according to C conventions. For example, the following struct is 4 bytes, not 6 bytes: .. code-block:: c diff --git a/Documentation/userspace-api/netlink/index.rst b/Documentation/userspace-api/netlink/index.rst index 26f3720cb3be..62725dafbbdb 100644 --- a/Documentation/userspace-api/netlink/index.rst +++ b/Documentation/userspace-api/netlink/index.rst @@ -14,5 +14,6 @@ Netlink documentation for users. specs c-code-gen genetlink-legacy + netlink-raw See also :ref:`Documentation/core-api/netlink.rst <kernel_netlink>`. diff --git a/Documentation/userspace-api/netlink/intro.rst b/Documentation/userspace-api/netlink/intro.rst index 0955e9f203d3..7b1d401210ef 100644 --- a/Documentation/userspace-api/netlink/intro.rst +++ b/Documentation/userspace-api/netlink/intro.rst @@ -528,6 +528,8 @@ families may, however, require a larger buffer. 32kB buffer is recommended for most efficient handling of dumps (larger buffer fits more dumped objects and therefore fewer recvmsg() calls are needed). +.. _classic_netlink: + Classic Netlink =============== @@ -615,7 +617,7 @@ and ``SET``. Each object can handle all or some of those requests is defined by the 2 lowest bits of the message type, so commands for new objects would always be allocated with a stride of 4. -Each object would also have it's own fixed metadata shared by all request +Each object would also have its own fixed metadata shared by all request types (e.g. struct ifinfomsg for netdev requests, struct ifaddrmsg for address requests, struct tcmsg for qdisc requests). diff --git a/Documentation/userspace-api/netlink/netlink-raw.rst b/Documentation/userspace-api/netlink/netlink-raw.rst new file mode 100644 index 000000000000..f07fb9b9c101 --- /dev/null +++ b/Documentation/userspace-api/netlink/netlink-raw.rst @@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: BSD-3-Clause + +====================================================== +Netlink specification support for raw Netlink families +====================================================== + +This document describes the additional properties required by raw Netlink +families such as ``NETLINK_ROUTE`` which use the ``netlink-raw`` protocol +specification. + +Specification +============= + +The netlink-raw schema extends the :doc:`genetlink-legacy <genetlink-legacy>` +schema with properties that are needed to specify the protocol numbers and +multicast IDs used by raw netlink families. See :ref:`classic_netlink` for more +information. + +Globals +------- + +protonum +~~~~~~~~ + +The ``protonum`` property is used to specify the protocol number to use when +opening a netlink socket. + +.. code-block:: yaml + + # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) + + name: rt-addr + protocol: netlink-raw + protonum: 0 # part of the NETLINK_ROUTE protocol + + +Multicast group properties +-------------------------- + +value +~~~~~ + +The ``value`` property is used to specify the group ID to use for multicast +group registration. + +.. code-block:: yaml + + mcast-groups: + list: + - + name: rtnlgrp-ipv4-ifaddr + value: 5 + - + name: rtnlgrp-ipv6-ifaddr + value: 9 + - + name: rtnlgrp-mctp-ifaddr + value: 34 diff --git a/Documentation/userspace-api/netlink/specs.rst b/Documentation/userspace-api/netlink/specs.rst index 2e4acde890b7..c1b951649113 100644 --- a/Documentation/userspace-api/netlink/specs.rst +++ b/Documentation/userspace-api/netlink/specs.rst @@ -68,6 +68,10 @@ The following sections describe the properties of the most modern ``genetlink`` schema. See the documentation of :doc:`genetlink-c <c-code-gen>` for information on how C names are derived from name properties. +See also :ref:`Documentation/core-api/netlink.rst <kernel_netlink>` for +information on the Netlink specification properties that are only relevant to +the kernel space and not part of the user space API. + genetlink ========= @@ -82,11 +86,6 @@ name Name of the family. Name identifies the family in a unique way, since the Family IDs are allocated dynamically. -version -~~~~~~~ - -Generic Netlink family version, default is 1. - protocol ~~~~~~~~ @@ -180,6 +179,8 @@ attributes List of attributes in the set. +.. _attribute_properties: + Attribute properties -------------------- @@ -264,6 +265,13 @@ a C array of u32 values can be specified with ``type: binary`` and ``sub-type: u32``. Binary types and legacy array formats are described in more detail in :doc:`genetlink-legacy`. +display-hint +~~~~~~~~~~~~ + +Optional format indicator that is intended only for choosing the right +formatting mechanism when displaying values of this type. Currently supported +hints are ``hex``, ``mac``, ``fddi``, ``ipv4``, ``ipv6`` and ``uuid``. + operations ---------- @@ -395,10 +403,21 @@ This section describes the attribute types supported by the ``genetlink`` compatibility level. Refer to documentation of different levels for additional attribute types. -Scalar integer types +Common integer types -------------------- -Fixed-width integer types: +``sint`` and ``uint`` represent signed and unsigned 64 bit integers. +If the value can fit on 32 bits only 32 bits are carried in netlink +messages, otherwise full 64 bits are carried. Note that the payload +is only aligned to 4B, so the full 64 bit value may be unaligned! + +Common integer types should be preferred over fix-width types in majority +of cases. + +Fix-width integer types +----------------------- + +Fixed-width integer types include: ``u8``, ``u16``, ``u32``, ``u64``, ``s8``, ``s16``, ``s32``, ``s64``. Note that types smaller than 32 bit should be avoided as using them @@ -408,6 +427,9 @@ See :ref:`pad_type` for padding of 64 bit attributes. The payload of the attribute is the integer in host order unless ``byte-order`` specifies otherwise. +64 bit values are usually aligned by the kernel but it is recommended +that the user space is able to deal with unaligned values. + .. _pad_type: pad diff --git a/Documentation/virt/hyperv/clocks.rst b/Documentation/virt/hyperv/clocks.rst index 2da2879fad52..a56f4837d443 100644 --- a/Documentation/virt/hyperv/clocks.rst +++ b/Documentation/virt/hyperv/clocks.rst @@ -60,7 +60,7 @@ vDSO, and gettimeofday() and related system calls can execute entirely in user space. The vDSO is implemented by mapping the shared page with scale and offset values into user space. User space code performs the same algorithm of reading the TSC and -appying the scale and offset to get the constant 10 MHz clock. +applying the scale and offset to get the constant 10 MHz clock. Linux clockevents are based on Hyper-V synthetic timer 0. While Hyper-V offers 4 synthetic timers for each CPU, Linux only uses diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index c0ddd3035462..7025b3751027 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -416,6 +416,13 @@ Reads the general purpose registers from the vcpu. __u64 pc; }; + /* LoongArch */ + struct kvm_regs { + /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */ + unsigned long gpr[32]; + unsigned long pc; + }; + 4.12 KVM_SET_REGS ----------------- @@ -506,7 +513,7 @@ translation mode. ------------------ :Capability: basic -:Architectures: x86, ppc, mips, riscv +:Architectures: x86, ppc, mips, riscv, loongarch :Type: vcpu ioctl :Parameters: struct kvm_interrupt (in) :Returns: 0 on success, negative on failure. @@ -540,7 +547,7 @@ ioctl is useful if the in-kernel PIC is not used. PPC: ^^^^ -Queues an external interrupt to be injected. This ioctl is overleaded +Queues an external interrupt to be injected. This ioctl is overloaded with 3 different irq values: a) KVM_INTERRUPT_SET @@ -578,7 +585,7 @@ This is an asynchronous vcpu ioctl and can be invoked from any thread. RISC-V: ^^^^^^^ -Queues an external interrupt to be injected into the virutal CPU. This ioctl +Queues an external interrupt to be injected into the virtual CPU. This ioctl is overloaded with 2 different irq values: a) KVM_INTERRUPT_SET @@ -592,6 +599,14 @@ b) KVM_INTERRUPT_UNSET This is an asynchronous vcpu ioctl and can be invoked from any thread. +LOONGARCH: +^^^^^^^^^^ + +Queues an external interrupt to be injected into the virtual CPU. A negative +interrupt number dequeues the interrupt. + +This is an asynchronous vcpu ioctl and can be invoked from any thread. + 4.17 KVM_DEBUG_GUEST -------------------- @@ -737,7 +752,7 @@ signal mask. ---------------- :Capability: basic -:Architectures: x86 +:Architectures: x86, loongarch :Type: vcpu ioctl :Parameters: struct kvm_fpu (out) :Returns: 0 on success, -1 on error @@ -746,7 +761,7 @@ Reads the floating point state from the vcpu. :: - /* for KVM_GET_FPU and KVM_SET_FPU */ + /* x86: for KVM_GET_FPU and KVM_SET_FPU */ struct kvm_fpu { __u8 fpr[8][16]; __u16 fcw; @@ -761,12 +776,21 @@ Reads the floating point state from the vcpu. __u32 pad2; }; + /* LoongArch: for KVM_GET_FPU and KVM_SET_FPU */ + struct kvm_fpu { + __u32 fcsr; + __u64 fcc; + struct kvm_fpureg { + __u64 val64[4]; + }fpr[32]; + }; + 4.23 KVM_SET_FPU ---------------- :Capability: basic -:Architectures: x86 +:Architectures: x86, loongarch :Type: vcpu ioctl :Parameters: struct kvm_fpu (in) :Returns: 0 on success, -1 on error @@ -775,7 +799,7 @@ Writes the floating point state to the vcpu. :: - /* for KVM_GET_FPU and KVM_SET_FPU */ + /* x86: for KVM_GET_FPU and KVM_SET_FPU */ struct kvm_fpu { __u8 fpr[8][16]; __u16 fcw; @@ -790,6 +814,15 @@ Writes the floating point state to the vcpu. __u32 pad2; }; + /* LoongArch: for KVM_GET_FPU and KVM_SET_FPU */ + struct kvm_fpu { + __u32 fcsr; + __u64 fcc; + struct kvm_fpureg { + __u64 val64[4]; + }fpr[32]; + }; + 4.24 KVM_CREATE_IRQCHIP ----------------------- @@ -965,7 +998,7 @@ be set in the flags field of this ioctl: The KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL flag requests KVM to generate the contents of the hypercall page automatically; hypercalls will be intercepted and passed to userspace through KVM_EXIT_XEN. In this -ase, all of the blob size and address fields must be zero. +case, all of the blob size and address fields must be zero. The KVM_XEN_HVM_CONFIG_EVTCHN_SEND flag indicates to KVM that userspace will always use the KVM_XEN_HVM_EVTCHN_SEND ioctl to deliver event @@ -1070,7 +1103,7 @@ Other flags returned by ``KVM_GET_CLOCK`` are accepted but ignored. :Extended by: KVM_CAP_INTR_SHADOW :Architectures: x86, arm64 :Type: vcpu ioctl -:Parameters: struct kvm_vcpu_event (out) +:Parameters: struct kvm_vcpu_events (out) :Returns: 0 on success, -1 on error X86: @@ -1193,7 +1226,7 @@ directly to the virtual CPU). :Extended by: KVM_CAP_INTR_SHADOW :Architectures: x86, arm64 :Type: vcpu ioctl -:Parameters: struct kvm_vcpu_event (in) +:Parameters: struct kvm_vcpu_events (in) :Returns: 0 on success, -1 on error X86: @@ -1387,7 +1420,7 @@ documentation when it pops into existence). ------------------- :Capability: KVM_CAP_ENABLE_CAP -:Architectures: mips, ppc, s390, x86 +:Architectures: mips, ppc, s390, x86, loongarch :Type: vcpu ioctl :Parameters: struct kvm_enable_cap (in) :Returns: 0 on success; -1 on error @@ -1442,7 +1475,7 @@ for vm-wide capabilities. --------------------- :Capability: KVM_CAP_MP_STATE -:Architectures: x86, s390, arm64, riscv +:Architectures: x86, s390, arm64, riscv, loongarch :Type: vcpu ioctl :Parameters: struct kvm_mp_state (out) :Returns: 0 on success; -1 on error @@ -1460,7 +1493,7 @@ Possible values are: ========================== =============================================== KVM_MP_STATE_RUNNABLE the vcpu is currently running - [x86,arm64,riscv] + [x86,arm64,riscv,loongarch] KVM_MP_STATE_UNINITIALIZED the vcpu is an application processor (AP) which has not yet received an INIT signal [x86] KVM_MP_STATE_INIT_RECEIVED the vcpu has received an INIT signal, and is @@ -1516,11 +1549,14 @@ For riscv: The only states that are valid are KVM_MP_STATE_STOPPED and KVM_MP_STATE_RUNNABLE which reflect if the vcpu is paused or not. +On LoongArch, only the KVM_MP_STATE_RUNNABLE state is used to reflect +whether the vcpu is runnable. + 4.39 KVM_SET_MP_STATE --------------------- :Capability: KVM_CAP_MP_STATE -:Architectures: x86, s390, arm64, riscv +:Architectures: x86, s390, arm64, riscv, loongarch :Type: vcpu ioctl :Parameters: struct kvm_mp_state (in) :Returns: 0 on success; -1 on error @@ -1538,6 +1574,9 @@ For arm64/riscv: The only states that are valid are KVM_MP_STATE_STOPPED and KVM_MP_STATE_RUNNABLE which reflect if the vcpu should be paused or not. +On LoongArch, only the KVM_MP_STATE_RUNNABLE state is used to reflect +whether the vcpu is runnable. + 4.40 KVM_SET_IDENTITY_MAP_ADDR ------------------------------ @@ -2259,6 +2298,8 @@ Errors: EINVAL invalid register ID, or no such register or used with VMs in protected virtualization mode on s390 EPERM (arm64) register access not allowed before vcpu finalization + EBUSY (riscv) changing register value not allowed after the vcpu + has run at least once ====== ============================================================ (These error codes are indicative only: do not rely on a specific error @@ -2722,7 +2763,7 @@ The isa config register can be read anytime but can only be written before a Guest VCPU runs. It will have ISA feature bits matching underlying host set by default. -RISC-V core registers represent the general excution state of a Guest VCPU +RISC-V core registers represent the general execution state of a Guest VCPU and it has the following id bit patterns:: 0x8020 0000 02 <index into the kvm_riscv_core struct:24> (32bit Host) @@ -2839,6 +2880,19 @@ Following are the RISC-V D-extension registers: 0x8020 0000 0600 0020 fcsr Floating point control and status register ======================= ========= ============================================= +LoongArch registers are mapped using the lower 32 bits. The upper 16 bits of +that is the register group type. + +LoongArch csr registers are used to control guest cpu or get status of guest +cpu, and they have the following id bit patterns:: + + 0x9030 0000 0001 00 <reg:5> <sel:3> (64-bit) + +LoongArch KVM control registers are used to implement some new defined functions +such as set vcpu counter or reset vcpu, and they have the following id bit patterns:: + + 0x9030 0000 0002 <reg:16> + 4.69 KVM_GET_ONE_REG -------------------- @@ -3061,7 +3115,7 @@ as follow:: }; An entry with a "page_shift" of 0 is unused. Because the array is -organized in increasing order, a lookup can stop when encoutering +organized in increasing order, a lookup can stop when encountering such an entry. The "slb_enc" field provides the encoding to use in the SLB for the @@ -3368,6 +3422,8 @@ return indicates the attribute is implemented. It does not necessarily indicate that the attribute can be read or written in the device's current state. "addr" is ignored. +.. _KVM_ARM_VCPU_INIT: + 4.82 KVM_ARM_VCPU_INIT ---------------------- @@ -3453,7 +3509,7 @@ Possible features: - KVM_RUN and KVM_GET_REG_LIST are not available; - KVM_GET_ONE_REG and KVM_SET_ONE_REG cannot be used to access - the scalable archietctural SVE registers + the scalable architectural SVE registers KVM_REG_ARM64_SVE_ZREG(), KVM_REG_ARM64_SVE_PREG() or KVM_REG_ARM64_SVE_FFR; @@ -3499,7 +3555,7 @@ VCPU matching underlying host. --------------------- :Capability: basic -:Architectures: arm64, mips +:Architectures: arm64, mips, riscv :Type: vcpu ioctl :Parameters: struct kvm_reg_list (in/out) :Returns: 0 on success; -1 on error @@ -4399,7 +4455,7 @@ This will have undefined effects on the guest if it has not already placed itself in a quiescent state where no vcpu will make MMU enabled memory accesses. -On succsful completion, the pending HPT will become the guest's active +On successful completion, the pending HPT will become the guest's active HPT and the previous HPT will be discarded. On failure, the guest will still be operating on its previous HPT. @@ -5014,7 +5070,7 @@ before the vcpu is fully usable. Between KVM_ARM_VCPU_INIT and KVM_ARM_VCPU_FINALIZE, the feature may be configured by use of ioctls such as KVM_SET_ONE_REG. The exact configuration -that should be performaned and how to do it are feature-dependent. +that should be performed and how to do it are feature-dependent. Other calls that depend on a particular feature being finalized, such as KVM_RUN, KVM_GET_REG_LIST, KVM_GET_ONE_REG and KVM_SET_ONE_REG, will fail with @@ -5122,6 +5178,24 @@ Valid values for 'action':: #define KVM_PMU_EVENT_ALLOW 0 #define KVM_PMU_EVENT_DENY 1 +Via this API, KVM userspace can also control the behavior of the VM's fixed +counters (if any) by configuring the "action" and "fixed_counter_bitmap" fields. + +Specifically, KVM follows the following pseudo-code when determining whether to +allow the guest FixCtr[i] to count its pre-defined fixed event:: + + FixCtr[i]_is_allowed = (action == ALLOW) && (bitmap & BIT(i)) || + (action == DENY) && !(bitmap & BIT(i)); + FixCtr[i]_is_denied = !FixCtr[i]_is_allowed; + +KVM always consumes fixed_counter_bitmap, it's userspace's responsibility to +ensure fixed_counter_bitmap is set correctly, e.g. if userspace wants to define +a filter that only affects general purpose counters. + +Note, the "events" field also applies to fixed counters' hardcoded event_select +and unit_mask values. "fixed_counter_bitmap" has higher priority than "events" +if there is a contradiction between the two. + 4.121 KVM_PPC_SVM_OFF --------------------- @@ -5232,7 +5306,7 @@ KVM_PV_DISABLE Deregister the VM from the Ultravisor and reclaim the memory that had been donated to the Ultravisor, making it usable by the kernel again. All registered VCPUs are converted back to non-protected ones. If a - previous protected VM had been prepared for asynchonous teardown with + previous protected VM had been prepared for asynchronous teardown with KVM_PV_ASYNC_CLEANUP_PREPARE and not subsequently torn down with KVM_PV_ASYNC_CLEANUP_PERFORM, it will be torn down in this call together with the current protected VM. @@ -5473,7 +5547,7 @@ KVM_XEN_ATTR_TYPE_EVTCHN from the guest. A given sending port number may be directed back to a specified vCPU (by APIC ID) / port / priority on the guest, or to trigger events on an eventfd. The vCPU and priority can be changed - by setting KVM_XEN_EVTCHN_UPDATE in a subsequent call, but but other + by setting KVM_XEN_EVTCHN_UPDATE in a subsequent call, but other fields cannot change for a given sending port. A port mapping is removed by using KVM_XEN_EVTCHN_DEASSIGN in the flags field. Passing KVM_XEN_EVTCHN_RESET in the flags field removes all interception of @@ -5692,7 +5766,7 @@ flags values for ``kvm_sregs2``: ``KVM_SREGS2_FLAGS_PDPTRS_VALID`` - Indicates thats the struct contain valid PDPTR values. + Indicates that the struct contains valid PDPTR values. 4.132 KVM_SET_SREGS2 @@ -6068,6 +6142,56 @@ writes to the CNTVCT_EL0 and CNTPCT_EL0 registers using the SET_ONE_REG interface. No error will be returned, but the resulting offset will not be applied. +.. _KVM_ARM_GET_REG_WRITABLE_MASKS: + +4.139 KVM_ARM_GET_REG_WRITABLE_MASKS +------------------------------------------- + +:Capability: KVM_CAP_ARM_SUPPORTED_REG_MASK_RANGES +:Architectures: arm64 +:Type: vm ioctl +:Parameters: struct reg_mask_range (in/out) +:Returns: 0 on success, < 0 on error + + +:: + + #define KVM_ARM_FEATURE_ID_RANGE 0 + #define KVM_ARM_FEATURE_ID_RANGE_SIZE (3 * 8 * 8) + + struct reg_mask_range { + __u64 addr; /* Pointer to mask array */ + __u32 range; /* Requested range */ + __u32 reserved[13]; + }; + +This ioctl copies the writable masks for a selected range of registers to +userspace. + +The ``addr`` field is a pointer to the destination array where KVM copies +the writable masks. + +The ``range`` field indicates the requested range of registers. +``KVM_CHECK_EXTENSION`` for the ``KVM_CAP_ARM_SUPPORTED_REG_MASK_RANGES`` +capability returns the supported ranges, expressed as a set of flags. Each +flag's bit index represents a possible value for the ``range`` field. +All other values are reserved for future use and KVM may return an error. + +The ``reserved[13]`` array is reserved for future use and should be 0, or +KVM may return an error. + +KVM_ARM_FEATURE_ID_RANGE (0) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Feature ID range is defined as the AArch64 System register space with +op0==3, op1=={0, 1, 3}, CRn==0, CRm=={0-7}, op2=={0-7}. + +The mask returned array pointed to by ``addr`` is indexed by the macro +``ARM64_FEATURE_ID_RANGE_IDX(op0, op1, crn, crm, op2)``, allowing userspace +to know what fields can be changed for the system register described by +``op0, op1, crn, crm, op2``. KVM rejects ID register values that describe a +superset of the features supported by the system. + 5. The kvm_run structure ======================== @@ -6263,7 +6387,7 @@ to the byte array. It is strongly recommended that userspace use ``KVM_EXIT_IO`` (x86) or ``KVM_EXIT_MMIO`` (all except s390) to implement functionality that -requires a guest to interact with host userpace. +requires a guest to interact with host userspace. .. note:: KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO. @@ -6336,7 +6460,7 @@ s390 specific. } s390_ucontrol; s390 specific. A page fault has occurred for a user controlled virtual -machine (KVM_VM_S390_UNCONTROL) on it's host page table that cannot be +machine (KVM_VM_S390_UNCONTROL) on its host page table that cannot be resolved by the kernel. The program code and the translation exception code that were placed in the cpu's lowcore are presented here as defined by the z Architecture @@ -7510,7 +7634,7 @@ APIC/MSRs/etc). attribute is not supported by KVM. KVM_CAP_SGX_ATTRIBUTE enables a userspace VMM to grant a VM access to one or -more priveleged enclave attributes. args[0] must hold a file handle to a valid +more privileged enclave attributes. args[0] must hold a file handle to a valid SGX attribute file corresponding to an attribute that is supported/restricted by KVM (currently only PROVISIONKEY). @@ -7928,7 +8052,7 @@ writing to the respective MSRs. This capability indicates that userspace can load HV_X64_MSR_VP_INDEX msr. Its value is used to denote the target vcpu for a SynIC interrupt. For -compatibilty, KVM initializes this msr to KVM's internal vcpu index. When this +compatibility, KVM initializes this msr to KVM's internal vcpu index. When this capability is absent, userspace can still query this msr's value. 8.13 KVM_CAP_S390_AIS_MIGRATION @@ -8118,10 +8242,10 @@ regardless of what has actually been exposed through the CPUID leaf. :Parameters: args[0] - size of the dirty log ring KVM is capable of tracking dirty memory using ring buffers that are -mmaped into userspace; there is one dirty ring per vcpu. +mmapped into userspace; there is one dirty ring per vcpu. The dirty ring is available to userspace as an array of -``struct kvm_dirty_gfn``. Each dirty entry it's defined as:: +``struct kvm_dirty_gfn``. Each dirty entry is defined as:: struct kvm_dirty_gfn { __u32 flags; @@ -8160,7 +8284,7 @@ state machine for the entry is as follows:: | | +------------------------------------------+ -To harvest the dirty pages, userspace accesses the mmaped ring buffer +To harvest the dirty pages, userspace accesses the mmapped ring buffer to read the dirty GFNs. If the flags has the DIRTY bit set (at this stage the RESET bit must be cleared), then it means this GFN is a dirty GFN. The userspace should harvest this GFN and mark the flags from state @@ -8286,7 +8410,7 @@ the KVM_XEN_ATTR_TYPE_RUNSTATE_UPDATE_FLAG attribute in the KVM_XEN_SET_ATTR and KVM_XEN_GET_ATTR ioctls. This controls whether KVM will set the XEN_RUNSTATE_UPDATE flag in guest memory mapped vcpu_runstate_info during updates of the runstate information. Note that versions of KVM which support -the RUNSTATE feature above, but not thie RUNSTATE_UPDATE_FLAG feature, will +the RUNSTATE feature above, but not the RUNSTATE_UPDATE_FLAG feature, will always set the XEN_RUNSTATE_UPDATE flag when updating the guest structure, which is perhaps counterintuitive. When this flag is advertised, KVM will behave more correctly, not using the XEN_RUNSTATE_UPDATE flag until/unless @@ -8335,7 +8459,7 @@ Architectures: x86 When enabled, KVM will disable emulated Hyper-V features provided to the guest according to the bits Hyper-V CPUID feature leaves. Otherwise, all -currently implmented Hyper-V features are provided unconditionally when +currently implemented Hyper-V features are provided unconditionally when Hyper-V identification is set in the HYPERV_CPUID_INTERFACE (0x40000001) leaf. diff --git a/Documentation/virt/kvm/arm/index.rst b/Documentation/virt/kvm/arm/index.rst index e84848432158..7f231c724e16 100644 --- a/Documentation/virt/kvm/arm/index.rst +++ b/Documentation/virt/kvm/arm/index.rst @@ -11,3 +11,4 @@ ARM hypercalls pvtime ptp_kvm + vcpu-features diff --git a/Documentation/virt/kvm/arm/vcpu-features.rst b/Documentation/virt/kvm/arm/vcpu-features.rst new file mode 100644 index 000000000000..f7cc6d8d8b74 --- /dev/null +++ b/Documentation/virt/kvm/arm/vcpu-features.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============================== +vCPU feature selection on arm64 +=============================== + +KVM/arm64 provides two mechanisms that allow userspace to configure +the CPU features presented to the guest. + +KVM_ARM_VCPU_INIT +================= + +The ``KVM_ARM_VCPU_INIT`` ioctl accepts a bitmap of feature flags +(``struct kvm_vcpu_init::features``). Features enabled by this interface are +*opt-in* and may change/extend UAPI. See :ref:`KVM_ARM_VCPU_INIT` for complete +documentation of the features controlled by the ioctl. + +Otherwise, all CPU features supported by KVM are described by the architected +ID registers. + +The ID Registers +================ + +The Arm architecture specifies a range of *ID Registers* that describe the set +of architectural features supported by the CPU implementation. KVM initializes +the guest's ID registers to the maximum set of CPU features supported by the +system. The ID register values may be VM-scoped in KVM, meaning that the +values could be shared for all vCPUs in a VM. + +KVM allows userspace to *opt-out* of certain CPU features described by the ID +registers by writing values to them via the ``KVM_SET_ONE_REG`` ioctl. The ID +registers are mutable until the VM has started, i.e. userspace has called +``KVM_RUN`` on at least one vCPU in the VM. Userspace can discover what fields +are mutable in the ID registers using the ``KVM_ARM_GET_REG_WRITABLE_MASKS``. +See the :ref:`ioctl documentation <KVM_ARM_GET_REG_WRITABLE_MASKS>` for more +details. + +Userspace is allowed to *limit* or *mask* CPU features according to the rules +outlined by the architecture in DDI0487J.a D19.1.3 'Principles of the ID +scheme for fields in ID register'. KVM does not allow ID register values that +exceed the capabilities of the system. + +.. warning:: + It is **strongly recommended** that userspace modify the ID register values + before accessing the rest of the vCPU's CPU register state. KVM may use the + ID register values to control feature emulation. Interleaving ID register + modification with other system register accesses may lead to unpredictable + behavior. diff --git a/Documentation/virt/kvm/devices/arm-vgic-v3.rst b/Documentation/virt/kvm/devices/arm-vgic-v3.rst index 51e5e5762571..5817edb4e046 100644 --- a/Documentation/virt/kvm/devices/arm-vgic-v3.rst +++ b/Documentation/virt/kvm/devices/arm-vgic-v3.rst @@ -59,6 +59,13 @@ Groups: It is invalid to mix calls with KVM_VGIC_V3_ADDR_TYPE_REDIST and KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION attributes. + Note that to obtain reproducible results (the same VCPU being associated + with the same redistributor across a save/restore operation), VCPU creation + order, redistributor region creation order as well as the respective + interleaves of VCPU and region creation MUST be preserved. Any change in + either ordering may result in a different vcpu_id/redistributor association, + resulting in a VM that will fail to run at restore time. + Errors: ======= ============================================================= diff --git a/Documentation/virt/kvm/devices/vfio.rst b/Documentation/virt/kvm/devices/vfio.rst index 08b544212638..c549143bb891 100644 --- a/Documentation/virt/kvm/devices/vfio.rst +++ b/Documentation/virt/kvm/devices/vfio.rst @@ -9,22 +9,34 @@ Device types supported: - KVM_DEV_TYPE_VFIO Only one VFIO instance may be created per VM. The created device -tracks VFIO groups in use by the VM and features of those groups -important to the correctness and acceleration of the VM. As groups -are enabled and disabled for use by the VM, KVM should be updated -about their presence. When registered with KVM, a reference to the -VFIO-group is held by KVM. +tracks VFIO files (group or device) in use by the VM and features +of those groups/devices important to the correctness and acceleration +of the VM. As groups/devices are enabled and disabled for use by the +VM, KVM should be updated about their presence. When registered with +KVM, a reference to the VFIO file is held by KVM. Groups: - KVM_DEV_VFIO_GROUP - -KVM_DEV_VFIO_GROUP attributes: - KVM_DEV_VFIO_GROUP_ADD: Add a VFIO group to VFIO-KVM device tracking - kvm_device_attr.addr points to an int32_t file descriptor - for the VFIO group. - KVM_DEV_VFIO_GROUP_DEL: Remove a VFIO group from VFIO-KVM device tracking - kvm_device_attr.addr points to an int32_t file descriptor - for the VFIO group. + KVM_DEV_VFIO_FILE + alias: KVM_DEV_VFIO_GROUP + +KVM_DEV_VFIO_FILE attributes: + KVM_DEV_VFIO_FILE_ADD: Add a VFIO file (group/device) to VFIO-KVM device + tracking + + kvm_device_attr.addr points to an int32_t file descriptor for the + VFIO file. + + KVM_DEV_VFIO_FILE_DEL: Remove a VFIO file (group/device) from VFIO-KVM + device tracking + + kvm_device_attr.addr points to an int32_t file descriptor for the + VFIO file. + +KVM_DEV_VFIO_GROUP (legacy kvm device group restricted to the handling of VFIO group fd): + KVM_DEV_VFIO_GROUP_ADD: same as KVM_DEV_VFIO_FILE_ADD for group fd only + + KVM_DEV_VFIO_GROUP_DEL: same as KVM_DEV_VFIO_FILE_DEL for group fd only + KVM_DEV_VFIO_GROUP_SET_SPAPR_TCE: attaches a guest visible TCE table allocated by sPAPR KVM. kvm_device_attr.addr points to a struct:: @@ -40,7 +52,10 @@ KVM_DEV_VFIO_GROUP attributes: - @tablefd is a file descriptor for a TCE table allocated via KVM_CREATE_SPAPR_TCE. -The GROUP_ADD operation above should be invoked prior to accessing the +The FILE/GROUP_ADD operation above should be invoked prior to accessing the device file descriptor via VFIO_GROUP_GET_DEVICE_FD in order to support drivers which require a kvm pointer to be set in their .open_device() -callback. +callback. It is the same for device file descriptor via character device +open which gets device access via VFIO_DEVICE_BIND_IOMMUFD. For such file +descriptors, FILE_ADD should be invoked before VFIO_DEVICE_BIND_IOMMUFD +to support the drivers mentioned in prior sentence as well. diff --git a/Documentation/virt/kvm/devices/vm.rst b/Documentation/virt/kvm/devices/vm.rst index 9d726e60ec47..a4d39fa1b083 100644 --- a/Documentation/virt/kvm/devices/vm.rst +++ b/Documentation/virt/kvm/devices/vm.rst @@ -92,7 +92,7 @@ Allows user space to retrieve or request to change cpu related information for a KVM does not enforce or limit the cpu model data in any form. Take the information retrieved by means of KVM_S390_VM_CPU_MACHINE as hint for reasonable configuration setups. Instruction interceptions triggered by additionally set facility bits that -are not handled by KVM need to by imlemented in the VM driver code. +are not handled by KVM need to by implemented in the VM driver code. :Parameters: address of buffer to store/set the processor related cpu data of type struct kvm_s390_vm_cpu_processor*. diff --git a/Documentation/virt/kvm/devices/xive.rst b/Documentation/virt/kvm/devices/xive.rst index 8b5e7b40bdf8..a07e16d34006 100644 --- a/Documentation/virt/kvm/devices/xive.rst +++ b/Documentation/virt/kvm/devices/xive.rst @@ -50,7 +50,7 @@ the legacy interrupt mode, referred as XICS (POWER7/8). When a device is passed-through into the guest, the source interrupts are from a different HW controller (PHB4) and the ESB - pages exposed to the guest should accommadate this change. + pages exposed to the guest should accommodate this change. The passthru_irq helpers, kvmppc_xive_set_mapped() and kvmppc_xive_clr_mapped() are called when the device HW irqs are diff --git a/Documentation/virt/kvm/halt-polling.rst b/Documentation/virt/kvm/halt-polling.rst index 4f1a1b23d99c..c82a04b709b4 100644 --- a/Documentation/virt/kvm/halt-polling.rst +++ b/Documentation/virt/kvm/halt-polling.rst @@ -14,7 +14,7 @@ before giving up the cpu to the scheduler in order to let something else run. Polling provides a latency advantage in cases where the guest can be run again very quickly by at least saving us a trip through the scheduler, normally on the order of a few micro-seconds, although performance benefits are workload -dependant. In the event that no wakeup source arrives during the polling +dependent. In the event that no wakeup source arrives during the polling interval or some other task on the runqueue is runnable the scheduler is invoked. Thus halt polling is especially useful on workloads with very short wakeup periods where the time spent halt polling is minimised and the time diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst index 26f62034b6f3..2b3b6d442302 100644 --- a/Documentation/virt/kvm/x86/mmu.rst +++ b/Documentation/virt/kvm/x86/mmu.rst @@ -202,10 +202,22 @@ Shadow pages contain the following information: Is 1 if the MMU instance cannot use A/D bits. EPT did not have A/D bits before Haswell; shadow EPT page tables also cannot use A/D bits if the L1 hypervisor does not enable them. + role.guest_mode: + Indicates the shadow page is created for a nested guest. role.passthrough: The page is not backed by a guest page table, but its first entry points to one. This is set if NPT uses 5-level page tables (host CR4.LA57=1) and is shadowing L1's 4-level NPT (L1 CR4.LA57=0). + mmu_valid_gen: + The MMU generation of this page, used to fast zap of all MMU pages within a + VM without blocking vCPUs too long. Specifically, KVM updates the per-VM + valid MMU generation which causes the mismatch of mmu_valid_gen for each mmu + page. This makes all existing MMU pages obsolete. Obsolete pages can't be + used. Therefore, vCPUs must load a new, valid root before re-entering the + guest. The MMU generation is only ever '0' or '1'. Note, the TDP MMU doesn't + use this field as non-root TDP MMU pages are reachable only from their + owning root. Thus it suffices for TDP MMU to use role.invalid in root pages + to invalidate all MMU pages. gfn: Either the guest page table containing the translations shadowed by this page, or the base page frame for linear translations. See role.direct. @@ -219,21 +231,30 @@ Shadow pages contain the following information: at __pa(sp2->spt). sp2 will point back at sp1 through parent_pte. The spt array forms a DAG structure with the shadow page as a node, and guest pages as leaves. - gfns: - An array of 512 guest frame numbers, one for each present pte. Used to - perform a reverse map from a pte to a gfn. When role.direct is set, any - element of this array can be calculated from the gfn field when used, in - this case, the array of gfns is not allocated. See role.direct and gfn. - root_count: - A counter keeping track of how many hardware registers (guest cr3 or - pdptrs) are now pointing at the page. While this counter is nonzero, the - page cannot be destroyed. See role.invalid. + shadowed_translation: + An array of 512 shadow translation entries, one for each present pte. Used + to perform a reverse map from a pte to a gfn as well as its access + permission. When role.direct is set, the shadow_translation array is not + allocated. This is because the gfn contained in any element of this array + can be calculated from the gfn field when used. In addition, when + role.direct is set, KVM does not track access permission for each of the + gfn. See role.direct and gfn. + root_count / tdp_mmu_root_count: + root_count is a reference counter for root shadow pages in Shadow MMU. + vCPUs elevate the refcount when getting a shadow page that will be used as + a root page, i.e. page that will be loaded into hardware directly (CR3, + PDPTRs, nCR3 EPTP). Root pages cannot be destroyed while their refcount is + non-zero. See role.invalid. tdp_mmu_root_count is similar but exclusively + used in TDP MMU as an atomic refcount. parent_ptes: The reverse mapping for the pte/ptes pointing at this page's spt. If parent_ptes bit 0 is zero, only one spte points at this page and parent_ptes points at this single spte, otherwise, there exists multiple sptes pointing at this page and (parent_ptes & ~0x1) points at a data structure with a list of parent sptes. + ptep: + The kernel virtual address of the SPTE that points at this shadow page. + Used exclusively by the TDP MMU, this field is a union with parent_ptes. unsync: If true, then the translations in this page may not match the guest's translation. This is equivalent to the state of the tlb when a pte is @@ -245,7 +266,7 @@ Shadow pages contain the following information: unsynchronized children). unsync_child_bitmap: A bitmap indicating which sptes in spt point (directly or indirectly) at - pages that may be unsynchronized. Used to quickly locate all unsychronized + pages that may be unsynchronized. Used to quickly locate all unsynchronized pages reachable from a given page. clear_spte_count: Only present on 32-bit hosts, where a 64-bit spte cannot be written @@ -261,6 +282,10 @@ Shadow pages contain the following information: since the last time the page table was actually used; if emulation is triggered too frequently on this page, KVM will unmap the page to avoid emulation in the future. + tdp_mmu_page: + Is 1 if the shadow page is a TDP MMU page. This variable is used to + bifurcate the control flows for KVM when walking any data structure that + may contain pages from both TDP MMU and shadow MMU. Reverse map =========== diff --git a/Documentation/virt/kvm/x86/running-nested-guests.rst b/Documentation/virt/kvm/x86/running-nested-guests.rst index 71136fe1723b..87326413d5c7 100644 --- a/Documentation/virt/kvm/x86/running-nested-guests.rst +++ b/Documentation/virt/kvm/x86/running-nested-guests.rst @@ -169,7 +169,7 @@ Enabling "nested" (s390x) $ modprobe kvm nested=1 .. note:: On s390x, the kernel parameter ``hpage`` is mutually exclusive - with the ``nested`` paramter — i.e. to be able to enable + with the ``nested`` parameter — i.e. to be able to enable ``nested``, the ``hpage`` parameter *must* be disabled. 2. The guest hypervisor (L1) must be provided with the ``sie`` CPU diff --git a/Documentation/virt/uml/user_mode_linux_howto_v2.rst b/Documentation/virt/uml/user_mode_linux_howto_v2.rst index af2a97429692..d1cfe415e4c4 100644 --- a/Documentation/virt/uml/user_mode_linux_howto_v2.rst +++ b/Documentation/virt/uml/user_mode_linux_howto_v2.rst @@ -1224,7 +1224,7 @@ between a driver and the host at the UML command line is OK security-wise. Allowing it as a loadable module parameter isn't. -If such functionality is desireable for a particular application +If such functionality is desirable for a particular application (e.g. loading BPF "firmware" for raw socket network transports), it should be off by default and should be explicitly turned on as a command line parameter at startup. diff --git a/Documentation/w1/slaves/w1_therm.rst b/Documentation/w1/slaves/w1_therm.rst index 758dadba84f6..6aec04dd0905 100644 --- a/Documentation/w1/slaves/w1_therm.rst +++ b/Documentation/w1/slaves/w1_therm.rst @@ -58,7 +58,7 @@ A strong pullup will be applied during the conversion if required. ``conv_time`` is used to get current conversion time (read), and adjust it (write). A temperature conversion time depends on the device type and -it's current resolution. Default conversion time is set by the driver according +its current resolution. Default conversion time is set by the driver according to the device datasheet. A conversion time for many original device clones deviate from datasheet specs. There are three options: 1) manually set the correct conversion time by writing a value in milliseconds to ``conv_time``; 2) diff --git a/Documentation/w1/w1-generic.rst b/Documentation/w1/w1-generic.rst index 99255b6d0e53..96a042585fce 100644 --- a/Documentation/w1/w1-generic.rst +++ b/Documentation/w1/w1-generic.rst @@ -101,7 +101,7 @@ w1_master_search (rw) the number of searches left to do, w1_master_slave_count (ro) the number of slaves found w1_master_slaves (ro) the names of the slaves, one per line w1_master_timeout (ro) the delay in seconds between searches -w1_master_timeout_us (ro) the delay in microseconds beetwen searches +w1_master_timeout_us (ro) the delay in microseconds between searches ========================= ===================================================== If you have a w1 bus that never changes (you don't add or remove devices), diff --git a/Documentation/w1/w1-netlink.rst b/Documentation/w1/w1-netlink.rst index aaa13243a5e4..be4f7b82dcb4 100644 --- a/Documentation/w1/w1-netlink.rst +++ b/Documentation/w1/w1-netlink.rst @@ -66,7 +66,7 @@ Each connector message can include one or more w1_netlink_msg with zero or more attached w1_netlink_cmd messages. For event messages there are no w1_netlink_cmd embedded structures, -only connector header and w1_netlink_msg strucutre with "len" field +only connector header and w1_netlink_msg structure with "len" field being zero and filled type (one of event types) and id: either 8 bytes of slave unique id in host order, or master's id, which is assigned to bus master device diff --git a/Documentation/watchdog/watchdog-kernel-api.rst b/Documentation/watchdog/watchdog-kernel-api.rst index baf44e986b07..243231fe4c0a 100644 --- a/Documentation/watchdog/watchdog-kernel-api.rst +++ b/Documentation/watchdog/watchdog-kernel-api.rst @@ -77,7 +77,7 @@ It contains following fields: * groups: List of sysfs attribute groups to create when creating the watchdog device. * info: a pointer to a watchdog_info structure. This structure gives some - additional information about the watchdog timer itself. (Like it's unique name) + additional information about the watchdog timer itself. (Like its unique name) * ops: a pointer to the list of watchdog operations that the watchdog supports. * gov: a pointer to the assigned watchdog device pretimeout governor or NULL. * timeout: the watchdog timer's timeout value (in seconds). diff --git a/Documentation/wmi/devices/dell-wmi-ddv.rst b/Documentation/wmi/devices/dell-wmi-ddv.rst index d8aa64e9c827..2fcdfcf03327 100644 --- a/Documentation/wmi/devices/dell-wmi-ddv.rst +++ b/Documentation/wmi/devices/dell-wmi-ddv.rst @@ -185,9 +185,10 @@ Performs an analysis of the battery and returns a status code: WMI method BatteryeRawAnalytics() --------------------------------- -Returns a buffer usually containg 12 blocks of analytics data. +Returns a buffer usually containing 12 blocks of analytics data. Those blocks contain: -- block number starting with 0 (u8) + +- a block number starting with 0 (u8) - 31 bytes of unknown data .. note:: @@ -217,7 +218,7 @@ Returns the WMI interface version as an u32. WMI method FanSensorInformation() --------------------------------- -Returns a buffer containg fan sensor entries, terminated +Returns a buffer containing fan sensor entries, terminated with a single ``0xff``. Those entries contain: |
