diff options
Diffstat (limited to 'Documentation')
1102 files changed, 34682 insertions, 9849 deletions
diff --git a/Documentation/ABI/stable/sysfs-block b/Documentation/ABI/stable/sysfs-block index cd14ecb3c9a5..ac1e519272aa 100644 --- a/Documentation/ABI/stable/sysfs-block +++ b/Documentation/ABI/stable/sysfs-block @@ -432,7 +432,8 @@ Contact: linux-block@vger.kernel.org Description: [RW] This is the maximum number of kilobytes that the block layer will allow for a filesystem request. Must be smaller than - or equal to the maximum size allowed by the hardware. + or equal to the maximum size allowed by the hardware. Write 0 + to use default kernel settings. What: /sys/block/<disk>/queue/max_segment_size diff --git a/Documentation/ABI/stable/sysfs-devices-node b/Documentation/ABI/stable/sysfs-devices-node index 8db67aa472f1..402af4b2b905 100644 --- a/Documentation/ABI/stable/sysfs-devices-node +++ b/Documentation/ABI/stable/sysfs-devices-node @@ -182,3 +182,42 @@ Date: November 2021 Contact: Jarkko Sakkinen <jarkko@kernel.org> Description: The total amount of SGX physical memory in bytes. + +What: /sys/devices/system/node/nodeX/memory_failure/total +Date: January 2023 +Contact: Jiaqi Yan <jiaqiyan@google.com> +Description: + The total number of raw poisoned pages (pages containing + corrupted data due to memory errors) on a NUMA node. + +What: /sys/devices/system/node/nodeX/memory_failure/ignored +Date: January 2023 +Contact: Jiaqi Yan <jiaqiyan@google.com> +Description: + Of the raw poisoned pages on a NUMA node, how many pages are + ignored by memory error recovery attempt, usually because + support for this type of pages is unavailable, and kernel + gives up the recovery. + +What: /sys/devices/system/node/nodeX/memory_failure/failed +Date: January 2023 +Contact: Jiaqi Yan <jiaqiyan@google.com> +Description: + Of the raw poisoned pages on a NUMA node, how many pages are + failed by memory error recovery attempt. This usually means + a key recovery operation failed. + +What: /sys/devices/system/node/nodeX/memory_failure/delayed +Date: January 2023 +Contact: Jiaqi Yan <jiaqiyan@google.com> +Description: + Of the raw poisoned pages on a NUMA node, how many pages are + delayed by memory error recovery attempt. Delayed poisoned + pages usually will be retried by kernel. + +What: /sys/devices/system/node/nodeX/memory_failure/recovered +Date: January 2023 +Contact: Jiaqi Yan <jiaqiyan@google.com> +Description: + Of the raw poisoned pages on a NUMA node, how many pages are + recovered by memory error recovery attempt. diff --git a/Documentation/ABI/stable/sysfs-driver-mlxreg-io b/Documentation/ABI/stable/sysfs-driver-mlxreg-io index af0cbf143c48..60953903d007 100644 --- a/Documentation/ABI/stable/sysfs-driver-mlxreg-io +++ b/Documentation/ABI/stable/sysfs-driver-mlxreg-io @@ -522,7 +522,6 @@ Description: These files allow to each of ASICs by writing 1. The files are write only. - What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/comm_chnl_ready Date: July 2022 KernelVersion: 5.20 @@ -542,3 +541,124 @@ Description: The file indicates COME module hardware configuration. The purpose is to expose some minor BOM changes for the same system SKU. The file is read only. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_pwr_converter_fail +Date: February 2023 +KernelVersion: 6.3 +Contact: Vadim Pasternak <vadimp@nvidia.com> +Description: This file shows the system reset cause due to power converter + devices 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*/erot1_ap_reset +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/erot2_ap_reset +Date: February 2023 +KernelVersion: 6.3 +Contact: Vadim Pasternak <vadimp@nvidia.com> +Description: These files aim to monitor the status of the External Root of Trust (EROT) + processor's RESET output to the Application Processor (AP). + By reading this file, could be determined if the EROT has invalidated or + revoked AP Firmware, at which point it will hold the AP in RESET until a + valid firmware is loaded. This protects the AP from running an + unauthorized firmware. In the normal flow, the AP reset should be released + after the EROT validates the integrity of the FW, and it should be done so + as quickly as possible so that the AP boots before the CPU starts to + communicate to each ASIC. + + The files are read only. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/erot1_recovery +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/erot2_recovery +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/erot1_reset +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/erot2_reset +Date: February 2023 +KernelVersion: 6.3 +Contact: Vadim Pasternak <vadimp@nvidia.com> +Description: These files aim to perform External Root of Trust (EROT) recovery + sequence after EROT device failure. + These EROT devices protect ASICs from unauthorized access and in normal + flow their reset should be released with system power – earliest power + up stage, so that EROTs can begin boot and authentication process before + CPU starts to communicate to ASICs. + Issuing a reset to the EROT while asserting the recovery signal will cause + the EROT Application Processor to enter recovery mode so that the EROT FW + can be updated/recovered. + For reset/recovery the related file should be toggled by 1/0. + + The files are read/write. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/erot1_wp +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/erot2_wp +Date: February 2023 +KernelVersion: 6.3 +Contact: Vadim Pasternak <vadimp@nvidia.com> +Description: These files allow access to External Root of Trust (EROT) for reset + and recovery sequence after EROT device failure. + Default is 0 (programming disabled). + If the system is in locked-down mode writing this file will not be allowed. + + The files are read/write. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/spi_chnl_select +Date: February 2023 +KernelVersion: 6.3 +Contact: Vadim Pasternak <vadimp@nvidia.com> +Description: This file allows SPI chip selection for External Root of Trust (EROT) + device Out-of-Band recovery. + File can be written with 0 or with 1. It selects which EROT can be accessed + through SPI device. + + The file is read/write. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/asic_pg_fail +Date: February 2023 +KernelVersion: 6.3 +Contact: Vadim Pasternak vadimp@nvidia.com +Description: This file shows ASIC Power Good status. + Value 1 in file means ASIC Power Good failed, 0 - otherwise. + + The file is read only. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/clk_brd1_boot_fail +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/clk_brd2_boot_fail +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/clk_brd_fail +Date: February 2023 +KernelVersion: 6.3 +Contact: Vadim Pasternak vadimp@nvidia.com +Description: These files are related to clock boards status in system. + - clk_brd1_boot_fail: warning about 1-st clock board failed to boot from CI. + - clk_brd2_boot_fail: warning about 2-nd clock board failed to boot from CI. + - clk_brd_fail: error about common clock board boot failure. + + The files are read only. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/clk_brd_prog_en +Date: February 2023 +KernelVersion: 6.3 +Contact: Vadim Pasternak <vadimp@nvidia.com> +Description: This file enables programming of clock boards. + Default is 0 (programming disabled). + If the system is in locked-down mode writing this file will not be allowed. + + The file is read/write. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/pwr_converter_prog_en +Date: February 2023 +KernelVersion: 6.3 +Contact: Vadim Pasternak <vadimp@nvidia.com> +Description: This file enables programming of power converters. + Default is 0 (programming disabled). + If the system is in locked-down mode writing this file will not be allowed. + + The file is read/write. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_ac_ok_fail +Date: February 2023 +KernelVersion: 6.3 +Contact: Vadim Pasternak <vadimp@nvidia.com> +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. diff --git a/Documentation/ABI/stable/sysfs-hypervisor-xen b/Documentation/ABI/stable/sysfs-hypervisor-xen index 748593c64568..be9ca9981bb1 100644 --- a/Documentation/ABI/stable/sysfs-hypervisor-xen +++ b/Documentation/ABI/stable/sysfs-hypervisor-xen @@ -120,3 +120,16 @@ Contact: xen-devel@lists.xenproject.org Description: If running under Xen: The Xen version is in the format <major>.<minor><extra> This is the <minor> part of it. + +What: /sys/hypervisor/start_flags/* +Date: March 2023 +KernelVersion: 6.3.0 +Contact: xen-devel@lists.xenproject.org +Description: If running under Xen: + All bits in Xen's start-flags are represented as + boolean files, returning '1' if set, '0' otherwise. + This takes the place of the defunct /proc/xen/capabilities, + which would contain "control_d" on dom0, and be empty + otherwise. This flag is now exposed as "initdomain" in + addition to the "privileged" flag; all other possible flags + are accessible as "unknownXX". diff --git a/Documentation/ABI/testing/configfs-usb-gadget b/Documentation/ABI/testing/configfs-usb-gadget index b7943aa7e997..a8bb896def54 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget +++ b/Documentation/ABI/testing/configfs-usb-gadget @@ -143,3 +143,16 @@ Description: qw_sign an identifier to be reported as "OS String" proper ============= =============================================== + +What: /config/usb-gadget/gadget/webusb +Date: Dec 2022 +KernelVersion: 6.3 +Description: + This group contains "WebUSB" extension handling attributes. + + ============= =============================================== + use flag turning "WebUSB" support on/off + bcdVersion bcd WebUSB specification version number + bVendorCode one-byte value used for custom per-device + landingPage UTF-8 encoded URL of the device's landing page + ============= =============================================== diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uvc b/Documentation/ABI/testing/configfs-usb-gadget-uvc index f00cff6d8c5c..80b98a4a4d0f 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-uvc +++ b/Documentation/ABI/testing/configfs-usb-gadget-uvc @@ -15,12 +15,14 @@ Date: Dec 2014 KernelVersion: 4.0 Description: Control descriptors - All attributes read only: + All attributes read only except enable_interrupt_ep: - ================ ============================= + =================== ============================= bInterfaceNumber USB interface number for this streaming interface - ================ ============================= + enable_interrupt_ep flag to enable the interrupt + endpoint for the VC interface + =================== ============================= What: /config/usb-gadget/gadget/functions/uvc.name/control/class Date: Dec 2014 @@ -52,7 +54,7 @@ Date: Dec 2014 KernelVersion: 4.0 Description: Default output terminal descriptors - All attributes read only: + All attributes read only except bSourceID: ============== ============================================= iTerminal index of string descriptor @@ -111,6 +113,34 @@ Description: Default processing unit descriptors bUnitID a non-zero id of this unit =============== ======================================== +What: /config/usb-gadget/gadget/functions/uvc.name/control/extensions +Date: Nov 2022 +KernelVersion: 6.1 +Description: Extension unit descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/extensions/name +Date: Nov 2022 +KernelVersion: 6.1 +Description: Extension Unit (XU) Descriptor + + bLength, bUnitID and iExtension are read-only. All others are + read-write. + + ================= ======================================== + bLength size of the descriptor in bytes + bUnitID non-zero ID of this unit + guidExtensionCode Vendor-specific code identifying the XU + bNumControls number of controls in this XU + bNrInPins number of input pins for this unit + baSourceID list of the IDs of the units or terminals + to which this XU is connected + bControlSize size of the bmControls field in bytes + bmControls list of bitmaps detailing which vendor + specific controls are supported + iExtension index of a string descriptor that describes + this extension unit + ================= ======================================== + What: /config/usb-gadget/gadget/functions/uvc.name/control/header Date: Dec 2014 KernelVersion: 4.0 @@ -165,7 +195,24 @@ Date: Dec 2014 KernelVersion: 4.0 Description: Default color matching descriptors - All attributes read only: + All attributes read/write: + + ======================== ====================================== + bMatrixCoefficients matrix used to compute luma and + chroma values from the color primaries + bTransferCharacteristics optoelectronic transfer + characteristic of the source picture, + also called the gamma function + bColorPrimaries color primaries and the reference + white + ======================== ====================================== + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/color_matching/name +Date: Dec 2022 +KernelVersion: 6.3 +Description: Additional color matching descriptors + + All attributes read/write: ======================== ====================================== bMatrixCoefficients matrix used to compute luma and diff --git a/Documentation/ABI/testing/debugfs-pktcdvd b/Documentation/ABI/testing/debugfs-pktcdvd new file mode 100644 index 000000000000..f6f65a4faea0 --- /dev/null +++ b/Documentation/ABI/testing/debugfs-pktcdvd @@ -0,0 +1,18 @@ +What: /sys/kernel/debug/pktcdvd/pktcdvd[0-7] +Date: Oct. 2006 +KernelVersion: 2.6.20 +Contact: Thomas Maier <balagi@justmail.de> +Description: + +The pktcdvd module (packet writing driver) creates +these files in debugfs: + +/sys/kernel/debug/pktcdvd/pktcdvd[0-7]/ + + ==== ====== ==================================== + info 0444 Lots of driver statistics and infos. + ==== ====== ==================================== + +Example:: + + cat /sys/kernel/debug/pktcdvd/pktcdvd0/info diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy index db17fc8a0c9f..49db0ff288e5 100644 --- a/Documentation/ABI/testing/ima_policy +++ b/Documentation/ABI/testing/ima_policy @@ -35,7 +35,7 @@ Description: [FIRMWARE_CHECK] [KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK] [KEXEC_CMDLINE] [KEY_CHECK] [CRITICAL_DATA] - [SETXATTR_CHECK] + [SETXATTR_CHECK][MMAP_CHECK_REQPROT] mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND] [[^]MAY_EXEC] fsmagic:= hex value diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x index 651602a61eac..234c33fbdb55 100644 --- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x @@ -236,7 +236,7 @@ What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/traceid Date: November 2014 KernelVersion: 3.19 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (RW) Holds the trace ID that will appear in the trace stream +Description: (RO) Holds the trace ID that will appear in the trace stream coming from this trace entity. What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/trigger_event diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tpdm b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tpdm new file mode 100644 index 000000000000..4a58e649550d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tpdm @@ -0,0 +1,13 @@ +What: /sys/bus/coresight/devices/<tpdm-name>/integration_test +Date: January 2023 +KernelVersion 6.2 +Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com> +Description: + (Write) Run integration test for tpdm. Integration test + will generate test data for tpdm. It can help to make + sure that the trace path is enabled and the link configurations + are fine. + + Accepts only one of the 2 values - 1 or 2. + 1 : Generate 64 bits data + 2 : Generate 32 bits data diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-ultra_smb b/Documentation/ABI/testing/sysfs-bus-coresight-devices-ultra_smb new file mode 100644 index 000000000000..f560918ae738 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-ultra_smb @@ -0,0 +1,31 @@ +What: /sys/bus/coresight/devices/ultra_smb<N>/enable_sink +Date: January 2023 +KernelVersion: 6.3 +Contact: Junhao He <hejunhao3@huawei.com> +Description: (RW) Add/remove a SMB device from a trace path. There can be + multiple sources for a single SMB device. + +What: /sys/bus/coresight/devices/ultra_smb<N>/mgmt/buf_size +Date: January 2023 +KernelVersion: 6.3 +Contact: Junhao He <hejunhao3@huawei.com> +Description: (RO) Shows the buffer size of each UltraSoc SMB device. + +What: /sys/bus/coresight/devices/ultra_smb<N>/mgmt/buf_status +Date: January 2023 +KernelVersion: 6.3 +Contact: Junhao He <hejunhao3@huawei.com> +Description: (RO) Shows the value of UltraSoc SMB status register. + BIT(0) is zero means buffer is empty. + +What: /sys/bus/coresight/devices/ultra_smb<N>/mgmt/read_pos +Date: January 2023 +KernelVersion: 6.3 +Contact: Junhao He <hejunhao3@huawei.com> +Description: (RO) Shows the value of UltraSoc SMB Read Pointer register. + +What: /sys/bus/coresight/devices/ultra_smb<N>/mgmt/write_pos +Date: January 2023 +KernelVersion: 6.3 +Contact: Junhao He <hejunhao3@huawei.com> +Description: (RO) Shows the value of UltraSoc SMB Write Pointer register. diff --git a/Documentation/ABI/testing/sysfs-bus-css b/Documentation/ABI/testing/sysfs-bus-css index 12a733fe357f..d4d5cfb63b90 100644 --- a/Documentation/ABI/testing/sysfs-bus-css +++ b/Documentation/ABI/testing/sysfs-bus-css @@ -1,22 +1,19 @@ What: /sys/bus/css/devices/.../type Date: March 2008 -Contact: Cornelia Huck <cornelia.huck@de.ibm.com> - linux-s390@vger.kernel.org +Contact: linux-s390@vger.kernel.org Description: Contains the subchannel type, as reported by the hardware. This attribute is present for all subchannel types. What: /sys/bus/css/devices/.../modalias Date: March 2008 -Contact: Cornelia Huck <cornelia.huck@de.ibm.com> - linux-s390@vger.kernel.org +Contact: linux-s390@vger.kernel.org Description: Contains the module alias as reported with uevents. It is of the format css:t<type> and present for all subchannel types. What: /sys/bus/css/drivers/io_subchannel/.../chpids Date: December 2002 -Contact: Cornelia Huck <cornelia.huck@de.ibm.com> - linux-s390@vger.kernel.org +Contact: linux-s390@vger.kernel.org Description: Contains the ids of the channel paths used by this subchannel, as reported by the channel subsystem during subchannel recognition. @@ -26,8 +23,7 @@ Users: s390-tools, HAL What: /sys/bus/css/drivers/io_subchannel/.../pimpampom Date: December 2002 -Contact: Cornelia Huck <cornelia.huck@de.ibm.com> - linux-s390@vger.kernel.org +Contact: linux-s390@vger.kernel.org Description: Contains the PIM/PAM/POM values, as reported by the channel subsystem when last queried by the common I/O layer (this implies that this attribute is not necessarily @@ -38,8 +34,7 @@ Users: s390-tools, HAL What: /sys/bus/css/devices/.../driver_override Date: June 2019 -Contact: Cornelia Huck <cohuck@redhat.com> - linux-s390@vger.kernel.org +Contact: linux-s390@vger.kernel.org Description: This file allows the driver for a device to be specified. When specified, only a driver with a name matching the value written to driver_override will have an opportunity to bind to the diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-iommu b/Documentation/ABI/testing/sysfs-bus-event_source-devices-iommu new file mode 100644 index 000000000000..d7af4919302e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-iommu @@ -0,0 +1,37 @@ +What: /sys/bus/event_source/devices/dmar*/format +Date: Jan 2023 +KernelVersion: 6.3 +Contact: Kan Liang <kan.liang@linux.intel.com> +Description: Read-only. Attribute group to describe the magic bits + that go into perf_event_attr.config, + perf_event_attr.config1 or perf_event_attr.config2 for + the IOMMU pmu. (See also + ABI/testing/sysfs-bus-event_source-devices-format). + + Each attribute in this group defines a bit range in + perf_event_attr.config, perf_event_attr.config1, + or perf_event_attr.config2. All supported attributes + are listed below (See the VT-d Spec 4.0 for possible + attribute values):: + + event = "config:0-27" - event ID + event_group = "config:28-31" - event group ID + + filter_requester_en = "config1:0" - Enable Requester ID filter + filter_domain_en = "config1:1" - Enable Domain ID filter + filter_pasid_en = "config1:2" - Enable PASID filter + filter_ats_en = "config1:3" - Enable Address Type filter + filter_page_table_en= "config1:4" - Enable Page Table Level filter + filter_requester_id = "config1:16-31" - Requester ID filter + filter_domain = "config1:32-47" - Domain ID filter + filter_pasid = "config2:0-21" - PASID filter + filter_ats = "config2:24-28" - Address Type filter + filter_page_table = "config2:32-36" - Page Table Level filter + +What: /sys/bus/event_source/devices/dmar*/cpumask +Date: Jan 2023 +KernelVersion: 6.3 +Contact: Kan Liang <kan.liang@linux.intel.com> +Description: Read-only. This file always returns the CPU to which the + IOMMU pmu is bound for access to all IOMMU pmu performance + monitoring events. diff --git a/Documentation/ABI/testing/sysfs-class-hwmon b/Documentation/ABI/testing/sysfs-class-hwmon index 7271781a23b2..638f4c6d4ec7 100644 --- a/Documentation/ABI/testing/sysfs-class-hwmon +++ b/Documentation/ABI/testing/sysfs-class-hwmon @@ -276,6 +276,15 @@ Description: RW +What: /sys/class/hwmon/hwmonX/fanY_fault +Description: + Reports if a fan has reported failure. + + - 1: Failed + - 0: Ok + + RO + What: /sys/class/hwmon/hwmonX/pwmY Description: Pulse width modulation fan control. diff --git a/Documentation/ABI/testing/sysfs-class-net-peak_usb b/Documentation/ABI/testing/sysfs-class-net-peak_usb new file mode 100644 index 000000000000..9e3d0bf4d4b2 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-net-peak_usb @@ -0,0 +1,19 @@ + +What: /sys/class/net/<iface>/peak_usb/can_channel_id +Date: November 2022 +KernelVersion: 6.2 +Contact: Stephane Grosjean <s.grosjean@peak-system.com> +Description: + PEAK PCAN-USB devices support user-configurable CAN channel + identifiers. Contrary to a USB serial number, these identifiers + are writable and can be set per CAN interface. This means that + if a USB device exports multiple CAN interfaces, each of them + can be assigned a unique channel ID. + This attribute provides read-only access to the currently + configured value of the channel identifier. Depending on the + device type, the identifier has a length of 8 or 32 bit. The + value read from this attribute is always an 8 digit 32 bit + hexadecimal value in big endian format. If the device only + supports an 8 bit identifier, the upper 24 bit of the value are + set to zero. + diff --git a/Documentation/ABI/testing/sysfs-class-pktcdvd b/Documentation/ABI/testing/sysfs-class-pktcdvd new file mode 100644 index 000000000000..ba1ce626591d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-pktcdvd @@ -0,0 +1,97 @@ +sysfs interface +--------------- +The pktcdvd module (packet writing driver) creates the following files in the +sysfs: (<devid> is in the format major:minor) + +What: /sys/class/pktcdvd/add +What: /sys/class/pktcdvd/remove +What: /sys/class/pktcdvd/device_map +Date: Oct. 2006 +KernelVersion: 2.6.20 +Contact: Thomas Maier <balagi@justmail.de> +Description: + + ========== ============================================== + add (WO) Write a block device id (major:minor) to + create a new pktcdvd device and map it to the + block device. + + remove (WO) Write the pktcdvd device id (major:minor) + to remove the pktcdvd device. + + device_map (RO) Shows the device mapping in format: + pktcdvd[0-7] <pktdevid> <blkdevid> + ========== ============================================== + + +What: /sys/class/pktcdvd/pktcdvd[0-7]/dev +What: /sys/class/pktcdvd/pktcdvd[0-7]/uevent +Date: Oct. 2006 +KernelVersion: 2.6.20 +Contact: Thomas Maier <balagi@justmail.de> +Description: + dev: (RO) Device id + + uevent: (WO) To send a uevent + + +What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/packets_started +What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/packets_finished +What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/kb_written +What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/kb_read +What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/kb_read_gather +What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/reset +Date: Oct. 2006 +KernelVersion: 2.6.20 +Contact: Thomas Maier <balagi@justmail.de> +Description: + packets_started: (RO) Number of started packets. + + packets_finished: (RO) Number of finished packets. + + kb_written: (RO) kBytes written. + + kb_read: (RO) kBytes read. + + kb_read_gather: (RO) kBytes read to fill write packets. + + reset: (WO) Write any value to it to reset + pktcdvd device statistic values, like + bytes read/written. + + +What: /sys/class/pktcdvd/pktcdvd[0-7]/write_queue/size +What: /sys/class/pktcdvd/pktcdvd[0-7]/write_queue/congestion_off +What: /sys/class/pktcdvd/pktcdvd[0-7]/write_queue/congestion_on +Date: Oct. 2006 +KernelVersion: 2.6.20 +Contact: Thomas Maier <balagi@justmail.de> +Description: + ============== ================================================ + size (RO) Contains the size of the bio write queue. + + congestion_off (RW) If bio write queue size is below this mark, + accept new bio requests from the block layer. + + congestion_on (RW) If bio write queue size is higher as this + mark, do no longer accept bio write requests + from the block layer and wait till the pktcdvd + device has processed enough bio's so that bio + write queue size is below congestion off mark. + A value of <= 0 disables congestion control. + ============== ================================================ + + +Example: +-------- +To use the pktcdvd sysfs interface directly, you can do:: + + # create a new pktcdvd device mapped to /dev/hdc + echo "22:0" >/sys/class/pktcdvd/add + cat /sys/class/pktcdvd/device_map + # assuming device pktcdvd0 was created, look at stat's + cat /sys/class/pktcdvd/pktcdvd0/stat/kb_written + # print the device id of the mapped block device + fgrep pktcdvd0 /sys/class/pktcdvd/device_map + # remove device, using pktcdvd0 device id 253:0 + echo "253:0" >/sys/class/pktcdvd/remove diff --git a/Documentation/ABI/testing/sysfs-class-usb_power_delivery b/Documentation/ABI/testing/sysfs-class-usb_power_delivery index ce2b1b563cb3..1bf9d1d7902c 100644 --- a/Documentation/ABI/testing/sysfs-class-usb_power_delivery +++ b/Documentation/ABI/testing/sysfs-class-usb_power_delivery @@ -69,7 +69,7 @@ Description: This file contains boolean value that tells does the device support both source and sink power roles. -What: /sys/class/usb_power_delivery/.../<capability>/1:fixed_supply/usb_suspend_supported +What: /sys/class/usb_power_delivery/.../source-capabilities/1:fixed_supply/usb_suspend_supported Date: May 2022 Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> Description: @@ -78,6 +78,15 @@ Description: will follow the USB 2.0 and USB 3.2 rules for suspend and resume. +What: /sys/class/usb_power_delivery/.../sink-capabilities/1:fixed_supply/higher_capability +Date: February 2023 +Contact: Saranya Gopal <saranya.gopal@linux.intel.com> +Description: + This file shows the value of the Higher capability bit in + vsafe5V Fixed Supply Object. If the bit is set, then the sink + needs more than vsafe5V(eg. 12 V) to provide full functionality. + Valid values: 0, 1 + What: /sys/class/usb_power_delivery/.../<capability>/1:fixed_supply/unconstrained_power Date: May 2022 Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> diff --git a/Documentation/ABI/testing/sysfs-driver-habanalabs b/Documentation/ABI/testing/sysfs-driver-habanalabs index 13b5b2ec3be7..1b98b6503b23 100644 --- a/Documentation/ABI/testing/sysfs-driver-habanalabs +++ b/Documentation/ABI/testing/sysfs-driver-habanalabs @@ -201,7 +201,19 @@ What: /sys/class/habanalabs/hl<n>/status Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org -Description: Status of the card: "Operational", "Malfunction", "In reset". +Description: Status of the card: + + * "operational" - Device is available for work. + * "in reset" - Device is going through reset, will be + available shortly. + * "disabled" - Device is not usable. + * "needs reset" - Device is not usable until a hard reset + is initiated. + * "in device creation" - Device is not available yet, as it + is still initializing. + * "in reset after device release" - Device is going through + a compute-reset which is executed after a device release + (relevant for Gaudi2 only). What: /sys/class/habanalabs/hl<n>/thermal_ver Date: Jan 2019 diff --git a/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc b/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc index 9773925138af..a8ab58035c95 100644 --- a/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc +++ b/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc @@ -1,4 +1,4 @@ -What: /sys/bus/spi/devices/.../bmc_version +What: /sys/bus/.../drivers/intel-m10-bmc/.../bmc_version Date: June 2020 KernelVersion: 5.10 Contact: Xu Yilun <yilun.xu@intel.com> @@ -6,7 +6,7 @@ Description: Read only. Returns the hardware build version of Intel MAX10 BMC chip. Format: "0x%x". -What: /sys/bus/spi/devices/.../bmcfw_version +What: /sys/bus/.../drivers/intel-m10-bmc/.../bmcfw_version Date: June 2020 KernelVersion: 5.10 Contact: Xu Yilun <yilun.xu@intel.com> @@ -14,7 +14,7 @@ Description: Read only. Returns the firmware version of Intel MAX10 BMC chip. Format: "0x%x". -What: /sys/bus/spi/devices/.../mac_address +What: /sys/bus/.../drivers/intel-m10-bmc/.../mac_address Date: January 2021 KernelVersion: 5.12 Contact: Russ Weight <russell.h.weight@intel.com> @@ -25,7 +25,7 @@ Description: Read only. Returns the first MAC address in a block space. Format: "%02x:%02x:%02x:%02x:%02x:%02x". -What: /sys/bus/spi/devices/.../mac_count +What: /sys/bus/.../drivers/intel-m10-bmc/.../mac_count Date: January 2021 KernelVersion: 5.12 Contact: Russ Weight <russell.h.weight@intel.com> diff --git a/Documentation/ABI/testing/sysfs-driver-qat b/Documentation/ABI/testing/sysfs-driver-qat index 185f81a2aab3..087842b1969e 100644 --- a/Documentation/ABI/testing/sysfs-driver-qat +++ b/Documentation/ABI/testing/sysfs-driver-qat @@ -1,6 +1,6 @@ What: /sys/bus/pci/devices/<BDF>/qat/state Date: June 2022 -KernelVersion: 5.20 +KernelVersion: 6.0 Contact: qat-linux@intel.com Description: (RW) Reports the current state of the QAT device. Write to the file to start or stop the device. @@ -18,7 +18,7 @@ Description: (RW) Reports the current state of the QAT device. Write to What: /sys/bus/pci/devices/<BDF>/qat/cfg_services Date: June 2022 -KernelVersion: 5.20 +KernelVersion: 6.0 Contact: qat-linux@intel.com Description: (RW) Reports the current configuration of the QAT device. Write to the file to change the configured services. diff --git a/Documentation/ABI/testing/sysfs-driver-typec-displayport b/Documentation/ABI/testing/sysfs-driver-typec-displayport index 231471ad0d4b..256c87c5219a 100644 --- a/Documentation/ABI/testing/sysfs-driver-typec-displayport +++ b/Documentation/ABI/testing/sysfs-driver-typec-displayport @@ -47,3 +47,18 @@ Description: USB SuperSpeed protocol. From user perspective pin assignments C and E are equal, where all channels on the connector are used for carrying DisplayPort protocol (allowing higher resolutions). + +What: /sys/bus/typec/devices/.../displayport/hpd +Date: Dec 2022 +Contact: Badhri Jagan Sridharan <badhri@google.com> +Description: + VESA DisplayPort Alt Mode on USB Type-C Standard defines how + HotPlugDetect(HPD) shall be supported on the USB-C connector when + operating in DisplayPort Alt Mode. This is a read only node which + reflects the current state of HPD. + + Valid values: + - 1: when HPD’s logical state is high (HPD_High) as defined + by VESA DisplayPort Alt Mode on USB Type-C Standard. + - 0 when HPD’s logical state is low (HPD_Low) as defined by + VESA DisplayPort Alt Mode on USB Type-C Standard. diff --git a/Documentation/ABI/testing/sysfs-driver-uacce b/Documentation/ABI/testing/sysfs-driver-uacce index 08f2591138af..d3f0b8f3c589 100644 --- a/Documentation/ABI/testing/sysfs-driver-uacce +++ b/Documentation/ABI/testing/sysfs-driver-uacce @@ -19,6 +19,24 @@ Contact: linux-accelerators@lists.ozlabs.org Description: Available instances left of the device Return -ENODEV if uacce_ops get_available_instances is not provided +What: /sys/class/uacce/<dev_name>/isolate_strategy +Date: Nov 2022 +KernelVersion: 6.1 +Contact: linux-accelerators@lists.ozlabs.org +Description: (RW) A sysfs node that configure the error threshold for the hardware + isolation strategy. This size is a configured integer value, which is the + number of threshold for hardware errors occurred in one hour. The default is 0. + 0 means never isolate the device. The maximum value is 65535. You can write + a number of threshold based on your hardware. + +What: /sys/class/uacce/<dev_name>/isolate +Date: Nov 2022 +KernelVersion: 6.1 +Contact: linux-accelerators@lists.ozlabs.org +Description: (R) A sysfs node that read the device isolated state. The value 1 + means the device is unavailable. The 0 means the device is + available. + What: /sys/class/uacce/<dev_name>/algorithms Date: Feb 2020 KernelVersion: 5.7 diff --git a/Documentation/ABI/testing/sysfs-driver-xilinx-tmr-manager b/Documentation/ABI/testing/sysfs-driver-xilinx-tmr-manager new file mode 100644 index 000000000000..57b9b68a73ee --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-xilinx-tmr-manager @@ -0,0 +1,16 @@ +What: /sys/devices/platform/amba_pl/<dev>/errcnt +Date: Nov 2022 +Contact: appana.durga.kedareswara.rao@amd.com +Description: This control file provides the fault detection count. + This file cannot be written. + Example: + # cat /sys/devices/platform/amba_pl/44a10000.tmr_manager/errcnt + 1 + +What: /sys/devices/platform/amba_pl/<dev>/dis_block_break +Date: Nov 2022 +Contact: appana.durga.kedareswara.rao@amd.com +Description: Write any value to it, This control file enables the break signal. + This file is write only. + Example: + # echo <any value> > /sys/devices/platform/amba_pl/44a10000.tmr_manager/dis_block_break diff --git a/Documentation/ABI/testing/sysfs-fs-erofs b/Documentation/ABI/testing/sysfs-fs-erofs index bb4681a01811..284224d1b56f 100644 --- a/Documentation/ABI/testing/sysfs-fs-erofs +++ b/Documentation/ABI/testing/sysfs-fs-erofs @@ -4,7 +4,8 @@ Contact: "Huang Jianan" <huangjianan@oppo.com> Description: Shows all enabled kernel features. Supported features: zero_padding, compr_cfgs, big_pcluster, chunked_file, - device_table, compr_head2, sb_chksum. + device_table, compr_head2, sb_chksum, ztailpacking, + dedupe, fragments. What: /sys/fs/erofs/<disk>/sync_decompress Date: November 2021 diff --git a/Documentation/ABI/testing/sysfs-kernel-address_bits b/Documentation/ABI/testing/sysfs-kernel-address_bits new file mode 100644 index 000000000000..5d09ff84d4d6 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-address_bits @@ -0,0 +1,10 @@ +What: /sys/kernel/address_bit +Date: May 2023 +KernelVersion: 6.3 +Contact: Thomas Weißschuh <linux@weissschuh.net> +Description: + The address size of the running kernel in bits. + + Access: Read + +Users: util-linux diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-damon b/Documentation/ABI/testing/sysfs-kernel-mm-damon index 13397b853692..2744f21b5a6b 100644 --- a/Documentation/ABI/testing/sysfs-kernel-mm-damon +++ b/Documentation/ABI/testing/sysfs-kernel-mm-damon @@ -258,6 +258,35 @@ Contact: SeongJae Park <sj@kernel.org> Description: Writing to and reading from this file sets and gets the low watermark of the scheme in permil. +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/nr_filters +Date: Dec 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing a number 'N' to this file creates the number of + directories for setting filters of the scheme named '0' to + 'N-1' under the filters/ directory. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/type +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. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/memcg_path +Date: Dec 2022 +Contact: SeongJae Park <sj@kernel.org> +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>/matching +Date: Dec 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing 'Y' or 'N' to this file sets whether to filter out + pages that do or do not match to the 'type' and 'memcg_path', + respectively. Filter out means the action of the scheme will + not be applied to. + What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/nr_tried Date: Mar 2022 Contact: SeongJae Park <sj@kernel.org> diff --git a/Documentation/Kconfig b/Documentation/Kconfig index 252bfc164dbd..3a0e7ac0c4e3 100644 --- a/Documentation/Kconfig +++ b/Documentation/Kconfig @@ -1,6 +1,9 @@ +if COMPILE_TEST + +menu "Documentation" + config WARN_MISSING_DOCUMENTS bool "Warn if there's a missing documentation file" - depends on COMPILE_TEST help It is not uncommon that a document gets renamed. This option makes the Kernel to check for missing dependencies, @@ -11,7 +14,6 @@ config WARN_MISSING_DOCUMENTS config WARN_ABI_ERRORS bool "Warn if there are errors at ABI files" - depends on COMPILE_TEST help The files under Documentation/ABI should follow what's described at Documentation/ABI/README. Yet, as they're manually @@ -20,3 +22,7 @@ config WARN_ABI_ERRORS scripts/get_abi.pl. Add a check to verify them. If unsure, select 'N'. + +endmenu + +endif diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst index c17c87af1968..e73f84aebde3 100644 --- a/Documentation/PCI/index.rst +++ b/Documentation/PCI/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -======================= -Linux PCI Bus Subsystem -======================= +================= +PCI Bus Subsystem +================= .. toctree:: :maxdepth: 2 diff --git a/Documentation/RCU/NMI-RCU.rst b/Documentation/RCU/NMI-RCU.rst index 2a92bc685ef1..dff60a80b386 100644 --- a/Documentation/RCU/NMI-RCU.rst +++ b/Documentation/RCU/NMI-RCU.rst @@ -8,7 +8,7 @@ Although RCU is usually used to protect read-mostly data structures, it is possible to use RCU to provide dynamic non-maskable interrupt handlers, as well as dynamic irq handlers. This document describes how to do this, drawing loosely from Zwane Mwaikambo's NMI-timer -work in "arch/x86/kernel/traps.c". +work in an old version of "arch/x86/kernel/traps.c". The relevant pieces of code are listed below, each followed by a brief explanation:: @@ -116,7 +116,7 @@ Answer to Quick Quiz: This same sad story can happen on other CPUs when using a compiler with aggressive pointer-value speculation - optimizations. + optimizations. (But please don't!) More important, the rcu_dereference_sched() makes it clear to someone reading the code that the pointer is diff --git a/Documentation/RCU/UP.rst b/Documentation/RCU/UP.rst index e26dda27430c..8b20fd45f255 100644 --- a/Documentation/RCU/UP.rst +++ b/Documentation/RCU/UP.rst @@ -38,7 +38,7 @@ by having call_rcu() directly invoke its arguments only if it was called from process context. However, this can fail in a similar manner. Suppose that an RCU-based algorithm again scans a linked list containing -elements A, B, and C in process contexts, but that it invokes a function +elements A, B, and C in process context, but that it invokes a function on each element as it is scanned. Suppose further that this function deletes element B from the list, then passes it to call_rcu() for deferred freeing. This may be a bit unconventional, but it is perfectly legal @@ -59,7 +59,8 @@ Example 3: Death by Deadlock Suppose that call_rcu() is invoked while holding a lock, and that the callback function must acquire this same lock. In this case, if call_rcu() were to directly invoke the callback, the result would -be self-deadlock. +be self-deadlock *even if* this invocation occurred from a later +call_rcu() invocation a full grace period later. In some cases, it would possible to restructure to code so that the call_rcu() is delayed until after the lock is released. However, @@ -85,6 +86,14 @@ Quick Quiz #2: :ref:`Answers to Quick Quiz <answer_quick_quiz_up>` +It is important to note that userspace RCU implementations *do* +permit call_rcu() to directly invoke callbacks, but only if a full +grace period has elapsed since those callbacks were queued. This is +the case because some userspace environments are extremely constrained. +Nevertheless, people writing userspace RCU implementations are strongly +encouraged to avoid invoking callbacks from call_rcu(), thus obtaining +the deadlock-avoidance benefits called out above. + Summary ------- diff --git a/Documentation/RCU/lockdep.rst b/Documentation/RCU/lockdep.rst index 9308f1bdba05..2749f43ec1b0 100644 --- a/Documentation/RCU/lockdep.rst +++ b/Documentation/RCU/lockdep.rst @@ -69,9 +69,8 @@ checking of rcu_dereference() primitives: value of the pointer itself, for example, against NULL. The rcu_dereference_check() check expression can be any boolean -expression, but would normally include a lockdep expression. However, -any boolean expression can be used. For a moderately ornate example, -consider the following:: +expression, but would normally include a lockdep expression. For a +moderately ornate example, consider the following:: file = rcu_dereference_check(fdt->fd[fd], lockdep_is_held(&files->file_lock) || @@ -97,10 +96,10 @@ code, it could instead be written as follows:: atomic_read(&files->count) == 1); This would verify cases #2 and #3 above, and furthermore lockdep would -complain if this was used in an RCU read-side critical section unless one -of these two cases held. Because rcu_dereference_protected() omits all -barriers and compiler constraints, it generates better code than do the -other flavors of rcu_dereference(). On the other hand, it is illegal +complain even if this was used in an RCU read-side critical section unless +one of these two cases held. Because rcu_dereference_protected() omits +all barriers and compiler constraints, it generates better code than do +the other flavors of rcu_dereference(). On the other hand, it is illegal to use rcu_dereference_protected() if either the RCU-protected pointer or the RCU-protected data that it points to can change concurrently. diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst index 3cfe01ba9a49..bf6617b330a7 100644 --- a/Documentation/RCU/rcu.rst +++ b/Documentation/RCU/rcu.rst @@ -77,15 +77,17 @@ Frequently Asked Questions search for the string "Patent" in Documentation/RCU/RTFP.txt to find them. Of these, one was allowed to lapse by the assignee, and the others have been contributed to the Linux kernel under GPL. + Many (but not all) have long since expired. There are now also LGPL implementations of user-level RCU available (https://liburcu.org/). - I hear that RCU needs work in order to support realtime kernels? - Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU + Realtime-friendly RCU are enabled via the CONFIG_PREEMPTION kernel configuration parameter. - Where can I find more information on RCU? See the Documentation/RCU/RTFP.txt file. - Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/). + Or point your browser at (https://docs.google.com/document/d/1X0lThx8OK0ZgLMqVoXiR4ZrGURHrXK6NyLRbeXe3Xac/edit) + or (https://docs.google.com/document/d/1GCdQC8SDbb54W1shjEXqGZ0Rq8a6kIeYutdSIajfpLA/edit?usp=sharing). diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst index 81e828c8313b..3b739f6243c8 100644 --- a/Documentation/RCU/rcu_dereference.rst +++ b/Documentation/RCU/rcu_dereference.rst @@ -19,8 +19,9 @@ Follow these rules to keep your RCU code working properly: can reload the value, and won't your code have fun with two different values for a single pointer! Without rcu_dereference(), DEC Alpha can load a pointer, dereference that pointer, and - return data preceding initialization that preceded the store of - the pointer. + return data preceding initialization that preceded the store + of the pointer. (As noted later, in recent kernels READ_ONCE() + also prevents DEC Alpha from playing these tricks.) In addition, the volatile cast in rcu_dereference() prevents the compiler from deducing the resulting pointer value. Please see @@ -34,7 +35,7 @@ Follow these rules to keep your RCU code working properly: takes on the role of the lockless_dereference() primitive that was removed in v4.15. -- You are only permitted to use rcu_dereference on pointer values. +- You are only permitted to use rcu_dereference() on pointer values. The compiler simply knows too much about integral values to trust it to carry dependencies through integer operations. There are a very few exceptions, namely that you can temporarily @@ -240,6 +241,7 @@ precautions. To see this, consider the following code fragment:: struct foo *q; int r1, r2; + rcu_read_lock(); p = rcu_dereference(gp2); if (p == NULL) return; @@ -248,7 +250,10 @@ precautions. To see this, consider the following code fragment:: if (p == q) { /* The compiler decides that q->c is same as p->c. */ r2 = p->c; /* Could get 44 on weakly order system. */ + } else { + r2 = p->c - r1; /* Unconditional access to p->c. */ } + rcu_read_unlock(); do_something_with(r1, r2); } @@ -297,6 +302,7 @@ Then one approach is to use locking, for example, as follows:: struct foo *q; int r1, r2; + rcu_read_lock(); p = rcu_dereference(gp2); if (p == NULL) return; @@ -306,7 +312,12 @@ Then one approach is to use locking, for example, as follows:: if (p == q) { /* The compiler decides that q->c is same as p->c. */ r2 = p->c; /* Locking guarantees r2 == 144. */ + } else { + spin_lock(&q->lock); + r2 = q->c - r1; + spin_unlock(&q->lock); } + rcu_read_unlock(); spin_unlock(&p->lock); do_something_with(r1, r2); } @@ -364,7 +375,7 @@ the exact value of "p" even in the not-equals case. This allows the compiler to make the return values independent of the load from "gp", in turn destroying the ordering between this load and the loads of the return values. This can result in "p->b" returning pre-initialization -garbage values. +garbage values on weakly ordered systems. In short, rcu_dereference() is *not* optional when you are going to dereference the resulting pointer. @@ -430,7 +441,7 @@ member of the rcu_dereference() to use in various situations: SPARSE CHECKING OF RCU-PROTECTED POINTERS ----------------------------------------- -The sparse static-analysis tool checks for direct access to RCU-protected +The sparse static-analysis tool checks for non-RCU access to RCU-protected pointers, which can result in "interesting" bugs due to compiler optimizations involving invented loads and perhaps also load tearing. For example, suppose someone mistakenly does something like this:: diff --git a/Documentation/RCU/rcubarrier.rst b/Documentation/RCU/rcubarrier.rst index 3b4a24877496..6da7f66da2a8 100644 --- a/Documentation/RCU/rcubarrier.rst +++ b/Documentation/RCU/rcubarrier.rst @@ -5,37 +5,12 @@ RCU and Unloadable Modules [Originally published in LWN Jan. 14, 2007: http://lwn.net/Articles/217484/] -RCU (read-copy update) is a synchronization mechanism that can be thought -of as a replacement for read-writer locking (among other things), but with -very low-overhead readers that are immune to deadlock, priority inversion, -and unbounded latency. RCU read-side critical sections are delimited -by rcu_read_lock() and rcu_read_unlock(), which, in non-CONFIG_PREEMPTION -kernels, generate no code whatsoever. - -This means that RCU writers are unaware of the presence of concurrent -readers, so that RCU updates to shared data must be undertaken quite -carefully, leaving an old version of the data structure in place until all -pre-existing readers have finished. These old versions are needed because -such readers might hold a reference to them. RCU updates can therefore be -rather expensive, and RCU is thus best suited for read-mostly situations. - -How can an RCU writer possibly determine when all readers are finished, -given that readers might well leave absolutely no trace of their -presence? There is a synchronize_rcu() primitive that blocks until all -pre-existing readers have completed. An updater wishing to delete an -element p from a linked list might do the following, while holding an -appropriate lock, of course:: - - list_del_rcu(p); - synchronize_rcu(); - kfree(p); - -But the above code cannot be used in IRQ context -- the call_rcu() -primitive must be used instead. This primitive takes a pointer to an -rcu_head struct placed within the RCU-protected data structure and -another pointer to a function that may be invoked later to free that -structure. Code to delete an element p from the linked list from IRQ -context might then be as follows:: +RCU updaters sometimes use call_rcu() to initiate an asynchronous wait for +a grace period to elapse. This primitive takes a pointer to an rcu_head +struct placed within the RCU-protected data structure and another pointer +to a function that may be invoked later to free that structure. Code to +delete an element p from the linked list from IRQ context might then be +as follows:: list_del_rcu(p); call_rcu(&p->rcu, p_callback); @@ -54,7 +29,7 @@ IRQ context. The function p_callback() might be defined as follows:: Unloading Modules That Use call_rcu() ------------------------------------- -But what if p_callback is defined in an unloadable module? +But what if the p_callback() function is defined in an unloadable module? If we unload the module while some RCU callbacks are pending, the CPUs executing these callbacks are going to be severely @@ -67,20 +42,21 @@ grace period to elapse, it does not wait for the callbacks to complete. One might be tempted to try several back-to-back synchronize_rcu() calls, but this is still not guaranteed to work. If there is a very -heavy RCU-callback load, then some of the callbacks might be deferred -in order to allow other processing to proceed. Such deferral is required -in realtime kernels in order to avoid excessive scheduling latencies. +heavy RCU-callback load, then some of the callbacks might be deferred in +order to allow other processing to proceed. For but one example, such +deferral is required in realtime kernels in order to avoid excessive +scheduling latencies. rcu_barrier() ------------- -We instead need the rcu_barrier() primitive. Rather than waiting for -a grace period to elapse, rcu_barrier() waits for all outstanding RCU -callbacks to complete. Please note that rcu_barrier() does **not** imply -synchronize_rcu(), in particular, if there are no RCU callbacks queued -anywhere, rcu_barrier() is within its rights to return immediately, -without waiting for a grace period to elapse. +This situation can be handled by the rcu_barrier() primitive. Rather +than waiting for a grace period to elapse, rcu_barrier() waits for all +outstanding RCU callbacks to complete. Please note that rcu_barrier() +does **not** imply synchronize_rcu(), in particular, if there are no RCU +callbacks queued anywhere, rcu_barrier() is within its rights to return +immediately, without waiting for anything, let alone a grace period. Pseudo-code using rcu_barrier() is as follows: @@ -89,83 +65,86 @@ Pseudo-code using rcu_barrier() is as follows: 3. Allow the module to be unloaded. There is also an srcu_barrier() function for SRCU, and you of course -must match the flavor of rcu_barrier() with that of call_rcu(). If your -module uses multiple flavors of call_rcu(), then it must also use multiple -flavors of rcu_barrier() when unloading that module. For example, if -it uses call_rcu(), call_srcu() on srcu_struct_1, and call_srcu() on -srcu_struct_2, then the following three lines of code will be required -when unloading:: - - 1 rcu_barrier(); - 2 srcu_barrier(&srcu_struct_1); - 3 srcu_barrier(&srcu_struct_2); - -The rcutorture module makes use of rcu_barrier() in its exit function -as follows:: - - 1 static void - 2 rcu_torture_cleanup(void) - 3 { - 4 int i; - 5 - 6 fullstop = 1; - 7 if (shuffler_task != NULL) { - 8 VERBOSE_PRINTK_STRING("Stopping rcu_torture_shuffle task"); - 9 kthread_stop(shuffler_task); - 10 } - 11 shuffler_task = NULL; +must match the flavor of srcu_barrier() with that of call_srcu(). +If your module uses multiple srcu_struct structures, then it must also +use multiple invocations of srcu_barrier() when unloading that module. +For example, if it uses call_rcu(), call_srcu() on srcu_struct_1, and +call_srcu() on srcu_struct_2, then the following three lines of code +will be required when unloading:: + + 1 rcu_barrier(); + 2 srcu_barrier(&srcu_struct_1); + 3 srcu_barrier(&srcu_struct_2); + +If latency is of the essence, workqueues could be used to run these +three functions concurrently. + +An ancient version of the rcutorture module makes use of rcu_barrier() +in its exit function as follows:: + + 1 static void + 2 rcu_torture_cleanup(void) + 3 { + 4 int i; + 5 + 6 fullstop = 1; + 7 if (shuffler_task != NULL) { + 8 VERBOSE_PRINTK_STRING("Stopping rcu_torture_shuffle task"); + 9 kthread_stop(shuffler_task); + 10 } + 11 shuffler_task = NULL; 12 - 13 if (writer_task != NULL) { - 14 VERBOSE_PRINTK_STRING("Stopping rcu_torture_writer task"); - 15 kthread_stop(writer_task); - 16 } - 17 writer_task = NULL; + 13 if (writer_task != NULL) { + 14 VERBOSE_PRINTK_STRING("Stopping rcu_torture_writer task"); + 15 kthread_stop(writer_task); + 16 } + 17 writer_task = NULL; 18 - 19 if (reader_tasks != NULL) { - 20 for (i = 0; i < nrealreaders; i++) { - 21 if (reader_tasks[i] != NULL) { - 22 VERBOSE_PRINTK_STRING( - 23 "Stopping rcu_torture_reader task"); - 24 kthread_stop(reader_tasks[i]); - 25 } - 26 reader_tasks[i] = NULL; - 27 } - 28 kfree(reader_tasks); - 29 reader_tasks = NULL; - 30 } - 31 rcu_torture_current = NULL; + 19 if (reader_tasks != NULL) { + 20 for (i = 0; i < nrealreaders; i++) { + 21 if (reader_tasks[i] != NULL) { + 22 VERBOSE_PRINTK_STRING( + 23 "Stopping rcu_torture_reader task"); + 24 kthread_stop(reader_tasks[i]); + 25 } + 26 reader_tasks[i] = NULL; + 27 } + 28 kfree(reader_tasks); + 29 reader_tasks = NULL; + 30 } + 31 rcu_torture_current = NULL; 32 - 33 if (fakewriter_tasks != NULL) { - 34 for (i = 0; i < nfakewriters; i++) { - 35 if (fakewriter_tasks[i] != NULL) { - 36 VERBOSE_PRINTK_STRING( - 37 "Stopping rcu_torture_fakewriter task"); - 38 kthread_stop(fakewriter_tasks[i]); - 39 } - 40 fakewriter_tasks[i] = NULL; - 41 } - 42 kfree(fakewriter_tasks); - 43 fakewriter_tasks = NULL; - 44 } + 33 if (fakewriter_tasks != NULL) { + 34 for (i = 0; i < nfakewriters; i++) { + 35 if (fakewriter_tasks[i] != NULL) { + 36 VERBOSE_PRINTK_STRING( + 37 "Stopping rcu_torture_fakewriter task"); + 38 kthread_stop(fakewriter_tasks[i]); + 39 } + 40 fakewriter_tasks[i] = NULL; + 41 } + 42 kfree(fakewriter_tasks); + 43 fakewriter_tasks = NULL; + 44 } 45 - 46 if (stats_task != NULL) { - 47 VERBOSE_PRINTK_STRING("Stopping rcu_torture_stats task"); - 48 kthread_stop(stats_task); - 49 } - 50 stats_task = NULL; + 46 if (stats_task != NULL) { + 47 VERBOSE_PRINTK_STRING("Stopping rcu_torture_stats task"); + 48 kthread_stop(stats_task); + 49 } + 50 stats_task = NULL; 51 - 52 /* Wait for all RCU callbacks to fire. */ - 53 rcu_barrier(); + 52 /* Wait for all RCU callbacks to fire. */ + 53 rcu_barrier(); 54 - 55 rcu_torture_stats_print(); /* -After- the stats thread is stopped! */ + 55 rcu_torture_stats_print(); /* -After- the stats thread is stopped! */ 56 - 57 if (cur_ops->cleanup != NULL) - 58 cur_ops->cleanup(); - 59 if (atomic_read(&n_rcu_torture_error)) - 60 rcu_torture_print_module_parms("End of test: FAILURE"); - 61 else - 62 rcu_torture_print_module_parms("End of test: SUCCESS"); - 63 } + 57 if (cur_ops->cleanup != NULL) + 58 cur_ops->cleanup(); + 59 if (atomic_read(&n_rcu_torture_error)) + 60 rcu_torture_print_module_parms("End of test: FAILURE"); + 61 else + 62 rcu_torture_print_module_parms("End of test: SUCCESS"); + 63 } Line 6 sets a global variable that prevents any RCU callbacks from re-posting themselves. This will not be necessary in most cases, since @@ -190,16 +169,17 @@ Quick Quiz #1: :ref:`Answer to Quick Quiz #1 <answer_rcubarrier_quiz_1>` Your module might have additional complications. For example, if your -module invokes call_rcu() from timers, you will need to first cancel all -the timers, and only then invoke rcu_barrier() to wait for any remaining +module invokes call_rcu() from timers, you will need to first refrain +from posting new timers, cancel (or wait for) all the already-posted +timers, and only then invoke rcu_barrier() to wait for any remaining RCU callbacks to complete. -Of course, if you module uses call_rcu(), you will need to invoke +Of course, if your module uses call_rcu(), you will need to invoke rcu_barrier() before unloading. Similarly, if your module uses call_srcu(), you will need to invoke srcu_barrier() before unloading, and on the same srcu_struct structure. If your module uses call_rcu() -**and** call_srcu(), then you will need to invoke rcu_barrier() **and** -srcu_barrier(). +**and** call_srcu(), then (as noted above) you will need to invoke +rcu_barrier() **and** srcu_barrier(). Implementing rcu_barrier() @@ -211,27 +191,40 @@ queues. His implementation queues an RCU callback on each of the per-CPU callback queues, and then waits until they have all started executing, at which point, all earlier RCU callbacks are guaranteed to have completed. -The original code for rcu_barrier() was as follows:: - - 1 void rcu_barrier(void) - 2 { - 3 BUG_ON(in_interrupt()); - 4 /* Take cpucontrol mutex to protect against CPU hotplug */ - 5 mutex_lock(&rcu_barrier_mutex); - 6 init_completion(&rcu_barrier_completion); - 7 atomic_set(&rcu_barrier_cpu_count, 0); - 8 on_each_cpu(rcu_barrier_func, NULL, 0, 1); - 9 wait_for_completion(&rcu_barrier_completion); - 10 mutex_unlock(&rcu_barrier_mutex); - 11 } - -Line 3 verifies that the caller is in process context, and lines 5 and 10 +The original code for rcu_barrier() was roughly as follows:: + + 1 void rcu_barrier(void) + 2 { + 3 BUG_ON(in_interrupt()); + 4 /* Take cpucontrol mutex to protect against CPU hotplug */ + 5 mutex_lock(&rcu_barrier_mutex); + 6 init_completion(&rcu_barrier_completion); + 7 atomic_set(&rcu_barrier_cpu_count, 1); + 8 on_each_cpu(rcu_barrier_func, NULL, 0, 1); + 9 if (atomic_dec_and_test(&rcu_barrier_cpu_count)) + 10 complete(&rcu_barrier_completion); + 11 wait_for_completion(&rcu_barrier_completion); + 12 mutex_unlock(&rcu_barrier_mutex); + 13 } + +Line 3 verifies that the caller is in process context, and lines 5 and 12 use rcu_barrier_mutex to ensure that only one rcu_barrier() is using the global completion and counters at a time, which are initialized on lines 6 and 7. Line 8 causes each CPU to invoke rcu_barrier_func(), which is shown below. Note that the final "1" in on_each_cpu()'s argument list ensures that all the calls to rcu_barrier_func() will have completed -before on_each_cpu() returns. Line 9 then waits for the completion. +before on_each_cpu() returns. Line 9 removes the initial count from +rcu_barrier_cpu_count, and if this count is now zero, line 10 finalizes +the completion, which prevents line 11 from blocking. Either way, +line 11 then waits (if needed) for the completion. + +.. _rcubarrier_quiz_2: + +Quick Quiz #2: + Why doesn't line 8 initialize rcu_barrier_cpu_count to zero, + thereby avoiding the need for lines 9 and 10? + +:ref:`Answer to Quick Quiz #2 <answer_rcubarrier_quiz_2>` This code was rewritten in 2008 and several times thereafter, but this still gives the general idea. @@ -239,21 +232,21 @@ still gives the general idea. The rcu_barrier_func() runs on each CPU, where it invokes call_rcu() to post an RCU callback, as follows:: - 1 static void rcu_barrier_func(void *notused) - 2 { - 3 int cpu = smp_processor_id(); - 4 struct rcu_data *rdp = &per_cpu(rcu_data, cpu); - 5 struct rcu_head *head; - 6 - 7 head = &rdp->barrier; - 8 atomic_inc(&rcu_barrier_cpu_count); - 9 call_rcu(head, rcu_barrier_callback); - 10 } + 1 static void rcu_barrier_func(void *notused) + 2 { + 3 int cpu = smp_processor_id(); + 4 struct rcu_data *rdp = &per_cpu(rcu_data, cpu); + 5 struct rcu_head *head; + 6 + 7 head = &rdp->barrier; + 8 atomic_inc(&rcu_barrier_cpu_count); + 9 call_rcu(head, rcu_barrier_callback); + 10 } Lines 3 and 4 locate RCU's internal per-CPU rcu_data structure, which contains the struct rcu_head that needed for the later call to call_rcu(). Line 7 picks up a pointer to this struct rcu_head, and line -8 increments a global counter. This counter will later be decremented +8 increments the global counter. This counter will later be decremented by the callback. Line 9 then registers the rcu_barrier_callback() on the current CPU's queue. @@ -261,33 +254,34 @@ The rcu_barrier_callback() function simply atomically decrements the rcu_barrier_cpu_count variable and finalizes the completion when it reaches zero, as follows:: - 1 static void rcu_barrier_callback(struct rcu_head *notused) - 2 { - 3 if (atomic_dec_and_test(&rcu_barrier_cpu_count)) - 4 complete(&rcu_barrier_completion); - 5 } + 1 static void rcu_barrier_callback(struct rcu_head *notused) + 2 { + 3 if (atomic_dec_and_test(&rcu_barrier_cpu_count)) + 4 complete(&rcu_barrier_completion); + 5 } -.. _rcubarrier_quiz_2: +.. _rcubarrier_quiz_3: -Quick Quiz #2: +Quick Quiz #3: What happens if CPU 0's rcu_barrier_func() executes immediately (thus incrementing rcu_barrier_cpu_count to the value one), but the other CPU's rcu_barrier_func() invocations are delayed for a full grace period? Couldn't this result in rcu_barrier() returning prematurely? -:ref:`Answer to Quick Quiz #2 <answer_rcubarrier_quiz_2>` +:ref:`Answer to Quick Quiz #3 <answer_rcubarrier_quiz_3>` The current rcu_barrier() implementation is more complex, due to the need to avoid disturbing idle CPUs (especially on battery-powered systems) and the need to minimally disturb non-idle CPUs in real-time systems. -However, the code above illustrates the concepts. +In addition, a great many optimizations have been applied. However, +the code above illustrates the concepts. rcu_barrier() Summary --------------------- -The rcu_barrier() primitive has seen relatively little use, since most +The rcu_barrier() primitive is used relatively infrequently, since most code using RCU is in the core kernel rather than in modules. However, if you are using RCU from an unloadable module, you need to use rcu_barrier() so that your module may be safely unloaded. @@ -302,7 +296,8 @@ Quick Quiz #1: Is there any other situation where rcu_barrier() might be required? -Answer: Interestingly enough, rcu_barrier() was not originally +Answer: + Interestingly enough, rcu_barrier() was not originally implemented for module unloading. Nikita Danilov was using RCU in a filesystem, which resulted in a similar situation at filesystem-unmount time. Dipankar Sarma coded up rcu_barrier() @@ -318,13 +313,48 @@ Answer: Interestingly enough, rcu_barrier() was not originally .. _answer_rcubarrier_quiz_2: Quick Quiz #2: + Why doesn't line 8 initialize rcu_barrier_cpu_count to zero, + thereby avoiding the need for lines 9 and 10? + +Answer: + Suppose that the on_each_cpu() function shown on line 8 was + delayed, so that CPU 0's rcu_barrier_func() executed and + the corresponding grace period elapsed, all before CPU 1's + rcu_barrier_func() started executing. This would result in + rcu_barrier_cpu_count being decremented to zero, so that line + 11's wait_for_completion() would return immediately, failing to + wait for CPU 1's callbacks to be invoked. + + Note that this was not a problem when the rcu_barrier() code + was first added back in 2005. This is because on_each_cpu() + disables preemption, which acted as an RCU read-side critical + section, thus preventing CPU 0's grace period from completing + until on_each_cpu() had dealt with all of the CPUs. However, + with the advent of preemptible RCU, rcu_barrier() no longer + waited on nonpreemptible regions of code in preemptible kernels, + that being the job of the new rcu_barrier_sched() function. + + However, with the RCU flavor consolidation around v4.20, this + possibility was once again ruled out, because the consolidated + RCU once again waits on nonpreemptible regions of code. + + Nevertheless, that extra count might still be a good idea. + Relying on these sort of accidents of implementation can result + in later surprise bugs when the implementation changes. + +:ref:`Back to Quick Quiz #2 <rcubarrier_quiz_2>` + +.. _answer_rcubarrier_quiz_3: + +Quick Quiz #3: What happens if CPU 0's rcu_barrier_func() executes immediately (thus incrementing rcu_barrier_cpu_count to the value one), but the other CPU's rcu_barrier_func() invocations are delayed for a full grace period? Couldn't this result in rcu_barrier() returning prematurely? -Answer: This cannot happen. The reason is that on_each_cpu() has its last +Answer: + This cannot happen. The reason is that on_each_cpu() has its last argument, the wait flag, set to "1". This flag is passed through to smp_call_function() and further to smp_call_function_on_cpu(), causing this latter to spin until the cross-CPU invocation of @@ -336,18 +366,15 @@ Answer: This cannot happen. The reason is that on_each_cpu() has its last Therefore, on_each_cpu() disables preemption across its call to smp_call_function() and also across the local call to - rcu_barrier_func(). This prevents the local CPU from context - switching, again preventing grace periods from completing. This + rcu_barrier_func(). Because recent RCU implementations treat + preemption-disabled regions of code as RCU read-side critical + sections, this prevents grace periods from completing. This means that all CPUs have executed rcu_barrier_func() before the first rcu_barrier_callback() can possibly execute, in turn preventing rcu_barrier_cpu_count from prematurely reaching zero. - Currently, -rt implementations of RCU keep but a single global - queue for RCU callbacks, and thus do not suffer from this - problem. However, when the -rt RCU eventually does have per-CPU - callback queues, things will have to change. One simple change - is to add an rcu_read_lock() before line 8 of rcu_barrier() - and an rcu_read_unlock() after line 8 of this same function. If - you can think of a better change, please let me know! + But if on_each_cpu() ever decides to forgo disabling preemption, + as might well happen due to real-time latency considerations, + initializing rcu_barrier_cpu_count to one will save the day. -:ref:`Back to Quick Quiz #2 <rcubarrier_quiz_2>` +:ref:`Back to Quick Quiz #3 <rcubarrier_quiz_3>` diff --git a/Documentation/RCU/rculist_nulls.rst b/Documentation/RCU/rculist_nulls.rst index ca4692775ad4..9a734bf54b76 100644 --- a/Documentation/RCU/rculist_nulls.rst +++ b/Documentation/RCU/rculist_nulls.rst @@ -14,19 +14,19 @@ Using 'nulls' ============= Using special makers (called 'nulls') is a convenient way -to solve following problem : +to solve following problem. -A typical RCU linked list managing objects which are -allocated with SLAB_TYPESAFE_BY_RCU kmem_cache can -use following algos : +Without 'nulls', a typical RCU linked list managing objects which are +allocated with SLAB_TYPESAFE_BY_RCU kmem_cache can use the following +algorithms: -1) Lookup algo --------------- +1) Lookup algorithm +------------------- :: - rcu_read_lock() begin: + rcu_read_lock() obj = lockless_lookup(key); if (obj) { if (!try_get_ref(obj)) // might fail for free objects @@ -38,6 +38,7 @@ use following algos : */ if (obj->key != key) { // not the object we expected put_ref(obj); + rcu_read_unlock(); goto begin; } } @@ -52,9 +53,9 @@ 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; }); - pos = rcu_dereference(next)) + pos && ({ next = pos->next; smp_rmb(); prefetch(next); 1; }) && + ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; }); + pos = rcu_dereference(next)) if (obj->key == key) return obj; return NULL; @@ -64,9 +65,9 @@ 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; }); - pos = rcu_dereference(pos->next)) + pos && ({ prefetch(pos->next); 1; }) && + ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; }); + pos = rcu_dereference(pos->next)) if (obj->key == key) return obj; return NULL; @@ -82,36 +83,32 @@ Quoting Corey Minyard:: solved by pre-fetching the "next" field (with proper barriers) before checking the key." -2) Insert algo --------------- +2) Insertion algorithm +---------------------- We need to make sure a reader cannot read the new 'obj->obj_next' value -and previous value of 'obj->key'. Or else, an item could be deleted +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 detect it missed following items in original chain. +before the move, 'next' pointer is NULL, and lockless reader can not +detect the fact that it missed following items in original chain. :: /* - * Please note that new inserts are done at the head of list, - * not in the middle or end. - */ + * Please note that new inserts are done at the head of list, + * not in the middle or end. + */ obj = kmem_cache_alloc(...); lock_chain(); // typically a spin_lock() obj->key = key; - /* - * we need to make sure obj->key is updated before obj->next - * or obj->refcnt - */ - smp_wmb(); - atomic_set(&obj->refcnt, 1); + atomic_set_release(&obj->refcnt, 1); // key before refcnt hlist_add_head_rcu(&obj->obj_node, list); unlock_chain(); // typically a spin_unlock() -3) Remove algo --------------- +3) Removal algorithm +-------------------- + Nothing special here, we can use a standard RCU hlist deletion. But thanks to SLAB_TYPESAFE_BY_RCU, beware a deleted object can be reused very very fast (before the end of RCU grace period) @@ -133,7 +130,7 @@ Avoiding extra smp_rmb() ======================== With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup() -and extra smp_wmb() in insert function. +and extra _release() in insert function. 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,59 +139,61 @@ to another chain) checking the final 'nulls' value if the lookup met the end of chain. If final 'nulls' value is not the slot number, then we must restart the lookup at the beginning. If the object was moved to the same chain, -then the reader doesn't care : It might eventually +then the reader doesn't care: It might occasionally scan the list again without harm. -1) lookup algo --------------- +1) lookup algorithm +------------------- :: head = &table[slot]; - rcu_read_lock(); begin: + rcu_read_lock(); hlist_nulls_for_each_entry_rcu(obj, node, head, member) { if (obj->key == key) { - 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; + } if (obj->key != key) { // not the object we expected put_ref(obj); + rcu_read_unlock(); goto begin; } - goto out; + goto out; + } + } + + // If the nulls value we got at the end of this lookup is + // not the expected one, we must restart lookup. + // We probably met an item that was moved to another chain. + if (get_nulls_value(node) != slot) { + put_ref(obj); + rcu_read_unlock(); + goto begin; } - /* - * if the nulls value we got at the end of this lookup is - * not the expected one, we must restart lookup. - * We probably met an item that was moved to another chain. - */ - if (get_nulls_value(node) != slot) - goto begin; obj = NULL; out: rcu_read_unlock(); -2) Insert function ------------------- +2) Insert algorithm +------------------- :: /* - * Please note that new inserts are done at the head of list, - * not in the middle or end. - */ + * Please note that new inserts are done at the head of list, + * not in the middle or end. + */ obj = kmem_cache_alloc(cachep); lock_chain(); // typically a spin_lock() obj->key = key; + atomic_set_release(&obj->refcnt, 1); // key before refcnt /* - * changes to obj->key must be visible before refcnt one - */ - smp_wmb(); - atomic_set(&obj->refcnt, 1); - /* - * insert obj in RCU way (readers might be traversing chain) - */ + * insert obj in RCU way (readers might be traversing chain) + */ hlist_nulls_add_head_rcu(&obj->obj_node, list); unlock_chain(); // typically a spin_unlock() diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst index e38c587067fc..ca7b7cd806a1 100644 --- a/Documentation/RCU/stallwarn.rst +++ b/Documentation/RCU/stallwarn.rst @@ -25,10 +25,10 @@ warnings: - A CPU looping with bottom halves disabled. -- For !CONFIG_PREEMPTION kernels, a CPU looping anywhere in the kernel - without invoking schedule(). If the looping in the kernel is - really expected and desirable behavior, you might need to add - some calls to cond_resched(). +- For !CONFIG_PREEMPTION kernels, a CPU looping anywhere in the + kernel without potentially invoking schedule(). If the looping + in the kernel is really expected and desirable behavior, you + might need to add some calls to cond_resched(). - Booting Linux using a console connection that is too slow to keep up with the boot-time console-message rate. For example, @@ -108,16 +108,17 @@ warnings: - A bug in the RCU implementation. -- A hardware failure. This is quite unlikely, but has occurred - at least once in real life. A CPU failed in a running system, - becoming unresponsive, but not causing an immediate crash. - This resulted in a series of RCU CPU stall warnings, eventually - leading the realization that the CPU had failed. +- A hardware failure. This is quite unlikely, but is not at all + uncommon in large datacenter. In one memorable case some decades + back, a CPU failed in a running system, becoming unresponsive, + but not causing an immediate crash. This resulted in a series + of RCU CPU stall warnings, eventually leading the realization + that the CPU had failed. -The RCU, RCU-sched, and RCU-tasks implementations have CPU stall warning. -Note that SRCU does *not* have CPU stall warnings. Please note that -RCU only detects CPU stalls when there is a grace period in progress. -No grace period, no CPU stall warnings. +The RCU, RCU-sched, RCU-tasks, and RCU-tasks-trace implementations have +CPU stall warning. Note that SRCU does *not* have CPU stall warnings. +Please note that RCU only detects CPU stalls when there is a grace period +in progress. No grace period, no CPU stall warnings. To diagnose the cause of the stall, inspect the stack traces. The offending function will usually be near the top of the stack. @@ -205,16 +206,21 @@ RCU_STALL_RAT_DELAY rcupdate.rcu_task_stall_timeout ------------------------------- - This boot/sysfs parameter controls the RCU-tasks stall warning - interval. A value of zero or less suppresses RCU-tasks stall - warnings. A positive value sets the stall-warning interval - in seconds. An RCU-tasks stall warning starts with the line: + This boot/sysfs parameter controls the RCU-tasks and + RCU-tasks-trace stall warning intervals. A value of zero or less + suppresses RCU-tasks stall warnings. A positive value sets the + stall-warning interval in seconds. An RCU-tasks stall warning + starts with the line: INFO: rcu_tasks detected stalls on tasks: And continues with the output of sched_show_task() for each task stalling the current RCU-tasks grace period. + An RCU-tasks-trace stall warning starts (and continues) similarly: + + INFO: rcu_tasks_trace detected stalls on tasks + Interpreting RCU's CPU Stall-Detector "Splats" ============================================== @@ -248,7 +254,8 @@ dynticks counter, which will have an even-numbered value if the CPU is in dyntick-idle mode and an odd-numbered value otherwise. The hex number between the two "/"s is the value of the nesting, which will be a small non-negative number if in the idle loop (as shown above) and a -very large positive number otherwise. +very large positive number otherwise. The number following the final +"/" is the NMI nesting, which will be a small non-negative number. The "softirq=" portion of the message tracks the number of RCU softirq handlers that the stalled CPU has executed. The number before the "/" @@ -383,3 +390,95 @@ for example, "P3421". It is entirely possible to see stall warnings from normal and from expedited grace periods at about the same time during the same run. + +RCU_CPU_STALL_CPUTIME +===================== + +In kernels built with CONFIG_RCU_CPU_STALL_CPUTIME=y or booted with +rcupdate.rcu_cpu_stall_cputime=1, the following additional information +is supplied with each RCU CPU stall warning:: + + rcu: hardirqs softirqs csw/system + rcu: number: 624 45 0 + rcu: cputime: 69 1 2425 ==> 2500(ms) + +These statistics are collected during the sampling period. The values +in row "number:" are the number of hard interrupts, number of soft +interrupts, and number of context switches on the stalled CPU. The +first three values in row "cputime:" indicate the CPU time in +milliseconds consumed by hard interrupts, soft interrupts, and tasks +on the stalled CPU. The last number is the measurement interval, again +in milliseconds. Because user-mode tasks normally do not cause RCU CPU +stalls, these tasks are typically kernel tasks, which is why only the +system CPU time are considered. + +The sampling period is shown as follows:: + + |<------------first timeout---------->|<-----second timeout----->| + |<--half timeout-->|<--half timeout-->| | + | |<--first period-->| | + | |<-----------second sampling period---------->| + | | | | + snapshot time point 1st-stall 2nd-stall + +The following describes four typical scenarios: + +1. A CPU looping with interrupts disabled. + + :: + + rcu: hardirqs softirqs csw/system + rcu: number: 0 0 0 + rcu: cputime: 0 0 0 ==> 2500(ms) + + Because interrupts have been disabled throughout the measurement + interval, there are no interrupts and no context switches. + Furthermore, because CPU time consumption was measured using interrupt + handlers, the system CPU consumption is misleadingly measured as zero. + This scenario will normally also have "(0 ticks this GP)" printed on + this CPU's summary line. + +2. A CPU looping with bottom halves disabled. + + This is similar to the previous example, but with non-zero number of + and CPU time consumed by hard interrupts, along with non-zero CPU + time consumed by in-kernel execution:: + + rcu: hardirqs softirqs csw/system + rcu: number: 624 0 0 + rcu: cputime: 49 0 2446 ==> 2500(ms) + + The fact that there are zero softirqs gives a hint that these were + disabled, perhaps via local_bh_disable(). It is of course possible + that there were no softirqs, perhaps because all events that would + result in softirq execution are confined to other CPUs. In this case, + the diagnosis should continue as shown in the next example. + +3. A CPU looping with preemption disabled. + + Here, only the number of context switches is zero:: + + rcu: hardirqs softirqs csw/system + rcu: number: 624 45 0 + rcu: cputime: 69 1 2425 ==> 2500(ms) + + This situation hints that the stalled CPU was looping with preemption + disabled. + +4. No looping, but massive hard and soft interrupts. + + :: + + rcu: hardirqs softirqs csw/system + rcu: number: xx xx 0 + rcu: cputime: xx xx 0 ==> 2500(ms) + + Here, the number and CPU time of hard interrupts are all non-zero, + but the number of context switches and the in-kernel CPU time consumed + are zero. The number and cputime of soft interrupts will usually be + non-zero, but could be zero, for example, if the CPU was spinning + within a single hard interrupt handler. + + If this type of RCU CPU stall warning can be reproduced, you can + narrow it down by looking at /proc/interrupts or by writing code to + trace each interrupt, for example, by referring to show_interrupts(). diff --git a/Documentation/RCU/torture.rst b/Documentation/RCU/torture.rst index a90147713062..0316ba0c6922 100644 --- a/Documentation/RCU/torture.rst +++ b/Documentation/RCU/torture.rst @@ -206,7 +206,11 @@ values for memory may require disabling the callback-flooding tests using the --bootargs parameter discussed below. Sometimes additional debugging is useful, and in such cases the --kconfig -parameter to kvm.sh may be used, for example, ``--kconfig 'CONFIG_KASAN=y'``. +parameter to kvm.sh may be used, for example, ``--kconfig 'CONFIG_RCU_EQS_DEBUG=y'``. +In addition, there are the --gdb, --kasan, and --kcsan parameters. +Note that --gdb limits you to one scenario per kvm.sh run and requires +that you have another window open from which to run ``gdb`` as instructed +by the script. Kernel boot arguments can also be supplied, for example, to control rcutorture's module parameters. For example, to test a change to RCU's @@ -219,10 +223,17 @@ require disabling rcutorture's callback-flooding tests:: --bootargs 'rcutorture.fwd_progress=0' Sometimes all that is needed is a full set of kernel builds. This is -what the --buildonly argument does. +what the --buildonly parameter does. -Finally, the --trust-make argument allows each kernel build to reuse what -it can from the previous kernel build. +The --duration parameter can override the default run time of 30 minutes. +For example, ``--duration 2d`` would run for two days, ``--duration 3h`` +would run for three hours, ``--duration 5m`` would run for five minutes, +and ``--duration 45s`` would run for 45 seconds. This last can be useful +for tracking down rare boot-time failures. + +Finally, the --trust-make parameter allows each kernel build to reuse what +it can from the previous kernel build. Please note that without the +--trust-make parameter, your tags files may be demolished. There are additional more arcane arguments that are documented in the source code of the kvm.sh script. @@ -291,3 +302,73 @@ the following summary at the end of the run on a 12-CPU system:: TREE07 ------- 167347 GPs (30.9902/s) [rcu: g1079021 f0x0 ] n_max_cbs: 478732 CPU count limited from 16 to 12 TREE09 ------- 752238 GPs (139.303/s) [rcu: g13075057 f0x0 ] n_max_cbs: 99011 + + +Repeated Runs +============= + +Suppose that you are chasing down a rare boot-time failure. Although you +could use kvm.sh, doing so will rebuild the kernel on each run. If you +need (say) 1,000 runs to have confidence that you have fixed the bug, +these pointless rebuilds can become extremely annoying. + +This is why kvm-again.sh exists. + +Suppose that a previous kvm.sh run left its output in this directory:: + + tools/testing/selftests/rcutorture/res/2022.11.03-11.26.28 + +Then this run can be re-run without rebuilding as follow: + + kvm-again.sh tools/testing/selftests/rcutorture/res/2022.11.03-11.26.28 + +A few of the original run's kvm.sh parameters may be overridden, perhaps +most notably --duration and --bootargs. For example:: + + kvm-again.sh tools/testing/selftests/rcutorture/res/2022.11.03-11.26.28 \ + --duration 45s + +would re-run the previous test, but for only 45 seconds, thus facilitating +tracking down the aforementioned rare boot-time failure. + + +Distributed Runs +================ + +Although kvm.sh is quite useful, its testing is confined to a single +system. It is not all that hard to use your favorite framework to cause +(say) 5 instances of kvm.sh to run on your 5 systems, but this will very +likely unnecessarily rebuild kernels. In addition, manually distributing +the desired rcutorture scenarios across the available systems can be +painstaking and error-prone. + +And this is why the kvm-remote.sh script exists. + +If you the following command works:: + + ssh system0 date + +and if it also works for system1, system2, system3, system4, and system5, +and all of these systems have 64 CPUs, you can type:: + + kvm-remote.sh "system0 system1 system2 system3 system4 system5" \ + --cpus 64 --duration 8h --configs "5*CFLIST" + +This will build each default scenario's kernel on the local system, then +spread each of five instances of each scenario over the systems listed, +running each scenario for eight hours. At the end of the runs, the +results will be gathered, recorded, and printed. Most of the parameters +that kvm.sh will accept can be passed to kvm-remote.sh, but the list of +systems must come first. + +The kvm.sh ``--dryrun scenarios`` argument is useful for working out +how many scenarios may be run in one batch across a group of systems. + +You can also re-run a previous remote run in a manner similar to kvm.sh: + + kvm-remote.sh "system0 system1 system2 system3 system4 system5" \ + tools/testing/selftests/rcutorture/res/2022.11.03-11.26.28-remote \ + --duration 24h + +In this case, most of the kvm-again.sh parmeters may be supplied following +the pathname of the old run-results directory. diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst index 1c747ac3f2c8..2c5563a91998 100644 --- a/Documentation/RCU/whatisRCU.rst +++ b/Documentation/RCU/whatisRCU.rst @@ -16,18 +16,23 @@ to start learning about RCU: | 6. The RCU API, 2019 Edition https://lwn.net/Articles/777036/ | 2019 Big API Table https://lwn.net/Articles/777165/ +For those preferring video: + +| 1. Unraveling RCU Mysteries: Fundamentals https://www.linuxfoundation.org/webinars/unraveling-rcu-usage-mysteries +| 2. Unraveling RCU Mysteries: Additional Use Cases https://www.linuxfoundation.org/webinars/unraveling-rcu-usage-mysteries-additional-use-cases + What is RCU? RCU is a synchronization mechanism that was added to the Linux kernel during the 2.5 development effort that is optimized for read-mostly -situations. Although RCU is actually quite simple once you understand it, -getting there can sometimes be a challenge. Part of the problem is that -most of the past descriptions of RCU have been written with the mistaken -assumption that there is "one true way" to describe RCU. Instead, -the experience has been that different people must take different paths -to arrive at an understanding of RCU. This document provides several -different paths, as follows: +situations. Although RCU is actually quite simple, making effective use +of it requires you to think differently about your code. Another part +of the problem is the mistaken assumption that there is "one true way" to +describe and to use RCU. Instead, the experience has been that different +people must take different paths to arrive at an understanding of RCU, +depending on their experiences and use cases. This document provides +several different paths, as follows: :ref:`1. RCU OVERVIEW <1_whatisRCU>` @@ -157,34 +162,36 @@ rcu_read_lock() ^^^^^^^^^^^^^^^ void rcu_read_lock(void); - Used by a reader to inform the reclaimer that the reader is - entering an RCU read-side critical section. It is illegal - to block while in an RCU read-side critical section, though - kernels built with CONFIG_PREEMPT_RCU can preempt RCU - read-side critical sections. Any RCU-protected data structure - accessed during an RCU read-side critical section is guaranteed to - remain unreclaimed for the full duration of that critical section. - Reference counts may be used in conjunction with RCU to maintain - longer-term references to data structures. + This temporal primitive is used by a reader to inform the + reclaimer that the reader is entering an RCU read-side critical + section. It is illegal to block while in an RCU read-side + critical section, though kernels built with CONFIG_PREEMPT_RCU + can preempt RCU read-side critical sections. Any RCU-protected + data structure accessed during an RCU read-side critical section + is guaranteed to remain unreclaimed for the full duration of that + critical section. Reference counts may be used in conjunction + with RCU to maintain longer-term references to data structures. rcu_read_unlock() ^^^^^^^^^^^^^^^^^ void rcu_read_unlock(void); - Used by a reader to inform the reclaimer that the reader is - exiting an RCU read-side critical section. Note that RCU - read-side critical sections may be nested and/or overlapping. + This temporal primitives is used by a reader to inform the + reclaimer that the reader is exiting an RCU read-side critical + section. Note that RCU read-side critical sections may be nested + and/or overlapping. synchronize_rcu() ^^^^^^^^^^^^^^^^^ void synchronize_rcu(void); - Marks the end of updater code and the beginning of reclaimer - code. It does this by blocking until all pre-existing RCU - read-side critical sections on all CPUs have completed. - Note that synchronize_rcu() will **not** necessarily wait for - any subsequent RCU read-side critical sections to complete. - For example, consider the following sequence of events:: + This temporal primitive marks the end of updater code and the + beginning of reclaimer code. It does this by blocking until + all pre-existing RCU read-side critical sections on all CPUs + have completed. Note that synchronize_rcu() will **not** + necessarily wait for any subsequent RCU read-side critical + sections to complete. For example, consider the following + sequence of events:: CPU 0 CPU 1 CPU 2 ----------------- ------------------------- --------------- @@ -211,13 +218,13 @@ synchronize_rcu() to be useful in all but the most read-intensive situations, synchronize_rcu()'s overhead must also be quite small. - The call_rcu() API is a callback form of synchronize_rcu(), - and is described in more detail in a later section. Instead of - blocking, it registers a function and argument which are invoked - after all ongoing RCU read-side critical sections have completed. - This callback variant is particularly useful in situations where - it is illegal to block or where update-side performance is - critically important. + The call_rcu() API is an asynchronous callback form of + synchronize_rcu(), and is described in more detail in a later + section. Instead of blocking, it registers a function and + argument which are invoked after all ongoing RCU read-side + critical sections have completed. This callback variant is + particularly useful in situations where it is illegal to block + or where update-side performance is critically important. However, the call_rcu() API should not be used lightly, as use of the synchronize_rcu() API generally results in simpler code. @@ -236,11 +243,13 @@ rcu_assign_pointer() would be cool to be able to declare a function in this manner. (Compiler experts will no doubt disagree.) - The updater uses this function to assign a new value to an + The updater uses this spatial macro to assign a new value to an RCU-protected pointer, in order to safely communicate the change - in value from the updater to the reader. This macro does not - evaluate to an rvalue, but it does execute any memory-barrier - instructions required for a given CPU architecture. + in value from the updater to the reader. This is a spatial (as + opposed to temporal) macro. It does not evaluate to an rvalue, + but it does execute any memory-barrier instructions required + for a given CPU architecture. Its ordering properties are that + of a store-release operation. Perhaps just as important, it serves to document (1) which pointers are protected by RCU and (2) the point at which a @@ -255,14 +264,15 @@ rcu_dereference() Like rcu_assign_pointer(), rcu_dereference() must be implemented as a macro. - The reader uses rcu_dereference() to fetch an RCU-protected - pointer, which returns a value that may then be safely - dereferenced. Note that rcu_dereference() does not actually - dereference the pointer, instead, it protects the pointer for - later dereferencing. It also executes any needed memory-barrier - instructions for a given CPU architecture. Currently, only Alpha - needs memory barriers within rcu_dereference() -- on other CPUs, - it compiles to nothing, not even a compiler directive. + The reader uses the spatial rcu_dereference() macro to fetch + an RCU-protected pointer, which returns a value that may + then be safely dereferenced. Note that rcu_dereference() + does not actually dereference the pointer, instead, it + protects the pointer for later dereferencing. It also + executes any needed memory-barrier instructions for a given + CPU architecture. Currently, only Alpha needs memory barriers + within rcu_dereference() -- on other CPUs, it compiles to a + volatile load. Common coding practice uses rcu_dereference() to copy an RCU-protected pointer to a local variable, then dereferences @@ -355,12 +365,15 @@ reader, updater, and reclaimer. synchronize_rcu() & call_rcu() -The RCU infrastructure observes the time sequence of rcu_read_lock(), +The RCU infrastructure observes the temporal sequence of rcu_read_lock(), rcu_read_unlock(), synchronize_rcu(), and call_rcu() invocations in order to determine when (1) synchronize_rcu() invocations may return to their callers and (2) call_rcu() callbacks may be invoked. Efficient implementations of the RCU infrastructure make heavy use of batching in order to amortize their overhead over many uses of the corresponding APIs. +The rcu_assign_pointer() and rcu_dereference() invocations communicate +spatial changes via stores to and loads from the RCU-protected pointer in +question. There are at least three flavors of RCU usage in the Linux kernel. The diagram above shows the most common one. On the updater side, the rcu_assign_pointer(), @@ -392,7 +405,9 @@ b. RCU applied to networking data structures that may be subjected c. RCU applied to scheduler and interrupt/NMI-handler tasks. Again, most uses will be of (a). The (b) and (c) cases are important -for specialized uses, but are relatively uncommon. +for specialized uses, but are relatively uncommon. The SRCU, RCU-Tasks, +RCU-Tasks-Rude, and RCU-Tasks-Trace have similar relationships among +their assorted primitives. .. _3_whatisRCU: @@ -468,7 +483,7 @@ So, to sum up: - Within an RCU read-side critical section, use rcu_dereference() to dereference RCU-protected pointers. -- Use some solid scheme (such as locks or semaphores) to +- Use some solid design (such as locks or semaphores) to keep concurrent updates from interfering with each other. - Use rcu_assign_pointer() to update an RCU-protected pointer. @@ -579,6 +594,14 @@ to avoid having to write your own callback:: kfree_rcu(old_fp, rcu); +If the occasional sleep is permitted, the single-argument form may +be used, omitting the rcu_head structure from struct foo. + + kfree_rcu(old_fp); + +This variant of kfree_rcu() almost never blocks, but might do so by +invoking synchronize_rcu() in response to memory-allocation failure. + Again, see checklist.rst for additional rules governing the use of RCU. .. _5_whatisRCU: @@ -596,7 +619,7 @@ lacking both functionality and performance. However, they are useful in getting a feel for how RCU works. See kernel/rcu/update.c for a production-quality implementation, and see: - http://www.rdrop.com/users/paulmck/RCU + https://docs.google.com/document/d/1X0lThx8OK0ZgLMqVoXiR4ZrGURHrXK6NyLRbeXe3Xac/edit for papers describing the Linux kernel RCU implementation. The OLS'01 and OLS'02 papers are a good introduction, and the dissertation provides @@ -929,6 +952,8 @@ unfortunately any spinlock in a ``SLAB_TYPESAFE_BY_RCU`` object must be initialized after each and every call to kmem_cache_alloc(), which renders reference-free spinlock acquisition completely unsafe. Therefore, when using ``SLAB_TYPESAFE_BY_RCU``, make proper use of a reference counter. +(Those willing to use a kmem_cache constructor may also use locking, +including cache-friendly sequence locking.) With traditional reference counting -- such as that implemented by the kref library in Linux -- there is typically code that runs when the last @@ -1047,6 +1072,30 @@ sched:: rcu_read_lock_sched_held +RCU-Tasks:: + + Critical sections Grace period Barrier + + N/A call_rcu_tasks rcu_barrier_tasks + synchronize_rcu_tasks + + +RCU-Tasks-Rude:: + + Critical sections Grace period Barrier + + N/A call_rcu_tasks_rude rcu_barrier_tasks_rude + synchronize_rcu_tasks_rude + + +RCU-Tasks-Trace:: + + Critical sections Grace period Barrier + + rcu_read_lock_trace call_rcu_tasks_trace rcu_barrier_tasks_trace + rcu_read_unlock_trace synchronize_rcu_tasks_trace + + SRCU:: Critical sections Grace period Barrier @@ -1087,35 +1136,43 @@ list can be helpful: a. Will readers need to block? If so, you need SRCU. -b. What about the -rt patchset? If readers would need to block - in an non-rt kernel, you need SRCU. If readers would block - in a -rt kernel, but not in a non-rt kernel, SRCU is not - necessary. (The -rt patchset turns spinlocks into sleeplocks, - hence this distinction.) +b. Will readers need to block and are you doing tracing, for + example, ftrace or BPF? If so, you need RCU-tasks, + RCU-tasks-rude, and/or RCU-tasks-trace. + +c. What about the -rt patchset? If readers would need to block in + an non-rt kernel, you need SRCU. If readers would block when + acquiring spinlocks in a -rt kernel, but not in a non-rt kernel, + SRCU is not necessary. (The -rt patchset turns spinlocks into + sleeplocks, hence this distinction.) -c. Do you need to treat NMI handlers, hardirq handlers, +d. Do you need to treat NMI handlers, hardirq handlers, and code segments with preemption disabled (whether via preempt_disable(), local_irq_save(), local_bh_disable(), or some other mechanism) as if they were explicit RCU readers? - If so, RCU-sched is the only choice that will work for you. - -d. Do you need RCU grace periods to complete even in the face - of softirq monopolization of one or more of the CPUs? For - example, is your code subject to network-based denial-of-service - attacks? If so, you should disable softirq across your readers, - for example, by using rcu_read_lock_bh(). - -e. Is your workload too update-intensive for normal use of + If so, RCU-sched readers are the only choice that will work + for you, but since about v4.20 you use can use the vanilla RCU + update primitives. + +e. Do you need RCU grace periods to complete even in the face of + softirq monopolization of one or more of the CPUs? For example, + is your code subject to network-based denial-of-service attacks? + If so, you should disable softirq across your readers, for + example, by using rcu_read_lock_bh(). Since about v4.20 you + use can use the vanilla RCU update primitives. + +f. Is your workload too update-intensive for normal use of RCU, but inappropriate for other synchronization mechanisms? If so, consider SLAB_TYPESAFE_BY_RCU (which was originally named SLAB_DESTROY_BY_RCU). But please be careful! -f. Do you need read-side critical sections that are respected - even though they are in the middle of the idle loop, during - user-mode execution, or on an offlined CPU? If so, SRCU is the - only choice that will work for you. +g. Do you need read-side critical sections that are respected even + on CPUs that are deep in the idle loop, during entry to or exit + from user-mode execution, or on an offlined CPU? If so, SRCU + and RCU Tasks Trace are the only choices that will work for you, + with SRCU being strongly preferred in almost all cases. -g. Otherwise, use RCU. +h. Otherwise, use RCU. Of course, this all assumes that you have determined that RCU is in fact the right tool for your job. diff --git a/Documentation/accel/introduction.rst b/Documentation/accel/introduction.rst index 6f31af14b1fc..89984dfececf 100644 --- a/Documentation/accel/introduction.rst +++ b/Documentation/accel/introduction.rst @@ -67,9 +67,9 @@ tree - drivers/accel/. The accelerator devices will be exposed to the user space with the dedicated 261 major number and will have the following convention: -- device char files - /dev/accel/accel* -- sysfs - /sys/class/accel/accel*/ -- debugfs - /sys/kernel/debug/accel/accel*/ +- device char files - /dev/accel/accel\* +- sysfs - /sys/class/accel/accel\*/ +- debugfs - /sys/kernel/debug/accel/\*/ Getting Started =============== diff --git a/Documentation/admin-guide/bcache.rst b/Documentation/admin-guide/bcache.rst index 8d3a2d045c0a..bb5032a99234 100644 --- a/Documentation/admin-guide/bcache.rst +++ b/Documentation/admin-guide/bcache.rst @@ -204,7 +204,7 @@ For example:: This should present your unmodified backing device data in /dev/loop0 If your cache is in writethrough mode, then you can safely discard the -cache device without loosing data. +cache device without losing data. E) Wiping a cache device diff --git a/Documentation/admin-guide/blockdev/paride.rst b/Documentation/admin-guide/blockdev/paride.rst index e1ce90af602a..e85ad37cc0e5 100644 --- a/Documentation/admin-guide/blockdev/paride.rst +++ b/Documentation/admin-guide/blockdev/paride.rst @@ -3,6 +3,7 @@ Linux and parallel port IDE devices =================================== PARIDE v1.03 (c) 1997-8 Grant Guenther <grant@torque.net> +PATA_PARPORT (c) 2023 Ondrej Zary 1. Introduction =============== @@ -51,27 +52,15 @@ parallel port IDE subsystem, including: as well as most of the clone and no-name products on the market. -To support such a wide range of devices, PARIDE, the parallel port IDE -subsystem, is actually structured in three parts. There is a base -paride module which provides a registry and some common methods for -accessing the parallel ports. The second component is a set of -high-level drivers for each of the different types of supported devices: +To support such a wide range of devices, pata_parport is actually structured +in two parts. There is a base pata_parport module which provides an interface +to kernel libata subsystem, registry and some common methods for accessing +the parallel ports. - === ============= - pd IDE disk - pcd ATAPI CD-ROM - pf ATAPI disk - pt ATAPI tape - pg ATAPI generic - === ============= - -(Currently, the pg driver is only used with CD-R drives). - -The high-level drivers function according to the relevant standards. -The third component of PARIDE is a set of low-level protocol drivers -for each of the parallel port IDE adapter chips. Thanks to the interest -and encouragement of Linux users from many parts of the world, -support is available for almost all known adapter protocols: +The second component is a set of low-level protocol drivers for each of the +parallel port IDE adapter chips. Thanks to the interest and encouragement of +Linux users from many parts of the world, support is available for almost all +known adapter protocols: ==== ====================================== ==== aten ATEN EH-100 (HK) @@ -91,251 +80,87 @@ support is available for almost all known adapter protocols: ==== ====================================== ==== -2. Using the PARIDE subsystem -============================= +2. Using pata_parport subsystem +=============================== While configuring the Linux kernel, you may choose either to build -the PARIDE drivers into your kernel, or to build them as modules. +the pata_parport drivers into your kernel, or to build them as modules. In either case, you will need to select "Parallel port IDE device support" -as well as at least one of the high-level drivers and at least one -of the parallel port communication protocols. If you do not know -what kind of parallel port adapter is used in your drive, you could -begin by checking the file names and any text files on your DOS +and at least one of the parallel port communication protocols. +If you do not know what kind of parallel port adapter is used in your drive, +you could begin by checking the file names and any text files on your DOS installation floppy. Alternatively, you can look at the markings on the adapter chip itself. That's usually sufficient to identify the correct device. -You can actually select all the protocol modules, and allow the PARIDE +You can actually select all the protocol modules, and allow the pata_parport subsystem to try them all for you. For the "brand-name" products listed above, here are the protocol and high-level drivers that you would use: - ================ ============ ====== ======== - Manufacturer Model Driver Protocol - ================ ============ ====== ======== - MicroSolutions CD-ROM pcd bpck - MicroSolutions PD drive pf bpck - MicroSolutions hard-drive pd bpck - MicroSolutions 8000t tape pt bpck - SyQuest EZ, SparQ pd epat - Imation Superdisk pf epat - Maxell Superdisk pf friq - Avatar Shark pd epat - FreeCom CD-ROM pcd frpw - Hewlett-Packard 5GB Tape pt epat - Hewlett-Packard 7200e (CD) pcd epat - Hewlett-Packard 7200e (CD-R) pg epat - ================ ============ ====== ======== - -2.1 Configuring built-in drivers ---------------------------------- - -We recommend that you get to know how the drivers work and how to -configure them as loadable modules, before attempting to compile a -kernel with the drivers built-in. - -If you built all of your PARIDE support directly into your kernel, -and you have just a single parallel port IDE device, your kernel should -locate it automatically for you. If you have more than one device, -you may need to give some command line options to your bootloader -(eg: LILO), how to do that is beyond the scope of this document. - -The high-level drivers accept a number of command line parameters, all -of which are documented in the source files in linux/drivers/block/paride. -By default, each driver will automatically try all parallel ports it -can find, and all protocol types that have been installed, until it finds -a parallel port IDE adapter. Once it finds one, the probe stops. So, -if you have more than one device, you will need to tell the drivers -how to identify them. This requires specifying the port address, the -protocol identification number and, for some devices, the drive's -chain ID. While your system is booting, a number of messages are -displayed on the console. Like all such messages, they can be -reviewed with the 'dmesg' command. Among those messages will be -some lines like:: - - paride: bpck registered as protocol 0 - paride: epat registered as protocol 1 - -The numbers will always be the same until you build a new kernel with -different protocol selections. You should note these numbers as you -will need them to identify the devices. + ================ ============ ======== + Manufacturer Model Protocol + ================ ============ ======== + MicroSolutions CD-ROM bpck + MicroSolutions PD drive bpck + MicroSolutions hard-drive bpck + MicroSolutions 8000t tape bpck + SyQuest EZ, SparQ epat + Imation Superdisk epat + Maxell Superdisk friq + Avatar Shark epat + FreeCom CD-ROM frpw + Hewlett-Packard 5GB Tape epat + Hewlett-Packard 7200e (CD) epat + Hewlett-Packard 7200e (CD-R) epat + ================ ============ ======== + +All parports and all protocol drivers are probed automatically unless probe=0 +parameter is used. So just "modprobe epat" is enough for a Imation SuperDisk +drive to work. + +Manual device creation:: + + # echo "port protocol mode unit delay" >/sys/bus/pata_parport/new_device + +where: + + ======== ================================================ + port parport name (or "auto" for all parports) + protocol protocol name (or "auto" for all protocols) + mode mode number (protocol-specific) or -1 for probe + unit unit number (for backpack only, see below) + delay I/O delay (see troubleshooting section below) + ======== ================================================ If you happen to be using a MicroSolutions backpack device, you will also need to know the unit ID number for each drive. This is usually the last two digits of the drive's serial number (but read MicroSolutions' documentation about this). -As an example, let's assume that you have a MicroSolutions PD/CD drive -with unit ID number 36 connected to the parallel port at 0x378, a SyQuest -EZ-135 connected to the chained port on the PD/CD drive and also an -Imation Superdisk connected to port 0x278. You could give the following -options on your boot command:: - - pd.drive0=0x378,1 pf.drive0=0x278,1 pf.drive1=0x378,0,36 - -In the last option, pf.drive1 configures device /dev/pf1, the 0x378 -is the parallel port base address, the 0 is the protocol registration -number and 36 is the chain ID. - -Please note: while PARIDE will work both with and without the -PARPORT parallel port sharing system that is included by the -"Parallel port support" option, PARPORT must be included and enabled -if you want to use chains of devices on the same parallel port. - -2.2 Loading and configuring PARIDE as modules ----------------------------------------------- - -It is much faster and simpler to get to understand the PARIDE drivers -if you use them as loadable kernel modules. - -Note 1: - using these drivers with the "kerneld" automatic module loading - system is not recommended for beginners, and is not documented here. - -Note 2: - if you build PARPORT support as a loadable module, PARIDE must - also be built as loadable modules, and PARPORT must be loaded before - the PARIDE modules. - -To use PARIDE, you must begin by:: - - insmod paride - -this loads a base module which provides a registry for the protocols, -among other tasks. - -Then, load as many of the protocol modules as you think you might need. -As you load each module, it will register the protocols that it supports, -and print a log message to your kernel log file and your console. For -example:: - - # insmod epat - paride: epat registered as protocol 0 - # insmod kbic - paride: k951 registered as protocol 1 - paride: k971 registered as protocol 2 - -Finally, you can load high-level drivers for each kind of device that -you have connected. By default, each driver will autoprobe for a single -device, but you can support up to four similar devices by giving their -individual coordinates when you load the driver. - -For example, if you had two no-name CD-ROM drives both using the -KingByte KBIC-951A adapter, one on port 0x378 and the other on 0x3bc -you could give the following command:: - - # insmod pcd drive0=0x378,1 drive1=0x3bc,1 - -For most adapters, giving a port address and protocol number is sufficient, -but check the source files in linux/drivers/block/paride for more -information. (Hopefully someone will write some man pages one day !). - -As another example, here's what happens when PARPORT is installed, and -a SyQuest EZ-135 is attached to port 0x378:: - - # insmod paride - paride: version 1.0 installed - # insmod epat - paride: epat registered as protocol 0 - # insmod pd - pd: pd version 1.0, major 45, cluster 64, nice 0 - pda: Sharing parport1 at 0x378 - pda: epat 1.0, Shuttle EPAT chip c3 at 0x378, mode 5 (EPP-32), delay 1 - pda: SyQuest EZ135A, 262144 blocks [128M], (512/16/32), removable media - pda: pda1 - -Note that the last line is the output from the generic partition table -scanner - in this case it reports that it has found a disk with one partition. - -2.3 Using a PARIDE device --------------------------- - -Once the drivers have been loaded, you can access PARIDE devices in the -same way as their traditional counterparts. You will probably need to -create the device "special files". Here is a simple script that you can -cut to a file and execute:: - - #!/bin/bash - # - # mkd -- a script to create the device special files for the PARIDE subsystem - # - function mkdev { - mknod $1 $2 $3 $4 ; chmod 0660 $1 ; chown root:disk $1 - } - # - function pd { - D=$( printf \\$( printf "x%03x" $[ $1 + 97 ] ) ) - mkdev pd$D b 45 $[ $1 * 16 ] - for P in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 - do mkdev pd$D$P b 45 $[ $1 * 16 + $P ] - done - } - # - cd /dev - # - for u in 0 1 2 3 ; do pd $u ; done - for u in 0 1 2 3 ; do mkdev pcd$u b 46 $u ; done - for u in 0 1 2 3 ; do mkdev pf$u b 47 $u ; done - for u in 0 1 2 3 ; do mkdev pt$u c 96 $u ; done - for u in 0 1 2 3 ; do mkdev npt$u c 96 $[ $u + 128 ] ; done - for u in 0 1 2 3 ; do mkdev pg$u c 97 $u ; done - # - # end of mkd - -With the device files and drivers in place, you can access PARIDE devices -like any other Linux device. For example, to mount a CD-ROM in pcd0, use:: - - mount /dev/pcd0 /cdrom - -If you have a fresh Avatar Shark cartridge, and the drive is pda, you -might do something like:: - - fdisk /dev/pda -- make a new partition table with - partition 1 of type 83 - - mke2fs /dev/pda1 -- to build the file system - - mkdir /shark -- make a place to mount the disk - - mount /dev/pda1 /shark - -Devices like the Imation superdisk work in the same way, except that -they do not have a partition table. For example to make a 120MB -floppy that you could share with a DOS system:: - - mkdosfs /dev/pf0 - mount /dev/pf0 /mnt - - -2.4 The pf driver ------------------- - -The pf driver is intended for use with parallel port ATAPI disk -devices. The most common devices in this category are PD drives -and LS-120 drives. Traditionally, media for these devices are not -partitioned. Consequently, the pf driver does not support partitioned -media. This may be changed in a future version of the driver. - -2.5 Using the pt driver ------------------------- - -The pt driver for parallel port ATAPI tape drives is a minimal driver. -It does not yet support many of the standard tape ioctl operations. -For best performance, a block size of 32KB should be used. You will -probably want to set the parallel port delay to 0, if you can. - -2.6 Using the pg driver ------------------------- - -The pg driver can be used in conjunction with the cdrecord program -to create CD-ROMs. Please get cdrecord version 1.6.1 or later -from ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/ . To record CD-R media -your parallel port should ideally be set to EPP mode, and the "port delay" -should be set to 0. With those settings it is possible to record at 2x -speed without any buffer underruns. If you cannot get the driver to work -in EPP mode, try to use "bidirectional" or "PS/2" mode and 1x speeds only. +If you omit the parameters from the end, defaults will be used, e.g.: + +Probe all parports with all protocols:: + + # echo auto >/sys/bus/pata_parport/new_device + +Probe parport0 using protocol epat and mode 4 (EPP-16):: + + # echo "parport0 epat 4" >/sys/bus/pata_parport/new_device + +Probe parport0 using all protocols:: + + # echo "parport0 auto" >/sys/bus/pata_parport/new_device + +Probe all parports using protoocol epat:: + + # echo "auto epat" >/sys/bus/pata_parport/new_device + +Deleting devices:: + + # echo pata_parport.0 >/sys/bus/pata_parport/delete_device 3. Troubleshooting @@ -344,9 +169,9 @@ in EPP mode, try to use "bidirectional" or "PS/2" mode and 1x speeds only. 3.1 Use EPP mode if you can ---------------------------- -The most common problems that people report with the PARIDE drivers +The most common problems that people report with the pata_parport drivers concern the parallel port CMOS settings. At this time, none of the -PARIDE protocol modules support ECP mode, or any ECP combination modes. +protocol modules support ECP mode, or any ECP combination modes. If you are able to do so, please set your parallel port into EPP mode using your CMOS setup procedure. @@ -354,17 +179,14 @@ using your CMOS setup procedure. ------------------------- Some parallel ports cannot reliably transfer data at full speed. To -offset the errors, the PARIDE protocol modules introduce a "port +offset the errors, the protocol modules introduce a "port delay" between each access to the i/o ports. Each protocol sets a default value for this delay. In most cases, the user can override the default and set it to 0 - resulting in somewhat higher transfer rates. In some rare cases (especially with older 486 systems) the default delays are not long enough. if you experience corrupt data transfers, or unexpected failures, you may wish to increase the -port delay. The delay can be programmed using the "driveN" parameters -to each of the high-level drivers. Please see the notes above, or -read the comments at the beginning of the driver source files in -linux/drivers/block/paride. +port delay. 3.3 Some drives need a printer reset ------------------------------------- @@ -374,66 +196,12 @@ that do not always power up correctly. We have noticed this with some drives based on OnSpec and older Freecom adapters. In these rare cases, the adapter can often be reinitialised by issuing a "printer reset" on the parallel port. As the reset operation is potentially disruptive in -multiple device environments, the PARIDE drivers will not do it +multiple device environments, the pata_parport drivers will not do it automatically. You can however, force a printer reset by doing:: insmod lp reset=1 rmmod lp If you have one of these marginal cases, you should probably build -your paride drivers as modules, and arrange to do the printer reset -before loading the PARIDE drivers. - -3.4 Use the verbose option and dmesg if you need help ------------------------------------------------------- - -While a lot of testing has gone into these drivers to make them work -as smoothly as possible, problems will arise. If you do have problems, -please check all the obvious things first: does the drive work in -DOS with the manufacturer's drivers ? If that doesn't yield any useful -clues, then please make sure that only one drive is hooked to your system, -and that either (a) PARPORT is enabled or (b) no other device driver -is using your parallel port (check in /proc/ioports). Then, load the -appropriate drivers (you can load several protocol modules if you want) -as in:: - - # insmod paride - # insmod epat - # insmod bpck - # insmod kbic - ... - # insmod pd verbose=1 - -(using the correct driver for the type of device you have, of course). -The verbose=1 parameter will cause the drivers to log a trace of their -activity as they attempt to locate your drive. - -Use 'dmesg' to capture a log of all the PARIDE messages (any messages -beginning with paride:, a protocol module's name or a driver's name) and -include that with your bug report. You can submit a bug report in one -of two ways. Either send it directly to the author of the PARIDE suite, -by e-mail to grant@torque.net, or join the linux-parport mailing list -and post your report there. - -3.5 For more information or help ---------------------------------- - -You can join the linux-parport mailing list by sending a mail message -to: - - linux-parport-request@torque.net - -with the single word:: - - subscribe - -in the body of the mail message (not in the subject line). Please be -sure that your mail program is correctly set up when you do this, as -the list manager is a robot that will subscribe you using the reply -address in your mail headers. REMOVE any anti-spam gimmicks you may -have in your mail headers, when sending mail to the list server. - -You might also find some useful information on the linux-parport -web pages (although they are not always up to date) at - - http://web.archive.org/web/%2E/http://www.torque.net/parport/ +your pata_parport drivers as modules, and arrange to do the printer reset +before loading the pata_parport drivers. diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst index 9355c525fbe0..91339efdcb54 100644 --- a/Documentation/admin-guide/bootconfig.rst +++ b/Documentation/admin-guide/bootconfig.rst @@ -201,6 +201,8 @@ To remove the config from the image, you can use -d option as below:: Then add "bootconfig" on the normal kernel command line to tell the kernel to look for the bootconfig at the end of the initrd file. +Alternatively, build your kernel with the ``CONFIG_BOOT_CONFIG_FORCE`` +Kconfig option selected. Embedding a Boot Config into Kernel ----------------------------------- @@ -217,7 +219,9 @@ path to the bootconfig file from source tree or object tree. The kernel will embed it as the default bootconfig. Just as when attaching the bootconfig to the initrd, you need ``bootconfig`` -option on the kernel command line to enable the embedded bootconfig. +option on the kernel command line to enable the embedded bootconfig, or, +alternatively, build your kernel with the ``CONFIG_BOOT_CONFIG_FORCE`` +Kconfig option selected. Note that even if you set this option, you can override the embedded bootconfig by another bootconfig which attached to the initrd. diff --git a/Documentation/admin-guide/cgroup-v1/blkio-controller.rst b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst index 16253eda192e..dabb80cdd25a 100644 --- a/Documentation/admin-guide/cgroup-v1/blkio-controller.rst +++ b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst @@ -106,7 +106,7 @@ Proportional weight policy files see Documentation/block/bfq-iosched.rst. blkio.bfq.weight_device - Specifes per cgroup per device weights, overriding the default group + Specifies per cgroup per device weights, overriding the default group weight. For more details, see Documentation/block/bfq-iosched.rst. Following is the format:: diff --git a/Documentation/admin-guide/cgroup-v1/cgroups.rst b/Documentation/admin-guide/cgroup-v1/cgroups.rst index b0688011ed06..9343148ee993 100644 --- a/Documentation/admin-guide/cgroup-v1/cgroups.rst +++ b/Documentation/admin-guide/cgroup-v1/cgroups.rst @@ -80,6 +80,8 @@ access. For example, cpusets (see Documentation/admin-guide/cgroup-v1/cpusets.rs you to associate a set of CPUs and a set of memory nodes with the tasks in each cgroup. +.. _cgroups-why-needed: + 1.2 Why are cgroups needed ? ---------------------------- diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst index 60370f2c67b9..47d1d7d932a8 100644 --- a/Documentation/admin-guide/cgroup-v1/memory.rst +++ b/Documentation/admin-guide/cgroup-v1/memory.rst @@ -2,18 +2,18 @@ Memory Resource Controller ========================== -NOTE: +.. caution:: This document is hopelessly outdated and it asks for a complete rewrite. It still contains a useful information so we are keeping it here but make sure to check the current code if you need a deeper understanding. -NOTE: +.. note:: The Memory Resource Controller has generically been referred to as the memory controller in this document. Do not confuse memory controller used here with the memory controller that is used in hardware. -(For editors) In this document: +.. hint:: When we mention a cgroup (cgroupfs's directory) with memory controller, we call it "memory cgroup". When you see git-log and source code, you'll see patch's title and function names tend to use "memcg". @@ -23,7 +23,7 @@ Benefits and Purpose of the memory controller ============================================= The memory controller isolates the memory behaviour of a group of tasks -from the rest of the system. The article on LWN [12] mentions some probable +from the rest of the system. The article on LWN [12]_ mentions some probable uses of the memory controller. The memory controller can be used to a. Isolate an application or a group of applications @@ -55,7 +55,8 @@ Features: - Root cgroup has no limit controls. Kernel memory support is a work in progress, and the current version provides - basically functionality. (See Section 2.7) + basically functionality. (See :ref:`section 2.7 + <cgroup-v1-memory-kernel-extension>`) Brief summary of control files. @@ -86,6 +87,8 @@ Brief summary of control files. memory.swappiness set/show swappiness parameter of vmscan (See sysctl's vm.swappiness) memory.move_charge_at_immigrate set/show controls of moving charges + This knob is deprecated and shouldn't be + used. memory.oom_control set/show oom controls. memory.numa_stat show the number of memory usage per numa node @@ -107,16 +110,16 @@ Brief summary of control files. ========== The memory controller has a long history. A request for comments for the memory -controller was posted by Balbir Singh [1]. At the time the RFC was posted +controller was posted by Balbir Singh [1]_. At the time the RFC was posted there were several implementations for memory control. The goal of the RFC was to build consensus and agreement for the minimal features required -for memory control. The first RSS controller was posted by Balbir Singh[2] -in Feb 2007. Pavel Emelianov [3][4][5] has since posted three versions of the -RSS controller. At OLS, at the resource management BoF, everyone suggested -that we handle both page cache and RSS together. Another request was raised -to allow user space handling of OOM. The current memory controller is +for memory control. The first RSS controller was posted by Balbir Singh [2]_ +in Feb 2007. Pavel Emelianov [3]_ [4]_ [5]_ has since posted three versions +of the RSS controller. At OLS, at the resource management BoF, everyone +suggested that we handle both page cache and RSS together. Another request was +raised to allow user space handling of OOM. The current memory controller is at version 6; it combines both mapped (RSS) and unmapped Page -Cache Control [11]. +Cache Control [11]_. 2. Memory Control ================= @@ -147,7 +150,8 @@ specific data structure (mem_cgroup) associated with it. 2.2. Accounting --------------- -:: +.. code-block:: + :caption: Figure 1: Hierarchy of Accounting +--------------------+ | mem_cgroup | @@ -167,7 +171,6 @@ specific data structure (mem_cgroup) associated with it. | | | | +---------------+ +---------------+ - (Figure 1: Hierarchy of Accounting) Figure 1 shows the important aspects of the controller @@ -221,8 +224,9 @@ behind this approach is that a cgroup that aggressively uses a shared page will eventually get charged for it (once it is uncharged from the cgroup that brought it in -- this will happen on memory pressure). -But see section 8.2: when moving a task to another cgroup, its pages may -be recharged to the new cgroup, if move_charge_at_immigrate has been chosen. +But see :ref:`section 8.2 <cgroup-v1-memory-movable-charges>` when moving a +task to another cgroup, its pages may be recharged to the new cgroup, if +move_charge_at_immigrate has been chosen. 2.4 Swap Extension -------------------------------------- @@ -244,7 +248,8 @@ In this case, setting memsw.limit_in_bytes=3G will prevent bad use of swap. By using the memsw limit, you can avoid system OOM which can be caused by swap shortage. -**why 'memory+swap' rather than swap** +2.4.1 why 'memory+swap' rather than swap +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The global LRU(kswapd) can swap out arbitrary pages. Swap-out means to move account from memory to swap...there is no change in usage of @@ -252,7 +257,8 @@ memory+swap. In other words, when we want to limit the usage of swap without affecting global LRU, memory+swap limit is better than just limiting swap from an OS point of view. -**What happens when a cgroup hits memory.memsw.limit_in_bytes** +2.4.2. What happens when a cgroup hits memory.memsw.limit_in_bytes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When a cgroup hits memory.memsw.limit_in_bytes, it's useless to do swap-out in this cgroup. Then, swap-out will not be done by cgroup routine and file @@ -268,26 +274,26 @@ global VM. When a cgroup goes over its limit, we first try to reclaim memory from the cgroup so as to make space for the new pages that the cgroup has touched. If the reclaim is unsuccessful, an OOM routine is invoked to select and kill the bulkiest task in the -cgroup. (See 10. OOM Control below.) +cgroup. (See :ref:`10. OOM Control <cgroup-v1-memory-oom-control>` below.) The reclaim algorithm has not been modified for cgroups, except that pages that are selected for reclaiming come from the per-cgroup LRU list. -NOTE: - Reclaim does not work for the root cgroup, since we cannot set any - limits on the root cgroup. +.. note:: + Reclaim does not work for the root cgroup, since we cannot set any + limits on the root cgroup. -Note2: - When panic_on_oom is set to "2", the whole system will panic. +.. note:: + When panic_on_oom is set to "2", the whole system will panic. When oom event notifier is registered, event will be delivered. -(See oom_control section) +(See :ref:`oom_control <cgroup-v1-memory-oom-control>` section) 2.6 Locking ----------- -Lock order is as follows: +Lock order is as follows:: Page lock (PG_locked bit of page->flags) mm->page_table_lock or split pte_lock @@ -299,6 +305,8 @@ Per-node-per-memcgroup LRU (cgroup's private LRU) is guarded by lruvec->lru_lock; PG_lru bit of page->flags is cleared before isolating a page from its LRU under lruvec->lru_lock. +.. _cgroup-v1-memory-kernel-extension: + 2.7 Kernel Memory Extension ----------------------------------------------- @@ -367,10 +375,10 @@ U != 0, K < U: never greater than the total memory, and freely set U at the cost of his QoS. -WARNING: - In the current implementation, memory reclaim will NOT be - triggered for a cgroup when it hits K while staying below U, which makes - this setup impractical. + .. warning:: + In the current implementation, memory reclaim will NOT be triggered for + a cgroup when it hits K while staying below U, which makes this setup + impractical. U != 0, K >= U: Since kmem charges will also be fed to the user counter and reclaim will be @@ -381,45 +389,41 @@ U != 0, K >= U: 3. User Interface ================= -3.0. Configuration ------------------- - -a. Enable CONFIG_CGROUPS -b. Enable CONFIG_MEMCG +To use the user interface: -3.1. Prepare the cgroups (see cgroups.txt, Why are cgroups needed?) -------------------------------------------------------------------- - -:: +1. Enable CONFIG_CGROUPS and CONFIG_MEMCG options +2. Prepare the cgroups (see :ref:`Why are cgroups needed? + <cgroups-why-needed>` for the background information):: # mount -t tmpfs none /sys/fs/cgroup # mkdir /sys/fs/cgroup/memory # mount -t cgroup none /sys/fs/cgroup/memory -o memory -3.2. Make the new group and move bash into it:: +3. Make the new group and move bash into it:: # mkdir /sys/fs/cgroup/memory/0 # echo $$ > /sys/fs/cgroup/memory/0/tasks -Since now we're in the 0 cgroup, we can alter the memory limit:: +4. Since now we're in the 0 cgroup, we can alter the memory limit:: # echo 4M > /sys/fs/cgroup/memory/0/memory.limit_in_bytes -NOTE: - We can use a suffix (k, K, m, M, g or G) to indicate values in kilo, - mega or gigabytes. (Here, Kilo, Mega, Giga are Kibibytes, Mebibytes, - Gibibytes.) + The limit can now be queried:: + + # cat /sys/fs/cgroup/memory/0/memory.limit_in_bytes + 4194304 -NOTE: - We can write "-1" to reset the ``*.limit_in_bytes(unlimited)``. +.. note:: + We can use a suffix (k, K, m, M, g or G) to indicate values in kilo, + mega or gigabytes. (Here, Kilo, Mega, Giga are Kibibytes, Mebibytes, + Gibibytes.) -NOTE: - We cannot set limits on the root cgroup any more. +.. note:: + We can write "-1" to reset the ``*.limit_in_bytes(unlimited)``. -:: +.. note:: + We cannot set limits on the root cgroup any more. - # cat /sys/fs/cgroup/memory/0/memory.limit_in_bytes - 4194304 We can check the usage:: @@ -458,6 +462,8 @@ test because it has noise of shared objects/status. But the above two are testing extreme situations. Trying usual test under memory controller is always helpful. +.. _cgroup-v1-memory-test-troubleshoot: + 4.1 Troubleshooting ------------------- @@ -470,8 +476,11 @@ terminated by the OOM killer. There are several causes for this: A sync followed by echo 1 > /proc/sys/vm/drop_caches will help get rid of some of the pages cached in the cgroup (page cache pages). -To know what happens, disabling OOM_Kill as per "10. OOM Control" (below) and -seeing what happens will be helpful. +To know what happens, disabling OOM_Kill as per :ref:`"10. OOM Control" +<cgroup-v1-memory-oom-control>` (below) and seeing what happens will be +helpful. + +.. _cgroup-v1-memory-test-task-migration: 4.2 Task migration ------------------ @@ -482,15 +491,16 @@ remain charged to it, the charge is dropped when the page is freed or reclaimed. You can move charges of a task along with task migration. -See 8. "Move charges at task migration" +See :ref:`8. "Move charges at task migration" <cgroup-v1-memory-move-charges>` 4.3 Removing a cgroup --------------------- -A cgroup can be removed by rmdir, but as discussed in sections 4.1 and 4.2, a -cgroup might have some charge associated with it, even though all -tasks have migrated away from it. (because we charge against pages, not -against tasks.) +A cgroup can be removed by rmdir, but as discussed in :ref:`sections 4.1 +<cgroup-v1-memory-test-troubleshoot>` and :ref:`4.2 +<cgroup-v1-memory-test-task-migration>`, a cgroup might have some charge +associated with it, even though all tasks have migrated away from it. (because +we charge against pages, not against tasks.) We move the stats to parent, and no change on the charge except uncharging from the child. @@ -519,67 +529,66 @@ will be charged as a new owner of it. 5.2 stat file ------------- -memory.stat file includes following statistics - -per-memory cgroup local status -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -=============== =============================================================== -cache # of bytes of page cache memory. -rss # of bytes of anonymous and swap cache memory (includes - transparent hugepages). -rss_huge # of bytes of anonymous transparent hugepages. -mapped_file # of bytes of mapped file (includes tmpfs/shmem) -pgpgin # of charging events to the memory cgroup. The charging - event happens each time a page is accounted as either mapped - anon page(RSS) or cache page(Page Cache) to the cgroup. -pgpgout # of uncharging events to the memory cgroup. The uncharging - event happens each time a page is unaccounted from the cgroup. -swap # of bytes of swap usage -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. -inactive_anon # of bytes of anonymous and swap cache memory on inactive - LRU list. -active_anon # of bytes of anonymous and swap cache memory on active - LRU list. -inactive_file # of bytes of file-backed memory and MADV_FREE anonymous memory( - LazyFree pages) on inactive LRU list. -active_file # of bytes of file-backed memory on active LRU list. -unevictable # of bytes of memory that cannot be reclaimed (mlocked etc). -=============== =============================================================== - -status considering hierarchy (see memory.use_hierarchy settings) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -========================= =================================================== -hierarchical_memory_limit # of bytes of memory limit with regard to hierarchy - under which the memory cgroup is -hierarchical_memsw_limit # of bytes of memory+swap limit with regard to - hierarchy under which memory cgroup is. - -total_<counter> # hierarchical version of <counter>, which in - addition to the cgroup's own value includes the - sum of all hierarchical children's values of - <counter>, i.e. total_cache -========================= =================================================== - -The following additional stats are dependent on CONFIG_DEBUG_VM -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -========================= ======================================== -recent_rotated_anon VM internal parameter. (see mm/vmscan.c) -recent_rotated_file VM internal parameter. (see mm/vmscan.c) -recent_scanned_anon VM internal parameter. (see mm/vmscan.c) -recent_scanned_file VM internal parameter. (see mm/vmscan.c) -========================= ======================================== - -Memo: +memory.stat file includes following statistics: + + * per-memory cgroup local status + + =============== =============================================================== + cache # of bytes of page cache memory. + rss # of bytes of anonymous and swap cache memory (includes + transparent hugepages). + rss_huge # of bytes of anonymous transparent hugepages. + mapped_file # of bytes of mapped file (includes tmpfs/shmem) + pgpgin # of charging events to the memory cgroup. The charging + event happens each time a page is accounted as either mapped + anon page(RSS) or cache page(Page Cache) to the cgroup. + pgpgout # of uncharging events to the memory cgroup. The uncharging + event happens each time a page is unaccounted from the + cgroup. + swap # of bytes of swap usage + 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. + inactive_anon # of bytes of anonymous and swap cache memory on inactive + LRU list. + active_anon # of bytes of anonymous and swap cache memory on active + LRU list. + inactive_file # of bytes of file-backed memory and MADV_FREE anonymous + memory (LazyFree pages) on inactive LRU list. + active_file # of bytes of file-backed memory on active LRU list. + unevictable # of bytes of memory that cannot be reclaimed (mlocked etc). + =============== =============================================================== + + * status considering hierarchy (see memory.use_hierarchy settings): + + ========================= =================================================== + hierarchical_memory_limit # of bytes of memory limit with regard to + hierarchy + under which the memory cgroup is + hierarchical_memsw_limit # of bytes of memory+swap limit with regard to + hierarchy under which memory cgroup is. + + total_<counter> # hierarchical version of <counter>, which in + addition to the cgroup's own value includes the + sum of all hierarchical children's values of + <counter>, i.e. total_cache + ========================= =================================================== + + * additional vm parameters (depends on CONFIG_DEBUG_VM): + + ========================= ======================================== + recent_rotated_anon VM internal parameter. (see mm/vmscan.c) + recent_rotated_file VM internal parameter. (see mm/vmscan.c) + recent_scanned_anon VM internal parameter. (see mm/vmscan.c) + recent_scanned_file VM internal parameter. (see mm/vmscan.c) + ========================= ======================================== + +.. hint:: recent_rotated means recent frequency of LRU rotation. recent_scanned means recent # of scans to LRU. showing for better debug please see the code for meanings. -Note: +.. note:: Only anonymous and swap cache memory is listed as part of 'rss' stat. This should not be confused with the true 'resident set size' or the amount of physical memory used by the cgroup. @@ -710,15 +719,25 @@ If we want to change this to 1G, we can at any time use:: # echo 1G > memory.soft_limit_in_bytes -NOTE1: +.. note:: Soft limits take effect over a long period of time, since they involve reclaiming memory for balancing between memory cgroups -NOTE2: + +.. note:: It is recommended to set the soft limit always below the hard limit, otherwise the hard limit will take precedence. -8. Move charges at task migration -================================= +.. _cgroup-v1-memory-move-charges: + +8. Move charges at task migration (DEPRECATED!) +=============================================== + +THIS IS DEPRECATED! + +It's expensive and unreliable! It's better practice to launch workload +tasks directly from inside their target cgroup. Use dedicated workload +cgroups to allow fine-grained policy adjustments without having to +move physical pages between control domains. Users can move charges associated with a task along with task migration, that is, uncharge task's pages from the old cgroup and charge them to the new cgroup. @@ -735,23 +754,29 @@ If you want to enable it:: # echo (some positive value) > memory.move_charge_at_immigrate -Note: +.. note:: Each bits of move_charge_at_immigrate has its own meaning about what type - of charges should be moved. See 8.2 for details. -Note: + of charges should be moved. See :ref:`section 8.2 + <cgroup-v1-memory-movable-charges>` for details. + +.. note:: Charges are moved only when you move mm->owner, in other words, a leader of a thread group. -Note: + +.. note:: If we cannot find enough space for the task in the destination cgroup, we try to make space by reclaiming memory. Task migration may fail if we cannot make enough space. -Note: + +.. note:: It can take several seconds if you move charges much. And if you want disable it again:: # echo 0 > memory.move_charge_at_immigrate +.. _cgroup-v1-memory-movable-charges: + 8.2 Type of charges which can be moved -------------------------------------- @@ -801,6 +826,8 @@ threshold in any direction. It's applicable for root and non-root cgroup. +.. _cgroup-v1-memory-oom-control: + 10. OOM Control =============== @@ -956,15 +983,16 @@ commented and discussed quite extensively in the community. References ========== -1. Singh, Balbir. RFC: Memory Controller, http://lwn.net/Articles/206697/ -2. Singh, Balbir. Memory Controller (RSS Control), +.. [1] Singh, Balbir. RFC: Memory Controller, http://lwn.net/Articles/206697/ +.. [2] Singh, Balbir. Memory Controller (RSS Control), http://lwn.net/Articles/222762/ -3. Emelianov, Pavel. Resource controllers based on process cgroups +.. [3] Emelianov, Pavel. Resource controllers based on process cgroups https://lore.kernel.org/r/45ED7DEC.7010403@sw.ru -4. Emelianov, Pavel. RSS controller based on process cgroups (v2) +.. [4] Emelianov, Pavel. RSS controller based on process cgroups (v2) https://lore.kernel.org/r/461A3010.90403@sw.ru -5. Emelianov, Pavel. RSS controller based on process cgroups (v3) +.. [5] Emelianov, Pavel. RSS controller based on process cgroups (v3) https://lore.kernel.org/r/465D9739.8070209@openvz.org + 6. Menage, Paul. Control Groups v10, http://lwn.net/Articles/236032/ 7. Vaidyanathan, Srinivasan, Control Groups: Pagecache accounting and control subsystem (v3), http://lwn.net/Articles/235534/ @@ -974,7 +1002,8 @@ References https://lore.kernel.org/r/464D267A.50107@linux.vnet.ibm.com 10. Singh, Balbir. Memory controller v6 test results, https://lore.kernel.org/r/20070819094658.654.84837.sendpatchset@balbir-laptop -11. Singh, Balbir. Memory controller introduction (v6), - https://lore.kernel.org/r/20070817084228.26003.12568.sendpatchset@balbir-laptop -12. Corbet, Jonathan, Controlling memory use in cgroups, - http://lwn.net/Articles/243795/ + +.. [11] Singh, Balbir. Memory controller introduction (v6), + https://lore.kernel.org/r/20070817084228.26003.12568.sendpatchset@balbir-laptop +.. [12] Corbet, Jonathan, Controlling memory use in cgroups, + http://lwn.net/Articles/243795/ diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index c8ae7c897f14..f67c0829350b 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -619,10 +619,12 @@ process migrations. and is an example of this type. +.. _cgroupv2-limits-distributor: + Limits ------ -A child can only consume upto the configured amount of the resource. +A child can only consume up to the configured amount of the resource. Limits can be over-committed - the sum of the limits of children can exceed the amount of resource available to the parent. @@ -635,15 +637,16 @@ process migrations. "io.max" limits the maximum BPS and/or IOPS that a cgroup can consume on an IO device and is an example of this type. +.. _cgroupv2-protections-distributor: Protections ----------- -A cgroup is protected upto the configured amount of the resource +A cgroup is protected up to the configured amount of the resource as long as the usages of all its ancestors are under their protected levels. Protections can be hard guarantees or best effort soft boundaries. Protections can also be over-committed in which case -only upto the amount available to the parent is protected among +only up to the amount available to the parent is protected among children. Protections are in the range [0, max] and defaults to 0, which is @@ -1076,7 +1079,7 @@ All time durations are in microseconds. $MAX $PERIOD - which indicates that the group may consume upto $MAX in each + which indicates that the group may consume up to $MAX in each $PERIOD duration. "max" for $MAX indicates no limit. If only one number is written, $MAX is updated. @@ -1245,13 +1248,17 @@ PAGE_SIZE multiple when read back. This is a simple interface to trigger memory reclaim in the target cgroup. - This file accepts a string which contains the number of bytes to - reclaim. + This file accepts a single key, the number of bytes to reclaim. + No nested keys are currently supported. Example:: echo "1G" > memory.reclaim + The interface can be later extended with nested keys to + configure the reclaim behavior. For example, specify the + type of memory to reclaim from (anon, file, ..). + Please note that the kernel can over or under reclaim from the target cgroup. If less bytes are reclaimed than the specified amount, -EAGAIN is returned. @@ -1263,13 +1270,6 @@ PAGE_SIZE multiple when read back. This means that the networking layer will not adapt based on reclaim induced by memory.reclaim. - This file also allows the user to specify the nodes to reclaim from, - via the 'nodes=' key, for example:: - - echo "1G nodes=0,1" > memory.reclaim - - The above instructs the kernel to reclaim memory from nodes 0,1. - memory.peak A read-only single value file which exists on non-root cgroups. @@ -2289,7 +2289,7 @@ Cpuset Interface Files 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 - sibiling partitions with conflicting cpuset.cpus values. So + sibling partitions with conflicting cpuset.cpus values. So care must be taking in changing "cpuset.cpus". A valid non-root parent partition may distribute out all its CPUs diff --git a/Documentation/admin-guide/cifs/usage.rst b/Documentation/admin-guide/cifs/usage.rst index ed3b8dc854ec..2e151cd8c2e4 100644 --- a/Documentation/admin-guide/cifs/usage.rst +++ b/Documentation/admin-guide/cifs/usage.rst @@ -399,7 +399,7 @@ A partial list of the supported mount options follows: sep if first mount option (after the -o), overrides the comma as the separator between the mount - parms. e.g.:: + parameters. e.g.:: -o user=myname,password=mypassword,domain=mydom @@ -765,7 +765,7 @@ cifsFYI If set to non-zero value, additional debug information Some debugging statements are not compiled into the cifs kernel unless CONFIG_CIFS_DEBUG2 is enabled in the kernel configuration. cifsFYI may be set to one or - nore of the following flags (7 sets them all):: + more of the following flags (7 sets them all):: +-----------------------------------------------+------+ | log cifs informational messages | 0x01 | diff --git a/Documentation/admin-guide/device-mapper/cache-policies.rst b/Documentation/admin-guide/device-mapper/cache-policies.rst index b17fe352fc41..13da4d831d46 100644 --- a/Documentation/admin-guide/device-mapper/cache-policies.rst +++ b/Documentation/admin-guide/device-mapper/cache-policies.rst @@ -70,7 +70,7 @@ the entries (each hotspot block covers a larger area than a single cache block). All this means smq uses ~25bytes per cache block. Still a lot of -memory, but a substantial improvement nontheless. +memory, but a substantial improvement nonetheless. Level balancing ^^^^^^^^^^^^^^^ diff --git a/Documentation/admin-guide/device-mapper/dm-ebs.rst b/Documentation/admin-guide/device-mapper/dm-ebs.rst index 534fa38e8862..c09f66db5621 100644 --- a/Documentation/admin-guide/device-mapper/dm-ebs.rst +++ b/Documentation/admin-guide/device-mapper/dm-ebs.rst @@ -31,7 +31,7 @@ Mandatory parameters: Optional parameter: - <underyling sectors>: + <underlying sectors>: Number of sectors defining the logical block size of <dev path>. 2^N supported, e.g. 8 = emulate 8 sectors of 512 bytes = 4KiB. If not provided, the logical block size of <dev path> will be used. diff --git a/Documentation/admin-guide/device-mapper/dm-zoned.rst b/Documentation/admin-guide/device-mapper/dm-zoned.rst index 0fac051caeac..932383fe6e88 100644 --- a/Documentation/admin-guide/device-mapper/dm-zoned.rst +++ b/Documentation/admin-guide/device-mapper/dm-zoned.rst @@ -46,7 +46,7 @@ just like conventional zones. The zones of the device(s) are separated into 2 types: 1) Metadata zones: these are conventional zones used to store metadata. -Metadata zones are not reported as useable capacity to the user. +Metadata zones are not reported as usable capacity to the user. 2) Data zones: all remaining zones, the vast majority of which will be sequential zones used exclusively to store user data. The conventional diff --git a/Documentation/admin-guide/device-mapper/unstriped.rst b/Documentation/admin-guide/device-mapper/unstriped.rst index 0a8d3eb3f072..5772ccdd1f5f 100644 --- a/Documentation/admin-guide/device-mapper/unstriped.rst +++ b/Documentation/admin-guide/device-mapper/unstriped.rst @@ -35,7 +35,7 @@ An example of undoing an existing dm-stripe This small bash script will setup 4 loop devices and use the existing striped target to combine the 4 devices into one. It then will use -the unstriped target ontop of the striped device to access the +the unstriped target on top of the striped device to access the individual backing loop devices. We write data to the newly exposed unstriped devices and verify the data written matches the correct underlying device on the striped array:: @@ -110,8 +110,8 @@ to get a 92% reduction in read latency using this device mapper target. Example dmsetup usage ===================== -unstriped ontop of Intel NVMe device that has 2 cores ------------------------------------------------------ +unstriped on top of Intel NVMe device that has 2 cores +------------------------------------------------------ :: @@ -124,8 +124,8 @@ respectively:: /dev/mapper/nvmset0 /dev/mapper/nvmset1 -unstriped ontop of striped with 4 drives using 128K chunk size --------------------------------------------------------------- +unstriped on top of striped with 4 drives using 128K chunk size +--------------------------------------------------------------- :: diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst index faa22f77847a..8dc668cc1216 100644 --- a/Documentation/admin-guide/dynamic-debug-howto.rst +++ b/Documentation/admin-guide/dynamic-debug-howto.rst @@ -330,7 +330,7 @@ Examples // boot-args example, with newlines and comments for readability Kernel command line: ... - // see whats going on in dyndbg=value processing + // see what's going on in dyndbg=value processing dynamic_debug.verbose=3 // enable pr_debugs in the btrfs module (can be builtin or loadable) btrfs.dyndbg="+p" diff --git a/Documentation/admin-guide/gpio/gpio-sim.rst b/Documentation/admin-guide/gpio/gpio-sim.rst index d8a90c81b9ee..1cc5567a4bbe 100644 --- a/Documentation/admin-guide/gpio/gpio-sim.rst +++ b/Documentation/admin-guide/gpio/gpio-sim.rst @@ -123,7 +123,7 @@ Each simulated GPIO chip creates a separate sysfs group under its device directory for each exposed line (e.g. ``/sys/devices/platform/gpio-sim.X/gpiochipY/``). The name of each group is of the form: ``'sim_gpioX'`` where X is the offset of the line. Inside each -group there are two attibutes: +group there are two attributes: ``pull`` - allows to read and set the current simulated pull setting for every line, when writing the value must be one of: ``'pull-up'``, diff --git a/Documentation/admin-guide/hw-vuln/cross-thread-rsb.rst b/Documentation/admin-guide/hw-vuln/cross-thread-rsb.rst new file mode 100644 index 000000000000..875616d675fe --- /dev/null +++ b/Documentation/admin-guide/hw-vuln/cross-thread-rsb.rst @@ -0,0 +1,91 @@ + +.. SPDX-License-Identifier: GPL-2.0 + +Cross-Thread Return Address Predictions +======================================= + +Certain AMD and Hygon processors are subject to a cross-thread return address +predictions vulnerability. When running in SMT mode and one sibling thread +transitions out of C0 state, the other sibling thread could use return target +predictions from the sibling thread that transitioned out of C0. + +The Spectre v2 mitigations protect the Linux kernel, as it fills the return +address prediction entries with safe targets when context switching to the idle +thread. However, KVM does allow a VMM to prevent exiting guest mode when +transitioning out of C0. This could result in a guest-controlled return target +being consumed by the sibling thread. + +Affected processors +------------------- + +The following CPUs are vulnerable: + + - AMD Family 17h processors + - Hygon Family 18h processors + +Related CVEs +------------ + +The following CVE entry is related to this issue: + + ============== ======================================= + CVE-2022-27672 Cross-Thread Return Address Predictions + ============== ======================================= + +Problem +------- + +Affected SMT-capable processors support 1T and 2T modes of execution when SMT +is enabled. In 2T mode, both threads in a core are executing code. For the +processor core to enter 1T mode, it is required that one of the threads +requests to transition out of the C0 state. This can be communicated with the +HLT instruction or with an MWAIT instruction that requests non-C0. +When the thread re-enters the C0 state, the processor transitions back +to 2T mode, assuming the other thread is also still in C0 state. + +In affected processors, the return address predictor (RAP) is partitioned +depending on the SMT mode. For instance, in 2T mode each thread uses a private +16-entry RAP, but in 1T mode, the active thread uses a 32-entry RAP. Upon +transition between 1T/2T mode, the RAP contents are not modified but the RAP +pointers (which control the next return target to use for predictions) may +change. This behavior may result in return targets from one SMT thread being +used by RET predictions in the sibling thread following a 1T/2T switch. In +particular, a RET instruction executed immediately after a transition to 1T may +use a return target from the thread that just became idle. In theory, this +could lead to information disclosure if the return targets used do not come +from trustworthy code. + +Attack scenarios +---------------- + +An attack can be mounted on affected processors by performing a series of CALL +instructions with targeted return locations and then transitioning out of C0 +state. + +Mitigation mechanism +-------------------- + +Before entering idle state, the kernel context switches to the idle thread. The +context switch fills the RAP entries (referred to as the RSB in Linux) with safe +targets by performing a sequence of CALL instructions. + +Prevent a guest VM from directly putting the processor into an idle state by +intercepting HLT and MWAIT instructions. + +Both mitigations are required to fully address this issue. + +Mitigation control on the kernel command line +--------------------------------------------- + +Use existing Spectre v2 mitigations that will fill the RSB on context switch. + +Mitigation control for KVM - module parameter +--------------------------------------------- + +By default, the KVM hypervisor mitigates this issue by intercepting guest +attempts to transition out of C0. A VMM can use the KVM_CAP_X86_DISABLE_EXITS +capability to override those interceptions, but since this is not common, the +mitigation that covers this path is not enabled by default. + +The mitigation for the KVM_CAP_X86_DISABLE_EXITS capability can be turned on +using the boolean module parameter mitigate_smt_rsb, e.g. ``kvm.mitigate_smt_rsb=1``. diff --git a/Documentation/admin-guide/hw-vuln/index.rst b/Documentation/admin-guide/hw-vuln/index.rst index 4df436e7c417..e0614760a99e 100644 --- a/Documentation/admin-guide/hw-vuln/index.rst +++ b/Documentation/admin-guide/hw-vuln/index.rst @@ -18,3 +18,4 @@ are configurable at compile, boot or run time. core-scheduling.rst l1d_flush.rst processor_mmio_stale_data.rst + cross-thread-rsb.rst diff --git a/Documentation/admin-guide/hw-vuln/mds.rst b/Documentation/admin-guide/hw-vuln/mds.rst index 2d19c9f4c1fe..f491de74ea79 100644 --- a/Documentation/admin-guide/hw-vuln/mds.rst +++ b/Documentation/admin-guide/hw-vuln/mds.rst @@ -64,8 +64,8 @@ architecture section: :ref:`Documentation/x86/mds.rst <mds>`. Attack scenarios ---------------- -Attacks against the MDS vulnerabilities can be mounted from malicious non -priviledged user space applications running on hosts or guest. Malicious +Attacks against the MDS vulnerabilities can be mounted from malicious non- +privileged user space applications running on hosts or guest. Malicious guest OSes can obviously mount attacks as well. Contrary to other speculation based vulnerabilities the MDS vulnerability diff --git a/Documentation/admin-guide/hw-vuln/spectre.rst b/Documentation/admin-guide/hw-vuln/spectre.rst index c4dcdb3d0d45..3fe6511c5405 100644 --- a/Documentation/admin-guide/hw-vuln/spectre.rst +++ b/Documentation/admin-guide/hw-vuln/spectre.rst @@ -610,9 +610,9 @@ kernel command line. retpoline,generic Retpolines retpoline,lfence LFENCE; indirect branch retpoline,amd alias for retpoline,lfence - eibrs enhanced IBRS - eibrs,retpoline enhanced IBRS + Retpolines - eibrs,lfence enhanced IBRS + LFENCE + eibrs Enhanced/Auto IBRS + eibrs,retpoline Enhanced/Auto IBRS + Retpolines + eibrs,lfence Enhanced/Auto IBRS + LFENCE ibrs use IBRS to protect kernel Not specifying this option is equivalent to diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 5bfafcbb9562..0ad7e7ec0d27 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -56,6 +56,17 @@ ABI will be found here. sysfs-rules +This is the beginning of a section with information of interest to +application developers and system integrators doing analysis of the +Linux kernel for safety critical applications. Documents supporting +analysis of kernel interactions with applications, and key kernel +subsystems expectations will be found here. + +.. toctree:: + :maxdepth: 1 + + workload-tracing + The rest of this manual consists of various unordered guides on how to configure specific aspects of kernel behavior to your liking. @@ -116,6 +127,7 @@ configure specific aspects of kernel behavior to your liking. svga syscall-user-dispatch sysrq + thermal/index thunderbolt ufs unicode diff --git a/Documentation/admin-guide/kdump/gdbmacros.txt b/Documentation/admin-guide/kdump/gdbmacros.txt index 82aecdcae8a6..030de95e3e6b 100644 --- a/Documentation/admin-guide/kdump/gdbmacros.txt +++ b/Documentation/admin-guide/kdump/gdbmacros.txt @@ -312,10 +312,10 @@ define dmesg set var $prev_flags = $info->flags end - set var $id = ($id + 1) & $id_mask if ($id == $end_id) loop_break end + set var $id = ($id + 1) & $id_mask end end document dmesg diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index 959f73a32712..19600c50277b 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -142,7 +142,6 @@ parameter is applicable:: NFS Appropriate NFS support is enabled. OF Devicetree is enabled. PV_OPS A paravirtualized kernel is enabled. - PARIDE The ParIDE (parallel port IDE) subsystem is enabled. PARISC The PA-RISC architecture is enabled. PCI PCI bus support is enabled. PCIE PCI Express support is enabled. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index ecdb9530af8a..46268d6baa43 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -378,18 +378,16 @@ autoconf= [IPV6] See Documentation/networking/ipv6.rst. - show_lapic= [APIC,X86] Advanced Programmable Interrupt Controller - Limit apic dumping. The parameter defines the maximal - number of local apics being dumped. Also it is possible - to set it to "all" by meaning -- no limit here. - Format: { 1 (default) | 2 | ... | all }. - The parameter valid if only apic=debug or - apic=verbose is specified. - Example: apic=debug show_lapic=all - apm= [APM] Advanced Power Management See header of arch/x86/kernel/apm_32.c. + apparmor= [APPARMOR] Disable or enable AppArmor at boot time + Format: { "0" | "1" } + See security/apparmor/Kconfig help text + 0 -- disable. + 1 -- enable. + Default value is set via kernel config option. + arcrimi= [HW,NET] ARCnet - "RIM I" (entirely mem-mapped) cards Format: <io>,<irq>,<nodeID> @@ -480,8 +478,10 @@ See Documentation/block/cmdline-partition.rst boot_delay= Milliseconds to delay each printk during boot. - Values larger than 10 seconds (10000) are changed to - no delay (0). + Only works if CONFIG_BOOT_PRINTK_DELAY is enabled, + and you may also have to specify "lpj=". Boot_delay + values larger than 10 seconds (10000) are assumed + erroneous and ignored. Format: integer bootconfig [KNL] @@ -557,6 +557,7 @@ Format: <string> nosocket -- Disable socket memory accounting. nokmem -- Disable kernel memory accounting. + nobpf -- Disable BPF memory accounting. checkreqprot= [SELINUX] Set initial checkreqprot flag value. Format: { "0" | "1" } @@ -672,7 +673,7 @@ 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 - specificed, the default value is 0. + specified, the default value is 0. With per-numa CMA enabled, DMA users on node nid will first try to allocate buffer from the pernuma area which is located in node nid, if the allocation fails, @@ -944,7 +945,7 @@ driver code when a CPU writes to (or reads from) a random memory location. Note that there exists a class of memory corruptions problems caused by buggy H/W or - F/W or by drivers badly programing DMA (basically when + F/W or by drivers badly programming DMA (basically when memory is written at bus level and the CPU MMU is bypassed) which are not detectable by CONFIG_DEBUG_PAGEALLOC, hence this option will not help @@ -1045,26 +1046,12 @@ can be useful when debugging issues that require an SLB miss to occur. - stress_slb [PPC] - Limits the number of kernel SLB entries, and flushes - them frequently to increase the rate of SLB faults - on kernel addresses. - - stress_hpt [PPC] - Limits the number of kernel HPT entries in the hash - page table to increase the rate of hash page table - faults on kernel addresses. - disable= [IPV6] See Documentation/networking/ipv6.rst. disable_radix [PPC] Disable RADIX MMU mode on POWER9 - radix_hcall_invalidate=on [PPC/PSERIES] - Disable RADIX GTSE feature and use hcall for TLB - invalidate. - disable_tlbie [PPC] Disable TLBIE instruction. Currently does not work with KVM, with HASH MMU, or with coherent accelerators. @@ -1166,16 +1153,6 @@ Documentation/admin-guide/dynamic-debug-howto.rst for details. - nopku [X86] Disable Memory Protection Keys CPU feature found - in some Intel CPUs. - - <module>.async_probe[=<bool>] [KNL] - If no <bool> value is specified or if the value - specified is not a valid <bool>, enable asynchronous - probe on this module. Otherwise, enable/disable - asynchronous probe on this module as indicated by the - <bool> value. See also: module.async_probe - early_ioremap_debug [KNL] Enable debug messages in early_ioremap support. This is useful for tracking down temporary early mappings @@ -1195,10 +1172,10 @@ specified, the serial port must already be setup and configured. - uart[8250],io,<addr>[,options] - uart[8250],mmio,<addr>[,options] - uart[8250],mmio32,<addr>[,options] - uart[8250],mmio32be,<addr>[,options] + uart[8250],io,<addr>[,options[,uartclk]] + uart[8250],mmio,<addr>[,options[,uartclk]] + uart[8250],mmio32,<addr>[,options[,uartclk]] + uart[8250],mmio32be,<addr>[,options[,uartclk]] uart[8250],0x<addr>[,options] Start an early, polled-mode console on the 8250/16550 UART at the specified I/O port or MMIO address. @@ -1207,7 +1184,9 @@ If none of [io|mmio|mmio32|mmio32be], <addr> is assumed to be equivalent to 'mmio'. 'options' are specified in the same format described for "console=ttyS<n>"; if - unspecified, the h/w is not initialized. + unspecified, the h/w is not initialized. 'uartclk' is + the uart clock frequency; if unspecified, it is set + to 'BASE_BAUD' * 16. pl011,<addr> pl011,mmio32,<addr> @@ -1532,6 +1511,15 @@ boot up that is likely to be overridden by user space start up functionality. + Optionally, the snapshot can also be defined for a tracing + instance that was created by the trace_instance= command + line parameter. + + trace_instance=foo,sched_switch ftrace_boot_snapshot=foo + + The above will cause the "foo" tracing instance to trigger + a snapshot at the end of boot up. + ftrace_dump_on_oops[=orig_cpu] [FTRACE] will dump the trace buffers on oops. If no parameter is passed, ftrace will dump @@ -1752,7 +1740,7 @@ boot-time allocation of gigantic hugepages is skipped. hugetlb_free_vmemmap= - [KNL] Reguires CONFIG_HUGETLB_PAGE_OPTIMIZE_VMEMMAP + [KNL] Requires CONFIG_HUGETLB_PAGE_OPTIMIZE_VMEMMAP enabled. Control if HugeTLB Vmemmap Optimization (HVO) is enabled. Allows heavy hugetlb users to free up some more @@ -1791,12 +1779,6 @@ which allow the hypervisor to 'idle' the guest on lock contention. - keep_bootcon [KNL] - Do not unregister boot console at start. This is only - useful for debugging when something happens in the window - between unregistering the boot console and initializing - the real console. - i2c_bus= [HW] Override the default board specific I2C bus speed or register an additional I2C bus that is not registered from board initialization code. @@ -2366,17 +2348,18 @@ js= [HW,JOY] Analog joystick See Documentation/input/joydev/joystick.rst. - nokaslr [KNL] - When CONFIG_RANDOMIZE_BASE is set, this disables - kernel and module base offset ASLR (Address Space - Layout Randomization). - kasan_multi_shot [KNL] Enforce KASAN (Kernel Address Sanitizer) to print report on every invalid memory access. Without this parameter KASAN will print report only for the first invalid access. + keep_bootcon [KNL] + Do not unregister boot console at start. This is only + useful for debugging when something happens in the window + between unregistering the boot console and initializing + the real console. + keepinitrd [HW,ARM] kernelcore= [KNL,X86,IA-64,PPC] @@ -2816,6 +2799,9 @@ * [no]setxfer: Indicate if transfer speed mode setting should be skipped. + * [no]fua: Disable or enable FUA (Force Unit Access) + support for devices supporting this feature. + * dump_id: Dump IDENTIFY data. * disable: Disable this device. @@ -3325,6 +3311,13 @@ For details see: Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst + <module>.async_probe[=<bool>] [KNL] + If no <bool> value is specified or if the value + specified is not a valid <bool>, enable asynchronous + probe on this module. Otherwise, enable/disable + asynchronous probe on this module as indicated by the + <bool> value. See also: module.async_probe + module.async_probe=<bool> [KNL] When set to true, modules will use async probing by default. To enable/disable async probing for a @@ -3708,7 +3701,7 @@ implementation; requires CONFIG_GENERIC_IDLE_POLL_SETUP to be effective. This is useful on platforms where the sleep(SH) or wfi(ARM,ARM64) instructions do not work - correctly or when doing power measurements to evalute + correctly or when doing power measurements to evaluate the impact of the sleep instructions. This is also useful when using JTAG debugger. @@ -3779,6 +3772,11 @@ nojitter [IA-64] Disables jitter checking for ITC timers. + nokaslr [KNL] + When CONFIG_RANDOMIZE_BASE is set, this disables + kernel and module base offset ASLR (Address Space + Layout Randomization). + no-kvmclock [X86,KVM] Disable paravirtualized KVM clock driver no-kvmapf [X86,KVM] Disable paravirtualized asynchronous page @@ -3824,6 +3822,19 @@ nopcid [X86-64] Disable the PCID cpu feature. + nopku [X86] Disable Memory Protection Keys CPU feature found + in some Intel CPUs. + + nopv= [X86,XEN,KVM,HYPER_V,VMWARE] + Disables the PV optimizations forcing the guest to run + as generic guest with no PV drivers. Currently support + XEN HVM, KVM, HYPER_V and VMWARE guest. + + nopvspin [X86,XEN,KVM] + Disables the qspinlock slow path using PV optimizations + which allow the hypervisor to 'idle' the guest on lock + contention. + norandmaps Don't use address space randomization. Equivalent to echo 0 > /proc/sys/kernel/randomize_va_space @@ -4117,10 +4128,6 @@ pcbit= [HW,ISDN] - pcd. [PARIDE] - See header of drivers/block/paride/pcd.c. - See also Documentation/admin-guide/blockdev/paride.rst. - pci=option[,option...] [PCI] various PCI subsystem options. Some options herein operate on a specific device @@ -4385,9 +4392,6 @@ for debug and development, but should not be needed on a platform with proper driver support. - pd. [PARIDE] - See Documentation/admin-guide/blockdev/paride.rst. - pdcchassis= [PARISC,HW] Disable/Enable PDC Chassis Status codes at boot time. Format: { 0 | 1 } @@ -4400,12 +4404,6 @@ allocator. This parameter is primarily for debugging and performance comparison. - pf. [PARIDE] - See Documentation/admin-guide/blockdev/paride.rst. - - pg. [PARIDE] - See Documentation/admin-guide/blockdev/paride.rst. - pirq= [SMP,APIC] Manual mp-table setup See Documentation/x86/i386/IO-APIC.rst. @@ -4567,9 +4565,6 @@ pstore.backend= Specify the name of the pstore backend to use - pt. [PARIDE] - See Documentation/admin-guide/blockdev/paride.rst. - pti= [X86-64] Control Page Table Isolation of user and kernel address spaces. Disabling this feature removes hardening, but improves performance of @@ -4593,6 +4588,10 @@ r128= [HW,DRM] + radix_hcall_invalidate=on [PPC/PSERIES] + Disable RADIX GTSE feature and use hcall for TLB + invalidate. + raid= [HW,RAID] See Documentation/admin-guide/md.rst. @@ -5115,6 +5114,17 @@ rcupdate.rcu_cpu_stall_timeout to be used (after conversion from seconds to milliseconds). + rcupdate.rcu_cpu_stall_cputime= [KNL] + Provide statistics on the cputime and count of + interrupts and tasks during the sampling period. For + multiple continuous RCU stalls, all sampling periods + begin at half of the first RCU stall timeout. + + rcupdate.rcu_exp_stall_task_details= [KNL] + Print stack dumps of any tasks blocking the + current expedited RCU grace period during an + expedited RCU CPU stall warning. + rcupdate.rcu_expedited= [KNL] Use expedited grace-period primitives, for example, synchronize_rcu_expedited() instead @@ -5223,7 +5233,7 @@ rdt= [HW,X86,RDT] Turn on/off individual RDT features. List is: cmt, mbmtotal, mbmlocal, l3cat, l3cdp, l2cat, l2cdp, - mba. + mba, smba, bmec. E.g. to turn on cmt and turn off mba use: rdt=cmt,!mba @@ -5574,13 +5584,6 @@ 1 -- enable. Default value is 1. - apparmor= [APPARMOR] Disable or enable AppArmor at boot time - Format: { "0" | "1" } - See security/apparmor/Kconfig help text - 0 -- disable. - 1 -- enable. - Default value is set via kernel config option. - serialnumber [BUGS=X86-32] sev=option[,option...] [X86-64] See Documentation/x86/x86_64/boot-options.rst @@ -5588,6 +5591,15 @@ shapers= [NET] Maximal number of shapers. + show_lapic= [APIC,X86] Advanced Programmable Interrupt Controller + Limit apic dumping. The parameter defines the maximal + number of local apics being dumped. Also it is possible + to set it to "all" by meaning -- no limit here. + Format: { 1 (default) | 2 | ... | all }. + The parameter valid if only apic=debug or + apic=verbose is specified. + Example: apic=debug show_lapic=all + simeth= [IA-64] simscsi= @@ -5731,9 +5743,9 @@ retpoline,generic - Retpolines retpoline,lfence - LFENCE; indirect branch retpoline,amd - alias for retpoline,lfence - eibrs - enhanced IBRS - eibrs,retpoline - enhanced IBRS + Retpolines - eibrs,lfence - enhanced IBRS + LFENCE + eibrs - Enhanced/Auto IBRS + eibrs,retpoline - Enhanced/Auto IBRS + Retpolines + eibrs,lfence - Enhanced/Auto IBRS + LFENCE ibrs - use IBRS to protect kernel Not specifying this option is equivalent to @@ -6027,6 +6039,16 @@ be used to filter out binaries which have not yet been made aware of AT_MINSIGSTKSZ. + stress_hpt [PPC] + Limits the number of kernel HPT entries in the hash + page table to increase the rate of hash page table + faults on kernel addresses. + + stress_slb [PPC] + Limits the number of kernel SLB entries, and flushes + them frequently to increase the rate of SLB faults + on kernel addresses. + sunrpc.min_resvport= sunrpc.max_resvport= [NFS,SUNRPC] @@ -6274,13 +6296,33 @@ comma-separated list of trace events to enable. See also Documentation/trace/events.rst + trace_instance=[instance-info] + [FTRACE] Create a ring buffer instance early in boot up. + This will be listed in: + + /sys/kernel/tracing/instances + + Events can be enabled at the time the instance is created + via: + + trace_instance=<name>,<system1>:<event1>,<system2>:<event2> + + Note, the "<system*>:" portion is optional if the event is + unique. + + trace_instance=foo,sched:sched_switch,irq_handler_entry,initcall + + will enable the "sched_switch" event (note, the "sched:" is optional, and + the same thing would happen if it was left off). The irq_handler_entry + event, and all events under the "initcall" system. + trace_options=[option-list] [FTRACE] Enable or disable tracer options at boot. The option-list is a comma delimited list of options that can be enabled or disabled just as if you were to echo the option name into - /sys/kernel/debug/tracing/trace_options + /sys/kernel/tracing/trace_options For example, to enable stacktrace option (to dump the stack trace of each event), add to the command line: @@ -6313,7 +6355,7 @@ [FTRACE] enable this option to disable tracing when a warning is hit. This turns off "tracing_on". Tracing can be enabled again by echoing '1' into the "tracing_on" - file located in /sys/kernel/debug/tracing/ + file located in /sys/kernel/tracing/ This option is useful, as it disables the trace before the WARNING dump is called, which prevents the trace to @@ -6371,6 +6413,16 @@ in situations with strict latency requirements (where interruptions from clocksource watchdog are not acceptable). + [x86] recalibrate: force recalibration against a HW timer + (HPET or PM timer) on systems whose TSC frequency was + obtained from HW or FW using either an MSR or CPUID(0x15). + Warn if the difference is more than 500 ppm. + [x86] watchdog: Use TSC as the watchdog clocksource with + which to check other HW timers (HPET or PM timer), but + only on systems where TSC has been deemed trustworthy. + This will be suppressed by an earlier tsc=nowatchdog and + can be overridden by a later tsc=nowatchdog. A console + message will flag any such suppression or overriding. tsc_early_khz= [X86] Skip early TSC calibration and use the given value instead. Useful when the early TSC frequency discovery @@ -6758,11 +6810,11 @@ functions are at fixed addresses, they make nice targets for exploits that can control RIP. - emulate [default] Vsyscalls turn into traps and are - emulated reasonably safely. The vsyscall - page is readable. + emulate Vsyscalls turn into traps and are emulated + reasonably safely. The vsyscall page is + readable. - xonly Vsyscalls turn into traps and are + xonly [default] Vsyscalls turn into traps and are emulated reasonably safely. The vsyscall page is not readable. @@ -6959,16 +7011,6 @@ fairer and the number of possible event channels is much higher. Default is on (use fifo events). - nopv= [X86,XEN,KVM,HYPER_V,VMWARE] - Disables the PV optimizations forcing the guest to run - as generic guest with no PV drivers. Currently support - XEN HVM, KVM, HYPER_V and VMWARE guest. - - nopvspin [X86,XEN,KVM] - Disables the qspinlock slow path using PV optimizations - which allow the hypervisor to 'idle' the guest on lock - contention. - xirc2ps_cs= [NET,PCMCIA] Format: <irq>,<irq_mask>,<io>,<full_duplex>,<do_sound>,<lockup_hack>[,<irq2>[,<irq3>[,<irq4>]]] @@ -7022,3 +7064,10 @@ management firmware translates the requests into actual hardware states (core frequency, data fabric and memory clocks etc.) + active + Use amd_pstate_epp driver instance as the scaling driver, + driver provides a hint to the hardware if software wants + to bias toward performance (0x0) or energy efficiency (0xff) + to the CPPC firmware. then CPPC power algorithm will + calculate the runtime workload and adjust the realtime cores + frequency. diff --git a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst index e4a5fc26f1a9..993c2a05f5ee 100644 --- a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst +++ b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst @@ -25,7 +25,7 @@ References - In order to locate kernel-generated OS jitter on CPU N: - cd /sys/kernel/debug/tracing + cd /sys/kernel/tracing echo 1 > max_graph_depth # Increase the "1" for more detail echo function_graph > current_tracer # run workload diff --git a/Documentation/admin-guide/laptops/thinkpad-acpi.rst b/Documentation/admin-guide/laptops/thinkpad-acpi.rst index 475eb0e81e4a..e27a1c3f634e 100644 --- a/Documentation/admin-guide/laptops/thinkpad-acpi.rst +++ b/Documentation/admin-guide/laptops/thinkpad-acpi.rst @@ -1488,7 +1488,7 @@ Example of command to set keyboard language is mentioned below:: Text corresponding to keyboard layout to be set in sysfs are: be(Belgian), cz(Czech), da(Danish), de(German), en(English), es(Spain), et(Estonian), fr(French), fr-ch(French(Switzerland)), hu(Hungarian), it(Italy), jp (Japan), -nl(Dutch), nn(Norway), pl(Polish), pt(portugese), sl(Slovenian), sv(Sweden), +nl(Dutch), nn(Norway), pl(Polish), pt(portuguese), sl(Slovenian), sv(Sweden), tr(Turkey) WWAN Antenna type diff --git a/Documentation/admin-guide/md.rst b/Documentation/admin-guide/md.rst index d8fc9a59c086..4ff2cc291d18 100644 --- a/Documentation/admin-guide/md.rst +++ b/Documentation/admin-guide/md.rst @@ -317,7 +317,7 @@ All md devices contain: suspended (not supported yet) All IO requests will block. The array can be reconfigured. - Writing this, if accepted, will block until array is quiessent + Writing this, if accepted, will block until array is quiescent readonly no resync can happen. no superblocks get written. diff --git a/Documentation/admin-guide/media/bttv.rst b/Documentation/admin-guide/media/bttv.rst index 125f6f47123d..58cbaf6df694 100644 --- a/Documentation/admin-guide/media/bttv.rst +++ b/Documentation/admin-guide/media/bttv.rst @@ -909,7 +909,7 @@ DE hat diverse Treiber fuer diese Modelle (Stand 09/2002): - TVPhone98 (Bt878) - AVerTV und TVCapture98 w/VCR (Bt 878) - AVerTVStudio und TVPhone98 w/VCR (Bt878) - - AVerTV GO Serie (Kein SVideo Input) + - AVerTV GO Series (Kein SVideo Input) - AVerTV98 (BT-878 chip) - AVerTV98 mit Fernbedienung (BT-878 chip) - AVerTV/FM98 (BT-878 chip) diff --git a/Documentation/admin-guide/media/building.rst b/Documentation/admin-guide/media/building.rst index 2d660b76caea..a06473429916 100644 --- a/Documentation/admin-guide/media/building.rst +++ b/Documentation/admin-guide/media/building.rst @@ -137,7 +137,7 @@ The ``LIRC user interface`` option adds enhanced functionality when using the from remote controllers. The ``Support for eBPF programs attached to lirc devices`` option allows -the usage of special programs (called eBPF) that would allow aplications +the usage of special programs (called eBPF) that would allow applications to add extra remote controller decoding functionality to the Linux Kernel. The ``Remote controller decoders`` option allows selecting the diff --git a/Documentation/admin-guide/media/davinci-vpbe.rst b/Documentation/admin-guide/media/davinci-vpbe.rst deleted file mode 100644 index 9e6360fd02db..000000000000 --- a/Documentation/admin-guide/media/davinci-vpbe.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -The VPBE V4L2 driver design -=========================== - -Functional partitioning ------------------------ - -Consists of the following: - - 1. V4L2 display driver - - Implements creation of video2 and video3 device nodes and - provides v4l2 device interface to manage VID0 and VID1 layers. - - 2. Display controller - - Loads up VENC, OSD and external encoders such as ths8200. It provides - a set of API calls to V4L2 drivers to set the output/standards - in the VENC or external sub devices. It also provides - a device object to access the services from OSD subdevice - using sub device ops. The connection of external encoders to VENC LCD - controller port is done at init time based on default output and standard - selection or at run time when application change the output through - V4L2 IOCTLs. - - When connected to an external encoder, vpbe controller is also responsible - for setting up the interface between VENC and external encoders based on - board specific settings (specified in board-xxx-evm.c). This allows - interfacing external encoders such as ths8200. The setup_if_config() - is implemented for this as well as configure_venc() (part of the next patch) - API to set timings in VENC for a specific display resolution. As of this - patch series, the interconnection and enabling and setting of the external - encoders is not present, and would be a part of the next patch series. - - 3. VENC subdevice module - - Responsible for setting outputs provided through internal DACs and also - setting timings at LCD controller port when external encoders are connected - at the port or LCD panel timings required. When external encoder/LCD panel - is connected, the timings for a specific standard/preset is retrieved from - the board specific table and the values are used to set the timings in - venc using non-standard timing mode. - - Support LCD Panel displays using the VENC. For example to support a Logic - PD display, it requires setting up the LCD controller port with a set of - timings for the resolution supported and setting the dot clock. So we could - add the available outputs as a board specific entry (i.e add the "LogicPD" - output name to board-xxx-evm.c). A table of timings for various LCDs - supported can be maintained in the board specific setup file to support - various LCD displays.As of this patch a basic driver is present, and this - support for external encoders and displays forms a part of the next - patch series. - - 4. OSD module - - OSD module implements all OSD layer management and hardware specific - features. The VPBE module interacts with the OSD for enabling and - disabling appropriate features of the OSD. - -Current status --------------- - -A fully functional working version of the V4L2 driver is available. This -driver has been tested with NTSC and PAL standards and buffer streaming. diff --git a/Documentation/admin-guide/media/platform-cardlist.rst b/Documentation/admin-guide/media/platform-cardlist.rst index ac73c4166d1e..8ef57cd13dec 100644 --- a/Documentation/admin-guide/media/platform-cardlist.rst +++ b/Documentation/admin-guide/media/platform-cardlist.rst @@ -73,7 +73,6 @@ via-camera VIAFB camera controller video-mux Video Multiplexer vpif_display TI DaVinci VPIF V4L2-Display vpif_capture TI DaVinci VPIF video capture -vpss TI DaVinci VPBE V4L2-Display vsp1 Renesas VSP1 Video Processing Engine xilinx-tpg Xilinx Video Test Pattern Generator xilinx-video Xilinx Video IP (EXPERIMENTAL) diff --git a/Documentation/admin-guide/media/si476x.rst b/Documentation/admin-guide/media/si476x.rst index 87062301d6a1..c8882ee9f208 100644 --- a/Documentation/admin-guide/media/si476x.rst +++ b/Documentation/admin-guide/media/si476x.rst @@ -142,7 +142,7 @@ The drivers exposes following files: indicator 0x18 lassi Signed Low side adjacent Channel Strength indicator - 0x19 hassi ditto fpr High side + 0x19 hassi ditto for High side 0x20 mult Multipath indicator 0x21 dev Frequency deviation 0x24 assi Adjacent channel SSI diff --git a/Documentation/admin-guide/media/v4l-drivers.rst b/Documentation/admin-guide/media/v4l-drivers.rst index 90a026ee05c6..734e18c310bd 100644 --- a/Documentation/admin-guide/media/v4l-drivers.rst +++ b/Documentation/admin-guide/media/v4l-drivers.rst @@ -13,7 +13,6 @@ Video4Linux (V4L) driver-specific documentation cafe_ccic cpia2 cx88 - davinci-vpbe fimc imx imx7 diff --git a/Documentation/admin-guide/media/vivid.rst b/Documentation/admin-guide/media/vivid.rst index 672a8371f6ad..58ac25b2c385 100644 --- a/Documentation/admin-guide/media/vivid.rst +++ b/Documentation/admin-guide/media/vivid.rst @@ -580,7 +580,7 @@ Metadata Capture ---------------- The Metadata capture generates UVC format metadata. The PTS and SCR are -transmitted based on the values set in vivid contols. +transmitted based on the values set in vivid controls. The Metadata device will only work for the Webcam input, it will give back an error for all other inputs. diff --git a/Documentation/admin-guide/mm/concepts.rst b/Documentation/admin-guide/mm/concepts.rst index c79f1e336222..e796b0a7e4a5 100644 --- a/Documentation/admin-guide/mm/concepts.rst +++ b/Documentation/admin-guide/mm/concepts.rst @@ -1,5 +1,3 @@ -.. _mm_concepts: - ================= Concepts overview ================= @@ -86,16 +84,15 @@ memory with the huge pages. The first one is `HugeTLB filesystem`, or hugetlbfs. It is a pseudo filesystem that uses RAM as its backing store. For the files created in this filesystem the data resides in the memory and mapped using huge pages. The hugetlbfs is described at -:ref:`Documentation/admin-guide/mm/hugetlbpage.rst <hugetlbpage>`. +Documentation/admin-guide/mm/hugetlbpage.rst. Another, more recent, mechanism that enables use of the huge pages is called `Transparent HugePages`, or THP. Unlike the hugetlbfs that requires users and/or system administrators to configure what parts of the system memory should and can be mapped by the huge pages, THP manages such mappings transparently to the user and hence the -name. See -:ref:`Documentation/admin-guide/mm/transhuge.rst <admin_guide_transhuge>` -for more details about THP. +name. See Documentation/admin-guide/mm/transhuge.rst for more details +about THP. Zones ===== @@ -125,8 +122,8 @@ processor. Each bank is referred to as a `node` and for each node Linux constructs an independent memory management subsystem. A node has its own set of zones, lists of free and used pages and various statistics counters. You can find more details about NUMA in -:ref:`Documentation/mm/numa.rst <numa>` and in -:ref:`Documentation/admin-guide/mm/numa_memory_policy.rst <numa_memory_policy>`. +Documentation/mm/numa.rst` and in +Documentation/admin-guide/mm/numa_memory_policy.rst. Page cache ========== diff --git a/Documentation/admin-guide/mm/damon/lru_sort.rst b/Documentation/admin-guide/mm/damon/lru_sort.rst index c09cace80651..7b0775d281b4 100644 --- a/Documentation/admin-guide/mm/damon/lru_sort.rst +++ b/Documentation/admin-guide/mm/damon/lru_sort.rst @@ -54,7 +54,7 @@ that is built with ``CONFIG_DAMON_LRU_SORT=y``. To let sysadmins enable or disable it and tune for the given system, DAMON_LRU_SORT utilizes module parameters. That is, you can put ``damon_lru_sort.<parameter>=<value>`` on the kernel boot command line or write -proper values to ``/sys/modules/damon_lru_sort/parameters/<parameter>`` files. +proper values to ``/sys/module/damon_lru_sort/parameters/<parameter>`` files. Below are the description of each parameter. @@ -283,7 +283,7 @@ doesn't make progress and therefore the free memory rate becomes lower than 20%, it asks DAMON_LRU_SORT to do nothing again, so that we can fall back to the LRU-list based page granularity reclamation. :: - # cd /sys/modules/damon_lru_sort/parameters + # cd /sys/module/damon_lru_sort/parameters # echo 500 > hot_thres_access_freq # echo 120000000 > cold_min_age # echo 10 > quota_ms diff --git a/Documentation/admin-guide/mm/damon/reclaim.rst b/Documentation/admin-guide/mm/damon/reclaim.rst index 4f1479a11e63..343e25b252f4 100644 --- a/Documentation/admin-guide/mm/damon/reclaim.rst +++ b/Documentation/admin-guide/mm/damon/reclaim.rst @@ -46,7 +46,7 @@ that is built with ``CONFIG_DAMON_RECLAIM=y``. To let sysadmins enable or disable it and tune for the given system, DAMON_RECLAIM utilizes module parameters. That is, you can put ``damon_reclaim.<parameter>=<value>`` on the kernel boot command line or write -proper values to ``/sys/modules/damon_reclaim/parameters/<parameter>`` files. +proper values to ``/sys/module/damon_reclaim/parameters/<parameter>`` files. Below are the description of each parameter. @@ -205,6 +205,15 @@ The end physical address of memory region that DAMON_RECLAIM will do work against. That is, DAMON_RECLAIM will find cold memory regions in this region and reclaims. By default, biggest System RAM is used as the region. +skip_anon +--------- + +Skip anonymous pages reclamation. + +If this parameter is set as ``Y``, DAMON_RECLAIM does not reclaim anonymous +pages. By default, ``N``. + + kdamond_pid ----------- @@ -251,7 +260,7 @@ therefore the free memory rate becomes lower than 20%, it asks DAMON_RECLAIM to do nothing again, so that we can fall back to the LRU-list based page granularity reclamation. :: - # cd /sys/modules/damon_reclaim/parameters + # cd /sys/module/damon_reclaim/parameters # echo 30000000 > min_age # echo $((1 * 1024 * 1024 * 1024)) > quota_sz # echo 1000 > quota_reset_interval_ms diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst index 1a5b6b71efa1..9b823fec974d 100644 --- a/Documentation/admin-guide/mm/damon/usage.rst +++ b/Documentation/admin-guide/mm/damon/usage.rst @@ -25,10 +25,12 @@ DAMON provides below interfaces for different users. interface provides only simple :ref:`statistics <damos_stats>` for the monitoring results. For detailed monitoring results, DAMON provides a :ref:`tracepoint <tracepoint>`. -- *debugfs interface.* +- *debugfs interface. (DEPRECATED!)* :ref:`This <debugfs_interface>` is almost identical to :ref:`sysfs interface - <sysfs_interface>`. This will be removed after next LTS kernel is released, - so users should move to the :ref:`sysfs interface <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 @@ -87,6 +89,8 @@ comma (","). :: │ │ │ │ │ │ │ quotas/ms,bytes,reset_interval_ms │ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil │ │ │ │ │ │ │ watermarks/metric,interval_us,high,mid,low + │ │ │ │ │ │ │ filters/nr_filters + │ │ │ │ │ │ │ │ 0/type,matching,memcg_id │ │ │ │ │ │ │ stats/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds │ │ │ │ │ │ │ tried_regions/ │ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age @@ -151,6 +155,8 @@ number (``N``) to the file creates the number of child directories named as moment, only one context per kdamond is supported, so only ``0`` or ``1`` can be written to the file. +.. _sysfs_contexts: + contexts/<N>/ ------------- @@ -268,21 +274,32 @@ schemes/<N>/ ------------ In each scheme directory, five directories (``access_pattern``, ``quotas``, -``watermarks``, ``stats``, and ``tried_regions``) and one file (``action``) -exist. +``watermarks``, ``filters``, ``stats``, and ``tried_regions``) and one file +(``action``) exist. The ``action`` file is for setting and getting what action you want to apply to memory regions having specific access pattern of the interest. The keywords that can be written to and read from the file and their meaning are as below. - - ``willneed``: Call ``madvise()`` for the region with ``MADV_WILLNEED`` - - ``cold``: Call ``madvise()`` for the region with ``MADV_COLD`` - - ``pageout``: Call ``madvise()`` for the region with ``MADV_PAGEOUT`` - - ``hugepage``: Call ``madvise()`` for the region with ``MADV_HUGEPAGE`` - - ``nohugepage``: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE`` +Note that support of each action depends on the running DAMON operations set +`implementation <sysfs_contexts>`. + + - ``willneed``: Call ``madvise()`` for the region with ``MADV_WILLNEED``. + Supported by ``vaddr`` and ``fvaddr`` operations set. + - ``cold``: Call ``madvise()`` for the region with ``MADV_COLD``. + Supported by ``vaddr`` and ``fvaddr`` operations set. + - ``pageout``: Call ``madvise()`` for the region with ``MADV_PAGEOUT``. + Supported by ``vaddr``, ``fvaddr`` and ``paddr`` operations set. + - ``hugepage``: Call ``madvise()`` for the region with ``MADV_HUGEPAGE``. + Supported by ``vaddr`` and ``fvaddr`` operations set. + - ``nohugepage``: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE``. + Supported by ``vaddr`` and ``fvaddr`` operations set. - ``lru_prio``: Prioritize the region on its LRU lists. + Supported by ``paddr`` operations set. - ``lru_deprio``: Deprioritize the region on its LRU lists. - - ``stat``: Do nothing but count the statistics + Supported by ``paddr`` operations set. + - ``stat``: Do nothing but count the statistics. + Supported by all operations sets. schemes/<N>/access_pattern/ --------------------------- @@ -347,6 +364,46 @@ as below. The ``interval`` should written in microseconds unit. +schemes/<N>/filters/ +-------------------- + +Users could know something more than the kernel for specific types of memory. +In the case, users could do their own management for the memory and hence +doesn't want DAMOS bothers that. Users could limit DAMOS by setting the access +pattern of the scheme and/or the monitoring regions for the purpose, but that +can be inefficient in some cases. In such cases, users could set non-access +pattern driven filters using files in this directory. + +In the beginning, this directory has only one file, ``nr_filters``. Writing a +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. + +For example, below restricts a DAMOS action to be applied to only non-anonymous +pages of all memory cgroups except ``/having_care_already``.:: + + # echo 2 > nr_filters + # # filter out anonymous pages + echo anon > 0/type + echo Y > 0/matching + # # further filter out all cgroups except one at '/having_care_already' + echo memcg > 1/type + 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. + .. _sysfs_schemes_stats: schemes/<N>/stats/ @@ -432,13 +489,17 @@ the files as above. Above is only for an example. .. _debugfs_interface: -debugfs Interface -================= +debugfs Interface (DEPRECATED!) +=============================== .. note:: - DAMON debugfs interface will be removed after next LTS kernel is released, so - users should move to the :ref:`sysfs interface <sysfs_interface>`. + THIS IS DEPRECATED! + + DAMON debugfs interface 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. DAMON exports eight files, ``attrs``, ``target_ids``, ``init_regions``, ``schemes``, ``monitor_on``, ``kdamond_pid``, ``mk_contexts`` and @@ -574,11 +635,15 @@ The ``<action>`` is a predefined integer for memory management actions, which DAMON will apply to the regions having the target access pattern. The supported numbers and their meanings are as below. - - 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`` + - 0: Call ``madvise()`` for the region with ``MADV_WILLNEED``. Ignored if + ``target`` is ``paddr``. + - 1: Call ``madvise()`` for the region with ``MADV_COLD``. Ignored if + ``target`` is ``paddr``. + - 2: Call ``madvise()`` for the region with ``MADV_PAGEOUT``. + - 3: Call ``madvise()`` for the region with ``MADV_HUGEPAGE``. Ignored if + ``target`` is ``paddr``. + - 4: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE``. Ignored if + ``target`` is ``paddr``. - 5: Do nothing but count the statistics Quota diff --git a/Documentation/admin-guide/mm/hugetlbpage.rst b/Documentation/admin-guide/mm/hugetlbpage.rst index 19f27c0d92e0..e4d4b4a8dc97 100644 --- a/Documentation/admin-guide/mm/hugetlbpage.rst +++ b/Documentation/admin-guide/mm/hugetlbpage.rst @@ -1,5 +1,3 @@ -.. _hugetlbpage: - ============= HugeTLB Pages ============= @@ -86,7 +84,7 @@ by increasing or decreasing the value of ``nr_hugepages``. Note: When the feature of freeing unused vmemmap pages associated with each hugetlb page is enabled, we can fail to free the huge pages triggered by -the user when ths system is under memory pressure. Please try again later. +the user when the system is under memory pressure. Please try again later. Pages that are used as huge pages are reserved inside the kernel and cannot be used for other purposes. Huge pages cannot be swapped out under @@ -313,7 +311,7 @@ memory policy mode--bind, preferred, local or interleave--may be used. The resulting effect on persistent huge page allocation is as follows: #. Regardless of mempolicy mode [see - :ref:`Documentation/admin-guide/mm/numa_memory_policy.rst <numa_memory_policy>`], + Documentation/admin-guide/mm/numa_memory_policy.rst], persistent huge pages will be distributed across the node or nodes specified in the mempolicy as if "interleave" had been specified. However, if a node in the policy does not contain sufficient contiguous @@ -461,13 +459,13 @@ Examples .. _map_hugetlb: ``map_hugetlb`` - see tools/testing/selftests/vm/map_hugetlb.c + see tools/testing/selftests/mm/map_hugetlb.c ``hugepage-shm`` - see tools/testing/selftests/vm/hugepage-shm.c + see tools/testing/selftests/mm/hugepage-shm.c ``hugepage-mmap`` - see tools/testing/selftests/vm/hugepage-mmap.c + see tools/testing/selftests/mm/hugepage-mmap.c The `libhugetlbfs`_ library provides a wide range of userspace tools to help with huge page usability, environment setup, and control. diff --git a/Documentation/admin-guide/mm/idle_page_tracking.rst b/Documentation/admin-guide/mm/idle_page_tracking.rst index df9394fb39c2..16fcf38dac56 100644 --- a/Documentation/admin-guide/mm/idle_page_tracking.rst +++ b/Documentation/admin-guide/mm/idle_page_tracking.rst @@ -1,5 +1,3 @@ -.. _idle_page_tracking: - ================== Idle Page Tracking ================== @@ -65,14 +63,13 @@ workload one should: are not reclaimable, he or she can filter them out using ``/proc/kpageflags``. -The page-types tool in the tools/vm directory can be used to assist in this. +The page-types tool in the tools/mm directory can be used to assist in this. If the tool is run initially with the appropriate option, it will mark all the queried pages as idle. Subsequent runs of the tool can then show which pages have their idle flag cleared in the interim. -See :ref:`Documentation/admin-guide/mm/pagemap.rst <pagemap>` for more -information about ``/proc/pid/pagemap``, ``/proc/kpageflags``, and -``/proc/kpagecgroup``. +See Documentation/admin-guide/mm/pagemap.rst for more information about +``/proc/pid/pagemap``, ``/proc/kpageflags``, and ``/proc/kpagecgroup``. .. _impl_details: diff --git a/Documentation/admin-guide/mm/index.rst b/Documentation/admin-guide/mm/index.rst index d1064e0ba34a..1f883abf3f00 100644 --- a/Documentation/admin-guide/mm/index.rst +++ b/Documentation/admin-guide/mm/index.rst @@ -16,8 +16,7 @@ are described in Documentation/admin-guide/sysctl/vm.rst and in `man 5 proc`_. .. _man 5 proc: http://man7.org/linux/man-pages/man5/proc.5.html Linux memory management has its own jargon and if you are not yet -familiar with it, consider reading -:ref:`Documentation/admin-guide/mm/concepts.rst <mm_concepts>`. +familiar with it, consider reading Documentation/admin-guide/mm/concepts.rst. Here we document in detail how to interact with various mechanisms in the Linux memory management. diff --git a/Documentation/admin-guide/mm/ksm.rst b/Documentation/admin-guide/mm/ksm.rst index fb6ba2002a4b..eed51a910c94 100644 --- a/Documentation/admin-guide/mm/ksm.rst +++ b/Documentation/admin-guide/mm/ksm.rst @@ -1,5 +1,3 @@ -.. _admin_guide_ksm: - ======================= Kernel Samepage Merging ======================= diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst b/Documentation/admin-guide/mm/memory-hotplug.rst index a3c9e8ad8fa0..1b02fe5807cc 100644 --- a/Documentation/admin-guide/mm/memory-hotplug.rst +++ b/Documentation/admin-guide/mm/memory-hotplug.rst @@ -1,5 +1,3 @@ -.. _admin_guide_memory_hotplug: - ================== Memory Hot(Un)Plug ================== diff --git a/Documentation/admin-guide/mm/numa_memory_policy.rst b/Documentation/admin-guide/mm/numa_memory_policy.rst index 5a6afecbb0d0..46515ad2337f 100644 --- a/Documentation/admin-guide/mm/numa_memory_policy.rst +++ b/Documentation/admin-guide/mm/numa_memory_policy.rst @@ -1,5 +1,3 @@ -.. _numa_memory_policy: - ================== NUMA Memory Policy ================== @@ -246,7 +244,7 @@ MPOL_INTERLEAVED interleaved system default policy works in this mode. MPOL_PREFERRED_MANY - This mode specifices that the allocation should be preferrably + This mode specifies that the allocation should be preferably satisfied from the nodemask specified in the policy. If there is a memory pressure on all nodes in the nodemask, the allocation can fall back to all existing numa nodes. This is effectively @@ -360,7 +358,7 @@ and NUMA nodes. "Usage" here means one of the following: 2) examination of the policy to determine the policy mode and associated node or node lists, if any, for page allocation. This is considered a "hot path". Note that for MPOL_BIND, the "usage" extends across the entire - allocation process, which may sleep during page reclaimation, because the + allocation process, which may sleep during page reclamation, because the BIND policy nodemask is used, by reference, to filter ineligible nodes. We can avoid taking an extra reference during the usages listed above as diff --git a/Documentation/admin-guide/mm/numaperf.rst b/Documentation/admin-guide/mm/numaperf.rst index 166697325947..90a12b6a8bfc 100644 --- a/Documentation/admin-guide/mm/numaperf.rst +++ b/Documentation/admin-guide/mm/numaperf.rst @@ -1,6 +1,7 @@ -.. _numaperf: +======================= +NUMA Memory Performance +======================= -============= NUMA Locality ============= @@ -61,7 +62,6 @@ that are CPUs and hence suitable for generic task scheduling, and IO initiators such as GPUs and NICs. Unlike access class 0, only nodes containing CPUs are considered. -================ NUMA Performance ================ @@ -96,7 +96,6 @@ for the platform. Access class 1 takes the same form but only includes values for CPU to memory activity. -========== NUMA Cache ========== @@ -170,7 +169,6 @@ The "size" is the number of bytes provided by this cache level. The "write_policy" will be 0 for write-back, and non-zero for write-through caching. -======== See Also ======== diff --git a/Documentation/admin-guide/mm/pagemap.rst b/Documentation/admin-guide/mm/pagemap.rst index 6e2e416af783..b5f970dc91e7 100644 --- a/Documentation/admin-guide/mm/pagemap.rst +++ b/Documentation/admin-guide/mm/pagemap.rst @@ -1,5 +1,3 @@ -.. _pagemap: - ============================= Examining Process Page Tables ============================= @@ -19,10 +17,10 @@ There are four components to pagemap: * Bits 0-4 swap type if swapped * Bits 5-54 swap offset if swapped * Bit 55 pte is soft-dirty (see - :ref:`Documentation/admin-guide/mm/soft-dirty.rst <soft_dirty>`) + Documentation/admin-guide/mm/soft-dirty.rst) * Bit 56 page exclusively mapped (since 4.2) * Bit 57 pte is uffd-wp write-protected (since 5.13) (see - :ref:`Documentation/admin-guide/mm/userfaultfd.rst <userfaultfd>`) + Documentation/admin-guide/mm/userfaultfd.rst) * Bits 58-60 zero * Bit 61 page is file-page or shared-anon (since 3.5) * Bit 62 page swapped @@ -46,7 +44,7 @@ There are four components to pagemap: * ``/proc/kpagecount``. This file contains a 64-bit count of the number of times each page is mapped, indexed by PFN. -The page-types tool in the tools/vm directory can be used to query the +The page-types tool in the tools/mm directory can be used to query the number of times a page is mapped. * ``/proc/kpageflags``. This file contains a 64-bit set of flags for each @@ -105,8 +103,7 @@ Short descriptions to the page flags A compound page with order N consists of 2^N physically contiguous pages. A compound page with order 2 takes the form of "HTTT", where H donates its head page and T donates its tail page(s). The major consumers of compound - pages are hugeTLB pages - (:ref:`Documentation/admin-guide/mm/hugetlbpage.rst <hugetlbpage>`), + pages are hugeTLB pages (Documentation/admin-guide/mm/hugetlbpage.rst), the SLUB etc. memory allocators and various device drivers. However in this interface, only huge/giga pages are made visible to end users. @@ -128,7 +125,7 @@ Short descriptions to the page flags Zero page for pfn_zero or huge_zero page. 25 - IDLE The page has not been accessed since it was marked idle (see - :ref:`Documentation/admin-guide/mm/idle_page_tracking.rst <idle_page_tracking>`). + Documentation/admin-guide/mm/idle_page_tracking.rst). Note that this flag may be stale in case the page was accessed via a PTE. To make sure the flag is up-to-date one has to read ``/sys/kernel/mm/page_idle/bitmap`` first. @@ -173,7 +170,7 @@ LRU related page flags 14 - SWAPBACKED The page is backed by swap/RAM. -The page-types tool in the tools/vm directory can be used to query the +The page-types tool in the tools/mm directory can be used to query the above flags. Using pagemap to do something useful diff --git a/Documentation/admin-guide/mm/shrinker_debugfs.rst b/Documentation/admin-guide/mm/shrinker_debugfs.rst index 3887f0b294fe..c582033bd113 100644 --- a/Documentation/admin-guide/mm/shrinker_debugfs.rst +++ b/Documentation/admin-guide/mm/shrinker_debugfs.rst @@ -1,5 +1,3 @@ -.. _shrinker_debugfs: - ========================== Shrinker Debugfs Interface ========================== diff --git a/Documentation/admin-guide/mm/soft-dirty.rst b/Documentation/admin-guide/mm/soft-dirty.rst index cb0cfd6672fa..aeea936caa44 100644 --- a/Documentation/admin-guide/mm/soft-dirty.rst +++ b/Documentation/admin-guide/mm/soft-dirty.rst @@ -1,5 +1,3 @@ -.. _soft_dirty: - =============== Soft-Dirty PTEs =============== diff --git a/Documentation/admin-guide/mm/swap_numa.rst b/Documentation/admin-guide/mm/swap_numa.rst index e0466f2db8fa..2e630627bcee 100644 --- a/Documentation/admin-guide/mm/swap_numa.rst +++ b/Documentation/admin-guide/mm/swap_numa.rst @@ -1,5 +1,3 @@ -.. _swap_numa: - =========================================== Automatically bind swap device to numa node =========================================== diff --git a/Documentation/admin-guide/mm/transhuge.rst b/Documentation/admin-guide/mm/transhuge.rst index 8ee78ec232eb..b0cc8243e093 100644 --- a/Documentation/admin-guide/mm/transhuge.rst +++ b/Documentation/admin-guide/mm/transhuge.rst @@ -1,5 +1,3 @@ -.. _admin_guide_transhuge: - ============================ Transparent Hugepage Support ============================ diff --git a/Documentation/admin-guide/mm/userfaultfd.rst b/Documentation/admin-guide/mm/userfaultfd.rst index 83f31919ebb3..7dc823b56ca4 100644 --- a/Documentation/admin-guide/mm/userfaultfd.rst +++ b/Documentation/admin-guide/mm/userfaultfd.rst @@ -1,5 +1,3 @@ -.. _userfaultfd: - =========== Userfaultfd =========== diff --git a/Documentation/admin-guide/mm/zswap.rst b/Documentation/admin-guide/mm/zswap.rst index f67de481c7f6..c5c2c7dbb155 100644 --- a/Documentation/admin-guide/mm/zswap.rst +++ b/Documentation/admin-guide/mm/zswap.rst @@ -1,5 +1,3 @@ -.. _zswap: - ===== zswap ===== @@ -70,9 +68,7 @@ e.g. ``zswap.zpool=zbud``. It can also be changed at runtime using the sysfs The zbud type zpool allocates exactly 1 page to store 2 compressed pages, which 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. However, -zsmalloc does not implement compressed page eviction, so once zswap fills it -cannot evict the oldest page, it can only reject new pages. +storage method, and it can achieve greater storage densities. When a swap page is passed from frontswap to zswap, zswap maintains a mapping of the swap entry, a combination of the swap type and swap offset, to the zpool diff --git a/Documentation/admin-guide/perf/hns3-pmu.rst b/Documentation/admin-guide/perf/hns3-pmu.rst index 578407e487d6..75a40846d47f 100644 --- a/Documentation/admin-guide/perf/hns3-pmu.rst +++ b/Documentation/admin-guide/perf/hns3-pmu.rst @@ -53,7 +53,7 @@ two events have same value of bits 0~15 of config, that means they are event pair. And the bit 16 of config indicates getting counter 0 or counter 1 of hardware event. -After getting two values of event pair in usersapce, the formula of +After getting two values of event pair in userspace, the formula of computation to calculate real performance data is::: counter 0 / counter 1 diff --git a/Documentation/admin-guide/pm/amd-pstate.rst b/Documentation/admin-guide/pm/amd-pstate.rst index 5376d53faaa8..6e5298b521b1 100644 --- a/Documentation/admin-guide/pm/amd-pstate.rst +++ b/Documentation/admin-guide/pm/amd-pstate.rst @@ -230,8 +230,8 @@ with :c:macro:`MSR_AMD_CPPC_ENABLE` or ``cppc_set_enable``, it will respond to the request from AMD P-States. -User Space Interface in ``sysfs`` -================================== +User Space Interface in ``sysfs`` - Per-policy control +====================================================== ``amd-pstate`` exposes several global attributes (files) in ``sysfs`` to control its functionality at the system level. They are located in the @@ -262,6 +262,25 @@ lowest non-linear performance in `AMD CPPC Performance Capability <perf_cap_>`_.) This attribute is read-only. +``energy_performance_available_preferences`` + +A list of all the supported EPP preferences that could be used for +``energy_performance_preference`` on this system. +These profiles represent different hints that are provided +to the low-level firmware about the user's desired energy vs efficiency +tradeoff. ``default`` represents the epp value is set by platform +firmware. This attribute is read-only. + +``energy_performance_preference`` + +The current energy performance preference can be read from this attribute. +and user can change current preference according to energy or performance needs +Please get all support profiles list from +``energy_performance_available_preferences`` attribute, all the profiles are +integer values defined between 0 to 255 when EPP feature is enabled by platform +firmware, if EPP feature is disabled, driver will ignore the written value +This attribute is read-write. + Other performance and frequency values can be read back from ``/sys/devices/system/cpu/cpuX/acpi_cppc/``, see :ref:`cppc_sysfs`. @@ -280,8 +299,30 @@ module which supports the new AMD P-States mechanism on most of the future AMD platforms. The AMD P-States mechanism is the more performance and energy efficiency frequency management method on AMD processors. -Kernel Module Options for ``amd-pstate`` -========================================= + +AMD Pstate Driver Operation Modes +================================= + +``amd_pstate`` CPPC has two operation modes: CPPC Autonomous(active) mode and +CPPC non-autonomous(passive) mode. +active mode and passive mode can be chosen by different kernel parameters. +When in Autonomous mode, CPPC ignores requests done in the Desired Performance +Target register and takes into account only the values set to the Minimum requested +performance, Maximum requested performance, and Energy Performance Preference +registers. When Autonomous is disabled, it only considers the Desired Performance Target. + +Active Mode +------------ + +``amd_pstate=active`` + +This is the low-level firmware control mode which is implemented by ``amd_pstate_epp`` +driver with ``amd_pstate=active`` passed to the kernel in the command line. +In this mode, ``amd_pstate_epp`` driver provides a hint to the hardware if software +wants to bias toward performance (0x0) or energy efficiency (0xff) to the CPPC firmware. +then CPPC power algorithm will calculate the runtime workload and adjust the realtime +cores frequency according to the power supply and thermal, core voltage and some other +hardware conditions. Passive Mode ------------ @@ -298,6 +339,35 @@ processor must provide at least nominal performance requested and go higher if c operating conditions allow. +User Space Interface in ``sysfs`` - General +=========================================== + +Global Attributes +----------------- + +``amd-pstate`` exposes several global attributes (files) in ``sysfs`` to +control its functionality at the system level. They are located in the +``/sys/devices/system/cpu/amd-pstate/`` directory and affect all CPUs. + +``status`` + Operation mode of the driver: "active", "passive" or "disable". + + "active" + The driver is functional and in the ``active mode`` + + "passive" + The driver is functional and in the ``passive mode`` + + "disable" + The driver is unregistered and not functional now. + + This attribute can be written to in order to change the driver's + operation mode or to unregister it. The string written to it must be + one of the possible values of it and, if successful, writing one of + these values to the sysfs file will cause the driver to switch over + to the operation mode represented by that string - or to be + unregistered in the "disable" case. + ``cpupower`` tool support for ``amd-pstate`` =============================================== @@ -403,7 +473,7 @@ Unit Tests for amd-pstate * We can introduce more functional or performance tests to align the result together, it will benefit power and performance scale optimization. -1. Test case decriptions +1. Test case descriptions 1). Basic tests diff --git a/Documentation/admin-guide/pm/intel_pstate.rst b/Documentation/admin-guide/pm/intel_pstate.rst index d5043cd8d2f5..bf13ad25a32f 100644 --- a/Documentation/admin-guide/pm/intel_pstate.rst +++ b/Documentation/admin-guide/pm/intel_pstate.rst @@ -712,7 +712,7 @@ it works in the `active mode <Active Mode_>`_. The following sequence of shell commands can be used to enable them and see their output (if the kernel is generally configured to support event tracing):: - # cd /sys/kernel/debug/tracing/ + # cd /sys/kernel/tracing/ # echo 1 > events/power/pstate_sample/enable # echo 1 > events/power/cpu_frequency/enable # cat trace @@ -732,7 +732,7 @@ The ``ftrace`` interface can be used for low-level diagnostics of P-state is called, the ``ftrace`` filter can be set to :c:func:`intel_pstate_set_pstate`:: - # cd /sys/kernel/debug/tracing/ + # cd /sys/kernel/tracing/ # cat available_filter_functions | grep -i pstate intel_pstate_set_pstate intel_pstate_cpu_init diff --git a/Documentation/admin-guide/spkguide.txt b/Documentation/admin-guide/spkguide.txt index 1265c1eab31c..74ea7f391942 100644 --- a/Documentation/admin-guide/spkguide.txt +++ b/Documentation/admin-guide/spkguide.txt @@ -1105,8 +1105,8 @@ speakup load Alternatively, you can add the above line to your file ~/.bashrc or ~/.bash_profile. -If your system administrator ran himself the script, all the users will be able -to change from English to the language choosed by root and do directly +If your system administrator himself ran the script, all the users will be able +to change from English to the language chosen by root and do directly speakupconf load (or add this to the ~/.bashrc or ~/.bash_profile file). If there are several languages to handle, the administrator (or every user) will have to run the first steps until speakupconf diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 46e3d62c0eea..4b7bfea28cd7 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -453,9 +453,10 @@ this allows system administrators to override the kexec_load_disabled =================== -A toggle indicating if the ``kexec_load`` syscall has been disabled. -This value defaults to 0 (false: ``kexec_load`` enabled), but can be -set to 1 (true: ``kexec_load`` disabled). +A toggle indicating if the syscalls ``kexec_load`` and +``kexec_file_load`` have been disabled. +This value defaults to 0 (false: ``kexec_*load`` enabled), but can be +set to 1 (true: ``kexec_*load`` disabled). Once true, kexec can no longer be used, and the toggle cannot be set back to false. This allows a kexec image to be loaded before disabling the syscall, @@ -463,6 +464,24 @@ allowing a system to set up (and later use) an image without it being altered. Generally used together with the `modules_disabled`_ sysctl. +kexec_load_limit_panic +====================== + +This parameter specifies a limit to the number of times the syscalls +``kexec_load`` and ``kexec_file_load`` can be called with a crash +image. It can only be set with a more restrictive value than the +current one. + +== ====================================================== +-1 Unlimited calls to kexec. This is the default setting. +N Number of calls left. +== ====================================================== + +kexec_load_limit_reboot +======================= + +Similar functionality as ``kexec_load_limit_panic``, but for a normal +image. kptr_restrict ============= diff --git a/Documentation/admin-guide/sysctl/net.rst b/Documentation/admin-guide/sysctl/net.rst index 6394f5dc2303..466c560b0c30 100644 --- a/Documentation/admin-guide/sysctl/net.rst +++ b/Documentation/admin-guide/sysctl/net.rst @@ -215,6 +215,12 @@ rmem_max The maximum receive socket buffer size in bytes. +rps_default_mask +---------------- + +The default RPS CPU mask used on newly created network devices. An empty +mask means RPS disabled by default. + tstamp_allow_data ----------------- Allow processes to receive tx timestamps looped together with the original diff --git a/Documentation/admin-guide/sysctl/vm.rst b/Documentation/admin-guide/sysctl/vm.rst index 988f6a4c8084..45ba1f4dc004 100644 --- a/Documentation/admin-guide/sysctl/vm.rst +++ b/Documentation/admin-guide/sysctl/vm.rst @@ -356,7 +356,7 @@ The lowmem_reserve_ratio is an array. You can see them by reading this file:: But, these values are not used directly. The kernel calculates # of protection pages for each zones from them. These are shown as array of protection pages -in /proc/zoneinfo like followings. (This is an example of x86-64 box). +in /proc/zoneinfo like the following. (This is an example of x86-64 box). Each zone has an array of protection pages like this:: Node 0, zone DMA @@ -433,7 +433,7 @@ a 2bit error in a memory module) is detected in the background by hardware that cannot be handled by the kernel. In some cases (like the page still having a valid copy on disk) the kernel will handle the failure transparently without affecting any applications. But if there is -no other uptodate copy of the data it will kill to prevent any data +no other up-to-date copy of the data it will kill to prevent any data corruptions from propagating. 1: Kill all processes that have the corrupted and not reloadable page mapped diff --git a/Documentation/admin-guide/sysrq.rst b/Documentation/admin-guide/sysrq.rst index 0a178ef0111d..51906e47327b 100644 --- a/Documentation/admin-guide/sysrq.rst +++ b/Documentation/admin-guide/sysrq.rst @@ -138,7 +138,7 @@ Command Function ``v`` Forcefully restores framebuffer console ``v`` Causes ETM buffer dump [ARM-specific] -``w`` Dumps tasks that are in uninterruptable (blocked) state. +``w`` Dumps tasks that are in uninterruptible (blocked) state. ``x`` Used by xmon interface on ppc/powerpc platforms. Show global PMU Registers on sparc64. diff --git a/Documentation/admin-guide/thermal/index.rst b/Documentation/admin-guide/thermal/index.rst new file mode 100644 index 000000000000..193b7b01a87d --- /dev/null +++ b/Documentation/admin-guide/thermal/index.rst @@ -0,0 +1,8 @@ +================= +Thermal Subsystem +================= + +.. toctree:: + :maxdepth: 1 + + intel_powerclamp diff --git a/Documentation/driver-api/thermal/intel_powerclamp.rst b/Documentation/admin-guide/thermal/intel_powerclamp.rst index 3f6dfb0b3ea6..08509b978af4 100644 --- a/Documentation/driver-api/thermal/intel_powerclamp.rst +++ b/Documentation/admin-guide/thermal/intel_powerclamp.rst @@ -26,6 +26,8 @@ By: - Generic Thermal Layer (sysfs) - Kernel APIs (TBD) + (*) Module Parameters + INTRODUCTION ============ @@ -85,7 +87,7 @@ migrated, unless the CPU is taken offline. In this case, threads belong to the offlined CPUs will be terminated immediately. Running as SCHED_FIFO and relatively high priority, also allows such -scheme to work for both preemptable and non-preemptable kernels. +scheme to work for both preemptible and non-preemptible kernels. Alignment of idle time around jiffies ensures scalability for HZ values. This effect can be better visualized using a Perf timechart. The following diagram shows the behavior of kernel thread @@ -153,13 +155,15 @@ b) determine the amount of compensation needed at each target ratio Compensation to each target ratio consists of two parts: a) steady state error compensation - This is to offset the error occurring when the system can - enter idle without extra wakeups (such as external interrupts). + + This is to offset the error occurring when the system can + enter idle without extra wakeups (such as external interrupts). b) dynamic error compensation - When an excessive amount of wakeups occurs during idle, an - additional idle ratio can be added to quiet interrupts, by - slowing down CPU activities. + + When an excessive amount of wakeups occurs during idle, an + additional idle ratio can be added to quiet interrupts, by + slowing down CPU activities. A debugfs file is provided for the user to examine compensation progress and results, such as on a Westmere system:: @@ -281,6 +285,7 @@ cur_state returns value -1 instead of 0 which is to avoid confusing 100% busy state with the disabled state. Example usage: + - To inject 25% idle time:: $ sudo sh -c "echo 25 > /sys/class/thermal/cooling_device80/cur_state @@ -318,3 +323,23 @@ device, a PID based userspace thermal controller can manage to control CPU temperature effectively, when no other thermal influence is added. For example, a UltraBook user can compile the kernel under certain temperature (below most active trip points). + +Module Parameters +================= + +``cpumask`` (RW) + A bit mask of CPUs to inject idle. The format of the bitmask is same as + used in other subsystems like in /proc/irq/\*/smp_affinity. The mask is + comma separated 32 bit groups. Each CPU is one bit. For example for a 256 + CPU system the full mask is: + ffffffff,ffffffff,ffffffff,ffffffff,ffffffff,ffffffff,ffffffff,ffffffff + + The rightmost mask is for CPU 0-32. + +``max_idle`` (RW) + Maximum injected idle time to the total CPU time ratio in percent range + from 1 to 100. Even if the cooling device max_state is always 100 (100%), + this parameter allows to add a max idle percent limit. The default is 50, + to match the current implementation of powerclamp driver. Also doesn't + allow value more than 75, if the cpumask includes every CPU present in + the system. diff --git a/Documentation/admin-guide/workload-tracing.rst b/Documentation/admin-guide/workload-tracing.rst new file mode 100644 index 000000000000..b2e254ec8ee8 --- /dev/null +++ b/Documentation/admin-guide/workload-tracing.rst @@ -0,0 +1,606 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) + +====================================================== +Discovering Linux kernel subsystems used by a workload +====================================================== + +:Authors: - Shuah Khan <skhan@linuxfoundation.org> + - Shefali Sharma <sshefali021@gmail.com> +:maintained-by: Shuah Khan <skhan@linuxfoundation.org> + +Key Points +========== + + * Understanding system resources necessary to build and run a workload + is important. + * Linux tracing and strace can be used to discover the system resources + in use by a workload. The completeness of the system usage information + depends on the completeness of coverage of a workload. + * Performance and security of the operating system can be analyzed with + the help of tools such as: + `perf <https://man7.org/linux/man-pages/man1/perf.1.html>`_, + `stress-ng <https://www.mankier.com/1/stress-ng>`_, + `paxtest <https://github.com/opntr/paxtest-freebsd>`_. + * Once we discover and understand the workload needs, we can focus on them + to avoid regressions and use it to evaluate safety considerations. + +Methodology +=========== + +`strace <https://man7.org/linux/man-pages/man1/strace.1.html>`_ is a +diagnostic, instructional, and debugging tool and can be used to discover +the system resources in use by a workload. Once we discover and understand +the workload needs, we can focus on them to avoid regressions and use it +to evaluate safety considerations. We use strace tool to trace workloads. + +This method of tracing using strace tells us the system calls invoked by +the workload and doesn't include all the system calls that can be invoked +by it. In addition, this tracing method tells us just the code paths within +these system calls that are invoked. As an example, if a workload opens a +file and reads from it successfully, then the success path is the one that +is traced. Any error paths in that system call will not be traced. If there +is a workload that provides full coverage of a workload then the method +outlined here will trace and find all possible code paths. The completeness +of the system usage information depends on the completeness of coverage of a +workload. + +The goal is tracing a workload on a system running a default kernel without +requiring custom kernel installs. + +How do we gather fine-grained system information? +================================================= + +strace tool can be used to trace system calls made by a process and signals +it receives. System calls are the fundamental interface between an +application and the operating system kernel. They enable a program to +request services from the kernel. For instance, the open() system call in +Linux is used to provide access to a file in the file system. strace enables +us to track all the system calls made by an application. It lists all the +system calls made by a process and their resulting output. + +You can generate profiling data combining strace and perf record tools to +record the events and information associated with a process. This provides +insight into the process. "perf annotate" tool generates the statistics of +each instruction of the program. This document goes over the details of how +to gather fine-grained information on a workload's usage of system resources. + +We used strace to trace the perf, stress-ng, paxtest workloads to illustrate +our methodology to discover resources used by a workload. This process can +be applied to trace other workloads. + +Getting the system ready for tracing +==================================== + +Before we can get started we will show you how to get your system ready. +We assume that you have a Linux distribution running on a physical system +or a virtual machine. Most distributions will include strace command. Let’s +install other tools that aren’t usually included to build Linux kernel. +Please note that the following works on Debian based distributions. You +might have to find equivalent packages on other Linux distributions. + +Install tools to build Linux kernel and tools in kernel repository. +scripts/ver_linux is a good way to check if your system already has +the necessary tools:: + + sudo apt-get build-essentials flex bison yacc + sudo apt install libelf-dev systemtap-sdt-dev libaudit-dev libslang2-dev libperl-dev libdw-dev + +cscope is a good tool to browse kernel sources. Let's install it now:: + + sudo apt-get install cscope + +Install stress-ng and paxtest:: + + apt-get install stress-ng + apt-get install paxtest + +Workload overview +================= + +As mentioned earlier, we used strace to trace perf bench, stress-ng and +paxtest workloads to show how to analyze a workload and identify Linux +subsystems used by these workloads. Let's start with an overview of these +three workloads to get a better understanding of what they do and how to +use them. + +perf bench (all) workload +------------------------- + +The perf bench command contains multiple multi-threaded microkernel +benchmarks for executing different subsystems in the Linux kernel and +system calls. This allows us to easily measure the impact of changes, +which can help mitigate performance regressions. It also acts as a common +benchmarking framework, enabling developers to easily create test cases, +integrate transparently, and use performance-rich tooling subsystems. + +Stress-ng netdev stressor workload +---------------------------------- + +stress-ng is used for performing stress testing on the kernel. It allows +you to exercise various physical subsystems of the computer, as well as +interfaces of the OS kernel, using "stressor-s". They are available for +CPU, CPU cache, devices, I/O, interrupts, file system, memory, network, +operating system, pipelines, schedulers, and virtual machines. Please refer +to the `stress-ng man-page <https://www.mankier.com/1/stress-ng>`_ to +find the description of all the available stressor-s. The netdev stressor +starts specified number (N) of workers that exercise various netdevice +ioctl commands across all the available network devices. + +paxtest kiddie workload +----------------------- + +paxtest is a program that tests buffer overflows in the kernel. It tests +kernel enforcements over memory usage. Generally, execution in some memory +segments makes buffer overflows possible. It runs a set of programs that +attempt to subvert memory usage. It is used as a regression test suite for +PaX, but might be useful to test other memory protection patches for the +kernel. We used paxtest kiddie mode which looks for simple vulnerabilities. + +What is strace and how do we use it? +==================================== + +As mentioned earlier, strace which is a useful diagnostic, instructional, +and debugging tool and can be used to discover the system resources in use +by a workload. It can be used: + + * To see how a process interacts with the kernel. + * To see why a process is failing or hanging. + * For reverse engineering a process. + * To find the files on which a program depends. + * For analyzing the performance of an application. + * For troubleshooting various problems related to the operating system. + +In addition, strace can generate run-time statistics on times, calls, and +errors for each system call and report a summary when program exits, +suppressing the regular output. This attempts to show system time (CPU time +spent running in the kernel) independent of wall clock time. We plan to use +these features to get information on workload system usage. + +strace command supports basic, verbose, and stats modes. strace command when +run in verbose mode gives more detailed information about the system calls +invoked by a process. + +Running strace -c generates a report of the percentage of time spent in each +system call, the total time in seconds, the microseconds per call, the total +number of calls, the count of each system call that has failed with an error +and the type of system call made. + + * Usage: strace <command we want to trace> + * Verbose mode usage: strace -v <command> + * Gather statistics: strace -c <command> + +We used the “-c†option to gather fine-grained run-time statistics in use +by three workloads we have chose for this analysis. + + * perf + * stress-ng + * paxtest + +What is cscope and how do we use it? +==================================== + +Now let’s look at `cscope <https://cscope.sourceforge.net/>`_, a command +line tool for browsing C, C++ or Java code-bases. We can use it to find +all the references to a symbol, global definitions, functions called by a +function, functions calling a function, text strings, regular expression +patterns, files including a file. + +We can use cscope to find which system call belongs to which subsystem. +This way we can find the kernel subsystems used by a process when it is +executed. + +Let’s checkout the latest Linux repository and build cscope database:: + + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git linux + cd linux + cscope -R -p10 # builds cscope.out database before starting browse session + cscope -d -p10 # starts browse session on cscope.out database + +Note: Run "cscope -R -p10" to build the database and c"scope -d -p10" to +enter into the browsing session. cscope by default cscope.out database. +To get out of this mode press ctrl+d. -p option is used to specify the +number of file path components to display. -p10 is optimal for browsing +kernel sources. + +What is perf and how do we use it? +================================== + +Perf is an analysis tool based on Linux 2.6+ systems, which abstracts the +CPU hardware difference in performance measurement in Linux, and provides +a simple command line interface. Perf is based on the perf_events interface +exported by the kernel. It is very useful for profiling the system and +finding performance bottlenecks in an application. + +If you haven't already checked out the Linux mainline repository, you can do +so and then build kernel and perf tool:: + + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git linux + cd linux + make -j3 all + cd tools/perf + make + +Note: The perf command can be built without building the kernel in the +repository and can be run on older kernels. However matching the kernel +and perf revisions gives more accurate information on the subsystem usage. + +We used "perf stat" and "perf bench" options. For a detailed information on +the perf tool, run "perf -h". + +perf stat +--------- +The perf stat command generates a report of various hardware and software +events. It does so with the help of hardware counter registers found in +modern CPUs that keep the count of these activities. "perf stat cal" shows +stats for cal command. + +Perf bench +---------- +The perf bench command contains multiple multi-threaded microkernel +benchmarks for executing different subsystems in the Linux kernel and +system calls. This allows us to easily measure the impact of changes, +which can help mitigate performance regressions. It also acts as a common +benchmarking framework, enabling developers to easily create test cases, +integrate transparently, and use performance-rich tooling. + +"perf bench all" command runs the following benchmarks: + + * sched/messaging + * sched/pipe + * syscall/basic + * mem/memcpy + * mem/memset + +What is stress-ng and how do we use it? +======================================= + +As mentioned earlier, stress-ng is used for performing stress testing on +the kernel. It allows you to exercise various physical subsystems of the +computer, as well as interfaces of the OS kernel, using stressor-s. They +are available for CPU, CPU cache, devices, I/O, interrupts, file system, +memory, network, operating system, pipelines, schedulers, and virtual +machines. + +The netdev stressor starts N workers that exercise various netdevice ioctl +commands across all the available network devices. The following ioctls are +exercised: + + * SIOCGIFCONF, SIOCGIFINDEX, SIOCGIFNAME, SIOCGIFFLAGS + * SIOCGIFADDR, SIOCGIFNETMASK, SIOCGIFMETRIC, SIOCGIFMTU + * SIOCGIFHWADDR, SIOCGIFMAP, SIOCGIFTXQLEN + +The following command runs the stressor:: + + stress-ng --netdev 1 -t 60 --metrics command. + +We can use the perf record command to record the events and information +associated with a process. This command records the profiling data in the +perf.data file in the same directory. + +Using the following commands you can record the events associated with the +netdev stressor, view the generated report perf.data and annotate the to +view the statistics of each instruction of the program:: + + perf record stress-ng --netdev 1 -t 60 --metrics command. + perf report + perf annotate + +What is paxtest and how do we use it? +===================================== + +paxtest is a program that tests buffer overflows in the kernel. It tests +kernel enforcements over memory usage. Generally, execution in some memory +segments makes buffer overflows possible. It runs a set of programs that +attempt to subvert memory usage. It is used as a regression test suite for +PaX, and will be useful to test other memory protection patches for the +kernel. + +paxtest provides kiddie and blackhat modes. The paxtest kiddie mode runs +in normal mode, whereas the blackhat mode tries to get around the protection +of the kernel testing for vulnerabilities. We focus on the kiddie mode here +and combine "paxtest kiddie" run with "perf record" to collect CPU stack +traces for the paxtest kiddie run to see which function is calling other +functions in the performance profile. Then the "dwarf" (DWARF's Call Frame +Information) mode can be used to unwind the stack. + +The following command can be used to view resulting report in call-graph +format:: + + perf record --call-graph dwarf paxtest kiddie + perf report --stdio + +Tracing workloads +================= + +Now that we understand the workloads, let's start tracing them. + +Tracing perf bench all workload +------------------------------- + +Run the following command to trace perf bench all workload:: + + strace -c perf bench all + +**System Calls made by the workload** + +The below table shows the system calls invoked by the workload, number of +times each system call is invoked, and the corresponding Linux subsystem. + ++-------------------+-----------+-----------------+-------------------------+ +| System Call | # calls | Linux Subsystem | System Call (API) | ++===================+===========+=================+=========================+ +| getppid | 10000001 | Process Mgmt | sys_getpid() | ++-------------------+-----------+-----------------+-------------------------+ +| clone | 1077 | Process Mgmt. | sys_clone() | ++-------------------+-----------+-----------------+-------------------------+ +| prctl | 23 | Process Mgmt. | sys_prctl() | ++-------------------+-----------+-----------------+-------------------------+ +| prlimit64 | 7 | Process Mgmt. | sys_prlimit64() | ++-------------------+-----------+-----------------+-------------------------+ +| getpid | 10 | Process Mgmt. | sys_getpid() | ++-------------------+-----------+-----------------+-------------------------+ +| uname | 3 | Process Mgmt. | sys_uname() | ++-------------------+-----------+-----------------+-------------------------+ +| sysinfo | 1 | Process Mgmt. | sys_sysinfo() | ++-------------------+-----------+-----------------+-------------------------+ +| getuid | 1 | Process Mgmt. | sys_getuid() | ++-------------------+-----------+-----------------+-------------------------+ +| getgid | 1 | Process Mgmt. | sys_getgid() | ++-------------------+-----------+-----------------+-------------------------+ +| geteuid | 1 | Process Mgmt. | sys_geteuid() | ++-------------------+-----------+-----------------+-------------------------+ +| getegid | 1 | Process Mgmt. | sys_getegid | ++-------------------+-----------+-----------------+-------------------------+ +| close | 49951 | Filesystem | sys_close() | ++-------------------+-----------+-----------------+-------------------------+ +| pipe | 604 | Filesystem | sys_pipe() | ++-------------------+-----------+-----------------+-------------------------+ +| openat | 48560 | Filesystem | sys_opennat() | ++-------------------+-----------+-----------------+-------------------------+ +| fstat | 8338 | Filesystem | sys_fstat() | ++-------------------+-----------+-----------------+-------------------------+ +| stat | 1573 | Filesystem | sys_stat() | ++-------------------+-----------+-----------------+-------------------------+ +| pread64 | 9646 | Filesystem | sys_pread64() | ++-------------------+-----------+-----------------+-------------------------+ +| getdents64 | 1873 | Filesystem | sys_getdents64() | ++-------------------+-----------+-----------------+-------------------------+ +| access | 3 | Filesystem | sys_access() | ++-------------------+-----------+-----------------+-------------------------+ +| lstat | 1880 | Filesystem | sys_lstat() | ++-------------------+-----------+-----------------+-------------------------+ +| lseek | 6 | Filesystem | sys_lseek() | ++-------------------+-----------+-----------------+-------------------------+ +| ioctl | 3 | Filesystem | sys_ioctl() | ++-------------------+-----------+-----------------+-------------------------+ +| dup2 | 1 | Filesystem | sys_dup2() | ++-------------------+-----------+-----------------+-------------------------+ +| execve | 2 | Filesystem | sys_execve() | ++-------------------+-----------+-----------------+-------------------------+ +| fcntl | 8779 | Filesystem | sys_fcntl() | ++-------------------+-----------+-----------------+-------------------------+ +| statfs | 1 | Filesystem | sys_statfs() | ++-------------------+-----------+-----------------+-------------------------+ +| epoll_create | 2 | Filesystem | sys_epoll_create() | ++-------------------+-----------+-----------------+-------------------------+ +| epoll_ctl | 64 | Filesystem | sys_epoll_ctl() | ++-------------------+-----------+-----------------+-------------------------+ +| newfstatat | 8318 | Filesystem | sys_newfstatat() | ++-------------------+-----------+-----------------+-------------------------+ +| eventfd2 | 192 | Filesystem | sys_eventfd2() | ++-------------------+-----------+-----------------+-------------------------+ +| mmap | 243 | Memory Mgmt. | sys_mmap() | ++-------------------+-----------+-----------------+-------------------------+ +| mprotect | 32 | Memory Mgmt. | sys_mprotect() | ++-------------------+-----------+-----------------+-------------------------+ +| brk | 21 | Memory Mgmt. | sys_brk() | ++-------------------+-----------+-----------------+-------------------------+ +| munmap | 128 | Memory Mgmt. | sys_munmap() | ++-------------------+-----------+-----------------+-------------------------+ +| set_mempolicy | 156 | Memory Mgmt. | sys_set_mempolicy() | ++-------------------+-----------+-----------------+-------------------------+ +| set_tid_address | 1 | Process Mgmt. | sys_set_tid_address() | ++-------------------+-----------+-----------------+-------------------------+ +| set_robust_list | 1 | Futex | sys_set_robust_list() | ++-------------------+-----------+-----------------+-------------------------+ +| futex | 341 | Futex | sys_futex() | ++-------------------+-----------+-----------------+-------------------------+ +| sched_getaffinity | 79 | Scheduler | sys_sched_getaffinity() | ++-------------------+-----------+-----------------+-------------------------+ +| sched_setaffinity | 223 | Scheduler | sys_sched_setaffinity() | ++-------------------+-----------+-----------------+-------------------------+ +| socketpair | 202 | Network | sys_socketpair() | ++-------------------+-----------+-----------------+-------------------------+ +| rt_sigprocmask | 21 | Signal | sys_rt_sigprocmask() | ++-------------------+-----------+-----------------+-------------------------+ +| rt_sigaction | 36 | Signal | sys_rt_sigaction() | ++-------------------+-----------+-----------------+-------------------------+ +| rt_sigreturn | 2 | Signal | sys_rt_sigreturn() | ++-------------------+-----------+-----------------+-------------------------+ +| wait4 | 889 | Time | sys_wait4() | ++-------------------+-----------+-----------------+-------------------------+ +| clock_nanosleep | 37 | Time | sys_clock_nanosleep() | ++-------------------+-----------+-----------------+-------------------------+ +| capget | 4 | Capability | sys_capget() | ++-------------------+-----------+-----------------+-------------------------+ + +Tracing stress-ng netdev stressor workload +------------------------------------------ + +Run the following command to trace stress-ng netdev stressor workload:: + + strace -c stress-ng --netdev 1 -t 60 --metrics + +**System Calls made by the workload** + +The below table shows the system calls invoked by the workload, number of +times each system call is invoked, and the corresponding Linux subsystem. + ++-------------------+-----------+-----------------+-------------------------+ +| System Call | # calls | Linux Subsystem | System Call (API) | ++===================+===========+=================+=========================+ +| openat | 74 | Filesystem | sys_openat() | ++-------------------+-----------+-----------------+-------------------------+ +| close | 75 | Filesystem | sys_close() | ++-------------------+-----------+-----------------+-------------------------+ +| read | 58 | Filesystem | sys_read() | ++-------------------+-----------+-----------------+-------------------------+ +| fstat | 20 | Filesystem | sys_fstat() | ++-------------------+-----------+-----------------+-------------------------+ +| flock | 10 | Filesystem | sys_flock() | ++-------------------+-----------+-----------------+-------------------------+ +| write | 7 | Filesystem | sys_write() | ++-------------------+-----------+-----------------+-------------------------+ +| getdents64 | 8 | Filesystem | sys_getdents64() | ++-------------------+-----------+-----------------+-------------------------+ +| pread64 | 8 | Filesystem | sys_pread64() | ++-------------------+-----------+-----------------+-------------------------+ +| lseek | 1 | Filesystem | sys_lseek() | ++-------------------+-----------+-----------------+-------------------------+ +| access | 2 | Filesystem | sys_access() | ++-------------------+-----------+-----------------+-------------------------+ +| getcwd | 1 | Filesystem | sys_getcwd() | ++-------------------+-----------+-----------------+-------------------------+ +| execve | 1 | Filesystem | sys_execve() | ++-------------------+-----------+-----------------+-------------------------+ +| mmap | 61 | Memory Mgmt. | sys_mmap() | ++-------------------+-----------+-----------------+-------------------------+ +| munmap | 3 | Memory Mgmt. | sys_munmap() | ++-------------------+-----------+-----------------+-------------------------+ +| mprotect | 20 | Memory Mgmt. | sys_mprotect() | ++-------------------+-----------+-----------------+-------------------------+ +| mlock | 2 | Memory Mgmt. | sys_mlock() | ++-------------------+-----------+-----------------+-------------------------+ +| brk | 3 | Memory Mgmt. | sys_brk() | ++-------------------+-----------+-----------------+-------------------------+ +| rt_sigaction | 21 | Signal | sys_rt_sigaction() | ++-------------------+-----------+-----------------+-------------------------+ +| rt_sigprocmask | 1 | Signal | sys_rt_sigprocmask() | ++-------------------+-----------+-----------------+-------------------------+ +| sigaltstack | 1 | Signal | sys_sigaltstack() | ++-------------------+-----------+-----------------+-------------------------+ +| rt_sigreturn | 1 | Signal | sys_rt_sigreturn() | ++-------------------+-----------+-----------------+-------------------------+ +| getpid | 8 | Process Mgmt. | sys_getpid() | ++-------------------+-----------+-----------------+-------------------------+ +| prlimit64 | 5 | Process Mgmt. | sys_prlimit64() | ++-------------------+-----------+-----------------+-------------------------+ +| arch_prctl | 2 | Process Mgmt. | sys_arch_prctl() | ++-------------------+-----------+-----------------+-------------------------+ +| sysinfo | 2 | Process Mgmt. | sys_sysinfo() | ++-------------------+-----------+-----------------+-------------------------+ +| getuid | 2 | Process Mgmt. | sys_getuid() | ++-------------------+-----------+-----------------+-------------------------+ +| uname | 1 | Process Mgmt. | sys_uname() | ++-------------------+-----------+-----------------+-------------------------+ +| setpgid | 1 | Process Mgmt. | sys_setpgid() | ++-------------------+-----------+-----------------+-------------------------+ +| getrusage | 1 | Process Mgmt. | sys_getrusage() | ++-------------------+-----------+-----------------+-------------------------+ +| geteuid | 1 | Process Mgmt. | sys_geteuid() | ++-------------------+-----------+-----------------+-------------------------+ +| getppid | 1 | Process Mgmt. | sys_getppid() | ++-------------------+-----------+-----------------+-------------------------+ +| sendto | 3 | Network | sys_sendto() | ++-------------------+-----------+-----------------+-------------------------+ +| connect | 1 | Network | sys_connect() | ++-------------------+-----------+-----------------+-------------------------+ +| socket | 1 | Network | sys_socket() | ++-------------------+-----------+-----------------+-------------------------+ +| clone | 1 | Process Mgmt. | sys_clone() | ++-------------------+-----------+-----------------+-------------------------+ +| set_tid_address | 1 | Process Mgmt. | sys_set_tid_address() | ++-------------------+-----------+-----------------+-------------------------+ +| wait4 | 2 | Time | sys_wait4() | ++-------------------+-----------+-----------------+-------------------------+ +| alarm | 1 | Time | sys_alarm() | ++-------------------+-----------+-----------------+-------------------------+ +| set_robust_list | 1 | Futex | sys_set_robust_list() | ++-------------------+-----------+-----------------+-------------------------+ + +Tracing paxtest kiddie workload +------------------------------- + +Run the following command to trace paxtest kiddie workload:: + + strace -c paxtest kiddie + +**System Calls made by the workload** + +The below table shows the system calls invoked by the workload, number of +times each system call is invoked, and the corresponding Linux subsystem. + ++-------------------+-----------+-----------------+----------------------+ +| System Call | # calls | Linux Subsystem | System Call (API) | ++===================+===========+=================+======================+ +| read | 3 | Filesystem | sys_read() | ++-------------------+-----------+-----------------+----------------------+ +| write | 11 | Filesystem | sys_write() | ++-------------------+-----------+-----------------+----------------------+ +| close | 41 | Filesystem | sys_close() | ++-------------------+-----------+-----------------+----------------------+ +| stat | 24 | Filesystem | sys_stat() | ++-------------------+-----------+-----------------+----------------------+ +| fstat | 2 | Filesystem | sys_fstat() | ++-------------------+-----------+-----------------+----------------------+ +| pread64 | 6 | Filesystem | sys_pread64() | ++-------------------+-----------+-----------------+----------------------+ +| access | 1 | Filesystem | sys_access() | ++-------------------+-----------+-----------------+----------------------+ +| pipe | 1 | Filesystem | sys_pipe() | ++-------------------+-----------+-----------------+----------------------+ +| dup2 | 24 | Filesystem | sys_dup2() | ++-------------------+-----------+-----------------+----------------------+ +| execve | 1 | Filesystem | sys_execve() | ++-------------------+-----------+-----------------+----------------------+ +| fcntl | 26 | Filesystem | sys_fcntl() | ++-------------------+-----------+-----------------+----------------------+ +| openat | 14 | Filesystem | sys_openat() | ++-------------------+-----------+-----------------+----------------------+ +| rt_sigaction | 7 | Signal | sys_rt_sigaction() | ++-------------------+-----------+-----------------+----------------------+ +| rt_sigreturn | 38 | Signal | sys_rt_sigreturn() | ++-------------------+-----------+-----------------+----------------------+ +| clone | 38 | Process Mgmt. | sys_clone() | ++-------------------+-----------+-----------------+----------------------+ +| wait4 | 44 | Time | sys_wait4() | ++-------------------+-----------+-----------------+----------------------+ +| mmap | 7 | Memory Mgmt. | sys_mmap() | ++-------------------+-----------+-----------------+----------------------+ +| mprotect | 3 | Memory Mgmt. | sys_mprotect() | ++-------------------+-----------+-----------------+----------------------+ +| munmap | 1 | Memory Mgmt. | sys_munmap() | ++-------------------+-----------+-----------------+----------------------+ +| brk | 3 | Memory Mgmt. | sys_brk() | ++-------------------+-----------+-----------------+----------------------+ +| getpid | 1 | Process Mgmt. | sys_getpid() | ++-------------------+-----------+-----------------+----------------------+ +| getuid | 1 | Process Mgmt. | sys_getuid() | ++-------------------+-----------+-----------------+----------------------+ +| getgid | 1 | Process Mgmt. | sys_getgid() | ++-------------------+-----------+-----------------+----------------------+ +| geteuid | 2 | Process Mgmt. | sys_geteuid() | ++-------------------+-----------+-----------------+----------------------+ +| getegid | 1 | Process Mgmt. | sys_getegid() | ++-------------------+-----------+-----------------+----------------------+ +| getppid | 1 | Process Mgmt. | sys_getppid() | ++-------------------+-----------+-----------------+----------------------+ +| arch_prctl | 2 | Process Mgmt. | sys_arch_prctl() | ++-------------------+-----------+-----------------+----------------------+ + +Conclusion +========== + +This document is intended to be used as a guide on how to gather fine-grained +information on the resources in use by workloads using strace. + +References +========== + + * `Discovery Linux Kernel Subsystems used by OpenAPS <https://elisa.tech/blog/2022/02/02/discovery-linux-kernel-subsystems-used-by-openaps>`_ + * `ELISA-White-Papers-Discovering Linux kernel subsystems used by a workload <https://github.com/elisa-tech/ELISA-White-Papers/blob/master/Processes/Discovering_Linux_kernel_subsystems_used_by_a_workload.md>`_ + * `strace <https://man7.org/linux/man-pages/man1/strace.1.html>`_ + * `perf <https://man7.org/linux/man-pages/man1/perf.1.html>`_ + * `paxtest README <https://github.com/opntr/paxtest-freebsd/blob/hardenedbsd/0.9.14-hbsd/README>`_ + * `stress-ng <https://www.mankier.com/1/stress-ng>`_ + * `Monitoring and managing system status and performance <https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/monitoring_and_managing_system_status_and_performance/index>`_ diff --git a/Documentation/admin-guide/xfs.rst b/Documentation/admin-guide/xfs.rst index 8de008c0c5ad..e2561416391c 100644 --- a/Documentation/admin-guide/xfs.rst +++ b/Documentation/admin-guide/xfs.rst @@ -296,7 +296,7 @@ The following sysctls are available for the XFS filesystem: XFS_ERRLEVEL_LOW: 1 XFS_ERRLEVEL_HIGH: 5 - fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256) + fs.xfs.panic_mask (Min: 0 Default: 0 Max: 511) Causes certain error conditions to call BUG(). Value is a bitmask; OR together the tags which represent errors which should cause panics: diff --git a/Documentation/arm/index.rst b/Documentation/arm/index.rst index 8c636d4a061f..ae42fe886f0d 100644 --- a/Documentation/arm/index.rst +++ b/Documentation/arm/index.rst @@ -64,7 +64,6 @@ SoC-specific documents sunxi samsung/index - samsung-s3c24xx/index sunxi/clocks diff --git a/Documentation/arm/samsung-s3c24xx/cpufreq.rst b/Documentation/arm/samsung-s3c24xx/cpufreq.rst deleted file mode 100644 index cd22697cf606..000000000000 --- a/Documentation/arm/samsung-s3c24xx/cpufreq.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0-only - -======================= -S3C24XX CPUfreq support -======================= - -Introduction ------------- - - The S3C24XX series support a number of power saving systems, such as - the ability to change the core, memory and peripheral operating - frequencies. The core control is exported via the CPUFreq driver - which has a number of different manual or automatic controls over the - rate the core is running at. - - There are two forms of the driver depending on the specific CPU and - how the clocks are arranged. The first implementation used as single - PLL to feed the ARM, memory and peripherals via a series of dividers - and muxes and this is the implementation that is documented here. A - newer version where there is a separate PLL and clock divider for the - ARM core is available as a separate driver. - - -Layout ------- - - The code core manages the CPU specific drivers, any data that they - need to register and the interface to the generic drivers/cpufreq - system. Each CPU registers a driver to control the PLL, clock dividers - and anything else associated with it. Any board that wants to use this - framework needs to supply at least basic details of what is required. - - The core registers with drivers/cpufreq at init time if all the data - necessary has been supplied. - - -CPU support ------------ - - The support for each CPU depends on the facilities provided by the - SoC and the driver as each device has different PLL and clock chains - associated with it. - - -Slow Mode ---------- - - The SLOW mode where the PLL is turned off altogether and the - system is fed by the external crystal input is currently not - supported. - - -sysfs ------ - - The core code exports extra information via sysfs in the directory - devices/system/cpu/cpu0/arch-freq. - - -Board Support -------------- - - Each board that wants to use the cpufreq code must register some basic - information with the core driver to provide information about what the - board requires and any restrictions being placed on it. - - The board needs to supply information about whether it needs the IO bank - timings changing, any maximum frequency limits and information about the - SDRAM refresh rate. - - - - -Document Author ---------------- - -Ben Dooks, Copyright 2009 Simtec Electronics diff --git a/Documentation/arm/samsung-s3c24xx/eb2410itx.rst b/Documentation/arm/samsung-s3c24xx/eb2410itx.rst deleted file mode 100644 index 7863c93652f8..000000000000 --- a/Documentation/arm/samsung-s3c24xx/eb2410itx.rst +++ /dev/null @@ -1,59 +0,0 @@ -=================================== -Simtec Electronics EB2410ITX (BAST) -=================================== - - http://www.simtec.co.uk/products/EB2410ITX/ - -Introduction ------------- - - The EB2410ITX is a S3C2410 based development board with a variety of - peripherals and expansion connectors. This board is also known by - the shortened name of Bast. - - -Configuration -------------- - - To set the default configuration, use `make bast_defconfig` which - supports the commonly used features of this board. - - -Support -------- - - Official support information can be found on the Simtec Electronics - website, at the product page http://www.simtec.co.uk/products/EB2410ITX/ - - Useful links: - - - Resources Page http://www.simtec.co.uk/products/EB2410ITX/resources.html - - - Board FAQ at http://www.simtec.co.uk/products/EB2410ITX/faq.html - - - Bootloader info http://www.simtec.co.uk/products/SWABLE/resources.html - and FAQ http://www.simtec.co.uk/products/SWABLE/faq.html - - -MTD ---- - - The NAND and NOR support has been merged from the linux-mtd project. - Any problems, see http://www.linux-mtd.infradead.org/ for more - information or up-to-date versions of linux-mtd. - - -IDE ---- - - Both onboard IDE ports are supported, however there is no support for - changing speed of devices, PIO Mode 4 capable drives should be used. - - -Maintainers ------------ - - This board is maintained by Simtec Electronics. - - -Copyright 2004 Ben Dooks, Simtec Electronics diff --git a/Documentation/arm/samsung-s3c24xx/gpio.rst b/Documentation/arm/samsung-s3c24xx/gpio.rst deleted file mode 100644 index f4a8c800a457..000000000000 --- a/Documentation/arm/samsung-s3c24xx/gpio.rst +++ /dev/null @@ -1,172 +0,0 @@ -==================== -S3C24XX GPIO Control -==================== - -Introduction ------------- - - The s3c2410 kernel provides an interface to configure and - manipulate the state of the GPIO pins, and find out other - information about them. - - There are a number of conditions attached to the configuration - of the s3c2410 GPIO system, please read the Samsung provided - data-sheet/users manual to find out the complete list. - - See Documentation/arm/samsung/gpio.rst for the core implementation. - - -GPIOLIB -------- - - With the event of the GPIOLIB in drivers/gpio, support for some - of the GPIO functions such as reading and writing a pin will - be removed in favour of this common access method. - - Once all the extant drivers have been converted, the functions - listed below will be removed (they may be marked as __deprecated - in the near future). - - The following functions now either have a `s3c_` specific variant - or are merged into gpiolib. See the definitions in - arch/arm/mach-s3c/gpio-cfg.h: - - - s3c2410_gpio_setpin() gpio_set_value() or gpio_direction_output() - - s3c2410_gpio_getpin() gpio_get_value() or gpio_direction_input() - - s3c2410_gpio_getirq() gpio_to_irq() - - s3c2410_gpio_cfgpin() s3c_gpio_cfgpin() - - s3c2410_gpio_getcfg() s3c_gpio_getcfg() - - s3c2410_gpio_pullup() s3c_gpio_setpull() - - -GPIOLIB conversion ------------------- - -If you need to convert your board or driver to use gpiolib from the phased -out s3c2410 API, then here are some notes on the process. - -1) If your board is exclusively using an GPIO, say to control peripheral - power, then it will require to claim the gpio with gpio_request() before - it can use it. - - It is recommended to check the return value, with at least WARN_ON() - during initialisation. - -2) The s3c2410_gpio_cfgpin() can be directly replaced with s3c_gpio_cfgpin() - as they have the same arguments, and can either take the pin specific - values, or the more generic special-function-number arguments. - -3) s3c2410_gpio_pullup() changes have the problem that while the - s3c2410_gpio_pullup(x, 1) can be easily translated to the - s3c_gpio_setpull(x, S3C_GPIO_PULL_NONE), the s3c2410_gpio_pullup(x, 0) - are not so easy. - - The s3c2410_gpio_pullup(x, 0) case enables the pull-up (or in the case - of some of the devices, a pull-down) and as such the new API distinguishes - between the UP and DOWN case. There is currently no 'just turn on' setting - which may be required if this becomes a problem. - -4) s3c2410_gpio_setpin() can be replaced by gpio_set_value(), the old call - does not implicitly configure the relevant gpio to output. The gpio - direction should be changed before using gpio_set_value(). - -5) s3c2410_gpio_getpin() is replaceable by gpio_get_value() if the pin - has been set to input. It is currently unknown what the behaviour is - when using gpio_get_value() on an output pin (s3c2410_gpio_getpin - would return the value the pin is supposed to be outputting). - -6) s3c2410_gpio_getirq() should be directly replaceable with the - gpio_to_irq() call. - -The s3c2410_gpio and `gpio_` calls have always operated on the same gpio -numberspace, so there is no problem with converting the gpio numbering -between the calls. - - -Headers -------- - - See arch/arm/mach-s3c/regs-gpio-s3c24xx.h for the list - of GPIO pins, and the configuration values for them. This - is included by using #include <mach/regs-gpio.h> - - -PIN Numbers ------------ - - Each pin has an unique number associated with it in regs-gpio.h, - e.g. S3C2410_GPA(0) or S3C2410_GPF(1). These defines are used to tell - the GPIO functions which pin is to be used. - - With the conversion to gpiolib, there is no longer a direct conversion - from gpio pin number to register base address as in earlier kernels. This - is due to the number space required for newer SoCs where the later - GPIOs are not contiguous. - - -Configuring a pin ------------------ - - The following function allows the configuration of a given pin to - be changed. - - void s3c_gpio_cfgpin(unsigned int pin, unsigned int function); - - e.g.: - - s3c_gpio_cfgpin(S3C2410_GPA(0), S3C_GPIO_SFN(1)); - s3c_gpio_cfgpin(S3C2410_GPE(8), S3C_GPIO_SFN(2)); - - which would turn GPA(0) into the lowest Address line A0, and set - GPE(8) to be connected to the SDIO/MMC controller's SDDAT1 line. - - -Reading the current configuration ---------------------------------- - - The current configuration of a pin can be read by using standard - gpiolib function: - - s3c_gpio_getcfg(unsigned int pin); - - The return value will be from the same set of values which can be - passed to s3c_gpio_cfgpin(). - - -Configuring a pull-up resistor ------------------------------- - - A large proportion of the GPIO pins on the S3C2410 can have weak - pull-up resistors enabled. This can be configured by the following - function: - - void s3c_gpio_setpull(unsigned int pin, unsigned int to); - - Where the to value is S3C_GPIO_PULL_NONE to set the pull-up off, - and S3C_GPIO_PULL_UP to enable the specified pull-up. Any other - values are currently undefined. - - -Getting and setting the state of a PIN --------------------------------------- - - These calls are now implemented by the relevant gpiolib calls, convert - your board or driver to use gpiolib. - - -Getting the IRQ number associated with a PIN --------------------------------------------- - - A standard gpiolib function can map the given pin number to an IRQ - number to pass to the IRQ system. - - int gpio_to_irq(unsigned int pin); - - Note, not all pins have an IRQ. - - -Author -------- - -Ben Dooks, 03 October 2004 -Copyright 2004 Ben Dooks, Simtec Electronics diff --git a/Documentation/arm/samsung-s3c24xx/h1940.rst b/Documentation/arm/samsung-s3c24xx/h1940.rst deleted file mode 100644 index 62a562c178e3..000000000000 --- a/Documentation/arm/samsung-s3c24xx/h1940.rst +++ /dev/null @@ -1,41 +0,0 @@ -============= -HP IPAQ H1940 -============= - -http://www.handhelds.org/projects/h1940.html - -Introduction ------------- - - The HP H1940 is a S3C2410 based handheld device, with - bluetooth connectivity. - - -Support -------- - - A variety of information is available - - handhelds.org project page: - - http://www.handhelds.org/projects/h1940.html - - handhelds.org wiki page: - - http://handhelds.org/moin/moin.cgi/HpIpaqH1940 - - Herbert Pötzl pages: - - http://vserver.13thfloor.at/H1940/ - - -Maintainers ------------ - - This project is being maintained and developed by a variety - of people, including Ben Dooks, Arnaud Patard, and Herbert Pötzl. - - Thanks to the many others who have also provided support. - - -(c) 2005 Ben Dooks diff --git a/Documentation/arm/samsung-s3c24xx/index.rst b/Documentation/arm/samsung-s3c24xx/index.rst deleted file mode 100644 index ccb951a0bedb..000000000000 --- a/Documentation/arm/samsung-s3c24xx/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -========================== -Samsung S3C24XX SoC Family -========================== - -.. toctree:: - :maxdepth: 1 - - h1940 - gpio - cpufreq - suspend - usb-host - s3c2412 - eb2410itx - nand - smdk2440 - s3c2413 - overview diff --git a/Documentation/arm/samsung-s3c24xx/nand.rst b/Documentation/arm/samsung-s3c24xx/nand.rst deleted file mode 100644 index 938995694ee7..000000000000 --- a/Documentation/arm/samsung-s3c24xx/nand.rst +++ /dev/null @@ -1,30 +0,0 @@ -==================== -S3C24XX NAND Support -==================== - -Introduction ------------- - -Small Page NAND ---------------- - -The driver uses a 512 byte (1 page) ECC code for this setup. The -ECC code is not directly compatible with the default kernel ECC -code, so the driver enforces its own OOB layout and ECC parameters - -Large Page NAND ---------------- - -The driver is capable of handling NAND flash with a 2KiB page -size, with support for hardware ECC generation and correction. - -Unlike the 512byte page mode, the driver generates ECC data for -each 256 byte block in an 2KiB page. This means that more than -one error in a page can be rectified. It also means that the -OOB layout remains the default kernel layout for these flashes. - - -Document Author ---------------- - -Ben Dooks, Copyright 2007 Simtec Electronics diff --git a/Documentation/arm/samsung-s3c24xx/overview.rst b/Documentation/arm/samsung-s3c24xx/overview.rst deleted file mode 100644 index 14535e5cffb7..000000000000 --- a/Documentation/arm/samsung-s3c24xx/overview.rst +++ /dev/null @@ -1,311 +0,0 @@ -========================== -S3C24XX ARM Linux Overview -========================== - - - -Introduction ------------- - - The Samsung S3C24XX range of ARM9 System-on-Chip CPUs are supported - by the 's3c2410' architecture of ARM Linux. Currently the S3C2410, - S3C2412, S3C2413, S3C2416, S3C2440, S3C2442, S3C2443 and S3C2450 devices - are supported. - - Support for the S3C2400 and S3C24A0 series was never completed and the - corresponding code has been removed after a while. If someone wishes to - revive this effort, partial support can be retrieved from earlier Linux - versions. - - The S3C2416 and S3C2450 devices are very similar and S3C2450 support is - included under the arch/arm/mach-s3c directory. Note, while core - support for these SoCs is in, work on some of the extra peripherals - and extra interrupts is still ongoing. - - -Configuration -------------- - - A generic S3C2410 configuration is provided, and can be used as the - default by `make s3c2410_defconfig`. This configuration has support - for all the machines, and the commonly used features on them. - - Certain machines may have their own default configurations as well, - please check the machine specific documentation. - - -Layout ------- - - The core support files, register, kernel and paltform data are located in the - platform code contained in arch/arm/mach-s3c with headers in - arch/arm/mach-s3c/include - -arch/arm/mach-s3c: - - Files in here are either common to all the s3c24xx family, - or are common to only some of them with names to indicate this - status. The files that are not common to all are generally named - with the initial cpu they support in the series to ensure a short - name without any possibility of confusion with newer devices. - - As an example, initially s3c244x would cover s3c2440 and s3c2442, but - with the s3c2443 which does not share many of the same drivers in - this directory, the name becomes invalid. We stick to s3c2440-<x> - to indicate a driver that is s3c2440 and s3c2442 compatible. - - This does mean that to find the status of any given SoC, a number - of directories may need to be searched. - - -Machines --------- - - The currently supported machines are as follows: - - Simtec Electronics EB2410ITX (BAST) - - A general purpose development board, see EB2410ITX.txt for further - details - - Simtec Electronics IM2440D20 (Osiris) - - CPU Module from Simtec Electronics, with a S3C2440A CPU, nand flash - and a PCMCIA controller. - - Samsung SMDK2410 - - Samsung's own development board, geared for PDA work. - - Samsung/Aiji SMDK2412 - - The S3C2412 version of the SMDK2440. - - Samsung/Aiji SMDK2413 - - The S3C2412 version of the SMDK2440. - - Samsung/Meritech SMDK2440 - - The S3C2440 compatible version of the SMDK2440, which has the - option of an S3C2440 or S3C2442 CPU module. - - Thorcom VR1000 - - Custom embedded board - - HP IPAQ 1940 - - Handheld (IPAQ), available in several varieties - - HP iPAQ rx3715 - - S3C2440 based IPAQ, with a number of variations depending on - features shipped. - - Acer N30 - - A S3C2410 based PDA from Acer. There is a Wiki page at - http://handhelds.org/moin/moin.cgi/AcerN30Documentation . - - AML M5900 - - American Microsystems' M5900 - - Nex Vision Nexcoder - Nex Vision Otom - - Two machines by Nex Vision - - -Adding New Machines -------------------- - - The architecture has been designed to support as many machines as can - be configured for it in one kernel build, and any future additions - should keep this in mind before altering items outside of their own - machine files. - - Machine definitions should be kept in arch/arm/mach-s3c, - and there are a number of examples that can be looked at. - - Read the kernel patch submission policies as well as the - Documentation/arm directory before submitting patches. The - ARM kernel series is managed by Russell King, and has a patch system - located at http://www.arm.linux.org.uk/developer/patches/ - as well as mailing lists that can be found from the same site. - - As a courtesy, please notify <ben-linux@fluff.org> of any new - machines or other modifications. - - Any large scale modifications, or new drivers should be discussed - on the ARM kernel mailing list (linux-arm-kernel) before being - attempted. See http://www.arm.linux.org.uk/mailinglists/ for the - mailing list information. - - -I2C ---- - - The hardware I2C core in the CPU is supported in single master - mode, and can be configured via platform data. - - -RTC ---- - - Support for the onboard RTC unit, including alarm function. - - This has recently been upgraded to use the new RTC core, - and the module has been renamed to rtc-s3c to fit in with - the new rtc naming scheme. - - -Watchdog --------- - - The onchip watchdog is available via the standard watchdog - interface. - - -NAND ----- - - The current kernels now have support for the s3c2410 NAND - controller. If there are any problems the latest linux-mtd - code can be found from http://www.linux-mtd.infradead.org/ - - For more information see Documentation/arm/samsung-s3c24xx/nand.rst - - -SD/MMC ------- - - The SD/MMC hardware pre S3C2443 is supported in the current - kernel, the driver is drivers/mmc/host/s3cmci.c and supports - 1 and 4 bit SD or MMC cards. - - The SDIO behaviour of this driver has not been fully tested. There is no - current support for hardware SDIO interrupts. - - -Serial ------- - - The s3c2410 serial driver provides support for the internal - serial ports. These devices appear as /dev/ttySAC0 through 3. - - To create device nodes for these, use the following commands - - mknod ttySAC0 c 204 64 - mknod ttySAC1 c 204 65 - mknod ttySAC2 c 204 66 - - -GPIO ----- - - The core contains support for manipulating the GPIO, see the - documentation in GPIO.txt in the same directory as this file. - - Newer kernels carry GPIOLIB, and support is being moved towards - this with some of the older support in line to be removed. - - As of v2.6.34, the move towards using gpiolib support is almost - complete, and very little of the old calls are left. - - See Documentation/arm/samsung-s3c24xx/gpio.rst for the S3C24XX specific - support and Documentation/arm/samsung/gpio.rst for the core Samsung - implementation. - - -Clock Management ----------------- - - The core provides the interface defined in the header file - include/asm-arm/hardware/clock.h, to allow control over the - various clock units - - -Suspend to RAM --------------- - - For boards that provide support for suspend to RAM, the - system can be placed into low power suspend. - - See Suspend.txt for more information. - - -SPI ---- - - SPI drivers are available for both the in-built hardware - (although there is no DMA support yet) and a generic - GPIO based solution. - - -LEDs ----- - - There is support for GPIO based LEDs via a platform driver - in the LED subsystem. - - -Platform Data -------------- - - Whenever a device has platform specific data that is specified - on a per-machine basis, care should be taken to ensure the - following: - - 1) that default data is not left in the device to confuse the - driver if a machine does not set it at startup - - 2) the data should (if possible) be marked as __initdata, - to ensure that the data is thrown away if the machine is - not the one currently in use. - - The best way of doing this is to make a function that - kmalloc()s an area of memory, and copies the __initdata - and then sets the relevant device's platform data. Making - the function `__init` takes care of ensuring it is discarded - with the rest of the initialisation code:: - - static __init void s3c24xx_xxx_set_platdata(struct xxx_data *pd) - { - struct s3c2410_xxx_mach_info *npd; - - npd = kmalloc(sizeof(struct s3c2410_xxx_mach_info), GFP_KERNEL); - if (npd) { - memcpy(npd, pd, sizeof(struct s3c2410_xxx_mach_info)); - s3c_device_xxx.dev.platform_data = npd; - } else { - printk(KERN_ERR "no memory for xxx platform data\n"); - } - } - - Note, since the code is marked as __init, it should not be - exported outside arch/arm/mach-s3c/, or exported to - modules via EXPORT_SYMBOL() and related functions. - - -Port Contributors ------------------ - - Ben Dooks (BJD) - Vincent Sanders - Herbert Potzl - Arnaud Patard (RTP) - Roc Wu - Klaus Fetscher - Dimitry Andric - Shannon Holland - Guillaume Gourat (NexVision) - Christer Weinigel (wingel) (Acer N30) - Lucas Correia Villa Real (S3C2400 port) - - -Document Author ---------------- - -Ben Dooks, Copyright 2004-2006 Simtec Electronics diff --git a/Documentation/arm/samsung-s3c24xx/s3c2412.rst b/Documentation/arm/samsung-s3c24xx/s3c2412.rst deleted file mode 100644 index 68b985fc6bf4..000000000000 --- a/Documentation/arm/samsung-s3c24xx/s3c2412.rst +++ /dev/null @@ -1,121 +0,0 @@ -========================== -S3C2412 ARM Linux Overview -========================== - -Introduction ------------- - - The S3C2412 is part of the S3C24XX range of ARM9 System-on-Chip CPUs - from Samsung. This part has an ARM926-EJS core, capable of running up - to 266MHz (see data-sheet for more information) - - -Clock ------ - - The core clock code provides a set of clocks to the drivers, and allows - for source selection and a number of other features. - - -Power ------ - - No support for suspend/resume to RAM in the current system. - - -DMA ---- - - No current support for DMA. - - -GPIO ----- - - There is support for setting the GPIO to input/output/special function - and reading or writing to them. - - -UART ----- - - The UART hardware is similar to the S3C2440, and is supported by the - s3c2410 driver in the drivers/serial directory. - - -NAND ----- - - The NAND hardware is similar to the S3C2440, and is supported by the - s3c2410 driver in the drivers/mtd/nand/raw directory. - - -USB Host --------- - - The USB hardware is similar to the S3C2410, with extended clock source - control. The OHCI portion is supported by the ohci-s3c2410 driver, and - the clock control selection is supported by the core clock code. - - -USB Device ----------- - - No current support in the kernel - - -IRQs ----- - - All the standard, and external interrupt sources are supported. The - extra sub-sources are not yet supported. - - -RTC ---- - - The RTC hardware is similar to the S3C2410, and is supported by the - s3c2410-rtc driver. - - -Watchdog --------- - - The watchdog hardware is the same as the S3C2410, and is supported by - the s3c2410_wdt driver. - - -MMC/SD/SDIO ------------ - - No current support for the MMC/SD/SDIO block. - -IIC ---- - - The IIC hardware is the same as the S3C2410, and is supported by the - i2c-s3c24xx driver. - - -IIS ---- - - No current support for the IIS interface. - - -SPI ---- - - No current support for the SPI interfaces. - - -ATA ---- - - No current support for the on-board ATA block. - - -Document Author ---------------- - -Ben Dooks, Copyright 2006 Simtec Electronics diff --git a/Documentation/arm/samsung-s3c24xx/s3c2413.rst b/Documentation/arm/samsung-s3c24xx/s3c2413.rst deleted file mode 100644 index 1f51e207fc46..000000000000 --- a/Documentation/arm/samsung-s3c24xx/s3c2413.rst +++ /dev/null @@ -1,22 +0,0 @@ -========================== -S3C2413 ARM Linux Overview -========================== - -Introduction ------------- - - The S3C2413 is an extended version of the S3C2412, with an camera - interface and mobile DDR memory support. See the S3C2412 support - documentation for more information. - - -Camera Interface ----------------- - - This block is currently not supported. - - -Document Author ---------------- - -Ben Dooks, Copyright 2006 Simtec Electronics diff --git a/Documentation/arm/samsung-s3c24xx/smdk2440.rst b/Documentation/arm/samsung-s3c24xx/smdk2440.rst deleted file mode 100644 index 524fd0b4afaf..000000000000 --- a/Documentation/arm/samsung-s3c24xx/smdk2440.rst +++ /dev/null @@ -1,57 +0,0 @@ -========================= -Samsung/Meritech SMDK2440 -========================= - -Introduction ------------- - - The SMDK2440 is a two part evaluation board for the Samsung S3C2440 - processor. It includes support for LCD, SmartMedia, Audio, SD and - 10MBit Ethernet, and expansion headers for various signals, including - the camera and unused GPIO. - - -Configuration -------------- - - To set the default configuration, use `make smdk2440_defconfig` which - will configure the common features of this board, or use - `make s3c2410_config` to include support for all s3c2410/s3c2440 machines - - -Support -------- - - Ben Dooks' SMDK2440 site at http://www.fluff.org/ben/smdk2440/ which - includes linux based USB download tools. - - Some of the h1940 patches that can be found from the H1940 project - site at http://www.handhelds.org/projects/h1940.html can also be - applied to this board. - - -Peripherals ------------ - - There is no current support for any of the extra peripherals on the - base-board itself. - - -MTD ---- - - The NAND flash should be supported by the in kernel MTD NAND support, - NOR flash will be added later. - - -Maintainers ------------ - - This board is being maintained by Ben Dooks, for more info, see - http://www.fluff.org/ben/smdk2440/ - - Many thanks to Dimitry Andric of TomTom for the loan of the SMDK2440, - and to Simtec Electronics for allowing me time to work on this. - - -(c) 2004 Ben Dooks diff --git a/Documentation/arm/samsung-s3c24xx/suspend.rst b/Documentation/arm/samsung-s3c24xx/suspend.rst deleted file mode 100644 index b4f3ae9fe76e..000000000000 --- a/Documentation/arm/samsung-s3c24xx/suspend.rst +++ /dev/null @@ -1,137 +0,0 @@ -======================= -S3C24XX Suspend Support -======================= - - -Introduction ------------- - - The S3C24XX supports a low-power suspend mode, where the SDRAM is kept - in Self-Refresh mode, and all but the essential peripheral blocks are - powered down. For more information on how this works, please look - at the relevant CPU datasheet from Samsung. - - -Requirements ------------- - - 1) A bootloader that can support the necessary resume operation - - 2) Support for at least 1 source for resume - - 3) CONFIG_PM enabled in the kernel - - 4) Any peripherals that are going to be powered down at the same - time require suspend/resume support. - - -Resuming --------- - - The S3C2410 user manual defines the process of sending the CPU to - sleep and how it resumes. The default behaviour of the Linux code - is to set the GSTATUS3 register to the physical address of the - code to resume Linux operation. - - GSTATUS4 is currently left alone by the sleep code, and is free to - use for any other purposes (for example, the EB2410ITX uses this to - save memory configuration in). - - -Machine Support ---------------- - - The machine specific functions must call the s3c_pm_init() function - to say that its bootloader is capable of resuming. This can be as - simple as adding the following to the machine's definition: - - INITMACHINE(s3c_pm_init) - - A board can do its own setup before calling s3c_pm_init, if it - needs to setup anything else for power management support. - - There is currently no support for over-riding the default method of - saving the resume address, if your board requires it, then contact - the maintainer and discuss what is required. - - Note, the original method of adding an late_initcall() is wrong, - and will end up initialising all compiled machines' pm init! - - The following is an example of code used for testing wakeup from - an falling edge on IRQ_EINT0:: - - - static irqreturn_t button_irq(int irq, void *pw) - { - return IRQ_HANDLED; - } - - statuc void __init machine_init(void) - { - ... - - request_irq(IRQ_EINT0, button_irq, IRQF_TRIGGER_FALLING, - "button-irq-eint0", NULL); - - enable_irq_wake(IRQ_EINT0); - - s3c_pm_init(); - } - - -Debugging ---------- - - There are several important things to remember when using PM suspend: - - 1) The uart drivers will disable the clocks to the UART blocks when - suspending, which means that use of printascii() or similar direct - access to the UARTs will cause the debug to stop. - - 2) While the pm code itself will attempt to re-enable the UART clocks, - care should be taken that any external clock sources that the UARTs - rely on are still enabled at that point. - - 3) If any debugging is placed in the resume path, then it must have the - relevant clocks and peripherals setup before use (ie, bootloader). - - For example, if you transmit a character from the UART, the baud - rate and uart controls must be setup beforehand. - - -Configuration -------------- - - The S3C2410 specific configuration in `System Type` defines various - aspects of how the S3C2410 suspend and resume support is configured - - `S3C2410 PM Suspend debug` - - This option prints messages to the serial console before and after - the actual suspend, giving detailed information on what is - happening - - - `S3C2410 PM Suspend Memory CRC` - - Allows the entire memory to be checksummed before and after the - suspend to see if there has been any corruption of the contents. - - Note, the time to calculate the CRC is dependent on the CPU speed - and the size of memory. For an 64Mbyte RAM area on an 200MHz - S3C2410, this can take approximately 4 seconds to complete. - - This support requires the CRC32 function to be enabled. - - - `S3C2410 PM Suspend CRC Chunksize (KiB)` - - Defines the size of memory each CRC chunk covers. A smaller value - will mean that the CRC data block will take more memory, but will - identify any faults with better precision - - -Document Author ---------------- - -Ben Dooks, Copyright 2004 Simtec Electronics diff --git a/Documentation/arm/samsung-s3c24xx/usb-host.rst b/Documentation/arm/samsung-s3c24xx/usb-host.rst deleted file mode 100644 index 7aaffac89e04..000000000000 --- a/Documentation/arm/samsung-s3c24xx/usb-host.rst +++ /dev/null @@ -1,91 +0,0 @@ -======================== -S3C24XX USB Host support -======================== - - - -Introduction ------------- - - This document details the S3C2410/S3C2440 in-built OHCI USB host support. - -Configuration -------------- - - Enable at least the following kernel options: - - menuconfig:: - - Device Drivers ---> - USB support ---> - <*> Support for Host-side USB - <*> OHCI HCD support - - - .config: - - - CONFIG_USB - - CONFIG_USB_OHCI_HCD - - - Once these options are configured, the standard set of USB device - drivers can be configured and used. - - -Board Support -------------- - - The driver attaches to a platform device, which will need to be - added by the board specific support file in arch/arm/mach-s3c, - such as mach-bast.c or mach-smdk2410.c - - The platform device's platform_data field is only needed if the - board implements extra power control or over-current monitoring. - - The OHCI driver does not ensure the state of the S3C2410's MISCCTRL - register, so if both ports are to be used for the host, then it is - the board support file's responsibility to ensure that the second - port is configured to be connected to the OHCI core. - - -Platform Data -------------- - - See include/linux/platform_data/usb-ohci-s3c2410.h for the - descriptions of the platform device data. An implementation - can be found in arch/arm/mach-s3c/simtec-usb.c . - - The `struct s3c2410_hcd_info` contains a pair of functions - that get called to enable over-current detection, and to - control the port power status. - - The ports are numbered 0 and 1. - - power_control: - Called to enable or disable the power on the port. - - enable_oc: - Called to enable or disable the over-current monitoring. - This should claim or release the resources being used to - check the power condition on the port, such as an IRQ. - - report_oc: - The OHCI driver fills this field in for the over-current code - to call when there is a change to the over-current state on - an port. The ports argument is a bitmask of 1 bit per port, - with bit X being 1 for an over-current on port X. - - The function s3c2410_usb_report_oc() has been provided to - ensure this is called correctly. - - port[x]: - This is struct describes each port, 0 or 1. The platform driver - should set the flags field of each port to S3C_HCDFLG_USED if - the port is enabled. - - - -Document Author ---------------- - -Ben Dooks, Copyright 2005 Simtec Electronics diff --git a/Documentation/arm/samsung/gpio.rst b/Documentation/arm/samsung/gpio.rst index f6e27b07c993..27fae0d50361 100644 --- a/Documentation/arm/samsung/gpio.rst +++ b/Documentation/arm/samsung/gpio.rst @@ -9,14 +9,6 @@ This outlines the Samsung GPIO implementation and the architecture specific calls provided alongside the drivers/gpio core. -S3C24XX (Legacy) ----------------- - -See Documentation/arm/samsung-s3c24xx/gpio.rst for more information -about these devices. Their implementation has been brought into line -with the core samsung implementation described in this document. - - GPIOLIB integration ------------------- diff --git a/Documentation/arm/samsung/overview.rst b/Documentation/arm/samsung/overview.rst index e74307897416..8b15a190169b 100644 --- a/Documentation/arm/samsung/overview.rst +++ b/Documentation/arm/samsung/overview.rst @@ -12,21 +12,10 @@ Introduction The currently supported SoCs are: - - S3C24XX: See Documentation/arm/samsung-s3c24xx/overview.rst for full list - S3C64XX: S3C6400 and S3C6410 - S5PC110 / S5PV210 -S3C24XX Systems ---------------- - - There is still documentation in Documnetation/arm/Samsung-S3C24XX/ which - deals with the architecture and drivers specific to these devices. - - See Documentation/arm/samsung-s3c24xx/overview.rst for more information - on the implementation details and specific support. - - Configuration ------------- @@ -51,8 +40,6 @@ Layout specific information. It contains the base clock, GPIO and device definitions to get the system running. - plat-s3c24xx is for s3c24xx specific builds, see the S3C24XX docs. - plat-s5p is for s5p specific builds, and contains common support for the S5P specific systems. Not all S5Ps use all the features in this directory due to differences in the hardware. diff --git a/Documentation/arm64/booting.rst b/Documentation/arm64/booting.rst index 96fe10ec6c24..ffeccdd6bdac 100644 --- a/Documentation/arm64/booting.rst +++ b/Documentation/arm64/booting.rst @@ -223,7 +223,7 @@ Before jumping into the kernel, the following conditions must be met: For systems with a GICv3 interrupt controller to be used in v3 mode: - If EL3 is present: - - ICC_SRE_EL3.Enable (bit 3) must be initialiased to 0b1. + - ICC_SRE_EL3.Enable (bit 3) must be initialised to 0b1. - ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b1. - ICC_CTLR_EL3.PMHE (bit 6) must be set to the same value across all CPUs the kernel is executing on, and must stay constant @@ -369,6 +369,16 @@ Before jumping into the kernel, the following conditions must be met: - HCR_EL2.ATA (bit 56) must be initialised to 0b1. + For CPUs with the Scalable Matrix Extension version 2 (FEAT_SME2): + + - If EL3 is present: + + - SMCR_EL3.EZT0 (bit 30) must be initialised to 0b1. + + - If the kernel is entered at EL1 and EL2 is present: + + - SMCR_EL2.EZT0 (bit 30) must be initialised to 0b1. + The requirements described above for CPU mode, caches, MMUs, architected timers, coherency and system registers apply to all CPUs. All CPUs must enter the kernel in the same exception level. Where the values documented diff --git a/Documentation/arm64/elf_hwcaps.rst b/Documentation/arm64/elf_hwcaps.rst index 6fed84f935df..83e57e4d38e2 100644 --- a/Documentation/arm64/elf_hwcaps.rst +++ b/Documentation/arm64/elf_hwcaps.rst @@ -14,7 +14,7 @@ Some hardware or software features are only available on some CPU implementations, and/or with certain kernel configurations, but have no architected discovery mechanism available to userspace code at EL0. The kernel exposes the presence of these features to userspace through a set -of flags called hwcaps, exposed in the auxilliary vector. +of flags called hwcaps, exposed in the auxiliary vector. Userspace software can test for features by acquiring the AT_HWCAP or AT_HWCAP2 entry of the auxiliary vector, and testing whether the relevant @@ -284,6 +284,24 @@ HWCAP2_RPRFM HWCAP2_SVE2P1 Functionality implied by ID_AA64ZFR0_EL1.SVEver == 0b0010. +HWCAP2_SME2 + Functionality implied by ID_AA64SMFR0_EL1.SMEver == 0b0001. + +HWCAP2_SME2P1 + Functionality implied by ID_AA64SMFR0_EL1.SMEver == 0b0010. + +HWCAP2_SMEI16I32 + Functionality implied by ID_AA64SMFR0_EL1.I16I32 == 0b0101 + +HWCAP2_SMEBI32I32 + Functionality implied by ID_AA64SMFR0_EL1.BI32I32 == 0b1 + +HWCAP2_SMEB16B16 + Functionality implied by ID_AA64SMFR0_EL1.B16B16 == 0b1 + +HWCAP2_SMEF16F16 + Functionality implied by ID_AA64SMFR0_EL1.F16F16 == 0b1 + 4. Unused AT_HWCAP bits ----------------------- diff --git a/Documentation/arm64/silicon-errata.rst b/Documentation/arm64/silicon-errata.rst index 808ade4cc008..ec5f889d7681 100644 --- a/Documentation/arm64/silicon-errata.rst +++ b/Documentation/arm64/silicon-errata.rst @@ -120,6 +120,8 @@ stable kernels. +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A710 | #2224489 | ARM64_ERRATUM_2224489 | +----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A715 | #2645198 | ARM64_ERRATUM_2645198 | ++----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-X2 | #2119858 | ARM64_ERRATUM_2119858 | +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-X2 | #2224489 | ARM64_ERRATUM_2224489 | diff --git a/Documentation/arm64/sme.rst b/Documentation/arm64/sme.rst index 16d2db4c2e2e..1c43ea12eb4f 100644 --- a/Documentation/arm64/sme.rst +++ b/Documentation/arm64/sme.rst @@ -18,14 +18,19 @@ model features for SME is included in Appendix A. 1. General ----------- -* PSTATE.SM, PSTATE.ZA, the streaming mode vector length, the ZA - register state and TPIDR2_EL0 are tracked per thread. +* PSTATE.SM, PSTATE.ZA, the streaming mode vector length, the ZA and (when + present) ZTn register state and TPIDR2_EL0 are tracked per thread. * The presence of SME is reported to userspace via HWCAP2_SME in the aux vector AT_HWCAP2 entry. Presence of this flag implies the presence of the SME instructions and registers, and the Linux-specific system interfaces described in this document. SME is reported in /proc/cpuinfo as "sme". +* The presence of SME2 is reported to userspace via HWCAP2_SME2 in the + aux vector AT_HWCAP2 entry. Presence of this flag implies the presence of + the SME2 instructions and ZT0, and the Linux-specific system interfaces + described in this document. SME2 is reported in /proc/cpuinfo as "sme2". + * Support for the execution of SME instructions in userspace can also be detected by reading the CPU ID register ID_AA64PFR1_EL1 using an MRS instruction, and checking that the value of the SME field is nonzero. [3] @@ -44,6 +49,7 @@ model features for SME is included in Appendix A. HWCAP2_SME_B16F32 HWCAP2_SME_F32F32 HWCAP2_SME_FA64 + HWCAP2_SME2 This list may be extended over time as the SME architecture evolves. @@ -52,8 +58,8 @@ model features for SME is included in Appendix A. cpu-feature-registers.txt for details. * Debuggers should restrict themselves to interacting with the target via the - NT_ARM_SVE, NT_ARM_SSVE and NT_ARM_ZA regsets. The recommended way - of detecting support for these regsets is to connect to a target process + NT_ARM_SVE, NT_ARM_SSVE, NT_ARM_ZA and NT_ARM_ZT regsets. The recommended + way of detecting support for these regsets is to connect to a target process first and then attempt a ptrace(PTRACE_GETREGSET, pid, NT_ARM_<regset>, &iov). @@ -89,13 +95,13 @@ be zeroed. ------------------------- * On syscall PSTATE.ZA is preserved, if PSTATE.ZA==1 then the contents of the - ZA matrix are preserved. + ZA matrix and ZTn (if present) are preserved. * On syscall PSTATE.SM will be cleared and the SVE registers will be handled as per the standard SVE ABI. -* Neither the SVE registers nor ZA are used to pass arguments to or receive - results from any syscall. +* None of the SVE registers, ZA or ZTn are used to pass arguments to + or receive results from any syscall. * On process creation (eg, clone()) the newly created process will have PSTATE.SM cleared. @@ -111,6 +117,9 @@ be zeroed. * Signal handlers are invoked with streaming mode and ZA disabled. +* A new signal frame record TPIDR2_MAGIC is added formatted as a struct + tpidr2_context to allow access to TPIDR2_EL0 from signal handlers. + * A new signal frame record za_context encodes the ZA register contents on signal delivery. [1] @@ -134,6 +143,14 @@ be zeroed. __reserved[] referencing this space. za_context is then written in the extra space. Refer to [1] for further details about this mechanism. +* If ZTn is supported and PSTATE.ZA==1 then a signal frame record for ZTn will + be generated. + +* The signal record for ZTn has magic ZT_MAGIC (0x5a544e01) and consists of a + standard signal frame header followed by a struct zt_context specifying + the number of ZTn registers supported by the system, then zt_context.nregs + blocks of 64 bytes of data per register. + 5. Signal return ----------------- @@ -151,6 +168,9 @@ When returning from a signal handler: the signal frame does not match the current vector length, the signal return attempt is treated as illegal, resulting in a forced SIGSEGV. +* If ZTn is not supported or PSTATE.ZA==0 then it is illegal to have a + signal frame record for ZTn, resulting in a forced SIGSEGV. + 6. prctl extensions -------------------- @@ -214,8 +234,8 @@ prctl(PR_SME_SET_VL, unsigned long arg) vector length that will be applied at the next execve() by the calling thread. - * Changing the vector length causes all of ZA, P0..P15, FFR and all bits of - Z0..Z31 except for Z0 bits [127:0] .. Z31 bits [127:0] to become + * Changing the vector length causes all of ZA, ZTn, P0..P15, FFR and all + bits of Z0..Z31 except for Z0 bits [127:0] .. Z31 bits [127:0] to become unspecified, including both streaming and non-streaming SVE state. Calling PR_SME_SET_VL with vl equal to the thread's current vector length, or calling PR_SME_SET_VL with the PR_SVE_SET_VL_ONEXEC flag, @@ -317,6 +337,15 @@ The regset data starts with struct user_za_header, containing: * The effect of writing a partial, incomplete payload is unspecified. +* A new regset NT_ARM_ZT is defined for access to ZTn state via + PTRACE_GETREGSET and PTRACE_SETREGSET. + +* The NT_ARM_ZT regset consists of a single 512 bit register. + +* When PSTATE.ZA==0 reads of NT_ARM_ZT will report all bits of ZTn as 0. + +* Writes to NT_ARM_ZT will set PSTATE.ZA to 1. + 8. ELF coredump extensions --------------------------- @@ -331,6 +360,11 @@ The regset data starts with struct user_za_header, containing: been read if a PTRACE_GETREGSET of NT_ARM_ZA were executed for each thread when the coredump was generated. +* A NT_ARM_ZT note will be added to each coredump for each thread of the + dumped process. The contents will be equivalent to the data that would have + been read if a PTRACE_GETREGSET of NT_ARM_ZT were executed for each thread + when the coredump was generated. + * The NT_ARM_TLS note will be extended to two registers, the second register will contain TPIDR2_EL0 on systems that support SME and will be read as zero with writes ignored otherwise. @@ -406,6 +440,9 @@ In A64 state, SME adds the following: For best system performance it is strongly encouraged for software to enable ZA only when it is actively being used. +* A new ZT0 register is introduced when SME2 is present. This is a 512 bit + register which is accessible when PSTATE.ZA is set, as ZA itself is. + * Two new 1 bit fields in PSTATE which may be controlled via the SMSTART and SMSTOP instructions or by access to the SVCR system register: diff --git a/Documentation/arm64/sve.rst b/Documentation/arm64/sve.rst index c7a356bf4e8f..1b90a30382ac 100644 --- a/Documentation/arm64/sve.rst +++ b/Documentation/arm64/sve.rst @@ -175,7 +175,7 @@ the SVE instruction set architecture. When returning from a signal handler: * If there is no sve_context record in the signal frame, or if the record is - present but contains no register data as desribed in the previous section, + present but contains no register data as described in the previous section, then the SVE registers/bits become non-live and take unspecified values. * If sve_context is present in the signal frame and contains full register @@ -223,7 +223,7 @@ prctl(PR_SVE_SET_VL, unsigned long arg) Defer the requested vector length change until the next execve() performed by this thread. - The effect is equivalent to implicit exceution of the following + The effect is equivalent to implicit execution of the following call immediately after the next execve() (if any) by the thread: prctl(PR_SVE_SET_VL, arg & ~PR_SVE_SET_VL_ONEXEC) diff --git a/Documentation/atomic_t.txt b/Documentation/atomic_t.txt index 0f1ffa03db09..d7adc6d543db 100644 --- a/Documentation/atomic_t.txt +++ b/Documentation/atomic_t.txt @@ -324,7 +324,7 @@ atomic operations. Specifically 'simple' cmpxchg() loops are expected to not starve one another indefinitely. However, this is not evident on LL/SC architectures, because -while an LL/SC architecure 'can/should/must' provide forward progress +while an LL/SC architecture 'can/should/must' provide forward progress guarantees between competing LL/SC sections, such a guarantee does not transfer to cmpxchg() implemented using LL/SC. Consider: diff --git a/Documentation/block/capability.rst b/Documentation/block/capability.rst deleted file mode 100644 index 2ae7f064736a..000000000000 --- a/Documentation/block/capability.rst +++ /dev/null @@ -1,10 +0,0 @@ -=============================== -Generic Block Device Capability -=============================== - -This file documents the sysfs file ``block/<disk>/capability``. - -``capability`` is a bitfield, printed in hexadecimal, indicating which -capabilities a specific block device supports: - -.. kernel-doc:: include/linux/blkdev.h diff --git a/Documentation/block/index.rst b/Documentation/block/index.rst index c4c73db748a8..102953166429 100644 --- a/Documentation/block/index.rst +++ b/Documentation/block/index.rst @@ -10,7 +10,6 @@ Block bfq-iosched biovecs blk-mq - capability cmdline-partition data-integrity deadline-iosched diff --git a/Documentation/block/ublk.rst b/Documentation/block/ublk.rst index ba45c46cc0da..1713b2890abb 100644 --- a/Documentation/block/ublk.rst +++ b/Documentation/block/ublk.rst @@ -144,6 +144,43 @@ managing and controlling ublk devices with help of several control commands: For retrieving device info via ``ublksrv_ctrl_dev_info``. It is the server's responsibility to save IO target specific info in userspace. +- ``UBLK_CMD_GET_DEV_INFO2`` + Same purpose with ``UBLK_CMD_GET_DEV_INFO``, but ublk server has to + provide path of the char device of ``/dev/ublkc*`` for kernel to run + permission check, and this command is added for supporting unprivileged + ublk device, and introduced with ``UBLK_F_UNPRIVILEGED_DEV`` together. + Only the user owning the requested device can retrieve the device info. + + How to deal with userspace/kernel compatibility: + + 1) if kernel is capable of handling ``UBLK_F_UNPRIVILEGED_DEV`` + + If ublk server supports ``UBLK_F_UNPRIVILEGED_DEV``: + + ublk server should send ``UBLK_CMD_GET_DEV_INFO2``, given anytime + unprivileged application needs to query devices the current user owns, + when the application has no idea if ``UBLK_F_UNPRIVILEGED_DEV`` is set + given the capability info is stateless, and application should always + retrieve it via ``UBLK_CMD_GET_DEV_INFO2`` + + If ublk server doesn't support ``UBLK_F_UNPRIVILEGED_DEV``: + + ``UBLK_CMD_GET_DEV_INFO`` is always sent to kernel, and the feature of + UBLK_F_UNPRIVILEGED_DEV isn't available for user + + 2) if kernel isn't capable of handling ``UBLK_F_UNPRIVILEGED_DEV`` + + If ublk server supports ``UBLK_F_UNPRIVILEGED_DEV``: + + ``UBLK_CMD_GET_DEV_INFO2`` is tried first, and will be failed, then + ``UBLK_CMD_GET_DEV_INFO`` needs to be retried given + ``UBLK_F_UNPRIVILEGED_DEV`` can't be set + + If ublk server doesn't support ``UBLK_F_UNPRIVILEGED_DEV``: + + ``UBLK_CMD_GET_DEV_INFO`` is always sent to kernel, and the feature of + ``UBLK_F_UNPRIVILEGED_DEV`` isn't available for user + - ``UBLK_CMD_START_USER_RECOVERY`` This command is valid if ``UBLK_F_USER_RECOVERY`` feature is enabled. This @@ -180,6 +217,15 @@ managing and controlling ublk devices with help of several control commands: double-write since the driver may issue the same I/O request twice. It might be useful to a read-only FS or a VM backend. +Unprivileged ublk device is supported by passing ``UBLK_F_UNPRIVILEGED_DEV``. +Once the flag is set, all control commands can be sent by unprivileged +user. Except for command of ``UBLK_CMD_ADD_DEV``, permission check on +the specified char device(``/dev/ublkc*``) is done for all other control +commands by ublk driver, for doing that, path of the char device has to +be provided in these commands' payload from ublk server. With this way, +ublk device becomes container-ware, and device created in one container +can be controlled/accessed just inside this container. + Data plane ---------- @@ -254,15 +300,6 @@ with specified IO tag in the command data: Future development ================== -Container-aware ublk deivice ----------------------------- - -ublk driver doesn't handle any IO logic. Its function is well defined -for now and very limited userspace interfaces are needed, which is also -well defined too. It is possible to make ublk devices container-aware block -devices in future as Stefan Hajnoczi suggested [#stefan]_, by removing -ADMIN privilege. - Zero copy --------- diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst index cec2371173d7..bfff0e7e37c2 100644 --- a/Documentation/bpf/bpf_design_QA.rst +++ b/Documentation/bpf/bpf_design_QA.rst @@ -208,6 +208,10 @@ data structures and compile with kernel internal headers. Both of these kernel internals are subject to change and can break with newer kernels such that the program needs to be adapted accordingly. +New BPF functionality is generally added through the use of kfuncs instead of +new helpers. Kfuncs are not considered part of the stable API, and have their own +lifecycle expectations as described in :ref:`BPF_kfunc_lifecycle_expectations`. + Q: Are tracepoints part of the stable ABI? ------------------------------------------ A: NO. Tracepoints are tied to internal implementation details hence they are @@ -236,8 +240,8 @@ A: NO. Classic BPF programs are converted into extend BPF instructions. Q: Can BPF call arbitrary kernel functions? ------------------------------------------- -A: NO. BPF programs can only call a set of helper functions which -is defined for every program type. +A: NO. BPF programs can only call specific functions exposed as BPF helpers or +kfuncs. The set of available functions is defined for every program type. Q: Can BPF overwrite arbitrary kernel memory? --------------------------------------------- @@ -263,7 +267,12 @@ Q: New functionality via kernel modules? Q: Can BPF functionality such as new program or map types, new helpers, etc be added out of kernel module code? -A: NO. +A: Yes, through kfuncs and kptrs + +The core BPF functionality such as program types, maps and helpers cannot be +added to by modules. However, modules can expose functionality to BPF programs +by exporting kfuncs (which may return pointers to module-internal data +structures as kptrs). Q: Directly calling kernel function is an ABI? ---------------------------------------------- @@ -278,7 +287,8 @@ kernel functions have already been used by other kernel tcp cc (congestion-control) implementations. If any of these kernel functions has changed, both the in-tree and out-of-tree kernel tcp cc implementations have to be changed. The same goes for the bpf -programs and they have to be adjusted accordingly. +programs and they have to be adjusted accordingly. See +:ref:`BPF_kfunc_lifecycle_expectations` for details. Q: Attaching to arbitrary kernel functions is an ABI? ----------------------------------------------------- @@ -340,6 +350,7 @@ compatibility for these features? A: NO. -Unlike map value types, there are no stability guarantees for this case. The -whole API to work with allocated objects and any support for special fields -inside them is unstable (since it is exposed through kfuncs). +Unlike map value types, the API to work with allocated objects and any support +for special fields inside them is exposed through kfuncs, and thus has the same +lifecycle expectations as the kfuncs themselves. See +:ref:`BPF_kfunc_lifecycle_expectations` for details. diff --git a/Documentation/bpf/cpumasks.rst b/Documentation/bpf/cpumasks.rst new file mode 100644 index 000000000000..24bef9cbbeee --- /dev/null +++ b/Documentation/bpf/cpumasks.rst @@ -0,0 +1,393 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _cpumasks-header-label: + +================== +BPF cpumask kfuncs +================== + +1. Introduction +=============== + +``struct cpumask`` is a bitmap data structure in the kernel whose indices +reflect the CPUs on the system. Commonly, cpumasks are used to track which CPUs +a task is affinitized to, but they can also be used to e.g. track which cores +are associated with a scheduling domain, which cores on a machine are idle, +etc. + +BPF provides programs with a set of :ref:`kfuncs-header-label` that can be +used to allocate, mutate, query, and free cpumasks. + +2. BPF cpumask objects +====================== + +There are two different types of cpumasks that can be used by BPF programs. + +2.1 ``struct bpf_cpumask *`` +---------------------------- + +``struct bpf_cpumask *`` is a cpumask that is allocated by BPF, on behalf of a +BPF program, and whose lifecycle is entirely controlled by BPF. These cpumasks +are RCU-protected, can be mutated, can be used as kptrs, and can be safely cast +to a ``struct cpumask *``. + +2.1.1 ``struct bpf_cpumask *`` lifecycle +---------------------------------------- + +A ``struct bpf_cpumask *`` is allocated, acquired, and released, using the +following functions: + +.. kernel-doc:: kernel/bpf/cpumask.c + :identifiers: bpf_cpumask_create + +.. kernel-doc:: kernel/bpf/cpumask.c + :identifiers: bpf_cpumask_acquire + +.. kernel-doc:: kernel/bpf/cpumask.c + :identifiers: bpf_cpumask_release + +For example: + +.. code-block:: c + + struct cpumask_map_value { + struct bpf_cpumask __kptr_ref * cpumask; + }; + + struct array_map { + __uint(type, BPF_MAP_TYPE_ARRAY); + __type(key, int); + __type(value, struct cpumask_map_value); + __uint(max_entries, 65536); + } cpumask_map SEC(".maps"); + + static int cpumask_map_insert(struct bpf_cpumask *mask, u32 pid) + { + struct cpumask_map_value local, *v; + long status; + struct bpf_cpumask *old; + u32 key = pid; + + local.cpumask = NULL; + status = bpf_map_update_elem(&cpumask_map, &key, &local, 0); + if (status) { + bpf_cpumask_release(mask); + return status; + } + + v = bpf_map_lookup_elem(&cpumask_map, &key); + if (!v) { + bpf_cpumask_release(mask); + return -ENOENT; + } + + old = bpf_kptr_xchg(&v->cpumask, mask); + if (old) + bpf_cpumask_release(old); + + return 0; + } + + /** + * A sample tracepoint showing how a task's cpumask can be queried and + * recorded as a kptr. + */ + SEC("tp_btf/task_newtask") + int BPF_PROG(record_task_cpumask, struct task_struct *task, u64 clone_flags) + { + struct bpf_cpumask *cpumask; + int ret; + + cpumask = bpf_cpumask_create(); + if (!cpumask) + return -ENOMEM; + + if (!bpf_cpumask_full(task->cpus_ptr)) + bpf_printk("task %s has CPU affinity", task->comm); + + bpf_cpumask_copy(cpumask, task->cpus_ptr); + return cpumask_map_insert(cpumask, task->pid); + } + +---- + +2.1.1 ``struct bpf_cpumask *`` as kptrs +--------------------------------------- + +As mentioned and illustrated above, these ``struct bpf_cpumask *`` objects can +also be stored in a map and used as kptrs. If a ``struct bpf_cpumask *`` is in +a map, the reference can be removed from the map with bpf_kptr_xchg(), or +opportunistically acquired with bpf_cpumask_kptr_get(): + +.. kernel-doc:: kernel/bpf/cpumask.c + :identifiers: bpf_cpumask_kptr_get + +Here is an example of a ``struct bpf_cpumask *`` being retrieved from a map: + +.. code-block:: c + + /* struct containing the struct bpf_cpumask kptr which is stored in the map. */ + struct cpumasks_kfunc_map_value { + struct bpf_cpumask __kptr_ref * bpf_cpumask; + }; + + /* The map containing struct cpumasks_kfunc_map_value entries. */ + struct { + __uint(type, BPF_MAP_TYPE_ARRAY); + __type(key, int); + __type(value, struct cpumasks_kfunc_map_value); + __uint(max_entries, 1); + } cpumasks_kfunc_map SEC(".maps"); + + /* ... */ + + /** + * A simple example tracepoint program showing how a + * struct bpf_cpumask * kptr that is stored in a map can + * be acquired using the bpf_cpumask_kptr_get() kfunc. + */ + SEC("tp_btf/cgroup_mkdir") + int BPF_PROG(cgrp_ancestor_example, struct cgroup *cgrp, const char *path) + { + struct bpf_cpumask *kptr; + struct cpumasks_kfunc_map_value *v; + u32 key = 0; + + /* Assume a bpf_cpumask * kptr was previously stored in the map. */ + v = bpf_map_lookup_elem(&cpumasks_kfunc_map, &key); + if (!v) + return -ENOENT; + + /* Acquire a reference to the bpf_cpumask * kptr that's already stored in the map. */ + kptr = bpf_cpumask_kptr_get(&v->cpumask); + if (!kptr) + /* If no bpf_cpumask was present in the map, it's because + * we're racing with another CPU that removed it with + * bpf_kptr_xchg() between the bpf_map_lookup_elem() + * above, and our call to bpf_cpumask_kptr_get(). + * bpf_cpumask_kptr_get() internally safely handles this + * race, and will return NULL if the cpumask is no longer + * present in the map by the time we invoke the kfunc. + */ + return -EBUSY; + + /* Free the reference we just took above. Note that the + * original struct bpf_cpumask * kptr is still in the map. It will + * be freed either at a later time if another context deletes + * it from the map, or automatically by the BPF subsystem if + * it's still present when the map is destroyed. + */ + bpf_cpumask_release(kptr); + + return 0; + } + +---- + +2.2 ``struct cpumask`` +---------------------- + +``struct cpumask`` is the object that actually contains the cpumask bitmap +being queried, mutated, etc. A ``struct bpf_cpumask`` wraps a ``struct +cpumask``, which is why it's safe to cast it as such (note however that it is +**not** safe to cast a ``struct cpumask *`` to a ``struct bpf_cpumask *``, and +the verifier will reject any program that tries to do so). + +As we'll see below, any kfunc that mutates its cpumask argument will take a +``struct bpf_cpumask *`` as that argument. Any argument that simply queries the +cpumask will instead take a ``struct cpumask *``. + +3. cpumask kfuncs +================= + +Above, we described the kfuncs that can be used to allocate, acquire, release, +etc a ``struct bpf_cpumask *``. This section of the document will describe the +kfuncs for mutating and querying cpumasks. + +3.1 Mutating cpumasks +--------------------- + +Some cpumask kfuncs are "read-only" in that they don't mutate any of their +arguments, whereas others mutate at least one argument (which means that the +argument must be a ``struct bpf_cpumask *``, as described above). + +This section will describe all of the cpumask kfuncs which mutate at least one +argument. :ref:`cpumasks-querying-label` below describes the read-only kfuncs. + +3.1.1 Setting and clearing CPUs +------------------------------- + +bpf_cpumask_set_cpu() and bpf_cpumask_clear_cpu() can be used to set and clear +a CPU in a ``struct bpf_cpumask`` respectively: + +.. kernel-doc:: kernel/bpf/cpumask.c + :identifiers: bpf_cpumask_set_cpu bpf_cpumask_clear_cpu + +These kfuncs are pretty straightforward, and can be used, for example, as +follows: + +.. code-block:: c + + /** + * A sample tracepoint showing how a cpumask can be queried. + */ + SEC("tp_btf/task_newtask") + int BPF_PROG(test_set_clear_cpu, struct task_struct *task, u64 clone_flags) + { + struct bpf_cpumask *cpumask; + + cpumask = bpf_cpumask_create(); + if (!cpumask) + return -ENOMEM; + + bpf_cpumask_set_cpu(0, cpumask); + if (!bpf_cpumask_test_cpu(0, cast(cpumask))) + /* Should never happen. */ + goto release_exit; + + bpf_cpumask_clear_cpu(0, cpumask); + if (bpf_cpumask_test_cpu(0, cast(cpumask))) + /* Should never happen. */ + goto release_exit; + + /* struct cpumask * pointers such as task->cpus_ptr can also be queried. */ + if (bpf_cpumask_test_cpu(0, task->cpus_ptr)) + bpf_printk("task %s can use CPU %d", task->comm, 0); + + release_exit: + bpf_cpumask_release(cpumask); + return 0; + } + +---- + +bpf_cpumask_test_and_set_cpu() and bpf_cpumask_test_and_clear_cpu() are +complementary kfuncs that allow callers to atomically test and set (or clear) +CPUs: + +.. kernel-doc:: kernel/bpf/cpumask.c + :identifiers: bpf_cpumask_test_and_set_cpu bpf_cpumask_test_and_clear_cpu + +---- + +We can also set and clear entire ``struct bpf_cpumask *`` objects in one +operation using bpf_cpumask_setall() and bpf_cpumask_clear(): + +.. kernel-doc:: kernel/bpf/cpumask.c + :identifiers: bpf_cpumask_setall bpf_cpumask_clear + +3.1.2 Operations between cpumasks +--------------------------------- + +In addition to setting and clearing individual CPUs in a single cpumask, +callers can also perform bitwise operations between multiple cpumasks using +bpf_cpumask_and(), bpf_cpumask_or(), and bpf_cpumask_xor(): + +.. kernel-doc:: kernel/bpf/cpumask.c + :identifiers: bpf_cpumask_and bpf_cpumask_or bpf_cpumask_xor + +The following is an example of how they may be used. Note that some of the +kfuncs shown in this example will be covered in more detail below. + +.. code-block:: c + + /** + * A sample tracepoint showing how a cpumask can be mutated using + bitwise operators (and queried). + */ + SEC("tp_btf/task_newtask") + int BPF_PROG(test_and_or_xor, struct task_struct *task, u64 clone_flags) + { + struct bpf_cpumask *mask1, *mask2, *dst1, *dst2; + + mask1 = bpf_cpumask_create(); + if (!mask1) + return -ENOMEM; + + mask2 = bpf_cpumask_create(); + if (!mask2) { + bpf_cpumask_release(mask1); + return -ENOMEM; + } + + // ...Safely create the other two masks... */ + + bpf_cpumask_set_cpu(0, mask1); + bpf_cpumask_set_cpu(1, mask2); + bpf_cpumask_and(dst1, (const struct cpumask *)mask1, (const struct cpumask *)mask2); + if (!bpf_cpumask_empty((const struct cpumask *)dst1)) + /* Should never happen. */ + goto release_exit; + + bpf_cpumask_or(dst1, (const struct cpumask *)mask1, (const struct cpumask *)mask2); + if (!bpf_cpumask_test_cpu(0, (const struct cpumask *)dst1)) + /* Should never happen. */ + goto release_exit; + + if (!bpf_cpumask_test_cpu(1, (const struct cpumask *)dst1)) + /* Should never happen. */ + goto release_exit; + + bpf_cpumask_xor(dst2, (const struct cpumask *)mask1, (const struct cpumask *)mask2); + if (!bpf_cpumask_equal((const struct cpumask *)dst1, + (const struct cpumask *)dst2)) + /* Should never happen. */ + goto release_exit; + + release_exit: + bpf_cpumask_release(mask1); + bpf_cpumask_release(mask2); + bpf_cpumask_release(dst1); + bpf_cpumask_release(dst2); + return 0; + } + +---- + +The contents of an entire cpumask may be copied to another using +bpf_cpumask_copy(): + +.. kernel-doc:: kernel/bpf/cpumask.c + :identifiers: bpf_cpumask_copy + +---- + +.. _cpumasks-querying-label: + +3.2 Querying cpumasks +--------------------- + +In addition to the above kfuncs, there is also a set of read-only kfuncs that +can be used to query the contents of cpumasks. + +.. kernel-doc:: kernel/bpf/cpumask.c + :identifiers: bpf_cpumask_first bpf_cpumask_first_zero bpf_cpumask_test_cpu + +.. kernel-doc:: kernel/bpf/cpumask.c + :identifiers: bpf_cpumask_equal bpf_cpumask_intersects bpf_cpumask_subset + bpf_cpumask_empty bpf_cpumask_full + +.. kernel-doc:: kernel/bpf/cpumask.c + :identifiers: bpf_cpumask_any bpf_cpumask_any_and + +---- + +Some example usages of these querying kfuncs were shown above. We will not +replicate those exmaples 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. + +.. _tools/testing/selftests/bpf/progs/cpumask_success.c: + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/bpf/progs/cpumask_success.c + + +4. Adding BPF cpumask kfuncs +============================ + +The set of supported BPF cpumask kfuncs are not (yet) a 1-1 match with the +cpumask operations in include/linux/cpumask.h. Any of those cpumask operations +could easily be encapsulated in a new kfunc if and when required. If you'd like +to support a new cpumask operation, please feel free to submit a patch. If you +do add a new cpumask kfunc, please document it here, and add any relevant +selftest testcases to the cpumask selftest suite. diff --git a/Documentation/bpf/graph_ds_impl.rst b/Documentation/bpf/graph_ds_impl.rst new file mode 100644 index 000000000000..61274622b71d --- /dev/null +++ b/Documentation/bpf/graph_ds_impl.rst @@ -0,0 +1,267 @@ +========================= +BPF Graph Data Structures +========================= + +This document describes implementation details of new-style "graph" data +structures (linked_list, rbtree), with particular focus on the verifier's +implementation of semantics specific to those data structures. + +Although no specific verifier code is referred to in this document, the document +assumes that the reader has general knowledge of BPF verifier internals, BPF +maps, and BPF program writing. + +Note that the intent of this document is to describe the current state of +these graph data structures. **No guarantees** of stability for either +semantics or APIs are made or implied here. + +.. contents:: + :local: + :depth: 2 + +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 +interacting with the latter group of data structures can be hard to parse +for kernel programmers without previous BPF experience. + +Luckily, some restrictions which necessitated the use of BPF map semantics are +no longer relevant. With the introduction of kfuncs, kptrs, and the any-context +BPF allocator, it is now possible to implement BPF data structures whose API +and semantics more closely match those exposed to the rest of the kernel. + +Two such data structures - linked_list and rbtree - have many verification +details in common. Because both have "root"s ("head" for linked_list) and +"node"s, the verifier code and this document refer to common functionality +as "graph_api", "graph_root", "graph_node", etc. + +Unless otherwise stated, examples and semantics below apply to both graph data +structures. + +Unstable API +------------ + +Data structures implemented using the BPF map API have historically used BPF +helper functions - either standard map API helpers like ``bpf_map_update_elem`` +or map-specific helpers. The new-style graph data structures instead use kfuncs +to define their manipulation helpers. Because there are no stability guarantees +for kfuncs, the API and semantics for these data structures can be evolved in +a way that breaks backwards compatibility if necessary. + +Root and node types for the new data structures are opaquely defined in the +``uapi/linux/bpf.h`` header. + +Locking +------- + +The new-style data structures are intrusive and are defined similarly to their +vanilla kernel counterparts: + +.. code-block:: c + + struct node_data { + long key; + long data; + struct bpf_rb_node node; + }; + + struct bpf_spin_lock glock; + struct bpf_rb_root groot __contains(node_data, node); + +The "root" type for both linked_list and rbtree expects to be in a map_value +which also contains a ``bpf_spin_lock`` - in the above example both global +variables are placed in a single-value arraymap. The verifier considers this +spin_lock to be associated with the ``bpf_rb_root`` by virtue of both being in +the same map_value and will enforce that the correct lock is held when +verifying BPF programs that manipulate the tree. Since this lock checking +happens at verification time, there is no runtime penalty. + +Non-owning references +--------------------- + +**Motivation** + +Consider the following BPF code: + +.. code-block:: c + + struct node_data *n = bpf_obj_new(typeof(*n)); /* ACQUIRED */ + + bpf_spin_lock(&lock); + + bpf_rbtree_add(&tree, n); /* PASSED */ + + bpf_spin_unlock(&lock); + +From the verifier's perspective, the pointer ``n`` returned from ``bpf_obj_new`` +has type ``PTR_TO_BTF_ID | MEM_ALLOC``, with a ``btf_id`` of +``struct node_data`` and a nonzero ``ref_obj_id``. Because it holds ``n``, the +program has ownership of the pointee's (object pointed to by ``n``) lifetime. +The BPF program must pass off ownership before exiting - either via +``bpf_obj_drop``, which ``free``'s the object, or by adding it to ``tree`` with +``bpf_rbtree_add``. + +(``ACQUIRED`` and ``PASSED`` comments in the example denote statements where +"ownership is acquired" and "ownership is passed", respectively) + +What should the verifier do with ``n`` after ownership is passed off? If the +object was ``free``'d with ``bpf_obj_drop`` the answer is obvious: the verifier +should reject programs which attempt to access ``n`` after ``bpf_obj_drop`` as +the object is no longer valid. The underlying memory may have been reused for +some other allocation, unmapped, etc. + +When ownership is passed to ``tree`` via ``bpf_rbtree_add`` the answer is less +obvious. The verifier could enforce the same semantics as for ``bpf_obj_drop``, +but that would result in programs with useful, common coding patterns being +rejected, e.g.: + +.. code-block:: c + + int x; + struct node_data *n = bpf_obj_new(typeof(*n)); /* ACQUIRED */ + + bpf_spin_lock(&lock); + + bpf_rbtree_add(&tree, n); /* PASSED */ + x = n->data; + n->data = 42; + + bpf_spin_unlock(&lock); + +Both the read from and write to ``n->data`` would be rejected. The verifier +can do better, though, by taking advantage of two details: + + * Graph data structure APIs can only be used when the ``bpf_spin_lock`` + associated with the graph root is held + + * Both graph data structures have pointer stability + + * Because graph nodes are allocated with ``bpf_obj_new`` and + adding / removing from the root involves fiddling with the + ``bpf_{list,rb}_node`` field of the node struct, a graph node will + remain at the same address after either operation. + +Because the associated ``bpf_spin_lock`` must be held by any program adding +or removing, if we're in the critical section bounded by that lock, we know +that no other program can add or remove until the end of the critical section. +This combined with pointer stability means that, until the critical section +ends, we can safely access the graph node through ``n`` even after it was used +to pass ownership. + +The verifier considers such a reference a *non-owning reference*. The ref +returned by ``bpf_obj_new`` is accordingly considered an *owning reference*. +Both terms currently only have meaning in the context of graph nodes and API. + +**Details** + +Let's enumerate the properties of both types of references. + +*owning reference* + + * This reference controls the lifetime of the pointee + + * Ownership of pointee must be 'released' by passing it to some graph API + kfunc, or via ``bpf_obj_drop``, which ``free``'s the pointee + + * If not released before program ends, verifier considers program invalid + + * Access to the pointee's memory will not page fault + +*non-owning reference* + + * This reference does not own the pointee + + * It cannot be used to add the graph node to a graph root, nor ``free``'d via + ``bpf_obj_drop`` + + * No explicit control of lifetime, but can infer valid lifetime based on + non-owning ref existence (see explanation below) + + * Access to the pointee's memory will not page fault + +From verifier's perspective non-owning references can only exist +between spin_lock and spin_unlock. Why? After spin_unlock another program +can do arbitrary operations on the data structure like removing and ``free``-ing +via bpf_obj_drop. A non-owning ref to some chunk of memory that was remove'd, +``free``'d, and reused via bpf_obj_new would point to an entirely different thing. +Or the memory could go away. + +To prevent this logic violation all non-owning references are invalidated by the +verifier after a critical section ends. This is necessary to ensure the "will +not page fault" property of non-owning references. So if the verifier hasn't +invalidated a non-owning ref, accessing it will not page fault. + +Currently ``bpf_obj_drop`` is not allowed in the critical section, so +if there's a valid non-owning ref, we must be in a critical section, and can +conclude that the ref's memory hasn't been dropped-and- ``free``'d or +dropped-and-reused. + +Any reference to a node that is in an rbtree _must_ be non-owning, since +the tree has control of the pointee's lifetime. Similarly, any ref to a node +that isn't in rbtree _must_ be owning. This results in a nice property: +graph API add / remove implementations don't need to check if a node +has already been added (or already removed), as the ownership model +allows the verifier to prevent such a state from being valid by simply checking +types. + +However, pointer aliasing poses an issue for the above "nice property". +Consider the following example: + +.. code-block:: c + + struct node_data *n, *m, *o, *p; + n = bpf_obj_new(typeof(*n)); /* 1 */ + + bpf_spin_lock(&lock); + + bpf_rbtree_add(&tree, n); /* 2 */ + m = bpf_rbtree_first(&tree); /* 3 */ + + o = bpf_rbtree_remove(&tree, n); /* 4 */ + p = bpf_rbtree_remove(&tree, m); /* 5 */ + + bpf_spin_unlock(&lock); + + bpf_obj_drop(o); + bpf_obj_drop(p); /* 6 */ + +Assume the tree is empty before this program runs. If we track verifier state +changes here using numbers in above comments: + + 1) n is an owning reference + + 2) n is a non-owning reference, it's been added to the tree + + 3) n and m are non-owning references, they both point to the same node + + 4) o is an owning reference, n and m non-owning, all point to same node + + 5) o and p are owning, n and m non-owning, all point to the same node + + 6) a double-free has occurred, since o and p point to same node and o was + ``free``'d in previous statement + +States 4 and 5 violate our "nice property", as there are non-owning refs to +a node which is not in an rbtree. Statement 5 will try to remove a node which +has already been removed as a result of this violation. State 6 is a dangerous +double-free. + +At a minimum we should prevent state 6 from being possible. If we can't also +prevent state 5 then we must abandon our "nice property" and check whether a +node has already been removed at runtime. + +We prevent both by generalizing the "invalidate non-owning references" behavior +of ``bpf_spin_unlock`` and doing similar invalidation after +``bpf_rbtree_remove``. The logic here being that any graph API kfunc which: + + * takes an arbitrary node argument + + * removes it from the data structure + + * returns an owning reference to the removed node + +May result in a state where some other non-owning reference points to the same +node. So ``remove``-type kfuncs must be considered a non-owning reference +invalidation point as well. diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst index b81533d8b061..dbb39e8f9889 100644 --- a/Documentation/bpf/index.rst +++ b/Documentation/bpf/index.rst @@ -20,6 +20,7 @@ that goes into great technical depth about the BPF Architecture. syscall_api helpers kfuncs + cpumasks programs maps bpf_prog_run diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index e672d5ec6cc7..af515de5fc38 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -7,6 +7,11 @@ eBPF Instruction Set Specification, v1.0 This document specifies version 1.0 of the eBPF 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. Registers and calling convention ================================ @@ -30,20 +35,56 @@ Instruction encoding eBPF 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 value - (imm64) after the basic instruction for a total of 128 bits. +* the wide instruction encoding, which appends a second 64-bit immediate (i.e., + constant) value after the basic instruction for a total of 128 bits. + +The basic instruction encoding is as follows, where MSB and LSB mean the most significant +bits and least significant bits, respectively: + +============= ======= ======= ======= ============ +32 bits (MSB) 16 bits 4 bits 4 bits 8 bits (LSB) +============= ======= ======= ======= ============ +imm offset src_reg dst_reg opcode +============= ======= ======= ======= ============ + +**imm** + signed integer immediate value -The basic instruction encoding looks as follows: +**offset** + signed integer offset used with pointer arithmetic -============= ======= =============== ==================== ============ -32 bits (MSB) 16 bits 4 bits 4 bits 8 bits (LSB) -============= ======= =============== ==================== ============ -immediate offset source register destination register opcode -============= ======= =============== ==================== ============ +**src_reg** + the source register number (0-10), except where otherwise specified + (`64-bit immediate instructions`_ reuse this field for other purposes) + +**dst_reg** + destination register number (0-10) + +**opcode** + operation to perform Note that most instructions do not use all of the fields. Unused fields shall be cleared to zero. +As discussed below in `64-bit immediate instructions`_, a 64-bit immediate +instruction uses a 64-bit immediate value that is constructed as follows. +The 64 bits following the basic instruction contain a pseudo instruction +using the same format but with opcode, dst_reg, src_reg, and offset all set to zero, +and imm containing the high 32 bits of the immediate value. + +================= ================== +64 bits (MSB) 64 bits (LSB) +================= ================== +basic instruction pseudo instruction +================= ================== + +Thus the 64-bit immediate value is constructed as follows: + + imm64 = (next_imm << 32) | imm + +where 'next_imm' refers to the imm value of the pseudo instruction +following the basic instruction. + Instruction classes ------------------- @@ -71,27 +112,32 @@ For arithmetic and jump instructions (``BPF_ALU``, ``BPF_ALU64``, ``BPF_JMP`` an ============== ====== ================= 4 bits (MSB) 1 bit 3 bits (LSB) ============== ====== ================= -operation code source instruction class +code source instruction class ============== ====== ================= -The 4th bit encodes the source operand: +**code** + the operation code, whose meaning varies by instruction class - ====== ===== ======================================== - source value description - ====== ===== ======================================== - BPF_K 0x00 use 32-bit immediate as source operand - BPF_X 0x08 use 'src_reg' register as source operand - ====== ===== ======================================== +**source** + the source operand location, which unless otherwise specified is one of: -The four MSB bits store the operation code. + ====== ===== ============================================== + source value description + ====== ===== ============================================== + BPF_K 0x00 use 32-bit 'imm' value as source operand + BPF_X 0x08 use 'src_reg' register value as source operand + ====== ===== ============================================== +**instruction class** + the instruction class (see `Instruction classes`_) Arithmetic instructions ----------------------- ``BPF_ALU`` uses 32-bit wide operands while ``BPF_ALU64`` uses 64-bit wide operands for otherwise identical operations. -The 'code' field encodes the operation as below: +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 @@ -99,35 +145,49 @@ code value description BPF_ADD 0x00 dst += src BPF_SUB 0x10 dst -= src BPF_MUL 0x20 dst \*= src -BPF_DIV 0x30 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 BPF_RSH 0x70 dst >>= src BPF_NEG 0x80 dst = ~src -BPF_MOD 0x90 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 shift right BPF_END 0xd0 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 +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 +32 bits of the destination register are zeroed. + ``BPF_ADD | BPF_X | BPF_ALU`` means:: - dst_reg = (u32) dst_reg + (u32) src_reg; + dst = (u32) ((u32) dst + (u32) src) + +where '(u32)' indicates that the upper 32 bits are zeroed. ``BPF_ADD | BPF_X | BPF_ALU64`` means:: - dst_reg = dst_reg + src_reg + dst = dst + src ``BPF_XOR | BPF_K | BPF_ALU`` means:: - dst_reg = (u32) dst_reg ^ (u32) imm32 + dst = (u32) dst ^ (u32) imm32 ``BPF_XOR | BPF_K | BPF_ALU64`` means:: - dst_reg = dst_reg ^ imm32 + 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. Byte swap instructions ~~~~~~~~~~~~~~~~~~~~~~ @@ -155,11 +215,11 @@ Examples: ``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16 means:: - dst_reg = htole16(dst_reg) + dst = htole16(dst) ``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 64 means:: - dst_reg = htobe64(dst_reg) + dst = htobe64(dst) Jump instructions ----------------- @@ -234,15 +294,15 @@ instructions that transfer data between a register and memory. ``BPF_MEM | <size> | BPF_STX`` means:: - *(size *) (dst_reg + off) = src_reg + *(size *) (dst + offset) = src ``BPF_MEM | <size> | BPF_ST`` means:: - *(size *) (dst_reg + off) = imm32 + *(size *) (dst + offset) = imm32 ``BPF_MEM | <size> | BPF_LDX`` means:: - dst_reg = *(size *) (src_reg + off) + dst = *(size *) (src + offset) Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``. @@ -276,11 +336,11 @@ BPF_XOR 0xa0 atomic xor ``BPF_ATOMIC | BPF_W | BPF_STX`` with 'imm' = BPF_ADD means:: - *(u32 *)(dst_reg + off16) += src_reg + *(u32 *)(dst + offset) += src ``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means:: - *(u64 *)(dst_reg + off16) += src_reg + *(u64 *)(dst + offset) += src In addition to the simple atomic operations, there also is a modifier and two complex atomic operations: @@ -295,16 +355,16 @@ BPF_CMPXCHG 0xf0 | BPF_FETCH atomic compare and exchange The ``BPF_FETCH`` modifier is optional for simple atomic operations, and always set for the complex atomic operations. If the ``BPF_FETCH`` flag -is set, then the operation also overwrites ``src_reg`` with the value that +is set, then the operation also overwrites ``src`` with the value that was in memory before it was modified. -The ``BPF_XCHG`` operation atomically exchanges ``src_reg`` with the value -addressed by ``dst_reg + off``. +The ``BPF_XCHG`` operation atomically exchanges ``src`` with the value +addressed by ``dst + offset``. The ``BPF_CMPXCHG`` operation atomically compares the value addressed by -``dst_reg + off`` with ``R0``. If they match, the value addressed by -``dst_reg + off`` is replaced with ``src_reg``. In either case, the -value that was at ``dst_reg + off`` before the operation is zero-extended +``dst + offset`` with ``R0``. If they match, the value addressed by +``dst + offset`` is replaced with ``src``. In either case, the +value that was at ``dst + offset`` before the operation is zero-extended and loaded back to ``R0``. 64-bit immediate instructions @@ -317,7 +377,7 @@ There is currently only one such instruction. ``BPF_LD | BPF_DW | BPF_IMM`` means:: - dst_reg = imm64 + dst = imm64 Legacy BPF Packet access instructions diff --git a/Documentation/bpf/kfuncs.rst b/Documentation/bpf/kfuncs.rst index 9fd7fb539f85..ca96ef3f6896 100644 --- a/Documentation/bpf/kfuncs.rst +++ b/Documentation/bpf/kfuncs.rst @@ -1,3 +1,7 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _kfuncs-header-label: + ============================= BPF Kernel Functions (kfuncs) ============================= @@ -9,7 +13,7 @@ BPF Kernel Functions or more commonly known as kfuncs are functions in the Linux kernel which are exposed for use by BPF programs. Unlike normal BPF helpers, kfuncs do not have a stable interface and can change from one kernel release to another. Hence, BPF programs need to be updated in response to changes in the -kernel. +kernel. See :ref:`BPF_kfunc_lifecycle_expectations` for more information. 2. Defining a kfunc =================== @@ -37,7 +41,7 @@ An example is given below:: __diag_ignore_all("-Wmissing-prototypes", "Global kfuncs as their definitions will be in BTF"); - struct task_struct *bpf_find_get_task_by_vpid(pid_t nr) + __bpf_kfunc struct task_struct *bpf_find_get_task_by_vpid(pid_t nr) { return find_get_task_by_vpid(nr); } @@ -62,7 +66,7 @@ kfunc with a __tag, where tag may be one of the supported annotations. This annotation is used to indicate a memory and size pair in the argument list. An example is given below:: - void bpf_memzero(void *mem, int mem__sz) + __bpf_kfunc void bpf_memzero(void *mem, int mem__sz) { ... } @@ -82,7 +86,7 @@ safety of the program. An example is given below:: - void *bpf_obj_new(u32 local_type_id__k, ...) + __bpf_kfunc void *bpf_obj_new(u32 local_type_id__k, ...) { ... } @@ -121,6 +125,20 @@ flags on a set of kfuncs as follows:: This set encodes the BTF ID of each kfunc listed above, and encodes the flags along with it. Ofcourse, it is also allowed to specify no flags. +kfunc definitions should also always be annotated with the ``__bpf_kfunc`` +macro. This prevents issues such as the compiler inlining the kfunc if it's a +static kernel function, or the function being elided in an LTO build as it's +not used in the rest of the kernel. Developers should not manually add +annotations to their kfunc to prevent these issues. If an annotation is +required to prevent such an issue with your kfunc, it is a bug and should be +added to the definition of the macro so that other kfuncs are similarly +protected. An example is given below:: + + __bpf_kfunc struct task_struct *bpf_get_task_pid(s32 pid) + { + ... + } + 2.4.1 KF_ACQUIRE flag --------------------- @@ -163,7 +181,8 @@ KF_ACQUIRE and KF_RET_NULL flags. The KF_TRUSTED_ARGS flag is used for kfuncs taking pointer arguments. It indicates that the all pointer arguments are valid, and that all pointers to BTF objects have been passed in their unmodified form (that is, at a zero -offset, and without having been obtained from walking another pointer). +offset, and without having been obtained from walking another pointer, with one +exception described below). There are two types of pointers to kernel objects which are considered "valid": @@ -176,6 +195,25 @@ KF_TRUSTED_ARGS kfuncs, and may have a non-zero offset. The definition of "valid" pointers is subject to change at any time, and has absolutely no ABI stability guarantees. +As mentioned above, a nested pointer obtained from walking a trusted pointer is +no longer trusted, with one exception. If a struct type has a field that is +guaranteed to be valid as long as its parent pointer is trusted, the +``BTF_TYPE_SAFE_NESTED`` macro can be used to express that to the verifier as +follows: + +.. code-block:: c + + BTF_TYPE_SAFE_NESTED(struct task_struct) { + const cpumask_t *cpus_ptr; + }; + +In other words, you must: + +1. Wrap the trusted pointer type in the ``BTF_TYPE_SAFE_NESTED`` macro. + +2. Specify the type and name of the trusted nested field. This field must match + the field in the original type definition exactly. + 2.4.6 KF_SLEEPABLE flag ----------------------- @@ -200,6 +238,28 @@ single argument which must be a trusted argument or a MEM_RCU pointer. The argument may have reference count of 0 and the kfunc must take this into consideration. +.. _KF_deprecated_flag: + +2.4.9 KF_DEPRECATED flag +------------------------ + +The KF_DEPRECATED flag is used for kfuncs which are scheduled to be +changed or removed in a subsequent kernel release. A kfunc that is +marked with KF_DEPRECATED should also have any relevant information +captured in its kernel doc. Such information typically includes the +kfunc's expected remaining lifespan, a recommendation for new +functionality that can replace it if any is available, and possibly a +rationale for why it is being removed. + +Note that while on some occasions, a KF_DEPRECATED kfunc may continue to be +supported and have its KF_DEPRECATED flag removed, it is likely to be far more +difficult to remove a KF_DEPRECATED flag after it's been added than it is to +prevent it from being added in the first place. As described in +:ref:`BPF_kfunc_lifecycle_expectations`, users that rely on specific kfuncs are +encouraged to make their use-cases known as early as possible, and participate +in upstream discussions regarding whether to keep, change, deprecate, or remove +those kfuncs if and when such discussions occur. + 2.5 Registering the kfuncs -------------------------- @@ -223,14 +283,150 @@ type. An example is shown below:: } late_initcall(init_subsystem); -3. Core kfuncs +2.6 Specifying no-cast aliases with ___init +-------------------------------------------- + +The verifier will always enforce that the BTF type of a pointer passed to a +kfunc by a BPF program, matches the type of pointer specified in the kfunc +definition. The verifier, does, however, allow types that are equivalent +according to the C standard to be passed to the same kfunc arg, even if their +BTF_IDs differ. + +For example, for the following type definition: + +.. code-block:: c + + struct bpf_cpumask { + cpumask_t cpumask; + refcount_t usage; + }; + +The verifier would allow a ``struct bpf_cpumask *`` to be passed to a kfunc +taking a ``cpumask_t *`` (which is a typedef of ``struct cpumask *``). For +instance, both ``struct cpumask *`` and ``struct bpf_cpmuask *`` can be passed +to bpf_cpumask_test_cpu(). + +In some cases, this type-aliasing behavior is not desired. ``struct +nf_conn___init`` is one such example: + +.. code-block:: c + + struct nf_conn___init { + struct nf_conn ct; + }; + +The C standard would consider these types to be equivalent, but it would not +always be safe to pass either type to a trusted kfunc. ``struct +nf_conn___init`` represents an allocated ``struct nf_conn`` object that has +*not yet been initialized*, so it would therefore be unsafe to pass a ``struct +nf_conn___init *`` to a kfunc that's expecting a fully initialized ``struct +nf_conn *`` (e.g. ``bpf_ct_change_timeout()``). + +In order to accommodate such requirements, the verifier will enforce strict +PTR_TO_BTF_ID type matching if two types have the exact same name, with one +being suffixed with ``___init``. + +.. _BPF_kfunc_lifecycle_expectations: + +3. kfunc lifecycle expectations +=============================== + +kfuncs provide a kernel <-> kernel API, and thus are not bound by any of the +strict stability restrictions associated with kernel <-> user UAPIs. This means +they can be thought of as similar to EXPORT_SYMBOL_GPL, and can therefore be +modified or removed by a maintainer of the subsystem they're defined in when +it's deemed necessary. + +Like any other change to the kernel, maintainers will not change or remove a +kfunc without having a reasonable justification. Whether or not they'll choose +to change a kfunc will ultimately depend on a variety of factors, such as how +widely used the kfunc is, how long the kfunc has been in the kernel, whether an +alternative kfunc exists, what the norm is in terms of stability for the +subsystem in question, and of course what the technical cost is of continuing +to support the kfunc. + +There are several implications of this: + +a) kfuncs that are widely used or have been in the kernel for a long time will + be more difficult to justify being changed or removed by a maintainer. In + other words, kfuncs that are known to have a lot of users and provide + significant value provide stronger incentives for maintainers to invest the + time and complexity in supporting them. It is therefore important for + developers that are using kfuncs in their BPF programs to communicate and + explain how and why those kfuncs are being used, and to participate in + discussions regarding those kfuncs when they occur upstream. + +b) Unlike regular kernel symbols marked with EXPORT_SYMBOL_GPL, BPF programs + that call kfuncs are generally not part of the kernel tree. This means that + refactoring cannot typically change callers in-place when a kfunc changes, + as is done for e.g. an upstreamed driver being updated in place when a + kernel symbol is changed. + + Unlike with regular kernel symbols, this is expected behavior for BPF + symbols, and out-of-tree BPF programs that use kfuncs should be considered + relevant to discussions and decisions around modifying and removing those + kfuncs. The BPF community will take an active role in participating in + upstream discussions when necessary to ensure that the perspectives of such + users are taken into account. + +c) A kfunc will never have any hard stability guarantees. BPF APIs cannot and + will not ever hard-block a change in the kernel purely for stability + reasons. That being said, kfuncs are features that are meant to solve + problems and provide value to users. The decision of whether to change or + remove a kfunc is a multivariate technical decision that is made on a + case-by-case basis, and which is informed by data points such as those + mentioned above. It is expected that a kfunc being removed or changed with + no warning will not be a common occurrence or take place without sound + justification, but it is a possibility that must be accepted if one is to + use kfuncs. + +3.1 kfunc deprecation +--------------------- + +As described above, while sometimes a maintainer may find that a kfunc must be +changed or removed immediately to accommodate some changes in their subsystem, +usually kfuncs will be able to accommodate a longer and more measured +deprecation process. For example, if a new kfunc comes along which provides +superior functionality to an existing kfunc, the existing kfunc may be +deprecated for some period of time to allow users to migrate their BPF programs +to use the new one. Or, if a kfunc has no known users, a decision may be made +to remove the kfunc (without providing an alternative API) after some +deprecation period so as to provide users with a window to notify the kfunc +maintainer if it turns out that the kfunc is actually being used. + +It's expected that the common case will be that kfuncs will go through a +deprecation period rather than being changed or removed without warning. As +described in :ref:`KF_deprecated_flag`, the kfunc framework provides the +KF_DEPRECATED flag to kfunc developers to signal to users that a kfunc has been +deprecated. Once a kfunc has been marked with KF_DEPRECATED, the following +procedure is followed for removal: + +1. Any relevant information for deprecated kfuncs is documented in the kfunc's + kernel docs. This documentation will typically include the kfunc's expected + remaining lifespan, a recommendation for new functionality that can replace + the usage of the deprecated function (or an explanation as to why no such + replacement exists), etc. + +2. The deprecated kfunc is kept in the kernel for some period of time after it + was first marked as deprecated. This time period will be chosen on a + case-by-case basis, and will typically depend on how widespread the use of + the kfunc is, how long it has been in the kernel, and how hard it is to move + to alternatives. This deprecation time period is "best effort", and as + described :ref:`above<BPF_kfunc_lifecycle_expectations>`, circumstances may + sometimes dictate that the kfunc be removed before the full intended + deprecation period has elapsed. + +3. After the deprecation period the kfunc will be removed. At this point, BPF + programs calling the kfunc will be rejected by the verifier. + +4. Core kfuncs ============== The BPF subsystem provides a number of "core" kfuncs that are potentially applicable to a wide variety of different possible use cases and programs. Those kfuncs are documented here. -3.1 struct task_struct * kfuncs +4.1 struct task_struct * kfuncs ------------------------------- There are a number of kfuncs that allow ``struct task_struct *`` objects to be @@ -306,7 +502,7 @@ Here is an example of it being used: return 0; } -3.2 struct cgroup * kfuncs +4.2 struct cgroup * kfuncs -------------------------- ``struct cgroup *`` objects also have acquire and release functions: @@ -420,3 +616,10 @@ the verifier. bpf_cgroup_ancestor() can be used as follows: bpf_cgroup_release(parent); return 0; } + +4.3 struct cpumask * kfuncs +--------------------------- + +BPF provides a set of kfuncs that can be used to query, allocate, mutate, and +destroy struct cpumask * objects. Please refer to :ref:`cpumasks-header-label` +for more details. diff --git a/Documentation/bpf/libbpf/libbpf_naming_convention.rst b/Documentation/bpf/libbpf/libbpf_naming_convention.rst index c5ac97f3d4c4..b5b41b61b3c0 100644 --- a/Documentation/bpf/libbpf/libbpf_naming_convention.rst +++ b/Documentation/bpf/libbpf/libbpf_naming_convention.rst @@ -83,8 +83,8 @@ This prevents from accidentally exporting a symbol, that is not supposed to be a part of ABI what, in turn, improves both libbpf developer- and user-experiences. -ABI versionning ---------------- +ABI versioning +-------------- To make future ABI extensions possible libbpf ABI is versioned. Versioning is implemented by ``libbpf.map`` version script that is @@ -148,7 +148,7 @@ API documentation convention The libbpf API is documented via comments above definitions in header files. These comments can be rendered by doxygen and sphinx for well organized html output. This section describes the -convention in which these comments should be formated. +convention in which these comments should be formatted. Here is an example from btf.h: diff --git a/Documentation/bpf/map_sockmap.rst b/Documentation/bpf/map_sockmap.rst new file mode 100644 index 000000000000..cc92047c6630 --- /dev/null +++ b/Documentation/bpf/map_sockmap.rst @@ -0,0 +1,498 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. Copyright Red Hat + +============================================== +BPF_MAP_TYPE_SOCKMAP and BPF_MAP_TYPE_SOCKHASH +============================================== + +.. note:: + - ``BPF_MAP_TYPE_SOCKMAP`` was introduced in kernel version 4.14 + - ``BPF_MAP_TYPE_SOCKHASH`` was introduced in kernel version 4.18 + +``BPF_MAP_TYPE_SOCKMAP`` and ``BPF_MAP_TYPE_SOCKHASH`` maps can be used to +redirect skbs between sockets or to apply policy at the socket level based on +the result of a BPF (verdict) program with the help of the BPF helpers +``bpf_sk_redirect_map()``, ``bpf_sk_redirect_hash()``, +``bpf_msg_redirect_map()`` and ``bpf_msg_redirect_hash()``. + +``BPF_MAP_TYPE_SOCKMAP`` is backed by an array that uses an integer key as the +index to look up a reference to a ``struct sock``. The map values are socket +descriptors. Similarly, ``BPF_MAP_TYPE_SOCKHASH`` is a hash backed BPF map that +holds references to sockets via their socket descriptors. + +.. note:: + The value type is either __u32 or __u64; the latter (__u64) is to support + returning socket cookies to userspace. Returning the ``struct sock *`` that + the map holds to user-space is neither safe nor useful. + +These maps may have BPF programs attached to them, specifically a parser program +and a verdict program. The parser program determines how much data has been +parsed and therefore how much data needs to be queued to come to a verdict. The +verdict program is essentially the redirect program and can return a verdict +of ``__SK_DROP``, ``__SK_PASS``, or ``__SK_REDIRECT``. + +When a socket is inserted into one of these maps, its socket callbacks are +replaced and a ``struct sk_psock`` is attached to it. Additionally, this +``sk_psock`` inherits the programs that are attached to the map. + +A sock object may be in multiple maps, but can only inherit a single +parse or verdict program. If adding a sock object to a map would result +in having multiple parser programs the update will return an EBUSY error. + +The supported programs to attach to these maps are: + +.. code-block:: c + + struct sk_psock_progs { + struct bpf_prog *msg_parser; + struct bpf_prog *stream_parser; + struct bpf_prog *stream_verdict; + struct bpf_prog *skb_verdict; + }; + +.. note:: + Users are not allowed to attach ``stream_verdict`` and ``skb_verdict`` + programs to the same map. + +The attach types for the map programs are: + +- ``msg_parser`` program - ``BPF_SK_MSG_VERDICT``. +- ``stream_parser`` program - ``BPF_SK_SKB_STREAM_PARSER``. +- ``stream_verdict`` program - ``BPF_SK_SKB_STREAM_VERDICT``. +- ``skb_verdict`` program - ``BPF_SK_SKB_VERDICT``. + +There are additional helpers available to use with the parser and verdict +programs: ``bpf_msg_apply_bytes()`` and ``bpf_msg_cork_bytes()``. With +``bpf_msg_apply_bytes()`` BPF programs can tell the infrastructure how many +bytes the given verdict should apply to. The helper ``bpf_msg_cork_bytes()`` +handles a different case where a BPF program cannot reach a verdict on a msg +until it receives more bytes AND the program doesn't want to forward the packet +until it is known to be good. + +Finally, the helpers ``bpf_msg_pull_data()`` and ``bpf_msg_push_data()`` are +available to ``BPF_PROG_TYPE_SK_MSG`` BPF programs to pull in data and set the +start and end pointers to given values or to add metadata to the ``struct +sk_msg_buff *msg``. + +All these helpers will be described in more detail below. + +Usage +===== +Kernel BPF +---------- +bpf_msg_redirect_map() +^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + long bpf_msg_redirect_map(struct sk_msg_buff *msg, struct bpf_map *map, u32 key, u64 flags) + +This helper is used in programs implementing policies at the socket level. If +the message ``msg`` is allowed to pass (i.e., if the verdict BPF program +returns ``SK_PASS``), redirect it to the socket referenced by ``map`` (of type +``BPF_MAP_TYPE_SOCKMAP``) at index ``key``. Both ingress and egress interfaces +can be used for redirection. The ``BPF_F_INGRESS`` value in ``flags`` is used +to select the ingress path otherwise the egress path is selected. This is the +only flag supported for now. + +Returns ``SK_PASS`` on success, or ``SK_DROP`` on error. + +bpf_sk_redirect_map() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + long bpf_sk_redirect_map(struct sk_buff *skb, struct bpf_map *map, u32 key u64 flags) + +Redirect the packet to the socket referenced by ``map`` (of type +``BPF_MAP_TYPE_SOCKMAP``) at index ``key``. Both ingress and egress interfaces +can be used for redirection. The ``BPF_F_INGRESS`` value in ``flags`` is used +to select the ingress path otherwise the egress path is selected. This is the +only flag supported for now. + +Returns ``SK_PASS`` on success, or ``SK_DROP`` on error. + +bpf_map_lookup_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + void *bpf_map_lookup_elem(struct bpf_map *map, const void *key) + +socket entries of type ``struct sock *`` can be retrieved using the +``bpf_map_lookup_elem()`` helper. + +bpf_sock_map_update() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + long bpf_sock_map_update(struct bpf_sock_ops *skops, struct bpf_map *map, void *key, u64 flags) + +Add an entry to, or update a ``map`` referencing sockets. The ``skops`` is used +as a new value for the entry associated to ``key``. The ``flags`` argument can +be one of the following: + +- ``BPF_ANY``: Create a new element or update an existing element. +- ``BPF_NOEXIST``: Create a new element only if it did not exist. +- ``BPF_EXIST``: Update an existing element. + +If the ``map`` has BPF programs (parser and verdict), those will be inherited +by the socket being added. If the socket is already attached to BPF programs, +this results in an error. + +Returns 0 on success, or a negative error in case of failure. + +bpf_sock_hash_update() +^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + long bpf_sock_hash_update(struct bpf_sock_ops *skops, struct bpf_map *map, void *key, u64 flags) + +Add an entry to, or update a sockhash ``map`` referencing sockets. The ``skops`` +is used as a new value for the entry associated to ``key``. + +The ``flags`` argument can be one of the following: + +- ``BPF_ANY``: Create a new element or update an existing element. +- ``BPF_NOEXIST``: Create a new element only if it did not exist. +- ``BPF_EXIST``: Update an existing element. + +If the ``map`` has BPF programs (parser and verdict), those will be inherited +by the socket being added. If the socket is already attached to BPF programs, +this results in an error. + +Returns 0 on success, or a negative error in case of failure. + +bpf_msg_redirect_hash() +^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + long bpf_msg_redirect_hash(struct sk_msg_buff *msg, struct bpf_map *map, void *key, u64 flags) + +This helper is used in programs implementing policies at the socket level. If +the message ``msg`` is allowed to pass (i.e., if the verdict BPF program returns +``SK_PASS``), redirect it to the socket referenced by ``map`` (of type +``BPF_MAP_TYPE_SOCKHASH``) using hash ``key``. Both ingress and egress +interfaces can be used for redirection. The ``BPF_F_INGRESS`` value in +``flags`` is used to select the ingress path otherwise the egress path is +selected. This is the only flag supported for now. + +Returns ``SK_PASS`` on success, or ``SK_DROP`` on error. + +bpf_sk_redirect_hash() +^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + long bpf_sk_redirect_hash(struct sk_buff *skb, struct bpf_map *map, void *key, u64 flags) + +This helper is used in programs implementing policies at the skb socket level. +If the sk_buff ``skb`` is allowed to pass (i.e., if the verdict BPF program +returns ``SK_PASS``), redirect it to the socket referenced by ``map`` (of type +``BPF_MAP_TYPE_SOCKHASH``) using hash ``key``. Both ingress and egress +interfaces can be used for redirection. The ``BPF_F_INGRESS`` value in +``flags`` is used to select the ingress path otherwise the egress path is +selected. This is the only flag supported for now. + +Returns ``SK_PASS`` on success, or ``SK_DROP`` on error. + +bpf_msg_apply_bytes() +^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + long bpf_msg_apply_bytes(struct sk_msg_buff *msg, u32 bytes) + +For socket policies, apply the verdict of the BPF program to the next (number +of ``bytes``) of message ``msg``. For example, this helper can be used in the +following cases: + +- A single ``sendmsg()`` or ``sendfile()`` system call contains multiple + logical messages that the BPF program is supposed to read and for which it + should apply a verdict. +- A BPF program only cares to read the first ``bytes`` of a ``msg``. If the + message has a large payload, then setting up and calling the BPF program + repeatedly for all bytes, even though the verdict is already known, would + create unnecessary overhead. + +Returns 0 + +bpf_msg_cork_bytes() +^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + long bpf_msg_cork_bytes(struct sk_msg_buff *msg, u32 bytes) + +For socket policies, prevent the execution of the verdict BPF program for +message ``msg`` until the number of ``bytes`` have been accumulated. + +This can be used when one needs a specific number of bytes before a verdict can +be assigned, even if the data spans multiple ``sendmsg()`` or ``sendfile()`` +calls. + +Returns 0 + +bpf_msg_pull_data() +^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + long bpf_msg_pull_data(struct sk_msg_buff *msg, u32 start, u32 end, u64 flags) + +For socket policies, pull in non-linear data from user space for ``msg`` and set +pointers ``msg->data`` and ``msg->data_end`` to ``start`` and ``end`` bytes +offsets into ``msg``, respectively. + +If a program of type ``BPF_PROG_TYPE_SK_MSG`` is run on a ``msg`` it can only +parse data that the (``data``, ``data_end``) pointers have already consumed. +For ``sendmsg()`` hooks this is likely the first scatterlist element. But for +calls relying on the ``sendpage`` handler (e.g., ``sendfile()``) this will be +the range (**0**, **0**) because the data is shared with user space and by +default the objective is to avoid allowing user space to modify data while (or +after) BPF verdict is being decided. This helper can be used to pull in data +and to set the start and end pointers to given values. Data will be copied if +necessary (i.e., if data was not linear and if start and end pointers do not +point to the same chunk). + +A call to this helper is susceptible to change the underlying packet buffer. +Therefore, at load time, all checks on pointers previously done by the verifier +are invalidated and must be performed again, if the helper is used in +combination with direct packet access. + +All values for ``flags`` are reserved for future usage, and must be left at +zero. + +Returns 0 on success, or a negative error in case of failure. + +bpf_map_lookup_elem() +^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: c + + void *bpf_map_lookup_elem(struct bpf_map *map, const void *key) + +Look up a socket entry in the sockmap or sockhash map. + +Returns the socket entry associated to ``key``, or NULL if no entry was found. + +bpf_map_update_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + long bpf_map_update_elem(struct bpf_map *map, const void *key, const void *value, u64 flags) + +Add or update a socket entry in a sockmap or sockhash. + +The flags argument can be one of the following: + +- BPF_ANY: Create a new element or update an existing element. +- BPF_NOEXIST: Create a new element only if it did not exist. +- BPF_EXIST: Update an existing element. + +Returns 0 on success, or a negative error in case of failure. + +bpf_map_delete_elem() +^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + long bpf_map_delete_elem(struct bpf_map *map, const void *key) + +Delete a socket entry from a sockmap or a sockhash. + +Returns 0 on success, or a negative error in case of failure. + +User space +---------- +bpf_map_update_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + int bpf_map_update_elem(int fd, const void *key, const void *value, __u64 flags) + +Sockmap entries can be added or updated using the ``bpf_map_update_elem()`` +function. The ``key`` parameter is the index value of the sockmap array. And the +``value`` parameter is the FD value of that socket. + +Under the hood, the sockmap update function uses the socket FD value to +retrieve the associated socket and its attached psock. + +The flags argument can be one of the following: + +- BPF_ANY: Create a new element or update an existing element. +- BPF_NOEXIST: Create a new element only if it did not exist. +- BPF_EXIST: Update an existing element. + +bpf_map_lookup_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + int bpf_map_lookup_elem(int fd, const void *key, void *value) + +Sockmap entries can be retrieved using the ``bpf_map_lookup_elem()`` function. + +.. note:: + The entry returned is a socket cookie rather than a socket itself. + +bpf_map_delete_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + int bpf_map_delete_elem(int fd, const void *key) + +Sockmap entries can be deleted using the ``bpf_map_delete_elem()`` +function. + +Returns 0 on success, or negative error in case of failure. + +Examples +======== + +Kernel BPF +---------- +Several examples of the use of sockmap APIs can be found in: + +- `tools/testing/selftests/bpf/progs/test_sockmap_kern.h`_ +- `tools/testing/selftests/bpf/progs/sockmap_parse_prog.c`_ +- `tools/testing/selftests/bpf/progs/sockmap_verdict_prog.c`_ +- `tools/testing/selftests/bpf/progs/test_sockmap_listen.c`_ +- `tools/testing/selftests/bpf/progs/test_sockmap_update.c`_ + +The following code snippet shows how to declare a sockmap. + +.. code-block:: c + + struct { + __uint(type, BPF_MAP_TYPE_SOCKMAP); + __uint(max_entries, 1); + __type(key, __u32); + __type(value, __u64); + } sock_map_rx SEC(".maps"); + +The following code snippet shows a sample parser program. + +.. code-block:: c + + SEC("sk_skb/stream_parser") + int bpf_prog_parser(struct __sk_buff *skb) + { + return skb->len; + } + +The following code snippet shows a simple verdict program that interacts with a +sockmap to redirect traffic to another socket based on the local port. + +.. code-block:: c + + SEC("sk_skb/stream_verdict") + int bpf_prog_verdict(struct __sk_buff *skb) + { + __u32 lport = skb->local_port; + __u32 idx = 0; + + if (lport == 10000) + return bpf_sk_redirect_map(skb, &sock_map_rx, idx, 0); + + return SK_PASS; + } + +The following code snippet shows how to declare a sockhash map. + +.. code-block:: c + + struct socket_key { + __u32 src_ip; + __u32 dst_ip; + __u32 src_port; + __u32 dst_port; + }; + + struct { + __uint(type, BPF_MAP_TYPE_SOCKHASH); + __uint(max_entries, 1); + __type(key, struct socket_key); + __type(value, __u64); + } sock_hash_rx SEC(".maps"); + +The following code snippet shows a simple verdict program that interacts with a +sockhash to redirect traffic to another socket based on a hash of some of the +skb parameters. + +.. code-block:: c + + static inline + void extract_socket_key(struct __sk_buff *skb, struct socket_key *key) + { + key->src_ip = skb->remote_ip4; + key->dst_ip = skb->local_ip4; + key->src_port = skb->remote_port >> 16; + key->dst_port = (bpf_htonl(skb->local_port)) >> 16; + } + + SEC("sk_skb/stream_verdict") + int bpf_prog_verdict(struct __sk_buff *skb) + { + struct socket_key key; + + extract_socket_key(skb, &key); + + return bpf_sk_redirect_hash(skb, &sock_hash_rx, &key, 0); + } + +User space +---------- +Several examples of the use of sockmap APIs can be found in: + +- `tools/testing/selftests/bpf/prog_tests/sockmap_basic.c`_ +- `tools/testing/selftests/bpf/test_sockmap.c`_ +- `tools/testing/selftests/bpf/test_maps.c`_ + +The following code sample shows how to create a sockmap, attach a parser and +verdict program, as well as add a socket entry. + +.. code-block:: c + + int create_sample_sockmap(int sock, int parse_prog_fd, int verdict_prog_fd) + { + int index = 0; + int map, err; + + map = bpf_map_create(BPF_MAP_TYPE_SOCKMAP, NULL, sizeof(int), sizeof(int), 1, NULL); + if (map < 0) { + fprintf(stderr, "Failed to create sockmap: %s\n", strerror(errno)); + return -1; + } + + err = bpf_prog_attach(parse_prog_fd, map, BPF_SK_SKB_STREAM_PARSER, 0); + if (err){ + fprintf(stderr, "Failed to attach_parser_prog_to_map: %s\n", strerror(errno)); + goto out; + } + + err = bpf_prog_attach(verdict_prog_fd, map, BPF_SK_SKB_STREAM_VERDICT, 0); + if (err){ + fprintf(stderr, "Failed to attach_verdict_prog_to_map: %s\n", strerror(errno)); + goto out; + } + + err = bpf_map_update_elem(map, &index, &sock, BPF_NOEXIST); + if (err) { + fprintf(stderr, "Failed to update sockmap: %s\n", strerror(errno)); + goto out; + } + + out: + close(map); + return err; + } + +References +=========== + +- https://github.com/jrfastab/linux-kernel-xdp/commit/c89fd73cb9d2d7f3c716c3e00836f07b1aeb261f +- https://lwn.net/Articles/731133/ +- http://vger.kernel.org/lpc_net2018_talks/ktls_bpf_paper.pdf +- https://lwn.net/Articles/748628/ +- https://lore.kernel.org/bpf/20200218171023.844439-7-jakub@cloudflare.com/ + +.. _`tools/testing/selftests/bpf/progs/test_sockmap_kern.h`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/progs/test_sockmap_kern.h +.. _`tools/testing/selftests/bpf/progs/sockmap_parse_prog.c`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/progs/sockmap_parse_prog.c +.. _`tools/testing/selftests/bpf/progs/sockmap_verdict_prog.c`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/progs/sockmap_verdict_prog.c +.. _`tools/testing/selftests/bpf/prog_tests/sockmap_basic.c`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/prog_tests/sockmap_basic.c +.. _`tools/testing/selftests/bpf/test_sockmap.c`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/test_sockmap.c +.. _`tools/testing/selftests/bpf/test_maps.c`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/test_maps.c +.. _`tools/testing/selftests/bpf/progs/test_sockmap_listen.c`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/progs/test_sockmap_listen.c +.. _`tools/testing/selftests/bpf/progs/test_sockmap_update.c`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/progs/test_sockmap_update.c diff --git a/Documentation/bpf/map_xskmap.rst b/Documentation/bpf/map_xskmap.rst index 7093b8208451..dc143edd9233 100644 --- a/Documentation/bpf/map_xskmap.rst +++ b/Documentation/bpf/map_xskmap.rst @@ -178,7 +178,7 @@ The following code snippet shows how to update an XSKMAP with an XSK entry. For an example on how create AF_XDP sockets, please see the AF_XDP-example and AF_XDP-forwarding programs in the `bpf-examples`_ directory in the `libxdp`_ repository. -For a detailed explaination of the AF_XDP interface please see: +For a detailed explanation of the AF_XDP interface please see: - `libxdp-readme`_. - `AF_XDP`_ kernel documentation. diff --git a/Documentation/bpf/other.rst b/Documentation/bpf/other.rst index 3d61963403b4..7e6b12018802 100644 --- a/Documentation/bpf/other.rst +++ b/Documentation/bpf/other.rst @@ -6,4 +6,5 @@ Other :maxdepth: 1 ringbuf - llvm_reloc
\ No newline at end of file + llvm_reloc + graph_ds_impl diff --git a/Documentation/bpf/ringbuf.rst b/Documentation/bpf/ringbuf.rst index 6a615cd62bda..a99cd05d79d4 100644 --- a/Documentation/bpf/ringbuf.rst +++ b/Documentation/bpf/ringbuf.rst @@ -124,7 +124,7 @@ buffer. Currently 4 are supported: - ``BPF_RB_AVAIL_DATA`` returns amount of unconsumed data in ring buffer; - ``BPF_RB_RING_SIZE`` returns the size of ring buffer; -- ``BPF_RB_CONS_POS``/``BPF_RB_PROD_POS`` returns current logical possition +- ``BPF_RB_CONS_POS``/``BPF_RB_PROD_POS`` returns current logical position of consumer/producer, respectively. Returned values are momentarily snapshots of ring buffer state and could be @@ -146,7 +146,7 @@ Design and Implementation This reserve/commit schema allows a natural way for multiple producers, either on different CPUs or even on the same CPU/in the same BPF program, to reserve independent records and work with them without blocking other producers. This -means that if BPF program was interruped by another BPF program sharing the +means that if BPF program was interrupted by another BPF program sharing the same ring buffer, they will both get a record reserved (provided there is enough space left) and can work with it and submit it independently. This applies to NMI context as well, except that due to using a spinlock during diff --git a/Documentation/bpf/verifier.rst b/Documentation/bpf/verifier.rst index d4326caf01f9..f0ec19db301c 100644 --- a/Documentation/bpf/verifier.rst +++ b/Documentation/bpf/verifier.rst @@ -192,7 +192,7 @@ checked and found to be non-NULL, all copies can become PTR_TO_MAP_VALUEs. As well as range-checking, the tracked information is also used for enforcing alignment of pointer accesses. For instance, on most systems the packet pointer is 2 bytes after a 4-byte alignment. If a program adds 14 bytes to that to jump -over the Ethernet header, then reads IHL and addes (IHL * 4), the resulting +over the Ethernet header, then reads IHL and adds (IHL * 4), the resulting pointer will have a variable offset known to be 4n+2 for some n, so adding the 2 bytes (NET_IP_ALIGN) gives a 4-byte alignment and so word-sized accesses through that pointer are safe. @@ -316,6 +316,301 @@ Pruning considers not only the registers but also the stack (and any spilled registers it may hold). They must all be safe for the branch to be pruned. This is implemented in states_equal(). +Some technical details about state pruning implementation could be found below. + +Register liveness tracking +-------------------------- + +In order to make state pruning effective, liveness state is tracked for each +register and stack slot. The basic idea is to track which registers and stack +slots are actually used during subseqeuent execution of the program, until +program exit is reached. Registers and stack slots that were never used could be +removed from the cached state thus making more states equivalent to a cached +state. This could be illustrated by the following program:: + + 0: call bpf_get_prandom_u32() + 1: r1 = 0 + 2: if r0 == 0 goto +1 + 3: r0 = 1 + --- checkpoint --- + 4: r0 = r1 + 5: exit + +Suppose that a state cache entry is created at instruction #4 (such entries are +also called "checkpoints" in the text below). The verifier could reach the +instruction with one of two possible register states: + +* r0 = 1, r1 = 0 +* r0 = 0, r1 = 0 + +However, only the value of register ``r1`` is important to successfully finish +verification. The goal of the liveness tracking algorithm is to spot this fact +and figure out that both states are actually equivalent. + +Data structures +~~~~~~~~~~~~~~~ + +Liveness is tracked using the following data structures:: + + enum bpf_reg_liveness { + REG_LIVE_NONE = 0, + REG_LIVE_READ32 = 0x1, + REG_LIVE_READ64 = 0x2, + REG_LIVE_READ = REG_LIVE_READ32 | REG_LIVE_READ64, + REG_LIVE_WRITTEN = 0x4, + REG_LIVE_DONE = 0x8, + }; + + struct bpf_reg_state { + ... + struct bpf_reg_state *parent; + ... + enum bpf_reg_liveness live; + ... + }; + + struct bpf_stack_state { + struct bpf_reg_state spilled_ptr; + ... + }; + + struct bpf_func_state { + struct bpf_reg_state regs[MAX_BPF_REG]; + ... + struct bpf_stack_state *stack; + } + + struct bpf_verifier_state { + struct bpf_func_state *frame[MAX_CALL_FRAMES]; + struct bpf_verifier_state *parent; + ... + } + +* ``REG_LIVE_NONE`` is an initial value assigned to ``->live`` fields upon new + verifier state creation; + +* ``REG_LIVE_WRITTEN`` means that the value of the register (or stack slot) is + defined by some instruction verified between this verifier state's parent and + verifier state itself; + +* ``REG_LIVE_READ{32,64}`` means that the value of the register (or stack slot) + is read by a some child state of this verifier state; + +* ``REG_LIVE_DONE`` is a marker used by ``clean_verifier_state()`` to avoid + processing same verifier state multiple times and for some sanity checks; + +* ``->live`` field values are formed by combining ``enum bpf_reg_liveness`` + values using bitwise or. + +Register parentage chains +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to propagate information between parent and child states, a *register +parentage chain* is established. Each register or stack slot is linked to a +corresponding register or stack slot in its parent state via a ``->parent`` +pointer. This link is established upon state creation in ``is_state_visited()`` +and might be modified by ``set_callee_state()`` called from +``__check_func_call()``. + +The rules for correspondence between registers / stack slots are as follows: + +* For the current stack frame, registers and stack slots of the new state are + linked to the registers and stack slots of the parent state with the same + indices. + +* For the outer stack frames, only caller saved registers (r6-r9) and stack + slots are linked to the registers and stack slots of the parent state with the + same indices. + +* When function call is processed a new ``struct bpf_func_state`` instance is + allocated, it encapsulates a new set of registers and stack slots. For this + new frame, parent links for r6-r9 and stack slots are set to nil, parent links + for r1-r5 are set to match caller r1-r5 parent links. + +This could be illustrated by the following diagram (arrows stand for +``->parent`` pointers):: + + ... ; Frame #0, some instructions + --- checkpoint #0 --- + 1 : r6 = 42 ; Frame #0 + --- checkpoint #1 --- + 2 : call foo() ; Frame #0 + ... ; Frame #1, instructions from foo() + --- checkpoint #2 --- + ... ; Frame #1, instructions from foo() + --- checkpoint #3 --- + exit ; Frame #1, return from foo() + 3 : r1 = r6 ; Frame #0 <- current state + + +-------------------------------+-------------------------------+ + | Frame #0 | Frame #1 | + Checkpoint +-------------------------------+-------------------------------+ + #0 | r0 | r1-r5 | r6-r9 | fp-8 ... | + +-------------------------------+ + ^ ^ ^ ^ + | | | | + Checkpoint +-------------------------------+ + #1 | r0 | r1-r5 | r6-r9 | fp-8 ... | + +-------------------------------+ + ^ ^ ^ + |_______|_______|_______________ + | | | + nil nil | | | nil nil + | | | | | | | + Checkpoint +-------------------------------+-------------------------------+ + #2 | r0 | r1-r5 | r6-r9 | fp-8 ... | r0 | r1-r5 | r6-r9 | fp-8 ... | + +-------------------------------+-------------------------------+ + ^ ^ ^ ^ ^ + nil nil | | | | | + | | | | | | | + Checkpoint +-------------------------------+-------------------------------+ + #3 | r0 | r1-r5 | r6-r9 | fp-8 ... | r0 | r1-r5 | r6-r9 | fp-8 ... | + +-------------------------------+-------------------------------+ + ^ ^ + nil nil | | + | | | | + Current +-------------------------------+ + state | r0 | r1-r5 | r6-r9 | fp-8 ... | + +-------------------------------+ + \ + r6 read mark is propagated via these links + all the way up to checkpoint #1. + The checkpoint #1 contains a write mark for r6 + because of instruction (1), thus read propagation + does not reach checkpoint #0 (see section below). + +Liveness marks tracking +~~~~~~~~~~~~~~~~~~~~~~~ + +For each processed instruction, the verifier tracks read and written registers +and stack slots. The main idea of the algorithm is that read marks propagate +back along the state parentage chain until they hit a write mark, which 'screens +off' earlier states from the read. The information about reads is propagated by +function ``mark_reg_read()`` which could be summarized as follows:: + + mark_reg_read(struct bpf_reg_state *state, ...): + parent = state->parent + while parent: + if state->live & REG_LIVE_WRITTEN: + break + if parent->live & REG_LIVE_READ64: + break + parent->live |= REG_LIVE_READ64 + state = parent + parent = state->parent + +Notes: + +* The read marks are applied to the **parent** state while write marks are + applied to the **current** state. The write mark on a register or stack slot + means that it is updated by some instruction in the straight-line code leading + from the parent state to the current state. + +* Details about REG_LIVE_READ32 are omitted. + +* Function ``propagate_liveness()`` (see section :ref:`read_marks_for_cache_hits`) + might override the first parent link. Please refer to the comments in the + ``propagate_liveness()`` and ``mark_reg_read()`` source code for further + details. + +Because stack writes could have different sizes ``REG_LIVE_WRITTEN`` marks are +applied conservatively: stack slots are marked as written only if write size +corresponds to the size of the register, e.g. see function ``save_register_state()``. + +Consider the following example:: + + 0: (*u64)(r10 - 8) = 0 ; define 8 bytes of fp-8 + --- checkpoint #0 --- + 1: (*u32)(r10 - 8) = 1 ; redefine lower 4 bytes + 2: r1 = (*u32)(r10 - 8) ; read lower 4 bytes defined at (1) + 3: r2 = (*u32)(r10 - 4) ; read upper 4 bytes defined at (0) + +As stated above, the write at (1) does not count as ``REG_LIVE_WRITTEN``. Should +it be otherwise, the algorithm above wouldn't be able to propagate the read mark +from (3) to checkpoint #0. + +Once the ``BPF_EXIT`` instruction is reached ``update_branch_counts()`` is +called to update the ``->branches`` counter for each verifier state in a chain +of parent verifier states. When the ``->branches`` counter reaches zero the +verifier state becomes a valid entry in a set of cached verifier states. + +Each entry of the verifier states cache is post-processed by a function +``clean_live_states()``. This function marks all registers and stack slots +without ``REG_LIVE_READ{32,64}`` marks as ``NOT_INIT`` or ``STACK_INVALID``. +Registers/stack slots marked in this way are ignored in function ``stacksafe()`` +called from ``states_equal()`` when a state cache entry is considered for +equivalence with a current state. + +Now it is possible to explain how the example from the beginning of the section +works:: + + 0: call bpf_get_prandom_u32() + 1: r1 = 0 + 2: if r0 == 0 goto +1 + 3: r0 = 1 + --- checkpoint[0] --- + 4: r0 = r1 + 5: exit + +* At instruction #2 branching point is reached and state ``{ r0 == 0, r1 == 0, pc == 4 }`` + is pushed to states processing queue (pc stands for program counter). + +* At instruction #4: + + * ``checkpoint[0]`` states cache entry is created: ``{ r0 == 1, r1 == 0, pc == 4 }``; + * ``checkpoint[0].r0`` is marked as written; + * ``checkpoint[0].r1`` is marked as read; + +* At instruction #5 exit is reached and ``checkpoint[0]`` can now be processed + by ``clean_live_states()``. After this processing ``checkpoint[0].r0`` has a + read mark and all other registers and stack slots are marked as ``NOT_INIT`` + or ``STACK_INVALID`` + +* The state ``{ r0 == 0, r1 == 0, pc == 4 }`` is popped from the states queue + and is compared against a cached state ``{ r1 == 0, pc == 4 }``, the states + are considered equivalent. + +.. _read_marks_for_cache_hits: + +Read marks propagation for cache hits +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Another point is the handling of read marks when a previously verified state is +found in the states cache. Upon cache hit verifier must behave in the same way +as if the current state was verified to the program exit. This means that all +read marks, present on registers and stack slots of the cached state, must be +propagated over the parentage chain of the current state. Example below shows +why this is important. Function ``propagate_liveness()`` handles this case. + +Consider the following state parentage chain (S is a starting state, A-E are +derived states, -> arrows show which state is derived from which):: + + r1 read + <------------- A[r1] == 0 + C[r1] == 0 + S ---> A ---> B ---> exit E[r1] == 1 + | + ` ---> C ---> D + | + ` ---> E ^ + |___ suppose all these + ^ states are at insn #Y + | + suppose all these + states are at insn #X + +* Chain of states ``S -> A -> B -> exit`` is verified first. + +* While ``B -> exit`` is verified, register ``r1`` is read and this read mark is + propagated up to state ``A``. + +* When chain of states ``C -> D`` is verified the state ``D`` turns out to be + equivalent to state ``B``. + +* The read mark for ``r1`` has to be propagated to state ``C``, otherwise state + ``C`` might get mistakenly marked as equivalent to state ``E`` even though + values for register ``r1`` differ between ``C`` and ``E``. + Understanding eBPF verifier messages ==================================== diff --git a/Documentation/conf.py b/Documentation/conf.py index a5c45df0bd83..db16814f182f 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -31,6 +31,12 @@ def have_command(cmd): # Get Sphinx version major, minor, patch = sphinx.version_info[:3] +# +# Warn about older versions that we don't want to support for much +# longer. +# +if (major < 2) or (major == 2 and minor < 4): + print('WARNING: support for Sphinx < 2.4 will be removed soon.') # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -110,6 +116,9 @@ if major >= 3: # include/linux/linkage.h: "asmlinkage", + + # include/linux/btf.h + "__bpf_kfunc", ] else: @@ -147,7 +156,7 @@ else: math_renderer = 'mathjax' # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ['sphinx/templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: @@ -322,6 +331,7 @@ if html_theme == 'alabaster': 'description': get_cline_version(), 'page_width': '65em', 'sidebar_width': '15em', + 'fixed_sidebar': 'true', 'font_size': 'inherit', 'font_family': 'serif', } @@ -339,7 +349,11 @@ html_use_smartypants = False # Custom sidebar templates, maps document names to template names. # Note that the RTD theme ignores this -html_sidebars = { '**': ["about.html", 'searchbox.html', 'localtoc.html', 'sourcelink.html']} +html_sidebars = { '**': ['searchbox.html', 'kernel-toc.html', 'sourcelink.html']} + +# about.html is available for alabaster theme. Add it at the front. +if html_theme == 'alabaster': + html_sidebars['**'].insert(0, 'about.html') # Output file base name for HTML help builder. htmlhelp_basename = 'TheLinuxKerneldoc' diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index 77eb775b8b42..7a3a08d81f11 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -127,6 +127,7 @@ Documents that don't fit elsewhere or which have yet to be categorized. :maxdepth: 1 librs + netlink .. only:: subproject and html diff --git a/Documentation/core-api/netlink.rst b/Documentation/core-api/netlink.rst new file mode 100644 index 000000000000..e4a938a05cc9 --- /dev/null +++ b/Documentation/core-api/netlink.rst @@ -0,0 +1,101 @@ +.. SPDX-License-Identifier: BSD-3-Clause + +.. _kernel_netlink: + +=================================== +Netlink notes for kernel developers +=================================== + +General guidance +================ + +Attribute enums +--------------- + +Older families often define "null" attributes and commands with value +of ``0`` and named ``unspec``. This is supported (``type: unused``) +but should be avoided in new families. The ``unspec`` enum values are +not used in practice, so just set the value of the first attribute to ``1``. + +Message enums +------------- + +Use the same command IDs for requests and replies. This makes it easier +to match them up, and we have plenty of ID space. + +Use separate command IDs for notifications. This makes it easier to +sort the notifications from replies (and present them to the user +application via a different API than replies). + +Answer requests +--------------- + +Older families do not reply to all of the commands, especially NEW / ADD +commands. User only gets information whether the operation succeeded or +not via the ACK. Try to find useful data to return. Once the command is +added whether it replies with a full message or only an ACK is uAPI and +cannot be changed. It's better to err on the side of replying. + +Specifically NEW and ADD commands should reply with information identifying +the created object such as the allocated object's ID (without having to +resort to using ``NLM_F_ECHO``). + +NLM_F_ECHO +---------- + +Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO`` +to take effect. This is useful for programs that need precise feedback +from the kernel (for example for logging purposes). + +Support dump consistency +------------------------ + +If iterating over objects during dump may skip over objects or repeat +them - make sure to report dump inconsistency with ``NLM_F_DUMP_INTR``. +This is usually implemented by maintaining a generation id for the +structure and recording it in the ``seq`` member of struct netlink_callback. + +Netlink specification +===================== + +Documentation of the Netlink specification parts which are only relevant +to the kernel space. + +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. + +checks +------ + +Documentation for the ``checks`` sub-sections of attribute specs. + +unterminated-ok +~~~~~~~~~~~~~~~ + +Accept strings without the null-termination (for legacy families only). +Switches from the ``NLA_NUL_STRING`` to ``NLA_STRING`` policy type. + +max-len +~~~~~~~ + +Defines max length for a binary or string attribute (corresponding +to the ``len`` member of struct nla_policy). For string attributes terminating +null character is not counted towards ``max-len``. + +The field may either be a literal integer value or a name of a defined +constant. String types may reduce the constant by one +(i.e. specify ``max-len: CONST - 1``) to reserve space for the terminating +character so implementations should recognize such pattern. + +min-len +~~~~~~~ + +Similar to ``max-len`` but defines minimum length. diff --git a/Documentation/core-api/packing.rst b/Documentation/core-api/packing.rst index d8c341fe383e..3ed13bc9a195 100644 --- a/Documentation/core-api/packing.rst +++ b/Documentation/core-api/packing.rst @@ -161,6 +161,6 @@ xxx_packing() that calls it using the proper QUIRK_* one-hot bits set. The packing() function returns an int-encoded error code, which protects the programmer against incorrect API use. The errors are not expected to occur -durring runtime, therefore it is reasonable for xxx_packing() to return void +during runtime, therefore it is reasonable for xxx_packing() to return void and simply swallow those errors. Optionally it can dump stack or print the error description. diff --git a/Documentation/core-api/padata.rst b/Documentation/core-api/padata.rst index 35175710b43c..05b73c6c105f 100644 --- a/Documentation/core-api/padata.rst +++ b/Documentation/core-api/padata.rst @@ -42,7 +42,7 @@ padata_shells associated with it, each allowing a separate series of jobs. Modifying cpumasks ------------------ -The CPUs used to run jobs can be changed in two ways, programatically with +The CPUs used to run jobs can be changed in two ways, programmatically with padata_set_cpumask() or via sysfs. The former is defined:: int padata_set_cpumask(struct padata_instance *pinst, int cpumask_type, diff --git a/Documentation/core-api/pin_user_pages.rst b/Documentation/core-api/pin_user_pages.rst index b18416f4500f..9fb0b1080d3b 100644 --- a/Documentation/core-api/pin_user_pages.rst +++ b/Documentation/core-api/pin_user_pages.rst @@ -55,18 +55,17 @@ flags the caller provides. The caller is required to pass in a non-null struct pages* array, and the function then pins pages by incrementing each by a special value: GUP_PIN_COUNTING_BIAS. -For compound pages, the GUP_PIN_COUNTING_BIAS scheme is not used. Instead, -an exact form of pin counting is achieved, by using the 2nd struct page -in the compound page. A new struct page field, compound_pincount, has -been added in order to support this. - -This approach for compound pages avoids the counting upper limit problems that -are discussed below. Those limitations would have been aggravated severely by -huge pages, because each tail page adds a refcount to the head page. And in -fact, testing revealed that, without a separate compound_pincount field, -page overflows were seen in some huge page stress tests. - -This also means that huge pages and compound pages do not suffer +For large folios, the GUP_PIN_COUNTING_BIAS scheme is not used. Instead, +the extra space available in the struct folio is used to store the +pincount directly. + +This approach for large folios avoids the counting upper limit problems +that are discussed below. Those limitations would have been aggravated +severely by huge pages, because each tail page adds a refcount to the +head page. And in fact, testing revealed that, without a separate pincount +field, refcount overflows were seen in some huge page stress tests. + +This also means that huge pages and large folios do not suffer from the false positives problem that is mentioned below.:: Function @@ -221,7 +220,7 @@ Unit testing ============ This file:: - tools/testing/selftests/vm/gup_test.c + tools/testing/selftests/mm/gup_test.c has the following new calls to exercise the new pin*() wrapper functions: @@ -264,9 +263,9 @@ place.) Other diagnostics ================= -dump_page() has been enhanced slightly, to handle these new counting -fields, and to better report on compound pages in general. Specifically, -for compound pages, the exact (compound_pincount) pincount is reported. +dump_page() has been enhanced slightly to handle these new counting +fields, and to better report on large folios in general. Specifically, +for large folios, the exact pincount is reported. References ========== diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst index 3b22ed137662..8ec4d6270b24 100644 --- a/Documentation/core-api/workqueue.rst +++ b/Documentation/core-api/workqueue.rst @@ -370,8 +370,8 @@ of possible problems: The first one can be tracked using tracing: :: - $ echo workqueue:workqueue_queue_work > /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace_pipe > out.txt + $ echo workqueue:workqueue_queue_work > /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace_pipe > out.txt (wait a few secs) ^C diff --git a/Documentation/cpu-freq/index.rst b/Documentation/cpu-freq/index.rst index 2fe32dad562a..de25740651f7 100644 --- a/Documentation/cpu-freq/index.rst +++ b/Documentation/cpu-freq/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -============================================================================== -Linux CPUFreq - CPU frequency and voltage scaling code in the Linux(TM) kernel -============================================================================== +======================================================================== +CPUFreq - CPU frequency and voltage scaling code in the Linux(TM) kernel +======================================================================== Author: Dominik Brodowski <linux@brodo.de> diff --git a/Documentation/crypto/index.rst b/Documentation/crypto/index.rst index 21338fa92642..da5d5ad2bdf3 100644 --- a/Documentation/crypto/index.rst +++ b/Documentation/crypto/index.rst @@ -1,6 +1,6 @@ -======================= -Linux Kernel Crypto API -======================= +========== +Crypto API +========== :Author: Stephan Mueller :Author: Marek Vasut diff --git a/Documentation/dev-tools/coccinelle.rst b/Documentation/dev-tools/coccinelle.rst index d9976069ed12..535ce126fb4f 100644 --- a/Documentation/dev-tools/coccinelle.rst +++ b/Documentation/dev-tools/coccinelle.rst @@ -219,7 +219,7 @@ instance:: cat cocci.err You can use SPFLAGS to add debugging flags; for instance you may want to -add both --profile --show-trying to SPFLAGS when debugging. For example +add both ``--profile --show-trying`` to SPFLAGS when debugging. For example you may want to use:: rm -f err.log @@ -248,7 +248,7 @@ variables for .cocciconfig is as follows: - Your current user's home directory is processed first - Your directory from which spatch is called is processed next -- The directory provided with the --dir option is processed last, if used +- The directory provided with the ``--dir`` option is processed last, if used Since coccicheck runs through make, it naturally runs from the kernel proper dir; as such the second rule above would be implied for picking up a @@ -265,8 +265,8 @@ The kernel coccicheck script has:: fi KBUILD_EXTMOD is set when an explicit target with M= is used. For both cases -the spatch --dir argument is used, as such third rule applies when whether M= -is used or not, and when M= is used the target directory can have its own +the spatch ``--dir`` argument is used, as such third rule applies when whether +M= is used or not, and when M= is used the target directory can have its own .cocciconfig file. When M= is not passed as an argument to coccicheck the target directory is the same as the directory from where spatch was called. diff --git a/Documentation/dev-tools/gdb-kernel-debugging.rst b/Documentation/dev-tools/gdb-kernel-debugging.rst index 8e0f1fe8d17a..895285c037c7 100644 --- a/Documentation/dev-tools/gdb-kernel-debugging.rst +++ b/Documentation/dev-tools/gdb-kernel-debugging.rst @@ -39,6 +39,10 @@ Setup this mode. In this case, you should build the kernel with CONFIG_RANDOMIZE_BASE disabled if the architecture supports KASLR. +- Build the gdb scripts (required on kernels v5.1 and above):: + + make scripts_gdb + - Enable the gdb stub of QEMU/KVM, either - at VM startup time by appending "-s" to the QEMU command line diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index 5c93ab915049..e66916a483cd 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -140,6 +140,23 @@ disabling KASAN altogether or controlling its features: - ``kasan.vmalloc=off`` or ``=on`` disables or enables tagging of vmalloc allocations (default: ``on``). +- ``kasan.page_alloc.sample=<sampling interval>`` makes KASAN tag only every + Nth page_alloc allocation with the order equal or greater than + ``kasan.page_alloc.sample.order``, where N is the value of the ``sample`` + parameter (default: ``1``, or tag every such allocation). + This parameter is intended to mitigate the performance overhead introduced + by KASAN. + Note that enabling this parameter makes Hardware Tag-Based KASAN skip checks + of allocations chosen by sampling and thus miss bad accesses to these + allocations. Use the default value for accurate bug detection. + +- ``kasan.page_alloc.sample.order=<minimum page order>`` specifies the minimum + order of allocations that are affected by sampling (default: ``3``). + Only applies when ``kasan.page_alloc.sample`` is set to a value greater + than ``1``. + This parameter is intended to allow sampling only large page_alloc + allocations, which is the biggest source of the performance overhead. + Error reports ~~~~~~~~~~~~~ diff --git a/Documentation/dev-tools/kunit/api/functionredirection.rst b/Documentation/dev-tools/kunit/api/functionredirection.rst new file mode 100644 index 000000000000..3791efc2fcca --- /dev/null +++ b/Documentation/dev-tools/kunit/api/functionredirection.rst @@ -0,0 +1,162 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================== +Function Redirection API +======================== + +Overview +======== + +When writing unit tests, it's important to be able to isolate the code being +tested from other parts of the kernel. This ensures the reliability of the test +(it won't be affected by external factors), reduces dependencies on specific +hardware or config options (making the test easier to run), and protects the +stability of the rest of the system (making it less likely for test-specific +state to interfere with the rest of the system). + +While for some code (typically generic data structures, helpers, and other +"pure functions") this is trivial, for others (like device drivers, +filesystems, core subsystems) the code is heavily coupled with other parts of +the kernel. + +This coupling is often due to global state in some way: be it a global list of +devices, the filesystem, or some hardware state. Tests need to either carefully +manage, isolate, and restore state, or they can avoid it altogether by +replacing access to and mutation of this state with a "fake" or "mock" variant. + +By refactoring access to such state, such as by introducing a layer of +indirection which can use or emulate a separate set of test state. However, +such refactoring comes with its own costs (and undertaking significant +refactoring before being able to write tests is suboptimal). + +A simpler way to intercept and replace some of the function calls is to use +function redirection via static stubs. + + +Static Stubs +============ + +Static stubs are a way of redirecting calls to one function (the "real" +function) to another function (the "replacement" function). + +It works by adding a macro to the "real" function which checks to see if a test +is running, and if a replacement function is available. If so, that function is +called in place of the original. + +Using static stubs is pretty straightforward: + +1. Add the KUNIT_STATIC_STUB_REDIRECT() macro to the start of the "real" + function. + + This should be the first statement in the function, after any variable + declarations. KUNIT_STATIC_STUB_REDIRECT() takes the name of the + function, followed by all of the arguments passed to the real function. + + For example: + + .. code-block:: c + + void send_data_to_hardware(const char *str) + { + KUNIT_STATIC_STUB_REDIRECT(send_data_to_hardware, str); + /* real implementation */ + } + +2. Write one or more replacement functions. + + These functions should have the same function signature as the real function. + In the event they need to access or modify test-specific state, they can use + kunit_get_current_test() to get a struct kunit pointer. This can then + be passed to the expectation/assertion macros, or used to look up KUnit + resources. + + For example: + + .. code-block:: c + + void fake_send_data_to_hardware(const char *str) + { + struct kunit *test = kunit_get_current_test(); + KUNIT_EXPECT_STREQ(test, str, "Hello World!"); + } + +3. Activate the static stub from your test. + + From within a test, the redirection can be enabled with + kunit_activate_static_stub(), which accepts a struct kunit pointer, + the real function, and the replacement function. You can call this several + times with different replacement functions to swap out implementations of the + function. + + In our example, this would be + + .. code-block:: c + + kunit_activate_static_stub(test, + send_data_to_hardware, + fake_send_data_to_hardware); + +4. Call (perhaps indirectly) the real function. + + Once the redirection is activated, any call to the real function will call + the replacement function instead. Such calls may be buried deep in the + implementation of another function, but must occur from the test's kthread. + + For example: + + .. code-block:: c + + send_data_to_hardware("Hello World!"); /* Succeeds */ + send_data_to_hardware("Something else"); /* Fails the test. */ + +5. (Optionally) disable the stub. + + When you no longer need it, disable the redirection (and hence resume the + original behaviour of the 'real' function) using + kunit_deactivate_static_stub(). Otherwise, it will be automatically disabled + when the test exits. + + For example: + + .. code-block:: c + + kunit_deactivate_static_stub(test, send_data_to_hardware); + + +It's also possible to use these replacement functions to test to see if a +function is called at all, for example: + +.. code-block:: c + + void send_data_to_hardware(const char *str) + { + KUNIT_STATIC_STUB_REDIRECT(send_data_to_hardware, str); + /* real implementation */ + } + + /* In test file */ + int times_called = 0; + void fake_send_data_to_hardware(const char *str) + { + times_called++; + } + ... + /* In the test case, redirect calls for the duration of the test */ + kunit_activate_static_stub(test, send_data_to_hardware, fake_send_data_to_hardware); + + send_data_to_hardware("hello"); + KUNIT_EXPECT_EQ(test, times_called, 1); + + /* Can also deactivate the stub early, if wanted */ + kunit_deactivate_static_stub(test, send_data_to_hardware); + + send_data_to_hardware("hello again"); + KUNIT_EXPECT_EQ(test, times_called, 1); + + + +API Reference +============= + +.. kernel-doc:: include/kunit/static_stub.h + :internal: diff --git a/Documentation/dev-tools/kunit/api/index.rst b/Documentation/dev-tools/kunit/api/index.rst index 45ce04823f9f..2d8f756aab56 100644 --- a/Documentation/dev-tools/kunit/api/index.rst +++ b/Documentation/dev-tools/kunit/api/index.rst @@ -4,17 +4,24 @@ API Reference ============= .. toctree:: + :hidden: test resource + functionredirection -This section documents the KUnit kernel testing API. It is divided into the + +This page documents the KUnit kernel testing API. It is divided into the following sections: Documentation/dev-tools/kunit/api/test.rst - - documents all of the standard testing API + - Documents all of the standard testing API Documentation/dev-tools/kunit/api/resource.rst - - documents the KUnit resource API + - Documents the KUnit resource API + +Documentation/dev-tools/kunit/api/functionredirection.rst + + - Documents the KUnit Function Redirection API diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index 48f8196d5aad..9faf2b4153fc 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -648,10 +648,9 @@ We can do this via the ``kunit_test`` field in ``task_struct``, which we can access using the ``kunit_get_current_test()`` function in ``kunit/test-bug.h``. ``kunit_get_current_test()`` is safe to call even if KUnit is not enabled. If -KUnit is not enabled, was built as a module (``CONFIG_KUNIT=m``), or no test is -running in the current task, it will return ``NULL``. This compiles down to -either a no-op or a static key check, so will have a negligible performance -impact when no test is running. +KUnit is not enabled, or if no test is running in the current task, it will +return ``NULL``. This compiles down to either a no-op or a static key check, +so will have a negligible performance impact when no test is running. The example below uses this to implement a "mock" implementation of a function, ``foo``: @@ -726,8 +725,6 @@ structures as shown below: #endif ``kunit_fail_current_test()`` is safe to call even if KUnit is not enabled. If -KUnit is not enabled, was built as a module (``CONFIG_KUNIT=m``), or no test is -running in the current task, it will do nothing. This compiles down to either a -no-op or a static key check, so will have a negligible performance impact when -no test is running. - +KUnit is not enabled, or if no test is running in the current task, it will do +nothing. This compiles down to either a no-op or a static key check, so will +have a negligible performance impact when no test is running. diff --git a/Documentation/devicetree/bindings/.gitignore b/Documentation/devicetree/bindings/.gitignore index a77719968a7e..51ddb26d93f0 100644 --- a/Documentation/devicetree/bindings/.gitignore +++ b/Documentation/devicetree/bindings/.gitignore @@ -2,3 +2,8 @@ *.example.dts /processed-schema*.yaml /processed-schema*.json + +# +# We don't want to ignore the following even if they are dot-files +# +!.yamllint diff --git a/Documentation/devicetree/bindings/Makefile b/Documentation/devicetree/bindings/Makefile index bf2d8a8ced77..8b395893bd85 100644 --- a/Documentation/devicetree/bindings/Makefile +++ b/Documentation/devicetree/bindings/Makefile @@ -28,7 +28,7 @@ $(obj)/%.example.dts: $(src)/%.yaml check_dtschema_version FORCE find_all_cmd = find $(srctree)/$(src) \( -name '*.yaml' ! \ -name 'processed-schema*' \) -find_cmd = $(find_all_cmd) | grep -F "$(DT_SCHEMA_FILES)" +find_cmd = $(find_all_cmd) | grep -F -e "$(subst :," -e ",$(DT_SCHEMA_FILES))" CHK_DT_DOCS := $(shell $(find_cmd)) quiet_cmd_yamllint = LINT $(src) diff --git a/Documentation/devicetree/bindings/arm/altera.yaml b/Documentation/devicetree/bindings/arm/altera.yaml index 3eee03aa935c..8c7575455422 100644 --- a/Documentation/devicetree/bindings/arm/altera.yaml +++ b/Documentation/devicetree/bindings/arm/altera.yaml @@ -31,6 +31,7 @@ properties: - description: Mercury+ AA1 boards items: - enum: + - enclustra,mercury-pe1 - google,chameleon-v3 - const: enclustra,mercury-aa1 - const: altr,socfpga-arria10 diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml index e16b5fa55847..b634d5b04e15 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -154,6 +154,7 @@ properties: items: - enum: - khadas,vim3 + - radxa,zero2 - const: amlogic,a311d - const: amlogic,g12b @@ -165,6 +166,7 @@ properties: - azw,gtking-pro - hardkernel,odroid-go-ultra - hardkernel,odroid-n2 + - hardkernel,odroid-n2l - hardkernel,odroid-n2-plus - khadas,vim3 - ugoos,am6 @@ -176,6 +178,7 @@ properties: - enum: - amediatech,x96-air - amediatech,x96-air-gbit + - bananapi,bpi-m2-pro - bananapi,bpi-m5 - cyx,a95xf3-air - cyx,a95xf3-air-gbit diff --git a/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml b/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml index 73f272664e83..e0eff4c05879 100644 --- a/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml +++ b/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml @@ -78,6 +78,7 @@ properties: - facebook,cloudripper-bmc - facebook,elbert-bmc - facebook,fuji-bmc + - facebook,greatlakes-bmc - ibm,everest-bmc - ibm,rainier-bmc - ibm,tacoma-bmc @@ -85,6 +86,7 @@ properties: - jabil,rbp-bmc - qcom,dc-scm-v1-bmc - quanta,s6q-bmc + - ufispace,ncplite-bmc - const: aspeed,ast2600 additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/atmel-at91.yaml b/Documentation/devicetree/bindings/arm/atmel-at91.yaml index 2224b18801a1..dfb8fd089197 100644 --- a/Documentation/devicetree/bindings/arm/atmel-at91.yaml +++ b/Documentation/devicetree/bindings/arm/atmel-at91.yaml @@ -91,9 +91,11 @@ properties: - const: atmel,sama5d2 - const: atmel,sama5 - - description: SAM9X60-EK board + - description: Microchip SAM9X60 Evaluation Boards items: - - const: microchip,sam9x60ek + - enum: + - microchip,sam9x60ek + - microchip,sam9x60-curiosity - const: microchip,sam9x60 - const: atmel,at91sam9 diff --git a/Documentation/devicetree/bindings/arm/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml index 01b5a9c689a2..0e6b182c8a90 100644 --- a/Documentation/devicetree/bindings/arm/cpus.yaml +++ b/Documentation/devicetree/bindings/arm/cpus.yaml @@ -141,6 +141,7 @@ properties: - arm,cortex-a78ae - arm,cortex-a510 - arm,cortex-a710 + - arm,cortex-a715 - arm,cortex-m0 - arm,cortex-m0+ - arm,cortex-m1 @@ -151,6 +152,7 @@ properties: - arm,cortex-r7 - arm,cortex-x1 - arm,cortex-x2 + - arm,cortex-x3 - arm,neoverse-e1 - arm,neoverse-n1 - arm,neoverse-n2 diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index 05b5276a0e14..442ce8f4d675 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -88,12 +88,56 @@ properties: items: - enum: - armadeus,imx28-apf28 # APF28 SoM - - armadeus,imx28-apf28dev # APF28 SoM on APF28Dev board + - bluegiga,apx4devkit # Bluegiga APx4 SoM on dev board + - crystalfontz,cfa10036 # Crystalfontz CFA-10036 SoM + - eukrea,mbmx28lc - fsl,imx28-evk - i2se,duckbill - i2se,duckbill-2 + - karo,tx28 # Ka-Ro electronics TX28 module + - lwn,imx28-xea + - msr,m28cu3 # M28 SoM with custom base board + - schulercontrol,imx28-sps1 - technologic,imx28-ts4600 - const: fsl,imx28 + + - description: i.MX28 Aries M28 SoM Board + items: + - const: aries,m28 + - const: denx,m28 + - const: fsl,imx28 + + - description: i.MX28 Aries M28EVK Board + items: + - const: aries,m28evk + - const: denx,m28evk + - const: fsl,imx28 + + - description: i.MX28 Armadeus Systems APF28Dev Board + items: + - const: armadeus,imx28-apf28dev + - const: armadeus,imx28-apf28 + - const: fsl,imx28 + + - description: i.MX28 Crystalfontz CFA-10036 based Boards + items: + - enum: + - crystalfontz,cfa10037 + - crystalfontz,cfa10049 + - crystalfontz,cfa10057 + - crystalfontz,cfa10058 + - const: crystalfontz,cfa10036 + - const: fsl,imx28 + + - description: i.MX28 Crystalfontz CFA-10037 based Boards + items: + - enum: + - crystalfontz,cfa10055 + - crystalfontz,cfa10056 + - const: crystalfontz,cfa10037 + - const: crystalfontz,cfa10036 + - const: fsl,imx28 + - description: i.MX28 Duckbill 2 based Boards items: - enum: @@ -103,6 +147,19 @@ properties: - const: i2se,duckbill-2 - const: fsl,imx28 + - description: i.MX28 Eukrea Electromatique MBMX283LC Board + items: + - const: eukrea,mbmx283lc + - const: eukrea,mbmx28lc + - const: fsl,imx28 + + - description: i.MX28 Eukrea Electromatique MBMX287LC Board + items: + - const: eukrea,mbmx287lc + - const: eukrea,mbmx283lc + - const: eukrea,mbmx28lc + - const: fsl,imx28 + - description: i.MX31 based Boards items: - enum: @@ -173,6 +230,7 @@ properties: - kiebackpeter,imx53-ddc # K+P imx53 DDC - kiebackpeter,imx53-hsc # K+P imx53 HSC - menlo,m53menlo # i.MX53 Menlo board + - starterkit,sk-imx53 - voipac,imx53-dmm-668 # Voipac i.MX53 X53-DMM-668 - const: fsl,imx53 @@ -644,6 +702,16 @@ properties: - const: armadeus,imx6ull-opos6ul # OPOS6UL (i.MX6ULL) SoM - const: fsl,imx6ull + - description: i.MX6ULL DHCOM SoM based Boards + items: + - enum: + - dh,imx6ull-dhcom-drc02 + - dh,imx6ull-dhcom-pdk2 + - dh,imx6ull-dhcom-picoitx + - const: dh,imx6ull-dhcom-som # The DHCOR is soldered on the DHCOM + - const: dh,imx6ull-dhcor-som + - const: fsl,imx6ull + - description: i.MX6ULL PHYTEC phyBOARD-Segin items: - enum: @@ -815,7 +883,6 @@ properties: - enum: - beacon,imx8mm-beacon-kit # i.MX8MM Beacon Development Kit - boundary,imx8mm-nitrogen8mm # i.MX8MM Nitrogen Board - - cloos,imx8mm-phg # i.MX8MM Cloos PHG Board - dmo,imx8mm-data-modul-edm-sbc # i.MX8MM eDM SBC - emtrion,emcon-mx8mm-avari # emCON-MX8MM SoM on Avari Base - fsl,imx8mm-ddr4-evk # i.MX8MM DDR4 EVK Board @@ -830,7 +897,6 @@ properties: - innocomm,wb15-evk # i.MX8MM Innocomm EVK board with WB15 SoM - kontron,imx8mm-sl # i.MX8MM Kontron SL (N801X) SOM - kontron,imx8mm-osm-s # i.MX8MM Kontron OSM-S (N802X) SOM - - menlo,mx8menlo # i.MX8MM Menlo board with Verdin SoM - toradex,verdin-imx8mm # Verdin iMX8M Mini Modules - toradex,verdin-imx8mm-nonwifi # Verdin iMX8M Mini Modules without Wi-Fi / BT - toradex,verdin-imx8mm-wifi # Verdin iMX8M Mini Wi-Fi / BT Modules @@ -861,8 +927,10 @@ properties: - description: Toradex Boards with Verdin iMX8M Mini Modules items: - enum: + - menlo,mx8menlo # Verdin iMX8M Mini Module on i.MX8MM Menlo board - toradex,verdin-imx8mm-nonwifi-dahlia # Verdin iMX8M Mini Module on Dahlia - toradex,verdin-imx8mm-nonwifi-dev # Verdin iMX8M Mini Module on Verdin Development Board + - toradex,verdin-imx8mm-nonwifi-yavia # Verdin iMX8M Mini Module on Yavia - const: toradex,verdin-imx8mm-nonwifi # Verdin iMX8M Mini Module without Wi-Fi / BT - const: toradex,verdin-imx8mm # Verdin iMX8M Mini Module - const: fsl,imx8mm @@ -872,6 +940,7 @@ properties: - enum: - toradex,verdin-imx8mm-wifi-dahlia # Verdin iMX8M Mini Wi-Fi / BT Module on Dahlia - toradex,verdin-imx8mm-wifi-dev # Verdin iMX8M Mini Wi-Fi / BT M. on Verdin Development B. + - toradex,verdin-imx8mm-wifi-yavia # Verdin iMX8M Mini Wi-Fi / BT Module on Yavia - const: toradex,verdin-imx8mm-wifi # Verdin iMX8M Mini Wi-Fi / BT Module - const: toradex,verdin-imx8mm # Verdin iMX8M Mini Module - const: fsl,imx8mm @@ -895,6 +964,7 @@ properties: one compatible is needed. items: - enum: + - cloos,imx8mm-phg # i.MX8MM Cloos PHG Board - tq,imx8mm-tqma8mqml-mba8mx # TQ-Systems GmbH i.MX8MM TQMa8MQML SOM on MBa8Mx - const: tq,imx8mm-tqma8mqml # TQ-Systems GmbH i.MX8MM TQMa8MQML SOM - const: fsl,imx8mm @@ -931,10 +1001,11 @@ properties: - description: i.MX8MP based Boards items: - enum: - - dh,imx8mp-dhcom-som # i.MX8MP DHCOM SoM - - dh,imx8mp-dhcom-pdk2 # i.MX8MP DHCOM SoM on PDK2 board + - beacon,imx8mp-beacon-kit # i.MX8MP Beacon Development Kit - fsl,imx8mp-evk # i.MX8MP EVK Board - gateworks,imx8mp-gw74xx # 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 @@ -947,6 +1018,12 @@ properties: - const: avnet,sm2s-imx8mp # SM2S-IMX8PLUS SoM - const: fsl,imx8mp + - description: i.MX8MP DHCOM based Boards + items: + - const: dh,imx8mp-dhcom-pdk2 # i.MX8MP DHCOM SoM on PDK2 board + - const: dh,imx8mp-dhcom-som # i.MX8MP DHCOM SoM + - const: fsl,imx8mp + - description: Engicam i.Core MX8M Plus SoM based boards items: - enum: @@ -965,6 +1042,7 @@ properties: - enum: - toradex,verdin-imx8mp-nonwifi-dahlia # Verdin iMX8M Plus Module on Dahlia - toradex,verdin-imx8mp-nonwifi-dev # Verdin iMX8M Plus Module on Verdin Development Board + - toradex,verdin-imx8mp-nonwifi-yavia # Verdin iMX8M Plus Module on Yavia - const: toradex,verdin-imx8mp-nonwifi # Verdin iMX8M Plus Module without Wi-Fi / BT - const: toradex,verdin-imx8mp # Verdin iMX8M Plus Module - const: fsl,imx8mp @@ -974,6 +1052,7 @@ properties: - enum: - toradex,verdin-imx8mp-wifi-dahlia # Verdin iMX8M Plus Wi-Fi / BT Module on Dahlia - toradex,verdin-imx8mp-wifi-dev # Verdin iMX8M Plus Wi-Fi / BT M. on Verdin Development B. + - toradex,verdin-imx8mp-wifi-yavia # Verdin iMX8M Plus Wi-Fi / BT Module on Yavia - const: toradex,verdin-imx8mp-wifi # Verdin iMX8M Plus Wi-Fi / BT Module - const: toradex,verdin-imx8mp # Verdin iMX8M Plus Module - const: fsl,imx8mp @@ -999,12 +1078,17 @@ properties: - fsl,imx8mq-evk # i.MX8MQ EVK Board - google,imx8mq-phanbell # Google Coral Edge TPU - kontron,pitx-imx8m # Kontron pITX-imx8m Board - - mntre,reform2 # MNT Reform2 Laptop - purism,librem5-devkit # Purism Librem5 devkit - solidrun,hummingboard-pulse # SolidRun Hummingboard Pulse - technexion,pico-pi-imx8m # TechNexion PICO-PI-8M evk - const: fsl,imx8mq + - description: i.MX8MQ NITROGEN SoM based Boards + items: + - const: mntre,reform2 # MNT Reform2 Laptop + - const: boundary,imx8mq-nitrogen8m-som # i.MX8MQ NITROGEN SoM + - const: fsl,imx8mq + - description: Purism Librem5 phones items: - enum: diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml index 2275e5d93721..ae12b1cab9fb 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek.yaml @@ -246,6 +246,10 @@ properties: - const: mediatek,mt8183 - items: - enum: + - mediatek,mt8365-evk + - const: mediatek,mt8365 + - items: + - enum: - mediatek,mt8516-pumpkin - const: mediatek,mt8516 diff --git a/Documentation/devicetree/bindings/arm/qcom,coresight-tpda.yaml b/Documentation/devicetree/bindings/arm/qcom,coresight-tpda.yaml new file mode 100644 index 000000000000..2ec9b5b24d73 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/qcom,coresight-tpda.yaml @@ -0,0 +1,129 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +# Copyright (c) 2023 Qualcomm Innovation Center, Inc. All rights reserved. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/qcom,coresight-tpda.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Trace, Profiling and Diagnostics Aggregator - TPDA + +description: | + TPDAs are responsible for packetization and timestamping of data sets + utilizing the MIPI STPv2 packet protocol. Pulling data sets from one or + more attached TPDM and pushing the resultant (packetized) data out a + master ATB interface. Performing an arbitrated ATB interleaving (funneling) + task for free-flowing data from TPDM (i.e. CMB and DSB data set flows). + + There is no strict binding between TPDM and TPDA. TPDA can have multiple + TPDMs connect to it. But There must be only one TPDA in the path from the + TPDM source to TMC sink. TPDM can directly connect to TPDA's inport or + connect to funnel which will connect to TPDA's inport. + + We can use the commands are similar to the below to validate TPDMs. + Enable coresight sink first. + + echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink + echo 1 > /sys/bus/coresight/devices/tpdm0/enable_source + echo 1 > /sys/bus/coresight/devices/tpdm0/integration_test + echo 2 > /sys/bus/coresight/devices/tpdm0/integration_test + + The test data will be collected in the coresight sink which is enabled. + If rwp register of the sink is keeping updating when do integration_test + (by cat tmc_etf0/mgmt/rwp), it means there is data generated from TPDM + to sink. + +maintainers: + - Mao Jinlong <quic_jinlmao@quicinc.com> + - Tao Zhang <quic_taozha@quicinc.com> + +# Need a custom select here or 'arm,primecell' will match on lots of nodes +select: + properties: + compatible: + contains: + enum: + - qcom,coresight-tpda + required: + - compatible + +properties: + $nodename: + pattern: "^tpda(@[0-9a-f]+)$" + compatible: + items: + - const: qcom,coresight-tpda + - const: arm,primecell + + reg: + minItems: 1 + maxItems: 2 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: apb_pclk + + in-ports: + type: object + description: | + Input connections from TPDM to TPDA + $ref: /schemas/graph.yaml#/properties/ports + + out-ports: + type: object + description: | + Output connections from the TPDA to legacy CoreSight trace bus. + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port: + description: + Output connection from the TPDA to legacy CoreSight Trace bus. + $ref: /schemas/graph.yaml#/properties/port + +required: + - compatible + - reg + - clocks + - clock-names + - in-ports + - out-ports + +additionalProperties: false + +examples: + # minimum tpda definition. + - | + tpda@6004000 { + compatible = "qcom,coresight-tpda", "arm,primecell"; + reg = <0x6004000 0x1000>; + + clocks = <&aoss_qmp>; + clock-names = "apb_pclk"; + + in-ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + tpda_qdss_0_in_tpdm_dcc: endpoint { + remote-endpoint = + <&tpdm_dcc_out_tpda_qdss_0>; + }; + }; + }; + + out-ports { + port { + tpda_qdss_out_funnel_in0: endpoint { + remote-endpoint = + <&funnel_in0_in_tpda_qdss>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/arm/qcom,coresight-tpdm.yaml b/Documentation/devicetree/bindings/arm/qcom,coresight-tpdm.yaml new file mode 100644 index 000000000000..5c08342664ea --- /dev/null +++ b/Documentation/devicetree/bindings/arm/qcom,coresight-tpdm.yaml @@ -0,0 +1,93 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +# Copyright (c) 2023 Qualcomm Innovation Center, Inc. All rights reserved. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/qcom,coresight-tpdm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Trace, Profiling and Diagnostics Monitor - TPDM + +description: | + The TPDM or Monitor serves as data collection component for various dataset + types specified in the QPMDA spec. It covers Implementation defined ((ImplDef), + Basic Counts (BC), Tenure Counts (TC), Continuous Multi-Bit (CMB), and Discrete + Single Bit (DSB). It performs data collection in the data producing clock + domain and transfers it to the data collection time domain, generally ATB + clock domain. + + The primary use case of the TPDM is to collect data from different data + sources and send it to a TPDA for packetization, timestamping, and funneling. + +maintainers: + - Mao Jinlong <quic_jinlmao@quicinc.com> + - Tao Zhang <quic_taozha@quicinc.com> + +# Need a custom select here or 'arm,primecell' will match on lots of nodes +select: + properties: + compatible: + contains: + enum: + - qcom,coresight-tpdm + required: + - compatible + +properties: + $nodename: + pattern: "^tpdm(@[0-9a-f]+)$" + compatible: + items: + - const: qcom,coresight-tpdm + - const: arm,primecell + + reg: + minItems: 1 + maxItems: 2 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: apb_pclk + + out-ports: + description: | + Output connections from the TPDM to coresight funnel/TPDA. + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port: + description: Output connection from the TPDM to coresight + funnel/TPDA. + $ref: /schemas/graph.yaml#/properties/port + +required: + - compatible + - reg + - clocks + - clock-names + +additionalProperties: false + +examples: + # minimum TPDM definition. TPDM connect to coresight TPDA. + - | + tpdm@684c000 { + compatible = "qcom,coresight-tpdm", "arm,primecell"; + reg = <0x0684c000 0x1000>; + + clocks = <&aoss_qmp>; + clock-names = "apb_pclk"; + + out-ports { + port { + tpdm_prng_out_tpda_qdss: endpoint { + remote-endpoint = + <&tpda_qdss_in_tpdm_prng>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index 27063a045bd0..1bb24d46e4ee 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -35,6 +35,8 @@ description: | mdm9615 msm8226 msm8916 + msm8939 + msm8953 msm8956 msm8974 msm8976 @@ -47,11 +49,13 @@ description: | qru1000 sa8155p sa8540p + sa8775p sc7180 sc7280 sc8180x sc8280xp sda660 + sdm450 sdm630 sdm632 sdm636 @@ -62,6 +66,7 @@ description: | sdx65 sm4250 sm6115 + sm6115p sm6125 sm6350 sm6375 @@ -70,6 +75,7 @@ description: | sm8250 sm8350 sm8450 + sm8550 The 'board' element must be one of the following strings: @@ -84,6 +90,7 @@ description: | liquid mtp qrd + ride sbc x100 @@ -162,6 +169,12 @@ properties: - items: - enum: + - sony,kanuti-tulip + - square,apq8039-t2 + - const: qcom,msm8939 + + - items: + - enum: - sony,kugo-row - sony,suzu-row - const: qcom,msm8956 @@ -194,8 +207,10 @@ properties: - items: - enum: + - acer,a1-724 - alcatel,idol347 - asus,z00l + - gplus,fl8005a - huawei,g7 - longcheer,l8910 - samsung,a3u-eur @@ -203,8 +218,13 @@ properties: - samsung,e5 - samsung,e7 - samsung,grandmax + - samsung,gt510 + - samsung,gt58 - samsung,j5 + - samsung,j5x - samsung,serranove + - thwc,uf896 + - thwc,ufi001c - wingtech,wt88047 - const: qcom,msm8916 @@ -215,6 +235,15 @@ properties: - items: - enum: + - motorola,potter + - xiaomi,daisy + - xiaomi,mido + - xiaomi,tissot + - xiaomi,vince + - const: qcom,msm8953 + + - items: + - enum: - lg,bullhead - microsoft,talkman - xiaomi,libra @@ -627,6 +656,12 @@ properties: - const: google,hoglin - const: qcom,sc7280 + - description: Qualcomm Technologies, Inc. sc7280 CRD Pro platform (newest rev) + items: + - const: google,zoglin-sku1536 + - const: google,hoglin-sku1536 + - const: qcom,sc7280 + - description: Qualcomm Technologies, Inc. sc7280 IDP SKU1 platform items: - const: qcom,sc7280-idp @@ -679,6 +714,18 @@ properties: - const: google,zombie-sku512 - const: qcom,sc7280 + - description: Google Zombie with NVMe (newest rev) + items: + - const: google,zombie-sku2 + - const: google,zombie-sku3 + - const: google,zombie-sku515 + - const: qcom,sc7280 + + - description: Google Zombie with LTE and NVMe (newest rev) + items: + - const: google,zombie-sku514 + - const: qcom,sc7280 + - items: - enum: - lenovo,flex-5g @@ -695,6 +742,11 @@ properties: - items: - enum: + - motorola,ali + - const: qcom,sdm450 + + - items: + - enum: - sony,discovery-row - sony,kirin-row - sony,pioneer-row @@ -709,6 +761,7 @@ properties: - items: - enum: - fairphone,fp3 + - motorola,ocean - const: qcom,sdm632 - items: @@ -764,6 +817,11 @@ properties: - items: - enum: + - qcom,sa8775p-ride + - const: qcom,sa8775p + + - items: + - enum: - google,cheza - google,cheza-rev1 - google,cheza-rev2 @@ -792,6 +850,12 @@ properties: - items: - enum: + - lenovo,j606f + - const: qcom,sm6115p + - const: qcom,sm6115 + + - items: + - enum: - sony,pdx201 - const: qcom,sm6125 @@ -826,6 +890,7 @@ properties: - qcom,sm8250-mtp - sony,pdx203-generic - sony,pdx206-generic + - xiaomi,elish - const: qcom,sm8250 - items: @@ -845,6 +910,11 @@ properties: - sony,pdx224 - const: qcom,sm8450 + - items: + - enum: + - qcom,sm8550-mtp + - const: qcom,sm8550 + # Board compatibles go above qcom,msm-id: @@ -922,15 +992,22 @@ allOf: - qcom,apq8026 - qcom,apq8094 - qcom,apq8096 + - qcom,msm8939 + - qcom,msm8953 + - qcom,msm8956 - qcom,msm8992 - qcom,msm8994 - qcom,msm8996 - qcom,msm8998 + - qcom,sdm450 - qcom,sdm630 - qcom,sdm632 + - qcom,sdm636 - qcom,sdm845 - qcom,sdx55 - qcom,sdx65 + - qcom,sm4250 + - qcom,sm6115 - qcom,sm6125 - qcom,sm6350 - qcom,sm7225 @@ -954,6 +1031,8 @@ allOf: - oneplus,dumpling - oneplus,enchilada - oneplus,fajita + - oneplus,oneplus3 + - oneplus,oneplus3t then: properties: qcom,board-id: diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml index 88ff4422a8c1..35f74eda30ae 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -90,11 +90,33 @@ properties: - const: chipspark,rayeager-px2 - const: rockchip,rk3066a + - description: Edgeble Neural Compute Module 2(Neu2) SoM based boards + items: + - const: edgeble,neural-compute-module-2-io # Edgeble Neural Compute Module 2 IO Board + - const: edgeble,neural-compute-module-2 # Edgeble Neural Compute Module 2 SoM + - const: rockchip,rv1126 + + - description: Edgeble Neural Compute Module 6(Neu6) Model A SoM based boards + items: + - const: edgeble,neural-compute-module-6a-io # Edgeble Neural Compute Module 6A IO Board + - const: edgeble,neural-compute-module-6a # Edgeble Neural Compute Module 6A SoM + - const: rockchip,rk3588 + - description: Elgin RV1108 R1 items: - const: elgin,rv1108-r1 - const: rockchip,rv1108 + - description: EmbedFire LubanCat 1 + items: + - const: embedfire,lubancat-1 + - const: rockchip,rk3566 + + - description: EmbedFire LubanCat 2 + items: + - const: embedfire,lubancat-2 + - const: rockchip,rk3568 + - description: Engicam PX30.Core C.TOUCH 2.0 items: - const: engicam,px30-core-ctouch2 @@ -599,6 +621,20 @@ properties: - const: pine64,soquartz - const: rockchip,rk3566 + - description: Radxa Compute Module 3(CM3) + items: + - enum: + - radxa,cm3-io + - const: radxa,cm3 + - const: rockchip,rk3566 + + - description: Radxa CM3 Industrial + items: + - enum: + - radxa,e25 + - const: radxa,cm3i + - const: rockchip,rk3568 + - description: Radxa Rock items: - const: radxa,rock @@ -652,6 +688,16 @@ properties: - const: radxa,rock3a - const: rockchip,rk3568 + - description: Radxa ROCK 5 Model A + items: + - const: radxa,rock-5a + - const: rockchip,rk3588s + + - description: Radxa ROCK 5 Model B + items: + - const: radxa,rock-5b + - const: rockchip,rk3588 + - description: Rikomagic MK808 v1 items: - const: rikomagic,mk808 @@ -689,6 +735,11 @@ properties: - const: rockchip,rk3036-evb - const: rockchip,rk3036 + - description: Rockchip RK3128 Evaluation board + items: + - const: rockchip,rk3128-evb + - const: rockchip,rk3128 + - description: Rockchip RK3228 Evaluation board items: - const: rockchip,rk3228-evb @@ -736,6 +787,11 @@ properties: - const: rockchip,rk3399-sapphire-excavator - const: rockchip,rk3399 + - description: Rockchip RK3588 Evaluation board + items: + - const: rockchip,rk3588-evb1-v10 + - const: rockchip,rk3588 + - description: Rockchip RV1108 Evaluation board items: - const: rockchip,rv1108-evb @@ -761,6 +817,11 @@ properties: - const: tronsmart,orion-r68-meta - const: rockchip,rk3368 + - description: Xunlong Orange Pi R1 Plus + items: + - const: xunlong,orangepi-r1-plus + - const: rockchip,rk3328 + - description: Zkmagic A95X Z2 items: - const: zkmagic,a95x-z2 diff --git a/Documentation/devicetree/bindings/arm/rockchip/pmu.yaml b/Documentation/devicetree/bindings/arm/rockchip/pmu.yaml index 8c73bc7f4009..b79c81cd9f0e 100644 --- a/Documentation/devicetree/bindings/arm/rockchip/pmu.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip/pmu.yaml @@ -27,6 +27,7 @@ select: - rockchip,rk3399-pmu - rockchip,rk3568-pmu - rockchip,rk3588-pmu + - rockchip,rv1126-pmu required: - compatible @@ -43,6 +44,7 @@ properties: - rockchip,rk3399-pmu - rockchip,rk3568-pmu - rockchip,rk3588-pmu + - rockchip,rv1126-pmu - const: syscon - const: simple-mfd diff --git a/Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml b/Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml index faea33e4f731..deb2cf971871 100644 --- a/Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml +++ b/Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml @@ -171,6 +171,7 @@ properties: - hardkernel,odroid-xu3-lite # Hardkernel Odroid XU3 Lite - hardkernel,odroid-xu4 # Hardkernel Odroid XU4 - hardkernel,odroid-hc1 # Hardkernel Odroid HC1 + - samsung,k3g # Samsung Galaxy S5 (SM-G900H) - const: samsung,exynos5800 - const: samsung,exynos5 diff --git a/Documentation/devicetree/bindings/arm/ti/k3.yaml b/Documentation/devicetree/bindings/arm/ti/k3.yaml index 203faab80142..a60a4065caa8 100644 --- a/Documentation/devicetree/bindings/arm/ti/k3.yaml +++ b/Documentation/devicetree/bindings/arm/ti/k3.yaml @@ -38,10 +38,17 @@ properties: - ti,am642-sk - const: ti,am642 + - description: K3 AM642 SoC PHYTEC phyBOARD-Electra + items: + - const: phytec,am642-phyboard-electra-rdk + - const: phytec,am64-phycore-som + - const: ti,am642 + - description: K3 AM654 SoC items: - enum: - siemens,iot2050-advanced + - siemens,iot2050-advanced-m2 - siemens,iot2050-advanced-pg2 - siemens,iot2050-basic - siemens,iot2050-basic-pg2 @@ -69,9 +76,17 @@ properties: - description: K3 J721s2 SoC items: - enum: + - ti,am68-sk - ti,j721s2-evm - const: ti,j721s2 + - description: K3 J784s4 SoC + items: + - enum: + - ti,am69-sk + - ti,j784s4-evm + - const: ti,j784s4 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/ata/intel,ixp4xx-compact-flash.yaml b/Documentation/devicetree/bindings/ata/intel,ixp4xx-compact-flash.yaml index 52e18600ecff..378692010c56 100644 --- a/Documentation/devicetree/bindings/ata/intel,ixp4xx-compact-flash.yaml +++ b/Documentation/devicetree/bindings/ata/intel,ixp4xx-compact-flash.yaml @@ -35,6 +35,7 @@ required: allOf: - $ref: pata-common.yaml# + - $ref: /schemas/memory-controllers/intel,ixp4xx-expansion-peripheral-props.yaml# unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/bus/aspeed,ast2600-ahbc.yaml b/Documentation/devicetree/bindings/bus/aspeed,ast2600-ahbc.yaml new file mode 100644 index 000000000000..2894256c976d --- /dev/null +++ b/Documentation/devicetree/bindings/bus/aspeed,ast2600-ahbc.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/bus/aspeed,ast2600-ahbc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ASPEED Advanced High-Performance Bus Controller (AHBC) + +maintainers: + - Neal Liu <neal_liu@aspeedtech.com> + - Chia-Wei Wang <chiawei_wang@aspeedtech.com> + +description: | + Advanced High-performance Bus Controller (AHBC) supports plenty of mechanisms + including a priority arbiter, an address decoder and a data multiplexer + to control the overall operations of Advanced High-performance Bus (AHB). + +properties: + compatible: + enum: + - aspeed,ast2600-ahbc + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + ahbc@1e600000 { + compatible = "aspeed,ast2600-ahbc"; + reg = <0x1e600000 0x100>; + }; diff --git a/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml b/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml index d3ed048c9521..4157e885c6e7 100644 --- a/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml +++ b/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml @@ -40,10 +40,10 @@ properties: maxItems: 1 "#address-cells": - const: 1 + enum: [ 1, 2 ] "#size-cells": - const: 1 + enum: [ 1, 2 ] ranges: true diff --git a/Documentation/devicetree/bindings/clock/qcom,qdu1000-gcc.yaml b/Documentation/devicetree/bindings/clock/qcom,qdu1000-gcc.yaml new file mode 100644 index 000000000000..767a9d03aa32 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,qdu1000-gcc.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,qdu1000-gcc.yaml# +$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> + +description: | + Qualcomm global clock control module which supports the clocks, resets and + power domains on QDU1000 and QRU1000 + + See also:: include/dt-bindings/clock/qcom,qdu1000-gcc.h + +properties: + compatible: + const: qcom,qdu1000-gcc + + clocks: + items: + - description: Board XO source + - description: Sleep clock source + - description: PCIE 0 Pipe clock source + - description: PCIE 0 Phy Auxiliary 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,qdu1000-gcc"; + reg = <0x00100000 0x001f4200>; + clocks = <&rpmhcc RPMH_CXO_CLK>, <&sleep_clk>, + <&pcie_0_pipe_clk>, <&pcie_0_phy_aux_clk>, + <&usb3_phy_wrapper_pipe_clk>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,sm6350-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm6350-camcc.yaml new file mode 100644 index 000000000000..fd6658cb793d --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sm6350-camcc.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sm6350-camcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Camera Clock & Reset Controller on SM6350 + +maintainers: + - Konrad Dybcio <konrad.dybcio@linaro.org> + +description: | + Qualcomm camera clock control module provides the clocks, resets and power + domains on SM6350. + + See also:: include/dt-bindings/clock/qcom,sm6350-camcc.h + +properties: + compatible: + const: qcom,sm6350-camcc + + clocks: + items: + - description: Board XO source + + reg: + maxItems: 1 + +required: + - compatible + - clocks + +allOf: + - $ref: qcom,gcc.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@ad00000 { + compatible = "qcom,sm6350-camcc"; + reg = <0x0ad00000 0x16000>; + clocks = <&rpmhcc RPMH_CXO_CLK>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8550-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8550-dispcc.yaml new file mode 100644 index 000000000000..ab25f7cbaa2e --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sm8550-dispcc.yaml @@ -0,0 +1,105 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sm8550-dispcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display Clock & Reset Controller for SM8550 + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Neil Armstrong <neil.armstrong@linaro.org> + +description: | + Qualcomm display clock control module provides the clocks, resets and power + domains on SM8550. + + See also:: include/dt-bindings/clock/qcom,sm8550-dispcc.h + +properties: + compatible: + enum: + - qcom,sm8550-dispcc + + clocks: + items: + - description: Board XO source + - description: Board Always On XO source + - description: Display's AHB clock + - description: sleep clock + - description: Byte clock from DSI PHY0 + - description: Pixel clock from DSI PHY0 + - description: Byte clock from DSI PHY1 + - description: Pixel clock from DSI PHY1 + - description: Link clock from DP PHY0 + - description: VCO DIV clock from DP PHY0 + - description: Link clock from DP PHY1 + - description: VCO DIV clock from DP PHY1 + - description: Link clock from DP PHY2 + - description: VCO DIV clock from DP PHY2 + - description: Link clock from DP PHY3 + - description: VCO DIV clock from DP PHY3 + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + + power-domains: + description: + A phandle and PM domain specifier for the MMCX power domain. + maxItems: 1 + + required-opps: + description: + A phandle to an OPP node describing required MMCX performance point. + maxItems: 1 + +required: + - compatible + - reg + - clocks + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,sm8550-gcc.h> + #include <dt-bindings/clock/qcom,rpmh.h> + #include <dt-bindings/power/qcom-rpmpd.h> + clock-controller@af00000 { + compatible = "qcom,sm8550-dispcc"; + reg = <0x0af00000 0x10000>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&rpmhcc RPMH_CXO_CLK_A>, + <&gcc GCC_DISP_AHB_CLK>, + <&sleep_clk>, + <&dsi0_phy 0>, + <&dsi0_phy 1>, + <&dsi1_phy 0>, + <&dsi1_phy 1>, + <&dp0_phy 0>, + <&dp0_phy 1>, + <&dp1_phy 0>, + <&dp1_phy 1>, + <&dp2_phy 0>, + <&dp2_phy 1>, + <&dp3_phy 0>, + <&dp3_phy 1>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + power-domains = <&rpmhpd SM8550_MMCX>; + required-opps = <&rpmhpd_opp_low_svs>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8550-tcsr.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8550-tcsr.yaml new file mode 100644 index 000000000000..1bf1a41fd89c --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sm8550-tcsr.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,sm8550-tcsr.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm TCSR Clock Controller on SM8550 + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + +description: | + Qualcomm TCSR clock control module provides the clocks, resets and + power domains on SM8550 + + See also:: include/dt-bindings/clock/qcom,sm8550-tcsr.h + +properties: + compatible: + items: + - const: qcom,sm8550-tcsr + - const: syscon + + clocks: + items: + - description: TCXO pad clock + + reg: + maxItems: 1 + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + +required: + - compatible + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + + clock-controller@1fc0000 { + compatible = "qcom,sm8550-tcsr", "syscon"; + reg = <0x1fc0000 0x30000>; + clocks = <&rpmhcc RPMH_CXO_CLK>; + #clock-cells = <1>; + #reset-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/qcom,videocc.yaml b/Documentation/devicetree/bindings/clock/qcom,videocc.yaml index e221985e743f..2b07146161b4 100644 --- a/Documentation/devicetree/bindings/clock/qcom,videocc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,videocc.yaml @@ -30,12 +30,12 @@ properties: - qcom,sm8250-videocc clocks: - items: - - description: Board XO source + minItems: 1 + maxItems: 3 clock-names: - items: - - const: bi_tcxo + minItems: 1 + maxItems: 3 '#clock-cells': const: 1 @@ -68,6 +68,57 @@ required: - '#reset-cells' - '#power-domain-cells' +allOf: + - if: + properties: + compatible: + enum: + - qcom,sc7180-videocc + - qcom,sdm845-videocc + - qcom,sm8150-videocc + then: + properties: + clocks: + items: + - description: Board XO source + clock-names: + items: + - const: bi_tcxo + + - if: + properties: + compatible: + enum: + - qcom,sc7280-videocc + then: + properties: + clocks: + items: + - description: Board XO source + - description: Board active XO source + clock-names: + items: + - const: bi_tcxo + - const: bi_tcxo_ao + + - if: + properties: + compatible: + enum: + - qcom,sm8250-videocc + then: + properties: + clocks: + items: + - description: AHB + - description: Board XO source + - description: Board active XO source + clock-names: + items: + - const: iface + - const: bi_tcxo + - const: bi_tcxo_ao + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/clock/samsung,s3c2410-clock.txt b/Documentation/devicetree/bindings/clock/samsung,s3c2410-clock.txt deleted file mode 100644 index 2632d3f13004..000000000000 --- a/Documentation/devicetree/bindings/clock/samsung,s3c2410-clock.txt +++ /dev/null @@ -1,49 +0,0 @@ -* Samsung S3C2410 Clock Controller - -The S3C2410 clock controller generates and supplies clock to various controllers -within the SoC. The clock binding described here is applicable to the s3c2410, -s3c2440 and s3c2442 SoCs in the s3c24x family. - -Required Properties: - -- compatible: should be one of the following. - - "samsung,s3c2410-clock" - controller compatible with S3C2410 SoC. - - "samsung,s3c2440-clock" - controller compatible with S3C2440 SoC. - - "samsung,s3c2442-clock" - controller compatible with S3C2442 SoC. -- reg: physical base address of the controller and length of memory mapped - region. -- #clock-cells: should be 1. - -Each clock is assigned an identifier and client nodes can use this identifier -to specify the clock which they consume. Some of the clocks are available only -on a particular SoC. - -All available clocks are defined as preprocessor macros in -dt-bindings/clock/s3c2410.h header and can be used in device -tree sources. - -External clocks: - -The xti clock used as input for the plls is generated outside the SoC. It is -expected that is are defined using standard clock bindings with a -clock-output-names value of "xti". - -Example: Clock controller node: - - clocks: clock-controller@4c000000 { - compatible = "samsung,s3c2410-clock"; - reg = <0x4c000000 0x20>; - #clock-cells = <1>; - }; - -Example: UART controller node that consumes the clock generated by the clock - controller (refer to the standard clock bindings for information about - "clocks" and "clock-names" properties): - - serial@50004000 { - compatible = "samsung,s3c2440-uart"; - reg = <0x50004000 0x4000>; - interrupts = <1 23 3 4>, <1 23 4 4>; - clock-names = "uart", "clk_uart_baud2"; - clocks = <&clocks PCLK_UART0>, <&clocks PCLK_UART0>; - }; diff --git a/Documentation/devicetree/bindings/clock/samsung,s3c2412-clock.txt b/Documentation/devicetree/bindings/clock/samsung,s3c2412-clock.txt deleted file mode 100644 index 21a8c23e658f..000000000000 --- a/Documentation/devicetree/bindings/clock/samsung,s3c2412-clock.txt +++ /dev/null @@ -1,49 +0,0 @@ -* Samsung S3C2412 Clock Controller - -The S3C2412 clock controller generates and supplies clock to various controllers -within the SoC. The clock binding described here is applicable to the s3c2412 -and s3c2413 SoCs in the s3c24x family. - -Required Properties: - -- compatible: should be "samsung,s3c2412-clock" -- reg: physical base address of the controller and length of memory mapped - region. -- #clock-cells: should be 1. - -Each clock is assigned an identifier and client nodes can use this identifier -to specify the clock which they consume. Some of the clocks are available only -on a particular SoC. - -All available clocks are defined as preprocessor macros in -dt-bindings/clock/s3c2412.h header and can be used in device -tree sources. - -External clocks: - -There are several clocks that are generated outside the SoC. It is expected -that they are defined using standard clock bindings with following -clock-output-names: - - "xti" - crystal input - required, - - "ext" - external clock source - optional, - -Example: Clock controller node: - - clocks: clock-controller@4c000000 { - compatible = "samsung,s3c2412-clock"; - reg = <0x4c000000 0x20>; - #clock-cells = <1>; - }; - -Example: UART controller node that consumes the clock generated by the clock - controller (refer to the standard clock bindings for information about - "clocks" and "clock-names" properties): - - serial@50004000 { - compatible = "samsung,s3c2412-uart"; - reg = <0x50004000 0x4000>; - interrupts = <1 23 3 4>, <1 23 4 4>; - clock-names = "uart", "clk_uart_baud2", "clk_uart_baud3"; - clocks = <&clocks PCLK_UART0>, <&clocks PCLK_UART0>, - <&clocks SCLK_UART>; - }; diff --git a/Documentation/devicetree/bindings/clock/samsung,s3c2443-clock.txt b/Documentation/devicetree/bindings/clock/samsung,s3c2443-clock.txt deleted file mode 100644 index 985c0f574e9a..000000000000 --- a/Documentation/devicetree/bindings/clock/samsung,s3c2443-clock.txt +++ /dev/null @@ -1,55 +0,0 @@ -* Samsung S3C2443 Clock Controller - -The S3C2443 clock controller generates and supplies clock to various controllers -within the SoC. The clock binding described here is applicable to all SoCs in -the s3c24x family starting with the s3c2443. - -Required Properties: - -- compatible: should be one of the following. - - "samsung,s3c2416-clock" - controller compatible with S3C2416 SoC. - - "samsung,s3c2443-clock" - controller compatible with S3C2443 SoC. - - "samsung,s3c2450-clock" - controller compatible with S3C2450 SoC. -- reg: physical base address of the controller and length of memory mapped - region. -- #clock-cells: should be 1. - -Each clock is assigned an identifier and client nodes can use this identifier -to specify the clock which they consume. Some of the clocks are available only -on a particular SoC. - -All available clocks are defined as preprocessor macros in -dt-bindings/clock/s3c2443.h header and can be used in device -tree sources. - -External clocks: - -There are several clocks that are generated outside the SoC. It is expected -that they are defined using standard clock bindings with following -clock-output-names: - - "xti" - crystal input - required, - - "ext" - external clock source - optional, - - "ext_i2s" - external I2S clock - optional, - - "ext_uart" - external uart clock - optional, - -Example: Clock controller node: - - clocks: clock-controller@4c000000 { - compatible = "samsung,s3c2416-clock"; - reg = <0x4c000000 0x40>; - #clock-cells = <1>; - }; - -Example: UART controller node that consumes the clock generated by the clock - controller (refer to the standard clock bindings for information about - "clocks" and "clock-names" properties): - - serial@50004000 { - compatible = "samsung,s3c2440-uart"; - reg = <0x50004000 0x4000>; - interrupts = <1 23 3 4>, <1 23 4 4>; - clock-names = "uart", "clk_uart_baud2", - "clk_uart_baud3"; - clocks = <&clocks PCLK_UART0>, <&clocks PCLK_UART0>, - <&clocks SCLK_UART>; - }; diff --git a/Documentation/devicetree/bindings/clock/sifive/fu540-prci.yaml b/Documentation/devicetree/bindings/clock/sifive/fu540-prci.yaml index c3be1b600007..c79e752283aa 100644 --- a/Documentation/devicetree/bindings/clock/sifive/fu540-prci.yaml +++ b/Documentation/devicetree/bindings/clock/sifive/fu540-prci.yaml @@ -8,7 +8,6 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: SiFive FU540 Power Reset Clock Interrupt Controller (PRCI) maintainers: - - Sagar Kadam <sagar.kadam@sifive.com> - Paul Walmsley <paul.walmsley@sifive.com> description: diff --git a/Documentation/devicetree/bindings/clock/socionext,uniphier-clock.yaml b/Documentation/devicetree/bindings/clock/socionext,uniphier-clock.yaml index 9a0cc7341630..4e82582fb2f3 100644 --- a/Documentation/devicetree/bindings/clock/socionext,uniphier-clock.yaml +++ b/Documentation/devicetree/bindings/clock/socionext,uniphier-clock.yaml @@ -61,40 +61,7 @@ required: examples: - | - sysctrl@61840000 { - compatible = "socionext,uniphier-sysctrl", "simple-mfd", "syscon"; - reg = <0x61840000 0x4000>; - - clock { - compatible = "socionext,uniphier-ld11-clock"; - #clock-cells = <1>; - }; - - // other nodes ... - }; - - - | - mioctrl@59810000 { - compatible = "socionext,uniphier-mioctrl", "simple-mfd", "syscon"; - reg = <0x59810000 0x800>; - - clock { - compatible = "socionext,uniphier-ld11-mio-clock"; - #clock-cells = <1>; - }; - - // other nodes ... - }; - - - | - perictrl@59820000 { - compatible = "socionext,uniphier-perictrl", "simple-mfd", "syscon"; - reg = <0x59820000 0x200>; - - clock { - compatible = "socionext,uniphier-ld11-peri-clock"; - #clock-cells = <1>; - }; - - // other nodes ... + clock-controller { + compatible = "socionext,uniphier-ld11-clock"; + #clock-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml b/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml index 903b31129f01..e4aa8c67d532 100644 --- a/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml @@ -26,8 +26,13 @@ properties: items: - enum: - qcom,qdu1000-cpufreq-epss + - qcom,sc7280-cpufreq-epss + - qcom,sc8280xp-cpufreq-epss - qcom,sm6375-cpufreq-epss - qcom,sm8250-cpufreq-epss + - qcom,sm8350-cpufreq-epss + - qcom,sm8450-cpufreq-epss + - qcom,sm8550-cpufreq-epss - const: qcom,cpufreq-epss reg: @@ -54,6 +59,17 @@ properties: - const: xo - const: alternate + interrupts: + minItems: 1 + maxItems: 3 + + interrupt-names: + minItems: 1 + items: + - const: dcvsh-irq-0 + - const: dcvsh-irq-1 + - const: dcvsh-irq-2 + '#freq-domain-cells': const: 1 diff --git a/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml b/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml index 9c086eac6ca7..6f5e7904181f 100644 --- a/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml +++ b/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml @@ -17,6 +17,9 @@ description: | on the CPU OPP in use. The CPUFreq driver sets the CPR power domain level according to the required OPPs defined in the CPU OPP tables. + For old implementation efuses are parsed to select the correct opp table and + voltage and CPR is not supported/used. + select: properties: compatible: @@ -33,37 +36,65 @@ select: required: - compatible -properties: - cpus: - type: object - - patternProperties: - '^cpu@[0-9a-f]+$': - type: object - - properties: - power-domains: - maxItems: 1 - - power-domain-names: - items: - - const: cpr - - required: - - power-domains - - power-domain-names - patternProperties: '^opp-table(-[a-z0-9]+)?$': - if: + allOf: + - if: + properties: + compatible: + const: operating-points-v2-kryo-cpu + then: + $ref: /schemas/opp/opp-v2-kryo-cpu.yaml# + + - if: + properties: + compatible: + const: operating-points-v2-qcom-level + then: + $ref: /schemas/opp/opp-v2-qcom-level.yaml# + + unevaluatedProperties: false + +allOf: + - if: properties: compatible: - const: operating-points-v2-kryo-cpu + contains: + enum: + - qcom,qcs404 + then: + properties: + cpus: + type: object + + patternProperties: + '^cpu@[0-9a-f]+$': + type: object + + properties: + power-domains: + maxItems: 1 + + power-domain-names: + items: + - const: cpr + + required: + - power-domains + - power-domain-names + patternProperties: - '^opp-?[0-9]+$': - required: - - required-opps + '^opp-table(-[a-z0-9]+)?$': + if: + properties: + compatible: + const: operating-points-v2-kryo-cpu + then: + patternProperties: + '^opp-?[0-9]+$': + required: + - required-opps additionalProperties: true diff --git a/Documentation/devicetree/bindings/crypto/allwinner,sun8i-ce.yaml b/Documentation/devicetree/bindings/crypto/allwinner,sun8i-ce.yaml index 026a9f9e1aeb..4287678aa79f 100644 --- a/Documentation/devicetree/bindings/crypto/allwinner,sun8i-ce.yaml +++ b/Documentation/devicetree/bindings/crypto/allwinner,sun8i-ce.yaml @@ -14,6 +14,7 @@ properties: enum: - allwinner,sun8i-h3-crypto - allwinner,sun8i-r40-crypto + - allwinner,sun20i-d1-crypto - allwinner,sun50i-a64-crypto - allwinner,sun50i-h5-crypto - allwinner,sun50i-h6-crypto @@ -29,6 +30,7 @@ properties: - description: Bus clock - description: Module clock - description: MBus clock + - description: TRNG clock (RC oscillator) minItems: 2 clock-names: @@ -36,6 +38,7 @@ properties: - const: bus - const: mod - const: ram + - const: trng minItems: 2 resets: @@ -44,19 +47,33 @@ properties: if: properties: compatible: - const: allwinner,sun50i-h6-crypto + enum: + - allwinner,sun20i-d1-crypto then: properties: clocks: - minItems: 3 + minItems: 4 clock-names: - minItems: 3 + minItems: 4 else: - properties: - clocks: - maxItems: 2 - clock-names: - maxItems: 2 + if: + properties: + compatible: + const: allwinner,sun50i-h6-crypto + then: + properties: + clocks: + minItems: 3 + maxItems: 3 + clock-names: + minItems: 3 + maxItems: 3 + else: + properties: + clocks: + maxItems: 2 + clock-names: + maxItems: 2 required: - compatible diff --git a/Documentation/devicetree/bindings/crypto/aspeed,ast2600-acry.yaml b/Documentation/devicetree/bindings/crypto/aspeed,ast2600-acry.yaml new file mode 100644 index 000000000000..b18f178aac06 --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/aspeed,ast2600-acry.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/crypto/aspeed,ast2600-acry.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ASPEED ACRY ECDSA/RSA Hardware Accelerator Engines + +maintainers: + - Neal Liu <neal_liu@aspeedtech.com> + +description: + The ACRY ECDSA/RSA engines is designed to accelerate the throughput + of ECDSA/RSA signature and verification. Basically, ACRY can be + divided into two independent engines - ECC Engine and RSA Engine. + +properties: + compatible: + enum: + - aspeed,ast2600-acry + + reg: + items: + - description: acry base address & size + - description: acry sram base address & size + + clocks: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/ast2600-clock.h> + acry: crypto@1e6fa000 { + compatible = "aspeed,ast2600-acry"; + reg = <0x1e6fa000 0x400>, <0x1e710000 0x1800>; + interrupts = <160>; + clocks = <&syscon ASPEED_CLK_GATE_RSACLK>; + }; diff --git a/Documentation/devicetree/bindings/crypto/atmel,at91sam9g46-aes.yaml b/Documentation/devicetree/bindings/crypto/atmel,at91sam9g46-aes.yaml index 0ccaab16dc61..0b7383b3106b 100644 --- a/Documentation/devicetree/bindings/crypto/atmel,at91sam9g46-aes.yaml +++ b/Documentation/devicetree/bindings/crypto/atmel,at91sam9g46-aes.yaml @@ -8,7 +8,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Atmel Advanced Encryption Standard (AES) HW cryptographic accelerator maintainers: - - Tudor Ambarus <tudor.ambarus@microchip.com> + - Tudor Ambarus <tudor.ambarus@linaro.org> properties: compatible: diff --git a/Documentation/devicetree/bindings/crypto/atmel,at91sam9g46-sha.yaml b/Documentation/devicetree/bindings/crypto/atmel,at91sam9g46-sha.yaml index 5163c51b4547..ee2ffb034325 100644 --- a/Documentation/devicetree/bindings/crypto/atmel,at91sam9g46-sha.yaml +++ b/Documentation/devicetree/bindings/crypto/atmel,at91sam9g46-sha.yaml @@ -8,7 +8,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Atmel Secure Hash Algorithm (SHA) HW cryptographic accelerator maintainers: - - Tudor Ambarus <tudor.ambarus@microchip.com> + - Tudor Ambarus <tudor.ambarus@linaro.org> properties: compatible: diff --git a/Documentation/devicetree/bindings/crypto/atmel,at91sam9g46-tdes.yaml b/Documentation/devicetree/bindings/crypto/atmel,at91sam9g46-tdes.yaml index fcc5adf03cad..3d6ed24b1b00 100644 --- a/Documentation/devicetree/bindings/crypto/atmel,at91sam9g46-tdes.yaml +++ b/Documentation/devicetree/bindings/crypto/atmel,at91sam9g46-tdes.yaml @@ -8,7 +8,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Atmel Triple Data Encryption Standard (TDES) HW cryptographic accelerator maintainers: - - Tudor Ambarus <tudor.ambarus@microchip.com> + - Tudor Ambarus <tudor.ambarus@linaro.org> properties: compatible: diff --git a/Documentation/devicetree/bindings/crypto/st,stm32-hash.yaml b/Documentation/devicetree/bindings/crypto/st,stm32-hash.yaml index 4ccb335e8063..b767ec72a999 100644 --- a/Documentation/devicetree/bindings/crypto/st,stm32-hash.yaml +++ b/Documentation/devicetree/bindings/crypto/st,stm32-hash.yaml @@ -6,12 +6,18 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: STMicroelectronics STM32 HASH +description: The STM32 HASH block is built on the HASH block found in + the STn8820 SoC introduced in 2007, and subsequently used in the U8500 + SoC in 2010. + maintainers: - Lionel Debieve <lionel.debieve@foss.st.com> properties: compatible: enum: + - st,stn8820-hash + - stericsson,ux500-hash - st,stm32f456-hash - st,stm32f756-hash @@ -41,11 +47,26 @@ properties: maximum: 2 default: 0 + power-domains: + maxItems: 1 + required: - compatible - reg - clocks - - interrupts + +allOf: + - if: + properties: + compatible: + items: + const: stericsson,ux500-hash + then: + properties: + interrupts: false + else: + required: + - interrupts additionalProperties: false diff --git a/Documentation/devicetree/bindings/display/bridge/cdns,dsi.txt b/Documentation/devicetree/bindings/display/bridge/cdns,dsi.txt deleted file mode 100644 index 525a4bfd8634..000000000000 --- a/Documentation/devicetree/bindings/display/bridge/cdns,dsi.txt +++ /dev/null @@ -1,112 +0,0 @@ -Cadence DSI bridge -================== - -The Cadence DSI bridge is a DPI to DSI bridge supporting up to 4 DSI lanes. - -Required properties: -- compatible: should be set to "cdns,dsi". -- reg: physical base address and length of the controller's registers. -- interrupts: interrupt line connected to the DSI bridge. -- clocks: DSI bridge clocks. -- clock-names: must contain "dsi_p_clk" and "dsi_sys_clk". -- phys: phandle link to the MIPI D-PHY controller. -- phy-names: must contain "dphy". -- #address-cells: must be set to 1. -- #size-cells: must be set to 0. - -Optional properties: -- resets: DSI reset lines. -- reset-names: can contain "dsi_p_rst". - -Required subnodes: -- ports: Ports as described in Documentation/devicetree/bindings/graph.txt. - 2 ports are available: - * port 0: this port is only needed if some of your DSI devices are - controlled through an external bus like I2C or SPI. Can have at - most 4 endpoints. The endpoint number is directly encoding the - DSI virtual channel used by this device. - * port 1: represents the DPI input. - Other ports will be added later to support the new kind of inputs. - -- one subnode per DSI device connected on the DSI bus. Each DSI device should - contain a reg property encoding its virtual channel. - -Example: - dsi0: dsi@fd0c0000 { - compatible = "cdns,dsi"; - reg = <0x0 0xfd0c0000 0x0 0x1000>; - clocks = <&pclk>, <&sysclk>; - clock-names = "dsi_p_clk", "dsi_sys_clk"; - interrupts = <1>; - phys = <&dphy0>; - phy-names = "dphy"; - #address-cells = <1>; - #size-cells = <0>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@1 { - reg = <1>; - dsi0_dpi_input: endpoint { - remote-endpoint = <&xxx_dpi_output>; - }; - }; - }; - - panel: dsi-dev@0 { - compatible = "<vendor,panel>"; - reg = <0>; - }; - }; - -or - - dsi0: dsi@fd0c0000 { - compatible = "cdns,dsi"; - reg = <0x0 0xfd0c0000 0x0 0x1000>; - clocks = <&pclk>, <&sysclk>; - clock-names = "dsi_p_clk", "dsi_sys_clk"; - interrupts = <1>; - phys = <&dphy1>; - phy-names = "dphy"; - #address-cells = <1>; - #size-cells = <0>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - #address-cells = <1>; - #size-cells = <0>; - - dsi0_output: endpoint@0 { - reg = <0>; - remote-endpoint = <&dsi_panel_input>; - }; - }; - - port@1 { - reg = <1>; - dsi0_dpi_input: endpoint { - remote-endpoint = <&xxx_dpi_output>; - }; - }; - }; - }; - - i2c@xxx { - panel: panel@59 { - compatible = "<vendor,panel>"; - reg = <0x59>; - - port { - dsi_panel_input: endpoint { - remote-endpoint = <&dsi0_output>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/display/bridge/cdns,dsi.yaml b/Documentation/devicetree/bindings/display/bridge/cdns,dsi.yaml new file mode 100644 index 000000000000..23060324d16e --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/cdns,dsi.yaml @@ -0,0 +1,180 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/cdns,dsi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cadence DSI bridge + +maintainers: + - Boris Brezillon <boris.brezillon@bootlin.com> + +description: | + CDNS DSI is a bridge device which converts DPI to DSI + +properties: + compatible: + enum: + - cdns,dsi + - ti,j721e-dsi + + reg: + minItems: 1 + items: + - description: + Register block for controller's registers. + - description: + Register block for wrapper settings registers in case of TI J7 SoCs. + + clocks: + items: + - description: PSM clock, used by the IP + - description: sys clock, used by the IP + + clock-names: + items: + - const: dsi_p_clk + - const: dsi_sys_clk + + phys: + maxItems: 1 + + phy-names: + const: dphy + + interrupts: + maxItems: 1 + + resets: + maxItems: 1 + + reset-names: + const: dsi_p_rst + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: + Output port representing the DSI output. It can have + at most 4 endpoints. The endpoint number is directly encoding + the DSI virtual channel used by this device. + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: + Input port representing the DPI input. + + required: + - port@1 + +allOf: + - $ref: ../dsi-controller.yaml# + + - if: + properties: + compatible: + contains: + const: ti,j721e-dsi + then: + properties: + reg: + minItems: 2 + maxItems: 2 + power-domains: + maxItems: 1 + else: + properties: + reg: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - phys + - phy-names + - ports + +unevaluatedProperties: false + +examples: + - | + bus { + #address-cells = <2>; + #size-cells = <2>; + + dsi@fd0c0000 { + compatible = "cdns,dsi"; + reg = <0x0 0xfd0c0000 0x0 0x1000>; + clocks = <&pclk>, <&sysclk>; + clock-names = "dsi_p_clk", "dsi_sys_clk"; + interrupts = <1>; + phys = <&dphy0>; + phy-names = "dphy"; + + #address-cells = <1>; + #size-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@1 { + reg = <1>; + endpoint { + remote-endpoint = <&xxx_dpi_output>; + }; + }; + }; + + panel@0 { + compatible = "panasonic,vvx10f034n00"; + reg = <0>; + power-supply = <&vcc_lcd_reg>; + }; + }; + }; + + - | + bus { + #address-cells = <2>; + #size-cells = <2>; + + dsi@fd0c0000 { + compatible = "cdns,dsi"; + reg = <0x0 0xfd0c0000 0x0 0x1000>; + clocks = <&pclk>, <&sysclk>; + clock-names = "dsi_p_clk", "dsi_sys_clk"; + interrupts = <1>; + phys = <&dphy1>; + phy-names = "dphy"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + #address-cells = <1>; + #size-cells = <0>; + + endpoint@0 { + reg = <0>; + remote-endpoint = <&dsi_panel_input>; + }; + }; + + port@1 { + reg = <1>; + endpoint { + remote-endpoint = <&xxx_dpi_output>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/bridge/fsl,ldb.yaml b/Documentation/devicetree/bindings/display/bridge/fsl,ldb.yaml index b19be0804abe..6e0e3ba9b49e 100644 --- a/Documentation/devicetree/bindings/display/bridge/fsl,ldb.yaml +++ b/Documentation/devicetree/bindings/display/bridge/fsl,ldb.yaml @@ -16,7 +16,9 @@ description: | properties: compatible: - const: fsl,imx8mp-ldb + enum: + - fsl,imx8mp-ldb + - fsl,imx93-ldb clocks: maxItems: 1 @@ -57,6 +59,18 @@ required: - clocks - ports +allOf: + - if: + properties: + compatible: + contains: + const: fsl,imx93-ldb + then: + properties: + ports: + properties: + port@2: false + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/display/bridge/ite,it6505.yaml b/Documentation/devicetree/bindings/display/bridge/ite,it6505.yaml index b697c42399ea..c9a882ee6d98 100644 --- a/Documentation/devicetree/bindings/display/bridge/ite,it6505.yaml +++ b/Documentation/devicetree/bindings/display/bridge/ite,it6505.yaml @@ -52,9 +52,49 @@ properties: maxItems: 1 description: extcon specifier for the Power Delivery - port: - $ref: /schemas/graph.yaml#/properties/port - description: A port node pointing to DPI host port node + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: A port node pointing to DPI host port node + + properties: + endpoint: + $ref: /schemas/graph.yaml#/$defs/endpoint-base + unevaluatedProperties: false + + properties: + link-frequencies: + minItems: 1 + maxItems: 1 + description: Allowed max link frequencies in Hz + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: Video port for DP output + + properties: + endpoint: + $ref: /schemas/graph.yaml#/$defs/endpoint-base + unevaluatedProperties: false + + properties: + data-lanes: + minItems: 1 + uniqueItems: true + items: + - enum: [ 0, 1 ] + - const: 1 + - const: 2 + - const: 3 + + required: + - port@0 + - port@1 required: - compatible @@ -63,6 +103,7 @@ required: - interrupts - reset-gpios - extcon + - ports additionalProperties: false @@ -85,9 +126,24 @@ examples: reset-gpios = <&pio 179 1>; extcon = <&usbc_extcon>; - port { - it6505_in: endpoint { - remote-endpoint = <&dpi_out>; + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + it6505_in: endpoint { + remote-endpoint = <&dpi_out>; + link-frequencies = /bits/ 64 <150000000>; + }; + }; + + port@1 { + reg = <1>; + it6505_out: endpoint { + remote-endpoint = <&dp_in>; + data-lanes = <0 1>; + }; }; }; }; diff --git a/Documentation/devicetree/bindings/display/bridge/ite,it66121.yaml b/Documentation/devicetree/bindings/display/bridge/ite,it66121.yaml index d3454da1247a..a7eb2603691f 100644 --- a/Documentation/devicetree/bindings/display/bridge/ite,it66121.yaml +++ b/Documentation/devicetree/bindings/display/bridge/ite,it66121.yaml @@ -17,7 +17,9 @@ description: | properties: compatible: - const: ite,it66121 + enum: + - ite,it66121 + - ite,it6610 reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,dsi-csi2-tx.yaml b/Documentation/devicetree/bindings/display/bridge/renesas,dsi-csi2-tx.yaml index afeeb967393d..d33026f85e19 100644 --- a/Documentation/devicetree/bindings/display/bridge/renesas,dsi-csi2-tx.yaml +++ b/Documentation/devicetree/bindings/display/bridge/renesas,dsi-csi2-tx.yaml @@ -11,13 +11,14 @@ maintainers: description: | This binding describes the MIPI DSI/CSI-2 encoder embedded in the Renesas - R-Car V3U SoC. The encoder can operate in either DSI or CSI-2 mode, with up + R-Car Gen4 SoCs. The encoder can operate in either DSI or CSI-2 mode, with up to four data lanes. properties: compatible: enum: - renesas,r8a779a0-dsi-csi2-tx # for V3U + - renesas,r8a779g0-dsi-csi2-tx # for V4H reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,dsi.yaml b/Documentation/devicetree/bindings/display/bridge/renesas,dsi.yaml index 131d5b63ec4f..e08c24633926 100644 --- a/Documentation/devicetree/bindings/display/bridge/renesas,dsi.yaml +++ b/Documentation/devicetree/bindings/display/bridge/renesas,dsi.yaml @@ -22,6 +22,7 @@ properties: items: - enum: - renesas,r9a07g044-mipi-dsi # RZ/G2{L,LC} + - renesas,r9a07g054-mipi-dsi # RZ/V2L - const: renesas,rzg2l-mipi-dsi reg: diff --git a/Documentation/devicetree/bindings/display/bridge/sil,sii8620.yaml b/Documentation/devicetree/bindings/display/bridge/sil,sii8620.yaml new file mode 100644 index 000000000000..6d1a36b76fcb --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/sil,sii8620.yaml @@ -0,0 +1,108 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/sil,sii8620.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Silicon Image SiI8620 HDMI/MHL bridge + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +properties: + compatible: + const: sil,sii8620 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: xtal + + cvcc10-supply: + description: Digital Core Supply Voltage (1.0V) + + interrupts: + maxItems: 1 + + iovcc18-supply: + description: I/O Supply Voltage (1.8V) + + reset-gpios: + maxItems: 1 + + ports: + $ref: /schemas/graph.yaml#/properties/ports + unevaluatedProperties: false + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: + Video port for HDMI (encoder) input + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: + MHL to connector port + + required: + - port@0 + - port@1 + +required: + - compatible + - reg + - clocks + - cvcc10-supply + - interrupts + - iovcc18-supply + - reset-gpios + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + bridge@39 { + reg = <0x39>; + compatible = "sil,sii8620"; + cvcc10-supply = <&ldo36_reg>; + iovcc18-supply = <&ldo34_reg>; + interrupt-parent = <&gpf0>; + interrupts = <2 IRQ_TYPE_LEVEL_HIGH>; + reset-gpios = <&gpv7 0 GPIO_ACTIVE_LOW>; + clocks = <&pmu_system_controller 0>; + clock-names = "xtal"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + mhl_to_hdmi: endpoint { + remote-endpoint = <&hdmi_to_mhl>; + }; + }; + + port@1 { + reg = <1>; + mhl_to_musb_con: endpoint { + remote-endpoint = <&musb_con_to_mhl>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/bridge/sil-sii8620.txt b/Documentation/devicetree/bindings/display/bridge/sil-sii8620.txt deleted file mode 100644 index b05052f7d62f..000000000000 --- a/Documentation/devicetree/bindings/display/bridge/sil-sii8620.txt +++ /dev/null @@ -1,33 +0,0 @@ -Silicon Image SiI8620 HDMI/MHL bridge bindings - -Required properties: - - compatible: "sil,sii8620" - - reg: i2c address of the bridge - - cvcc10-supply: Digital Core Supply Voltage (1.0V) - - iovcc18-supply: I/O Supply Voltage (1.8V) - - interrupts: interrupt specifier of INT pin - - reset-gpios: gpio specifier of RESET pin - - clocks, clock-names: specification and name of "xtal" clock - - video interfaces: Device node can contain video interface port - node for HDMI encoder according to [1]. - -[1]: Documentation/devicetree/bindings/media/video-interfaces.txt - -Example: - sii8620@39 { - reg = <0x39>; - compatible = "sil,sii8620"; - cvcc10-supply = <&ldo36_reg>; - iovcc18-supply = <&ldo34_reg>; - interrupt-parent = <&gpf0>; - interrupts = <2 0>; - reset-gpio = <&gpv7 0 0>; - clocks = <&pmu_system_controller 0>; - clock-names = "xtal"; - - port { - mhl_to_hdmi: endpoint { - remote-endpoint = <&hdmi_to_mhl>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,aal.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,aal.yaml index d4d585485e7b..92741486c24d 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,aal.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,aal.yaml @@ -31,6 +31,7 @@ properties: - items: - enum: - mediatek,mt8186-disp-aal + - mediatek,mt8188-disp-aal - mediatek,mt8192-disp-aal - mediatek,mt8195-disp-aal - const: mediatek,mt8183-disp-aal diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,ccorr.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,ccorr.yaml index 63fb02014a56..b04820c95b22 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,ccorr.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,ccorr.yaml @@ -27,12 +27,13 @@ properties: - const: mediatek,mt8192-disp-ccorr - items: - enum: + - mediatek,mt8188-disp-ccorr - mediatek,mt8195-disp-ccorr - const: mediatek,mt8192-disp-ccorr - items: - enum: - mediatek,mt8186-disp-ccorr - - const: mediatek,mt8183-disp-ccorr + - const: mediatek,mt8192-disp-ccorr reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,color.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,color.yaml index d2f89ee7996f..62306c88f485 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,color.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,color.yaml @@ -37,6 +37,7 @@ properties: - enum: - mediatek,mt8183-disp-color - mediatek,mt8186-disp-color + - mediatek,mt8188-disp-color - mediatek,mt8192-disp-color - mediatek,mt8195-disp-color - const: mediatek,mt8173-disp-color diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,dither.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,dither.yaml index 8ad8187c02d1..5c7445c174e5 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,dither.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,dither.yaml @@ -27,6 +27,7 @@ properties: - items: - enum: - mediatek,mt8186-disp-dither + - mediatek,mt8188-disp-dither - mediatek,mt8192-disp-dither - mediatek,mt8195-disp-dither - const: mediatek,mt8183-disp-dither diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,gamma.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,gamma.yaml index a89ea0ea7542..a5c6a91fac71 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,gamma.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,gamma.yaml @@ -28,6 +28,7 @@ properties: - items: - enum: - mediatek,mt8186-disp-gamma + - mediatek,mt8188-disp-gamma - mediatek,mt8192-disp-gamma - mediatek,mt8195-disp-gamma - const: mediatek,mt8183-disp-gamma diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,ovl.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,ovl.yaml index a2a27d0ca038..065e526f950e 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,ovl.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,ovl.yaml @@ -36,6 +36,7 @@ properties: - const: mediatek,mt2701-disp-ovl - items: - enum: + - mediatek,mt8188-disp-ovl - mediatek,mt8195-disp-ovl - const: mediatek,mt8183-disp-ovl - items: diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,postmask.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,postmask.yaml index 654080bfbdfb..27de64495401 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,postmask.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,postmask.yaml @@ -26,6 +26,7 @@ properties: - items: - enum: - mediatek,mt8186-disp-postmask + - mediatek,mt8188-disp-postmask - const: mediatek,mt8192-disp-postmask reg: diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,rdma.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,rdma.yaml index 0882ae86e6c4..3ade2ece3fed 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,rdma.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,rdma.yaml @@ -33,6 +33,10 @@ properties: - const: mediatek,mt8195-disp-rdma - items: - enum: + - mediatek,mt8188-disp-rdma + - const: mediatek,mt8195-disp-rdma + - items: + - enum: - mediatek,mt7623-disp-rdma - mediatek,mt2712-disp-rdma - const: mediatek,mt2701-disp-rdma diff --git a/Documentation/devicetree/bindings/display/msm/dp-controller.yaml b/Documentation/devicetree/bindings/display/msm/dp-controller.yaml index f2515af8256f..0e8d8df686dc 100644 --- a/Documentation/devicetree/bindings/display/msm/dp-controller.yaml +++ b/Documentation/devicetree/bindings/display/msm/dp-controller.yaml @@ -21,6 +21,9 @@ properties: - qcom,sc7280-edp - qcom,sc8180x-dp - qcom,sc8180x-edp + - qcom,sc8280xp-dp + - qcom,sc8280xp-edp + - qcom,sdm845-dp - qcom,sm8350-dp reg: @@ -68,8 +71,7 @@ properties: items: - const: dp - operating-points-v2: - maxItems: 1 + operating-points-v2: true opp-table: true @@ -81,6 +83,7 @@ properties: data-lanes: $ref: /schemas/types.yaml#/definitions/uint32-array + deprecated: true minItems: 1 maxItems: 4 items: @@ -102,8 +105,28 @@ properties: description: Input endpoint of the controller port@1: - $ref: /schemas/graph.yaml#/properties/port + $ref: /schemas/graph.yaml#/$defs/port-base description: Output endpoint of the controller + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + properties: + data-lanes: + minItems: 1 + maxItems: 4 + items: + enum: [ 0, 1, 2, 3 ] + + link-frequencies: + minItems: 1 + maxItems: 4 + items: + enum: [ 1620000000, 2700000000, 5400000000, 8100000000 ] + + required: + - port@0 + - port@1 required: - compatible @@ -127,11 +150,10 @@ allOf: enum: - qcom,sc7280-edp - qcom,sc8180x-edp + - qcom,sc8280xp-edp then: properties: "#sound-dai-cells": false - reg: - maxItems: 4 else: properties: aux-bus: false @@ -193,6 +215,8 @@ examples: reg = <1>; endpoint { remote-endpoint = <&typec>; + data-lanes = <0 1>; + link-frequencies = /bits/ 64 <1620000000 2700000000 5400000000 8100000000>; }; }; }; diff --git a/Documentation/devicetree/bindings/display/msm/dpu-common.yaml b/Documentation/devicetree/bindings/display/msm/dpu-common.yaml index 8ffbc30c6b7f..3f953aa5e694 100644 --- a/Documentation/devicetree/bindings/display/msm/dpu-common.yaml +++ b/Documentation/devicetree/bindings/display/msm/dpu-common.yaml @@ -13,7 +13,15 @@ maintainers: description: | Common properties for QCom DPU display controller. +# Do not select this by default, otherwise it is also selected for all +# display-controller@ nodes +select: + false + properties: + $nodename: + pattern: '^display-controller@[0-9a-f]+$' + interrupts: maxItems: 1 @@ -40,10 +48,6 @@ properties: - port@0 required: - - compatible - - reg - - reg-names - - clocks - interrupts - power-domains - operating-points-v2 diff --git a/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml b/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml index f2c143730a55..e75a3efe4dac 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml @@ -9,14 +9,33 @@ title: Qualcomm Display DSI controller maintainers: - Krishna Manikandan <quic_mkrishn@quicinc.com> -allOf: - - $ref: "../dsi-controller.yaml#" - properties: compatible: - enum: - - qcom,mdss-dsi-ctrl - - qcom,dsi-ctrl-6g-qcm2290 + oneOf: + - items: + - enum: + - qcom,apq8064-dsi-ctrl + - qcom,msm8916-dsi-ctrl + - qcom,msm8953-dsi-ctrl + - qcom,msm8974-dsi-ctrl + - qcom,msm8996-dsi-ctrl + - qcom,msm8998-dsi-ctrl + - qcom,qcm2290-dsi-ctrl + - qcom,sc7180-dsi-ctrl + - qcom,sc7280-dsi-ctrl + - qcom,sdm660-dsi-ctrl + - qcom,sdm845-dsi-ctrl + - qcom,sm8150-dsi-ctrl + - qcom,sm8250-dsi-ctrl + - qcom,sm8350-dsi-ctrl + - qcom,sm8450-dsi-ctrl + - qcom,sm8550-dsi-ctrl + - const: qcom,mdss-dsi-ctrl + - items: + - enum: + - dsi-ctrl-6g-qcm2290 + - const: qcom,mdss-dsi-ctrl + deprecated: true reg: maxItems: 1 @@ -28,22 +47,23 @@ properties: maxItems: 1 clocks: - items: - - description: Display byte clock - - description: Display byte interface clock - - description: Display pixel clock - - description: Display escape clock - - description: Display AHB clock - - description: Display AXI clock + description: | + Several clocks are used, depending on the variant. Typical ones are:: + - bus:: Display AHB clock. + - byte:: Display byte clock. + - byte_intf:: Display byte interface clock. + - core:: Display core clock. + - core_mss:: Core MultiMedia SubSystem clock. + - iface:: Display AXI clock. + - mdp_core:: MDP Core clock. + - mnoc:: MNOC clock + - pixel:: Display pixel clock. + minItems: 3 + maxItems: 9 clock-names: - items: - - const: byte - - const: byte_intf - - const: pixel - - const: core - - const: iface - - const: bus + minItems: 3 + maxItems: 9 phys: maxItems: 1 @@ -52,10 +72,6 @@ properties: deprecated: true const: dsi - "#address-cells": true - - "#size-cells": true - syscon-sfpb: description: A phandle to mmss_sfpb syscon node (only for DSIv2). $ref: "/schemas/types.yaml#/definitions/phandle" @@ -67,12 +83,16 @@ properties: 2 DSI links. assigned-clocks: - maxItems: 2 + minItems: 2 + maxItems: 4 description: | Parents of "byte" and "pixel" for the given platform. + For DSIv2 platforms this should contain "byte", "esc", "src" and + "pixel_src" clocks. assigned-clock-parents: - maxItems: 2 + minItems: 2 + maxItems: 4 description: | The Byte clock and Pixel clock PLL outputs provided by a DSI PHY block. @@ -103,7 +123,7 @@ properties: properties: data-lanes: maxItems: 4 - minItems: 4 + minItems: 1 items: enum: [ 0, 1, 2, 3 ] @@ -119,7 +139,7 @@ properties: properties: data-lanes: maxItems: 4 - minItems: 4 + minItems: 1 items: enum: [ 0, 1, 2, 3 ] @@ -127,6 +147,26 @@ properties: - port@0 - port@1 + avdd-supply: + description: + Phandle to vdd regulator device node + + vcca-supply: + description: + Phandle to vdd regulator device node + + vdd-supply: + description: + VDD regulator + + vddio-supply: + description: + VDD-IO regulator + + vdda-supply: + description: + VDDA regulator + required: - compatible - reg @@ -137,11 +177,194 @@ required: - phys - assigned-clocks - assigned-clock-parents - - power-domains - - operating-points-v2 - ports -additionalProperties: false +allOf: + - $ref: ../dsi-controller.yaml# + - if: + properties: + compatible: + contains: + enum: + - qcom,apq8064-dsi-ctrl + then: + properties: + clocks: + maxItems: 7 + clock-names: + items: + - const: iface + - const: bus + - const: core_mmss + - const: src + - const: byte + - const: pixel + - const: core + + - if: + properties: + compatible: + contains: + enum: + - qcom,msm8916-dsi-ctrl + then: + properties: + clocks: + maxItems: 6 + clock-names: + items: + - const: mdp_core + - const: iface + - const: bus + - const: byte + - const: pixel + - const: core + + - if: + properties: + compatible: + contains: + enum: + - qcom,msm8953-dsi-ctrl + then: + properties: + clocks: + maxItems: 6 + clock-names: + items: + - const: mdp_core + - const: iface + - const: bus + - const: byte + - const: pixel + - const: core + + - if: + properties: + compatible: + contains: + enum: + - qcom,msm8974-dsi-ctrl + then: + properties: + clocks: + maxItems: 7 + clock-names: + items: + - const: mdp_core + - const: iface + - const: bus + - const: byte + - const: pixel + - const: core + - const: core_mmss + + - if: + properties: + compatible: + contains: + enum: + - qcom,msm8996-dsi-ctrl + then: + properties: + clocks: + maxItems: 7 + clock-names: + items: + - const: mdp_core + - const: byte + - const: iface + - const: bus + - const: core_mmss + - const: pixel + - const: core + + - if: + properties: + compatible: + contains: + enum: + - qcom,msm8998-dsi-ctrl + then: + properties: + clocks: + maxItems: 6 + clock-names: + items: + - const: byte + - const: byte_intf + - const: pixel + - const: core + - const: iface + - const: bus + + - if: + properties: + compatible: + contains: + enum: + - qcom,sc7180-dsi-ctrl + - qcom,sc7280-dsi-ctrl + - qcom,sm8150-dsi-ctrl + - qcom,sm8250-dsi-ctrl + - qcom,sm8350-dsi-ctrl + - qcom,sm8450-dsi-ctrl + - qcom,sm8550-dsi-ctrl + then: + properties: + clocks: + maxItems: 6 + clock-names: + items: + - const: byte + - const: byte_intf + - const: pixel + - const: core + - const: iface + - const: bus + + - if: + properties: + compatible: + contains: + enum: + - qcom,sdm660-dsi-ctrl + then: + properties: + clocks: + maxItems: 9 + clock-names: + items: + - const: mdp_core + - const: byte + - const: byte_intf + - const: mnoc + - const: iface + - const: bus + - const: core_mmss + - const: pixel + - const: core + + - if: + properties: + compatible: + contains: + enum: + - qcom,sdm845-dsi-ctrl + then: + properties: + clocks: + maxItems: 6 + clock-names: + items: + - const: byte + - const: byte_intf + - const: pixel + - const: core + - const: iface + - const: bus + +unevaluatedProperties: false examples: - | @@ -151,7 +374,7 @@ examples: #include <dt-bindings/power/qcom-rpmpd.h> dsi@ae94000 { - compatible = "qcom,mdss-dsi-ctrl"; + compatible = "qcom,sc7180-dsi-ctrl", "qcom,mdss-dsi-ctrl"; reg = <0x0ae94000 0x400>; reg-names = "dsi_ctrl"; diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-10nm.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-10nm.yaml index d9ad8b659f58..3ec466c3ab38 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-10nm.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-10nm.yaml @@ -69,7 +69,6 @@ required: - compatible - reg - reg-names - - vdds-supply unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.yaml index 819de5ce0bc9..a43e11d3b00d 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.yaml @@ -39,7 +39,6 @@ required: - compatible - reg - reg-names - - vcca-supply unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-28nm.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-28nm.yaml index 3d8540a06fe2..cf4a338c4661 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-28nm.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-28nm.yaml @@ -16,6 +16,7 @@ properties: compatible: enum: - qcom,dsi-phy-28nm-hpm + - qcom,dsi-phy-28nm-hpm-fam-b - qcom,dsi-phy-28nm-lp - qcom,dsi-phy-28nm-8960 @@ -34,6 +35,10 @@ properties: vddio-supply: description: Phandle to vdd-io regulator device node. + qcom,dsi-phy-regulator-ldo-mode: + type: boolean + description: Indicates if the LDO mode PHY regulator is wanted. + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-7nm.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-7nm.yaml index c851770bbdf2..8e9031bbde73 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-7nm.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-7nm.yaml @@ -18,6 +18,10 @@ properties: - qcom,dsi-phy-7nm - qcom,dsi-phy-7nm-8150 - qcom,sc7280-dsi-phy-7nm + - qcom,sm6375-dsi-phy-7nm + - qcom,sm8350-dsi-phy-5nm + - qcom,sm8450-dsi-phy-5nm + - qcom,sm8550-dsi-phy-4nm reg: items: @@ -44,7 +48,6 @@ required: - compatible - reg - reg-names - - vdds-supply unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-common.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-common.yaml index 76d40f7933dd..0f6f08890e7e 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-common.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-common.yaml @@ -4,14 +4,13 @@ $id: http://devicetree.org/schemas/display/msm/dsi-phy-common.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Description of Qualcomm Display DSI PHY common dt properties +title: Qualcomm Display DSI PHY Common Properties maintainers: - Krishna Manikandan <quic_mkrishn@quicinc.com> -description: | - This defines the DSI PHY dt properties which are common for all - dsi phy versions. +description: + Common properties for Qualcomm Display DSI PHY. properties: "#clock-cells": diff --git a/Documentation/devicetree/bindings/display/msm/gpu.yaml b/Documentation/devicetree/bindings/display/msm/gpu.yaml index c5f49842dc7b..d4191cca71fb 100644 --- a/Documentation/devicetree/bindings/display/msm/gpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/gpu.yaml @@ -89,7 +89,7 @@ properties: help bring the GPU out of secure mode. properties: memory-region: - $ref: /schemas/types.yaml#/definitions/phandle + maxItems: 1 firmware-name: description: | @@ -149,6 +149,8 @@ allOf: description: GPU 3D engine clock - const: rbbmtimer description: GPU RBBM Timer for Adreno 5xx series + - const: rbcpr + description: GPU RB Core Power Reduction clock minItems: 2 maxItems: 7 diff --git a/Documentation/devicetree/bindings/display/msm/mdp5.txt b/Documentation/devicetree/bindings/display/msm/mdp5.txt deleted file mode 100644 index 65d03c58dee6..000000000000 --- a/Documentation/devicetree/bindings/display/msm/mdp5.txt +++ /dev/null @@ -1,132 +0,0 @@ -Qualcomm adreno/snapdragon MDP5 display controller - -Description: - -This is the bindings documentation for the MDP5 display -controller found in SoCs like MSM8974, APQ8084, MSM8916, MSM8994 and MSM8996. - -MDP5: -Required properties: -- compatible: - * "qcom,mdp5" - MDP5 -- reg: Physical base address and length of the controller's registers. -- reg-names: The names of register regions. The following regions are required: - * "mdp_phys" -- interrupts: Interrupt line from MDP5 to MDSS interrupt controller. -- clocks: device clocks. See ../clocks/clock-bindings.txt for details. -- clock-names: the following clocks are required. -- * "bus" -- * "iface" -- * "core" -- * "vsync" -- ports: contains the list of output ports from MDP. These connect to interfaces - that are external to the MDP hardware, such as HDMI, DSI, EDP etc (LVDS is a - special case since it is a part of the MDP block itself). - - Each output port contains an endpoint that describes how it is connected to an - external interface. These are described by the standard properties documented - here: - Documentation/devicetree/bindings/graph.txt - Documentation/devicetree/bindings/media/video-interfaces.txt - - The availability of output ports can vary across SoC revisions: - - For MSM8974 and APQ8084: - Port 0 -> MDP_INTF0 (eDP) - Port 1 -> MDP_INTF1 (DSI1) - Port 2 -> MDP_INTF2 (DSI2) - Port 3 -> MDP_INTF3 (HDMI) - - For MSM8916: - Port 0 -> MDP_INTF1 (DSI1) - - For MSM8994 and MSM8996: - Port 0 -> MDP_INTF1 (DSI1) - Port 1 -> MDP_INTF2 (DSI2) - Port 2 -> MDP_INTF3 (HDMI) - -Optional properties: -- clock-names: the following clocks are optional: - * "lut" - * "tbu" - * "tbu_rt" - -Example: - -/ { - ... - - mdss: mdss@1a00000 { - compatible = "qcom,mdss"; - reg = <0x1a00000 0x1000>, - <0x1ac8000 0x3000>; - reg-names = "mdss_phys", "vbif_phys"; - - power-domains = <&gcc MDSS_GDSC>; - - clocks = <&gcc GCC_MDSS_AHB_CLK>, - <&gcc GCC_MDSS_AXI_CLK>, - <&gcc GCC_MDSS_VSYNC_CLK>; - clock-names = "iface", - "bus", - "vsync" - - interrupts = <0 72 0>; - - interrupt-controller; - #interrupt-cells = <1>; - - #address-cells = <1>; - #size-cells = <1>; - ranges; - - mdp: mdp@1a01000 { - compatible = "qcom,mdp5"; - reg = <0x1a01000 0x90000>; - reg-names = "mdp_phys"; - - interrupt-parent = <&mdss>; - interrupts = <0 0>; - - clocks = <&gcc GCC_MDSS_AHB_CLK>, - <&gcc GCC_MDSS_AXI_CLK>, - <&gcc GCC_MDSS_MDP_CLK>, - <&gcc GCC_MDSS_VSYNC_CLK>; - clock-names = "iface", - "bus", - "core", - "vsync"; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - mdp5_intf1_out: endpoint { - remote-endpoint = <&dsi0_in>; - }; - }; - }; - }; - - dsi0: dsi@1a98000 { - ... - ports { - ... - port@0 { - reg = <0>; - dsi0_in: endpoint { - remote-endpoint = <&mdp5_intf1_out>; - }; - }; - ... - }; - ... - }; - - dsi_phy0: dsi-phy@1a98300 { - ... - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/msm/mdss-common.yaml b/Documentation/devicetree/bindings/display/msm/mdss-common.yaml index 27d7242657b2..ccd7d6417523 100644 --- a/Documentation/devicetree/bindings/display/msm/mdss-common.yaml +++ b/Documentation/devicetree/bindings/display/msm/mdss-common.yaml @@ -15,7 +15,15 @@ description: Device tree bindings for MSM Mobile Display Subsystem(MDSS) that encapsulates sub-blocks like DPU display controller, DSI and DP interfaces etc. +# Do not select this by default, otherwise it is also selected for qcom,mdss +# devices. +select: + false + properties: + $nodename: + pattern: "^display-subsystem@[0-9a-f]+$" + reg: maxItems: 1 @@ -70,7 +78,6 @@ properties: - description: MDSS_CORE reset required: - - compatible - reg - reg-names - power-domains diff --git a/Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml b/Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml new file mode 100644 index 000000000000..ef461ad6ce4a --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml @@ -0,0 +1,156 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,mdp5.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Adreno/Snapdragon Mobile Display controller (MDP5) + +description: + MDP5 display controller found in SoCs like MSM8974, APQ8084, MSM8916, MSM8994 + and MSM8996. + +maintainers: + - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> + - Rob Clark <robdclark@gmail.com> + +properties: + compatible: + oneOf: + - const: qcom,mdp5 + deprecated: true + - items: + - enum: + - qcom,apq8084-mdp5 + - qcom,msm8916-mdp5 + - qcom,msm8917-mdp5 + - qcom,msm8953-mdp5 + - qcom,msm8974-mdp5 + - qcom,msm8976-mdp5 + - qcom,msm8994-mdp5 + - qcom,msm8996-mdp5 + - qcom,sdm630-mdp5 + - qcom,sdm660-mdp5 + - const: qcom,mdp5 + + $nodename: + pattern: '^display-controller@[0-9a-f]+$' + + reg: + maxItems: 1 + + reg-names: + items: + - const: mdp_phys + + interrupts: + maxItems: 1 + + clocks: + minItems: 4 + maxItems: 7 + + clock-names: + oneOf: + - minItems: 4 + items: + - const: iface + - const: bus + - const: core + - const: vsync + - const: lut + - const: tbu + - const: tbu_rt + #MSM8996 has additional iommu clock + - items: + - const: iface + - const: bus + - const: core + - const: iommu + - const: vsync + + interconnects: + minItems: 1 + items: + - description: Interconnect path from mdp0 (or a single mdp) port to the data bus + - description: Interconnect path from mdp1 port to the data bus + - description: Interconnect path from rotator port to the data bus + + interconnect-names: + minItems: 1 + items: + - const: mdp0-mem + - const: mdp1-mem + - const: rotator-mem + + iommus: + items: + - description: apps SMMU with the Stream-ID mask for Hard-Fail port0 + + power-domains: + maxItems: 1 + + operating-points-v2: true + opp-table: + type: object + + ports: + $ref: /schemas/graph.yaml#/properties/ports + description: > + Contains the list of output ports from DPU device. These ports + connect to interfaces that are external to the DPU hardware, + such as DSI, DP etc. MDP5 devices support up to 4 ports: + one or two DSI ports, HDMI and eDP. + + patternProperties: + "^port@[0-3]+$": + $ref: /schemas/graph.yaml#/properties/port + + # at least one port is required + required: + - port@0 + +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-msm8916.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + display-controller@1a01000 { + compatible = "qcom,mdp5"; + reg = <0x1a01000 0x90000>; + reg-names = "mdp_phys"; + + interrupt-parent = <&mdss>; + interrupts = <0>; + + clocks = <&gcc GCC_MDSS_AHB_CLK>, + <&gcc GCC_MDSS_AXI_CLK>, + <&gcc GCC_MDSS_MDP_CLK>, + <&gcc GCC_MDSS_VSYNC_CLK>; + clock-names = "iface", + "bus", + "core", + "vsync"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + endpoint { + remote-endpoint = <&dsi0_in>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,mdss.yaml index ba0460268731..20889e409430 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,mdss.yaml @@ -15,6 +15,9 @@ description: encapsulates sub-blocks like MDP5, DSI, HDMI, eDP, etc. properties: + $nodename: + pattern: "^display-subsystem@[0-9a-f]+$" + compatible: enum: - qcom,mdss @@ -44,18 +47,30 @@ properties: The MDSS power domain provided by GCC clocks: - minItems: 1 - items: - - description: Display abh clock - - description: Display axi clock - - description: Display vsync clock + oneOf: + - minItems: 3 + items: + - description: Display abh clock + - description: Display axi clock + - description: Display vsync clock + - description: Display core clock + - minItems: 1 + items: + - description: Display abh clock + - description: Display core clock clock-names: - minItems: 1 - items: - - const: iface - - const: bus - - const: vsync + oneOf: + - minItems: 3 + items: + - const: iface + - const: bus + - const: vsync + - const: core + - minItems: 1 + items: + - const: iface + - const: core "#address-cells": const: 1 @@ -84,17 +99,19 @@ required: - ranges patternProperties: - "^mdp@[1-9a-f][0-9a-f]*$": + "^display-controller@[1-9a-f][0-9a-f]*$": type: object properties: compatible: - const: qcom,mdp5 + contains: + const: qcom,mdp5 "^dsi@[1-9a-f][0-9a-f]*$": type: object properties: compatible: - const: qcom,mdss-dsi-ctrl + contains: + const: qcom,mdss-dsi-ctrl "^phy@[1-9a-f][0-9a-f]*$": type: object @@ -107,12 +124,6 @@ patternProperties: - qcom,dsi-phy-20nm - qcom,dsi-phy-28nm-hpm - qcom,dsi-phy-28nm-lp - - "^hdmi-phy@[1-9a-f][0-9a-f]*$": - type: object - properties: - compatible: - enum: - qcom,hdmi-phy-8084 - qcom,hdmi-phy-8660 - qcom,hdmi-phy-8960 @@ -137,7 +148,7 @@ examples: - | #include <dt-bindings/clock/qcom,gcc-msm8916.h> #include <dt-bindings/interrupt-controller/arm-gic.h> - mdss@1a00000 { + display-subsystem@1a00000 { compatible = "qcom,mdss"; reg = <0x1a00000 0x1000>, <0x1ac8000 0x3000>; @@ -161,8 +172,8 @@ examples: #size-cells = <1>; ranges; - mdp@1a01000 { - compatible = "qcom,mdp5"; + display-controller@1a01000 { + compatible = "qcom,msm8916-mdp5", "qcom,mdp5"; reg = <0x01a01000 0x89000>; reg-names = "mdp_phys"; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,msm8998-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,msm8998-dpu.yaml index b02adba36e9e..8d3cd46260fb 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,msm8998-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,msm8998-dpu.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/display/msm/qcom,msm8998-dpu.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Display DPU dt properties for MSM8998 target +title: Qualcomm Display DPU on MSM8998 maintainers: - AngeloGioacchino Del Regno <angelogioacchino.delregno@somainline.org> @@ -13,8 +13,7 @@ $ref: /schemas/display/msm/dpu-common.yaml# properties: compatible: - items: - - const: qcom,msm8998-dpu + const: qcom,msm8998-dpu reg: items: @@ -46,6 +45,13 @@ properties: - const: core - const: vsync +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/display/msm/qcom,msm8998-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,msm8998-mdss.yaml index cf52ff77a41a..3c2b6ed98a56 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,msm8998-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,msm8998-mdss.yaml @@ -18,8 +18,7 @@ $ref: /schemas/display/msm/mdss-common.yaml# properties: compatible: - items: - - const: qcom,msm8998-mdss + const: qcom,msm8998-mdss clocks: items: @@ -47,7 +46,9 @@ patternProperties: type: object properties: compatible: - const: qcom,mdss-dsi-ctrl + items: + - const: qcom,msm8998-dsi-ctrl + - const: qcom,mdss-dsi-ctrl "^phy@[0-9a-f]+$": type: object @@ -55,6 +56,9 @@ patternProperties: compatible: const: qcom,dsi-phy-10nm-8998 +required: + - compatible + unevaluatedProperties: false examples: @@ -126,7 +130,7 @@ examples: }; dsi@c994000 { - compatible = "qcom,mdss-dsi-ctrl"; + compatible = "qcom,msm8998-dsi-ctrl", "qcom,mdss-dsi-ctrl"; reg = <0x0c994000 0x400>; reg-names = "dsi_ctrl"; @@ -196,7 +200,7 @@ examples: }; dsi@c996000 { - compatible = "qcom,mdss-dsi-ctrl"; + compatible = "qcom,msm8998-dsi-ctrl", "qcom,mdss-dsi-ctrl"; reg = <0x0c996000 0x400>; reg-names = "dsi_ctrl"; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-dpu.yaml index a7b382f01b56..414f4e7ebdf1 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-dpu.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/display/msm/qcom,qcm2290-dpu.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Display DPU dt properties for QCM2290 target +title: Qualcomm Display DPU on QCM2290 maintainers: - Loic Poulain <loic.poulain@linaro.org> @@ -13,8 +13,7 @@ $ref: /schemas/display/msm/dpu-common.yaml# properties: compatible: - items: - - const: qcom,qcm2290-dpu + const: qcom,qcm2290-dpu reg: items: @@ -42,6 +41,13 @@ properties: - const: lut - const: vsync +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-mdss.yaml index d6f043a4b08d..2995b84b2cd4 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-mdss.yaml @@ -18,8 +18,7 @@ $ref: /schemas/display/msm/mdss-common.yaml# properties: compatible: - items: - - const: qcom,qcm2290-mdss + const: qcom,qcm2290-mdss clocks: items: @@ -61,6 +60,9 @@ patternProperties: compatible: const: qcom,dsi-phy-14nm-2290 +required: + - compatible + unevaluatedProperties: false examples: @@ -72,7 +74,7 @@ examples: #include <dt-bindings/interconnect/qcom,qcm2290.h> #include <dt-bindings/power/qcom-rpmpd.h> - mdss@5e00000 { + display-subsystem@5e00000 { #address-cells = <1>; #size-cells = <1>; compatible = "qcom,qcm2290-mdss"; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sc7180-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sc7180-dpu.yaml index bd590a6b5b96..1fb8321d9ee8 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sc7180-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sc7180-dpu.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/display/msm/qcom,sc7180-dpu.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Display DPU dt properties for SC7180 target +title: Qualcomm Display DPU on SC7180 maintainers: - Krishna Manikandan <quic_mkrishn@quicinc.com> @@ -13,8 +13,7 @@ $ref: /schemas/display/msm/dpu-common.yaml# properties: compatible: - items: - - const: qcom,sc7180-dpu + const: qcom,sc7180-dpu reg: items: @@ -44,6 +43,13 @@ properties: - const: core - const: vsync +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sc7180-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sc7180-mdss.yaml index 13e396d61a51..42ef06edddc4 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sc7180-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sc7180-mdss.yaml @@ -18,8 +18,7 @@ $ref: /schemas/display/msm/mdss-common.yaml# properties: compatible: - items: - - const: qcom,sc7180-mdss + const: qcom,sc7180-mdss clocks: items: @@ -59,7 +58,9 @@ patternProperties: type: object properties: compatible: - const: qcom,mdss-dsi-ctrl + items: + - const: qcom,sc7180-dsi-ctrl + - const: qcom,mdss-dsi-ctrl "^phy@[0-9a-f]+$": type: object @@ -67,6 +68,9 @@ patternProperties: compatible: const: qcom,dsi-phy-10nm +required: + - compatible + unevaluatedProperties: false examples: @@ -142,7 +146,7 @@ examples: }; dsi@ae94000 { - compatible = "qcom,mdss-dsi-ctrl"; + compatible = "qcom,sc7180-dsi-ctrl", "qcom,mdss-dsi-ctrl"; reg = <0x0ae94000 0x400>; reg-names = "dsi_ctrl"; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sc7280-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sc7280-dpu.yaml index 924059b387b6..26dc073bd19a 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sc7280-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sc7280-dpu.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/display/msm/qcom,sc7280-dpu.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Display DPU dt properties for SC7280 +title: Qualcomm Display DPU on SC7280 maintainers: - Krishna Manikandan <quic_mkrishn@quicinc.com> @@ -43,6 +43,13 @@ properties: - const: core - const: vsync +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sc7280-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sc7280-mdss.yaml index a3de1744ba11..078e1d1a7d2f 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sc7280-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sc7280-mdss.yaml @@ -58,7 +58,9 @@ patternProperties: type: object properties: compatible: - const: qcom,mdss-dsi-ctrl + items: + - const: qcom,sc7280-dsi-ctrl + - const: qcom,mdss-dsi-ctrl "^edp@[0-9a-f]+$": type: object @@ -74,6 +76,9 @@ patternProperties: - qcom,sc7280-dsi-phy-7nm - qcom,sc7280-edp-phy +required: + - compatible + unevaluatedProperties: false examples: @@ -162,7 +167,7 @@ examples: }; dsi@ae94000 { - compatible = "qcom,mdss-dsi-ctrl"; + compatible = "qcom,sc7280-dsi-ctrl", "qcom,mdss-dsi-ctrl"; reg = <0x0ae94000 0x400>; reg-names = "dsi_ctrl"; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sc8280xp-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sc8280xp-dpu.yaml new file mode 100644 index 000000000000..f2c8e16cf067 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sc8280xp-dpu.yaml @@ -0,0 +1,122 @@ +# 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# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SC8280XP Display Processing Unit + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + +description: + Device tree bindings for SC8280XP Display Processing Unit. + +$ref: /schemas/display/msm/dpu-common.yaml# + +properties: + compatible: + const: qcom,sc8280xp-dpu + + reg: + items: + - description: Address offset and size for mdp register set + - description: Address offset and size for vbif register set + + reg-names: + items: + - const: mdp + - const: vbif + + clocks: + items: + - description: Display hf axi clock + - description: Display sf axi clock + - description: Display ahb clock + - description: Display lut clock + - description: Display core clock + - description: Display vsync clock + + clock-names: + items: + - const: bus + - const: nrt_bus + - const: iface + - const: lut + - const: core + - const: vsync + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,dispcc-sc8280xp.h> + #include <dt-bindings/clock/qcom,gcc-sc8280xp.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interconnect/qcom,sc8280xp.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-controller@ae01000 { + compatible = "qcom,sc8280xp-dpu"; + reg = <0x0ae01000 0x8f000>, + <0x0aeb0000 0x2008>; + reg-names = "mdp", "vbif"; + + clocks = <&gcc GCC_DISP_HF_AXI_CLK>, + <&gcc GCC_DISP_SF_AXI_CLK>, + <&dispcc0 DISP_CC_MDSS_AHB_CLK>, + <&dispcc0 DISP_CC_MDSS_MDP_LUT_CLK>, + <&dispcc0 DISP_CC_MDSS_MDP_CLK>, + <&dispcc0 DISP_CC_MDSS_VSYNC_CLK>; + clock-names = "bus", + "nrt_bus", + "iface", + "lut", + "core", + "vsync"; + + assigned-clocks = <&dispcc0 DISP_CC_MDSS_MDP_CLK>, + <&dispcc0 DISP_CC_MDSS_VSYNC_CLK>; + assigned-clock-rates = <460000000>, + <19200000>; + + operating-points-v2 = <&mdp_opp_table>; + power-domains = <&rpmhpd SC8280XP_MMCX>; + + interrupt-parent = <&mdss0>; + interrupts = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + endpoint { + remote-endpoint = <&mdss0_dp0_in>; + }; + }; + + port@4 { + reg = <4>; + endpoint { + remote-endpoint = <&mdss0_dp1_in>; + }; + }; + + port@5 { + reg = <5>; + endpoint { + remote-endpoint = <&mdss0_dp3_in>; + }; + }; + + port@6 { + reg = <6>; + endpoint { + remote-endpoint = <&mdss0_dp2_in>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sc8280xp-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sc8280xp-mdss.yaml new file mode 100644 index 000000000000..c239544bc37f --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sc8280xp-mdss.yaml @@ -0,0 +1,151 @@ +# 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# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SC8280XP Mobile Display Subsystem + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + +description: + Device tree bindings for MSM Mobile Display Subsystem (MDSS) that encapsulates + sub-blocks like DPU display controller, DSI and DP interfaces etc. + +$ref: /schemas/display/msm/mdss-common.yaml# + +properties: + compatible: + const: qcom,sc8280xp-mdss + + clocks: + items: + - description: Display AHB clock from gcc + - description: Display AHB clock from dispcc + - description: Display core clock + + clock-names: + items: + - const: iface + - const: ahb + - const: core + +patternProperties: + "^display-controller@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,sc8280xp-dpu + + "^displayport-controller@[0-9a-f]+$": + type: object + properties: + compatible: + enum: + - qcom,sc8280xp-dp + - qcom,sc8280xp-edp + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,dispcc-sc8280xp.h> + #include <dt-bindings/clock/qcom,gcc-sc8280xp.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interconnect/qcom,sc8280xp.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-subsystem@ae00000 { + compatible = "qcom,sc8280xp-mdss"; + reg = <0x0ae00000 0x1000>; + reg-names = "mdss"; + + power-domains = <&dispcc0 MDSS_GDSC>; + + clocks = <&gcc GCC_DISP_AHB_CLK>, + <&dispcc0 DISP_CC_MDSS_AHB_CLK>, + <&dispcc0 DISP_CC_MDSS_MDP_CLK>; + clock-names = "iface", + "ahb", + "core"; + + resets = <&dispcc0 DISP_CC_MDSS_CORE_BCR>; + + interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <1>; + + interconnects = <&mmss_noc MASTER_MDP0 0 &mc_virt SLAVE_EBI1 0>, + <&mmss_noc MASTER_MDP1 0 &mc_virt SLAVE_EBI1 0>; + interconnect-names = "mdp0-mem", "mdp1-mem"; + + iommus = <&apps_smmu 0x1000 0x402>; + + #address-cells = <1>; + #size-cells = <1>; + ranges; + + display-controller@ae01000 { + compatible = "qcom,sc8280xp-dpu"; + reg = <0x0ae01000 0x8f000>, + <0x0aeb0000 0x2008>; + reg-names = "mdp", "vbif"; + + clocks = <&gcc GCC_DISP_HF_AXI_CLK>, + <&gcc GCC_DISP_SF_AXI_CLK>, + <&dispcc0 DISP_CC_MDSS_AHB_CLK>, + <&dispcc0 DISP_CC_MDSS_MDP_LUT_CLK>, + <&dispcc0 DISP_CC_MDSS_MDP_CLK>, + <&dispcc0 DISP_CC_MDSS_VSYNC_CLK>; + clock-names = "bus", + "nrt_bus", + "iface", + "lut", + "core", + "vsync"; + + assigned-clocks = <&dispcc0 DISP_CC_MDSS_VSYNC_CLK>; + assigned-clock-rates = <19200000>; + + operating-points-v2 = <&mdss0_mdp_opp_table>; + power-domains = <&rpmhpd SC8280XP_MMCX>; + + interrupt-parent = <&mdss0>; + interrupts = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + endpoint { + remote-endpoint = <&mdss0_dp0_in>; + }; + }; + + port@4 { + reg = <4>; + endpoint { + remote-endpoint = <&mdss0_dp1_in>; + }; + }; + + port@5 { + reg = <5>; + endpoint { + remote-endpoint = <&mdss0_dp3_in>; + }; + }; + + port@6 { + reg = <6>; + endpoint { + remote-endpoint = <&mdss0_dp2_in>; + }; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sdm845-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sdm845-dpu.yaml index 5719b45f2860..0f7765d832e7 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sdm845-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sdm845-dpu.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/display/msm/qcom,sdm845-dpu.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Display DPU dt properties for SDM845 target +title: Qualcomm Display DPU on SDM845 maintainers: - Krishna Manikandan <quic_mkrishn@quicinc.com> @@ -13,8 +13,7 @@ $ref: /schemas/display/msm/dpu-common.yaml# properties: compatible: - items: - - const: qcom,sdm845-dpu + const: qcom,sdm845-dpu reg: items: @@ -42,6 +41,13 @@ properties: - const: core - const: vsync +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sdm845-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sdm845-mdss.yaml index 31ca6f99fc22..6ecb00920d7f 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sdm845-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sdm845-mdss.yaml @@ -18,8 +18,7 @@ $ref: /schemas/display/msm/mdss-common.yaml# properties: compatible: - items: - - const: qcom,sdm845-mdss + const: qcom,sdm845-mdss clocks: items: @@ -47,11 +46,19 @@ patternProperties: compatible: const: qcom,sdm845-dpu + "^displayport-controller@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,sdm845-dp + "^dsi@[0-9a-f]+$": type: object properties: compatible: - const: qcom,mdss-dsi-ctrl + items: + - const: qcom,sdm845-dsi-ctrl + - const: qcom,mdss-dsi-ctrl "^phy@[0-9a-f]+$": type: object @@ -59,6 +66,9 @@ patternProperties: compatible: const: qcom,dsi-phy-10nm +required: + - compatible + unevaluatedProperties: false examples: @@ -128,7 +138,7 @@ examples: }; dsi@ae94000 { - compatible = "qcom,mdss-dsi-ctrl"; + compatible = "qcom,sdm845-dsi-ctrl", "qcom,mdss-dsi-ctrl"; reg = <0x0ae94000 0x400>; reg-names = "dsi_ctrl"; @@ -198,7 +208,7 @@ examples: }; dsi@ae96000 { - compatible = "qcom,mdss-dsi-ctrl"; + compatible = "qcom,sdm845-dsi-ctrl", "qcom,mdss-dsi-ctrl"; reg = <0x0ae96000 0x400>; reg-names = "dsi_ctrl"; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm6115-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm6115-dpu.yaml index 4a39a3031409..bf62c2f5325a 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm6115-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm6115-dpu.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/display/msm/qcom,sm6115-dpu.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Display DPU dt properties for SM6115 target +title: Qualcomm Display DPU on SM6115 maintainers: - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> @@ -13,8 +13,7 @@ $ref: /schemas/display/msm/dpu-common.yaml# properties: compatible: - items: - - const: qcom,sm6115-dpu + const: qcom,sm6115-dpu reg: items: diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm6115-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm6115-mdss.yaml index a86d7f53fa84..2491cb100b33 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm6115-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm6115-mdss.yaml @@ -18,8 +18,7 @@ $ref: /schemas/display/msm/mdss-common.yaml# properties: compatible: - items: - - const: qcom,sm6115-mdss + const: qcom,sm6115-mdss clocks: items: @@ -62,7 +61,7 @@ examples: #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/power/qcom-rpmpd.h> - mdss@5e00000 { + display-subsystem@5e00000 { #address-cells = <1>; #size-cells = <1>; compatible = "qcom,sm6115-mdss"; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8150-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8150-dpu.yaml new file mode 100644 index 000000000000..2b3f3fe9bdf7 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8150-dpu.yaml @@ -0,0 +1,92 @@ +# 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# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM8150 Display DPU + +maintainers: + - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> + +$ref: /schemas/display/msm/dpu-common.yaml# + +properties: + compatible: + const: qcom,sm8150-dpu + + reg: + items: + - description: Address offset and size for mdp register set + - description: Address offset and size for vbif register set + + reg-names: + items: + - const: mdp + - const: vbif + + clocks: + items: + - description: Display ahb clock + - description: Display hf axi clock + - description: Display core clock + - description: Display vsync clock + + clock-names: + items: + - const: iface + - const: bus + - const: core + - const: vsync + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,dispcc-sm8150.h> + #include <dt-bindings/clock/qcom,gcc-sm8150.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interconnect/qcom,sm8150.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-controller@ae01000 { + compatible = "qcom,sm8150-dpu"; + reg = <0x0ae01000 0x8f000>, + <0x0aeb0000 0x2008>; + reg-names = "mdp", "vbif"; + + clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&gcc GCC_DISP_HF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>, + <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + clock-names = "iface", "bus", "core", "vsync"; + + assigned-clocks = <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + assigned-clock-rates = <19200000>; + + operating-points-v2 = <&mdp_opp_table>; + power-domains = <&rpmhpd SM8150_MMCX>; + + interrupt-parent = <&mdss>; + interrupts = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + endpoint { + remote-endpoint = <&dsi0_in>; + }; + }; + + port@1 { + reg = <1>; + endpoint { + remote-endpoint = <&dsi1_in>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8150-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8150-mdss.yaml new file mode 100644 index 000000000000..5182e958e069 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8150-mdss.yaml @@ -0,0 +1,332 @@ +# 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# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM8150 Display MDSS + +maintainers: + - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> + +description: + Device tree bindings for MSM Mobile Display Subsystem(MDSS) that encapsulates + sub-blocks like DPU display controller, DSI and DP interfaces etc. Device tree + bindings of MDSS are mentioned for SM8150 target. + +$ref: /schemas/display/msm/mdss-common.yaml# + +properties: + compatible: + items: + - const: qcom,sm8150-mdss + + clocks: + items: + - description: Display AHB clock from gcc + - description: Display hf axi clock + - description: Display sf axi clock + - description: Display core clock + + clock-names: + items: + - const: iface + - const: bus + - const: nrt_bus + - const: core + + iommus: + maxItems: 1 + + interconnects: + maxItems: 2 + + interconnect-names: + maxItems: 2 + +patternProperties: + "^display-controller@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,sm8150-dpu + + "^dsi@[0-9a-f]+$": + type: object + properties: + compatible: + items: + - const: qcom,sm8150-dsi-ctrl + - const: qcom,mdss-dsi-ctrl + + "^phy@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,dsi-phy-7nm + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,dispcc-sm8150.h> + #include <dt-bindings/clock/qcom,gcc-sm8150.h> + #include <dt-bindings/clock/qcom,rpmh.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interconnect/qcom,sm8150.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-subsystem@ae00000 { + compatible = "qcom,sm8150-mdss"; + reg = <0x0ae00000 0x1000>; + reg-names = "mdss"; + + interconnects = <&mmss_noc MASTER_MDP_PORT0 &mc_virt SLAVE_EBI_CH0>, + <&mmss_noc MASTER_MDP_PORT1 &mc_virt SLAVE_EBI_CH0>; + interconnect-names = "mdp0-mem", "mdp1-mem"; + + power-domains = <&dispcc MDSS_GDSC>; + + clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&gcc GCC_DISP_HF_AXI_CLK>, + <&gcc GCC_DISP_SF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>; + clock-names = "iface", "bus", "nrt_bus", "core"; + + interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <1>; + + iommus = <&apps_smmu 0x800 0x420>; + + #address-cells = <1>; + #size-cells = <1>; + ranges; + + display-controller@ae01000 { + compatible = "qcom,sm8150-dpu"; + reg = <0x0ae01000 0x8f000>, + <0x0aeb0000 0x2008>; + reg-names = "mdp", "vbif"; + + clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&gcc GCC_DISP_HF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>, + <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + clock-names = "iface", "bus", "core", "vsync"; + + assigned-clocks = <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + assigned-clock-rates = <19200000>; + + operating-points-v2 = <&mdp_opp_table>; + power-domains = <&rpmhpd SM8150_MMCX>; + + interrupt-parent = <&mdss>; + interrupts = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dpu_intf1_out: endpoint { + remote-endpoint = <&dsi0_in>; + }; + }; + + port@1 { + reg = <1>; + dpu_intf2_out: endpoint { + remote-endpoint = <&dsi1_in>; + }; + }; + }; + + mdp_opp_table: opp-table { + compatible = "operating-points-v2"; + + opp-171428571 { + opp-hz = /bits/ 64 <171428571>; + required-opps = <&rpmhpd_opp_low_svs>; + }; + + opp-300000000 { + opp-hz = /bits/ 64 <300000000>; + required-opps = <&rpmhpd_opp_svs>; + }; + + opp-345000000 { + opp-hz = /bits/ 64 <345000000>; + required-opps = <&rpmhpd_opp_svs_l1>; + }; + + opp-460000000 { + opp-hz = /bits/ 64 <460000000>; + required-opps = <&rpmhpd_opp_nom>; + }; + }; + }; + + dsi@ae94000 { + compatible = "qcom,sm8150-dsi-ctrl", "qcom,mdss-dsi-ctrl"; + reg = <0x0ae94000 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 = <&dsi0_phy 0>, <&dsi0_phy 1>; + + operating-points-v2 = <&dsi_opp_table>; + power-domains = <&rpmhpd SM8150_MMCX>; + + phys = <&dsi0_phy>; + phy-names = "dsi"; + + #address-cells = <1>; + #size-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dsi0_in: endpoint { + remote-endpoint = <&dpu_intf1_out>; + }; + }; + + port@1 { + reg = <1>; + dsi0_out: endpoint { + }; + }; + }; + + dsi_opp_table: opp-table { + compatible = "operating-points-v2"; + + opp-187500000 { + opp-hz = /bits/ 64 <187500000>; + required-opps = <&rpmhpd_opp_low_svs>; + }; + + opp-300000000 { + opp-hz = /bits/ 64 <300000000>; + required-opps = <&rpmhpd_opp_svs>; + }; + + opp-358000000 { + opp-hz = /bits/ 64 <358000000>; + required-opps = <&rpmhpd_opp_svs_l1>; + }; + }; + }; + + dsi0_phy: phy@ae94400 { + compatible = "qcom,dsi-phy-7nm"; + reg = <0x0ae94400 0x200>, + <0x0ae94600 0x280>, + <0x0ae94900 0x260>; + reg-names = "dsi_phy", + "dsi_phy_lane", + "dsi_pll"; + + #clock-cells = <1>; + #phy-cells = <0>; + + clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&rpmhcc RPMH_CXO_CLK>; + clock-names = "iface", "ref"; + vdds-supply = <&vreg_dsi_phy>; + }; + + dsi@ae96000 { + compatible = "qcom,sm8150-dsi-ctrl", "qcom,mdss-dsi-ctrl"; + reg = <0x0ae96000 0x400>; + reg-names = "dsi_ctrl"; + + interrupt-parent = <&mdss>; + interrupts = <5>; + + clocks = <&dispcc DISP_CC_MDSS_BYTE1_CLK>, + <&dispcc DISP_CC_MDSS_BYTE1_INTF_CLK>, + <&dispcc DISP_CC_MDSS_PCLK1_CLK>, + <&dispcc DISP_CC_MDSS_ESC1_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_BYTE1_CLK_SRC>, + <&dispcc DISP_CC_MDSS_PCLK1_CLK_SRC>; + assigned-clock-parents = <&dsi1_phy 0>, <&dsi1_phy 1>; + + operating-points-v2 = <&dsi_opp_table>; + power-domains = <&rpmhpd SM8150_MMCX>; + + phys = <&dsi1_phy>; + phy-names = "dsi"; + + #address-cells = <1>; + #size-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dsi1_in: endpoint { + remote-endpoint = <&dpu_intf2_out>; + }; + }; + + port@1 { + reg = <1>; + dsi1_out: endpoint { + }; + }; + }; + }; + + dsi1_phy: phy@ae96400 { + compatible = "qcom,dsi-phy-7nm"; + reg = <0x0ae96400 0x200>, + <0x0ae96600 0x280>, + <0x0ae96900 0x260>; + reg-names = "dsi_phy", + "dsi_phy_lane", + "dsi_pll"; + + #clock-cells = <1>; + #phy-cells = <0>; + + clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&rpmhcc RPMH_CXO_CLK>; + clock-names = "iface", "ref"; + vdds-supply = <&vreg_dsi_phy>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8250-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8250-dpu.yaml index 9ff8a265c85f..687c8c170cd4 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm8250-dpu.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8250-dpu.yaml @@ -39,6 +39,13 @@ properties: - const: core - const: vsync +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8250-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8250-mdss.yaml index 0d3be5386b3f..368d3db0ce96 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm8250-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8250-mdss.yaml @@ -18,8 +18,7 @@ $ref: /schemas/display/msm/mdss-common.yaml# properties: compatible: - items: - - const: qcom,sm8250-mdss + const: qcom,sm8250-mdss clocks: items: @@ -55,7 +54,9 @@ patternProperties: type: object properties: compatible: - const: qcom,mdss-dsi-ctrl + items: + - const: qcom,sm8250-dsi-ctrl + - const: qcom,mdss-dsi-ctrl "^phy@[0-9a-f]+$": type: object @@ -63,6 +64,9 @@ patternProperties: compatible: const: qcom,dsi-phy-7nm +required: + - compatible + unevaluatedProperties: false examples: @@ -167,7 +171,7 @@ examples: }; dsi@ae94000 { - compatible = "qcom,mdss-dsi-ctrl"; + compatible = "qcom,sm8250-dsi-ctrl", "qcom,mdss-dsi-ctrl"; reg = <0x0ae94000 0x400>; reg-names = "dsi_ctrl"; @@ -257,7 +261,7 @@ examples: }; dsi@ae96000 { - compatible = "qcom,mdss-dsi-ctrl"; + compatible = "qcom,sm8250-dsi-ctrl", "qcom,mdss-dsi-ctrl"; reg = <0x0ae96000 0x400>; reg-names = "dsi_ctrl"; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8350-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8350-dpu.yaml new file mode 100644 index 000000000000..120500395c9a --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8350-dpu.yaml @@ -0,0 +1,120 @@ +# 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# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM8350 Display DPU + +maintainers: + - Robert Foss <robert.foss@linaro.org> + +$ref: /schemas/display/msm/dpu-common.yaml# + +properties: + compatible: + const: qcom,sm8350-dpu + + reg: + items: + - description: Address offset and size for mdp register set + - description: Address offset and size for vbif register set + + reg-names: + items: + - const: mdp + - const: vbif + + clocks: + items: + - description: Display hf axi clock + - description: Display sf axi clock + - description: Display ahb clock + - description: Display lut clock + - description: Display core clock + - description: Display vsync clock + + clock-names: + items: + - const: bus + - const: nrt_bus + - const: iface + - const: lut + - const: core + - const: vsync + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,dispcc-sm8350.h> + #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> + + display-controller@ae01000 { + compatible = "qcom,sm8350-dpu"; + reg = <0x0ae01000 0x8f000>, + <0x0aeb0000 0x2008>; + reg-names = "mdp", "vbif"; + + clocks = <&gcc GCC_DISP_HF_AXI_CLK>, + <&gcc GCC_DISP_SF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_MDP_LUT_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>, + <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + clock-names = "bus", + "nrt_bus", + "iface", + "lut", + "core", + "vsync"; + + assigned-clocks = <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + assigned-clock-rates = <19200000>; + + operating-points-v2 = <&mdp_opp_table>; + power-domains = <&rpmhpd SM8350_MMCX>; + + interrupt-parent = <&mdss>; + interrupts = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dpu_intf1_out: endpoint { + remote-endpoint = <&dsi0_in>; + }; + }; + }; + + mdp_opp_table: opp-table { + compatible = "operating-points-v2"; + + opp-200000000 { + opp-hz = /bits/ 64 <200000000>; + required-opps = <&rpmhpd_opp_low_svs>; + }; + + opp-300000000 { + opp-hz = /bits/ 64 <300000000>; + required-opps = <&rpmhpd_opp_svs>; + }; + + opp-345000000 { + opp-hz = /bits/ 64 <345000000>; + required-opps = <&rpmhpd_opp_svs_l1>; + }; + + opp-460000000 { + opp-hz = /bits/ 64 <460000000>; + required-opps = <&rpmhpd_opp_nom>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8350-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8350-mdss.yaml new file mode 100644 index 000000000000..4d94dbff3054 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8350-mdss.yaml @@ -0,0 +1,223 @@ +# 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# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM8350 Display MDSS + +maintainers: + - Robert Foss <robert.foss@linaro.org> + +description: + MSM Mobile Display Subsystem(MDSS) that encapsulates sub-blocks like + DPU display controller, DSI and DP interfaces etc. + +$ref: /schemas/display/msm/mdss-common.yaml# + +properties: + compatible: + items: + - const: qcom,sm8350-mdss + + clocks: + items: + - description: Display AHB clock from gcc + - description: Display hf axi clock + - description: Display sf axi clock + - description: Display core clock + + clock-names: + items: + - const: iface + - const: bus + - const: nrt_bus + - const: core + + iommus: + maxItems: 1 + + interconnects: + maxItems: 2 + + interconnect-names: + items: + - const: mdp0-mem + - const: mdp1-mem + +patternProperties: + "^display-controller@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,sm8350-dpu + + "^dsi@[0-9a-f]+$": + type: object + properties: + compatible: + items: + - const: qcom,sm8350-dsi-ctrl + - const: qcom,mdss-dsi-ctrl + + "^phy@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,dsi-phy-5nm-8350 + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,dispcc-sm8350.h> + #include <dt-bindings/clock/qcom,gcc-sm8350.h> + #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> + + display-subsystem@ae00000 { + compatible = "qcom,sm8350-mdss"; + reg = <0x0ae00000 0x1000>; + reg-names = "mdss"; + + interconnects = <&mmss_noc MASTER_MDP0 0 &mc_virt SLAVE_EBI1 0>, + <&mmss_noc MASTER_MDP1 0 &mc_virt SLAVE_EBI1 0>; + interconnect-names = "mdp0-mem", "mdp1-mem"; + + power-domains = <&dispcc MDSS_GDSC>; + resets = <&dispcc DISP_CC_MDSS_CORE_BCR>; + + clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&gcc GCC_DISP_HF_AXI_CLK>, + <&gcc GCC_DISP_SF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>; + clock-names = "iface", "bus", "nrt_bus", "core"; + + iommus = <&apps_smmu 0x820 0x402>; + + interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <1>; + + #address-cells = <1>; + #size-cells = <1>; + ranges; + + display-controller@ae01000 { + compatible = "qcom,sm8350-dpu"; + reg = <0x0ae01000 0x8f000>, + <0x0aeb0000 0x2008>; + reg-names = "mdp", "vbif"; + + clocks = <&gcc GCC_DISP_HF_AXI_CLK>, + <&gcc GCC_DISP_SF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_MDP_LUT_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>, + <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + clock-names = "bus", + "nrt_bus", + "iface", + "lut", + "core", + "vsync"; + + assigned-clocks = <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + assigned-clock-rates = <19200000>; + + operating-points-v2 = <&mdp_opp_table>; + power-domains = <&rpmhpd SM8350_MMCX>; + + interrupt-parent = <&mdss>; + interrupts = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dpu_intf1_out: endpoint { + remote-endpoint = <&dsi0_in>; + }; + }; + }; + + mdp_opp_table: opp-table { + compatible = "operating-points-v2"; + + opp-200000000 { + opp-hz = /bits/ 64 <200000000>; + required-opps = <&rpmhpd_opp_low_svs>; + }; + + opp-300000000 { + opp-hz = /bits/ 64 <300000000>; + required-opps = <&rpmhpd_opp_svs>; + }; + + opp-345000000 { + opp-hz = /bits/ 64 <345000000>; + required-opps = <&rpmhpd_opp_svs_l1>; + }; + + opp-460000000 { + opp-hz = /bits/ 64 <460000000>; + required-opps = <&rpmhpd_opp_nom>; + }; + }; + }; + + dsi0: dsi@ae94000 { + compatible = "qcom,sm8350-dsi-ctrl", "qcom,mdss-dsi-ctrl"; + reg = <0x0ae94000 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 = <&rpmhpd SM8350_MMCX>; + + phys = <&mdss_dsi0_phy>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dsi0_in: endpoint { + remote-endpoint = <&dpu_intf1_out>; + }; + }; + + port@1 { + reg = <1>; + dsi0_out: endpoint { + }; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8450-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8450-dpu.yaml new file mode 100644 index 000000000000..0d17ece1c453 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8450-dpu.yaml @@ -0,0 +1,139 @@ +# 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# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM8450 Display DPU + +maintainers: + - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> + +$ref: /schemas/display/msm/dpu-common.yaml# + +properties: + compatible: + const: qcom,sm8450-dpu + + reg: + items: + - description: Address offset and size for mdp register set + - description: Address offset and size for vbif register set + + reg-names: + items: + - const: mdp + - const: vbif + + clocks: + items: + - description: Display hf axi + - description: Display sf axi + - description: Display ahb + - description: Display lut + - description: Display core + - description: Display vsync + + clock-names: + items: + - const: bus + - const: nrt_bus + - const: iface + - const: lut + - const: core + - const: vsync + +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,sm8450-dispcc.h> + #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> + + display-controller@ae01000 { + compatible = "qcom,sm8450-dpu"; + reg = <0x0ae01000 0x8f000>, + <0x0aeb0000 0x2008>; + reg-names = "mdp", "vbif"; + + clocks = <&gcc GCC_DISP_HF_AXI_CLK>, + <&gcc GCC_DISP_SF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_MDP_LUT_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>, + <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + clock-names = "bus", + "nrt_bus", + "iface", + "lut", + "core", + "vsync"; + + assigned-clocks = <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + assigned-clock-rates = <19200000>; + + operating-points-v2 = <&mdp_opp_table>; + power-domains = <&rpmhpd SM8450_MMCX>; + + interrupt-parent = <&mdss>; + interrupts = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dpu_intf1_out: endpoint { + remote-endpoint = <&dsi0_in>; + }; + }; + + port@1 { + reg = <1>; + dpu_intf2_out: endpoint { + remote-endpoint = <&dsi1_in>; + }; + }; + }; + + mdp_opp_table: opp-table { + compatible = "operating-points-v2"; + + opp-172000000{ + opp-hz = /bits/ 64 <172000000>; + required-opps = <&rpmhpd_opp_low_svs_d1>; + }; + + opp-200000000 { + opp-hz = /bits/ 64 <200000000>; + required-opps = <&rpmhpd_opp_low_svs>; + }; + + opp-325000000 { + opp-hz = /bits/ 64 <325000000>; + required-opps = <&rpmhpd_opp_svs>; + }; + + opp-375000000 { + opp-hz = /bits/ 64 <375000000>; + required-opps = <&rpmhpd_opp_svs_l1>; + }; + + opp-500000000 { + opp-hz = /bits/ 64 <500000000>; + required-opps = <&rpmhpd_opp_nom>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8450-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8450-mdss.yaml new file mode 100644 index 000000000000..4c6929e2534c --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8450-mdss.yaml @@ -0,0 +1,345 @@ +# 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# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM8450 Display MDSS + +maintainers: + - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> + +description: + SM8450 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,sm8450-mdss + + clocks: + items: + - description: Display AHB + - description: Display hf AXI + - description: Display sf AXI + - description: Display core + + iommus: + maxItems: 1 + + interconnects: + maxItems: 2 + + interconnect-names: + maxItems: 2 + +patternProperties: + "^display-controller@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,sm8450-dpu + + "^dsi@[0-9a-f]+$": + type: object + properties: + compatible: + items: + - const: qcom,sm8450-dsi-ctrl + - const: qcom,mdss-dsi-ctrl + + "^phy@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,dsi-phy-5nm-8450 + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,sm8450-dispcc.h> + #include <dt-bindings/clock/qcom,gcc-sm8450.h> + #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> + + display-subsystem@ae00000 { + compatible = "qcom,sm8450-mdss"; + reg = <0x0ae00000 0x1000>; + reg-names = "mdss"; + + interconnects = <&mmss_noc MASTER_MDP_DISP 0 &mc_virt SLAVE_EBI1_DISP 0>, + <&mmss_noc MASTER_MDP_DISP 0 &mc_virt SLAVE_EBI1_DISP 0>; + interconnect-names = "mdp0-mem", "mdp1-mem"; + + resets = <&dispcc DISP_CC_MDSS_CORE_BCR>; + + power-domains = <&dispcc MDSS_GDSC>; + + clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&gcc GCC_DISP_HF_AXI_CLK>, + <&gcc GCC_DISP_SF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>; + clock-names = "iface", "bus", "nrt_bus", "core"; + + interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <1>; + + iommus = <&apps_smmu 0x2800 0x402>; + + #address-cells = <1>; + #size-cells = <1>; + ranges; + + display-controller@ae01000 { + compatible = "qcom,sm8450-dpu"; + reg = <0x0ae01000 0x8f000>, + <0x0aeb0000 0x2008>; + reg-names = "mdp", "vbif"; + + clocks = <&gcc GCC_DISP_HF_AXI_CLK>, + <&gcc GCC_DISP_SF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_MDP_LUT_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>, + <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + clock-names = "bus", + "nrt_bus", + "iface", + "lut", + "core", + "vsync"; + + assigned-clocks = <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + assigned-clock-rates = <19200000>; + + operating-points-v2 = <&mdp_opp_table>; + power-domains = <&rpmhpd SM8450_MMCX>; + + interrupt-parent = <&mdss>; + interrupts = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dpu_intf1_out: endpoint { + remote-endpoint = <&dsi0_in>; + }; + }; + + port@1 { + reg = <1>; + dpu_intf2_out: endpoint { + remote-endpoint = <&dsi1_in>; + }; + }; + }; + + mdp_opp_table: opp-table { + compatible = "operating-points-v2"; + + opp-172000000{ + opp-hz = /bits/ 64 <172000000>; + required-opps = <&rpmhpd_opp_low_svs_d1>; + }; + + opp-200000000 { + opp-hz = /bits/ 64 <200000000>; + required-opps = <&rpmhpd_opp_low_svs>; + }; + + opp-325000000 { + opp-hz = /bits/ 64 <325000000>; + required-opps = <&rpmhpd_opp_svs>; + }; + + opp-375000000 { + opp-hz = /bits/ 64 <375000000>; + required-opps = <&rpmhpd_opp_svs_l1>; + }; + + opp-500000000 { + opp-hz = /bits/ 64 <500000000>; + required-opps = <&rpmhpd_opp_nom>; + }; + }; + }; + + dsi@ae94000 { + compatible = "qcom,sm8450-dsi-ctrl", "qcom,mdss-dsi-ctrl"; + reg = <0x0ae94000 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 = <&dsi0_phy 0>, <&dsi0_phy 1>; + + operating-points-v2 = <&dsi_opp_table>; + power-domains = <&rpmhpd SM8450_MMCX>; + + phys = <&dsi0_phy>; + phy-names = "dsi"; + + #address-cells = <1>; + #size-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dsi0_in: endpoint { + remote-endpoint = <&dpu_intf1_out>; + }; + }; + + port@1 { + reg = <1>; + dsi0_out: endpoint { + }; + }; + }; + + dsi_opp_table: opp-table { + compatible = "operating-points-v2"; + + opp-160310000{ + opp-hz = /bits/ 64 <160310000>; + required-opps = <&rpmhpd_opp_low_svs_d1>; + }; + + opp-187500000 { + opp-hz = /bits/ 64 <187500000>; + required-opps = <&rpmhpd_opp_low_svs>; + }; + + opp-300000000 { + opp-hz = /bits/ 64 <300000000>; + required-opps = <&rpmhpd_opp_svs>; + }; + + opp-358000000 { + opp-hz = /bits/ 64 <358000000>; + required-opps = <&rpmhpd_opp_svs_l1>; + }; + }; + }; + + dsi0_phy: phy@ae94400 { + compatible = "qcom,dsi-phy-5nm-8450"; + reg = <0x0ae94400 0x200>, + <0x0ae94600 0x280>, + <0x0ae94900 0x260>; + reg-names = "dsi_phy", + "dsi_phy_lane", + "dsi_pll"; + + #clock-cells = <1>; + #phy-cells = <0>; + + clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&rpmhcc RPMH_CXO_CLK>; + clock-names = "iface", "ref"; + vdds-supply = <&vreg_dsi_phy>; + }; + + dsi@ae96000 { + compatible = "qcom,sm8450-dsi-ctrl", "qcom,mdss-dsi-ctrl"; + reg = <0x0ae96000 0x400>; + reg-names = "dsi_ctrl"; + + interrupt-parent = <&mdss>; + interrupts = <5>; + + clocks = <&dispcc DISP_CC_MDSS_BYTE1_CLK>, + <&dispcc DISP_CC_MDSS_BYTE1_INTF_CLK>, + <&dispcc DISP_CC_MDSS_PCLK1_CLK>, + <&dispcc DISP_CC_MDSS_ESC1_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_BYTE1_CLK_SRC>, + <&dispcc DISP_CC_MDSS_PCLK1_CLK_SRC>; + assigned-clock-parents = <&dsi1_phy 0>, <&dsi1_phy 1>; + + operating-points-v2 = <&dsi_opp_table>; + power-domains = <&rpmhpd SM8450_MMCX>; + + phys = <&dsi1_phy>; + phy-names = "dsi"; + + #address-cells = <1>; + #size-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dsi1_in: endpoint { + remote-endpoint = <&dpu_intf2_out>; + }; + }; + + port@1 { + reg = <1>; + dsi1_out: endpoint { + }; + }; + }; + }; + + dsi1_phy: phy@ae96400 { + compatible = "qcom,dsi-phy-5nm-8450"; + reg = <0x0ae96400 0x200>, + <0x0ae96600 0x280>, + <0x0ae96900 0x260>; + reg-names = "dsi_phy", + "dsi_phy_lane", + "dsi_pll"; + + #clock-cells = <1>; + #phy-cells = <0>; + + clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&rpmhcc RPMH_CXO_CLK>; + clock-names = "iface", "ref"; + vdds-supply = <&vreg_dsi_phy>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/panel/auo,a030jtn01.yaml b/Documentation/devicetree/bindings/display/panel/auo,a030jtn01.yaml new file mode 100644 index 000000000000..86c834eb4d98 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/auo,a030jtn01.yaml @@ -0,0 +1,60 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/auo,a030jtn01.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: AUO A030JTN01 3.0" (320x480 pixels) 24-bit TFT LCD panel + +description: | + Delta RGB 8-bit panel found in some Retrogame handhelds + +maintainers: + - Paul Cercueil <paul@crapouillou.net> + - Christophe Branchereau <cbranchereau@gmail.com> + +allOf: + - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# + +properties: + compatible: + const: auo,a030jtn01 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - power-supply + - reset-gpios + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + spi { + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "auo,a030jtn01"; + reg = <0>; + + spi-max-frequency = <10000000>; + + reset-gpios = <&gpe 4 GPIO_ACTIVE_LOW>; + power-supply = <&lcd_power>; + + backlight = <&backlight>; + + port { + panel_input: endpoint { + remote-endpoint = <&panel_output>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/focaltech,gpt3.yaml b/Documentation/devicetree/bindings/display/panel/focaltech,gpt3.yaml new file mode 100644 index 000000000000..d54e96b2a9e1 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/focaltech,gpt3.yaml @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/focaltech,gpt3.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Focaltech GPT3 3.0" (640x480 pixels) IPS LCD panel + +maintainers: + - Christophe Branchereau <cbranchereau@gmail.com> + +allOf: + - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# + +properties: + compatible: + const: focaltech,gpt3 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - power-supply + - reset-gpios + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + spi { + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "focaltech,gpt3"; + reg = <0>; + + spi-max-frequency = <3125000>; + + reset-gpios = <&gpe 2 GPIO_ACTIVE_LOW>; + + backlight = <&backlight>; + power-supply = <&vcc>; + + port { + panel_input: endpoint { + remote-endpoint = <&panel_output>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/himax,hx8394.yaml b/Documentation/devicetree/bindings/display/panel/himax,hx8394.yaml new file mode 100644 index 000000000000..1b2a1baa26f9 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/himax,hx8394.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/himax,hx8394.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Himax HX8394 MIPI-DSI LCD panel controller + +maintainers: + - Ondrej Jirman <megi@xff.cz> + - Javier Martinez Canillas <javierm@redhat.com> + +description: + Device tree bindings for panels based on the Himax HX8394 controller, + such as the HannStar HSD060BHW4 720x1440 TFT LCD panel connected with + a MIPI-DSI video interface. + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + items: + - enum: + - hannstar,hsd060bhw4 + - const: himax,hx8394 + + reg: true + + reset-gpios: true + + backlight: true + + port: true + + vcc-supply: + description: Panel power supply + + iovcc-supply: + description: I/O voltage supply + +required: + - compatible + - reg + - reset-gpios + - backlight + - port + - vcc-supply + - iovcc-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + dsi { + #address-cells = <1>; + #size-cells = <0>; + panel@0 { + compatible = "hannstar,hsd060bhw4", "himax,hx8394"; + reg = <0>; + vcc-supply = <®_2v8_p>; + iovcc-supply = <®_1v8_p>; + reset-gpios = <&gpio3 13 GPIO_ACTIVE_LOW>; + backlight = <&backlight>; + + port { + mipi_in_panel: endpoint { + remote-endpoint = <&mipi_out_panel>; + }; + }; + }; + }; + +... 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 c2df8d28aaf5..9b701df5e9d2 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-mipi-dbi-spi.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-mipi-dbi-spi.yaml @@ -22,8 +22,9 @@ description: | The standard defines the following interface signals for type C: - Power: - Vdd: Power supply for display module + Called power-supply in this binding. - Vddi: Logic level supply for interface signals - Combined into one in this binding called: power-supply + Called io-supply in this binding. - Interface: - CSx: Chip select - SCL: Serial clock @@ -80,6 +81,11 @@ properties: Controller data/command selection (D/CX) in 4-line SPI mode. If not set, the controller is in 3-line SPI mode. + io-supply: + description: | + Logic level supply for interface signals (Vddi). + No need to set if this is the same as power-supply. + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/panel/visionox,vtdr6130.yaml b/Documentation/devicetree/bindings/display/panel/visionox,vtdr6130.yaml new file mode 100644 index 000000000000..84562a5b710a --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/visionox,vtdr6130.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/visionox,vtdr6130.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Visionox VTDR6130 AMOLED DSI Panel + +maintainers: + - Neil Armstrong <neil.armstrong@linaro.org> + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: visionox,vtdr6130 + + reg: + maxItems: 1 + description: DSI virtual channel + + vddio-supply: true + vci-supply: true + vdd-supply: true + port: true + reset-gpios: true + +additionalProperties: false + +required: + - compatible + - reg + - vddio-supply + - vci-supply + - vdd-supply + - reset-gpios + - port + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + dsi { + #address-cells = <1>; + #size-cells = <0>; + panel@0 { + compatible = "visionox,vtdr6130"; + reg = <0>; + + vddio-supply = <&vreg_l12b_1p8>; + vci-supply = <&vreg_l13b_3p0>; + vdd-supply = <&vreg_l11b_1p2>; + + reset-gpios = <&tlmm 133 GPIO_ACTIVE_LOW>; + + port { + panel0_in: endpoint { + remote-endpoint = <&dsi0_out>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/renesas,du.yaml b/Documentation/devicetree/bindings/display/renesas,du.yaml index b3e588022082..d4830f52c512 100644 --- a/Documentation/devicetree/bindings/display/renesas,du.yaml +++ b/Documentation/devicetree/bindings/display/renesas,du.yaml @@ -40,6 +40,7 @@ properties: - renesas,du-r8a77990 # for R-Car E3 compatible DU - renesas,du-r8a77995 # for R-Car D3 compatible DU - renesas,du-r8a779a0 # for R-Car V3U compatible DU + - renesas,du-r8a779g0 # for R-Car V4H compatible DU reg: maxItems: 1 @@ -762,6 +763,7 @@ allOf: contains: enum: - renesas,du-r8a779a0 + - renesas,du-r8a779g0 then: properties: clocks: diff --git a/Documentation/devicetree/bindings/display/simple-framebuffer.yaml b/Documentation/devicetree/bindings/display/simple-framebuffer.yaml index dd64f70b5014..3c9f29e428a4 100644 --- a/Documentation/devicetree/bindings/display/simple-framebuffer.yaml +++ b/Documentation/devicetree/bindings/display/simple-framebuffer.yaml @@ -63,6 +63,11 @@ properties: reg: description: Location and size of the framebuffer memory + memory-region: + maxItems: 1 + description: Phandle to a node describing the memory to be used for the + framebuffer. If present, overrides the "reg" property (if one exists). + clocks: description: List of clocks used by the framebuffer. @@ -94,6 +99,7 @@ properties: * `x1r5g5b5` - 16-bit pixels, d[14:10]=r, d[9:5]=g, d[4:0]=b * `x2r10g10b10` - 32-bit pixels, d[29:20]=r, d[19:10]=g, d[9:0]=b * `x8r8g8b8` - 32-bit pixels, d[23:16]=r, d[15:8]=g, d[7:0]=b + * `x8b8g8r8` - 32-bit pixels, d[23:16]=b, d[15:8]=g, d[7:0]=r enum: - a1r5g5b5 - a2r10g10b10 @@ -105,6 +111,7 @@ properties: - x1r5g5b5 - x2r10g10b10 - x8r8g8b8 + - x8b8g8r8 display: $ref: /schemas/types.yaml#/definitions/phandle diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra186-display.yaml b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra186-display.yaml index ce5c673f940c..117c371ce24b 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra186-display.yaml +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra186-display.yaml @@ -20,10 +20,10 @@ properties: - nvidia,tegra194-display '#address-cells': - const: 1 + enum: [ 1, 2 ] '#size-cells': - const: 1 + enum: [ 1, 2 ] reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-dc.yaml b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-dc.yaml index 6eedee503aa0..69be95afd562 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-dc.yaml +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-dc.yaml @@ -59,8 +59,7 @@ properties: iommus: maxItems: 1 - operating-points-v2: - $ref: "/schemas/types.yaml#/definitions/phandle" + operating-points-v2: true power-domains: items: diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-dsi.yaml b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-dsi.yaml index 75546f250ad7..511cbe74e729 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-dsi.yaml +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-dsi.yaml @@ -47,8 +47,7 @@ properties: items: - const: dsi - operating-points-v2: - $ref: "/schemas/types.yaml#/definitions/phandle" + operating-points-v2: true power-domains: maxItems: 1 diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-epp.yaml b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-epp.yaml index 0d55e6206b5e..3c095a5491fe 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-epp.yaml +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-epp.yaml @@ -46,8 +46,7 @@ properties: interconnect-names: maxItems: 4 - operating-points-v2: - $ref: "/schemas/types.yaml#/definitions/phandle" + operating-points-v2: true power-domains: items: diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-gr2d.yaml b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-gr2d.yaml index bf38accd98eb..1026b0bc3dc8 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-gr2d.yaml +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-gr2d.yaml @@ -49,8 +49,7 @@ properties: interconnect-names: maxItems: 4 - operating-points-v2: - $ref: "/schemas/types.yaml#/definitions/phandle" + operating-points-v2: true power-domains: items: diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-gr3d.yaml b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-gr3d.yaml index 4755a73473c7..59a52e732ca3 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-gr3d.yaml +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-gr3d.yaml @@ -51,8 +51,7 @@ properties: minItems: 4 maxItems: 10 - operating-points-v2: - $ref: "/schemas/types.yaml#/definitions/phandle" + operating-points-v2: true power-domains: minItems: 1 diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-hdmi.yaml b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-hdmi.yaml index 035b9f1f2eb5..f65e59cfffa7 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-hdmi.yaml @@ -50,8 +50,7 @@ properties: items: - const: hdmi - operating-points-v2: - $ref: "/schemas/types.yaml#/definitions/phandle" + operating-points-v2: true power-domains: items: diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.yaml b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.yaml index 913ca104c871..94c5242c03b2 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.yaml +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.yaml @@ -90,8 +90,7 @@ properties: items: - const: dma-mem # read - operating-points-v2: - $ref: "/schemas/types.yaml#/definitions/phandle" + operating-points-v2: true power-domains: items: diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-mpe.yaml b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-mpe.yaml index 5f4f0fb4b692..2cd3e60cd0a8 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-mpe.yaml +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-mpe.yaml @@ -47,8 +47,7 @@ properties: interconnect-names: maxItems: 6 - operating-points-v2: - $ref: "/schemas/types.yaml#/definitions/phandle" + operating-points-v2: true power-domains: items: diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-tvo.yaml b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-tvo.yaml index 467b015e5700..6c84d8b7eb7b 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-tvo.yaml +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-tvo.yaml @@ -30,8 +30,7 @@ properties: items: - description: module clock - operating-points-v2: - $ref: "/schemas/types.yaml#/definitions/phandle" + operating-points-v2: true power-domains: items: diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-vi.yaml b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-vi.yaml index 782a4b10150a..a42bf33d1e7d 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-vi.yaml +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-vi.yaml @@ -55,8 +55,7 @@ properties: minItems: 4 maxItems: 5 - operating-points-v2: - $ref: "/schemas/types.yaml#/definitions/phandle" + operating-points-v2: true power-domains: items: diff --git a/Documentation/devicetree/bindings/dma/ti/k3-udma.yaml b/Documentation/devicetree/bindings/dma/ti/k3-udma.yaml index 7ff428ad3aae..97f6ae9b1236 100644 --- a/Documentation/devicetree/bindings/dma/ti/k3-udma.yaml +++ b/Documentation/devicetree/bindings/dma/ti/k3-udma.yaml @@ -44,6 +44,7 @@ description: | allOf: - $ref: "../dma-controller.yaml#" + - $ref: /schemas/arm/keystone/ti,k3-sci-common.yaml# properties: "#dma-cells": @@ -78,14 +79,6 @@ properties: msi-parent: true - ti,sci: - description: phandle to TI-SCI compatible System controller node - $ref: /schemas/types.yaml#/definitions/phandle - - ti,sci-dev-id: - description: TI-SCI device id of UDMAP - $ref: /schemas/types.yaml#/definitions/uint32 - ti,ringacc: description: phandle to the ring accelerator node $ref: /schemas/types.yaml#/definitions/phandle diff --git a/Documentation/devicetree/bindings/dsp/mediatek,mt8186-dsp.yaml b/Documentation/devicetree/bindings/dsp/mediatek,mt8186-dsp.yaml index 3e63f79890b4..88575da1e6d5 100644 --- a/Documentation/devicetree/bindings/dsp/mediatek,mt8186-dsp.yaml +++ b/Documentation/devicetree/bindings/dsp/mediatek,mt8186-dsp.yaml @@ -15,7 +15,9 @@ description: | properties: compatible: - const: mediatek,mt8186-dsp + enum: + - mediatek,mt8186-dsp + - mediatek,mt8188-dsp reg: items: diff --git a/Documentation/devicetree/bindings/firmware/arm,scmi.yaml b/Documentation/devicetree/bindings/firmware/arm,scmi.yaml index 176796931a22..2f7c51c75e85 100644 --- a/Documentation/devicetree/bindings/firmware/arm,scmi.yaml +++ b/Documentation/devicetree/bindings/firmware/arm,scmi.yaml @@ -100,7 +100,9 @@ properties: Channel specifier required when using OP-TEE transport. protocol@11: - type: object + $ref: '#/$defs/protocol-node' + unevaluatedProperties: false + properties: reg: const: 0x11 @@ -112,7 +114,9 @@ properties: - '#power-domain-cells' protocol@13: - type: object + $ref: '#/$defs/protocol-node' + unevaluatedProperties: false + properties: reg: const: 0x13 @@ -124,7 +128,9 @@ properties: - '#clock-cells' protocol@14: - type: object + $ref: '#/$defs/protocol-node' + unevaluatedProperties: false + properties: reg: const: 0x14 @@ -136,7 +142,9 @@ properties: - '#clock-cells' protocol@15: - type: object + $ref: '#/$defs/protocol-node' + unevaluatedProperties: false + properties: reg: const: 0x15 @@ -148,7 +156,9 @@ properties: - '#thermal-sensor-cells' protocol@16: - type: object + $ref: '#/$defs/protocol-node' + unevaluatedProperties: false + properties: reg: const: 0x16 @@ -160,20 +170,31 @@ properties: - '#reset-cells' protocol@17: - type: object + $ref: '#/$defs/protocol-node' + unevaluatedProperties: false + properties: reg: const: 0x17 regulators: type: object + additionalProperties: false description: The list of all regulators provided by this SCMI controller. + properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + patternProperties: - '^regulators@[0-9a-f]+$': + '^regulator@[0-9a-f]+$': type: object $ref: "../regulator/regulator.yaml#" + unevaluatedProperties: false properties: reg: @@ -184,15 +205,17 @@ properties: - reg protocol@18: - type: object + $ref: '#/$defs/protocol-node' + unevaluatedProperties: false + properties: reg: const: 0x18 additionalProperties: false -patternProperties: - '^protocol@[0-9a-f]+$': +$defs: + protocol-node: type: object description: Each sub-node represents a protocol supported. If the platform diff --git a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.yaml b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.yaml index 481901269872..02f0b0462377 100644 --- a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.yaml +++ b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.yaml @@ -44,8 +44,7 @@ properties: items: - const: fuse - operating-points-v2: - $ref: "/schemas/types.yaml#/definitions/phandle" + operating-points-v2: true power-domains: items: diff --git a/Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.txt b/Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.txt deleted file mode 100644 index bef353f370d8..000000000000 --- a/Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.txt +++ /dev/null @@ -1,20 +0,0 @@ -Fujitsu MB86S7x GPIO Controller -------------------------------- - -Required properties: -- compatible: Should be "fujitsu,mb86s70-gpio" -- reg: Base address and length of register space -- clocks: Specify the clock -- gpio-controller: Marks the device node as a gpio controller. -- #gpio-cells: Should be <2>. The first cell is the pin number and the - second cell is used to specify optional parameters: - - bit 0 specifies polarity (0 for normal, 1 for inverted). - -Examples: - gpio0: gpio@31000000 { - compatible = "fujitsu,mb86s70-gpio"; - reg = <0 0x31000000 0x10000>; - gpio-controller; - #gpio-cells = <2>; - clocks = <&clk 0 2 1>; - }; diff --git a/Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.yaml b/Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.yaml new file mode 100644 index 000000000000..d18d95285465 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/fujitsu,mb86s70-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Fujitsu MB86S7x GPIO Controller + +maintainers: + - Jassi Brar <jaswinder.singh@linaro.org> + +properties: + compatible: + oneOf: + - items: + - const: socionext,synquacer-gpio + - const: fujitsu,mb86s70-gpio + - const: fujitsu,mb86s70-gpio + + reg: + maxItems: 1 + + '#gpio-cells': + const: 2 + + gpio-controller: true + gpio-line-names: true + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - '#gpio-cells' + - gpio-controller + - clocks + +additionalProperties: false + +examples: + - | + gpio@31000000 { + compatible = "fujitsu,mb86s70-gpio"; + reg = <0x31000000 0x10000>; + gpio-controller; + #gpio-cells = <2>; + clocks = <&clk 0 2 1>; + }; +... diff --git a/Documentation/devicetree/bindings/gpio/gpio-eic-sprd.txt b/Documentation/devicetree/bindings/gpio/gpio-eic-sprd.txt deleted file mode 100644 index 54040a2bfe3a..000000000000 --- a/Documentation/devicetree/bindings/gpio/gpio-eic-sprd.txt +++ /dev/null @@ -1,97 +0,0 @@ -Spreadtrum EIC controller bindings - -The EIC is the abbreviation of external interrupt controller, which can -be used only in input mode. The Spreadtrum platform has 2 EIC controllers, -one is in digital chip, and another one is in PMIC. The digital chip EIC -controller contains 4 sub-modules: EIC-debounce, EIC-latch, EIC-async and -EIC-sync. But the PMIC EIC controller contains only one EIC-debounce sub- -module. - -The EIC-debounce sub-module provides up to 8 source input signal -connections. A debounce mechanism is used to capture the input signals' -stable status (millisecond resolution) and a single-trigger mechanism -is introduced into this sub-module to enhance the input event detection -reliability. In addition, this sub-module's clock can be shut off -automatically to reduce power dissipation. Moreover the debounce range -is from 1ms to 4s with a step size of 1ms. The input signal will be -ignored if it is asserted for less than 1 ms. - -The EIC-latch sub-module is used to latch some special power down signals -and generate interrupts, since the EIC-latch does not depend on the APB -clock to capture signals. - -The EIC-async sub-module uses a 32kHz clock to capture the short signals -(microsecond resolution) to generate interrupts by level or edge trigger. - -The EIC-sync is similar with GPIO's input function, which is a synchronized -signal input register. It can generate interrupts by level or edge trigger -when detecting input signals. - -Required properties: -- compatible: Should be one of the following: - "sprd,sc9860-eic-debounce", - "sprd,sc9860-eic-latch", - "sprd,sc9860-eic-async", - "sprd,sc9860-eic-sync", - "sprd,sc2731-eic". -- reg: Define the base and range of the I/O address space containing - the GPIO controller registers. -- gpio-controller: Marks the device node as a GPIO controller. -- #gpio-cells: Should be <2>. The first cell is the gpio number and - the second cell is used to specify optional parameters. -- interrupt-controller: Marks the device node as an interrupt controller. -- #interrupt-cells: Should be <2>. Specifies the number of cells needed - to encode interrupt source. -- interrupts: Should be the port interrupt shared by all the gpios. - -Example: - eic_debounce: gpio@40210000 { - compatible = "sprd,sc9860-eic-debounce"; - reg = <0 0x40210000 0 0x80>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>; - }; - - eic_latch: gpio@40210080 { - compatible = "sprd,sc9860-eic-latch"; - reg = <0 0x40210080 0 0x20>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>; - }; - - eic_async: gpio@402100a0 { - compatible = "sprd,sc9860-eic-async"; - reg = <0 0x402100a0 0 0x20>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>; - }; - - eic_sync: gpio@402100c0 { - compatible = "sprd,sc9860-eic-sync"; - reg = <0 0x402100c0 0 0x20>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>; - }; - - pmic_eic: gpio@300 { - compatible = "sprd,sc2731-eic"; - reg = <0x300>; - interrupt-parent = <&sc2731_pmic>; - interrupts = <5 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; - }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-sprd.txt b/Documentation/devicetree/bindings/gpio/gpio-sprd.txt deleted file mode 100644 index eca97d45388f..000000000000 --- a/Documentation/devicetree/bindings/gpio/gpio-sprd.txt +++ /dev/null @@ -1,28 +0,0 @@ -Spreadtrum GPIO controller bindings - -The controller's registers are organized as sets of sixteen 16-bit -registers with each set controlling a bank of up to 16 pins. A single -interrupt is shared for all of the banks handled by the controller. - -Required properties: -- compatible: Should be "sprd,sc9860-gpio". -- reg: Define the base and range of the I/O address space containing -the GPIO controller registers. -- gpio-controller: Marks the device node as a GPIO controller. -- #gpio-cells: Should be <2>. The first cell is the gpio number and -the second cell is used to specify optional parameters. -- interrupt-controller: Marks the device node as an interrupt controller. -- #interrupt-cells: Should be <2>. Specifies the number of cells needed -to encode interrupt source. -- interrupts: Should be the port interrupt shared by all the gpios. - -Example: - ap_gpio: gpio@40280000 { - compatible = "sprd,sc9860-gpio"; - reg = <0 0x40280000 0 0x1000>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = <GIC_SPI 50 IRQ_TYPE_LEVEL_HIGH>; - }; diff --git a/Documentation/devicetree/bindings/gpio/sprd,gpio-eic.yaml b/Documentation/devicetree/bindings/gpio/sprd,gpio-eic.yaml new file mode 100644 index 000000000000..99fcf970773a --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/sprd,gpio-eic.yaml @@ -0,0 +1,124 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright 2022 Unisoc Inc. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/sprd,gpio-eic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Unisoc EIC controller + +maintainers: + - Orson Zhai <orsonzhai@gmail.com> + - Baolin Wang <baolin.wang7@gmail.com> + - Chunyan Zhang <zhang.lyra@gmail.com> + +description: | + The EIC is the abbreviation of external interrupt controller, which can + be used only in input mode. The Spreadtrum platform has 2 EIC controllers, + one is in digital chip, and another one is in PMIC. The digital chip EIC + controller contains 4 sub-modules, i.e. EIC-debounce, EIC-latch, EIC-async and + EIC-sync. But the PMIC EIC controller contains only one EIC-debounce sub- + module. + + The EIC-debounce sub-module provides up to 8 source input signal + connections. A debounce mechanism is used to capture the input signals' + stable status (millisecond resolution) and a single-trigger mechanism + is introduced into this sub-module to enhance the input event detection + reliability. In addition, this sub-module's clock can be shut off + automatically to reduce power dissipation. Moreover the debounce range + is from 1ms to 4s with a step size of 1ms. The input signal will be + ignored if it is asserted for less than 1 ms. + + The EIC-latch sub-module is used to latch some special power down signals + and generate interrupts, since the EIC-latch does not depend on the APB + clock to capture signals. + + The EIC-async sub-module uses a 32kHz clock to capture the short signals + (microsecond resolution) to generate interrupts by level or edge trigger. + + The EIC-sync is similar with GPIO's input function, which is a synchronized + signal input register. It can generate interrupts by level or edge trigger + when detecting input signals. + +properties: + compatible: + oneOf: + - enum: + - sprd,sc9860-eic-debounce + - sprd,sc9860-eic-latch + - sprd,sc9860-eic-async + - sprd,sc9860-eic-sync + - sprd,sc2731-eic + - items: + - enum: + - sprd,ums512-eic-debounce + - const: sprd,sc9860-eic-debounce + - items: + - enum: + - sprd,ums512-eic-latch + - const: sprd,sc9860-eic-latch + - items: + - enum: + - sprd,ums512-eic-async + - const: sprd,sc9860-eic-async + - items: + - enum: + - sprd,ums512-eic-sync + - const: sprd,sc9860-eic-sync + - items: + - enum: + - sprd,sc2730-eic + - const: sprd,sc2731-eic + + reg: + minItems: 1 + maxItems: 3 + description: + EIC controller can support maximum 3 banks which has its own + address base. + + gpio-controller: true + + "#gpio-cells": + const: 2 + + interrupt-controller: true + + "#interrupt-cells": + const: 2 + + interrupts: + maxItems: 1 + description: + The interrupt shared by all GPIO lines for this controller. + +required: + - compatible + - reg + - gpio-controller + - "#gpio-cells" + - interrupt-controller + - "#interrupt-cells" + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + eic_debounce: gpio@40210000 { + compatible = "sprd,sc9860-eic-debounce"; + reg = <0 0x40210000 0 0x80>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/gpio/sprd,gpio.yaml b/Documentation/devicetree/bindings/gpio/sprd,gpio.yaml new file mode 100644 index 000000000000..483168838128 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/sprd,gpio.yaml @@ -0,0 +1,75 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright 2022 Unisoc Inc. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/sprd,gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Unisoc GPIO controller + +maintainers: + - Orson Zhai <orsonzhai@gmail.com> + - Baolin Wang <baolin.wang7@gmail.com> + - Chunyan Zhang <zhang.lyra@gmail.com> + +description: | + The controller's registers are organized as sets of sixteen 16-bit + registers with each set controlling a bank of up to 16 pins. A single + interrupt is shared for all of the banks handled by the controller. + +properties: + compatible: + oneOf: + - const: sprd,sc9860-gpio + - items: + - enum: + - sprd,ums512-gpio + - const: sprd,sc9860-gpio + + reg: + maxItems: 1 + + gpio-controller: true + + "#gpio-cells": + const: 2 + + interrupt-controller: true + + "#interrupt-cells": + const: 2 + + interrupts: + maxItems: 1 + description: The interrupt shared by all GPIO lines for this controller. + +required: + - compatible + - reg + - gpio-controller + - "#gpio-cells" + - interrupt-controller + - "#interrupt-cells" + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + ap_gpio: gpio@40280000 { + compatible = "sprd,sc9860-gpio"; + reg = <0 0x40280000 0 0x1000>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 50 IRQ_TYPE_LEVEL_HIGH>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/hwmon/adi,adm1177.yaml b/Documentation/devicetree/bindings/hwmon/adi,adm1177.yaml index d794deb08bb7..ca2b47320689 100644 --- a/Documentation/devicetree/bindings/hwmon/adi,adm1177.yaml +++ b/Documentation/devicetree/bindings/hwmon/adi,adm1177.yaml @@ -52,16 +52,16 @@ examples: - | #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/interrupt-controller/irq.h> - i2c0 { + i2c { #address-cells = <1>; #size-cells = <0>; pwmon@5a { - compatible = "adi,adm1177"; - reg = <0x5a>; - shunt-resistor-micro-ohms = <50000>; /* 50 mOhm */ - adi,shutdown-threshold-microamp = <1059000>; /* 1.059 A */ - adi,vrange-high-enable; + compatible = "adi,adm1177"; + reg = <0x5a>; + shunt-resistor-micro-ohms = <50000>; /* 50 mOhm */ + adi,shutdown-threshold-microamp = <1059000>; /* 1.059 A */ + adi,vrange-high-enable; }; }; ... diff --git a/Documentation/devicetree/bindings/hwmon/adi,adm1266.yaml b/Documentation/devicetree/bindings/hwmon/adi,adm1266.yaml index 43b4f4f57b49..4f8e11bd5142 100644 --- a/Documentation/devicetree/bindings/hwmon/adi,adm1266.yaml +++ b/Documentation/devicetree/bindings/hwmon/adi,adm1266.yaml @@ -39,13 +39,13 @@ additionalProperties: false examples: - | - i2c0 { + i2c { #address-cells = <1>; #size-cells = <0>; adm1266@40 { - compatible = "adi,adm1266"; - reg = <0x40>; + compatible = "adi,adm1266"; + reg = <0x40>; }; }; ... diff --git a/Documentation/devicetree/bindings/hwmon/adi,axi-fan-control.yaml b/Documentation/devicetree/bindings/hwmon/adi,axi-fan-control.yaml index f2f99afb3a3b..0cf3ed6212a6 100644 --- a/Documentation/devicetree/bindings/hwmon/adi,axi-fan-control.yaml +++ b/Documentation/devicetree/bindings/hwmon/adi,axi-fan-control.yaml @@ -49,15 +49,15 @@ additionalProperties: false examples: - | fpga_axi: fpga-axi { - #address-cells = <0x2>; - #size-cells = <0x1>; - - axi_fan_control: axi-fan-control@80000000 { - compatible = "adi,axi-fan-control-1.00.a"; - reg = <0x0 0x80000000 0x10000>; - clocks = <&clk 71>; - interrupts = <0 110 0>; - pulses-per-revolution = <2>; - }; + #address-cells = <0x2>; + #size-cells = <0x1>; + + axi_fan_control: axi-fan-control@80000000 { + compatible = "adi,axi-fan-control-1.00.a"; + reg = <0x0 0x80000000 0x10000>; + clocks = <&clk 71>; + interrupts = <0 110 0>; + pulses-per-revolution = <2>; + }; }; ... diff --git a/Documentation/devicetree/bindings/hwmon/adi,ltc2945.yaml b/Documentation/devicetree/bindings/hwmon/adi,ltc2945.yaml new file mode 100644 index 000000000000..5cb66e97e816 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/adi,ltc2945.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/hwmon/adi,ltc2945.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices LTC2945 wide range i2c power monitor + +maintainers: + - Guenter Roeck <linux@roeck-us.net> + +description: | + Analog Devices LTC2945 wide range i2c power monitor over I2C. + + https://www.analog.com/media/en/technical-documentation/data-sheets/LTC2945.pdf + +properties: + compatible: + enum: + - adi,ltc2945 + + reg: + maxItems: 1 + + shunt-resistor-micro-ohms: + description: + Shunt resistor value in micro-Ohms + default: 1000 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + power-monitor@6e { + compatible = "adi,ltc2945"; + reg = <0x6e>; + /* 10 milli-Ohm shunt resistor */ + shunt-resistor-micro-ohms = <10000>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/hwmon/adi,ltc2947.yaml b/Documentation/devicetree/bindings/hwmon/adi,ltc2947.yaml index bf04151b63d2..152935334c76 100644 --- a/Documentation/devicetree/bindings/hwmon/adi,ltc2947.yaml +++ b/Documentation/devicetree/bindings/hwmon/adi,ltc2947.yaml @@ -87,15 +87,15 @@ additionalProperties: false examples: - | spi { - #address-cells = <1>; - #size-cells = <0>; - - ltc2947_spi: ltc2947@0 { - compatible = "adi,ltc2947"; - reg = <0>; - /* accumulation takes place always for energ1/charge1. */ - /* accumulation only on positive current for energy2/charge2. */ - adi,accumulator-ctl-pol = <0 1>; - }; + #address-cells = <1>; + #size-cells = <0>; + + ltc2947_spi: ltc2947@0 { + compatible = "adi,ltc2947"; + reg = <0>; + /* accumulation takes place always for energ1/charge1. */ + /* accumulation only on positive current for energy2/charge2. */ + adi,accumulator-ctl-pol = <0 1>; + }; }; ... diff --git a/Documentation/devicetree/bindings/hwmon/adi,ltc2992.yaml b/Documentation/devicetree/bindings/hwmon/adi,ltc2992.yaml index 64a8fcb7bc46..dba74f400bc2 100644 --- a/Documentation/devicetree/bindings/hwmon/adi,ltc2992.yaml +++ b/Documentation/devicetree/bindings/hwmon/adi,ltc2992.yaml @@ -55,26 +55,26 @@ additionalProperties: false examples: - | - i2c1 { + i2c { #address-cells = <1>; #size-cells = <0>; - ltc2992@6F { - #address-cells = <1>; - #size-cells = <0>; + ltc2992@6f { + #address-cells = <1>; + #size-cells = <0>; - compatible = "adi,ltc2992"; - reg = <0x6F>; + compatible = "adi,ltc2992"; + reg = <0x6f>; - channel@0 { - reg = <0x0>; - shunt-resistor-micro-ohms = <10000>; - }; + channel@0 { + reg = <0x0>; + shunt-resistor-micro-ohms = <10000>; + }; - channel@1 { - reg = <0x1>; - shunt-resistor-micro-ohms = <10000>; - }; + channel@1 { + reg = <0x1>; + shunt-resistor-micro-ohms = <10000>; + }; }; }; ... diff --git a/Documentation/devicetree/bindings/hwmon/amd,sbrmi.yaml b/Documentation/devicetree/bindings/hwmon/amd,sbrmi.yaml index 7598b083979c..353d81d89bf5 100644 --- a/Documentation/devicetree/bindings/hwmon/amd,sbrmi.yaml +++ b/Documentation/devicetree/bindings/hwmon/amd,sbrmi.yaml @@ -41,13 +41,13 @@ additionalProperties: false examples: - | - i2c0 { + i2c { #address-cells = <1>; #size-cells = <0>; sbrmi@3c { - compatible = "amd,sbrmi"; - reg = <0x3c>; + compatible = "amd,sbrmi"; + reg = <0x3c>; }; }; ... diff --git a/Documentation/devicetree/bindings/hwmon/amd,sbtsi.yaml b/Documentation/devicetree/bindings/hwmon/amd,sbtsi.yaml index 446b09f1ce94..75088244a274 100644 --- a/Documentation/devicetree/bindings/hwmon/amd,sbtsi.yaml +++ b/Documentation/devicetree/bindings/hwmon/amd,sbtsi.yaml @@ -42,13 +42,13 @@ additionalProperties: false examples: - | - i2c0 { + i2c { #address-cells = <1>; #size-cells = <0>; sbtsi@4c { - compatible = "amd,sbtsi"; - reg = <0x4c>; + compatible = "amd,sbtsi"; + reg = <0x4c>; }; }; ... diff --git a/Documentation/devicetree/bindings/hwmon/hpe,gxp-fan-ctrl.yaml b/Documentation/devicetree/bindings/hwmon/hpe,gxp-fan-ctrl.yaml new file mode 100644 index 000000000000..4a52aac6be72 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/hpe,gxp-fan-ctrl.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/hwmon/hpe,gxp-fan-ctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: HPE GXP Fan Controller + +maintainers: + - Nick Hawkins <nick.hawkins@hpe.com> + +description: | + The HPE GXP fan controller controls the fans through an external CPLD + device that connects to the fans. + +properties: + compatible: + const: hpe,gxp-fan-ctrl + + reg: + items: + - description: Fan controller PWM + - description: Programmable logic + - description: Function 2 + + reg-names: + items: + - const: base + - const: pl + - const: fn2 + +required: + - compatible + - reg + - reg-names + +additionalProperties: false + +examples: + - | + fan-controller@1000c00 { + compatible = "hpe,gxp-fan-ctrl"; + reg = <0x1000c00 0x200>, <0xd1000000 0xff>, <0x80200000 0x100000>; + reg-names = "base", "pl", "fn2"; + }; diff --git a/Documentation/devicetree/bindings/hwmon/iio-hwmon.yaml b/Documentation/devicetree/bindings/hwmon/iio-hwmon.yaml index e1ccbd30e0eb..c54b5986b365 100644 --- a/Documentation/devicetree/bindings/hwmon/iio-hwmon.yaml +++ b/Documentation/devicetree/bindings/hwmon/iio-hwmon.yaml @@ -31,7 +31,7 @@ additionalProperties: false examples: - | - iio-hwmon { - compatible = "iio-hwmon"; - io-channels = <&adc 1>, <&adc 2>; - }; + iio-hwmon { + compatible = "iio-hwmon"; + io-channels = <&adc 1>, <&adc 2>; + }; diff --git a/Documentation/devicetree/bindings/hwmon/national,lm90.yaml b/Documentation/devicetree/bindings/hwmon/national,lm90.yaml index e1719839faf0..7b9d48d6d6da 100644 --- a/Documentation/devicetree/bindings/hwmon/national,lm90.yaml +++ b/Documentation/devicetree/bindings/hwmon/national,lm90.yaml @@ -198,30 +198,30 @@ examples: }; - | i2c { - #address-cells = <1>; - #size-cells = <0>; - - sensor@4c { - compatible = "adi,adt7481"; - reg = <0x4c>; #address-cells = <1>; #size-cells = <0>; - channel@0 { - reg = <0x0>; - label = "local"; - }; - - channel@1 { - reg = <0x1>; - label = "front"; - temperature-offset-millicelsius = <4000>; - }; - - channel@2 { - reg = <0x2>; - label = "back"; - temperature-offset-millicelsius = <750>; + sensor@4c { + compatible = "adi,adt7481"; + reg = <0x4c>; + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + reg = <0x0>; + label = "local"; + }; + + channel@1 { + reg = <0x1>; + label = "front"; + temperature-offset-millicelsius = <4000>; + }; + + channel@2 { + reg = <0x2>; + label = "back"; + temperature-offset-millicelsius = <750>; + }; }; - }; }; diff --git a/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml b/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml index 6a1920712fb9..3d0146e20d3e 100644 --- a/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml +++ b/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml @@ -131,7 +131,7 @@ additionalProperties: false examples: - | - thermistor0 { + thermistor { compatible = "murata,ncp18wb473"; io-channels = <&gpadc 0x06>; pullup-uv = <1800000>; diff --git a/Documentation/devicetree/bindings/hwmon/nuvoton,nct7802.yaml b/Documentation/devicetree/bindings/hwmon/nuvoton,nct7802.yaml index 2f0620ecccc9..cd8dcd797031 100644 --- a/Documentation/devicetree/bindings/hwmon/nuvoton,nct7802.yaml +++ b/Documentation/devicetree/bindings/hwmon/nuvoton,nct7802.yaml @@ -123,23 +123,23 @@ examples: #size-cells = <0>; channel@0 { /* LTD */ - reg = <0>; + reg = <0>; }; channel@1 { /* RTD1 */ - reg = <1>; - sensor-type = "voltage"; + reg = <1>; + sensor-type = "voltage"; }; channel@2 { /* RTD2 */ - reg = <2>; - sensor-type = "temperature"; - temperature-mode = "thermal-diode"; + reg = <2>; + sensor-type = "temperature"; + temperature-mode = "thermal-diode"; }; channel@3 { /* RTD3 */ - reg = <3>; - sensor-type = "temperature"; + reg = <3>; + sensor-type = "temperature"; }; }; }; diff --git a/Documentation/devicetree/bindings/hwmon/nxp,mc34vr500.yaml b/Documentation/devicetree/bindings/hwmon/nxp,mc34vr500.yaml new file mode 100644 index 000000000000..306f67315835 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/nxp,mc34vr500.yaml @@ -0,0 +1,36 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/hwmon/nxp,mc34vr500.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP MC34VR500 hwmon sensor + +maintainers: + - Mario Kicherer <dev@kicherer.org> + +properties: + compatible: + enum: + - nxp,mc34vr500 + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@8 { + compatible = "nxp,mc34vr500"; + reg = <0x08>; + }; + }; diff --git a/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml b/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml index 1502b22c77cc..fde5225ce012 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml @@ -77,15 +77,15 @@ additionalProperties: false examples: - | i2c { - #address-cells = <1>; - #size-cells = <0>; - - tmp513@5c { - compatible = "ti,tmp513"; - reg = <0x5C>; - shunt-resistor-micro-ohms = <330000>; - ti,bus-range-microvolt = <32000000>; - ti,pga-gain = <8>; - ti,nfactor = <0x1 0xF3 0x00>; - }; + #address-cells = <1>; + #size-cells = <0>; + + tmp513@5c { + compatible = "ti,tmp513"; + reg = <0x5c>; + shunt-resistor-micro-ohms = <330000>; + ti,bus-range-microvolt = <32000000>; + ti,pga-gain = <8>; + ti,nfactor = <0x1 0xf3 0x00>; + }; }; diff --git a/Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml b/Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml index 3bc8e73dfbf0..bce68a326919 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml @@ -40,12 +40,12 @@ additionalProperties: false examples: - | i2c { - #address-cells = <1>; - #size-cells = <0>; - - tps23861@30 { - compatible = "ti,tps23861"; - reg = <0x30>; - shunt-resistor-micro-ohms = <255000>; - }; + #address-cells = <1>; + #size-cells = <0>; + + tps23861@30 { + compatible = "ti,tps23861"; + reg = <0x30>; + shunt-resistor-micro-ohms = <255000>; + }; }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-synquacer.txt b/Documentation/devicetree/bindings/i2c/i2c-synquacer.txt deleted file mode 100644 index 72f4a2f0fedc..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-synquacer.txt +++ /dev/null @@ -1,29 +0,0 @@ -Socionext SynQuacer I2C - -Required properties: -- compatible : Must be "socionext,synquacer-i2c" -- reg : Offset and length of the register set for the device -- interrupts : A single interrupt specifier -- #address-cells : Must be <1>; -- #size-cells : Must be <0>; -- clock-names : Must contain "pclk". -- clocks : Must contain an entry for each name in clock-names. - (See the common clock bindings.) - -Optional properties: -- clock-frequency : Desired I2C bus clock frequency in Hz. As only Normal and - Fast modes are supported, possible values are 100000 and - 400000. - -Example : - - i2c@51210000 { - compatible = "socionext,synquacer-i2c"; - reg = <0x51210000 0x1000>; - interrupts = <GIC_SPI 165 IRQ_TYPE_LEVEL_HIGH>; - #address-cells = <1>; - #size-cells = <0>; - clock-names = "pclk"; - clocks = <&clk_i2c>; - clock-frequency = <400000>; - }; diff --git a/Documentation/devicetree/bindings/i2c/qcom,i2c-geni-qcom.yaml b/Documentation/devicetree/bindings/i2c/qcom,i2c-geni-qcom.yaml index f5f7dc8f325c..0e88c85985b5 100644 --- a/Documentation/devicetree/bindings/i2c/qcom,i2c-geni-qcom.yaml +++ b/Documentation/devicetree/bindings/i2c/qcom,i2c-geni-qcom.yaml @@ -46,6 +46,8 @@ properties: interrupts: maxItems: 1 + operating-points-v2: true + pinctrl-0: true pinctrl-1: true diff --git a/Documentation/devicetree/bindings/i2c/renesas,rzv2m.yaml b/Documentation/devicetree/bindings/i2c/renesas,rzv2m.yaml index c46378efc123..92e899905ef8 100644 --- a/Documentation/devicetree/bindings/i2c/renesas,rzv2m.yaml +++ b/Documentation/devicetree/bindings/i2c/renesas,rzv2m.yaml @@ -16,7 +16,7 @@ properties: compatible: items: - enum: - - renesas,i2c-r9a09g011 # RZ/V2M + - renesas,r9a09g011-i2c # RZ/V2M - const: renesas,rzv2m-i2c reg: @@ -66,7 +66,7 @@ examples: #include <dt-bindings/interrupt-controller/arm-gic.h> i2c0: i2c@a4030000 { - compatible = "renesas,i2c-r9a09g011", "renesas,rzv2m-i2c"; + compatible = "renesas,r9a09g011-i2c", "renesas,rzv2m-i2c"; reg = <0xa4030000 0x80>; interrupts = <GIC_SPI 232 IRQ_TYPE_EDGE_RISING>, <GIC_SPI 236 IRQ_TYPE_EDGE_RISING>; diff --git a/Documentation/devicetree/bindings/i2c/socionext,synquacer-i2c.yaml b/Documentation/devicetree/bindings/i2c/socionext,synquacer-i2c.yaml new file mode 100644 index 000000000000..f9d6e2038bb4 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/socionext,synquacer-i2c.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/socionext,synquacer-i2c.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext SynQuacer I2C Controller + +maintainers: + - Ard Biesheuvel <ardb@kernel.org> + +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml# + +properties: + compatible: + const: socionext,synquacer-i2c + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + const: pclk + + clock-frequency: + minimum: 100000 + maximum: 400000 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + i2c@51210000 { + compatible = "socionext,synquacer-i2c"; + reg = <0x51210000 0x1000>; + interrupts = <GIC_SPI 165 IRQ_TYPE_LEVEL_HIGH>; + #address-cells = <1>; + #size-cells = <0>; + clock-names = "pclk"; + clocks = <&clk_i2c>; + clock-frequency = <400000>; + }; +... diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adis16201.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adis16201.yaml index 7332442e5661..b6ba7ad1a8d5 100644 --- a/Documentation/devicetree/bindings/iio/accel/adi,adis16201.yaml +++ b/Documentation/devicetree/bindings/iio/accel/adi,adis16201.yaml @@ -41,7 +41,7 @@ unevaluatedProperties: false examples: - | #include <dt-bindings/interrupt-controller/irq.h> - spi0 { + spi { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adis16240.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adis16240.yaml index f6f97164c2ca..5887021cc90f 100644 --- a/Documentation/devicetree/bindings/iio/accel/adi,adis16240.yaml +++ b/Documentation/devicetree/bindings/iio/accel/adi,adis16240.yaml @@ -39,7 +39,7 @@ examples: - | #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/interrupt-controller/irq.h> - spi0 { + spi { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adxl313.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adxl313.yaml index 185b68ffb536..0c5b64cae965 100644 --- a/Documentation/devicetree/bindings/iio/accel/adi,adxl313.yaml +++ b/Documentation/devicetree/bindings/iio/accel/adi,adxl313.yaml @@ -59,7 +59,7 @@ examples: - | #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/interrupt-controller/irq.h> - i2c0 { + i2c { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml index 346abfb13a3a..07cacc3f6a97 100644 --- a/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml +++ b/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml @@ -49,7 +49,7 @@ examples: - | #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/interrupt-controller/irq.h> - i2c0 { + i2c { #address-cells = <1>; #size-cells = <0>; @@ -64,7 +64,7 @@ examples: - | #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/interrupt-controller/irq.h> - spi0 { + spi { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adxl355.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adxl355.yaml index 6b03c4efbb08..c07261c71013 100644 --- a/Documentation/devicetree/bindings/iio/accel/adi,adxl355.yaml +++ b/Documentation/devicetree/bindings/iio/accel/adi,adxl355.yaml @@ -58,34 +58,34 @@ unevaluatedProperties: false examples: - | - #include <dt-bindings/gpio/gpio.h> - #include <dt-bindings/interrupt-controller/irq.h> - i2c { - #address-cells = <1>; - #size-cells = <0>; + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; - /* Example for a I2C device node */ - accelerometer@1d { - compatible = "adi,adxl355"; - reg = <0x1d>; - interrupt-parent = <&gpio>; - interrupts = <25 IRQ_TYPE_EDGE_RISING>; - interrupt-names = "DRDY"; - }; + /* Example for a I2C device node */ + accelerometer@1d { + compatible = "adi,adxl355"; + reg = <0x1d>; + interrupt-parent = <&gpio>; + interrupts = <25 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "DRDY"; }; + }; - | - #include <dt-bindings/gpio/gpio.h> - #include <dt-bindings/interrupt-controller/irq.h> - spi { - #address-cells = <1>; - #size-cells = <0>; + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + spi { + #address-cells = <1>; + #size-cells = <0>; - accelerometer@0 { - compatible = "adi,adxl355"; - reg = <0>; - spi-max-frequency = <1000000>; - interrupt-parent = <&gpio>; - interrupts = <25 IRQ_TYPE_EDGE_RISING>; - interrupt-names = "DRDY"; - }; + accelerometer@0 { + compatible = "adi,adxl355"; + reg = <0>; + spi-max-frequency = <1000000>; + interrupt-parent = <&gpio>; + interrupts = <25 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "DRDY"; }; + }; diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adxl372.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adxl372.yaml index 73a5c8f814cc..62465e36a590 100644 --- a/Documentation/devicetree/bindings/iio/accel/adi,adxl372.yaml +++ b/Documentation/devicetree/bindings/iio/accel/adi,adxl372.yaml @@ -37,32 +37,32 @@ unevaluatedProperties: false examples: - | - #include <dt-bindings/gpio/gpio.h> - #include <dt-bindings/interrupt-controller/irq.h> - i2c0 { - #address-cells = <1>; - #size-cells = <0>; + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; - /* Example for a I2C device node */ - accelerometer@53 { - compatible = "adi,adxl372"; - reg = <0x53>; - interrupt-parent = <&gpio>; - interrupts = <25 IRQ_TYPE_EDGE_FALLING>; - }; + /* Example for a I2C device node */ + accelerometer@53 { + compatible = "adi,adxl372"; + reg = <0x53>; + interrupt-parent = <&gpio>; + interrupts = <25 IRQ_TYPE_EDGE_FALLING>; }; + }; - | - #include <dt-bindings/gpio/gpio.h> - #include <dt-bindings/interrupt-controller/irq.h> - spi0 { - #address-cells = <1>; - #size-cells = <0>; + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + spi { + #address-cells = <1>; + #size-cells = <0>; - accelerometer@0 { - compatible = "adi,adxl372"; - reg = <0>; - spi-max-frequency = <1000000>; - interrupt-parent = <&gpio>; - interrupts = <25 IRQ_TYPE_EDGE_FALLING>; - }; + accelerometer@0 { + compatible = "adi,adxl372"; + reg = <0>; + spi-max-frequency = <1000000>; + interrupt-parent = <&gpio>; + interrupts = <25 IRQ_TYPE_EDGE_FALLING>; }; + }; diff --git a/Documentation/devicetree/bindings/iio/accel/bosch,bma220.yaml b/Documentation/devicetree/bindings/iio/accel/bosch,bma220.yaml index 5dd06f5905b4..ec643de031a3 100644 --- a/Documentation/devicetree/bindings/iio/accel/bosch,bma220.yaml +++ b/Documentation/devicetree/bindings/iio/accel/bosch,bma220.yaml @@ -36,7 +36,7 @@ unevaluatedProperties: false examples: - | #include <dt-bindings/interrupt-controller/irq.h> - spi0 { + spi { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.yaml b/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.yaml index 714e48e613de..6ddb03f61bd9 100644 --- a/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.yaml +++ b/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.yaml @@ -44,7 +44,7 @@ examples: accel@f { compatible = "kionix,kxtf9"; - reg = <0x0F>; + reg = <0xf>; mount-matrix = "0", "1", "0", "1", "0", "0", "0", "0", "1"; diff --git a/Documentation/devicetree/bindings/iio/accel/memsensing,msa311.yaml b/Documentation/devicetree/bindings/iio/accel/memsensing,msa311.yaml index 23528dcaa073..d530ec041fe7 100644 --- a/Documentation/devicetree/bindings/iio/accel/memsensing,msa311.yaml +++ b/Documentation/devicetree/bindings/iio/accel/memsensing,msa311.yaml @@ -1,9 +1,8 @@ # SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause - %YAML 1.2 --- -$id: "http://devicetree.org/schemas/iio/accel/memsensing,msa311.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/iio/accel/memsensing,msa311.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: MEMSensing digital 3-Axis accelerometer diff --git a/Documentation/devicetree/bindings/iio/accel/nxp,fxls8962af.yaml b/Documentation/devicetree/bindings/iio/accel/nxp,fxls8962af.yaml index 65ce8ea14b52..783c7ddfcd90 100644 --- a/Documentation/devicetree/bindings/iio/accel/nxp,fxls8962af.yaml +++ b/Documentation/devicetree/bindings/iio/accel/nxp,fxls8962af.yaml @@ -50,7 +50,7 @@ unevaluatedProperties: false examples: - | #include <dt-bindings/interrupt-controller/irq.h> - i2c0 { + i2c { #address-cells = <1>; #size-cells = <0>; @@ -65,7 +65,7 @@ examples: }; - | #include <dt-bindings/interrupt-controller/irq.h> - spi0 { + spi { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7091r5.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7091r5.yaml index b97559f23b3a..ce7ba634643c 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7091r5.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7091r5.yaml @@ -44,11 +44,11 @@ examples: #size-cells = <0>; adc@2f { - compatible = "adi,ad7091r5"; - reg = <0x2f>; + compatible = "adi,ad7091r5"; + reg = <0x2f>; - interrupts = <25 IRQ_TYPE_EDGE_FALLING>; - interrupt-parent = <&gpio>; + interrupts = <25 IRQ_TYPE_EDGE_FALLING>; + interrupt-parent = <&gpio>; }; }; ... diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml index 75a7184a4735..35ed04350e28 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml @@ -61,7 +61,7 @@ required: patternProperties: "^channel@([0-9]|1[0-5])$": - $ref: "adc.yaml" + $ref: adc.yaml type: object description: | Represents the external channels which are connected to the ADC. diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml index cc347dade4ef..d521d516088b 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml @@ -99,26 +99,26 @@ unevaluatedProperties: false examples: - | - spi0 { - #address-cells = <1>; - #size-cells = <0>; - - adc@0 { - compatible = "adi,ad7192"; - reg = <0>; - spi-max-frequency = <1000000>; - spi-cpol; - spi-cpha; - clocks = <&ad7192_mclk>; - clock-names = "mclk"; - interrupts = <25 0x2>; - interrupt-parent = <&gpio>; - dvdd-supply = <&dvdd>; - avdd-supply = <&avdd>; - - adi,refin2-pins-enable; - adi,rejection-60-Hz-enable; - adi,buffer-enable; - adi,burnout-currents-enable; + spi { + #address-cells = <1>; + #size-cells = <0>; + + adc@0 { + compatible = "adi,ad7192"; + reg = <0>; + spi-max-frequency = <1000000>; + spi-cpol; + spi-cpha; + clocks = <&ad7192_mclk>; + clock-names = "mclk"; + interrupts = <25 0x2>; + interrupt-parent = <&gpio>; + dvdd-supply = <&dvdd>; + avdd-supply = <&avdd>; + + adi,refin2-pins-enable; + adi,rejection-60-Hz-enable; + adi,buffer-enable; + adi,burnout-currents-enable; }; }; diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml index 1bfbeed6f299..7cc4ddc4e9b7 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml @@ -43,7 +43,7 @@ required: patternProperties: "^channel@[0-7]$": - $ref: "adc.yaml" + $ref: adc.yaml type: object description: | Represents the external channels which are connected to the ADC. diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml index ac5a47c8f070..7fa46df1f4fb 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml @@ -112,30 +112,30 @@ examples: - | #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/interrupt-controller/irq.h> - spi0 { + spi { #address-cells = <1>; #size-cells = <0>; adc@0 { - compatible = "adi,ad7606-8"; - reg = <0>; - spi-max-frequency = <1000000>; - spi-cpol; - spi-cpha; - - avcc-supply = <&adc_vref>; - - interrupts = <25 IRQ_TYPE_EDGE_FALLING>; - interrupt-parent = <&gpio>; - - adi,conversion-start-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>; - reset-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>; - adi,first-data-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>; - adi,oversampling-ratio-gpios = <&gpio 18 GPIO_ACTIVE_HIGH>, - <&gpio 23 GPIO_ACTIVE_HIGH>, - <&gpio 26 GPIO_ACTIVE_HIGH>; - standby-gpios = <&gpio 24 GPIO_ACTIVE_LOW>; - adi,sw-mode; + compatible = "adi,ad7606-8"; + reg = <0>; + spi-max-frequency = <1000000>; + spi-cpol; + spi-cpha; + + avcc-supply = <&adc_vref>; + + interrupts = <25 IRQ_TYPE_EDGE_FALLING>; + interrupt-parent = <&gpio>; + + adi,conversion-start-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>; + adi,first-data-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>; + adi,oversampling-ratio-gpios = <&gpio 18 GPIO_ACTIVE_HIGH>, + <&gpio 23 GPIO_ACTIVE_HIGH>, + <&gpio 26 GPIO_ACTIVE_HIGH>; + standby-gpios = <&gpio 24 GPIO_ACTIVE_LOW>; + adi,sw-mode; }; }; ... diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7780.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7780.yaml index a67ba67dab51..5fcc8dd012f1 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7780.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7780.yaml @@ -72,7 +72,7 @@ additionalProperties: false examples: - | #include <dt-bindings/gpio/gpio.h> - spi0 { + spi { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad799x.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad799x.yaml index 29641ce7175b..433ed2c9295f 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad799x.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad799x.yaml @@ -57,17 +57,17 @@ additionalProperties: false examples: - | i2c { - #address-cells = <1>; - #size-cells = <0>; + #address-cells = <1>; + #size-cells = <0>; - adc1: adc@28 { - reg = <0x28>; - compatible = "adi,ad7991"; - interrupts = <13 2>; - interrupt-parent = <&gpio6>; + adc1: adc@28 { + reg = <0x28>; + compatible = "adi,ad7991"; + interrupts = <13 2>; + interrupt-parent = <&gpio6>; - vcc-supply = <&vcc_3v3>; - vref-supply = <&adc_vref>; + vcc-supply = <&vcc_3v3>; + vref-supply = <&adc_vref>; }; }; ... diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad9467.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad9467.yaml index 2d72ff6bcbc0..7aa748d6b7a0 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad9467.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad9467.yaml @@ -64,10 +64,10 @@ examples: #size-cells = <0>; adc@0 { - compatible = "adi,ad9467"; - reg = <0>; - clocks = <&adc_clk>; - clock-names = "adc-clk"; + compatible = "adi,ad9467"; + reg = <0>; + clocks = <&adc_clk>; + clock-names = "adc-clk"; }; }; ... diff --git a/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml b/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml index 8e25773d69be..9996dd93f84b 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml @@ -51,11 +51,11 @@ additionalProperties: false examples: - | axi-adc@44a00000 { - compatible = "adi,axi-adc-10.0.a"; - reg = <0x44a00000 0x10000>; - dmas = <&rx_dma 0>; - dma-names = "rx"; + compatible = "adi,axi-adc-10.0.a"; + reg = <0x44a00000 0x10000>; + dmas = <&rx_dma 0>; + dma-names = "rx"; - adi,adc-dev = <&spi_adc>; + adi,adc-dev = <&spi_adc>; }; ... diff --git a/Documentation/devicetree/bindings/iio/adc/atmel,sama5d2-adc.yaml b/Documentation/devicetree/bindings/iio/adc/atmel,sama5d2-adc.yaml index 31f840d59303..4817b840977a 100644 --- a/Documentation/devicetree/bindings/iio/adc/atmel,sama5d2-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/atmel,sama5d2-adc.yaml @@ -41,7 +41,7 @@ properties: description: Startup time expressed in ms, it depends on SoC. atmel,trigger-edge-type: - $ref: '/schemas/types.yaml#/definitions/uint32' + $ref: /schemas/types.yaml#/definitions/uint32 description: One of possible edge types for the ADTRG hardware trigger pin. When the specific edge type is detected, the conversion will diff --git a/Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml b/Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml index 77605f17901c..9c57eb13f892 100644 --- a/Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml +++ b/Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: GPL-2.0 %YAML 1.2 --- -$id: "http://devicetree.org/schemas/iio/adc/avia-hx711.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/iio/adc/avia-hx711.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: AVIA HX711 ADC chip for weight cells diff --git a/Documentation/devicetree/bindings/iio/adc/cirrus,ep9301-adc.yaml b/Documentation/devicetree/bindings/iio/adc/cirrus,ep9301-adc.yaml new file mode 100644 index 000000000000..6d4fb3e1d2a2 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/cirrus,ep9301-adc.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/cirrus,ep9301-adc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cirrus Logic EP930x internal ADC + +description: | + Cirrus Logic EP9301/EP9302 SoCs' internal ADC block. + + User's manual: + https://cdn.embeddedts.com/resource-attachments/ts-7000_ep9301-ug.pdf + +maintainers: + - Alexander Sverdlin <alexander.sverdlin@gmail.com> + +properties: + compatible: + const: cirrus,ep9301-adc + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - clocks + +additionalProperties: false + +examples: + - | + adc: adc@80900000 { + compatible = "cirrus,ep9301-adc"; + reg = <0x80900000 0x28>; + clocks = <&syscon 24>; + interrupt-parent = <&vic1>; + interrupts = <30>; + }; +... diff --git a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml index 517e8b1fcb73..9cd0fd539782 100644 --- a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml @@ -2,8 +2,8 @@ # Copyright 2019-2020 Artur Rojek %YAML 1.2 --- -$id: "http://devicetree.org/schemas/iio/adc/ingenic,adc.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/iio/adc/ingenic,adc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Ingenic JZ47xx ADC controller IIO @@ -78,14 +78,14 @@ examples: #include <dt-bindings/iio/adc/ingenic,adc.h> adc@10070000 { - compatible = "ingenic,jz4740-adc"; - #io-channel-cells = <1>; + compatible = "ingenic,jz4740-adc"; + #io-channel-cells = <1>; - reg = <0x10070000 0x30>; + reg = <0x10070000 0x30>; - clocks = <&cgu JZ4740_CLK_ADC>; - clock-names = "adc"; + clocks = <&cgu JZ4740_CLK_ADC>; + clock-names = "adc"; - interrupt-parent = <&intc>; - interrupts = <18>; + interrupt-parent = <&intc>; + interrupts = <18>; }; diff --git a/Documentation/devicetree/bindings/iio/adc/maxim,max1027.yaml b/Documentation/devicetree/bindings/iio/adc/maxim,max1027.yaml index d0a7ed26d9ea..e4b362113509 100644 --- a/Documentation/devicetree/bindings/iio/adc/maxim,max1027.yaml +++ b/Documentation/devicetree/bindings/iio/adc/maxim,max1027.yaml @@ -54,8 +54,8 @@ examples: - | #include <dt-bindings/interrupt-controller/irq.h> spi { - #address-cells = <1>; - #size-cells = <0>; + #address-cells = <1>; + #size-cells = <0>; maxadc: adc@0 { compatible = "maxim,max1027"; reg = <0>; diff --git a/Documentation/devicetree/bindings/iio/adc/maxim,max1238.yaml b/Documentation/devicetree/bindings/iio/adc/maxim,max1238.yaml index 50bcd72ac9d6..60d7b34e3286 100644 --- a/Documentation/devicetree/bindings/iio/adc/maxim,max1238.yaml +++ b/Documentation/devicetree/bindings/iio/adc/maxim,max1238.yaml @@ -10,7 +10,7 @@ maintainers: - Jonathan Cameron <jic23@kernel.org> description: | - Family of simple ADCs with i2c inteface and internal references. + Family of simple ADCs with i2c interface and internal references. properties: compatible: diff --git a/Documentation/devicetree/bindings/iio/adc/maxim,max1241.yaml b/Documentation/devicetree/bindings/iio/adc/maxim,max1241.yaml index 58b12fe8070c..ef8d51e74c08 100644 --- a/Documentation/devicetree/bindings/iio/adc/maxim,max1241.yaml +++ b/Documentation/devicetree/bindings/iio/adc/maxim,max1241.yaml @@ -54,8 +54,8 @@ examples: - | #include <dt-bindings/gpio/gpio.h> spi { - #address-cells = <1>; - #size-cells = <0>; + #address-cells = <1>; + #size-cells = <0>; adc@0 { compatible = "maxim,max1241"; diff --git a/Documentation/devicetree/bindings/iio/adc/maxim,max1363.yaml b/Documentation/devicetree/bindings/iio/adc/maxim,max1363.yaml index e04f09f35601..96f3f535fe34 100644 --- a/Documentation/devicetree/bindings/iio/adc/maxim,max1363.yaml +++ b/Documentation/devicetree/bindings/iio/adc/maxim,max1363.yaml @@ -10,7 +10,7 @@ maintainers: - Jonathan Cameron <jic23@kernel.org> description: | - Family of ADCs with i2c inteface, internal references and threshold + Family of ADCs with i2c interface, internal references and threshold monitoring. properties: diff --git a/Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml b/Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml index 2c93fb41f172..f7b3fde4115a 100644 --- a/Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml +++ b/Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml @@ -2,8 +2,8 @@ # Copyright 2019 Marcus Folkesson <marcus.folkesson@gmail.com> %YAML 1.2 --- -$id: "http://devicetree.org/schemas/iio/adc/microchip,mcp3911.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/iio/adc/microchip,mcp3911.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Microchip MCP3911 Dual channel analog front end (ADC) diff --git a/Documentation/devicetree/bindings/iio/adc/nxp,imx93-adc.yaml b/Documentation/devicetree/bindings/iio/adc/nxp,imx93-adc.yaml new file mode 100644 index 000000000000..dacc526dc695 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/nxp,imx93-adc.yaml @@ -0,0 +1,81 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/nxp,imx93-adc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP iMX93 ADC + +maintainers: + - Haibo Chen <haibo.chen@nxp.com> + +description: + The ADC on iMX93 is a 8-channel 12-bit 1MS/s ADC with 4 channels + connected to pins. it support normal and inject mode, include + One-Shot and Scan (continuous) conversions. Programmable DMA + enables for each channel Also this ADC contain alternate analog + watchdog thresholds, select threshold through input ports. And + also has Self-test logic and Software-initiated calibration. + +properties: + compatible: + const: nxp,imx93-adc + + reg: + maxItems: 1 + + interrupts: + items: + - description: WDGnL, watchdog threshold interrupt requests. + - description: WDGnH, watchdog threshold interrupt requests. + - description: normal conversion, include EOC (End of Conversion), + ECH (End of Chain), JEOC (End of Injected Conversion) and + JECH (End of injected Chain). + - description: Self-testing Interrupts. + + clocks: + maxItems: 1 + + clock-names: + const: ipg + + vref-supply: + description: + The reference voltage which used to establish channel scaling. + + "#io-channel-cells": + const: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - vref-supply + - "#io-channel-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/clock/imx93-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + soc { + #address-cells = <1>; + #size-cells = <1>; + adc@44530000 { + compatible = "nxp,imx93-adc"; + reg = <0x44530000 0x10000>; + interrupts = <GIC_SPI 217 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 218 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 219 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 268 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk IMX93_CLK_ADC1_GATE>; + clock-names = "ipg"; + vref-supply = <®_vref_1v8>; + #io-channel-cells = <1>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,pm8018-adc.yaml b/Documentation/devicetree/bindings/iio/adc/qcom,pm8018-adc.yaml index d186b713d6a7..58ea1ca4a5ee 100644 --- a/Documentation/devicetree/bindings/iio/adc/qcom,pm8018-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/qcom,pm8018-adc.yaml @@ -160,7 +160,7 @@ examples: }; ref_muxoff: adc-channel@f { reg = <0x00 0x0f>; - }; + }; }; }; ... diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-iadc.yaml b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-iadc.yaml index fa855baa368c..73def67fbe01 100644 --- a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-iadc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-iadc.yaml @@ -20,6 +20,7 @@ properties: compatible: items: - enum: + - qcom,pm8226-iadc - qcom,pm8941-iadc - const: qcom,spmi-iadc @@ -49,7 +50,7 @@ additionalProperties: false examples: - | #include <dt-bindings/interrupt-controller/irq.h> - spmi_bus { + spmi { #address-cells = <1>; #size-cells = <0>; pmic_iadc: adc@3600 { diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-rradc.yaml b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-rradc.yaml index c8cbfd3444be..b3a626389870 100644 --- a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-rradc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-rradc.yaml @@ -40,12 +40,12 @@ additionalProperties: false examples: - | pmic { - #address-cells = <1>; - #size-cells = <0>; - - pmic_rradc: adc@4500 { - compatible = "qcom,pmi8998-rradc"; - reg = <0x4500>; - #io-channel-cells = <1>; - }; + #address-cells = <1>; + #size-cells = <0>; + + pmic_rradc: adc@4500 { + compatible = "qcom,pmi8998-rradc"; + reg = <0x4500>; + #io-channel-cells = <1>; + }; }; diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml index 8b743742a5f9..ba86c7b7d622 100644 --- a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml @@ -69,7 +69,7 @@ required: patternProperties: "^channel@[0-7]$": - $ref: "adc.yaml" + $ref: adc.yaml type: object description: | Represents the external channels which are connected to the ADC. diff --git a/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml b/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml index 81c87295912c..582d0a03b814 100644 --- a/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml @@ -52,7 +52,7 @@ properties: vdd-supply: true samsung,syscon-phandle: - $ref: '/schemas/types.yaml#/definitions/phandle' + $ref: /schemas/types.yaml#/definitions/phandle description: Phandle to the PMU system controller node (to access the ADC_PHY register on Exynos3250/4x12/5250/5420/5800). @@ -142,7 +142,7 @@ examples: pullup-ohm = <47000>; pulldown-ohm = <0>; io-channels = <&adc 4>; - }; + }; }; - | @@ -150,7 +150,7 @@ examples: adc@126c0000 { compatible = "samsung,exynos3250-adc"; - reg = <0x126C0000 0x100>; + reg = <0x126c0000 0x100>; interrupts = <0 137 0>; #io-channel-cells = <1>; diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.yaml b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.yaml index 1c340c95df16..995cbf8cefc6 100644 --- a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) %YAML 1.2 --- -$id: "http://devicetree.org/schemas/iio/adc/st,stm32-adc.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/iio/adc/st,stm32-adc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: STMicroelectronics STM32 ADC @@ -80,7 +80,7 @@ properties: description: Phandle to system configuration controller. It can be used to control the analog circuitry on stm32mp1. - $ref: "/schemas/types.yaml#/definitions/phandle-array" + $ref: /schemas/types.yaml#/definitions/phandle-array interrupt-controller: true @@ -341,7 +341,7 @@ patternProperties: patternProperties: "^channel@([0-9]|1[0-9])$": type: object - $ref: "adc.yaml" + $ref: adc.yaml description: Represents the external channels which are connected to the ADC. properties: diff --git a/Documentation/devicetree/bindings/iio/adc/st,stmpe-adc.yaml b/Documentation/devicetree/bindings/iio/adc/st,stmpe-adc.yaml index 333744a2159c..474e35c49348 100644 --- a/Documentation/devicetree/bindings/iio/adc/st,stmpe-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/st,stmpe-adc.yaml @@ -35,10 +35,8 @@ additionalProperties: false examples: - | - stmpe { - stmpe_adc { - compatible = "st,stmpe-adc"; - st,norequest-mask = <0x0F>; /* dont use ADC CH3-0 */ - }; + adc { + compatible = "st,stmpe-adc"; + st,norequest-mask = <0x0f>; /* dont use ADC CH3-0 */ }; ... diff --git a/Documentation/devicetree/bindings/iio/adc/ti,adc081c.yaml b/Documentation/devicetree/bindings/iio/adc/ti,adc081c.yaml new file mode 100644 index 000000000000..caaad777580c --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ti,adc081c.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/ti,adc081c.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI Single-channel I2C ADCs + +maintainers: + - Jonathan Cameron <jic23@kernel.org> + - Lars-Peter Clausen <lars@metafoo.de> + +description: | + Single-channel ADC supporting 8, 10, or 12-bit samples and high/low alerts. + +properties: + compatible: + enum: + - ti,adc081c + - ti,adc101c + - ti,adc121c + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + vref-supply: + description: + Regulator for the combined power supply and voltage reference + + "#io-channel-cells": + const: 1 + +required: + - compatible + - reg + - vref-supply + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + adc@52 { + compatible = "ti,adc081c"; + reg = <0x52>; + vref-supply = <®_2p5v>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml index 2c3c2cf2145c..2127d639a768 100644 --- a/Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml +++ b/Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml @@ -104,12 +104,12 @@ examples: #address-cells = <1>; #size-cells = <0>; channel@0 { - reg = <0>; + reg = <0>; }; channel@4 { - reg = <4>; - ti,gain = <3>; - ti,datarate = <5>; + reg = <4>; + ti,gain = <3>; + ti,datarate = <5>; }; }; }; diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads131e08.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads131e08.yaml index 55c2c73626f4..890f125d422c 100644 --- a/Documentation/devicetree/bindings/iio/adc/ti,ads131e08.yaml +++ b/Documentation/devicetree/bindings/iio/adc/ti,ads131e08.yaml @@ -77,7 +77,7 @@ required: patternProperties: "^channel@([0-7])$": - $ref: "adc.yaml" + $ref: adc.yaml type: object description: | Represents the external channels which are connected to the ADC. diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads7924.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads7924.yaml new file mode 100644 index 000000000000..0d8d06afed8b --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ti,ads7924.yaml @@ -0,0 +1,110 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/ti,ads7924.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI ADS7924 4 channels 12 bits I2C analog to digital converter + +maintainers: + - Hugo Villeneuve <hvilleneuve@dimonoff.com> + +description: | + Texas Instruments ADS7924 4 channels 12 bits I2C analog to digital converter + + Specifications: + https://www.ti.com/lit/gpn/ads7924 + +properties: + compatible: + const: ti,ads7924 + + reg: + maxItems: 1 + + vref-supply: + description: + The regulator supply for the ADC reference voltage (AVDD) + + reset-gpios: + maxItems: 1 + + interrupts: + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + "#io-channel-cells": + const: 1 + +patternProperties: + "^channel@[0-3]+$": + $ref: adc.yaml + + description: | + Represents the external channels which are connected to the ADC. + + properties: + reg: + description: | + The channel number. It can have up to 4 channels numbered from 0 to 3. + items: + - minimum: 0 + maximum: 3 + + label: true + + required: + - reg + + additionalProperties: false + +additionalProperties: false + +required: + - compatible + - reg + - vref-supply + - "#address-cells" + - "#size-cells" + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/gpio/gpio.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + adc@48 { + compatible = "ti,ads7924"; + reg = <0x48>; + vref-supply = <&ads7924_reg>; + reset-gpios = <&gpio 5 GPIO_ACTIVE_LOW>; + interrupts = <25 IRQ_TYPE_EDGE_FALLING>; + interrupt-parent = <&gpio>; + #address-cells = <1>; + #size-cells = <0>; + channel@0 { + reg = <0>; + label = "CH0"; + }; + channel@1 { + reg = <1>; + label = "CH1"; + }; + channel@2 { + reg = <2>; + label = "CH2"; + }; + channel@3 { + reg = <3>; + label = "CH3"; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/adc/ti,lmp92064.yaml b/Documentation/devicetree/bindings/iio/adc/ti,lmp92064.yaml new file mode 100644 index 000000000000..5fb65bf7749d --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ti,lmp92064.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/ti,lmp92064.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments LMP92064 Precision Current and Voltage Sensor. + +maintainers: + - Leonard Göhrs <l.goehrs@pengutronix.de> + +description: | + The LMP92064 is a two channel ADC intended for combined voltage and current + measurements. + + The device contains two ADCs to allow simultaneous sampling of voltage and + current and thus of instantaneous power consumption. + +properties: + compatible: + enum: + - ti,lmp92064 + + reg: + maxItems: 1 + + vdd-supply: + description: Regulator that provides power to the main part of the chip + + vdig-supply: + description: | + Regulator that provides power to the digital I/O part of the chip + + shunt-resistor-micro-ohms: + description: | + Value of the shunt resistor (in µΩ) connected between INCP and INCN, + across which current is measured. Used to provide correct scaling of the + raw ADC measurement. + + reset-gpios: + maxItems: 1 + +required: + - compatible + - reg + - shunt-resistor-micro-ohms + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + spi { + #address-cells = <1>; + #size-cells = <0>; + + adc@0 { + compatible = "ti,lmp92064"; + reg = <0>; + vdd-supply = <&vdd>; + vdig-supply = <&vdd>; + spi-max-frequency = <20000000>; + shunt-resistor-micro-ohms = <15000>; + reset-gpios = <&gpio1 16 GPIO_ACTIVE_HIGH>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/adc/ti,tsc2046.yaml b/Documentation/devicetree/bindings/iio/adc/ti,tsc2046.yaml index bdf3bba2d750..866a05c9db36 100644 --- a/Documentation/devicetree/bindings/iio/adc/ti,tsc2046.yaml +++ b/Documentation/devicetree/bindings/iio/adc/ti,tsc2046.yaml @@ -41,7 +41,7 @@ required: patternProperties: "^channel@[0-7]$": - $ref: "adc.yaml" + $ref: adc.yaml type: object properties: @@ -83,36 +83,36 @@ examples: #size-cells = <0>; channel@0 { - reg = <0>; + reg = <0>; }; channel@1 { - reg = <1>; - settling-time-us = <700>; - oversampling-ratio = <5>; + reg = <1>; + settling-time-us = <700>; + oversampling-ratio = <5>; }; channel@2 { - reg = <2>; + reg = <2>; }; channel@3 { - reg = <3>; - settling-time-us = <700>; - oversampling-ratio = <5>; + reg = <3>; + settling-time-us = <700>; + oversampling-ratio = <5>; }; channel@4 { - reg = <4>; - settling-time-us = <700>; - oversampling-ratio = <5>; + reg = <4>; + settling-time-us = <700>; + oversampling-ratio = <5>; }; channel@5 { - reg = <5>; - settling-time-us = <700>; - oversampling-ratio = <5>; + reg = <5>; + settling-time-us = <700>; + oversampling-ratio = <5>; }; channel@6 { - reg = <6>; + reg = <6>; }; channel@7 { - reg = <7>; + reg = <7>; }; }; }; diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml index fee0f023a8c8..96340a05754c 100644 --- a/Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml @@ -192,26 +192,26 @@ additionalProperties: false examples: - | spi { - #address-cells = <1>; - #size-cells = <0>; - ad3552r@0 { - compatible = "adi,ad3552r"; - reg = <0>; - spi-max-frequency = <20000000>; - #address-cells = <1>; - #size-cells = <0>; - channel@0 { - reg = <0>; - adi,output-range-microvolt = <0 10000000>; - }; - channel@1 { - reg = <1>; - custom-output-range-config { - adi,gain-offset = <5>; - adi,gain-scaling-p-inv-log2 = <1>; - adi,gain-scaling-n-inv-log2 = <2>; - adi,rfb-ohms = <1>; - }; + #address-cells = <1>; + #size-cells = <0>; + ad3552r@0 { + compatible = "adi,ad3552r"; + reg = <0>; + spi-max-frequency = <20000000>; + #address-cells = <1>; + #size-cells = <0>; + channel@0 { + reg = <0>; + adi,output-range-microvolt = <0 10000000>; + }; + channel@1 { + reg = <1>; + custom-output-range-config { + adi,gain-offset = <5>; + adi,gain-scaling-p-inv-log2 = <1>; + adi,gain-scaling-n-inv-log2 = <2>; + adi,rfb-ohms = <1>; + }; }; }; }; diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5380.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5380.yaml index ff50c72c62b5..9eb9928500e2 100644 --- a/Documentation/devicetree/bindings/iio/dac/adi,ad5380.yaml +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5380.yaml @@ -12,6 +12,7 @@ maintainers: description: | DAC devices supporting both SPI and I2C interfaces. + properties: compatible: enum: diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5686.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5686.yaml index 13f214234b8e..b4400c52bec3 100644 --- a/Documentation/devicetree/bindings/iio/dac/adi,ad5686.yaml +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5686.yaml @@ -33,6 +33,7 @@ properties: - description: I2C devices enum: - adi,ad5311r + - adi,ad5337r - adi,ad5338r - adi,ad5671r - adi,ad5675r diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5766.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5766.yaml index 3c8784a54d2c..212c936bab8d 100644 --- a/Documentation/devicetree/bindings/iio/dac/adi,ad5766.yaml +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5766.yaml @@ -51,15 +51,15 @@ additionalProperties: false examples: - | spi { - #address-cells = <1>; - #size-cells = <0>; + #address-cells = <1>; + #size-cells = <0>; - ad5766@0 { - compatible = "adi,ad5766"; - output-range-microvolts = <(-5000000) 5000000>; - reg = <0>; - spi-cpol; - spi-max-frequency = <1000000>; - reset-gpios = <&gpio 22 0>; - }; - }; + ad5766@0 { + compatible = "adi,ad5766"; + output-range-microvolts = <(-5000000) 5000000>; + reg = <0>; + spi-cpol; + spi-max-frequency = <1000000>; + reset-gpios = <&gpio 22 0>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5770r.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5770r.yaml index 8e7da0de918f..82b0eed6a7b7 100644 --- a/Documentation/devicetree/bindings/iio/dac/adi,ad5770r.yaml +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5770r.yaml @@ -147,49 +147,49 @@ unevaluatedProperties: false examples: - | - spi { - #address-cells = <1>; - #size-cells = <0>; - - ad5770r@0 { - compatible = "adi,ad5770r"; - reg = <0>; - spi-max-frequency = <1000000>; - vref-supply = <&vref>; - adi,external-resistor; - reset-gpios = <&gpio 22 0>; - #address-cells = <1>; - #size-cells = <0>; - - channel@0 { - reg = <0>; - adi,range-microamp = <0 300000>; - }; - - channel@1 { - reg = <1>; - adi,range-microamp = <0 140000>; - }; - - channel@2 { - reg = <2>; - adi,range-microamp = <0 55000>; - }; - - channel@3 { - reg = <3>; - adi,range-microamp = <0 45000>; - }; - - channel@4 { - reg = <4>; - adi,range-microamp = <0 45000>; - }; - - channel@5 { - reg = <5>; - adi,range-microamp = <0 45000>; - }; - }; + spi { + #address-cells = <1>; + #size-cells = <0>; + + ad5770r@0 { + compatible = "adi,ad5770r"; + reg = <0>; + spi-max-frequency = <1000000>; + vref-supply = <&vref>; + adi,external-resistor; + reset-gpios = <&gpio 22 0>; + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + reg = <0>; + adi,range-microamp = <0 300000>; + }; + + channel@1 { + reg = <1>; + adi,range-microamp = <0 140000>; + }; + + channel@2 { + reg = <2>; + adi,range-microamp = <0 55000>; + }; + + channel@3 { + reg = <3>; + adi,range-microamp = <0 45000>; + }; + + channel@4 { + reg = <4>; + adi,range-microamp = <0 45000>; + }; + + channel@5 { + reg = <5>; + adi,range-microamp = <0 45000>; + }; }; + }; ... diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ltc2688.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ltc2688.yaml index 15cc6bf59b13..f22ef710ecde 100644 --- a/Documentation/devicetree/bindings/iio/dac/adi,ltc2688.yaml +++ b/Documentation/devicetree/bindings/iio/dac/adi,ltc2688.yaml @@ -116,32 +116,32 @@ examples: - | spi { - #address-cells = <1>; - #size-cells = <0>; - ltc2688: ltc2688@0 { - compatible = "adi,ltc2688"; - reg = <0>; - - vcc-supply = <&vcc>; - iovcc-supply = <&vcc>; - vref-supply = <&vref>; - - #address-cells = <1>; - #size-cells = <0>; - channel@0 { - reg = <0>; - adi,toggle-mode; - adi,overrange; - }; - - channel@1 { - reg = <1>; - adi,output-range-microvolt = <0 10000000>; - - clocks = <&clock_tgp3>; - adi,toggle-dither-input = <2>; - }; - }; + #address-cells = <1>; + #size-cells = <0>; + ltc2688: ltc2688@0 { + compatible = "adi,ltc2688"; + reg = <0>; + + vcc-supply = <&vcc>; + iovcc-supply = <&vcc>; + vref-supply = <&vref>; + + #address-cells = <1>; + #size-cells = <0>; + channel@0 { + reg = <0>; + adi,toggle-mode; + adi,overrange; + }; + + channel@1 { + reg = <1>; + adi,output-range-microvolt = <0 10000000>; + + clocks = <&clock_tgp3>; + adi,toggle-dither-input = <2>; + }; + }; }; ... diff --git a/Documentation/devicetree/bindings/iio/dac/lltc,ltc1660.yaml b/Documentation/devicetree/bindings/iio/dac/lltc,ltc1660.yaml index 133b0f867992..c9f51d00fa8f 100644 --- a/Documentation/devicetree/bindings/iio/dac/lltc,ltc1660.yaml +++ b/Documentation/devicetree/bindings/iio/dac/lltc,ltc1660.yaml @@ -2,8 +2,8 @@ # Copyright 2019 Marcus Folkesson <marcus.folkesson@gmail.com> %YAML 1.2 --- -$id: "http://devicetree.org/schemas/iio/dac/lltc,ltc1660.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/iio/dac/lltc,ltc1660.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Linear Technology Micropower octal 8-Bit and 10-Bit DACs diff --git a/Documentation/devicetree/bindings/iio/dac/lltc,ltc2632.yaml b/Documentation/devicetree/bindings/iio/dac/lltc,ltc2632.yaml index b1eb77335d05..733edc7d6d17 100644 --- a/Documentation/devicetree/bindings/iio/dac/lltc,ltc2632.yaml +++ b/Documentation/devicetree/bindings/iio/dac/lltc,ltc2632.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause %YAML 1.2 --- -$id: "http://devicetree.org/schemas/iio/dac/lltc,ltc2632.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/iio/dac/lltc,ltc2632.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Linear Technology LTC263x 12-/10-/8-Bit Rail-to-Rail DAC @@ -64,14 +64,14 @@ examples: }; spi { - #address-cells = <1>; - #size-cells = <0>; + #address-cells = <1>; + #size-cells = <0>; - dac@0 { - compatible = "lltc,ltc2632-l12"; - reg = <0>; /* CS0 */ - spi-max-frequency = <1000000>; - vref-supply = <&vref>; - }; + dac@0 { + compatible = "lltc,ltc2632-l12"; + reg = <0>; /* CS0 */ + spi-max-frequency = <1000000>; + vref-supply = <&vref>; + }; }; ... diff --git a/Documentation/devicetree/bindings/iio/dac/maxim,max5522.yaml b/Documentation/devicetree/bindings/iio/dac/maxim,max5522.yaml new file mode 100644 index 000000000000..24830f56c501 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/maxim,max5522.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/maxim,max5522.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated MAX5522 Dual 10-bit Voltage-Output SPI DACs + +maintainers: + - Angelo Dureghello <angelo.dureghello@timesys.com> + - Jonathan Cameron <jic23@kernel.org> + +description: | + Datasheet available at: + https://www.analog.com/en/products/max5522.html + +properties: + compatible: + const: maxim,max5522 + + reg: + maxItems: 1 + + vdd-supply: true + vrefin-supply: true + +required: + - compatible + - reg + - vrefin-supply + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + +unevaluatedProperties: false + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + dac@0 { + compatible = "maxim,max5522"; + reg = <0>; + vrefin-supply = <&vref>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/dac/st,stm32-dac.yaml b/Documentation/devicetree/bindings/iio/dac/st,stm32-dac.yaml index 0f1bf1110122..04045b932bd2 100644 --- a/Documentation/devicetree/bindings/iio/dac/st,stm32-dac.yaml +++ b/Documentation/devicetree/bindings/iio/dac/st,stm32-dac.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) %YAML 1.2 --- -$id: "http://devicetree.org/schemas/iio/dac/st,stm32-dac.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/iio/dac/st,stm32-dac.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: STMicroelectronics STM32 DAC diff --git a/Documentation/devicetree/bindings/iio/dac/ti,dac5571.yaml b/Documentation/devicetree/bindings/iio/dac/ti,dac5571.yaml index 88298bc43b81..79da0323c327 100644 --- a/Documentation/devicetree/bindings/iio/dac/ti,dac5571.yaml +++ b/Documentation/devicetree/bindings/iio/dac/ti,dac5571.yaml @@ -46,7 +46,7 @@ examples: dac@4c { compatible = "ti,dac5571"; - reg = <0x4C>; + reg = <0x4c>; vref-supply = <&vdd_supply>; }; }; diff --git a/Documentation/devicetree/bindings/iio/frequency/adf4371.yaml b/Documentation/devicetree/bindings/iio/frequency/adf4371.yaml index 0144f74a4768..1cb2adaf66f9 100644 --- a/Documentation/devicetree/bindings/iio/frequency/adf4371.yaml +++ b/Documentation/devicetree/bindings/iio/frequency/adf4371.yaml @@ -53,16 +53,16 @@ unevaluatedProperties: false examples: - | - spi0 { + spi { #address-cells = <1>; #size-cells = <0>; frequency@0 { - compatible = "adi,adf4371"; - reg = <0>; - spi-max-frequency = <1000000>; - clocks = <&adf4371_clkin>; - clock-names = "clkin"; + compatible = "adi,adf4371"; + reg = <0>; + spi-max-frequency = <1000000>; + clocks = <&adf4371_clkin>; + clock-names = "clkin"; }; }; ... diff --git a/Documentation/devicetree/bindings/iio/gyroscope/adi,adxrs290.yaml b/Documentation/devicetree/bindings/iio/gyroscope/adi,adxrs290.yaml index 0ae2464b9bc4..3d94dd4612c4 100644 --- a/Documentation/devicetree/bindings/iio/gyroscope/adi,adxrs290.yaml +++ b/Documentation/devicetree/bindings/iio/gyroscope/adi,adxrs290.yaml @@ -50,13 +50,13 @@ examples: #address-cells = <1>; #size-cells = <0>; gyro@0 { - compatible = "adi,adxrs290"; - reg = <0>; - spi-max-frequency = <5000000>; - spi-cpol; - spi-cpha; - interrupt-parent = <&gpio>; - interrupts = <25 IRQ_TYPE_EDGE_RISING>; + compatible = "adi,adxrs290"; + reg = <0>; + spi-max-frequency = <5000000>; + spi-cpol; + spi-cpha; + interrupt-parent = <&gpio>; + interrupts = <25 IRQ_TYPE_EDGE_RISING>; }; }; ... diff --git a/Documentation/devicetree/bindings/iio/gyroscope/nxp,fxas21002c.yaml b/Documentation/devicetree/bindings/iio/gyroscope/nxp,fxas21002c.yaml index 2c900e9dddc6..297d519d68f2 100644 --- a/Documentation/devicetree/bindings/iio/gyroscope/nxp,fxas21002c.yaml +++ b/Documentation/devicetree/bindings/iio/gyroscope/nxp,fxas21002c.yaml @@ -65,34 +65,34 @@ examples: - | #include <dt-bindings/interrupt-controller/irq.h> - i2c0 { + i2c { #address-cells = <1>; #size-cells = <0>; gyroscope@20 { - compatible = "nxp,fxas21002c"; - reg = <0x20>; + compatible = "nxp,fxas21002c"; + reg = <0x20>; - vdd-supply = <®_peri_3p15v>; - vddio-supply = <®_peri_3p15v>; + vdd-supply = <®_peri_3p15v>; + vddio-supply = <®_peri_3p15v>; - interrupt-parent = <&gpio1>; - interrupts = <7 IRQ_TYPE_EDGE_RISING>; - interrupt-names = "INT1"; + interrupt-parent = <&gpio1>; + interrupts = <7 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "INT1"; }; }; - spi0 { + spi { #address-cells = <1>; #size-cells = <0>; gyroscope@0 { - compatible = "nxp,fxas21002c"; - reg = <0x0>; + compatible = "nxp,fxas21002c"; + reg = <0x0>; - spi-max-frequency = <2000000>; + spi-max-frequency = <2000000>; - interrupt-parent = <&gpio2>; - interrupts = <7 IRQ_TYPE_EDGE_RISING>; - interrupt-names = "INT2"; + interrupt-parent = <&gpio2>; + interrupts = <7 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "INT2"; }; }; diff --git a/Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml b/Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml index 6c5ad426a016..b9b5beac33b2 100644 --- a/Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml +++ b/Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml @@ -42,7 +42,7 @@ examples: #address-cells = <1>; #size-cells = <0>; - heart_mon@0 { + heart-mon@0 { compatible = "ti,afe4403"; reg = <0>; spi-max-frequency = <10000000>; diff --git a/Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml b/Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml index c0e815d9999e..2958c4ca75b4 100644 --- a/Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml +++ b/Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml @@ -39,7 +39,7 @@ examples: #address-cells = <1>; #size-cells = <0>; - heart_mon@58 { + heart-mon@58 { compatible = "ti,afe4404"; reg = <0x58>; tx-supply = <&vbat>; diff --git a/Documentation/devicetree/bindings/iio/humidity/dht11.yaml b/Documentation/devicetree/bindings/iio/humidity/dht11.yaml index 2247481d0203..0103f4238942 100644 --- a/Documentation/devicetree/bindings/iio/humidity/dht11.yaml +++ b/Documentation/devicetree/bindings/iio/humidity/dht11.yaml @@ -34,7 +34,7 @@ additionalProperties: false examples: - | - humidity_sensor { + humidity-sensor { compatible = "dht11"; gpios = <&gpio0 6 0>; }; diff --git a/Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml b/Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml index 88384b69f917..a2bc1fa92da0 100644 --- a/Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml +++ b/Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml @@ -35,12 +35,12 @@ additionalProperties: false examples: - | - i2c0 { - #address-cells = <1>; - #size-cells = <0>; - - humidity@40 { - compatible = "ti,hdc2010"; - reg = <0x40>; - }; + i2c { + #address-cells = <1>; + #size-cells = <0>; + + humidity@40 { + compatible = "ti,hdc2010"; + reg = <0x40>; + }; }; diff --git a/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml b/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml index d166dbca18c3..4e43c80e5119 100644 --- a/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml +++ b/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml @@ -42,7 +42,7 @@ examples: - | #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/interrupt-controller/irq.h> - spi0 { + spi { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml b/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml index 5dbfae80bb28..c73533c54588 100644 --- a/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml +++ b/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml @@ -114,17 +114,17 @@ examples: - | #include <dt-bindings/interrupt-controller/irq.h> spi { - #address-cells = <1>; - #size-cells = <0>; - - adis16475: adis16475-3@0 { - compatible = "adi,adis16475-3"; - reg = <0>; - spi-cpha; - spi-cpol; - spi-max-frequency = <2000000>; - interrupts = <4 IRQ_TYPE_EDGE_RISING>; - interrupt-parent = <&gpio>; - }; + #address-cells = <1>; + #size-cells = <0>; + + adis16475: adis16475-3@0 { + compatible = "adi,adis16475-3"; + reg = <0>; + spi-cpha; + spi-cpol; + spi-max-frequency = <2000000>; + interrupts = <4 IRQ_TYPE_EDGE_RISING>; + interrupt-parent = <&gpio>; + }; }; ... diff --git a/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml b/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml index a0760382548d..47cfba939ca6 100644 --- a/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml +++ b/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml @@ -64,16 +64,16 @@ examples: #size-cells = <0>; bmi160@68 { - compatible = "bosch,bmi160"; - reg = <0x68>; - vdd-supply = <&pm8916_l17>; - vddio-supply = <&pm8916_l6>; - interrupt-parent = <&gpio4>; - interrupts = <12 IRQ_TYPE_EDGE_RISING>; - interrupt-names = "INT1"; - mount-matrix = "0", "1", "0", - "-1", "0", "0", - "0", "0", "1"; + compatible = "bosch,bmi160"; + reg = <0x68>; + vdd-supply = <&pm8916_l17>; + vddio-supply = <&pm8916_l6>; + interrupt-parent = <&gpio4>; + interrupts = <12 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "INT1"; + mount-matrix = "0", "1", "0", + "-1", "0", "0", + "0", "0", "1"; }; }; - | @@ -84,11 +84,11 @@ examples: #size-cells = <0>; bmi160@0 { - compatible = "bosch,bmi160"; - reg = <0>; - spi-max-frequency = <10000000>; - interrupt-parent = <&gpio2>; - interrupts = <12 IRQ_TYPE_EDGE_RISING>; - interrupt-names = "INT2"; + compatible = "bosch,bmi160"; + reg = <0>; + spi-max-frequency = <10000000>; + interrupt-parent = <&gpio2>; + interrupts = <12 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "INT2"; }; }; diff --git a/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml b/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml index 13c9abdd3131..7cd05bcbee31 100644 --- a/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml +++ b/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml @@ -65,35 +65,35 @@ examples: - | #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/interrupt-controller/irq.h> - i2c0 { + i2c { #address-cells = <1>; #size-cells = <0>; icm42605@68 { - compatible = "invensense,icm42605"; - reg = <0x68>; - interrupt-parent = <&gpio2>; - interrupts = <7 IRQ_TYPE_EDGE_FALLING>; - vdd-supply = <&vdd>; - vddio-supply = <&vddio>; + compatible = "invensense,icm42605"; + reg = <0x68>; + interrupt-parent = <&gpio2>; + interrupts = <7 IRQ_TYPE_EDGE_FALLING>; + vdd-supply = <&vdd>; + vddio-supply = <&vddio>; }; }; - | #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/interrupt-controller/irq.h> - spi0 { + spi { #address-cells = <1>; #size-cells = <0>; icm42602@0 { - compatible = "invensense,icm42602"; - reg = <0>; - spi-max-frequency = <24000000>; - spi-cpha; - spi-cpol; - interrupt-parent = <&gpio1>; - interrupts = <2 IRQ_TYPE_EDGE_FALLING>; - vdd-supply = <&vdd>; - vddio-supply = <&vddio>; + compatible = "invensense,icm42602"; + reg = <0>; + spi-max-frequency = <24000000>; + spi-cpha; + spi-cpol; + interrupt-parent = <&gpio1>; + interrupts = <2 IRQ_TYPE_EDGE_FALLING>; + vdd-supply = <&vdd>; + vddio-supply = <&vddio>; }; }; diff --git a/Documentation/devicetree/bindings/iio/imu/nxp,fxos8700.yaml b/Documentation/devicetree/bindings/iio/imu/nxp,fxos8700.yaml index 24416b59b782..688100b240bc 100644 --- a/Documentation/devicetree/bindings/iio/imu/nxp,fxos8700.yaml +++ b/Documentation/devicetree/bindings/iio/imu/nxp,fxos8700.yaml @@ -49,33 +49,33 @@ examples: - | #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/interrupt-controller/irq.h> - i2c0 { + i2c { #address-cells = <1>; #size-cells = <0>; fxos8700@1e { - compatible = "nxp,fxos8700"; - reg = <0x1e>; + compatible = "nxp,fxos8700"; + reg = <0x1e>; - interrupt-parent = <&gpio2>; - interrupts = <7 IRQ_TYPE_EDGE_RISING>; - interrupt-names = "INT1"; + interrupt-parent = <&gpio2>; + interrupts = <7 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "INT1"; }; }; - | #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/interrupt-controller/irq.h> - spi0 { + spi { #address-cells = <1>; #size-cells = <0>; fxos8700@0 { - compatible = "nxp,fxos8700"; - reg = <0>; + compatible = "nxp,fxos8700"; + reg = <0>; - spi-max-frequency = <1000000>; - interrupt-parent = <&gpio1>; - interrupts = <7 IRQ_TYPE_EDGE_RISING>; - interrupt-names = "INT2"; + spi-max-frequency = <1000000>; + interrupt-parent = <&gpio1>; + interrupts = <7 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "INT2"; }; }; diff --git a/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml b/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml index 68b481c63318..decf022335d8 100644 --- a/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml +++ b/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml @@ -63,7 +63,7 @@ properties: description: if defined provides VDD IO power to the sensor. st,drdy-int-pin: - $ref: '/schemas/types.yaml#/definitions/uint32' + $ref: /schemas/types.yaml#/definitions/uint32 description: | The pin on the package that will be used to signal data ready enum: diff --git a/Documentation/devicetree/bindings/iio/magnetometer/ti,tmag5273.yaml b/Documentation/devicetree/bindings/iio/magnetometer/ti,tmag5273.yaml new file mode 100644 index 000000000000..121d540b7b6e --- /dev/null +++ b/Documentation/devicetree/bindings/iio/magnetometer/ti,tmag5273.yaml @@ -0,0 +1,75 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/magnetometer/ti,tmag5273.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI TMAG5273 Low-Power Linear 3D Hall-Effect Sensor + +maintainers: + - Gerald Loacker <gerald.loacker@wolfvision.net> + +description: + The TI TMAG5273 is a low-power linear 3D Hall-effect sensor. This device + integrates three independent Hall-effect sensors in the X, Y, and Z axes. + The device has an integrated temperature sensor available. The TMAG5273 + can be configured through the I2C interface to enable any combination of + magnetic axes and temperature measurements. An integrated angle calculation + engine (CORDIC) provides full 360° angular position information for both + on-axis and off-axis angle measurement topologies. The angle calculation is + performed using two user-selected magnetic axes. + +properties: + compatible: + const: ti,tmag5273 + + reg: + maxItems: 1 + + "#io-channel-cells": + const: 1 + + ti,angle-measurement: + $ref: /schemas/types.yaml#/definitions/string + description: + Enables angle measurement in the selected plane. + If not specified, "x-y" will be anables as default. + enum: + - off + - x-y + - y-z + - x-z + + vcc-supply: + description: + A regulator providing 1.7 V to 3.6 V supply voltage on the VCC pin, + typically 3.3 V. + + interrupts: + description: + The low active interrupt can be configured to be fixed width or latched. + Interrupt events can be configured to be generated from magnetic + thresholds or when a conversion is completed. + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + magnetometer@35 { + compatible = "ti,tmag5273"; + reg = <0x35>; + #io-channel-cells = <1>; + ti,angle-measurement = "x-z"; + vcc-supply = <&vcc3v3>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/magnetometer/yamaha,yas530.yaml b/Documentation/devicetree/bindings/iio/magnetometer/yamaha,yas530.yaml index 9438fffaf0ba..877226e9219b 100644 --- a/Documentation/devicetree/bindings/iio/magnetometer/yamaha,yas530.yaml +++ b/Documentation/devicetree/bindings/iio/magnetometer/yamaha,yas530.yaml @@ -91,12 +91,12 @@ examples: #size-cells = <0>; magnetometer@2e { - compatible = "yamaha,yas530"; - reg = <0x2e>; - vdd-supply = <&ldo1_reg>; - iovdd-supply = <&ldo2_reg>; - reset-gpios = <&gpio6 12 GPIO_ACTIVE_LOW>; - interrupts = <13 IRQ_TYPE_EDGE_RISING>; + compatible = "yamaha,yas530"; + reg = <0x2e>; + vdd-supply = <&ldo1_reg>; + iovdd-supply = <&ldo2_reg>; + reset-gpios = <&gpio6 12 GPIO_ACTIVE_LOW>; + interrupts = <13 IRQ_TYPE_EDGE_RISING>; }; }; @@ -105,8 +105,8 @@ examples: #size-cells = <0>; magnetometer@2e { - compatible = "yamaha,yas539"; - reg = <0x2e>; - vdd-supply = <&ldo1_reg>; + compatible = "yamaha,yas539"; + reg = <0x2e>; + vdd-supply = <&ldo1_reg>; }; }; diff --git a/Documentation/devicetree/bindings/iio/potentiometer/adi,ad5272.yaml b/Documentation/devicetree/bindings/iio/potentiometer/adi,ad5272.yaml index 0ebb6725a1af..b8d7083c97f8 100644 --- a/Documentation/devicetree/bindings/iio/potentiometer/adi,ad5272.yaml +++ b/Documentation/devicetree/bindings/iio/potentiometer/adi,ad5272.yaml @@ -44,7 +44,7 @@ examples: potentiometer@2f { compatible = "adi,ad5272-020"; - reg = <0x2F>; + reg = <0x2f>; reset-gpios = <&gpio3 6 GPIO_ACTIVE_LOW>; }; }; diff --git a/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml b/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml index 1f9fe15b4b3c..9fb8d773efa3 100644 --- a/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml +++ b/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml @@ -39,7 +39,7 @@ examples: - | #include <dt-bindings/interrupt-controller/irq.h> - i2c0 { + i2c { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/iio/pressure/bmp085.yaml b/Documentation/devicetree/bindings/iio/pressure/bmp085.yaml index 72cd2c2d3f17..63885af6a74b 100644 --- a/Documentation/devicetree/bindings/iio/pressure/bmp085.yaml +++ b/Documentation/devicetree/bindings/iio/pressure/bmp085.yaml @@ -60,16 +60,16 @@ examples: - | #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/interrupt-controller/irq.h> - i2c0 { - #address-cells = <1>; - #size-cells = <0>; - pressure@77 { - compatible = "bosch,bmp085"; - reg = <0x77>; - interrupt-parent = <&gpio0>; - interrupts = <25 IRQ_TYPE_EDGE_RISING>; - reset-gpios = <&gpio0 26 GPIO_ACTIVE_LOW>; - vddd-supply = <&foo>; - vdda-supply = <&bar>; - }; + i2c { + #address-cells = <1>; + #size-cells = <0>; + pressure@77 { + compatible = "bosch,bmp085"; + reg = <0x77>; + interrupt-parent = <&gpio0>; + interrupts = <25 IRQ_TYPE_EDGE_RISING>; + reset-gpios = <&gpio0 26 GPIO_ACTIVE_LOW>; + vddd-supply = <&foo>; + vdda-supply = <&bar>; + }; }; diff --git a/Documentation/devicetree/bindings/iio/proximity/ams,as3935.yaml b/Documentation/devicetree/bindings/iio/proximity/ams,as3935.yaml index 710d3b9a86d9..c999994e19e3 100644 --- a/Documentation/devicetree/bindings/iio/proximity/ams,as3935.yaml +++ b/Documentation/devicetree/bindings/iio/proximity/ams,as3935.yaml @@ -60,7 +60,7 @@ examples: #address-cells = <1>; #size-cells = <0>; - lightning@0 { + lightning@0 { compatible = "ams,as3935"; reg = <0>; spi-max-frequency = <400000>; diff --git a/Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml b/Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml index 00e3b59641d2..d4e09d2dcd21 100644 --- a/Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml +++ b/Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml @@ -1,7 +1,6 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) %YAML 1.2 --- - $id: http://devicetree.org/schemas/iio/proximity/google,cros-ec-mkbp-proximity.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# diff --git a/Documentation/devicetree/bindings/iio/proximity/semtech,sx9360.yaml b/Documentation/devicetree/bindings/iio/proximity/semtech,sx9360.yaml index f088c5d2be99..ad0bb44f41b6 100644 --- a/Documentation/devicetree/bindings/iio/proximity/semtech,sx9360.yaml +++ b/Documentation/devicetree/bindings/iio/proximity/semtech,sx9360.yaml @@ -36,7 +36,7 @@ properties: const: 1 semtech,resolution: - $ref: /schemas/types.yaml#/definitions/uint32-array + $ref: /schemas/types.yaml#/definitions/uint32 enum: [8, 16, 32, 64, 128, 256, 512, 1024] description: Capacitance measurement resolution. For both phases, "reference" and diff --git a/Documentation/devicetree/bindings/iio/st,st-sensors.yaml b/Documentation/devicetree/bindings/iio/st,st-sensors.yaml index 250439b13152..c6201976378f 100644 --- a/Documentation/devicetree/bindings/iio/st,st-sensors.yaml +++ b/Documentation/devicetree/bindings/iio/st,st-sensors.yaml @@ -39,6 +39,7 @@ properties: - st,lis3lv02dl-accel - st,lng2dm-accel - st,lsm303agr-accel + - st,lsm303c-accel - st,lsm303dl-accel - st,lsm303dlh-accel - st,lsm303dlhc-accel @@ -66,6 +67,7 @@ properties: - st,lis2mdl - st,lis3mdl-magn - st,lsm303agr-magn + - st,lsm303c-magn - st,lsm303dlh-magn - st,lsm303dlhc-magn - st,lsm303dlm-magn diff --git a/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml b/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml index b69813f281da..f44fc32ce87e 100644 --- a/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml +++ b/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml @@ -472,75 +472,74 @@ examples: #size-cells = <0>; temperature-sensor@0 { - compatible = "adi,ltc2983"; - reg = <0>; - - #address-cells = <1>; - #size-cells = <0>; - - interrupts = <20 IRQ_TYPE_EDGE_RISING>; - interrupt-parent = <&gpio>; - - thermocouple@18 { - reg = <18>; - adi,sensor-type = <8>; //Type B - adi,sensor-oc-current-microamp = <10>; - adi,cold-junction-handle = <&diode5>; - }; - - diode5: diode@5 { - reg = <5>; - adi,sensor-type = <28>; - }; - - rsense2: rsense@2 { - reg = <2>; - adi,sensor-type = <29>; - adi,rsense-val-milli-ohms = <1200000>; //1.2Kohms - }; - - rtd@14 { - reg = <14>; - adi,sensor-type = <15>; //PT1000 - /*2-wire, internal gnd, no current rotation*/ - adi,number-of-wires = <2>; - adi,rsense-share; - adi,excitation-current-microamp = <500>; - adi,rsense-handle = <&rsense2>; - }; - - adc@10 { - reg = <10>; - adi,sensor-type = <30>; - adi,single-ended; - }; - - thermistor@12 { - reg = <12>; - adi,sensor-type = <26>; //Steinhart - adi,rsense-handle = <&rsense2>; - adi,custom-steinhart = <0x00F371EC 0x12345678 - 0x2C0F8733 0x10018C66 0xA0FEACCD - 0x90021D99>; //6 entries - }; - - thermocouple@20 { - reg = <20>; - adi,sensor-type = <9>; //custom thermocouple - adi,single-ended; - adi,custom-thermocouple = - /bits/ 64 <(-50220000) 0>, - /bits/ 64 <(-30200000) 99100000>, - /bits/ 64 <(-5300000) 135400000>, - /bits/ 64 <0 273150000>, - /bits/ 64 <40200000 361200000>, - /bits/ 64 <55300000 522100000>, - /bits/ 64 <88300000 720300000>, - /bits/ 64 <132200000 811200000>, - /bits/ 64 <188700000 922500000>, - /bits/ 64 <460400000 1000000000>; //10 pairs - }; - + compatible = "adi,ltc2983"; + reg = <0>; + + #address-cells = <1>; + #size-cells = <0>; + + interrupts = <20 IRQ_TYPE_EDGE_RISING>; + interrupt-parent = <&gpio>; + + thermocouple@18 { + reg = <18>; + adi,sensor-type = <8>; //Type B + adi,sensor-oc-current-microamp = <10>; + adi,cold-junction-handle = <&diode5>; + }; + + diode5: diode@5 { + reg = <5>; + adi,sensor-type = <28>; + }; + + rsense2: rsense@2 { + reg = <2>; + adi,sensor-type = <29>; + adi,rsense-val-milli-ohms = <1200000>; //1.2Kohms + }; + + rtd@14 { + reg = <14>; + adi,sensor-type = <15>; //PT1000 + /*2-wire, internal gnd, no current rotation*/ + adi,number-of-wires = <2>; + adi,rsense-share; + adi,excitation-current-microamp = <500>; + adi,rsense-handle = <&rsense2>; + }; + + adc@10 { + reg = <10>; + adi,sensor-type = <30>; + adi,single-ended; + }; + + thermistor@12 { + reg = <12>; + adi,sensor-type = <26>; //Steinhart + adi,rsense-handle = <&rsense2>; + adi,custom-steinhart = <0x00f371ec 0x12345678 + 0x2c0f8733 0x10018c66 0xa0feaccd + 0x90021d99>; //6 entries + }; + + thermocouple@20 { + reg = <20>; + adi,sensor-type = <9>; //custom thermocouple + adi,single-ended; + adi,custom-thermocouple = + /bits/ 64 <(-50220000) 0>, + /bits/ 64 <(-30200000) 99100000>, + /bits/ 64 <(-5300000) 135400000>, + /bits/ 64 <0 273150000>, + /bits/ 64 <40200000 361200000>, + /bits/ 64 <55300000 522100000>, + /bits/ 64 <88300000 720300000>, + /bits/ 64 <132200000 811200000>, + /bits/ 64 <188700000 922500000>, + /bits/ 64 <460400000 1000000000>; //10 pairs + }; }; }; ... diff --git a/Documentation/devicetree/bindings/iio/temperature/maxim,max31865.yaml b/Documentation/devicetree/bindings/iio/temperature/maxim,max31865.yaml index a2823ed6867b..7cc365e0ebc8 100644 --- a/Documentation/devicetree/bindings/iio/temperature/maxim,max31865.yaml +++ b/Documentation/devicetree/bindings/iio/temperature/maxim,max31865.yaml @@ -43,12 +43,12 @@ examples: #address-cells = <1>; #size-cells = <0>; - temp_sensor@0 { - compatible = "maxim,max31865"; - reg = <0>; - spi-max-frequency = <400000>; - spi-cpha; - maxim,3-wire; + temperature-sensor@0 { + compatible = "maxim,max31865"; + reg = <0>; + spi-max-frequency = <400000>; + spi-cpha; + maxim,3-wire; }; }; ... diff --git a/Documentation/devicetree/bindings/iio/temperature/ti,tmp117.yaml b/Documentation/devicetree/bindings/iio/temperature/ti,tmp117.yaml index 347bc16a4671..c4f1c69f9330 100644 --- a/Documentation/devicetree/bindings/iio/temperature/ti,tmp117.yaml +++ b/Documentation/devicetree/bindings/iio/temperature/ti,tmp117.yaml @@ -1,10 +1,10 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: "http://devicetree.org/schemas/iio/temperature/ti,tmp117.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/iio/temperature/ti,tmp117.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# -title: "TI TMP117 - Digital temperature sensor with integrated NV memory" +title: TI TMP117 - Digital temperature sensor with integrated NV memory description: | TI TMP117 - Digital temperature sensor with integrated NV memory that supports diff --git a/Documentation/devicetree/bindings/input/goodix,gt7375p.yaml b/Documentation/devicetree/bindings/input/goodix,gt7375p.yaml index 1c191bc5a178..ce18d7dadae2 100644 --- a/Documentation/devicetree/bindings/input/goodix,gt7375p.yaml +++ b/Documentation/devicetree/bindings/input/goodix,gt7375p.yaml @@ -36,6 +36,13 @@ properties: vdd-supply: description: The 3.3V supply to the touchscreen. + mainboard-vddio-supply: + description: + The supply on the main board needed to power up IO signals going + to the touchscreen. This supply need not go to the touchscreen + itself as long as it allows the main board to make signals compatible + with what the touchscreen is expecting for its IO rails. + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml b/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml index 0c720dbde36e..12a0d3ecbabb 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml @@ -27,11 +27,13 @@ properties: - qcom,sc7280-cpu-bwmon - qcom,sc8280xp-cpu-bwmon - qcom,sdm845-bwmon + - qcom,sm8550-cpu-bwmon - const: qcom,msm8998-bwmon - const: qcom,msm8998-bwmon # BWMON v4 - items: - enum: - qcom,sc8280xp-llcc-bwmon + - qcom,sm8550-llcc-bwmon - const: qcom,sc7280-llcc-bwmon - const: qcom,sc7280-llcc-bwmon # BWMON v5 - const: qcom,sdm845-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 aadae4424ba9..576992a6dc5a 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml @@ -22,6 +22,7 @@ properties: - qcom,sc7180-osm-l3 - qcom,sc8180x-osm-l3 - qcom,sdm845-osm-l3 + - qcom,sm6350-osm-l3 - qcom,sm8150-osm-l3 - const: qcom,osm-l3 - items: diff --git a/Documentation/devicetree/bindings/interconnect/qcom,qdu1000-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,qdu1000-rpmh.yaml new file mode 100644 index 000000000000..0070b0396e31 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,qdu1000-rpmh.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/qcom,qdu1000-rpmh.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm RPMh Network-On-Chip Interconnect on QDU1000 + +maintainers: + - Georgi Djakov <djakov@kernel.org> + - Odelu Kukatla <quic_okukatla@quicinc.com> + +description: | + RPMh interconnect providers support system bandwidth requirements through + RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is + able to communicate with the BCM through the Resource State Coordinator (RSC) + associated with each execution environment. Provider nodes must point to at + least one RPMh device child node pertaining to their RSC and each provider + can map to multiple RPMh resources. + +properties: + compatible: + enum: + - qcom,qdu1000-clk-virt + - qcom,qdu1000-gem-noc + - qcom,qdu1000-mc-virt + - qcom,qdu1000-system-noc + + '#interconnect-cells': true + + reg: + maxItems: 1 + +allOf: + - $ref: qcom,rpmh-common.yaml# + - if: + properties: + compatible: + contains: + enum: + - qcom,qdu1000-clk-virt + - qcom,qdu1000-mc-virt + then: + properties: + reg: false + else: + required: + - reg + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interconnect/qcom,qdu1000-rpmh.h> + + system_noc: interconnect@1640000 { + compatible = "qcom,qdu1000-system-noc"; + reg = <0x1640000 0x45080>; + #interconnect-cells = <2>; + qcom,bcm-voters = <&apps_bcm_voter>; + }; + + clk_virt: interconnect-0 { + compatible = "qcom,qdu1000-clk-virt"; + #interconnect-cells = <2>; + qcom,bcm-voters = <&apps_bcm_voter>; + }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml b/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml index 4b37aa88a375..d9d243c5514b 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml @@ -62,6 +62,37 @@ properties: power-domains: maxItems: 1 +# Child node's properties +patternProperties: + '^interconnect-[a-z0-9]+$': + type: object + description: + snoc-mm is a child of snoc, sharing snoc's register address space. + + properties: + compatible: + enum: + - qcom,msm8939-snoc-mm + + '#interconnect-cells': + const: 1 + + clock-names: + items: + - const: bus + - const: bus_a + + clocks: + items: + - description: Bus Clock + - description: Bus A Clock + + required: + - compatible + - '#interconnect-cells' + - clock-names + - clocks + required: - compatible - reg @@ -84,7 +115,6 @@ allOf: - qcom,msm8939-pcnoc - qcom,msm8939-snoc - qcom,msm8996-a1noc - - qcom,msm8996-a2noc - qcom,msm8996-bimc - qcom,msm8996-cnoc - qcom,msm8996-pnoc @@ -109,37 +139,6 @@ allOf: - description: Bus Clock - description: Bus A Clock - # Child node's properties - patternProperties: - '^interconnect-[a-z0-9]+$': - type: object - description: - snoc-mm is a child of snoc, sharing snoc's register address space. - - properties: - compatible: - enum: - - qcom,msm8939-snoc-mm - - '#interconnect-cells': - const: 1 - - clock-names: - items: - - const: bus - - const: bus_a - - clocks: - items: - - description: Bus Clock - - description: Bus A Clock - - required: - - compatible - - '#interconnect-cells' - - clock-names - - clocks - - if: properties: compatible: @@ -191,6 +190,29 @@ allOf: compatible: contains: enum: + - qcom,msm8996-a2noc + + then: + properties: + clock-names: + items: + - const: bus + - const: bus_a + - const: aggre2_ufs_axi + - const: ufs_axi + + clocks: + items: + - description: Bus Clock + - description: Bus A Clock + - description: Aggregate2 NoC UFS AXI Clock + - description: UFS AXI Clock + + - if: + properties: + compatible: + contains: + enum: - qcom,sdm660-a2noc then: @@ -215,6 +237,17 @@ allOf: - description: Aggregate2 USB3 AXI Clock. - description: Config NoC USB2 AXI Clock. + - if: + not: + properties: + compatible: + contains: + enum: + - qcom,msm8939-snoc + then: + patternProperties: + '^interconnect-[a-z0-9]+$': false + examples: - | #include <dt-bindings/clock/qcom,rpmcc.h> diff --git a/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml index a429a1ed1006..4d93ad415e0b 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml @@ -39,18 +39,6 @@ properties: - qcom,sc7180-npu-noc - qcom,sc7180-qup-virt - qcom,sc7180-system-noc - - qcom,sc7280-aggre1-noc - - qcom,sc7280-aggre2-noc - - qcom,sc7280-clk-virt - - qcom,sc7280-cnoc2 - - qcom,sc7280-cnoc3 - - qcom,sc7280-dc-noc - - qcom,sc7280-gem-noc - - qcom,sc7280-lpass-ag-noc - - qcom,sc7280-mc-virt - - qcom,sc7280-mmss-noc - - qcom,sc7280-nsp-noc - - qcom,sc7280-system-noc - qcom,sc8180x-aggre1-noc - qcom,sc8180x-aggre2-noc - qcom,sc8180x-camnoc-virt @@ -58,23 +46,18 @@ properties: - qcom,sc8180x-config-noc - qcom,sc8180x-dc-noc - qcom,sc8180x-gem-noc - - qcom,sc8180x-ipa-virt - qcom,sc8180x-mc-virt - qcom,sc8180x-mmss-noc - qcom,sc8180x-qup-virt - qcom,sc8180x-system-noc - - qcom,sc8280xp-aggre1-noc - - qcom,sc8280xp-aggre2-noc - - qcom,sc8280xp-clk-virt - - qcom,sc8280xp-config-noc - - qcom,sc8280xp-dc-noc - - qcom,sc8280xp-gem-noc - - qcom,sc8280xp-lpass-ag-noc - - qcom,sc8280xp-mc-virt - - qcom,sc8280xp-mmss-noc - - qcom,sc8280xp-nspa-noc - - qcom,sc8280xp-nspb-noc - - qcom,sc8280xp-system-noc + - qcom,sdm670-aggre1-noc + - qcom,sdm670-aggre2-noc + - qcom,sdm670-config-noc + - qcom,sdm670-dc-noc + - qcom,sdm670-gladiator-noc + - qcom,sdm670-mem-noc + - qcom,sdm670-mmss-noc + - qcom,sdm670-system-noc - qcom,sdm845-aggre1-noc - qcom,sdm845-aggre2-noc - qcom,sdm845-config-noc @@ -96,7 +79,6 @@ properties: - qcom,sm8150-config-noc - qcom,sm8150-dc-noc - qcom,sm8150-gem-noc - - qcom,sm8150-ipa-virt - qcom,sm8150-mc-virt - qcom,sm8150-mmss-noc - qcom,sm8150-system-noc @@ -106,7 +88,6 @@ properties: - qcom,sm8250-config-noc - qcom,sm8250-dc-noc - qcom,sm8250-gem-noc - - qcom,sm8250-ipa-virt - qcom,sm8250-mc-virt - qcom,sm8250-mmss-noc - qcom,sm8250-npu-noc @@ -121,17 +102,6 @@ properties: - qcom,sm8350-mmss-noc - qcom,sm8350-compute-noc - qcom,sm8350-system-noc - - qcom,sm8450-aggre1-noc - - qcom,sm8450-aggre2-noc - - qcom,sm8450-clk-virt - - qcom,sm8450-config-noc - - qcom,sm8450-gem-noc - - qcom,sm8450-lpass-ag-noc - - qcom,sm8450-mc-virt - - qcom,sm8450-mmss-noc - - qcom,sm8450-nsp-noc - - qcom,sm8450-pcie-anoc - - qcom,sm8450-system-noc '#interconnect-cells': true diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sa8775p-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sa8775p-rpmh.yaml new file mode 100644 index 000000000000..2e0c0bc7a376 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,sa8775p-rpmh.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/qcom,sa8775p-rpmh.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm RPMh Network-On-Chip Interconnect on SA8775P + +maintainers: + - Bartosz Golaszewski <bartosz.golaszewski@linaro.org> + +description: | + RPMh interconnect providers support system bandwidth requirements through + RPMh hardware accelerators known as Bus Clock Manager (BCM). + + See also:: include/dt-bindings/interconnect/qcom,sa8775p.h + +properties: + compatible: + enum: + - qcom,sa8775p-aggre1-noc + - qcom,sa8775p-aggre2-noc + - qcom,sa8775p-clk-virt + - qcom,sa8775p-config-noc + - qcom,sa8775p-dc-noc + - qcom,sa8775p-gem-noc + - qcom,sa8775p-gpdsp-anoc + - qcom,sa8775p-lpass-ag-noc + - qcom,sa8775p-mc-virt + - qcom,sa8775p-mmss-noc + - qcom,sa8775p-nspa-noc + - qcom,sa8775p-nspb-noc + - qcom,sa8775p-pcie-anoc + - qcom,sa8775p-system-noc + +required: + - compatible + +allOf: + - $ref: qcom,rpmh-common.yaml# + +unevaluatedProperties: false + +examples: + - | + aggre1_noc: interconnect-aggre1-noc { + compatible = "qcom,sa8775p-aggre1-noc"; + #interconnect-cells = <2>; + qcom,bcm-voters = <&apps_bcm_voter>; + }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sc7280-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sc7280-rpmh.yaml new file mode 100644 index 000000000000..b135597d9489 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,sc7280-rpmh.yaml @@ -0,0 +1,71 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/qcom,sc7280-rpmh.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm RPMh Network-On-Chip Interconnect on SC7280 + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Konrad Dybcio <konrad.dybcio@linaro.org> + +description: | + RPMh interconnect providers support system bandwidth requirements through + RPMh hardware accelerators known as Bus Clock Manager (BCM). + + See also:: include/dt-bindings/interconnect/qcom,sc7280.h + +properties: + compatible: + enum: + - qcom,sc7280-aggre1-noc + - qcom,sc7280-aggre2-noc + - qcom,sc7280-clk-virt + - qcom,sc7280-cnoc2 + - qcom,sc7280-cnoc3 + - qcom,sc7280-dc-noc + - qcom,sc7280-gem-noc + - qcom,sc7280-lpass-ag-noc + - qcom,sc7280-mc-virt + - qcom,sc7280-mmss-noc + - qcom,sc7280-nsp-noc + - qcom,sc7280-system-noc + + reg: + maxItems: 1 + +required: + - compatible + +allOf: + - $ref: qcom,rpmh-common.yaml# + - if: + properties: + compatible: + contains: + enum: + - qcom,sc7280-clk-virt + then: + properties: + reg: false + else: + required: + - reg + +unevaluatedProperties: false + +examples: + - | + interconnect { + compatible = "qcom,sc7280-clk-virt"; + #interconnect-cells = <2>; + qcom,bcm-voters = <&apps_bcm_voter>; + }; + + interconnect@9100000 { + reg = <0x9100000 0xe2200>; + compatible = "qcom,sc7280-gem-noc"; + #interconnect-cells = <2>; + qcom,bcm-voters = <&apps_bcm_voter>; + }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sc8280xp-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sc8280xp-rpmh.yaml new file mode 100644 index 000000000000..6c2da03f0cd2 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,sc8280xp-rpmh.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/qcom,sc8280xp-rpmh.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm RPMh Network-On-Chip Interconnect on SC8280XP + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Konrad Dybcio <konrad.dybcio@linaro.org> + +description: | + RPMh interconnect providers support system bandwidth requirements through + RPMh hardware accelerators known as Bus Clock Manager (BCM). + + See also:: include/dt-bindings/interconnect/qcom,sc8280xp.h + +properties: + compatible: + enum: + - qcom,sc8280xp-aggre1-noc + - qcom,sc8280xp-aggre2-noc + - qcom,sc8280xp-clk-virt + - qcom,sc8280xp-config-noc + - qcom,sc8280xp-dc-noc + - qcom,sc8280xp-gem-noc + - qcom,sc8280xp-lpass-ag-noc + - qcom,sc8280xp-mc-virt + - qcom,sc8280xp-mmss-noc + - qcom,sc8280xp-nspa-noc + - qcom,sc8280xp-nspb-noc + - qcom,sc8280xp-system-noc + +required: + - compatible + +allOf: + - $ref: qcom,rpmh-common.yaml# + +unevaluatedProperties: false + +examples: + - | + interconnect-0 { + compatible = "qcom,sc8280xp-aggre1-noc"; + #interconnect-cells = <2>; + qcom,bcm-voters = <&apps_bcm_voter>; + }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sm8450-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sm8450-rpmh.yaml new file mode 100644 index 000000000000..3cff7e662255 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,sm8450-rpmh.yaml @@ -0,0 +1,124 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/qcom,sm8450-rpmh.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm RPMh Network-On-Chip Interconnect on SM8450 + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Konrad Dybcio <konrad.dybcio@linaro.org> + +description: | + RPMh interconnect providers support system bandwidth requirements through + RPMh hardware accelerators known as Bus Clock Manager (BCM). + + See also:: include/dt-bindings/interconnect/qcom,sm8450.h + +properties: + compatible: + enum: + - qcom,sm8450-aggre1-noc + - qcom,sm8450-aggre2-noc + - qcom,sm8450-clk-virt + - qcom,sm8450-config-noc + - qcom,sm8450-gem-noc + - qcom,sm8450-lpass-ag-noc + - qcom,sm8450-mc-virt + - qcom,sm8450-mmss-noc + - qcom,sm8450-nsp-noc + - qcom,sm8450-pcie-anoc + - qcom,sm8450-system-noc + + reg: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 4 + +required: + - compatible + +allOf: + - $ref: qcom,rpmh-common.yaml# + - if: + properties: + compatible: + contains: + enum: + - qcom,sm8450-clk-virt + - qcom,sm8450-mc-virt + then: + properties: + reg: false + else: + required: + - reg + + - if: + properties: + compatible: + contains: + enum: + - qcom,sm8450-aggre1-noc + then: + properties: + clocks: + items: + - description: aggre UFS PHY AXI clock + - description: aggre USB3 PRIM AXI clock + + - if: + properties: + compatible: + contains: + enum: + - qcom,sm8450-aggre2-noc + then: + properties: + clocks: + items: + - description: aggre-NOC PCIe 0 AXI clock + - description: aggre-NOC PCIe 1 AXI clock + - description: aggre UFS PHY AXI clock + - description: RPMH CC IPA clock + + - if: + properties: + compatible: + contains: + enum: + - qcom,sm8450-aggre1-noc + - qcom,sm8450-aggre2-noc + then: + required: + - clocks + else: + properties: + clocks: false + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-sm8450.h> + #include <dt-bindings/clock/qcom,rpmh.h> + + interconnect-0 { + compatible = "qcom,sm8450-clk-virt"; + #interconnect-cells = <2>; + qcom,bcm-voters = <&apps_bcm_voter>; + }; + + interconnect@1700000 { + compatible = "qcom,sm8450-aggre2-noc"; + reg = <0x01700000 0x31080>; + #interconnect-cells = <2>; + qcom,bcm-voters = <&apps_bcm_voter>; + clocks = <&gcc GCC_AGGRE_NOC_PCIE_0_AXI_CLK>, + <&gcc GCC_AGGRE_NOC_PCIE_1_AXI_CLK>, + <&gcc GCC_AGGRE_UFS_PHY_AXI_CLK>, + <&rpmhcc RPMH_IPA_CLK>; + }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sm8550-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sm8550-rpmh.yaml new file mode 100644 index 000000000000..716bd21f6041 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,sm8550-rpmh.yaml @@ -0,0 +1,139 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/qcom,sm8550-rpmh.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm RPMh Network-On-Chip Interconnect on SM8550 + +maintainers: + - Abel Vesa <abel.vesa@linaro.org> + - Neil Armstrong <neil.armstrong@linaro.org> + +description: | + RPMh interconnect providers support system bandwidth requirements through + RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is + able to communicate with the BCM through the Resource State Coordinator (RSC) + associated with each execution environment. Provider nodes must point to at + least one RPMh device child node pertaining to their RSC and each provider + can map to multiple RPMh resources. + + See also:: include/dt-bindings/interconnect/qcom,sm8550-rpmh.h + +properties: + compatible: + enum: + - qcom,sm8550-aggre1-noc + - qcom,sm8550-aggre2-noc + - qcom,sm8550-clk-virt + - qcom,sm8550-cnoc-main + - qcom,sm8550-config-noc + - qcom,sm8550-gem-noc + - qcom,sm8550-lpass-ag-noc + - qcom,sm8550-lpass-lpiaon-noc + - qcom,sm8550-lpass-lpicx-noc + - qcom,sm8550-mc-virt + - qcom,sm8550-mmss-noc + - qcom,sm8550-nsp-noc + - qcom,sm8550-pcie-anoc + - qcom,sm8550-system-noc + + reg: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 2 + +allOf: + - $ref: qcom,rpmh-common.yaml# + - if: + properties: + compatible: + contains: + enum: + - qcom,sm8550-clk-virt + - qcom,sm8550-mc-virt + then: + properties: + reg: false + else: + required: + - reg + + - if: + properties: + compatible: + contains: + enum: + - qcom,sm8550-pcie-anoc + then: + properties: + clocks: + items: + - description: aggre-NOC PCIe AXI clock + - description: cfg-NOC PCIe a-NOC AHB clock + + - if: + properties: + compatible: + contains: + enum: + - qcom,sm8550-aggre1-noc + then: + properties: + clocks: + items: + - description: aggre UFS PHY AXI clock + - description: aggre USB3 PRIM AXI clock + + - if: + properties: + compatible: + contains: + enum: + - qcom,sm8550-aggre2-noc + then: + properties: + clocks: + items: + - description: RPMH CC IPA clock + + - if: + properties: + compatible: + contains: + enum: + - qcom,sm8550-aggre1-noc + - qcom,sm8550-aggre2-noc + - qcom,sm8550-pcie-anoc + then: + required: + - clocks + else: + properties: + clocks: false + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,sm8550-gcc.h> + + clk_virt: interconnect-0 { + compatible = "qcom,sm8550-clk-virt"; + #interconnect-cells = <2>; + qcom,bcm-voters = <&apps_bcm_voter>; + }; + + aggre1_noc: interconnect@16e0000 { + compatible = "qcom,sm8550-aggre1-noc"; + reg = <0x016e0000 0x14400>; + #interconnect-cells = <2>; + clocks = <&gcc GCC_AGGRE_UFS_PHY_AXI_CLK>, + <&gcc GCC_AGGRE_USB3_PRIM_AXI_CLK>; + qcom,bcm-voters = <&apps_bcm_voter>; + }; diff --git a/Documentation/devicetree/bindings/interconnect/samsung,exynos-bus.yaml b/Documentation/devicetree/bindings/interconnect/samsung,exynos-bus.yaml index ad9ed596dfef..5e26e48c7217 100644 --- a/Documentation/devicetree/bindings/interconnect/samsung,exynos-bus.yaml +++ b/Documentation/devicetree/bindings/interconnect/samsung,exynos-bus.yaml @@ -196,6 +196,8 @@ properties: maxItems: 2 operating-points-v2: true + opp-table: + type: object samsung,data-clock-ratio: $ref: /schemas/types.yaml#/definitions/uint32 @@ -227,6 +229,31 @@ examples: operating-points-v2 = <&bus_dmc_opp_table>; devfreq-events = <&ppmu_dmc0_3>, <&ppmu_dmc1_3>; vdd-supply = <&buck1_reg>; + + bus_dmc_opp_table: opp-table { + compatible = "operating-points-v2"; + + opp-50000000 { + opp-hz = /bits/ 64 <50000000>; + opp-microvolt = <800000>; + }; + opp-100000000 { + opp-hz = /bits/ 64 <100000000>; + opp-microvolt = <800000>; + }; + opp-134000000 { + opp-hz = /bits/ 64 <134000000>; + opp-microvolt = <800000>; + }; + opp-200000000 { + opp-hz = /bits/ 64 <200000000>; + opp-microvolt = <825000>; + }; + opp-400000000 { + opp-hz = /bits/ 64 <400000000>; + opp-microvolt = <875000>; + }; + }; }; ppmu_dmc0: ppmu@106a0000 { diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml index 9f7d3e11aacb..8449e14af9f3 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml @@ -108,7 +108,7 @@ properties: msi-controller: description: - Only present if the Message Based Interrupt functionnality is + Only present if the Message Based Interrupt functionality is being exposed by the HW, and the mbi-ranges property present. mbi-ranges: 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 46b2eb3c43ee..c680de1cbd56 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.yaml @@ -109,7 +109,8 @@ properties: for system suspend/resume. brcm,int-fwd-mask: - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: /schemas/types.yaml#/definitions/uint32-array + maxItems: 1 description: > if present, a bit mask to configure the interrupts which have a mux gate, typically UARTs. Setting these bits will make their respective interrupt diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,ls1x-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/loongson,ls1x-intc.txt deleted file mode 100644 index a63ed9fcb535..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/loongson,ls1x-intc.txt +++ /dev/null @@ -1,24 +0,0 @@ -Loongson ls1x Interrupt Controller - -Required properties: - -- compatible : should be "loongson,ls1x-intc". Valid strings are: - -- reg : Specifies base physical address and size of the registers. -- interrupt-controller : Identifies the node as an interrupt controller -- #interrupt-cells : Specifies the number of cells needed to encode an - interrupt source. The value shall be 2. -- interrupts : Specifies the CPU interrupt the controller is connected to. - -Example: - -intc: interrupt-controller@1fd01040 { - compatible = "loongson,ls1x-intc"; - reg = <0x1fd01040 0x18>; - - interrupt-controller; - #interrupt-cells = <2>; - - interrupt-parent = <&cpu_intc>; - interrupts = <2>; -}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,ls1x-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,ls1x-intc.yaml new file mode 100644 index 000000000000..c60125fb1cbf --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,ls1x-intc.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/loongson,ls1x-intc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Loongson-1 Interrupt Controller + +maintainers: + - Keguang Zhang <keguang.zhang@gmail.com> + +description: + Loongson-1 interrupt controller is connected to the MIPS core interrupt + controller, which controls several groups of interrupts. + +properties: + compatible: + const: loongson,ls1x-intc + + reg: + maxItems: 1 + + interrupt-controller: true + + '#interrupt-cells': + const: 2 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupt-controller + - '#interrupt-cells' + - interrupts + +additionalProperties: false + +examples: + - | + intc0: interrupt-controller@1fd01040 { + compatible = "loongson,ls1x-intc"; + reg = <0x1fd01040 0x18>; + + interrupt-controller; + #interrupt-cells = <2>; + + interrupt-parent = <&cpu_intc>; + interrupts = <2>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/samsung,s3c24xx-irq.txt b/Documentation/devicetree/bindings/interrupt-controller/samsung,s3c24xx-irq.txt deleted file mode 100644 index c54c5a9a2a90..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/samsung,s3c24xx-irq.txt +++ /dev/null @@ -1,53 +0,0 @@ -Samsung S3C24XX Interrupt Controllers - -The S3C24XX SoCs contain a custom set of interrupt controllers providing a -varying number of interrupt sources. The set consists of a main- and sub- -controller and on newer SoCs even a second main controller. - -Required properties: -- compatible: Compatible property value should be "samsung,s3c2410-irq" - for machines before s3c2416 and "samsung,s3c2416-irq" for s3c2416 and later. - -- reg: Physical base address of the controller and length of memory mapped - region. - -- interrupt-controller : Identifies the node as an interrupt controller - -- #interrupt-cells : Specifies the number of cells needed to encode an - interrupt source. The value shall be 4 and interrupt descriptor shall - have the following format: - <ctrl_num parent_irq ctrl_irq type> - - ctrl_num contains the controller to use: - - 0 ... main controller - - 1 ... sub controller - - 2 ... second main controller on s3c2416 and s3c2450 - parent_irq contains the parent bit in the main controller and will be - ignored in main controllers - ctrl_irq contains the interrupt bit of the controller - type contains the trigger type to use - -Example: - - interrupt-controller@4a000000 { - compatible = "samsung,s3c2410-irq"; - reg = <0x4a000000 0x100>; - interrupt-controller; - #interrupt-cells=<4>; - }; - - [...] - - serial@50000000 { - compatible = "samsung,s3c2410-uart"; - reg = <0x50000000 0x4000>; - interrupt-parent = <&subintc>; - interrupts = <1 28 0 4>, <1 28 1 4>; - }; - - rtc@57000000 { - compatible = "samsung,s3c2410-rtc"; - reg = <0x57000000 0x100>; - interrupt-parent = <&intc>; - interrupts = <0 30 0 3>, <0 8 0 3>; - }; 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 99e01f4d0a69..63bc89e13480 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 @@ -45,7 +45,6 @@ description: from S-mode. So add thead,c900-plic to distinguish them. maintainers: - - Sagar Kadam <sagar.kadam@sifive.com> - Paul Walmsley <paul.walmsley@sifive.com> - Palmer Dabbelt <palmer@dabbelt.com> diff --git a/Documentation/devicetree/bindings/interrupt-controller/socionext,synquacer-exiu.txt b/Documentation/devicetree/bindings/interrupt-controller/socionext,synquacer-exiu.txt deleted file mode 100644 index dac0846fe789..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/socionext,synquacer-exiu.txt +++ /dev/null @@ -1,31 +0,0 @@ -Socionext SynQuacer External Interrupt Unit (EXIU) - -The Socionext Synquacer SoC has an external interrupt unit (EXIU) -that forwards a block of 32 configurable input lines to 32 adjacent -level-high type GICv3 SPIs. - -Required properties: - -- compatible : Should be "socionext,synquacer-exiu". -- reg : Specifies base physical address and size of the - control registers. -- interrupt-controller : Identifies the node as an interrupt controller. -- #interrupt-cells : Specifies the number of cells needed to encode an - interrupt source. The value must be 3. -- socionext,spi-base : The SPI number of the first SPI of the 32 adjacent - ones the EXIU forwards its interrups to. - -Notes: - -- Only SPIs can use the EXIU as an interrupt parent. - -Example: - - exiu: interrupt-controller@510c0000 { - compatible = "socionext,synquacer-exiu"; - reg = <0x0 0x510c0000 0x0 0x20>; - interrupt-controller; - interrupt-parent = <&gic>; - #interrupt-cells = <3>; - socionext,spi-base = <112>; - }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/socionext,synquacer-exiu.yaml b/Documentation/devicetree/bindings/interrupt-controller/socionext,synquacer-exiu.yaml new file mode 100644 index 000000000000..92cec2255cca --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/socionext,synquacer-exiu.yaml @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/socionext,synquacer-exiu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext SynQuacer External Interrupt Unit (EXIU) + +maintainers: + - Ard Biesheuvel <ardb@kernel.org> + +description: |+ + The Socionext SynQuacer SoC has an external interrupt unit (EXIU) + that forwards a block of 32 configurable input lines to 32 adjacent + level-high type GICv3 SPIs. + +properties: + compatible: + const: socionext,synquacer-exiu + + reg: + maxItems: 1 + + '#interrupt-cells': + const: 3 + + interrupt-controller: true + + socionext,spi-base: + $ref: /schemas/types.yaml#/definitions/uint32 + description: The SPI number of the first SPI of the 32 adjacent ones the + EXIU forwards its interrupts to. + +required: + - compatible + - reg + - '#interrupt-cells' + - interrupt-controller + - socionext,spi-base + +unevaluatedProperties: false + +examples: + - | + interrupt-controller@510c0000 { + compatible = "socionext,synquacer-exiu"; + reg = <0x510c0000 0x20>; + interrupt-controller; + interrupt-parent = <&gic>; + #interrupt-cells = <3>; + socionext,spi-base = <112>; + }; +... diff --git a/Documentation/devicetree/bindings/iommu/apple,dart.yaml b/Documentation/devicetree/bindings/iommu/apple,dart.yaml index 06af2bacbe97..903edf85d72e 100644 --- a/Documentation/devicetree/bindings/iommu/apple,dart.yaml +++ b/Documentation/devicetree/bindings/iommu/apple,dart.yaml @@ -24,6 +24,7 @@ properties: compatible: enum: - apple,t8103-dart + - apple,t8110-dart - apple,t6000-dart reg: diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu.yaml b/Documentation/devicetree/bindings/iommu/arm,smmu.yaml index b28c5c2b0ff2..807cb511fe18 100644 --- a/Documentation/devicetree/bindings/iommu/arm,smmu.yaml +++ b/Documentation/devicetree/bindings/iommu/arm,smmu.yaml @@ -36,13 +36,17 @@ properties: - enum: - qcom,qcm2290-smmu-500 - qcom,qdu1000-smmu-500 + - qcom,sa8775p-smmu-500 - qcom,sc7180-smmu-500 - qcom,sc7280-smmu-500 - qcom,sc8180x-smmu-500 - qcom,sc8280xp-smmu-500 - qcom,sdm670-smmu-500 - qcom,sdm845-smmu-500 + - qcom,sdx55-smmu-500 + - qcom,sdx65-smmu-500 - qcom,sm6115-smmu-500 + - qcom,sm6125-smmu-500 - qcom,sm6350-smmu-500 - qcom,sm6375-smmu-500 - qcom,sm8150-smmu-500 @@ -52,14 +56,6 @@ properties: - const: qcom,smmu-500 - const: arm,mmu-500 - - description: Qcom SoCs implementing "arm,mmu-500" (non-qcom implementation) - deprecated: true - items: - - enum: - - qcom,sdx55-smmu-500 - - qcom,sdx65-smmu-500 - - const: arm,mmu-500 - - description: Qcom SoCs implementing "arm,mmu-500" (legacy binding) deprecated: true items: @@ -84,6 +80,7 @@ properties: items: - enum: - qcom,sc7280-smmu-500 + - qcom,sm8150-smmu-500 - qcom,sm8250-smmu-500 - const: qcom,adreno-smmu - const: arm,mmu-500 @@ -201,7 +198,8 @@ properties: maxItems: 7 power-domains: - maxItems: 1 + minItems: 1 + maxItems: 3 nvidia,memory-controller: description: | @@ -366,6 +364,56 @@ allOf: - description: interface clock required to access smmu's registers through the TCU's programming interface. + # Disallow clocks for all other platforms with specific compatibles + - if: + properties: + compatible: + contains: + enum: + - cavium,smmu-v2 + - marvell,ap806-smmu-500 + - nvidia,smmu-500 + - qcom,qcm2290-smmu-500 + - qcom,qdu1000-smmu-500 + - qcom,sa8775p-smmu-500 + - qcom,sc7180-smmu-500 + - qcom,sc8180x-smmu-500 + - qcom,sc8280xp-smmu-500 + - qcom,sdm670-smmu-500 + - qcom,sdm845-smmu-500 + - qcom,sdx55-smmu-500 + - qcom,sdx65-smmu-500 + - qcom,sm6115-smmu-500 + - qcom,sm6125-smmu-500 + - qcom,sm6350-smmu-500 + - qcom,sm6375-smmu-500 + - qcom,sm8350-smmu-500 + - qcom,sm8450-smmu-500 + then: + properties: + clock-names: false + clocks: false + + - if: + properties: + compatible: + contains: + const: qcom,sm6375-smmu-500 + then: + properties: + power-domains: + items: + - description: SNoC MMU TBU RT GDSC + - description: SNoC MMU TBU NRT GDSC + - description: SNoC TURING MMU TBU0 GDSC + + required: + - power-domains + else: + properties: + power-domains: + maxItems: 1 + examples: - |+ /* SMMU with stream matching or stream indexing */ diff --git a/Documentation/devicetree/bindings/iommu/qcom,iommu.txt b/Documentation/devicetree/bindings/iommu/qcom,iommu.txt index 059139abce35..e6cecfd360eb 100644 --- a/Documentation/devicetree/bindings/iommu/qcom,iommu.txt +++ b/Documentation/devicetree/bindings/iommu/qcom,iommu.txt @@ -10,6 +10,7 @@ to non-secure vs secure interrupt line. - compatible : Should be one of: "qcom,msm8916-iommu" + "qcom,msm8953-iommu" Followed by "qcom,msm-iommu-v1". diff --git a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml index 26d0a5121f02..72308a4c14e7 100644 --- a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml +++ b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml @@ -49,6 +49,7 @@ properties: - enum: - renesas,ipmmu-r8a779a0 # R-Car V3U - renesas,ipmmu-r8a779f0 # R-Car S4-8 + - renesas,ipmmu-r8a779g0 # R-Car V4H - const: renesas,rcar-gen4-ipmmu-vmsa # R-Car Gen4 reg: diff --git a/Documentation/devicetree/bindings/leds/backlight/kinetic,ktz8866.yaml b/Documentation/devicetree/bindings/leds/backlight/kinetic,ktz8866.yaml new file mode 100644 index 000000000000..e1191453c2f0 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/backlight/kinetic,ktz8866.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/backlight/kinetic,ktz8866.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Kinetic Technologies KTZ8866 backlight + +maintainers: + - Jianhua Lu <lujianhua000@gmail.com> + +description: | + The Kinetic Technologies KTZ8866 is a high efficiency 6-channels-current-sinks + led backlight with dual lcd bias power. + https://www.kinet-ic.com/ktz8866/ + +allOf: + - $ref: common.yaml# + +properties: + compatible: + const: kinetic,ktz8866 + + vddpos-supply: + description: positive boost supply regulator. + + vddneg-supply: + description: negative boost supply regulator. + + enable-gpios: + description: GPIO to use to enable/disable the backlight (HWEN pin). + maxItems: 1 + + current-num-sinks: + description: number of the LED current sinks' channels. + enum: [1, 2, 3, 4, 5, 6] + + kinetic,current-ramp-delay-ms: + description: | + LED current ramping delay time in milliseconds, note that the + case 1 will be mapped to 1μs. + enum: [1, 2, 4, 8, 16, 32, 64, 128, 192, 256, 320, 384, 448, 512, 576, 640] + + kinetic,led-enable-ramp-delay-ms: + description: | + LED on/off ramping delay time in milliseconds, note that the case 0 will be + mapped to 512μs because ktz8866 can't ramp faster than it. + enum: [0, 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384] + + kinetic,enable-lcd-bias: + description: Set if we want to output bias power supply for LCD. + type: boolean + +required: + - compatible + - vddpos-supply + - vddneg-supply + - enable-gpios + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + backlight { + compatible = "kinetic,ktz8866"; + + vddpos-supply = <&bl_vddpos_5p5>; + vddneg-supply = <&bl_vddneg_5p5>; + enable-gpios = <&tlmm 139 GPIO_ACTIVE_HIGH>; + current-num-sinks = <5>; + kinetic,current-ramp-delay-ms = <128>; + kinetic,led-enable-ramp-delay-ms = <1>; + kinetic,enable-lcd-bias; + }; diff --git a/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml b/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml index 9acdb7895514..5f1849bdabba 100644 --- a/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml +++ b/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml @@ -19,6 +19,7 @@ properties: compatible: enum: - qcom,pm8941-wled + - qcom,pmi8950-wled - qcom,pmi8994-wled - qcom,pmi8998-wled - qcom,pm660l-wled diff --git a/Documentation/devicetree/bindings/leds/common.yaml b/Documentation/devicetree/bindings/leds/common.yaml index f5c57a580078..15e3f6645682 100644 --- a/Documentation/devicetree/bindings/leds/common.yaml +++ b/Documentation/devicetree/bindings/leds/common.yaml @@ -90,17 +90,22 @@ properties: - heartbeat # LED indicates disk activity - disk-activity - # LED indicates IDE disk activity (deprecated), in new implementations - # use "disk-activity" - - ide-disk + - disk-read + - disk-write # LED flashes at a fixed, configurable rate - timer # LED alters the brightness for the specified duration with one software # timer (requires "led-pattern" property) - pattern - # LED is triggered by SD/MMC activity - - pattern: "^mmc[0-9]+$" + - usb-gadget + - usb-host - pattern: "^cpu[0-9]*$" + - pattern: "^hci[0-9]+-power$" + # LED is triggered by Bluetooth activity + - pattern: "^mmc[0-9]+$" + # LED is triggered by SD/MMC activity + - pattern: "^phy[0-9]+tx$" + # LED is triggered by WLAN activity led-pattern: description: | diff --git a/Documentation/devicetree/bindings/bus/intel,ixp4xx-expansion-bus-controller.yaml b/Documentation/devicetree/bindings/memory-controllers/intel,ixp4xx-expansion-bus-controller.yaml index 5fb4e7bfa4da..188db821dff3 100644 --- a/Documentation/devicetree/bindings/bus/intel,ixp4xx-expansion-bus-controller.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/intel,ixp4xx-expansion-bus-controller.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/bus/intel,ixp4xx-expansion-bus-controller.yaml# +$id: http://devicetree.org/schemas/memory-controllers/intel,ixp4xx-expansion-bus-controller.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Intel IXP4xx Expansion Bus Controller @@ -56,69 +56,7 @@ patternProperties: description: Devices attached to chip selects are represented as subnodes. type: object - - properties: - intel,ixp4xx-eb-t1: - description: Address timing, extend address phase with n cycles. - $ref: /schemas/types.yaml#/definitions/uint32 - maximum: 3 - - intel,ixp4xx-eb-t2: - description: Setup chip select timing, extend setup phase with n cycles. - $ref: /schemas/types.yaml#/definitions/uint32 - maximum: 3 - - intel,ixp4xx-eb-t3: - description: Strobe timing, extend strobe phase with n cycles. - $ref: /schemas/types.yaml#/definitions/uint32 - maximum: 15 - - intel,ixp4xx-eb-t4: - description: Hold timing, extend hold phase with n cycles. - $ref: /schemas/types.yaml#/definitions/uint32 - maximum: 3 - - intel,ixp4xx-eb-t5: - description: Recovery timing, extend recovery phase with n cycles. - $ref: /schemas/types.yaml#/definitions/uint32 - maximum: 15 - - intel,ixp4xx-eb-cycle-type: - description: The type of cycles to use on the expansion bus for this - chip select. 0 = Intel cycles, 1 = Motorola cycles, 2 = HPI cycles. - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1, 2] - - intel,ixp4xx-eb-byte-access-on-halfword: - description: Allow byte read access on half word devices. - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1] - - intel,ixp4xx-eb-hpi-hrdy-pol-high: - description: Set HPI HRDY polarity to active high when using HPI. - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1] - - intel,ixp4xx-eb-mux-address-and-data: - description: Multiplex address and data on the data bus. - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1] - - intel,ixp4xx-eb-ahb-split-transfers: - description: Enable AHB split transfers. - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1] - - intel,ixp4xx-eb-write-enable: - description: Enable write cycles. - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1] - - intel,ixp4xx-eb-byte-access: - description: Expansion bus uses only 8 bits. The default is to use - 16 bits. - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1] + $ref: /schemas/memory-controllers/intel,ixp4xx-expansion-peripheral-props.yaml# required: - compatible diff --git a/Documentation/devicetree/bindings/memory-controllers/intel,ixp4xx-expansion-peripheral-props.yaml b/Documentation/devicetree/bindings/memory-controllers/intel,ixp4xx-expansion-peripheral-props.yaml new file mode 100644 index 000000000000..d1479a7b9c8d --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/intel,ixp4xx-expansion-peripheral-props.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/intel,ixp4xx-expansion-peripheral-props.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Peripheral properties for Intel IXP4xx Expansion Bus + +description: + The IXP4xx expansion bus controller handles access to devices on the + memory-mapped expansion bus on the Intel IXP4xx family of system on chips, + including IXP42x, IXP43x, IXP45x and IXP46x. + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +properties: + intel,ixp4xx-eb-t1: + description: Address timing, extend address phase with n cycles. + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 3 + + intel,ixp4xx-eb-t2: + description: Setup chip select timing, extend setup phase with n cycles. + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 3 + + intel,ixp4xx-eb-t3: + description: Strobe timing, extend strobe phase with n cycles. + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 15 + + intel,ixp4xx-eb-t4: + description: Hold timing, extend hold phase with n cycles. + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 3 + + intel,ixp4xx-eb-t5: + description: Recovery timing, extend recovery phase with n cycles. + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 15 + + intel,ixp4xx-eb-cycle-type: + description: The type of cycles to use on the expansion bus for this + chip select. 0 = Intel cycles, 1 = Motorola cycles, 2 = HPI cycles. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2] + + intel,ixp4xx-eb-byte-access-on-halfword: + description: Allow byte read access on half word devices. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + + intel,ixp4xx-eb-hpi-hrdy-pol-high: + description: Set HPI HRDY polarity to active high when using HPI. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + + intel,ixp4xx-eb-mux-address-and-data: + description: Multiplex address and data on the data bus. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + + intel,ixp4xx-eb-ahb-split-transfers: + description: Enable AHB split transfers. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + + intel,ixp4xx-eb-write-enable: + description: Enable write cycles. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + + intel,ixp4xx-eb-byte-access: + description: Expansion bus uses only 8 bits. The default is to use + 16 bits. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/memory-controllers/mc-peripheral-props.yaml b/Documentation/devicetree/bindings/memory-controllers/mc-peripheral-props.yaml index 53ae995462db..5acfcad12bb7 100644 --- a/Documentation/devicetree/bindings/memory-controllers/mc-peripheral-props.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/mc-peripheral-props.yaml @@ -34,5 +34,6 @@ required: # The controller specific properties go here. allOf: - $ref: st,stm32-fmc2-ebi-props.yaml# + - $ref: intel,ixp4xx-expansion-peripheral-props.yaml# additionalProperties: true diff --git a/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml b/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml index 4f30173ad747..bc9406929f6c 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml @@ -90,7 +90,7 @@ properties: interrupt-controller: description: | - The GPMC driver implements and interrupt controller for + The GPMC driver implements an interrupt controller for the NAND events "fifoevent" and "termcount" plus the rising/falling edges on the GPMC_WAIT pins. The interrupt number mapping is as follows diff --git a/Documentation/devicetree/bindings/memory-controllers/xlnx,zynqmp-ocmc-1.0.yaml b/Documentation/devicetree/bindings/memory-controllers/xlnx,zynqmp-ocmc-1.0.yaml new file mode 100644 index 000000000000..ca9fc747bf4f --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/xlnx,zynqmp-ocmc-1.0.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/xlnx,zynqmp-ocmc-1.0.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx Zynqmp OCM(On-Chip Memory) Controller + +maintainers: + - Shubhrajyoti Datta <shubhrajyoti.datta@amd.com> + - Sai Krishna Potthuri <sai.krishna.potthuri@amd.com> + +description: | + The OCM supports 64-bit wide ECC functionality to detect multi-bit errors + and recover from a single-bit memory fault.On a write, if all bytes are + being written, the ECC is generated and written into the ECC RAM along with + the write-data that is written into the data RAM. If one or more bytes are + not written, then the read operation results in an correctable error or + uncorrectable error. + +properties: + compatible: + const: xlnx,zynqmp-ocmc-1.0 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + memory-controller@ff960000 { + compatible = "xlnx,zynqmp-ocmc-1.0"; + reg = <0xff960000 0x1000>; + interrupts = <GIC_SPI 10 IRQ_TYPE_LEVEL_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml index 3d5efa5578d1..cdf1d719efe9 100644 --- a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml +++ b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml @@ -33,6 +33,9 @@ properties: - description: For implementations of the EC connected through RPMSG. const: google,cros-ec-rpmsg + - description: + For implementations of the EC connected through UART. + const: google,cros-ec-uart controller-data: true @@ -187,6 +190,15 @@ allOf: properties: mediatek,rpmsg-name: false + - if: + properties: + compatible: + not: + contains: + enum: + - google,cros-ec-rpmsg + - google,cros-ec-uart + then: required: - reg - interrupts @@ -299,4 +311,12 @@ examples: vdd-supply = <&pp3300_fp_mcu>; }; }; + + # Example for UART + - | + serial { + cros-ec { + compatible = "google,cros-ec-uart"; + }; + }; ... diff --git a/Documentation/devicetree/bindings/mfd/mscc,ocelot.yaml b/Documentation/devicetree/bindings/mfd/mscc,ocelot.yaml index 1d1fee1a16c1..8bd1abfc44d9 100644 --- a/Documentation/devicetree/bindings/mfd/mscc,ocelot.yaml +++ b/Documentation/devicetree/bindings/mfd/mscc,ocelot.yaml @@ -57,6 +57,15 @@ patternProperties: enum: - mscc,ocelot-miim + "^ethernet-switch@[0-9a-f]+$": + type: object + $ref: /schemas/net/mscc,vsc7514-switch.yaml + unevaluatedProperties: false + properties: + compatible: + enum: + - mscc,vsc7512-switch + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/mfd/nxp,bbnsm.yaml b/Documentation/devicetree/bindings/mfd/nxp,bbnsm.yaml new file mode 100644 index 000000000000..b1ade64a1554 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/nxp,bbnsm.yaml @@ -0,0 +1,101 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/nxp,bbnsm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP Battery-Backed Non-Secure Module + +maintainers: + - Jacky Bai <ping.bai@nxp.com> + +description: | + NXP BBNSM serves as non-volatile logic and storage for the system. + it Intergrates RTC & ON/OFF control. + The RTC can retain its state and continues counting even when the + main chip is power down. A time alarm is generated once the most + significant 32 bits of the real-time counter match the value in the + Time Alarm register. + The ON/OFF logic inside the BBNSM allows for connecting directly to + a PMIC or other voltage regulator device. both smart PMIC mode and + Dumb PMIC mode supported. + +properties: + compatible: + items: + - enum: + - nxp,imx93-bbnsm + - const: syscon + - const: simple-mfd + + reg: + maxItems: 1 + + rtc: + type: object + $ref: /schemas/rtc/rtc.yaml# + + properties: + compatible: + enum: + - nxp,imx93-bbnsm-rtc + + interrupts: + maxItems: 1 + + start-year: true + + required: + - compatible + - interrupts + + additionalProperties: false + + pwrkey: + type: object + $ref: /schemas/input/input.yaml# + + properties: + compatible: + enum: + - nxp,imx93-bbnsm-pwrkey + + interrupts: + maxItems: 1 + + linux,code: true + + required: + - compatible + - interrupts + + additionalProperties: false + +required: + - compatible + - reg + - rtc + - pwrkey + +additionalProperties: false + +examples: + - | + #include <dt-bindings/input/linux-event-codes.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + bbnsm: bbnsm@44440000 { + compatible = "nxp,imx93-bbnsm", "syscon", "simple-mfd"; + reg = <0x44440000 0x10000>; + + bbnsm_rtc: rtc { + compatible = "nxp,imx93-bbnsm-rtc"; + interrupts = <GIC_SPI 73 IRQ_TYPE_LEVEL_HIGH>; + }; + + bbnsm_pwrkey: pwrkey { + compatible = "nxp,imx93-bbnsm-pwrkey"; + interrupts = <GIC_SPI 73 IRQ_TYPE_LEVEL_HIGH>; + linux,code = <KEY_POWER>; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/omap-usb-host.txt b/Documentation/devicetree/bindings/mfd/omap-usb-host.txt index aa1eaa59581b..a0d8c30c2631 100644 --- a/Documentation/devicetree/bindings/mfd/omap-usb-host.txt +++ b/Documentation/devicetree/bindings/mfd/omap-usb-host.txt @@ -64,8 +64,8 @@ Required properties if child node exists: Properties for children: The OMAP HS USB Host subsystem contains EHCI and OHCI controllers. -See Documentation/devicetree/bindings/usb/ehci-omap.txt and -Documentation/devicetree/bindings/usb/ohci-omap3.txt. +See Documentation/devicetree/bindings/usb/generic-ehci.yaml and +Documentation/devicetree/bindings/usb/generic-ohci.yaml. Example for OMAP4: @@ -78,14 +78,14 @@ usbhshost: usbhshost@4a064000 { ranges; usbhsohci: ohci@4a064800 { - compatible = "ti,ohci-omap3", "usb-ohci"; + compatible = "ti,ohci-omap3"; reg = <0x4a064800 0x400>; interrupt-parent = <&gic>; interrupts = <0 76 0x4>; }; usbhsehci: ehci@4a064c00 { - compatible = "ti,ehci-omap", "usb-ehci"; + compatible = "ti,ehci-omap"; reg = <0x4a064c00 0x400>; interrupt-parent = <&gic>; interrupts = <0 77 0x4>; diff --git a/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml b/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml index 37d16e16f444..adf88245c409 100644 --- a/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml +++ b/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml @@ -44,6 +44,7 @@ properties: - qcom,pm8004 - qcom,pm8005 - qcom,pm8009 + - qcom,pm8010 - qcom,pm8019 - qcom,pm8028 - qcom,pm8110 @@ -55,6 +56,10 @@ properties: - qcom,pm8350 - qcom,pm8350b - qcom,pm8350c + - qcom,pm8550 + - qcom,pm8550b + - qcom,pm8550ve + - qcom,pm8550vs - qcom,pm8841 - qcom,pm8909 - qcom,pm8916 @@ -71,10 +76,12 @@ properties: - qcom,pmi8998 - qcom,pmk8002 - qcom,pmk8350 + - qcom,pmk8550 - qcom,pmm8155au - qcom,pmp8074 - qcom,pmr735a - qcom,pmr735b + - qcom,pmr735d - qcom,pms405 - qcom,pmx55 - qcom,pmx65 diff --git a/Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml b/Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml index adcae6c007d9..2eeebe920e6e 100644 --- a/Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml +++ b/Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml @@ -28,9 +28,11 @@ properties: - qcom,sm8150-tcsr - qcom,tcsr-apq8064 - qcom,tcsr-apq8084 + - qcom,tcsr-ipq5332 - qcom,tcsr-ipq6018 - qcom,tcsr-ipq8064 - qcom,tcsr-mdm9615 + - qcom,tcsr-msm8226 - qcom,tcsr-msm8660 - qcom,tcsr-msm8916 - qcom,tcsr-msm8953 diff --git a/Documentation/devicetree/bindings/mfd/syscon.yaml b/Documentation/devicetree/bindings/mfd/syscon.yaml index 1b01bd010431..c828c4f5e4a7 100644 --- a/Documentation/devicetree/bindings/mfd/syscon.yaml +++ b/Documentation/devicetree/bindings/mfd/syscon.yaml @@ -38,6 +38,7 @@ properties: - allwinner,sun8i-h3-system-controller - allwinner,sun8i-v3s-system-controller - allwinner,sun50i-a64-system-controller + - amd,pensando-elba-syscon - brcm,cru-clkset - freecom,fsg-cs2-system-controller - fsl,imx93-aonmix-ns-syscfg @@ -46,10 +47,12 @@ properties: - hisilicon,hi6220-sramctrl - hisilicon,pcie-sas-subctrl - hisilicon,peri-subctrl + - hpe,gxp-sysreg - intel,lgm-syscon - marvell,armada-3700-usb2-host-misc - mediatek,mt8135-pctl-a-syscfg - mediatek,mt8135-pctl-b-syscfg + - mediatek,mt8365-syscfg - microchip,lan966x-cpu-syscon - microchip,sparx5-cpu-syscon - mstar,msc313-pmsleep @@ -64,12 +67,6 @@ properties: - rockchip,rk3568-qos - rockchip,rk3588-qos - rockchip,rv1126-qos - - samsung,exynos3-sysreg - - samsung,exynos4-sysreg - - samsung,exynos5-sysreg - - samsung,exynos5433-sysreg - - samsung,exynos850-sysreg - - samsung,exynosautov9-sysreg - const: syscon @@ -87,6 +84,9 @@ properties: on the device. enum: [1, 2, 4, 8] + resets: + maxItems: 1 + hwlocks: maxItems: 1 description: diff --git a/Documentation/devicetree/bindings/misc/xlnx,tmr-inject.yaml b/Documentation/devicetree/bindings/misc/xlnx,tmr-inject.yaml new file mode 100644 index 000000000000..1b6020e4ec27 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/xlnx,tmr-inject.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/misc/xlnx,tmr-inject.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx Triple Modular Redundancy(TMR) Inject IP + +maintainers: + - Appana Durga Kedareswara rao <appana.durga.kedareswara.rao@amd.com> + +description: | + The Triple Modular Redundancy(TMR) Inject core provides functional fault + injection by changing selected MicroBlaze instructions, which provides the + possibility to verify that the TMR subsystem error detection and fault + recovery logic is working properly. + +properties: + compatible: + enum: + - xlnx,tmr-inject-1.0 + + reg: + maxItems: 1 + + xlnx,magic: + minimum: 0 + maximum: 255 + description: | + Magic number, When configured it allows the controller to perform + recovery. + $ref: /schemas/types.yaml#/definitions/uint32 + +required: + - compatible + - reg + - xlnx,magic + +additionalProperties: false + +examples: + - | + fault-inject@44a30000 { + compatible = "xlnx,tmr-inject-1.0"; + reg = <0x44a10000 0x10000>; + xlnx,magic = <0x46>; + }; diff --git a/Documentation/devicetree/bindings/misc/xlnx,tmr-manager.yaml b/Documentation/devicetree/bindings/misc/xlnx,tmr-manager.yaml new file mode 100644 index 000000000000..27de12147a52 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/xlnx,tmr-manager.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/misc/xlnx,tmr-manager.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx Triple Modular Redundancy(TMR) Manager IP + +maintainers: + - Appana Durga Kedareswara rao <appana.durga.kedareswara.rao@amd.com> + +description: | + The Triple Modular Redundancy(TMR) Manager is responsible for handling the + TMR subsystem state, including fault detection and error recovery. The core + is triplicated in each of the sub-blocks in the TMR subsystem, and provides + majority voting of its internal state. + +properties: + compatible: + enum: + - xlnx,tmr-manager-1.0 + + reg: + maxItems: 1 + + xlnx,magic1: + minimum: 0 + maximum: 255 + description: + Magic byte 1, When configured it allows the controller to perform + recovery. + $ref: /schemas/types.yaml#/definitions/uint32 + +required: + - compatible + - reg + - xlnx,magic1 + +additionalProperties: false + +examples: + - | + tmr-manager@44a10000 { + compatible = "xlnx,tmr-manager-1.0"; + reg = <0x44a10000 0x10000>; + xlnx,magic1 = <0x46>; + }; diff --git a/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.yaml b/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.yaml index fe0270207622..fda0b45ee577 100644 --- a/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.yaml +++ b/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.yaml @@ -82,8 +82,7 @@ properties: iommus: maxItems: 1 - operating-points-v2: - $ref: "/schemas/types.yaml#/definitions/phandle" + operating-points-v2: true power-domains: items: diff --git a/Documentation/devicetree/bindings/mmc/samsung,s3cmci.txt b/Documentation/devicetree/bindings/mmc/samsung,s3cmci.txt deleted file mode 100644 index 5f68feb9f9d6..000000000000 --- a/Documentation/devicetree/bindings/mmc/samsung,s3cmci.txt +++ /dev/null @@ -1,42 +0,0 @@ -* Samsung's S3C24XX MMC/SD/SDIO controller device tree bindings - -Samsung's S3C24XX MMC/SD/SDIO controller is used as a connectivity interface -with external MMC, SD and SDIO storage mediums. - -This file documents differences between the core mmc properties described by -mmc.txt and the properties used by the Samsung S3C24XX MMC/SD/SDIO controller -implementation. - -Required SoC Specific Properties: -- compatible: should be one of the following - - "samsung,s3c2410-sdi": for controllers compatible with s3c2410 - - "samsung,s3c2412-sdi": for controllers compatible with s3c2412 - - "samsung,s3c2440-sdi": for controllers compatible with s3c2440 -- reg: register location and length -- interrupts: mmc controller interrupt -- clocks: Should reference the controller clock -- clock-names: Should contain "sdi" - -Required Board Specific Properties: -- pinctrl-0: Should specify pin control groups used for this controller. -- pinctrl-names: Should contain only one value - "default". - -Optional Properties: -- bus-width: number of data lines (see mmc.txt) -- cd-gpios: gpio for card detection (see mmc.txt) -- wp-gpios: gpio for write protection (see mmc.txt) - -Example: - - mmc0: mmc@5a000000 { - compatible = "samsung,s3c2440-sdi"; - pinctrl-names = "default"; - pinctrl-0 = <&sdi_pins>; - reg = <0x5a000000 0x100000>; - interrupts = <0 0 21 3>; - clocks = <&clocks PCLK_SDI>; - clock-names = "sdi"; - bus-width = <4>; - cd-gpios = <&gpg 8 GPIO_ACTIVE_LOW>; - wp-gpios = <&gph 8 GPIO_ACTIVE_LOW>; - }; diff --git a/Documentation/devicetree/bindings/mtd/mtd-physmap.yaml b/Documentation/devicetree/bindings/mtd/mtd-physmap.yaml index 5df94953c34e..44cd4476d1d3 100644 --- a/Documentation/devicetree/bindings/mtd/mtd-physmap.yaml +++ b/Documentation/devicetree/bindings/mtd/mtd-physmap.yaml @@ -15,6 +15,7 @@ description: | allOf: - $ref: "mtd.yaml#" + - $ref: /schemas/memory-controllers/mc-peripheral-props.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml b/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml index 1432fda3b603..47bc2057e629 100644 --- a/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml +++ b/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml @@ -40,6 +40,9 @@ properties: clock-names: const: stmmaceth + phy-supply: + description: PHY regulator + syscon: $ref: /schemas/types.yaml#/definitions/phandle description: diff --git a/Documentation/devicetree/bindings/net/amlogic,g12a-mdio-mux.yaml b/Documentation/devicetree/bindings/net/amlogic,g12a-mdio-mux.yaml new file mode 100644 index 000000000000..ec5c038ce6a0 --- /dev/null +++ b/Documentation/devicetree/bindings/net/amlogic,g12a-mdio-mux.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/amlogic,g12a-mdio-mux.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MDIO bus multiplexer/glue of Amlogic G12a SoC family + +description: + This is a special case of a MDIO bus multiplexer. It allows to choose between + the internal mdio bus leading to the embedded 10/100 PHY or the external + MDIO bus. + +maintainers: + - Neil Armstrong <neil.armstrong@linaro.org> + +allOf: + - $ref: mdio-mux.yaml# + +properties: + compatible: + const: amlogic,g12a-mdio-mux + + reg: + maxItems: 1 + + clocks: + items: + - description: peripheral clock + - description: platform crytal + - description: SoC 50MHz MPLL + + clock-names: + items: + - const: pclk + - const: clkin0 + - const: clkin1 + +required: + - compatible + - reg + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + mdio-multiplexer@4c000 { + compatible = "amlogic,g12a-mdio-mux"; + reg = <0x4c000 0xa4>; + clocks = <&clkc_eth_phy>, <&xtal>, <&clkc_mpll>; + clock-names = "pclk", "clkin0", "clkin1"; + mdio-parent-bus = <&mdio0>; + #address-cells = <1>; + #size-cells = <0>; + + mdio@0 { + reg = <0>; + #address-cells = <1>; + #size-cells = <0>; + }; + + mdio@1 { + reg = <1>; + #address-cells = <1>; + #size-cells = <0>; + + ethernet-phy@8 { + compatible = "ethernet-phy-id0180.3301", + "ethernet-phy-ieee802.3-c22"; + interrupts = <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>; + reg = <8>; + max-speed = <100>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/net/amlogic,gxl-mdio-mux.yaml b/Documentation/devicetree/bindings/net/amlogic,gxl-mdio-mux.yaml new file mode 100644 index 000000000000..27ae004dbea0 --- /dev/null +++ b/Documentation/devicetree/bindings/net/amlogic,gxl-mdio-mux.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/amlogic,gxl-mdio-mux.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic GXL MDIO bus multiplexer + +maintainers: + - Jerome Brunet <jbrunet@baylibre.com> + +description: + This is a special case of a MDIO bus multiplexer. It allows to choose between + the internal mdio bus leading to the embedded 10/100 PHY or the external + MDIO bus on the Amlogic GXL SoC family. + +allOf: + - $ref: mdio-mux.yaml# + +properties: + compatible: + const: amlogic,gxl-mdio-mux + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: ref + +required: + - compatible + - reg + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + eth_phy_mux: mdio@558 { + compatible = "amlogic,gxl-mdio-mux"; + reg = <0x558 0xc>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&refclk>; + clock-names = "ref"; + mdio-parent-bus = <&mdio0>; + + external_mdio: mdio@0 { + reg = <0x0>; + #address-cells = <1>; + #size-cells = <0>; + }; + + internal_mdio: mdio@1 { + reg = <0x1>; + #address-cells = <1>; + #size-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/asix,ax88796c.yaml b/Documentation/devicetree/bindings/net/asix,ax88796c.yaml index 699ebf452479..164d1ff9e83c 100644 --- a/Documentation/devicetree/bindings/net/asix,ax88796c.yaml +++ b/Documentation/devicetree/bindings/net/asix,ax88796c.yaml @@ -19,6 +19,7 @@ description: | allOf: - $ref: ethernet-controller.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml properties: compatible: @@ -39,8 +40,8 @@ properties: it should be marked GPIO_ACTIVE_LOW. maxItems: 1 + controller-data: true local-mac-address: true - mac-address: true required: diff --git a/Documentation/devicetree/bindings/net/can/renesas,rcar-canfd.yaml b/Documentation/devicetree/bindings/net/can/renesas,rcar-canfd.yaml index 1eb98c9a1a26..d3f45d29fa0a 100644 --- a/Documentation/devicetree/bindings/net/can/renesas,rcar-canfd.yaml +++ b/Documentation/devicetree/bindings/net/can/renesas,rcar-canfd.yaml @@ -30,13 +30,17 @@ properties: - items: - enum: + - renesas,r8a779a0-canfd # R-Car V3U + - renesas,r8a779g0-canfd # R-Car V4H + - const: renesas,rcar-gen4-canfd # R-Car Gen4 + + - items: + - enum: - renesas,r9a07g043-canfd # RZ/G2UL and RZ/Five - renesas,r9a07g044-canfd # RZ/G2{L,LC} - renesas,r9a07g054-canfd # RZ/V2L - const: renesas,rzg2l-canfd # RZ/G2L family - - const: renesas,r8a779a0-canfd # R-Car V3U - reg: maxItems: 1 @@ -60,7 +64,7 @@ properties: $ref: /schemas/types.yaml#/definitions/flag description: The controller can operate in either CAN FD only mode (default) or - Classical CAN only mode. The mode is global to both the channels. + Classical CAN only mode. The mode is global to all channels. Specify this property to put the controller in Classical CAN only mode. assigned-clocks: @@ -80,6 +84,10 @@ patternProperties: The controller supports multiple channels and each is represented as a child node. Each channel can be enabled/disabled individually. + properties: + phys: + maxItems: 1 + additionalProperties: false required: @@ -159,7 +167,7 @@ allOf: properties: compatible: contains: - const: renesas,r8a779a0-canfd + const: renesas,rcar-gen4-canfd then: patternProperties: "^channel[2-7]$": false diff --git a/Documentation/devicetree/bindings/net/dsa/arrow,xrs700x.yaml b/Documentation/devicetree/bindings/net/dsa/arrow,xrs700x.yaml index 2a6d126606ca..9565a7402146 100644 --- a/Documentation/devicetree/bindings/net/dsa/arrow,xrs700x.yaml +++ b/Documentation/devicetree/bindings/net/dsa/arrow,xrs700x.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Arrow SpeedChips XRS7000 Series Switch allOf: - - $ref: dsa.yaml# + - $ref: dsa.yaml#/$defs/ethernet-ports maintainers: - George McCollister <george.mccollister@gmail.com> diff --git a/Documentation/devicetree/bindings/net/dsa/brcm,b53.yaml b/Documentation/devicetree/bindings/net/dsa/brcm,b53.yaml index 1219b830b1a4..5bef4128d175 100644 --- a/Documentation/devicetree/bindings/net/dsa/brcm,b53.yaml +++ b/Documentation/devicetree/bindings/net/dsa/brcm,b53.yaml @@ -66,7 +66,7 @@ required: - reg allOf: - - $ref: dsa.yaml# + - $ref: dsa.yaml#/$defs/ethernet-ports - if: properties: compatible: diff --git a/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml b/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml index d159ac78cec1..eed16e216fb6 100644 --- a/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml +++ b/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml @@ -85,11 +85,16 @@ properties: ports: type: object - properties: - brcm,use-bcm-hdr: - description: if present, indicates that the switch port has Broadcom - tags enabled (per-packet metadata) - type: boolean + patternProperties: + '^port@[0-9a-f]$': + $ref: dsa-port.yaml# + unevaluatedProperties: false + + properties: + brcm,use-bcm-hdr: + description: if present, indicates that the switch port has Broadcom + tags enabled (per-packet metadata) + type: boolean required: - reg diff --git a/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml b/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml index b173fceb8998..480120469953 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml +++ b/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml @@ -4,18 +4,19 @@ $id: http://devicetree.org/schemas/net/dsa/dsa-port.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Ethernet Switch port +title: Generic DSA Switch Port maintainers: - Andrew Lunn <andrew@lunn.ch> - Florian Fainelli <f.fainelli@gmail.com> - - Vivien Didelot <vivien.didelot@gmail.com> + - Vladimir Oltean <olteanv@gmail.com> description: - Ethernet switch port Description + A DSA switch port is a component of a switch that manages one MAC, and can + pass Ethernet frames. It can act as a stanadard Ethernet switch port, or have + DSA-specific functionality. -allOf: - - $ref: /schemas/net/ethernet-controller.yaml# +$ref: /schemas/net/ethernet-switch-port.yaml# properties: reg: @@ -58,25 +59,6 @@ properties: - rtl8_4t - seville - phy-handle: true - - phy-mode: true - - fixed-link: true - - mac-address: true - - sfp: true - - managed: true - - rx-internal-delay-ps: true - - tx-internal-delay-ps: true - -required: - - reg - # CPU and DSA ports must have phylink-compatible link descriptions if: oneOf: diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.yaml b/Documentation/devicetree/bindings/net/dsa/dsa.yaml index 5469ae8a4389..8d971813bab6 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa.yaml +++ b/Documentation/devicetree/bindings/net/dsa/dsa.yaml @@ -9,7 +9,7 @@ title: Ethernet Switch maintainers: - Andrew Lunn <andrew@lunn.ch> - Florian Fainelli <f.fainelli@gmail.com> - - Vivien Didelot <vivien.didelot@gmail.com> + - Vladimir Oltean <olteanv@gmail.com> description: This binding represents Ethernet Switches which have a dedicated CPU @@ -18,10 +18,9 @@ description: select: false -properties: - $nodename: - pattern: "^(ethernet-)?switch(@.*)?$" +$ref: /schemas/net/ethernet-switch.yaml# +properties: dsa,member: minItems: 2 maxItems: 2 @@ -32,30 +31,28 @@ properties: (single device hanging off a CPU port) must not specify this property $ref: /schemas/types.yaml#/definitions/uint32-array -patternProperties: - "^(ethernet-)?ports$": - type: object - properties: - '#address-cells': - const: 1 - '#size-cells': - const: 0 +additionalProperties: true + +$defs: + ethernet-ports: + description: A DSA switch without any extra port properties + $ref: '#/' patternProperties: - "^(ethernet-)?port@[0-9]+$": + "^(ethernet-)?ports$": type: object - description: Ethernet switch ports - - $ref: dsa-port.yaml# - - unevaluatedProperties: false - -oneOf: - - required: - - ports - - required: - - ethernet-ports - -additionalProperties: true + additionalProperties: false + + properties: + '#address-cells': + const: 1 + '#size-cells': + const: 0 + + patternProperties: + "^(ethernet-)?port@[0-9]+$": + description: Ethernet switch ports + $ref: dsa-port.yaml# + unevaluatedProperties: false ... diff --git a/Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml b/Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml index 447589b01e8e..4021b054f684 100644 --- a/Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml +++ b/Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Hirschmann Hellcreek TSN Switch allOf: - - $ref: dsa.yaml# + - $ref: dsa.yaml#/$defs/ethernet-ports maintainers: - Andrew Lunn <andrew@lunn.ch> diff --git a/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml b/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml index f2e9ff3f580b..449ee0735012 100644 --- a/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml +++ b/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml @@ -24,56 +24,46 @@ description: | There is only the standalone version of MT7531. - Port 5 on MT7530 has got various ways of configuration. - - For standalone MT7530: + Port 5 on MT7530 has got various ways of configuration: - Port 5 can be used as a CPU port. - - PHY 0 or 4 of the switch can be muxed to connect to the gmac of the SoC - which port 5 is wired to. Usually used for connecting the wan port - directly to the CPU to achieve 2 Gbps routing in total. + - PHY 0 or 4 of the switch can be muxed to gmac5 of the switch. Therefore, + the gmac of the SoC which is wired to port 5 can connect to the PHY. + This is usually used for connecting the wan port directly to the CPU to + achieve 2 Gbps routing in total. - The driver looks up the reg on the ethernet-phy node which the phy-handle - property refers to on the gmac node to mux the specified phy. + The driver looks up the reg on the ethernet-phy node, which the phy-handle + property on the gmac node refers to, to mux the specified phy. The driver requires the gmac of the SoC to have "mediatek,eth-mac" as the - compatible string and the reg must be 1. So, for now, only gmac1 of an + compatible string and the reg must be 1. So, for now, only gmac1 of a MediaTek SoC can benefit this. Banana Pi BPI-R2 suits this. - Check out example 5 for a similar configuration. - - - Port 5 can be wired to an external phy. Port 5 becomes a DSA slave. - Check out example 7 for a similar configuration. - - For multi-chip module MT7530: - - - Port 5 can be used as a CPU port. - - - PHY 0 or 4 of the switch can be muxed to connect to gmac1 of the SoC. - Usually used for connecting the wan port directly to the CPU to achieve 2 - Gbps routing in total. - - The driver looks up the reg on the ethernet-phy node which the phy-handle - property refers to on the gmac node to mux the specified phy. For the MT7621 SoCs, rgmii2 group must be claimed with rgmii2 function. + Check out example 5. - - In case of an external phy wired to gmac1 of the SoC, port 5 must not be - enabled. + - For the multi-chip module MT7530, in case of an external phy wired to + gmac1 of the SoC, port 5 must not be enabled. In case of muxing PHY 0 or 4, the external phy must not be enabled. For the MT7621 SoCs, rgmii2 group must be claimed with rgmii2 function. + Check out example 6. - - Port 5 can be muxed to an external phy. Port 5 becomes a DSA slave. - The external phy must be wired TX to TX to gmac1 of the SoC for this to - work. Ubiquiti EdgeRouter X SFP is wired this way. + - Port 5 can be wired to an external phy. Port 5 becomes a DSA slave. - Muxing PHY 0 or 4 won't work when the external phy is connected TX to TX. + 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 + this way. + + For the multi-chip module MT7530, muxing PHY 0 or 4 won't work when the + external phy is connected TX to TX. For the MT7621 SoCs, rgmii2 group must be claimed with gpio function. + Check out example 7. properties: @@ -157,9 +147,6 @@ patternProperties: patternProperties: "^(ethernet-)?port@[0-9]+$": type: object - description: Ethernet switch ports - - unevaluatedProperties: false properties: reg: @@ -168,7 +155,6 @@ patternProperties: for user ports. allOf: - - $ref: dsa-port.yaml# - if: required: [ ethernet ] then: @@ -238,7 +224,7 @@ $defs: - sgmii allOf: - - $ref: dsa.yaml# + - $ref: dsa.yaml#/$defs/ethernet-ports - if: required: - mediatek,mcm @@ -605,7 +591,7 @@ examples: label = "lan4"; }; - /* Commented out, phy4 is muxed to gmac1. + /* Commented out, phy4 is connected to gmac1. port@4 { reg = <4>; label = "wan"; diff --git a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml index 4da75b1f9533..a4b53434c85c 100644 --- a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml +++ b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml @@ -11,7 +11,7 @@ maintainers: - Woojung Huh <Woojung.Huh@microchip.com> allOf: - - $ref: dsa.yaml# + - $ref: dsa.yaml#/$defs/ethernet-ports - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: diff --git a/Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml b/Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml index b34de303966b..8d7e878b84dc 100644 --- a/Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml +++ b/Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml @@ -10,7 +10,7 @@ maintainers: - UNGLinuxDriver@microchip.com allOf: - - $ref: dsa.yaml# + - $ref: dsa.yaml#/$defs/ethernet-ports properties: compatible: diff --git a/Documentation/devicetree/bindings/net/dsa/mscc,ocelot.yaml b/Documentation/devicetree/bindings/net/dsa/mscc,ocelot.yaml index 347a0e1b3d3f..fe02d05196e4 100644 --- a/Documentation/devicetree/bindings/net/dsa/mscc,ocelot.yaml +++ b/Documentation/devicetree/bindings/net/dsa/mscc,ocelot.yaml @@ -78,7 +78,7 @@ required: - reg allOf: - - $ref: dsa.yaml# + - $ref: dsa.yaml#/$defs/ethernet-ports - if: properties: compatible: diff --git a/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml b/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml index df98a16e4e75..9a64ed658745 100644 --- a/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml +++ b/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml @@ -13,7 +13,7 @@ description: depends on the SPI bus master driver. allOf: - - $ref: "dsa.yaml#" + - $ref: dsa.yaml#/$defs/ethernet-ports - $ref: /schemas/spi/spi-peripheral-props.yaml# maintainers: diff --git a/Documentation/devicetree/bindings/net/dsa/qca8k.yaml b/Documentation/devicetree/bindings/net/dsa/qca8k.yaml index 978162df51f7..389892592aac 100644 --- a/Documentation/devicetree/bindings/net/dsa/qca8k.yaml +++ b/Documentation/devicetree/bindings/net/dsa/qca8k.yaml @@ -66,15 +66,11 @@ properties: With the legacy mapping the reg corresponding to the internal mdio is the switch reg with an offset of -1. +$ref: "dsa.yaml#" + patternProperties: "^(ethernet-)?ports$": type: object - properties: - '#address-cells': - const: 1 - '#size-cells': - const: 0 - patternProperties: "^(ethernet-)?port@[0-6]$": type: object @@ -116,7 +112,7 @@ required: - compatible - reg -additionalProperties: true +unevaluatedProperties: false examples: - | @@ -148,8 +144,6 @@ examples: switch@10 { compatible = "qca,qca8337"; - #address-cells = <1>; - #size-cells = <0>; reset-gpios = <&gpio 42 GPIO_ACTIVE_LOW>; reg = <0x10>; @@ -209,8 +203,6 @@ examples: switch@10 { compatible = "qca,qca8337"; - #address-cells = <1>; - #size-cells = <0>; reset-gpios = <&gpio 42 GPIO_ACTIVE_LOW>; reg = <0x10>; diff --git a/Documentation/devicetree/bindings/net/dsa/realtek.yaml b/Documentation/devicetree/bindings/net/dsa/realtek.yaml index 1a7d45a8ad66..cfd69c2604ea 100644 --- a/Documentation/devicetree/bindings/net/dsa/realtek.yaml +++ b/Documentation/devicetree/bindings/net/dsa/realtek.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Realtek switches for unmanaged switches allOf: - - $ref: dsa.yaml# + - $ref: dsa.yaml#/$defs/ethernet-ports maintainers: - Linus Walleij <linus.walleij@linaro.org> diff --git a/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml b/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml index 0a0d62b6c00e..833d2f68daa1 100644 --- a/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml +++ b/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml @@ -14,7 +14,7 @@ description: | handles 4 ports + 1 CPU management port. allOf: - - $ref: dsa.yaml# + - $ref: dsa.yaml#/$defs/ethernet-ports properties: compatible: diff --git a/Documentation/devicetree/bindings/net/ethernet-switch-port.yaml b/Documentation/devicetree/bindings/net/ethernet-switch-port.yaml new file mode 100644 index 000000000000..d5cf7e40e3c3 --- /dev/null +++ b/Documentation/devicetree/bindings/net/ethernet-switch-port.yaml @@ -0,0 +1,26 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/ethernet-switch-port.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic Ethernet Switch Port + +maintainers: + - Andrew Lunn <andrew@lunn.ch> + - Florian Fainelli <f.fainelli@gmail.com> + - Vladimir Oltean <olteanv@gmail.com> + +description: + An Ethernet switch port is a component of a switch that manages one MAC, and + can pass Ethernet frames. + +$ref: ethernet-controller.yaml# + +properties: + reg: + description: Port number + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/net/ethernet-switch.yaml b/Documentation/devicetree/bindings/net/ethernet-switch.yaml new file mode 100644 index 000000000000..a04f8ef744aa --- /dev/null +++ b/Documentation/devicetree/bindings/net/ethernet-switch.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/ethernet-switch.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic Ethernet Switch + +maintainers: + - Andrew Lunn <andrew@lunn.ch> + - Florian Fainelli <f.fainelli@gmail.com> + - Vladimir Oltean <olteanv@gmail.com> + +description: + Ethernet switches are multi-port Ethernet controllers. Each port has + its own number and is represented as its own Ethernet controller. + The minimum required functionality is to pass packets to software. + They may or may not be able to forward packets automonously between + ports. + +select: false + +properties: + $nodename: + pattern: "^(ethernet-)?switch(@.*)?$" + +patternProperties: + "^(ethernet-)?ports$": + type: object + unevaluatedProperties: false + + properties: + '#address-cells': + const: 1 + '#size-cells': + const: 0 + + patternProperties: + "^(ethernet-)?port@[0-9]+$": + type: object + description: Ethernet switch ports + +oneOf: + - required: + - ports + - required: + - ethernet-ports + +additionalProperties: true + +$defs: + base: + 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 + +... diff --git a/Documentation/devicetree/bindings/net/fsl,fec.yaml b/Documentation/devicetree/bindings/net/fsl,fec.yaml index 77e5f32cb62f..e6f2045f05de 100644 --- a/Documentation/devicetree/bindings/net/fsl,fec.yaml +++ b/Documentation/devicetree/bindings/net/fsl,fec.yaml @@ -51,6 +51,7 @@ properties: - fsl,imx8mm-fec - fsl,imx8mn-fec - fsl,imx8mp-fec + - fsl,imx93-fec - const: fsl,imx8mq-fec - const: fsl,imx6sx-fec - items: diff --git a/Documentation/devicetree/bindings/net/marvell,orion-mdio.yaml b/Documentation/devicetree/bindings/net/marvell,orion-mdio.yaml index d2906b4a0f59..e35da8b01dc2 100644 --- a/Documentation/devicetree/bindings/net/marvell,orion-mdio.yaml +++ b/Documentation/devicetree/bindings/net/marvell,orion-mdio.yaml @@ -16,9 +16,6 @@ description: | 8k has a second unit which provides an interface with the xMDIO bus. This driver handles these interfaces. -allOf: - - $ref: "mdio.yaml#" - properties: compatible: enum: @@ -39,13 +36,38 @@ required: - compatible - reg +allOf: + - $ref: mdio.yaml# + + - if: + required: + - interrupts + + then: + properties: + reg: + items: + - items: + - $ref: /schemas/types.yaml#/definitions/cell + - const: 0x84 + + else: + properties: + reg: + items: + - items: + - $ref: /schemas/types.yaml#/definitions/cell + - enum: + - 0x4 + - 0x10 + unevaluatedProperties: false examples: - | mdio@d0072004 { compatible = "marvell,orion-mdio"; - reg = <0xd0072004 0x4>; + reg = <0xd0072004 0x84>; #address-cells = <1>; #size-cells = <0>; interrupts = <30>; diff --git a/Documentation/devicetree/bindings/net/maxlinear,gpy2xx.yaml b/Documentation/devicetree/bindings/net/maxlinear,gpy2xx.yaml new file mode 100644 index 000000000000..d71fa9de2b64 --- /dev/null +++ b/Documentation/devicetree/bindings/net/maxlinear,gpy2xx.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/maxlinear,gpy2xx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MaxLinear GPY2xx PHY + +maintainers: + - Andrew Lunn <andrew@lunn.ch> + - Michael Walle <michael@walle.cc> + +allOf: + - $ref: ethernet-phy.yaml# + +properties: + maxlinear,use-broken-interrupts: + description: | + Interrupts are broken on some GPY2xx PHYs in that they keep the + interrupt line asserted even after the interrupt status register is + cleared. Thus it is blocking the interrupt line which is usually bad + for shared lines. By default interrupts are disabled for this PHY and + polling mode is used. If one can live with the consequences, this + property can be used to enable interrupt handling. + + Affected PHYs (as far as known) are GPY215B and GPY215C. + type: boolean + +dependencies: + maxlinear,use-broken-interrupts: [ interrupts ] + +unevaluatedProperties: false + +examples: + - | + ethernet { + #address-cells = <1>; + #size-cells = <0>; + + ethernet-phy@0 { + reg = <0>; + interrupts-extended = <&intc 0>; + maxlinear,use-broken-interrupts; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/net/mdio-mux-meson-g12a.txt b/Documentation/devicetree/bindings/net/mdio-mux-meson-g12a.txt deleted file mode 100644 index 3a96cbed9294..000000000000 --- a/Documentation/devicetree/bindings/net/mdio-mux-meson-g12a.txt +++ /dev/null @@ -1,48 +0,0 @@ -Properties for the MDIO bus multiplexer/glue of Amlogic G12a SoC family. - -This is a special case of a MDIO bus multiplexer. It allows to choose between -the internal mdio bus leading to the embedded 10/100 PHY or the external -MDIO bus. - -Required properties in addition to the generic multiplexer properties: -- compatible : amlogic,g12a-mdio-mux -- reg: physical address and length of the multiplexer/glue registers -- clocks: list of clock phandle, one for each entry clock-names. -- clock-names: should contain the following: - * "pclk" : peripheral clock. - * "clkin0" : platform crytal - * "clkin1" : SoC 50MHz MPLL - -Example : - -mdio_mux: mdio-multiplexer@4c000 { - compatible = "amlogic,g12a-mdio-mux"; - reg = <0x0 0x4c000 0x0 0xa4>; - clocks = <&clkc CLKID_ETH_PHY>, - <&xtal>, - <&clkc CLKID_MPLL_5OM>; - clock-names = "pclk", "clkin0", "clkin1"; - mdio-parent-bus = <&mdio0>; - #address-cells = <1>; - #size-cells = <0>; - - ext_mdio: mdio@0 { - reg = <0>; - #address-cells = <1>; - #size-cells = <0>; - }; - - int_mdio: mdio@1 { - reg = <1>; - #address-cells = <1>; - #size-cells = <0>; - - internal_ephy: ethernet-phy@8 { - compatible = "ethernet-phy-id0180.3301", - "ethernet-phy-ieee802.3-c22"; - interrupts = <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>; - reg = <8>; - max-speed = <100>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt b/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt index df9e844dd6bc..2681168777a1 100644 --- a/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt +++ b/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt @@ -158,6 +158,7 @@ KSZ9031: no link will be established. KSZ9131: +LAN8841: All skew control options are specified in picoseconds. The increment step is 100ps. Unlike KSZ9031, the values represent picoseccond delays. diff --git a/Documentation/devicetree/bindings/net/motorcomm,yt8xxx.yaml b/Documentation/devicetree/bindings/net/motorcomm,yt8xxx.yaml new file mode 100644 index 000000000000..157e3bbcaf6f --- /dev/null +++ b/Documentation/devicetree/bindings/net/motorcomm,yt8xxx.yaml @@ -0,0 +1,117 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/motorcomm,yt8xxx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MotorComm yt8xxx Ethernet PHY + +maintainers: + - Frank Sae <frank.sae@motor-comm.com> + +allOf: + - $ref: ethernet-phy.yaml# + +properties: + compatible: + enum: + - ethernet-phy-id4f51.e91a + - ethernet-phy-id4f51.e91b + + rx-internal-delay-ps: + description: | + RGMII RX Clock Delay used only when PHY operates in RGMII mode with + internal delay (phy-mode is 'rgmii-id' or 'rgmii-rxid') in pico-seconds. + enum: [ 0, 150, 300, 450, 600, 750, 900, 1050, 1200, 1350, 1500, 1650, + 1800, 1900, 1950, 2050, 2100, 2200, 2250, 2350, 2500, 2650, 2800, + 2950, 3100, 3250, 3400, 3550, 3700, 3850, 4000, 4150 ] + default: 1950 + + tx-internal-delay-ps: + description: | + RGMII TX Clock Delay used only when PHY operates in RGMII mode with + internal delay (phy-mode is 'rgmii-id' or 'rgmii-txid') in pico-seconds. + enum: [ 0, 150, 300, 450, 600, 750, 900, 1050, 1200, 1350, 1500, 1650, 1800, + 1950, 2100, 2250 ] + default: 1950 + + motorcomm,clk-out-frequency-hz: + description: clock output on clock output pin. + enum: [0, 25000000, 125000000] + default: 0 + + motorcomm,keep-pll-enabled: + description: | + If set, keep the PLL enabled even if there is no link. Useful if you + want to use the clock output without an ethernet link. + type: boolean + + motorcomm,auto-sleep-disabled: + description: | + If set, PHY will not enter sleep mode and close AFE after unplug cable + for a timer. + type: boolean + + motorcomm,tx-clk-adj-enabled: + description: | + This configuration is mainly to adapt to VF2 with JH7110 SoC. + Useful if you want to use tx-clk-xxxx-inverted to adj the delay of tx clk. + type: boolean + + motorcomm,tx-clk-10-inverted: + description: | + Use original or inverted RGMII Transmit PHY Clock to drive the RGMII + Transmit PHY Clock delay train configuration when speed is 10Mbps. + type: boolean + + motorcomm,tx-clk-100-inverted: + description: | + Use original or inverted RGMII Transmit PHY Clock to drive the RGMII + Transmit PHY Clock delay train configuration when speed is 100Mbps. + type: boolean + + motorcomm,tx-clk-1000-inverted: + description: | + Use original or inverted RGMII Transmit PHY Clock to drive the RGMII + Transmit PHY Clock delay train configuration when speed is 1000Mbps. + type: boolean + +unevaluatedProperties: false + +examples: + - | + mdio { + #address-cells = <1>; + #size-cells = <0>; + phy-mode = "rgmii-id"; + ethernet-phy@4 { + /* Only needed to make DT lint tools work. Do not copy/paste + * into real DTS files. + */ + compatible = "ethernet-phy-id4f51.e91a"; + + reg = <4>; + rx-internal-delay-ps = <2100>; + tx-internal-delay-ps = <150>; + motorcomm,clk-out-frequency-hz = <0>; + motorcomm,keep-pll-enabled; + motorcomm,auto-sleep-disabled; + }; + }; + - | + mdio { + #address-cells = <1>; + #size-cells = <0>; + phy-mode = "rgmii"; + ethernet-phy@5 { + /* Only needed to make DT lint tools work. Do not copy/paste + * into real DTS files. + */ + compatible = "ethernet-phy-id4f51.e91a"; + + reg = <5>; + motorcomm,clk-out-frequency-hz = <125000000>; + motorcomm,keep-pll-enabled; + motorcomm,auto-sleep-disabled; + }; + }; diff --git a/Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml b/Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml index ee0a504bdb24..8ee2c7d7ff42 100644 --- a/Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml +++ b/Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml @@ -18,14 +18,52 @@ description: | packets using CPU. Additionally, PTP is supported as well as FDMA for faster packet extraction/injection. -properties: - $nodename: - pattern: "^switch@[0-9a-f]+$" +allOf: + - if: + properties: + compatible: + const: mscc,vsc7514-switch + then: + $ref: ethernet-switch.yaml# + required: + - interrupts + - interrupt-names + properties: + reg: + 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# + 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: - const: mscc,vsc7514-switch + enum: + - mscc,vsc7512-switch + - mscc,vsc7514-switch reg: + minItems: 20 items: - description: system target - description: rewriter target @@ -50,6 +88,7 @@ properties: - description: fdma target reg-names: + minItems: 20 items: - const: sys - const: rew @@ -87,59 +126,16 @@ properties: - const: xtr - const: fdma - ethernet-ports: - type: object - - properties: - '#address-cells': - const: 1 - '#size-cells': - const: 0 - - additionalProperties: false - - patternProperties: - "^port@[0-9a-f]+$": - type: object - description: Ethernet ports handled by the switch - - $ref: ethernet-controller.yaml# - - unevaluatedProperties: false - - properties: - reg: - description: Switch port number - - phy-handle: true - - phy-mode: true - - fixed-link: true - - mac-address: true - - required: - - reg - - phy-mode - - oneOf: - - required: - - phy-handle - - required: - - fixed-link - required: - compatible - reg - reg-names - - interrupts - - interrupt-names - ethernet-ports -additionalProperties: false +unevaluatedProperties: false examples: + # VSC7514 (Switchdev) - | switch@1010000 { compatible = "mscc,vsc7514-switch"; @@ -187,5 +183,51 @@ examples: }; }; }; + # VSC7512 (DSA) + - | + ethernet-switch@1{ + compatible = "mscc,vsc7512-switch"; + reg = <0x71010000 0x10000>, + <0x71030000 0x10000>, + <0x71080000 0x100>, + <0x710e0000 0x10000>, + <0x711e0000 0x100>, + <0x711f0000 0x100>, + <0x71200000 0x100>, + <0x71210000 0x100>, + <0x71220000 0x100>, + <0x71230000 0x100>, + <0x71240000 0x100>, + <0x71250000 0x100>, + <0x71260000 0x100>, + <0x71270000 0x100>, + <0x71280000 0x100>, + <0x71800000 0x80000>, + <0x71880000 0x10000>, + <0x71040000 0x10000>, + <0x71050000 0x10000>, + <0x71060000 0x10000>; + reg-names = "sys", "rew", "qs", "ptp", "port0", "port1", + "port2", "port3", "port4", "port5", "port6", + "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"; + }; + }; + }; ... diff --git a/Documentation/devicetree/bindings/net/nxp,dwmac-imx.yaml b/Documentation/devicetree/bindings/net/nxp,dwmac-imx.yaml index 04df496af7e6..63409cbff5ad 100644 --- a/Documentation/devicetree/bindings/net/nxp,dwmac-imx.yaml +++ b/Documentation/devicetree/bindings/net/nxp,dwmac-imx.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/net/nxp,dwmac-imx.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: NXP i.MX8 DWMAC glue layer +title: NXP i.MX8/9 DWMAC glue layer maintainers: - Clark Wang <xiaoning.wang@nxp.com> @@ -19,6 +19,7 @@ select: enum: - nxp,imx8mp-dwmac-eqos - nxp,imx8dxl-dwmac-eqos + - nxp,imx93-dwmac-eqos required: - compatible @@ -32,6 +33,7 @@ properties: - enum: - nxp,imx8mp-dwmac-eqos - nxp,imx8dxl-dwmac-eqos + - nxp,imx93-dwmac-eqos - const: snps,dwmac-5.10a clocks: diff --git a/Documentation/devicetree/bindings/net/rfkill-gpio.yaml b/Documentation/devicetree/bindings/net/rfkill-gpio.yaml new file mode 100644 index 000000000000..9630c8466fac --- /dev/null +++ b/Documentation/devicetree/bindings/net/rfkill-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/net/rfkill-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: GPIO controlled rfkill switch + +maintainers: + - Johannes Berg <johannes@sipsolutions.net> + - Philipp Zabel <p.zabel@pengutronix.de> + +properties: + compatible: + const: rfkill-gpio + + label: + description: rfkill switch name, defaults to node name + + radio-type: + description: rfkill radio type + enum: + - bluetooth + - fm + - gps + - nfc + - ultrawideband + - wimax + - wlan + - wwan + + shutdown-gpios: + maxItems: 1 + +required: + - compatible + - radio-type + - shutdown-gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + rfkill { + compatible = "rfkill-gpio"; + label = "rfkill-pcie-wlan"; + radio-type = "wlan"; + shutdown-gpios = <&gpio2 25 GPIO_ACTIVE_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/net/rockchip-dwmac.yaml b/Documentation/devicetree/bindings/net/rockchip-dwmac.yaml index 42fb72b6909d..04936632fcbb 100644 --- a/Documentation/devicetree/bindings/net/rockchip-dwmac.yaml +++ b/Documentation/devicetree/bindings/net/rockchip-dwmac.yaml @@ -49,11 +49,11 @@ properties: - rockchip,rk3368-gmac - rockchip,rk3399-gmac - rockchip,rv1108-gmac - - rockchip,rv1126-gmac - items: - enum: - rockchip,rk3568-gmac - rockchip,rk3588-gmac + - rockchip,rv1126-gmac - const: snps,dwmac-4.20a clocks: diff --git a/Documentation/devicetree/bindings/net/snps,dwmac.yaml b/Documentation/devicetree/bindings/net/snps,dwmac.yaml index e88a86623fce..16b7d2904696 100644 --- a/Documentation/devicetree/bindings/net/snps,dwmac.yaml +++ b/Documentation/devicetree/bindings/net/snps,dwmac.yaml @@ -552,7 +552,7 @@ required: dependencies: snps,reset-active-low: ["snps,reset-gpio"] - snps,reset-delay-us: ["snps,reset-gpio"] + snps,reset-delays-us: ["snps,reset-gpio"] allOf: - $ref: "ethernet-controller.yaml#" diff --git a/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml b/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml index 821974815dec..900063411a20 100644 --- a/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml +++ b/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml @@ -57,6 +57,7 @@ properties: - ti,am654-cpsw-nuss - ti,j7200-cpswxg-nuss - ti,j721e-cpsw-nuss + - ti,j721e-cpswxg-nuss - ti,am642-cpsw-nuss reg: @@ -111,7 +112,7 @@ properties: const: 0 patternProperties: - "^port@[1-4]$": + "^port@[1-8]$": type: object description: CPSWxG NUSS external ports @@ -121,7 +122,7 @@ properties: properties: reg: minimum: 1 - maximum: 4 + maximum: 8 description: CPSW port number phys: @@ -186,12 +187,36 @@ allOf: properties: compatible: contains: - const: ti,j7200-cpswxg-nuss + const: ti,j721e-cpswxg-nuss then: properties: ethernet-ports: patternProperties: - "^port@[3-4]$": false + "^port@[5-8]$": false + "^port@[1-4]$": + properties: + reg: + minimum: 1 + maximum: 4 + + - if: + not: + properties: + compatible: + contains: + enum: + - ti,j721e-cpswxg-nuss + - ti,j7200-cpswxg-nuss + then: + properties: + ethernet-ports: + patternProperties: + "^port@[3-8]$": false + "^port@[1-2]$": + properties: + reg: + minimum: 1 + maximum: 2 additionalProperties: false diff --git a/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml b/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml index 6230f576134b..3e910d3b24a0 100644 --- a/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml +++ b/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml @@ -93,6 +93,14 @@ properties: description: Number of timestamp Generator function outputs (TS_GENFx) + ti,pps: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 2 + maxItems: 2 + description: | + The pair of HWx_TS_PUSH input and TS_GENFy output indexes used for + PPS events generation. Platform/board specific. + refclk-mux: type: object additionalProperties: false diff --git a/Documentation/devicetree/bindings/net/wireless/esp,esp8089.yaml b/Documentation/devicetree/bindings/net/wireless/esp,esp8089.yaml index 5557676e9d4b..0ea84d6fe73e 100644 --- a/Documentation/devicetree/bindings/net/wireless/esp,esp8089.yaml +++ b/Documentation/devicetree/bindings/net/wireless/esp,esp8089.yaml @@ -29,15 +29,15 @@ additionalProperties: false examples: - | - mmc { - #address-cells = <1>; - #size-cells = <0>; - - wifi@1 { - compatible = "esp,esp8089"; - reg = <1>; - esp,crystal-26M-en = <2>; - }; - }; + mmc { + #address-cells = <1>; + #size-cells = <0>; + + wifi@1 { + compatible = "esp,esp8089"; + reg = <1>; + esp,crystal-26M-en = <2>; + }; + }; ... diff --git a/Documentation/devicetree/bindings/net/wireless/ieee80211.yaml b/Documentation/devicetree/bindings/net/wireless/ieee80211.yaml index e68ed9423150..d89f7a3f88a7 100644 --- a/Documentation/devicetree/bindings/net/wireless/ieee80211.yaml +++ b/Documentation/devicetree/bindings/net/wireless/ieee80211.yaml @@ -1,6 +1,5 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) # Copyright (c) 2018-2019 The Linux Foundation. All rights reserved. - %YAML 1.2 --- $id: http://devicetree.org/schemas/net/wireless/ieee80211.yaml# diff --git a/Documentation/devicetree/bindings/net/wireless/marvell-8xxx.txt b/Documentation/devicetree/bindings/net/wireless/marvell-8xxx.txt index 9bf9bbac16e2..cdc303caf5f4 100644 --- a/Documentation/devicetree/bindings/net/wireless/marvell-8xxx.txt +++ b/Documentation/devicetree/bindings/net/wireless/marvell-8xxx.txt @@ -1,4 +1,4 @@ -Marvell 8787/8897/8997 (sd8787/sd8897/sd8997/pcie8997) SDIO/PCIE devices +Marvell 8787/8897/8978/8997 (sd8787/sd8897/sd8978/sd8997/pcie8997) SDIO/PCIE devices ------ This node provides properties for controlling the Marvell SDIO/PCIE wireless device. @@ -10,7 +10,9 @@ Required properties: - compatible : should be one of the following: * "marvell,sd8787" * "marvell,sd8897" + * "marvell,sd8978" * "marvell,sd8997" + * "nxp,iw416" * "pci11ab,2b42" * "pci1b4b,2b42" diff --git a/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.yaml b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.yaml index f0c78f994491..7d526ff53fb7 100644 --- a/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.yaml +++ b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.yaml @@ -1,6 +1,5 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) # Copyright (c) 2018-2019 The Linux Foundation. All rights reserved. - %YAML 1.2 --- $id: http://devicetree.org/schemas/net/wireless/mediatek,mt76.yaml# diff --git a/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml b/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml index 556eb523606a..7d5f982a3d09 100644 --- a/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml +++ b/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml @@ -1,6 +1,5 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) # Copyright (c) 2018-2019 The Linux Foundation. All rights reserved. - %YAML 1.2 --- $id: http://devicetree.org/schemas/net/wireless/qcom,ath11k.yaml# @@ -21,6 +20,7 @@ properties: - qcom,ipq8074-wifi - qcom,ipq6018-wifi - qcom,wcn6750-wifi + - qcom,ipq5018-wifi reg: maxItems: 1 @@ -262,10 +262,10 @@ allOf: examples: - | - q6v5_wcss: q6v5_wcss@CD00000 { + q6v5_wcss: remoteproc@cd00000 { compatible = "qcom,ipq8074-wcss-pil"; - reg = <0xCD00000 0x4040>, - <0x4AB000 0x20>; + reg = <0xcd00000 0x4040>, + <0x4ab000 0x20>; reg-names = "qdsp6", "rmb"; }; @@ -386,7 +386,7 @@ examples: #address-cells = <2>; #size-cells = <2>; - qcn9074_0: qcn9074_0@51100000 { + qcn9074_0: wifi@51100000 { no-map; reg = <0x0 0x51100000 0x0 0x03500000>; }; @@ -463,6 +463,6 @@ examples: qcom,smem-states = <&wlan_smp2p_out 0>; qcom,smem-state-names = "wlan-smp2p-out"; wifi-firmware { - iommus = <&apps_smmu 0x1c02 0x1>; + iommus = <&apps_smmu 0x1c02 0x1>; }; }; diff --git a/Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml b/Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml index 583db5d42226..84e5659e50ef 100644 --- a/Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml +++ b/Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml @@ -2,7 +2,6 @@ # Copyright (c) 2020, Silicon Laboratories, Inc. %YAML 1.2 --- - $id: http://devicetree.org/schemas/net/wireless/silabs,wfx.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# diff --git a/Documentation/devicetree/bindings/net/wireless/ti,wlcore.yaml b/Documentation/devicetree/bindings/net/wireless/ti,wlcore.yaml index e31456730e9f..f799a1e52173 100644 --- a/Documentation/devicetree/bindings/net/wireless/ti,wlcore.yaml +++ b/Documentation/devicetree/bindings/net/wireless/ti,wlcore.yaml @@ -90,47 +90,47 @@ examples: // For wl12xx family: spi1 { - #address-cells = <1>; - #size-cells = <0>; - - wlcore1: wlcore@1 { - compatible = "ti,wl1271"; - reg = <1>; - spi-max-frequency = <48000000>; - interrupts = <8 IRQ_TYPE_LEVEL_HIGH>; - vwlan-supply = <&vwlan_fixed>; - clock-xtal; - ref-clock-frequency = <38400000>; - }; + #address-cells = <1>; + #size-cells = <0>; + + wlcore1: wlcore@1 { + compatible = "ti,wl1271"; + reg = <1>; + spi-max-frequency = <48000000>; + interrupts = <8 IRQ_TYPE_LEVEL_HIGH>; + vwlan-supply = <&vwlan_fixed>; + clock-xtal; + ref-clock-frequency = <38400000>; + }; }; // For wl18xx family: spi2 { - #address-cells = <1>; - #size-cells = <0>; - - wlcore2: wlcore@0 { - compatible = "ti,wl1835"; - reg = <0>; - spi-max-frequency = <48000000>; - interrupts = <27 IRQ_TYPE_EDGE_RISING>; - vwlan-supply = <&vwlan_fixed>; - }; + #address-cells = <1>; + #size-cells = <0>; + + wlcore2: wlcore@0 { + compatible = "ti,wl1835"; + reg = <0>; + spi-max-frequency = <48000000>; + interrupts = <27 IRQ_TYPE_EDGE_RISING>; + vwlan-supply = <&vwlan_fixed>; + }; }; // SDIO example: mmc3 { - vmmc-supply = <&wlan_en_reg>; - bus-width = <4>; - cap-power-off-card; - keep-power-in-suspend; - - #address-cells = <1>; - #size-cells = <0>; - - wlcore3: wlcore@2 { - compatible = "ti,wl1835"; - reg = <2>; - interrupts = <19 IRQ_TYPE_LEVEL_HIGH>; - }; + vmmc-supply = <&wlan_en_reg>; + bus-width = <4>; + cap-power-off-card; + keep-power-in-suspend; + + #address-cells = <1>; + #size-cells = <0>; + + wlcore3: wlcore@2 { + compatible = "ti,wl1835"; + reg = <2>; + interrupts = <19 IRQ_TYPE_LEVEL_HIGH>; + }; }; diff --git a/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml index 8e89b15b535f..2173fe82317d 100644 --- a/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml +++ b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml @@ -19,16 +19,21 @@ properties: - qcom,apq8064-qfprom - qcom,apq8084-qfprom - qcom,ipq8064-qfprom - - qcom,msm8974-qfprom + - qcom,ipq8074-qfprom - qcom,msm8916-qfprom + - qcom,msm8974-qfprom + - qcom,msm8976-qfprom - qcom,msm8996-qfprom - qcom,msm8998-qfprom - qcom,qcs404-qfprom - qcom,sc7180-qfprom - qcom,sc7280-qfprom - qcom,sdm630-qfprom + - qcom,sdm670-qfprom - qcom,sdm845-qfprom - qcom,sm6115-qfprom + - qcom,sm8150-qfprom + - qcom,sm8250-qfprom - const: qcom,qfprom reg: diff --git a/Documentation/devicetree/bindings/nvmem/socionext,uniphier-efuse.yaml b/Documentation/devicetree/bindings/nvmem/socionext,uniphier-efuse.yaml index 73a0c658dbfd..dc790d2cd9f0 100644 --- a/Documentation/devicetree/bindings/nvmem/socionext,uniphier-efuse.yaml +++ b/Documentation/devicetree/bindings/nvmem/socionext,uniphier-efuse.yaml @@ -31,65 +31,56 @@ unevaluatedProperties: false examples: - | - // The UniPhier eFuse should be a subnode of a "soc-glue" node. + efuse@100 { + compatible = "socionext,uniphier-efuse"; + reg = <0x100 0x28>; + }; - soc-glue@5f900000 { - compatible = "simple-mfd"; + efuse@200 { + compatible = "socionext,uniphier-efuse"; + reg = <0x200 0x68>; #address-cells = <1>; #size-cells = <1>; - ranges = <0x0 0x5f900000 0x2000>; - efuse@100 { - compatible = "socionext,uniphier-efuse"; - reg = <0x100 0x28>; + /* Data cells */ + usb_rterm0: trim@54,4 { + reg = <0x54 1>; + bits = <4 2>; }; - - efuse@200 { - compatible = "socionext,uniphier-efuse"; - reg = <0x200 0x68>; - #address-cells = <1>; - #size-cells = <1>; - - /* Data cells */ - usb_rterm0: trim@54,4 { - reg = <0x54 1>; - bits = <4 2>; - }; - usb_rterm1: trim@55,4 { - reg = <0x55 1>; - bits = <4 2>; - }; - usb_rterm2: trim@58,4 { - reg = <0x58 1>; - bits = <4 2>; - }; - usb_rterm3: trim@59,4 { - reg = <0x59 1>; - bits = <4 2>; - }; - usb_sel_t0: trim@54,0 { - reg = <0x54 1>; - bits = <0 4>; - }; - usb_sel_t1: trim@55,0 { - reg = <0x55 1>; - bits = <0 4>; - }; - usb_sel_t2: trim@58,0 { - reg = <0x58 1>; - bits = <0 4>; - }; - usb_sel_t3: trim@59,0 { - reg = <0x59 1>; - bits = <0 4>; - }; - usb_hs_i0: trim@56,0 { - reg = <0x56 1>; - bits = <0 4>; - }; - usb_hs_i2: trim@5a,0 { - reg = <0x5a 1>; - bits = <0 4>; - }; + usb_rterm1: trim@55,4 { + reg = <0x55 1>; + bits = <4 2>; + }; + usb_rterm2: trim@58,4 { + reg = <0x58 1>; + bits = <4 2>; + }; + usb_rterm3: trim@59,4 { + reg = <0x59 1>; + bits = <4 2>; + }; + usb_sel_t0: trim@54,0 { + reg = <0x54 1>; + bits = <0 4>; + }; + usb_sel_t1: trim@55,0 { + reg = <0x55 1>; + bits = <0 4>; + }; + usb_sel_t2: trim@58,0 { + reg = <0x58 1>; + bits = <0 4>; + }; + usb_sel_t3: trim@59,0 { + reg = <0x59 1>; + bits = <0 4>; + }; + usb_hs_i0: trim@56,0 { + reg = <0x56 1>; + bits = <0 4>; + }; + usb_hs_i2: trim@5a,0 { + reg = <0x5a 1>; + bits = <0 4>; }; }; diff --git a/Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml b/Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml index 60cf3cbde4c5..bbbad31ae4ca 100644 --- a/Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml +++ b/Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml @@ -50,12 +50,22 @@ patternProperties: opp-supported-hw: description: | A single 32 bit bitmap value, representing compatible HW. - Bitmap: + Bitmap for MSM8996 format: 0: MSM8996, speedbin 0 1: MSM8996, speedbin 1 2: MSM8996, speedbin 2 - 3-31: unused - maximum: 0x7 + 3: MSM8996, speedbin 3 + 4-31: unused + + Bitmap for MSM8996SG format (speedbin shifted of 4 left): + 0-3: unused + 4: MSM8996SG, speedbin 0 + 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] clock-latency-ns: true @@ -106,6 +116,7 @@ examples: L2_0: l2-cache { compatible = "cache"; cache-level = <2>; + cache-unified; }; }; @@ -140,6 +151,7 @@ examples: L2_1: l2-cache { compatible = "cache"; cache-level = <2>; + cache-unified; }; }; diff --git a/Documentation/devicetree/bindings/opp/opp-v2-qcom-level.yaml b/Documentation/devicetree/bindings/opp/opp-v2-qcom-level.yaml index b9ce2e099ce9..a30ef93213c0 100644 --- a/Documentation/devicetree/bindings/opp/opp-v2-qcom-level.yaml +++ b/Documentation/devicetree/bindings/opp/opp-v2-qcom-level.yaml @@ -30,7 +30,9 @@ patternProperties: this OPP node. Sometimes several corners/levels shares a certain fuse corner/level. A fuse corner/level contains e.g. ref uV, min uV, and max uV. - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 2 required: - opp-level diff --git a/Documentation/devicetree/bindings/pci/rockchip,rk3399-pcie-common.yaml b/Documentation/devicetree/bindings/pci/rockchip,rk3399-pcie-common.yaml new file mode 100644 index 000000000000..a8574f8a84a3 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/rockchip,rk3399-pcie-common.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/rockchip,rk3399-pcie-common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip AXI PCIe Bridge Common Properties + +maintainers: + - Shawn Lin <shawn.lin@rock-chips.com> + +properties: + reg: + maxItems: 2 + + clocks: + maxItems: 4 + + clock-names: + items: + - const: aclk + - const: aclk-perf + - const: hclk + - const: pm + + num-lanes: + maximum: 4 + + phys: + oneOf: + - maxItems: 1 + - maxItems: 4 + + phy-names: + oneOf: + - const: pcie-phy + - items: + - const: pcie-phy-0 + - const: pcie-phy-1 + - const: pcie-phy-2 + - const: pcie-phy-3 + + resets: + maxItems: 7 + + reset-names: + items: + - const: core + - const: mgmt + - const: mgmt-sticky + - const: pipe + - const: pm + - const: pclk + - const: aclk + +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + - phys + - phy-names + - resets + - reset-names + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/pci/rockchip,rk3399-pcie-ep.yaml b/Documentation/devicetree/bindings/pci/rockchip,rk3399-pcie-ep.yaml new file mode 100644 index 000000000000..88386a6d7011 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/rockchip,rk3399-pcie-ep.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/rockchip,rk3399-pcie-ep.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip AXI PCIe Endpoint + +maintainers: + - Shawn Lin <shawn.lin@rock-chips.com> + +allOf: + - $ref: /schemas/pci/pci-ep.yaml# + - $ref: rockchip,rk3399-pcie-common.yaml# + +properties: + compatible: + const: rockchip,rk3399-pcie-ep + + reg: true + + reg-names: + items: + - const: apb-base + - const: mem-base + + rockchip,max-outbound-regions: + description: Maximum number of outbound regions + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 32 + default: 32 + +required: + - rockchip,max-outbound-regions + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/clock/rk3399-cru.h> + + bus { + #address-cells = <2>; + #size-cells = <2>; + + pcie-ep@f8000000 { + compatible = "rockchip,rk3399-pcie-ep"; + reg = <0x0 0xfd000000 0x0 0x1000000>, <0x0 0x80000000 0x0 0x20000>; + reg-names = "apb-base", "mem-base"; + clocks = <&cru ACLK_PCIE>, <&cru ACLK_PERF_PCIE>, + <&cru PCLK_PCIE>, <&cru SCLK_PCIE_PM>; + clock-names = "aclk", "aclk-perf", + "hclk", "pm"; + max-functions = /bits/ 8 <8>; + num-lanes = <4>; + resets = <&cru SRST_PCIE_CORE>, <&cru SRST_PCIE_MGMT>, + <&cru SRST_PCIE_MGMT_STICKY>, <&cru SRST_PCIE_PIPE> , + <&cru SRST_PCIE_PM>, <&cru SRST_P_PCIE>, <&cru SRST_A_PCIE>; + reset-names = "core", "mgmt", "mgmt-sticky", "pipe", + "pm", "pclk", "aclk"; + phys = <&pcie_phy 0>, <&pcie_phy 1>, <&pcie_phy 2>, <&pcie_phy 3>; + phy-names = "pcie-phy-0", "pcie-phy-1", "pcie-phy-2", "pcie-phy-3"; + rockchip,max-outbound-regions = <16>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pci/rockchip,rk3399-pcie.yaml b/Documentation/devicetree/bindings/pci/rockchip,rk3399-pcie.yaml new file mode 100644 index 000000000000..531008f0b6ac --- /dev/null +++ b/Documentation/devicetree/bindings/pci/rockchip,rk3399-pcie.yaml @@ -0,0 +1,132 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/rockchip,rk3399-pcie.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip AXI PCIe Root Port Bridge Host + +maintainers: + - Shawn Lin <shawn.lin@rock-chips.com> + +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + - $ref: rockchip,rk3399-pcie-common.yaml# + +properties: + compatible: + const: rockchip,rk3399-pcie + + reg: true + + reg-names: + items: + - const: axi-base + - const: apb-base + + interrupts: + maxItems: 3 + + interrupt-names: + items: + - const: sys + - const: legacy + - const: client + + aspm-no-l0s: + description: This property is needed if using 24MHz OSC for RC's PHY. + + ep-gpios: + description: pre-reset GPIO + + vpcie12v-supply: + description: The 12v regulator to use for PCIe. + + vpcie3v3-supply: + description: The 3.3v regulator to use for PCIe. + + vpcie1v8-supply: + description: The 1.8v regulator to use for PCIe. + + vpcie0v9-supply: + description: The 0.9v regulator to use for PCIe. + + interrupt-controller: + type: object + additionalProperties: false + + properties: + '#address-cells': + const: 0 + + '#interrupt-cells': + const: 1 + + interrupt-controller: true + +required: + - ranges + - "#interrupt-cells" + - interrupts + - interrupt-controller + - interrupt-map + - interrupt-map-mask + - msi-map + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/clock/rk3399-cru.h> + + bus { + #address-cells = <2>; + #size-cells = <2>; + + pcie@f8000000 { + compatible = "rockchip,rk3399-pcie"; + device_type = "pci"; + #address-cells = <3>; + #size-cells = <2>; + clocks = <&cru ACLK_PCIE>, <&cru ACLK_PERF_PCIE>, + <&cru PCLK_PCIE>, <&cru SCLK_PCIE_PM>; + clock-names = "aclk", "aclk-perf", + "hclk", "pm"; + interrupts = <GIC_SPI 49 IRQ_TYPE_LEVEL_HIGH 0>, + <GIC_SPI 50 IRQ_TYPE_LEVEL_HIGH 0>, + <GIC_SPI 51 IRQ_TYPE_LEVEL_HIGH 0>; + interrupt-names = "sys", "legacy", "client"; + ep-gpios = <&gpio3 13 GPIO_ACTIVE_HIGH>; + ranges = <0x83000000 0x0 0xfa000000 0x0 0xfa000000 0x0 0x600000 + 0x81000000 0x0 0xfa600000 0x0 0xfa600000 0x0 0x100000>; + num-lanes = <4>; + msi-map = <0x0 &its 0x0 0x1000>; + reg = <0x0 0xf8000000 0x0 0x2000000>, <0x0 0xfd000000 0x0 0x1000000>; + reg-names = "axi-base", "apb-base"; + resets = <&cru SRST_PCIE_CORE>, <&cru SRST_PCIE_MGMT>, + <&cru SRST_PCIE_MGMT_STICKY>, <&cru SRST_PCIE_PIPE> , + <&cru SRST_PCIE_PM>, <&cru SRST_P_PCIE>, <&cru SRST_A_PCIE>; + reset-names = "core", "mgmt", "mgmt-sticky", "pipe", + "pm", "pclk", "aclk"; + /* deprecated legacy PHY model */ + phys = <&pcie_phy>; + phy-names = "pcie-phy"; + pinctrl-names = "default"; + pinctrl-0 = <&pcie_clkreq>; + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0 0 0 1 &pcie0_intc 0>, + <0 0 0 2 &pcie0_intc 1>, + <0 0 0 3 &pcie0_intc 2>, + <0 0 0 4 &pcie0_intc 3>; + + pcie0_intc: interrupt-controller { + interrupt-controller; + #address-cells = <0>; + #interrupt-cells = <1>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pci/rockchip-pcie-ep.txt b/Documentation/devicetree/bindings/pci/rockchip-pcie-ep.txt deleted file mode 100644 index 778467307a93..000000000000 --- a/Documentation/devicetree/bindings/pci/rockchip-pcie-ep.txt +++ /dev/null @@ -1,62 +0,0 @@ -* Rockchip AXI PCIe Endpoint Controller DT description - -Required properties: -- compatible: Should contain "rockchip,rk3399-pcie-ep" -- reg: Two register ranges as listed in the reg-names property -- reg-names: Must include the following names - - "apb-base" - - "mem-base" -- clocks: Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names: Must include the following entries: - - "aclk" - - "aclk-perf" - - "hclk" - - "pm" -- resets: Must contain seven entries for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names: Must include the following names - - "core" - - "mgmt" - - "mgmt-sticky" - - "pipe" - - "pm" - - "aclk" - - "pclk" -- pinctrl-names : The pin control state names -- pinctrl-0: The "default" pinctrl state -- phys: Must contain an phandle to a PHY for each entry in phy-names. -- phy-names: Must include 4 entries for all 4 lanes even if some of - them won't be used for your cases. Entries are of the form "pcie-phy-N": - where N ranges from 0 to 3. - (see example below and you MUST also refer to ../phy/rockchip-pcie-phy.txt - for changing the #phy-cells of phy node to support it) -- rockchip,max-outbound-regions: Maximum number of outbound regions - -Optional Property: -- num-lanes: number of lanes to use -- max-functions: Maximum number of functions that can be configured (default 1). - -pcie0-ep: pcie@f8000000 { - compatible = "rockchip,rk3399-pcie-ep"; - #address-cells = <3>; - #size-cells = <2>; - rockchip,max-outbound-regions = <16>; - clocks = <&cru ACLK_PCIE>, <&cru ACLK_PERF_PCIE>, - <&cru PCLK_PCIE>, <&cru SCLK_PCIE_PM>; - clock-names = "aclk", "aclk-perf", - "hclk", "pm"; - max-functions = /bits/ 8 <8>; - num-lanes = <4>; - reg = <0x0 0xfd000000 0x0 0x1000000>, <0x0 0x80000000 0x0 0x20000>; - reg-names = "apb-base", "mem-base"; - resets = <&cru SRST_PCIE_CORE>, <&cru SRST_PCIE_MGMT>, - <&cru SRST_PCIE_MGMT_STICKY>, <&cru SRST_PCIE_PIPE> , - <&cru SRST_PCIE_PM>, <&cru SRST_P_PCIE>, <&cru SRST_A_PCIE>; - reset-names = "core", "mgmt", "mgmt-sticky", "pipe", - "pm", "pclk", "aclk"; - phys = <&pcie_phy 0>, <&pcie_phy 1>, <&pcie_phy 2>, <&pcie_phy 3>; - phy-names = "pcie-phy-0", "pcie-phy-1", "pcie-phy-2", "pcie-phy-3"; - pinctrl-names = "default"; - pinctrl-0 = <&pcie_clkreq>; -}; diff --git a/Documentation/devicetree/bindings/pci/rockchip-pcie-host.txt b/Documentation/devicetree/bindings/pci/rockchip-pcie-host.txt deleted file mode 100644 index af34c65773fd..000000000000 --- a/Documentation/devicetree/bindings/pci/rockchip-pcie-host.txt +++ /dev/null @@ -1,135 +0,0 @@ -* Rockchip AXI PCIe Root Port Bridge DT description - -Required properties: -- #address-cells: Address representation for root ports, set to <3> -- #size-cells: Size representation for root ports, set to <2> -- #interrupt-cells: specifies the number of cells needed to encode an - interrupt source. The value must be 1. -- compatible: Should contain "rockchip,rk3399-pcie" -- reg: Two register ranges as listed in the reg-names property -- reg-names: Must include the following names - - "axi-base" - - "apb-base" -- clocks: Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names: Must include the following entries: - - "aclk" - - "aclk-perf" - - "hclk" - - "pm" -- msi-map: Maps a Requester ID to an MSI controller and associated - msi-specifier data. See ./pci-msi.txt -- interrupts: Three interrupt entries must be specified. -- interrupt-names: Must include the following names - - "sys" - - "legacy" - - "client" -- resets: Must contain seven entries for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names: Must include the following names - - "core" - - "mgmt" - - "mgmt-sticky" - - "pipe" - - "pm" - - "aclk" - - "pclk" -- pinctrl-names : The pin control state names -- pinctrl-0: The "default" pinctrl state -- #interrupt-cells: specifies the number of cells needed to encode an - interrupt source. The value must be 1. -- interrupt-map-mask and interrupt-map: standard PCI properties - -Required properties for legacy PHY model (deprecated): -- phys: From PHY bindings: Phandle for the Generic PHY for PCIe. -- phy-names: MUST be "pcie-phy". - -Required properties for per-lane PHY model (preferred): -- phys: Must contain an phandle to a PHY for each entry in phy-names. -- phy-names: Must include 4 entries for all 4 lanes even if some of - them won't be used for your cases. Entries are of the form "pcie-phy-N": - where N ranges from 0 to 3. - (see example below and you MUST also refer to ../phy/rockchip-pcie-phy.txt - for changing the #phy-cells of phy node to support it) - -Optional Property: -- aspm-no-l0s: RC won't support ASPM L0s. This property is needed if - using 24MHz OSC for RC's PHY. -- ep-gpios: contain the entry for pre-reset GPIO -- num-lanes: number of lanes to use -- vpcie12v-supply: The phandle to the 12v regulator to use for PCIe. -- vpcie3v3-supply: The phandle to the 3.3v regulator to use for PCIe. -- vpcie1v8-supply: The phandle to the 1.8v regulator to use for PCIe. -- vpcie0v9-supply: The phandle to the 0.9v regulator to use for PCIe. - -*Interrupt controller child node* -The core controller provides a single interrupt for legacy INTx. The PCIe node -should contain an interrupt controller node as a target for the PCI -'interrupt-map' property. This node represents the domain at which the four -INTx interrupts are decoded and routed. - - -Required properties for Interrupt controller child node: -- interrupt-controller: identifies the node as an interrupt controller -- #address-cells: specifies the number of cells needed to encode an - address. The value must be 0. -- #interrupt-cells: specifies the number of cells needed to encode an - interrupt source. The value must be 1. - -Example: - -pcie0: pcie@f8000000 { - compatible = "rockchip,rk3399-pcie"; - #address-cells = <3>; - #size-cells = <2>; - clocks = <&cru ACLK_PCIE>, <&cru ACLK_PERF_PCIE>, - <&cru PCLK_PCIE>, <&cru SCLK_PCIE_PM>; - clock-names = "aclk", "aclk-perf", - "hclk", "pm"; - bus-range = <0x0 0x1>; - interrupts = <GIC_SPI 49 IRQ_TYPE_LEVEL_HIGH 0>, - <GIC_SPI 50 IRQ_TYPE_LEVEL_HIGH 0>, - <GIC_SPI 51 IRQ_TYPE_LEVEL_HIGH 0>; - interrupt-names = "sys", "legacy", "client"; - assigned-clocks = <&cru SCLK_PCIEPHY_REF>; - assigned-clock-parents = <&cru SCLK_PCIEPHY_REF100M>; - assigned-clock-rates = <100000000>; - ep-gpios = <&gpio3 13 GPIO_ACTIVE_HIGH>; - ranges = <0x83000000 0x0 0xfa000000 0x0 0xfa000000 0x0 0x600000 - 0x81000000 0x0 0xfa600000 0x0 0xfa600000 0x0 0x100000>; - num-lanes = <4>; - msi-map = <0x0 &its 0x0 0x1000>; - reg = <0x0 0xf8000000 0x0 0x2000000>, <0x0 0xfd000000 0x0 0x1000000>; - reg-names = "axi-base", "apb-base"; - resets = <&cru SRST_PCIE_CORE>, <&cru SRST_PCIE_MGMT>, - <&cru SRST_PCIE_MGMT_STICKY>, <&cru SRST_PCIE_PIPE> , - <&cru SRST_PCIE_PM>, <&cru SRST_P_PCIE>, <&cru SRST_A_PCIE>; - reset-names = "core", "mgmt", "mgmt-sticky", "pipe", - "pm", "pclk", "aclk"; - /* deprecated legacy PHY model */ - phys = <&pcie_phy>; - phy-names = "pcie-phy"; - pinctrl-names = "default"; - pinctrl-0 = <&pcie_clkreq>; - #interrupt-cells = <1>; - interrupt-map-mask = <0 0 0 7>; - interrupt-map = <0 0 0 1 &pcie0_intc 0>, - <0 0 0 2 &pcie0_intc 1>, - <0 0 0 3 &pcie0_intc 2>, - <0 0 0 4 &pcie0_intc 3>; - pcie0_intc: interrupt-controller { - interrupt-controller; - #address-cells = <0>; - #interrupt-cells = <1>; - }; -}; - -pcie0: pcie@f8000000 { - ... - - /* preferred per-lane PHY model */ - phys = <&pcie_phy 0>, <&pcie_phy 1>, <&pcie_phy 2>, <&pcie_phy 3>; - phy-names = "pcie-phy-0", "pcie-phy-1", "pcie-phy-2", "pcie-phy-3"; - - ... -}; diff --git a/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml b/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml index b0513b197d08..3d7aee97353a 100644 --- a/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml +++ b/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml @@ -66,15 +66,11 @@ properties: const: 0x104c device-id: - oneOf: - - items: - - const: 0xb00d - - items: - - const: 0xb00f - - items: - - const: 0xb010 - - items: - - const: 0xb013 + enum: + - 0xb00d + - 0xb00f + - 0xb010 + - 0xb013 msi-map: true diff --git a/Documentation/devicetree/bindings/perf/riscv,pmu.yaml b/Documentation/devicetree/bindings/perf/riscv,pmu.yaml new file mode 100644 index 000000000000..a55a4d047d3f --- /dev/null +++ b/Documentation/devicetree/bindings/perf/riscv,pmu.yaml @@ -0,0 +1,161 @@ +# SPDX-License-Identifier: BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/perf/riscv,pmu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: RISC-V SBI PMU events + +maintainers: + - Atish Patra <atishp@rivosinc.com> + +description: | + The SBI PMU extension allows supervisor software to configure, start and + stop any performance counter at anytime. Thus, a user can leverage all + capabilities of performance analysis tools, such as perf, if the SBI PMU + extension is enabled. The following constraints apply: + + The platform must provide information about PMU event to counter mappings + either via device tree or another way, specific to the platform. + Without the event to counter mappings, the SBI PMU extension cannot be used. + + Platforms should provide information about the PMU event selector values + that should be encoded in the expected value of MHPMEVENTx while configuring + MHPMCOUNTERx for that specific event. The can either be done via device tree + or another way, specific to the platform. + The exact value to be written to MHPMEVENTx is completely dependent on the + platform. + + For information on the SBI specification see the section "Performance + Monitoring Unit Extension" of: + https://github.com/riscv-non-isa/riscv-sbi-doc/blob/master/riscv-sbi.adoc + +properties: + compatible: + const: riscv,pmu + + riscv,event-to-mhpmevent: + $ref: /schemas/types.yaml#/definitions/uint32-matrix + description: + Represents an ONE-to-ONE mapping between a PMU event and the event + selector value that the platform expects to be written to the MHPMEVENTx + CSR for that event. + The mapping is encoded in an matrix format where each element represents + an event. + This property shouldn't encode any raw hardware event. + items: + items: + - description: event_idx, a 20-bit wide encoding of the event type and + code. Refer to the SBI specification for a complete description of + the event types and codes. + - description: upper 32 bits of the event selector value for MHPMEVENTx + - description: lower 32 bits of the event selector value for MHPMEVENTx + + riscv,event-to-mhpmcounters: + $ref: /schemas/types.yaml#/definitions/uint32-matrix + description: + Represents a MANY-to-MANY mapping between a range of events and all the + MHPMCOUNTERx in a bitmap format that can be used to monitor these range + of events. The information is encoded in an matrix format where each + element represents a certain range of events and corresponding counters. + This property shouldn't encode any raw event. + items: + items: + - description: first event_idx of the range of events + - description: last event_idx of the range of events + - description: bitmap of MHPMCOUNTERx for this event + + riscv,raw-event-to-mhpmcounters: + $ref: /schemas/types.yaml#/definitions/uint32-matrix + description: + Represents an ONE-to-MANY or MANY-to-MANY mapping between the rawevent(s) + and all the MHPMCOUNTERx in a bitmap format that can be used to monitor + that raw event. + The encoding of the raw events are platform specific. The information is + encoded in a matrix format where each element represents the specific raw + event(s). + If a platform directly encodes each raw PMU event as a unique ID, the + value of variant must be 0xffffffff_ffffffff. + items: + items: + - description: + upper 32 invariant bits for the range of events + - description: + lower 32 invariant bits for the range of events + - description: + upper 32 bits of the variant bit mask for the range of events + - description: + lower 32 bits of the variant bit mask for the range of events + - description: + bitmap of all MHPMCOUNTERx that can monitor the range of events + +dependencies: + "riscv,event-to-mhpmevent": [ "riscv,event-to-mhpmcounters" ] + "riscv,event-to-mhpmcounters": [ "riscv,event-to-mhpmevent" ] + +required: + - compatible + +additionalProperties: false + +examples: + - | + pmu { + compatible = "riscv,pmu"; + riscv,event-to-mhpmevent = <0x0000B 0x0000 0x0001>; + riscv,event-to-mhpmcounters = <0x00001 0x00001 0x00000001>, + <0x00002 0x00002 0x00000004>, + <0x00003 0x0000A 0x00000ff8>, + <0x10000 0x10033 0x000ff000>; + riscv,raw-event-to-mhpmcounters = + /* For event ID 0x0002 */ + <0x0000 0x0002 0xffffffff 0xffffffff 0x00000f8>, + /* For event ID 0-4 */ + <0x0 0x0 0xffffffff 0xfffffff0 0x00000ff0>, + /* For event ID 0xffffffff0000000f - 0xffffffff000000ff */ + <0xffffffff 0x0 0xffffffff 0xffffff0f 0x00000ff0>; + }; + + - | + /* + * For HiFive Unmatched board the encodings can be found here + * https://sifive.cdn.prismic.io/sifive/1a82e600-1f93-4f41-b2d8-86ed8b16acba_fu740-c000-manual-v1p6.pdf + * + * This example also binds standard SBI PMU hardware IDs to U74 PMU event + * codes, U74 uses a bitfield for events encoding, so several U74 events + * can be bound to a single perf ID. + * See SBI PMU hardware IDs in arch/riscv/include/asm/sbi.h + */ + pmu { + compatible = "riscv,pmu"; + riscv,event-to-mhpmevent = + /* SBI_PMU_HW_CACHE_REFERENCES -> Instruction or Data cache/ITIM busy */ + <0x00003 0x00000000 0x1801>, + /* SBI_PMU_HW_CACHE_MISSES -> Instruction or Data cache miss or MMIO access */ + <0x00004 0x00000000 0x0302>, + /* SBI_PMU_HW_BRANCH_INSTRUCTIONS -> Conditional branch retired */ + <0x00005 0x00000000 0x4000>, + /* SBI_PMU_HW_BRANCH_MISSES -> Branch or jump misprediction */ + <0x00006 0x00000000 0x6001>, + /* L1D_READ_MISS -> Data cache miss or MMIO access */ + <0x10001 0x00000000 0x0202>, + /* L1D_WRITE_ACCESS -> Data cache write-back */ + <0x10002 0x00000000 0x0402>, + /* L1I_READ_ACCESS -> Instruction cache miss */ + <0x10009 0x00000000 0x0102>, + /* LL_READ_MISS -> UTLB miss */ + <0x10011 0x00000000 0x2002>, + /* DTLB_READ_MISS -> Data TLB miss */ + <0x10019 0x00000000 0x1002>, + /* ITLB_READ_MISS-> Instruction TLB miss */ + <0x10021 0x00000000 0x0802>; + riscv,event-to-mhpmcounters = <0x00003 0x00006 0x18>, + <0x10001 0x10002 0x18>, + <0x10009 0x10009 0x18>, + <0x10011 0x10011 0x18>, + <0x10019 0x10019 0x18>, + <0x10021 0x10021 0x18>; + riscv,raw-event-to-mhpmcounters = <0x0 0x0 0xffffffff 0xfc0000ff 0x18>, + <0x0 0x1 0xffffffff 0xfff800ff 0x18>, + <0x0 0x2 0xffffffff 0xffffe0ff 0x18>; + }; diff --git a/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb2-phy.yaml b/Documentation/devicetree/bindings/phy/amlogic,g12a-usb2-phy.yaml index f3a5fbabbbb5..bb01c6b34dab 100644 --- a/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb2-phy.yaml +++ b/Documentation/devicetree/bindings/phy/amlogic,g12a-usb2-phy.yaml @@ -2,7 +2,7 @@ # Copyright 2019 BayLibre, SAS %YAML 1.2 --- -$id: "http://devicetree.org/schemas/phy/amlogic,meson-g12a-usb2-phy.yaml#" +$id: "http://devicetree.org/schemas/phy/amlogic,g12a-usb2-phy.yaml#" $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic G12A USB2 PHY @@ -13,8 +13,8 @@ maintainers: properties: compatible: enum: - - amlogic,meson-g12a-usb2-phy - - amlogic,meson-a1-usb2-phy + - amlogic,g12a-usb2-phy + - amlogic,a1-usb2-phy reg: maxItems: 1 @@ -68,7 +68,7 @@ additionalProperties: false examples: - | phy@36000 { - compatible = "amlogic,meson-g12a-usb2-phy"; + compatible = "amlogic,g12a-usb2-phy"; reg = <0x36000 0x2000>; clocks = <&xtal>; clock-names = "xtal"; diff --git a/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb3-pcie-phy.yaml b/Documentation/devicetree/bindings/phy/amlogic,g12a-usb3-pcie-phy.yaml index 868b4e6fde71..129d26e99776 100644 --- a/Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb3-pcie-phy.yaml +++ b/Documentation/devicetree/bindings/phy/amlogic,g12a-usb3-pcie-phy.yaml @@ -2,7 +2,7 @@ # Copyright 2019 BayLibre, SAS %YAML 1.2 --- -$id: "http://devicetree.org/schemas/phy/amlogic,meson-g12a-usb3-pcie-phy.yaml#" +$id: "http://devicetree.org/schemas/phy/amlogic,g12a-usb3-pcie-phy.yaml#" $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: Amlogic G12A USB3 + PCIE Combo PHY @@ -13,7 +13,7 @@ maintainers: properties: compatible: enum: - - amlogic,meson-g12a-usb3-pcie-phy + - amlogic,g12a-usb3-pcie-phy reg: maxItems: 1 @@ -49,7 +49,7 @@ additionalProperties: false examples: - | phy@46000 { - compatible = "amlogic,meson-g12a-usb3-pcie-phy"; + compatible = "amlogic,g12a-usb3-pcie-phy"; reg = <0x46000 0x2000>; clocks = <&ref_clk>; clock-names = "ref_clk"; diff --git a/Documentation/devicetree/bindings/phy/hisilicon,hi3660-usb3.yaml b/Documentation/devicetree/bindings/phy/hisilicon,hi3660-usb3.yaml index 20b79e2e8b82..b11d9873854a 100644 --- a/Documentation/devicetree/bindings/phy/hisilicon,hi3660-usb3.yaml +++ b/Documentation/devicetree/bindings/phy/hisilicon,hi3660-usb3.yaml @@ -27,7 +27,8 @@ properties: description: phandle of syscon used to control usb tcxo. hisilicon,eye-diagram-param: - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: /schemas/types.yaml#/definitions/uint32-array + maxItems: 1 description: Eye diagram for phy. required: diff --git a/Documentation/devicetree/bindings/phy/hisilicon,hi3670-usb3.yaml b/Documentation/devicetree/bindings/phy/hisilicon,hi3670-usb3.yaml index 1cb00dbcd4c5..3c69aca6c7eb 100644 --- a/Documentation/devicetree/bindings/phy/hisilicon,hi3670-usb3.yaml +++ b/Documentation/devicetree/bindings/phy/hisilicon,hi3670-usb3.yaml @@ -32,7 +32,8 @@ properties: description: phandle of syscon used to control phy deep sleep. hisilicon,eye-diagram-param: - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: /schemas/types.yaml#/definitions/uint32-array + maxItems: 1 description: Eye diagram for phy. hisilicon,tx-vboost-lvl: diff --git a/Documentation/devicetree/bindings/phy/qcom,hdmi-phy-other.yaml b/Documentation/devicetree/bindings/phy/qcom,hdmi-phy-other.yaml index fdb277edebeb..0c8f03b78608 100644 --- a/Documentation/devicetree/bindings/phy/qcom,hdmi-phy-other.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,hdmi-phy-other.yaml @@ -43,6 +43,9 @@ properties: vddio-supply: description: phandle to VDD I/O supply regulator + '#clock-cells': + const: 0 + '#phy-cells': const: 0 @@ -53,7 +56,6 @@ allOf: contains: enum: - qcom,hdmi-phy-8660 - - qcom,hdmi-phy-8960 then: properties: clocks: @@ -68,6 +70,24 @@ allOf: compatible: contains: enum: + - qcom,hdmi-phy-8960 + then: + properties: + clocks: + minItems: 1 + maxItems: 2 + clock-names: + minItems: 1 + items: + - const: slave_iface + - const: pxo + vddio-supply: false + + - if: + properties: + compatible: + contains: + enum: - qcom,hdmi-phy-8084 - qcom,hdmi-phy-8974 then: @@ -96,9 +116,10 @@ examples: "hdmi_pll"; reg = <0x4a00400 0x60>, <0x4a00500 0x100>; + #clock-cells = <0>; #phy-cells = <0>; power-domains = <&mmcc 1>; - clock-names = "slave_iface"; - clocks = <&clk 21>; + clock-names = "slave_iface", "pxo"; + clocks = <&clk 21>, <&pxo_board>; core-vdda-supply = <&pm8921_hdmi_mvs>; }; diff --git a/Documentation/devicetree/bindings/phy/qcom,usb-hs-28nm.yaml b/Documentation/devicetree/bindings/phy/qcom,usb-hs-28nm.yaml index abcc4373f39e..ca6a0836b53c 100644 --- a/Documentation/devicetree/bindings/phy/qcom,usb-hs-28nm.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,usb-hs-28nm.yaml @@ -16,7 +16,6 @@ properties: compatible: enum: - qcom,usb-hs-28nm-femtophy - - qcom,usb-hs-28nm-mdm9607 reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.yaml b/Documentation/devicetree/bindings/phy/rockchip,inno-usb2phy.yaml index f71920082fa3..0d6b8c28be07 100644 --- a/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.yaml +++ b/Documentation/devicetree/bindings/phy/rockchip,inno-usb2phy.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0 %YAML 1.2 --- -$id: http://devicetree.org/schemas/phy/phy-rockchip-inno-usb2.yaml# +$id: http://devicetree.org/schemas/phy/rockchip,inno-usb2phy.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Rockchip USB2.0 phy with inno IP block diff --git a/Documentation/devicetree/bindings/phy/rockchip,rk3288-dp-phy.yaml b/Documentation/devicetree/bindings/phy/rockchip,rk3288-dp-phy.yaml new file mode 100644 index 000000000000..2538235c5ac6 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/rockchip,rk3288-dp-phy.yaml @@ -0,0 +1,41 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/rockchip,rk3288-dp-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip specific extensions to the Analogix Display Port PHY + +maintainers: + - Heiko Stuebner <heiko@sntech.de> + +properties: + compatible: + const: rockchip,rk3288-dp-phy + + clocks: + maxItems: 1 + + clock-names: + const: 24m + + "#phy-cells": + const: 0 + +required: + - compatible + - clocks + - clock-names + - "#phy-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/rk3288-cru.h> + edp-phy { + compatible = "rockchip,rk3288-dp-phy"; + clocks = <&cru SCLK_EDP_24M>; + clock-names = "24m"; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/rockchip-dp-phy.txt b/Documentation/devicetree/bindings/phy/rockchip-dp-phy.txt deleted file mode 100644 index e3b4809fbe82..000000000000 --- a/Documentation/devicetree/bindings/phy/rockchip-dp-phy.txt +++ /dev/null @@ -1,26 +0,0 @@ -Rockchip specific extensions to the Analogix Display Port PHY ------------------------------------- - -Required properties: -- compatible : should be one of the following supported values: - - "rockchip.rk3288-dp-phy" -- clocks: from common clock binding: handle to dp clock. - of memory mapped region. -- clock-names: from common clock binding: - Required elements: "24m" -- #phy-cells : from the generic PHY bindings, must be 0; - -Example: - -grf: syscon@ff770000 { - compatible = "rockchip,rk3288-grf", "syscon", "simple-mfd"; - -... - - edp_phy: edp-phy { - compatible = "rockchip,rk3288-dp-phy"; - clocks = <&cru SCLK_EDP_24M>; - clock-names = "24m"; - #phy-cells = <0>; - }; -}; diff --git a/Documentation/devicetree/bindings/phy/socionext,uniphier-ahci-phy.yaml b/Documentation/devicetree/bindings/phy/socionext,uniphier-ahci-phy.yaml index a3cd45acea28..de3cffc850bc 100644 --- a/Documentation/devicetree/bindings/phy/socionext,uniphier-ahci-phy.yaml +++ b/Documentation/devicetree/bindings/phy/socionext,uniphier-ahci-phy.yaml @@ -117,20 +117,12 @@ additionalProperties: false examples: - | - ahci-glue@65700000 { - compatible = "socionext,uniphier-pxs3-ahci-glue", - "simple-mfd"; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0 0x65700000 0x100>; - - ahci_phy: phy@10 { - compatible = "socionext,uniphier-pxs3-ahci-phy"; - reg = <0x10 0x10>; - #phy-cells = <0>; - clock-names = "link", "phy"; - clocks = <&sys_clk 28>, <&sys_clk 30>; - reset-names = "link", "phy"; - resets = <&sys_rst 28>, <&sys_rst 30>; - }; + ahci_phy: phy@10 { + compatible = "socionext,uniphier-pxs3-ahci-phy"; + reg = <0x10 0x10>; + #phy-cells = <0>; + clock-names = "link", "phy"; + clocks = <&sys_clk 28>, <&sys_clk 30>; + reset-names = "link", "phy"; + resets = <&sys_rst 28>, <&sys_rst 30>; }; diff --git a/Documentation/devicetree/bindings/phy/socionext,uniphier-usb2-phy.yaml b/Documentation/devicetree/bindings/phy/socionext,uniphier-usb2-phy.yaml index 63dab914a48d..19522c54f448 100644 --- a/Documentation/devicetree/bindings/phy/socionext,uniphier-usb2-phy.yaml +++ b/Documentation/devicetree/bindings/phy/socionext,uniphier-usb2-phy.yaml @@ -61,28 +61,23 @@ examples: - | // The UniPhier usb2-phy should be a subnode of a "syscon" compatible node. - soc-glue@5f800000 { - compatible = "socionext,uniphier-ld11-soc-glue", "simple-mfd", "syscon"; - reg = <0x5f800000 0x2000>; - - usb-controller { - compatible = "socionext,uniphier-ld11-usb2-phy"; - #address-cells = <1>; - #size-cells = <0>; - - usb_phy0: phy@0 { - reg = <0>; - #phy-cells = <0>; - }; - - usb_phy1: phy@1 { - reg = <1>; - #phy-cells = <0>; - }; - - usb_phy2: phy@2 { - reg = <2>; - #phy-cells = <0>; - }; + usb-hub { + compatible = "socionext,uniphier-ld11-usb2-phy"; + #address-cells = <1>; + #size-cells = <0>; + + usb_phy0: phy@0 { + reg = <0>; + #phy-cells = <0>; + }; + + usb_phy1: phy@1 { + reg = <1>; + #phy-cells = <0>; + }; + + usb_phy2: phy@2 { + reg = <2>; + #phy-cells = <0>; }; }; diff --git a/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml b/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml index 21e4414eea60..2107d98ace15 100644 --- a/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml +++ b/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml @@ -146,22 +146,15 @@ additionalProperties: false examples: - | - usb-glue@65b00000 { - compatible = "socionext,uniphier-ld20-dwc3-glue", "simple-mfd"; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0 0x65b00000 0x400>; - - usb_hsphy0: hs-phy@200 { - compatible = "socionext,uniphier-ld20-usb3-hsphy"; - reg = <0x200 0x10>; - #phy-cells = <0>; - clock-names = "link", "phy"; - clocks = <&sys_clk 14>, <&sys_clk 16>; - reset-names = "link", "phy"; - resets = <&sys_rst 14>, <&sys_rst 16>; - vbus-supply = <&usb_vbus0>; - nvmem-cell-names = "rterm", "sel_t", "hs_i"; - nvmem-cells = <&usb_rterm0>, <&usb_sel_t0>, <&usb_hs_i0>; - }; + usb_hsphy0: phy@200 { + compatible = "socionext,uniphier-ld20-usb3-hsphy"; + reg = <0x200 0x10>; + #phy-cells = <0>; + clock-names = "link", "phy"; + clocks = <&sys_clk 14>, <&sys_clk 16>; + reset-names = "link", "phy"; + resets = <&sys_rst 14>, <&sys_rst 16>; + vbus-supply = <&usb_vbus0>; + nvmem-cell-names = "rterm", "sel_t", "hs_i"; + nvmem-cells = <&usb_rterm0>, <&usb_sel_t0>, <&usb_hs_i0>; }; diff --git a/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3ss-phy.yaml b/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3ss-phy.yaml index 4c26d2d2303d..8f5aa6238bf3 100644 --- a/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3ss-phy.yaml +++ b/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3ss-phy.yaml @@ -131,21 +131,13 @@ additionalProperties: false examples: - | - usb-glue@65b00000 { - compatible = "socionext,uniphier-ld20-dwc3-glue", - "simple-mfd"; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0 0x65b00000 0x400>; - - usb_ssphy0: ss-phy@300 { - compatible = "socionext,uniphier-ld20-usb3-ssphy"; - reg = <0x300 0x10>; - #phy-cells = <0>; - clock-names = "link", "phy"; - clocks = <&sys_clk 14>, <&sys_clk 16>; - reset-names = "link", "phy"; - resets = <&sys_rst 14>, <&sys_rst 16>; - vbus-supply = <&usb_vbus0>; - }; + usb_ssphy0: phy@300 { + compatible = "socionext,uniphier-ld20-usb3-ssphy"; + reg = <0x300 0x10>; + #phy-cells = <0>; + clock-names = "link", "phy"; + clocks = <&sys_clk 14>, <&sys_clk 16>; + reset-names = "link", "phy"; + resets = <&sys_rst 14>, <&sys_rst 16>; + vbus-supply = <&usb_vbus0>; }; diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mm-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/fsl,imx8m-pinctrl.yaml index 6717f163390b..7ae084397258 100644 --- a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mm-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx8m-pinctrl.yaml @@ -1,13 +1,13 @@ -# 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/pinctrl/fsl,imx8mm-pinctrl.yaml# +$id: http://devicetree.org/schemas/pinctrl/fsl,imx8m-pinctrl.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Freescale IMX8MM IOMUX Controller +title: Freescale IMX8M IOMUX Controller maintainers: - - Anson Huang <Anson.Huang@nxp.com> + - Peng Fan <peng.fan@nxp.com> description: Please refer to fsl,imx-pinctrl.txt and pinctrl-bindings.txt in this directory @@ -15,7 +15,11 @@ description: properties: compatible: - const: fsl,imx8mm-iomuxc + enum: + - fsl,imx8mm-iomuxc + - fsl,imx8mn-iomuxc + - fsl,imx8mp-iomuxc + - fsl,imx8mq-iomuxc reg: maxItems: 1 @@ -34,9 +38,10 @@ patternProperties: each entry consists of 6 integers and represents the mux and config setting for one pin. The first 5 integers <mux_reg conf_reg input_reg mux_val input_val> are specified using a PIN_FUNC_ID macro, which can - be found in <arch/arm64/boot/dts/freescale/imx8mm-pinfunc.h>. The last - integer CONFIG is the pad setting value like pull-up on this pin. Please - refer to i.MX8M Mini Reference Manual for detailed CONFIG settings. + be found in <arch/arm64/boot/dts/freescale/imx8m[m,n,p,q]-pinfunc.h>. + The last integer CONFIG is the pad setting value like pull-up on this + pin. Please refer to i.MX8M Mini/Nano/Plus/Quad Reference Manual for + detailed CONFIG settings. $ref: /schemas/types.yaml#/definitions/uint32-matrix items: items: @@ -51,7 +56,8 @@ patternProperties: - description: | "input_val" indicates the select input value to be applied. - description: | - "pad_setting" indicates the pad configuration value to be applied. + "pad_setting" indicates the pad configuration value to be + applied. required: - fsl,pins diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mn-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mn-pinctrl.yaml deleted file mode 100644 index b1cdbb56d4e4..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mn-pinctrl.yaml +++ /dev/null @@ -1,84 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/pinctrl/fsl,imx8mn-pinctrl.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Freescale IMX8MN IOMUX Controller - -maintainers: - - Anson Huang <Anson.Huang@nxp.com> - -description: - Please refer to fsl,imx-pinctrl.txt and pinctrl-bindings.txt in this directory - for common binding part and usage. - -properties: - compatible: - const: fsl,imx8mn-iomuxc - - reg: - maxItems: 1 - -# Client device subnode's properties -patternProperties: - 'grp$': - type: object - description: - Pinctrl node's client devices use subnodes for desired pin configuration. - Client device subnodes use below standard properties. - - properties: - fsl,pins: - description: - each entry consists of 6 integers and represents the mux and config - setting for one pin. The first 5 integers <mux_reg conf_reg input_reg - mux_val input_val> are specified using a PIN_FUNC_ID macro, which can - be found in <arch/arm64/boot/dts/freescale/imx8mn-pinfunc.h>. The last - integer CONFIG is the pad setting value like pull-up on this pin. Please - refer to i.MX8M Nano Reference Manual for detailed CONFIG settings. - $ref: /schemas/types.yaml#/definitions/uint32-matrix - items: - items: - - description: | - "mux_reg" indicates the offset of mux register. - - description: | - "conf_reg" indicates the offset of pad configuration register. - - description: | - "input_reg" indicates the offset of select input register. - - description: | - "mux_val" indicates the mux value to be applied. - - description: | - "input_val" indicates the select input value to be applied. - - description: | - "pad_setting" indicates the pad configuration value to be applied. - - required: - - fsl,pins - - additionalProperties: false - -allOf: - - $ref: "pinctrl.yaml#" - -required: - - compatible - - reg - -additionalProperties: false - -examples: - # Pinmux controller node - - | - iomuxc: pinctrl@30330000 { - compatible = "fsl,imx8mn-iomuxc"; - reg = <0x30330000 0x10000>; - - pinctrl_uart2: uart2grp { - fsl,pins = - <0x23C 0x4A4 0x4FC 0x0 0x0 0x140>, - <0x240 0x4A8 0x000 0x0 0x0 0x140>; - }; - }; - -... diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mp-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mp-pinctrl.yaml deleted file mode 100644 index 4eed3a4e153a..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mp-pinctrl.yaml +++ /dev/null @@ -1,84 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/pinctrl/fsl,imx8mp-pinctrl.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Freescale IMX8MP IOMUX Controller - -maintainers: - - Anson Huang <Anson.Huang@nxp.com> - -description: - Please refer to fsl,imx-pinctrl.txt and pinctrl-bindings.txt in this directory - for common binding part and usage. - -properties: - compatible: - const: fsl,imx8mp-iomuxc - - reg: - maxItems: 1 - -# Client device subnode's properties -patternProperties: - 'grp$': - type: object - description: - Pinctrl node's client devices use subnodes for desired pin configuration. - Client device subnodes use below standard properties. - - properties: - fsl,pins: - description: - each entry consists of 6 integers and represents the mux and config - setting for one pin. The first 5 integers <mux_reg conf_reg input_reg - mux_val input_val> are specified using a PIN_FUNC_ID macro, which can - be found in <arch/arm64/boot/dts/freescale/imx8mp-pinfunc.h>. The last - integer CONFIG is the pad setting value like pull-up on this pin. Please - refer to i.MX8M Plus Reference Manual for detailed CONFIG settings. - $ref: /schemas/types.yaml#/definitions/uint32-matrix - items: - items: - - description: | - "mux_reg" indicates the offset of mux register. - - description: | - "conf_reg" indicates the offset of pad configuration register. - - description: | - "input_reg" indicates the offset of select input register. - - description: | - "mux_val" indicates the mux value to be applied. - - description: | - "input_val" indicates the select input value to be applied. - - description: | - "pad_setting" indicates the pad configuration value to be applied. - - required: - - fsl,pins - - additionalProperties: false - -allOf: - - $ref: "pinctrl.yaml#" - -required: - - compatible - - reg - -additionalProperties: false - -examples: - # Pinmux controller node - - | - iomuxc: pinctrl@30330000 { - compatible = "fsl,imx8mp-iomuxc"; - reg = <0x30330000 0x10000>; - - pinctrl_uart2: uart2grp { - fsl,pins = - <0x228 0x488 0x5F0 0x0 0x6 0x49>, - <0x228 0x488 0x000 0x0 0x0 0x49>; - }; - }; - -... diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mq-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mq-pinctrl.yaml deleted file mode 100644 index d4a8ea5551a5..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mq-pinctrl.yaml +++ /dev/null @@ -1,84 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/pinctrl/fsl,imx8mq-pinctrl.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Freescale IMX8MQ IOMUX Controller - -maintainers: - - Anson Huang <Anson.Huang@nxp.com> - -description: - Please refer to fsl,imx-pinctrl.txt and pinctrl-bindings.txt in this directory - for common binding part and usage. - -properties: - compatible: - const: fsl,imx8mq-iomuxc - - reg: - maxItems: 1 - -# Client device subnode's properties -patternProperties: - 'grp$': - type: object - description: - Pinctrl node's client devices use subnodes for desired pin configuration. - Client device subnodes use below standard properties. - - properties: - fsl,pins: - description: - each entry consists of 6 integers and represents the mux and config - setting for one pin. The first 5 integers <mux_reg conf_reg input_reg - mux_val input_val> are specified using a PIN_FUNC_ID macro, which can - be found in <arch/arm64/boot/dts/freescale/imx8mq-pinfunc.h>. The last - integer CONFIG is the pad setting value like pull-up on this pin. Please - refer to i.MX8M Quad Reference Manual for detailed CONFIG settings. - $ref: /schemas/types.yaml#/definitions/uint32-matrix - items: - items: - - description: | - "mux_reg" indicates the offset of mux register. - - description: | - "conf_reg" indicates the offset of pad configuration register. - - description: | - "input_reg" indicates the offset of select input register. - - description: | - "mux_val" indicates the mux value to be applied. - - description: | - "input_val" indicates the select input value to be applied. - - description: | - "pad_setting" indicates the pad configuration value to be applied. - - required: - - fsl,pins - - additionalProperties: false - -allOf: - - $ref: "pinctrl.yaml#" - -required: - - compatible - - reg - -additionalProperties: false - -examples: - # Pinmux controller node - - | - iomuxc: pinctrl@30330000 { - compatible = "fsl,imx8mq-iomuxc"; - reg = <0x30330000 0x10000>; - - pinctrl_uart1: uart1grp { - fsl,pins = - <0x234 0x49C 0x4F4 0x0 0x0 0x49>, - <0x238 0x4A0 0x4F4 0x0 0x0 0x49>; - }; - }; - -... diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt65xx-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt65xx-pinctrl.yaml index 1b44335b1e94..a55c8e4ff26e 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt65xx-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt65xx-pinctrl.yaml @@ -70,11 +70,11 @@ allOf: - $ref: "pinctrl.yaml#" patternProperties: - '-[0-9]+$': + 'pins$': type: object additionalProperties: false patternProperties: - 'pins': + '(^pins|pins?$)': type: object additionalProperties: false description: | @@ -158,7 +158,7 @@ examples: <GIC_SPI 117 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 118 IRQ_TYPE_LEVEL_HIGH>; - i2c0_pins_a: i2c0-0 { + i2c0_pins_a: i2c0-pins { pins1 { pinmux = <MT8135_PIN_100_SDA0__FUNC_SDA0>, <MT8135_PIN_101_SCL0__FUNC_SCL0>; @@ -166,7 +166,7 @@ examples: }; }; - i2c1_pins_a: i2c1-0 { + i2c1_pins_a: i2c1-pins { pins { pinmux = <MT8135_PIN_195_SDA1__FUNC_SDA1>, <MT8135_PIN_196_SCL1__FUNC_SCL1>; @@ -174,7 +174,7 @@ examples: }; }; - i2c2_pins_a: i2c2-0 { + i2c2_pins_a: i2c2-pins { pins1 { pinmux = <MT8135_PIN_193_SDA2__FUNC_SDA2>; bias-pull-down; @@ -186,7 +186,7 @@ examples: }; }; - i2c3_pins_a: i2c3-0 { + i2c3_pins_a: i2c3-pins { pins1 { pinmux = <MT8135_PIN_40_DAC_CLK__FUNC_GPIO40>, <MT8135_PIN_41_DAC_WS__FUNC_GPIO41>; diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt7622-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt7622-pinctrl.yaml index c9ea0cad489b..ac93eb8f01a6 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt7622-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt7622-pinctrl.yaml @@ -61,11 +61,11 @@ then: - "#interrupt-cells" patternProperties: - '-[0-9]+$': + '-pins(-[a-z]+)?$': type: object additionalProperties: false patternProperties: - 'mux': + '^mux(-|$)': type: object additionalProperties: false description: | @@ -244,7 +244,7 @@ patternProperties: groups: enum: [wf0_2g, wf0_5g] - 'conf': + '^conf(-|$)': type: object additionalProperties: false description: | @@ -348,7 +348,7 @@ examples: gpio-controller; #gpio-cells = <2>; - pinctrl_eth_default: eth-0 { + pinctrl_eth_default: eth-pins { mux-mdio { groups = "mdc_mdio"; function = "eth"; diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt7981-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt7981-pinctrl.yaml new file mode 100644 index 000000000000..74c66fbcb2ae --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt7981-pinctrl.yaml @@ -0,0 +1,475 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/mediatek,mt7981-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mediatek MT7981 Pin Controller + +maintainers: + - Daniel Golle <daniel@makrotopia.org> + +description: + The MediaTek's MT7981 Pin controller is used to control SoC pins. + +properties: + compatible: + enum: + - mediatek,mt7981-pinctrl + + reg: + minItems: 9 + maxItems: 9 + + reg-names: + items: + - const: gpio + - const: iocfg_rt + - const: iocfg_rm + - const: iocfg_rb + - const: iocfg_lb + - const: iocfg_bl + - const: iocfg_tm + - const: iocfg_tl + - const: eint + + gpio-controller: true + + "#gpio-cells": + const: 2 + description: > + Number of cells in GPIO specifier. Since the generic GPIO binding is used, + the amount of cells must be specified as 2. See the below mentioned gpio + binding representation for description of particular cells. + + gpio-ranges: + minItems: 1 + maxItems: 5 + description: GPIO valid number range. + + interrupt-controller: true + + interrupts: + maxItems: 1 + + "#interrupt-cells": + const: 2 + +allOf: + - $ref: pinctrl.yaml# + +required: + - compatible + - reg + - reg-names + - gpio-controller + - "#gpio-cells" + +patternProperties: + '-pins$': + type: object + additionalProperties: false + + patternProperties: + '^.*mux.*$': + type: object + additionalProperties: false + description: | + pinmux configuration nodes. + + The following table shows the effective values of "group", "function" + properties and chip pinout pins + + groups function pins (in pin#) + --------------------------------------------------------------------- + "wa_aice1" "wa_aice" 0, 1 + "wa_aice2" "wa_aice" 0, 1 + "wm_uart_0" "uart" 0, 1 + "dfd" "dfd" 0, 1, 4, 5 + "watchdog" "watchdog" 2 + "pcie_pereset" "pcie" 3 + "jtag" "jtag" 4, 5, 6, 7, 8 + "wm_jtag_0" "jtag" 4, 5, 6, 7, 8 + "wo0_jtag_0" "jtag" 9, 10, 11, 12, 13 + "uart2_0" "uart" 4, 5, 6, 7 + "gbe_led0" "led" 8 + "pta_ext_0" "pta" 4, 5, 6 + "pwm2" "pwm" 7 + "net_wo0_uart_txd_0" "uart" 8 + "spi1_0" "spi" 4, 5, 6, 7 + "i2c0_0" "i2c" 6, 7 + "dfd_ntrst" "dfd" 8 + "wm_aice1" "wa_aice" 9, 10 + "pwm0_0" "pwm" 13 + "pwm0_1" "pwm" 15 + "pwm1_0" "pwm" 14 + "pwm1_1" "pwm" 15 + "net_wo0_uart_txd_1" "uart" 14 + "net_wo0_uart_txd_2" "uart" 15 + "gbe_led1" "led" 13 + "pcm" "pcm" 9, 10, 11, 12, 13, 25 + "watchdog1" "watchdog" 13 + "udi" "udi" 9, 10, 11, 12, 13 + "drv_vbus" "usb" 14 + "emmc_45" "flash" 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25 + "snfi" "flash" 16, 17, 18, 19, 20, 21 + "spi0" "spi" 16, 17, 18, 19 + "spi0_wp_hold" "spi" 20, 21 + "spi1_1" "spi" 22, 23, 24, 25 + "spi2" "spi" 26, 27, 28, 29 + "spi2_wp_hold" "spi" 30, 31 + "uart1_0" "uart" 16, 17, 18, 19 + "uart1_1" "uart" 26, 27, 28, 29 + "uart2_1" "uart" 22, 23, 24, 25 + "pta_ext_1" "pta" 22, 23, 24 + "wm_aurt_1" "uart" 20, 21 + "wm_aurt_2" "uart" 30, 31 + "wm_jtag_1" "jtag" 20, 21, 22, 23, 24 + "wo0_jtag_1" "jtag" 25, 26, 27, 28, 29 + "wa_aice3" "wa_aice" 28, 20 + "wm_aice2" "wa_aice" 30, 31 + "i2c0_1" "i2c" 30, 31 + "u2_phy_i2c" "i2c" 30, 31 + "uart0" "uart" 32, 33 + "sgmii1_phy_i2c" "i2c" 32, 33 + "u3_phy_i2c" "i2c" 32, 33 + "sgmii0_phy_i2c" "i2c" 32, 33 + "pcie_clk" "pcie" 34 + "pcie_wake" "pcie" 35 + "i2c0_2" "i2c" 36, 37 + "smi_mdc_mdio" "eth" 36, 37 + "gbe_ext_mdc_mdio" "eth" 36, 37 + "wf0_mode1" "eth" 40, 41, 42, 43, 44, 45, 46, 47, 48, + 49, 50, 51, 52, 53, 54, 55, 56 + + "wf0_mode3" "eth" 45, 46, 47, 48, 49, 51 + "wf2g_led0" "led" 30 + "wf2g_led1" "led" 34 + "wf5g_led0" "led" 31 + "wf5g_led1" "led" 35 + "mt7531_int" "eth" 38 + "ant_sel" "ant" 14, 15, 16, 17, 18, 19, 20, 21, 22 + 23, 24, 25, 34, 35 + + $ref: /schemas/pinctrl/pinmux-node.yaml + properties: + function: + description: + A string containing the name of the function to mux to the group. + enum: [wa_aice, dfd, jtag, pta, pcm, udi, usb, ant, eth, i2c, led, + pwm, spi, uart, watchdog, flash, pcie] + groups: + description: + An array of strings. Each string contains the name of a group. + + required: + - function + - groups + + allOf: + - if: + properties: + function: + const: wa_aice + then: + properties: + groups: + enum: [wa_aice1, wa_aice2, wm_aice1_1, wa_aice3, wm_aice1_2] + - if: + properties: + function: + const: dfd + then: + properties: + groups: + enum: [dfd, dfd_ntrst] + - if: + properties: + function: + const: jtag + then: + properties: + groups: + enum: [jtag, wm_jtag_0, wo0_jtag_0, wo0_jtag_1, wm_jtag_1] + - if: + properties: + function: + const: pta + then: + properties: + groups: + enum: [pta_ext_0, pta_ext_1] + - if: + properties: + function: + const: pcm + then: + properties: + groups: + enum: [pcm] + - if: + properties: + function: + const: udi + then: + properties: + groups: + enum: [udi] + - if: + properties: + function: + const: usb + then: + properties: + groups: + enum: [drv_vbus] + - if: + properties: + function: + const: ant + then: + properties: + groups: + enum: [ant_sel] + - if: + properties: + function: + const: eth + then: + properties: + groups: + enum: [smi_mdc_mdio, gbe_ext_mdc_mdio, wf0_mode1, wf0_mode3, + mt7531_int] + - if: + properties: + function: + const: i2c + then: + properties: + groups: + enum: [i2c0_0, i2c0_1, u2_phy_i2c, sgmii1_phy_i2c, u3_phy_i2c, + sgmii0_phy_i2c, i2c0_2] + - if: + properties: + function: + const: led + then: + properties: + groups: + enum: [gbe_led0, gbe_led1, wf2g_led0, wf2g_led1, wf5g_led0, wf5g_led1] + - if: + properties: + function: + const: pwm + then: + properties: + groups: + items: + enum: [pwm2, pwm0_0, pwm0_1, pwm1_0, pwm1_1] + maxItems: 3 + - if: + properties: + function: + const: spi + then: + properties: + groups: + items: + enum: [spi1_0, spi0, spi0_wp_hold, spi1_1, spi2, spi2_wp_hold] + maxItems: 4 + - if: + properties: + function: + const: uart + then: + properties: + groups: + items: + enum: [wm_uart_0, uart2_0, net_wo0_uart_txd_0, + net_wo0_uart_txd_1, net_wo0_uart_txd_2, uart1_0, + uart1_1, uart2_1, wm_aurt_1, wm_aurt_2, uart0] + - if: + properties: + function: + const: watchdog + then: + properties: + groups: + enum: [watchdog] + - if: + properties: + function: + const: flash + then: + properties: + groups: + items: + enum: [emmc_45, snfi] + maxItems: 1 + - if: + properties: + function: + const: pcie + then: + properties: + groups: + items: + enum: [pcie_clk, pcie_wake, pcie_pereset] + maxItems: 3 + + '^.*conf.*$': + type: object + additionalProperties: false + description: pinconf configuration nodes. + $ref: /schemas/pinctrl/pincfg-node.yaml + + properties: + pins: + description: + An array of strings. Each string contains the name of a pin. + items: + enum: [GPIO_WPS, GPIO_RESET, SYS_WATCHDOG, PCIE_PERESET_N, + JTAG_JTDO, JTAG_JTDI, JTAG_JTMS, JTAG_JTCLK, JTAG_JTRST_N, + WO_JTAG_JTDO, WO_JTAG_JTDI, WO_JTAG_JTMS, WO_JTAG_JTCLK, + WO_JTAG_JTRST_N, USB_VBUS, PWM0, SPI0_CLK, SPI0_MOSI, + SPI0_MISO, SPI0_CS, SPI0_HOLD, SPI0_WP, SPI1_CLK, SPI1_MOSI, + SPI1_MISO, SPI1_CS, SPI2_CLK, SPI2_MOSI, SPI2_MISO, SPI2_CS, + SPI2_HOLD, SPI2_WP, UART0_RXD, UART0_TXD, PCIE_CLK_REQ, + PCIE_WAKE_N, SMI_MDC, SMI_MDIO, GBE_INT, GBE_RESET, + WF_DIG_RESETB, WF_CBA_RESETB, WF_XO_REQ, WF_TOP_CLK, + WF_TOP_DATA, WF_HB1, WF_HB2, WF_HB3, WF_HB4, WF_HB0, + WF_HB0_B, WF_HB5, WF_HB6, WF_HB7, WF_HB8, WF_HB9, WF_HB10] + maxItems: 57 + + bias-disable: true + + bias-pull-up: + oneOf: + - type: boolean + description: normal pull up. + - enum: [100, 101, 102, 103] + description: > + PUPD/R1/R0 pull down type. See MTK_PUPD_SET_R1R0 defines in + dt-bindings/pinctrl/mt65xx.h. + + bias-pull-down: + oneOf: + - type: boolean + description: normal pull down. + - enum: [100, 101, 102, 103] + description: > + PUPD/R1/R0 pull down type. See MTK_PUPD_SET_R1R0 defines in + dt-bindings/pinctrl/mt65xx.h. + + input-enable: true + + input-disable: true + + output-enable: true + + output-low: true + + output-high: true + + input-schmitt-enable: true + + input-schmitt-disable: true + + drive-strength: + enum: [2, 4, 6, 8, 10, 12, 14, 16] + + 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 + 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. + 2: (R1, R0) = (1, 0) which means R1 enabled and R0 disabled. + 3: (R1, R0) = (1, 1) which means R1 enabled and R0 enabled. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + + 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 + 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. + 2: (R1, R0) = (1, 0) which means R1 enabled and R0 disabled. + 3: (R1, R0) = (1, 1) which means R1 enabled and R0 enabled. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + + required: + - pins + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/pinctrl/mt65xx.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + pio: pinctrl@11d00000 { + compatible = "mediatek,mt7981-pinctrl"; + reg = <0 0x11d00000 0 0x1000>, + <0 0x11c00000 0 0x1000>, + <0 0x11c10000 0 0x1000>, + <0 0x11d20000 0 0x1000>, + <0 0x11e00000 0 0x1000>, + <0 0x11e20000 0 0x1000>, + <0 0x11f00000 0 0x1000>, + <0 0x11f10000 0 0x1000>, + <0 0x1000b000 0 0x1000>; + reg-names = "gpio", "iocfg_rt", "iocfg_rm", + "iocfg_rb", "iocfg_lb", "iocfg_bl", + "iocfg_tm", "iocfg_tl", "eint"; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&pio 0 0 56>; + interrupt-controller; + interrupts = <GIC_SPI 225 IRQ_TYPE_LEVEL_HIGH>; + interrupt-parent = <&gic>; + #interrupt-cells = <2>; + + mdio_pins: mdio-pins { + mux { + function = "eth"; + groups = "smi_mdc_mdio"; + }; + }; + + spi0_flash_pins: spi0-pins { + mux { + function = "spi"; + groups = "spi0", "spi0_wp_hold"; + }; + + conf-pu { + pins = "SPI0_CS", "SPI0_HOLD", "SPI0_WP"; + drive-strength = <MTK_DRIVE_8mA>; + bias-pull-up = <MTK_PUPD_SET_R1R0_11>; + }; + + conf-pd { + pins = "SPI0_CLK", "SPI0_MOSI", "SPI0_MISO"; + drive-strength = <MTK_DRIVE_8mA>; + bias-pull-down = <MTK_PUPD_SET_R1R0_11>; + }; + }; + + pcie_pins: pcie-pins { + mux { + function = "pcie"; + groups = "pcie_clk", "pcie_wake", "pcie_pereset"; + }; + }; + + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt8183-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt8183-pinctrl.yaml index 0d2484056a0f..c30cd0d010dd 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt8183-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt8183-pinctrl.yaml @@ -67,11 +67,11 @@ required: - gpio-ranges patternProperties: - '-[0-9]+$': + '-pins(-[a-z]+)?$': type: object additionalProperties: false patternProperties: - 'pins': + '^pins': type: object additionalProperties: false description: | @@ -210,7 +210,7 @@ examples: interrupts = <GIC_SPI 177 IRQ_TYPE_LEVEL_HIGH>; #interrupt-cells = <2>; - i2c0_pins_a: i2c-0 { + i2c0_pins_a: i2c0-pins { pins1 { pinmux = <PINMUX_GPIO48__FUNC_SCL5>, <PINMUX_GPIO49__FUNC_SDA5>; @@ -219,7 +219,7 @@ examples: }; }; - i2c1_pins_a: i2c-1 { + i2c1_pins_a: i2c1-pins { pins { pinmux = <PINMUX_GPIO50__FUNC_SCL3>, <PINMUX_GPIO51__FUNC_SDA3>; diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt8365-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt8365-pinctrl.yaml new file mode 100644 index 000000000000..4b96884a1afc --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt8365-pinctrl.yaml @@ -0,0 +1,197 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/mediatek,mt8365-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mediatek MT8365 Pin Controller + +maintainers: + - Zhiyong Tao <zhiyong.tao@mediatek.com> + - Bernhard Rosenkränzer <bero@baylibre.com> + +description: | + The MediaTek's MT8365 Pin controller is used to control SoC pins. + +properties: + compatible: + const: mediatek,mt8365-pinctrl + + reg: + maxItems: 1 + + mediatek,pctl-regmap: + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + maxItems: 1 + minItems: 1 + maxItems: 2 + description: | + Should be phandles of the syscfg node. + + gpio-controller: true + + "#gpio-cells": + const: 2 + description: | + Number of cells in GPIO specifier. Since the generic GPIO + binding is used, the amount of cells must be specified as 2. See the below + mentioned gpio binding representation for description of particular cells. + + interrupt-controller: true + + interrupts: + maxItems: 1 + + "#interrupt-cells": + const: 2 + +patternProperties: + "-pins$": + type: object + additionalProperties: false + patternProperties: + "pins$": + type: object + additionalProperties: false + description: | + A pinctrl node should contain at least one subnode representing the + pinctrl groups available on the machine. Each subnode will list the + pins it needs, and how they should be configured, with regard to muxer + configuration, pullups, drive strength, input enable/disable and input + schmitt. + $ref: /schemas/pinctrl/pincfg-node.yaml + + properties: + pinmux: + description: + integer array, represents gpio pin number and mux setting. + Supported pin number and mux varies for different SoCs, and are + defined as macros in <soc>-pinfunc.h directly. + + bias-disable: true + + bias-pull-up: + description: | + Besides generic pinconfig options, it can be used as the pull up + settings for 2 pull resistors, R0 and R1. User can configure those + special pins. + + bias-pull-down: true + + input-enable: true + + input-disable: true + + output-low: true + + output-high: true + + input-schmitt-enable: true + + input-schmitt-disable: true + + mediatek,drive-strength-adv: + description: | + Describe the specific driving setup property. + For I2C pins, the existing generic driving setup can only support + 2/4/6/8/10/12/14/16mA driving. But in specific driving setup, they + can support 0.125/0.25/0.5/1mA adjustment. If we enable specific + driving setup, the existing generic setup will be disabled. + The specific driving setup is controlled by E1E0EN. + When E1=0/E0=0, the strength is 0.125mA. + When E1=0/E0=1, the strength is 0.25mA. + When E1=1/E0=0, the strength is 0.5mA. + When E1=1/E0=1, the strength is 1mA. + EN is used to enable or disable the specific driving setup. + Valid arguments are described as below: + 0: (E1, E0, EN) = (0, 0, 0) + 1: (E1, E0, EN) = (0, 0, 1) + 2: (E1, E0, EN) = (0, 1, 0) + 3: (E1, E0, EN) = (0, 1, 1) + 4: (E1, E0, EN) = (1, 0, 0) + 5: (E1, E0, EN) = (1, 0, 1) + 6: (E1, E0, EN) = (1, 1, 0) + 7: (E1, E0, EN) = (1, 1, 1) + So the valid arguments are from 0 to 7. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3, 4, 5, 6, 7] + + mediatek,pull-up-adv: + description: | + Pull up setings 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. + 1: (R1, R0) = (0, 1) which means R1 disabled and R0 enabled. + 2: (R1, R0) = (1, 0) which means R1 enabled and R0 disabled. + 3: (R1, R0) = (1, 1) which means R1 enabled and R0 enabled. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + + mediatek,pull-down-adv: + description: | + Pull down 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. + 1: (R1, R0) = (0, 1) which means R1 disabled and R0 enabled. + 2: (R1, R0) = (1, 0) which means R1 enabled and R0 disabled. + 3: (R1, R0) = (1, 1) which means R1 enabled and R0 enabled. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + + mediatek,tdsel: + description: | + An integer describing the steps for output level shifter duty + cycle when asserted (high pulse width adjustment). Valid arguments + are from 0 to 15. + $ref: /schemas/types.yaml#/definitions/uint32 + + mediatek,rdsel: + description: | + An integer describing the steps for input level shifter duty cycle + when asserted (high pulse width adjustment). Valid arguments are + from 0 to 63. + $ref: /schemas/types.yaml#/definitions/uint32 + + required: + - pinmux + +required: + - compatible + - reg + - gpio-controller + - "#gpio-cells" + +allOf: + - $ref: pinctrl.yaml# + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/pinctrl/mt8365-pinfunc.h> + soc { + #address-cells = <2>; + #size-cells = <2>; + + pio: pinctrl@1000b000 { + compatible = "mediatek,mt8365-pinctrl"; + reg = <0 0x1000b000 0 0x1000>; + mediatek,pctl-regmap = <&syscfg_pctl>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 115 IRQ_TYPE_LEVEL_HIGH>; + + pio-pins { + pins { + pinmux = <MT8365_PIN_59_SDA1__FUNC_SDA1_0>, <MT8365_PIN_60_SCL1__FUNC_SCL1_0>; + mediatek,pull-up-adv = <3>; + mediatek,drive-strength-adv = <00>; + bias-pull-up; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,ipq5332-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,ipq5332-tlmm.yaml new file mode 100644 index 000000000000..300747252a7b --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,ipq5332-tlmm.yaml @@ -0,0 +1,134 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,ipq5332-tlmm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm IPQ5332 TLMM pin controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: | + Top Level Mode Multiplexer pin controller in Qualcomm IPQ5332 SoC. + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +properties: + compatible: + const: qcom,ipq5332-tlmm + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 27 + + gpio-line-names: + maxItems: 53 + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-ipq5332-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-ipq5332-tlmm-state" + additionalProperties: false + +$defs: + qcom-ipq5332-tlmm-state: + type: object + description: + Pinctrl node's client devices use subnodes for desired pin configuration. + Client device subnodes use below standard properties. + $ref: qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state + + properties: + pins: + description: + List of gpio pins affected by the properties specified in this + subnode. + items: + pattern: "^gpio([0-9]|[1-4][0-9]|5[0-2])$" + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ atest_char, atest_char0, atest_char1, atest_char2, atest_char3, + atest_tic, audio_pri, audio_pri0, audio_pri1, audio_sec, + audio_sec0, audio_sec1, blsp0_i2c, blsp0_spi, blsp0_uart0, + blsp0_uart1, blsp1_i2c0, blsp1_i2c1, blsp1_spi0, blsp1_spi1, + blsp1_uart0, blsp1_uart1, blsp1_uart2, blsp2_i2c0, blsp2_i2c1, + blsp2_spi, blsp2_spi0, blsp2_spi1, core_voltage, cri_trng0, + cri_trng1, cri_trng2, cri_trng3, cxc_clk, cxc_data, dbg_out, + gcc_plltest, gcc_tlmm, gpio, lock_det, mac0, mac1, mdc0, mdc1, + mdio0, mdio1, pc, pcie0_clk, pcie0_wake, pcie1_clk, pcie1_wake, + pcie2_clk, pcie2_wake, pll_test, prng_rosc0, prng_rosc1, + prng_rosc2, prng_rosc3, pta, pwm0, pwm1, pwm2, pwm3, + qdss_cti_trig_in_a0, qdss_cti_trig_in_a1, qdss_cti_trig_in_b0, + qdss_cti_trig_in_b1, qdss_cti_trig_out_a0, + qdss_cti_trig_out_a1, qdss_cti_trig_out_b0, + qdss_cti_trig_out_b1, qdss_traceclk_a, qdss_traceclk_b, + qdss_tracectl_a, qdss_tracectl_b, qdss_tracedata_a, + qdss_tracedata_b, qspi_data, qspi_clk, qspi_cs, resout, rx0, + rx1, sdc_data, sdc_clk, sdc_cmd, tsens_max, wci_txd, wci_rxd, + wsi_clk, wsi_clk3, wsi_data, wsi_data3, wsis_reset, xfem ] + + bias-pull-down: true + bias-pull-up: true + bias-disable: true + drive-strength: true + input-enable: true + output-high: true + output-low: true + + required: + - pins + + additionalProperties: false + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + tlmm: pinctrl@1000000 { + compatible = "qcom,ipq5332-tlmm"; + reg = <0x01000000 0x300000>; + gpio-controller; + #gpio-cells = <0x2>; + gpio-ranges = <&tlmm 0 0 53>; + interrupts = <GIC_SPI 249 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <0x2>; + + serial0-state { + pins = "gpio18", "gpio19"; + function = "blsp0_uart0"; + drive-strength = <8>; + bias-pull-up; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,ipq6018-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,ipq6018-pinctrl.yaml index 93f231c7a3b4..28f1b6a07b70 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,ipq6018-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,ipq6018-pinctrl.yaml @@ -19,7 +19,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.yaml index 5687acaf19bf..3137db927fc0 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.yaml @@ -20,7 +20,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-tlmm.yaml index a0a12171b6d0..96b598bf9a76 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-tlmm.yaml @@ -22,7 +22,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.yaml index a4f6e4c588f4..c7c94d742ed2 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.yaml @@ -20,7 +20,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true '#interrupt-cells': true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml index 3b79f5be860b..6cb667fa8665 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml @@ -20,7 +20,9 @@ properties: description: Specifies the base address and size of the TLMM register space maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true @@ -54,7 +56,7 @@ $defs: subnode. items: oneOf: - - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-1][0-6])$" + - pattern: "^gpio([0-9]|[1-9][0-9]|10[0-9]|11[0-6])$" - enum: [ sdc1_clk, sdc1_cmd, sdc1_data, sdc2_clk, sdc2_cmd, sdc2_data ] minItems: 1 maxItems: 36 @@ -66,8 +68,8 @@ $defs: enum: [ gpio, cci_i2c0, blsp_uim1, blsp_uim2, blsp_uim3, blsp_uim5, blsp_i2c1, blsp_i2c2, blsp_i2c3, blsp_i2c4, blsp_i2c5, blsp_spi1, blsp_spi2, blsp_spi3, blsp_spi5, blsp_uart1, blsp_uart2, - blsp_uart3, blsp_uart4, blsp_uart5, cam_mclk0, cam_mclk1, sdc3, - wlan ] + blsp_uart3, blsp_uart4, blsp_uart5, cam_mclk0, cam_mclk1, + gp0_clk, gp1_clk, sdc3, wlan ] bias-pull-down: true bias-pull-up: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8660-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8660-pinctrl.yaml index ad0cad4694c0..348d84c3cd21 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8660-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8660-pinctrl.yaml @@ -20,7 +20,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8909-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8909-tlmm.yaml index cc6d0c9c5100..85082adc1811 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8909-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8909-tlmm.yaml @@ -22,7 +22,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true @@ -61,7 +63,7 @@ $defs: subnode. items: oneOf: - - pattern: "^gpio([0-9]|[1-9][0-9]|10[0-9]|11[0-7])$" + - pattern: "^gpio([0-9]|[1-9][0-9]|10[0-9]|11[0-2])$" - enum: [ sdc1_clk, sdc1_cmd, sdc1_data, sdc2_clk, sdc2_cmd, sdc2_data, qdsd_clk, qdsd_cmd, qdsd_data0, qdsd_data1, qdsd_data2, qdsd_data3 ] @@ -125,7 +127,7 @@ examples: interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; gpio-controller; #gpio-cells = <2>; - gpio-ranges = <&tlmm 0 0 117>; + gpio-ranges = <&tlmm 0 0 113>; interrupt-controller; #interrupt-cells = <2>; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.yaml index 5495f58905af..633c9e5ed49e 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.yaml @@ -20,7 +20,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8953-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8953-pinctrl.yaml index c9a4a79e8d01..ce219827ccc8 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8953-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8953-pinctrl.yaml @@ -19,7 +19,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true @@ -51,7 +53,7 @@ $defs: subnode. items: oneOf: - - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-7][0-9])$" + - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-3][0-9]|14[01])$" - enum: [ sdc1_clk, sdc1_cmd, sdc1_data, sdc1_rclk, sdc2_clk, sdc2_cmd, sdc2_data, qdsd_clk, qdsd_cmd, qdsd_data0, qdsd_data1, qdsd_data2, qdsd_data3 ] diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.yaml index 33d07d531273..cf386f644ccb 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.yaml @@ -20,7 +20,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.yaml index 9287cbbff711..afe4a80f0b79 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.yaml @@ -20,7 +20,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8976-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8976-pinctrl.yaml index 858f45710fe2..5dfcc3eadbb0 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8976-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8976-pinctrl.yaml @@ -20,7 +20,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.yaml index 55d5439c6c24..0c4936fc35ef 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.yaml @@ -22,7 +22,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true @@ -32,10 +34,10 @@ properties: gpio-reserved-ranges: minItems: 1 - maxItems: 75 + maxItems: 73 gpio-line-names: - maxItems: 150 + maxItems: 146 patternProperties: "-state$": @@ -61,7 +63,7 @@ $defs: subnode. items: oneOf: - - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-4][0-9])$" + - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-3][0-9]|14[0-5])$" - enum: [ sdc1_clk, sdc1_cmd, sdc1_data, sdc1_rclk, sdc2_clk, sdc2_cmd, sdc2_data, sdc3_clk, sdc3_cmd, sdc3_data ] minItems: 1 diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.yaml index 8e1cd4ba1116..047b4584e3c0 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.yaml @@ -20,7 +20,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.yaml index 21ba32cc204a..c07ee9868046 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.yaml @@ -20,7 +20,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml index 29dd503f9522..db505fdeac86 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml @@ -40,6 +40,10 @@ properties: - qcom,pm8350b-gpio - qcom,pm8350c-gpio - qcom,pm8450-gpio + - qcom,pm8550-gpio + - qcom,pm8550b-gpio + - qcom,pm8550ve-gpio + - qcom,pm8550vs-gpio - qcom,pm8916-gpio - qcom,pm8917-gpio - qcom,pm8921-gpio @@ -52,10 +56,12 @@ properties: - qcom,pmi8994-gpio - qcom,pmi8998-gpio - qcom,pmk8350-gpio + - qcom,pmk8550-gpio - qcom,pmm8155au-gpio - qcom,pmp8074-gpio - qcom,pmr735a-gpio - qcom,pmr735b-gpio + - qcom,pmr735d-gpio - qcom,pms405-gpio - qcom,pmx55-gpio - qcom,pmx65-gpio @@ -111,6 +117,7 @@ allOf: enum: - qcom,pm8008-gpio - qcom,pmi8950-gpio + - qcom,pmr735d-gpio then: properties: gpio-line-names: @@ -146,6 +153,8 @@ allOf: enum: - qcom,pm8018-gpio - qcom,pm8019-gpio + - qcom,pm8550vs-gpio + - qcom,pmk8550-gpio then: properties: gpio-line-names: @@ -162,6 +171,7 @@ allOf: enum: - qcom,pm8226-gpio - qcom,pm8350b-gpio + - qcom,pm8550ve-gpio - qcom,pm8950-gpio then: properties: @@ -236,6 +246,8 @@ allOf: - qcom,pm8038-gpio - qcom,pm8150b-gpio - qcom,pm8150l-gpio + - qcom,pm8550-gpio + - qcom,pm8550b-gpio - qcom,pmc8180c-gpio - qcom,pmp8074-gpio - qcom,pms405-gpio @@ -411,6 +423,10 @@ $defs: - gpio1-gpio8 for pm8350b - gpio1-gpio9 for pm8350c - gpio1-gpio4 for pm8450 + - gpio1-gpio12 for pm8550 + - gpio1-gpio12 for pm8550b + - gpio1-gpio8 for pm8550ve + - gpio1-gpio6 for pm8550vs - gpio1-gpio38 for pm8917 - gpio1-gpio44 for pm8921 - gpio1-gpio36 for pm8941 @@ -421,10 +437,12 @@ $defs: - gpio1-gpio2 for pmi8950 - gpio1-gpio10 for pmi8994 - gpio1-gpio4 for pmk8350 + - gpio1-gpio6 for pmk8550 - gpio1-gpio10 for pmm8155au - gpio1-gpio12 for pmp8074 (holes on gpio1 and gpio12) - gpio1-gpio4 for pmr735a - gpio1-gpio4 for pmr735b + - gpio1-gpio2 for pmr735d - gpio1-gpio12 for pms405 (holes on gpio1, gpio9 and gpio10) - gpio1-gpio11 for pmx55 (holes on gpio3, gpio7, gpio10 diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.yaml index 72cce38bc1ce..9412b9362328 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.yaml @@ -74,7 +74,7 @@ patternProperties: oneOf: - $ref: "#/$defs/qcom-pmic-mpp-state" - patternProperties: - "mpp": + '-pins$': $ref: "#/$defs/qcom-pmic-mpp-state" additionalProperties: false @@ -179,7 +179,7 @@ examples: }; default-state { - gpio-mpp { + gpio-pins { pins = "mpp1", "mpp2", "mpp3", "mpp4"; function = "digital"; input-enable; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,qcm2290-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,qcm2290-tlmm.yaml index adf64bfaa4ed..6271fd15e0b6 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,qcm2290-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,qcm2290-tlmm.yaml @@ -19,7 +19,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.yaml index 29d50c4a0034..20bc967a17b5 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.yaml @@ -26,7 +26,9 @@ properties: - const: north - const: east - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,qdu1000-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,qdu1000-tlmm.yaml new file mode 100644 index 000000000000..7e5fb9a6e7d3 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,qdu1000-tlmm.yaml @@ -0,0 +1,134 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,qdu1000-tlmm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. QDU1000/QRU1000 TLMM block + +maintainers: + - Melody Olvera <quic_molvera@quicinc.com> + +description: | + Top Level Mode Multiplexer pin controller found in the QDU1000 and + QRU1000 SoCs. + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +properties: + compatible: + const: qcom,qdu1000-tlmm + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 76 + + gpio-line-names: + maxItems: 151 + + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-qdu1000-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-qdu1000-tlmm-state" + additionalProperties: false + +$defs: + qcom-qdu1000-tlmm-state: + type: object + description: + Pinctrl node's client devices use subnodes for desired pin configuration. + Client device subnodes use below standard properties. + $ref: qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state + + properties: + pins: + description: + List of gpio pins affected by the properties specified in this + subnode. + items: + oneOf: + - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-4][0-9]|150)$" + - enum: [ sdc1_rclk, sdc1_clk, sdc1_cmd, sdc1_data ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + enum: [ atest_char, atest_usb, char_exec, CMO_PRI, cmu_rng, + dbg_out_clk, ddr_bist, ddr_pxi1, ddr_pxi2, ddr_pxi3, ddr_pxi4, + ddr_pxi5, ddr_pxi6, ddr_pxi7, eth012_int_n, eth345_int_n, + gcc_gp1, gcc_gp2, gcc_gp3, gpio, gps_pps_in, hardsync_pps_in, + intr_c, jitter_bist_ref, pcie_clkreqn, phase_flag, pll_bist, + pll_clk, prng_rosc, qdss_cti, qdss_gpio, qlink0_enable, + qlink0_request, qlink0_wmss, qlink1_enable, qlink1_request, + qlink1_wmss, qlink2_enable, qlink2_request, qlink2_wmss, + qlink3_enable, qlink3_request, qlink3_wmss, qlink4_enable, + qlink4_request, qlink4_wmss, qlink5_enable, qlink5_request, + qlink5_wmss, qlink6_enable, qlink6_request, qlink6_wmss, + qlink7_enable, qlink7_request, qlink7_wmss, qspi_clk, qspi_cs, + qspi0, qspi1, qspi2, qspi3, qup00, qup01, qup02, qup03, qup04, + qup05, qup06, qup07, qup08, qup10, qup11, qup12, qup13, qup14, + qup15, qup16, qup17, qup20, qup21, qup22, SI5518_INT, smb_alert, + smb_clk, smb_dat, tb_trig, tgu_ch0, tgu_ch1, tgu_ch2, tgu_ch3, + tgu_ch4, tgu_ch5, tgu_ch6, tgu_ch7, tmess_prng0, tmess_prng1, + tmess_prng2, tmess_prng3, tod_pps_in, tsense_pwm1, tsense_pwm2, + usb2phy_ac, usb_con_det, usb_dfp_en, usb_phy, vfr_0, vfr_1, + vsense_trigger ] + + bias-disable: true + bias-pull-down: true + bias-pull-up: true + drive-strength: true + input-enable: true + output-high: true + output-low: true + + required: + - pins + + additionalProperties: false + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + pinctrl@f000000 { + compatible = "qcom,qdu1000-tlmm"; + reg = <0xf000000 0x1000000>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-ranges = <&tlmm 0 0 151>; + wakeup-parent = <&pdc>; + + uart0-default-state { + pins = "gpio6", "gpio7", "gpio8", "gpio9"; + function = "qup00"; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sa8775p-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sa8775p-tlmm.yaml new file mode 100644 index 000000000000..70d9106ad83d --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sa8775p-tlmm.yaml @@ -0,0 +1,138 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,sa8775p-tlmm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. SA8775P TLMM block + +maintainers: + - Bartosz Golaszewski <bartosz.golaszewski@linaro.org> + +description: | + Top Level Mode Multiplexer pin controller in Qualcomm SA8775P SoC. + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +properties: + compatible: + const: qcom,sa8775p-tlmm + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + "#gpio-cells": true + gpio-ranges: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 74 + + gpio-line-names: + maxItems: 148 + +required: + - compatible + - reg + +additionalProperties: false + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-sa8775p-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sa8775p-tlmm-state" + additionalProperties: false + +$defs: + qcom-sa8775p-tlmm-state: + type: object + description: + Pinctrl node's client devices use subnodes for desired pin configuration. + Client device subnodes use below standard properties. + $ref: qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state + + properties: + pins: + description: + List of gpio pins affected by the properties specified in this + subnode. + items: + oneOf: + - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-3][0-9]|14[0-7])$" + - enum: [ sdc1_clk, sdc1_cmd, sdc1_data, sdc1_rclk, ufs_reset ] + minItems: 1 + maxItems: 16 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ atest_char, atest_usb2, audio_ref, cam_mclk, cci_async, cci_i2c, + cci_timer0, cci_timer1, cci_timer2, cci_timer3, cci_timer4, + cci_timer5, cci_timer6, cci_timer7, cci_timer8, cci_timer9, + cri_trng, cri_trng0, cri_trng1, dbg_out, ddr_bist, ddr_pxi0, + ddr_pxi1, ddr_pxi2, ddr_pxi3, ddr_pxi4, ddr_pxi5, edp0_hot, + edp0_lcd, edp1_hot, edp1_lcd, edp2_hot, edp2_lcd, edp3_hot, + edp3_lcd, emac0_mcg0, emac0_mcg1, emac0_mcg2, emac0_mcg3, + 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, + 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, + mdp1_vsync5, mdp1_vsync6, mdp1_vsync7, mdp1_vsync8, mdp_vsync, + mi2s1_data0, mi2s1_data1, mi2s1_sck, mi2s1_ws, mi2s2_data0, + mi2s2_data1, mi2s2_sck, mi2s2_ws, mi2s_mclk0, mi2s_mclk1, + pcie0_clkreq, pcie1_clkreq, phase_flag, pll_bist, pll_clk, + prng_rosc0, prng_rosc1, prng_rosc2, prng_rosc3, qdss_cti, + qdss_gpio, qup0_se0, qup0_se1, qup0_se2, qup0_se3, qup0_se4, + qup0_se5, qup1_se0, qup1_se1, qup1_se2, qup1_se3, qup1_se4, + qup1_se5, qup1_se6, qup2_se0, qup2_se1, qup2_se2, qup2_se3, + qup2_se4, qup2_se5, qup2_se6, qup3_se0, sailss_emac0, + sailss_ospi, sail_top, sgmii_phy, tb_trig, tgu_ch0, tgu_ch1, + tgu_ch2, tgu_ch3, tgu_ch4, tgu_ch5, tsense_pwm1, tsense_pwm2, + tsense_pwm3, tsense_pwm4, usb2phy_ac, vsense_trigger ] + + bias-disable: true + bias-pull-down: true + bias-pull-up: true + drive-strength: true + input-enable: true + output-high: true + output-low: true + + required: + - pins + + additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + tlmm: pinctrl@f000000 { + compatible = "qcom,sa8775p-tlmm"; + reg = <0xf000000 0x1000000>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-ranges = <&tlmm 0 0 148>; + + qup-uart10-state { + pins = "gpio46", "gpio47"; + function = "qup1_se3"; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.yaml index b40f6dc6adae..f33792a1af6c 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.yaml @@ -26,7 +26,9 @@ properties: - const: north - const: south - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true 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 f7ec8a4f664f..e51feb4c0700 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-lpass-lpi-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-lpass-lpi-pinctrl.yaml @@ -59,7 +59,7 @@ $defs: subnode. items: oneOf: - - pattern: "^gpio([0-9]|[1-9][0-9])$" + - pattern: "^gpio([0-9]|1[0-4])$" minItems: 1 maxItems: 15 diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc8180x-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sc8180x-tlmm.yaml index 24191d5f64ac..0ace55c9868e 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc8180x-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc8180x-tlmm.yaml @@ -28,7 +28,9 @@ properties: - const: east - const: south - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true '#interrupt-cells': true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc8280xp-lpass-lpi-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sc8280xp-lpass-lpi-pinctrl.yaml index 7d2589387e1a..200b3b6ccd87 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc8280xp-lpass-lpi-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc8280xp-lpass-lpi-pinctrl.yaml @@ -65,7 +65,7 @@ $defs: List of gpio pins affected by the properties specified in this subnode. items: - pattern: "^gpio([0-1]|1[0-8])$" + pattern: "^gpio([0-9]|1[0-8])$" function: enum: [ swr_tx_clk, swr_tx_data, swr_rx_clk, swr_rx_data, @@ -94,14 +94,12 @@ $defs: 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: @@ -136,7 +134,7 @@ examples: clock-names = "core", "audio"; gpio-controller; #gpio-cells = <2>; - gpio-ranges = <&lpi_tlmm 0 0 18>; + gpio-ranges = <&lpi_tlmm 0 0 19>; dmic01-state { dmic01-clk-pins { diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc8280xp-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sc8280xp-tlmm.yaml index 4efde29c36a2..97b27d6835e9 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc8280xp-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc8280xp-tlmm.yaml @@ -22,7 +22,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdm630-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sdm630-pinctrl.yaml index bd4fd8404aa4..ea6bd0b44f56 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sdm630-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sdm630-pinctrl.yaml @@ -31,7 +31,9 @@ properties: - const: center - const: north - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdm670-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sdm670-tlmm.yaml index 7585117c0f06..f586b3aa138e 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sdm670-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sdm670-tlmm.yaml @@ -22,7 +22,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.yaml index c9627777ceb3..23d7c030fec0 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.yaml @@ -23,7 +23,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true @@ -48,6 +50,10 @@ patternProperties: $ref: "#/$defs/qcom-sdm845-tlmm-state" additionalProperties: false + "-hog(-[0-9]+)?$": + required: + - gpio-hog + $defs: qcom-sdm845-tlmm-state: type: object @@ -117,6 +123,7 @@ additionalProperties: false examples: - | + #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/interrupt-controller/arm-gic.h> pinctrl@3400000 { @@ -130,6 +137,12 @@ examples: gpio-ranges = <&tlmm 0 0 151>; wakeup-parent = <&pdc_intc>; + ap-suspend-l-hog { + gpio-hog; + gpios = <126 GPIO_ACTIVE_LOW>; + output-low; + }; + cci0-default-state { pins = "gpio17", "gpio18"; function = "cci_i2c"; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdx55-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sdx55-pinctrl.yaml index a76117e41d93..a40175258495 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sdx55-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sdx55-pinctrl.yaml @@ -20,7 +20,9 @@ properties: description: Specifies the base address and size of the TLMM register space maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true @@ -53,7 +55,7 @@ $defs: List of gpio pins affected by the properties specified in this subnode. items: oneOf: - - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-1][0-6])$" + - pattern: "^gpio([0-9]|[1-9][0-9]|10[0-7])$" - enum: [ sdc1_clk, sdc1_cmd, sdc1_data, sdc2_clk, sdc2_cmd, sdc2_data ] minItems: 1 maxItems: 36 diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdx65-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sdx65-tlmm.yaml index 2f53905260e6..89c5562583d1 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sdx65-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sdx65-tlmm.yaml @@ -19,7 +19,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-tlmm.yaml index 164f24db8b2b..29325483cd2b 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-tlmm.yaml @@ -26,7 +26,9 @@ properties: - const: south - const: east - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm6125-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm6125-tlmm.yaml index e1dd54a160d5..c9bc4893e8e8 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm6125-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm6125-tlmm.yaml @@ -27,7 +27,9 @@ properties: - const: south - const: east - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm6350-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm6350-tlmm.yaml index 41e3e0afc9a8..d95935fcc8b5 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm6350-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm6350-tlmm.yaml @@ -22,11 +22,21 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + minItems: 9 + maxItems: 9 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true - gpio-reserved-ranges: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 78 + + gpio-line-names: + maxItems: 156 + "#gpio-cells": true gpio-ranges: true wakeup-parent: true @@ -61,7 +71,7 @@ $defs: subnode. items: oneOf: - - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-4][0-9]|15[0-7])$" + - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-4][0-9]|15[0-5])$" - enum: [ sdc1_clk, sdc1_cmd, sdc1_data, sdc2_clk, sdc2_cmd, sdc2_data ] minItems: 1 maxItems: 36 @@ -118,7 +128,16 @@ examples: pinctrl@f100000 { compatible = "qcom,sm6350-tlmm"; reg = <0x0f100000 0x300000>; - interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 209 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 210 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 211 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 212 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 213 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 214 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 215 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 216 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; #gpio-cells = <2>; interrupt-controller; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm6375-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm6375-tlmm.yaml index d54ebb2bd5a8..66cef48ed59b 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm6375-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm6375-tlmm.yaml @@ -22,7 +22,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true @@ -61,7 +63,7 @@ $defs: subnode. items: oneOf: - - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-4][0-9]|15[0-6])$" + - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-4][0-9]|15[0-5])$" - enum: [ ufs_reset, sdc1_clk, sdc1_cmd, sdc1_data, sdc2_clk, sdc2_cmd, sdc2_data ] minItems: 1 @@ -132,7 +134,7 @@ examples: #gpio-cells = <2>; interrupt-controller; #interrupt-cells = <2>; - gpio-ranges = <&tlmm 0 0 157>; + gpio-ranges = <&tlmm 0 0 157>; /* GPIOs + ufs_reset */ gpio-wo-subnode-state { pins = "gpio1"; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm8150-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm8150-pinctrl.yaml index 85adddbdee56..4376a9bd4d70 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm8150-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8150-pinctrl.yaml @@ -27,7 +27,9 @@ properties: - const: north - const: south - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-lpass-lpi-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-lpass-lpi-pinctrl.yaml index bd45faa3f078..de9d8854c690 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-lpass-lpi-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-lpass-lpi-pinctrl.yaml @@ -64,7 +64,7 @@ $defs: subnode. items: oneOf: - - pattern: "^gpio([0-9]|[1-9][0-9])$" + - pattern: "^gpio([0-9]|1[0-3])$" minItems: 1 maxItems: 14 diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-pinctrl.yaml index c80f3847ac08..cf561dff8893 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-pinctrl.yaml @@ -25,7 +25,9 @@ properties: - const: south - const: north - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true @@ -129,6 +131,6 @@ examples: #gpio-cells = <2>; interrupt-controller; #interrupt-cells = <2>; - gpio-ranges = <&tlmm 0 0 180>; + gpio-ranges = <&tlmm 0 0 181>; /* GPIOs + ufs_reset */ wakeup-parent = <&pdc>; }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm8350-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm8350-tlmm.yaml index 0b1e4aa5819e..797242f68b1c 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm8350-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8350-tlmm.yaml @@ -22,11 +22,20 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true - gpio-reserved-ranges: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 102 + + gpio-line-names: + maxItems: 203 + "#gpio-cells": true gpio-ranges: true wakeup-parent: true @@ -61,7 +70,7 @@ $defs: subnode. items: oneOf: - - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-9][0-9]|20[0-3])$" + - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-9][0-9]|20[0-2])$" - enum: [ sdc1_clk, sdc1_cmd, sdc1_data, sdc2_clk, sdc2_cmd, sdc2_data ] minItems: 1 maxItems: 36 @@ -100,6 +109,7 @@ $defs: bias-pull-down: true bias-pull-up: true drive-strength: true + input-disable: true input-enable: true output-high: true output-low: true @@ -120,7 +130,7 @@ examples: #gpio-cells = <2>; interrupt-controller; #interrupt-cells = <2>; - gpio-ranges = <&tlmm 0 0 203>; + gpio-ranges = <&tlmm 0 0 204>; /* GPIOs + ufs_reset */ gpio-wo-subnode-state { pins = "gpio1"; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm8450-lpass-lpi-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm8450-lpass-lpi-pinctrl.yaml index 01a0a4a40ba5..8bf51df0b231 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm8450-lpass-lpi-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8450-lpass-lpi-pinctrl.yaml @@ -65,7 +65,7 @@ $defs: List of gpio pins affected by the properties specified in this subnode. items: - pattern: "^gpio([0-9]|[1-2][0-9])$" + pattern: "^gpio([0-9]|1[0-9]|2[0-2])$" function: enum: [ swr_tx_clk, swr_tx_data, swr_rx_clk, swr_rx_data, @@ -96,14 +96,12 @@ $defs: 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: diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm8450-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm8450-tlmm.yaml index 4a1d10d6c5e7..56c8046f1be0 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm8450-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8450-tlmm.yaml @@ -22,7 +22,9 @@ properties: reg: maxItems: 1 - interrupts: true + interrupts: + maxItems: 1 + interrupt-controller: true "#interrupt-cells": true gpio-controller: true @@ -32,7 +34,7 @@ properties: maxItems: 105 gpio-line-names: - maxItems: 209 + maxItems: 210 "#gpio-cells": true gpio-ranges: true diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm8550-lpass-lpi-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm8550-lpass-lpi-pinctrl.yaml new file mode 100644 index 000000000000..5e90051ed314 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8550-lpass-lpi-pinctrl.yaml @@ -0,0 +1,148 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,sm8550-lpass-lpi-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM8550 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 SM8550 SoC. + +properties: + compatible: + const: qcom,sm8550-lpass-lpi-pinctrl + + reg: + items: + - description: LPASS LPI TLMM Control and Status registers + - description: LPASS LPI pins SLEW 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-sm8550-lpass-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sm8550-lpass-state" + additionalProperties: false + +$defs: + qcom-sm8550-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-pull-down: true + bias-pull-up: true + bias-disable: 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,q6dsp-lpass-ports.h> + + lpass_tlmm: pinctrl@6e80000 { + compatible = "qcom,sm8550-lpass-lpi-pinctrl"; + reg = <0x06e80000 0x20000>, + <0x0725a000 0x10000>; + + clocks = <&q6prmcc LPASS_HW_MACRO_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>, + <&q6prmcc LPASS_HW_DCODEC_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>; + clock-names = "core", "audio"; + + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&lpass_tlmm 0 0 23>; + + tx-swr-sleep-clk-state { + pins = "gpio0"; + function = "swr_tx_clk"; + drive-strength = <2>; + bias-pull-down; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm8550-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm8550-tlmm.yaml new file mode 100644 index 000000000000..a457425ba112 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8550-tlmm.yaml @@ -0,0 +1,163 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,sm8550-tlmm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. SM8550 TLMM block + +maintainers: + - Abel Vesa <abel.vesa@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in Qualcomm SM8550 SoC. + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +properties: + compatible: + const: qcom,sm8550-tlmm + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 105 + + gpio-line-names: + maxItems: 210 + + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-sm8550-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sm8550-tlmm-state" + additionalProperties: false + +$defs: + qcom-sm8550-tlmm-state: + type: object + description: + Pinctrl node's client devices use subnodes for desired pin configuration. + Client device subnodes use below standard properties. + $ref: qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state + + properties: + pins: + description: + List of gpio pins affected by the properties specified in this + subnode. + items: + oneOf: + - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-9][0-9]|20[0-9])$" + - enum: [ ufs_reset, sdc2_clk, sdc2_cmd, sdc2_data ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + enum: [ aon_cci, aoss_cti, atest_char, atest_usb, + audio_ext_mclk0, audio_ext_mclk1, audio_ref_clk, + cam_aon_mclk4, cam_mclk, cci_async_in, cci_i2c_scl, + cci_i2c_sda, cci_timer, cmu_rng, coex_uart1_rx, + coex_uart1_tx, coex_uart2_rx, coex_uart2_tx, + cri_trng, dbg_out_clk, ddr_bist_complete, + ddr_bist_fail, ddr_bist_start, ddr_bist_stop, + ddr_pxi0, ddr_pxi1, ddr_pxi2, ddr_pxi3, dp_hot, + gcc_gp1, gcc_gp2, gcc_gp3, gpio, i2chub0_se0, + i2chub0_se1, i2chub0_se2, i2chub0_se3, i2chub0_se4, + i2chub0_se5, i2chub0_se6, i2chub0_se7, i2chub0_se8, + i2chub0_se9, i2s0_data0, i2s0_data1, i2s0_sck, + i2s0_ws, i2s1_data0, i2s1_data1, i2s1_sck, i2s1_ws, + ibi_i3c, jitter_bist, mdp_vsync, mdp_vsync0_out, + mdp_vsync1_out, mdp_vsync2_out, mdp_vsync3_out, + mdp_vsync_e, nav_gpio0, nav_gpio1, nav_gpio2, + pcie0_clk_req_n, pcie1_clk_req_n, phase_flag, + pll_bist_sync, pll_clk_aux, prng_rosc0, prng_rosc1, + prng_rosc2, prng_rosc3, qdss_cti, qdss_gpio, + qlink0_enable, qlink0_request, qlink0_wmss, + qlink1_enable, qlink1_request, qlink1_wmss, + qlink2_enable, qlink2_request, qlink2_wmss, + qspi0, qspi1, qspi2, qspi3, qspi_clk, qspi_cs, + qup1_se0, qup1_se1, qup1_se2, qup1_se3, qup1_se4, + qup1_se5, qup1_se6, qup1_se7, qup2_se0, + qup2_se0_l0_mira, qup2_se0_l0_mirb, qup2_se0_l1_mira, + qup2_se0_l1_mirb, qup2_se0_l2_mira, qup2_se0_l2_mirb, + qup2_se0_l3_mira, qup2_se0_l3_mirb, qup2_se1, + qup2_se2, qup2_se3, qup2_se4, qup2_se5, qup2_se6, + qup2_se7, sd_write_protect, sdc40, sdc41, sdc42, + sdc43, sdc4_clk, sdc4_cmd, tb_trig_sdc2, tb_trig_sdc4, + tgu_ch0_trigout, tgu_ch1_trigout, tgu_ch2_trigout, + tgu_ch3_trigout, tmess_prng0, tmess_prng1, tmess_prng2, + tmess_prng3, tsense_pwm1, tsense_pwm2, tsense_pwm3, + uim0_clk, uim0_data, uim0_present, uim0_reset, + uim1_clk, uim1_data, uim1_present, uim1_reset, + usb1_hs, usb_phy, vfr_0, vfr_1, vsense_trigger_mirnat ] + + bias-disable: true + bias-pull-down: true + bias-pull-up: true + drive-strength: true + input-enable: true + output-high: true + output-low: true + + required: + - pins + + additionalProperties: false + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + tlmm: pinctrl@f100000 { + compatible = "qcom,sm8550-tlmm"; + reg = <0x0f100000 0x300000>; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&tlmm 0 0 211>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + + gpio-wo-state { + pins = "gpio1"; + function = "gpio"; + }; + + uart-w-state { + rx-pins { + pins = "gpio26"; + function = "qup2_se7"; + bias-pull-up; + }; + + tx-pins { + pins = "gpio27"; + function = "qup2_se7"; + bias-disable; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,tlmm-common.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,tlmm-common.yaml index e1354f0c64f8..cb5ba1bd6f8d 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,tlmm-common.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,tlmm-common.yaml @@ -16,8 +16,9 @@ description: properties: interrupts: description: - Specifies the TLMM summary IRQ - maxItems: 1 + TLMM summary IRQ and dirconn interrupts. + minItems: 1 + maxItems: 9 interrupt-controller: true diff --git a/Documentation/devicetree/bindings/pinctrl/ralink,mt7620-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/ralink,mt7620-pinctrl.yaml index 6f17f3991640..1e63ea34146a 100644 --- a/Documentation/devicetree/bindings/pinctrl/ralink,mt7620-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/ralink,mt7620-pinctrl.yaml @@ -29,47 +29,609 @@ patternProperties: $ref: pinmux-node.yaml# properties: - groups: - description: The pin group to select. - enum: [ - # common - i2c, spi, wdt, - - # For MT7620 SoC - ephy, mdio, nd_sd, pa, pcie, rgmii1, rgmii2, spi refclk, - uartf, uartlite, wled, - - # For MT7628 and MT7688 SoCs - gpio, i2s, p0led_an, p0led_kn, p1led_an, p1led_kn, p2led_an, - p2led_kn, p3led_an, p3led_kn, p4led_an, p4led_kn, perst, pwm0, - pwm1, refclk, sdmode, spi cs1, spis, uart0, uart1, uart2, - wled_an, wled_kn, - ] - function: - description: The mux function to select. - enum: [ - # common - gpio, i2c, refclk, spi, - - # For MT7620 SoC - ephy, gpio i2s, gpio uartf, i2s uartf, mdio, nand, pa, - pcie refclk, pcie rst, pcm gpio, pcm i2s, pcm uartf, - rgmii1, rgmii2, sd, spi refclk, uartf, uartlite, wdt refclk, - wdt rst, wled, - - # For MT7628 and MT7688 SoCs - antenna, debug, i2s, jtag, p0led_an, p0led_kn, - p1led_an, p1led_kn, p2led_an, p2led_kn, p3led_an, p3led_kn, - p4led_an, p4led_kn, pcie, pcm, perst, pwm, pwm0, pwm1, pwm_uart2, - rsvd, sdxc, sdxc d5 d4, sdxc d6, sdxc d7, spi cs1, - spis, sw_r, uart0, uart1, uart2, utif, wdt, wled_an, wled_kn, -, - ] + description: + A string containing the name of the function to mux to the group. + anyOf: + - description: For MT7620 SoC + enum: [ephy, gpio, gpio i2s, gpio uartf, i2c, i2s uartf, mdio, nand, pa, + pcie refclk, pcie rst, pcm gpio, pcm i2s, pcm uartf, refclk, + rgmii1, rgmii2, sd, spi, spi refclk, uartf, uartlite, wdt refclk, + wdt rst, wled] + + - description: For MT7628 and MT7688 SoCs + enum: [antenna, debug, gpio, i2c, i2s, jtag, p0led_an, p0led_kn, + p1led_an, p1led_kn, p2led_an, p2led_kn, p3led_an, p3led_kn, + p4led_an, p4led_kn, pcie, pcm, perst, pwm, pwm0, pwm1, pwm_uart2, + refclk, rsvd, sdxc, sdxc d5 d4, sdxc d6, sdxc d7, spi, spi cs1, + spis, sw_r, uart0, uart1, uart2, utif, wdt, wled_an, wled_kn, -] + + groups: + description: + An array of strings. Each string contains the name of a group. + maxItems: 1 required: - groups - function + allOf: + - if: + properties: + function: + const: antenna + then: + properties: + groups: + enum: [i2s] + + - if: + properties: + function: + const: debug + then: + properties: + groups: + enum: [i2c] + + - if: + properties: + function: + const: ephy + then: + properties: + groups: + enum: [ephy] + + - if: + properties: + function: + const: gpio + then: + properties: + groups: + anyOf: + - description: For MT7620 SoC + enum: [ephy, i2c, mdio, nd_sd, pa, pcie, rgmii1, rgmii2, + spi, spi refclk, uartf, uartlite, wdt, wled] + + - description: For MT7628 and MT7688 SoCs + enum: [gpio, i2c, i2s, p0led_an, p0led_kn, p1led_an, + p1led_kn, p2led_an, p2led_kn, p3led_an, p3led_kn, + p4led_an, p4led_kn, perst, pwm0, pwm1, refclk, + sdmode, spi, spi cs1, spis, uart0, uart1, uart2, + wdt, wled_an, wled_kn] + + - if: + properties: + function: + const: gpio i2s + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: gpio uartf + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: i2c + then: + properties: + groups: + enum: [i2c] + + - if: + properties: + function: + const: i2s + then: + properties: + groups: + enum: [i2s] + + - if: + properties: + function: + const: i2s uartf + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: jtag + then: + properties: + groups: + enum: [p0led_an, p0led_kn, p1led_an, p1led_kn, p2led_an, + p2led_kn, p3led_an, p3led_kn, p4led_an, p4led_kn, + sdmode] + + - if: + properties: + function: + const: mdio + then: + properties: + groups: + enum: [mdio] + + - if: + properties: + function: + const: nand + then: + properties: + groups: + enum: [nd_sd] + + - if: + properties: + function: + const: p0led_an + then: + properties: + groups: + enum: [p0led_an] + + - if: + properties: + function: + const: p0led_kn + then: + properties: + groups: + enum: [p0led_kn] + + - if: + properties: + function: + const: p1led_an + then: + properties: + groups: + enum: [p1led_an] + + - if: + properties: + function: + const: p1led_kn + then: + properties: + groups: + enum: [p1led_kn] + + - if: + properties: + function: + const: p2led_an + then: + properties: + groups: + enum: [p2led_an] + + - if: + properties: + function: + const: p2led_kn + then: + properties: + groups: + enum: [p2led_kn] + + - if: + properties: + function: + const: p3led_an + then: + properties: + groups: + enum: [p3led_an] + + - if: + properties: + function: + const: p3led_kn + then: + properties: + groups: + enum: [p3led_kn] + + - if: + properties: + function: + const: p4led_an + then: + properties: + groups: + enum: [p4led_an] + + - if: + properties: + function: + const: p4led_kn + then: + properties: + groups: + enum: [p4led_kn] + + - if: + properties: + function: + const: pa + then: + properties: + groups: + enum: [pa] + + - if: + properties: + function: + const: pcie + then: + properties: + groups: + enum: [gpio] + + - if: + properties: + function: + const: pcie refclk + then: + properties: + groups: + enum: [pcie] + + - if: + properties: + function: + const: pcie rst + then: + properties: + groups: + enum: [pcie] + + - if: + properties: + function: + const: pcm + then: + properties: + groups: + enum: [i2s] + + - if: + properties: + function: + const: pcm gpio + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: pcm i2s + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: pcm uartf + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: perst + then: + properties: + groups: + enum: [perst] + + - if: + properties: + function: + const: pwm + then: + properties: + groups: + enum: [uart1, uart2] + + - if: + properties: + function: + const: pwm0 + then: + properties: + groups: + enum: [pwm0] + + - if: + properties: + function: + const: pwm1 + then: + properties: + groups: + enum: [pwm1] + + - if: + properties: + function: + const: pwm_uart2 + then: + properties: + groups: + enum: [spis] + + - if: + properties: + function: + const: refclk + then: + properties: + groups: + anyOf: + - description: For MT7620 SoC + enum: [mdio] + + - description: For MT7628 and MT7688 SoCs + enum: [gpio, refclk, spi cs1] + + - if: + properties: + function: + const: rgmii1 + then: + properties: + groups: + enum: [rgmii1] + + - if: + properties: + function: + const: rgmii2 + then: + properties: + groups: + enum: [rgmii2] + + - if: + properties: + function: + const: rsvd + then: + properties: + groups: + enum: [p0led_an, p0led_kn, wled_an, wled_kn] + + - if: + properties: + function: + const: sd + then: + properties: + groups: + enum: [nd_sd] + + - if: + properties: + function: + const: sdxc + then: + properties: + groups: + enum: [sdmode] + + - if: + properties: + function: + const: sdxc d5 d4 + then: + properties: + groups: + enum: [uart2] + + - if: + properties: + function: + const: sdxc d6 + then: + properties: + groups: + enum: [pwm1] + + - if: + properties: + function: + const: sdxc d7 + then: + properties: + groups: + enum: [pwm0] + + - if: + properties: + function: + const: spi + then: + properties: + groups: + enum: [spi] + + - if: + properties: + function: + const: spi cs1 + then: + properties: + groups: + enum: [spi cs1] + + - if: + properties: + function: + const: spi refclk + then: + properties: + groups: + enum: [spi refclk] + + - if: + properties: + function: + const: spis + then: + properties: + groups: + enum: [spis] + + - if: + properties: + function: + const: sw_r + then: + properties: + groups: + enum: [uart1] + + - if: + properties: + function: + const: uart0 + then: + properties: + groups: + enum: [uart0] + + - if: + properties: + function: + const: uart1 + then: + properties: + groups: + enum: [uart1] + + - if: + properties: + function: + const: uart2 + then: + properties: + groups: + enum: [uart2] + + - if: + properties: + function: + const: uartf + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: uartlite + then: + properties: + groups: + enum: [uartlite] + + - if: + properties: + function: + const: utif + then: + properties: + groups: + enum: [p1led_an, p1led_kn, p2led_an, p2led_kn, p3led_an, + p3led_kn, p4led_an, p4led_kn, pwm0, pwm1, sdmode, spis] + + - if: + properties: + function: + const: wdt + then: + properties: + groups: + enum: [wdt] + + - if: + properties: + function: + const: wdt refclk + then: + properties: + groups: + enum: [wdt] + + - if: + properties: + function: + const: wdt rst + then: + properties: + groups: + enum: [wdt] + + - if: + properties: + function: + const: wled + then: + properties: + groups: + enum: [wled] + + - if: + properties: + function: + const: wled_an + then: + properties: + groups: + enum: [wled_an] + + - if: + properties: + function: + const: wled_kn + then: + properties: + groups: + enum: [wled_kn] + + - if: + properties: + function: + const: "-" + then: + properties: + groups: + enum: [i2c, spi cs1, uart0] + additionalProperties: false additionalProperties: false @@ -83,7 +645,6 @@ required: additionalProperties: false examples: - # Pinmux controller node - | pinctrl { compatible = "ralink,mt7620-pinctrl"; diff --git a/Documentation/devicetree/bindings/pinctrl/ralink,mt7621-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/ralink,mt7621-pinctrl.yaml index 61e5c847e8c8..1b1d37b981d9 100644 --- a/Documentation/devicetree/bindings/pinctrl/ralink,mt7621-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/ralink,mt7621-pinctrl.yaml @@ -29,21 +29,213 @@ patternProperties: $ref: pinmux-node.yaml# properties: - groups: - description: The pin group to select. - enum: [i2c, jtag, mdio, pcie, rgmii1, rgmii2, sdhci, spi, uart1, - uart2, uart3, wdt] - function: - description: The mux function to select. + description: + A string containing the name of the function to mux to the group. enum: [gpio, i2c, i2s, jtag, mdio, nand1, nand2, pcie refclk, pcie rst, pcm, rgmii1, rgmii2, sdhci, spdif2, spdif3, spi, uart1, uart2, uart3, wdt refclk, wdt rst] + groups: + description: + An array of strings. Each string contains the name of a group. + maxItems: 1 + required: - groups - function + allOf: + - if: + properties: + function: + const: gpio + then: + properties: + groups: + enum: [i2c, jtag, mdio, pcie, rgmii1, rgmii2, sdhci, spi, + uart1, uart2, uart3, wdt] + + - if: + properties: + function: + const: i2c + then: + properties: + groups: + enum: [i2c] + + - if: + properties: + function: + const: i2s + then: + properties: + groups: + enum: [uart3] + + - if: + properties: + function: + const: jtag + then: + properties: + groups: + enum: [jtag] + + - if: + properties: + function: + const: mdio + then: + properties: + groups: + enum: [mdio] + + - if: + properties: + function: + const: nand1 + then: + properties: + groups: + enum: [spi] + + - if: + properties: + function: + const: nand2 + then: + properties: + groups: + enum: [sdhci] + + - if: + properties: + function: + const: pcie refclk + then: + properties: + groups: + enum: [pcie] + + - if: + properties: + function: + const: pcie rst + then: + properties: + groups: + enum: [pcie] + + - if: + properties: + function: + const: pcm + then: + properties: + groups: + enum: [uart2] + + - if: + properties: + function: + const: rgmii1 + then: + properties: + groups: + enum: [rgmii1] + + - if: + properties: + function: + const: rgmii2 + then: + properties: + groups: + enum: [rgmii2] + + - if: + properties: + function: + const: sdhci + then: + properties: + groups: + enum: [sdhci] + + - if: + properties: + function: + const: spdif2 + then: + properties: + groups: + enum: [uart2] + + - if: + properties: + function: + const: spdif3 + then: + properties: + groups: + enum: [uart3] + + - if: + properties: + function: + const: spi + then: + properties: + groups: + enum: [spi] + + - if: + properties: + function: + const: uart1 + then: + properties: + groups: + enum: [uart1] + + - if: + properties: + function: + const: uart2 + then: + properties: + groups: + enum: [uart2] + + - if: + properties: + function: + const: uart3 + then: + properties: + groups: + enum: [uart3] + + - if: + properties: + function: + const: wdt refclk + then: + properties: + groups: + enum: [wdt] + + - if: + properties: + function: + const: wdt rst + then: + properties: + groups: + enum: [wdt] + additionalProperties: false additionalProperties: false @@ -57,7 +249,6 @@ required: additionalProperties: false examples: - # Pinmux controller node - | pinctrl { compatible = "ralink,mt7621-pinctrl"; diff --git a/Documentation/devicetree/bindings/pinctrl/ralink,rt2880-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/ralink,rt2880-pinctrl.yaml index 56e5becabcfd..7fd0df880a76 100644 --- a/Documentation/devicetree/bindings/pinctrl/ralink,rt2880-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/ralink,rt2880-pinctrl.yaml @@ -29,18 +29,93 @@ patternProperties: $ref: pinmux-node.yaml# properties: - groups: - description: The pin group to select. - enum: [i2c, spi, uartlite, jtag, mdio, sdram, pci] - function: - description: The mux function to select. + description: + A string containing the name of the function to mux to the group. enum: [gpio, i2c, spi, uartlite, jtag, mdio, sdram, pci] + groups: + description: + An array of strings. Each string contains the name of a group. + maxItems: 1 + required: - groups - function + allOf: + - if: + properties: + function: + const: gpio + then: + properties: + groups: + enum: [i2c, spi, uartlite, jtag, mdio, sdram, pci] + + - if: + properties: + function: + const: i2c + then: + properties: + groups: + enum: [i2c] + + - if: + properties: + function: + const: spi + then: + properties: + groups: + enum: [spi] + + - if: + properties: + function: + const: uartlite + then: + properties: + groups: + enum: [uartlite] + + - if: + properties: + function: + const: jtag + then: + properties: + groups: + enum: [jtag] + + - if: + properties: + function: + const: mdio + then: + properties: + groups: + enum: [mdio] + + - if: + properties: + function: + const: sdram + then: + properties: + groups: + enum: [sdram] + + - if: + properties: + function: + const: pci + then: + properties: + groups: + enum: [pci] + additionalProperties: false additionalProperties: false @@ -54,7 +129,6 @@ required: additionalProperties: false examples: - # Pinmux controller node - | pinctrl { compatible = "ralink,rt2880-pinctrl"; diff --git a/Documentation/devicetree/bindings/pinctrl/ralink,rt305x-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/ralink,rt305x-pinctrl.yaml index f602a5d6e13a..4d66ca752a30 100644 --- a/Documentation/devicetree/bindings/pinctrl/ralink,rt305x-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/ralink,rt305x-pinctrl.yaml @@ -30,38 +30,225 @@ patternProperties: $ref: pinmux-node.yaml# properties: - groups: - description: The pin group to select. - enum: [ - # common - i2c, jtag, led, mdio, rgmii, spi, spi_cs1, uartf, uartlite, - - # For RT3050, RT3052 and RT3350 SoCs - sdram, - - # For RT3352 SoC - lna, pa - ] - function: - description: The mux function to select. - enum: [ - # common - gpio, gpio i2s, gpio uartf, i2c, i2s uartf, jtag, led, mdio, - pcm gpio, pcm i2s, pcm uartf, rgmii, spi, spi_cs1, uartf, - uartlite, wdg_cs1, + description: + A string containing the name of the function to mux to the group. + anyOf: + - description: For RT3050, RT3052 and RT3350 SoCs + enum: [gpio, gpio i2s, gpio uartf, i2c, i2s uartf, jtag, mdio, + pcm gpio, pcm i2s, pcm uartf, rgmii, sdram, spi, uartf, + uartlite] - # For RT3050, RT3052 and RT3350 SoCs - sdram, + - description: For RT3352 SoC + enum: [gpio, gpio i2s, gpio uartf, i2c, i2s uartf, jtag, led, + lna, mdio, pa, pcm gpio, pcm i2s, pcm uartf, rgmii, spi, + spi_cs1, uartf, uartlite, wdg_cs1] - # For RT3352 SoC - lna, pa - ] + - description: For RT5350 SoC + enum: [gpio, gpio i2s, gpio uartf, i2c, i2s uartf, jtag, led, + pcm gpio, pcm i2s, pcm uartf, spi, spi_cs1, uartf, + uartlite, wdg_cs1] + + groups: + description: + An array of strings. Each string contains the name of a group. + maxItems: 1 required: - groups - function + allOf: + - if: + properties: + function: + const: gpio + then: + properties: + groups: + anyOf: + - description: For RT3050, RT3052 and RT3350 SoCs + enum: [i2c, jtag, mdio, rgmii, sdram, spi, uartf, + uartlite] + + - description: For RT3352 SoC + enum: [i2c, jtag, led, lna, mdio, pa, rgmii, spi, spi_cs1, + uartf, uartlite] + + - description: For RT5350 SoC + enum: [i2c, jtag, led, spi, spi_cs1, uartf, uartlite] + + - if: + properties: + function: + const: gpio i2s + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: gpio uartf + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: i2c + then: + properties: + groups: + enum: [i2c] + + - if: + properties: + function: + const: i2s uartf + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: jtag + then: + properties: + groups: + enum: [jtag] + + - if: + properties: + function: + const: led + then: + properties: + groups: + enum: [led] + + - if: + properties: + function: + const: lna + then: + properties: + groups: + enum: [lna] + + - if: + properties: + function: + const: mdio + then: + properties: + groups: + enum: [mdio] + + - if: + properties: + function: + const: pa + then: + properties: + groups: + enum: [pa] + + - if: + properties: + function: + const: pcm gpio + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: pcm i2s + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: pcm uartf + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: rgmii + then: + properties: + groups: + enum: [rgmii] + + - if: + properties: + function: + const: sdram + then: + properties: + groups: + enum: [sdram] + + - if: + properties: + function: + const: spi + then: + properties: + groups: + enum: [spi] + + - if: + properties: + function: + const: spi_cs1 + then: + properties: + groups: + enum: [spi_cs1] + + - if: + properties: + function: + const: uartf + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: uartlite + then: + properties: + groups: + enum: [uartlite] + + - if: + properties: + function: + const: wdg_cs1 + then: + properties: + groups: + enum: [spi_cs1] + additionalProperties: false additionalProperties: false @@ -75,7 +262,6 @@ required: additionalProperties: false examples: - # Pinmux controller node - | pinctrl { compatible = "ralink,rt305x-pinctrl"; diff --git a/Documentation/devicetree/bindings/pinctrl/ralink,rt3883-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/ralink,rt3883-pinctrl.yaml index feb6e66dcb61..008d93181aea 100644 --- a/Documentation/devicetree/bindings/pinctrl/ralink,rt3883-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/ralink,rt3883-pinctrl.yaml @@ -29,21 +29,213 @@ patternProperties: $ref: pinmux-node.yaml# properties: - groups: - description: The pin group to select. - enum: [ge1, ge2, i2c, jtag, lna a, lna g, mdio, pci, spi, uartf, - uartlite] - function: - description: The mux function to select. + description: + A string containing the name of the function to mux to the group. enum: [ge1, ge2, gpio, gpio i2s, gpio uartf, i2c, i2s uartf, jtag, lna a, lna g, mdio, pci-dev, pci-fnc, pci-host1, pci-host2, pcm gpio, pcm i2s, pcm uartf, spi, uartf, uartlite] + groups: + description: + An array of strings. Each string contains the name of a group. + maxItems: 1 + required: - groups - function + allOf: + - if: + properties: + function: + const: ge1 + then: + properties: + groups: + enum: [ge1] + + - if: + properties: + function: + const: ge2 + then: + properties: + groups: + enum: [ge2] + + - if: + properties: + function: + const: gpio + then: + properties: + groups: + enum: [ge1, ge2, i2c, jtag, lna a, lna g, mdio, pci, spi, + uartf, uartlite] + + - if: + properties: + function: + const: gpio i2s + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: gpio uartf + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: i2c + then: + properties: + groups: + enum: [i2c] + + - if: + properties: + function: + const: i2s uartf + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: jtag + then: + properties: + groups: + enum: [jtag] + + - if: + properties: + function: + const: lna a + then: + properties: + groups: + enum: [lna a] + + - if: + properties: + function: + const: lna g + then: + properties: + groups: + enum: [lna g] + + - if: + properties: + function: + const: mdio + then: + properties: + groups: + enum: [mdio] + + - if: + properties: + function: + const: pci-dev + then: + properties: + groups: + enum: [pci] + + - if: + properties: + function: + const: pci-fnc + then: + properties: + groups: + enum: [pci] + + - if: + properties: + function: + const: pci-host1 + then: + properties: + groups: + enum: [pci] + + - if: + properties: + function: + const: pci-host2 + then: + properties: + groups: + enum: [pci] + + - if: + properties: + function: + const: pcm gpio + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: pcm i2s + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: pcm uartf + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: spi + then: + properties: + groups: + enum: [spi] + + - if: + properties: + function: + const: uartf + then: + properties: + groups: + enum: [uartf] + + - if: + properties: + function: + const: uartlite + then: + properties: + groups: + enum: [uartlite] + additionalProperties: false additionalProperties: false @@ -57,7 +249,6 @@ required: additionalProperties: false examples: - # Pinmux controller node - | pinctrl { compatible = "ralink,rt3883-pinctrl"; diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-poeg.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-poeg.yaml new file mode 100644 index 000000000000..ab2d456c93e4 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-poeg.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/renesas,rzg2l-poeg.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/G2L Port Output Enable for GPT (POEG) + +maintainers: + - Biju Das <biju.das.jz@bp.renesas.com> + +description: | + The output pins(GTIOCxA and GTIOCxB) of the general PWM timer (GPT) can be + disabled by using the port output enabling function for the GPT (POEG). + Specifically, either of the following ways can be used. + * Input level detection of the GTETRGA to GTETRGD pins. + * Output-disable request from the GPT. + * SSF bit setting(ie, by setting POEGGn.SSF to 1) + + The state of the GTIOCxA and the GTIOCxB pins when the output is disabled, + are controlled by the GPT module. + +properties: + compatible: + items: + - enum: + - renesas,r9a07g044-poeg # RZ/G2{L,LC} + - renesas,r9a07g054-poeg # RZ/V2L + - const: renesas,rzg2l-poeg + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + renesas,gpt: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to gpt instance that serves the pwm operation. + + renesas,poeg-id: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1, 2, 3 ] + description: | + POEG group index. Valid values are: + <0> : POEG group A + <1> : POEG group B + <2> : POEG group C + <3> : POEG group D + +required: + - compatible + - reg + - interrupts + - clocks + - power-domains + - resets + - renesas,poeg-id + - renesas,gpt + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r9a07g044-cpg.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + poeggd: poeg@10049400 { + compatible = "renesas,r9a07g044-poeg", "renesas,rzg2l-poeg"; + reg = <0x10049400 0x400>; + interrupts = <GIC_SPI 325 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD R9A07G044_POEG_D_CLKP>; + power-domains = <&cpg>; + resets = <&cpg R9A07G044_POEG_D_RST>; + renesas,poeg-id = <3>; + renesas,gpt = <&gpt>; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml index d6539723f354..45b767986a87 100644 --- a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml @@ -76,15 +76,13 @@ allOf: required: - compatible - rockchip,grf - - "#address-cells" - - "#size-cells" - - ranges patternProperties: "gpio@[0-9a-f]+$": type: object $ref: "/schemas/gpio/rockchip,gpio-bank.yaml#" + deprecated: true unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.yaml index 14a8c0215cc6..bc34e2c872bc 100644 --- a/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.yaml @@ -1,4 +1,5 @@ # SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause + %YAML 1.2 --- $id: http://devicetree.org/schemas/pinctrl/socionext,uniphier-pinctrl.yaml# @@ -69,11 +70,17 @@ examples: - | // The UniPhier pinctrl should be a subnode of a "syscon" compatible node. - soc-glue@5f800000 { - compatible = "socionext,uniphier-pro4-soc-glue", "simple-mfd", "syscon"; - reg = <0x5f800000 0x2000>; + pinctrl { + compatible = "socionext,uniphier-ld20-pinctrl"; + + pinctrl_ether_rgmii: ether-rgmii { + groups = "ether_rgmii"; + function = "ether_rgmii"; - pinctrl: pinctrl { - compatible = "socionext,uniphier-pro4-pinctrl"; + tx { + pins = "RGMII_TXCLK", "RGMII_TXD0", "RGMII_TXD1", + "RGMII_TXD2", "RGMII_TXD3", "RGMII_TXCTL"; + drive-strength = <9>; + }; }; }; diff --git a/Documentation/devicetree/bindings/pinctrl/starfive,jh7110-aon-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/starfive,jh7110-aon-pinctrl.yaml new file mode 100644 index 000000000000..b470901f5f56 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/starfive,jh7110-aon-pinctrl.yaml @@ -0,0 +1,124 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/starfive,jh7110-aon-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive JH7110 AON Pin Controller + +description: | + Bindings for the JH7110 RISC-V SoC from StarFive Technology Ltd. + + Out of the SoC's many pins only the ones named PAD_RGPIO0 to PAD_RGPIO3 + can be multiplexed and have configurable bias, drive strength, + schmitt trigger etc. + Some peripherals such as PWM have their I/O go through the 4 "GPIOs". + +maintainers: + - Jianlong Huang <jianlong.huang@starfivetech.com> + +properties: + compatible: + const: starfive,jh7110-aon-pinctrl + + reg: + maxItems: 1 + + resets: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + '#interrupt-cells': + const: 2 + + gpio-controller: true + + '#gpio-cells': + const: 2 + +patternProperties: + '-[0-9]+$': + type: object + additionalProperties: false + patternProperties: + '-pins$': + type: object + description: | + A pinctrl node should contain at least one subnode representing the + pinctrl groups available on the machine. Each subnode will list the + pins it needs, and how they should be configured, with regard to + muxer configuration, bias, input enable/disable, input schmitt + trigger enable/disable, slew-rate and drive strength. + allOf: + - $ref: /schemas/pinctrl/pincfg-node.yaml + - $ref: /schemas/pinctrl/pinmux-node.yaml + additionalProperties: false + + properties: + pinmux: + description: | + The list of GPIOs and their mux settings that properties in the + node apply to. This should be set using the GPIOMUX macro. + + bias-disable: true + + bias-pull-up: + type: boolean + + bias-pull-down: + type: boolean + + drive-strength: + enum: [ 2, 4, 8, 12 ] + + input-enable: true + + input-disable: true + + input-schmitt-enable: true + + input-schmitt-disable: true + + slew-rate: + maximum: 1 + +required: + - compatible + - reg + - interrupts + - interrupt-controller + - '#interrupt-cells' + - gpio-controller + - '#gpio-cells' + +additionalProperties: false + +examples: + - | + pinctrl@17020000 { + compatible = "starfive,jh7110-aon-pinctrl"; + reg = <0x17020000 0x10000>; + resets = <&aoncrg 2>; + interrupts = <85>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-controller; + #gpio-cells = <2>; + + pwm-0 { + pwm-pins { + pinmux = <0xff030802>; + bias-disable; + drive-strength = <12>; + input-disable; + input-schmitt-disable; + slew-rate = <0>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/pinctrl/starfive,jh7110-sys-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/starfive,jh7110-sys-pinctrl.yaml new file mode 100644 index 000000000000..222b9e240f8a --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/starfive,jh7110-sys-pinctrl.yaml @@ -0,0 +1,142 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/starfive,jh7110-sys-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive JH7110 SYS Pin Controller + +description: | + Bindings for the JH7110 RISC-V SoC from StarFive Technology Ltd. + + Out of the SoC's many pins only the ones named PAD_GPIO0 to PAD_GPIO63 + can be multiplexed and have configurable bias, drive strength, + schmitt trigger etc. + Some peripherals have their I/O go through the 64 "GPIOs". This also + includes a number of other UARTs, I2Cs, SPIs, PWMs etc. + All these peripherals are connected to all 64 GPIOs such that + any GPIO can be set up to be controlled by any of the peripherals. + +maintainers: + - Jianlong Huang <jianlong.huang@starfivetech.com> + +properties: + compatible: + const: starfive,jh7110-sys-pinctrl + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + '#interrupt-cells': + const: 2 + + gpio-controller: true + + '#gpio-cells': + const: 2 + +patternProperties: + '-[0-9]+$': + type: object + additionalProperties: false + patternProperties: + '-pins$': + type: object + description: | + A pinctrl node should contain at least one subnode representing the + pinctrl groups available on the machine. Each subnode will list the + pins it needs, and how they should be configured, with regard to + muxer configuration, bias, input enable/disable, input schmitt + trigger enable/disable, slew-rate and drive strength. + allOf: + - $ref: /schemas/pinctrl/pincfg-node.yaml + - $ref: /schemas/pinctrl/pinmux-node.yaml + additionalProperties: false + + properties: + pinmux: + description: | + The list of GPIOs and their mux settings that properties in the + node apply to. This should be set using the GPIOMUX or PINMUX + macros. + + bias-disable: true + + bias-pull-up: + type: boolean + + bias-pull-down: + type: boolean + + drive-strength: + enum: [ 2, 4, 8, 12 ] + + input-enable: true + + input-disable: true + + input-schmitt-enable: true + + input-schmitt-disable: true + + slew-rate: + maximum: 1 + +required: + - compatible + - reg + - clocks + - interrupts + - interrupt-controller + - '#interrupt-cells' + - gpio-controller + - '#gpio-cells' + +additionalProperties: false + +examples: + - | + pinctrl@13040000 { + compatible = "starfive,jh7110-sys-pinctrl"; + reg = <0x13040000 0x10000>; + clocks = <&syscrg 112>; + resets = <&syscrg 2>; + interrupts = <86>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-controller; + #gpio-cells = <2>; + + uart0-0 { + tx-pins { + pinmux = <0xff140005>; + bias-disable; + drive-strength = <12>; + input-disable; + input-schmitt-disable; + slew-rate = <0>; + }; + + rx-pins { + pinmux = <0x0E000406>; + bias-pull-up; + drive-strength = <2>; + input-enable; + input-schmitt-enable; + slew-rate = <0>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/power/fsl,imx-gpc.yaml b/Documentation/devicetree/bindings/power/fsl,imx-gpc.yaml index 777e1d852ddd..c21a66422d4f 100644 --- a/Documentation/devicetree/bindings/power/fsl,imx-gpc.yaml +++ b/Documentation/devicetree/bindings/power/fsl,imx-gpc.yaml @@ -23,11 +23,16 @@ description: | properties: compatible: - enum: - - fsl,imx6q-gpc - - fsl,imx6qp-gpc - - fsl,imx6sl-gpc - - fsl,imx6sx-gpc + oneOf: + - enum: + - fsl,imx6q-gpc + - items: + - enum: + - fsl,imx6qp-gpc + - fsl,imx6sl-gpc + - fsl,imx6sx-gpc + - fsl,imx6ul-gpc + - const: fsl,imx6q-gpc reg: maxItems: 1 @@ -35,6 +40,10 @@ properties: interrupts: maxItems: 1 + interrupt-controller: true + '#interrupt-cells': + const: 3 + clocks: maxItems: 1 diff --git a/Documentation/devicetree/bindings/power/power-domain.yaml b/Documentation/devicetree/bindings/power/power-domain.yaml index 889091b9814f..d1235e562041 100644 --- a/Documentation/devicetree/bindings/power/power-domain.yaml +++ b/Documentation/devicetree/bindings/power/power-domain.yaml @@ -43,9 +43,6 @@ properties: domain would be considered as capable of being powered-on or powered-off. operating-points-v2: - $ref: /schemas/types.yaml#/definitions/phandle-array - items: - maxItems: 1 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 diff --git a/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt b/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt index c4d78f28d23c..3ff6ebbb4998 100644 --- a/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt +++ b/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt @@ -97,16 +97,6 @@ Nintendo Wii device tree - reg : should contain the EXI registers location and length - interrupts : should contain the EXI interrupt -1.g) The Open Host Controller Interface (OHCI) nodes - - Represent the USB 1.x Open Host Controller Interfaces. - - Required properties: - - - compatible : should be "nintendo,hollywood-usb-ohci","usb-ohci" - - reg : should contain the OHCI registers location and length - - interrupts : should contain the OHCI interrupt - 1.h) The Enhanced Host Controller Interface (EHCI) node Represents the USB 2.0 Enhanced Host Controller Interface. diff --git a/Documentation/devicetree/bindings/pwm/nvidia,tegra20-pwm.yaml b/Documentation/devicetree/bindings/pwm/nvidia,tegra20-pwm.yaml index 739d3155dd32..41cea4979132 100644 --- a/Documentation/devicetree/bindings/pwm/nvidia,tegra20-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/nvidia,tegra20-pwm.yaml @@ -63,8 +63,7 @@ properties: pinctrl-1: description: configuration for the sleep state - operating-points-v2: - $ref: /schemas/types.yaml#/definitions/phandle + operating-points-v2: true power-domains: items: diff --git a/Documentation/devicetree/bindings/pwm/pwm-sifive.yaml b/Documentation/devicetree/bindings/pwm/pwm-sifive.yaml index 605c1766dba8..bae993128981 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-sifive.yaml +++ b/Documentation/devicetree/bindings/pwm/pwm-sifive.yaml @@ -8,7 +8,6 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: SiFive PWM controller maintainers: - - Sagar Kadam <sagar.kadam@sifive.com> - Paul Walmsley <paul.walmsley@sifive.com> description: diff --git a/Documentation/devicetree/bindings/regulator/act8865-regulator.txt b/Documentation/devicetree/bindings/regulator/act8865-regulator.txt deleted file mode 100644 index b9f58e480349..000000000000 --- a/Documentation/devicetree/bindings/regulator/act8865-regulator.txt +++ /dev/null @@ -1,117 +0,0 @@ -ACT88xx regulators -------------------- - -Required properties: -- compatible: "active-semi,act8846" or "active-semi,act8865" or "active-semi,act8600" -- reg: I2C slave address - -Optional properties: -- system-power-controller: Telling whether or not this pmic is controlling - the system power. See Documentation/devicetree/bindings/power/power-controller.txt . -- active-semi,vsel-high: Indicates the VSEL pin is high. - If this property is missing, assume the VSEL pin is low(0). - -Optional input supply properties: -- for act8600: - - vp1-supply: The input supply for DCDC_REG1 - - vp2-supply: The input supply for DCDC_REG2 - - vp3-supply: The input supply for DCDC_REG3 - - inl-supply: The input supply for LDO_REG5, LDO_REG6, LDO_REG7 and LDO_REG8 - SUDCDC_REG4, LDO_REG9 and LDO_REG10 do not have separate supplies. -- for act8846: - - vp1-supply: The input supply for REG1 - - vp2-supply: The input supply for REG2 - - vp3-supply: The input supply for REG3 - - vp4-supply: The input supply for REG4 - - inl1-supply: The input supply for REG5, REG6 and REG7 - - inl2-supply: The input supply for REG8 and LDO_REG9 - - inl3-supply: The input supply for REG10, REG11 and REG12 -- for act8865: - - vp1-supply: The input supply for DCDC_REG1 - - vp2-supply: The input supply for DCDC_REG2 - - vp3-supply: The input supply for DCDC_REG3 - - inl45-supply: The input supply for LDO_REG1 and LDO_REG2 - - inl67-supply: The input supply for LDO_REG3 and LDO_REG4 - -Any standard regulator properties can be used to configure the single regulator. -regulator-initial-mode, regulator-allowed-modes and regulator-mode could be specified -for act8865 using mode values from dt-bindings/regulator/active-semi,8865-regulator.h -file. - -The valid names for regulators are: - - for act8846: - REG1, REG2, REG3, REG4, REG5, REG6, REG7, REG8, REG9, REG10, REG11, REG12 - - for act8865: - DCDC_REG1, DCDC_REG2, DCDC_REG3, LDO_REG1, LDO_REG2, LDO_REG3, LDO_REG4. - - for act8600: - DCDC_REG1, DCDC_REG2, DCDC_REG3, SUDCDC_REG4, LDO_REG5, LDO_REG6, LDO_REG7, - LDO_REG8, LDO_REG9, LDO_REG10, - -Example: --------- - -#include <dt-bindings/regulator/active-semi,8865-regulator.h> - - i2c1: i2c@f0018000 { - pmic: act8865@5b { - compatible = "active-semi,act8865"; - reg = <0x5b>; - active-semi,vsel-high; - - regulators { - vcc_1v8_reg: DCDC_REG1 { - regulator-name = "VCC_1V8"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - regulator-always-on; - }; - - vcc_1v2_reg: DCDC_REG2 { - regulator-name = "VCC_1V2"; - regulator-min-microvolt = <1100000>; - regulator-max-microvolt = <1300000>; - regulator-always-on; - - regulator-allowed-modes = <ACT8865_REGULATOR_MODE_FIXED>, - <ACT8865_REGULATOR_MODE_LOWPOWER>; - regulator-initial-mode = <ACT8865_REGULATOR_MODE_FIXED>; - - regulator-state-mem { - regulator-on-in-suspend; - regulator-suspend-min-microvolt = <1150000>; - regulator-suspend-max-microvolt = <1150000>; - regulator-changeable-in-suspend; - regulator-mode = <ACT8865_REGULATOR_MODE_LOWPOWER>; - }; - }; - - vcc_3v3_reg: DCDC_REG3 { - regulator-name = "VCC_3V3"; - regulator-min-microvolt = <3300000>; - regulator-max-microvolt = <3300000>; - regulator-always-on; - }; - - vddana_reg: LDO_REG1 { - regulator-name = "VDDANA"; - regulator-min-microvolt = <3300000>; - regulator-max-microvolt = <3300000>; - regulator-always-on; - - regulator-allowed-modes = <ACT8865_REGULATOR_MODE_NORMAL>, - <ACT8865_REGULATOR_MODE_LOWPOWER>; - regulator-initial-mode = <ACT8865_REGULATOR_MODE_NORMAL>; - - regulator-state-mem { - regulator-off-in-suspend; - }; - }; - - vddfuse_reg: LDO_REG2 { - regulator-name = "FUSE_2V5"; - regulator-min-microvolt = <2500000>; - regulator-max-microvolt = <2500000>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/regulator/act8945a-regulator.txt b/Documentation/devicetree/bindings/regulator/act8945a-regulator.txt deleted file mode 100644 index 4017527619ab..000000000000 --- a/Documentation/devicetree/bindings/regulator/act8945a-regulator.txt +++ /dev/null @@ -1,113 +0,0 @@ -Device-Tree bindings for regulators of Active-semi ACT8945A Multi-Function Device - -Required properties: - - compatible: "active-semi,act8945a", please refer to ../mfd/act8945a.txt. - -Optional properties: -- active-semi,vsel-high: Indicates if the VSEL pin is set to logic-high. - If this property is missing, assume the VSEL pin is set to logic-low. - -Optional input supply properties: - - vp1-supply: The input supply for REG_DCDC1 - - vp2-supply: The input supply for REG_DCDC2 - - vp3-supply: The input supply for REG_DCDC3 - - inl45-supply: The input supply for REG_LDO1 and REG_LDO2 - - inl67-supply: The input supply for REG_LDO3 and REG_LDO4 - -Any standard regulator properties can be used to configure the single regulator. -regulator-initial-mode, regulator-allowed-modes and regulator-mode could be -specified using mode values from dt-bindings/regulator/active-semi,8945a-regulator.h -file. - -The valid names for regulators are: - REG_DCDC1, REG_DCDC2, REG_DCDC3, REG_LDO1, REG_LDO2, REG_LDO3, REG_LDO4. - -Example: - -#include <dt-bindings/regulator/active-semi,8945a-regulator.h> - - pmic@5b { - compatible = "active-semi,act8945a"; - reg = <0x5b>; - - active-semi,vsel-high; - - regulators { - vdd_1v35_reg: REG_DCDC1 { - regulator-name = "VDD_1V35"; - regulator-min-microvolt = <1350000>; - regulator-max-microvolt = <1350000>; - regulator-always-on; - - regulator-allowed-modes = <ACT8945A_REGULATOR_MODE_FIXED>, - <ACT8945A_REGULATOR_MODE_LOWPOWER>; - regulator-initial-mode = <ACT8945A_REGULATOR_MODE_FIXED>; - - regulator-state-mem { - regulator-on-in-suspend; - regulator-suspend-min-microvolt=<1400000>; - regulator-suspend-max-microvolt=<1400000>; - regulator-changeable-in-suspend; - regulator-mode=<ACT8945A_REGULATOR_MODE_LOWPOWER>; - }; - }; - - vdd_1v2_reg: REG_DCDC2 { - regulator-name = "VDD_1V2"; - regulator-min-microvolt = <1100000>; - regulator-max-microvolt = <1300000>; - regulator-always-on; - - regulator-allowed-modes = <ACT8945A_REGULATOR_MODE_FIXED>, - <ACT8945A_REGULATOR_MODE_LOWPOWER>; - regulator-initial-mode = <ACT8945A_REGULATOR_MODE_FIXED>; - - regulator-state-mem { - regulator-off-in-suspend; - }; - }; - - vdd_3v3_reg: REG_DCDC3 { - regulator-name = "VDD_3V3"; - regulator-min-microvolt = <3300000>; - regulator-max-microvolt = <3300000>; - regulator-always-on; - }; - - vdd_fuse_reg: REG_LDO1 { - regulator-name = "VDD_FUSE"; - regulator-min-microvolt = <2500000>; - regulator-max-microvolt = <2500000>; - regulator-always-on; - - regulator-allowed-modes = <ACT8945A_REGULATOR_MODE_NORMAL>, - <ACT8945A_REGULATOR_MODE_LOWPOWER>; - regulator-initial-mode = <ACT8945A_REGULATOR_MODE_NORMAL>; - - regulator-state-mem { - regulator-off-in-suspend; - }; - }; - - vdd_3v3_lp_reg: REG_LDO2 { - regulator-name = "VDD_3V3_LP"; - regulator-min-microvolt = <3300000>; - regulator-max-microvolt = <3300000>; - regulator-always-on; - }; - - vdd_led_reg: REG_LDO3 { - regulator-name = "VDD_LED"; - regulator-min-microvolt = <3300000>; - regulator-max-microvolt = <3300000>; - regulator-always-on; - }; - - vdd_sdhc_1v8_reg: REG_LDO4 { - regulator-name = "VDD_SDHC_1V8"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - regulator-always-on; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/regulator/active-semi,act8600.yaml b/Documentation/devicetree/bindings/regulator/active-semi,act8600.yaml new file mode 100644 index 000000000000..b8ca967bc83d --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/active-semi,act8600.yaml @@ -0,0 +1,139 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/active-semi,act8600.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Active-semi ACT8600 regulator + +maintainers: + - Paul Cercueil <paul@crapouillou.net> + +properties: + compatible: + const: active-semi,act8600 + + reg: + maxItems: 1 + + system-power-controller: + description: + Indicates that the ACT8600 is responsible for powering OFF + the system. + type: boolean + + active-semi,vsel-high: + description: + Indicates the VSEL pin is high. If this property is missing, + the VSEL pin is assumed to be low. + type: boolean + + regulators: + type: object + additionalProperties: false + + properties: + DCDC1: + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + vp1-supply: + description: Handle to the VP1 input supply + + DCDC2: + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + vp2-supply: + description: Handle to the VP2 input supply + + DCDC3: + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + vp3-supply: + description: Handle to the VP3 input supply + + patternProperties: + "^(SUDCDC_REG4|LDO_REG9|LDO_REG10)$": + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + "^LDO[5-8]$": + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + inl-supply: + description: Handle to the INL input supply + +additionalProperties: false + +required: + - reg + - compatible + - regulators + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@5a { + compatible = "active-semi,act8600"; + reg = <0x5a>; + + regulators { + SUDCDC_REG4 { + regulator-min-microvolt = <5300000>; + regulator-max-microvolt = <5300000>; + inl-supply = <&vcc>; + }; + + LDO5 { + regulator-min-microvolt = <2500000>; + regulator-max-microvolt = <2500000>; + inl-supply = <&vcc>; + }; + + LDO6 { + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + inl-supply = <&vcc>; + }; + + LDO7 { + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + inl-supply = <&vcc>; + }; + + LDO8 { + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-always-on; + inl-supply = <&vcc>; + }; + + LDO_REG9 { + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + inl-supply = <&vcc>; + }; + + LDO_REG10 { + inl-supply = <&vcc>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/active-semi,act8846.yaml b/Documentation/devicetree/bindings/regulator/active-semi,act8846.yaml new file mode 100644 index 000000000000..3725348bb235 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/active-semi,act8846.yaml @@ -0,0 +1,205 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/active-semi,act8846.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Active-semi ACT8846 regulator + +maintainers: + - Paul Cercueil <paul@crapouillou.net> + +properties: + compatible: + const: active-semi,act8846 + + reg: + maxItems: 1 + + system-power-controller: + description: + Indicates that the ACT8846 is responsible for powering OFF + the system. + type: boolean + + active-semi,vsel-high: + description: + Indicates the VSEL pin is high. If this property is missing, + the VSEL pin is assumed to be low. + type: boolean + + regulators: + type: object + additionalProperties: false + + properties: + REG1: + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + vp1-supply: + description: Handle to the VP1 input supply + + REG2: + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + vp2-supply: + description: Handle to the VP2 input supply + + REG3: + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + vp3-supply: + description: Handle to the VP3 input supply + + REG4: + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + vp4-supply: + description: Handle to the VP4 input supply + + patternProperties: + "^REG[5-7]$": + 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: + - reg + - compatible + - regulators + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@5a { + compatible = "active-semi,act8846"; + reg = <0x5a>; + + system-power-controller; + + regulators { + REG1 { + regulator-name = "VCC_DDR"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-always-on; + }; + + REG2 { + regulator-name = "VCC_IO"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + REG3 { + regulator-name = "VDD_LOG"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1000000>; + regulator-always-on; + }; + + REG4 { + regulator-name = "VCC_20"; + regulator-min-microvolt = <2000000>; + regulator-max-microvolt = <2000000>; + regulator-always-on; + }; + + REG5 { + regulator-name = "VCCIO_SD"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + REG6 { + regulator-name = "VDD10_LCD"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1000000>; + regulator-always-on; + }; + + REG7 { + regulator-name = "VCC_WL"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + REG8 { + regulator-name = "VCCA_33"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + REG9 { + regulator-name = "VCC_LAN"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + REG10 { + regulator-name = "VDD_10"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1000000>; + regulator-always-on; + }; + + REG11 { + regulator-name = "VCC_18"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-always-on; + }; + + REG12 { + regulator-name = "VCC18_LCD"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-always-on; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/active-semi,act8865.yaml b/Documentation/devicetree/bindings/regulator/active-semi,act8865.yaml new file mode 100644 index 000000000000..e8bf09faafb8 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/active-semi,act8865.yaml @@ -0,0 +1,158 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/active-semi,act8865.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Active-semi ACT8865 regulator + +maintainers: + - Paul Cercueil <paul@crapouillou.net> + +properties: + compatible: + const: active-semi,act8865 + + reg: + maxItems: 1 + + system-power-controller: + description: + Indicates that the ACT8865 is responsible for powering OFF + the system. + type: boolean + + active-semi,vsel-high: + description: + Indicates the VSEL pin is high. If this property is missing, + the VSEL pin is assumed to be low. + type: boolean + + regulators: + type: object + additionalProperties: false + + properties: + DCDC_REG1: + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + vp1-supply: + description: Handle to the VP1 input supply + + DCDC_REG2: + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + vp2-supply: + description: Handle to the VP2 input supply + + DCDC_REG3: + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + vp3-supply: + description: Handle to the VP3 input supply + + patternProperties: + "^LDO_REG[1-2]$": + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + inl45-supply: + description: Handle to the INL45 input supply + + "^LDO_REG[3-4]$": + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + inl67-supply: + description: Handle to the INL67 input supply + +additionalProperties: false + +required: + - reg + - compatible + - regulators + +examples: + - | + #include <dt-bindings/regulator/active-semi,8865-regulator.h> + + i2c1 { + #address-cells = <1>; + #size-cells = <0>; + + pmic@5b { + compatible = "active-semi,act8865"; + reg = <0x5b>; + active-semi,vsel-high; + + regulators { + DCDC_REG1 { + regulator-name = "VCC_1V8"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-always-on; + }; + + DCDC_REG2 { + regulator-name = "VCC_1V2"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1300000>; + regulator-always-on; + + regulator-allowed-modes = <ACT8865_REGULATOR_MODE_FIXED>, + <ACT8865_REGULATOR_MODE_LOWPOWER>; + regulator-initial-mode = <ACT8865_REGULATOR_MODE_FIXED>; + + regulator-state-mem { + regulator-on-in-suspend; + regulator-suspend-min-microvolt = <1150000>; + regulator-suspend-max-microvolt = <1150000>; + regulator-changeable-in-suspend; + regulator-mode = <ACT8865_REGULATOR_MODE_LOWPOWER>; + }; + }; + + DCDC_REG3 { + regulator-name = "VCC_3V3"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + LDO_REG1 { + regulator-name = "VDDANA"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + + regulator-allowed-modes = <ACT8865_REGULATOR_MODE_NORMAL>, + <ACT8865_REGULATOR_MODE_LOWPOWER>; + regulator-initial-mode = <ACT8865_REGULATOR_MODE_NORMAL>; + + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + LDO_REG2 { + regulator-name = "FUSE_2V5"; + regulator-min-microvolt = <2500000>; + regulator-max-microvolt = <2500000>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/active-semi,act8945a.yaml b/Documentation/devicetree/bindings/regulator/active-semi,act8945a.yaml new file mode 100644 index 000000000000..bdf3f7d34ef5 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/active-semi,act8945a.yaml @@ -0,0 +1,258 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/active-semi,act8945a.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Active-semi ACT8945a regulator + +maintainers: + - Paul Cercueil <paul@crapouillou.net> + +properties: + compatible: + const: active-semi,act8945a + + reg: + maxItems: 1 + + system-power-controller: + description: + Indicates that the ACT8945a is responsible for powering OFF + the system. + type: boolean + + active-semi,vsel-high: + description: + Indicates the VSEL pin is high. If this property is missing, + the VSEL pin is assumed to be low. + type: boolean + + regulators: + type: object + additionalProperties: false + + properties: + REG_DCDC1: + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + vp1-supply: + description: Handle to the VP1 input supply + + REG_DCDC2: + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + vp2-supply: + description: Handle to the VP2 input supply + + REG_DCDC3: + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + vp3-supply: + description: Handle to the VP3 input supply + + patternProperties: + "^REG_LDO[1-2]$": + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + inl45-supply: + description: Handle to the INL45 input supply + + "^REG_LDO[3-4]$": + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + properties: + inl67-supply: + description: Handle to the INL67 input supply + + charger: + type: object + additionalProperties: false + + properties: + compatible: + const: active-semi,act8945a-charger + + interrupts: + maxItems: 1 + + active-semi,chglev-gpios: + description: CGHLEV GPIO + maxItems: 1 + + active-semi,lbo-gpios: + description: LBO GPIO + maxItems: 1 + + active-semi,input-voltage-threshold-microvolt: + description: Input voltage threshold + maxItems: 1 + + active-semi,precondition-timeout: + description: Precondition timeout + $ref: /schemas/types.yaml#/definitions/uint32 + + active-semi,total-timeout: + description: Total timeout + $ref: /schemas/types.yaml#/definitions/uint32 + + required: + - compatible + - interrupts + +additionalProperties: false + +required: + - reg + - compatible + - regulators + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/mfd/atmel-flexcom.h> + #include <dt-bindings/regulator/active-semi,8945a-regulator.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@5b { + compatible = "active-semi,act8945a"; + reg = <0x5b>; + active-semi,vsel-high; + + regulators { + REG_DCDC1 { + regulator-name = "VDD_1V35"; + regulator-min-microvolt = <1350000>; + regulator-max-microvolt = <1350000>; + regulator-allowed-modes = <ACT8945A_REGULATOR_MODE_FIXED>, + <ACT8945A_REGULATOR_MODE_LOWPOWER>; + regulator-initial-mode = <ACT8945A_REGULATOR_MODE_FIXED>; + regulator-always-on; + + regulator-state-mem { + regulator-on-in-suspend; + regulator-suspend-min-microvolt = <1400000>; + regulator-suspend-max-microvolt = <1400000>; + regulator-changeable-in-suspend; + regulator-mode = <ACT8945A_REGULATOR_MODE_LOWPOWER>; + }; + }; + + REG_DCDC2 { + regulator-name = "VDD_1V2"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1300000>; + regulator-allowed-modes = <ACT8945A_REGULATOR_MODE_FIXED>, + <ACT8945A_REGULATOR_MODE_LOWPOWER>; + regulator-initial-mode = <ACT8945A_REGULATOR_MODE_FIXED>; + regulator-always-on; + + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + REG_DCDC3 { + regulator-name = "VDD_3V3"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-allowed-modes = <ACT8945A_REGULATOR_MODE_FIXED>, + <ACT8945A_REGULATOR_MODE_LOWPOWER>; + regulator-initial-mode = <ACT8945A_REGULATOR_MODE_FIXED>; + regulator-always-on; + + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + REG_LDO1 { + regulator-name = "VDD_FUSE"; + regulator-min-microvolt = <2500000>; + regulator-max-microvolt = <2500000>; + regulator-allowed-modes = <ACT8945A_REGULATOR_MODE_NORMAL>, + <ACT8945A_REGULATOR_MODE_LOWPOWER>; + regulator-initial-mode = <ACT8945A_REGULATOR_MODE_NORMAL>; + regulator-always-on; + + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + REG_LDO2 { + regulator-name = "VDD_3V3_LP"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-allowed-modes = <ACT8945A_REGULATOR_MODE_NORMAL>, + <ACT8945A_REGULATOR_MODE_LOWPOWER>; + regulator-initial-mode = <ACT8945A_REGULATOR_MODE_NORMAL>; + regulator-always-on; + + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + REG_LDO3 { + regulator-name = "VDD_LED"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-allowed-modes = <ACT8945A_REGULATOR_MODE_NORMAL>, + <ACT8945A_REGULATOR_MODE_LOWPOWER>; + regulator-initial-mode = <ACT8945A_REGULATOR_MODE_NORMAL>; + regulator-always-on; + + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + REG_LDO4 { + regulator-name = "VDD_SDHC_1V8"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-allowed-modes = <ACT8945A_REGULATOR_MODE_NORMAL>, + <ACT8945A_REGULATOR_MODE_LOWPOWER>; + regulator-initial-mode = <ACT8945A_REGULATOR_MODE_NORMAL>; + regulator-always-on; + + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + }; + + charger { + compatible = "active-semi,act8945a-charger"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_charger_chglev &pinctrl_charger_lbo &pinctrl_charger_irq>; + interrupt-parent = <&pioA>; + interrupts = <45 IRQ_TYPE_EDGE_RISING>; + + active-semi,chglev-gpios = <&pioA 12 GPIO_ACTIVE_HIGH>; + active-semi,lbo-gpios = <&pioA 72 GPIO_ACTIVE_LOW>; + active-semi,input-voltage-threshold-microvolt = <6600>; + active-semi,precondition-timeout = <40>; + active-semi,total-timeout = <3>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/fan53555.txt b/Documentation/devicetree/bindings/regulator/fan53555.txt deleted file mode 100644 index 013f096ac0aa..000000000000 --- a/Documentation/devicetree/bindings/regulator/fan53555.txt +++ /dev/null @@ -1,24 +0,0 @@ -Binding for Fairchild FAN53555 regulators - -Required properties: - - compatible: one of "fcs,fan53555", "fcs,fan53526", "silergy,syr827", - "silergy,syr828" or "tcs,tcs4525". - - reg: I2C address - -Optional properties: - - fcs,suspend-voltage-selector: declare which of the two available - voltage selector registers should be used for the suspend - voltage. The other one is used for the runtime voltage setting - Possible values are either <0> or <1> - - vin-supply: regulator supplying the vin pin - -Example: - - regulator@40 { - compatible = "fcs,fan53555"; - regulator-name = "fan53555"; - regulator-min-microvolt = <1000000>; - regulator-max-microvolt = <1800000>; - vin-supply = <&parent_reg>; - fcs,suspend-voltage-selector = <1>; - }; diff --git a/Documentation/devicetree/bindings/regulator/fcs,fan53555.yaml b/Documentation/devicetree/bindings/regulator/fcs,fan53555.yaml new file mode 100644 index 000000000000..c0dbba843f70 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/fcs,fan53555.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/fcs,fan53555.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Fairchild FAN53555 regulators + +maintainers: + - Heiko Stuebner <heiko@sntech.de> + +allOf: + - $ref: regulator.yaml# + +properties: + compatible: + enum: + - fcs,fan53555 + - fcs,fan53526 + - silergy,syr827 + - silergy,syr828 + - tcs,tcs4525 + + reg: + maxItems: 1 + + fcs,suspend-voltage-selector: + description: Declares which of the two available voltage selector + registers should be used for the suspend voltage. The other one is used + for the runtime voltage setting. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1 ] + + vin-supply: + description: Supply for the vin pin + + vsel-gpios: + description: Voltage Select. When this pin is LOW, VOUT is set by the + VSEL0 register. When this pin is HIGH, VOUT is set by the VSEL1 register. + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + regulator@40 { + compatible = "fcs,fan53555"; + reg = <0x40>; + regulator-name = "fan53555"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1800000>; + vin-supply = <&parent_reg>; + fcs,suspend-voltage-selector = <1>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml index 84eeaef179a5..48af7cba4652 100644 --- a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml @@ -35,6 +35,10 @@ allOf: required: - power-domains - required-opps + - not: + required: + - gpio + - gpios properties: compatible: @@ -49,6 +53,9 @@ properties: description: gpio to use for enable control maxItems: 1 + gpios: + maxItems: 1 + clocks: description: clock to use for enable control. This binding is only available if diff --git a/Documentation/devicetree/bindings/regulator/maxim,max20411.yaml b/Documentation/devicetree/bindings/regulator/maxim,max20411.yaml new file mode 100644 index 000000000000..5b3a42d24e51 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/maxim,max20411.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/maxim,max20411.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated MAX20411 Step-Down DC-DC Converter + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + +description: + The MAX20411 is a high-efficiency, DC-DC step-down converter. It provides + configurable output voltage in the range of 0.5V to 1.275V, configurable over + I2C. + +allOf: + - $ref: regulator.yaml# + +properties: + compatible: + const: maxim,max20411 + + reg: + maxItems: 1 + + enable-gpios: + description: GPIO connected to the EN pin, active high + + vdd-supply: + description: Input supply for the device (VDD pin, 3.0V to 5.5V) + +required: + - compatible + - reg + - enable-gpios + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + regulator@39 { + compatible = "maxim,max20411"; + reg = <0x39>; + + enable-gpios = <&gpio 2 GPIO_ACTIVE_HIGH>; + + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <1000000>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/mps,mpq7932.yaml b/Documentation/devicetree/bindings/regulator/mps,mpq7932.yaml new file mode 100644 index 000000000000..2185cd011c46 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/mps,mpq7932.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/mps,mpq7932.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Monolithic Power System MPQ7932 PMIC + +maintainers: + - Saravanan Sekar <saravanan@linumiz.com> + +properties: + compatible: + enum: + - mps,mpq7932 + + reg: + maxItems: 1 + + regulators: + type: object + description: | + list of regulators provided by this controller, must be named + after their hardware counterparts BUCK[1-6] + + patternProperties: + "^buck[1-6]$": + 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,mpq7932"; + reg = <0x3>; + + regulators { + buck1 { + regulator-name = "buck1"; + regulator-min-microvolt = <1600000>; + regulator-max-microvolt = <1800000>; + regulator-boot-on; + }; + + buck2 { + regulator-name = "buck2"; + regulator-min-microvolt = <1700000>; + regulator-max-microvolt = <1800000>; + regulator-boot-on; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/qcom,rpm-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,rpm-regulator.yaml new file mode 100644 index 000000000000..8a08698e3484 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/qcom,rpm-regulator.yaml @@ -0,0 +1,128 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/qcom,rpm-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm RPM regulator + +description: + The Qualcomm RPM regulator is modelled as a subdevice of the RPM. + + Please refer to Documentation/devicetree/bindings/soc/qcom/qcom,rpm.yaml + for information regarding the RPM node. + + The regulator node houses sub-nodes for each regulator within the device. + Each sub-node is identified using the node's name, with valid values listed + for each of the pmics below. + + For pm8058 l0, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, + l16, l17, l18, l19, l20, l21, l22, l23, l24, l25, s0, s1, s2, s3, s4, + lvs0, lvs1, ncp + + For pm8901 l0, l1, l2, l3, l4, l5, l6, s0, s1, s2, s3, s4, lvs0, lvs1, lvs2, lvs3, + mvs + + For pm8921 s1, s2, s3, s4, s7, s8, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, + l12, l14, l15, l16, l17, l18, l21, l22, l23, l24, l25, l26, l27, l28, + l29, lvs1, lvs2, lvs3, lvs4, lvs5, lvs6, lvs7, usb-switch, hdmi-switch, + ncp + + For pm8018 s1, s2, s3, s4, s5, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, + l12, l14, lvs1 + + For smb208 s1a, s1b, s2a, s2b + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + +properties: + compatible: + enum: + - qcom,rpm-pm8058-regulators + - qcom,rpm-pm8901-regulators + - qcom,rpm-pm8921-regulators + - qcom,rpm-pm8018-regulators + - qcom,rpm-smb208-regulators + +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)$": + description: List of regulators and its properties + $ref: regulator.yaml# + unevaluatedProperties: false + properties: + bias-pull-down: + description: enable pull down of the regulator when inactive + type: boolean + + qcom,switch-mode-frequency: + description: Frequency (Hz) of the switch-mode power supply + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 19200000 + - 9600000 + - 6400000 + - 4800000 + - 3840000 + - 3200000 + - 2740000 + - 2400000 + - 2130000 + - 1920000 + - 1750000 + - 1600000 + - 1480000 + - 1370000 + - 1280000 + - 1200000 + + qcom,force-mode: + description: Indicates that the regulator should be forced to a particular mode + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # QCOM_RPM_FORCE_MODE_NONE do not force any mode + - 1 # QCOM_RPM_FORCE_MODE_LPM force into low power mode + - 2 # QCOM_RPM_FORCE_MODE_HPM force into high power mode + - 3 # QCOM_RPM_FORCE_MODE_AUTO allow regulator to automatically select its own mode + # based on realtime current draw, only for pm8921 smps and ftsmps + + qcom,power-mode-hysteretic: + description: select that the power supply should operate in hysteretic mode, + instead of the default pwm mode + type: boolean + +additionalProperties: false + +required: + - compatible + +examples: + - | + #include <dt-bindings/mfd/qcom-rpm.h> + regulators { + compatible = "qcom,rpm-pm8921-regulators"; + vdd_l1_l2_l12_l18-supply = <&pm8921_s4>; + + s1 { + regulator-min-microvolt = <1225000>; + regulator-max-microvolt = <1225000>; + + bias-pull-down; + + qcom,switch-mode-frequency = <3200000>; + }; + + pm8921_s4: s4 { + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + + qcom,switch-mode-frequency = <1600000>; + bias-pull-down; + + qcom,force-mode = <QCOM_RPM_FORCE_MODE_AUTO>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml index dbe78cd4adba..b1cff3adb21b 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml @@ -33,7 +33,7 @@ examples: pm8150b { #address-cells = <1>; #size-cells = <0>; - pm8150b_vbus: dcdc@1100 { + pm8150b_vbus: usb-vbus-regulator@1100 { compatible = "qcom,pm8150b-vbus-reg"; reg = <0x1100>; }; diff --git a/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml index f97b8083678f..e987c39b223e 100644 --- a/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml @@ -20,7 +20,8 @@ properties: lab: type: object - additionalProperties: false + $ref: regulator.yaml# + unevaluatedProperties: false properties: qcom,soft-start-us: @@ -46,7 +47,8 @@ properties: ibb: type: object - additionalProperties: false + $ref: regulator.yaml# + unevaluatedProperties: false properties: qcom,discharge-resistor-kohms: diff --git a/Documentation/devicetree/bindings/regulator/samsung,s2mps14.yaml b/Documentation/devicetree/bindings/regulator/samsung,s2mps14.yaml index 01f9d4e236e9..a7feb497eb89 100644 --- a/Documentation/devicetree/bindings/regulator/samsung,s2mps14.yaml +++ b/Documentation/devicetree/bindings/regulator/samsung,s2mps14.yaml @@ -19,8 +19,8 @@ description: | additional information and example. patternProperties: - # 25 LDOs - "^LDO([1-9]|[1][0-9]|2[0-5])$": + # 25 LDOs, without LDO10-12 + "^LDO([1-9]|1[3-9]|2[0-5])$": type: object $ref: regulator.yaml# unevaluatedProperties: false @@ -30,6 +30,23 @@ patternProperties: required: - regulator-name + "^LDO(1[0-2])$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: + Properties for single LDO regulator. + + properties: + samsung,ext-control-gpios: + maxItems: 1 + description: + LDO10, LDO11 and LDO12 can be configured to external control over + GPIO. + + required: + - regulator-name + # 5 bucks "^BUCK[1-5]$": type: object diff --git a/Documentation/devicetree/bindings/regulator/socionext,uniphier-regulator.yaml b/Documentation/devicetree/bindings/regulator/socionext,uniphier-regulator.yaml index c0acf949753d..a6949a581cd1 100644 --- a/Documentation/devicetree/bindings/regulator/socionext,uniphier-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/socionext,uniphier-regulator.yaml @@ -89,18 +89,11 @@ required: examples: - | - usb-glue@65b00000 { - compatible = "simple-mfd"; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0 0x65b00000 0x400>; - - usb_vbus0: regulators@100 { - compatible = "socionext,uniphier-ld20-usb3-regulator"; - reg = <0x100 0x10>; - clock-names = "link"; - clocks = <&sys_clk 14>; - reset-names = "link"; - resets = <&sys_rst 14>; - }; + usb_vbus0: regulators@100 { + compatible = "socionext,uniphier-ld20-usb3-regulator"; + reg = <0x100 0x10>; + clock-names = "link"; + clocks = <&sys_clk 14>; + reset-names = "link"; + resets = <&sys_rst 14>; }; diff --git a/Documentation/devicetree/bindings/reserved-memory/framebuffer.yaml b/Documentation/devicetree/bindings/reserved-memory/framebuffer.yaml new file mode 100644 index 000000000000..05b6648b3458 --- /dev/null +++ b/Documentation/devicetree/bindings/reserved-memory/framebuffer.yaml @@ -0,0 +1,52 @@ +# 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 bindings + +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/reserved-memory.yaml b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml index 44f72bcf1782..c680e397cfd2 100644 --- a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml +++ b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml @@ -31,17 +31,17 @@ properties: reg: true size: - $ref: /schemas/types.yaml#/definitions/uint32-array - minItems: 1 - maxItems: 2 + 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: - $ref: /schemas/types.yaml#/definitions/uint32-array - minItems: 1 - maxItems: 2 + 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. @@ -52,6 +52,30 @@ properties: 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: > @@ -89,12 +113,69 @@ allOf: - no-map oneOf: - - required: - - reg + - oneOf: + - required: + - reg + + - required: + - size + + - oneOf: + # IOMMU reservations + - required: + - iommu-addresses - - required: - - size + # 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/reset/socionext,uniphier-glue-reset.yaml b/Documentation/devicetree/bindings/reset/socionext,uniphier-glue-reset.yaml index 0a2c13e1e230..fa253c518d79 100644 --- a/Documentation/devicetree/bindings/reset/socionext,uniphier-glue-reset.yaml +++ b/Documentation/devicetree/bindings/reset/socionext,uniphier-glue-reset.yaml @@ -95,19 +95,12 @@ required: examples: - | - usb-glue@65b00000 { - compatible = "simple-mfd"; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0 0x65b00000 0x400>; - - usb_rst: reset@0 { - compatible = "socionext,uniphier-ld20-usb3-reset"; - reg = <0x0 0x4>; - #reset-cells = <1>; - clock-names = "link"; - clocks = <&sys_clk 14>; - reset-names = "link"; - resets = <&sys_rst 14>; - }; + usb_rst: reset-controller@0 { + compatible = "socionext,uniphier-ld20-usb3-reset"; + reg = <0x0 0x4>; + #reset-cells = <1>; + clock-names = "link"; + clocks = <&sys_clk 14>; + reset-names = "link"; + resets = <&sys_rst 14>; }; diff --git a/Documentation/devicetree/bindings/reset/socionext,uniphier-reset.yaml b/Documentation/devicetree/bindings/reset/socionext,uniphier-reset.yaml index 6566804ec567..033b252a3dfe 100644 --- a/Documentation/devicetree/bindings/reset/socionext,uniphier-reset.yaml +++ b/Documentation/devicetree/bindings/reset/socionext,uniphier-reset.yaml @@ -66,53 +66,7 @@ required: examples: - | - sysctrl@61840000 { - compatible = "socionext,uniphier-sysctrl", "simple-mfd", "syscon"; - reg = <0x61840000 0x4000>; - - reset { - compatible = "socionext,uniphier-ld11-reset"; - #reset-cells = <1>; - }; - - // other nodes ... - }; - - - | - mioctrl@59810000 { - compatible = "socionext,uniphier-mioctrl", "simple-mfd", "syscon"; - reg = <0x59810000 0x800>; - - reset { - compatible = "socionext,uniphier-ld11-mio-reset"; - #reset-cells = <1>; - }; - - // other nodes ... - }; - - - | - perictrl@59820000 { - compatible = "socionext,uniphier-perictrl", "simple-mfd", "syscon"; - reg = <0x59820000 0x200>; - - reset { - compatible = "socionext,uniphier-ld11-peri-reset"; - #reset-cells = <1>; - }; - - // other nodes ... - }; - - - | - adamv@57920000 { - compatible = "socionext,uniphier-ld11-adamv", "simple-mfd", "syscon"; - reg = <0x57920000 0x1000>; - - reset { - compatible = "socionext,uniphier-ld11-adamv-reset"; - #reset-cells = <1>; - }; - - // other nodes ... + reset-controller { + compatible = "socionext,uniphier-ld11-reset"; + #reset-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/riscv/cpus.yaml b/Documentation/devicetree/bindings/riscv/cpus.yaml index c6720764e765..a2884e3113da 100644 --- a/Documentation/devicetree/bindings/riscv/cpus.yaml +++ b/Documentation/devicetree/bindings/riscv/cpus.yaml @@ -83,7 +83,7 @@ properties: insensitive, letters in the riscv,isa string must be all lowercase to simplify parsing. $ref: "/schemas/types.yaml#/definitions/string" - pattern: ^rv(?:64|32)imaf?d?q?c?b?v?k?h?(?:_[hsxz](?:[a-z])+)*$ + pattern: ^rv(?:64|32)imaf?d?q?c?b?k?j?p?v?h?(?:[hsxz](?:[a-z])+)?(?:_[hsxz](?:[a-z])+)*$ # RISC-V requires 'timebase-frequency' in /cpus, so disallow it here timebase-frequency: false diff --git a/Documentation/devicetree/bindings/riscv/microchip.yaml b/Documentation/devicetree/bindings/riscv/microchip.yaml index 714d0fcab399..4a29c890619a 100644 --- a/Documentation/devicetree/bindings/riscv/microchip.yaml +++ b/Documentation/devicetree/bindings/riscv/microchip.yaml @@ -27,6 +27,7 @@ properties: - items: - enum: + - aldec,tysom-m-mpfs250t-rev2 - aries,m100pfsevp - microchip,mpfs-sev-kit - sundance,polarberry diff --git a/Documentation/devicetree/bindings/riscv/sifive,ccache0.yaml b/Documentation/devicetree/bindings/riscv/sifive,ccache0.yaml index bf3f07421f7e..0551a0d1b3df 100644 --- a/Documentation/devicetree/bindings/riscv/sifive,ccache0.yaml +++ b/Documentation/devicetree/bindings/riscv/sifive,ccache0.yaml @@ -8,8 +8,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: SiFive Composable Cache Controller maintainers: - - Sagar Kadam <sagar.kadam@sifive.com> - - Paul Walmsley <paul.walmsley@sifive.com> + - Paul Walmsley <paul.walmsley@sifive.com> description: The SiFive Composable Cache Controller is used to provide access to fast copies diff --git a/Documentation/devicetree/bindings/riscv/starfive.yaml b/Documentation/devicetree/bindings/riscv/starfive.yaml index 5d3fcee52d59..cc4d92f0a1bf 100644 --- a/Documentation/devicetree/bindings/riscv/starfive.yaml +++ b/Documentation/devicetree/bindings/riscv/starfive.yaml @@ -24,6 +24,12 @@ properties: - starfive,visionfive-v1 - const: starfive,jh7100 + - items: + - enum: + - starfive,visionfive-2-v1.2a + - starfive,visionfive-2-v1.3b + - const: starfive,jh7110 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/riscv/sunxi.yaml b/Documentation/devicetree/bindings/riscv/sunxi.yaml new file mode 100644 index 000000000000..9edb5e5992b1 --- /dev/null +++ b/Documentation/devicetree/bindings/riscv/sunxi.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/riscv/sunxi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner RISC-V SoC-based boards + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Jernej Skrabec <jernej.skrabec@gmail.com> + - Samuel Holland <samuel@sholland.org> + +description: + Allwinner RISC-V SoC-based boards + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - description: Dongshan Nezha STU SoM + items: + - const: 100ask,dongshan-nezha-stu + - const: allwinner,sun20i-d1 + + - description: D1 Nezha board + items: + - const: allwinner,d1-nezha + - const: allwinner,sun20i-d1 + + - description: ClockworkPi R-01 SoM and v3.14 board + items: + - const: clockwork,r-01-clockworkpi-v3.14 + - const: allwinner,sun20i-d1 + + - description: ClockworkPi R-01 SoM, v3.14 board, and DevTerm expansion + items: + - const: clockwork,r-01-devterm-v3.14 + - const: clockwork,r-01-clockworkpi-v3.14 + - const: allwinner,sun20i-d1 + + - description: Lichee RV SoM + items: + - const: sipeed,lichee-rv + - const: allwinner,sun20i-d1 + + - description: Carrier boards for the Lichee RV SoM + items: + - enum: + - sipeed,lichee-rv-86-panel-480p + - sipeed,lichee-rv-86-panel-720p + - sipeed,lichee-rv-dock + - const: sipeed,lichee-rv + - const: allwinner,sun20i-d1 + + - description: MangoPi MQ board + items: + - const: widora,mangopi-mq + - const: allwinner,sun20i-d1s + + - description: MangoPi MQ Pro board + items: + - const: widora,mangopi-mq-pro + - const: allwinner,sun20i-d1 + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/rng/starfive,jh7110-trng.yaml b/Documentation/devicetree/bindings/rng/starfive,jh7110-trng.yaml new file mode 100644 index 000000000000..2b76ce25acc4 --- /dev/null +++ b/Documentation/devicetree/bindings/rng/starfive,jh7110-trng.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rng/starfive,jh7110-trng.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive SoC TRNG Module + +maintainers: + - Jia Jie Ho <jiajie.ho@starfivetech.com> + +properties: + compatible: + const: starfive,jh7110-trng + + reg: + maxItems: 1 + + clocks: + items: + - description: Hardware reference clock + - description: AHB reference clock + + clock-names: + items: + - const: hclk + - const: ahb + + resets: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - resets + - interrupts + +additionalProperties: false + +examples: + - | + rng: rng@1600C000 { + compatible = "starfive,jh7110-trng"; + reg = <0x1600C000 0x4000>; + clocks = <&clk 15>, <&clk 16>; + clock-names = "hclk", "ahb"; + resets = <&reset 3>; + interrupts = <30>; + }; +... diff --git a/Documentation/devicetree/bindings/rtc/qcom-pm8xxx-rtc.yaml b/Documentation/devicetree/bindings/rtc/qcom-pm8xxx-rtc.yaml index 0a7aa29563c1..21c8ea08ff0a 100644 --- a/Documentation/devicetree/bindings/rtc/qcom-pm8xxx-rtc.yaml +++ b/Documentation/devicetree/bindings/rtc/qcom-pm8xxx-rtc.yaml @@ -40,6 +40,8 @@ properties: description: Indicates that the setting of RTC time is allowed by the host CPU. + wakeup-source: true + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/serial/8250.yaml b/Documentation/devicetree/bindings/serial/8250.yaml index 34b8e59aa9d4..692aa05500fd 100644 --- a/Documentation/devicetree/bindings/serial/8250.yaml +++ b/Documentation/devicetree/bindings/serial/8250.yaml @@ -11,6 +11,7 @@ maintainers: allOf: - $ref: serial.yaml# + - $ref: /schemas/memory-controllers/mc-peripheral-props.yaml# - if: anyOf: - required: @@ -62,7 +63,6 @@ properties: - const: mrvl,pxa-uart - const: nuvoton,wpcm450-uart - const: nuvoton,npcm750-uart - - const: nuvoton,npcm845-uart - const: nvidia,tegra20-uart - const: nxp,lpc3220-uart - items: @@ -94,6 +94,10 @@ properties: - ns16550a - items: - enum: + - nuvoton,npcm845-uart + - const: nuvoton,npcm750-uart + - items: + - enum: - ralink,mt7620a-uart - ralink,rt3052-uart - ralink,rt3883-uart @@ -200,12 +204,13 @@ properties: deprecated: true aspeed,lpc-io-reg: - $ref: '/schemas/types.yaml#/definitions/uint32' + $ref: /schemas/types.yaml#/definitions/uint32-array + maxItems: 1 description: | The VUART LPC address. Only applicable to aspeed,ast2500-vuart. aspeed,lpc-interrupts: - $ref: "/schemas/types.yaml#/definitions/uint32-array" + $ref: /schemas/types.yaml#/definitions/uint32-array minItems: 2 maxItems: 2 description: | diff --git a/Documentation/devicetree/bindings/serial/8250_omap.yaml b/Documentation/devicetree/bindings/serial/8250_omap.yaml index 53dc1212ad2e..eb3488d8f9ee 100644 --- a/Documentation/devicetree/bindings/serial/8250_omap.yaml +++ b/Documentation/devicetree/bindings/serial/8250_omap.yaml @@ -70,11 +70,6 @@ properties: dsr-gpios: true rng-gpios: true dcd-gpios: true - rs485-rts-delay: true - rs485-rts-active-low: true - rs485-rx-during-tx: true - rs485-rts-active-high: true - linux,rs485-enabled-at-boot-time: true rts-gpio: true power-domains: true clock-frequency: true @@ -109,12 +104,12 @@ else: examples: - | - serial@49042000 { - compatible = "ti,omap3-uart"; - reg = <0x49042000 0x400>; - interrupts = <80>; - dmas = <&sdma 81 &sdma 82>; - dma-names = "tx", "rx"; - ti,hwmods = "uart4"; - clock-frequency = <48000000>; - }; + serial@49042000 { + compatible = "ti,omap3-uart"; + reg = <0x49042000 0x400>; + interrupts = <80>; + dmas = <&sdma 81 &sdma 82>; + dma-names = "tx", "rx"; + ti,hwmods = "uart4"; + clock-frequency = <48000000>; + }; diff --git a/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml b/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml index 7822705ad16c..3cbdde85ed71 100644 --- a/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml +++ b/Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml @@ -19,6 +19,9 @@ description: | is active since power-on and does not need any clock gating and is usable as very early serial console. +allOf: + - $ref: serial.yaml# + properties: compatible: oneOf: @@ -69,14 +72,14 @@ required: - clocks - clock-names -additionalProperties: false +unevaluatedProperties: false examples: - | serial@84c0 { - compatible = "amlogic,meson-gx-uart"; - reg = <0x84c0 0x14>; - interrupts = <26>; - clocks = <&xtal>, <&pclk>, <&xtal>; - clock-names = "xtal", "pclk", "baud"; + compatible = "amlogic,meson-gx-uart"; + reg = <0x84c0 0x14>; + interrupts = <26>; + clocks = <&xtal>, <&pclk>, <&xtal>; + clock-names = "xtal", "pclk", "baud"; }; diff --git a/Documentation/devicetree/bindings/serial/cdns,uart.yaml b/Documentation/devicetree/bindings/serial/cdns,uart.yaml index 876b8cf1cafb..a8b323d7bf94 100644 --- a/Documentation/devicetree/bindings/serial/cdns,uart.yaml +++ b/Documentation/devicetree/bindings/serial/cdns,uart.yaml @@ -9,9 +9,6 @@ title: Cadence UART Controller maintainers: - Michal Simek <michal.simek@xilinx.com> -allOf: - - $ref: /schemas/serial.yaml# - properties: compatible: oneOf: @@ -46,6 +43,9 @@ properties: port does not use this pin. type: boolean + power-domains: + maxItems: 1 + required: - compatible - reg @@ -53,14 +53,25 @@ required: - clocks - clock-names +allOf: + - $ref: serial.yaml# + - if: + properties: + compatible: + contains: + const: cdns,uart-r1p8 + then: + properties: + power-domains: false + unevaluatedProperties: false examples: - | uart0: serial@e0000000 { - compatible = "xlnx,xuartps", "cdns,uart-r1p8"; - clocks = <&clkc 23>, <&clkc 40>; - clock-names = "uart_clk", "pclk"; - reg = <0xE0000000 0x1000>; - interrupts = <0 27 4>; + compatible = "xlnx,xuartps", "cdns,uart-r1p8"; + clocks = <&clkc 23>, <&clkc 40>; + clock-names = "uart_clk", "pclk"; + reg = <0xe0000000 0x1000>; + interrupts = <0 27 4>; }; diff --git a/Documentation/devicetree/bindings/serial/fsl,s32-linflexuart.yaml b/Documentation/devicetree/bindings/serial/fsl,s32-linflexuart.yaml index 8b643bae3c7b..920539926d7e 100644 --- a/Documentation/devicetree/bindings/serial/fsl,s32-linflexuart.yaml +++ b/Documentation/devicetree/bindings/serial/fsl,s32-linflexuart.yaml @@ -16,7 +16,7 @@ maintainers: - Chester Lin <clin@suse.com> allOf: - - $ref: "serial.yaml" + - $ref: serial.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml b/Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml index 9d949296a142..4cbe76e1715b 100644 --- a/Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml +++ b/Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml @@ -10,8 +10,8 @@ maintainers: - Fabio Estevam <festevam@gmail.com> allOf: - - $ref: "serial.yaml" - - $ref: "rs485.yaml" + - $ref: serial.yaml# + - $ref: rs485.yaml# properties: compatible: @@ -83,13 +83,6 @@ properties: are sensible for most use cases. If you need low latency processing on slow connections this needs to be configured appropriately. - uart-has-rtscts: true - - rs485-rts-delay: true - rs485-rts-active-low: true - rs485-rx-during-tx: true - linux,rs485-enabled-at-boot-time: true - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml b/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml index 74f75f669e77..ab81722293d3 100644 --- a/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml +++ b/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml @@ -10,7 +10,8 @@ maintainers: - Fugang Duan <fugang.duan@nxp.com> allOf: - - $ref: "rs485.yaml" + - $ref: rs485.yaml# + - $ref: serial.yaml# properties: compatible: @@ -64,9 +65,6 @@ properties: - const: rx - const: tx - rs485-rts-active-low: true - linux,rs485-enabled-at-boot-time: true - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/serial/fsl-mxs-auart.yaml b/Documentation/devicetree/bindings/serial/fsl-mxs-auart.yaml index 14c7594c88c6..6a400a5e6fc7 100644 --- a/Documentation/devicetree/bindings/serial/fsl-mxs-auart.yaml +++ b/Documentation/devicetree/bindings/serial/fsl-mxs-auart.yaml @@ -10,7 +10,7 @@ maintainers: - Fabio Estevam <festevam@gmail.com> allOf: - - $ref: "serial.yaml" + - $ref: serial.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/serial/pl011.yaml b/Documentation/devicetree/bindings/serial/pl011.yaml index 80af72859876..9571041030b7 100644 --- a/Documentation/devicetree/bindings/serial/pl011.yaml +++ b/Documentation/devicetree/bindings/serial/pl011.yaml @@ -10,6 +10,7 @@ maintainers: - Rob Herring <robh@kernel.org> allOf: + - $ref: /schemas/arm/primecell.yaml# - $ref: serial.yaml# # Need a custom select here or 'arm,primecell' will match on lots of nodes diff --git a/Documentation/devicetree/bindings/serial/qcom,msm-uart.txt b/Documentation/devicetree/bindings/serial/qcom,msm-uart.txt deleted file mode 100644 index ce8c90161959..000000000000 --- a/Documentation/devicetree/bindings/serial/qcom,msm-uart.txt +++ /dev/null @@ -1,25 +0,0 @@ -* MSM Serial UART - -The MSM serial UART hardware is designed for low-speed use cases where a -dma-engine isn't needed. From a software perspective it's mostly compatible -with the MSM serial UARTDM except that it only supports reading and writing one -character at a time. - -Required properties: -- compatible: Should contain "qcom,msm-uart" -- reg: Should contain UART register location and length. -- interrupts: Should contain UART interrupt. -- clocks: Should contain the core clock. -- clock-names: Should be "core". - -Example: - -A uart device at 0xa9c00000 with interrupt 11. - -serial@a9c00000 { - compatible = "qcom,msm-uart"; - reg = <0xa9c00000 0x1000>; - interrupts = <11>; - clocks = <&uart_cxc>; - clock-names = "core"; -}; diff --git a/Documentation/devicetree/bindings/serial/qcom,msm-uart.yaml b/Documentation/devicetree/bindings/serial/qcom,msm-uart.yaml new file mode 100644 index 000000000000..a052aaef21f4 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/qcom,msm-uart.yaml @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/serial/qcom,msm-uart.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm MSM SoC Serial UART + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: + The MSM serial UART hardware is designed for low-speed use cases where a + dma-engine isn't needed. From a software perspective it's mostly compatible + with the MSM serial UARTDM except that it only supports reading and writing + one character at a time. + +properties: + compatible: + const: qcom,msm-uart + + clocks: + maxItems: 1 + + clock-names: + items: + - const: core + + interrupts: + maxItems: 1 + + reg: + maxItems: 1 + +required: + - compatible + - clock-names + - clocks + - interrupts + - reg + +unevaluatedProperties: false + +allOf: + - $ref: /schemas/serial/serial.yaml# + +examples: + - | + serial@a9c00000 { + compatible = "qcom,msm-uart"; + reg = <0xa9c00000 0x1000>; + interrupts = <11>; + clocks = <&uart_cxc>; + clock-names = "core"; + }; diff --git a/Documentation/devicetree/bindings/serial/renesas,em-uart.yaml b/Documentation/devicetree/bindings/serial/renesas,em-uart.yaml index b25aca733b72..12d0fa34f9f9 100644 --- a/Documentation/devicetree/bindings/serial/renesas,em-uart.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,em-uart.yaml @@ -66,9 +66,9 @@ examples: - | #include <dt-bindings/interrupt-controller/arm-gic.h> uart0: serial@e1020000 { - compatible = "renesas,em-uart"; - reg = <0xe1020000 0x38>; - interrupts = <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&usia_u0_sclk>; - clock-names = "sclk"; + compatible = "renesas,em-uart"; + reg = <0xe1020000 0x38>; + interrupts = <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&usia_u0_sclk>; + clock-names = "sclk"; }; diff --git a/Documentation/devicetree/bindings/serial/renesas,hscif.yaml b/Documentation/devicetree/bindings/serial/renesas,hscif.yaml index 1957b9d782e8..afedb6edfc34 100644 --- a/Documentation/devicetree/bindings/serial/renesas,hscif.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,hscif.yaml @@ -131,20 +131,20 @@ examples: #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/power/r8a7795-sysc.h> aliases { - serial1 = &hscif1; + serial1 = &hscif1; }; hscif1: serial@e6550000 { - compatible = "renesas,hscif-r8a7795", "renesas,rcar-gen3-hscif", - "renesas,hscif"; - reg = <0xe6550000 96>; - interrupts = <GIC_SPI 155 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 519>, <&cpg CPG_CORE R8A7795_CLK_S3D1>, - <&scif_clk>; - clock-names = "fck", "brg_int", "scif_clk"; - dmas = <&dmac1 0x33>, <&dmac1 0x32>, <&dmac2 0x33>, <&dmac2 0x32>; - dma-names = "tx", "rx", "tx", "rx"; - power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; - resets = <&cpg 519>; - uart-has-rtscts; + compatible = "renesas,hscif-r8a7795", "renesas,rcar-gen3-hscif", + "renesas,hscif"; + reg = <0xe6550000 96>; + interrupts = <GIC_SPI 155 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 519>, <&cpg CPG_CORE R8A7795_CLK_S3D1>, + <&scif_clk>; + clock-names = "fck", "brg_int", "scif_clk"; + dmas = <&dmac1 0x33>, <&dmac1 0x32>, <&dmac2 0x33>, <&dmac2 0x32>; + dma-names = "tx", "rx", "tx", "rx"; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + resets = <&cpg 519>; + uart-has-rtscts; }; diff --git a/Documentation/devicetree/bindings/serial/renesas,sci.yaml b/Documentation/devicetree/bindings/serial/renesas,sci.yaml index bf7708a7a2c0..dc445b327e0b 100644 --- a/Documentation/devicetree/bindings/serial/renesas,sci.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,sci.yaml @@ -91,19 +91,19 @@ examples: #include <dt-bindings/interrupt-controller/arm-gic.h> aliases { - serial0 = &sci0; + serial0 = &sci0; }; sci0: serial@1004d000 { - compatible = "renesas,r9a07g044-sci", "renesas,sci"; - reg = <0x1004d000 0x400>; - interrupts = <GIC_SPI 405 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 406 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 407 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 408 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "eri", "rxi", "txi", "tei"; - clocks = <&cpg CPG_MOD R9A07G044_SCI0_CLKP>; - clock-names = "fck"; - power-domains = <&cpg>; - resets = <&cpg R9A07G044_SCI0_RST>; + compatible = "renesas,r9a07g044-sci", "renesas,sci"; + reg = <0x1004d000 0x400>; + interrupts = <GIC_SPI 405 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 406 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 407 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 408 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "eri", "rxi", "txi", "tei"; + clocks = <&cpg CPG_MOD R9A07G044_SCI0_CLKP>; + clock-names = "fck"; + power-domains = <&cpg>; + resets = <&cpg R9A07G044_SCI0_RST>; }; diff --git a/Documentation/devicetree/bindings/serial/renesas,scif.yaml b/Documentation/devicetree/bindings/serial/renesas,scif.yaml index f81f2d67a1ed..1989bd67d04e 100644 --- a/Documentation/devicetree/bindings/serial/renesas,scif.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,scif.yaml @@ -180,19 +180,19 @@ examples: #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/power/r8a7791-sysc.h> aliases { - serial0 = &scif0; + serial0 = &scif0; }; scif0: serial@e6e60000 { - compatible = "renesas,scif-r8a7791", "renesas,rcar-gen2-scif", - "renesas,scif"; - reg = <0xe6e60000 64>; - interrupts = <GIC_SPI 152 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 721>, <&cpg CPG_CORE R8A7791_CLK_ZS>, - <&scif_clk>; - clock-names = "fck", "brg_int", "scif_clk"; - dmas = <&dmac0 0x29>, <&dmac0 0x2a>, <&dmac1 0x29>, <&dmac1 0x2a>; - dma-names = "tx", "rx", "tx", "rx"; - power-domains = <&sysc R8A7791_PD_ALWAYS_ON>; - resets = <&cpg 721>; + compatible = "renesas,scif-r8a7791", "renesas,rcar-gen2-scif", + "renesas,scif"; + reg = <0xe6e60000 64>; + interrupts = <GIC_SPI 152 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 721>, <&cpg CPG_CORE R8A7791_CLK_ZS>, + <&scif_clk>; + clock-names = "fck", "brg_int", "scif_clk"; + dmas = <&dmac0 0x29>, <&dmac0 0x2a>, <&dmac1 0x29>, <&dmac1 0x2a>; + dma-names = "tx", "rx", "tx", "rx"; + power-domains = <&sysc R8A7791_PD_ALWAYS_ON>; + resets = <&cpg 721>; }; diff --git a/Documentation/devicetree/bindings/serial/renesas,scifa.yaml b/Documentation/devicetree/bindings/serial/renesas,scifa.yaml index 3c67d3202e1b..4c3b5e7270da 100644 --- a/Documentation/devicetree/bindings/serial/renesas,scifa.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,scifa.yaml @@ -95,18 +95,18 @@ examples: #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/power/r8a7790-sysc.h> aliases { - serial0 = &scifa0; + serial0 = &scifa0; }; scifa0: serial@e6c40000 { - compatible = "renesas,scifa-r8a7790", "renesas,rcar-gen2-scifa", - "renesas,scifa"; - reg = <0xe6c40000 64>; - interrupts = <GIC_SPI 144 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 204>; - clock-names = "fck"; - power-domains = <&sysc R8A7790_PD_ALWAYS_ON>; - resets = <&cpg 204>; - dmas = <&dmac0 0x21>, <&dmac0 0x22>, <&dmac1 0x21>, <&dmac1 0x22>; - dma-names = "tx", "rx", "tx", "rx"; + compatible = "renesas,scifa-r8a7790", "renesas,rcar-gen2-scifa", + "renesas,scifa"; + reg = <0xe6c40000 64>; + interrupts = <GIC_SPI 144 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 204>; + clock-names = "fck"; + power-domains = <&sysc R8A7790_PD_ALWAYS_ON>; + resets = <&cpg 204>; + dmas = <&dmac0 0x21>, <&dmac0 0x22>, <&dmac1 0x21>, <&dmac1 0x22>; + dma-names = "tx", "rx", "tx", "rx"; }; diff --git a/Documentation/devicetree/bindings/serial/renesas,scifb.yaml b/Documentation/devicetree/bindings/serial/renesas,scifb.yaml index d5571c7a4424..2f7cbbb48960 100644 --- a/Documentation/devicetree/bindings/serial/renesas,scifb.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,scifb.yaml @@ -94,10 +94,10 @@ examples: #include <dt-bindings/clock/r8a7740-clock.h> #include <dt-bindings/interrupt-controller/arm-gic.h> scifb: serial@e6c30000 { - compatible = "renesas,scifb-r8a7740", "renesas,scifb"; - reg = <0xe6c30000 0x100>; - interrupts = <GIC_SPI 108 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&mstp2_clks R8A7740_CLK_SCIFB>; - clock-names = "fck"; - power-domains = <&pd_a3sp>; + compatible = "renesas,scifb-r8a7740", "renesas,scifb"; + reg = <0xe6c30000 0x100>; + interrupts = <GIC_SPI 108 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&mstp2_clks R8A7740_CLK_SCIFB>; + clock-names = "fck"; + power-domains = <&pd_a3sp>; }; diff --git a/Documentation/devicetree/bindings/serial/rs485.yaml b/Documentation/devicetree/bindings/serial/rs485.yaml index 789763cf427a..303a443d9e29 100644 --- a/Documentation/devicetree/bindings/serial/rs485.yaml +++ b/Documentation/devicetree/bindings/serial/rs485.yaml @@ -51,6 +51,12 @@ properties: description: GPIO pin to enable RS485 bus termination. maxItems: 1 + rs485-rx-during-tx-gpios: + description: Output GPIO pin that sets the state of rs485-rx-during-tx. This + signal can be used to control the RX part of an RS485 transceiver. Thereby + the active state enables RX during TX. + maxItems: 1 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/serial/serial.yaml b/Documentation/devicetree/bindings/serial/serial.yaml index 11e822bf09e2..c9231e501f1f 100644 --- a/Documentation/devicetree/bindings/serial/serial.yaml +++ b/Documentation/devicetree/bindings/serial/serial.yaml @@ -96,7 +96,7 @@ then: rts-gpios: false patternProperties: - ".*": + "^bluetooth|gnss|gps|mcu$": if: type: object then: @@ -141,13 +141,13 @@ additionalProperties: true examples: - | serial@1234 { - compatible = "ns16550a"; - reg = <0x1234 0x20>; - interrupts = <1>; - - bluetooth { - compatible = "brcm,bcm4330-bt"; - interrupt-parent = <&gpio>; - interrupts = <10>; - }; + compatible = "ns16550a"; + reg = <0x1234 0x20>; + interrupts = <1>; + + bluetooth { + compatible = "brcm,bcm4330-bt"; + interrupt-parent = <&gpio>; + interrupts = <10>; + }; }; diff --git a/Documentation/devicetree/bindings/serial/sifive-serial.yaml b/Documentation/devicetree/bindings/serial/sifive-serial.yaml index b0a8871e3641..b0df1cac4968 100644 --- a/Documentation/devicetree/bindings/serial/sifive-serial.yaml +++ b/Documentation/devicetree/bindings/serial/sifive-serial.yaml @@ -53,13 +53,13 @@ unevaluatedProperties: false examples: - | - #include <dt-bindings/clock/sifive-fu540-prci.h> - serial@10010000 { + #include <dt-bindings/clock/sifive-fu540-prci.h> + serial@10010000 { compatible = "sifive,fu540-c000-uart", "sifive,uart0"; interrupt-parent = <&plic0>; interrupts = <80>; reg = <0x10010000 0x1000>; clocks = <&prci FU540_PRCI_CLK_TLCLK>; - }; + }; ... diff --git a/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.yaml b/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.yaml index b9c2287c5d1e..2becdfab4f15 100644 --- a/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.yaml +++ b/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.yaml @@ -67,6 +67,14 @@ properties: - const: baudclk - const: apb_pclk + dmas: + minItems: 2 + + dma-names: + items: + - const: rx + - const: tx + snps,uart-16550-compatible: description: reflects the value of UART_16550_COMPATIBLE configuration parameter. Define this if your UART does not implement the busy functionality. diff --git a/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml b/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml index 85876c668f6d..1df8ffe95fc6 100644 --- a/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml +++ b/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml @@ -35,8 +35,6 @@ properties: description: enable hardware flow control (deprecated) $ref: /schemas/types.yaml#/definitions/flag - uart-has-rtscts: true - rx-tx-swap: true dmas: @@ -60,11 +58,6 @@ properties: wakeup-source: true - rs485-rts-delay: true - rs485-rts-active-low: true - linux,rs485-enabled-at-boot-time: true - rs485-rx-during-tx: true - rx-threshold: description: If value is set to 1, RX FIFO threshold is disabled. diff --git a/Documentation/devicetree/bindings/serial/xlnx,opb-uartlite.yaml b/Documentation/devicetree/bindings/serial/xlnx,opb-uartlite.yaml index 2f4390e8d4e8..08dcb275d8e2 100644 --- a/Documentation/devicetree/bindings/serial/xlnx,opb-uartlite.yaml +++ b/Documentation/devicetree/bindings/serial/xlnx,opb-uartlite.yaml @@ -63,7 +63,7 @@ required: - xlnx,use-parity allOf: - - $ref: /schemas/serial.yaml# + - $ref: serial.yaml# - if: properties: xlnx,use-parity: @@ -76,7 +76,7 @@ unevaluatedProperties: false examples: - | - serial@800c0000 { + serial@800c0000 { compatible = "xlnx,xps-uartlite-1.00.a"; reg = <0x800c0000 0x10000>; interrupts = <0x0 0x6e 0x1>; @@ -84,5 +84,5 @@ examples: current-speed = <115200>; xlnx,data-bits = <8>; xlnx,use-parity = <0>; - }; + }; ... diff --git a/Documentation/devicetree/bindings/soc/imx/fsl,imx-iomuxc-gpr.yaml b/Documentation/devicetree/bindings/soc/imx/fsl,imx-iomuxc-gpr.yaml new file mode 100644 index 000000000000..1da1b758b4ae --- /dev/null +++ b/Documentation/devicetree/bindings/soc/imx/fsl,imx-iomuxc-gpr.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/imx/fsl,imx-iomuxc-gpr.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale IOMUX Controller General Purpose Registers + +maintainers: + - Peng Fan <peng.fan@nxp.com> + +description: + i.MX Processors have an IOMUXC General Purpose Register group for + various System Settings + +properties: + compatible: + oneOf: + - items: + - const: fsl,imx8mq-iomuxc-gpr + - const: syscon + - const: simple-mfd + - items: + - enum: + - fsl,imx8mm-iomuxc-gpr + - fsl,imx8mn-iomuxc-gpr + - fsl,imx8mp-iomuxc-gpr + - const: syscon + + reg: + maxItems: 1 + + mux-controller: + type: object + $ref: /schemas/mux/reg-mux.yaml + +additionalProperties: false + +required: + - compatible + - reg + +examples: + # Pinmux controller node + - | + iomuxc_gpr: syscon@30340000 { + compatible = "fsl,imx8mq-iomuxc-gpr", "syscon", "simple-mfd"; + reg = <0x30340000 0x10000>; + + mux: mux-controller { + compatible = "mmio-mux"; + #mux-control-cells = <1>; + mux-reg-masks = <0x34 0x00000004>; /* MIPI_MUX_SEL */ + }; + }; + +... diff --git a/Documentation/devicetree/bindings/soc/imx/fsl,imx8mp-hsio-blk-ctrl.yaml b/Documentation/devicetree/bindings/soc/imx/fsl,imx8mp-hsio-blk-ctrl.yaml index c29181a9745b..1fe68b53b1d8 100644 --- a/Documentation/devicetree/bindings/soc/imx/fsl,imx8mp-hsio-blk-ctrl.yaml +++ b/Documentation/devicetree/bindings/soc/imx/fsl,imx8mp-hsio-blk-ctrl.yaml @@ -39,6 +39,9 @@ properties: - const: pcie - const: pcie-phy + '#clock-cells': + const: 0 + clocks: minItems: 2 maxItems: 2 @@ -85,4 +88,5 @@ examples: power-domain-names = "bus", "usb", "usb-phy1", "usb-phy2", "pcie", "pcie-phy"; #power-domain-cells = <1>; + #clock-cells = <0>; }; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,apr-services.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,apr-services.yaml index 290555426c39..bdf482db32aa 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,apr-services.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,apr-services.yaml @@ -39,8 +39,8 @@ properties: qcom,protection-domain: $ref: /schemas/types.yaml#/definitions/string-array description: | - Protection domain service name and path for APR service - possible values are:: + Protection domain service name and path for APR service (if supported). + Possible values are:: "avs/audio", "msm/adsp/audio_pd". "kernel/elf_loader", "msm/modem/wlan_pd". "tms/servreg", "msm/adsp/audio_pd". @@ -49,6 +49,5 @@ properties: required: - reg - - qcom,protection-domain additionalProperties: true diff --git a/Documentation/devicetree/bindings/soc/renesas/renesas,rzv2m-pwc.yaml b/Documentation/devicetree/bindings/soc/renesas/renesas,rzv2m-pwc.yaml new file mode 100644 index 000000000000..12df33f58484 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/renesas/renesas,rzv2m-pwc.yaml @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/renesas/renesas,rzv2m-pwc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/V2M External Power Sequence Controller (PWC) + +description: |+ + The PWC IP found in the RZ/V2M family of chips comes with the below + capabilities + - external power supply on/off sequence generation + - on/off signal generation for the LPDDR4 core power supply (LPVDD) + - key input signals processing + - general-purpose output pins + +maintainers: + - Fabrizio Castro <fabrizio.castro.jz@renesas.com> + +properties: + compatible: + items: + - enum: + - renesas,r9a09g011-pwc # RZ/V2M + - renesas,r9a09g055-pwc # RZ/V2MA + - const: renesas,rzv2m-pwc + + reg: + maxItems: 1 + + gpio-controller: true + + '#gpio-cells': + const: 2 + + renesas,rzv2m-pwc-power: + description: The PWC is used to control the system power supplies. + type: boolean + +required: + - compatible + - reg + - gpio-controller + - '#gpio-cells' + +additionalProperties: false + +examples: + - | + pwc: pwc@a3700000 { + compatible = "renesas,r9a09g011-pwc", "renesas,rzv2m-pwc"; + reg = <0xa3700000 0x800>; + gpio-controller; + #gpio-cells = <2>; + renesas,rzv2m-pwc-power; + }; diff --git a/Documentation/devicetree/bindings/soc/rockchip/grf.yaml b/Documentation/devicetree/bindings/soc/rockchip/grf.yaml index 2ed8cca79b59..e697c928900d 100644 --- a/Documentation/devicetree/bindings/soc/rockchip/grf.yaml +++ b/Documentation/devicetree/bindings/soc/rockchip/grf.yaml @@ -20,6 +20,11 @@ properties: - rockchip,rk3568-pipe-grf - rockchip,rk3568-pipe-phy-grf - rockchip,rk3568-usb2phy-grf + - rockchip,rk3588-bigcore0-grf + - rockchip,rk3588-bigcore1-grf + - rockchip,rk3588-ioc + - rockchip,rk3588-php-grf + - rockchip,rk3588-sys-grf - rockchip,rk3588-pcie3-phy-grf - rockchip,rk3588-pcie3-pipe-grf - rockchip,rv1108-usbgrf @@ -92,8 +97,9 @@ allOf: then: properties: edp-phy: - description: - Documentation/devicetree/bindings/phy/rockchip-dp-phy.txt + type: object + $ref: /schemas/phy/rockchip,rk3288-dp-phy.yaml# + unevaluatedProperties: false - if: properties: @@ -200,7 +206,7 @@ allOf: "usb2phy@[0-9a-f]+$": type: object - $ref: "/schemas/phy/phy-rockchip-inno-usb2.yaml#" + $ref: /schemas/phy/rockchip,inno-usb2phy.yaml# unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/soc/samsung/exynos-pmu.yaml b/Documentation/devicetree/bindings/soc/samsung/exynos-pmu.yaml index 13bb8dfcefe6..f7c141dd11ec 100644 --- a/Documentation/devicetree/bindings/soc/samsung/exynos-pmu.yaml +++ b/Documentation/devicetree/bindings/soc/samsung/exynos-pmu.yaml @@ -31,20 +31,28 @@ select: properties: compatible: - items: - - enum: - - samsung,exynos3250-pmu - - samsung,exynos4210-pmu - - samsung,exynos4412-pmu - - samsung,exynos5250-pmu - - samsung,exynos5260-pmu - - samsung,exynos5410-pmu - - samsung,exynos5420-pmu - - samsung,exynos5433-pmu - - samsung,exynos7-pmu - - samsung,exynos850-pmu - - samsung-s5pv210-pmu - - const: syscon + oneOf: + - items: + - enum: + - samsung,exynos3250-pmu + - samsung,exynos4210-pmu + - samsung,exynos4412-pmu + - samsung,exynos5250-pmu + - samsung,exynos5260-pmu + - samsung,exynos5410-pmu + - samsung,exynos5420-pmu + - samsung,exynos5433-pmu + - samsung,exynos7-pmu + - samsung,exynos850-pmu + - samsung-s5pv210-pmu + - const: syscon + - items: + - enum: + - samsung,exynos5250-pmu + - samsung,exynos5420-pmu + - samsung,exynos5433-pmu + - const: simple-mfd + - const: syscon reg: maxItems: 1 @@ -64,6 +72,10 @@ properties: minItems: 1 maxItems: 32 + dp-phy: + $ref: /schemas/phy/samsung,dp-video-phy.yaml + unevaluatedProperties: false + interrupt-controller: description: Some PMUs are capable of behaving as an interrupt controller (mostly @@ -74,6 +86,10 @@ properties: Must be identical to the that of the parent interrupt controller. const: 3 + mipi-phy: + $ref: /schemas/phy/samsung,mipi-video-phy.yaml + unevaluatedProperties: false + reboot-mode: $ref: /schemas/power/reset/syscon-reboot-mode.yaml type: object @@ -117,6 +133,23 @@ allOf: - clock-names - clocks + - if: + properties: + compatible: + contains: + enum: + - samsung,exynos5250-pmu + - samsung,exynos5420-pmu + - samsung,exynos5433-pmu + then: + properties: + dp-phy: true + mipi-phy: true + else: + properties: + dp-phy: false + mipi-phy: false + examples: - | #include <dt-bindings/clock/exynos5250.h> @@ -130,4 +163,14 @@ examples: #clock-cells = <1>; clock-names = "clkout16"; clocks = <&clock CLK_FIN_PLL>; + + dp-phy { + compatible = "samsung,exynos5250-dp-video-phy"; + #phy-cells = <0>; + }; + + mipi-phy { + compatible = "samsung,s5pv210-mipi-video-phy"; + #phy-cells = <1>; + }; }; diff --git a/Documentation/devicetree/bindings/soc/samsung/samsung,exynos-sysreg.yaml b/Documentation/devicetree/bindings/soc/samsung/samsung,exynos-sysreg.yaml new file mode 100644 index 000000000000..163e912e9cad --- /dev/null +++ b/Documentation/devicetree/bindings/soc/samsung/samsung,exynos-sysreg.yaml @@ -0,0 +1,87 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/samsung/samsung,exynos-sysreg.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Exynos SoC series System Registers (SYSREG) + +maintainers: + - Krzysztof Kozlowski <krzk@kernel.org> + +properties: + compatible: + oneOf: + - items: + - enum: + - samsung,exynos3-sysreg + - samsung,exynos4-sysreg + - samsung,exynos5-sysreg + - tesla,fsd-cam-sysreg + - tesla,fsd-fsys0-sysreg + - tesla,fsd-fsys1-sysreg + - tesla,fsd-peric-sysreg + - const: syscon + - items: + - enum: + - samsung,exynos5433-cam0-sysreg + - samsung,exynos5433-cam1-sysreg + - samsung,exynos5433-disp-sysreg + - samsung,exynos5433-fsys-sysreg + - const: samsung,exynos5433-sysreg + - const: syscon + - items: + - enum: + - samsung,exynos5433-sysreg + - samsung,exynos850-sysreg + - samsung,exynosautov9-sysreg + - const: syscon + deprecated: true + - items: + - enum: + - samsung,exynos850-cmgp-sysreg + - samsung,exynos850-peri-sysreg + - const: samsung,exynos850-sysreg + - const: syscon + - items: + - enum: + - samsung,exynosautov9-fsys2-sysreg + - samsung,exynosautov9-peric0-sysreg + - samsung,exynosautov9-peric1-sysreg + - const: samsung,exynosautov9-sysreg + - const: syscon + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + +allOf: + - if: + properties: + compatible: + contains: + enum: + - samsung,exynos850-cmgp-sysreg + - samsung,exynos850-peri-sysreg + - samsung,exynos850-sysreg + then: + required: + - clocks + else: + properties: + clocks: false + +additionalProperties: false + +examples: + - | + system-controller@10010000 { + compatible = "samsung,exynos4-sysreg", "syscon"; + reg = <0x10010000 0x400>; + }; diff --git a/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-adamv.yaml b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-adamv.yaml new file mode 100644 index 000000000000..32d9cc2d72a8 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-adamv.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/socionext/socionext,uniphier-adamv.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext UniPhier ADAMV block + +maintainers: + - Kunihiko Hayashi <hayashi.kunihiko@socionext.com> + +description: |+ + ADAMV block implemented on Socionext UniPhier SoCs is an analog signal + amplifier that is a part of the external video and audio I/O system. + + This block is defined for controlling audio I/O reset only. + +properties: + compatible: + items: + - enum: + - socionext,uniphier-ld11-adamv + - socionext,uniphier-ld20-adamv + - const: simple-mfd + - const: syscon + + reg: + maxItems: 1 + + reset-controller: + $ref: /schemas/reset/socionext,uniphier-reset.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + syscon@57920000 { + compatible = "socionext,uniphier-ld20-adamv", + "simple-mfd", "syscon"; + reg = <0x57920000 0x1000>; + + reset-controller { + compatible = "socionext,uniphier-ld20-adamv-reset"; + #reset-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-ahci-glue.yaml b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-ahci-glue.yaml new file mode 100644 index 000000000000..09f861cc068f --- /dev/null +++ b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-ahci-glue.yaml @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/socionext/socionext,uniphier-ahci-glue.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext UniPhier SoC AHCI glue layer + +maintainers: + - Kunihiko Hayashi <hayashi.kunihiko@socionext.com> + +description: |+ + AHCI glue layer implemented on Socionext UniPhier SoCs is a sideband + logic handling signals to AHCI host controller inside AHCI component. + +properties: + compatible: + items: + - enum: + - socionext,uniphier-pro4-ahci-glue + - socionext,uniphier-pxs2-ahci-glue + - socionext,uniphier-pxs3-ahci-glue + - const: simple-mfd + + reg: + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + ranges: true + +patternProperties: + "^reset-controller@[0-9a-f]+$": + $ref: /schemas/reset/socionext,uniphier-glue-reset.yaml# + + "phy@[0-9a-f]+$": + $ref: /schemas/phy/socionext,uniphier-ahci-phy.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + sata-controller@65700000 { + compatible = "socionext,uniphier-pxs3-ahci-glue", "simple-mfd"; + reg = <0x65b00000 0x400>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x65700000 0x100>; + + reset-controller@0 { + compatible = "socionext,uniphier-pxs3-ahci-reset"; + reg = <0x0 0x4>; + clock-names = "link"; + clocks = <&sys_clk 28>; + reset-names = "link"; + resets = <&sys_rst 28>; + #reset-cells = <1>; + }; + + phy@10 { + compatible = "socionext,uniphier-pxs3-ahci-phy"; + reg = <0x10 0x10>; + clock-names = "link", "phy"; + clocks = <&sys_clk 28>, <&sys_clk 30>; + reset-names = "link", "phy"; + resets = <&sys_rst 28>, <&sys_rst 30>; + #phy-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-dwc3-glue.yaml b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-dwc3-glue.yaml new file mode 100644 index 000000000000..bd0def7236b5 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-dwc3-glue.yaml @@ -0,0 +1,106 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/socionext/socionext,uniphier-dwc3-glue.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext UniPhier SoC DWC3 USB3.0 glue layer + +maintainers: + - Kunihiko Hayashi <hayashi.kunihiko@socionext.com> + +description: |+ + DWC3 USB3.0 glue layer implemented on Socionext UniPhier SoCs is + a sideband logic handling signals to DWC3 host controller inside + USB3.0 component. + +properties: + compatible: + items: + - enum: + - socionext,uniphier-pro4-dwc3-glue + - socionext,uniphier-pro5-dwc3-glue + - socionext,uniphier-pxs2-dwc3-glue + - socionext,uniphier-ld20-dwc3-glue + - socionext,uniphier-pxs3-dwc3-glue + - socionext,uniphier-nx1-dwc3-glue + - const: simple-mfd + + reg: + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + ranges: true + +patternProperties: + "^reset-controller@[0-9a-f]+$": + $ref: /schemas/reset/socionext,uniphier-glue-reset.yaml# + + "^regulator@[0-9a-f]+$": + $ref: /schemas/regulator/socionext,uniphier-regulator.yaml# + + "^phy@[0-9a-f]+$": + oneOf: + - $ref: /schemas/phy/socionext,uniphier-usb3hs-phy.yaml# + - $ref: /schemas/phy/socionext,uniphier-usb3ss-phy.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + usb@65b00000 { + compatible = "socionext,uniphier-ld20-dwc3-glue", "simple-mfd"; + reg = <0x65b00000 0x400>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x65b00000 0x400>; + + reset-controller@0 { + compatible = "socionext,uniphier-ld20-usb3-reset"; + reg = <0x0 0x4>; + #reset-cells = <1>; + clock-names = "link"; + clocks = <&sys_clk 14>; + reset-names = "link"; + resets = <&sys_rst 14>; + }; + + regulator@100 { + compatible = "socionext,uniphier-ld20-usb3-regulator"; + reg = <0x100 0x10>; + clock-names = "link"; + clocks = <&sys_clk 14>; + reset-names = "link"; + resets = <&sys_rst 14>; + }; + + phy@200 { + compatible = "socionext,uniphier-ld20-usb3-hsphy"; + reg = <0x200 0x10>; + #phy-cells = <0>; + clock-names = "link", "phy"; + clocks = <&sys_clk 14>, <&sys_clk 16>; + reset-names = "link", "phy"; + resets = <&sys_rst 14>, <&sys_rst 16>; + }; + + phy@300 { + compatible = "socionext,uniphier-ld20-usb3-ssphy"; + reg = <0x300 0x10>; + #phy-cells = <0>; + clock-names = "link", "phy"; + clocks = <&sys_clk 14>, <&sys_clk 18>; + reset-names = "link", "phy"; + resets = <&sys_rst 14>, <&sys_rst 18>; + }; + }; + diff --git a/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-mioctrl.yaml b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-mioctrl.yaml new file mode 100644 index 000000000000..2cc38bb5038e --- /dev/null +++ b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-mioctrl.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/socionext/socionext,uniphier-mioctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext UniPhier media I/O block (MIO) controller + +maintainers: + - Kunihiko Hayashi <hayashi.kunihiko@socionext.com> + +description: |+ + Media I/O block implemented on Socionext UniPhier SoCs is a legacy + integrated component of the stream type peripherals including USB2.0, + SD/eMMC, and MIO-DMAC. + Media I/O block has a common logic to control the component. + + Recent SoCs have SD interface logic specialized only for SD functions + as a subset of media I/O block. See socionext,uniphier-sdctrl.yaml. + +properties: + compatible: + items: + - enum: + - socionext,uniphier-ld4-mioctrl + - socionext,uniphier-pro4-mioctrl + - socionext,uniphier-sld8-mioctrl + - socionext,uniphier-ld11-mioctrl + - const: simple-mfd + - const: syscon + + reg: + maxItems: 1 + + clock-controller: + $ref: /schemas/clock/socionext,uniphier-clock.yaml# + + reset-controller: + $ref: /schemas/reset/socionext,uniphier-reset.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + syscon@5b3e0000 { + compatible = "socionext,uniphier-ld11-mioctrl", + "simple-mfd", "syscon"; + reg = <0x5b3e0000 0x800>; + + clock-controller { + compatible = "socionext,uniphier-ld11-mio-clock"; + #clock-cells = <1>; + }; + + reset-controller { + compatible = "socionext,uniphier-ld11-mio-reset"; + #reset-cells = <1>; + resets = <&sys_rst 7>; + }; + }; + diff --git a/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-perictrl.yaml b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-perictrl.yaml new file mode 100644 index 000000000000..0adcffe859ab --- /dev/null +++ b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-perictrl.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/socionext/socionext,uniphier-perictrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext UniPhier peripheral block controller + +maintainers: + - Kunihiko Hayashi <hayashi.kunihiko@socionext.com> + +description: |+ + Peripheral block implemented on Socionext UniPhier SoCs is an integrated + component of the peripherals including UART, I2C/FI2C, and SCSSI. + Peripheral block controller is a logic to control the component. + +properties: + compatible: + items: + - enum: + - socionext,uniphier-ld4-perictrl + - socionext,uniphier-pro4-perictrl + - socionext,uniphier-pro5-perictrl + - socionext,uniphier-pxs2-perictrl + - socionext,uniphier-sld8-perictrl + - socionext,uniphier-ld11-perictrl + - socionext,uniphier-ld20-perictrl + - socionext,uniphier-pxs3-perictrl + - socionext,uniphier-nx1-perictrl + - const: simple-mfd + - const: syscon + + reg: + maxItems: 1 + + clock-controller: + $ref: /schemas/clock/socionext,uniphier-clock.yaml# + + reset-controller: + $ref: /schemas/reset/socionext,uniphier-reset.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + syscon@59820000 { + compatible = "socionext,uniphier-ld20-perictrl", + "simple-mfd", "syscon"; + reg = <0x59820000 0x200>; + + clock-controller { + compatible = "socionext,uniphier-ld20-peri-clock"; + #clock-cells = <1>; + }; + + reset-controller { + compatible = "socionext,uniphier-ld20-peri-reset"; + #reset-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-sdctrl.yaml b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-sdctrl.yaml new file mode 100644 index 000000000000..cb3b0d42739f --- /dev/null +++ b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-sdctrl.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/socionext/socionext,uniphier-sdctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext UniPhier SD interface logic + +maintainers: + - Kunihiko Hayashi <hayashi.kunihiko@socionext.com> + +description: |+ + SD interface logic implemented on Socionext UniPhier SoCs is + attached outside SDHC, and has some SD related functions such as + clock control, reset control, mode switch, and so on. + +properties: + compatible: + items: + - enum: + - socionext,uniphier-pro5-sdctrl + - socionext,uniphier-pxs2-sdctrl + - socionext,uniphier-ld11-sdctrl + - socionext,uniphier-ld20-sdctrl + - socionext,uniphier-pxs3-sdctrl + - socionext,uniphier-nx1-sdctrl + - const: simple-mfd + - const: syscon + + reg: + maxItems: 1 + + clock-controller: + $ref: /schemas/clock/socionext,uniphier-clock.yaml# + + reset-controller: + $ref: /schemas/reset/socionext,uniphier-reset.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + syscon@59810000 { + compatible = "socionext,uniphier-ld20-sdctrl", + "simple-mfd", "syscon"; + reg = <0x59810000 0x400>; + + clock-controller { + compatible = "socionext,uniphier-ld20-sd-clock"; + #clock-cells = <1>; + }; + + reset-controller { + compatible = "socionext,uniphier-ld20-sd-reset"; + #reset-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-soc-glue-debug.yaml b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-soc-glue-debug.yaml new file mode 100644 index 000000000000..1341544d1df5 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-soc-glue-debug.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/socionext/socionext,uniphier-soc-glue-debug.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext UniPhier SoC-glue logic debug part + +maintainers: + - Kunihiko Hayashi <hayashi.kunihiko@socionext.com> + +description: |+ + SoC-glue logic debug part implemented on Socionext UniPhier SoCs is + a collection of miscellaneous function registers handling signals outside + system components for debug and monitor use. + +properties: + compatible: + items: + - enum: + - socionext,uniphier-ld4-soc-glue-debug + - socionext,uniphier-pro4-soc-glue-debug + - socionext,uniphier-pro5-soc-glue-debug + - socionext,uniphier-pxs2-soc-glue-debug + - socionext,uniphier-sld8-soc-glue-debug + - socionext,uniphier-ld11-soc-glue-debug + - socionext,uniphier-ld20-soc-glue-debug + - socionext,uniphier-pxs3-soc-glue-debug + - socionext,uniphier-nx1-soc-glue-debug + - const: simple-mfd + - const: syscon + + reg: + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + ranges: true + +patternProperties: + "^efuse@[0-9a-f]+$": + $ref: /schemas/nvmem/socionext,uniphier-efuse.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + syscon@5f900000 { + compatible = "socionext,uniphier-pxs2-soc-glue-debug", + "simple-mfd", "syscon"; + reg = <0x5f900000 0x2000>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x5f900000 0x2000>; + + efuse@100 { + compatible = "socionext,uniphier-efuse"; + reg = <0x100 0x28>; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-soc-glue.yaml b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-soc-glue.yaml new file mode 100644 index 000000000000..7845dcfca986 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-soc-glue.yaml @@ -0,0 +1,114 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/socionext/socionext,uniphier-soc-glue.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext UniPhier SoC-glue logic + +maintainers: + - Kunihiko Hayashi <hayashi.kunihiko@socionext.com> + +description: |+ + SoC-glue logic implemented on Socionext UniPhier SoCs is a collection of + miscellaneous function registers handling signals outside system components. + +properties: + compatible: + items: + - enum: + - socionext,uniphier-ld4-soc-glue + - socionext,uniphier-pro4-soc-glue + - socionext,uniphier-pro5-soc-glue + - socionext,uniphier-pxs2-soc-glue + - socionext,uniphier-sld8-soc-glue + - socionext,uniphier-ld11-soc-glue + - socionext,uniphier-ld20-soc-glue + - socionext,uniphier-pxs3-soc-glue + - socionext,uniphier-nx1-soc-glue + - const: simple-mfd + - const: syscon + + reg: + maxItems: 1 + + pinctrl: + $ref: /schemas/pinctrl/socionext,uniphier-pinctrl.yaml# + + usb-hub: + $ref: /schemas/phy/socionext,uniphier-usb2-phy.yaml# + + clock-controller: + $ref: /schemas/clock/socionext,uniphier-clock.yaml# + +allOf: + - if: + not: + properties: + compatible: + contains: + enum: + - socionext,uniphier-pro4-soc-glue + - socionext,uniphier-ld11-soc-glue + then: + properties: + usb-hub: false + + - if: + not: + properties: + compatible: + contains: + const: socionext,uniphier-pro4-soc-glue + then: + properties: + clock-controller: false + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + syscon@5f800000 { + compatible = "socionext,uniphier-pro4-soc-glue", + "simple-mfd", "syscon"; + reg = <0x5f800000 0x2000>; + + pinctrl { + compatible = "socionext,uniphier-pro4-pinctrl"; + }; + + usb-hub { + compatible = "socionext,uniphier-pro4-usb2-phy"; + #address-cells = <1>; + #size-cells = <0>; + + phy@0 { + reg = <0>; + #phy-cells = <0>; + }; + + phy@1 { + reg = <1>; + #phy-cells = <0>; + }; + + phy@2 { + reg = <2>; + #phy-cells = <0>; + }; + + phy@3 { + reg = <3>; + #phy-cells = <0>; + }; + }; + + clock-controller { + compatible = "socionext,uniphier-pro4-sg-clock"; + #clock-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-sysctrl.yaml b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-sysctrl.yaml new file mode 100644 index 000000000000..3acb14201d1a --- /dev/null +++ b/Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-sysctrl.yaml @@ -0,0 +1,104 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/socionext/socionext,uniphier-sysctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext UniPhier system controller + +maintainers: + - Kunihiko Hayashi <hayashi.kunihiko@socionext.com> + +description: |+ + System controller implemented on Socionext UniPhier SoCs has multiple + functions such as clock control, reset control, internal watchdog timer, + thermal management, and so on. + +properties: + compatible: + items: + - enum: + - socionext,uniphier-ld4-sysctrl + - socionext,uniphier-pro4-sysctrl + - socionext,uniphier-pro5-sysctrl + - socionext,uniphier-pxs2-sysctrl + - socionext,uniphier-sld8-sysctrl + - socionext,uniphier-ld11-sysctrl + - socionext,uniphier-ld20-sysctrl + - socionext,uniphier-pxs3-sysctrl + - socionext,uniphier-nx1-sysctrl + - const: simple-mfd + - const: syscon + + reg: + maxItems: 1 + + clock-controller: + $ref: /schemas/clock/socionext,uniphier-clock.yaml# + + reset-controller: + $ref: /schemas/reset/socionext,uniphier-reset.yaml# + + watchdog: + $ref: /schemas/watchdog/socionext,uniphier-wdt.yaml# + + thermal-sensor: + $ref: /schemas/thermal/socionext,uniphier-thermal.yaml# + +allOf: + - if: + properties: + compatible: + contains: + const: socionext,uniphier-ld4-sysctrl + then: + properties: + watchdog: false + + - if: + properties: + compatible: + contains: + enum: + - socionext,uniphier-ld4-sysctrl + - socionext,uniphier-pro4-sysctrl + - socionext,uniphier-sld8-sysctrl + - socionext,uniphier-ld11-sysctrl + then: + properties: + thermal-sensor: false + +additionalProperties: false + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + syscon@61840000 { + compatible = "socionext,uniphier-ld20-sysctrl", + "simple-mfd", "syscon"; + reg = <0x61840000 0x4000>; + + clock-controller { + compatible = "socionext,uniphier-ld20-clock"; + #clock-cells = <1>; + }; + + reset-controller { + compatible = "socionext,uniphier-ld20-reset"; + #reset-cells = <1>; + }; + + watchdog { + compatible = "socionext,uniphier-wdt"; + }; + + thermal-sensor { + compatible = "socionext,uniphier-ld20-thermal"; + interrupts = <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>; + #thermal-sensor-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml index ddea3d41971d..22cf9002fee7 100644 --- a/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml +++ b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml @@ -25,6 +25,9 @@ description: | The Ring Accelerator is a hardware module that is responsible for accelerating management of the packet queues. The K3 SoCs can have more than one RA instances +allOf: + - $ref: /schemas/arm/keystone/ti,k3-sci-common.yaml# + properties: compatible: items: @@ -54,14 +57,6 @@ properties: $ref: /schemas/types.yaml#/definitions/uint32 description: TI-SCI RM subtype for GP ring range - ti,sci: - $ref: /schemas/types.yaml#/definitions/phandle-array - description: phandle on TI-SCI compatible System controller node - - ti,sci-dev-id: - $ref: /schemas/types.yaml#/definitions/uint32 - description: TI-SCI device id of the ring accelerator - required: - compatible - reg @@ -72,7 +67,7 @@ required: - ti,sci - ti,sci-dev-id -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/adi,adau7002.txt b/Documentation/devicetree/bindings/sound/adi,adau7002.txt deleted file mode 100644 index f144ee1abf85..000000000000 --- a/Documentation/devicetree/bindings/sound/adi,adau7002.txt +++ /dev/null @@ -1,19 +0,0 @@ -Analog Devices ADAU7002 Stereo PDM-to-I2S/TDM Converter - -Required properties: - - - compatible: Must be "adi,adau7002" - -Optional properties: - - - IOVDD-supply: Phandle and specifier for the power supply providing the IOVDD - supply as covered in Documentation/devicetree/bindings/regulator/regulator.txt - - If this property is not present it is assumed that the supply pin is - hardwired to always on. - -Example: - adau7002: pdm-to-i2s { - compatible = "adi,adau7002"; - IOVDD-supply = <&supply>; - }; diff --git a/Documentation/devicetree/bindings/sound/adi,adau7002.yaml b/Documentation/devicetree/bindings/sound/adi,adau7002.yaml new file mode 100644 index 000000000000..fcca0fde7d86 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/adi,adau7002.yaml @@ -0,0 +1,40 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/adi,adau7002.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices ADAU7002 Stereo PDM-to-I2S/TDM Converter + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + const: adi,adau7002 + + IOVDD-supply: + description: + IOVDD power supply, if skipped then it is assumed that the supply pin is + hardwired to always on. + + wakeup-delay-ms: + description: + Delay after power up needed for device to settle. + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + audio-codec { + compatible = "adi,adau7002"; + IOVDD-supply = <&pp1800_l15a>; + #sound-dai-cells = <0>; + wakeup-delay-ms = <80>; + }; diff --git a/Documentation/devicetree/bindings/sound/ak4613.yaml b/Documentation/devicetree/bindings/sound/ak4613.yaml index 010574645e6a..75e13414d6eb 100644 --- a/Documentation/devicetree/bindings/sound/ak4613.yaml +++ b/Documentation/devicetree/bindings/sound/ak4613.yaml @@ -25,6 +25,13 @@ properties: "#sound-dai-cells": const: 0 + ports: + $ref: audio-graph-port.yaml#/definitions/ports + + port: + $ref: audio-graph-port.yaml# + unevaluatedProperties: false + patternProperties: "^asahi-kasei,in[1-2]-single-end$": description: Input Pin 1 - 2. diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt deleted file mode 100644 index fa4545ed81ca..000000000000 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt +++ /dev/null @@ -1,34 +0,0 @@ -* Amlogic Audio FIFO controllers - -Required properties: -- compatible: 'amlogic,axg-toddr' or - 'amlogic,axg-toddr' or - 'amlogic,g12a-frddr' or - 'amlogic,g12a-toddr' or - 'amlogic,sm1-frddr' or - 'amlogic,sm1-toddr' -- reg: physical base address of the controller and length of memory - mapped region. -- interrupts: interrupt specifier for the fifo. -- clocks: phandle to the fifo peripheral clock provided by the audio - clock controller. -- resets: list of reset phandle, one for each entry reset-names. -- reset-names: should contain the following: - * "arb" : memory ARB line (required) - * "rst" : dedicated device reset line (optional) -- #sound-dai-cells: must be 0. -- amlogic,fifo-depth: The size of the controller's fifo in bytes. This - is useful for determining certain configuration such - as the flush threshold of the fifo - -Example of FRDDR A on the A113 SoC: - -frddr_a: audio-controller@1c0 { - compatible = "amlogic,axg-frddr"; - reg = <0x0 0x1c0 0x0 0x1c>; - #sound-dai-cells = <0>; - interrupts = <GIC_SPI 88 IRQ_TYPE_EDGE_RISING>; - clocks = <&clkc_audio AUD_CLKID_FRDDR_A>; - resets = <&arb AXG_ARB_FRDDR_A>; - fifo-depth = <512>; -}; diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.yaml b/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.yaml new file mode 100644 index 000000000000..b1b48d683101 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.yaml @@ -0,0 +1,112 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/amlogic,axg-fifo.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic AXG Audio FIFO controllers + +maintainers: + - Jerome Brunet <jbrunet@baylibre.com> + +properties: + compatible: + oneOf: + - enum: + - amlogic,axg-toddr + - amlogic,axg-frddr + - items: + - enum: + - amlogic,g12a-toddr + - amlogic,sm1-toddr + - const: amlogic,axg-toddr + - items: + - enum: + - amlogic,g12a-frddr + - amlogic,sm1-frddr + - const: amlogic,axg-frddr + + reg: + maxItems: 1 + + "#sound-dai-cells": + const: 0 + + clocks: + items: + - description: Peripheral clock + + interrupts: + maxItems: 1 + + resets: + minItems: 1 + maxItems: 2 + + reset-names: + minItems: 1 + maxItems: 2 + + amlogic,fifo-depth: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Size of the controller's fifo in bytes + +required: + - compatible + - reg + - "#sound-dai-cells" + - clocks + - interrupts + - resets + - amlogic,fifo-depth + +allOf: + - $ref: dai-common.yaml# + - if: + properties: + compatible: + contains: + enum: + - amlogic,g12a-toddr + - amlogic,sm1-toddr + - amlogic,g12a-frddr + - amlogic,sm1-frddr + + then: + properties: + resets: + minItems: 2 + reset-names: + items: + - const: arb + - const: rst + required: + - reset-names + + else: + properties: + resets: + maxItems: 1 + reset-names: + const: arb + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/axg-audio-clkc.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/reset/amlogic,meson-axg-audio-arb.h> + #include <dt-bindings/reset/amlogic,meson-g12a-audio-reset.h> + + audio-controller@1c0 { + compatible = "amlogic,g12a-frddr", "amlogic,axg-frddr"; + reg = <0x1c0 0x1c>; + #sound-dai-cells = <0>; + clocks = <&clkc_audio AUD_CLKID_FRDDR_A>; + interrupts = <GIC_SPI 88 IRQ_TYPE_EDGE_RISING>; + resets = <&arb>, <&clkc_audio AUD_RESET_FRDDR_A>; + reset-names = "arb", "rst"; + amlogic,fifo-depth = <512>; + }; diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.txt deleted file mode 100644 index 716878107a24..000000000000 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.txt +++ /dev/null @@ -1,29 +0,0 @@ -* Amlogic Audio PDM input - -Required properties: -- compatible: 'amlogic,axg-pdm' or - 'amlogic,g12a-pdm' or - 'amlogic,sm1-pdm' -- reg: physical base address of the controller and length of memory - mapped region. -- clocks: list of clock phandle, one for each entry clock-names. -- clock-names: should contain the following: - * "pclk" : peripheral clock. - * "dclk" : pdm digital clock - * "sysclk" : dsp system clock -- #sound-dai-cells: must be 0. - -Optional property: -- resets: phandle to the dedicated reset line of the pdm input. - -Example of PDM on the A113 SoC: - -pdm: audio-controller@ff632000 { - compatible = "amlogic,axg-pdm"; - reg = <0x0 0xff632000 0x0 0x34>; - #sound-dai-cells = <0>; - clocks = <&clkc_audio AUD_CLKID_PDM>, - <&clkc_audio AUD_CLKID_PDM_DCLK>, - <&clkc_audio AUD_CLKID_PDM_SYSCLK>; - clock-names = "pclk", "dclk", "sysclk"; -}; diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.yaml b/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.yaml new file mode 100644 index 000000000000..df21dd72fc65 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.yaml @@ -0,0 +1,82 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/amlogic,axg-pdm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic Audio AXG PDM input + +maintainers: + - Jerome Brunet <jbrunet@baylibre.com> + +properties: + compatible: + oneOf: + - items: + - enum: + - amlogic,g12a-pdm + - amlogic,sm1-pdm + - const: amlogic,axg-pdm + - const: amlogic,axg-pdm + + reg: + maxItems: 1 + + "#sound-dai-cells": + const: 0 + + clocks: + items: + - description: Peripheral clock + - description: PDM digital clock + - description: DSP system clock + + clock-names: + items: + - const: pclk + - const: dclk + - const: sysclk + + resets: + maxItems: 1 + +required: + - compatible + - reg + - "#sound-dai-cells" + - clocks + - clock-names + +allOf: + - $ref: dai-common.yaml# + + - if: + properties: + compatible: + contains: + enum: + - amlogic,g12a-pdm + - amlogic,sm1-pdm + then: + required: + - resets + + else: + properties: + resets: false + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/axg-audio-clkc.h> + + audio-controller@ff632000 { + compatible = "amlogic,axg-pdm"; + reg = <0xff632000 0x34>; + #sound-dai-cells = <0>; + clocks = <&clkc_audio AUD_CLKID_PDM>, + <&clkc_audio AUD_CLKID_PDM_DCLK>, + <&clkc_audio AUD_CLKID_PDM_SYSCLK>; + clock-names = "pclk", "dclk", "sysclk"; + }; diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-sound-card.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-sound-card.txt deleted file mode 100644 index 80b411296480..000000000000 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-sound-card.txt +++ /dev/null @@ -1,124 +0,0 @@ -Amlogic AXG sound card: - -Required properties: - -- compatible: "amlogic,axg-sound-card" -- model : User specified audio sound card name, one string - -Optional properties: - -- audio-aux-devs : List of phandles pointing to auxiliary devices -- audio-widgets : Please refer to widgets.txt. -- audio-routing : A list of the connections between audio components. - -Subnodes: - -- dai-link: Container for dai-link level properties and the CODEC - sub-nodes. There should be at least one (and probably more) - subnode of this type. - -Required dai-link properties: - -- sound-dai: phandle and port of the CPU DAI. - -Required TDM Backend dai-link properties: -- dai-format : CPU/CODEC common audio format - -Optional TDM Backend dai-link properties: -- dai-tdm-slot-rx-mask-{0,1,2,3}: Receive direction slot masks -- dai-tdm-slot-tx-mask-{0,1,2,3}: Transmit direction slot masks - When omitted, mask is assumed to have to no - slots. A valid must have at one slot, so at - least one these mask should be provided with - an enabled slot. -- dai-tdm-slot-num : Please refer to tdm-slot.txt. - If omitted, slot number is set to accommodate the largest - mask provided. -- dai-tdm-slot-width : Please refer to tdm-slot.txt. default to 32 if omitted. -- mclk-fs : Multiplication factor between stream rate and mclk - -Backend dai-link subnodes: - -- codec: dai-link representing backend links should have at least one subnode. - One subnode for each codec of the dai-link. - dai-link representing frontend links have no codec, therefore have no - subnodes - -Required codec subnodes properties: - -- sound-dai: phandle and port of the CODEC DAI. - -Optional codec subnodes properties: - -- dai-tdm-slot-tx-mask : Please refer to tdm-slot.txt. -- dai-tdm-slot-rx-mask : Please refer to tdm-slot.txt. - -Example: - -sound { - compatible = "amlogic,axg-sound-card"; - model = "AXG-S420"; - audio-aux-devs = <&tdmin_a>, <&tdmout_c>; - audio-widgets = "Line", "Lineout", - "Line", "Linein", - "Speaker", "Speaker1 Left", - "Speaker", "Speaker1 Right"; - "Speaker", "Speaker2 Left", - "Speaker", "Speaker2 Right"; - audio-routing = "TDMOUT_C IN 0", "FRDDR_A OUT 2", - "SPDIFOUT IN 0", "FRDDR_A OUT 3", - "TDM_C Playback", "TDMOUT_C OUT", - "TDMIN_A IN 2", "TDM_C Capture", - "TDMIN_A IN 5", "TDM_C Loopback", - "TODDR_A IN 0", "TDMIN_A OUT", - "Lineout", "Lineout AOUTL", - "Lineout", "Lineout AOUTR", - "Speaker1 Left", "SPK1 OUT_A", - "Speaker2 Left", "SPK2 OUT_A", - "Speaker1 Right", "SPK1 OUT_B", - "Speaker2 Right", "SPK2 OUT_B", - "Linein AINL", "Linein", - "Linein AINR", "Linein"; - - dai-link@0 { - sound-dai = <&frddr_a>; - }; - - dai-link@1 { - sound-dai = <&toddr_a>; - }; - - dai-link@2 { - sound-dai = <&tdmif_c>; - dai-format = "i2s"; - dai-tdm-slot-tx-mask-2 = <1 1>; - dai-tdm-slot-tx-mask-3 = <1 1>; - dai-tdm-slot-rx-mask-1 = <1 1>; - mclk-fs = <256>; - - codec@0 { - sound-dai = <&lineout>; - }; - - codec@1 { - sound-dai = <&speaker_amp1>; - }; - - codec@2 { - sound-dai = <&speaker_amp2>; - }; - - codec@3 { - sound-dai = <&linein>; - }; - - }; - - dai-link@3 { - sound-dai = <&spdifout>; - - codec { - sound-dai = <&spdif_dit>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-sound-card.yaml b/Documentation/devicetree/bindings/sound/amlogic,axg-sound-card.yaml new file mode 100644 index 000000000000..bf1234550343 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-sound-card.yaml @@ -0,0 +1,183 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/amlogic,axg-sound-card.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic AXG sound card + +maintainers: + - Jerome Brunet <jbrunet@baylibre.com> + +properties: + compatible: + const: amlogic,axg-sound-card + + audio-aux-devs: + $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 + additionalProperties: false + description: + Container for dai-link level properties and the CODEC sub-nodes. + There should be at least one (and probably more) subnode of this type + + properties: + dai-format: + $ref: /schemas/types.yaml#/definitions/string + enum: [ i2s, left-j, dsp_a ] + + dai-tdm-slot-num: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Number of slots in use. If omitted, slot number is set to + accommodate the largest mask provided. + maximum: 32 + + dai-tdm-slot-width: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Width in bits for each slot + enum: [ 8, 16, 20, 24, 32 ] + default: 32 + + mclk-fs: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Multiplication factor between the frame rate and master clock + rate + + sound-dai: + maxItems: 1 + description: phandle of the CPU DAI + + patternProperties: + "^dai-tdm-slot-(t|r)x-mask-[0-3]$": + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 32 + description: + Transmit and receive cpu slot masks of each TDM lane + When omitted, mask is assumed to have to no slots. A valid + interface must have at least one slot, so at least one these + mask should be provided with an enabled slot. + + "^codec(-[0-9]+)?$": + type: object + additionalProperties: false + description: + dai-link representing backend links should have at least one subnode. + One subnode for each codec of the dai-link. dai-link representing + frontend links have no codec, therefore have no subnodes + + properties: + sound-dai: + maxItems: 1 + description: phandle of the codec DAI + + patternProperties: + "^dai-tdm-slot-(t|r)x-mask$": + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 32 + description: Transmit and receive codec slot masks + + required: + - sound-dai + + required: + - sound-dai + +required: + - model + - dai-link-0 + +unevaluatedProperties: false + +examples: + - | + sound { + compatible = "amlogic,axg-sound-card"; + model = "AXG-S420"; + audio-aux-devs = <&tdmin_a>, <&tdmout_c>; + audio-widgets = "Line", "Lineout", + "Line", "Linein", + "Speaker", "Speaker1 Left", + "Speaker", "Speaker1 Right", + "Speaker", "Speaker2 Left", + "Speaker", "Speaker2 Right"; + audio-routing = "TDMOUT_C IN 0", "FRDDR_A OUT 2", + "SPDIFOUT IN 0", "FRDDR_A OUT 3", + "TDM_C Playback", "TDMOUT_C OUT", + "TDMIN_A IN 2", "TDM_C Capture", + "TDMIN_A IN 5", "TDM_C Loopback", + "TODDR_A IN 0", "TDMIN_A OUT", + "Lineout", "Lineout AOUTL", + "Lineout", "Lineout AOUTR", + "Speaker1 Left", "SPK1 OUT_A", + "Speaker2 Left", "SPK2 OUT_A", + "Speaker1 Right", "SPK1 OUT_B", + "Speaker2 Right", "SPK2 OUT_B", + "Linein AINL", "Linein", + "Linein AINR", "Linein"; + + dai-link-0 { + sound-dai = <&frddr_a>; + }; + + dai-link-1 { + sound-dai = <&toddr_a>; + }; + + dai-link-2 { + sound-dai = <&tdmif_c>; + dai-format = "i2s"; + dai-tdm-slot-tx-mask-2 = <1 1>; + dai-tdm-slot-tx-mask-3 = <1 1>; + dai-tdm-slot-rx-mask-1 = <1 1>; + mclk-fs = <256>; + + codec-0 { + sound-dai = <&lineout>; + }; + + codec-1 { + sound-dai = <&speaker_amp1>; + }; + + codec-2 { + sound-dai = <&speaker_amp2>; + }; + + codec-3 { + sound-dai = <&linein>; + }; + }; + + dai-link-3 { + sound-dai = <&spdifout>; + + codec { + sound-dai = <&spdif_dit>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt deleted file mode 100644 index df92a4ecf288..000000000000 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt +++ /dev/null @@ -1,27 +0,0 @@ -* Amlogic Audio SPDIF Input - -Required properties: -- compatible: 'amlogic,axg-spdifin' or - 'amlogic,g12a-spdifin' or - 'amlogic,sm1-spdifin' -- interrupts: interrupt specifier for the spdif input. -- clocks: list of clock phandle, one for each entry clock-names. -- clock-names: should contain the following: - * "pclk" : peripheral clock. - * "refclk" : spdif input reference clock -- #sound-dai-cells: must be 0. - -Optional property: -- resets: phandle to the dedicated reset line of the spdif input. - -Example on the A113 SoC: - -spdifin: audio-controller@400 { - compatible = "amlogic,axg-spdifin"; - reg = <0x0 0x400 0x0 0x30>; - #sound-dai-cells = <0>; - interrupts = <GIC_SPI 87 IRQ_TYPE_EDGE_RISING>; - clocks = <&clkc_audio AUD_CLKID_SPDIFIN>, - <&clkc_audio AUD_CLKID_SPDIFIN_CLK>; - clock-names = "pclk", "refclk"; -}; diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.yaml b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.yaml new file mode 100644 index 000000000000..a0bd7a5fb9b3 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/amlogic,axg-spdifin.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic Audio AXG SPDIF Input + +maintainers: + - Jerome Brunet <jbrunet@baylibre.com> + +properties: + compatible: + oneOf: + - const: amlogic,axg-spdifin + - items: + - enum: + - amlogic,g12a-spdifin + - amlogic,sm1-spdifin + - const: amlogic,axg-spdifin + + reg: + maxItems: 1 + + "#sound-dai-cells": + const: 0 + + clocks: + items: + - description: Peripheral clock + - description: SPDIF input reference clock + + clock-names: + items: + - const: pclk + - const: refclk + + interrupts: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - "#sound-dai-cells" + - clocks + - clock-names + - interrupts + +allOf: + - $ref: dai-common.yaml# + + - if: + properties: + compatible: + contains: + enum: + - amlogic,g12a-spdifin + - amlogic,sm1-spdifin + then: + required: + - resets + + else: + properties: + resets: false + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/axg-audio-clkc.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + audio-controller@400 { + compatible = "amlogic,axg-spdifin"; + reg = <0x400 0x30>; + #sound-dai-cells = <0>; + interrupts = <GIC_SPI 87 IRQ_TYPE_EDGE_RISING>; + clocks = <&clkc_audio AUD_CLKID_SPDIFIN>, + <&clkc_audio AUD_CLKID_SPDIFIN_CLK>; + clock-names = "pclk", "refclk"; + }; diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.txt deleted file mode 100644 index 28381dd1f633..000000000000 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.txt +++ /dev/null @@ -1,25 +0,0 @@ -* Amlogic Audio SPDIF Output - -Required properties: -- compatible: 'amlogic,axg-spdifout' or - 'amlogic,g12a-spdifout' or - 'amlogic,sm1-spdifout' -- clocks: list of clock phandle, one for each entry clock-names. -- clock-names: should contain the following: - * "pclk" : peripheral clock. - * "mclk" : master clock -- #sound-dai-cells: must be 0. - -Optional property: -- resets: phandle to the dedicated reset line of the spdif output. - -Example on the A113 SoC: - -spdifout: audio-controller@480 { - compatible = "amlogic,axg-spdifout"; - reg = <0x0 0x480 0x0 0x50>; - #sound-dai-cells = <0>; - clocks = <&clkc_audio AUD_CLKID_SPDIFOUT>, - <&clkc_audio AUD_CLKID_SPDIFOUT_CLK>; - clock-names = "pclk", "mclk"; -}; diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.yaml b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.yaml new file mode 100644 index 000000000000..15be8dae9398 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/amlogic,axg-spdifout.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic Audio AXG SPDIF Output + +maintainers: + - Jerome Brunet <jbrunet@baylibre.com> + +properties: + compatible: + oneOf: + - const: amlogic,axg-spdifout + - items: + - enum: + - amlogic,g12a-spdifout + - amlogic,sm1-spdifout + - const: amlogic,axg-spdifout + + reg: + maxItems: 1 + + "#sound-dai-cells": + const: 0 + + clocks: + items: + - description: Peripheral clock + - description: SPDIF output master clock + + clock-names: + items: + - const: pclk + - const: mclk + + resets: + maxItems: 1 + +required: + - compatible + - reg + - "#sound-dai-cells" + - clocks + - clock-names + +allOf: + - $ref: dai-common.yaml# + + - if: + properties: + compatible: + contains: + enum: + - amlogic,g12a-spdifout + - amlogic,sm1-spdifout + then: + required: + - resets + + else: + properties: + resets: false + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/axg-audio-clkc.h> + + audio-controller@480 { + compatible = "amlogic,axg-spdifout"; + reg = <0x480 0x50>; + #sound-dai-cells = <0>; + clocks = <&clkc_audio AUD_CLKID_SPDIFOUT>, + <&clkc_audio AUD_CLKID_SPDIFOUT_CLK>; + clock-names = "pclk", "mclk"; + }; diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt deleted file mode 100644 index 5996c0cd89c2..000000000000 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt +++ /dev/null @@ -1,36 +0,0 @@ -* Amlogic Audio TDM formatters - -Required properties: -- compatible: 'amlogic,axg-tdmin' or - 'amlogic,axg-tdmout' or - 'amlogic,g12a-tdmin' or - 'amlogic,g12a-tdmout' or - 'amlogic,sm1-tdmin' or - 'amlogic,sm1-tdmout -- reg: physical base address of the controller and length of memory - mapped region. -- clocks: list of clock phandle, one for each entry clock-names. -- clock-names: should contain the following: - * "pclk" : peripheral clock. - * "sclk" : bit clock. - * "sclk_sel" : bit clock input multiplexer. - * "lrclk" : sample clock - * "lrclk_sel": sample clock input multiplexer - -Optional property: -- resets: phandle to the dedicated reset line of the tdm formatter. - -Example of TDMOUT_A on the S905X2 SoC: - -tdmout_a: audio-controller@500 { - compatible = "amlogic,axg-tdmout"; - reg = <0x0 0x500 0x0 0x40>; - resets = <&clkc_audio AUD_RESET_TDMOUT_A>; - clocks = <&clkc_audio AUD_CLKID_TDMOUT_A>, - <&clkc_audio AUD_CLKID_TDMOUT_A_SCLK>, - <&clkc_audio AUD_CLKID_TDMOUT_A_SCLK_SEL>, - <&clkc_audio AUD_CLKID_TDMOUT_A_LRCLK>, - <&clkc_audio AUD_CLKID_TDMOUT_A_LRCLK>; - clock-names = "pclk", "sclk", "sclk_sel", - "lrclk", "lrclk_sel"; -}; diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.yaml b/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.yaml new file mode 100644 index 000000000000..719ca8fc98c7 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.yaml @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/amlogic,axg-tdm-formatters.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic Audio AXG TDM formatters + +maintainers: + - Jerome Brunet <jbrunet@baylibre.com> + +properties: + compatible: + enum: + - amlogic,g12a-tdmout + - amlogic,sm1-tdmout + - amlogic,axg-tdmout + - amlogic,g12a-tdmin + - amlogic,sm1-tdmin + - amlogic,axg-tdmin + + clocks: + items: + - description: Peripheral clock + - description: Bit clock + - description: Bit clock input multiplexer + - description: Sample clock + - description: Sample clock input multiplexer + + clock-names: + items: + - const: pclk + - const: sclk + - const: sclk_sel + - const: lrclk + - const: lrclk_sel + + reg: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + +allOf: + - $ref: component-common.yaml# + + - if: + properties: + compatible: + contains: + enum: + - amlogic,g12a-tdmin + - amlogic,sm1-tdmin + - amlogic,g12a-tdmout + - amlogic,sm1-tdmout + then: + required: + - resets + + else: + properties: + resets: false + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/axg-audio-clkc.h> + #include <dt-bindings/reset/amlogic,meson-g12a-audio-reset.h> + + audio-controller@500 { + compatible = "amlogic,g12a-tdmout"; + reg = <0x500 0x40>; + resets = <&clkc_audio AUD_RESET_TDMOUT_A>; + clocks = <&clkc_audio AUD_CLKID_TDMOUT_A>, + <&clkc_audio AUD_CLKID_TDMOUT_A_SCLK>, + <&clkc_audio AUD_CLKID_TDMOUT_A_SCLK_SEL>, + <&clkc_audio AUD_CLKID_TDMOUT_A_LRCLK>, + <&clkc_audio AUD_CLKID_TDMOUT_A_LRCLK>; + clock-names = "pclk", "sclk", "sclk_sel", + "lrclk", "lrclk_sel"; + }; diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-iface.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-iface.txt deleted file mode 100644 index cabfb26a5f22..000000000000 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-iface.txt +++ /dev/null @@ -1,22 +0,0 @@ -* Amlogic Audio TDM Interfaces - -Required properties: -- compatible: 'amlogic,axg-tdm-iface' -- clocks: list of clock phandle, one for each entry clock-names. -- clock-names: should contain the following: - * "sclk" : bit clock. - * "lrclk": sample clock - * "mclk" : master clock - -> optional if the interface is in clock slave mode. -- #sound-dai-cells: must be 0. - -Example of TDM_A on the A113 SoC: - -tdmif_a: audio-controller@0 { - compatible = "amlogic,axg-tdm-iface"; - #sound-dai-cells = <0>; - clocks = <&clkc_audio AUD_CLKID_MST_A_MCLK>, - <&clkc_audio AUD_CLKID_MST_A_SCLK>, - <&clkc_audio AUD_CLKID_MST_A_LRCLK>; - clock-names = "mclk", "sclk", "lrclk"; -}; diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-iface.yaml b/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-iface.yaml new file mode 100644 index 000000000000..320f0002649d --- /dev/null +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-iface.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/amlogic,axg-tdm-iface.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic Audio TDM Interfaces + +maintainers: + - Jerome Brunet <jbrunet@baylibre.com> + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + const: amlogic,axg-tdm-iface + + "#sound-dai-cells": + const: 0 + + clocks: + minItems: 2 + items: + - description: Bit clock + - description: Sample clock + - description: Master clock #optional + + clock-names: + minItems: 2 + items: + - const: sclk + - const: lrclk + - const: mclk + +required: + - compatible + - "#sound-dai-cells" + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/axg-audio-clkc.h> + + audio-controller { + compatible = "amlogic,axg-tdm-iface"; + #sound-dai-cells = <0>; + clocks = <&clkc_audio AUD_CLKID_MST_A_SCLK>, + <&clkc_audio AUD_CLKID_MST_A_LRCLK>, + <&clkc_audio AUD_CLKID_MST_A_MCLK>; + clock-names = "sclk", "lrclk", "mclk"; + }; diff --git a/Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml b/Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml index 5b8d59245f82..b358fd601ed3 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml +++ b/Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml @@ -62,7 +62,7 @@ patternProperties: description: phandle of the CPU DAI patternProperties: - "^codec-[0-9]+$": + "^codec(-[0-9]+)?$": type: object additionalProperties: false description: |- diff --git a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml index f5b8b6d13077..6b4e02a0695a 100644 --- a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml +++ b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml @@ -11,32 +11,24 @@ maintainers: select: false -allOf: - - $ref: /schemas/graph.yaml#/$defs/port-base - -properties: - prefix: - description: "device name prefix" - $ref: /schemas/types.yaml#/definitions/string - 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" +definitions: + port-base: + $ref: /schemas/graph.yaml#/$defs/port-base + 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" -patternProperties: - "^endpoint(@[0-9a-f]+)?": + endpoint-base: $ref: /schemas/graph.yaml#/$defs/endpoint-base - unevaluatedProperties: false - properties: mclk-fs: - description: | - Multiplication factor between stream rate and codec mclk. - When defined, mclk-fs property defined in dai-link sub nodes are - ignored. - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: "simple-card.yaml#/definitions/mclk-fs" frame-inversion: description: dai-link uses frame clock inversion $ref: /schemas/types.yaml#/definitions/flag @@ -53,6 +45,15 @@ patternProperties: oneOf: - $ref: /schemas/types.yaml#/definitions/flag - $ref: /schemas/types.yaml#/definitions/phandle + clocks: + description: Indicates system clock + $ref: /schemas/types.yaml#/definitions/phandle + system-clock-frequency: + $ref: "simple-card.yaml#/definitions/system-clock-frequency" + system-clock-direction-out: + $ref: "simple-card.yaml#/definitions/system-clock-direction-out" + system-clock-fixed: + $ref: "simple-card.yaml#/definitions/system-clock-fixed" dai-format: description: audio format. @@ -100,4 +101,24 @@ patternProperties: minimum: 1 maximum: 64 + ports: + $ref: "#/definitions/port-base" + unevaluatedProperties: false + patternProperties: + "^port(@[0-9a-f]+)?$": + $ref: "#/definitions/port-base" + unevaluatedProperties: false + patternProperties: + "^endpoint(@[0-9a-f]+)?": + $ref: "#/definitions/endpoint-base" + unevaluatedProperties: false + +allOf: + - $ref: "#/definitions/port-base" + +patternProperties: + "^endpoint(@[0-9a-f]+)?": + $ref: "#/definitions/endpoint-base" + unevaluatedProperties: false + additionalProperties: true diff --git a/Documentation/devicetree/bindings/sound/awinic,aw88395.yaml b/Documentation/devicetree/bindings/sound/awinic,aw88395.yaml new file mode 100644 index 000000000000..35eef7d818a2 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/awinic,aw88395.yaml @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/awinic,aw88395.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Awinic AW88395 Smart Audio Amplifier + +maintainers: + - Weidong Wang <wangweidong.a@awinic.com> + +description: + The Awinic AW88395 is an I2S/TDM input, high efficiency + digital Smart K audio amplifier with an integrated 10.25V + smart boost convert. + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + const: awinic,aw88395 + + reg: + maxItems: 1 + + '#sound-dai-cells': + const: 0 + + reset-gpios: + maxItems: 1 + +required: + - compatible + - reg + - '#sound-dai-cells' + - reset-gpios + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + audio-codec@34 { + compatible = "awinic,aw88395"; + reg = <0x34>; + #sound-dai-cells = <0>; + reset-gpios = <&gpio 10 GPIO_ACTIVE_LOW>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/cirrus,cs35l41.yaml b/Documentation/devicetree/bindings/sound/cirrus,cs35l41.yaml index 82062d80d700..18fb471aa891 100644 --- a/Documentation/devicetree/bindings/sound/cirrus,cs35l41.yaml +++ b/Documentation/devicetree/bindings/sound/cirrus,cs35l41.yaml @@ -22,6 +22,9 @@ properties: reg: maxItems: 1 + interrupts: + maxItems: 1 + '#sound-dai-cells': description: The first cell indicating the audio interface. @@ -42,7 +45,7 @@ properties: Configures the peak current by monitoring the current through the boost FET. Range starts at 1600 mA and goes to a maximum of 4500 mA with increments of 50 mA. See section 4.3.6 of the datasheet for details. - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 1600 maximum: 4500 default: 4500 @@ -51,7 +54,7 @@ properties: description: Boost inductor value, expressed in nH. Valid values include 1000, 1200, 1500 and 2200. - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 1000 maximum: 2200 @@ -60,7 +63,7 @@ properties: Total equivalent boost capacitance on the VBST and VAMP pins, derated at 11 volts DC. The value must be rounded to the nearest integer and expressed in uF. - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 cirrus,asp-sdout-hiz: description: @@ -70,7 +73,7 @@ properties: 1 = Hi-Z during unused slots but logic 0 while all transmit channels disabled 2 = (Default) Logic 0 during unused slots, but Hi-Z while all transmit channels disabled 3 = Hi-Z during unused slots and while all transmit channels disabled - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3 default: 2 @@ -84,7 +87,7 @@ properties: enable boost voltage. 0 = Internal Boost 1 = External Boost - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 1 @@ -109,7 +112,7 @@ properties: 1 = GPIO 2 = Sync 3 = MCLK input - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3 @@ -136,7 +139,7 @@ properties: 3 = MCLK input 4 = Push-pull INTB (active low) 5 = Push-pull INT (active high) - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 5 @@ -176,21 +179,23 @@ unevaluatedProperties: false examples: - | + #include <dt-bindings/gpio/gpio.h> + spi { #address-cells = <1>; #size-cells = <0>; - cs35l41: cs35l41@2 { - #sound-dai-cells = <1>; - compatible = "cirrus,cs35l41"; - reg = <2>; - VA-supply = <&dummy_vreg>; - VP-supply = <&dummy_vreg>; - reset-gpios = <&gpio 110 0>; - - cirrus,boost-type = <0>; - cirrus,boost-peak-milliamp = <4500>; - cirrus,boost-ind-nanohenry = <1000>; - cirrus,boost-cap-microfarad = <15>; + cs35l41: speaker-amp@2 { + #sound-dai-cells = <1>; + compatible = "cirrus,cs35l41"; + reg = <2>; + VA-supply = <&dummy_vreg>; + VP-supply = <&dummy_vreg>; + reset-gpios = <&gpio 110 GPIO_ACTIVE_HIGH>; + + cirrus,boost-type = <0>; + cirrus,boost-peak-milliamp = <4500>; + cirrus,boost-ind-nanohenry = <1000>; + cirrus,boost-cap-microfarad = <15>; }; }; diff --git a/Documentation/devicetree/bindings/sound/component-common.yaml b/Documentation/devicetree/bindings/sound/component-common.yaml new file mode 100644 index 000000000000..37766c5f3974 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/component-common.yaml @@ -0,0 +1,21 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/component-common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Audio Component Common Properties + +maintainers: + - Jerome Brunet <jbrunet@baylibre.com> + +properties: + sound-name-prefix: + $ref: /schemas/types.yaml#/definitions/string + description: | + Card implementing the routing property define the connection between + audio components as list of string pair. Component using the same + sink/source names may use this property to prepend the name of their + sinks/sources with the provided string. + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/sound/dai-common.yaml b/Documentation/devicetree/bindings/sound/dai-common.yaml index d858eea73ed7..1aed2f0f1775 100644 --- a/Documentation/devicetree/bindings/sound/dai-common.yaml +++ b/Documentation/devicetree/bindings/sound/dai-common.yaml @@ -9,15 +9,10 @@ title: Digital Audio Interface Common Properties maintainers: - Jerome Brunet <jbrunet@baylibre.com> -properties: - sound-name-prefix: - $ref: /schemas/types.yaml#/definitions/string - description: | - Card implementing the routing property define the connection between - audio components as list of string pair. Component using the same - sink/source names may use this property to prepend the name of their - sinks/sources with the provided string. +allOf: + - $ref: component-common.yaml# +properties: '#sound-dai-cells': true additionalProperties: true diff --git a/Documentation/devicetree/bindings/sound/everest,es8326.yaml b/Documentation/devicetree/bindings/sound/everest,es8326.yaml index 07781408e788..07781408e788 100755..100644 --- a/Documentation/devicetree/bindings/sound/everest,es8326.yaml +++ b/Documentation/devicetree/bindings/sound/everest,es8326.yaml diff --git a/Documentation/devicetree/bindings/sound/fsl,sai.yaml b/Documentation/devicetree/bindings/sound/fsl,sai.yaml index 7e56337d8edc..088c26b001cc 100644 --- a/Documentation/devicetree/bindings/sound/fsl,sai.yaml +++ b/Documentation/devicetree/bindings/sound/fsl,sai.yaml @@ -76,10 +76,14 @@ properties: minItems: 4 dmas: - maxItems: 2 + items: + - description: DMA controller phandle and request line for RX + - description: DMA controller phandle and request line for TX dma-names: - maxItems: 2 + items: + - const: rx + - const: tx interrupts: items: @@ -143,31 +147,6 @@ properties: allOf: - $ref: dai-common.yaml# - if: - properties: - compatible: - contains: - const: fsl,vf610-sai - then: - properties: - dmas: - items: - - description: DMA controller phandle and request line for TX - - description: DMA controller phandle and request line for RX - dma-names: - items: - - const: tx - - const: rx - else: - properties: - dmas: - items: - - description: DMA controller phandle and request line for RX - - description: DMA controller phandle and request line for TX - dma-names: - items: - - const: rx - - const: tx - - if: required: - fsl,sai-asynchronous then: @@ -199,9 +178,8 @@ examples: <&clks VF610_CLK_SAI2>, <&clks 0>, <&clks 0>; clock-names = "bus", "mclk1", "mclk2", "mclk3"; - dma-names = "tx", "rx"; - dmas = <&edma0 0 21>, - <&edma0 0 20>; + dma-names = "rx", "tx"; + dmas = <&edma0 0 20>, <&edma0 0 21>; big-endian; lsb-first; }; diff --git a/Documentation/devicetree/bindings/sound/fsl,xcvr.yaml b/Documentation/devicetree/bindings/sound/fsl,xcvr.yaml index 223b8ea693dc..799b362ba498 100644 --- a/Documentation/devicetree/bindings/sound/fsl,xcvr.yaml +++ b/Documentation/devicetree/bindings/sound/fsl,xcvr.yaml @@ -21,6 +21,7 @@ properties: compatible: enum: - fsl,imx8mp-xcvr + - fsl,imx93-xcvr reg: items: diff --git a/Documentation/devicetree/bindings/sound/google,sc7280-herobrine.yaml b/Documentation/devicetree/bindings/sound/google,sc7280-herobrine.yaml index 869b40363af8..0b1a01a4c14e 100644 --- a/Documentation/devicetree/bindings/sound/google,sc7280-herobrine.yaml +++ b/Documentation/devicetree/bindings/sound/google,sc7280-herobrine.yaml @@ -75,6 +75,18 @@ patternProperties: additionalProperties: false + platform: + description: Holds subnode which includes the phandle of q6apm platform device. + type: object + properties: + sound-dai: + maxItems: 1 + + required: + - sound-dai + + additionalProperties: false + required: - link-name - cpu diff --git a/Documentation/devicetree/bindings/sound/infineon,peb2466.yaml b/Documentation/devicetree/bindings/sound/infineon,peb2466.yaml new file mode 100644 index 000000000000..66993d378aaf --- /dev/null +++ b/Documentation/devicetree/bindings/sound/infineon,peb2466.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/infineon,peb2466.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Infineon PEB2466 codec + +maintainers: + - Herve Codina <herve.codina@bootlin.com> + +description: | + The Infineon PEB2466 codec is a programmable DSP-based four channels codec + with filters capabilities. + + The time-slots used by the codec must be set and so, the properties + 'dai-tdm-slot-num', 'dai-tdm-slot-width', 'dai-tdm-slot-tx-mask' and + 'dai-tdm-slot-rx-mask' must be present in the sound card node for sub-nodes + that involve the codec. The codec uses one 8bit time-slot per channel. + 'dai-tdm-tdm-slot-with' must be set to 8. + + The PEB2466 codec also supports 28 gpios (signaling pins). + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml + - $ref: dai-common.yaml# + +properties: + compatible: + const: infineon,peb2466 + + reg: + description: + SPI device address. + maxItems: 1 + + clocks: + items: + - description: Master clock + + clock-names: + items: + - const: mclk + + spi-max-frequency: + maximum: 8192000 + + reset-gpios: + description: + GPIO used to reset the device. + maxItems: 1 + + firmware-name: + $ref: /schemas/types.yaml#/definitions/string + description: + Filters coefficients file to load. If this property is omitted, internal + filters are disabled. + + '#sound-dai-cells': + const: 0 + + '#gpio-cells': + const: 2 + + gpio-controller: true + +required: + - compatible + - reg + - '#sound-dai-cells' + - gpio-controller + - '#gpio-cells' + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + spi { + #address-cells = <1>; + #size-cells = <0>; + audio-codec@0 { + compatible = "infineon,peb2466"; + reg = <0>; + spi-max-frequency = <8192000>; + reset-gpios = <&gpio 10 GPIO_ACTIVE_LOW>; + #sound-dai-cells = <0>; + gpio-controller; + #gpio-cells = <2>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/irondevice,sma1303.yaml b/Documentation/devicetree/bindings/sound/irondevice,sma1303.yaml new file mode 100644 index 000000000000..b36c35e5da1a --- /dev/null +++ b/Documentation/devicetree/bindings/sound/irondevice,sma1303.yaml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/irondevice,sma1303.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Iron Device SMA1303 Audio Amplifier + +maintainers: + - Kiseok Jo <kiseok.jo@irondevice.com> + +description: + SMA1303 digital class-D audio amplifier + with an integrated boost converter. + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + enum: + - irondevice,sma1303 + + reg: + maxItems: 1 + + '#sound-dai-cells': + const: 1 + +required: + - compatible + - reg + - '#sound-dai-cells' + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + amplifier@1e { + compatible = "irondevice,sma1303"; + reg = <0x1e>; + #sound-dai-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/max98090.txt b/Documentation/devicetree/bindings/sound/max98090.txt deleted file mode 100644 index 39d640294c62..000000000000 --- a/Documentation/devicetree/bindings/sound/max98090.txt +++ /dev/null @@ -1,59 +0,0 @@ -MAX98090 audio CODEC - -This device supports I2C only. - -Required properties: - -- compatible : "maxim,max98090" or "maxim,max98091". - -- reg : The I2C address of the device. - -- interrupts : The CODEC's interrupt output. - -Optional properties: - -- clocks: The phandle of the master clock to the CODEC - -- clock-names: Should be "mclk" - -- #sound-dai-cells : should be 0. - -- maxim,dmic-freq: Frequency at which to clock DMIC - -- maxim,micbias: Micbias voltage applies to the analog mic, valid voltages value are: - 0 - 2.2v - 1 - 2.55v - 2 - 2.4v - 3 - 2.8v - -Pins on the device (for linking into audio routes): - - * MIC1 - * MIC2 - * DMICL - * DMICR - * IN1 - * IN2 - * IN3 - * IN4 - * IN5 - * IN6 - * IN12 - * IN34 - * IN56 - * HPL - * HPR - * SPKL - * SPKR - * RCVL - * RCVR - * MICBIAS - -Example: - -audio-codec@10 { - compatible = "maxim,max98090"; - reg = <0x10>; - interrupt-parent = <&gpio>; - interrupts = <TEGRA_GPIO(H, 4) IRQ_TYPE_LEVEL_HIGH>; -}; diff --git a/Documentation/devicetree/bindings/sound/max98095.txt b/Documentation/devicetree/bindings/sound/max98095.txt deleted file mode 100644 index 318a4c82f17f..000000000000 --- a/Documentation/devicetree/bindings/sound/max98095.txt +++ /dev/null @@ -1,22 +0,0 @@ -MAX98095 audio CODEC - -This device supports I2C only. - -Required properties: - -- compatible : "maxim,max98095". - -- reg : The I2C address of the device. - -Optional properties: - -- clocks: The phandle of the master clock to the CODEC - -- clock-names: Should be "mclk" - -Example: - -max98095: codec@11 { - compatible = "maxim,max98095"; - reg = <0x11>; -}; diff --git a/Documentation/devicetree/bindings/sound/maxim,max98090.yaml b/Documentation/devicetree/bindings/sound/maxim,max98090.yaml new file mode 100644 index 000000000000..65e4c516912f --- /dev/null +++ b/Documentation/devicetree/bindings/sound/maxim,max98090.yaml @@ -0,0 +1,84 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/maxim,max98090.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated MAX98090/MAX98091 audio codecs + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: | + Pins on the device (for linking into audio routes): + MIC1, MIC2, DMICL, DMICR, IN1, IN2, IN3, IN4, IN5, IN6, IN12, IN34, IN56, + HPL, HPR, SPKL, SPKR, RCVL, RCVR, MICBIAS + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + enum: + - maxim,max98090 + - maxim,max98091 + + reg: + maxItems: 1 + + clocks: + items: + - description: master clock + + clock-names: + items: + - const: mclk + + interrupts: + maxItems: 1 + + maxim,dmic-freq: + $ref: /schemas/types.yaml#/definitions/uint32 + default: 2500000 + description: + DMIC clock frequency + + maxim,micbias: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1, 2, 3 ] + default: 3 + description: | + Micbias voltage applied to the analog mic, valid voltages value are: + 0 - 2.2v + 1 - 2.55v + 2 - 2.4v + 3 - 2.8v + + '#sound-dai-cells': + const: 0 + +required: + - compatible + - reg + - interrupts + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + audio-codec@10 { + compatible = "maxim,max98090"; + reg = <0x10>; + interrupt-parent = <&gpx3>; + interrupts = <2 IRQ_TYPE_EDGE_FALLING>; + clocks = <&i2s0 0>; + clock-names = "mclk"; + #sound-dai-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/maxim,max98095.yaml b/Documentation/devicetree/bindings/sound/maxim,max98095.yaml new file mode 100644 index 000000000000..77544a9e1587 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/maxim,max98095.yaml @@ -0,0 +1,54 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/maxim,max98095.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated MAX98095 audio codec + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + enum: + - maxim,max98095 + + reg: + maxItems: 1 + + clocks: + items: + - description: master clock + + clock-names: + items: + - const: mclk + + '#sound-dai-cells': + const: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + audio-codec@11 { + compatible = "maxim,max98095"; + reg = <0x11>; + clocks = <&i2s0 0>; + clock-names = "mclk"; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/mediatek,mt8188-afe.yaml b/Documentation/devicetree/bindings/sound/mediatek,mt8188-afe.yaml new file mode 100644 index 000000000000..82ccb32f08f2 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mediatek,mt8188-afe.yaml @@ -0,0 +1,208 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/mediatek,mt8188-afe.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek AFE PCM controller for mt8188 + +maintainers: + - Trevor Wu <trevor.wu@mediatek.com> + +properties: + compatible: + const: mediatek,mt8188-afe + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + resets: + maxItems: 1 + + reset-names: + const: audiosys + + mediatek,topckgen: + $ref: /schemas/types.yaml#/definitions/phandle + description: The phandle of the mediatek topckgen controller + + power-domains: + maxItems: 1 + + clocks: + items: + - description: 26M clock + - description: audio pll1 clock + - description: audio pll2 clock + - description: clock divider for i2si1_mck + - description: clock divider for i2si2_mck + - description: clock divider for i2so1_mck + - description: clock divider for i2so2_mck + - description: clock divider for dptx_mck + - description: a1sys hoping clock + - description: audio intbus clock + - description: audio hires clock + - description: audio local bus clock + - description: mux for dptx_mck + - description: mux for i2so1_mck + - description: mux for i2so2_mck + - description: mux for i2si1_mck + - description: mux for i2si2_mck + - description: audio 26m clock + + clock-names: + items: + - const: clk26m + - const: apll1 + - const: apll2 + - const: apll12_div0 + - const: apll12_div1 + - const: apll12_div2 + - const: apll12_div3 + - const: apll12_div9 + - const: a1sys_hp_sel + - const: aud_intbus_sel + - const: audio_h_sel + - const: audio_local_bus_sel + - const: dptx_m_sel + - const: i2so1_m_sel + - const: i2so2_m_sel + - const: i2si1_m_sel + - const: i2si2_m_sel + - const: adsp_audio_26m + + mediatek,etdm-in1-cowork-source: + $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 module. + enum: + - 1 # etdm2_in + - 2 # etdm1_out + - 3 # etdm2_out + + mediatek,etdm-in2-cowork-source: + $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 module. + enum: + - 0 # etdm1_in + - 2 # etdm1_out + - 3 # etdm2_out + + mediatek,etdm-out1-cowork-source: + $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 module. + enum: + - 0 # etdm1_in + - 1 # etdm2_in + - 3 # etdm2_out + + mediatek,etdm-out2-cowork-source: + $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 module. + enum: + - 0 # etdm1_in + - 1 # etdm2_in + - 2 # etdm1_out + +patternProperties: + "^mediatek,etdm-in[1-2]-chn-disabled$": + $ref: /schemas/types.yaml#/definitions/uint8-array + minItems: 1 + 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 + memory. etdm in supports disable_out in direct mode(w/o interconn), + so user can disable the specified channels by the property. + uniqueItems: true + items: + minimum: 0 + maximum: 15 + + "^mediatek,etdm-in[1-2]-multi-pin-mode$": + type: boolean + description: if present, the etdm data mode is I2S. + + "^mediatek,etdm-out[1-3]-multi-pin-mode$": + type: boolean + description: if present, the etdm data mode is I2S. + +required: + - compatible + - reg + - interrupts + - resets + - reset-names + - mediatek,topckgen + - power-domains + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + afe@10b10000 { + compatible = "mediatek,mt8188-afe"; + reg = <0x10b10000 0x10000>; + interrupts = <GIC_SPI 822 IRQ_TYPE_LEVEL_HIGH 0>; + resets = <&watchdog 14>; + reset-names = "audiosys"; + mediatek,topckgen = <&topckgen>; + power-domains = <&spm 13>; //MT8188_POWER_DOMAIN_AUDIO + mediatek,etdm-in2-cowork-source = <2>; + mediatek,etdm-out2-cowork-source = <0>; + mediatek,etdm-in1-multi-pin-mode; + mediatek,etdm-in1-chn-disabled = /bits/ 8 <0x0 0x2>; + clocks = <&clk26m>, + <&apmixedsys 9>, //CLK_APMIXED_APLL1 + <&apmixedsys 10>, //CLK_APMIXED_APLL2 + <&topckgen 186>, //CLK_TOP_APLL12_CK_DIV0 + <&topckgen 187>, //CLK_TOP_APLL12_CK_DIV1 + <&topckgen 188>, //CLK_TOP_APLL12_CK_DIV2 + <&topckgen 189>, //CLK_TOP_APLL12_CK_DIV3 + <&topckgen 191>, //CLK_TOP_APLL12_CK_DIV9 + <&topckgen 83>, //CLK_TOP_A1SYS_HP + <&topckgen 31>, //CLK_TOP_AUD_INTBUS + <&topckgen 32>, //CLK_TOP_AUDIO_H + <&topckgen 69>, //CLK_TOP_AUDIO_LOCAL_BUS + <&topckgen 81>, //CLK_TOP_DPTX + <&topckgen 77>, //CLK_TOP_I2SO1 + <&topckgen 78>, //CLK_TOP_I2SO2 + <&topckgen 79>, //CLK_TOP_I2SI1 + <&topckgen 80>, //CLK_TOP_I2SI2 + <&adsp_audio26m 0>; //CLK_AUDIODSP_AUDIO26M + clock-names = "clk26m", + "apll1", + "apll2", + "apll12_div0", + "apll12_div1", + "apll12_div2", + "apll12_div3", + "apll12_div9", + "a1sys_hp_sel", + "aud_intbus_sel", + "audio_h_sel", + "audio_local_bus_sel", + "dptx_m_sel", + "i2so1_m_sel", + "i2so2_m_sel", + "i2si1_m_sel", + "i2si2_m_sel", + "adsp_audio_26m"; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/mediatek,mt8188-mt6359.yaml b/Documentation/devicetree/bindings/sound/mediatek,mt8188-mt6359.yaml new file mode 100644 index 000000000000..6640272b3f4f --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mediatek,mt8188-mt6359.yaml @@ -0,0 +1,97 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/mediatek,mt8188-mt6359.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek MT8188 ASoC sound card + +maintainers: + - Trevor Wu <trevor.wu@mediatek.com> + +properties: + compatible: + const: mediatek,mt8188-mt6359-evb + + 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 + 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. + + mediatek,platform: + $ref: /schemas/types.yaml#/definitions/phandle + description: The phandle of MT8188 ASoC platform. + +patternProperties: + "^dai-link-[0-9]+$": + type: object + description: + Container for dai-link level properties and CODEC sub-nodes. + + properties: + link-name: + description: + This property corresponds to the name of the BE dai-link to which + we are going to update parameters in this node. + items: + enum: + - ADDA_BE + - DPTX_BE + - ETDM1_IN_BE + - ETDM2_IN_BE + - ETDM1_OUT_BE + - ETDM2_OUT_BE + - ETDM3_OUT_BE + - PCM1_BE + + codec: + description: Holds subnode which indicates codec dai. + type: object + additionalProperties: false + properties: + sound-dai: + minItems: 1 + maxItems: 2 + required: + - sound-dai + + additionalProperties: false + + required: + - link-name + - codec + +additionalProperties: false + +required: + - compatible + - mediatek,platform + +examples: + - | + sound { + compatible = "mediatek,mt8188-mt6359-evb"; + mediatek,platform = <&afe>; + pinctrl-names = "default"; + pinctrl-0 = <&aud_pins_default>; + audio-routing = + "Headphone", "Headphone L", + "Headphone", "Headphone R", + "AIN1", "Headset Mic"; + dai-link-0 { + link-name = "ETDM3_OUT_BE"; + + codec { + sound-dai = <&hdmi0>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/mchp,i2s-mcc.yaml b/Documentation/devicetree/bindings/sound/microchip,sama7g5-i2smcc.yaml index 621022872c8d..651f61c7c25a 100644 --- a/Documentation/devicetree/bindings/sound/mchp,i2s-mcc.yaml +++ b/Documentation/devicetree/bindings/sound/microchip,sama7g5-i2smcc.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/sound/mchp,i2s-mcc.yaml# +$id: http://devicetree.org/schemas/sound/microchip,sama7g5-i2smcc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Microchip I2S Multi-Channel Controller diff --git a/Documentation/devicetree/bindings/sound/microchip,pdmc.yaml b/Documentation/devicetree/bindings/sound/microchip,sama7g5-pdmc.yaml index c37b89d94c12..c4cf1e5ab84b 100644 --- a/Documentation/devicetree/bindings/sound/microchip,pdmc.yaml +++ b/Documentation/devicetree/bindings/sound/microchip,sama7g5-pdmc.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/sound/microchip,pdmc.yaml# +$id: http://devicetree.org/schemas/sound/microchip,sama7g5-pdmc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Microchip Pulse Density Microphone Controller diff --git a/Documentation/devicetree/bindings/sound/mchp,spdifrx.yaml b/Documentation/devicetree/bindings/sound/microchip,sama7g5-spdifrx.yaml index 70a47c6823b1..2f43c684ab88 100644 --- a/Documentation/devicetree/bindings/sound/mchp,spdifrx.yaml +++ b/Documentation/devicetree/bindings/sound/microchip,sama7g5-spdifrx.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/sound/mchp,spdifrx.yaml# +$id: http://devicetree.org/schemas/sound/microchip,sama7g5-spdifrx.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Microchip S/PDIF Rx Controller diff --git a/Documentation/devicetree/bindings/sound/mchp,spdiftx.yaml b/Documentation/devicetree/bindings/sound/microchip,sama7g5-spdiftx.yaml index c383162140bb..4702c528700d 100644 --- a/Documentation/devicetree/bindings/sound/mchp,spdiftx.yaml +++ b/Documentation/devicetree/bindings/sound/microchip,sama7g5-spdiftx.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/sound/mchp,spdiftx.yaml# +$id: http://devicetree.org/schemas/sound/microchip,sama7g5-spdiftx.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Microchip S/PDIF Tx Controller diff --git a/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml b/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml index 9d3139990237..aa23b0024c46 100644 --- a/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml +++ b/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml @@ -16,6 +16,7 @@ properties: compatible: enum: - mediatek,mt8186-mt6366-rt1019-rt5682s-sound + - mediatek,mt8186-mt6366-rt5682s-max98360-sound mediatek,platform: $ref: "/schemas/types.yaml#/definitions/phandle" diff --git a/Documentation/devicetree/bindings/sound/nau8822.txt b/Documentation/devicetree/bindings/sound/nau8822.txt deleted file mode 100644 index a471d162d4e5..000000000000 --- a/Documentation/devicetree/bindings/sound/nau8822.txt +++ /dev/null @@ -1,16 +0,0 @@ -NAU8822 audio CODEC - -This device supports I2C only. - -Required properties: - - - compatible : "nuvoton,nau8822" - - - reg : the I2C address of the device. - -Example: - -codec: nau8822@1a { - compatible = "nuvoton,nau8822"; - reg = <0x1a>; -}; diff --git a/Documentation/devicetree/bindings/sound/nuvoton,nau8822.yaml b/Documentation/devicetree/bindings/sound/nuvoton,nau8822.yaml new file mode 100644 index 000000000000..65105402a53d --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nuvoton,nau8822.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nuvoton,nau8822.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NAU8822 audio CODEC + +description: | + 24 bit stereo audio codec with speaker driver. + This device supports I2C/SPI. + +maintainers: + - David Lin <CTLIN0@nuvoton.com> + +properties: + compatible: + enum: + - nuvoton,nau8822 + + reg: + maxItems: 1 + + nuvoton,spk-btl: + description: + If set, configure the two loudspeaker outputs as a Bridge Tied Load output + to drive a high power external loudspeaker. + $ref: /schemas/types.yaml#/definitions/flag + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + codec@1a { + compatible = "nuvoton,nau8822"; + reg = <0x1a>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml index 89f7805de274..c4abac81f207 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml @@ -50,10 +50,10 @@ properties: maxItems: 1 "#address-cells": - const: 1 + enum: [ 1, 2 ] "#size-cells": - const: 1 + enum: [ 1, 2 ] ranges: true diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-ope.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-ope.yaml index 5fc03b8771b1..9017fb6d575d 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-ope.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-ope.yaml @@ -34,10 +34,10 @@ properties: maxItems: 1 "#address-cells": - const: 1 + enum: [ 1, 2 ] "#size-cells": - const: 1 + enum: [ 1, 2 ] ranges: true diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml index bb42220916b3..6cc8f86c7531 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml @@ -35,7 +35,7 @@ properties: clocks: minItems: 3 - maxItems: 7 + maxItems: 10 clock-names: minItems: 1 @@ -65,6 +65,9 @@ properties: power-domain-names: maxItems: 1 + required-opps: + maxItems: 1 + '#sound-dai-cells': const: 1 @@ -75,7 +78,7 @@ properties: const: 0 patternProperties: - "^dai-link@[0-9a-f]$": + "^dai-link@[0-9a-f]+$": type: object description: | LPASS CPU dai node for each I2S device or Soundwire device. Bindings of each node @@ -121,6 +124,8 @@ allOf: then: properties: + clocks: + maxItems: 3 clock-names: items: - const: ahbix-clk @@ -135,6 +140,9 @@ allOf: then: properties: + clocks: + minItems: 7 + maxItems: 7 clock-names: items: - const: ahbix-clk @@ -153,33 +161,31 @@ allOf: then: properties: + clocks: + minItems: 6 + maxItems: 6 clock-names: - oneOf: - - items: #for I2S - - const: pcnoc-sway-clk - - const: audio-core - - const: mclk0 - - const: pcnoc-mport-clk - - const: mi2s-bit-clk0 - - const: mi2s-bit-clk1 - - items: #for HDMI - - const: pcnoc-sway-clk - - const: audio-core - - const: pcnoc-mport-clk + items: + - const: pcnoc-sway-clk + - const: audio-core + - const: mclk0 + - const: pcnoc-mport-clk + - const: mi2s-bit-clk0 + - const: mi2s-bit-clk1 + reg: + minItems: 2 + maxItems: 2 reg-names: - anyOf: - - items: #for I2S - - const: lpass-lpaif - - items: #for I2S and HDMI - - const: lpass-hdmiif - - const: lpass-lpaif + items: + - const: lpass-hdmiif + - const: lpass-lpaif + interrupts: + minItems: 2 + maxItems: 2 interrupt-names: - anyOf: - - items: #for I2S - - const: lpass-irq-lpaif - - items: #for I2S and HDMI - - const: lpass-irq-lpaif - - const: lpass-irq-hdmi + items: + - const: lpass-irq-lpaif + - const: lpass-irq-hdmi required: - iommus - power-domains @@ -192,54 +198,44 @@ allOf: then: properties: + clocks: + minItems: 10 + maxItems: 10 clock-names: - oneOf: - - items: #for I2S - - const: aon_cc_audio_hm_h - - const: audio_cc_ext_mclk0 - - const: core_cc_sysnoc_mport_core - - const: core_cc_ext_if0_ibit - - const: core_cc_ext_if1_ibit - - items: #for Soundwire - - const: aon_cc_audio_hm_h - - const: audio_cc_codec_mem - - const: audio_cc_codec_mem0 - - const: audio_cc_codec_mem1 - - const: audio_cc_codec_mem2 - - const: aon_cc_va_mem0 - - items: #for HDMI - - const: core_cc_sysnoc_mport_core - + items: + - const: aon_cc_audio_hm_h + - const: audio_cc_ext_mclk0 + - const: core_cc_sysnoc_mport_core + - const: core_cc_ext_if0_ibit + - const: core_cc_ext_if1_ibit + - const: audio_cc_codec_mem + - const: audio_cc_codec_mem0 + - const: audio_cc_codec_mem1 + - const: audio_cc_codec_mem2 + - const: aon_cc_va_mem0 + reg: + minItems: 6 + maxItems: 6 reg-names: - anyOf: - - items: #for I2S - - const: lpass-lpaif - - items: #for I2S and HDMI - - const: lpass-hdmiif - - const: lpass-lpaif - - items: #for I2S, soundwire and HDMI - - const: lpass-hdmiif - - const: lpass-lpaif - - const: lpass-rxtx-cdc-dma-lpm - - const: lpass-rxtx-lpaif - - const: lpass-va-lpaif - - const: lpass-va-cdc-dma-lpm + items: + - const: lpass-hdmiif + - const: lpass-lpaif + - const: lpass-rxtx-cdc-dma-lpm + - const: lpass-rxtx-lpaif + - const: lpass-va-lpaif + - const: lpass-va-cdc-dma-lpm + interrupts: + minItems: 4 + maxItems: 4 interrupt-names: - anyOf: - - items: #for I2S - - const: lpass-irq-lpaif - - items: #for I2S and HDMI - - const: lpass-irq-lpaif - - const: lpass-irq-hdmi - - items: #for I2S, soundwire and HDMI - - const: lpass-irq-lpaif - - const: lpass-irq-hdmi - - const: lpass-irq-vaif - - const: lpass-irq-rxtxif + items: + - const: lpass-irq-lpaif + - const: lpass-irq-hdmi + - const: lpass-irq-vaif + - const: lpass-irq-rxtxif power-domain-names: - allOf: - - items: - - const: lcx + items: + - const: lcx required: - iommus diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml index 66431aade3b7..da5f70910da5 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml @@ -30,7 +30,9 @@ properties: const: 0 clocks: - maxItems: 5 + oneOf: + - maxItems: 3 + - maxItems: 5 clock-names: oneOf: diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml index 26f0343b5aac..0a3c688ef1ec 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml @@ -36,7 +36,7 @@ properties: oneOf: - items: #for ADSP based platforms - const: mclk - - const: core + - const: macro - const: dcodec - items: #for ADSP bypass based platforms - const: mclk @@ -77,7 +77,7 @@ examples: clocks = <&aoncc 0>, <&q6afecc LPASS_HW_MACRO_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>, <&q6afecc LPASS_HW_DCODEC_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>; - clock-names = "mclk", "core", "dcodec"; + clock-names = "mclk", "macro", "dcodec"; clock-output-names = "fsgen"; qcom,dmic-sample-rate = <600000>; vdd-micb-supply = <&vreg_s4a_1p8>; diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml index 2bf8d082f8f1..66cbb1f5e31a 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml @@ -9,9 +9,6 @@ title: LPASS(Low Power Audio Subsystem) VA Macro audio codec maintainers: - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> -allOf: - - $ref: dai-common.yaml# - properties: compatible: enum: @@ -30,15 +27,12 @@ properties: const: 0 clocks: - maxItems: 5 + minItems: 5 + maxItems: 6 clock-names: - items: - - const: mclk - - const: npl - - const: macro - - const: dcodec - - const: fsgen + minItems: 5 + maxItems: 6 clock-output-names: maxItems: 1 @@ -55,10 +49,51 @@ required: - reg - "#sound-dai-cells" +allOf: + - $ref: dai-common.yaml# + + - if: + properties: + compatible: + enum: + - qcom,sc7280-lpass-wsa-macro + - qcom,sm8450-lpass-wsa-macro + - qcom,sc8280xp-lpass-wsa-macro + then: + properties: + clocks: + maxItems: 5 + clock-names: + items: + - const: mclk + - const: npl + - const: macro + - const: dcodec + - const: fsgen + + - if: + properties: + compatible: + enum: + - qcom,sm8250-lpass-wsa-macro + then: + properties: + clocks: + minItems: 6 + clock-names: + items: + - const: mclk + - const: npl + - const: macro + - const: dcodec + - const: va + - const: fsgen + unevaluatedProperties: false examples: - | + #include <dt-bindings/clock/qcom,sm8250-lpass-aoncc.h> #include <dt-bindings/sound/qcom,q6afe.h> codec@3240000 { compatible = "qcom,sm8250-lpass-wsa-macro"; @@ -69,7 +104,8 @@ examples: <&audiocc 0>, <&q6afecc LPASS_HW_MACRO_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>, <&q6afecc LPASS_HW_DCODEC_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>, + <&aoncc LPASS_CDC_VA_MCLK>, <&vamacro>; - clock-names = "mclk", "npl", "macro", "dcodec", "fsgen"; + clock-names = "mclk", "npl", "macro", "dcodec", "va", "fsgen"; clock-output-names = "mclk"; }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6apm-dai.yaml b/Documentation/devicetree/bindings/sound/qcom,q6apm-dai.yaml index a53c9ef938fa..cdbb4096fa44 100644 --- a/Documentation/devicetree/bindings/sound/qcom,q6apm-dai.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,q6apm-dai.yaml @@ -17,7 +17,8 @@ properties: const: qcom,q6apm-dais iommus: - maxItems: 1 + minItems: 1 + maxItems: 2 required: - compatible diff --git a/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml b/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml index 70080d04ddc9..262de7a60a73 100644 --- a/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml @@ -15,16 +15,20 @@ description: properties: compatible: - enum: - - lenovo,yoga-c630-sndcard - - qcom,apq8016-sbc-sndcard - - qcom,db845c-sndcard - - qcom,msm8916-qdsp6-sndcard - - qcom,qrb5165-rb5-sndcard - - qcom,sc8280xp-sndcard - - qcom,sdm845-sndcard - - qcom,sm8250-sndcard - - qcom,sm8450-sndcard + oneOf: + - items: + - enum: + - lenovo,yoga-c630-sndcard + - qcom,db845c-sndcard + - const: qcom,sdm845-sndcard + - enum: + - qcom,apq8016-sbc-sndcard + - qcom,msm8916-qdsp6-sndcard + - qcom,qrb5165-rb5-sndcard + - qcom,sc8280xp-sndcard + - qcom,sdm845-sndcard + - qcom,sm8250-sndcard + - qcom,sm8450-sndcard audio-routing: $ref: /schemas/types.yaml#/definitions/non-unique-string-array diff --git a/Documentation/devicetree/bindings/sound/qcom,wcd934x.yaml b/Documentation/devicetree/bindings/sound/qcom,wcd934x.yaml index 184e8ccbdd13..ea09590bfa30 100644 --- a/Documentation/devicetree/bindings/sound/qcom,wcd934x.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,wcd934x.yaml @@ -28,7 +28,9 @@ properties: description: GPIO spec for reset line to use maxItems: 1 - slim-ifc-dev: true + slim-ifc-dev: + description: IFC device interface + $ref: /schemas/types.yaml#/definitions/phandle clocks: maxItems: 1 @@ -147,21 +149,49 @@ patternProperties: required: - compatible - reg - - reset-gpios - - slim-ifc-dev - - interrupts - - interrupt-controller - - clock-frequency - - clock-output-names - - qcom,micbias1-microvolt - - qcom,micbias2-microvolt - - qcom,micbias3-microvolt - - qcom,micbias4-microvolt - - "#interrupt-cells" - - "#clock-cells" - - "#sound-dai-cells" - - "#address-cells" - - "#size-cells" + +allOf: + - if: + required: + - slim-ifc-dev + then: + required: + - reset-gpios + - slim-ifc-dev + - interrupt-controller + - clock-frequency + - clock-output-names + - qcom,micbias1-microvolt + - qcom,micbias2-microvolt + - qcom,micbias3-microvolt + - qcom,micbias4-microvolt + - "#interrupt-cells" + - "#clock-cells" + - "#sound-dai-cells" + - "#address-cells" + - "#size-cells" + oneOf: + - required: + - interrupts-extended + - required: + - interrupts + else: + properties: + reset-gpios: false + slim-ifc-dev: false + interrupts: false + interrupt-controller: false + clock-frequency: false + clock-output-names: false + qcom,micbias1-microvolt: false + qcom,micbias2-microvolt: false + qcom,micbias3-microvolt: false + qcom,micbias4-microvolt: false + "#interrupt-cells": false + "#clock-cells": false + "#sound-dai-cells": false + "#address-cells": false + "#size-cells": false additionalProperties: false diff --git a/Documentation/devicetree/bindings/sound/qcom,wsa881x.yaml b/Documentation/devicetree/bindings/sound/qcom,wsa881x.yaml index d702b489320f..ac03672ebf6d 100644 --- a/Documentation/devicetree/bindings/sound/qcom,wsa881x.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,wsa881x.yaml @@ -15,6 +15,9 @@ description: | Their primary operating mode uses a SoundWire digital audio interface. This binding is for SoundWire interface. +allOf: + - $ref: dai-common.yaml# + properties: compatible: const: sdw10217201000 @@ -39,7 +42,7 @@ required: - "#thermal-sensor-cells" - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/renesas,idt821034.yaml b/Documentation/devicetree/bindings/sound/renesas,idt821034.yaml new file mode 100644 index 000000000000..a2b92dba5529 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/renesas,idt821034.yaml @@ -0,0 +1,75 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/renesas,idt821034.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas IDT821034 codec device + +maintainers: + - Herve Codina <herve.codina@bootlin.com> + +description: | + The IDT821034 codec is a four channel PCM codec with onchip filters and + programmable gain setting. + + The time-slots used by the codec must be set and so, the properties + 'dai-tdm-slot-num', 'dai-tdm-slot-width', 'dai-tdm-slot-tx-mask' and + 'dai-tdm-slot-rx-mask' must be present in the ALSA sound card node for + sub-nodes that involve the codec. The codec uses one 8bit time-slot per + channel. + 'dai-tdm-tdm-slot-with' must be set to 8. + + The IDT821034 codec also supports 5 gpios (SLIC signals) per channel. + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + - $ref: dai-common.yaml# + +properties: + compatible: + const: renesas,idt821034 + + reg: + description: + SPI device address. + maxItems: 1 + + spi-max-frequency: + maximum: 8192000 + + spi-cpha: true + + '#sound-dai-cells': + const: 0 + + '#gpio-cells': + const: 2 + + gpio-controller: true + +required: + - compatible + - reg + - spi-cpha + - '#sound-dai-cells' + - gpio-controller + - '#gpio-cells' + +unevaluatedProperties: false + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + audio-codec@0 { + compatible = "renesas,idt821034"; + reg = <0>; + spi-max-frequency = <8192000>; + spi-cpha; + #sound-dai-cells = <0>; + gpio-controller; + #gpio-cells = <2>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml index cb90463c7297..12ccf29338d9 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml @@ -18,8 +18,7 @@ properties: - enum: - renesas,rcar_sound-r8a7778 # R-Car M1A - renesas,rcar_sound-r8a7779 # R-Car H1 - - enum: - - renesas,rcar_sound-gen1 + - const: renesas,rcar_sound-gen1 # for Gen2 SoC - items: - enum: @@ -32,8 +31,7 @@ properties: - renesas,rcar_sound-r8a7791 # R-Car M2-W - renesas,rcar_sound-r8a7793 # R-Car M2-N - renesas,rcar_sound-r8a7794 # R-Car E2 - - enum: - - renesas,rcar_sound-gen2 + - const: renesas,rcar_sound-gen2 # for Gen3 SoC - items: - enum: @@ -47,14 +45,16 @@ properties: - renesas,rcar_sound-r8a77965 # R-Car M3-N - renesas,rcar_sound-r8a77990 # R-Car E3 - renesas,rcar_sound-r8a77995 # R-Car D3 - - enum: - - renesas,rcar_sound-gen3 - # for Generic + - const: renesas,rcar_sound-gen3 + # for Gen4 SoC - items: - - enum: - - renesas,rcar_sound-gen1 - - renesas,rcar_sound-gen2 - - renesas,rcar_sound-gen3 + - const: renesas,rcar_sound-r8a779g0 # R-Car V4H + - const: renesas,rcar_sound-gen4 + # for Generic + - enum: + - renesas,rcar_sound-gen1 + - renesas,rcar_sound-gen2 + - renesas,rcar_sound-gen3 reg: minItems: 1 @@ -68,6 +68,7 @@ properties: description: | it must be 0 if your system is using single DAI it must be 1 if your system is using multi DAIs + This is used on simple-audio-card enum: [0, 1] "#clock-cells": @@ -113,15 +114,34 @@ properties: - pattern: '^clk_(a|b|c|i)$' ports: - $ref: /schemas/graph.yaml#/properties/ports + $ref: audio-graph-port.yaml#/definitions/port-base + unevaluatedProperties: false patternProperties: '^port(@[0-9a-f]+)?$': - $ref: audio-graph-port.yaml# + $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 port: - $ref: audio-graph-port.yaml# + $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 rcar_sound,dvc: description: DVC subnode. @@ -178,10 +198,6 @@ properties: enum: - tx - rx - required: - - interrupts - - dmas - - dma-names additionalProperties: false rcar_sound,ssiu: @@ -240,8 +256,6 @@ properties: $ref: /schemas/types.yaml#/definitions/flag required: - interrupts - - dmas - - dma-names additionalProperties: false # For DAI base @@ -271,7 +285,6 @@ required: - reg-names - clocks - clock-names - - "#sound-dai-cells" allOf: - $ref: dai-common.yaml# @@ -285,7 +298,6 @@ allOf: reg: maxItems: 3 reg-names: - maxItems: 3 items: enum: - scu @@ -294,9 +306,8 @@ allOf: else: properties: reg: - maxItems: 5 + minItems: 5 reg-names: - maxItems: 5 items: enum: - scu diff --git a/Documentation/devicetree/bindings/sound/rt5640.txt b/Documentation/devicetree/bindings/sound/rt5640.txt index ff1228713f7e..0c398581d52b 100644 --- a/Documentation/devicetree/bindings/sound/rt5640.txt +++ b/Documentation/devicetree/bindings/sound/rt5640.txt @@ -20,6 +20,9 @@ Optional properties: - realtek,in3-differential Boolean. Indicate MIC1/2/3 input are differential, rather than single-ended. +- realtek,lout-differential + Boolean. Indicate LOUT output is differential, rather than stereo. + - realtek,ldo1-en-gpios : The GPIO that controls the CODEC's LDO1_EN pin. - realtek,dmic1-data-pin diff --git a/Documentation/devicetree/bindings/sound/samsung,odroid.yaml b/Documentation/devicetree/bindings/sound/samsung,odroid.yaml index 7b4e08ddef6a..7774543b8819 100644 --- a/Documentation/devicetree/bindings/sound/samsung,odroid.yaml +++ b/Documentation/devicetree/bindings/sound/samsung,odroid.yaml @@ -43,9 +43,10 @@ properties: type: object properties: sound-dai: + minItems: 1 items: - - description: phandle of the MAX98090 CODEC - description: phandle of the HDMI IP block node + - description: phandle of the MAX98090 CODEC samsung,audio-routing: $ref: /schemas/types.yaml#/definitions/non-unique-string-array diff --git a/Documentation/devicetree/bindings/sound/samsung-i2s.yaml b/Documentation/devicetree/bindings/sound/samsung-i2s.yaml index 8d5dcf9cd43e..30b3b6e9824b 100644 --- a/Documentation/devicetree/bindings/sound/samsung-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/samsung-i2s.yaml @@ -37,12 +37,20 @@ properties: samsung,exynos7-i2s1: I2S1 on previous samsung platforms supports stereo channels. Exynos7 I2S1 upgraded to 5.1 multichannel with slightly modified bit offsets. + + tesla,fsd-i2s: for 8/16/24bit stereo channel I2S for playback and + capture, secondary FIFO using external DMA, s/w reset control, + internal mux for root clock source with all root clock sampling + frequencies supported by Exynos7 I2S and 7.1 channel TDM support + for playback and capture TDM (Time division multiplexing) to allow + transfer of multiple channel audio data on single data line. enum: - samsung,s3c6410-i2s - samsung,s5pv210-i2s - samsung,exynos5420-i2s - samsung,exynos7-i2s - samsung,exynos7-i2s1 + - tesla,fsd-i2s '#address-cells': const: 1 @@ -67,9 +75,6 @@ properties: - const: rx - const: tx-sec - assigned-clock-parents: true - assigned-clocks: true - clocks: minItems: 1 maxItems: 3 diff --git a/Documentation/devicetree/bindings/sound/simple-card.yaml b/Documentation/devicetree/bindings/sound/simple-card.yaml index ed19899bc94b..f0d81bfe2598 100644 --- a/Documentation/devicetree/bindings/sound/simple-card.yaml +++ b/Documentation/devicetree/bindings/sound/simple-card.yaml @@ -205,6 +205,8 @@ patternProperties: $ref: "#/definitions/dai" "^simple-audio-card,codec(@[0-9a-f]+)?$": $ref: "#/definitions/dai" + "^simple-audio-card,plat(@[0-9a-f]+)?$": + $ref: "#/definitions/dai" "^simple-audio-card,dai-link(@[0-9a-f]+)?$": description: | @@ -215,6 +217,10 @@ patternProperties: reg: maxItems: 1 + "#address-cells": + const: 1 + "#size-cells": + const: 0 # common properties frame-master: $ref: "#/definitions/frame-master" @@ -244,9 +250,9 @@ patternProperties: maxItems: 1 patternProperties: - "^cpu(@[0-9a-f]+)?": + "^cpu(-[0-9]+)?$": $ref: "#/definitions/dai" - "^codec(@[0-9a-f]+)?": + "^codec(-[0-9]+)?$": $ref: "#/definitions/dai" additionalProperties: false @@ -462,16 +468,16 @@ examples: convert-channels = <8>; /* TDM Split */ - sndcpu1: cpu0 { + sndcpu1: cpu-0 { sound-dai = <&rcar_sound 1>; }; - cpu1 { + cpu-1 { sound-dai = <&rcar_sound 2>; }; - cpu2 { + cpu-2 { sound-dai = <&rcar_sound 3>; }; - cpu3 { + cpu-3 { sound-dai = <&rcar_sound 4>; }; codec { diff --git a/Documentation/devicetree/bindings/sound/tas5720.txt b/Documentation/devicetree/bindings/sound/tas5720.txt index df99ca9451b0..7d851ae2bba2 100644 --- a/Documentation/devicetree/bindings/sound/tas5720.txt +++ b/Documentation/devicetree/bindings/sound/tas5720.txt @@ -6,11 +6,13 @@ audio playback. For more product information please see the links below: https://www.ti.com/product/TAS5720L https://www.ti.com/product/TAS5720M +https://www.ti.com/product/TAS5720A-Q1 https://www.ti.com/product/TAS5722L Required properties: - compatible : "ti,tas5720", + "ti,tas5720a-q1", "ti,tas5722" - reg : I2C slave address - dvdd-supply : phandle to a 3.3-V supply for the digital circuitry diff --git a/Documentation/devicetree/bindings/sound/ti,pcm3168a.txt b/Documentation/devicetree/bindings/sound/ti,pcm3168a.txt deleted file mode 100644 index a02ecaab5183..000000000000 --- a/Documentation/devicetree/bindings/sound/ti,pcm3168a.txt +++ /dev/null @@ -1,56 +0,0 @@ -Texas Instruments pcm3168a DT bindings - -This driver supports both SPI and I2C bus access for this codec - -Required properties: - - - compatible: "ti,pcm3168a" - - - clocks : Contains an entry for each entry in clock-names - - - clock-names : Includes the following entries: - "scki" The system clock - - - VDD1-supply : Digital power supply regulator 1 (+3.3V) - - - VDD2-supply : Digital power supply regulator 2 (+3.3V) - - - VCCAD1-supply : ADC power supply regulator 1 (+5V) - - - VCCAD2-supply : ADC power supply regulator 2 (+5V) - - - VCCDA1-supply : DAC power supply regulator 1 (+5V) - - - VCCDA2-supply : DAC power supply regulator 2 (+5V) - -For required properties on SPI/I2C, consult SPI/I2C device tree documentation - -Optional properties: - - - reset-gpios : Optional reset gpio line connected to RST pin of the codec. - The RST line is low active: - RST = low: device power-down - RST = high: device is enabled - -Examples: - -i2c0: i2c0@0 { - - ... - - pcm3168a: audio-codec@44 { - compatible = "ti,pcm3168a"; - reg = <0x44>; - reset-gpios = <&gpio0 4 GPIO_ACTIVE_LOW>; - clocks = <&clk_core CLK_AUDIO>; - clock-names = "scki"; - VDD1-supply = <&supply3v3>; - VDD2-supply = <&supply3v3>; - VCCAD1-supply = <&supply5v0>; - VCCAD2-supply = <&supply5v0>; - VCCDA1-supply = <&supply5v0>; - VCCDA2-supply = <&supply5v0>; - pinctrl-names = "default"; - pinctrl-0 = <&dac_clk_pin>; - }; -}; diff --git a/Documentation/devicetree/bindings/sound/ti,pcm3168a.yaml b/Documentation/devicetree/bindings/sound/ti,pcm3168a.yaml new file mode 100644 index 000000000000..b6a4360ab845 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ti,pcm3168a.yaml @@ -0,0 +1,107 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/ti,pcm3168a.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments PCM3168A Audio Codec + +maintainers: + - Damien Horsley <Damien.Horsley@imgtec.com> + - Geert Uytterhoeven <geert+renesas@glider.be> + - Kuninori Morimoto <kuninori.morimoto.gx@renesas.com> + +description: + The Texas Instruments PCM3168A is a 24-bit Multi-channel Audio CODEC with + 96/192kHz sampling rate, supporting both SPI and I2C bus access. + +properties: + compatible: + const: ti,pcm3168a + + reg: + maxItems: 1 + + clocks: + items: + - description: System clock input + + clock-names: + items: + - const: scki + + reset-gpios: + items: + - description: | + GPIO line connected to the active-low RST pin of the codec. + RST = low: device power-down + RST = high: device is enabled + + "#sound-dai-cells": + enum: [0, 1] + + VDD1-supply: + description: Digital power supply regulator 1 (+3.3V) + + VDD2-supply: + description: Digital power supply regulator 2 (+3.3V) + + VCCAD1-supply: + description: ADC power supply regulator 1 (+5V) + + VCCAD2-supply: + description: ADC power supply regulator 2 (+5V) + + VCCDA1-supply: + description: DAC power supply regulator 1 (+5V) + + VCCDA2-supply: + description: DAC power supply regulator 2 (+5V) + + ports: + $ref: audio-graph-port.yaml#/definitions/port-base + properties: + port@0: + $ref: audio-graph-port.yaml# + description: Audio input port. + + port@1: + $ref: audio-graph-port.yaml# + description: Audio output port. + +required: + - compatible + - reg + - clocks + - clock-names + - VDD1-supply + - VDD2-supply + - VCCAD1-supply + - VCCAD2-supply + - VCCDA1-supply + - VCCDA2-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pcm3168a: audio-codec@44 { + compatible = "ti,pcm3168a"; + reg = <0x44>; + reset-gpios = <&gpio0 4 GPIO_ACTIVE_LOW>; + clocks = <&clk_core 42>; + clock-names = "scki"; + VDD1-supply = <&supply3v3>; + VDD2-supply = <&supply3v3>; + VCCAD1-supply = <&supply5v0>; + VCCAD2-supply = <&supply5v0>; + VCCDA1-supply = <&supply5v0>; + VCCDA2-supply = <&supply5v0>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/ti,tlv320aic3x.yaml b/Documentation/devicetree/bindings/sound/ti,tlv320aic3x.yaml new file mode 100644 index 000000000000..e8ca9f3369f8 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ti,tlv320aic3x.yaml @@ -0,0 +1,165 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +# Copyright (C) 2022 Texas Instruments Incorporated +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/ti,tlv320aic3x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments TLV320AIC3x Codec + +description: | + TLV320AIC3x are a series of low-power stereo audio codecs with stereo + headphone amplifier, as well as multiple inputs and outputs programmable in + single-ended or fully differential configurations. + + The serial control bus supports SPI or I2C protocols, while the serial audio + data bus is programmable for I2S, left/right-justified, DSP, or TDM modes. + + The following pins can be referred in the sound node's audio routing property: + + CODEC output pins: + LLOUT + RLOUT + MONO_LOUT + HPLOUT + HPROUT + HPLCOM + HPRCOM + + CODEC input pins for TLV320AIC3104: + MIC2L + MIC2R + LINE1L + LINE1R + + CODEC input pins for other compatible codecs: + MIC3L + MIC3R + LINE1L + LINE2L + LINE1R + LINE2R + +maintainers: + - Jai Luthra <j-luthra@ti.com> + +properties: + compatible: + enum: + - ti,tlv320aic3x + - ti,tlv320aic33 + - ti,tlv320aic3007 + - ti,tlv320aic3106 + - ti,tlv320aic3104 + + reg: + maxItems: 1 + + reset-gpios: + maxItems: 1 + description: + GPIO specification for the active low RESET input. + + gpio-reset: + maxItems: 1 + description: + Deprecated, please use reset-gpios instead. + deprecated: true + + ai3x-gpio-func: + description: AIC3X_GPIO1 & AIC3X_GPIO2 Functionality + $ref: /schemas/types.yaml#/definitions/uint32-array + maxItems: 2 + + ai3x-micbias-vg: + description: MicBias required voltage. If node is omitted then MicBias is powered down. + $ref: /schemas/types.yaml#/definitions/uint32 + oneOf: + - const: 1 + description: MICBIAS output is powered to 2.0V. + - const: 2 + description: MICBIAS output is powered to 2.5V. + - const: 3 + description: MICBIAS output is connected to AVDD. + + ai3x-ocmv: + description: Output Common-Mode Voltage selection. + $ref: /schemas/types.yaml#/definitions/uint32 + oneOf: + - const: 0 + description: 1.35V + - const: 1 + description: 1.5V + - const: 2 + description: 1.65V + - const: 3 + description: 1.8V + + AVDD-supply: + description: Analog DAC voltage. + + IOVDD-supply: + description: I/O voltage. + + DRVDD-supply: + description: ADC analog and output driver voltage. + + DVDD-supply: + description: Digital core voltage. + + '#sound-dai-cells': + const: 0 + + clocks: + maxItems: 1 + + port: + $ref: audio-graph-port.yaml# + unevaluatedProperties: false + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + tlv320aic3x_i2c: audio-codec@1b { + compatible = "ti,tlv320aic3x"; + reg = <0x1b>; + + reset-gpios = <&gpio1 17 GPIO_ACTIVE_LOW>; + + AVDD-supply = <®ulator>; + IOVDD-supply = <®ulator>; + DRVDD-supply = <®ulator>; + DVDD-supply = <®ulator>; + }; + }; + + - | + #include <dt-bindings/gpio/gpio.h> + spi { + #address-cells = <1>; + #size-cells = <0>; + + tlv320aic3x_spi: audio-codec@0 { + compatible = "ti,tlv320aic3x"; + reg = <0>; /* CS number */ + #sound-dai-cells = <0>; + + AVDD-supply = <®ulator>; + IOVDD-supply = <®ulator>; + DRVDD-supply = <®ulator>; + DVDD-supply = <®ulator>; + ai3x-ocmv = <0>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/tlv320aic3x.txt b/Documentation/devicetree/bindings/sound/tlv320aic3x.txt deleted file mode 100644 index 20931a63fd64..000000000000 --- a/Documentation/devicetree/bindings/sound/tlv320aic3x.txt +++ /dev/null @@ -1,97 +0,0 @@ -Texas Instruments - tlv320aic3x Codec module - -The tlv320aic3x serial control bus communicates through both I2C and SPI bus protocols - -Required properties: - -- compatible - "string" - One of: - "ti,tlv320aic3x" - Generic TLV320AIC3x device - "ti,tlv320aic33" - TLV320AIC33 - "ti,tlv320aic3007" - TLV320AIC3007 - "ti,tlv320aic3106" - TLV320AIC3106 - "ti,tlv320aic3104" - TLV320AIC3104 - - -- reg - <int> - I2C slave address - - -Optional properties: - -- reset-gpios - GPIO specification for the active low RESET input. -- ai3x-gpio-func - <array of 2 int> - AIC3X_GPIO1 & AIC3X_GPIO2 Functionality - - Not supported on tlv320aic3104 -- ai3x-micbias-vg - MicBias Voltage required. - 1 - MICBIAS output is powered to 2.0V, - 2 - MICBIAS output is powered to 2.5V, - 3 - MICBIAS output is connected to AVDD, - If this node is not mentioned or if the value is incorrect, then MicBias - is powered down. -- ai3x-ocmv - Output Common-Mode Voltage selection: - 0 - 1.35V, - 1 - 1.5V, - 2 - 1.65V, - 3 - 1.8V -- AVDD-supply, IOVDD-supply, DRVDD-supply, DVDD-supply : power supplies for the - device as covered in Documentation/devicetree/bindings/regulator/regulator.txt - -Deprecated properties: - -- gpio-reset - gpio pin number used for codec reset - -CODEC output pins: - * LLOUT - * RLOUT - * MONO_LOUT - * HPLOUT - * HPROUT - * HPLCOM - * HPRCOM - -CODEC input pins for TLV320AIC3104: - * MIC2L - * MIC2R - * LINE1L - * LINE1R - -CODEC input pins for other compatible codecs: - * MIC3L - * MIC3R - * LINE1L - * LINE2L - * LINE1R - * LINE2R - -The pins can be used in referring sound node's audio-routing property. - -I2C example: - -#include <dt-bindings/gpio/gpio.h> - -tlv320aic3x: tlv320aic3x@1b { - compatible = "ti,tlv320aic3x"; - reg = <0x1b>; - - reset-gpios = <&gpio1 17 GPIO_ACTIVE_LOW>; - - AVDD-supply = <®ulator>; - IOVDD-supply = <®ulator>; - DRVDD-supply = <®ulator>; - DVDD-supply = <®ulator>; -}; - -SPI example: - -spi0: spi@f0000000 { - tlv320aic3x: codec@0 { - compatible = "ti,tlv320aic3x"; - reg = <0>; /* CS number */ - #sound-dai-cells = <0>; - spi-max-frequency = <1000000>; - - AVDD-supply = <®ulator>; - IOVDD-supply = <®ulator>; - DRVDD-supply = <®ulator>; - DVDD-supply = <®ulator>; - ai3x-ocmv = <0>; - }; -}; diff --git a/Documentation/devicetree/bindings/soundwire/qcom,soundwire.yaml b/Documentation/devicetree/bindings/soundwire/qcom,soundwire.yaml index bcbfa71536cd..3efdc192ab01 100644 --- a/Documentation/devicetree/bindings/soundwire/qcom,soundwire.yaml +++ b/Documentation/devicetree/bindings/soundwire/qcom,soundwire.yaml @@ -80,7 +80,7 @@ properties: or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. minItems: 3 - maxItems: 5 + maxItems: 8 qcom,ports-sinterval-low: $ref: /schemas/types.yaml#/definitions/uint8-array @@ -124,7 +124,7 @@ properties: or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. minItems: 3 - maxItems: 5 + maxItems: 8 qcom,ports-block-pack-mode: $ref: /schemas/types.yaml#/definitions/uint8-array @@ -154,7 +154,7 @@ properties: or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. minItems: 3 - maxItems: 5 + maxItems: 8 items: oneOf: - minimum: 0 @@ -171,7 +171,7 @@ properties: or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. minItems: 3 - maxItems: 5 + maxItems: 8 items: oneOf: - minimum: 0 @@ -187,7 +187,7 @@ properties: or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. minItems: 3 - maxItems: 5 + maxItems: 8 items: oneOf: - minimum: 0 diff --git a/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml b/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml index f1176a28fd87..eb0567b2971a 100644 --- a/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml +++ b/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Allwinner A10 SPI Controller allOf: - - $ref: "spi-controller.yaml" + - $ref: spi-controller.yaml maintainers: - Chen-Yu Tsai <wens@csie.org> diff --git a/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml b/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml index 58b7056f4a70..acf218507d22 100644 --- a/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml +++ b/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Allwinner A31 SPI Controller allOf: - - $ref: "spi-controller.yaml" + - $ref: spi-controller.yaml maintainers: - Chen-Yu Tsai <wens@csie.org> diff --git a/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml b/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml index 53eb6562b979..4e28e6e9d8e0 100644 --- a/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml +++ b/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml @@ -2,8 +2,8 @@ # Copyright 2019 BayLibre, SAS %YAML 1.2 --- -$id: "http://devicetree.org/schemas/spi/amlogic,meson-gx-spicc.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/spi/amlogic,meson-gx-spicc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Amlogic Meson SPI Communication Controller @@ -41,7 +41,7 @@ properties: maxItems: 2 allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# - if: properties: compatible: @@ -100,17 +100,17 @@ unevaluatedProperties: false examples: - | spi@c1108d80 { - compatible = "amlogic,meson-gx-spicc"; - reg = <0xc1108d80 0x80>; - interrupts = <112>; - clocks = <&clk81>; - clock-names = "core"; - #address-cells = <1>; - #size-cells = <0>; - - display@0 { - compatible = "lg,lg4573"; - spi-max-frequency = <1000000>; - reg = <0>; - }; + compatible = "amlogic,meson-gx-spicc"; + reg = <0xc1108d80 0x80>; + interrupts = <112>; + clocks = <&clk81>; + clock-names = "core"; + #address-cells = <1>; + #size-cells = <0>; + + display@0 { + compatible = "lg,lg4573"; + spi-max-frequency = <1000000>; + reg = <0>; + }; }; diff --git a/Documentation/devicetree/bindings/spi/amlogic,meson6-spifc.yaml b/Documentation/devicetree/bindings/spi/amlogic,meson6-spifc.yaml index ac3b2ec300ac..8e769ccda97f 100644 --- a/Documentation/devicetree/bindings/spi/amlogic,meson6-spifc.yaml +++ b/Documentation/devicetree/bindings/spi/amlogic,meson6-spifc.yaml @@ -2,8 +2,8 @@ # Copyright 2019 BayLibre, SAS %YAML 1.2 --- -$id: "http://devicetree.org/schemas/spi/amlogic,meson6-spifc.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/spi/amlogic,meson6-spifc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Amlogic Meson SPI Flash Controller @@ -11,7 +11,7 @@ maintainers: - Neil Armstrong <neil.armstrong@linaro.org> allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# description: | The Meson SPIFC is a controller optimized for communication with SPI @@ -40,15 +40,15 @@ unevaluatedProperties: false examples: - | spi@c1108c80 { - compatible = "amlogic,meson6-spifc"; - reg = <0xc1108c80 0x80>; - clocks = <&clk81>; - #address-cells = <1>; - #size-cells = <0>; - - flash: flash@0 { - compatible = "spansion,m25p80", "jedec,spi-nor"; - reg = <0>; - spi-max-frequency = <40000000>; - }; + compatible = "amlogic,meson6-spifc"; + reg = <0xc1108c80 0x80>; + clocks = <&clk81>; + #address-cells = <1>; + #size-cells = <0>; + + flash: flash@0 { + compatible = "spansion,m25p80", "jedec,spi-nor"; + reg = <0>; + spi-max-frequency = <40000000>; + }; }; diff --git a/Documentation/devicetree/bindings/spi/aspeed,ast2600-fmc.yaml b/Documentation/devicetree/bindings/spi/aspeed,ast2600-fmc.yaml index e6c817de3449..57d932af4506 100644 --- a/Documentation/devicetree/bindings/spi/aspeed,ast2600-fmc.yaml +++ b/Documentation/devicetree/bindings/spi/aspeed,ast2600-fmc.yaml @@ -15,7 +15,7 @@ description: | SPI) of the AST2400, AST2500 and AST2600 SOCs. allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# properties: compatible: @@ -60,23 +60,23 @@ examples: interrupts = <GIC_SPI 39 IRQ_TYPE_LEVEL_HIGH>; flash@0 { - reg = < 0 >; - compatible = "jedec,spi-nor"; - spi-max-frequency = <50000000>; - spi-rx-bus-width = <2>; + reg = < 0 >; + compatible = "jedec,spi-nor"; + spi-max-frequency = <50000000>; + spi-rx-bus-width = <2>; }; flash@1 { - reg = < 1 >; - compatible = "jedec,spi-nor"; - spi-max-frequency = <50000000>; - spi-rx-bus-width = <2>; + reg = < 1 >; + compatible = "jedec,spi-nor"; + spi-max-frequency = <50000000>; + spi-rx-bus-width = <2>; }; flash@2 { - reg = < 2 >; - compatible = "jedec,spi-nor"; - spi-max-frequency = <50000000>; - spi-rx-bus-width = <2>; + reg = < 2 >; + compatible = "jedec,spi-nor"; + spi-max-frequency = <50000000>; + spi-rx-bus-width = <2>; }; }; diff --git a/Documentation/devicetree/bindings/spi/atmel,at91rm9200-spi.yaml b/Documentation/devicetree/bindings/spi/atmel,at91rm9200-spi.yaml index 4dd973e341e6..6c57dd6c3a36 100644 --- a/Documentation/devicetree/bindings/spi/atmel,at91rm9200-spi.yaml +++ b/Documentation/devicetree/bindings/spi/atmel,at91rm9200-spi.yaml @@ -8,7 +8,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Atmel SPI device maintainers: - - Tudor Ambarus <tudor.ambarus@microchip.com> + - Tudor Ambarus <tudor.ambarus@linaro.org> allOf: - $ref: spi-controller.yaml# diff --git a/Documentation/devicetree/bindings/spi/atmel,quadspi.yaml b/Documentation/devicetree/bindings/spi/atmel,quadspi.yaml index 1d493add4053..b0d99bc10535 100644 --- a/Documentation/devicetree/bindings/spi/atmel,quadspi.yaml +++ b/Documentation/devicetree/bindings/spi/atmel,quadspi.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Atmel Quad Serial Peripheral Interface (QSPI) maintainers: - - Tudor Ambarus <tudor.ambarus@microchip.com> + - Tudor Ambarus <tudor.ambarus@linaro.org> allOf: - $ref: spi-controller.yaml# diff --git a/Documentation/devicetree/bindings/spi/brcm,bcm63xx-hsspi.yaml b/Documentation/devicetree/bindings/spi/brcm,bcm63xx-hsspi.yaml new file mode 100644 index 000000000000..6554978583f8 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/brcm,bcm63xx-hsspi.yaml @@ -0,0 +1,134 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/brcm,bcm63xx-hsspi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom Broadband SoC High Speed SPI controller + +maintainers: + - William Zhang <william.zhang@broadcom.com> + - Kursad Oney <kursad.oney@broadcom.com> + - Jonas Gorski <jonas.gorski@gmail.com> + +description: | + Broadcom Broadband SoC supports High Speed SPI master controller since the + early MIPS based chips such as BCM6328 and BCM63268. This initial rev 1.0 + controller was carried over to recent ARM based chips, such as BCM63138, + BCM4908 and BCM6858. The old MIPS based chip should continue to use the + brcm,bcm6328-hsspi compatible string. The recent ARM based chip is required to + use the brcm,bcmbca-hsspi-v1.0 as part of its compatible string list as + defined below to match the specific chip along with ip revision info. + + This rev 1.0 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 either the controller's prepend mode or using the dummy chip + select workaround. Driver automatically picks the suitable mode based on + transfer type so it is transparent to the user. + + The newer SoCs such as BCM6756, BCM4912 and BCM6855 include an updated SPI + controller rev 1.1 that add the capability to allow the driver to control chip + select explicitly. This solves the issue in the old controller. + +properties: + compatible: + oneOf: + - const: brcm,bcm6328-hsspi + - items: + - enum: + - brcm,bcm47622-hsspi + - brcm,bcm4908-hsspi + - brcm,bcm63138-hsspi + - brcm,bcm63146-hsspi + - brcm,bcm63148-hsspi + - brcm,bcm63158-hsspi + - brcm,bcm63178-hsspi + - brcm,bcm6846-hsspi + - brcm,bcm6856-hsspi + - brcm,bcm6858-hsspi + - brcm,bcm6878-hsspi + - const: brcm,bcmbca-hsspi-v1.0 + - items: + - enum: + - brcm,bcm4912-hsspi + - brcm,bcm6756-hsspi + - brcm,bcm6813-hsspi + - brcm,bcm6855-hsspi + - const: brcm,bcmbca-hsspi-v1.1 + + reg: + items: + - description: main registers + - description: miscellaneous control registers + minItems: 1 + + reg-names: + items: + - const: hsspi + - const: spim-ctrl + minItems: 1 + + clocks: + items: + - description: SPI master reference clock + - description: SPI master pll clock + + clock-names: + items: + - const: hsspi + - const: pll + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + +allOf: + - $ref: spi-controller.yaml# + - if: + properties: + compatible: + contains: + enum: + - brcm,bcm6328-hsspi + - brcm,bcmbca-hsspi-v1.0 + then: + properties: + reg: + maxItems: 1 + reg-names: + maxItems: 1 + else: + properties: + reg: + minItems: 2 + maxItems: 2 + reg-names: + minItems: 2 + maxItems: 2 + required: + - reg-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + spi@ff801000 { + compatible = "brcm,bcm6756-hsspi", "brcm,bcmbca-hsspi-v1.1"; + reg = <0xff801000 0x1000>, + <0xff802610 0x4>; + reg-names = "hsspi", "spim-ctrl"; + interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&hsspi>, <&hsspi_pll>; + clock-names = "hsspi", "pll"; + num-cs = <8>; + #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 ec5873919170..28222aae3077 100644 --- a/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.yaml +++ b/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.yaml @@ -99,98 +99,98 @@ required: examples: - | # BRCMSTB SoC: SPI Master (MSPI+BSPI) for SPI-NOR access spi@f03e3400 { - compatible = "brcm,spi-brcmstb-qspi", "brcm,spi-bcm-qspi"; - reg = <0xf03e3400 0x188>, <0xf03e3200 0x50>, <0xf03e0920 0x4>; - reg-names = "mspi", "bspi", "cs_reg"; - interrupts = <0x5>, <0x6>, <0x1>, <0x2>, <0x3>, <0x4>, <0x0>; - interrupt-parent = <&gic>; - interrupt-names = "mspi_done", - "mspi_halted", - "spi_lr_fullness_reached", - "spi_lr_session_aborted", - "spi_lr_impatient", - "spi_lr_session_done", - "spi_lr_overread"; - clocks = <&hif_spi>; - #address-cells = <0x1>; - #size-cells = <0x0>; - - flash@0 { - #size-cells = <0x2>; - #address-cells = <0x2>; - compatible = "m25p80"; - reg = <0x0>; - spi-max-frequency = <0x2625a00>; - spi-cpol; - spi-cpha; - }; + compatible = "brcm,spi-brcmstb-qspi", "brcm,spi-bcm-qspi"; + reg = <0xf03e3400 0x188>, <0xf03e3200 0x50>, <0xf03e0920 0x4>; + reg-names = "mspi", "bspi", "cs_reg"; + interrupts = <0x5>, <0x6>, <0x1>, <0x2>, <0x3>, <0x4>, <0x0>; + interrupt-parent = <&gic>; + interrupt-names = "mspi_done", + "mspi_halted", + "spi_lr_fullness_reached", + "spi_lr_session_aborted", + "spi_lr_impatient", + "spi_lr_session_done", + "spi_lr_overread"; + clocks = <&hif_spi>; + #address-cells = <0x1>; + #size-cells = <0x0>; + + flash@0 { + #size-cells = <0x2>; + #address-cells = <0x2>; + compatible = "m25p80"; + reg = <0x0>; + spi-max-frequency = <0x2625a00>; + spi-cpol; + spi-cpha; + }; }; - | # BRCMSTB SoC: MSPI master for any SPI device spi@f0416000 { - clocks = <&upg_fixed>; - compatible = "brcm,spi-brcmstb-mspi", "brcm,spi-bcm-qspi"; - reg = <0xf0416000 0x180>; - reg-names = "mspi"; - interrupts = <0x14>; - interrupt-parent = <&irq0_aon_intc>; - interrupt-names = "mspi_done"; - #address-cells = <1>; - #size-cells = <0>; + clocks = <&upg_fixed>; + compatible = "brcm,spi-brcmstb-mspi", "brcm,spi-bcm-qspi"; + reg = <0xf0416000 0x180>; + reg-names = "mspi"; + interrupts = <0x14>; + interrupt-parent = <&irq0_aon_intc>; + interrupt-names = "mspi_done"; + #address-cells = <1>; + #size-cells = <0>; }; - | # iProc SoC #include <dt-bindings/interrupt-controller/irq.h> #include <dt-bindings/interrupt-controller/arm-gic.h> spi@18027200 { - compatible = "brcm,spi-nsp-qspi", "brcm,spi-bcm-qspi"; - reg = <0x18027200 0x184>, - <0x18027000 0x124>, - <0x1811c408 0x004>, - <0x180273a0 0x01c>; - reg-names = "mspi", "bspi", "intr_regs", "intr_status_reg"; - interrupts = <GIC_SPI 77 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 78 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 72 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 73 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 74 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 75 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 76 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "mspi_done", - "mspi_halted", - "spi_lr_fullness_reached", - "spi_lr_session_aborted", - "spi_lr_impatient", - "spi_lr_session_done"; - clocks = <&iprocmed>; - num-cs = <2>; - #address-cells = <1>; - #size-cells = <0>; + compatible = "brcm,spi-nsp-qspi", "brcm,spi-bcm-qspi"; + reg = <0x18027200 0x184>, + <0x18027000 0x124>, + <0x1811c408 0x004>, + <0x180273a0 0x01c>; + reg-names = "mspi", "bspi", "intr_regs", "intr_status_reg"; + interrupts = <GIC_SPI 77 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 78 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 72 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 73 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 74 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 75 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 76 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "mspi_done", + "mspi_halted", + "spi_lr_fullness_reached", + "spi_lr_session_aborted", + "spi_lr_impatient", + "spi_lr_session_done"; + clocks = <&iprocmed>; + num-cs = <2>; + #address-cells = <1>; + #size-cells = <0>; }; - | # NS2 SoC #include <dt-bindings/interrupt-controller/irq.h> #include <dt-bindings/interrupt-controller/arm-gic.h> spi@66470200 { - compatible = "brcm,spi-ns2-qspi", "brcm,spi-bcm-qspi"; - reg = <0x66470200 0x184>, - <0x66470000 0x124>, - <0x67017408 0x004>, - <0x664703a0 0x01c>; - reg-names = "mspi", "bspi", "intr_regs", "intr_status_reg"; - interrupts = <GIC_SPI 419 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "spi_l1_intr"; - clocks = <&iprocmed>; - num-cs = <2>; + compatible = "brcm,spi-ns2-qspi", "brcm,spi-bcm-qspi"; + reg = <0x66470200 0x184>, + <0x66470000 0x124>, + <0x67017408 0x004>, + <0x664703a0 0x01c>; + reg-names = "mspi", "bspi", "intr_regs", "intr_status_reg"; + interrupts = <GIC_SPI 419 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "spi_l1_intr"; + clocks = <&iprocmed>; + num-cs = <2>; + #address-cells = <1>; + #size-cells = <0>; + + flash@0 { #address-cells = <1>; - #size-cells = <0>; - - flash@0 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "m25p80"; - reg = <0x0>; - spi-max-frequency = <12500000>; - spi-cpol; - spi-cpha; - }; + #size-cells = <1>; + compatible = "m25p80"; + reg = <0x0>; + spi-max-frequency = <12500000>; + spi-cpol; + spi-cpha; + }; }; diff --git a/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml b/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml index 4707294d8f59..5c01db128be0 100644 --- a/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml +++ b/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml @@ -47,7 +47,7 @@ properties: cdns,fifo-depth: description: Size of the data FIFO in words. - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 enum: [ 128, 256 ] default: 128 @@ -103,21 +103,21 @@ unevaluatedProperties: false examples: - | qspi: spi@ff705000 { - compatible = "cdns,qspi-nor"; - #address-cells = <1>; - #size-cells = <0>; - reg = <0xff705000 0x1000>, - <0xffa00000 0x1000>; - interrupts = <0 151 4>; - clocks = <&qspi_clk>; - cdns,fifo-depth = <128>; - cdns,fifo-width = <4>; - cdns,trigger-address = <0x00000000>; - resets = <&rst 0x1>, <&rst 0x2>; - reset-names = "qspi", "qspi-ocp"; - - flash@0 { - compatible = "jedec,spi-nor"; - reg = <0x0>; - }; + compatible = "cdns,qspi-nor"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xff705000 0x1000>, + <0xffa00000 0x1000>; + interrupts = <0 151 4>; + clocks = <&qspi_clk>; + cdns,fifo-depth = <128>; + cdns,fifo-width = <4>; + cdns,trigger-address = <0x00000000>; + resets = <&rst 0x1>, <&rst 0x2>; + reset-names = "qspi", "qspi-ocp"; + + flash@0 { + compatible = "jedec,spi-nor"; + reg = <0x0>; + }; }; diff --git a/Documentation/devicetree/bindings/spi/cdns,xspi.yaml b/Documentation/devicetree/bindings/spi/cdns,xspi.yaml index b8bb8a3dbf54..eb0f92468185 100644 --- a/Documentation/devicetree/bindings/spi/cdns,xspi.yaml +++ b/Documentation/devicetree/bindings/spi/cdns,xspi.yaml @@ -2,8 +2,8 @@ # Copyright 2020-21 Cadence %YAML 1.2 --- -$id: "http://devicetree.org/schemas/spi/cdns,xspi.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/spi/cdns,xspi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Cadence XSPI Controller @@ -16,7 +16,7 @@ description: | read/write access to slaves such as SPI-NOR flash. allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/spi/fsl,spi-fsl-qspi.yaml b/Documentation/devicetree/bindings/spi/fsl,spi-fsl-qspi.yaml index e58644558412..f2dd20370dbb 100644 --- a/Documentation/devicetree/bindings/spi/fsl,spi-fsl-qspi.yaml +++ b/Documentation/devicetree/bindings/spi/fsl,spi-fsl-qspi.yaml @@ -10,7 +10,7 @@ maintainers: - Han Xu <han.xu@nxp.com> allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml index 12cb76711000..2f593c7225e5 100644 --- a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml +++ b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml @@ -10,7 +10,7 @@ maintainers: - Shawn Guo <shawnguo@kernel.org> allOf: - - $ref: "/schemas/spi/spi-controller.yaml#" + - $ref: /schemas/spi/spi-controller.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/spi/mediatek,spi-mt65xx.yaml b/Documentation/devicetree/bindings/spi/mediatek,spi-mt65xx.yaml index 8d2a6c084eab..b6249880c3f9 100644 --- a/Documentation/devicetree/bindings/spi/mediatek,spi-mt65xx.yaml +++ b/Documentation/devicetree/bindings/spi/mediatek,spi-mt65xx.yaml @@ -10,7 +10,7 @@ maintainers: - Leilk Liu <leilk.liu@mediatek.com> allOf: - - $ref: "/schemas/spi/spi-controller.yaml#" + - $ref: /schemas/spi/spi-controller.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-snfi.yaml b/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-snfi.yaml index 6e6e02c91780..1e5e89a693c3 100644 --- a/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-snfi.yaml +++ b/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-snfi.yaml @@ -18,14 +18,12 @@ description: | using the accompanying ECC engine. There should be only one spi slave device following generic spi bindings. -allOf: - - $ref: /schemas/spi/spi-controller.yaml# - properties: compatible: enum: - mediatek,mt7622-snand - mediatek,mt7629-snand + - mediatek,mt7986-snand reg: items: @@ -36,19 +34,20 @@ properties: - description: NFI interrupt clocks: - items: - - description: clock used for the controller - - description: clock used for the SPI bus + minItems: 2 + maxItems: 3 clock-names: - items: - - const: nfi_clk - - const: pad_clk + minItems: 2 + maxItems: 3 nand-ecc-engine: description: device-tree node of the accompanying ECC engine. $ref: /schemas/types.yaml#/definitions/phandle + mediatek,rx-latch-latency-ns: + description: Data read latch latency, unit is nanoseconds. + required: - compatible - reg @@ -57,6 +56,43 @@ required: - clock-names - nand-ecc-engine +allOf: + - $ref: /schemas/spi/spi-controller.yaml# + - if: + properties: + compatible: + enum: + - mediatek,mt7622-snand + - mediatek,mt7629-snand + then: + properties: + clocks: + items: + - description: clock used for the controller + - description: clock used for the SPI bus + clock-names: + items: + - const: nfi_clk + - const: pad_clk + + - if: + properties: + compatible: + enum: + - mediatek,mt7986-snand + then: + properties: + clocks: + items: + - description: clock used for the controller + - description: clock used for the SPI bus + - description: clock used for the AHB bus + clock-names: + items: + - const: nfi_clk + - const: pad_clk + - const: nfi_hclk + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/spi/mediatek,spi-slave-mt27xx.yaml b/Documentation/devicetree/bindings/spi/mediatek,spi-slave-mt27xx.yaml index 7977799a8ee1..d19c9f73978f 100644 --- a/Documentation/devicetree/bindings/spi/mediatek,spi-slave-mt27xx.yaml +++ b/Documentation/devicetree/bindings/spi/mediatek,spi-slave-mt27xx.yaml @@ -10,7 +10,7 @@ maintainers: - Leilk Liu <leilk.liu@mediatek.com> allOf: - - $ref: "/schemas/spi/spi-controller.yaml#" + - $ref: /schemas/spi/spi-controller.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/spi/mikrotik,rb4xx-spi.yaml b/Documentation/devicetree/bindings/spi/mikrotik,rb4xx-spi.yaml index 3fd0a8adfe9a..303f6dca89c0 100644 --- a/Documentation/devicetree/bindings/spi/mikrotik,rb4xx-spi.yaml +++ b/Documentation/devicetree/bindings/spi/mikrotik,rb4xx-spi.yaml @@ -11,7 +11,7 @@ maintainers: - Bert Vermeulen <bert@biot.com> allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/spi/mxicy,mx25f0a-spi.yaml b/Documentation/devicetree/bindings/spi/mxicy,mx25f0a-spi.yaml index a3aa5e07c0e4..221fe6e2ef53 100644 --- a/Documentation/devicetree/bindings/spi/mxicy,mx25f0a-spi.yaml +++ b/Documentation/devicetree/bindings/spi/mxicy,mx25f0a-spi.yaml @@ -10,7 +10,7 @@ maintainers: - Miquel Raynal <miquel.raynal@bootlin.com> allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/spi/mxs-spi.yaml b/Documentation/devicetree/bindings/spi/mxs-spi.yaml index 51f8c664323e..e2512166c1cd 100644 --- a/Documentation/devicetree/bindings/spi/mxs-spi.yaml +++ b/Documentation/devicetree/bindings/spi/mxs-spi.yaml @@ -10,7 +10,7 @@ maintainers: - Marek Vasut <marex@denx.de> allOf: - - $ref: "/schemas/spi/spi-controller.yaml#" + - $ref: /schemas/spi/spi-controller.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml b/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml index 899100e783c9..9ae1611175f2 100644 --- a/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml +++ b/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml @@ -11,7 +11,7 @@ maintainers: - Jonathan Hunter <jonathanh@nvidia.com> allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# properties: compatible: @@ -74,25 +74,25 @@ examples: #include <dt-bindings/reset/tegra210-car.h> #include <dt-bindings/interrupt-controller/arm-gic.h> spi@70410000 { - compatible = "nvidia,tegra210-qspi"; - reg = <0x70410000 0x1000>; - interrupts = <GIC_SPI 10 IRQ_TYPE_LEVEL_HIGH>; - #address-cells = <1>; - #size-cells = <0>; - clocks = <&tegra_car TEGRA210_CLK_QSPI>, - <&tegra_car TEGRA210_CLK_QSPI_PM>; - clock-names = "qspi", "qspi_out"; - resets = <&tegra_car 211>; - dmas = <&apbdma 5>, <&apbdma 5>; - dma-names = "rx", "tx"; - - flash@0 { - compatible = "jedec,spi-nor"; - reg = <0>; - spi-max-frequency = <104000000>; - spi-tx-bus-width = <2>; - spi-rx-bus-width = <2>; - nvidia,tx-clk-tap-delay = <0>; - nvidia,rx-clk-tap-delay = <0>; - }; + compatible = "nvidia,tegra210-qspi"; + reg = <0x70410000 0x1000>; + interrupts = <GIC_SPI 10 IRQ_TYPE_LEVEL_HIGH>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&tegra_car TEGRA210_CLK_QSPI>, + <&tegra_car TEGRA210_CLK_QSPI_PM>; + clock-names = "qspi", "qspi_out"; + resets = <&tegra_car 211>; + dmas = <&apbdma 5>, <&apbdma 5>; + dma-names = "rx", "tx"; + + flash@0 { + compatible = "jedec,spi-nor"; + reg = <0>; + spi-max-frequency = <104000000>; + spi-tx-bus-width = <2>; + spi-rx-bus-width = <2>; + nvidia,tx-clk-tap-delay = <0>; + nvidia,rx-clk-tap-delay = <0>; + }; }; diff --git a/Documentation/devicetree/bindings/spi/qcom,spi-qcom-qspi.yaml b/Documentation/devicetree/bindings/spi/qcom,spi-qcom-qspi.yaml index b622bb7363ec..ee8f7ea907b0 100644 --- a/Documentation/devicetree/bindings/spi/qcom,spi-qcom-qspi.yaml +++ b/Documentation/devicetree/bindings/spi/qcom,spi-qcom-qspi.yaml @@ -1,9 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) - %YAML 1.2 --- -$id: "http://devicetree.org/schemas/spi/qcom,spi-qcom-qspi.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/spi/qcom,spi-qcom-qspi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Quad Serial Peripheral Interface (QSPI) @@ -53,6 +52,11 @@ properties: - const: qspi-config - const: qspi-memory + operating-points-v2: true + + power-domains: + maxItems: 1 + required: - compatible - reg @@ -88,7 +92,6 @@ examples: spi-tx-bus-width = <2>; spi-rx-bus-width = <2>; }; - }; }; ... diff --git a/Documentation/devicetree/bindings/spi/realtek,rtl-spi.yaml b/Documentation/devicetree/bindings/spi/realtek,rtl-spi.yaml index 2f938c293f70..70330d945a70 100644 --- a/Documentation/devicetree/bindings/spi/realtek,rtl-spi.yaml +++ b/Documentation/devicetree/bindings/spi/realtek,rtl-spi.yaml @@ -11,7 +11,7 @@ maintainers: - Birger Koblitz <mail@birger-koblitz.de> allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/spi/renesas,rspi.yaml b/Documentation/devicetree/bindings/spi/renesas,rspi.yaml index f45d3b75d6de..4d8ec69214c9 100644 --- a/Documentation/devicetree/bindings/spi/renesas,rspi.yaml +++ b/Documentation/devicetree/bindings/spi/renesas,rspi.yaml @@ -141,15 +141,15 @@ examples: #include <dt-bindings/power/r8a7791-sysc.h> qspi: spi@e6b10000 { - compatible = "renesas,qspi-r8a7791", "renesas,qspi"; - reg = <0xe6b10000 0x2c>; - interrupts = <GIC_SPI 184 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 917>; - dmas = <&dmac0 0x17>, <&dmac0 0x18>, <&dmac1 0x17>, <&dmac1 0x18>; - dma-names = "tx", "rx", "tx", "rx"; - power-domains = <&sysc R8A7791_PD_ALWAYS_ON>; - resets = <&cpg 917>; - num-cs = <1>; - #address-cells = <1>; - #size-cells = <0>; + compatible = "renesas,qspi-r8a7791", "renesas,qspi"; + reg = <0xe6b10000 0x2c>; + interrupts = <GIC_SPI 184 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 917>; + dmas = <&dmac0 0x17>, <&dmac0 0x18>, <&dmac1 0x17>, <&dmac1 0x18>; + dma-names = "tx", "rx", "tx", "rx"; + power-domains = <&sysc R8A7791_PD_ALWAYS_ON>; + resets = <&cpg 917>; + num-cs = <1>; + #address-cells = <1>; + #size-cells = <0>; }; diff --git a/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml b/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml index d33b72fabc5d..a132b5fc56e0 100644 --- a/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml +++ b/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml @@ -10,7 +10,7 @@ maintainers: - Mark Brown <broonie@kernel.org> allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# - if: properties: compatible: diff --git a/Documentation/devicetree/bindings/spi/spi-bcm63xx-hsspi.txt b/Documentation/devicetree/bindings/spi/spi-bcm63xx-hsspi.txt deleted file mode 100644 index 37b29ee13860..000000000000 --- a/Documentation/devicetree/bindings/spi/spi-bcm63xx-hsspi.txt +++ /dev/null @@ -1,33 +0,0 @@ -Binding for Broadcom BCM6328 High Speed SPI controller - -Required properties: -- compatible: must contain of "brcm,bcm6328-hsspi". -- reg: Base address and size of the controllers memory area. -- interrupts: Interrupt for the SPI block. -- clocks: phandles of the SPI clock and the PLL clock. -- clock-names: must be "hsspi", "pll". -- #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@10001000 { - compatible = "brcm,bcm6328-hsspi"; - reg = <0x10001000 0x600>; - - interrupts = <29>; - - clocks = <&clkctl 9>, <&hsspi_pll>; - clock-names = "hsspi", "pll"; - - num-cs = <2>; - - #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 64bf4e621142..b0f83b5c2cdd 100644 --- a/Documentation/devicetree/bindings/spi/spi-cadence.yaml +++ b/Documentation/devicetree/bindings/spi/spi-cadence.yaml @@ -10,7 +10,7 @@ maintainers: - Michal Simek <michal.simek@xilinx.com> allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml index 94caa2b7e241..e91425012319 100644 --- a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml +++ b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml @@ -10,7 +10,7 @@ maintainers: - Anson Huang <Anson.Huang@nxp.com> allOf: - - $ref: "/schemas/spi/spi-controller.yaml#" + - $ref: /schemas/spi/spi-controller.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/spi/spi-gpio.yaml b/Documentation/devicetree/bindings/spi/spi-gpio.yaml index f29b89076c99..9ce1df93d4c3 100644 --- a/Documentation/devicetree/bindings/spi/spi-gpio.yaml +++ b/Documentation/devicetree/bindings/spi/spi-gpio.yaml @@ -14,7 +14,7 @@ description: dedicated GPIO lines. allOf: - - $ref: "/schemas/spi/spi-controller.yaml#" + - $ref: /schemas/spi/spi-controller.yaml# properties: compatible: @@ -41,7 +41,7 @@ properties: num-chipselects: description: Number of chipselect lines. Should be <0> if a single device with no chip select is connected. - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 # Deprecated properties gpio-sck: false diff --git a/Documentation/devicetree/bindings/spi/spi-mux.yaml b/Documentation/devicetree/bindings/spi/spi-mux.yaml index 7ea79f6d33f3..fb2a6039928c 100644 --- a/Documentation/devicetree/bindings/spi/spi-mux.yaml +++ b/Documentation/devicetree/bindings/spi/spi-mux.yaml @@ -30,8 +30,8 @@ description: | +------------+ allOf: - - $ref: "/schemas/spi/spi-controller.yaml#" - - $ref: "/schemas/spi/spi-peripheral-props.yaml#" + - $ref: /schemas/spi/spi-controller.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# maintainers: - Chris Packham <chris.packham@alliedtelesis.co.nz> diff --git a/Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml b/Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml index 1b552c298277..a813c971ecf6 100644 --- a/Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml +++ b/Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml @@ -11,7 +11,7 @@ maintainers: - Kuldeep Singh <singh.kuldeep87k@gmail.com> allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml index ead2cccf658f..782a014b63a7 100644 --- a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml +++ b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml @@ -44,11 +44,21 @@ properties: description: Maximum SPI clocking speed of the device in Hz. - spi-cs-setup-ns: + spi-cs-setup-delay-ns: description: - Delay in nanosecods to be introduced by the controller after CS is + Delay in nanoseconds to be introduced by the controller after CS is asserted. + spi-cs-hold-delay-ns: + description: + Delay in nanoseconds to be introduced by the controller before CS is + de-asserted. + + spi-cs-inactive-delay-ns: + description: + Delay in nanoseconds to be introduced by the controller after CS is + de-asserted. + spi-rx-bus-width: description: Bus width to the SPI bus used for read transfers. diff --git a/Documentation/devicetree/bindings/spi/spi-pl022.yaml b/Documentation/devicetree/bindings/spi/spi-pl022.yaml index 0e382119c64f..91e540a92faf 100644 --- a/Documentation/devicetree/bindings/spi/spi-pl022.yaml +++ b/Documentation/devicetree/bindings/spi/spi-pl022.yaml @@ -10,7 +10,7 @@ maintainers: - Linus Walleij <linus.walleij@linaro.org> allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# # We need a select here so we don't match all nodes with 'arm,primecell' select: @@ -45,7 +45,7 @@ properties: description: delay in ms following transfer completion before the runtime power management system suspends the device. A setting of 0 indicates no delay and the device will be suspended immediately. - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 pl022,rt: description: indicates the controller should run the message pump with realtime @@ -81,7 +81,7 @@ patternProperties: properties: pl022,interface: description: SPI interface type - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 enum: - 0 # SPI - 1 # Texas Instruments Synchronous Serial Frame Format @@ -89,7 +89,7 @@ patternProperties: pl022,com-mode: description: Specifies the transfer mode - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 enum: - 0 # interrupt mode - 1 # polling mode @@ -98,30 +98,30 @@ patternProperties: pl022,rx-level-trig: description: Rx FIFO watermark level - $ref: "/schemas/types.yaml#/definitions/uint32" + $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" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 4 pl022,ctrl-len: description: Microwire interface - Control length - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0x03 maximum: 0x1f pl022,wait-state: description: Microwire interface - Wait state - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 enum: [0, 1] pl022,duplex: description: Microwire interface - Full/Half duplex - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 enum: [0, 1] required: diff --git a/Documentation/devicetree/bindings/spi/spi-rockchip.yaml b/Documentation/devicetree/bindings/spi/spi-rockchip.yaml index 66e49947b703..e4941e9212d1 100644 --- a/Documentation/devicetree/bindings/spi/spi-rockchip.yaml +++ b/Documentation/devicetree/bindings/spi/spi-rockchip.yaml @@ -11,7 +11,7 @@ description: as flash and display controllers using the SPI communication interface. allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# maintainers: - Heiko Stuebner <heiko@sntech.de> diff --git a/Documentation/devicetree/bindings/spi/spi-sifive.yaml b/Documentation/devicetree/bindings/spi/spi-sifive.yaml index 6e7e394fc1e4..5bffefb9c7eb 100644 --- a/Documentation/devicetree/bindings/spi/spi-sifive.yaml +++ b/Documentation/devicetree/bindings/spi/spi-sifive.yaml @@ -12,7 +12,7 @@ maintainers: - Palmer Dabbelt <palmer@sifive.com> allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# properties: compatible: @@ -51,14 +51,14 @@ properties: sifive,fifo-depth: description: Depth of hardware queues; defaults to 8 - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 enum: [8] default: 8 sifive,max-bits-per-word: description: Maximum bits per word; defaults to 8 - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 enum: [0, 1, 2, 3, 4, 5, 6, 7, 8] default: 8 diff --git a/Documentation/devicetree/bindings/spi/spi-st-ssc.txt b/Documentation/devicetree/bindings/spi/spi-st-ssc.txt deleted file mode 100644 index 1bdc4709e474..000000000000 --- a/Documentation/devicetree/bindings/spi/spi-st-ssc.txt +++ /dev/null @@ -1,40 +0,0 @@ -STMicroelectronics SSC (SPI) Controller ---------------------------------------- - -Required properties: -- compatible : "st,comms-ssc4-spi" -- reg : Offset and length of the device's register set -- interrupts : The interrupt specifier -- clock-names : Must contain "ssc" -- clocks : Must contain an entry for each name in clock-names - See ../clk/* -- pinctrl-names : Uses "default", can use "sleep" if provided - See ../pinctrl/pinctrl-bindings.txt - -Optional properties: -- cs-gpios : List of GPIO chip selects - See ../spi/spi-bus.txt - -Child nodes represent devices on the SPI bus - See ../spi/spi-bus.txt - -Example: - spi@9840000 { - compatible = "st,comms-ssc4-spi"; - reg = <0x9840000 0x110>; - interrupts = <GIC_SPI 112 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clk_s_c0_flexgen CLK_EXT2F_A9>; - clock-names = "ssc"; - pinctrl-0 = <&pinctrl_spi0_default>; - pinctrl-names = "default"; - cs-gpios = <&pio17 5 0>; - #address-cells = <1>; - #size-cells = <0>; - - st95hf@0{ - compatible = "st,st95hf"; - reg = <0>; - spi-max-frequency = <1000000>; - interrupts = <2 IRQ_TYPE_EDGE_FALLING>; - }; - }; diff --git a/Documentation/devicetree/bindings/spi/spi-sunplus-sp7021.yaml b/Documentation/devicetree/bindings/spi/spi-sunplus-sp7021.yaml index 3a58cf0f1ec8..edb5ba71af3a 100644 --- a/Documentation/devicetree/bindings/spi/spi-sunplus-sp7021.yaml +++ b/Documentation/devicetree/bindings/spi/spi-sunplus-sp7021.yaml @@ -8,7 +8,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Sunplus sp7021 SPI controller allOf: - - $ref: "spi-controller.yaml" + - $ref: spi-controller.yaml maintainers: - Li-hao Kuo <lhjeff911@gmail.com> @@ -59,9 +59,9 @@ unevaluatedProperties: false examples: - | #include <dt-bindings/interrupt-controller/irq.h> - spi@9C002D80 { + spi@9c002d80 { compatible = "sunplus,sp7021-spi"; - reg = <0x9C002D80 0x80>, <0x9C002E00 0x80>; + reg = <0x9c002d80 0x80>, <0x9c002e00 0x80>; reg-names = "master", "slave"; interrupt-parent = <&intc>; interrupt-names = "dma_w", diff --git a/Documentation/devicetree/bindings/spi/spi-xilinx.yaml b/Documentation/devicetree/bindings/spi/spi-xilinx.yaml index bbb735603f29..6bd83836eded 100644 --- a/Documentation/devicetree/bindings/spi/spi-xilinx.yaml +++ b/Documentation/devicetree/bindings/spi/spi-xilinx.yaml @@ -10,7 +10,7 @@ maintainers: - Michal Simek <michal.simek@xilinx.com> allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml b/Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml index 546c416cdb55..20f77246d365 100644 --- a/Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml +++ b/Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml @@ -10,7 +10,7 @@ maintainers: - Michal Simek <michal.simek@xilinx.com> allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/spi/sprd,spi-adi.yaml b/Documentation/devicetree/bindings/spi/sprd,spi-adi.yaml index a3ab1a1f1eb4..903b06f88b1b 100644 --- a/Documentation/devicetree/bindings/spi/sprd,spi-adi.yaml +++ b/Documentation/devicetree/bindings/spi/sprd,spi-adi.yaml @@ -1,9 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) - %YAML 1.2 --- -$id: "http://devicetree.org/schemas/spi/sprd,spi-adi.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/spi/sprd,spi-adi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Spreadtrum ADI controller diff --git a/Documentation/devicetree/bindings/spi/st,ssc-spi.yaml b/Documentation/devicetree/bindings/spi/st,ssc-spi.yaml new file mode 100644 index 000000000000..6a77cd3f5d6e --- /dev/null +++ b/Documentation/devicetree/bindings/spi/st,ssc-spi.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/st,ssc-spi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics SSC SPI Controller + +description: | + The STMicroelectronics SSC SPI controller can be found on STi platforms + and it used to communicate with external devices using the + Serial Peripheral Interface. + +maintainers: + - Patrice Chotard <patrice.chotard@foss.st.com> + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + const: st,comms-ssc4-spi + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + const: ssc + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/stih407-clks.h> + spi@9840000 { + compatible = "st,comms-ssc4-spi"; + reg = <0x9840000 0x110>; + interrupts = <GIC_SPI 112 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk_s_c0_flexgen CLK_EXT2F_A9>; + clock-names = "ssc"; + pinctrl-0 = <&pinctrl_spi0_default>; + pinctrl-names = "default"; + #address-cells = <1>; + #size-cells = <0>; + }; + +... diff --git a/Documentation/devicetree/bindings/spi/st,stm32-qspi.yaml b/Documentation/devicetree/bindings/spi/st,stm32-qspi.yaml index 1eb17f7a4d86..8bba965a9ae6 100644 --- a/Documentation/devicetree/bindings/spi/st,stm32-qspi.yaml +++ b/Documentation/devicetree/bindings/spi/st,stm32-qspi.yaml @@ -11,7 +11,7 @@ maintainers: - Patrice Chotard <patrice.chotard@foss.st.com> allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml b/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml index 1cda15f91cc3..9ca1a843c820 100644 --- a/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml +++ b/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml @@ -17,7 +17,7 @@ maintainers: - Fabrice Gasnier <fabrice.gasnier@foss.st.com> allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# - if: properties: compatible: @@ -84,18 +84,17 @@ examples: #include <dt-bindings/clock/stm32mp1-clks.h> #include <dt-bindings/reset/stm32mp1-resets.h> spi@4000b000 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "st,stm32h7-spi"; - reg = <0x4000b000 0x400>; - interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&rcc SPI2_K>; - resets = <&rcc SPI2_R>; - dmas = <&dmamux1 0 39 0x400 0x05>, - <&dmamux1 1 40 0x400 0x05>; - dma-names = "rx", "tx"; - cs-gpios = <&gpioa 11 0>; - + #address-cells = <1>; + #size-cells = <0>; + compatible = "st,stm32h7-spi"; + reg = <0x4000b000 0x400>; + interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&rcc SPI2_K>; + resets = <&rcc SPI2_R>; + dmas = <&dmamux1 0 39 0x400 0x05>, + <&dmamux1 1 40 0x400 0x05>; + dma-names = "rx", "tx"; + cs-gpios = <&gpioa 11 0>; }; ... diff --git a/Documentation/devicetree/bindings/spi/xlnx,zynq-qspi.yaml b/Documentation/devicetree/bindings/spi/xlnx,zynq-qspi.yaml index 1f1c40a9f320..83e8fb4a548d 100644 --- a/Documentation/devicetree/bindings/spi/xlnx,zynq-qspi.yaml +++ b/Documentation/devicetree/bindings/spi/xlnx,zynq-qspi.yaml @@ -11,7 +11,7 @@ description: memory devices. allOf: - - $ref: "spi-controller.yaml#" + - $ref: spi-controller.yaml# maintainers: - Michal Simek <michal.simek@xilinx.com> diff --git a/Documentation/devicetree/bindings/sram/qcom,imem.yaml b/Documentation/devicetree/bindings/sram/qcom,imem.yaml index 665c06e14f79..ba694ce4a037 100644 --- a/Documentation/devicetree/bindings/sram/qcom,imem.yaml +++ b/Documentation/devicetree/bindings/sram/qcom,imem.yaml @@ -26,6 +26,7 @@ properties: - qcom,sdm845-imem - qcom,sdx55-imem - qcom,sdx65-imem + - qcom,sm8450-imem - const: syscon - const: simple-mfd diff --git a/Documentation/devicetree/bindings/thermal/mediatek,lvts-thermal.yaml b/Documentation/devicetree/bindings/thermal/mediatek,lvts-thermal.yaml new file mode 100644 index 000000000000..fe9ae4c425c0 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/mediatek,lvts-thermal.yaml @@ -0,0 +1,142 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/mediatek,lvts-thermal.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek SoC Low Voltage Thermal Sensor (LVTS) + +maintainers: + - Balsam CHIHI <bchihi@baylibre.com> + +description: | + LVTS is a thermal management architecture composed of three subsystems, + a Sensing device - Thermal Sensing Micro Circuit Unit (TSMCU), + a Converter - Low Voltage Thermal Sensor converter (LVTS), and + a Digital controller (LVTS_CTRL). + +properties: + compatible: + enum: + - mediatek,mt8192-lvts-ap + - mediatek,mt8192-lvts-mcu + - mediatek,mt8195-lvts-ap + - mediatek,mt8195-lvts-mcu + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + description: LVTS reset for clearing temporary data on AP/MCU. + + nvmem-cells: + minItems: 1 + items: + - description: Calibration eFuse data 1 for LVTS + - description: Calibration eFuse data 2 for LVTS + + nvmem-cell-names: + minItems: 1 + items: + - const: lvts-calib-data-1 + - const: lvts-calib-data-2 + + "#thermal-sensor-cells": + const: 1 + +allOf: + - $ref: thermal-sensor.yaml# + + - if: + properties: + compatible: + contains: + enum: + - mediatek,mt8192-lvts-ap + - mediatek,mt8192-lvts-mcu + then: + properties: + nvmem-cells: + maxItems: 1 + + nvmem-cell-names: + maxItems: 1 + + - if: + properties: + compatible: + contains: + enum: + - mediatek,mt8195-lvts-ap + - mediatek,mt8195-lvts-mcu + then: + properties: + nvmem-cells: + minItems: 2 + + nvmem-cell-names: + minItems: 2 + +required: + - compatible + - reg + - interrupts + - clocks + - resets + - nvmem-cells + - nvmem-cell-names + - "#thermal-sensor-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/mt8195-clk.h> + #include <dt-bindings/reset/mt8195-resets.h> + #include <dt-bindings/thermal/mediatek,lvts-thermal.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + lvts_mcu: thermal-sensor@11278000 { + compatible = "mediatek,mt8195-lvts-mcu"; + reg = <0 0x11278000 0 0x1000>; + interrupts = <GIC_SPI 170 IRQ_TYPE_LEVEL_HIGH 0>; + clocks = <&infracfg_ao CLK_INFRA_AO_THERM>; + resets = <&infracfg_ao MT8195_INFRA_RST4_THERM_CTRL_MCU_SWRST>; + nvmem-cells = <&lvts_efuse_data1 &lvts_efuse_data2>; + nvmem-cell-names = "lvts-calib-data-1", "lvts-calib-data-2"; + #thermal-sensor-cells = <1>; + }; + }; + + thermal_zones: thermal-zones { + cpu0-thermal { + polling-delay = <1000>; + polling-delay-passive = <250>; + thermal-sensors = <&lvts_mcu MT8195_MCU_LITTLE_CPU0>; + + trips { + cpu0_alert: trip-alert { + temperature = <85000>; + hysteresis = <2000>; + type = "passive"; + }; + + cpu0_crit: trip-crit { + temperature = <100000>; + hysteresis = <2000>; + type = "critical"; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml b/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml index d20569b9b763..52ec18cf1eda 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml @@ -13,6 +13,7 @@ properties: enum: - qcom,spmi-adc-tm5 - qcom,spmi-adc-tm5-gen2 + - qcom,adc-tm7 # Incomplete / subject to change reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml index 0231f187b097..926e9c51c93c 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml @@ -37,6 +37,7 @@ properties: - description: v1 of TSENS items: - enum: + - qcom,msm8956-tsens - qcom,msm8976-tsens - qcom,qcs404-tsens - const: qcom,tsens-v1 @@ -80,18 +81,120 @@ properties: maxItems: 2 nvmem-cells: - minItems: 1 - maxItems: 2 - description: - Reference to an nvmem node for the calibration data + oneOf: + - minItems: 1 + maxItems: 2 + description: + Reference to an nvmem node for the calibration data + - minItems: 5 + maxItems: 35 + description: | + Reference to nvmem cells for the calibration mode, two calibration + bases and two cells per each sensor + # special case for msm8974 / apq8084 + - maxItems: 51 + description: | + Reference to nvmem cells for the calibration mode, two calibration + bases and two cells per each sensor, main and backup copies, plus use_backup cell nvmem-cell-names: - minItems: 1 - items: - - const: calib - - enum: - - calib_backup - - calib_sel + oneOf: + - minItems: 1 + items: + - const: calib + - enum: + - calib_backup + - calib_sel + - minItems: 5 + items: + - const: mode + - const: base1 + - const: base2 + - pattern: '^s[0-9]+_p1$' + - pattern: '^s[0-9]+_p2$' + - pattern: '^s[0-9]+_p1$' + - pattern: '^s[0-9]+_p2$' + - pattern: '^s[0-9]+_p1$' + - pattern: '^s[0-9]+_p2$' + - pattern: '^s[0-9]+_p1$' + - pattern: '^s[0-9]+_p2$' + - pattern: '^s[0-9]+_p1$' + - pattern: '^s[0-9]+_p2$' + - pattern: '^s[0-9]+_p1$' + - pattern: '^s[0-9]+_p2$' + - pattern: '^s[0-9]+_p1$' + - pattern: '^s[0-9]+_p2$' + - pattern: '^s[0-9]+_p1$' + - pattern: '^s[0-9]+_p2$' + - pattern: '^s[0-9]+_p1$' + - pattern: '^s[0-9]+_p2$' + - pattern: '^s[0-9]+_p1$' + - pattern: '^s[0-9]+_p2$' + - pattern: '^s[0-9]+_p1$' + - pattern: '^s[0-9]+_p2$' + - pattern: '^s[0-9]+_p1$' + - pattern: '^s[0-9]+_p2$' + - pattern: '^s[0-9]+_p1$' + - pattern: '^s[0-9]+_p2$' + - pattern: '^s[0-9]+_p1$' + - pattern: '^s[0-9]+_p2$' + - pattern: '^s[0-9]+_p1$' + - pattern: '^s[0-9]+_p2$' + - pattern: '^s[0-9]+_p1$' + - pattern: '^s[0-9]+_p2$' + # special case for msm8974 / apq8084 + - items: + - const: mode + - const: base1 + - const: base2 + - const: use_backup + - const: mode_backup + - const: base1_backup + - const: base2_backup + - const: s0_p1 + - const: s0_p2 + - const: s1_p1 + - const: s1_p2 + - const: s2_p1 + - const: s2_p2 + - const: s3_p1 + - const: s3_p2 + - const: s4_p1 + - const: s4_p2 + - const: s5_p1 + - const: s5_p2 + - const: s6_p1 + - const: s6_p2 + - const: s7_p1 + - const: s7_p2 + - const: s8_p1 + - const: s8_p2 + - const: s9_p1 + - const: s9_p2 + - const: s10_p1 + - const: s10_p2 + - const: s0_p1_backup + - const: s0_p2_backup + - const: s1_p1_backup + - const: s1_p2_backup + - const: s2_p1_backup + - const: s2_p2_backup + - const: s3_p1_backup + - const: s3_p2_backup + - const: s4_p1_backup + - const: s4_p2_backup + - const: s5_p1_backup + - const: s5_p2_backup + - const: s6_p1_backup + - const: s6_p2_backup + - const: s7_p1_backup + - const: s7_p2_backup + - const: s8_p1_backup + - const: s8_p2_backup + - const: s9_p1_backup + - const: s9_p2_backup + - const: s10_p1_backup + - const: s10_p2_backup "#qcom,sensors": description: @@ -222,6 +325,36 @@ examples: - | #include <dt-bindings/interrupt-controller/arm-gic.h> + // Example 1 (new calbiration data: for pre v1 IP): + thermal-sensor@900000 { + compatible = "qcom,msm8916-tsens", "qcom,tsens-v0_1"; + reg = <0x4a9000 0x1000>, /* TM */ + <0x4a8000 0x1000>; /* SROT */ + + nvmem-cells = <&tsens_mode>, + <&tsens_base1>, <&tsens_base2>, + <&tsens_s0_p1>, <&tsens_s0_p2>, + <&tsens_s1_p1>, <&tsens_s1_p2>, + <&tsens_s2_p1>, <&tsens_s2_p2>, + <&tsens_s4_p1>, <&tsens_s4_p2>, + <&tsens_s5_p1>, <&tsens_s5_p2>; + nvmem-cell-names = "mode", + "base1", "base2", + "s0_p1", "s0_p2", + "s1_p1", "s1_p2", + "s2_p1", "s2_p2", + "s4_p1", "s4_p2", + "s5_p1", "s5_p2"; + + interrupts = <GIC_SPI 184 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "uplow"; + + #qcom,sensors = <5>; + #thermal-sensor-cells = <1>; + }; + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> // Example 1 (legacy: for pre v1 IP): tsens1: thermal-sensor@900000 { compatible = "qcom,msm8916-tsens", "qcom,tsens-v0_1"; diff --git a/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml b/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml index 0f05f5c886c5..ecf276fd155c 100644 --- a/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml @@ -28,6 +28,7 @@ properties: - renesas,r8a77980-thermal # R-Car V3H - renesas,r8a779a0-thermal # R-Car V3U - renesas,r8a779f0-thermal # R-Car S4-8 + - renesas,r8a779g0-thermal # R-Car V4H reg: true @@ -80,6 +81,7 @@ else: - description: TSC1 registers - description: TSC2 registers - description: TSC3 registers + - description: TSC4 registers if: not: properties: @@ -87,6 +89,7 @@ else: contains: enum: - renesas,r8a779f0-thermal + - renesas,r8a779g0-thermal then: required: - interrupts diff --git a/Documentation/devicetree/bindings/thermal/socionext,uniphier-thermal.yaml b/Documentation/devicetree/bindings/thermal/socionext,uniphier-thermal.yaml index c5b25ce44956..6f975821fa5e 100644 --- a/Documentation/devicetree/bindings/thermal/socionext,uniphier-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/socionext,uniphier-thermal.yaml @@ -46,14 +46,9 @@ examples: - | // The UniPhier thermal should be a subnode of a "syscon" compatible node. - sysctrl@61840000 { - compatible = "socionext,uniphier-ld20-sysctrl", - "simple-mfd", "syscon"; - reg = <0x61840000 0x10000>; - - pvtctl: thermal { - compatible = "socionext,uniphier-ld20-thermal"; - interrupts = <0 3 1>; - #thermal-sensor-cells = <0>; - }; + #include <dt-bindings/interrupt-controller/arm-gic.h> + pvtctl: thermal-sensor { + compatible = "socionext,uniphier-ld20-thermal"; + interrupts = <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>; + #thermal-sensor-cells = <0>; }; diff --git a/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt b/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt index 8bbb6e94508b..b3e797e8aa31 100644 --- a/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt +++ b/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt @@ -33,6 +33,7 @@ Required properties: For those SoCs that use CPUX * "mediatek,mt6795-systimer" for MT6795 compatible timers (CPUX) + * "mediatek,mt8365-systimer" for MT8365 compatible timers (CPUX) - reg: Should contain location and length for timer register. - clocks: Should contain system clock. diff --git a/Documentation/devicetree/bindings/timer/riscv,timer.yaml b/Documentation/devicetree/bindings/timer/riscv,timer.yaml new file mode 100644 index 000000000000..38d67e1a5a79 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/riscv,timer.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/riscv,timer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: RISC-V timer + +maintainers: + - Anup Patel <anup@brainfault.org> + +description: |+ + RISC-V platforms always have a RISC-V timer device for the supervisor-mode + based on the time CSR defined by the RISC-V privileged specification. The + timer interrupts of this device are configured using the RISC-V SBI Time + extension or the RISC-V Sstc extension. + + The clock frequency of RISC-V timer device is specified via the + "timebase-frequency" DT property of "/cpus" DT node which is described + in Documentation/devicetree/bindings/riscv/cpus.yaml + +properties: + compatible: + enum: + - riscv,timer + + interrupts-extended: + minItems: 1 + maxItems: 4096 # Should be enough? + + riscv,timer-cannot-wake-cpu: + type: boolean + description: + If present, the timer interrupt cannot wake up the CPU from one or + more suspend/idle states. + +additionalProperties: false + +required: + - compatible + - interrupts-extended + +examples: + - | + timer { + compatible = "riscv,timer"; + interrupts-extended = <&cpu1intc 5>, + <&cpu2intc 5>, + <&cpu3intc 5>, + <&cpu4intc 5>; + }; +... diff --git a/Documentation/devicetree/bindings/timer/rockchip,rk-timer.yaml b/Documentation/devicetree/bindings/timer/rockchip,rk-timer.yaml index b61ed1a431bb..65e59836a660 100644 --- a/Documentation/devicetree/bindings/timer/rockchip,rk-timer.yaml +++ b/Documentation/devicetree/bindings/timer/rockchip,rk-timer.yaml @@ -17,6 +17,7 @@ properties: - items: - enum: - rockchip,rv1108-timer + - rockchip,rv1126-timer - rockchip,rk3036-timer - rockchip,rk3128-timer - rockchip,rk3188-timer diff --git a/Documentation/devicetree/bindings/timer/sifive,clint.yaml b/Documentation/devicetree/bindings/timer/sifive,clint.yaml index bbad24165837..aada6957216c 100644 --- a/Documentation/devicetree/bindings/timer/sifive,clint.yaml +++ b/Documentation/devicetree/bindings/timer/sifive,clint.yaml @@ -20,6 +20,10 @@ description: property of "/cpus" DT node. The "timebase-frequency" DT property is described in Documentation/devicetree/bindings/riscv/cpus.yaml + T-Head C906/C910 CPU cores include an implementation of CLINT too, however + their implementation lacks a memory-mapped MTIME register, thus not + compatible with SiFive ones. + properties: compatible: oneOf: @@ -30,6 +34,10 @@ properties: - canaan,k210-clint - const: sifive,clint0 - items: + - enum: + - allwinner,sun20i-d1-clint + - const: thead,c900-clint + - items: - const: sifive,clint0 - const: riscv,clint0 deprecated: true diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index f5c0a6283e61..6f482a254a1d 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -65,6 +65,8 @@ properties: - capella,cm3232 # CM3323: Ambient Light Sensor - capella,cm3323 + # Cisco SPI Petra + - cisco,spi-petra # High-Precision Digital Thermometer - dallas,ds1631 # Total-Elapsed-Time Recorder with Alarm @@ -141,6 +143,8 @@ 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 @@ -169,6 +173,8 @@ properties: - isil,isl29030 # Intersil ISL68137 Digital Output Configurable PWM Controller - isil,isl68137 + # Linear Technology LTC2488 + - lineartechnology,ltc2488 # 5 Bit Programmable, Pulse-Width Modulator - maxim,ds1050 # 10 kOhm digital potentiometer with I2C interface @@ -227,6 +233,8 @@ properties: - memsic,mxc6655 # Menlo on-board CPLD trivial SPI device - menlo,m53cpld + # Micron SPI NOR Authenta + - micron,spi-authenta # Microchip differential I2C ADC, 1 Channel, 18 bit - microchip,mcp3421 # Microchip differential I2C ADC, 2 Channel, 18 bit @@ -305,10 +313,14 @@ properties: - pulsedlight,lidar-lite-v2 # Renesas ISL29501 time-of-flight sensor - renesas,isl29501 + # Rohm DH2228FV + - rohm,dh2228fv # S524AD0XF1 (128K/256K-bit Serial EEPROM for Low Power) - samsung,24ad0xd1 # Samsung Exynos SoC SATA PHY I2C device - samsung,exynos-sataphy-i2c + # Semtech sx1301 baseband processor + - semtech,sx1301 # Sensirion low power multi-pixel gas sensor with I2C interface - sensirion,sgpc3 # Sensirion multi-pixel gas sensor with I2C interface @@ -323,6 +335,10 @@ properties: - sensortek,stk8ba50 # SGX Sensortech VZ89X Sensors - sgx,vz89x + # Silicon Labs EM3581 Zigbee SoC with SPI interface + - silabs,em3581 + # Silicon Labs SI3210 Programmable CMOS SLIC/CODEC with SPI interface + - silabs,si3210 # Relative Humidity and Temperature Sensors - silabs,si7020 # Skyworks SKY81452: Six-Channel White LED Driver with Touch Panel Bias Supply diff --git a/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml b/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml index f2d6298d926c..c5a06c048389 100644 --- a/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml +++ b/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml @@ -33,6 +33,7 @@ properties: - qcom,sm8250-ufshc - qcom,sm8350-ufshc - qcom,sm8450-ufshc + - qcom,sm8550-ufshc - const: qcom,ufshc - const: jedec,ufs-2.0 @@ -44,6 +45,8 @@ properties: minItems: 8 maxItems: 11 + dma-coherent: true + interconnects: minItems: 2 maxItems: 2 @@ -71,6 +74,9 @@ properties: minItems: 1 maxItems: 2 + required-opps: + maxItems: 1 + resets: maxItems: 1 @@ -103,6 +109,7 @@ allOf: - qcom,sm8250-ufshc - qcom,sm8350-ufshc - qcom,sm8450-ufshc + - qcom,sm8550-ufshc then: properties: clocks: diff --git a/Documentation/devicetree/bindings/ufs/sprd,ums9620-ufs.yaml b/Documentation/devicetree/bindings/ufs/sprd,ums9620-ufs.yaml new file mode 100644 index 000000000000..36a8ae77949f --- /dev/null +++ b/Documentation/devicetree/bindings/ufs/sprd,ums9620-ufs.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/ufs/sprd,ums9620-ufs.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Unisoc Universal Flash Storage (UFS) Controller + +maintainers: + - Zhe Wang <zhe.wang1@unisoc.com> + +allOf: + - $ref: ufs-common.yaml + +properties: + compatible: + const: sprd,ums9620-ufs + + reg: + maxItems: 1 + + clocks: + maxItems: 3 + + clock-names: + items: + - const: controller_eb + - const: cfg_eb + - const: core + + resets: + maxItems: 2 + + reset-names: + items: + - const: controller + - const: device + + vdd-mphy-supply: + description: + Phandle to vdd-mphy supply regulator node. + + sprd,ufs-anlg-syscon: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle of syscon used to control ufs analog regs. + + sprd,aon-apb-syscon: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle of syscon used to control always-on regs. + +required: + - compatible + - reg + - clocks + - clock-names + - resets + - reset-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + ufs: ufs@22000000 { + compatible = "sprd,ums9620-ufs"; + reg = <0x22000000 0x3000>; + interrupts = <GIC_SPI 159 IRQ_TYPE_LEVEL_HIGH>; + vcc-supply = <&vddemmccore>; + vdd-mphy-supply = <&vddufs1v2>; + clocks = <&apahb_gate 5>, <&apahb_gate 22>, <&aonapb_clk 52>; + clock-names = "controller_eb", "cfg_eb", "core"; + assigned-clocks = <&aonapb_clk 52>; + assigned-clock-parents = <&g5l_pll 12>; + resets = <&apahb_gate 4>, <&aonapb_gate 69>; + reset-names = "controller", "device"; + sprd,ufs-anlg-syscon = <&anlg_phy_g12_regs>; + sprd,aon-apb-syscon = <&aon_apb_regs>; + }; diff --git a/Documentation/devicetree/bindings/usb/allwinner,sun4i-a10-musb.yaml b/Documentation/devicetree/bindings/usb/allwinner,sun4i-a10-musb.yaml index 8992eff6ce38..f972ce976e86 100644 --- a/Documentation/devicetree/bindings/usb/allwinner,sun4i-a10-musb.yaml +++ b/Documentation/devicetree/bindings/usb/allwinner,sun4i-a10-musb.yaml @@ -13,10 +13,12 @@ maintainers: properties: compatible: oneOf: - - const: allwinner,sun4i-a10-musb - - const: allwinner,sun6i-a31-musb - - const: allwinner,sun8i-a33-musb - - const: allwinner,sun8i-h3-musb + - enum: + - allwinner,sun4i-a10-musb + - allwinner,sun6i-a31-musb + - allwinner,sun8i-a33-musb + - allwinner,sun8i-h3-musb + - allwinner,suniv-f1c100s-musb - items: - enum: - allwinner,sun8i-a83t-musb diff --git a/Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml b/Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml index daf2a859418d..f38a2be07eda 100644 --- a/Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml +++ b/Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml @@ -108,6 +108,7 @@ allOf: then: properties: phy-names: + minItems: 2 items: - const: usb2-phy0 # USB2 PHY0 if USBHOST_A port is used - const: usb2-phy1 # USB2 PHY1 if USBOTG_B port is used diff --git a/Documentation/devicetree/bindings/usb/brcm,bcm3384-usb.txt b/Documentation/devicetree/bindings/usb/brcm,bcm3384-usb.txt deleted file mode 100644 index 452c45c7bf29..000000000000 --- a/Documentation/devicetree/bindings/usb/brcm,bcm3384-usb.txt +++ /dev/null @@ -1,11 +0,0 @@ -* Broadcom USB controllers - -Required properties: -- compatible: "brcm,bcm3384-ohci", "brcm,bcm3384-ehci" - - These currently use the generic-ohci and generic-ehci drivers. On some - systems, special handling may be needed in the following cases: - - - Restoring state after systemwide power save modes - - Sharing PHYs with the USBD (UDC) hardware - - Figuring out which controllers are disabled on ASIC bondout variants diff --git a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt index ba51fb1252b9..72ceea575d58 100644 --- a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt +++ b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt @@ -11,6 +11,7 @@ Required properties: "fsl,imx6ul-usb" "fsl,imx7d-usb" "fsl,imx7ulp-usb" + "fsl,imx8mm-usb" "lsi,zevio-usb" "qcom,ci-hdrc" "chipidea,usb2" diff --git a/Documentation/devicetree/bindings/usb/cypress,cypd4226.yaml b/Documentation/devicetree/bindings/usb/cypress,cypd4226.yaml new file mode 100644 index 000000000000..75eec4a9a020 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/cypress,cypd4226.yaml @@ -0,0 +1,98 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/cypress,cypd4226.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cypress cypd4226 Type-C Controller + +maintainers: + - Wayne Chang <waynec@nvidia.com> + +description: + The Cypress cypd4226 is a dual Type-C controller that is controlled + via an I2C interface. + +properties: + compatible: + const: cypress,cypd4226 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + reg: + const: 0x08 + + interrupts: + items: + - description: cypd4226 host interrupt + + firmware-name: + enum: + - nvidia,gpu + - nvidia,jetson-agx-xavier + description: | + The name of the CCGx firmware built for product series. + should be set one of following: + - "nvidia,gpu" for the NVIDIA RTX product series + - "nvidia,jetson-agx-xavier" for the NVIDIA Jetson product series + +patternProperties: + '^connector@[01]$': + $ref: /schemas/connector/usb-connector.yaml# + unevaluatedProperties: false + properties: + reg: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +anyOf: + - required: + - connector@0 + - required: + - connector@1 + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/tegra194-gpio.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + #interrupt-cells = <2>; + + typec@8 { + compatible = "cypress,cypd4226"; + reg = <0x08>; + interrupt-parent = <&gpio_aon>; + interrupts = <TEGRA194_AON_GPIO(BB, 2) IRQ_TYPE_LEVEL_LOW>; + firmware-name = "nvidia,jetson-agx-xavier"; + #address-cells = <1>; + #size-cells = <0>; + connector@0 { + compatible = "usb-c-connector"; + reg = <0>; + label = "USB-C"; + data-role = "dual"; + ports { + #address-cells = <1>; + #size-cells = <0>; + port@0 { + reg = <0>; + endpoint { + remote-endpoint = <&usb_role_switch0>; + }; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/ehci-omap.txt b/Documentation/devicetree/bindings/usb/ehci-omap.txt deleted file mode 100644 index d77e11a975a2..000000000000 --- a/Documentation/devicetree/bindings/usb/ehci-omap.txt +++ /dev/null @@ -1,31 +0,0 @@ -OMAP HS USB EHCI controller - -This device is usually the child of the omap-usb-host -Documentation/devicetree/bindings/mfd/omap-usb-host.txt - -Required properties: - -- compatible: should be "ti,ehci-omap" -- reg: should contain one register range i.e. start and length -- interrupts: description of the interrupt line - -Optional properties: - -- phys: list of phandles to PHY nodes. - This property is required if at least one of the ports are in - PHY mode i.e. OMAP_EHCI_PORT_MODE_PHY - -To specify the port mode, see -Documentation/devicetree/bindings/mfd/omap-usb-host.txt - -Example for OMAP4: - -usbhsehci: ehci@4a064c00 { - compatible = "ti,ehci-omap"; - reg = <0x4a064c00 0x400>; - interrupts = <0 77 0x4>; -}; - -&usbhsehci { - phys = <&hsusb1_phy 0 &hsusb3_phy>; -}; diff --git a/Documentation/devicetree/bindings/usb/ehci-orion.txt b/Documentation/devicetree/bindings/usb/ehci-orion.txt deleted file mode 100644 index 2855bae79fda..000000000000 --- a/Documentation/devicetree/bindings/usb/ehci-orion.txt +++ /dev/null @@ -1,22 +0,0 @@ -* EHCI controller, Orion Marvell variants - -Required properties: -- compatible: must be one of the following - "marvell,orion-ehci" - "marvell,armada-3700-ehci" -- reg: physical base address of the controller and length of memory mapped - region. -- interrupts: The EHCI interrupt - -Optional properties: -- clocks: reference to the clock -- phys: reference to the USB PHY -- phy-names: name of the USB PHY, should be "usb" - -Example: - - ehci@50000 { - compatible = "marvell,orion-ehci"; - reg = <0x50000 0x1000>; - interrupts = <19>; - }; diff --git a/Documentation/devicetree/bindings/usb/faraday,fotg210.yaml b/Documentation/devicetree/bindings/usb/faraday,fotg210.yaml index 84b3b69256b1..3fe4d1564dfe 100644 --- a/Documentation/devicetree/bindings/usb/faraday,fotg210.yaml +++ b/Documentation/devicetree/bindings/usb/faraday,fotg210.yaml @@ -5,7 +5,7 @@ $id: http://devicetree.org/schemas/usb/faraday,fotg210.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Faraday Technology FOTG210 HS OTG USB 2.0 controller +title: Faraday Technology FOTG200 series HS OTG USB 2.0 controller maintainers: - Linus Walleij <linus.walleij@linaro.org> @@ -17,10 +17,11 @@ allOf: properties: compatible: oneOf: + - const: faraday,fotg200 - const: faraday,fotg210 - items: - const: cortina,gemini-usb - - const: faraday,fotg210 + - const: faraday,fotg200 reg: maxItems: 1 @@ -66,7 +67,7 @@ examples: #include <dt-bindings/clock/cortina,gemini-clock.h> #include <dt-bindings/reset/cortina,gemini-reset.h> usb0: usb@68000000 { - compatible = "cortina,gemini-usb", "faraday,fotg210"; + compatible = "cortina,gemini-usb", "faraday,fotg200"; reg = <0x68000000 0x1000>; interrupts = <10 IRQ_TYPE_LEVEL_HIGH>; resets = <&syscon GEMINI_RESET_USB0>; diff --git a/Documentation/devicetree/bindings/usb/fcs,fsa4480.yaml b/Documentation/devicetree/bindings/usb/fcs,fsa4480.yaml index 9473f26b0621..51120fe90322 100644 --- a/Documentation/devicetree/bindings/usb/fcs,fsa4480.yaml +++ b/Documentation/devicetree/bindings/usb/fcs,fsa4480.yaml @@ -51,7 +51,7 @@ examples: #address-cells = <1>; #size-cells = <0>; - fsa4480@42 { + typec-mux@42 { compatible = "fcs,fsa4480"; reg = <0x42>; diff --git a/Documentation/devicetree/bindings/usb/fcs,fusb302.txt b/Documentation/devicetree/bindings/usb/fcs,fusb302.txt deleted file mode 100644 index 60e4654297af..000000000000 --- a/Documentation/devicetree/bindings/usb/fcs,fusb302.txt +++ /dev/null @@ -1,34 +0,0 @@ -Fairchild FUSB302 Type-C Port controllers - -Required properties : -- compatible : "fcs,fusb302" -- reg : I2C slave address -- interrupts : Interrupt specifier - -Required sub-node: -- connector : The "usb-c-connector" attached to the FUSB302 IC. The bindings - of the connector node are specified in: - - Documentation/devicetree/bindings/connector/usb-connector.yaml - - -Example: - -fusb302: typec-portc@54 { - compatible = "fcs,fusb302"; - reg = <0x54>; - interrupt-parent = <&nmi_intc>; - interrupts = <0 IRQ_TYPE_LEVEL_LOW>; - - usb_con: connector { - compatible = "usb-c-connector"; - label = "USB-C"; - power-role = "dual"; - try-power-role = "sink"; - source-pdos = <PDO_FIXED(5000, 3000, PDO_FIXED_USB_COMM)>; - sink-pdos = <PDO_FIXED(5000, 3000, PDO_FIXED_USB_COMM) - PDO_VAR(3000, 12000, 3000) - PDO_PPS_APDO(3000, 11000, 3000)>; - op-sink-microwatt = <10000000>; - }; -}; diff --git a/Documentation/devicetree/bindings/usb/fcs,fusb302.yaml b/Documentation/devicetree/bindings/usb/fcs,fusb302.yaml new file mode 100644 index 000000000000..b396ea0ab10c --- /dev/null +++ b/Documentation/devicetree/bindings/usb/fcs,fusb302.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/fcs,fusb302.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Fairchild FUSB302 Type-C Port controller + +maintainers: + - Rob Herring <robh@kernel.org> + +properties: + compatible: + const: fcs,fusb302 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + vbus-supply: + description: VBUS power supply + + connector: + type: object + $ref: /schemas/connector/usb-connector.yaml# + unevaluatedProperties: false + +required: + - compatible + - reg + - interrupts + - vbus-supply + - connector + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/usb/pd.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + typec-portc@54 { + compatible = "fcs,fusb302"; + reg = <0x54>; + interrupt-parent = <&nmi_intc>; + interrupts = <0 IRQ_TYPE_LEVEL_LOW>; + vbus-supply = <&vbus_typec>; + + connector { + compatible = "usb-c-connector"; + label = "USB-C"; + power-role = "dual"; + try-power-role = "sink"; + source-pdos = <PDO_FIXED(5000, 3000, PDO_FIXED_USB_COMM)>; + sink-pdos = <PDO_FIXED(5000, 3000, PDO_FIXED_USB_COMM) + PDO_VAR(3000, 12000, 3000) + PDO_PPS_APDO(3000, 11000, 3000)>; + op-sink-microwatt = <10000000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml b/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml index 01ab0f922ae8..3fb4feb6d3d9 100644 --- a/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml @@ -71,6 +71,9 @@ properties: description: Power pad (PWR) polarity is active low. + power-domains: + maxItems: 1 + # Required child node: patternProperties: @@ -87,12 +90,14 @@ required: - clocks - clock-names - interrupts + - power-domains additionalProperties: false examples: - | #include <dt-bindings/clock/imx8mp-clock.h> + #include <dt-bindings/power/imx8mp-power.h> #include <dt-bindings/interrupt-controller/arm-gic.h> usb3_0: usb@32f10100 { compatible = "fsl,imx8mp-dwc3"; @@ -102,6 +107,7 @@ examples: <&clk IMX8MP_CLK_USB_ROOT>; clock-names = "hsio", "suspend"; interrupts = <GIC_SPI 148 IRQ_TYPE_LEVEL_HIGH>; + power-domains = <&hsio_blk_ctrl IMX8MP_HSIOBLK_PD_USB>; #address-cells = <1>; #size-cells = <1>; dma-ranges = <0x40000000 0x40000000 0xc0000000>; diff --git a/Documentation/devicetree/bindings/usb/generic-ehci.yaml b/Documentation/devicetree/bindings/usb/generic-ehci.yaml index 994818cb6044..050cfd5acdaa 100644 --- a/Documentation/devicetree/bindings/usb/generic-ehci.yaml +++ b/Documentation/devicetree/bindings/usb/generic-ehci.yaml @@ -74,6 +74,11 @@ properties: - const: usb-ehci - enum: - generic-ehci + - marvell,armada-3700-ehci + - marvell,orion-ehci + - nuvoton,npcm750-ehci + - nuvoton,npcm845-ehci + - ti,ehci-omap - usb-ehci reg: diff --git a/Documentation/devicetree/bindings/usb/generic-ohci.yaml b/Documentation/devicetree/bindings/usb/generic-ohci.yaml index 4fcbd0add49d..a9ba7257b884 100644 --- a/Documentation/devicetree/bindings/usb/generic-ohci.yaml +++ b/Documentation/devicetree/bindings/usb/generic-ohci.yaml @@ -6,9 +6,6 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: USB OHCI Controller -allOf: - - $ref: "usb-hcd.yaml" - maintainers: - Greg Kroah-Hartman <gregkh@linuxfoundation.org> @@ -49,7 +46,16 @@ properties: - ingenic,jz4740-ohci - snps,hsdk-v1.0-ohci - const: generic-ohci - - const: generic-ohci + - enum: + - generic-ohci + - ti,ohci-omap3 + - items: + - enum: + - cavium,octeon-6335-ohci + - nintendo,hollywood-usb-ohci + - nxp,ohci-nxp + - st,spear600-ohci + - const: usb-ohci reg: maxItems: 1 @@ -119,11 +125,29 @@ properties: - host - otg + transceiver: + $ref: /schemas/types.yaml#/definitions/phandle + description: + The associated ISP1301 device. Necessary for the UDC controller for + connecting to the USB physical layer. + required: - compatible - reg - interrupts +allOf: + - $ref: usb-hcd.yaml + - if: + not: + properties: + compatible: + contains: + const: nxp,ohci-nxp + then: + properties: + transceiver: false + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/usb/genesys,gl850g.yaml b/Documentation/devicetree/bindings/usb/genesys,gl850g.yaml index a9f831448cca..cc4cf92b70d1 100644 --- a/Documentation/devicetree/bindings/usb/genesys,gl850g.yaml +++ b/Documentation/devicetree/bindings/usb/genesys,gl850g.yaml @@ -16,6 +16,7 @@ properties: compatible: enum: - usb5e3,608 + - usb5e3,610 reg: true diff --git a/Documentation/devicetree/bindings/usb/gpio-sbu-mux.yaml b/Documentation/devicetree/bindings/usb/gpio-sbu-mux.yaml new file mode 100644 index 000000000000..bf4b1d016e1f --- /dev/null +++ b/Documentation/devicetree/bindings/usb/gpio-sbu-mux.yaml @@ -0,0 +1,110 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/usb/gpio-sbu-mux.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: GPIO-based SBU mux + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + +description: + In USB Type-C applications the SBU lines needs to be connected, disconnected + and swapped depending on the altmode and orientation. This binding describes + a family of hardware solutions which switches between these modes using GPIO + signals. + +properties: + compatible: + items: + - enum: + - onnn,fsusb43l10x + - pericom,pi3usb102 + - const: gpio-sbu-mux + + enable-gpios: + description: Switch enable GPIO + + select-gpios: + description: Orientation select + + vcc-supply: + description: power supply + + mode-switch: + description: Flag the port as possible handle of altmode switching + type: boolean + + orientation-switch: + description: Flag the port as possible handler of orientation switching + type: boolean + + port: + $ref: /schemas/graph.yaml#/properties/port + description: + A port node to link the SBU mux to a TypeC controller for the purpose of + handling altmode muxing and orientation switching. + +required: + - compatible + - enable-gpios + - select-gpios + - mode-switch + - orientation-switch + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + tcpm { + connector { + compatible = "usb-c-connector"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + tcpm_hs_out: endpoint { + remote-endpoint = <&usb_hs_phy_in>; + }; + }; + + port@1 { + reg = <1>; + tcpm_ss_out: endpoint { + remote-endpoint = <&usb_ss_phy_in>; + }; + }; + + port@2 { + reg = <2>; + tcpm_sbu_out: endpoint { + remote-endpoint = <&sbu_mux_in>; + }; + }; + }; + }; + }; + + sbu-mux { + compatible = "pericom,pi3usb102", "gpio-sbu-mux"; + + enable-gpios = <&tlmm 101 GPIO_ACTIVE_LOW>; + select-gpios = <&tlmm 164 GPIO_ACTIVE_HIGH>; + + mode-switch; + orientation-switch; + + port { + sbu_mux_in: endpoint { + remote-endpoint = <&tcpm_sbu_out>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml index a3c37944c630..c119caa9ad16 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml +++ b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml @@ -35,6 +35,7 @@ properties: - mediatek,mt8188-xhci - mediatek,mt8192-xhci - mediatek,mt8195-xhci + - mediatek,mt8365-xhci - const: mediatek,mtk-xhci reg: diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml index 7168110e2f9d..d2655173e108 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml +++ b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml @@ -28,6 +28,7 @@ properties: - mediatek,mt8188-mtu3 - mediatek,mt8192-mtu3 - mediatek,mt8195-mtu3 + - mediatek,mt8365-mtu3 - const: mediatek,mtu3 reg: diff --git a/Documentation/devicetree/bindings/usb/npcm7xx-usb.txt b/Documentation/devicetree/bindings/usb/npcm7xx-usb.txt deleted file mode 100644 index 352a0a1e2f76..000000000000 --- a/Documentation/devicetree/bindings/usb/npcm7xx-usb.txt +++ /dev/null @@ -1,20 +0,0 @@ -Nuvoton NPCM7XX SoC USB controllers: ------------------------------ - -EHCI: ------ - -Required properties: -- compatible: should be one of - "nuvoton,npcm750-ehci" - "nuvoton,npcm845-ehci" -- interrupts: Should contain the EHCI interrupt -- reg: Physical address and length of the register set for the device - -Example: - - ehci1: usb@f0806000 { - compatible = "nuvoton,npcm750-ehci"; - reg = <0xf0806000 0x1000>; - interrupts = <0 61 4>; - }; diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra-xudc.yaml b/Documentation/devicetree/bindings/usb/nvidia,tegra-xudc.yaml index f6cb19efd98b..e638f77658fc 100644 --- a/Documentation/devicetree/bindings/usb/nvidia,tegra-xudc.yaml +++ b/Documentation/devicetree/bindings/usb/nvidia,tegra-xudc.yaml @@ -22,6 +22,7 @@ properties: - nvidia,tegra210-xudc # For Tegra210 - nvidia,tegra186-xudc # For Tegra186 - nvidia,tegra194-xudc # For Tegra194 + - nvidia,tegra234-xudc # For Tegra234 reg: minItems: 2 @@ -112,6 +113,8 @@ properties: hvdd-usb-supply: description: USB controller power supply. Must supply 3.3 V. + dma-coherent: true + required: - compatible - reg @@ -153,6 +156,7 @@ allOf: enum: - nvidia,tegra186-xudc - nvidia,tegra194-xudc + - nvidia,tegra234-xudc then: properties: reg: @@ -164,6 +168,17 @@ allOf: clock-names: maxItems: 4 + - if: + properties: + compatible: + contains: + enum: + - nvidia,tegra194-xudc + - nvidia,tegra234-xudc + then: + required: + - dma-coherent + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra234-xusb.yaml b/Documentation/devicetree/bindings/usb/nvidia,tegra234-xusb.yaml new file mode 100644 index 000000000000..db761dcbf72a --- /dev/null +++ b/Documentation/devicetree/bindings/usb/nvidia,tegra234-xusb.yaml @@ -0,0 +1,159 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/nvidia,tegra234-xusb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra234 xHCI controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +description: | + The Tegra xHCI controller supports both USB2 and USB3 interfaces exposed by + the Tegra XUSB pad controller. The xHCI controller controls up to eight + ports; there are four USB 2.0 ports and four USB 3.2 Gen1 x1 ports. + +properties: + compatible: + const: nvidia,tegra234-xusb + + reg: + items: + - description: xHCI host registers + - description: XUSB FPCI registers + - description: XUSB bar2 registers + + reg-names: + items: + - const: hcd + - const: fpci + - const: bar2 + + interrupts: + items: + - description: xHCI host interrupt + - description: mailbox interrupt + + clocks: + items: + - description: XUSB host clock + - description: XUSB Falcon source clock + - description: XUSB SuperSpeed clock + - description: XUSB SuperSpeed source clock + - description: XUSB HighSpeed clock source + - description: XUSB FullSpeed clock source + - description: USB PLL + - description: reference clock + - description: I/O PLL + + clock-names: + items: + - const: xusb_host + - const: xusb_falcon_src + - const: xusb_ss + - const: xusb_ss_src + - const: xusb_hs_src + - const: xusb_fs_src + - const: pll_u_480m + - const: clk_m + - const: pll_e + + interconnects: + items: + - description: read client + - description: write client + + interconnect-names: + items: + - const: dma-mem # read + - const: write + + iommus: + maxItems: 1 + + nvidia,xusb-padctl: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to the XUSB pad controller that is used to configure + the USB pads used by the XHCI controller + + phys: + minItems: 1 + maxItems: 8 + + phy-names: + minItems: 1 + maxItems: 8 + items: + enum: + - usb2-0 + - usb2-1 + - usb2-2 + - usb2-3 + - usb3-0 + - usb3-1 + - usb3-2 + - usb3-3 + + power-domains: + items: + - description: XUSBC power domain (for Host and USB 2.0) + - description: XUSBA power domain (for SuperSpeed) + + power-domain-names: + items: + - const: xusb_host + - const: xusb_ss + + dma-coherent: true + +allOf: + - $ref: usb-xhci.yaml + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/tegra234-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/memory/tegra234-mc.h> + #include <dt-bindings/power/tegra234-powergate.h> + + usb@3610000 { + compatible = "nvidia,tegra234-xusb"; + reg = <0x03610000 0x40000>, + <0x03600000 0x10000>, + <0x03650000 0x10000>; + reg-names = "hcd", "fpci", "bar2"; + + interrupts = <GIC_SPI 163 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 164 IRQ_TYPE_LEVEL_HIGH>; + + clocks = <&bpmp TEGRA234_CLK_XUSB_CORE_HOST>, + <&bpmp TEGRA234_CLK_XUSB_FALCON>, + <&bpmp TEGRA234_CLK_XUSB_CORE_SS>, + <&bpmp TEGRA234_CLK_XUSB_SS>, + <&bpmp TEGRA234_CLK_CLK_M>, + <&bpmp TEGRA234_CLK_XUSB_FS>, + <&bpmp TEGRA234_CLK_UTMIP_PLL>, + <&bpmp TEGRA234_CLK_CLK_M>, + <&bpmp TEGRA234_CLK_PLLE>; + clock-names = "xusb_host", "xusb_falcon_src", + "xusb_ss", "xusb_ss_src", "xusb_hs_src", + "xusb_fs_src", "pll_u_480m", "clk_m", + "pll_e"; + interconnects = <&mc TEGRA234_MEMORY_CLIENT_XUSB_HOSTR &emc>, + <&mc TEGRA234_MEMORY_CLIENT_XUSB_HOSTW &emc>; + interconnect-names = "dma-mem", "write"; + iommus = <&smmu_niso1 TEGRA234_SID_XUSB_HOST>; + + power-domains = <&bpmp TEGRA234_POWER_DOMAIN_XUSBC>, + <&bpmp TEGRA234_POWER_DOMAIN_XUSBA>; + power-domain-names = "xusb_host", "xusb_ss"; + + nvidia,xusb-padctl = <&xusb_padctl>; + + phys = <&pad_lanes_usb2_0>; + phy-names = "usb2-0"; + }; diff --git a/Documentation/devicetree/bindings/usb/ohci-nxp.txt b/Documentation/devicetree/bindings/usb/ohci-nxp.txt deleted file mode 100644 index 71e28c1017ed..000000000000 --- a/Documentation/devicetree/bindings/usb/ohci-nxp.txt +++ /dev/null @@ -1,24 +0,0 @@ -* OHCI controller, NXP ohci-nxp variant - -Required properties: -- compatible: must be "nxp,ohci-nxp" -- reg: physical base address of the controller and length of memory mapped - region. -- interrupts: The OHCI interrupt -- transceiver: phandle of the associated ISP1301 device - this is necessary for - the UDC controller for connecting to the USB physical layer - -Example (LPC32xx): - - isp1301: usb-transceiver@2c { - compatible = "nxp,isp1301"; - reg = <0x2c>; - }; - - ohci@31020000 { - compatible = "nxp,ohci-nxp"; - reg = <0x31020000 0x300>; - interrupt-parent = <&mic>; - interrupts = <0x3b 0>; - transceiver = <&isp1301>; - }; diff --git a/Documentation/devicetree/bindings/usb/ohci-omap3.txt b/Documentation/devicetree/bindings/usb/ohci-omap3.txt deleted file mode 100644 index ce8c47cff6d0..000000000000 --- a/Documentation/devicetree/bindings/usb/ohci-omap3.txt +++ /dev/null @@ -1,15 +0,0 @@ -OMAP HS USB OHCI controller (OMAP3 and later) - -Required properties: - -- compatible: should be "ti,ohci-omap3" -- reg: should contain one register range i.e. start and length -- interrupts: description of the interrupt line - -Example for OMAP4: - -usbhsohci: ohci@4a064800 { - compatible = "ti,ohci-omap3"; - reg = <0x4a064800 0x400>; - interrupts = <0 76 0x4>; -}; diff --git a/Documentation/devicetree/bindings/usb/pxa-usb.txt b/Documentation/devicetree/bindings/usb/pxa-usb.txt index 9c331799b87c..53fdae4fa6f6 100644 --- a/Documentation/devicetree/bindings/usb/pxa-usb.txt +++ b/Documentation/devicetree/bindings/usb/pxa-usb.txt @@ -22,7 +22,7 @@ Optional properties: Example: usb0: ohci@4c000000 { - compatible = "marvell,pxa-ohci", "usb-ohci"; + compatible = "marvell,pxa-ohci"; reg = <0x4c000000 0x100000>; interrupts = <18>; marvell,enable-port1; diff --git a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml index a3f8a3f49852..4875c5b7d5b5 100644 --- a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml @@ -58,6 +58,9 @@ properties: description: specifies a phandle to PM domain provider node maxItems: 1 + required-opps: + maxItems: 1 + clocks: description: | Several clocks are used, depending on the variant. Typical ones are:: diff --git a/Documentation/devicetree/bindings/usb/renesas,rzn1-usbf.yaml b/Documentation/devicetree/bindings/usb/renesas,rzn1-usbf.yaml new file mode 100644 index 000000000000..b6e84a2a6925 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/renesas,rzn1-usbf.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/renesas,rzn1-usbf.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/N1 SoCs USBF (USB Function) controller + +description: | + The Renesas USBF controller is an USB2.0 device + controller (UDC). + +maintainers: + - Herve Codina <herve.codina@bootlin.com> + +properties: + compatible: + items: + - enum: + - renesas,r9a06g032-usbf + - const: renesas,rzn1-usbf + + reg: + maxItems: 1 + + clocks: + items: + - description: Internal bus clock (AHB) for Function + - description: Internal bus clock (AHB) for Power Management + + clock-names: + items: + - const: hclkf + - const: hclkpm + + power-domains: + maxItems: 1 + + interrupts: + items: + - description: The USBF EPC interrupt + - description: The USBF AHB-EPC interrupt + +required: + - compatible + - reg + - clocks + - clock-names + - power-domains + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/r9a06g032-sysctrl.h> + + usb@4001e000 { + compatible = "renesas,r9a06g032-usbf", "renesas,rzn1-usbf"; + reg = <0x4001e000 0x2000>; + interrupts = <GIC_SPI 77 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 78 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&sysctrl R9A06G032_HCLK_USBF>, + <&sysctrl R9A06G032_HCLK_USBPM>; + clock-names = "hclkf", "hclkpm"; + power-domains = <&sysctrl>; + }; diff --git a/Documentation/devicetree/bindings/usb/renesas,rzv2m-usb3drd.yaml b/Documentation/devicetree/bindings/usb/renesas,rzv2m-usb3drd.yaml new file mode 100644 index 000000000000..ff625600d9af --- /dev/null +++ b/Documentation/devicetree/bindings/usb/renesas,rzv2m-usb3drd.yaml @@ -0,0 +1,129 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/renesas,rzv2m-usb3drd.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/V2M USB 3.1 DRD controller + +maintainers: + - Biju Das <biju.das.jz@bp.renesas.com> + +description: | + The RZ/V2{M, MA} USB3.1 DRD module supports the following functions + * Role swapping function by the ID pin of the Micro-AB receptacle + * Battery Charging Specification Revision 1.2 + +properties: + compatible: + items: + - enum: + - renesas,r9a09g011-usb3drd # RZ/V2M + - renesas,r9a09g055-usb3drd # RZ/V2MA + - const: renesas,rzv2m-usb3drd + + reg: + maxItems: 1 + + interrupts: + items: + - description: Dual Role Device (DRD) + - description: Battery Charging + - description: Global Purpose Input + + interrupt-names: + items: + - const: drd + - const: bc + - const: gpi + + clocks: + items: + - description: Peripheral AXI clock + - description: APB clock + + clock-names: + items: + - const: axi + - const: reg + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + ranges: true + + '#address-cells': + enum: [ 1, 2 ] + + '#size-cells': + enum: [ 1, 2 ] + +patternProperties: + "^usb3peri@[0-9a-f]+$": + type: object + $ref: /schemas/usb/renesas,usb3-peri.yaml + + "^usb@[0-9a-f]+$": + type: object + $ref: renesas,usb-xhci.yaml# + +required: + - compatible + - reg + - interrupts + - interrupt-names + - clocks + - clock-names + - power-domains + - resets + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r9a09g011-cpg.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + usb3drd: usb@85070400 { + compatible = "renesas,r9a09g011-usb3drd", "renesas,rzv2m-usb3drd"; + reg = <0x85070400 0x100>; + interrupts = <GIC_SPI 242 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 243 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 244 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "drd", "bc", "gpi"; + clocks = <&cpg CPG_MOD R9A09G011_USB_ACLK_P>, + <&cpg CPG_MOD R9A09G011_USB_PCLK>; + clock-names = "axi", "reg"; + power-domains = <&cpg>; + resets = <&cpg R9A09G011_USB_DRD_RESET>; + ranges; + #address-cells = <1>; + #size-cells = <1>; + + usb3host: usb@85060000 { + compatible = "renesas,r9a09g011-xhci", + "renesas,rzv2m-xhci"; + reg = <0x85060000 0x2000>; + interrupts = <GIC_SPI 245 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD R9A09G011_USB_ACLK_H>, + <&cpg CPG_MOD R9A09G011_USB_PCLK>; + clock-names = "axi", "reg"; + power-domains = <&cpg>; + resets = <&cpg R9A09G011_USB_ARESETN_H>; + }; + + usb3peri: usb3peri@85070000 { + compatible = "renesas,r9a09g011-usb3-peri", + "renesas,rzv2m-usb3-peri"; + reg = <0x85070000 0x400>; + interrupts = <GIC_SPI 246 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD R9A09G011_USB_ACLK_P>, + <&cpg CPG_MOD R9A09G011_USB_PCLK>; + clock-names = "axi", "reg"; + power-domains = <&cpg>; + resets = <&cpg R9A09G011_USB_ARESETN_P>; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml b/Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml index 4c5efaf02308..1a07c0d2b1b1 100644 --- a/Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml +++ b/Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml @@ -10,9 +10,6 @@ maintainers: - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com> - Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com> -allOf: - - $ref: "usb-xhci.yaml" - properties: compatible: oneOf: @@ -37,6 +34,11 @@ properties: - renesas,xhci-r8a77965 # R-Car M3-N - renesas,xhci-r8a77990 # R-Car E3 - const: renesas,rcar-gen3-xhci # R-Car Gen3 and RZ/G2 + - items: + - enum: + - renesas,r9a09g011-xhci # RZ/V2M + - renesas,r9a09g055-xhci # RZ/V2MA + - const: renesas,rzv2m-xhci # RZ/{V2M, V2MA} reg: maxItems: 1 @@ -45,7 +47,16 @@ properties: maxItems: 1 clocks: - maxItems: 1 + minItems: 1 + items: + - description: Main clock for host + - description: Register access clock + + clock-names: + minItems: 1 + items: + - const: axi + - const: reg phys: maxItems: 1 @@ -68,6 +79,28 @@ required: - power-domains - resets +allOf: + - $ref: usb-xhci.yaml + + - if: + properties: + compatible: + contains: + enum: + - renesas,rzv2m-xhci + then: + properties: + clocks: + minItems: 2 + clock-names: + minItems: 2 + required: + - clock-names + else: + properties: + clocks: + maxItems: 1 + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/usb/renesas,usb3-peri.yaml b/Documentation/devicetree/bindings/usb/renesas,usb3-peri.yaml index 55dfd121b555..b2b811a0ade8 100644 --- a/Documentation/devicetree/bindings/usb/renesas,usb3-peri.yaml +++ b/Documentation/devicetree/bindings/usb/renesas,usb3-peri.yaml @@ -28,26 +28,14 @@ properties: - items: - enum: - renesas,r9a09g011-usb3-peri # RZ/V2M + - renesas,r9a09g055-usb3-peri # RZ/V2MA - const: renesas,rzv2m-usb3-peri reg: maxItems: 1 interrupts: - minItems: 1 - items: - - description: Combined interrupt for DMA, SYS and ERR - - description: Dual Role Device (DRD) - - description: Battery Charging - - description: Global Purpose Input - - interrupt-names: - minItems: 1 - items: - - const: all_p - - const: drd - - const: bc - - const: gpi + maxItems: 1 clocks: minItems: 1 @@ -58,7 +46,7 @@ properties: clock-names: minItems: 1 items: - - const: aclk + - const: axi - const: reg phys: @@ -71,15 +59,7 @@ properties: maxItems: 1 resets: - minItems: 1 - items: - - description: Peripheral reset - - description: DRD reset - - reset-names: - items: - - const: aresetn_p - - const: drd_reset + maxItems: 1 usb-role-switch: $ref: /schemas/types.yaml#/definitions/flag @@ -127,25 +107,13 @@ allOf: minItems: 2 clock-names: minItems: 2 - interrupts: - minItems: 4 - interrupt-names: - minItems: 4 - resets: - minItems: 2 required: - clock-names - - interrupt-names - resets - - reset-names else: properties: clocks: maxItems: 1 - interrupts: - maxItems: 1 - resets: - maxItems: 1 additionalProperties: false diff --git a/Documentation/devicetree/bindings/usb/rockchip,dwc3.yaml b/Documentation/devicetree/bindings/usb/rockchip,dwc3.yaml index b3798d94d2fd..291844c8f3e1 100644 --- a/Documentation/devicetree/bindings/usb/rockchip,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/rockchip,dwc3.yaml @@ -29,7 +29,6 @@ select: contains: enum: - rockchip,rk3328-dwc3 - - rockchip,rk3399-dwc3 - rockchip,rk3568-dwc3 required: - compatible @@ -39,7 +38,6 @@ properties: items: - enum: - rockchip,rk3328-dwc3 - - rockchip,rk3399-dwc3 - rockchip,rk3568-dwc3 - const: snps,dwc3 @@ -90,7 +88,7 @@ required: examples: - | - #include <dt-bindings/clock/rk3399-cru.h> + #include <dt-bindings/clock/rk3328-cru.h> #include <dt-bindings/interrupt-controller/arm-gic.h> bus { @@ -98,11 +96,11 @@ examples: #size-cells = <2>; usbdrd3_0: usb@fe800000 { - compatible = "rockchip,rk3399-dwc3", "snps,dwc3"; + compatible = "rockchip,rk3328-dwc3", "snps,dwc3"; reg = <0x0 0xfe800000 0x0 0x100000>; interrupts = <GIC_SPI 105 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cru SCLK_USB3OTG0_REF>, <&cru SCLK_USB3OTG0_SUSPEND>, - <&cru ACLK_USB3OTG0>, <&cru ACLK_USB3_GRF>; + clocks = <&cru SCLK_USB3OTG_REF>, <&cru SCLK_USB3OTG_SUSPEND>, + <&cru ACLK_USB3OTG>; clock-names = "ref_clk", "suspend_clk", "bus_clk", "grf_clk"; dr_mode = "otg"; diff --git a/Documentation/devicetree/bindings/usb/rockchip,rk3399-dwc3.yaml b/Documentation/devicetree/bindings/usb/rockchip,rk3399-dwc3.yaml new file mode 100644 index 000000000000..3159f9a6a0f7 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/rockchip,rk3399-dwc3.yaml @@ -0,0 +1,115 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/rockchip,rk3399-dwc3.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip RK3399 SuperSpeed DWC3 USB SoC controller + +maintainers: + - Heiko Stuebner <heiko@sntech.de> + +properties: + compatible: + const: rockchip,rk3399-dwc3 + + '#address-cells': + const: 2 + + '#size-cells': + const: 2 + + ranges: true + + clocks: + items: + - description: + Controller reference clock, must to be 24 MHz + - description: + Controller suspend clock, must to be 24 MHz or 32 KHz + - description: + Master/Core clock, must to be >= 62.5 MHz for SS + operation and >= 30MHz for HS operation + - description: + USB3 aclk peri + - description: + USB3 aclk + - description: + Controller grf clock + + clock-names: + items: + - const: ref_clk + - const: suspend_clk + - const: bus_clk + - const: aclk_usb3_rksoc_axi_perf + - const: aclk_usb3 + - const: grf_clk + + resets: + maxItems: 1 + + reset-names: + const: usb3-otg + +patternProperties: + '^usb@': + $ref: snps,dwc3.yaml# + +additionalProperties: false + +required: + - compatible + - '#address-cells' + - '#size-cells' + - ranges + - clocks + - clock-names + - resets + - reset-names + +examples: + - | + #include <dt-bindings/clock/rk3399-cru.h> + #include <dt-bindings/power/rk3399-power.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + bus { + #address-cells = <2>; + #size-cells = <2>; + + usb { + compatible = "rockchip,rk3399-dwc3"; + #address-cells = <2>; + #size-cells = <2>; + ranges; + clocks = <&cru SCLK_USB3OTG0_REF>, <&cru SCLK_USB3OTG0_SUSPEND>, + <&cru ACLK_USB3OTG0>, <&cru ACLK_USB3_RKSOC_AXI_PERF>, + <&cru ACLK_USB3>, <&cru ACLK_USB3_GRF>; + clock-names = "ref_clk", "suspend_clk", + "bus_clk", "aclk_usb3_rksoc_axi_perf", + "aclk_usb3", "grf_clk"; + resets = <&cru SRST_A_USB3_OTG0>; + reset-names = "usb3-otg"; + + usb@fe800000 { + compatible = "snps,dwc3"; + reg = <0x0 0xfe800000 0x0 0x100000>; + interrupts = <GIC_SPI 105 IRQ_TYPE_LEVEL_HIGH 0>; + clocks = <&cru SCLK_USB3OTG0_REF>, <&cru ACLK_USB3OTG0>, + <&cru SCLK_USB3OTG0_SUSPEND>; + clock-names = "ref", "bus_early", "suspend"; + dr_mode = "otg"; + phys = <&u2phy0_otg>, <&tcphy0_usb3>; + phy-names = "usb2-phy", "usb3-phy"; + phy_type = "utmi_wide"; + snps,dis_enblslpm_quirk; + snps,dis-u2-freeclk-exists-quirk; + snps,dis_u2_susphy_quirk; + snps,dis-del-phy-power-chg-quirk; + snps,dis-tx-ipgap-linecheck-quirk; + power-domains = <&power RK3399_PD_USB3>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/usb/samsung,exynos-dwc3.yaml b/Documentation/devicetree/bindings/usb/samsung,exynos-dwc3.yaml index 6b9a3bcb3926..42ceaf13cd5d 100644 --- a/Documentation/devicetree/bindings/usb/samsung,exynos-dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/samsung,exynos-dwc3.yaml @@ -108,19 +108,19 @@ examples: #include <dt-bindings/clock/exynos5420.h> #include <dt-bindings/interrupt-controller/arm-gic.h> - usb { + usb@12000000 { compatible = "samsung,exynos5250-dwusb3"; #address-cells = <1>; #size-cells = <1>; - ranges; + ranges = <0x0 0x12000000 0x10000>; clocks = <&clock CLK_USBD300>; clock-names = "usbdrd30"; vdd33-supply = <&ldo9_reg>; vdd10-supply = <&ldo11_reg>; - usb@12000000 { + usb@0 { compatible = "snps,dwc3"; - reg = <0x12000000 0x10000>; + reg = <0x0 0x10000>; interrupts = <GIC_SPI 72 IRQ_TYPE_LEVEL_HIGH>; phys = <&usbdrd_phy0 0>, <&usbdrd_phy0 1>; phy-names = "usb2-phy", "usb3-phy"; diff --git a/Documentation/devicetree/bindings/usb/snps,dwc3.yaml b/Documentation/devicetree/bindings/usb/snps,dwc3.yaml index 6d78048c4613..be36956af53b 100644 --- a/Documentation/devicetree/bindings/usb/snps,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/snps,dwc3.yaml @@ -91,6 +91,16 @@ properties: - usb2-phy - usb3-phy + power-domains: + description: + The DWC3 has 2 power-domains. The power management unit (PMU) and + everything else. The PMU is typically always powered and may not have an + entry. + minItems: 1 + items: + - description: Core + - description: Power management unit + resets: minItems: 1 diff --git a/Documentation/devicetree/bindings/usb/spear-usb.txt b/Documentation/devicetree/bindings/usb/spear-usb.txt deleted file mode 100644 index 1dc91cc459c0..000000000000 --- a/Documentation/devicetree/bindings/usb/spear-usb.txt +++ /dev/null @@ -1,35 +0,0 @@ -ST SPEAr SoC USB controllers: ------------------------------ - -EHCI: ------ - -Required properties: -- compatible: "st,spear600-ehci" -- interrupts: Should contain the EHCI interrupt - -Example: - - ehci@e1800000 { - compatible = "st,spear600-ehci", "usb-ehci"; - reg = <0xe1800000 0x1000>; - interrupt-parent = <&vic1>; - interrupts = <27>; - }; - - -OHCI: ------ - -Required properties: -- compatible: "st,spear600-ohci" -- interrupts: Should contain the OHCI interrupt - -Example: - - ohci@e1900000 { - compatible = "st,spear600-ohci", "usb-ohci"; - reg = <0xe1800000 0x1000>; - interrupt-parent = <&vic1>; - interrupts = <26>; - }; diff --git a/Documentation/devicetree/bindings/usb/ti,hd3ss3220.yaml b/Documentation/devicetree/bindings/usb/ti,hd3ss3220.yaml index b86bf6bc9cd6..a1cffb70c621 100644 --- a/Documentation/devicetree/bindings/usb/ti,hd3ss3220.yaml +++ b/Documentation/devicetree/bindings/usb/ti,hd3ss3220.yaml @@ -46,7 +46,6 @@ properties: required: - compatible - reg - - interrupts additionalProperties: false diff --git a/Documentation/devicetree/bindings/usb/ti,tps6598x.yaml b/Documentation/devicetree/bindings/usb/ti,tps6598x.yaml index fef4acdc4773..348a715d61f4 100644 --- a/Documentation/devicetree/bindings/usb/ti,tps6598x.yaml +++ b/Documentation/devicetree/bindings/usb/ti,tps6598x.yaml @@ -23,6 +23,8 @@ properties: reg: maxItems: 1 + wakeup-source: true + interrupts: maxItems: 1 @@ -48,6 +50,7 @@ examples: tps6598x: tps6598x@38 { compatible = "ti,tps6598x"; reg = <0x38>; + wakeup-source; interrupt-parent = <&msmgpio>; interrupts = <107 IRQ_TYPE_LEVEL_LOW>; diff --git a/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml b/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml index 326131dcf14d..921b986adc47 100644 --- a/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml +++ b/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml @@ -35,7 +35,7 @@ properties: maxItems: 1 vbus-regulator: - description: Should specifiy the regulator supplying current drawn from + description: Should specify the regulator supplying current drawn from the VBus line. $ref: /schemas/types.yaml#/definitions/phandle diff --git a/Documentation/devicetree/bindings/usb/usbmisc-imx.txt b/Documentation/devicetree/bindings/usb/usbmisc-imx.txt index b796836d2ce7..29b8f65ff849 100644 --- a/Documentation/devicetree/bindings/usb/usbmisc-imx.txt +++ b/Documentation/devicetree/bindings/usb/usbmisc-imx.txt @@ -8,6 +8,7 @@ Required properties: "fsl,imx6sx-usbmisc" for imx6sx "fsl,imx7d-usbmisc" for imx7d "fsl,imx7ulp-usbmisc" for imx7ulp + "fsl,imx8mm-usbmisc" for imx8mm - reg: Should contain registers location and length Examples: diff --git a/Documentation/devicetree/bindings/usb/vialab,vl817.yaml b/Documentation/devicetree/bindings/usb/vialab,vl817.yaml new file mode 100644 index 000000000000..23a13e1d5c7a --- /dev/null +++ b/Documentation/devicetree/bindings/usb/vialab,vl817.yaml @@ -0,0 +1,71 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/vialab,vl817.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Via labs VL817 USB 3.1 hub controller + +maintainers: + - Anand Moon <linux.amoon@gmail.com> + +allOf: + - $ref: usb-device.yaml# + +properties: + compatible: + enum: + - usb2109,2817 + - usb2109,817 + + reg: true + + reset-gpios: + maxItems: 1 + description: + GPIO controlling the RESET# pin. + + vdd-supply: + description: + phandle to the regulator that provides power to the hub. + + peer-hub: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle to the peer hub on the controller. + +required: + - compatible + - reg + - reset-gpios + - vdd-supply + - peer-hub + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + usb { + #address-cells = <1>; + #size-cells = <0>; + + /* 2.0 hub on port 1 */ + hub_2_0: hub@1 { + compatible = "usb2109,2817"; + reg = <1>; + vdd-supply = <&vcc_5v>; + peer-hub = <&hub_3_0>; + reset-gpios = <&gpio 20 GPIO_ACTIVE_LOW>; + }; + + /* 3.1 hub on port 4 */ + hub_3_0: hub@2 { + compatible = "usb2109,817"; + reg = <2>; + vdd-supply = <&vcc_5v>; + peer-hub = <&hub_2_0>; + reset-gpios = <&gpio 20 GPIO_ACTIVE_LOW>; + }; + }; diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 70ffb3780621..ed64e06ecca4 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -69,6 +69,8 @@ patternProperties: description: Annapurna Labs "^alcatel,.*": description: Alcatel + "^aldec,.*": + description: Aldec, Inc. "^alfa-network,.*": description: ALFA Network Inc. "^allegro,.*": @@ -264,6 +266,8 @@ patternProperties: description: Cirrus Logic, Inc. "^cisco,.*": description: Cisco Systems, Inc. + "^clockwork,.*": + description: Clockwork Tech LLC "^cloos,.*": description: Carl Cloos Schweisstechnik GmbH. "^cloudengines,.*": @@ -374,6 +378,8 @@ patternProperties: description: EBV Elektronik "^eckelmann,.*": description: Eckelmann AG + "^edgeble,.*": + description: Edgeble AI Technologies Pvt. Ltd. "^edimax,.*": description: EDIMAX Technology Co., Ltd "^edt,.*": @@ -396,6 +402,8 @@ patternProperties: description: Elimo Engineering Ltd. "^elpida,.*": description: Elpida Memory, Inc. + "^embedfire,.*": + description: Dongguan EmbedFire Electronic Technology Co., Ltd. "^embest,.*": description: Shenzhen Embest Technology Co., Ltd. "^emlid,.*": @@ -512,6 +520,8 @@ patternProperties: description: Shenzhen Huiding Technology Co., Ltd. "^google,.*": description: Google, Inc. + "^gplus,.*": + description: GPLUS "^grinn,.*": description: Grinn "^grmn,.*": @@ -635,6 +645,8 @@ patternProperties: description: Inverse Path "^iom,.*": description: Iomega Corporation + "^irondevice,.*": + description: Iron Device Corporation "^isee,.*": description: ISEE 2007 S.L. "^isil,.*": @@ -729,6 +741,8 @@ patternProperties: description: Lichee Pi "^linaro,.*": description: Linaro Limited + "^lineartechnology,.*": + description: Linear Technology "^linksprite,.*": description: LinkSprite Technologies, Inc. "^linksys,.*": @@ -775,6 +789,8 @@ patternProperties: description: MaxBotix Inc. "^maxim,.*": description: Maxim Integrated Products + "^maxlinear,.*": + description: MaxLinear Inc. "^mbvl,.*": description: Mobiveil Inc. "^mcube,.*": @@ -845,6 +861,8 @@ patternProperties: description: Moortec Semiconductor Ltd. "^mosaixtech,.*": description: Mosaix Technologies, Inc. + "^motorcomm,.*": + description: MotorComm, Inc. "^motorola,.*": description: Motorola, Inc. "^moxa,.*": @@ -1025,6 +1043,8 @@ patternProperties: description: PocketBook International SA "^polaroid,.*": description: Polaroid Corporation + "^polyhex,.*": + description: Polyhex Technology Co. Ltd. "^portwell,.*": description: Portwell Inc. "^poslab,.*": @@ -1246,6 +1266,8 @@ patternProperties: description: Starry Electronic Technology (ShenZhen) Co., LTD "^startek,.*": description: Startek + "^starterkit,.*": + description: Starterkit "^ste,.*": description: ST-Ericsson deprecated: true @@ -1319,6 +1341,8 @@ patternProperties: description: thingy.jp "^thundercomm,.*": description: Thundercomm Technology Co., Ltd. + "^thwc,.*": + description: Shenzhen Tong Heng Wei Chuang Technology Co., Ltd. "^ti,.*": description: Texas Instruments "^tianma,.*": @@ -1372,6 +1396,8 @@ patternProperties: description: uCRobotics "^udoo,.*": description: Udoo + "^ufispace,.*": + description: Ufi Space Co., Ltd. "^ugoos,.*": description: Ugoos Industrial Co., Ltd. "^uniwest,.*": @@ -1398,6 +1424,8 @@ patternProperties: description: Vertexcom Technologies, Inc. "^via,.*": description: VIA Technologies, Inc. + "^vialab,.*": + description: VIA Labs, Inc. "^vicor,.*": description: Vicor Corporation "^videostrong,.*": @@ -1444,6 +1472,8 @@ patternProperties: description: Shenzhen whwave Electronics, Inc. "^wi2wi,.*": description: Wi2Wi, Inc. + "^widora,.*": + description: Beijing Widora Technology Co., Ltd. "^wiligear,.*": description: Wiligear, Ltd. "^willsemi,.*": diff --git a/Documentation/devicetree/bindings/watchdog/maxim,max63xx.yaml b/Documentation/devicetree/bindings/watchdog/maxim,max63xx.yaml index ab9641e845db..38079e1b6a44 100644 --- a/Documentation/devicetree/bindings/watchdog/maxim,max63xx.yaml +++ b/Documentation/devicetree/bindings/watchdog/maxim,max63xx.yaml @@ -8,6 +8,7 @@ title: Maxim 63xx Watchdog Timers allOf: - $ref: "watchdog.yaml#" + - $ref: /schemas/memory-controllers/mc-peripheral-props.yaml# maintainers: - Marc Zyngier <maz@kernel.org> diff --git a/Documentation/devicetree/bindings/watchdog/socionext,uniphier-wdt.yaml b/Documentation/devicetree/bindings/watchdog/socionext,uniphier-wdt.yaml index 90698cfa8f94..70c005fdd197 100644 --- a/Documentation/devicetree/bindings/watchdog/socionext,uniphier-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/socionext,uniphier-wdt.yaml @@ -25,12 +25,6 @@ examples: - | // The UniPhier watchdog should be a subnode of a "syscon" compatible node. - sysctrl@61840000 { - compatible = "socionext,uniphier-ld11-sysctrl", - "simple-mfd", "syscon"; - reg = <0x61840000 0x10000>; - - watchdog { - compatible = "socionext,uniphier-wdt"; - }; + watchdog { + compatible = "socionext,uniphier-wdt"; }; diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index 622b8156d212..2e8dfd1a66b6 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -1,5 +1,5 @@ -Buffer Sharing and Synchronization -================================== +Buffer Sharing and Synchronization (dma-buf) +============================================ The dma-buf subsystem provides the framework for sharing buffers for hardware (DMA) access across multiple device drivers and subsystems, and @@ -264,7 +264,7 @@ through memory management dependencies which userspace is unaware of, which randomly hangs workloads until the timeout kicks in. Workloads, which from userspace's perspective, do not contain a deadlock. In such a mixed fencing architecture there is no single entity with knowledge of all dependencies. -Thefore preventing such deadlocks from within the kernel is not possible. +Therefore preventing such deadlocks from within the kernel is not possible. The only solution to avoid dependencies loops is by not allowing indefinite fences in the kernel. This means: diff --git a/Documentation/driver-api/dmaengine/client.rst b/Documentation/driver-api/dmaengine/client.rst index bfd057b21a00..ecf139f73da4 100644 --- a/Documentation/driver-api/dmaengine/client.rst +++ b/Documentation/driver-api/dmaengine/client.rst @@ -175,7 +175,7 @@ The details of these operations are: driver can ask for the pointer, maximum size and the currently used size of the metadata and can directly update or read it. - Becasue the DMA driver manages the memory area containing the metadata, + Because the DMA driver manages the memory area containing the metadata, clients must make sure that they do not try to access or get the pointer after their transfer completion callback has run for the descriptor. If no completion callback has been defined for the transfer, then the diff --git a/Documentation/driver-api/dmaengine/dmatest.rst b/Documentation/driver-api/dmaengine/dmatest.rst index cf9859cd0b43..e2a63cefd783 100644 --- a/Documentation/driver-api/dmaengine/dmatest.rst +++ b/Documentation/driver-api/dmaengine/dmatest.rst @@ -89,7 +89,7 @@ The following command returns the state of the test. :: % cat /sys/module/dmatest/parameters/run -To wait for test completion userpace can poll 'run' until it is false, or use +To wait for test completion userspace can poll 'run' until it is false, or use the wait parameter. Specifying 'wait=1' when loading the module causes module initialization to pause until a test run has completed, while reading /sys/module/dmatest/parameters/wait waits for any running test to complete diff --git a/Documentation/driver-api/gpio/legacy.rst b/Documentation/driver-api/gpio/legacy.rst index e17910cc3271..a0559d93efd1 100644 --- a/Documentation/driver-api/gpio/legacy.rst +++ b/Documentation/driver-api/gpio/legacy.rst @@ -387,9 +387,6 @@ map between them using calls like:: /* map GPIO numbers to IRQ numbers */ int gpio_to_irq(unsigned gpio); - /* map IRQ numbers to GPIO numbers (avoid using this) */ - int irq_to_gpio(unsigned irq); - Those return either the corresponding number in the other namespace, or else a negative errno code if the mapping can't be done. (For example, some GPIOs can't be used as IRQs.) It is an unchecked error to use a GPIO @@ -405,11 +402,6 @@ devices, by the board-specific initialization code. Note that IRQ trigger options are part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as are system wakeup capabilities. -Non-error values returned from irq_to_gpio() would most commonly be used -with gpio_get_value(), for example to initialize or update driver state -when the IRQ is edge-triggered. Note that some platforms don't support -this reverse mapping, so you should avoid using it. - Emulating Open Drain Signals ---------------------------- @@ -735,10 +727,6 @@ requested using gpio_request():: /* reverse gpio_export() */ void gpio_unexport(); - /* create a sysfs link to an exported GPIO node */ - int gpio_export_link(struct device *dev, const char *name, - unsigned gpio) - After a kernel driver requests a GPIO, it may only be made available in the sysfs interface by gpio_export(). The driver can control whether the signal direction may change. This helps drivers prevent userspace code @@ -748,11 +736,6 @@ This explicit exporting can help with debugging (by making some kinds of experiments easier), or can provide an always-there interface that's suitable for documenting as part of a board support package. -After the GPIO has been exported, gpio_export_link() allows creating -symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can -use this to provide the interface under their own device in sysfs with -a descriptive name. - API Reference ============= diff --git a/Documentation/driver-api/hsi.rst b/Documentation/driver-api/hsi.rst index f9cec02b72a1..01b6bebfbd1a 100644 --- a/Documentation/driver-api/hsi.rst +++ b/Documentation/driver-api/hsi.rst @@ -4,7 +4,7 @@ High Speed Synchronous Serial Interface (HSI) Introduction --------------- -High Speed Syncronous Interface (HSI) is a fullduplex, low latency protocol, +High Speed Synchronous Interface (HSI) is a full duplex, low latency protocol, that is optimized for die-level interconnect between an Application Processor and a Baseband chipset. It has been specified by the MIPI alliance in 2003 and implemented by multiple vendors since then. @@ -52,7 +52,7 @@ hsi-char Device ------------------ Each port automatically registers a generic client driver called hsi_char, -which provides a charecter device for userspace representing the HSI port. +which provides a character device for userspace representing the HSI port. It can be used to communicate via HSI from userspace. Userspace may configure the hsi_char device using the following ioctl commands: diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index d3a58f77328e..7a2584ab63c4 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -1,6 +1,8 @@ -======================================== -The Linux driver implementer's API guide -======================================== +.. SPDX-License-Identifier: GPL-2.0 + +============================== +Driver implementer's API guide +============================== The kernel offers a wide variety of interfaces to support the development of device drivers. This document is an only somewhat organized collection diff --git a/Documentation/driver-api/io-mapping.rst b/Documentation/driver-api/io-mapping.rst index a0cfb15988df..7274204b0435 100644 --- a/Documentation/driver-api/io-mapping.rst +++ b/Documentation/driver-api/io-mapping.rst @@ -44,7 +44,7 @@ This _wc variant returns a write-combining map to the page and may only be used with mappings created by io_mapping_create_wc() Temporary mappings are only valid in the context of the caller. The mapping -is not guaranteed to be globaly visible. +is not guaranteed to be globally visible. io_mapping_map_local_wc() has a side effect on X86 32bit as it disables migration to make the mapping code work. No caller can rely on this side @@ -78,7 +78,7 @@ variant, although this may be significantly slower:: unsigned long offset) This works like io_mapping_map_atomic/local_wc() except it has no side -effects and the pointer is globaly visible. +effects and the pointer is globally visible. The mappings are released with:: diff --git a/Documentation/driver-api/md/md-cluster.rst b/Documentation/driver-api/md/md-cluster.rst index 96eb52cec7eb..e93f35e0e157 100644 --- a/Documentation/driver-api/md/md-cluster.rst +++ b/Documentation/driver-api/md/md-cluster.rst @@ -65,7 +65,7 @@ There are three groups of locks for managing the device: 2.3 new-device management ------------------------- - A single lock: "no-new-dev" is used to co-ordinate the addition of + A single lock: "no-new-dev" is used to coordinate the addition of new devices - this must be synchronized across the array. Normally all nodes hold a concurrent-read lock on this device. diff --git a/Documentation/driver-api/md/raid5-cache.rst b/Documentation/driver-api/md/raid5-cache.rst index d7a15f44a7c3..5f947cbc2e78 100644 --- a/Documentation/driver-api/md/raid5-cache.rst +++ b/Documentation/driver-api/md/raid5-cache.rst @@ -81,7 +81,7 @@ The write-through and write-back cache use the same disk format. The cache disk is organized as a simple write log. The log consists of 'meta data' and 'data' pairs. The meta data describes the data. It also includes checksum and sequence ID for recovery identification. Data can be IO data and parity data. Data is -checksumed too. The checksum is stored in the meta data ahead of the data. The +checksummed too. The checksum is stored in the meta data ahead of the data. The checksum is an optimization because MD can write meta and data freely without worry about the order. MD superblock has a field pointed to the valid meta data of log head. diff --git a/Documentation/driver-api/media/drivers/davinci-vpbe-devel.rst b/Documentation/driver-api/media/drivers/davinci-vpbe-devel.rst deleted file mode 100644 index 4e87bdbc7ae4..000000000000 --- a/Documentation/driver-api/media/drivers/davinci-vpbe-devel.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -The VPBE V4L2 driver design -=========================== - -File partitioning ------------------ - - V4L2 display device driver - drivers/media/platform/ti/davinci/vpbe_display.c - drivers/media/platform/ti/davinci/vpbe_display.h - - VPBE display controller - drivers/media/platform/ti/davinci/vpbe.c - drivers/media/platform/ti/davinci/vpbe.h - - VPBE venc sub device driver - drivers/media/platform/ti/davinci/vpbe_venc.c - drivers/media/platform/ti/davinci/vpbe_venc.h - drivers/media/platform/ti/davinci/vpbe_venc_regs.h - - VPBE osd driver - drivers/media/platform/ti/davinci/vpbe_osd.c - drivers/media/platform/ti/davinci/vpbe_osd.h - drivers/media/platform/ti/davinci/vpbe_osd_regs.h - -To be done ----------- - -vpbe display controller - - Add support for external encoders. - - add support for selecting external encoder as default at probe time. - -vpbe venc sub device - - add timings for supporting ths8200 - - add support for LogicPD LCD. - -FB drivers - - Add support for fbdev drivers.- Ready and part of subsequent patches. diff --git a/Documentation/driver-api/media/drivers/index.rst b/Documentation/driver-api/media/drivers/index.rst index 32406490557c..3c17d48f83c0 100644 --- a/Documentation/driver-api/media/drivers/index.rst +++ b/Documentation/driver-api/media/drivers/index.rst @@ -16,7 +16,6 @@ Video4Linux (V4L) drivers cpia2_devel cx2341x-devel cx88-devel - davinci-vpbe-devel fimc-devel pvrusb2 pxa_camera diff --git a/Documentation/driver-api/media/drivers/vidtv.rst b/Documentation/driver-api/media/drivers/vidtv.rst index 673bdff919ea..54f269f478d3 100644 --- a/Documentation/driver-api/media/drivers/vidtv.rst +++ b/Documentation/driver-api/media/drivers/vidtv.rst @@ -28,7 +28,7 @@ Currently, it consists of: takes parameters at initialization that will dictate how the simulation behaves. -- Code reponsible for encoding a valid MPEG Transport Stream, which is then +- Code responsible for encoding a valid MPEG Transport Stream, which is then passed to the bridge driver. This fake stream contains some hardcoded content. For now, we have a single, audio-only channel containing a single MPEG Elementary Stream, which in turn contains a SMPTE 302m encoded sine-wave. diff --git a/Documentation/driver-api/media/dtv-demux.rst b/Documentation/driver-api/media/dtv-demux.rst index c0ae5dec5328..144124142622 100644 --- a/Documentation/driver-api/media/dtv-demux.rst +++ b/Documentation/driver-api/media/dtv-demux.rst @@ -24,7 +24,7 @@ unless this is fixed in the HW platform. The demux kABI only controls front-ends regarding to their connections with demuxes; the kABI used to set the other front-end parameters, such as -tuning, are devined via the Digital TV Frontend kABI. +tuning, are defined via the Digital TV Frontend kABI. The functions that implement the abstract interface demux should be defined static or module private and registered to the Demux core for external diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst index 6f8d79926aa5..8797037c4e2e 100644 --- a/Documentation/driver-api/media/v4l2-subdev.rst +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -321,7 +321,7 @@ response to video node operations. This hides the complexity of the underlying hardware from applications. For complex devices, finer-grained control of the device than what the video nodes offer may be required. In those cases, bridge drivers that implement :ref:`the media controller API <media_controller>` may -opt for making the subdevice operations directly accessible from userpace. +opt for making the subdevice operations directly accessible from userspace. Device nodes named ``v4l-subdev``\ *X* can be created in ``/dev`` to access sub-devices directly. If a sub-device supports direct userspace configuration @@ -574,7 +574,7 @@ issues with subdevice drivers that let the V4L2 core manage the active state, as they expect to receive the appropriate state as a parameter. To help the conversion of subdevice drivers to a managed active state without having to convert all callers at the same time, an additional wrapper layer has been -added to v4l2_subdev_call(), which handles the NULL case by geting and locking +added to v4l2_subdev_call(), which handles the NULL case by getting and locking the callee's active state with :c:func:`v4l2_subdev_lock_and_get_active_state()`, and unlocking the state after the call. diff --git a/Documentation/driver-api/mei/nfc.rst b/Documentation/driver-api/mei/nfc.rst index b5b6fc96f85e..8fe8664c28cc 100644 --- a/Documentation/driver-api/mei/nfc.rst +++ b/Documentation/driver-api/mei/nfc.rst @@ -3,7 +3,7 @@ MEI NFC ------- -Some Intel 8 and 9 Serieses chipsets supports NFC devices connected behind +Some Intel 8 and 9 Series chipsets support NFC devices connected behind the Intel Management Engine controller. MEI client bus exposes the NFC chips as NFC phy devices and enables binding with Microread and NXP PN544 NFC device driver from the Linux NFC diff --git a/Documentation/driver-api/nfc/nfc-hci.rst b/Documentation/driver-api/nfc/nfc-hci.rst index f10fe53aa9fe..486aa647c456 100644 --- a/Documentation/driver-api/nfc/nfc-hci.rst +++ b/Documentation/driver-api/nfc/nfc-hci.rst @@ -150,7 +150,7 @@ LLC Communication between the CPU and the chip often requires some link layer protocol. Those are isolated as modules managed by the HCI layer. There are -currently two modules : nop (raw transfert) and shdlc. +currently two modules : nop (raw transfer) and shdlc. A new llc must implement the following functions:: struct nfc_llc_ops { diff --git a/Documentation/driver-api/nvdimm/nvdimm.rst b/Documentation/driver-api/nvdimm/nvdimm.rst index be8587a558e1..ca16b5acbf30 100644 --- a/Documentation/driver-api/nvdimm/nvdimm.rst +++ b/Documentation/driver-api/nvdimm/nvdimm.rst @@ -82,7 +82,7 @@ LABEL: Metadata stored on a DIMM device that partitions and identifies (persistently names) capacity allocated to different PMEM namespaces. It also indicates whether an address abstraction like a BTT is applied to - the namepsace. Note that traditional partition tables, GPT/MBR, are + the namespace. Note that traditional partition tables, GPT/MBR, are layered on top of a PMEM namespace, or an address abstraction like BTT if present, but partition support is deprecated going forward. diff --git a/Documentation/driver-api/nvdimm/security.rst b/Documentation/driver-api/nvdimm/security.rst index 7aab71524116..eb3d35e6a95c 100644 --- a/Documentation/driver-api/nvdimm/security.rst +++ b/Documentation/driver-api/nvdimm/security.rst @@ -83,7 +83,7 @@ passed in. 6. Freeze --------- The freeze operation does not require any keys. The security config can be -frozen by a user with root privelege. +frozen by a user with root privilege. 7. Disable ---------- diff --git a/Documentation/driver-api/pin-control.rst b/Documentation/driver-api/pin-control.rst index 0022e930e93e..4639912dc9cc 100644 --- a/Documentation/driver-api/pin-control.rst +++ b/Documentation/driver-api/pin-control.rst @@ -11,20 +11,18 @@ This subsystem deals with: - Multiplexing of pins, pads, fingers (etc) see below for details - Configuration of pins, pads, fingers (etc), such as software-controlled - biasing and driving mode specific pins, such as pull-up/down, open drain, + biasing and driving mode specific pins, such as pull-up, pull-down, open drain, load capacitance etc. Top-level interface =================== -Definition of PIN CONTROLLER: +Definitions: -- A pin controller is a piece of hardware, usually a set of registers, that +- A PIN CONTROLLER is a piece of hardware, usually a set of registers, that can control PINs. It may be able to multiplex, bias, set load capacitance, set drive strength, etc. for individual pins or groups of pins. -Definition of PIN: - - PINS are equal to pads, fingers, balls or whatever packaging input or output line you want to control and these are denoted by unsigned integers in the range 0..maxpin. This numberspace is local to each PIN CONTROLLER, so @@ -57,7 +55,9 @@ Here is an example of a PGA (Pin Grid Array) chip seen from underneath:: 1 o o o o o o o o To register a pin controller and name all the pins on this package we can do -this in our driver:: +this in our driver: + +.. code-block:: c #include <linux/pinctrl/pinctrl.h> @@ -78,14 +78,13 @@ this in our driver:: .owner = THIS_MODULE, }; - int __init foo_probe(void) + int __init foo_init(void) { int error; struct pinctrl_dev *pctl; - error = pinctrl_register_and_init(&foo_desc, <PARENT>, - NULL, &pctl); + error = pinctrl_register_and_init(&foo_desc, <PARENT>, NULL, &pctl); if (error) return error; @@ -95,20 +94,20 @@ this in our driver:: To enable the pinctrl subsystem and the subgroups for PINMUX and PINCONF and selected drivers, you need to select them from your machine's Kconfig entry, since these are so tightly integrated with the machines they are used on. -See for example arch/arm/mach-ux500/Kconfig for an example. +See ``arch/arm/mach-ux500/Kconfig`` for an example. Pins usually have fancier names than this. You can find these in the datasheet for your chip. Notice that the core pinctrl.h file provides a fancy macro -called PINCTRL_PIN() to create the struct entries. As you can see I enumerated -the pins from 0 in the upper left corner to 63 in the lower right corner. +called ``PINCTRL_PIN()`` to create the struct entries. As you can see the pins are +enumerated from 0 in the upper left corner to 63 in the lower right corner. This enumeration was arbitrarily chosen, in practice you need to think through your numbering system so that it matches the layout of registers and such things in your driver, or the code may become complicated. You must also consider matching of offsets to the GPIO ranges that may be handled by the pin controller. -For a padring with 467 pads, as opposed to actual pins, I used an enumeration -like this, walking around the edge of the chip, which seems to be industry +For a padding with 467 pads, as opposed to actual pins, the enumeration will +be like this, walking around the edge of the chip, which seems to be industry standard too (all these pads had names, too):: @@ -132,50 +131,38 @@ on { 0, 8, 16, 24 }, and a group of pins dealing with an I2C interface on pins on { 24, 25 }. These two groups are presented to the pin control subsystem by implementing -some generic pinctrl_ops like this:: +some generic ``pinctrl_ops`` like this: - #include <linux/pinctrl/pinctrl.h> +.. code-block:: c - struct foo_group { - const char *name; - const unsigned int *pins; - const unsigned num_pins; - }; + #include <linux/pinctrl/pinctrl.h> static const unsigned int spi0_pins[] = { 0, 8, 16, 24 }; static const unsigned int i2c0_pins[] = { 24, 25 }; - static const struct foo_group foo_groups[] = { - { - .name = "spi0_grp", - .pins = spi0_pins, - .num_pins = ARRAY_SIZE(spi0_pins), - }, - { - .name = "i2c0_grp", - .pins = i2c0_pins, - .num_pins = ARRAY_SIZE(i2c0_pins), - }, + static const struct pingroup foo_groups[] = { + PINCTRL_PINGROUP("spi0_grp", spi0_pins, ARRAY_SIZE(spi0_pins)), + PINCTRL_PINGROUP("i2c0_grp", i2c0_pins, ARRAY_SIZE(i2c0_pins)), }; - static int foo_get_groups_count(struct pinctrl_dev *pctldev) { return ARRAY_SIZE(foo_groups); } static const char *foo_get_group_name(struct pinctrl_dev *pctldev, - unsigned selector) + unsigned int selector) { return foo_groups[selector].name; } - static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector, - const unsigned **pins, - unsigned *num_pins) + static int foo_get_group_pins(struct pinctrl_dev *pctldev, + unsigned int selector, + const unsigned int **pins, + unsigned int *npins) { - *pins = (unsigned *) foo_groups[selector].pins; - *num_pins = foo_groups[selector].num_pins; + *pins = foo_groups[selector].pins; + *npins = foo_groups[selector].npins; return 0; } @@ -185,13 +172,12 @@ some generic pinctrl_ops like this:: .get_group_pins = foo_get_group_pins, }; - static struct pinctrl_desc foo_desc = { - ... - .pctlops = &foo_pctrl_ops, + ... + .pctlops = &foo_pctrl_ops, }; -The pin control subsystem will call the .get_groups_count() function to +The pin control subsystem will call the ``.get_groups_count()`` function to determine the total number of legal selectors, then it will call the other functions to retrieve the name and pins of the group. Maintaining the data structure of the groups is up to the driver, this is just a simple example - in practice you @@ -204,59 +190,62 @@ Pin configuration Pins can sometimes be software-configured in various ways, mostly related to their electronic properties when used as inputs or outputs. For example you -may be able to make an output pin high impedance, or "tristate" meaning it is +may be able to make an output pin high impedance (Hi-Z), or "tristate" meaning it is effectively disconnected. You may be able to connect an input pin to VDD or GND using a certain resistor value - pull up and pull down - so that the pin has a stable value when nothing is driving the rail it is connected to, or when it's unconnected. Pin configuration can be programmed by adding configuration entries into the -mapping table; see section "Board/machine configuration" below. +mapping table; see section `Board/machine configuration`_ below. The format and meaning of the configuration parameter, PLATFORM_X_PULL_UP above, is entirely defined by the pin controller driver. The pin configuration driver implements callbacks for changing pin -configuration in the pin controller ops like this:: +configuration in the pin controller ops like this: + +.. code-block:: c - #include <linux/pinctrl/pinctrl.h> #include <linux/pinctrl/pinconf.h> + #include <linux/pinctrl/pinctrl.h> + #include "platform_x_pindefs.h" static int foo_pin_config_get(struct pinctrl_dev *pctldev, - unsigned offset, - unsigned long *config) + unsigned int offset, + unsigned long *config) { struct my_conftype conf; - ... Find setting for pin @ offset ... + /* ... Find setting for pin @ offset ... */ *config = (unsigned long) conf; } static int foo_pin_config_set(struct pinctrl_dev *pctldev, - unsigned offset, - unsigned long config) + unsigned int offset, + unsigned long config) { struct my_conftype *conf = (struct my_conftype *) config; switch (conf) { case PLATFORM_X_PULL_UP: ... - } + break; } } - static int foo_pin_config_group_get (struct pinctrl_dev *pctldev, - unsigned selector, - unsigned long *config) + static int foo_pin_config_group_get(struct pinctrl_dev *pctldev, + unsigned selector, + unsigned long *config) { ... } - static int foo_pin_config_group_set (struct pinctrl_dev *pctldev, - unsigned selector, - unsigned long config) + static int foo_pin_config_group_set(struct pinctrl_dev *pctldev, + unsigned selector, + unsigned long config) { ... } @@ -281,8 +270,8 @@ The GPIO drivers may want to perform operations of various types on the same physical pins that are also registered as pin controller pins. First and foremost, the two subsystems can be used as completely orthogonal, -see the section named "pin control requests from drivers" and -"drivers needing both pin control and GPIOs" below for details. But in some +see the section named `Pin control requests from drivers`_ and +`Drivers needing both pin control and GPIOs`_ below for details. But in some situations a cross-subsystem mapping between pins and GPIOs is needed. Since the pin controller subsystem has its pinspace local to the pin controller @@ -291,7 +280,13 @@ controller handles control of a certain GPIO pin. Since a single pin controller may be muxing several GPIO ranges (typically SoCs that have one set of pins, but internally several GPIO silicon blocks, each modelled as a struct gpio_chip) any number of GPIO ranges can be added to a pin controller instance -like this:: +like this: + +.. code-block:: c + + #include <linux/gpio/driver.h> + + #include <linux/pinctrl/pinctrl.h> struct gpio_chip chip_a; struct gpio_chip chip_b; @@ -302,7 +297,7 @@ like this:: .base = 32, .pin_base = 32, .npins = 16, - .gc = &chip_a; + .gc = &chip_a, }; static struct pinctrl_gpio_range gpio_range_b = { @@ -314,16 +309,18 @@ like this:: .gc = &chip_b; }; + int __init foo_init(void) { struct pinctrl_dev *pctl; ... pinctrl_add_gpio_range(pctl, &gpio_range_a); pinctrl_add_gpio_range(pctl, &gpio_range_b); + ... } So this complex system has one pin controller handling two different GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and -"chip b" have different .pin_base, which means a start pin number of the +"chip b" have different ``pin_base``, which means a start pin number of the GPIO range. The GPIO range of "chip a" starts from the GPIO base of 32 and actual @@ -331,7 +328,7 @@ pin range also starts from 32. However "chip b" has different starting offset for the GPIO range and pin range. The GPIO range of "chip b" starts from GPIO number 48, while the pin range of "chip b" starts from 64. -We can convert a gpio number to actual pin number using this "pin_base". +We can convert a gpio number to actual pin number using this ``pin_base``. They are mapped in the global GPIO pin space at: chip a: @@ -343,9 +340,11 @@ chip b: The above examples assume the mapping between the GPIOs and pins is linear. If the mapping is sparse or haphazard, an array of arbitrary pin -numbers can be encoded in the range like this:: +numbers can be encoded in the range like this: + +.. code-block:: c - static const unsigned range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 }; + static const unsigned int range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 }; static struct pinctrl_gpio_range gpio_range = { .name = "chip", @@ -353,16 +352,17 @@ numbers can be encoded in the range like this:: .base = 32, .pins = &range_pins, .npins = ARRAY_SIZE(range_pins), - .gc = &chip; + .gc = &chip, }; -In this case the pin_base property will be ignored. If the name of a pin +In this case the ``pin_base`` property will be ignored. If the name of a pin group is known, the pins and npins elements of the above structure can be -initialised using the function pinctrl_get_group_pins(), e.g. for pin -group "foo":: +initialised using the function ``pinctrl_get_group_pins()``, e.g. for pin +group "foo": - pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins, - &gpio_range.npins); +.. code-block:: c + + pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins, &gpio_range.npins); When GPIO-specific functions in the pin control subsystem are called, these ranges will be used to look up the appropriate pin controller by inspecting @@ -378,8 +378,8 @@ will get a pin number into its handled number range. Further it is also passed the range ID value, so that the pin controller knows which range it should deal with. -Calling pinctrl_add_gpio_range from pinctrl driver is DEPRECATED. Please see -section 2.1 of Documentation/devicetree/bindings/gpio/gpio.txt on how to bind +Calling ``pinctrl_add_gpio_range()`` from pinctrl driver is DEPRECATED. Please see +section 2.1 of ``Documentation/devicetree/bindings/gpio/gpio.txt`` on how to bind pinctrl and gpio drivers. @@ -466,10 +466,10 @@ in your machine configuration. It is inspired by the clk, GPIO and regulator subsystems, so devices will request their mux setting, but it's also possible to request a single pin for e.g. GPIO. -Definitions: +The conventions are: - FUNCTIONS can be switched in and out by a driver residing with the pin - control subsystem in the drivers/pinctrl/* directory of the kernel. The + control subsystem in the ``drivers/pinctrl`` directory of the kernel. The pin control driver knows the possible functions. In the example above you can identify three pinmux functions, one for spi, one for i2c and one for mmc. @@ -515,11 +515,13 @@ Definitions: In the example case we can define that this particular machine shall use device spi0 with pinmux function fspi0 group gspi0 and i2c0 on function fi2c0 group gi2c0, on the primary pin controller, we get mappings - like these:: + like these: + + .. code-block:: c { {"map-spi0", spi0, pinctrl0, fspi0, gspi0}, - {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0} + {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0}, } Every map must be assigned a state name, pin controller, device and @@ -569,80 +571,51 @@ is possible to perform the requested mux setting, poke the hardware so that this happens. Pinmux drivers are required to supply a few callback functions, some are -optional. Usually the set_mux() function is implemented, writing values into +optional. Usually the ``.set_mux()`` function is implemented, writing values into some certain registers to activate a certain mux setting for a certain pin. -A simple driver for the above example will work by setting bits 0, 1, 2, 3 or 4 +A simple driver for the above example will work by setting bits 0, 1, 2, 3, 4, or 5 into some register named MUX to select a certain function with a certain -group of pins would work something like this:: +group of pins would work something like this: + +.. code-block:: c #include <linux/pinctrl/pinctrl.h> #include <linux/pinctrl/pinmux.h> - struct foo_group { - const char *name; - const unsigned int *pins; - const unsigned num_pins; - }; - - static const unsigned spi0_0_pins[] = { 0, 8, 16, 24 }; - static const unsigned spi0_1_pins[] = { 38, 46, 54, 62 }; - static const unsigned i2c0_pins[] = { 24, 25 }; - static const unsigned mmc0_1_pins[] = { 56, 57 }; - static const unsigned mmc0_2_pins[] = { 58, 59 }; - static const unsigned mmc0_3_pins[] = { 60, 61, 62, 63 }; - - static const struct foo_group foo_groups[] = { - { - .name = "spi0_0_grp", - .pins = spi0_0_pins, - .num_pins = ARRAY_SIZE(spi0_0_pins), - }, - { - .name = "spi0_1_grp", - .pins = spi0_1_pins, - .num_pins = ARRAY_SIZE(spi0_1_pins), - }, - { - .name = "i2c0_grp", - .pins = i2c0_pins, - .num_pins = ARRAY_SIZE(i2c0_pins), - }, - { - .name = "mmc0_1_grp", - .pins = mmc0_1_pins, - .num_pins = ARRAY_SIZE(mmc0_1_pins), - }, - { - .name = "mmc0_2_grp", - .pins = mmc0_2_pins, - .num_pins = ARRAY_SIZE(mmc0_2_pins), - }, - { - .name = "mmc0_3_grp", - .pins = mmc0_3_pins, - .num_pins = ARRAY_SIZE(mmc0_3_pins), - }, + static const unsigned int spi0_0_pins[] = { 0, 8, 16, 24 }; + static const unsigned int spi0_1_pins[] = { 38, 46, 54, 62 }; + static const unsigned int i2c0_pins[] = { 24, 25 }; + static const unsigned int mmc0_1_pins[] = { 56, 57 }; + static const unsigned int mmc0_2_pins[] = { 58, 59 }; + static const unsigned int mmc0_3_pins[] = { 60, 61, 62, 63 }; + + static const struct pingroup foo_groups[] = { + PINCTRL_PINGROUP("spi0_0_grp", spi0_0_pins, ARRAY_SIZE(spi0_0_pins)), + PINCTRL_PINGROUP("spi0_1_grp", spi0_1_pins, ARRAY_SIZE(spi0_1_pins)), + PINCTRL_PINGROUP("i2c0_grp", i2c0_pins, ARRAY_SIZE(i2c0_pins)), + PINCTRL_PINGROUP("mmc0_1_grp", mmc0_1_pins, ARRAY_SIZE(mmc0_1_pins)), + PINCTRL_PINGROUP("mmc0_2_grp", mmc0_2_pins, ARRAY_SIZE(mmc0_2_pins)), + PINCTRL_PINGROUP("mmc0_3_grp", mmc0_3_pins, ARRAY_SIZE(mmc0_3_pins)), }; - static int foo_get_groups_count(struct pinctrl_dev *pctldev) { return ARRAY_SIZE(foo_groups); } static const char *foo_get_group_name(struct pinctrl_dev *pctldev, - unsigned selector) + unsigned int selector) { return foo_groups[selector].name; } - static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector, - const unsigned ** pins, - unsigned * num_pins) + static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned int selector, + const unsigned int **pins, + unsigned int *npins) { - *pins = (unsigned *) foo_groups[selector].pins; - *num_pins = foo_groups[selector].num_pins; + *pins = foo_groups[selector].pins; + *npins = foo_groups[selector].npins; return 0; } @@ -652,33 +625,14 @@ group of pins would work something like this:: .get_group_pins = foo_get_group_pins, }; - struct foo_pmx_func { - const char *name; - const char * const *groups; - const unsigned num_groups; - }; - static const char * const spi0_groups[] = { "spi0_0_grp", "spi0_1_grp" }; static const char * const i2c0_groups[] = { "i2c0_grp" }; - static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp", - "mmc0_3_grp" }; + static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp", "mmc0_3_grp" }; - static const struct foo_pmx_func foo_functions[] = { - { - .name = "spi0", - .groups = spi0_groups, - .num_groups = ARRAY_SIZE(spi0_groups), - }, - { - .name = "i2c0", - .groups = i2c0_groups, - .num_groups = ARRAY_SIZE(i2c0_groups), - }, - { - .name = "mmc0", - .groups = mmc0_groups, - .num_groups = ARRAY_SIZE(mmc0_groups), - }, + static const struct pinfunction foo_functions[] = { + PINCTRL_PINFUNCTION("spi0", spi0_groups, ARRAY_SIZE(spi0_groups)), + PINCTRL_PINFUNCTION("i2c0", i2c0_groups, ARRAY_SIZE(i2c0_groups)), + PINCTRL_PINFUNCTION("mmc0", mmc0_groups, ARRAY_SIZE(mmc0_groups)), }; static int foo_get_functions_count(struct pinctrl_dev *pctldev) @@ -686,26 +640,26 @@ group of pins would work something like this:: return ARRAY_SIZE(foo_functions); } - static const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector) + static const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned int selector) { return foo_functions[selector].name; } - static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector, - const char * const **groups, - unsigned * const num_groups) + static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned int selector, + const char * const **groups, + unsigned int * const ngroups) { *groups = foo_functions[selector].groups; - *num_groups = foo_functions[selector].num_groups; + *ngroups = foo_functions[selector].ngroups; return 0; } - static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned selector, - unsigned group) + static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned int selector, + unsigned int group) { - u8 regbit = (1 << selector + group); + u8 regbit = BIT(group); - writeb((readb(MUX)|regbit), MUX); + writeb((readb(MUX) | regbit), MUX); return 0; } @@ -724,16 +678,17 @@ group of pins would work something like this:: .pmxops = &foo_pmxops, }; -In the example activating muxing 0 and 1 at the same time setting bits -0 and 1, uses one pin in common so they would collide. +In the example activating muxing 0 and 2 at the same time setting bits +0 and 2, uses pin 24 in common so they would collide. All the same for +the muxes 1 and 5, which have pin 62 in common. The beauty of the pinmux subsystem is that since it keeps track of all pins and who is using them, it will already have denied an impossible request like that, so the driver does not need to worry about such things - when it gets a selector passed in, the pinmux subsystem makes sure no other device or GPIO assignment is already using the selected -pins. Thus bits 0 and 1 in the control register will never be set at the -same time. +pins. Thus bits 0 and 2, or 1 and 5 in the control register will never +be set at the same time. All the above functions are mandatory to implement for a pinmux driver. @@ -742,18 +697,18 @@ Pin control interaction with the GPIO subsystem =============================================== Note that the following implies that the use case is to use a certain pin -from the Linux kernel using the API in <linux/gpio.h> with gpio_request() +from the Linux kernel using the API in ``<linux/gpio/consumer.h>`` with gpiod_get() and similar functions. There are cases where you may be using something that your datasheet calls "GPIO mode", but actually is just an electrical configuration for a certain device. See the section below named -"GPIO mode pitfalls" for more details on this scenario. +`GPIO mode pitfalls`_ for more details on this scenario. -The public pinmux API contains two functions named pinctrl_gpio_request() -and pinctrl_gpio_free(). These two functions shall *ONLY* be called from -gpiolib-based drivers as part of their gpio_request() and -gpio_free() semantics. Likewise the pinctrl_gpio_direction_[input|output] -shall only be called from within respective gpio_direction_[input|output] -gpiolib implementation. +The public pinmux API contains two functions named ``pinctrl_gpio_request()`` +and ``pinctrl_gpio_free()``. These two functions shall *ONLY* be called from +gpiolib-based drivers as part of their ``.request()`` and ``.free()`` semantics. +Likewise the ``pinctrl_gpio_direction_input()`` / ``pinctrl_gpio_direction_output()`` +shall only be called from within respective ``.direction_input()`` / +``.direction_output()`` gpiolib implementation. NOTE that platforms and individual drivers shall *NOT* request GPIO pins to be controlled e.g. muxed in. Instead, implement a proper gpiolib driver and have @@ -767,8 +722,8 @@ In this case, the function array would become 64 entries for each GPIO setting and then the device functions. For this reason there are two functions a pin control driver can implement -to enable only GPIO on an individual pin: .gpio_request_enable() and -.gpio_disable_free(). +to enable only GPIO on an individual pin: ``.gpio_request_enable()`` and +``.gpio_disable_free()``. This function will pass in the affected GPIO range identified by the pin controller core, so you know which GPIO pins are being affected by the request @@ -776,12 +731,12 @@ operation. If your driver needs to have an indication from the framework of whether the GPIO pin shall be used for input or output you can implement the -.gpio_set_direction() function. As described this shall be called from the +``.gpio_set_direction()`` function. As described this shall be called from the gpiolib driver and the affected GPIO range, pin offset and desired direction will be passed along to this function. Alternatively to using these special functions, it is fully allowed to use -named functions for each GPIO pin, the pinctrl_gpio_request() will attempt to +named functions for each GPIO pin, the ``pinctrl_gpio_request()`` will attempt to obtain the function "gpioN" where "N" is the global GPIO pin number if no special GPIO-handler is registered. @@ -794,7 +749,7 @@ is taken to mean different things than what the kernel does, the developer may be confused by a datasheet talking about a pin being possible to set into "GPIO mode". It appears that what hardware engineers mean with "GPIO mode" is not necessarily the use case that is implied in the kernel -interface <linux/gpio.h>: a pin that you grab from kernel code and then +interface ``<linux/gpio/consumer.h>``: a pin that you grab from kernel code and then either listen for input or drive high/low to assert/deassert some external line. @@ -805,9 +760,10 @@ for a device. The GPIO portions of a pin and its relation to a certain pin controller configuration and muxing logic can be constructed in several ways. Here -are two examples:: +are two examples. + +Example **(A)**:: - (A) pin config logic regs | +- SPI @@ -836,9 +792,7 @@ simultaneous access to the same pin from GPIO and pin multiplexing consumers on hardware of this type. The pinctrl driver should set this flag accordingly. -:: - - (B) +Example **(B)**:: pin config logic regs @@ -882,7 +836,7 @@ hardware and shall be put into different subsystems: Depending on the exact HW register design, some functions exposed by the GPIO subsystem may call into the pinctrl subsystem in order to -co-ordinate register settings across HW modules. In particular, this may +coordinate register settings across HW modules. In particular, this may be needed for HW with separate GPIO and pin controller HW modules, where e.g. GPIO direction is determined by a register in the pin controller HW module rather than the GPIO HW module. @@ -899,14 +853,14 @@ If you make a 1-to-1 map to the GPIO subsystem for this pin, you may start to think that you need to come up with something really complex, that the pin shall be used for UART TX and GPIO at the same time, that you will grab a pin control handle and set it to a certain state to enable UART TX to be -muxed in, then twist it over to GPIO mode and use gpio_direction_output() +muxed in, then twist it over to GPIO mode and use gpiod_direction_output() to drive it low during sleep, then mux it over to UART TX again when you -wake up and maybe even gpio_request/gpio_free as part of this cycle. This +wake up and maybe even gpiod_get() / gpiod_put() as part of this cycle. This all gets very complicated. The solution is to not think that what the datasheet calls "GPIO mode" -has to be handled by the <linux/gpio.h> interface. Instead view this as -a certain pin config setting. Look in e.g. <linux/pinctrl/pinconf-generic.h> +has to be handled by the ``<linux/gpio/consumer.h>`` interface. Instead view this as +a certain pin config setting. Look in e.g. ``<linux/pinctrl/pinconf-generic.h>`` and you find this in the documentation: PIN_CONFIG_OUTPUT: @@ -915,7 +869,9 @@ and you find this in the documentation: So it is perfectly possible to push a pin into "GPIO mode" and drive the line low as part of the usual pin control map. So for example your UART -driver may look like this:: +driver may look like this: + +.. code-block:: c #include <linux/pinctrl/consumer.h> @@ -928,13 +884,13 @@ driver may look like this:: /* Normal mode */ retval = pinctrl_select_state(pinctrl, pins_default); + /* Sleep mode */ retval = pinctrl_select_state(pinctrl, pins_sleep); And your machine configuration may look like this: --------------------------------------------------- -:: +.. code-block:: c static unsigned long uart_default_mode[] = { PIN_CONF_PACKED(PIN_CONFIG_DRIVE_PUSH_PULL, 0), @@ -946,16 +902,17 @@ And your machine configuration may look like this: static struct pinctrl_map pinmap[] __initdata = { PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo", - "u0_group", "u0"), + "u0_group", "u0"), PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo", - "UART_TX_PIN", uart_default_mode), + "UART_TX_PIN", uart_default_mode), PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo", - "u0_group", "gpio-mode"), + "u0_group", "gpio-mode"), PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo", - "UART_TX_PIN", uart_sleep_mode), + "UART_TX_PIN", uart_sleep_mode), }; - foo_init(void) { + foo_init(void) + { pinctrl_register_mappings(pinmap, ARRAY_SIZE(pinmap)); } @@ -995,7 +952,9 @@ part of this. A pin controller configuration for a machine looks pretty much like a simple regulator configuration, so for the example array above we want to enable i2c -and spi on the second function mapping:: +and spi on the second function mapping: + +.. code-block:: c #include <linux/pinctrl/machine.h> @@ -1030,13 +989,17 @@ must match a function provided by the pinmux driver handling this pin range. As you can see we may have several pin controllers on the system and thus we need to specify which one of them contains the functions we wish to map. -You register this pinmux mapping to the pinmux subsystem by simply:: +You register this pinmux mapping to the pinmux subsystem by simply: + +.. code-block:: c ret = pinctrl_register_mappings(mapping, ARRAY_SIZE(mapping)); Since the above construct is pretty common there is a helper macro to make it even more compact which assumes you want to use pinctrl-foo and position -0 for mapping, for example:: +0 for mapping, for example: + +.. code-block:: c static struct pinctrl_map mapping[] __initdata = { PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT, @@ -1046,7 +1009,9 @@ it even more compact which assumes you want to use pinctrl-foo and position The mapping table may also contain pin configuration entries. It's common for each pin/group to have a number of configuration entries that affect it, so the table entries for configuration reference an array of config parameters -and values. An example using the convenience macros is shown below:: +and values. An example using the convenience macros is shown below: + +.. code-block:: c static unsigned long i2c_grp_configs[] = { FOO_PIN_DRIVEN, @@ -1073,8 +1038,10 @@ Finally, some devices expect the mapping table to contain certain specific named states. When running on hardware that doesn't need any pin controller configuration, the mapping table must still contain those named states, in order to explicitly indicate that the states were provided and intended to -be empty. Table entry macro PIN_MAP_DUMMY_STATE serves the purpose of defining -a named state without causing any pin controller to be programmed:: +be empty. Table entry macro ``PIN_MAP_DUMMY_STATE()`` serves the purpose of defining +a named state without causing any pin controller to be programmed: + +.. code-block:: c static struct pinctrl_map mapping[] __initdata = { PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT), @@ -1085,7 +1052,9 @@ Complex mappings ================ As it is possible to map a function to different groups of pins an optional -.group can be specified like this:: +.group can be specified like this: + +.. code-block:: c ... { @@ -1107,13 +1076,15 @@ As it is possible to map a function to different groups of pins an optional ... This example mapping is used to switch between two positions for spi0 at -runtime, as described further below under the heading "Runtime pinmuxing". +runtime, as described further below under the heading `Runtime pinmuxing`_. Further it is possible for one named state to affect the muxing of several groups of pins, say for example in the mmc0 example above, where you can additively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all -three groups for a total of 2+2+4 = 8 pins (for an 8-bit MMC bus as is the -case), we define a mapping like this:: +three groups for a total of 2 + 2 + 4 = 8 pins (for an 8-bit MMC bus as is the +case), we define a mapping like this: + +.. code-block:: c ... { @@ -1167,13 +1138,17 @@ case), we define a mapping like this:: ... The result of grabbing this mapping from the device with something like -this (see next paragraph):: +this (see next paragraph): + +.. code-block:: c p = devm_pinctrl_get(dev); s = pinctrl_lookup_state(p, "8bit"); ret = pinctrl_select_state(p, s); -or more simply:: +or more simply: + +.. code-block:: c p = devm_pinctrl_get_select(dev, "8bit"); @@ -1188,7 +1163,7 @@ Pin control requests from drivers ================================= When a device driver is about to probe the device core will automatically -attempt to issue pinctrl_get_select_default() on these devices. +attempt to issue ``pinctrl_get_select_default()`` on these devices. This way driver writers do not need to add any of the boilerplate code of the type found below. However when doing fine-grained state selection and not using the "default" state, you may have to do some device driver @@ -1206,12 +1181,14 @@ some cases where a driver needs to e.g. switch between different mux mappings at runtime this is not possible. A typical case is if a driver needs to switch bias of pins from normal -operation and going to sleep, moving from the PINCTRL_STATE_DEFAULT to -PINCTRL_STATE_SLEEP at runtime, re-biasing or even re-muxing pins to save +operation and going to sleep, moving from the ``PINCTRL_STATE_DEFAULT`` to +``PINCTRL_STATE_SLEEP`` at runtime, re-biasing or even re-muxing pins to save current in sleep mode. A driver may request a certain control state to be activated, usually just the -default state like this:: +default state like this: + +.. code-block:: c #include <linux/pinctrl/consumer.h> @@ -1251,49 +1228,49 @@ arrangement on your bus. The semantics of the pinctrl APIs are: -- pinctrl_get() is called in process context to obtain a handle to all pinctrl +- ``pinctrl_get()`` is called in process context to obtain a handle to all pinctrl information for a given client device. It will allocate a struct from the kernel memory to hold the pinmux state. All mapping table parsing or similar slow operations take place within this API. -- devm_pinctrl_get() is a variant of pinctrl_get() that causes pinctrl_put() +- ``devm_pinctrl_get()`` is a variant of pinctrl_get() that causes ``pinctrl_put()`` to be called automatically on the retrieved pointer when the associated device is removed. It is recommended to use this function over plain - pinctrl_get(). + ``pinctrl_get()``. -- pinctrl_lookup_state() is called in process context to obtain a handle to a +- ``pinctrl_lookup_state()`` is called in process context to obtain a handle to a specific state for a client device. This operation may be slow, too. -- pinctrl_select_state() programs pin controller hardware according to the +- ``pinctrl_select_state()`` programs pin controller hardware according to the definition of the state as given by the mapping table. In theory, this is a fast-path operation, since it only involved blasting some register settings into hardware. However, note that some pin controllers may have their registers on a slow/IRQ-based bus, so client devices should not assume they - can call pinctrl_select_state() from non-blocking contexts. + can call ``pinctrl_select_state()`` from non-blocking contexts. -- pinctrl_put() frees all information associated with a pinctrl handle. +- ``pinctrl_put()`` frees all information associated with a pinctrl handle. -- devm_pinctrl_put() is a variant of pinctrl_put() that may be used to - explicitly destroy a pinctrl object returned by devm_pinctrl_get(). +- ``devm_pinctrl_put()`` is a variant of ``pinctrl_put()`` that may be used to + explicitly destroy a pinctrl object returned by ``devm_pinctrl_get()``. However, use of this function will be rare, due to the automatic cleanup that will occur even without calling it. - pinctrl_get() must be paired with a plain pinctrl_put(). - pinctrl_get() may not be paired with devm_pinctrl_put(). - devm_pinctrl_get() can optionally be paired with devm_pinctrl_put(). - devm_pinctrl_get() may not be paired with plain pinctrl_put(). + ``pinctrl_get()`` must be paired with a plain ``pinctrl_put()``. + ``pinctrl_get()`` may not be paired with ``devm_pinctrl_put()``. + ``devm_pinctrl_get()`` can optionally be paired with ``devm_pinctrl_put()``. + ``devm_pinctrl_get()`` may not be paired with plain ``pinctrl_put()``. Usually the pin control core handled the get/put pair and call out to the device drivers bookkeeping operations, like checking available functions and -the associated pins, whereas select_state pass on to the pin controller +the associated pins, whereas ``pinctrl_select_state()`` pass on to the pin controller driver which takes care of activating and/or deactivating the mux setting by quickly poking some registers. -The pins are allocated for your device when you issue the devm_pinctrl_get() +The pins are allocated for your device when you issue the ``devm_pinctrl_get()`` call, after this you should be able to see this in the debugfs listing of all pins. -NOTE: the pinctrl system will return -EPROBE_DEFER if it cannot find the +NOTE: the pinctrl system will return ``-EPROBE_DEFER`` if it cannot find the requested pinctrl handles, for example if the pinctrl driver has not yet registered. Thus make sure that the error path in your driver gracefully cleans up and is ready to retry the probing later in the startup process. @@ -1305,18 +1282,20 @@ Drivers needing both pin control and GPIOs Again, it is discouraged to let drivers lookup and select pin control states themselves, but again sometimes this is unavoidable. -So say that your driver is fetching its resources like this:: +So say that your driver is fetching its resources like this: + +.. code-block:: c #include <linux/pinctrl/consumer.h> - #include <linux/gpio.h> + #include <linux/gpio/consumer.h> struct pinctrl *pinctrl; - int gpio; + struct gpio_desc *gpio; pinctrl = devm_pinctrl_get_select_default(&dev); - gpio = devm_gpio_request(&dev, 14, "foo"); + gpio = devm_gpiod_get(&dev, "foo"); -Here we first request a certain pin state and then request GPIO 14 to be +Here we first request a certain pin state and then request GPIO "foo" to be used. If you're using the subsystems orthogonally like this, you should nominally always get your pinctrl handle and select the desired pinctrl state BEFORE requesting the GPIO. This is a semantic convention to avoid @@ -1331,9 +1310,9 @@ probing, nevertheless orthogonal to the GPIO subsystem. But there are also situations where it makes sense for the GPIO subsystem to communicate directly with the pinctrl subsystem, using the latter as a back-end. This is when the GPIO driver may call out to the functions -described in the section "Pin control interaction with the GPIO subsystem" +described in the section `Pin control interaction with the GPIO subsystem`_ above. This only involves per-pin multiplexing, and will be completely -hidden behind the gpio_*() function namespace. In this case, the driver +hidden behind the gpiod_*() function namespace. In this case, the driver need not interact with the pin control subsystem at all. If a pin control driver and a GPIO driver is dealing with the same pins @@ -1348,12 +1327,14 @@ System pin control hogging ========================== Pin control map entries can be hogged by the core when the pin controller -is registered. This means that the core will attempt to call pinctrl_get(), -lookup_state() and select_state() on it immediately after the pin control -device has been registered. +is registered. This means that the core will attempt to call ``pinctrl_get()``, +``pinctrl_lookup_state()`` and ``pinctrl_select_state()`` on it immediately after +the pin control device has been registered. This occurs for mapping table entries where the client device name is equal -to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT:: +to the pin controller device name, and the state name is ``PINCTRL_STATE_DEFAULT``: + +.. code-block:: c { .dev_name = "pinctrl-foo", @@ -1365,7 +1346,9 @@ to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT:: Since it may be common to request the core to hog a few always-applicable mux settings on the primary pin controller, there is a convenience macro for -this:: +this: + +.. code-block:: c PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */, "power_func") @@ -1385,7 +1368,9 @@ function, but with different named in the mapping as described under This snippet first initializes a state object for both groups (in foo_probe()), then muxes the function in the pins defined by group A, and finally muxes it in -on the pins defined by group B:: +on the pins defined by group B: + +.. code-block:: c #include <linux/pinctrl/consumer.h> @@ -1413,14 +1398,14 @@ on the pins defined by group B:: /* Enable on position A */ ret = pinctrl_select_state(p, s1); if (ret < 0) - ... + ... ... /* Enable on position B */ ret = pinctrl_select_state(p, s2); if (ret < 0) - ... + ... ... } @@ -1432,6 +1417,7 @@ can be used by different functions at different times on a running system. Debugfs files ============= + These files are created in ``/sys/kernel/debug/pinctrl``: - ``pinctrl-devices``: prints each pin controller device along with columns to @@ -1440,7 +1426,7 @@ These files are created in ``/sys/kernel/debug/pinctrl``: - ``pinctrl-handles``: prints each configured pin controller handle and the corresponding pinmux maps -- ``pinctrl-maps``: print all pinctrl maps +- ``pinctrl-maps``: prints all pinctrl maps A sub-directory is created inside of ``/sys/kernel/debug/pinctrl`` for each pin controller device containing these files: @@ -1448,20 +1434,22 @@ controller device containing these files: - ``pins``: prints a line for each pin registered on the pin controller. The pinctrl driver may add additional information such as register contents. -- ``gpio-ranges``: print ranges that map gpio lines to pins on the controller +- ``gpio-ranges``: prints ranges that map gpio lines to pins on the controller -- ``pingroups``: print all pin groups registered on the pin controller +- ``pingroups``: prints all pin groups registered on the pin controller -- ``pinconf-pins``: print pin config settings for each pin +- ``pinconf-pins``: prints pin config settings for each pin -- ``pinconf-groups``: print pin config settings per pin group +- ``pinconf-groups``: prints pin config settings per pin group -- ``pinmux-functions``: print each pin function along with the pin groups that +- ``pinmux-functions``: prints each pin function along with the pin groups that map to the pin function -- ``pinmux-pins``: iterate through all pins and print mux owner, gpio owner +- ``pinmux-pins``: iterates through all pins and prints mux owner, gpio owner and if the pin is a hog -- ``pinmux-select``: write to this file to activate a pin function for a group:: +- ``pinmux-select``: write to this file to activate a pin function for a group: + + .. code-block:: sh echo "<group-name function-name>" > pinmux-select diff --git a/Documentation/driver-api/pldmfw/index.rst b/Documentation/driver-api/pldmfw/index.rst index ad2c33ece30f..fd871b83f34f 100644 --- a/Documentation/driver-api/pldmfw/index.rst +++ b/Documentation/driver-api/pldmfw/index.rst @@ -20,7 +20,7 @@ Overview of the ``pldmfw`` library The ``pldmfw`` library is intended to be used by device drivers for implementing device flash update based on firmware files following the PLDM -firwmare file format. +firmware file format. It is implemented using an ops table that allows device drivers to provide the underlying device specific functionality. diff --git a/Documentation/driver-api/serial/driver.rst b/Documentation/driver-api/serial/driver.rst index 98d268555dcc..84b43061c11b 100644 --- a/Documentation/driver-api/serial/driver.rst +++ b/Documentation/driver-api/serial/driver.rst @@ -24,7 +24,7 @@ console support. Console Support --------------- -The serial core provides a few helper functions. This includes identifing +The serial core provides a few helper functions. This includes identifying the correct port structure (via uart_get_console()) and decoding command line arguments (uart_parse_options()). diff --git a/Documentation/driver-api/surface_aggregator/client.rst b/Documentation/driver-api/surface_aggregator/client.rst index 27f95abdbe99..e100ab0a24cc 100644 --- a/Documentation/driver-api/surface_aggregator/client.rst +++ b/Documentation/driver-api/surface_aggregator/client.rst @@ -19,7 +19,7 @@ .. |ssam_notifier_unregister| replace:: :c:func:`ssam_notifier_unregister` .. |ssam_device_notifier_register| replace:: :c:func:`ssam_device_notifier_register` .. |ssam_device_notifier_unregister| replace:: :c:func:`ssam_device_notifier_unregister` -.. |ssam_request_sync| replace:: :c:func:`ssam_request_sync` +.. |ssam_request_do_sync| replace:: :c:func:`ssam_request_do_sync` .. |ssam_event_mask| replace:: :c:type:`enum ssam_event_mask <ssam_event_mask>` @@ -191,7 +191,7 @@ data received from it is converted from little-endian to host endianness. * they do not correspond to an actual SAM/EC request. */ rqst.target_category = SSAM_SSH_TC_SAM; - rqst.target_id = 0x01; + rqst.target_id = SSAM_SSH_TID_SAM; rqst.command_id = 0x02; rqst.instance_id = 0x03; rqst.flags = SSAM_REQUEST_HAS_RESPONSE; @@ -209,12 +209,12 @@ data received from it is converted from little-endian to host endianness. * with the SSAM_REQUEST_HAS_RESPONSE flag set in the specification * above. */ - status = ssam_request_sync(ctrl, &rqst, &resp); + status = ssam_request_do_sync(ctrl, &rqst, &resp); /* * Alternatively use * - * ssam_request_sync_onstack(ctrl, &rqst, &resp, sizeof(arg_le)); + * ssam_request_do_sync_onstack(ctrl, &rqst, &resp, sizeof(arg_le)); * * to perform the request, allocating the message buffer directly * on the stack as opposed to allocation via kzalloc(). @@ -230,7 +230,7 @@ data received from it is converted from little-endian to host endianness. return status; } -Note that |ssam_request_sync| in its essence is a wrapper over lower-level +Note that |ssam_request_do_sync| in its essence is a wrapper over lower-level request primitives, which may also be used to perform requests. Refer to its implementation and documentation for more details. @@ -241,7 +241,7 @@ one of the generator macros, for example via: SSAM_DEFINE_SYNC_REQUEST_W(__ssam_tmp_perf_mode_set, __le32, { .target_category = SSAM_SSH_TC_TMP, - .target_id = 0x01, + .target_id = SSAM_SSH_TID_SAM, .command_id = 0x03, .instance_id = 0x00, }); diff --git a/Documentation/driver-api/surface_aggregator/ssh.rst b/Documentation/driver-api/surface_aggregator/ssh.rst index bf007d6c9873..b955b673838b 100644 --- a/Documentation/driver-api/surface_aggregator/ssh.rst +++ b/Documentation/driver-api/surface_aggregator/ssh.rst @@ -13,6 +13,7 @@ .. |DATA_NSQ| replace:: ``DATA_NSQ`` .. |TC| replace:: ``TC`` .. |TID| replace:: ``TID`` +.. |SID| replace:: ``SID`` .. |IID| replace:: ``IID`` .. |RQID| replace:: ``RQID`` .. |CID| replace:: ``CID`` @@ -76,7 +77,7 @@ after the frame structure and before the payload. The payload is followed by its own CRC (over all payload bytes). If the payload is not present (i.e. the frame has ``LEN=0``), the CRC of the payload is still present and will evaluate to ``0xffff``. The |LEN| field does not include any of the CRCs, it -equals the number of bytes inbetween the CRC of the frame and the CRC of the +equals the number of bytes between the CRC of the frame and the CRC of the payload. Additionally, the following fixed two-byte sequences are used: @@ -219,13 +220,13 @@ following fields, packed together and in order: - |u8| - Target category. - * - |TID| (out) + * - |TID| - |u8| - - Target ID for outgoing (host to EC) commands. + - Target ID for commands/messages. - * - |TID| (in) + * - |SID| - |u8| - - Target ID for incoming (EC to host) commands. + - Source ID for commands/messages. * - |IID| - |u8| @@ -286,19 +287,20 @@ general, however, a single target category should map to a single reserved event request ID. Furthermore, requests, responses, and events have an associated target ID -(``TID``). This target ID is split into output (host to EC) and input (EC to -host) fields, with the respecting other field (e.g. output field on incoming -messages) set to zero. Two ``TID`` values are known: Primary (``0x01``) and -secondary (``0x02``). In general, the response to a request should have the -same ``TID`` value, however, the field (output vs. input) should be used in -accordance to the direction in which the response is sent (i.e. on the input -field, as responses are generally sent from the EC to the host). - -Note that, even though requests and events should be uniquely identifiable -by target category and command ID alone, the EC may require specific -target ID and instance ID values to accept a command. A command that is -accepted for ``TID=1``, for example, may not be accepted for ``TID=2`` -and vice versa. +(``TID``) and source ID (``SID``). These two fields indicate where a message +originates from (``SID``) and what the intended target of the message is +(``TID``). Note that a response to a specific request therefore has the source +and target IDs swapped when compared to the original request (i.e. the request +target is the response source and the request source is the response target). +See (:c:type:`enum ssh_request_id <ssh_request_id>`) for possible values of +both. + +Note that, even though requests and events should be uniquely identifiable by +target category and command ID alone, the EC may require specific target ID and +instance ID values to accept a command. A command that is accepted for +``TID=1``, for example, may not be accepted for ``TID=2`` and vice versa. While +this may not always hold in reality, you can think of different target/source +IDs indicating different physical ECs with potentially different feature sets. Limitations and Observations diff --git a/Documentation/driver-api/thermal/index.rst b/Documentation/driver-api/thermal/index.rst index 030306ffa408..a886028014ab 100644 --- a/Documentation/driver-api/thermal/index.rst +++ b/Documentation/driver-api/thermal/index.rst @@ -14,7 +14,6 @@ Thermal exynos_thermal exynos_thermal_emulation - intel_powerclamp nouveau_thermal x86_pkg_temperature_thermal intel_dptf diff --git a/Documentation/driver-api/thermal/intel_dptf.rst b/Documentation/driver-api/thermal/intel_dptf.rst index 372bdb4d04c6..f5c193cccbda 100644 --- a/Documentation/driver-api/thermal/intel_dptf.rst +++ b/Documentation/driver-api/thermal/intel_dptf.rst @@ -84,6 +84,9 @@ DPTF ACPI Drivers interface https:/github.com/intel/thermal_daemon for decoding thermal table. +``production_mode`` (RO) + When different from zero, manufacturer locked thermal configuration + from further changes. ACPI Thermal Relationship table interface ------------------------------------------ diff --git a/Documentation/driver-api/tty/n_gsm.rst b/Documentation/driver-api/tty/n_gsm.rst index 35d7381515b0..9447b8a3b8e2 100644 --- a/Documentation/driver-api/tty/n_gsm.rst +++ b/Documentation/driver-api/tty/n_gsm.rst @@ -25,6 +25,8 @@ Config Initiator #. Switch the serial line to using the n_gsm line discipline by using ``TIOCSETD`` ioctl. +#. Configure the mux using ``GSMIOC_GETCONF_EXT``/``GSMIOC_SETCONF_EXT`` ioctl if needed. + #. Configure the mux using ``GSMIOC_GETCONF``/``GSMIOC_SETCONF`` ioctl. #. Obtain base gsmtty number for the used serial port. @@ -42,6 +44,7 @@ Config Initiator int ldisc = N_GSM0710; struct gsm_config c; + struct gsm_config_ext ce; struct termios configuration; uint32_t first; @@ -62,6 +65,12 @@ Config Initiator /* use n_gsm line discipline */ ioctl(fd, TIOCSETD, &ldisc); + /* get n_gsm extended configuration */ + ioctl(fd, GSMIOC_GETCONF_EXT, &ce); + /* use keep-alive once every 5s for modem connection supervision */ + ce.keep_alive = 500; + /* set the new extended configuration */ + ioctl(fd, GSMIOC_SETCONF_EXT, &ce); /* get n_gsm configuration */ ioctl(fd, GSMIOC_GETCONF, &c); /* we are initiator and need encoding 0 (basic) */ @@ -106,6 +115,9 @@ Config Requester #. Switch the serial line to using the *n_gsm* line discipline by using ``TIOCSETD`` ioctl. +#. Configure the mux using ``GSMIOC_GETCONF_EXT``/``GSMIOC_SETCONF_EXT`` + ioctl if needed. + #. Configure the mux using ``GSMIOC_GETCONF``/``GSMIOC_SETCONF`` ioctl. #. Obtain base gsmtty number for the used serial port:: @@ -119,6 +131,7 @@ Config Requester int ldisc = N_GSM0710; struct gsm_config c; + struct gsm_config_ext ce; struct termios configuration; uint32_t first; @@ -132,6 +145,12 @@ Config Requester /* use n_gsm line discipline */ ioctl(fd, TIOCSETD, &ldisc); + /* get n_gsm extended configuration */ + ioctl(fd, GSMIOC_GETCONF_EXT, &ce); + /* use keep-alive once every 5s for peer connection supervision */ + ce.keep_alive = 500; + /* set the new extended configuration */ + ioctl(fd, GSMIOC_SETCONF_EXT, &ce); /* get n_gsm configuration */ ioctl(fd, GSMIOC_GETCONF, &c); /* we are requester and need encoding 0 (basic) */ diff --git a/Documentation/driver-api/usb/dwc3.rst b/Documentation/driver-api/usb/dwc3.rst index 8b36ff11cef9..e3d6a620997f 100644 --- a/Documentation/driver-api/usb/dwc3.rst +++ b/Documentation/driver-api/usb/dwc3.rst @@ -18,7 +18,7 @@ controller which can be configured in one of 4 ways: 4. Hub configuration Linux currently supports several versions of this controller. In all -likelyhood, the version in your SoC is already supported. At the time +likelihood, the version in your SoC is already supported. At the time of this writing, known tested versions range from 2.02a to 3.10a. As a rule of thumb, anything above 2.02a should work reliably well. diff --git a/Documentation/driver-api/usb/usb3-debug-port.rst b/Documentation/driver-api/usb/usb3-debug-port.rst index b9fd131f4723..d4610457b052 100644 --- a/Documentation/driver-api/usb/usb3-debug-port.rst +++ b/Documentation/driver-api/usb/usb3-debug-port.rst @@ -48,7 +48,7 @@ kernel boot parameter:: "earlyprintk=xdbc" If there are multiple xHCI controllers in your system, you can -append a host contoller index to this kernel parameter. This +append a host controller index to this kernel parameter. This index starts from 0. Current design doesn't support DbC runtime suspend/resume. As diff --git a/Documentation/fault-injection/fault-injection.rst b/Documentation/fault-injection/fault-injection.rst index 5f6454b9dbd4..08e420e10973 100644 --- a/Documentation/fault-injection/fault-injection.rst +++ b/Documentation/fault-injection/fault-injection.rst @@ -231,6 +231,71 @@ proc entries This feature is intended for systematic testing of faults in a single system call. See an example below. + +Error Injectable Functions +-------------------------- + +This part is for the kenrel developers considering to add a function to +ALLOW_ERROR_INJECTION() macro. + +Requirements for the Error Injectable Functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Since the function-level error injection forcibly changes the code path +and returns an error even if the input and conditions are proper, this can +cause unexpected kernel crash if you allow error injection on the function +which is NOT error injectable. Thus, you (and reviewers) must ensure; + +- The function returns an error code if it fails, and the callers must check + it correctly (need to recover from it). + +- The function does not execute any code which can change any state before + the first error return. The state includes global or local, or input + variable. For example, clear output address storage (e.g. `*ret = NULL`), + increments/decrements counter, set a flag, preempt/irq disable or get + a lock (if those are recovered before returning error, that will be OK.) + +The first requirement is important, and it will result in that the release +(free objects) functions are usually harder to inject errors than allocate +functions. If errors of such release functions are not correctly handled +it will cause a memory leak easily (the caller will confuse that the object +has been released or corrupted.) + +The second one is for the caller which expects the function should always +does something. Thus if the function error injection skips whole of the +function, the expectation is betrayed and causes an unexpected error. + +Type of the Error Injectable Functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Each error injectable functions will have the error type specified by the +ALLOW_ERROR_INJECTION() macro. You have to choose it carefully if you add +a new error injectable function. If the wrong error type is chosen, the +kernel may crash because it may not be able to handle the error. +There are 4 types of errors defined in include/asm-generic/error-injection.h + +EI_ETYPE_NULL + This function will return `NULL` if it fails. e.g. return an allocateed + object address. + +EI_ETYPE_ERRNO + This function will return an `-errno` error code if it fails. e.g. return + -EINVAL if the input is wrong. This will include the functions which will + return an address which encodes `-errno` by ERR_PTR() macro. + +EI_ETYPE_ERRNO_NULL + This function will return an `-errno` or `NULL` if it fails. If the caller + of this function checks the return value with IS_ERR_OR_NULL() macro, this + type will be appropriate. + +EI_ETYPE_TRUE + This function will return `true` (non-zero positive value) if it fails. + +If you specifies a wrong type, for example, EI_TYPE_ERRNO for the function +which returns an allocated object, it may cause a problem because the returned +value is not an object address and the caller can not access to the address. + + How to add new fault injection capability ----------------------------------------- diff --git a/Documentation/fb/modedb.rst b/Documentation/fb/modedb.rst index e53375033146..bb2889c6ea27 100644 --- a/Documentation/fb/modedb.rst +++ b/Documentation/fb/modedb.rst @@ -29,7 +29,10 @@ Things between square brackets are optional. Valid names are:: - NSTC: 480i output, with the CCIR System-M TV mode and NTSC color encoding + - NTSC-J: 480i output, with the CCIR System-M TV mode, the NTSC color + encoding, and a black level equal to the blanking level. - PAL: 576i output, with the CCIR System-B TV mode and PAL color encoding + - PAL-M: 480i output, with the CCIR System-M TV mode and PAL color encoding If 'M' is specified in the mode_option argument (after <yres> and before <bpp> and <refresh>, if specified) the timings will be calculated using @@ -70,6 +73,8 @@ Valid options are:: - reflect_y (boolean): Perform an axial symmetry on the Y axis - rotate (integer): Rotate the initial framebuffer by x degrees. Valid values are 0, 90, 180 and 270. + - tv_mode: Analog TV mode. One of "NTSC", "NTSC-443", "NTSC-J", "PAL", + "PAL-M", "PAL-N", or "SECAM". - panel_orientation, one of "normal", "upside_down", "left_side_up", or "right_side_up". For KMS drivers only, this sets the "panel orientation" property on the kms connector as hint for kms users. diff --git a/Documentation/features/seccomp/seccomp-filter/arch-support.txt b/Documentation/features/seccomp/seccomp-filter/arch-support.txt index dc71bf7b1a7e..3a7237b989cd 100644 --- a/Documentation/features/seccomp/seccomp-filter/arch-support.txt +++ b/Documentation/features/seccomp/seccomp-filter/arch-support.txt @@ -14,7 +14,7 @@ | hexagon: | TODO | | ia64: | TODO | | loongarch: | ok | - | m68k: | TODO | + | m68k: | ok | | microblaze: | TODO | | mips: | ok | | nios2: | TODO | diff --git a/Documentation/filesystems/erofs.rst b/Documentation/filesystems/erofs.rst index 067fd1670b1f..a43aacf1494e 100644 --- a/Documentation/filesystems/erofs.rst +++ b/Documentation/filesystems/erofs.rst @@ -120,6 +120,8 @@ dax={always,never} Use direct access (no page cache). See dax A legacy option which is an alias for ``dax=always``. device=%s Specify a path to an extra device to be used together. fsid=%s Specify a filesystem image ID for Fscache back-end. +domain_id=%s Specify a domain ID in fscache mode so that different images + with the same blobs under a given domain ID can share storage. =================== ========================================================= Sysfs Entries diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index ef183387da20..eccd327e6df5 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -1277,8 +1277,8 @@ the file contents themselves, as described below: For the read path (->read_folio()) of regular files, filesystems can read the ciphertext into the page cache and decrypt it in-place. The -page lock must be held until decryption has finished, to prevent the -page from becoming visible to userspace prematurely. +folio lock must be held until decryption has finished, to prevent the +folio from becoming visible to userspace prematurely. For the write path (->writepage()) of regular files, filesystems cannot encrypt data in-place in the page cache, since the cached diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst index cb8e7573882a..ede672dedf11 100644 --- a/Documentation/filesystems/fsverity.rst +++ b/Documentation/filesystems/fsverity.rst @@ -118,10 +118,11 @@ as follows: - ``hash_algorithm`` must be the identifier for the hash algorithm to use for the Merkle tree, such as FS_VERITY_HASH_ALG_SHA256. See ``include/uapi/linux/fsverity.h`` for the list of possible values. -- ``block_size`` must be the Merkle tree block size. Currently, this - must be equal to the system page size, which is usually 4096 bytes. - Other sizes may be supported in the future. This value is not - necessarily the same as the filesystem block size. +- ``block_size`` is the Merkle tree block size, in bytes. In Linux + v6.3 and later, this can be any power of 2 between (inclusively) + 1024 and the minimum of the system page size and the filesystem + block size. In earlier versions, the page size was the only allowed + value. - ``salt_size`` is the size of the salt in bytes, or 0 if no salt is provided. The salt is a value that is prepended to every hashed block; it can be used to personalize the hashing for a particular @@ -161,6 +162,7 @@ FS_IOC_ENABLE_VERITY can fail with the following errors: - ``EBUSY``: this ioctl is already running on the file - ``EEXIST``: the file already has verity enabled - ``EFAULT``: the caller provided inaccessible memory +- ``EFBIG``: the file is too large to enable verity on - ``EINTR``: the operation was interrupted by a fatal signal - ``EINVAL``: unsupported version, hash algorithm, or block size; or reserved bits are set; or the file descriptor refers to neither a @@ -495,9 +497,11 @@ To create verity files on an ext4 filesystem, the filesystem must have been formatted with ``-O verity`` or had ``tune2fs -O verity`` run on it. "verity" is an RO_COMPAT filesystem feature, so once set, old kernels will only be able to mount the filesystem readonly, and old -versions of e2fsck will be unable to check the filesystem. Moreover, -currently ext4 only supports mounting a filesystem with the "verity" -feature when its block size is equal to PAGE_SIZE (often 4096 bytes). +versions of e2fsck will be unable to check the filesystem. + +Originally, an ext4 filesystem with the "verity" feature could only be +mounted when its block size was equal to the system page size +(typically 4096 bytes). In Linux v6.3, this limitation was removed. ext4 sets the EXT4_VERITY_FL on-disk inode flag on verity files. It can only be set by `FS_IOC_ENABLE_VERITY`_, and it cannot be cleared. @@ -518,9 +522,7 @@ support paging multi-gigabyte xattrs into memory, and to support encrypting xattrs. Note that the verity metadata *must* be encrypted when the file is, since it contains hashes of the plaintext data. -Currently, ext4 verity only supports the case where the Merkle tree -block size, filesystem block size, and page size are all the same. It -also only supports extent-based files. +ext4 only allows verity on extent-based files. f2fs ---- @@ -538,11 +540,10 @@ Like ext4, f2fs stores the verity metadata (Merkle tree and fsverity_descriptor) past the end of the file, starting at the first 64K boundary beyond i_size. See explanation for ext4 above. Moreover, f2fs supports at most 4096 bytes of xattr entries per inode -which wouldn't be enough for even a single Merkle tree block. +which usually wouldn't be enough for even a single Merkle tree block. -Currently, f2fs verity only supports a Merkle tree block size of 4096. -Also, f2fs doesn't support enabling verity on files that currently -have atomic or volatile writes pending. +f2fs doesn't support enabling verity on files that currently have +atomic or volatile writes pending. btrfs ----- @@ -567,51 +568,48 @@ Pagecache ~~~~~~~~~ For filesystems using Linux's pagecache, the ``->read_folio()`` and -``->readahead()`` methods must be modified to verify pages before they -are marked Uptodate. Merely hooking ``->read_iter()`` would be +``->readahead()`` methods must be modified to verify folios before +they are marked Uptodate. Merely hooking ``->read_iter()`` would be insufficient, since ``->read_iter()`` is not used for memory maps. -Therefore, fs/verity/ provides a function fsverity_verify_page() which -verifies a page that has been read into the pagecache of a verity -inode, but is still locked and not Uptodate, so it's not yet readable -by userspace. As needed to do the verification, -fsverity_verify_page() will call back into the filesystem to read -Merkle tree pages via fsverity_operations::read_merkle_tree_page(). +Therefore, fs/verity/ provides the function fsverity_verify_blocks() +which verifies data that has been read into the pagecache of a verity +inode. The containing folio must still be locked and not Uptodate, so +it's not yet readable by userspace. As needed to do the verification, +fsverity_verify_blocks() will call back into the filesystem to read +hash blocks via fsverity_operations::read_merkle_tree_page(). -fsverity_verify_page() returns false if verification failed; in this -case, the filesystem must not set the page Uptodate. Following this, +fsverity_verify_blocks() returns false if verification failed; in this +case, the filesystem must not set the folio Uptodate. Following this, as per the usual Linux pagecache behavior, attempts by userspace to -read() from the part of the file containing the page will fail with -EIO, and accesses to the page within a memory map will raise SIGBUS. - -fsverity_verify_page() currently only supports the case where the -Merkle tree block size is equal to PAGE_SIZE (often 4096 bytes). +read() from the part of the file containing the folio will fail with +EIO, and accesses to the folio within a memory map will raise SIGBUS. -In principle, fsverity_verify_page() verifies the entire path in the -Merkle tree from the data page to the root hash. However, for -efficiency the filesystem may cache the hash pages. Therefore, -fsverity_verify_page() only ascends the tree reading hash pages until -an already-verified hash page is seen, as indicated by the PageChecked -bit being set. It then verifies the path to that page. +In principle, verifying a data block requires verifying the entire +path in the Merkle tree from the data block to the root hash. +However, for efficiency the filesystem may cache the hash blocks. +Therefore, fsverity_verify_blocks() only ascends the tree reading hash +blocks until an already-verified hash block is seen. It then verifies +the path to that block. This optimization, which is also used by dm-verity, results in excellent sequential read performance. This is because usually (e.g. -127 in 128 times for 4K blocks and SHA-256) the hash page from the +127 in 128 times for 4K blocks and SHA-256) the hash block from the bottom level of the tree will already be cached and checked from -reading a previous data page. However, random reads perform worse. +reading a previous data block. However, random reads perform worse. Block device based filesystems ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Block device based filesystems (e.g. ext4 and f2fs) in Linux also use the pagecache, so the above subsection applies too. However, they -also usually read many pages from a file at once, grouped into a +also usually read many data blocks from a file at once, grouped into a structure called a "bio". To make it easier for these types of filesystems to support fs-verity, fs/verity/ also provides a function -fsverity_verify_bio() which verifies all pages in a bio. +fsverity_verify_bio() which verifies all data blocks in a bio. ext4 and f2fs also support encryption. If a verity file is also -encrypted, the pages must be decrypted before being verified. To +encrypted, the data must be decrypted before being verified. To support this, these filesystems allocate a "post-read context" for each bio and store it in ``->bi_private``:: @@ -626,14 +624,14 @@ each bio and store it in ``->bi_private``:: verity, or both is enabled. After the bio completes, for each needed postprocessing step the filesystem enqueues the bio_post_read_ctx on a workqueue, and then the workqueue work does the decryption or -verification. Finally, pages where no decryption or verity error -occurred are marked Uptodate, and the pages are unlocked. +verification. Finally, folios where no decryption or verity error +occurred are marked Uptodate, and the folios are unlocked. On many filesystems, files can contain holes. Normally, -``->readahead()`` simply zeroes holes and sets the corresponding pages -Uptodate; no bios are issued. To prevent this case from bypassing -fs-verity, these filesystems use fsverity_verify_page() to verify hole -pages. +``->readahead()`` simply zeroes hole blocks and considers the +corresponding data to be up-to-date; no bios are issued. To prevent +this case from bypassing fs-verity, filesystems use +fsverity_verify_blocks() to verify hole blocks. Filesystems also disable direct I/O on verity files, since otherwise direct I/O would bypass fs-verity. @@ -644,7 +642,7 @@ Userspace utility This document focuses on the kernel, but a userspace utility for fs-verity can be found at: - https://git.kernel.org/pub/scm/linux/kernel/git/ebiggers/fsverity-utils.git + https://git.kernel.org/pub/scm/fs/fsverity/fsverity-utils.git See the README.md file in the fsverity-utils source tree for details, including examples of setting up fs-verity protected files. @@ -793,9 +791,9 @@ weren't already directly answered in other parts of this document. :A: There are many reasons why this is not possible or would be very difficult, including the following: - - To prevent bypassing verification, pages must not be marked + - To prevent bypassing verification, folios must not be marked Uptodate until they've been verified. Currently, each - filesystem is responsible for marking pages Uptodate via + filesystem is responsible for marking folios Uptodate via ``->readahead()``. Therefore, currently it's not possible for the VFS to do the verification on its own. Changing this would require significant changes to the VFS and all filesystems. diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index 36fa2a83d714..7de7a7272a5e 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -56,35 +56,35 @@ inode_operations prototypes:: - int (*create) (struct inode *,struct dentry *,umode_t, bool); + int (*create) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t, bool); struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int); int (*link) (struct dentry *,struct inode *,struct dentry *); int (*unlink) (struct inode *,struct dentry *); - int (*symlink) (struct inode *,struct dentry *,const char *); - int (*mkdir) (struct inode *,struct dentry *,umode_t); + int (*symlink) (struct mnt_idmap *, struct inode *,struct dentry *,const char *); + int (*mkdir) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t); int (*rmdir) (struct inode *,struct dentry *); - int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t); - int (*rename) (struct inode *, struct dentry *, + int (*mknod) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t,dev_t); + int (*rename) (struct mnt_idmap *, struct inode *, struct dentry *, struct inode *, struct dentry *, unsigned int); int (*readlink) (struct dentry *, char __user *,int); const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *); void (*truncate) (struct inode *); - int (*permission) (struct inode *, int, unsigned int); + int (*permission) (struct mnt_idmap *, struct inode *, int, unsigned int); struct posix_acl * (*get_inode_acl)(struct inode *, int, bool); - int (*setattr) (struct dentry *, struct iattr *); - int (*getattr) (const struct path *, struct kstat *, u32, unsigned int); + int (*setattr) (struct mnt_idmap *, struct dentry *, struct iattr *); + int (*getattr) (struct mnt_idmap *, const struct path *, struct kstat *, u32, unsigned int); ssize_t (*listxattr) (struct dentry *, char *, size_t); int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len); void (*update_time)(struct inode *, struct timespec *, int); int (*atomic_open)(struct inode *, struct dentry *, struct file *, unsigned open_flag, umode_t create_mode); - int (*tmpfile) (struct user_namespace *, struct inode *, + int (*tmpfile) (struct mnt_idmap *, struct inode *, struct file *, umode_t); - int (*fileattr_set)(struct user_namespace *mnt_userns, + int (*fileattr_set)(struct mnt_idmap *idmap, struct dentry *dentry, struct fileattr *fa); int (*fileattr_get)(struct dentry *dentry, struct fileattr *fa); - struct posix_acl * (*get_acl)(struct user_namespace *, struct dentry *, int); + struct posix_acl * (*get_acl)(struct mnt_idmap *, struct dentry *, int); locking rules: all may block @@ -135,7 +135,7 @@ prototypes:: struct inode *inode, const char *name, void *buffer, size_t size); int (*set)(const struct xattr_handler *handler, - struct user_namespace *mnt_userns, + struct mnt_idmap *idmap, struct dentry *dentry, struct inode *inode, const char *name, const void *buffer, size_t size, int flags); diff --git a/Documentation/filesystems/nfs/client-identifier.rst b/Documentation/filesystems/nfs/client-identifier.rst index 5147e15815a1..a94c7a9748d7 100644 --- a/Documentation/filesystems/nfs/client-identifier.rst +++ b/Documentation/filesystems/nfs/client-identifier.rst @@ -152,7 +152,7 @@ string: via the kernel command line, or when the "nfs" module is loaded. - /sys/fs/nfs/client/net/identifier + /sys/fs/nfs/net/nfs_client/identifier This virtual file, available since Linux 5.3, is local to the network namespace in which it is accessed and so can provide distinction between network namespaces (containers) when the @@ -164,7 +164,7 @@ then that uniquifier can be used. For example, a uniquifier might be formed at boot using the container's internal identifier: sha256sum /etc/machine-id | awk '{print $1}' \\ - > /sys/fs/nfs/client/net/identifier + > /sys/fs/nfs/net/nfs_client/identifier Security considerations ----------------------- diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index e224b6d5b642..9d5fd9424e8b 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -1284,6 +1284,7 @@ support this. Table 1-9 lists the files and their meaning. rt_cache Routing cache snmp SNMP data sockstat Socket statistics + softnet_stat Per-CPU incoming packets queues statistics of online CPUs tcp TCP sockets udp UDP sockets unix UNIX domain sockets diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index 2c15e7053113..c53f30251a66 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -421,31 +421,31 @@ As of kernel 2.6.22, the following members are defined: .. code-block:: c struct inode_operations { - int (*create) (struct user_namespace *, struct inode *,struct dentry *, umode_t, bool); + int (*create) (struct mnt_idmap *, struct inode *,struct dentry *, umode_t, bool); struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int); int (*link) (struct dentry *,struct inode *,struct dentry *); int (*unlink) (struct inode *,struct dentry *); - int (*symlink) (struct user_namespace *, struct inode *,struct dentry *,const char *); - int (*mkdir) (struct user_namespace *, struct inode *,struct dentry *,umode_t); + int (*symlink) (struct mnt_idmap *, struct inode *,struct dentry *,const char *); + int (*mkdir) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t); int (*rmdir) (struct inode *,struct dentry *); - int (*mknod) (struct user_namespace *, struct inode *,struct dentry *,umode_t,dev_t); - int (*rename) (struct user_namespace *, struct inode *, struct dentry *, + int (*mknod) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t,dev_t); + int (*rename) (struct mnt_idmap *, struct inode *, struct dentry *, struct inode *, struct dentry *, unsigned int); int (*readlink) (struct dentry *, char __user *,int); const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *); - int (*permission) (struct user_namespace *, struct inode *, int); + int (*permission) (struct mnt_idmap *, struct inode *, int); struct posix_acl * (*get_inode_acl)(struct inode *, int, bool); - int (*setattr) (struct user_namespace *, struct dentry *, struct iattr *); - int (*getattr) (struct user_namespace *, const struct path *, struct kstat *, u32, unsigned int); + int (*setattr) (struct mnt_idmap *, struct dentry *, struct iattr *); + int (*getattr) (struct mnt_idmap *, const struct path *, struct kstat *, u32, unsigned int); ssize_t (*listxattr) (struct dentry *, char *, size_t); void (*update_time)(struct inode *, struct timespec *, int); int (*atomic_open)(struct inode *, struct dentry *, struct file *, unsigned open_flag, umode_t create_mode); - int (*tmpfile) (struct user_namespace *, struct inode *, struct file *, umode_t); - struct posix_acl * (*get_acl)(struct user_namespace *, struct dentry *, int); - int (*set_acl)(struct user_namespace *, struct dentry *, struct posix_acl *, int); - int (*fileattr_set)(struct user_namespace *mnt_userns, + int (*tmpfile) (struct mnt_idmap *, struct inode *, struct file *, umode_t); + struct posix_acl * (*get_acl)(struct mnt_idmap *, struct dentry *, int); + int (*set_acl)(struct mnt_idmap *, struct dentry *, struct posix_acl *, int); + int (*fileattr_set)(struct mnt_idmap *idmap, struct dentry *dentry, struct fileattr *fa); int (*fileattr_get)(struct dentry *dentry, struct fileattr *fa); }; diff --git a/Documentation/firmware-guide/acpi/acpi-lid.rst b/Documentation/firmware-guide/acpi/acpi-lid.rst index 71b9af13a048..03cbad6c6730 100644 --- a/Documentation/firmware-guide/acpi/acpi-lid.rst +++ b/Documentation/firmware-guide/acpi/acpi-lid.rst @@ -34,7 +34,7 @@ state upon the last _LID evaluation. There won't be difference when the _LID control method is evaluated during the runtime, the problem is its initial returning value. When the AML tables implement this control method with cached value, the initial returning value is likely not reliable. -There are platforms always retun "closed" as initial lid state. +There are platforms always return "closed" as initial lid state. Restrictions of the lid state change notifications ================================================== diff --git a/Documentation/firmware-guide/acpi/gpio-properties.rst b/Documentation/firmware-guide/acpi/gpio-properties.rst index eaec732cc77c..db0c0b1f3700 100644 --- a/Documentation/firmware-guide/acpi/gpio-properties.rst +++ b/Documentation/firmware-guide/acpi/gpio-properties.rst @@ -67,17 +67,30 @@ state of the output pin which driver should use during its initialization. Linux tries to use common sense here and derives the state from the bias and polarity settings. The table below shows the expectations: -========= ============= ============== -Pull Bias Polarity Requested... -========= ============= ============== -Implicit x AS IS (assumed firmware configured for us) -Explicit x (no _DSD) as Pull Bias (Up == High, Down == Low), - assuming non-active (Polarity = !Pull Bias) -Down Low as low, assuming active -Down High as low, assuming non-active -Up Low as high, assuming non-active -Up High as high, assuming active -========= ============= ============== ++-------------+-------------+-----------------------------------------------+ +| Pull Bias | Polarity | Requested... | ++=============+=============+===============================================+ +| Implicit | ++-------------+-------------+-----------------------------------------------+ +| **Default** | x | AS IS (assumed firmware configured it for us) | ++-------------+-------------+-----------------------------------------------+ +| Explicit | ++-------------+-------------+-----------------------------------------------+ +| **None** | x | AS IS (assumed firmware configured it for us) | +| | | with no Pull Bias | ++-------------+-------------+-----------------------------------------------+ +| **Up** | x (no _DSD) | | +| +-------------+ as high, assuming non-active | +| | Low | | +| +-------------+-----------------------------------------------+ +| | High | as high, assuming active | ++-------------+-------------+-----------------------------------------------+ +| **Down** | x (no _DSD) | | +| +-------------+ as low, assuming non-active | +| | High | | +| +-------------+-----------------------------------------------+ +| | Low | as low, assuming active | ++-------------+-------------+-----------------------------------------------+ That said, for our above example the both GPIOs, since the bias setting is explicit and _DSD is present, will be treated as active with a high diff --git a/Documentation/firmware-guide/acpi/namespace.rst b/Documentation/firmware-guide/acpi/namespace.rst index 6193582a2204..4ef963679a3d 100644 --- a/Documentation/firmware-guide/acpi/namespace.rst +++ b/Documentation/firmware-guide/acpi/namespace.rst @@ -31,7 +31,7 @@ Description Table). The XSDT always points to the FADT (Fixed ACPI Description Table) using its first entry, the data within the FADT includes various fixed-length entries that describe fixed ACPI features of the hardware. The FADT contains a pointer to the DSDT -(Differentiated System Descripition Table). The XSDT also contains +(Differentiated System Description Table). The XSDT also contains entries pointing to possibly multiple SSDTs (Secondary System Description Table). diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst index 15b670926084..80255e2dc3e6 100644 --- a/Documentation/fpga/dfl.rst +++ b/Documentation/fpga/dfl.rst @@ -75,6 +75,125 @@ convenient for software to locate each feature by walking through this list, and can be implemented in register regions of any FPGA device. +Device Feature Header - Version 0 +================================= +Version 0 (DFHv0) is the original version of the Device Feature Header. +All multi-byte quantities in DFHv0 are little-endian. +The format of DFHv0 is shown below:: + + +-----------------------------------------------------------------------+ + |63 Type 60|59 DFH VER 52|51 Rsvd 41|40 EOL|39 Next 16|15 REV 12|11 ID 0| 0x00 + +-----------------------------------------------------------------------+ + |63 GUID_L 0| 0x08 + +-----------------------------------------------------------------------+ + |63 GUID_H 0| 0x10 + +-----------------------------------------------------------------------+ + +- Offset 0x00 + + * Type - The type of DFH (e.g. FME, AFU, or private feature). + * DFH VER - The version of the DFH. + * Rsvd - Currently unused. + * EOL - Set if the DFH is the end of the Device Feature List (DFL). + * Next - The offset in bytes of the next DFH in the DFL from the DFH start, + and the start of a DFH must be aligned to an 8 byte boundary. + If EOL is set, Next is the size of MMIO of the last feature in the list. + * REV - The revision of the feature associated with this header. + * ID - The feature ID if Type is private feature. + +- Offset 0x08 + + * GUID_L - Least significant 64 bits of a 128-bit Globally Unique Identifier + (present only if Type is FME or AFU). + +- Offset 0x10 + + * GUID_H - Most significant 64 bits of a 128-bit Globally Unique Identifier + (present only if Type is FME or AFU). + + +Device Feature Header - Version 1 +================================= +Version 1 (DFHv1) of the Device Feature Header adds the following functionality: + +* Provides a standardized mechanism for features to describe + parameters/capabilities to software. +* Standardize the use of a GUID for all DFHv1 types. +* Decouples the DFH location from the register space of the feature itself. + +All multi-byte quantities in DFHv1 are little-endian. +The format of Version 1 of the Device Feature Header (DFH) is shown below:: + + +-----------------------------------------------------------------------+ + |63 Type 60|59 DFH VER 52|51 Rsvd 41|40 EOL|39 Next 16|15 REV 12|11 ID 0| 0x00 + +-----------------------------------------------------------------------+ + |63 GUID_L 0| 0x08 + +-----------------------------------------------------------------------+ + |63 GUID_H 0| 0x10 + +-----------------------------------------------------------------------+ + |63 Reg Address/Offset 1| Rel 0| 0x18 + +-----------------------------------------------------------------------+ + |63 Reg Size 32|Params 31|30 Group 16|15 Instance 0| 0x20 + +-----------------------------------------------------------------------+ + |63 Next 35|34RSV33|EOP32|31 Param Version 16|15 Param ID 0| 0x28 + +-----------------------------------------------------------------------+ + |63 Parameter Data 0| 0x30 + +-----------------------------------------------------------------------+ + + ... + + +-----------------------------------------------------------------------+ + |63 Next 35|34RSV33|EOP32|31 Param Version 16|15 Param ID 0| + +-----------------------------------------------------------------------+ + |63 Parameter Data 0| + +-----------------------------------------------------------------------+ + +- Offset 0x00 + + * Type - The type of DFH (e.g. FME, AFU, or private feature). + * DFH VER - The version of the DFH. + * Rsvd - Currently unused. + * EOL - Set if the DFH is the end of the Device Feature List (DFL). + * Next - The offset in bytes of the next DFH in the DFL from the DFH start, + and the start of a DFH must be aligned to an 8 byte boundary. + If EOL is set, Next is the size of MMIO of the last feature in the list. + * REV - The revision of the feature associated with this header. + * ID - The feature ID if Type is private feature. + +- Offset 0x08 + + * GUID_L - Least significant 64 bits of a 128-bit Globally Unique Identifier. + +- Offset 0x10 + + * GUID_H - Most significant 64 bits of a 128-bit Globally Unique Identifier. + +- Offset 0x18 + + * Reg Address/Offset - If Rel bit is set, then the value is the high 63 bits + of a 16-bit aligned absolute address of the feature's registers. Otherwise + the value is the offset from the start of the DFH of the feature's registers. + +- Offset 0x20 + + * Reg Size - Size of feature's register set in bytes. + * Params - Set if DFH has a list of parameter blocks. + * Group - Id of group if feature is part of a group. + * Instance - Id of feature instance within a group. + +- Offset 0x28 if feature has parameters + + * Next - Offset to the next parameter block in 8 byte words. If EOP set, + size in 8 byte words of last parameter. + * Param Version - Version of Param ID. + * Param ID - ID of parameter. + +- Offset 0x30 + + * Parameter Data - Parameter data whose size and format is defined by + version and ID of the parameter. + + FIU - FME (FPGA Management Engine) ================================== The FPGA Management Engine performs reconfiguration and other infrastructure diff --git a/Documentation/gpu/amdgpu/apu-asic-info-table.csv b/Documentation/gpu/amdgpu/apu-asic-info-table.csv index 98c6988e424e..395a7b7bfaef 100644 --- a/Documentation/gpu/amdgpu/apu-asic-info-table.csv +++ b/Documentation/gpu/amdgpu/apu-asic-info-table.csv @@ -1,8 +1,10 @@ -Product Name, Code Reference, DCN/DCE version, GC version, VCE/UVD/VCN version, SDMA version -Radeon R* Graphics, CARRIZO/STONEY, DCE 11, 8, VCE 3 / UVD 6, 3 -Ryzen 3000 series / AMD Ryzen Embedded V1*/R1* with Radeon Vega Gfx, RAVEN/PICASSO, DCN 1.0, 9.1.0, VCN 1.0, 4.1.0 -Ryzen 4000 series, RENOIR, DCN 2.1, 9.3, VCN 2.2, 4.1.2 -Ryzen 3000 series / AMD Ryzen Embedded V1*/R1* with Radeon Vega Gfx, RAVEN2, DCN 1.0, 9.2.2, VCN 1.0.1, 4.1.1 -SteamDeck, VANGOGH, DCN 3.0.1, 10.3.1, VCN 3.1.0, 5.2.1 -Ryzen 5000 series, GREEN SARDINE, DCN 2.1, 9.3, VCN 2.2, 4.1.1 -Ryzen 6000 Zen, YELLOW CARP, 3.1.2, 10.3.3, VCN 3.1.1, 5.2.3 +Product Name, Code Reference, DCN/DCE version, GC version, VCE/UVD/VCN version, SDMA version, MP0 version +Radeon R* Graphics, CARRIZO/STONEY, DCE 11, 8, VCE 3 / UVD 6, 3, n/a +Ryzen 3000 series / AMD Ryzen Embedded V1*/R1* with Radeon Vega Gfx, RAVEN/PICASSO, DCN 1.0, 9.1.0, VCN 1.0, 4.1.0, 10.0.0 +Ryzen 4000 series, RENOIR, DCN 2.1, 9.3, VCN 2.2, 4.1.2, 11.0.3 +Ryzen 3000 series / AMD Ryzen Embedded V1*/R1* with Radeon Vega Gfx, RAVEN2, DCN 1.0, 9.2.2, VCN 1.0.1, 4.1.1, 10.0.1 +SteamDeck, VANGOGH, DCN 3.0.1, 10.3.1, VCN 3.1.0, 5.2.1, 11.5.0 +Ryzen 5000 series / Ryzen 7x30 series, GREEN SARDINE / Cezanne / Barcelo / Barcelo-R, DCN 2.1, 9.3, VCN 2.2, 4.1.1, 12.0.1 +Ryzen 6000 series / Ryzen 7x35 series, YELLOW CARP / Rembrandt / Rembrandt+, 3.1.2, 10.3.3, VCN 3.1.1, 5.2.3, 13.0.3 +Ryzen 7000 series (AM5), Raphael, 3.1.5, 10.3.6, 3.1.2, 5.2.6, 13.0.5 +Ryzen 7x20 series, Mendocino, 3.1.6, 10.3.7, 3.1.1, 5.2.7, 13.0.8 diff --git a/Documentation/gpu/amdgpu/dgpu-asic-info-table.csv b/Documentation/gpu/amdgpu/dgpu-asic-info-table.csv index 84617aa35dab..882d2518f8ed 100644 --- a/Documentation/gpu/amdgpu/dgpu-asic-info-table.csv +++ b/Documentation/gpu/amdgpu/dgpu-asic-info-table.csv @@ -22,3 +22,5 @@ AMD Radeon RX 6800(XT) /6900(XT) /W6800, SIENNA_CICHLID, DCN 3.0.0, 10.3.0, VCN AMD Radeon RX 6700 XT / 6800M / 6700M, NAVY_FLOUNDER, DCN 3.0.0, 10.3.2, VCN 3.0.0, 5.2.2 AMD Radeon RX 6600(XT) /6600M /W6600 /W6600M, DIMGREY_CAVEFISH, DCN 3.0.2, 10.3.4, VCN 3.0.16, 5.2.4 AMD Radeon RX 6500M /6300M /W6500M /W6300M, BEIGE_GOBY, DCN 3.0.3, 10.3.5, VCN 3.0.33, 5.2.5 +AMD Radeon RX 7900 XT /XTX, , DCN 3.2.0, 11.0.0, VCN 4.0.0, 6.0.0 +AMD Radeon RX 7600M (XT) /7700S /7600S, , DCN 3.2.1, 11.0.2, VCN 4.0.4, 6.0.2 diff --git a/Documentation/gpu/amdgpu/driver-misc.rst b/Documentation/gpu/amdgpu/driver-misc.rst index 1800543d45f7..be131e963d87 100644 --- a/Documentation/gpu/amdgpu/driver-misc.rst +++ b/Documentation/gpu/amdgpu/driver-misc.rst @@ -37,7 +37,7 @@ Accelerated Processing Units (APU) Info .. csv-table:: :header-rows: 1 - :widths: 3, 2, 2, 1, 1, 1 + :widths: 3, 2, 2, 1, 1, 1, 1 :file: ./apu-asic-info-table.csv Discrete GPU Info diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index a4860ffd6e86..b8ab05e42dbb 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -188,6 +188,13 @@ Bridge Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_bridge.c :export: +MIPI-DSI bridge operation +------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :doc: dsi bridge operations + + Bridge Connector Helper Reference --------------------------------- diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index b4377a545425..c92d425cb2dd 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -520,6 +520,12 @@ HDMI Specific Connector Properties .. kernel-doc:: drivers/gpu/drm/drm_connector.c :doc: HDMI connector properties +Analog TV Specific Connector Properties +--------------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_connector.c + :doc: Analog TV Connector Properties + Standard CRTC Properties ------------------------ diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index ce47b4292481..65fb3036a580 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -402,19 +402,19 @@ It's possible to run the IGT-tests in a VM in two ways: 1. Use IGT inside a VM 2. Use IGT from the host machine and write the results in a shared directory. -As follow, there is an example of using a VM with a shared directory with -the host machine to run igt-tests. As an example it's used virtme:: +Following is an example of using a VM with a shared directory with +the host machine to run igt-tests. This example uses virtme:: $ virtme-run --rwdir /path/for/shared_dir --kdir=path/for/kernel/directory --mods=auto -Run the igt-tests in the guest machine, as example it's ran the 'kms_flip' +Run the igt-tests in the guest machine. This example runs the 'kms_flip' tests:: $ /path/for/igt-gpu-tools/scripts/run-tests.sh -p -s -t "kms_flip.*" -v -In this example, instead of build the igt_runner, Piglit is used -(-p option); it's created html summary of the tests results and it's saved -in the folder "igt-gpu-tools/results"; it's executed only the igt-tests +In this example, instead of building the igt_runner, Piglit is used +(-p option). It creates an HTML summary of the test results and saves +them in the folder "igt-gpu-tools/results". It executes only the igt-tests matching the -t option. Display CRC Support diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst index b99dede9a5b1..eee5996acf2c 100644 --- a/Documentation/gpu/index.rst +++ b/Documentation/gpu/index.rst @@ -1,6 +1,6 @@ -================================== -Linux GPU Driver Developer's Guide -================================== +============================ +GPU Driver Developer's Guide +============================ .. toctree:: diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index b2c6aaf1edf2..1f8a5ebe188e 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -508,17 +508,18 @@ Clean up the debugfs support There's a bunch of issues with it: -- The drm_info_list ->show() function doesn't even bother to cast to the drm - structure for you. This is lazy. +- Convert drivers to support the drm_debugfs_add_files() function instead of + the drm_debugfs_create_files() function. + +- Improve late-register debugfs by rolling out the same debugfs pre-register + infrastructure for connector and crtc too. That way, the drivers won't need to + split their setup code into init and register anymore. - We probably want to have some support for debugfs files on crtc/connectors and maybe other kms objects directly in core. There's even drm_print support in the funcs for these objects to dump kms state, so it's all there. And then the ->show() functions should obviously give you a pointer to the right object. -- The drm_info_list stuff is centered on drm_minor instead of drm_device. For - anything we want to print drm_device (or maybe drm_file) is the right thing. - - The drm_driver->debugfs_init hooks we have is just an artifact of the old midlayered load sequence. DRM debugfs should work more like sysfs, where you can create properties/files for an object anytime you want, and the core @@ -527,8 +528,6 @@ There's a bunch of issues with it: this (together with the drm_minor->drm_device move) would allow us to remove debugfs_init. -Previous RFC that hasn't landed yet: https://lore.kernel.org/dri-devel/20200513114130.28641-2-wambui.karugax@gmail.com/ - Contact: Daniel Vetter Level: Intermediate diff --git a/Documentation/gpu/vc4.rst b/Documentation/gpu/vc4.rst index 5df1d98b9544..5e5e92e40919 100644 --- a/Documentation/gpu/vc4.rst +++ b/Documentation/gpu/vc4.rst @@ -54,6 +54,25 @@ VEC (Composite TV out) encoder .. kernel-doc:: drivers/gpu/drm/vc4/vc4_vec.c :doc: VC4 SDTV module +KUnit Tests +=========== + +The VC4 Driver uses KUnit to perform driver-specific unit and +integration tests. + +These tests are using a mock driver and can be ran using the +command below, on either arm or arm64 architectures, + +.. code-block:: bash + + $ ./tools/testing/kunit/kunit.py run \ + --kunitconfig=drivers/gpu/drm/vc4/tests/.kunitconfig \ + --cross_compile aarch64-linux-gnu- --arch arm64 + +Parts of the driver that are currently covered by tests are: + * The HVS to PixelValve dynamic FIFO assignment, for the BCM2835-7 + and BCM2711. + Memory Management and 3D Command Submission =========================================== diff --git a/Documentation/hid/hid-alps.rst b/Documentation/hid/hid-alps.rst index 767c96bcbb7c..94382bb0ada4 100644 --- a/Documentation/hid/hid-alps.rst +++ b/Documentation/hid/hid-alps.rst @@ -9,7 +9,7 @@ Currently ALPS HID driver supports U1 Touchpad device. U1 device basic information. ========== ====== -Vender ID 0x044E +Vendor ID 0x044E Product ID 0x120B Version ID 0x0121 ========== ====== diff --git a/Documentation/hid/hid-bpf.rst b/Documentation/hid/hid-bpf.rst new file mode 100644 index 000000000000..4fad83a6ebc3 --- /dev/null +++ b/Documentation/hid/hid-bpf.rst @@ -0,0 +1,522 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======= +HID-BPF +======= + +HID is a standard protocol for input devices but some devices may require +custom tweaks, traditionally done with a kernel driver fix. Using the eBPF +capabilities instead speeds up development and adds new capabilities to the +existing HID interfaces. + +.. contents:: + :local: + :depth: 2 + + +When (and why) to use HID-BPF +============================= + +There are several use cases when using HID-BPF is better +than standard kernel driver fix: + +Dead zone of a joystick +----------------------- + +Assuming you have a joystick that is getting older, it is common to see it +wobbling around its neutral point. This is usually filtered at the application +level by adding a *dead zone* for this specific axis. + +With HID-BPF, we can apply this filtering in the kernel directly so userspace +does not get woken up when nothing else is happening on the input controller. + +Of course, given that this dead zone is specific to an individual device, we +can not create a generic fix for all of the same joysticks. Adding a custom +kernel API for this (e.g. by adding a sysfs entry) does not guarantee this new +kernel API will be broadly adopted and maintained. + +HID-BPF allows the userspace program to load the program itself, ensuring we +only load the custom API when we have a user. + +Simple fixup of report descriptor +--------------------------------- + +In the HID tree, half of the drivers only fix one key or one byte +in the report descriptor. These fixes all require a kernel patch and the +subsequent shepherding into a release, a long and painful process for users. + +We can reduce this burden by providing an eBPF program instead. Once such a +program has been verified by the user, we can embed the source code into the +kernel tree and ship the eBPF program and load it directly instead of loading +a specific kernel module for it. + +Note: distribution of eBPF programs and their inclusion in the kernel is not +yet fully implemented + +Add a new feature that requires a new kernel API +------------------------------------------------ + +An example for such a feature are the Universal Stylus Interface (USI) pens. +Basically, USI pens require a new kernel API because there are new +channels of communication that our HID and input stack do not support. +Instead of using hidraw or creating new sysfs entries or ioctls, we can rely +on eBPF to have the kernel API controlled by the consumer and to not +impact the performances by waking up userspace every time there is an +event. + +Morph a device into something else and control that from userspace +------------------------------------------------------------------ + +The kernel has a relatively static mapping of HID items to evdev bits. +It cannot decide to dynamically transform a given device into something else +as it does not have the required context and any such transformation cannot be +undone (or even discovered) by userspace. + +However, some devices are useless with that static way of defining devices. For +example, the Microsoft Surface Dial is a pushbutton with haptic feedback that +is barely usable as of today. + +With eBPF, userspace can morph that device into a mouse, and convert the dial +events into wheel events. Also, the userspace program can set/unset the haptic +feedback depending on the context. For example, if a menu is visible on the +screen we likely need to have a haptic click every 15 degrees. But when +scrolling in a web page the user experience is better when the device emits +events at the highest resolution. + +Firewall +-------- + +What if we want to prevent other users to access a specific feature of a +device? (think a possibly broken firmware update entry point) + +With eBPF, we can intercept any HID command emitted to the device and +validate it or not. + +This also allows to sync the state between the userspace and the +kernel/bpf program because we can intercept any incoming command. + +Tracing +------- + +The last usage is tracing events and all the fun we can do we BPF to summarize +and analyze events. + +Right now, tracing relies on hidraw. It works well except for a couple +of issues: + +1. if the driver doesn't export a hidraw node, we can't trace anything + (eBPF will be a "god-mode" there, so this may raise some eyebrows) +2. hidraw doesn't catch other processes' requests to the device, which + means that we have cases where we need to add printks to the kernel + to understand what is happening. + +High-level view of HID-BPF +========================== + +The main idea behind HID-BPF is that it works at an array of bytes level. +Thus, all of the parsing of the HID report and the HID report descriptor +must be implemented in the userspace component that loads the eBPF +program. + +For example, in the dead zone joystick from above, knowing which fields +in the data stream needs to be set to ``0`` needs to be computed by userspace. + +A corollary of this is that HID-BPF doesn't know about the other subsystems +available in the kernel. *You can not directly emit input event through the +input API from eBPF*. + +When a BPF program needs to emit input events, it needs to talk with the HID +protocol, and rely on the HID kernel processing to translate the HID data into +input events. + +Available types of programs +=========================== + +HID-BPF is built "on top" of BPF, meaning that we use tracing method to +declare our programs. + +HID-BPF has the following attachment types available: + +1. event processing/filtering with ``SEC("fmod_ret/hid_bpf_device_event")`` in libbpf +2. actions coming from userspace with ``SEC("syscall")`` in libbpf +3. change of the report descriptor with ``SEC("fmod_ret/hid_bpf_rdesc_fixup")`` in libbpf + +A ``hid_bpf_device_event`` is calling a BPF program when an event is received from +the device. Thus we are in IRQ context and can act on the data or notify userspace. +And given that we are in IRQ context, we can not talk back to the device. + +A ``syscall`` means that userspace called the syscall ``BPF_PROG_RUN`` facility. +This time, we can do any operations allowed by HID-BPF, and talking to the device is +allowed. + +Last, ``hid_bpf_rdesc_fixup`` is different from the others as there can be only one +BPF program of this type. This is called on ``probe`` from the driver and allows to +change the report descriptor from the BPF program. Once a ``hid_bpf_rdesc_fixup`` +program has been loaded, it is not possible to overwrite it unless the program which +inserted it allows us by pinning the program and closing all of its fds pointing to it. + +Developer API: +============== + +User API data structures available in programs: +----------------------------------------------- + +.. kernel-doc:: include/linux/hid_bpf.h + +Available tracing functions to attach a HID-BPF program: +-------------------------------------------------------- + +.. kernel-doc:: drivers/hid/bpf/hid_bpf_dispatch.c + :functions: hid_bpf_device_event hid_bpf_rdesc_fixup + +Available API that can be used in all HID-BPF programs: +------------------------------------------------------- + +.. kernel-doc:: drivers/hid/bpf/hid_bpf_dispatch.c + :functions: hid_bpf_get_data + +Available API that can be used in syscall HID-BPF programs: +----------------------------------------------------------- + +.. kernel-doc:: drivers/hid/bpf/hid_bpf_dispatch.c + :functions: hid_bpf_attach_prog hid_bpf_hw_request hid_bpf_allocate_context hid_bpf_release_context + +General overview of a HID-BPF program +===================================== + +Accessing the data attached to the context +------------------------------------------ + +The ``struct hid_bpf_ctx`` doesn't export the ``data`` fields directly and to access +it, a bpf program needs to first call :c:func:`hid_bpf_get_data`. + +``offset`` can be any integer, but ``size`` needs to be constant, known at compile +time. + +This allows the following: + +1. for a given device, if we know that the report length will always be of a certain value, + we can request the ``data`` pointer to point at the full report length. + + The kernel will ensure we are using a correct size and offset and eBPF will ensure + the code will not attempt to read or write outside of the boundaries:: + + __u8 *data = hid_bpf_get_data(ctx, 0 /* offset */, 256 /* size */); + + if (!data) + return 0; /* ensure data is correct, now the verifier knows we + * have 256 bytes available */ + + bpf_printk("hello world: %02x %02x %02x", data[0], data[128], data[255]); + +2. if the report length is variable, but we know the value of ``X`` is always a 16-bit + integer, we can then have a pointer to that value only:: + + __u16 *x = hid_bpf_get_data(ctx, offset, sizeof(*x)); + + if (!x) + return 0; /* something went wrong */ + + *x += 1; /* increment X by one */ + +Effect of a HID-BPF program +--------------------------- + +For all HID-BPF attachment types except for :c:func:`hid_bpf_rdesc_fixup`, several eBPF +programs can be attached to the same device. + +Unless ``HID_BPF_FLAG_INSERT_HEAD`` is added to the flags while attaching the +program, the new program is appended at the end of the list. +``HID_BPF_FLAG_INSERT_HEAD`` will insert the new program at the beginning of the +list which is useful for e.g. tracing where we need to get the unprocessed events +from the device. + +Note that if there are multiple programs using the ``HID_BPF_FLAG_INSERT_HEAD`` flag, +only the most recently loaded one is actually the first in the list. + +``SEC("fmod_ret/hid_bpf_device_event")`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Whenever a matching event is raised, the eBPF programs are called one after the other +and are working on the same data buffer. + +If a program changes the data associated with the context, the next one will see +the modified data but it will have *no* idea of what the original data was. + +Once all the programs are run and return ``0`` or a positive value, the rest of the +HID stack will work on the modified data, with the ``size`` field of the last hid_bpf_ctx +being the new size of the input stream of data. + +A BPF program returning a negative error discards the event, i.e. this event will not be +processed by the HID stack. Clients (hidraw, input, LEDs) will **not** see this event. + +``SEC("syscall")`` +~~~~~~~~~~~~~~~~~~ + +``syscall`` are not attached to a given device. To tell which device we are working +with, userspace needs to refer to the device by its unique system id (the last 4 numbers +in the sysfs path: ``/sys/bus/hid/devices/xxxx:yyyy:zzzz:0000``). + +To retrieve a context associated with the device, the program must call +:c:func:`hid_bpf_allocate_context` and must release it with :c:func:`hid_bpf_release_context` +before returning. +Once the context is retrieved, one can also request a pointer to kernel memory with +:c:func:`hid_bpf_get_data`. This memory is big enough to support all input/output/feature +reports of the given device. + +``SEC("fmod_ret/hid_bpf_rdesc_fixup")`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``hid_bpf_rdesc_fixup`` program works in a similar manner to +``.report_fixup`` of ``struct hid_driver``. + +When the device is probed, the kernel sets the data buffer of the context with the +content of the report descriptor. The memory associated with that buffer is +``HID_MAX_DESCRIPTOR_SIZE`` (currently 4kB). + +The eBPF program can modify the data buffer at-will and the kernel uses the +modified content and size as the report descriptor. + +Whenever a ``SEC("fmod_ret/hid_bpf_rdesc_fixup")`` program is attached (if no +program was attached before), the kernel immediately disconnects the HID device +and does a reprobe. + +In the same way, when the ``SEC("fmod_ret/hid_bpf_rdesc_fixup")`` program is +detached, the kernel issues a disconnect on the device. + +There is no ``detach`` facility in HID-BPF. Detaching a program happens when +all the user space file descriptors pointing at a program are closed. +Thus, if we need to replace a report descriptor fixup, some cooperation is +required from the owner of the original report descriptor fixup. +The previous owner will likely pin the program in the bpffs, and we can then +replace it through normal bpf operations. + +Attaching a bpf program to a device +=================================== + +``libbpf`` does not export any helper to attach a HID-BPF program. +Users need to use a dedicated ``syscall`` program which will call +``hid_bpf_attach_prog(hid_id, program_fd, flags)``. + +``hid_id`` is the unique system ID of the HID device (the last 4 numbers in the +sysfs path: ``/sys/bus/hid/devices/xxxx:yyyy:zzzz:0000``) + +``progam_fd`` is the opened file descriptor of the program to attach. + +``flags`` is of type ``enum hid_bpf_attach_flags``. + +We can not rely on hidraw to bind a BPF program to a HID device. hidraw is an +artefact of the processing of the HID device, and is not stable. Some drivers +even disable it, so that removes the tracing capabilities on those devices +(where it is interesting to get the non-hidraw traces). + +On the other hand, the ``hid_id`` is stable for the entire life of the HID device, +even if we change its report descriptor. + +Given that hidraw is not stable when the device disconnects/reconnects, we recommend +accessing the current report descriptor of the device through the sysfs. +This is available at ``/sys/bus/hid/devices/BUS:VID:PID.000N/report_descriptor`` as a +binary stream. + +Parsing the report descriptor is the responsibility of the BPF programmer or the userspace +component that loads the eBPF program. + +An (almost) complete example of a BPF enhanced HID device +========================================================= + +*Foreword: for most parts, this could be implemented as a kernel driver* + +Let's imagine we have a new tablet device that has some haptic capabilities +to simulate the surface the user is scratching on. This device would also have +a specific 3 positions switch to toggle between *pencil on paper*, *cray on a wall* +and *brush on a painting canvas*. To make things even better, we can control the +physical position of the switch through a feature report. + +And of course, the switch is relying on some userspace component to control the +haptic feature of the device itself. + +Filtering events +---------------- + +The first step consists in filtering events from the device. Given that the switch +position is actually reported in the flow of the pen events, using hidraw to implement +that filtering would mean that we wake up userspace for every single event. + +This is OK for libinput, but having an external library that is just interested in +one byte in the report is less than ideal. + +For that, we can create a basic skeleton for our BPF program:: + + #include "vmlinux.h" + #include <bpf/bpf_helpers.h> + #include <bpf/bpf_tracing.h> + + /* HID programs need to be GPL */ + char _license[] SEC("license") = "GPL"; + + /* HID-BPF kfunc API definitions */ + extern __u8 *hid_bpf_get_data(struct hid_bpf_ctx *ctx, + unsigned int offset, + const size_t __sz) __ksym; + extern int hid_bpf_attach_prog(unsigned int hid_id, int prog_fd, u32 flags) __ksym; + + struct { + __uint(type, BPF_MAP_TYPE_RINGBUF); + __uint(max_entries, 4096 * 64); + } ringbuf SEC(".maps"); + + struct attach_prog_args { + int prog_fd; + unsigned int hid; + unsigned int flags; + int retval; + }; + + SEC("syscall") + int attach_prog(struct attach_prog_args *ctx) + { + ctx->retval = hid_bpf_attach_prog(ctx->hid, + ctx->prog_fd, + ctx->flags); + return 0; + } + + __u8 current_value = 0; + + SEC("?fmod_ret/hid_bpf_device_event") + int BPF_PROG(filter_switch, struct hid_bpf_ctx *hid_ctx) + { + __u8 *data = hid_bpf_get_data(hid_ctx, 0 /* offset */, 192 /* size */); + __u8 *buf; + + if (!data) + return 0; /* EPERM check */ + + if (current_value != data[152]) { + buf = bpf_ringbuf_reserve(&ringbuf, 1, 0); + if (!buf) + return 0; + + *buf = data[152]; + + bpf_ringbuf_commit(buf, 0); + + current_value = data[152]; + } + + return 0; + } + +To attach ``filter_switch``, userspace needs to call the ``attach_prog`` syscall +program first:: + + static int attach_filter(struct hid *hid_skel, int hid_id) + { + int err, prog_fd; + int ret = -1; + struct attach_prog_args args = { + .hid = hid_id, + }; + DECLARE_LIBBPF_OPTS(bpf_test_run_opts, tattrs, + .ctx_in = &args, + .ctx_size_in = sizeof(args), + ); + + args.prog_fd = bpf_program__fd(hid_skel->progs.filter_switch); + + prog_fd = bpf_program__fd(hid_skel->progs.attach_prog); + + err = bpf_prog_test_run_opts(prog_fd, &tattrs); + if (err) + return err; + + return args.retval; /* the fd of the created bpf_link */ + } + +Our userspace program can now listen to notifications on the ring buffer, and +is awaken only when the value changes. + +When the userspace program doesn't need to listen to events anymore, it can just +close the returned fd from :c:func:`attach_filter`, which will tell the kernel to +detach the program from the HID device. + +Of course, in other use cases, the userspace program can also pin the fd to the +BPF filesystem through a call to :c:func:`bpf_obj_pin`, as with any bpf_link. + +Controlling the device +---------------------- + +To be able to change the haptic feedback from the tablet, the userspace program +needs to emit a feature report on the device itself. + +Instead of using hidraw for that, we can create a ``SEC("syscall")`` program +that talks to the device:: + + /* some more HID-BPF kfunc API definitions */ + extern struct hid_bpf_ctx *hid_bpf_allocate_context(unsigned int hid_id) __ksym; + extern void hid_bpf_release_context(struct hid_bpf_ctx *ctx) __ksym; + extern int hid_bpf_hw_request(struct hid_bpf_ctx *ctx, + __u8* data, + size_t len, + enum hid_report_type type, + enum hid_class_request reqtype) __ksym; + + + struct hid_send_haptics_args { + /* data needs to come at offset 0 so we can do a memcpy into it */ + __u8 data[10]; + unsigned int hid; + }; + + SEC("syscall") + int send_haptic(struct hid_send_haptics_args *args) + { + struct hid_bpf_ctx *ctx; + int ret = 0; + + ctx = hid_bpf_allocate_context(args->hid); + if (!ctx) + return 0; /* EPERM check */ + + ret = hid_bpf_hw_request(ctx, + args->data, + 10, + HID_FEATURE_REPORT, + HID_REQ_SET_REPORT); + + hid_bpf_release_context(ctx); + + return ret; + } + +And then userspace needs to call that program directly:: + + static int set_haptic(struct hid *hid_skel, int hid_id, __u8 haptic_value) + { + int err, prog_fd; + int ret = -1; + struct hid_send_haptics_args args = { + .hid = hid_id, + }; + DECLARE_LIBBPF_OPTS(bpf_test_run_opts, tattrs, + .ctx_in = &args, + .ctx_size_in = sizeof(args), + ); + + args.data[0] = 0x02; /* report ID of the feature on our device */ + args.data[1] = haptic_value; + + prog_fd = bpf_program__fd(hid_skel->progs.set_haptic); + + err = bpf_prog_test_run_opts(prog_fd, &tattrs); + return err; + } + +Now our userspace program is aware of the haptic state and can control it. The +program could make this state further available to other userspace programs +(e.g. via a DBus API). + +The interesting bit here is that we did not created a new kernel API for this. +Which means that if there is a bug in our implementation, we can change the +interface with the kernel at-will, because the userspace application is +responsible for its own usage. diff --git a/Documentation/hid/hiddev.rst b/Documentation/hid/hiddev.rst index caebc6266603..9b82c7f896aa 100644 --- a/Documentation/hid/hiddev.rst +++ b/Documentation/hid/hiddev.rst @@ -8,7 +8,7 @@ Introduction In addition to the normal input type HID devices, USB also uses the human interface device protocols for things that are not really human interfaces, but have similar sorts of communication needs. The two big -examples for this are power devices (especially uninterruptable power +examples for this are power devices (especially uninterruptible power supplies) and monitor control on higher end monitors. To support these disparate requirements, the Linux USB system provides diff --git a/Documentation/hid/hidraw.rst b/Documentation/hid/hidraw.rst index b717ee5cdaef..14d076753b85 100644 --- a/Documentation/hid/hidraw.rst +++ b/Documentation/hid/hidraw.rst @@ -163,7 +163,7 @@ HIDIOCGOUTPUT(len): Get an Output Report This ioctl will request an output report from the device using the control -endpoint. Typically, this is used to retrive the initial state of +endpoint. Typically, this is used to retrieve the initial state of an output report of a device, before an application updates it as necessary either via a HIDIOCSOUTPUT request, or the regular device write() interface. The format of the buffer issued with this report is identical to that of HIDIOCGFEATURE. diff --git a/Documentation/hid/index.rst b/Documentation/hid/index.rst index e50f513c579c..b2028f382f11 100644 --- a/Documentation/hid/index.rst +++ b/Documentation/hid/index.rst @@ -11,6 +11,7 @@ Human Interface Devices (HID) hidraw hid-sensor hid-transport + hid-bpf uhid diff --git a/Documentation/hid/intel-ish-hid.rst b/Documentation/hid/intel-ish-hid.rst index 7a851252267a..42dc77b7b10f 100644 --- a/Documentation/hid/intel-ish-hid.rst +++ b/Documentation/hid/intel-ish-hid.rst @@ -199,7 +199,7 @@ the sender that the memory region for that message may be reused. DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message (that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK. Additionally to DMA address communication, this sequence checks capabilities: -if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't +if the host doesn't support DMA, then it won't send DMA allocation, so FW can't send DMA; if FW doesn't support DMA then it won't respond with DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers. Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER, @@ -344,8 +344,8 @@ Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space. To debug ISH, event tracing mechanism is used. To enable debug logs:: - echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable - cat /sys/kernel/debug/tracing/trace + echo 1 > /sys/kernel/tracing/events/intel_ish/enable + cat /sys/kernel/tracing/trace 3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260 ----------------------------------------------------- diff --git a/Documentation/hwmon/aht10.rst b/Documentation/hwmon/aht10.rst index 482262ca117c..4e198c5eb683 100644 --- a/Documentation/hwmon/aht10.rst +++ b/Documentation/hwmon/aht10.rst @@ -38,7 +38,7 @@ Sysfs entries ------------- =============== ============================================ -temp1_input Measured temperature in millidegrees Celcius +temp1_input Measured temperature in millidegrees Celsius humidity1_input Measured humidity in %H update_interval The minimum interval for polling the sensor, in milliseconds. Writable. Must be at diff --git a/Documentation/hwmon/aquacomputer_d5next.rst b/Documentation/hwmon/aquacomputer_d5next.rst index 637bdbc8fcad..7d0d015b1a52 100644 --- a/Documentation/hwmon/aquacomputer_d5next.rst +++ b/Documentation/hwmon/aquacomputer_d5next.rst @@ -5,12 +5,15 @@ Kernel driver aquacomputer-d5next Supported devices: +* Aquacomputer Aquaero 5/6 fan controllers * Aquacomputer D5 Next watercooling pump * Aquacomputer Farbwerk RGB controller * Aquacomputer Farbwerk 360 RGB controller * Aquacomputer Octo fan controller * Aquacomputer Quadro fan controller * Aquacomputer High Flow Next sensor +* Aquacomputer Aquastream Ultimate watercooling pump +* Aquacomputer Poweradjust 3 fan controller Author: Aleksa Savic @@ -20,6 +23,10 @@ Description This driver exposes hardware sensors of listed Aquacomputer devices, which communicate through proprietary USB HID protocols. +The Aquaero devices expose eight physical, eight virtual and four calculated +virtual temperature sensors, as well as two flow sensors. The fans expose their +speed (in RPM), power, voltage and current. + For the D5 Next pump, available sensors are pump and fan speed, power, voltage and current, as well as coolant temperature and eight virtual temp sensors. Also available through debugfs are the serial number, firmware version and power-on @@ -48,6 +55,12 @@ The High Flow Next exposes +5V voltages, water quality, conductivity and flow re A temperature sensor can be connected to it, in which case it provides its reading and an estimation of the dissipated/absorbed power in the liquid cooling loop. +The Aquastream Ultimate pump exposes coolant temp and an external temp sensor, along +with speed, power, voltage and current of both the pump and optionally connected fan. +It also exposes pressure and flow speed readings. + +The Poweradjust 3 controller exposes a single external temperature sensor. + 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/aspeed-pwm-tacho.rst b/Documentation/hwmon/aspeed-pwm-tacho.rst index 6dcec845fbc7..f7bbe96f4bc8 100644 --- a/Documentation/hwmon/aspeed-pwm-tacho.rst +++ b/Documentation/hwmon/aspeed-pwm-tacho.rst @@ -10,7 +10,7 @@ Authors: Description: ------------ This driver implements support for ASPEED AST2400/2500 PWM and Fan Tacho -controller. The PWM controller supports upto 8 PWM outputs. The Fan tacho +controller. The PWM controller supports up to 8 PWM outputs. The Fan tacho controller supports up to 16 tachometer inputs. The driver provides the following sensor accesses in sysfs: diff --git a/Documentation/hwmon/asus_ec_sensors.rst b/Documentation/hwmon/asus_ec_sensors.rst index 02f4ad314a1e..a4039f2f9ca4 100644 --- a/Documentation/hwmon/asus_ec_sensors.rst +++ b/Documentation/hwmon/asus_ec_sensors.rst @@ -23,6 +23,7 @@ Supported boards: * ROG STRIX X570-I GAMING * ROG STRIX Z690-A GAMING WIFI D4 * ROG ZENITH II EXTREME + * ROG ZENITH II EXTREME ALPHA Authors: - Eugene Shalygin <eugene.shalygin@gmail.com> diff --git a/Documentation/hwmon/corsair-psu.rst b/Documentation/hwmon/corsair-psu.rst index 6a03edb551a8..c389bd21f4f2 100644 --- a/Documentation/hwmon/corsair-psu.rst +++ b/Documentation/hwmon/corsair-psu.rst @@ -40,7 +40,7 @@ This driver implements the sysfs interface for the Corsair PSUs with a HID proto interface of the HXi and RMi series. These power supplies provide access to a micro-controller with 2 attached temperature sensors, 1 fan rpm sensor, 4 sensors for volt levels, 4 sensors for -power usage and 4 sensors for current levels and addtional non-sensor information +power usage and 4 sensors for current levels and additional non-sensor information like uptimes. Sysfs entries diff --git a/Documentation/hwmon/ftsteutates.rst b/Documentation/hwmon/ftsteutates.rst index 58a2483d8d0d..b3bfec36661d 100644 --- a/Documentation/hwmon/ftsteutates.rst +++ b/Documentation/hwmon/ftsteutates.rst @@ -22,6 +22,15 @@ enhancements. It can monitor up to 4 voltages, 16 temperatures and 8 fans. It also contains an integrated watchdog which is currently implemented in this driver. +The ``pwmX_auto_channels_temp`` attributes show which temperature sensor +is currently driving which fan channel. This value might dynamically change +during runtime depending on the temperature sensor selected by +the fan control circuit. + +The 4 voltages require a board-specific multiplier, since the BMC can +only measure voltages up to 3.3V and thus relies on voltage dividers. +Consult your motherboard manual for details. + To clear a temperature or fan alarm, execute the following command with the correct path to the alarm file:: diff --git a/Documentation/hwmon/gsc-hwmon.rst b/Documentation/hwmon/gsc-hwmon.rst index ffac392a7129..e9ab27940d02 100644 --- a/Documentation/hwmon/gsc-hwmon.rst +++ b/Documentation/hwmon/gsc-hwmon.rst @@ -31,7 +31,7 @@ Temperature Monitoring Temperatures are measured with 12-bit or 10-bit resolution and are scaled either internally or by the driver depending on the GSC version and firmware. -The values returned by the driver reflect millidegree Celcius: +The values returned by the driver reflect millidegree Celsius: tempX_input Measured temperature. tempX_label Name of temperature input. @@ -41,8 +41,8 @@ PWM Output Control ------------------ The GSC features 1 PWM output that operates in automatic mode where the -PWM value will be scalled depending on 6 temperature boundaries. -The tempeature boundaries are read-write and in millidegree Celcius and the +PWM value will be scaled depending on 6 temperature boundaries. +The tempeature boundaries are read-write and in millidegree Celsius and the read-only PWM values range from 0 (off) to 255 (full speed). Fan speed will be set to minimum (off) when the temperature sensor reads less than pwm1_auto_point1_temp and maximum when the temperature sensor diff --git a/Documentation/hwmon/gxp-fan-ctrl.rst b/Documentation/hwmon/gxp-fan-ctrl.rst new file mode 100644 index 000000000000..ae3397e81c04 --- /dev/null +++ b/Documentation/hwmon/gxp-fan-ctrl.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +Kernel driver gxp-fan-ctrl +========================== + +Supported chips: + + * HPE GXP SOC + +Author: Nick Hawkins <nick.hawkins@hpe.com> + + +Description +----------- + +gxp-fan-ctrl is a driver which provides fan control for the hpe gxp soc. +The driver allows the gathering of fan status and the use of fan +PWM control. + + +Sysfs attributes +---------------- + +======================= =========================================================== +pwm[0-7] Fan 0 to 7 respective PWM value (0-255) +fan[0-7]_fault Fan 0 to 7 respective fault status: 1 fail, 0 ok +fan[0-7]_enable Fan 0 to 7 respective enabled status: 1 enabled, 0 disabled +======================= =========================================================== diff --git a/Documentation/hwmon/hwmon-kernel-api.rst b/Documentation/hwmon/hwmon-kernel-api.rst index f3276b3a381a..5451a6d4c874 100644 --- a/Documentation/hwmon/hwmon-kernel-api.rst +++ b/Documentation/hwmon/hwmon-kernel-api.rst @@ -57,7 +57,7 @@ register/unregister functions:: hwmon_device_register_with_groups registers a hardware monitoring device. The first parameter of this function is a pointer to the parent device. The name parameter is a pointer to the hwmon device name. The registration -function wil create a name sysfs attribute pointing to this name. +function will create a name sysfs attribute pointing to this name. The drvdata parameter is the pointer to the local driver data. hwmon_device_register_with_groups will attach this pointer to the newly allocated hwmon device. The pointer can be retrieved by the driver using @@ -299,7 +299,7 @@ Parameters: Return value: The file mode for this attribute. Typically, this will be 0 (the - attribute will not be created), S_IRUGO, or 'S_IRUGO | S_IWUSR'. + attribute will not be created), 0444, or 0644. :: @@ -360,7 +360,7 @@ functions is used. The header file linux/hwmon-sysfs.h provides a number of useful macros to declare and use hardware monitoring sysfs attributes. -In many cases, you can use the exsting define DEVICE_ATTR or its variants +In many cases, you can use the existing define DEVICE_ATTR or its variants DEVICE_ATTR_{RW,RO,WO} to declare such attributes. This is feasible if an attribute has no additional context. However, in many cases there will be additional information such as a sensor index which will need to be passed diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index fe2cc6b73634..f1fe75f596a5 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -1,6 +1,8 @@ -========================= -Linux Hardware Monitoring -========================= +.. SPDX-License-Identifier: GPL-2.0 + +=================== +Hardware Monitoring +=================== .. toctree:: :maxdepth: 1 @@ -73,6 +75,7 @@ Hardware Monitoring Kernel Drivers g762 gsc-hwmon gl518sm + gxp-fan-ctrl hih6130 ibmaem ibm-cffps @@ -144,6 +147,7 @@ Hardware Monitoring Kernel Drivers max6697 max8688 mc13783-adc + mc34vr500 mcp3021 menf21bmc mlxreg-fan diff --git a/Documentation/hwmon/it87.rst b/Documentation/hwmon/it87.rst index 2d83f23bee93..5cef4f265000 100644 --- a/Documentation/hwmon/it87.rst +++ b/Documentation/hwmon/it87.rst @@ -145,6 +145,22 @@ Supported chips: Datasheet: Not publicly available + * IT8792E/IT8795E + + Prefix: 'it8792' + + Addresses scanned: from Super I/O config space (8 I/O ports) + + Datasheet: Not publicly available + + * IT87952E + + Prefix: 'it87952' + + Addresses scanned: from Super I/O config space (8 I/O ports) + + Datasheet: Not publicly available + * SiS950 [clone of IT8705F] Prefix: 'it87' @@ -162,7 +178,7 @@ Authors: Module Parameters ----------------- -* update_vbat: int +* update_vbat bool 0 if vbat should report power on value, 1 if vbat should be updated after each read. Default is 0. On some boards the battery voltage is provided by either the battery or the onboard power supply. Only the first reading @@ -171,11 +187,31 @@ Module Parameters the chip so can be read at any time. Excessive reading may decrease battery life but no information is given in the datasheet. -* fix_pwm_polarity int +* fix_pwm_polarity bool Force PWM polarity to active high (DANGEROUS). Some chips are misconfigured by BIOS - PWM values would be inverted. This option tries to fix this. Please contact your BIOS manufacturer and ask him for fix. +* force_id short, short + + Force multiple chip ID to specified value, separated by ','. + For example "force_id=0x8689,0x8633". A value of 0 is ignored + for that chip. + Note: A single force_id value (e.g. "force_id=0x8689") is used for + all chips, to only set the first chip use "force_id=0x8689,0". + Should only be used for testing. + +* ignore_resource_conflict bool + + Similar to acpi_enforce_resources=lax, but only affects this driver. + ACPI resource conflicts are ignored if this parameter is provided and + set to 1. + Provided since there are reports that system-wide acpi_enfore_resources=lax + can result in boot failures on some systems. + Note: This is inherently risky since it means that both ACPI and this driver + may access the chip at the same time. This can result in race conditions and, + worst case, result in unexpected system reboots. + Hardware Interfaces ------------------- @@ -193,8 +229,8 @@ Description This driver implements support for the IT8603E, IT8620E, IT8623E, IT8628E, IT8705F, IT8712F, IT8716F, IT8718F, IT8720F, IT8721F, IT8726F, IT8728F, IT8732F, -IT8758E, IT8771E, IT8772E, IT8781F, IT8782F, IT8783E/F, IT8786E, IT8790E, and -SiS950 chips. +IT8758E, IT8771E, IT8772E, IT8781F, IT8782F, IT8783E/F, IT8786E, IT8790E, +IT8792E/IT8795E, IT87952E and SiS950 chips. These chips are 'Super I/O chips', supporting floppy disks, infrared ports, joysticks and other miscellaneous stuff. For hardware monitoring, they @@ -238,7 +274,8 @@ of the fan is not supported (value 0 of pwmX_enable). The IT8620E and IT8628E are custom designs, hardware monitoring part is similar to IT8728F. It only supports 16-bit fan mode. Both chips support up to 6 fans. -The IT8790E supports up to 3 fans. 16-bit fan mode is always enabled. +The IT8790E, IT8792E/IT8795E and IT87952E support up to 3 fans. 16-bit fan +mode is always enabled. The IT8732F supports a closed-loop mode for fan control, but this is not currently implemented by the driver. diff --git a/Documentation/hwmon/ltc2978.rst b/Documentation/hwmon/ltc2978.rst index b99a63965cfb..edf24e5e1e11 100644 --- a/Documentation/hwmon/ltc2978.rst +++ b/Documentation/hwmon/ltc2978.rst @@ -333,7 +333,7 @@ temp[N]_input Measured temperature. - On LTC3883, temp1 reports an external temperature, and temp2 reports the chip temperature. -temp[N]_min Mimimum temperature. +temp[N]_min Minimum temperature. LTC2972, LTC2974, LCT2977, LTM2980, LTC2978, LTC2979, and LTM2987 only. diff --git a/Documentation/hwmon/max16601.rst b/Documentation/hwmon/max16601.rst index 6a4eef8efbaf..c8c63a053e40 100644 --- a/Documentation/hwmon/max16601.rst +++ b/Documentation/hwmon/max16601.rst @@ -13,6 +13,14 @@ Supported chips: Datasheet: Not published + * Maxim MAX16600 + + Prefix: 'max16600' + + Addresses scanned: - + + Datasheet: Not published + * Maxim MAX16601 Prefix: 'max16601' @@ -36,7 +44,8 @@ Description ----------- This driver supports the MAX16508 VR13 Dual-Output Voltage Regulator -as well as the MAX16601 VR13.HC Dual-Output Voltage Regulator chipsets. +as well as the MAX16600, MAX16601, and MAX16602 VR13.HC Dual-Output +Voltage Regulator chipsets. The driver is a client driver to the core PMBus driver. Please see Documentation/hwmon/pmbus.rst for details on PMBus client drivers. diff --git a/Documentation/hwmon/max6697.rst b/Documentation/hwmon/max6697.rst index ffc5a7d8d33b..90ca224c446a 100644 --- a/Documentation/hwmon/max6697.rst +++ b/Documentation/hwmon/max6697.rst @@ -73,7 +73,7 @@ Description This driver implements support for several MAX6697 compatible temperature sensor chips. The chips support one local temperature sensor plus four, six, or seven remote temperature sensors. Remote temperature sensors are diode-connected -thermal transitors, except for MAX6698 which supports three diode-connected +thermal transistors, except for MAX6698 which supports three diode-connected thermal transistors plus three thermistors in addition to the local temperature sensor. diff --git a/Documentation/hwmon/mc34vr500.rst b/Documentation/hwmon/mc34vr500.rst new file mode 100644 index 000000000000..f82d872477ac --- /dev/null +++ b/Documentation/hwmon/mc34vr500.rst @@ -0,0 +1,32 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver mc34vr500 +======================= + +Supported Chips: + + * NXP MC34VR500 + + Prefix: 'mc34vr500' + + Datasheet: https://www.nxp.com/docs/en/data-sheet/MC34VR500.pdf + +Author: Mario Kicherer <dev@kicherer.org> + +Description +----------- + +This driver implements initial support for the NXP MC34VR500 PMIC. The MC34VR500 +monitors the temperature, input voltage and output currents and provides +corresponding alarms. For the temperature, the chip can send interrupts if +the temperature rises above one of the following values: 110°, 120°, 125° and +130° Celsius. For the input voltage, an interrupt is sent when the voltage +drops below 2.8V. + +Currently, this driver only implements the input voltage and temperature +alarms. The interrupts are mapped as follows: + +<= 2.8V -> in0_min_alarm +>110°c -> temp1_max_alarm +>120°c -> temp1_crit_alarm +>130°c -> temp1_emergency_alarm diff --git a/Documentation/hwmon/menf21bmc.rst b/Documentation/hwmon/menf21bmc.rst index 978691d5956d..e7f3f67b38d4 100644 --- a/Documentation/hwmon/menf21bmc.rst +++ b/Documentation/hwmon/menf21bmc.rst @@ -7,7 +7,7 @@ Supported chips: Prefix: 'menf21bmc_hwmon' - Adresses scanned: - + Addresses scanned: - Author: Andreas Werner <andreas.werner@men.de> diff --git a/Documentation/hwmon/oxp-sensors.rst b/Documentation/hwmon/oxp-sensors.rst index 39c588ec5c50..566a8d5bde08 100644 --- a/Documentation/hwmon/oxp-sensors.rst +++ b/Documentation/hwmon/oxp-sensors.rst @@ -3,18 +3,21 @@ Kernel driver oxp-sensors ========================= -Author: +Authors: + - Derek John Clark <derekjohn.clark@gmail.com> - JoaquÃn Ignacio AramendÃa <samsagax@gmail.com> Description: ------------ -One X Player devices from One Netbook provide fan readings and fan control -through its Embedded Controller. +Handheld devices from One Netbook and Aya Neo provide fan readings and fan +control through their embedded controllers. -Currently only supports AMD boards from the One X Player and AOK ZOE lineup. -Intel boards could be supported if we could figure out the EC registers and -values to write to since the EC layout and model is different. +Currently only supports AMD boards from One X Player, AOK ZOE, and some Aya +Neo devices. One X Player Intel boards could be supported if we could figure +out the EC registers and values to write to since the EC layout and model is +different. Aya Neo devices preceding the AIR may not be supportable as the EC +model is different and do not appear to have manual control capabilities. Supported devices ----------------- @@ -22,6 +25,8 @@ Supported devices Currently the driver supports the following handhelds: - AOK ZOE A1 + - Aya Neo AIR + - Aya Neo AIR Pro - OneXPlayer AMD - OneXPlayer mini AMD - OneXPlayer mini AMD PRO diff --git a/Documentation/hwmon/pmbus-core.rst b/Documentation/hwmon/pmbus-core.rst index 84c5a4e40c40..cff93adf6e42 100644 --- a/Documentation/hwmon/pmbus-core.rst +++ b/Documentation/hwmon/pmbus-core.rst @@ -174,7 +174,7 @@ Read byte from page <page>, register <reg>. int (*read_word_data)(struct i2c_client *client, int page, int phase, int reg); -Read word from page <page>, phase <pase>, register <reg>. If the chip does not +Read word from page <page>, phase <phase>, register <reg>. If the chip does not support multiple phases, the phase parameter can be ignored. If the chip supports multiple phases, a phase value of 0xff indicates all phases. diff --git a/Documentation/hwmon/sht4x.rst b/Documentation/hwmon/sht4x.rst index c318e5582ead..daf21e763425 100644 --- a/Documentation/hwmon/sht4x.rst +++ b/Documentation/hwmon/sht4x.rst @@ -37,7 +37,7 @@ Sysfs entries ------------- =============== ============================================ -temp1_input Measured temperature in millidegrees Celcius +temp1_input Measured temperature in millidegrees Celsius humidity1_input Measured humidity in %H update_interval The minimum interval for polling the sensor, in milliseconds. Writable. Must be at least diff --git a/Documentation/hwmon/smm665.rst b/Documentation/hwmon/smm665.rst index a0e27f62b57b..481e69d8bf39 100644 --- a/Documentation/hwmon/smm665.rst +++ b/Documentation/hwmon/smm665.rst @@ -180,7 +180,7 @@ in9_crit_alarm AIN1 critical alarm in10_crit_alarm AIN2 critical alarm temp1_input Chip temperature -temp1_min Mimimum 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/hwmon/stpddc60.rst b/Documentation/hwmon/stpddc60.rst index 7f7ce7f7871b..0c31f78fe58b 100644 --- a/Documentation/hwmon/stpddc60.rst +++ b/Documentation/hwmon/stpddc60.rst @@ -39,7 +39,7 @@ output voltage as a positive or negative offset in the interval 50mV to 400mV in 50mV steps. This means that the absolute values of the limits will change when the commanded output voltage changes. Also, care should be taken when writing to those limits since in the worst case the commanded output voltage -could change at the same time as the limit is written to, wich will lead to +could change at the same time as the limit is written to, which will lead to unpredictable results. diff --git a/Documentation/hwmon/submitting-patches.rst b/Documentation/hwmon/submitting-patches.rst index d953ee763c96..6482c4f137dc 100644 --- a/Documentation/hwmon/submitting-patches.rst +++ b/Documentation/hwmon/submitting-patches.rst @@ -126,7 +126,7 @@ increase the chances of your change being accepted. * Use devm_hwmon_device_register_with_info() or, if your driver needs a remove function, hwmon_device_register_with_info() to register your driver with the hwmon subsystem. Try using devm_add_action() instead of a remove function if - possible. Do not use hwmon_device_register(). + possible. Do not use any of the deprecated registration functions. * Your driver should be buildable as module. If not, please be prepared to explain why it has to be built into the kernel. diff --git a/Documentation/hwmon/vexpress.rst b/Documentation/hwmon/vexpress.rst index 8c861c8151ac..7fc99f75b3b1 100644 --- a/Documentation/hwmon/vexpress.rst +++ b/Documentation/hwmon/vexpress.rst @@ -27,7 +27,7 @@ Versatile Express platform (http://www.arm.com/versatileexpress/) is a reference & prototyping system for ARM Ltd. processors. It can be set up from a wide range of boards, each of them containing (apart of the main chip/FPGA) a number of microcontrollers responsible for platform -configuration and control. Theses microcontrollers can also monitor the +configuration and control. These microcontrollers can also monitor the board and its environment by a number of internal and external sensors, providing information about power lines voltages and currents, board temperature and power usage. Some of them also calculate consumed energy diff --git a/Documentation/hwmon/via686a.rst b/Documentation/hwmon/via686a.rst index 7ab9ddebcf79..8c52a9207bcb 100644 --- a/Documentation/hwmon/via686a.rst +++ b/Documentation/hwmon/via686a.rst @@ -58,7 +58,7 @@ representable value is around 2600 RPM. Voltage sensors (also known as IN sensors) report their values in volts. An alarm is triggered if the voltage has crossed a programmable minimum -or maximum limit. Voltages are internally scalled, so each voltage channel +or maximum limit. Voltages are internally scaled, so each voltage channel has a different resolution and range. If an alarm triggers, it will remain triggered until the hardware register diff --git a/Documentation/input/index.rst b/Documentation/input/index.rst index 9888f5cbf6d5..35581cd18e91 100644 --- a/Documentation/input/index.rst +++ b/Documentation/input/index.rst @@ -1,6 +1,6 @@ -============================= -The Linux Input Documentation -============================= +=================== +Input Documentation +=================== Contents: diff --git a/Documentation/isdn/interface_capi.rst b/Documentation/isdn/interface_capi.rst index fe2421444b76..4d63b34b35cf 100644 --- a/Documentation/isdn/interface_capi.rst +++ b/Documentation/isdn/interface_capi.rst @@ -323,7 +323,7 @@ If the lowest bit of showcapimsgs is set, kernelcapi logs controller and application up and down events. In addition, every registered CAPI controller has an associated traceflag -parameter controlling how CAPI messages sent from and to tha controller are +parameter controlling how CAPI messages sent from and to the controller are logged. The traceflag parameter is initialized with the value of the showcapimsgs parameter when the controller is registered, but can later be changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE. diff --git a/Documentation/isdn/m_isdn.rst b/Documentation/isdn/m_isdn.rst index 9957de349e69..5847a164287e 100644 --- a/Documentation/isdn/m_isdn.rst +++ b/Documentation/isdn/m_isdn.rst @@ -3,7 +3,7 @@ mISDN Driver ============ mISDN is a new modular ISDN driver, in the long term it should replace -the old I4L driver architecture for passiv ISDN cards. +the old I4L driver architecture for passive ISDN cards. It was designed to allow a broad range of applications and interfaces but only have the basic function in kernel, the interface to the user space is based on sockets with a own address family AF_ISDN. diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst index 08f575e6236c..5202186728b4 100644 --- a/Documentation/kbuild/kbuild.rst +++ b/Documentation/kbuild/kbuild.rst @@ -278,6 +278,13 @@ To get all available archs you can also specify all. E.g.:: $ make ALLSOURCE_ARCHS=all tags +IGNORE_DIRS +----------- +For tags/TAGS/cscope targets, you can choose which directories won't +be included in the databases, separated by blank space. E.g.:: + + $ make IGNORE_DIRS="drivers/gpu/drm/radeon tools" cscope + KBUILD_BUILD_TIMESTAMP ---------------------- Setting this to a date string overrides the timestamp used in the diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index 6b7368d1f516..38bc74eaa547 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -1042,7 +1042,7 @@ $(clean-files). When executing "make clean", the file "crc32table.h" will be deleted. Kbuild will assume files to be in the same relative directory as the -Makefile, except if prefixed with $(objtree). +Makefile. To exclude certain files or directories from make clean, use the $(no-clean-files) variable. diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst index c756786e17ae..dff0646a717b 100644 --- a/Documentation/kernel-hacking/locking.rst +++ b/Documentation/kernel-hacking/locking.rst @@ -1277,11 +1277,11 @@ Manfred Spraul points out that you can still do this, even if the data is very occasionally accessed in user context or softirqs/tasklets. The irq handler doesn't use a lock, and all other accesses are done as so:: - spin_lock(&lock); + mutex_lock(&lock); disable_irq(irq); ... enable_irq(irq); - spin_unlock(&lock); + mutex_unlock(&lock); The disable_irq() prevents the irq handler from running (and waits for it to finish if it's currently running on other CPUs). diff --git a/Documentation/leds/index.rst b/Documentation/leds/index.rst index e5d63b940045..b9ca081fac71 100644 --- a/Documentation/leds/index.rst +++ b/Documentation/leds/index.rst @@ -26,3 +26,4 @@ LEDs leds-lp55xx leds-mlxcpld leds-sc27xx + leds-qcom-lpg diff --git a/Documentation/leds/leds-qcom-lpg.rst b/Documentation/leds/leds-qcom-lpg.rst index de7ceead9337..d6a76c38c581 100644 --- a/Documentation/leds/leds-qcom-lpg.rst +++ b/Documentation/leds/leds-qcom-lpg.rst @@ -34,7 +34,7 @@ Specify a hardware pattern for a Qualcomm LPG LED. The pattern is a series of brightness and hold-time pairs, with the hold-time expressed in milliseconds. The hold time is a property of the pattern and must -therefor be identical for each element in the pattern (except for the pauses +therefore be identical for each element in the pattern (except for the pauses described below). As the LPG hardware is not able to perform the linear transitions expected by the leds-trigger-pattern format, each entry in the pattern must be followed a zero-length entry of the same brightness. @@ -66,7 +66,7 @@ Low-pause pattern:: +-----------------------------> 0 5 10 15 20 25 time (100ms) -Similarily, the last entry can be stretched by using a higher hold-time on the +Similarly, the last entry can be stretched by using a higher hold-time on the last entry. In order to save space in the shared lookup table the LPG supports "ping-pong" diff --git a/Documentation/livepatch/module-elf-format.rst b/Documentation/livepatch/module-elf-format.rst index 7347638895a0..d48f530c0881 100644 --- a/Documentation/livepatch/module-elf-format.rst +++ b/Documentation/livepatch/module-elf-format.rst @@ -298,12 +298,5 @@ A livepatch module's symbol table is accessible through module->symtab. Since apply_relocate_add() requires access to a module's section headers, symbol table, and relocation section indices, Elf information is preserved for livepatch modules and is made accessible by the module loader through -module->klp_info, which is a klp_modinfo struct. When a livepatch module loads, -this struct is filled in by the module loader. Its fields are documented below:: - - struct klp_modinfo { - Elf_Ehdr hdr; /* Elf header */ - Elf_Shdr *sechdrs; /* Section header table */ - char *secstrings; /* String table for the section headers */ - unsigned int symndx; /* The symbol table section index */ - }; +module->klp_info, which is a :c:type:`klp_modinfo` struct. When a livepatch module +loads, this struct is filled in by the module loader. diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index 93b2ae6c34a9..cfd37f31077f 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -104,3 +104,4 @@ to do something different in the near future. ../riscv/patch-acceptance ../driver-api/media/maintainer-entry-profile ../driver-api/vfio-pci-device-specific-driver-acceptance + ../nvme/feature-and-quirk-policy diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index cc621decd943..06e14efd8662 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -1910,7 +1910,8 @@ There are some more advanced barrier functions: These are for use with consistent memory to guarantee the ordering of writes or reads of shared memory accessible to both the CPU and a - DMA capable device. + DMA capable device. See Documentation/core-api/dma-api.rst file for more + information about consistent memory. For example, consider a device driver that shares memory with a device and uses a descriptor status value to indicate if the descriptor belongs @@ -1931,22 +1932,21 @@ There are some more advanced barrier functions: /* assign ownership */ desc->status = DEVICE_OWN; - /* notify device of new descriptors */ + /* Make descriptor status visible to the device followed by + * notify device of new descriptor + */ writel(DESC_NOTIFY, doorbell); } - The dma_rmb() allows us guarantee the device has released ownership + The dma_rmb() allows us to guarantee that the device has released ownership before we read the data from the descriptor, and the dma_wmb() allows us to guarantee the data is written to the descriptor before the device can see it now has ownership. The dma_mb() implies both a dma_rmb() and - a dma_wmb(). Note that, when using writel(), a prior wmb() is not needed - to guarantee that the cache coherent memory writes have completed before - writing to the MMIO region. The cheaper writel_relaxed() does not provide - this guarantee and must not be used here. - - See the subsection "Kernel I/O barrier effects" for more information on - relaxed I/O accessors and the Documentation/core-api/dma-api.rst file for - more information on consistent memory. + a dma_wmb(). + + Note that the dma_*() barriers do not provide any ordering guarantees for + accesses to MMIO regions. See the later "KERNEL I/O BARRIER EFFECTS" + subsection for more information about I/O accessors and MMIO ordering. (*) pmem_wmb(); diff --git a/Documentation/mm/active_mm.rst b/Documentation/mm/active_mm.rst index 6f8269c284ed..45d89f8fb3a8 100644 --- a/Documentation/mm/active_mm.rst +++ b/Documentation/mm/active_mm.rst @@ -1,5 +1,3 @@ -.. _active_mm: - ========= Active MM ========= diff --git a/Documentation/mm/arch_pgtable_helpers.rst b/Documentation/mm/arch_pgtable_helpers.rst index fd2a19df884e..30d9a09f01f4 100644 --- a/Documentation/mm/arch_pgtable_helpers.rst +++ b/Documentation/mm/arch_pgtable_helpers.rst @@ -1,7 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 -.. _arch_page_table_helpers: - =============================== Architecture Page Table Helpers =============================== diff --git a/Documentation/mm/balance.rst b/Documentation/mm/balance.rst index 6a1fadf3e173..abaa78561c31 100644 --- a/Documentation/mm/balance.rst +++ b/Documentation/mm/balance.rst @@ -1,12 +1,10 @@ -.. _balance: - ================ Memory Balancing ================ Started Jan 2000 by Kanoj Sarcar <kanoj@sgi.com> -Memory balancing is needed for !__GFP_ATOMIC and !__GFP_KSWAPD_RECLAIM as +Memory balancing is needed for !__GFP_HIGH and !__GFP_KSWAPD_RECLAIM as well as for non __GFP_IO allocations. The first reason why a caller may avoid reclaim is that the caller can not diff --git a/Documentation/mm/damon/index.rst b/Documentation/mm/damon/index.rst index 48c0bbff98b2..5e0a50583500 100644 --- a/Documentation/mm/damon/index.rst +++ b/Documentation/mm/damon/index.rst @@ -4,8 +4,9 @@ DAMON: Data Access MONitor ========================== -DAMON is a data access monitoring framework subsystem for the Linux kernel. -The core mechanisms of DAMON (refer to :doc:`design` for the detail) make it +DAMON is a Linux kernel subsystem that provides a framework for data access +monitoring and the monitoring results based system operations. The core +monitoring mechanisms of DAMON (refer to :doc:`design` for the detail) make it - *accurate* (the monitoring output is useful enough for DRAM level memory management; It might not appropriate for CPU Cache levels, though), @@ -14,12 +15,16 @@ The core mechanisms of DAMON (refer to :doc:`design` for the detail) make it - *scalable* (the upper-bound of the overhead is in constant range regardless of the size of target workloads). -Using this framework, therefore, the kernel's memory management mechanisms can -make advanced decisions. Experimental memory management optimization works -that incurring high data accesses monitoring overhead could implemented again. -In user space, meanwhile, users who have some special workloads can write -personalized applications for better understanding and optimizations of their -workloads and systems. +Using this framework, therefore, the kernel can operate system in an +access-aware fashion. Because the features are also exposed to the user space, +users who have special information about their workloads can write personalized +applications for better understanding and optimizations of their workloads and +systems. + +For easier development of such systems, DAMON provides a feature called DAMOS +(DAMon-based Operation Schemes) in addition to the monitoring. Using the +feature, DAMON users in both kernel and user spaces can do access-aware system +operations with no code but simple configurations. .. toctree:: :maxdepth: 2 @@ -27,3 +32,4 @@ workloads and systems. faq design api + maintainer-profile diff --git a/Documentation/mm/damon/maintainer-profile.rst b/Documentation/mm/damon/maintainer-profile.rst new file mode 100644 index 000000000000..24a202f03de8 --- /dev/null +++ b/Documentation/mm/damon/maintainer-profile.rst @@ -0,0 +1,62 @@ +.. SPDX-License-Identifier: GPL-2.0 + +DAMON Maintainer Entry Profile +============================== + +The DAMON subsystem covers the files that listed in 'DATA ACCESS MONITOR' +section of 'MAINTAINERS' file. + +The mailing lists for the subsystem are damon@lists.linux.dev and +linux-mm@kvack.org. Patches should be made against the mm-unstable tree [1]_ +whenever possible and posted to the mailing lists. + +SCM Trees +--------- + +There are multiple Linux trees for DAMON development. Patches under +development or testing are queued in damon/next [2]_ by the DAMON maintainer. +Suffieicntly reviewed patches will be queued in mm-unstable [1]_ by the memory +management subsystem maintainer. After more sufficient tests, the patches will +be queued in mm-stable [3]_ , and finally pull-requested to the mainline by the +memory management subsystem maintainer. + +Note again the patches for review should be made against the mm-unstable +tree[1] whenever possible. damon/next is only for preview of others' works in +progress. + +Submit checklist addendum +------------------------- + +When making DAMON changes, you should do below. + +- Build changes related outputs including kernel and documents. +- Ensure the builds introduce no new errors or warnings. +- Run and ensure no new failures for DAMON selftests [4]_ and kunittests [5]_ . + +Further doing below and putting the results will be helpful. + +- Run damon-tests/corr [6]_ for normal changes. +- Run damon-tests/perf [7]_ for performance changes. + +Key cycle dates +--------------- + +Patches can be sent anytime. Key cycle dates of the mm-unstable[1] and +mm-stable[3] trees depend on the memory management subsystem maintainer. + +Review cadence +-------------- + +The DAMON maintainer does the work on the usual work hour (09:00 to 17:00, +Mon-Fri) in PST. The response to patches will occasionally be slow. Do not +hesitate to send a ping if you have not heard back within a week of sending a +patch. + + +.. [1] https://git.kernel.org/akpm/mm/h/mm-unstable +.. [2] https://git.kernel.org/sj/h/damon/next +.. [3] https://git.kernel.org/akpm/mm/h/mm-stable +.. [4] https://github.com/awslabs/damon-tests/blob/master/corr/run.sh#L49 +.. [5] https://github.com/awslabs/damon-tests/blob/master/corr/tests/kunit.sh +.. [6] https://github.com/awslabs/damon-tests/tree/master/corr +.. [7] https://github.com/awslabs/damon-tests/tree/master/perf diff --git a/Documentation/mm/free_page_reporting.rst b/Documentation/mm/free_page_reporting.rst index 8c05e62d8b2b..1468f71c261f 100644 --- a/Documentation/mm/free_page_reporting.rst +++ b/Documentation/mm/free_page_reporting.rst @@ -1,5 +1,3 @@ -.. _free_page_reporting: - ===================== Free Page Reporting ===================== diff --git a/Documentation/mm/frontswap.rst b/Documentation/mm/frontswap.rst index feecc5e24477..c892412988af 100644 --- a/Documentation/mm/frontswap.rst +++ b/Documentation/mm/frontswap.rst @@ -1,5 +1,3 @@ -.. _frontswap: - ========= Frontswap ========= diff --git a/Documentation/mm/highmem.rst b/Documentation/mm/highmem.rst index 0f731d9196b0..c964e0848702 100644 --- a/Documentation/mm/highmem.rst +++ b/Documentation/mm/highmem.rst @@ -1,5 +1,3 @@ -.. _highmem: - ==================== High Memory Handling ==================== @@ -57,7 +55,8 @@ list shows them in order of preference of use. 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 be preferred, where feasible, over all the others. + This function should always be used, whereas kmap_atomic() and kmap() have + been deprecated. These mappings are thread-local and CPU-local, meaning that the mapping can only be accessed from within this thread and the thread is bound to the @@ -82,7 +81,7 @@ list shows them in order of preference of use. for pages which are known to not come from ZONE_HIGHMEM. However, it is always safe to use kmap_local_page() / kunmap_local(). - While it is significantly faster than kmap(), for the higmem case it + While it is significantly faster than kmap(), for the highmem case it comes 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 @@ -100,10 +99,21 @@ list shows them in order of preference of use. (included in the "Functions" section) for details on how to manage nested mappings. -* kmap_atomic(). This permits a very short duration mapping of a single - page. Since the mapping is restricted to the CPU that issued it, it - performs well, but the issuing task is therefore required to stay on that - CPU until it has finished, lest some other task displace its mappings. +* kmap_atomic(). This function has been deprecated; use kmap_local_page(). + + NOTE: Conversions to kmap_local_page() must take care to follow the mapping + restrictions imposed on kmap_local_page(). Furthermore, the code between + calls to kmap_atomic() and kunmap_atomic() may implicitly depend on the side + effects of atomic mappings, i.e. disabling page faults or preemption, or both. + In that case, explicit calls to pagefault_disable() or preempt_disable() or + both must be made in conjunction with the use of kmap_local_page(). + + [Legacy documentation] + + This permits a very short duration mapping of a single page. Since the + mapping is restricted to the CPU that issued it, it performs well, but + the issuing task is therefore required to stay on that CPU until it has + finished, lest some other task displace its mappings. kmap_atomic() may also be used by interrupt contexts, since it does not sleep and the callers too may not sleep until after kunmap_atomic() is @@ -115,11 +125,20 @@ list shows them in order of preference of use. It is assumed that k[un]map_atomic() won't fail. -* kmap(). This should be used to make short duration mapping of a single - page with no restrictions on preemption or migration. It comes with an - overhead as mapping space is restricted and protected by a global lock - for synchronization. When mapping is no longer needed, the address that - the page was mapped to must be released with kunmap(). +* kmap(). This function has been deprecated; use kmap_local_page(). + + NOTE: Conversions to kmap_local_page() must take care to follow the mapping + restrictions imposed on kmap_local_page(). In particular, it is necessary to + make sure that the kernel virtual memory pointer is only valid in the thread + that obtained it. + + [Legacy documentation] + + This should be used to make short duration mapping of a single page with no + restrictions on preemption or migration. It comes with an overhead as mapping + space is restricted and protected by a global lock for synchronization. When + mapping is no longer needed, the address that the page was mapped to must be + released with kunmap(). Mapping changes must be propagated across all the CPUs. kmap() also requires global TLB invalidation when the kmap's pool wraps and it might diff --git a/Documentation/mm/hmm.rst b/Documentation/mm/hmm.rst index f2a59ed82ed3..9aa512c3a12c 100644 --- a/Documentation/mm/hmm.rst +++ b/Documentation/mm/hmm.rst @@ -1,5 +1,3 @@ -.. _hmm: - ===================================== Heterogeneous Memory Management (HMM) ===================================== @@ -304,7 +302,7 @@ devm_memunmap_pages(), and devm_release_mem_region() when the resources can be tied to a ``struct device``. The overall migration steps are similar to migrating NUMA pages within system -memory (see :ref:`Page migration <page_migration>`) but the steps are split +memory (see Documentation/mm/page_migration.rst) but the steps are split between device driver specific code and shared common code: 1. ``mmap_read_lock()`` diff --git a/Documentation/mm/hugetlbfs_reserv.rst b/Documentation/mm/hugetlbfs_reserv.rst index f143954e0d05..3d05d64de9b4 100644 --- a/Documentation/mm/hugetlbfs_reserv.rst +++ b/Documentation/mm/hugetlbfs_reserv.rst @@ -1,5 +1,3 @@ -.. _hugetlbfs_reserve: - ===================== Hugetlbfs Reservation ===================== @@ -7,7 +5,7 @@ Hugetlbfs Reservation Overview ======== -Huge pages as described at :ref:`hugetlbpage` are typically +Huge pages as described at Documentation/mm/hugetlbpage.rst are typically preallocated for application use. These huge pages are instantiated in a task's address space at page fault time if the VMA indicates huge pages are to be used. If no huge page exists at page fault time, the task is sent @@ -181,14 +179,14 @@ Consuming Reservations/Allocating a Huge Page Reservations are consumed when huge pages associated with the reservations are allocated and instantiated in the corresponding mapping. The allocation -is performed within the routine alloc_huge_page():: +is performed within the routine alloc_hugetlb_folio():: - struct page *alloc_huge_page(struct vm_area_struct *vma, + struct folio *alloc_hugetlb_folio(struct vm_area_struct *vma, unsigned long addr, int avoid_reserve) -alloc_huge_page is passed a VMA pointer and a virtual address, so it can +alloc_hugetlb_folio is passed a VMA pointer and a virtual address, so it can consult the reservation map to determine if a reservation exists. In addition, -alloc_huge_page takes the argument avoid_reserve which indicates reserves +alloc_hugetlb_folio takes the argument avoid_reserve which indicates reserves should not be used even if it appears they have been set aside for the specified address. The avoid_reserve argument is most often used in the case of Copy on Write and Page Migration where additional copies of an existing @@ -208,7 +206,8 @@ a reservation for the allocation. After determining whether a reservation exists and can be used for the allocation, the routine dequeue_huge_page_vma() is called. This routine takes two arguments related to reservations: -- avoid_reserve, this is the same value/argument passed to alloc_huge_page() +- avoid_reserve, this is the same value/argument passed to + alloc_hugetlb_folio(). - chg, even though this argument is of type long only the values 0 or 1 are passed to dequeue_huge_page_vma. If the value is 0, it indicates a reservation exists (see the section "Memory Policy and Reservations" for @@ -233,9 +232,9 @@ the scope reservations. Even if a surplus page is allocated, the same reservation based adjustments as above will be made: SetPagePrivate(page) and resv_huge_pages--. -After obtaining a new huge page, (page)->private is set to the value of -the subpool associated with the page if it exists. This will be used for -subpool accounting when the page is freed. +After obtaining a new hugetlb folio, (folio)->_hugetlb_subpool is set to the +value of the subpool associated with the page if it exists. This will be used +for subpool accounting when the folio is freed. The routine vma_commit_reservation() is then called to adjust the reserve map based on the consumption of the reservation. In general, this involves @@ -246,8 +245,8 @@ was no reservation in a shared mapping or this was a private mapping a new entry must be created. It is possible that the reserve map could have been changed between the call -to vma_needs_reservation() at the beginning of alloc_huge_page() and the -call to vma_commit_reservation() after the page was allocated. This would +to vma_needs_reservation() at the beginning of alloc_hugetlb_folio() and the +call to vma_commit_reservation() after the folio was allocated. This would be possible if hugetlb_reserve_pages was called for the same page in a shared mapping. In such cases, the reservation count and subpool free page count will be off by one. This rare condition can be identified by comparing the diff --git a/Documentation/mm/hwpoison.rst b/Documentation/mm/hwpoison.rst index b9d5253c1305..ba48a441feed 100644 --- a/Documentation/mm/hwpoison.rst +++ b/Documentation/mm/hwpoison.rst @@ -1,5 +1,3 @@ -.. hwpoison: - ======== hwpoison ======== diff --git a/Documentation/mm/index.rst b/Documentation/mm/index.rst index 4aa12b8be278..5a94a921ea40 100644 --- a/Documentation/mm/index.rst +++ b/Documentation/mm/index.rst @@ -1,6 +1,6 @@ -===================================== -Linux Memory Management Documentation -===================================== +=============================== +Memory Management Documentation +=============================== Memory Management Guide ======================= diff --git a/Documentation/mm/ksm.rst b/Documentation/mm/ksm.rst index f83cfbc12f4c..2806e3e4a10e 100644 --- a/Documentation/mm/ksm.rst +++ b/Documentation/mm/ksm.rst @@ -1,5 +1,3 @@ -.. _ksm: - ======================= Kernel Samepage Merging ======================= @@ -8,7 +6,7 @@ KSM is a memory-saving de-duplication feature, enabled by CONFIG_KSM=y, added to the Linux kernel in 2.6.32. See ``mm/ksm.c`` for its implementation, and http://lwn.net/Articles/306704/ and https://lwn.net/Articles/330589/ -The userspace interface of KSM is described in :ref:`Documentation/admin-guide/mm/ksm.rst <admin_guide_ksm>` +The userspace interface of KSM is described in Documentation/admin-guide/mm/ksm.rst Design ====== diff --git a/Documentation/mm/memory-model.rst b/Documentation/mm/memory-model.rst index 3779e562dc76..5f3eafbbc520 100644 --- a/Documentation/mm/memory-model.rst +++ b/Documentation/mm/memory-model.rst @@ -1,7 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 -.. _physical_memory_model: - ===================== Physical Memory Model ===================== diff --git a/Documentation/mm/mmu_notifier.rst b/Documentation/mm/mmu_notifier.rst index df5d7777fc6b..c687bea4922f 100644 --- a/Documentation/mm/mmu_notifier.rst +++ b/Documentation/mm/mmu_notifier.rst @@ -1,5 +1,3 @@ -.. _mmu_notifier: - When do you need to notify inside page table lock ? =================================================== diff --git a/Documentation/mm/multigen_lru.rst b/Documentation/mm/multigen_lru.rst index d7062c6a8946..5f1f6ecbb79b 100644 --- a/Documentation/mm/multigen_lru.rst +++ b/Documentation/mm/multigen_lru.rst @@ -89,15 +89,15 @@ variables are monotonically increasing. Generation numbers are truncated into ``order_base_2(MAX_NR_GENS+1)`` bits in order to fit into the gen counter in ``folio->flags``. Each -truncated generation number is an index to ``lrugen->lists[]``. The +truncated generation number is an index to ``lrugen->folios[]``. The sliding window technique is used to track at least ``MIN_NR_GENS`` and at most ``MAX_NR_GENS`` generations. The gen counter stores a value within ``[1, MAX_NR_GENS]`` while a page is on one of -``lrugen->lists[]``; otherwise it stores zero. +``lrugen->folios[]``; otherwise it stores zero. Each generation is divided into multiple tiers. A page accessed ``N`` times through file descriptors is in tier ``order_base_2(N)``. Unlike -generations, tiers do not have dedicated ``lrugen->lists[]``. In +generations, tiers do not have dedicated ``lrugen->folios[]``. In contrast to moving across generations, which requires the LRU lock, moving across tiers only involves atomic operations on ``folio->flags`` and therefore has a negligible cost. A feedback loop @@ -127,7 +127,7 @@ page mapped by this PTE to ``(max_seq%MAX_NR_GENS)+1``. Eviction -------- The eviction consumes old generations. Given an ``lruvec``, it -increments ``min_seq`` when ``lrugen->lists[]`` indexed by +increments ``min_seq`` when ``lrugen->folios[]`` indexed by ``min_seq%MAX_NR_GENS`` becomes empty. To select a type and a tier to evict from, it first compares ``min_seq[]`` to select the older type. If both types are equally old, it selects the one whose first tier has @@ -141,9 +141,85 @@ loop has detected outlying refaults from the tier this page is in. To this end, the feedback loop uses the first tier as the baseline, for the reason stated earlier. +Working set protection +---------------------- +Each generation is timestamped at birth. If ``lru_gen_min_ttl`` is +set, an ``lruvec`` is protected from the eviction when its oldest +generation was born within ``lru_gen_min_ttl`` milliseconds. In other +words, it prevents the working set of ``lru_gen_min_ttl`` milliseconds +from getting evicted. The OOM killer is triggered if this working set +cannot be kept in memory. + +This time-based approach has the following advantages: + +1. It is easier to configure because it is agnostic to applications + and memory sizes. +2. It is more reliable because it is directly wired to the OOM killer. + +Rmap/PT walk feedback +--------------------- +Searching the rmap for PTEs mapping each page on an LRU list (to test +and clear the accessed bit) can be expensive because pages from +different VMAs (PA space) are not cache friendly to the rmap (VA +space). For workloads mostly using mapped pages, searching the rmap +can incur the highest CPU cost in the reclaim path. + +``lru_gen_look_around()`` exploits spatial locality to reduce the +trips into the rmap. It scans the adjacent PTEs of a young PTE and +promotes hot pages. If the scan was done cacheline efficiently, it +adds the PMD entry pointing to the PTE table to the Bloom filter. This +forms a feedback loop between the eviction and the aging. + +Bloom Filters +------------- +Bloom filters are a space and memory efficient data structure for set +membership test, i.e., test if an element is not in the set or may be +in the set. + +In the eviction path, specifically, in ``lru_gen_look_around()``, if a +PMD has a sufficient number of hot pages, its address is placed in the +filter. In the aging path, set membership means that the PTE range +will be scanned for young pages. + +Note that Bloom filters are probabilistic on set membership. If a test +is false positive, the cost is an additional scan of a range of PTEs, +which may yield hot pages anyway. Parameters of the filter itself can +control the false positive rate in the limit. + +Memcg LRU +--------- +An memcg LRU is a per-node LRU of memcgs. It is also an LRU of LRUs, +since each node and memcg combination has an LRU of folios (see +``mem_cgroup_lruvec()``). Its goal is to improve the scalability of +global reclaim, which is critical to system-wide memory overcommit in +data centers. Note that memcg LRU only applies to global reclaim. + +The basic structure of an memcg LRU can be understood by an analogy to +the active/inactive LRU (of folios): + +1. It has the young and the old (generations), i.e., the counterparts + to the active and the inactive; +2. The increment of ``max_seq`` triggers promotion, i.e., the + counterpart to activation; +3. Other events trigger similar operations, e.g., offlining an memcg + triggers demotion, i.e., the counterpart to deactivation. + +In terms of global reclaim, it has two distinct features: + +1. Sharding, which allows each thread to start at a random memcg (in + the old generation) and improves parallelism; +2. Eventual fairness, which allows direct reclaim to bail out at will + and reduces latency without affecting fairness over some time. + +In terms of traversing memcgs during global reclaim, it improves the +best-case complexity from O(n) to O(1) and does not affect the +worst-case complexity O(n). Therefore, on average, it has a sublinear +complexity. + Summary ------- -The multi-gen LRU can be disassembled into the following parts: +The multi-gen LRU (of folios) can be disassembled into the following +parts: * Generations * Rmap walks diff --git a/Documentation/mm/numa.rst b/Documentation/mm/numa.rst index 99fdeca917ca..0f1b56809dca 100644 --- a/Documentation/mm/numa.rst +++ b/Documentation/mm/numa.rst @@ -1,5 +1,3 @@ -.. _numa: - Started Nov 1999 by Kanoj Sarcar <kanoj@sgi.com> ============= @@ -64,7 +62,7 @@ In addition, for some architectures, again x86 is an example, Linux supports the emulation of additional nodes. For NUMA emulation, linux will carve up the existing nodes--or the system memory for non-NUMA platforms--into multiple nodes. Each emulated node will manage a fraction of the underlying cells' -physical memory. NUMA emluation is useful for testing NUMA kernel and +physical memory. NUMA emulation is useful for testing NUMA kernel and application features on non-NUMA platforms, and as a sort of memory resource management mechanism when used together with cpusets. [see Documentation/admin-guide/cgroup-v1/cpusets.rst] @@ -110,7 +108,7 @@ to improve NUMA locality using various CPU affinity command line interfaces, such as taskset(1) and numactl(1), and program interfaces such as sched_setaffinity(2). Further, one can modify the kernel's default local allocation behavior using Linux NUMA memory policy. [see -:ref:`Documentation/admin-guide/mm/numa_memory_policy.rst <numa_memory_policy>`]. +Documentation/admin-guide/mm/numa_memory_policy.rst]. System administrators can restrict the CPUs and nodes' memories that a non- privileged user can specify in the scheduling or NUMA commands and functions diff --git a/Documentation/mm/page_frags.rst b/Documentation/mm/page_frags.rst index 7d6f9385d129..a81617e688a8 100644 --- a/Documentation/mm/page_frags.rst +++ b/Documentation/mm/page_frags.rst @@ -1,5 +1,3 @@ -.. _page_frags: - ============== Page fragments ============== diff --git a/Documentation/mm/page_migration.rst b/Documentation/mm/page_migration.rst index 11493bad7112..313dce18893e 100644 --- a/Documentation/mm/page_migration.rst +++ b/Documentation/mm/page_migration.rst @@ -1,5 +1,3 @@ -.. _page_migration: - ============== Page migration ============== @@ -9,8 +7,8 @@ nodes in a NUMA system while the process is running. This means that the virtual addresses that the process sees do not change. However, the system rearranges the physical location of those pages. -Also see :ref:`Heterogeneous Memory Management (HMM) <hmm>` -for migrating pages to or from device private memory. +Also see Documentation/mm/hmm.rst for migrating pages to or from device +private memory. The main intent of page migration is to reduce the latency of memory accesses by moving pages near to the processor where the process accessing that memory diff --git a/Documentation/mm/page_owner.rst b/Documentation/mm/page_owner.rst index 127514955a5e..62e3f7ab23cc 100644 --- a/Documentation/mm/page_owner.rst +++ b/Documentation/mm/page_owner.rst @@ -1,5 +1,3 @@ -.. _page_owner: - ================================================== page owner: Tracking about who allocated each page ================================================== @@ -52,7 +50,7 @@ pages are investigated and marked as allocated in initialization phase. Although it doesn't mean that they have the right owner information, at least, we can tell whether the page is allocated or not, more accurately. On 2GB memory x86-64 VM box, 13343 early allocated pages -are catched and marked, although they are mostly allocated from struct +are caught and marked, although they are mostly allocated from struct page extension feature. Anyway, after that, no page is left in un-tracking state. @@ -61,7 +59,7 @@ Usage 1) Build user-space helper:: - cd tools/vm + cd tools/mm make page_owner_sort 2) Enable page owner: add "page_owner=on" to boot cmdline. @@ -178,7 +176,7 @@ STANDARD FORMAT SPECIFIERS at alloc_ts timestamp of the page when it was allocated ator allocator memory allocator for pages - For --curl option: + For --cull option: KEY LONG DESCRIPTION p pid process ID diff --git a/Documentation/mm/page_table_check.rst b/Documentation/mm/page_table_check.rst index 1a09472f10a3..cfd8f4117cf3 100644 --- a/Documentation/mm/page_table_check.rst +++ b/Documentation/mm/page_table_check.rst @@ -1,7 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 -.. _page_table_check: - ================ Page Table Check ================ diff --git a/Documentation/mm/physical_memory.rst b/Documentation/mm/physical_memory.rst index 2ab7b8c1c863..f9d7ea4b9dca 100644 --- a/Documentation/mm/physical_memory.rst +++ b/Documentation/mm/physical_memory.rst @@ -3,3 +3,350 @@ =============== Physical Memory =============== + +Linux is available for a wide range of architectures so there is a need for an +architecture-independent abstraction to represent the physical memory. This +chapter describes the structures used to manage physical memory in a running +system. + +The first principal concept prevalent in the memory management is +`Non-Uniform Memory Access (NUMA) +<https://en.wikipedia.org/wiki/Non-uniform_memory_access>`_. +With multi-core and multi-socket machines, memory may be arranged into banks +that incur a different cost to access depending on the “distance†from the +processor. For example, there might be a bank of memory assigned to each CPU or +a bank of memory very suitable for DMA near peripheral devices. + +Each bank is called a node and the concept is represented under Linux by a +``struct pglist_data`` even if the architecture is UMA. This structure is +always referenced to by it's typedef ``pg_data_t``. ``A pg_data_t`` structure +for a particular node can be referenced by ``NODE_DATA(nid)`` macro where +``nid`` is the ID of that node. + +For NUMA architectures, the node structures are allocated by the architecture +specific code early during boot. Usually, these structures are allocated +locally on the memory bank they represent. For UMA architectures, only one +static ``pg_data_t`` structure called ``contig_page_data`` is used. Nodes will +be discussed further in Section :ref:`Nodes <nodes>` + +The entire physical address space is partitioned into one or more blocks +called zones which represent ranges within memory. These ranges are usually +determined by architectural constraints for accessing the physical memory. +The memory range within a node that corresponds to a particular zone is +described by a ``struct zone``, typedeffed to ``zone_t``. Each zone has +one of the types described below. + +* ``ZONE_DMA`` and ``ZONE_DMA32`` historically represented memory suitable for + DMA by peripheral devices that cannot access all of the addressable + memory. For many years there are better more and robust interfaces to get + memory with DMA specific requirements (Documentation/core-api/dma-api.rst), + but ``ZONE_DMA`` and ``ZONE_DMA32`` still represent memory ranges that have + restrictions on how they can be accessed. + Depending on the architecture, either of these zone types or even they both + can be disabled at build time using ``CONFIG_ZONE_DMA`` and + ``CONFIG_ZONE_DMA32`` configuration options. Some 64-bit platforms may need + both zones as they support peripherals with different DMA addressing + limitations. + +* ``ZONE_NORMAL`` is for normal memory that can be accessed by the kernel all + the time. DMA operations can be performed on pages in this zone if the DMA + devices support transfers to all addressable memory. ``ZONE_NORMAL`` is + always enabled. + +* ``ZONE_HIGHMEM`` is the part of the physical memory that is not covered by a + permanent mapping in the kernel page tables. The memory in this zone is only + accessible to the kernel using temporary mappings. This zone is available + only on some 32-bit architectures and is enabled with ``CONFIG_HIGHMEM``. + +* ``ZONE_MOVABLE`` is for normal accessible memory, just like ``ZONE_NORMAL``. + The difference is that the contents of most pages in ``ZONE_MOVABLE`` is + movable. That means that while virtual addresses of these pages do not + change, their content may move between different physical pages. Often + ``ZONE_MOVABLE`` is populated during memory hotplug, but it may be + also populated on boot using one of ``kernelcore``, ``movablecore`` and + ``movable_node`` kernel command line parameters. See + Documentation/mm/page_migration.rst and + Documentation/admin-guide/mm/memory_hotplug.rst for additional details. + +* ``ZONE_DEVICE`` represents memory residing on devices such as PMEM and GPU. + It has different characteristics than RAM zone types and it exists to provide + :ref:`struct page <Pages>` and memory map services for device driver + identified physical address ranges. ``ZONE_DEVICE`` is enabled with + configuration option ``CONFIG_ZONE_DEVICE``. + +It is important to note that many kernel operations can only take place using +``ZONE_NORMAL`` so it is the most performance critical zone. Zones are +discussed further in Section :ref:`Zones <zones>`. + +The relation between node and zone extents is determined by the physical memory +map reported by the firmware, architectural constraints for memory addressing +and certain parameters in the kernel command line. + +For example, with 32-bit kernel on an x86 UMA machine with 2 Gbytes of RAM the +entire memory will be on node 0 and there will be three zones: ``ZONE_DMA``, +``ZONE_NORMAL`` and ``ZONE_HIGHMEM``:: + + 0 2G + +-------------------------------------------------------------+ + | node 0 | + +-------------------------------------------------------------+ + + 0 16M 896M 2G + +----------+-----------------------+--------------------------+ + | ZONE_DMA | ZONE_NORMAL | ZONE_HIGHMEM | + +----------+-----------------------+--------------------------+ + + +With a kernel built with ``ZONE_DMA`` disabled and ``ZONE_DMA32`` enabled and +booted with ``movablecore=80%`` parameter on an arm64 machine with 16 Gbytes of +RAM equally split between two nodes, there will be ``ZONE_DMA32``, +``ZONE_NORMAL`` and ``ZONE_MOVABLE`` on node 0, and ``ZONE_NORMAL`` and +``ZONE_MOVABLE`` on node 1:: + + + 1G 9G 17G + +--------------------------------+ +--------------------------+ + | node 0 | | node 1 | + +--------------------------------+ +--------------------------+ + + 1G 4G 4200M 9G 9320M 17G + +---------+----------+-----------+ +------------+-------------+ + | DMA32 | NORMAL | MOVABLE | | NORMAL | MOVABLE | + +---------+----------+-----------+ +------------+-------------+ + +.. _nodes: + +Nodes +===== + +As we have mentioned, each node in memory is described by a ``pg_data_t`` which +is a typedef for a ``struct pglist_data``. When allocating a page, by default +Linux uses a node-local allocation policy to allocate memory from the node +closest to the running CPU. As processes tend to run on the same CPU, it is +likely the memory from the current node will be used. The allocation policy can +be controlled by users as described in +Documentation/admin-guide/mm/numa_memory_policy.rst. + +Most NUMA architectures maintain an array of pointers to the node +structures. The actual structures are allocated early during boot when +architecture specific code parses the physical memory map reported by the +firmware. The bulk of the node initialization happens slightly later in the +boot process by free_area_init() function, described later in Section +:ref:`Initialization <initialization>`. + + +Along with the node structures, kernel maintains an array of ``nodemask_t`` +bitmasks called ``node_states``. Each bitmask in this array represents a set of +nodes with particular properties as defined by ``enum node_states``: + +``N_POSSIBLE`` + The node could become online at some point. +``N_ONLINE`` + The node is online. +``N_NORMAL_MEMORY`` + The node has regular memory. +``N_HIGH_MEMORY`` + The node has regular or high memory. When ``CONFIG_HIGHMEM`` is disabled + aliased to ``N_NORMAL_MEMORY``. +``N_MEMORY`` + The node has memory(regular, high, movable) +``N_CPU`` + The node has one or more CPUs + +For each node that has a property described above, the bit corresponding to the +node ID in the ``node_states[<property>]`` bitmask is set. + +For example, for node 2 with normal memory and CPUs, bit 2 will be set in :: + + node_states[N_POSSIBLE] + node_states[N_ONLINE] + node_states[N_NORMAL_MEMORY] + node_states[N_HIGH_MEMORY] + node_states[N_MEMORY] + node_states[N_CPU] + +For various operations possible with nodemasks please refer to +``include/linux/nodemask.h``. + +Among other things, nodemasks are used to provide macros for node traversal, +namely ``for_each_node()`` and ``for_each_online_node()``. + +For instance, to call a function foo() for each online node:: + + for_each_online_node(nid) { + pg_data_t *pgdat = NODE_DATA(nid); + + foo(pgdat); + } + +Node structure +-------------- + +The nodes structure ``struct pglist_data`` is declared in +``include/linux/mmzone.h``. Here we briefly describe fields of this +structure: + +General +~~~~~~~ + +``node_zones`` + The zones for this node. Not all of the zones may be populated, but it is + the full list. It is referenced by this node's node_zonelists as well as + other node's node_zonelists. + +``node_zonelists`` + The list of all zones in all nodes. This list defines the order of zones + that allocations are preferred from. The ``node_zonelists`` is set up by + ``build_zonelists()`` in ``mm/page_alloc.c`` during the initialization of + core memory management structures. + +``nr_zones`` + Number of populated zones in this node. + +``node_mem_map`` + For UMA systems that use FLATMEM memory model the 0's node + ``node_mem_map`` is array of struct pages representing each physical frame. + +``node_page_ext`` + For UMA systems that use FLATMEM memory model the 0's node + ``node_page_ext`` is array of extensions of struct pages. Available only + in the kernels built with ``CONFIG_PAGE_EXTENSION`` enabled. + +``node_start_pfn`` + The page frame number of the starting page frame in this node. + +``node_present_pages`` + Total number of physical pages present in this node. + +``node_spanned_pages`` + Total size of physical page range, including holes. + +``node_size_lock`` + A lock that protects the fields defining the node extents. Only defined when + at least one of ``CONFIG_MEMORY_HOTPLUG`` or + ``CONFIG_DEFERRED_STRUCT_PAGE_INIT`` configuration options are enabled. + ``pgdat_resize_lock()`` and ``pgdat_resize_unlock()`` are provided to + manipulate ``node_size_lock`` without checking for ``CONFIG_MEMORY_HOTPLUG`` + or ``CONFIG_DEFERRED_STRUCT_PAGE_INIT``. + +``node_id`` + The Node ID (NID) of the node, starts at 0. + +``totalreserve_pages`` + This is a per-node reserve of pages that are not available to userspace + allocations. + +``first_deferred_pfn`` + If memory initialization on large machines is deferred then this is the first + PFN that needs to be initialized. Defined only when + ``CONFIG_DEFERRED_STRUCT_PAGE_INIT`` is enabled + +``deferred_split_queue`` + Per-node queue of huge pages that their split was deferred. Defined only when ``CONFIG_TRANSPARENT_HUGEPAGE`` is enabled. + +``__lruvec`` + Per-node lruvec holding LRU lists and related parameters. Used only when + memory cgroups are disabled. It should not be accessed directly, use + ``mem_cgroup_lruvec()`` to look up lruvecs instead. + +Reclaim control +~~~~~~~~~~~~~~~ + +See also Documentation/mm/page_reclaim.rst. + +``kswapd`` + Per-node instance of kswapd kernel thread. + +``kswapd_wait``, ``pfmemalloc_wait``, ``reclaim_wait`` + Workqueues used to synchronize memory reclaim tasks + +``nr_writeback_throttled`` + Number of tasks that are throttled waiting on dirty pages to clean. + +``nr_reclaim_start`` + Number of pages written while reclaim is throttled waiting for writeback. + +``kswapd_order`` + Controls the order kswapd tries to reclaim + +``kswapd_highest_zoneidx`` + The highest zone index to be reclaimed by kswapd + +``kswapd_failures`` + Number of runs kswapd was unable to reclaim any pages + +``min_unmapped_pages`` + Minimal number of unmapped file backed pages that cannot be reclaimed. + Determined by ``vm.min_unmapped_ratio`` sysctl. Only defined when + ``CONFIG_NUMA`` is enabled. + +``min_slab_pages`` + Minimal number of SLAB pages that cannot be reclaimed. Determined by + ``vm.min_slab_ratio sysctl``. Only defined when ``CONFIG_NUMA`` is enabled + +``flags`` + Flags controlling reclaim behavior. + +Compaction control +~~~~~~~~~~~~~~~~~~ + +``kcompactd_max_order`` + Page order that kcompactd should try to achieve. + +``kcompactd_highest_zoneidx`` + The highest zone index to be compacted by kcompactd. + +``kcompactd_wait`` + Workqueue used to synchronize memory compaction tasks. + +``kcompactd`` + Per-node instance of kcompactd kernel thread. + +``proactive_compact_trigger`` + Determines if proactive compaction is enabled. Controlled by + ``vm.compaction_proactiveness`` sysctl. + +Statistics +~~~~~~~~~~ + +``per_cpu_nodestats`` + Per-CPU VM statistics for the node + +``vm_stat`` + VM statistics for the node. + +.. _zones: + +Zones +===== + +.. admonition:: Stub + + This section is incomplete. Please list and describe the appropriate fields. + +.. _pages: + +Pages +===== + +.. admonition:: Stub + + This section is incomplete. Please list and describe the appropriate fields. + +.. _folios: + +Folios +====== + +.. admonition:: Stub + + This section is incomplete. Please list and describe the appropriate fields. + +.. _initialization: + +Initialization +============== + +.. admonition:: Stub + + This section is incomplete. Please list and describe the appropriate fields. diff --git a/Documentation/mm/remap_file_pages.rst b/Documentation/mm/remap_file_pages.rst index 7bef6718e3a9..297091ce257c 100644 --- a/Documentation/mm/remap_file_pages.rst +++ b/Documentation/mm/remap_file_pages.rst @@ -1,5 +1,3 @@ -.. _remap_file_pages: - ============================== remap_file_pages() system call ============================== diff --git a/Documentation/mm/slub.rst b/Documentation/mm/slub.rst index 7f652216dabe..be75971532f5 100644 --- a/Documentation/mm/slub.rst +++ b/Documentation/mm/slub.rst @@ -1,5 +1,3 @@ -.. _slub: - ========================== Short users guide for SLUB ========================== @@ -21,7 +19,7 @@ slabs that have data in them. See "slabinfo -h" for more options when running the command. ``slabinfo`` can be compiled with :: - gcc -o slabinfo tools/vm/slabinfo.c + gcc -o slabinfo tools/mm/slabinfo.c Some of the modes of operation of ``slabinfo`` require that slub debugging be enabled on the command line. F.e. no tracking information will be diff --git a/Documentation/mm/split_page_table_lock.rst b/Documentation/mm/split_page_table_lock.rst index c08919662704..50ee0dfc95be 100644 --- a/Documentation/mm/split_page_table_lock.rst +++ b/Documentation/mm/split_page_table_lock.rst @@ -1,5 +1,3 @@ -.. _split_page_table_lock: - ===================== Split page table lock ===================== diff --git a/Documentation/mm/transhuge.rst b/Documentation/mm/transhuge.rst index ec3dc5b04226..9a607059ea11 100644 --- a/Documentation/mm/transhuge.rst +++ b/Documentation/mm/transhuge.rst @@ -1,5 +1,3 @@ -.. _transhuge: - ============================ Transparent Hugepage Support ============================ @@ -112,20 +110,20 @@ Refcounts and transparent huge pages Refcounting on THP is mostly consistent with refcounting on other compound pages: - - get_page()/put_page() and GUP operate on head page's ->_refcount. + - get_page()/put_page() and GUP operate on the folio->_refcount. - ->_refcount in tail pages is always zero: get_page_unless_zero() never succeeds on tail pages. - - map/unmap of PMD entry for the whole compound page increment/decrement - ->compound_mapcount, stored in the first tail page of the compound page; - and also increment/decrement ->subpages_mapcount (also in the first tail) - by COMPOUND_MAPPED when compound_mapcount goes from -1 to 0 or 0 to -1. + - map/unmap of a PMD entry for the whole THP increment/decrement + folio->_entire_mapcount and also increment/decrement + folio->_nr_pages_mapped by COMPOUND_MAPPED when _entire_mapcount + goes from -1 to 0 or 0 to -1. - - map/unmap of sub-pages with PTE entry increment/decrement ->_mapcount - on relevant sub-page of the compound page, and also increment/decrement - ->subpages_mapcount, stored in first tail page of the compound page, when - _mapcount goes from -1 to 0 or 0 to -1: counting sub-pages mapped by PTE. + - map/unmap of individual pages with PTE entry increment/decrement + page->_mapcount and also increment/decrement folio->_nr_pages_mapped + when page->_mapcount goes from -1 to 0 or 0 to -1 as this counts + the number of pages mapped by PTE. split_huge_page internally has to distribute the refcounts in the head page to the tail pages before clearing all PG_head/tail bits from the page @@ -153,8 +151,8 @@ clear where references should go after split: it will stay on the head page. Note that split_huge_pmd() doesn't have any limitations on refcounting: pmd can be split at any point and never fails. -Partial unmap and deferred_split_huge_page() -============================================ +Partial unmap and deferred_split_folio() +======================================== Unmapping part of THP (with munmap() or other way) is not going to free memory immediately. Instead, we detect that a subpage of THP is not in use @@ -166,6 +164,6 @@ the place where we can detect partial unmap. It also might be counterproductive since in many cases partial unmap happens during exit(2) if a THP crosses a VMA boundary. -The function deferred_split_huge_page() is used to queue a page for splitting. +The function deferred_split_folio() is used to queue a folio for splitting. The splitting itself will happen when we get memory pressure via shrinker interface. diff --git a/Documentation/mm/unevictable-lru.rst b/Documentation/mm/unevictable-lru.rst index 4a0e158aa9ce..92ac5dca420c 100644 --- a/Documentation/mm/unevictable-lru.rst +++ b/Documentation/mm/unevictable-lru.rst @@ -1,5 +1,3 @@ -.. _unevictable_lru: - ============================== Unevictable LRU Infrastructure ============================== @@ -12,7 +10,7 @@ Introduction This document describes the Linux memory manager's "Unevictable LRU" infrastructure and the use of this to manage several types of "unevictable" -pages. +folios. The document attempts to provide the overall rationale behind this mechanism and the rationale for some of the design decisions that drove the @@ -27,8 +25,8 @@ The Unevictable LRU =================== The Unevictable LRU facility adds an additional LRU list to track unevictable -pages and to hide these pages from vmscan. This mechanism is based on a patch -by Larry Woodman of Red Hat to address several scalability problems with page +folios and to hide these folios from vmscan. This mechanism is based on a patch +by Larry Woodman of Red Hat to address several scalability problems with folio reclaim in Linux. The problems have been observed at customer sites on large memory x86_64 systems. @@ -52,40 +50,41 @@ The infrastructure may also be able to handle other conditions that make pages unevictable, either by definition or by circumstance, in the future. -The Unevictable LRU Page List ------------------------------ +The Unevictable LRU Folio List +------------------------------ -The Unevictable LRU page list is a lie. It was never an LRU-ordered list, but a -companion to the LRU-ordered anonymous and file, active and inactive page lists; -and now it is not even a page list. But following familiar convention, here in -this document and in the source, we often imagine it as a fifth LRU page list. +The Unevictable LRU folio list is a lie. It was never an LRU-ordered +list, but a companion to the LRU-ordered anonymous and file, active and +inactive folio lists; and now it is not even a folio list. But following +familiar convention, here in this document and in the source, we often +imagine it as a fifth LRU folio list. The Unevictable LRU infrastructure consists of an additional, per-node, LRU list -called the "unevictable" list and an associated page flag, PG_unevictable, to -indicate that the page is being managed on the unevictable list. +called the "unevictable" list and an associated folio flag, PG_unevictable, to +indicate that the folio is being managed on the unevictable list. The PG_unevictable flag is analogous to, and mutually exclusive with, the -PG_active flag in that it indicates on which LRU list a page resides when +PG_active flag in that it indicates on which LRU list a folio resides when PG_lru is set. -The Unevictable LRU infrastructure maintains unevictable pages as if they were +The Unevictable LRU infrastructure maintains unevictable folios as if they were on an additional LRU list for a few reasons: - (1) We get to "treat unevictable pages just like we treat other pages in the + (1) We get to "treat unevictable folios just like we treat other folios in the system - which means we get to use the same code to manipulate them, the same code to isolate them (for migrate, etc.), the same code to keep track of the statistics, etc..." [Rik van Riel] - (2) We want to be able to migrate unevictable pages between nodes for memory + (2) We want to be able to migrate unevictable folios between nodes for memory defragmentation, workload management and memory hotplug. The Linux kernel - can only migrate pages that it can successfully isolate from the LRU + can only migrate folios that it can successfully isolate from the LRU lists (or "Movable" pages: outside of consideration here). If we were to - maintain pages elsewhere than on an LRU-like list, where they can be - detected by isolate_lru_page(), we would prevent their migration. + maintain folios elsewhere than on an LRU-like list, where they can be + detected by folio_isolate_lru(), we would prevent their migration. -The unevictable list does not differentiate between file-backed and anonymous, -swap-backed pages. This differentiation is only important while the pages are, -in fact, evictable. +The unevictable list does not differentiate between file-backed and +anonymous, swap-backed folios. This differentiation is only important +while the folios are, in fact, evictable. The unevictable list benefits from the "arrayification" of the per-node LRU lists and statistics originally proposed and posted by Christoph Lameter. @@ -158,7 +157,7 @@ These are currently used in three places in the kernel: Detecting Unevictable Pages --------------------------- -The function page_evictable() in mm/internal.h determines whether a page is +The function folio_evictable() in mm/internal.h determines whether a folio is evictable or not using the query function outlined above [see section :ref:`Marking address spaces unevictable <mark_addr_space_unevict>`] to check the AS_UNEVICTABLE flag. @@ -167,7 +166,7 @@ For address spaces that are so marked after being populated (as SHM regions might be), the lock action (e.g. SHM_LOCK) can be lazy, and need not populate the page tables for the region as does, for example, mlock(), nor need it make any special effort to push any pages in the SHM_LOCK'd area to the unevictable -list. Instead, vmscan will do this if and when it encounters the pages during +list. Instead, vmscan will do this if and when it encounters the folios during a reclamation scan. On an unlock action (such as SHM_UNLOCK), the unlocker (e.g. shmctl()) must scan @@ -176,41 +175,43 @@ condition is keeping them unevictable. If an unevictable region is destroyed, the pages are also "rescued" from the unevictable list in the process of freeing them. -page_evictable() also checks for mlocked pages by testing an additional page -flag, PG_mlocked (as wrapped by PageMlocked()), which is set when a page is -faulted into a VM_LOCKED VMA, or found in a VMA being VM_LOCKED. +folio_evictable() also checks for mlocked folios by calling +folio_test_mlocked(), which is set when a folio is faulted into a +VM_LOCKED VMA, or found in a VMA being VM_LOCKED. -Vmscan's Handling of Unevictable Pages --------------------------------------- +Vmscan's Handling of Unevictable Folios +--------------------------------------- -If unevictable pages are culled in the fault path, or moved to the unevictable -list at mlock() or mmap() time, vmscan will not encounter the pages until they +If unevictable folios are culled in the fault path, or moved to the unevictable +list at mlock() or mmap() time, vmscan will not encounter the folios until they have become evictable again (via munlock() for example) and have been "rescued" from the unevictable list. However, there may be situations where we decide, -for the sake of expediency, to leave an unevictable page on one of the regular +for the sake of expediency, to leave an unevictable folio on one of the regular active/inactive LRU lists for vmscan to deal with. vmscan checks for such -pages in all of the shrink_{active|inactive|page}_list() functions and will -"cull" such pages that it encounters: that is, it diverts those pages to the +folios in all of the shrink_{active|inactive|page}_list() functions and will +"cull" such folios that it encounters: that is, it diverts those folios to the unevictable list for the memory cgroup and node being scanned. -There may be situations where a page is mapped into a VM_LOCKED VMA, but the -page is not marked as PG_mlocked. Such pages will make it all the way to -shrink_active_list() or shrink_page_list() where they will be detected when -vmscan walks the reverse map in folio_referenced() or try_to_unmap(). The page -is culled to the unevictable list when it is released by the shrinker. +There may be situations where a folio is mapped into a VM_LOCKED VMA, +but the folio does not have the mlocked flag set. Such folios will make +it all the way to shrink_active_list() or shrink_page_list() where they +will be detected when vmscan walks the reverse map in folio_referenced() +or try_to_unmap(). The folio is culled to the unevictable list when it +is released by the shrinker. -To "cull" an unevictable page, vmscan simply puts the page back on the LRU list -using putback_lru_page() - the inverse operation to isolate_lru_page() - after -dropping the page lock. Because the condition which makes the page unevictable -may change once the page is unlocked, __pagevec_lru_add_fn() will recheck the -unevictable state of a page before placing it on the unevictable list. +To "cull" an unevictable folio, vmscan simply puts the folio back on +the LRU list using folio_putback_lru() - the inverse operation to +folio_isolate_lru() - after dropping the folio lock. Because the +condition which makes the folio unevictable may change once the folio +is unlocked, __pagevec_lru_add_fn() will recheck the unevictable state +of a folio before placing it on the unevictable list. MLOCKED Pages ============= -The unevictable page list is also useful for mlock(), in addition to ramfs and +The unevictable folio list is also useful for mlock(), in addition to ramfs and SYSV SHM. Note that mlock() is only available in CONFIG_MMU=y situations; in NOMMU situations, all mappings are effectively mlocked. @@ -295,7 +296,7 @@ treated as a no-op and mlock_fixup() simply returns. If the VMA passes some filtering as described in "Filtering Special VMAs" below, mlock_fixup() will attempt to merge the VMA with its neighbors or split off a subset of the VMA if the range does not cover the entire VMA. Any pages -already present in the VMA are then marked as mlocked by mlock_page() via +already present in the VMA are then marked as mlocked by mlock_folio() via mlock_pte_range() via walk_page_range() via mlock_vma_pages_range(). Before returning from the system call, do_mlock() or mlockall() will call @@ -308,22 +309,22 @@ do end up getting faulted into this VM_LOCKED VMA, they will be handled in the fault path - which is also how mlock2()'s MLOCK_ONFAULT areas are handled. For each PTE (or PMD) being faulted into a VMA, the page add rmap function -calls mlock_vma_page(), which calls mlock_page() when the VMA is VM_LOCKED +calls mlock_vma_folio(), which calls mlock_folio() when the VMA is VM_LOCKED (unless it is a PTE mapping of a part of a transparent huge page). Or when -it is a newly allocated anonymous page, lru_cache_add_inactive_or_unevictable() -calls mlock_new_page() instead: similar to mlock_page(), but can make better +it is a newly allocated anonymous page, folio_add_lru_vma() calls +mlock_new_folio() instead: similar to mlock_folio(), but can make better judgments, since this page is held exclusively and known not to be on LRU yet. -mlock_page() sets PageMlocked immediately, then places the page on the CPU's -mlock pagevec, to batch up the rest of the work to be done under lru_lock by -__mlock_page(). __mlock_page() sets PageUnevictable, initializes mlock_count +mlock_folio() sets PG_mlocked immediately, then places the page on the CPU's +mlock folio batch, to batch up the rest of the work to be done under lru_lock by +__mlock_folio(). __mlock_folio() sets PG_unevictable, initializes mlock_count and moves the page to unevictable state ("the unevictable LRU", but with -mlock_count in place of LRU threading). Or if the page was already PageLRU -and PageUnevictable and PageMlocked, it simply increments the mlock_count. +mlock_count in place of LRU threading). Or if the page was already PG_lru +and PG_unevictable and PG_mlocked, it simply increments the mlock_count. But in practice that may not work ideally: the page may not yet be on an LRU, or it may have been temporarily isolated from LRU. In such cases the mlock_count -field cannot be touched, but will be set to 0 later when __pagevec_lru_add_fn() +field cannot be touched, but will be set to 0 later when __munlock_folio() returns the page to "LRU". Races prohibit mlock_count from being set to 1 then: rather than risk stranding a page indefinitely as unevictable, always err with mlock_count on the low side, so that when munlocked the page will be rescued to @@ -370,20 +371,21 @@ Because of the VMA filtering discussed above, VM_LOCKED will not be set in any "special" VMAs. So, those VMAs will be ignored for munlock. If the VMA is VM_LOCKED, mlock_fixup() again attempts to merge or split off the -specified range. All pages in the VMA are then munlocked by munlock_page() via +specified range. All pages in the VMA are then munlocked by munlock_folio() via mlock_pte_range() via walk_page_range() via mlock_vma_pages_range() - the same function used when mlocking a VMA range, with new flags for the VMA indicating that it is munlock() being performed. -munlock_page() uses the mlock pagevec to batch up work to be done under -lru_lock by __munlock_page(). __munlock_page() decrements the page's -mlock_count, and when that reaches 0 it clears PageMlocked and clears -PageUnevictable, moving the page from unevictable state to inactive LRU. +munlock_folio() uses the mlock pagevec to batch up work to be done +under lru_lock by __munlock_folio(). __munlock_folio() decrements the +folio's mlock_count, and when that reaches 0 it clears the mlocked flag +and clears the unevictable flag, moving the folio from unevictable state +to the inactive LRU. -But in practice that may not work ideally: the page may not yet have reached +But in practice that may not work ideally: the folio may not yet have reached "the unevictable LRU", or it may have been temporarily isolated from it. In those cases its mlock_count field is unusable and must be assumed to be 0: so -that the page will be rescued to an evictable LRU, then perhaps be mlocked +that the folio will be rescued to an evictable LRU, then perhaps be mlocked again later if vmscan finds it in a VM_LOCKED VMA. @@ -410,7 +412,7 @@ However, since mlock_vma_pages_range() starts by setting VM_LOCKED on a VMA, before mlocking any pages already present, if one of those pages were migrated before mlock_pte_range() reached it, it would get counted twice in mlock_count. To prevent that, mlock_vma_pages_range() temporarily marks the VMA as VM_IO, -so that mlock_vma_page() will skip it. +so that mlock_vma_folio() will skip it. To complete page migration, we place the old and new pages back onto the LRU afterwards. The "unneeded" page - old page on success, new page on failure - @@ -483,18 +485,19 @@ Before the unevictable/mlock changes, mlocking did not mark the pages in any way, so unmapping them required no processing. For each PTE (or PMD) being unmapped from a VMA, page_remove_rmap() calls -munlock_vma_page(), which calls munlock_page() when the VMA is VM_LOCKED +munlock_vma_folio(), which calls munlock_folio() when the VMA is VM_LOCKED (unless it was a PTE mapping of a part of a transparent huge page). -munlock_page() uses the mlock pagevec to batch up work to be done under -lru_lock by __munlock_page(). __munlock_page() decrements the page's -mlock_count, and when that reaches 0 it clears PageMlocked and clears -PageUnevictable, moving the page from unevictable state to inactive LRU. +munlock_folio() uses the mlock pagevec to batch up work to be done +under lru_lock by __munlock_folio(). __munlock_folio() decrements the +folio's mlock_count, and when that reaches 0 it clears the mlocked flag +and clears the unevictable flag, moving the folio from unevictable state +to the inactive LRU. -But in practice that may not work ideally: the page may not yet have reached +But in practice that may not work ideally: the folio may not yet have reached "the unevictable LRU", or it may have been temporarily isolated from it. In those cases its mlock_count field is unusable and must be assumed to be 0: so -that the page will be rescued to an evictable LRU, then perhaps be mlocked +that the folio will be rescued to an evictable LRU, then perhaps be mlocked again later if vmscan finds it in a VM_LOCKED VMA. @@ -507,7 +510,7 @@ which had been Copied-On-Write from the file pages now being truncated. Mlocked pages can be munlocked and deleted in this way: like with munmap(), for each PTE (or PMD) being unmapped from a VMA, page_remove_rmap() calls -munlock_vma_page(), which calls munlock_page() when the VMA is VM_LOCKED +munlock_vma_folio(), which calls munlock_folio() when the VMA is VM_LOCKED (unless it was a PTE mapping of a part of a transparent huge page). However, if there is a racing munlock(), since mlock_vma_pages_range() starts @@ -515,7 +518,7 @@ munlocking by clearing VM_LOCKED from a VMA, before munlocking all the pages present, if one of those pages were unmapped by truncation or hole punch before mlock_pte_range() reached it, it would not be recognized as mlocked by this VMA, and would not be counted out of mlock_count. In this rare case, a page may -still appear as PageMlocked after it has been fully unmapped: and it is left to +still appear as PG_mlocked after it has been fully unmapped: and it is left to release_pages() (or __page_cache_release()) to clear it and update statistics before freeing (this event is counted in /proc/vmstat unevictable_pgs_cleared, which is usually 0). @@ -527,7 +530,7 @@ Page Reclaim in shrink_*_list() vmscan's shrink_active_list() culls any obviously unevictable pages - i.e. !page_evictable(page) pages - diverting those to the unevictable list. However, shrink_active_list() only sees unevictable pages that made it onto the -active/inactive LRU lists. Note that these pages do not have PageUnevictable +active/inactive LRU lists. Note that these pages do not have PG_unevictable set - otherwise they would be on the unevictable list and shrink_active_list() would never see them. @@ -549,6 +552,6 @@ and node unevictable list. rmap's folio_referenced_one(), called via vmscan's shrink_active_list() or shrink_page_list(), and rmap's try_to_unmap_one() called via shrink_page_list(), -check for (3) pages still mapped into VM_LOCKED VMAs, and call mlock_vma_page() +check for (3) pages still mapped into VM_LOCKED VMAs, and call mlock_vma_folio() to correct them. Such pages are culled to the unevictable list when released by the shrinker. diff --git a/Documentation/mm/z3fold.rst b/Documentation/mm/z3fold.rst index 224e3c61d686..25b5935d06c7 100644 --- a/Documentation/mm/z3fold.rst +++ b/Documentation/mm/z3fold.rst @@ -1,5 +1,3 @@ -.. _z3fold: - ====== z3fold ====== diff --git a/Documentation/mm/zsmalloc.rst b/Documentation/mm/zsmalloc.rst index 6e79893d6132..64d127bfc221 100644 --- a/Documentation/mm/zsmalloc.rst +++ b/Documentation/mm/zsmalloc.rst @@ -1,5 +1,3 @@ -.. _zsmalloc: - ======== zsmalloc ======== @@ -80,3 +78,171 @@ Similarly, we assign zspage to: * ZS_ALMOST_FULL when n > N / f * ZS_EMPTY when n == 0 * ZS_FULL when n == N + + +Internals +========= + +zsmalloc has 255 size classes, each of which can hold a number of zspages. +Each zspage can contain up to ZSMALLOC_CHAIN_SIZE physical (0-order) pages. +The optimal zspage chain size for each size class is calculated during the +creation of the zsmalloc pool (see calculate_zspage_chain_size()). + +As an optimization, zsmalloc merges size classes that have similar +characteristics in terms of the number of pages per zspage and the number +of objects that each zspage can store. + +For instance, consider the following size classes::: + + class size almost_full almost_empty obj_allocated obj_used pages_used pages_per_zspage freeable + ... + 94 1536 0 0 0 0 0 3 0 + 100 1632 0 0 0 0 0 2 0 + ... + + +Size classes #95-99 are merged with size class #100. This means that when we +need to store an object of size, say, 1568 bytes, we end up using size class +#100 instead of size class #96. Size class #100 is meant for objects of size +1632 bytes, so each object of size 1568 bytes wastes 1632-1568=64 bytes. + +Size class #100 consists of zspages with 2 physical pages each, which can +hold a total of 5 objects. If we need to store 13 objects of size 1568, we +end up allocating three zspages, or 6 physical pages. + +However, if we take a closer look at size class #96 (which is meant for +objects of size 1568 bytes) and trace `calculate_zspage_chain_size()`, we +find that the most optimal zspage configuration for this class is a chain +of 5 physical pages::: + + pages per zspage wasted bytes used% + 1 960 76 + 2 352 95 + 3 1312 89 + 4 704 95 + 5 96 99 + +This means that a class #96 configuration with 5 physical pages can store 13 +objects of size 1568 in a single zspage, using a total of 5 physical pages. +This is more efficient than the class #100 configuration, which would use 6 +physical pages to store the same number of objects. + +As the zspage chain size for class #96 increases, its key characteristics +such as pages per-zspage and objects per-zspage also change. This leads to +dewer class mergers, resulting in a more compact grouping of classes, which +reduces memory wastage. + +Let's take a closer look at the bottom of `/sys/kernel/debug/zsmalloc/zramX/classes`::: + + class size almost_full almost_empty obj_allocated obj_used pages_used pages_per_zspage freeable + ... + 202 3264 0 0 0 0 0 4 0 + 254 4096 0 0 0 0 0 1 0 + ... + +Size class #202 stores objects of size 3264 bytes and has a maximum of 4 pages +per zspage. Any object larger than 3264 bytes is considered huge and belongs +to size class #254, which stores each object in its own physical page (objects +in huge classes do not share pages). + +Increasing the size of the chain of zspages also results in a higher watermark +for the huge size class and fewer huge classes overall. This allows for more +efficient storage of large objects. + +For zspage chain size of 8, huge class watermark becomes 3632 bytes::: + + class size almost_full almost_empty obj_allocated obj_used pages_used pages_per_zspage freeable + ... + 202 3264 0 0 0 0 0 4 0 + 211 3408 0 0 0 0 0 5 0 + 217 3504 0 0 0 0 0 6 0 + 222 3584 0 0 0 0 0 7 0 + 225 3632 0 0 0 0 0 8 0 + 254 4096 0 0 0 0 0 1 0 + ... + +For zspage chain size of 16, huge class watermark becomes 3840 bytes::: + + class size almost_full almost_empty obj_allocated obj_used pages_used pages_per_zspage freeable + ... + 202 3264 0 0 0 0 0 4 0 + 206 3328 0 0 0 0 0 13 0 + 207 3344 0 0 0 0 0 9 0 + 208 3360 0 0 0 0 0 14 0 + 211 3408 0 0 0 0 0 5 0 + 212 3424 0 0 0 0 0 16 0 + 214 3456 0 0 0 0 0 11 0 + 217 3504 0 0 0 0 0 6 0 + 219 3536 0 0 0 0 0 13 0 + 222 3584 0 0 0 0 0 7 0 + 223 3600 0 0 0 0 0 15 0 + 225 3632 0 0 0 0 0 8 0 + 228 3680 0 0 0 0 0 9 0 + 230 3712 0 0 0 0 0 10 0 + 232 3744 0 0 0 0 0 11 0 + 234 3776 0 0 0 0 0 12 0 + 235 3792 0 0 0 0 0 13 0 + 236 3808 0 0 0 0 0 14 0 + 238 3840 0 0 0 0 0 15 0 + 254 4096 0 0 0 0 0 1 0 + ... + +Overall the combined zspage chain size effect on zsmalloc pool configuration::: + + pages per zspage number of size classes (clusters) huge size class watermark + 4 69 3264 + 5 86 3408 + 6 93 3504 + 7 112 3584 + 8 123 3632 + 9 140 3680 + 10 143 3712 + 11 159 3744 + 12 164 3776 + 13 180 3792 + 14 183 3808 + 15 188 3840 + 16 191 3840 + + +A synthetic test +---------------- + +zram as a build artifacts storage (Linux kernel compilation). + +* `CONFIG_ZSMALLOC_CHAIN_SIZE=4` + + zsmalloc classes stats::: + + class size almost_full almost_empty obj_allocated obj_used pages_used pages_per_zspage freeable + ... + Total 13 51 413836 412973 159955 3 + + zram mm_stat::: + + 1691783168 628083717 655175680 0 655175680 60 0 34048 34049 + + +* `CONFIG_ZSMALLOC_CHAIN_SIZE=8` + + zsmalloc classes stats::: + + class size almost_full almost_empty obj_allocated obj_used pages_used pages_per_zspage freeable + ... + Total 18 87 414852 412978 156666 0 + + zram mm_stat::: + + 1691803648 627793930 641703936 0 641703936 60 0 33591 33591 + +Using larger zspage chains may result in using fewer physical pages, as seen +in the example where the number of physical pages used decreased from 159955 +to 156666, at the same time maximum zsmalloc pool memory usage went down from +655175680 to 641703936 bytes. + +However, this advantage may be offset by the potential for increased system +memory pressure (as some zspages have larger chain sizes) in cases where there +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). diff --git a/Documentation/netlink/genetlink-c.yaml b/Documentation/netlink/genetlink-c.yaml new file mode 100644 index 000000000000..bbcfa2472b04 --- /dev/null +++ b/Documentation/netlink/genetlink-c.yaml @@ -0,0 +1,331 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://kernel.org/schemas/netlink/genetlink-c.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 genetlink protocol +type: object +required: [ name, doc, attribute-sets, operations ] +additionalProperties: False +properties: + name: + description: Name of the genetlink family. + 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 ] + # Start genetlink-c + uapi-header: + description: Path to the uAPI header, default is linux/${family-name}.h + type: string + c-family-name: + 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. + type: string + max-by-define: + description: Makes the number of attributes and commands be specified by a define, not an enum value. + type: boolean + # End genetlink-c + + 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 ] + 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 + + 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, type ] + additionalProperties: False + properties: + name: + type: string + type: &attr-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' + sub-type: *attr-type + + # 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 ] + + 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 ] + 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 + 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 ] + 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 + 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 diff --git a/Documentation/netlink/genetlink-legacy.yaml b/Documentation/netlink/genetlink-legacy.yaml new file mode 100644 index 000000000000..5642925c4ceb --- /dev/null +++ b/Documentation/netlink/genetlink-legacy.yaml @@ -0,0 +1,361 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://kernel.org/schemas/netlink/genetlink-legacy.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 genetlink protocol +type: object +required: [ name, doc, attribute-sets, operations ] +additionalProperties: False +properties: + name: + description: Name of the genetlink family. + 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 + # Start genetlink-c + uapi-header: + description: Path to the uAPI header, default is linux/${family-name}.h + type: string + c-family-name: + 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. + type: string + max-by-define: + description: Makes the number of attributes and commands be specified by a define, not an enum value. + type: boolean + # 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: + enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string ] + len: + $ref: '#/$defs/len-or-define' + # 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, type ] + additionalProperties: False + properties: + name: + type: string + type: &attr-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' + sub-type: *attr-type + + # 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 ] + + 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 + 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 ] + 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 diff --git a/Documentation/netlink/genetlink.yaml b/Documentation/netlink/genetlink.yaml new file mode 100644 index 000000000000..62a922755ce2 --- /dev/null +++ b/Documentation/netlink/genetlink.yaml @@ -0,0 +1,296 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://kernel.org/schemas/netlink/genetlink-legacy.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 genetlink protocol +type: object +required: [ name, doc, attribute-sets, operations ] +additionalProperties: False +properties: + name: + description: Name of the genetlink family. + 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 ] + + 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 ] + 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 + + 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 + attributes: + description: List of attributes in the space. + type: array + items: + type: object + required: [ name, type ] + additionalProperties: False + properties: + name: + type: string + type: &attr-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' + sub-type: *attr-type + + # 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 ] + + 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 ] + 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 + 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 ] + 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 + 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 + flags: *cmd_flags diff --git a/Documentation/netlink/specs/ethtool.yaml b/Documentation/netlink/specs/ethtool.yaml new file mode 100644 index 000000000000..08b776908d15 --- /dev/null +++ b/Documentation/netlink/specs/ethtool.yaml @@ -0,0 +1,397 @@ +name: ethtool + +protocol: genetlink-legacy + +doc: Partial family for Ethtool Netlink. + +attribute-sets: + - + name: header + attributes: + - + name: dev-index + type: u32 + value: 1 + - + name: dev-name + type: string + - + name: flags + type: u32 + + - + name: bitset-bit + attributes: + - + name: index + type: u32 + value: 1 + - + name: name + type: string + - + name: value + type: flag + - + name: bitset-bits + attributes: + - + name: bit + type: nest + nested-attributes: bitset-bit + value: 1 + - + name: bitset + attributes: + - + name: nomask + type: flag + value: 1 + - + name: size + type: u32 + - + name: bits + type: nest + nested-attributes: bitset-bits + + - + name: string + attributes: + - + name: index + type: u32 + value: 1 + - + name: value + type: string + - + name: strings + attributes: + - + name: string + type: nest + value: 1 + multi-attr: true + nested-attributes: string + - + name: stringset + attributes: + - + name: id + type: u32 + value: 1 + - + name: count + type: u32 + - + name: strings + type: nest + multi-attr: true + nested-attributes: strings + - + name: stringsets + attributes: + - + name: stringset + type: nest + multi-attr: true + value: 1 + nested-attributes: stringset + - + name: strset + attributes: + - + name: header + value: 1 + type: nest + nested-attributes: header + - + name: stringsets + type: nest + nested-attributes: stringsets + - + name: counts-only + type: flag + + - + name: privflags + attributes: + - + name: header + value: 1 + type: nest + nested-attributes: header + - + name: flags + type: nest + nested-attributes: bitset + + - + name: rings + attributes: + - + name: header + value: 1 + type: nest + nested-attributes: header + - + name: rx-max + type: u32 + - + name: rx-mini-max + type: u32 + - + name: rx-jumbo-max + type: u32 + - + name: tx-max + type: u32 + - + name: rx + type: u32 + - + name: rx-mini + type: u32 + - + name: rx-jumbo + type: u32 + - + name: tx + type: u32 + - + name: rx-buf-len + type: u32 + - + name: tcp-data-split + type: u8 + - + name: cqe-size + type: u32 + - + name: tx-push + type: u8 + - + name: rx-push + type: u8 + + - + name: mm-stat + attributes: + - + name: pad + value: 1 + type: pad + - + name: reassembly-errors + type: u64 + - + name: smd-errors + type: u64 + - + name: reassembly-ok + type: u64 + - + name: rx-frag-count + type: u64 + - + name: tx-frag-count + type: u64 + - + name: hold-count + type: u64 + - + name: mm + attributes: + - + name: header + value: 1 + type: nest + nested-attributes: header + - + name: pmac-enabled + type: u8 + - + name: tx-enabled + type: u8 + - + name: tx-active + type: u8 + - + name: tx-min-frag-size + type: u32 + - + name: tx-min-frag-size + type: u32 + - + name: verify-enabled + type: u8 + - + name: verify-status + type: u8 + - + name: verify-time + type: u32 + - + name: max-verify-time + type: u32 + - + name: stats + type: nest + nested-attributes: mm-stat + +operations: + enum-model: directional + list: + - + name: strset-get + doc: Get string set from the kernel. + + attribute-set: strset + + do: &strset-get-op + request: + value: 1 + attributes: + - header + - stringsets + - counts-only + reply: + value: 1 + attributes: + - header + - stringsets + dump: *strset-get-op + + # TODO: fill in the requests in between + + - + name: privflags-get + doc: Get device private flags. + + attribute-set: privflags + + do: &privflag-get-op + request: + value: 13 + attributes: + - header + reply: + value: 14 + attributes: + - header + - flags + dump: *privflag-get-op + - + name: privflags-set + doc: Set device private flags. + + attribute-set: privflags + + do: + request: + attributes: + - header + - flags + - + name: privflags-ntf + doc: Notification for change in device private flags. + notify: privflags-get + + - + name: rings-get + doc: Get ring params. + + attribute-set: rings + + do: &ring-get-op + request: + attributes: + - header + reply: + attributes: + - header + - rx-max + - rx-mini-max + - rx-jumbo-max + - tx-max + - rx + - rx-mini + - rx-jumbo + - tx + - rx-buf-len + - tcp-data-split + - cqe-size + - tx-push + - rx-push + dump: *ring-get-op + - + name: rings-set + doc: Set ring params. + + attribute-set: rings + + do: + request: + attributes: + - header + - rx + - rx-mini + - rx-jumbo + - tx + - rx-buf-len + - tcp-data-split + - cqe-size + - tx-push + - rx-push + - + name: rings-ntf + doc: Notification for change in ring params. + notify: rings-get + + # TODO: fill in the requests in between + + - + name: mm-get + doc: Get MAC Merge configuration and state + + attribute-set: mm + + do: &mm-get-op + request: + value: 42 + attributes: + - header + reply: + value: 42 + attributes: + - header + - pmac-enabled + - tx-enabled + - tx-active + - tx-min-frag-size + - rx-min-frag-size + - verify-enabled + - verify-time + - max-verify-time + - stats + dump: *mm-get-op + - + name: mm-set + doc: Set MAC Merge configuration + + attribute-set: mm + + do: + request: + attributes: + - header + - verify-enabled + - verify-time + - tx-enabled + - pmac-enabled + - tx-min-frag-size + - + name: mm-ntf + doc: Notification for change in MAC Merge configuration. + notify: mm-get diff --git a/Documentation/netlink/specs/fou.yaml b/Documentation/netlink/specs/fou.yaml new file mode 100644 index 000000000000..266c386eedf3 --- /dev/null +++ b/Documentation/netlink/specs/fou.yaml @@ -0,0 +1,128 @@ +name: fou + +protocol: genetlink-legacy + +doc: | + Foo-over-UDP. + +c-family-name: fou-genl-name +c-version-name: fou-genl-version +max-by-define: true +kernel-policy: global + +definitions: + - + type: enum + name: encap_type + name-prefix: fou-encap- + enum-name: + entries: [ unspec, direct, gue ] + +attribute-sets: + - + name: fou + name-prefix: fou-attr- + attributes: + - + name: unspec + type: unused + - + name: port + type: u16 + byte-order: big-endian + - + name: af + type: u8 + - + name: ipproto + type: u8 + - + name: type + type: u8 + - + name: remcsum_nopartial + type: flag + - + name: local_v4 + type: u32 + - + name: local_v6 + type: binary + checks: + min-len: 16 + - + name: peer_v4 + type: u32 + - + name: peer_v6 + type: binary + checks: + min-len: 16 + - + name: peer_port + type: u16 + byte-order: big-endian + - + name: ifindex + type: s32 + +operations: + list: + - + name: unspec + doc: unused + + - + name: add + doc: Add port. + attribute-set: fou + + dont-validate: [ strict, dump ] + flags: [ admin-perm ] + + do: + request: &all_attrs + attributes: + - port + - ipproto + - type + - remcsum_nopartial + - local_v4 + - peer_v4 + - local_v6 + - peer_v6 + - peer_port + - ifindex + + - + name: del + doc: Delete port. + attribute-set: fou + + dont-validate: [ strict, dump ] + flags: [ admin-perm ] + + do: + request: &select_attrs + attributes: + - af + - ifindex + - port + - peer_port + - local_v4 + - peer_v4 + - local_v6 + - peer_v6 + + - + name: get + doc: Get tunnel info. + attribute-set: fou + dont-validate: [ strict, dump ] + + do: + request: *select_attrs + reply: *all_attrs + + dump: + reply: *all_attrs diff --git a/Documentation/netlink/specs/netdev.yaml b/Documentation/netlink/specs/netdev.yaml new file mode 100644 index 000000000000..b4dcdae54ffd --- /dev/null +++ b/Documentation/netlink/specs/netdev.yaml @@ -0,0 +1,100 @@ +name: netdev + +doc: + netdev configuration over generic netlink. + +definitions: + - + type: flags + name: xdp-act + entries: + - + name: basic + doc: + XDP feautues set supported by all drivers + (XDP_ABORTED, XDP_DROP, XDP_PASS, XDP_TX) + - + name: redirect + doc: + The netdev supports XDP_REDIRECT + - + name: ndo-xmit + doc: + This feature informs if netdev implements ndo_xdp_xmit callback. + - + name: xsk-zerocopy + doc: + This feature informs if netdev supports AF_XDP in zero copy mode. + - + name: hw-offload + doc: + This feature informs if netdev supports XDP hw oflloading. + - + name: rx-sg + doc: + This feature informs if netdev implements non-linear XDP buffer + support in the driver napi callback. + - + name: ndo-xmit-sg + doc: + This feature informs if netdev implements non-linear XDP buffer + support in ndo_xdp_xmit callback. + +attribute-sets: + - + name: dev + attributes: + - + name: ifindex + doc: netdev ifindex + type: u32 + value: 1 + checks: + min: 1 + - + name: pad + type: pad + - + name: xdp-features + doc: Bitmask of enabled xdp-features. + type: u64 + enum: xdp-act + enum-as-flags: true + +operations: + list: + - + name: dev-get + doc: Get / dump information about a netdev. + value: 1 + attribute-set: dev + do: + request: + attributes: + - ifindex + reply: &dev-all + attributes: + - ifindex + - xdp-features + dump: + reply: *dev-all + - + name: dev-add-ntf + doc: Notification about device appearing. + notify: dev-get + mcgrp: mgmt + - + name: dev-del-ntf + doc: Notification about device disappearing. + notify: dev-get + mcgrp: mgmt + - + name: dev-change-ntf + doc: Notification about device configuration being changed. + notify: dev-get + mcgrp: mgmt + +mcast-groups: + list: + - + name: mgmt diff --git a/Documentation/networking/af_xdp.rst b/Documentation/networking/af_xdp.rst index 60b217b436be..247c6c4127e9 100644 --- a/Documentation/networking/af_xdp.rst +++ b/Documentation/networking/af_xdp.rst @@ -419,7 +419,7 @@ XDP_UMEM_REG setsockopt ----------------------- This setsockopt registers a UMEM to a socket. This is the area that -contain all the buffers that packet can recide in. The call takes a +contain all the buffers that packet can reside in. The call takes a pointer to the beginning of this area and the size of it. Moreover, it also has parameter called chunk_size that is the size that the UMEM is divided into. It can only be 2K or 4K at the moment. If you have an @@ -592,7 +592,7 @@ A: When a netdev of a physical NIC is initialized, Linux usually A number of other ways are possible all up to the capabilities of the NIC you have. -Q: Can I use the XSKMAP to implement a switch betwen different umems +Q: Can I use the XSKMAP to implement a switch between different umems in copy mode? A: The short answer is no, that is not supported at the moment. The diff --git a/Documentation/networking/arcnet-hardware.rst b/Documentation/networking/arcnet-hardware.rst index ac249ac8fcf2..982215723582 100644 --- a/Documentation/networking/arcnet-hardware.rst +++ b/Documentation/networking/arcnet-hardware.rst @@ -1902,7 +1902,7 @@ of 32 possible I/O Base addresses using the following tables:: 6 | 10 The I/O address is sum of all switches set to "1". Remember that -the I/O address space bellow 0x200 is RESERVED for mainboard, so +the I/O address space below 0x200 is RESERVED for mainboard, so switch 1 should be ALWAYS SET TO OFF. diff --git a/Documentation/networking/batman-adv.rst b/Documentation/networking/batman-adv.rst index b85563ea3682..8a0dcb1894b4 100644 --- a/Documentation/networking/batman-adv.rst +++ b/Documentation/networking/batman-adv.rst @@ -159,7 +159,7 @@ Please send us comments, experiences, questions, anything :) IRC: #batadv on ircs://irc.hackint.org/ Mailing-list: - b.a.t.m.a.n@open-mesh.org (optional subscription at + b.a.t.m.a.n@lists.open-mesh.org (optional subscription at https://lists.open-mesh.org/mailman3/postorius/lists/b.a.t.m.a.n.lists.open-mesh.org/) You can also contact the Authors: diff --git a/Documentation/networking/bridge.rst b/Documentation/networking/bridge.rst index 4aef9cddde2f..c859f3c1636e 100644 --- a/Documentation/networking/bridge.rst +++ b/Documentation/networking/bridge.rst @@ -8,7 +8,7 @@ In order to use the Ethernet bridging functionality, you'll need the userspace tools. Documentation for Linux bridging is on: - http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge + https://wiki.linuxfoundation.org/networking/bridge The bridge-utilities are maintained at: git://git.kernel.org/pub/scm/linux/kernel/git/shemminger/bridge-utils.git diff --git a/Documentation/networking/can.rst b/Documentation/networking/can.rst index 90121deef217..d7e1ada905b2 100644 --- a/Documentation/networking/can.rst +++ b/Documentation/networking/can.rst @@ -931,7 +931,7 @@ ival1: ival2: Throttle the received message rate down to the value of ival2. This is useful to reduce messages for the application when the signal inside the - CAN frame is stateless as state changes within the ival2 periode may get + CAN frame is stateless as state changes within the ival2 period may get lost. Broadcast Manager Multiplex Message Receive Filter diff --git a/Documentation/networking/can_ucan_protocol.rst b/Documentation/networking/can_ucan_protocol.rst index 638ac1ee7914..935d872ae87c 100644 --- a/Documentation/networking/can_ucan_protocol.rst +++ b/Documentation/networking/can_ucan_protocol.rst @@ -50,7 +50,7 @@ Setup Packet ``wIndex`` USB Interface Index (0 for device commands) ``wLength`` * Host to Device - Number of bytes to transmit * Device to Host - Maximum Number of bytes to - receive. If the device send less. Commom ZLP + receive. If the device send less. Common ZLP semantics are used. ================= ===================================================== diff --git a/Documentation/networking/cdc_mbim.rst b/Documentation/networking/cdc_mbim.rst index 0048409c06b4..37f968acc473 100644 --- a/Documentation/networking/cdc_mbim.rst +++ b/Documentation/networking/cdc_mbim.rst @@ -93,7 +93,7 @@ MBIM function can be looked up using sysfs. For example:: USB configuration descriptors ----------------------------- The wMaxControlMessage field of the CDC MBIM functional descriptor -limits the maximum control message size. The managament application is +limits the maximum control message size. The management application is responsible for negotiating a control message size complying with the requirements in section 9.3.1 of [1], taking this descriptor field into consideration. diff --git a/Documentation/networking/device_drivers/atm/iphase.rst b/Documentation/networking/device_drivers/atm/iphase.rst index 92d9b757d75a..388c7101e2cb 100644 --- a/Documentation/networking/device_drivers/atm/iphase.rst +++ b/Documentation/networking/device_drivers/atm/iphase.rst @@ -4,7 +4,7 @@ ATM (i)Chip IA Linux Driver Source ================================== - READ ME FISRT + READ ME FIRST -------------------------------------------------------------------------------- diff --git a/Documentation/networking/device_drivers/can/ctu/ctucanfd-driver.rst b/Documentation/networking/device_drivers/can/ctu/ctucanfd-driver.rst index 40c92ea272af..1a4fc6607582 100644 --- a/Documentation/networking/device_drivers/can/ctu/ctucanfd-driver.rst +++ b/Documentation/networking/device_drivers/can/ctu/ctucanfd-driver.rst @@ -577,7 +577,7 @@ CTU CAN FD IP Core and Driver Development Acknowledgment * Linux driver development * continuous integration platform architect and GHDL updates - * theses `Open-source and Open-hardware CAN FD Protocol Support <https://dspace.cvut.cz/bitstream/handle/10467/80366/F3-DP-2019-Jerabek-Martin-Jerabek-thesis-2019-canfd.pdf>`_ + * thesis `Open-source and Open-hardware CAN FD Protocol Support <https://dspace.cvut.cz/bitstream/handle/10467/80366/F3-DP-2019-Jerabek-Martin-Jerabek-thesis-2019-canfd.pdf>`_ * Jiri Novak <jnovak@fel.cvut.cz> @@ -603,7 +603,7 @@ CTU CAN FD IP Core and Driver Development Acknowledgment * Jan Charvat * implemented CTU CAN FD functional model for QEMU which has been integrated into QEMU mainline (`docs/system/devices/can.rst <https://www.qemu.org/docs/master/system/devices/can.html>`_) - * Bachelor theses Model of CAN FD Communication Controller for QEMU Emulator + * Bachelor thesis Model of CAN FD Communication Controller for QEMU Emulator Notes ----- diff --git a/Documentation/networking/device_drivers/can/ctu/fsm_txt_buffer_user.svg b/Documentation/networking/device_drivers/can/ctu/fsm_txt_buffer_user.svg index b371650788f4..381323423b4c 100644 --- a/Documentation/networking/device_drivers/can/ctu/fsm_txt_buffer_user.svg +++ b/Documentation/networking/device_drivers/can/ctu/fsm_txt_buffer_user.svg @@ -129,10 +129,10 @@ </g> </g> <text transform="matrix(.264583 0 0 .264583 91.8919 139.964)" x="26.959213" y="9.11724" fill="#2aa1ff" filter="url(#filter1204-6-2-9-1-3-1)" font-size="12px" stroke-width="3.77953" text-align="center" text-anchor="middle" style="line-height:1.1" xml:space="preserve"><tspan x="26.959213" y="9.11724" text-align="center">Set</tspan><tspan x="26.959213" y="22.31724" text-align="center">abort</tspan></text> - <text transform="translate(49.0277 104.823)" x="57.620724" y="16.855087" filter="url(#filter1204)" font-size="3.175px" text-align="center" text-anchor="middle" style="line-height:1.1" xml:space="preserve"><tspan x="57.620724" y="16.855087" text-align="center">Transmission</tspan><tspan x="57.620724" y="20.347588" text-align="center">unsuccesfull</tspan></text> + <text transform="translate(49.0277 104.823)" x="57.620724" y="16.855087" filter="url(#filter1204)" font-size="3.175px" text-align="center" text-anchor="middle" style="line-height:1.1" xml:space="preserve"><tspan x="57.620724" y="16.855087" text-align="center">Transmission</tspan><tspan x="57.620724" y="20.347588" text-align="center">unsuccessful</tspan></text> <g font-size="12px" stroke-width="3.77953" text-anchor="middle"> <text transform="matrix(.264583 0 0 .264583 68.5988 118.913)" x="38.824219" y="9.1171875" filter="url(#filter1204)" text-align="center" style="line-height:1.1" xml:space="preserve"><tspan x="38.824219" y="9.1171875" text-align="center">Transmission</tspan><tspan x="38.824219" y="22.317188" text-align="center">starts</tspan></text> - <text transform="matrix(.264583 0 0 .264583 106.802 130.509)" x="38.824219" y="9.1171875" filter="url(#filter1204)" text-align="center" style="line-height:1.1" xml:space="preserve"><tspan x="38.824219" y="9.1171875" text-align="center">Transmission</tspan><tspan x="38.824219" y="22.317188" text-align="center">succesfull</tspan></text> + <text transform="matrix(.264583 0 0 .264583 106.802 130.509)" x="38.824219" y="9.1171875" filter="url(#filter1204)" text-align="center" style="line-height:1.1" xml:space="preserve"><tspan x="38.824219" y="9.1171875" text-align="center">Transmission</tspan><tspan x="38.824219" y="22.317188" text-align="center">successful</tspan></text> <text transform="matrix(.264583 0 0 .264583 107.77 145.476)" x="38.824219" y="9.1171875" filter="url(#filter1204)" text-align="center" style="line-height:1.1" xml:space="preserve"><tspan x="38.824219" y="9.1171875" text-align="center">Transmission</tspan><tspan x="38.824219" y="22.317188" text-align="center">sborted</tspan></text> </g> <g stroke-width="3.77953" text-anchor="middle"> diff --git a/Documentation/networking/device_drivers/ethernet/3com/vortex.rst b/Documentation/networking/device_drivers/ethernet/3com/vortex.rst index e89e4192af88..a060f84c4f96 100644 --- a/Documentation/networking/device_drivers/ethernet/3com/vortex.rst +++ b/Documentation/networking/device_drivers/ethernet/3com/vortex.rst @@ -254,7 +254,7 @@ Media selection A number of the older NICs such as the 3c590 and 3c900 series have 10base2 and AUI interfaces. -Prior to January, 2001 this driver would autoeselect the 10base2 or AUI +Prior to January, 2001 this driver would autoselect the 10base2 or AUI port if it didn't detect activity on the 10baseT port. It would then get stuck on the 10base2 port and a driver reload was necessary to switch back to 10baseT. This behaviour could not be prevented with a diff --git a/Documentation/networking/device_drivers/ethernet/aquantia/atlantic.rst b/Documentation/networking/device_drivers/ethernet/aquantia/atlantic.rst index 595ddef1c8b3..099280a261be 100644 --- a/Documentation/networking/device_drivers/ethernet/aquantia/atlantic.rst +++ b/Documentation/networking/device_drivers/ethernet/aquantia/atlantic.rst @@ -270,7 +270,7 @@ RX flow rules (ntuple filters) ethtool -K ethX ntuple <on|off> - When disabling ntuple filters, all the user programed filters are + When disabling ntuple filters, all the user programmed filters are flushed from the driver cache and hardware. All needed filters must be re-added when ntuple is re-enabled. @@ -418,7 +418,7 @@ Default value: 0xFFFF 0 Disable interrupt throttling. 1 Enable interrupt throttling and use specified tx and rx rates. 0xFFFF Auto throttling mode. Driver will choose the best RX and TX - interrupt throtting settings based on link speed. + interrupt throttling settings based on link speed. ====== ============================================================== aq_itr_tx - TX interrupt throttle rate @@ -456,7 +456,7 @@ AQ_CFG_RX_PAGEORDER Default value: 0 -RX page order override. Thats a power of 2 number of RX pages allocated for +RX page order override. That's a power of 2 number of RX pages allocated for each descriptor. Received descriptor size is still limited by AQ_CFG_RX_FRAME_MAX. diff --git a/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/mac-phy-support.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/mac-phy-support.rst index 1d2f55feca24..e2a36d0d88ef 100644 --- a/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/mac-phy-support.rst +++ b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/mac-phy-support.rst @@ -11,7 +11,7 @@ Overview -------- The DPAA2 MAC / PHY support consists of a set of APIs that help DPAA2 network -drivers (dpaa2-eth, dpaa2-ethsw) interract with the PHY library. +drivers (dpaa2-eth, dpaa2-ethsw) interact with the PHY library. DPAA2 Software Architecture --------------------------- diff --git a/Documentation/networking/device_drivers/ethernet/index.rst b/Documentation/networking/device_drivers/ethernet/index.rst index 5196905582c5..392969ac88ad 100644 --- a/Documentation/networking/device_drivers/ethernet/index.rst +++ b/Documentation/networking/device_drivers/ethernet/index.rst @@ -39,7 +39,7 @@ Contents: intel/ice marvell/octeontx2 marvell/octeon_ep - mellanox/mlx5 + mellanox/mlx5/index microsoft/netvsc neterion/s2io netronome/nfp diff --git a/Documentation/networking/device_drivers/ethernet/intel/ice.rst b/Documentation/networking/device_drivers/ethernet/intel/ice.rst index dc2e60ced927..5efea4dd1251 100644 --- a/Documentation/networking/device_drivers/ethernet/intel/ice.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/ice.rst @@ -819,7 +819,7 @@ NAPI ---- This driver supports NAPI (Rx polling mode). For more information on NAPI, see -https://www.linuxfoundation.org/collaborate/workgroups/networking/napi +https://wiki.linuxfoundation.org/networking/napi MACVLAN @@ -901,15 +901,17 @@ To enable/disable UDP Segmentation Offload, issue the following command:: # ethtool -K <ethX> tx-udp-segmentation [off|on] + GNSS module ----------- -Allows user to read messages from the GNSS module and write supported commands. -If the module is physically present, driver creates 2 TTYs for each supported -device in /dev, ttyGNSS_<device>:<function>_0 and _1. First one (_0) is RW and -the second one is RO. -The protocol of write commands is dependent on the GNSS module as the driver -writes raw bytes from the TTY to the GNSS i2c. Please refer to the module -documentation for details. +Requires kernel compiled with CONFIG_GNSS=y or CONFIG_GNSS=m. +Allows user to read messages from the GNSS hardware module and write supported +commands. If the module is physically present, a GNSS device is spawned: +``/dev/gnss<id>``. +The protocol of write command is dependent on the GNSS hardware module as the +driver writes raw bytes by the GNSS object to the receiver through i2c. Please +refer to the hardware GNSS module documentation for configuration details. + Performance Optimization ======================== diff --git a/Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst b/Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst index dd5cd69467be..5ba9015336e2 100644 --- a/Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst +++ b/Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst @@ -127,7 +127,7 @@ Type1: Type2: - RVU PF0 ie admin function creates these VFs and maps them to loopback block's channels. - A set of two VFs (VF0 & VF1, VF2 & VF3 .. so on) works as a pair ie pkts sent out of - VF0 will be received by VF1 and viceversa. + VF0 will be received by VF1 and vice versa. - These VFs can be used by applications or virtual machines to communicate between them without sending traffic outside. There is no switch present in HW, hence the support for loopback VFs. diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst deleted file mode 100644 index 6969652f593c..000000000000 --- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst +++ /dev/null @@ -1,746 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 OR Linux-OpenIB - -================================================= -Mellanox ConnectX(R) mlx5 core VPI Network Driver -================================================= - -Copyright (c) 2019, Mellanox Technologies LTD. - -Contents -======== - -- `Enabling the driver and kconfig options`_ -- `Devlink info`_ -- `Devlink parameters`_ -- `Bridge offload`_ -- `mlx5 subfunction`_ -- `mlx5 function attributes`_ -- `Devlink health reporters`_ -- `mlx5 tracepoints`_ - -Enabling the driver and kconfig options -======================================= - -| mlx5 core is modular and most of the major mlx5 core driver features can be selected (compiled in/out) -| at build time via kernel Kconfig flags. -| Basic features, ethernet net device rx/tx offloads and XDP, are available with the most basic flags -| CONFIG_MLX5_CORE=y/m and CONFIG_MLX5_CORE_EN=y. -| For the list of advanced features, please see below. - -**CONFIG_MLX5_CORE=(y/m/n)** (module mlx5_core.ko) - -| The driver can be enabled by choosing CONFIG_MLX5_CORE=y/m in kernel config. -| This will provide mlx5 core driver for mlx5 ulps to interface with (mlx5e, mlx5_ib). - - -**CONFIG_MLX5_CORE_EN=(y/n)** - -| Choosing this option will allow basic ethernet netdevice support with all of the standard rx/tx offloads. -| mlx5e is the mlx5 ulp driver which provides netdevice kernel interface, when chosen, mlx5e will be -| built-in into mlx5_core.ko. - - -**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 - - -**CONFIG_MLX5_EN_RXNFC=(y/n)** - -| Enables ethtool receive network flow classification, which allows user defined -| flow rules to direct traffic into arbitrary rx queue via ethtool set/get_rxnfc API. - - -**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>`_. - - -**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 -| user configured unicast MAC addresses to the requesting PF. - - -**CONFIG_MLX5_ESWITCH=(y/n)** - -| 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>`_. - - -**CONFIG_MLX5_CORE_IPOIB=(y/n)** - -| IPoIB offloads & acceleration support. -| Requires CONFIG_MLX5_CORE_EN to provide an accelerated interface for the rdma -| IPoIB ulp netdevice. - - -**CONFIG_MLX5_FPGA=(y/n)** - -| Build support for the Innova family of network cards by Mellanox Technologies. -| Innova network cards are comprised of a ConnectX chip and an FPGA chip on one board. -| If you select this option, the mlx5_core driver will include the Innova FPGA core and allow -| building sandbox-specific client drivers. - - -**CONFIG_MLX5_EN_IPSEC=(y/n)** - -| Enables `IPSec XFRM cryptography-offload acceleration <http://www.mellanox.com/related-docs/prod_software/Mellanox_Innova_IPsec_Ethernet_Adapter_Card_User_Manual.pdf>`_. - -**CONFIG_MLX5_EN_TLS=(y/n)** - -| TLS cryptography-offload acceleration. - - -**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. - -**CONFIG_MLX5_SF=(y/n)** - -| Build support for subfunction. -| Subfunctons are more light weight than PCI SRIOV VFs. Choosing this option -| will enable support for creating subfunction devices. - -**External options** ( Choose if the corresponding mlx5 feature is required ) - -- CONFIG_PTP_1588_CLOCK: When chosen, mlx5 ptp support will be enabled -- CONFIG_VXLAN: When chosen, mlx5 vxlan support will be enabled. -- CONFIG_MLXFW: When chosen, mlx5 firmware flashing support will be enabled (via devlink and ethtool). - -Devlink 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 - -Devlink 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 ----------------------------------- -RoCE enablement state controls driver support for RoCE traffic. -When RoCE is disabled, there is no gid table, only raw ethernet QPs are supported and traffic on the well-known UDP RoCE port is handled as raw ethernet traffic. - -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 - -Bridge offload -============== -The mlx5 driver implements support for offloading bridge rules when in switchdev -mode. Linux bridge FDBs are automatically offloaded when mlx5 switchdev -representor is attached to bridge. - -- Change device to switchdev mode:: - - $ devlink dev eswitch set pci/0000:06:00.0 mode switchdev - -- Attach mlx5 switchdev representor 'enp8s0f0' to bridge netdev 'bridge1':: - - $ ip link set enp8s0f0 master bridge1 - -VLANs ------ -Following bridge VLAN functions are supported by mlx5: - -- VLAN filtering (including multiple VLANs per port):: - - $ ip link set bridge1 type bridge vlan_filtering 1 - $ bridge vlan add dev enp8s0f0 vid 2-3 - -- VLAN push on bridge ingress:: - - $ bridge vlan add dev enp8s0f0 vid 3 pvid - -- VLAN pop on bridge egress:: - - $ bridge vlan add dev enp8s0f0 vid 3 untagged - -mlx5 subfunction -================ -mlx5 supports subfunction management using devlink port (see :ref:`Documentation/networking/devlink/devlink-port.rst <devlink_port>`) interface. - -A subfunction has its own function capabilities and its own resources. This -means a subfunction has its own dedicated queues (txq, rxq, cq, eq). These -queues are neither shared nor stolen from the parent PCI function. - -When a subfunction is RDMA capable, it has its own QP1, GID table, and RDMA -resources neither shared nor stolen from the parent PCI function. - -A subfunction has a dedicated window in PCI BAR space that is not shared -with the other subfunctions or the parent PCI function. This ensures that all -devices (netdev, rdma, vdpa, etc.) of the subfunction accesses only assigned -PCI BAR space. - -A subfunction supports eswitch representation through which it supports tc -offloads. The user configures eswitch to send/receive packets from/to -the subfunction port. - -Subfunctions share PCI level resources such as PCI MSI-X IRQs with -other subfunctions and/or with its parent PCI function. - -Example mlx5 software, system, and device view:: - - _______ - | admin | - | user |---------- - |_______| | - | | - ____|____ __|______ _________________ - | | | | | | - | devlink | | tc tool | | user | - | tool | |_________| | applications | - |_________| | |_________________| - | | | | - | | | | Userspace - +---------|-------------|-------------------|----------|--------------------+ - | | +----------+ +----------+ Kernel - | | | netdev | | rdma dev | - | | +----------+ +----------+ - (devlink port add/del | ^ ^ - port function set) | | | - | | +---------------| - _____|___ | | _______|_______ - | | | | | mlx5 class | - | devlink | +------------+ | | drivers | - | kernel | | rep netdev | | |(mlx5_core,ib) | - |_________| +------------+ | |_______________| - | | | ^ - (devlink ops) | | (probe/remove) - _________|________ | | ____|________ - | subfunction | | +---------------+ | subfunction | - | management driver|----- | subfunction |---| driver | - | (mlx5_core) | | auxiliary dev | | (mlx5_core) | - |__________________| +---------------+ |_____________| - | ^ - (sf add/del, vhca events) | - | (device add/del) - _____|____ ____|________ - | | | subfunction | - | PCI NIC |--- activate/deactivate events--->| host driver | - |__________| | (mlx5_core) | - |_____________| - -Subfunction is created using devlink port interface. - -- Change device to switchdev mode:: - - $ devlink dev eswitch set pci/0000:06:00.0 mode switchdev - -- Add a devlink port of subfunction flavour:: - - $ devlink port add pci/0000:06:00.0 flavour pcisf pfnum 0 sfnum 88 - pci/0000:06:00.0/32768: type eth netdev eth6 flavour pcisf controller 0 pfnum 0 sfnum 88 external false splittable false - function: - hw_addr 00:00:00:00:00:00 state inactive opstate detached - -- Show a devlink port of the subfunction:: - - $ devlink port show pci/0000:06:00.0/32768 - pci/0000:06:00.0/32768: type eth netdev enp6s0pf0sf88 flavour pcisf pfnum 0 sfnum 88 - function: - hw_addr 00:00:00:00:00:00 state inactive opstate detached - -- Delete a devlink port of subfunction after use:: - - $ devlink port del pci/0000:06:00.0/32768 - -mlx5 function attributes -======================== -The mlx5 driver provides a mechanism to setup PCI VF/SF function attributes in -a unified way for SmartNIC and non-SmartNIC. - -This is supported only when the eswitch mode is set to switchdev. Port function -configuration of the PCI VF/SF is supported through devlink eswitch port. - -Port function attributes should be set before PCI VF/SF is enumerated by the -driver. - -MAC address setup ------------------ -mlx5 driver support devlink port function attr mechanism to setup MAC -address. (refer to Documentation/networking/devlink/devlink-port.rst) - -RoCE capability setup ---------------------- -Not all mlx5 PCI devices/SFs require RoCE capability. - -When RoCE capability is disabled, it saves 1 Mbytes worth of system memory per -PCI devices/SF. - -mlx5 driver support devlink port function attr mechanism to setup RoCE -capability. (refer to Documentation/networking/devlink/devlink-port.rst) - -migratable capability setup ---------------------------- -User who wants mlx5 PCI VFs to be able to perform live migration need to -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) - -SF state setup --------------- -To use the SF, the user must activate the SF using the SF function state -attribute. - -- Get the state of the SF identified by its unique devlink port index:: - - $ devlink port show ens2f0npf0sf88 - pci/0000:06:00.0/32768: type eth netdev ens2f0npf0sf88 flavour pcisf controller 0 pfnum 0 sfnum 88 external false splittable false - function: - hw_addr 00:00:00:00:88:88 state inactive opstate detached - -- Activate the function and verify its state is active:: - - $ devlink port function set ens2f0npf0sf88 state active - - $ devlink port show ens2f0npf0sf88 - pci/0000:06:00.0/32768: type eth netdev ens2f0npf0sf88 flavour pcisf controller 0 pfnum 0 sfnum 88 external false splittable false - function: - hw_addr 00:00:00:00:88:88 state active opstate detached - -Upon function activation, the PF driver instance gets the event from the device -that a particular SF was activated. It's the cue to put the device on bus, probe -it and instantiate the devlink instance and class specific auxiliary devices -for it. - -- Show the auxiliary device and port of the subfunction:: - - $ devlink dev show - devlink dev show auxiliary/mlx5_core.sf.4 - - $ devlink port show auxiliary/mlx5_core.sf.4/1 - auxiliary/mlx5_core.sf.4/1: type eth netdev p0sf88 flavour virtual port 0 splittable false - - $ rdma link show mlx5_0/1 - link mlx5_0/1 state ACTIVE physical_state LINK_UP netdev p0sf88 - - $ rdma dev show - 8: rocep6s0f1: node_type ca fw 16.29.0550 node_guid 248a:0703:00b3:d113 sys_image_guid 248a:0703:00b3:d112 - 13: mlx5_0: node_type ca fw 16.29.0550 node_guid 0000:00ff:fe00:8888 sys_image_guid 248a:0703:00b3:d112 - -- Subfunction auxiliary device and class device hierarchy:: - - mlx5_core.sf.4 - (subfunction auxiliary device) - /\ - / \ - / \ - / \ - / \ - mlx5_core.eth.4 mlx5_core.rdma.4 - (sf eth aux dev) (sf rdma aux dev) - | | - | | - p0sf88 mlx5_0 - (sf netdev) (sf rdma device) - -Additionally, the SF port also gets the event when the driver attaches to the -auxiliary device of the subfunction. This results in changing the operational -state of the function. This provides visibility to the user to decide when is it -safe to delete the SF port for graceful termination of the subfunction. - -- Show the SF port operational state:: - - $ devlink port show ens2f0npf0sf88 - pci/0000:06:00.0/32768: type eth netdev ens2f0npf0sf88 flavour pcisf controller 0 pfnum 0 sfnum 88 external false splittable false - function: - hw_addr 00:00:00:00:88:88 state active opstate attached - -Devlink 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. - -mlx5 tracepoints -================ - -mlx5 driver provides internal tracepoints for tracking and debugging using -kernel tracepoints interfaces (refer to Documentation/trace/ftrace.rst). - -For the list of support mlx5 events, check `/sys/kernel/debug/tracing/events/mlx5/`. - -tc and eswitch offloads tracepoints: - -- mlx5e_configure_flower: trace flower filter actions and cookies offloaded to mlx5:: - - $ echo mlx5:mlx5e_configure_flower >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - tc-6535 [019] ...1 2672.404466: mlx5e_configure_flower: cookie=0000000067874a55 actions= REDIRECT - -- mlx5e_delete_flower: trace flower filter actions and cookies deleted from mlx5:: - - $ echo mlx5:mlx5e_delete_flower >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - tc-6569 [010] .N.1 2686.379075: mlx5e_delete_flower: cookie=0000000067874a55 actions= NULL - -- mlx5e_stats_flower: trace flower stats request:: - - $ echo mlx5:mlx5e_stats_flower >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - tc-6546 [010] ...1 2679.704889: mlx5e_stats_flower: cookie=0000000060eb3d6a bytes=0 packets=0 lastused=4295560217 - -- mlx5e_tc_update_neigh_used_value: trace tunnel rule neigh update value offloaded to mlx5:: - - $ echo mlx5:mlx5e_tc_update_neigh_used_value >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - kworker/u48:4-8806 [009] ...1 55117.882428: mlx5e_tc_update_neigh_used_value: netdev: ens1f0 IPv4: 1.1.1.10 IPv6: ::ffff:1.1.1.10 neigh_used=1 - -- mlx5e_rep_neigh_update: trace neigh update tasks scheduled due to neigh state change events:: - - $ echo mlx5:mlx5e_rep_neigh_update >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - kworker/u48:7-2221 [009] ...1 1475.387435: mlx5e_rep_neigh_update: netdev: ens1f0 MAC: 24:8a:07:9a:17:9a IPv4: 1.1.1.10 IPv6: ::ffff:1.1.1.10 neigh_connected=1 - -Bridge offloads tracepoints: - -- mlx5_esw_bridge_fdb_entry_init: trace bridge FDB entry offloaded to mlx5:: - - $ echo mlx5:mlx5_esw_bridge_fdb_entry_init >> set_event - $ cat /sys/kernel/debug/tracing/trace - ... - kworker/u20:9-2217 [003] ...1 318.582243: mlx5_esw_bridge_fdb_entry_init: net_device=enp8s0f0_0 addr=e4:fd:05:08:00:02 vid=0 flags=0 used=0 - -- mlx5_esw_bridge_fdb_entry_cleanup: trace bridge FDB entry deleted from mlx5:: - - $ echo mlx5:mlx5_esw_bridge_fdb_entry_cleanup >> set_event - $ cat /sys/kernel/debug/tracing/trace - ... - ip-2581 [005] ...1 318.629871: mlx5_esw_bridge_fdb_entry_cleanup: net_device=enp8s0f0_1 addr=e4:fd:05:08:00:03 vid=0 flags=0 used=16 - -- mlx5_esw_bridge_fdb_entry_refresh: trace bridge FDB entry offload refreshed in - mlx5:: - - $ echo mlx5:mlx5_esw_bridge_fdb_entry_refresh >> set_event - $ cat /sys/kernel/debug/tracing/trace - ... - kworker/u20:8-3849 [003] ...1 466716: mlx5_esw_bridge_fdb_entry_refresh: net_device=enp8s0f0_0 addr=e4:fd:05:08:00:02 vid=3 flags=0 used=0 - -- mlx5_esw_bridge_vlan_create: trace bridge VLAN object add on mlx5 - representor:: - - $ echo mlx5:mlx5_esw_bridge_vlan_create >> set_event - $ cat /sys/kernel/debug/tracing/trace - ... - ip-2560 [007] ...1 318.460258: mlx5_esw_bridge_vlan_create: vid=1 flags=6 - -- mlx5_esw_bridge_vlan_cleanup: trace bridge VLAN object delete from mlx5 - representor:: - - $ echo mlx5:mlx5_esw_bridge_vlan_cleanup >> set_event - $ cat /sys/kernel/debug/tracing/trace - ... - bridge-2582 [007] ...1 318.653496: mlx5_esw_bridge_vlan_cleanup: vid=2 flags=8 - -- mlx5_esw_bridge_vport_init: trace mlx5 vport assigned with bridge upper - device:: - - $ echo mlx5:mlx5_esw_bridge_vport_init >> set_event - $ cat /sys/kernel/debug/tracing/trace - ... - ip-2560 [007] ...1 318.458915: mlx5_esw_bridge_vport_init: vport_num=1 - -- mlx5_esw_bridge_vport_cleanup: trace mlx5 vport removed from bridge upper - device:: - - $ echo mlx5:mlx5_esw_bridge_vport_cleanup >> set_event - $ cat /sys/kernel/debug/tracing/trace - ... - ip-5387 [000] ...1 573713: mlx5_esw_bridge_vport_cleanup: vport_num=1 - -Eswitch QoS tracepoints: - -- mlx5_esw_vport_qos_create: trace creation of transmit scheduler arbiter for vport:: - - $ echo mlx5:mlx5_esw_vport_qos_create >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - <...>-23496 [018] .... 73136.838831: mlx5_esw_vport_qos_create: (0000:82:00.0) vport=2 tsar_ix=4 bw_share=0, max_rate=0 group=000000007b576bb3 - -- mlx5_esw_vport_qos_config: trace configuration of transmit scheduler arbiter for vport:: - - $ echo mlx5:mlx5_esw_vport_qos_config >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - <...>-26548 [023] .... 75754.223823: mlx5_esw_vport_qos_config: (0000:82:00.0) vport=1 tsar_ix=3 bw_share=34, max_rate=10000 group=000000007b576bb3 - -- mlx5_esw_vport_qos_destroy: trace deletion of transmit scheduler arbiter for vport:: - - $ echo mlx5:mlx5_esw_vport_qos_destroy >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - <...>-27418 [004] .... 76546.680901: mlx5_esw_vport_qos_destroy: (0000:82:00.0) vport=1 tsar_ix=3 - -- mlx5_esw_group_qos_create: trace creation of transmit scheduler arbiter for rate group:: - - $ echo mlx5:mlx5_esw_group_qos_create >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - <...>-26578 [008] .... 75776.022112: mlx5_esw_group_qos_create: (0000:82:00.0) group=000000008dac63ea tsar_ix=5 - -- mlx5_esw_group_qos_config: trace configuration of transmit scheduler arbiter for rate group:: - - $ echo mlx5:mlx5_esw_group_qos_config >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - <...>-27303 [020] .... 76461.455356: mlx5_esw_group_qos_config: (0000:82:00.0) group=000000008dac63ea tsar_ix=5 bw_share=100 max_rate=20000 - -- mlx5_esw_group_qos_destroy: trace deletion of transmit scheduler arbiter for group:: - - $ echo mlx5:mlx5_esw_group_qos_destroy >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - <...>-27418 [006] .... 76547.187258: mlx5_esw_group_qos_destroy: (0000:82:00.0) group=000000007b576bb3 tsar_ix=1 - -SF tracepoints: - -- mlx5_sf_add: trace addition of the SF port:: - - $ echo mlx5:mlx5_sf_add >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - devlink-9363 [031] ..... 24610.188722: mlx5_sf_add: (0000:06:00.0) port_index=32768 controller=0 hw_id=0x8000 sfnum=88 - -- mlx5_sf_free: trace freeing of the SF port:: - - $ echo mlx5:mlx5_sf_free >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - devlink-9830 [038] ..... 26300.404749: mlx5_sf_free: (0000:06:00.0) port_index=32768 controller=0 hw_id=0x8000 - -- mlx5_sf_hwc_alloc: trace allocating of the hardware SF context:: - - $ echo mlx5:mlx5_sf_hwc_alloc >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - devlink-9775 [031] ..... 26296.385259: mlx5_sf_hwc_alloc: (0000:06:00.0) controller=0 hw_id=0x8000 sfnum=88 - -- mlx5_sf_hwc_free: trace freeing of the hardware SF context:: - - $ echo mlx5:mlx5_sf_hwc_free >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - kworker/u128:3-9093 [046] ..... 24625.365771: mlx5_sf_hwc_free: (0000:06:00.0) hw_id=0x8000 - -- mlx5_sf_hwc_deferred_free : trace deferred freeing of the hardware SF context:: - - $ echo mlx5:mlx5_sf_hwc_deferred_free >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - devlink-9519 [046] ..... 24624.400271: mlx5_sf_hwc_deferred_free: (0000:06:00.0) hw_id=0x8000 - -- mlx5_sf_vhca_event: trace SF vhca event and state:: - - $ echo mlx5:mlx5_sf_vhca_event >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - kworker/u128:3-9093 [046] ..... 24625.365525: mlx5_sf_vhca_event: (0000:06:00.0) hw_id=0x8000 sfnum=88 vhca_state=1 - -- mlx5_sf_dev_add : trace SF device add event:: - - $ echo mlx5:mlx5_sf_dev_add>> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - kworker/u128:3-9093 [000] ..... 24616.524495: mlx5_sf_dev_add: (0000:06:00.0) sfdev=00000000fc5d96fd aux_id=4 hw_id=0x8000 sfnum=88 - -- mlx5_sf_dev_del : trace SF device delete event:: - - $ echo mlx5:mlx5_sf_dev_del >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace - ... - kworker/u128:3-9093 [044] ..... 24624.400749: mlx5_sf_dev_del: (0000:06:00.0) sfdev=00000000fc5d96fd aux_id=4 hw_id=0x8000 sfnum=88 diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/counters.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/counters.rst new file mode 100644 index 000000000000..4cd8e869762b --- /dev/null +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/counters.rst @@ -0,0 +1,1302 @@ +.. SPDX-License-Identifier: GPL-2.0 OR Linux-OpenIB +.. include:: <isonum.txt> + +================ +Ethtool counters +================ + +:Copyright: |copy| 2023, NVIDIA CORPORATION & AFFILIATES. All rights reserved. + +Contents +======== + +- `Overview`_ +- `Groups`_ +- `Types`_ +- `Descriptions`_ + +Overview +======== + +There are several counter groups based on where the counter is being counted. In +addition, each group of counters may have different counter types. + +These counter groups are based on which component in a networking setup, +illustrated below, that they describe:: + + ---------------------------------------- + | | + ---------------------------------------- ---------------------------------------- | + | Hypervisor | | VM | | + | | | | | + | ------------------- --------------- | | ------------------- --------------- | | + | | Ethernet driver | | RDMA driver | | | | Ethernet driver | | RDMA driver | | | + | ------------------- --------------- | | ------------------- --------------- | | + | | | | | | | | | + | ------------------- | | ------------------- | | + | | | | | |-- + ---------------------------------------- ---------------------------------------- + | | + ------------- ----------------------------- + | | + ------ ------ ------ ------ ------ ------ ------ + -----| PF |----------------------| VF |-| VF |-| VF |----- --| PF |--- --| PF |--- --| PF |--- + | ------ ------ ------ ------ | | ------ | | ------ | | ------ | + | | | | | | | | + | | | | | | | | + | | | | | | | | + | eSwitch | | eSwitch | | eSwitch | | eSwitch | + ---------------------------------------------------------- ----------- ----------- ----------- + ------------------------------------------------------------------------------- + | | + | | + | Uplink (no counters) | + ------------------------------------------------------------------------------- + --------------------------------------------------------------- + | | + | | + | MPFS (no counters) | + --------------------------------------------------------------- + | + | + | Port + +Groups +====== + +Ring + Software counters populated by the driver stack. + +Netdev + An aggregation of software ring counters. + +vPort counters + Traffic counters and drops due to steering or no buffers. May indicate issues + with NIC. These counters include Ethernet traffic counters (including Raw + Ethernet) and RDMA/RoCE traffic counters. + +Physical port counters + Counters that collect statistics about the PFs and VFs. May indicate issues + with NIC, link, or network. This measuring point holds information on + standardized counters like IEEE 802.3, RFC2863, RFC 2819, RFC 3635 and + additional counters like flow control, FEC and more. Physical port counters + are not exposed to virtual machines. + +Priority Port Counters + A set of the physical port counters, per priority per port. + +Types +===== + +Counters are divided into three types. + +Traffic Informative Counters + Counters which count traffic. These counters can be used for load estimation + or for general debug. + +Traffic Acceleration Counters + Counters which count traffic that was accelerated by Mellanox driver or by + hardware. The counters are an additional layer to the informative counter set, + and the same traffic is counted in both informative and acceleration counters. + +.. [#accel] Traffic acceleration counter. + +Error Counters + Increment of these counters might indicate a problem. Each of these counters + has an explanation and correction action. + +Statistic can be fetched via the `ip link` or `ethtool` commands. `ethtool` +provides more detailed information.:: + + ip –s link show <if-name> + ethtool -S <if-name> + +Descriptions +============ + +XSK, PTP, and QoS counters that are similar to counters defined previously will +not be separately listed. For example, `ptp_tx[i]_packets` will not be +explicitly documented since `tx[i]_packets` describes the behavior of both +counters, except `ptp_tx[i]_packets` is only counted when precision time +protocol is used. + +Ring / Netdev Counter +---------------------------- +The following counters are available per ring or software port. + +These counters provide information on the amount of traffic that was accelerated +by the NIC. The counters are counting the accelerated traffic in addition to the +standard counters which counts it (i.e. accelerated traffic is counted twice). + +The counter names in the table below refers to both ring and port counters. The +notation for ring counters includes the [i] index without the braces. The +notation for port counters doesn't include the [i]. A counter name +`rx[i]_packets` will be printed as `rx0_packets` for ring 0 and `rx_packets` for +the software port. + +.. flat-table:: Ring / Software Port Counter Table + :widths: 2 3 1 + + * - Counter + - Description + - Type + + * - `rx[i]_packets` + - The number of packets received on ring i. + - Informative + + * - `rx[i]_bytes` + - The number of bytes received on ring i. + - Informative + + * - `tx[i]_packets` + - The number of packets transmitted on ring i. + - Informative + + * - `tx[i]_bytes` + - The number of bytes transmitted on ring i. + - Informative + + * - `tx[i]_recover` + - The number of times the SQ was recovered. + - Error + + * - `tx[i]_cqes` + - Number of CQEs events on SQ issued on ring i. + - Informative + + * - `tx[i]_cqe_err` + - The number of error CQEs encountered on the SQ for ring i. + - Error + + * - `tx[i]_tso_packets` + - The number of TSO packets transmitted on ring i [#accel]_. + - Acceleration + + * - `tx[i]_tso_bytes` + - The number of TSO bytes transmitted on ring i [#accel]_. + - Acceleration + + * - `tx[i]_tso_inner_packets` + - The number of TSO packets which are indicated to be carry internal + encapsulation transmitted on ring i [#accel]_. + - Acceleration + + * - `tx[i]_tso_inner_bytes` + - The number of TSO bytes which are indicated to be carry internal + encapsulation transmitted on ring i [#accel]_. + - Acceleration + + * - `rx[i]_gro_packets` + - Number of received packets processed using hardware-accelerated GRO. The + number of hardware GRO offloaded packets received on ring i. + - Acceleration + + * - `rx[i]_gro_bytes` + - Number of received bytes processed using hardware-accelerated GRO. The + number of hardware GRO offloaded bytes received on ring i. + - Acceleration + + * - `rx[i]_gro_skbs` + - The number of receive SKBs constructed while performing + hardware-accelerated GRO. + - Informative + + * - `rx[i]_gro_match_packets` + - Number of received packets processed using hardware-accelerated GRO that + met the flow table match criteria. + - Informative + + * - `rx[i]_gro_large_hds` + - Number of receive packets using hardware-accelerated GRO that have large + headers that require additional memory to be allocated. + - Informative + + * - `rx[i]_lro_packets` + - The number of LRO packets received on ring i [#accel]_. + - Acceleration + + * - `rx[i]_lro_bytes` + - The number of LRO bytes received on ring i [#accel]_. + - Acceleration + + * - `rx[i]_ecn_mark` + - The number of received packets where the ECN mark was turned on. + - Informative + + * - `rx_oversize_pkts_buffer` + - The number of dropped received packets due to length which arrived to RQ + and exceed software buffer size allocated by the device for incoming + traffic. It might imply that the device MTU is larger than the software + buffers size. + - Error + + * - `rx_oversize_pkts_sw_drop` + - Number of received packets dropped in software because the CQE data is + larger than the MTU size. + - Error + + * - `rx[i]_csum_unnecessary` + - Packets received with a `CHECKSUM_UNNECESSARY` on ring i [#accel]_. + - Acceleration + + * - `rx[i]_csum_unnecessary_inner` + - Packets received with inner encapsulation with a `CHECKSUM_UNNECESSARY` + on ring i [#accel]_. + - Acceleration + + * - `rx[i]_csum_none` + - Packets received with a `CHECKSUM_NONE` on ring i [#accel]_. + - Acceleration + + * - `rx[i]_csum_complete` + - Packets received with a `CHECKSUM_COMPLETE` on ring i [#accel]_. + - Acceleration + + * - `rx[i]_csum_complete_tail` + - Number of received packets that had checksum calculation computed, + potentially needed padding, and were able to do so with + `CHECKSUM_PARTIAL`. + - Informative + + * - `rx[i]_csum_complete_tail_slow` + - Number of received packets that need padding larger than eight bytes for + the checksum. + - Informative + + * - `tx[i]_csum_partial` + - Packets transmitted with a `CHECKSUM_PARTIAL` on ring i [#accel]_. + - Acceleration + + * - `tx[i]_csum_partial_inner` + - Packets transmitted with inner encapsulation with a `CHECKSUM_PARTIAL` on + ring i [#accel]_. + - Acceleration + + * - `tx[i]_csum_none` + - Packets transmitted with no hardware checksum acceleration on ring i. + - Informative + + * - `tx[i]_stopped` / `tx_queue_stopped` [#ring_global]_ + - Events where SQ was full on ring i. If this counter is increased, check + the amount of buffers allocated for transmission. + - Informative + + * - `tx[i]_wake` / `tx_queue_wake` [#ring_global]_ + - Events where SQ was full and has become not full on ring i. + - Informative + + * - `tx[i]_dropped` / `tx_queue_dropped` [#ring_global]_ + - Packets transmitted that were dropped due to DMA mapping failure on + ring i. If this counter is increased, check the amount of buffers + allocated for transmission. + - Error + + * - `tx[i]_nop` + - The number of nop WQEs (empty WQEs) inserted to the SQ (related to + ring i) due to the reach of the end of the cyclic buffer. When reaching + near to the end of cyclic buffer the driver may add those empty WQEs to + avoid handling a state the a WQE start in the end of the queue and ends + in the beginning of the queue. This is a normal condition. + - Informative + + * - `tx[i]_added_vlan_packets` + - The number of packets sent where vlan tag insertion was offloaded to the + hardware. + - Acceleration + + * - `rx[i]_removed_vlan_packets` + - The number of packets received where vlan tag stripping was offloaded to + the hardware. + - Acceleration + + * - `rx[i]_wqe_err` + - The number of wrong opcodes received on ring i. + - Error + + * - `rx[i]_mpwqe_frag` + - The number of WQEs that failed to allocate compound page and hence + fragmented MPWQE’s (Multi Packet WQEs) were used on ring i. If this + counter raise, it may suggest that there is no enough memory for large + pages, the driver allocated fragmented pages. This is not abnormal + condition. + - Informative + + * - `rx[i]_mpwqe_filler_cqes` + - The number of filler CQEs events that were issued on ring i. + - Informative + + * - `rx[i]_mpwqe_filler_strides` + - The number of strides consumed by filler CQEs on ring i. + - Informative + + * - `tx[i]_mpwqe_blks` + - The number of send blocks processed from Multi-Packet WQEs (mpwqe). + - Informative + + * - `tx[i]_mpwqe_pkts` + - The number of send packets processed from Multi-Packet WQEs (mpwqe). + - Informative + + * - `rx[i]_cqe_compress_blks` + - The number of receive blocks with CQE compression on ring i [#accel]_. + - Acceleration + + * - `rx[i]_cqe_compress_pkts` + - The number of receive packets with CQE compression on ring i [#accel]_. + - Acceleration + + * - `rx[i]_cache_reuse` + - The number of events of successful reuse of a page from a driver's + internal page cache. + - Acceleration + + * - `rx[i]_cache_full` + - The number of events of full internal page cache where driver can't put a + page back to the cache for recycling (page will be freed). + - Acceleration + + * - `rx[i]_cache_empty` + - The number of events where cache was empty - no page to give. Driver + shall allocate new page. + - Acceleration + + * - `rx[i]_cache_busy` + - The number of events where cache head was busy and cannot be recycled. + Driver allocated new page. + - Acceleration + + * - `rx[i]_cache_waive` + - The number of cache evacuation. This can occur due to page move to + another NUMA node or page was pfmemalloc-ed and should be freed as soon + as possible. + - Acceleration + + * - `rx[i]_arfs_err` + - Number of flow rules that failed to be added to the flow table. + - Error + + * - `rx[i]_recover` + - The number of times the RQ was recovered. + - Error + + * - `tx[i]_xmit_more` + - The number of packets sent with `xmit_more` indication set on the skbuff + (no doorbell). + - Acceleration + + * - `ch[i]_poll` + - The number of invocations of NAPI poll of channel i. + - Informative + + * - `ch[i]_arm` + - The number of times the NAPI poll function completed and armed the + completion queues on channel i. + - Informative + + * - `ch[i]_aff_change` + - The number of times the NAPI poll function explicitly stopped execution + on a CPU due to a change in affinity, on channel i. + - Informative + + * - `ch[i]_events` + - The number of hard interrupt events on the completion queues of channel i. + - Informative + + * - `ch[i]_eq_rearm` + - The number of times the EQ was recovered. + - Error + + * - `ch[i]_force_irq` + - Number of times NAPI is triggered by XSK wakeups by posting a NOP to + ICOSQ. + - Acceleration + + * - `rx[i]_congst_umr` + - The number of times an outstanding UMR request is delayed due to + congestion, on ring i. + - Informative + + * - `rx_pp_alloc_fast` + - Number of successful fast path allocations. + - Informative + + * - `rx_pp_alloc_slow` + - Number of slow path order-0 allocations. + - Informative + + * - `rx_pp_alloc_slow_high_order` + - Number of slow path high order allocations. + - Informative + + * - `rx_pp_alloc_empty` + - Counter is incremented when ptr ring is empty, so a slow path allocation + was forced. + - Informative + + * - `rx_pp_alloc_refill` + - Counter is incremented when an allocation which triggered a refill of the + cache. + - Informative + + * - `rx_pp_alloc_waive` + - Counter is incremented when pages obtained from the ptr ring that cannot + be added to the cache due to a NUMA mismatch. + - Informative + + * - `rx_pp_recycle_cached` + - Counter is incremented when recycling placed page in the page pool cache. + - Informative + + * - `rx_pp_recycle_cache_full` + - Counter is incremented when page pool cache was full. + - Informative + + * - `rx_pp_recycle_ring` + - Counter is incremented when page placed into the ptr ring. + - Informative + + * - `rx_pp_recycle_ring_full` + - Counter is incremented when page released from page pool because the ptr + ring was full. + - Informative + + * - `rx_pp_recycle_released_ref` + - Counter is incremented when page released (and not recycled) because + refcnt > 1. + - Informative + + * - `rx[i]_xsk_buff_alloc_err` + - The number of times allocating an skb or XSK buffer failed in the XSK RQ + 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 + software counters. These packets are counted by physical port and vPort + counters. + - Informative + + * - `rx[i]_xdp_tx_mpwqe` + - Number of multi-packet WQEs transmitted by the netdev and `XDP_TX`-ed by + the netdev during the RQ context. + - Acceleration + + * - `rx[i]_xdp_tx_inlnw` + - Number of WQE data segments transmitted where the data could be inlined + in the WQE and then `XDP_TX`-ed during the RQ context. + - Acceleration + + * - `rx[i]_xdp_tx_nops` + - Number of NOP WQEBBs (WQE building blocks) received posted to the XDP SQ. + - Acceleration + + * - `rx[i]_xdp_tx_full` + - The number of packets that should have been forwarded back to the port + due to `XDP_TX` action but were dropped due to full tx queue. These packets + are not counted by other software counters. These packets are counted by + physical port and vPort counters. You may open more rx queues and spread + traffic rx over all queues and/or increase rx ring size. + - Error + + * - `rx[i]_xdp_tx_err` + - The number of times an `XDP_TX` error such as frame too long and frame + too short occurred on `XDP_TX` ring of RX ring. + - Error + + * - `rx[i]_xdp_tx_cqes` / `rx_xdp_tx_cqe` [#ring_global]_ + - The number of completions received on the CQ of the `XDP_TX` ring. + - Informative + + * - `rx[i]_xdp_drop` + - The number of packets dropped due to XDP program `XDP_DROP` action. these + packets are not counted by other software counters. These packets are + counted by physical port and vPort counters. + - Informative + + * - `rx[i]_xdp_redirect` + - The number of times an XDP redirect action was triggered on ring i. + - Acceleration + + * - `tx[i]_xdp_xmit` + - The number of packets redirected to the interface(due to XDP redirect). + These packets are not counted by other software counters. These packets + are counted by physical port and vPort counters. + - Informative + + * - `tx[i]_xdp_full` + - The number of packets redirected to the interface(due to XDP redirect), + but were dropped due to full tx queue. these packets are not counted by + other software counters. you may enlarge tx queues. + - Informative + + * - `tx[i]_xdp_mpwqe` + - Number of multi-packet WQEs offloaded onto the NIC that were + `XDP_REDIRECT`-ed from other netdevs. + - Acceleration + + * - `tx[i]_xdp_inlnw` + - Number of WQE data segments where the data could be inlined in the WQE + where the data segments were `XDP_REDIRECT`-ed from other netdevs. + - Acceleration + + * - `tx[i]_xdp_nops` + - Number of NOP WQEBBs (WQE building blocks) posted to the SQ that were + `XDP_REDIRECT`-ed from other netdevs. + - Acceleration + + * - `tx[i]_xdp_err` + - The number of packets redirected to the interface(due to XDP redirect) + but were dropped due to error such as frame too long and frame too short. + - Error + + * - `tx[i]_xdp_cqes` + - The number of completions received for packets redirected to the + interface(due to XDP redirect) on the CQ. + - Informative + + * - `tx[i]_xsk_xmit` + - The number of packets transmitted using XSK zerocopy functionality. + - Acceleration + + * - `tx[i]_xsk_mpwqe` + - Number of multi-packet WQEs offloaded onto the NIC that were + `XDP_REDIRECT`-ed from other netdevs. + - Acceleration + + * - `tx[i]_xsk_inlnw` + - Number of WQE data segments where the data could be inlined in the WQE + that are transmitted using XSK zerocopy. + - Acceleration + + * - `tx[i]_xsk_full` + - Number of times doorbell is rung in XSK zerocopy mode when SQ is full. + - Error + + * - `tx[i]_xsk_err` + - Number of errors that occurred in XSK zerocopy mode such as if the data + size is larger than the MTU size. + - Error + + * - `tx[i]_xsk_cqes` + - Number of CQEs processed in XSK zerocopy mode. + - Acceleration + + * - `tx_tls_ctx` + - Number of TLS TX HW offload contexts added to device for encryption. + - Acceleration + + * - `tx_tls_del` + - Number of TLS TX HW offload contexts removed from device (connection + closed). + - Acceleration + + * - `tx_tls_pool_alloc` + - Number of times a unit of work is successfully allocated in the TLS HW + offload pool. + - Acceleration + + * - `tx_tls_pool_free` + - Number of times a unit of work is freed in the TLS HW offload pool. + - Acceleration + + * - `rx_tls_ctx` + - Number of TLS RX HW offload contexts added to device for decryption. + - Acceleration + + * - `rx_tls_del` + - Number of TLS RX HW offload contexts deleted from device (connection has + finished). + - Acceleration + + * - `rx[i]_tls_decrypted_packets` + - Number of successfully decrypted RX packets which were part of a TLS + stream. + - Acceleration + + * - `rx[i]_tls_decrypted_bytes` + - Number of TLS payload bytes in RX packets which were successfully + decrypted. + - Acceleration + + * - `rx[i]_tls_resync_req_pkt` + - Number of received TLS packets with a resync request. + - Acceleration + + * - `rx[i]_tls_resync_req_start` + - Number of times the TLS async resync request was started. + - Acceleration + + * - `rx[i]_tls_resync_req_end` + - Number of times the TLS async resync request properly ended with + providing the HW tracked tcp-seq. + - Acceleration + + * - `rx[i]_tls_resync_req_skip` + - Number of times the TLS async resync request procedure was started but + not properly ended. + - Error + + * - `rx[i]_tls_resync_res_ok` + - Number of times the TLS resync response call to the driver was + successfully handled. + - Acceleration + + * - `rx[i]_tls_resync_res_retry` + - Number of times the TLS resync response call to the driver was + reattempted when ICOSQ is full. + - Error + + * - `rx[i]_tls_resync_res_skip` + - Number of times the TLS resync response call to the driver was terminated + unsuccessfully. + - Error + + * - `rx[i]_tls_err` + - Number of times when CQE TLS offload was problematic. + - Error + + * - `tx[i]_tls_encrypted_packets` + - The number of send packets that are TLS encrypted by the kernel. + - Acceleration + + * - `tx[i]_tls_encrypted_bytes` + - The number of send bytes that are TLS encrypted by the kernel. + - Acceleration + + * - `tx[i]_tls_ooo` + - Number of times out of order TLS SQE fragments were handled on ring i. + - Acceleration + + * - `tx[i]_tls_dump_packets` + - Number of TLS decrypted packets copied over from NIC over DMA. + - Acceleration + + * - `tx[i]_tls_dump_bytes` + - Number of TLS decrypted bytes copied over from NIC over DMA. + - Acceleration + + * - `tx[i]_tls_resync_bytes` + - Number of TLS bytes requested to be resynchronized in order to be + decrypted. + - Acceleration + + * - `tx[i]_tls_skip_no_sync_data` + - Number of TLS send data that can safely be skipped / do not need to be + decrypted. + - Acceleration + + * - `tx[i]_tls_drop_no_sync_data` + - Number of TLS send data that were dropped due to retransmission of TLS + data. + - Acceleration + + * - `ptp_cq[i]_abort` + - Number of times a CQE has to be skipped in precision time protocol due to + a skew between the port timestamp and CQE timestamp being greater than + 128 seconds. + - Error + + * - `ptp_cq[i]_abort_abs_diff_ns` + - Accumulation of time differences between the port timestamp and CQE + timestamp when the difference is greater than 128 seconds in precision + time protocol. + - Error + +.. [#ring_global] The corresponding ring and global counters do not share the + same name (i.e. do not follow the common naming scheme). + +vPort Counters +-------------- +Counters on the NIC port that is connected to a eSwitch. + +.. flat-table:: vPort Counter Table + :widths: 2 3 1 + + * - Counter + - Description + - Type + + * - `rx_vport_unicast_packets` + - Unicast packets received, steered to a port including Raw Ethernet + QP/DPDK traffic, excluding RDMA traffic. + - Informative + + * - `rx_vport_unicast_bytes` + - Unicast bytes received, steered to a port including Raw Ethernet QP/DPDK + traffic, excluding RDMA traffic. + - Informative + + * - `tx_vport_unicast_packets` + - Unicast packets transmitted, steered from a port including Raw Ethernet + QP/DPDK traffic, excluding RDMA traffic. + - Informative + + * - `tx_vport_unicast_bytes` + - Unicast bytes transmitted, steered from a port including Raw Ethernet + QP/DPDK traffic, excluding RDMA traffic. + - Informative + + * - `rx_vport_multicast_packets` + - Multicast packets received, steered to a port including Raw Ethernet + QP/DPDK traffic, excluding RDMA traffic. + - Informative + + * - `rx_vport_multicast_bytes` + - Multicast bytes received, steered to a port including Raw Ethernet + QP/DPDK traffic, excluding RDMA traffic. + - Informative + + * - `tx_vport_multicast_packets` + - Multicast packets transmitted, steered from a port including Raw Ethernet + QP/DPDK traffic, excluding RDMA traffic. + - Informative + + * - `tx_vport_multicast_bytes` + - Multicast bytes transmitted, steered from a port including Raw Ethernet + QP/DPDK traffic, excluding RDMA traffic. + - Informative + + * - `rx_vport_broadcast_packets` + - Broadcast packets received, steered to a port including Raw Ethernet + QP/DPDK traffic, excluding RDMA traffic. + - Informative + + * - `rx_vport_broadcast_bytes` + - Broadcast bytes received, steered to a port including Raw Ethernet + QP/DPDK traffic, excluding RDMA traffic. + - Informative + + * - `tx_vport_broadcast_packets` + - Broadcast packets transmitted, steered from a port including Raw Ethernet + QP/DPDK traffic, excluding RDMA traffic. + - Informative + + * - `tx_vport_broadcast_bytes` + - Broadcast bytes transmitted, steered from a port including Raw Ethernet + QP/DPDK traffic, excluding RDMA traffic. + - Informative + + * - `rx_vport_rdma_unicast_packets` + - RDMA unicast packets received, steered to a port (counters counts + RoCE/UD/RC traffic) [#accel]_. + - Acceleration + + * - `rx_vport_rdma_unicast_bytes` + - RDMA unicast bytes received, steered to a port (counters counts + RoCE/UD/RC traffic) [#accel]_. + - Acceleration + + * - `tx_vport_rdma_unicast_packets` + - RDMA unicast packets transmitted, steered from a port (counters counts + RoCE/UD/RC traffic) [#accel]_. + - Acceleration + + * - `tx_vport_rdma_unicast_bytes` + - RDMA unicast bytes transmitted, steered from a port (counters counts + RoCE/UD/RC traffic) [#accel]_. + - Acceleration + + * - `rx_vport_rdma_multicast_packets` + - RDMA multicast packets received, steered to a port (counters counts + RoCE/UD/RC traffic) [#accel]_. + - Acceleration + + * - `rx_vport_rdma_multicast_bytes` + - RDMA multicast bytes received, steered to a port (counters counts + RoCE/UD/RC traffic) [#accel]_. + - Acceleration + + * - `tx_vport_rdma_multicast_packets` + - RDMA multicast packets transmitted, steered from a port (counters counts + RoCE/UD/RC traffic) [#accel]_. + - Acceleration + + * - `tx_vport_rdma_multicast_bytes` + - RDMA multicast bytes transmitted, steered from a port (counters counts + RoCE/UD/RC traffic) [#accel]_. + - Acceleration + + * - `rx_steer_missed_packets` + - Number of packets that was received by the NIC, however was discarded + because it did not match any flow in the NIC flow table. + - Error + + * - `rx_packets` + - Representor only: packets received, that were handled by the hypervisor. + - Informative + + * - `rx_bytes` + - Representor only: bytes received, that were handled by the hypervisor. + - Informative + + * - `tx_packets` + - Representor only: packets transmitted, that were handled by the + hypervisor. + - Informative + + * - `tx_bytes` + - Representor only: bytes transmitted, that were handled by the hypervisor. + - Informative + + * - `dev_internal_queue_oob` + - The number of dropped packets due to lack of receive WQEs for an internal + device RQ. + - Error + +Physical Port Counters +---------------------- +The physical port counters are the counters on the external port connecting the +adapter to the network. This measuring point holds information on standardized +counters like IEEE 802.3, RFC2863, RFC 2819, RFC 3635 and additional counters +like flow control, FEC and more. + +.. flat-table:: Physical Port Counter Table + :widths: 2 3 1 + + * - Counter + - Description + - Type + + * - `rx_packets_phy` + - The number of packets received on the physical port. This counter doesn’t + include packets that were discarded due to FCS, frame size and similar + errors. + - Informative + + * - `tx_packets_phy` + - The number of packets transmitted on the physical port. + - Informative + + * - `rx_bytes_phy` + - The number of bytes received on the physical port, including Ethernet + header and FCS. + - Informative + + * - `tx_bytes_phy` + - The number of bytes transmitted on the physical port. + - Informative + + * - `rx_multicast_phy` + - The number of multicast packets received on the physical port. + - Informative + + * - `tx_multicast_phy` + - The number of multicast packets transmitted on the physical port. + - Informative + + * - `rx_broadcast_phy` + - The number of broadcast packets received on the physical port. + - Informative + + * - `tx_broadcast_phy` + - The number of broadcast packets transmitted on the physical port. + - Informative + + * - `rx_crc_errors_phy` + - The number of dropped received packets due to FCS (Frame Check Sequence) + error on the physical port. If this counter is increased in high rate, + check the link quality using `rx_symbol_error_phy` and + `rx_corrected_bits_phy` counters below. + - Error + + * - `rx_in_range_len_errors_phy` + - The number of received packets dropped due to length/type errors on a + physical port. + - Error + + * - `rx_out_of_range_len_phy` + - The number of received packets dropped due to length greater than allowed + on a physical port. If this counter is increasing, it implies that the + peer connected to the adapter has a larger MTU configured. Using same MTU + configuration shall resolve this issue. + - Error + + * - `rx_oversize_pkts_phy` + - The number of dropped received packets due to length which exceed MTU + size on a physical port. If this counter is increasing, it implies that + the peer connected to the adapter has a larger MTU configured. Using same + MTU configuration shall resolve this issue. + - Error + + * - `rx_symbol_err_phy` + - The number of received packets dropped due to physical coding errors + (symbol errors) on a physical port. + - Error + + * - `rx_mac_control_phy` + - The number of MAC control packets received on the physical port. + - Informative + + * - `tx_mac_control_phy` + - The number of MAC control packets transmitted on the physical port. + - Informative + + * - `rx_pause_ctrl_phy` + - The number of link layer pause packets received on a physical port. If + this counter is increasing, it implies that the network is congested and + cannot absorb the traffic coming from to the adapter. + - Informative + + * - `tx_pause_ctrl_phy` + - The number of link layer pause packets transmitted on a physical port. If + this counter is increasing, it implies that the NIC is congested and + cannot absorb the traffic coming from the network. + - Informative + + * - `rx_unsupported_op_phy` + - The number of MAC control packets received with unsupported opcode on a + physical port. + - Error + + * - `rx_discards_phy` + - The number of received packets dropped due to lack of buffers on a + physical port. If this counter is increasing, it implies that the adapter + is congested and cannot absorb the traffic coming from the network. + - Error + + * - `tx_discards_phy` + - The number of packets which were discarded on transmission, even no + errors were detected. the drop might occur due to link in down state, + head of line drop, pause from the network, etc. + - Error + + * - `tx_errors_phy` + - The number of transmitted packets dropped due to a length which exceed + MTU size on a physical port. + - Error + + * - `rx_undersize_pkts_phy` + - The number of received packets dropped due to length which is shorter + than 64 bytes on a physical port. If this counter is increasing, it + implies that the peer connected to the adapter has a non-standard MTU + configured or malformed packet had arrived. + - Error + + * - `rx_fragments_phy` + - The number of received packets dropped due to a length which is shorter + than 64 bytes and has FCS error on a physical port. If this counter is + increasing, it implies that the peer connected to the adapter has a + non-standard MTU configured. + - Error + + * - `rx_jabbers_phy` + - The number of received packets d due to a length which is longer than 64 + bytes and had FCS error on a physical port. + - Error + + * - `rx_64_bytes_phy` + - The number of packets received on the physical port with size of 64 bytes. + - Informative + + * - `rx_65_to_127_bytes_phy` + - The number of packets received on the physical port with size of 65 to + 127 bytes. + - Informative + + * - `rx_128_to_255_bytes_phy` + - The number of packets received on the physical port with size of 128 to + 255 bytes. + - Informative + + * - `rx_256_to_511_bytes_phy` + - The number of packets received on the physical port with size of 256 to + 512 bytes. + - Informative + + * - `rx_512_to_1023_bytes_phy` + - The number of packets received on the physical port with size of 512 to + 1023 bytes. + - Informative + + * - `rx_1024_to_1518_bytes_phy` + - The number of packets received on the physical port with size of 1024 to + 1518 bytes. + - Informative + + * - `rx_1519_to_2047_bytes_phy` + - The number of packets received on the physical port with size of 1519 to + 2047 bytes. + - Informative + + * - `rx_2048_to_4095_bytes_phy` + - The number of packets received on the physical port with size of 2048 to + 4095 bytes. + - Informative + + * - `rx_4096_to_8191_bytes_phy` + - The number of packets received on the physical port with size of 4096 to + 8191 bytes. + - Informative + + * - `rx_8192_to_10239_bytes_phy` + - The number of packets received on the physical port with size of 8192 to + 10239 bytes. + - Informative + + * - `link_down_events_phy` + - The number of times where the link operative state changed to down. In + case this counter is increasing it may imply on port flapping. You may + need to replace the cable/transceiver. + - Error + + * - `rx_out_of_buffer` + - Number of times receive queue had no software buffers allocated for the + adapter's incoming traffic. + - Error + + * - `module_bus_stuck` + - The number of times that module's I\ :sup:`2`\C bus (data or clock) + short-wire was detected. You may need to replace the cable/transceiver. + - Error + + * - `module_high_temp` + - The number of times that the module temperature was too high. If this + issue persist, you may need to check the ambient temperature or replace + the cable/transceiver module. + - Error + + * - `module_bad_shorted` + - The number of times that the module cables were shorted. You may need to + replace the cable/transceiver module. + - Error + + * - `module_unplug` + - The number of times that module was ejected. + - Informative + + * - `rx_buffer_passed_thres_phy` + - The number of events where the port receive buffer was over 85% full. + - Informative + + * - `tx_pause_storm_warning_events` + - The number of times the device was sending pauses for a long period of + time. + - Informative + + * - `tx_pause_storm_error_events` + - The number of times the device was sending pauses for a long period of + time, reaching time out and disabling transmission of pause frames. on + the period where pause frames were disabled, drop could have been + occurred. + - Error + + * - `rx[i]_buff_alloc_err` + - Failed to allocate a buffer to received packet (or SKB) on ring i. + - Error + + * - `rx_bits_phy` + - This counter provides information on the total amount of traffic that + could have been received and can be used as a guideline to measure the + ratio of errored traffic in `rx_pcs_symbol_err_phy` and + `rx_corrected_bits_phy`. + - Informative + + * - `rx_pcs_symbol_err_phy` + - This counter counts the number of symbol errors that wasn’t corrected by + FEC correction algorithm or that FEC algorithm was not active on this + interface. If this counter is increasing, it implies that the link + between the NIC and the network is suffering from high BER, and that + traffic is lost. You may need to replace the cable/transceiver. The error + rate is the number of `rx_pcs_symbol_err_phy` divided by the number of + `rx_bits_phy` on a specific time frame. + - Error + + * - `rx_corrected_bits_phy` + - The number of corrected bits on this port according to active FEC + (RS/FC). If this counter is increasing, it implies that the link between + the NIC and the network is suffering from high BER. The corrected bit + rate is the number of `rx_corrected_bits_phy` divided by the number of + `rx_bits_phy` on a specific time frame. + - Error + + * - `rx_err_lane_[l]_phy` + - This counter counts the number of physical raw errors per lane l index. + The counter counts errors before FEC corrections. If this counter is + increasing, it implies that the link between the NIC and the network is + suffering from high BER, and that traffic might be lost. You may need to + replace the cable/transceiver. Please check in accordance with + `rx_corrected_bits_phy`. + - Error + + * - `rx_global_pause` + - The number of pause packets received on the physical port. If this + counter is increasing, it implies that the network is congested and + cannot absorb the traffic coming from the adapter. Note: This counter is + only enabled when global pause mode is enabled. + - Informative + + * - `rx_global_pause_duration` + - The duration of pause received (in microSec) on the physical port. The + counter represents the time the port did not send any traffic. If this + counter is increasing, it implies that the network is congested and + cannot absorb the traffic coming from the adapter. Note: This counter is + only enabled when global pause mode is enabled. + - Informative + + * - `tx_global_pause` + - The number of pause packets transmitted on a physical port. If this + counter is increasing, it implies that the adapter is congested and + cannot absorb the traffic coming from the network. Note: This counter is + only enabled when global pause mode is enabled. + - Informative + + * - `tx_global_pause_duration` + - The duration of pause transmitter (in microSec) on the physical port. + Note: This counter is only enabled when global pause mode is enabled. + - Informative + + * - `rx_global_pause_transition` + - The number of times a transition from Xoff to Xon on the physical port + has occurred. Note: This counter is only enabled when global pause mode + is enabled. + - Informative + + * - `rx_if_down_packets` + - The number of received packets that were dropped due to interface down. + - Informative + +Priority Port Counters +---------------------- +The following counters are physical port counters that are counted per L2 +priority (0-7). + +**Note:** `p` in the counter name represents the priority. + +.. flat-table:: Priority Port Counter Table + :widths: 2 3 1 + + * - Counter + - Description + - Type + + * - `rx_prio[p]_bytes` + - The number of bytes received with priority p on the physical port. + - Informative + + * - `rx_prio[p]_packets` + - The number of packets received with priority p on the physical port. + - Informative + + * - `tx_prio[p]_bytes` + - The number of bytes transmitted on priority p on the physical port. + - Informative + + * - `tx_prio[p]_packets` + - The number of packets transmitted on priority p on the physical port. + - Informative + + * - `rx_prio[p]_pause` + - The number of pause packets received with priority p on a physical port. + If this counter is increasing, it implies that the network is congested + and cannot absorb the traffic coming from the adapter. Note: This counter + is available only if PFC was enabled on priority p. + - Informative + + * - `rx_prio[p]_pause_duration` + - The duration of pause received (in microSec) on priority p on the + physical port. The counter represents the time the port did not send any + traffic on this priority. If this counter is increasing, it implies that + the network is congested and cannot absorb the traffic coming from the + adapter. Note: This counter is available only if PFC was enabled on + priority p. + - Informative + + * - `rx_prio[p]_pause_transition` + - The number of times a transition from Xoff to Xon on priority p on the + physical port has occurred. Note: This counter is available only if PFC + was enabled on priority p. + - Informative + + * - `tx_prio[p]_pause` + - The number of pause packets transmitted on priority p on a physical port. + If this counter is increasing, it implies that the adapter is congested + and cannot absorb the traffic coming from the network. Note: This counter + is available only if PFC was enabled on priority p. + - Informative + + * - `tx_prio[p]_pause_duration` + - The duration of pause transmitter (in microSec) on priority p on the + physical port. Note: This counter is available only if PFC was enabled on + priority p. + - Informative + + * - `rx_prio[p]_buf_discard` + - The number of packets discarded by device due to lack of per host receive + buffers. + - Informative + + * - `rx_prio[p]_cong_discard` + - The number of packets discarded by device due to per host congestion. + - Informative + + * - `rx_prio[p]_marked` + - The number of packets ecn marked by device due to per host congestion. + - Informative + + * - `rx_prio[p]_discards` + - The number of packets discarded by device due to lack of receive buffers. + - Informative + +Device Counters +--------------- +.. flat-table:: Device Counter Table + :widths: 2 3 1 + + * - Counter + - Description + - Type + + * - `rx_pci_signal_integrity` + - Counts physical layer PCIe signal integrity errors, the number of + transitions to recovery due to Framing errors and CRC (dlp and tlp). If + this counter is raising, try moving the adapter card to a different slot + to rule out a bad PCI slot. Validate that you are running with the latest + firmware available and latest server BIOS version. + - Error + + * - `tx_pci_signal_integrity` + - Counts physical layer PCIe signal integrity errors, the number of + transition to recovery initiated by the other side (moving to recovery + due to getting TS/EIEOS). If this counter is raising, try moving the + adapter card to a different slot to rule out a bad PCI slot. Validate + that you are running with the latest firmware available and latest server + BIOS version. + - Error + + * - `outbound_pci_buffer_overflow` + - The number of packets dropped due to pci buffer overflow. If this counter + is raising in high rate, it might indicate that the receive traffic rate + for a host is larger than the PCIe bus and therefore a congestion occurs. + - Informative + + * - `outbound_pci_stalled_rd` + - The percentage (in the range 0...100) of time within the last second that + the NIC had outbound non-posted reads requests but could not perform the + operation due to insufficient posted credits. + - Informative + + * - `outbound_pci_stalled_wr` + - The percentage (in the range 0...100) of time within the last second that + the NIC had outbound posted writes requests but could not perform the + operation due to insufficient posted credits. + - Informative + + * - `outbound_pci_stalled_rd_events` + - The number of seconds where `outbound_pci_stalled_rd` was above 30%. + - Informative + + * - `outbound_pci_stalled_wr_events` + - The number of seconds where `outbound_pci_stalled_wr` was above 30%. + - Informative + + * - `dev_out_of_buffer` + - The number of times the device owned queue had not enough buffers + allocated. + - Error diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst new file mode 100644 index 000000000000..9b5c40ba7f0d --- /dev/null +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst @@ -0,0 +1,224 @@ +.. 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 + +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. diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/index.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/index.rst new file mode 100644 index 000000000000..3fdcd6b61ccf --- /dev/null +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/index.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0 OR Linux-OpenIB +.. include:: <isonum.txt> + +Mellanox ConnectX(R) mlx5 core VPI Network Driver +================================================= + +:Copyright: |copy| 2019, Mellanox Technologies LTD. +:Copyright: |copy| 2020-2023, NVIDIA CORPORATION & AFFILIATES. All rights reserved. + +Contents: + +.. toctree:: + :maxdepth: 2 + + kconfig + devlink + switchdev + tracepoints + counters + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/kconfig.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/kconfig.rst new file mode 100644 index 000000000000..43b1f7e87ec4 --- /dev/null +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/kconfig.rst @@ -0,0 +1,168 @@ +.. SPDX-License-Identifier: GPL-2.0 OR Linux-OpenIB +.. include:: <isonum.txt> + +======================================= +Enabling the driver and kconfig options +======================================= + +:Copyright: |copy| 2023, NVIDIA CORPORATION & AFFILIATES. All rights reserved. + +| mlx5 core is modular and most of the major mlx5 core driver features can be selected (compiled in/out) +| at build time via kernel Kconfig flags. +| Basic features, ethernet net device rx/tx offloads and XDP, are available with the most basic flags +| CONFIG_MLX5_CORE=y/m and CONFIG_MLX5_CORE_EN=y. +| For the list of advanced features, please see below. + +**CONFIG_MLX5_BRIDGE=(y/n)** + +| Enable :ref:`Ethernet Bridging (BRIDGE) offloading support <mlx5_bridge_offload>`. +| This will provide the ability to add representors of mlx5 uplink and VF +| ports to Bridge and offloading rules for traffic between such ports. +| Supports VLANs (trunk and access modes). + + +**CONFIG_MLX5_CORE=(y/m/n)** (module mlx5_core.ko) + +| The driver can be enabled by choosing CONFIG_MLX5_CORE=y/m in kernel config. +| This will provide mlx5 core driver for mlx5 ulps to interface with (mlx5e, mlx5_ib). + + +**CONFIG_MLX5_CORE_EN=(y/n)** + +| Choosing this option will allow basic ethernet netdevice support with all of the standard rx/tx offloads. +| mlx5e is the mlx5 ulp driver which provides netdevice kernel interface, when chosen, mlx5e will be +| built-in into mlx5_core.ko. + + +**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>`_. + + +**CONFIG_MLX5_CORE_IPOIB=(y/n)** + +| IPoIB offloads & acceleration support. +| Requires CONFIG_MLX5_CORE_EN to provide an accelerated interface for the rdma +| IPoIB ulp netdevice. + + +**CONFIG_MLX5_CLS_ACT=(y/n)** + +| Enables offload support for TC classifier action (NET_CLS_ACT). +| Works in both native NIC mode and Switchdev SRIOV mode. +| Flow-based classifiers, such as those registered through +| `tc-flower(8)`, are processed by the device, rather than the +| host. Actions that would then overwrite matching classification +| results would then be instant due to the offload. + + +**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 + + +**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>`_. + + +**CONFIG_MLX5_EN_MACSEC=(y/n)** + +| Build support for MACsec cryptography-offload acceleration in the NIC. + + +**CONFIG_MLX5_EN_RXNFC=(y/n)** + +| Enables ethtool receive network flow classification, which allows user defined +| flow rules to direct traffic into arbitrary rx queue via ethtool set/get_rxnfc API. + + +**CONFIG_MLX5_EN_TLS=(y/n)** + +| TLS cryptography-offload acceleration. + + +**CONFIG_MLX5_ESWITCH=(y/n)** + +| 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>`_. + + +**CONFIG_MLX5_FPGA=(y/n)** + +| Build support for the Innova family of network cards by Mellanox Technologies. +| Innova network cards are comprised of a ConnectX chip and an FPGA chip on one board. +| If you select this option, the mlx5_core driver will include the Innova FPGA core and allow +| building sandbox-specific client drivers. + + +**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. + + +**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 +| user configured unicast MAC addresses to the requesting PF. + + +**CONFIG_MLX5_SF=(y/n)** + +| Build support for subfunction. +| Subfunctons are more light weight than PCI SRIOV VFs. Choosing this option +| will enable support for creating subfunction devices. + + +**CONFIG_MLX5_SF_MANAGER=(y/n)** + +| Build support for subfuction port in the NIC. A Mellanox subfunction +| port is managed through devlink. A subfunction supports RDMA, netdevice +| and vdpa device. It is similar to a SRIOV VF but it doesn't require +| SRIOV support. + + +**CONFIG_MLX5_SW_STEERING=(y/n)** + +| Build support for software-managed steering in the NIC. + + +**CONFIG_MLX5_TC_CT=(y/n)** + +| Support offloading connection tracking rules via tc ct action. + + +**CONFIG_MLX5_TC_SAMPLE=(y/n)** + +| Support offloading sample rules via tc sample action. + + +**CONFIG_MLX5_VDPA=(y/n)** + +| Support library for Mellanox VDPA drivers. Provides code that is +| common for all types of VDPA drivers. The following drivers are planned: +| net, block. + + +**CONFIG_MLX5_VDPA_NET=(y/n)** + +| VDPA network driver for ConnectX6 and newer. Provides offloading +| of virtio net datapath such that descriptors put on the ring will +| be executed by the hardware. It also supports a variety of stateless +| offloads depending on the actual device used and firmware version. + + +**CONFIG_MLX5_VFIO_PCI=(y/n)** + +| This provides migration support for MLX5 devices using the VFIO framework. + + +**External options** ( Choose if the corresponding mlx5 feature is required ) + +- CONFIG_MLXFW: When chosen, mlx5 firmware flashing support will be enabled (via devlink and ethtool). +- CONFIG_PTP_1588_CLOCK: When chosen, mlx5 ptp support will be enabled +- CONFIG_VXLAN: When chosen, mlx5 vxlan support will be enabled. diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/switchdev.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/switchdev.rst new file mode 100644 index 000000000000..01deedb71597 --- /dev/null +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/switchdev.rst @@ -0,0 +1,239 @@ +.. SPDX-License-Identifier: GPL-2.0 OR Linux-OpenIB +.. include:: <isonum.txt> + +========= +Switchdev +========= + +:Copyright: |copy| 2023, NVIDIA CORPORATION & AFFILIATES. All rights reserved. + +.. _mlx5_bridge_offload: + +Bridge offload +============== + +The mlx5 driver implements support for offloading bridge rules when in switchdev +mode. Linux bridge FDBs are automatically offloaded when mlx5 switchdev +representor is attached to bridge. + +- Change device to switchdev mode:: + + $ devlink dev eswitch set pci/0000:06:00.0 mode switchdev + +- Attach mlx5 switchdev representor 'enp8s0f0' to bridge netdev 'bridge1':: + + $ ip link set enp8s0f0 master bridge1 + +VLANs +----- + +Following bridge VLAN functions are supported by mlx5: + +- VLAN filtering (including multiple VLANs per port):: + + $ ip link set bridge1 type bridge vlan_filtering 1 + $ bridge vlan add dev enp8s0f0 vid 2-3 + +- VLAN push on bridge ingress:: + + $ bridge vlan add dev enp8s0f0 vid 3 pvid + +- VLAN pop on bridge egress:: + + $ bridge vlan add dev enp8s0f0 vid 3 untagged + +Subfunction +=========== + +mlx5 supports subfunction management using devlink port (see :ref:`Documentation/networking/devlink/devlink-port.rst <devlink_port>`) interface. + +A subfunction has its own function capabilities and its own resources. This +means a subfunction has its own dedicated queues (txq, rxq, cq, eq). These +queues are neither shared nor stolen from the parent PCI function. + +When a subfunction is RDMA capable, it has its own QP1, GID table, and RDMA +resources neither shared nor stolen from the parent PCI function. + +A subfunction has a dedicated window in PCI BAR space that is not shared +with the other subfunctions or the parent PCI function. This ensures that all +devices (netdev, rdma, vdpa, etc.) of the subfunction accesses only assigned +PCI BAR space. + +A subfunction supports eswitch representation through which it supports tc +offloads. The user configures eswitch to send/receive packets from/to +the subfunction port. + +Subfunctions share PCI level resources such as PCI MSI-X IRQs with +other subfunctions and/or with its parent PCI function. + +Example mlx5 software, system, and device view:: + + _______ + | admin | + | user |---------- + |_______| | + | | + ____|____ __|______ _________________ + | | | | | | + | devlink | | tc tool | | user | + | tool | |_________| | applications | + |_________| | |_________________| + | | | | + | | | | Userspace + +---------|-------------|-------------------|----------|--------------------+ + | | +----------+ +----------+ Kernel + | | | netdev | | rdma dev | + | | +----------+ +----------+ + (devlink port add/del | ^ ^ + port function set) | | | + | | +---------------| + _____|___ | | _______|_______ + | | | | | mlx5 class | + | devlink | +------------+ | | drivers | + | kernel | | rep netdev | | |(mlx5_core,ib) | + |_________| +------------+ | |_______________| + | | | ^ + (devlink ops) | | (probe/remove) + _________|________ | | ____|________ + | subfunction | | +---------------+ | subfunction | + | management driver|----- | subfunction |---| driver | + | (mlx5_core) | | auxiliary dev | | (mlx5_core) | + |__________________| +---------------+ |_____________| + | ^ + (sf add/del, vhca events) | + | (device add/del) + _____|____ ____|________ + | | | subfunction | + | PCI NIC |--- activate/deactivate events--->| host driver | + |__________| | (mlx5_core) | + |_____________| + +Subfunction is created using devlink port interface. + +- Change device to switchdev mode:: + + $ devlink dev eswitch set pci/0000:06:00.0 mode switchdev + +- Add a devlink port of subfunction flavour:: + + $ devlink port add pci/0000:06:00.0 flavour pcisf pfnum 0 sfnum 88 + pci/0000:06:00.0/32768: type eth netdev eth6 flavour pcisf controller 0 pfnum 0 sfnum 88 external false splittable false + function: + hw_addr 00:00:00:00:00:00 state inactive opstate detached + +- Show a devlink port of the subfunction:: + + $ devlink port show pci/0000:06:00.0/32768 + pci/0000:06:00.0/32768: type eth netdev enp6s0pf0sf88 flavour pcisf pfnum 0 sfnum 88 + function: + hw_addr 00:00:00:00:00:00 state inactive opstate detached + +- Delete a devlink port of subfunction after use:: + + $ devlink port del pci/0000:06:00.0/32768 + +Function attributes +=================== + +The mlx5 driver provides a mechanism to setup PCI VF/SF function attributes in +a unified way for SmartNIC and non-SmartNIC. + +This is supported only when the eswitch mode is set to switchdev. Port function +configuration of the PCI VF/SF is supported through devlink eswitch port. + +Port function attributes should be set before PCI VF/SF is enumerated by the +driver. + +MAC address setup +----------------- + +mlx5 driver support devlink port function attr mechanism to setup MAC +address. (refer to Documentation/networking/devlink/devlink-port.rst) + +RoCE capability setup +~~~~~~~~~~~~~~~~~~~~~ +Not all mlx5 PCI devices/SFs require RoCE capability. + +When RoCE capability is disabled, it saves 1 Mbytes worth of system memory per +PCI devices/SF. + +mlx5 driver support devlink port function attr mechanism to setup RoCE +capability. (refer to Documentation/networking/devlink/devlink-port.rst) + +migratable capability setup +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +User who wants mlx5 PCI VFs to be able to perform live migration need to +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) + +SF state setup +-------------- + +To use the SF, the user must activate the SF using the SF function state +attribute. + +- Get the state of the SF identified by its unique devlink port index:: + + $ devlink port show ens2f0npf0sf88 + pci/0000:06:00.0/32768: type eth netdev ens2f0npf0sf88 flavour pcisf controller 0 pfnum 0 sfnum 88 external false splittable false + function: + hw_addr 00:00:00:00:88:88 state inactive opstate detached + +- Activate the function and verify its state is active:: + + $ devlink port function set ens2f0npf0sf88 state active + + $ devlink port show ens2f0npf0sf88 + pci/0000:06:00.0/32768: type eth netdev ens2f0npf0sf88 flavour pcisf controller 0 pfnum 0 sfnum 88 external false splittable false + function: + hw_addr 00:00:00:00:88:88 state active opstate detached + +Upon function activation, the PF driver instance gets the event from the device +that a particular SF was activated. It's the cue to put the device on bus, probe +it and instantiate the devlink instance and class specific auxiliary devices +for it. + +- Show the auxiliary device and port of the subfunction:: + + $ devlink dev show + devlink dev show auxiliary/mlx5_core.sf.4 + + $ devlink port show auxiliary/mlx5_core.sf.4/1 + auxiliary/mlx5_core.sf.4/1: type eth netdev p0sf88 flavour virtual port 0 splittable false + + $ rdma link show mlx5_0/1 + link mlx5_0/1 state ACTIVE physical_state LINK_UP netdev p0sf88 + + $ rdma dev show + 8: rocep6s0f1: node_type ca fw 16.29.0550 node_guid 248a:0703:00b3:d113 sys_image_guid 248a:0703:00b3:d112 + 13: mlx5_0: node_type ca fw 16.29.0550 node_guid 0000:00ff:fe00:8888 sys_image_guid 248a:0703:00b3:d112 + +- Subfunction auxiliary device and class device hierarchy:: + + mlx5_core.sf.4 + (subfunction auxiliary device) + /\ + / \ + / \ + / \ + / \ + mlx5_core.eth.4 mlx5_core.rdma.4 + (sf eth aux dev) (sf rdma aux dev) + | | + | | + p0sf88 mlx5_0 + (sf netdev) (sf rdma device) + +Additionally, the SF port also gets the event when the driver attaches to the +auxiliary device of the subfunction. This results in changing the operational +state of the function. This provides visibility to the user to decide when is it +safe to delete the SF port for graceful termination of the subfunction. + +- Show the SF port operational state:: + + $ devlink port show ens2f0npf0sf88 + pci/0000:06:00.0/32768: type eth netdev ens2f0npf0sf88 flavour pcisf controller 0 pfnum 0 sfnum 88 external false splittable false + function: + hw_addr 00:00:00:00:88:88 state active opstate attached diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/tracepoints.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/tracepoints.rst new file mode 100644 index 000000000000..da8e53cebb6c --- /dev/null +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/tracepoints.rst @@ -0,0 +1,229 @@ +.. SPDX-License-Identifier: GPL-2.0 OR Linux-OpenIB +.. include:: <isonum.txt> + +=========== +Tracepoints +=========== + +:Copyright: |copy| 2023, NVIDIA CORPORATION & AFFILIATES. All rights reserved. + +mlx5 driver provides internal tracepoints for tracking and debugging using +kernel tracepoints interfaces (refer to Documentation/trace/ftrace.rst). + +For the list of support mlx5 events, check /sys/kernel/tracing/events/mlx5/. + +tc and eswitch offloads tracepoints: + +- mlx5e_configure_flower: trace flower filter actions and cookies offloaded to mlx5:: + + $ echo mlx5:mlx5e_configure_flower >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + tc-6535 [019] ...1 2672.404466: mlx5e_configure_flower: cookie=0000000067874a55 actions= REDIRECT + +- mlx5e_delete_flower: trace flower filter actions and cookies deleted from mlx5:: + + $ echo mlx5:mlx5e_delete_flower >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + tc-6569 [010] .N.1 2686.379075: mlx5e_delete_flower: cookie=0000000067874a55 actions= NULL + +- mlx5e_stats_flower: trace flower stats request:: + + $ echo mlx5:mlx5e_stats_flower >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + tc-6546 [010] ...1 2679.704889: mlx5e_stats_flower: cookie=0000000060eb3d6a bytes=0 packets=0 lastused=4295560217 + +- mlx5e_tc_update_neigh_used_value: trace tunnel rule neigh update value offloaded to mlx5:: + + $ echo mlx5:mlx5e_tc_update_neigh_used_value >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + kworker/u48:4-8806 [009] ...1 55117.882428: mlx5e_tc_update_neigh_used_value: netdev: ens1f0 IPv4: 1.1.1.10 IPv6: ::ffff:1.1.1.10 neigh_used=1 + +- mlx5e_rep_neigh_update: trace neigh update tasks scheduled due to neigh state change events:: + + $ echo mlx5:mlx5e_rep_neigh_update >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + kworker/u48:7-2221 [009] ...1 1475.387435: mlx5e_rep_neigh_update: netdev: ens1f0 MAC: 24:8a:07:9a:17:9a IPv4: 1.1.1.10 IPv6: ::ffff:1.1.1.10 neigh_connected=1 + +Bridge offloads tracepoints: + +- mlx5_esw_bridge_fdb_entry_init: trace bridge FDB entry offloaded to mlx5:: + + $ echo mlx5:mlx5_esw_bridge_fdb_entry_init >> set_event + $ cat /sys/kernel/tracing/trace + ... + kworker/u20:9-2217 [003] ...1 318.582243: mlx5_esw_bridge_fdb_entry_init: net_device=enp8s0f0_0 addr=e4:fd:05:08:00:02 vid=0 flags=0 used=0 + +- mlx5_esw_bridge_fdb_entry_cleanup: trace bridge FDB entry deleted from mlx5:: + + $ echo mlx5:mlx5_esw_bridge_fdb_entry_cleanup >> set_event + $ cat /sys/kernel/tracing/trace + ... + ip-2581 [005] ...1 318.629871: mlx5_esw_bridge_fdb_entry_cleanup: net_device=enp8s0f0_1 addr=e4:fd:05:08:00:03 vid=0 flags=0 used=16 + +- mlx5_esw_bridge_fdb_entry_refresh: trace bridge FDB entry offload refreshed in + mlx5:: + + $ echo mlx5:mlx5_esw_bridge_fdb_entry_refresh >> set_event + $ cat /sys/kernel/tracing/trace + ... + kworker/u20:8-3849 [003] ...1 466716: mlx5_esw_bridge_fdb_entry_refresh: net_device=enp8s0f0_0 addr=e4:fd:05:08:00:02 vid=3 flags=0 used=0 + +- mlx5_esw_bridge_vlan_create: trace bridge VLAN object add on mlx5 + representor:: + + $ echo mlx5:mlx5_esw_bridge_vlan_create >> set_event + $ cat /sys/kernel/tracing/trace + ... + ip-2560 [007] ...1 318.460258: mlx5_esw_bridge_vlan_create: vid=1 flags=6 + +- mlx5_esw_bridge_vlan_cleanup: trace bridge VLAN object delete from mlx5 + representor:: + + $ echo mlx5:mlx5_esw_bridge_vlan_cleanup >> set_event + $ cat /sys/kernel/tracing/trace + ... + bridge-2582 [007] ...1 318.653496: mlx5_esw_bridge_vlan_cleanup: vid=2 flags=8 + +- mlx5_esw_bridge_vport_init: trace mlx5 vport assigned with bridge upper + device:: + + $ echo mlx5:mlx5_esw_bridge_vport_init >> set_event + $ cat /sys/kernel/tracing/trace + ... + ip-2560 [007] ...1 318.458915: mlx5_esw_bridge_vport_init: vport_num=1 + +- mlx5_esw_bridge_vport_cleanup: trace mlx5 vport removed from bridge upper + device:: + + $ echo mlx5:mlx5_esw_bridge_vport_cleanup >> set_event + $ cat /sys/kernel/tracing/trace + ... + ip-5387 [000] ...1 573713: mlx5_esw_bridge_vport_cleanup: vport_num=1 + +Eswitch QoS tracepoints: + +- mlx5_esw_vport_qos_create: trace creation of transmit scheduler arbiter for vport:: + + $ echo mlx5:mlx5_esw_vport_qos_create >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + <...>-23496 [018] .... 73136.838831: mlx5_esw_vport_qos_create: (0000:82:00.0) vport=2 tsar_ix=4 bw_share=0, max_rate=0 group=000000007b576bb3 + +- mlx5_esw_vport_qos_config: trace configuration of transmit scheduler arbiter for vport:: + + $ echo mlx5:mlx5_esw_vport_qos_config >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + <...>-26548 [023] .... 75754.223823: mlx5_esw_vport_qos_config: (0000:82:00.0) vport=1 tsar_ix=3 bw_share=34, max_rate=10000 group=000000007b576bb3 + +- mlx5_esw_vport_qos_destroy: trace deletion of transmit scheduler arbiter for vport:: + + $ echo mlx5:mlx5_esw_vport_qos_destroy >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + <...>-27418 [004] .... 76546.680901: mlx5_esw_vport_qos_destroy: (0000:82:00.0) vport=1 tsar_ix=3 + +- mlx5_esw_group_qos_create: trace creation of transmit scheduler arbiter for rate group:: + + $ echo mlx5:mlx5_esw_group_qos_create >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + <...>-26578 [008] .... 75776.022112: mlx5_esw_group_qos_create: (0000:82:00.0) group=000000008dac63ea tsar_ix=5 + +- mlx5_esw_group_qos_config: trace configuration of transmit scheduler arbiter for rate group:: + + $ echo mlx5:mlx5_esw_group_qos_config >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + <...>-27303 [020] .... 76461.455356: mlx5_esw_group_qos_config: (0000:82:00.0) group=000000008dac63ea tsar_ix=5 bw_share=100 max_rate=20000 + +- mlx5_esw_group_qos_destroy: trace deletion of transmit scheduler arbiter for group:: + + $ echo mlx5:mlx5_esw_group_qos_destroy >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + <...>-27418 [006] .... 76547.187258: mlx5_esw_group_qos_destroy: (0000:82:00.0) group=000000007b576bb3 tsar_ix=1 + +SF tracepoints: + +- mlx5_sf_add: trace addition of the SF port:: + + $ echo mlx5:mlx5_sf_add >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + devlink-9363 [031] ..... 24610.188722: mlx5_sf_add: (0000:06:00.0) port_index=32768 controller=0 hw_id=0x8000 sfnum=88 + +- mlx5_sf_free: trace freeing of the SF port:: + + $ echo mlx5:mlx5_sf_free >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + devlink-9830 [038] ..... 26300.404749: mlx5_sf_free: (0000:06:00.0) port_index=32768 controller=0 hw_id=0x8000 + +- mlx5_sf_activate: trace activation of the SF port:: + + $ echo mlx5:mlx5_sf_activate >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + devlink-29841 [008] ..... 3669.635095: mlx5_sf_activate: (0000:08:00.0) port_index=32768 controller=0 hw_id=0x8000 + +- mlx5_sf_deactivate: trace deactivation of the SF port:: + + $ echo mlx5:mlx5_sf_deactivate >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + devlink-29994 [008] ..... 4015.969467: mlx5_sf_deactivate: (0000:08:00.0) port_index=32768 controller=0 hw_id=0x8000 + +- mlx5_sf_hwc_alloc: trace allocating of the hardware SF context:: + + $ echo mlx5:mlx5_sf_hwc_alloc >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + devlink-9775 [031] ..... 26296.385259: mlx5_sf_hwc_alloc: (0000:06:00.0) controller=0 hw_id=0x8000 sfnum=88 + +- mlx5_sf_hwc_free: trace freeing of the hardware SF context:: + + $ echo mlx5:mlx5_sf_hwc_free >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + kworker/u128:3-9093 [046] ..... 24625.365771: mlx5_sf_hwc_free: (0000:06:00.0) hw_id=0x8000 + +- mlx5_sf_hwc_deferred_free: trace deferred freeing of the hardware SF context:: + + $ echo mlx5:mlx5_sf_hwc_deferred_free >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + devlink-9519 [046] ..... 24624.400271: mlx5_sf_hwc_deferred_free: (0000:06:00.0) hw_id=0x8000 + +- mlx5_sf_update_state: trace state updates for SF contexts:: + + $ echo mlx5:mlx5_sf_update_state >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + kworker/u20:3-29490 [009] ..... 4141.453530: mlx5_sf_update_state: (0000:08:00.0) port_index=32768 controller=0 hw_id=0x8000 state=2 + +- mlx5_sf_vhca_event: trace SF vhca event and state:: + + $ echo mlx5:mlx5_sf_vhca_event >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + kworker/u128:3-9093 [046] ..... 24625.365525: mlx5_sf_vhca_event: (0000:06:00.0) hw_id=0x8000 sfnum=88 vhca_state=1 + +- mlx5_sf_dev_add: trace SF device add event:: + + $ echo mlx5:mlx5_sf_dev_add>> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + kworker/u128:3-9093 [000] ..... 24616.524495: mlx5_sf_dev_add: (0000:06:00.0) sfdev=00000000fc5d96fd aux_id=4 hw_id=0x8000 sfnum=88 + +- mlx5_sf_dev_del: trace SF device delete event:: + + $ echo mlx5:mlx5_sf_dev_del >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace + ... + kworker/u128:3-9093 [044] ..... 24624.400749: mlx5_sf_dev_del: (0000:06:00.0) sfdev=00000000fc5d96fd aux_id=4 hw_id=0x8000 sfnum=88 diff --git a/Documentation/networking/device_drivers/ethernet/pensando/ionic.rst b/Documentation/networking/device_drivers/ethernet/pensando/ionic.rst index 0eabbc347d6c..6ec7d686efab 100644 --- a/Documentation/networking/device_drivers/ethernet/pensando/ionic.rst +++ b/Documentation/networking/device_drivers/ethernet/pensando/ionic.rst @@ -83,7 +83,7 @@ Configuring the Driver MTU --- -Jumbo frame support is available with a maximim size of 9194 bytes. +Jumbo frame support is available with a maximum size of 9194 bytes. Interrupt coalescing -------------------- diff --git a/Documentation/networking/device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst b/Documentation/networking/device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst index f24adfab6a1b..25fd9aa284e2 100644 --- a/Documentation/networking/device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst +++ b/Documentation/networking/device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst @@ -124,7 +124,7 @@ Multicast flooding ================== CPU port mcast_flooding is always on -Turning flooding on/off on swithch ports: +Turning flooding on/off on switch ports: bridge link set dev sw0p1 mcast_flood on/off Access and Trunk port diff --git a/Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst b/Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst index 1241ecac73bd..464dce938ed1 100644 --- a/Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst +++ b/Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst @@ -174,7 +174,7 @@ Multicast flooding ================== CPU port mcast_flooding is always on -Turning flooding on/off on swithch ports: +Turning flooding on/off on switch ports: bridge link set dev sw0p1 mcast_flood on/off Access and Trunk port diff --git a/Documentation/networking/device_drivers/ethernet/wangxun/txgbe.rst b/Documentation/networking/device_drivers/ethernet/wangxun/txgbe.rst index eaa87dbe8848..d052ef40fe36 100644 --- a/Documentation/networking/device_drivers/ethernet/wangxun/txgbe.rst +++ b/Documentation/networking/device_drivers/ethernet/wangxun/txgbe.rst @@ -16,5 +16,5 @@ Contents Support ======= -If you got any problem, contact Wangxun support team via support@trustnetic.com +If you got any problem, contact Wangxun support team via nic-support@net-swift.com and Cc: netdev. diff --git a/Documentation/networking/device_drivers/wwan/iosm.rst b/Documentation/networking/device_drivers/wwan/iosm.rst index aceb0223eb46..6f9e955af984 100644 --- a/Documentation/networking/device_drivers/wwan/iosm.rst +++ b/Documentation/networking/device_drivers/wwan/iosm.rst @@ -69,7 +69,7 @@ wwan0-X network device The IOSM driver exposes IP link interface "wwan0-X" of type "wwan" for IP traffic. Iproute network utility is used for creating "wwan0-X" network interface and for associating it with MBIM IP session. The Driver supports -upto 8 IP sessions for simultaneous IP communication. +up to 8 IP sessions for simultaneous IP communication. The userspace management application is responsible for creating new IP link prior to establishing MBIM IP session where the SessionId is greater than 0. diff --git a/Documentation/networking/devlink/devlink-health.rst b/Documentation/networking/devlink/devlink-health.rst index e37f77734b5b..e0b8cfed610a 100644 --- a/Documentation/networking/devlink/devlink-health.rst +++ b/Documentation/networking/devlink/devlink-health.rst @@ -33,7 +33,7 @@ Device driver can provide specific callbacks for each "health reporter", e.g.: * Recovery procedures * Diagnostics procedures * Object dump procedures - * OOB initial parameters + * Out Of Box initial parameters Different parts of the driver can register different types of health reporters with different handlers. @@ -46,12 +46,31 @@ Once an error is reported, devlink health will perform the following actions: * A log is being send to the kernel trace events buffer * Health status and statistics are being updated for the reporter instance * Object dump is being taken and saved at the reporter instance (as long as - there is no other dump which is already stored) + auto-dump is set and there is no other dump which is already stored) * Auto recovery attempt is being done. Depends on: - Auto-recovery configuration - Grace period vs. time passed since last recover +Devlink formatted message +========================= + +To handle devlink health diagnose and health dump requests, devlink creates a +formatted message structure ``devlink_fmsg`` and send it to the driver's callback +to fill the data in using the devlink fmsg API. + +Devlink fmsg is a mechanism to pass descriptors between drivers and devlink, in +json-like format. The API allows the driver to add nested attributes such as +object, object pair and value array, in addition to attributes such as name and +value. + +Driver should use this API to fill the fmsg context in a format which will be +translated by the devlink to the netlink message later. When it needs to send +the data using SKBs to the netlink layer, it fragments the data between +different SKBs. In order to do this fragmentation, it uses virtual nests +attributes, to avoid actual nesting use which cannot be divided between +different SKBs. + User Interface ============== diff --git a/Documentation/networking/devlink/ice.rst b/Documentation/networking/devlink/ice.rst index 625efb3777d5..10f282c2117c 100644 --- a/Documentation/networking/devlink/ice.rst +++ b/Documentation/networking/devlink/ice.rst @@ -285,7 +285,7 @@ features are enabled after the hierarchy is exported, but before any changes are made. This feature is also dependent on switchdev being enabled in the system. -It's required bacause devlink-rate requires devlink-port objects to be +It's required because devlink-rate requires devlink-port objects to be present, and those objects are only created in switchdev mode. If the driver is set to the switchdev mode, it will export internal @@ -320,7 +320,7 @@ nodes and nodes with children also can't be deleted. * - ``tx_weight`` - allows for usage of Weighted Fair Queuing arbitration scheme among siblings. This arbitration scheme can be used simultaneously with - the strict priority. Range 1-200. Only relative values mater for + the strict priority. Range 1-200. Only relative values matter for arbitration. ``tx_priority`` and ``tx_weight`` can be used simultaneously. In that case diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst index fee4d3968309..b49749e2b9a6 100644 --- a/Documentation/networking/devlink/index.rst +++ b/Documentation/networking/devlink/index.rst @@ -66,3 +66,4 @@ parameters, info versions, and other features it supports. prestera iosm octeontx2 + sfc diff --git a/Documentation/networking/devlink/mlx5.rst b/Documentation/networking/devlink/mlx5.rst index 29ad304e6fba..3321117cf605 100644 --- a/Documentation/networking/devlink/mlx5.rst +++ b/Documentation/networking/devlink/mlx5.rst @@ -54,6 +54,24 @@ parameters. - Control the number of large groups (size > 1) in the FDB table. * The default value is 15, and the range is between 1 and 1024. + * - ``esw_multiport`` + - Boolean + - runtime + - Control MultiPort E-Switch shared fdb mode. + + An experimental mode where a single E-Switch is used and all the vports + and physical ports on the NIC are connected to it. + + An example is to send traffic from a VF that is created on PF0 to an + uplink that is natively associated with the uplink of PF1 + + Note: Future devices, ConnectX-8 and onward, will eventually have this + as the default to allow forwarding between all NIC ports in a single + E-switch environment and the dual E-switch mode will likely get + deprecated. + + Default: disabled + The ``mlx5`` driver supports reloading via ``DEVLINK_CMD_RELOAD`` diff --git a/Documentation/networking/devlink/netdevsim.rst b/Documentation/networking/devlink/netdevsim.rst index ec5e6d79b2e2..88482725422c 100644 --- a/Documentation/networking/devlink/netdevsim.rst +++ b/Documentation/networking/devlink/netdevsim.rst @@ -95,5 +95,5 @@ Driver-specific Traps * - ``fid_miss`` - ``exception`` - When a packet enters the device it is classified to a filtering - indentifier (FID) based on the ingress port and VLAN. This trap is used + identifier (FID) based on the ingress port and VLAN. This trap is used to trap packets for which a FID could not be found diff --git a/Documentation/networking/devlink/prestera.rst b/Documentation/networking/devlink/prestera.rst index 49409d1d3081..96b1124e614b 100644 --- a/Documentation/networking/devlink/prestera.rst +++ b/Documentation/networking/devlink/prestera.rst @@ -138,4 +138,4 @@ Driver-specific Traps - Drops packets with zero (0) IPV4 source address. * - ``met_red`` - ``drop`` - - Drops non-conforming packets (dropped by Ingress policer, metering drop), e.g. packet rate exceeded configured bandwith. + - Drops non-conforming packets (dropped by Ingress policer, metering drop), e.g. packet rate exceeded configured bandwidth. diff --git a/Documentation/networking/devlink/sfc.rst b/Documentation/networking/devlink/sfc.rst new file mode 100644 index 000000000000..db64a1bd9733 --- /dev/null +++ b/Documentation/networking/devlink/sfc.rst @@ -0,0 +1,57 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================== +sfc devlink support +=================== + +This document describes the devlink features implemented by the ``sfc`` +device driver for the ef100 device. + +Info versions +============= + +The ``sfc`` driver reports the following versions + +.. list-table:: devlink info versions implemented + :widths: 5 5 90 + + * - Name + - Type + - Description + * - ``fw.mgmt.suc`` + - running + - For boards where the management function is split between multiple + control units, this is the SUC control unit's firmware version. + * - ``fw.mgmt.cmc`` + - running + - For boards where the management function is split between multiple + control units, this is the CMC control unit's firmware version. + * - ``fpga.rev`` + - running + - FPGA design revision. + * - ``fpga.app`` + - running + - Datapath programmable logic version. + * - ``fw.app`` + - running + - Datapath software/microcode/firmware version. + * - ``coproc.boot`` + - running + - SmartNIC application co-processor (APU) first stage boot loader version. + * - ``coproc.uboot`` + - running + - SmartNIC application co-processor (APU) co-operating system loader version. + * - ``coproc.main`` + - running + - SmartNIC application co-processor (APU) main operating system version. + * - ``coproc.recovery`` + - running + - SmartNIC application co-processor (APU) recovery operating system version. + * - ``fw.exprom`` + - running + - Expansion ROM version. For boards where the expansion ROM is split between + multiple images (e.g. PXE and UEFI), this is the specifically the PXE boot + ROM version. + * - ``fw.uefi`` + - running + - UEFI driver version (No UNDI support). diff --git a/Documentation/networking/dsa/configuration.rst b/Documentation/networking/dsa/configuration.rst index 827701f8cbfe..d2934c40f0f1 100644 --- a/Documentation/networking/dsa/configuration.rst +++ b/Documentation/networking/dsa/configuration.rst @@ -5,7 +5,7 @@ DSA switch configuration from userspace ======================================= The DSA switch configuration is not integrated into the main userspace -network configuration suites by now and has to be performed manualy. +network configuration suites by now and has to be performed manually. .. _dsa-config-showcases: diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst index f10f8eb44255..e1bc6186d7ea 100644 --- a/Documentation/networking/ethtool-netlink.rst +++ b/Documentation/networking/ethtool-netlink.rst @@ -106,7 +106,7 @@ modifying a bitmap, the former changes the bit set in mask to values set in value and preserves the rest; the latter sets the bits set in the bitmap and clears the rest. -Compact form: nested (bitset) atrribute contents: +Compact form: nested (bitset) attribute contents: ============================ ====== ============================ ``ETHTOOL_A_BITSET_NOMASK`` flag no mask, only a list @@ -223,6 +223,8 @@ Userspace to kernel: ``ETHTOOL_MSG_PSE_SET`` set PSE parameters ``ETHTOOL_MSG_PSE_GET`` get PSE parameters ``ETHTOOL_MSG_RSS_GET`` get RSS settings + ``ETHTOOL_MSG_MM_GET`` get MAC merge layer state + ``ETHTOOL_MSG_MM_SET`` set MAC merge layer parameters ===================================== ================================= Kernel to userspace: @@ -265,6 +267,7 @@ Kernel to userspace: ``ETHTOOL_MSG_MODULE_GET_REPLY`` transceiver module parameters ``ETHTOOL_MSG_PSE_GET_REPLY`` PSE parameters ``ETHTOOL_MSG_RSS_GET_REPLY`` RSS settings + ``ETHTOOL_MSG_MM_GET_REPLY`` MAC merge layer status ======================================== ================================= ``GET`` requests are sent by userspace applications to retrieve device @@ -780,7 +783,7 @@ Kernel response contents: ``ETHTOOL_A_FEATURES_ACTIVE`` bitset diff old vs. new active ==================================== ====== ========================== -Request constains only one bitset which can be either value/mask pair (request +Request contains only one bitset which can be either value/mask pair (request to change specific feature bits and leave the rest) or only a value (request to set all features to specified set). @@ -871,6 +874,7 @@ Kernel response contents: ``ETHTOOL_A_RINGS_TCP_DATA_SPLIT`` u8 TCP header / data split ``ETHTOOL_A_RINGS_CQE_SIZE`` u32 Size of TX/RX CQE ``ETHTOOL_A_RINGS_TX_PUSH`` u8 flag of TX Push mode + ``ETHTOOL_A_RINGS_RX_PUSH`` u8 flag of RX Push mode ==================================== ====== =========================== ``ETHTOOL_A_RINGS_TCP_DATA_SPLIT`` indicates whether the device is usable with @@ -880,8 +884,8 @@ separate buffers. The device configuration must make it possible to receive full memory pages of data, for example because MTU is high enough or through HW-GRO. -``ETHTOOL_A_RINGS_TX_PUSH`` flag is used to enable descriptor fast -path to send packets. In ordinary path, driver fills descriptors in DRAM and +``ETHTOOL_A_RINGS_[RX|TX]_PUSH`` flag is used to enable descriptor fast +path to send or receive packets. In ordinary path, driver fills descriptors in DRAM and notifies NIC hardware. In fast path, driver pushes descriptors to the device through MMIO writes, thus reducing the latency. However, enabling this feature may increase the CPU cost. Drivers may enforce additional per-packet @@ -903,6 +907,7 @@ Request contents: ``ETHTOOL_A_RINGS_RX_BUF_LEN`` u32 size of buffers on the ring ``ETHTOOL_A_RINGS_CQE_SIZE`` u32 Size of TX/RX CQE ``ETHTOOL_A_RINGS_TX_PUSH`` u8 flag of TX Push mode + ``ETHTOOL_A_RINGS_RX_PUSH`` u8 flag of RX Push mode ==================================== ====== =========================== Kernel checks that requested ring sizes do not exceed limits reported by @@ -1004,6 +1009,9 @@ Kernel response contents: ``ETHTOOL_A_COALESCE_RATE_SAMPLE_INTERVAL`` u32 rate sampling interval ``ETHTOOL_A_COALESCE_USE_CQE_TX`` bool timer reset mode, Tx ``ETHTOOL_A_COALESCE_USE_CQE_RX`` bool timer reset mode, Rx + ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_BYTES`` u32 max aggr size, Tx + ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_FRAMES`` u32 max aggr packets, Tx + ``ETHTOOL_A_COALESCE_TX_AGGR_TIME_USECS`` u32 time (us), aggr, Tx =========================================== ====== ======================= Attributes are only included in reply if their value is not zero or the @@ -1022,6 +1030,17 @@ each packet event resets the timer. In this mode timer is used to force the interrupt if queue goes idle, while busy queues depend on the packet limit to trigger interrupts. +Tx aggregation consists of copying frames into a contiguous buffer so that they +can be submitted as a single IO operation. ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_BYTES`` +describes the maximum size in bytes for the submitted buffer. +``ETHTOOL_A_COALESCE_TX_AGGR_MAX_FRAMES`` describes the maximum number of frames +that can be aggregated into a single buffer. +``ETHTOOL_A_COALESCE_TX_AGGR_TIME_USECS`` describes the amount of time in usecs, +counted since the first packet arrival in an aggregated block, after which the +block should be sent. +This feature is mainly of interest for specific USB devices which does not cope +well with frequent small-sized URBs transmissions. + COALESCE_SET ============ @@ -1055,6 +1074,9 @@ Request contents: ``ETHTOOL_A_COALESCE_RATE_SAMPLE_INTERVAL`` u32 rate sampling interval ``ETHTOOL_A_COALESCE_USE_CQE_TX`` bool timer reset mode, Tx ``ETHTOOL_A_COALESCE_USE_CQE_RX`` bool timer reset mode, Rx + ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_BYTES`` u32 max aggr size, Tx + ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_FRAMES`` u32 max aggr packets, Tx + ``ETHTOOL_A_COALESCE_TX_AGGR_TIME_USECS`` u32 time (us), aggr, Tx =========================================== ====== ======================= Request is rejected if it attributes declared as unsupported by driver (i.e. @@ -1072,8 +1094,18 @@ Request contents: ===================================== ====== ========================== ``ETHTOOL_A_PAUSE_HEADER`` nested request header + ``ETHTOOL_A_PAUSE_STATS_SRC`` u32 source of statistics ===================================== ====== ========================== +``ETHTOOL_A_PAUSE_STATS_SRC`` is optional. It takes values from: + +.. kernel-doc:: include/uapi/linux/ethtool.h + :identifiers: ethtool_mac_stats_src + +If absent from the request, stats will be provided with +an ``ETHTOOL_A_PAUSE_STATS_SRC`` attribute in the response equal to +``ETHTOOL_MAC_STATS_SRC_AGGREGATE``. + Kernel response contents: ===================================== ====== ========================== @@ -1488,6 +1520,7 @@ Request contents: ======================================= ====== ========================== ``ETHTOOL_A_STATS_HEADER`` nested request header + ``ETHTOOL_A_STATS_SRC`` u32 source of statistics ``ETHTOOL_A_STATS_GROUPS`` bitset requested groups of stats ======================================= ====== ========================== @@ -1496,6 +1529,8 @@ Kernel response contents: +-----------------------------------+--------+--------------------------------+ | ``ETHTOOL_A_STATS_HEADER`` | nested | reply header | +-----------------------------------+--------+--------------------------------+ + | ``ETHTOOL_A_STATS_SRC`` | u32 | source of statistics | + +-----------------------------------+--------+--------------------------------+ | ``ETHTOOL_A_STATS_GRP`` | nested | one or more group of stats | +-+---------------------------------+--------+--------------------------------+ | | ``ETHTOOL_A_STATS_GRP_ID`` | u32 | group ID - ``ETHTOOL_STATS_*`` | @@ -1557,6 +1592,11 @@ Low and high bounds are inclusive, for example: etherStatsPkts512to1023Octets 512 1023 ============================= ==== ==== +``ETHTOOL_A_STATS_SRC`` is optional. Similar to ``PAUSE_GET``, it takes values +from ``enum ethtool_mac_stats_src``. If absent from the request, stats will be +provided with an ``ETHTOOL_A_STATS_SRC`` attribute in the response equal to +``ETHTOOL_MAC_STATS_SRC_AGGREGATE``. + PHC_VCLOCKS_GET =============== @@ -1716,6 +1756,225 @@ being used. Current supported options are toeplitz, xor or crc32. ETHTOOL_A_RSS_INDIR attribute returns RSS indrection table where each byte indicates queue number. +PLCA_GET_CFG +============ + +Gets the IEEE 802.3cg-2019 Clause 148 Physical Layer Collision Avoidance +(PLCA) Reconciliation Sublayer (RS) attributes. + +Request contents: + + ===================================== ====== ========================== + ``ETHTOOL_A_PLCA_HEADER`` nested request header + ===================================== ====== ========================== + +Kernel response contents: + + ====================================== ====== ============================= + ``ETHTOOL_A_PLCA_HEADER`` nested reply header + ``ETHTOOL_A_PLCA_VERSION`` u16 Supported PLCA management + interface standard/version + ``ETHTOOL_A_PLCA_ENABLED`` u8 PLCA Admin State + ``ETHTOOL_A_PLCA_NODE_ID`` u32 PLCA unique local node ID + ``ETHTOOL_A_PLCA_NODE_CNT`` u32 Number of PLCA nodes on the + network, including the + coordinator + ``ETHTOOL_A_PLCA_TO_TMR`` u32 Transmit Opportunity Timer + value in bit-times (BT) + ``ETHTOOL_A_PLCA_BURST_CNT`` u32 Number of additional packets + the node is allowed to send + within a single TO + ``ETHTOOL_A_PLCA_BURST_TMR`` u32 Time to wait for the MAC to + transmit a new frame before + terminating the burst + ====================================== ====== ============================= + +When set, the optional ``ETHTOOL_A_PLCA_VERSION`` attribute indicates which +standard and version the PLCA management interface complies to. When not set, +the interface is vendor-specific and (possibly) supplied by the driver. +The OPEN Alliance SIG specifies a standard register map for 10BASE-T1S PHYs +embedding the PLCA Reconcialiation Sublayer. See "10BASE-T1S PLCA Management +Registers" at https://www.opensig.org/about/specifications/. + +When set, the optional ``ETHTOOL_A_PLCA_ENABLED`` attribute indicates the +administrative state of the PLCA RS. When not set, the node operates in "plain" +CSMA/CD mode. This option is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.1 +aPLCAAdminState / 30.16.1.2.1 acPLCAAdminControl. + +When set, the optional ``ETHTOOL_A_PLCA_NODE_ID`` attribute indicates the +configured local node ID of the PHY. This ID determines which transmit +opportunity (TO) is reserved for the node to transmit into. This option is +corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.4 aPLCALocalNodeID. The valid +range for this attribute is [0 .. 255] where 255 means "not configured". + +When set, the optional ``ETHTOOL_A_PLCA_NODE_CNT`` attribute indicates the +configured maximum number of PLCA nodes on the mixing-segment. This number +determines the total number of transmit opportunities generated during a +PLCA cycle. This attribute is relevant only for the PLCA coordinator, which is +the node with aPLCALocalNodeID set to 0. Follower nodes ignore this setting. +This option is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.3 +aPLCANodeCount. The valid range for this attribute is [1 .. 255]. + +When set, the optional ``ETHTOOL_A_PLCA_TO_TMR`` attribute indicates the +configured value of the transmit opportunity timer in bit-times. This value +must be set equal across all nodes sharing the medium for PLCA to work +correctly. This option is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.5 +aPLCATransmitOpportunityTimer. The valid range for this attribute is +[0 .. 255]. + +When set, the optional ``ETHTOOL_A_PLCA_BURST_CNT`` attribute indicates the +configured number of extra packets that the node is allowed to send during a +single transmit opportunity. By default, this attribute is 0, meaning that +the node can only send a single frame per TO. When greater than 0, the PLCA RS +keeps the TO after any transmission, waiting for the MAC to send a new frame +for up to aPLCABurstTimer BTs. This can only happen a number of times per PLCA +cycle up to the value of this parameter. After that, the burst is over and the +normal counting of TOs resumes. This option is corresponding to +``IEEE 802.3cg-2019`` 30.16.1.1.6 aPLCAMaxBurstCount. The valid range for this +attribute is [0 .. 255]. + +When set, the optional ``ETHTOOL_A_PLCA_BURST_TMR`` attribute indicates how +many bit-times the PLCA RS waits for the MAC to initiate a new transmission +when aPLCAMaxBurstCount is greater than 0. If the MAC fails to send a new +frame within this time, the burst ends and the counting of TOs resumes. +Otherwise, the new frame is sent as part of the current burst. This option +is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.7 aPLCABurstTimer. The +valid range for this attribute is [0 .. 255]. Although, the value should be +set greater than the Inter-Frame-Gap (IFG) time of the MAC (plus some margin) +for PLCA burst mode to work as intended. + +PLCA_SET_CFG +============ + +Sets PLCA RS parameters. + +Request contents: + + ====================================== ====== ============================= + ``ETHTOOL_A_PLCA_HEADER`` nested request header + ``ETHTOOL_A_PLCA_ENABLED`` u8 PLCA Admin State + ``ETHTOOL_A_PLCA_NODE_ID`` u8 PLCA unique local node ID + ``ETHTOOL_A_PLCA_NODE_CNT`` u8 Number of PLCA nodes on the + netkork, including the + coordinator + ``ETHTOOL_A_PLCA_TO_TMR`` u8 Transmit Opportunity Timer + value in bit-times (BT) + ``ETHTOOL_A_PLCA_BURST_CNT`` u8 Number of additional packets + the node is allowed to send + within a single TO + ``ETHTOOL_A_PLCA_BURST_TMR`` u8 Time to wait for the MAC to + transmit a new frame before + terminating the burst + ====================================== ====== ============================= + +For a description of each attribute, see ``PLCA_GET_CFG``. + +PLCA_GET_STATUS +=============== + +Gets PLCA RS status information. + +Request contents: + + ===================================== ====== ========================== + ``ETHTOOL_A_PLCA_HEADER`` nested request header + ===================================== ====== ========================== + +Kernel response contents: + + ====================================== ====== ============================= + ``ETHTOOL_A_PLCA_HEADER`` nested reply header + ``ETHTOOL_A_PLCA_STATUS`` u8 PLCA RS operational status + ====================================== ====== ============================= + +When set, the ``ETHTOOL_A_PLCA_STATUS`` attribute indicates whether the node is +detecting the presence of the BEACON on the network. This flag is +corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.2 aPLCAStatus. + +MM_GET +====== + +Retrieve 802.3 MAC Merge parameters. + +Request contents: + + ==================================== ====== ========================== + ``ETHTOOL_A_MM_HEADER`` nested request header + ==================================== ====== ========================== + +Kernel response contents: + + ================================= ====== =================================== + ``ETHTOOL_A_MM_HEADER`` nested request header + ``ETHTOOL_A_MM_PMAC_ENABLED`` bool set if RX of preemptible and SMD-V + frames is enabled + ``ETHTOOL_A_MM_TX_ENABLED`` bool set if TX of preemptible frames is + administratively enabled (might be + inactive if verification failed) + ``ETHTOOL_A_MM_TX_ACTIVE`` bool set if TX of preemptible frames is + operationally enabled + ``ETHTOOL_A_MM_TX_MIN_FRAG_SIZE`` u32 minimum size of transmitted + non-final fragments, in octets + ``ETHTOOL_A_MM_RX_MIN_FRAG_SIZE`` u32 minimum size of received non-final + fragments, in octets + ``ETHTOOL_A_MM_VERIFY_ENABLED`` bool set if TX of SMD-V frames is + administratively enabled + ``ETHTOOL_A_MM_VERIFY_STATUS`` u8 state of the verification function + ``ETHTOOL_A_MM_VERIFY_TIME`` u32 delay between verification attempts + ``ETHTOOL_A_MM_MAX_VERIFY_TIME``` u32 maximum verification interval + supported by device + ``ETHTOOL_A_MM_STATS`` nested IEEE 802.3-2018 subclause 30.14.1 + oMACMergeEntity statistics counters + ================================= ====== =================================== + +The attributes are populated by the device driver through the following +structure: + +.. kernel-doc:: include/linux/ethtool.h + :identifiers: ethtool_mm_state + +The ``ETHTOOL_A_MM_VERIFY_STATUS`` will report one of the values from + +.. kernel-doc:: include/uapi/linux/ethtool.h + :identifiers: ethtool_mm_verify_status + +If ``ETHTOOL_A_MM_VERIFY_ENABLED`` was passed as false in the ``MM_SET`` +command, ``ETHTOOL_A_MM_VERIFY_STATUS`` will report either +``ETHTOOL_MM_VERIFY_STATUS_INITIAL`` or ``ETHTOOL_MM_VERIFY_STATUS_DISABLED``, +otherwise it should report one of the other states. + +It is recommended that drivers start with the pMAC disabled, and enable it upon +user space request. It is also recommended that user space does not depend upon +the default values from ``ETHTOOL_MSG_MM_GET`` requests. + +``ETHTOOL_A_MM_STATS`` are reported if ``ETHTOOL_FLAG_STATS`` was set in +``ETHTOOL_A_HEADER_FLAGS``. The attribute will be empty if driver did not +report any statistics. Drivers fill in the statistics in the following +structure: + +.. kernel-doc:: include/linux/ethtool.h + :identifiers: ethtool_mm_stats + +MM_SET +====== + +Modifies the configuration of the 802.3 MAC Merge layer. + +Request contents: + + ================================= ====== ========================== + ``ETHTOOL_A_MM_VERIFY_TIME`` u32 see MM_GET description + ``ETHTOOL_A_MM_VERIFY_ENABLED`` bool see MM_GET description + ``ETHTOOL_A_MM_TX_ENABLED`` bool see MM_GET description + ``ETHTOOL_A_MM_PMAC_ENABLED`` bool see MM_GET description + ``ETHTOOL_A_MM_TX_MIN_FRAG_SIZE`` u32 see MM_GET description + ================================= ====== ========================== + +The attributes are propagated to the driver through the following structure: + +.. kernel-doc:: include/linux/ethtool.h + :identifiers: ethtool_mm_cfg + Request translation =================== @@ -1817,4 +2076,9 @@ are netlink only. n/a ``ETHTOOL_MSG_PHC_VCLOCKS_GET`` n/a ``ETHTOOL_MSG_MODULE_GET`` n/a ``ETHTOOL_MSG_MODULE_SET`` + n/a ``ETHTOOL_MSG_PLCA_GET_CFG`` + n/a ``ETHTOOL_MSG_PLCA_SET_CFG`` + n/a ``ETHTOOL_MSG_PLCA_GET_STATUS`` + n/a ``ETHTOOL_MSG_MM_GET`` + n/a ``ETHTOOL_MSG_MM_SET`` =================================== ===================================== diff --git a/Documentation/networking/gtp.rst b/Documentation/networking/gtp.rst index 1563fb94b289..9a7835cc1437 100644 --- a/Documentation/networking/gtp.rst +++ b/Documentation/networking/gtp.rst @@ -162,7 +162,7 @@ Local GTP-U entity and tunnel identification GTP-U uses UDP for transporting PDU's. The receiving UDP port is 2152 for GTPv1-U and 3386 for GTPv0-U. -There is only one GTP-U entity (and therefor SGSN/GGSN/S-GW/PDN-GW +There is only one GTP-U entity (and therefore SGSN/GGSN/S-GW/PDN-GW instance) per IP address. Tunnel Endpoint Identifier (TEID) are unique per GTP-U entity. diff --git a/Documentation/networking/ieee802154.rst b/Documentation/networking/ieee802154.rst index f27856d77c8b..c652d383fe10 100644 --- a/Documentation/networking/ieee802154.rst +++ b/Documentation/networking/ieee802154.rst @@ -70,7 +70,7 @@ Like with WiFi, there are several types of devices implementing IEEE 802.15.4. exports a management (e.g. MLME) and data API. 2) 'SoftMAC' or just radio. These types of devices are just radio transceivers possibly with some kinds of acceleration like automatic CRC computation and -comparation, automagic ACK handling, address matching, etc. +comparison, automagic ACK handling, address matching, etc. Those types of devices require different approach to be hooked into Linux kernel. diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 4f2d1f682a18..4ddcae33c336 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -120,6 +120,7 @@ Contents: xfrm_proc xfrm_sync xfrm_sysctl + xdp-rx-metadata .. only:: subproject and html diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst index 7fbd060d6047..87dd1c5283e6 100644 --- a/Documentation/networking/ip-sysctl.rst +++ b/Documentation/networking/ip-sysctl.rst @@ -50,7 +50,7 @@ ip_no_pmtu_disc - INTEGER Default: FALSE min_pmtu - INTEGER - default 552 - minimum Path MTU. Unless this is changed mannually, + default 552 - minimum Path MTU. Unless this is changed manually, each cached pmtu will never be lower than this setting. ip_forward_use_pmtu - BOOLEAN @@ -156,6 +156,9 @@ route/max_size - INTEGER From linux kernel 3.6 onwards, this is deprecated for ipv4 as route cache is no longer used. + From linux kernel 6.3 onwards, this is deprecated for ipv6 + as garbage collection manages cached route entries. + neigh/default/gc_thresh1 - INTEGER Minimum number of entries to keep. Garbage collector will not purge entries if there are fewer than this number. @@ -1589,6 +1592,14 @@ proxy_arp_pvlan - BOOLEAN Hewlett-Packard call it Source-Port filtering or port-isolation. Ericsson call it MAC-Forced Forwarding (RFC Draft). +proxy_delay - INTEGER + Delay proxy response. + + Delay response to a neighbor solicitation when proxy_arp + or proxy_ndp is enabled. A random value between [0, proxy_delay) + will be chosen, setting to zero means reply with no delay. + Value in jiffies. Defaults to 80. + shared_media - BOOLEAN Send(router) or accept(host) RFC1620 shared media redirects. Overrides secure_redirects. @@ -2075,7 +2086,7 @@ skip_notify_on_dev_down - BOOLEAN nexthop_compat_mode - BOOLEAN New nexthop API provides a means for managing nexthops independent of - prefixes. Backwards compatibilty with old route format is enabled by + prefixes. Backwards compatibility with old route format is enabled by default which means route dumps and notifications contain the new nexthop attribute but also the full, expanded nexthop definition. Further, updates or deletes of a nexthop configuration generate route @@ -2808,7 +2819,7 @@ pf_expose - INTEGER can be got via SCTP_GET_PEER_ADDR_INFO sockopt; When it's enabled, a SCTP_PEER_ADDR_CHANGE event will be sent for a transport becoming SCTP_PF state and a SCTP_PF-state transport info can be got via - SCTP_GET_PEER_ADDR_INFO sockopt; When it's diabled, no + SCTP_GET_PEER_ADDR_INFO sockopt; When it's disabled, no SCTP_PEER_ADDR_CHANGE event will be sent and it returns -EACCES when trying to get a SCTP_PF-state transport info via SCTP_GET_PEER_ADDR_INFO sockopt. diff --git a/Documentation/networking/ipvlan.rst b/Documentation/networking/ipvlan.rst index 0000c1d383bc..895d0ccfd596 100644 --- a/Documentation/networking/ipvlan.rst +++ b/Documentation/networking/ipvlan.rst @@ -61,7 +61,7 @@ e.g. IPvlan has two modes of operation - L2 and L3. For a given master device, you can select one of these two modes and all slaves on that master will operate in the same (selected) mode. The RX mode is almost identical except -that in L3 mode the slaves wont receive any multicast / broadcast traffic. +that in L3 mode the slaves won't receive any multicast / broadcast traffic. L3 mode is more restrictive since routing is controlled from the other (mostly) default namespace. diff --git a/Documentation/networking/j1939.rst b/Documentation/networking/j1939.rst index b705d2801e9c..e4bd7aa1f5aa 100644 --- a/Documentation/networking/j1939.rst +++ b/Documentation/networking/j1939.rst @@ -116,7 +116,7 @@ format, the Group Extension is set in the PS-field. ---------------------------------------- 23 ... 16 15 ... 8 ============== ======================== - F0h ... FFh GE (Group Extenstion) + F0h ... FFh GE (Group Extension) ============== ======================== On the other hand, when using PDU1 format, the PS-field contains a so-called diff --git a/Documentation/networking/net_failover.rst b/Documentation/networking/net_failover.rst index 3a662f2b4d6e..f4e1b4e07adc 100644 --- a/Documentation/networking/net_failover.rst +++ b/Documentation/networking/net_failover.rst @@ -90,7 +90,7 @@ virtio-net interface, and ens11 is the slave 'primary' VF passthrough interface. One point to note here is that some user space network configuration daemons like systemd-networkd, ifupdown, etc, do not understand the 'net_failover' device; and on the first boot, the VM might end up with both 'failover' device -and VF accquiring IP addresses (either same or different) from the DHCP server. +and VF acquiring IP addresses (either same or different) from the DHCP server. This will result in lack of connectivity to the VM. So some tweaks might be needed to these network configuration daemons to make sure that an IP is received only on the 'failover' device. diff --git a/Documentation/networking/netconsole.rst b/Documentation/networking/netconsole.rst index 1f5c4a04027c..dd0518e002f6 100644 --- a/Documentation/networking/netconsole.rst +++ b/Documentation/networking/netconsole.rst @@ -167,7 +167,7 @@ following format which is the same as /dev/kmsg:: Non printable characters in <message text> are escaped using "\xff" notation. If the message contains optional dictionary, verbatim -newline is used as the delimeter. +newline is used as the delimiter. If a message doesn't fit in certain number of bytes (currently 1000), the message is split into multiple fragments by netconsole. These diff --git a/Documentation/networking/nf_conntrack-sysctl.rst b/Documentation/networking/nf_conntrack-sysctl.rst index 49db1d11d7c4..8b1045c3b59e 100644 --- a/Documentation/networking/nf_conntrack-sysctl.rst +++ b/Documentation/networking/nf_conntrack-sysctl.rst @@ -173,7 +173,9 @@ nf_conntrack_sctp_timeout_cookie_echoed - INTEGER (seconds) default 3 nf_conntrack_sctp_timeout_established - INTEGER (seconds) - default 432000 (5 days) + default 210 + + Default is set to (hb_interval * path_max_retrans + rto_max) nf_conntrack_sctp_timeout_shutdown_sent - INTEGER (seconds) default 0.3 @@ -190,12 +192,6 @@ nf_conntrack_sctp_timeout_heartbeat_sent - INTEGER (seconds) This timeout is used to setup conntrack entry on secondary paths. Default is set to hb_interval. -nf_conntrack_sctp_timeout_heartbeat_acked - INTEGER (seconds) - default 210 - - This timeout is used to setup conntrack entry on secondary paths. - Default is set to (hb_interval * path_max_retrans + rto_max) - nf_conntrack_udp_timeout - INTEGER (seconds) default 30 diff --git a/Documentation/networking/page_pool.rst b/Documentation/networking/page_pool.rst index 5db8c263b0c6..30f1344e7cca 100644 --- a/Documentation/networking/page_pool.rst +++ b/Documentation/networking/page_pool.rst @@ -11,7 +11,7 @@ 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 inflight pages, in order to let API user know +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 @@ -19,7 +19,7 @@ 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 inflight state accounting. +release the DMA mapping and in-flight state accounting. Architecture overview ===================== @@ -88,7 +88,7 @@ a page will cause no race conditions is enough. directly into the pool fast cache. * page_pool_release_page(): Unmap the page (if mapped) and account for it on - inflight counters. + in-flight counters. * page_pool_dev_alloc_pages(): Get a page from the page allocator or page_pool caches. diff --git a/Documentation/networking/phonet.rst b/Documentation/networking/phonet.rst index 8668dcbc5e6a..d705cc5b09fc 100644 --- a/Documentation/networking/phonet.rst +++ b/Documentation/networking/phonet.rst @@ -131,7 +131,7 @@ Phonet resources, as follow:: Subscription is similarly cancelled using the SIOCPNDELRESOURCE I/O control request, or when the socket is closed. -Note that no more than one socket can be subcribed to any given +Note that no more than one socket can be subscribed to any given resource at a time. If not, ioctl() will return EBUSY. diff --git a/Documentation/networking/phy.rst b/Documentation/networking/phy.rst index d11329a08984..b7ac4c64cf67 100644 --- a/Documentation/networking/phy.rst +++ b/Documentation/networking/phy.rst @@ -315,7 +315,7 @@ Some of the interface modes are described below: only the port id, but also so-called "extensions". The only documented extension so-far in the specification is the inclusion of timestamps, for PTP-enabled PHYs. This mode isn't compatible with QSGMII, but offers the - same capabilities in terms of link speed and negociation. + same capabilities in terms of link speed and negotiation. ``PHY_INTERFACE_MODE_1000BASEKX`` This is 1000BASE-X as defined by IEEE 802.3 Clause 36 with Clause 73 diff --git a/Documentation/networking/regulatory.rst b/Documentation/networking/regulatory.rst index 16782a95b74a..5e42c8a175c3 100644 --- a/Documentation/networking/regulatory.rst +++ b/Documentation/networking/regulatory.rst @@ -66,7 +66,7 @@ An example:: iw reg set CR This will request the kernel to set the regulatory domain to -the specificied alpha2. The kernel in turn will then ask userspace +the specified alpha2. The kernel in turn will then ask userspace to provide a regulatory domain for the alpha2 specified by the user by sending a uevent. @@ -158,7 +158,7 @@ kmalloc() a structure big enough to hold your regulatory domain structure and you should then fill it with your data. Finally you simply call regulatory_hint() with the regulatory domain structure in it. -Bellow is a simple example, with a regulatory domain cached using the stack. +Below is a simple example, with a regulatory domain cached using the stack. Your implementation may vary (read EEPROM cache instead, for example). Example cache of some regulatory domain:: diff --git a/Documentation/networking/rxrpc.rst b/Documentation/networking/rxrpc.rst index 39494a6ea739..ec1323d92c96 100644 --- a/Documentation/networking/rxrpc.rst +++ b/Documentation/networking/rxrpc.rst @@ -880,8 +880,8 @@ The kernel interface functions are as follows: notify_end_rx can be NULL or it can be used to specify a function to be called when the call changes state to end the Tx phase. This function is - called with the call-state spinlock held to prevent any reply or final ACK - from being delivered first. + called with a spinlock held to prevent the last DATA packet from being + transmitted until the function returns. (#) Receive data from a call:: @@ -1069,7 +1069,7 @@ The kernel interface functions are as follows: This value can be used to determine if the remote client has been restarted as it shouldn't change otherwise. - (#) Set the maxmimum lifespan on a call:: + (#) Set the maximum lifespan on a call:: void rxrpc_kernel_set_max_life(struct socket *sock, struct rxrpc_call *call, diff --git a/Documentation/networking/snmp_counter.rst b/Documentation/networking/snmp_counter.rst index 423d138b5ff3..213637474478 100644 --- a/Documentation/networking/snmp_counter.rst +++ b/Documentation/networking/snmp_counter.rst @@ -980,7 +980,7 @@ How many reply packets of the SYN cookies the TCP stack receives. The MSS decoded from the SYN cookie is invalid. When this counter is updated, the received packet won't be treated as a SYN cookie and the -TcpExtSyncookiesRecv counter wont be updated. +TcpExtSyncookiesRecv counter won't be updated. Challenge ACK ============= @@ -1681,7 +1681,7 @@ RST to nstat-b:: nstatuser@nstat-a:~$ sudo iptables -A INPUT -p tcp --sport 9000 -j DROP -Send 3 SYN repeatly to nstat-b:: +Send 3 SYN repeatedly to nstat-b:: nstatuser@nstat-a:~$ for i in {1..3}; do sudo tcpreplay -i ens3 /tmp/syn_fixcsum.pcap; done diff --git a/Documentation/networking/statistics.rst b/Documentation/networking/statistics.rst index c9aeb70dafa2..551b3cc29a41 100644 --- a/Documentation/networking/statistics.rst +++ b/Documentation/networking/statistics.rst @@ -171,6 +171,7 @@ statistics are supported in the following commands: - `ETHTOOL_MSG_PAUSE_GET` - `ETHTOOL_MSG_FEC_GET` + - `ETHTOOL_MSG_MM_GET` debugfs ------- diff --git a/Documentation/networking/sysfs-tagging.rst b/Documentation/networking/sysfs-tagging.rst index 83647e10c207..65307130ab63 100644 --- a/Documentation/networking/sysfs-tagging.rst +++ b/Documentation/networking/sysfs-tagging.rst @@ -43,6 +43,6 @@ Users of this interface: - current_ns() which returns current's namespace - netlink_ns() which returns a socket's namespace - - initial_ns() which returns the initial namesapce + - initial_ns() which returns the initial namespace - call kobj_ns_exit() when an individual tag is no longer valid diff --git a/Documentation/networking/xdp-rx-metadata.rst b/Documentation/networking/xdp-rx-metadata.rst new file mode 100644 index 000000000000..aac63fc2d08b --- /dev/null +++ b/Documentation/networking/xdp-rx-metadata.rst @@ -0,0 +1,110 @@ +=============== +XDP RX Metadata +=============== + +This document describes how an eXpress Data Path (XDP) program can access +hardware metadata related to a packet using a set of helper functions, +and how it can pass that metadata on to other consumers. + +General Design +============== + +XDP has access to a set of kfuncs to manipulate the metadata in an XDP frame. +Every device driver that wishes to expose additional packet metadata can +implement these kfuncs. The set of kfuncs is declared in ``include/net/xdp.h`` +via ``XDP_METADATA_KFUNC_xxx``. + +Currently, the following kfuncs are supported. In the future, as more +metadata is supported, this set will grow: + +.. kernel-doc:: net/core/xdp.c + :identifiers: bpf_xdp_metadata_rx_timestamp bpf_xdp_metadata_rx_hash + +An XDP program can use these kfuncs to read the metadata into stack +variables for its own consumption. Or, to pass the metadata on to other +consumers, an XDP program can store it into the metadata area carried +ahead of the packet. + +Not all kfuncs have to be implemented by the device driver; when not +implemented, the default ones that return ``-EOPNOTSUPP`` will be used. + +Within an XDP frame, the metadata layout (accessed via ``xdp_buff``) is +as follows:: + + +----------+-----------------+------+ + | headroom | custom metadata | data | + +----------+-----------------+------+ + ^ ^ + | | + xdp_buff->data_meta xdp_buff->data + +An XDP program can store individual metadata items into this ``data_meta`` +area in whichever format it chooses. Later consumers of the metadata +will have to agree on the format by some out of band contract (like for +the AF_XDP use case, see below). + +AF_XDP +====== + +:doc:`af_xdp` use-case implies that there is a contract between the BPF +program that redirects XDP frames into the ``AF_XDP`` socket (``XSK``) and +the final consumer. Thus the BPF program manually allocates a fixed number of +bytes out of metadata via ``bpf_xdp_adjust_meta`` and calls a subset +of kfuncs to populate it. The userspace ``XSK`` consumer computes +``xsk_umem__get_data() - METADATA_SIZE`` to locate that metadata. +Note, ``xsk_umem__get_data`` is defined in ``libxdp`` and +``METADATA_SIZE`` is an application-specific constant (``AF_XDP`` receive +descriptor does _not_ explicitly carry the size of the metadata). + +Here is the ``AF_XDP`` consumer layout (note missing ``data_meta`` pointer):: + + +----------+-----------------+------+ + | headroom | custom metadata | data | + +----------+-----------------+------+ + ^ + | + rx_desc->address + +XDP_PASS +======== + +This is the path where the packets processed by the XDP program are passed +into the kernel. The kernel creates the ``skb`` out of the ``xdp_buff`` +contents. Currently, every driver has custom kernel code to parse +the descriptors and populate ``skb`` metadata when doing this ``xdp_buff->skb`` +conversion, and the XDP metadata is not used by the kernel when building +``skbs``. However, TC-BPF programs can access the XDP metadata area using +the ``data_meta`` pointer. + +In the future, we'd like to support a case where an XDP program +can override some of the metadata used for building ``skbs``. + +bpf_redirect_map +================ + +``bpf_redirect_map`` can redirect the frame to a different device. +Some devices (like virtual ethernet links) support running a second XDP +program after the redirect. However, the final consumer doesn't have +access to the original hardware descriptor and can't access any of +the original metadata. The same applies to XDP programs installed +into devmaps and cpumaps. + +This means that for redirected packets only custom metadata is +currently supported, which has to be prepared by the initial XDP program +before redirect. If the frame is eventually passed to the kernel, the +``skb`` created from such a frame won't have any hardware metadata populated +in its ``skb``. If such a packet is later redirected into an ``XSK``, +that will also only have access to the custom metadata. + +bpf_tail_call +============= + +Adding programs that access metadata kfuncs to the ``BPF_MAP_TYPE_PROG_ARRAY`` +is currently not supported. + +Example +======= + +See ``tools/testing/selftests/bpf/progs/xdp_metadata.c`` and +``tools/testing/selftests/bpf/prog_tests/xdp_metadata.c`` for an example of +BPF program that handles XDP metadata. diff --git a/Documentation/networking/xfrm_device.rst b/Documentation/networking/xfrm_device.rst index c43ace79e320..83abdfef4ec3 100644 --- a/Documentation/networking/xfrm_device.rst +++ b/Documentation/networking/xfrm_device.rst @@ -64,7 +64,7 @@ Callbacks to implement /* from include/linux/netdevice.h */ struct xfrmdev_ops { /* Crypto and Packet offload callbacks */ - int (*xdo_dev_state_add) (struct xfrm_state *x); + int (*xdo_dev_state_add) (struct xfrm_state *x, struct netlink_ext_ack *extack); void (*xdo_dev_state_delete) (struct xfrm_state *x); void (*xdo_dev_state_free) (struct xfrm_state *x); bool (*xdo_dev_offload_ok) (struct sk_buff *skb, @@ -73,7 +73,7 @@ Callbacks to implement /* Solely packet offload callbacks */ void (*xdo_dev_state_update_curlft) (struct xfrm_state *x); - int (*xdo_dev_policy_add) (struct xfrm_policy *x); + int (*xdo_dev_policy_add) (struct xfrm_policy *x, struct netlink_ext_ack *extack); void (*xdo_dev_policy_delete) (struct xfrm_policy *x); void (*xdo_dev_policy_free) (struct xfrm_policy *x); }; diff --git a/Documentation/nvme/feature-and-quirk-policy.rst b/Documentation/nvme/feature-and-quirk-policy.rst new file mode 100644 index 000000000000..c01d836d8e41 --- /dev/null +++ b/Documentation/nvme/feature-and-quirk-policy.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================= +Linux NVMe feature and and quirk policy +======================================= + +This file explains the policy used to decide what is supported by the +Linux NVMe driver and what is not. + + +Introduction +============ + +NVM Express is an open collection of standards and information. + +The Linux NVMe host driver in drivers/nvme/host/ supports devices +implementing the NVM Express (NVMe) family of specifications, which +currently consists of a number of documents: + + - the NVMe Base specification + - various Command Set specifications (e.g. NVM Command Set) + - various Transport specifications (e.g. PCIe, Fibre Channel, RDMA, TCP) + - the NVMe Management Interface specification + +See https://nvmexpress.org/developers/ for the NVMe specifications. + + +Supported features +================== + +NVMe is a large suite of specifications, and contains features that are only +useful or suitable for specific use-cases. It is important to note that Linux +does not aim to implement every feature in the specification. Every additional +feature implemented introduces more code, more maintenance and potentially more +bugs. Hence there is an inherent tradeoff between functionality and +maintainability of the NVMe host driver. + +Any feature implemented in the Linux NVMe host driver must support the +following requirements: + + 1. The feature is specified in a release version of an official NVMe + specification, or in a ratified Technical Proposal (TP) that is + available on NVMe website. Or if it is not directly related to the + on-wire protocol, does not contradict any of the NVMe specifications. + 2. Does not conflict with the Linux architecture, nor the design of the + NVMe host driver. + 3. Has a clear, indisputable value-proposition and a wide consensus across + the community. + +Vendor specific extensions are generally not supported in the NVMe host +driver. + +It is strongly recommended to work with the Linux NVMe and block layer +maintainers and get feedback on specification changes that are intended +to be used by the Linux NVMe host driver in order to avoid conflict at a +later stage. + + +Quirks +====== + +Sometimes implementations of open standards fail to correctly implement parts +of the standards. Linux uses identifier-based quirks to work around such +implementation bugs. The intent of quirks is to deal with widely available +hardware, usually consumer, which Linux users can't use without these quirks. +Typically these implementations are not or only superficially tested with Linux +by the hardware manufacturer. + +The Linux NVMe maintainers decide ad hoc whether to quirk implementations +based on the impact of the problem to Linux users and how it impacts +maintainability of the driver. In general quirks are a last resort, if no +firmware updates or other workarounds are available from the vendor. + +Quirks will not be added to the Linux kernel for hardware that isn't available +on the mass market. Hardware that fails qualification for enterprise Linux +distributions, ChromeOS, Android or other consumers of the Linux kernel +should be fixed before it is shipped instead of relying on Linux quirks. diff --git a/Documentation/peci/index.rst b/Documentation/peci/index.rst index 989de10416e7..930e75217c33 100644 --- a/Documentation/peci/index.rst +++ b/Documentation/peci/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0-only -==================== -Linux PECI Subsystem -==================== +============== +PECI Subsystem +============== .. toctree:: diff --git a/Documentation/power/power_supply_class.rst b/Documentation/power/power_supply_class.rst index c04fabee0a58..da8e275a14ff 100644 --- a/Documentation/power/power_supply_class.rst +++ b/Documentation/power/power_supply_class.rst @@ -40,8 +40,8 @@ kind of power supply, and can process/present them to a user in consistent manner. Results for different power supplies and machines are also directly comparable. -See drivers/power/supply/ds2760_battery.c and drivers/power/supply/pda_power.c -for the example how to declare and handle attributes. +See drivers/power/supply/ds2760_battery.c for the example how to declare +and handle attributes. Units diff --git a/Documentation/power/suspend-and-interrupts.rst b/Documentation/power/suspend-and-interrupts.rst index 4cda6617709a..dfbace2f4600 100644 --- a/Documentation/power/suspend-and-interrupts.rst +++ b/Documentation/power/suspend-and-interrupts.rst @@ -67,7 +67,7 @@ That may involve turning on a special signal handling logic within the platform during system sleep so as to trigger a system wakeup when needed. For example, the platform may include a dedicated interrupt controller used specifically for handling system wakeup events. Then, if a given interrupt line is supposed to -wake up the system from sleep sates, the corresponding input of that interrupt +wake up the system from sleep states, the corresponding input of that interrupt controller needs to be enabled to receive signals from the line in question. After wakeup, it generally is better to disable that input to prevent the dedicated controller from triggering interrupts unnecessarily. diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst index ba4667ab396b..9739b88463a5 100644 --- a/Documentation/process/botching-up-ioctls.rst +++ b/Documentation/process/botching-up-ioctls.rst @@ -41,7 +41,7 @@ will need to add a 32-bit compat layer: structures to the kernel, or if the kernel checks the structure size, which e.g. the drm core does. - * Pointers are __u64, cast from/to a uintprt_t on the userspace side and + * Pointers are __u64, cast from/to a uintptr_t on the userspace side and from/to a void __user * in the kernel. Try really hard not to delay this conversion or worse, fiddle the raw __u64 through your code since that diminishes the checking tools like sparse can provide. The macro diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index c8fd53a11a20..f91b8441f2ef 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -346,3 +346,29 @@ struct_size() and flex_array_size() helpers:: instance->count = count; memcpy(instance->items, source, flex_array_size(instance, items, instance->count)); + +There are two special cases of replacement where the DECLARE_FLEX_ARRAY() +helper needs to be used. (Note that it is named __DECLARE_FLEX_ARRAY() for +use in UAPI headers.) Those cases are when the flexible array is either +alone in a struct or is part of a union. These are disallowed by the C99 +specification, but for no technical reason (as can be seen by both the +existing use of such arrays in those places and the work-around that +DECLARE_FLEX_ARRAY() uses). For example, to convert this:: + + struct something { + ... + union { + struct type1 one[0]; + struct type2 two[0]; + }; + }; + +The helper must be used:: + + struct something { + ... + union { + DECLARE_FLEX_ARRAY(struct type1, one); + DECLARE_FLEX_ARRAY(struct type2, two); + }; + }; diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst index fc2c46f3f82d..471e1f93fa09 100644 --- a/Documentation/process/email-clients.rst +++ b/Documentation/process/email-clients.rst @@ -350,3 +350,23 @@ although tab2space problem can be solved with external editor. Another problem is that Gmail will base64-encode any message that has a non-ASCII character. That includes things like European names. + +Proton Mail +*********** + +Proton Mail has a "feature" where it looks up keys using Web Key Directory +(WKD) and encrypts mail to any recipients for which it finds a key. +Kernel.org publishes the WKD for all developers who have kernel.org accounts. +As a result, emails sent using Proton Mail to kernel.org addresses will be +encrypted. +Unfortunately, Proton Mail does not provide a mechanism to disable the +automatic encryption, viewing it as a privacy feature. +The automatic encryption feature is also enabled for mail sent via the Proton +Mail Bridge, so this affects all outgoing messages, including patches sent with +``git send-email``. +Encrypted mail adds unnecessary friction, as other developers may not have mail +clients, or tooling, configured for use with encrypted mail and some mail +clients may encrypt responses to encrypted mail for all recipients, including +the mailing lists. +Unless a way to disable this "feature" is introduced, Proton Mail is unsuited +to kernel development. diff --git a/Documentation/process/embargoed-hardware-issues.rst b/Documentation/process/embargoed-hardware-issues.rst index b6b4481e2474..df978127f2d7 100644 --- a/Documentation/process/embargoed-hardware-issues.rst +++ b/Documentation/process/embargoed-hardware-issues.rst @@ -251,6 +251,7 @@ 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> + Samsung Javier González <javier.gonz@samsung.com> Microsoft James Morris <jamorris@linux.microsoft.com> VMware diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst index 1fa5ab8754d3..4a75686d35ab 100644 --- a/Documentation/process/maintainer-netdev.rst +++ b/Documentation/process/maintainer-netdev.rst @@ -2,9 +2,9 @@ .. _netdev-FAQ: -========== -netdev FAQ -========== +============================= +Networking subsystem (netdev) +============================= tl;dr ----- @@ -15,14 +15,15 @@ tl;dr - don't repost your patches within one 24h period - reverse xmas tree -What is netdev? ---------------- -It is a mailing list for all network-related Linux stuff. This +netdev +------ + +netdev is a mailing list for all network-related Linux stuff. This includes anything found under net/ (i.e. core code like IPv6) and drivers/net (i.e. hardware specific drivers) in the Linux source tree. Note that some subsystems (e.g. wireless drivers) which have a high -volume of traffic have their own specific mailing lists. +volume of traffic have their own specific mailing lists and trees. The netdev list is managed (like many other Linux mailing lists) through VGER (http://vger.kernel.org/) with archives available at @@ -32,32 +33,10 @@ Aside from subsystems like those mentioned above, all network-related Linux development (i.e. RFC, review, comments, etc.) takes place on netdev. -How do the changes posted to netdev make their way into Linux? --------------------------------------------------------------- -There are always two trees (git repositories) in play. Both are -driven by David Miller, the main network maintainer. There is the -``net`` tree, and the ``net-next`` tree. As you can probably guess from -the names, the ``net`` tree is for fixes to existing code already in the -mainline tree from Linus, and ``net-next`` is where the new code goes -for the future release. You can find the trees here: - -- https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net.git -- https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-next.git - -How do I indicate which tree (net vs. net-next) my patch should be in? ----------------------------------------------------------------------- -To help maintainers and CI bots you should explicitly mark which tree -your patch is targeting. Assuming that you use git, use the prefix -flag:: - - git format-patch --subject-prefix='PATCH net-next' start..finish +Development cycle +----------------- -Use ``net`` instead of ``net-next`` (always lower case) in the above for -bug-fix ``net`` content. - -How often do changes from these trees make it to the mainline Linus tree? -------------------------------------------------------------------------- -To understand this, you need to know a bit of background information on +Here is a bit of background information on the cadence of Linux development. Each new release starts off with a two week "merge window" where the main maintainers feed their new stuff to Linus for merging into the mainline tree. After the two weeks, the @@ -69,9 +48,33 @@ rc2 is released. This repeats on a roughly weekly basis until rc7 state of churn), and a week after the last vX.Y-rcN was done, the official vX.Y is released. -Relating that to netdev: At the beginning of the 2-week merge window, -the ``net-next`` tree will be closed - no new changes/features. The -accumulated new content of the past ~10 weeks will be passed onto +To find out where we are now in the cycle - load the mainline (Linus) +page here: + + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + +and note the top of the "tags" section. If it is rc1, it is early in +the dev cycle. If it was tagged rc7 a week ago, then a release is +probably imminent. If the most recent tag is a final release tag +(without an ``-rcN`` suffix) - we are most likely in a merge window +and ``net-next`` is closed. + +git trees and patch flow +------------------------ + +There are two networking trees (git repositories) in play. Both are +driven by David Miller, the main network maintainer. There is the +``net`` tree, and the ``net-next`` tree. As you can probably guess from +the names, the ``net`` tree is for fixes to existing code already in the +mainline tree from Linus, and ``net-next`` is where the new code goes +for the future release. You can find the trees here: + +- https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net.git +- https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-next.git + +Relating that to kernel development: At the beginning of the 2-week +merge window, the ``net-next`` tree will be closed - no new changes/features. +The accumulated new content of the past ~10 weeks will be passed onto mainline/Linus via a pull request for vX.Y -- at the same time, the ``net`` tree will start accumulating fixes for this pulled content relating to vX.Y @@ -103,22 +106,14 @@ focus for ``net`` is on stabilization and bug fixes. Finally, the vX.Y gets released, and the whole cycle starts over. -So where are we now in this cycle? ----------------------------------- +netdev patch review +------------------- -Load the mainline (Linus) page here: +Patch status +~~~~~~~~~~~~ - https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git - -and note the top of the "tags" section. If it is rc1, it is early in -the dev cycle. If it was tagged rc7 a week ago, then a release is -probably imminent. If the most recent tag is a final release tag -(without an ``-rcN`` suffix) - we are most likely in a merge window -and ``net-next`` is closed. - -How can I tell the status of a patch I've sent? ------------------------------------------------ -Start by looking at the main patchworks queue for netdev: +Status of a patch can be checked by looking at the main patchwork +queue for netdev: https://patchwork.kernel.org/project/netdevbpf/list/ @@ -127,73 +122,141 @@ patch. 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. -How long before my patch is accepted? -------------------------------------- -Generally speaking, the patches get triaged quickly (in less than -48h). But be patient, if your patch is active in patchwork (i.e. it's -listed on the project's patch list) the chances it was missed are close to zero. -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. +Updating patch status +~~~~~~~~~~~~~~~~~~~~~ -Should I directly update patchwork state of my own patches? ------------------------------------------------------------ It may be tempting to help the maintainers and update the state of your -own patches when you post a new version or spot a bug. Please do not do that. +own patches when you post a new version or spot a bug. Please **do not** +do that. Interfering with the patch status on patchwork will only cause confusion. Leave it to the maintainer to figure out what is the most recent and current version that should be applied. If there is any doubt, the maintainer will reply and ask what should be done. -How do I divide my work into patches? -------------------------------------- +Review timelines +~~~~~~~~~~~~~~~~ -Put yourself in the shoes of the reviewer. Each patch is read separately -and therefore should constitute a comprehensible step towards your stated -goal. +Generally speaking, the patches get triaged quickly (in less than +48h). But be patient, if your patch is active in patchwork (i.e. it's +listed on the project's patch list) the chances it was missed are close to zero. +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. -Avoid sending series longer than 15 patches. Larger series takes longer -to review as reviewers will defer looking at it until they find a large -chunk of time. A small series can be reviewed in a short time, so Maintainers -just do it. As a result, a sequence of smaller series gets merged quicker and -with better review coverage. Re-posting large series also increases the mailing -list traffic. +Partial resends +~~~~~~~~~~~~~~~ -I made changes to only a few patches in a patch series should I resend only those changed? ------------------------------------------------------------------------------------------- -No, please resend the entire patch series and make sure you do number your +Please always resend the entire patch series and make sure you do number your patches such that it is clear this is the latest and greatest set of patches -that can be applied. - -I have received review feedback, when should I post a revised version of the patches? -------------------------------------------------------------------------------------- -Allow at least 24 hours to pass between postings. This will ensure reviewers -from all geographical locations have a chance to chime in. Do not wait -too long (weeks) between postings either as it will make it harder for reviewers -to recall all the context. +that can be applied. Do not try to resend just the patches which changed. -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. +Handling misapplied patches +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -I submitted multiple versions of a patch series and it looks like a version other than the last one has been accepted, what should I do? ----------------------------------------------------------------------------------------------------------------------------------------- +Occasionally a patch series gets applied before receiving critical feedback, +or the wrong version of a series gets applied. There is no revert possible, once it is pushed out, it stays like that. Please send incremental versions on top of what has been merged in order to fix the patches the way they would look like if your latest patch series was to be merged. -Are there special rules regarding stable submissions on netdev? ---------------------------------------------------------------- +Stable tree +~~~~~~~~~~~ + While it used to be the case that netdev submissions were not supposed to carry explicit ``CC: stable@vger.kernel.org`` tags that is no longer the case today. Please follow the standard stable rules in :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`, and make sure you include appropriate Fixes tags! -Is the comment style convention different for the networking content? ---------------------------------------------------------------------- -Yes, in a largely trivial way. Instead of this:: +Security fixes +~~~~~~~~~~~~~~ + +Do not email netdev maintainers directly if you think you discovered +a bug that might have possible security implications. +The current netdev maintainer has consistently requested that +people use the mailing lists and not reach out directly. If you aren't +OK with that, then perhaps consider mailing security@kernel.org or +reading about http://oss-security.openwall.org/wiki/mailing-lists/distros +as possible alternative mechanisms. + + +Co-posting changes to user space components +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +User space code exercising kernel features should be posted +alongside kernel patches. This gives reviewers a chance to see +how any new interface is used and how well it works. + +When user space tools reside in the kernel repo itself all changes +should generally come as one series. If series becomes too large +or the user space project is not reviewed on netdev include a link +to a public repo where user space patches can be seen. + +In case user space tooling lives in a separate repository but is +reviewed on netdev (e.g. patches to ``iproute2`` tools) kernel and +user space patches should form separate series (threads) when posted +to the mailing list, e.g.:: + + [PATCH net-next 0/3] net: some feature cover letter + └─ [PATCH net-next 1/3] net: some feature prep + └─ [PATCH net-next 2/3] net: some feature do it + └─ [PATCH net-next 3/3] selftest: net: some feature + + [PATCH iproute2-next] ip: add support for some feature + +Posting as one thread is discouraged because it confuses patchwork +(as of patchwork 2.2.2). + +Preparing changes +----------------- + +Attention to detail is important. Re-read your own work as if you were the +reviewer. You can start with using ``checkpatch.pl``, perhaps even with +the ``--strict`` flag. But do not be mindlessly robotic in doing so. +If your change is a bug fix, make sure your commit log indicates the +end-user visible symptom, the underlying reason as to why it happens, +and then if necessary, explain why the fix proposed is the best way to +get things done. Don't mangle whitespace, and as is common, don't +mis-indent function arguments that span multiple lines. If it is your +first patch, mail it to yourself so you can test apply it to an +unpatched tree to confirm infrastructure didn't mangle it. + +Finally, go back and read +:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` +to be sure you are not repeating some common mistake documented there. + +Indicating target tree +~~~~~~~~~~~~~~~~~~~~~~ + +To help maintainers and CI bots you should explicitly mark which tree +your patch is targeting. Assuming that you use git, use the prefix +flag:: + + git format-patch --subject-prefix='PATCH net-next' start..finish + +Use ``net`` instead of ``net-next`` (always lower case) in the above for +bug-fix ``net`` content. + +Dividing work into patches +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Put yourself in the shoes of the reviewer. Each patch is read separately +and therefore should constitute a comprehensible step towards your stated +goal. + +Avoid sending series longer than 15 patches. Larger series takes longer +to review as reviewers will defer looking at it until they find a large +chunk of time. A small series can be reviewed in a short time, so Maintainers +just do it. As a result, a sequence of smaller series gets merged quicker and +with better review coverage. Re-posting large series also increases the mailing +list traffic. + +Multi-line comments +~~~~~~~~~~~~~~~~~~~ + +Comment style convention is slightly different for networking and most of +the tree. Instead of this:: /* * foobar blah blah blah @@ -206,8 +269,8 @@ it is requested that you make it look like this:: * another line of text */ -What is "reverse xmas tree"? ----------------------------- +Local variable ordering ("reverse xmas tree", "RCS") +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Netdev has a convention for ordering local variables in functions. Order the variable declaration lines longest to shortest, e.g.:: @@ -219,21 +282,31 @@ Order the variable declaration lines longest to shortest, e.g.:: If there are dependencies between the variables preventing the ordering move the initialization out of line. -I am working in existing code which uses non-standard formatting. Which formatting should I use? ------------------------------------------------------------------------------------------------- -Make your code follow the most recent guidelines, so that eventually all code +Format precedence +~~~~~~~~~~~~~~~~~ + +When working in existing code which uses nonstandard formatting make +your code follow the most recent guidelines, so that eventually all code in the domain of netdev is in the preferred format. -I found a bug that might have possible security implications or similar. Should I mail the main netdev maintainer off-list? ---------------------------------------------------------------------------------------------------------------------------- -No. The current netdev maintainer has consistently requested that -people use the mailing lists and not reach out directly. If you aren't -OK with that, then perhaps consider mailing security@kernel.org or -reading about http://oss-security.openwall.org/wiki/mailing-lists/distros -as possible alternative mechanisms. +Resending after review +~~~~~~~~~~~~~~~~~~~~~~ + +Allow at least 24 hours to pass between postings. This will ensure reviewers +from all geographical locations have a chance to chime in. Do not wait +too long (weeks) between postings either as it will make it harder for reviewers +to recall all the context. + +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. + +Testing +------- + +Expected level of testing +~~~~~~~~~~~~~~~~~~~~~~~~~ -What level of testing is expected before I submit my change? ------------------------------------------------------------- At the very minimum your changes must survive an ``allyesconfig`` and an ``allmodconfig`` build with ``W=1`` set without new warnings or failures. @@ -244,86 +317,42 @@ and the patch series contains a set of kernel selftest for You are expected to test your changes on top of the relevant networking tree (``net`` or ``net-next``) and not e.g. a stable tree or ``linux-next``. -How do I post corresponding changes to user space components? -------------------------------------------------------------- -User space code exercising kernel features should be posted -alongside kernel patches. This gives reviewers a chance to see -how any new interface is used and how well it works. - -When user space tools reside in the kernel repo itself all changes -should generally come as one series. If series becomes too large -or the user space project is not reviewed on netdev include a link -to a public repo where user space patches can be seen. - -In case user space tooling lives in a separate repository but is -reviewed on netdev (e.g. patches to ``iproute2`` tools) kernel and -user space patches should form separate series (threads) when posted -to the mailing list, e.g.:: - - [PATCH net-next 0/3] net: some feature cover letter - └─ [PATCH net-next 1/3] net: some feature prep - └─ [PATCH net-next 2/3] net: some feature do it - └─ [PATCH net-next 3/3] selftest: net: some feature - - [PATCH iproute2-next] ip: add support for some feature - -Posting as one thread is discouraged because it confuses patchwork -(as of patchwork 2.2.2). - -Can I reproduce the checks from patchwork on my local machine? --------------------------------------------------------------- +patchwork checks +~~~~~~~~~~~~~~~~ Checks in patchwork are mostly simple wrappers around existing kernel scripts, the sources are available at: https://github.com/kuba-moo/nipa/tree/master/tests -Running all the builds and checks locally is a pain, can I post my patches and have the patchwork bot validate them? --------------------------------------------------------------------------------------------------------------------- - -No, you must ensure that your patches are ready by testing them locally +**Do not** post your patches just to run them through the checks. +You must ensure that your patches are ready by testing them locally before posting to the mailing list. The patchwork build bot instance gets overloaded very easily and netdev@vger really doesn't need more traffic if we can help it. -netdevsim is great, can I extend it for my out-of-tree tests? -------------------------------------------------------------- +netdevsim +~~~~~~~~~ -No, ``netdevsim`` is a test vehicle solely for upstream tests. -(Please add your tests under ``tools/testing/selftests/``.) +``netdevsim`` is a test driver which can be used to exercise driver +configuration APIs without requiring capable hardware. +Mock-ups and tests based on ``netdevsim`` are strongly encouraged when +adding new APIs, but ``netdevsim`` in itself is **not** considered +a use case/user. You must also implement the new APIs in a real driver. -We also give no guarantees that ``netdevsim`` won't change in the future +We give no guarantees that ``netdevsim`` won't change in the future in a way which would break what would normally be considered uAPI. -Is netdevsim considered a "user" of an API? -------------------------------------------- - -Linux kernel has a long standing rule that no API should be added unless -it has a real, in-tree user. Mock-ups and tests based on ``netdevsim`` are -strongly encouraged when adding new APIs, but ``netdevsim`` in itself -is **not** considered a use case/user. - -Any other tips to help ensure my net/net-next patch gets OK'd? --------------------------------------------------------------- -Attention to detail. Re-read your own work as if you were the -reviewer. You can start with using ``checkpatch.pl``, perhaps even with -the ``--strict`` flag. But do not be mindlessly robotic in doing so. -If your change is a bug fix, make sure your commit log indicates the -end-user visible symptom, the underlying reason as to why it happens, -and then if necessary, explain why the fix proposed is the best way to -get things done. Don't mangle whitespace, and as is common, don't -mis-indent function arguments that span multiple lines. If it is your -first patch, mail it to yourself so you can test apply it to an -unpatched tree to confirm infrastructure didn't mangle it. - -Finally, go back and read -:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` -to be sure you are not repeating some common mistake documented there. +``netdevsim`` is reserved for use by upstream tests only, so any +new ``netdevsim`` features must be accompanied by selftests under +``tools/testing/selftests/``. -My company uses peer feedback in employee performance reviews. Can I ask netdev maintainers for feedback? ---------------------------------------------------------------------------------------------------------- +Testimonials / feedback +----------------------- -Yes, especially if you spend significant amount of time reviewing code +Some companies use peer feedback in employee performance reviews. +Please feel free to request feedback from netdev maintainers, +especially if you spend significant amount of time reviewing code and go out of your way to improve shared infrastructure. The feedback must be requested by you, the contributor, and will always diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index 40bfbd3b7648..f5277993b195 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -60,36 +60,18 @@ establish the integrity of the Linux kernel itself. PGP tools ========= -Use GnuPG v2 ------------- +Use GnuPG 2.2 or later +---------------------- Your distro should already have GnuPG installed by default, you just -need to verify that you are using version 2.x and not the legacy 1.4 -release -- many distributions still package both, with the default -``gpg`` command invoking GnuPG v.1. To check, run:: +need to verify that you are using a reasonably recent version of it. +To check, run:: $ gpg --version | head -n1 -If you see ``gpg (GnuPG) 1.4.x``, then you are using GnuPG v.1. Try the -``gpg2`` command (if you don't have it, you may need to install the -gnupg2 package):: - - $ gpg2 --version | head -n1 - -If you see ``gpg (GnuPG) 2.x.x``, then you are good to go. This guide -will assume you have the version 2.2 of GnuPG (or later). If you are -using version 2.0 of GnuPG, then some of the commands in this guide will -not work, and you should consider installing the latest 2.2 version of -GnuPG. Versions of gnupg-2.1.11 and later should be compatible for the -purposes of this guide as well. - -If you have both ``gpg`` and ``gpg2`` commands, you should make sure you -are always using GnuPG v2, not the legacy version. You can enforce this -by setting the appropriate alias:: - - $ alias gpg=gpg2 - -You can put that in your ``.bashrc`` to make sure it's always the case. +If you have version 2.2 or above, then you are good to go. If you have a +version that is prior than 2.2, then some commands from this guide may +not work. Configure gpg-agent options ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -150,9 +132,9 @@ PGP defines four capabilities that a key can have: The key with the **[C]** capability is often called the "master" key, but this terminology is misleading because it implies that the Certify key can be used in place of any of other subkey on the same chain (like -a physical "master key" can be used to open the locks made for other -keys). Since this is not the case, this guide will refer to it as "the -Certify key" to avoid any ambiguity. +a physical "master key" can be used to open locks made for other keys). +Since this is not the case, this guide will refer to it as "the Certify +key" to avoid any ambiguity. It is critical to fully understand the following: @@ -186,10 +168,10 @@ If you used the default parameters when generating your key, then that is what you will have. You can verify by running ``gpg --list-secret-keys``, for example:: - sec rsa2048 2018-01-23 [SC] [expires: 2020-01-23] + sec ed25519 2022-12-20 [SC] [expires: 2024-12-19] 000000000000000000000000AAAABBBBCCCCDDDD uid [ultimate] Alice Dev <adev@kernel.org> - ssb rsa2048 2018-01-23 [E] [expires: 2020-01-23] + ssb cv25519 2022-12-20 [E] [expires: 2024-12-19] The long line under the ``sec`` entry is your key fingerprint -- whenever you see ``[fpr]`` in the examples below, that 40-character @@ -219,18 +201,9 @@ separate signing subkey:: .. note:: ECC support in GnuPG - GnuPG 2.1 and later has full support for Elliptic Curve - Cryptography, with ability to combine ECC subkeys with traditional - RSA keys. The main upside of ECC cryptography is that it is much - faster computationally and creates much smaller signatures when - compared byte for byte with 2048+ bit RSA keys. Unless you plan on - using a smartcard device that does not support ECC operations, we - recommend that you create an ECC signing subkey for your kernel - work. - - Note, that if you plan to use a hardware device that does not + Note, that if you intend to use a hardware token that does not support ED25519 ECC keys, you should choose "nistp256" instead or - "ed25519." + "ed25519." See the section below on recommended hardware devices. Back up your Certify key for disaster recovery @@ -336,13 +309,13 @@ First, identify the keygrip of your Certify key:: The output will be something like this:: - pub rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + pub ed25519 2022-12-20 [SC] [expires: 2022-12-19] 000000000000000000000000AAAABBBBCCCCDDDD Keygrip = 1111000000000000000000000000000000000000 uid [ultimate] Alice Dev <adev@kernel.org> - sub rsa2048 2018-01-24 [E] [expires: 2020-01-24] + sub cv25519 2022-12-20 [E] [expires: 2022-12-19] Keygrip = 2222000000000000000000000000000000000000 - sub ed25519 2018-01-24 [S] + sub ed25519 2022-12-20 [S] Keygrip = 3333000000000000000000000000000000000000 Find the keygrip entry that is beneath the ``pub`` line (right under the @@ -365,14 +338,14 @@ Now, if you issue the ``--list-secret-keys`` command, it will show that the Certify key is missing (the ``#`` indicates it is not available):: $ gpg --list-secret-keys - sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19] 000000000000000000000000AAAABBBBCCCCDDDD uid [ultimate] Alice Dev <adev@kernel.org> - ssb rsa2048 2018-01-24 [E] [expires: 2020-01-24] - ssb ed25519 2018-01-24 [S] + ssb cv25519 2022-12-20 [E] [expires: 2024-12-19] + ssb ed25519 2022-12-20 [S] You should also remove any ``secring.gpg`` files in the ``~/.gnupg`` -directory, which are left over from earlier versions of GnuPG. +directory, which may be left over from previous versions of GnuPG. If you don't have the "private-keys-v1.d" directory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -437,8 +410,7 @@ functionality. There are several options available: U2F, among others, and now finally supports NISTP and ED25519 ECC keys. -`LWN has a good review`_ of some of the above models, as well as several -others. Your choice will depend on cost, shipping availability in your +Your choice will depend on cost, shipping availability in your geographical region, and open/proprietary hardware considerations. .. note:: @@ -451,7 +423,6 @@ geographical region, and open/proprietary hardware considerations. .. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nkpr2-nitrokey-pro-2-3 .. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/ .. _Gnuk: https://www.fsij.org/doc-gnuk/ -.. _`LWN has a good review`: https://lwn.net/Articles/736231/ .. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html Configure your smartcard device @@ -509,11 +480,11 @@ passphrase and the admin PIN of the card for most operations:: Secret subkeys are available. - pub rsa2048/AAAABBBBCCCCDDDD - created: 2018-01-23 expires: 2020-01-23 usage: SC + pub ed25519/AAAABBBBCCCCDDDD + created: 2022-12-20 expires: 2024-12-19 usage: SC trust: ultimate validity: ultimate - ssb rsa2048/1111222233334444 - created: 2018-01-23 expires: never usage: E + ssb cv25519/1111222233334444 + created: 2022-12-20 expires: never usage: E ssb ed25519/5555666677778888 created: 2017-12-07 expires: never usage: S [ultimate] (1). Alice Dev <adev@kernel.org> @@ -577,11 +548,11 @@ If you perform ``--list-secret-keys`` now, you will see a subtle difference in the output:: $ gpg --list-secret-keys - sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19] 000000000000000000000000AAAABBBBCCCCDDDD uid [ultimate] Alice Dev <adev@kernel.org> - ssb> rsa2048 2018-01-24 [E] [expires: 2020-01-24] - ssb> ed25519 2018-01-24 [S] + ssb> cv25519 2022-12-20 [E] [expires: 2024-12-19] + ssb> ed25519 2022-12-20 [S] The ``>`` in the ``ssb>`` output indicates that the subkey is only available on the smartcard. If you go back into your secret keys @@ -644,7 +615,7 @@ run:: You can also use a specific date if that is easier to remember (e.g. your birthday, January 1st, or Canada Day):: - $ gpg --quick-set-expire [fpr] 2020-07-01 + $ gpg --quick-set-expire [fpr] 2025-07-01 Remember to send the updated key back to keyservers:: @@ -707,12 +678,6 @@ should be used (``[fpr]`` is the fingerprint of your key):: $ git config --global user.signingKey [fpr] -**IMPORTANT**: If you have a distinct ``gpg2`` command, then you should -tell git to always use it instead of the legacy ``gpg`` from version 1:: - - $ git config --global gpg.program gpg2 - $ git config --global gpgv.program gpgv2 - How to work with signed tags ---------------------------- @@ -751,13 +716,6 @@ If you are verifying someone else's git tag, then you will need to import their PGP key. Please refer to the ":ref:`verify_identities`" section below. -.. note:: - - If you get "``gpg: Can't check signature: unknown pubkey - algorithm``" error, you need to tell git to use gpgv2 for - verification, so it properly processes signatures made by ECC keys. - See instructions at the start of this section. - Configure git to always sign annotated tags ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/s390/pci.rst b/Documentation/s390/pci.rst index 8157f0cddbc2..a1a72a47dc96 100644 --- a/Documentation/s390/pci.rst +++ b/Documentation/s390/pci.rst @@ -51,7 +51,7 @@ Entries specific to zPCI functions and entries that hold zPCI information. The slot entries are set up using the function identifier (FID) of the PCI function. The format depicted as XXXXXXXX above is 8 hexadecimal digits - with 0 padding and lower case hexadecimal digitis. + with 0 padding and lower case hexadecimal digits. - /sys/bus/pci/slots/XXXXXXXX/power @@ -66,7 +66,7 @@ Entries specific to zPCI functions and entries that hold zPCI information. - function_handle Low-level identifier used for a configured PCI function. - It might be useful for debuging. + It might be useful for debugging. - pchid Model-dependent location of the I/O adapter. diff --git a/Documentation/s390/vfio-ccw.rst b/Documentation/s390/vfio-ccw.rst index ea928a3806f4..37026fa18179 100644 --- a/Documentation/s390/vfio-ccw.rst +++ b/Documentation/s390/vfio-ccw.rst @@ -176,7 +176,7 @@ The process of how these work together. Use the 'mdev_create' sysfs file, we need to manually create one (and only one for our case) mediated device. 3. vfio_mdev.ko drives the mediated ccw device. - vfio_mdev is also the vfio device drvier. It will probe the mdev and + vfio_mdev is also the vfio device driver. It will probe the mdev and add it to an iommu_group and a vfio_group. Then we could pass through the mdev to a guest. @@ -219,8 +219,8 @@ values may occur: The operation was successful. ``-EOPNOTSUPP`` - The orb specified transport mode or an unidentified IDAW format, or the - scsw specified a function other than the start function. + The ORB specified transport mode or the + SCSW specified a function other than the start function. ``-EIO`` A request was issued while the device was not in a state ready to accept diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst index b430d856056a..3170747226f6 100644 --- a/Documentation/scheduler/index.rst +++ b/Documentation/scheduler/index.rst @@ -1,6 +1,6 @@ -=============== -Linux Scheduler -=============== +========= +Scheduler +========= .. toctree:: :maxdepth: 1 @@ -15,6 +15,7 @@ Linux Scheduler sched-capacity sched-energy schedutil + sched-util-clamp sched-nice-design sched-rt-group sched-stats diff --git a/Documentation/scheduler/sched-util-clamp.rst b/Documentation/scheduler/sched-util-clamp.rst new file mode 100644 index 000000000000..74d5b7c6431d --- /dev/null +++ b/Documentation/scheduler/sched-util-clamp.rst @@ -0,0 +1,741 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +Utilization Clamping +==================== + +1. Introduction +=============== + +Utilization clamping, also known as util clamp or uclamp, is a scheduler +feature that allows user space to help in managing the performance requirement +of tasks. It was introduced in v5.3 release. The CGroup support was merged in +v5.4. + +Uclamp is a hinting mechanism that allows the scheduler to understand the +performance requirements and restrictions of the tasks, thus it helps the +scheduler to make a better decision. And when schedutil cpufreq governor is +used, util clamp will influence the CPU frequency selection as well. + +Since the scheduler and schedutil are both driven by PELT (util_avg) signals, +util clamp acts on that to achieve its goal by clamping the signal to a certain +point; hence the name. That is, by clamping utilization we are making the +system run at a certain performance point. + +The right way to view util clamp is as a mechanism to make request or hint on +performance constraints. It consists of two tunables: + + * UCLAMP_MIN, which sets the lower bound. + * UCLAMP_MAX, which sets the upper bound. + +These two bounds will ensure a task will operate within this performance range +of the system. UCLAMP_MIN implies boosting a task, while UCLAMP_MAX implies +capping a task. + +One can tell the system (scheduler) that some tasks require a minimum +performance point to operate at to deliver the desired user experience. Or one +can tell the system that some tasks should be restricted from consuming too +much resources and should not go above a specific performance point. Viewing +the uclamp values as performance points rather than utilization is a better +abstraction from user space point of view. + +As an example, a game can use util clamp to form a feedback loop with its +perceived Frames Per Second (FPS). It can dynamically increase the minimum +performance point required by its display pipeline to ensure no frame is +dropped. It can also dynamically 'prime' up these tasks if it knows in the +coming few hundred milliseconds a computationally intensive scene is about to +happen. + +On mobile hardware where the capability of the devices varies a lot, this +dynamic feedback loop offers a great flexibility to ensure best user experience +given the capabilities of any system. + +Of course a static configuration is possible too. The exact usage will depend +on the system, application and the desired outcome. + +Another example is in Android where tasks are classified as background, +foreground, top-app, etc. Util clamp can be used to constrain how much +resources background tasks are consuming by capping the performance point they +can run at. This constraint helps reserve resources for important tasks, like +the ones belonging to the currently active app (top-app group). Beside this +helps in limiting how much power they consume. This can be more obvious in +heterogeneous systems (e.g. Arm big.LITTLE); the constraint will help bias the +background tasks to stay on the little cores which will ensure that: + + 1. The big cores are free to run top-app tasks immediately. top-app + tasks are the tasks the user is currently interacting with, hence + the most important tasks in the system. + 2. They don't run on a power hungry core and drain battery even if they + are CPU intensive tasks. + +.. note:: + **little cores**: + CPUs with capacity < 1024 + + **big cores**: + CPUs with capacity = 1024 + +By making these uclamp performance requests, or rather hints, user space can +ensure system resources are used optimally to deliver the best possible user +experience. + +Another use case is to help with **overcoming the ramp up latency inherit in +how scheduler utilization signal is calculated**. + +On the other hand, a busy task for instance that requires to run at maximum +performance point will suffer a delay of ~200ms (PELT HALFIFE = 32ms) for the +scheduler to realize that. This is known to affect workloads like gaming on +mobile devices where frames will drop due to slow response time to select the +higher frequency required for the tasks to finish their work in time. Setting +UCLAMP_MIN=1024 will ensure such tasks will always see the highest performance +level when they start running. + +The overall visible effect goes beyond better perceived user +experience/performance and stretches to help achieve a better overall +performance/watt if used effectively. + +User space can form a feedback loop with the thermal subsystem too to ensure +the device doesn't heat up to the point where it will throttle. + +Both SCHED_NORMAL/OTHER and SCHED_FIFO/RR honour uclamp requests/hints. + +In the SCHED_FIFO/RR case, uclamp gives the option to run RT tasks at any +performance point rather than being tied to MAX frequency all the time. Which +can be useful on general purpose systems that run on battery powered devices. + +Note that by design RT tasks don't have per-task PELT signal and must always +run at a constant frequency to combat undeterministic DVFS rampup delays. + +Note that using schedutil always implies a single delay to modify the frequency +when an RT task wakes up. This cost is unchanged by using uclamp. Uclamp only +helps picking what frequency to request instead of schedutil always requesting +MAX for all RT tasks. + +See :ref:`section 3.4 <uclamp-default-values>` for default values and +:ref:`3.4.1 <sched-util-clamp-min-rt-default>` on how to change RT tasks +default value. + +2. Design +========= + +Util clamp is a property of every task in the system. It sets the boundaries of +its utilization signal; acting as a bias mechanism that influences certain +decisions within the scheduler. + +The actual utilization signal of a task is never clamped in reality. If you +inspect PELT signals at any point of time you should continue to see them as +they are intact. Clamping happens only when needed, e.g: when a task wakes up +and the scheduler needs to select a suitable CPU for it to run on. + +Since the goal of util clamp is to allow requesting a minimum and maximum +performance point for a task to run on, it must be able to influence the +frequency selection as well as task placement to be most effective. Both of +which have implications on the utilization value at CPU runqueue (rq for short) +level, which brings us to the main design challenge. + +When a task wakes up on an rq, the utilization signal of the rq will be +affected by the uclamp settings of all the tasks enqueued on it. For example if +a task requests to run at UTIL_MIN = 512, then the util signal of the rq needs +to respect to this request as well as all other requests from all of the +enqueued tasks. + +To be able to aggregate the util clamp value of all the tasks attached to the +rq, uclamp must do some housekeeping at every enqueue/dequeue, which is the +scheduler hot path. Hence care must be taken since any slow down will have +significant impact on a lot of use cases and could hinder its usability in +practice. + +The way this is handled is by dividing the utilization range into buckets +(struct uclamp_bucket) which allows us to reduce the search space from every +task on the rq to only a subset of tasks on the top-most bucket. + +When a task is enqueued, the counter in the matching bucket is incremented, +and on dequeue it is decremented. This makes keeping track of the effective +uclamp value at rq level a lot easier. + +As tasks are enqueued and dequeued, we keep track of the current effective +uclamp value of the rq. See :ref:`section 2.1 <uclamp-buckets>` for details on +how this works. + +Later at any path that wants to identify the effective uclamp value of the rq, +it will simply need to read this effective uclamp value of the rq at that exact +moment of time it needs to take a decision. + +For task placement case, only Energy Aware and Capacity Aware Scheduling +(EAS/CAS) make use of uclamp for now, which implies that it is applied on +heterogeneous systems only. +When a task wakes up, the scheduler will look at the current effective uclamp +value of every rq and compare it with the potential new value if the task were +to be enqueued there. Favoring the rq that will end up with the most energy +efficient combination. + +Similarly in schedutil, when it needs to make a frequency update it will look +at the current effective uclamp value of the rq which is influenced by the set +of tasks currently enqueued there and select the appropriate frequency that +will satisfy constraints from requests. + +Other paths like setting overutilization state (which effectively disables EAS) +make use of uclamp as well. Such cases are considered necessary housekeeping to +allow the 2 main use cases above and will not be covered in detail here as they +could change with implementation details. + +.. _uclamp-buckets: + +2.1. Buckets +------------ + +:: + + [struct rq] + + (bottom) (top) + + 0 1024 + | | + +-----------+-----------+-----------+---- ----+-----------+ + | Bucket 0 | Bucket 1 | Bucket 2 | ... | Bucket N | + +-----------+-----------+-----------+---- ----+-----------+ + : : : + +- p0 +- p3 +- p4 + : : + +- p1 +- p5 + : + +- p2 + + +.. note:: + The diagram above is an illustration rather than a true depiction of the + internal data structure. + +To reduce the search space when trying to decide the effective uclamp value of +an rq as tasks are enqueued/dequeued, the whole utilization range is divided +into N buckets where N is configured at compile time by setting +CONFIG_UCLAMP_BUCKETS_COUNT. By default it is set to 5. + +The rq has a bucket for each uclamp_id tunables: [UCLAMP_MIN, UCLAMP_MAX]. + +The range of each bucket is 1024/N. For example, for the default value of +5 there will be 5 buckets, each of which will cover the following range: + +:: + + DELTA = round_closest(1024/5) = 204.8 = 205 + + Bucket 0: [0:204] + Bucket 1: [205:409] + Bucket 2: [410:614] + Bucket 3: [615:819] + Bucket 4: [820:1024] + +When a task p with following tunable parameters + +:: + + p->uclamp[UCLAMP_MIN] = 300 + p->uclamp[UCLAMP_MAX] = 1024 + +is enqueued into the rq, bucket 1 will be incremented for UCLAMP_MIN and bucket +4 will be incremented for UCLAMP_MAX to reflect the fact the rq has a task in +this range. + +The rq then keeps track of its current effective uclamp value for each +uclamp_id. + +When a task p is enqueued, the rq value changes to: + +:: + + // update bucket logic goes here + rq->uclamp[UCLAMP_MIN] = max(rq->uclamp[UCLAMP_MIN], p->uclamp[UCLAMP_MIN]) + // repeat for UCLAMP_MAX + +Similarly, when p is dequeued the rq value changes to: + +:: + + // update bucket logic goes here + rq->uclamp[UCLAMP_MIN] = search_top_bucket_for_highest_value() + // repeat for UCLAMP_MAX + +When all buckets are empty, the rq uclamp values are reset to system defaults. +See :ref:`section 3.4 <uclamp-default-values>` for details on default values. + + +2.2. Max aggregation +-------------------- + +Util clamp is tuned to honour the request for the task that requires the +highest performance point. + +When multiple tasks are attached to the same rq, then util clamp must make sure +the task that needs the highest performance point gets it even if there's +another task that doesn't need it or is disallowed from reaching this point. + +For example, if there are multiple tasks attached to an rq with the following +values: + +:: + + p0->uclamp[UCLAMP_MIN] = 300 + p0->uclamp[UCLAMP_MAX] = 900 + + p1->uclamp[UCLAMP_MIN] = 500 + p1->uclamp[UCLAMP_MAX] = 500 + +then assuming both p0 and p1 are enqueued to the same rq, both UCLAMP_MIN +and UCLAMP_MAX become: + +:: + + rq->uclamp[UCLAMP_MIN] = max(300, 500) = 500 + rq->uclamp[UCLAMP_MAX] = max(900, 500) = 900 + +As we shall see in :ref:`section 5.1 <uclamp-capping-fail>`, this max +aggregation is the cause of one of limitations when using util clamp, in +particular for UCLAMP_MAX hint when user space would like to save power. + +2.3. Hierarchical aggregation +----------------------------- + +As stated earlier, util clamp is a property of every task in the system. But +the actual applied (effective) value can be influenced by more than just the +request made by the task or another actor on its behalf (middleware library). + +The effective util clamp value of any task is restricted as follows: + + 1. By the uclamp settings defined by the cgroup CPU controller it is attached + to, if any. + 2. The restricted value in (1) is then further restricted by the system wide + uclamp settings. + +:ref:`Section 3 <uclamp-interfaces>` discusses the interfaces and will expand +further on that. + +For now suffice to say that if a task makes a request, its actual effective +value will have to adhere to some restrictions imposed by cgroup and system +wide settings. + +The system will still accept the request even if effectively will be beyond the +constraints, but as soon as the task moves to a different cgroup or a sysadmin +modifies the system settings, the request will be satisfied only if it is +within new constraints. + +In other words, this aggregation will not cause an error when a task changes +its uclamp values, but rather the system may not be able to satisfy requests +based on those factors. + +2.4. Range +---------- + +Uclamp performance request has the range of 0 to 1024 inclusive. + +For cgroup interface percentage is used (that is 0 to 100 inclusive). +Just like other cgroup interfaces, you can use 'max' instead of 100. + +.. _uclamp-interfaces: + +3. Interfaces +============= + +3.1. Per task interface +----------------------- + +sched_setattr() syscall was extended to accept two new fields: + +* sched_util_min: requests the minimum performance point the system should run + at when this task is running. Or lower performance bound. +* sched_util_max: requests the maximum performance point the system should run + at when this task is running. Or upper performance bound. + +For example, the following scenario have 40% to 80% utilization constraints: + +:: + + attr->sched_util_min = 40% * 1024; + attr->sched_util_max = 80% * 1024; + +When task @p is running, **the scheduler should try its best to ensure it +starts at 40% performance level**. If the task runs for a long enough time so +that its actual utilization goes above 80%, the utilization, or performance +level, will be capped. + +The special value -1 is used to reset the uclamp settings to the system +default. + +Note that resetting the uclamp value to system default using -1 is not the same +as manually setting uclamp value to system default. This distinction is +important because as we shall see in system interfaces, the default value for +RT could be changed. SCHED_NORMAL/OTHER might gain similar knobs too in the +future. + +3.2. cgroup interface +--------------------- + +There are two uclamp related values in the CPU cgroup controller: + +* cpu.uclamp.min +* cpu.uclamp.max + +When a task is attached to a CPU controller, its uclamp values will be impacted +as follows: + +* cpu.uclamp.min is a protection as described in :ref:`section 3-3 of cgroup + v2 documentation <cgroupv2-protections-distributor>`. + + If a task uclamp_min value is lower than cpu.uclamp.min, then the task will + inherit the cgroup cpu.uclamp.min value. + + In a cgroup hierarchy, effective cpu.uclamp.min is the max of (child, + parent). + +* cpu.uclamp.max is a limit as described in :ref:`section 3-2 of cgroup v2 + documentation <cgroupv2-limits-distributor>`. + + If a task uclamp_max value is higher than cpu.uclamp.max, then the task will + inherit the cgroup cpu.uclamp.max value. + + In a cgroup hierarchy, effective cpu.uclamp.max is the min of (child, + parent). + +For example, given following parameters: + +:: + + p0->uclamp[UCLAMP_MIN] = // system default; + p0->uclamp[UCLAMP_MAX] = // system default; + + p1->uclamp[UCLAMP_MIN] = 40% * 1024; + p1->uclamp[UCLAMP_MAX] = 50% * 1024; + + cgroup0->cpu.uclamp.min = 20% * 1024; + cgroup0->cpu.uclamp.max = 60% * 1024; + + cgroup1->cpu.uclamp.min = 60% * 1024; + cgroup1->cpu.uclamp.max = 100% * 1024; + +when p0 and p1 are attached to cgroup0, the values become: + +:: + + p0->uclamp[UCLAMP_MIN] = cgroup0->cpu.uclamp.min = 20% * 1024; + p0->uclamp[UCLAMP_MAX] = cgroup0->cpu.uclamp.max = 60% * 1024; + + p1->uclamp[UCLAMP_MIN] = 40% * 1024; // intact + p1->uclamp[UCLAMP_MAX] = 50% * 1024; // intact + +when p0 and p1 are attached to cgroup1, these instead become: + +:: + + p0->uclamp[UCLAMP_MIN] = cgroup1->cpu.uclamp.min = 60% * 1024; + p0->uclamp[UCLAMP_MAX] = cgroup1->cpu.uclamp.max = 100% * 1024; + + p1->uclamp[UCLAMP_MIN] = cgroup1->cpu.uclamp.min = 60% * 1024; + p1->uclamp[UCLAMP_MAX] = 50% * 1024; // intact + +Note that cgroup interfaces allows cpu.uclamp.max value to be lower than +cpu.uclamp.min. Other interfaces don't allow that. + +3.3. System interface +--------------------- + +3.3.1 sched_util_clamp_min +-------------------------- + +System wide limit of allowed UCLAMP_MIN range. By default it is set to 1024, +which means that permitted effective UCLAMP_MIN range for tasks is [0:1024]. +By changing it to 512 for example the range reduces to [0:512]. This is useful +to restrict how much boosting tasks are allowed to acquire. + +Requests from tasks to go above this knob value will still succeed, but +they won't be satisfied until it is more than p->uclamp[UCLAMP_MIN]. + +The value must be smaller than or equal to sched_util_clamp_max. + +3.3.2 sched_util_clamp_max +-------------------------- + +System wide limit of allowed UCLAMP_MAX range. By default it is set to 1024, +which means that permitted effective UCLAMP_MAX range for tasks is [0:1024]. + +By changing it to 512 for example the effective allowed range reduces to +[0:512]. This means is that no task can run above 512, which implies that all +rqs are restricted too. IOW, the whole system is capped to half its performance +capacity. + +This is useful to restrict the overall maximum performance point of the system. +For example, it can be handy to limit performance when running low on battery +or when the system wants to limit access to more energy hungry performance +levels when it's in idle state or screen is off. + +Requests from tasks to go above this knob value will still succeed, but they +won't be satisfied until it is more than p->uclamp[UCLAMP_MAX]. + +The value must be greater than or equal to sched_util_clamp_min. + +.. _uclamp-default-values: + +3.4. Default values +------------------- + +By default all SCHED_NORMAL/SCHED_OTHER tasks are initialized to: + +:: + + p_fair->uclamp[UCLAMP_MIN] = 0 + p_fair->uclamp[UCLAMP_MAX] = 1024 + +That is, by default they're boosted to run at the maximum performance point of +changed at boot or runtime. No argument was made yet as to why we should +provide this, but can be added in the future. + +For SCHED_FIFO/SCHED_RR tasks: + +:: + + p_rt->uclamp[UCLAMP_MIN] = 1024 + p_rt->uclamp[UCLAMP_MAX] = 1024 + +That is by default they're boosted to run at the maximum performance point of +the system which retains the historical behavior of the RT tasks. + +RT tasks default uclamp_min value can be modified at boot or runtime via +sysctl. See below section. + +.. _sched-util-clamp-min-rt-default: + +3.4.1 sched_util_clamp_min_rt_default +------------------------------------- + +Running RT tasks at maximum performance point is expensive on battery powered +devices and not necessary. To allow system developer to offer good performance +guarantees for these tasks without pushing it all the way to maximum +performance point, this sysctl knob allows tuning the best boost value to +address the system requirement without burning power running at maximum +performance point all the time. + +Application developer are encouraged to use the per task util clamp interface +to ensure they are performance and power aware. Ideally this knob should be set +to 0 by system designers and leave the task of managing performance +requirements to the apps. + +4. How to use util clamp +======================== + +Util clamp promotes the concept of user space assisted power and performance +management. At the scheduler level there is no info required to make the best +decision. However, with util clamp user space can hint to the scheduler to make +better decision about task placement and frequency selection. + +Best results are achieved by not making any assumptions about the system the +application is running on and to use it in conjunction with a feedback loop to +dynamically monitor and adjust. Ultimately this will allow for a better user +experience at a better perf/watt. + +For some systems and use cases, static setup will help to achieve good results. +Portability will be a problem in this case. How much work one can do at 100, +200 or 1024 is different for each system. Unless there's a specific target +system, static setup should be avoided. + +There are enough possibilities to create a whole framework based on util clamp +or self contained app that makes use of it directly. + +4.1. Boost important and DVFS-latency-sensitive tasks +----------------------------------------------------- + +A GUI task might not be busy to warrant driving the frequency high when it +wakes up. However, it requires to finish its work within a specific time window +to deliver the desired user experience. The right frequency it requires at +wakeup will be system dependent. On some underpowered systems it will be high, +on other overpowered ones it will be low or 0. + +This task can increase its UCLAMP_MIN value every time it misses the deadline +to ensure on next wake up it runs at a higher performance point. It should try +to approach the lowest UCLAMP_MIN value that allows to meet its deadline on any +particular system to achieve the best possible perf/watt for that system. + +On heterogeneous systems, it might be important for this task to run on +a faster CPU. + +**Generally it is advised to perceive the input as performance level or point +which will imply both task placement and frequency selection**. + +4.2. Cap background tasks +------------------------- + +Like explained for Android case in the introduction. Any app can lower +UCLAMP_MAX for some background tasks that don't care about performance but +could end up being busy and consume unnecessary system resources on the system. + +4.3. Powersave mode +------------------- + +sched_util_clamp_max system wide interface can be used to limit all tasks from +operating at the higher performance points which are usually energy +inefficient. + +This is not unique to uclamp as one can achieve the same by reducing max +frequency of the cpufreq governor. It can be considered a more convenient +alternative interface. + +4.4. Per-app performance restriction +------------------------------------ + +Middleware/Utility can provide the user an option to set UCLAMP_MIN/MAX for an +app every time it is executed to guarantee a minimum performance point and/or +limit it from draining system power at the cost of reduced performance for +these apps. + +If you want to prevent your laptop from heating up while on the go from +compiling the kernel and happy to sacrifice performance to save power, but +still would like to keep your browser performance intact, uclamp makes it +possible. + +5. Limitations +============== + +.. _uclamp-capping-fail: + +5.1. Capping frequency with uclamp_max fails under certain conditions +--------------------------------------------------------------------- + +If task p0 is capped to run at 512: + +:: + + p0->uclamp[UCLAMP_MAX] = 512 + +and it shares the rq with p1 which is free to run at any performance point: + +:: + + p1->uclamp[UCLAMP_MAX] = 1024 + +then due to max aggregation the rq will be allowed to reach max performance +point: + +:: + + rq->uclamp[UCLAMP_MAX] = max(512, 1024) = 1024 + +Assuming both p0 and p1 have UCLAMP_MIN = 0, then the frequency selection for +the rq will depend on the actual utilization value of the tasks. + +If p1 is a small task but p0 is a CPU intensive task, then due to the fact that +both are running at the same rq, p1 will cause the frequency capping to be left +from the rq although p1, which is allowed to run at any performance point, +doesn't actually need to run at that frequency. + +5.2. UCLAMP_MAX can break PELT (util_avg) signal +------------------------------------------------ + +PELT assumes that frequency will always increase as the signals grow to ensure +there's always some idle time on the CPU. But with UCLAMP_MAX, this frequency +increase will be prevented which can lead to no idle time in some +circumstances. When there's no idle time, a task will stuck in a busy loop, +which would result in util_avg being 1024. + +Combing with issue described below, this can lead to unwanted frequency spikes +when severely capped tasks share the rq with a small non capped task. + +As an example if task p, which have: + +:: + + p0->util_avg = 300 + p0->uclamp[UCLAMP_MAX] = 0 + +wakes up on an idle CPU, then it will run at min frequency (Fmin) this +CPU is capable of. The max CPU frequency (Fmax) matters here as well, +since it designates the shortest computational time to finish the task's +work on this CPU. + +:: + + rq->uclamp[UCLAMP_MAX] = 0 + +If the ratio of Fmax/Fmin is 3, then maximum value will be: + +:: + + 300 * (Fmax/Fmin) = 900 + +which indicates the CPU will still see idle time since 900 is < 1024. The +_actual_ util_avg will not be 900 though, but somewhere between 300 and 900. As +long as there's idle time, p->util_avg updates will be off by a some margin, +but not proportional to Fmax/Fmin. + +:: + + p0->util_avg = 300 + small_error + +Now if the ratio of Fmax/Fmin is 4, the maximum value becomes: + +:: + + 300 * (Fmax/Fmin) = 1200 + +which is higher than 1024 and indicates that the CPU has no idle time. When +this happens, then the _actual_ util_avg will become: + +:: + + p0->util_avg = 1024 + +If task p1 wakes up on this CPU, which have: + +:: + + p1->util_avg = 200 + p1->uclamp[UCLAMP_MAX] = 1024 + +then the effective UCLAMP_MAX for the CPU will be 1024 according to max +aggregation rule. But since the capped p0 task was running and throttled +severely, then the rq->util_avg will be: + +:: + + p0->util_avg = 1024 + p1->util_avg = 200 + + rq->util_avg = 1024 + rq->uclamp[UCLAMP_MAX] = 1024 + +Hence lead to a frequency spike since if p0 wasn't throttled we should get: + +:: + + p0->util_avg = 300 + p1->util_avg = 200 + + rq->util_avg = 500 + +and run somewhere near mid performance point of that CPU, not the Fmax we get. + +5.3. Schedutil response time issues +----------------------------------- + +schedutil has three limitations: + + 1. Hardware takes non-zero time to respond to any frequency change + request. On some platforms can be in the order of few ms. + 2. Non fast-switch systems require a worker deadline thread to wake up + and perform the frequency change, which adds measurable overhead. + 3. schedutil rate_limit_us drops any requests during this rate_limit_us + window. + +If a relatively small task is doing critical job and requires a certain +performance point when it wakes up and starts running, then all these +limitations will prevent it from getting what it wants in the time scale it +expects. + +This limitation is not only impactful when using uclamp, but will be more +prevalent as we no longer gradually ramp up or down. We could easily be +jumping between frequencies depending on the order tasks wake up, and their +respective uclamp values. + +We regard that as a limitation of the capabilities of the underlying system +itself. + +There is room to improve the behavior of schedutil rate_limit_us, but not much +to be done for 1 or 2. They are considered hard limitations of the system. diff --git a/Documentation/scsi/ChangeLog.lpfc b/Documentation/scsi/ChangeLog.lpfc index caedc8571b45..d16e6874d223 100644 --- a/Documentation/scsi/ChangeLog.lpfc +++ b/Documentation/scsi/ChangeLog.lpfc @@ -174,7 +174,7 @@ Changes from 20050201 to 20050208 lpfc_sli_chipset_init static. * Cleaned up references to list_head->next field in the driver. * Replaced lpfc_discq_post_event with lpfc_workq_post_event. - * Implmented Christoph Hellwig's review from 2/5: Check for return + * Implemented Christoph Hellwig's review from 2/5: Check for return values of kmalloc. * Integrated Christoph Hellwig's patch from 1/30: Protecting scan_tmo and friends in !FC_TRANSPORT_PATCHES_V2 && @@ -182,7 +182,7 @@ Changes from 20050201 to 20050208 * Integrated Christoph Hellwig's patch from 1/30: Some fixes in the evt handling area. * Integrated Christoph Hellwig's patch from 1/30: Remove usage of - intr_inited variable. The interrupt initilization from OS side + intr_inited variable. The interrupt initialization from OS side now happens in lpfc_probe_one(). * Integrated Christoph Hellwig's patch from 1/30: remove shim lpfc_alloc_transport_attr - remove shim lpfc_alloc_shost_attrs - @@ -389,7 +389,7 @@ Changes from 20041220 to 20041229 moved to kthread. kthread_stop() is not able to wake up thread waiting on a semaphore and "modprobe -r lpfc" is not always (most of the times) able to complete. Fix is in not using - semaphore for the interruptable sleep. + semaphore for the interruptible sleep. * Small Makefile cleanup - Remove remnants of 2.4 vs. 2.6 determination. @@ -439,8 +439,8 @@ Changes from 20041207 to 20041213 hardware actually found). * Integrate Christoph Hellwig's patch for 8.0.14: Add missing __iomem annotations, remove broken casts, mark functions static. - Only major changes is chaning of some offsets from word-based to - byte-based so we cans simply do void pointer arithmetics (gcc + Only major changes is changing of some offsets from word-based to + byte-based so we can simply do void pointer arithmetic (gcc extension) instead of casting to uint32_t. * Integrate Christoph Hellwig's patch for 8.0.14: flag is always LPFC_SLI_ABORT_IMED, aka 0 - remove dead code. @@ -515,7 +515,7 @@ Changes from 20041018 to 20041123 a result of removing from the txcmpl list item which was already removed (100100 is a LIST_POISON1 value from the next pointer and 8 is an offset of the "prev") Driver runs out of iotags and - does not handle that case well. The root of the proble is in the + does not handle that case well. The root of the problem is in the initialization code in lpfc_sli.c * Changes to work with proposed linux kernel patch to support hotplug. @@ -570,8 +570,8 @@ Changes from 20041018 to 20041123 associated I/Os to complete before returning. * Fix memset byte count in lpfc_hba_init so that LP1050 would initialize correctly. - * Backround nodev_timeout processing to DPC This enables us to - unblock (stop dev_loss_tmo) when appopriate. + * Background nodev_timeout processing to DPC. This enables us to + unblock (stop dev_loss_tmo) when appropriate. * Fix array discovery with multiple luns. The max_luns was 0 at the time the host structure was initialized. lpfc_cfg_params then set the max_luns to the correct value afterwards. @@ -1012,7 +1012,7 @@ Changes from 20040614 to 20040709 LINK_[UP|DOWN] and RSCN events. * Get rid of delay_iodone timer. * Remove qfull timers and qfull logic. - * Convert mbox_tmo, nlp_xri_tmo to 1 argment clock handler + * Convert mbox_tmo, nlp_xri_tmo to 1 argument clock handler * Removed duplicate extern defs of the bind variables. * Streamline usage of the defines CLASS2 and CLASS3, removing un-necessary checks on config[LPFC_CFG_FCP_CLASS]. @@ -1369,7 +1369,7 @@ Changes from 20040416 to 20040426 * Removed lpfc_max_target from lpfc_linux_attach * Replace references to lpfcDRVR.pHba[] with lpfc_get_phba_by_inst() * Change lpfc_param to lpfc-param - * Partially removed 32 HBA restriction within driver. Incorported + * Partially removed 32 HBA restriction within driver. Incorporated lpfc_instcnt, lpfc_instance[], and pHba[] into lpfcDRVR structure Added routines lpfc_get_phba_by_inst() lpfc_get_inst_by_phba() lpfc_check_valid_phba() @@ -1535,7 +1535,7 @@ Changes from 20040326 to 20040402 * Use Linux list macros for DMABUF_t * Break up ioctls into 3 sections, dfc, util, hbaapi rearranged code so this could be easily separated into a - differnet module later All 3 are currently turned on by + different module later. All 3 are currently turned on by defines in lpfc_ioctl.c LPFC_DFC_IOCTL, LPFC_UTIL_IOCTL, LPFC_HBAAPI_IOCTL * Misc cleanup: some goto's; add comments; clarify function @@ -1562,7 +1562,7 @@ Changes from 20040326 to 20040402 * Remove unused log message. * Collapse elx_crtn.h and prod_crtn.h into lpfc_crtn.h * Ifdef Scheduler specific routines - * Removed following ununsed ioclt's: ELX_READ_IOCB + * Removed following unused ioctl's: ELX_READ_IOCB ELX_READ_MEMSEG ELX_READ_BINFO ELX_READ_EINVAL ELX_READ_LHBA ELX_READ_LXHBA ELX_SET ELX_DBG LPFC_TRACE * Removed variable fc_dbg_flg @@ -1570,7 +1570,7 @@ Changes from 20040326 to 20040402 3-digit HBAs. Also changed can_queue so midlayer will only send (HBA_Q_DEPTH - 10) cmds. * Clean up code in the error path, check condition. Remove - ununsed sense-related fields in lun structure. + unused sense-related fields in lun structure. * Added code for safety pools for following objects: mbuf/bpl, mbox, iocb, ndlp, bind * Wrapped '#include <elx_sched.h>' in '#ifdef USE_SCHEDULER'. @@ -1592,7 +1592,7 @@ Changes from 20040326 to 20040402 ELX_READ_HBA ELX_INSTANCE ELX_LIP. Also introduced attribute "set" to be used in conjunction with the above attributes. - * Removed DLINK, enque and deque declarations now that clock + * Removed DLINK, enqueue and dequeue declarations now that clock doesn't use them anymore * Separated install rule so that BUILD_IPFC has to be set when make is called in order for the install rule to attempt to @@ -1662,7 +1662,7 @@ Changes from 20040326 to 20040402 * Create utility clock function elx_start_timer() and elx_stop_timer(). All timeout routines now use these common routines. - * Minor formating changes fix up comments + * Minor formatting changes fix up comments * Minor formatting changes get rid of failover defines for syntax checking * Minor formatting changes remove ISCSI defines. @@ -1676,7 +1676,7 @@ Changes from 20040326 to 20040402 will not exist otherwise. * Removed unused malloc counters from lpfcLINUXfcp.c. * Remove some unnecessary #includes in lpfcLINUXfcp.c - * Remove unncessary #includes in elxLINUXfcp.c + * Remove unnecessary #includes in elxLINUXfcp.c * Minor formatting cleanups in Makefile to avoid some linewrapping. * Removed unused elx_mem_pool data structure. @@ -1753,7 +1753,7 @@ Changes from 20040319 to 20040326 elx_str_atox). * Replaced DLINK_t and SLINK_t by standard Linux list_head * Removed deque macro - * Replaced ELX_DLINK_t ans ELX_SLINK_t by Linux struct list_head + * Replaced ELX_DLINK_t and ELX_SLINK_t by Linux struct list_head (except for clock) * Removed following functions from code: linux_kmalloc linux_kfree elx_alloc_bigbuf elx_free_bigbuf @@ -1801,7 +1801,7 @@ Changes from 20040312 to 20040319 * Correct Iocbq completion routine for 2.6 kernel case * Change void *pOSCmd to Scsi_Smnd *pCmd * Change void *pOScmd to struct sk_buff *pCmd - * Remove data directon code. + * Remove data direction code. * Removed memory pool for buf/bpl buffers and use kmalloc/kfree pci_pool_alloc/free directly. * Move PPC check for DMA address 0 in scatter-gather list, into diff --git a/Documentation/scsi/ChangeLog.megaraid b/Documentation/scsi/ChangeLog.megaraid index cbb329956897..a0d216a612f6 100644 --- a/Documentation/scsi/ChangeLog.megaraid +++ b/Documentation/scsi/ChangeLog.megaraid @@ -22,7 +22,7 @@ Older Version : 2.20.4.8 (scsi module), 2.20.2.6 (cmm module) Customer reported "garbage in file on x86_64 platform". Root Cause: the driver registered controllers as 64-bit DMA capable for those which are not support it. - Fix: Made change in the function inserting identification machanism + Fix: Made change in the function inserting identification mechanism identifying 64-bit DMA capable controllers. > -----Original Message----- @@ -82,9 +82,9 @@ Older Version : 2.20.4.8 (scsi module), 2.20.2.6 (cmm module) Fix: MegaRAID F/W has fixed the problem and being process of release, soon. Meanwhile, driver will filter out the request. -3. One of member in the data structure of the driver leads unaligne +3. One member in the data structure of the driver leads to unaligned issue on 64-bit platform. - Customer reporeted "kernel unaligned access addrss" issue when + Customer reported "kernel unaligned access address" issue when application communicates with MegaRAID HBA driver. Root Cause: in uioc_t structure, one of member had misaligned and it led system to display the error message. @@ -441,7 +441,7 @@ i. When copying the mailbox packets, copy only first 14 bytes (for 32-bit avoid getting the stale values for busy bit. We want to set the busy bit just before issuing command to the FW. -ii. In the reset handling, if the reseted command is not owned by the +ii. In the reset handling, if the reset command is not owned by the driver, do not (wrongly) print information for the "attached" driver packet. diff --git a/Documentation/scsi/ChangeLog.megaraid_sas b/Documentation/scsi/ChangeLog.megaraid_sas index 234ddabb23ef..fd3d586d7a75 100644 --- a/Documentation/scsi/ChangeLog.megaraid_sas +++ b/Documentation/scsi/ChangeLog.megaraid_sas @@ -517,7 +517,7 @@ i. bios_param entry added in scsi_host_template that returns disk geometry 1. Added new memory management module to support the IOCTL memory allocation. For IOCTL we try to allocate from the memory pool created during driver initialization. If mem pool is empty then we allocate at run time. 2. Added check in megasas_queue_command and dpc/isr routine to see if we have already declared adapter dead - (hw_crit_error=1). If hw_crit_error==1, now we donot accept any processing of pending cmds/accept any cmd from OS + (hw_crit_error=1). If hw_crit_error==1, now we do not accept any processing of pending cmds/accept any cmd from OS 1 Release Date : Mon Oct 02 11:21:32 PDT 2006 - Sumant Patro <Sumant.Patro@lsil.com> 2 Current Version : 00.00.03.05 @@ -562,7 +562,7 @@ vii. Added print : FW now in Ready State during initialization 2 Current Version : 00.00.03.02 3 Older Version : 00.00.03.01 -i. Added FW tranistion state for Hotplug scenario +i. Added FW transition state for Hotplug scenario 1 Release Date : Sun May 14 22:49:52 PDT 2006 - Sumant Patro <Sumant.Patro@lsil.com> 2 Current Version : 00.00.03.01 diff --git a/Documentation/scsi/ChangeLog.ncr53c8xx b/Documentation/scsi/ChangeLog.ncr53c8xx index 9288e3d8974a..50bf850da838 100644 --- a/Documentation/scsi/ChangeLog.ncr53c8xx +++ b/Documentation/scsi/ChangeLog.ncr53c8xx @@ -230,7 +230,7 @@ Sat Nov 21 18:00 1998 Gerard Roudier (groudier@club-internet.fr) - Still a buglet in the tags initial settings that needed to be fixed. It was not possible to disable TGQ at system startup for devices that claim TGQ support. The driver used at least 2 for the queue - depth but did'nt keep track of user settings for tags depth lower + depth but didn't keep track of user settings for tags depth lower than 2. Wed Nov 11 10:00 1998 Gerard Roudier (groudier@club-internet.fr) @@ -270,7 +270,7 @@ Sun Oct 4 14:00 1998 Gerard Roudier (groudier@club-internet.fr) were due to a SCSI selection problem triggered by a clearly documented feature that in fact seems not to work: (53C8XX chips are claimed by the manuals to be able to execute SCSI scripts just - after abitration while the SCSI core is performing SCSI selection). + after arbitration while the SCSI core is performing SCSI selection). This optimization is broken and has been removed. - Some broken scsi devices are confused when a negotiation is started on a LUN that does not correspond to a real device. According to @@ -347,7 +347,7 @@ Tue Jun 4 23:00 1998 Gerard Roudier (groudier@club-internet.fr) - Code cleanup and simplification: Remove kernel 1.2.X and 1.3.X support. Remove the _old_ target capabilities table. - Remove the error recovery code that have'nt been really useful. + Remove the error recovery code that hasn't been really useful. Use a single alignment boundary (CACHE_LINE_SIZE) for data structures. - Several aggressive SCRIPTS optimizations and changes: @@ -367,8 +367,8 @@ Wed May 13 20:00 1998 Gerard Roudier (groudier@club-internet.fr) - Some simplification for 64 bit arch done ccb address testing. - Add a check of the MSG_OUT phase after Selection with ATN. - The new tagged queue stuff seems ok, so some informationnal - message have been conditionned by verbose >= 3. - - Donnot reset if a SBMC interrupt reports the same bus mode. + message have been conditioned by verbose >= 3. + - Do not reset if a SBMC interrupt reports the same bus mode. - Print out the whole driver set-up. Some options were missing and the print statement was misplaced for modules. - Ignore a SCSI parity interrupt if the chip is not connected to @@ -392,7 +392,7 @@ Sat Apr 25 21:00 1998 Gerard Roudier (groudier@club-internet.fr) context on phase mismatch. - The above allows now to use the on-chip RAM without requiring to get access to the on-chip RAM from the C code. This makes - on-chip RAM useable for linux-1.2.13 and for Linux-Alpha for + on-chip RAM usable for linux-1.2.13 and for Linux-Alpha for instance. - Some simplifications and cleanups in the SCRIPTS and C code. - Buglet fixed in parity error recovery SCRIPTS (never tested). @@ -433,7 +433,7 @@ Sun Mar 29 12:00 1998 Gerard Roudier (groudier@club-internet.fr) Tue Mar 26 23:00 1998 Gerard Roudier (groudier@club-internet.fr) * revision 2.6g - - New done queue. 8 entries by default (6 always useable). + - New done queue. 8 entries by default (6 always usable). Can be increased if needed. - Resources management using doubly linked queues. - New auto-sense and QUEUE FULL handling that does not need to @@ -464,7 +464,7 @@ Sun Jan 11 22:00 1998 Gerard Roudier (groudier@club-internet.fr) - generalization of the restart of CCB on special condition as Abort, QUEUE FULL, CHECK CONDITION. This has been called 'silly scheduler'. - - make all the profiling code conditionned by a config option. + - make all the profiling code conditioned by a config option. This spare some PCI traffic and C code when this feature is not needed. - handle more cleanly the situation where direction is unknown. diff --git a/Documentation/scsi/ChangeLog.sym53c8xx b/Documentation/scsi/ChangeLog.sym53c8xx index c1933707d0bc..3435227a2bed 100644 --- a/Documentation/scsi/ChangeLog.sym53c8xx +++ b/Documentation/scsi/ChangeLog.sym53c8xx @@ -255,7 +255,7 @@ Sat Sep 11 11:00 1999 Gerard Roudier (groudier@club-internet.fr) - Work-around PCI chips being reported twice on some platforms. - Add some redundant PCI reads in order to deal with common bridge misbehaviour regarding posted write flushing. - - Add some other conditionnal code for people who have to deal + - Add some other conditional code for people who have to deal with really broken bridges (they will have to edit a source file to try these options). - Handle correctly (hopefully) jiffies wrap-around. @@ -300,7 +300,7 @@ Sat May 29 12:00 1999 Gerard Roudier (groudier@club-internet.fr) Tue May 25 23:00 1999 Gerard Roudier (groudier@club-internet.fr) * version sym53c8xx-1.5a - Add support for task abort and bus device reset SCSI message - and implement proper synchonisation with SCRIPTS to handle + and implement proper synchronisation with SCRIPTS to handle correctly task abortion without races. - Send an ABORT message (if untagged) or ABORT TAG message (if tagged) when the driver is told to abort a command that is disconnected and @@ -410,7 +410,7 @@ Fri Feb 12 23:00 1999 Gerard Roudier (groudier@club-internet.fr) the support of non compliant SCSI removal, insertion and all kinds of screw-up that may happen on the SCSI BUS. Hopefully, the driver is now unbreakable or may-be, it is just - quite brocken. :-) + quite broken. :-) Many thanks to Johnson Russel (Symbios) for having responded to my questions and for his interesting advices and comments about support of SCSI hot-plug. @@ -432,7 +432,7 @@ Sun Jan 31 18:00 1999 Gerard Roudier (groudier@club-internet.fr) Sun Jan 24 18:00 1999 Gerard Roudier (groudier@club-internet.fr) * version sym53c8xx-1.1 - Major rewrite of the SCSI parity error handling. - The informations contained in the data manuals are incomplete about + The information contained in the data manuals is incomplete about this feature. I asked SYMBIOS about and got in reply the explanations that are _indeed_ missing in the data manuals. @@ -460,7 +460,7 @@ Sat Dec 19 21:00 1998 Gerard Roudier (groudier@club-internet.fr) - Revamp slightly the Symbios NVRAM lay-out based on the excerpt of the header file I received from Symbios. - Check the PCI bus number for the boot order (Using a fast - PCI controller behing a PCI-PCI bridge seems sub-optimal). + PCI controller behind a PCI-PCI bridge seems sub-optimal). - Disable overlapped PCI arbitration for the 896 revision 1. - Reduce a bit the number of IO register reads for phase mismatch by reading DWORDS at a time instead of BYTES. @@ -488,7 +488,7 @@ Sun Nov 29 18:00 1998 Gerard Roudier (groudier@club-internet.fr) Tue Nov 24 23:00 1998 Gerard Roudier (groudier@club-internet.fr) * version pre-sym53c8xx-0.16 - Add SCSI_NCR_OPTIMIZE_896_1 compile option and 'optim' boot option. - When set, the driver unconditionnaly assumes that the interrupt + When set, the driver unconditionally assumes that the interrupt handler is called for command completion, then clears INTF, scans the done queue and returns if some completed CCB is found. If no completed CCB are found, interrupt handling will proceed normally. @@ -502,7 +502,7 @@ Tue Nov 24 23:00 1998 Gerard Roudier (groudier@club-internet.fr) - Still a buglet in the tags initial settings that needed to be fixed. It was not possible to disable TGQ at system startup for devices that claim TGQ support. The driver used at least 2 for the queue - depth but did'nt keep track of user settings for tags depth lower + depth but didn't keep track of user settings for tags depth lower than 2. Thu Nov 19 23:00 1998 Gerard Roudier (groudier@club-internet.fr) diff --git a/Documentation/scsi/ChangeLog.sym53c8xx_2 b/Documentation/scsi/ChangeLog.sym53c8xx_2 index 18a5d712a56a..9180eb343991 100644 --- a/Documentation/scsi/ChangeLog.sym53c8xx_2 +++ b/Documentation/scsi/ChangeLog.sym53c8xx_2 @@ -40,7 +40,7 @@ Wed Feb 7 21:00 2001 Gerard Roudier - Call pci_enable_device() as wished by kernel maintainers. - Change the sym_queue_scsiio() interface. This is intended to simplify portability. - - Move the code intended to deal with the dowloading of SCRIPTS + - Move the code intended to deal with the downloading of SCRIPTS from SCRIPTS :) in the patch method (was wrongly placed in the SCRIPTS setup method). - Add a missing cpu_to_scr() (np->abort_tbl.addr) @@ -53,9 +53,9 @@ Sat Mar 3 21:00 2001 Gerard Roudier Also move the code that sniffes INQUIRY to sym_misc.c. This allows to share the corresponding code with NetBSD without polluating the core driver source (sym_hipd.c). - - Add optionnal code that handles IO timeouts from the driver. + - Add optional code that handles IO timeouts from the driver. (not used under Linux, but required for NetBSD) - - Donnot assume any longer that PAGE_SHIFT and PAGE_SIZE are + - Do not assume any longer that PAGE_SHIFT and PAGE_SIZE are defined at compile time, as at least NetBSD uses variables in memory for that. - Refine a work-around for the C1010-33 that consists in @@ -104,7 +104,7 @@ Sun Sep 9 18:00 2001 Gerard Roudier - Change my email address. - Add infrastructure for the forthcoming 64 bit DMA addressing support. (Based on PCI 64 bit patch from David S. Miller) - - Donnot use anymore vm_offset_t type. + - Do not use anymore vm_offset_t type. Sat Sep 15 20:00 2001 Gerard Roudier * version sym-2.1.13-20010916 @@ -119,7 +119,7 @@ Sat Sep 22 12:00 2001 Gerard Roudier Sun Sep 30 17:00 2001 Gerard Roudier * version sym-2.1.15-20010930 - - Include <linux/module.h> unconditionnaly as expected by latest + - Include <linux/module.h> unconditionally as expected by latest kernels. - Use del_timer_sync() for recent kernels to kill the driver timer on module release. diff --git a/Documentation/scsi/index.rst b/Documentation/scsi/index.rst index 7c5f5f8f614e..919f3edfe1bf 100644 --- a/Documentation/scsi/index.rst +++ b/Documentation/scsi/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -==================== -Linux SCSI Subsystem -==================== +============== +SCSI Subsystem +============== .. toctree:: :maxdepth: 1 diff --git a/Documentation/scsi/ncr53c8xx.rst b/Documentation/scsi/ncr53c8xx.rst index c41cec99f07c..1c79e08ec964 100644 --- a/Documentation/scsi/ncr53c8xx.rst +++ b/Documentation/scsi/ncr53c8xx.rst @@ -906,7 +906,7 @@ burst:#x burst enabled (1<<#x burst transfers max) led:0 disable LED support ===== =================== - Donnot enable LED support if your scsi board does not use SDMS BIOS. + Do not enable LED support if your scsi board does not use SDMS BIOS. (See 'Configuration parameters') 10.2.13 Max wide @@ -1222,7 +1222,7 @@ Unfortunately, the following common SCSI BUS problems are not detected: - Bad quality terminators. On the other hand, either bad cabling, broken devices, not conformant -devices, ... may cause a SCSI signal to be wrong when te driver reads it. +devices, ... may cause a SCSI signal to be wrong when the driver reads it. 10.7 IMMEDIATE ARBITRATION boot option ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/scsi/sym53c8xx_2.rst b/Documentation/scsi/sym53c8xx_2.rst index 8de44a7baa9b..004f1a750e7d 100644 --- a/Documentation/scsi/sym53c8xx_2.rst +++ b/Documentation/scsi/sym53c8xx_2.rst @@ -703,7 +703,7 @@ Unfortunately, the following common SCSI BUS problems are not detected: - Bad quality terminators. On the other hand, either bad cabling, broken devices, not conformant -devices, ... may cause a SCSI signal to be wrong when te driver reads it. +devices, ... may cause a SCSI signal to be wrong when the driver reads it. 15. SCSI problem troubleshooting ================================ diff --git a/Documentation/scsi/tcm_qla2xxx.rst b/Documentation/scsi/tcm_qla2xxx.rst index 91bc1fcd369e..7268c2771e8f 100644 --- a/Documentation/scsi/tcm_qla2xxx.rst +++ b/Documentation/scsi/tcm_qla2xxx.rst @@ -6,7 +6,7 @@ tcm_qla2xxx Driver Notes tcm_qla2xxx jam_host attribute ------------------------------ -There is now a new module endpoint atribute called jam_host +There is now a new module endpoint attribute called jam_host attribute:: jam_host: boolean=0/1 diff --git a/Documentation/scsi/ufs.rst b/Documentation/scsi/ufs.rst index 885b1a736e3f..a7b2b2ed1c3a 100644 --- a/Documentation/scsi/ufs.rst +++ b/Documentation/scsi/ufs.rst @@ -206,5 +206,5 @@ Device-Specific Data property named "ref-clk-freq". In both ways the value is interpreted as frequency in Hz and must match one of the values given in the UFS specification. UFS subsystem will attempt to read the value when executing common controller initialization. If the value is available, UFS -subsytem will ensure the bRefClkFreq attribute of the UFS storage device is +subsystem will ensure the bRefClkFreq attribute of the UFS storage device is set accordingly and will modify it if there is a mismatch. diff --git a/Documentation/security/landlock.rst b/Documentation/security/landlock.rst index c0029d5d02eb..36f26501fd15 100644 --- a/Documentation/security/landlock.rst +++ b/Documentation/security/landlock.rst @@ -7,7 +7,7 @@ Landlock LSM: kernel documentation ================================== :Author: Mickaël Salaün -:Date: September 2022 +:Date: December 2022 Landlock's goal is to create scoped access-control (i.e. sandboxing). To harden a whole system, this feature should be available to any process, @@ -41,12 +41,16 @@ Guiding principles for safe access controls processes. * Computation related to Landlock operations (e.g. enforcing a ruleset) shall only impact the processes requesting them. +* Resources (e.g. file descriptors) directly obtained from the kernel by a + sandboxed process shall retain their scoped accesses (at the time of resource + acquisition) whatever process use them. + Cf. `File descriptor access rights`_. Design choices ============== -Filesystem access rights ------------------------- +Inode access rights +------------------- All access rights are tied to an inode and what can be accessed through it. Reading the content of a directory does not imply to be allowed to read the @@ -57,6 +61,30 @@ directory, not the unlinked inode. This is the reason why ``LANDLOCK_ACCESS_FS_REMOVE_FILE`` or ``LANDLOCK_ACCESS_FS_REFER`` are not allowed to be tied to files but only to directories. +File descriptor access rights +----------------------------- + +Access rights are checked and tied to file descriptors at open time. The +underlying principle is that equivalent sequences of operations should lead to +the same results, when they are executed under the same Landlock domain. + +Taking the ``LANDLOCK_ACCESS_FS_TRUNCATE`` right as an example, it may be +allowed to open a file for writing without being allowed to +:manpage:`ftruncate` the resulting file descriptor if the related file +hierarchy doesn't grant such access right. The following sequences of +operations have the same semantic and should then have the same result: + +* ``truncate(path);`` +* ``int fd = open(path, O_WRONLY); ftruncate(fd); close(fd);`` + +Similarly to file access modes (e.g. ``O_RDWR``), Landlock access rights +attached to file descriptors are retained even if they are passed between +processes (e.g. through a Unix domain socket). Such access rights will then be +enforced even if the receiving process is not sandboxed by Landlock. Indeed, +this is required to keep a consistent access control over the whole system, and +this avoids unattended bypasses through file descriptor passing (i.e. confused +deputy attack). + Tests ===== diff --git a/Documentation/sound/alsa-configuration.rst b/Documentation/sound/alsa-configuration.rst index 21ab5e6f7062..5f31fa5e2435 100644 --- a/Documentation/sound/alsa-configuration.rst +++ b/Documentation/sound/alsa-configuration.rst @@ -70,7 +70,7 @@ dsp_map PCM device number maps assigned to the 1st OSS device; Default: 0 adsp_map - PCM device number maps assigned to the 2st OSS device; + PCM device number maps assigned to the 2nd OSS device; Default: 1 nonblock_open Don't block opening busy PCM devices; @@ -97,7 +97,7 @@ midi_map MIDI device number maps assigned to the 1st OSS device; Default: 0 amidi_map - MIDI device number maps assigned to the 2st OSS device; + MIDI device number maps assigned to the 2nd OSS device; Default: 1 Module snd-soc-core @@ -727,9 +727,9 @@ Module for EMU10K1/EMU10k2 based PCI sound cards. * Sound Blaster Audigy extin - bitmap of available external inputs for FX8010 (see bellow) + bitmap of available external inputs for FX8010 (see below) extout - bitmap of available external outputs for FX8010 (see bellow) + bitmap of available external outputs for FX8010 (see below) seq_ports allocated sequencer ports (4 by default) max_synth_voices diff --git a/Documentation/sound/cards/audigy-mixer.rst b/Documentation/sound/cards/audigy-mixer.rst index f3f4640ee2af..c506f8d16f2e 100644 --- a/Documentation/sound/cards/audigy-mixer.rst +++ b/Documentation/sound/cards/audigy-mixer.rst @@ -17,7 +17,7 @@ Digital mixer controls ====================== These controls are built using the DSP instructions. They offer extended -functionality. Only the default build-in code in the ALSA driver is described +functionality. Only the default built-in code in the ALSA driver is described here. 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 wrapped diff --git a/Documentation/sound/cards/maya44.rst b/Documentation/sound/cards/maya44.rst index bf09a584b443..ab973f66c973 100644 --- a/Documentation/sound/cards/maya44.rst +++ b/Documentation/sound/cards/maya44.rst @@ -156,7 +156,7 @@ IEC958 Output S/PDIF should output the same signal as channel 3+4. [untested!] -Digitial output selectors +Digital output selectors These switches allow a direct digital routing from the ADCs to the DACs. Each switch determines where the digital input data to one of the DACs comes from. They are not supported by the ESI windows driver. diff --git a/Documentation/sound/cards/sb-live-mixer.rst b/Documentation/sound/cards/sb-live-mixer.rst index 2ce41d3822d8..357fcd619d39 100644 --- a/Documentation/sound/cards/sb-live-mixer.rst +++ b/Documentation/sound/cards/sb-live-mixer.rst @@ -31,7 +31,7 @@ Digital mixer controls ====================== These controls are built using the DSP instructions. They offer extended -functionality. Only the default build-in code in the ALSA driver is described +functionality. Only the default built-in code in the ALSA driver is described here. 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 wrapped diff --git a/Documentation/sound/designs/jack-controls.rst b/Documentation/sound/designs/jack-controls.rst index ae25b1531bb0..e8a18f126a63 100644 --- a/Documentation/sound/designs/jack-controls.rst +++ b/Documentation/sound/designs/jack-controls.rst @@ -8,7 +8,7 @@ Why we need Jack kcontrols ALSA uses kcontrols to export audio controls(switch, volume, Mux, ...) to user space. This means userspace applications like pulseaudio can switch off headphones and switch on speakers when no headphones are -pluged in. +plugged in. The old ALSA jack code only created input devices for each registered jack. These jack input devices are not readable by userspace devices diff --git a/Documentation/sound/designs/seq-oss.rst b/Documentation/sound/designs/seq-oss.rst index e82ffe0e7f43..ec6304a07441 100644 --- a/Documentation/sound/designs/seq-oss.rst +++ b/Documentation/sound/designs/seq-oss.rst @@ -96,7 +96,7 @@ if you use an AWE64 card, you'll see like the following: Number of synth devices: 1 synth 0: [EMU8000] type 0x1 : subtype 0x20 : voices 32 - capabilties : ioctl enabled / load_patch enabled + capabilities : ioctl enabled / load_patch enabled Number of MIDI devices: 3 midi 0: [Emu8000 Port-0] ALSA port 65:0 diff --git a/Documentation/sound/hd-audio/notes.rst b/Documentation/sound/hd-audio/notes.rst index d118b6fe269b..a9e35b1f87bd 100644 --- a/Documentation/sound/hd-audio/notes.rst +++ b/Documentation/sound/hd-audio/notes.rst @@ -500,7 +500,7 @@ add_jack_modes (bool) change the headphone amp and mic bias VREF capabilities power_save_node (bool) advanced power management for each widget, controlling the power - sate (D0/D3) of each widget node depending on the actual pin and + state (D0/D3) of each widget node depending on the actual pin and stream states power_down_unused (bool) power down the unused widgets, a subset of power_save_node, and @@ -651,14 +651,14 @@ via power-saving behavior. Enabling all tracepoints can be done like :: - # echo 1 > /sys/kernel/debug/tracing/events/hda/enable + # echo 1 > /sys/kernel/tracing/events/hda/enable then after some commands, you can traces from -/sys/kernel/debug/tracing/trace file. For example, when you want to +/sys/kernel/tracing/trace file. For example, when you want to trace what codec command is sent, enable the tracepoint like: :: - # cat /sys/kernel/debug/tracing/trace + # cat /sys/kernel/tracing/trace # tracer: nop # # TASK-PID CPU# TIMESTAMP FUNCTION diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst index 4d7d42acf6df..7e67e12730d3 100644 --- a/Documentation/sound/index.rst +++ b/Documentation/sound/index.rst @@ -1,6 +1,8 @@ -=================================== -Linux Sound Subsystem Documentation -=================================== +.. SPDX-License-Identifier: GPL-2.0 + +============================= +Sound Subsystem Documentation +============================= .. toctree:: :maxdepth: 2 diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index 07a620c5ca74..5c9523b7d55c 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -1720,16 +1720,16 @@ Typically, you'll have a hardware descriptor as below: - ``rate_min`` and ``rate_max`` define the minimum and maximum sample rate. This should correspond somehow to ``rates`` bits. -- ``channel_min`` and ``channel_max`` define, as you might already +- ``channels_min`` and ``channels_max`` define, as you might already expected, the minimum and maximum number of channels. - ``buffer_bytes_max`` defines the maximum buffer size in bytes. There is no ``buffer_bytes_min`` field, since it can be calculated from the minimum period size and the minimum number of - periods. Meanwhile, ``period_bytes_min`` and define the minimum and - maximum size of the period in bytes. ``periods_max`` and - ``periods_min`` define the maximum and minimum number of periods in - the buffer. + periods. Meanwhile, ``period_bytes_min`` and ``period_bytes_max`` + define the minimum and maximum size of the period in bytes. + ``periods_max`` and ``periods_min`` define the maximum and minimum + number of periods in the buffer. The “period†is a term that corresponds to a fragment in the OSS world. The period defines the size at which a PCM interrupt is diff --git a/Documentation/sparc/adi.rst b/Documentation/sparc/adi.rst index 857ad30f9569..dbcd8b6e7bc3 100644 --- a/Documentation/sparc/adi.rst +++ b/Documentation/sparc/adi.rst @@ -38,7 +38,7 @@ virtual addresses that contain 0xa in bits 63-60. ADI is enabled on a set of pages using mprotect() with PROT_ADI flag. When ADI is enabled on a set of pages by a task for the first time, -kernel sets the PSTATE.mcde bit fot the task. Version tags for memory +kernel sets the PSTATE.mcde bit for the task. Version tags for memory addresses are set with an stxa instruction on the addresses using ASI_MCD_PRIMARY or ASI_MCD_ST_BLKINIT_PRIMARY. ADI block size is provided by the hypervisor to the kernel. Kernel returns the value of @@ -97,7 +97,7 @@ With ADI enabled, following new traps may occur: Disrupting memory corruption ---------------------------- - When a store accesses a memory localtion that has TTE.mcd=1, + When a store accesses a memory location that has TTE.mcd=1, the task is running with ADI enabled (PSTATE.mcde=1), and the ADI tag in the address used (bits 63:60) does not match the tag set on the corresponding cacheline, a memory corruption trap occurs. By diff --git a/Documentation/sparc/oradax/dax-hv-api.txt b/Documentation/sparc/oradax/dax-hv-api.txt index 73e8d506cf64..7ecd0bf4957b 100644 --- a/Documentation/sparc/oradax/dax-hv-api.txt +++ b/Documentation/sparc/oradax/dax-hv-api.txt @@ -22,7 +22,7 @@ Chapter 36. Coprocessor services functionality offered may vary by virtual machine implementation. The DAX is a virtual device to sun4v guests, with supported data operations indicated by the virtual device - compatibilty property. Functionality is accessed through the submission of Command Control Blocks + compatibility property. Functionality is accessed through the submission of Command Control Blocks (CCBs) via the ccb_submit API function. The operations are processed asynchronously, with the status of the submitted operations reported through a Completion Area linked to each CCB. Each CCB has a separate Completion Area and, unless execution order is specifically restricted through the use of serial- @@ -313,7 +313,7 @@ bits set, and terminate at a CCB that has the Conditional bit set, but not the P Secondary Input Description Format Code - 0 Element is stored as value minus 1 (0 evalutes to 1, 1 evalutes + 0 Element is stored as value minus 1 (0 evaluates to 1, 1 evaluates to 2, etc) 1 Element is stored as value @@ -659,7 +659,7 @@ Offset Size Field Description “Secondary Input Element Size†[13:10] Output Format (see Section 36.2.1.1.6, “Output Formatâ€) [9:5] Operand size for first scan criteria value. In a scan value - operation, this is one of two potential extact match values. + operation, this is one of two potential exact match values. In a scan range operation, this is the size of the upper range @@ -673,7 +673,7 @@ Offset Size Field Description operand, minus 1. Values 0xF-0x1E are reserved. A value of 0x1F indicates this operand is not in use for this scan operation. [4:0] Operand size for second scan criteria value. In a scan value - operation, this is one of two potential extact match values. + operation, this is one of two potential exact match values. In a scan range operation, this is the size of the lower range boundary. The value of this field is the number of bytes in the operand, minus 1. Values 0xF-0x1E are reserved. A value of @@ -690,24 +690,24 @@ Offset Size Field Description 48 8 Output (same fields as Primary Input) 56 8 Symbol Table (if used by Primary Input). Same fields as Section 36.2.1.2, “Extract command†-64 4 Next 4 most significant bytes of first scan criteria operand occuring after the +64 4 Next 4 most significant bytes of first scan criteria operand occurring after the bytes specified at offset 40, if needed by the operand size. If first operand is less than 8 bytes, the valid bytes are left-aligned to the lowest address. -68 4 Next 4 most significant bytes of second scan criteria operand occuring after +68 4 Next 4 most significant bytes of second scan criteria operand occurring after the bytes specified at offset 44, if needed by the operand size. If second operand is less than 8 bytes, the valid bytes are left-aligned to the lowest address. -72 4 Next 4 most significant bytes of first scan criteria operand occuring after the +72 4 Next 4 most significant bytes of first scan criteria operand occurring after the bytes specified at offset 64, if needed by the operand size. If first operand is less than 12 bytes, the valid bytes are left-aligned to the lowest address. -76 4 Next 4 most significant bytes of second scan criteria operand occuring after +76 4 Next 4 most significant bytes of second scan criteria operand occurring after the bytes specified at offset 68, if needed by the operand size. If second operand is less than 12 bytes, the valid bytes are left-aligned to the lowest address. -80 4 Next 4 most significant bytes of first scan criteria operand occuring after the +80 4 Next 4 most significant bytes of first scan criteria operand occurring after the bytes specified at offset 72, if needed by the operand size. If first operand is less than 16 bytes, the valid bytes are left-aligned to the lowest address. -84 4 Next 4 most significant bytes of second scan criteria operand occuring after +84 4 Next 4 most significant bytes of second scan criteria operand occurring after the bytes specified at offset 76, if needed by the operand size. If second operand is less than 16 bytes, the valid bytes are left-aligned to the lowest address. @@ -721,10 +721,10 @@ Offset Size Field Description 36.2.1.4. Translate commands - The translate commands takes an input array of indicies, and a table of single bit values indexed by those - indicies, and outputs a bit vector or index array created by reading the tables bit value at each index in + The translate commands takes an input array of indices, and a table of single bit values indexed by those + indices, and outputs a bit vector or index array created by reading the tables bit value at each index in the input array. The output should therefore contain exactly one bit per index in the input data stream, - when outputing as a bit vector. When outputing as an index array, the number of elements depends on the + when outputting as a bit vector. When outputting as an index array, the number of elements depends on the values read in the bit table, but will always be less than, or equal to, the number of input elements. Only a restricted subset of the possible input format types are supported. No variable width or Huffman/OZIP encoded input streams are allowed. The primary input data element size must be 3 bytes or less. @@ -742,7 +742,7 @@ Offset Size Field Description code in the CCB header. There are two supported formats for the output stream: the bit vector and index array formats (codes 0x8, - 0xD, and 0xE). The index array format is an array of indicies of bits which would have been set if the + 0xD, and 0xE). The index array format is an array of indices of bits which would have been set if the output format was a bit array. The return value of the CCB completion area contains the number of bits set in the output bit vector, @@ -1254,7 +1254,7 @@ EUNAVAILABLE The requested CCB operation could not be performed at this time. submitted CCB, or may apply to a larger scope. The status should not be interpreted as permanent, and the guest should attempt to submit CCBs in the future which had previously been unable to be performed. The status - data provides additional information about scope of the retricted availability + data provides additional information about scope of the restricted availability as follows: Value Description 0 Processing for the exact CCB instance submitted was unavailable, @@ -1330,20 +1330,20 @@ EUNAVAILABLE The requested CCB operation could not be performed at this time. of other CCBs ahead of the requested CCB, to provide a relative estimate of when the CCB may execute. The dax return value is only valid when the state is ENQUEUED. The value returned is the DAX unit - instance indentifier for the DAX unit processing the queue where the requested CCB is located. The value + instance identifier for the DAX unit processing the queue where the requested CCB is located. The value matches the value that would have been, or was, returned by ccb_submit using the queue info flag. The queue return value is only valid when the state is ENQUEUED. The value returned is the DAX - queue instance indentifier for the DAX unit processing the queue where the requested CCB is located. The + queue instance identifier for the DAX unit processing the queue where the requested CCB is located. The value matches the value that would have been, or was, returned by ccb_submit using the queue info flag. 36.3.2.1. Errors - EOK The request was proccessed and the CCB state is valid. + EOK The request was processed and the CCB state is valid. EBADALIGN address is not on a 64-byte aligned. ENORADDR The real address provided for address is not valid. EINVAL The CCB completion area contents are not valid. - EWOULDBLOCK Internal resource contraints prevented the CCB state from being queried at this + EWOULDBLOCK Internal resource constraints prevented the CCB state from being queried at this time. The guest should retry the request. ENOACCESS The guest does not have permission to access the coprocessor virtual device functionality. @@ -1401,11 +1401,11 @@ EUNAVAILABLE The requested CCB operation could not be performed at this time. 36.3.3.2. Errors - EOK The request was proccessed and the result is valid. + EOK The request was processed and the result is valid. EBADALIGN address is not on a 64-byte aligned. ENORADDR The real address provided for address is not valid. EINVAL The CCB completion area contents are not valid. - EWOULDBLOCK Internal resource contraints prevented the CCB from being killed at this time. + EWOULDBLOCK Internal resource constraints prevented the CCB from being killed at this time. The guest should retry the request. ENOACCESS The guest does not have permission to access the coprocessor virtual device functionality. @@ -1423,7 +1423,7 @@ EUNAVAILABLE The requested CCB operation could not be performed at this time. 36.3.4.1. Errors - EOK The request was proccessed and the number of enabled/disabled DAX units + EOK The request was processed and the number of enabled/disabled DAX units are valid. diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css index 45a624fdcf2c..084a884f6fb7 100644 --- a/Documentation/sphinx-static/custom.css +++ b/Documentation/sphinx-static/custom.css @@ -11,7 +11,9 @@ div.body h3 { font-size: 130%; } /* Tighten up the layout slightly */ div.body { padding: 0 15px 0 10px; } div.sphinxsidebarwrapper { padding: 1em 0.4em; } -div.sphinxsidebar { font-size: inherit; } +div.sphinxsidebar { font-size: inherit; + max-height: 100%; + overflow-y: auto; } /* Tweak document margins and don't force width */ div.document { margin: 20px 10px 0 10px; @@ -27,3 +29,47 @@ dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; } dl.function dt { margin-left: 10em; text-indent: -10em; } dt.sig-object { font-size: larger; } div.kernelindent { margin-left: 2em; margin-right: 4em; } + +/* + * Tweaks for our local TOC + */ +div.kerneltoc li.toctree-l1 { font-size: smaller; + text-indent: -1em; + margin-left: 1em; } +div.kerneltoc li.current > a {font-weight: bold; } +div.kerneltoc li.toctree-l2,li.toctree-l3 { font-size: small; + text-indent: -1em; + margin-left: 1em; + list-style-type: none; + } +div.kerneltoc li.current ul { margin-left: 0; } +div.kerneltoc { background-color: #eeeeee; } +div.kerneltoc li.current ul { background-color: white; } + +/* + * The CSS magic to toggle the contents on small screens. + */ +label.kernel-toc-title { display: none; } +label.kernel-toc-title:after { + content: "[Hide]"; +} +input[type=checkbox]:checked ~ label.kernel-toc-title:after { + content: "[Show]"; +} +/* Hide the toggle on large screens */ +input.kernel-toc-toggle { display: none; } + +/* + * Show and implement the toggle on small screens. + * The 875px width seems to be wired into alabaster. + */ +@media screen and (max-width: 875px) { + label.kernel-toc-title { display: inline; + font-weight: bold; + font-size: larger; } + input[type=checkbox]:checked ~ div.kerneltoc { + display: none; + } + h3.kernel-toc-contents { display: inline; } + div.kerneltoc a { color: black; } +} diff --git a/Documentation/sphinx/load_config.py b/Documentation/sphinx/load_config.py index eeb394b39e2c..8b416bfd75ac 100644 --- a/Documentation/sphinx/load_config.py +++ b/Documentation/sphinx/load_config.py @@ -3,7 +3,7 @@ import os import sys -from sphinx.util.pycompat import execfile_ +from sphinx.util.osutil import fs_encoding # ------------------------------------------------------------------------------ def loadConfig(namespace): @@ -48,7 +48,9 @@ def loadConfig(namespace): sys.stdout.write("load additional sphinx-config: %s\n" % config_file) config = namespace.copy() config['__file__'] = config_file - execfile_(config_file, config) + with open(config_file, 'rb') as f: + code = compile(f.read(), fs_encoding, 'exec') + exec(code, config) del config['__file__'] namespace.update(config) else: diff --git a/Documentation/sphinx/templates/kernel-toc.html b/Documentation/sphinx/templates/kernel-toc.html new file mode 100644 index 000000000000..b58efa99df52 --- /dev/null +++ b/Documentation/sphinx/templates/kernel-toc.html @@ -0,0 +1,16 @@ +<!-- SPDX-License-Identifier: GPL-2.0 --> +{# Create a local TOC the kernel way #} +<p> +<h3 class="kernel-toc-contents">Contents</h3> +<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked> +<label class="kernel-toc-title" for="kernel-toc-toggle"></label> + +<div class="kerneltoc" id="kerneltoc"> +{{ toctree(maxdepth=3) }} +</div> +{# hacky script to try to position the left column #} +<script type="text/javascript"> <!-- + var sbar = document.getElementsByClassName("sphinxsidebar")[0]; + let currents = document.getElementsByClassName("current") + sbar.scrollTop = currents[currents.length - 1].offsetTop; + --> </script> diff --git a/Documentation/spi/pxa2xx.rst b/Documentation/spi/pxa2xx.rst index 716f65d87d04..04f2a3856c40 100644 --- a/Documentation/spi/pxa2xx.rst +++ b/Documentation/spi/pxa2xx.rst @@ -141,15 +141,15 @@ field. Below is a sample configuration using the PXA255 NSSP. :: static struct pxa2xx_spi_chip cs8415a_chip_info = { - .tx_threshold = 8, /* SSP hardward FIFO threshold */ - .rx_threshold = 8, /* SSP hardward FIFO threshold */ + .tx_threshold = 8, /* SSP hardware FIFO threshold */ + .rx_threshold = 8, /* SSP hardware FIFO threshold */ .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ .timeout = 235, /* See Intel documentation */ }; static struct pxa2xx_spi_chip cs8405a_chip_info = { - .tx_threshold = 8, /* SSP hardward FIFO threshold */ - .rx_threshold = 8, /* SSP hardward FIFO threshold */ + .tx_threshold = 8, /* SSP hardware FIFO threshold */ + .rx_threshold = 8, /* SSP hardware FIFO threshold */ .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ .timeout = 235, /* See Intel documentation */ }; @@ -157,7 +157,7 @@ field. Below is a sample configuration using the PXA255 NSSP. static struct spi_board_info streetracer_spi_board_info[] __initdata = { { .modalias = "cs8415a", /* Name of spi_driver for this device */ - .max_speed_hz = 3686400, /* Run SSP as fast a possbile */ + .max_speed_hz = 3686400, /* Run SSP as fast a possible */ .bus_num = 2, /* Framework bus number */ .chip_select = 0, /* Framework chip select */ .platform_data = NULL; /* No spi_driver specific config */ @@ -166,7 +166,7 @@ field. Below is a sample configuration using the PXA255 NSSP. }, { .modalias = "cs8405a", /* Name of spi_driver for this device */ - .max_speed_hz = 3686400, /* Run SSP as fast a possbile */ + .max_speed_hz = 3686400, /* Run SSP as fast a possible */ .bus_num = 2, /* Framework bus number */ .chip_select = 1, /* Framework chip select */ .controller_data = &cs8405a_chip_info, /* Master chip config */ diff --git a/Documentation/spi/spi-lm70llp.rst b/Documentation/spi/spi-lm70llp.rst index 07631aef4343..0144e12d95bb 100644 --- a/Documentation/spi/spi-lm70llp.rst +++ b/Documentation/spi/spi-lm70llp.rst @@ -57,7 +57,7 @@ devices might share the same SI/SO pin. The bitbanger routine in this driver (lm70_txrx) is called back from the bound "hwmon/lm70" protocol driver through its sysfs hook, using a spi_write_then_read() call. It performs Mode 0 (SPI/Microwire) bitbanging. -The lm70 driver then inteprets the resulting digital temperature value +The lm70 driver then interprets the resulting digital temperature value and exports it through sysfs. A "gotcha": National Semiconductor's LM70 LLP eval board circuit schematic diff --git a/Documentation/spi/spi-summary.rst b/Documentation/spi/spi-summary.rst index aab5d07cb3d7..3c95ae322fb1 100644 --- a/Documentation/spi/spi-summary.rst +++ b/Documentation/spi/spi-summary.rst @@ -105,7 +105,7 @@ find isn't necessarily helpful. The four modes combine two mode bits: - CPHA indicates the clock phase used to sample data; CPHA=0 says sample on the leading edge, CPHA=1 means the trailing edge. - Since the signal needs to stablize before it's sampled, CPHA=0 + Since the signal needs to stabilize before it's sampled, CPHA=0 implies that its data is written half a clock before the first clock edge. The chipselect may have made it become available. diff --git a/Documentation/target/tcmu-design.rst b/Documentation/target/tcmu-design.rst index e47047e32e27..eff3da1d2f68 100644 --- a/Documentation/target/tcmu-design.rst +++ b/Documentation/target/tcmu-design.rst @@ -171,7 +171,7 @@ When the opcode is CMD, the entry in the command ring is a struct tcmu_cmd_entry. Userspace finds the SCSI CDB (Command Data Block) via tcmu_cmd_entry.req.cdb_off. This is an offset from the start of the overall shared memory region, not the entry. The data in/out buffers -are accessible via tht req.iov[] array. iov_cnt contains the number of +are accessible via the req.iov[] array. iov_cnt contains the number of entries in iov[] needed to describe either the Data-In or Data-Out buffers. For bidirectional commands, iov_cnt specifies how many iovec entries cover the Data-Out area, and iov_bidi_cnt specifies how many diff --git a/Documentation/tools/rtla/common_timerlat_aa.rst b/Documentation/tools/rtla/common_timerlat_aa.rst new file mode 100644 index 000000000000..077029e6b289 --- /dev/null +++ b/Documentation/tools/rtla/common_timerlat_aa.rst @@ -0,0 +1,7 @@ +**--dump-tasks** + + prints the task running on all CPUs if stop conditions are met (depends on !--no-aa) + +**--no-aa** + + disable auto-analysis, reducing rtla timerlat cpu usage diff --git a/Documentation/tools/rtla/index.rst b/Documentation/tools/rtla/index.rst index 840f0bf3e803..05d2652e4072 100644 --- a/Documentation/tools/rtla/index.rst +++ b/Documentation/tools/rtla/index.rst @@ -17,6 +17,7 @@ behavior on specific hardware. rtla-timerlat rtla-timerlat-hist rtla-timerlat-top + rtla-hwnoise .. only:: subproject and html diff --git a/Documentation/tools/rtla/rtla-hwnoise.rst b/Documentation/tools/rtla/rtla-hwnoise.rst new file mode 100644 index 000000000000..fb1c52bbc00b --- /dev/null +++ b/Documentation/tools/rtla/rtla-hwnoise.rst @@ -0,0 +1,107 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ +rtla-hwnoise +============ +------------------------------------------ +Detect and quantify hardware-related noise +------------------------------------------ + +:Manual section: 1 + +SYNOPSIS +======== + +**rtla hwnoise** [*OPTIONS*] + +DESCRIPTION +=========== + +**rtla hwnoise** collects the periodic summary from the *osnoise* tracer +running with *interrupts disabled*. By disabling interrupts, and the scheduling +of threads as a consequence, only non-maskable interrupts and hardware-related +noise is allowed. + +The tool also allows the configurations of the *osnoise* tracer and the +collection of the tracer output. + +OPTIONS +======= +.. include:: common_osnoise_options.rst + +.. include:: common_top_options.rst + +.. include:: common_options.rst + +EXAMPLE +======= +In the example below, the **rtla hwnoise** tool is set to run on CPUs *1-7* +on a system with 8 cores/16 threads with hyper-threading enabled. + +The tool is set to detect any noise higher than *one microsecond*, +to run for *ten minutes*, displaying a summary of the report at the +end of the session:: + + # rtla hwnoise -c 1-7 -T 1 -d 10m -q + Hardware-related Noise + duration: 0 00:10:00 | time is in us + CPU Period Runtime Noise % CPU Aval Max Noise Max Single HW NMI + 1 #599 599000000 138 99.99997 3 3 4 74 + 2 #599 599000000 85 99.99998 3 3 4 75 + 3 #599 599000000 86 99.99998 4 3 6 75 + 4 #599 599000000 81 99.99998 4 4 2 75 + 5 #599 599000000 85 99.99998 2 2 2 75 + 6 #599 599000000 76 99.99998 2 2 0 75 + 7 #599 599000000 77 99.99998 3 3 0 75 + + +The first column shows the *CPU*, and the second column shows how many +*Periods* the tool ran during the session. The *Runtime* is the time +the tool effectively runs on the CPU. The *Noise* column is the sum of +all noise that the tool observed, and the *% CPU Aval* is the relation +between the *Runtime* and *Noise*. + +The *Max Noise* column is the maximum hardware noise the tool detected in a +single period, and the *Max Single* is the maximum single noise seen. + +The *HW* and *NMI* columns show the total number of *hardware* and *NMI* noise +occurrence observed by the tool. + +For example, *CPU 3* ran *599* periods of *1 second Runtime*. The CPU received +*86 us* of noise during the entire execution, leaving *99.99997 %* of CPU time +for the application. In the worst single period, the CPU caused *4 us* of +noise to the application, but it was certainly caused by more than one single +noise, as the *Max Single* noise was of *3 us*. The CPU has *HW noise,* at a +rate of *six occurrences*/*ten minutes*. The CPU also has *NMIs*, at a higher +frequency: around *seven per second*. + +The tool should report *0* hardware-related noise in the ideal situation. +For example, by disabling hyper-threading to remove the hardware noise, +and disabling the TSC watchdog to remove the NMI (it is possible to identify +this using tracing options of **rtla hwnoise**), it was possible to reach +the ideal situation in the same hardware:: + + # rtla hwnoise -c 1-7 -T 1 -d 10m -q + Hardware-related Noise + duration: 0 00:10:00 | time is in us + CPU Period Runtime Noise % CPU Aval Max Noise Max Single HW NMI + 1 #599 599000000 0 100.00000 0 0 0 0 + 2 #599 599000000 0 100.00000 0 0 0 0 + 3 #599 599000000 0 100.00000 0 0 0 0 + 4 #599 599000000 0 100.00000 0 0 0 0 + 5 #599 599000000 0 100.00000 0 0 0 0 + 6 #599 599000000 0 100.00000 0 0 0 0 + 7 #599 599000000 0 100.00000 0 0 0 0 + +SEE ALSO +======== + +**rtla-osnoise**\(1) + +Osnoise tracer documentation: <https://www.kernel.org/doc/html/latest/trace/osnoise-tracer.html> + +AUTHOR +====== +Written by Daniel Bristot de Oliveira <bristot@kernel.org> + +.. include:: common_appendix.rst diff --git a/Documentation/tools/rtla/rtla-timerlat-top.rst b/Documentation/tools/rtla/rtla-timerlat-top.rst index 7c4e4b109493..73799c1150ad 100644 --- a/Documentation/tools/rtla/rtla-timerlat-top.rst +++ b/Documentation/tools/rtla/rtla-timerlat-top.rst @@ -30,102 +30,84 @@ OPTIONS .. include:: common_options.rst +.. include:: common_timerlat_aa.rst + EXAMPLE ======= -In the example below, the *timerlat* tracer is set to capture the stack trace at -the IRQ handler, printing it to the buffer if the *Thread* timer latency is -higher than *30 us*. It is also set to stop the session if a *Thread* timer -latency higher than *30 us* is hit. Finally, it is set to save the trace -buffer if the stop condition is hit:: +In the example below, the timerlat tracer is dispatched in cpus *1-23* in the +automatic trace mode, instructing the tracer to stop if a *40 us* latency or +higher is found:: - [root@alien ~]# rtla timerlat top -s 30 -T 30 -t - Timer Latency - 0 00:00:59 | IRQ Timer Latency (us) | Thread Timer Latency (us) + # timerlat -a 40 -c 1-23 -q + Timer Latency + 0 00:00:12 | IRQ Timer Latency (us) | Thread Timer Latency (us) CPU COUNT | cur min avg max | cur min avg max - 0 #58634 | 1 0 1 10 | 11 2 10 23 - 1 #58634 | 1 0 1 9 | 12 2 9 23 - 2 #58634 | 0 0 1 11 | 10 2 9 23 - 3 #58634 | 1 0 1 11 | 11 2 9 24 - 4 #58634 | 1 0 1 10 | 11 2 9 26 - 5 #58634 | 1 0 1 8 | 10 2 9 25 - 6 #58634 | 12 0 1 12 | 30 2 10 30 <--- CPU with spike - 7 #58634 | 1 0 1 9 | 11 2 9 23 - 8 #58633 | 1 0 1 9 | 11 2 9 26 - 9 #58633 | 1 0 1 9 | 10 2 9 26 - 10 #58633 | 1 0 1 13 | 11 2 9 28 - 11 #58633 | 1 0 1 13 | 12 2 9 24 - 12 #58633 | 1 0 1 8 | 10 2 9 23 - 13 #58633 | 1 0 1 10 | 10 2 9 22 - 14 #58633 | 1 0 1 18 | 12 2 9 27 - 15 #58633 | 1 0 1 10 | 11 2 9 28 - 16 #58633 | 0 0 1 11 | 7 2 9 26 - 17 #58633 | 1 0 1 13 | 10 2 9 24 - 18 #58633 | 1 0 1 9 | 13 2 9 22 - 19 #58633 | 1 0 1 10 | 11 2 9 23 - 20 #58633 | 1 0 1 12 | 11 2 9 28 - 21 #58633 | 1 0 1 14 | 11 2 9 24 - 22 #58633 | 1 0 1 8 | 11 2 9 22 - 23 #58633 | 1 0 1 10 | 11 2 9 27 - timerlat hit stop tracing - saving trace to timerlat_trace.txt - [root@alien bristot]# tail -60 timerlat_trace.txt - [...] - timerlat/5-79755 [005] ....... 426.271226: #58634 context thread timer_latency 10823 ns - sh-109404 [006] dnLh213 426.271247: #58634 context irq timer_latency 12505 ns - sh-109404 [006] dNLh313 426.271258: irq_noise: local_timer:236 start 426.271245463 duration 12553 ns - sh-109404 [006] d...313 426.271263: thread_noise: sh:109404 start 426.271245853 duration 4769 ns - timerlat/6-79756 [006] ....... 426.271264: #58634 context thread timer_latency 30328 ns - timerlat/6-79756 [006] ....1.. 426.271265: <stack trace> - => timerlat_irq - => __hrtimer_run_queues - => hrtimer_interrupt - => __sysvec_apic_timer_interrupt - => sysvec_apic_timer_interrupt - => asm_sysvec_apic_timer_interrupt - => _raw_spin_unlock_irqrestore <---- spinlock that disabled interrupt. - => try_to_wake_up - => autoremove_wake_function - => __wake_up_common - => __wake_up_common_lock - => ep_poll_callback - => __wake_up_common - => __wake_up_common_lock - => fsnotify_add_event - => inotify_handle_inode_event - => fsnotify - => __fsnotify_parent - => __fput - => task_work_run - => exit_to_user_mode_prepare - => syscall_exit_to_user_mode - => do_syscall_64 - => entry_SYSCALL_64_after_hwframe - => 0x7265000001378c - => 0x10000cea7 - => 0x25a00000204a - => 0x12e302d00000000 - => 0x19b51010901b6 - => 0x283ce00726500 - => 0x61ea308872 - => 0x00000fe3 - bash-109109 [007] d..h... 426.271265: #58634 context irq timer_latency 1211 ns - timerlat/6-79756 [006] ....... 426.271267: timerlat_main: stop tracing hit on cpu 6 - -In the trace, it is possible the notice that the *IRQ* timer latency was -already high, accounting *12505 ns*. The IRQ delay was caused by the -*bash-109109* process that disabled IRQs in the wake-up path -(*_try_to_wake_up()* function). The duration of the IRQ handler that woke -up the timerlat thread, informed with the **osnoise:irq_noise** event, was -also high and added more *12553 ns* to the Thread latency. Finally, the -**osnoise:thread_noise** added by the currently running thread (including -the scheduling overhead) added more *4769 ns*. Summing up these values, -the *Thread* timer latency accounted for *30328 ns*. - -The primary reason for this high value is the wake-up path that was hit -twice during this case: when the *bash-109109* was waking up a thread -and then when the *timerlat* thread was awakened. This information can -then be used as the starting point of a more fine-grained analysis. + 1 #12322 | 0 0 1 15 | 10 3 9 31 + 2 #12322 | 3 0 1 12 | 10 3 9 23 + 3 #12322 | 1 0 1 21 | 8 2 8 34 + 4 #12322 | 1 0 1 17 | 10 2 11 33 + 5 #12322 | 0 0 1 12 | 8 3 8 25 + 6 #12322 | 1 0 1 14 | 16 3 11 35 + 7 #12322 | 0 0 1 14 | 9 2 8 29 + 8 #12322 | 1 0 1 22 | 9 3 9 34 + 9 #12322 | 0 0 1 14 | 8 2 8 24 + 10 #12322 | 1 0 0 12 | 9 3 8 24 + 11 #12322 | 0 0 0 15 | 6 2 7 29 + 12 #12321 | 1 0 0 13 | 5 3 8 23 + 13 #12319 | 0 0 1 14 | 9 3 9 26 + 14 #12321 | 1 0 0 13 | 6 2 8 24 + 15 #12321 | 1 0 1 15 | 12 3 11 27 + 16 #12318 | 0 0 1 13 | 7 3 10 24 + 17 #12319 | 0 0 1 13 | 11 3 9 25 + 18 #12318 | 0 0 0 12 | 8 2 8 20 + 19 #12319 | 0 0 1 18 | 10 2 9 28 + 20 #12317 | 0 0 0 20 | 9 3 8 34 + 21 #12318 | 0 0 0 13 | 8 3 8 28 + 22 #12319 | 0 0 1 11 | 8 3 10 22 + 23 #12320 | 28 0 1 28 | 41 3 11 41 + rtla timerlat hit stop tracing + ## CPU 23 hit stop tracing, analyzing it ## + IRQ handler delay: 27.49 us (65.52 %) + IRQ latency: 28.13 us + Timerlat IRQ duration: 9.59 us (22.85 %) + Blocking thread: 3.79 us (9.03 %) + objtool:49256 3.79 us + Blocking thread stacktrace + -> timerlat_irq + -> __hrtimer_run_queues + -> hrtimer_interrupt + -> __sysvec_apic_timer_interrupt + -> sysvec_apic_timer_interrupt + -> asm_sysvec_apic_timer_interrupt + -> _raw_spin_unlock_irqrestore + -> cgroup_rstat_flush_locked + -> cgroup_rstat_flush_irqsafe + -> mem_cgroup_flush_stats + -> mem_cgroup_wb_stats + -> balance_dirty_pages + -> balance_dirty_pages_ratelimited_flags + -> btrfs_buffered_write + -> btrfs_do_write_iter + -> vfs_write + -> __x64_sys_pwrite64 + -> do_syscall_64 + -> entry_SYSCALL_64_after_hwframe + ------------------------------------------------------------------------ + Thread latency: 41.96 us (100%) + + The system has exit from idle latency! + Max timerlat IRQ latency from idle: 17.48 us in cpu 4 + Saving trace to timerlat_trace.txt + +In this case, the major factor was the delay suffered by the *IRQ handler* +that handles **timerlat** wakeup: *65.52%*. This can be caused by the +current thread masking interrupts, which can be seen in the blocking +thread stacktrace: the current thread (*objtool:49256*) disabled interrupts +via *raw spin lock* operations inside mem cgroup, while doing write +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 diff --git a/Documentation/trace/coresight/coresight-tpda.rst b/Documentation/trace/coresight/coresight-tpda.rst new file mode 100644 index 000000000000..a37f387ceaea --- /dev/null +++ b/Documentation/trace/coresight/coresight-tpda.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================================================= +The trace performance monitoring and diagnostics aggregator(TPDA) +================================================================= + + :Author: Jinlong Mao <quic_jinlmao@quicinc.com> + :Date: January 2023 + +Hardware Description +-------------------- + +TPDA - The trace performance monitoring and diagnostics aggregator or +TPDA in short serves as an arbitration and packetization engine for the +performance monitoring and diagnostics network specification. +The primary use case of the TPDA is to provide packetization, funneling +and timestamping of Monitor data. + + +Sysfs files and directories +--------------------------- +Root: ``/sys/bus/coresight/devices/tpda<N>`` + +Config details +--------------------------- + +The tpdm and tpda nodes should be observed at the coresight path +"/sys/bus/coresight/devices". +e.g. +/sys/bus/coresight/devices # ls -l | grep tpd +tpda0 -> ../../../devices/platform/soc@0/6004000.tpda/tpda0 +tpdm0 -> ../../../devices/platform/soc@0/6c08000.mm.tpdm/tpdm0 + +We can use the commands are similar to the below to validate TPDMs. +Enable coresight sink first. The port of tpda which is connected to +the tpdm will be enabled after commands below. + +echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink +echo 1 > /sys/bus/coresight/devices/tpdm0/enable_source +echo 1 > /sys/bus/coresight/devices/tpdm0/integration_test +echo 2 > /sys/bus/coresight/devices/tpdm0/integration_test + +The test data will be collected in the coresight sink which is enabled. +If rwp register of the sink is keeping updating when do +integration_test (by cat tmc_etf0/mgmt/rwp), it means there is data +generated from TPDM to sink. + +There must be a tpda between tpdm and the sink. When there are some +other trace event hw components in the same HW block with tpdm, tpdm +and these hw components will connect to the coresight funnel. When +there is only tpdm trace hw in the HW block, tpdm will connect to +tpda directly. diff --git a/Documentation/trace/coresight/coresight-tpdm.rst b/Documentation/trace/coresight/coresight-tpdm.rst new file mode 100644 index 000000000000..72fd5c855d45 --- /dev/null +++ b/Documentation/trace/coresight/coresight-tpdm.rst @@ -0,0 +1,45 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================================================== +Trace performance monitoring and diagnostics monitor(TPDM) +========================================================== + + :Author: Jinlong Mao <quic_jinlmao@quicinc.com> + :Date: January 2023 + +Hardware Description +-------------------- +TPDM - The trace performance monitoring and diagnostics monitor or TPDM in +short serves as data collection component for various dataset types. +The primary use case of the TPDM is to collect data from different data +sources and send it to a TPDA for packetization, timestamping and funneling. + +Sysfs files and directories +--------------------------- +Root: ``/sys/bus/coresight/devices/tpdm<N>`` + +---- + +:File: ``enable_source`` (RW) +:Notes: + - > 0 : enable the datasets of TPDM. + + - = 0 : disable the datasets of TPDM. + +:Syntax: + ``echo 1 > enable_source`` + +---- + +:File: ``integration_test`` (wo) +:Notes: + Integration test will generate test data for tpdm. + +:Syntax: + ``echo value > integration_test`` + + value - 1 or 2. + +---- + +.. This text is intentionally added to make Sphinx happy. diff --git a/Documentation/trace/coresight/ultrasoc-smb.rst b/Documentation/trace/coresight/ultrasoc-smb.rst new file mode 100644 index 000000000000..a05488a75ff0 --- /dev/null +++ b/Documentation/trace/coresight/ultrasoc-smb.rst @@ -0,0 +1,83 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================================== +UltraSoc - HW Assisted Tracing on SoC +====================================== + :Author: Qi Liu <liuqi115@huawei.com> + :Date: January 2023 + +Introduction +------------ + +UltraSoc SMB is a per SCCL (Super CPU Cluster) hardware. It provides a +way to buffer and store CPU trace messages in a region of shared system +memory. The device acts as a coresight sink device and the +corresponding trace generators (ETM) are attached as source devices. + +Sysfs files and directories +--------------------------- + +The SMB devices appear on the existing coresight bus alongside other +devices:: + + $# ls /sys/bus/coresight/devices/ + ultra_smb0 ultra_smb1 ultra_smb2 ultra_smb3 + +The ``ultra_smb<N>`` names SMB device associated with SCCL.:: + + $# ls /sys/bus/coresight/devices/ultra_smb0 + enable_sink mgmt + $# ls /sys/bus/coresight/devices/ultra_smb0/mgmt + buf_size buf_status read_pos write_pos + +Key file items are: + + * ``read_pos``: Shows the value on the read pointer register. + * ``write_pos``: Shows the value on the write pointer register. + * ``buf_status``: Shows the value on the status register. + BIT(0) is zero value which means the buffer is empty. + * ``buf_size``: Shows the buffer size of each device. + +Firmware Bindings +----------------- + +The device is only supported with ACPI. Its binding describes device +identifier, resource information and graph structure. + +The device is identified as ACPI HID "HISI03A1". Device resources are allocated +using the _CRS method. Each device must present two base address; the first one +is the configuration base address of the device, the second one is the 32-bit +base address of shared system memory. + +Example:: + + Device(USMB) { \ + Name(_HID, "HISI03A1") \ + Name(_CRS, ResourceTemplate() { \ + QWordMemory (ResourceConsumer, , MinFixed, MaxFixed, NonCacheable, \ + ReadWrite, 0x0, 0x95100000, 0x951FFFFF, 0x0, 0x100000) \ + QWordMemory (ResourceConsumer, , MinFixed, MaxFixed, Cacheable, \ + ReadWrite, 0x0, 0x50000000, 0x53FFFFFF, 0x0, 0x4000000) \ + }) \ + Name(_DSD, Package() { \ + ToUUID("ab02a46b-74c7-45a2-bd68-f7d344ef2153"), \ + /* Use CoreSight Graph ACPI bindings to describe connections topology */ + Package() { \ + 0, \ + 1, \ + Package() { \ + 1, \ + ToUUID("3ecbc8b6-1d0e-4fb3-8107-e627f805c6cd"), \ + 8, \ + Package() {0x8, 0, \_SB.S00.SL11.CL28.F008, 0}, \ + Package() {0x9, 0, \_SB.S00.SL11.CL29.F009, 0}, \ + Package() {0xa, 0, \_SB.S00.SL11.CL2A.F010, 0}, \ + Package() {0xb, 0, \_SB.S00.SL11.CL2B.F011, 0}, \ + Package() {0xc, 0, \_SB.S00.SL11.CL2C.F012, 0}, \ + Package() {0xd, 0, \_SB.S00.SL11.CL2D.F013, 0}, \ + Package() {0xe, 0, \_SB.S00.SL11.CL2E.F014, 0}, \ + Package() {0xf, 0, \_SB.S00.SL11.CL2F.F015, 0}, \ + } \ + } \ + }) \ + } diff --git a/Documentation/trace/events-msr.rst b/Documentation/trace/events-msr.rst index 810481e530b6..35d06dc66bc2 100644 --- a/Documentation/trace/events-msr.rst +++ b/Documentation/trace/events-msr.rst @@ -8,7 +8,7 @@ at https://www.intel.com/sdm (Volume 3) Available trace points: -/sys/kernel/debug/tracing/events/msr/ +/sys/kernel/tracing/events/msr/ Trace MSR reads: @@ -34,7 +34,7 @@ rdpmc The trace data can be post processed with the postprocess/decode_msr.py script:: - cat /sys/kernel/debug/tracing/trace | decode_msr.py /usr/src/linux/include/asm/msr-index.h + cat /sys/kernel/tracing/trace | decode_msr.py /usr/src/linux/include/asm/msr-index.h to add symbolic MSR names. diff --git a/Documentation/trace/events-nmi.rst b/Documentation/trace/events-nmi.rst index 9e0a7289d80a..22ac1be0ea6f 100644 --- a/Documentation/trace/events-nmi.rst +++ b/Documentation/trace/events-nmi.rst @@ -4,7 +4,7 @@ NMI Trace Events These events normally show up here: - /sys/kernel/debug/tracing/events/nmi + /sys/kernel/tracing/events/nmi nmi_handler @@ -31,13 +31,13 @@ really hogging a lot of CPU time, like a millisecond at a time. Note that the kernel's output is in milliseconds, but the input to the filter is in nanoseconds! You can filter on 'delta_ns':: - cd /sys/kernel/debug/tracing/events/nmi/nmi_handler + cd /sys/kernel/tracing/events/nmi/nmi_handler echo 'handler==0xffffffff81625600 && delta_ns>1000000' > filter echo 1 > enable Your output would then look like:: - $ cat /sys/kernel/debug/tracing/trace_pipe + $ cat /sys/kernel/tracing/trace_pipe <idle>-0 [000] d.h3 505.397558: nmi_handler: perf_event_nmi_handler() delta_ns: 3236765 handled: 1 <idle>-0 [000] d.h3 505.805893: nmi_handler: perf_event_nmi_handler() delta_ns: 3174234 handled: 1 <idle>-0 [000] d.h3 506.158206: nmi_handler: perf_event_nmi_handler() delta_ns: 3084642 handled: 1 diff --git a/Documentation/trace/events.rst b/Documentation/trace/events.rst index c47f381d0c00..f5fcb8e1218f 100644 --- a/Documentation/trace/events.rst +++ b/Documentation/trace/events.rst @@ -24,27 +24,27 @@ tracing information should be printed. --------------------------------- The events which are available for tracing can be found in the file -/sys/kernel/debug/tracing/available_events. +/sys/kernel/tracing/available_events. To enable a particular event, such as 'sched_wakeup', simply echo it -to /sys/kernel/debug/tracing/set_event. For example:: +to /sys/kernel/tracing/set_event. For example:: - # echo sched_wakeup >> /sys/kernel/debug/tracing/set_event + # echo sched_wakeup >> /sys/kernel/tracing/set_event .. Note:: '>>' is necessary, otherwise it will firstly disable all the events. To disable an event, echo the event name to the set_event file prefixed with an exclamation point:: - # echo '!sched_wakeup' >> /sys/kernel/debug/tracing/set_event + # echo '!sched_wakeup' >> /sys/kernel/tracing/set_event To disable all events, echo an empty line to the set_event file:: - # echo > /sys/kernel/debug/tracing/set_event + # echo > /sys/kernel/tracing/set_event To enable all events, echo ``*:*`` or ``*:`` to the set_event file:: - # echo *:* > /sys/kernel/debug/tracing/set_event + # echo *:* > /sys/kernel/tracing/set_event The events are organized into subsystems, such as ext4, irq, sched, etc., and a full event name looks like this: <subsystem>:<event>. The @@ -53,29 +53,29 @@ file. All of the events in a subsystem can be specified via the syntax ``<subsystem>:*``; for example, to enable all irq events, you can use the command:: - # echo 'irq:*' > /sys/kernel/debug/tracing/set_event + # echo 'irq:*' > /sys/kernel/tracing/set_event 2.2 Via the 'enable' toggle --------------------------- -The events available are also listed in /sys/kernel/debug/tracing/events/ hierarchy +The events available are also listed in /sys/kernel/tracing/events/ hierarchy of directories. To enable event 'sched_wakeup':: - # echo 1 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable + # echo 1 > /sys/kernel/tracing/events/sched/sched_wakeup/enable To disable it:: - # echo 0 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable + # echo 0 > /sys/kernel/tracing/events/sched/sched_wakeup/enable To enable all events in sched subsystem:: - # echo 1 > /sys/kernel/debug/tracing/events/sched/enable + # echo 1 > /sys/kernel/tracing/events/sched/enable To enable all events:: - # echo 1 > /sys/kernel/debug/tracing/events/enable + # echo 1 > /sys/kernel/tracing/events/enable When reading one of these enable files, there are four results: @@ -126,7 +126,7 @@ is the size of the data item, in bytes. For example, here's the information displayed for the 'sched_wakeup' event:: - # cat /sys/kernel/debug/tracing/events/sched/sched_wakeup/format + # cat /sys/kernel/tracing/events/sched/sched_wakeup/format name: sched_wakeup ID: 60 @@ -207,6 +207,18 @@ field name:: As the kernel will have to know how to retrieve the memory that the pointer is at from user space. +You can convert any long type to a function address and search by function name:: + + call_site.function == security_prepare_creds + +The above will filter when the field "call_site" falls on the address within +"security_prepare_creds". That is, it will compare the value of "call_site" and +the filter will return true if it is greater than or equal to the start of +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 "!=". + 5.2 Setting filters ------------------- @@ -215,19 +227,19 @@ to the 'filter' file for the given event. For example:: - # cd /sys/kernel/debug/tracing/events/sched/sched_wakeup + # cd /sys/kernel/tracing/events/sched/sched_wakeup # echo "common_preempt_count > 4" > filter A slightly more involved example:: - # cd /sys/kernel/debug/tracing/events/signal/signal_generate + # cd /sys/kernel/tracing/events/signal/signal_generate # echo "((sig >= 10 && sig < 15) || sig == 17) && comm != bash" > filter If there is an error in the expression, you'll get an 'Invalid argument' error when setting it, and the erroneous string along with an error message can be seen by looking at the filter e.g.:: - # cd /sys/kernel/debug/tracing/events/signal/signal_generate + # cd /sys/kernel/tracing/events/signal/signal_generate # echo "((sig >= 10 && sig < 15) || dsig == 17) && comm != bash" > filter -bash: echo: write error: Invalid argument # cat filter @@ -258,7 +270,7 @@ file. To clear the filters for all events in a subsystem, write a '0' to the subsystem's filter file. -5.3 Subsystem filters +5.4 Subsystem filters --------------------- For convenience, filters for every event in a subsystem can be set or @@ -277,7 +289,7 @@ above points: Clear the filters on all events in the sched subsystem:: - # cd /sys/kernel/debug/tracing/events/sched + # cd /sys/kernel/tracing/events/sched # echo 0 > filter # cat sched_switch/filter none @@ -287,7 +299,7 @@ Clear the filters on all events in the sched subsystem:: Set a filter using only common fields for all events in the sched subsystem (all events end up with the same filter):: - # cd /sys/kernel/debug/tracing/events/sched + # cd /sys/kernel/tracing/events/sched # echo common_pid == 0 > filter # cat sched_switch/filter common_pid == 0 @@ -298,14 +310,14 @@ Attempt to set a filter using a non-common field for all events in the sched subsystem (all events but those that have a prev_pid field retain their old filters):: - # cd /sys/kernel/debug/tracing/events/sched + # cd /sys/kernel/tracing/events/sched # echo prev_pid == 0 > filter # cat sched_switch/filter prev_pid == 0 # cat sched_wakeup/filter common_pid == 0 -5.4 PID filtering +5.5 PID filtering ----------------- The set_event_pid file in the same directory as the top events directory @@ -313,7 +325,7 @@ exists, will filter all events from tracing any task that does not have the PID listed in the set_event_pid file. :: - # cd /sys/kernel/debug/tracing + # cd /sys/kernel/tracing # echo $$ > set_event_pid # echo 1 > events/enable @@ -409,14 +421,14 @@ The following commands are supported: specifies that this enablement happens only once:: # echo 'enable_event:kmem:kmalloc:1' > \ - /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger + /sys/kernel/tracing/events/syscalls/sys_enter_read/trigger The following trigger causes kmalloc events to stop being traced when a read system call exits. This disablement happens on every read system call exit:: # echo 'disable_event:kmem:kmalloc' > \ - /sys/kernel/debug/tracing/events/syscalls/sys_exit_read/trigger + /sys/kernel/tracing/events/syscalls/sys_exit_read/trigger The format is:: @@ -426,10 +438,10 @@ The following commands are supported: To remove the above commands:: # echo '!enable_event:kmem:kmalloc:1' > \ - /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger + /sys/kernel/tracing/events/syscalls/sys_enter_read/trigger # echo '!disable_event:kmem:kmalloc' > \ - /sys/kernel/debug/tracing/events/syscalls/sys_exit_read/trigger + /sys/kernel/tracing/events/syscalls/sys_exit_read/trigger Note that there can be any number of enable/disable_event triggers per triggering event, but there can only be one trigger per @@ -448,13 +460,13 @@ The following commands are supported: kmalloc tracepoint is hit:: # echo 'stacktrace' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger The following trigger dumps a stacktrace the first 5 times a kmalloc request happens with a size >= 64K:: # echo 'stacktrace:5 if bytes_req >= 65536' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger The format is:: @@ -463,16 +475,16 @@ The following commands are supported: To remove the above commands:: # echo '!stacktrace' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger # echo '!stacktrace:5 if bytes_req >= 65536' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger The latter can also be removed more simply by the following (without the filter):: # echo '!stacktrace:5' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger Note that there can be only one stacktrace trigger per triggering event. @@ -488,20 +500,20 @@ The following commands are supported: capture those events when the trigger event occurred:: # echo 'snapshot if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger + /sys/kernel/tracing/events/block/block_unplug/trigger To only snapshot once:: # echo 'snapshot:1 if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger + /sys/kernel/tracing/events/block/block_unplug/trigger To remove the above commands:: # echo '!snapshot if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger + /sys/kernel/tracing/events/block/block_unplug/trigger # echo '!snapshot:1 if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger + /sys/kernel/tracing/events/block/block_unplug/trigger Note that there can be only one snapshot trigger per triggering event. @@ -519,20 +531,20 @@ The following commands are supported: trigger event:: # echo 'traceoff:1 if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger + /sys/kernel/tracing/events/block/block_unplug/trigger To always disable tracing when nr_rq > 1:: # echo 'traceoff if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger + /sys/kernel/tracing/events/block/block_unplug/trigger To remove the above commands:: # echo '!traceoff:1 if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger + /sys/kernel/tracing/events/block/block_unplug/trigger # echo '!traceoff if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger + /sys/kernel/tracing/events/block/block_unplug/trigger Note that there can be only one traceon or traceoff trigger per triggering event. diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index 21f01d32c959..b927fb2b94dc 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -830,10 +830,10 @@ Error conditions The extended error information and usage takes the form shown in this example:: - # echo xxx > /sys/kernel/debug/tracing/events/sched/sched_wakeup/trigger + # echo xxx > /sys/kernel/tracing/events/sched/sched_wakeup/trigger echo: write error: Invalid argument - # cat /sys/kernel/debug/tracing/error_log + # cat /sys/kernel/tracing/error_log [ 5348.887237] location: error: Couldn't yyy: zzz Command: xxx ^ @@ -843,7 +843,7 @@ Error conditions To clear the error log, echo the empty string into it:: - # echo > /sys/kernel/debug/tracing/error_log + # echo > /sys/kernel/tracing/error_log Examples of using the tracer ---------------------------- diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst index 088c8cce738b..5765eb3e9efa 100644 --- a/Documentation/trace/histogram-design.rst +++ b/Documentation/trace/histogram-design.rst @@ -14,7 +14,7 @@ tracing_map.c. Note: All the ftrace histogram command examples assume the working directory is the ftrace /tracing directory. For example:: - # cd /sys/kernel/debug/tracing + # cd /sys/kernel/tracing Also, the histogram output displayed for those commands will be generally be truncated - only enough to make the point is displayed. @@ -905,7 +905,7 @@ means it will be automatically converted into a field variable:: # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0: \ onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid)' >> - /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + /sys/kernel/tracing/events/sched/sched_switch/trigger The diagram for the sched_switch event is similar to previous examples but shows the additional field_vars[] array for hist_data and shows @@ -1112,7 +1112,7 @@ sched_switch event fields, next_pid and next_comm, to generate a wakeup_latency trace event. The next_pid and next_comm event fields are automatically converted into field variables for this purpose:: - # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid,next_comm)' >> /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid,next_comm)' >> /sys/kernel/tracing/events/sched/sched_switch/trigger The sched_waking hist_debug output shows the same data as in the previous test example:: @@ -1305,7 +1305,7 @@ and event name for the onmatch() handler:: The commands below can be used to clean things up for the next test:: - # echo '!hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid,next_comm)' >> /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + # echo '!hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid,next_comm)' >> /sys/kernel/tracing/events/sched/sched_switch/trigger # echo '!hist:keys=pid:ts0=common_timestamp.usecs' >> events/sched/sched_waking/trigger @@ -1363,13 +1363,13 @@ with the save() and snapshot() actions. For example:: # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0: \ onmax($wakeup_lat).save(next_comm,prev_pid,prev_prio,prev_comm)' >> - /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + /sys/kernel/tracing/events/sched/sched_switch/trigger or:: # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0: \ onmax($wakeup_lat).snapshot()' >> - /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + /sys/kernel/tracing/events/sched/sched_switch/trigger save() action field variable test --------------------------------- diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst index f95459aa984f..479c9eac6335 100644 --- a/Documentation/trace/histogram.rst +++ b/Documentation/trace/histogram.rst @@ -81,6 +81,7 @@ Documentation written by Tom Zanussi .usecs display a common_timestamp in microseconds .percent display a number of percentage value .graph display a bar-graph of a value + .stacktrace display as a stacktrace (must by a long[] type) ============= ================================================= Note that in general the semantics of a given field aren't @@ -102,12 +103,12 @@ Documentation written by Tom Zanussi trigger, read its current contents, and then turn it off:: # echo 'hist:keys=skbaddr.hex:vals=len' > \ - /sys/kernel/debug/tracing/events/net/netif_rx/trigger + /sys/kernel/tracing/events/net/netif_rx/trigger - # cat /sys/kernel/debug/tracing/events/net/netif_rx/hist + # cat /sys/kernel/tracing/events/net/netif_rx/hist # echo '!hist:keys=skbaddr.hex:vals=len' > \ - /sys/kernel/debug/tracing/events/net/netif_rx/trigger + /sys/kernel/tracing/events/net/netif_rx/trigger The trigger file itself can be read to show the details of the currently attached hist trigger. This information is also displayed @@ -169,13 +170,13 @@ Documentation written by Tom Zanussi aggregation on and off when conditions of interest are hit:: # echo 'hist:keys=skbaddr.hex:vals=len:pause' > \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger # echo 'enable_hist:net:netif_receive_skb if filename==/usr/bin/wget' > \ - /sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger + /sys/kernel/tracing/events/sched/sched_process_exec/trigger # echo 'disable_hist:net:netif_receive_skb if comm==wget' > \ - /sys/kernel/debug/tracing/events/sched/sched_process_exit/trigger + /sys/kernel/tracing/events/sched/sched_process_exit/trigger The above sets up an initially paused hist trigger which is unpaused and starts aggregating events when a given program is executed, and @@ -218,7 +219,7 @@ Extended error information event. The fields that can be used for the hist trigger are listed in the kmalloc event's format file:: - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/format + # cat /sys/kernel/tracing/events/kmem/kmalloc/format name: kmalloc ID: 374 format: @@ -238,7 +239,7 @@ Extended error information the kernel that made one or more calls to kmalloc:: # echo 'hist:key=call_site:val=bytes_req.buckets=32' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger This tells the tracing system to create a 'hist' trigger using the call_site field of the kmalloc event as the key for the table, which @@ -252,7 +253,7 @@ Extended error information file in the kmalloc event's subdirectory (for readability, a number of entries have been omitted):: - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist + # cat /sys/kernel/tracing/events/kmem/kmalloc/hist # trigger info: hist:keys=call_site:vals=bytes_req:sort=hitcount:size=2048 [active] { call_site: 18446744072106379007 } hitcount: 1 bytes_req: 176 @@ -292,7 +293,7 @@ Extended error information the trigger info, which can also be displayed by reading the 'trigger' file:: - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + # cat /sys/kernel/tracing/events/kmem/kmalloc/trigger hist:keys=call_site:vals=bytes_req:sort=hitcount:size=2048 [active] At the end of the output are a few lines that display the overall @@ -323,7 +324,7 @@ Extended error information command history and re-execute it with a '!' prepended:: # echo '!hist:key=call_site:val=bytes_req' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger Finally, notice that the call_site as displayed in the output above isn't really very useful. It's an address, but normally addresses @@ -331,9 +332,9 @@ Extended error information value, simply append '.hex' to the field name in the trigger:: # echo 'hist:key=call_site.hex:val=bytes_req' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist + # cat /sys/kernel/tracing/events/kmem/kmalloc/hist # trigger info: hist:keys=call_site.hex:vals=bytes_req:sort=hitcount:size=2048 [active] { call_site: ffffffffa026b291 } hitcount: 1 bytes_req: 433 @@ -376,9 +377,9 @@ Extended error information trigger:: # echo 'hist:key=call_site.sym:val=bytes_req' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist + # cat /sys/kernel/tracing/events/kmem/kmalloc/hist # trigger info: hist:keys=call_site.sym:vals=bytes_req:sort=hitcount:size=2048 [active] { call_site: [ffffffff810adcb9] syslog_print_all } hitcount: 1 bytes_req: 1024 @@ -426,9 +427,9 @@ Extended error information the 'sort' parameter, along with the 'descending' modifier:: # echo 'hist:key=call_site.sym:val=bytes_req:sort=bytes_req.descending' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist + # cat /sys/kernel/tracing/events/kmem/kmalloc/hist # trigger info: hist:keys=call_site.sym:vals=bytes_req:sort=bytes_req.descending:size=2048 [active] { call_site: [ffffffffa046041c] i915_gem_execbuffer2 [i915] } hitcount: 2186 bytes_req: 3397464 @@ -467,9 +468,9 @@ Extended error information name, just use 'sym-offset' instead:: # echo 'hist:key=call_site.sym-offset:val=bytes_req:sort=bytes_req.descending' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist + # cat /sys/kernel/tracing/events/kmem/kmalloc/hist # trigger info: hist:keys=call_site.sym-offset:vals=bytes_req:sort=bytes_req.descending:size=2048 [active] { call_site: [ffffffffa046041c] i915_gem_execbuffer2+0x6c/0x2c0 [i915] } hitcount: 4569 bytes_req: 3163720 @@ -506,9 +507,9 @@ Extended error information allocated in a descending order:: # echo 'hist:keys=call_site.sym:values=bytes_req,bytes_alloc:sort=bytes_alloc.descending' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist + # cat /sys/kernel/tracing/events/kmem/kmalloc/hist # trigger info: hist:keys=call_site.sym:vals=bytes_req,bytes_alloc:sort=bytes_alloc.descending:size=2048 [active] { call_site: [ffffffffa046041c] i915_gem_execbuffer2 [i915] } hitcount: 7403 bytes_req: 4084360 bytes_alloc: 5958016 @@ -549,7 +550,7 @@ Extended error information value 'stacktrace' for the key parameter:: # echo 'hist:keys=stacktrace:values=bytes_req,bytes_alloc:sort=bytes_alloc' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger The above trigger will use the kernel stack trace in effect when an event is triggered as the key for the hash table. This allows the @@ -559,7 +560,7 @@ Extended error information every callpath in the system that led up to a kmalloc (in this case every callpath to a kmalloc for a kernel compile):: - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist + # cat /sys/kernel/tracing/events/kmem/kmalloc/hist # trigger info: hist:keys=stacktrace:vals=bytes_req,bytes_alloc:sort=bytes_alloc:size=2048 [active] { stacktrace: @@ -658,9 +659,9 @@ Extended error information keeps a per-process sum of total bytes read:: # echo 'hist:key=common_pid.execname:val=count:sort=count.descending' > \ - /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger + /sys/kernel/tracing/events/syscalls/sys_enter_read/trigger - # cat /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/hist + # cat /sys/kernel/tracing/events/syscalls/sys_enter_read/hist # trigger info: hist:keys=common_pid.execname:vals=count:sort=count.descending:size=2048 [active] { common_pid: gnome-terminal [ 3196] } hitcount: 280 count: 1093512 @@ -699,9 +700,9 @@ Extended error information counts for the system during the run:: # echo 'hist:key=id.syscall:val=hitcount' > \ - /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/trigger + /sys/kernel/tracing/events/raw_syscalls/sys_enter/trigger - # cat /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/hist + # cat /sys/kernel/tracing/events/raw_syscalls/sys_enter/hist # trigger info: hist:keys=id.syscall:vals=hitcount:sort=hitcount:size=2048 [active] { id: sys_fsync [ 74] } hitcount: 1 @@ -753,9 +754,9 @@ Extended error information hitcount sum as the secondary key:: # echo 'hist:key=id.syscall,common_pid.execname:val=hitcount:sort=id,hitcount' > \ - /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/trigger + /sys/kernel/tracing/events/raw_syscalls/sys_enter/trigger - # cat /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/hist + # cat /sys/kernel/tracing/events/raw_syscalls/sys_enter/hist # trigger info: hist:keys=id.syscall,common_pid.execname:vals=hitcount:sort=id.syscall,hitcount:size=2048 [active] { id: sys_read [ 0], common_pid: rtkit-daemon [ 1877] } hitcount: 1 @@ -803,9 +804,9 @@ Extended error information can use that to filter out all the other syscalls:: # echo 'hist:key=id.syscall,common_pid.execname:val=hitcount:sort=id,hitcount if id == 16' > \ - /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/trigger + /sys/kernel/tracing/events/raw_syscalls/sys_enter/trigger - # cat /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/hist + # cat /sys/kernel/tracing/events/raw_syscalls/sys_enter/hist # trigger info: hist:keys=id.syscall,common_pid.execname:vals=hitcount:sort=id.syscall,hitcount:size=2048 if id == 16 [active] { id: sys_ioctl [ 16], common_pid: gmain [ 2769] } hitcount: 1 @@ -846,9 +847,9 @@ Extended error information each process:: # echo 'hist:key=common_pid.execname,size:val=hitcount:sort=common_pid,size' > \ - /sys/kernel/debug/tracing/events/syscalls/sys_enter_recvfrom/trigger + /sys/kernel/tracing/events/syscalls/sys_enter_recvfrom/trigger - # cat /sys/kernel/debug/tracing/events/syscalls/sys_enter_recvfrom/hist + # cat /sys/kernel/tracing/events/syscalls/sys_enter_recvfrom/hist # trigger info: hist:keys=common_pid.execname,size:vals=hitcount:sort=common_pid.execname,size:size=2048 [active] { common_pid: smbd [ 784], size: 4 } hitcount: 1 @@ -899,9 +900,9 @@ Extended error information much smaller number, say 256:: # echo 'hist:key=child_comm:val=hitcount:size=256' > \ - /sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger + /sys/kernel/tracing/events/sched/sched_process_fork/trigger - # cat /sys/kernel/debug/tracing/events/sched/sched_process_fork/hist + # cat /sys/kernel/tracing/events/sched/sched_process_fork/hist # trigger info: hist:keys=child_comm:vals=hitcount:sort=hitcount:size=256 [active] { child_comm: dconf worker } hitcount: 1 @@ -935,9 +936,9 @@ Extended error information displays as [paused]:: # echo 'hist:key=child_comm:val=hitcount:size=256:pause' >> \ - /sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger + /sys/kernel/tracing/events/sched/sched_process_fork/trigger - # cat /sys/kernel/debug/tracing/events/sched/sched_process_fork/hist + # cat /sys/kernel/tracing/events/sched/sched_process_fork/hist # trigger info: hist:keys=child_comm:vals=hitcount:sort=hitcount:size=256 [paused] { child_comm: dconf worker } hitcount: 1 @@ -972,9 +973,9 @@ Extended error information again, and the data has changed:: # echo 'hist:key=child_comm:val=hitcount:size=256:cont' >> \ - /sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger + /sys/kernel/tracing/events/sched/sched_process_fork/trigger - # cat /sys/kernel/debug/tracing/events/sched/sched_process_fork/hist + # cat /sys/kernel/tracing/events/sched/sched_process_fork/hist # trigger info: hist:keys=child_comm:vals=hitcount:sort=hitcount:size=256 [active] { child_comm: dconf worker } hitcount: 1 @@ -1026,7 +1027,7 @@ Extended error information netif_receive_skb event:: # echo 'hist:key=stacktrace:vals=len:pause' > \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger Next, we set up an 'enable_hist' trigger on the sched_process_exec event, with an 'if filename==/usr/bin/wget' filter. The effect of @@ -1037,7 +1038,7 @@ Extended error information hash table keyed on stacktrace:: # echo 'enable_hist:net:netif_receive_skb if filename==/usr/bin/wget' > \ - /sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger + /sys/kernel/tracing/events/sched/sched_process_exec/trigger The aggregation continues until the netif_receive_skb is paused again, which is what the following disable_hist event does by @@ -1045,7 +1046,7 @@ Extended error information filter 'comm==wget':: # echo 'disable_hist:net:netif_receive_skb if comm==wget' > \ - /sys/kernel/debug/tracing/events/sched/sched_process_exit/trigger + /sys/kernel/tracing/events/sched/sched_process_exit/trigger Whenever a process exits and the comm field of the disable_hist trigger filter matches 'comm==wget', the netif_receive_skb hist @@ -1058,7 +1059,7 @@ Extended error information $ wget https://www.kernel.org/pub/linux/kernel/v3.x/patch-3.19.xz - # cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist + # cat /sys/kernel/tracing/events/net/netif_receive_skb/hist # trigger info: hist:keys=stacktrace:vals=len:sort=hitcount:size=2048 [paused] { stacktrace: @@ -1142,12 +1143,12 @@ Extended error information again, we can just clear the histogram first:: # echo 'hist:key=stacktrace:vals=len:clear' >> \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger Just to verify that it is in fact cleared, here's what we now see in the hist file:: - # cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist + # cat /sys/kernel/tracing/events/net/netif_receive_skb/hist # trigger info: hist:keys=stacktrace:vals=len:sort=hitcount:size=2048 [paused] Totals: @@ -1162,21 +1163,21 @@ Extended error information sched_process_exit events as such:: # echo 'enable_event:net:netif_receive_skb if filename==/usr/bin/wget' > \ - /sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger + /sys/kernel/tracing/events/sched/sched_process_exec/trigger # echo 'disable_event:net:netif_receive_skb if comm==wget' > \ - /sys/kernel/debug/tracing/events/sched/sched_process_exit/trigger + /sys/kernel/tracing/events/sched/sched_process_exit/trigger If you read the trigger files for the sched_process_exec and sched_process_exit triggers, you should see two triggers for each: one enabling/disabling the hist aggregation and the other enabling/disabling the logging of events:: - # cat /sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger + # cat /sys/kernel/tracing/events/sched/sched_process_exec/trigger enable_event:net:netif_receive_skb:unlimited if filename==/usr/bin/wget enable_hist:net:netif_receive_skb:unlimited if filename==/usr/bin/wget - # cat /sys/kernel/debug/tracing/events/sched/sched_process_exit/trigger + # cat /sys/kernel/tracing/events/sched/sched_process_exit/trigger enable_event:net:netif_receive_skb:unlimited if comm==wget disable_hist:net:netif_receive_skb:unlimited if comm==wget @@ -1192,7 +1193,7 @@ Extended error information saw in the last run, but this time you should also see the individual events in the trace file:: - # cat /sys/kernel/debug/tracing/trace + # cat /sys/kernel/tracing/trace # tracer: nop # @@ -1226,15 +1227,15 @@ Extended error information other things:: # echo 'hist:keys=skbaddr.hex:vals=len if len < 0' >> \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger # echo 'hist:keys=skbaddr.hex:vals=len if len > 4096' >> \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger # echo 'hist:keys=skbaddr.hex:vals=len if len == 256' >> \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger # echo 'hist:keys=skbaddr.hex:vals=len' >> \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger # echo 'hist:keys=len:vals=common_preempt_count' >> \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger The above set of commands create four triggers differing only in their filters, along with a completely different though fairly @@ -1246,7 +1247,7 @@ Extended error information Displaying the contents of the 'hist' file for the event shows the contents of all five histograms:: - # cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist + # cat /sys/kernel/tracing/events/net/netif_receive_skb/hist # event histogram # @@ -1367,15 +1368,15 @@ Extended error information field in the shared 'foo' histogram data:: # echo 'hist:name=foo:keys=skbaddr.hex:vals=len' > \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger # echo 'hist:name=foo:keys=skbaddr.hex:vals=len' > \ - /sys/kernel/debug/tracing/events/net/netif_rx/trigger + /sys/kernel/tracing/events/net/netif_rx/trigger You can see that they're updating common histogram data by reading each event's hist files at the same time:: - # cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist; - cat /sys/kernel/debug/tracing/events/net/netif_rx/hist + # cat /sys/kernel/tracing/events/net/netif_receive_skb/hist; + cat /sys/kernel/tracing/events/net/netif_rx/hist # event histogram # @@ -1488,15 +1489,15 @@ Extended error information couple of triggers named 'bar' using those fields:: # echo 'hist:name=bar:key=stacktrace:val=hitcount' > \ - /sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger + /sys/kernel/tracing/events/sched/sched_process_fork/trigger # echo 'hist:name=bar:key=stacktrace:val=hitcount' > \ - /sys/kernel/debug/tracing/events/net/netif_rx/trigger + /sys/kernel/tracing/events/net/netif_rx/trigger And displaying the output of either shows some interesting if somewhat confusing output:: - # cat /sys/kernel/debug/tracing/events/sched/sched_process_fork/hist - # cat /sys/kernel/debug/tracing/events/net/netif_rx/hist + # cat /sys/kernel/tracing/events/sched/sched_process_fork/hist + # cat /sys/kernel/tracing/events/net/netif_rx/hist # event histogram # @@ -1786,6 +1787,8 @@ or assigned to a variable and referenced in a subsequent expression:: # echo 'hist:keys=next_pid:us_per_sec=1000000 ...' >> event/trigger # echo 'hist:keys=next_pid:timestamp_secs=common_timestamp/$us_per_sec ...' >> event/trigger +Variables can even hold stacktraces, which are useful with synthetic events. + 2.2.2 Synthetic Events ---------------------- @@ -1826,19 +1829,19 @@ variable reference to a variable on another event:: u64 lat; \ pid_t pid; \ int prio' >> \ - /sys/kernel/debug/tracing/synthetic_events + /sys/kernel/tracing/synthetic_events Reading the tracing/synthetic_events file lists all the currently defined synthetic events, in this case the event defined above:: - # cat /sys/kernel/debug/tracing/synthetic_events + # cat /sys/kernel/tracing/synthetic_events wakeup_latency u64 lat; pid_t pid; int prio An existing synthetic event definition can be removed by prepending the command that defined it with a '!':: # echo '!wakeup_latency u64 lat pid_t pid int prio' >> \ - /sys/kernel/debug/tracing/synthetic_events + /sys/kernel/tracing/synthetic_events At this point, there isn't yet an actual 'wakeup_latency' event instantiated in the event subsystem - for this to happen, a 'hist @@ -1850,20 +1853,20 @@ done, the 'wakeup_latency' synthetic event instance is created. The new event is created under the tracing/events/synthetic/ directory and looks and behaves just like any other event:: - # ls /sys/kernel/debug/tracing/events/synthetic/wakeup_latency + # ls /sys/kernel/tracing/events/synthetic/wakeup_latency enable filter format hist id trigger A histogram can now be defined for the new synthetic event:: # echo 'hist:keys=pid,prio,lat.log2:sort=lat' >> \ - /sys/kernel/debug/tracing/events/synthetic/wakeup_latency/trigger + /sys/kernel/tracing/events/synthetic/wakeup_latency/trigger The above shows the latency "lat" in a power of 2 grouping. Like any other event, once a histogram is enabled for the event, the -output can be displayed by reading the event's 'hist' file. +output can be displayed by reading the event's 'hist' file:: - # cat /sys/kernel/debug/tracing/events/synthetic/wakeup_latency/hist + # cat /sys/kernel/tracing/events/synthetic/wakeup_latency/hist # event histogram # @@ -1908,10 +1911,10 @@ output can be displayed by reading the event's 'hist' file. The latency values can also be grouped linearly by a given size with -the ".buckets" modifier and specify a size (in this case groups of 10). +the ".buckets" modifier and specify a size (in this case groups of 10):: # echo 'hist:keys=pid,prio,lat.buckets=10:sort=lat' >> \ - /sys/kernel/debug/tracing/events/synthetic/wakeup_latency/trigger + /sys/kernel/tracing/events/synthetic/wakeup_latency/trigger # event histogram # @@ -1940,6 +1943,157 @@ the ".buckets" modifier and specify a size (in this case groups of 10). Entries: 16 Dropped: 0 +To save stacktraces, create a synthetic event with a field of type "unsigned long[]" +or even just "long[]". For example, to see how long a task is blocked in an +uninterruptible state:: + + # cd /sys/kernel/tracing + # echo 's:block_lat pid_t pid; u64 delta; unsigned long[] stack;' > dynamic_events + # echo 'hist:keys=next_pid:ts=common_timestamp.usecs,st=stacktrace if prev_state == 2' >> events/sched/sched_switch/trigger + # echo 'hist:keys=prev_pid:delta=common_timestamp.usecs-$ts,s=$st:onmax($delta).trace(block_lat,prev_pid,$delta,$s)' >> events/sched/sched_switch/trigger + # echo 1 > events/synthetic/block_lat/enable + # cat trace + + # tracer: nop + # + # entries-in-buffer/entries-written: 2/2 #P:8 + # + # _-----=> irqs-off/BH-disabled + # / _----=> need-resched + # | / _---=> hardirq/softirq + # || / _--=> preempt-depth + # ||| / _-=> migrate-disable + # |||| / delay + # TASK-PID CPU# ||||| TIMESTAMP FUNCTION + # | | | ||||| | | + <idle>-0 [005] d..4. 521.164922: block_lat: pid=0 delta=8322 stack=STACK: + => __schedule+0x448/0x7b0 + => schedule+0x5a/0xb0 + => io_schedule+0x42/0x70 + => bit_wait_io+0xd/0x60 + => __wait_on_bit+0x4b/0x140 + => out_of_line_wait_on_bit+0x91/0xb0 + => jbd2_journal_commit_transaction+0x1679/0x1a70 + => kjournald2+0xa9/0x280 + => kthread+0xe9/0x110 + => ret_from_fork+0x2c/0x50 + + <...>-2 [004] d..4. 525.184257: block_lat: pid=2 delta=76 stack=STACK: + => __schedule+0x448/0x7b0 + => schedule+0x5a/0xb0 + => schedule_timeout+0x11a/0x150 + => wait_for_completion_killable+0x144/0x1f0 + => __kthread_create_on_node+0xe7/0x1e0 + => kthread_create_on_node+0x51/0x70 + => create_worker+0xcc/0x1a0 + => worker_thread+0x2ad/0x380 + => kthread+0xe9/0x110 + => ret_from_fork+0x2c/0x50 + +A synthetic event that has a stacktrace field may use it as a key in +histogram:: + + # echo 'hist:keys=delta.buckets=100,stack.stacktrace:sort=delta' > events/synthetic/block_lat/trigger + # cat events/synthetic/block_lat/hist + + # event histogram + # + # trigger info: hist:keys=delta.buckets=100,stack.stacktrace:vals=hitcount:sort=delta.buckets=100:size=2048 [active] + # + { delta: ~ 0-99, stack.stacktrace __schedule+0xa19/0x1520 + schedule+0x6b/0x110 + io_schedule+0x46/0x80 + bit_wait_io+0x11/0x80 + __wait_on_bit+0x4e/0x120 + out_of_line_wait_on_bit+0x8d/0xb0 + __wait_on_buffer+0x33/0x40 + jbd2_journal_commit_transaction+0x155a/0x19b0 + kjournald2+0xab/0x270 + kthread+0xfa/0x130 + ret_from_fork+0x29/0x50 + } hitcount: 1 + { delta: ~ 0-99, stack.stacktrace __schedule+0xa19/0x1520 + schedule+0x6b/0x110 + io_schedule+0x46/0x80 + rq_qos_wait+0xd0/0x170 + wbt_wait+0x9e/0xf0 + __rq_qos_throttle+0x25/0x40 + blk_mq_submit_bio+0x2c3/0x5b0 + __submit_bio+0xff/0x190 + submit_bio_noacct_nocheck+0x25b/0x2b0 + submit_bio_noacct+0x20b/0x600 + submit_bio+0x28/0x90 + ext4_bio_write_page+0x1e0/0x8c0 + mpage_submit_page+0x60/0x80 + mpage_process_page_bufs+0x16c/0x180 + mpage_prepare_extent_to_map+0x23f/0x530 + } hitcount: 1 + { delta: ~ 0-99, stack.stacktrace __schedule+0xa19/0x1520 + schedule+0x6b/0x110 + schedule_hrtimeout_range_clock+0x97/0x110 + schedule_hrtimeout_range+0x13/0x20 + usleep_range_state+0x65/0x90 + __intel_wait_for_register+0x1c1/0x230 [i915] + intel_psr_wait_for_idle_locked+0x171/0x2a0 [i915] + intel_pipe_update_start+0x169/0x360 [i915] + intel_update_crtc+0x112/0x490 [i915] + skl_commit_modeset_enables+0x199/0x600 [i915] + intel_atomic_commit_tail+0x7c4/0x1080 [i915] + intel_atomic_commit_work+0x12/0x20 [i915] + process_one_work+0x21c/0x3f0 + worker_thread+0x50/0x3e0 + kthread+0xfa/0x130 + } hitcount: 3 + { delta: ~ 0-99, stack.stacktrace __schedule+0xa19/0x1520 + schedule+0x6b/0x110 + schedule_timeout+0x11e/0x160 + __wait_for_common+0x8f/0x190 + wait_for_completion+0x24/0x30 + __flush_work.isra.0+0x1cc/0x360 + flush_work+0xe/0x20 + drm_mode_rmfb+0x18b/0x1d0 [drm] + drm_mode_rmfb_ioctl+0x10/0x20 [drm] + drm_ioctl_kernel+0xb8/0x150 [drm] + drm_ioctl+0x243/0x560 [drm] + __x64_sys_ioctl+0x92/0xd0 + do_syscall_64+0x59/0x90 + entry_SYSCALL_64_after_hwframe+0x72/0xdc + } hitcount: 1 + { delta: ~ 0-99, stack.stacktrace __schedule+0xa19/0x1520 + schedule+0x6b/0x110 + schedule_timeout+0x87/0x160 + __wait_for_common+0x8f/0x190 + wait_for_completion_timeout+0x1d/0x30 + drm_atomic_helper_wait_for_flip_done+0x57/0x90 [drm_kms_helper] + intel_atomic_commit_tail+0x8ce/0x1080 [i915] + intel_atomic_commit_work+0x12/0x20 [i915] + process_one_work+0x21c/0x3f0 + worker_thread+0x50/0x3e0 + kthread+0xfa/0x130 + ret_from_fork+0x29/0x50 + } hitcount: 1 + { delta: ~ 100-199, stack.stacktrace __schedule+0xa19/0x1520 + schedule+0x6b/0x110 + schedule_hrtimeout_range_clock+0x97/0x110 + schedule_hrtimeout_range+0x13/0x20 + usleep_range_state+0x65/0x90 + pci_set_low_power_state+0x17f/0x1f0 + pci_set_power_state+0x49/0x250 + pci_finish_runtime_suspend+0x4a/0x90 + pci_pm_runtime_suspend+0xcb/0x1b0 + __rpm_callback+0x48/0x120 + rpm_callback+0x67/0x70 + rpm_suspend+0x167/0x780 + rpm_idle+0x25a/0x380 + pm_runtime_work+0x93/0xc0 + process_one_work+0x21c/0x3f0 + } hitcount: 1 + + Totals: + Hits: 10 + Entries: 7 + Dropped: 0 + 2.2.3 Hist trigger 'handlers' and 'actions' ------------------------------------------- @@ -2039,9 +2193,9 @@ The following commonly-used handler.action pairs are available: event:: # echo 'wakeup_new_test pid_t pid' >> \ - /sys/kernel/debug/tracing/synthetic_events + /sys/kernel/tracing/synthetic_events - # cat /sys/kernel/debug/tracing/synthetic_events + # cat /sys/kernel/tracing/synthetic_events wakeup_new_test pid_t pid The following hist trigger both defines the missing testpid @@ -2052,26 +2206,26 @@ The following commonly-used handler.action pairs are available: # echo 'hist:keys=$testpid:testpid=pid:onmatch(sched.sched_wakeup_new).\ wakeup_new_test($testpid) if comm=="cyclictest"' >> \ - /sys/kernel/debug/tracing/events/sched/sched_wakeup_new/trigger + /sys/kernel/tracing/events/sched/sched_wakeup_new/trigger - Or, equivalently, using the 'trace' keyword syntax: + Or, equivalently, using the 'trace' keyword syntax:: - # echo 'hist:keys=$testpid:testpid=pid:onmatch(sched.sched_wakeup_new).\ - trace(wakeup_new_test,$testpid) if comm=="cyclictest"' >> \ - /sys/kernel/debug/tracing/events/sched/sched_wakeup_new/trigger + # echo 'hist:keys=$testpid:testpid=pid:onmatch(sched.sched_wakeup_new).\ + trace(wakeup_new_test,$testpid) if comm=="cyclictest"' >> \ + /sys/kernel/tracing/events/sched/sched_wakeup_new/trigger Creating and displaying a histogram based on those events is now just a matter of using the fields and new synthetic event in the tracing/events/synthetic directory, as usual:: # echo 'hist:keys=pid:sort=pid' >> \ - /sys/kernel/debug/tracing/events/synthetic/wakeup_new_test/trigger + /sys/kernel/tracing/events/synthetic/wakeup_new_test/trigger Running 'cyclictest' should cause wakeup_new events to generate wakeup_new_test synthetic events which should result in histogram output in the wakeup_new_test event's hist file:: - # cat /sys/kernel/debug/tracing/events/synthetic/wakeup_new_test/hist + # cat /sys/kernel/tracing/events/synthetic/wakeup_new_test/hist A more typical usage would be to use two events to calculate a latency. The following example uses a set of hist triggers to @@ -2080,14 +2234,14 @@ The following commonly-used handler.action pairs are available: First, we define a 'wakeup_latency' synthetic event:: # echo 'wakeup_latency u64 lat; pid_t pid; int prio' >> \ - /sys/kernel/debug/tracing/synthetic_events + /sys/kernel/tracing/synthetic_events Next, we specify that whenever we see a sched_waking event for a cyclictest thread, save the timestamp in a 'ts0' variable:: # echo 'hist:keys=$saved_pid:saved_pid=pid:ts0=common_timestamp.usecs \ if comm=="cyclictest"' >> \ - /sys/kernel/debug/tracing/events/sched/sched_waking/trigger + /sys/kernel/tracing/events/sched/sched_waking/trigger Then, when the corresponding thread is actually scheduled onto the CPU by a sched_switch event (saved_pid matches next_pid), calculate @@ -2097,19 +2251,19 @@ The following commonly-used handler.action pairs are available: # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:\ onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,\ $saved_pid,next_prio) if next_comm=="cyclictest"' >> \ - /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + /sys/kernel/tracing/events/sched/sched_switch/trigger We also need to create a histogram on the wakeup_latency synthetic event in order to aggregate the generated synthetic event data:: # echo 'hist:keys=pid,prio,lat:sort=pid,lat' >> \ - /sys/kernel/debug/tracing/events/synthetic/wakeup_latency/trigger + /sys/kernel/tracing/events/synthetic/wakeup_latency/trigger Finally, once we've run cyclictest to actually generate some events, we can see the output by looking at the wakeup_latency synthetic event's hist file:: - # cat /sys/kernel/debug/tracing/events/synthetic/wakeup_latency/hist + # cat /sys/kernel/tracing/events/synthetic/wakeup_latency/hist - onmax(var).save(field,.. .) @@ -2135,19 +2289,19 @@ The following commonly-used handler.action pairs are available: # echo 'hist:keys=pid:ts0=common_timestamp.usecs \ if comm=="cyclictest"' >> \ - /sys/kernel/debug/tracing/events/sched/sched_waking/trigger + /sys/kernel/tracing/events/sched/sched_waking/trigger # echo 'hist:keys=next_pid:\ wakeup_lat=common_timestamp.usecs-$ts0:\ onmax($wakeup_lat).save(next_comm,prev_pid,prev_prio,prev_comm) \ if next_comm=="cyclictest"' >> \ - /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + /sys/kernel/tracing/events/sched/sched_switch/trigger When the histogram is displayed, the max value and the saved values corresponding to the max are displayed following the rest of the fields:: - # cat /sys/kernel/debug/tracing/events/sched/sched_switch/hist + # cat /sys/kernel/tracing/events/sched/sched_switch/hist { next_pid: 2255 } hitcount: 239 common_timestamp-ts0: 0 max: 27 @@ -2191,48 +2345,48 @@ The following commonly-used handler.action pairs are available: resulting latency, stored in wakeup_lat, exceeds the current maximum latency, a snapshot is taken. As part of the setup, all the scheduler events are also enabled, which are the events that - will show up in the snapshot when it is taken at some point: + will show up in the snapshot when it is taken at some point:: - # echo 1 > /sys/kernel/debug/tracing/events/sched/enable + # echo 1 > /sys/kernel/tracing/events/sched/enable - # echo 'hist:keys=pid:ts0=common_timestamp.usecs \ - if comm=="cyclictest"' >> \ - /sys/kernel/debug/tracing/events/sched/sched_waking/trigger + # echo 'hist:keys=pid:ts0=common_timestamp.usecs \ + if comm=="cyclictest"' >> \ + /sys/kernel/tracing/events/sched/sched_waking/trigger - # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0: \ - onmax($wakeup_lat).save(next_prio,next_comm,prev_pid,prev_prio, \ - prev_comm):onmax($wakeup_lat).snapshot() \ - if next_comm=="cyclictest"' >> \ - /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0: \ + onmax($wakeup_lat).save(next_prio,next_comm,prev_pid,prev_prio, \ + prev_comm):onmax($wakeup_lat).snapshot() \ + if next_comm=="cyclictest"' >> \ + /sys/kernel/tracing/events/sched/sched_switch/trigger When the histogram is displayed, for each bucket the max value and the saved values corresponding to the max are displayed following the rest of the fields. If a snapshot was taken, there is also a message indicating that, - along with the value and event that triggered the global maximum: + along with the value and event that triggered the global maximum:: - # cat /sys/kernel/debug/tracing/events/sched/sched_switch/hist - { next_pid: 2101 } hitcount: 200 - max: 52 next_prio: 120 next_comm: cyclictest \ - prev_pid: 0 prev_prio: 120 prev_comm: swapper/6 + # cat /sys/kernel/tracing/events/sched/sched_switch/hist + { next_pid: 2101 } hitcount: 200 + max: 52 next_prio: 120 next_comm: cyclictest \ + prev_pid: 0 prev_prio: 120 prev_comm: swapper/6 - { next_pid: 2103 } hitcount: 1326 - max: 572 next_prio: 19 next_comm: cyclictest \ - prev_pid: 0 prev_prio: 120 prev_comm: swapper/1 + { next_pid: 2103 } hitcount: 1326 + max: 572 next_prio: 19 next_comm: cyclictest \ + prev_pid: 0 prev_prio: 120 prev_comm: swapper/1 - { next_pid: 2102 } hitcount: 1982 \ - max: 74 next_prio: 19 next_comm: cyclictest \ - prev_pid: 0 prev_prio: 120 prev_comm: swapper/5 + { next_pid: 2102 } hitcount: 1982 \ + max: 74 next_prio: 19 next_comm: cyclictest \ + prev_pid: 0 prev_prio: 120 prev_comm: swapper/5 - Snapshot taken (see tracing/snapshot). Details: - triggering value { onmax($wakeup_lat) }: 572 \ - triggered by event with key: { next_pid: 2103 } + Snapshot taken (see tracing/snapshot). Details: + triggering value { onmax($wakeup_lat) }: 572 \ + triggered by event with key: { next_pid: 2103 } - Totals: - Hits: 3508 - Entries: 3 - Dropped: 0 + Totals: + Hits: 3508 + Entries: 3 + Dropped: 0 In the above case, the event that triggered the global maximum has the key with next_pid == 2103. If you look at the bucket that has @@ -2247,7 +2401,7 @@ The following commonly-used handler.action pairs are available: sched_switch events, which should match the time displayed in the global maximum):: - # cat /sys/kernel/debug/tracing/snapshot + # cat /sys/kernel/tracing/snapshot <...>-2103 [005] d..3 309.873125: sched_switch: prev_comm=cyclictest prev_pid=2103 prev_prio=19 prev_state=D ==> next_comm=swapper/5 next_pid=0 next_prio=120 <idle>-0 [005] d.h3 309.873611: sched_waking: comm=cyclictest pid=2102 prio=19 target_cpu=005 @@ -2310,15 +2464,15 @@ The following commonly-used handler.action pairs are available: $cwnd variable. If the value has changed, a snapshot is taken. As part of the setup, all the scheduler and tcp events are also enabled, which are the events that will show up in the snapshot - when it is taken at some point: + when it is taken at some point:: - # echo 1 > /sys/kernel/debug/tracing/events/sched/enable - # echo 1 > /sys/kernel/debug/tracing/events/tcp/enable + # echo 1 > /sys/kernel/tracing/events/sched/enable + # echo 1 > /sys/kernel/tracing/events/tcp/enable - # echo 'hist:keys=dport:cwnd=snd_cwnd: \ - onchange($cwnd).save(snd_wnd,srtt,rcv_wnd): \ - onchange($cwnd).snapshot()' >> \ - /sys/kernel/debug/tracing/events/tcp/tcp_probe/trigger + # echo 'hist:keys=dport:cwnd=snd_cwnd: \ + onchange($cwnd).save(snd_wnd,srtt,rcv_wnd): \ + onchange($cwnd).snapshot()' >> \ + /sys/kernel/tracing/events/tcp/tcp_probe/trigger When the histogram is displayed, for each bucket the tracked value and the saved values corresponding to that value are displayed @@ -2327,7 +2481,7 @@ The following commonly-used handler.action pairs are available: If a snapshot was taken, there is also a message indicating that, along with the value and event that triggered the snapshot:: - # cat /sys/kernel/debug/tracing/events/tcp/tcp_probe/hist + # cat /sys/kernel/tracing/events/tcp/tcp_probe/hist { dport: 1521 } hitcount: 8 changed: 10 snd_wnd: 35456 srtt: 154262 rcv_wnd: 42112 @@ -2341,10 +2495,10 @@ The following commonly-used handler.action pairs are available: { dport: 443 } hitcount: 211 changed: 10 snd_wnd: 26960 srtt: 17379 rcv_wnd: 28800 - Snapshot taken (see tracing/snapshot). Details:: + Snapshot taken (see tracing/snapshot). Details: - triggering value { onchange($cwnd) }: 10 - triggered by event with key: { dport: 80 } + triggering value { onchange($cwnd) }: 10 + triggered by event with key: { dport: 80 } Totals: Hits: 414 @@ -2361,7 +2515,7 @@ The following commonly-used handler.action pairs are available: And finally, looking at the snapshot data should show at or near the end the event that triggered the snapshot:: - # cat /sys/kernel/debug/tracing/snapshot + # cat /sys/kernel/tracing/snapshot gnome-shell-1261 [006] dN.3 49.823113: sched_stat_runtime: comm=gnome-shell pid=1261 runtime=49347 [ns] vruntime=1835730389 [ns] kworker/u16:4-773 [003] d..3 49.823114: sched_switch: prev_comm=kworker/u16:4 prev_pid=773 prev_prio=120 prev_state=R+ ==> next_comm=kworker/3:2 next_pid=135 next_prio=120 diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst index 08a2a6a3782f..651f9ab53f3e 100644 --- a/Documentation/trace/kprobetrace.rst +++ b/Documentation/trace/kprobetrace.rst @@ -6,21 +6,21 @@ Kprobe-based Event Tracing Overview -------- -These events are similar to tracepoint based events. Instead of Tracepoint, +These events are similar to tracepoint-based events. Instead of tracepoints, this is based on kprobes (kprobe and kretprobe). So it can probe wherever kprobes can probe (this means, all functions except those with __kprobes/nokprobe_inline annotation and those marked NOKPROBE_SYMBOL). -Unlike the Tracepoint based event, this can be added and removed +Unlike the tracepoint-based event, this can be added and removed dynamically, on the fly. To enable this feature, build your kernel with CONFIG_KPROBE_EVENTS=y. -Similar to the events tracer, this doesn't need to be activated via +Similar to the event tracer, this doesn't need to be activated via current_tracer. Instead of that, add probe points via -/sys/kernel/debug/tracing/kprobe_events, and enable it via -/sys/kernel/debug/tracing/events/kprobes/<EVENT>/enable. +/sys/kernel/tracing/kprobe_events, and enable it via +/sys/kernel/tracing/events/kprobes/<EVENT>/enable. -You can also use /sys/kernel/debug/tracing/dynamic_events instead of +You can also use /sys/kernel/tracing/dynamic_events instead of kprobe_events. That interface will provide unified access to other dynamic events too. @@ -58,7 +58,7 @@ Synopsis of kprobe_events NAME=FETCHARG : Set NAME as the argument name of FETCHARG. FETCHARG:TYPE : Set TYPE as the type of FETCHARG. Currently, basic types (u8/u16/u32/u64/s8/s16/s32/s64), hexadecimal types - (x8/x16/x32/x64), "string", "ustring", "symbol", "symstr" + (x8/x16/x32/x64), "char", "string", "ustring", "symbol", "symstr" and bitfield are supported. (\*1) only for the probe on function entry (offs == 0). @@ -68,22 +68,27 @@ Synopsis of kprobe_events Types ----- -Several types are supported for fetch-args. Kprobe tracer will access memory +Several types are supported for fetchargs. Kprobe tracer will access memory by given type. Prefix 's' and 'u' means those types are signed and unsigned respectively. 'x' prefix implies it is unsigned. Traced arguments are shown in decimal ('s' and 'u') or hexadecimal ('x'). Without type casting, 'x32' or 'x64' is used depends on the architecture (e.g. x86-32 uses x32, and x86-64 uses x64). + These value types can be an array. To record array data, you can add '[N]' (where N is a fixed number, less than 64) to the base type. -E.g. 'x16[4]' means an array of x16 (2bytes hex) with 4 elements. +E.g. 'x16[4]' means an array of x16 (2-byte hex) with 4 elements. Note that the array can be applied to memory type fetchargs, you can not apply it to registers/stack-entries etc. (for example, '$stack1:x8[8]' is wrong, but '+8($stack):x8[8]' is OK.) + +Char type can be used to show the character value of traced arguments. + String type is a special type, which fetches a "null-terminated" string from kernel space. This means it will fail and store NULL if the string container has been paged out. "ustring" type is an alternative of string for user-space. -See :ref:`user_mem_access` for more info.. +See :ref:`user_mem_access` for more info. + The string array type is a bit different from other types. For other base types, <base-type>[1] is equal to <base-type> (e.g. +0(%di):x32[1] is same as +0(%di):x32.) But string[1] is not equal to string. The string type itself @@ -120,8 +125,8 @@ space. 'ustring' is a shortcut way of performing the same task. That is, Note that kprobe-event provides the user-memory access syntax but it doesn't use it transparently. This means if you use normal dereference or string type -for user memory, it might fail, and may always fail on some archs. The user -has to carefully check if the target data is in kernel or user space. +for user memory, it might fail, and may always fail on some architectures. The +user has to carefully check if the target data is in kernel or user space. Per-Probe Event Filtering ------------------------- @@ -150,7 +155,7 @@ trigger: Event Profiling --------------- You can check the total number of probe hits and probe miss-hits via -/sys/kernel/debug/tracing/kprobe_profile. +/sys/kernel/tracing/kprobe_profile. The first column is event name, the second is the number of probe hits, the third is the number of probe miss-hits. @@ -160,11 +165,11 @@ You can add and enable new kprobe events when booting up the kernel by "kprobe_event=" parameter. The parameter accepts a semicolon-delimited kprobe events, which format is similar to the kprobe_events. The difference is that the probe definition parameters are comma-delimited -instead of space. For example, adding myprobe event on do_sys_open like below +instead of space. For example, adding myprobe event on do_sys_open like below:: p:myprobe do_sys_open dfd=%ax filename=%dx flags=%cx mode=+4($stack) -should be below for kernel boot parameter (just replace spaces with comma) +should be below for kernel boot parameter (just replace spaces with comma):: p:myprobe,do_sys_open,dfd=%ax,filename=%dx,flags=%cx,mode=+4($stack) @@ -174,7 +179,7 @@ Usage examples To add a probe as a new event, write a new definition to kprobe_events as below:: - echo 'p:myprobe do_sys_open dfd=%ax filename=%dx flags=%cx mode=+4($stack)' > /sys/kernel/debug/tracing/kprobe_events + echo 'p:myprobe do_sys_open dfd=%ax filename=%dx flags=%cx mode=+4($stack)' > /sys/kernel/tracing/kprobe_events This sets a kprobe on the top of do_sys_open() function with recording 1st to 4th arguments as "myprobe" event. Note, which register/stack entry is @@ -184,15 +189,15 @@ under tools/perf/). As this example shows, users can choose more familiar names for each arguments. :: - echo 'r:myretprobe do_sys_open $retval' >> /sys/kernel/debug/tracing/kprobe_events + echo 'r:myretprobe do_sys_open $retval' >> /sys/kernel/tracing/kprobe_events This sets a kretprobe on the return point of do_sys_open() function with recording return value as "myretprobe" event. You can see the format of these events via -/sys/kernel/debug/tracing/events/kprobes/<EVENT>/format. +/sys/kernel/tracing/events/kprobes/<EVENT>/format. :: - cat /sys/kernel/debug/tracing/events/kprobes/myprobe/format + cat /sys/kernel/tracing/events/kprobes/myprobe/format name: myprobe ID: 780 format: @@ -215,7 +220,7 @@ You can see the format of these events via You can see that the event has 4 arguments as in the expressions you specified. :: - echo > /sys/kernel/debug/tracing/kprobe_events + echo > /sys/kernel/tracing/kprobe_events This clears all probe points. @@ -230,8 +235,8 @@ Right after definition, each event is disabled by default. For tracing these events, you need to enable it. :: - echo 1 > /sys/kernel/debug/tracing/events/kprobes/myprobe/enable - echo 1 > /sys/kernel/debug/tracing/events/kprobes/myretprobe/enable + echo 1 > /sys/kernel/tracing/events/kprobes/myprobe/enable + echo 1 > /sys/kernel/tracing/events/kprobes/myretprobe/enable Use the following command to start tracing in an interval. :: @@ -240,10 +245,10 @@ Use the following command to start tracing in an interval. Open something... # echo 0 > tracing_on -And you can see the traced information via /sys/kernel/debug/tracing/trace. +And you can see the traced information via /sys/kernel/tracing/trace. :: - cat /sys/kernel/debug/tracing/trace + cat /sys/kernel/tracing/trace # tracer: nop # # TASK-PID CPU# TIMESTAMP FUNCTION diff --git a/Documentation/trace/mmiotrace.rst b/Documentation/trace/mmiotrace.rst index fed13eaead89..95b750722a13 100644 --- a/Documentation/trace/mmiotrace.rst +++ b/Documentation/trace/mmiotrace.rst @@ -36,11 +36,11 @@ Usage Quick Reference :: $ mount -t debugfs debugfs /sys/kernel/debug - $ echo mmiotrace > /sys/kernel/debug/tracing/current_tracer - $ cat /sys/kernel/debug/tracing/trace_pipe > mydump.txt & + $ echo mmiotrace > /sys/kernel/tracing/current_tracer + $ cat /sys/kernel/tracing/trace_pipe > mydump.txt & Start X or whatever. - $ echo "X is up" > /sys/kernel/debug/tracing/trace_marker - $ echo nop > /sys/kernel/debug/tracing/current_tracer + $ echo "X is up" > /sys/kernel/tracing/trace_marker + $ echo nop > /sys/kernel/tracing/current_tracer Check for lost events. @@ -56,11 +56,11 @@ Check that the driver you are about to trace is not loaded. Activate mmiotrace (requires root privileges):: - $ echo mmiotrace > /sys/kernel/debug/tracing/current_tracer + $ echo mmiotrace > /sys/kernel/tracing/current_tracer Start storing the trace:: - $ cat /sys/kernel/debug/tracing/trace_pipe > mydump.txt & + $ cat /sys/kernel/tracing/trace_pipe > mydump.txt & The 'cat' process should stay running (sleeping) in the background. @@ -68,14 +68,14 @@ Load the driver you want to trace and use it. Mmiotrace will only catch MMIO accesses to areas that are ioremapped while mmiotrace is active. During tracing you can place comments (markers) into the trace by -$ echo "X is up" > /sys/kernel/debug/tracing/trace_marker +$ echo "X is up" > /sys/kernel/tracing/trace_marker This makes it easier to see which part of the (huge) trace corresponds to which action. It is recommended to place descriptive markers about what you do. Shut down mmiotrace (requires root privileges):: - $ echo nop > /sys/kernel/debug/tracing/current_tracer + $ echo nop > /sys/kernel/tracing/current_tracer The 'cat' process exits. If it does not, kill it by issuing 'fg' command and pressing ctrl+c. @@ -93,12 +93,12 @@ events were lost, the trace is incomplete. You should enlarge the buffers and try again. Buffers are enlarged by first seeing how large the current buffers are:: - $ cat /sys/kernel/debug/tracing/buffer_size_kb + $ cat /sys/kernel/tracing/buffer_size_kb gives you a number. Approximately double this number and write it back, for instance:: - $ echo 128000 > /sys/kernel/debug/tracing/buffer_size_kb + $ echo 128000 > /sys/kernel/tracing/buffer_size_kb Then start again from the top. diff --git a/Documentation/trace/postprocess/trace-pagealloc-postprocess.pl b/Documentation/trace/postprocess/trace-pagealloc-postprocess.pl index b9b7d80c2f9d..d16494c5e200 100644 --- a/Documentation/trace/postprocess/trace-pagealloc-postprocess.pl +++ b/Documentation/trace/postprocess/trace-pagealloc-postprocess.pl @@ -4,7 +4,7 @@ # to extract some high-level information on what is going on. The accuracy of the parser # may vary considerably # -# Example usage: trace-pagealloc-postprocess.pl < /sys/kernel/debug/tracing/trace_pipe +# Example usage: trace-pagealloc-postprocess.pl < /sys/kernel/tracing/trace_pipe # other options # --prepend-parent Report on the parent proc and PID # --read-procstat If the trace lacks process info, get it from /proc @@ -94,7 +94,7 @@ sub generate_traceevent_regex { my $regex; # Read the event format or use the default - if (!open (FORMAT, "/sys/kernel/debug/tracing/events/$event/format")) { + if (!open (FORMAT, "/sys/kernel/tracing/events/$event/format")) { $regex = $default; } else { my $line; diff --git a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl index 2f4e39875fb3..e24c009789a0 100644 --- a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl +++ b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl @@ -3,7 +3,7 @@ # page reclaim. It makes an attempt to extract some high-level information on # what is going on. The accuracy of the parser may vary # -# Example usage: trace-vmscan-postprocess.pl < /sys/kernel/debug/tracing/trace_pipe +# Example usage: trace-vmscan-postprocess.pl < /sys/kernel/tracing/trace_pipe # other options # --read-procstat If the trace lacks process info, get it from /proc # --ignore-pid Aggregate processes of the same name together @@ -140,7 +140,7 @@ sub generate_traceevent_regex { my $regex; # Read the event format or use the default - if (!open (FORMAT, "/sys/kernel/debug/tracing/events/$event/format")) { + if (!open (FORMAT, "/sys/kernel/tracing/events/$event/format")) { print("WARNING: Event $event format string not found\n"); return $default; } else { diff --git a/Documentation/trace/tracepoint-analysis.rst b/Documentation/trace/tracepoint-analysis.rst index 716326b9f152..be01bf7b47e5 100644 --- a/Documentation/trace/tracepoint-analysis.rst +++ b/Documentation/trace/tracepoint-analysis.rst @@ -26,10 +26,10 @@ assumed that the PCL tool tools/perf has been installed and is in your path. 2.1 Standard Utilities ---------------------- -All possible events are visible from /sys/kernel/debug/tracing/events. Simply +All possible events are visible from /sys/kernel/tracing/events. Simply calling:: - $ find /sys/kernel/debug/tracing/events -type d + $ find /sys/kernel/tracing/events -type d will give a fair indication of the number of events available. @@ -59,7 +59,7 @@ See Documentation/trace/events.rst for a proper description on how events can be enabled system-wide. A short example of enabling all events related to page allocation would look something like:: - $ for i in `find /sys/kernel/debug/tracing/events -name "enable" | grep mm_`; do echo 1 > $i; done + $ for i in `find /sys/kernel/tracing/events -name "enable" | grep mm_`; do echo 1 > $i; done 3.2 System-Wide Event Enabling with SystemTap --------------------------------------------- @@ -189,7 +189,7 @@ time on a system-wide basis using -a and sleep. ============================================ When events are enabled the events that are triggering can be read from -/sys/kernel/debug/tracing/trace_pipe in human-readable format although binary +/sys/kernel/tracing/trace_pipe in human-readable format although binary options exist as well. By post-processing the output, further information can be gathered on-line as appropriate. Examples of post-processing might include diff --git a/Documentation/trace/uprobetracer.rst b/Documentation/trace/uprobetracer.rst index 3a1797d707f4..122d15572fd5 100644 --- a/Documentation/trace/uprobetracer.rst +++ b/Documentation/trace/uprobetracer.rst @@ -12,13 +12,13 @@ To enable this feature, build your kernel with CONFIG_UPROBE_EVENTS=y. Similar to the kprobe-event tracer, this doesn't need to be activated via current_tracer. Instead of that, add probe points via -/sys/kernel/debug/tracing/uprobe_events, and enable it via -/sys/kernel/debug/tracing/events/uprobes/<EVENT>/enable. +/sys/kernel/tracing/uprobe_events, and enable it via +/sys/kernel/tracing/events/uprobes/<EVENT>/enable. However unlike kprobe-event tracer, the uprobe event interface expects the user to calculate the offset of the probepoint in the object. -You can also use /sys/kernel/debug/tracing/dynamic_events instead of +You can also use /sys/kernel/tracing/dynamic_events instead of uprobe_events. That interface will provide unified access to other dynamic events too. @@ -79,7 +79,7 @@ For $comm, the default type is "string"; any other type is invalid. Event Profiling --------------- You can check the total number of probe hits per event via -/sys/kernel/debug/tracing/uprobe_profile. The first column is the filename, +/sys/kernel/tracing/uprobe_profile. The first column is the filename, the second is the event name, the third is the number of probe hits. Usage examples @@ -87,28 +87,28 @@ Usage examples * Add a probe as a new uprobe event, write a new definition to uprobe_events as below (sets a uprobe at an offset of 0x4245c0 in the executable /bin/bash):: - echo 'p /bin/bash:0x4245c0' > /sys/kernel/debug/tracing/uprobe_events + echo 'p /bin/bash:0x4245c0' > /sys/kernel/tracing/uprobe_events * Add a probe as a new uretprobe event:: - echo 'r /bin/bash:0x4245c0' > /sys/kernel/debug/tracing/uprobe_events + echo 'r /bin/bash:0x4245c0' > /sys/kernel/tracing/uprobe_events * Unset registered event:: - echo '-:p_bash_0x4245c0' >> /sys/kernel/debug/tracing/uprobe_events + echo '-:p_bash_0x4245c0' >> /sys/kernel/tracing/uprobe_events * Print out the events that are registered:: - cat /sys/kernel/debug/tracing/uprobe_events + cat /sys/kernel/tracing/uprobe_events * Clear all events:: - echo > /sys/kernel/debug/tracing/uprobe_events + echo > /sys/kernel/tracing/uprobe_events Following example shows how to dump the instruction pointer and %ax register at the probed text address. Probe zfree function in /bin/zsh:: - # cd /sys/kernel/debug/tracing/ + # cd /sys/kernel/tracing/ # cat /proc/`pgrep zsh`/maps | grep /bin/zsh | grep r-xp 00400000-0048a000 r-xp 00000000 08:03 130904 /bin/zsh # objdump -T /bin/zsh | grep -w zfree @@ -168,7 +168,7 @@ Also, you can disable the event by:: # echo 0 > events/uprobes/enable -And you can see the traced information via /sys/kernel/debug/tracing/trace. +And you can see the traced information via /sys/kernel/tracing/trace. :: # cat trace diff --git a/Documentation/trace/user_events.rst b/Documentation/trace/user_events.rst index 9f181f342a70..422802ef4025 100644 --- a/Documentation/trace/user_events.rst +++ b/Documentation/trace/user_events.rst @@ -11,10 +11,10 @@ that can be viewed via existing tools, such as ftrace and perf. To enable this feature, build your kernel with CONFIG_USER_EVENTS=y. Programs can view status of the events via -/sys/kernel/debug/tracing/user_events_status and can both register and write -data out via /sys/kernel/debug/tracing/user_events_data. +/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/debug/tracing/dynamic_events to register and +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. @@ -22,9 +22,9 @@ 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 gives back two ints to the program for each event. The first int is the status bit. This describes which bit in little-endian format in the -/sys/kernel/debug/tracing/user_events_status file represents this event. The +/sys/kernel/tracing/user_events_status file represents this event. The second int is the write index which describes the data when a write() or -writev() is called on the /sys/kernel/debug/tracing/user_events_data file. +writev() is called on the /sys/kernel/tracing/user_events_data file. The structures referenced in this document are contained within the /include/uapi/linux/user_events.h file in the source tree. @@ -35,7 +35,7 @@ filesystem and may be mounted at different paths than above.* Registering ----------- Registering within a user process is done via ioctl() out to the -/sys/kernel/debug/tracing/user_events_data file. The command to issue is +/sys/kernel/tracing/user_events_data file. The command to issue is DIAG_IOCSREG. This command takes a packed struct user_reg as an argument:: @@ -54,7 +54,7 @@ and the write index. User based events show up under tracefs like any other event under the subsystem named "user_events". This means tools that wish to attach to the -events need to use /sys/kernel/debug/tracing/events/user_events/[name]/enable +events need to use /sys/kernel/tracing/events/user_events/[name]/enable or perf record -e user_events:[name] when attaching/recording. **NOTE:** *The write_index returned is only valid for the FD that was used* @@ -96,7 +96,7 @@ Would be represented by the following field:: Deleting ----------- Deleting an event from within a user process is done via ioctl() out to the -/sys/kernel/debug/tracing/user_events_data file. The command to issue is +/sys/kernel/tracing/user_events_data file. The command to issue is DIAG_IOCSDEL. This command only requires a single string specifying the event to delete by @@ -110,7 +110,7 @@ When tools attach/record user based events the status of the event is updated in realtime. This allows user programs to only incur the cost of the write() or writev() calls when something is actively attached to the event. -User programs call mmap() on /sys/kernel/debug/tracing/user_events_status to +User programs call mmap() on /sys/kernel/tracing/user_events_status to check the status for each event that is registered. The bit to check in the file is given back after the register ioctl() via user_reg.status_bit. The bit is always in little-endian format. Programs can check if the bit is set either diff --git a/Documentation/translations/it_IT/admin-guide/README.rst b/Documentation/translations/it_IT/admin-guide/README.rst index b37166817842..c874586a9af9 100644 --- a/Documentation/translations/it_IT/admin-guide/README.rst +++ b/Documentation/translations/it_IT/admin-guide/README.rst @@ -4,7 +4,7 @@ .. _it_readme: -Rilascio del kernel Linux 5.x <http://kernel.org/> +Rilascio del kernel Linux 6.x <http://kernel.org/> =================================================== .. warning:: diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst index 78082281acf9..5cece223b46b 100644 --- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst +++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst @@ -3,6 +3,8 @@ .. note:: Per leggere la documentazione originale in inglese: :ref:`Documentation/doc-guide/index.rst <doc_guide>` +.. title:: Commenti in kernel-doc + .. _it_kernel_doc: ================================= diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst index 64528790dc34..1f513bc33618 100644 --- a/Documentation/translations/it_IT/doc-guide/sphinx.rst +++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst @@ -151,7 +151,8 @@ Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``) dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx verrà utilizzato per ottenere una documentazione HTML più gradevole. Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX` -e di ``convert(1)`` disponibile in ImageMagick (https://www.imagemagick.org). +e di ``convert(1)`` disponibile in ImageMagick +(https://www.imagemagick.org). \ [#ink]_ Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle distribuzioni Linux. @@ -162,9 +163,20 @@ la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``. Potete anche personalizzare l'ouptut html passando un livello aggiuntivo DOCS_CSS usando la rispettiva variabile d'ambiente ``DOCS_CSS``. +La variable make ``SPHINXDIRS`` è utile quando si vuole generare solo una parte +della documentazione. Per esempio, si possono generare solo di documenti in +``Documentation/doc-guide`` eseguendo ``make SPHINXDIRS=doc-guide htmldocs``. La +sezione dedicata alla documentazione di ``make help`` vi mostrerà quali sotto +cartelle potete specificare. + Potete eliminare la documentazione generata tramite il comando ``make cleandocs``. +.. [#ink] Avere installato anche ``inkscape(1)`` dal progetto Inkscape () + potrebbe aumentare la qualità delle immagini che verranno integrate + nel documento PDF, specialmente per quando si usando rilasci del + kernel uguali o superiori a 5.18 + Scrivere la documentazione ========================== diff --git a/Documentation/translations/it_IT/index.rst b/Documentation/translations/it_IT/index.rst index e80a3097aa57..fc5f39814e83 100644 --- a/Documentation/translations/it_IT/index.rst +++ b/Documentation/translations/it_IT/index.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. _it_linux_doc: =================== @@ -67,75 +69,68 @@ I miglioramenti alla documentazione sono sempre i benvenuti; per cui, se vuoi aiutare, iscriviti alla lista di discussione linux-doc presso vger.kernel.org. -Documentazione sulla licenza dei sorgenti ------------------------------------------ - -I seguenti documenti descrivono la licenza usata nei sorgenti del kernel Linux -(GPLv2), come licenziare i singoli file; inoltre troverete i riferimenti al -testo integrale della licenza. +Lavorare con la comunità di sviluppo +------------------------------------ -* :ref:`it_kernel_licensing` +Le guide fondamentali per l'interazione con la comunità di sviluppo del kernel e +su come vedere il proprio lavoro integrato. -Documentazione per gli utenti ------------------------------ - -I seguenti manuali sono scritti per gli *utenti* del kernel - ovvero, -coloro che cercano di farlo funzionare in modo ottimale su un dato sistema - -.. warning:: +.. toctree:: + :maxdepth: 1 - TODO ancora da tradurre + process/development-process + process/submitting-patches + Code of conduct <process/code-of-conduct> + All development-process docs <process/index> -Documentazione per gli sviluppatori di applicazioni ---------------------------------------------------- -Il manuale delle API verso lo spazio utente è una collezione di documenti -che descrivono le interfacce del kernel viste dagli sviluppatori -di applicazioni. +Manuali sull'API interna +------------------------ -.. warning:: +Di seguito una serie di manuali per gli sviluppatori che hanno bisogno di +interfacciarsi con il resto del kernel. - TODO ancora da tradurre +.. toctree:: + :maxdepth: 1 + core-api/index -Introduzione allo sviluppo del kernel -------------------------------------- +Strumenti e processi per lo sviluppo +------------------------------------ -Questi manuali contengono informazioni su come contribuire allo sviluppo -del kernel. -Attorno al kernel Linux gira una comunità molto grande con migliaia di -sviluppatori che contribuiscono ogni anno. Come in ogni grande comunità , -sapere come le cose vengono fatte renderà il processo di integrazione delle -vostre modifiche molto più semplice +Di seguito una serie di manuali contenenti informazioni utili a tutti gli +sviluppatori del kernel. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - process/index + process/license-rules doc-guide/index kernel-hacking/index -Documentazione della API del kernel ------------------------------------ +Documentazione per gli utenti +----------------------------- -Questi manuali forniscono dettagli su come funzionano i sottosistemi del -kernel dal punto di vista degli sviluppatori del kernel. Molte delle -informazioni contenute in questi manuali sono prese direttamente dai -file sorgenti, informazioni aggiuntive vengono aggiunte solo se necessarie -(o almeno ci proviamo — probabilmente *non* tutto quello che è davvero -necessario). +Di seguito una serie di manuali per gli *utenti* del kernel - ovvero coloro che +stanno cercando di farlo funzionare al meglio per un dato sistema, ma anche +coloro che stanno sviluppando applicazioni che sfruttano l'API verso lo +spazio-utente. -.. toctree:: - :maxdepth: 2 +Consultate anche `Linux man pages <https://www.kernel.org/doc/man-pages/>`_, che +vengono mantenuti separatamente dalla documentazione del kernel Linux + +Documentazione relativa ai firmware +----------------------------------- +Di seguito informazioni sulle aspettative del kernel circa i firmware. - core-api/index Documentazione specifica per architettura ----------------------------------------- -Questi manuali forniscono dettagli di programmazione per le diverse -implementazioni d'architettura. -.. warning:: +Documentazione varia +-------------------- - TODO ancora da tradurre +Ci sono documenti che sono difficili da inserire nell'attuale organizzazione +della documentazione; altri hanno bisogno di essere migliorati e/o convertiti +nel formato *ReStructured Text*; altri sono semplicamente troppo vecchi. diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst index 560f1d0482d2..dd06bfc1a050 100644 --- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst @@ -137,7 +137,7 @@ macro :c:func:`in_softirq()` (``include/linux/preempt.h``). .. warning:: State attenti che questa macro ritornerà un falso positivo - se :ref:`botton half lock <it_local_bh_disable>` è bloccato. + se :ref:`bottom half lock <it_local_bh_disable>` è bloccato. Alcune regole basilari ====================== diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst index b8ecf41273c5..05d362b16bf0 100644 --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst @@ -1307,11 +1307,11 @@ se i dati vengono occasionalmente utilizzati da un contesto utente o da un'interruzione software. Il gestore d'interruzione non utilizza alcun *lock*, e tutti gli altri accessi verranno fatti così:: - spin_lock(&lock); + mutex_lock(&lock); disable_irq(irq); ... enable_irq(irq); - spin_unlock(&lock); + mutex_unlock(&lock); La funzione disable_irq() impedisce al gestore d'interruzioni d'essere eseguito (e aspetta che finisca nel caso fosse in esecuzione su diff --git a/Documentation/translations/it_IT/process/2.Process.rst b/Documentation/translations/it_IT/process/2.Process.rst index 62826034e0b2..25cd00351c03 100644 --- a/Documentation/translations/it_IT/process/2.Process.rst +++ b/Documentation/translations/it_IT/process/2.Process.rst @@ -136,18 +136,11 @@ Quindi, per esempio, la storia del kernel 5.2 appare così (anno 2019): La 5.2.21 fu l'aggiornamento finale per la versione 5.2. Alcuni kernel sono destinati ad essere kernel a "lungo termine"; questi -riceveranno assistenza per un lungo periodo di tempo. Al momento in cui -scriviamo, i manutentori dei kernel stabili a lungo termine sono: - - ====== ================================ ========================================== - 3.16 Ben Hutchings (kernel stabile molto più a lungo termine) - 4.4 Greg Kroah-Hartman e Sasha Levin (kernel stabile molto più a lungo termine) - 4.9 Greg Kroah-Hartman e Sasha Levin - 4.14 Greg Kroah-Hartman e Sasha Levin - 4.19 Greg Kroah-Hartman e Sasha Levin - 5.4i Greg Kroah-Hartman e Sasha Levin - ====== ================================ ========================================== +riceveranno assistenza per un lungo periodo di tempo. Consultate il seguente +collegamento per avere la lista delle versioni attualmente supportate e i +relativi manutentori: + https://www.kernel.org/category/releases.html Questa selezione di kernel di lungo periodo sono puramente dovuti ai loro manutentori, alla loro necessità e al tempo per tenere aggiornate proprio diff --git a/Documentation/translations/it_IT/process/7.AdvancedTopics.rst b/Documentation/translations/it_IT/process/7.AdvancedTopics.rst index cc1cff5d23ae..dffd813a0910 100644 --- a/Documentation/translations/it_IT/process/7.AdvancedTopics.rst +++ b/Documentation/translations/it_IT/process/7.AdvancedTopics.rst @@ -35,9 +35,9 @@ git è parte del processo di sviluppo del kernel. Gli sviluppatori che desiderassero diventare agili con git troveranno più informazioni ai seguenti indirizzi: - http://git-scm.com/ + https://git-scm.com/ - http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + https://www.kernel.org/pub/software/scm/git/docs/user-manual.html e su varie guide che potrete trovare su internet. @@ -63,7 +63,7 @@ eseguire git-daemon è relativamente semplice . Altrimenti, iniziano a svilupparsi piattaforme che offrono spazi pubblici, e gratuiti (Github, per esempio). Gli sviluppatori permanenti possono ottenere un account su kernel.org, ma non è proprio facile da ottenere; per maggiori informazioni -consultate la pagina web http://kernel.org/faq/. +consultate la pagina web https://kernel.org/faq/. In git è normale avere a che fare con tanti rami. Ogni linea di sviluppo può essere separata in "rami per argomenti" e gestiti indipendentemente. @@ -137,7 +137,7 @@ vostri rami. Citando Linus facendo, e ho bisogno di fidarmi *senza* dover passare tutte le modifiche manualmente una per una. -(http://lwn.net/Articles/224135/). +(https://lwn.net/Articles/224135/). Per evitare queste situazioni, assicuratevi che tutte le patch in un ramo siano strettamente correlate al tema delle modifiche; un ramo "driver fixes" diff --git a/Documentation/translations/it_IT/process/botching-up-ioctls.rst b/Documentation/translations/it_IT/process/botching-up-ioctls.rst new file mode 100644 index 000000000000..91732cdf808a --- /dev/null +++ b/Documentation/translations/it_IT/process/botching-up-ioctls.rst @@ -0,0 +1,249 @@ +.. include:: ../disclaimer-ita.rst + +:Original: Documentation/process/botching-up-ioctls.rst + +========================================== +(Come evitare di) Raffazzonare delle ioctl +========================================== + +Preso da: https://blog.ffwll.ch/2013/11/botching-up-ioctls.html + +Scritto da : Daniel Vetter, Copyright © 2013 Intel Corporation + +Una cosa che gli sviluppatori del sottosistema grafico del kernel Linux hanno +imparato negli ultimi anni è l'inutilità di cercare di creare un'interfaccia +unificata per gestire la memoria e le unità esecutive di diverse GPU. Dunque, +oggigiorno ogni driver ha il suo insieme di ioctl per allocare memoria ed +inviare dei programmi alla GPU. Il che è va bene dato che non c'è più un insano +sistema che finge di essere generico, ma al suo posto ci sono interfacce +dedicate. Ma al tempo stesso è più facile incasinare le cose. + +Per evitare di ripetere gli stessi errori ho preso nota delle lezioni imparate +mentre raffazzonavo il driver drm/i915. La maggior parte di queste lezioni si +focalizzano sui tecnicismi e non sulla visione d'insieme, come le discussioni +riguardo al modo migliore per implementare una ioctl per inviare compiti alla +GPU. Probabilmente, ogni sviluppatore di driver per GPU dovrebbe imparare queste +lezioni in autonomia. + + +Prerequisiti +------------ + +Prima i prerequisiti. Seguite i seguenti suggerimenti se non volete fallire in +partenza e ritrovarvi ad aggiungere un livello di compatibilità a 32-bit. + +* Usate solamente interi a lunghezza fissa. Per evitare i conflitti coi tipi + definiti nello spazio utente, il kernel definisce alcuni tipi speciali, come: + ``__u32``, ``__s64``. Usateli. + +* Allineate tutto alla lunghezza naturale delle piattaforma in uso e riempite + esplicitamente i vuoti. Non necessariamente le piattaforme a 32-bit allineano + i valori a 64-bit rispettandone l'allineamento, ma le piattaforme a 64-bit lo + fanno. Dunque, per farlo correttamente in entrambe i casi dobbiamo sempre + riempire i vuoti. + +* Se una struttura dati contiene valori a 64-bit, allora fate si che la sua + dimensione sia allineata a 64-bit, altrimenti la sua dimensione varierà su + sistemi a 32-bit e 64-bit. Avere una dimensione differente causa problemi + quando si passano vettori di strutture dati al kernel, o quando il kernel + effettua verifiche sulla dimensione (per esempio il sistema drm lo fa). + +* I puntatori sono di tipo ``__u64``, con un *cast* da/a ``uintptr_t`` da lato + spazio utente e da/a ``void __user *`` nello spazio kernel. Sforzatevi il più + possibile per non ritardare la conversione, o peggio maneggiare ``__u64`` nel + vostro codice perché questo riduce le verifiche che strumenti come sparse + possono effettuare. La macro u64_to_user_ptr() può essere usata nel kernel + per evitare avvisi riguardo interi e puntatori di dimensioni differenti. + + +Le Basi +------- + +Con la gioia d'aver evitato un livello di compatibilità , possiamo ora dare uno +sguardo alle basi. Trascurare questi punti renderà difficile la gestione della +compatibilità all'indietro ed in avanti. E dato che sbagliare al primo colpo è +garantito, dovrete rivisitare il codice o estenderlo per ogni interfaccia. + +* Abbiate un modo chiaro per capire dallo spazio utente se una nuova ioctl, o + l'estensione di una esistente, sia supportata dal kernel in esecuzione. Se non + potete fidarvi del fatto che un vecchio kernel possa rifiutare correttamente + un nuovo *flag*, modalità , o ioctl, (probabilmente perché avevate raffazzonato + qualcosa nel passato) allora dovrete implementare nel driver un meccanismo per + notificare quali funzionalità sono supportate, o in alternativa un numero di + versione. + +* Abbiate un piano per estendere le ioctl con nuovi *flag* o campi alla fine di + una struttura dati. Il sistema drm verifica la dimensione di ogni ioctl in + arrivo, ed estende con zeri ogni incongruenza fra kernel e spazio utente. + Questo aiuta, ma non è una soluzione completa dato che uno spazio utente nuovo + su un kernel vecchio non noterebbe che i campi nuovi alla fine della struttura + vengono ignorati. Dunque, anche questo avrà bisogno di essere notificato dal + driver allo spazio utente. + +* Verificate tutti i campi e *flag* inutilizzati ed i riempimenti siano a 0, + altrimenti rifiutare la ioctl. Se non lo fate il vostro bel piano per + estendere le ioctl andrà a rotoli dato che qualcuno userà delle ioctl con + strutture dati con valori casuali dallo stack nei campi inutilizzati. Il che + si traduce nell'avere questi campi nell'ABI, e la cui unica utilità sarà + quella di contenere spazzatura. Per questo dovrete esplicitamente riempire i + vuoti di tutte le vostre strutture dati, anche se non le userete in un + vettore. Il riempimento fatto dal compilatore potrebbe contenere valori + casuali. + +* Abbiate un semplice codice di test per ognuno dei casi sopracitati. + + +Divertirsi coi percorsi d'errore +-------------------------------- + +Oggigiorno non ci sono più scuse rimaste per permettere ai driver drm di essere +sfruttati per diventare root. Questo significa che dobbiamo avere una completa +validazione degli input e gestire in modo robusto i percorsi - tanto le GPU +moriranno comunque nel più strano dei casi particolari: + + * Le ioctl devono verificare l'overflow dei vettori. Inoltre, per i valori + interi si devono verificare *overflow*, *underflow*, e *clamping*. Il + classico esempio è l'inserimento direttamente nell'hardware di valori di + posizionamento di un'immagine *sprite* quando l'hardware supporta giusto 12 + bit, o qualcosa del genere. Tutto funzionerà finché qualche strano *display + server* non decide di preoccuparsi lui stesso del *clamping* e il cursore + farà il giro dello schermo. + + * Avere un test semplice per ogni possibile fallimento della vostra ioctl. + Verificate che il codice di errore rispetti le aspettative. Ed infine, + assicuratevi che verifichiate un solo percorso sbagliato per ogni sotto-test + inviando comunque dati corretti. Senza questo, verifiche precedenti + potrebbero rigettare la ioctl troppo presto, impedendo l'esecuzione del + codice che si voleva effettivamente verificare, rischiando quindi di + mascherare bachi e regressioni. + + * Fate si che tutte le vostre ioctl siano rieseguibili. Prima di tutto X adora + i segnali; secondo questo vi permetterà di verificare il 90% dei percorsi + d'errore interrompendo i vostri test con dei segnali. Grazie all'amore di X + per i segnali, otterrete gratuitamente un eccellente copertura di base per + tutti i vostri percorsi d'errore. Inoltre, siate consistenti sul modo di + gestire la riesecuzione delle ioctl - per esempio, drm ha una piccola + funzione di supporto `drmIoctl` nella sua librerie in spazio utente. Il + driver i915 l'abbozza con l'ioctl `set_tiling`, ed ora siamo inchiodati per + sempre con una semantica arcana sia nel kernel che nello spazio utente. + + + * Se non potete rendere un pezzo di codice rieseguibile, almeno rendete + possibile la sua interruzione. Le GPU moriranno e i vostri utenti non vi + apprezzeranno affatto se tenete in ostaggio il loro scatolotto (mediante un + processo X insopprimibile). Se anche recuperare lo stato è troppo complicato, + allora implementate una scadenza oppure come ultima spiaggia una rete di + sicurezza per rilevare situazioni di stallo quando l'hardware da di matto. + + * Preparate dei test riguardo ai casi particolarmente estremi nel codice di + recupero del sistema - è troppo facile create uno stallo fra il vostro codice + anti-stallo e un processo scrittore. + + +Tempi, attese e mancate scadenze +-------------------------------- + +Le GPU fanno quasi tutto in modo asincrono, dunque dobbiamo regolare le +operazioni ed attendere quelle in sospeso. Questo è davvero difficile; al +momento nessuna delle ioctl supportante dal driver drm/i915 riesce a farlo +perfettamente, il che significa che qui ci sono ancora una valanga di lezioni da +apprendere. + + * Per fare riferimento al tempo usate sempre ``CLOCK_MONOTONIC``. Oggigiorno + questo è quello che viene usato di base da alsa, drm, e v4l. Tuttavia, + lasciate allo spazio utente la possibilità di capire quali *timestamp* + derivano da domini temporali diversi come il vostro orologio di sistema + (fornito dal kernel) oppure un contatore hardware indipendente da qualche + parte. Gli orologi divergeranno, ma con questa informazione gli strumenti di + analisi delle prestazioni possono compensare il problema. Se il vostro spazio + utente può ottenere i valori grezzi degli orologi, allora considerate di + esporre anch'essi. + + * Per descrivere il tempo, usate ``__s64`` per i secondi e ``__u64`` per i + nanosecondi. Non è il modo migliore per specificare il tempo, ma è + praticamente uno standard. + + * Verificate che gli input di valori temporali siano normalizzati, e se non lo + sono scartateli. Fate attenzione perché la struttura dati ``struct ktime`` + del kernel usa interi con segni sia per i secondi che per i nanosecondi. + + * Per le scadenze (*timeout*) usate valori temporali assoluti. Se siete dei + bravi ragazzi e avete reso la vostra ioctl rieseguibile, allora i tempi + relativi tendono ad essere troppo grossolani e a causa degli arrotondamenti + potrebbero estendere in modo indefinito i tempi di attesa ad ogni + riesecuzione. Particolarmente vero se il vostro orologio di riferimento è + qualcosa di molto lento come il contatore di *frame*. Con la giacca da + avvocato delle specifiche diremmo che questo non è un baco perché tutte le + scadenze potrebbero essere estese - ma sicuramente gli utenti vi odieranno + quando le animazioni singhiozzano. + + * Considerate l'idea di eliminare tutte le ioctl sincrone con scadenze, e di + sostituirle con una versione asincrona il cui stato può essere consultato + attraverso il descrittore di file mediante ``poll``. Questo approccio si + sposa meglio in un applicazione guidata dagli eventi. + + * Sviluppate dei test per i casi estremi, specialmente verificate che i valori + di ritorno per gli eventi già completati, le attese terminate con successo, e + le attese scadute abbiano senso e servano ai vostri scopi. + + +Non perdere risorse +------------------- +Nel suo piccolo il driver drm implementa un sistema operativo specializzato per +certe GPU. Questo significa che il driver deve esporre verso lo spazio +utente tonnellate di agganci per accedere ad oggetti e altre risorse. Farlo +correttamente porterà con se alcune insidie: + + * Collegate sempre la vita di una risorsa creata dinamicamente, a quella del + descrittore di file. Considerate una mappatura 1:1 se la vostra risorsa + dev'essere condivisa fra processi - passarsi descrittori di file sul socket + unix semplifica la gestione anche per lo spazio utente. + + * Dev'esserci sempre Il supporto ``O_CLOEXEC``. + + * Assicuratevi di avere abbastanza isolamento fra utenti diversi. Di base + impostate uno spazio dei nomi riservato per ogni descrittore di file, il che + forzerà ogni condivisione ad essere esplicita. Usate uno spazio più globale + per dispositivo solo se gli oggetti sono effettivamente unici per quel + dispositivo. Un controesempio viene dall'interfaccia drm modeset, dove + oggetti specifici di dispositivo, come i connettori, condividono uno spazio + dei nomi con oggetti per il *framebuffer*, ma questi non sono per niente + condivisi. Uno spazio separato, privato di base, per i *framebuffer* sarebbe + stato meglio. + + * Pensate all'identificazione univoca degli agganci verso lo spazio utente. Per + esempio, per la maggior parte dei driver drm, si considera fallace la doppia + sottomissione di un oggetto allo stesso comando ioctl. Ma per evitarlo, se + gli oggetti sono condivisibili, lo spazio utente ha bisogno di sapere se il + driver ha importato un oggetto da un altro processo. Non l'ho ancora provato, + ma considerate l'idea di usare il numero di inode come identificatore per i + descrittori di file condivisi - che poi è come si distinguono i veri file. + Sfortunatamente, questo richiederebbe lo sviluppo di un vero e proprio + filesystem virtuale nel kernel. + + +Ultimo, ma non meno importante +------------------------------ + +Non tutti i problemi si risolvono con una nuova ioctl: + +* Pensateci su due o tre volte prima di implementare un'interfaccia privata per + un driver. Ovviamente è molto più veloce seguire questa via piuttosto che + buttarsi in lunghe discussioni alla ricerca di una soluzione più generica. Ed + a volte un'interfaccia privata è quello che serve per sviluppare un nuovo + concetto. Ma alla fine, una volta che c'è un'interfaccia generica a + disposizione finirete per mantenere due interfacce. Per sempre. + +* Considerate interfacce alternative alle ioctl. Gli attributi sysfs sono molto + meglio per impostazioni che sono specifiche di un dispositivo, o per + sotto-oggetti con una vita piuttosto statica (come le uscite dei connettori in + drm con tutti gli attributi per la sovrascrittura delle rilevazioni). O magari + solo il vostro sistema di test ha bisogno di una certa interfaccia, e allora + debugfs (che non ha un'interfaccia stabile) sarà la soluzione migliore. + +Per concludere. Questo gioco consiste nel fare le cose giuste fin da subito, +dato che se il vostro driver diventa popolare e la piattaforma hardware longeva +finirete per mantenere le vostre ioctl per sempre. Potrete tentare di deprecare +alcune orribili ioctl, ma ci vorranno anni per riuscirci effettivamente. E +ancora, altri anni prima che sparisca l'ultimo utente capace di lamentarsi per +una regressione. diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst index 10e0ef9c34b7..473ec2cc558e 100644 --- a/Documentation/translations/it_IT/process/changes.rst +++ b/Documentation/translations/it_IT/process/changes.rst @@ -35,6 +35,7 @@ PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils. GNU C 5.1 gcc --version Clang/LLVM (optional) 11.0.0 clang --version GNU make 3.81 make --version +bash 4.2 bash --version binutils 2.23 ld -v flex 2.5.35 flex --version bison 2.0 bison --version @@ -88,6 +89,11 @@ Make Per compilare il kernel vi servirà GNU make 3.81 o successivo. +Bash +---- +Per generare il kernel vengono usati alcuni script per bash. +Questo richiede bash 4.2 o successivo. + Binutils -------- @@ -370,6 +376,11 @@ Make - <ftp://ftp.gnu.org/gnu/make/> +Bash +---- + +- <ftp://ftp.gnu.org/gnu/bash/> + Binutils -------- diff --git a/Documentation/translations/it_IT/process/email-clients.rst b/Documentation/translations/it_IT/process/email-clients.rst index de7d32f78246..970671cd91af 100644 --- a/Documentation/translations/it_IT/process/email-clients.rst +++ b/Documentation/translations/it_IT/process/email-clients.rst @@ -106,7 +106,7 @@ Funziona. Alcune persone riescono ad usarlo con successo per inviare le patch. Per inserire una patch usate :menuselection:`Messaggio-->Inserisci file` (:kbd:`CTRL-I`) oppure un editor esterno. -Se la patch che avete inserito dev'essere modificata usato la finestra di +Se la patch che avete inserito dev'essere modificata usando la finestra di scrittura di Claws, allora assicuratevi che l'"auto-interruzione" sia disabilitata :menuselection:`Configurazione-->Preferenze-->Composizione-->Interruzione riga`. @@ -288,37 +288,62 @@ Thunderbird (GUI) Thunderbird è un clone di Outlook a cui piace maciullare il testo, ma esistono modi per impedirglielo. +Dopo la configurazione, inclusa l'installazione delle estenzioni, dovrete +riavviare Thunderbird. + - permettere l'uso di editor esterni: + La cosa più semplice da fare con Thunderbird e le patch è quello di usare - l'estensione "external editor" e di usare il vostro ``$EDITOR`` preferito per - leggere/includere patch nel vostro messaggio. Per farlo, scaricate ed - installate l'estensione e aggiungete un bottone per chiamarla rapidamente - usando :menuselection:`Visualizza-->Barra degli strumenti-->Personalizza...`; - una volta fatto potrete richiamarlo premendo sul bottone mentre siete nella - finestra :menuselection:`Scrivi` - - Tenete presente che "external editor" richiede che il vostro editor non - faccia alcun fork, in altre parole, l'editor non deve ritornare prima di - essere stato chiuso. Potreste dover passare dei parametri aggiuntivi al - vostro editor oppure cambiargli la configurazione. Per esempio, usando - gvim dovrete aggiungere l'opzione -f ``/usr/bin/gvim -f`` (Se il binario - si trova in ``/usr/bin``) nell'apposito campo nell'interfaccia di - configurazione di :menuselection:`external editor`. Se usate altri editor - consultate il loro manuale per sapere come configurarli. + estensioni che permettano di aprire il vostro editor preferito. + + Di seguito alcune estensioni che possono essere utili al caso. + + - "External Editor Revived" + + https://github.com/Frederick888/external-editor-revived + + https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor-revived/ + + L'estensione richiede l'installazione di "native messaging host". Date + un'occhiata alla seguente wiki: + https://github.com/Frederick888/external-editor-revived/wiki + + - "External Editor" + + https://github.com/exteditor/exteditor + + Per usarlo, scaricate ed installate l'applicazione. Poi aprite la finestra + :menuselection:`Scrivi` e a seguire aggiungete un bottone per eseguirlo + `Visualizza-->Barra degli strumenti-->Personalizza...`. Infine, premente + questo nuovo bottone tutte le volte che volete usare l'editor esterno. + + Tenete presente che "external editor" richiede che il vostro editor non + faccia alcun fork, in altre parole, l'editor non deve ritornare prima di + essere stato chiuso. Potreste dover passare dei parametri aggiuntivi al + vostro editor oppure cambiargli la configurazione. Per esempio, usando + gvim dovrete aggiungere l'opzione -f ``/usr/bin/gvim -f`` (Se il binario + si trova in ``/usr/bin``) nell'apposito campo nell'interfaccia di + configurazione di :menuselection:`external editor`. Se usate altri editor + consultate il loro manuale per sapere come configurarli.``)`` Per rendere l'editor interno un po' più sensato, fate così: -- Modificate le impostazioni di Thunderbird per far si che non usi - ``format=flowed``. Andate in :menuselection:`Modifica-->Preferenze-->Avanzate-->Editor di configurazione` +- Modificate le impostazioni di Thunderbird per far si che non usi ``format=flowed``! + Andate sulla finestra principale e cercate il bottone per il menu a tendina principale. + Poi :menuselection:`Modifica-->Preferenze-->Avanzate-->Editor di configurazione` per invocare il registro delle impostazioni. -- impostate ``mailnews.send_plaintext_flowed`` a ``false`` + - impostate ``mailnews.send_plaintext_flowed`` a ``false`` -- impostate ``mailnews.wraplength`` da ``72`` a ``0`` + - impostate ``mailnews.wraplength`` da ``72`` a ``0`` -- :menuselection:`Visualizza-->Corpo del messaggio come-->Testo semplice` +- Non scrivete messaggi HTML! Andate sulla finestra principale ed aprite la + schermata :menuselection:`Menu principale-->Impostazioni account-->nome@unserver.ovunque-->Composizioni e indirizzi`. + Qui potrete disabilitare l'opzione "Componi i messaggi in HTML" -- :menuselection:`Visualizza-->Codifica del testo-->Unicode` +- Aprite i messaggi solo in formato testo! Andate sulla finestra principale e + selezionate + :menuselection:`Menu principale-->Visualizza-->Copro del messaggio come-->Testo semplice` TkRat (GUI) diff --git a/Documentation/translations/it_IT/process/index.rst b/Documentation/translations/it_IT/process/index.rst index 8d4e36a07ff4..25602c1a97d1 100644 --- a/Documentation/translations/it_IT/process/index.rst +++ b/Documentation/translations/it_IT/process/index.rst @@ -58,6 +58,7 @@ perché non si è trovato un posto migliore. adding-syscalls magic-number volatile-considered-harmful + botching-up-ioctls clang-format ../riscv/patch-acceptance diff --git a/Documentation/translations/it_IT/process/kernel-docs.rst b/Documentation/translations/it_IT/process/kernel-docs.rst index 38e0a955121a..eadcbf50a1b5 100644 --- a/Documentation/translations/it_IT/process/kernel-docs.rst +++ b/Documentation/translations/it_IT/process/kernel-docs.rst @@ -6,8 +6,8 @@ .. _it_kernel_docs: -Indice di documenti per le persone interessate a capire e/o scrivere per il kernel Linux -======================================================================================== +Ulteriore Documentazione Del Kernel Linux +========================================= .. note:: Questo documento contiene riferimenti a documenti in lingua inglese; inoltre diff --git a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst index a1e98ec9532e..5526bcabeb0a 100644 --- a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst +++ b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst @@ -163,7 +163,7 @@ chiave principale attraverso firme certificate. È quindi importante comprendere i seguenti punti: 1. Non ci sono differenze tecniche tra la chiave principale e la sottochiave. -2. In fesa di creazione, assegniamo limitazioni funzionali ad ogni chiave +2. In fase di creazione, assegniamo limitazioni funzionali ad ogni chiave assegnando capacità specifiche. 3. Una chiave PGP può avere 4 capacità : @@ -286,9 +286,7 @@ magari in una cassetta di sicurezza in banca. Probabilmente la vostra stampante non è più quello stupido dispositivo connesso alla porta parallela, ma dato che il suo output è comunque criptato con la passphrase, eseguire la stampa in un sistema "cloud" - moderno dovrebbe essere comunque relativamente sicuro. Un'opzione potrebbe - essere quella di cambiare la passphrase della vostra chiave primaria - subito dopo aver finito con paperkey. + moderno dovrebbe essere comunque relativamente sicuro. Copia di riserva di tutta la cartella GnuPG ------------------------------------------- diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index a3bb0008837a..c2cfa0948b2b 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -340,7 +340,7 @@ Assicuratevi di dire ai revisori quali cambiamenti state facendo e di ringraziarli per il loro tempo. Revisionare codice è un lavoro faticoso e che richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche in questo caso, rispondete con educazione e concentratevi sul problema che hanno -evidenziato. Quando inviate una version successiva ricordatevi di aggiungere un +evidenziato. Quando inviate una versione successiva ricordatevi di aggiungere un ``patch changelog`` alla email di intestazione o ad ogni singola patch spiegando le differenze rispetto a sottomissioni precedenti (vedere :ref:`it_the_canonical_patch_format`). diff --git a/Documentation/translations/sp_SP/process/code-of-conduct.rst b/Documentation/translations/sp_SP/process/code-of-conduct.rst new file mode 100644 index 000000000000..adc6c770cc37 --- /dev/null +++ b/Documentation/translations/sp_SP/process/code-of-conduct.rst @@ -0,0 +1,97 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/code-of-conduct.rst <code_of_conduct>` +:Translator: Contributor Covenant and Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_code_of_conduct: + +Código de Conducta para Contribuyentes ++++++++++++++++++++++++++++++++++++++++ + +Nuestro Compromiso +================== + +Nosotros, como miembros, contribuyentes y administradores nos comprometemos +a hacer de la participación en nuestra comunidad una experiencia libre de +acoso para todo el mundo, independientemente de la edad, dimensión corporal, +minusvalÃa visible o invisible, etnicidad, caracterÃsticas sexuales, +identidad y expresión de género, nivel de experiencia, educación, nivel +socio-económico, nacionalidad, apariencia personal, raza, religión, o +identidad u orientación sexual. Nos comprometemos a actuar e interactuar de +maneras que contribuyan a una comunidad abierta, acogedora, diversa, +inclusiva y sana. + +Nuestros Estándares +=================== + +Ejemplos de comportamiento que contribuyen a crear un ambiente positivo +para nuestra comunidad: + +* Demostrar empatÃa y amabilidad ante otras personas +* Respeto a diferentes opiniones, puntos de vista y experiencias +* Dar y aceptar adecuadamente retroalimentación constructiva +* Aceptar la responsabilidad y disculparse ante quienes se vean afectados + por nuestros errores, aprendiendo de la experiencia +* Centrarse en lo que sea mejor no sólo para nosotros como individuos, sino + para la comunidad en general + + +Ejemplos de comportamiento inaceptable: + +* El uso de lenguaje o imágenes sexualizadas, y aproximaciones o + atenciones sexuales de cualquier tipo +* Comentarios despectivos (trolling), insultantes o derogatorios, y ataques + personales o polÃticos +* El acoso en público o privado +* Publicar información privada de otras personas, tales como direcciones + fÃsicas o de correo + electrónico, sin su permiso explÃcito +* Otras conductas que puedan ser razonablemente consideradas como + inapropiadas en un entorno profesional + + +Aplicación de las responsabilidades +=================================== + +Los administradores de la comunidad son responsables de aclarar y hacer +cumplir nuestros estándares de comportamiento aceptable y tomarán acciones +apropiadas y correctivas de forma justa en respuesta a cualquier +comportamiento que consideren inapropiado, amenazante, ofensivo o dañino. + +Los administradores de la comunidad tendrán el derecho y la responsabilidad +de eliminar, editar o rechazar comentarios, commits, código, ediciones de +páginas de wiki, issues y otras contribuciones que no se alineen con este +Código de Conducta, y comunicarán las razones para sus decisiones de +moderación cuando sea apropiado. + +Alcance +======= + +Este código de conducta aplica tanto a espacios del proyecto como a +espacios públicos donde un individuo esté en representación del proyecto o +comunidad. Ejemplos de esto incluyen el uso de la cuenta oficial de correo +electrónico, publicaciones a través de las redes sociales oficiales, o +presentaciones con personas designadas en eventos en lÃnea o no. + +Aplicación +========== + +Instancias de comportamiento abusivo, acosador o inaceptable de otro modo +podrán ser reportadas contactando el Code of Conduct Commitee a través de +<conduct@kernel.org>. Todas las quejas serán evaluadas e investigadas de +una manera puntual y justa. El Code of Condut Commitee está obligados a +respetar la privacidad y la seguridad de quienes reporten incidentes. +Detalles de polÃticas y aplicación en particular, serán incluidos por +separado. + +Atribución +========== + +Este Código de Conducta es una adaptación del Contributor Covenant, versión +1.4, disponible en https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +Interpretación +============== + +Consulte el documento :ref:`code_of_conduct_interpretation` para ver cómo +interpretará la comunidad del kernel Linux este documento. diff --git a/Documentation/translations/sp_SP/process/email-clients.rst b/Documentation/translations/sp_SP/process/email-clients.rst new file mode 100644 index 000000000000..fdf1e51b84e4 --- /dev/null +++ b/Documentation/translations/sp_SP/process/email-clients.rst @@ -0,0 +1,374 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/email-clients.rst <email_clients>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_email_clients: + +Información de clientes de correo electrónico para Linux +======================================================== + +Git +--- + +A dÃa de hoy, la mayorÃa de los desarrolladores usan ``git send-email`` en +lugar de los clientes de correo electrónico normales. La página de manual +para esto es bastante buena. En la recepción del correo, los maintainers +usan ``git am`` para aplicar los parches. + +Si es usted nuevo en ``git`` entonces envÃese su primer parche. Guárdelo +como texto sin formato, incluidos todos los encabezados. Ejecute ``git am raw_email.txt`` +y luego revise el registro de cambios con ``git log``. Cuando eso funcione, +envÃe el parche a la(s) lista(s) de correo apropiada(s). + +Preferencias Generales +---------------------- + +Los parches para el kernel de Linux se envÃan por correo electrónico, +preferiblemente como texto en lÃnea en el cuerpo del correo electrónico. +Algunos maintainers aceptan archivos adjuntos, pero entonces los archivos +adjuntos deben tener tipo de contenido ``text/plain``. Sin embargo, los +archivos adjuntos generalmente están mal vistos porque hacen que citar +partes del parche sea más difÃcil durante el proceso de revisión del +parche. + +También se recomienda encarecidamente que utilice texto sin formato en el +cuerpo del correo electrónico, para parches y otros correos electrónicos +por igual. https://useplaintext.email puede ser útil para obtener +información sobre cómo configurar su cliente de correo electrónico +preferido, asà como una lista de clientes de correo electrónico +recomendados si aún no tiene una preferencia. + +Los clientes de correo electrónico que se utilizan para los parches del +kernel Linux deben enviar el texto del parche intacto. Por ejemplo, no +deben modificar ni eliminar pestañas o espacios, incluso al principio o al +final de las lÃneas. + +No envÃe parches con ``format=flowed``. Esto puede causar saltos de lÃnea +no deseados e inesperados. + +No deje que su cliente de correo electrónico ajuste automáticamente las +palabras por usted. Esto también puede corromper su parche. + +Los clientes de correo electrónico no deben modificar la codificación del +de caracteres del texto. Los parches enviados por correo electrónico deben +estar en codificación ASCII o UTF-8 únicamente. Si configura su cliente de +correo electrónico para enviar correos electrónicos con codificación UTF-8, +evite algunos posibles problemas con los caracteres. + +Los clientes de correo electrónico deben generar y mantener los +encabezados "References:" o "In-Reply-To:" para que el hilo de correo no +se rompa. + +Copiar y pegar (o cortar y pegar) generalmente no funciona para los +parches, porque las tabulaciones se convierten en espacios. Utilizar +xclipboard, xclip y/o xcutsel puede funcionar, pero es mejor probarlo usted +mismo o simplemente evitar copiar y pegar. + +No utilice firmas PGP/GPG en el correo que contiene parches. +Esto rompe muchos scripts que leen y aplican los parches. +(Esto deberÃa ser reparable.) + +Es una buena idea enviarse un parche a sà mismo, guardar el mensaje +recibido, y aplicarlo con éxito con 'patch' antes de enviar el parche a las +listas de correo de Linux. + +Algunas sugerencias para el cliente de correo electrónico (MUA) +--------------------------------------------------------------- + +Aquà hay algunos consejos especÃficos de configuración de MUA para editar y +enviar parches para el kernel de Linux. Estos no pretenden cubrir todo +detalle de configuración de los paquetes de software. + +Leyenda: + +- TUI = text-based user interface (interfaz de usuario basada en texto) +- GUI = graphical user interface (interfaz de usuario gráfica) + +Alpine (TUI) +************ + +Opciones de configuración: + +En la sección :menuselection:`Sending Preferences`: + +- :menuselection: `Do Not Send Flowed Text` debe estar ``enabled`` +- :menuselection:`Strip Whitespace Before Sending` debe estar ``disabled`` + +Al redactar el mensaje, el cursor debe colocarse donde el parche deberÃa +aparecer, y luego presionando :kbd:`CTRL-R` se le permite especificar e +archivo de parche a insertar en el mensaje. + +Claws Mail (GUI) +**************** + +Funciona. Algunos usan esto con éxito para los parches. + +Para insertar un parche haga :menuselection:`Message-->Insert File` (:kbd:`CTRL-I`) +o use un editor externo. + +Si el parche insertado debe editarse en la ventana de composición de Claws +"Auto wrapping" en +:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` debe +permanecer deshabilitado. + +Evolution (GUI) +*************** + +Algunos usan esto con éxito para sus parches. + +Cuando escriba un correo seleccione: Preformat + desde :menuselection:`Format-->Paragraph Style-->Preformatted` (:kbd:`CTRL-7`) + o en la barra de herramientas + +Luego haga: +:menuselection:`Insert-->Text File...` (:kbd:`ALT-N x`) +para insertar el parche. + +También puede hacer ``diff -Nru old.c new.c | xclip``, seleccione +:menuselection:`Preformat`, luego pege con el boton del medio. + +Kmail (GUI) +*********** + +Algunos usan Kmail con éxito para los parches. + +La configuración predeterminada de no redactar en HTML es adecuada; no haga +cambios en esto. + +Al redactar un correo electrónico, en las opciones, desmarque "word wrap". +La única desventaja es que cualquier texto que escriba en el correo +electrónico no se ajustará a cada palabra, por lo que tendrá que ajustar +manualmente el texto antes del parche. La forma más fácil de evitar esto es +redactar su correo electrónico con Word Wrap habilitado, luego guardar +como borrador. Una vez que lo vuelva a sacar de sus borradores, estará +envuelto por palabras y puede desmarcar "word wrap" sin perder el existente +texto. + +En la parte inferior de su correo electrónico, coloque el delimitador de +parche de uso común antes de insertar su parche: tres guiones (``---``). + +Luego desde la opción de menu :menuselection:`Message` seleccione +:menuselection:`insert file` y busque su parche. +De forma adicional, puede personalizar el menú de la barra de herramientas +de creación de mensajes y poner el icono :menuselection:`insert file`. + +Haga que la ventana del editor sea lo suficientemente ancha para que no se +envuelva ninguna lÃnea. A partir de KMail 1.13.5 (KDE 4.5.4), KMail +aplicará ajuste de texto al enviar el correo electrónico si las lÃneas se +ajustan en la ventana del redactor. Tener ajuste de palabras deshabilitado +en el menú Opciones no es suficiente. Por lo tanto, si su parche tiene +lÃneas muy largas, debe hacer que la ventana del redactor sea muy amplia +antes de enviar el correo electrónico. Consulte: https://bugs.kde.org/show_bug.cgi?id=174034 + +You can safely GPG sign attachments, but inlined text is preferred for +patches so do not GPG sign them. Signing patches that have been inserted +as inlined text will make them tricky to extract from their 7-bit encoding. + +Puede firmar archivos adjuntos con GPG de forma segura, pero se prefiere el +texto en lÃnea para parches, asà que no los firme con GPG. Firmar parches +que se han insertado como texto en lÃnea hará que sea difÃcil extraerlos de +su codificación de 7 bits. + +Si es absolutamente necesario enviar parches como archivos adjuntos en +lugar de como texto en lÃnea, haga clic con el botón derecho en el archivo +adjunto y seleccione :menuselection:`properties`, y luego +:menuselection:`Suggest automatic display` para hacer que el archivo +adjunto esté en lÃnea para que sea más visible. + +Al guardar parches que se envÃan como texto en lÃnea, seleccione el correo +electrónico que contiene el parche del panel de la lista de mensajes, haga +clic con el botón derecho y seleccione :menuselection:`save as`. Puede usar +todo el correo electrónico sin modificar como un parche de estar bien +compuesto. Los correos electrónicos se guardan como lectura y escritura +solo para el usuario, por lo que tendrá que cambiarlos para que sean +legibles en grupo y en todo el mundo si copia estos en otro lugar. + +Notas de Lotus (GUI) +******************** + +Huya de este. + +IBM Verse (Web GUI) +******************* + +Vea notas sobre Lotus. + +Mutt (TUI) +********** + +Muchos desarrolladores de Linux usan ``mutt``, por lo que debe funcionar +bastante bien. + +Mutt no viene con un editor, por lo que cualquier editor que use debe ser +utilizado de forma que no haya saltos de lÃnea automáticos. La mayorÃa de +los editores tienen una opción :menuselection:`insert file` que inserta el +contenido de un archivo inalterado. + +Para usar ``vim`` con mutt:: + + set editor="vi" + +Si utiliza xclip, escriba el comando:: + + :set paste + +antes del boton del medio o shift-insert o use:: + + :r filename + +si desea incluir el parche en lÃnea. +(a)ttach (adjuntar) funciona bien sin ``set paste``. + +También puedes generar parches con ``git format-patch`` y luego usar Mutt +para enviarlos:: + + $ mutt -H 0001-some-bug-fix.patch + +Opciones de configuración: + +DeberÃa funcionar con la configuración predeterminada. +Sin embargo, es una buena idea establecer ``send_charset`` en: + + set send_charset="us-ascii:utf-8" + +Mutt es altamente personalizable. Aquà tiene una configuración mÃnima para +empezar a usar Mutt para enviar parches a través de Gmail:: + + # .muttrc + # ================ IMAP ==================== + set imap_user = 'suusuario@gmail.com' + set imap_pass = 'sucontraseña' + set spoolfile = imaps://imap.gmail.com/INBOX + set folder = imaps://imap.gmail.com/ + set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" + set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" + set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" + + # ================ SMTP ==================== + set smtp_url = "smtp://username@smtp.gmail.com:587/" + set smtp_pass = $imap_pass + set ssl_force_tls = yes # Requerir conexión encriptada + + # ================ Composición ==================== + set editor = `echo \$EDITOR` + set edit_headers = yes # Ver los encabezados al editar + set charset = UTF-8 # valor de $LANG; also fallback for send_charset + # El remitente, la dirección de correo electrónico y la lÃnea de firma deben coincidir + unset use_domain # Porque joe@localhost es simplemente vergonzoso + set realname = "SU NOMBRE" + set from = "username@gmail.com" + set use_from = yes + +Los documentos Mutt tienen mucha más información: + + https://gitlab.com/muttmua/mutt/-/wikis/UseCases/Gmail + + http://www.mutt.org/doc/manual/ + +Pine (TUI) +********** + +Pine ha tenido algunos problemas de truncamiento de espacios en blanco en +el pasado, pero estos todo deberÃa estar arreglados ahora. + +Use alpine (sucesor de pino) si puede. + +Opciones de configuración: + +- ``quell-flowed-text`` necesitado para versiones actuales +- la opción ``no-strip-whitespace-before-send`` es necesaria + + +Sylpheed (GUI) +************** + +- Funciona bien para insertar texto (o usar archivos adjuntos). +- Permite el uso de un editor externo. +- Es lento en carpetas grandes. +- No realizará la autenticación TLS SMTP en una conexión que no sea SSL. +- Tiene una útil barra de reglas en la ventana de redacción. +- Agregar direcciones a la libreta de direcciones no las muestra + adecuadamente. + +Thunderbird (GUI) +***************** + +Thunderbird es un clon de Outlook al que le gusta alterar el texto, pero +hay formas para obligarlo a comportarse. + +Después de hacer las modificaciones, que incluye instalar las extensiones, +necesita reiniciar Thunderbird. + +- Permitir el uso de un editor externo: + + Lo más fácil de hacer con Thunderbird y los parches es usar extensiones + que abran su editor externo favorito. + + Aquà hay algunas extensiones de ejemplo que son capaces de hacer esto. + + - "External Editor Revived" + + https://github.com/Frederick888/external-editor-revived + + https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor-revived/ + + Requiere instalar un "native messaging host". + Por favor, lea la wiki que se puede encontrar aquÃ: + https://github.com/Frederick888/external-editor-revived/wiki + + - "External Editor" + + https://github.com/exteditor/exteditor + + Para hacer esto, descargue e instale la extensión, luego abra la ventana + :menuselection:`compose`, agregue un botón para ello usando + :menuselection:`View-->Toolbars-->Customize...` + luego simplemente haga clic en el botón nuevo cuando desee usar el editor + externo. + + Tenga en cuenta que "External Editor" requiere que su editor no haga + fork, o en otras palabras, el editor no debe regresar antes de cerrar. + Es posible que deba pasar flags adicionales o cambiar la configuración + de su editor. En particular, si está utilizando gvim, debe pasar la + opción -f a gvim poniendo ``/usr/bin/gvim --nofork"`` (si el binario + está en ``/usr/bin``) al campo del editor de texto en los ajustes + :menuselection:`external editor`. Si está utilizando algún otro editor, + lea su manual para saber cómo hacer esto. + +Para sacarle algo de sentido al editor interno, haga esto: + +- Edite sus ajustes de configuración de Thunderbird para que no utilice ``format=flowed``! + Vaya a su ventana principal y busque el botón de su menú desplegable principal. + :menuselection:`Main Menu-->Preferences-->General-->Config Editor...` + para abrir el editor de registro de Thunderbird. + + - Seleccione ``mailnews.send_plaintext_flowed`` como ``false`` + + - Seleccione ``mailnews.wraplength`` de ``72`` a ``0`` + +- ¡No escriba mensajes HTML! Acuda a la ventana principal + :menuselection:`Main Menu-->Account Settings-->youracc@server.something-->Composition & Addressing`! + Ahà puede deshabilitar la opción "Compose messages in HTML format". + +- ¡Abra mensajes solo como texto sin formato! Acuda a la ventana principal + :menuselection:`Main Menu-->View-->Message Body As-->Plain Text`! + +TkRat (GUI) +*********** + +Funciona. Utilice "Insert file..." o un editor externo. + +Gmail (Web GUI) +*************** + +No funciona para enviar parches. + +El cliente web de Gmail convierte las tabulaciones en espacios automáticamente. + +Al mismo tiempo, envuelve lÃneas cada 78 caracteres con saltos de lÃnea de +estilo CRLF aunque el problema de tab2space se puede resolver con un editor +externo. + +Otro problema es que Gmail codificará en base64 cualquier mensaje que tenga +un carácter no ASCII. Eso incluye cosas como nombres europeos. diff --git a/Documentation/translations/sp_SP/process/index.rst b/Documentation/translations/sp_SP/process/index.rst index 49a05f6a5544..c978a8132ce1 100644 --- a/Documentation/translations/sp_SP/process/index.rst +++ b/Documentation/translations/sp_SP/process/index.rst @@ -13,3 +13,7 @@ submitting-patches kernel-docs coding-style + code-of-conduct + kernel-enforcement-statement + email-clients + magic-number diff --git a/Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst b/Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst new file mode 100644 index 000000000000..d66902694089 --- /dev/null +++ b/Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst @@ -0,0 +1,174 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/kernel-enforcement-statement.rst <process_statement_kernel>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_process_statement_kernel: + +Aplicación de la licencia en el kernel Linux +============================================ + +Como desarrolladores del kernel Linux, tenemos un gran interés en cómo se +se utiliza nuestro software y cómo se aplica la licencia de nuestro software. +El cumplimiento de las obligaciones de intercambio recÃproco de GPL-2.0 son +fundamentales en el largo plazo para la sostenibilidad de nuestro software +y comunidad. + +Aunque existe el derecho de hacer valer un copyright distinto en las +contribuciones hechas a nuestra comunidad, compartimos el interés de +asegurar que las acciones individuales para proteger estos se lleven a cabo +de una manera que beneficia a nuestra comunidad y no tenga un indeseado +impacto negativo en la salud y crecimiento de nuestro ecosistema de software. +Con el fin de disuadir la aplicación inútil de acciones, estamos de acuerdo +en que es en el mejor interés de nuestro desarrollo como comunidad asumir +el siguiente compromiso con los usuarios del kernel Linux, en nombre +nuestro y de cualquier sucesor de nuestros derechos de autor (copyright): + + Sin perjuicio de las disposiciones de terminación de GPL-2.0, aceptamos + que es en el mejor interés de nuestra comunidad de desarrollo adoptar + las siguientes disposiciones de GPL-3.0 como permisos adicionales bajo + nuestra licencia, con respecto a cualquier interposición de alegación + de infringimiento (en inglés, "non-defensive assertion") de los + derechos bajo la licencia. + + Sin embargo, si deja de violar esta Licencia, entonces su licencia + de copyright como particular se restablece (a) provisionalmente, + a menos que y hasta que el titular de los derechos de autor explÃcita + y finalmente rescinda su licencia, y (b) de forma permanente, si el + titular de los derechos de autor no le notifica la violación por algún + medio razonable antes de 60 dÃas después del cese. + + Además, su licencia de un titular de derechos de autor en particular es + restablecida permanentemente si el titular de los derechos de autor le + notifica de la violación por algún medio razonable, esta es la primera + vez que ha recibido notificación de violación de esta Licencia (para + cualquier trabajo) de ese titular de los derechos de autor, y subsana + la infracción antes de los 30 dÃas posteriores de recibir el aviso. + +Nuestra intención al proporcionar estas garantÃas es fomentar un mayor uso +del software. Queremos que empresas y particulares utilicen, modifiquen y +distribuyan este software. Queremos trabajar con los usuarios de forma +abierta y transparente para eliminar cualquier incertidumbre sobre nuestras +expectativas con respecto al cumplimiento que podrÃa limitar la adopción de +nuestro software. Entendemos la acción legal como último recurso, que se +iniciará solo cuando otros esfuerzos de la comunidad no hayan podido +resolver el problema. + +Finalmente, una vez que se resuelva un problema de incumplimiento, +esperamos que el usuario se sienta bienvenido a unirse a nosotros en +nuestros esfuerzos con este proyecto. Trabajando juntos, somos más fuertes. + +Excepto donde se indica a continuación, hablamos solo por nosotros mismos y +no por ninguna compañÃa donde puede que trabajemos hoy, o hayamos trabajado +en el pasado, o trabajaremos en el futuro. + +- Laura Abbott +- Bjorn Andersson (Linaro) +- Andrea Arcangeli +- Neil Armstrong +- Jens Axboe +- Pablo Neira Ayuso +- Khalid Aziz +- Ralf Baechle +- Felipe Balbi +- Arnd Bergmann +- Ard Biesheuvel +- Tim Bird +- Paolo Bonzini +- Christian Borntraeger +- Mark Brown (Linaro) +- Paul Burton +- Javier Martinez Canillas +- Rob Clark +- Kees Cook (Google) +- Jonathan Corbet +- Dennis Dalessandro +- Vivien Didelot (Savoir-faire Linux) +- Hans de Goede +- Mel Gorman (SUSE) +- Sven Eckelmann +- Alex Elder (Linaro) +- Fabio Estevam +- Larry Finger +- Bhumika Goyal +- Andy Gross +- Juergen Gross +- Shawn Guo +- Ulf Hansson +- Stephen Hemminger (Microsoft) +- Tejun Heo +- Rob Herring +- Masami Hiramatsu +- Michal Hocko +- Simon Horman +- Johan Hovold (Hovold Consulting AB) +- Christophe JAILLET +- Olof Johansson +- Lee Jones (Linaro) +- Heiner Kallweit +- Srinivas Kandagatla +- Jan Kara +- Shuah Khan (Samsung) +- David Kershner +- Jaegeuk Kim +- Namhyung Kim +- Colin Ian King +- Jeff Kirsher +- Greg Kroah-Hartman (Linux Foundation) +- Christian König +- Vinod Koul +- Krzysztof Kozlowski +- Viresh Kumar +- Aneesh Kumar K.V +- Julia Lawall +- Doug Ledford +- Chuck Lever (Oracle) +- Daniel Lezcano +- Shaohua Li +- Xin Long +- Tony Luck +- Catalin Marinas (Arm Ltd) +- Mike Marshall +- Chris Mason +- Paul E. McKenney +- Arnaldo Carvalho de Melo +- David S. Miller +- Ingo Molnar +- Kuninori Morimoto +- Trond Myklebust +- Martin K. Petersen (Oracle) +- Borislav Petkov +- Jiri Pirko +- Josh Poimboeuf +- Sebastian Reichel (Collabora) +- Guenter Roeck +- Joerg Roedel +- Leon Romanovsky +- Steven Rostedt (VMware) +- Frank Rowand +- Ivan Safonov +- Anna Schumaker +- Jes Sorensen +- K.Y. Srinivasan +- David Sterba (SUSE) +- Heiko Stuebner +- Jiri Kosina (SUSE) +- Willy Tarreau +- Dmitry Torokhov +- Linus Torvalds +- Thierry Reding +- Rik van Riel +- Luis R. Rodriguez +- Geert Uytterhoeven (Glider bvba) +- Eduardo Valentin (Amazon.com) +- Daniel Vetter +- Linus Walleij +- Richard Weinberger +- Dan Williams +- Rafael J. Wysocki +- Arvind Yadav +- Masahiro Yamada +- Wei Yongjun +- Lv Zheng +- Marc Zyngier (Arm Ltd) + diff --git a/Documentation/translations/sp_SP/process/magic-number.rst b/Documentation/translations/sp_SP/process/magic-number.rst new file mode 100644 index 000000000000..2b62cec34e8e --- /dev/null +++ b/Documentation/translations/sp_SP/process/magic-number.rst @@ -0,0 +1,90 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/magic-number.rst <magicnumbers>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_magicnumbers: + +Números mágicos de Linux +======================== + +Este archivo es un registro de los números mágicos que están en uso. Cuando +usted incluya un número mágico a una estructura, también debe agregarlo a +este documento, ya que es mejor si los números mágicos utilizados por +varias estructuras son únicos. + +Es una muy buena idea proteger las estructuras de datos del kernel con +números mágicos. Esto le permite verificar en tiempo de ejecución si (a) +una estructura ha sido manipulada, o (b) ha pasado la estructura incorrecta +a una rutina. Esto último es especialmente útil --- particularmente cuando +pasa punteros a estructuras a través de un puntero void \*. El código tty, +por ejemplo, hace esto con frecuencia para pasar información especÃfica del +driver y lÃneas de estructuras especÃficas de protocolo de un lado al +otro. + +La forma de usar números mágicos es declararlos al principio de la +estructura, asÃ:: + + struct tty_ldisc { + int magic; + ... + }; + +Por favor, siga este método cuando agregue futuras mejoras al kernel! Me ha +ahorrado innumerables horas de depuración, especialmente en los casos +complicados donde una matriz ha sido invadida y las estructuras que siguen +a la matriz se han sobrescrito. Usando este método, estos casos se detectan +de forma rápida y segura. + +Changelog:: + + Theodore Ts'o + 31 Mar 94 + + La tabla mágica ha sido actualizada para Linux 2.1.55. + + Michael Chastain + <mailto:mec@shout.net> + 22 Sep 1997 + + Ahora deberÃa estar actualizada con Linux 2.1.112. Porque + estamos en fase de "feature freeze", es muy poco probable que + algo cambiará antes de 2.2.x. Las entradas son + ordenados por campo numérico. + + Krzysztof G. Baranowski + <mailto: kgb@knm.org.pl> + 29 Jul 1998 + + Se actualizó la tabla mágica a Linux 2.5.45. Justo sobre el feature + freeze, pero es posible que algunos nuevos números mágicos se cuelen en + el kernel antes de 2.6.x todavÃa. + + Petr Baudis + <pasky@ucw.cz> + 03 Nov 2002 + + La tabla mágica ha sido actualizada para Linux 2.5.74. + + Fabian Frederick + <ffrederick@users.sourceforge.net> + 09 Jul 2003 + +===================== ================ ======================== ========================================== +Magic Name Number Structure File +===================== ================ ======================== ========================================== +PG_MAGIC 'P' pg_{read,write}_hdr ``include/linux/pg.h`` +APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` +FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` +SLIP_MAGIC 0x5302 slip ``drivers/net/slip.h`` +MGSLPC_MAGIC 0x5402 mgslpc_info ``drivers/char/pcmcia/synclink_cs.c`` +BAYCOM_MAGIC 0x19730510 baycom_state ``drivers/net/baycom_epp.c`` +HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state ``include/linux/hdlcdrv.h`` +KV_MAGIC 0x5f4b565f kernel_vars_s ``arch/mips/include/asm/sn/klkernvars.h`` +CODA_MAGIC 0xC0DAC0DA coda_file_info ``fs/coda/coda_fs_i.h`` +YAM_MAGIC 0xF10A7654 yam_port ``drivers/net/hamradio/yam.c`` +CCB_MAGIC 0xf2691ad2 ccb ``drivers/scsi/ncr53c8xx.c`` +QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry ``drivers/scsi/arm/queue.c`` +QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry ``drivers/scsi/arm/queue.c`` +NMI_MAGIC 0x48414d4d455201 nmi_s ``arch/mips/include/asm/sn/nmi.h`` +===================== ================ ======================== ========================================== diff --git a/Documentation/translations/zh_CN/PCI/msi-howto.rst b/Documentation/translations/zh_CN/PCI/msi-howto.rst index 7ea4d50cdad2..1b9b5ea790d8 100644 --- a/Documentation/translations/zh_CN/PCI/msi-howto.rst +++ b/Documentation/translations/zh_CN/PCI/msi-howto.rst @@ -231,3 +231,14 @@ ACPI FADT表ä¸æŒ‡æ˜Žäº†å®ƒã€‚在这ç§æƒ…况下，Linux会自动ç¦ç”¨MSI。有 也需è¦æ£€æŸ¥è®¾å¤‡é©±åŠ¨ç¨‹åºï¼Œçœ‹å®ƒæ˜¯å¦æ”¯æŒMSI。例如，它å¯èƒ½åŒ…å«å¯¹å¸¦æœ‰PCI_IRQ_MSI或 PCI_IRQ_MSIXæ ‡å¿—çš„pci_alloc_irq_vectors（）的调用。 + + +MSI(-X) APIs设备驱动程åºåˆ—表 +============================ + +PCI/MSIå系统有一个专门的C文件，用于其导出的设备驱动程åºAPIs - `drivers/pci/msi/api.c` 。 +以下是导出的函数: + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +drivers/pci/msi/api.c diff --git a/Documentation/translations/zh_CN/accounting/delay-accounting.rst b/Documentation/translations/zh_CN/accounting/delay-accounting.rst index f1849411018e..a01dc3d5b0db 100644 --- a/Documentation/translations/zh_CN/accounting/delay-accounting.rst +++ b/Documentation/translations/zh_CN/accounting/delay-accounting.rst @@ -17,8 +17,9 @@ a) ç‰å¾…一个CPU（任务为å¯è¿è¡Œï¼‰ b) 完æˆç”±è¯¥ä»»åŠ¡å‘èµ·çš„å—I/OåŒæ¥è¯·æ±‚ c) 页é¢äº¤æ¢ d) 内å˜å›žæ”¶ -e) 页缓å˜æŠ–动 +e) 抖动 f) 直接规整 +g) 写ä¿æŠ¤å¤åˆ¶ 并将这些统计信æ¯é€šè¿‡taskstats接å£æ供给用户空间。 @@ -42,7 +43,7 @@ f) 直接规整 include/uapi/linux/taskstats.h å…¶æ述了延时计数相关å—段。系统通常以计数器形å¼è¿”回 CPUã€åŒæ¥å— I/Oã€äº¤æ¢ã€å†…å˜ -回收ã€é¡µç¼“å˜æŠ–动ã€ç›´æŽ¥è§„æ•´ç‰çš„累积延时。 +回收ã€é¡µç¼“å˜æŠ–动ã€ç›´æŽ¥è§„æ•´ã€å†™ä¿æŠ¤å¤åˆ¶ç‰çš„累积延时。 å–任务æŸè®¡æ•°å™¨ä¸¤ä¸ªè¿žç»è¯»æ•°çš„差值，将得到任务在该时间间隔内ç‰å¾…对应资æºçš„总延时。 @@ -100,6 +101,8 @@ getdelayså‘½ä»¤çš„ä¸€èˆ¬æ ¼å¼:: 0 0 0ms COMPACT count delay total delay average 0 0 0ms + WPCOPY count delay total delay average + 0 0 0ms 获å–pid为1çš„IO计数，它åªå’Œ-p一起使用:: # ./getdelays -i -p 1 diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst index 30c69e1f44fe..6f8676a50b38 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst @@ -22,6 +22,7 @@ start usage reclaim + lru_sort diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst new file mode 100644 index 000000000000..812ef315c8f6 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst @@ -0,0 +1,263 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_CN.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_CN/admin-guide/mm/damon/reclaim.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst index c976f3e33ffd..d14ba32f7788 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst @@ -45,11 +45,7 @@ DAMON_RECLAIM找到在特定时间内没有被访问的内å˜åŒºåŸŸå¹¶åˆ†é¡µã€‚ä 为了让系统管ç†å‘˜å¯ç”¨æˆ–ç¦ç”¨å®ƒï¼Œå¹¶ä¸ºç»™å®šçš„系统进行调整，DAMON_RECLAIM利用了模å—å‚数。也就 æ˜¯è¯´ï¼Œä½ å¯ä»¥æŠŠ ``damon_reclaim.<parameter>=<value>`` æ”¾åœ¨å†…æ ¸å¯åŠ¨å‘½ä»¤è¡Œä¸Šï¼Œæˆ–者把 -适当的值写入 ``/sys/modules/damon_reclaim/parameters/<parameter>`` 文件。 - -注æ„，除 ``å¯ç”¨`` 外的å‚数值åªåœ¨DAMON_RECLAIMå¯åŠ¨æ—¶åº”ç”¨ã€‚å› æ¤ï¼Œå¦‚æžœä½ æƒ³åœ¨è¿è¡Œæ—¶åº”用新 -çš„å‚数值，而DAMON_RECLAIMå·²ç»è¢«å¯ç”¨ï¼Œä½ 应该通过 ``å¯ç”¨`` çš„å‚数文件ç¦ç”¨å’Œé‡æ–°å¯ç”¨å®ƒã€‚ -在é‡æ–°å¯ç”¨ä¹‹å‰ï¼Œåº”将新的å‚数值写入适当的å‚数值ä¸ã€‚ +适当的值写入 ``/sys/module/damon_reclaim/parameters/<parameter>`` 文件。 下é¢æ˜¯æ¯ä¸ªå‚æ•°çš„æ述。 @@ -218,7 +214,7 @@ nr_quota_exceeds 就开始真æ£çš„工作。如果DAMON_RECLAIM没有å–å¾—è¿›å±•ï¼Œå› æ¤ç©ºé—²å†…å˜çŽ‡ä½ŽäºŽ20%，它会è¦æ±‚ DAMON_RECLAIMå†æ¬¡ä»€ä¹ˆéƒ½ä¸åšï¼Œè¿™æ ·æˆ‘们就å¯ä»¥é€€å›žåˆ°åŸºäºŽLRU列表的页é¢ç²’度回收了:: - # cd /sys/modules/damon_reclaim/parameters + # cd /sys/module/damon_reclaim/parameters # echo 30000000 > min_age # echo $((1 * 1024 * 1024 * 1024)) > quota_sz # echo 1000 > quota_reset_interval_ms diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst index 67d1b49481dc..bf21ff84f396 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst @@ -34,16 +34,8 @@ https://github.com/awslabs/damo找到。下é¢çš„例åå‡è®¾DAMOåœ¨ä½ çš„$PATH上。当然，但 这并ä¸æ˜¯å¼ºåˆ¶æ€§çš„。 -å› ä¸ºDAMO使用的是DAMONçš„debugfs接å£(详情请å‚考 :doc:`usage` ä¸çš„使用方法) ä½ åº”è¯¥ -ç¡®ä¿debugfs被挂载。手动挂载它，如下所示:: - - # mount -t debugfs none /sys/kernel/debug/ - -æˆ–è€…åœ¨ä½ çš„ ``/etc/fstab`` 文件ä¸æ·»åŠ ä»¥ä¸‹ä¸€è¡Œï¼Œè¿™æ ·ä½ çš„ç³»ç»Ÿå°±å¯ä»¥åœ¨å¯åŠ¨æ—¶è‡ªåŠ¨æŒ‚è½½ -debugfs了:: - - debugfs /sys/kernel/debug debugfs defaults 0 0 - +å› ä¸ºDAMO使用了DAMONçš„sysfs接å£ï¼ˆè¯¦æƒ…请å‚考:doc:`usage`ï¼‰ï¼Œä½ åº”è¯¥ç¡®ä¿ +:doc:`sysfs </filesystems/sysfs>` 被挂载。 记录数æ®è®¿é—®æ¨¡å¼ ================ diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst index aeae2ab65dd8..17b9949d9b43 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst @@ -46,10 +46,10 @@ DAMONçš„sysfs接å£æ˜¯åœ¨å®šä¹‰ ``CONFIG_DAMON_SYSFS`` 时建立的。它在其s 对于一个简çŸçš„例å，用户å¯ä»¥ç›‘测一个给定工作负载的虚拟地å€ç©ºé—´ï¼Œå¦‚下所示:: # cd /sys/kernel/mm/damon/admin/ - # echo 1 > kdamonds/nr && echo 1 > kdamonds/0/contexts/nr + # 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 - # echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid + # 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 文件层次结构 @@ -82,6 +82,9 @@ DAMON sysfs接å£çš„文件层次结构如下图所示。在下图ä¸ï¼Œçˆ¶åå…³ │ │ │ │ │ │ │ │ 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 + │ │ │ │ │ │ │ │ ... │ │ │ │ │ │ ... │ │ │ │ ... │ │ ... @@ -111,7 +114,11 @@ kdamonds/<N>/ è¯»å– ``state`` 时，如果kdamond当å‰æ£åœ¨è¿è¡Œï¼Œåˆ™è¿”回 ``on`` ，如果没有è¿è¡Œåˆ™è¿”回 ``off`` 。 写入 ``on`` 或 ``off`` 使kdamond处于状æ€ã€‚å‘ ``state`` 文件写 ``update_schemes_stats`` ， æ›´æ–°kdamondçš„æ¯ä¸ªåŸºäºŽDAMONçš„æ“作方案的统计文件的内容。关于统计信æ¯çš„细节，请å‚考 -:ref:`stats section <sysfs_schemes_stats>`. +: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。 @@ -186,6 +193,8 @@ regions/<N>/ 在æ¯ä¸ªåŒºåŸŸç›®å½•ä¸ï¼Œä½ 会å‘现两个文件（ ``start`` å’Œ ``end`` ï¼‰ã€‚ä½ å¯ä»¥é€šè¿‡å‘文件写入 和从文件ä¸è¯»å‡ºï¼Œåˆ†åˆ«è®¾ç½®å’ŒèŽ·å¾—åˆå§‹ç›‘æµ‹ç›®æ ‡åŒºåŸŸçš„èµ·å§‹å’Œç»“æŸåœ°å€ã€‚ +æ¯ä¸ªåŒºåŸŸä¸åº”该与其他区域é‡å 。 目录“Nâ€çš„“结æŸâ€åº”ç‰äºŽæˆ–å°äºŽç›®å½•â€œN+1â€çš„“开始â€ã€‚ + contexts/<N>/schemes/ --------------------- @@ -199,8 +208,8 @@ contexts/<N>/schemes/ schemes/<N>/ ------------ -在æ¯ä¸ªæ–¹æ¡ˆç›®å½•ä¸ï¼Œå˜åœ¨å››ä¸ªç›®å½•(``access_pattern``, ``quotas``,``watermarks``, -å’Œ ``stats``)和一个文件(``action``)。 +在æ¯ä¸ªæ–¹æ¡ˆç›®å½•ä¸ï¼Œå˜åœ¨äº”个目录(``access_pattern``ã€``quotas``ã€``watermarks``〠+``stats`` å’Œ ``tried_regions``)和一个文件(``action``)。 ``action`` 文件用于设置和获å–ä½ æƒ³åº”ç”¨äºŽå…·æœ‰ç‰¹å®šè®¿é—®æ¨¡å¼çš„内å˜åŒºåŸŸçš„动作。å¯ä»¥å†™å…¥æ–‡ä»¶ 和从文件ä¸è¯»å–的关键è¯åŠå…¶å«ä¹‰å¦‚下。 @@ -229,8 +238,8 @@ schemes/<N>/quotas/ æ¯ä¸ª ``动作`` 的最佳 ``ç›®æ ‡è®¿é—®æ¨¡å¼`` å–决于工作负载，所以ä¸å®¹æ˜“找到。更糟糕的是，将æŸäº›åŠ¨ä½œ çš„æ–¹æ¡ˆè®¾ç½®å¾—è¿‡äºŽæ¿€è¿›ä¼šé€ æˆä¸¥é‡çš„开销。为了é¿å…è¿™ç§å¼€é”€ï¼Œç”¨æˆ·å¯ä»¥ä¸ºæ¯ä¸ªæ–¹æ¡ˆé™åˆ¶æ—¶é—´å’Œå¤§å°é…é¢ã€‚ -具体æ¥è¯´ï¼Œç”¨æˆ·å¯ä»¥è¦æ±‚DAMONå°½é‡åªä½¿ç”¨ç‰¹å®šçš„时间（``时间é…é¢``）æ¥åº”用行动，并且在给定的时间间 -隔（``é‡ç½®é—´éš”``）内，åªå¯¹å…·æœ‰ç›®æ ‡è®¿é—®æ¨¡å¼çš„内å˜åŒºåŸŸåº”用行动，而ä¸ä½¿ç”¨ç‰¹å®šæ•°é‡ï¼ˆ``大å°é…é¢``）。 +具体æ¥è¯´ï¼Œç”¨æˆ·å¯ä»¥è¦æ±‚DAMONå°½é‡åªä½¿ç”¨ç‰¹å®šçš„时间（``时间é…é¢``）æ¥åº”用动作，并且在给定的时间间 +隔（``é‡ç½®é—´éš”``）内，åªå¯¹å…·æœ‰ç›®æ ‡è®¿é—®æ¨¡å¼çš„内å˜åŒºåŸŸåº”用动作，而ä¸ä½¿ç”¨ç‰¹å®šæ•°é‡ï¼ˆ``大å°é…é¢``）。 当预计超过é…é¢é™åˆ¶æ—¶ï¼ŒDAMONä¼šæ ¹æ® ``ç›®æ ‡è®¿é—®æ¨¡å¼`` 的大å°ã€è®¿é—®é¢‘率和年龄，对找到的内å˜åŒºåŸŸ 进行优先排åºã€‚为了进行个性化的优先排åºï¼Œç”¨æˆ·å¯ä»¥ä¸ºè¿™ä¸‰ä¸ªå±žæ€§è®¾ç½®æƒé‡ã€‚ @@ -272,6 +281,24 @@ DAMON统计æ¯ä¸ªæ–¹æ¡ˆè¢«å°è¯•åº”用的区域的总数é‡å’Œå—节数，æ¯ä¸ª ä½ åº”è¯¥è¦æ±‚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`` +å’Œ ``年龄`` 。 + 用例 ~~~~ @@ -287,12 +314,12 @@ DAMON统计æ¯ä¸ªæ–¹æ¡ˆè¢«å°è¯•åº”用的区域的总数é‡å’Œå—节数，æ¯ä¸ª # 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_patterns/sz/min - # echo 8192 > access_patterns/sz/max - # echo 0 > access_patterns/nr_accesses/min - # echo 5 > access_patterns/nr_accesses/max - # echo 10 > access_patterns/age/min - # echo 20 > access_patterns/age/max + # 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 @@ -311,6 +338,11 @@ DAMON统计æ¯ä¸ªæ–¹æ¡ˆè¢«å°è¯•åº”用的区域的总数é‡å’Œå—节数，æ¯ä¸ª 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/``. @@ -364,7 +396,7 @@ DAMON导出了八个文件, ``attrs``, ``target_ids``, ``init_regions``, ç›‘æµ‹ç›®æ ‡åŒºåŸŸã€‚ 在这ç§æƒ…况下，用户å¯ä»¥é€šè¿‡åœ¨ ``init_regions`` 文件ä¸å†™å…¥é€‚当的值，明确地设置他们想è¦çš„åˆ -å§‹ç›‘æµ‹ç›®æ ‡åŒºåŸŸã€‚è¾“å…¥çš„æ¯ä¸€è¡Œåº”代表一个区域，形å¼å¦‚下:: +å§‹ç›‘æµ‹ç›®æ ‡åŒºåŸŸã€‚è¾“å…¥åº”è¯¥æ˜¯ä¸€ä¸ªç”±ä¸‰ä¸ªæ•´æ•°ç»„æˆçš„é˜Ÿåˆ—ï¼Œç”¨ç©ºæ ¼éš”å¼€ï¼Œä»£è¡¨ä¸€ä¸ªåŒºåŸŸçš„å½¢å¼å¦‚下:: <target idx> <start address> <end address> @@ -376,9 +408,9 @@ DAMON导出了八个文件, ``attrs``, ``target_ids``, ``init_regions``, # cd <debugfs>/damon # cat target_ids 42 4242 - # echo "0 1 100 - 0 100 200 - 1 20 40 + # echo "0 1 100 \ + 0 100 200 \ + 1 20 40 \ 1 50 100" > init_regions 请注æ„，这åªæ˜¯è®¾ç½®äº†åˆå§‹çš„ç›‘æµ‹ç›®æ ‡åŒºåŸŸã€‚åœ¨è™šæ‹Ÿå†…å˜ç›‘测的情况下，DAMON会在一个 ``æ›´æ–°é—´éš”`` diff --git a/Documentation/translations/zh_CN/admin-guide/mm/index.rst b/Documentation/translations/zh_CN/admin-guide/mm/index.rst index 702271c5b683..a8fd2c4a8796 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/index.rst @@ -22,7 +22,7 @@ Linux内å˜ç®¡ç†æ˜¯ä¸€ä¸ªå…·æœ‰è®¸å¤šå¯é…置设置的å¤æ‚系统, 且这些è .. _man 5 proc: http://man7.org/linux/man-pages/man5/proc.5.html Linux内å˜ç®¡ç†æœ‰å®ƒè‡ªå·±çš„术è¯ï¼Œå¦‚æžœä½ è¿˜ä¸ç†Ÿæ‚‰å®ƒï¼Œè¯·è€ƒè™‘阅读下é¢å‚考： -:ref:`Documentation/admin-guide/mm/concepts.rst <mm_concepts>`. +Documentation/admin-guide/mm/concepts.rst. 在æ¤ç›®å½•ä¸‹ï¼Œæˆ‘们详细æ述了如何与Linux内å˜ç®¡ç†ä¸çš„å„ç§æœºåˆ¶äº¤äº’。 diff --git a/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst b/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst index 4829156ef1ae..0029c4fd2201 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst @@ -146,3 +146,53 @@ stable_node_dups 比值 ``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_CN/core-api/kernel-api.rst b/Documentation/translations/zh_CN/core-api/kernel-api.rst index c22662679065..a4b373c48c0c 100644 --- a/Documentation/translations/zh_CN/core-api/kernel-api.rst +++ b/Documentation/translations/zh_CN/core-api/kernel-api.rst @@ -48,6 +48,8 @@ lib/string_helpers.c 该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: +include/linux/fortify-string.h + lib/string.c include/linux/string.h @@ -119,6 +121,12 @@ include/linux/textsearch.h Linuxä¸çš„CRC和数å¦å‡½æ•° ====================== +算术溢出检查 +------------ + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +include/linux/overflow.h CRC函数 ------- @@ -166,8 +174,6 @@ include/asm-generic/div64.h include/linux/math64.h -lib/math/div64.c - lib/math/gcd.c UUID/GUID diff --git a/Documentation/translations/zh_CN/core-api/mm-api.rst b/Documentation/translations/zh_CN/core-api/mm-api.rst index a732b0eebf16..113359bdb7be 100644 --- a/Documentation/translations/zh_CN/core-api/mm-api.rst +++ b/Documentation/translations/zh_CN/core-api/mm-api.rst @@ -37,7 +37,7 @@ mm/gup.c 该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: -include/linux/gfp.h +include/linux/gfp_types.h Slabç¼“å˜ ======== diff --git a/Documentation/translations/zh_CN/core-api/workqueue.rst b/Documentation/translations/zh_CN/core-api/workqueue.rst index f6567cf9d3fb..6c1b5ec31d75 100644 --- a/Documentation/translations/zh_CN/core-api/workqueue.rst +++ b/Documentation/translations/zh_CN/core-api/workqueue.rst @@ -313,8 +313,8 @@ And with cmwq with ``@max_active`` >= 3, :: 第一个å¯ä»¥ç”¨è¿½è¸ªçš„æ–¹å¼è¿›è¡Œè·Ÿè¸ª: :: - $ echo workqueue:workqueue_queue_work > /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace_pipe > out.txt + $ echo workqueue:workqueue_queue_work > /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace_pipe > out.txt (wait a few secs) 如果有什么东西在工作队列上忙ç€åšå¾ªçŽ¯ï¼Œå®ƒå°±ä¼šä¸»å¯¼è¾“出，å¯ä»¥ç”¨å·¥ä½œé¡¹å‡½æ•°ç¡®å®šè¿è§„者。 diff --git a/Documentation/translations/zh_CN/dev-tools/kasan.rst b/Documentation/translations/zh_CN/dev-tools/kasan.rst index fe76cbe77ad6..05ef904dbcfb 100644 --- a/Documentation/translations/zh_CN/dev-tools/kasan.rst +++ b/Documentation/translations/zh_CN/dev-tools/kasan.rst @@ -90,6 +90,47 @@ KASANåªæ”¯æŒSLUB。 ``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`` ）。 + 错误报告 ~~~~~~~~ @@ -194,39 +235,6 @@ slab对象的æ述以åŠå…³äºŽè®¿é—®çš„内å˜é¡µçš„ä¿¡æ¯ã€‚ 通用KASANè¿˜æŠ¥å‘Šä¸¤ä¸ªè¾…åŠ©è°ƒç”¨å †æ ˆè·Ÿè¸ªã€‚è¿™äº›å †æ ˆè·Ÿè¸ªæŒ‡å‘代ç ä¸ä¸Žå¯¹è±¡äº¤äº’但ä¸ç›´æŽ¥ å‡ºçŽ°åœ¨é”™è¯¯è®¿é—®å †æ ˆè·Ÿè¸ªä¸çš„ä½ç½®ã€‚ç›®å‰ï¼Œè¿™åŒ…括 call_rcu() 和排队的工作队列。 -å¯åŠ¨å‚æ•° -~~~~~~~~ - -KASANå—通用 ``panic_on_warn`` 命令行å‚æ•°çš„å½±å“。å¯ç”¨è¯¥åŠŸèƒ½åŽï¼ŒKASAN在打å°é”™è¯¯ -报告åŽä¼šå¼•èµ·å†…æ ¸æ慌。 - -默认情况下，KASANåªä¸ºç¬¬ä¸€æ¬¡æ— 效内å˜è®¿é—®æ‰“å°é”™è¯¯æŠ¥å‘Šã€‚使用 ``kasan_multi_shot`` ， -KASAN会针对æ¯ä¸ªæ— 效访问打å°æŠ¥å‘Šã€‚这有效地ç¦ç”¨äº†KASAN报告的 ``panic_on_warn`` 。 - -å¦å¤–，独立于 ``panic_on_warn`` , ``kasan.fault=`` 引导å‚æ•°å¯ä»¥ç”¨æ¥æŽ§åˆ¶æ慌和报 -告行为: - -- ``kasan.fault=report`` 或 ``=panic`` 控制是åªæ‰“å°KASAN报告还是åŒæ—¶ä½¿å†…æ ¸ææ…Œ - (默认: ``report`` )。å³ä½¿å¯ç”¨äº† ``kasan_multi_shot`` ，也会å‘ç”Ÿå†…æ ¸æ慌。 - -åŸºäºŽç¡¬ä»¶æ ‡ç¾çš„KASAN模å¼ï¼ˆè¯·å‚阅下é¢æœ‰å…³å„ç§æ¨¡å¼çš„部分）旨在在生产ä¸ç”¨ä½œå®‰å…¨ç¼“解 -æŽªæ–½ã€‚å› æ¤ï¼Œå®ƒæ”¯æŒå…许ç¦ç”¨KASANæˆ–æŽ§åˆ¶å…¶åŠŸèƒ½çš„é™„åŠ å¼•å¯¼å‚数。 - -- ``kasan=off`` 或 ``=on`` 控制KASAN是å¦å¯ç”¨ (默认: ``on`` )。 - -- ``kasan.mode=sync`` 〠``=async`` 或 ``=asymm`` 控制KASAN是å¦é…ç½® - 为åŒæ¥æˆ–异æ¥æ‰§è¡Œæ¨¡å¼(默认:``sync`` )。 - åŒæ¥æ¨¡å¼ï¼šå½“æ ‡ç¾æ£€æŸ¥é”™è¯¯å‘生时，立å³æ£€æµ‹åˆ°é”™è¯¯è®¿é—®ã€‚ - 异æ¥æ¨¡å¼ï¼šå»¶è¿Ÿé”™è¯¯è®¿é—®æ£€æµ‹ã€‚å½“æ ‡ç¾æ£€æŸ¥é”™è¯¯å‘生时，信æ¯å˜å‚¨åœ¨ç¡¬ä»¶ä¸ï¼ˆåœ¨arm64çš„ - TFSR_EL1寄å˜å™¨ä¸ï¼‰ã€‚å†…æ ¸ä¼šå®šæœŸæ£€æŸ¥ç¡¬ä»¶ï¼Œå¹¶ä¸”ä»…åœ¨è¿™äº›æ£€æŸ¥æœŸé—´æŠ¥å‘Šæ ‡ç¾é”™è¯¯ã€‚ - éžå¯¹ç§°æ¨¡å¼ï¼šè¯»å–æ—¶åŒæ¥æ£€æµ‹ä¸è‰¯è®¿é—®ï¼Œå†™å…¥æ—¶å¼‚æ¥æ£€æµ‹ã€‚ - -- ``kasan.vmalloc=off`` 或 ``=on`` ç¦ç”¨æˆ–å¯ç”¨vmalloc分é…çš„æ ‡è®°ï¼ˆé»˜è®¤ï¼š``on`` ）。 - -- ``kasan.stacktrace=off`` 或 ``=on`` ç¦ç”¨æˆ–å¯ç”¨allocå’Œfreeå †æ ˆè·Ÿè¸ªæ”¶é›† - (默认: ``on`` )。 - - 实施细则 -------- diff --git a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst index d6f2c65ed511..af65e7e93c02 100644 --- a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst +++ b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst @@ -132,3 +132,30 @@ Documentation/dev-tools/kcov.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_CN/driver-api/gpio/legacy.rst b/Documentation/translations/zh_CN/driver-api/gpio/legacy.rst index 6399521d0548..74fa473bb504 100644 --- a/Documentation/translations/zh_CN/driver-api/gpio/legacy.rst +++ b/Documentation/translations/zh_CN/driver-api/gpio/legacy.rst @@ -358,9 +358,6 @@ GPIO ç¼–å·æ˜¯æ— 符å·æ•´æ•°;IRQ ç¼–å·ä¹Ÿæ˜¯ã€‚这些构æˆäº†ä¸¤ä¸ªé€»è¾‘上ä /* æ˜ å°„ GPIO ç¼–å·åˆ° IRQ ç¼–å· */ int gpio_to_irq(unsigned gpio); - /* æ˜ å°„ IRQ ç¼–å·åˆ° GPIO ç¼–å· (å°½é‡é¿å…使用) */ - int irq_to_gpio(unsigned irq); - 它们的返回值为对应命å空间的相关编å·ï¼Œæˆ–是负的错误代ç (å¦‚æžœæ— æ³•æ˜ å°„)。 (例如,æŸäº› GPIO æ— æ³•åšä¸º IRQ 使用。)以下的编å·é”™è¯¯æ˜¯æœªç»æ£€æµ‹çš„:使用一个 未通过 gpio_direction_input()é…置为输入的 GPIO ç¼–å·ï¼Œæˆ–者使用一个 @@ -373,10 +370,6 @@ gpio_to_irq()返回的éžé”™è¯¯å€¼å¯ä»¥ä¼ 递给 request_irq()或者 free_irq() 触å‘选项是 IRQ 接å£çš„一部分，如 IRQF_TRIGGER_FALLING，系统唤醒能力 也是如æ¤ã€‚ -irq_to_gpio()返回的éžé”™è¯¯å€¼å¤§å¤šæ•°é€šå¸¸å¯ä»¥è¢« gpio_get_value()所使用， -比如在 IRQ 是沿触å‘æ—¶åˆå§‹åŒ–或更新驱动状æ€ã€‚注æ„æŸäº›å¹³å°ä¸æ”¯æŒåæ˜ å°„,所以 -ä½ åº”è¯¥å°½é‡é¿å…使用它。 - 模拟开æ¼ä¿¡å· ------------ @@ -672,10 +665,6 @@ GPIO 控制器的路径类似 /sys/class/gpio/gpiochip42/ (对于从#42 GPIO /* gpio_export()的逆æ“作 */ void gpio_unexport(); - /* 创建一个 sysfs 连接到已导出的 GPIO 节点 */ - int gpio_export_link(struct device *dev, const char *name, - unsigned gpio) - åœ¨ä¸€ä¸ªå†…æ ¸é©±åŠ¨ç”³è¯·ä¸€ä¸ª GPIO 之åŽï¼Œå®ƒå¯ä»¥é€šè¿‡ gpio_export()使其在 sysfs 接å£ä¸å¯è§ã€‚该驱动å¯ä»¥æŽ§åˆ¶ä¿¡å·æ–¹å‘是å¦å¯ä¿®æ”¹ã€‚这有助于防æ¢ç”¨æˆ·ç©ºé—´ä»£ç æ— æ„é—´ ç ´åé‡è¦çš„系统状æ€ã€‚ @@ -683,10 +672,6 @@ GPIO 控制器的路径类似 /sys/class/gpio/gpiochip42/ (对于从#42 GPIO 这个明确的导出有助于(通过使æŸäº›å®žéªŒæ›´å®¹æ˜“æ¥)调试，也å¯ä»¥æ供一个始终å˜åœ¨çš„接å£ï¼Œ 与文档é…åˆä½œä¸ºæ¿çº§æ”¯æŒåŒ…的一部分。 -在 GPIO 被导出之åŽï¼Œgpio_export_link()å…许在 sysfs 文件系统的任何地方 -创建一个到这个 GPIO sysfs 节点的符å·é“¾æŽ¥ã€‚è¿™æ ·é©±åŠ¨å°±å¯ä»¥é€šè¿‡ä¸€ä¸ªæ述性的 -åå—，在 sysfs ä¸ä»–们所拥有的设备下æ供一个(到这个 GPIO sysfs 节点的)接å£ã€‚ - APIå‚考 ======= diff --git a/Documentation/translations/zh_CN/glossary.rst b/Documentation/translations/zh_CN/glossary.rst new file mode 100644 index 000000000000..24f094df97cd --- /dev/null +++ b/Documentation/translations/zh_CN/glossary.rst @@ -0,0 +1,36 @@ +.. SPDX-License-Identifier: GPL-2.0 + +术è¯è¡¨ +====== + +è¿™ä¸æ˜¯ä¸€ä¸ªå®Œå–„的术è¯è¡¨ï¼Œæˆ‘们åªæ˜¯å°†æœ‰äº‰è®®çš„和陌生的翻译è¯æ±‡è®°å½•äºŽæ¤ï¼Œ +å®ƒçš„ç¯‡å¹…åº”è¯¥æ ¹æ®å†…æ ¸æ–‡æ¡£ç¿»è¯‘çš„éœ€æ±‚è€Œå¢žåŠ ã€‚æ–°è¯æ¡æœ€å¥½éšç¿»è¯‘è¡¥ä¸ä¸€èµ· +æ交，且仅在以下情况下收录新è¯æ¡ï¼š + + - 在翻译过程ä¸é‡åˆ°é™Œç”Ÿè¯æ±‡ï¼Œä¸”å°šæ— ç¿»è¯‘å…ˆä¾‹çš„ï¼› + - 在审阅过程ä¸ï¼Œé’ˆå¯¹æŸè¯æ¡å‡ºçŽ°äº†ä¸åŒçš„翻译æ„è§ï¼› + - 使用频率ä¸é«˜çš„è¯æ¡å’Œé¦–å—æ¯ç¼©å†™ç±»åž‹çš„è¯æ¡ï¼› + - å·²ç»å˜åœ¨ä¸”有æ§ä¹‰çš„è¯æ¡ç¿»è¯‘。 + + +* atomic: 原å的，一般指ä¸å¯ä¸æ–çš„æžå°çš„临界区æ“作。 +* DVFS: 动æ€ç”µåŽ‹é¢‘率å‡é™ã€‚（Dynamic Voltage and Frequency Scaling） +* EAS: 能耗感知调度。（Energy Aware Scheduling） +* flush: 刷新，一般指对cache的冲洗æ“作。 +* fork: 创建, 通常指父进程创建å进程。 +* futex: 快速用户互斥é”。（fast user mutex） +* guest halt polling: 客户机åœæœºè½®è¯¢æœºåˆ¶ã€‚ +* HugePage: 巨页。 +* hypervisor: 虚拟机超级管ç†å™¨ã€‚ +* memory barriers: 内å˜å±éšœã€‚ +* MIPS: æ¯ç§’百万指令。（Millions of Instructions Per Second）,注æ„与mips指令集区分开。 +* mutex: 互斥é”。 +* NUMA: éžç»Ÿä¸€å†…å˜è®¿é—®ã€‚ +* OpenCAPI: å¼€æ”¾ç›¸å¹²åŠ é€Ÿå™¨å¤„ç†å™¨æŽ¥å£ã€‚（Open Coherent Accelerator Processor Interface） +* OPP: æ“作性能值。 +* overhead: 开销，一般指需è¦æ¶ˆè€—的计算机资æºã€‚ +* PELT: 实体负载跟踪。（Per-Entity Load Tracking） +* sched domain: 调度域。 +* semaphores: ä¿¡å·é‡ã€‚ +* spinlock: 自旋é”。 +* watermark: æ°´ä½ï¼Œä¸€èˆ¬æŒ‡é¡µè¡¨çš„消耗水平。 diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index 3660a3451c86..7c3216845b71 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -133,6 +133,15 @@ TODOList: staging/index +术è¯è¡¨ +------ + +.. toctree:: + :maxdepth: 1 + + glossary + + ç´¢å¼•å’Œè¡¨æ ¼ ---------- diff --git a/Documentation/translations/zh_CN/mm/highmem.rst b/Documentation/translations/zh_CN/mm/highmem.rst index f74800a6d9a7..2c0ee0cbf5c4 100644 --- a/Documentation/translations/zh_CN/mm/highmem.rst +++ b/Documentation/translations/zh_CN/mm/highmem.rst @@ -57,15 +57,29 @@ 在å¯è¡Œçš„情况下，这个函数应该比其他所有的函数优先使用。 - è¿™äº›æ˜ å°„æ˜¯çº¿ç¨‹æœ¬åœ°å’ŒCPU本地的，这æ„味ç€æ˜ å°„åªèƒ½ä»Žè¿™ä¸ªçº¿ç¨‹ä¸è®¿é—®ï¼Œå¹¶ä¸”å½“æ˜ å°„å¤„äºŽæ´»åŠ¨çŠ¶ - æ€æ—¶ï¼Œè¯¥çº¿ç¨‹ä¸ŽCPU绑定。å³ä½¿çº¿ç¨‹è¢«æŠ¢å äº†ï¼ˆå› ä¸ºæŠ¢å 永远ä¸ä¼šè¢«å‡½æ•°ç¦ç”¨ï¼‰ï¼ŒCPU也ä¸èƒ½é€šè¿‡ - CPU-hotplug从系统ä¸æ‹”å‡ºï¼Œç›´åˆ°æ˜ å°„è¢«å¤„ç†æŽ‰ã€‚ + è¿™äº›æ˜ å°„æ˜¯çº¿ç¨‹æœ¬åœ°å’ŒCPU本地的，这æ„味ç€æ˜ å°„åªèƒ½ä»Žè¿™ä¸ªçº¿ç¨‹ä¸è®¿é—®ï¼Œå¹¶ä¸”å½“æ˜ å°„å¤„äºŽæ´»è·ƒçŠ¶ + æ€æ—¶ï¼Œçº¿ç¨‹è¢«ç»‘定到CPU上。尽管这个函数从æ¥æ²¡æœ‰ç¦ç”¨è¿‡æŠ¢å ï¼Œä½†åœ¨æ˜ å°„è¢«å¤„ç†ä¹‹å‰ï¼ŒCPUä¸èƒ½ + 通过CPU-hotplug从系统ä¸æ‹”出。 在本地的kmap区域ä¸é‡‡å–pagefaults是有效的，除éžèŽ·å–æœ¬åœ°æ˜ å°„çš„ä¸Šä¸‹æ–‡ç”±äºŽå…¶ä»–åŽŸå› ä¸å…许 è¿™æ ·åšã€‚ + 如å‰æ‰€è¿°ï¼Œç¼ºé¡µå¼‚常和抢å 从未被ç¦ç”¨ã€‚没有必è¦ç¦ç”¨æŠ¢å ï¼Œå› ä¸ºå½“ä¸Šä¸‹æ–‡åˆ‡æ¢åˆ°ä¸€ä¸ªä¸åŒçš„任务 + æ—¶ï¼Œç¦»å¼€çš„ä»»åŠ¡çš„æ˜ å°„è¢«ä¿å˜ï¼Œè€Œè¿›å…¥çš„ä»»åŠ¡çš„æ˜ å°„è¢«æ¢å¤ã€‚ + kmap_local_page()总是返回一个有效的虚拟地å€ï¼Œå¹¶ä¸”å‡å®škunmap_local()ä¸ä¼šå¤±è´¥ã€‚ + 在CONFIG_HIGHMEM=nçš„å†…æ ¸ä¸ï¼Œå¯¹äºŽä½Žå†…å˜é¡µï¼Œå®ƒè¿”å›žç›´æŽ¥æ˜ å°„çš„è™šæ‹Ÿåœ°å€ã€‚åªæœ‰çœŸæ£çš„高内 + å˜é¡µé¢æ‰ä¼šè¢«ä¸´æ—¶æ˜ å°„ã€‚å› æ¤ï¼Œç”¨æˆ·å¯ä»¥ä¸ºé‚£äº›å·²çŸ¥ä¸æ˜¯æ¥è‡ªZONE_HIGHMEM的页é¢è°ƒç”¨æ™®é€šçš„ + page_address()。然而，使用kmap_local_page() / kunmap_local()总是安全的。 + + 虽然它比kmap()快得多，但在高内å˜çš„情况下，它对指针的有效性有é™åˆ¶ã€‚与kmap()æ˜ å°„ç›¸å， + æœ¬åœ°æ˜ å°„åªåœ¨è°ƒç”¨è€…的上下文ä¸æœ‰æ•ˆï¼Œä¸èƒ½ä¼ 递给其他上下文。这æ„味ç€ç”¨æˆ·å¿…é¡»ç»å¯¹ä¿è¯è¿”回 + 地å€çš„使用åªé™äºŽæ˜ 射它的线程。 + + 大多数代ç å¯ä»¥è¢«è®¾è®¡æˆä½¿ç”¨çº¿ç¨‹æœ¬åœ°æ˜ å°„ã€‚å› æ¤ï¼Œç”¨æˆ·åœ¨è®¾è®¡ä»–们的代ç 时，应该尽é‡é¿å…使用 + kmap()，将页é¢æ˜ 射到将被使用的åŒä¸€çº¿ç¨‹ä¸ï¼Œå¹¶ä¼˜å…ˆä½¿ç”¨kmap_local_page()。 + 嵌套kmap_local_page()å’Œkmap_atomic()æ˜ å°„åœ¨ä¸€å®šç¨‹åº¦ä¸Šæ˜¯å…许的（最多到KMAP_TYPE_NR）， ä½†æ˜¯å®ƒä»¬çš„è°ƒç”¨å¿…é¡»ä¸¥æ ¼æŽ’åºï¼Œå› ä¸ºæ˜ å°„çš„å®žçŽ°æ˜¯åŸºäºŽå †æ ˆçš„ã€‚å…³äºŽå¦‚ä½•ç®¡ç†åµŒå¥—æ˜ å°„çš„ç»†èŠ‚ï¼Œ 请å‚è§kmap_local_page() kdocs（包å«åœ¨ "函数 "部分）。 diff --git a/Documentation/translations/zh_CN/mm/hmm.rst b/Documentation/translations/zh_CN/mm/hmm.rst index 5024a8a15516..babbbe756c0f 100644 --- a/Documentation/translations/zh_CN/mm/hmm.rst +++ b/Documentation/translations/zh_CN/mm/hmm.rst @@ -248,7 +248,7 @@ migrate_vma_finalize() 函数旨在使驱动程åºæ›´æ˜“于编写并集ä¸è·¨é©± 还有devm_request_free_mem_region(), devm_memremap_pages(), devm_memunmap_pages() å’Œ devm_release_mem_region() 当资æºå¯ä»¥ç»‘定到 ``struct device``. -整体è¿ç§»æ¥éª¤ç±»ä¼¼äºŽåœ¨ç³»ç»Ÿå†…å˜ä¸è¿ç§» NUMA 页é¢(see :ref:`Page migration <page_migration>`) ， +整体è¿ç§»æ¥éª¤ç±»ä¼¼äºŽåœ¨ç³»ç»Ÿå†…å˜ä¸è¿ç§» NUMA 页é¢(see Documentation/mm/page_migration.rst) ， 但这些æ¥éª¤åˆ†ä¸ºè®¾å¤‡é©±åŠ¨ç¨‹åºç‰¹å®šä»£ç 和共享公共代ç : 1. ``mmap_read_lock()`` diff --git a/Documentation/translations/zh_CN/mm/hugetlbfs_reserv.rst b/Documentation/translations/zh_CN/mm/hugetlbfs_reserv.rst index 752e5696cd47..c1fa35315d8b 100644 --- a/Documentation/translations/zh_CN/mm/hugetlbfs_reserv.rst +++ b/Documentation/translations/zh_CN/mm/hugetlbfs_reserv.rst @@ -15,7 +15,7 @@ Hugetlbfs 预留 概述 ==== -:ref:`hugetlbpage` ä¸æ述的巨页通常是预先分é…给应用程åºä½¿ç”¨çš„。如果VMA指 +Documentation/mm/hugetlbpage.rst ä¸æ述的巨页通常是预先分é…给应用程åºä½¿ç”¨çš„。如果VMA指 示è¦ä½¿ç”¨å·¨é¡µï¼Œè¿™äº›å·¨é¡µä¼šåœ¨ç¼ºé¡µå¼‚常时被实例化到任务的地å€ç©ºé—´ã€‚如果在缺页异常 时没有巨页å˜åœ¨ï¼Œä»»åŠ¡å°±ä¼šè¢«å‘é€ä¸€ä¸ªSIGBUS，并ç»å¸¸ä¸é«˜å…´åœ°æ»åŽ»ã€‚åœ¨åŠ å…¥å·¨é¡µæ”¯ æŒåŽä¸ä¹…，人们决定，在mmap()时检测巨页的çŸç¼ºæƒ…况会更好。这个想法是，如果 @@ -142,14 +142,14 @@ HPAGE_RESV_OWNERæ ‡å¿—è¢«è®¾ç½®ï¼Œä»¥è¡¨æ˜Žè¯¥VMA拥有预留。 消耗预留/分é…一个巨页 =========================== -å½“ä¸Žé¢„ç•™ç›¸å…³çš„å·¨é¡µåœ¨ç›¸åº”çš„æ˜ å°„ä¸è¢«åˆ†é…和实例化时，预留就被消耗了。该分é…是在函数alloc_huge_page() +å½“ä¸Žé¢„ç•™ç›¸å…³çš„å·¨é¡µåœ¨ç›¸åº”çš„æ˜ å°„ä¸è¢«åˆ†é…和实例化时，预留就被消耗了。该分é…是在函数alloc_hugetlb_folio() ä¸è¿›è¡Œçš„:: - struct page *alloc_huge_page(struct vm_area_struct *vma, + struct folio *alloc_hugetlb_folio(struct vm_area_struct *vma, unsigned long addr, int avoid_reserve) -alloc_huge_pageè¢«ä¼ é€’ç»™ä¸€ä¸ªVMA指针和一个虚拟地å€ï¼Œå› æ¤å®ƒå¯ä»¥æŸ¥é˜…é¢„ç•™æ˜ å°„ä»¥ç¡®å®šæ˜¯å¦å˜åœ¨é¢„留。 -æ¤å¤–，alloc_huge_page需è¦ä¸€ä¸ªå‚æ•°avoid_reserve，该å‚数表示å³ä½¿çœ‹èµ·æ¥å·²ç»ä¸ºæŒ‡å®šçš„地å€é¢„留了 +alloc_hugetlb_folioè¢«ä¼ é€’ç»™ä¸€ä¸ªVMA指针和一个虚拟地å€ï¼Œå› æ¤å®ƒå¯ä»¥æŸ¥é˜…é¢„ç•™æ˜ å°„ä»¥ç¡®å®šæ˜¯å¦å˜åœ¨é¢„留。 +æ¤å¤–，alloc_hugetlb_folio需è¦ä¸€ä¸ªå‚æ•°avoid_reserve，该å‚数表示å³ä½¿çœ‹èµ·æ¥å·²ç»ä¸ºæŒ‡å®šçš„地å€é¢„留了 预留，也ä¸åº”该使用预留。avoid_reserveå‚数最常被用于写时拷è´å’Œé¡µé¢è¿ç§»çš„情况下，å³çŽ°æœ‰é¡µé¢çš„é¢ å¤–æ‹·è´è¢«åˆ†é…。 @@ -162,7 +162,7 @@ vma_needs_reservation()返回的值通常为0或1。如果该地å€å˜åœ¨é¢„ç•™ï 确定预留是å¦å˜åœ¨å¹¶å¯ç”¨äºŽåˆ†é…åŽï¼Œè°ƒç”¨dequeue_huge_page_vma()函数。这个函数需è¦ä¸¤ä¸ªä¸Žé¢„留有关 çš„å‚数： -- avoid_reserveï¼Œè¿™æ˜¯ä¼ é€’ç»™alloc_huge_page()çš„åŒä¸€ä¸ªå€¼/å‚数。 +- avoid_reserveï¼Œè¿™æ˜¯ä¼ é€’ç»™alloc_hugetlb_folio()çš„åŒä¸€ä¸ªå€¼/å‚数。 - chg，尽管这个å‚数的类型是long，但åªæœ‰0或1çš„å€¼è¢«ä¼ é€’ç»™dequeue_huge_page_vma。如果该值为0， 则表明å˜åœ¨é¢„留（关于å¯èƒ½çš„问题，请å‚è§ â€œé¢„ç•™å’Œå†…å˜ç–略†一节）。如果值 为1，则表示ä¸å˜åœ¨é¢„留，如果å¯èƒ½çš„è¯ï¼Œå¿…é¡»ä»Žå…¨å±€ç©ºé—²æ± ä¸å–出该页。 @@ -179,7 +179,7 @@ free_huge_pages的值被递å‡ã€‚å¦‚æžœæœ‰ä¸€ä¸ªä¸Žè¯¥é¡µç›¸å…³çš„é¢„ç•™ï¼Œå°†è¿ çš„å‰©ä½™å·¨é¡µå’Œè¶…é¢åˆ†é…的问题。å³ä½¿åˆ†é…了一个多余的页é¢ï¼Œä¹Ÿä¼šè¿›è¡Œä¸Žä¸Šé¢ä¸€æ ·çš„基于预留的调整: SetPagePrivate(page) å’Œ resv_huge_pages--. -在获得一个新的巨页åŽï¼Œ(page)->private被设置为与该页é¢ç›¸å…³çš„åæ± çš„å€¼ï¼Œå¦‚æžœå®ƒå˜åœ¨çš„è¯ã€‚当页 +在获得一个新的巨页åŽï¼Œ(folio)->_hugetlb_subpool被设置为与该页é¢ç›¸å…³çš„åæ± çš„å€¼ï¼Œå¦‚æžœå®ƒå˜åœ¨çš„è¯ã€‚当页 é¢è¢«é‡Šæ”¾æ—¶ï¼Œè¿™å°†è¢«ç”¨äºŽåæ± çš„è®¡æ•°ã€‚ 然åŽè°ƒç”¨å‡½æ•°vma_commit_reservation()ï¼Œæ ¹æ®é¢„ç•™çš„æ¶ˆè€—æƒ…å†µè°ƒæ•´é¢„ç•™æ˜ å°„ã€‚ä¸€èˆ¬æ¥è¯´ï¼Œè¿™æ¶‰åŠ @@ -199,7 +199,7 @@ SetPagePrivate(page)å’Œresv_huge_pages-。 å·²ç»å˜åœ¨ï¼Œæ‰€ä»¥ä¸åšä»»ä½•æ”¹å˜ã€‚ç„¶è€Œï¼Œå¦‚æžœå…±äº«æ˜ å°„ä¸æ²¡æœ‰é¢„留，或者这是一个ç§æœ‰æ˜ 射，则必须创建 一个新的æ¡ç›®ã€‚ -在alloc_huge_page()开始调用vma_needs_reservation()和页é¢åˆ†é…åŽè°ƒç”¨ +在alloc_hugetlb_folio()开始调用vma_needs_reservation()和页é¢åˆ†é…åŽè°ƒç”¨ vma_commit_reservation()ä¹‹é—´ï¼Œé¢„ç•™æ˜ å°„æœ‰å¯èƒ½è¢«æ”¹å˜ã€‚如果hugetlb_reserve_pages在共 äº«æ˜ å°„ä¸ä¸ºåŒä¸€é¡µé¢è¢«è°ƒç”¨ï¼Œè¿™å°†æ˜¯å¯èƒ½çš„。在这ç§æƒ…况下，预留计数和åæ± ç©ºé—²é¡µè®¡æ•°ä¼šæœ‰ä¸€ä¸ªå差。 è¿™ç§ç½•è§çš„情况å¯ä»¥é€šè¿‡æ¯”较vma_needs_reservationå’Œvma_commit_reservationçš„è¿”å›žå€¼æ¥ diff --git a/Documentation/translations/zh_CN/mm/numa.rst b/Documentation/translations/zh_CN/mm/numa.rst index b15cfeeb6dfb..61fad89272fa 100644 --- a/Documentation/translations/zh_CN/mm/numa.rst +++ b/Documentation/translations/zh_CN/mm/numa.rst @@ -76,7 +76,7 @@ Linux将系统的硬件资æºåˆ’分为多个软件抽象，称为“节点â€ã€‚ 系统管ç†å‘˜å’Œåº”用程åºè®¾è®¡è€…å¯ä»¥ä½¿ç”¨å„ç§CPU亲和命令行接å£ï¼Œå¦‚taskset(1)å’Œnumactl(1)，以åŠç¨‹ åºæŽ¥å£ï¼Œå¦‚sched_setaffinity(2)，æ¥é™åˆ¶ä»»åŠ¡çš„è¿ç§»ï¼Œä»¥æ”¹å–„NUMA定ä½ã€‚æ¤å¤–，人们å¯ä»¥ä½¿ç”¨ Linux NUMA内å˜ç–ç•¥ä¿®æ”¹å†…æ ¸çš„é»˜è®¤æœ¬åœ°åˆ†é…行为。 [è§ -:ref:`Documentation/admin-guide/mm/numa_memory_policy.rst <numa_memory_policy>`]. +Documentation/admin-guide/mm/numa_memory_policy.rst]. 系统管ç†å‘˜å¯ä»¥ä½¿ç”¨æŽ§åˆ¶ç»„å’ŒCPUsetsé™åˆ¶éžç‰¹æƒç”¨æˆ·åœ¨è°ƒåº¦æˆ–NUMA命令和功能ä¸å¯ä»¥æŒ‡å®šçš„CPU和节点 的内å˜ã€‚ [è§ Documentation/admin-guide/cgroup-v1/cpusets.rst] diff --git a/Documentation/translations/zh_CN/mm/page_owner.rst b/Documentation/translations/zh_CN/mm/page_owner.rst index 21a6a0837d42..b72a972271d9 100644 --- a/Documentation/translations/zh_CN/mm/page_owner.rst +++ b/Documentation/translations/zh_CN/mm/page_owner.rst @@ -34,20 +34,9 @@ page owner在默认情况下是ç¦ç”¨çš„ã€‚æ‰€ä»¥ï¼Œå¦‚æžœä½ æƒ³ä½¿ç”¨å®ƒï¼Œä½ é ä¸€æ ·è¿›è¡Œã€‚è¿™ä¸¤ä¸ªä¸å¯èƒ½çš„分支应该ä¸ä¼šå½±å“到分é…的性能，特别是在é™æ€é”®è·³è½¬æ ‡ç¾ä¿®è¡¥ 功能å¯ç”¨çš„æƒ…å†µä¸‹ã€‚ä»¥ä¸‹æ˜¯ç”±äºŽè¿™ä¸ªåŠŸèƒ½è€Œå¯¼è‡´çš„å†…æ ¸ä»£ç 大å°çš„å˜åŒ–。 -- 没有page owner:: - - text data bss dec hex filename - 48392 2333 644 51369 c8a9 mm/page_alloc.o - -- 有page owner:: - - text data bss dec hex filename - 48800 2445 644 51889 cab1 mm/page_alloc.o - 6662 108 29 6799 1a8f mm/page_owner.o - 1025 8 8 1041 411 mm/page_ext.o - -è™½ç„¶æ€»å…±å¢žåŠ äº†8KB的代ç ，但page_alloc.oå¢žåŠ äº†520å—节，其ä¸ä¸åˆ°ä¸€åŠæ˜¯åœ¨hotpath -ä¸ã€‚构建带有page ownerçš„å†…æ ¸ï¼Œå¹¶åœ¨éœ€è¦æ—¶æ‰“å¼€å®ƒï¼Œå°†æ˜¯è°ƒè¯•å†…æ ¸å†…å˜é—®é¢˜çš„最佳选择。 +尽管å¯ç”¨page ownerä¼šä½¿å†…æ ¸çš„å¤§å°å¢žåŠ å‡ åƒå—节，但这些代ç 大部分都在页é¢åˆ†é…器和 +çƒè·¯å¾„之外。构建带有page ownerçš„å†…æ ¸ï¼Œå¹¶åœ¨éœ€è¦æ—¶æ‰“å¼€å®ƒï¼Œå°†æ˜¯è°ƒè¯•å†…æ ¸å†…å˜é—®é¢˜çš„ +最佳选择。 有一个问题是由实现细节引起的。页所有者将信æ¯å˜å‚¨åˆ°struct page扩展的内å˜ä¸ã€‚è¿™ 个内å˜çš„åˆå§‹åŒ–时间比稀ç–内å˜ç³»ç»Ÿä¸çš„页é¢åˆ†é…器å¯åŠ¨çš„时间è¦æ™šä¸€äº›ï¼Œæ‰€ä»¥ï¼Œåœ¨åˆå§‹åŒ– @@ -62,7 +51,7 @@ page owner在默认情况下是ç¦ç”¨çš„ã€‚æ‰€ä»¥ï¼Œå¦‚æžœä½ æƒ³ä½¿ç”¨å®ƒï¼Œä½ é 1) 构建用户空间的帮助:: - cd tools/vm + cd tools/mm make page_owner_sort 2) å¯ç”¨page owner: æ·»åŠ "page_owner=on" 到 boot cmdline. diff --git a/Documentation/translations/zh_CN/power/energy-model.rst b/Documentation/translations/zh_CN/power/energy-model.rst index c7da1b6aefee..48849919d8aa 100644 --- a/Documentation/translations/zh_CN/power/energy-model.rst +++ b/Documentation/translations/zh_CN/power/energy-model.rst @@ -23,15 +23,15 @@ 实现支æŒï¼ŒEMæ¡†æž¶ä½œä¸ºä¸€ä¸ªæŠ½è±¡å±‚ä»‹å…¥ï¼Œå®ƒåœ¨å†…æ ¸ä¸å¯¹åŠŸçŽ‡æˆæœ¬è¡¨çš„æ ¼å¼è¿›è¡Œæ ‡å‡†åŒ–， å› æ¤èƒ½å¤Ÿé¿å…多余的工作。 -功率值å¯ä»¥ç”¨æ¯«ç“¦æˆ–“抽象刻度â€è¡¨ç¤ºã€‚多个å系统å¯èƒ½ä½¿ç”¨EM，由系统集æˆå•†æ¥æ£€æŸ¥ +功率值å¯ä»¥ç”¨å¾®ç“¦æˆ–“抽象刻度â€è¡¨ç¤ºã€‚多个å系统å¯èƒ½ä½¿ç”¨EM，由系统集æˆå•†æ¥æ£€æŸ¥ 功率值刻度类型的è¦æ±‚是å¦æ»¡è¶³ã€‚å¯ä»¥åœ¨èƒ½é‡æ„ŸçŸ¥è°ƒåº¦å™¨çš„文档ä¸æ‰¾åˆ°ä¸€ä¸ªä¾‹å Documentation/scheduler/sched-energy.rst。对于一些å系统，比如çƒèƒ½æˆ– powercap，用“抽象刻度â€æ述功率值å¯èƒ½ä¼šå¯¼è‡´é—®é¢˜ã€‚这些å系统对过去使用的功率的 -ä¼°ç®—å€¼æ›´æ„Ÿå…´è¶£ï¼Œå› æ¤å¯èƒ½éœ€è¦çœŸå®žçš„毫瓦。这些è¦æ±‚的一个例åå¯ä»¥åœ¨æ™ºèƒ½åŠŸçŽ‡åˆ†é… +ä¼°ç®—å€¼æ›´æ„Ÿå…´è¶£ï¼Œå› æ¤å¯èƒ½éœ€è¦çœŸå®žçš„微瓦。这些è¦æ±‚的一个例åå¯ä»¥åœ¨æ™ºèƒ½åŠŸçŽ‡åˆ†é… Documentation/driver-api/thermal/power_allocator.rst文档ä¸æ‰¾åˆ°ã€‚ å†…æ ¸å系统å¯èƒ½ï¼ˆåŸºäºŽEMå†…éƒ¨æ ‡å¿—ä½ï¼‰å®žçŽ°äº†å¯¹EM注册设备是å¦å…·æœ‰ä¸ä¸€è‡´åˆ»åº¦çš„自动 -检查。è¦è®°ä½çš„é‡è¦äº‹æƒ…是，当功率值以“抽象刻度â€è¡¨ç¤ºæ—¶ï¼Œä»Žä¸æŽ¨å¯¼ä»¥æ¯«ç„¦è€³ä¸ºå•ä½ +检查。è¦è®°ä½çš„é‡è¦äº‹æƒ…是，当功率值以“抽象刻度â€è¡¨ç¤ºæ—¶ï¼Œä»Žä¸æŽ¨å¯¼ä»¥å¾®ç„¦è€³ä¸ºå•ä½ 的真实能é‡æ¶ˆè€—是ä¸å¯èƒ½çš„。 下图æ述了一个驱动的例å（这里是针对Arm的，但该方法适用于任何体系结构），它 @@ -89,20 +89,40 @@ Documentation/driver-api/thermal/power_allocator.rst文档ä¸æ‰¾åˆ°ã€‚ 驱动程åºåº”通过以下API将性能域注册到EM框架ä¸:: int em_dev_register_perf_domain(struct device *dev, unsigned int nr_states, - struct em_data_callback *cb, cpumask_t *cpus, bool milliwatts); + struct em_data_callback *cb, cpumask_t *cpus, bool microwatts); 驱动程åºå¿…é¡»æ供一个回调函数，为æ¯ä¸ªæ€§èƒ½çŠ¶æ€è¿”回<频率,功率>å…ƒç»„ã€‚é©±åŠ¨ç¨‹åº æ供的回调函数å¯ä»¥è‡ªç”±åœ°ä»Žä»»ä½•ç›¸å…³ä½ç½®ï¼ˆDTã€å›ºä»¶......）以åŠä»¥ä»»ä½•è¢«è®¤ä¸ºæ˜¯ å¿…è¦çš„æ–¹å¼èŽ·å–æ•°æ®ã€‚åªæœ‰å¯¹äºŽCPU设备，驱动程åºå¿…须使用cpumask指定性能域的CPU。 对于CPU以外的其他设备，最åŽä¸€ä¸ªå‚数必须被设置为NULL。 -最åŽä¸€ä¸ªå‚数“milliwattsâ€ï¼ˆæ¯«ç“¦ï¼‰è®¾ç½®æˆæ£ç¡®çš„值是很é‡è¦çš„，使用EMçš„å†…æ ¸ +最åŽä¸€ä¸ªå‚数“microwattsâ€ï¼ˆå¾®ç“¦ï¼‰è®¾ç½®æˆæ£ç¡®çš„值是很é‡è¦çš„，使用EMçš„å†…æ ¸ å系统å¯èƒ½ä¼šä¾èµ–è¿™ä¸ªæ ‡å¿—æ¥æ£€æŸ¥æ‰€æœ‰çš„EM设备是å¦ä½¿ç”¨ç›¸åŒçš„刻度。如果有ä¸åŒçš„ -刻度，这些å系统å¯èƒ½å†³å®šï¼šè¿”回è¦å‘Š/错误，åœæ¢å·¥ä½œæˆ–崩溃（panic）。 +刻度，这些å系统å¯èƒ½å†³å®šè¿”回è¦å‘Š/错误，åœæ¢å·¥ä½œæˆ–崩溃（panic）。 关于实现这个回调函数的驱动程åºçš„例å，å‚è§ç¬¬3节。或者在第2.4节阅读这个API 的更多文档。 +使用DTçš„EM注册 +============== + +EM也å¯ä»¥ä½¿ç”¨OPP框架和DT "æ“作点-v2 "ä¸çš„ä¿¡æ¯æ³¨å†Œã€‚DTä¸çš„æ¯ä¸ªOPPæ¡ç›®éƒ½å¯ +以用一个包å«å¾®ç“¦ç‰¹åŠŸçŽ‡å€¼çš„属性 "op-microwatt "æ¥æ‰©å±•ã€‚这个OPP DTå±žæ€§å… +许平å°æ³¨å†Œåæ˜ æ€»åŠŸçŽ‡ï¼ˆé™æ€+动æ€ï¼‰çš„EM功率值。这些功率值å¯èƒ½ç›´æŽ¥æ¥è‡ªå®žéªŒå’Œ +测é‡ã€‚ + +“人工â€EM的注册 +============== + +有一个选项å¯ä»¥ä¸ºç¼ºå°‘关于æ¯ä¸ªæ€§èƒ½çŠ¶æ€çš„功率值的详细知识的驱动程åºæ供一个自 +定义回调。回调.get_cost()是å¯é€‰çš„，它æä¾›EAS使用的“æˆæœ¬â€å€¼ã€‚这对那些åªæ +ä¾›CPU类型之间相对效率信æ¯çš„å¹³å°å¾ˆæœ‰ç”¨ï¼Œäººä»¬å¯ä»¥åˆ©ç”¨è¿™äº›ä¿¡æ¯æ¥åˆ›å»ºä¸€ä¸ªæŠ½è±¡çš„ +功率模型。但是，考虑到输入功率值的大å°é™åˆ¶ï¼Œå³ä½¿æ˜¯æŠ½è±¡çš„功率模型有时也很难装 +进去。.get_cost()å…许æä¾›åæ˜ CPU效率的“æˆæœ¬â€å€¼ã€‚这将å…许æä¾›EASä¿¡æ¯ï¼Œå®ƒ +与EM内部计算'æˆæœ¬'值的公å¼æœ‰ä¸åŒçš„关系。è¦ä¸ºè¿™æ ·çš„å¹³å°æ³¨å†ŒEM，驱动程åºå¿…é¡» +å°†æ ‡å¿—â€œmicrowattsâ€è®¾ç½®ä¸º0，æä¾›.get_power()回调和.get_cost()回调。EM +框架会在注册过程ä¸æ£ç¡®å¤„ç†è¿™æ ·çš„å¹³å°ã€‚è¿™ç§å¹³å°ä¼šè¢«è®¾ç½®EM_PERF_DOMAIN_ARTIFICIAL +æ ‡å¿—ã€‚å…¶ä»–ä½¿ç”¨EM的框架应该特别注æ„测试和æ£ç¡®å¯¹å¾…è¿™ä¸ªæ ‡å¿—ã€‚ “简å•â€EM的注册 ~~~~~~~~~~~~~~~~ @@ -147,8 +167,8 @@ cpufreq_driver::register_em()。这个回调必须为æ¯ä¸ªç‰¹å®šçš„é©±åŠ¨ç¨‹åº -> drivers/cpufreq/foo_cpufreq.c - 01 static int est_power(unsigned long *mW, unsigned long *KHz, - 02 struct device *dev) + 01 static int est_power(struct device *dev, unsigned long *mW, + 02 unsigned long *KHz) 03 { 04 long freq, power; 05 diff --git a/Documentation/translations/zh_CN/process/howto.rst b/Documentation/translations/zh_CN/process/howto.rst index 888978a62db3..10254751df6a 100644 --- a/Documentation/translations/zh_CN/process/howto.rst +++ b/Documentation/translations/zh_CN/process/howto.rst @@ -254,7 +254,7 @@ Linux-next 集æˆæµ‹è¯•æ ‘ https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git 通过这ç§æ–¹å¼ï¼ŒLinux-next 对下一个åˆå¹¶é˜¶æ®µå°†è¿›å…¥ä¸»çº¿å†…æ ¸çš„å†…å®¹ç»™å‡ºäº†ä¸€ä¸ªæ¦‚è¦ -展望。éžå¸¸æ¬¢å†’险的测试者è¿è¡Œæµ‹è¯•Linux-next。 +展望。éžå¸¸æ¬¢è¿Žå†’险的测试者è¿è¡Œæµ‹è¯•Linux-next。 多个主è¦ç‰ˆæœ¬çš„ç¨³å®šç‰ˆå†…æ ¸æ ‘ ----------------------------------- diff --git a/Documentation/translations/zh_TW/gpio.txt b/Documentation/translations/zh_TW/gpio.txt index e3c076dd75a5..1b986bbb0909 100644 --- a/Documentation/translations/zh_TW/gpio.txt +++ b/Documentation/translations/zh_TW/gpio.txt @@ -363,9 +363,6 @@ GPIO 編號是無符號整數;IRQ 編號也是。這些構æˆäº†å…©å€‹é‚輯上ä /* æ˜ å°„ GPIO 編號到 IRQ 編號 */ int gpio_to_irq(unsigned gpio); - /* æ˜ å°„ IRQ 編號到 GPIO 編號 (儘é‡é¿å…使用) */ - int irq_to_gpio(unsigned irq); - 它們的返回值爲å°æ‡‰å‘½åç©ºé–“çš„ç›¸é—œç·¨è™Ÿï¼Œæˆ–æ˜¯è² çš„éŒ¯èª¤ä»£ç¢¼(å¦‚æžœç„¡æ³•æ˜ å°„)。 (例如,æŸäº› GPIO 無法åšçˆ² IRQ 使用。)以下的編號錯誤是未經檢測的:使用一個 æœªé€šéŽ gpio_direction_input()é…置爲輸入的 GPIO 編號，或者使用一個 @@ -378,10 +375,6 @@ gpio_to_irq()返回的éžéŒ¯èª¤å€¼å¯ä»¥å‚³éžçµ¦ request_irq()或者 free_irq() 觸發é¸é …是 IRQ 接å£çš„一部分，如 IRQF_TRIGGER_FALLING，系統喚醒能力 也是如æ¤ã€‚ -irq_to_gpio()返回的éžéŒ¯èª¤å€¼å¤§å¤šæ•¸é€šå¸¸å¯ä»¥è¢« gpio_get_value()所使用， -比如在 IRQ 是沿觸發時åˆå§‹åŒ–或更新驅動狀態。注æ„æŸäº›å¹³å°ä¸æ”¯æŒåæ˜ å°„,所以 -ä½ æ‡‰è©²å„˜é‡é¿å…使用它。 - 模擬開æ¼ä¿¡è™Ÿ ---------------------------- @@ -634,18 +627,9 @@ GPIO 控制器的路徑類似 /sys/class/gpio/gpiochip42/ (å°æ–¼å¾ž#42 GPIO /* gpio_export()的逆æ“作 */ void gpio_unexport(); - /* 創建一個 sysfs 連接到已導出的 GPIO 節點 */ - int gpio_export_link(struct device *dev, const char *name, - unsigned gpio) - åœ¨ä¸€å€‹å…§æ ¸é©…å‹•ç”³è«‹ä¸€å€‹ GPIO 之後，它å¯ä»¥é€šéŽ gpio_export()使其在 sysfs 接å£ä¸å¯è¦‹ã€‚該驅動å¯ä»¥æŽ§åˆ¶ä¿¡è™Ÿæ–¹å‘是å¦å¯ä¿®æ”¹ã€‚這有助於防æ¢ç”¨æˆ¶ç©ºé–“代碼無æ„é–“ ç ´å£žé‡è¦çš„系統狀態。 這個明確的導出有助於(通éŽä½¿æŸäº›å¯¦é©—更容易來)調試，也å¯ä»¥æ供一個始終å˜åœ¨çš„接å£ï¼Œ 與文檔é…åˆä½œçˆ²æ¿ç´šæ”¯æŒåŒ…的一部分。 - -在 GPIO 被導出之後，gpio_export_link()å…許在 sysfs 文件系統的任何地方 -創建一個到這個 GPIO sysfs 節點的符號連çµã€‚這樣驅動就å¯ä»¥é€šéŽä¸€å€‹æ述性的 -åå—，在 sysfs ä¸ä»–們所æ“有的è¨å‚™ä¸‹æ供一個(到這個 GPIO sysfs 節點的)接å£ã€‚ - diff --git a/Documentation/usb/chipidea.rst b/Documentation/usb/chipidea.rst index 68473abe2823..d9920c24eca0 100644 --- a/Documentation/usb/chipidea.rst +++ b/Documentation/usb/chipidea.rst @@ -35,10 +35,10 @@ which can show otg fsm variables and some controller registers value:: 1) Power up 2 Freescale i.MX6Q sabre SD boards with gadget class driver loaded (e.g. g_mass_storage). -2) Connect 2 boards with usb cable with one end is micro A plug, the other end +2) Connect 2 boards with usb cable: one end is micro A plug, the other end is micro B plug. - The A-device(with micro A plug inserted) should enumerate B-device. + The A-device (with micro A plug inserted) should enumerate B-device. 3) Role switch @@ -54,18 +54,19 @@ which can show otg fsm variables and some controller registers value:: echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - or, by introducing HNP polling, B-Host can know when A-peripheral wish - to be host role, so this role switch also can be trigged in A-peripheral - side by answering the polling from B-Host, this can be done on A-device:: + or, by introducing HNP polling, B-Host can know when A-peripheral wishes to + be in the host role, so this role switch also can be triggered in + A-peripheral side by answering the polling from B-Host. This can be done on + A-device:: echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req A-device should switch back to host and enumerate B-device. -5) Remove B-device(unplug micro B plug) and insert again in 10 seconds, +5) Remove B-device (unplug micro B plug) and insert again in 10 seconds; A-device should enumerate B-device again. -6) Remove B-device(unplug micro B plug) and insert again after 10 seconds, +6) Remove B-device (unplug micro B plug) and insert again after 10 seconds; A-device should NOT enumerate B-device. if A-device wants to use bus: @@ -105,7 +106,7 @@ July 27, 2012 Revision 2.0 version 1.1a" 2. How to enable USB as system wakeup source -------------------------------------------- Below is the example for how to enable USB as system wakeup source -at imx6 platform. +on an imx6 platform. 2.1 Enable core's wakeup:: @@ -128,6 +129,6 @@ at imx6 platform. echo enabled > /sys/bus/usb/devices/1-1/power/wakeup If the system has only one usb port, and you want usb wakeup at this port, you -can use below script to enable usb wakeup:: +can use the below script to enable usb wakeup:: for i in $(find /sys -name wakeup | grep usb);do echo enabled > $i;done; diff --git a/Documentation/usb/gadget-testing.rst b/Documentation/usb/gadget-testing.rst index 2278c9ffb74a..2fca40443dc9 100644 --- a/Documentation/usb/gadget-testing.rst +++ b/Documentation/usb/gadget-testing.rst @@ -813,7 +813,7 @@ the user must provide the following: ================== ==================================================== Each frame description contains frame interval specification, and each -such specification consists of a number of lines with an inverval value +such specification consists of a number of lines with an interval value in each line. The rules stated above are best illustrated with an example:: # mkdir functions/uvc.usb0/control/header/h diff --git a/Documentation/usb/gadget_configfs.rst b/Documentation/usb/gadget_configfs.rst index e4566ffb223f..868e118a2644 100644 --- a/Documentation/usb/gadget_configfs.rst +++ b/Documentation/usb/gadget_configfs.rst @@ -90,6 +90,16 @@ Then the strings can be specified:: $ echo <manufacturer> > strings/0x409/manufacturer $ echo <product> > strings/0x409/product +Further custom string descriptors can be created as directories within the +language's directory, with the string text being written to the "s" attribute +within the string's directory: + + $ mkdir strings/0x409/xu.0 + $ echo <string text> > strings/0x409/xu.0/s + +Where function drivers support it, functions may allow symlinks to these custom +string descriptors to associate those strings with class descriptors. + 2. Creating the configurations ------------------------------ diff --git a/Documentation/usb/mass-storage.rst b/Documentation/usb/mass-storage.rst index f399ec631599..80a601a60931 100644 --- a/Documentation/usb/mass-storage.rst +++ b/Documentation/usb/mass-storage.rst @@ -150,7 +150,7 @@ Module parameters - bcdDevice -- USB Device version (BCD) (16 bit integer) - iManufacturer -- USB Manufacturer string (string) - iProduct -- USB Product string (string) - - iSerialNumber -- SerialNumber string (sting) + - iSerialNumber -- SerialNumber string (string) sysfs entries ============= diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index eb045fc495a4..0a1882e296ae 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -201,7 +201,6 @@ Code Seq# Include File Comments 'V' all linux/videodev2.h conflict! 'V' C0 linux/ivtvfb.h conflict! 'V' C0 linux/ivtv.h conflict! -'V' C0 media/davinci/vpfe_capture.h conflict! 'V' C0 media/si4713.h conflict! 'W' 00-1F linux/watchdog.h conflict! 'W' 00-1F linux/wanrouter.h conflict! (pre 3.9) @@ -222,6 +221,7 @@ Code Seq# Include File Comments 'a' 00-0F drivers/crypto/qat/qat_common/adf_cfg_common.h conflict! qat driver 'b' 00-FF conflict! bit3 vme host bridge <mailto:natalia@nikhefk.nikhef.nl> +'b' 00-0F linux/dma-buf.h conflict! 'c' all linux/cm4000_cs.h conflict! 'c' 00-7F linux/comstats.h conflict! 'c' 00-7F linux/coda.h conflict! diff --git a/Documentation/userspace-api/iommufd.rst b/Documentation/userspace-api/iommufd.rst index 79dd9eb51587..aa004faed5fd 100644 --- a/Documentation/userspace-api/iommufd.rst +++ b/Documentation/userspace-api/iommufd.rst @@ -165,7 +165,7 @@ Multiple io_pagetable-s, through their iopt_area-s, can share a single iopt_pages which avoids multi-pinning and double accounting of page consumption. -iommufd_ioas is sharable between subsystems, e.g. VFIO and VDPA, as long as +iommufd_ioas is shareable between subsystems, e.g. VFIO and VDPA, as long as devices managed by different subsystems are bound to a same iommufd. IOMMUFD User API diff --git a/Documentation/userspace-api/media/drivers/st-vgxy61.rst b/Documentation/userspace-api/media/drivers/st-vgxy61.rst index d9e3b80e3a96..17ac15afa77c 100644 --- a/Documentation/userspace-api/media/drivers/st-vgxy61.rst +++ b/Documentation/userspace-api/media/drivers/st-vgxy61.rst @@ -18,7 +18,7 @@ The ST VGXY61 driver implements the following controls: * - HDR linearize - The merger outputs a long exposure capture as long as it is not saturated. - * - HDR substraction + * - HDR subtraction - This involves subtracting the short exposure frame from the long exposure frame. * - No HDR diff --git a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst index c9d578e291b8..5ae8fac8ed4f 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst @@ -43,7 +43,7 @@ reduced range of reception. .. note:: - Wide band receiver might be implictly enabled if you enable + Wide band receiver might be implicitly enabled if you enable carrier reports. In that case it will be disabled as soon as you disable carrier reports. Trying to disable wide band receiver while carrier reports are active will do nothing. diff --git a/Documentation/userspace-api/media/rc/rc-protos.rst b/Documentation/userspace-api/media/rc/rc-protos.rst index a2eab3b45647..2a888ff5829f 100644 --- a/Documentation/userspace-api/media/rc/rc-protos.rst +++ b/Documentation/userspace-api/media/rc/rc-protos.rst @@ -75,7 +75,7 @@ protocol, or the manchester BPF decoder. - Command There is a variant of rc5 called either rc5x or extended rc5 -where there the second stop bit is the 6th commmand bit, but inverted. +where there the second stop bit is the 6th command bit, but inverted. This is done so it the scancodes and encoding is compatible with existing schemes. This bit is stored in bit 6 of the scancode, inverted. This is done to keep it compatible with plain rc-5 where there are two start bits. diff --git a/Documentation/userspace-api/media/rc/rc-tables.rst b/Documentation/userspace-api/media/rc/rc-tables.rst index 28ed94088015..aab99260fef5 100644 --- a/Documentation/userspace-api/media/rc/rc-tables.rst +++ b/Documentation/userspace-api/media/rc/rc-tables.rst @@ -628,7 +628,7 @@ the remote via /dev/input/event devices. - Put device into zoom/full screen mode - - ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH + - ZOOM / FULL SCREEN / ZOOM+ / HIDE PANEL / SWITCH - .. row 80 diff --git a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst index 44415822c7c5..42cdb0a9f786 100644 --- a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst +++ b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst @@ -490,7 +490,7 @@ struct v4l2_mpeg_vbi_fmt_ivtv - An alternate form of the sliced VBI data payload used when 36 lines of sliced VBI data are present. No line masks are provided in this form of the payload; all valid line mask bits are - implcitly set. + implicitly set. * - } - 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 cd33857d947d..3d8411acd5b8 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst @@ -1213,7 +1213,7 @@ FWHT Flags - Luma AC coefficient table index. * - __s8 - ``y_dc_delta`` - - Luma DC delta vaue. + - Luma DC delta value. * - __s8 - ``y2_dc_delta`` - Y2 block DC delta value. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst index 60f9a09422d6..522095c08469 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst @@ -8,7 +8,7 @@ JPEG Control Reference The JPEG class includes controls for common features of JPEG encoders and decoders. Currently it includes features for codecs implementing -progressive baseline DCT compression process with Huffman entrophy +progressive baseline DCT compression process with Huffman entropy coding. diff --git a/Documentation/userspace-api/media/v4l/hist-v4l2.rst b/Documentation/userspace-api/media/v4l/hist-v4l2.rst index dbc04374dc22..cdc11e9a0f32 100644 --- a/Documentation/userspace-api/media/v4l/hist-v4l2.rst +++ b/Documentation/userspace-api/media/v4l/hist-v4l2.rst @@ -47,7 +47,7 @@ Codec API was released. 1998-11-08: Many minor changes. Most symbols have been renamed. Some material changes to struct v4l2_capability. -1998-11-12: The read/write directon of some ioctls was misdefined. +1998-11-12: The read/write direction of some ioctls was misdefined. 1998-11-14: ``V4L2_PIX_FMT_RGB24`` changed to ``V4L2_PIX_FMT_BGR24``, and ``V4L2_PIX_FMT_RGB32`` changed to ``V4L2_PIX_FMT_BGR32``. Audio @@ -145,7 +145,7 @@ common Linux driver API conventions. ``VIDIOC_G_INFMT``, ``VIDIOC_S_OUTFMT``, ``VIDIOC_G_OUTFMT``, ``VIDIOC_S_VBIFMT`` and ``VIDIOC_G_VBIFMT``. The image format struct v4l2_format was renamed to struct v4l2_pix_format, while - struct v4l2_format is now the envelopping structure + struct v4l2_format is now the enveloping structure for all format negotiations. 5. Similar to the changes above, the ``VIDIOC_G_PARM`` and diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst index bf283a1b5581..24a771542059 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst @@ -262,7 +262,12 @@ the second byte and Y'\ :sub:`7-0` in the third byte. ================= These formats, commonly referred to as YUYV or YUY2, subsample the chroma -components horizontally by 2, storing 2 pixels in 4 bytes. +components horizontally by 2, storing 2 pixels in a container. The container +is 32-bits for 8-bit formats, and 64-bits for 10+-bit formats. + +The packed YUYV formats with more than 8 bits per component are stored as four +16-bit little-endian words. Each word's most significant bits contain one +component, and the least significant bits are zero padding. .. raw:: latex @@ -270,7 +275,7 @@ components horizontally by 2, storing 2 pixels in 4 bytes. .. tabularcolumns:: |p{3.4cm}|p{1.2cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}| -.. flat-table:: Packed YUV 4:2:2 Formats +.. flat-table:: Packed YUV 4:2:2 Formats in 32-bit container :header-rows: 1 :stub-columns: 0 @@ -337,6 +342,46 @@ components horizontally by 2, storing 2 pixels in 4 bytes. - Y'\ :sub:`3` - Cb\ :sub:`2` +.. tabularcolumns:: |p{3.4cm}|p{1.2cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}| + +.. flat-table:: Packed YUV 4:2:2 Formats in 64-bit container + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Word 0 + - Word 1 + - Word 2 + - Word 3 + * .. _V4L2-PIX-FMT-Y210: + + - ``V4L2_PIX_FMT_Y210`` + - 'Y210' + + - Y'\ :sub:`0` (bits 15-6) + - Cb\ :sub:`0` (bits 15-6) + - Y'\ :sub:`1` (bits 15-6) + - Cr\ :sub:`0` (bits 15-6) + * .. _V4L2-PIX-FMT-Y212: + + - ``V4L2_PIX_FMT_Y212`` + - 'Y212' + + - Y'\ :sub:`0` (bits 15-4) + - Cb\ :sub:`0` (bits 15-4) + - Y'\ :sub:`1` (bits 15-4) + - Cr\ :sub:`0` (bits 15-4) + * .. _V4L2-PIX-FMT-Y216: + + - ``V4L2_PIX_FMT_Y216`` + - 'Y216' + + - Y'\ :sub:`0` (bits 15-0) + - Cb\ :sub:`0` (bits 15-0) + - Y'\ :sub:`1` (bits 15-0) + - Cr\ :sub:`0` (bits 15-0) + .. raw:: latex \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst index 30f51cd33f99..d330aeb4d3eb 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst @@ -763,6 +763,200 @@ nomenclature that instead use the order of components as seen in a 24- or \normalsize +10 Bits Per Component +===================== + +These formats store a 30-bit RGB triplet with an optional 2 bit alpha in four +bytes. They are named based on the order of the RGB components as seen in a +32-bit word, which is then stored in memory in little endian byte order +(unless otherwise noted by the presence of bit 31 in the 4CC value), and on the +number of bits for each component. + +.. raw:: latex + + \begingroup + \tiny + \setlength{\tabcolsep}{2pt} + +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| + + +.. flat-table:: RGB Formats 10 Bits Per Color Component + :header-rows: 2 + :stub-columns: 0 + + * - Identifier + - Code + - :cspan:`7` Byte 0 in memory + - :cspan:`7` Byte 1 + - :cspan:`7` Byte 2 + - :cspan:`7` Byte 3 + * - + - + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + * .. _V4L2-PIX-FMT-RGBX1010102: + + - ``V4L2_PIX_FMT_RGBX1010102`` + - 'RX30' + + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - x + - x + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`9` + - b\ :sub:`8` + - b\ :sub:`7` + - b\ :sub:`6` + + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`9` + - g\ :sub:`8` + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + + - r\ :sub:`9` + - r\ :sub:`8` + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - + * .. _V4L2-PIX-FMT-RGBA1010102: + + - ``V4L2_PIX_FMT_RGBA1010102`` + - 'RA30' + + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - a\ :sub:`1` + - a\ :sub:`0` + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`9` + - b\ :sub:`8` + - b\ :sub:`7` + - b\ :sub:`6` + + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`9` + - g\ :sub:`8` + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + + - r\ :sub:`9` + - r\ :sub:`8` + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - + * .. _V4L2-PIX-FMT-ARGB2101010: + + - ``V4L2_PIX_FMT_ARGB2101010`` + - 'AR30' + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`9` + - b\ :sub:`8` + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`9` + - g\ :sub:`8` + - g\ :sub:`7` + - g\ :sub:`6` + + - a\ :sub:`1` + - a\ :sub:`0` + - r\ :sub:`9` + - r\ :sub:`8` + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - + +.. raw:: latex + + \endgroup + + Deprecated RGB Formats ====================== diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst index 6a387f9df3ba..62078a01de76 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst @@ -14,7 +14,7 @@ are often referred to as greyscale formats. - In all the tables that follow, bit 7 is the most significant bit in a byte. - Formats are described with the minimum number of pixels needed to create a byte-aligned repeating pattern. `...` indicates repetition of the pattern. - - Y'\ :sub:`x`\ [9:2] denotes bits 9 to 2 of the Y' value for pixel at colum + - Y'\ :sub:`x`\ [9:2] denotes bits 9 to 2 of the Y' value for pixel at column `x`. - `0` denotes padding bits set to 0. diff --git a/Documentation/userspace-api/media/v4l/subdev-formats.rst b/Documentation/userspace-api/media/v4l/subdev-formats.rst index 16ef3b41932e..a3a35eeed708 100644 --- a/Documentation/userspace-api/media/v4l/subdev-formats.rst +++ b/Documentation/userspace-api/media/v4l/subdev-formats.rst @@ -949,6 +949,43 @@ The following tables list existing packed RGB formats. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` + * .. _MEDIA-BUS-FMT-BGR666-1X18: + + - MEDIA_BUS_FMT_BGR666_1X18 + - 0x1023 + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` * .. _MEDIA-BUS-FMT-RBG888-1X24: - MEDIA_BUS_FMT_RBG888_1X24 @@ -1023,6 +1060,80 @@ The following tables list existing packed RGB formats. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` + * .. _MEDIA-BUS-FMT-BGR666-1X24_CPADHI: + + - MEDIA_BUS_FMT_BGR666_1X24_CPADHI + - 0x1024 + - + - + - + - + - + - + - + - + - + - 0 + - 0 + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - 0 + - 0 + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + * .. _MEDIA-BUS-FMT-RGB565-1X24_CPADHI: + + - MEDIA_BUS_FMT_RGB565_1X24_CPADHI + - 0x1022 + - + - + - + - + - + - + - + - + - + - 0 + - 0 + - 0 + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - 0 + - 0 + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - 0 + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` * .. _MEDIA-BUS-FMT-BGR888-1X24: - MEDIA_BUS_FMT_BGR888_1X24 diff --git a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst index 551ac9d3c6ef..7f10f0bbcfd3 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst @@ -71,7 +71,7 @@ overlay devices. - Default cropping rectangle, it shall cover the "whole picture". Assuming pixel aspect 1/1 this could be for example a 640 × 480 rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM - centered over the active picture area. The same co-ordinate system + centered over the active picture area. The same coordinate system as for ``bounds`` is used. * - struct :c:type:`v4l2_fract` - ``pixelaspect`` diff --git a/Documentation/userspace-api/netlink/c-code-gen.rst b/Documentation/userspace-api/netlink/c-code-gen.rst new file mode 100644 index 000000000000..89de42c13350 --- /dev/null +++ b/Documentation/userspace-api/netlink/c-code-gen.rst @@ -0,0 +1,107 @@ +.. SPDX-License-Identifier: BSD-3-Clause + +============================== +Netlink spec C code generation +============================== + +This document describes how Netlink specifications are used to render +C code (uAPI, policies etc.). It also defines the additional properties +allowed in older families by the ``genetlink-c`` protocol level, +to control the naming. + +For brevity this document refers to ``name`` properties of various +objects by the object type. For example ``$attr`` is the value +of ``name`` in an attribute, and ``$family`` is the name of the +family (the global ``name`` property). + +The upper case is used to denote literal values, e.g. ``$family-CMD`` +means the concatenation of ``$family``, a dash character, and the literal +``CMD``. + +The names of ``#defines`` and enum values are always converted to upper case, +and with dashes (``-``) replaced by underscores (``_``). + +If the constructed name is a C keyword, an extra underscore is +appended (``do`` -> ``do_``). + +Globals +======= + +``c-family-name`` controls the name of the ``#define`` for the family +name, default is ``$family-FAMILY-NAME``. + +``c-version-name`` controls the name of the ``#define`` for the version +of the family, default is ``$family-FAMILY-VERSION``. + +``max-by-define`` selects if max values for enums are defined as a +``#define`` rather than inside the enum. + +Definitions +=========== + +Constants +--------- + +Every constant is rendered as a ``#define``. +The name of the constant is ``$family-$constant`` and the value +is rendered as a string or integer according to its type in the spec. + +Enums and flags +--------------- + +Enums are named ``$family-$enum``. The full name can be set directly +or suppressed by specifying the ``enum-name`` property. +Default entry name is ``$family-$enum-$entry``. +If ``name-prefix`` is specified it replaces the ``$family-$enum`` +portion of the entry name. + +Boolean ``render-max`` controls creation of the max values +(which are enabled by default for attribute enums). + +Attributes +========== + +Each attribute set (excluding fractional sets) is rendered as an enum. + +Attribute enums are traditionally unnamed in netlink headers. +If naming is desired ``enum-name`` can be used to specify the name. + +The default attribute name prefix is ``$family-A`` if the name of the set +is the same as the name of the family and ``$family-A-$set`` if the names +differ. The prefix can be overridden by the ``name-prefix`` property of a set. +The rest of the section will refer to the prefix as ``$pfx``. + +Attributes are named ``$pfx-$attribute``. + +Attribute enums end with two special values ``__$pfx-MAX`` and ``$pfx-MAX`` +which are used for sizing attribute tables. +These two names can be specified directly with the ``attr-cnt-name`` +and ``attr-max-name`` properties respectively. + +If ``max-by-define`` is set to ``true`` at the global level ``attr-max-name`` +will be specified as a ``#define`` rather than an enum value. + +Operations +========== + +Operations are named ``$family-CMD-$operation``. +If ``name-prefix`` is specified it replaces the ``$family-CMD`` +portion of the name. + +Similarly to attribute enums operation enums end with special count and max +attributes. For operations those attributes can be renamed with +``cmd-cnt-name`` and ``cmd-max-name``. Max will be a define if ``max-by-define`` +is ``true``. + +Multicast groups +================ + +Each multicast group gets a define rendered into the kernel uAPI header. +The name of the define is ``$family-MCGRP-$group``, and can be overwritten +with the ``c-define-name`` property. + +Code generation +=============== + +uAPI header is assumed to come from ``<linux/$family.h>`` in the default header +search path. It can be changed using the ``uapi-header`` global property. diff --git a/Documentation/userspace-api/netlink/genetlink-legacy.rst b/Documentation/userspace-api/netlink/genetlink-legacy.rst new file mode 100644 index 000000000000..3bf0bcdf21d8 --- /dev/null +++ b/Documentation/userspace-api/netlink/genetlink-legacy.rst @@ -0,0 +1,178 @@ +.. SPDX-License-Identifier: BSD-3-Clause + +================================================================= +Netlink specification support for legacy Generic Netlink families +================================================================= + +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 (defined) +======================= + +Attribute type nests +-------------------- + +New Netlink families should use ``multi-attr`` to define arrays. +Older families (e.g. ``genetlink`` control family) attempted to +define array types reusing attribute type to carry information. + +For reference the ``multi-attr`` array may look like this:: + + [ARRAY-ATTR] + [INDEX (optionally)] + [MEMBER1] + [MEMBER2] + [SOME-OTHER-ATTR] + [ARRAY-ATTR] + [INDEX (optionally)] + [MEMBER1] + [MEMBER2] + +where ``ARRAY-ATTR`` is the array entry type. + +array-nest +~~~~~~~~~~ + +``array-nest`` creates the following structure:: + + [SOME-OTHER-ATTR] + [ARRAY-ATTR] + [ENTRY] + [MEMBER1] + [MEMBER2] + [ENTRY] + [MEMBER1] + [MEMBER2] + +It wraps the entire array in an extra attribute (hence limiting its size +to 64kB). The ``ENTRY`` nests are special and have the index of the entry +as their type instead of normal attribute type. + +type-value +~~~~~~~~~~ + +``type-value`` is a construct which uses attribute types to carry +information about a single object (often used when array is dumped +entry-by-entry). + +``type-value`` can have multiple levels of nesting, for example +genetlink's policy dumps create the following structures:: + + [POLICY-IDX] + [ATTR-IDX] + [POLICY-INFO-ATTR1] + [POLICY-INFO-ATTR2] + +Where the first level of nest has the policy index as it's attribute +type, it contains a single nest which has the attribute index as its +type. Inside the attr-index nest are the policy attributes. Modern +Netlink families should have instead defined this as a flat structure, +the nesting serves no good purpose here. + +Operations +========== + +Enum (message ID) model +----------------------- + +unified +~~~~~~~ + +Modern families use the ``unified`` message ID model, which uses +a single enumeration for all messages within family. Requests and +responses share the same message ID. Notifications have separate +IDs from the same space. For example given the following list +of operations: + +.. code-block:: yaml + + - + name: a + value: 1 + do: ... + - + name: b + do: ... + - + name: c + value: 4 + notify: a + - + name: d + do: ... + +Requests and responses for operation ``a`` will have the ID of 1, +the requests and responses of ``b`` - 2 (since there is no explicit +``value`` it's previous operation ``+ 1``). Notification ``c`` will +use the ID of 4, operation ``d`` 5 etc. + +directional +~~~~~~~~~~~ + +The ``directional`` model splits the ID assignment by the direction of +the message. Messages from and to the kernel can't be confused with +each other so this conserves the ID space (at the cost of making +the programming more cumbersome). + +In this case ``value`` attribute should be specified in the ``request`` +``reply`` sections of the operations (if an operation has both ``do`` +and ``dump`` the IDs are shared, ``value`` should be set in ``do``). +For notifications the ``value`` is provided at the op level but it +only allocates a ``reply`` (i.e. a "from-kernel" ID). Let's look +at an example: + +.. code-block:: yaml + + - + name: a + do: + request: + value: 2 + attributes: ... + reply: + value: 1 + attributes: ... + - + name: b + notify: a + - + name: c + notify: a + value: 7 + - + name: d + do: ... + +In this case ``a`` will use 2 when sending the message to the kernel +and expects message with ID 1 in response. Notification ``b`` allocates +a "from-kernel" ID which is 2. ``c`` allocates "from-kernel" ID of 7. +If operation ``d`` does not set ``values`` explicitly in the spec +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) +=================== + +Structures +---------- + +Legacy families can define C structures both to be used as the contents +of an attribute and as a fixed message header. The plan is to define +the structs in ``definitions`` and link the appropriate attrs. + +Multi-message DO +---------------- + +New Netlink families should never respond to a DO operation with multiple +replies, with ``NLM_F_MULTI`` set. Use a filtered dump instead. + +At the spec level we can define a ``dumps`` property for the ``do``, +perhaps with values of ``combine`` and ``multi-object`` depending +on how the parsing should be implemented (parse into a single reply +vs list of objects i.e. pretty much a dump). diff --git a/Documentation/userspace-api/netlink/index.rst b/Documentation/userspace-api/netlink/index.rst index b0c21538d97d..26f3720cb3be 100644 --- a/Documentation/userspace-api/netlink/index.rst +++ b/Documentation/userspace-api/netlink/index.rst @@ -10,3 +10,9 @@ Netlink documentation for users. :maxdepth: 2 intro + intro-specs + specs + c-code-gen + genetlink-legacy + +See also :ref:`Documentation/core-api/netlink.rst <kernel_netlink>`. diff --git a/Documentation/userspace-api/netlink/intro-specs.rst b/Documentation/userspace-api/netlink/intro-specs.rst new file mode 100644 index 000000000000..a3b847eafff7 --- /dev/null +++ b/Documentation/userspace-api/netlink/intro-specs.rst @@ -0,0 +1,80 @@ +.. SPDX-License-Identifier: BSD-3-Clause + +===================================== +Using Netlink protocol specifications +===================================== + +This document is a quick starting guide for using Netlink protocol +specifications. For more detailed description of the specs see :doc:`specs`. + +Simple CLI +========== + +Kernel comes with a simple CLI tool which should be useful when +developing Netlink related code. The tool is implemented in Python +and can use a YAML specification to issue Netlink requests +to the kernel. Only Generic Netlink is supported. + +The tool is located at ``tools/net/ynl/cli.py``. It accepts +a handul of arguments, the most important ones are: + + - ``--spec`` - point to the spec file + - ``--do $name`` / ``--dump $name`` - issue request ``$name`` + - ``--json $attrs`` - provide attributes for the request + - ``--subscribe $group`` - receive notifications from ``$group`` + +YAML specs can be found under ``Documentation/netlink/specs/``. + +Example use:: + + $ ./tools/net/ynl/cli.py --spec Documentation/netlink/specs/ethtool.yaml \ + --do rings-get \ + --json '{"header":{"dev-index": 18}}' + {'header': {'dev-index': 18, 'dev-name': 'eni1np1'}, + 'rx': 0, + 'rx-jumbo': 0, + 'rx-jumbo-max': 4096, + 'rx-max': 4096, + 'rx-mini': 0, + 'rx-mini-max': 4096, + 'tx': 0, + 'tx-max': 4096, + 'tx-push': 0} + +The input arguments are parsed as JSON, while the output is only +Python-pretty-printed. This is because some Netlink types can't +be expressed as JSON directly. If such attributes are needed in +the input some hacking of the script will be necessary. + +The spec and Netlink internals are factored out as a standalone +library - it should be easy to write Python tools / tests reusing +code from ``cli.py``. + +Generating kernel code +====================== + +``tools/net/ynl/ynl-regen.sh`` scans the kernel tree in search of +auto-generated files which need to be updated. Using this tool is the easiest +way to generate / update auto-generated code. + +By default code is re-generated only if spec is newer than the source, +to force regeneration use ``-f``. + +``ynl-regen.sh`` searches for ``YNL-GEN`` in the contents of files +(note that it only scans files in the git index, that is only files +tracked by git!) For instance the ``fou_nl.c`` kernel source contains:: + + /* Documentation/netlink/specs/fou.yaml */ + /* YNL-GEN kernel source */ + +``ynl-regen.sh`` will find this marker and replace the file with +kernel source based on fou.yaml. + +The simplest way to generate a new file based on a spec is to add +the two marker lines like above to a file, add that file to git, +and run the regeneration tool. Grep the tree for ``YNL-GEN`` +to see other examples. + +The code generation itself is performed by ``tools/net/ynl/ynl-gen-c.py`` +but it takes a few arguments so calling it directly for each file +quickly becomes tedious. diff --git a/Documentation/userspace-api/netlink/specs.rst b/Documentation/userspace-api/netlink/specs.rst new file mode 100644 index 000000000000..6ffe8137cd90 --- /dev/null +++ b/Documentation/userspace-api/netlink/specs.rst @@ -0,0 +1,425 @@ +.. SPDX-License-Identifier: BSD-3-Clause + +========================================= +Netlink protocol specifications (in YAML) +========================================= + +Netlink protocol specifications are complete, machine readable descriptions of +Netlink protocols written in YAML. The goal of the specifications is to allow +separating Netlink parsing from user space logic and minimize the amount of +hand written Netlink code for each new family, command, attribute. +Netlink specs should be complete and not depend on any other spec +or C header file, making it easy to use in languages which can't include +kernel headers directly. + +Internally kernel uses the YAML specs to generate: + + - the C uAPI header + - documentation of the protocol as a ReST file + - policy tables for input attribute validation + - operation tables + +YAML specifications can be found under ``Documentation/netlink/specs/`` + +This document describes details of the schema. +See :doc:`intro-specs` for a practical starting guide. + +Compatibility levels +==================== + +There are four schema levels for Netlink specs, from the simplest used +by new families to the most complex covering all the quirks of the old ones. +Each next level inherits the attributes of the previous level, meaning that +user capable of parsing more complex ``genetlink`` schemas is also compatible +with simpler ones. The levels are: + + - ``genetlink`` - most streamlined, should be used by all new families + - ``genetlink-c`` - superset of ``genetlink`` with extra attributes allowing + customization of define and enum type and value names; this schema should + be equivalent to ``genetlink`` for all implementations which don't interact + directly with C uAPI headers + - ``genetlink-legacy`` - Generic Netlink catch all schema supporting quirks of + all old genetlink families, strange attribute formats, binary structures etc. + - ``netlink-raw`` - catch all schema supporting pre-Generic Netlink protocols + such as ``NETLINK_ROUTE`` + +The definition of the schemas (in ``jsonschema``) can be found +under ``Documentation/netlink/``. + +Schema structure +================ + +YAML schema has the following conceptual sections: + + - globals + - definitions + - attributes + - operations + - multicast groups + +Most properties in the schema accept (or in fact require) a ``doc`` +sub-property documenting the defined object. + +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. + +genetlink +========= + +Globals +------- + +Attributes listed directly at the root level of the spec file. + +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 +~~~~~~~~ + +The schema level, default is ``genetlink``, which is the only value +allowed for new ``genetlink`` families. + +definitions +----------- + +Array of type and constant definitions. + +name +~~~~ + +Name of the type / constant. + +type +~~~~ + +One of the following types: + + - const - a single, standalone constant + - enum - defines an integer enumeration, with values for each entry + incrementing by 1, (e.g. 0, 1, 2, 3) + - flags - defines an integer enumeration, with values for each entry + occupying a bit, starting from bit 0, (e.g. 1, 2, 4, 8) + +value +~~~~~ + +The value for the ``const``. + +value-start +~~~~~~~~~~~ + +The first value for ``enum`` and ``flags``, allows overriding the default +start value of ``0`` (for ``enum``) and starting bit (for ``flags``). +For ``flags`` ``value-start`` selects the starting bit, not the shifted value. + +Sparse enumerations are not supported. + +entries +~~~~~~~ + +Array of names of the entries for ``enum`` and ``flags``. + +header +~~~~~~ + +For C-compatible languages, header which already defines this value. +In case the definition is shared by multiple families (e.g. ``IFNAMSIZ``) +code generators for C-compatible languages may prefer to add an appropriate +include instead of rendering a new definition. + +attribute-sets +-------------- + +This property contains information about netlink attributes of the family. +All families have at least one attribute set, most have multiple. +``attribute-sets`` is an array, with each entry describing a single set. + +Note that the spec is "flattened" and is not meant to visually resemble +the format of the netlink messages (unlike certain ad-hoc documentation +formats seen in kernel comments). In the spec subordinate attribute sets +are not defined inline as a nest, but defined in a separate attribute set +referred to with a ``nested-attributes`` property of the container. + +Spec may also contain fractional sets - sets which contain a ``subset-of`` +property. Such sets describe a section of a full set, allowing narrowing down +which attributes are allowed in a nest or refining the validation criteria. +Fractional sets can only be used in nests. They are not rendered to the uAPI +in any fashion. + +name +~~~~ + +Uniquely identifies the attribute set, operations and nested attributes +refer to the sets by the ``name``. + +subset-of +~~~~~~~~~ + +Re-defines a portion of another set (a fractional set). +Allows narrowing down fields and changing validation criteria +or even types of attributes depending on the nest in which they +are contained. The ``value`` of each attribute in the fractional +set is implicitly the same as in the main set. + +attributes +~~~~~~~~~~ + +List of attributes in the set. + +Attribute properties +-------------------- + +name +~~~~ + +Identifies the attribute, unique within the set. + +type +~~~~ + +Netlink attribute type, see :ref:`attr_types`. + +.. _assign_val: + +value +~~~~~ + +Numerical attribute ID, used in serialized Netlink messages. +The ``value`` property can be skipped, in which case the attribute ID +will be the value of the previous attribute plus one (recursively) +and ``0`` for the first attribute in the attribute set. + +Note that the ``value`` of an attribute is defined only in its main set. + +enum +~~~~ + +For integer types specifies that values in the attribute belong +to an ``enum`` or ``flags`` from the ``definitions`` section. + +enum-as-flags +~~~~~~~~~~~~~ + +Treat ``enum`` as ``flags`` regardless of its type in ``definitions``. +When both ``enum`` and ``flags`` forms are needed ``definitions`` should +contain an ``enum`` and attributes which need the ``flags`` form should +use this attribute. + +nested-attributes +~~~~~~~~~~~~~~~~~ + +Identifies the attribute space for attributes nested within given attribute. +Only valid for complex attributes which may have sub-attributes. + +multi-attr (arrays) +~~~~~~~~~~~~~~~~~~~ + +Boolean property signifying that the attribute may be present multiple times. +Allowing an attribute to repeat is the recommended way of implementing arrays +(no extra nesting). + +byte-order +~~~~~~~~~~ + +For integer types specifies attribute byte order - ``little-endian`` +or ``big-endian``. + +checks +~~~~~~ + +Input validation constraints used by the kernel. User space should query +the policy of the running kernel using Generic Netlink introspection, +rather than depend on what is specified in the spec file. + +The validation policy in the kernel is formed by combining the type +definition (``type`` and ``nested-attributes``) and the ``checks``. + +operations +---------- + +This section describes messages passed between the kernel and the user space. +There are three types of entries in this section - operations, notifications +and events. + +Operations describe the most common request - response communication. User +sends a request and kernel replies. Each operation may contain any combination +of the two modes familiar to netlink users - ``do`` and ``dump``. +``do`` and ``dump`` in turn contain a combination of ``request`` and +``response`` properties. If no explicit message with attributes is passed +in a given direction (e.g. a ``dump`` which does not accept filter, or a ``do`` +of a SET operation to which the kernel responds with just the netlink error +code) ``request`` or ``response`` section can be skipped. +``request`` and ``response`` sections list the attributes allowed in a message. +The list contains only the names of attributes from a set referred +to by the ``attribute-set`` property. + +Notifications and events both refer to the asynchronous messages sent by +the kernel to members of a multicast group. The difference between the +two is that a notification shares its contents with a GET operation +(the name of the GET operation is specified in the ``notify`` property). +This arrangement is commonly used for notifications about +objects where the notification carries the full object definition. + +Events are more focused and carry only a subset of information rather than full +object state (a made up example would be a link state change event with just +the interface name and the new link state). Events contain the ``event`` +property. Events are considered less idiomatic for netlink and notifications +should be preferred. + +list +~~~~ + +The only property of ``operations`` for ``genetlink``, holds the list of +operations, notifications etc. + +Operation properties +-------------------- + +name +~~~~ + +Identifies the operation. + +value +~~~~~ + +Numerical message ID, used in serialized Netlink messages. +The same enumeration rules are applied as to +:ref:`attribute values<assign_val>`. + +attribute-set +~~~~~~~~~~~~~ + +Specifies the attribute set contained within the message. + +do +~~~ + +Specification for the ``doit`` request. Should contain ``request``, ``reply`` +or both of these properties, each holding a :ref:`attr_list`. + +dump +~~~~ + +Specification for the ``dumpit`` request. Should contain ``request``, ``reply`` +or both of these properties, each holding a :ref:`attr_list`. + +notify +~~~~~~ + +Designates the message as a notification. Contains the name of the operation +(possibly the same as the operation holding this property) which shares +the contents with the notification (``do``). + +event +~~~~~ + +Specification of attributes in the event, holds a :ref:`attr_list`. +``event`` property is mutually exclusive with ``notify``. + +mcgrp +~~~~~ + +Used with ``event`` and ``notify``, specifies which multicast group +message belongs to. + +.. _attr_list: + +Message attribute list +---------------------- + +``request``, ``reply`` and ``event`` properties have a single ``attributes`` +property which holds the list of attribute names. + +Messages can also define ``pre`` and ``post`` properties which will be rendered +as ``pre_doit`` and ``post_doit`` calls in the kernel (these properties should +be ignored by user space). + +mcast-groups +------------ + +This section lists the multicast groups of the family. + +list +~~~~ + +The only property of ``mcast-groups`` for ``genetlink``, holds the list +of groups. + +Multicast group properties +-------------------------- + +name +~~~~ + +Uniquely identifies the multicast group in the family. Similarly to +Family ID, Multicast Group ID needs to be resolved at runtime, based +on the name. + +.. _attr_types: + +Attribute types +=============== + +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 +-------------------- + +Fixed-width integer types: +``u8``, ``u16``, ``u32``, ``u64``, ``s8``, ``s16``, ``s32``, ``s64``. + +Note that types smaller than 32 bit should be avoided as using them +does not save any memory in Netlink messages (due to alignment). +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. + +.. _pad_type: + +pad +--- + +Special attribute type used for padding attributes which require alignment +bigger than standard 4B alignment required by netlink (e.g. 64 bit integers). +There can only be a single attribute of the ``pad`` type in any attribute set +and it should be automatically used for padding when needed. + +flag +---- + +Attribute with no payload, its presence is the entire information. + +binary +------ + +Raw binary data attribute, the contents are opaque to generic code. + +string +------ + +Character string. Unless ``checks`` has ``unterminated-ok`` set to ``true`` +the string is required to be null terminated. +``max-len`` in ``checks`` indicates the longest possible string, +if not present the length of the string is unbounded. + +Note that ``max-len`` does not count the terminating character. + +nest +---- + +Attribute containing other (nested) attributes. +``nested-attributes`` specifies which attribute set is used inside. diff --git a/Documentation/userspace-api/seccomp_filter.rst b/Documentation/userspace-api/seccomp_filter.rst index d1e2b9193f09..cff0fa7f3175 100644 --- a/Documentation/userspace-api/seccomp_filter.rst +++ b/Documentation/userspace-api/seccomp_filter.rst @@ -274,7 +274,7 @@ value will be the injected file descriptor number. The notifying process can be preempted, resulting in the notification being aborted. This can be problematic when trying to take actions on behalf of the notifying process that are long-running and typically retryable (mounting a -filesytem). Alternatively, at filter installation time, the +filesystem). Alternatively, at filter installation time, the ``SECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV`` flag can be set. This flag makes it such that when a user notification is received by the supervisor, the notifying process will ignore non-fatal signals until the response is sent. Signals that diff --git a/Documentation/userspace-api/sysfs-platform_profile.rst b/Documentation/userspace-api/sysfs-platform_profile.rst index c33a71263d9e..4fccde2e4563 100644 --- a/Documentation/userspace-api/sysfs-platform_profile.rst +++ b/Documentation/userspace-api/sysfs-platform_profile.rst @@ -37,6 +37,6 @@ representation onto this fixed set. If there is no good match when mapping then a new profile name may be added. Drivers which wish to introduce new profile names must: - 1. Explain why the existing profile names canot be used. + 1. Explain why the existing profile names cannot be used. 2. Add the new profile name, along with a clear description of the expected behaviour, to the sysfs-platform_profile ABI documentation. diff --git a/Documentation/virt/index.rst b/Documentation/virt/index.rst index 56e003ff28ff..7fb55ae08598 100644 --- a/Documentation/virt/index.rst +++ b/Documentation/virt/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -============================ -Linux Virtualization Support -============================ +====================== +Virtualization Support +====================== .. toctree:: :maxdepth: 2 diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 0dd5d8733dd5..0a67cb738013 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -1354,6 +1354,14 @@ the memory region are automatically reflected into the guest. For example, an mmap() that affects the region will be made visible immediately. Another example is madvise(MADV_DROP). +Note: On arm64, a write generated by the page-table walker (to update +the Access and Dirty flags, for example) never results in a +KVM_EXIT_MMIO exit when the slot has the KVM_MEM_READONLY flag. This +is because KVM cannot provide the data that would be written by the +page-table walker, making it impossible to emulate the access. +Instead, an abort (data abort if the cause of the page-table update +was a load or a store, instruction abort if it was an instruction +fetch) is injected in the guest. 4.36 KVM_SET_TSS_ADDR --------------------- @@ -5343,9 +5351,9 @@ KVM_XEN_ATTR_TYPE_SHARED_INFO 32 vCPUs in the shared_info page, KVM does not automatically do so and instead requires that KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO be used explicitly even when the vcpu_info for a given vCPU resides at the - "default" location in the shared_info page. This is because KVM is - not aware of the Xen CPU id which is used as the index into the - vcpu_info[] array, so cannot know the correct default location. + "default" location in the shared_info page. This is because KVM may + not be aware of the Xen CPU id which is used as the index into the + vcpu_info[] array, so may know the correct default location. Note that the shared info page may be constantly written to by KVM; it contains the event channel bitmap used to deliver interrupts to @@ -5356,23 +5364,29 @@ KVM_XEN_ATTR_TYPE_SHARED_INFO any vCPU has been running or any event channel interrupts can be routed to the guest. + Setting the gfn to KVM_XEN_INVALID_GFN will disable the shared info + page. + KVM_XEN_ATTR_TYPE_UPCALL_VECTOR Sets the exception vector used to deliver Xen event channel upcalls. This is the HVM-wide vector injected directly by the hypervisor (not through the local APIC), typically configured by a guest via - HVM_PARAM_CALLBACK_IRQ. + HVM_PARAM_CALLBACK_IRQ. This can be disabled again (e.g. for guest + SHUTDOWN_soft_reset) by setting it to zero. KVM_XEN_ATTR_TYPE_EVTCHN This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It configures an outbound port number for interception of EVTCHNOP_send requests - 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 other fields cannot change for a given sending port. A port - mapping is removed by using KVM_XEN_EVTCHN_DEASSIGN in the flags - field. + 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 + 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 + outbound event channels. The values of the flags field are mutually + exclusive and cannot be combined as a bitmask. KVM_XEN_ATTR_TYPE_XEN_VERSION This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates @@ -5388,7 +5402,7 @@ KVM_XEN_ATTR_TYPE_RUNSTATE_UPDATE_FLAG support for KVM_XEN_HVM_CONFIG_RUNSTATE_UPDATE_FLAG. It enables the XEN_RUNSTATE_UPDATE flag which allows guest vCPUs to safely read other vCPUs' vcpu_runstate_info. Xen guests enable this feature via - the VM_ASST_TYPE_runstate_update_flag of the HYPERVISOR_vm_assist + the VMASST_TYPE_runstate_update_flag of the HYPERVISOR_vm_assist hypercall. 4.127 KVM_XEN_HVM_GET_ATTR @@ -5446,15 +5460,18 @@ KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO As with the shared_info page for the VM, the corresponding page may be dirtied at any time if event channel interrupt delivery is enabled, so userspace should always assume that the page is dirty without relying - on dirty logging. + on dirty logging. Setting the gpa to KVM_XEN_INVALID_GPA will disable + the vcpu_info. KVM_XEN_VCPU_ATTR_TYPE_VCPU_TIME_INFO Sets the guest physical address of an additional pvclock structure for a given vCPU. This is typically used for guest vsyscall support. + Setting the gpa to KVM_XEN_INVALID_GPA will disable the structure. KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADDR Sets the guest physical address of the vcpu_runstate_info for a given vCPU. This is how a Xen guest tracks CPU state such as steal time. + Setting the gpa to KVM_XEN_INVALID_GPA will disable the runstate area. KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_CURRENT Sets the runstate (RUNSTATE_running/_runnable/_blocked/_offline) of @@ -5487,7 +5504,8 @@ KVM_XEN_VCPU_ATTR_TYPE_TIMER This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It sets the event channel port/priority for the VIRQ_TIMER of the vCPU, as well - as allowing a pending timer to be saved/restored. + as allowing a pending timer to be saved/restored. Setting the timer + port to zero disables kernel handling of the singleshot timer. KVM_XEN_VCPU_ATTR_TYPE_UPCALL_VECTOR This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates @@ -5495,7 +5513,8 @@ KVM_XEN_VCPU_ATTR_TYPE_UPCALL_VECTOR per-vCPU local APIC upcall vector, configured by a Xen guest with the HVMOP_set_evtchn_upcall_vector hypercall. This is typically used by Windows guests, and is distinct from the HVM-wide upcall - vector configured with HVM_PARAM_CALLBACK_IRQ. + vector configured with HVM_PARAM_CALLBACK_IRQ. It is disabled by + setting the vector to zero. 4.129 KVM_XEN_VCPU_GET_ATTR @@ -6577,11 +6596,6 @@ Please note that the kernel is allowed to use the kvm_run structure as the primary storage for certain register types. Therefore, the kernel may use the values in kvm_run even if the corresponding bit in kvm_dirty_regs is not set. -:: - - }; - - 6. Capabilities that can be enabled on vCPUs ============================================ @@ -8056,9 +8070,13 @@ considering the state as complete. VMM needs to ensure that the dirty state is final and avoid missing dirty pages from another ioctl ordered after the bitmap collection. -NOTE: One example of using the backup bitmap is saving arm64 vgic/its -tables through KVM_DEV_ARM_{VGIC_GRP_CTRL, ITS_SAVE_TABLES} command on -KVM device "kvm-arm-vgic-its" when dirty ring is enabled. +NOTE: Multiple examples of using the backup bitmap: (1) save vgic/its +tables through command KVM_DEV_ARM_{VGIC_GRP_CTRL, ITS_SAVE_TABLES} on +KVM device "kvm-arm-vgic-its". (2) restore vgic/its tables through +command KVM_DEV_ARM_{VGIC_GRP_CTRL, ITS_RESTORE_TABLES} on KVM device +"kvm-arm-vgic-its". VGICv3 LPI pending status is restored. (3) save +vgic3 pending table through KVM_DEV_ARM_VGIC_{GRP_CTRL, SAVE_PENDING_TABLES} +command on KVM device "kvm-arm-vgic-v3". 8.30 KVM_CAP_XEN_HVM -------------------- @@ -8304,6 +8322,20 @@ CPU[EAX=1]:ECX[24] (TSC_DEADLINE) is not reported by ``KVM_GET_SUPPORTED_CPUID`` It can be enabled if ``KVM_CAP_TSC_DEADLINE_TIMER`` is present and the kernel has enabled in-kernel emulation of the local APIC. +CPU topology +~~~~~~~~~~~~ + +Several CPUID values include topology information for the host CPU: +0x0b and 0x1f for Intel systems, 0x8000001e for AMD systems. Different +versions of KVM return different values for this information and userspace +should not rely on it. Currently they return all zeroes. + +If userspace wishes to set up a guest topology, it should be careful that +the values of these three leaves differ for each CPU. In particular, +the APIC ID is found in EDX for all subleaves of 0x0b and 0x1f, and in EAX +for 0x8000001e; the latter also encodes the core id and node id in bits +7:0 of EBX and ECX respectively. + Obsolete ioctls and capabilities ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/locking.rst index 845a561629f1..a0146793d197 100644 --- a/Documentation/virt/kvm/locking.rst +++ b/Documentation/virt/kvm/locking.rst @@ -16,20 +16,30 @@ The acquisition orders for mutexes are as follows: - kvm->slots_lock is taken outside kvm->irq_lock, though acquiring them together is quite rare. -- Unlike kvm->slots_lock, kvm->slots_arch_lock is released before - synchronize_srcu(&kvm->srcu). Therefore kvm->slots_arch_lock - can be taken inside a kvm->srcu read-side critical section, - while kvm->slots_lock cannot. - - kvm->mn_active_invalidate_count ensures that pairs of invalidate_range_start() and invalidate_range_end() callbacks use the same memslots array. kvm->slots_lock and kvm->slots_arch_lock are taken on the waiting side in install_new_memslots, so MMU notifiers must not take either kvm->slots_lock or kvm->slots_arch_lock. +For SRCU: + +- ``synchronize_srcu(&kvm->srcu)`` is called inside critical sections + for kvm->lock, vcpu->mutex and kvm->slots_lock. These locks _cannot_ + be taken inside a kvm->srcu read-side critical section; that is, the + following is broken:: + + srcu_read_lock(&kvm->srcu); + mutex_lock(&kvm->slots_lock); + +- kvm->slots_arch_lock instead is released before the call to + ``synchronize_srcu()``. It _can_ therefore be taken inside a + kvm->srcu read-side critical section, for example while processing + a vmexit. + On x86: -- vcpu->mutex is taken outside kvm->arch.hyperv.hv_lock +- vcpu->mutex is taken outside kvm->arch.hyperv.hv_lock and kvm->arch.xen.xen_lock - kvm->arch.mmu_lock is an rwlock. kvm->arch.tdp_mmu_pages_lock and kvm->arch.mmu_unsync_pages_lock are taken inside kvm->arch.mmu_lock, and diff --git a/Documentation/virt/kvm/x86/amd-memory-encryption.rst b/Documentation/virt/kvm/x86/amd-memory-encryption.rst index 935aaeb97fe6..487b6328b3e7 100644 --- a/Documentation/virt/kvm/x86/amd-memory-encryption.rst +++ b/Documentation/virt/kvm/x86/amd-memory-encryption.rst @@ -440,7 +440,7 @@ References See [white-paper]_, [api-spec]_, [amd-apm]_ and [kvm-forum]_ for more info. -.. [white-paper] http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf +.. [white-paper] https://developer.amd.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf .. [api-spec] https://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf .. [amd-apm] https://support.amd.com/TechDocs/24593.pdf (section 15.34) .. [kvm-forum] https://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf diff --git a/Documentation/virt/kvm/x86/running-nested-guests.rst b/Documentation/virt/kvm/x86/running-nested-guests.rst index a27e6768d900..71136fe1723b 100644 --- a/Documentation/virt/kvm/x86/running-nested-guests.rst +++ b/Documentation/virt/kvm/x86/running-nested-guests.rst @@ -150,7 +150,7 @@ able to start an L1 guest with:: $ qemu-kvm -cpu host [...] The above will pass through the host CPU's capabilities as-is to the -gues); or for better live migration compatibility, use a named CPU +guest, or for better live migration compatibility, use a named CPU model supported by QEMU. e.g.:: $ qemu-kvm -cpu Haswell-noTSX-IBRS,vmx=on diff --git a/Documentation/watchdog/hpwdt.rst b/Documentation/watchdog/hpwdt.rst index c824cd7f6e32..5eab5dfec042 100644 --- a/Documentation/watchdog/hpwdt.rst +++ b/Documentation/watchdog/hpwdt.rst @@ -48,7 +48,7 @@ Last reviewed: 08/20/2018 NOTE: More information about watchdog drivers in general, including the ioctl interface to /dev/watchdog can be found in - Documentation/watchdog/watchdog-api.rst and Documentation/IPMI.txt. + Documentation/watchdog/watchdog-api.rst and Documentation/driver-api/ipmi.rst Due to limitations in the iLO hardware, the NMI pretimeout if enabled, can only be set to 9 seconds. Attempts to set pretimeout to other @@ -63,9 +63,9 @@ Last reviewed: 08/20/2018 and loop forever. This is generally not what a watchdog user wants. For those wishing to learn more please see: - Documentation/admin-guide/kdump/kdump.rst - Documentation/admin-guide/kernel-parameters.txt (panic=) - Your Linux Distribution specific documentation. + - Documentation/admin-guide/kdump/kdump.rst + - Documentation/admin-guide/kernel-parameters.txt (panic=) + - Your Linux Distribution specific documentation. If the hpwdt does not receive the NMI associated with an expiring timer, the iLO will proceed to reset the system at timeout if the timer hasn't diff --git a/Documentation/watchdog/index.rst b/Documentation/watchdog/index.rst index c177645081d8..4603f2511f58 100644 --- a/Documentation/watchdog/index.rst +++ b/Documentation/watchdog/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -====================== -Linux Watchdog Support -====================== +================ +Watchdog Support +================ .. toctree:: :maxdepth: 1 diff --git a/Documentation/x86/amd-memory-encryption.rst b/Documentation/x86/amd-memory-encryption.rst index a1940ebe7be5..934310ce7258 100644 --- a/Documentation/x86/amd-memory-encryption.rst +++ b/Documentation/x86/amd-memory-encryption.rst @@ -95,3 +95,39 @@ by supplying mem_encrypt=on on the kernel command line. However, if BIOS does not enable SME, then Linux will not be able to activate memory encryption, even if configured to do so by default or the mem_encrypt=on command line parameter is specified. + +Secure Nested Paging (SNP) +========================== + +SEV-SNP introduces new features (SEV_FEATURES[1:63]) which can be enabled +by the hypervisor for security enhancements. Some of these features need +guest side implementation to function correctly. The below table lists the +expected guest behavior with various possible scenarios of guest/hypervisor +SNP feature support. + ++-----------------+---------------+---------------+------------------+ +| Feature Enabled | Guest needs | Guest has | Guest boot | +| by the HV | implementation| implementation| behaviour | ++=================+===============+===============+==================+ +| No | No | No | Boot | +| | | | | ++-----------------+---------------+---------------+------------------+ +| No | Yes | No | Boot | +| | | | | ++-----------------+---------------+---------------+------------------+ +| No | Yes | Yes | Boot | +| | | | | ++-----------------+---------------+---------------+------------------+ +| Yes | No | No | Boot with | +| | | | feature enabled | ++-----------------+---------------+---------------+------------------+ +| Yes | Yes | No | Graceful boot | +| | | | failure | ++-----------------+---------------+---------------+------------------+ +| Yes | Yes | Yes | Boot with | +| | | | feature enabled | ++-----------------+---------------+---------------+------------------+ + +More details in AMD64 APM[1] Vol 2: 15.34.10 SEV_STATUS MSR + +[1] https://www.amd.com/system/files/TechDocs/40332.pdf diff --git a/Documentation/x86/resctrl.rst b/Documentation/x86/resctrl.rst index 71a531061e4e..387ccbcb558f 100644 --- a/Documentation/x86/resctrl.rst +++ b/Documentation/x86/resctrl.rst @@ -17,14 +17,21 @@ AMD refers to this feature as AMD Platform Quality of Service(AMD QoS). This feature is enabled by the CONFIG_X86_CPU_RESCTRL and the x86 /proc/cpuinfo flag bits: -============================================= ================================ +=============================================== ================================ RDT (Resource Director Technology) Allocation "rdt_a" CAT (Cache Allocation Technology) "cat_l3", "cat_l2" CDP (Code and Data Prioritization) "cdp_l3", "cdp_l2" CQM (Cache QoS Monitoring) "cqm_llc", "cqm_occup_llc" MBM (Memory Bandwidth Monitoring) "cqm_mbm_total", "cqm_mbm_local" MBA (Memory Bandwidth Allocation) "mba" -============================================= ================================ +SMBA (Slow Memory Bandwidth Allocation) "" +BMEC (Bandwidth Monitoring Event Configuration) "" +=============================================== ================================ + +Historically, new features were made visible by default in /proc/cpuinfo. This +resulted in the feature flags becoming hard to parse by humans. Adding a new +flag to /proc/cpuinfo should be avoided if user space can obtain information +about the feature from resctrl's info directory. To use the feature mount the file system:: @@ -161,6 +168,83 @@ with the following files: "mon_features": Lists the monitoring events if monitoring is enabled for the resource. + Example:: + + # cat /sys/fs/resctrl/info/L3_MON/mon_features + llc_occupancy + mbm_total_bytes + mbm_local_bytes + + If the system supports Bandwidth Monitoring Event + Configuration (BMEC), then the bandwidth events will + be configurable. The output will be:: + + # cat /sys/fs/resctrl/info/L3_MON/mon_features + llc_occupancy + mbm_total_bytes + mbm_total_bytes_config + mbm_local_bytes + mbm_local_bytes_config + +"mbm_total_bytes_config", "mbm_local_bytes_config": + Read/write files containing the configuration for the mbm_total_bytes + and mbm_local_bytes events, respectively, when the Bandwidth + Monitoring Event Configuration (BMEC) feature is supported. + The event configuration settings are domain specific and affect + all the CPUs in the domain. When either event configuration is + changed, the bandwidth counters for all RMIDs of both events + (mbm_total_bytes as well as mbm_local_bytes) are cleared for that + domain. The next read for every RMID will report "Unavailable" + and subsequent reads will report the valid value. + + Following are the types of events supported: + + ==== ======================================================== + Bits Description + ==== ======================================================== + 6 Dirty Victims from the QOS domain to all types of memory + 5 Reads to slow memory in the non-local NUMA domain + 4 Reads to slow memory in the local NUMA domain + 3 Non-temporal writes to non-local NUMA domain + 2 Non-temporal writes to local NUMA domain + 1 Reads to memory in the non-local NUMA domain + 0 Reads to memory in the local NUMA domain + ==== ======================================================== + + By default, the mbm_total_bytes configuration is set to 0x7f to count + all the event types and the mbm_local_bytes configuration is set to + 0x15 to count all the local memory events. + + Examples: + + * To view the current configuration:: + :: + + # cat /sys/fs/resctrl/info/L3_MON/mbm_total_bytes_config + 0=0x7f;1=0x7f;2=0x7f;3=0x7f + + # cat /sys/fs/resctrl/info/L3_MON/mbm_local_bytes_config + 0=0x15;1=0x15;3=0x15;4=0x15 + + * To change the mbm_total_bytes to count only reads on domain 0, + the bits 0, 1, 4 and 5 needs to be set, which is 110011b in binary + (in hexadecimal 0x33): + :: + + # echo "0=0x33" > /sys/fs/resctrl/info/L3_MON/mbm_total_bytes_config + + # cat /sys/fs/resctrl/info/L3_MON/mbm_total_bytes_config + 0=0x33;1=0x7f;2=0x7f;3=0x7f + + * To change the mbm_local_bytes to count all the slow memory reads on + domain 0 and 1, the bits 4 and 5 needs to be set, which is 110000b + in binary (in hexadecimal 0x30): + :: + + # echo "0=0x30;1=0x30" > /sys/fs/resctrl/info/L3_MON/mbm_local_bytes_config + + # cat /sys/fs/resctrl/info/L3_MON/mbm_local_bytes_config + 0=0x30;1=0x30;3=0x15;4=0x15 "max_threshold_occupancy": Read/write file provides the largest value (in @@ -464,6 +548,25 @@ Memory bandwidth domain is L3 cache. MB:<cache_id0>=bw_MBps0;<cache_id1>=bw_MBps1;... +Slow Memory Bandwidth Allocation (SMBA) +--------------------------------------- +AMD hardware supports Slow Memory Bandwidth Allocation (SMBA). +CXL.memory is the only supported "slow" memory device. With the +support of SMBA, the hardware enables bandwidth allocation on +the slow memory devices. If there are multiple such devices in +the system, the throttling logic groups all the slow sources +together and applies the limit on them as a whole. + +The presence of SMBA (with CXL.memory) is independent of slow memory +devices presence. If there are no such devices on the system, then +configuring SMBA will have no impact on the performance of the system. + +The bandwidth domain for slow memory is L3 cache. Its schemata file +is formatted as: +:: + + SMBA:<cache_id0>=bandwidth0;<cache_id1>=bandwidth1;... + Reading/writing the schemata file --------------------------------- Reading the schemata file will show the state of all resources @@ -479,6 +582,46 @@ which you wish to change. E.g. L3DATA:0=fffff;1=fffff;2=3c0;3=fffff L3CODE:0=fffff;1=fffff;2=fffff;3=fffff +Reading/writing the schemata file (on AMD systems) +-------------------------------------------------- +Reading the schemata file will show the current bandwidth limit on all +domains. The allocated resources are in multiples of one eighth GB/s. +When writing to the file, you need to specify what cache id you wish to +configure the bandwidth limit. + +For example, to allocate 2GB/s limit on the first cache id: + +:: + + # cat schemata + MB:0=2048;1=2048;2=2048;3=2048 + L3:0=ffff;1=ffff;2=ffff;3=ffff + + # echo "MB:1=16" > schemata + # cat schemata + MB:0=2048;1= 16;2=2048;3=2048 + L3:0=ffff;1=ffff;2=ffff;3=ffff + +Reading/writing the schemata file (on AMD systems) with SMBA feature +-------------------------------------------------------------------- +Reading and writing the schemata file is the same as without SMBA in +above section. + +For example, to allocate 8GB/s limit on the first cache id: + +:: + + # cat schemata + SMBA:0=2048;1=2048;2=2048;3=2048 + MB:0=2048;1=2048;2=2048;3=2048 + L3:0=ffff;1=ffff;2=ffff;3=ffff + + # echo "SMBA:1=64" > schemata + # cat schemata + SMBA:0=2048;1= 64;2=2048;3=2048 + MB:0=2048;1=2048;2=2048;3=2048 + L3:0=ffff;1=ffff;2=ffff;3=ffff + Cache Pseudo-Locking ==================== CAT enables a user to specify the amount of cache space that an @@ -608,12 +751,12 @@ how we can measure the latency in cycles of reading from this region and visualize this data with a histogram that is available if CONFIG_HIST_TRIGGERS is set:: - # :> /sys/kernel/debug/tracing/trace - # echo 'hist:keys=latency' > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/trigger - # echo 1 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/enable + # :> /sys/kernel/tracing/trace + # echo 'hist:keys=latency' > /sys/kernel/tracing/events/resctrl/pseudo_lock_mem_latency/trigger + # echo 1 > /sys/kernel/tracing/events/resctrl/pseudo_lock_mem_latency/enable # echo 1 > /sys/kernel/debug/resctrl/newlock/pseudo_lock_measure - # echo 0 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/enable - # cat /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/hist + # echo 0 > /sys/kernel/tracing/events/resctrl/pseudo_lock_mem_latency/enable + # cat /sys/kernel/tracing/events/resctrl/pseudo_lock_mem_latency/hist # event histogram # @@ -642,11 +785,11 @@ cache of a platform. Here is how we can obtain details of the cache hits and misses using the platform's precision counters. :: - # :> /sys/kernel/debug/tracing/trace - # echo 1 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_l2/enable + # :> /sys/kernel/tracing/trace + # echo 1 > /sys/kernel/tracing/events/resctrl/pseudo_lock_l2/enable # echo 2 > /sys/kernel/debug/resctrl/newlock/pseudo_lock_measure - # echo 0 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_l2/enable - # cat /sys/kernel/debug/tracing/trace + # echo 0 > /sys/kernel/tracing/events/resctrl/pseudo_lock_l2/enable + # cat /sys/kernel/tracing/trace # tracer: nop # diff --git a/Documentation/x86/x86_64/mm.rst b/Documentation/x86/x86_64/mm.rst index 9798676bb0bf..35e5e18c83d0 100644 --- a/Documentation/x86/x86_64/mm.rst +++ b/Documentation/x86/x86_64/mm.rst @@ -140,7 +140,7 @@ The direct mapping covers all memory in the system up to the highest memory address (this means in some cases it can also include PCI memory holes). -We map EFI runtime services in the 'efi_pgd' PGD in a 64Gb large virtual +We map EFI runtime services in the 'efi_pgd' PGD in a 64GB large virtual memory window (this size is arbitrary, it can be raised later if needed). The mappings are not part of any other kernel PGD and are only available during EFI runtime calls. |
