diff options
Diffstat (limited to 'Documentation')
937 files changed, 37634 insertions, 12120 deletions
diff --git a/Documentation/ABI/testing/debugfs-dell-wmi-ddv b/Documentation/ABI/testing/debugfs-dell-wmi-ddv new file mode 100644 index 000000000000..fbcc5d6f7388 --- /dev/null +++ b/Documentation/ABI/testing/debugfs-dell-wmi-ddv @@ -0,0 +1,21 @@ +What: /sys/kernel/debug/dell-wmi-ddv-<wmi_device_name>/fan_sensor_information +Date: September 2022 +KernelVersion: 6.1 +Contact: Armin Wolf <W_Armin@gmx.de> +Description: + This file contains the contents of the fan sensor information buffer, + which contains fan sensor entries and a terminating character (0xFF). + + Each fan sensor entry consists of three bytes with an unknown meaning, + interested people may use this file for reverse-engineering. + +What: /sys/kernel/debug/dell-wmi-ddv-<wmi_device_name>/thermal_sensor_information +Date: September 2022 +KernelVersion: 6.1 +Contact: Armin Wolf <W_Armin@gmx.de> +Description: + This file contains the contents of the thermal sensor information buffer, + which contains thermal sensor entries and a terminating character (0xFF). + + Each thermal sensor entry consists of five bytes with an unknown meaning, + interested people may use this file for reverse-engineering. diff --git a/Documentation/ABI/testing/debugfs-pktcdvd b/Documentation/ABI/testing/debugfs-pktcdvd deleted file mode 100644 index f6f65a4faea0..000000000000 --- a/Documentation/ABI/testing/debugfs-pktcdvd +++ /dev/null @@ -1,18 +0,0 @@ -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/sysfs-block-zram b/Documentation/ABI/testing/sysfs-block-zram index 14b2bf2e5105..628a00fb20a9 100644 --- a/Documentation/ABI/testing/sysfs-block-zram +++ b/Documentation/ABI/testing/sysfs-block-zram @@ -137,3 +137,17 @@ Description: The writeback_limit file is read-write and specifies the maximum amount of writeback ZRAM can do. The limit could be changed in run time. + +What: /sys/block/zram<id>/recomp_algorithm +Date: November 2022 +Contact: Sergey Senozhatsky <senozhatsky@chromium.org> +Description: + The recomp_algorithm file is read-write and allows to set + or show secondary compression algorithms. + +What: /sys/block/zram<id>/recompress +Date: November 2022 +Contact: Sergey Senozhatsky <senozhatsky@chromium.org> +Description: + The recompress file is write-only and triggers re-compression + with secondary compression algorithms. diff --git a/Documentation/ABI/testing/sysfs-bus-nvdimm b/Documentation/ABI/testing/sysfs-bus-nvdimm index 1c1f5acbf53d..de8c5a59c77f 100644 --- a/Documentation/ABI/testing/sysfs-bus-nvdimm +++ b/Documentation/ABI/testing/sysfs-bus-nvdimm @@ -41,3 +41,17 @@ KernelVersion: 5.18 Contact: Kajol Jain <kjain@linux.ibm.com> Description: (RO) This sysfs file exposes the cpumask which is designated to to retrieve nvdimm pmu event counter data. + +What: /sys/bus/nd/devices/nmemX/cxl/id +Date: November 2022 +KernelVersion: 6.2 +Contact: Dave Jiang <dave.jiang@intel.com> +Description: (RO) Show the id (serial) of the device. This is CXL specific. + +What: /sys/bus/nd/devices/nmemX/cxl/provider +Date: November 2022 +KernelVersion: 6.2 +Contact: Dave Jiang <dave.jiang@intel.com> +Description: (RO) Shows the CXL bridge device that ties to a CXL memory device + to this NVDIMM device. I.e. the parent of the device returned is + a /sys/bus/cxl/devices/memX instance. diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci index 840727fc75dc..ecf47559f495 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci +++ b/Documentation/ABI/testing/sysfs-bus-pci @@ -407,6 +407,16 @@ Description: file contains a '1' if the memory has been published for use outside the driver that owns the device. +What: /sys/bus/pci/devices/.../p2pmem/allocate +Date: August 2022 +Contact: Logan Gunthorpe <logang@deltatee.com> +Description: + This file allows mapping p2pmem into userspace. For each + mmap() call on this file, the kernel will allocate a chunk + of Peer-to-Peer memory for use in Peer-to-Peer transactions. + This memory can be used in O_DIRECT calls to NVMe backed + files for Peer-to-Peer copies. + What: /sys/bus/pci/devices/.../link/clkpm /sys/bus/pci/devices/.../link/l0s_aspm /sys/bus/pci/devices/.../link/l1_aspm diff --git a/Documentation/ABI/testing/sysfs-bus-spi-devices-spi-nor b/Documentation/ABI/testing/sysfs-bus-spi-devices-spi-nor index d76cd3946434..c800621eff95 100644 --- a/Documentation/ABI/testing/sysfs-bus-spi-devices-spi-nor +++ b/Documentation/ABI/testing/sysfs-bus-spi-devices-spi-nor @@ -5,6 +5,9 @@ Contact: linux-mtd@lists.infradead.org Description: (RO) The JEDEC ID of the SPI NOR flash as reported by the flash device. + The attribute is not present if the flash doesn't support + the "Read JEDEC ID" command (9Fh). This is the case for + non-JEDEC compliant flashes. What: /sys/bus/spi/devices/.../spi-nor/manufacturer Date: April 2021 @@ -12,6 +15,9 @@ KernelVersion: 5.14 Contact: linux-mtd@lists.infradead.org Description: (RO) Manufacturer of the SPI NOR flash. + The attribute is not present if the flash device isn't + known to the kernel and is only probed by its SFDP + tables. What: /sys/bus/spi/devices/.../spi-nor/partname Date: April 2021 diff --git a/Documentation/ABI/testing/sysfs-class-bdi b/Documentation/ABI/testing/sysfs-class-bdi index 6d2a2fc189dd..0d2abd88a18c 100644 --- a/Documentation/ABI/testing/sysfs-class-bdi +++ b/Documentation/ABI/testing/sysfs-class-bdi @@ -44,6 +44,21 @@ Description: (read-write) +What: /sys/class/bdi/<bdi>/min_ratio_fine +Date: November 2022 +Contact: Stefan Roesch <shr@devkernel.io> +Description: + Under normal circumstances each device is given a part of the + total write-back cache that relates to its current average + writeout speed in relation to the other devices. + + The 'min_ratio_fine' parameter allows assigning a minimum reserve + of the write-back cache to a particular device. The value is + expressed as part of 1 million. For example, this is useful for + providing a minimum QoS. + + (read-write) + What: /sys/class/bdi/<bdi>/max_ratio Date: January 2008 Contact: Peter Zijlstra <a.p.zijlstra@chello.nl> @@ -56,6 +71,59 @@ Description: be trusted to play fair. (read-write) + +What: /sys/class/bdi/<bdi>/max_ratio_fine +Date: November 2022 +Contact: Stefan Roesch <shr@devkernel.io> +Description: + Allows limiting a particular device to use not more than the + given value of the write-back cache. The value is given as part + of 1 million. This is useful in situations where we want to avoid + one device taking all or most of the write-back cache. For example + in case of an NFS mount that is prone to get stuck, or a FUSE mount + which cannot be trusted to play fair. + + (read-write) + +What: /sys/class/bdi/<bdi>/min_bytes +Date: October 2022 +Contact: Stefan Roesch <shr@devkernel.io> +Description: + Under normal circumstances each device is given a part of the + total write-back cache that relates to its current average + writeout speed in relation to the other devices. + + The 'min_bytes' parameter allows assigning a minimum + percentage of the write-back cache to a particular device + expressed in bytes. + For example, this is useful for providing a minimum QoS. + + (read-write) + +What: /sys/class/bdi/<bdi>/max_bytes +Date: October 2022 +Contact: Stefan Roesch <shr@devkernel.io> +Description: + Allows limiting a particular device to use not more than the + given 'max_bytes' of the write-back cache. This is useful in + situations where we want to avoid one device taking all or + most of the write-back cache. For example in case of an NFS + mount that is prone to get stuck, a FUSE mount which cannot be + trusted to play fair, or a nbd device. + + (read-write) + +What: /sys/class/bdi/<bdi>/strict_limit +Date: October 2022 +Contact: Stefan Roesch <shr@devkernel.io> +Description: + Forces per-BDI checks for the share of given device in the write-back + cache even before the global background dirty limit is reached. This + is useful in situations where the global limit is much higher than + affordable for given relatively slow (or untrusted) device. Turning + strictlimit on has no visible effect if max_ratio is equal to 100%. + + (read-write) What: /sys/class/bdi/<bdi>/stable_pages_required Date: January 2008 Contact: Peter Zijlstra <a.p.zijlstra@chello.nl> diff --git a/Documentation/ABI/testing/sysfs-class-pktcdvd b/Documentation/ABI/testing/sysfs-class-pktcdvd deleted file mode 100644 index ba1ce626591d..000000000000 --- a/Documentation/ABI/testing/sysfs-class-pktcdvd +++ /dev/null @@ -1,97 +0,0 @@ -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-devices-mapping b/Documentation/ABI/testing/sysfs-devices-mapping index 8d202bac9394..2eee1446ad4c 100644 --- a/Documentation/ABI/testing/sysfs-devices-mapping +++ b/Documentation/ABI/testing/sysfs-devices-mapping @@ -1,6 +1,6 @@ What: /sys/devices/uncore_iio_x/dieX Date: February 2020 -Contact: Roman Sudarikov <roman.sudarikov@linux.intel.com> +Contact: Alexander Antonov <alexander.antonov@linux.intel.com> Description: Each IIO stack (PCIe root port) has its own IIO PMON block, so each dieX file (where X is die number) holds "Segment:Root Bus" @@ -32,3 +32,31 @@ Description: IIO PMU 0 on die 1 belongs to PCI RP on bus 0x40, domain 0x0000 IIO PMU 0 on die 2 belongs to PCI RP on bus 0x80, domain 0x0000 IIO PMU 0 on die 3 belongs to PCI RP on bus 0xc0, domain 0x0000 + +What: /sys/devices/uncore_upi_x/dieX +Date: March 2022 +Contact: Alexander Antonov <alexander.antonov@linux.intel.com> +Description: + Each /sys/devices/uncore_upi_X/dieY file holds "upi_Z,die_W" + value that means UPI link number X on die Y is connected to UPI + link Z on die W and this link between sockets can be monitored + by UPI PMON block. + For example, 4-die Sapphire Rapids platform has the following + UPI 0 topology:: + + # tail /sys/devices/uncore_upi_0/die* + ==> /sys/devices/uncore_upi_0/die0 <== + upi_1,die_1 + ==> /sys/devices/uncore_upi_0/die1 <== + upi_0,die_3 + ==> /sys/devices/uncore_upi_0/die2 <== + upi_1,die_3 + ==> /sys/devices/uncore_upi_0/die3 <== + upi_0,die_1 + + Which means:: + + UPI link 0 on die 0 is connected to UPI link 1 on die 1 + UPI link 0 on die 1 is connected to UPI link 0 on die 3 + UPI link 0 on die 2 is connected to UPI link 1 on die 3 + UPI link 0 on die 3 is connected to UPI link 0 on die 1
\ No newline at end of file diff --git a/Documentation/ABI/testing/sysfs-driver-intel-i915-hwmon b/Documentation/ABI/testing/sysfs-driver-intel-i915-hwmon new file mode 100644 index 000000000000..2d6a472eef88 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-intel-i915-hwmon @@ -0,0 +1,75 @@ +What: /sys/devices/.../hwmon/hwmon<i>/in0_input +Date: February 2023 +KernelVersion: 6.2 +Contact: intel-gfx@lists.freedesktop.org +Description: RO. Current Voltage in millivolt. + + Only supported for particular Intel i915 graphics platforms. + +What: /sys/devices/.../hwmon/hwmon<i>/power1_max +Date: February 2023 +KernelVersion: 6.2 +Contact: intel-gfx@lists.freedesktop.org +Description: RW. Card reactive sustained (PL1/Tau) power limit in microwatts. + + The power controller will throttle the operating frequency + if the power averaged over a window (typically seconds) + exceeds this limit. + + Only supported for particular Intel i915 graphics platforms. + +What: /sys/devices/.../hwmon/hwmon<i>/power1_rated_max +Date: February 2023 +KernelVersion: 6.2 +Contact: intel-gfx@lists.freedesktop.org +Description: RO. Card default power limit (default TDP setting). + + Only supported for particular Intel i915 graphics platforms. + +What: /sys/devices/.../hwmon/hwmon<i>/power1_max_interval +Date: February 2023 +KernelVersion: 6.2 +Contact: intel-gfx@lists.freedesktop.org +Description: RW. Sustained power limit interval (Tau in PL1/Tau) in + milliseconds over which sustained power is averaged. + + Only supported for particular Intel i915 graphics platforms. + +What: /sys/devices/.../hwmon/hwmon<i>/power1_crit +Date: February 2023 +KernelVersion: 6.2 +Contact: intel-gfx@lists.freedesktop.org +Description: RW. Card reactive critical (I1) power limit in microwatts. + + Card reactive critical (I1) power limit in microwatts is exposed + for client products. The power controller will throttle the + operating frequency if the power averaged over a window exceeds + this limit. + + Only supported for particular Intel i915 graphics platforms. + +What: /sys/devices/.../hwmon/hwmon<i>/curr1_crit +Date: February 2023 +KernelVersion: 6.2 +Contact: intel-gfx@lists.freedesktop.org +Description: RW. Card reactive critical (I1) power limit in milliamperes. + + Card reactive critical (I1) power limit in milliamperes is + exposed for server products. The power controller will throttle + the operating frequency if the power averaged over a window + exceeds this limit. + + Only supported for particular Intel i915 graphics platforms. + +What: /sys/devices/.../hwmon/hwmon<i>/energy1_input +Date: February 2023 +KernelVersion: 6.2 +Contact: intel-gfx@lists.freedesktop.org +Description: RO. Energy input of device or gt in microjoules. + + For i915 device level hwmon devices (name "i915") this + reflects energy input for the entire device. For gt level + hwmon devices (name "i915_gtN") this reflects energy input + for the gt. + + Only supported for particular Intel i915 graphics platforms. diff --git a/Documentation/ABI/testing/sysfs-driver-intel_sdsi b/Documentation/ABI/testing/sysfs-driver-intel_sdsi index 96b92c105ec4..f8afed127107 100644 --- a/Documentation/ABI/testing/sysfs-driver-intel_sdsi +++ b/Documentation/ABI/testing/sysfs-driver-intel_sdsi @@ -4,21 +4,21 @@ KernelVersion: 5.18 Contact: "David E. Box" <david.e.box@linux.intel.com> Description: This directory contains interface files for accessing Intel - Software Defined Silicon (SDSi) features on a CPU. X - represents the socket instance (though not the socket ID). - The socket ID is determined by reading the registers file - and decoding it per the specification. + On Demand (formerly Software Defined Silicon or SDSi) features + on a CPU. X represents the socket instance (though not the + socket ID). The socket ID is determined by reading the + registers file and decoding it per the specification. - Some files communicate with SDSi hardware through a mailbox. - Should the operation fail, one of the following error codes - may be returned: + Some files communicate with On Demand hardware through a + mailbox. Should the operation fail, one of the following error + codes may be returned: ========== ===== Error Code Cause ========== ===== EIO General mailbox failure. Log may indicate cause. EBUSY Mailbox is owned by another agent. - EPERM SDSI capability is not enabled in hardware. + EPERM On Demand capability is not enabled in hardware. EPROTO Failure in mailbox protocol detected by driver. See log for details. EOVERFLOW For provision commands, the size of the data @@ -54,8 +54,8 @@ KernelVersion: 5.18 Contact: "David E. Box" <david.e.box@linux.intel.com> Description: (WO) Used to write an Authentication Key Certificate (AKC) to - the SDSi NVRAM for the CPU. The AKC is used to authenticate a - Capability Activation Payload. Mailbox command. + the On Demand NVRAM for the CPU. The AKC is used to authenticate + a Capability Activation Payload. Mailbox command. What: /sys/bus/auxiliary/devices/intel_vsec.sdsi.X/provision_cap Date: Feb 2022 @@ -63,17 +63,28 @@ KernelVersion: 5.18 Contact: "David E. Box" <david.e.box@linux.intel.com> Description: (WO) Used to write a Capability Activation Payload (CAP) to the - SDSi NVRAM for the CPU. CAPs are used to activate a given CPU - feature. A CAP is validated by SDSi hardware using a previously - provisioned AKC file. Upon successful authentication, the CPU - configuration is updated. A cold reboot is required to fully - activate the feature. Mailbox command. + On Demand NVRAM for the CPU. CAPs are used to activate a given + CPU feature. A CAP is validated by On Demand hardware using a + previously provisioned AKC file. Upon successful authentication, + the CPU configuration is updated. A cold reboot is required to + fully activate the feature. Mailbox command. + +What: /sys/bus/auxiliary/devices/intel_vsec.sdsi.X/meter_certificate +Date: Nov 2022 +KernelVersion: 6.2 +Contact: "David E. Box" <david.e.box@linux.intel.com> +Description: + (RO) Used to read back the current meter certificate for the CPU + from Intel On Demand hardware. The meter certificate contains + utilization metrics of On Demand enabled features. Mailbox + command. What: /sys/bus/auxiliary/devices/intel_vsec.sdsi.X/state_certificate Date: Feb 2022 KernelVersion: 5.18 Contact: "David E. Box" <david.e.box@linux.intel.com> Description: - (RO) Used to read back the current State Certificate for the CPU - from SDSi hardware. The State Certificate contains information - about the current licenses on the CPU. Mailbox command. + (RO) Used to read back the current state certificate for the CPU + from On Demand hardware. The state certificate contains + information about the current licenses on the CPU. Mailbox + command. diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index 483639fb727b..9e3756625a81 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -99,6 +99,12 @@ Description: Controls the issue rate of discard commands that consist of small checkpoint is triggered, and issued during the checkpoint. By default, it is disabled with 0. +What: /sys/fs/f2fs/<disk>/max_ordered_discard +Date: October 2022 +Contact: "Yangtao Li" <frank.li@vivo.com> +Description: Controls the maximum ordered discard, the unit size is one block(4KB). + Set it to 16 by default. + What: /sys/fs/f2fs/<disk>/max_discard_request Date: December 2021 Contact: "Konstantin Vyshetsky" <vkon@google.com> @@ -132,7 +138,8 @@ Contact: "Chao Yu" <yuchao0@huawei.com> Description: Controls discard granularity of inner discard thread. Inner thread will not issue discards with size that is smaller than granularity. The unit size is one block(4KB), now only support configuring - in range of [1, 512]. Default value is 4(=16KB). + in range of [1, 512]. Default value is 16. + For small devices, default value is 1. What: /sys/fs/f2fs/<disk>/umount_discard_timeout Date: January 2019 @@ -235,7 +242,7 @@ Description: Shows total written kbytes issued to disk. What: /sys/fs/f2fs/<disk>/features Date: July 2017 Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> -Description: <deprecated: should use /sys/fs/f2fs/<disk>/feature_list/ +Description: <deprecated: should use /sys/fs/f2fs/<disk>/feature_list/> Shows all enabled features in current device. Supported features: encryption, blkzoned, extra_attr, projquota, inode_checksum, @@ -592,10 +599,10 @@ Description: With "mode=fragment:block" mount options, we can scatter block allo in the length of 1..<max_fragment_hole> by turns. This value can be set between 1..512 and the default value is 4. -What: /sys/fs/f2fs/<disk>/gc_urgent_high_remaining -Date: December 2021 -Contact: "Daeho Jeong" <daehojeong@google.com> -Description: You can set the trial count limit for GC urgent high mode with this value. +What: /sys/fs/f2fs/<disk>/gc_remaining_trials +Date: October 2022 +Contact: "Yangtao Li" <frank.li@vivo.com> +Description: You can set the trial count limit for GC urgent and idle mode with this value. If GC thread gets to the limit, the mode will turn back to GC normal mode. By default, the value is zero, which means there is no limit like before. @@ -634,3 +641,31 @@ Date: July 2022 Contact: "Daeho Jeong" <daehojeong@google.com> Description: Show the accumulated total revoked atomic write block count after boot. If you write "0" here, you can initialize to "0". + +What: /sys/fs/f2fs/<disk>/gc_mode +Date: October 2022 +Contact: "Yangtao Li" <frank.li@vivo.com> +Description: Show the current gc_mode as a string. + This is a read-only entry. + +What: /sys/fs/f2fs/<disk>/discard_urgent_util +Date: November 2022 +Contact: "Yangtao Li" <frank.li@vivo.com> +Description: When space utilization exceeds this, do background DISCARD aggressively. + Does DISCARD forcibly in a period of given min_discard_issue_time when the number + of discards is not 0 and set discard granularity to 1. + Default: 80 + +What: /sys/fs/f2fs/<disk>/hot_data_age_threshold +Date: November 2022 +Contact: "Ping Xiong" <xiongping1@xiaomi.com> +Description: When DATA SEPARATION is on, it controls the age threshold to indicate + the data blocks as hot. By default it was initialized as 262144 blocks + (equals to 1GB). + +What: /sys/fs/f2fs/<disk>/warm_data_age_threshold +Date: November 2022 +Contact: "Ping Xiong" <xiongping1@xiaomi.com> +Description: When DATA SEPARATION is on, it controls the age threshold to indicate + the data blocks as warm. By default it was initialized as 2621440 blocks + (equals to 10GB). diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-damon b/Documentation/ABI/testing/sysfs-kernel-mm-damon index 08b9df323560..13397b853692 100644 --- a/Documentation/ABI/testing/sysfs-kernel-mm-damon +++ b/Documentation/ABI/testing/sysfs-kernel-mm-damon @@ -27,6 +27,10 @@ Description: Writing 'on' or 'off' to this file makes the kdamond starts or makes the kdamond reads the user inputs in the sysfs files except 'state' again. Writing 'update_schemes_stats' to the file updates contents of schemes stats files of the kdamond. + Writing 'update_schemes_tried_regions' to the file updates + contents of 'tried_regions' directory of every scheme directory + of this kdamond. Writing 'clear_schemes_tried_regions' to the + file removes contents of the 'tried_regions' directory. What: /sys/kernel/mm/damon/admin/kdamonds/<K>/pid Date: Mar 2022 @@ -283,3 +287,31 @@ Date: Mar 2022 Contact: SeongJae Park <sj@kernel.org> Description: Reading this file returns the number of the exceed events of the scheme's quotas. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/<R>/start +Date: Oct 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Reading this file returns the start address of a memory region + that corresponding DAMON-based Operation Scheme's action has + tried to be applied. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/<R>/end +Date: Oct 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Reading this file returns the end address of a memory region + that corresponding DAMON-based Operation Scheme's action has + tried to be applied. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/<R>/nr_accesses +Date: Oct 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Reading this file returns the 'nr_accesses' of a memory region + that corresponding DAMON-based Operation Scheme's action has + tried to be applied. + +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/<R>/age +Date: Oct 2022 +Contact: SeongJae Park <sj@kernel.org> +Description: Reading this file returns the 'age' of a memory region that + corresponding DAMON-based Operation Scheme's action has tried + to be applied. diff --git a/Documentation/ABI/testing/sysfs-kernel-oops_count b/Documentation/ABI/testing/sysfs-kernel-oops_count new file mode 100644 index 000000000000..156cca9dbc96 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-oops_count @@ -0,0 +1,6 @@ +What: /sys/kernel/oops_count +Date: November 2022 +KernelVersion: 6.2.0 +Contact: Linux Kernel Hardening List <linux-hardening@vger.kernel.org> +Description: + Shows how many times the system has Oopsed since last boot. diff --git a/Documentation/ABI/testing/sysfs-kernel-warn_count b/Documentation/ABI/testing/sysfs-kernel-warn_count new file mode 100644 index 000000000000..08f083d2fd51 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-warn_count @@ -0,0 +1,6 @@ +What: /sys/kernel/oops_count +Date: November 2022 +KernelVersion: 6.2.0 +Contact: Linux Kernel Hardening List <linux-hardening@vger.kernel.org> +Description: + Shows how many times the system has Warned since last boot. diff --git a/Documentation/ABI/testing/sysfs-platform-dell-wmi-ddv b/Documentation/ABI/testing/sysfs-platform-dell-wmi-ddv new file mode 100644 index 000000000000..1d97ad615c66 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-dell-wmi-ddv @@ -0,0 +1,7 @@ +What: /sys/class/power_supply/<battery_name>/eppid +Date: September 2022 +KernelVersion: 6.1 +Contact: Armin Wolf <W_Armin@gmx.de> +Description: + Reports the Dell ePPID (electronic Dell Piece Part Identification) + of the ACPI battery. diff --git a/Documentation/ABI/testing/sysfs-platform-intel-ifs b/Documentation/ABI/testing/sysfs-platform-intel-ifs index 486d6d2ff8a0..55991983d0d0 100644 --- a/Documentation/ABI/testing/sysfs-platform-intel-ifs +++ b/Documentation/ABI/testing/sysfs-platform-intel-ifs @@ -1,39 +1,41 @@ What: /sys/devices/virtual/misc/intel_ifs_<N>/run_test -Date: April 21 2022 -KernelVersion: 5.19 +Date: Nov 16 2022 +KernelVersion: 6.2 Contact: "Jithu Joseph" <jithu.joseph@intel.com> Description: Write <cpu#> to trigger IFS test for one online core. Note that the test is per core. The cpu# can be for any thread on the core. Running on one thread completes the test for the core containing that thread. Example: to test the core containing cpu5: echo 5 > - /sys/devices/platform/intel_ifs.<N>/run_test + /sys/devices/virtual/misc/intel_ifs_<N>/run_test What: /sys/devices/virtual/misc/intel_ifs_<N>/status -Date: April 21 2022 -KernelVersion: 5.19 +Date: Nov 16 2022 +KernelVersion: 6.2 Contact: "Jithu Joseph" <jithu.joseph@intel.com> Description: The status of the last test. It can be one of "pass", "fail" or "untested". What: /sys/devices/virtual/misc/intel_ifs_<N>/details -Date: April 21 2022 -KernelVersion: 5.19 +Date: Nov 16 2022 +KernelVersion: 6.2 Contact: "Jithu Joseph" <jithu.joseph@intel.com> Description: Additional information regarding the last test. The details file reports the hex value of the SCAN_STATUS MSR. Note that the error_code field may contain driver defined software code not defined in the Intel SDM. What: /sys/devices/virtual/misc/intel_ifs_<N>/image_version -Date: April 21 2022 -KernelVersion: 5.19 +Date: Nov 16 2022 +KernelVersion: 6.2 Contact: "Jithu Joseph" <jithu.joseph@intel.com> Description: Version (hexadecimal) of loaded IFS binary image. If no scan image is loaded reports "none". -What: /sys/devices/virtual/misc/intel_ifs_<N>/reload -Date: April 21 2022 -KernelVersion: 5.19 +What: /sys/devices/virtual/misc/intel_ifs_<N>/current_batch +Date: Nov 16 2022 +KernelVersion: 6.2 Contact: "Jithu Joseph" <jithu.joseph@intel.com> -Description: Write "1" (or "y" or "Y") to reload the IFS image from - /lib/firmware/intel/ifs/ff-mm-ss.scan. +Description: Write a number less than or equal to 0xff to load an IFS test image. + The number written treated as the 2 digit suffix in the following file name: + /lib/firmware/intel/ifs_<N>/ff-mm-ss-02x.scan + Reading the file will provide the suffix of the currently loaded IFS test image. diff --git a/Documentation/Makefile b/Documentation/Makefile index 64d44c1ecad3..bb73dcb5ed05 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -95,6 +95,15 @@ htmldocs: @$(srctree)/scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) +texinfodocs: + @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var))) + +# Note: the 'info' Make target is generated by sphinx itself when +# running the texinfodocs target define above. +infodocs: texinfodocs + $(MAKE) -C $(BUILDDIR)/texinfo info + linkcheckdocs: @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var))) @@ -143,6 +152,8 @@ cleandocs: dochelp: @echo ' Linux kernel internal documentation in different formats from ReST:' @echo ' htmldocs - HTML' + @echo ' texinfodocs - Texinfo' + @echo ' infodocs - Info' @echo ' latexdocs - LaTeX' @echo ' pdfdocs - PDF' @echo ' epubdocs - EPUB' diff --git a/Documentation/PCI/msi-howto.rst b/Documentation/PCI/msi-howto.rst index aa2046af69f7..8ae461e97c54 100644 --- a/Documentation/PCI/msi-howto.rst +++ b/Documentation/PCI/msi-howto.rst @@ -285,3 +285,13 @@ to bridges between the PCI root and the device, MSIs are disabled. It is also worth checking the device driver to see whether it supports MSIs. For example, it may contain calls to pci_alloc_irq_vectors() with the PCI_IRQ_MSI or PCI_IRQ_MSIX flags. + + +List of device drivers MSI(-X) APIs +=================================== + +The PCI/MSI subystem has a dedicated C file for its exported device driver +APIs — `drivers/pci/msi/api.c`. The following functions are exported: + +.. kernel-doc:: drivers/pci/msi/api.c + :export: diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst index 187f43a03200..bdafeb4b66dc 100644 --- a/Documentation/PCI/pci-error-recovery.rst +++ b/Documentation/PCI/pci-error-recovery.rst @@ -83,6 +83,7 @@ This structure has the form:: int (*mmio_enabled)(struct pci_dev *dev); int (*slot_reset)(struct pci_dev *dev); void (*resume)(struct pci_dev *dev); + void (*cor_error_detected)(struct pci_dev *dev); }; The possible channel states are:: @@ -422,5 +423,11 @@ That is, the recovery API only requires that: - drivers/net/cxgb3 - drivers/net/s2io.c + The cor_error_detected() callback is invoked in handle_error_source() when + the error severity is "correctable". The callback is optional and allows + additional logging to be done if desired. See example: + + - drivers/cxl/pci.c + The End ------- diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst index a0f8164c8513..49387d823619 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.rst +++ b/Documentation/RCU/Design/Requirements/Requirements.rst @@ -1858,7 +1858,7 @@ unloaded. After a given module has been unloaded, any attempt to call one of its functions results in a segmentation fault. The module-unload functions must therefore cancel any delayed calls to loadable-module functions, for example, any outstanding mod_timer() must be dealt -with via del_timer_sync() or similar. +with via timer_shutdown_sync() or similar. Unfortunately, there is no way to cancel an RCU callback; once you invoke call_rcu(), the callback function is eventually going to be diff --git a/Documentation/RCU/arrayRCU.rst b/Documentation/RCU/arrayRCU.rst deleted file mode 100644 index a5f2ff8fc54c..000000000000 --- a/Documentation/RCU/arrayRCU.rst +++ /dev/null @@ -1,165 +0,0 @@ -.. _array_rcu_doc: - -Using RCU to Protect Read-Mostly Arrays -======================================= - -Although RCU is more commonly used to protect linked lists, it can -also be used to protect arrays. Three situations are as follows: - -1. :ref:`Hash Tables <hash_tables>` - -2. :ref:`Static Arrays <static_arrays>` - -3. :ref:`Resizable Arrays <resizable_arrays>` - -Each of these three situations involves an RCU-protected pointer to an -array that is separately indexed. It might be tempting to consider use -of RCU to instead protect the index into an array, however, this use -case is **not** supported. The problem with RCU-protected indexes into -arrays is that compilers can play way too many optimization games with -integers, which means that the rules governing handling of these indexes -are far more trouble than they are worth. If RCU-protected indexes into -arrays prove to be particularly valuable (which they have not thus far), -explicit cooperation from the compiler will be required to permit them -to be safely used. - -That aside, each of the three RCU-protected pointer situations are -described in the following sections. - -.. _hash_tables: - -Situation 1: Hash Tables ------------------------- - -Hash tables are often implemented as an array, where each array entry -has a linked-list hash chain. Each hash chain can be protected by RCU -as described in listRCU.rst. This approach also applies to other -array-of-list situations, such as radix trees. - -.. _static_arrays: - -Situation 2: Static Arrays --------------------------- - -Static arrays, where the data (rather than a pointer to the data) is -located in each array element, and where the array is never resized, -have not been used with RCU. Rik van Riel recommends using seqlock in -this situation, which would also have minimal read-side overhead as long -as updates are rare. - -Quick Quiz: - Why is it so important that updates be rare when using seqlock? - -:ref:`Answer to Quick Quiz <answer_quick_quiz_seqlock>` - -.. _resizable_arrays: - -Situation 3: Resizable Arrays ------------------------------- - -Use of RCU for resizable arrays is demonstrated by the grow_ary() -function formerly used by the System V IPC code. The array is used -to map from semaphore, message-queue, and shared-memory IDs to the data -structure that represents the corresponding IPC construct. The grow_ary() -function does not acquire any locks; instead its caller must hold the -ids->sem semaphore. - -The grow_ary() function, shown below, does some limit checks, allocates a -new ipc_id_ary, copies the old to the new portion of the new, initializes -the remainder of the new, updates the ids->entries pointer to point to -the new array, and invokes ipc_rcu_putref() to free up the old array. -Note that rcu_assign_pointer() is used to update the ids->entries pointer, -which includes any memory barriers required on whatever architecture -you are running on:: - - static int grow_ary(struct ipc_ids* ids, int newsize) - { - struct ipc_id_ary* new; - struct ipc_id_ary* old; - int i; - int size = ids->entries->size; - - if(newsize > IPCMNI) - newsize = IPCMNI; - if(newsize <= size) - return newsize; - - new = ipc_rcu_alloc(sizeof(struct kern_ipc_perm *)*newsize + - sizeof(struct ipc_id_ary)); - if(new == NULL) - return size; - new->size = newsize; - memcpy(new->p, ids->entries->p, - sizeof(struct kern_ipc_perm *)*size + - sizeof(struct ipc_id_ary)); - for(i=size;i<newsize;i++) { - new->p[i] = NULL; - } - old = ids->entries; - - /* - * Use rcu_assign_pointer() to make sure the memcpyed - * contents of the new array are visible before the new - * array becomes visible. - */ - rcu_assign_pointer(ids->entries, new); - - ipc_rcu_putref(old); - return newsize; - } - -The ipc_rcu_putref() function decrements the array's reference count -and then, if the reference count has dropped to zero, uses call_rcu() -to free the array after a grace period has elapsed. - -The array is traversed by the ipc_lock() function. This function -indexes into the array under the protection of rcu_read_lock(), -using rcu_dereference() to pick up the pointer to the array so -that it may later safely be dereferenced -- memory barriers are -required on the Alpha CPU. Since the size of the array is stored -with the array itself, there can be no array-size mismatches, so -a simple check suffices. The pointer to the structure corresponding -to the desired IPC object is placed in "out", with NULL indicating -a non-existent entry. After acquiring "out->lock", the "out->deleted" -flag indicates whether the IPC object is in the process of being -deleted, and, if not, the pointer is returned:: - - struct kern_ipc_perm* ipc_lock(struct ipc_ids* ids, int id) - { - struct kern_ipc_perm* out; - int lid = id % SEQ_MULTIPLIER; - struct ipc_id_ary* entries; - - rcu_read_lock(); - entries = rcu_dereference(ids->entries); - if(lid >= entries->size) { - rcu_read_unlock(); - return NULL; - } - out = entries->p[lid]; - if(out == NULL) { - rcu_read_unlock(); - return NULL; - } - spin_lock(&out->lock); - - /* ipc_rmid() may have already freed the ID while ipc_lock - * was spinning: here verify that the structure is still valid - */ - if (out->deleted) { - spin_unlock(&out->lock); - rcu_read_unlock(); - return NULL; - } - return out; - } - -.. _answer_quick_quiz_seqlock: - -Answer to Quick Quiz: - Why is it so important that updates be rare when using seqlock? - - The reason that it is important that updates be rare when - using seqlock is that frequent updates can livelock readers. - One way to avoid this problem is to assign a seqlock for - each array entry rather than to the entire array. diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst index 048c5bc1f813..cc361fb01ed4 100644 --- a/Documentation/RCU/checklist.rst +++ b/Documentation/RCU/checklist.rst @@ -32,8 +32,8 @@ over a rather long period of time, but improvements are always welcome! for lockless updates. This does result in the mildly counter-intuitive situation where rcu_read_lock() and rcu_read_unlock() are used to protect updates, however, this - approach provides the same potential simplifications that garbage - collectors do. + approach can provide the same simplifications to certain types + of lockless algorithms that garbage collectors do. 1. Does the update code have proper mutual exclusion? @@ -49,12 +49,12 @@ over a rather long period of time, but improvements are always welcome! them -- even x86 allows later loads to be reordered to precede earlier stores), and be prepared to explain why this added complexity is worthwhile. If you choose #c, be prepared to - explain how this single task does not become a major bottleneck on - big multiprocessor machines (for example, if the task is updating - information relating to itself that other tasks can read, there - by definition can be no bottleneck). Note that the definition - of "large" has changed significantly: Eight CPUs was "large" - in the year 2000, but a hundred CPUs was unremarkable in 2017. + explain how this single task does not become a major bottleneck + on large systems (for example, if the task is updating information + relating to itself that other tasks can read, there by definition + can be no bottleneck). Note that the definition of "large" has + changed significantly: Eight CPUs was "large" in the year 2000, + but a hundred CPUs was unremarkable in 2017. 2. Do the RCU read-side critical sections make proper use of rcu_read_lock() and friends? These primitives are needed @@ -97,33 +97,38 @@ over a rather long period of time, but improvements are always welcome! b. Proceed as in (a) above, but also maintain per-element locks (that are acquired by both readers and writers) - that guard per-element state. Of course, fields that - the readers refrain from accessing can be guarded by - some other lock acquired only by updaters, if desired. + that guard per-element state. Fields that the readers + refrain from accessing can be guarded by some other lock + acquired only by updaters, if desired. - This works quite well, also. + This also works quite well. c. Make updates appear atomic to readers. For example, pointer updates to properly aligned fields will appear atomic, as will individual atomic primitives. Sequences of operations performed under a lock will *not* appear to be atomic to RCU readers, nor will sequences - of multiple atomic primitives. + of multiple atomic primitives. One alternative is to + move multiple individual fields to a separate structure, + thus solving the multiple-field problem by imposing an + additional level of indirection. This can work, but is starting to get a bit tricky. - d. Carefully order the updates and the reads so that - readers see valid data at all phases of the update. - This is often more difficult than it sounds, especially - given modern CPUs' tendency to reorder memory references. - One must usually liberally sprinkle memory barriers - (smp_wmb(), smp_rmb(), smp_mb()) through the code, - making it difficult to understand and to test. - - It is usually better to group the changing data into - a separate structure, so that the change may be made - to appear atomic by updating a pointer to reference - a new structure containing updated values. + d. Carefully order the updates and the reads so that readers + see valid data at all phases of the update. This is often + more difficult than it sounds, especially given modern + CPUs' tendency to reorder memory references. One must + usually liberally sprinkle memory-ordering operations + through the code, making it difficult to understand and + to test. Where it works, it is better to use things + like smp_store_release() and smp_load_acquire(), but in + some cases the smp_mb() full memory barrier is required. + + As noted earlier, it is usually better to group the + changing data into a separate structure, so that the + change may be made to appear atomic by updating a pointer + to reference a new structure containing updated values. 4. Weakly ordered CPUs pose special challenges. Almost all CPUs are weakly ordered -- even x86 CPUs allow later loads to be @@ -188,26 +193,29 @@ over a rather long period of time, but improvements are always welcome! when publicizing a pointer to a structure that can be traversed by an RCU read-side critical section. -5. If call_rcu() or call_srcu() is used, the callback function will - be called from softirq context. In particular, it cannot block. - If you need the callback to block, run that code in a workqueue - handler scheduled from the callback. The queue_rcu_work() - function does this for you in the case of call_rcu(). +5. If any of call_rcu(), call_srcu(), call_rcu_tasks(), + call_rcu_tasks_rude(), or call_rcu_tasks_trace() is used, + the callback function may be invoked from softirq context, + and in any case with bottom halves disabled. In particular, + this callback function cannot block. If you need the callback + to block, run that code in a workqueue handler scheduled from + the callback. The queue_rcu_work() function does this for you + in the case of call_rcu(). 6. Since synchronize_rcu() can block, it cannot be called from any sort of irq context. The same rule applies - for synchronize_srcu(), synchronize_rcu_expedited(), and - synchronize_srcu_expedited(). + for synchronize_srcu(), synchronize_rcu_expedited(), + synchronize_srcu_expedited(), synchronize_rcu_tasks(), + synchronize_rcu_tasks_rude(), and synchronize_rcu_tasks_trace(). The expedited forms of these primitives have the same semantics - as the non-expedited forms, but expediting is both expensive and - (with the exception of synchronize_srcu_expedited()) unfriendly - to real-time workloads. Use of the expedited primitives should - be restricted to rare configuration-change operations that would - not normally be undertaken while a real-time workload is running. - However, real-time workloads can use rcupdate.rcu_normal kernel - boot parameter to completely disable expedited grace periods, - though this might have performance implications. + as the non-expedited forms, but expediting is more CPU intensive. + Use of the expedited primitives should be restricted to rare + configuration-change operations that would not normally be + undertaken while a real-time workload is running. Note that + IPI-sensitive real-time workloads can use the rcupdate.rcu_normal + kernel boot parameter to completely disable expedited grace + periods, though this might have performance implications. In particular, if you find yourself invoking one of the expedited primitives repeatedly in a loop, please do everyone a favor: @@ -215,8 +223,9 @@ over a rather long period of time, but improvements are always welcome! a single non-expedited primitive to cover the entire batch. This will very likely be faster than the loop containing the expedited primitive, and will be much much easier on the rest - of the system, especially to real-time workloads running on - the rest of the system. + of the system, especially to real-time workloads running on the + rest of the system. Alternatively, instead use asynchronous + primitives such as call_rcu(). 7. As of v4.20, a given kernel implements only one RCU flavor, which is RCU-sched for PREEMPTION=n and RCU-preempt for PREEMPTION=y. @@ -239,7 +248,8 @@ over a rather long period of time, but improvements are always welcome! the corresponding readers must use rcu_read_lock_trace() and rcu_read_unlock_trace(). If an updater uses call_rcu_tasks_rude() or synchronize_rcu_tasks_rude(), then the corresponding readers - must use anything that disables interrupts. + must use anything that disables preemption, for example, + preempt_disable() and preempt_enable(). Mixing things up will result in confusion and broken kernels, and has even resulted in an exploitable security issue. Therefore, @@ -253,15 +263,16 @@ over a rather long period of time, but improvements are always welcome! that this usage is safe is that readers can use anything that disables BH when updaters use call_rcu() or synchronize_rcu(). -8. Although synchronize_rcu() is slower than is call_rcu(), it - usually results in simpler code. So, unless update performance is - critically important, the updaters cannot block, or the latency of - synchronize_rcu() is visible from userspace, synchronize_rcu() - should be used in preference to call_rcu(). Furthermore, - kfree_rcu() usually results in even simpler code than does - synchronize_rcu() without synchronize_rcu()'s multi-millisecond - latency. So please take advantage of kfree_rcu()'s "fire and - forget" memory-freeing capabilities where it applies. +8. Although synchronize_rcu() is slower than is call_rcu(), + it usually results in simpler code. So, unless update + performance is critically important, the updaters cannot block, + or the latency of synchronize_rcu() is visible from userspace, + synchronize_rcu() should be used in preference to call_rcu(). + Furthermore, kfree_rcu() and kvfree_rcu() usually result + in even simpler code than does synchronize_rcu() without + synchronize_rcu()'s multi-millisecond latency. So please take + advantage of kfree_rcu()'s and kvfree_rcu()'s "fire and forget" + memory-freeing capabilities where it applies. An especially important property of the synchronize_rcu() primitive is that it automatically self-limits: if grace periods @@ -271,8 +282,8 @@ over a rather long period of time, but improvements are always welcome! cases where grace periods are delayed, as failing to do so can result in excessive realtime latencies or even OOM conditions. - Ways of gaining this self-limiting property when using call_rcu() - include: + Ways of gaining this self-limiting property when using call_rcu(), + kfree_rcu(), or kvfree_rcu() include: a. Keeping a count of the number of data-structure elements used by the RCU-protected data structure, including @@ -304,18 +315,21 @@ over a rather long period of time, but improvements are always welcome! here is that superuser already has lots of ways to crash the machine. - d. Periodically invoke synchronize_rcu(), permitting a limited - number of updates per grace period. Better yet, periodically - invoke rcu_barrier() to wait for all outstanding callbacks. + d. Periodically invoke rcu_barrier(), permitting a limited + number of updates per grace period. - The same cautions apply to call_srcu() and kfree_rcu(). + The same cautions apply to call_srcu(), call_rcu_tasks(), + call_rcu_tasks_rude(), and call_rcu_tasks_trace(). This is + why there is an srcu_barrier(), rcu_barrier_tasks(), + rcu_barrier_tasks_rude(), and rcu_barrier_tasks_rude(), + respectively. - Note that although these primitives do take action to avoid memory - exhaustion when any given CPU has too many callbacks, a determined - user could still exhaust memory. This is especially the case - if a system with a large number of CPUs has been configured to - offload all of its RCU callbacks onto a single CPU, or if the - system has relatively little free memory. + Note that although these primitives do take action to avoid + memory exhaustion when any given CPU has too many callbacks, + a determined user or administrator can still exhaust memory. + This is especially the case if a system with a large number of + CPUs has been configured to offload all of its RCU callbacks onto + a single CPU, or if the system has relatively little free memory. 9. All RCU list-traversal primitives, which include rcu_dereference(), list_for_each_entry_rcu(), and @@ -344,14 +358,14 @@ over a rather long period of time, but improvements are always welcome! and you don't hold the appropriate update-side lock, you *must* use the "_rcu()" variants of the list macros. Failing to do so will break Alpha, cause aggressive compilers to generate bad code, - and confuse people trying to read your code. + and confuse people trying to understand your code. 11. Any lock acquired by an RCU callback must be acquired elsewhere - with softirq disabled, e.g., via spin_lock_irqsave(), - spin_lock_bh(), etc. Failing to disable softirq on a given - acquisition of that lock will result in deadlock as soon as - the RCU softirq handler happens to run your RCU callback while - interrupting that acquisition's critical section. + with softirq disabled, e.g., via spin_lock_bh(). Failing to + disable softirq on a given acquisition of that lock will result + in deadlock as soon as the RCU softirq handler happens to run + your RCU callback while interrupting that acquisition's critical + section. 12. RCU callbacks can be and are executed in parallel. In many cases, the callback code simply wrappers around kfree(), so that this @@ -372,7 +386,17 @@ over a rather long period of time, but improvements are always welcome! for some real-time workloads, this is the whole point of using the rcu_nocbs= kernel boot parameter. -13. Unlike other forms of RCU, it *is* permissible to block in an + In addition, do not assume that callbacks queued in a given order + will be invoked in that order, even if they all are queued on the + same CPU. Furthermore, do not assume that same-CPU callbacks will + be invoked serially. For example, in recent kernels, CPUs can be + switched between offloaded and de-offloaded callback invocation, + and while a given CPU is undergoing such a switch, its callbacks + might be concurrently invoked by that CPU's softirq handler and + that CPU's rcuo kthread. At such times, that CPU's callbacks + might be executed both concurrently and out of order. + +13. Unlike most flavors of RCU, it *is* permissible to block in an SRCU read-side critical section (demarked by srcu_read_lock() and srcu_read_unlock()), hence the "SRCU": "sleepable RCU". Please note that if you don't need to sleep in read-side critical @@ -412,6 +436,12 @@ over a rather long period of time, but improvements are always welcome! never sends IPIs to other CPUs, so it is easier on real-time workloads than is synchronize_rcu_expedited(). + It is also permissible to sleep in RCU Tasks Trace read-side + critical, which are delimited by rcu_read_lock_trace() and + rcu_read_unlock_trace(). However, this is a specialized flavor + of RCU, and you should not use it without first checking with + its current users. In most cases, you should instead use SRCU. + Note that rcu_assign_pointer() relates to SRCU just as it does to other forms of RCU, but instead of rcu_dereference() you should use srcu_dereference() in order to avoid lockdep splats. @@ -442,50 +472,62 @@ over a rather long period of time, but improvements are always welcome! find problems as follows: CONFIG_PROVE_LOCKING: - check that accesses to RCU-protected data - structures are carried out under the proper RCU - read-side critical section, while holding the right - combination of locks, or whatever other conditions - are appropriate. + check that accesses to RCU-protected data structures + are carried out under the proper RCU read-side critical + section, while holding the right combination of locks, + or whatever other conditions are appropriate. CONFIG_DEBUG_OBJECTS_RCU_HEAD: - check that you don't pass the - same object to call_rcu() (or friends) before an RCU - grace period has elapsed since the last time that you - passed that same object to call_rcu() (or friends). + check that you don't pass the same object to call_rcu() + (or friends) before an RCU grace period has elapsed + since the last time that you passed that same object to + call_rcu() (or friends). __rcu sparse checks: - tag the pointer to the RCU-protected data - structure with __rcu, and sparse will warn you if you - access that pointer without the services of one of the - variants of rcu_dereference(). + tag the pointer to the RCU-protected data structure + with __rcu, and sparse will warn you if you access that + pointer without the services of one of the variants + of rcu_dereference(). These debugging aids can help you find problems that are otherwise extremely difficult to spot. -17. If you register a callback using call_rcu() or call_srcu(), and - pass in a function defined within a loadable module, then it in - necessary to wait for all pending callbacks to be invoked after - the last invocation and before unloading that module. Note that - it is absolutely *not* sufficient to wait for a grace period! - The current (say) synchronize_rcu() implementation is *not* - guaranteed to wait for callbacks registered on other CPUs. - Or even on the current CPU if that CPU recently went offline - and came back online. +17. If you pass a callback function defined within a module to one of + call_rcu(), call_srcu(), call_rcu_tasks(), call_rcu_tasks_rude(), + or call_rcu_tasks_trace(), then it is necessary to wait for all + pending callbacks to be invoked before unloading that module. + Note that it is absolutely *not* sufficient to wait for a grace + period! For example, synchronize_rcu() implementation is *not* + guaranteed to wait for callbacks registered on other CPUs via + call_rcu(). Or even on the current CPU if that CPU recently + went offline and came back online. You instead need to use one of the barrier functions: - call_rcu() -> rcu_barrier() - call_srcu() -> srcu_barrier() + - call_rcu_tasks() -> rcu_barrier_tasks() + - call_rcu_tasks_rude() -> rcu_barrier_tasks_rude() + - call_rcu_tasks_trace() -> rcu_barrier_tasks_trace() However, these barrier functions are absolutely *not* guaranteed - to wait for a grace period. In fact, if there are no call_rcu() - callbacks waiting anywhere in the system, rcu_barrier() is within - its rights to return immediately. - - So if you need to wait for both an RCU grace period and for - all pre-existing call_rcu() callbacks, you will need to execute - both rcu_barrier() and synchronize_rcu(), if necessary, using - something like workqueues to execute them concurrently. + to wait for a grace period. For example, if there are no + call_rcu() callbacks queued anywhere in the system, rcu_barrier() + can and will return immediately. + + So if you need to wait for both a grace period and for all + pre-existing callbacks, you will need to invoke both functions, + with the pair depending on the flavor of RCU: + + - Either synchronize_rcu() or synchronize_rcu_expedited(), + together with rcu_barrier() + - Either synchronize_srcu() or synchronize_srcu_expedited(), + together with and srcu_barrier() + - synchronize_rcu_tasks() and rcu_barrier_tasks() + - synchronize_tasks_rude() and rcu_barrier_tasks_rude() + - synchronize_tasks_trace() and rcu_barrier_tasks_trace() + + If necessary, you can use something like workqueues to execute + the requisite pair of functions concurrently. See rcubarrier.rst for more information. diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst index e703d3dbe60c..84a79903f6a8 100644 --- a/Documentation/RCU/index.rst +++ b/Documentation/RCU/index.rst @@ -9,7 +9,6 @@ RCU concepts .. toctree:: :maxdepth: 3 - arrayRCU checklist lockdep lockdep-splat diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst index 2a643e293fb4..bdc4bcc5289f 100644 --- a/Documentation/RCU/listRCU.rst +++ b/Documentation/RCU/listRCU.rst @@ -3,11 +3,10 @@ Using RCU to Protect Read-Mostly Linked Lists ============================================= -One of the best applications of RCU is to protect read-mostly linked lists -(``struct list_head`` in list.h). One big advantage of this approach -is that all of the required memory barriers are included for you in -the list macros. This document describes several applications of RCU, -with the best fits first. +One of the most common uses of RCU is protecting read-mostly linked lists +(``struct list_head`` in list.h). One big advantage of this approach is +that all of the required memory ordering is provided by the list macros. +This document describes several list-based RCU use cases. Example 1: Read-mostly list: Deferred Destruction @@ -35,7 +34,8 @@ The code traversing the list of all processes typically looks like:: } rcu_read_unlock(); -The simplified code for removing a process from a task list is:: +The simplified and heavily inlined code for removing a process from a +task list is:: void release_task(struct task_struct *p) { @@ -45,39 +45,48 @@ The simplified code for removing a process from a task list is:: call_rcu(&p->rcu, delayed_put_task_struct); } -When a process exits, ``release_task()`` calls ``list_del_rcu(&p->tasks)`` under -``tasklist_lock`` writer lock protection, to remove the task from the list of -all tasks. The ``tasklist_lock`` prevents concurrent list additions/removals -from corrupting the list. Readers using ``for_each_process()`` are not protected -with the ``tasklist_lock``. To prevent readers from noticing changes in the list -pointers, the ``task_struct`` object is freed only after one or more grace -periods elapse (with the help of call_rcu()). This deferring of destruction -ensures that any readers traversing the list will see valid ``p->tasks.next`` -pointers and deletion/freeing can happen in parallel with traversal of the list. -This pattern is also called an **existence lock**, since RCU pins the object in -memory until all existing readers finish. +When a process exits, ``release_task()`` calls ``list_del_rcu(&p->tasks)`` +via __exit_signal() and __unhash_process() under ``tasklist_lock`` +writer lock protection. The list_del_rcu() invocation removes +the task from the list of all tasks. The ``tasklist_lock`` +prevents concurrent list additions/removals from corrupting the +list. Readers using ``for_each_process()`` are not protected with the +``tasklist_lock``. To prevent readers from noticing changes in the list +pointers, the ``task_struct`` object is freed only after one or more +grace periods elapse, with the help of call_rcu(), which is invoked via +put_task_struct_rcu_user(). This deferring of destruction ensures that +any readers traversing the list will see valid ``p->tasks.next`` pointers +and deletion/freeing can happen in parallel with traversal of the list. +This pattern is also called an **existence lock**, since RCU refrains +from invoking the delayed_put_task_struct() callback function until +all existing readers finish, which guarantees that the ``task_struct`` +object in question will remain in existence until after the completion +of all RCU readers that might possibly have a reference to that object. Example 2: Read-Side Action Taken Outside of Lock: No In-Place Updates ---------------------------------------------------------------------- -The best applications are cases where, if reader-writer locking were -used, the read-side lock would be dropped before taking any action -based on the results of the search. The most celebrated example is -the routing table. Because the routing table is tracking the state of -equipment outside of the computer, it will at times contain stale data. -Therefore, once the route has been computed, there is no need to hold -the routing table static during transmission of the packet. After all, -you can hold the routing table static all you want, but that won't keep -the external Internet from changing, and it is the state of the external -Internet that really matters. In addition, routing entries are typically -added or deleted, rather than being modified in place. - -A straightforward example of this use of RCU may be found in the -system-call auditing support. For example, a reader-writer locked +Some reader-writer locking use cases compute a value while holding +the read-side lock, but continue to use that value after that lock is +released. These use cases are often good candidates for conversion +to RCU. One prominent example involves network packet routing. +Because the packet-routing data tracks the state of equipment outside +of the computer, it will at times contain stale data. Therefore, once +the route has been computed, there is no need to hold the routing table +static during transmission of the packet. After all, you can hold the +routing table static all you want, but that won't keep the external +Internet from changing, and it is the state of the external Internet +that really matters. In addition, routing entries are typically added +or deleted, rather than being modified in place. This is a rare example +of the finite speed of light and the non-zero size of atoms actually +helping make synchronization be lighter weight. + +A straightforward example of this type of RCU use case may be found in +the system-call auditing support. For example, a reader-writer locked implementation of ``audit_filter_task()`` might be as follows:: - static enum audit_state audit_filter_task(struct task_struct *tsk) + static enum audit_state audit_filter_task(struct task_struct *tsk, char **key) { struct audit_entry *e; enum audit_state state; @@ -86,6 +95,8 @@ implementation of ``audit_filter_task()`` might be as follows:: /* Note: audit_filter_mutex held by caller. */ list_for_each_entry(e, &audit_tsklist, list) { if (audit_filter_rules(tsk, &e->rule, NULL, &state)) { + if (state == AUDIT_STATE_RECORD) + *key = kstrdup(e->rule.filterkey, GFP_ATOMIC); read_unlock(&auditsc_lock); return state; } @@ -101,7 +112,7 @@ you are turning auditing off, it is OK to audit a few extra system calls. This means that RCU can be easily applied to the read side, as follows:: - static enum audit_state audit_filter_task(struct task_struct *tsk) + static enum audit_state audit_filter_task(struct task_struct *tsk, char **key) { struct audit_entry *e; enum audit_state state; @@ -110,6 +121,8 @@ This means that RCU can be easily applied to the read side, as follows:: /* Note: audit_filter_mutex held by caller. */ list_for_each_entry_rcu(e, &audit_tsklist, list) { if (audit_filter_rules(tsk, &e->rule, NULL, &state)) { + if (state == AUDIT_STATE_RECORD) + *key = kstrdup(e->rule.filterkey, GFP_ATOMIC); rcu_read_unlock(); return state; } @@ -118,13 +131,15 @@ This means that RCU can be easily applied to the read side, as follows:: return AUDIT_BUILD_CONTEXT; } -The ``read_lock()`` and ``read_unlock()`` calls have become rcu_read_lock() -and rcu_read_unlock(), respectively, and the list_for_each_entry() has -become list_for_each_entry_rcu(). The **_rcu()** list-traversal primitives -insert the read-side memory barriers that are required on DEC Alpha CPUs. +The read_lock() and read_unlock() calls have become rcu_read_lock() +and rcu_read_unlock(), respectively, and the list_for_each_entry() +has become list_for_each_entry_rcu(). The **_rcu()** list-traversal +primitives add READ_ONCE() and diagnostic checks for incorrect use +outside of an RCU read-side critical section. The changes to the update side are also straightforward. A reader-writer lock -might be used as follows for deletion and insertion:: +might be used as follows for deletion and insertion in these simplified +versions of audit_del_rule() and audit_add_rule():: static inline int audit_del_rule(struct audit_rule *rule, struct list_head *list) @@ -188,16 +203,16 @@ Following are the RCU equivalents for these two functions:: return 0; } -Normally, the ``write_lock()`` and ``write_unlock()`` would be replaced by a +Normally, the write_lock() and write_unlock() would be replaced by a spin_lock() and a spin_unlock(). But in this case, all callers hold ``audit_filter_mutex``, so no additional locking is required. The -``auditsc_lock`` can therefore be eliminated, since use of RCU eliminates the +auditsc_lock can therefore be eliminated, since use of RCU eliminates the need for writers to exclude readers. The list_del(), list_add(), and list_add_tail() primitives have been replaced by list_del_rcu(), list_add_rcu(), and list_add_tail_rcu(). -The **_rcu()** list-manipulation primitives add memory barriers that are needed on -weakly ordered CPUs (most of them!). The list_del_rcu() primitive omits the +The **_rcu()** list-manipulation primitives add memory barriers that are +needed on weakly ordered CPUs. The list_del_rcu() primitive omits the pointer poisoning debug-assist code that would otherwise cause concurrent readers to fail spectacularly. @@ -238,7 +253,9 @@ need to be filled in):: The RCU version creates a copy, updates the copy, then replaces the old entry with the newly updated entry. This sequence of actions, allowing concurrent reads while making a copy to perform an update, is what gives -RCU (*read-copy update*) its name. The RCU code is as follows:: +RCU (*read-copy update*) its name. + +The RCU version of audit_upd_rule() is as follows:: static inline int audit_upd_rule(struct audit_rule *rule, struct list_head *list, @@ -267,6 +284,9 @@ RCU (*read-copy update*) its name. The RCU code is as follows:: Again, this assumes that the caller holds ``audit_filter_mutex``. Normally, the writer lock would become a spinlock in this sort of code. +The update_lsm_rule() does something very similar, for those who would +prefer to look at real Linux-kernel code. + Another use of this pattern can be found in the openswitch driver's *connection tracking table* code in ``ct_limit_set()``. The table holds connection tracking entries and has a limit on the maximum entries. There is one such table @@ -281,9 +301,10 @@ Example 4: Eliminating Stale Data --------------------------------- The auditing example above tolerates stale data, as do most algorithms -that are tracking external state. Because there is a delay from the -time the external state changes before Linux becomes aware of the change, -additional RCU-induced staleness is generally not a problem. +that are tracking external state. After all, given there is a delay +from the time the external state changes before Linux becomes aware +of the change, and so as noted earlier, a small quantity of additional +RCU-induced staleness is generally not a problem. However, there are many examples where stale data cannot be tolerated. One example in the Linux kernel is the System V IPC (see the shm_lock() @@ -302,7 +323,7 @@ Quick Quiz: If the system-call audit module were to ever need to reject stale data, one way to accomplish this would be to add a ``deleted`` flag and a ``lock`` spinlock to the -audit_entry structure, and modify ``audit_filter_task()`` as follows:: +``audit_entry`` structure, and modify audit_filter_task() as follows:: static enum audit_state audit_filter_task(struct task_struct *tsk) { @@ -319,6 +340,8 @@ audit_entry structure, and modify ``audit_filter_task()`` as follows:: return AUDIT_BUILD_CONTEXT; } rcu_read_unlock(); + if (state == AUDIT_STATE_RECORD) + *key = kstrdup(e->rule.filterkey, GFP_ATOMIC); return state; } } @@ -326,12 +349,6 @@ audit_entry structure, and modify ``audit_filter_task()`` as follows:: return AUDIT_BUILD_CONTEXT; } -Note that this example assumes that entries are only added and deleted. -Additional mechanism is required to deal correctly with the update-in-place -performed by ``audit_upd_rule()``. For one thing, ``audit_upd_rule()`` would -need additional memory barriers to ensure that the list_add_rcu() was really -executed before the list_del_rcu(). - The ``audit_del_rule()`` function would need to set the ``deleted`` flag under the spinlock as follows:: @@ -357,24 +374,32 @@ spinlock as follows:: This too assumes that the caller holds ``audit_filter_mutex``. +Note that this example assumes that entries are only added and deleted. +Additional mechanism is required to deal correctly with the update-in-place +performed by audit_upd_rule(). For one thing, audit_upd_rule() would +need to hold the locks of both the old ``audit_entry`` and its replacement +while executing the list_replace_rcu(). + Example 5: Skipping Stale Objects --------------------------------- -For some usecases, reader performance can be improved by skipping stale objects -during read-side list traversal if the object in concern is pending destruction -after one or more grace periods. One such example can be found in the timerfd -subsystem. When a ``CLOCK_REALTIME`` clock is reprogrammed - for example due to -setting of the system time, then all programmed timerfds that depend on this -clock get triggered and processes waiting on them to expire are woken up in -advance of their scheduled expiry. To facilitate this, all such timers are added -to an RCU-managed ``cancel_list`` when they are setup in +For some use cases, reader performance can be improved by skipping +stale objects during read-side list traversal, where stale objects +are those that will be removed and destroyed after one or more grace +periods. One such example can be found in the timerfd subsystem. When a +``CLOCK_REALTIME`` clock is reprogrammed (for example due to setting +of the system time) then all programmed ``timerfds`` that depend on +this clock get triggered and processes waiting on them are awakened in +advance of their scheduled expiry. To facilitate this, all such timers +are added to an RCU-managed ``cancel_list`` when they are setup in ``timerfd_setup_cancel()``:: static void timerfd_setup_cancel(struct timerfd_ctx *ctx, int flags) { spin_lock(&ctx->cancel_lock); - if ((ctx->clockid == CLOCK_REALTIME && + if ((ctx->clockid == CLOCK_REALTIME || + ctx->clockid == CLOCK_REALTIME_ALARM) && (flags & TFD_TIMER_ABSTIME) && (flags & TFD_TIMER_CANCEL_ON_SET)) { if (!ctx->might_cancel) { ctx->might_cancel = true; @@ -382,13 +407,16 @@ to an RCU-managed ``cancel_list`` when they are setup in list_add_rcu(&ctx->clist, &cancel_list); spin_unlock(&cancel_lock); } + } else { + __timerfd_remove_cancel(ctx); } spin_unlock(&ctx->cancel_lock); } -When a timerfd is freed (fd is closed), then the ``might_cancel`` flag of the -timerfd object is cleared, the object removed from the ``cancel_list`` and -destroyed:: +When a timerfd is freed (fd is closed), then the ``might_cancel`` +flag of the timerfd object is cleared, the object removed from the +``cancel_list`` and destroyed, as shown in this simplified and inlined +version of timerfd_release():: int timerfd_release(struct inode *inode, struct file *file) { @@ -403,7 +431,10 @@ destroyed:: } spin_unlock(&ctx->cancel_lock); - hrtimer_cancel(&ctx->t.tmr); + if (isalarm(ctx)) + alarm_cancel(&ctx->t.alarm); + else + hrtimer_cancel(&ctx->t.tmr); kfree_rcu(ctx, rcu); return 0; } @@ -416,6 +447,7 @@ objects:: void timerfd_clock_was_set(void) { + ktime_t moffs = ktime_mono_to_real(0); struct timerfd_ctx *ctx; unsigned long flags; @@ -424,7 +456,7 @@ objects:: if (!ctx->might_cancel) continue; spin_lock_irqsave(&ctx->wqh.lock, flags); - if (ctx->moffs != ktime_mono_to_real(0)) { + if (ctx->moffs != moffs) { ctx->moffs = KTIME_MAX; ctx->ticks++; wake_up_locked_poll(&ctx->wqh, EPOLLIN); @@ -434,10 +466,10 @@ objects:: rcu_read_unlock(); } -The key point here is, because RCU-traversal of the ``cancel_list`` happens -while objects are being added and removed to the list, sometimes the traversal -can step on an object that has been removed from the list. In this example, it -is seen that it is better to skip such objects using a flag. +The key point is that because RCU-protected traversal of the +``cancel_list`` happens concurrently with object addition and removal, +sometimes the traversal can access an object that has been removed from +the list. In this example, a flag is used to skip such objects. Summary diff --git a/Documentation/RCU/lockdep.rst b/Documentation/RCU/lockdep.rst index a94f55991a71..9308f1bdba05 100644 --- a/Documentation/RCU/lockdep.rst +++ b/Documentation/RCU/lockdep.rst @@ -17,7 +17,9 @@ state:: rcu_read_lock_held() for normal RCU. rcu_read_lock_bh_held() for RCU-bh. rcu_read_lock_sched_held() for RCU-sched. + rcu_read_lock_any_held() for any of normal RCU, RCU-bh, and RCU-sched. srcu_read_lock_held() for SRCU. + rcu_read_lock_trace_held() for RCU Tasks Trace. These functions are conservative, and will therefore return 1 if they aren't certain (for example, if CONFIG_DEBUG_LOCK_ALLOC is not set). @@ -53,6 +55,8 @@ checking of rcu_dereference() primitives: is invoked by both SRCU readers and updaters. rcu_dereference_raw(p): Don't check. (Use sparingly, if at all.) + rcu_dereference_raw_check(p): + Don't do lockdep at all. (Use sparingly, if at all.) rcu_dereference_protected(p, c): Use explicit check expression "c", and omit all barriers and compiler constraints. This is useful when the data diff --git a/Documentation/accel/index.rst b/Documentation/accel/index.rst new file mode 100644 index 000000000000..2b43c9a7f67b --- /dev/null +++ b/Documentation/accel/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +Compute Accelerators +==================== + +.. toctree:: + :maxdepth: 1 + + introduction + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/accel/introduction.rst b/Documentation/accel/introduction.rst new file mode 100644 index 000000000000..6f31af14b1fc --- /dev/null +++ b/Documentation/accel/introduction.rst @@ -0,0 +1,110 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ +Introduction +============ + +The Linux compute accelerators subsystem is designed to expose compute +accelerators in a common way to user-space and provide a common set of +functionality. + +These devices can be either stand-alone ASICs or IP blocks inside an SoC/GPU. +Although these devices are typically designed to accelerate +Machine-Learning (ML) and/or Deep-Learning (DL) computations, the accel layer +is not limited to handling these types of accelerators. + +Typically, a compute accelerator will belong to one of the following +categories: + +- Edge AI - doing inference at an edge device. It can be an embedded ASIC/FPGA, + or an IP inside a SoC (e.g. laptop web camera). These devices + are typically configured using registers and can work with or without DMA. + +- Inference data-center - single/multi user devices in a large server. This + type of device can be stand-alone or an IP inside a SoC or a GPU. It will + have on-board DRAM (to hold the DL topology), DMA engines and + command submission queues (either kernel or user-space queues). + It might also have an MMU to manage multiple users and might also enable + virtualization (SR-IOV) to support multiple VMs on the same device. In + addition, these devices will usually have some tools, such as profiler and + debugger. + +- Training data-center - Similar to Inference data-center cards, but typically + have more computational power and memory b/w (e.g. HBM) and will likely have + a method of scaling-up/out, i.e. connecting to other training cards inside + the server or in other servers, respectively. + +All these devices typically have different runtime user-space software stacks, +that are tailored-made to their h/w. In addition, they will also probably +include a compiler to generate programs to their custom-made computational +engines. Typically, the common layer in user-space will be the DL frameworks, +such as PyTorch and TensorFlow. + +Sharing code with DRM +===================== + +Because this type of devices can be an IP inside GPUs or have similar +characteristics as those of GPUs, the accel subsystem will use the +DRM subsystem's code and functionality. i.e. the accel core code will +be part of the DRM subsystem and an accel device will be a new type of DRM +device. + +This will allow us to leverage the extensive DRM code-base and +collaborate with DRM developers that have experience with this type of +devices. In addition, new features that will be added for the accelerator +drivers can be of use to GPU drivers as well. + +Differentiation from GPUs +========================= + +Because we want to prevent the extensive user-space graphic software stack +from trying to use an accelerator as a GPU, the compute accelerators will be +differentiated from GPUs by using a new major number and new device char files. + +Furthermore, the drivers will be located in a separate place in the kernel +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*/ + +Getting Started +=============== + +First, read the DRM documentation at Documentation/gpu/index.rst. +Not only it will explain how to write a new DRM driver but it will also +contain all the information on how to contribute, the Code Of Conduct and +what is the coding style/documentation. All of that is the same for the +accel subsystem. + +Second, make sure the kernel is configured with CONFIG_DRM_ACCEL. + +To expose your device as an accelerator, two changes are needed to +be done in your driver (as opposed to a standard DRM driver): + +- Add the DRIVER_COMPUTE_ACCEL feature flag in your drm_driver's + driver_features field. It is important to note that this driver feature is + mutually exclusive with DRIVER_RENDER and DRIVER_MODESET. Devices that want + to expose both graphics and compute device char files should be handled by + two drivers that are connected using the auxiliary bus framework. + +- Change the open callback in your driver fops structure to accel_open(). + Alternatively, your driver can use DEFINE_DRM_ACCEL_FOPS macro to easily + set the correct function operations pointers structure. + +External References +=================== + +email threads +------------- + +* `Initial discussion on the New subsystem for acceleration devices <https://lkml.org/lkml/2022/7/31/83>`_ - Oded Gabbay (2022) +* `patch-set to add the new subsystem <https://lkml.org/lkml/2022/10/22/544>`_ - Oded Gabbay (2022) + +Conference talks +---------------- + +* `LPC 2022 Accelerators BOF outcomes summary <https://airlied.blogspot.com/2022/09/accelerators-bof-outcomes-summary.html>`_ - Dave Airlie (2022) diff --git a/Documentation/admin-guide/blockdev/zram.rst b/Documentation/admin-guide/blockdev/zram.rst index c73b16930449..e4551579cb12 100644 --- a/Documentation/admin-guide/blockdev/zram.rst +++ b/Documentation/admin-guide/blockdev/zram.rst @@ -348,8 +348,13 @@ this can be accomplished with:: echo huge_idle > /sys/block/zramX/writeback +If a user chooses to writeback only incompressible pages (pages that none of +algorithms can compress) this can be accomplished with:: + + echo incompressible > /sys/block/zramX/writeback + If an admin wants to write a specific page in zram device to the backing device, -they could write a page index into the interface. +they could write a page index into the interface:: echo "page_index=1251" > /sys/block/zramX/writeback @@ -401,6 +406,87 @@ budget in next setting is user's job. If admin wants to measure writeback count in a certain period, they could know it via /sys/block/zram0/bd_stat's 3rd column. +recompression +------------- + +With CONFIG_ZRAM_MULTI_COMP, zram can recompress pages using alternative +(secondary) compression algorithms. The basic idea is that alternative +compression algorithm can provide better compression ratio at a price of +(potentially) slower compression/decompression speeds. Alternative compression +algorithm can, for example, be more successful compressing huge pages (those +that default algorithm failed to compress). Another application is idle pages +recompression - pages that are cold and sit in the memory can be recompressed +using more effective algorithm and, hence, reduce zsmalloc memory usage. + +With CONFIG_ZRAM_MULTI_COMP, zram supports up to 4 compression algorithms: +one primary and up to 3 secondary ones. Primary zram compressor is explained +in "3) Select compression algorithm", secondary algorithms are configured +using recomp_algorithm device attribute. + +Example::: + + #show supported recompression algorithms + cat /sys/block/zramX/recomp_algorithm + #1: lzo lzo-rle lz4 lz4hc [zstd] + #2: lzo lzo-rle lz4 [lz4hc] zstd + +Alternative compression algorithms are sorted by priority. In the example +above, zstd is used as the first alternative algorithm, which has priority +of 1, while lz4hc is configured as a compression algorithm with priority 2. +Alternative compression algorithm's priority is provided during algorithms +configuration::: + + #select zstd recompression algorithm, priority 1 + echo "algo=zstd priority=1" > /sys/block/zramX/recomp_algorithm + + #select deflate recompression algorithm, priority 2 + echo "algo=deflate priority=2" > /sys/block/zramX/recomp_algorithm + +Another device attribute that CONFIG_ZRAM_MULTI_COMP enables is recompress, +which controls recompression. + +Examples::: + + #IDLE pages recompression is activated by `idle` mode + echo "type=idle" > /sys/block/zramX/recompress + + #HUGE pages recompression is activated by `huge` mode + echo "type=huge" > /sys/block/zram0/recompress + + #HUGE_IDLE pages recompression is activated by `huge_idle` mode + echo "type=huge_idle" > /sys/block/zramX/recompress + +The number of idle pages can be significant, so user-space can pass a size +threshold (in bytes) to the recompress knob: zram will recompress only pages +of equal or greater size::: + + #recompress all pages larger than 3000 bytes + echo "threshold=3000" > /sys/block/zramX/recompress + + #recompress idle pages larger than 2000 bytes + echo "type=idle threshold=2000" > /sys/block/zramX/recompress + +Recompression of idle pages requires memory tracking. + +During re-compression for every page, that matches re-compression criteria, +ZRAM iterates the list of registered alternative compression algorithms in +order of their priorities. ZRAM stops either when re-compression was +successful (re-compressed object is smaller in size than the original one) +and matches re-compression criteria (e.g. size threshold) or when there are +no secondary algorithms left to try. If none of the secondary algorithms can +successfully re-compressed the page such a page is marked as incompressible, +so ZRAM will not attempt to re-compress it in the future. + +This re-compression behaviour, when it iterates through the list of +registered compression algorithms, increases our chances of finding the +algorithm that successfully compresses a particular page. Sometimes, however, +it is convenient (and sometimes even necessary) to limit recompression to +only one particular algorithm so that it will not try any other algorithms. +This can be achieved by providing a algo=NAME parameter::: + + #use zstd algorithm only (if registered) + echo "type=huge algo=zstd" > /sys/block/zramX/recompress + memory tracking =============== @@ -411,9 +497,11 @@ pages of the process with*pagemap. If you enable the feature, you could see block state via /sys/kernel/debug/zram/zram0/block_state". The output is as follows:: - 300 75.033841 .wh. - 301 63.806904 s... - 302 63.806919 ..hi + 300 75.033841 .wh... + 301 63.806904 s..... + 302 63.806919 ..hi.. + 303 62.801919 ....r. + 304 146.781902 ..hi.n First column zram's block index. @@ -430,6 +518,10 @@ Third column huge page i: idle page + r: + recompressed page (secondary compression algorithm) + n: + none (including secondary) of algorithms could compress it First line of above example says 300th block is accessed at 75.033841sec and the block's state is huge so it is written back to the backing diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst index d99994345d41..9355c525fbe0 100644 --- a/Documentation/admin-guide/bootconfig.rst +++ b/Documentation/admin-guide/bootconfig.rst @@ -229,7 +229,7 @@ In addition to the kernel command line, the boot config can be used for passing the kernel parameters. All the key-value pairs under ``kernel`` key will be passed to kernel cmdline directly. Moreover, the key-value pairs under ``init`` will be passed to init process via the cmdline. -The parameters are concatinated with user-given kernel cmdline string +The parameters are concatenated with user-given kernel cmdline string as the following order, so that the command line parameter can override bootconfig parameters (this depends on how the subsystem handles parameters but in general, earlier parameter will be overwritten by later one.):: diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst index 5b86245450bd..60370f2c67b9 100644 --- a/Documentation/admin-guide/cgroup-v1/memory.rst +++ b/Documentation/admin-guide/cgroup-v1/memory.rst @@ -543,7 +543,8 @@ 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 on inactive 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). =============== =============================================================== diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index dc254a3cb956..c8ae7c897f14 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -1245,17 +1245,13 @@ PAGE_SIZE multiple when read back. This is a simple interface to trigger memory reclaim in the target cgroup. - This file accepts a single key, the number of bytes to reclaim. - No nested keys are currently supported. + This file accepts a string which contains the number of bytes to + reclaim. 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. @@ -1267,6 +1263,13 @@ 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. @@ -1488,12 +1491,18 @@ PAGE_SIZE multiple when read back. pgscan_direct (npn) Amount of scanned pages directly (in an inactive LRU list) + pgscan_khugepaged (npn) + Amount of scanned pages by khugepaged (in an inactive LRU list) + pgsteal_kswapd (npn) Amount of reclaimed pages by kswapd pgsteal_direct (npn) Amount of reclaimed pages directly + pgsteal_khugepaged (npn) + Amount of reclaimed pages by khugepaged + pgfault (npn) Total number of page faults incurred diff --git a/Documentation/admin-guide/device-mapper/dm-init.rst b/Documentation/admin-guide/device-mapper/dm-init.rst index e5242ff17e9b..981d6a907699 100644 --- a/Documentation/admin-guide/device-mapper/dm-init.rst +++ b/Documentation/admin-guide/device-mapper/dm-init.rst @@ -123,3 +123,11 @@ Other examples (per target): 0 1638400 verity 1 8:1 8:2 4096 4096 204800 1 sha256 fb1a5a0f00deb908d8b53cb270858975e76cf64105d412ce764225d53b8f3cfd 51934789604d1b92399c52e7cb149d1b3a1b74bbbcb103b2a0aaacbed5c08584 + +For setups using device-mapper on top of asynchronously probed block +devices (MMC, USB, ..), it may be necessary to tell dm-init to +explicitly wait for them to become available before setting up the +device-mapper tables. This can be done with the "dm-mod.waitfor=" +module parameter, which takes a list of devices to wait for:: + + dm-mod.waitfor=<device1>[,..,<deviceN>] diff --git a/Documentation/admin-guide/devices.txt b/Documentation/admin-guide/devices.txt index 9764d6edb189..06c525e01ea5 100644 --- a/Documentation/admin-guide/devices.txt +++ b/Documentation/admin-guide/devices.txt @@ -3080,6 +3080,11 @@ ... 255 = /dev/osd255 256th OSD Device + 261 char Compute Acceleration Devices + 0 = /dev/accel/accel0 First acceleration device + 1 = /dev/accel/accel1 Second acceleration device + ... + 384-511 char RESERVED FOR DYNAMIC ASSIGNMENT Character devices that request a dynamic allocation of major number will take numbers starting from 511 and downward, diff --git a/Documentation/admin-guide/hw_random.rst b/Documentation/admin-guide/hw_random.rst index 121de96e395e..d494601717f1 100644 --- a/Documentation/admin-guide/hw_random.rst +++ b/Documentation/admin-guide/hw_random.rst @@ -1,6 +1,6 @@ -========================================================== -Linux support for random number generator in i8xx chipsets -========================================================== +================================= +Hardware random number generators +================================= Introduction ============ diff --git a/Documentation/admin-guide/kdump/vmcoreinfo.rst b/Documentation/admin-guide/kdump/vmcoreinfo.rst index 6726f439958c..86fd88492870 100644 --- a/Documentation/admin-guide/kdump/vmcoreinfo.rst +++ b/Documentation/admin-guide/kdump/vmcoreinfo.rst @@ -595,3 +595,32 @@ X2TLB ----- Indicates whether the crashed kernel enabled SH extended mode. + +RISCV64 +======= + +VA_BITS +------- + +The maximum number of bits for virtual addresses. Used to compute the +virtual memory ranges. + +PAGE_OFFSET +----------- + +Indicates the virtual kernel start address of the direct-mapped RAM region. + +phys_ram_base +------------- + +Indicates the start physical RAM address. + +MODULES_VADDR|MODULES_END|VMALLOC_START|VMALLOC_END|VMEMMAP_START|VMEMMAP_END|KERNEL_LINK_ADDR +---------------------------------------------------------------------------------------------- + +Used to get the correct ranges: + + * MODULES_VADDR ~ MODULES_END : Kernel module space. + * VMALLOC_START ~ VMALLOC_END : vmalloc() / ioremap() space. + * VMEMMAP_START ~ VMEMMAP_END : vmemmap space, used for struct page array. + * KERNEL_LINK_ADDR : start address of Kernel link and BPF diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index a465d5242774..fb388c6c8c60 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -703,6 +703,17 @@ condev= [HW,S390] console device conmode= + con3215_drop= [S390] 3215 console drop mode. + Format: y|n|Y|N|1|0 + When set to true, drop data on the 3215 console when + the console buffer is full. In this case the + operator using a 3270 terminal emulator (for example + x3270) does not have to enter the clear key for the + console output to advance and the kernel to continue. + This leads to a much faster boot time when a 3270 + terminal emulator is active. If no 3270 terminal + emulator is used, this parameter has no effect. + console= [KNL] Output console device and options. tty<n> Use the virtual console device <n>. @@ -831,7 +842,7 @@ memory region [offset, offset + size] for that kernel image. If '@offset' is omitted, then a suitable offset is selected automatically. - [KNL, X86-64] Select a region under 4G first, and + [KNL, X86-64, ARM64] Select a region under 4G first, and fall back to reserve region above 4G when '@offset' hasn't been specified. See Documentation/admin-guide/kdump/kdump.rst for further details. @@ -851,26 +862,23 @@ available. It will be ignored if crashkernel=X is specified. crashkernel=size[KMG],low - [KNL, X86-64] range under 4G. When crashkernel=X,high + [KNL, X86-64, ARM64] range under 4G. When crashkernel=X,high is passed, kernel could allocate physical memory region above 4G, that cause second kernel crash on system that require some amount of low memory, e.g. swiotlb requires at least 64M+32K low memory, also enough extra low memory is needed to make sure DMA buffers for 32-bit devices won't run out. Kernel would try to allocate - at least 256M below 4G automatically. + default size of memory below 4G automatically. The default + size is platform dependent. + --> x86: max(swiotlb_size_or_default() + 8MiB, 256MiB) + --> arm64: 128MiB This one lets the user specify own low range under 4G for second kernel instead. 0: to disable low allocation. It will be ignored when crashkernel=X,high is not used or memory reserved is below 4G. - [KNL, ARM64] range in low memory. - This one lets the user specify a low range in the - DMA zone for the crash dump kernel. - It will be ignored when crashkernel=X,high is not used - or memory reserved is located in the DMA zones. - cryptomgr.notests [KNL] Disable crypto self-tests @@ -3777,12 +3785,15 @@ shutdown the other cpus. Instead use the REBOOT_VECTOR irq. - nomodeset Disable kernel modesetting. DRM drivers will not perform - display-mode changes or accelerated rendering. Only the - system framebuffer will be available for use if this was - set-up by the firmware or boot loader. + nomodeset Disable kernel modesetting. Most systems' firmware + sets up a display mode and provides framebuffer memory + for output. With nomodeset, DRM and fbdev drivers will + not load if they could possibly displace the pre- + initialized output. Only the system framebuffer will + be available for use. The respective drivers will not + perform display-mode changes or accelerated rendering. - Useful as fallback, or for testing and debugging. + Useful as error fallback, or for testing and debugging. nomodule Disable module load @@ -4566,17 +4577,15 @@ ramdisk_start= [RAM] RAM disk image start address - random.trust_cpu={on,off} - [KNL] Enable or disable trusting the use of the - CPU's random number generator (if available) to - fully seed the kernel's CRNG. Default is controlled - by CONFIG_RANDOM_TRUST_CPU. + random.trust_cpu=off + [KNL] Disable trusting the use of the CPU's + random number generator (if available) to + initialize the kernel's RNG. - random.trust_bootloader={on,off} - [KNL] Enable or disable trusting the use of a - seed passed by the bootloader (if available) to - fully seed the kernel's CRNG. Default is controlled - by CONFIG_RANDOM_TRUST_BOOTLOADER. + random.trust_bootloader=off + [KNL] Disable trusting the use of the a seed + passed by the bootloader (if available) to + initialize the kernel's RNG. randomize_kstack_offset= [KNL] Enable or disable kernel stack offset @@ -6959,3 +6968,14 @@ memory, and other data can't be written using xmon commands. off xmon is disabled. + + amd_pstate= [X86] + disable + Do not enable amd_pstate as the default + scaling driver for the supported processors + passive + Use amd_pstate as a scaling driver, driver requests a + desired performance on this abstract scale and the power + management firmware translates the requests into actual + hardware states (core frequency, data fabric and memory + clocks etc.) diff --git a/Documentation/admin-guide/media/cec-drivers.rst b/Documentation/admin-guide/media/cec-drivers.rst deleted file mode 100644 index 8d9686c08df9..000000000000 --- a/Documentation/admin-guide/media/cec-drivers.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -================================= -CEC driver-specific documentation -================================= - -.. toctree:: - :maxdepth: 2 - - pulse8-cec diff --git a/Documentation/admin-guide/media/cec.rst b/Documentation/admin-guide/media/cec.rst new file mode 100644 index 000000000000..5c7259371494 --- /dev/null +++ b/Documentation/admin-guide/media/cec.rst @@ -0,0 +1,369 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======== +HDMI CEC +======== + +Supported hardware in mainline +============================== + +HDMI Transmitters: + +- Exynos4 +- Exynos5 +- STIH4xx HDMI CEC +- V4L2 adv7511 (same HW, but a different driver from the drm adv7511) +- stm32 +- Allwinner A10 (sun4i) +- Raspberry Pi +- dw-hdmi (Synopsis IP) +- amlogic (meson ao-cec and ao-cec-g12a) +- drm adv7511/adv7533 +- omap4 +- tegra +- rk3288, rk3399 +- tda998x +- DisplayPort CEC-Tunneling-over-AUX on i915, nouveau and amdgpu +- ChromeOS EC CEC +- CEC for SECO boards (UDOO x86). +- Chrontel CH7322 + + +HDMI Receivers: + +- adv7604/11/12 +- adv7842 +- tc358743 + +USB Dongles (see below for additional information on how to use these +dongles): + +- Pulse-Eight: the pulse8-cec driver implements the following module option: + ``persistent_config``: by default this is off, but when set to 1 the driver + will store the current settings to the device's internal eeprom and restore + it the next time the device is connected to the USB port. +- RainShadow Tech. Note: this driver does not support the persistent_config + module option of the Pulse-Eight driver. The hardware supports it, but I + have no plans to add this feature. But I accept patches :-) + +Miscellaneous: + +- vivid: emulates a CEC receiver and CEC transmitter. + Can be used to test CEC applications without actual CEC hardware. + +- cec-gpio. If the CEC pin is hooked up to a GPIO pin then + you can control the CEC line through this driver. This supports error + injection as well. + + +Utilities +========= + +Utilities are available here: https://git.linuxtv.org/v4l-utils.git + +``utils/cec-ctl``: control a CEC device + +``utils/cec-compliance``: test compliance of a remote CEC device + +``utils/cec-follower``: emulate a CEC follower device + +Note that ``cec-ctl`` has support for the CEC Hospitality Profile as is +used in some hotel displays. See http://www.htng.org. + +Note that the libcec library (https://github.com/Pulse-Eight/libcec) supports +the linux CEC framework. + +If you want to get the CEC specification, then look at the References of +the HDMI wikipedia page: https://en.wikipedia.org/wiki/HDMI. CEC is part +of the HDMI specification. HDMI 1.3 is freely available (very similar to +HDMI 1.4 w.r.t. CEC) and should be good enough for most things. + + +DisplayPort to HDMI Adapters with working CEC +============================================= + +Background: most adapters do not support the CEC Tunneling feature, +and of those that do many did not actually connect the CEC pin. +Unfortunately, this means that while a CEC device is created, it +is actually all alone in the world and will never be able to see other +CEC devices. + +This is a list of known working adapters that have CEC Tunneling AND +that properly connected the CEC pin. If you find adapters that work +but are not in this list, then drop me a note. + +To test: hook up your DP-to-HDMI adapter to a CEC capable device +(typically a TV), then run:: + + cec-ctl --playback # Configure the PC as a CEC Playback device + cec-ctl -S # Show the CEC topology + +The ``cec-ctl -S`` command should show at least two CEC devices, +ourselves and the CEC device you are connected to (i.e. typically the TV). + +General note: I have only seen this work with the Parade PS175, PS176 and +PS186 chipsets and the MegaChips 2900. While MegaChips 28x0 claims CEC support, +I have never seen it work. + +USB-C to HDMI +------------- + +Samsung Multiport Adapter EE-PW700: https://www.samsung.com/ie/support/model/EE-PW700BBEGWW/ + +Kramer ADC-U31C/HF: https://www.kramerav.com/product/ADC-U31C/HF + +Club3D CAC-2504: https://www.club-3d.com/en/detail/2449/usb_3.1_type_c_to_hdmi_2.0_uhd_4k_60hz_active_adapter/ + +DisplayPort to HDMI +------------------- + +Club3D CAC-1080: https://www.club-3d.com/en/detail/2442/displayport_1.4_to_hdmi_2.0b_hdr/ + +CableCreation (SKU: CD0712): https://www.cablecreation.com/products/active-displayport-to-hdmi-adapter-4k-hdr + +HP DisplayPort to HDMI True 4k Adapter (P/N 2JA63AA): https://www.hp.com/us-en/shop/pdp/hp-displayport-to-hdmi-true-4k-adapter + +Mini-DisplayPort to HDMI +------------------------ + +Club3D CAC-1180: https://www.club-3d.com/en/detail/2443/mini_displayport_1.4_to_hdmi_2.0b_hdr/ + +Note that passive adapters will never work, you need an active adapter. + +The Club3D adapters in this list are all MegaChips 2900 based. Other Club3D adapters +are PS176 based and do NOT have the CEC pin hooked up, so only the three Club3D +adapters above are known to work. + +I suspect that MegaChips 2900 based designs in general are likely to work +whereas with the PS176 it is more hit-and-miss (mostly miss). The PS186 is +likely to have the CEC pin hooked up, it looks like they changed the reference +design for that chipset. + + +USB CEC Dongles +=============== + +These dongles appear as ``/dev/ttyACMX`` devices and need the ``inputattach`` +utility to create the ``/dev/cecX`` devices. Support for the Pulse-Eight +has been added to ``inputattach`` 1.6.0. Support for the Rainshadow Tech has +been added to ``inputattach`` 1.6.1. + +You also need udev rules to automatically start systemd services:: + + SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="2548", ATTRS{idProduct}=="1002", ACTION=="add", TAG+="systemd", ENV{SYSTEMD_WANTS}+="pulse8-cec-inputattach@%k.service" + SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="2548", ATTRS{idProduct}=="1001", ACTION=="add", TAG+="systemd", ENV{SYSTEMD_WANTS}+="pulse8-cec-inputattach@%k.service" + SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="ff59", ACTION=="add", TAG+="systemd", ENV{SYSTEMD_WANTS}+="rainshadow-cec-inputattach@%k.service" + +and these systemd services: + +For Pulse-Eight make /lib/systemd/system/pulse8-cec-inputattach@.service:: + + [Unit] + Description=inputattach for pulse8-cec device on %I + + [Service] + Type=simple + ExecStart=/usr/bin/inputattach --pulse8-cec /dev/%I + +For the RainShadow Tech make /lib/systemd/system/rainshadow-cec-inputattach@.service:: + + [Unit] + Description=inputattach for rainshadow-cec device on %I + + [Service] + Type=simple + ExecStart=/usr/bin/inputattach --rainshadow-cec /dev/%I + + +For proper suspend/resume support create: /lib/systemd/system/restart-cec-inputattach.service:: + + [Unit] + Description=restart inputattach for cec devices + After=suspend.target + + [Service] + Type=forking + ExecStart=/bin/bash -c 'for d in /dev/serial/by-id/usb-Pulse-Eight*; do /usr/bin/inputattach --daemon --pulse8-cec $d; done; for d in /dev/serial/by-id/usb-RainShadow_Tech*; do /usr/bin/inputattach --daemon --rainshadow-cec $d; done' + + [Install] + WantedBy=suspend.target + +And run ``systemctl enable restart-cec-inputattach``. + +To automatically set the physical address of the CEC device whenever the +EDID changes, you can use ``cec-ctl`` with the ``-E`` option:: + + cec-ctl -E /sys/class/drm/card0-DP-1/edid + +This assumes the dongle is connected to the card0-DP-1 output (``xrandr`` will tell +you which output is used) and it will poll for changes to the EDID and update +the Physical Address whenever they occur. + +To automatically run this command you can use cron. Edit crontab with +``crontab -e`` and add this line:: + + @reboot /usr/local/bin/cec-ctl -E /sys/class/drm/card0-DP-1/edid + +This only works for display drivers that expose the EDID in ``/sys/class/drm``, +such as the i915 driver. + + +CEC Without HPD +=============== + +Some displays when in standby mode have no HDMI Hotplug Detect signal, but +CEC is still enabled so connected devices can send an <Image View On> CEC +message in order to wake up such displays. Unfortunately, not all CEC +adapters can support this. An example is the Odroid-U3 SBC that has a +level-shifter that is powered off when the HPD signal is low, thus +blocking the CEC pin. Even though the SoC can use CEC without a HPD, +the level-shifter will prevent this from functioning. + +There is a CEC capability flag to signal this: ``CEC_CAP_NEEDS_HPD``. +If set, then the hardware cannot wake up displays with this behavior. + +Note for CEC application implementers: the <Image View On> message must +be the first message you send, don't send any other messages before. +Certain very bad but unfortunately not uncommon CEC implementations +get very confused if they receive anything else but this message and +they won't wake up. + +When writing a driver it can be tricky to test this. There are two +ways to do this: + +1) Get a Pulse-Eight USB CEC dongle, connect an HDMI cable from your + device to the Pulse-Eight, but do not connect the Pulse-Eight to + the display. + + Now configure the Pulse-Eight dongle:: + + cec-ctl -p0.0.0.0 --tv + + and start monitoring:: + + sudo cec-ctl -M + + On the device you are testing run:: + + cec-ctl --playback + + It should report a physical address of f.f.f.f. Now run this + command:: + + cec-ctl -t0 --image-view-on + + The Pulse-Eight should see the <Image View On> message. If not, + then something (hardware and/or software) is preventing the CEC + message from going out. + + To make sure you have the wiring correct just connect the + Pulse-Eight to a CEC-enabled display and run the same command + on your device: now there is a HPD, so you should see the command + arriving at the Pulse-Eight. + +2) If you have another linux device supporting CEC without HPD, then + you can just connect your device to that device. Yes, you can connect + two HDMI outputs together. You won't have a HPD (which is what we + want for this test), but the second device can monitor the CEC pin. + + Otherwise use the same commands as in 1. + +If CEC messages do not come through when there is no HPD, then you +need to figure out why. Typically it is either a hardware restriction +or the software powers off the CEC core when the HPD goes low. The +first cannot be corrected of course, the second will likely required +driver changes. + + +Microcontrollers & CEC +====================== + +We have seen some CEC implementations in displays that use a microcontroller +to sample the bus. This does not have to be a problem, but some implementations +have timing issues. This is hard to discover unless you can hook up a low-level +CEC debugger (see the next section). + +You will see cases where the CEC transmitter holds the CEC line high or low for +a longer time than is allowed. For directed messages this is not a problem since +if that happens the message will not be Acked and it will be retransmitted. +For broadcast messages no such mechanism exists. + +It's not clear what to do about this. It is probably wise to transmit some +broadcast messages twice to reduce the chance of them being lost. Specifically +<Standby> and <Active Source> are candidates for that. + + +Making a CEC debugger +===================== + +By using a Raspberry Pi 2B/3/4 and some cheap components you can make +your own low-level CEC debugger. + +Here is a picture of my setup: + +https://hverkuil.home.xs4all.nl/rpi3-cec.jpg + +It's a Raspberry Pi 3 together with a breadboard and some breadboard wires: + +http://www.dx.com/p/diy-40p-male-to-female-male-to-male-female-to-female-dupont-line-wire-3pcs-356089#.WYLOOXWGN7I + +Finally on of these HDMI female-female passthrough connectors (full soldering type 1): + +https://elabbay.myshopify.com/collections/camera/products/hdmi-af-af-v1a-hdmi-type-a-female-to-hdmi-type-a-female-pass-through-adapter-breakout-board?variant=45533926147 + +We've tested this and it works up to 4kp30 (297 MHz). The quality is not high +enough to pass-through 4kp60 (594 MHz). + +I also added an RTC and a breakout shield: + +https://www.amazon.com/Makerfire%C2%AE-Raspberry-Module-DS1307-Battery/dp/B00ZOXWHK4 + +https://www.dx.com/p/raspberry-pi-gpio-expansion-board-breadboard-easy-multiplexing-board-one-to-three-with-screw-for-raspberry-pi-2-3-b-b-2729992.html#.YGRCG0MzZ7I + +These two are not needed but they make life a bit easier. + +If you want to monitor the HPD line as well, then you need one of these +level shifters: + +https://www.adafruit.com/product/757 + +(This is just where I got these components, there are many other places you +can get similar things). + +The CEC pin of the HDMI connector needs to be connected to these pins: +CE0/IO8 and CE1/IO7 (pull-up GPIOs). The (optional) HPD pin of the HDMI +connector should be connected (via a level shifter to convert the 5V +to 3.3V) to these pins: IO17 and IO27. The (optional) 5V pin of the HDMI +connector should be connected (via a level shifter) to these pins: IO22 +and IO24. Monitoring the HPD an 5V lines is not necessary, but it is helpful. + +This kernel patch will hook up the cec-gpio driver correctly to +e.g. ``arch/arm/boot/dts/bcm2837-rpi-3-b-plus.dts``:: + + cec-gpio@7 { + compatible = "cec-gpio"; + cec-gpios = <&gpio 7 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>; + hpd-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>; + v5-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>; + }; + + cec-gpio@8 { + compatible = "cec-gpio"; + cec-gpios = <&gpio 8 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>; + hpd-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>; + v5-gpios = <&gpio 24 GPIO_ACTIVE_HIGH>; + }; + +This dts change will enable two cec GPIO devices: I typically use one to +send/receive CEC commands and the other to monitor. If you monitor using +an unconfigured CEC adapter then it will use GPIO interrupts which makes +monitoring very accurate. + +The documentation on how to use the error injection is here: :ref:`cec_pin_error_inj`. + +``cec-ctl --monitor-pin`` will do low-level CEC bus sniffing and analysis. +You can also store the CEC traffic to file using ``--store-pin`` and analyze +it later using ``--analyze-pin``. + +You can also use this as a full-fledged CEC device by configuring it +using ``cec-ctl --tv -p0.0.0.0`` or ``cec-ctl --playback -p1.0.0.0``. diff --git a/Documentation/admin-guide/media/index.rst b/Documentation/admin-guide/media/index.rst index c676af665111..43f4a292b245 100644 --- a/Documentation/admin-guide/media/index.rst +++ b/Documentation/admin-guide/media/index.rst @@ -38,13 +38,14 @@ The media subsystem remote-controller + cec + dvb cardlist v4l-drivers dvb-drivers - cec-drivers **Copyright** |copy| 1999-2020 : LinuxTV Developers diff --git a/Documentation/admin-guide/media/pulse8-cec.rst b/Documentation/admin-guide/media/pulse8-cec.rst deleted file mode 100644 index 356d08b519f3..000000000000 --- a/Documentation/admin-guide/media/pulse8-cec.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -Pulse-Eight CEC Adapter driver -============================== - -The pulse8-cec driver implements the following module option: - -``persistent_config`` ---------------------- - -By default this is off, but when set to 1 the driver will store the current -settings to the device's internal eeprom and restore it the next time the -device is connected to the USB port. diff --git a/Documentation/admin-guide/media/v4l-drivers.rst b/Documentation/admin-guide/media/v4l-drivers.rst index 9c7ebe2ca3bd..90a026ee05c6 100644 --- a/Documentation/admin-guide/media/v4l-drivers.rst +++ b/Documentation/admin-guide/media/v4l-drivers.rst @@ -31,4 +31,5 @@ Video4Linux (V4L) driver-specific documentation si4713 si476x vimc + visl vivid diff --git a/Documentation/admin-guide/media/vimc.rst b/Documentation/admin-guide/media/vimc.rst index 3b4d2b36b4f3..29d843a8ddb1 100644 --- a/Documentation/admin-guide/media/vimc.rst +++ b/Documentation/admin-guide/media/vimc.rst @@ -35,11 +35,11 @@ of commands fits for the default topology: media-ctl -d platform:vimc -V '"Sensor A":0[fmt:SBGGR8_1X8/640x480]' media-ctl -d platform:vimc -V '"Debayer A":0[fmt:SBGGR8_1X8/640x480]' - media-ctl -d platform:vimc -V '"Sensor B":0[fmt:SBGGR8_1X8/640x480]' - media-ctl -d platform:vimc -V '"Debayer B":0[fmt:SBGGR8_1X8/640x480]' - v4l2-ctl -z platform:vimc -d "RGB/YUV Capture" -v width=1920,height=1440 + media-ctl -d platform:vimc -V '"Scaler":0[fmt:RGB888_1X24/640x480]' + media-ctl -d platform:vimc -V '"Scaler":0[crop:(100,50)/400x150]' + media-ctl -d platform:vimc -V '"Scaler":1[fmt:RGB888_1X24/300x700]' + v4l2-ctl -z platform:vimc -d "RGB/YUV Capture" -v width=300,height=700 v4l2-ctl -z platform:vimc -d "Raw Capture 0" -v pixelformat=BA81 - v4l2-ctl -z platform:vimc -d "Raw Capture 1" -v pixelformat=BA81 Subdevices ---------- diff --git a/Documentation/admin-guide/media/visl.rst b/Documentation/admin-guide/media/visl.rst new file mode 100644 index 000000000000..7d2dc78341c9 --- /dev/null +++ b/Documentation/admin-guide/media/visl.rst @@ -0,0 +1,175 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The Virtual Stateless Decoder Driver (visl) +=========================================== + +A virtual stateless decoder device for stateless uAPI development +purposes. + +This tool's objective is to help the development and testing of +userspace applications that use the V4L2 stateless API to decode media. + +A userspace implementation can use visl to run a decoding loop even when +no hardware is available or when the kernel uAPI for the codec has not +been upstreamed yet. This can reveal bugs at an early stage. + +This driver can also trace the contents of the V4L2 controls submitted +to it. It can also dump the contents of the vb2 buffers through a +debugfs interface. This is in many ways similar to the tracing +infrastructure available for other popular encode/decode APIs out there +and can help develop a userspace application by using another (working) +one as a reference. + +.. note:: + + No actual decoding of video frames is performed by visl. The + V4L2 test pattern generator is used to write various debug information + to the capture buffers instead. + +Module parameters +----------------- + +- visl_debug: Activates debug info, printing various debug messages through + dprintk. Also controls whether per-frame debug info is shown. Defaults to off. + Note that enabling this feature can result in slow performance through serial. + +- visl_transtime_ms: Simulated process time in milliseconds. Slowing down the + decoding speed can be useful for debugging. + +- visl_dprintk_frame_start, visl_dprintk_frame_nframes: Dictates a range of + frames where dprintk is activated. This only controls the dprintk tracing on a + per-frame basis. Note that printing a lot of data can be slow through serial. + +- keep_bitstream_buffers: Controls whether bitstream (i.e. OUTPUT) buffers are + kept after a decoding session. Defaults to false so as to reduce the amount of + clutter. keep_bitstream_buffers == false works well when live debugging the + client program with GDB. + +- bitstream_trace_frame_start, bitstream_trace_nframes: Similar to + visl_dprintk_frame_start, visl_dprintk_nframes, but controls the dumping of + buffer data through debugfs instead. + +What is the default use case for this driver? +--------------------------------------------- + +This driver can be used as a way to compare different userspace implementations. +This assumes that a working client is run against visl and that the ftrace and +OUTPUT buffer data is subsequently used to debug a work-in-progress +implementation. + +Information on reference frames, their timestamps, the status of the OUTPUT and +CAPTURE queues and more can be read directly from the CAPTURE buffers. + +Supported codecs +---------------- + +The following codecs are supported: + +- FWHT +- MPEG2 +- VP8 +- VP9 +- H.264 +- HEVC + +visl trace events +----------------- +The trace events are defined on a per-codec basis, e.g.: + +.. code-block:: bash + + $ ls /sys/kernel/debug/tracing/events/ | grep visl + visl_fwht_controls + visl_h264_controls + visl_hevc_controls + visl_mpeg2_controls + visl_vp8_controls + visl_vp9_controls + +For example, in order to dump HEVC SPS data: + +.. code-block:: bash + + $ echo 1 > /sys/kernel/debug/tracing/events/visl_hevc_controls/v4l2_ctrl_hevc_sps/enable + +The SPS data will be dumped to the trace buffer, i.e.: + +.. code-block:: bash + + $ cat /sys/kernel/debug/tracing/trace + video_parameter_set_id 0 + seq_parameter_set_id 0 + pic_width_in_luma_samples 1920 + pic_height_in_luma_samples 1080 + bit_depth_luma_minus8 0 + bit_depth_chroma_minus8 0 + log2_max_pic_order_cnt_lsb_minus4 4 + sps_max_dec_pic_buffering_minus1 6 + sps_max_num_reorder_pics 2 + sps_max_latency_increase_plus1 0 + log2_min_luma_coding_block_size_minus3 0 + log2_diff_max_min_luma_coding_block_size 3 + log2_min_luma_transform_block_size_minus2 0 + log2_diff_max_min_luma_transform_block_size 3 + max_transform_hierarchy_depth_inter 2 + max_transform_hierarchy_depth_intra 2 + pcm_sample_bit_depth_luma_minus1 0 + pcm_sample_bit_depth_chroma_minus1 0 + log2_min_pcm_luma_coding_block_size_minus3 0 + log2_diff_max_min_pcm_luma_coding_block_size 0 + num_short_term_ref_pic_sets 0 + num_long_term_ref_pics_sps 0 + chroma_format_idc 1 + sps_max_sub_layers_minus1 0 + flags AMP_ENABLED|SAMPLE_ADAPTIVE_OFFSET|TEMPORAL_MVP_ENABLED|STRONG_INTRA_SMOOTHING_ENABLED + + +Dumping OUTPUT buffer data through debugfs +------------------------------------------ + +If the **VISL_DEBUGFS** Kconfig is enabled, visl will populate +**/sys/kernel/debug/visl/bitstream** with OUTPUT buffer data according to the +values of bitstream_trace_frame_start and bitstream_trace_nframes. This can +highlight errors as broken clients may fail to fill the buffers properly. + +A single file is created for each processed OUTPUT buffer. Its name contains an +integer that denotes the buffer sequence, i.e.: + +.. code-block:: c + + snprintf(name, 32, "bitstream%d", run->src->sequence); + +Dumping the values is simply a matter of reading from the file, i.e.: + +For the buffer with sequence == 0: + +.. code-block:: bash + + $ xxd /sys/kernel/debug/visl/bitstream/bitstream0 + 00000000: 2601 af04 d088 bc25 a173 0e41 a4f2 3274 &......%.s.A..2t + 00000010: c668 cb28 e775 b4ac f53a ba60 f8fd 3aa1 .h.(.u...:.`..:. + 00000020: 46b4 bcfc 506c e227 2372 e5f5 d7ea 579f F...Pl.'#r....W. + 00000030: 6371 5eb5 0eb8 23b5 ca6a 5de5 983a 19e4 cq^...#..j]..:.. + 00000040: e8c3 4320 b4ba a226 cbc1 4138 3a12 32d6 ..C ...&..A8:.2. + 00000050: fef3 247b 3523 4e90 9682 ac8e eb0c a389 ..${5#N......... + 00000060: ddd0 6cfc 0187 0e20 7aae b15b 1812 3d33 ..l.... z..[..=3 + 00000070: e1c5 f425 a83a 00b7 4f18 8127 3c4c aefb ...%.:..O..'<L.. + +For the buffer with sequence == 1: + +.. code-block:: bash + + $ xxd /sys/kernel/debug/visl/bitstream/bitstream1 + 00000000: 0201 d021 49e1 0c40 aa11 1449 14a6 01dc ...!I..@...I.... + 00000010: 7023 889a c8cd 2cd0 13b4 dab0 e8ca 21fe p#....,.......!. + 00000020: c4c8 ab4c 486e 4e2f b0df 96cc c74e 8dde ...LHnN/.....N.. + 00000030: 8ce7 ee36 d880 4095 4d64 30a0 ff4f 0c5e ...6..@.Md0..O.^ + 00000040: f16b a6a1 d806 ca2a 0ece a673 7bea 1f37 .k.....*...s{..7 + 00000050: 370f 5bb9 1dc4 ba21 6434 bc53 0173 cba0 7.[....!d4.S.s.. + 00000060: dfe6 bc99 01ea b6e0 346b 92b5 c8de 9f5d ........4k.....] + 00000070: e7cc 3484 1769 fef2 a693 a945 2c8b 31da ..4..i.....E,.1. + +And so on. + +By default, the files are removed during STREAMOFF. This is to reduce the amount +of clutter. diff --git a/Documentation/admin-guide/media/vivid.rst b/Documentation/admin-guide/media/vivid.rst index abd90ed31090..672a8371f6ad 100644 --- a/Documentation/admin-guide/media/vivid.rst +++ b/Documentation/admin-guide/media/vivid.rst @@ -392,7 +392,7 @@ Which one is returned depends on the chosen channel, each next valid channel will cycle through the possible audio subchannel combinations. This allows you to test the various combinations by just switching channels.. -Finally, for these inputs the v4l2_timecode struct is filled in in the +Finally, for these inputs the v4l2_timecode struct is filled in the dequeued v4l2_buffer struct. diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst index b47b0cbbd491..1a5b6b71efa1 100644 --- a/Documentation/admin-guide/mm/damon/usage.rst +++ b/Documentation/admin-guide/mm/damon/usage.rst @@ -88,6 +88,9 @@ comma (","). :: │ │ │ │ │ │ │ │ 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 + │ │ │ │ │ │ │ │ ... │ │ │ │ │ │ ... │ │ │ │ ... │ │ ... @@ -125,7 +128,14 @@ in the state. Writing ``commit`` to the ``state`` file makes kdamond reads the user inputs in the sysfs files except ``state`` file again. Writing ``update_schemes_stats`` to ``state`` file updates the contents of stats files for each DAMON-based operation scheme of the kdamond. For details of the -stats, please refer to :ref:`stats section <sysfs_schemes_stats>`. +stats, please refer to :ref:`stats section <sysfs_schemes_stats>`. Writing +``update_schemes_tried_regions`` to ``state`` file updates the DAMON-based +operation scheme action tried regions directory for each DAMON-based operation +scheme of the kdamond. Writing ``clear_schemes_tried_regions`` to ``state`` +file clears the DAMON-based operating scheme action tried regions directory for +each DAMON-based operation scheme of the kdamond. For details of the +DAMON-based operation scheme action tried regions directory, please refer to +:ref:tried_regions section <sysfs_schemes_tried_regions>`. If the state is ``on``, reading ``pid`` shows the pid of the kdamond thread. @@ -166,6 +176,8 @@ You can set and get what type of monitoring operations DAMON will use for the context by writing one of the keywords listed in ``avail_operations`` file and reading from the ``operations`` file. +.. _sysfs_monitoring_attrs: + contexts/<N>/monitoring_attrs/ ------------------------------ @@ -235,6 +247,9 @@ In each region directory, you will find two files (``start`` and ``end``). You can set and get the start and end addresses of the initial monitoring target region by writing to and reading from the files, respectively. +Each region should not overlap with others. ``end`` of directory ``N`` should +be equal or smaller than ``start`` of directory ``N+1``. + contexts/<N>/schemes/ --------------------- @@ -252,8 +267,9 @@ to ``N-1``. Each directory represents each DAMON-based operation scheme. schemes/<N>/ ------------ -In each scheme directory, four directories (``access_pattern``, ``quotas``, -``watermarks``, and ``stats``) and one file (``action``) exist. +In each scheme directory, five directories (``access_pattern``, ``quotas``, +``watermarks``, ``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 @@ -348,6 +364,32 @@ should ask DAMON sysfs interface to updte the content of the files for the stats by writing a special keyword, ``update_schemes_stats`` to the relevant ``kdamonds/<N>/state`` file. +.. _sysfs_schemes_tried_regions: + +schemes/<N>/tried_regions/ +-------------------------- + +When a special keyword, ``update_schemes_tried_regions``, is written to the +relevant ``kdamonds/<N>/state`` file, DAMON creates directories named integer +starting from ``0`` under this directory. Each directory contains files +exposing detailed information about each of the memory region that the +corresponding scheme's ``action`` has tried to be applied under this directory, +during next :ref:`aggregation interval <sysfs_monitoring_attrs>`. The +information includes address range, ``nr_accesses``, , and ``age`` of the +region. + +The directories will be removed when another special keyword, +``clear_schemes_tried_regions``, is written to the relevant +``kdamonds/<N>/state`` file. + +tried_regions/<N>/ +------------------ + +In each region directory, you will find four files (``start``, ``end``, +``nr_accesses``, and ``age``). Reading the files will show the start and end +addresses, ``nr_accesses``, and ``age`` of the region that corresponding +DAMON-based operation scheme ``action`` has tried to be applied. + Example ~~~~~~~ @@ -465,8 +507,9 @@ regions in case of physical memory monitoring. Therefore, users should set the monitoring target regions by themselves. In such cases, users can explicitly set the initial monitoring target regions -as they want, by writing proper values to the ``init_regions`` file. Each line -of the input should represent one region in below form.:: +as they want, by writing proper values to the ``init_regions`` file. The input +should be a sequence of three integers separated by white spaces that represent +one region in below form.:: <target idx> <start address> <end address> @@ -481,9 +524,9 @@ ranges, ``20-40`` and ``50-100`` as that of pid 4242, which is the second one # 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 Note that this sets the initial monitoring target regions only. In case of diff --git a/Documentation/admin-guide/mm/zswap.rst b/Documentation/admin-guide/mm/zswap.rst index 6e6f7b0d6562..f67de481c7f6 100644 --- a/Documentation/admin-guide/mm/zswap.rst +++ b/Documentation/admin-guide/mm/zswap.rst @@ -14,13 +14,7 @@ for potentially reduced swap I/O. This trade-off can also result in a significant performance improvement if reads from the compressed cache are faster than reads from a swap device. -.. note:: - Zswap is a new feature as of v3.11 and interacts heavily with memory - reclaim. This interaction has not been fully explored on the large set of - potential configurations and workloads that exist. For this reason, zswap - is a work in progress and should be considered experimental. - - Some potential benefits: +Some potential benefits: * Desktop/laptop users with limited RAM capacities can mitigate the performance impact of swapping. diff --git a/Documentation/admin-guide/perf/hisi-pcie-pmu.rst b/Documentation/admin-guide/perf/hisi-pcie-pmu.rst index 294ebbdb22af..7e863662e2d4 100644 --- a/Documentation/admin-guide/perf/hisi-pcie-pmu.rst +++ b/Documentation/admin-guide/perf/hisi-pcie-pmu.rst @@ -15,10 +15,10 @@ HiSilicon PCIe PMU driver The PCIe PMU driver registers a perf PMU with the name of its sicl-id and PCIe Core id.:: - /sys/bus/event_source/hisi_pcie<sicl>_<core> + /sys/bus/event_source/hisi_pcie<sicl>_core<core> PMU driver provides description of available events and filter options in sysfs, -see /sys/bus/event_source/devices/hisi_pcie<sicl>_<core>. +see /sys/bus/event_source/devices/hisi_pcie<sicl>_core<core>. The "format" directory describes all formats of the config (events) and config1 (filter options) fields of the perf_event_attr structure. The "events" directory @@ -33,13 +33,13 @@ monitored by PMU. Example usage of perf:: $# perf list - hisi_pcie0_0/rx_mwr_latency/ [kernel PMU event] - hisi_pcie0_0/rx_mwr_cnt/ [kernel PMU event] + hisi_pcie0_core0/rx_mwr_latency/ [kernel PMU event] + hisi_pcie0_core0/rx_mwr_cnt/ [kernel PMU event] ------------------------------------------ - $# perf stat -e hisi_pcie0_0/rx_mwr_latency/ - $# perf stat -e hisi_pcie0_0/rx_mwr_cnt/ - $# perf stat -g -e hisi_pcie0_0/rx_mwr_latency/ -e hisi_pcie0_0/rx_mwr_cnt/ + $# perf stat -e hisi_pcie0_core0/rx_mwr_latency/ + $# perf stat -e hisi_pcie0_core0/rx_mwr_cnt/ + $# perf stat -g -e hisi_pcie0_core0/rx_mwr_latency/ -e hisi_pcie0_core0/rx_mwr_cnt/ The current driver does not support sampling. So "perf record" is unsupported. Also attach to a task is unsupported for PCIe PMU. @@ -48,59 +48,83 @@ Filter options -------------- 1. Target filter -PMU could only monitor the performance of traffic downstream target Root Ports -or downstream target Endpoint. PCIe PMU driver support "port" and "bdf" -interfaces for users, and these two interfaces aren't supported at the same -time. --port -"port" filter can be used in all PCIe PMU events, target Root Port can be -selected by configuring the 16-bits-bitmap "port". Multi ports can be selected -for AP-layer-events, and only one port can be selected for TL/DL-layer-events. + PMU could only monitor the performance of traffic downstream target Root + Ports or downstream target Endpoint. PCIe PMU driver support "port" and + "bdf" interfaces for users, and these two interfaces aren't supported at the + same time. -For example, if target Root Port is 0000:00:00.0 (x8 lanes), bit0 of bitmap -should be set, port=0x1; if target Root Port is 0000:00:04.0 (x4 lanes), -bit8 is set, port=0x100; if these two Root Ports are both monitored, port=0x101. + - port -Example usage of perf:: + "port" filter can be used in all PCIe PMU events, target Root Port can be + selected by configuring the 16-bits-bitmap "port". Multi ports can be + selected for AP-layer-events, and only one port can be selected for + TL/DL-layer-events. - $# perf stat -e hisi_pcie0_0/rx_mwr_latency,port=0x1/ sleep 5 + For example, if target Root Port is 0000:00:00.0 (x8 lanes), bit0 of + bitmap should be set, port=0x1; if target Root Port is 0000:00:04.0 (x4 + lanes), bit8 is set, port=0x100; if these two Root Ports are both + monitored, port=0x101. --bdf + Example usage of perf:: -"bdf" filter can only be used in bandwidth events, target Endpoint is selected -by configuring BDF to "bdf". Counter only counts the bandwidth of message -requested by target Endpoint. + $# perf stat -e hisi_pcie0_core0/rx_mwr_latency,port=0x1/ sleep 5 -For example, "bdf=0x3900" means BDF of target Endpoint is 0000:39:00.0. + - bdf -Example usage of perf:: + "bdf" filter can only be used in bandwidth events, target Endpoint is + selected by configuring BDF to "bdf". Counter only counts the bandwidth of + message requested by target Endpoint. + + For example, "bdf=0x3900" means BDF of target Endpoint is 0000:39:00.0. + + Example usage of perf:: - $# perf stat -e hisi_pcie0_0/rx_mrd_flux,bdf=0x3900/ sleep 5 + $# perf stat -e hisi_pcie0_core0/rx_mrd_flux,bdf=0x3900/ sleep 5 2. Trigger filter -Event statistics start when the first time TLP length is greater/smaller -than trigger condition. You can set the trigger condition by writing "trig_len", -and set the trigger mode by writing "trig_mode". This filter can only be used -in bandwidth events. -For example, "trig_len=4" means trigger condition is 2^4 DW, "trig_mode=0" -means statistics start when TLP length > trigger condition, "trig_mode=1" -means start when TLP length < condition. + Event statistics start when the first time TLP length is greater/smaller + than trigger condition. You can set the trigger condition by writing + "trig_len", and set the trigger mode by writing "trig_mode". This filter can + only be used in bandwidth events. -Example usage of perf:: + For example, "trig_len=4" means trigger condition is 2^4 DW, "trig_mode=0" + means statistics start when TLP length > trigger condition, "trig_mode=1" + means start when TLP length < condition. + + Example usage of perf:: - $# perf stat -e hisi_pcie0_0/rx_mrd_flux,trig_len=0x4,trig_mode=1/ sleep 5 + $# perf stat -e hisi_pcie0_core0/rx_mrd_flux,trig_len=0x4,trig_mode=1/ sleep 5 3. Threshold filter -Counter counts when TLP length within the specified range. You can set the -threshold by writing "thr_len", and set the threshold mode by writing -"thr_mode". This filter can only be used in bandwidth events. -For example, "thr_len=4" means threshold is 2^4 DW, "thr_mode=0" means -counter counts when TLP length >= threshold, and "thr_mode=1" means counts -when TLP length < threshold. + Counter counts when TLP length within the specified range. You can set the + threshold by writing "thr_len", and set the threshold mode by writing + "thr_mode". This filter can only be used in bandwidth events. -Example usage of perf:: + For example, "thr_len=4" means threshold is 2^4 DW, "thr_mode=0" means + counter counts when TLP length >= threshold, and "thr_mode=1" means counts + when TLP length < threshold. + + Example usage of perf:: + + $# perf stat -e hisi_pcie0_core0/rx_mrd_flux,thr_len=0x4,thr_mode=1/ sleep 5 + +4. TLP Length filter + + When counting bandwidth, the data can be composed of certain parts of TLP + packets. You can specify it through "len_mode": + + - 2'b00: Reserved (Do not use this since the behaviour is undefined) + - 2'b01: Bandwidth of TLP payloads + - 2'b10: Bandwidth of TLP headers + - 2'b11: Bandwidth of both TLP payloads and headers + + For example, "len_mode=2" means only counting the bandwidth of TLP headers + and "len_mode=3" means the final bandwidth data is composed of both TLP + headers and payloads. Default value if not specified is 2'b11. + + Example usage of perf:: - $# perf stat -e hisi_pcie0_0/rx_mrd_flux,thr_len=0x4,thr_mode=1/ sleep 5 + $# perf stat -e hisi_pcie0_core0/rx_mrd_flux,len_mode=0x1/ sleep 5 diff --git a/Documentation/admin-guide/perf/index.rst b/Documentation/admin-guide/perf/index.rst index 793e1970bc05..9de64a40adab 100644 --- a/Documentation/admin-guide/perf/index.rst +++ b/Documentation/admin-guide/perf/index.rst @@ -19,3 +19,5 @@ Performance monitor support arm_dsu_pmu thunderx2-pmu alibaba_pmu + nvidia-pmu + meson-ddr-pmu diff --git a/Documentation/admin-guide/perf/meson-ddr-pmu.rst b/Documentation/admin-guide/perf/meson-ddr-pmu.rst new file mode 100644 index 000000000000..8e71be1d6346 --- /dev/null +++ b/Documentation/admin-guide/perf/meson-ddr-pmu.rst @@ -0,0 +1,70 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================================================== +Amlogic SoC DDR Bandwidth Performance Monitoring Unit (PMU) +=========================================================== + +The Amlogic Meson G12 SoC contains a bandwidth monitor inside DRAM controller. +The monitor includes 4 channels. Each channel can count the request accessing +DRAM. The channel can count up to 3 AXI port simultaneously. It can be helpful +to show if the performance bottleneck is on DDR bandwidth. + +Currently, this driver supports the following 5 perf events: + ++ meson_ddr_bw/total_rw_bytes/ ++ meson_ddr_bw/chan_1_rw_bytes/ ++ meson_ddr_bw/chan_2_rw_bytes/ ++ meson_ddr_bw/chan_3_rw_bytes/ ++ meson_ddr_bw/chan_4_rw_bytes/ + +meson_ddr_bw/chan_{1,2,3,4}_rw_bytes/ events are channel-specific events. +Each channel support filtering, which can let the channel to monitor +individual IP module in SoC. + +Below are DDR access request event filter keywords: + ++ arm - from CPU ++ vpu_read1 - from OSD + VPP read ++ gpu - from 3D GPU ++ pcie - from PCIe controller ++ hdcp - from HDCP controller ++ hevc_front - from HEVC codec front end ++ usb3_0 - from USB3.0 controller ++ hevc_back - from HEVC codec back end ++ h265enc - from HEVC encoder ++ vpu_read2 - from DI read ++ vpu_write1 - from VDIN write ++ vpu_write2 - from di write ++ vdec - from legacy codec video decoder ++ hcodec - from H264 encoder ++ ge2d - from ge2d ++ spicc1 - from SPI controller 1 ++ usb0 - from USB2.0 controller 0 ++ dma - from system DMA controller 1 ++ arb0 - from arb0 ++ sd_emmc_b - from SD eMMC b controller ++ usb1 - from USB2.0 controller 1 ++ audio - from Audio module ++ sd_emmc_c - from SD eMMC c controller ++ spicc2 - from SPI controller 2 ++ ethernet - from Ethernet controller + + +Examples: + + + Show the total DDR bandwidth per seconds: + + .. code-block:: bash + + perf stat -a -e meson_ddr_bw/total_rw_bytes/ -I 1000 sleep 10 + + + + Show individual DDR bandwidth from CPU and GPU respectively, as well as + sum of them: + + .. code-block:: bash + + perf stat -a -e meson_ddr_bw/chan_1_rw_bytes,arm=1/ -I 1000 sleep 10 + perf stat -a -e meson_ddr_bw/chan_2_rw_bytes,gpu=1/ -I 1000 sleep 10 + perf stat -a -e meson_ddr_bw/chan_3_rw_bytes,arm=1,gpu=1/ -I 1000 sleep 10 + diff --git a/Documentation/admin-guide/perf/nvidia-pmu.rst b/Documentation/admin-guide/perf/nvidia-pmu.rst new file mode 100644 index 000000000000..2e0d47cfe7ea --- /dev/null +++ b/Documentation/admin-guide/perf/nvidia-pmu.rst @@ -0,0 +1,299 @@ +========================================================= +NVIDIA Tegra SoC Uncore Performance Monitoring Unit (PMU) +========================================================= + +The NVIDIA Tegra SoC includes various system PMUs to measure key performance +metrics like memory bandwidth, latency, and utilization: + +* Scalable Coherency Fabric (SCF) +* NVLink-C2C0 +* NVLink-C2C1 +* CNVLink +* PCIE + +PMU Driver +---------- + +The PMUs in this document are based on ARM CoreSight PMU Architecture as +described in document: ARM IHI 0091. Since this is a standard architecture, the +PMUs are managed by a common driver "arm-cs-arch-pmu". This driver describes +the available events and configuration of each PMU in sysfs. Please see the +sections below to get the sysfs path of each PMU. Like other uncore PMU drivers, +the driver provides "cpumask" sysfs attribute to show the CPU id used to handle +the PMU event. There is also "associated_cpus" sysfs attribute, which contains a +list of CPUs associated with the PMU instance. + +.. _SCF_PMU_Section: + +SCF PMU +------- + +The SCF PMU monitors system level cache events, CPU traffic, and +strongly-ordered (SO) PCIE write traffic to local/remote memory. Please see +:ref:`NVIDIA_Uncore_PMU_Traffic_Coverage_Section` for more info about the PMU +traffic coverage. + +The events and configuration options of this PMU device are described in sysfs, +see /sys/bus/event_sources/devices/nvidia_scf_pmu_<socket-id>. + +Example usage: + +* Count event id 0x0 in socket 0:: + + perf stat -a -e nvidia_scf_pmu_0/event=0x0/ + +* Count event id 0x0 in socket 1:: + + perf stat -a -e nvidia_scf_pmu_1/event=0x0/ + +NVLink-C2C0 PMU +-------------------- + +The NVLink-C2C0 PMU monitors incoming traffic from a GPU/CPU connected with +NVLink-C2C (Chip-2-Chip) interconnect. The type of traffic captured by this PMU +varies dependent on the chip configuration: + +* NVIDIA Grace Hopper Superchip: Hopper GPU is connected with Grace SoC. + + In this config, the PMU captures GPU ATS translated or EGM traffic from the GPU. + +* NVIDIA Grace CPU Superchip: two Grace CPU SoCs are connected. + + In this config, the PMU captures read and relaxed ordered (RO) writes from + PCIE device of the remote SoC. + +Please see :ref:`NVIDIA_Uncore_PMU_Traffic_Coverage_Section` for more info about +the PMU traffic coverage. + +The events and configuration options of this PMU device are described in sysfs, +see /sys/bus/event_sources/devices/nvidia_nvlink_c2c0_pmu_<socket-id>. + +Example usage: + +* Count event id 0x0 from the GPU/CPU connected with socket 0:: + + perf stat -a -e nvidia_nvlink_c2c0_pmu_0/event=0x0/ + +* Count event id 0x0 from the GPU/CPU connected with socket 1:: + + perf stat -a -e nvidia_nvlink_c2c0_pmu_1/event=0x0/ + +* Count event id 0x0 from the GPU/CPU connected with socket 2:: + + perf stat -a -e nvidia_nvlink_c2c0_pmu_2/event=0x0/ + +* Count event id 0x0 from the GPU/CPU connected with socket 3:: + + perf stat -a -e nvidia_nvlink_c2c0_pmu_3/event=0x0/ + +NVLink-C2C1 PMU +------------------- + +The NVLink-C2C1 PMU monitors incoming traffic from a GPU connected with +NVLink-C2C (Chip-2-Chip) interconnect. This PMU captures untranslated GPU +traffic, in contrast with NvLink-C2C0 PMU that captures ATS translated traffic. +Please see :ref:`NVIDIA_Uncore_PMU_Traffic_Coverage_Section` for more info about +the PMU traffic coverage. + +The events and configuration options of this PMU device are described in sysfs, +see /sys/bus/event_sources/devices/nvidia_nvlink_c2c1_pmu_<socket-id>. + +Example usage: + +* Count event id 0x0 from the GPU connected with socket 0:: + + perf stat -a -e nvidia_nvlink_c2c1_pmu_0/event=0x0/ + +* Count event id 0x0 from the GPU connected with socket 1:: + + perf stat -a -e nvidia_nvlink_c2c1_pmu_1/event=0x0/ + +* Count event id 0x0 from the GPU connected with socket 2:: + + perf stat -a -e nvidia_nvlink_c2c1_pmu_2/event=0x0/ + +* Count event id 0x0 from the GPU connected with socket 3:: + + perf stat -a -e nvidia_nvlink_c2c1_pmu_3/event=0x0/ + +CNVLink PMU +--------------- + +The CNVLink PMU monitors traffic from GPU and PCIE device on remote sockets +to local memory. For PCIE traffic, this PMU captures read and relaxed ordered +(RO) write traffic. Please see :ref:`NVIDIA_Uncore_PMU_Traffic_Coverage_Section` +for more info about the PMU traffic coverage. + +The events and configuration options of this PMU device are described in sysfs, +see /sys/bus/event_sources/devices/nvidia_cnvlink_pmu_<socket-id>. + +Each SoC socket can be connected to one or more sockets via CNVLink. The user can +use "rem_socket" bitmap parameter to select the remote socket(s) to monitor. +Each bit represents the socket number, e.g. "rem_socket=0xE" corresponds to +socket 1 to 3. +/sys/bus/event_sources/devices/nvidia_cnvlink_pmu_<socket-id>/format/rem_socket +shows the valid bits that can be set in the "rem_socket" parameter. + +The PMU can not distinguish the remote traffic initiator, therefore it does not +provide filter to select the traffic source to monitor. It reports combined +traffic from remote GPU and PCIE devices. + +Example usage: + +* Count event id 0x0 for the traffic from remote socket 1, 2, and 3 to socket 0:: + + perf stat -a -e nvidia_cnvlink_pmu_0/event=0x0,rem_socket=0xE/ + +* Count event id 0x0 for the traffic from remote socket 0, 2, and 3 to socket 1:: + + perf stat -a -e nvidia_cnvlink_pmu_1/event=0x0,rem_socket=0xD/ + +* Count event id 0x0 for the traffic from remote socket 0, 1, and 3 to socket 2:: + + perf stat -a -e nvidia_cnvlink_pmu_2/event=0x0,rem_socket=0xB/ + +* Count event id 0x0 for the traffic from remote socket 0, 1, and 2 to socket 3:: + + perf stat -a -e nvidia_cnvlink_pmu_3/event=0x0,rem_socket=0x7/ + + +PCIE PMU +------------ + +The PCIE PMU monitors all read/write traffic from PCIE root ports to +local/remote memory. Please see :ref:`NVIDIA_Uncore_PMU_Traffic_Coverage_Section` +for more info about the PMU traffic coverage. + +The events and configuration options of this PMU device are described in sysfs, +see /sys/bus/event_sources/devices/nvidia_pcie_pmu_<socket-id>. + +Each SoC socket can support multiple root ports. The user can use +"root_port" bitmap parameter to select the port(s) to monitor, i.e. +"root_port=0xF" corresponds to root port 0 to 3. +/sys/bus/event_sources/devices/nvidia_pcie_pmu_<socket-id>/format/root_port +shows the valid bits that can be set in the "root_port" parameter. + +Example usage: + +* Count event id 0x0 from root port 0 and 1 of socket 0:: + + perf stat -a -e nvidia_pcie_pmu_0/event=0x0,root_port=0x3/ + +* Count event id 0x0 from root port 0 and 1 of socket 1:: + + perf stat -a -e nvidia_pcie_pmu_1/event=0x0,root_port=0x3/ + +.. _NVIDIA_Uncore_PMU_Traffic_Coverage_Section: + +Traffic Coverage +---------------- + +The PMU traffic coverage may vary dependent on the chip configuration: + +* **NVIDIA Grace Hopper Superchip**: Hopper GPU is connected with Grace SoC. + + Example configuration with two Grace SoCs:: + + ********************************* ********************************* + * SOCKET-A * * SOCKET-B * + * * * * + * :::::::: * * :::::::: * + * : PCIE : * * : PCIE : * + * :::::::: * * :::::::: * + * | * * | * + * | * * | * + * ::::::: ::::::::: * * ::::::::: ::::::: * + * : : : : * * : : : : * + * : GPU :<--NVLink-->: Grace :<---CNVLink--->: Grace :<--NVLink-->: GPU : * + * : : C2C : SoC : * * : SoC : C2C : : * + * ::::::: ::::::::: * * ::::::::: ::::::: * + * | | * * | | * + * | | * * | | * + * &&&&&&&& &&&&&&&& * * &&&&&&&& &&&&&&&& * + * & GMEM & & CMEM & * * & CMEM & & GMEM & * + * &&&&&&&& &&&&&&&& * * &&&&&&&& &&&&&&&& * + * * * * + ********************************* ********************************* + + GMEM = GPU Memory (e.g. HBM) + CMEM = CPU Memory (e.g. LPDDR5X) + + | + | Following table contains traffic coverage of Grace SoC PMU in socket-A: + + :: + + +--------------+-------+-----------+-----------+-----+----------+----------+ + | | Source | + + +-------+-----------+-----------+-----+----------+----------+ + | Destination | |GPU ATS |GPU Not-ATS| | Socket-B | Socket-B | + | |PCI R/W|Translated,|Translated | CPU | CPU/PCIE1| GPU/PCIE2| + | | |EGM | | | | | + +==============+=======+===========+===========+=====+==========+==========+ + | Local | PCIE |NVLink-C2C0|NVLink-C2C1| SCF | SCF PMU | CNVLink | + | SYSRAM/CMEM | PMU |PMU |PMU | PMU | | PMU | + +--------------+-------+-----------+-----------+-----+----------+----------+ + | Local GMEM | PCIE | N/A |NVLink-C2C1| SCF | SCF PMU | CNVLink | + | | PMU | |PMU | PMU | | PMU | + +--------------+-------+-----------+-----------+-----+----------+----------+ + | Remote | PCIE |NVLink-C2C0|NVLink-C2C1| SCF | | | + | SYSRAM/CMEM | PMU |PMU |PMU | PMU | N/A | N/A | + | over CNVLink | | | | | | | + +--------------+-------+-----------+-----------+-----+----------+----------+ + | Remote GMEM | PCIE |NVLink-C2C0|NVLink-C2C1| SCF | | | + | over CNVLink | PMU |PMU |PMU | PMU | N/A | N/A | + +--------------+-------+-----------+-----------+-----+----------+----------+ + + PCIE1 traffic represents strongly ordered (SO) writes. + PCIE2 traffic represents reads and relaxed ordered (RO) writes. + +* **NVIDIA Grace CPU Superchip**: two Grace CPU SoCs are connected. + + Example configuration with two Grace SoCs:: + + ******************* ******************* + * SOCKET-A * * SOCKET-B * + * * * * + * :::::::: * * :::::::: * + * : PCIE : * * : PCIE : * + * :::::::: * * :::::::: * + * | * * | * + * | * * | * + * ::::::::: * * ::::::::: * + * : : * * : : * + * : Grace :<--------NVLink------->: Grace : * + * : SoC : * C2C * : SoC : * + * ::::::::: * * ::::::::: * + * | * * | * + * | * * | * + * &&&&&&&& * * &&&&&&&& * + * & CMEM & * * & CMEM & * + * &&&&&&&& * * &&&&&&&& * + * * * * + ******************* ******************* + + GMEM = GPU Memory (e.g. HBM) + CMEM = CPU Memory (e.g. LPDDR5X) + + | + | Following table contains traffic coverage of Grace SoC PMU in socket-A: + + :: + + +-----------------+-----------+---------+----------+-------------+ + | | Source | + + +-----------+---------+----------+-------------+ + | Destination | | | Socket-B | Socket-B | + | | PCI R/W | CPU | CPU/PCIE1| PCIE2 | + | | | | | | + +=================+===========+=========+==========+=============+ + | Local | PCIE PMU | SCF PMU | SCF PMU | NVLink-C2C0 | + | SYSRAM/CMEM | | | | PMU | + +-----------------+-----------+---------+----------+-------------+ + | Remote | | | | | + | SYSRAM/CMEM | PCIE PMU | SCF PMU | N/A | N/A | + | over NVLink-C2C | | | | | + +-----------------+-----------+---------+----------+-------------+ + + PCIE1 traffic represents strongly ordered (SO) writes. + PCIE2 traffic represents reads and relaxed ordered (RO) writes. diff --git a/Documentation/admin-guide/pm/amd-pstate.rst b/Documentation/admin-guide/pm/amd-pstate.rst index 8f3d30c5a0d8..5376d53faaa8 100644 --- a/Documentation/admin-guide/pm/amd-pstate.rst +++ b/Documentation/admin-guide/pm/amd-pstate.rst @@ -283,23 +283,19 @@ efficiency frequency management method on AMD processors. Kernel Module Options for ``amd-pstate`` ========================================= -.. _shared_mem: +Passive Mode +------------ -``shared_mem`` -Use a module param (shared_mem) to enable related processors manually with -**amd_pstate.shared_mem=1**. -Due to the performance issue on the processors with `Shared Memory Support -<perf_cap_>`_, we disable it presently and will re-enable this by default -once we address performance issue with this solution. +``amd_pstate=passive`` -To check whether the current processor is using `Full MSR Support <perf_cap_>`_ -or `Shared Memory Support <perf_cap_>`_ : :: - - ray@hr-test1:~$ lscpu | grep cppc - Flags: fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush mmx fxsr sse sse2 ht syscall nx mmxext fxsr_opt pdpe1gb rdtscp lm constant_tsc rep_good nopl nonstop_tsc cpuid extd_apicid aperfmperf rapl pni pclmulqdq monitor ssse3 fma cx16 sse4_1 sse4_2 x2apic movbe popcnt aes xsave avx f16c rdrand lahf_lm cmp_legacy svm extapic cr8_legacy abm sse4a misalignsse 3dnowprefetch osvw ibs skinit wdt tce topoext perfctr_core perfctr_nb bpext perfctr_llc mwaitx cpb cat_l3 cdp_l3 hw_pstate ssbd mba ibrs ibpb stibp vmmcall fsgsbase bmi1 avx2 smep bmi2 erms invpcid cqm rdt_a rdseed adx smap clflushopt clwb sha_ni xsaveopt xsavec xgetbv1 xsaves cqm_llc cqm_occup_llc cqm_mbm_total cqm_mbm_local clzero irperf xsaveerptr rdpru wbnoinvd cppc arat npt lbrv svm_lock nrip_save tsc_scale vmcb_clean flushbyasid decodeassists pausefilter pfthreshold avic v_vmsave_vmload vgif v_spec_ctrl umip pku ospke vaes vpclmulqdq rdpid overflow_recov succor smca fsrm - -If the CPU flags have ``cppc``, then this processor supports `Full MSR Support -<perf_cap_>`_. Otherwise, it supports `Shared Memory Support <perf_cap_>`_. +It will be enabled if the ``amd_pstate=passive`` is passed to the kernel in the command line. +In this mode, ``amd_pstate`` driver software specifies a desired QoS target in the CPPC +performance scale as a relative number. This can be expressed as percentage of nominal +performance (infrastructure max). Below the nominal sustained performance level, +desired performance expresses the average performance level of the processor subject +to the Performance Reduction Tolerance register. Above the nominal performance level, +processor must provide at least nominal performance requested and go higher if current +operating conditions allow. ``cpupower`` tool support for ``amd-pstate`` @@ -409,37 +405,55 @@ Unit Tests for amd-pstate 1. Test case decriptions + 1). Basic tests + + Test prerequisite and basic functions for the ``amd-pstate`` driver. + +---------+--------------------------------+------------------------------------------------------------------------------------+ | Index | Functions | Description | +=========+================================+====================================================================================+ - | 0 | amd_pstate_ut_acpi_cpc_valid || Check whether the _CPC object is present in SBIOS. | + | 1 | amd_pstate_ut_acpi_cpc_valid || Check whether the _CPC object is present in SBIOS. | | | || | | | || The detail refer to `Processor Support <processor_support_>`_. | +---------+--------------------------------+------------------------------------------------------------------------------------+ - | 1 | amd_pstate_ut_check_enabled || Check whether AMD P-State is enabled. | + | 2 | amd_pstate_ut_check_enabled || Check whether AMD P-State is enabled. | | | || | | | || AMD P-States and ACPI hardware P-States always can be supported in one processor. | | | | But AMD P-States has the higher priority and if it is enabled with | | | | :c:macro:`MSR_AMD_CPPC_ENABLE` or ``cppc_set_enable``, it will respond to the | | | | request from AMD P-States. | +---------+--------------------------------+------------------------------------------------------------------------------------+ - | 2 | amd_pstate_ut_check_perf || Check if the each performance values are reasonable. | + | 3 | amd_pstate_ut_check_perf || Check if the each performance values are reasonable. | | | || highest_perf >= nominal_perf > lowest_nonlinear_perf > lowest_perf > 0. | +---------+--------------------------------+------------------------------------------------------------------------------------+ - | 3 | amd_pstate_ut_check_freq || Check if the each frequency values and max freq when set support boost mode | + | 4 | amd_pstate_ut_check_freq || Check if the each frequency values and max freq when set support boost mode | | | | are reasonable. | | | || max_freq >= nominal_freq > lowest_nonlinear_freq > min_freq > 0 | | | || If boost is not active but supported, this maximum frequency will be larger than | | | | the one in ``cpuinfo``. | +---------+--------------------------------+------------------------------------------------------------------------------------+ + 2). Tbench test + + Test and monitor the cpu changes when running tbench benchmark under the specified governor. + These changes include desire performance, frequency, load, performance, energy etc. + The specified governor is ondemand or schedutil. + Tbench can also be tested on the ``acpi-cpufreq`` kernel driver for comparison. + + 3). Gitsource test + + Test and monitor the cpu changes when running gitsource benchmark under the specified governor. + These changes include desire performance, frequency, load, time, energy etc. + The specified governor is ondemand or schedutil. + Gitsource can also be tested on the ``acpi-cpufreq`` kernel driver for comparison. + #. How to execute the tests We use test module in the kselftest frameworks to implement it. - We create amd-pstate-ut module and tie it into kselftest.(for + We create ``amd-pstate-ut`` module and tie it into kselftest.(for details refer to Linux Kernel Selftests [4]_). - 1. Build + 1). Build + open the :c:macro:`CONFIG_X86_AMD_PSTATE` configuration option. + set the :c:macro:`CONFIG_X86_AMD_PSTATE_UT` configuration option to M. @@ -449,23 +463,159 @@ Unit Tests for amd-pstate $ cd linux $ make -C tools/testing/selftests - #. Installation & Steps :: + + make perf :: + + $ cd tools/perf/ + $ make + + + 2). Installation & Steps :: $ make -C tools/testing/selftests install INSTALL_PATH=~/kselftest + $ cp tools/perf/perf /usr/bin/perf $ sudo ./kselftest/run_kselftest.sh -c amd-pstate - TAP version 13 - 1..1 - # selftests: amd-pstate: amd-pstate-ut.sh - # amd-pstate-ut: ok - ok 1 selftests: amd-pstate: amd-pstate-ut.sh - - #. Results :: - - $ dmesg | grep "amd_pstate_ut" | tee log.txt - [12977.570663] amd_pstate_ut: 1 amd_pstate_ut_acpi_cpc_valid success! - [12977.570673] amd_pstate_ut: 2 amd_pstate_ut_check_enabled success! - [12977.571207] amd_pstate_ut: 3 amd_pstate_ut_check_perf success! - [12977.571212] amd_pstate_ut: 4 amd_pstate_ut_check_freq success! + + 3). Specified test case :: + + $ cd ~/kselftest/amd-pstate + $ sudo ./run.sh -t basic + $ sudo ./run.sh -t tbench + $ sudo ./run.sh -t tbench -m acpi-cpufreq + $ sudo ./run.sh -t gitsource + $ sudo ./run.sh -t gitsource -m acpi-cpufreq + $ ./run.sh --help + ./run.sh: illegal option -- - + Usage: ./run.sh [OPTION...] + [-h <help>] + [-o <output-file-for-dump>] + [-c <all: All testing, + basic: Basic testing, + tbench: Tbench testing, + gitsource: Gitsource testing.>] + [-t <tbench time limit>] + [-p <tbench process number>] + [-l <loop times for tbench>] + [-i <amd tracer interval>] + [-m <comparative test: acpi-cpufreq>] + + + 4). Results + + + basic + + When you finish test, you will get the following log info :: + + $ dmesg | grep "amd_pstate_ut" | tee log.txt + [12977.570663] amd_pstate_ut: 1 amd_pstate_ut_acpi_cpc_valid success! + [12977.570673] amd_pstate_ut: 2 amd_pstate_ut_check_enabled success! + [12977.571207] amd_pstate_ut: 3 amd_pstate_ut_check_perf success! + [12977.571212] amd_pstate_ut: 4 amd_pstate_ut_check_freq success! + + + tbench + + When you finish test, you will get selftest.tbench.csv and png images. + The selftest.tbench.csv file contains the raw data and the drop of the comparative test. + The png images shows the performance, energy and performan per watt of each test. + Open selftest.tbench.csv : + + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + Governor | Round | Des-perf | Freq | Load | Performance | Energy | Performance Per Watt | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + Unit | | | GHz | | MB/s | J | MB/J | + +=================================================+==============+==========+=========+==========+=============+=========+======================+ + + amd-pstate-ondemand | 1 | | | | 2504.05 | 1563.67 | 158.5378 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + amd-pstate-ondemand | 2 | | | | 2243.64 | 1430.32 | 155.2941 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + amd-pstate-ondemand | 3 | | | | 2183.88 | 1401.32 | 154.2860 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + amd-pstate-ondemand | Average | | | | 2310.52 | 1465.1 | 156.1268 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + amd-pstate-schedutil | 1 | 165.329 | 1.62257 | 99.798 | 2136.54 | 1395.26 | 151.5971 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + amd-pstate-schedutil | 2 | 166 | 1.49761 | 99.9993 | 2100.56 | 1380.5 | 150.6377 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + amd-pstate-schedutil | 3 | 166 | 1.47806 | 99.9993 | 2084.12 | 1375.76 | 149.9737 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + amd-pstate-schedutil | Average | 165.776 | 1.53275 | 99.9322 | 2107.07 | 1383.84 | 150.7399 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-ondemand | 1 | | | | 2529.9 | 1564.4 | 160.0997 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-ondemand | 2 | | | | 2249.76 | 1432.97 | 155.4297 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-ondemand | 3 | | | | 2181.46 | 1406.88 | 153.5060 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-ondemand | Average | | | | 2320.37 | 1468.08 | 156.4741 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-schedutil | 1 | | | | 2137.64 | 1385.24 | 152.7723 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-schedutil | 2 | | | | 2107.05 | 1372.23 | 152.0138 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-schedutil | 3 | | | | 2085.86 | 1365.35 | 151.2433 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-schedutil | Average | | | | 2110.18 | 1374.27 | 152.0136 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-ondemand VS acpi-cpufreq-schedutil | Comprison(%) | | | | -9.0584 | -6.3899 | -2.8506 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + amd-pstate-ondemand VS amd-pstate-schedutil | Comprison(%) | | | | 8.8053 | -5.5463 | -3.4503 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-ondemand VS amd-pstate-ondemand | Comprison(%) | | | | -0.4245 | -0.2029 | -0.2219 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-schedutil VS amd-pstate-schedutil | Comprison(%) | | | | -0.1473 | 0.6963 | -0.8378 | + +-------------------------------------------------+--------------+----------+---------+----------+-------------+---------+----------------------+ + + + gitsource + + When you finish test, you will get selftest.gitsource.csv and png images. + The selftest.gitsource.csv file contains the raw data and the drop of the comparative test. + The png images shows the performance, energy and performan per watt of each test. + Open selftest.gitsource.csv : + + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + Governor | Round | Des-perf | Freq | Load | Time | Energy | Performance Per Watt | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + Unit | | | GHz | | s | J | 1/J | + +=================================================+==============+==========+==========+==========+=============+=========+======================+ + + amd-pstate-ondemand | 1 | 50.119 | 2.10509 | 23.3076 | 475.69 | 865.78 | 0.001155027 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + amd-pstate-ondemand | 2 | 94.8006 | 1.98771 | 56.6533 | 467.1 | 839.67 | 0.001190944 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + amd-pstate-ondemand | 3 | 76.6091 | 2.53251 | 43.7791 | 467.69 | 855.85 | 0.001168429 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + amd-pstate-ondemand | Average | 73.8429 | 2.20844 | 41.2467 | 470.16 | 853.767 | 0.001171279 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + amd-pstate-schedutil | 1 | 165.919 | 1.62319 | 98.3868 | 464.17 | 866.8 | 0.001153668 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + amd-pstate-schedutil | 2 | 165.97 | 1.31309 | 99.5712 | 480.15 | 880.4 | 0.001135847 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + amd-pstate-schedutil | 3 | 165.973 | 1.28448 | 99.9252 | 481.79 | 867.02 | 0.001153375 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + amd-pstate-schedutil | Average | 165.954 | 1.40692 | 99.2944 | 475.37 | 871.407 | 0.001147569 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-ondemand | 1 | | | | 2379.62 | 742.96 | 0.001345967 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-ondemand | 2 | | | | 441.74 | 817.49 | 0.001223256 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-ondemand | 3 | | | | 455.48 | 820.01 | 0.001219497 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-ondemand | Average | | | | 425.613 | 793.487 | 0.001260260 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-schedutil | 1 | | | | 459.69 | 838.54 | 0.001192548 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-schedutil | 2 | | | | 466.55 | 830.89 | 0.001203528 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-schedutil | 3 | | | | 470.38 | 837.32 | 0.001194286 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-schedutil | Average | | | | 465.54 | 835.583 | 0.001196769 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-ondemand VS acpi-cpufreq-schedutil | Comprison(%) | | | | 9.3810 | 5.3051 | -5.0379 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + amd-pstate-ondemand VS amd-pstate-schedutil | Comprison(%) | 124.7392 | -36.2934 | 140.7329 | 1.1081 | 2.0661 | -2.0242 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-ondemand VS amd-pstate-ondemand | Comprison(%) | | | | 10.4665 | 7.5968 | -7.0605 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ + + acpi-cpufreq-schedutil VS amd-pstate-schedutil | Comprison(%) | | | | 2.1115 | 4.2873 | -4.1110 | + +-------------------------------------------------+--------------+----------+----------+----------+-------------+---------+----------------------+ Reference =========== diff --git a/Documentation/admin-guide/sysctl/fs.rst b/Documentation/admin-guide/sysctl/fs.rst index 2a501c9ddc55..a321b84eccaa 100644 --- a/Documentation/admin-guide/sysctl/fs.rst +++ b/Documentation/admin-guide/sysctl/fs.rst @@ -2,8 +2,6 @@ Documentation for /proc/sys/fs/ =============================== -kernel version 2.2.10 - Copyright (c) 1998, 1999, Rik van Riel <riel@nl.linux.org> Copyright (c) 2009, Shen Feng<shen@cn.fujitsu.com> @@ -12,58 +10,40 @@ For general info and legal blurb, please look in intro.rst. ------------------------------------------------------------------------------ -This file contains documentation for the sysctl files in -/proc/sys/fs/ and is valid for Linux kernel version 2.2. +This file contains documentation for the sysctl files and directories +in ``/proc/sys/fs/``. The files in this directory can be used to tune and monitor miscellaneous and general things in the operation of the Linux -kernel. Since some of the files _can_ be used to screw up your +kernel. Since some of the files *can* be used to screw up your system, it is advisable to read both documentation and source before actually making adjustments. 1. /proc/sys/fs =============== -Currently, these files are in /proc/sys/fs: - -- aio-max-nr -- aio-nr -- dentry-state -- dquot-max -- dquot-nr -- file-max -- file-nr -- inode-max -- inode-nr -- inode-state -- nr_open -- overflowuid -- overflowgid -- pipe-user-pages-hard -- pipe-user-pages-soft -- protected_fifos -- protected_hardlinks -- protected_regular -- protected_symlinks -- suid_dumpable -- super-max -- super-nr +Currently, these files might (depending on your configuration) +show up in ``/proc/sys/fs``: + +.. contents:: :local: aio-nr & aio-max-nr ------------------- -aio-nr is the running total of the number of events specified on the -io_setup system call for all currently active aio contexts. If aio-nr -reaches aio-max-nr then io_setup will fail with EAGAIN. Note that -raising aio-max-nr does not result in the pre-allocation or re-sizing -of any kernel data structures. +``aio-nr`` shows the current system-wide number of asynchronous io +requests. ``aio-max-nr`` allows you to change the maximum value +``aio-nr`` can grow to. If ``aio-nr`` reaches ``aio-nr-max`` then +``io_setup`` will fail with ``EAGAIN``. Note that raising +``aio-max-nr`` does not result in the +pre-allocation or re-sizing of any kernel data structures. dentry-state ------------ -From linux/include/linux/dcache.h:: +This file shows the values in ``struct dentry_stat``, as defined in +``linux/include/linux/dcache.h``:: struct dentry_stat_t dentry_stat { int nr_dentry; @@ -76,95 +56,84 @@ From linux/include/linux/dcache.h:: Dentries are dynamically allocated and deallocated. -nr_dentry shows the total number of dentries allocated (active -+ unused). nr_unused shows the number of dentries that are not +``nr_dentry`` shows the total number of dentries allocated (active ++ unused). ``nr_unused shows`` the number of dentries that are not actively used, but are saved in the LRU list for future reuse. -Age_limit is the age in seconds after which dcache entries -can be reclaimed when memory is short and want_pages is -nonzero when shrink_dcache_pages() has been called and the +``age_limit`` is the age in seconds after which dcache entries +can be reclaimed when memory is short and ``want_pages`` is +nonzero when ``shrink_dcache_pages()`` has been called and the dcache isn't pruned yet. -nr_negative shows the number of unused dentries that are also +``nr_negative`` shows the number of unused dentries that are also negative dentries which do not map to any files. Instead, they help speeding up rejection of non-existing files provided by the users. -dquot-max & dquot-nr --------------------- - -The file dquot-max shows the maximum number of cached disk -quota entries. - -The file dquot-nr shows the number of allocated disk quota -entries and the number of free disk quota entries. - -If the number of free cached disk quotas is very low and -you have some awesome number of simultaneous system users, -you might want to raise the limit. - - file-max & file-nr ------------------ -The value in file-max denotes the maximum number of file- +The value in ``file-max`` denotes the maximum number of file- handles that the Linux kernel will allocate. When you get lots of error messages about running out of file handles, you might want to increase this limit. Historically,the kernel was able to allocate file handles dynamically, but not to free them again. The three values in -file-nr denote the number of allocated file handles, the number +``file-nr`` denote the number of allocated file handles, the number of allocated but unused file handles, and the maximum number of -file handles. Linux 2.6 always reports 0 as the number of free +file handles. Linux 2.6 and later always reports 0 as the number of free file handles -- this is not an error, it just means that the number of allocated file handles exactly matches the number of used file handles. -Attempts to allocate more file descriptors than file-max are -reported with printk, look for "VFS: file-max limit <number> -reached". +Attempts to allocate more file descriptors than ``file-max`` are +reported with ``printk``, look for:: + VFS: file-max limit <number> reached -nr_open -------- - -This denotes the maximum number of file-handles a process can -allocate. Default value is 1024*1024 (1048576) which should be -enough for most machines. Actual limit depends on RLIMIT_NOFILE -resource limit. +in the kernel logs. -inode-max, inode-nr & inode-state ---------------------------------- +inode-nr & inode-state +---------------------- As with file handles, the kernel allocates the inode structures dynamically, but can't free them yet. -The value in inode-max denotes the maximum number of inode -handlers. This value should be 3-4 times larger than the value -in file-max, since stdin, stdout and network sockets also -need an inode struct to handle them. When you regularly run -out of inodes, you need to increase this value. - -The file inode-nr contains the first two items from -inode-state, so we'll skip to that file... +The file ``inode-nr`` contains the first two items from +``inode-state``, so we'll skip to that file... -Inode-state contains three actual numbers and four dummies. -The actual numbers are, in order of appearance, nr_inodes, -nr_free_inodes and preshrink. +``inode-state`` contains three actual numbers and four dummies. +The actual numbers are, in order of appearance, ``nr_inodes``, +``nr_free_inodes`` and ``preshrink``. -Nr_inodes stands for the number of inodes the system has -allocated, this can be slightly more than inode-max because -Linux allocates them one pageful at a time. +``nr_inodes`` stands for the number of inodes the system has +allocated. -Nr_free_inodes represents the number of free inodes (?) and -preshrink is nonzero when the nr_inodes > inode-max and the +``nr_free_inodes`` represents the number of free inodes (?) and +preshrink is nonzero when the system needs to prune the inode list instead of allocating more. +mount-max +--------- + +This denotes the maximum number of mounts that may exist +in a mount namespace. + + +nr_open +------- + +This denotes the maximum number of file-handles a process can +allocate. Default value is 1024*1024 (1048576) which should be +enough for most machines. Actual limit depends on ``RLIMIT_NOFILE`` +resource limit. + + overflowgid & overflowuid ------------------------- @@ -192,7 +161,7 @@ pipe-user-pages-soft Maximum total number of pages a non-privileged user may allocate for pipes before the pipe size gets limited to a single page. Once this limit is reached, new pipes will be limited to a single page in size for this user in order to -limit total memory usage, and trying to increase them using fcntl() will be +limit total memory usage, and trying to increase them using ``fcntl()`` will be denied until usage goes below the limit again. The default value allows to allocate up to 1024 pipes at their default size. When set to 0, no limit is applied. @@ -207,7 +176,7 @@ file. When set to "0", writing to FIFOs is unrestricted. -When set to "1" don't allow O_CREAT open on FIFOs that we don't own +When set to "1" don't allow ``O_CREAT`` open on FIFOs that we don't own in world writable sticky directories, unless they are owned by the owner of the directory. @@ -221,7 +190,7 @@ protected_hardlinks A long-standing class of security issues is the hardlink-based time-of-check-time-of-use race, most commonly seen in world-writable -directories like /tmp. The common method of exploitation of this flaw +directories like ``/tmp``. The common method of exploitation of this flaw is to cross privilege boundaries when following a given hardlink (i.e. a root process follows a hardlink created by another user). Additionally, on systems without separated partitions, this stops unauthorized users @@ -239,13 +208,13 @@ This protection is based on the restrictions in Openwall and grsecurity. protected_regular ----------------- -This protection is similar to protected_fifos, but it +This protection is similar to `protected_fifos`_, but it avoids writes to an attacker-controlled regular file, where a program expected to create one. When set to "0", writing to regular files is unrestricted. -When set to "1" don't allow O_CREAT open on regular files that we +When set to "1" don't allow ``O_CREAT`` open on regular files that we don't own in world writable sticky directories, unless they are owned by the owner of the directory. @@ -257,7 +226,7 @@ protected_symlinks A long-standing class of security issues is the symlink-based time-of-check-time-of-use race, most commonly seen in world-writable -directories like /tmp. The common method of exploitation of this flaw +directories like ``/tmp``. The common method of exploitation of this flaw is to cross privilege boundaries when following a given symlink (i.e. a root process follows a symlink belonging to another user). For a likely incomplete list of hundreds of examples across the years, please see: @@ -272,23 +241,25 @@ follower match, or when the directory owner matches the symlink's owner. This protection is based on the restrictions in Openwall and grsecurity. -suid_dumpable: --------------- +suid_dumpable +------------- This value can be used to query and set the core dump mode for setuid or otherwise protected/tainted binaries. The modes are = ========== =============================================================== -0 (default) traditional behaviour. Any process which has changed +0 (default) Traditional behaviour. Any process which has changed privilege levels or is execute only will not be dumped. -1 (debug) all processes dump core when possible. The core dump is +1 (debug) All processes dump core when possible. The core dump is owned by the current user and no security is applied. This is intended for system debugging situations only. Ptrace is unchecked. This is insecure as it allows regular users to examine the memory contents of privileged processes. -2 (suidsafe) any binary which normally would not be dumped is dumped - anyway, but only if the "core_pattern" kernel sysctl is set to +2 (suidsafe) Any binary which normally would not be dumped is dumped + anyway, but only if the ``core_pattern`` kernel sysctl (see + :ref:`Documentation/admin-guide/sysctl/kernel.rst <core_pattern>`) + is set to either a pipe handler or a fully qualified path. (For more details on this limitation, see CVE-2006-2451.) This mode is appropriate when administrators are attempting to debug @@ -301,36 +272,11 @@ or otherwise protected/tainted binaries. The modes are = ========== =============================================================== -super-max & super-nr --------------------- - -These numbers control the maximum number of superblocks, and -thus the maximum number of mounted filesystems the kernel -can have. You only need to increase super-max if you need to -mount more filesystems than the current value in super-max -allows you to. - - -aio-nr & aio-max-nr -------------------- - -aio-nr shows the current system-wide number of asynchronous io -requests. aio-max-nr allows you to change the maximum value -aio-nr can grow to. - - -mount-max ---------- - -This denotes the maximum number of mounts that may exist -in a mount namespace. - - 2. /proc/sys/fs/binfmt_misc =========================== -Documentation for the files in /proc/sys/fs/binfmt_misc is +Documentation for the files in ``/proc/sys/fs/binfmt_misc`` is in Documentation/admin-guide/binfmt-misc.rst. @@ -343,28 +289,32 @@ creation of a user space library that implements the POSIX message queues API (as noted by the MSG tag in the POSIX 1003.1-2001 version of the System Interfaces specification.) -The "mqueue" filesystem contains values for determining/setting the amount of -resources used by the file system. +The "mqueue" filesystem contains values for determining/setting the +amount of resources used by the file system. -/proc/sys/fs/mqueue/queues_max is a read/write file for setting/getting the -maximum number of message queues allowed on the system. +``/proc/sys/fs/mqueue/queues_max`` is a read/write file for +setting/getting the maximum number of message queues allowed on the +system. -/proc/sys/fs/mqueue/msg_max is a read/write file for setting/getting the -maximum number of messages in a queue value. In fact it is the limiting value -for another (user) limit which is set in mq_open invocation. This attribute of -a queue must be less or equal then msg_max. +``/proc/sys/fs/mqueue/msg_max`` is a read/write file for +setting/getting the maximum number of messages in a queue value. In +fact it is the limiting value for another (user) limit which is set in +``mq_open`` invocation. This attribute of a queue must be less than +or equal to ``msg_max``. -/proc/sys/fs/mqueue/msgsize_max is a read/write file for setting/getting the -maximum message size value (it is every message queue's attribute set during -its creation). +``/proc/sys/fs/mqueue/msgsize_max`` is a read/write file for +setting/getting the maximum message size value (it is an attribute of +every message queue, set during its creation). -/proc/sys/fs/mqueue/msg_default is a read/write file for setting/getting the -default number of messages in a queue value if attr parameter of mq_open(2) is -NULL. If it exceed msg_max, the default value is initialized msg_max. +``/proc/sys/fs/mqueue/msg_default`` is a read/write file for +setting/getting the default number of messages in a queue value if the +``attr`` parameter of ``mq_open(2)`` is ``NULL``. If it exceeds +``msg_max``, the default value is initialized to ``msg_max``. -/proc/sys/fs/mqueue/msgsize_default is a read/write file for setting/getting -the default message size value if attr parameter of mq_open(2) is NULL. If it -exceed msgsize_max, the default value is initialized msgsize_max. +``/proc/sys/fs/mqueue/msgsize_default`` is a read/write file for +setting/getting the default message size value if the ``attr`` +parameter of ``mq_open(2)`` is ``NULL``. If it exceeds +``msgsize_max``, the default value is initialized to ``msgsize_max``. 4. /proc/sys/fs/epoll - Configuration options for the epoll interface ===================================================================== @@ -378,7 +328,7 @@ Every epoll file descriptor can store a number of files to be monitored for event readiness. Each one of these monitored files constitutes a "watch". This configuration option sets the maximum number of "watches" that are allowed for each user. -Each "watch" costs roughly 90 bytes on a 32bit kernel, and roughly 160 bytes -on a 64bit one. -The current default value for max_user_watches is the 1/25 (4%) of the -available low memory, divided for the "watch" cost in bytes. +Each "watch" costs roughly 90 bytes on a 32-bit kernel, and roughly 160 bytes +on a 64-bit one. +The current default value for ``max_user_watches`` is 4% of the +available low memory, divided by the "watch" cost in bytes. diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 98d1b198b2b4..659d7bc47d7b 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -139,6 +139,8 @@ Highest valid capability of the running kernel. Exports ``CAP_LAST_CAP`` from the kernel. +.. _core_pattern: + core_pattern ============ @@ -174,6 +176,7 @@ core_pattern %f executable filename %E executable path %c maximum size of core file by resource limit RLIMIT_CORE + %C CPU the task ran on %<OTHER> both are dropped ======== ========================================== @@ -667,6 +670,15 @@ This is the default behavior. an oops event is detected. +oops_limit +========== + +Number of kernel oopses after which the kernel should panic when +``panic_on_oops`` is not set. Setting this to 0 disables checking +the count. Setting this to 1 has the same effect as setting +``panic_on_oops=1``. The default value is 10000. + + osrelease, ostype & version =========================== @@ -1314,6 +1326,29 @@ watchdog work to be queued by the watchdog timer function, otherwise the NMI watchdog — if enabled — can detect a hard lockup condition. +split_lock_mitigate (x86 only) +============================== + +On x86, each "split lock" imposes a system-wide performance penalty. On larger +systems, large numbers of split locks from unprivileged users can result in +denials of service to well-behaved and potentially more important users. + +The kernel mitigates these bad users by detecting split locks and imposing +penalties: forcing them to wait and only allowing one core to execute split +locks at a time. + +These mitigations can make those bad applications unbearably slow. Setting +split_lock_mitigate=0 may restore some application performance, but will also +increase system exposure to denial of service attacks from split lock users. + += =================================================================== +0 Disable the mitigation mode - just warns the split lock on kernel log + and exposes the system to denials of service from the split lockers. +1 Enable the mitigation mode (this is the default) - penalizes the split + lockers with intentional performance degradation. += =================================================================== + + stack_erasing ============= @@ -1500,6 +1535,16 @@ entry will default to 2 instead of 0. 2 Unprivileged calls to ``bpf()`` are disabled = ============================================================= + +warn_limit +========== + +Number of kernel warnings after which the kernel should panic when +``panic_on_warn`` is not set. Setting this to 0 disables checking +the warning count. Setting this to 1 has the same effect as setting +``panic_on_warn=1``. The default value is 0. + + watchdog ======== diff --git a/Documentation/arm/marvell.rst b/Documentation/arm/marvell.rst index 370721518987..3d369a566038 100644 --- a/Documentation/arm/marvell.rst +++ b/Documentation/arm/marvell.rst @@ -14,18 +14,20 @@ Orion family Flavors: - 88F5082 - - 88F5181 - - 88F5181L - - 88F5182 + - 88F5181 a.k.a Orion-1 + - 88F5181L a.k.a Orion-VoIP + - 88F5182 a.k.a Orion-NAS - Datasheet: https://web.archive.org/web/20210124231420/http://csclub.uwaterloo.ca/~board/ts7800/MV88F5182-datasheet.pdf - Programmer's User Guide: https://web.archive.org/web/20210124231536/http://csclub.uwaterloo.ca/~board/ts7800/MV88F5182-opensource-manual.pdf - User Manual: https://web.archive.org/web/20210124231631/http://csclub.uwaterloo.ca/~board/ts7800/MV88F5182-usermanual.pdf - Functional Errata: https://web.archive.org/web/20210704165540/https://www.digriz.org.uk/ts78xx/88F5182_Functional_Errata.pdf - - 88F5281 + - 88F5281 a.k.a Orion-2 - Datasheet: https://web.archive.org/web/20131028144728/http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf - - 88F6183 + - 88F6183 a.k.a Orion-1-90 + Homepage: + https://web.archive.org/web/20080607215437/http://www.marvell.com/products/media/index.jsp Core: Feroceon 88fr331 (88f51xx) or 88fr531-vd (88f52xx) ARMv5 compatible Linux kernel mach directory: diff --git a/Documentation/arm64/acpi_object_usage.rst b/Documentation/arm64/acpi_object_usage.rst index 0609da73970b..484ef9676653 100644 --- a/Documentation/arm64/acpi_object_usage.rst +++ b/Documentation/arm64/acpi_object_usage.rst @@ -163,7 +163,7 @@ FPDT Section 5.2.23 (signature == "FPDT") **Firmware Performance Data Table** - Optional, not currently supported. + Optional, useful for boot performance profiling. GTDT Section 5.2.24 (signature == "GTDT") diff --git a/Documentation/arm64/booting.rst b/Documentation/arm64/booting.rst index 8c324ad638de..96fe10ec6c24 100644 --- a/Documentation/arm64/booting.rst +++ b/Documentation/arm64/booting.rst @@ -121,8 +121,9 @@ Header notes: to the base of DRAM, since memory below it is not accessible via the linear mapping 1 - 2MB aligned base may be anywhere in physical - memory + 2MB aligned base such that all image_size bytes + counted from the start of the image are within + the 48-bit addressable range of physical memory Bits 4-63 Reserved. ============= =============================================================== @@ -348,7 +349,7 @@ Before jumping into the kernel, the following conditions must be met: - HWFGWTR_EL2.nSMPRI_EL1 (bit 54) must be initialised to 0b01. - For CPUs with the Scalable Matrix Extension FA64 feature (FEAT_SME_FA64) + For CPUs with the Scalable Matrix Extension FA64 feature (FEAT_SME_FA64): - If EL3 is present: diff --git a/Documentation/arm64/elf_hwcaps.rst b/Documentation/arm64/elf_hwcaps.rst index bb34287c8e01..6fed84f935df 100644 --- a/Documentation/arm64/elf_hwcaps.rst +++ b/Documentation/arm64/elf_hwcaps.rst @@ -275,6 +275,15 @@ HWCAP2_EBF16 HWCAP2_SVE_EBF16 Functionality implied by ID_AA64ZFR0_EL1.BF16 == 0b0010. +HWCAP2_CSSC + Functionality implied by ID_AA64ISAR2_EL1.CSSC == 0b0001. + +HWCAP2_RPRFM + Functionality implied by ID_AA64ISAR2_EL1.RPRFM == 0b0001. + +HWCAP2_SVE2P1 + Functionality implied by ID_AA64ZFR0_EL1.SVEver == 0b0010. + 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/sve.rst b/Documentation/arm64/sve.rst index f338ee2df46d..c7a356bf4e8f 100644 --- a/Documentation/arm64/sve.rst +++ b/Documentation/arm64/sve.rst @@ -52,6 +52,7 @@ model features for SVE is included in Appendix A. HWCAP2_SVEBITPERM HWCAP2_SVESHA3 HWCAP2_SVESM4 + HWCAP2_SVE2P1 This list may be extended over time as the SVE architecture evolves. diff --git a/Documentation/block/inline-encryption.rst b/Documentation/block/inline-encryption.rst index 4d151fbe2058..f9bf18ea6509 100644 --- a/Documentation/block/inline-encryption.rst +++ b/Documentation/block/inline-encryption.rst @@ -142,7 +142,7 @@ Therefore, we also introduce *blk-crypto-fallback*, which is an implementation of inline encryption using the kernel crypto API. blk-crypto-fallback is built into the block layer, so it works on any block device without any special setup. Essentially, when a bio with an encryption context is submitted to a -request_queue that doesn't support that encryption context, the block layer will +block_device that doesn't support that encryption context, the block layer will handle en/decryption of the bio using blk-crypto-fallback. For encryption, the data cannot be encrypted in-place, as callers usually rely @@ -187,7 +187,7 @@ API presented to users of the block layer ``blk_crypto_config_supported()`` allows users to check ahead of time whether inline encryption with particular crypto settings will work on a particular -request_queue -- either via hardware or via blk-crypto-fallback. This function +block_device -- either via hardware or via blk-crypto-fallback. This function takes in a ``struct blk_crypto_config`` which is like blk_crypto_key, but omits the actual bytes of the key and instead just contains the algorithm, data unit size, etc. This function can be useful if blk-crypto-fallback is disabled. @@ -195,7 +195,7 @@ size, etc. This function can be useful if blk-crypto-fallback is disabled. ``blk_crypto_init_key()`` allows users to initialize a blk_crypto_key. Users must call ``blk_crypto_start_using_key()`` before actually starting to use -a blk_crypto_key on a request_queue (even if ``blk_crypto_config_supported()`` +a blk_crypto_key on a block_device (even if ``blk_crypto_config_supported()`` was called earlier). This is needed to initialize blk-crypto-fallback if it will be needed. This must not be called from the data path, as this may have to allocate resources, which may deadlock in that case. @@ -207,7 +207,7 @@ for en/decryption. Users don't need to worry about freeing the bio_crypt_ctx later, as that happens automatically when the bio is freed or reset. Finally, when done using inline encryption with a blk_crypto_key on a -request_queue, users must call ``blk_crypto_evict_key()``. This ensures that +block_device, users must call ``blk_crypto_evict_key()``. This ensures that the key is evicted from all keyslots it may be programmed into and unlinked from any kernel data structures it may be linked into. @@ -221,9 +221,9 @@ as follows: 5. ``blk_crypto_evict_key()`` (after all I/O has completed) 6. Zeroize the blk_crypto_key (this has no dedicated function) -If a blk_crypto_key is being used on multiple request_queues, then +If a blk_crypto_key is being used on multiple block_devices, then ``blk_crypto_config_supported()`` (if used), ``blk_crypto_start_using_key()``, -and ``blk_crypto_evict_key()`` must be called on each request_queue. +and ``blk_crypto_evict_key()`` must be called on each block_device. API presented to device drivers =============================== diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst index a210b8a4df00..cec2371173d7 100644 --- a/Documentation/bpf/bpf_design_QA.rst +++ b/Documentation/bpf/bpf_design_QA.rst @@ -298,3 +298,48 @@ A: NO. The BTF_ID macro does not cause a function to become part of the ABI any more than does the EXPORT_SYMBOL_GPL macro. + +Q: What is the compatibility story for special BPF types in map values? +----------------------------------------------------------------------- +Q: Users are allowed to embed bpf_spin_lock, bpf_timer fields in their BPF map +values (when using BTF support for BPF maps). This allows to use helpers for +such objects on these fields inside map values. Users are also allowed to embed +pointers to some kernel types (with __kptr and __kptr_ref BTF tags). Will the +kernel preserve backwards compatibility for these features? + +A: It depends. For bpf_spin_lock, bpf_timer: YES, for kptr and everything else: +NO, but see below. + +For struct types that have been added already, like bpf_spin_lock and bpf_timer, +the kernel will preserve backwards compatibility, as they are part of UAPI. + +For kptrs, they are also part of UAPI, but only with respect to the kptr +mechanism. The types that you can use with a __kptr and __kptr_ref tagged +pointer in your struct are NOT part of the UAPI contract. The supported types can +and will change across kernel releases. However, operations like accessing kptr +fields and bpf_kptr_xchg() helper will continue to be supported across kernel +releases for the supported types. + +For any other supported struct type, unless explicitly stated in this document +and added to bpf.h UAPI header, such types can and will arbitrarily change their +size, type, and alignment, or any other user visible API or ABI detail across +kernel releases. The users must adapt their BPF programs to the new changes and +update them to make sure their programs continue to work correctly. + +NOTE: BPF subsystem specially reserves the 'bpf\_' prefix for type names, in +order to introduce more special fields in the future. Hence, user programs must +avoid defining types with 'bpf\_' prefix to not be broken in future releases. +In other words, no backwards compatibility is guaranteed if one using a type +in BTF with 'bpf\_' prefix. + +Q: What is the compatibility story for special BPF types in allocated objects? +------------------------------------------------------------------------------ +Q: Same as above, but for allocated objects (i.e. objects allocated using +bpf_obj_new for user defined types). Will the kernel preserve backwards +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). diff --git a/Documentation/bpf/bpf_devel_QA.rst b/Documentation/bpf/bpf_devel_QA.rst index 761474bd7fe6..03d4993eda6f 100644 --- a/Documentation/bpf/bpf_devel_QA.rst +++ b/Documentation/bpf/bpf_devel_QA.rst @@ -44,6 +44,33 @@ is a guarantee that the reported issue will be overlooked.** Submitting patches ================== +Q: How do I run BPF CI on my changes before sending them out for review? +------------------------------------------------------------------------ +A: BPF CI is GitHub based and hosted at https://github.com/kernel-patches/bpf. +While GitHub also provides a CLI that can be used to accomplish the same +results, here we focus on the UI based workflow. + +The following steps lay out how to start a CI run for your patches: + +- Create a fork of the aforementioned repository in your own account (one time + action) + +- Clone the fork locally, check out a new branch tracking either the bpf-next + or bpf branch, and apply your to-be-tested patches on top of it + +- Push the local branch to your fork and create a pull request against + kernel-patches/bpf's bpf-next_base or bpf_base branch, respectively + +Shortly after the pull request has been created, the CI workflow will run. Note +that capacity is shared with patches submitted upstream being checked and so +depending on utilization the run can take a while to finish. + +Note furthermore that both base branches (bpf-next_base and bpf_base) will be +updated as patches are pushed to the respective upstream branches they track. As +such, your patch set will automatically (be attempted to) be rebased as well. +This behavior can result in a CI run being aborted and restarted with the new +base line. + Q: To which mailing list do I need to submit my BPF patches? ------------------------------------------------------------ A: Please submit your BPF patches to the bpf kernel mailing list: diff --git a/Documentation/bpf/bpf_iterators.rst b/Documentation/bpf/bpf_iterators.rst new file mode 100644 index 000000000000..6d7770793fab --- /dev/null +++ b/Documentation/bpf/bpf_iterators.rst @@ -0,0 +1,485 @@ +============= +BPF Iterators +============= + + +---------- +Motivation +---------- + +There are a few existing ways to dump kernel data into user space. The most +popular one is the ``/proc`` system. For example, ``cat /proc/net/tcp6`` dumps +all tcp6 sockets in the system, and ``cat /proc/net/netlink`` dumps all netlink +sockets in the system. However, their output format tends to be fixed, and if +users want more information about these sockets, they have to patch the kernel, +which often takes time to publish upstream and release. The same is true for popular +tools like `ss <https://man7.org/linux/man-pages/man8/ss.8.html>`_ where any +additional information needs a kernel patch. + +To solve this problem, the `drgn +<https://www.kernel.org/doc/html/latest/bpf/drgn.html>`_ tool is often used to +dig out the kernel data with no kernel change. However, the main drawback for +drgn is performance, as it cannot do pointer tracing inside the kernel. In +addition, drgn cannot validate a pointer value and may read invalid data if the +pointer becomes invalid inside the kernel. + +The BPF iterator solves the above problem by providing flexibility on what data +(e.g., tasks, bpf_maps, etc.) to collect by calling BPF programs for each kernel +data object. + +---------------------- +How BPF Iterators Work +---------------------- + +A BPF iterator is a type of BPF program that allows users to iterate over +specific types of kernel objects. Unlike traditional BPF tracing programs that +allow users to define callbacks that are invoked at particular points of +execution in the kernel, BPF iterators allow users to define callbacks that +should be executed for every entry in a variety of kernel data structures. + +For example, users can define a BPF iterator that iterates over every task on +the system and dumps the total amount of CPU runtime currently used by each of +them. Another BPF task iterator may instead dump the cgroup information for each +task. Such flexibility is the core value of BPF iterators. + +A BPF program is always loaded into the kernel at the behest of a user space +process. A user space process loads a BPF program by opening and initializing +the program skeleton as required and then invoking a syscall to have the BPF +program verified and loaded by the kernel. + +In traditional tracing programs, a program is activated by having user space +obtain a ``bpf_link`` to the program with ``bpf_program__attach()``. Once +activated, the program callback will be invoked whenever the tracepoint is +triggered in the main kernel. For BPF iterator programs, a ``bpf_link`` to the +program is obtained using ``bpf_link_create()``, and the program callback is +invoked by issuing system calls from user space. + +Next, let us see how you can use the iterators to iterate on kernel objects and +read data. + +------------------------ +How to Use BPF iterators +------------------------ + +BPF selftests are a great resource to illustrate how to use the iterators. In +this section, we’ll walk through a BPF selftest which shows how to load and use +a BPF iterator program. To begin, we’ll look at `bpf_iter.c +<https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/tree/tools/testing/selftests/bpf/prog_tests/bpf_iter.c>`_, +which illustrates how to load and trigger BPF iterators on the user space side. +Later, we’ll look at a BPF program that runs in kernel space. + +Loading a BPF iterator in the kernel from user space typically involves the +following steps: + +* The BPF program is loaded into the kernel through ``libbpf``. Once the kernel + has verified and loaded the program, it returns a file descriptor (fd) to user + space. +* Obtain a ``link_fd`` to the BPF program by calling the ``bpf_link_create()`` + specified with the BPF program file descriptor received from the kernel. +* Next, obtain a BPF iterator file descriptor (``bpf_iter_fd``) by calling the + ``bpf_iter_create()`` specified with the ``bpf_link`` received from Step 2. +* Trigger the iteration by calling ``read(bpf_iter_fd)`` until no data is + available. +* Close the iterator fd using ``close(bpf_iter_fd)``. +* If needed to reread the data, get a new ``bpf_iter_fd`` and do the read again. + +The following are a few examples of selftest BPF iterator programs: + +* `bpf_iter_tcp4.c <https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/tree/tools/testing/selftests/bpf/progs/bpf_iter_tcp4.c>`_ +* `bpf_iter_task_vma.c <https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/tree/tools/testing/selftests/bpf/progs/bpf_iter_task_vma.c>`_ +* `bpf_iter_task_file.c <https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/tree/tools/testing/selftests/bpf/progs/bpf_iter_task_file.c>`_ + +Let us look at ``bpf_iter_task_file.c``, which runs in kernel space: + +Here is the definition of ``bpf_iter__task_file`` in `vmlinux.h +<https://facebookmicrosites.github.io/bpf/blog/2020/02/19/bpf-portability-and-co-re.html#btf>`_. +Any struct name in ``vmlinux.h`` in the format ``bpf_iter__<iter_name>`` +represents a BPF iterator. The suffix ``<iter_name>`` represents the type of +iterator. + +:: + + struct bpf_iter__task_file { + union { + struct bpf_iter_meta *meta; + }; + union { + struct task_struct *task; + }; + u32 fd; + union { + struct file *file; + }; + }; + +In the above code, the field 'meta' contains the metadata, which is the same for +all BPF iterator programs. The rest of the fields are specific to different +iterators. For example, for task_file iterators, the kernel layer provides the +'task', 'fd' and 'file' field values. The 'task' and 'file' are `reference +counted +<https://facebookmicrosites.github.io/bpf/blog/2018/08/31/object-lifetime.html#file-descriptors-and-reference-counters>`_, +so they won't go away when the BPF program runs. + +Here is a snippet from the ``bpf_iter_task_file.c`` file: + +:: + + SEC("iter/task_file") + int dump_task_file(struct bpf_iter__task_file *ctx) + { + struct seq_file *seq = ctx->meta->seq; + struct task_struct *task = ctx->task; + struct file *file = ctx->file; + __u32 fd = ctx->fd; + + if (task == NULL || file == NULL) + return 0; + + if (ctx->meta->seq_num == 0) { + count = 0; + BPF_SEQ_PRINTF(seq, " tgid gid fd file\n"); + } + + if (tgid == task->tgid && task->tgid != task->pid) + count++; + + if (last_tgid != task->tgid) { + last_tgid = task->tgid; + unique_tgid_count++; + } + + BPF_SEQ_PRINTF(seq, "%8d %8d %8d %lx\n", task->tgid, task->pid, fd, + (long)file->f_op); + return 0; + } + +In the above example, the section name ``SEC(iter/task_file)``, indicates that +the program is a BPF iterator program to iterate all files from all tasks. The +context of the program is ``bpf_iter__task_file`` struct. + +The user space program invokes the BPF iterator program running in the kernel +by issuing a ``read()`` syscall. Once invoked, the BPF +program can export data to user space using a variety of BPF helper functions. +You can use either ``bpf_seq_printf()`` (and BPF_SEQ_PRINTF helper macro) or +``bpf_seq_write()`` function based on whether you need formatted output or just +binary data, respectively. For binary-encoded data, the user space applications +can process the data from ``bpf_seq_write()`` as needed. For the formatted data, +you can use ``cat <path>`` to print the results similar to ``cat +/proc/net/netlink`` after pinning the BPF iterator to the bpffs mount. Later, +use ``rm -f <path>`` to remove the pinned iterator. + +For example, you can use the following command to create a BPF iterator from the +``bpf_iter_ipv6_route.o`` object file and pin it to the ``/sys/fs/bpf/my_route`` +path: + +:: + + $ bpftool iter pin ./bpf_iter_ipv6_route.o /sys/fs/bpf/my_route + +And then print out the results using the following command: + +:: + + $ cat /sys/fs/bpf/my_route + + +------------------------------------------------------- +Implement Kernel Support for BPF Iterator Program Types +------------------------------------------------------- + +To implement a BPF iterator in the kernel, the developer must make a one-time +change to the following key data structure defined in the `bpf.h +<https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/tree/include/linux/bpf.h>`_ +file. + +:: + + struct bpf_iter_reg { + const char *target; + bpf_iter_attach_target_t attach_target; + bpf_iter_detach_target_t detach_target; + bpf_iter_show_fdinfo_t show_fdinfo; + bpf_iter_fill_link_info_t fill_link_info; + bpf_iter_get_func_proto_t get_func_proto; + u32 ctx_arg_info_size; + u32 feature; + struct bpf_ctx_arg_aux ctx_arg_info[BPF_ITER_CTX_ARG_MAX]; + const struct bpf_iter_seq_info *seq_info; + }; + +After filling the data structure fields, call ``bpf_iter_reg_target()`` to +register the iterator to the main BPF iterator subsystem. + +The following is the breakdown for each field in struct ``bpf_iter_reg``. + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * - Fields + - Description + * - target + - Specifies the name of the BPF iterator. For example: ``bpf_map``, + ``bpf_map_elem``. The name should be different from other ``bpf_iter`` target names in the kernel. + * - attach_target and detach_target + - Allows for target specific ``link_create`` action since some targets + may need special processing. Called during the user space link_create stage. + * - show_fdinfo and fill_link_info + - Called to fill target specific information when user tries to get link + info associated with the iterator. + * - get_func_proto + - Permits a BPF iterator to access BPF helpers specific to the iterator. + * - ctx_arg_info_size and ctx_arg_info + - Specifies the verifier states for BPF program arguments associated with + the bpf iterator. + * - feature + - Specifies certain action requests in the kernel BPF iterator + infrastructure. Currently, only BPF_ITER_RESCHED is supported. This means + that the kernel function cond_resched() is called to avoid other kernel + subsystem (e.g., rcu) misbehaving. + * - seq_info + - Specifies certain action requests in the kernel BPF iterator + infrastructure. Currently, only BPF_ITER_RESCHED is supported. This means + that the kernel function cond_resched() is called to avoid other kernel + subsystem (e.g., rcu) misbehaving. + + +`Click here +<https://lore.kernel.org/bpf/20210212183107.50963-2-songliubraving@fb.com/>`_ +to see an implementation of the ``task_vma`` BPF iterator in the kernel. + +--------------------------------- +Parameterizing BPF Task Iterators +--------------------------------- + +By default, BPF iterators walk through all the objects of the specified types +(processes, cgroups, maps, etc.) across the entire system to read relevant +kernel data. But often, there are cases where we only care about a much smaller +subset of iterable kernel objects, such as only iterating tasks within a +specific process. Therefore, BPF iterator programs support filtering out objects +from iteration by allowing user space to configure the iterator program when it +is attached. + +-------------------------- +BPF Task Iterator Program +-------------------------- + +The following code is a BPF iterator program to print files and task information +through the ``seq_file`` of the iterator. It is a standard BPF iterator program +that visits every file of an iterator. We will use this BPF program in our +example later. + +:: + + #include <vmlinux.h> + #include <bpf/bpf_helpers.h> + + char _license[] SEC("license") = "GPL"; + + SEC("iter/task_file") + int dump_task_file(struct bpf_iter__task_file *ctx) + { + struct seq_file *seq = ctx->meta->seq; + struct task_struct *task = ctx->task; + struct file *file = ctx->file; + __u32 fd = ctx->fd; + if (task == NULL || file == NULL) + return 0; + if (ctx->meta->seq_num == 0) { + BPF_SEQ_PRINTF(seq, " tgid pid fd file\n"); + } + BPF_SEQ_PRINTF(seq, "%8d %8d %8d %lx\n", task->tgid, task->pid, fd, + (long)file->f_op); + return 0; + } + +---------------------------------------- +Creating a File Iterator with Parameters +---------------------------------------- + +Now, let us look at how to create an iterator that includes only files of a +process. + +First, fill the ``bpf_iter_attach_opts`` struct as shown below: + +:: + + LIBBPF_OPTS(bpf_iter_attach_opts, opts); + union bpf_iter_link_info linfo; + memset(&linfo, 0, sizeof(linfo)); + linfo.task.pid = getpid(); + opts.link_info = &linfo; + opts.link_info_len = sizeof(linfo); + +``linfo.task.pid``, if it is non-zero, directs the kernel to create an iterator +that only includes opened files for the process with the specified ``pid``. In +this example, we will only be iterating files for our process. If +``linfo.task.pid`` is zero, the iterator will visit every opened file of every +process. Similarly, ``linfo.task.tid`` directs the kernel to create an iterator +that visits opened files of a specific thread, not a process. In this example, +``linfo.task.tid`` is different from ``linfo.task.pid`` only if the thread has a +separate file descriptor table. In most circumstances, all process threads share +a single file descriptor table. + +Now, in the userspace program, pass the pointer of struct to the +``bpf_program__attach_iter()``. + +:: + + link = bpf_program__attach_iter(prog, &opts); iter_fd = + bpf_iter_create(bpf_link__fd(link)); + +If both *tid* and *pid* are zero, an iterator created from this struct +``bpf_iter_attach_opts`` will include every opened file of every task in the +system (in the namespace, actually.) It is the same as passing a NULL as the +second argument to ``bpf_program__attach_iter()``. + +The whole program looks like the following code: + +:: + + #include <stdio.h> + #include <unistd.h> + #include <bpf/bpf.h> + #include <bpf/libbpf.h> + #include "bpf_iter_task_ex.skel.h" + + static int do_read_opts(struct bpf_program *prog, struct bpf_iter_attach_opts *opts) + { + struct bpf_link *link; + char buf[16] = {}; + int iter_fd = -1, len; + int ret = 0; + + link = bpf_program__attach_iter(prog, opts); + if (!link) { + fprintf(stderr, "bpf_program__attach_iter() fails\n"); + return -1; + } + iter_fd = bpf_iter_create(bpf_link__fd(link)); + if (iter_fd < 0) { + fprintf(stderr, "bpf_iter_create() fails\n"); + ret = -1; + goto free_link; + } + /* not check contents, but ensure read() ends without error */ + while ((len = read(iter_fd, buf, sizeof(buf) - 1)) > 0) { + buf[len] = 0; + printf("%s", buf); + } + printf("\n"); + free_link: + if (iter_fd >= 0) + close(iter_fd); + bpf_link__destroy(link); + return 0; + } + + static void test_task_file(void) + { + LIBBPF_OPTS(bpf_iter_attach_opts, opts); + struct bpf_iter_task_ex *skel; + union bpf_iter_link_info linfo; + skel = bpf_iter_task_ex__open_and_load(); + if (skel == NULL) + return; + memset(&linfo, 0, sizeof(linfo)); + linfo.task.pid = getpid(); + opts.link_info = &linfo; + opts.link_info_len = sizeof(linfo); + printf("PID %d\n", getpid()); + do_read_opts(skel->progs.dump_task_file, &opts); + bpf_iter_task_ex__destroy(skel); + } + + int main(int argc, const char * const * argv) + { + test_task_file(); + return 0; + } + +The following lines are the output of the program. +:: + + PID 1859 + + tgid pid fd file + 1859 1859 0 ffffffff82270aa0 + 1859 1859 1 ffffffff82270aa0 + 1859 1859 2 ffffffff82270aa0 + 1859 1859 3 ffffffff82272980 + 1859 1859 4 ffffffff8225e120 + 1859 1859 5 ffffffff82255120 + 1859 1859 6 ffffffff82254f00 + 1859 1859 7 ffffffff82254d80 + 1859 1859 8 ffffffff8225abe0 + +------------------ +Without Parameters +------------------ + +Let us look at how a BPF iterator without parameters skips files of other +processes in the system. In this case, the BPF program has to check the pid or +the tid of tasks, or it will receive every opened file in the system (in the +current *pid* namespace, actually). So, we usually add a global variable in the +BPF program to pass a *pid* to the BPF program. + +The BPF program would look like the following block. + + :: + + ...... + int target_pid = 0; + + SEC("iter/task_file") + int dump_task_file(struct bpf_iter__task_file *ctx) + { + ...... + if (task->tgid != target_pid) /* Check task->pid instead to check thread IDs */ + return 0; + BPF_SEQ_PRINTF(seq, "%8d %8d %8d %lx\n", task->tgid, task->pid, fd, + (long)file->f_op); + return 0; + } + +The user space program would look like the following block: + + :: + + ...... + static void test_task_file(void) + { + ...... + skel = bpf_iter_task_ex__open_and_load(); + if (skel == NULL) + return; + skel->bss->target_pid = getpid(); /* process ID. For thread id, use gettid() */ + memset(&linfo, 0, sizeof(linfo)); + linfo.task.pid = getpid(); + opts.link_info = &linfo; + opts.link_info_len = sizeof(linfo); + ...... + } + +``target_pid`` is a global variable in the BPF program. The user space program +should initialize the variable with a process ID to skip opened files of other +processes in the BPF program. When you parametrize a BPF iterator, the iterator +calls the BPF program fewer times which can save significant resources. + +--------------------------- +Parametrizing VMA Iterators +--------------------------- + +By default, a BPF VMA iterator includes every VMA in every process. However, +you can still specify a process or a thread to include only its VMAs. Unlike +files, a thread can not have a separate address space (since Linux 2.6.0-test6). +Here, using *tid* makes no difference from using *pid*. + +---------------------------- +Parametrizing Task Iterators +---------------------------- + +A BPF task iterator with *pid* includes all tasks (threads) of a process. The +BPF program receives these tasks one after another. You can specify a BPF task +iterator with *tid* parameter to include only the tasks that match the given +*tid*. diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst index cf8722f96090..7cd7c5415a99 100644 --- a/Documentation/bpf/btf.rst +++ b/Documentation/bpf/btf.rst @@ -1062,4 +1062,9 @@ format.:: 7. Testing ========== -Kernel bpf selftest `test_btf.c` provides extensive set of BTF-related tests. +The kernel BPF selftest `tools/testing/selftests/bpf/prog_tests/btf.c`_ +provides an extensive set of BTF-related tests. + +.. Links +.. _tools/testing/selftests/bpf/prog_tests/btf.c: + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/bpf/prog_tests/btf.c diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst index 1b50de1983ee..b81533d8b061 100644 --- a/Documentation/bpf/index.rst +++ b/Documentation/bpf/index.rst @@ -24,11 +24,13 @@ that goes into great technical depth about the BPF Architecture. maps bpf_prog_run classic_vs_extended.rst + bpf_iterators bpf_licensing test_debug clang-notes linux-notes other + redirect .. only:: subproject and html diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 5d798437dad4..e672d5ec6cc7 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -122,11 +122,11 @@ BPF_END 0xd0 byte swap operations (see `Byte swap instructions`_ below) ``BPF_XOR | BPF_K | BPF_ALU`` means:: - src_reg = (u32) src_reg ^ (u32) imm32 + dst_reg = (u32) dst_reg ^ (u32) imm32 ``BPF_XOR | BPF_K | BPF_ALU64`` means:: - src_reg = src_reg ^ imm32 + dst_reg = dst_reg ^ imm32 Byte swap instructions diff --git a/Documentation/bpf/kfuncs.rst b/Documentation/bpf/kfuncs.rst index 0f858156371d..9fd7fb539f85 100644 --- a/Documentation/bpf/kfuncs.rst +++ b/Documentation/bpf/kfuncs.rst @@ -72,6 +72,30 @@ argument as its size. By default, without __sz annotation, the size of the type of the pointer is used. Without __sz annotation, a kfunc cannot accept a void pointer. +2.2.2 __k Annotation +-------------------- + +This annotation is only understood for scalar arguments, where it indicates that +the verifier must check the scalar argument to be a known constant, which does +not indicate a size parameter, and the value of the constant is relevant to the +safety of the program. + +An example is given below:: + + void *bpf_obj_new(u32 local_type_id__k, ...) + { + ... + } + +Here, bpf_obj_new uses local_type_id argument to find out the size of that type +ID in program's BTF and return a sized pointer to it. Each type ID will have a +distinct size, hence it is crucial to treat each such call as distinct when +values don't match during verifier state pruning checks. + +Hence, whenever a constant scalar argument is accepted by a kfunc which is not a +size parameter, and the value of the constant matters for program safety, __k +suffix should be used. + .. _BPF_kfunc_nodef: 2.3 Using an existing kernel function @@ -137,22 +161,20 @@ 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 will always have a guaranteed lifetime, -and pointers to kernel objects are always passed to helpers in their unmodified -form (as obtained from acquire kfuncs). +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). -It can be used to enforce that a pointer to a refcounted object acquired from a -kfunc or BPF helper is passed as an argument to this kfunc without any -modifications (e.g. pointer arithmetic) such that it is trusted and points to -the original object. +There are two types of pointers to kernel objects which are considered "valid": -Meanwhile, it is also allowed pass pointers to normal memory to such kfuncs, -but those can have a non-zero offset. +1. Pointers which are passed as tracepoint or struct_ops callback arguments. +2. Pointers which were returned from a KF_ACQUIRE or KF_KPTR_GET kfunc. -This flag is often used for kfuncs that operate (change some property, perform -some operation) on an object that was obtained using an acquire kfunc. Such -kfuncs need an unchanged pointer to ensure the integrity of the operation being -performed on the expected object. +Pointers to non-BTF objects (e.g. scalar pointers) may also be passed to +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. 2.4.6 KF_SLEEPABLE flag ----------------------- @@ -169,6 +191,15 @@ rebooting or panicking. Due to this additional restrictions apply to these calls. At the moment they only require CAP_SYS_BOOT capability, but more can be added later. +2.4.8 KF_RCU flag +----------------- + +The KF_RCU flag is used for kfuncs which have a rcu ptr as its argument. +When used together with KF_ACQUIRE, it indicates the kfunc should have a +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. + 2.5 Registering the kfuncs -------------------------- @@ -191,3 +222,201 @@ type. An example is shown below:: return register_btf_kfunc_id_set(BPF_PROG_TYPE_TRACING, &bpf_task_kfunc_set); } late_initcall(init_subsystem); + +3. 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 +------------------------------- + +There are a number of kfuncs that allow ``struct task_struct *`` objects to be +used as kptrs: + +.. kernel-doc:: kernel/bpf/helpers.c + :identifiers: bpf_task_acquire bpf_task_release + +These kfuncs are useful when you want to acquire or release a reference to a +``struct task_struct *`` that was passed as e.g. a tracepoint arg, or a +struct_ops callback arg. For example: + +.. code-block:: c + + /** + * A trivial example tracepoint program that shows how to + * acquire and release a struct task_struct * pointer. + */ + SEC("tp_btf/task_newtask") + int BPF_PROG(task_acquire_release_example, struct task_struct *task, u64 clone_flags) + { + struct task_struct *acquired; + + acquired = bpf_task_acquire(task); + + /* + * In a typical program you'd do something like store + * the task in a map, and the map will automatically + * release it later. Here, we release it manually. + */ + bpf_task_release(acquired); + return 0; + } + +---- + +A BPF program can also look up a task from a pid. This can be useful if the +caller doesn't have a trusted pointer to a ``struct task_struct *`` object that +it can acquire a reference on with bpf_task_acquire(). + +.. kernel-doc:: kernel/bpf/helpers.c + :identifiers: bpf_task_from_pid + +Here is an example of it being used: + +.. code-block:: c + + SEC("tp_btf/task_newtask") + int BPF_PROG(task_get_pid_example, struct task_struct *task, u64 clone_flags) + { + struct task_struct *lookup; + + lookup = bpf_task_from_pid(task->pid); + if (!lookup) + /* A task should always be found, as %task is a tracepoint arg. */ + return -ENOENT; + + if (lookup->pid != task->pid) { + /* bpf_task_from_pid() looks up the task via its + * globally-unique pid from the init_pid_ns. Thus, + * the pid of the lookup task should always be the + * same as the input task. + */ + bpf_task_release(lookup); + return -EINVAL; + } + + /* bpf_task_from_pid() returns an acquired reference, + * so it must be dropped before returning from the + * tracepoint handler. + */ + bpf_task_release(lookup); + return 0; + } + +3.2 struct cgroup * kfuncs +-------------------------- + +``struct cgroup *`` objects also have acquire and release functions: + +.. kernel-doc:: kernel/bpf/helpers.c + :identifiers: bpf_cgroup_acquire bpf_cgroup_release + +These kfuncs are used in exactly the same manner as bpf_task_acquire() and +bpf_task_release() respectively, so we won't provide examples for them. + +---- + +You may also acquire a reference to a ``struct cgroup`` kptr that's already +stored in a map using bpf_cgroup_kptr_get(): + +.. kernel-doc:: kernel/bpf/helpers.c + :identifiers: bpf_cgroup_kptr_get + +Here's an example of how it can be used: + +.. code-block:: c + + /* struct containing the struct task_struct kptr which is actually stored in the map. */ + struct __cgroups_kfunc_map_value { + struct cgroup __kptr_ref * cgroup; + }; + + /* The map containing struct __cgroups_kfunc_map_value entries. */ + struct { + __uint(type, BPF_MAP_TYPE_HASH); + __type(key, int); + __type(value, struct __cgroups_kfunc_map_value); + __uint(max_entries, 1); + } __cgroups_kfunc_map SEC(".maps"); + + /* ... */ + + /** + * A simple example tracepoint program showing how a + * struct cgroup kptr that is stored in a map can + * be acquired using the bpf_cgroup_kptr_get() kfunc. + */ + SEC("tp_btf/cgroup_mkdir") + int BPF_PROG(cgroup_kptr_get_example, struct cgroup *cgrp, const char *path) + { + struct cgroup *kptr; + struct __cgroups_kfunc_map_value *v; + s32 id = cgrp->self.id; + + /* Assume a cgroup kptr was previously stored in the map. */ + v = bpf_map_lookup_elem(&__cgroups_kfunc_map, &id); + if (!v) + return -ENOENT; + + /* Acquire a reference to the cgroup kptr that's already stored in the map. */ + kptr = bpf_cgroup_kptr_get(&v->cgroup); + if (!kptr) + /* If no cgroup 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_cgroup_kptr_get(). + * bpf_cgroup_kptr_get() internally safely handles this + * race, and will return NULL if the task 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 cgroup 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_cgroup_release(kptr); + + return 0; + } + +---- + +Another kfunc available for interacting with ``struct cgroup *`` objects is +bpf_cgroup_ancestor(). This allows callers to access the ancestor of a cgroup, +and return it as a cgroup kptr. + +.. kernel-doc:: kernel/bpf/helpers.c + :identifiers: bpf_cgroup_ancestor + +Eventually, BPF should be updated to allow this to happen with a normal memory +load in the program itself. This is currently not possible without more work in +the verifier. bpf_cgroup_ancestor() can be used as follows: + +.. code-block:: c + + /** + * Simple tracepoint example that illustrates how a cgroup's + * ancestor can be accessed using bpf_cgroup_ancestor(). + */ + SEC("tp_btf/cgroup_mkdir") + int BPF_PROG(cgrp_ancestor_example, struct cgroup *cgrp, const char *path) + { + struct cgroup *parent; + + /* The parent cgroup resides at the level before the current cgroup's level. */ + parent = bpf_cgroup_ancestor(cgrp, cgrp->level - 1); + if (!parent) + return -ENOENT; + + bpf_printk("Parent id is %d", parent->self.id); + + /* Return the parent cgroup that was acquired above. */ + bpf_cgroup_release(parent); + return 0; + } diff --git a/Documentation/bpf/libbpf/index.rst b/Documentation/bpf/libbpf/index.rst index 3722537d1384..f9b3b252e28f 100644 --- a/Documentation/bpf/libbpf/index.rst +++ b/Documentation/bpf/libbpf/index.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) +.. _libbpf: + libbpf ====== @@ -7,6 +9,7 @@ libbpf :maxdepth: 1 API Documentation <https://libbpf.readthedocs.io/en/latest/api.html> + program_types libbpf_naming_convention libbpf_build diff --git a/Documentation/bpf/libbpf/program_types.rst b/Documentation/bpf/libbpf/program_types.rst new file mode 100644 index 000000000000..ad4d4d5eecb0 --- /dev/null +++ b/Documentation/bpf/libbpf/program_types.rst @@ -0,0 +1,203 @@ +.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) + +.. _program_types_and_elf: + +Program Types and ELF Sections +============================== + +The table below lists the program types, their attach types where relevant and the ELF section +names supported by libbpf for them. The ELF section names follow these rules: + +- ``type`` is an exact match, e.g. ``SEC("socket")`` +- ``type+`` means it can be either exact ``SEC("type")`` or well-formed ``SEC("type/extras")`` + with a '``/``' separator between ``type`` and ``extras``. + +When ``extras`` are specified, they provide details of how to auto-attach the BPF program. The +format of ``extras`` depends on the program type, e.g. ``SEC("tracepoint/<category>/<name>")`` +for tracepoints or ``SEC("usdt/<path>:<provider>:<name>")`` for USDT probes. The extras are +described in more detail in the footnotes. + + ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| Program Type | Attach Type | ELF Section Name | Sleepable | ++===========================================+========================================+==================================+===========+ +| ``BPF_PROG_TYPE_CGROUP_DEVICE`` | ``BPF_CGROUP_DEVICE`` | ``cgroup/dev`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_CGROUP_SKB`` | | ``cgroup/skb`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_INET_EGRESS`` | ``cgroup_skb/egress`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_INET_INGRESS`` | ``cgroup_skb/ingress`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_CGROUP_SOCKOPT`` | ``BPF_CGROUP_GETSOCKOPT`` | ``cgroup/getsockopt`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_SETSOCKOPT`` | ``cgroup/setsockopt`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_CGROUP_SOCK_ADDR`` | ``BPF_CGROUP_INET4_BIND`` | ``cgroup/bind4`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_INET4_CONNECT`` | ``cgroup/connect4`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_INET4_GETPEERNAME`` | ``cgroup/getpeername4`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_INET4_GETSOCKNAME`` | ``cgroup/getsockname4`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_INET6_BIND`` | ``cgroup/bind6`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_INET6_CONNECT`` | ``cgroup/connect6`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_INET6_GETPEERNAME`` | ``cgroup/getpeername6`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_INET6_GETSOCKNAME`` | ``cgroup/getsockname6`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_UDP4_RECVMSG`` | ``cgroup/recvmsg4`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_UDP4_SENDMSG`` | ``cgroup/sendmsg4`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_UDP6_RECVMSG`` | ``cgroup/recvmsg6`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_UDP6_SENDMSG`` | ``cgroup/sendmsg6`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_CGROUP_SOCK`` | ``BPF_CGROUP_INET4_POST_BIND`` | ``cgroup/post_bind4`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_INET6_POST_BIND`` | ``cgroup/post_bind6`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_INET_SOCK_CREATE`` | ``cgroup/sock_create`` | | ++ + +----------------------------------+-----------+ +| | | ``cgroup/sock`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_INET_SOCK_RELEASE`` | ``cgroup/sock_release`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_CGROUP_SYSCTL`` | ``BPF_CGROUP_SYSCTL`` | ``cgroup/sysctl`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_EXT`` | | ``freplace+`` [#fentry]_ | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_FLOW_DISSECTOR`` | ``BPF_FLOW_DISSECTOR`` | ``flow_dissector`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_KPROBE`` | | ``kprobe+`` [#kprobe]_ | | ++ + +----------------------------------+-----------+ +| | | ``kretprobe+`` [#kprobe]_ | | ++ + +----------------------------------+-----------+ +| | | ``ksyscall+`` [#ksyscall]_ | | ++ + +----------------------------------+-----------+ +| | | ``kretsyscall+`` [#ksyscall]_ | | ++ + +----------------------------------+-----------+ +| | | ``uprobe+`` [#uprobe]_ | | ++ + +----------------------------------+-----------+ +| | | ``uprobe.s+`` [#uprobe]_ | Yes | ++ + +----------------------------------+-----------+ +| | | ``uretprobe+`` [#uprobe]_ | | ++ + +----------------------------------+-----------+ +| | | ``uretprobe.s+`` [#uprobe]_ | Yes | ++ + +----------------------------------+-----------+ +| | | ``usdt+`` [#usdt]_ | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_TRACE_KPROBE_MULTI`` | ``kprobe.multi+`` [#kpmulti]_ | | ++ + +----------------------------------+-----------+ +| | | ``kretprobe.multi+`` [#kpmulti]_ | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_LIRC_MODE2`` | ``BPF_LIRC_MODE2`` | ``lirc_mode2`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_LSM`` | ``BPF_LSM_CGROUP`` | ``lsm_cgroup+`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_LSM_MAC`` | ``lsm+`` [#lsm]_ | | ++ + +----------------------------------+-----------+ +| | | ``lsm.s+`` [#lsm]_ | Yes | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_LWT_IN`` | | ``lwt_in`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_LWT_OUT`` | | ``lwt_out`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_LWT_SEG6LOCAL`` | | ``lwt_seg6local`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_LWT_XMIT`` | | ``lwt_xmit`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_PERF_EVENT`` | | ``perf_event`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_RAW_TRACEPOINT_WRITABLE`` | | ``raw_tp.w+`` [#rawtp]_ | | ++ + +----------------------------------+-----------+ +| | | ``raw_tracepoint.w+`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_RAW_TRACEPOINT`` | | ``raw_tp+`` [#rawtp]_ | | ++ + +----------------------------------+-----------+ +| | | ``raw_tracepoint+`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_SCHED_ACT`` | | ``action`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_SCHED_CLS`` | | ``classifier`` | | ++ + +----------------------------------+-----------+ +| | | ``tc`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_SK_LOOKUP`` | ``BPF_SK_LOOKUP`` | ``sk_lookup`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_SK_MSG`` | ``BPF_SK_MSG_VERDICT`` | ``sk_msg`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_SK_REUSEPORT`` | ``BPF_SK_REUSEPORT_SELECT_OR_MIGRATE`` | ``sk_reuseport/migrate`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_SK_REUSEPORT_SELECT`` | ``sk_reuseport`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_SK_SKB`` | | ``sk_skb`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_SK_SKB_STREAM_PARSER`` | ``sk_skb/stream_parser`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_SK_SKB_STREAM_VERDICT`` | ``sk_skb/stream_verdict`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_SOCKET_FILTER`` | | ``socket`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_SOCK_OPS`` | ``BPF_CGROUP_SOCK_OPS`` | ``sockops`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_STRUCT_OPS`` | | ``struct_ops+`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_SYSCALL`` | | ``syscall`` | Yes | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_TRACEPOINT`` | | ``tp+`` [#tp]_ | | ++ + +----------------------------------+-----------+ +| | | ``tracepoint+`` [#tp]_ | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_TRACING`` | ``BPF_MODIFY_RETURN`` | ``fmod_ret+`` [#fentry]_ | | ++ + +----------------------------------+-----------+ +| | | ``fmod_ret.s+`` [#fentry]_ | Yes | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_TRACE_FENTRY`` | ``fentry+`` [#fentry]_ | | ++ + +----------------------------------+-----------+ +| | | ``fentry.s+`` [#fentry]_ | Yes | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_TRACE_FEXIT`` | ``fexit+`` [#fentry]_ | | ++ + +----------------------------------+-----------+ +| | | ``fexit.s+`` [#fentry]_ | Yes | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_TRACE_ITER`` | ``iter+`` [#iter]_ | | ++ + +----------------------------------+-----------+ +| | | ``iter.s+`` [#iter]_ | Yes | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_TRACE_RAW_TP`` | ``tp_btf+`` [#fentry]_ | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ +| ``BPF_PROG_TYPE_XDP`` | ``BPF_XDP_CPUMAP`` | ``xdp.frags/cpumap`` | | ++ + +----------------------------------+-----------+ +| | | ``xdp/cpumap`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_XDP_DEVMAP`` | ``xdp.frags/devmap`` | | ++ + +----------------------------------+-----------+ +| | | ``xdp/devmap`` | | ++ +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_XDP`` | ``xdp.frags`` | | ++ + +----------------------------------+-----------+ +| | | ``xdp`` | | ++-------------------------------------------+----------------------------------------+----------------------------------+-----------+ + + +.. rubric:: Footnotes + +.. [#fentry] The ``fentry`` attach format is ``fentry[.s]/<function>``. +.. [#kprobe] The ``kprobe`` attach format is ``kprobe/<function>[+<offset>]``. Valid + characters for ``function`` are ``a-zA-Z0-9_.`` and ``offset`` must be a valid + non-negative integer. +.. [#ksyscall] The ``ksyscall`` attach format is ``ksyscall/<syscall>``. +.. [#uprobe] The ``uprobe`` attach format is ``uprobe[.s]/<path>:<function>[+<offset>]``. +.. [#usdt] The ``usdt`` attach format is ``usdt/<path>:<provider>:<name>``. +.. [#kpmulti] The ``kprobe.multi`` attach format is ``kprobe.multi/<pattern>`` where ``pattern`` + supports ``*`` and ``?`` wildcards. Valid characters for pattern are + ``a-zA-Z0-9_.*?``. +.. [#lsm] The ``lsm`` attachment format is ``lsm[.s]/<hook>``. +.. [#rawtp] The ``raw_tp`` attach format is ``raw_tracepoint[.w]/<tracepoint>``. +.. [#tp] The ``tracepoint`` attach format is ``tracepoint/<category>/<name>``. +.. [#iter] The ``iter`` attach format is ``iter[.s]/<struct-name>``. diff --git a/Documentation/bpf/map_array.rst b/Documentation/bpf/map_array.rst new file mode 100644 index 000000000000..f2f51a53e8ae --- /dev/null +++ b/Documentation/bpf/map_array.rst @@ -0,0 +1,262 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. Copyright (C) 2022 Red Hat, Inc. + +================================================ +BPF_MAP_TYPE_ARRAY and BPF_MAP_TYPE_PERCPU_ARRAY +================================================ + +.. note:: + - ``BPF_MAP_TYPE_ARRAY`` was introduced in kernel version 3.19 + - ``BPF_MAP_TYPE_PERCPU_ARRAY`` was introduced in version 4.6 + +``BPF_MAP_TYPE_ARRAY`` and ``BPF_MAP_TYPE_PERCPU_ARRAY`` provide generic array +storage. The key type is an unsigned 32-bit integer (4 bytes) and the map is +of constant size. The size of the array is defined in ``max_entries`` at +creation time. All array elements are pre-allocated and zero initialized when +created. ``BPF_MAP_TYPE_PERCPU_ARRAY`` uses a different memory region for each +CPU whereas ``BPF_MAP_TYPE_ARRAY`` uses the same memory region. The value +stored can be of any size, however, all array elements are aligned to 8 +bytes. + +Since kernel 5.5, memory mapping may be enabled for ``BPF_MAP_TYPE_ARRAY`` by +setting the flag ``BPF_F_MMAPABLE``. The map definition is page-aligned and +starts on the first page. Sufficient page-sized and page-aligned blocks of +memory are allocated to store all array values, starting on the second page, +which in some cases will result in over-allocation of memory. The benefit of +using this is increased performance and ease of use since userspace programs +would not be required to use helper functions to access and mutate data. + +Usage +===== + +Kernel BPF +---------- + +bpf_map_lookup_elem() +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + void *bpf_map_lookup_elem(struct bpf_map *map, const void *key) + +Array elements can be retrieved using the ``bpf_map_lookup_elem()`` helper. +This helper returns a pointer into the array element, so to avoid data races +with userspace reading the value, the user must use primitives like +``__sync_fetch_and_add()`` when updating the value in-place. + +bpf_map_update_elem() +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + long bpf_map_update_elem(struct bpf_map *map, const void *key, const void *value, u64 flags) + +Array elements can be updated using the ``bpf_map_update_elem()`` helper. + +``bpf_map_update_elem()`` returns 0 on success, or negative error in case of +failure. + +Since the array is of constant size, ``bpf_map_delete_elem()`` is not supported. +To clear an array element, you may use ``bpf_map_update_elem()`` to insert a +zero value to that index. + +Per CPU Array +------------- + +Values stored in ``BPF_MAP_TYPE_ARRAY`` can be accessed by multiple programs +across different CPUs. To restrict storage to a single CPU, you may use a +``BPF_MAP_TYPE_PERCPU_ARRAY``. + +When using a ``BPF_MAP_TYPE_PERCPU_ARRAY`` the ``bpf_map_update_elem()`` and +``bpf_map_lookup_elem()`` helpers automatically access the slot for the current +CPU. + +bpf_map_lookup_percpu_elem() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + void *bpf_map_lookup_percpu_elem(struct bpf_map *map, const void *key, u32 cpu) + +The ``bpf_map_lookup_percpu_elem()`` helper can be used to lookup the array +value for a specific CPU. Returns value on success , or ``NULL`` if no entry was +found or ``cpu`` is invalid. + +Concurrency +----------- + +Since kernel version 5.1, the BPF infrastructure provides ``struct bpf_spin_lock`` +to synchronize access. + +Userspace +--------- + +Access from userspace uses libbpf APIs with the same names as above, with +the map identified by its ``fd``. + +Examples +======== + +Please see the ``tools/testing/selftests/bpf`` directory for functional +examples. The code samples below demonstrate API usage. + +Kernel BPF +---------- + +This snippet shows how to declare an array in a BPF program. + +.. code-block:: c + + struct { + __uint(type, BPF_MAP_TYPE_ARRAY); + __type(key, u32); + __type(value, long); + __uint(max_entries, 256); + } my_map SEC(".maps"); + + +This example BPF program shows how to access an array element. + +.. code-block:: c + + int bpf_prog(struct __sk_buff *skb) + { + struct iphdr ip; + int index; + long *value; + + if (bpf_skb_load_bytes(skb, ETH_HLEN, &ip, sizeof(ip)) < 0) + return 0; + + index = ip.protocol; + value = bpf_map_lookup_elem(&my_map, &index); + if (value) + __sync_fetch_and_add(value, skb->len); + + return 0; + } + +Userspace +--------- + +BPF_MAP_TYPE_ARRAY +~~~~~~~~~~~~~~~~~~ + +This snippet shows how to create an array, using ``bpf_map_create_opts`` to +set flags. + +.. code-block:: c + + #include <bpf/libbpf.h> + #include <bpf/bpf.h> + + int create_array() + { + int fd; + LIBBPF_OPTS(bpf_map_create_opts, opts, .map_flags = BPF_F_MMAPABLE); + + fd = bpf_map_create(BPF_MAP_TYPE_ARRAY, + "example_array", /* name */ + sizeof(__u32), /* key size */ + sizeof(long), /* value size */ + 256, /* max entries */ + &opts); /* create opts */ + return fd; + } + +This snippet shows how to initialize the elements of an array. + +.. code-block:: c + + int initialize_array(int fd) + { + __u32 i; + long value; + int ret; + + for (i = 0; i < 256; i++) { + value = i; + ret = bpf_map_update_elem(fd, &i, &value, BPF_ANY); + if (ret < 0) + return ret; + } + + return ret; + } + +This snippet shows how to retrieve an element value from an array. + +.. code-block:: c + + int lookup(int fd) + { + __u32 index = 42; + long value; + int ret; + + ret = bpf_map_lookup_elem(fd, &index, &value); + if (ret < 0) + return ret; + + /* use value here */ + assert(value == 42); + + return ret; + } + +BPF_MAP_TYPE_PERCPU_ARRAY +~~~~~~~~~~~~~~~~~~~~~~~~~ + +This snippet shows how to initialize the elements of a per CPU array. + +.. code-block:: c + + int initialize_array(int fd) + { + int ncpus = libbpf_num_possible_cpus(); + long values[ncpus]; + __u32 i, j; + int ret; + + for (i = 0; i < 256 ; i++) { + for (j = 0; j < ncpus; j++) + values[j] = i; + ret = bpf_map_update_elem(fd, &i, &values, BPF_ANY); + if (ret < 0) + return ret; + } + + return ret; + } + +This snippet shows how to access the per CPU elements of an array value. + +.. code-block:: c + + int lookup(int fd) + { + int ncpus = libbpf_num_possible_cpus(); + __u32 index = 42, j; + long values[ncpus]; + int ret; + + ret = bpf_map_lookup_elem(fd, &index, &values); + if (ret < 0) + return ret; + + for (j = 0; j < ncpus; j++) { + /* Use per CPU value here */ + assert(values[j] == 42); + } + + return ret; + } + +Semantics +========= + +As shown in the example above, when accessing a ``BPF_MAP_TYPE_PERCPU_ARRAY`` +in userspace, each value is an array with ``ncpus`` elements. + +When calling ``bpf_map_update_elem()`` the flag ``BPF_NOEXIST`` can not be used +for these maps. diff --git a/Documentation/bpf/map_bloom_filter.rst b/Documentation/bpf/map_bloom_filter.rst new file mode 100644 index 000000000000..c82487f2fe0d --- /dev/null +++ b/Documentation/bpf/map_bloom_filter.rst @@ -0,0 +1,174 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. Copyright (C) 2022 Red Hat, Inc. + +========================= +BPF_MAP_TYPE_BLOOM_FILTER +========================= + +.. note:: + - ``BPF_MAP_TYPE_BLOOM_FILTER`` was introduced in kernel version 5.16 + +``BPF_MAP_TYPE_BLOOM_FILTER`` provides a BPF bloom filter map. Bloom +filters are a space-efficient probabilistic data structure used to +quickly test whether an element exists in a set. In a bloom filter, +false positives are possible whereas false negatives are not. + +The bloom filter map does not have keys, only values. When the bloom +filter map is created, it must be created with a ``key_size`` of 0. The +bloom filter map supports two operations: + +- push: adding an element to the map +- peek: determining whether an element is present in the map + +BPF programs must use ``bpf_map_push_elem`` to add an element to the +bloom filter map and ``bpf_map_peek_elem`` to query the map. These +operations are exposed to userspace applications using the existing +``bpf`` syscall in the following way: + +- ``BPF_MAP_UPDATE_ELEM`` -> push +- ``BPF_MAP_LOOKUP_ELEM`` -> peek + +The ``max_entries`` size that is specified at map creation time is used +to approximate a reasonable bitmap size for the bloom filter, and is not +otherwise strictly enforced. If the user wishes to insert more entries +into the bloom filter than ``max_entries``, this may lead to a higher +false positive rate. + +The number of hashes to use for the bloom filter is configurable using +the lower 4 bits of ``map_extra`` in ``union bpf_attr`` at map creation +time. If no number is specified, the default used will be 5 hash +functions. In general, using more hashes decreases both the false +positive rate and the speed of a lookup. + +It is not possible to delete elements from a bloom filter map. A bloom +filter map may be used as an inner map. The user is responsible for +synchronising concurrent updates and lookups to ensure no false negative +lookups occur. + +Usage +===== + +Kernel BPF +---------- + +bpf_map_push_elem() +~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + long bpf_map_push_elem(struct bpf_map *map, const void *value, u64 flags) + +A ``value`` can be added to a bloom filter using the +``bpf_map_push_elem()`` helper. The ``flags`` parameter must be set to +``BPF_ANY`` when adding an entry to the bloom filter. This helper +returns ``0`` on success, or negative error in case of failure. + +bpf_map_peek_elem() +~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + long bpf_map_peek_elem(struct bpf_map *map, void *value) + +The ``bpf_map_peek_elem()`` helper is used to determine whether +``value`` is present in the bloom filter map. This helper returns ``0`` +if ``value`` is probably present in the map, or ``-ENOENT`` if ``value`` +is definitely not present in the map. + +Userspace +--------- + +bpf_map_update_elem() +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + int bpf_map_update_elem (int fd, const void *key, const void *value, __u64 flags) + +A userspace program can add a ``value`` to a bloom filter using libbpf's +``bpf_map_update_elem`` function. The ``key`` parameter must be set to +``NULL`` and ``flags`` must be set to ``BPF_ANY``. Returns ``0`` on +success, or negative error in case of failure. + +bpf_map_lookup_elem() +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + int bpf_map_lookup_elem (int fd, const void *key, void *value) + +A userspace program can determine the presence of ``value`` in a bloom +filter using libbpf's ``bpf_map_lookup_elem`` function. The ``key`` +parameter must be set to ``NULL``. Returns ``0`` if ``value`` is +probably present in the map, or ``-ENOENT`` if ``value`` is definitely +not present in the map. + +Examples +======== + +Kernel BPF +---------- + +This snippet shows how to declare a bloom filter in a BPF program: + +.. code-block:: c + + struct { + __uint(type, BPF_MAP_TYPE_BLOOM_FILTER); + __type(value, __u32); + __uint(max_entries, 1000); + __uint(map_extra, 3); + } bloom_filter SEC(".maps"); + +This snippet shows how to determine presence of a value in a bloom +filter in a BPF program: + +.. code-block:: c + + void *lookup(__u32 key) + { + if (bpf_map_peek_elem(&bloom_filter, &key) == 0) { + /* Verify not a false positive and fetch an associated + * value using a secondary lookup, e.g. in a hash table + */ + return bpf_map_lookup_elem(&hash_table, &key); + } + return 0; + } + +Userspace +--------- + +This snippet shows how to use libbpf to create a bloom filter map from +userspace: + +.. code-block:: c + + int create_bloom() + { + LIBBPF_OPTS(bpf_map_create_opts, opts, + .map_extra = 3); /* number of hashes */ + + return bpf_map_create(BPF_MAP_TYPE_BLOOM_FILTER, + "ipv6_bloom", /* name */ + 0, /* key size, must be zero */ + sizeof(ipv6_addr), /* value size */ + 10000, /* max entries */ + &opts); /* create options */ + } + +This snippet shows how to add an element to a bloom filter from +userspace: + +.. code-block:: c + + int add_element(struct bpf_map *bloom_map, __u32 value) + { + int bloom_fd = bpf_map__fd(bloom_map); + return bpf_map_update_elem(bloom_fd, NULL, &value, BPF_ANY); + } + +References +========== + +https://lwn.net/ml/bpf/20210831225005.2762202-1-joannekoong@fb.com/ diff --git a/Documentation/bpf/map_cgrp_storage.rst b/Documentation/bpf/map_cgrp_storage.rst new file mode 100644 index 000000000000..5d3f603efffa --- /dev/null +++ b/Documentation/bpf/map_cgrp_storage.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. Copyright (C) 2022 Meta Platforms, Inc. and affiliates. + +========================= +BPF_MAP_TYPE_CGRP_STORAGE +========================= + +The ``BPF_MAP_TYPE_CGRP_STORAGE`` map type represents a local fix-sized +storage for cgroups. It is only available with ``CONFIG_CGROUPS``. +The programs are made available by the same Kconfig. The +data for a particular cgroup can be retrieved by looking up the map +with that cgroup. + +This document describes the usage and semantics of the +``BPF_MAP_TYPE_CGRP_STORAGE`` map type. + +Usage +===== + +The map key must be ``sizeof(int)`` representing a cgroup fd. +To access the storage in a program, use ``bpf_cgrp_storage_get``:: + + void *bpf_cgrp_storage_get(struct bpf_map *map, struct cgroup *cgroup, void *value, u64 flags) + +``flags`` could be 0 or ``BPF_LOCAL_STORAGE_GET_F_CREATE`` which indicates that +a new local storage will be created if one does not exist. + +The local storage can be removed with ``bpf_cgrp_storage_delete``:: + + long bpf_cgrp_storage_delete(struct bpf_map *map, struct cgroup *cgroup) + +The map is available to all program types. + +Examples +======== + +A BPF program example with BPF_MAP_TYPE_CGRP_STORAGE:: + + #include <vmlinux.h> + #include <bpf/bpf_helpers.h> + #include <bpf/bpf_tracing.h> + + struct { + __uint(type, BPF_MAP_TYPE_CGRP_STORAGE); + __uint(map_flags, BPF_F_NO_PREALLOC); + __type(key, int); + __type(value, long); + } cgrp_storage SEC(".maps"); + + SEC("tp_btf/sys_enter") + int BPF_PROG(on_enter, struct pt_regs *regs, long id) + { + struct task_struct *task = bpf_get_current_task_btf(); + long *ptr; + + ptr = bpf_cgrp_storage_get(&cgrp_storage, task->cgroups->dfl_cgrp, 0, + BPF_LOCAL_STORAGE_GET_F_CREATE); + if (ptr) + __sync_fetch_and_add(ptr, 1); + + return 0; + } + +Userspace accessing map declared above:: + + #include <linux/bpf.h> + #include <linux/libbpf.h> + + __u32 map_lookup(struct bpf_map *map, int cgrp_fd) + { + __u32 *value; + value = bpf_map_lookup_elem(bpf_map__fd(map), &cgrp_fd); + if (value) + return *value; + return 0; + } + +Difference Between BPF_MAP_TYPE_CGRP_STORAGE and BPF_MAP_TYPE_CGROUP_STORAGE +============================================================================ + +The old cgroup storage map ``BPF_MAP_TYPE_CGROUP_STORAGE`` has been marked as +deprecated (renamed to ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED``). The new +``BPF_MAP_TYPE_CGRP_STORAGE`` map should be used instead. The following +illusates the main difference between ``BPF_MAP_TYPE_CGRP_STORAGE`` and +``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED``. + +(1). ``BPF_MAP_TYPE_CGRP_STORAGE`` can be used by all program types while + ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED`` is available only to cgroup program types + like BPF_CGROUP_INET_INGRESS or BPF_CGROUP_SOCK_OPS, etc. + +(2). ``BPF_MAP_TYPE_CGRP_STORAGE`` supports local storage for more than one + cgroup while ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED`` only supports one cgroup + which is attached by a BPF program. + +(3). ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED`` allocates local storage at attach time so + ``bpf_get_local_storage()`` always returns non-NULL local storage. + ``BPF_MAP_TYPE_CGRP_STORAGE`` allocates local storage at runtime so + it is possible that ``bpf_cgrp_storage_get()`` may return null local storage. + To avoid such null local storage issue, user space can do + ``bpf_map_update_elem()`` to pre-allocate local storage before a BPF program + is attached. + +(4). ``BPF_MAP_TYPE_CGRP_STORAGE`` supports deleting local storage by a BPF program + while ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED`` only deletes storage during + prog detach time. + +So overall, ``BPF_MAP_TYPE_CGRP_STORAGE`` supports all ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED`` +functionality and beyond. It is recommended to use ``BPF_MAP_TYPE_CGRP_STORAGE`` +instead of ``BPF_MAP_TYPE_CGROUP_STORAGE_DEPRECATED``. diff --git a/Documentation/bpf/map_cpumap.rst b/Documentation/bpf/map_cpumap.rst new file mode 100644 index 000000000000..923cfc8ab51f --- /dev/null +++ b/Documentation/bpf/map_cpumap.rst @@ -0,0 +1,177 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. Copyright (C) 2022 Red Hat, Inc. + +=================== +BPF_MAP_TYPE_CPUMAP +=================== + +.. note:: + - ``BPF_MAP_TYPE_CPUMAP`` was introduced in kernel version 4.15 + +.. kernel-doc:: kernel/bpf/cpumap.c + :doc: cpu map + +An example use-case for this map type is software based Receive Side Scaling (RSS). + +The CPUMAP represents the CPUs in the system indexed as the map-key, and the +map-value is the config setting (per CPUMAP entry). Each CPUMAP entry has a dedicated +kernel thread bound to the given CPU to represent the remote CPU execution unit. + +Starting from Linux kernel version 5.9 the CPUMAP can run a second XDP program +on the remote CPU. This allows an XDP program to split its processing across +multiple CPUs. For example, a scenario where the initial CPU (that sees/receives +the packets) needs to do minimal packet processing and the remote CPU (to which +the packet is directed) can afford to spend more cycles processing the frame. The +initial CPU is where the XDP redirect program is executed. The remote CPU +receives raw ``xdp_frame`` objects. + +Usage +===== + +Kernel BPF +---------- +bpf_redirect_map() +^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + long bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags) + +Redirect the packet to the endpoint referenced by ``map`` at index ``key``. +For ``BPF_MAP_TYPE_CPUMAP`` this map contains references to CPUs. + +The lower two bits of ``flags`` are used as the return code if the map lookup +fails. This is so that the return value can be one of the XDP program return +codes up to ``XDP_TX``, as chosen by the caller. + +User space +---------- +.. note:: + CPUMAP entries can only be updated/looked up/deleted from user space and not + from an eBPF program. Trying to call these functions from a kernel eBPF + program will result in the program failing to load and a verifier warning. + +bpf_map_update_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + int bpf_map_update_elem(int fd, const void *key, const void *value, __u64 flags); + +CPU entries can be added or updated using the ``bpf_map_update_elem()`` +helper. This helper replaces existing elements atomically. The ``value`` parameter +can be ``struct bpf_cpumap_val``. + + .. code-block:: c + + struct bpf_cpumap_val { + __u32 qsize; /* queue size to remote target CPU */ + union { + int fd; /* prog fd on map write */ + __u32 id; /* prog id on map read */ + } bpf_prog; + }; + +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); + +CPU entries can be retrieved using the ``bpf_map_lookup_elem()`` +helper. + +bpf_map_delete_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + int bpf_map_delete_elem(int fd, const void *key); + +CPU entries can be deleted using the ``bpf_map_delete_elem()`` +helper. This helper will return 0 on success, or negative error in case of +failure. + +Examples +======== +Kernel +------ + +The following code snippet shows how to declare a ``BPF_MAP_TYPE_CPUMAP`` called +``cpu_map`` and how to redirect packets to a remote CPU using a round robin scheme. + +.. code-block:: c + + struct { + __uint(type, BPF_MAP_TYPE_CPUMAP); + __type(key, __u32); + __type(value, struct bpf_cpumap_val); + __uint(max_entries, 12); + } cpu_map SEC(".maps"); + + struct { + __uint(type, BPF_MAP_TYPE_ARRAY); + __type(key, __u32); + __type(value, __u32); + __uint(max_entries, 12); + } cpus_available SEC(".maps"); + + struct { + __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY); + __type(key, __u32); + __type(value, __u32); + __uint(max_entries, 1); + } cpus_iterator SEC(".maps"); + + SEC("xdp") + int xdp_redir_cpu_round_robin(struct xdp_md *ctx) + { + __u32 key = 0; + __u32 cpu_dest = 0; + __u32 *cpu_selected, *cpu_iterator; + __u32 cpu_idx; + + cpu_iterator = bpf_map_lookup_elem(&cpus_iterator, &key); + if (!cpu_iterator) + return XDP_ABORTED; + cpu_idx = *cpu_iterator; + + *cpu_iterator += 1; + if (*cpu_iterator == bpf_num_possible_cpus()) + *cpu_iterator = 0; + + cpu_selected = bpf_map_lookup_elem(&cpus_available, &cpu_idx); + if (!cpu_selected) + return XDP_ABORTED; + cpu_dest = *cpu_selected; + + if (cpu_dest >= bpf_num_possible_cpus()) + return XDP_ABORTED; + + return bpf_redirect_map(&cpu_map, cpu_dest, 0); + } + +User space +---------- + +The following code snippet shows how to dynamically set the max_entries for a +CPUMAP to the max number of cpus available on the system. + +.. code-block:: c + + int set_max_cpu_entries(struct bpf_map *cpu_map) + { + if (bpf_map__set_max_entries(cpu_map, libbpf_num_possible_cpus()) < 0) { + fprintf(stderr, "Failed to set max entries for cpu_map map: %s", + strerror(errno)); + return -1; + } + return 0; + } + +References +=========== + +- https://developers.redhat.com/blog/2021/05/13/receive-side-scaling-rss-with-ebpf-and-cpumap#redirecting_into_a_cpumap diff --git a/Documentation/bpf/map_devmap.rst b/Documentation/bpf/map_devmap.rst new file mode 100644 index 000000000000..927312c7b8c8 --- /dev/null +++ b/Documentation/bpf/map_devmap.rst @@ -0,0 +1,238 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. Copyright (C) 2022 Red Hat, Inc. + +================================================= +BPF_MAP_TYPE_DEVMAP and BPF_MAP_TYPE_DEVMAP_HASH +================================================= + +.. note:: + - ``BPF_MAP_TYPE_DEVMAP`` was introduced in kernel version 4.14 + - ``BPF_MAP_TYPE_DEVMAP_HASH`` was introduced in kernel version 5.4 + +``BPF_MAP_TYPE_DEVMAP`` and ``BPF_MAP_TYPE_DEVMAP_HASH`` are BPF maps primarily +used as backend maps for the XDP BPF helper call ``bpf_redirect_map()``. +``BPF_MAP_TYPE_DEVMAP`` is backed by an array that uses the key as +the index to lookup a reference to a net device. While ``BPF_MAP_TYPE_DEVMAP_HASH`` +is backed by a hash table that uses a key to lookup a reference to a net device. +The user provides either <``key``/ ``ifindex``> or <``key``/ ``struct bpf_devmap_val``> +pairs to update the maps with new net devices. + +.. note:: + - The key to a hash map doesn't have to be an ``ifindex``. + - While ``BPF_MAP_TYPE_DEVMAP_HASH`` allows for densely packing the net devices + it comes at the cost of a hash of the key when performing a look up. + +The setup and packet enqueue/send code is shared between the two types of +devmap; only the lookup and insertion is different. + +Usage +===== +Kernel BPF +---------- +bpf_redirect_map() +^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + long bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags) + +Redirect the packet to the endpoint referenced by ``map`` at index ``key``. +For ``BPF_MAP_TYPE_DEVMAP`` and ``BPF_MAP_TYPE_DEVMAP_HASH`` this map contains +references to net devices (for forwarding packets through other ports). + +The lower two bits of *flags* are used as the return code if the map lookup +fails. This is so that the return value can be one of the XDP program return +codes up to ``XDP_TX``, as chosen by the caller. The higher bits of ``flags`` +can be set to ``BPF_F_BROADCAST`` or ``BPF_F_EXCLUDE_INGRESS`` as defined +below. + +With ``BPF_F_BROADCAST`` the packet will be broadcast to all the interfaces +in the map, with ``BPF_F_EXCLUDE_INGRESS`` the ingress interface will be excluded +from the broadcast. + +.. note:: + - The key is ignored if BPF_F_BROADCAST is set. + - The broadcast feature can also be used to implement multicast forwarding: + simply create multiple DEVMAPs, each one corresponding to a single multicast group. + +This helper will return ``XDP_REDIRECT`` on success, or the value of the two +lower bits of the ``flags`` argument if the map lookup fails. + +More information about redirection can be found :doc:`redirect` + +bpf_map_lookup_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + void *bpf_map_lookup_elem(struct bpf_map *map, const void *key) + +Net device entries can be retrieved using the ``bpf_map_lookup_elem()`` +helper. + +User space +---------- +.. note:: + DEVMAP entries can only be updated/deleted from user space and not + from an eBPF program. Trying to call these functions from a kernel eBPF + program will result in the program failing to load and a verifier warning. + +bpf_map_update_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + int bpf_map_update_elem(int fd, const void *key, const void *value, __u64 flags); + +Net device entries can be added or updated using the ``bpf_map_update_elem()`` +helper. This helper replaces existing elements atomically. The ``value`` parameter +can be ``struct bpf_devmap_val`` or a simple ``int ifindex`` for backwards +compatibility. + + .. code-block:: c + + struct bpf_devmap_val { + __u32 ifindex; /* device index */ + union { + int fd; /* prog fd on map write */ + __u32 id; /* prog id on map read */ + } bpf_prog; + }; + +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. + +DEVMAPs can associate a program with a device entry by adding a ``bpf_prog.fd`` +to ``struct bpf_devmap_val``. Programs are run after ``XDP_REDIRECT`` and have +access to both Rx device and Tx device. The program associated with the ``fd`` +must have type XDP with expected attach type ``xdp_devmap``. +When a program is associated with a device index, the program is run on an +``XDP_REDIRECT`` and before the buffer is added to the per-cpu queue. Examples +of how to attach/use xdp_devmap progs can be found in the kernel selftests: + +- ``tools/testing/selftests/bpf/prog_tests/xdp_devmap_attach.c`` +- ``tools/testing/selftests/bpf/progs/test_xdp_with_devmap_helpers.c`` + +bpf_map_lookup_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + +.. c:function:: + int bpf_map_lookup_elem(int fd, const void *key, void *value); + +Net device entries can be retrieved using the ``bpf_map_lookup_elem()`` +helper. + +bpf_map_delete_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + +.. c:function:: + int bpf_map_delete_elem(int fd, const void *key); + +Net device entries can be deleted using the ``bpf_map_delete_elem()`` +helper. This helper will return 0 on success, or negative error in case of +failure. + +Examples +======== + +Kernel BPF +---------- + +The following code snippet shows how to declare a ``BPF_MAP_TYPE_DEVMAP`` +called tx_port. + +.. code-block:: c + + struct { + __uint(type, BPF_MAP_TYPE_DEVMAP); + __type(key, __u32); + __type(value, __u32); + __uint(max_entries, 256); + } tx_port SEC(".maps"); + +The following code snippet shows how to declare a ``BPF_MAP_TYPE_DEVMAP_HASH`` +called forward_map. + +.. code-block:: c + + struct { + __uint(type, BPF_MAP_TYPE_DEVMAP_HASH); + __type(key, __u32); + __type(value, struct bpf_devmap_val); + __uint(max_entries, 32); + } forward_map SEC(".maps"); + +.. note:: + + The value type in the DEVMAP above is a ``struct bpf_devmap_val`` + +The following code snippet shows a simple xdp_redirect_map program. This program +would work with a user space program that populates the devmap ``forward_map`` based +on ingress ifindexes. The BPF program (below) is redirecting packets using the +ingress ``ifindex`` as the ``key``. + +.. code-block:: c + + SEC("xdp") + int xdp_redirect_map_func(struct xdp_md *ctx) + { + int index = ctx->ingress_ifindex; + + return bpf_redirect_map(&forward_map, index, 0); + } + +The following code snippet shows a BPF program that is broadcasting packets to +all the interfaces in the ``tx_port`` devmap. + +.. code-block:: c + + SEC("xdp") + int xdp_redirect_map_func(struct xdp_md *ctx) + { + return bpf_redirect_map(&tx_port, 0, BPF_F_BROADCAST | BPF_F_EXCLUDE_INGRESS); + } + +User space +---------- + +The following code snippet shows how to update a devmap called ``tx_port``. + +.. code-block:: c + + int update_devmap(int ifindex, int redirect_ifindex) + { + int ret; + + ret = bpf_map_update_elem(bpf_map__fd(tx_port), &ifindex, &redirect_ifindex, 0); + if (ret < 0) { + fprintf(stderr, "Failed to update devmap_ value: %s\n", + strerror(errno)); + } + + return ret; + } + +The following code snippet shows how to update a hash_devmap called ``forward_map``. + +.. code-block:: c + + int update_devmap(int ifindex, int redirect_ifindex) + { + struct bpf_devmap_val devmap_val = { .ifindex = redirect_ifindex }; + int ret; + + ret = bpf_map_update_elem(bpf_map__fd(forward_map), &ifindex, &devmap_val, 0); + if (ret < 0) { + fprintf(stderr, "Failed to update devmap_ value: %s\n", + strerror(errno)); + } + return ret; + } + +References +=========== + +- https://lwn.net/Articles/728146/ +- https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/commit/?id=6f9d451ab1a33728adb72d7ff66a7b374d665176 +- https://elixir.bootlin.com/linux/latest/source/net/core/filter.c#L4106 diff --git a/Documentation/bpf/map_hash.rst b/Documentation/bpf/map_hash.rst index e85120878b27..8669426264c6 100644 --- a/Documentation/bpf/map_hash.rst +++ b/Documentation/bpf/map_hash.rst @@ -34,7 +34,14 @@ the ``BPF_F_NO_COMMON_LRU`` flag when calling ``bpf_map_create``. Usage ===== -.. c:function:: +Kernel BPF +---------- + +bpf_map_update_elem() +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + long bpf_map_update_elem(struct bpf_map *map, const void *key, const void *value, u64 flags) Hash entries can be added or updated using the ``bpf_map_update_elem()`` @@ -49,14 +56,22 @@ parameter can be used to control the update behaviour: ``bpf_map_update_elem()`` returns 0 on success, or negative error in case of failure. -.. c:function:: +bpf_map_lookup_elem() +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + void *bpf_map_lookup_elem(struct bpf_map *map, const void *key) Hash entries can be retrieved using the ``bpf_map_lookup_elem()`` helper. This helper returns a pointer to the value associated with ``key``, or ``NULL`` if no entry was found. -.. c:function:: +bpf_map_delete_elem() +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + long bpf_map_delete_elem(struct bpf_map *map, const void *key) Hash entries can be deleted using the ``bpf_map_delete_elem()`` @@ -70,7 +85,11 @@ For ``BPF_MAP_TYPE_PERCPU_HASH`` and ``BPF_MAP_TYPE_LRU_PERCPU_HASH`` the ``bpf_map_update_elem()`` and ``bpf_map_lookup_elem()`` helpers automatically access the hash slot for the current CPU. -.. c:function:: +bpf_map_lookup_percpu_elem() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + void *bpf_map_lookup_percpu_elem(struct bpf_map *map, const void *key, u32 cpu) The ``bpf_map_lookup_percpu_elem()`` helper can be used to lookup the @@ -89,7 +108,11 @@ See ``tools/testing/selftests/bpf/progs/test_spin_lock.c``. Userspace --------- -.. c:function:: +bpf_map_get_next_key() +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + int bpf_map_get_next_key(int fd, const void *cur_key, void *next_key) In userspace, it is possible to iterate through the keys of a hash using diff --git a/Documentation/bpf/map_lpm_trie.rst b/Documentation/bpf/map_lpm_trie.rst new file mode 100644 index 000000000000..74d64a30f500 --- /dev/null +++ b/Documentation/bpf/map_lpm_trie.rst @@ -0,0 +1,197 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. Copyright (C) 2022 Red Hat, Inc. + +===================== +BPF_MAP_TYPE_LPM_TRIE +===================== + +.. note:: + - ``BPF_MAP_TYPE_LPM_TRIE`` was introduced in kernel version 4.11 + +``BPF_MAP_TYPE_LPM_TRIE`` provides a longest prefix match algorithm that +can be used to match IP addresses to a stored set of prefixes. +Internally, data is stored in an unbalanced trie of nodes that uses +``prefixlen,data`` pairs as its keys. The ``data`` is interpreted in +network byte order, i.e. big endian, so ``data[0]`` stores the most +significant byte. + +LPM tries may be created with a maximum prefix length that is a multiple +of 8, in the range from 8 to 2048. The key used for lookup and update +operations is a ``struct bpf_lpm_trie_key``, extended by +``max_prefixlen/8`` bytes. + +- For IPv4 addresses the data length is 4 bytes +- For IPv6 addresses the data length is 16 bytes + +The value type stored in the LPM trie can be any user defined type. + +.. note:: + When creating a map of type ``BPF_MAP_TYPE_LPM_TRIE`` you must set the + ``BPF_F_NO_PREALLOC`` flag. + +Usage +===== + +Kernel BPF +---------- + +bpf_map_lookup_elem() +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + void *bpf_map_lookup_elem(struct bpf_map *map, const void *key) + +The longest prefix entry for a given data value can be found using the +``bpf_map_lookup_elem()`` helper. This helper returns a pointer to the +value associated with the longest matching ``key``, or ``NULL`` if no +entry was found. + +The ``key`` should have ``prefixlen`` set to ``max_prefixlen`` when +performing longest prefix lookups. For example, when searching for the +longest prefix match for an IPv4 address, ``prefixlen`` should be set to +``32``. + +bpf_map_update_elem() +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + long bpf_map_update_elem(struct bpf_map *map, const void *key, const void *value, u64 flags) + +Prefix entries can be added or updated using the ``bpf_map_update_elem()`` +helper. This helper replaces existing elements atomically. + +``bpf_map_update_elem()`` returns ``0`` on success, or negative error in +case of failure. + + .. note:: + The flags parameter must be one of BPF_ANY, BPF_NOEXIST or BPF_EXIST, + but the value is ignored, giving BPF_ANY semantics. + +bpf_map_delete_elem() +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + long bpf_map_delete_elem(struct bpf_map *map, const void *key) + +Prefix entries can be deleted using the ``bpf_map_delete_elem()`` +helper. This helper will return 0 on success, or negative error in case +of failure. + +Userspace +--------- + +Access from userspace uses libbpf APIs with the same names as above, with +the map identified by ``fd``. + +bpf_map_get_next_key() +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + int bpf_map_get_next_key (int fd, const void *cur_key, void *next_key) + +A userspace program can iterate through the entries in an LPM trie using +libbpf's ``bpf_map_get_next_key()`` function. The first key can be +fetched by calling ``bpf_map_get_next_key()`` with ``cur_key`` set to +``NULL``. Subsequent calls will fetch the next key that follows the +current key. ``bpf_map_get_next_key()`` returns ``0`` on success, +``-ENOENT`` if ``cur_key`` is the last key in the trie, or negative +error in case of failure. + +``bpf_map_get_next_key()`` will iterate through the LPM trie elements +from leftmost leaf first. This means that iteration will return more +specific keys before less specific ones. + +Examples +======== + +Please see ``tools/testing/selftests/bpf/test_lpm_map.c`` for examples +of LPM trie usage from userspace. The code snippets below demonstrate +API usage. + +Kernel BPF +---------- + +The following BPF code snippet shows how to declare a new LPM trie for IPv4 +address prefixes: + +.. code-block:: c + + #include <linux/bpf.h> + #include <bpf/bpf_helpers.h> + + struct ipv4_lpm_key { + __u32 prefixlen; + __u32 data; + }; + + struct { + __uint(type, BPF_MAP_TYPE_LPM_TRIE); + __type(key, struct ipv4_lpm_key); + __type(value, __u32); + __uint(map_flags, BPF_F_NO_PREALLOC); + __uint(max_entries, 255); + } ipv4_lpm_map SEC(".maps"); + +The following BPF code snippet shows how to lookup by IPv4 address: + +.. code-block:: c + + void *lookup(__u32 ipaddr) + { + struct ipv4_lpm_key key = { + .prefixlen = 32, + .data = ipaddr + }; + + return bpf_map_lookup_elem(&ipv4_lpm_map, &key); + } + +Userspace +--------- + +The following snippet shows how to insert an IPv4 prefix entry into an +LPM trie: + +.. code-block:: c + + int add_prefix_entry(int lpm_fd, __u32 addr, __u32 prefixlen, struct value *value) + { + struct ipv4_lpm_key ipv4_key = { + .prefixlen = prefixlen, + .data = addr + }; + return bpf_map_update_elem(lpm_fd, &ipv4_key, value, BPF_ANY); + } + +The following snippet shows a userspace program walking through the entries +of an LPM trie: + + +.. code-block:: c + + #include <bpf/libbpf.h> + #include <bpf/bpf.h> + + void iterate_lpm_trie(int map_fd) + { + struct ipv4_lpm_key *cur_key = NULL; + struct ipv4_lpm_key next_key; + struct value value; + int err; + + for (;;) { + err = bpf_map_get_next_key(map_fd, cur_key, &next_key); + if (err) + break; + + bpf_map_lookup_elem(map_fd, &next_key, &value); + + /* Use key and value here */ + + cur_key = &next_key; + } + } diff --git a/Documentation/bpf/map_of_maps.rst b/Documentation/bpf/map_of_maps.rst new file mode 100644 index 000000000000..7b5617c2d017 --- /dev/null +++ b/Documentation/bpf/map_of_maps.rst @@ -0,0 +1,130 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. Copyright (C) 2022 Red Hat, Inc. + +======================================================== +BPF_MAP_TYPE_ARRAY_OF_MAPS and BPF_MAP_TYPE_HASH_OF_MAPS +======================================================== + +.. note:: + - ``BPF_MAP_TYPE_ARRAY_OF_MAPS`` and ``BPF_MAP_TYPE_HASH_OF_MAPS`` were + introduced in kernel version 4.12 + +``BPF_MAP_TYPE_ARRAY_OF_MAPS`` and ``BPF_MAP_TYPE_HASH_OF_MAPS`` provide general +purpose support for map in map storage. One level of nesting is supported, where +an outer map contains instances of a single type of inner map, for example +``array_of_maps->sock_map``. + +When creating an outer map, an inner map instance is used to initialize the +metadata that the outer map holds about its inner maps. This inner map has a +separate lifetime from the outer map and can be deleted after the outer map has +been created. + +The outer map supports element lookup, update and delete from user space using +the syscall API. A BPF program is only allowed to do element lookup in the outer +map. + +.. note:: + - Multi-level nesting is not supported. + - Any BPF map type can be used as an inner map, except for + ``BPF_MAP_TYPE_PROG_ARRAY``. + - A BPF program cannot update or delete outer map entries. + +For ``BPF_MAP_TYPE_ARRAY_OF_MAPS`` the key is an unsigned 32-bit integer index +into the array. The array is a fixed size with ``max_entries`` elements that are +zero initialized when created. + +For ``BPF_MAP_TYPE_HASH_OF_MAPS`` the key type can be chosen when defining the +map. The kernel is responsible for allocating and freeing key/value pairs, up to +the max_entries limit that you specify. Hash maps use pre-allocation of hash +table elements by default. The ``BPF_F_NO_PREALLOC`` flag can be used to disable +pre-allocation when it is too memory expensive. + +Usage +===== + +Kernel BPF Helper +----------------- + +bpf_map_lookup_elem() +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + void *bpf_map_lookup_elem(struct bpf_map *map, const void *key) + +Inner maps can be retrieved using the ``bpf_map_lookup_elem()`` helper. This +helper returns a pointer to the inner map, or ``NULL`` if no entry was found. + +Examples +======== + +Kernel BPF Example +------------------ + +This snippet shows how to create and initialise an array of devmaps in a BPF +program. Note that the outer array can only be modified from user space using +the syscall API. + +.. code-block:: c + + struct inner_map { + __uint(type, BPF_MAP_TYPE_DEVMAP); + __uint(max_entries, 10); + __type(key, __u32); + __type(value, __u32); + } inner_map1 SEC(".maps"), inner_map2 SEC(".maps"); + + struct { + __uint(type, BPF_MAP_TYPE_ARRAY_OF_MAPS); + __uint(max_entries, 2); + __type(key, __u32); + __array(values, struct inner_map); + } outer_map SEC(".maps") = { + .values = { &inner_map1, + &inner_map2 } + }; + +See ``progs/test_btf_map_in_map.c`` in ``tools/testing/selftests/bpf`` for more +examples of declarative initialisation of outer maps. + +User Space +---------- + +This snippet shows how to create an array based outer map: + +.. code-block:: c + + int create_outer_array(int inner_fd) { + LIBBPF_OPTS(bpf_map_create_opts, opts, .inner_map_fd = inner_fd); + int fd; + + fd = bpf_map_create(BPF_MAP_TYPE_ARRAY_OF_MAPS, + "example_array", /* name */ + sizeof(__u32), /* key size */ + sizeof(__u32), /* value size */ + 256, /* max entries */ + &opts); /* create opts */ + return fd; + } + + +This snippet shows how to add an inner map to an outer map: + +.. code-block:: c + + int add_devmap(int outer_fd, int index, const char *name) { + int fd; + + fd = bpf_map_create(BPF_MAP_TYPE_DEVMAP, name, + sizeof(__u32), sizeof(__u32), 256, NULL); + if (fd < 0) + return fd; + + return bpf_map_update_elem(outer_fd, &index, &fd, BPF_ANY); + } + +References +========== + +- https://lore.kernel.org/netdev/20170322170035.923581-3-kafai@fb.com/ +- https://lore.kernel.org/netdev/20170322170035.923581-4-kafai@fb.com/ diff --git a/Documentation/bpf/map_queue_stack.rst b/Documentation/bpf/map_queue_stack.rst new file mode 100644 index 000000000000..8d14ed49d6e1 --- /dev/null +++ b/Documentation/bpf/map_queue_stack.rst @@ -0,0 +1,146 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. Copyright (C) 2022 Red Hat, Inc. + +========================================= +BPF_MAP_TYPE_QUEUE and BPF_MAP_TYPE_STACK +========================================= + +.. note:: + - ``BPF_MAP_TYPE_QUEUE`` and ``BPF_MAP_TYPE_STACK`` were introduced + in kernel version 4.20 + +``BPF_MAP_TYPE_QUEUE`` provides FIFO storage and ``BPF_MAP_TYPE_STACK`` +provides LIFO storage for BPF programs. These maps support peek, pop and +push operations that are exposed to BPF programs through the respective +helpers. These operations are exposed to userspace applications using +the existing ``bpf`` syscall in the following way: + +- ``BPF_MAP_LOOKUP_ELEM`` -> peek +- ``BPF_MAP_LOOKUP_AND_DELETE_ELEM`` -> pop +- ``BPF_MAP_UPDATE_ELEM`` -> push + +``BPF_MAP_TYPE_QUEUE`` and ``BPF_MAP_TYPE_STACK`` do not support +``BPF_F_NO_PREALLOC``. + +Usage +===== + +Kernel BPF +---------- + +bpf_map_push_elem() +~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + long bpf_map_push_elem(struct bpf_map *map, const void *value, u64 flags) + +An element ``value`` can be added to a queue or stack using the +``bpf_map_push_elem`` helper. The ``flags`` parameter must be set to +``BPF_ANY`` or ``BPF_EXIST``. If ``flags`` is set to ``BPF_EXIST`` then, +when the queue or stack is full, the oldest element will be removed to +make room for ``value`` to be added. Returns ``0`` on success, or +negative error in case of failure. + +bpf_map_peek_elem() +~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + long bpf_map_peek_elem(struct bpf_map *map, void *value) + +This helper fetches an element ``value`` from a queue or stack without +removing it. Returns ``0`` on success, or negative error in case of +failure. + +bpf_map_pop_elem() +~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + long bpf_map_pop_elem(struct bpf_map *map, void *value) + +This helper removes an element into ``value`` from a queue or +stack. Returns ``0`` on success, or negative error in case of failure. + + +Userspace +--------- + +bpf_map_update_elem() +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + int bpf_map_update_elem (int fd, const void *key, const void *value, __u64 flags) + +A userspace program can push ``value`` onto a queue or stack using libbpf's +``bpf_map_update_elem`` function. The ``key`` parameter must be set to +``NULL`` and ``flags`` must be set to ``BPF_ANY`` or ``BPF_EXIST``, with the +same semantics as the ``bpf_map_push_elem`` kernel helper. Returns ``0`` on +success, or negative error in case of failure. + +bpf_map_lookup_elem() +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + int bpf_map_lookup_elem (int fd, const void *key, void *value) + +A userspace program can peek at the ``value`` at the head of a queue or stack +using the libbpf ``bpf_map_lookup_elem`` function. The ``key`` parameter must be +set to ``NULL``. Returns ``0`` on success, or negative error in case of +failure. + +bpf_map_lookup_and_delete_elem() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + int bpf_map_lookup_and_delete_elem (int fd, const void *key, void *value) + +A userspace program can pop a ``value`` from the head of a queue or stack using +the libbpf ``bpf_map_lookup_and_delete_elem`` function. The ``key`` parameter +must be set to ``NULL``. Returns ``0`` on success, or negative error in case of +failure. + +Examples +======== + +Kernel BPF +---------- + +This snippet shows how to declare a queue in a BPF program: + +.. code-block:: c + + struct { + __uint(type, BPF_MAP_TYPE_QUEUE); + __type(value, __u32); + __uint(max_entries, 10); + } queue SEC(".maps"); + + +Userspace +--------- + +This snippet shows how to use libbpf's low-level API to create a queue from +userspace: + +.. code-block:: c + + int create_queue() + { + return bpf_map_create(BPF_MAP_TYPE_QUEUE, + "sample_queue", /* name */ + 0, /* key size, must be zero */ + sizeof(__u32), /* value size */ + 10, /* max entries */ + NULL); /* create options */ + } + + +References +========== + +https://lwn.net/ml/netdev/153986858555.9127.14517764371945179514.stgit@kernel/ diff --git a/Documentation/bpf/map_sk_storage.rst b/Documentation/bpf/map_sk_storage.rst new file mode 100644 index 000000000000..047e16c8aaa8 --- /dev/null +++ b/Documentation/bpf/map_sk_storage.rst @@ -0,0 +1,155 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. Copyright (C) 2022 Red Hat, Inc. + +======================= +BPF_MAP_TYPE_SK_STORAGE +======================= + +.. note:: + - ``BPF_MAP_TYPE_SK_STORAGE`` was introduced in kernel version 5.2 + +``BPF_MAP_TYPE_SK_STORAGE`` is used to provide socket-local storage for BPF +programs. A map of type ``BPF_MAP_TYPE_SK_STORAGE`` declares the type of storage +to be provided and acts as the handle for accessing the socket-local +storage. The values for maps of type ``BPF_MAP_TYPE_SK_STORAGE`` are stored +locally with each socket instead of with the map. The kernel is responsible for +allocating storage for a socket when requested and for freeing the storage when +either the map or the socket is deleted. + +.. note:: + - The key type must be ``int`` and ``max_entries`` must be set to ``0``. + - The ``BPF_F_NO_PREALLOC`` flag must be used when creating a map for + socket-local storage. + +Usage +===== + +Kernel BPF +---------- + +bpf_sk_storage_get() +~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + void *bpf_sk_storage_get(struct bpf_map *map, void *sk, void *value, u64 flags) + +Socket-local storage can be retrieved using the ``bpf_sk_storage_get()`` +helper. The helper gets the storage from ``sk`` that is associated with ``map``. +If the ``BPF_LOCAL_STORAGE_GET_F_CREATE`` flag is used then +``bpf_sk_storage_get()`` will create the storage for ``sk`` if it does not +already exist. ``value`` can be used together with +``BPF_LOCAL_STORAGE_GET_F_CREATE`` to initialize the storage value, otherwise it +will be zero initialized. Returns a pointer to the storage on success, or +``NULL`` in case of failure. + +.. note:: + - ``sk`` is a kernel ``struct sock`` pointer for LSM or tracing programs. + - ``sk`` is a ``struct bpf_sock`` pointer for other program types. + +bpf_sk_storage_delete() +~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + long bpf_sk_storage_delete(struct bpf_map *map, void *sk) + +Socket-local storage can be deleted using the ``bpf_sk_storage_delete()`` +helper. The helper deletes the storage from ``sk`` that is identified by +``map``. Returns ``0`` on success, or negative error in case of failure. + +User space +---------- + +bpf_map_update_elem() +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + int bpf_map_update_elem(int map_fd, const void *key, const void *value, __u64 flags) + +Socket-local storage for the socket identified by ``key`` belonging to +``map_fd`` can be added or updated using the ``bpf_map_update_elem()`` libbpf +function. ``key`` must be a pointer to a valid ``fd`` in the user space +program. The ``flags`` parameter can be used to control the update behaviour: + +- ``BPF_ANY`` will create storage for ``fd`` or update existing storage. +- ``BPF_NOEXIST`` will create storage for ``fd`` only if it did not already + exist, otherwise the call will fail with ``-EEXIST``. +- ``BPF_EXIST`` will update existing storage for ``fd`` if it already exists, + otherwise the call will fail with ``-ENOENT``. + +Returns ``0`` on success, or negative error in case of failure. + +bpf_map_lookup_elem() +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + int bpf_map_lookup_elem(int map_fd, const void *key, void *value) + +Socket-local storage for the socket identified by ``key`` belonging to +``map_fd`` can be retrieved using the ``bpf_map_lookup_elem()`` libbpf +function. ``key`` must be a pointer to a valid ``fd`` in the user space +program. Returns ``0`` on success, or negative error in case of failure. + +bpf_map_delete_elem() +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + int bpf_map_delete_elem(int map_fd, const void *key) + +Socket-local storage for the socket identified by ``key`` belonging to +``map_fd`` can be deleted using the ``bpf_map_delete_elem()`` libbpf +function. Returns ``0`` on success, or negative error in case of failure. + +Examples +======== + +Kernel BPF +---------- + +This snippet shows how to declare socket-local storage in a BPF program: + +.. code-block:: c + + struct { + __uint(type, BPF_MAP_TYPE_SK_STORAGE); + __uint(map_flags, BPF_F_NO_PREALLOC); + __type(key, int); + __type(value, struct my_storage); + } socket_storage SEC(".maps"); + +This snippet shows how to retrieve socket-local storage in a BPF program: + +.. code-block:: c + + SEC("sockops") + int _sockops(struct bpf_sock_ops *ctx) + { + struct my_storage *storage; + struct bpf_sock *sk; + + sk = ctx->sk; + if (!sk) + return 1; + + storage = bpf_sk_storage_get(&socket_storage, sk, 0, + BPF_LOCAL_STORAGE_GET_F_CREATE); + if (!storage) + return 1; + + /* Use 'storage' here */ + + return 1; + } + + +Please see the ``tools/testing/selftests/bpf`` directory for functional +examples. + +References +========== + +https://lwn.net/ml/netdev/20190426171103.61892-1-kafai@fb.com/ diff --git a/Documentation/bpf/map_xskmap.rst b/Documentation/bpf/map_xskmap.rst new file mode 100644 index 000000000000..7093b8208451 --- /dev/null +++ b/Documentation/bpf/map_xskmap.rst @@ -0,0 +1,192 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. Copyright (C) 2022 Red Hat, Inc. + +=================== +BPF_MAP_TYPE_XSKMAP +=================== + +.. note:: + - ``BPF_MAP_TYPE_XSKMAP`` was introduced in kernel version 4.18 + +The ``BPF_MAP_TYPE_XSKMAP`` is used as a backend map for XDP BPF helper +call ``bpf_redirect_map()`` and ``XDP_REDIRECT`` action, like 'devmap' and 'cpumap'. +This map type redirects raw XDP frames to `AF_XDP`_ sockets (XSKs), a new type of +address family in the kernel that allows redirection of frames from a driver to +user space without having to traverse the full network stack. An AF_XDP socket +binds to a single netdev queue. A mapping of XSKs to queues is shown below: + +.. code-block:: none + + +---------------------------------------------------+ + | xsk A | xsk B | xsk C |<---+ User space + =========================================================|========== + | Queue 0 | Queue 1 | Queue 2 | | Kernel + +---------------------------------------------------+ | + | Netdev eth0 | | + +---------------------------------------------------+ | + | +=============+ | | + | | key | xsk | | | + | +---------+ +=============+ | | + | | | | 0 | xsk A | | | + | | | +-------------+ | | + | | | | 1 | xsk B | | | + | | BPF |-- redirect -->+-------------+-------------+ + | | prog | | 2 | xsk C | | + | | | +-------------+ | + | | | | + | | | | + | +---------+ | + | | + +---------------------------------------------------+ + +.. note:: + An AF_XDP socket that is bound to a certain <netdev/queue_id> will *only* + accept XDP frames from that <netdev/queue_id>. If an XDP program tries to redirect + from a <netdev/queue_id> other than what the socket is bound to, the frame will + not be received on the socket. + +Typically an XSKMAP is created per netdev. This map contains an array of XSK File +Descriptors (FDs). The number of array elements is typically set or adjusted using +the ``max_entries`` map parameter. For AF_XDP ``max_entries`` is equal to the number +of queues supported by the netdev. + +.. note:: + Both the map key and map value size must be 4 bytes. + +Usage +===== + +Kernel BPF +---------- +bpf_redirect_map() +^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + long bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags) + +Redirect the packet to the endpoint referenced by ``map`` at index ``key``. +For ``BPF_MAP_TYPE_XSKMAP`` this map contains references to XSK FDs +for sockets attached to a netdev's queues. + +.. note:: + If the map is empty at an index, the packet is dropped. This means that it is + necessary to have an XDP program loaded with at least one XSK in the + XSKMAP to be able to get any traffic to user space through the socket. + +bpf_map_lookup_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + void *bpf_map_lookup_elem(struct bpf_map *map, const void *key) + +XSK entry references of type ``struct xdp_sock *`` can be retrieved using the +``bpf_map_lookup_elem()`` helper. + +User space +---------- +.. note:: + XSK entries can only be updated/deleted from user space and not from + a BPF program. Trying to call these functions from a kernel BPF program will + result in the program failing to load and a verifier warning. + +bpf_map_update_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + int bpf_map_update_elem(int fd, const void *key, const void *value, __u64 flags) + +XSK entries can be added or updated using the ``bpf_map_update_elem()`` +helper. The ``key`` parameter is equal to the queue_id of the queue the XSK +is attaching to. And the ``value`` parameter is the FD value of that socket. + +Under the hood, the XSKMAP update function uses the XSK FD value to retrieve the +associated ``struct xdp_sock`` instance. + +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) + +Returns ``struct xdp_sock *`` or negative error in case of failure. + +bpf_map_delete_elem() +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c + + int bpf_map_delete_elem(int fd, const void *key) + +XSK entries can be deleted using the ``bpf_map_delete_elem()`` +helper. This helper will return 0 on success, or negative error in case of +failure. + +.. note:: + When `libxdp`_ deletes an XSK it also removes the associated socket + entry from the XSKMAP. + +Examples +======== +Kernel +------ + +The following code snippet shows how to declare a ``BPF_MAP_TYPE_XSKMAP`` called +``xsks_map`` and how to redirect packets to an XSK. + +.. code-block:: c + + struct { + __uint(type, BPF_MAP_TYPE_XSKMAP); + __type(key, __u32); + __type(value, __u32); + __uint(max_entries, 64); + } xsks_map SEC(".maps"); + + + SEC("xdp") + int xsk_redir_prog(struct xdp_md *ctx) + { + __u32 index = ctx->rx_queue_index; + + if (bpf_map_lookup_elem(&xsks_map, &index)) + return bpf_redirect_map(&xsks_map, index, 0); + return XDP_PASS; + } + +User space +---------- + +The following code snippet shows how to update an XSKMAP with an XSK entry. + +.. code-block:: c + + int update_xsks_map(struct bpf_map *xsks_map, int queue_id, int xsk_fd) + { + int ret; + + ret = bpf_map_update_elem(bpf_map__fd(xsks_map), &queue_id, &xsk_fd, 0); + if (ret < 0) + fprintf(stderr, "Failed to update xsks_map: %s\n", strerror(errno)); + + return ret; + } + +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: + +- `libxdp-readme`_. +- `AF_XDP`_ kernel documentation. + +.. note:: + The most comprehensive resource for using XSKMAPs and AF_XDP is `libxdp`_. + +.. _libxdp: https://github.com/xdp-project/xdp-tools/tree/master/lib/libxdp +.. _AF_XDP: https://www.kernel.org/doc/html/latest/networking/af_xdp.html +.. _bpf-examples: https://github.com/xdp-project/bpf-examples +.. _libxdp-readme: https://github.com/xdp-project/xdp-tools/tree/master/lib/libxdp#using-af_xdp-sockets diff --git a/Documentation/bpf/maps.rst b/Documentation/bpf/maps.rst index f41619e312ac..4906ff0f8382 100644 --- a/Documentation/bpf/maps.rst +++ b/Documentation/bpf/maps.rst @@ -1,52 +1,81 @@ -========= -eBPF maps +======== +BPF maps +======== + +BPF 'maps' provide generic storage of different types for sharing data between +kernel and user space. There are several storage types available, including +hash, array, bloom filter and radix-tree. Several of the map types exist to +support specific BPF helpers that perform actions based on the map contents. The +maps are accessed from BPF programs via BPF helpers which are documented in the +`man-pages`_ for `bpf-helpers(7)`_. + +BPF maps are accessed from user space via the ``bpf`` syscall, which provides +commands to create maps, lookup elements, update elements and delete +elements. More details of the BPF syscall are available in +:doc:`/userspace-api/ebpf/syscall` and in the `man-pages`_ for `bpf(2)`_. + +Map Types ========= -'maps' is a generic storage of different types for sharing data between kernel -and userspace. +.. toctree:: + :maxdepth: 1 + :glob: -The maps are accessed from user space via BPF syscall, which has commands: + map_* -- create a map with given type and attributes - ``map_fd = bpf(BPF_MAP_CREATE, union bpf_attr *attr, u32 size)`` - using attr->map_type, attr->key_size, attr->value_size, attr->max_entries - returns process-local file descriptor or negative error +Usage Notes +=========== -- lookup key in a given map - ``err = bpf(BPF_MAP_LOOKUP_ELEM, union bpf_attr *attr, u32 size)`` - using attr->map_fd, attr->key, attr->value - returns zero and stores found elem into value or negative error +.. c:function:: + int bpf(int command, union bpf_attr *attr, u32 size) -- create or update key/value pair in a given map - ``err = bpf(BPF_MAP_UPDATE_ELEM, union bpf_attr *attr, u32 size)`` - using attr->map_fd, attr->key, attr->value - returns zero or negative error +Use the ``bpf()`` system call to perform the operation specified by +``command``. The operation takes parameters provided in ``attr``. The ``size`` +argument is the size of the ``union bpf_attr`` in ``attr``. -- find and delete element by key in a given map - ``err = bpf(BPF_MAP_DELETE_ELEM, union bpf_attr *attr, u32 size)`` - using attr->map_fd, attr->key +**BPF_MAP_CREATE** -- to delete map: close(fd) - Exiting process will delete maps automatically +Create a map with the desired type and attributes in ``attr``: -userspace programs use this syscall to create/access maps that eBPF programs -are concurrently updating. +.. code-block:: c -maps can have different types: hash, array, bloom filter, radix-tree, etc. + int fd; + union bpf_attr attr = { + .map_type = BPF_MAP_TYPE_ARRAY; /* mandatory */ + .key_size = sizeof(__u32); /* mandatory */ + .value_size = sizeof(__u32); /* mandatory */ + .max_entries = 256; /* mandatory */ + .map_flags = BPF_F_MMAPABLE; + .map_name = "example_array"; + }; -The map is defined by: + fd = bpf(BPF_MAP_CREATE, &attr, sizeof(attr)); - - type - - max number of elements - - key size in bytes - - value size in bytes +Returns a process-local file descriptor on success, or negative error in case of +failure. The map can be deleted by calling ``close(fd)``. Maps held by open +file descriptors will be deleted automatically when a process exits. -Map Types -========= +.. note:: Valid characters for ``map_name`` are ``A-Z``, ``a-z``, ``0-9``, + ``'_'`` and ``'.'``. -.. toctree:: - :maxdepth: 1 - :glob: +**BPF_MAP_LOOKUP_ELEM** + +Lookup key in a given map using ``attr->map_fd``, ``attr->key``, +``attr->value``. Returns zero and stores found elem into ``attr->value`` on +success, or negative error on failure. + +**BPF_MAP_UPDATE_ELEM** + +Create or update key/value pair in a given map using ``attr->map_fd``, ``attr->key``, +``attr->value``. Returns zero on success or negative error on failure. + +**BPF_MAP_DELETE_ELEM** + +Find and delete element by key in a given map using ``attr->map_fd``, +``attr->key``. Returns zero on success or negative error on failure. - map_*
\ No newline at end of file +.. Links: +.. _man-pages: https://www.kernel.org/doc/man-pages/ +.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html +.. _bpf-helpers(7): https://man7.org/linux/man-pages/man7/bpf-helpers.7.html diff --git a/Documentation/bpf/programs.rst b/Documentation/bpf/programs.rst index 620eb667ac7a..c99000ab6d9b 100644 --- a/Documentation/bpf/programs.rst +++ b/Documentation/bpf/programs.rst @@ -7,3 +7,6 @@ Program Types :glob: prog_* + +For a list of all program types, see :ref:`program_types_and_elf` in +the :ref:`libbpf` documentation. diff --git a/Documentation/bpf/redirect.rst b/Documentation/bpf/redirect.rst new file mode 100644 index 000000000000..2fa2b0b05004 --- /dev/null +++ b/Documentation/bpf/redirect.rst @@ -0,0 +1,81 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. Copyright (C) 2022 Red Hat, Inc. + +======== +Redirect +======== +XDP_REDIRECT +############ +Supported maps +-------------- + +XDP_REDIRECT works with the following map types: + +- ``BPF_MAP_TYPE_DEVMAP`` +- ``BPF_MAP_TYPE_DEVMAP_HASH`` +- ``BPF_MAP_TYPE_CPUMAP`` +- ``BPF_MAP_TYPE_XSKMAP`` + +For more information on these maps, please see the specific map documentation. + +Process +------- + +.. kernel-doc:: net/core/filter.c + :doc: xdp redirect + +.. note:: + Not all drivers support transmitting frames after a redirect, and for + those that do, not all of them support non-linear frames. Non-linear xdp + bufs/frames are bufs/frames that contain more than one fragment. + +Debugging packet drops +---------------------- +Silent packet drops for XDP_REDIRECT can be debugged using: + +- bpf_trace +- perf_record + +bpf_trace +^^^^^^^^^ +The following bpftrace command can be used to capture and count all XDP tracepoints: + +.. code-block:: none + + sudo bpftrace -e 'tracepoint:xdp:* { @cnt[probe] = count(); }' + Attaching 12 probes... + ^C + + @cnt[tracepoint:xdp:mem_connect]: 18 + @cnt[tracepoint:xdp:mem_disconnect]: 18 + @cnt[tracepoint:xdp:xdp_exception]: 19605 + @cnt[tracepoint:xdp:xdp_devmap_xmit]: 1393604 + @cnt[tracepoint:xdp:xdp_redirect]: 22292200 + +.. note:: + The various xdp tracepoints can be found in ``source/include/trace/events/xdp.h`` + +The following bpftrace command can be used to extract the ``ERRNO`` being returned as +part of the err parameter: + +.. code-block:: none + + sudo bpftrace -e \ + 'tracepoint:xdp:xdp_redirect*_err {@redir_errno[-args->err] = count();} + tracepoint:xdp:xdp_devmap_xmit {@devmap_errno[-args->err] = count();}' + +perf record +^^^^^^^^^^^ +The perf tool also supports recording tracepoints: + +.. code-block:: none + + perf record -a -e xdp:xdp_redirect_err \ + -e xdp:xdp_redirect_map_err \ + -e xdp:xdp_exception \ + -e xdp:xdp_devmap_xmit + +References +=========== + +- https://github.com/xdp-project/xdp-tutorial/tree/master/tracing02-xdp-monitor diff --git a/Documentation/conf.py b/Documentation/conf.py index b50c85083149..a5c45df0bd83 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -194,6 +194,24 @@ finally: else: version = release = "unknown version" +# +# HACK: there seems to be no easy way for us to get at the version and +# release information passed in from the makefile...so go pawing through the +# command-line options and find it for ourselves. +# +def get_cline_version(): + c_version = c_release = '' + for arg in sys.argv: + if arg.startswith('version='): + c_version = arg[8:] + elif arg.startswith('release='): + c_release = arg[8:] + if c_version: + if c_release: + return c_version + '-' + c_release + return c_version + return version # Whatever we came up with before + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # @@ -247,7 +265,7 @@ highlight_language = 'none' # a list of builtin themes. # Default theme -html_theme = 'sphinx_rtd_theme' +html_theme = 'alabaster' html_css_files = [] if "DOCS_THEME" in os.environ: @@ -278,8 +296,12 @@ if html_theme == 'sphinx_rtd_theme' or html_theme == 'sphinx_rtd_dark_mode': # Add color-specific RTD normal mode html_css_files.append('theme_rtd_colors.css') + html_theme_options = { + 'navigation_depth': -1, + } + except ImportError: - html_theme = 'classic' + html_theme = 'alabaster' if "DOCS_CSS" in os.environ: css = os.environ["DOCS_CSS"].split(" ") @@ -295,127 +317,29 @@ if major <= 1 and minor < 8: for l in html_css_files: html_context['css_files'].append('_static/' + l) -if html_theme == 'classic': +if html_theme == 'alabaster': html_theme_options = { - 'rightsidebar': False, - 'stickysidebar': True, - 'collapsiblesidebar': True, - 'externalrefs': False, - - 'footerbgcolor': "white", - 'footertextcolor': "white", - 'sidebarbgcolor': "white", - 'sidebarbtncolor': "black", - 'sidebartextcolor': "black", - 'sidebarlinkcolor': "#686bff", - 'relbarbgcolor': "#133f52", - 'relbartextcolor': "white", - 'relbarlinkcolor': "white", - 'bgcolor': "white", - 'textcolor': "black", - 'headbgcolor': "#f2f2f2", - 'headtextcolor': "#20435c", - 'headlinkcolor': "#c60f0f", - 'linkcolor': "#355f7c", - 'visitedlinkcolor': "#355f7c", - 'codebgcolor': "#3f3f3f", - 'codetextcolor': "white", - - 'bodyfont': "serif", - 'headfont': "sans-serif", + 'description': get_cline_version(), + 'page_width': '65em', + 'sidebar_width': '15em', + 'font_size': 'inherit', + 'font_family': 'serif', } sys.stderr.write("Using %s theme\n" % html_theme) -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['sphinx-static'] -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -#html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. html_use_smartypants = False # Custom sidebar templates, maps document names to template names. -# Note that the RTD theme ignores this. -html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a <link> tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' -#html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# Now only 'ja' uses this config value -#html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' +# Note that the RTD theme ignores this +html_sidebars = { '**': ["about.html", 'searchbox.html', 'localtoc.html', 'sourcelink.html']} # Output file base name for HTML help builder. htmlhelp_basename = 'TheLinuxKerneldoc' @@ -558,19 +482,6 @@ texinfo_documents = [ 'Miscellaneous'), ] -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False - - # -- Options for Epub output ---------------------------------------------- # Bibliographic Dublin Core info. @@ -579,67 +490,9 @@ epub_author = author epub_publisher = author epub_copyright = copyright -# The basename for the epub file. It defaults to the project name. -#epub_basename = project - -# The HTML theme for the epub output. Since the default themes are not -# optimized for small screen space, using the same theme for HTML and epub -# output is usually not wise. This defaults to 'epub', a theme designed to save -# visual space. -#epub_theme = 'epub' - -# The language of the text. It defaults to the language option -# or 'en' if the language is not set. -#epub_language = '' - -# The scheme of the identifier. Typical schemes are ISBN or URL. -#epub_scheme = '' - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -#epub_identifier = '' - -# A unique identification for the text. -#epub_uid = '' - -# A tuple containing the cover image and cover page html template filenames. -#epub_cover = () - -# A sequence of (type, uri, title) tuples for the guide element of content.opf. -#epub_guide = () - -# HTML files that should be inserted before the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_pre_files = [] - -# HTML files that should be inserted after the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_post_files = [] - # A list of files that should not be packed into the epub file. epub_exclude_files = ['search.html'] -# The depth of the table of contents in toc.ncx. -#epub_tocdepth = 3 - -# Allow duplicate toc entries. -#epub_tocdup = True - -# Choose between 'default' and 'includehidden'. -#epub_tocscope = 'default' - -# Fix unsupported image types using the Pillow. -#epub_fix_images = False - -# Scale large images. -#epub_max_image_width = 0 - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#epub_show_urls = 'inline' - -# If false, no index is generated. -#epub_use_index = True - #======= # rst2pdf # diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index 06f4ab122697..62f961610773 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -36,6 +36,9 @@ String Conversions String Manipulation ------------------- +.. kernel-doc:: include/linux/fortify-string.h + :internal: + .. kernel-doc:: lib/string.c :export: @@ -171,9 +174,6 @@ Division Functions .. kernel-doc:: include/linux/math64.h :internal: -.. kernel-doc:: lib/math/div64.c - :functions: div_s64_rem div64_u64_rem div64_u64 div64_s64 - .. kernel-doc:: lib/math/gcd.c :export: diff --git a/Documentation/core-api/local_ops.rst b/Documentation/core-api/local_ops.rst index 2ac3f9f29845..0b42ceaaf3c4 100644 --- a/Documentation/core-api/local_ops.rst +++ b/Documentation/core-api/local_ops.rst @@ -191,7 +191,7 @@ Here is a sample module which implements a basic per cpu counter using static void __exit test_exit(void) { - del_timer_sync(&test_timer); + timer_shutdown_sync(&test_timer); } module_init(test_init); diff --git a/Documentation/cpu-freq/index.rst b/Documentation/cpu-freq/index.rst index aba7831ab1cb..2fe32dad562a 100644 --- a/Documentation/cpu-freq/index.rst +++ b/Documentation/cpu-freq/index.rst @@ -20,18 +20,15 @@ Author: Dominik Brodowski <linux@brodo.de> Mailing List ------------ -There is a CPU frequency changing CVS commit and general list where -you can report bugs, problems or submit patches. To post a message, -send an email to linux-pm@vger.kernel.org. +There is a CPU frequency general list where you can report bugs, +problems or submit patches. To post a message, send an email to +linux-pm@vger.kernel.org. Links ----- the FTP archives: * ftp://ftp.linux.org.uk/pub/linux/cpufreq/ -how to access the CVS repository: -* http://cvs.arm.linux.org.uk/ - the CPUFreq Mailing list: * http://vger.kernel.org/vger-lists.html#linux-pm diff --git a/Documentation/crypto/devel-algos.rst b/Documentation/crypto/devel-algos.rst index f225a953ab4b..3506899ef83e 100644 --- a/Documentation/crypto/devel-algos.rst +++ b/Documentation/crypto/devel-algos.rst @@ -172,7 +172,7 @@ Here are schematics of how these functions are called when operated from other part of the kernel. Note that the .setkey() call might happen before or after any of these schematics happen, but must not happen during any of these are in-flight. Please note that calling .init() -followed immediately by .finish() is also a perfectly valid +followed immediately by .final() is also a perfectly valid transformation. :: diff --git a/Documentation/crypto/userspace-if.rst b/Documentation/crypto/userspace-if.rst index b45dabbf69d6..f80f243e227e 100644 --- a/Documentation/crypto/userspace-if.rst +++ b/Documentation/crypto/userspace-if.rst @@ -131,9 +131,9 @@ from the kernel crypto API. If the buffer is too small for the message digest, the flag MSG_TRUNC is set by the kernel. In order to set a message digest key, the calling application must use -the setsockopt() option of ALG_SET_KEY. If the key is not set the HMAC -operation is performed without the initial HMAC state change caused by -the key. +the setsockopt() option of ALG_SET_KEY or ALG_SET_KEY_BY_KEY_SERIAL. If the +key is not set the HMAC operation is performed without the initial HMAC state +change caused by the key. Symmetric Cipher API -------------------- @@ -382,6 +382,15 @@ mentioned optname: - the RNG cipher type to provide the seed +- ALG_SET_KEY_BY_KEY_SERIAL -- Setting the key via keyring key_serial_t. + This operation behaves the same as ALG_SET_KEY. The decrypted + data is copied from a keyring key, and uses that data as the + key for symmetric encryption. + + The passed in key_serial_t must have the KEY_(POS|USR|GRP|OTH)_SEARCH + permission set, otherwise -EPERM is returned. Supports key types: user, + logon, encrypted, and trusted. + - ALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size for AEAD ciphers. For a encryption operation, the authentication tag of the given size will be generated. For a decryption operation, the diff --git a/Documentation/dev-tools/kmsan.rst b/Documentation/dev-tools/kmsan.rst index 2a53a801198c..55fa82212eb2 100644 --- a/Documentation/dev-tools/kmsan.rst +++ b/Documentation/dev-tools/kmsan.rst @@ -67,6 +67,7 @@ uninitialized in the local variable, as well as the stack where the value was copied to another memory location before use. A use of uninitialized value ``v`` is reported by KMSAN in the following cases: + - in a condition, e.g. ``if (v) { ... }``; - in an indexing or pointer dereferencing, e.g. ``array[v]`` or ``*v``; - when it is copied to userspace or hardware, e.g. ``copy_to_user(..., &v, ...)``; diff --git a/Documentation/dev-tools/ktap.rst b/Documentation/dev-tools/ktap.rst index d0a9565b0f44..414c105b10a9 100644 --- a/Documentation/dev-tools/ktap.rst +++ b/Documentation/dev-tools/ktap.rst @@ -80,8 +80,8 @@ have the number 1 and the number then must increase by 1 for each additional subtest within the same test at the same nesting level. The description is a description of the test, generally the name of -the test, and can be any string of words (can't include #). The -description is optional, but recommended. +the test, and can be any string of characters other than # or a +newline. The description is optional, but recommended. The directive and any diagnostic data is optional. If either are present, they must follow a hash sign, "#". diff --git a/Documentation/dev-tools/kunit/architecture.rst b/Documentation/dev-tools/kunit/architecture.rst index 8efe792bdcb9..e95ab05342bb 100644 --- a/Documentation/dev-tools/kunit/architecture.rst +++ b/Documentation/dev-tools/kunit/architecture.rst @@ -4,16 +4,17 @@ KUnit Architecture ================== -The KUnit architecture can be divided into two parts: +The KUnit architecture is divided into two parts: - `In-Kernel Testing Framework`_ -- `kunit_tool (Command Line Test Harness)`_ +- `kunit_tool (Command-line Test Harness)`_ In-Kernel Testing Framework =========================== The kernel testing library supports KUnit tests written in C using -KUnit. KUnit tests are kernel code. KUnit does several things: +KUnit. These KUnit tests are kernel code. KUnit performs the following +tasks: - Organizes tests - Reports test results @@ -22,19 +23,17 @@ KUnit. KUnit tests are kernel code. KUnit does several things: Test Cases ---------- -The fundamental unit in KUnit is the test case. The KUnit test cases are -grouped into KUnit suites. A KUnit test case is a function with type -signature ``void (*)(struct kunit *test)``. -These test case functions are wrapped in a struct called -struct kunit_case. +The test case is the fundamental unit in KUnit. KUnit test cases are organised +into suites. A KUnit test case is a function with type signature +``void (*)(struct kunit *test)``. These test case functions are wrapped in a +struct called struct kunit_case. .. note: ``generate_params`` is optional for non-parameterized tests. -Each KUnit test case gets a ``struct kunit`` context -object passed to it that tracks a running test. The KUnit assertion -macros and other KUnit utilities use the ``struct kunit`` context -object. As an exception, there are two fields: +Each KUnit test case receives a ``struct kunit`` context object that tracks a +running test. The KUnit assertion macros and other KUnit utilities use the +``struct kunit`` context object. As an exception, there are two fields: - ``->priv``: The setup functions can use it to store arbitrary test user data. @@ -77,12 +76,13 @@ Executor The KUnit executor can list and run built-in KUnit tests on boot. The Test suites are stored in a linker section -called ``.kunit_test_suites``. For code, see: -https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v5.15#n945. +called ``.kunit_test_suites``. For the code, see ``KUNIT_TABLE()`` macro +definition in +`include/asm-generic/vmlinux.lds.h <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v6.0#n950>`_. The linker section consists of an array of pointers to ``struct kunit_suite``, and is populated by the ``kunit_test_suites()`` -macro. To run all tests compiled into the kernel, the KUnit executor -iterates over the linker section array. +macro. The KUnit executor iterates over the linker section array in order to +run all the tests that are compiled into the kernel. .. kernel-figure:: kunit_suitememorydiagram.svg :alt: KUnit Suite Memory @@ -90,17 +90,17 @@ iterates over the linker section array. KUnit Suite Memory Diagram On the kernel boot, the KUnit executor uses the start and end addresses -of this section to iterate over and run all tests. For code, see: -https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c - +of this section to iterate over and run all tests. For the implementation of the +executor, see +`lib/kunit/executor.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c>`_. When built as a module, the ``kunit_test_suites()`` macro defines a ``module_init()`` function, which runs all the tests in the compilation unit instead of utilizing the executor. In KUnit tests, some error classes do not affect other tests or parts of the kernel, each KUnit case executes in a separate thread -context. For code, see: -https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58 +context. See the ``kunit_try_catch_run()`` function in +`lib/kunit/try-catch.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58>`_. Assertion Macros ---------------- @@ -111,37 +111,36 @@ All expectations/assertions are formatted as: - ``{EXPECT|ASSERT}`` determines whether the check is an assertion or an expectation. + In the event of a failure, the testing flow differs as follows: - - For an expectation, if the check fails, marks the test as failed - and logs the failure. + - For expectations, the test is marked as failed and the failure is logged. - - An assertion, on failure, causes the test case to terminate - immediately. + - Failing assertions, on the other hand, result in the test case being + terminated immediately. - - Assertions call function: + - Assertions call the function: ``void __noreturn kunit_abort(struct kunit *)``. - - ``kunit_abort`` calls function: + - ``kunit_abort`` calls the function: ``void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch)``. - - ``kunit_try_catch_throw`` calls function: + - ``kunit_try_catch_throw`` calls the function: ``void kthread_complete_and_exit(struct completion *, long) __noreturn;`` and terminates the special thread context. - ``<op>`` denotes a check with options: ``TRUE`` (supplied property - has the boolean value “true”), ``EQ`` (two supplied properties are + has the boolean value "true"), ``EQ`` (two supplied properties are equal), ``NOT_ERR_OR_NULL`` (supplied pointer is not null and does not - contain an “err” value). + contain an "err" value). - ``[_MSG]`` prints a custom message on failure. Test Result Reporting --------------------- -KUnit prints test results in KTAP format. KTAP is based on TAP14, see: -https://github.com/isaacs/testanything.github.io/blob/tap14/tap-version-14-specification.md. -KTAP (yet to be standardized format) works with KUnit and Kselftest. -The KUnit executor prints KTAP results to dmesg, and debugfs -(if configured). +KUnit prints the test results in KTAP format. KTAP is based on TAP14, see +Documentation/dev-tools/ktap.rst. +KTAP works with KUnit and Kselftest. The KUnit executor prints KTAP results to +dmesg, and debugfs (if configured). Parameterized Tests ------------------- @@ -150,33 +149,35 @@ Each KUnit parameterized test is associated with a collection of parameters. The test is invoked multiple times, once for each parameter value and the parameter is stored in the ``param_value`` field. The test case includes a KUNIT_CASE_PARAM() macro that accepts a -generator function. -The generator function is passed the previous parameter and returns the next -parameter. It also provides a macro to generate common-case generators based on -arrays. +generator function. The generator function is passed the previous parameter +and returns the next parameter. It also includes a macro for generating +array-based common-case generators. -kunit_tool (Command Line Test Harness) +kunit_tool (Command-line Test Harness) ====================================== -kunit_tool is a Python script ``(tools/testing/kunit/kunit.py)`` -that can be used to configure, build, exec, parse and run (runs other -commands in order) test results. You can either run KUnit tests using -kunit_tool or can include KUnit in kernel and parse manually. +``kunit_tool`` is a Python script, found in ``tools/testing/kunit/kunit.py``. It +is used to configure, build, execute, parse test results and run all of the +previous commands in correct order (i.e., configure, build, execute and parse). +You have two options for running KUnit tests: either build the kernel with KUnit +enabled and manually parse the results (see +Documentation/dev-tools/kunit/run_manual.rst) or use ``kunit_tool`` +(see Documentation/dev-tools/kunit/run_wrapper.rst). - ``configure`` command generates the kernel ``.config`` from a ``.kunitconfig`` file (and any architecture-specific options). - For some architectures, additional config options are specified in the - ``qemu_config`` Python script - (For example: ``tools/testing/kunit/qemu_configs/powerpc.py``). + The Python scripts available in ``qemu_configs`` folder + (for example, ``tools/testing/kunit/qemu configs/powerpc.py``) contains + additional configuration options for specific architectures. It parses both the existing ``.config`` and the ``.kunitconfig`` files - and ensures that ``.config`` is a superset of ``.kunitconfig``. - If this is not the case, it will combine the two and run - ``make olddefconfig`` to regenerate the ``.config`` file. It then - verifies that ``.config`` is now a superset. This checks if all - Kconfig dependencies are correctly specified in ``.kunitconfig``. - ``kunit_config.py`` includes the parsing Kconfigs code. The code which - runs ``make olddefconfig`` is a part of ``kunit_kernel.py``. You can - invoke this command via: ``./tools/testing/kunit/kunit.py config`` and + to ensure that ``.config`` is a superset of ``.kunitconfig``. + If not, it will combine the two and run ``make olddefconfig`` to regenerate + the ``.config`` file. It then checks to see if ``.config`` has become a superset. + This verifies that all the Kconfig dependencies are correctly specified in the + file ``.kunitconfig``. The ``kunit_config.py`` script contains the code for parsing + Kconfigs. The code which runs ``make olddefconfig`` is part of the + ``kunit_kernel.py`` script. You can invoke this command through: + ``./tools/testing/kunit/kunit.py config`` and generate a ``.config`` file. - ``build`` runs ``make`` on the kernel tree with required options (depends on the architecture and some options, for example: build_dir) @@ -184,8 +185,8 @@ kunit_tool or can include KUnit in kernel and parse manually. To build a KUnit kernel from the current ``.config``, you can use the ``build`` argument: ``./tools/testing/kunit/kunit.py build``. - ``exec`` command executes kernel results either directly (using - User-mode Linux configuration), or via an emulator such - as QEMU. It reads results from the log via standard + User-mode Linux configuration), or through an emulator such + as QEMU. It reads results from the log using standard output (stdout), and passes them to ``parse`` to be parsed. If you already have built a kernel with built-in KUnit tests, you can run the kernel and display the test results with the ``exec`` diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst index f5d13f1d37be..b3593ae29ace 100644 --- a/Documentation/dev-tools/kunit/index.rst +++ b/Documentation/dev-tools/kunit/index.rst @@ -16,7 +16,6 @@ KUnit - Linux Kernel Unit Testing api/index style faq - tips running_tips This section details the kernel unit testing framework. @@ -100,14 +99,11 @@ Read also :ref:`kinds-of-tests`. How do I use it? ================ -* Documentation/dev-tools/kunit/start.rst - for KUnit new users. -* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture. -* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool. -* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool. -* Documentation/dev-tools/kunit/usage.rst - write tests. -* Documentation/dev-tools/kunit/tips.rst - best practices with - examples. -* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs - used for testing. -* Documentation/dev-tools/kunit/faq.rst - KUnit common questions and - answers. +You can find a step-by-step guide to writing and running KUnit tests in +Documentation/dev-tools/kunit/start.rst + +Alternatively, feel free to look through the rest of the KUnit documentation, +or to experiment with tools/testing/kunit/kunit.py and the example test under +lib/kunit/kunit-example-test.c + +Happy testing! diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst index f4f504f1fb15..c736613c9b19 100644 --- a/Documentation/dev-tools/kunit/start.rst +++ b/Documentation/dev-tools/kunit/start.rst @@ -294,13 +294,11 @@ Congrats! You just wrote your first KUnit test. Next Steps ========== -* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture. -* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool. -* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool. -* Documentation/dev-tools/kunit/usage.rst - write tests. -* Documentation/dev-tools/kunit/tips.rst - best practices with - examples. -* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs - used for testing. -* Documentation/dev-tools/kunit/faq.rst - KUnit common questions and - answers. +If you're interested in using some of the more advanced features of kunit.py, +take a look at Documentation/dev-tools/kunit/run_wrapper.rst + +If you'd like to run tests without using kunit.py, check out +Documentation/dev-tools/kunit/run_manual.rst + +For more information on writing KUnit tests (including some common techniques +for testing different things), see Documentation/dev-tools/kunit/usage.rst diff --git a/Documentation/dev-tools/kunit/tips.rst b/Documentation/dev-tools/kunit/tips.rst deleted file mode 100644 index 492d2ded2f5a..000000000000 --- a/Documentation/dev-tools/kunit/tips.rst +++ /dev/null @@ -1,190 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -============================ -Tips For Writing KUnit Tests -============================ - -Exiting early on failed expectations ------------------------------------- - -``KUNIT_EXPECT_EQ`` and friends will mark the test as failed and continue -execution. In some cases, it's unsafe to continue and you can use the -``KUNIT_ASSERT`` variant to exit on failure. - -.. code-block:: c - - void example_test_user_alloc_function(struct kunit *test) - { - void *object = alloc_some_object_for_me(); - - /* Make sure we got a valid pointer back. */ - KUNIT_ASSERT_NOT_ERR_OR_NULL(test, object); - do_something_with_object(object); - } - -Allocating memory ------------------ - -Where you would use ``kzalloc``, you should prefer ``kunit_kzalloc`` instead. -KUnit will ensure the memory is freed once the test completes. - -This is particularly useful since it lets you use the ``KUNIT_ASSERT_EQ`` -macros to exit early from a test without having to worry about remembering to -call ``kfree``. - -Example: - -.. code-block:: c - - void example_test_allocation(struct kunit *test) - { - char *buffer = kunit_kzalloc(test, 16, GFP_KERNEL); - /* Ensure allocation succeeded. */ - KUNIT_ASSERT_NOT_ERR_OR_NULL(test, buffer); - - KUNIT_ASSERT_STREQ(test, buffer, ""); - } - - -Testing static functions ------------------------- - -If you don't want to expose functions or variables just for testing, one option -is to conditionally ``#include`` the test file at the end of your .c file, e.g. - -.. code-block:: c - - /* In my_file.c */ - - static int do_interesting_thing(); - - #ifdef CONFIG_MY_KUNIT_TEST - #include "my_kunit_test.c" - #endif - -Injecting test-only code ------------------------- - -Similarly to the above, it can be useful to add test-specific logic. - -.. code-block:: c - - /* In my_file.h */ - - #ifdef CONFIG_MY_KUNIT_TEST - /* Defined in my_kunit_test.c */ - void test_only_hook(void); - #else - void test_only_hook(void) { } - #endif - -This test-only code can be made more useful by accessing the current kunit -test, see below. - -Accessing the current test --------------------------- - -In some cases, you need to call test-only code from outside the test file, e.g. -like in the example above or if you're providing a fake implementation of an -ops struct. -There is a ``kunit_test`` field in ``task_struct``, so you can access it via -``current->kunit_test``. - -Here's a slightly in-depth example of how one could implement "mocking": - -.. code-block:: c - - #include <linux/sched.h> /* for current */ - - struct test_data { - int foo_result; - int want_foo_called_with; - }; - - static int fake_foo(int arg) - { - struct kunit *test = current->kunit_test; - struct test_data *test_data = test->priv; - - KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg); - return test_data->foo_result; - } - - static void example_simple_test(struct kunit *test) - { - /* Assume priv is allocated in the suite's .init */ - struct test_data *test_data = test->priv; - - test_data->foo_result = 42; - test_data->want_foo_called_with = 1; - - /* In a real test, we'd probably pass a pointer to fake_foo somewhere - * like an ops struct, etc. instead of calling it directly. */ - KUNIT_EXPECT_EQ(test, fake_foo(1), 42); - } - - -Note: here we're able to get away with using ``test->priv``, but if you wanted -something more flexible you could use a named ``kunit_resource``, see -Documentation/dev-tools/kunit/api/test.rst. - -Failing the current test ------------------------- - -But sometimes, you might just want to fail the current test. In that case, we -have ``kunit_fail_current_test(fmt, args...)`` which is defined in ``<kunit/test-bug.h>`` and -doesn't require pulling in ``<kunit/test.h>``. - -E.g. say we had an option to enable some extra debug checks on some data structure: - -.. code-block:: c - - #include <kunit/test-bug.h> - - #ifdef CONFIG_EXTRA_DEBUG_CHECKS - static void validate_my_data(struct data *data) - { - if (is_valid(data)) - return; - - kunit_fail_current_test("data %p is invalid", data); - - /* Normal, non-KUnit, error reporting code here. */ - } - #else - static void my_debug_function(void) { } - #endif - - -Customizing error messages --------------------------- - -Each of the ``KUNIT_EXPECT`` and ``KUNIT_ASSERT`` macros have a ``_MSG`` variant. -These take a format string and arguments to provide additional context to the automatically generated error messages. - -.. code-block:: c - - char some_str[41]; - generate_sha1_hex_string(some_str); - - /* Before. Not easy to tell why the test failed. */ - KUNIT_EXPECT_EQ(test, strlen(some_str), 40); - - /* After. Now we see the offending string. */ - KUNIT_EXPECT_EQ_MSG(test, strlen(some_str), 40, "some_str='%s'", some_str); - -Alternatively, one can take full control over the error message by using ``KUNIT_FAIL()``, e.g. - -.. code-block:: c - - /* Before */ - KUNIT_EXPECT_EQ(test, some_setup_function(), 0); - - /* After: full control over the failure message. */ - if (some_setup_function()) - KUNIT_FAIL(test, "Failed to setup thing for testing"); - -Next Steps -========== -* Optional: see the Documentation/dev-tools/kunit/usage.rst page for a more - in-depth explanation of KUnit. diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index 2737863ef365..48f8196d5aad 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -112,11 +112,45 @@ terminates the test case if the condition is not satisfied. For example: KUNIT_EXPECT_LE(test, a[i], a[i + 1]); } -In this example, the method under test should return pointer to a value. If the -pointer returns null or an errno, we want to stop the test since the following -expectation could crash the test case. `ASSERT_NOT_ERR_OR_NULL(...)` allows us -to bail out of the test case if the appropriate conditions are not satisfied to -complete the test. +In this example, we need to be able to allocate an array to test the ``sort()`` +function. So we use ``KUNIT_ASSERT_NOT_ERR_OR_NULL()`` to abort the test if +there's an allocation error. + +.. note:: + In other test frameworks, ``ASSERT`` macros are often implemented by calling + ``return`` so they only work from the test function. In KUnit, we stop the + current kthread on failure, so you can call them from anywhere. + +Customizing error messages +-------------------------- + +Each of the ``KUNIT_EXPECT`` and ``KUNIT_ASSERT`` macros have a ``_MSG`` +variant. These take a format string and arguments to provide additional +context to the automatically generated error messages. + +.. code-block:: c + + char some_str[41]; + generate_sha1_hex_string(some_str); + + /* Before. Not easy to tell why the test failed. */ + KUNIT_EXPECT_EQ(test, strlen(some_str), 40); + + /* After. Now we see the offending string. */ + KUNIT_EXPECT_EQ_MSG(test, strlen(some_str), 40, "some_str='%s'", some_str); + +Alternatively, one can take full control over the error message by using +``KUNIT_FAIL()``, e.g. + +.. code-block:: c + + /* Before */ + KUNIT_EXPECT_EQ(test, some_setup_function(), 0); + + /* After: full control over the failure message. */ + if (some_setup_function()) + KUNIT_FAIL(test, "Failed to setup thing for testing"); + Test Suites ~~~~~~~~~~~ @@ -546,24 +580,6 @@ By reusing the same ``cases`` array from above, we can write the test as a {} }; -Exiting Early on Failed Expectations ------------------------------------- - -We can use ``KUNIT_EXPECT_EQ`` to mark the test as failed and continue -execution. In some cases, it is unsafe to continue. We can use the -``KUNIT_ASSERT`` variant to exit on failure. - -.. code-block:: c - - void example_test_user_alloc_function(struct kunit *test) - { - void *object = alloc_some_object_for_me(); - - /* Make sure we got a valid pointer back. */ - KUNIT_ASSERT_NOT_ERR_OR_NULL(test, object); - do_something_with_object(object); - } - Allocating Memory ----------------- @@ -625,17 +641,23 @@ as shown in next section: *Accessing The Current Test*. Accessing The Current Test -------------------------- -In some cases, we need to call test-only code from outside the test file. -For example, see example in section *Injecting Test-Only Code* or if -we are providing a fake implementation of an ops struct. Using -``kunit_test`` field in ``task_struct``, we can access it via -``current->kunit_test``. +In some cases, we need to call test-only code from outside the test file. This +is helpful, for example, when providing a fake implementation of a function, or +to fail any current test from within an error handler. +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. -The example below includes how to implement "mocking": +The example below uses this to implement a "mock" implementation of a function, ``foo``: .. code-block:: c - #include <linux/sched.h> /* for current */ + #include <kunit/test-bug.h> /* for kunit_get_current_test */ struct test_data { int foo_result; @@ -644,7 +666,7 @@ The example below includes how to implement "mocking": static int fake_foo(int arg) { - struct kunit *test = current->kunit_test; + struct kunit *test = kunit_get_current_test(); struct test_data *test_data = test->priv; KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg); @@ -675,7 +697,7 @@ Each test can have multiple resources which have string names providing the same flexibility as a ``priv`` member, but also, for example, allowing helper functions to create resources without conflicting with each other. It is also possible to define a clean up function for each resource, making it easy to -avoid resource leaks. For more information, see Documentation/dev-tools/kunit/api/test.rst. +avoid resource leaks. For more information, see Documentation/dev-tools/kunit/api/resource.rst. Failing The Current Test ------------------------ @@ -703,3 +725,9 @@ structures as shown below: static void my_debug_function(void) { } #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. + diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml index 9fda2436c618..e16b5fa55847 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -163,6 +163,7 @@ properties: - azw,gsking-x - azw,gtking - azw,gtking-pro + - hardkernel,odroid-go-ultra - hardkernel,odroid-n2 - hardkernel,odroid-n2-plus - khadas,vim3 diff --git a/Documentation/devicetree/bindings/arm/apple.yaml b/Documentation/devicetree/bindings/arm/apple.yaml index 7262f3c09867..da78c69774f2 100644 --- a/Documentation/devicetree/bindings/arm/apple.yaml +++ b/Documentation/devicetree/bindings/arm/apple.yaml @@ -19,12 +19,14 @@ description: | - MacBook Air (M1, 2020) - iMac (24-inch, M1, 2021) - And devices based on the "M1 Pro" and "M1 Max" SoCs: + And devices based on the "M1 Pro", "M1 Max" and "M1 Ultra" SoCs: - MacBook Pro (14-inch, M1 Pro, 2021) - MacBook Pro (14-inch, M1 Max, 2021) - MacBook Pro (16-inch, M1 Pro, 2021) - MacBook Pro (16-inch, M1 Max, 2021) + - Mac Studio (M1 Max, 2022) + - Mac Studio (M1 Ultra, 2022) The compatible property should follow this format: @@ -67,6 +69,7 @@ properties: - apple,j457 # iMac (24-inch, 2x USB-C, M1, 2021) - const: apple,t8103 - const: apple,arm-platform + - description: Apple M1 Pro SoC based platforms items: - enum: @@ -74,14 +77,23 @@ properties: - apple,j316s # MacBook Pro (16-inch, M1 Pro, 2021) - const: apple,t6000 - const: apple,arm-platform + - description: Apple M1 Max SoC based platforms items: - enum: - apple,j314c # MacBook Pro (14-inch, M1 Max, 2021) - apple,j316c # MacBook Pro (16-inch, M1 Max, 2021) + - apple,j375c # Mac Studio (M1 Max, 2022) - const: apple,t6001 - const: apple,arm-platform + - description: Apple M1 Ultra SoC based platforms + items: + - enum: + - apple,j375d # Mac Studio (M1 Ultra, 2022) + - const: apple,t6002 + - const: apple,arm-platform + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml b/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml index 217a1d674863..73f272664e83 100644 --- a/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml +++ b/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml @@ -17,6 +17,7 @@ properties: - description: AST2400 based boards items: - enum: + - delta,ahe50dc-bmc - facebook,galaxy100-bmc - facebook,wedge100-bmc - facebook,wedge40-bmc @@ -82,7 +83,7 @@ properties: - ibm,tacoma-bmc - inventec,transformer-bmc - jabil,rbp-bmc - - nuvia,dc-scm-bmc + - qcom,dc-scm-v1-bmc - quanta,s6q-bmc - const: aspeed,ast2600 diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml index 958df32b4899..52b575c40599 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml @@ -66,6 +66,7 @@ properties: - enum: - asus,rt-ac88u - dlink,dir-885l + - dlink,dir-890l - linksys,panamera - luxul,abr-4500-v1 - luxul,xap-1610-v1 @@ -97,6 +98,7 @@ properties: - description: BCM53016 based boards items: - enum: + - dlink,dwl-8610ap - meraki,mr32 - const: brcm,bcm53016 - const: brcm,bcm4708 diff --git a/Documentation/devicetree/bindings/arm/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml index 5c13b73e4d57..7dd84f8f8e4f 100644 --- a/Documentation/devicetree/bindings/arm/cpus.yaml +++ b/Documentation/devicetree/bindings/arm/cpus.yaml @@ -178,11 +178,13 @@ properties: - qcom,kryo250 - qcom,kryo260 - qcom,kryo280 + - qcom,kryo360 - qcom,kryo385 - qcom,kryo468 - qcom,kryo485 - qcom,kryo560 - qcom,kryo570 + - qcom,kryo660 - qcom,kryo685 - qcom,kryo780 - qcom,scorpion diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index fbfc4f99c01e..05b5276a0e14 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -520,6 +520,7 @@ properties: items: - enum: - fsl,imx6sl-evk # i.MX6 SoloLite EVK Board + - kobo,aura2 - kobo,tolino-shine2hd - kobo,tolino-shine3 - kobo,tolino-vision5 @@ -814,6 +815,7 @@ 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 @@ -825,6 +827,7 @@ properties: - gw,imx8mm-gw7901 # i.MX8MM Gateworks Board - gw,imx8mm-gw7902 # i.MX8MM Gateworks Board - gw,imx8mm-gw7903 # i.MX8MM Gateworks Board + - 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 @@ -1067,6 +1070,18 @@ properties: - fsl,imx93-11x11-evk # i.MX93 11x11 EVK Board - const: fsl,imx93 + - description: i.MXRT1050 based Boards + items: + - enum: + - fsl,imxrt1050-evk # i.MXRT1050 EVK Board + - const: fsl,imxrt1050 + + - description: i.MXRT1170 based Boards + items: + - enum: + - fsl,imxrt1170-evk # i.MXRT1170 EVK Board + - const: fsl,imxrt1170 + - description: Freescale Vybrid Platform Device Tree Bindings diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml index d76ce4c3819d..2275e5d93721 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek.yaml @@ -58,6 +58,7 @@ properties: - items: - enum: - mediatek,mt6795-evb + - sony,xperia-m5 - const: mediatek,mt6795 - items: - enum: @@ -83,6 +84,7 @@ properties: - const: mediatek,mt7629 - items: - enum: + - bananapi,bpi-r3 - mediatek,mt7986a-rfb - const: mediatek,mt7986a - items: diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.yaml b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.yaml index eb451bec23d3..0711f1834fbd 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.yaml @@ -32,14 +32,26 @@ properties: - mediatek,mt8183-mmsys - mediatek,mt8186-mmsys - mediatek,mt8192-mmsys - - mediatek,mt8195-mmsys - mediatek,mt8365-mmsys - const: syscon + + - description: vdosys0 and vdosys1 are 2 display HW pipelines, + so mt8195 binding should be deprecated. + deprecated: true + items: + - const: mediatek,mt8195-mmsys + - const: syscon + - items: - const: mediatek,mt7623-mmsys - const: mediatek,mt2701-mmsys - const: syscon + - items: + - const: mediatek,mt8195-vdosys0 + - const: mediatek,mt8195-mmsys + - const: syscon + reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml index 84fb0a146b6e..5c223cb063d4 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml @@ -29,6 +29,38 @@ properties: interrupts: maxItems: 1 + memory-region: + items: + - description: firmware EMI region + - description: firmware ILM region + - description: firmware DLM region + - description: firmware CPU DATA region + - description: firmware BOOT region + + memory-region-names: + items: + - const: wo-emi + - const: wo-ilm + - const: wo-dlm + - const: wo-data + - const: wo-boot + + mediatek,wo-ccif: + $ref: /schemas/types.yaml#/definitions/phandle + description: mediatek wed-wo controller interface. + +allOf: + - if: + properties: + compatible: + contains: + const: mediatek,mt7622-wed + then: + properties: + memory-region-names: false + memory-region: false + mediatek,wo-ccif: false + required: - compatible - reg @@ -49,3 +81,23 @@ examples: interrupts = <GIC_SPI 214 IRQ_TYPE_LEVEL_LOW>; }; }; + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + soc { + #address-cells = <2>; + #size-cells = <2>; + + wed@15010000 { + compatible = "mediatek,mt7986-wed", "syscon"; + reg = <0 0x15010000 0 0x1000>; + interrupts = <GIC_SPI 205 IRQ_TYPE_LEVEL_HIGH>; + + memory-region = <&wo_emi>, <&wo_ilm>, <&wo_dlm>, + <&wo_data>, <&wo_boot>; + memory-region-names = "wo-emi", "wo-ilm", "wo-dlm", + "wo-data", "wo-boot"; + mediatek,wo-ccif = <&wo_ccif0>; + }; + }; diff --git a/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml b/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml index 5ea506412b4e..38efcad56dbd 100644 --- a/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml +++ b/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml @@ -31,6 +31,7 @@ properties: - qcom,sm8250-llcc - qcom,sm8350-llcc - qcom,sm8450-llcc + - qcom,sm8550-llcc reg: items: diff --git a/Documentation/devicetree/bindings/arm/qcom-soc.yaml b/Documentation/devicetree/bindings/arm/qcom-soc.yaml new file mode 100644 index 000000000000..e333ec4a9c5f --- /dev/null +++ b/Documentation/devicetree/bindings/arm/qcom-soc.yaml @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/qcom-soc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SoC compatibles naming convention + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + +description: | + Guidelines for new compatibles for SoC blocks/components. + When adding new compatibles in new bindings, use the format:: + qcom,SoC-IP + + For example:: + qcom,sdm845-llcc-bwmon + + When adding new compatibles to existing bindings, use the format in the + existing binding, even if it contradicts the above. + +select: + properties: + compatible: + pattern: "^qcom,.*(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$" + required: + - compatible + +properties: + compatible: + oneOf: + # Preferred naming style for compatibles of SoC components: + - pattern: "^qcom,(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+-.*$" + - pattern: "^qcom,(sa|sc)8[0-9]+[a-z][a-z]?-.*$" + + # Legacy namings - variations of existing patterns/compatibles are OK, + # but do not add completely new entries to these: + - pattern: "^qcom,[ak]pss-wdt-(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$" + - pattern: "^qcom,gcc-(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$" + - pattern: "^qcom,mmcc-(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$" + - pattern: "^qcom,pcie-(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$" + - pattern: "^qcom,rpm-(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$" + - pattern: "^qcom,scm-(apq|ipq|mdm|msm|qcm|qcs|sa|sc|sdm|sdx|sm)[0-9]+.*$" + - enum: + - qcom,dsi-ctrl-6g-qcm2290 + - qcom,gpucc-sdm630 + - qcom,gpucc-sdm660 + - qcom,lcc-apq8064 + - qcom,lcc-ipq8064 + - qcom,lcc-mdm9615 + - qcom,lcc-msm8960 + - qcom,lpass-cpu-apq8016 + - qcom,usb-ss-ipq4019-phy + - qcom,usb-hs-ipq4019-phy + - qcom,vqmmc-ipq4019-regulator + + # Legacy compatibles with wild-cards - list cannot grow with new bindings: + - enum: + - qcom,ipq806x-gmac + - qcom,ipq806x-nand + - qcom,ipq806x-sata-phy + - qcom,ipq806x-usb-phy-ss + - qcom,ipq806x-usb-phy-hs + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index 1b5ac6b02bc5..27063a045bd0 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -29,17 +29,22 @@ description: | apq8074 apq8084 apq8096 + ipq4018 ipq6018 ipq8074 mdm9615 msm8226 msm8916 + msm8956 msm8974 + msm8976 msm8992 msm8994 msm8996 msm8998 qcs404 + qdu1000 + qru1000 sa8155p sa8540p sc7180 @@ -51,11 +56,15 @@ description: | sdm632 sdm636 sdm660 + sdm670 sdm845 sdx55 sdx65 + sm4250 + sm6115 sm6125 sm6350 + sm6375 sm7225 sm8150 sm8250 @@ -76,6 +85,7 @@ description: | mtp qrd sbc + x100 The 'soc_version' and 'board_version' elements take the form of v<Major>.<Minor> where the minor number may be omitted when it's zero, i.e. v1.0 is the same @@ -114,7 +124,9 @@ properties: - items: - enum: - asus,sparrow + - huawei,sturgeon - lg,lenok + - samsung,matisse-wifi - const: qcom,apq8026 - items: @@ -150,20 +162,32 @@ properties: - items: - enum: + - sony,kugo-row + - sony,suzu-row + - const: qcom,msm8956 + + - items: + - enum: - qcom,msm8960-cdp - const: qcom,msm8960 - items: - enum: - - fairphone,fp2 - lge,hammerhead - - samsung,klte - sony,xperia-amami - - sony,xperia-castor - sony,xperia-honami - const: qcom,msm8974 - items: + - enum: + - fairphone,fp2 + - oneplus,bacon + - samsung,klte + - sony,xperia-castor + - const: qcom,msm8974pro + - const: qcom,msm8974 + + - items: - const: qcom,msm8916-mtp - const: qcom,msm8916-mtp/1 - const: qcom,msm8916 @@ -221,13 +245,20 @@ properties: - items: - enum: + - oneplus,oneplus3 + - oneplus,oneplus3t - qcom,msm8996-mtp - sony,dora-row - sony,kagura-row - sony,keyaki-row - xiaomi,gemini + - const: qcom,msm8996 + + - items: + - enum: - xiaomi,natrium - xiaomi,scorpio + - const: qcom,msm8996pro - const: qcom,msm8996 - items: @@ -242,10 +273,17 @@ properties: - sony,xperia-lilac - sony,xperia-maple - sony,xperia-poplar + - xiaomi,sagit - const: qcom,msm8998 - items: - enum: + - 8dev,jalapeno + - alfa-network,ap120c-ac + - const: qcom,ipq4018 + + - items: + - enum: - qcom,ipq4019-ap-dk01.1-c1 - qcom,ipq4019-ap-dk04.1-c3 - qcom,ipq4019-ap-dk07.1-c1 @@ -255,6 +293,7 @@ properties: - items: - enum: + - mikrotik,rb3011 - qcom,ipq8064-ap148 - const: qcom,ipq8064 @@ -265,6 +304,25 @@ properties: - qcom,ipq8074-hk10-c2 - const: qcom,ipq8074 + - description: Sierra Wireless MangOH Green with WP8548 Module + items: + - const: swir,mangoh-green-wp8548 + - const: swir,wp8548 + - const: qcom,mdm9615 + + - description: Qualcomm Technologies, Inc. Distributed Unit 1000 platform + items: + - enum: + - qcom,qdu1000-idp + - qcom,qdu1000-x100 + - const: qcom,qdu1000 + + - description: Qualcomm Technologies, Inc. Radio Unit 1000 platform + items: + - enum: + - qcom,qru1000-idp + - const: qcom,qru1000 + - description: Qualcomm Technologies, Inc. SC7180 IDP items: - enum: @@ -463,6 +521,17 @@ properties: - const: google,pazquel-sku2 - const: qcom,sc7180 + - description: Google Pazquel360 with LTE (newest rev) + items: + - const: google,pazquel-sku22 + - const: google,pazquel-sku20 + - const: qcom,sc7180 + + - description: Google Pazquel360 with WiFi (newest rev) + items: + - const: google,pazquel-sku21 + - const: qcom,sc7180 + - description: Sharp Dynabook Chromebook C1 (rev1) items: - const: google,pompom-rev1 @@ -575,6 +644,11 @@ properties: - const: google,evoker - const: qcom,sc7280 + - description: Google Evoker with LTE (newest rev) + items: + - const: google,evoker-sku512 + - const: qcom,sc7280 + - description: Google Herobrine (newest rev) items: - const: google,herobrine @@ -595,6 +669,16 @@ properties: - const: google,villager-sku512 - const: qcom,sc7280 + - description: Google Zombie (newest rev) + items: + - const: google,zombie + - const: qcom,sc7280 + + - description: Google Zombie with LTE (newest rev) + items: + - const: google,zombie-sku512 + - const: qcom,sc7280 + - items: - enum: - lenovo,flex-5g @@ -639,6 +723,11 @@ properties: - items: - enum: + - google,sargo + - const: qcom,sdm670 + + - items: + - enum: - qcom,sdx55-mtp - qcom,sdx55-telit-fn980-tlb - qcom,sdx55-t55 @@ -670,10 +759,14 @@ properties: - items: - enum: - qcom,sa8295p-adp + - qcom,sa8540p-ride - const: qcom,sa8540p - items: - enum: + - google,cheza + - google,cheza-rev1 + - google,cheza-rev2 - lenovo,yoga-c630 - lg,judyln - lg,judyp @@ -681,17 +774,24 @@ properties: - oneplus,fajita - qcom,sdm845-mtp - shift,axolotl + - samsung,starqltechn - samsung,w737 - sony,akari-row - sony,akatsuki-row - sony,apollo-row - thundercomm,db845c - xiaomi,beryllium + - xiaomi,beryllium-ebbg - xiaomi,polaris - const: qcom,sdm845 - items: - enum: + - oneplus,billie2 + - const: qcom,sm4250 + + - items: + - enum: - sony,pdx201 - const: qcom,sm6125 @@ -702,6 +802,11 @@ properties: - items: - enum: + - sony,pdx225 + - const: qcom,sm6375 + + - items: + - enum: - fairphone,fp4 - const: qcom,sm7225 @@ -737,8 +842,129 @@ properties: - qcom,sm8450-hdk - qcom,sm8450-qrd - sony,pdx223 + - sony,pdx224 - const: qcom,sm8450 + # Board compatibles go above + + qcom,msm-id: + $ref: /schemas/types.yaml#/definitions/uint32-matrix + minItems: 1 + maxItems: 8 + items: + items: + - description: | + MSM chipset ID - an exact match value consisting of two bitfields:: + - bits 0-15 - The unique MSM chipset ID + - bits 16-31 - Reserved; should be 0 + - description: | + Hardware revision ID - a chipset specific 32-bit ID representing + the version of the chipset. It is best a match value - the + bootloader will look for the closest possible match. + deprecated: true + description: + The MSM chipset and hardware revision used Qualcomm bootloaders. It + can optionally be an array of these to indicate multiple hardware that + use the same device tree. It is expected that the bootloader will use + this information at boot-up to decide which device tree to use when given + multiple device trees, some of which may not be compatible with the + actual hardware. It is the bootloader's responsibility to pass the + correct device tree to the kernel. + The property is deprecated. + + qcom,board-id: + $ref: /schemas/types.yaml#/definitions/uint32-matrix + minItems: 1 + maxItems: 8 + oneOf: + - items: + - items: + - description: | + Board ID consisting of three bitfields:: + - bits 31-24 - Unused + - bits 23-16 - Platform Version Major + - bits 15-8 - Platform Version Minor + - bits 7-0 - Platform Type + Platform Type field is an exact match value. The + Platform Major/Minor field is a best match. The bootloader will + look for the closest possible match. + - description: | + Subtype ID unique to a Platform Type/Chipset ID. For a given + Platform Type, there will typically only be a single board and the + subtype_id will be 0. However in some cases board variants may + need to be distinguished by different subtype_id values. + - items: + # OnePlus uses a variant of board-id with four elements: + - items: + - const: 8 + - const: 0 + - description: OnePlus board ID + - description: OnePlus subtype ID + deprecated: true + description: + The board type and revision information. It can optionally be an array + of these to indicate multiple boards that use the same device tree. It + is expected that the bootloader will use this information at boot-up to + decide which device tree to use when given multiple device trees, some of + which may not be compatible with the actual hardware. It is the + bootloader's responsibility to pass the correct device tree to the + kernel + The property is deprecated. + +allOf: + # Explicit allow-list for older SoCs. The legacy properties are not allowed + # on newer SoCs. + - if: + properties: + compatible: + contains: + enum: + - qcom,apq8026 + - qcom,apq8094 + - qcom,apq8096 + - qcom,msm8992 + - qcom,msm8994 + - qcom,msm8996 + - qcom,msm8998 + - qcom,sdm630 + - qcom,sdm632 + - qcom,sdm845 + - qcom,sdx55 + - qcom,sdx65 + - qcom,sm6125 + - qcom,sm6350 + - qcom,sm7225 + - qcom,sm8150 + - qcom,sm8250 + then: + properties: + qcom,board-id: true + qcom,msm-id: true + else: + properties: + qcom,board-id: false + qcom,msm-id: false + + - if: + properties: + compatible: + contains: + enum: + - oneplus,cheeseburger + - oneplus,dumpling + - oneplus,enchilada + - oneplus,fajita + then: + properties: + qcom,board-id: + items: + minItems: 4 + else: + properties: + qcom,board-id: + items: + maxItems: 2 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml index c6c69a4e3777..88ff4422a8c1 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -30,11 +30,26 @@ properties: - const: amarula,vyasa-rk3288 - const: rockchip,rk3288 + - description: Anbernic RG351M + items: + - const: anbernic,rg351m + - const: rockchip,rk3326 + - description: Anbernic RG353P items: - const: anbernic,rg353p - const: rockchip,rk3566 + - description: Anbernic RG353V + items: + - const: anbernic,rg353v + - const: rockchip,rk3566 + + - description: Anbernic RG353VS + items: + - const: anbernic,rg353vs + - const: rockchip,rk3566 + - description: Anbernic RG503 items: - const: anbernic,rg503 @@ -468,6 +483,21 @@ properties: - const: hardkernel,rk3326-odroid-go2 - const: rockchip,rk3326 + - description: Hardkernel Odroid Go Advance Black Edition + items: + - const: hardkernel,rk3326-odroid-go2-v11 + - const: rockchip,rk3326 + + - description: Hardkernel Odroid Go Super + items: + - const: hardkernel,rk3326-odroid-go3 + - const: rockchip,rk3326 + + - description: Hardkernel Odroid M1 + items: + - const: rockchip,rk3568-odroid-m1 + - const: rockchip,rk3568 + - description: Hugsun X99 TV Box items: - const: hugsun,x99 @@ -563,7 +593,9 @@ properties: - description: Pine64 SoQuartz SoM items: - enum: + - pine64,soquartz-blade - pine64,soquartz-cm4io + - pine64,soquartz-model-a - const: pine64,soquartz - const: rockchip,rk3566 @@ -709,6 +741,11 @@ properties: - const: rockchip,rv1108-evb - const: rockchip,rv1108 + - description: Theobroma Systems PX30-uQ7 with Haikou baseboard + items: + - const: tsd,px30-ringneck-haikou + - const: rockchip,px30 + - description: Theobroma Systems RK3368-uQ7 with Haikou baseboard items: - const: tsd,rk3368-lion-haikou @@ -729,6 +766,11 @@ properties: - const: zkmagic,a95x-z2 - const: rockchip,rk3318 + - description: Rockchip RK3566 BOX Evaluation Demo board + items: + - const: rockchip,rk3566-box-demo + - const: rockchip,rk3566 + - description: Rockchip RK3568 Evaluation board items: - const: rockchip,rk3568-evb1-v10 diff --git a/Documentation/devicetree/bindings/arm/socionext/uniphier.yaml b/Documentation/devicetree/bindings/arm/socionext/uniphier.yaml index 8c0e91658474..c2cea1c90f3c 100644 --- a/Documentation/devicetree/bindings/arm/socionext/uniphier.yaml +++ b/Documentation/devicetree/bindings/arm/socionext/uniphier.yaml @@ -26,6 +26,12 @@ properties: - socionext,uniphier-pro4-ref - socionext,uniphier-pro4-sanji - const: socionext,uniphier-pro4 + - description: Pro5 SoC boards + items: + - enum: + - socionext,uniphier-pro5-epcore + - socionext,uniphier-pro5-proex + - const: socionext,uniphier-pro5 - description: sLD8 SoC boards items: - enum: diff --git a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml index 4c605bccc474..44f5c5855af8 100644 --- a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml +++ b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml @@ -59,6 +59,12 @@ properties: - prt,prtt1s # Protonic PRTT1S - const: st,stm32mp151 + - description: DH STM32MP151 DHCOR SoM based Boards + items: + - const: dh,stm32mp151a-dhcor-testbench + - const: dh,stm32mp151a-dhcor-som + - const: st,stm32mp151 + - description: DH STM32MP153 DHCOM SoM based Boards items: - const: dh,stm32mp153c-dhcom-drc02 diff --git a/Documentation/devicetree/bindings/arm/swir.txt b/Documentation/devicetree/bindings/arm/swir.txt deleted file mode 100644 index 042be73a95d3..000000000000 --- a/Documentation/devicetree/bindings/arm/swir.txt +++ /dev/null @@ -1,12 +0,0 @@ -Sierra Wireless Modules device tree bindings --------------------------------------------- - -Supported Modules : - - WP8548 : Includes MDM9615 and PM8018 in a module - -Sierra Wireless modules shall have the following properties : - Required root node property - - compatible: "swir,wp8548" for the WP8548 CF3 Module - -Board compatible values: - - "swir,mangoh-green-wp8548" for the mangOH green board with the WP8548 module diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra-ccplex-cluster.yaml b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra-ccplex-cluster.yaml index 711bb4d08c60..869c266e7ebc 100644 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra-ccplex-cluster.yaml +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra-ccplex-cluster.yaml @@ -47,5 +47,4 @@ examples: compatible = "nvidia,tegra234-ccplex-cluster"; reg = <0x0e000000 0x5ffff>; nvidia,bpmp = <&bpmp>; - status = "okay"; }; diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.yaml b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.yaml index 7fd8d47b1be4..4a00593b9f7f 100644 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.yaml +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.yaml @@ -123,6 +123,33 @@ properties: some PLLs, clocks and then brings up CPU0 for resuming the system. + core-supply: + description: + Phandle to voltage regulator connected to the SoC Core power rail. + + core-domain: + type: object + description: | + The vast majority of hardware blocks of Tegra SoC belong to a + Core power domain, which has a dedicated voltage rail that powers + the blocks. + + properties: + operating-points-v2: + description: + Should contain level, voltages and opp-supported-hw property. + The supported-hw is a bitfield indicating SoC speedo or process + ID mask. + + "#power-domain-cells": + const: 0 + + required: + - operating-points-v2 + - "#power-domain-cells" + + additionalProperties: false + i2c-thermtrip: type: object description: @@ -300,33 +327,6 @@ patternProperties: additionalProperties: false - core-domain: - type: object - description: | - The vast majority of hardware blocks of Tegra SoC belong to a - Core power domain, which has a dedicated voltage rail that powers - the blocks. - - properties: - operating-points-v2: - description: - Should contain level, voltages and opp-supported-hw property. - The supported-hw is a bitfield indicating SoC speedo or process - ID mask. - - "#power-domain-cells": - const: 0 - - required: - - operating-points-v2 - - "#power-domain-cells" - - additionalProperties: false - - core-supply: - description: - Phandle to voltage regulator connected to the SoC Core power rail. - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/arm/ti/k3.yaml b/Documentation/devicetree/bindings/arm/ti/k3.yaml index 28b8232e1c5b..09e6845ff243 100644 --- a/Documentation/devicetree/bindings/arm/ti/k3.yaml +++ b/Documentation/devicetree/bindings/arm/ti/k3.yaml @@ -61,6 +61,7 @@ properties: - const: ti,j721e - items: - enum: + - beagle,j721e-beagleboneai64 - ti,j721e-evm - ti,j721e-sk - const: ti,j721e diff --git a/Documentation/devicetree/bindings/ata/ata-generic.yaml b/Documentation/devicetree/bindings/ata/ata-generic.yaml new file mode 100644 index 000000000000..0697927f3d7e --- /dev/null +++ b/Documentation/devicetree/bindings/ata/ata-generic.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/ata/ata-generic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic Parallel ATA Controller + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +description: + Generic Parallel ATA controllers supporting PIO modes only. + +properties: + compatible: + items: + - enum: + - arm,vexpress-cf + - fsl,mpc8349emitx-pata + - const: ata-generic + + reg: + items: + - description: Command interface registers + - description: Control interface registers + + reg-shift: + enum: [ 1, 2 ] + + interrupts: + maxItems: 1 + + ata-generic,use16bit: + type: boolean + description: Use 16-bit accesses instead of 32-bit for data transfers + + pio-mode: + description: Maximum ATA PIO transfer mode + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 6 + default: 0 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + compact-flash@1a000 { + compatible = "arm,vexpress-cf", "ata-generic"; + reg = <0x1a000 0x100>, + <0x1a100 0xf00>; + reg-shift = <2>; + }; +... diff --git a/Documentation/devicetree/bindings/chrome/google,cros-ec-typec.yaml b/Documentation/devicetree/bindings/chrome/google,cros-ec-typec.yaml index 50ebd8c57795..defcf1e12aa1 100644 --- a/Documentation/devicetree/bindings/chrome/google,cros-ec-typec.yaml +++ b/Documentation/devicetree/bindings/chrome/google,cros-ec-typec.yaml @@ -48,6 +48,7 @@ examples: cros_ec: ec@0 { compatible = "google,cros-ec-spi"; reg = <0>; + interrupts = <35 0>; typec { compatible = "google,cros-ec-typec"; diff --git a/Documentation/devicetree/bindings/chrome/google,cros-kbd-led-backlight.yaml b/Documentation/devicetree/bindings/chrome/google,cros-kbd-led-backlight.yaml index 5b875af6a95a..40244d003c32 100644 --- a/Documentation/devicetree/bindings/chrome/google,cros-kbd-led-backlight.yaml +++ b/Documentation/devicetree/bindings/chrome/google,cros-kbd-led-backlight.yaml @@ -27,6 +27,7 @@ examples: cros_ec: ec@0 { compatible = "google,cros-ec-spi"; reg = <0>; + interrupts = <15 0>; kbd-led-backlight { compatible = "google,cros-kbd-led-backlight"; diff --git a/Documentation/devicetree/bindings/clock/fsl,imx8m-anatop.yaml b/Documentation/devicetree/bindings/clock/fsl,imx8m-anatop.yaml new file mode 100644 index 000000000000..bbd22e95b319 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/fsl,imx8m-anatop.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/fsl,imx8m-anatop.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP i.MX8M Family Anatop Module + +maintainers: + - Peng Fan <peng.fan@nxp.com> + +description: | + NXP i.MX8M Family anatop PLL module which generates PLL to CCM root. + +properties: + compatible: + oneOf: + - enum: + - fsl,imx8mm-anatop + - fsl,imx8mq-anatop + - items: + - enum: + - fsl,imx8mn-anatop + - fsl,imx8mp-anatop + - const: fsl,imx8mm-anatop + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + '#clock-cells': + const: 1 + +required: + - compatible + - reg + - '#clock-cells' + +additionalProperties: false + +examples: + - | + anatop: clock-controller@30360000 { + compatible = "fsl,imx8mn-anatop", "fsl,imx8mm-anatop"; + reg = <0x30360000 0x10000>; + #clock-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/ingenic,cgu.yaml b/Documentation/devicetree/bindings/clock/ingenic,cgu.yaml index aa1df03ef4a6..df256ebcd366 100644 --- a/Documentation/devicetree/bindings/clock/ingenic,cgu.yaml +++ b/Documentation/devicetree/bindings/clock/ingenic,cgu.yaml @@ -22,6 +22,7 @@ select: enum: - ingenic,jz4740-cgu - ingenic,jz4725b-cgu + - ingenic,jz4755-cgu - ingenic,jz4760-cgu - ingenic,jz4760b-cgu - ingenic,jz4770-cgu @@ -51,6 +52,7 @@ properties: - enum: - ingenic,jz4740-cgu - ingenic,jz4725b-cgu + - ingenic,jz4755-cgu - ingenic,jz4760-cgu - ingenic,jz4760b-cgu - ingenic,jz4770-cgu diff --git a/Documentation/devicetree/bindings/clock/mediatek,mt8186-fhctl.yaml b/Documentation/devicetree/bindings/clock/mediatek,mt8186-fhctl.yaml new file mode 100644 index 000000000000..cfd042ac1e14 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/mediatek,mt8186-fhctl.yaml @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/mediatek,mt8186-fhctl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek frequency hopping and spread spectrum clocking control + +maintainers: + - Edward-JW Yang <edward-jw.yang@mediatek.com> + +description: | + Frequency hopping control (FHCTL) is a piece of hardware that control + some PLLs to adopt "hopping" mechanism to adjust their frequency. + Spread spectrum clocking (SSC) is another function provided by this hardware. + +properties: + compatible: + const: mediatek,mt8186-fhctl + + reg: + maxItems: 1 + + clocks: + description: Phandles of the PLL with FHCTL hardware capability. + minItems: 1 + maxItems: 30 + + mediatek,hopping-ssc-percent: + description: The percentage of spread spectrum clocking for one PLL. + minItems: 1 + maxItems: 30 + items: + default: 0 + minimum: 0 + maximum: 8 + +required: + - compatible + - reg + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/mt8186-clk.h> + fhctl: fhctl@1000ce00 { + compatible = "mediatek,mt8186-fhctl"; + reg = <0x1000ce00 0x200>; + clocks = <&apmixedsys CLK_APMIXED_MSDCPLL>; + mediatek,hopping-ssc-percent = <3>; + }; diff --git a/Documentation/devicetree/bindings/clock/nvidia,tegra124-dfll.txt b/Documentation/devicetree/bindings/clock/nvidia,tegra124-dfll.txt index 958e0ad78c52..f7d347385b57 100644 --- a/Documentation/devicetree/bindings/clock/nvidia,tegra124-dfll.txt +++ b/Documentation/devicetree/bindings/clock/nvidia,tegra124-dfll.txt @@ -136,7 +136,7 @@ clock@70110000 { }; /* pinmux nodes added for completeness. Binding doc can be found in: - * Documentation/devicetree/bindings/pinctrl/nvidia,tegra210-pinmux.txt + * Documentation/devicetree/bindings/pinctrl/nvidia,tegra210-pinmux.yaml */ pinmux: pinmux@700008d4 { diff --git a/Documentation/devicetree/bindings/clock/pwm-clock.txt b/Documentation/devicetree/bindings/clock/pwm-clock.txt deleted file mode 100644 index 83db876b3b90..000000000000 --- a/Documentation/devicetree/bindings/clock/pwm-clock.txt +++ /dev/null @@ -1,26 +0,0 @@ -Binding for an external clock signal driven by a PWM pin. - -This binding uses the common clock binding[1] and the common PWM binding[2]. - -[1] Documentation/devicetree/bindings/clock/clock-bindings.txt -[2] Documentation/devicetree/bindings/pwm/pwm.txt - -Required properties: -- compatible : shall be "pwm-clock". -- #clock-cells : from common clock binding; shall be set to 0. -- pwms : from common PWM binding; this determines the clock frequency - via the period given in the PWM specifier. - -Optional properties: -- clock-output-names : From common clock binding. -- clock-frequency : Exact output frequency, in case the PWM period - is not exact but was rounded to nanoseconds. - -Example: - clock { - compatible = "pwm-clock"; - #clock-cells = <0>; - clock-frequency = <25000000>; - clock-output-names = "mipi_mclk"; - pwms = <&pwm2 0 40>; /* 1 / 40 ns = 25 MHz */ - }; diff --git a/Documentation/devicetree/bindings/clock/pwm-clock.yaml b/Documentation/devicetree/bindings/clock/pwm-clock.yaml new file mode 100644 index 000000000000..f88ecb2995e0 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/pwm-clock.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/pwm-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: An external clock signal driven by a PWM pin. + +maintainers: + - Philipp Zabel <p.zabel@pengutronix.de> + +properties: + compatible: + const: pwm-clock + + '#clock-cells': + const: 0 + + clock-frequency: + description: Exact output frequency, in case the PWM period is not exact + but was rounded to nanoseconds. + + clock-output-names: + maxItems: 1 + + pwms: + maxItems: 1 + +required: + - compatible + - '#clock-cells' + - pwms + +additionalProperties: false + +examples: + - | + clock { + compatible = "pwm-clock"; + #clock-cells = <0>; + clock-frequency = <25000000>; + clock-output-names = "mipi_mclk"; + pwms = <&pwm2 0 40>; /* 1 / 40 ns = 25 MHz */ + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml b/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml index fe6ca4f68bbe..525ebaa93c85 100644 --- a/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/clock/qcom,a53pll.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm A53 PLL Binding +title: Qualcomm A53 PLL clock maintainers: - Bjorn Andersson <andersson@kernel.org> diff --git a/Documentation/devicetree/bindings/clock/qcom,a7pll.yaml b/Documentation/devicetree/bindings/clock/qcom,a7pll.yaml index 0e96f693b050..809c34eb7d5a 100644 --- a/Documentation/devicetree/bindings/clock/qcom,a7pll.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,a7pll.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/clock/qcom,a7pll.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm A7 PLL Binding +title: Qualcomm A7 PLL clock maintainers: - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org> diff --git a/Documentation/devicetree/bindings/clock/qcom,aoncc-sm8250.yaml b/Documentation/devicetree/bindings/clock/qcom,aoncc-sm8250.yaml index c40a74b5d672..8b8932bd5a92 100644 --- a/Documentation/devicetree/bindings/clock/qcom,aoncc-sm8250.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,aoncc-sm8250.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/clock/qcom,aoncc-sm8250.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Clock bindings for LPASS Always ON Clock Controller on SM8250 SoCs +title: LPASS Always ON Clock Controller on SM8250 SoCs maintainers: - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> @@ -17,7 +17,7 @@ description: | properties: compatible: - const: qcom,sm8250-lpass-aon + const: qcom,sm8250-lpass-aoncc reg: maxItems: 1 @@ -28,11 +28,13 @@ properties: clocks: items: - description: LPASS Core voting clock + - description: LPASS Audio codec voting clock - description: Glitch Free Mux register clock clock-names: items: - const: core + - const: audio - const: bus required: @@ -50,9 +52,10 @@ examples: #include <dt-bindings/sound/qcom,q6afe.h> clock-controller@3800000 { #clock-cells = <1>; - compatible = "qcom,sm8250-lpass-aon"; + compatible = "qcom,sm8250-lpass-aoncc"; reg = <0x03380000 0x40000>; clocks = <&q6afecc LPASS_HW_MACRO_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>, + <&q6afecc LPASS_HW_DCODEC_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>, <&q6afecc LPASS_CLK_ID_TX_CORE_MCLK LPASS_CLK_ATTRIBUTE_COUPLE_NO>; - clock-names = "core", "bus"; + clock-names = "core", "audio", "bus"; }; diff --git a/Documentation/devicetree/bindings/clock/qcom,audiocc-sm8250.yaml b/Documentation/devicetree/bindings/clock/qcom,audiocc-sm8250.yaml index 915d76206ad0..cfca888f6014 100644 --- a/Documentation/devicetree/bindings/clock/qcom,audiocc-sm8250.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,audiocc-sm8250.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/clock/qcom,audiocc-sm8250.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Clock bindings for LPASS Audio Clock Controller on SM8250 SoCs +title: LPASS Audio Clock Controller on SM8250 SoCs maintainers: - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> @@ -28,11 +28,13 @@ properties: clocks: items: - description: LPASS Core voting clock + - description: LPASS Audio codec voting clock - description: Glitch Free Mux register clock clock-names: items: - const: core + - const: audio - const: bus required: @@ -53,6 +55,7 @@ examples: compatible = "qcom,sm8250-lpass-audiocc"; reg = <0x03300000 0x30000>; clocks = <&q6afecc LPASS_HW_MACRO_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>, + <&q6afecc LPASS_HW_DCODEC_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>, <&q6afecc LPASS_CLK_ID_TX_CORE_MCLK LPASS_CLK_ATTRIBUTE_COUPLE_NO>; - clock-names = "core", "bus"; + clock-names = "core", "audio", "bus"; }; diff --git a/Documentation/devicetree/bindings/clock/qcom,camcc-sm8250.yaml b/Documentation/devicetree/bindings/clock/qcom,camcc-sm8250.yaml index 9f239c3960d1..93ec1f598e6e 100644 --- a/Documentation/devicetree/bindings/clock/qcom,camcc-sm8250.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,camcc-sm8250.yaml @@ -4,16 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,camcc-sm8250.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Camera Clock & Reset Controller Binding for SM8250 +title: Qualcomm Camera Clock & Reset Controller on SM8250 maintainers: - Jonathan Marek <jonathan@marek.ca> description: | - Qualcomm camera clock control module which supports the clocks, resets and + Qualcomm camera clock control module provides the clocks, resets and power domains on SM8250. - See also dt-bindings/clock/qcom,camcc-sm8250.h + See also:: include/dt-bindings/clock/qcom,camcc-sm8250.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,dispcc-sc8280xp.yaml b/Documentation/devicetree/bindings/clock/qcom,dispcc-sc8280xp.yaml new file mode 100644 index 000000000000..28c13237059f --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,dispcc-sc8280xp.yaml @@ -0,0 +1,97 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,dispcc-sc8280xp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display Clock & Reset Controller Binding for SC8280XP + +maintainers: + - Bjorn Andersson <bjorn.andersson@linaro.org> + +description: | + Qualcomm display clock control module which supports the clocks, resets and + power domains for the two MDSS instances on SC8280XP. + + See also: + include/dt-bindings/clock/qcom,dispcc-sc8280xp.h + +properties: + compatible: + enum: + - qcom,sc8280xp-dispcc0 + - qcom,sc8280xp-dispcc1 + + clocks: + items: + - description: AHB interface clock, + - description: SoC CXO clock + - description: SoC sleep clock + - description: DisplayPort 0 link clock + - description: DisplayPort 0 VCO div clock + - description: DisplayPort 1 link clock + - description: DisplayPort 1 VCO div clock + - description: DisplayPort 2 link clock + - description: DisplayPort 2 VCO div clock + - description: DisplayPort 3 link clock + - description: DisplayPort 3 VCO div clock + - description: DSI 0 PLL byte clock + - description: DSI 0 PLL DSI clock + - description: DSI 1 PLL byte clock + - description: DSI 1 PLL DSI clock + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + + power-domains: + items: + - description: MMCX power domain + +required: + - compatible + - reg + - clocks + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-sc8280xp.h> + #include <dt-bindings/clock/qcom,rpmh.h> + #include <dt-bindings/power/qcom-rpmpd.h> + clock-controller@af00000 { + compatible = "qcom,sc8280xp-dispcc0"; + reg = <0x0af00000 0x20000>; + clocks = <&gcc GCC_DISP_AHB_CLK>, + <&rpmhcc RPMH_CXO_CLK>, + <&sleep_clk>, + <&mdss0_dp_phy0 0>, + <&mdss0_dp_phy0 1>, + <&mdss0_dp_phy1 0>, + <&mdss0_dp_phy1 1>, + <&mdss0_dp_phy2 0>, + <&mdss0_dp_phy2 1>, + <&mdss0_dp_phy3 0>, + <&mdss0_dp_phy3 1>, + <&mdss0_dsi0_phy 0>, + <&mdss0_dsi0_phy 1>, + <&mdss0_dsi1_phy 0>, + <&mdss0_dsi1_phy 1>; + power-domains = <&rpmhpd SC8280XP_MMCX>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6125.yaml b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6125.yaml index 7a03ef19c947..8a210c4c5f82 100644 --- a/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6125.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6125.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,dispcc-sm6125.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Display Clock Controller Binding for SM6125 +title: Qualcomm Display Clock Controller on SM6125 maintainers: - Martin Botka <martin.botka@somainline.org> description: | - Qualcomm display clock control module which supports the clocks and - power domains on SM6125. + Qualcomm display clock control module provides the clocks and power domains + on SM6125. - See also: - dt-bindings/clock/qcom,dispcc-sm6125.h + See also:: include/dt-bindings/clock/qcom,dispcc-sm6125.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6350.yaml b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6350.yaml index e706678b353a..8efac3fb159f 100644 --- a/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6350.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm6350.yaml @@ -4,16 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,dispcc-sm6350.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Display Clock & Reset Controller Binding for SM6350 +title: Qualcomm Display Clock & Reset Controller on SM6350 maintainers: - Konrad Dybcio <konrad.dybcio@somainline.org> description: | - Qualcomm display clock control module which supports the clocks, resets and - power domains on SM6350. + Qualcomm display clock control module provides the clocks, resets and power + domains on SM6350. - See also dt-bindings/clock/qcom,dispcc-sm6350.h. + See also:: include/dt-bindings/clock/qcom,dispcc-sm6350.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,dispcc-sm8x50.yaml b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm8x50.yaml index 7a8d375e055e..d6774db257f0 100644 --- a/Documentation/devicetree/bindings/clock/qcom,dispcc-sm8x50.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm8x50.yaml @@ -4,19 +4,19 @@ $id: http://devicetree.org/schemas/clock/qcom,dispcc-sm8x50.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Display Clock & Reset Controller Binding for SM8150/SM8250/SM8350 +title: Qualcomm Display Clock & Reset Controller on SM8150/SM8250/SM8350 maintainers: - Jonathan Marek <jonathan@marek.ca> description: | - Qualcomm display clock control module which supports the clocks, resets and - power domains on SM8150/SM8250/SM8350. + Qualcomm display clock control module provides the clocks, resets and power + domains on SM8150/SM8250/SM8350. - See also: - dt-bindings/clock/qcom,dispcc-sm8150.h - dt-bindings/clock/qcom,dispcc-sm8250.h - dt-bindings/clock/qcom,dispcc-sm8350.h + See also:: + include/dt-bindings/clock/qcom,dispcc-sm8150.h + include/dt-bindings/clock/qcom,dispcc-sm8250.h + include/dt-bindings/clock/qcom,dispcc-sm8350.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-apq8064.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-apq8064.yaml index 6b4efd64c154..09cd7a786871 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-apq8064.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-apq8064.yaml @@ -4,22 +4,22 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-apq8064.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for APQ8064/MSM8960 - -allOf: - - $ref: qcom,gcc.yaml# +title: Qualcomm Global Clock & Reset Controller on APQ8064/MSM8960 maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on APQ8064. + Qualcomm global clock control module provides the clocks, resets and power + domains on APQ8064. - See also: - - dt-bindings/clock/qcom,gcc-msm8960.h - - dt-bindings/reset/qcom,gcc-msm8960.h + See also:: + include/dt-bindings/clock/qcom,gcc-msm8960.h + include/dt-bindings/reset/qcom,gcc-msm8960.h + +allOf: + - $ref: qcom,gcc.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-apq8084.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-apq8084.yaml index 397fb918e032..8ade176c24f4 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-apq8084.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-apq8084.yaml @@ -4,19 +4,19 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-apq8084.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for APQ8084 +title: Qualcomm Global Clock & Reset Controller on APQ8084 maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <quic_tdas@quicinc.com> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on APQ8084. + Qualcomm global clock control module provides the clocks, resets and power + domains on APQ8084. See also:: - - dt-bindings/clock/qcom,gcc-apq8084.h - - dt-bindings/reset/qcom,gcc-apq8084.h + include/dt-bindings/clock/qcom,gcc-apq8084.h + include/dt-bindings/reset/qcom,gcc-apq8084.h allOf: - $ref: qcom,gcc.yaml# diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8064.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8064.yaml index 9eb91dd22557..93f3084b97c1 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8064.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8064.yaml @@ -4,21 +4,21 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-ipq8064.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for IPQ8064 - -allOf: - - $ref: qcom,gcc.yaml# +title: Qualcomm Global Clock & Reset Controller on IPQ8064 maintainers: - Ansuel Smith <ansuelsmth@gmail.com> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on IPQ8064. + Qualcomm global clock control module provides the clocks, resets and power + domains on IPQ8064. - See also: - - dt-bindings/clock/qcom,gcc-ipq806x.h (qcom,gcc-ipq8064) - - dt-bindings/reset/qcom,gcc-ipq806x.h (qcom,gcc-ipq8064) + See also:: + include/dt-bindings/clock/qcom,gcc-ipq806x.h (qcom,gcc-ipq8064) + include/dt-bindings/reset/qcom,gcc-ipq806x.h (qcom,gcc-ipq8064) + +allOf: + - $ref: qcom,gcc.yaml# properties: compatible: @@ -27,14 +27,18 @@ properties: - const: syscon clocks: + minItems: 2 items: - description: PXO source - description: CXO source + - description: PLL4 from LCC clock-names: + minItems: 2 items: - const: pxo - const: cxo + - const: pll4 thermal-sensor: type: object @@ -51,13 +55,14 @@ unevaluatedProperties: false examples: - | + #include <dt-bindings/clock/qcom,lcc-ipq806x.h> #include <dt-bindings/interrupt-controller/arm-gic.h> gcc: clock-controller@900000 { compatible = "qcom,gcc-ipq8064", "syscon"; reg = <0x00900000 0x4000>; - clocks = <&pxo_board>, <&cxo_board>; - clock-names = "pxo", "cxo"; + clocks = <&pxo_board>, <&cxo_board>, <&lcc PLL4>; + clock-names = "pxo", "cxo", "pll4"; #clock-cells = <1>; #reset-cells = <1>; #power-domain-cells = <1>; diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8074.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8074.yaml index 21470f52ce36..deef398a9872 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8074.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-ipq8074.yaml @@ -4,47 +4,39 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-ipq8074.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Bindingfor IPQ8074 +title: Qualcomm Global Clock & Reset Controller on IPQ8074 maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on IPQ8074. + Qualcomm global clock control module provides the clocks, resets and power + domains on IPQ8074. - See also: - - dt-bindings/clock/qcom,gcc-ipq8074.h + See also:: include/dt-bindings/clock/qcom,gcc-ipq8074.h + +allOf: + - $ref: qcom,gcc.yaml# properties: compatible: const: qcom,gcc-ipq8074 - '#clock-cells': - const: 1 - - '#power-domain-cells': - const: 1 - - '#reset-cells': - const: 1 - - reg: - maxItems: 1 + clocks: + items: + - description: board XO clock + - description: sleep clock - protected-clocks: - description: - Protected clock specifier list as per common clock binding. + clock-names: + items: + - const: xo + - const: sleep_clk required: - compatible - - reg - - '#clock-cells' - - '#power-domain-cells' - - '#reset-cells' -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8660.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8660.yaml index 09b2ea60d356..c9e985548621 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8660.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8660.yaml @@ -4,22 +4,22 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-msm8660.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for MSM8660 +title: Qualcomm Global Clock & Reset Controller on MSM8660 maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <quic_tdas@quicinc.com> description: | - Qualcomm global clock control module which supports the clocks and resets on + Qualcomm global clock control module provides the clocks and resets on MSM8660 - See also: - - dt-bindings/clock/qcom,gcc-msm8660.h - - dt-bindings/reset/qcom,gcc-msm8660.h + See also:: + include/dt-bindings/clock/qcom,gcc-msm8660.h + include/dt-bindings/reset/qcom,gcc-msm8660.h allOf: - - $ref: "qcom,gcc.yaml#" + - $ref: qcom,gcc.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8909.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8909.yaml index 2272ea5f78d0..6279a59c2e20 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8909.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8909.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-msm8909.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for MSM8909 +title: Qualcomm Global Clock & Reset Controller on MSM8909 maintainers: - Stephan Gerhold <stephan@gerhold.net> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on MSM8909. + Qualcomm global clock control module provides the clocks, resets and power + domains on MSM8909. - See also: - - dt-bindings/clock/qcom,gcc-msm8909.h + See also:: include/dt-bindings/clock/qcom,gcc-msm8909.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8916.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8916.yaml index 2ceb1e501ef9..ad84c0f7680b 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8916.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8916.yaml @@ -4,21 +4,21 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-msm8916.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for MSM8916 and MSM8939 +title: Qualcomm Global Clock & Reset Controller on MSM8916 and MSM8939 maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <quic_tdas@quicinc.com> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on MSM8916 or MSM8939. + Qualcomm global clock control module provides the clocks, resets and power + domains on MSM8916 or MSM8939. - See also: - - dt-bindings/clock/qcom,gcc-msm8916.h - - dt-bindings/clock/qcom,gcc-msm8939.h - - dt-bindings/reset/qcom,gcc-msm8916.h - - dt-bindings/reset/qcom,gcc-msm8939.h + See also:: + include/dt-bindings/clock/qcom,gcc-msm8916.h + include/dt-bindings/clock/qcom,gcc-msm8939.h + include/dt-bindings/reset/qcom,gcc-msm8916.h + include/dt-bindings/reset/qcom,gcc-msm8939.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8974.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8974.yaml new file mode 100644 index 000000000000..1927aecc86bc --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8974.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-msm8974.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller on MSM8974 (including Pro) and MSM8226 + Controller + +maintainers: + - Stephen Boyd <sboyd@kernel.org> + - Taniya Das <quic_tdas@quicinc.com> + +description: | + Qualcomm global clock control module provides the clocks, resets and power + domains on MSM8974 (all variants) and MSM8226. + + See also:: + include/dt-bindings/clock/qcom,gcc-msm8974.h (qcom,gcc-msm8226 and qcom,gcc-msm8974) + include/dt-bindings/reset/qcom,gcc-msm8974.h (qcom,gcc-msm8226 and qcom,gcc-msm8974) + +$ref: qcom,gcc.yaml# + +properties: + compatible: + enum: + - qcom,gcc-msm8226 + - qcom,gcc-msm8974 + - qcom,gcc-msm8974pro + - qcom,gcc-msm8974pro-ac + + clocks: + items: + - description: XO source + - description: Sleep clock source + + clock-names: + items: + - const: xo + - const: sleep_clk + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@fc400000 { + compatible = "qcom,gcc-msm8974"; + reg = <0x00100000 0x94000>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + + clock-names = "xo", "sleep_clk"; + clocks = <&xo_board>, + <&sleep_clk>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8976.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8976.yaml index 4b7d69518371..d2186e25f55f 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8976.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8976.yaml @@ -4,18 +4,17 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-msm8976.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for MSM8976 +title: Qualcomm Global Clock & Reset Controller on MSM8976 maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on MSM8976. + Qualcomm global clock control module provides the clocks, resets and power + domains on MSM8976. - See also: - - dt-bindings/clock/qcom,gcc-msm8976.h + See also:: include/dt-bindings/clock/qcom,gcc-msm8976.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8994.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8994.yaml index 7b9fef6d9b23..8f0f20c1442a 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8994.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8994.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-msm8994.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for MSM8994 +title: Qualcomm Global Clock & Reset Controller on MSM8994 maintainers: - Konrad Dybcio <konrad.dybcio@somainline.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on MSM8994 and MSM8992. + Qualcomm global clock control module provides the clocks, resets and power + domains on MSM8994 and MSM8992. - See also: - - dt-bindings/clock/qcom,gcc-msm8994.h + See also:: include/dt-bindings/clock/qcom,gcc-msm8994.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8996.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8996.yaml index dfc5165db9f1..f77036ace31b 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8996.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8996.yaml @@ -4,18 +4,17 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-msm8996.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for MSM8996 +title: Qualcomm Global Clock & Reset Controller on MSM8996 maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm global clock control module which supports the clocks, resets and + Qualcomm global clock control module which provides the clocks, resets and power domains on MSM8996. - See also: - - dt-bindings/clock/qcom,gcc-msm8996.h + See also:: include/dt-bindings/clock/qcom,gcc-msm8996.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8998.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8998.yaml index 544a2335cf05..2d5355cf9def 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-msm8998.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-msm8998.yaml @@ -4,18 +4,17 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-msm8998.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for MSM8998 +title: Qualcomm Global Clock & Reset Controller on MSM8998 maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on MSM8998. + Qualcomm global clock control module provides the clocks, resets and power + domains on MSM8998. - See also: - - dt-bindings/clock/qcom,gcc-msm8998.h + See also:: include/dt-bindings/clock/qcom,gcc-msm8998.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-other.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-other.yaml index 76988e04c7db..2e8acca64af1 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-other.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-other.yaml @@ -4,30 +4,27 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-other.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding +title: Qualcomm Global Clock & Reset Controller maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains. - - See also: - - dt-bindings/clock/qcom,gcc-ipq4019.h - - dt-bindings/clock/qcom,gcc-ipq6018.h - - dt-bindings/reset/qcom,gcc-ipq6018.h - - dt-bindings/clock/qcom,gcc-msm8953.h - - dt-bindings/clock/qcom,gcc-msm8974.h (qcom,gcc-msm8226 and qcom,gcc-msm8974) - - dt-bindings/reset/qcom,gcc-msm8974.h (qcom,gcc-msm8226 and qcom,gcc-msm8974) - - dt-bindings/clock/qcom,gcc-mdm9607.h - - dt-bindings/clock/qcom,gcc-mdm9615.h - - dt-bindings/reset/qcom,gcc-mdm9615.h - - dt-bindings/clock/qcom,gcc-sdm660.h (qcom,gcc-sdm630 and qcom,gcc-sdm660) + Qualcomm global clock control module provides the clocks, resets and power + domains. + + See also:: + include/dt-bindings/clock/qcom,gcc-ipq4019.h + include/dt-bindings/clock/qcom,gcc-ipq6018.h + include/dt-bindings/reset/qcom,gcc-ipq6018.h + include/dt-bindings/clock/qcom,gcc-msm8953.h + include/dt-bindings/clock/qcom,gcc-mdm9607.h + include/dt-bindings/clock/qcom,gcc-mdm9615.h + include/dt-bindings/reset/qcom,gcc-mdm9615.h allOf: - - $ref: "qcom,gcc.yaml#" + - $ref: qcom,gcc.yaml# properties: compatible: @@ -35,14 +32,8 @@ properties: - qcom,gcc-ipq4019 - qcom,gcc-ipq6018 - qcom,gcc-mdm9607 - - qcom,gcc-msm8226 - qcom,gcc-msm8953 - - qcom,gcc-msm8974 - - qcom,gcc-msm8974pro - - qcom,gcc-msm8974pro-ac - qcom,gcc-mdm9615 - - qcom,gcc-sdm630 - - qcom,gcc-sdm660 required: - compatible @@ -50,10 +41,9 @@ required: unevaluatedProperties: false examples: - # Example for GCC for MSM8974: - | clock-controller@900000 { - compatible = "qcom,gcc-msm8974"; + compatible = "qcom,gcc-mdm9607"; reg = <0x900000 0x4000>; #clock-cells = <1>; #reset-cells = <1>; diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-qcm2290.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-qcm2290.yaml index aec37e3f5e30..c9bec4656f6e 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-qcm2290.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-qcm2290.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-qcm2290.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for QCM2290 +title: Qualcomm Global Clock & Reset Controller on QCM2290 maintainers: - Shawn Guo <shawn.guo@linaro.org> description: | - Qualcomm global clock control module which supports the clocks, resets - and power domains on QCM2290. + Qualcomm global clock control module provides the clocks, resets and power + domains on QCM2290. - See also: - - dt-bindings/clock/qcom,gcc-qcm2290.h + See also:: include/dt-bindings/clock/qcom,gcc-qcm2290.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-qcs404.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-qcs404.yaml index ce06f3f8c3e3..dca5775f79a4 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-qcs404.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-qcs404.yaml @@ -4,18 +4,17 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-qcs404.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Bindingfor QCS404 +title: Qualcomm Global Clock & Reset Controller on QCS404 maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on QCS404. + Qualcomm global clock control module provides the clocks, resets and power + domains on QCS404. - See also: - - dt-bindings/clock/qcom,gcc-qcs404.h + See also:: include/dt-bindings/clock/qcom,gcc-qcs404.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sc7180.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sc7180.yaml index e4d490e65d14..06dce0c6b7d0 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sc7180.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sc7180.yaml @@ -4,18 +4,17 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-sc7180.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for SC7180 +title: Qualcomm Global Clock & Reset Controller on SC7180 maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on SC7180. + Qualcomm global clock control module provides the clocks, resets and power + domains on SC7180. - See also: - - dt-bindings/clock/qcom,gcc-sc7180.h + See also:: include/dt-bindings/clock/qcom,gcc-sc7180.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sc7280.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sc7280.yaml index ea61367e5abc..947b47168cec 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sc7280.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sc7280.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-sc7280.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for SC7280 +title: Qualcomm Global Clock & Reset Controller on SC7280 maintainers: - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on SC7280. + Qualcomm global clock control module provides the clocks, resets and power + domains on SC7280. - See also: - - dt-bindings/clock/qcom,gcc-sc7280.h + See also:: include/dt-bindings/clock/qcom,gcc-sc7280.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sc8180x.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sc8180x.yaml index 30b5d1215fa8..6c4846b34e4b 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sc8180x.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sc8180x.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-sc8180x.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for SC8180x +title: Qualcomm Global Clock & Reset Controller on SC8180x maintainers: - Bjorn Andersson <bjorn.andersson@linaro.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on SC8180x. + Qualcomm global clock control module provides the clocks, resets and power + domains on SC8180x. - See also: - - dt-bindings/clock/qcom,gcc-sc8180x.h + See also:: include/dt-bindings/clock/qcom,gcc-sc8180x.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sc8280xp.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sc8280xp.yaml index b1bf768530a3..c9d8e436d73a 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sc8280xp.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sc8280xp.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-sc8280xp.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for SC8280xp +title: Qualcomm Global Clock & Reset Controller on SC8280xp maintainers: - Bjorn Andersson <bjorn.andersson@linaro.org> description: | - Qualcomm global clock control module which supports the clocks, resets and + Qualcomm global clock control module provides the clocks, resets and power domains on SC8280xp. - See also: - - include/dt-bindings/clock/qcom,gcc-sc8280xp.h + See also:: include/dt-bindings/clock/qcom,gcc-sc8280xp.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sdm660.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sdm660.yaml new file mode 100644 index 000000000000..52e7412aace5 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sdm660.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gcc-sdm660.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SDM660/SDM630/SDM636 Global Clock & Reset Controller + +maintainers: + - Stephen Boyd <sboyd@kernel.org> + - Taniya Das <quic_tdas@quicinc.com> + +description: | + Qualcomm global clock control module provides the clocks, resets and power + domains on SDM630, SDM636 and SDM660 + + See also:: + include/dt-bindings/clock/qcom,gcc-sdm660.h (qcom,gcc-sdm630 and qcom,gcc-sdm660) + +$ref: qcom,gcc.yaml# + +properties: + compatible: + enum: + - qcom,gcc-sdm630 + - qcom,gcc-sdm660 + + clocks: + items: + - description: XO source + - description: Sleep clock source + + clock-names: + items: + - const: xo + - const: sleep_clk + + power-domains: + maxItems: 1 + +required: + - compatible + +unevaluatedProperties: false + +examples: + # Example for GCC for SDM660: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@100000 { + compatible = "qcom,gcc-sdm660"; + reg = <0x00100000 0x94000>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + + clock-names = "xo", "sleep_clk"; + clocks = <&xo_board>, + <&sleep_clk>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sdm845.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sdm845.yaml index e169d46c78f8..68e1b7822fe0 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sdm845.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sdm845.yaml @@ -4,18 +4,17 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-sdm845.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding +title: Qualcomm Global Clock & Reset Controller on SDM670 and SDM845 maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on SDM845 + Qualcomm global clock control module provides the clocks, resets and power + domains on SDM670 and SDM845 - See also: - - dt-bindings/clock/qcom,gcc-sdm845.h + See also:: include/dt-bindings/clock/qcom,gcc-sdm845.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sdx55.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sdx55.yaml index 13ffa16e0833..68d3099c96ae 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sdx55.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sdx55.yaml @@ -4,18 +4,17 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-sdx55.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for SDX55 +title: Qualcomm Global Clock & Reset Controller on SDX55 maintainers: - Vinod Koul <vkoul@kernel.org> - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org> description: | - Qualcomm global clock control module which supports the clocks, resets and + Qualcomm global clock control module provides the clocks, resets and power domains on SDX55 - See also: - - dt-bindings/clock/qcom,gcc-sdx55.h + See also:: include/dt-bindings/clock/qcom,gcc-sdx55.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sdx65.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sdx65.yaml index 8a1419c4d465..ba62baab916c 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sdx65.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sdx65.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-sdx65.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for SDX65 +title: Qualcomm Global Clock & Reset Controller on SDX65 maintainers: - Vamsi krishna Lanka <quic_vamslank@quicinc.com> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on SDX65 + Qualcomm global clock control module provides the clocks, resets and power + domains on SDX65 - See also: - - dt-bindings/clock/qcom,gcc-sdx65.h + See also:: include/dt-bindings/clock/qcom,gcc-sdx65.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sm6115.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sm6115.yaml index bb81a27a1b16..a5ad0a3da397 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sm6115.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sm6115.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-sm6115.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for SM6115 and SM4250 +title: Qualcomm Global Clock & Reset Controller on SM6115 and SM4250 maintainers: - Iskren Chernev <iskren.chernev@gmail.com> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on SM4250/6115. + Qualcomm global clock control module provides the clocks, resets and power + domains on SM4250/6115. - See also: - - dt-bindings/clock/qcom,gcc-sm6115.h + See also:: include/dt-bindings/clock/qcom,gcc-sm6115.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sm6125.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sm6125.yaml index 03e84e15815c..8e37623788bd 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sm6125.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sm6125.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-sm6125.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for SM6125 +title: Qualcomm Global Clock & Reset Controller on SM6125 maintainers: - Konrad Dybcio <konrad.dybcio@somainline.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on SM6125. + Qualcomm global clock control module provides the clocks, resets and power + domains on SM6125. - See also: - - dt-bindings/clock/qcom,gcc-sm6125.h + See also:: include/dt-bindings/clock/qcom,gcc-sm6125.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sm6350.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sm6350.yaml index cbe98c01c085..d1b26ab48eaf 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sm6350.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sm6350.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-sm6350.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for SM6350 +title: Qualcomm Global Clock & Reset Controller on SM6350 maintainers: - Konrad Dybcio <konrad.dybcio@somainline.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on SM6350. + Qualcomm global clock control module provides the clocks, resets and power + domains on SM6350. - See also: - - dt-bindings/clock/qcom,gcc-sm6350.h + See also:: include/dt-bindings/clock/qcom,gcc-sm6350.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sm8150.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8150.yaml index 0333ccb07d8d..3ea0ff37a4cb 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sm8150.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8150.yaml @@ -4,18 +4,17 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-sm8150.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for SM8150 +title: Qualcomm Global Clock & Reset Controller on SM8150 maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on SM8150. + Qualcomm global clock control module provides the clocks, resets and power + domains on SM8150. - See also: - - dt-bindings/clock/qcom,gcc-sm8150.h + See also:: include/dt-bindings/clock/qcom,gcc-sm8150.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sm8250.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8250.yaml index 4e2a9cac0a91..b752542ee20c 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sm8250.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8250.yaml @@ -4,18 +4,17 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-sm8250.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for SM8250 +title: Qualcomm Global Clock & Reset Controller on SM8250 maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on SM8250. + Qualcomm global clock control module provides the clocks, resets and power + domains on SM8250. - See also: - - dt-bindings/clock/qcom,gcc-sm8250.h + See also:: include/dt-bindings/clock/qcom,gcc-sm8250.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sm8350.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8350.yaml index 3edbeca70a9c..703d9e075247 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sm8350.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8350.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-sm8350.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for SM8350 +title: Qualcomm Global Clock & Reset Controller on SM8350 maintainers: - Vinod Koul <vkoul@kernel.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on SM8350. + Qualcomm global clock control module provides the clocks, resets and power + domains on SM8350. - See also: - - dt-bindings/clock/qcom,gcc-sm8350.h + See also:: include/dt-bindings/clock/qcom,gcc-sm8350.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sm8450.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8450.yaml index 102ce6862e24..9a31981fbeb2 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sm8450.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sm8450.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc-sm8450.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for SM8450 +title: Qualcomm Global Clock & Reset Controller on SM8450 maintainers: - Vinod Koul <vkoul@kernel.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on SM8450 + Qualcomm global clock control module provides the clocks, resets and power + domains on SM8450 - See also: - - dt-bindings/clock/qcom,gcc-sm8450.h + See also:: include/dt-bindings/clock/qcom,gcc-sm8450.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc.yaml index 2ed27a2ef445..1ab416c83c8d 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc.yaml @@ -4,15 +4,15 @@ $id: http://devicetree.org/schemas/clock/qcom,gcc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding Common Bindings +title: Qualcomm Global Clock & Reset Controller Common Bindings maintainers: - Stephen Boyd <sboyd@kernel.org> - Taniya Das <tdas@codeaurora.org> description: | - Common bindings for Qualcomm global clock control module which supports - the clocks, resets and power domains. + Common bindings for Qualcomm global clock control module providing the + clocks, resets and power domains. properties: '#clock-cells': diff --git a/Documentation/devicetree/bindings/clock/qcom,gpucc-sdm660.yaml b/Documentation/devicetree/bindings/clock/qcom,gpucc-sdm660.yaml index 3f70eb59aae3..0518ea963cdd 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gpucc-sdm660.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gpucc-sdm660.yaml @@ -4,13 +4,13 @@ $id: http://devicetree.org/schemas/clock/qcom,gpucc-sdm660.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Graphics Clock & Reset Controller Binding for SDM630 and SDM660 +title: Qualcomm Graphics Clock & Reset Controller on SDM630 and SDM660 maintainers: - AngeloGioacchino Del Regno <angelogioacchino.delregno@somainline.org> description: | - Qualcomm graphics clock control module which supports the clocks, resets and + Qualcomm graphics clock control module provides the clocks, resets and power domains on SDM630 and SDM660. See also dt-bindings/clock/qcom,gpucc-sdm660.h. diff --git a/Documentation/devicetree/bindings/clock/qcom,gpucc-sm8350.yaml b/Documentation/devicetree/bindings/clock/qcom,gpucc-sm8350.yaml index 0a0546c079a9..fb7ae3d18503 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gpucc-sm8350.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gpucc-sm8350.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,gpucc-sm8350.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Graphics Clock & Reset Controller Binding +title: Qualcomm Graphics Clock & Reset Controller on SM8350 maintainers: - Robert Foss <robert.foss@linaro.org> description: | - Qualcomm graphics clock control module which supports the clocks, resets and - power domains on Qualcomm SoCs. + Qualcomm graphics clock control module provides the clocks, resets and power + domains on Qualcomm SoCs. - See also: - dt-bindings/clock/qcom,gpucc-sm8350.h + See also:: include/dt-bindings/clock/qcom,gpucc-sm8350.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml b/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml index a7d0af1bd9e0..7256c438a4cf 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml @@ -4,23 +4,23 @@ $id: http://devicetree.org/schemas/clock/qcom,gpucc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Graphics Clock & Reset Controller Binding +title: Qualcomm Graphics Clock & Reset Controller maintainers: - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm graphics clock control module which supports the clocks, resets and - power domains on Qualcomm SoCs. + Qualcomm graphics clock control module provides the clocks, resets and power + domains on Qualcomm SoCs. - See also: - dt-bindings/clock/qcom,gpucc-sdm845.h - dt-bindings/clock/qcom,gpucc-sc7180.h - dt-bindings/clock/qcom,gpucc-sc7280.h - dt-bindings/clock/qcom,gpucc-sc8280xp.h - dt-bindings/clock/qcom,gpucc-sm6350.h - dt-bindings/clock/qcom,gpucc-sm8150.h - dt-bindings/clock/qcom,gpucc-sm8250.h + See also:: + include/dt-bindings/clock/qcom,gpucc-sdm845.h + include/dt-bindings/clock/qcom,gpucc-sc7180.h + include/dt-bindings/clock/qcom,gpucc-sc7280.h + include/dt-bindings/clock/qcom,gpucc-sc8280xp.h + include/dt-bindings/clock/qcom,gpucc-sm6350.h + include/dt-bindings/clock/qcom,gpucc-sm8150.h + include/dt-bindings/clock/qcom,gpucc-sm8250.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,lcc.txt b/Documentation/devicetree/bindings/clock/qcom,lcc.txt deleted file mode 100644 index a3c78aa88038..000000000000 --- a/Documentation/devicetree/bindings/clock/qcom,lcc.txt +++ /dev/null @@ -1,22 +0,0 @@ -Qualcomm LPASS Clock & Reset Controller Binding ------------------------------------------------- - -Required properties : -- compatible : shall contain only one of the following: - - "qcom,lcc-msm8960" - "qcom,lcc-apq8064" - "qcom,lcc-ipq8064" - "qcom,lcc-mdm9615" - -- reg : shall contain base register location and length -- #clock-cells : shall contain 1 -- #reset-cells : shall contain 1 - -Example: - clock-controller@28000000 { - compatible = "qcom,lcc-ipq8064"; - reg = <0x28000000 0x1000>; - #clock-cells = <1>; - #reset-cells = <1>; - }; diff --git a/Documentation/devicetree/bindings/clock/qcom,lcc.yaml b/Documentation/devicetree/bindings/clock/qcom,lcc.yaml new file mode 100644 index 000000000000..8c783823e93c --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,lcc.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,lcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm LPASS Clock & Reset Controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + +properties: + compatible: + enum: + - qcom,lcc-apq8064 + - qcom,lcc-ipq8064 + - qcom,lcc-mdm9615 + - qcom,lcc-msm8960 + + clocks: + maxItems: 8 + + clock-names: + maxItems: 8 + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - '#clock-cells' + - '#reset-cells' + +additionalProperties: false + +allOf: + - if: + properties: + compatible: + contains: + enum: + - qcom,lcc-apq8064 + - qcom,lcc-msm8960 + then: + properties: + clocks: + items: + - description: Board PXO source + - description: PLL 4 Vote clock + - description: MI2S codec clock + - description: Mic I2S codec clock + - description: Mic I2S spare clock + - description: Speaker I2S codec clock + - description: Speaker I2S spare clock + - description: PCM codec clock + + clock-names: + items: + - const: pxo + - const: pll4_vote + - const: mi2s_codec_clk + - const: codec_i2s_mic_codec_clk + - const: spare_i2s_mic_codec_clk + - const: codec_i2s_spkr_codec_clk + - const: spare_i2s_spkr_codec_clk + - const: pcm_codec_clk + + required: + - clocks + - clock-names + +examples: + - | + clock-controller@28000000 { + compatible = "qcom,lcc-ipq8064"; + reg = <0x28000000 0x1000>; + #clock-cells = <1>; + #reset-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,lpasscc.txt b/Documentation/devicetree/bindings/clock/qcom,lpasscc.txt deleted file mode 100644 index b9e9787045b9..000000000000 --- a/Documentation/devicetree/bindings/clock/qcom,lpasscc.txt +++ /dev/null @@ -1,26 +0,0 @@ -Qualcomm LPASS Clock Controller Binding ------------------------------------------------ - -Required properties : -- compatible : shall contain "qcom,sdm845-lpasscc" -- #clock-cells : from common clock binding, shall contain 1. -- reg : shall contain base register address and size, - in the order - Index-0 maps to LPASS_CC register region - Index-1 maps to LPASS_QDSP6SS register region - -Optional properties : -- reg-names : register names of LPASS domain - "cc", "qdsp6ss". - -Example: - -The below node has to be defined in the cases where the LPASS peripheral loader -would bring the subsystem out of reset. - - lpasscc: clock-controller@17014000 { - compatible = "qcom,sdm845-lpasscc"; - reg = <0x17014000 0x1f004>, <0x17300000 0x200>; - reg-names = "cc", "qdsp6ss"; - #clock-cells = <1>; - }; diff --git a/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml b/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml index 03faab5b6a41..e6d17426e903 100644 --- a/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,mmcc.yaml @@ -4,14 +4,14 @@ $id: http://devicetree.org/schemas/clock/qcom,mmcc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Multimedia Clock & Reset Controller Binding +title: Qualcomm Multimedia Clock & Reset Controller maintainers: - Jeffrey Hugo <quic_jhugo@quicinc.com> - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm multimedia clock control module which supports the clocks, resets and + Qualcomm multimedia clock control module provides the clocks, resets and power domains. properties: @@ -104,6 +104,44 @@ allOf: compatible: contains: enum: + - qcom,mmcc-msm8974 + then: + properties: + clocks: + items: + - description: Board XO source + - description: MMSS GPLL0 voted clock + - description: GPLL0 voted clock + - description: GPLL1 voted clock + - description: GFX3D clock source + - description: DSI phy instance 0 dsi clock + - description: DSI phy instance 0 byte clock + - description: DSI phy instance 1 dsi clock + - description: DSI phy instance 1 byte clock + - description: HDMI phy PLL clock + - description: eDP phy PLL link clock + - description: eDP phy PLL vco clock + + clock-names: + items: + - const: xo + - const: mmss_gpll0_vote + - const: gpll0_vote + - const: gpll1_vote + - const: gfx3d_clk_src + - const: dsi0pll + - const: dsi0pllbyte + - const: dsi1pll + - const: dsi1pllbyte + - const: hdmipll + - const: edp_link_clk + - const: edp_vco_div + + - if: + properties: + compatible: + contains: + enum: - qcom,mmcc-msm8994 - qcom,mmcc-msm8998 - qcom,mmcc-sdm630 diff --git a/Documentation/devicetree/bindings/clock/qcom,msm8998-gpucc.yaml b/Documentation/devicetree/bindings/clock/qcom,msm8998-gpucc.yaml index d747bb58f0a7..2d8897991663 100644 --- a/Documentation/devicetree/bindings/clock/qcom,msm8998-gpucc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,msm8998-gpucc.yaml @@ -4,16 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,msm8998-gpucc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Graphics Clock & Reset Controller Binding for MSM8998 +title: Qualcomm Graphics Clock & Reset Controller on MSM8998 maintainers: - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm graphics clock control module which supports the clocks, resets and - power domains on MSM8998. + Qualcomm graphics clock control module provides the clocks, resets and power + domains on MSM8998. - See also dt-bindings/clock/qcom,gpucc-msm8998.h. + See also:: include/dt-bindings/clock/qcom,gpucc-msm8998.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,q6sstopcc.yaml b/Documentation/devicetree/bindings/clock/qcom,q6sstopcc.yaml index bbaaf1e2a203..03fa30fe9253 100644 --- a/Documentation/devicetree/bindings/clock/qcom,q6sstopcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,q6sstopcc.yaml @@ -11,7 +11,7 @@ maintainers: properties: compatible: - const: "qcom,qcs404-q6sstopcc" + const: qcom,qcs404-q6sstopcc reg: items: diff --git a/Documentation/devicetree/bindings/clock/qcom,qcm2290-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,qcm2290-dispcc.yaml index 973e408c6268..4a00f2d41684 100644 --- a/Documentation/devicetree/bindings/clock/qcom,qcm2290-dispcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,qcm2290-dispcc.yaml @@ -4,16 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,qcm2290-dispcc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Display Clock & Reset Controller Binding for qcm2290 +title: Qualcomm Display Clock & Reset Controller on QCM2290 maintainers: - Loic Poulain <loic.poulain@linaro.org> description: | - Qualcomm display clock control module which supports the clocks, resets and - power domains on qcm2290. + Qualcomm display clock control module provides the clocks, resets and power + domains on qcm2290. - See also dt-bindings/clock/qcom,dispcc-qcm2290.h. + See also:: include/dt-bindings/clock/qcom,dispcc-qcm2290.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml index 437a34b930e3..fccb91e78e49 100644 --- a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml @@ -17,6 +17,7 @@ description: | properties: compatible: enum: + - qcom,qdu1000-rpmh-clk - qcom,sc7180-rpmh-clk - qcom,sc7280-rpmh-clk - qcom,sc8180x-rpmh-clk diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-camcc.yaml index f49027edfc44..098c8acf4bad 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7180-camcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7180-camcc.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,sc7180-camcc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Camera Clock & Reset Controller Binding for SC7180 +title: Qualcomm Camera Clock & Reset Controller on SC7180 maintainers: - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm camera clock control module which supports the clocks, resets and - power domains on SC7180. + Qualcomm camera clock control module provides the clocks, resets and power + domains on SC7180. - See also: - - dt-bindings/clock/qcom,camcc-sc7180.h + See also:: include/dt-bindings/clock/qcom,camcc-sc7180.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-dispcc.yaml index e94847f92770..95ad16d0abc3 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7180-dispcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7180-dispcc.yaml @@ -4,16 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,sc7180-dispcc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Display Clock & Reset Controller Binding for SC7180 +title: Qualcomm Display Clock & Reset Controller on SC7180 maintainers: - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm display clock control module which supports the clocks, resets and - power domains on SC7180. + Qualcomm display clock control module provides the clocks, resets and power + domains on SC7180. - See also dt-bindings/clock/qcom,dispcc-sc7180.h. + See also:: include/dt-bindings/clock/qcom,dispcc-sc7180.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-lpasscorecc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-lpasscorecc.yaml index c54172fbf29f..f297694ef8b8 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7180-lpasscorecc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7180-lpasscorecc.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,sc7180-lpasscorecc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm LPASS Core Clock Controller Binding for SC7180 +title: Qualcomm LPASS Core Clock Controller on SC7180 maintainers: - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm LPASS core clock control module which supports the clocks and - power domains on SC7180. + Qualcomm LPASS core clock control module provides the clocks and power + domains on SC7180. - See also: - - dt-bindings/clock/qcom,lpasscorecc-sc7180.h + See also:: include/dt-bindings/clock/qcom,lpasscorecc-sc7180.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-mss.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-mss.yaml index 970030986a86..1e856a8a996e 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7180-mss.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7180-mss.yaml @@ -4,16 +4,15 @@ $id: http://devicetree.org/schemas/clock/qcom,sc7180-mss.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Modem Clock Controller Binding for SC7180 +title: Qualcomm Modem Clock Controller on SC7180 maintainers: - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm modem clock control module which supports the clocks on SC7180. + Qualcomm modem clock control module provides the clocks on SC7180. - See also: - - dt-bindings/clock/qcom,mss-sc7180.h + See also:: include/dt-bindings/clock/qcom,mss-sc7180.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7280-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7280-camcc.yaml index f27ca6f03ffa..b60adbad4590 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7280-camcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7280-camcc.yaml @@ -4,16 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,sc7280-camcc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Camera Clock & Reset Controller Binding for SC7280 +title: Qualcomm Camera Clock & Reset Controller on SC7280 maintainers: - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm camera clock control module which supports the clocks, resets and + Qualcomm camera clock control module provides the clocks, resets and power domains on SC7280. - See also dt-bindings/clock/qcom,camcc-sc7280.h + See also:: include/dt-bindings/clock/qcom,camcc-sc7280.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7280-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7280-dispcc.yaml index 2178666fb697..cfe6594a0a6b 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7280-dispcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7280-dispcc.yaml @@ -4,16 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,sc7280-dispcc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Display Clock & Reset Controller Binding for SC7280 +title: Qualcomm Display Clock & Reset Controller on SC7280 maintainers: - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm display clock control module which supports the clocks, resets and - power domains on SC7280. + Qualcomm display clock control module provides the clocks, resets and power + domains on SC7280. - See also dt-bindings/clock/qcom,dispcc-sc7280.h. + See also:: include/dt-bindings/clock/qcom,dispcc-sc7280.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscc.yaml index 633887dc2f8a..6151fdebbff8 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscc.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,sc7280-lpasscc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm LPASS Core Clock Controller Binding for SC7280 +title: Qualcomm LPASS Core Clock Controller on SC7280 maintainers: - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm LPASS core clock control module which supports the clocks and - power domains on SC7280. + Qualcomm LPASS core clock control module provides the clocks and power + domains on SC7280. - See also: - - dt-bindings/clock/qcom,lpass-sc7280.h + See also:: include/dt-bindings/clock/qcom,lpass-sc7280.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscorecc.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscorecc.yaml index f50e284e5f46..447cdc447a0c 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscorecc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscorecc.yaml @@ -4,18 +4,18 @@ $id: http://devicetree.org/schemas/clock/qcom,sc7280-lpasscorecc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm LPASS Core & Audio Clock Controller Binding for SC7280 +title: Qualcomm LPASS Core & Audio Clock Controller on SC7280 maintainers: - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm LPASS core and audio clock control module which supports the - clocks and power domains on SC7280. + Qualcomm LPASS core and audio clock control module provides the clocks and + power domains on SC7280. - See also: - - dt-bindings/clock/qcom,lpasscorecc-sc7280.h - - dt-bindings/clock/qcom,lpassaudiocc-sc7280.h + See also:: + include/dt-bindings/clock/qcom,lpasscorecc-sc7280.h + include/dt-bindings/clock/qcom,lpassaudiocc-sc7280.h properties: clocks: true diff --git a/Documentation/devicetree/bindings/clock/qcom,sdm845-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sdm845-camcc.yaml index d4239ccae917..91d1f7918037 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sdm845-camcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sdm845-camcc.yaml @@ -4,16 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,sdm845-camcc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Camera Clock & Reset Controller Binding for SDM845 +title: Qualcomm Camera Clock & Reset Controller on SDM845 maintainers: - Bjorn Andersson <bjorn.andersson@linaro.org> description: | - Qualcomm camera clock control module which supports the clocks, resets and - power domains on SDM845. + Qualcomm camera clock control module provides the clocks, resets and power + domains on SDM845. - See also dt-bindings/clock/qcom,camcc-sm845.h + See also:: include/dt-bindings/clock/qcom,camcc-sm845.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,sdm845-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sdm845-dispcc.yaml index 4a3be733d042..76b53ce64e40 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sdm845-dispcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sdm845-dispcc.yaml @@ -4,16 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,sdm845-dispcc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Display Clock & Reset Controller Binding for SDM845 +title: Qualcomm Display Clock & Reset Controller on SDM845 maintainers: - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm display clock control module which supports the clocks, resets and - power domains on SDM845. + Qualcomm display clock control module provides the clocks, resets and power + domains on SDM845. - See also dt-bindings/clock/qcom,dispcc-sdm845.h. + See also:: include/dt-bindings/clock/qcom,dispcc-sdm845.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,sdm845-lpasscc.yaml b/Documentation/devicetree/bindings/clock/qcom,sdm845-lpasscc.yaml new file mode 100644 index 000000000000..a96fd837c70a --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sdm845-lpasscc.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sdm845-lpasscc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SDM845 LPASS Clock Controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + +description: | + Qualcomm SDM845 LPASS (Low Power Audio SubSystem) Clock Controller. + + See also:: include/dt-bindings/clock/qcom,lpass-sdm845.h + +properties: + compatible: + const: qcom,sdm845-lpasscc + + '#clock-cells': + const: 1 + + reg: + maxItems: 2 + + reg-names: + items: + - const: cc + - const: qdsp6ss + +required: + - compatible + - '#clock-cells' + - reg + - reg-names + +additionalProperties: false + +examples: + - | + clock-controller@17014000 { + compatible = "qcom,sdm845-lpasscc"; + reg = <0x17014000 0x1f004>, <0x17300000 0x200>; + reg-names = "cc", "qdsp6ss"; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,sm6115-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm6115-dispcc.yaml index 6660ff16ad1b..f802a2e7f818 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm6115-dispcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm6115-dispcc.yaml @@ -10,11 +10,10 @@ maintainers: - Bjorn Andersson <andersson@kernel.org> description: | - Qualcomm display clock control module which supports the clocks and - power domains on SM6115. + Qualcomm display clock control module provides the clocks and power domains + on SM6115. - See also: - include/dt-bindings/clock/qcom,sm6115-dispcc.h + See also:: include/dt-bindings/clock/qcom,sm6115-dispcc.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,sm6375-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm6375-dispcc.yaml new file mode 100644 index 000000000000..183b1c75dbdf --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sm6375-dispcc.yaml @@ -0,0 +1,54 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sm6375-dispcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display Clock & Reset Controller on SM6375 + +maintainers: + - Konrad Dybcio <konrad.dybcio@linaro.org> + +description: | + Qualcomm display clock control module provides the clocks, resets and power + domains on SM6375. + + See also:: include/dt-bindings/clock/qcom,dispcc-sm6375.h + +allOf: + - $ref: qcom,gcc.yaml# + +properties: + compatible: + const: qcom,sm6375-dispcc + + clocks: + items: + - description: Board XO source + - description: GPLL0 source from GCC + - description: Byte clock from DSI PHY + - description: Pixel clock from DSI PHY + +required: + - compatible + - clocks + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,sm6375-gcc.h> + #include <dt-bindings/clock/qcom,rpmh.h> + + clock-controller@5f00000 { + compatible = "qcom,sm6375-dispcc"; + reg = <0x05f00000 0x20000>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&gcc GCC_DISP_GPLL0_CLK_SRC>, + <&dsi_phy 0>, + <&dsi_phy 1>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,sm6375-gcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm6375-gcc.yaml index 3c573e1a1257..295d4bb1a966 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm6375-gcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm6375-gcc.yaml @@ -4,17 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,sm6375-gcc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Global Clock & Reset Controller Binding for SM6375 +title: Qualcomm Global Clock & Reset Controller on SM6375 maintainers: - Konrad Dybcio <konrad.dybcio@somainline.org> description: | - Qualcomm global clock control module which supports the clocks, resets and - power domains on SM6375 + Qualcomm global clock control module provides the clocks, resets and power + domains on SM6375 - See also: - - dt-bindings/clock/qcom,sm6375-gcc.h + See also:: include/dt-bindings/clock/qcom,sm6375-gcc.h allOf: - $ref: qcom,gcc.yaml# diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml index 268f4c6ae0ee..a52a83fe2831 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml @@ -4,16 +4,16 @@ $id: http://devicetree.org/schemas/clock/qcom,sm8450-camcc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Camera Clock & Reset Controller Binding for SM8450 +title: Qualcomm Camera Clock & Reset Controller on SM8450 maintainers: - Vladimir Zapolskiy <vladimir.zapolskiy@linaro.org> description: | - Qualcomm camera clock control module which supports the clocks, resets and - power domains on SM8450. + Qualcomm camera clock control module provides the clocks, resets and power + domains on SM8450. - See also include/dt-bindings/clock/qcom,sm8450-camcc.h + See also:: include/dt-bindings/clock/qcom,sm8450-camcc.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8450-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8450-dispcc.yaml index 1cc2457f8208..1dd1f696dcd3 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm8450-dispcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm8450-dispcc.yaml @@ -10,11 +10,10 @@ maintainers: - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> description: | - Qualcomm display clock control module which supports the clocks, resets and - power domains on SM8450. + Qualcomm display clock control module provides the clocks, resets and power + domains on SM8450. - See also: - include/dt-bindings/clock/qcom,sm8450-dispcc.h + See also:: include/dt-bindings/clock/qcom,sm8450-dispcc.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8550-gcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8550-gcc.yaml new file mode 100644 index 000000000000..0c706de31cf1 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sm8550-gcc.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sm8550-gcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller on SM8550 + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + +description: | + Qualcomm global clock control module provides the clocks, resets and power + domains on SM8550 + + See also:: include/dt-bindings/clock/qcom,sm8550-gcc.h + +properties: + compatible: + const: qcom,sm8550-gcc + + clocks: + items: + - description: Board XO source + - description: Sleep clock source + - description: PCIE 0 Pipe clock source + - description: PCIE 1 Pipe clock source + - description: PCIE 1 Phy Auxiliary clock source + - description: UFS Phy Rx symbol 0 clock source + - description: UFS Phy Rx symbol 1 clock source + - description: UFS Phy Tx symbol 0 clock source + - description: USB3 Phy wrapper pipe clock source + +required: + - compatible + - clocks + +allOf: + - $ref: qcom,gcc.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@100000 { + compatible = "qcom,sm8550-gcc"; + reg = <0x00100000 0x001f4200>; + clocks = <&rpmhcc RPMH_CXO_CLK>, <&sleep_clk>, + <&pcie0_phy>, + <&pcie1_phy>, + <&pcie_1_phy_aux_clk>, + <&ufs_mem_phy 0>, + <&ufs_mem_phy 1>, + <&ufs_mem_phy 2>, + <&usb_1_qmpphy>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/qcom,videocc.yaml b/Documentation/devicetree/bindings/clock/qcom,videocc.yaml index 3cdbcebdc1a1..e221985e743f 100644 --- a/Documentation/devicetree/bindings/clock/qcom,videocc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,videocc.yaml @@ -4,21 +4,21 @@ $id: http://devicetree.org/schemas/clock/qcom,videocc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Video Clock & Reset Controller Binding +title: Qualcomm Video Clock & Reset Controller maintainers: - Taniya Das <tdas@codeaurora.org> description: | - Qualcomm video clock control module which supports the clocks, resets and - power domains on Qualcomm SoCs. - - See also: - dt-bindings/clock/qcom,videocc-sc7180.h - dt-bindings/clock/qcom,videocc-sc7280.h - dt-bindings/clock/qcom,videocc-sdm845.h - dt-bindings/clock/qcom,videocc-sm8150.h - dt-bindings/clock/qcom,videocc-sm8250.h + Qualcomm video clock control module provides the clocks, resets and power + domains on Qualcomm SoCs. + + See also:: + include/dt-bindings/clock/qcom,videocc-sc7180.h + include/dt-bindings/clock/qcom,videocc-sc7280.h + include/dt-bindings/clock/qcom,videocc-sdm845.h + include/dt-bindings/clock/qcom,videocc-sm8150.h + include/dt-bindings/clock/qcom,videocc-sm8250.h properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/rockchip,rk3588-cru.yaml b/Documentation/devicetree/bindings/clock/rockchip,rk3588-cru.yaml new file mode 100644 index 000000000000..74cd3f3f229a --- /dev/null +++ b/Documentation/devicetree/bindings/clock/rockchip,rk3588-cru.yaml @@ -0,0 +1,71 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/rockchip,rk3588-cru.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip rk3588 Family Clock and Reset Control Module + +maintainers: + - Elaine Zhang <zhangqing@rock-chips.com> + - Heiko Stuebner <heiko@sntech.de> + +description: | + The RK3588 clock controller generates the clock and also implements a reset + controller for SoC peripherals. For example it provides SCLK_UART2 and + PCLK_UART2, as well as SRST_P_UART2 and SRST_S_UART2 for the second UART + module. + Each clock is assigned an identifier and client nodes can use this identifier + to specify the clock which they consume. All available clock and reset IDs + are defined as preprocessor macros in dt-binding headers. + +properties: + compatible: + enum: + - rockchip,rk3588-cru + + reg: + maxItems: 1 + + "#clock-cells": + const: 1 + + "#reset-cells": + const: 1 + + clocks: + minItems: 2 + maxItems: 2 + + clock-names: + items: + - const: xin24m + - const: xin32k + + assigned-clocks: true + + assigned-clock-rates: true + + rockchip,grf: + $ref: /schemas/types.yaml#/definitions/phandle + description: > + phandle to the syscon managing the "general register files". It is used + for GRF muxes, if missing any muxes present in the GRF will not be + available. + +required: + - compatible + - reg + - "#clock-cells" + - "#reset-cells" + +additionalProperties: false + +examples: + - | + cru: clock-controller@fd7c0000 { + compatible = "rockchip,rk3588-cru"; + reg = <0xfd7c0000 0x5c000>; + #clock-cells = <1>; + #reset-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/samsung,exynosautov9-clock.yaml b/Documentation/devicetree/bindings/clock/samsung,exynosautov9-clock.yaml index 2ab4642679c0..55c4f94a14d1 100644 --- a/Documentation/devicetree/bindings/clock/samsung,exynosautov9-clock.yaml +++ b/Documentation/devicetree/bindings/clock/samsung,exynosautov9-clock.yaml @@ -148,7 +148,7 @@ allOf: items: - const: oscclk - const: dout_clkcmu_fsys1_bus - - const: dout_clkcmu_fsys1_mmc_card + - const: gout_clkcmu_fsys1_mmc_card - const: dout_clkcmu_fsys1_usbdrd - if: diff --git a/Documentation/devicetree/bindings/clock/ti,cdce925.txt b/Documentation/devicetree/bindings/clock/ti,cdce925.txt deleted file mode 100644 index df42ab72718f..000000000000 --- a/Documentation/devicetree/bindings/clock/ti,cdce925.txt +++ /dev/null @@ -1,53 +0,0 @@ -Binding for TI CDCE913/925/937/949 programmable I2C clock synthesizers. - -Reference -This binding uses the common clock binding[1]. - -[1] Documentation/devicetree/bindings/clock/clock-bindings.txt -[2] https://www.ti.com/product/cdce913 -[3] https://www.ti.com/product/cdce925 -[4] https://www.ti.com/product/cdce937 -[5] https://www.ti.com/product/cdce949 - -The driver provides clock sources for each output Y1 through Y5. - -Required properties: - - compatible: Shall be one of the following: - - "ti,cdce913": 1-PLL, 3 Outputs - - "ti,cdce925": 2-PLL, 5 Outputs - - "ti,cdce937": 3-PLL, 7 Outputs - - "ti,cdce949": 4-PLL, 9 Outputs - - reg: I2C device address. - - clocks: Points to a fixed parent clock that provides the input frequency. - - #clock-cells: From common clock bindings: Shall be 1. - -Optional properties: - - xtal-load-pf: Crystal load-capacitor value to fine-tune performance on a - board, or to compensate for external influences. -- vdd-supply: A regulator node for Vdd -- vddout-supply: A regulator node for Vddout - -For all PLL1, PLL2, ... an optional child node can be used to specify spread -spectrum clocking parameters for a board. - - spread-spectrum: SSC mode as defined in the data sheet. - - spread-spectrum-center: Use "centered" mode instead of "max" mode. When - present, the clock runs at the requested frequency on average. Otherwise - the requested frequency is the maximum value of the SCC range. - - -Example: - - clockgen: cdce925pw@64 { - compatible = "cdce925"; - reg = <0x64>; - clocks = <&xtal_27Mhz>; - #clock-cells = <1>; - xtal-load-pf = <5>; - vdd-supply = <&1v8-reg>; - vddout-supply = <&3v3-reg>; - /* PLL options to get SSC 1% centered */ - PLL2 { - spread-spectrum = <4>; - spread-spectrum-center; - }; - }; diff --git a/Documentation/devicetree/bindings/clock/ti,cdce925.yaml b/Documentation/devicetree/bindings/clock/ti,cdce925.yaml new file mode 100644 index 000000000000..a4ec8dd5ddf1 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/ti,cdce925.yaml @@ -0,0 +1,103 @@ +# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/ti,cdce925.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI CDCE913/925/937/949 programmable I2C clock synthesizers + +maintainers: + - Alexander Stein <alexander.stein@ew.tq-group.com> + +description: | + Flexible Low Power LVCMOS Clock Generator with SSC Support for EMI Reduction + + - CDCE(L)913: 1-PLL, 3 Outputs https://www.ti.com/product/cdce913 + - CDCE(L)925: 2-PLL, 5 Outputs https://www.ti.com/product/cdce925 + - CDCE(L)937: 3-PLL, 7 Outputs https://www.ti.com/product/cdce937 + - CDCE(L)949: 4-PLL, 9 Outputs https://www.ti.com/product/cdce949 + +properties: + compatible: + enum: + - ti,cdce913 + - ti,cdce925 + - ti,cdce937 + - ti,cdce949 + + reg: + maxItems: 1 + + clocks: + items: + - description: fixed parent clock + + "#clock-cells": + const: 1 + + vdd-supply: + description: Regulator that provides 1.8V Vdd power supply + + vddout-supply: + description: | + Regulator that provides Vddout power supply. + non-L variant: 2.5V or 3.3V for + L variant: 1.8V for + + xtal-load-pf: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Crystal load-capacitor value to fine-tune performance on a + board, or to compensate for external influences. + +patternProperties: + "^PLL[1-4]$": + type: object + description: | + optional child node can be used to specify spread + spectrum clocking parameters for a board + + additionalProperties: false + + properties: + spread-spectrum: + $ref: /schemas/types.yaml#/definitions/uint32 + description: SSC mode as defined in the data sheet + + spread-spectrum-center: + type: boolean + description: | + Use "centered" mode instead of "max" mode. When + present, the clock runs at the requested frequency on average. + Otherwise the requested frequency is the maximum value of the + SCC range. + +required: + - compatible + - reg + - clocks + - "#clock-cells" + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + cdce925: clock-controller@64 { + compatible = "ti,cdce925"; + reg = <0x64>; + clocks = <&xtal_27Mhz>; + #clock-cells = <1>; + xtal-load-pf = <5>; + vdd-supply = <®_1v8>; + vddout-supply = <®_3v3>; + /* PLL options to get SSC 1% centered */ + PLL2 { + spread-spectrum = <4>; + spread-spectrum-center; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/cpufreq/apple,cluster-cpufreq.yaml b/Documentation/devicetree/bindings/cpufreq/apple,cluster-cpufreq.yaml new file mode 100644 index 000000000000..76cb9726660e --- /dev/null +++ b/Documentation/devicetree/bindings/cpufreq/apple,cluster-cpufreq.yaml @@ -0,0 +1,117 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/cpufreq/apple,cluster-cpufreq.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Apple SoC cluster cpufreq device + +maintainers: + - Hector Martin <marcan@marcan.st> + +description: | + Apple SoCs (e.g. M1) have a per-cpu-cluster DVFS controller that is part of + the cluster management register block. This binding uses the standard + operating-points-v2 table to define the CPU performance states, with the + opp-level property specifying the hardware p-state index for that level. + +properties: + compatible: + oneOf: + - items: + - enum: + - apple,t8103-cluster-cpufreq + - apple,t8112-cluster-cpufreq + - const: apple,cluster-cpufreq + - items: + - const: apple,t6000-cluster-cpufreq + - const: apple,t8103-cluster-cpufreq + - const: apple,cluster-cpufreq + + reg: + maxItems: 1 + + '#performance-domain-cells': + const: 0 + +required: + - compatible + - reg + - '#performance-domain-cells' + +additionalProperties: false + +examples: + - | + // This example shows a single CPU per domain and 2 domains, + // with two p-states per domain. + // Shipping hardware has 2-4 CPUs per domain and 2-6 domains. + cpus { + #address-cells = <2>; + #size-cells = <0>; + + cpu@0 { + compatible = "apple,icestorm"; + device_type = "cpu"; + reg = <0x0 0x0>; + operating-points-v2 = <&ecluster_opp>; + performance-domains = <&cpufreq_e>; + }; + + cpu@10100 { + compatible = "apple,firestorm"; + device_type = "cpu"; + reg = <0x0 0x10100>; + operating-points-v2 = <&pcluster_opp>; + performance-domains = <&cpufreq_p>; + }; + }; + + ecluster_opp: opp-table-0 { + compatible = "operating-points-v2"; + opp-shared; + + opp01 { + opp-hz = /bits/ 64 <600000000>; + opp-level = <1>; + clock-latency-ns = <7500>; + }; + opp02 { + opp-hz = /bits/ 64 <972000000>; + opp-level = <2>; + clock-latency-ns = <22000>; + }; + }; + + pcluster_opp: opp-table-1 { + compatible = "operating-points-v2"; + opp-shared; + + opp01 { + opp-hz = /bits/ 64 <600000000>; + opp-level = <1>; + clock-latency-ns = <8000>; + }; + opp02 { + opp-hz = /bits/ 64 <828000000>; + opp-level = <2>; + clock-latency-ns = <19000>; + }; + }; + + soc { + #address-cells = <2>; + #size-cells = <2>; + + cpufreq_e: performance-controller@210e20000 { + compatible = "apple,t8103-cluster-cpufreq", "apple,cluster-cpufreq"; + reg = <0x2 0x10e20000 0 0x1000>; + #performance-domain-cells = <0>; + }; + + cpufreq_p: performance-controller@211e20000 { + compatible = "apple,t8103-cluster-cpufreq", "apple,cluster-cpufreq"; + reg = <0x2 0x11e20000 0 0x1000>; + #performance-domain-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml b/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml index 24fa3d87a40b..903b31129f01 100644 --- a/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml @@ -25,6 +25,7 @@ properties: - description: v2 of CPUFREQ HW (EPSS) items: - enum: + - qcom,qdu1000-cpufreq-epss - qcom,sm6375-cpufreq-epss - qcom,sm8250-cpufreq-epss - const: qcom,cpufreq-epss @@ -56,6 +57,9 @@ properties: '#freq-domain-cells': const: 1 + '#clock-cells': + const: 1 + required: - compatible - reg @@ -83,11 +87,16 @@ examples: enable-method = "psci"; next-level-cache = <&L2_0>; qcom,freq-domain = <&cpufreq_hw 0>; + clocks = <&cpufreq_hw 0>; L2_0: l2-cache { compatible = "cache"; + cache-unified; + cache-level = <2>; next-level-cache = <&L3_0>; L3_0: l3-cache { compatible = "cache"; + cache-unified; + cache-level = <3>; }; }; }; @@ -99,8 +108,11 @@ examples: enable-method = "psci"; next-level-cache = <&L2_100>; qcom,freq-domain = <&cpufreq_hw 0>; + clocks = <&cpufreq_hw 0>; L2_100: l2-cache { compatible = "cache"; + cache-unified; + cache-level = <2>; next-level-cache = <&L3_0>; }; }; @@ -112,8 +124,11 @@ examples: enable-method = "psci"; next-level-cache = <&L2_200>; qcom,freq-domain = <&cpufreq_hw 0>; + clocks = <&cpufreq_hw 0>; L2_200: l2-cache { compatible = "cache"; + cache-unified; + cache-level = <2>; next-level-cache = <&L3_0>; }; }; @@ -125,8 +140,11 @@ examples: enable-method = "psci"; next-level-cache = <&L2_300>; qcom,freq-domain = <&cpufreq_hw 0>; + clocks = <&cpufreq_hw 0>; L2_300: l2-cache { compatible = "cache"; + cache-unified; + cache-level = <2>; next-level-cache = <&L3_0>; }; }; @@ -138,8 +156,11 @@ examples: enable-method = "psci"; next-level-cache = <&L2_400>; qcom,freq-domain = <&cpufreq_hw 1>; + clocks = <&cpufreq_hw 1>; L2_400: l2-cache { compatible = "cache"; + cache-unified; + cache-level = <2>; next-level-cache = <&L3_0>; }; }; @@ -151,8 +172,11 @@ examples: enable-method = "psci"; next-level-cache = <&L2_500>; qcom,freq-domain = <&cpufreq_hw 1>; + clocks = <&cpufreq_hw 1>; L2_500: l2-cache { compatible = "cache"; + cache-unified; + cache-level = <2>; next-level-cache = <&L3_0>; }; }; @@ -164,8 +188,11 @@ examples: enable-method = "psci"; next-level-cache = <&L2_600>; qcom,freq-domain = <&cpufreq_hw 1>; + clocks = <&cpufreq_hw 1>; L2_600: l2-cache { compatible = "cache"; + cache-unified; + cache-level = <2>; next-level-cache = <&L3_0>; }; }; @@ -177,8 +204,11 @@ examples: enable-method = "psci"; next-level-cache = <&L2_700>; qcom,freq-domain = <&cpufreq_hw 1>; + clocks = <&cpufreq_hw 1>; L2_700: l2-cache { compatible = "cache"; + cache-unified; + cache-level = <2>; next-level-cache = <&L3_0>; }; }; @@ -197,6 +227,7 @@ examples: clock-names = "xo", "alternate"; #freq-domain-cells = <1>; + #clock-cells = <1>; }; }; ... diff --git a/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml b/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml index a11e1b867379..3c00ad09eeaa 100644 --- a/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml +++ b/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml @@ -38,7 +38,7 @@ properties: type: object patternProperties: - 'cpu@[0-9a-f]+': + '^cpu@[0-9a-f]+$': type: object properties: diff --git a/Documentation/devicetree/bindings/crypto/rockchip,rk3288-crypto.yaml b/Documentation/devicetree/bindings/crypto/rockchip,rk3288-crypto.yaml new file mode 100644 index 000000000000..f1a9da8bff7a --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/rockchip,rk3288-crypto.yaml @@ -0,0 +1,127 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/crypto/rockchip,rk3288-crypto.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip Electronics Security Accelerator + +maintainers: + - Heiko Stuebner <heiko@sntech.de> + +properties: + compatible: + enum: + - rockchip,rk3288-crypto + - rockchip,rk3328-crypto + - rockchip,rk3399-crypto + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 3 + maxItems: 4 + + clock-names: + minItems: 3 + maxItems: 4 + + resets: + minItems: 1 + maxItems: 3 + + reset-names: + minItems: 1 + maxItems: 3 + +allOf: + - if: + properties: + compatible: + contains: + const: rockchip,rk3288-crypto + then: + properties: + clocks: + minItems: 4 + clock-names: + items: + - const: aclk + - const: hclk + - const: sclk + - const: apb_pclk + resets: + maxItems: 1 + reset-names: + items: + - const: crypto-rst + - if: + properties: + compatible: + contains: + const: rockchip,rk3328-crypto + then: + properties: + clocks: + maxItems: 3 + clock-names: + items: + - const: hclk_master + - const: hclk_slave + - const: sclk + resets: + maxItems: 1 + reset-names: + items: + - const: crypto-rst + - if: + properties: + compatible: + contains: + const: rockchip,rk3399-crypto + then: + properties: + clocks: + maxItems: 3 + clock-names: + items: + - const: hclk_master + - const: hclk_slave + - const: sclk + resets: + minItems: 3 + reset-names: + items: + - const: master + - const: slave + - const: crypto-rst + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - resets + - reset-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/rk3288-cru.h> + crypto@ff8a0000 { + compatible = "rockchip,rk3288-crypto"; + reg = <0xff8a0000 0x4000>; + interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru ACLK_CRYPTO>, <&cru HCLK_CRYPTO>, + <&cru SCLK_CRYPTO>, <&cru ACLK_DMAC1>; + clock-names = "aclk", "hclk", "sclk", "apb_pclk"; + resets = <&cru SRST_CRYPTO>; + reset-names = "crypto-rst"; + }; diff --git a/Documentation/devicetree/bindings/crypto/rockchip-crypto.txt b/Documentation/devicetree/bindings/crypto/rockchip-crypto.txt deleted file mode 100644 index 5e2ba385b8c9..000000000000 --- a/Documentation/devicetree/bindings/crypto/rockchip-crypto.txt +++ /dev/null @@ -1,28 +0,0 @@ -Rockchip Electronics And Security Accelerator - -Required properties: -- compatible: Should be "rockchip,rk3288-crypto" -- reg: Base physical address of the engine and length of memory mapped - region -- interrupts: Interrupt number -- clocks: Reference to the clocks about crypto -- clock-names: "aclk" used to clock data - "hclk" used to clock data - "sclk" used to clock crypto accelerator - "apb_pclk" used to clock dma -- resets: Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names: Must include the name "crypto-rst". - -Examples: - - crypto: cypto-controller@ff8a0000 { - compatible = "rockchip,rk3288-crypto"; - reg = <0xff8a0000 0x4000>; - interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cru ACLK_CRYPTO>, <&cru HCLK_CRYPTO>, - <&cru SCLK_CRYPTO>, <&cru ACLK_DMAC1>; - clock-names = "aclk", "hclk", "sclk", "apb_pclk"; - resets = <&cru SRST_CRYPTO>; - reset-names = "crypto-rst"; - }; diff --git a/Documentation/devicetree/bindings/crypto/st,stm32-cryp.yaml b/Documentation/devicetree/bindings/crypto/st,stm32-cryp.yaml index ed23bf94a8e0..6759c5bf3e57 100644 --- a/Documentation/devicetree/bindings/crypto/st,stm32-cryp.yaml +++ b/Documentation/devicetree/bindings/crypto/st,stm32-cryp.yaml @@ -6,12 +6,18 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: STMicroelectronics STM32 CRYP bindings +description: The STM32 CRYP block is built on the CRYP 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-cryp + - stericsson,ux500-cryp - st,stm32f756-cryp - st,stm32mp1-cryp @@ -27,6 +33,19 @@ properties: resets: maxItems: 1 + dmas: + items: + - description: mem2cryp DMA channel + - description: cryp2mem DMA channel + + dma-names: + items: + - const: mem2cryp + - const: cryp2mem + + power-domains: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-mipi-dsi.yaml b/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-mipi-dsi.yaml index 7910831fa4b8..c731fbdc2fe0 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-mipi-dsi.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-mipi-dsi.yaml @@ -12,9 +12,14 @@ maintainers: properties: compatible: - enum: - - allwinner,sun6i-a31-mipi-dsi - - allwinner,sun50i-a64-mipi-dsi + oneOf: + - enum: + - allwinner,sun6i-a31-mipi-dsi + - allwinner,sun50i-a64-mipi-dsi + - allwinner,sun50i-a100-mipi-dsi + - items: + - const: allwinner,sun20i-d1-mipi-dsi + - const: allwinner,sun50i-a100-mipi-dsi reg: maxItems: 1 @@ -59,7 +64,6 @@ required: - phys - phy-names - resets - - vcc-dsi-supply - port allOf: @@ -68,7 +72,9 @@ allOf: properties: compatible: contains: - const: allwinner,sun6i-a31-mipi-dsi + enum: + - allwinner,sun6i-a31-mipi-dsi + - allwinner,sun50i-a100-mipi-dsi then: properties: @@ -78,16 +84,22 @@ allOf: required: - clock-names + else: + properties: + clocks: + maxItems: 1 + - if: properties: compatible: contains: - const: allwinner,sun50i-a64-mipi-dsi + enum: + - allwinner,sun6i-a31-mipi-dsi + - allwinner,sun50i-a64-mipi-dsi then: - properties: - clocks: - minItems: 1 + required: + - vcc-dsi-supply unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml index 7cdffdb131ac..74cefdf1b843 100644 --- a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml @@ -11,7 +11,7 @@ maintainers: - Neil Armstrong <neil.armstrong@linaro.org> allOf: - - $ref: /schemas/sound/name-prefix.yaml# + - $ref: /schemas/sound/dai-common.yaml# description: | The Amlogic Meson Synopsys Designware Integration is composed of diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,dsi.yaml b/Documentation/devicetree/bindings/display/bridge/renesas,dsi.yaml new file mode 100644 index 000000000000..131d5b63ec4f --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/renesas,dsi.yaml @@ -0,0 +1,182 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/renesas,dsi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/G2L MIPI DSI Encoder + +maintainers: + - Biju Das <biju.das.jz@bp.renesas.com> + +description: | + This binding describes the MIPI DSI encoder embedded in the Renesas + RZ/G2L alike family of SoC's. The encoder can operate in DSI mode, with + up to four data lanes. + +allOf: + - $ref: /schemas/display/dsi-controller.yaml# + +properties: + compatible: + items: + - enum: + - renesas,r9a07g044-mipi-dsi # RZ/G2{L,LC} + - const: renesas,rzg2l-mipi-dsi + + reg: + maxItems: 1 + + interrupts: + items: + - description: Sequence operation channel 0 interrupt + - description: Sequence operation channel 1 interrupt + - description: Video-Input operation channel 1 interrupt + - description: DSI Packet Receive interrupt + - description: DSI Fatal Error interrupt + - description: DSI D-PHY PPI interrupt + - description: Debug interrupt + + interrupt-names: + items: + - const: seq0 + - const: seq1 + - const: vin1 + - const: rcv + - const: ferr + - const: ppi + - const: debug + + clocks: + items: + - description: DSI D-PHY PLL multiplied clock + - description: DSI D-PHY system clock + - description: DSI AXI bus clock + - description: DSI Register access clock + - description: DSI Video clock + - description: DSI D-PHY Escape mode transmit clock + + clock-names: + items: + - const: pllclk + - const: sysclk + - const: aclk + - const: pclk + - const: vclk + - const: lpclk + + resets: + items: + - description: MIPI_DSI_CMN_RSTB + - description: MIPI_DSI_ARESET_N + - description: MIPI_DSI_PRESET_N + + reset-names: + items: + - const: rst + - const: arst + - const: prst + + power-domains: + maxItems: 1 + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: Parallel input port + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: DSI output port + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: + description: array of physical DSI data lane indexes. + minItems: 1 + items: + - const: 1 + - const: 2 + - const: 3 + - const: 4 + + required: + - data-lanes + + required: + - port@0 + - port@1 + +required: + - compatible + - reg + - interrupts + - interrupt-names + - clocks + - clock-names + - resets + - reset-names + - power-domains + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r9a07g044-cpg.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + dsi0: dsi@10850000 { + compatible = "renesas,r9a07g044-mipi-dsi", "renesas,rzg2l-mipi-dsi"; + reg = <0x10850000 0x20000>; + interrupts = <GIC_SPI 142 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 143 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 144 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 145 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 146 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 147 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 148 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "seq0", "seq1", "vin1", "rcv", + "ferr", "ppi", "debug"; + clocks = <&cpg CPG_MOD R9A07G044_MIPI_DSI_PLLCLK>, + <&cpg CPG_MOD R9A07G044_MIPI_DSI_SYSCLK>, + <&cpg CPG_MOD R9A07G044_MIPI_DSI_ACLK>, + <&cpg CPG_MOD R9A07G044_MIPI_DSI_PCLK>, + <&cpg CPG_MOD R9A07G044_MIPI_DSI_VCLK>, + <&cpg CPG_MOD R9A07G044_MIPI_DSI_LPCLK>; + clock-names = "pllclk", "sysclk", "aclk", "pclk", "vclk", "lpclk"; + resets = <&cpg R9A07G044_MIPI_DSI_CMN_RSTB>, + <&cpg R9A07G044_MIPI_DSI_ARESET_N>, + <&cpg R9A07G044_MIPI_DSI_PRESET_N>; + reset-names = "rst", "arst", "prst"; + power-domains = <&cpg>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dsi0_in: endpoint { + remote-endpoint = <&du_out_dsi0>; + }; + }; + + port@1 { + reg = <1>; + dsi0_out: endpoint { + data-lanes = <1 2 3 4>; + remote-endpoint = <&adv7535_in>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/fsl,lcdif.yaml b/Documentation/devicetree/bindings/display/fsl,lcdif.yaml index 876015a44a1e..f449cfc76789 100644 --- a/Documentation/devicetree/bindings/display/fsl,lcdif.yaml +++ b/Documentation/devicetree/bindings/display/fsl,lcdif.yaml @@ -52,6 +52,9 @@ properties: interrupts: maxItems: 1 + power-domains: + maxItems: 1 + port: $ref: /schemas/graph.yaml#/properties/port description: The LCDIF output port @@ -81,7 +84,31 @@ allOf: maxItems: 3 required: - clock-names - else: + - if: + properties: + compatible: + contains: + const: fsl,imx8mp-lcdif + then: + properties: + clocks: + minItems: 3 + maxItems: 3 + clock-names: + minItems: 3 + maxItems: 3 + required: + - clock-names + - power-domains + - if: + not: + properties: + compatible: + contains: + enum: + - fsl,imx6sx-lcdif + - fsl,imx8mp-lcdif + then: properties: clocks: maxItems: 1 diff --git a/Documentation/devicetree/bindings/display/imx/fsl,imx-fb.txt b/Documentation/devicetree/bindings/display/imx/fsl,imx-fb.txt deleted file mode 100644 index f4df9e83bcd2..000000000000 --- a/Documentation/devicetree/bindings/display/imx/fsl,imx-fb.txt +++ /dev/null @@ -1,57 +0,0 @@ -Freescale imx21 Framebuffer - -This framebuffer driver supports devices imx1, imx21, imx25, and imx27. - -Required properties: -- compatible : "fsl,<chip>-fb", chip should be imx1 or imx21 -- reg : Should contain 1 register ranges(address and length) -- interrupts : One interrupt of the fb dev - -Required nodes: -- display: Phandle to a display node as described in - Documentation/devicetree/bindings/display/panel/display-timing.txt - Additional, the display node has to define properties: - - bits-per-pixel: Bits per pixel - - fsl,pcr: LCDC PCR value - A display node may optionally define - - fsl,aus-mode: boolean to enable AUS mode (only for imx21) - -Optional properties: -- lcd-supply: Regulator for LCD supply voltage. -- fsl,dmacr: DMA Control Register value. This is optional. By default, the - register is not modified as recommended by the datasheet. -- fsl,lpccr: Contrast Control Register value. This property provides the - default value for the contrast control register. - If that property is omitted, the register is zeroed. -- fsl,lscr1: LCDC Sharp Configuration Register value. - -Example: - - imxfb: fb@10021000 { - compatible = "fsl,imx21-fb"; - interrupts = <61>; - reg = <0x10021000 0x1000>; - display = <&display0>; - }; - - ... - - display0: display0 { - model = "Primeview-PD050VL1"; - bits-per-pixel = <16>; - fsl,pcr = <0xf0c88080>; /* non-standard but required */ - display-timings { - native-mode = <&timing_disp0>; - timing_disp0: 640x480 { - hactive = <640>; - vactive = <480>; - hback-porch = <112>; - hfront-porch = <36>; - hsync-len = <32>; - vback-porch = <33>; - vfront-porch = <33>; - vsync-len = <2>; - clock-frequency = <25000000>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/display/imx/fsl,imx-lcdc.yaml b/Documentation/devicetree/bindings/display/imx/fsl,imx-lcdc.yaml new file mode 100644 index 000000000000..35a8fff036ca --- /dev/null +++ b/Documentation/devicetree/bindings/display/imx/fsl,imx-lcdc.yaml @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/imx/fsl,imx-lcdc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale i.MX LCD Controller, found on i.MX1, i.MX21, i.MX25 and i.MX27 + +maintainers: + - Sascha Hauer <s.hauer@pengutronix.de> + - Pengutronix Kernel Team <kernel@pengutronix.de> + +properties: + compatible: + oneOf: + - enum: + - fsl,imx1-fb + - fsl,imx21-fb + - items: + - enum: + - fsl,imx25-fb + - fsl,imx27-fb + - const: fsl,imx21-fb + + clocks: + maxItems: 3 + + clock-names: + items: + - const: ipg + - const: ahb + - const: per + + display: + $ref: /schemas/types.yaml#/definitions/phandle + + interrupts: + maxItems: 1 + + reg: + maxItems: 1 + + lcd-supply: + description: + Regulator for LCD supply voltage. + + fsl,dmacr: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Override value for DMA Control Register + + fsl,lpccr: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Contrast Control Register value. + + fsl,lscr1: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + LCDC Sharp Configuration Register value. + +required: + - compatible + - clocks + - clock-names + - display + - interrupts + - reg + +additionalProperties: false + +examples: + - | + imxfb: fb@10021000 { + compatible = "fsl,imx21-fb"; + interrupts = <61>; + reg = <0x10021000 0x1000>; + display = <&display0>; + clocks = <&clks 103>, <&clks 49>, <&clks 66>; + clock-names = "ipg", "ahb", "per"; + }; + + display0: display0 { + model = "Primeview-PD050VL1"; + bits-per-pixel = <16>; + fsl,pcr = <0xf0c88080>; /* non-standard but required */ + + display-timings { + native-mode = <&timing_disp0>; + timing_disp0: timing0 { + hactive = <640>; + vactive = <480>; + hback-porch = <112>; + hfront-porch = <36>; + hsync-len = <32>; + vback-porch = <33>; + vfront-porch = <33>; + vsync-len = <2>; + clock-frequency = <25000000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml index 5bb23e97cf33..d976380801e3 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml @@ -23,6 +23,7 @@ properties: - mediatek,mt8173-dpi - mediatek,mt8183-dpi - mediatek,mt8186-dpi + - mediatek,mt8188-dp-intf - mediatek,mt8192-dpi - mediatek,mt8195-dp-intf diff --git a/Documentation/devicetree/bindings/display/msm/dpu-common.yaml b/Documentation/devicetree/bindings/display/msm/dpu-common.yaml new file mode 100644 index 000000000000..8ffbc30c6b7f --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/dpu-common.yaml @@ -0,0 +1,52 @@ +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/dpu-common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display DPU common properties + +maintainers: + - Krishna Manikandan <quic_mkrishn@quicinc.com> + - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> + - Rob Clark <robdclark@gmail.com> + +description: | + Common properties for QCom DPU display controller. + +properties: + interrupts: + maxItems: 1 + + 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. + + patternProperties: + "^port@[0-9a-f]+$": + $ref: /schemas/graph.yaml#/properties/port + + # at least one port is required + required: + - port@0 + +required: + - compatible + - reg + - reg-names + - clocks + - interrupts + - power-domains + - operating-points-v2 + - ports + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/display/msm/dpu-msm8998.yaml b/Documentation/devicetree/bindings/display/msm/dpu-msm8998.yaml deleted file mode 100644 index 253665c693e6..000000000000 --- a/Documentation/devicetree/bindings/display/msm/dpu-msm8998.yaml +++ /dev/null @@ -1,223 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/display/msm/dpu-msm8998.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Qualcomm Display DPU dt properties for MSM8998 target - -maintainers: - - AngeloGioacchino Del Regno <angelogioacchino.delregno@somainline.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 and DPU are mentioned for MSM8998 target. - -properties: - compatible: - items: - - const: qcom,msm8998-mdss - - reg: - maxItems: 1 - - reg-names: - const: mdss - - power-domains: - maxItems: 1 - - clocks: - items: - - description: Display AHB clock - - description: Display AXI clock - - description: Display core clock - - clock-names: - items: - - const: iface - - const: bus - - const: core - - interrupts: - maxItems: 1 - - interrupt-controller: true - - "#address-cells": true - - "#size-cells": true - - "#interrupt-cells": - const: 1 - - iommus: - items: - - description: Phandle to apps_smmu node with SID mask for Hard-Fail port0 - - ranges: true - -patternProperties: - "^display-controller@[0-9a-f]+$": - type: object - description: Node containing the properties of DPU. - additionalProperties: false - - properties: - compatible: - items: - - const: qcom,msm8998-dpu - - reg: - items: - - description: Address offset and size for mdp register set - - description: Address offset and size for regdma register set - - description: Address offset and size for vbif register set - - description: Address offset and size for non-realtime vbif register set - - reg-names: - items: - - const: mdp - - const: regdma - - const: vbif - - const: vbif_nrt - - clocks: - items: - - description: Display ahb clock - - description: Display axi clock - - description: Display mem-noc clock - - description: Display core clock - - description: Display vsync clock - - clock-names: - items: - - const: iface - - const: bus - - const: mnoc - - const: core - - const: vsync - - interrupts: - maxItems: 1 - - 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. Each output port contains an endpoint that - describes how it is connected to an external interface. - - properties: - port@0: - $ref: /schemas/graph.yaml#/properties/port - description: DPU_INTF1 (DSI1) - - port@1: - $ref: /schemas/graph.yaml#/properties/port - description: DPU_INTF2 (DSI2) - - required: - - port@0 - - port@1 - - required: - - compatible - - reg - - reg-names - - clocks - - interrupts - - power-domains - - operating-points-v2 - - ports - -required: - - compatible - - reg - - reg-names - - power-domains - - clocks - - interrupts - - interrupt-controller - - iommus - - ranges - -additionalProperties: false - -examples: - - | - #include <dt-bindings/clock/qcom,mmcc-msm8998.h> - #include <dt-bindings/interrupt-controller/arm-gic.h> - #include <dt-bindings/power/qcom-rpmpd.h> - - mdss: display-subsystem@c900000 { - compatible = "qcom,msm8998-mdss"; - reg = <0x0c900000 0x1000>; - reg-names = "mdss"; - - clocks = <&mmcc MDSS_AHB_CLK>, - <&mmcc MDSS_AXI_CLK>, - <&mmcc MDSS_MDP_CLK>; - clock-names = "iface", "bus", "core"; - - #address-cells = <1>; - #interrupt-cells = <1>; - #size-cells = <1>; - - interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; - interrupt-controller; - iommus = <&mmss_smmu 0>; - - power-domains = <&mmcc MDSS_GDSC>; - ranges; - - display-controller@c901000 { - compatible = "qcom,msm8998-dpu"; - reg = <0x0c901000 0x8f000>, - <0x0c9a8e00 0xf0>, - <0x0c9b0000 0x2008>, - <0x0c9b8000 0x1040>; - reg-names = "mdp", "regdma", "vbif", "vbif_nrt"; - - clocks = <&mmcc MDSS_AHB_CLK>, - <&mmcc MDSS_AXI_CLK>, - <&mmcc MNOC_AHB_CLK>, - <&mmcc MDSS_MDP_CLK>, - <&mmcc MDSS_VSYNC_CLK>; - clock-names = "iface", "bus", "mnoc", "core", "vsync"; - - interrupt-parent = <&mdss>; - interrupts = <0>; - operating-points-v2 = <&mdp_opp_table>; - power-domains = <&rpmpd MSM8998_VDDMX>; - - 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>; - }; - }; - }; - }; - }; -... diff --git a/Documentation/devicetree/bindings/display/msm/dpu-qcm2290.yaml b/Documentation/devicetree/bindings/display/msm/dpu-qcm2290.yaml deleted file mode 100644 index c5824e1d2382..000000000000 --- a/Documentation/devicetree/bindings/display/msm/dpu-qcm2290.yaml +++ /dev/null @@ -1,222 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/display/msm/dpu-qcm2290.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Qualcomm Display DPU dt properties for QCM2290 target - -maintainers: - - Loic Poulain <loic.poulain@linaro.org> - -description: | - Device tree bindings for MSM Mobile Display Subsystem(MDSS) that encapsulates - sub-blocks like DPU display controller and DSI. Device tree bindings of MDSS - and DPU are mentioned for QCM2290 target. - -properties: - compatible: - items: - - const: qcom,qcm2290-mdss - - reg: - maxItems: 1 - - reg-names: - const: mdss - - power-domains: - maxItems: 1 - - clocks: - items: - - description: Display AHB clock from gcc - - description: Display AXI clock - - description: Display core clock - - clock-names: - items: - - const: iface - - const: bus - - const: core - - interrupts: - maxItems: 1 - - interrupt-controller: true - - "#address-cells": true - - "#size-cells": true - - "#interrupt-cells": - const: 1 - - iommus: - items: - - description: Phandle to apps_smmu node with SID mask for Hard-Fail port0 - - description: Phandle to apps_smmu node with SID mask for Hard-Fail port1 - - ranges: true - - interconnects: - items: - - description: Interconnect path specifying the port ids for data bus - - interconnect-names: - const: mdp0-mem - - resets: - items: - - description: MDSS_CORE reset - -patternProperties: - "^display-controller@[0-9a-f]+$": - type: object - description: Node containing the properties of DPU. - additionalProperties: false - - properties: - compatible: - items: - - const: qcom,qcm2290-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 AXI clock from gcc - - description: Display AHB clock from dispcc - - description: Display core clock from dispcc - - description: Display lut clock from dispcc - - description: Display vsync clock from dispcc - - clock-names: - items: - - const: bus - - const: iface - - const: core - - const: lut - - const: vsync - - interrupts: - maxItems: 1 - - 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. Each output port contains an endpoint that - describes how it is connected to an external interface. - - properties: - port@0: - $ref: /schemas/graph.yaml#/properties/port - description: DPU_INTF1 (DSI1) - - required: - - port@0 - - required: - - compatible - - reg - - reg-names - - clocks - - interrupts - - power-domains - - operating-points-v2 - - ports - -required: - - compatible - - reg - - reg-names - - power-domains - - clocks - - interrupts - - interrupt-controller - - iommus - - ranges - -additionalProperties: false - -examples: - - | - #include <dt-bindings/clock/qcom,dispcc-qcm2290.h> - #include <dt-bindings/clock/qcom,gcc-qcm2290.h> - #include <dt-bindings/interrupt-controller/arm-gic.h> - #include <dt-bindings/interconnect/qcom,qcm2290.h> - #include <dt-bindings/power/qcom-rpmpd.h> - - mdss: mdss@5e00000 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "qcom,qcm2290-mdss"; - reg = <0x05e00000 0x1000>; - reg-names = "mdss"; - power-domains = <&dispcc MDSS_GDSC>; - clocks = <&gcc GCC_DISP_AHB_CLK>, - <&gcc GCC_DISP_HF_AXI_CLK>, - <&dispcc DISP_CC_MDSS_MDP_CLK>; - clock-names = "iface", "bus", "core"; - - interrupts = <GIC_SPI 186 IRQ_TYPE_LEVEL_HIGH>; - interrupt-controller; - #interrupt-cells = <1>; - - interconnects = <&mmrt_virt MASTER_MDP0 &bimc SLAVE_EBI1>; - interconnect-names = "mdp0-mem"; - - iommus = <&apps_smmu 0x420 0x2>, - <&apps_smmu 0x421 0x0>; - ranges; - - mdss_mdp: display-controller@5e01000 { - compatible = "qcom,qcm2290-dpu"; - reg = <0x05e01000 0x8f000>, - <0x05eb0000 0x2008>; - reg-names = "mdp", "vbif"; - - clocks = <&gcc GCC_DISP_HF_AXI_CLK>, - <&dispcc DISP_CC_MDSS_AHB_CLK>, - <&dispcc DISP_CC_MDSS_MDP_CLK>, - <&dispcc DISP_CC_MDSS_MDP_LUT_CLK>, - <&dispcc DISP_CC_MDSS_VSYNC_CLK>; - clock-names = "bus", "iface", "core", "lut", "vsync"; - - operating-points-v2 = <&mdp_opp_table>; - power-domains = <&rpmpd QCM2290_VDDCX>; - - interrupt-parent = <&mdss>; - interrupts = <0>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - dpu_intf1_out: endpoint { - remote-endpoint = <&dsi0_in>; - }; - }; - }; - }; - }; -... diff --git a/Documentation/devicetree/bindings/display/msm/dpu-sc7180.yaml b/Documentation/devicetree/bindings/display/msm/dpu-sc7180.yaml deleted file mode 100644 index 4890bc25f3fd..000000000000 --- a/Documentation/devicetree/bindings/display/msm/dpu-sc7180.yaml +++ /dev/null @@ -1,235 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/display/msm/dpu-sc7180.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Qualcomm Display DPU dt properties for SC7180 target - -maintainers: - - Krishna Manikandan <quic_mkrishn@quicinc.com> - -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 and DPU are mentioned for SC7180 target. - -properties: - compatible: - items: - - const: qcom,sc7180-mdss - - reg: - maxItems: 1 - - reg-names: - const: mdss - - power-domains: - maxItems: 1 - - 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 - - interrupts: - maxItems: 1 - - interrupt-controller: true - - "#address-cells": true - - "#size-cells": true - - "#interrupt-cells": - const: 1 - - iommus: - items: - - description: Phandle to apps_smmu node with SID mask for Hard-Fail port0 - - ranges: true - - interconnects: - items: - - description: Interconnect path specifying the port ids for data bus - - interconnect-names: - const: mdp0-mem - - resets: - items: - - description: MDSS_CORE reset - -patternProperties: - "^display-controller@[0-9a-f]+$": - type: object - description: Node containing the properties of DPU. - additionalProperties: false - - properties: - compatible: - items: - - const: qcom,sc7180-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 ahb clock - - description: Display rotator clock - - description: Display lut clock - - description: Display core clock - - description: Display vsync clock - - clock-names: - items: - - const: bus - - const: iface - - const: rot - - const: lut - - const: core - - const: vsync - - interrupts: - maxItems: 1 - - 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. Each output port contains an endpoint that - describes how it is connected to an external interface. - - properties: - port@0: - $ref: /schemas/graph.yaml#/properties/port - description: DPU_INTF1 (DSI1) - - port@2: - $ref: /schemas/graph.yaml#/properties/port - description: DPU_INTF0 (DP) - - required: - - port@0 - - required: - - compatible - - reg - - reg-names - - clocks - - interrupts - - power-domains - - operating-points-v2 - - ports - -required: - - compatible - - reg - - reg-names - - power-domains - - clocks - - interrupts - - interrupt-controller - - iommus - - ranges - -additionalProperties: false - -examples: - - | - #include <dt-bindings/clock/qcom,dispcc-sc7180.h> - #include <dt-bindings/clock/qcom,gcc-sc7180.h> - #include <dt-bindings/interrupt-controller/arm-gic.h> - #include <dt-bindings/interconnect/qcom,sdm845.h> - #include <dt-bindings/power/qcom-rpmpd.h> - - display-subsystem@ae00000 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "qcom,sc7180-mdss"; - reg = <0xae00000 0x1000>; - reg-names = "mdss"; - power-domains = <&dispcc MDSS_GDSC>; - clocks = <&gcc GCC_DISP_AHB_CLK>, - <&dispcc DISP_CC_MDSS_AHB_CLK>, - <&dispcc DISP_CC_MDSS_MDP_CLK>; - clock-names = "iface", "ahb", "core"; - - interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; - interrupt-controller; - #interrupt-cells = <1>; - - interconnects = <&mmss_noc MASTER_MDP0 &mc_virt SLAVE_EBI1>; - interconnect-names = "mdp0-mem"; - - iommus = <&apps_smmu 0x800 0x2>; - ranges; - - display-controller@ae01000 { - compatible = "qcom,sc7180-dpu"; - reg = <0x0ae01000 0x8f000>, - <0x0aeb0000 0x2008>; - - reg-names = "mdp", "vbif"; - - clocks = <&gcc GCC_DISP_HF_AXI_CLK>, - <&dispcc DISP_CC_MDSS_AHB_CLK>, - <&dispcc DISP_CC_MDSS_ROT_CLK>, - <&dispcc DISP_CC_MDSS_MDP_LUT_CLK>, - <&dispcc DISP_CC_MDSS_MDP_CLK>, - <&dispcc DISP_CC_MDSS_VSYNC_CLK>; - clock-names = "bus", "iface", "rot", "lut", "core", - "vsync"; - - interrupt-parent = <&mdss>; - interrupts = <0>; - power-domains = <&rpmhpd SC7180_CX>; - operating-points-v2 = <&mdp_opp_table>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - dpu_intf1_out: endpoint { - remote-endpoint = <&dsi0_in>; - }; - }; - - port@2 { - reg = <2>; - dpu_intf0_out: endpoint { - remote-endpoint = <&dp_in>; - }; - }; - }; - }; - }; -... diff --git a/Documentation/devicetree/bindings/display/msm/dpu-sc7280.yaml b/Documentation/devicetree/bindings/display/msm/dpu-sc7280.yaml deleted file mode 100644 index 584d646021d5..000000000000 --- a/Documentation/devicetree/bindings/display/msm/dpu-sc7280.yaml +++ /dev/null @@ -1,239 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/display/msm/dpu-sc7280.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Qualcomm Display DPU dt properties for SC7280 - -maintainers: - - Krishna Manikandan <quic_mkrishn@quicinc.com> - -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 and DPU are mentioned for SC7280. - -properties: - compatible: - const: qcom,sc7280-mdss - - reg: - maxItems: 1 - - reg-names: - const: mdss - - power-domains: - maxItems: 1 - - 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 - - interrupts: - maxItems: 1 - - interrupt-controller: true - - "#address-cells": true - - "#size-cells": true - - "#interrupt-cells": - const: 1 - - iommus: - items: - - description: Phandle to apps_smmu node with SID mask for Hard-Fail port0 - - ranges: true - - interconnects: - items: - - description: Interconnect path specifying the port ids for data bus - - interconnect-names: - const: mdp0-mem - - resets: - items: - - description: MDSS_CORE reset - -patternProperties: - "^display-controller@[0-9a-f]+$": - type: object - description: Node containing the properties of DPU. - additionalProperties: false - - properties: - compatible: - const: qcom,sc7280-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 - - interrupts: - maxItems: 1 - - 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. Each output port contains an endpoint that - describes how it is connected to an external interface. - - properties: - port@0: - $ref: /schemas/graph.yaml#/properties/port - description: DPU_INTF1 (DSI) - - port@1: - $ref: /schemas/graph.yaml#/properties/port - description: DPU_INTF5 (EDP) - - required: - - port@0 - - required: - - compatible - - reg - - reg-names - - clocks - - interrupts - - power-domains - - operating-points-v2 - - ports - -required: - - compatible - - reg - - reg-names - - power-domains - - clocks - - interrupts - - interrupt-controller - - iommus - - ranges - -additionalProperties: false - -examples: - - | - #include <dt-bindings/clock/qcom,dispcc-sc7280.h> - #include <dt-bindings/clock/qcom,gcc-sc7280.h> - #include <dt-bindings/interrupt-controller/arm-gic.h> - #include <dt-bindings/interconnect/qcom,sc7280.h> - #include <dt-bindings/power/qcom-rpmpd.h> - - display-subsystem@ae00000 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "qcom,sc7280-mdss"; - reg = <0xae00000 0x1000>; - reg-names = "mdss"; - power-domains = <&dispcc DISP_CC_MDSS_CORE_GDSC>; - clocks = <&gcc GCC_DISP_AHB_CLK>, - <&dispcc DISP_CC_MDSS_AHB_CLK>, - <&dispcc DISP_CC_MDSS_MDP_CLK>; - clock-names = "iface", - "ahb", - "core"; - - interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; - interrupt-controller; - #interrupt-cells = <1>; - - interconnects = <&mmss_noc MASTER_MDP0 &mc_virt SLAVE_EBI1>; - interconnect-names = "mdp0-mem"; - - iommus = <&apps_smmu 0x900 0x402>; - ranges; - - display-controller@ae01000 { - compatible = "qcom,sc7280-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"; - - interrupt-parent = <&mdss>; - interrupts = <0>; - power-domains = <&rpmhpd SC7280_CX>; - operating-points-v2 = <&mdp_opp_table>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - dpu_intf1_out: endpoint { - remote-endpoint = <&dsi0_in>; - }; - }; - - port@1 { - reg = <1>; - dpu_intf5_out: endpoint { - remote-endpoint = <&edp_in>; - }; - }; - }; - }; - }; -... diff --git a/Documentation/devicetree/bindings/display/msm/dpu-sdm845.yaml b/Documentation/devicetree/bindings/display/msm/dpu-sdm845.yaml deleted file mode 100644 index 7d1037373175..000000000000 --- a/Documentation/devicetree/bindings/display/msm/dpu-sdm845.yaml +++ /dev/null @@ -1,217 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/display/msm/dpu-sdm845.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Qualcomm Display DPU dt properties for SDM845 target - -maintainers: - - Krishna Manikandan <quic_mkrishn@quicinc.com> - -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 and DPU are mentioned for SDM845 target. - -properties: - compatible: - items: - - const: qcom,sdm845-mdss - - reg: - maxItems: 1 - - reg-names: - const: mdss - - power-domains: - maxItems: 1 - - clocks: - items: - - description: Display AHB clock from gcc - - description: Display core clock - - clock-names: - items: - - const: iface - - const: core - - interrupts: - maxItems: 1 - - interrupt-controller: true - - "#address-cells": true - - "#size-cells": true - - "#interrupt-cells": - const: 1 - - iommus: - items: - - description: Phandle to apps_smmu node with SID mask for Hard-Fail port0 - - description: Phandle to apps_smmu node with SID mask for Hard-Fail port1 - - ranges: true - - resets: - items: - - description: MDSS_CORE reset - -patternProperties: - "^display-controller@[0-9a-f]+$": - type: object - description: Node containing the properties of DPU. - additionalProperties: false - - properties: - compatible: - items: - - const: qcom,sdm845-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 axi clock - - description: Display core clock - - description: Display vsync clock - - clock-names: - items: - - const: iface - - const: bus - - const: core - - const: vsync - - interrupts: - maxItems: 1 - - 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. Each output port contains an endpoint that - describes how it is connected to an external interface. - - properties: - port@0: - $ref: /schemas/graph.yaml#/properties/port - description: DPU_INTF1 (DSI1) - - port@1: - $ref: /schemas/graph.yaml#/properties/port - description: DPU_INTF2 (DSI2) - - required: - - port@0 - - port@1 - - required: - - compatible - - reg - - reg-names - - clocks - - interrupts - - power-domains - - operating-points-v2 - - ports - -required: - - compatible - - reg - - reg-names - - power-domains - - clocks - - interrupts - - interrupt-controller - - iommus - - ranges - -additionalProperties: false - -examples: - - | - #include <dt-bindings/clock/qcom,dispcc-sdm845.h> - #include <dt-bindings/clock/qcom,gcc-sdm845.h> - #include <dt-bindings/interrupt-controller/arm-gic.h> - #include <dt-bindings/power/qcom-rpmpd.h> - - display-subsystem@ae00000 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "qcom,sdm845-mdss"; - reg = <0x0ae00000 0x1000>; - reg-names = "mdss"; - power-domains = <&dispcc MDSS_GDSC>; - - clocks = <&gcc GCC_DISP_AHB_CLK>, - <&dispcc DISP_CC_MDSS_MDP_CLK>; - clock-names = "iface", "core"; - - interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; - interrupt-controller; - #interrupt-cells = <1>; - - iommus = <&apps_smmu 0x880 0x8>, - <&apps_smmu 0xc80 0x8>; - ranges; - - display-controller@ae01000 { - compatible = "qcom,sdm845-dpu"; - reg = <0x0ae01000 0x8f000>, - <0x0aeb0000 0x2008>; - reg-names = "mdp", "vbif"; - - clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, - <&dispcc DISP_CC_MDSS_AXI_CLK>, - <&dispcc DISP_CC_MDSS_MDP_CLK>, - <&dispcc DISP_CC_MDSS_VSYNC_CLK>; - clock-names = "iface", "bus", "core", "vsync"; - - interrupt-parent = <&mdss>; - interrupts = <0>; - power-domains = <&rpmhpd SDM845_CX>; - operating-points-v2 = <&mdp_opp_table>; - - 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>; - }; - }; - }; - }; - }; -... diff --git a/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml b/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml index 3b609c19e0bc..f2c143730a55 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml @@ -49,6 +49,7 @@ properties: maxItems: 1 phy-names: + deprecated: true const: dsi "#address-cells": true @@ -80,6 +81,9 @@ properties: operating-points-v2: true + opp-table: + type: object + ports: $ref: "/schemas/graph.yaml#/properties/ports" description: | @@ -131,7 +135,6 @@ required: - clocks - clock-names - phys - - phy-names - assigned-clocks - assigned-clock-parents - power-domains diff --git a/Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.yaml b/Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.yaml index 1342d74ecfe0..819de5ce0bc9 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.yaml @@ -16,6 +16,7 @@ properties: compatible: enum: - qcom,dsi-phy-14nm + - qcom,dsi-phy-14nm-2290 - qcom,dsi-phy-14nm-660 - qcom,dsi-phy-14nm-8953 diff --git a/Documentation/devicetree/bindings/display/msm/mdp5.txt b/Documentation/devicetree/bindings/display/msm/mdp5.txt index 43d11279c925..65d03c58dee6 100644 --- a/Documentation/devicetree/bindings/display/msm/mdp5.txt +++ b/Documentation/devicetree/bindings/display/msm/mdp5.txt @@ -2,37 +2,9 @@ Qualcomm adreno/snapdragon MDP5 display controller Description: -This is the bindings documentation for the Mobile Display Subsytem(MDSS) that -encapsulates sub-blocks like MDP5, DSI, HDMI, eDP etc, and the MDP5 display +This is the bindings documentation for the MDP5 display controller found in SoCs like MSM8974, APQ8084, MSM8916, MSM8994 and MSM8996. -MDSS: -Required properties: -- compatible: - * "qcom,mdss" - MDSS -- reg: Physical base address and length of the controller's registers. -- reg-names: The names of register regions. The following regions are required: - * "mdss_phys" - * "vbif_phys" -- interrupts: The interrupt signal from MDSS. -- interrupt-controller: identifies the node as an interrupt controller. -- #interrupt-cells: specifies the number of cells needed to encode an interrupt - source, should be 1. -- power-domains: a power domain consumer specifier according to - Documentation/devicetree/bindings/power/power_domain.txt -- clocks: device clocks. See ../clocks/clock-bindings.txt for details. -- clock-names: the following clocks are required. - * "iface" - * "bus" - * "vsync" -- #address-cells: number of address cells for the MDSS children. Should be 1. -- #size-cells: Should be 1. -- ranges: parent bus address space is the same as the child bus address space. - -Optional properties: -- clock-names: the following clocks are optional: - * "lut" - MDP5: Required properties: - compatible: diff --git a/Documentation/devicetree/bindings/display/msm/mdss-common.yaml b/Documentation/devicetree/bindings/display/msm/mdss-common.yaml new file mode 100644 index 000000000000..27d7242657b2 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/mdss-common.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/mdss-common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display MDSS common properties + +maintainers: + - Krishna Manikandan <quic_mkrishn@quicinc.com> + - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> + - Rob Clark <robdclark@gmail.com> + +description: + Device tree bindings for MSM Mobile Display Subsystem(MDSS) that encapsulates + sub-blocks like DPU display controller, DSI and DP interfaces etc. + +properties: + reg: + maxItems: 1 + + reg-names: + const: mdss + + power-domains: + maxItems: 1 + + clocks: + minItems: 2 + maxItems: 4 + + clock-names: + minItems: 2 + maxItems: 4 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + "#address-cells": true + + "#size-cells": true + + "#interrupt-cells": + const: 1 + + iommus: + minItems: 1 + items: + - description: Phandle to apps_smmu node with SID mask for Hard-Fail port0 + - description: Phandle to apps_smmu node with SID mask for Hard-Fail port1 + + ranges: true + + 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 + + interconnect-names: + minItems: 1 + items: + - const: mdp0-mem + - const: mdp1-mem + + resets: + items: + - description: MDSS_CORE reset + +required: + - compatible + - reg + - reg-names + - power-domains + - clocks + - interrupts + - interrupt-controller + - iommus + - ranges + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/display/msm/qcom,mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,mdss.yaml new file mode 100644 index 000000000000..ba0460268731 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,mdss.yaml @@ -0,0 +1,196 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,mdss.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Mobile Display SubSystem (MDSS) + +maintainers: + - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> + - Rob Clark <robdclark@gmail.com> + +description: + This is the bindings documentation for the Mobile Display Subsytem(MDSS) that + encapsulates sub-blocks like MDP5, DSI, HDMI, eDP, etc. + +properties: + compatible: + enum: + - qcom,mdss + + reg: + minItems: 2 + maxItems: 3 + + reg-names: + minItems: 2 + items: + - const: mdss_phys + - const: vbif_phys + - const: vbif_nrt_phys + + interrupts: + maxItems: 1 + + interrupt-controller: true + + "#interrupt-cells": + const: 1 + + power-domains: + maxItems: 1 + description: | + The MDSS power domain provided by GCC + + clocks: + minItems: 1 + items: + - description: Display abh clock + - description: Display axi clock + - description: Display vsync clock + + clock-names: + minItems: 1 + items: + - const: iface + - const: bus + - const: vsync + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + ranges: true + + resets: + items: + - description: MDSS_CORE reset + +required: + - compatible + - reg + - reg-names + - interrupts + - interrupt-controller + - "#interrupt-cells" + - power-domains + - clocks + - clock-names + - "#address-cells" + - "#size-cells" + - ranges + +patternProperties: + "^mdp@[1-9a-f][0-9a-f]*$": + type: object + properties: + compatible: + const: qcom,mdp5 + + "^dsi@[1-9a-f][0-9a-f]*$": + type: object + properties: + compatible: + const: qcom,mdss-dsi-ctrl + + "^phy@[1-9a-f][0-9a-f]*$": + type: object + properties: + compatible: + enum: + - qcom,dsi-phy-14nm + - qcom,dsi-phy-14nm-660 + - qcom,dsi-phy-14nm-8953 + - 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 + - qcom,hdmi-phy-8974 + - qcom,hdmi-phy-8996 + + "^hdmi-tx@[1-9a-f][0-9a-f]*$": + type: object + properties: + compatible: + enum: + - qcom,hdmi-tx-8084 + - qcom,hdmi-tx-8660 + - qcom,hdmi-tx-8960 + - qcom,hdmi-tx-8974 + - qcom,hdmi-tx-8994 + - qcom,hdmi-tx-8996 + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-msm8916.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + 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 = <GIC_SPI 72 IRQ_TYPE_LEVEL_HIGH>; + + interrupt-controller; + #interrupt-cells = <1>; + + #address-cells = <1>; + #size-cells = <1>; + ranges; + + mdp@1a01000 { + compatible = "qcom,mdp5"; + reg = <0x01a01000 0x89000>; + 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"; + + iommus = <&apps_iommu 4>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + mdp5_intf1_out: endpoint { + remote-endpoint = <&dsi0_in>; + }; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,msm8998-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,msm8998-dpu.yaml new file mode 100644 index 000000000000..b02adba36e9e --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,msm8998-dpu.yaml @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,msm8998-dpu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display DPU dt properties for MSM8998 target + +maintainers: + - AngeloGioacchino Del Regno <angelogioacchino.delregno@somainline.org> + +$ref: /schemas/display/msm/dpu-common.yaml# + +properties: + compatible: + items: + - const: qcom,msm8998-dpu + + reg: + items: + - description: Address offset and size for mdp register set + - description: Address offset and size for regdma register set + - description: Address offset and size for vbif register set + - description: Address offset and size for non-realtime vbif register set + + reg-names: + items: + - const: mdp + - const: regdma + - const: vbif + - const: vbif_nrt + + clocks: + items: + - description: Display ahb clock + - description: Display axi clock + - description: Display mem-noc clock + - description: Display core clock + - description: Display vsync clock + + clock-names: + items: + - const: iface + - const: bus + - const: mnoc + - const: core + - const: vsync + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,mmcc-msm8998.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-controller@c901000 { + compatible = "qcom,msm8998-dpu"; + reg = <0x0c901000 0x8f000>, + <0x0c9a8e00 0xf0>, + <0x0c9b0000 0x2008>, + <0x0c9b8000 0x1040>; + reg-names = "mdp", "regdma", "vbif", "vbif_nrt"; + + clocks = <&mmcc MDSS_AHB_CLK>, + <&mmcc MDSS_AXI_CLK>, + <&mmcc MNOC_AHB_CLK>, + <&mmcc MDSS_MDP_CLK>, + <&mmcc MDSS_VSYNC_CLK>; + clock-names = "iface", "bus", "mnoc", "core", "vsync"; + + interrupt-parent = <&mdss>; + interrupts = <0>; + operating-points-v2 = <&mdp_opp_table>; + power-domains = <&rpmpd MSM8998_VDDMX>; + + 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,msm8998-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,msm8998-mdss.yaml new file mode 100644 index 000000000000..cf52ff77a41a --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,msm8998-mdss.yaml @@ -0,0 +1,268 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,msm8998-mdss.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm MSM8998 Display MDSS + +maintainers: + - AngeloGioacchino Del Regno <angelogioacchino.delregno@somainline.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 MSM8998 target. + +$ref: /schemas/display/msm/mdss-common.yaml# + +properties: + compatible: + items: + - const: qcom,msm8998-mdss + + clocks: + items: + - description: Display AHB clock + - description: Display AXI clock + - description: Display core clock + + clock-names: + items: + - const: iface + - const: bus + - const: core + + iommus: + maxItems: 1 + +patternProperties: + "^display-controller@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,msm8998-dpu + + "^dsi@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,mdss-dsi-ctrl + + "^phy@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,dsi-phy-10nm-8998 + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,mmcc-msm8998.h> + #include <dt-bindings/clock/qcom,rpmcc.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-subsystem@c900000 { + compatible = "qcom,msm8998-mdss"; + reg = <0x0c900000 0x1000>; + reg-names = "mdss"; + + clocks = <&mmcc MDSS_AHB_CLK>, + <&mmcc MDSS_AXI_CLK>, + <&mmcc MDSS_MDP_CLK>; + clock-names = "iface", "bus", "core"; + + #address-cells = <1>; + #interrupt-cells = <1>; + #size-cells = <1>; + + interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + iommus = <&mmss_smmu 0>; + + power-domains = <&mmcc MDSS_GDSC>; + ranges; + + display-controller@c901000 { + compatible = "qcom,msm8998-dpu"; + reg = <0x0c901000 0x8f000>, + <0x0c9a8e00 0xf0>, + <0x0c9b0000 0x2008>, + <0x0c9b8000 0x1040>; + reg-names = "mdp", "regdma", "vbif", "vbif_nrt"; + + clocks = <&mmcc MDSS_AHB_CLK>, + <&mmcc MDSS_AXI_CLK>, + <&mmcc MNOC_AHB_CLK>, + <&mmcc MDSS_MDP_CLK>, + <&mmcc MDSS_VSYNC_CLK>; + clock-names = "iface", "bus", "mnoc", "core", "vsync"; + + interrupt-parent = <&mdss>; + interrupts = <0>; + operating-points-v2 = <&mdp_opp_table>; + power-domains = <&rpmpd MSM8998_VDDMX>; + + 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>; + }; + }; + }; + }; + + dsi@c994000 { + compatible = "qcom,mdss-dsi-ctrl"; + reg = <0x0c994000 0x400>; + reg-names = "dsi_ctrl"; + + interrupt-parent = <&mdss>; + interrupts = <4>; + + clocks = <&mmcc MDSS_BYTE0_CLK>, + <&mmcc MDSS_BYTE0_INTF_CLK>, + <&mmcc MDSS_PCLK0_CLK>, + <&mmcc MDSS_ESC0_CLK>, + <&mmcc MDSS_AHB_CLK>, + <&mmcc MDSS_AXI_CLK>; + clock-names = "byte", + "byte_intf", + "pixel", + "core", + "iface", + "bus"; + assigned-clocks = <&mmcc BYTE0_CLK_SRC>, <&mmcc PCLK0_CLK_SRC>; + assigned-clock-parents = <&dsi0_phy 0>, <&dsi0_phy 1>; + + operating-points-v2 = <&dsi_opp_table>; + power-domains = <&rpmpd MSM8998_VDDCX>; + + 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 { + }; + }; + }; + }; + + dsi0_phy: phy@c994400 { + compatible = "qcom,dsi-phy-10nm-8998"; + reg = <0x0c994400 0x200>, + <0x0c994600 0x280>, + <0x0c994a00 0x1e0>; + reg-names = "dsi_phy", + "dsi_phy_lane", + "dsi_pll"; + + #clock-cells = <1>; + #phy-cells = <0>; + + clocks = <&mmcc MDSS_AHB_CLK>, + <&rpmcc RPM_SMD_XO_CLK_SRC>; + clock-names = "iface", "ref"; + + vdds-supply = <&pm8998_l1>; + }; + + dsi@c996000 { + compatible = "qcom,mdss-dsi-ctrl"; + reg = <0x0c996000 0x400>; + reg-names = "dsi_ctrl"; + + interrupt-parent = <&mdss>; + interrupts = <5>; + + clocks = <&mmcc MDSS_BYTE1_CLK>, + <&mmcc MDSS_BYTE1_INTF_CLK>, + <&mmcc MDSS_PCLK1_CLK>, + <&mmcc MDSS_ESC1_CLK>, + <&mmcc MDSS_AHB_CLK>, + <&mmcc MDSS_AXI_CLK>; + clock-names = "byte", + "byte_intf", + "pixel", + "core", + "iface", + "bus"; + assigned-clocks = <&mmcc BYTE1_CLK_SRC>, <&mmcc PCLK1_CLK_SRC>; + assigned-clock-parents = <&dsi1_phy 0>, <&dsi1_phy 1>; + + operating-points-v2 = <&dsi_opp_table>; + power-domains = <&rpmpd MSM8998_VDDCX>; + + 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@c996400 { + compatible = "qcom,dsi-phy-10nm-8998"; + reg = <0x0c996400 0x200>, + <0x0c996600 0x280>, + <0x0c996a00 0x10e>; + reg-names = "dsi_phy", + "dsi_phy_lane", + "dsi_pll"; + + #clock-cells = <1>; + #phy-cells = <0>; + + clocks = <&mmcc MDSS_AHB_CLK>, + <&rpmcc RPM_SMD_XO_CLK_SRC>; + clock-names = "iface", "ref"; + + vdds-supply = <&pm8998_l1>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-dpu.yaml new file mode 100644 index 000000000000..a7b382f01b56 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-dpu.yaml @@ -0,0 +1,84 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,qcm2290-dpu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display DPU dt properties for QCM2290 target + +maintainers: + - Loic Poulain <loic.poulain@linaro.org> + +$ref: /schemas/display/msm/dpu-common.yaml# + +properties: + compatible: + items: + - const: qcom,qcm2290-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 AXI clock from gcc + - description: Display AHB clock from dispcc + - description: Display core clock from dispcc + - description: Display lut clock from dispcc + - description: Display vsync clock from dispcc + + clock-names: + items: + - const: bus + - const: iface + - const: core + - const: lut + - const: vsync + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,dispcc-qcm2290.h> + #include <dt-bindings/clock/qcom,gcc-qcm2290.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-controller@5e01000 { + compatible = "qcom,qcm2290-dpu"; + reg = <0x05e01000 0x8f000>, + <0x05eb0000 0x2008>; + reg-names = "mdp", "vbif"; + + clocks = <&gcc GCC_DISP_HF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>, + <&dispcc DISP_CC_MDSS_MDP_LUT_CLK>, + <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + clock-names = "bus", "iface", "core", "lut", "vsync"; + + operating-points-v2 = <&mdp_opp_table>; + power-domains = <&rpmpd QCM2290_VDDCX>; + + interrupt-parent = <&mdss>; + interrupts = <0>; + + 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,qcm2290-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-mdss.yaml new file mode 100644 index 000000000000..d6f043a4b08d --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,qcm2290-mdss.yaml @@ -0,0 +1,198 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,qcm2290-mdss.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm QCM220 Display MDSS + +maintainers: + - Loic Poulain <loic.poulain@linaro.org> + +description: + Device tree bindings for MSM Mobile Display Subsystem(MDSS) that encapsulates + sub-blocks like DPU display controller and DSI. Device tree bindings of MDSS + are mentioned for QCM2290 target. + +$ref: /schemas/display/msm/mdss-common.yaml# + +properties: + compatible: + items: + - const: qcom,qcm2290-mdss + + clocks: + items: + - description: Display AHB clock from gcc + - description: Display AXI clock + - description: Display core clock + + clock-names: + items: + - const: iface + - const: bus + - const: core + + iommus: + maxItems: 2 + + interconnects: + maxItems: 1 + + interconnect-names: + maxItems: 1 + +patternProperties: + "^display-controller@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,qcm2290-dpu + + "^dsi@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,dsi-ctrl-6g-qcm2290 + + "^phy@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,dsi-phy-14nm-2290 + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,dispcc-qcm2290.h> + #include <dt-bindings/clock/qcom,gcc-qcm2290.h> + #include <dt-bindings/clock/qcom,rpmcc.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interconnect/qcom,qcm2290.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + mdss@5e00000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "qcom,qcm2290-mdss"; + reg = <0x05e00000 0x1000>; + reg-names = "mdss"; + power-domains = <&dispcc MDSS_GDSC>; + clocks = <&gcc GCC_DISP_AHB_CLK>, + <&gcc GCC_DISP_HF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>; + clock-names = "iface", "bus", "core"; + + interrupts = <GIC_SPI 186 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <1>; + + interconnects = <&mmrt_virt MASTER_MDP0 &bimc SLAVE_EBI1>; + interconnect-names = "mdp0-mem"; + + iommus = <&apps_smmu 0x420 0x2>, + <&apps_smmu 0x421 0x0>; + ranges; + + display-controller@5e01000 { + compatible = "qcom,qcm2290-dpu"; + reg = <0x05e01000 0x8f000>, + <0x05eb0000 0x2008>; + reg-names = "mdp", "vbif"; + + clocks = <&gcc GCC_DISP_HF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>, + <&dispcc DISP_CC_MDSS_MDP_LUT_CLK>, + <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + clock-names = "bus", "iface", "core", "lut", "vsync"; + + operating-points-v2 = <&mdp_opp_table>; + power-domains = <&rpmpd QCM2290_VDDCX>; + + interrupt-parent = <&mdss>; + interrupts = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dpu_intf1_out: endpoint { + remote-endpoint = <&dsi0_in>; + }; + }; + }; + }; + + dsi@5e94000 { + compatible = "qcom,dsi-ctrl-6g-qcm2290"; + reg = <0x05e94000 0x400>; + reg-names = "dsi_ctrl"; + + interrupt-parent = <&mdss>; + interrupts = <4>; + + clocks = <&dispcc DISP_CC_MDSS_BYTE0_CLK>, + <&dispcc DISP_CC_MDSS_BYTE0_INTF_CLK>, + <&dispcc DISP_CC_MDSS_PCLK0_CLK>, + <&dispcc DISP_CC_MDSS_ESC0_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&gcc GCC_DISP_HF_AXI_CLK>; + clock-names = "byte", + "byte_intf", + "pixel", + "core", + "iface", + "bus"; + assigned-clocks = <&dispcc DISP_CC_MDSS_BYTE0_CLK_SRC>, <&dispcc DISP_CC_MDSS_PCLK0_CLK_SRC>; + assigned-clock-parents = <&dsi0_phy 0>, <&dsi0_phy 1>; + + operating-points-v2 = <&dsi_opp_table>; + power-domains = <&rpmpd QCM2290_VDDCX>; + + 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 { + }; + }; + }; + }; + + dsi0_phy: phy@5e94400 { + compatible = "qcom,dsi-phy-14nm-2290"; + reg = <0x05e94400 0x100>, + <0x05e94500 0x300>, + <0x05e94800 0x188>; + reg-names = "dsi_phy", + "dsi_phy_lane", + "dsi_pll"; + + #clock-cells = <1>; + #phy-cells = <0>; + + clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, <&rpmcc RPM_SMD_XO_CLK_SRC>; + clock-names = "iface", "ref"; + vcca-supply = <&vreg_dsi_phy>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sc7180-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sc7180-dpu.yaml new file mode 100644 index 000000000000..bd590a6b5b96 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sc7180-dpu.yaml @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,sc7180-dpu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display DPU dt properties for SC7180 target + +maintainers: + - Krishna Manikandan <quic_mkrishn@quicinc.com> + +$ref: /schemas/display/msm/dpu-common.yaml# + +properties: + compatible: + items: + - const: qcom,sc7180-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 ahb clock + - description: Display rotator clock + - description: Display lut clock + - description: Display core clock + - description: Display vsync clock + + clock-names: + items: + - const: bus + - const: iface + - const: rot + - const: lut + - const: core + - const: vsync + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,dispcc-sc7180.h> + #include <dt-bindings/clock/qcom,gcc-sc7180.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-controller@ae01000 { + compatible = "qcom,sc7180-dpu"; + reg = <0x0ae01000 0x8f000>, + <0x0aeb0000 0x2008>; + + reg-names = "mdp", "vbif"; + + clocks = <&gcc GCC_DISP_HF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_ROT_CLK>, + <&dispcc DISP_CC_MDSS_MDP_LUT_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>, + <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + clock-names = "bus", "iface", "rot", "lut", "core", + "vsync"; + + interrupt-parent = <&mdss>; + interrupts = <0>; + power-domains = <&rpmhpd SC7180_CX>; + operating-points-v2 = <&mdp_opp_table>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + endpoint { + remote-endpoint = <&dsi0_in>; + }; + }; + + port@2 { + reg = <2>; + endpoint { + remote-endpoint = <&dp_in>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sc7180-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sc7180-mdss.yaml new file mode 100644 index 000000000000..13e396d61a51 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sc7180-mdss.yaml @@ -0,0 +1,304 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,sc7180-mdss.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SC7180 Display MDSS + +maintainers: + - Krishna Manikandan <quic_mkrishn@quicinc.com> + +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 SC7180 target. + +$ref: /schemas/display/msm/mdss-common.yaml# + +properties: + compatible: + items: + - const: qcom,sc7180-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 + + iommus: + maxItems: 1 + + interconnects: + maxItems: 1 + + interconnect-names: + maxItems: 1 + +patternProperties: + "^display-controller@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,sc7180-dpu + + "^displayport-controller@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,sc7180-dp + + "^dsi@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,mdss-dsi-ctrl + + "^phy@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,dsi-phy-10nm + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,dispcc-sc7180.h> + #include <dt-bindings/clock/qcom,gcc-sc7180.h> + #include <dt-bindings/clock/qcom,rpmh.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interconnect/qcom,sdm845.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-subsystem@ae00000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "qcom,sc7180-mdss"; + reg = <0xae00000 0x1000>; + reg-names = "mdss"; + power-domains = <&dispcc MDSS_GDSC>; + clocks = <&gcc GCC_DISP_AHB_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>; + clock-names = "iface", "ahb", "core"; + + interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <1>; + + interconnects = <&mmss_noc MASTER_MDP0 &mc_virt SLAVE_EBI1>; + interconnect-names = "mdp0-mem"; + + iommus = <&apps_smmu 0x800 0x2>; + ranges; + + display-controller@ae01000 { + compatible = "qcom,sc7180-dpu"; + reg = <0x0ae01000 0x8f000>, + <0x0aeb0000 0x2008>; + + reg-names = "mdp", "vbif"; + + clocks = <&gcc GCC_DISP_HF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_ROT_CLK>, + <&dispcc DISP_CC_MDSS_MDP_LUT_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>, + <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + clock-names = "bus", "iface", "rot", "lut", "core", + "vsync"; + + interrupt-parent = <&mdss>; + interrupts = <0>; + power-domains = <&rpmhpd SC7180_CX>; + operating-points-v2 = <&mdp_opp_table>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dpu_intf1_out: endpoint { + remote-endpoint = <&dsi0_in>; + }; + }; + + port@2 { + reg = <2>; + dpu_intf0_out: endpoint { + remote-endpoint = <&dp_in>; + }; + }; + }; + }; + + dsi@ae94000 { + compatible = "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 = <&dsi_phy 0>, <&dsi_phy 1>; + + operating-points-v2 = <&dsi_opp_table>; + power-domains = <&rpmhpd SC7180_CX>; + + phys = <&dsi_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>; + }; + }; + }; + + dsi_phy: phy@ae94400 { + compatible = "qcom,dsi-phy-10nm"; + reg = <0x0ae94400 0x200>, + <0x0ae94600 0x280>, + <0x0ae94a00 0x1e0>; + 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>; + }; + + displayport-controller@ae90000 { + compatible = "qcom,sc7180-dp"; + + reg = <0xae90000 0x200>, + <0xae90200 0x200>, + <0xae90400 0xc00>, + <0xae91000 0x400>, + <0xae91400 0x400>; + + interrupt-parent = <&mdss>; + interrupts = <12>; + + clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_DP_AUX_CLK>, + <&dispcc DISP_CC_MDSS_DP_LINK_CLK>, + <&dispcc DISP_CC_MDSS_DP_LINK_INTF_CLK>, + <&dispcc DISP_CC_MDSS_DP_PIXEL_CLK>; + clock-names = "core_iface", "core_aux", "ctrl_link", + "ctrl_link_iface", "stream_pixel"; + assigned-clocks = <&dispcc DISP_CC_MDSS_DP_LINK_CLK_SRC>, + <&dispcc DISP_CC_MDSS_DP_PIXEL_CLK_SRC>; + assigned-clock-parents = <&dp_phy 0>, <&dp_phy 1>; + phys = <&dp_phy>; + phy-names = "dp"; + + operating-points-v2 = <&dp_opp_table>; + power-domains = <&rpmhpd SC7180_CX>; + + #sound-dai-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + port@0 { + reg = <0>; + dp_in: endpoint { + remote-endpoint = <&dpu_intf0_out>; + }; + }; + + port@1 { + reg = <1>; + dp_out: endpoint { }; + }; + }; + + dp_opp_table: opp-table { + compatible = "operating-points-v2"; + + opp-160000000 { + opp-hz = /bits/ 64 <160000000>; + required-opps = <&rpmhpd_opp_low_svs>; + }; + + opp-270000000 { + opp-hz = /bits/ 64 <270000000>; + required-opps = <&rpmhpd_opp_svs>; + }; + + opp-540000000 { + opp-hz = /bits/ 64 <540000000>; + required-opps = <&rpmhpd_opp_svs_l1>; + }; + + opp-810000000 { + opp-hz = /bits/ 64 <810000000>; + required-opps = <&rpmhpd_opp_nom>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sc7280-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sc7280-dpu.yaml new file mode 100644 index 000000000000..924059b387b6 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sc7280-dpu.yaml @@ -0,0 +1,98 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,sc7280-dpu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display DPU dt properties for SC7280 + +maintainers: + - Krishna Manikandan <quic_mkrishn@quicinc.com> + +$ref: /schemas/display/msm/dpu-common.yaml# + +properties: + compatible: + const: qcom,sc7280-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-sc7280.h> + #include <dt-bindings/clock/qcom,gcc-sc7280.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-controller@ae01000 { + compatible = "qcom,sc7280-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"; + + interrupt-parent = <&mdss>; + interrupts = <0>; + power-domains = <&rpmhpd SC7280_CX>; + operating-points-v2 = <&mdp_opp_table>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + endpoint { + remote-endpoint = <&dsi0_in>; + }; + }; + + port@1 { + reg = <1>; + endpoint { + remote-endpoint = <&edp_in>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sc7280-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sc7280-mdss.yaml new file mode 100644 index 000000000000..a3de1744ba11 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sc7280-mdss.yaml @@ -0,0 +1,422 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,sc7280-mdss.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SC7280 Display MDSS + +maintainers: + - Krishna Manikandan <quic_mkrishn@quicinc.com> + +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 SC7280. + +$ref: /schemas/display/msm/mdss-common.yaml# + +properties: + compatible: + const: qcom,sc7280-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 + + iommus: + maxItems: 1 + + interconnects: + maxItems: 1 + + interconnect-names: + maxItems: 1 + +patternProperties: + "^display-controller@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,sc7280-dpu + + "^displayport-controller@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,sc7280-dp + + "^dsi@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,mdss-dsi-ctrl + + "^edp@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,sc7280-edp + + "^phy@[0-9a-f]+$": + type: object + properties: + compatible: + enum: + - qcom,sc7280-dsi-phy-7nm + - qcom,sc7280-edp-phy + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,dispcc-sc7280.h> + #include <dt-bindings/clock/qcom,gcc-sc7280.h> + #include <dt-bindings/clock/qcom,rpmh.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interconnect/qcom,sc7280.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-subsystem@ae00000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "qcom,sc7280-mdss"; + reg = <0xae00000 0x1000>; + reg-names = "mdss"; + power-domains = <&dispcc DISP_CC_MDSS_CORE_GDSC>; + clocks = <&gcc GCC_DISP_AHB_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>; + clock-names = "iface", + "ahb", + "core"; + + interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <1>; + + interconnects = <&mmss_noc MASTER_MDP0 &mc_virt SLAVE_EBI1>; + interconnect-names = "mdp0-mem"; + + iommus = <&apps_smmu 0x900 0x402>; + ranges; + + display-controller@ae01000 { + compatible = "qcom,sc7280-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"; + + interrupt-parent = <&mdss>; + interrupts = <0>; + power-domains = <&rpmhpd SC7280_CX>; + operating-points-v2 = <&mdp_opp_table>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dpu_intf1_out: endpoint { + remote-endpoint = <&dsi0_in>; + }; + }; + + port@1 { + reg = <1>; + dpu_intf5_out: endpoint { + remote-endpoint = <&edp_in>; + }; + }; + + port@2 { + reg = <2>; + dpu_intf0_out: endpoint { + remote-endpoint = <&dp_in>; + }; + }; + }; + }; + + dsi@ae94000 { + compatible = "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_dsi_phy 0>, <&mdss_dsi_phy 1>; + + operating-points-v2 = <&dsi_opp_table>; + power-domains = <&rpmhpd SC7280_CX>; + + phys = <&mdss_dsi_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>; + }; + }; + }; + + mdss_dsi_phy: phy@ae94400 { + compatible = "qcom,sc7280-dsi-phy-7nm"; + reg = <0x0ae94400 0x200>, + <0x0ae94600 0x280>, + <0x0ae94900 0x280>; + 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_supply>; + }; + + edp@aea0000 { + compatible = "qcom,sc7280-edp"; + pinctrl-names = "default"; + pinctrl-0 = <&edp_hot_plug_det>; + + reg = <0xaea0000 0x200>, + <0xaea0200 0x200>, + <0xaea0400 0xc00>, + <0xaea1000 0x400>; + + interrupt-parent = <&mdss>; + interrupts = <14>; + + clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_EDP_AUX_CLK>, + <&dispcc DISP_CC_MDSS_EDP_LINK_CLK>, + <&dispcc DISP_CC_MDSS_EDP_LINK_INTF_CLK>, + <&dispcc DISP_CC_MDSS_EDP_PIXEL_CLK>; + clock-names = "core_iface", + "core_aux", + "ctrl_link", + "ctrl_link_iface", + "stream_pixel"; + assigned-clocks = <&dispcc DISP_CC_MDSS_EDP_LINK_CLK_SRC>, + <&dispcc DISP_CC_MDSS_EDP_PIXEL_CLK_SRC>; + assigned-clock-parents = <&mdss_edp_phy 0>, <&mdss_edp_phy 1>; + + phys = <&mdss_edp_phy>; + phy-names = "dp"; + + operating-points-v2 = <&edp_opp_table>; + power-domains = <&rpmhpd SC7280_CX>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + edp_in: endpoint { + remote-endpoint = <&dpu_intf5_out>; + }; + }; + + port@1 { + reg = <1>; + mdss_edp_out: endpoint { }; + }; + }; + + edp_opp_table: opp-table { + compatible = "operating-points-v2"; + + opp-160000000 { + opp-hz = /bits/ 64 <160000000>; + required-opps = <&rpmhpd_opp_low_svs>; + }; + + opp-270000000 { + opp-hz = /bits/ 64 <270000000>; + required-opps = <&rpmhpd_opp_svs>; + }; + + opp-540000000 { + opp-hz = /bits/ 64 <540000000>; + required-opps = <&rpmhpd_opp_nom>; + }; + + opp-810000000 { + opp-hz = /bits/ 64 <810000000>; + required-opps = <&rpmhpd_opp_nom>; + }; + }; + }; + + mdss_edp_phy: phy@aec2a00 { + compatible = "qcom,sc7280-edp-phy"; + + reg = <0xaec2a00 0x19c>, + <0xaec2200 0xa0>, + <0xaec2600 0xa0>, + <0xaec2000 0x1c0>; + + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&gcc GCC_EDP_CLKREF_EN>; + clock-names = "aux", + "cfg_ahb"; + + #clock-cells = <1>; + #phy-cells = <0>; + }; + + displayport-controller@ae90000 { + compatible = "qcom,sc7280-dp"; + + reg = <0xae90000 0x200>, + <0xae90200 0x200>, + <0xae90400 0xc00>, + <0xae91000 0x400>, + <0xae91400 0x400>; + + interrupt-parent = <&mdss>; + interrupts = <12>; + + clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_DP_AUX_CLK>, + <&dispcc DISP_CC_MDSS_DP_LINK_CLK>, + <&dispcc DISP_CC_MDSS_DP_LINK_INTF_CLK>, + <&dispcc DISP_CC_MDSS_DP_PIXEL_CLK>; + clock-names = "core_iface", + "core_aux", + "ctrl_link", + "ctrl_link_iface", + "stream_pixel"; + assigned-clocks = <&dispcc DISP_CC_MDSS_DP_LINK_CLK_SRC>, + <&dispcc DISP_CC_MDSS_DP_PIXEL_CLK_SRC>; + assigned-clock-parents = <&dp_phy 0>, <&dp_phy 1>; + phys = <&dp_phy>; + phy-names = "dp"; + + operating-points-v2 = <&dp_opp_table>; + power-domains = <&rpmhpd SC7280_CX>; + + #sound-dai-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dp_in: endpoint { + remote-endpoint = <&dpu_intf0_out>; + }; + }; + + port@1 { + reg = <1>; + dp_out: endpoint { }; + }; + }; + + dp_opp_table: opp-table { + compatible = "operating-points-v2"; + + opp-160000000 { + opp-hz = /bits/ 64 <160000000>; + required-opps = <&rpmhpd_opp_low_svs>; + }; + + opp-270000000 { + opp-hz = /bits/ 64 <270000000>; + required-opps = <&rpmhpd_opp_svs>; + }; + + opp-540000000 { + opp-hz = /bits/ 64 <540000000>; + required-opps = <&rpmhpd_opp_svs_l1>; + }; + + opp-810000000 { + opp-hz = /bits/ 64 <810000000>; + required-opps = <&rpmhpd_opp_nom>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sdm845-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sdm845-dpu.yaml new file mode 100644 index 000000000000..5719b45f2860 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sdm845-dpu.yaml @@ -0,0 +1,90 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,sdm845-dpu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display DPU dt properties for SDM845 target + +maintainers: + - Krishna Manikandan <quic_mkrishn@quicinc.com> + +$ref: /schemas/display/msm/dpu-common.yaml# + +properties: + compatible: + items: + - const: qcom,sdm845-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 GCC bus clock + - description: Display ahb clock + - description: Display axi clock + - description: Display core clock + - description: Display vsync clock + + clock-names: + items: + - const: gcc-bus + - const: iface + - const: bus + - const: core + - const: vsync + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,dispcc-sdm845.h> + #include <dt-bindings/clock/qcom,gcc-sdm845.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-controller@ae01000 { + compatible = "qcom,sdm845-dpu"; + reg = <0x0ae01000 0x8f000>, + <0x0aeb0000 0x2008>; + reg-names = "mdp", "vbif"; + + clocks = <&gcc GCC_DISP_AXI_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_AXI_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>, + <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + clock-names = "gcc-bus", "iface", "bus", "core", "vsync"; + + interrupt-parent = <&mdss>; + interrupts = <0>; + power-domains = <&rpmhpd SDM845_CX>; + operating-points-v2 = <&mdp_opp_table>; + + 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,sdm845-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sdm845-mdss.yaml new file mode 100644 index 000000000000..31ca6f99fc22 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sdm845-mdss.yaml @@ -0,0 +1,270 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,sdm845-mdss.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SDM845 Display MDSS + +maintainers: + - Krishna Manikandan <quic_mkrishn@quicinc.com> + +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 SDM845 target. + +$ref: /schemas/display/msm/mdss-common.yaml# + +properties: + compatible: + items: + - const: qcom,sdm845-mdss + + clocks: + items: + - description: Display AHB clock from gcc + - description: Display core clock + + clock-names: + items: + - const: iface + - const: core + + iommus: + maxItems: 2 + + interconnects: + maxItems: 2 + + interconnect-names: + maxItems: 2 + +patternProperties: + "^display-controller@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,sdm845-dpu + + "^dsi@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,mdss-dsi-ctrl + + "^phy@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,dsi-phy-10nm + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,dispcc-sdm845.h> + #include <dt-bindings/clock/qcom,gcc-sdm845.h> + #include <dt-bindings/clock/qcom,rpmh.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-subsystem@ae00000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "qcom,sdm845-mdss"; + reg = <0x0ae00000 0x1000>; + reg-names = "mdss"; + power-domains = <&dispcc MDSS_GDSC>; + + clocks = <&gcc GCC_DISP_AHB_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>; + clock-names = "iface", "core"; + + interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <1>; + + iommus = <&apps_smmu 0x880 0x8>, + <&apps_smmu 0xc80 0x8>; + ranges; + + display-controller@ae01000 { + compatible = "qcom,sdm845-dpu"; + reg = <0x0ae01000 0x8f000>, + <0x0aeb0000 0x2008>; + reg-names = "mdp", "vbif"; + + clocks = <&gcc GCC_DISP_AXI_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_AXI_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>, + <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + clock-names = "gcc-bus", "iface", "bus", "core", "vsync"; + + interrupt-parent = <&mdss>; + interrupts = <0>; + power-domains = <&rpmhpd SDM845_CX>; + operating-points-v2 = <&mdp_opp_table>; + + 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>; + }; + }; + }; + }; + + dsi@ae94000 { + compatible = "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>, + <&dispcc DISP_CC_MDSS_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 SDM845_CX>; + + 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 { + }; + }; + }; + }; + + dsi0_phy: phy@ae94400 { + compatible = "qcom,dsi-phy-10nm"; + reg = <0x0ae94400 0x200>, + <0x0ae94600 0x280>, + <0x0ae94a00 0x1e0>; + 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,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>, + <&dispcc DISP_CC_MDSS_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 SDM845_CX>; + + 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-10nm"; + reg = <0x0ae96400 0x200>, + <0x0ae96600 0x280>, + <0x0ae96a00 0x10e>; + 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,sm6115-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm6115-dpu.yaml new file mode 100644 index 000000000000..4a39a3031409 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm6115-dpu.yaml @@ -0,0 +1,94 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,sm6115-dpu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Display DPU dt properties for SM6115 target + +maintainers: + - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> + +$ref: /schemas/display/msm/dpu-common.yaml# + +properties: + compatible: + items: + - const: qcom,sm6115-dpu + + reg: + items: + - description: MDP register set + - description: VBIF register set + + reg-names: + items: + - const: mdp + - const: vbif + + clocks: + items: + - description: Display AXI + - description: Display AHB + - description: Display core + - description: Display lut + - description: Display rotator + - description: Display vsync + + clock-names: + items: + - const: bus + - const: iface + - const: core + - const: lut + - const: rot + - const: vsync + +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,sm6115-dispcc.h> + #include <dt-bindings/clock/qcom,gcc-sm6115.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-controller@5e01000 { + compatible = "qcom,sm6115-dpu"; + reg = <0x05e01000 0x8f000>, + <0x05eb0000 0x2008>; + reg-names = "mdp", "vbif"; + + clocks = <&gcc GCC_DISP_HF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>, + <&dispcc DISP_CC_MDSS_MDP_LUT_CLK>, + <&dispcc DISP_CC_MDSS_ROT_CLK>, + <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + clock-names = "bus", "iface", "core", "lut", "rot", "vsync"; + + operating-points-v2 = <&mdp_opp_table>; + power-domains = <&rpmpd SM6115_VDDCX>; + + interrupt-parent = <&mdss>; + interrupts = <0>; + + 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,sm6115-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm6115-mdss.yaml new file mode 100644 index 000000000000..a86d7f53fa84 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm6115-mdss.yaml @@ -0,0 +1,182 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,sm6115-mdss.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM6115 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 and DSI. Device tree bindings of MDSS + are mentioned for SM6115 target. + +$ref: /schemas/display/msm/mdss-common.yaml# + +properties: + compatible: + items: + - const: qcom,sm6115-mdss + + clocks: + items: + - description: Display AHB clock from gcc + - description: Display AXI clock + - description: Display core clock + + iommus: + maxItems: 2 + +patternProperties: + "^display-controller@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,sm6115-dpu + + "^dsi@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,dsi-ctrl-6g-qcm2290 + + "^phy@[0-9a-f]+$": + type: object + properties: + compatible: + const: qcom,dsi-phy-14nm-2290 + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,sm6115-dispcc.h> + #include <dt-bindings/clock/qcom,gcc-sm6115.h> + #include <dt-bindings/clock/qcom,rpmcc.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + mdss@5e00000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "qcom,sm6115-mdss"; + reg = <0x05e00000 0x1000>; + reg-names = "mdss"; + power-domains = <&dispcc MDSS_GDSC>; + clocks = <&gcc GCC_DISP_AHB_CLK>, + <&gcc GCC_DISP_HF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>; + + interrupts = <GIC_SPI 186 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <1>; + + iommus = <&apps_smmu 0x420 0x2>, + <&apps_smmu 0x421 0x0>; + ranges; + + display-controller@5e01000 { + compatible = "qcom,sm6115-dpu"; + reg = <0x05e01000 0x8f000>, + <0x05eb0000 0x2008>; + reg-names = "mdp", "vbif"; + + clocks = <&gcc GCC_DISP_HF_AXI_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&dispcc DISP_CC_MDSS_MDP_CLK>, + <&dispcc DISP_CC_MDSS_MDP_LUT_CLK>, + <&dispcc DISP_CC_MDSS_ROT_CLK>, + <&dispcc DISP_CC_MDSS_VSYNC_CLK>; + clock-names = "bus", "iface", "core", "lut", "rot", "vsync"; + + operating-points-v2 = <&mdp_opp_table>; + power-domains = <&rpmpd SM6115_VDDCX>; + + interrupt-parent = <&mdss>; + interrupts = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dpu_intf1_out: endpoint { + remote-endpoint = <&dsi0_in>; + }; + }; + }; + }; + + dsi@5e94000 { + compatible = "qcom,dsi-ctrl-6g-qcm2290"; + reg = <0x05e94000 0x400>; + reg-names = "dsi_ctrl"; + + interrupt-parent = <&mdss>; + interrupts = <4>; + + clocks = <&dispcc DISP_CC_MDSS_BYTE0_CLK>, + <&dispcc DISP_CC_MDSS_BYTE0_INTF_CLK>, + <&dispcc DISP_CC_MDSS_PCLK0_CLK>, + <&dispcc DISP_CC_MDSS_ESC0_CLK>, + <&dispcc DISP_CC_MDSS_AHB_CLK>, + <&gcc GCC_DISP_HF_AXI_CLK>; + clock-names = "byte", + "byte_intf", + "pixel", + "core", + "iface", + "bus"; + assigned-clocks = <&dispcc DISP_CC_MDSS_BYTE0_CLK_SRC>, <&dispcc DISP_CC_MDSS_PCLK0_CLK_SRC>; + assigned-clock-parents = <&dsi0_phy 0>, <&dsi0_phy 1>; + + operating-points-v2 = <&dsi_opp_table>; + power-domains = <&rpmpd SM6115_VDDCX>; + phys = <&dsi0_phy>; + + #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 { + }; + }; + }; + }; + + dsi0_phy: phy@5e94400 { + compatible = "qcom,dsi-phy-14nm-2290"; + reg = <0x05e94400 0x100>, + <0x05e94500 0x300>, + <0x05e94800 0x188>; + reg-names = "dsi_phy", + "dsi_phy_lane", + "dsi_pll"; + + #clock-cells = <1>; + #phy-cells = <0>; + + clocks = <&dispcc DISP_CC_MDSS_AHB_CLK>, <&rpmcc RPM_SMD_XO_CLK_SRC>; + clock-names = "iface", "ref"; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8250-dpu.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8250-dpu.yaml new file mode 100644 index 000000000000..9ff8a265c85f --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8250-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,sm8250-dpu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM8250 Display DPU + +maintainers: + - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> + +$ref: /schemas/display/msm/dpu-common.yaml# + +properties: + compatible: + const: qcom,sm8250-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-sm8250.h> + #include <dt-bindings/clock/qcom,gcc-sm8250.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interconnect/qcom,sm8250.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-controller@ae01000 { + compatible = "qcom,sm8250-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 SM8250_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,sm8250-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8250-mdss.yaml new file mode 100644 index 000000000000..0d3be5386b3f --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8250-mdss.yaml @@ -0,0 +1,330 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/msm/qcom,sm8250-mdss.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM8250 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 SM8250 target. + +$ref: /schemas/display/msm/mdss-common.yaml# + +properties: + compatible: + items: + - const: qcom,sm8250-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,sm8250-dpu + + "^dsi@[0-9a-f]+$": + type: object + properties: + compatible: + 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-sm8250.h> + #include <dt-bindings/clock/qcom,gcc-sm8250.h> + #include <dt-bindings/clock/qcom,rpmh.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interconnect/qcom,sm8250.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + display-subsystem@ae00000 { + compatible = "qcom,sm8250-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 0x820 0x402>; + + #address-cells = <1>; + #size-cells = <1>; + ranges; + + display-controller@ae01000 { + compatible = "qcom,sm8250-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 SM8250_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-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>; + }; + }; + }; + + dsi@ae94000 { + compatible = "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 SM8250_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,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 SM8250_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/panel/ilitek,ili9163.yaml b/Documentation/devicetree/bindings/display/panel/ilitek,ili9163.yaml index 7e7a8362b951..a4154b51043e 100644 --- a/Documentation/devicetree/bindings/display/panel/ilitek,ili9163.yaml +++ b/Documentation/devicetree/bindings/display/panel/ilitek,ili9163.yaml @@ -15,6 +15,7 @@ description: allOf: - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: @@ -41,7 +42,7 @@ required: - dc-gpios - reset-gpios -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/display/panel/ilitek,ili9341.yaml b/Documentation/devicetree/bindings/display/panel/ilitek,ili9341.yaml index 99e0cb9440cf..94f169ea065a 100644 --- a/Documentation/devicetree/bindings/display/panel/ilitek,ili9341.yaml +++ b/Documentation/devicetree/bindings/display/panel/ilitek,ili9341.yaml @@ -16,6 +16,7 @@ description: | allOf: - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/display/panel/jadard,jd9365da-h3.yaml b/Documentation/devicetree/bindings/display/panel/jadard,jd9365da-h3.yaml new file mode 100644 index 000000000000..c06902e4fe70 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/jadard,jd9365da-h3.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/jadard,jd9365da-h3.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Jadard JD9365DA-HE WXGA DSI panel + +maintainers: + - Jagan Teki <jagan@edgeble.ai> + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + items: + - enum: + - chongzhou,cz101b4001 + - const: jadard,jd9365da-h3 + + reg: true + + vdd-supply: + description: supply regulator for VDD, usually 3.3V + + vccio-supply: + description: supply regulator for VCCIO, usually 1.8V + + reset-gpios: true + + backlight: true + + port: true + +required: + - compatible + - reg + - vdd-supply + - vccio-supply + - reset-gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/pinctrl/rockchip.h> + + dsi { + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "chongzhou,cz101b4001", "jadard,jd9365da-h3"; + reg = <0>; + vdd-supply = <&lcd_3v3>; + vccio-supply = <&vcca_1v8>; + reset-gpios = <&gpio1 RK_PC2 GPIO_ACTIVE_HIGH>; + backlight = <&backlight>; + + port { + mipi_in_panel: endpoint { + remote-endpoint = <&mipi_out_panel>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/nec,nl8048hl11.yaml b/Documentation/devicetree/bindings/display/panel/nec,nl8048hl11.yaml index aa788eaa2f71..3b09b359023e 100644 --- a/Documentation/devicetree/bindings/display/panel/nec,nl8048hl11.yaml +++ b/Documentation/devicetree/bindings/display/panel/nec,nl8048hl11.yaml @@ -15,6 +15,7 @@ maintainers: allOf: - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: @@ -34,7 +35,7 @@ required: - reset-gpios - port -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/display/panel/newvision,nv3051d.yaml b/Documentation/devicetree/bindings/display/panel/newvision,nv3051d.yaml new file mode 100644 index 000000000000..116c1b6030a2 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/newvision,nv3051d.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/newvision,nv3051d.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NewVision NV3051D based LCD panel + +description: | + The NewVision NV3051D is a driver chip used to drive DSI panels. For now, + this driver only supports the 640x480 panels found in the Anbernic RG353 + based devices. + +maintainers: + - Chris Morgan <macromorgan@hotmail.com> + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + items: + - enum: + - anbernic,rg353p-panel + - anbernic,rg353v-panel + - const: newvision,nv3051d + + reg: true + backlight: true + port: true + reset-gpios: + description: Active low reset GPIO + vdd-supply: true + +required: + - compatible + - reg + - backlight + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + dsi { + #address-cells = <1>; + #size-cells = <0>; + panel@0 { + compatible = "anbernic,rg353p-panel", "newvision,nv3051d"; + reg = <0>; + backlight = <&backlight>; + reset-gpios = <&gpio4 0 GPIO_ACTIVE_LOW>; + vdd-supply = <&vcc3v3_lcd>; + + port { + mipi_in_panel: endpoint { + remote-endpoint = <&mipi_out_panel>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/samsung,lms380kf01.yaml b/Documentation/devicetree/bindings/display/panel/samsung,lms380kf01.yaml index 251f0c7115aa..70ffc88d2a08 100644 --- a/Documentation/devicetree/bindings/display/panel/samsung,lms380kf01.yaml +++ b/Documentation/devicetree/bindings/display/panel/samsung,lms380kf01.yaml @@ -9,14 +9,13 @@ title: Samsung LMS380KF01 display panel description: The LMS380KF01 is a 480x800 DPI display panel from Samsung Mobile Displays (SMD) utilizing the WideChips WS2401 display controller. It can be used with internal or external backlight control. - The panel must obey the rules for a SPI slave device as specified in - spi/spi-controller.yaml maintainers: - Linus Walleij <linus.walleij@linaro.org> allOf: - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: @@ -59,7 +58,7 @@ required: - spi-cpol - port -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/display/panel/samsung,lms397kf04.yaml b/Documentation/devicetree/bindings/display/panel/samsung,lms397kf04.yaml index cd62968426fb..5e77cee93f83 100644 --- a/Documentation/devicetree/bindings/display/panel/samsung,lms397kf04.yaml +++ b/Documentation/devicetree/bindings/display/panel/samsung,lms397kf04.yaml @@ -14,6 +14,7 @@ maintainers: allOf: - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: @@ -51,7 +52,7 @@ required: - spi-cpol - port -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/display/panel/samsung,s6d27a1.yaml b/Documentation/devicetree/bindings/display/panel/samsung,s6d27a1.yaml index 26e3c820a2f7..d273faf4442a 100644 --- a/Documentation/devicetree/bindings/display/panel/samsung,s6d27a1.yaml +++ b/Documentation/devicetree/bindings/display/panel/samsung,s6d27a1.yaml @@ -7,14 +7,14 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Samsung S6D27A1 display panel description: The S6D27A1 is a 480x800 DPI display panel from Samsung Mobile - Displays (SMD). The panel must obey the rules for a SPI slave device - as specified in spi/spi-controller.yaml + Displays (SMD). maintainers: - Markuss Broks <markuss.broks@gmail.com> allOf: - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/display/panel/tpo,tpg110.yaml b/Documentation/devicetree/bindings/display/panel/tpo,tpg110.yaml index 6f1f02044b4b..f0243d196191 100644 --- a/Documentation/devicetree/bindings/display/panel/tpo,tpg110.yaml +++ b/Documentation/devicetree/bindings/display/panel/tpo,tpg110.yaml @@ -41,6 +41,7 @@ description: |+ allOf: - $ref: panel-common.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra124-dpaux.yaml b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra124-dpaux.yaml index 9ab123cd2325..5cdbc527a560 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra124-dpaux.yaml +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra124-dpaux.yaml @@ -128,7 +128,6 @@ examples: resets = <&tegra_car 181>; reset-names = "dpaux"; power-domains = <&pd_sor>; - status = "disabled"; state_dpaux_aux: pinmux-aux { groups = "dpaux-io"; diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra186-display.yaml b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra186-display.yaml index 8c0231345529..ce5c673f940c 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra186-display.yaml +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra186-display.yaml @@ -138,7 +138,6 @@ examples: <&bpmp TEGRA186_CLK_NVDISPLAY_DSC>, <&bpmp TEGRA186_CLK_NVDISPLAYHUB>; clock-names = "disp", "dsc", "hub"; - status = "disabled"; power-domains = <&bpmp TEGRA186_POWER_DOMAIN_DISP>; @@ -227,7 +226,6 @@ examples: clocks = <&bpmp TEGRA194_CLK_NVDISPLAY_DISP>, <&bpmp TEGRA194_CLK_NVDISPLAYHUB>; clock-names = "disp", "hub"; - status = "disabled"; power-domains = <&bpmp TEGRA194_POWER_DOMAIN_DISP>; diff --git a/Documentation/devicetree/bindings/display/xlnx/xlnx,zynqmp-dpsub.yaml b/Documentation/devicetree/bindings/display/xlnx/xlnx,zynqmp-dpsub.yaml index 10ec78ca1c65..554f9d5809d4 100644 --- a/Documentation/devicetree/bindings/display/xlnx/xlnx,zynqmp-dpsub.yaml +++ b/Documentation/devicetree/bindings/display/xlnx/xlnx,zynqmp-dpsub.yaml @@ -117,6 +117,45 @@ properties: - const: dp-phy0 - const: dp-phy1 + ports: + $ref: /schemas/graph.yaml#/properties/ports + description: | + Connections to the programmable logic and the DisplayPort PHYs. Each port + shall have a single endpoint. + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: The live video input from the programmable logic + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: The live graphics input from the programmable logic + + port@2: + $ref: /schemas/graph.yaml#/properties/port + description: The live audio input from the programmable logic + + port@3: + $ref: /schemas/graph.yaml#/properties/port + description: The blended video output to the programmable logic + + port@4: + $ref: /schemas/graph.yaml#/properties/port + description: The mixed audio output to the programmable logic + + port@5: + $ref: /schemas/graph.yaml#/properties/port + description: The DisplayPort output + + required: + - port@0 + - port@1 + - port@2 + - port@3 + - port@4 + - port@5 + required: - compatible - reg @@ -130,6 +169,7 @@ required: - dma-names - phys - phy-names + - ports additionalProperties: false @@ -164,6 +204,33 @@ examples: <&psgtr 0 PHY_TYPE_DP 1 3>; phy-names = "dp-phy0", "dp-phy1"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + }; + port@1 { + reg = <1>; + }; + port@2 { + reg = <2>; + }; + port@3 { + reg = <3>; + }; + port@4 { + reg = <4>; + }; + port@5 { + reg = <5>; + dpsub_dp_out: endpoint { + remote-endpoint = <&dp_connector>; + }; + }; + }; }; ... diff --git a/Documentation/devicetree/bindings/dma/apple,admac.yaml b/Documentation/devicetree/bindings/dma/apple,admac.yaml index 3b1e667f7ea0..97282469e4af 100644 --- a/Documentation/devicetree/bindings/dma/apple,admac.yaml +++ b/Documentation/devicetree/bindings/dma/apple,admac.yaml @@ -56,6 +56,9 @@ properties: power-domains: maxItems: 1 + resets: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/dma/snps,dw-axi-dmac.yaml b/Documentation/devicetree/bindings/dma/snps,dw-axi-dmac.yaml index 67aa7bb6d36a..ad107a4d3b33 100644 --- a/Documentation/devicetree/bindings/dma/snps,dw-axi-dmac.yaml +++ b/Documentation/devicetree/bindings/dma/snps,dw-axi-dmac.yaml @@ -8,7 +8,6 @@ title: Synopsys DesignWare AXI DMA Controller maintainers: - Eugeniy Paltsev <Eugeniy.Paltsev@synopsys.com> - - Jee Heng Sia <jee.heng.sia@intel.com> description: Synopsys DesignWare AXI DMA Controller DT Binding diff --git a/Documentation/devicetree/bindings/extcon/extcon-usbc-cros-ec.yaml b/Documentation/devicetree/bindings/extcon/extcon-usbc-cros-ec.yaml index 2d82b44268db..2e5b39881449 100644 --- a/Documentation/devicetree/bindings/extcon/extcon-usbc-cros-ec.yaml +++ b/Documentation/devicetree/bindings/extcon/extcon-usbc-cros-ec.yaml @@ -40,6 +40,7 @@ examples: cros-ec@0 { compatible = "google,cros-ec-spi"; reg = <0>; + interrupts = <44 0>; usbc_extcon0: extcon0 { compatible = "google,extcon-usbc-cros-ec"; diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.yaml b/Documentation/devicetree/bindings/firmware/qcom,scm.yaml index c5b76c9f7ad0..25688571ee7c 100644 --- a/Documentation/devicetree/bindings/firmware/qcom,scm.yaml +++ b/Documentation/devicetree/bindings/firmware/qcom,scm.yaml @@ -41,12 +41,14 @@ properties: - qcom,scm-sc7180 - qcom,scm-sc7280 - qcom,scm-sc8280xp + - qcom,scm-sdm670 - qcom,scm-sdm845 - qcom,scm-sdx55 - qcom,scm-sdx65 - qcom,scm-sm6115 - qcom,scm-sm6125 - qcom,scm-sm6350 + - qcom,scm-sm6375 - qcom,scm-sm8150 - qcom,scm-sm8250 - qcom,scm-sm8350 @@ -88,6 +90,7 @@ allOf: - qcom,scm-apq8064 - qcom,scm-msm8660 - qcom,scm-msm8960 + - qcom,scm-sm6375 then: properties: clock-names: diff --git a/Documentation/devicetree/bindings/gpio/gpio-davinci.yaml b/Documentation/devicetree/bindings/gpio/gpio-davinci.yaml index f32e09ef937c..10e56cf306db 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-davinci.yaml +++ b/Documentation/devicetree/bindings/gpio/gpio-davinci.yaml @@ -35,7 +35,7 @@ properties: gpio-line-names: description: strings describing the names of each gpio line. minItems: 1 - maxItems: 100 + maxItems: 144 "#gpio-cells": const: 2 diff --git a/Documentation/devicetree/bindings/gpio/gpio-latch.yaml b/Documentation/devicetree/bindings/gpio/gpio-latch.yaml new file mode 100644 index 000000000000..1ed82a2cebda --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-latch.yaml @@ -0,0 +1,94 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/gpio-latch.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: GPIO latch controller + +maintainers: + - Sascha Hauer <s.hauer@pengutronix.de> + +description: | + This binding describes a GPIO multiplexer based on latches connected to + other GPIOs, like this: + + CLK0 ----------------------. ,--------. + CLK1 -------------------. `--------|> #0 | + | | | + OUT0 ----------------+--|-----------|D0 Q0|-----|< + OUT1 --------------+-|--|-----------|D1 Q1|-----|< + OUT2 ------------+-|-|--|-----------|D2 Q2|-----|< + OUT3 ----------+-|-|-|--|-----------|D3 Q3|-----|< + OUT4 --------+-|-|-|-|--|-----------|D4 Q4|-----|< + OUT5 ------+-|-|-|-|-|--|-----------|D5 Q5|-----|< + OUT6 ----+-|-|-|-|-|-|--|-----------|D6 Q6|-----|< + OUT7 --+-|-|-|-|-|-|-|--|-----------|D7 Q7|-----|< + | | | | | | | | | `--------' + | | | | | | | | | + | | | | | | | | | ,--------. + | | | | | | | | `-----------|> #1 | + | | | | | | | | | | + | | | | | | | `--------------|D0 Q0|-----|< + | | | | | | `----------------|D1 Q1|-----|< + | | | | | `------------------|D2 Q2|-----|< + | | | | `--------------------|D3 Q3|-----|< + | | | `----------------------|D4 Q4|-----|< + | | `------------------------|D5 Q5|-----|< + | `--------------------------|D6 Q6|-----|< + `----------------------------|D7 Q7|-----|< + `--------' + + The number of clk-gpios and latched-gpios is not fixed. The actual number + of number of latches and the number of inputs per latch is derived from + the number of GPIOs given in the corresponding device tree properties. + +properties: + compatible: + const: gpio-latch + "#gpio-cells": + const: 2 + + clk-gpios: + description: Array of GPIOs to be used to clock a latch + + latched-gpios: + description: Array of GPIOs to be used as inputs per latch + + setup-duration-ns: + description: Delay in nanoseconds to wait after the latch inputs have been + set up + + clock-duration-ns: + description: Delay in nanoseconds to wait between clock output changes + + gpio-controller: true + + gpio-line-names: true + +required: + - compatible + - "#gpio-cells" + - gpio-controller + - clk-gpios + - latched-gpios + +additionalProperties: false + +examples: + - | + gpio-latch { + #gpio-cells = <2>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_di_do_leds>; + compatible = "gpio-latch"; + gpio-controller; + setup-duration-ns = <100>; + clock-duration-ns = <100>; + + clk-gpios = <&gpio3 7 0>, <&gpio3 8 0>; + latched-gpios = <&gpio3 21 0>, <&gpio3 22 0>, + <&gpio3 23 0>, <&gpio3 24 0>, + <&gpio3 25 0>, <&gpio3 26 0>, + <&gpio3 27 0>, <&gpio3 28 0>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml b/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml index 1acaa0a3d35a..48bf414aa50e 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml +++ b/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml @@ -12,6 +12,7 @@ maintainers: properties: compatible: enum: + - dlg,slg7xl45106 - nxp,pca9570 - nxp,pca9571 diff --git a/Documentation/devicetree/bindings/gpio/hisilicon,ascend910-gpio.yaml b/Documentation/devicetree/bindings/gpio/hisilicon,ascend910-gpio.yaml new file mode 100644 index 000000000000..735d97d645a0 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/hisilicon,ascend910-gpio.yaml @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/hisilicon,ascend910-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: HiSilicon common GPIO controller + +maintainers: + - Jay Fang <f.fangjian@huawei.com> + +description: + The HiSilicon common GPIO controller can be used for many different + types of SoC such as Huawei Ascend AI series chips. + +properties: + compatible: + const: hisilicon,ascend910-gpio + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + gpio-controller: true + + "#gpio-cells": + const: 2 + + ngpios: + minimum: 1 + maximum: 32 + +required: + - compatible + - reg + - interrupts + - gpio-controller + - "#gpio-cells" + - ngpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + gpio@840d0000 { + compatible = "hisilicon,ascend910-gpio"; + reg = <0x840d0000 0x1000>; + ngpios = <32>; + gpio-controller; + #gpio-cells = <2>; + interrupts = <GIC_SPI 33 IRQ_TYPE_LEVEL_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra234-nvdec.yaml b/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra234-nvdec.yaml new file mode 100644 index 000000000000..7cc2dd525a96 --- /dev/null +++ b/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra234-nvdec.yaml @@ -0,0 +1,156 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/gpu/host1x/nvidia,tegra234-nvdec.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Device tree binding for NVIDIA Tegra234 NVDEC + +description: | + NVDEC is the hardware video decoder present on NVIDIA Tegra210 + and newer chips. It is located on the Host1x bus and typically + programmed through Host1x channels. + +maintainers: + - Thierry Reding <treding@gmail.com> + - Mikko Perttunen <mperttunen@nvidia.com> + +properties: + $nodename: + pattern: "^nvdec@[0-9a-f]*$" + + compatible: + enum: + - nvidia,tegra234-nvdec + + reg: + maxItems: 1 + + clocks: + maxItems: 3 + + clock-names: + items: + - const: nvdec + - const: fuse + - const: tsec_pka + + resets: + maxItems: 1 + + reset-names: + items: + - const: nvdec + + power-domains: + maxItems: 1 + + iommus: + maxItems: 1 + + dma-coherent: true + + interconnects: + items: + - description: DMA read memory client + - description: DMA write memory client + + interconnect-names: + items: + - const: dma-mem + - const: write + + nvidia,memory-controller: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle to the memory controller for determining information for the NVDEC + firmware secure carveout. This carveout is configured by the bootloader and + not accessible to CPU. + + nvidia,bl-manifest-offset: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Offset to bootloader manifest from beginning of firmware that was configured by + the bootloader. + + nvidia,bl-code-offset: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Offset to bootloader code section from beginning of firmware that was configured by + the bootloader. + + nvidia,bl-data-offset: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Offset to bootloader data section from beginning of firmware that was configured by + the bootloader. + + nvidia,os-manifest-offset: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Offset to operating system manifest from beginning of firmware that was configured by + the bootloader. + + nvidia,os-code-offset: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Offset to operating system code section from beginning of firmware that was configured by + the bootloader. + + nvidia,os-data-offset: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Offset to operating system data section from beginning of firmware that was configured + by the bootloader. + +required: + - compatible + - reg + - clocks + - clock-names + - resets + - reset-names + - power-domains + - nvidia,memory-controller + - nvidia,bl-manifest-offset + - nvidia,bl-code-offset + - nvidia,bl-data-offset + - nvidia,os-manifest-offset + - nvidia,os-code-offset + - nvidia,os-data-offset + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/tegra234-clock.h> + #include <dt-bindings/memory/tegra234-mc.h> + #include <dt-bindings/power/tegra234-powergate.h> + #include <dt-bindings/reset/tegra234-reset.h> + + nvdec@15480000 { + compatible = "nvidia,tegra234-nvdec"; + reg = <0x15480000 0x00040000>; + clocks = <&bpmp TEGRA234_CLK_NVDEC>, + <&bpmp TEGRA234_CLK_FUSE>, + <&bpmp TEGRA234_CLK_TSEC_PKA>; + clock-names = "nvdec", "fuse", "tsec_pka"; + resets = <&bpmp TEGRA234_RESET_NVDEC>; + reset-names = "nvdec"; + power-domains = <&bpmp TEGRA234_POWER_DOMAIN_NVDEC>; + interconnects = <&mc TEGRA234_MEMORY_CLIENT_NVDECSRD &emc>, + <&mc TEGRA234_MEMORY_CLIENT_NVDECSWR &emc>; + interconnect-names = "dma-mem", "write"; + iommus = <&smmu_niso1 TEGRA234_SID_NVDEC>; + dma-coherent; + + nvidia,memory-controller = <&mc>; + + /* Placeholder values, to be replaced with values from overlay */ + nvidia,bl-manifest-offset = <0>; + nvidia,bl-data-offset = <0>; + nvidia,bl-code-offset = <0>; + nvidia,os-manifest-offset = <0>; + nvidia,os-data-offset = <0>; + nvidia,os-code-offset = <0>; + }; diff --git a/Documentation/devicetree/bindings/hwinfo/loongson,ls2k-chipid.yaml b/Documentation/devicetree/bindings/hwinfo/loongson,ls2k-chipid.yaml new file mode 100644 index 000000000000..9d0c36ec1982 --- /dev/null +++ b/Documentation/devicetree/bindings/hwinfo/loongson,ls2k-chipid.yaml @@ -0,0 +1,38 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/hwinfo/loongson,ls2k-chipid.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Loongson-2 SoC ChipID + +maintainers: + - Yinbo Zhu <zhuyinbo@loongson.cn> + +description: | + Loongson-2 SoC contains many groups of global utilities register + blocks, of which the ChipID group registers record SoC version, + feature, vendor and id information. + +properties: + compatible: + const: loongson,ls2k-chipid + + reg: + maxItems: 1 + + little-endian: true + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + chipid: chipid@1fe00000 { + compatible = "loongson,ls2k-chipid"; + reg = <0x1fe00000 0x3ffc>; + little-endian; + }; diff --git a/Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.yaml b/Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.yaml index 1c7149f7d171..ee2726149cf3 100644 --- a/Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.yaml +++ b/Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.yaml @@ -15,9 +15,22 @@ description: properties: compatible: - enum: - - qcom,sfpb-mutex - - qcom,tcsr-mutex + oneOf: + - enum: + - qcom,sfpb-mutex + - qcom,tcsr-mutex + - items: + - enum: + - qcom,apq8084-tcsr-mutex + - qcom,ipq6018-tcsr-mutex + - qcom,msm8226-tcsr-mutex + - qcom,msm8994-tcsr-mutex + - const: qcom,tcsr-mutex + - items: + - enum: + - qcom,msm8974-tcsr-mutex + - const: qcom,tcsr-mutex + - const: syscon reg: maxItems: 1 @@ -34,9 +47,9 @@ additionalProperties: false examples: - | - tcsr_mutex: hwlock@1f40000 { - compatible = "qcom,tcsr-mutex"; - reg = <0x01f40000 0x40000>; - #hwlock-cells = <1>; - }; + hwlock@1f40000 { + compatible = "qcom,tcsr-mutex"; + reg = <0x01f40000 0x40000>; + #hwlock-cells = <1>; + }; ... diff --git a/Documentation/devicetree/bindings/hwmon/adt7475.yaml b/Documentation/devicetree/bindings/hwmon/adt7475.yaml index ea595102a86e..051c976ab711 100644 --- a/Documentation/devicetree/bindings/hwmon/adt7475.yaml +++ b/Documentation/devicetree/bindings/hwmon/adt7475.yaml @@ -61,7 +61,7 @@ patternProperties: $ref: /schemas/types.yaml#/definitions/uint32 enum: [0, 1] - "adi,pin(5|10)-function": + "^adi,pin(5|10)-function$": description: | Configures the function for pin 5 on the adi,adt7473 and adi,adt7475. Or pin 10 on the adi,adt7476 and adi,adt7490. @@ -70,7 +70,7 @@ patternProperties: - pwm2 - smbalert# - "adi,pin(9|14)-function": + "^adi,pin(9|14)-function$": description: | Configures the function for pin 9 on the adi,adt7473 and adi,adt7475. Or pin 14 on the adi,adt7476 and adi,adt7490 diff --git a/Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml b/Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml index 6e1c70e9275e..cf523615f5e3 100644 --- a/Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml +++ b/Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml @@ -47,6 +47,7 @@ examples: compatible = "google,cros-ec-spi"; reg = <0>; spi-max-frequency = <5000000>; + interrupts = <99 0>; i2c-tunnel { compatible = "google,cros-ec-i2c-tunnel"; diff --git a/Documentation/devicetree/bindings/iio/adc/aspeed,ast2600-adc.yaml b/Documentation/devicetree/bindings/iio/adc/aspeed,ast2600-adc.yaml index b283c8ca2bbf..5c08d8b6e995 100644 --- a/Documentation/devicetree/bindings/iio/adc/aspeed,ast2600-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/aspeed,ast2600-adc.yaml @@ -62,13 +62,6 @@ properties: description: Inform the driver that last channel will be used to sensor battery. - aspeed,trim-data-valid: - type: boolean - description: | - The ADC reference voltage can be calibrated to obtain the trimming - data which will be stored in otp. This property informs the driver that - the data store in the otp is valid. - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml index 8bac0c4120dd..e94beb2255ba 100644 --- a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml @@ -238,42 +238,72 @@ additionalProperties: false examples: - | - spmi_bus { - #address-cells = <1>; - #size-cells = <0>; - /* VADC node */ - pmic_vadc: adc@3100 { - compatible = "qcom,spmi-vadc"; - reg = <0x3100>; - interrupts = <0x0 0x31 0x0 0x1>; + spmi { #address-cells = <1>; #size-cells = <0>; - #io-channel-cells = <1>; - - /* Channel node */ - adc-chan@39 { - reg = <0x39>; - qcom,decimation = <512>; - qcom,ratiometric; - qcom,hw-settle-time = <200>; - qcom,avg-samples = <1>; - qcom,pre-scaling = <1 3>; - }; - - adc-chan@9 { - reg = <0x9>; - }; - - adc-chan@a { - reg = <0xa>; + /* VADC node */ + pmic_vadc: adc@3100 { + compatible = "qcom,spmi-vadc"; + reg = <0x3100>; + interrupts = <0x0 0x31 0x0 0x1>; + #address-cells = <1>; + #size-cells = <0>; + #io-channel-cells = <1>; + + /* Channel node */ + adc-chan@39 { + reg = <0x39>; + qcom,decimation = <512>; + qcom,ratiometric; + qcom,hw-settle-time = <200>; + qcom,avg-samples = <1>; + qcom,pre-scaling = <1 3>; + }; + + adc-chan@9 { + reg = <0x9>; + }; + + adc-chan@a { + reg = <0xa>; + }; + + adc-chan@e { + reg = <0xe>; + }; + + adc-chan@f { + reg = <0xf>; + }; }; + }; - adc-chan@e { - reg = <0xe>; - }; + - | + #include <dt-bindings/iio/qcom,spmi-adc7-pmk8350.h> + #include <dt-bindings/iio/qcom,spmi-adc7-pm8350.h> + #include <dt-bindings/interrupt-controller/irq.h> - adc-chan@f { - reg = <0xf>; + spmi { + #address-cells = <1>; + #size-cells = <0>; + adc@3100 { + reg = <0x3100>; + compatible = "qcom,spmi-adc7"; + #address-cells = <1>; + #size-cells = <0>; + #io-channel-cells = <1>; + + /* Other properties are omitted */ + xo-therm@44 { + reg = <PMK8350_ADC7_AMUX_THM1_100K_PU>; + qcom,ratiometric; + qcom,hw-settle-time = <200>; + }; + + conn-therm@47 { + reg = <PM8350_ADC7_AMUX_THM4_100K_PU(1)>; + qcom,ratiometric; + qcom,hw-settle-time = <200>; + }; }; - }; }; diff --git a/Documentation/devicetree/bindings/iio/addac/adi,ad74413r.yaml b/Documentation/devicetree/bindings/iio/addac/adi,ad74413r.yaml index 03bb90a7f4f8..d2a9f92c0a6d 100644 --- a/Documentation/devicetree/bindings/iio/addac/adi,ad74413r.yaml +++ b/Documentation/devicetree/bindings/iio/addac/adi,ad74413r.yaml @@ -114,7 +114,6 @@ examples: #size-cells = <0>; cs-gpios = <&gpio 17 GPIO_ACTIVE_LOW>; - status = "okay"; ad74413r@0 { compatible = "adi,ad74413r"; diff --git a/Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml b/Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml index 5d631f7137e7..5efceb313879 100644 --- a/Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml +++ b/Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml @@ -16,7 +16,9 @@ properties: - const: allwinner,sun4i-a10-lradc-keys - const: allwinner,sun8i-a83t-r-lradc - items: - - const: allwinner,sun50i-a64-lradc + - enum: + - allwinner,suniv-f1c100s-lradc + - allwinner,sun50i-a64-lradc - const: allwinner,sun8i-a83t-r-lradc - const: allwinner,sun50i-r329-lradc - items: diff --git a/Documentation/devicetree/bindings/input/azoteq,iqs7222.yaml b/Documentation/devicetree/bindings/input/azoteq,iqs7222.yaml index 02e605fac408..9ddba7f2e7aa 100644 --- a/Documentation/devicetree/bindings/input/azoteq,iqs7222.yaml +++ b/Documentation/devicetree/bindings/input/azoteq,iqs7222.yaml @@ -473,9 +473,6 @@ patternProperties: Specifies whether the event is to be interpreted as a key (1) or a switch (5). - required: - - linux,code - additionalProperties: false dependencies: @@ -501,7 +498,7 @@ patternProperties: azoteq,slider-size: $ref: /schemas/types.yaml#/definitions/uint32 - minimum: 0 + minimum: 1 maximum: 65535 description: Specifies the slider's one-dimensional resolution, equal to the @@ -575,9 +572,9 @@ patternProperties: linux,code: true azoteq,gesture-max-ms: - multipleOf: 4 + multipleOf: 16 minimum: 0 - maximum: 1020 + maximum: 4080 description: Specifies the length of time (in ms) within which a tap, swipe or flick gesture must be completed in order to be acknowledged @@ -585,9 +582,9 @@ patternProperties: gesture applies to all remaining swipe or flick gestures. azoteq,gesture-min-ms: - multipleOf: 4 + multipleOf: 16 minimum: 0 - maximum: 124 + maximum: 496 description: Specifies the length of time (in ms) for which a tap gesture must be held in order to be acknowledged by the device. @@ -620,9 +617,6 @@ patternProperties: GPIO, they must all be of the same type (proximity, touch or slider gesture). - required: - - linux,code - additionalProperties: false required: @@ -693,6 +687,7 @@ allOf: properties: azoteq,slider-size: multipleOf: 16 + minimum: 16 maximum: 4080 azoteq,top-speed: @@ -935,14 +930,14 @@ examples: event-tap { linux,code = <KEY_PLAYPAUSE>; - azoteq,gesture-max-ms = <600>; - azoteq,gesture-min-ms = <24>; + azoteq,gesture-max-ms = <400>; + azoteq,gesture-min-ms = <32>; }; event-flick-pos { linux,code = <KEY_NEXTSONG>; - azoteq,gesture-max-ms = <600>; - azoteq,gesture-dist = <816>; + azoteq,gesture-max-ms = <800>; + azoteq,gesture-dist = <800>; }; event-flick-neg { diff --git a/Documentation/devicetree/bindings/input/goodix,gt7375p.yaml b/Documentation/devicetree/bindings/input/goodix,gt7375p.yaml index fe1c5016f7f3..1c191bc5a178 100644 --- a/Documentation/devicetree/bindings/input/goodix,gt7375p.yaml +++ b/Documentation/devicetree/bindings/input/goodix,gt7375p.yaml @@ -16,8 +16,11 @@ description: properties: compatible: - items: + oneOf: - const: goodix,gt7375p + - items: + - const: goodix,gt7986u + - const: goodix,gt7375p reg: enum: diff --git a/Documentation/devicetree/bindings/input/gpio-beeper.txt b/Documentation/devicetree/bindings/input/gpio-beeper.txt deleted file mode 100644 index a5086e37fce6..000000000000 --- a/Documentation/devicetree/bindings/input/gpio-beeper.txt +++ /dev/null @@ -1,13 +0,0 @@ -* GPIO beeper device tree bindings - -Register a beeper connected to GPIO pin. - -Required properties: -- compatible: Should be "gpio-beeper". -- gpios: From common gpio binding; gpio connection to beeper enable pin. - -Example: - beeper: beeper { - compatible = "gpio-beeper"; - gpios = <&gpio3 23 GPIO_ACTIVE_HIGH>; - }; diff --git a/Documentation/devicetree/bindings/input/gpio-beeper.yaml b/Documentation/devicetree/bindings/input/gpio-beeper.yaml new file mode 100644 index 000000000000..290372add3d5 --- /dev/null +++ b/Documentation/devicetree/bindings/input/gpio-beeper.yaml @@ -0,0 +1,33 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/gpio-beeper.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: GPIO controlled beeper + +maintainers: + - Fabio Estevam <festevam@denx.de> + +properties: + compatible: + const: gpio-beeper + + gpios: + maxItems: 1 + description: + GPIO that drives the beeper. + +required: + - compatible + - gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + beeper { + compatible = "gpio-beeper"; + gpios = <&gpio3 23 GPIO_ACTIVE_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/input/qcom,pm8921-pwrkey.yaml b/Documentation/devicetree/bindings/input/qcom,pm8921-pwrkey.yaml new file mode 100644 index 000000000000..12c74c083258 --- /dev/null +++ b/Documentation/devicetree/bindings/input/qcom,pm8921-pwrkey.yaml @@ -0,0 +1,75 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/qcom,pm8921-pwrkey.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm PM8921 PMIC Power Key + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + +allOf: + - $ref: input.yaml# + +properties: + compatible: + oneOf: + - enum: + - qcom,pm8921-pwrkey + - qcom,pm8058-pwrkey + - items: + - enum: + - qcom,pm8018-pwrkey + - const: qcom,pm8921-pwrkey + + reg: + maxItems: 1 + + interrupts: + items: + - description: key release + - description: key press + + debounce: + description: + Time in microseconds that key must be pressed or + released for state change interrupt to trigger. + $ref: /schemas/types.yaml#/definitions/uint32 + + pull-up: + description: + Presence of this property indicates that the KPDPWR_N + pin should be configured for pull up. + $ref: /schemas/types.yaml#/definitions/flag + +required: + - compatible + - reg + - interrupts + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + ssbi { + #address-cells = <1>; + #size-cells = <0>; + + pmic@0 { + reg = <0x0>; + #address-cells = <1>; + #size-cells = <0>; + + pwrkey@1c { + compatible = "qcom,pm8921-pwrkey"; + reg = <0x1c>; + interrupt-parent = <&pmicint>; + interrupts = <50 IRQ_TYPE_EDGE_RISING>, <51 IRQ_TYPE_EDGE_RISING>; + debounce = <15625>; + pull-up; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/input/qcom,pm8xxx-pwrkey.txt b/Documentation/devicetree/bindings/input/qcom,pm8xxx-pwrkey.txt deleted file mode 100644 index 588536cc96ed..000000000000 --- a/Documentation/devicetree/bindings/input/qcom,pm8xxx-pwrkey.txt +++ /dev/null @@ -1,46 +0,0 @@ -Qualcomm PM8xxx PMIC Power Key - -PROPERTIES - -- compatible: - Usage: required - Value type: <string> - Definition: must be one of: - "qcom,pm8058-pwrkey" - "qcom,pm8921-pwrkey" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: address of power key control register - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: the first interrupt specifies the key release interrupt - and the second interrupt specifies the key press interrupt. - The format of the specifier is defined by the binding - document describing the node's interrupt parent. - -- debounce: - Usage: optional - Value type: <u32> - Definition: time in microseconds that key must be pressed or release - for state change interrupt to trigger. - -- pull-up: - Usage: optional - Value type: <empty> - Definition: presence of this property indicates that the KPDPWR_N pin - should be configured for pull up. - -EXAMPLE - - pwrkey@1c { - compatible = "qcom,pm8921-pwrkey"; - reg = <0x1c>; - interrupt-parent = <&pmicintc>; - interrupts = <50 1>, <51 1>; - debounce = <15625>; - pull-up; - }; diff --git a/Documentation/devicetree/bindings/input/ti,drv260x.txt b/Documentation/devicetree/bindings/input/ti,drv260x.txt deleted file mode 100644 index 4c5312eaaa85..000000000000 --- a/Documentation/devicetree/bindings/input/ti,drv260x.txt +++ /dev/null @@ -1,50 +0,0 @@ -* Texas Instruments - drv260x Haptics driver family - -Required properties: - - compatible - One of: - "ti,drv2604" - DRV2604 - "ti,drv2605" - DRV2605 - "ti,drv2605l" - DRV2605L - - reg - I2C slave address - - vbat-supply - Required supply regulator - - mode - Power up mode of the chip (defined in include/dt-bindings/input/ti-drv260x.h) - DRV260X_LRA_MODE - Linear Resonance Actuator mode (Piezoelectric) - DRV260X_LRA_NO_CAL_MODE - This is a LRA Mode but there is no calibration - sequence during init. And the device is configured for real - time playback mode (RTP mode). - DRV260X_ERM_MODE - Eccentric Rotating Mass mode (Rotary vibrator) - - library-sel - These are ROM based waveforms pre-programmed into the IC. - This should be set to set the library to use at power up. - (defined in include/dt-bindings/input/ti-drv260x.h) - DRV260X_LIB_EMPTY - Do not use a pre-programmed library - DRV260X_ERM_LIB_A - Pre-programmed Library - DRV260X_ERM_LIB_B - Pre-programmed Library - DRV260X_ERM_LIB_C - Pre-programmed Library - DRV260X_ERM_LIB_D - Pre-programmed Library - DRV260X_ERM_LIB_E - Pre-programmed Library - DRV260X_ERM_LIB_F - Pre-programmed Library - DRV260X_LIB_LRA - Pre-programmed LRA Library - -Optional properties: - - enable-gpio - gpio pin to enable/disable the device. - - vib-rated-mv - The rated voltage of the actuator in millivolts. - If this is not set then the value will be defaulted to - 3.2 v. - - vib-overdrive-mv - The overdrive voltage of the actuator in millivolts. - If this is not set then the value will be defaulted to - 3.2 v. -Example: - -haptics: haptics@5a { - compatible = "ti,drv2605l"; - reg = <0x5a>; - vbat-supply = <&vbat>; - enable-gpio = <&gpio1 28 GPIO_ACTIVE_HIGH>; - mode = <DRV260X_LRA_MODE>; - library-sel = <DRV260X_LIB_LRA>; - vib-rated-mv = <3200>; - vib-overdrive-mv = <3200>; -} - -For more product information please see the link below: -http://www.ti.com/product/drv2605 diff --git a/Documentation/devicetree/bindings/input/ti,drv260x.yaml b/Documentation/devicetree/bindings/input/ti,drv260x.yaml new file mode 100644 index 000000000000..c6245c5b9e2e --- /dev/null +++ b/Documentation/devicetree/bindings/input/ti,drv260x.yaml @@ -0,0 +1,109 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/ti,drv260x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments - drv260x Haptics driver family + +maintainers: + - Andrew Davis <afd@ti.com> + +properties: + compatible: + enum: + - ti,drv2604 + - ti,drv2605 + - ti,drv2605l + + reg: + maxItems: 1 + + vbat-supply: + description: Power supply to the haptic motor + + # TODO: Deprecate 'mode' in favor of differently named property + mode: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Power up mode of the chip + (defined in include/dt-bindings/input/ti-drv260x.h) + + DRV260X_LRA_MODE + Linear Resonance Actuator mode (Piezoelectric) + + DRV260X_LRA_NO_CAL_MODE + This is a LRA Mode but there is no calibration sequence during init. + And the device is configured for real time playback mode (RTP mode). + + DRV260X_ERM_MODE + Eccentric Rotating Mass mode (Rotary vibrator) + enum: [ 0, 1, 2 ] + + library-sel: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + These are ROM based waveforms pre-programmed into the IC. + This should be set to set the library to use at power up. + (defined in include/dt-bindings/input/ti-drv260x.h) + + DRV260X_LIB_EMPTY - Do not use a pre-programmed library + DRV260X_ERM_LIB_A - Pre-programmed Library + DRV260X_ERM_LIB_B - Pre-programmed Library + DRV260X_ERM_LIB_C - Pre-programmed Library + DRV260X_ERM_LIB_D - Pre-programmed Library + DRV260X_ERM_LIB_E - Pre-programmed Library + DRV260X_ERM_LIB_F - Pre-programmed Library + DRV260X_LIB_LRA - Pre-programmed LRA Library + enum: [ 0, 1, 2, 3, 4, 5, 6, 7 ] + + enable-gpio: + maxItems: 1 + deprecated: true + + enable-gpios: + maxItems: 1 + + vib-rated-mv: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + The rated voltage of the actuator in millivolts. + If this is not set then the value will be defaulted to 3200 mV. + default: 3200 + + vib-overdrive-mv: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + The overdrive voltage of the actuator in millivolts. + If this is not set then the value will be defaulted to 3200 mV. + default: 3200 + +required: + - compatible + - reg + - enable-gpios + - mode + - library-sel + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/input/ti-drv260x.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + haptics@5a { + compatible = "ti,drv2605l"; + reg = <0x5a>; + vbat-supply = <&vbat>; + enable-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>; + mode = <DRV260X_LRA_MODE>; + library-sel = <DRV260X_LIB_LRA>; + vib-rated-mv = <3200>; + vib-overdrive-mv = <3200>; + }; + }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/cypress,tt21000.yaml b/Documentation/devicetree/bindings/input/touchscreen/cypress,tt21000.yaml new file mode 100644 index 000000000000..1959ec394768 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/cypress,tt21000.yaml @@ -0,0 +1,106 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/touchscreen/cypress,tt21000.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cypress TT21000 touchscreen controller + +description: The Cypress TT21000 series (also known as "CYTTSP5" after + the marketing name Cypress TrueTouch Standard Product series 5). + +maintainers: + - Alistair Francis <alistair@alistair23.me> + +allOf: + - $ref: touchscreen.yaml# + +properties: + compatible: + const: cypress,tt21000 + + reg: + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + interrupts: + maxItems: 1 + + vdd-supply: + description: Regulator for voltage. + + reset-gpios: + maxItems: 1 + + linux,keycodes: + description: EV_ABS specific event code generated by the axis. + +patternProperties: + "^button@[0-9]+$": + type: object + $ref: ../input.yaml# + properties: + reg: + maxItems: 1 + linux,keycodes: + description: Keycode to emit + + required: + - reg + - linux,keycodes + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - vdd-supply + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/input/linux-event-codes.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + touchscreen@24 { + #address-cells = <1>; + #size-cells = <0>; + + compatible = "cypress,tt21000"; + reg = <0x24>; + pinctrl-names = "default"; + pinctrl-0 = <&tp_reset_ds203>; + interrupt-parent = <&pio>; + interrupts = <1 5 IRQ_TYPE_LEVEL_LOW>; + reset-gpios = <&pio 7 1 GPIO_ACTIVE_LOW>; + vdd-supply = <®_touch>; + + button@0 { + reg = <0>; + linux,keycodes = <KEY_HOMEPAGE>; + }; + + button@1 { + reg = <1>; + linux,keycodes = <KEY_MENU>; + }; + + button@2 { + reg = <2>; + linux,keycodes = <KEY_BACK>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/input/touchscreen/egalax-ts.txt b/Documentation/devicetree/bindings/input/touchscreen/egalax-ts.txt index 92fb2620f5e2..ebbe93810574 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/egalax-ts.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/egalax-ts.txt @@ -13,6 +13,6 @@ Example: compatible = "eeti,egalax_ts"; reg = <0x04>; interrupt-parent = <&gpio1>; - interrupts = <9 2>; - wakeup-gpios = <&gpio1 9 0>; + interrupts = <9 IRQ_TYPE_LEVEL_LOW>; + wakeup-gpios = <&gpio1 9 GPIO_ACTIVE_LOW>; }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/himax,hx83112b.yaml b/Documentation/devicetree/bindings/input/touchscreen/himax,hx83112b.yaml new file mode 100644 index 000000000000..be2ba185c086 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/himax,hx83112b.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/touchscreen/himax,hx83112b.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Himax hx83112b touchscreen controller bindings + +maintainers: + - Job Noorman <job@noorman.info> + +allOf: + - $ref: touchscreen.yaml# + +properties: + compatible: + enum: + - himax,hx83112b + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + reset-gpios: + maxItems: 1 + + touchscreen-inverted-x: true + touchscreen-inverted-y: true + touchscreen-size-x: true + touchscreen-size-y: true + touchscreen-swapped-x-y: true + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + - reset-gpios + - touchscreen-size-x + - touchscreen-size-y + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/gpio/gpio.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + touchscreen@48 { + compatible = "himax,hx83112b"; + reg = <0x48>; + interrupt-parent = <&tlmm>; + interrupts = <65 IRQ_TYPE_LEVEL_LOW>; + touchscreen-size-x = <1080>; + touchscreen-size-y = <2160>; + reset-gpios = <&tlmm 64 GPIO_ACTIVE_LOW>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/input/touchscreen/hynitron,cstxxx.yaml b/Documentation/devicetree/bindings/input/touchscreen/hynitron,cstxxx.yaml new file mode 100644 index 000000000000..9cb5d4af00f7 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/hynitron,cstxxx.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/touchscreen/hynitron,cstxxx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Hynitron cstxxx series touchscreen controller + +description: | + Bindings for Hynitron cstxxx series multi-touch touchscreen + controllers. + +maintainers: + - Chris Morgan <macromorgan@hotmail.com> + +allOf: + - $ref: touchscreen.yaml# + +properties: + compatible: + enum: + - hynitron,cst340 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + reset-gpios: + maxItems: 1 + + touchscreen-size-x: true + touchscreen-size-y: true + touchscreen-inverted-x: true + touchscreen-inverted-y: true + touchscreen-swapped-x-y: true + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + - reset-gpios + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + touchscreen@1a { + compatible = "hynitron,cst340"; + reg = <0x1a>; + interrupt-parent = <&gpio4>; + interrupts = <9 IRQ_TYPE_EDGE_FALLING>; + reset-gpios = <&gpio4 6 GPIO_ACTIVE_LOW>; + touchscreen-size-x = <640>; + touchscreen-size-y = <480>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/input/touchscreen/mstar,msg2638.yaml b/Documentation/devicetree/bindings/input/touchscreen/mstar,msg2638.yaml index 3a42c23faf6f..af4f954de958 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/mstar,msg2638.yaml +++ b/Documentation/devicetree/bindings/input/touchscreen/mstar,msg2638.yaml @@ -14,7 +14,9 @@ allOf: properties: compatible: - const: mstar,msg2638 + enum: + - mstar,msg2138 + - mstar,msg2638 reg: const: 0x26 @@ -34,6 +36,10 @@ properties: touchscreen-size-x: true touchscreen-size-y: true + linux,keycodes: + minItems: 1 + maxItems: 4 + additionalProperties: false required: diff --git a/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml b/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml index 2684562df4d9..be29e0b80995 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml @@ -24,7 +24,7 @@ properties: oneOf: - items: - enum: - - qcom,sc7280-bwmon + - qcom,sc7280-cpu-bwmon - qcom,sdm845-bwmon - const: qcom,msm8998-bwmon - const: qcom,msm8998-bwmon # BWMON v4 diff --git a/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml b/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml index e18107eafe7c..698588e9aa86 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml @@ -90,7 +90,6 @@ properties: maximum: 5 cpus: - $ref: /schemas/types.yaml#/definitions/phandle-array description: Should be a list of phandles to CPU nodes (as described in Documentation/devicetree/bindings/arm/cpus.yaml). diff --git a/Documentation/devicetree/bindings/interrupt-controller/apple,aic2.yaml b/Documentation/devicetree/bindings/interrupt-controller/apple,aic2.yaml index 47a78a167aba..06948c0e36a5 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/apple,aic2.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/apple,aic2.yaml @@ -69,6 +69,35 @@ properties: power-domains: maxItems: 1 + affinities: + type: object + additionalProperties: false + description: + FIQ affinity can be expressed as a single "affinities" node, + containing a set of sub-nodes, one per FIQ with a non-default + affinity. + patternProperties: + "^.+-affinity$": + type: object + additionalProperties: false + properties: + apple,fiq-index: + description: + The interrupt number specified as a FIQ, and for which + the affinity is not the default. + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 5 + + cpus: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + Should be a list of phandles to CPU nodes (as described in + Documentation/devicetree/bindings/arm/cpus.yaml). + + required: + - apple,fiq-index + - cpus + required: - compatible - '#interrupt-cells' diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,intmux.yaml b/Documentation/devicetree/bindings/interrupt-controller/fsl,intmux.yaml index 1d6e0f64a807..985bfa4f6fda 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/fsl,intmux.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/fsl,intmux.yaml @@ -7,7 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Freescale INTMUX interrupt multiplexer maintainers: - - Joakim Zhang <qiangqing.zhang@nxp.com> + - Shawn Guo <shawnguo@kernel.org> + - NXP Linux Team <linux-imx@nxp.com> properties: compatible: diff --git a/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-ioapic.txt b/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-ioapic.txt deleted file mode 100644 index 7d19f494f19a..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-ioapic.txt +++ /dev/null @@ -1,26 +0,0 @@ -Interrupt chips ---------------- - -* Intel I/O Advanced Programmable Interrupt Controller (IO APIC) - - Required properties: - -------------------- - compatible = "intel,ce4100-ioapic"; - #interrupt-cells = <2>; - - Device's interrupt property: - - interrupts = <P S>; - - The first number (P) represents the interrupt pin which is wired to the - IO APIC. The second number (S) represents the sense of interrupt which - should be configured and can be one of: - 0 - Edge Rising - 1 - Level Low - 2 - Level High - 3 - Edge Falling - -* Local APIC - Required property: - - compatible = "intel,ce4100-lapic"; diff --git a/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-ioapic.yaml b/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-ioapic.yaml new file mode 100644 index 000000000000..39ab8cdd19b4 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-ioapic.yaml @@ -0,0 +1,60 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/interrupt-controller/intel,ce4100-ioapic.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Intel I/O Advanced Programmable Interrupt Controller (IO APIC) + +maintainers: + - Rahul Tanwar <rtanwar@maxlinear.com> + +description: | + Intel's Advanced Programmable Interrupt Controller (APIC) is a + family of interrupt controllers. The APIC is a split + architecture design, with a local component (LAPIC) integrated + into the processor itself and an external I/O APIC. Local APIC + (lapic) receives interrupts from the processor's interrupt pins, + from internal sources and from an external I/O APIC (ioapic). + And it sends these to the processor core for handling. + See [1] Chapter 8 for more details. + + Many of the Intel's generic devices like hpet, ioapic, lapic have + the ce4100 name in their compatible property names because they + first appeared in CE4100 SoC. + + This schema defines bindings for I/O APIC interrupt controller. + + [1] https://pdos.csail.mit.edu/6.828/2008/readings/ia32/IA32-3A.pdf + +properties: + compatible: + const: intel,ce4100-ioapic + + reg: + maxItems: 1 + + interrupt-controller: true + + '#interrupt-cells': + const: 2 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupt-controller + - '#interrupt-cells' + +additionalProperties: false + +examples: + - | + ioapic1: interrupt-controller@fec00000 { + compatible = "intel,ce4100-ioapic"; + reg = <0xfec00000 0x1000>; + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-lapic.yaml b/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-lapic.yaml new file mode 100644 index 000000000000..d2d0145cb889 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-lapic.yaml @@ -0,0 +1,71 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/interrupt-controller/intel,ce4100-lapic.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Intel Local Advanced Programmable Interrupt Controller (LAPIC) + +maintainers: + - Rahul Tanwar <rtanwar@maxlinear.com> + +description: | + Intel's Advanced Programmable Interrupt Controller (APIC) is a + family of interrupt controllers. The APIC is a split + architecture design, with a local component (LAPIC) integrated + into the processor itself and an external I/O APIC. Local APIC + (lapic) receives interrupts from the processor's interrupt pins, + from internal sources and from an external I/O APIC (ioapic). + And it sends these to the processor core for handling. + See [1] Chapter 8 for more details. + + Many of the Intel's generic devices like hpet, ioapic, lapic have + the ce4100 name in their compatible property names because they + first appeared in CE4100 SoC. + + This schema defines bindings for local APIC interrupt controller. + + [1] https://pdos.csail.mit.edu/6.828/2008/readings/ia32/IA32-3A.pdf + +properties: + compatible: + const: intel,ce4100-lapic + + reg: + maxItems: 1 + + interrupt-controller: true + + '#interrupt-cells': + const: 2 + + intel,virtual-wire-mode: + description: Intel defines a few possible interrupt delivery + modes. With respect to boot/init time, mainly two interrupt + delivery modes are possible. + PIC Mode - Legacy external 8259 compliant PIC interrupt controller. + Virtual Wire Mode - use lapic as virtual wire interrupt delivery mode. + For ACPI or MPS spec compliant systems, it is figured out by some read + only bit field/s available in their respective defined data structures. + For OF based systems, it is by default set to PIC mode. + But if this optional boolean property is set, then the interrupt delivery + mode is configured to virtual wire compatibility mode. + type: boolean + +required: + - compatible + - reg + - interrupt-controller + - '#interrupt-cells' + +additionalProperties: false + +examples: + - | + lapic0: interrupt-controller@fee00000 { + compatible = "intel,ce4100-lapic"; + reg = <0xfee00000 0x1000>; + interrupt-controller; + #interrupt-cells = <2>; + intel,virtual-wire-mode; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongarch,cpu-interrupt-controller.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongarch,cpu-interrupt-controller.yaml new file mode 100644 index 000000000000..2a1cf885c99d --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/loongarch,cpu-interrupt-controller.yaml @@ -0,0 +1,34 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/loongarch,cpu-interrupt-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: LoongArch CPU Interrupt Controller + +maintainers: + - Liu Peibao <liupeibao@loongson.cn> + +properties: + compatible: + const: loongarch,cpu-interrupt-controller + + '#interrupt-cells': + const: 1 + + interrupt-controller: true + +additionalProperties: false + +required: + - compatible + - '#interrupt-cells' + - interrupt-controller + +examples: + - | + interrupt-controller { + compatible = "loongarch,cpu-interrupt-controller"; + #interrupt-cells = <1>; + interrupt-controller; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/mediatek,cirq.txt b/Documentation/devicetree/bindings/interrupt-controller/mediatek,cirq.txt deleted file mode 100644 index 5865f4f2c69d..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/mediatek,cirq.txt +++ /dev/null @@ -1,33 +0,0 @@ -* Mediatek 27xx cirq - -In Mediatek SOCs, the CIRQ is a low power interrupt controller designed to -work outside MCUSYS which comprises with Cortex-Ax cores,CCI and GIC. -The external interrupts (outside MCUSYS) will feed through CIRQ and connect -to GIC in MCUSYS. When CIRQ is enabled, it will record the edge-sensitive -interrupts and generate a pulse signal to parent interrupt controller when -flush command is executed. With CIRQ, MCUSYS can be completely turned off -to improve the system power consumption without losing interrupts. - -Required properties: -- compatible: should be one of - - "mediatek,mt2701-cirq" for mt2701 CIRQ - - "mediatek,mt8135-cirq" for mt8135 CIRQ - - "mediatek,mt8173-cirq" for mt8173 CIRQ - and "mediatek,cirq" as a fallback. -- interrupt-controller : Identifies the node as an interrupt controller. -- #interrupt-cells : Use the same format as specified by GIC in arm,gic.txt. -- reg: Physical base address of the cirq registers and length of memory - mapped region. -- mediatek,ext-irq-range: Identifies external irq number range in different - SOCs. - -Example: - cirq: interrupt-controller@10204000 { - compatible = "mediatek,mt2701-cirq", - "mediatek,mtk-cirq"; - interrupt-controller; - #interrupt-cells = <3>; - interrupt-parent = <&sysirq>; - reg = <0 0x10204000 0 0x400>; - mediatek,ext-irq-start = <32 200>; - }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/mediatek,mtk-cirq.yaml b/Documentation/devicetree/bindings/interrupt-controller/mediatek,mtk-cirq.yaml new file mode 100644 index 000000000000..fdcb4d8db818 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/mediatek,mtk-cirq.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/mediatek,mtk-cirq.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek System Interrupt Controller + +maintainers: + - Youlin Pei <youlin.pei@mediatek.com> + +description: + In MediaTek SoCs, the CIRQ is a low power interrupt controller designed to + work outside of MCUSYS which comprises with Cortex-Ax cores, CCI and GIC. + The external interrupts (outside MCUSYS) will feed through CIRQ and connect + to GIC in MCUSYS. When CIRQ is enabled, it will record the edge-sensitive + interrupts and generate a pulse signal to parent interrupt controller when + flush command is executed. With CIRQ, MCUSYS can be completely turned off + to improve the system power consumption without losing interrupts. + + +properties: + compatible: + items: + - enum: + - mediatek,mt2701-cirq + - mediatek,mt8135-cirq + - mediatek,mt8173-cirq + - mediatek,mt8192-cirq + - const: mediatek,mtk-cirq + + reg: + maxItems: 1 + + '#interrupt-cells': + const: 3 + + interrupt-controller: true + + mediatek,ext-irq-range: + $ref: /schemas/types.yaml#/definitions/uint32-array + items: + - description: First CIRQ interrupt + - description: Last CIRQ interrupt + description: + Identifies the range of external interrupts in different SoCs + +required: + - compatible + - reg + - '#interrupt-cells' + - interrupt-controller + - mediatek,ext-irq-range + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + cirq: interrupt-controller@10204000 { + compatible = "mediatek,mt2701-cirq", "mediatek,mtk-cirq"; + reg = <0x10204000 0x400>; + #interrupt-cells = <3>; + interrupt-controller; + interrupt-parent = <&sysirq>; + mediatek,ext-irq-range = <32 200>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.yaml b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.yaml index b6f56cf5fbe3..94791e261c42 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.yaml @@ -28,11 +28,15 @@ properties: - enum: - qcom,sc7180-pdc - qcom,sc7280-pdc + - qcom,sc8280xp-pdc - qcom,sdm845-pdc + - qcom,sdx55-pdc + - qcom,sdx65-pdc - qcom,sm6350-pdc - qcom,sm8150-pdc - qcom,sm8250-pdc - qcom,sm8350-pdc + - qcom,sm8450-pdc - const: qcom,pdc reg: diff --git a/Documentation/devicetree/bindings/iommu/apple,dart.yaml b/Documentation/devicetree/bindings/iommu/apple,dart.yaml index 82ad669feef7..06af2bacbe97 100644 --- a/Documentation/devicetree/bindings/iommu/apple,dart.yaml +++ b/Documentation/devicetree/bindings/iommu/apple,dart.yaml @@ -22,7 +22,9 @@ description: |+ properties: compatible: - const: apple,t8103-dart + enum: + - apple,t8103-dart + - apple,t6000-dart reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml index 8854569ca3a6..26d0a5121f02 100644 --- a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml +++ b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml @@ -29,6 +29,7 @@ properties: - renesas,ipmmu-r8a7793 # R-Car M2-N - renesas,ipmmu-r8a7794 # R-Car E2 - const: renesas,ipmmu-vmsa # R-Mobile APE6 or R-Car Gen2 or RZ/G1 + - items: - enum: - renesas,ipmmu-r8a774a1 # RZ/G2M @@ -43,10 +44,11 @@ properties: - renesas,ipmmu-r8a77980 # R-Car V3H - renesas,ipmmu-r8a77990 # R-Car E3 - renesas,ipmmu-r8a77995 # R-Car D3 - - renesas,ipmmu-r8a779a0 # R-Car V3U + - items: - enum: - - renesas,ipmmu-r8a779f0 # R-Car S4-8 + - renesas,ipmmu-r8a779a0 # R-Car V3U + - renesas,ipmmu-r8a779f0 # R-Car S4-8 - const: renesas,rcar-gen4-ipmmu-vmsa # R-Car Gen4 reg: diff --git a/Documentation/devicetree/bindings/ipmi/ssif-bmc.yaml b/Documentation/devicetree/bindings/ipmi/ssif-bmc.yaml new file mode 100644 index 000000000000..02b662d780bb --- /dev/null +++ b/Documentation/devicetree/bindings/ipmi/ssif-bmc.yaml @@ -0,0 +1,38 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/ipmi/ssif-bmc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: SSIF IPMI BMC interface + +description: SSIF IPMI BMC device bindings + +maintainers: + - Quan Nguyen <quan@os.amperecomputing.com> + +properties: + compatible: + enum: + - ssif-bmc + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + ssif-bmc@10 { + compatible = "ssif-bmc"; + reg = <0x10>; + }; + }; diff --git a/Documentation/devicetree/bindings/leds/irled/gpio-ir-tx.txt b/Documentation/devicetree/bindings/leds/irled/gpio-ir-tx.txt deleted file mode 100644 index cbe8dfd29715..000000000000 --- a/Documentation/devicetree/bindings/leds/irled/gpio-ir-tx.txt +++ /dev/null @@ -1,14 +0,0 @@ -Device tree bindings for IR LED connected through gpio pin which is used as -remote controller transmitter. - -Required properties: - - compatible: should be "gpio-ir-tx". - - gpios : Should specify the IR LED GPIO, see "gpios property" in - Documentation/devicetree/bindings/gpio/gpio.txt. Active low LEDs - should be indicated using flags in the GPIO specifier. - -Example: - irled@0 { - compatible = "gpio-ir-tx"; - gpios = <&gpio1 2 GPIO_ACTIVE_HIGH>; - }; diff --git a/Documentation/devicetree/bindings/leds/irled/gpio-ir-tx.yaml b/Documentation/devicetree/bindings/leds/irled/gpio-ir-tx.yaml new file mode 100644 index 000000000000..5839d00c7089 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/irled/gpio-ir-tx.yaml @@ -0,0 +1,36 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/irled/gpio-ir-tx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: IR LED connected through GPIO pin + +maintainers: + - Sean Young <sean@mess.org> + +description: + IR LED connected through GPIO pin which is used as remote controller + transmitter. + +properties: + compatible: + const: gpio-ir-tx + + gpios: + maxItems: 1 + +required: + - compatible + - gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + irled { + compatible = "gpio-ir-tx"; + gpios = <&gpio1 2 GPIO_ACTIVE_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/leds/irled/ir-spi-led.yaml b/Documentation/devicetree/bindings/leds/irled/ir-spi-led.yaml new file mode 100644 index 000000000000..72cadebf6e3e --- /dev/null +++ b/Documentation/devicetree/bindings/leds/irled/ir-spi-led.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/irled/ir-spi-led.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: IR LED connected through SPI bus + +maintainers: + - Sean Young <sean@mess.org> + +description: + IR LED switch is connected to the MOSI line of the SPI device and the data + is delivered through that. + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + +properties: + compatible: + const: ir-spi-led + + reg: + maxItems: 1 + + duty-cycle: + $ref: /schemas/types.yaml#/definitions/uint8 + enum: [50, 60, 70, 75, 80, 90] + description: + Percentage of one period in which the signal is active. + + led-active-low: + type: boolean + description: + Output is negated with a NOT gate. + + power-supply: true + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + irled@0 { + compatible = "ir-spi-led"; + reg = <0x0>; + + duty-cycle = /bits/ 8 <60>; + led-active-low; + power-supply = <&irda_regulator>; + spi-max-frequency = <5000000>; + }; + }; + diff --git a/Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.txt b/Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.txt deleted file mode 100644 index 66e5672c2e3d..000000000000 --- a/Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.txt +++ /dev/null @@ -1,13 +0,0 @@ -Device tree bindings for IR LED connected through pwm pin which is used as -remote controller transmitter. - -Required properties: - - compatible: should be "pwm-ir-tx". - - pwms : PWM property to point to the PWM device (phandle)/port (id) - and to specify the period time to be used: <&phandle id period_ns>; - -Example: - irled { - compatible = "pwm-ir-tx"; - pwms = <&pwm0 0 10000000>; - }; diff --git a/Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.yaml b/Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.yaml new file mode 100644 index 000000000000..f2a6fa140f38 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.yaml @@ -0,0 +1,34 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/irled/pwm-ir-tx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: IR LED connected through PWM pin + +maintainers: + - Sean Young <sean@mess.org> + +description: + IR LED connected through PWM pin which is used as remote controller + transmitter. + +properties: + compatible: + const: pwm-ir-tx + + pwms: + maxItems: 1 + +required: + - compatible + - pwms + +additionalProperties: false + +examples: + - | + irled { + compatible = "pwm-ir-tx"; + pwms = <&pwm0 0 10000000>; + }; diff --git a/Documentation/devicetree/bindings/leds/irled/spi-ir-led.txt b/Documentation/devicetree/bindings/leds/irled/spi-ir-led.txt deleted file mode 100644 index 83ff1b4d70a6..000000000000 --- a/Documentation/devicetree/bindings/leds/irled/spi-ir-led.txt +++ /dev/null @@ -1,29 +0,0 @@ -Device tree bindings for IR LED connected through SPI bus which is used as -remote controller. - -The IR LED switch is connected to the MOSI line of the SPI device and the data -are delivered thourgh that. - -Required properties: - - compatible: should be "ir-spi-led". - -Optional properties: - - duty-cycle: 8 bit value that represents the percentage of one period - in which the signal is active. It can be 50, 60, 70, 75, 80 or 90. - - led-active-low: boolean value that specifies whether the output is - negated with a NOT gate. - - power-supply: specifies the power source. It can either be a regulator - or a gpio which enables a regulator, i.e. a regulator-fixed as - described in - Documentation/devicetree/bindings/regulator/fixed-regulator.yaml - -Example: - - irled@0 { - compatible = "ir-spi-led"; - reg = <0x0>; - spi-max-frequency = <5000000>; - power-supply = <&vdd_led>; - led-active-low; - duty-cycle = /bits/ 8 <60>; - }; diff --git a/Documentation/devicetree/bindings/leds/issi,is31fl319x.yaml b/Documentation/devicetree/bindings/leds/issi,is31fl319x.yaml index 940333f2d69c..2929382625b6 100644 --- a/Documentation/devicetree/bindings/leds/issi,is31fl319x.yaml +++ b/Documentation/devicetree/bindings/leds/issi,is31fl319x.yaml @@ -57,6 +57,7 @@ patternProperties: "^led@[1-9]$": type: object $ref: common.yaml# + unevaluatedProperties: false properties: reg: diff --git a/Documentation/devicetree/bindings/leds/leds-aw2013.yaml b/Documentation/devicetree/bindings/leds/leds-aw2013.yaml index e24b0d15ef01..6c3ea0f06cef 100644 --- a/Documentation/devicetree/bindings/leds/leds-aw2013.yaml +++ b/Documentation/devicetree/bindings/leds/leds-aw2013.yaml @@ -33,6 +33,7 @@ patternProperties: "^led@[0-2]$": type: object $ref: common.yaml# + unevaluatedProperties: false properties: reg: diff --git a/Documentation/devicetree/bindings/leds/leds-gpio.yaml b/Documentation/devicetree/bindings/leds/leds-gpio.yaml index 7ad2baeda0b0..7e11703acbd6 100644 --- a/Documentation/devicetree/bindings/leds/leds-gpio.yaml +++ b/Documentation/devicetree/bindings/leds/leds-gpio.yaml @@ -23,8 +23,8 @@ patternProperties: # node name to at least catch some child nodes. "(^led-[0-9a-f]$|led)": type: object - $ref: common.yaml# + unevaluatedProperties: false properties: gpios: diff --git a/Documentation/devicetree/bindings/leds/leds-lgm.yaml b/Documentation/devicetree/bindings/leds/leds-lgm.yaml index f8d7963c3a13..8b3b3bf1eaf2 100644 --- a/Documentation/devicetree/bindings/leds/leds-lgm.yaml +++ b/Documentation/devicetree/bindings/leds/leds-lgm.yaml @@ -56,7 +56,8 @@ properties: patternProperties: "^led@[0-2]$": - type: object + $ref: common.yaml# + unevaluatedProperties: false properties: reg: @@ -64,6 +65,9 @@ properties: minimum: 0 maximum: 2 + led-gpios: + maxItems: 1 + intel,sso-hw-trigger: type: boolean description: This property indicates Hardware driven/control LED. @@ -118,14 +122,14 @@ examples: reg = <0>; function = "gphy"; color = <LED_COLOR_ID_GREEN>; - led-gpio = <&ssogpio 0 0>; + led-gpios = <&ssogpio 0 0>; }; led@2 { reg = <2>; function = LED_FUNCTION_POWER; color = <LED_COLOR_ID_GREEN>; - led-gpio = <&ssogpio 23 0>; + led-gpios = <&ssogpio 23 0>; }; }; }; diff --git a/Documentation/devicetree/bindings/leds/leds-lp50xx.yaml b/Documentation/devicetree/bindings/leds/leds-lp50xx.yaml index 63da380748bf..402c25424525 100644 --- a/Documentation/devicetree/bindings/leds/leds-lp50xx.yaml +++ b/Documentation/devicetree/bindings/leds/leds-lp50xx.yaml @@ -77,6 +77,14 @@ patternProperties: "^led@[0-9a-f]+$": type: object $ref: common.yaml# + unevaluatedProperties: false + + properties: + reg: + maxItems: 1 + + required: + - reg required: - compatible diff --git a/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml b/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml index 7ec676e53851..ae607911f1db 100644 --- a/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml +++ b/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml @@ -43,11 +43,13 @@ properties: - 1 # internal - 2 # external - enable-gpio: + enable-gpios: maxItems: 1 description: | GPIO attached to the chip's enable pin + label: true + pwr-sel: $ref: /schemas/types.yaml#/definitions/uint8 description: | @@ -65,9 +67,50 @@ properties: const: 0 patternProperties: - "(^led@[0-9a-f]$|led)": + '^multi-led@[0-8]$': + type: object + $ref: leds-class-multicolor.yaml# + unevaluatedProperties: false + + properties: + reg: + maximum: 8 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + patternProperties: + "^led@[0-8]$": + type: object + $ref: common.yaml# + unevaluatedProperties: false + + properties: + led-cur: + $ref: /schemas/types.yaml#/definitions/uint8 + description: | + Current setting at each LED channel (mA x10, 0 if LED is not connected) + minimum: 0 + maximum: 255 + + max-cur: + $ref: /schemas/types.yaml#/definitions/uint8 + description: Maximun current at each LED channel. + + reg: + maximum: 8 + + required: + - reg + + "^led@[0-8]$": type: object $ref: common.yaml# + unevaluatedProperties: false + properties: led-cur: $ref: /schemas/types.yaml#/definitions/uint8 diff --git a/Documentation/devicetree/bindings/leds/leds-max77650.yaml b/Documentation/devicetree/bindings/leds/leds-max77650.yaml index c6f96cabd4d1..fdb08f44a45d 100644 --- a/Documentation/devicetree/bindings/leds/leds-max77650.yaml +++ b/Documentation/devicetree/bindings/leds/leds-max77650.yaml @@ -30,9 +30,8 @@ properties: patternProperties: "^led@[0-2]$": - type: object - description: | - Properties for a single LED. + $ref: common.yaml# + unevaluatedProperties: false properties: reg: @@ -41,10 +40,6 @@ patternProperties: minimum: 0 maximum: 2 - label: true - - linux,default-trigger: true - required: - compatible - "#address-cells" diff --git a/Documentation/devicetree/bindings/leds/leds-mt6360.yaml b/Documentation/devicetree/bindings/leds/leds-mt6360.yaml index 69e579226d9b..d84e28e616d7 100644 --- a/Documentation/devicetree/bindings/leds/leds-mt6360.yaml +++ b/Documentation/devicetree/bindings/leds/leds-mt6360.yaml @@ -26,11 +26,10 @@ properties: const: 0 patternProperties: - "^(multi-)?led@[0-5]$": + "^multi-led@[0-5]$": type: object - $ref: common.yaml# - description: - Properties for a single LED. + $ref: leds-class-multicolor.yaml# + unevaluatedProperties: false properties: reg: @@ -43,6 +42,42 @@ patternProperties: - 4 # LED output FLASH1 - 5 # LED output FLASH2 + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + patternProperties: + "^led@[0-2]$": + type: object + $ref: common.yaml# + unevaluatedProperties: false + + properties: + reg: + enum: [0, 1, 2] + + required: + - reg + - color + + required: + - reg + - "#address-cells" + - "#size-cells" + + "^led@[0-5]$": + type: object + $ref: common.yaml# + unevaluatedProperties: false + description: + Properties for a single LED. + + properties: + reg: + enum: [0, 1, 2, 3, 4, 5] + required: - compatible - "#address-cells" diff --git a/Documentation/devicetree/bindings/leds/leds-pwm.yaml b/Documentation/devicetree/bindings/leds/leds-pwm.yaml index fe4d5fd25913..7de6da58be3c 100644 --- a/Documentation/devicetree/bindings/leds/leds-pwm.yaml +++ b/Documentation/devicetree/bindings/leds/leds-pwm.yaml @@ -20,8 +20,8 @@ properties: patternProperties: "^led(-[0-9a-f]+)?$": type: object - $ref: common.yaml# + unevaluatedProperties: false properties: pwms: diff --git a/Documentation/devicetree/bindings/leds/leds-qcom-lpg.yaml b/Documentation/devicetree/bindings/leds/leds-qcom-lpg.yaml index 497db289169d..1df837798249 100644 --- a/Documentation/devicetree/bindings/leds/leds-qcom-lpg.yaml +++ b/Documentation/devicetree/bindings/leds/leds-qcom-lpg.yaml @@ -72,14 +72,24 @@ properties: "^led@[0-9a-f]$": type: object $ref: common.yaml# + unevaluatedProperties: false + + properties: + reg: + maxItems: 1 + + required: + - reg patternProperties: "^led@[0-9a-f]$": type: object $ref: common.yaml# + unevaluatedProperties: false properties: - reg: true + reg: + maxItems: 1 required: - reg diff --git a/Documentation/devicetree/bindings/leds/leds-rt4505.yaml b/Documentation/devicetree/bindings/leds/leds-rt4505.yaml index 5b0c74aa6723..cb71fec173c1 100644 --- a/Documentation/devicetree/bindings/leds/leds-rt4505.yaml +++ b/Documentation/devicetree/bindings/leds/leds-rt4505.yaml @@ -27,6 +27,7 @@ properties: led: type: object $ref: common.yaml# + unevaluatedProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/leds/leds-sgm3140.yaml b/Documentation/devicetree/bindings/leds/leds-sgm3140.yaml index f68259619488..4d2ffe5fcfc7 100644 --- a/Documentation/devicetree/bindings/leds/leds-sgm3140.yaml +++ b/Documentation/devicetree/bindings/leds/leds-sgm3140.yaml @@ -18,7 +18,9 @@ description: | properties: compatible: - const: sgmicro,sgm3140 + enum: + - ocs,ocp8110 + - sgmicro,sgm3140 enable-gpios: maxItems: 1 @@ -34,6 +36,7 @@ properties: led: type: object $ref: common.yaml# + unevaluatedProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/leds/rohm,bd71828-leds.yaml b/Documentation/devicetree/bindings/leds/rohm,bd71828-leds.yaml index 86a37c92b834..ca92cea56a6f 100644 --- a/Documentation/devicetree/bindings/leds/rohm,bd71828-leds.yaml +++ b/Documentation/devicetree/bindings/leds/rohm,bd71828-leds.yaml @@ -26,26 +26,16 @@ properties: patternProperties: "^led-[1-2]$": - type: object - description: - Properties for a single LED. + $ref: common.yaml# + unevaluatedProperties: false + properties: - #allOf: - #- $ref: "common.yaml#" rohm,led-compatible: description: LED identification string $ref: "/schemas/types.yaml#/definitions/string" enum: - bd71828-ambled - bd71828-grnled - function: - description: - Purpose of LED as defined in dt-bindings/leds/common.h - $ref: "/schemas/types.yaml#/definitions/string" - color: - description: - LED colour as defined in dt-bindings/leds/common.h - $ref: "/schemas/types.yaml#/definitions/uint32" required: - compatible diff --git a/Documentation/devicetree/bindings/leds/ti,tca6507.yaml b/Documentation/devicetree/bindings/leds/ti,tca6507.yaml index 32c600387895..9ce5c0f16e17 100644 --- a/Documentation/devicetree/bindings/leds/ti,tca6507.yaml +++ b/Documentation/devicetree/bindings/leds/ti,tca6507.yaml @@ -38,8 +38,8 @@ properties: patternProperties: "^led@[0-6]$": type: object - $ref: common.yaml# + unevaluatedProperties: false properties: reg: diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml index 704033e21ee8..53945c61325c 100644 --- a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml +++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml @@ -21,6 +21,7 @@ properties: - const: allwinner,sun6i-a31-ir - items: - enum: + - allwinner,suniv-f1c100s-ir - allwinner,sun8i-a83t-ir - allwinner,sun8i-r40-ir - allwinner,sun50i-a64-ir diff --git a/Documentation/devicetree/bindings/media/allwinner,sun50i-h6-vpu-g2.yaml b/Documentation/devicetree/bindings/media/allwinner,sun50i-h6-vpu-g2.yaml index 24d7bf21499e..9d44236f2deb 100644 --- a/Documentation/devicetree/bindings/media/allwinner,sun50i-h6-vpu-g2.yaml +++ b/Documentation/devicetree/bindings/media/allwinner,sun50i-h6-vpu-g2.yaml @@ -36,6 +36,9 @@ properties: resets: maxItems: 1 + iommus: + maxItems: 1 + required: - compatible - reg @@ -43,6 +46,7 @@ required: - clocks - clock-names - resets + - iommus additionalProperties: false @@ -59,6 +63,7 @@ examples: clocks = <&ccu CLK_BUS_VP9>, <&ccu CLK_VP9>; clock-names = "bus", "mod"; resets = <&ccu RST_BUS_VP9>; + iommus = <&iommu 5>; }; ... diff --git a/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-csi.yaml b/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-csi.yaml index f1ccca35a790..b3d6db922693 100644 --- a/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-csi.yaml +++ b/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-csi.yaml @@ -73,6 +73,10 @@ properties: $ref: /schemas/graph.yaml#/properties/port description: MIPI CSI-2 bridge input port + port@2: + $ref: /schemas/graph.yaml#/properties/port + description: Internal output port to the ISP + anyOf: - required: - port@0 diff --git a/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-isp.yaml b/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-isp.yaml new file mode 100644 index 000000000000..6bda4f2b94c2 --- /dev/null +++ b/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-isp.yaml @@ -0,0 +1,101 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/allwinner,sun6i-a31-isp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A31 Image Signal Processor Driver (ISP) Device Tree Bindings + +maintainers: + - Paul Kocialkowski <paul.kocialkowski@bootlin.com> + +properties: + compatible: + enum: + - allwinner,sun6i-a31-isp + - allwinner,sun8i-v3s-isp + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Bus Clock + - description: Module Clock + - description: DRAM Clock + + clock-names: + items: + - const: bus + - const: mod + - const: ram + + resets: + maxItems: 1 + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: CSI0 input port + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: CSI1 input port + + if: + properties: + compatible: + contains: + enum: + - allwinner,sun8i-v3s-isp + then: + required: + - port@0 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - resets + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/sun8i-v3s-ccu.h> + #include <dt-bindings/reset/sun8i-v3s-ccu.h> + + isp: isp@1cb8000 { + compatible = "allwinner,sun8i-v3s-isp"; + reg = <0x01cb8000 0x1000>; + interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_CSI>, + <&ccu CLK_CSI1_SCLK>, + <&ccu CLK_DRAM_CSI>; + clock-names = "bus", "mod", "ram"; + resets = <&ccu RST_BUS_CSI>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + isp_in_csi0: endpoint { + remote-endpoint = <&csi0_out_isp>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/atmel,isc.yaml b/Documentation/devicetree/bindings/media/atmel,isc.yaml index cd6d7af0c768..dc8aba698d78 100644 --- a/Documentation/devicetree/bindings/media/atmel,isc.yaml +++ b/Documentation/devicetree/bindings/media/atmel,isc.yaml @@ -45,7 +45,7 @@ properties: port: $ref: /schemas/graph.yaml#/$defs/port-base - unevaluatedProperties: false + additionalProperties: false description: Input port node, single endpoint describing the input pad. @@ -77,8 +77,6 @@ properties: additionalProperties: false - additionalProperties: false - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/media/i2c/imx290.txt b/Documentation/devicetree/bindings/media/i2c/imx290.txt deleted file mode 100644 index a3cc21410f7c..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/imx290.txt +++ /dev/null @@ -1,57 +0,0 @@ -* Sony IMX290 1/2.8-Inch CMOS Image Sensor - -The Sony IMX290 is a 1/2.8-Inch CMOS Solid-state image sensor with -Square Pixel for Color Cameras. It is programmable through I2C and 4-wire -interfaces. The sensor output is available via CMOS logic parallel SDR output, -Low voltage LVDS DDR output and CSI-2 serial data output. The CSI-2 bus is the -default. No bindings have been defined for the other busses. - -Required Properties: -- compatible: Should be "sony,imx290" -- reg: I2C bus address of the device -- clocks: Reference to the xclk clock. -- clock-names: Should be "xclk". -- clock-frequency: Frequency of the xclk clock in Hz. -- vdddo-supply: Sensor digital IO regulator. -- vdda-supply: Sensor analog regulator. -- vddd-supply: Sensor digital core regulator. - -Optional Properties: -- reset-gpios: Sensor reset GPIO - -The imx290 device node should contain one 'port' child node with -an 'endpoint' subnode. For further reading on port node refer to -Documentation/devicetree/bindings/media/video-interfaces.txt. - -Required Properties on endpoint: -- data-lanes: check ../video-interfaces.txt -- link-frequencies: check ../video-interfaces.txt -- remote-endpoint: check ../video-interfaces.txt - -Example: - &i2c1 { - ... - imx290: camera-sensor@1a { - compatible = "sony,imx290"; - reg = <0x1a>; - - reset-gpios = <&msmgpio 35 GPIO_ACTIVE_LOW>; - pinctrl-names = "default"; - pinctrl-0 = <&camera_rear_default>; - - clocks = <&gcc GCC_CAMSS_MCLK0_CLK>; - clock-names = "xclk"; - clock-frequency = <37125000>; - - vdddo-supply = <&camera_vdddo_1v8>; - vdda-supply = <&camera_vdda_2v8>; - vddd-supply = <&camera_vddd_1v5>; - - port { - imx290_ep: endpoint { - data-lanes = <1 2 3 4>; - link-frequencies = /bits/ 64 <445500000>; - remote-endpoint = <&csiphy0_ep>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml b/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml index 39395ea8c318..edde4201116f 100644 --- a/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml +++ b/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml @@ -104,6 +104,7 @@ additionalProperties: false examples: - | #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/media/video-interfaces.h> i2c2 { #address-cells = <1>; @@ -124,7 +125,7 @@ examples: remote-endpoint = <&csi2a_ep>; link-frequencies = /bits/ 64 <199200000 210000000 499200000>; - bus-type = <4>; + bus-type = <MEDIA_BUS_TYPE_CSI2_DPHY>; }; }; }; diff --git a/Documentation/devicetree/bindings/media/i2c/ov5645.txt b/Documentation/devicetree/bindings/media/i2c/ov5645.txt deleted file mode 100644 index 72ad992f77be..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/ov5645.txt +++ /dev/null @@ -1,54 +0,0 @@ -* Omnivision 1/4-Inch 5Mp CMOS Digital Image Sensor - -The Omnivision OV5645 is a 1/4-Inch CMOS active pixel digital image sensor with -an active array size of 2592H x 1944V. It is programmable through a serial I2C -interface. - -Required Properties: -- compatible: Value should be "ovti,ov5645". -- clocks: Reference to the xclk clock. -- clock-names: Should be "xclk". -- clock-frequency: Frequency of the xclk clock. -- enable-gpios: Chip enable GPIO. Polarity is GPIO_ACTIVE_HIGH. This corresponds - to the hardware pin PWDNB which is physically active low. -- reset-gpios: Chip reset GPIO. Polarity is GPIO_ACTIVE_LOW. This corresponds to - the hardware pin RESETB. -- vdddo-supply: Chip digital IO regulator. -- vdda-supply: Chip analog regulator. -- vddd-supply: Chip digital core regulator. - -The device node must contain one 'port' child node for its digital output -video port, in accordance with the video interface bindings defined in -Documentation/devicetree/bindings/media/video-interfaces.txt. - -Example: - - &i2c1 { - ... - - ov5645: ov5645@3c { - compatible = "ovti,ov5645"; - reg = <0x3c>; - - enable-gpios = <&gpio1 6 GPIO_ACTIVE_HIGH>; - reset-gpios = <&gpio5 20 GPIO_ACTIVE_LOW>; - pinctrl-names = "default"; - pinctrl-0 = <&camera_rear_default>; - - clocks = <&clks 200>; - clock-names = "xclk"; - clock-frequency = <24000000>; - - vdddo-supply = <&camera_dovdd_1v8>; - vdda-supply = <&camera_avdd_2v8>; - vddd-supply = <&camera_dvdd_1v2>; - - port { - ov5645_ep: endpoint { - clock-lanes = <1>; - data-lanes = <0 2>; - remote-endpoint = <&csi0_ep>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov4689.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov4689.yaml new file mode 100644 index 000000000000..50579c947f3c --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov4689.yaml @@ -0,0 +1,134 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/ovti,ov4689.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Omnivision OV4689 CMOS + +maintainers: + - Mikhail Rudenko <mike.rudenko@gmail.com> + +description: | + The Omnivision OV4689 is a high performance, 1/3-inch, 4 megapixel + image sensor. Ihis chip supports high frame rate speeds up to 90 fps + at 2688x1520 resolution. It is programmable through an I2C + interface, and sensor output is sent via 1/2/4 lane MIPI CSI-2 + connection. + +allOf: + - $ref: /schemas/media/video-interface-devices.yaml# + +properties: + compatible: + const: ovti,ov4689 + + reg: + maxItems: 1 + + clocks: + description: + External clock (XVCLK) for the sensor, 6-64 MHz + maxItems: 1 + + dovdd-supply: + description: + Digital I/O voltage supply, 1.7-3.0 V + + avdd-supply: + description: + Analog voltage supply, 2.6-3.0 V + + dvdd-supply: + description: + Digital core voltage supply, 1.1-1.3 V + + powerdown-gpios: + description: + GPIO connected to the powerdown pin (active low) + + reset-gpios: + maxItems: 1 + description: + GPIO connected to the reset pin (active low) + + orientation: true + + rotation: true + + port: + $ref: /schemas/graph.yaml#/$defs/port-base + additionalProperties: false + description: + Output port node, single endpoint describing the CSI-2 transmitter + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: + oneOf: + - items: + - const: 1 + - const: 2 + - const: 3 + - const: 4 + - items: + - const: 1 + - const: 2 + - items: + - const: 1 + link-frequencies: true + + required: + - data-lanes + - link-frequencies + +required: + - compatible + - reg + - clocks + - dovdd-supply + - avdd-supply + - dvdd-supply + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + ov4689: camera@36 { + compatible = "ovti,ov4689"; + reg = <0x36>; + + clocks = <&ov4689_clk>; + + avdd-supply = <&ov4689_avdd>; + dovdd-supply = <&ov4689_dovdd>; + dvdd-supply = <&ov4689_dvdd>; + + powerdown-gpios = <&pio 107 GPIO_ACTIVE_LOW>; + reset-gpios = <&pio 109 GPIO_ACTIVE_LOW>; + + orientation = <2>; + rotation = <0>; + + port { + wcam_out: endpoint { + remote-endpoint = <&mipi_in_wcam>; + data-lanes = <1 2 3 4>; + link-frequencies = /bits/ 64 <504000000>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov5645.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5645.yaml new file mode 100644 index 000000000000..52c6281a6684 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5645.yaml @@ -0,0 +1,104 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/ovti,ov5645.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: OmniVision OV5645 Image Sensor Device Tree Bindings + +maintainers: + - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com> + +properties: + compatible: + const: ovti,ov5645 + + reg: + maxItems: 1 + + clocks: + description: XCLK Input Clock + + clock-frequency: + description: Frequency of the xclk clock in Hz. + + vdda-supply: + description: Analog voltage supply, 2.8 volts + + vddd-supply: + description: Digital core voltage supply, 1.5 volts + + vdddo-supply: + description: Digital I/O voltage supply, 1.8 volts + + enable-gpios: + maxItems: 1 + description: + Reference to the GPIO connected to the PWDNB pin, if any. + + reset-gpios: + maxItems: 1 + description: + Reference to the GPIO connected to the RESETB pin, if any. + + port: + description: Digital Output Port + $ref: /schemas/graph.yaml#/$defs/port-base + additionalProperties: false + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: + minItems: 1 + maxItems: 2 + items: + enum: [1, 2] + + required: + - data-lanes + +required: + - compatible + - reg + - clocks + - vdddo-supply + - vdda-supply + - vddd-supply + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + camera@3c { + compatible = "ovti,ov5645"; + reg = <0x3c>; + clocks = <&clks 1>; + clock-frequency = <24000000>; + vdddo-supply = <&ov5645_vdddo_1v8>; + vdda-supply = <&ov5645_vdda_2v8>; + vddd-supply = <&ov5645_vddd_1v5>; + enable-gpios = <&gpio1 19 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio1 20 GPIO_ACTIVE_LOW>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_ov5645>; + + port { + ov5645_ep: endpoint { + remote-endpoint = <&csi0_ep>; + data-lanes = <1 2>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml index 44529425ce3a..161e6d598e1c 100644 --- a/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml @@ -105,6 +105,7 @@ additionalProperties: false examples: - | #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/media/video-interfaces.h> i2c0 { #address-cells = <1>; @@ -118,7 +119,7 @@ examples: port { ov772x_0: endpoint { - bus-type = <5>; + bus-type = <MEDIA_BUS_TYPE_PARALLEL>; vsync-active = <0>; hsync-active = <0>; pclk-sample = <0>; diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov9282.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov9282.yaml index bf115ab9d926..0c4654e70d46 100644 --- a/Documentation/devicetree/bindings/media/i2c/ovti,ov9282.yaml +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov9282.yaml @@ -16,10 +16,13 @@ description: sensor with an active array size of 1296H x 816V. It is programmable through I2C interface. The I2C client address is fixed to 0x60/0x70 as per sensor data sheet. Image data is sent through MIPI CSI-2. + OV9281 has a different lens chief ray angle. properties: compatible: - const: ovti,ov9282 + enum: + - ovti,ov9281 + - ovti,ov9282 reg: description: I2C address maxItems: 1 @@ -36,6 +39,15 @@ properties: description: Reference to the GPIO connected to the XCLR pin, if any. maxItems: 1 + avdd-supply: + description: Analog voltage supply, 2.8 volts + + dvdd-supply: + description: Digital core voltage supply, 1.2 volts + + dovdd-supply: + description: Digital I/O voltage supply, 1.8 volts + port: additionalProperties: false $ref: /schemas/graph.yaml#/$defs/port-base diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx290.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx290.yaml new file mode 100644 index 000000000000..21377daae026 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/sony,imx290.yaml @@ -0,0 +1,129 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/sony,imx290.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sony IMX290 1/2.8-Inch CMOS Image Sensor + +maintainers: + - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org> + - Laurent Pinchart <laurent.pinchart@ideasonboard.com> + +description: |- + The Sony IMX290 is a 1/2.8-Inch CMOS Solid-state image sensor with Square + Pixel for Color Cameras. It is programmable through I2C and 4-wire + interfaces. The sensor output is available via CMOS logic parallel SDR + output, Low voltage LVDS DDR output and CSI-2 serial data output. The CSI-2 + bus is the default. No bindings have been defined for the other busses. + +properties: + compatible: + enum: + - sony,imx290 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + description: Input clock (37.125 MHz or 74.25 MHz) + items: + - const: xclk + + clock-frequency: + description: Frequency of the xclk clock in Hz + + vdda-supply: + description: Analog power supply (2.9V) + + vddd-supply: + description: Digital core power supply (1.2V) + + vdddo-supply: + description: Digital I/O power supply (1.8V) + + reset-gpios: + description: Sensor reset (XCLR) GPIO + maxItems: 1 + + port: + $ref: /schemas/graph.yaml#/$defs/port-base + description: | + Video output port + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: + anyOf: + - items: + - const: 1 + - const: 2 + - items: + - const: 1 + - const: 2 + - const: 3 + - const: 4 + + link-frequencies: true + + required: + - data-lanes + - link-frequencies + + additionalProperties: false + +required: + - compatible + - reg + - clocks + - clock-names + - clock-frequency + - vdda-supply + - vddd-supply + - vdddo-supply + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + imx290: camera-sensor@1a { + compatible = "sony,imx290"; + reg = <0x1a>; + + pinctrl-names = "default"; + pinctrl-0 = <&camera_rear_default>; + + clocks = <&gcc 90>; + clock-names = "xclk"; + clock-frequency = <37125000>; + + vdddo-supply = <&camera_vdddo_1v8>; + vdda-supply = <&camera_vdda_2v8>; + vddd-supply = <&camera_vddd_1v5>; + + reset-gpios = <&msmgpio 35 GPIO_ACTIVE_LOW>; + + port { + imx290_ep: endpoint { + data-lanes = <1 2 3 4>; + link-frequencies = /bits/ 64 <445500000>; + remote-endpoint = <&csiphy0_ep>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx412.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx412.yaml index 26d1807d0bb6..60dc25ff2b9e 100644 --- a/Documentation/devicetree/bindings/media/i2c/sony,imx412.yaml +++ b/Documentation/devicetree/bindings/media/i2c/sony,imx412.yaml @@ -19,7 +19,9 @@ description: properties: compatible: - const: sony,imx412 + enum: + - sony,imx412 + - sony,imx577 reg: description: I2C address maxItems: 1 diff --git a/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.txt b/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.txt deleted file mode 100644 index 7976e6c40a80..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.txt +++ /dev/null @@ -1,82 +0,0 @@ -STMicroelectronics MIPID02 CSI-2 to PARALLEL bridge - -MIPID02 has two CSI-2 input ports, only one of those ports can be active at a -time. Active port input stream will be de-serialized and its content outputted -through PARALLEL output port. -CSI-2 first input port is a dual lane 800Mbps per lane whereas CSI-2 second -input port is a single lane 800Mbps. Both ports support clock and data lane -polarity swap. First port also supports data lane swap. -PARALLEL output port has a maximum width of 12 bits. -Supported formats are RAW6, RAW7, RAW8, RAW10, RAW12, RGB565, RGB888, RGB444, -YUV420 8-bit, YUV422 8-bit and YUV420 10-bit. - -Required Properties: -- compatible: shall be "st,st-mipid02" -- clocks: reference to the xclk input clock. -- clock-names: shall be "xclk". -- VDDE-supply: sensor digital IO supply. Must be 1.8 volts. -- VDDIN-supply: sensor internal regulator supply. Must be 1.8 volts. - -Optional Properties: -- reset-gpios: reference to the GPIO connected to the xsdn pin, if any. - This is an active low signal to the mipid02. - -Required subnodes: - - ports: A ports node with one port child node per device input and output - port, in accordance with the video interface bindings defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. The - port nodes are numbered as follows: - - Port Description - ----------------------------- - 0 CSI-2 first input port - 1 CSI-2 second input port - 2 PARALLEL output - -Endpoint node required property for CSI-2 connection is: -- data-lanes: shall be <1> for Port 1. for Port 0 dual-lane operation shall be -<1 2> or <2 1>. For Port 0 single-lane operation shall be <1> or <2>. -Endpoint node optional property for CSI-2 connection is: -- lane-polarities: any lane can be inverted or not. - -Endpoint node required property for PARALLEL connection is: -- bus-width: shall be set to <6>, <7>, <8>, <10> or <12>. -Endpoint node optional properties for PARALLEL connection are: -- hsync-active: active state of the HSYNC signal, 0/1 for LOW/HIGH respectively. -LOW being the default. -- vsync-active: active state of the VSYNC signal, 0/1 for LOW/HIGH respectively. -LOW being the default. - -Example: - -mipid02: csi2rx@14 { - compatible = "st,st-mipid02"; - reg = <0x14>; - status = "okay"; - clocks = <&clk_ext_camera_12>; - clock-names = "xclk"; - VDDE-supply = <&vdd>; - VDDIN-supply = <&vdd>; - ports { - #address-cells = <1>; - #size-cells = <0>; - port@0 { - reg = <0>; - - ep0: endpoint { - data-lanes = <1 2>; - remote-endpoint = <&mipi_csi2_in>; - }; - }; - port@2 { - reg = <2>; - - ep2: endpoint { - bus-width = <8>; - hsync-active = <0>; - vsync-active = <0>; - remote-endpoint = <¶llel_out>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.yaml b/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.yaml new file mode 100644 index 000000000000..19a39d753aad --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.yaml @@ -0,0 +1,176 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/st,st-mipid02.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics MIPID02 CSI-2 to PARALLEL bridge + +maintainers: + - Benjamin Mugnier <benjamin.mugnier@foss.st.com> + - Sylvain Petinot <sylvain.petinot@foss.st.com> + +description: + MIPID02 has two CSI-2 input ports, only one of those ports can be + active at a time. Active port input stream will be de-serialized + and its content outputted through PARALLEL output port. + CSI-2 first input port is a dual lane 800Mbps per lane whereas CSI-2 + second input port is a single lane 800Mbps. Both ports support clock + and data lane polarity swap. First port also supports data lane swap. + PARALLEL output port has a maximum width of 12 bits. + Supported formats are RAW6, RAW7, RAW8, RAW10, RAW12, RGB565, RGB888, + RGB444, YUV420 8-bit, YUV422 8-bit and YUV420 10-bit. + +properties: + compatible: + const: st,st-mipid02 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + const: xclk + + VDDE-supply: + description: + Sensor digital IO supply. Must be 1.8 volts. + + VDDIN-supply: + description: + Sensor internal regulator supply. Must be 1.8 volts. + + reset-gpios: + description: + Reference to the GPIO connected to the xsdn pin, if any. + This is an active low signal to the mipid02. + + ports: + $ref: /schemas/graph.yaml#/properties/ports + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: CSI-2 first input port + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: + description: + Single-lane operation shall be <1> or <2> . + Dual-lane operation shall be <1 2> or <2 1> . + minItems: 1 + maxItems: 2 + + lane-polarities: + description: + Any lane can be inverted or not. + minItems: 1 + maxItems: 2 + + required: + - data-lanes + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: CSI-2 second input port + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: + description: + Single-lane operation shall be <1> or <2> . + maxItems: 1 + + lane-polarities: + description: + Any lane can be inverted or not. + maxItems: 1 + + required: + - data-lanes + + port@2: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: Output port + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + bus-width: + enum: [6, 7, 8, 10, 12] + + required: + - bus-width + + anyOf: + - required: + - port@0 + - required: + - port@1 + + required: + - port@2 + +additionalProperties: false + +required: + - compatible + - reg + - clocks + - clock-names + - VDDE-supply + - VDDIN-supply + - ports + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + mipid02: csi2rx@14 { + compatible = "st,st-mipid02"; + reg = <0x14>; + status = "okay"; + clocks = <&clk_ext_camera_12>; + clock-names = "xclk"; + VDDE-supply = <&vdd>; + VDDIN-supply = <&vdd>; + ports { + #address-cells = <1>; + #size-cells = <0>; + port@0 { + reg = <0>; + + ep0: endpoint { + data-lanes = <1 2>; + remote-endpoint = <&mipi_csi2_in>; + }; + }; + port@2 { + reg = <2>; + + ep2: endpoint { + bus-width = <8>; + hsync-active = <0>; + vsync-active = <0>; + remote-endpoint = <¶llel_out>; + }; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/i2c/st,st-vgxy61.yaml b/Documentation/devicetree/bindings/media/i2c/st,st-vgxy61.yaml new file mode 100644 index 000000000000..6597e1d0e65f --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/st,st-vgxy61.yaml @@ -0,0 +1,113 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright (c) 2022 STMicroelectronics SA. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/st,st-vgxy61.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics VGxy61 HDR Global Shutter Sensor Family Device Tree Bindings + +maintainers: + - Benjamin Mugnier <benjamin.mugnier@foss.st.com> + - Sylvain Petinot <sylvain.petinot@foss.st.com> + +description: |- + STMicroelectronics VGxy61 family has a CSI-2 output port. CSI-2 output is a + quad lanes 800Mbps per lane. + Supported formats are RAW8, RAW10, RAW12, RAW14 and RAW16. + Following part number are supported + - VG5661 and VG6661 are 1.6 Mpx (1464 x 1104) monochrome and color sensors. + Maximum frame rate is 75 fps. + - VG5761 and VG6761 are 2.3 Mpx (1944 x 1204) monochrome and color sensors. + Maximum frame rate is 60 fps. + +properties: + compatible: + const: st,st-vgxy61 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + VCORE-supply: + description: + Sensor digital core supply. Must be 1.2 volts. + + VDDIO-supply: + description: + Sensor digital IO supply. Must be 1.8 volts. + + VANA-supply: + description: + Sensor analog supply. Must be 2.8 volts. + + reset-gpios: + description: + Reference to the GPIO connected to the reset pin, if any. + This is an active low signal to the vgxy61. + + st,strobe-gpios-polarity: + description: + Invert polarity of illuminator's lights strobe GPIOs. + These GPIOs directly drive the illuminator LEDs. + type: boolean + + port: + $ref: /schemas/graph.yaml#/$defs/port-base + additionalProperties: false + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: + description: + CSI lanes to use + items: + - const: 1 + - const: 2 + - const: 3 + - const: 4 + + remote-endpoint: true + + required: + - data-lanes + +required: + - compatible + - clocks + - VCORE-supply + - VDDIO-supply + - VANA-supply + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + vgxy61: csi2tx@10 { + compatible = "st,st-vgxy61"; + reg = <0x10>; + clocks = <&clk_ext_camera>; + VCORE-supply = <&v1v2>; + VDDIO-supply = <&v1v8>; + VANA-supply = <&v2v8>; + reset-gpios = <&mfxgpio 18 GPIO_ACTIVE_LOW>; + port { + ep0: endpoint { + data-lanes = <1 2 3 4>; + remote-endpoint = <&mipi_csi2_out>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/i2c/toshiba,tc358746.yaml b/Documentation/devicetree/bindings/media/i2c/toshiba,tc358746.yaml new file mode 100644 index 000000000000..b8ba85a2416c --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/toshiba,tc358746.yaml @@ -0,0 +1,178 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/toshiba,tc358746.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Toshiba TC358746 Parallel to MIPI CSI2 Bridge + +maintainers: + - Marco Felsch <kernel@pengutronix.de> + +description: |- + The Toshiba TC358746 converts a parallel video stream into a MIPI CSI-2 + stream. The direction can be either parallel-in -> csi-out or csi-in -> + parallel-out The chip is programmable trough I2C and SPI but the SPI + interface is only supported in parallel-in -> csi-out mode. + + Note that the current device tree bindings only support the + parallel-in -> csi-out path. + +properties: + compatible: + const: toshiba,tc358746 + + reg: + maxItems: 1 + + clocks: + description: + The phandle to the reference clock source. This corresponds to the + hardware pin REFCLK. + maxItems: 1 + + clock-names: + const: refclk + + "#clock-cells": + description: | + The bridge can act as clock provider for the sensor. To enable this + support #clock-cells must be specified. Attention if this feature is used + then the mclk rate must be at least: (2 * link-frequency) / 8 + `------------------´ ^ + internal PLL rate smallest possible + mclk-div + const: 0 + + clock-output-names: + description: + The clock name of the MCLK output, the default name is tc358746-mclk. + maxItems: 1 + + vddc-supply: + description: Digital core voltage supply, 1.2 volts + + vddio-supply: + description: Digital I/O voltage supply, 1.8 volts + + vddmipi-supply: + description: MIPI CSI phy voltage supply, 1.2 volts + + reset-gpios: + description: + The phandle and specifier for the GPIO that controls the chip reset. + This corresponds to the hardware pin RESX which is physically active low. + maxItems: 1 + + ports: + $ref: /schemas/graph.yaml#/properties/ports + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + description: Input port + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + hsync-active: true + vsync-active: true + bus-type: + enum: [ 5, 6 ] + + required: + - hsync-active + - vsync-active + - bus-type + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + description: Output port + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: + minItems: 1 + maxItems: 4 + + clock-noncontinuous: true + link-frequencies: true + + required: + - data-lanes + - link-frequencies + + required: + - port@0 + - port@1 + +required: + - compatible + - reg + - clocks + - clock-names + - vddc-supply + - vddio-supply + - vddmipi-supply + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + csi-bridge@e { + compatible = "toshiba,tc358746"; + reg = <0xe>; + + clocks = <&refclk>; + clock-names = "refclk"; + + reset-gpios = <&gpio 2 GPIO_ACTIVE_LOW>; + + vddc-supply = <&v1_2d>; + vddio-supply = <&v1_8d>; + vddmipi-supply = <&v1_2d>; + + /* sensor mclk provider */ + #clock-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + /* Input */ + port@0 { + reg = <0>; + tc358746_in: endpoint { + remote-endpoint = <&sensor_out>; + hsync-active = <0>; + vsync-active = <0>; + bus-type = <5>; + }; + }; + + /* Output */ + port@1 { + reg = <1>; + tc358746_out: endpoint { + remote-endpoint = <&mipi_csi2_in>; + data-lanes = <1 2>; + clock-noncontinuous; + link-frequencies = /bits/ 64 <216000000>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/marvell,mmp2-ccic.yaml b/Documentation/devicetree/bindings/media/marvell,mmp2-ccic.yaml index b39b84c5f012..0e3478551e13 100644 --- a/Documentation/devicetree/bindings/media/marvell,mmp2-ccic.yaml +++ b/Documentation/devicetree/bindings/media/marvell,mmp2-ccic.yaml @@ -68,6 +68,7 @@ additionalProperties: false examples: - | #include <dt-bindings/clock/marvell,mmp2.h> + #include <dt-bindings/media/video-interfaces.h> #include <dt-bindings/power/marvell,mmp2.h> camera@d420a000 { @@ -83,7 +84,7 @@ examples: port { camera0_0: endpoint { remote-endpoint = <&ov7670_0>; - bus-type = <5>; /* Parallel */ + bus-type = <MEDIA_BUS_TYPE_PARALLEL>; hsync-active = <1>; /* Active high */ vsync-active = <1>; /* Active high */ pclk-sample = <0>; /* Falling */ diff --git a/Documentation/devicetree/bindings/media/mediatek,mt8195-jpegdec.yaml b/Documentation/devicetree/bindings/media/mediatek,mt8195-jpegdec.yaml new file mode 100644 index 000000000000..71595c013dbb --- /dev/null +++ b/Documentation/devicetree/bindings/media/mediatek,mt8195-jpegdec.yaml @@ -0,0 +1,168 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/mediatek,mt8195-jpegdec.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek JPEG Decoder + +maintainers: + - kyrie wu <kyrie.wu@mediatek.corp-partner.google.com> + +description: + MediaTek JPEG Decoder is the JPEG decode hardware present in MediaTek SoCs + +properties: + compatible: + const: mediatek,mt8195-jpgdec + + power-domains: + maxItems: 1 + + iommus: + maxItems: 6 + description: + Points to the respective IOMMU block with master port as argument, see + Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details. + Ports are according to the HW. + + dma-ranges: + maxItems: 1 + description: | + Describes the physical address space of IOMMU maps to memory. + + "#address-cells": + const: 2 + + "#size-cells": + const: 2 + + ranges: true + +# Required child node: +patternProperties: + "^jpgdec@[0-9a-f]+$": + type: object + description: + The jpeg decoder hardware device node which should be added as subnodes to + the main jpeg node. + + properties: + compatible: + const: mediatek,mt8195-jpgdec-hw + + reg: + maxItems: 1 + + iommus: + minItems: 1 + maxItems: 32 + description: + List of the hardware port in respective IOMMU block for current Socs. + Refer to bindings/iommu/mediatek,iommu.yaml. + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: jpgdec + + power-domains: + maxItems: 1 + + required: + - compatible + - reg + - iommus + - interrupts + - clocks + - clock-names + - power-domains + + additionalProperties: false + +required: + - compatible + - power-domains + - iommus + - dma-ranges + - ranges + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/memory/mt8195-memory-port.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/clock/mt8195-clk.h> + #include <dt-bindings/power/mt8195-power.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + jpgdec-master { + compatible = "mediatek,mt8195-jpgdec"; + power-domains = <&spm MT8195_POWER_DOMAIN_VDEC1>; + iommus = <&iommu_vpp M4U_PORT_L19_JPGDEC_WDMA0>, + <&iommu_vpp M4U_PORT_L19_JPGDEC_BSDMA0>, + <&iommu_vpp M4U_PORT_L19_JPGDEC_WDMA1>, + <&iommu_vpp M4U_PORT_L19_JPGDEC_BSDMA1>, + <&iommu_vpp M4U_PORT_L19_JPGDEC_BUFF_OFFSET1>, + <&iommu_vpp M4U_PORT_L19_JPGDEC_BUFF_OFFSET0>; + dma-ranges = <0x1 0x0 0x0 0x40000000 0x0 0xfff00000>; + #address-cells = <2>; + #size-cells = <2>; + ranges; + + jpgdec@1a040000 { + compatible = "mediatek,mt8195-jpgdec-hw"; + reg = <0 0x1a040000 0 0x10000>;/* JPGDEC_C0 */ + iommus = <&iommu_vdo M4U_PORT_L19_JPGDEC_WDMA0>, + <&iommu_vdo M4U_PORT_L19_JPGDEC_BSDMA0>, + <&iommu_vdo M4U_PORT_L19_JPGDEC_WDMA1>, + <&iommu_vdo M4U_PORT_L19_JPGDEC_BSDMA1>, + <&iommu_vdo M4U_PORT_L19_JPGDEC_BUFF_OFFSET1>, + <&iommu_vdo M4U_PORT_L19_JPGDEC_BUFF_OFFSET0>; + interrupts = <GIC_SPI 343 IRQ_TYPE_LEVEL_HIGH 0>; + clocks = <&vencsys CLK_VENC_JPGDEC>; + clock-names = "jpgdec"; + power-domains = <&spm MT8195_POWER_DOMAIN_VDEC0>; + }; + + jpgdec@1a050000 { + compatible = "mediatek,mt8195-jpgdec-hw"; + reg = <0 0x1a050000 0 0x10000>;/* JPGDEC_C1 */ + iommus = <&iommu_vdo M4U_PORT_L19_JPGDEC_WDMA0>, + <&iommu_vdo M4U_PORT_L19_JPGDEC_BSDMA0>, + <&iommu_vdo M4U_PORT_L19_JPGDEC_WDMA1>, + <&iommu_vdo M4U_PORT_L19_JPGDEC_BSDMA1>, + <&iommu_vdo M4U_PORT_L19_JPGDEC_BUFF_OFFSET1>, + <&iommu_vdo M4U_PORT_L19_JPGDEC_BUFF_OFFSET0>; + interrupts = <GIC_SPI 344 IRQ_TYPE_LEVEL_HIGH 0>; + clocks = <&vencsys CLK_VENC_JPGDEC_C1>; + clock-names = "jpgdec"; + power-domains = <&spm MT8195_POWER_DOMAIN_VDEC1>; + }; + + jpgdec@1b040000 { + compatible = "mediatek,mt8195-jpgdec-hw"; + reg = <0 0x1b040000 0 0x10000>;/* JPGDEC_C2 */ + iommus = <&iommu_vpp M4U_PORT_L20_JPGDEC_WDMA0>, + <&iommu_vpp M4U_PORT_L20_JPGDEC_BSDMA0>, + <&iommu_vpp M4U_PORT_L20_JPGDEC_WDMA1>, + <&iommu_vpp M4U_PORT_L20_JPGDEC_BSDMA1>, + <&iommu_vpp M4U_PORT_L20_JPGDEC_BUFF_OFFSET1>, + <&iommu_vpp M4U_PORT_L20_JPGDEC_BUFF_OFFSET0>; + interrupts = <GIC_SPI 348 IRQ_TYPE_LEVEL_HIGH 0>; + clocks = <&vencsys_core1 CLK_VENC_CORE1_JPGDEC>; + clock-names = "jpgdec"; + power-domains = <&spm MT8195_POWER_DOMAIN_VDEC2>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/mediatek,mt8195-jpegenc.yaml b/Documentation/devicetree/bindings/media/mediatek,mt8195-jpegenc.yaml new file mode 100644 index 000000000000..95990539f7c0 --- /dev/null +++ b/Documentation/devicetree/bindings/media/mediatek,mt8195-jpegenc.yaml @@ -0,0 +1,147 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/mediatek,mt8195-jpegenc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek JPEG Encoder + +maintainers: + - kyrie wu <kyrie.wu@mediatek.corp-partner.google.com> + +description: + MediaTek JPEG Encoder is the JPEG encode hardware present in MediaTek SoCs + +properties: + compatible: + const: mediatek,mt8195-jpgenc + + power-domains: + maxItems: 1 + + iommus: + maxItems: 4 + description: + Points to the respective IOMMU block with master port as argument, see + Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details. + Ports are according to the HW. + + dma-ranges: + maxItems: 1 + description: | + Describes the physical address space of IOMMU maps to memory. + + "#address-cells": + const: 2 + + "#size-cells": + const: 2 + + ranges: true + +# Required child node: +patternProperties: + "^jpgenc@[0-9a-f]+$": + type: object + description: + The jpeg encoder hardware device node which should be added as subnodes to + the main jpeg node. + + properties: + compatible: + const: mediatek,mt8195-jpgenc-hw + + reg: + maxItems: 1 + + iommus: + minItems: 1 + maxItems: 32 + description: + List of the hardware port in respective IOMMU block for current Socs. + Refer to bindings/iommu/mediatek,iommu.yaml. + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: jpgenc + + power-domains: + maxItems: 1 + + required: + - compatible + - reg + - iommus + - interrupts + - clocks + - clock-names + - power-domains + + additionalProperties: false + +required: + - compatible + - power-domains + - iommus + - dma-ranges + - ranges + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/memory/mt8195-memory-port.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/clock/mt8195-clk.h> + #include <dt-bindings/power/mt8195-power.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + jpgenc-master { + compatible = "mediatek,mt8195-jpgenc"; + power-domains = <&spm MT8195_POWER_DOMAIN_VENC_CORE1>; + iommus = <&iommu_vpp M4U_PORT_L20_JPGENC_Y_RDMA>, + <&iommu_vpp M4U_PORT_L20_JPGENC_C_RDMA>, + <&iommu_vpp M4U_PORT_L20_JPGENC_Q_TABLE>, + <&iommu_vpp M4U_PORT_L20_JPGENC_BSDMA>; + dma-ranges = <0x1 0x0 0x0 0x40000000 0x0 0xfff00000>; + #address-cells = <2>; + #size-cells = <2>; + ranges; + + jpgenc@1a030000 { + compatible = "mediatek,mt8195-jpgenc-hw"; + reg = <0 0x1a030000 0 0x10000>; + iommus = <&iommu_vdo M4U_PORT_L19_JPGENC_Y_RDMA>, + <&iommu_vdo M4U_PORT_L19_JPGENC_C_RDMA>, + <&iommu_vdo M4U_PORT_L19_JPGENC_Q_TABLE>, + <&iommu_vdo M4U_PORT_L19_JPGENC_BSDMA>; + interrupts = <GIC_SPI 342 IRQ_TYPE_LEVEL_HIGH 0>; + clocks = <&vencsys CLK_VENC_JPGENC>; + clock-names = "jpgenc"; + power-domains = <&spm MT8195_POWER_DOMAIN_VENC>; + }; + + jpgenc@1b030000 { + compatible = "mediatek,mt8195-jpgenc-hw"; + reg = <0 0x1b030000 0 0x10000>; + iommus = <&iommu_vpp M4U_PORT_L20_JPGENC_Y_RDMA>, + <&iommu_vpp M4U_PORT_L20_JPGENC_C_RDMA>, + <&iommu_vpp M4U_PORT_L20_JPGENC_Q_TABLE>, + <&iommu_vpp M4U_PORT_L20_JPGENC_BSDMA>; + interrupts = <GIC_SPI 347 IRQ_TYPE_LEVEL_HIGH 0>; + clocks = <&vencsys_core1 CLK_VENC_CORE1_JPGENC>; + clock-names = "jpgenc"; + power-domains = <&spm MT8195_POWER_DOMAIN_VENC_CORE1>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/mediatek,vcodec-encoder.yaml b/Documentation/devicetree/bindings/media/mediatek,vcodec-encoder.yaml index 32aee09aea33..0f2ea8d9a10c 100644 --- a/Documentation/devicetree/bindings/media/mediatek,vcodec-encoder.yaml +++ b/Documentation/devicetree/bindings/media/mediatek,vcodec-encoder.yaml @@ -67,6 +67,12 @@ properties: power-domains: maxItems: 1 + "#address-cells": + const: 2 + + "#size-cells": + const: 2 + required: - compatible - reg @@ -84,7 +90,9 @@ allOf: contains: enum: - mediatek,mt8183-vcodec-enc + - mediatek,mt8188-vcodec-enc - mediatek,mt8192-vcodec-enc + - mediatek,mt8195-vcodec-enc then: required: @@ -107,7 +115,9 @@ allOf: compatible: enum: - mediatek,mt8173-vcodec-enc + - mediatek,mt8188-vcodec-enc - mediatek,mt8192-vcodec-enc + - mediatek,mt8195-vcodec-enc then: properties: @@ -118,7 +128,7 @@ allOf: clock-names: items: - const: venc_sel - else: # for vp8 hw decoder + else: # for vp8 hw encoder properties: clock: items: diff --git a/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.yaml b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.yaml index 5e8d001492cc..cfabf360f278 100644 --- a/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.yaml +++ b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.yaml @@ -22,6 +22,7 @@ properties: - items: - enum: - mediatek,mt7623-jpgdec + - mediatek,mt8188-jpgdec - const: mediatek,mt2701-jpgdec reg: diff --git a/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.yaml b/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.yaml index fc727300b493..c8412e8ab353 100644 --- a/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.yaml +++ b/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.yaml @@ -19,6 +19,7 @@ properties: - mediatek,mt2701-jpgenc - mediatek,mt8183-jpgenc - mediatek,mt8186-jpgenc + - mediatek,mt8188-jpgenc - const: mediatek,mtk-jpgenc reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/media/microchip,xisc.yaml b/Documentation/devicetree/bindings/media/microchip,xisc.yaml index 8b37fccab5e2..25f5f79d40ce 100644 --- a/Documentation/devicetree/bindings/media/microchip,xisc.yaml +++ b/Documentation/devicetree/bindings/media/microchip,xisc.yaml @@ -106,6 +106,7 @@ examples: #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/clock/at91.h> #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/media/video-interfaces.h> xisc: xisc@e1408000 { compatible = "microchip,sama7g5-isc"; @@ -118,7 +119,7 @@ examples: port { xisc_in: endpoint { - bus-type = <5>; /* Parallel */ + bus-type = <MEDIA_BUS_TYPE_PARALLEL>; remote-endpoint = <&csi2dc_out>; hsync-active = <1>; vsync-active = <1>; diff --git a/Documentation/devicetree/bindings/media/renesas,rzg2l-cru.yaml b/Documentation/devicetree/bindings/media/renesas,rzg2l-cru.yaml new file mode 100644 index 000000000000..7dde7967c886 --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,rzg2l-cru.yaml @@ -0,0 +1,157 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright (C) 2022 Renesas Electronics Corp. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/renesas,rzg2l-cru.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/G2L (and alike SoC's) Camera Data Receiving Unit (CRU) Image processing + +maintainers: + - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com> + +description: + The CRU image processing module is a data conversion module equipped with pixel + color space conversion, LUT, pixel format conversion, etc. An MIPI CSI-2 input and + parallel (including ITU-R BT.656) input are provided as the image sensor interface. + +properties: + compatible: + items: + - enum: + - renesas,r9a07g044-cru # RZ/G2{L,LC} + - renesas,r9a07g054-cru # RZ/V2L + - const: renesas,rzg2l-cru + + reg: + maxItems: 1 + + interrupts: + maxItems: 3 + + interrupt-names: + items: + - const: image_conv + - const: image_conv_err + - const: axi_mst_err + + clocks: + items: + - description: CRU Main clock + - description: CRU Register access clock + - description: CRU image transfer clock + + clock-names: + items: + - const: video + - const: apb + - const: axi + + power-domains: + maxItems: 1 + + resets: + items: + - description: CRU_PRESETN reset terminal + - description: CRU_ARESETN reset terminal + + reset-names: + items: + - const: presetn + - const: aresetn + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port node, single endpoint describing a parallel input source. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + hsync-active: true + vsync-active: true + bus-width: true + data-shift: true + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: + Input port node, describing the Image Processing module connected to the + CSI-2 receiver. + + required: + - port@0 + - port@1 + +required: + - compatible + - reg + - interrupts + - interrupt-names + - clocks + - clock-names + - resets + - reset-names + - power-domains + +additionalProperties: false + +examples: + # Device node example with CSI-2 + - | + #include <dt-bindings/clock/r9a07g044-cpg.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + cru: video@10830000 { + compatible = "renesas,r9a07g044-cru", "renesas,rzg2l-cru"; + reg = <0x10830000 0x400>; + interrupts = <GIC_SPI 167 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 168 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 169 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "image_conv", "image_conv_err", "axi_mst_err"; + clocks = <&cpg CPG_MOD R9A07G044_CRU_VCLK>, + <&cpg CPG_MOD R9A07G044_CRU_PCLK>, + <&cpg CPG_MOD R9A07G044_CRU_ACLK>; + clock-names = "video", "apb", "axi"; + power-domains = <&cpg>; + resets = <&cpg R9A07G044_CRU_PRESETN>, + <&cpg R9A07G044_CRU_ARESETN>; + reset-names = "presetn", "aresetn"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + + cru_parallel_in: endpoint@0 { + reg = <0>; + remote-endpoint= <&ov5642>; + hsync-active = <1>; + vsync-active = <1>; + }; + }; + + port@1 { + #address-cells = <1>; + #size-cells = <0>; + reg = <1>; + + cru_csi_in: endpoint@0 { + reg = <0>; + remote-endpoint= <&csi_cru_in>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/renesas,rzg2l-csi2.yaml b/Documentation/devicetree/bindings/media/renesas,rzg2l-csi2.yaml new file mode 100644 index 000000000000..67eea2ac1d22 --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,rzg2l-csi2.yaml @@ -0,0 +1,149 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright (C) 2022 Renesas Electronics Corp. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/renesas,rzg2l-csi2.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/G2L (and alike SoC's) MIPI CSI-2 receiver + +maintainers: + - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com> + +description: + The CSI-2 receiver device provides MIPI CSI-2 capabilities for the Renesas RZ/G2L + (and alike SoCs). MIPI CSI-2 is part of the CRU block which is used in conjunction + with the Image Processing module, which provides the video capture capabilities. + +properties: + compatible: + items: + - enum: + - renesas,r9a07g044-csi2 # RZ/G2{L,LC} + - renesas,r9a07g054-csi2 # RZ/V2L + - const: renesas,rzg2l-csi2 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Internal clock for connecting CRU and MIPI + - description: CRU Main clock + - description: CRU Register access clock + + clock-names: + items: + - const: system + - const: video + - const: apb + + power-domains: + maxItems: 1 + + resets: + items: + - description: CRU_PRESETN reset terminal + - description: CRU_CMN_RSTB reset terminal + + reset-names: + items: + - const: presetn + - const: cmn-rstb + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port node, single endpoint describing the CSI-2 transmitter. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: + minItems: 1 + maxItems: 4 + items: + maximum: 4 + + required: + - clock-lanes + - data-lanes + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: + Output port node, Image Processing block connected to the CSI-2 receiver. + + required: + - port@0 + - port@1 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - power-domains + - resets + - reset-names + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r9a07g044-cpg.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + csi: csi@10830400 { + compatible = "renesas,r9a07g044-csi2", "renesas,rzg2l-csi2"; + reg = <0x10830400 0xfc00>; + interrupts = <GIC_SPI 166 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD R9A07G044_CRU_SYSCLK>, + <&cpg CPG_MOD R9A07G044_CRU_VCLK>, + <&cpg CPG_MOD R9A07G044_CRU_PCLK>; + clock-names = "system", "video", "apb"; + power-domains = <&cpg>; + resets = <&cpg R9A07G044_CRU_PRESETN>, + <&cpg R9A07G044_CRU_CMN_RSTB>; + reset-names = "presetn", "cmn-rstb"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + csi2_in: endpoint { + clock-lanes = <0>; + data-lanes = <1 2>; + remote-endpoint = <&ov5645_ep>; + }; + }; + + port@1 { + #address-cells = <1>; + #size-cells = <0>; + + reg = <1>; + + csi2cru: endpoint@0 { + reg = <0>; + remote-endpoint = <&crucsi2>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/s5p-mfc.txt b/Documentation/devicetree/bindings/media/s5p-mfc.txt index aa54c8159d9f..8eb90c043d5d 100644 --- a/Documentation/devicetree/bindings/media/s5p-mfc.txt +++ b/Documentation/devicetree/bindings/media/s5p-mfc.txt @@ -10,10 +10,12 @@ Required properties: - compatible : value should be either one among the following (a) "samsung,mfc-v5" for MFC v5 present in Exynos4 SoCs (b) "samsung,mfc-v6" for MFC v6 present in Exynos5 SoCs - (c) "samsung,mfc-v7" for MFC v7 present in Exynos5420 SoC - (d) "samsung,mfc-v8" for MFC v8 present in Exynos5800 SoC - (e) "samsung,exynos5433-mfc" for MFC v8 present in Exynos5433 SoC - (f) "samsung,mfc-v10" for MFC v10 present in Exynos7880 SoC + (c) "samsung,exynos3250-mfc", "samsung,mfc-v7" for MFC v7 + present in Exynos3250 SoC + (d) "samsung,mfc-v7" for MFC v7 present in Exynos5420 SoC + (e) "samsung,mfc-v8" for MFC v8 present in Exynos5800 SoC + (f) "samsung,exynos5433-mfc" for MFC v8 present in Exynos5433 SoC + (g) "samsung,mfc-v10" for MFC v10 present in Exynos7880 SoC - reg : Physical base address of the IP registers and length of memory mapped region. diff --git a/Documentation/devicetree/bindings/media/samsung-s5c73m3.txt b/Documentation/devicetree/bindings/media/samsung-s5c73m3.txt index 21f31fdf5543..f0ea9adad442 100644 --- a/Documentation/devicetree/bindings/media/samsung-s5c73m3.txt +++ b/Documentation/devicetree/bindings/media/samsung-s5c73m3.txt @@ -76,7 +76,7 @@ i2c@138a000000 { clock-frequency = <24000000>; clocks = <&clk 0>; clock-names = "cis_extclk"; - reset-gpios = <&gpf1 3 1>; + xshutdown-gpios = <&gpf1 3 1>; standby-gpios = <&gpm0 1 1>; port { s5c73m3_ep: endpoint { diff --git a/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml b/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml index 9c1262a276b5..e80fcdf280f0 100644 --- a/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml +++ b/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml @@ -90,7 +90,9 @@ examples: - | #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/clock/stm32mp1-clks.h> + #include <dt-bindings/media/video-interfaces.h> #include <dt-bindings/reset/stm32mp1-resets.h> + dcmi: dcmi@4c006000 { compatible = "st,stm32-dcmi"; reg = <0x4c006000 0x400>; @@ -104,7 +106,7 @@ examples: port { dcmi_0: endpoint { remote-endpoint = <&ov5640_0>; - bus-type = <5>; + bus-type = <MEDIA_BUS_TYPE_PARALLEL>; bus-width = <8>; hsync-active = <0>; vsync-active = <0>; diff --git a/Documentation/devicetree/bindings/media/video-interfaces.yaml b/Documentation/devicetree/bindings/media/video-interfaces.yaml index 68c3b9871cf3..34bdad028180 100644 --- a/Documentation/devicetree/bindings/media/video-interfaces.yaml +++ b/Documentation/devicetree/bindings/media/video-interfaces.yaml @@ -145,9 +145,10 @@ properties: pclk-sample: $ref: /schemas/types.yaml#/definitions/uint32 - enum: [ 0, 1 ] + enum: [ 0, 1, 2 ] description: - Sample data on rising (1) or falling (0) edge of the pixel clock signal. + Sample data on falling (0), rising (1) or both (2) edges of the pixel + clock signal. sync-on-green-active: $ref: /schemas/types.yaml#/definitions/uint32 diff --git a/Documentation/devicetree/bindings/memory-controllers/arm,pl353-smc.yaml b/Documentation/devicetree/bindings/memory-controllers/arm,pl35x-smc.yaml index 01c9acf9275d..bd23257fe021 100644 --- a/Documentation/devicetree/bindings/memory-controllers/arm,pl353-smc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/arm,pl35x-smc.yaml @@ -1,26 +1,31 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/memory-controllers/arm,pl353-smc.yaml# +$id: http://devicetree.org/schemas/memory-controllers/arm,pl35x-smc.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: ARM PL353 Static Memory Controller (SMC) device-tree bindings +title: Arm PL35x Series Static Memory Controller (SMC) maintainers: - Miquel Raynal <miquel.raynal@bootlin.com> - Naga Sureshkumar Relli <naga.sureshkumar.relli@xilinx.com> -description: - The PL353 Static Memory Controller is a bus where you can connect two kinds +description: | + The PL35x Static Memory Controller is a bus where you can connect two kinds of memory interfaces, which are NAND and memory mapped interfaces (such as - SRAM or NOR). + SRAM or NOR) depending on the specific configuration. + + The TRM is available here: + https://documentation-service.arm.com/static/5e8e2524fd977155116a58aa # We need a select here so we don't match all nodes with 'arm,primecell' select: properties: compatible: contains: - const: arm,pl353-smc-r2p1 + enum: + - arm,pl353-smc-r2p1 + - arm,pl354 required: - compatible @@ -30,7 +35,9 @@ properties: compatible: items: - - const: arm,pl353-smc-r2p1 + - enum: + - arm,pl353-smc-r2p1 + - arm,pl354 - const: arm,primecell "#address-cells": @@ -46,30 +53,25 @@ properties: The three chip select regions are defined in 'ranges'. clocks: - items: - - description: clock for the memory device bus - - description: main clock of the SMC + minItems: 1 + maxItems: 2 clock-names: - items: - - const: memclk - - const: apb_pclk + minItems: 1 + maxItems: 2 ranges: minItems: 1 - description: | - Memory bus areas for interacting with the devices. Reflects - the memory layout with four integer values following: - <cs-number> 0 <offset> <size> - items: - - description: NAND bank 0 - - description: NOR/SRAM bank 0 - - description: NOR/SRAM bank 1 + maxItems: 8 - interrupts: true + interrupts: + minItems: 1 + items: + - description: Combined or Memory interface 0 IRQ + - description: Memory interface 1 IRQ patternProperties: - "@[0-3],[a-f0-9]+$": + "@[0-7],[a-f0-9]+$": type: object description: | The child device node represents the controller connected to the SMC @@ -87,7 +89,7 @@ patternProperties: - description: | Chip-select ID, as in the parent range property. minimum: 0 - maximum: 2 + maximum: 7 - description: | Offset of the memory region requested by the device. - description: | @@ -102,12 +104,36 @@ required: - reg - clock-names - clocks - - "#address-cells" - - "#size-cells" - - ranges additionalProperties: false +allOf: + - if: + properties: + compatible: + contains: + const: arm,pl354 + then: + properties: + clocks: + # According to TRM, really should be 3 clocks + maxItems: 1 + + clock-names: + const: apb_pclk + + else: + properties: + clocks: + items: + - description: clock for the memory device bus + - description: main clock of the SMC + + clock-names: + items: + - const: memclk + - const: apb_pclk + examples: - | smcc: memory-controller@e000e000 { diff --git a/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr-channel.yaml b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr-channel.yaml new file mode 100644 index 000000000000..34b5bd153f63 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr-channel.yaml @@ -0,0 +1,146 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/ddr/jedec,lpddr-channel.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: LPDDR channel with chip/rank topology description + +description: + An LPDDR channel is a completely independent set of LPDDR pins (DQ, CA, CS, + CK, etc.) that connect one or more LPDDR chips to a host system. The main + purpose of this node is to overall LPDDR topology of the system, including the + amount of individual LPDDR chips and the ranks per chip. + +maintainers: + - Julius Werner <jwerner@chromium.org> + +properties: + compatible: + enum: + - jedec,lpddr2-channel + - jedec,lpddr3-channel + - jedec,lpddr4-channel + - jedec,lpddr5-channel + + io-width: + description: + The number of DQ pins in the channel. If this number is different + from (a multiple of) the io-width of the LPDDR chip, that means that + multiple instances of that type of chip are wired in parallel on this + channel (with the channel's DQ pins split up between the different + chips, and the CA, CS, etc. pins of the different chips all shorted + together). This means that the total physical memory controlled by a + channel is equal to the sum of the densities of each rank on the + connected LPDDR chip, times the io-width of the channel divided by + the io-width of the LPDDR chip. + enum: + - 8 + - 16 + - 32 + - 64 + - 128 + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + +patternProperties: + "^rank@[0-9]+$": + type: object + description: + Each physical LPDDR chip may have one or more ranks. Ranks are + internal but fully independent sub-units of the chip. Each LPDDR bus + transaction on the channel targets exactly one rank, based on the + state of the CS pins. Different ranks may have different densities and + timing requirements. + required: + - reg + +allOf: + - if: + properties: + compatible: + contains: + const: jedec,lpddr2-channel + then: + patternProperties: + "^rank@[0-9]+$": + $ref: /schemas/memory-controllers/ddr/jedec,lpddr2.yaml# + - if: + properties: + compatible: + contains: + const: jedec,lpddr3-channel + then: + patternProperties: + "^rank@[0-9]+$": + $ref: /schemas/memory-controllers/ddr/jedec,lpddr3.yaml# + - if: + properties: + compatible: + contains: + const: jedec,lpddr4-channel + then: + patternProperties: + "^rank@[0-9]+$": + $ref: /schemas/memory-controllers/ddr/jedec,lpddr4.yaml# + - if: + properties: + compatible: + contains: + const: jedec,lpddr5-channel + then: + patternProperties: + "^rank@[0-9]+$": + $ref: /schemas/memory-controllers/ddr/jedec,lpddr5.yaml# + +required: + - compatible + - io-width + - "#address-cells" + - "#size-cells" + +additionalProperties: false + +examples: + - | + lpddr-channel0 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "jedec,lpddr3-channel"; + io-width = <32>; + + rank@0 { + compatible = "lpddr3-ff,0100", "jedec,lpddr3"; + reg = <0>; + density = <8192>; + io-width = <16>; + revision-id = <1 0>; + }; + }; + + lpddr-channel1 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "jedec,lpddr4-channel"; + io-width = <32>; + + rank@0 { + compatible = "lpddr4-05,0301", "jedec,lpddr4"; + reg = <0>; + density = <4096>; + io-width = <32>; + revision-id = <3 1>; + }; + + rank@1 { + compatible = "lpddr4-05,0301", "jedec,lpddr4"; + reg = <1>; + density = <2048>; + io-width = <32>; + revision-id = <3 1>; + }; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr-props.yaml b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr-props.yaml new file mode 100644 index 000000000000..30267ce70124 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr-props.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/ddr/jedec,lpddr-props.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common properties for LPDDR types + +description: + Different LPDDR types generally use the same properties and only differ in the + range of legal values for each. This file defines the common parts that can be + reused for each type. Nodes using this schema should generally be nested under + an LPDDR channel node. + +maintainers: + - Krzysztof Kozlowski <krzk@kernel.org> + +properties: + compatible: + description: + Compatible strings can be either explicit vendor names and part numbers + (e.g. elpida,ECB240ABACN), or generated strings of the form + lpddrX-YY,ZZZZ where X is the LPDDR version, YY is the manufacturer ID + (from MR5) and ZZZZ is the revision ID (from MR6 and MR7). Both IDs are + formatted in lower case hexadecimal representation with leading zeroes. + The latter form can be useful when LPDDR nodes are created at runtime by + boot firmware that doesn't have access to static part number information. + + reg: + description: + The rank number of this LPDDR rank when used as a subnode to an LPDDR + channel. + minimum: 0 + maximum: 3 + + revision-id: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: + Revision IDs read from Mode Register 6 and 7. One byte per uint32 cell (i.e. <MR6 MR7>). + maxItems: 2 + items: + minimum: 0 + maximum: 255 + + density: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Density in megabits of SDRAM chip. Decoded from Mode Register 8. + enum: + - 64 + - 128 + - 256 + - 512 + - 1024 + - 2048 + - 3072 + - 4096 + - 6144 + - 8192 + - 12288 + - 16384 + - 24576 + - 32768 + + io-width: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + IO bus width in bits of SDRAM chip. Decoded from Mode Register 8. + enum: + - 8 + - 16 + - 32 + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr2.yaml b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr2.yaml index 9d78f140609b..a237bc259273 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr2.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr2.yaml @@ -9,6 +9,9 @@ title: LPDDR2 SDRAM compliant to JEDEC JESD209-2 maintainers: - Krzysztof Kozlowski <krzk@kernel.org> +allOf: + - $ref: jedec,lpddr-props.yaml# + properties: compatible: oneOf: @@ -17,13 +20,15 @@ properties: - elpida,ECB240ABACN - elpida,B8132B2PB-6D-F - enum: - - jedec,lpddr2-s4 - - items: - - enum: + - jedec,lpddr2-nvm - jedec,lpddr2-s2 + - jedec,lpddr2-s4 - items: + - pattern: "^lpddr2-[0-9a-f]{2},[0-9a-f]{4}$" - enum: - jedec,lpddr2-nvm + - jedec,lpddr2-s2 + - jedec,lpddr2-s4 revision-id1: $ref: /schemas/types.yaml#/definitions/uint32 @@ -41,41 +46,6 @@ properties: Property is deprecated, use revision-id instead. deprecated: true - revision-id: - $ref: /schemas/types.yaml#/definitions/uint32-array - description: | - Revision IDs read from Mode Register 6 and 7. One byte per uint32 cell (i.e. <MR6 MR7>). - minItems: 2 - maxItems: 2 - items: - minimum: 0 - maximum: 255 - - density: - $ref: /schemas/types.yaml#/definitions/uint32 - description: | - Density in megabits of SDRAM chip. Obtained from device datasheet. - enum: - - 64 - - 128 - - 256 - - 512 - - 1024 - - 2048 - - 4096 - - 8192 - - 16384 - - 32768 - - io-width: - $ref: /schemas/types.yaml#/definitions/uint32 - description: | - IO bus width in bits of SDRAM chip. Obtained from device datasheet. - enum: - - 32 - - 16 - - 8 - tRRD-min-tck: $ref: /schemas/types.yaml#/definitions/uint32 maximum: 16 @@ -168,7 +138,7 @@ required: - density - io-width -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr3.yaml b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr3.yaml index 48908a19473c..e328a1195ba6 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr3.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr3.yaml @@ -9,35 +9,24 @@ title: LPDDR3 SDRAM compliant to JEDEC JESD209-3 maintainers: - Krzysztof Kozlowski <krzk@kernel.org> +allOf: + - $ref: jedec,lpddr-props.yaml# + properties: compatible: - items: - - enum: - - samsung,K3QF2F20DB - - const: jedec,lpddr3 + oneOf: + - items: + - enum: + - samsung,K3QF2F20DB + - const: jedec,lpddr3 + - items: + - pattern: "^lpddr3-[0-9a-f]{2},[0-9a-f]{4}$" + - const: jedec,lpddr3 '#address-cells': const: 1 deprecated: true - density: - $ref: /schemas/types.yaml#/definitions/uint32 - description: | - Density in megabits of SDRAM chip. - enum: - - 4096 - - 8192 - - 16384 - - 32768 - - io-width: - $ref: /schemas/types.yaml#/definitions/uint32 - description: | - IO bus width in bits of SDRAM chip. - enum: - - 32 - - 16 - manufacturer-id: $ref: /schemas/types.yaml#/definitions/uint32 description: | @@ -45,15 +34,6 @@ properties: deprecated, manufacturer should be derived from the compatible. deprecated: true - revision-id: - $ref: /schemas/types.yaml#/definitions/uint32-array - minItems: 2 - maxItems: 2 - items: - maximum: 255 - description: | - Revision value of SDRAM chip read from Mode Registers 6 and 7. - '#size-cells': const: 0 deprecated: true @@ -206,7 +186,7 @@ required: - density - io-width -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr4.yaml b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr4.yaml new file mode 100644 index 000000000000..a078892fecee --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr4.yaml @@ -0,0 +1,35 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/ddr/jedec,lpddr4.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: LPDDR4 SDRAM compliant to JEDEC JESD209-4 + +maintainers: + - Krzysztof Kozlowski <krzk@kernel.org> + +allOf: + - $ref: jedec,lpddr-props.yaml# + +properties: + compatible: + items: + - pattern: "^lpddr4-[0-9a-f]{2},[0-9a-f]{4}$" + - const: jedec,lpddr4 + +required: + - compatible + - density + - io-width + +unevaluatedProperties: false + +examples: + - | + lpddr { + compatible = "lpddr4-ff,0100", "jedec,lpddr4"; + density = <8192>; + io-width = <16>; + revision-id = <1 0>; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr5.yaml b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr5.yaml new file mode 100644 index 000000000000..e441dac5f154 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr5.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/ddr/jedec,lpddr5.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: LPDDR5 SDRAM compliant to JEDEC JESD209-5 + +maintainers: + - Krzysztof Kozlowski <krzk@kernel.org> + +allOf: + - $ref: jedec,lpddr-props.yaml# + +properties: + compatible: + items: + - pattern: "^lpddr5-[0-9a-f]{2},[0-9a-f]{4}$" + - const: jedec,lpddr5 + + serial-id: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: + Serial IDs read from Mode Registers 47 through 54. One byte per uint32 + cell (i.e. <MR47 MR48 MR49 MR50 MR51 MR52 MR53 MR54>). + maxItems: 8 + items: + minimum: 0 + maximum: 255 + +required: + - compatible + - density + - io-width + +unevaluatedProperties: false + +examples: + - | + lpddr { + compatible = "lpddr5-01,0200", "jedec,lpddr5"; + density = <8192>; + io-width = <8>; + revision-id = <2 0>; + serial-id = <3 1 0 0 0 0 0 0>; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/mc-peripheral-props.yaml b/Documentation/devicetree/bindings/memory-controllers/mc-peripheral-props.yaml new file mode 100644 index 000000000000..53ae995462db --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/mc-peripheral-props.yaml @@ -0,0 +1,38 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/mc-peripheral-props.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Peripheral-specific properties for a Memory Controller bus. + +description: + Many Memory Controllers need to add properties to peripheral devices. + They could be common properties like reg or they could be controller + specific like delay in clock or data lines, etc. These properties need + to be defined in the peripheral node because they are per-peripheral + and there can be multiple peripherals attached to a controller. All + those properties are listed here. The controller specific properties + should go in their own separate schema that should be referenced + from here. + +maintainers: + - Marek Vasut <marex@denx.de> + +properties: + reg: + description: Bank number, base address and size of the device. + + bank-width: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Bank width of the device, in bytes. + enum: [1, 2, 4] + +required: + - reg + +# The controller specific properties go here. +allOf: + - $ref: st,stm32-fmc2-ebi-props.yaml# + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml index 645249ea21d1..30a403b1b79a 100644 --- a/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml @@ -44,6 +44,11 @@ properties: - items: - enum: + - renesas,r8a779g0-rpc-if # R-Car V4H + - const: renesas,rcar-gen4-rpc-if # a generic R-Car gen4 device + + - items: + - enum: - renesas,r9a07g043-rpc-if # RZ/G2UL - renesas,r9a07g044-rpc-if # RZ/G2{L,LC} - renesas,r9a07g054-rpc-if # RZ/V2L diff --git a/Documentation/devicetree/bindings/memory-controllers/st,stm32-fmc2-ebi-props.yaml b/Documentation/devicetree/bindings/memory-controllers/st,stm32-fmc2-ebi-props.yaml new file mode 100644 index 000000000000..475e4095068c --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/st,stm32-fmc2-ebi-props.yaml @@ -0,0 +1,144 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/st,stm32-fmc2-ebi-props.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Peripheral properties for ST FMC2 Controller + +maintainers: + - Christophe Kerello <christophe.kerello@foss.st.com> + - Marek Vasut <marex@denx.de> + +properties: + st,fmc2-ebi-cs-transaction-type: + description: | + Select one of the transactions type supported + 0: Asynchronous mode 1 SRAM/FRAM. + 1: Asynchronous mode 1 PSRAM. + 2: Asynchronous mode A SRAM/FRAM. + 3: Asynchronous mode A PSRAM. + 4: Asynchronous mode 2 NOR. + 5: Asynchronous mode B NOR. + 6: Asynchronous mode C NOR. + 7: Asynchronous mode D NOR. + 8: Synchronous read synchronous write PSRAM. + 9: Synchronous read asynchronous write PSRAM. + 10: Synchronous read synchronous write NOR. + 11: Synchronous read asynchronous write NOR. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 11 + + st,fmc2-ebi-cs-cclk-enable: + description: Continuous clock enable (first bank must be configured + in synchronous mode). The FMC_CLK is generated continuously + during asynchronous and synchronous access. By default, the + FMC_CLK is only generated during synchronous access. + $ref: /schemas/types.yaml#/definitions/flag + + st,fmc2-ebi-cs-mux-enable: + description: Address/Data multiplexed on databus (valid only with + NOR and PSRAM transactions type). By default, Address/Data + are not multiplexed. + $ref: /schemas/types.yaml#/definitions/flag + + st,fmc2-ebi-cs-buswidth: + description: Data bus width + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 8, 16 ] + default: 16 + + st,fmc2-ebi-cs-waitpol-high: + description: Wait signal polarity (NWAIT signal active high). + By default, NWAIT is active low. + $ref: /schemas/types.yaml#/definitions/flag + + st,fmc2-ebi-cs-waitcfg-enable: + description: The NWAIT signal indicates wheither the data from the + device are valid or if a wait state must be inserted when accessing + the device in synchronous mode. By default, the NWAIT signal is + active one data cycle before wait state. + $ref: /schemas/types.yaml#/definitions/flag + + st,fmc2-ebi-cs-wait-enable: + description: The NWAIT signal is enabled (its level is taken into + account after the programmed latency period to insert wait states + if asserted). By default, the NWAIT signal is disabled. + $ref: /schemas/types.yaml#/definitions/flag + + st,fmc2-ebi-cs-asyncwait-enable: + description: The NWAIT signal is taken into account during asynchronous + transactions. By default, the NWAIT signal is not taken into account + during asynchronous transactions. + $ref: /schemas/types.yaml#/definitions/flag + + st,fmc2-ebi-cs-cpsize: + description: CRAM page size. The controller splits the burst access + when the memory page is reached. By default, no burst split when + crossing page boundary. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 128, 256, 512, 1024 ] + default: 0 + + st,fmc2-ebi-cs-byte-lane-setup-ns: + description: This property configures the byte lane setup timing + defined in nanoseconds from NBLx low to Chip Select NEx low. + + st,fmc2-ebi-cs-address-setup-ns: + description: This property defines the duration of the address setup + phase in nanoseconds used for asynchronous read/write transactions. + + st,fmc2-ebi-cs-address-hold-ns: + description: This property defines the duration of the address hold + phase in nanoseconds used for asynchronous multiplexed read/write + transactions. + + st,fmc2-ebi-cs-data-setup-ns: + description: This property defines the duration of the data setup phase + in nanoseconds used for asynchronous read/write transactions. + + st,fmc2-ebi-cs-bus-turnaround-ns: + description: This property defines the delay in nanoseconds between the + end of current read/write transaction and the next transaction. + + st,fmc2-ebi-cs-data-hold-ns: + description: This property defines the duration of the data hold phase + in nanoseconds used for asynchronous read/write transactions. + + st,fmc2-ebi-cs-clk-period-ns: + description: This property defines the FMC_CLK output signal period in + nanoseconds. + + st,fmc2-ebi-cs-data-latency-ns: + description: This property defines the data latency before reading or + writing the first data in nanoseconds. + + st,fmc2-ebi-cs-write-address-setup-ns: + description: This property defines the duration of the address setup + phase in nanoseconds used for asynchronous write transactions. + + st,fmc2-ebi-cs-write-address-hold-ns: + description: This property defines the duration of the address hold + phase in nanoseconds used for asynchronous multiplexed write + transactions. + + st,fmc2-ebi-cs-write-data-setup-ns: + description: This property defines the duration of the data setup + phase in nanoseconds used for asynchronous write transactions. + + st,fmc2-ebi-cs-write-bus-turnaround-ns: + description: This property defines the delay between the end of current + write transaction and the next transaction in nanoseconds. + + st,fmc2-ebi-cs-write-data-hold-ns: + description: This property defines the duration of the data hold phase + in nanoseconds used for asynchronous write transactions. + + st,fmc2-ebi-cs-max-low-pulse-ns: + description: This property defines the maximum chip select low pulse + duration in nanoseconds for synchronous transactions. When this timing + reaches 0, the controller splits the current access, toggles NE to + allow device refresh and restarts a new access. + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/memory-controllers/st,stm32-fmc2-ebi.yaml b/Documentation/devicetree/bindings/memory-controllers/st,stm32-fmc2-ebi.yaml index 6b516d3895af..d71af02b7f16 100644 --- a/Documentation/devicetree/bindings/memory-controllers/st,stm32-fmc2-ebi.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/st,stm32-fmc2-ebi.yaml @@ -48,143 +48,7 @@ properties: patternProperties: "^.*@[0-4],[a-f0-9]+$": type: object - - properties: - reg: - description: Bank number, base address and size of the device. - - st,fmc2-ebi-cs-transaction-type: - description: | - Select one of the transactions type supported - 0: Asynchronous mode 1 SRAM/FRAM. - 1: Asynchronous mode 1 PSRAM. - 2: Asynchronous mode A SRAM/FRAM. - 3: Asynchronous mode A PSRAM. - 4: Asynchronous mode 2 NOR. - 5: Asynchronous mode B NOR. - 6: Asynchronous mode C NOR. - 7: Asynchronous mode D NOR. - 8: Synchronous read synchronous write PSRAM. - 9: Synchronous read asynchronous write PSRAM. - 10: Synchronous read synchronous write NOR. - 11: Synchronous read asynchronous write NOR. - $ref: /schemas/types.yaml#/definitions/uint32 - minimum: 0 - maximum: 11 - - st,fmc2-ebi-cs-cclk-enable: - description: Continuous clock enable (first bank must be configured - in synchronous mode). The FMC_CLK is generated continuously - during asynchronous and synchronous access. By default, the - FMC_CLK is only generated during synchronous access. - $ref: /schemas/types.yaml#/definitions/flag - - st,fmc2-ebi-cs-mux-enable: - description: Address/Data multiplexed on databus (valid only with - NOR and PSRAM transactions type). By default, Address/Data - are not multiplexed. - $ref: /schemas/types.yaml#/definitions/flag - - st,fmc2-ebi-cs-buswidth: - description: Data bus width - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [ 8, 16 ] - default: 16 - - st,fmc2-ebi-cs-waitpol-high: - description: Wait signal polarity (NWAIT signal active high). - By default, NWAIT is active low. - $ref: /schemas/types.yaml#/definitions/flag - - st,fmc2-ebi-cs-waitcfg-enable: - description: The NWAIT signal indicates wheither the data from the - device are valid or if a wait state must be inserted when accessing - the device in synchronous mode. By default, the NWAIT signal is - active one data cycle before wait state. - $ref: /schemas/types.yaml#/definitions/flag - - st,fmc2-ebi-cs-wait-enable: - description: The NWAIT signal is enabled (its level is taken into - account after the programmed latency period to insert wait states - if asserted). By default, the NWAIT signal is disabled. - $ref: /schemas/types.yaml#/definitions/flag - - st,fmc2-ebi-cs-asyncwait-enable: - description: The NWAIT signal is taken into account during asynchronous - transactions. By default, the NWAIT signal is not taken into account - during asynchronous transactions. - $ref: /schemas/types.yaml#/definitions/flag - - st,fmc2-ebi-cs-cpsize: - description: CRAM page size. The controller splits the burst access - when the memory page is reached. By default, no burst split when - crossing page boundary. - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [ 0, 128, 256, 512, 1024 ] - default: 0 - - st,fmc2-ebi-cs-byte-lane-setup-ns: - description: This property configures the byte lane setup timing - defined in nanoseconds from NBLx low to Chip Select NEx low. - - st,fmc2-ebi-cs-address-setup-ns: - description: This property defines the duration of the address setup - phase in nanoseconds used for asynchronous read/write transactions. - - st,fmc2-ebi-cs-address-hold-ns: - description: This property defines the duration of the address hold - phase in nanoseconds used for asynchronous multiplexed read/write - transactions. - - st,fmc2-ebi-cs-data-setup-ns: - description: This property defines the duration of the data setup phase - in nanoseconds used for asynchronous read/write transactions. - - st,fmc2-ebi-cs-bus-turnaround-ns: - description: This property defines the delay in nanoseconds between the - end of current read/write transaction and the next transaction. - - st,fmc2-ebi-cs-data-hold-ns: - description: This property defines the duration of the data hold phase - in nanoseconds used for asynchronous read/write transactions. - - st,fmc2-ebi-cs-clk-period-ns: - description: This property defines the FMC_CLK output signal period in - nanoseconds. - - st,fmc2-ebi-cs-data-latency-ns: - description: This property defines the data latency before reading or - writing the first data in nanoseconds. - - st,fmc2_ebi-cs-write-address-setup-ns: - description: This property defines the duration of the address setup - phase in nanoseconds used for asynchronous write transactions. - - st,fmc2-ebi-cs-write-address-hold-ns: - description: This property defines the duration of the address hold - phase in nanoseconds used for asynchronous multiplexed write - transactions. - - st,fmc2-ebi-cs-write-data-setup-ns: - description: This property defines the duration of the data setup - phase in nanoseconds used for asynchronous write transactions. - - st,fmc2-ebi-cs-write-bus-turnaround-ns: - description: This property defines the delay between the end of current - write transaction and the next transaction in nanoseconds. - - st,fmc2-ebi-cs-write-data-hold-ns: - description: This property defines the duration of the data hold phase - in nanoseconds used for asynchronous write transactions. - - st,fmc2-ebi-cs-max-low-pulse-ns: - description: This property defines the maximum chip select low pulse - duration in nanoseconds for synchronous transactions. When this timing - reaches 0, the controller splits the current access, toggles NE to - allow device refresh and restarts a new access. - - required: - - reg + $ref: mc-peripheral-props.yaml# required: - "#address-cells" diff --git a/Documentation/devicetree/bindings/memory-controllers/ti,gpmc-child.yaml b/Documentation/devicetree/bindings/memory-controllers/ti,gpmc-child.yaml index 6e3995bb1630..4a257fac577e 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ti,gpmc-child.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/ti,gpmc-child.yaml @@ -230,6 +230,13 @@ properties: Wait-pin used by client. Must be less than "gpmc,num-waitpins". $ref: /schemas/types.yaml#/definitions/uint32 + ti,wait-pin-polarity: + description: | + Set the desired polarity for the selected wait pin. + 0 for active low, 1 for active high. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + gpmc,wait-on-read: description: Enables wait monitoring on reads. type: boolean diff --git a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml index 04962bb29576..3d5efa5578d1 100644 --- a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml +++ b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml @@ -20,19 +20,21 @@ properties: compatible: oneOf: - description: - For implementations of the EC is connected through I2C. + For implementations of the EC connected through I2C. const: google,cros-ec-i2c - description: - For implementations of the EC is connected through SPI. + For implementations of the EC connected through SPI. const: google,cros-ec-spi - description: - For implementations of the EC is connected through RPMSG. + For implementations of the FPMCU connected through SPI. + items: + - const: google,cros-ec-fp + - const: google,cros-ec-spi + - description: + For implementations of the EC connected through RPMSG. const: google,cros-ec-rpmsg - controller-data: - description: - SPI controller data, see bindings/spi/samsung,spi-peripheral-props.yaml - type: object + controller-data: true google,cros-ec-spi-pre-delay: description: @@ -62,8 +64,7 @@ properties: the SCP. $ref: "/schemas/types.yaml#/definitions/string" - spi-max-frequency: - description: Maximum SPI frequency of the device in Hz. + spi-max-frequency: true reg: maxItems: 1 @@ -71,6 +72,15 @@ properties: interrupts: maxItems: 1 + reset-gpios: + maxItems: 1 + + boot0-gpios: + maxItems: 1 + description: Assert for bootloader mode. + + vdd-supply: true + wakeup-source: description: Button can wake-up the system. @@ -155,18 +165,67 @@ allOf: - if: properties: compatible: - contains: - enum: - - google,cros-ec-i2c - - google,cros-ec-rpmsg + not: + contains: + const: google,cros-ec-spi then: properties: + controller-data: false google,cros-ec-spi-pre-delay: false google,cros-ec-spi-msg-delay: false spi-max-frequency: false else: $ref: /schemas/spi/spi-peripheral-props.yaml + - if: + properties: + compatible: + not: + contains: + const: google,cros-ec-rpmsg + then: + properties: + mediatek,rpmsg-name: false + + required: + - reg + - interrupts + + - if: + properties: + compatible: + contains: + const: google,cros-ec-fp + then: + properties: + '#address-cells': false + '#size-cells': false + typec: false + ec-pwm: false + kbd-led-backlight: false + keyboard-controller: false + proximity: false + codecs: false + cbas: false + + patternProperties: + "^i2c-tunnel[0-9]*$": false + "^regulator@[0-9]+$": false + "^extcon[0-9]*$": false + + # Using additionalProperties: false here and + # listing true properties doesn't work + + required: + - reset-gpios + - boot0-gpios + - vdd-supply + else: + properties: + reset-gpios: false + boot0-gpios: false + vdd-supply: false + additionalProperties: false examples: @@ -222,4 +281,22 @@ examples: compatible = "google,cros-ec-rpmsg"; }; }; + + # Example for FPMCU + - | + spi0 { + #address-cells = <0x1>; + #size-cells = <0x0>; + + ec@0 { + compatible = "google,cros-ec-fp", "google,cros-ec-spi"; + reg = <0x0>; + interrupt-parent = <&gpio_controller>; + interrupts = <4 IRQ_TYPE_LEVEL_LOW>; + spi-max-frequency = <3000000>; + reset-gpios = <&gpio_controller 5 GPIO_ACTIVE_LOW>; + boot0-gpios = <&gpio_controller 10 GPIO_ACTIVE_HIGH>; + vdd-supply = <&pp3300_fp_mcu>; + }; + }; ... diff --git a/Documentation/devicetree/bindings/mfd/max77650.yaml b/Documentation/devicetree/bindings/mfd/max77650.yaml index b0a0f0d3d9d4..4181174fcf58 100644 --- a/Documentation/devicetree/bindings/mfd/max77650.yaml +++ b/Documentation/devicetree/bindings/mfd/max77650.yaml @@ -100,14 +100,12 @@ examples: compatible = "maxim,max77650-regulator"; max77650_ldo: regulator-ldo { - regulator-compatible = "ldo"; regulator-name = "max77650-ldo"; regulator-min-microvolt = <1350000>; regulator-max-microvolt = <2937500>; }; max77650_sbb0: regulator-sbb0 { - regulator-compatible = "sbb0"; regulator-name = "max77650-sbb0"; regulator-min-microvolt = <800000>; regulator-max-microvolt = <1587500>; diff --git a/Documentation/devicetree/bindings/mfd/mediatek,mt6360.yaml b/Documentation/devicetree/bindings/mfd/mediatek,mt6360.yaml index 28eee02441ee..fb65abf30d57 100644 --- a/Documentation/devicetree/bindings/mfd/mediatek,mt6360.yaml +++ b/Documentation/devicetree/bindings/mfd/mediatek,mt6360.yaml @@ -83,7 +83,6 @@ examples: richtek,vinovp-microvolt = <14500000>; otg_vbus_regulator: usb-otg-vbus-regulator { - regulator-compatible = "usb-otg-vbus"; regulator-name = "usb-otg-vbus"; regulator-min-microvolt = <4425000>; regulator-max-microvolt = <5825000>; @@ -145,7 +144,6 @@ examples: compatible = "mediatek,mt6360-regulator"; LDO_VIN3-supply = <&BUCK2>; buck1 { - regulator-compatible = "BUCK1"; regulator-name = "mt6360,buck1"; regulator-min-microvolt = <300000>; regulator-max-microvolt = <1300000>; @@ -154,7 +152,6 @@ examples: MT6360_OPMODE_ULP>; }; BUCK2: buck2 { - regulator-compatible = "BUCK2"; regulator-name = "mt6360,buck2"; regulator-min-microvolt = <300000>; regulator-max-microvolt = <1300000>; @@ -163,7 +160,6 @@ examples: MT6360_OPMODE_ULP>; }; ldo6 { - regulator-compatible = "LDO6"; regulator-name = "mt6360,ldo6"; regulator-min-microvolt = <500000>; regulator-max-microvolt = <2100000>; @@ -171,7 +167,6 @@ examples: MT6360_OPMODE_LP>; }; ldo7 { - regulator-compatible = "LDO7"; regulator-name = "mt6360,ldo7"; regulator-min-microvolt = <500000>; regulator-max-microvolt = <2100000>; @@ -179,7 +174,6 @@ examples: MT6360_OPMODE_LP>; }; ldo1 { - regulator-compatible = "LDO1"; regulator-name = "mt6360,ldo1"; regulator-min-microvolt = <1200000>; regulator-max-microvolt = <3600000>; @@ -187,7 +181,6 @@ examples: MT6360_OPMODE_LP>; }; ldo2 { - regulator-compatible = "LDO2"; regulator-name = "mt6360,ldo2"; regulator-min-microvolt = <1200000>; regulator-max-microvolt = <3600000>; @@ -195,7 +188,6 @@ examples: MT6360_OPMODE_LP>; }; ldo3 { - regulator-compatible = "LDO3"; regulator-name = "mt6360,ldo3"; regulator-min-microvolt = <1200000>; regulator-max-microvolt = <3600000>; @@ -203,7 +195,6 @@ examples: MT6360_OPMODE_LP>; }; ldo5 { - regulator-compatible = "LDO5"; regulator-name = "mt6360,ldo5"; regulator-min-microvolt = <2700000>; regulator-max-microvolt = <3600000>; diff --git a/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml b/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml index 6a3e3ede1ede..a5edab6f2e40 100644 --- a/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml +++ b/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml @@ -33,6 +33,7 @@ properties: compatible: items: - enum: + - qcom,pm6125 - qcom,pm6150 - qcom,pm6150l - qcom,pm6350 diff --git a/Documentation/devicetree/bindings/mips/brcm/brcm,bmips.txt b/Documentation/devicetree/bindings/mips/brcm/brcm,bmips.txt deleted file mode 100644 index 8ef71b4085ca..000000000000 --- a/Documentation/devicetree/bindings/mips/brcm/brcm,bmips.txt +++ /dev/null @@ -1,8 +0,0 @@ -* Broadcom MIPS (BMIPS) CPUs - -Required properties: -- compatible: "brcm,bmips3300", "brcm,bmips4350", "brcm,bmips4380", - "brcm,bmips5000" - -- mips-hpt-frequency: This is common to all CPUs in the system so it lives - under the "cpus" node. diff --git a/Documentation/devicetree/bindings/mips/brcm/soc.yaml b/Documentation/devicetree/bindings/mips/brcm/soc.yaml new file mode 100644 index 000000000000..975945ca2888 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/brcm/soc.yaml @@ -0,0 +1,96 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mips/brcm/soc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom cable/DSL/settop platforms + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +description: | + Boards Broadcom cable/DSL/settop SoC shall have the following properties. + The experimental -viper variants are for running Linux on the 3384's + BMIPS4355 cable modem CPU instead of the BMIPS5000 application processor. + +properties: + $nodename: + const: '/' + + compatible: + enum: + - brcm,bcm3368 + - brcm,bcm3384 + - brcm,bcm33843 + - brcm,bcm3384-viper + - brcm,bcm33843-viper + - brcm,bcm6328 + - brcm,bcm6358 + - brcm,bcm6362 + - brcm,bcm6368 + - brcm,bcm63168 + - brcm,bcm63268 + - brcm,bcm7125 + - brcm,bcm7346 + - brcm,bcm7358 + - brcm,bcm7360 + - brcm,bcm7362 + - brcm,bcm7420 + - brcm,bcm7425 + + cpus: + type: object + additionalProperties: false + properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + mips-hpt-frequency: + description: MIPS counter high precision timer frequency. + This is common to all CPUs in the system so it lives + under the "cpus" node. + $ref: /schemas/types.yaml#/definitions/uint32 + + patternProperties: + "^cpu@[0-9]$": + type: object + $ref: /schemas/mips/cpus.yaml# + unevaluatedProperties: false + + required: + - mips-hpt-frequency + +additionalProperties: true + +examples: + - | + / { + compatible = "brcm,bcm3368"; + #address-cells = <1>; + #size-cells = <1>; + model = "Broadcom 3368"; + + cpus { + #address-cells = <1>; + #size-cells = <0>; + + mips-hpt-frequency = <150000000>; + + cpu@0 { + compatible = "brcm,bmips4350"; + device_type = "cpu"; + reg = <0>; + }; + + cpu@1 { + compatible = "brcm,bmips4350"; + device_type = "cpu"; + reg = <1>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/mips/cpus.yaml b/Documentation/devicetree/bindings/mips/cpus.yaml new file mode 100644 index 000000000000..e991f4c6668d --- /dev/null +++ b/Documentation/devicetree/bindings/mips/cpus.yaml @@ -0,0 +1,115 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mips/cpus.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MIPS CPUs bindings + +maintainers: + - Thomas Bogendoerfer <tsbogend@alpha.franken.de> + - 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com> + +description: | + The device tree allows to describe the layout of CPUs in a system through + the "cpus" node, which in turn contains a number of subnodes (ie "cpu") + defining properties for every CPU. + +properties: + compatible: + enum: + - brcm,bmips3300 + - brcm,bmips4350 + - brcm,bmips4380 + - brcm,bmips5000 + - brcm,bmips5200 + - ingenic,xburst-mxu1.0 + - ingenic,xburst-fpu1.0-mxu1.1 + - ingenic,xburst-fpu2.0-mxu2.0 + - ingenic,xburst2-fpu2.1-mxu2.1-smt + - loongson,gs264 + - mips,m14Kc + - mips,mips4Kc + - mips,mips4KEc + - mips,mips24Kc + - mips,mips24KEc + - mips,mips74Kc + - mips,mips1004Kc + - mti,interaptiv + - mti,mips24KEc + - mti,mips14KEc + - mti,mips14Kc + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + device_type: true + +allOf: + - if: + properties: + compatible: + contains: + enum: + - ingenic,xburst-mxu1.0 + - ingenic,xburst-fpu1.0-mxu1.1 + - ingenic,xburst-fpu2.0-mxu2.0 + - ingenic,xburst2-fpu2.1-mxu2.1-smt + then: + required: + - device_type + - clocks + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + cpus { + #size-cells = <0>; + #address-cells = <1>; + + cpu@0 { + compatible = "mips,mips1004Kc"; + device_type = "cpu"; + reg = <0>; + }; + + cpu@1 { + compatible = "mips,mips1004Kc"; + device_type = "cpu"; + reg = <1>; + }; + }; + + - | + // Example 2 (Ingenic CPU) + #include <dt-bindings/clock/ingenic,jz4780-cgu.h> + + cpus { + #address-cells = <1>; + #size-cells = <0>; + + cpu@0 { + compatible = "ingenic,xburst-fpu1.0-mxu1.1"; + device_type = "cpu"; + reg = <0>; + + clocks = <&cgu JZ4780_CLK_CPU>; + }; + + cpu@1 { + compatible = "ingenic,xburst-fpu1.0-mxu1.1"; + device_type = "cpu"; + reg = <1>; + + clocks = <&cgu JZ4780_CLK_CORE1>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/mips/ingenic/ingenic,cpu.yaml b/Documentation/devicetree/bindings/mips/ingenic/ingenic,cpu.yaml deleted file mode 100644 index b7e7fa715437..000000000000 --- a/Documentation/devicetree/bindings/mips/ingenic/ingenic,cpu.yaml +++ /dev/null @@ -1,69 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/mips/ingenic/ingenic,cpu.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Bindings for Ingenic XBurst family CPUs - -maintainers: - - 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com> - -description: - Ingenic XBurst family CPUs shall have the following properties. - -properties: - compatible: - oneOf: - - - description: Ingenic XBurst®1 CPU Cores - enum: - - ingenic,xburst-mxu1.0 - - ingenic,xburst-fpu1.0-mxu1.1 - - ingenic,xburst-fpu2.0-mxu2.0 - - - description: Ingenic XBurst®2 CPU Cores - enum: - - ingenic,xburst2-fpu2.1-mxu2.1-smt - - reg: - maxItems: 1 - - clocks: - maxItems: 1 - - device_type: true - -required: - - device_type - - compatible - - reg - - clocks - -additionalProperties: false - -examples: - - | - #include <dt-bindings/clock/ingenic,jz4780-cgu.h> - - cpus { - #address-cells = <1>; - #size-cells = <0>; - - cpu0: cpu@0 { - device_type = "cpu"; - compatible = "ingenic,xburst-fpu1.0-mxu1.1"; - reg = <0>; - - clocks = <&cgu JZ4780_CLK_CPU>; - }; - - cpu1: cpu@1 { - device_type = "cpu"; - compatible = "ingenic,xburst-fpu1.0-mxu1.1"; - reg = <1>; - - clocks = <&cgu JZ4780_CLK_CORE1>; - }; - }; -... diff --git a/Documentation/devicetree/bindings/misc/idt,89hpesx.yaml b/Documentation/devicetree/bindings/misc/idt,89hpesx.yaml new file mode 100644 index 000000000000..452236e79354 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/idt,89hpesx.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/misc/idt,89hpesx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: EEPROM / CSR SMBus-slave interface of IDT 89HPESx devices + +maintainers: + - Serge Semin <fancer.lancer@gmail.com> + +select: + properties: + compatible: + contains: + pattern: '^idt,89hpes' + required: + - compatible + +properties: + compatible: + oneOf: + - pattern: '^idt,89hpes(8nt2|12nt3|12n3a?|24n3a?|(12|24)t3g2|4t4g2|10t4g2|[56]t5|8t5a?)$' + - pattern: '^idt,89hpes(6t6g2|16t7|(24t6|32t8|48t12|16t4a?)(g2)?)$' + - pattern: '^idt,89hpes(24nt6a|32nt8[ab]|12nt12|16nt16|24nt24|32nt24[ab])g2$' + - pattern: '^idt,89hpes((32h8|48h12a?|22h16|34h16|64h16a?)(g2)?|16h16)$' + + reg: + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + +patternProperties: + '^eeprom@': + $ref: /schemas/eeprom/at24.yaml# + unevaluatedProperties: false + + properties: + compatible: + description: Only a subset of devices are supported + pattern: ',24c(32|64|128|256|512)$' + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + idt@74 { + compatible = "idt,89hpes32nt8ag2"; + reg = <0x74>; + #address-cells = <1>; + #size-cells = <0>; + + eeprom@50 { + compatible = "atmel,24c64"; + reg = <0x50>; + read-only; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/misc/idt_89hpesx.txt b/Documentation/devicetree/bindings/misc/idt_89hpesx.txt deleted file mode 100644 index b9093b79ab7d..000000000000 --- a/Documentation/devicetree/bindings/misc/idt_89hpesx.txt +++ /dev/null @@ -1,44 +0,0 @@ -EEPROM / CSR SMBus-slave interface of IDT 89HPESx devices - -Required properties: - - compatible : should be "<manufacturer>,<type>" - Basically there is only one manufacturer: idt, but some - compatible devices may be produced in future. Following devices - are supported: 89hpes8nt2, 89hpes12nt3, 89hpes24nt6ag2, - 89hpes32nt8ag2, 89hpes32nt8bg2, 89hpes12nt12g2, 89hpes16nt16g2, - 89hpes24nt24g2, 89hpes32nt24ag2, 89hpes32nt24bg2; - 89hpes12n3, 89hpes12n3a, 89hpes24n3, 89hpes24n3a; - 89hpes32h8, 89hpes32h8g2, 89hpes48h12, 89hpes48h12g2, - 89hpes48h12ag2, 89hpes16h16, 89hpes22h16, 89hpes22h16g2, - 89hpes34h16, 89hpes34h16g2, 89hpes64h16, 89hpes64h16g2, - 89hpes64h16ag2; - 89hpes12t3g2, 89hpes24t3g2, 89hpes16t4, 89hpes4t4g2, - 89hpes10t4g2, 89hpes16t4g2, 89hpes16t4ag2, 89hpes5t5, - 89hpes6t5, 89hpes8t5, 89hpes8t5a, 89hpes24t6, 89hpes6t6g2, - 89hpes24t6g2, 89hpes16t7, 89hpes32t8, 89hpes32t8g2, - 89hpes48t12, 89hpes48t12g2. - - reg : I2C address of the IDT 89HPESx device. - -Optionally there can be EEPROM-compatible subnode: - - compatible: There are five EEPROM devices supported: 24c32, 24c64, 24c128, - 24c256 and 24c512 differed by size. - - reg: Custom address of EEPROM device (If not specified IDT 89HPESx - (optional) device will try to communicate with EEPROM sited by default - address - 0x50) - - read-only : Parameterless property disables writes to the EEPROM - (optional) - -Example: - idt@60 { - compatible = "idt,89hpes32nt8ag2"; - reg = <0x74>; - #address-cells = <1>; - #size-cells = <0>; - - eeprom@50 { - compatible = "onsemi,24c64"; - reg = <0x50>; - read-only; - }; - }; - diff --git a/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml b/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml index 1e69a5a42439..1c96da04f0e5 100644 --- a/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml +++ b/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml @@ -95,7 +95,9 @@ properties: PIO (polled I/O) interrupt and occurs when the FIFO needs to be emptied as part of a bulk read from the card. Some variants have these two interrupts wired into the same line (logic OR) and in that case - only one interrupt may be provided. + only one interrupt may be provided. The interrupt-names property is + not used due to inconsistency of existing DTs regarding its content. + deprecated: false minItems: 1 maxItems: 2 diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml index 29339d0196ec..dc6256f04b42 100644 --- a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml +++ b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml @@ -50,11 +50,11 @@ properties: - const: fsl,imx8mm-usdhc - items: - enum: + - fsl,imx8dxl-usdhc - fsl,imx8qm-usdhc - const: fsl,imx8qxp-usdhc - items: - enum: - - fsl,imx8dxl-usdhc - fsl,imx8mm-usdhc - fsl,imx8mn-usdhc - fsl,imx8mp-usdhc @@ -71,10 +71,15 @@ properties: deprecated: true - items: - enum: + - fsl,imx8dxl-usdhc - fsl,imx8qm-usdhc - const: fsl,imx8qxp-usdhc - const: fsl,imx7d-usdhc deprecated: true + - items: + - enum: + - fsl,imxrt1170-usdhc + - const: fsl,imxrt1050-usdhc reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/mmc/fujitsu,sdhci-fujitsu.yaml b/Documentation/devicetree/bindings/mmc/fujitsu,sdhci-fujitsu.yaml new file mode 100644 index 000000000000..73d747e917f3 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/fujitsu,sdhci-fujitsu.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/fujitsu,sdhci-fujitsu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Fujitsu/Socionext SDHCI controller (F_SDH30) + +maintainers: + - Kunihiko Hayashi <hayashi.kunihiko@socionext.com> + +allOf: + - $ref: mmc-controller.yaml# + +properties: + compatible: + enum: + - fujitsu,mb86s70-sdhci-3.0 + - socionext,f-sdh30-e51-mmc + + reg: + maxItems: 1 + + clocks: + maxItems: 2 + + clock-names: + items: + - const: iface + - const: core + + resets: + maxItems: 1 + + fujitsu,cmd-dat-delay-select: + type: boolean + description: | + Indicating that this host requires the CMD_DAT_DELAY control to be enabled + +unevaluatedProperties: false + +required: + - compatible + - reg + - clocks + - clock-names + +examples: + - | + sdhci1: mmc@36600000 { + compatible = "fujitsu,mb86s70-sdhci-3.0"; + reg = <0x36600000 0x1000>; + bus-width = <4>; + vqmmc-supply = <&vccq_sdhci1>; + clocks = <&clock 2 2 0>, <&clock 2 3 0>; + clock-names = "iface", "core"; + }; diff --git a/Documentation/devicetree/bindings/mmc/mmc-controller.yaml b/Documentation/devicetree/bindings/mmc/mmc-controller.yaml index 802e3ca8be4d..e82c00368088 100644 --- a/Documentation/devicetree/bindings/mmc/mmc-controller.yaml +++ b/Documentation/devicetree/bindings/mmc/mmc-controller.yaml @@ -293,7 +293,6 @@ properties: description: SDIO only. Preserves card power during a suspend/resume cycle. - # Deprecated: enable-sdio-wakeup wakeup-source: $ref: /schemas/types.yaml#/definitions/flag description: diff --git a/Documentation/devicetree/bindings/mmc/mtk-sd.yaml b/Documentation/devicetree/bindings/mmc/mtk-sd.yaml index d8e1e2e9adf2..8ed94a12a03b 100644 --- a/Documentation/devicetree/bindings/mmc/mtk-sd.yaml +++ b/Documentation/devicetree/bindings/mmc/mtk-sd.yaml @@ -10,9 +10,6 @@ maintainers: - Chaotian Jing <chaotian.jing@mediatek.com> - Wenbin Mei <wenbin.mei@mediatek.com> -allOf: - - $ref: mmc-controller.yaml# - properties: compatible: oneOf: @@ -23,6 +20,7 @@ properties: - mediatek,mt6795-mmc - mediatek,mt7620-mmc - mediatek,mt7622-mmc + - mediatek,mt7986-mmc - mediatek,mt8135-mmc - mediatek,mt8173-mmc - mediatek,mt8183-mmc @@ -48,27 +46,11 @@ properties: description: Should contain phandle for the clock feeding the MMC controller. minItems: 2 - items: - - description: source clock (required). - - description: HCLK which used for host (required). - - description: independent source clock gate (required for MT2712). - - description: bus clock used for internal register access (required for MT2712 MSDC0/3). - - description: msdc subsys clock gate (required for MT8192). - - description: peripheral bus clock gate (required for MT8192). - - description: AXI bus clock gate (required for MT8192). - - description: AHB bus clock gate (required for MT8192). + maxItems: 7 clock-names: minItems: 2 - items: - - const: source - - const: hclk - - const: source_cg - - const: bus_clk - - const: sys_cg - - const: pclk_cg - - const: axi_cg - - const: ahb_cg + maxItems: 7 interrupts: description: @@ -190,15 +172,144 @@ required: - vmmc-supply - vqmmc-supply -if: - properties: - compatible: - contains: - const: mediatek,mt8183-mmc -then: - properties: - reg: - minItems: 2 +allOf: + - $ref: mmc-controller.yaml# + - if: + properties: + compatible: + enum: + - mediatek,mt2701-mmc + - mediatek,mt6779-mmc + - mediatek,mt6795-mmc + - mediatek,mt7620-mmc + - mediatek,mt7622-mmc + - mediatek,mt7623-mmc + - mediatek,mt8135-mmc + - mediatek,mt8173-mmc + - mediatek,mt8183-mmc + - mediatek,mt8186-mmc + - mediatek,mt8188-mmc + - mediatek,mt8195-mmc + - mediatek,mt8516-mmc + then: + properties: + clocks: + minItems: 2 + items: + - description: source clock + - description: HCLK which used for host + - description: independent source clock gate + clock-names: + minItems: 2 + items: + - const: source + - const: hclk + - const: source_cg + + - if: + properties: + compatible: + contains: + const: mediatek,mt2712-mmc + then: + properties: + clocks: + minItems: 3 + items: + - description: source clock + - description: HCLK which used for host + - description: independent source clock gate + - description: bus clock used for internal register access (required for MSDC0/3). + clock-names: + minItems: 3 + items: + - const: source + - const: hclk + - const: source_cg + - const: bus_clk + + - if: + properties: + compatible: + contains: + const: mediatek,mt8183-mmc + then: + properties: + reg: + minItems: 2 + + - if: + properties: + compatible: + contains: + enum: + - mediatek,mt7986-mmc + then: + properties: + clocks: + minItems: 3 + items: + - description: source clock + - description: HCLK which used for host + - description: independent source clock gate + - description: bus clock used for internal register access (required for MSDC0/3). + - description: msdc subsys clock gate + clock-names: + minItems: 3 + items: + - const: source + - const: hclk + - const: source_cg + - const: bus_clk + - const: sys_cg + + - if: + properties: + compatible: + enum: + - mediatek,mt8186-mmc + - mediatek,mt8188-mmc + - mediatek,mt8195-mmc + then: + properties: + clocks: + items: + - description: source clock + - description: HCLK which used for host + - description: independent source clock gate + - description: crypto clock used for data encrypt/decrypt (optional) + clock-names: + items: + - const: source + - const: hclk + - const: source_cg + - const: crypto + + - if: + properties: + compatible: + contains: + const: mediatek,mt8192-mmc + then: + properties: + clocks: + items: + - description: source clock + - description: HCLK which used for host + - description: independent source clock gate + - description: msdc subsys clock gate + - description: peripheral bus clock gate + - description: AXI bus clock gate + - description: AHB bus clock gate + clock-names: + items: + - const: source + - const: hclk + - const: source_cg + - const: sys_cg + - const: pclk_cg + - const: axi_cg + - const: ahb_cg unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml index 0424b06cb655..7bfb10c62566 100644 --- a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml +++ b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml @@ -64,6 +64,7 @@ properties: - enum: - renesas,sdhi-r8a779a0 # R-Car V3U - renesas,sdhi-r8a779f0 # R-Car S4-8 + - renesas,sdhi-r8a779g0 # R-Car V4H - const: renesas,rcar-gen4-sdhi # R-Car Gen4 reg: diff --git a/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.yaml b/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.yaml index 95f59a5e3576..c7e14b7dba9e 100644 --- a/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.yaml +++ b/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.yaml @@ -71,6 +71,9 @@ properties: to control the clock phases, "ciu-sample" is required for tuning high speed modes. + power-domains: + maxItems: 1 + rockchip,default-sample-phase: $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 diff --git a/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml b/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml index ea9121fb188d..676a74695389 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml +++ b/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml @@ -2,8 +2,8 @@ # Copyright (C) 2020 Texas Instruments Incorporated - http://www.ti.com/ %YAML 1.2 --- -$id: "http://devicetree.org/schemas/mmc/sdhci-am654.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/mmc/sdhci-am654.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: TI AM654 MMC Controller @@ -11,17 +11,18 @@ maintainers: - Ulf Hansson <ulf.hansson@linaro.org> allOf: - - $ref: mmc-controller.yaml# + - $ref: sdhci-common.yaml# properties: compatible: oneOf: - - const: ti,am654-sdhci-5.1 - - const: ti,j721e-sdhci-8bit - - const: ti,j721e-sdhci-4bit - - const: ti,am64-sdhci-8bit - - const: ti,am64-sdhci-4bit - - const: ti,am62-sdhci + - enum: + - ti,am62-sdhci + - ti,am64-sdhci-4bit + - ti,am64-sdhci-8bit + - ti,am654-sdhci-5.1 + - ti,j721e-sdhci-4bit + - ti,j721e-sdhci-8bit - items: - const: ti,j7200-sdhci-8bit - const: ti,j721e-sdhci-8bit @@ -49,8 +50,6 @@ properties: - const: clk_ahb - const: clk_xin - sdhci-caps-mask: true - dma-coherent: type: boolean @@ -61,67 +60,67 @@ properties: ti,otap-del-sel-legacy: description: Output tap delay for SD/MMC legacy timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0xf ti,otap-del-sel-mmc-hs: description: Output tap delay for MMC high speed timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0xf ti,otap-del-sel-sd-hs: description: Output tap delay for SD high speed timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0xf ti,otap-del-sel-sdr12: description: Output tap delay for SD UHS SDR12 timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0xf ti,otap-del-sel-sdr25: description: Output tap delay for SD UHS SDR25 timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0xf ti,otap-del-sel-sdr50: description: Output tap delay for SD UHS SDR50 timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0xf ti,otap-del-sel-sdr104: description: Output tap delay for SD UHS SDR104 timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0xf ti,otap-del-sel-ddr50: description: Output tap delay for SD UHS DDR50 timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0xf ti,otap-del-sel-ddr52: description: Output tap delay for eMMC DDR52 timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0xf ti,otap-del-sel-hs200: description: Output tap delay for eMMC HS200 timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0xf ti,otap-del-sel-hs400: description: Output tap delay for eMMC HS400 timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0xf @@ -131,49 +130,55 @@ properties: ti,itap-del-sel-legacy: description: Input tap delay for SD/MMC legacy timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0x1f ti,itap-del-sel-mmc-hs: description: Input tap delay for MMC high speed timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0x1f ti,itap-del-sel-sd-hs: description: Input tap delay for SD high speed timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0x1f ti,itap-del-sel-sdr12: description: Input tap delay for SD UHS SDR12 timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0x1f ti,itap-del-sel-sdr25: description: Input tap delay for SD UHS SDR25 timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 0x1f + + ti,itap-del-sel-ddr50: + description: Input tap delay for MMC DDR50 timing + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0x1f ti,itap-del-sel-ddr52: description: Input tap delay for MMC DDR52 timing - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0x1f ti,trm-icp: description: DLL trim select - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 0xf ti,driver-strength-ohm: description: DLL drive strength in ohms - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 enum: - 33 - 40 @@ -183,11 +188,11 @@ properties: ti,strobe-sel: description: strobe select delay for HS400 speed mode. - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 ti,clkbuf-sel: description: Clock Delay Buffer Select - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: /schemas/types.yaml#/definitions/uint32 ti,fails-without-test-cd: $ref: /schemas/types.yaml#/definitions/flag diff --git a/Documentation/devicetree/bindings/mmc/sdhci-common.yaml b/Documentation/devicetree/bindings/mmc/sdhci-common.yaml new file mode 100644 index 000000000000..1664615187c8 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/sdhci-common.yaml @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/sdhci-common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: SDHCI Controller Common Properties + +maintainers: + - Adrian Hunter <adrian.hunter@intel.com> + +description: + Common properties present on Secure Digital Host Controller Interface (SDHCI) + devices. + +properties: + sdhci-caps: + $ref: /schemas/types.yaml#/definitions/uint64 + description: + Additionally present SDHCI capabilities - values for SDHCI_CAPABILITIES + and SDHCI_CAPABILITIES_1 registers. + + sdhci-caps-mask: + $ref: /schemas/types.yaml#/definitions/uint64 + description: + Masked SDHCI capabilities to remove from SDHCI_CAPABILITIES and + SDHCI_CAPABILITIES_1 registers. + +allOf: + - $ref: mmc-controller.yaml# + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/mmc/sdhci-fujitsu.txt b/Documentation/devicetree/bindings/mmc/sdhci-fujitsu.txt deleted file mode 100644 index 3ee9263adf73..000000000000 --- a/Documentation/devicetree/bindings/mmc/sdhci-fujitsu.txt +++ /dev/null @@ -1,32 +0,0 @@ -* Fujitsu SDHCI controller - -This file documents differences between the core properties in mmc.txt -and the properties used by the sdhci_f_sdh30 driver. - -Required properties: -- compatible: "fujitsu,mb86s70-sdhci-3.0" -- clocks: Must contain an entry for each entry in clock-names. It is a - list of phandles and clock-specifier pairs. - See ../clocks/clock-bindings.txt for details. -- clock-names: Should contain the following two entries: - "iface" - clock used for sdhci interface - "core" - core clock for sdhci controller - -Optional properties: -- vqmmc-supply: phandle to the regulator device tree node, mentioned - as the VCCQ/VDD_IO supply in the eMMC/SD specs. -- fujitsu,cmd-dat-delay-select: boolean property indicating that this host - requires the CMD_DAT_DELAY control to be enabled. - -Example: - - sdhci1: mmc@36600000 { - compatible = "fujitsu,mb86s70-sdhci-3.0"; - reg = <0 0x36600000 0x1000>; - interrupts = <0 172 0x4>, - <0 173 0x4>; - bus-width = <4>; - vqmmc-supply = <&vccq_sdhci1>; - clocks = <&clock 2 2 0>, <&clock 2 3 0>; - clock-names = "iface", "core"; - }; diff --git a/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml b/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml index a96f143479c7..6b89238f0565 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml +++ b/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml @@ -1,9 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) - %YAML 1.2 --- -$id: "http://devicetree.org/schemas/mmc/sdhci-msm.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/mmc/sdhci-msm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm SDHCI controller (sdhci-msm) @@ -26,6 +25,7 @@ properties: - qcom,msm8226-sdhci - qcom,msm8953-sdhci - qcom,msm8974-sdhci + - qcom,msm8976-sdhci - qcom,msm8916-sdhci - qcom,msm8992-sdhci - qcom,msm8994-sdhci @@ -45,9 +45,12 @@ properties: - qcom,sm6115-sdhci - qcom,sm6125-sdhci - qcom,sm6350-sdhci + - qcom,sm6375-sdhci - qcom,sm8150-sdhci - qcom,sm8250-sdhci + - qcom,sm8350-sdhci - qcom,sm8450-sdhci + - qcom,sm8550-sdhci - const: qcom,sdhci-msm-v5 # for sdcc version 5.0 reg: @@ -80,6 +83,8 @@ properties: - const: cal - const: sleep + dma-coherent: true + interrupts: maxItems: 2 @@ -133,16 +138,6 @@ properties: description: A phandle to sdhci power domain node maxItems: 1 - mmc-ddr-1_8v: true - - mmc-hs200-1_8v: true - - mmc-hs400-1_8v: true - - bus-width: true - - max-frequency: true - operating-points-v2: true patternProperties: @@ -165,7 +160,7 @@ required: - interrupts allOf: - - $ref: mmc-controller.yaml# + - $ref: sdhci-common.yaml# - if: properties: diff --git a/Documentation/devicetree/bindings/mmc/snps,dwcmshc-sdhci.yaml b/Documentation/devicetree/bindings/mmc/snps,dwcmshc-sdhci.yaml index 71f8e726d641..51ba44cad842 100644 --- a/Documentation/devicetree/bindings/mmc/snps,dwcmshc-sdhci.yaml +++ b/Documentation/devicetree/bindings/mmc/snps,dwcmshc-sdhci.yaml @@ -45,6 +45,17 @@ properties: - const: block - const: timer + resets: + maxItems: 5 + + reset-names: + items: + - const: core + - const: bus + - const: axi + - const: block + - const: timer + rockchip,txclk-tapnum: description: Specify the number of delay for tx sampling. $ref: /schemas/types.yaml#/definitions/uint8 diff --git a/Documentation/devicetree/bindings/mmc/sunplus,mmc.yaml b/Documentation/devicetree/bindings/mmc/sunplus,mmc.yaml new file mode 100644 index 000000000000..23aa8e6b2d70 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/sunplus,mmc.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) Sunplus Ltd. Co. 2021 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/sunplus,mmc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sunplus MMC Controller + +maintainers: + - Tony Huang <tonyhuang.sunplus@gmail.com> + - Li-hao Kuo <lhjeff911@gmail.com> + +allOf: + - $ref: "mmc-controller.yaml" + +properties: + compatible: + enum: + - sunplus,sp7021-mmc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - resets + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + mmc0: mmc@9c003b00 { + compatible = "sunplus,sp7021-mmc"; + reg = <0x9c003b00 0x180>; + interrupts = <20 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clkc 0x4e>; + resets = <&rstc 0x3e>; + bus-width = <8>; + max-frequency = <52000000>; + non-removable; + disable-wp; + cap-mmc-highspeed; + mmc-ddr-3_3v; + no-sdio; + no-sd; + }; diff --git a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml index ae6d6fca79e2..e1f5f26f3f1c 100644 --- a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml +++ b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml @@ -6,9 +6,6 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Synopsys Designware Mobile Storage Host Controller Binding -allOf: - - $ref: "synopsys-dw-mshc-common.yaml#" - maintainers: - Ulf Hansson <ulf.hansson@linaro.org> @@ -38,6 +35,35 @@ properties: - const: biu - const: ciu + altr,sysmgr-syscon: + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + - items: + - description: phandle to the sysmgr node + - description: register offset that controls the SDMMC clock phase + - description: register shift for the smplsel(drive in) setting + description: + This property is optional. Contains the phandle to System Manager block + that contains the SDMMC clock-phase control register. The first value is + the pointer to the sysmgr, the 2nd value is the register offset for the + SDMMC clock phase register, and the 3rd value is the bit shift for the + smplsel(drive in) setting. + +allOf: + - $ref: synopsys-dw-mshc-common.yaml# + + - if: + properties: + compatible: + contains: + const: altr,socfpga-dw-mshc + then: + properties: + altr,sysmgr-syscon: true + else: + properties: + altr,sysmgr-syscon: false + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml b/Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml index 4741864da48e..e7ec0c59bca6 100644 --- a/Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml +++ b/Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml @@ -14,9 +14,6 @@ maintainers: - Maxime Ripard <mripard@kernel.org> properties: - "#address-cells": true - "#size-cells": true - compatible: enum: - allwinner,sun4i-a10-nand @@ -49,12 +46,8 @@ properties: dma-names: const: rxtx - pinctrl-names: true - patternProperties: - "^pinctrl-[0-9]+$": true - - "^nand@[a-f0-9]+$": + "^nand@[a-f0-9]$": type: object properties: reg: @@ -91,6 +84,29 @@ required: - clocks - clock-names -additionalProperties: false +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/sun6i-rtc.h> + #include <dt-bindings/clock/sun8i-a23-a33-ccu.h> + #include <dt-bindings/reset/sun8i-a23-a33-ccu.h> + + nand-controller@1c03000 { + compatible = "allwinner,sun8i-a23-nand-controller"; + reg = <0x01c03000 0x1000>; + interrupts = <GIC_SPI 70 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_NAND>, <&ccu CLK_NAND>; + clock-names = "ahb", "mod"; + resets = <&ccu RST_BUS_NAND>; + reset-names = "ahb"; + dmas = <&dma 5>; + dma-names = "rxtx"; + pinctrl-names = "default"; + pinctrl-0 = <&nand_pins &nand_cs0_pin &nand_rb0_pin>; + #address-cells = <1>; + #size-cells = <0>; + }; ... diff --git a/Documentation/devicetree/bindings/mtd/arasan,nand-controller.yaml b/Documentation/devicetree/bindings/mtd/arasan,nand-controller.yaml index f013fb976d95..d028269cdbaa 100644 --- a/Documentation/devicetree/bindings/mtd/arasan,nand-controller.yaml +++ b/Documentation/devicetree/bindings/mtd/arasan,nand-controller.yaml @@ -35,9 +35,6 @@ properties: interrupts: maxItems: 1 - "#address-cells": true - "#size-cells": true - required: - compatible - reg @@ -45,7 +42,7 @@ required: - clock-names - interrupts -additionalProperties: true +unevaluatedProperties: true examples: - | diff --git a/Documentation/devicetree/bindings/mtd/arm,pl353-nand-r2p1.yaml b/Documentation/devicetree/bindings/mtd/arm,pl353-nand-r2p1.yaml index 023f3ef0fa13..e552875040e2 100644 --- a/Documentation/devicetree/bindings/mtd/arm,pl353-nand-r2p1.yaml +++ b/Documentation/devicetree/bindings/mtd/arm,pl353-nand-r2p1.yaml @@ -34,20 +34,20 @@ unevaluatedProperties: false examples: - | smcc: memory-controller@e000e000 { - compatible = "arm,pl353-smc-r2p1", "arm,primecell"; - reg = <0xe000e000 0x0001000>; - clock-names = "memclk", "apb_pclk"; - clocks = <&clkc 11>, <&clkc 44>; - ranges = <0x0 0x0 0xe1000000 0x1000000 /* Nand CS region */ - 0x1 0x0 0xe2000000 0x2000000 /* SRAM/NOR CS0 region */ - 0x2 0x0 0xe4000000 0x2000000>; /* SRAM/NOR CS1 region */ - #address-cells = <2>; - #size-cells = <1>; - - nfc0: nand-controller@0,0 { - compatible = "arm,pl353-nand-r2p1"; - reg = <0 0 0x1000000>; - #address-cells = <1>; - #size-cells = <0>; - }; + compatible = "arm,pl353-smc-r2p1", "arm,primecell"; + reg = <0xe000e000 0x0001000>; + clock-names = "memclk", "apb_pclk"; + clocks = <&clkc 11>, <&clkc 44>; + ranges = <0x0 0x0 0xe1000000 0x1000000 /* Nand CS region */ + 0x1 0x0 0xe2000000 0x2000000 /* SRAM/NOR CS0 region */ + 0x2 0x0 0xe4000000 0x2000000>; /* SRAM/NOR CS1 region */ + #address-cells = <2>; + #size-cells = <1>; + + nfc0: nand-controller@0,0 { + compatible = "arm,pl353-nand-r2p1"; + reg = <0 0 0x1000000>; + #address-cells = <1>; + #size-cells = <0>; + }; }; diff --git a/Documentation/devicetree/bindings/mtd/atmel-nand.txt b/Documentation/devicetree/bindings/mtd/atmel-nand.txt index 3aa297c97ab6..50645828ac20 100644 --- a/Documentation/devicetree/bindings/mtd/atmel-nand.txt +++ b/Documentation/devicetree/bindings/mtd/atmel-nand.txt @@ -45,10 +45,8 @@ Optional properties: - atmel,rb: an integer identifying the native Ready/Busy pin. Only meaningful on sama5 SoCs. -All generic properties described in -Documentation/devicetree/bindings/mtd/{common,nand}.txt also apply to the NAND -device node, and NAND partitions should be defined under the NAND node as -described in Documentation/devicetree/bindings/mtd/partition.txt. +All generic properties are described in the generic yaml files under +Documentation/devicetree/bindings/mtd/. * ECC engine (PMECC) bindings: diff --git a/Documentation/devicetree/bindings/mtd/brcm,brcmnand.yaml b/Documentation/devicetree/bindings/mtd/brcm,brcmnand.yaml index dd5a64969e37..1571024aa119 100644 --- a/Documentation/devicetree/bindings/mtd/brcm,brcmnand.yaml +++ b/Documentation/devicetree/bindings/mtd/brcm,brcmnand.yaml @@ -86,15 +86,15 @@ properties: minItems: 1 items: - description: NAND CTLRDY interrupt - - description: FLASH_DMA_DONE if flash DMA is available - - description: FLASH_EDU_DONE if EDU is available + - description: FLASH_DMA_DONE (if flash DMA is available) or FLASH_EDU_DONE (if EDU is available) interrupt-names: minItems: 1 items: - const: nand_ctlrdy - - const: flash_dma_done - - const: flash_edu_done + - enum: + - flash_dma_done + - flash_edu_done clocks: maxItems: 1 @@ -173,6 +173,13 @@ allOf: - const: nand - const: iproc-idm - const: iproc-ext + - if: + properties: + interrupts: + minItems: 2 + then: + required: + - interrupt-names unevaluatedProperties: false @@ -184,51 +191,52 @@ required: examples: - | nand-controller@f0442800 { - compatible = "brcm,brcmnand-v7.0", "brcm,brcmnand"; - reg = <0xf0442800 0x600>, - <0xf0443000 0x100>; - reg-names = "nand", "flash-dma"; - interrupt-parent = <&hif_intr2_intc>; - interrupts = <24>, <4>; + compatible = "brcm,brcmnand-v7.0", "brcm,brcmnand"; + reg = <0xf0442800 0x600>, + <0xf0443000 0x100>; + reg-names = "nand", "flash-dma"; + interrupt-parent = <&hif_intr2_intc>; + interrupts = <24>, <4>; + interrupt-names = "nand_ctlrdy", "flash_dma_done"; + + #address-cells = <1>; + #size-cells = <0>; + + nand@1 { + compatible = "brcm,nandcs"; + reg = <1>; // Chip select 1 + nand-on-flash-bbt; + nand-ecc-strength = <12>; + nand-ecc-step-size = <512>; #address-cells = <1>; - #size-cells = <0>; - - nand@1 { - compatible = "brcm,nandcs"; - reg = <1>; // Chip select 1 - nand-on-flash-bbt; - nand-ecc-strength = <12>; - nand-ecc-step-size = <512>; - - #address-cells = <1>; - #size-cells = <1>; - }; + #size-cells = <1>; + }; }; - | nand-controller@10000200 { - compatible = "brcm,nand-bcm63168", "brcm,nand-bcm6368", - "brcm,brcmnand-v4.0", "brcm,brcmnand"; - reg = <0x10000200 0x180>, - <0x100000b0 0x10>, - <0x10000600 0x200>; - reg-names = "nand", "nand-int-base", "nand-cache"; - interrupt-parent = <&periph_intc>; - interrupts = <50>; - clocks = <&periph_clk 20>; - clock-names = "nand"; + compatible = "brcm,nand-bcm63168", "brcm,nand-bcm6368", + "brcm,brcmnand-v4.0", "brcm,brcmnand"; + reg = <0x10000200 0x180>, + <0x100000b0 0x10>, + <0x10000600 0x200>; + reg-names = "nand", "nand-int-base", "nand-cache"; + interrupt-parent = <&periph_intc>; + interrupts = <50>; + clocks = <&periph_clk 20>; + clock-names = "nand"; + + #address-cells = <1>; + #size-cells = <0>; + + nand@0 { + compatible = "brcm,nandcs"; + reg = <0>; + nand-on-flash-bbt; + nand-ecc-strength = <1>; + nand-ecc-step-size = <512>; #address-cells = <1>; - #size-cells = <0>; - - nand@0 { - compatible = "brcm,nandcs"; - reg = <0>; - nand-on-flash-bbt; - nand-ecc-strength = <1>; - nand-ecc-step-size = <512>; - - #address-cells = <1>; - #size-cells = <1>; - }; + #size-cells = <1>; + }; }; diff --git a/Documentation/devicetree/bindings/mtd/denali,nand.yaml b/Documentation/devicetree/bindings/mtd/denali,nand.yaml index 1307ed7e7fc6..0be83ad42970 100644 --- a/Documentation/devicetree/bindings/mtd/denali,nand.yaml +++ b/Documentation/devicetree/bindings/mtd/denali,nand.yaml @@ -145,6 +145,6 @@ examples: #size-cells = <0>; nand@0 { - reg = <0>; + reg = <0>; }; }; diff --git a/Documentation/devicetree/bindings/mtd/ingenic,nand.yaml b/Documentation/devicetree/bindings/mtd/ingenic,nand.yaml index 8c272c842bfd..a811a512ecc5 100644 --- a/Documentation/devicetree/bindings/mtd/ingenic,nand.yaml +++ b/Documentation/devicetree/bindings/mtd/ingenic,nand.yaml @@ -32,9 +32,9 @@ properties: partitions: type: object + deprecated: true description: Node containing description of fixed partitions. - See Documentation/devicetree/bindings/mtd/partition.txt patternProperties: "^nand@[a-f0-9]$": @@ -58,78 +58,78 @@ examples: - | #include <dt-bindings/clock/ingenic,jz4780-cgu.h> memory-controller@13410000 { - compatible = "ingenic,jz4780-nemc"; - reg = <0x13410000 0x10000>; - #address-cells = <2>; - #size-cells = <1>; - ranges = <1 0 0x1b000000 0x1000000>, - <2 0 0x1a000000 0x1000000>, - <3 0 0x19000000 0x1000000>, - <4 0 0x18000000 0x1000000>, - <5 0 0x17000000 0x1000000>, - <6 0 0x16000000 0x1000000>; - - clocks = <&cgu JZ4780_CLK_NEMC>; - - nand-controller@1 { - compatible = "ingenic,jz4780-nand"; - reg = <1 0 0x1000000>; - - #address-cells = <1>; - #size-cells = <0>; - - ecc-engine = <&bch>; - - ingenic,nemc-tAS = <10>; - ingenic,nemc-tAH = <5>; - ingenic,nemc-tBP = <10>; - ingenic,nemc-tAW = <15>; - ingenic,nemc-tSTRV = <100>; - - pinctrl-names = "default"; - pinctrl-0 = <&pins_nemc>; - - nand@1 { - reg = <1>; - - nand-ecc-step-size = <1024>; - nand-ecc-strength = <24>; - nand-ecc-mode = "hw"; - nand-on-flash-bbt; - - pinctrl-names = "default"; - pinctrl-0 = <&pins_nemc_cs1>; - - partitions { - compatible = "fixed-partitions"; - #address-cells = <2>; - #size-cells = <2>; - - partition@0 { - label = "u-boot-spl"; - reg = <0x0 0x0 0x0 0x800000>; + compatible = "ingenic,jz4780-nemc"; + reg = <0x13410000 0x10000>; + #address-cells = <2>; + #size-cells = <1>; + ranges = <1 0 0x1b000000 0x1000000>, + <2 0 0x1a000000 0x1000000>, + <3 0 0x19000000 0x1000000>, + <4 0 0x18000000 0x1000000>, + <5 0 0x17000000 0x1000000>, + <6 0 0x16000000 0x1000000>; + + clocks = <&cgu JZ4780_CLK_NEMC>; + + nand-controller@1 { + compatible = "ingenic,jz4780-nand"; + reg = <1 0 0x1000000>; + + #address-cells = <1>; + #size-cells = <0>; + + ecc-engine = <&bch>; + + ingenic,nemc-tAS = <10>; + ingenic,nemc-tAH = <5>; + ingenic,nemc-tBP = <10>; + ingenic,nemc-tAW = <15>; + ingenic,nemc-tSTRV = <100>; + + pinctrl-names = "default"; + pinctrl-0 = <&pins_nemc>; + + nand@1 { + reg = <1>; + + nand-ecc-step-size = <1024>; + nand-ecc-strength = <24>; + nand-ecc-mode = "hw"; + nand-on-flash-bbt; + + pinctrl-names = "default"; + pinctrl-0 = <&pins_nemc_cs1>; + + partitions { + compatible = "fixed-partitions"; + #address-cells = <2>; + #size-cells = <2>; + + partition@0 { + label = "u-boot-spl"; + reg = <0x0 0x0 0x0 0x800000>; + }; + + partition@800000 { + label = "u-boot"; + reg = <0x0 0x800000 0x0 0x200000>; + }; + + partition@a00000 { + label = "u-boot-env"; + reg = <0x0 0xa00000 0x0 0x200000>; + }; + + partition@c00000 { + label = "boot"; + reg = <0x0 0xc00000 0x0 0x4000000>; + }; + + partition@4c00000 { + label = "system"; + reg = <0x0 0x4c00000 0x1 0xfb400000>; + }; + }; }; - - partition@800000 { - label = "u-boot"; - reg = <0x0 0x800000 0x0 0x200000>; - }; - - partition@a00000 { - label = "u-boot-env"; - reg = <0x0 0xa00000 0x0 0x200000>; - }; - - partition@c00000 { - label = "boot"; - reg = <0x0 0xc00000 0x0 0x4000000>; - }; - - partition@4c00000 { - label = "system"; - reg = <0x0 0x4c00000 0x1 0xfb400000>; - }; - }; }; - }; }; diff --git a/Documentation/devicetree/bindings/mtd/intel,lgm-ebunand.yaml b/Documentation/devicetree/bindings/mtd/intel,lgm-ebunand.yaml index 741c66ee06c3..8c62c7d3d0cd 100644 --- a/Documentation/devicetree/bindings/mtd/intel,lgm-ebunand.yaml +++ b/Documentation/devicetree/bindings/mtd/intel,lgm-ebunand.yaml @@ -39,14 +39,8 @@ properties: - const: tx - const: rx - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - patternProperties: - "^nand@[a-f0-9]+$": + "^nand@[a-f0-9]$": type: object properties: reg: @@ -67,33 +61,31 @@ required: - clocks - dmas - dma-names - - "#address-cells" - - "#size-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | nand-controller@e0f00000 { - compatible = "intel,lgm-ebunand"; - reg = <0xe0f00000 0x100>, - <0xe1000000 0x300>, - <0xe1400000 0x8000>, - <0xe1c00000 0x1000>, - <0x17400000 0x4>, - <0x17c00000 0x4>; - reg-names = "ebunand", "hsnand", "nand_cs0", "nand_cs1", - "addr_sel0", "addr_sel1"; - clocks = <&cgu0 125>; - dmas = <&dma0 8>, <&dma0 9>; - dma-names = "tx", "rx"; - #address-cells = <1>; - #size-cells = <0>; - - nand@0 { - reg = <0>; - nand-ecc-mode = "hw"; - }; + compatible = "intel,lgm-ebunand"; + reg = <0xe0f00000 0x100>, + <0xe1000000 0x300>, + <0xe1400000 0x8000>, + <0xe1c00000 0x1000>, + <0x17400000 0x4>, + <0x17c00000 0x4>; + reg-names = "ebunand", "hsnand", "nand_cs0", "nand_cs1", + "addr_sel0", "addr_sel1"; + clocks = <&cgu0 125>; + dmas = <&dma0 8>, <&dma0 9>; + dma-names = "tx", "rx"; + #address-cells = <1>; + #size-cells = <0>; + + nand@0 { + reg = <0>; + nand-ecc-mode = "hw"; + }; }; ... diff --git a/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml b/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml index 7149784a36ac..3fe981b14e2c 100644 --- a/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml +++ b/Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml @@ -70,24 +70,17 @@ properties: be used on such systems, to denote the absence of a reliable reset mechanism. - partitions: - type: object - - '#address-cells': true - '#size-cells': true - -patternProperties: - # Note: use 'partitions' node for new users - '^partition@': - type: object - - "^otp(-[0-9]+)?$": - type: object + reset-gpios: + description: + A GPIO line connected to the RESET (active low) signal of the device. + If "broken-flash-reset" is present then having this property does not + make any difference. unevaluatedProperties: false examples: - | + #include <dt-bindings/gpio/gpio.h> spi { #address-cells = <1>; #size-cells = <0>; @@ -97,6 +90,7 @@ examples: reg = <0>; spi-max-frequency = <40000000>; m25p,fast-read; + reset-gpios = <&gpio 12 GPIO_ACTIVE_LOW>; }; }; ... diff --git a/Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt b/Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt index 6d60bc3063f5..64c06aa05ac7 100644 --- a/Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt +++ b/Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt @@ -19,7 +19,7 @@ accuracy:) - nxp,wr_low: WR_LOW Optional subnodes: -- Partitions, see Documentation/devicetree/bindings/mtd/partition.txt +- Partitions, see Documentation/devicetree/bindings/mtd/mtd.yaml Example: diff --git a/Documentation/devicetree/bindings/mtd/lpc32xx-slc.txt b/Documentation/devicetree/bindings/mtd/lpc32xx-slc.txt index d94edc0fc554..39f17630a301 100644 --- a/Documentation/devicetree/bindings/mtd/lpc32xx-slc.txt +++ b/Documentation/devicetree/bindings/mtd/lpc32xx-slc.txt @@ -20,7 +20,7 @@ clock speed:) - nxp,rsetup: Read setup time (R_SETUP) Optional subnodes: -- Partitions, see Documentation/devicetree/bindings/mtd/partition.txt +- Partitions, see Documentation/devicetree/bindings/mtd/mtd.yaml Example: diff --git a/Documentation/devicetree/bindings/mtd/microchip,mchp48l640.yaml b/Documentation/devicetree/bindings/mtd/microchip,mchp48l640.yaml index 8cc2a7ceb5fb..ea9450fe7c9f 100644 --- a/Documentation/devicetree/bindings/mtd/microchip,mchp48l640.yaml +++ b/Documentation/devicetree/bindings/mtd/microchip,mchp48l640.yaml @@ -34,13 +34,13 @@ unevaluatedProperties: false examples: - | spi { - #address-cells = <1>; - #size-cells = <0>; - - eeram@0 { - compatible = "microchip,48l640"; - reg = <0>; - spi-max-frequency = <20000000>; - }; + #address-cells = <1>; + #size-cells = <0>; + + eeram@0 { + compatible = "microchip,48l640"; + reg = <0>; + spi-max-frequency = <20000000>; + }; }; ... diff --git a/Documentation/devicetree/bindings/mtd/mtd-physmap.yaml b/Documentation/devicetree/bindings/mtd/mtd-physmap.yaml index 82eb4e0f453b..5df94953c34e 100644 --- a/Documentation/devicetree/bindings/mtd/mtd-physmap.yaml +++ b/Documentation/devicetree/bindings/mtd/mtd-physmap.yaml @@ -13,6 +13,9 @@ description: | Flash chips (Memory Technology Devices) are often used for solid state file systems on embedded devices. +allOf: + - $ref: "mtd.yaml#" + properties: compatible: oneOf: @@ -121,10 +124,6 @@ properties: big-endian: true little-endian: true -patternProperties: - '@[0-9a-f]+$': - $ref: partitions/partition.yaml - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/mtd/mtd.yaml b/Documentation/devicetree/bindings/mtd/mtd.yaml index 3498e485679b..78da129e9985 100644 --- a/Documentation/devicetree/bindings/mtd/mtd.yaml +++ b/Documentation/devicetree/bindings/mtd/mtd.yaml @@ -12,7 +12,7 @@ maintainers: properties: $nodename: - pattern: "^flash(@.*)?$" + pattern: "^(flash|.*sram)(@.*)?$" label: description: @@ -21,9 +21,28 @@ properties: based name) in order to ease flash device identification and/or describe what they are used for. + '#address-cells': + deprecated: true + + '#size-cells': + deprecated: true + + partitions: + $ref: /schemas/mtd/partitions/partitions.yaml + + required: + - compatible + patternProperties: + "@[0-9a-f]+$": + $ref: partitions/partition.yaml + deprecated: true + + "^partition@[0-9a-f]+": + $ref: partitions/partition.yaml + deprecated: true + "^otp(-[0-9]+)?$": - type: object $ref: ../nvmem/nvmem.yaml# description: | @@ -40,6 +59,7 @@ patternProperties: required: - compatible +# This is a generic file other binding inherit from additionalProperties: true examples: diff --git a/Documentation/devicetree/bindings/mtd/mtk-nand.txt b/Documentation/devicetree/bindings/mtd/mtk-nand.txt index 4d3ec5e4ff8a..839ea2f93d04 100644 --- a/Documentation/devicetree/bindings/mtd/mtk-nand.txt +++ b/Documentation/devicetree/bindings/mtd/mtk-nand.txt @@ -131,7 +131,7 @@ Example: }; NAND chip optional subnodes: -- Partitions, see Documentation/devicetree/bindings/mtd/partition.txt +- Partitions, see Documentation/devicetree/bindings/mtd/mtd.yaml Example: nand@0 { diff --git a/Documentation/devicetree/bindings/mtd/nand-chip.yaml b/Documentation/devicetree/bindings/mtd/nand-chip.yaml index 97ac3a3fbb52..6e2dc025d694 100644 --- a/Documentation/devicetree/bindings/mtd/nand-chip.yaml +++ b/Documentation/devicetree/bindings/mtd/nand-chip.yaml @@ -9,6 +9,9 @@ title: NAND Chip and NAND Controller Generic Binding maintainers: - Miquel Raynal <miquel.raynal@bootlin.com> +allOf: + - $ref: "mtd.yaml#" + description: | This file covers the generic description of a NAND chip. It implies that the bus interface should not be taken into account: both raw NAND devices and @@ -67,4 +70,5 @@ properties: required: - reg +# This file can be referenced by more specific devices (like spi-nands) additionalProperties: true diff --git a/Documentation/devicetree/bindings/mtd/nand-controller.yaml b/Documentation/devicetree/bindings/mtd/nand-controller.yaml index 359a015d4e5a..220aa2c8c0b5 100644 --- a/Documentation/devicetree/bindings/mtd/nand-controller.yaml +++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml @@ -51,7 +51,6 @@ properties: patternProperties: "^nand@[a-f0-9]$": - type: object $ref: "nand-chip.yaml#" properties: @@ -130,6 +129,7 @@ required: - "#address-cells" - "#size-cells" +# This is a generic file other binding inherit from and extend additionalProperties: true examples: diff --git a/Documentation/devicetree/bindings/mtd/partition.txt b/Documentation/devicetree/bindings/mtd/partition.txt deleted file mode 100644 index ead90e8274d6..000000000000 --- a/Documentation/devicetree/bindings/mtd/partition.txt +++ /dev/null @@ -1,33 +0,0 @@ -Flash partitions in device tree -=============================== - -Flash devices can be partitioned into one or more functional ranges (e.g. "boot -code", "nvram", "kernel"). - -Different devices may be partitioned in a different ways. Some may use a fixed -flash layout set at production time. Some may use on-flash table that describes -the geometry and naming/purpose of each functional region. It is also possible -to see these methods mixed. - -To assist system software in locating partitions, we allow describing which -method is used for a given flash device. To describe the method there should be -a subnode of the flash device that is named 'partitions'. It must have a -'compatible' property, which is used to identify the method to use. - -When a single partition is represented with a DT node (it depends on a used -format) it may also be described using above rules ('compatible' and optionally -some extra properties / subnodes). It allows describing more complex, -hierarchical (multi-level) layouts and should be used if there is some -significant relation between partitions or some partition internally uses -another partitioning method. - -Available bindings are listed in the "partitions" subdirectory. - - -Deprecated: partitions defined in flash node -============================================ - -For backwards compatibility partitions as direct subnodes of the flash device are -supported. This use is discouraged. -NOTE: also for backwards compatibility, direct subnodes that have a compatible -string are not considered partitions, as they may be used for other bindings. diff --git a/Documentation/devicetree/bindings/mtd/partitions/arm,arm-firmware-suite.yaml b/Documentation/devicetree/bindings/mtd/partitions/arm,arm-firmware-suite.yaml index 76c88027b6d2..97618847ee35 100644 --- a/Documentation/devicetree/bindings/mtd/partitions/arm,arm-firmware-suite.yaml +++ b/Documentation/devicetree/bindings/mtd/partitions/arm,arm-firmware-suite.yaml @@ -9,6 +9,8 @@ title: ARM Firmware Suite (AFS) Partitions maintainers: - Linus Walleij <linus.walleij@linaro.org> +select: false + description: | The ARM Firmware Suite is a flash partitioning system found on the ARM reference designs: Integrator AP, Integrator CP, Versatile AB, diff --git a/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm4908-partitions.yaml b/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm4908-partitions.yaml index 7b113e5e3421..5bbb1c01ddee 100644 --- a/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm4908-partitions.yaml +++ b/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm4908-partitions.yaml @@ -17,6 +17,8 @@ description: | maintainers: - Rafał Miłecki <rafal@milecki.pl> +select: false + properties: compatible: const: brcm,bcm4908-partitions diff --git a/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm947xx-cfe-partitions.yaml b/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm947xx-cfe-partitions.yaml index 3484e06d6bcb..939e7b50db22 100644 --- a/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm947xx-cfe-partitions.yaml +++ b/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm947xx-cfe-partitions.yaml @@ -35,6 +35,8 @@ description: | maintainers: - Rafał Miłecki <rafal@milecki.pl> +select: false + properties: compatible: const: brcm,bcm947xx-cfe-partitions diff --git a/Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml b/Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml index ad3ccd250802..331e564f29dc 100644 --- a/Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml +++ b/Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml @@ -31,24 +31,17 @@ properties: patternProperties: "@[0-9a-f]+$": - allOf: - - $ref: "partition.yaml#" - - if: - properties: - compatible: - contains: - const: sercomm,sc-partitions - then: - properties: - sercomm,scpart-id: - description: Partition id in Sercomm partition map. Mtd - parser uses this id to find a record in the partition map - containing offset and size of the current partition. The - values from partition map overrides partition offset and - size defined in reg property of the dts. Frequently these - values are the same, but may differ if device has bad - eraseblocks on a flash. - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: partition.yaml# + + properties: + sercomm,scpart-id: + description: Partition id in Sercomm partition map. Mtd parser + uses this id to find a record in the partition map containing + offset and size of the current partition. The values from + partition map overrides partition offset and size defined in + reg property of the dts. Frequently these values are the same, + but may differ if device has bad eraseblocks on a flash. + $ref: /schemas/types.yaml#/definitions/uint32 required: - "#address-cells" @@ -84,6 +77,7 @@ examples: partition@0 { label = "filesystem"; reg = <0x00000000 0x1 0x00000000>; + linux,rootfs; }; }; diff --git a/Documentation/devicetree/bindings/mtd/partitions/linksys,ns-partitions.yaml b/Documentation/devicetree/bindings/mtd/partitions/linksys,ns-partitions.yaml index 99249cdfbfb3..213858f60375 100644 --- a/Documentation/devicetree/bindings/mtd/partitions/linksys,ns-partitions.yaml +++ b/Documentation/devicetree/bindings/mtd/partitions/linksys,ns-partitions.yaml @@ -18,6 +18,8 @@ description: | maintainers: - Rafał Miłecki <rafal@milecki.pl> +select: false + properties: compatible: const: linksys,ns-partitions diff --git a/Documentation/devicetree/bindings/mtd/partitions/nvmem-cells.yaml b/Documentation/devicetree/bindings/mtd/partitions/nvmem-cells.yaml index 5cdd2efa9132..5474d63268dc 100644 --- a/Documentation/devicetree/bindings/mtd/partitions/nvmem-cells.yaml +++ b/Documentation/devicetree/bindings/mtd/partitions/nvmem-cells.yaml @@ -17,6 +17,7 @@ maintainers: - Ansuel Smith <ansuelsmth@gmail.com> allOf: + - $ref: /schemas/mtd/partitions/partition.yaml# - $ref: /schemas/nvmem/nvmem.yaml# properties: @@ -26,7 +27,7 @@ properties: required: - compatible -additionalProperties: true +unevaluatedProperties: false examples: - | @@ -84,7 +85,6 @@ examples: compatible = "nvmem-cells"; label = "calibration"; reg = <0xf00000 0x100000>; - ranges = <0 0xf00000 0x100000>; #address-cells = <1>; #size-cells = <1>; diff --git a/Documentation/devicetree/bindings/mtd/partitions/partition.yaml b/Documentation/devicetree/bindings/mtd/partitions/partition.yaml index f1a02d840b12..cdffbb9cedc2 100644 --- a/Documentation/devicetree/bindings/mtd/partitions/partition.yaml +++ b/Documentation/devicetree/bindings/mtd/partitions/partition.yaml @@ -52,6 +52,10 @@ properties: immune to paired-pages corruptions type: boolean + linux,rootfs: + description: Marks partition that contains root filesystem to mount and boot + user space from + if: not: required: [ reg ] @@ -60,4 +64,5 @@ then: $nodename: pattern: '^partition-.*$' +# This is a generic file other binding inherit from and extend additionalProperties: true diff --git a/Documentation/devicetree/bindings/mtd/partitions/partitions.yaml b/Documentation/devicetree/bindings/mtd/partitions/partitions.yaml new file mode 100644 index 000000000000..9aca4e6c6047 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/partitions/partitions.yaml @@ -0,0 +1,41 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/partitions/partitions.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Partitions + +description: | + This binding is generic and describes the content of the partitions container + node. All partition parsers must be referenced here. + +maintainers: + - Miquel Raynal <miquel.raynal@bootlin.com> + +oneOf: + - $ref: arm,arm-firmware-suite.yaml + - $ref: brcm,bcm4908-partitions.yaml + - $ref: brcm,bcm947xx-cfe-partitions.yaml + - $ref: fixed-partitions.yaml + - $ref: linksys,ns-partitions.yaml + - $ref: qcom,smem-part.yaml + - $ref: redboot-fis.yaml + +properties: + compatible: true + + '#address-cells': + enum: [1, 2] + + '#size-cells': + enum: [1, 2] + +patternProperties: + "partition(-.+|@[0-9a-f]+)": + $ref: partition.yaml + +required: + - compatible + +unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/mtd/partitions/qcom,smem-part.yaml b/Documentation/devicetree/bindings/mtd/partitions/qcom,smem-part.yaml index dc07909af023..61d12bda356e 100644 --- a/Documentation/devicetree/bindings/mtd/partitions/qcom,smem-part.yaml +++ b/Documentation/devicetree/bindings/mtd/partitions/qcom,smem-part.yaml @@ -15,13 +15,15 @@ description: | varies between partition table revisions. V3 supports maximum 16 partitions and V4 supports 48 partitions. +select: false + properties: compatible: const: qcom,smem-part patternProperties: "^partition-[0-9a-z]+$": - $ref: partition.yaml# + $ref: nvmem-cells.yaml required: - compatible @@ -39,22 +41,22 @@ examples: - | /* Example declaring dynamic partition */ flash { - partitions { - compatible = "qcom,smem-part"; - - partition-art { - compatible = "nvmem-cells"; - #address-cells = <1>; - #size-cells = <1>; - label = "0:art"; - - macaddr_art_0: macaddr@0 { - reg = <0x0 0x6>; - }; - - macaddr_art_6: macaddr@6 { - reg = <0x6 0x6>; - }; + partitions { + compatible = "qcom,smem-part"; + + partition-art { + compatible = "nvmem-cells"; + #address-cells = <1>; + #size-cells = <1>; + label = "0:art"; + + macaddr_art_0: macaddr@0 { + reg = <0x0 0x6>; + }; + + macaddr_art_6: macaddr@6 { + reg = <0x6 0x6>; + }; + }; }; - }; }; diff --git a/Documentation/devicetree/bindings/mtd/partitions/redboot-fis.yaml b/Documentation/devicetree/bindings/mtd/partitions/redboot-fis.yaml index fee8d81b5276..ba7445cd69e8 100644 --- a/Documentation/devicetree/bindings/mtd/partitions/redboot-fis.yaml +++ b/Documentation/devicetree/bindings/mtd/partitions/redboot-fis.yaml @@ -16,6 +16,8 @@ description: The FLASH Image System (FIS) directory is a flash description maintainers: - Linus Walleij <linus.walleij@linaro.org> +select: false + properties: compatible: const: redboot-fis @@ -26,6 +28,10 @@ properties: device. On a flash memory with 32KB eraseblocks, 0 means the first eraseblock at 0x00000000, 1 means the second eraseblock at 0x00008000 and so on. + '#address-cells': false + + '#size-cells': false + required: - compatible - fis-index-block diff --git a/Documentation/devicetree/bindings/mtd/partitions/tplink,safeloader-partitions.yaml b/Documentation/devicetree/bindings/mtd/partitions/tplink,safeloader-partitions.yaml new file mode 100644 index 000000000000..a24bbaac3a90 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/partitions/tplink,safeloader-partitions.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/partitions/tplink,safeloader-partitions.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TP-Link SafeLoader partitions + +description: | + TP-Link home routers store various data on flash (e.g. bootloader, + flash layout, firmware, product info, configuration, calibration + data). That requires flash partitioning. + + Flash space layout of TP-Link devices is stored on flash itself using + a custom ASCII-based format. That format was first found in TP-Link + devices with a custom SafeLoader bootloader. Later it was adapted to + CFE and U-Boot bootloaders. + + Partitions specified in partitions table cover whole flash space. Some + contain static data that shouldn't get modified (device's MAC or WiFi + calibration data). Others are semi-static (like kernel). Finally some + partitions contain fully changeable content (like rootfs). + + This binding describes partitioning method and defines offset of ASCII + based partitions table. That offset is picked at manufacturing process + and doesn't change. + +maintainers: + - Rafał Miłecki <rafal@milecki.pl> + +properties: + compatible: + const: tplink,safeloader-partitions + + partitions-table-offset: + description: Flash offset of partitions table + $ref: /schemas/types.yaml#/definitions/uint32 + +patternProperties: + "^partition-.*$": + $ref: partition.yaml# + +required: + - partitions-table-offset + +additionalProperties: false + +examples: + - | + partitions { + compatible = "tplink,safeloader-partitions"; + partitions-table-offset = <0x100000>; + + partition-file-system { + linux,rootfs; + }; + }; diff --git a/Documentation/devicetree/bindings/mtd/partitions/u-boot.yaml b/Documentation/devicetree/bindings/mtd/partitions/u-boot.yaml index 8a88e7d16524..3c56efe48efd 100644 --- a/Documentation/devicetree/bindings/mtd/partitions/u-boot.yaml +++ b/Documentation/devicetree/bindings/mtd/partitions/u-boot.yaml @@ -27,6 +27,10 @@ properties: Broadcom stores environment variables inside a U-Boot partition. They can be identified by a custom header with magic value. +patternProperties: + "^partition-.*$": + $ref: partition.yaml# + unevaluatedProperties: false examples: @@ -40,6 +44,9 @@ examples: compatible = "brcm,u-boot"; reg = <0x0 0x100000>; label = "u-boot"; + + partition-u-boot-env { + }; }; partition@100000 { diff --git a/Documentation/devicetree/bindings/mtd/qcom,nandc.yaml b/Documentation/devicetree/bindings/mtd/qcom,nandc.yaml index 482a2c068740..07024ee45951 100644 --- a/Documentation/devicetree/bindings/mtd/qcom,nandc.yaml +++ b/Documentation/devicetree/bindings/mtd/qcom,nandc.yaml @@ -31,9 +31,6 @@ properties: - const: core - const: aon - "#address-cells": true - "#size-cells": true - patternProperties: "^nand@[a-f0-9]$": type: object @@ -139,85 +136,85 @@ examples: - | #include <dt-bindings/clock/qcom,gcc-ipq806x.h> nand-controller@1ac00000 { - compatible = "qcom,ipq806x-nand"; - reg = <0x1ac00000 0x800>; + compatible = "qcom,ipq806x-nand"; + reg = <0x1ac00000 0x800>; - clocks = <&gcc EBI2_CLK>, - <&gcc EBI2_AON_CLK>; - clock-names = "core", "aon"; + clocks = <&gcc EBI2_CLK>, + <&gcc EBI2_AON_CLK>; + clock-names = "core", "aon"; - dmas = <&adm_dma 3>; - dma-names = "rxtx"; - qcom,cmd-crci = <15>; - qcom,data-crci = <3>; + dmas = <&adm_dma 3>; + dma-names = "rxtx"; + qcom,cmd-crci = <15>; + qcom,data-crci = <3>; - #address-cells = <1>; - #size-cells = <0>; + #address-cells = <1>; + #size-cells = <0>; - nand@0 { - reg = <0>; + nand@0 { + reg = <0>; - nand-ecc-strength = <4>; - nand-bus-width = <8>; + nand-ecc-strength = <4>; + nand-bus-width = <8>; - qcom,boot-partitions = <0x0 0x58a0000>; + qcom,boot-partitions = <0x0 0x58a0000>; - partitions { - compatible = "fixed-partitions"; - #address-cells = <1>; - #size-cells = <1>; + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; - partition@0 { - label = "boot-nand"; - reg = <0 0x58a0000>; - }; + partition@0 { + label = "boot-nand"; + reg = <0 0x58a0000>; + }; - partition@58a0000 { - label = "fs-nand"; - reg = <0x58a0000 0x4000000>; - }; + partition@58a0000 { + label = "fs-nand"; + reg = <0x58a0000 0x4000000>; + }; + }; }; - }; }; #include <dt-bindings/clock/qcom,gcc-ipq4019.h> nand-controller@79b0000 { - compatible = "qcom,ipq4019-nand"; - reg = <0x79b0000 0x1000>; - - clocks = <&gcc GCC_QPIC_CLK>, - <&gcc GCC_QPIC_AHB_CLK>; - clock-names = "core", "aon"; - - dmas = <&qpicbam 0>, - <&qpicbam 1>, - <&qpicbam 2>; - dma-names = "tx", "rx", "cmd"; - - #address-cells = <1>; - #size-cells = <0>; - - nand@0 { - reg = <0>; - nand-ecc-strength = <4>; - nand-bus-width = <8>; - - partitions { - compatible = "fixed-partitions"; - #address-cells = <1>; - #size-cells = <1>; - - partition@0 { - label = "boot-nand"; - reg = <0 0x58a0000>; - }; - - partition@58a0000 { - label = "fs-nand"; - reg = <0x58a0000 0x4000000>; - }; + compatible = "qcom,ipq4019-nand"; + reg = <0x79b0000 0x1000>; + + clocks = <&gcc GCC_QPIC_CLK>, + <&gcc GCC_QPIC_AHB_CLK>; + clock-names = "core", "aon"; + + dmas = <&qpicbam 0>, + <&qpicbam 1>, + <&qpicbam 2>; + dma-names = "tx", "rx", "cmd"; + + #address-cells = <1>; + #size-cells = <0>; + + nand@0 { + reg = <0>; + nand-ecc-strength = <4>; + nand-bus-width = <8>; + + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + partition@0 { + label = "boot-nand"; + reg = <0 0x58a0000>; + }; + + partition@58a0000 { + label = "fs-nand"; + reg = <0x58a0000 0x4000000>; + }; + }; }; - }; }; ... diff --git a/Documentation/devicetree/bindings/mtd/rockchip,nand-controller.yaml b/Documentation/devicetree/bindings/mtd/rockchip,nand-controller.yaml index d681a4676f06..566f330851f7 100644 --- a/Documentation/devicetree/bindings/mtd/rockchip,nand-controller.yaml +++ b/Documentation/devicetree/bindings/mtd/rockchip,nand-controller.yaml @@ -19,7 +19,9 @@ properties: - const: rockchip,rk2928-nfc - const: rockchip,rv1108-nfc - items: - - const: rockchip,rk3036-nfc + - enum: + - rockchip,rk3036-nfc + - rockchip,rk3128-nfc - const: rockchip,rk2928-nfc - items: - const: rockchip,rk3308-nfc diff --git a/Documentation/devicetree/bindings/mtd/st,stm32-fmc2-nand.yaml b/Documentation/devicetree/bindings/mtd/st,stm32-fmc2-nand.yaml index eab8ea3da1fa..8cbfa1504a0f 100644 --- a/Documentation/devicetree/bindings/mtd/st,stm32-fmc2-nand.yaml +++ b/Documentation/devicetree/bindings/mtd/st,stm32-fmc2-nand.yaml @@ -101,31 +101,32 @@ examples: #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/clock/stm32mp1-clks.h> #include <dt-bindings/reset/stm32mp1-resets.h> + nand-controller@58002000 { - compatible = "st,stm32mp15-fmc2"; - reg = <0x58002000 0x1000>, - <0x80000000 0x1000>, - <0x88010000 0x1000>, - <0x88020000 0x1000>, - <0x81000000 0x1000>, - <0x89010000 0x1000>, - <0x89020000 0x1000>; - interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>; - dmas = <&mdma1 20 0x2 0x12000a02 0x0 0x0>, - <&mdma1 20 0x2 0x12000a08 0x0 0x0>, - <&mdma1 21 0x2 0x12000a0a 0x0 0x0>; - dma-names = "tx", "rx", "ecc"; - clocks = <&rcc FMC_K>; - resets = <&rcc FMC_R>; - #address-cells = <1>; - #size-cells = <0>; - - nand@0 { - reg = <0>; - nand-on-flash-bbt; + compatible = "st,stm32mp15-fmc2"; + reg = <0x58002000 0x1000>, + <0x80000000 0x1000>, + <0x88010000 0x1000>, + <0x88020000 0x1000>, + <0x81000000 0x1000>, + <0x89010000 0x1000>, + <0x89020000 0x1000>; + interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>; + dmas = <&mdma1 20 0x2 0x12000a02 0x0 0x0>, + <&mdma1 20 0x2 0x12000a08 0x0 0x0>, + <&mdma1 21 0x2 0x12000a0a 0x0 0x0>; + dma-names = "tx", "rx", "ecc"; + clocks = <&rcc FMC_K>; + resets = <&rcc FMC_R>; #address-cells = <1>; - #size-cells = <1>; - }; + #size-cells = <0>; + + nand@0 { + reg = <0>; + nand-on-flash-bbt; + #address-cells = <1>; + #size-cells = <1>; + }; }; ... diff --git a/Documentation/devicetree/bindings/mtd/ti,am654-hbmc.yaml b/Documentation/devicetree/bindings/mtd/ti,am654-hbmc.yaml index 30b458c41cac..4774c92e7fc4 100644 --- a/Documentation/devicetree/bindings/mtd/ti,am654-hbmc.yaml +++ b/Documentation/devicetree/bindings/mtd/ti,am654-hbmc.yaml @@ -44,26 +44,26 @@ additionalProperties: false examples: - | bus { - #address-cells = <2>; - #size-cells = <2>; - - hbmc: memory-controller@47034000 { - compatible = "ti,am654-hbmc"; - reg = <0x0 0x47034000 0x0 0x100>, - <0x5 0x00000000 0x1 0x0000000>; - ranges = <0x0 0x0 0x5 0x00000000 0x4000000>, /* CS0 - 64MB */ - <0x1 0x0 0x5 0x04000000 0x4000000>; /* CS1 - 64MB */ - clocks = <&k3_clks 102 0>; #address-cells = <2>; - #size-cells = <1>; - power-domains = <&k3_pds 55>; - mux-controls = <&hbmc_mux 0>; + #size-cells = <2>; - flash@0,0 { - compatible = "cypress,hyperflash", "cfi-flash"; - reg = <0x0 0x0 0x4000000>; - #address-cells = <1>; + hbmc: memory-controller@47034000 { + compatible = "ti,am654-hbmc"; + reg = <0x0 0x47034000 0x0 0x100>, + <0x5 0x00000000 0x1 0x0000000>; + ranges = <0x0 0x0 0x5 0x00000000 0x4000000>, /* CS0 - 64MB */ + <0x1 0x0 0x5 0x04000000 0x4000000>; /* CS1 - 64MB */ + clocks = <&k3_clks 102 0>; + #address-cells = <2>; #size-cells = <1>; + power-domains = <&k3_pds 55>; + mux-controls = <&hbmc_mux 0>; + + flash@0,0 { + compatible = "cypress,hyperflash", "cfi-flash"; + reg = <0x0 0x0 0x4000000>; + #address-cells = <1>; + #size-cells = <1>; + }; }; - }; }; diff --git a/Documentation/devicetree/bindings/mtd/ti,gpmc-onenand.yaml b/Documentation/devicetree/bindings/mtd/ti,gpmc-onenand.yaml index a953f7397c40..8a79ad300216 100644 --- a/Documentation/devicetree/bindings/mtd/ti,gpmc-onenand.yaml +++ b/Documentation/devicetree/bindings/mtd/ti,gpmc-onenand.yaml @@ -15,6 +15,9 @@ description: as child nodes of the GPMC controller. properties: + $nodename: + pattern: "^onenand@[0-9],[0,9]$" + compatible: const: ti,omap2-onenand diff --git a/Documentation/devicetree/bindings/net/adi,adin1110.yaml b/Documentation/devicetree/bindings/net/adi,adin1110.yaml index b6bd8ee38a18..9de865295d7a 100644 --- a/Documentation/devicetree/bindings/net/adi,adin1110.yaml +++ b/Documentation/devicetree/bindings/net/adi,adin1110.yaml @@ -46,6 +46,10 @@ properties: interrupts: maxItems: 1 + reset-gpios: + maxItems: 1 + description: GPIO connected to active low reset + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/net/asix,ax88178.yaml b/Documentation/devicetree/bindings/net/asix,ax88178.yaml index 1af52358de4c..a81dbc4792f6 100644 --- a/Documentation/devicetree/bindings/net/asix,ax88178.yaml +++ b/Documentation/devicetree/bindings/net/asix,ax88178.yaml @@ -27,7 +27,9 @@ properties: - usbb95,772b # ASIX AX88772B - usbb95,7e2b # ASIX AX88772B - reg: true + reg: + maxItems: 1 + local-mac-address: true mac-address: true diff --git a/Documentation/devicetree/bindings/net/bluetooth.txt b/Documentation/devicetree/bindings/net/bluetooth.txt deleted file mode 100644 index 94797df751b8..000000000000 --- a/Documentation/devicetree/bindings/net/bluetooth.txt +++ /dev/null @@ -1,5 +0,0 @@ -The following properties are common to the Bluetooth controllers: - -- local-bd-address: array of 6 bytes, specifies the BD address that was - uniquely assigned to the Bluetooth device, formatted with least significant - byte first (little-endian). diff --git a/Documentation/devicetree/bindings/net/bluetooth/bluetooth-controller.yaml b/Documentation/devicetree/bindings/net/bluetooth/bluetooth-controller.yaml new file mode 100644 index 000000000000..9309dc40f54f --- /dev/null +++ b/Documentation/devicetree/bindings/net/bluetooth/bluetooth-controller.yaml @@ -0,0 +1,29 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/bluetooth/bluetooth-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Bluetooth Controller Generic Binding + +maintainers: + - Marcel Holtmann <marcel@holtmann.org> + - Johan Hedberg <johan.hedberg@gmail.com> + - Luiz Augusto von Dentz <luiz.dentz@gmail.com> + +properties: + $nodename: + pattern: "^bluetooth(@.*)?$" + + local-bd-address: + $ref: /schemas/types.yaml#/definitions/uint8-array + maxItems: 6 + description: + Specifies the BD address that was uniquely assigned to the Bluetooth + device. Formatted with least significant byte first (little-endian), e.g. + in order to assign the address 00:11:22:33:44:55 this property must have + the value [55 44 33 22 11 00]. + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/net/bluetooth/brcm,bcm4377-bluetooth.yaml b/Documentation/devicetree/bindings/net/bluetooth/brcm,bcm4377-bluetooth.yaml new file mode 100644 index 000000000000..37cb39a3a62e --- /dev/null +++ b/Documentation/devicetree/bindings/net/bluetooth/brcm,bcm4377-bluetooth.yaml @@ -0,0 +1,81 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/bluetooth/brcm,bcm4377-bluetooth.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM4377 family PCIe Bluetooth Chips + +maintainers: + - Sven Peter <sven@svenpeter.dev> + +description: + This binding describes Broadcom BCM4377 family PCIe-attached bluetooth chips + usually found in Apple machines. The Wi-Fi part of the chip is described in + bindings/net/wireless/brcm,bcm4329-fmac.yaml. + +allOf: + - $ref: bluetooth-controller.yaml# + +properties: + compatible: + enum: + - pci14e4,5fa0 # BCM4377 + - pci14e4,5f69 # BCM4378 + - pci14e4,5f71 # BCM4387 + + reg: + maxItems: 1 + + brcm,board-type: + $ref: /schemas/types.yaml#/definitions/string + description: Board type of the Bluetooth chip. This is used to decouple + the overall system board from the Bluetooth module and used to construct + firmware and calibration data filenames. + On Apple platforms, this should be the Apple module-instance codename + prefixed by "apple,", e.g. "apple,atlantisb". + pattern: '^apple,.*' + + brcm,taurus-cal-blob: + $ref: /schemas/types.yaml#/definitions/uint8-array + description: A per-device calibration blob for the Bluetooth radio. This + should be filled in by the bootloader from platform configuration + data, if necessary, and will be uploaded to the device. + This blob is used if the chip stepping of the Bluetooth module does not + support beamforming. + + brcm,taurus-bf-cal-blob: + $ref: /schemas/types.yaml#/definitions/uint8-array + description: A per-device calibration blob for the Bluetooth radio. This + should be filled in by the bootloader from platform configuration + data, if necessary, and will be uploaded to the device. + This blob is used if the chip stepping of the Bluetooth module supports + beamforming. + + local-bd-address: true + +required: + - compatible + - reg + - local-bd-address + - brcm,board-type + +additionalProperties: false + +examples: + - | + pcie@a0000000 { + #address-cells = <3>; + #size-cells = <2>; + reg = <0xa0000000 0x1000000>; + device_type = "pci"; + ranges = <0x43000000 0x6 0xa0000000 0xa0000000 0x0 0x20000000>; + + bluetooth@0,1 { + compatible = "pci14e4,5f69"; + reg = <0x100 0x0 0x0 0x0 0x0>; + brcm,board-type = "apple,honshu"; + /* To be filled by the bootloader */ + local-bd-address = [00 00 00 00 00 00]; + }; + }; diff --git a/Documentation/devicetree/bindings/net/qualcomm-bluetooth.yaml b/Documentation/devicetree/bindings/net/bluetooth/qualcomm-bluetooth.yaml index f93c6e7a1b59..a6a6b0e4df7a 100644 --- a/Documentation/devicetree/bindings/net/qualcomm-bluetooth.yaml +++ b/Documentation/devicetree/bindings/net/bluetooth/qualcomm-bluetooth.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/net/qualcomm-bluetooth.yaml# +$id: http://devicetree.org/schemas/net/bluetooth/qualcomm-bluetooth.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Bluetooth Chips @@ -79,8 +79,7 @@ properties: firmware-name: description: specify the name of nvm firmware to load - local-bd-address: - description: see Documentation/devicetree/bindings/net/bluetooth.txt + local-bd-address: true required: @@ -89,6 +88,7 @@ required: additionalProperties: false allOf: + - $ref: bluetooth-controller.yaml# - if: properties: compatible: diff --git a/Documentation/devicetree/bindings/net/broadcom-bluetooth.yaml b/Documentation/devicetree/bindings/net/broadcom-bluetooth.yaml index 445b2a553625..b964c7dcec15 100644 --- a/Documentation/devicetree/bindings/net/broadcom-bluetooth.yaml +++ b/Documentation/devicetree/bindings/net/broadcom-bluetooth.yaml @@ -19,11 +19,14 @@ properties: - brcm,bcm4329-bt - brcm,bcm4330-bt - brcm,bcm4334-bt + - brcm,bcm43430a0-bt + - brcm,bcm43430a1-bt - brcm,bcm43438-bt - brcm,bcm4345c5 - brcm,bcm43540-bt - brcm,bcm4335a0 - brcm,bcm4349-bt + - cypress,cyw4373a0-bt - infineon,cyw55572-bt shutdown-gpios: diff --git a/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml b/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml index e52db841bb8c..6e59bd2a6094 100644 --- a/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml +++ b/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml @@ -17,6 +17,7 @@ properties: compatible: oneOf: - enum: + - fsl,imx93-flexcan - fsl,imx8qm-flexcan - fsl,imx8mp-flexcan - fsl,imx6q-flexcan diff --git a/Documentation/devicetree/bindings/net/can/renesas,rcar-canfd.yaml b/Documentation/devicetree/bindings/net/can/renesas,rcar-canfd.yaml index 6f71fc96bc4e..1eb98c9a1a26 100644 --- a/Documentation/devicetree/bindings/net/can/renesas,rcar-canfd.yaml +++ b/Documentation/devicetree/bindings/net/can/renesas,rcar-canfd.yaml @@ -9,9 +9,6 @@ title: Renesas R-Car CAN FD Controller maintainers: - Fabrizio Castro <fabrizio.castro.jz@renesas.com> -allOf: - - $ref: can-controller.yaml# - properties: compatible: oneOf: @@ -33,7 +30,7 @@ properties: - items: - enum: - - renesas,r9a07g043-canfd # RZ/G2UL + - 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 @@ -77,12 +74,13 @@ properties: description: Maximum frequency of the CANFD clock. patternProperties: - "^channel[01]$": + "^channel[0-7]$": type: object description: - The controller supports two channels and each is represented as a child - node. Each child node supports the "status" property only, which - is used to enable/disable the respective channel. + The controller supports multiple channels and each is represented as a + child node. Each channel can be enabled/disabled individually. + + additionalProperties: false required: - compatible @@ -98,60 +96,73 @@ required: - channel0 - channel1 -if: - properties: - compatible: - contains: - enum: - - renesas,rzg2l-canfd -then: - properties: - interrupts: - items: - - description: CAN global error interrupt - - description: CAN receive FIFO interrupt - - description: CAN0 error interrupt - - description: CAN0 transmit interrupt - - description: CAN0 transmit/receive FIFO receive completion interrupt - - description: CAN1 error interrupt - - description: CAN1 transmit interrupt - - description: CAN1 transmit/receive FIFO receive completion interrupt - - interrupt-names: - items: - - const: g_err - - const: g_recc - - const: ch0_err - - const: ch0_rec - - const: ch0_trx - - const: ch1_err - - const: ch1_rec - - const: ch1_trx - - resets: - maxItems: 2 - - reset-names: - items: - - const: rstp_n - - const: rstc_n - - required: - - reset-names -else: - properties: - interrupts: - items: - - description: Channel interrupt - - description: Global interrupt - - interrupt-names: - items: - - const: ch_int - - const: g_int - - resets: - maxItems: 1 +allOf: + - $ref: can-controller.yaml# + + - if: + properties: + compatible: + contains: + enum: + - renesas,rzg2l-canfd + then: + properties: + interrupts: + items: + - description: CAN global error interrupt + - description: CAN receive FIFO interrupt + - description: CAN0 error interrupt + - description: CAN0 transmit interrupt + - description: CAN0 transmit/receive FIFO receive completion interrupt + - description: CAN1 error interrupt + - description: CAN1 transmit interrupt + - description: CAN1 transmit/receive FIFO receive completion interrupt + + interrupt-names: + items: + - const: g_err + - const: g_recc + - const: ch0_err + - const: ch0_rec + - const: ch0_trx + - const: ch1_err + - const: ch1_rec + - const: ch1_trx + + resets: + maxItems: 2 + + reset-names: + items: + - const: rstp_n + - const: rstc_n + + required: + - reset-names + else: + properties: + interrupts: + items: + - description: Channel interrupt + - description: Global interrupt + + interrupt-names: + items: + - const: ch_int + - const: g_int + + resets: + maxItems: 1 + + - if: + not: + properties: + compatible: + contains: + const: renesas,r8a779a0-canfd + then: + patternProperties: + "^channel[2-7]$": false unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/net/cdns,macb.yaml b/Documentation/devicetree/bindings/net/cdns,macb.yaml index 318f4efe7f6f..bef5e0f895be 100644 --- a/Documentation/devicetree/bindings/net/cdns,macb.yaml +++ b/Documentation/devicetree/bindings/net/cdns,macb.yaml @@ -203,7 +203,6 @@ examples: power-domains = <&zynqmp_firmware PD_ETH_1>; resets = <&zynqmp_reset ZYNQMP_RESET_GEM1>; reset-names = "gem1_rst"; - status = "okay"; phy-mode = "sgmii"; phys = <&psgtr 1 PHY_TYPE_SGMII 1 1>; fixed-link { diff --git a/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml b/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml index 10ad7e71097b..9abb8eba5fad 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml +++ b/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml @@ -19,7 +19,8 @@ allOf: properties: reg: - description: Port number + items: + - description: Port number label: description: diff --git a/Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml b/Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml index 73b774eadd0b..1d7dab31457d 100644 --- a/Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml +++ b/Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml @@ -12,7 +12,7 @@ allOf: maintainers: - Andrew Lunn <andrew@lunn.ch> - Florian Fainelli <f.fainelli@gmail.com> - - Vivien Didelot <vivien.didelot@gmail.com> + - Vladimir Oltean <olteanv@gmail.com> - Kurt Kanzenbach <kurt@linutronix.de> description: diff --git a/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml b/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml index 7ca9c19a157c..0a0d62b6c00e 100644 --- a/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml +++ b/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml @@ -74,10 +74,10 @@ properties: properties: pcs-handle: + maxItems: 1 description: phandle pointing to a PCS sub-node compatible with renesas,rzn1-miic.yaml# - $ref: /schemas/types.yaml#/definitions/phandle unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/net/engleder,tsnep.yaml b/Documentation/devicetree/bindings/net/engleder,tsnep.yaml index 5bd964a46a9d..a6921e805e37 100644 --- a/Documentation/devicetree/bindings/net/engleder,tsnep.yaml +++ b/Documentation/devicetree/bindings/net/engleder,tsnep.yaml @@ -47,7 +47,7 @@ properties: nvmem-cells: true - nvmem-cells-names: true + nvmem-cell-names: true phy-connection-type: enum: diff --git a/Documentation/devicetree/bindings/net/ethernet-controller.yaml b/Documentation/devicetree/bindings/net/ethernet-controller.yaml index 4b3c590fcebf..3aef506fa158 100644 --- a/Documentation/devicetree/bindings/net/ethernet-controller.yaml +++ b/Documentation/devicetree/bindings/net/ethernet-controller.yaml @@ -108,11 +108,17 @@ properties: $ref: "#/properties/phy-connection-type" pcs-handle: - $ref: /schemas/types.yaml#/definitions/phandle + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + maxItems: 1 description: Specifies a reference to a node representing a PCS PHY device on a MDIO bus to link with an external PHY (phy-handle) if exists. + pcs-handle-names: + description: + The name of each PCS in pcs-handle. + phy-handle: $ref: /schemas/types.yaml#/definitions/phandle description: @@ -216,6 +222,9 @@ properties: required: - speed +dependencies: + pcs-handle-names: [pcs-handle] + allOf: - if: properties: diff --git a/Documentation/devicetree/bindings/net/fsl,fec.yaml b/Documentation/devicetree/bindings/net/fsl,fec.yaml index e0f376f7e274..77e5f32cb62f 100644 --- a/Documentation/devicetree/bindings/net/fsl,fec.yaml +++ b/Documentation/devicetree/bindings/net/fsl,fec.yaml @@ -7,7 +7,9 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Freescale Fast Ethernet Controller (FEC) maintainers: - - Joakim Zhang <qiangqing.zhang@nxp.com> + - Shawn Guo <shawnguo@kernel.org> + - Wei Fang <wei.fang@nxp.com> + - NXP Linux Team <linux-imx@nxp.com> allOf: - $ref: ethernet-controller.yaml# diff --git a/Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml b/Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml index 3a35ac1c260d..c80c880a9dab 100644 --- a/Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml +++ b/Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml @@ -85,9 +85,39 @@ properties: $ref: /schemas/types.yaml#/definitions/phandle description: A reference to the IEEE1588 timer + phys: + description: A reference to the SerDes lane(s) + maxItems: 1 + + phy-names: + items: + - const: serdes + pcsphy-handle: - $ref: /schemas/types.yaml#/definitions/phandle - description: A reference to the PCS (typically found on the SerDes) + $ref: /schemas/types.yaml#/definitions/phandle-array + minItems: 1 + maxItems: 3 + deprecated: true + description: See pcs-handle. + + pcs-handle: + minItems: 1 + maxItems: 3 + description: | + A reference to the various PCSs (typically found on the SerDes). If + pcs-handle-names is absent, and phy-connection-type is "xgmii", then the first + reference will be assumed to be for "xfi". Otherwise, if pcs-handle-names is + absent, then the first reference will be assumed to be for "sgmii". + + pcs-handle-names: + minItems: 1 + maxItems: 3 + items: + enum: + - sgmii + - qsgmii + - xfi + description: The type of each PCS in pcsphy-handle. tbi-handle: $ref: /schemas/types.yaml#/definitions/phandle @@ -100,6 +130,10 @@ required: - fsl,fman-ports - ptp-timer +dependencies: + pcs-handle-names: + - pcs-handle + allOf: - $ref: ethernet-controller.yaml# - if: @@ -110,14 +144,6 @@ allOf: then: required: - tbi-handle - - if: - properties: - compatible: - contains: - const: fsl,fman-memac - then: - required: - - pcsphy-handle unevaluatedProperties: false @@ -138,8 +164,9 @@ examples: reg = <0xe8000 0x1000>; fsl,fman-ports = <&fman0_rx_0x0c &fman0_tx_0x2c>; ptp-timer = <&ptp_timer0>; - pcsphy-handle = <&pcsphy4>; - phy-handle = <&sgmii_phy1>; - phy-connection-type = "sgmii"; + pcs-handle = <&pcsphy4>, <&qsgmiib_pcs1>; + pcs-handle-names = "sgmii", "qsgmii"; + phys = <&serdes1 1>; + phy-names = "serdes"; }; ... diff --git a/Documentation/devicetree/bindings/net/fsl,qoriq-mc-dpmac.yaml b/Documentation/devicetree/bindings/net/fsl,qoriq-mc-dpmac.yaml index 7f620a71a972..600240281e8c 100644 --- a/Documentation/devicetree/bindings/net/fsl,qoriq-mc-dpmac.yaml +++ b/Documentation/devicetree/bindings/net/fsl,qoriq-mc-dpmac.yaml @@ -31,7 +31,7 @@ properties: phy-mode: true pcs-handle: - $ref: /schemas/types.yaml#/definitions/phandle + maxItems: 1 description: A reference to a node representing a PCS PHY device found on the internal MDIO bus. diff --git a/Documentation/devicetree/bindings/net/fsl-fman.txt b/Documentation/devicetree/bindings/net/fsl-fman.txt index b9055335db3b..bda4b41af074 100644 --- a/Documentation/devicetree/bindings/net/fsl-fman.txt +++ b/Documentation/devicetree/bindings/net/fsl-fman.txt @@ -320,8 +320,9 @@ For internal PHY device on internal mdio bus, a PHY node should be created. See the definition of the PHY node in booting-without-of.txt for an example of how to define a PHY (Internal PHY has no interrupt line). - For "fsl,fman-mdio" compatible internal mdio bus, the PHY is TBI PHY. -- For "fsl,fman-memac-mdio" compatible internal mdio bus, the PHY is PCS PHY, - PCS PHY addr must be '0'. +- For "fsl,fman-memac-mdio" compatible internal mdio bus, the PHY is PCS PHY. + The PCS PHY address should correspond to the value of the appropriate + MDEV_PORT. EXAMPLE diff --git a/Documentation/devicetree/bindings/net/marvell,dfx-server.yaml b/Documentation/devicetree/bindings/net/marvell,dfx-server.yaml new file mode 100644 index 000000000000..8a14c919e3f7 --- /dev/null +++ b/Documentation/devicetree/bindings/net/marvell,dfx-server.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/marvell,dfx-server.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell Prestera DFX server + +maintainers: + - Miquel Raynal <miquel.raynal@bootlin.com> + +select: + properties: + compatible: + contains: + const: marvell,dfx-server + required: + - compatible + +properties: + compatible: + items: + - const: marvell,dfx-server + - const: simple-bus + + reg: + maxItems: 1 + + ranges: true + + '#address-cells': + const: 1 + + '#size-cells': + const: 1 + +required: + - compatible + - reg + - ranges + +# The DFX server may expose clocks described as subnodes +additionalProperties: + type: object + +examples: + - | + + #define MBUS_ID(target,attributes) (((target) << 24) | ((attributes) << 16)) + bus@0 { + reg = <0 0>; + #address-cells = <2>; + #size-cells = <1>; + + dfx-bus@ac000000 { + compatible = "marvell,dfx-server", "simple-bus"; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 MBUS_ID(0x08, 0x00) 0 0x100000>; + reg = <MBUS_ID(0x08, 0x00) 0 0x100000>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/marvell,pp2.yaml b/Documentation/devicetree/bindings/net/marvell,pp2.yaml new file mode 100644 index 000000000000..4eadafc43d4f --- /dev/null +++ b/Documentation/devicetree/bindings/net/marvell,pp2.yaml @@ -0,0 +1,305 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/marvell,pp2.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell CN913X / Marvell Armada 375, 7K, 8K Ethernet Controller + +maintainers: + - Marcin Wojtas <mw@semihalf.com> + - Russell King <linux@armlinux.org> + +description: | + Marvell Armada 375 Ethernet Controller (PPv2.1) + Marvell Armada 7K/8K Ethernet Controller (PPv2.2) + Marvell CN913X Ethernet Controller (PPv2.3) + +properties: + compatible: + enum: + - marvell,armada-375-pp2 + - marvell,armada-7k-pp22 + + reg: + minItems: 3 + maxItems: 4 + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + clocks: + minItems: 2 + items: + - description: main controller clock + - description: GOP clock + - description: MG clock + - description: MG Core clock + - description: AXI clock + + clock-names: + minItems: 2 + items: + - const: pp_clk + - const: gop_clk + - const: mg_clk + - const: mg_core_clk + - const: axi_clk + + dma-coherent: true + + marvell,system-controller: + $ref: /schemas/types.yaml#/definitions/phandle + description: a phandle to the system controller. + +patternProperties: + '^(ethernet-)?port@[0-2]$': + type: object + description: subnode for each ethernet port. + $ref: ethernet-controller.yaml# + unevaluatedProperties: false + + properties: + reg: + description: ID of the port from the MAC point of view. + maximum: 2 + + interrupts: + minItems: 1 + maxItems: 10 + description: interrupt(s) for the port + + interrupt-names: + minItems: 1 + items: + - const: hif0 + - const: hif1 + - const: hif2 + - const: hif3 + - const: hif4 + - const: hif5 + - const: hif6 + - const: hif7 + - const: hif8 + - const: link + + description: > + if more than a single interrupt for is given, must be the + name associated to the interrupts listed. Valid names are: + "hifX", with X in [0..8], and "link". The names "tx-cpu0", + "tx-cpu1", "tx-cpu2", "tx-cpu3" and "rx-shared" are supported + for backward compatibility but shouldn't be used for new + additions. + + phys: + minItems: 1 + maxItems: 2 + description: > + Generic PHY, providing SerDes connectivity. For most modes, + one lane is sufficient, but some (e.g. RXAUI) may require two. + + phy-mode: + enum: + - gmii + - sgmii + - rgmii-id + - 1000base-x + - 2500base-x + - 5gbase-r + - rxaui + - 10gbase-r + + port-id: + $ref: /schemas/types.yaml#/definitions/uint32 + deprecated: true + description: > + ID of the port from the MAC point of view. + Legacy binding for backward compatibility. + + marvell,loopback: + $ref: /schemas/types.yaml#/definitions/flag + description: port is loopback mode. + + gop-port-id: + $ref: /schemas/types.yaml#/definitions/uint32 + description: > + only for marvell,armada-7k-pp22, ID of the port from the + GOP (Group Of Ports) point of view. This ID is used to index the + per-port registers in the second register area. + + required: + - reg + - interrupts + - phy-mode + - port-id + +required: + - compatible + - reg + - clocks + - clock-names + +allOf: + - if: + properties: + compatible: + const: marvell,armada-7k-pp22 + then: + properties: + reg: + items: + - description: Packet Processor registers + - description: Networking interfaces registers + - description: CM3 address space used for TX Flow Control + + clocks: + minItems: 5 + + clock-names: + minItems: 5 + + patternProperties: + '^(ethernet-)?port@[0-2]$': + required: + - gop-port-id + + required: + - marvell,system-controller + else: + properties: + reg: + items: + - description: Packet Processor registers + - description: LMS registers + - description: Register area per eth0 + - description: Register area per eth1 + + clocks: + maxItems: 2 + + clock-names: + maxItems: 2 + + patternProperties: + '^(ethernet-)?port@[0-1]$': + properties: + reg: + maximum: 1 + + gop-port-id: false + +additionalProperties: false + +examples: + - | + // For Armada 375 variant + #include <dt-bindings/interrupt-controller/mvebu-icu.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + ethernet@f0000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "marvell,armada-375-pp2"; + reg = <0xf0000 0xa000>, + <0xc0000 0x3060>, + <0xc4000 0x100>, + <0xc5000 0x100>; + clocks = <&gateclk 3>, <&gateclk 19>; + clock-names = "pp_clk", "gop_clk"; + + ethernet-port@0 { + interrupts = <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>; + reg = <0>; + port-id = <0>; /* For backward compatibility. */ + phy = <&phy0>; + phy-mode = "rgmii-id"; + }; + + ethernet-port@1 { + interrupts = <GIC_SPI 41 IRQ_TYPE_LEVEL_HIGH>; + reg = <1>; + port-id = <1>; /* For backward compatibility. */ + phy = <&phy3>; + phy-mode = "gmii"; + }; + }; + + - | + // For Armada 7k/8k and Cn913x variants + #include <dt-bindings/interrupt-controller/mvebu-icu.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + ethernet@0 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "marvell,armada-7k-pp22"; + reg = <0x0 0x100000>, <0x129000 0xb000>, <0x220000 0x800>; + clocks = <&cp0_clk 1 3>, <&cp0_clk 1 9>, + <&cp0_clk 1 5>, <&cp0_clk 1 6>, <&cp0_clk 1 18>; + clock-names = "pp_clk", "gop_clk", "mg_clk", "mg_core_clk", "axi_clk"; + marvell,system-controller = <&cp0_syscon0>; + + ethernet-port@0 { + interrupts = <ICU_GRP_NSR 39 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 43 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 47 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 51 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 55 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 59 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 63 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 67 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 71 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 129 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "hif0", "hif1", "hif2", "hif3", "hif4", + "hif5", "hif6", "hif7", "hif8", "link"; + phy-mode = "10gbase-r"; + phys = <&cp0_comphy4 0>; + reg = <0>; + port-id = <0>; /* For backward compatibility. */ + gop-port-id = <0>; + }; + + ethernet-port@1 { + interrupts = <ICU_GRP_NSR 40 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 44 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 48 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 52 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 56 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 60 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 64 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 68 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 72 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 128 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "hif0", "hif1", "hif2", "hif3", "hif4", + "hif5", "hif6", "hif7", "hif8", "link"; + phy-mode = "rgmii-id"; + reg = <1>; + port-id = <1>; /* For backward compatibility. */ + gop-port-id = <2>; + }; + + ethernet-port@2 { + interrupts = <ICU_GRP_NSR 41 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 45 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 49 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 53 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 57 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 61 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 65 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 69 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 73 IRQ_TYPE_LEVEL_HIGH>, + <ICU_GRP_NSR 127 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "hif0", "hif1", "hif2", "hif3", "hif4", + "hif5", "hif6", "hif7", "hif8", "link"; + phy-mode = "2500base-x"; + managed = "in-band-status"; + phys = <&cp0_comphy5 2>; + sfp = <&sfp_eth3>; + reg = <2>; + port-id = <2>; /* For backward compatibility. */ + gop-port-id = <3>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/marvell,prestera.txt b/Documentation/devicetree/bindings/net/marvell,prestera.txt deleted file mode 100644 index e28938ddfdf5..000000000000 --- a/Documentation/devicetree/bindings/net/marvell,prestera.txt +++ /dev/null @@ -1,81 +0,0 @@ -Marvell Prestera Switch Chip bindings -------------------------------------- - -Required properties: -- compatible: must be "marvell,prestera" and one of the following - "marvell,prestera-98dx3236", - "marvell,prestera-98dx3336", - "marvell,prestera-98dx4251", -- reg: address and length of the register set for the device. -- interrupts: interrupt for the device - -Optional properties: -- dfx: phandle reference to the "DFX Server" node - -Example: - -switch { - compatible = "simple-bus"; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0 MBUS_ID(0x03, 0x00) 0 0x100000>; - - packet-processor@0 { - compatible = "marvell,prestera-98dx3236", "marvell,prestera"; - reg = <0 0x4000000>; - interrupts = <33>, <34>, <35>; - dfx = <&dfx>; - }; -}; - -DFX Server bindings -------------------- - -Required properties: -- compatible: must be "marvell,dfx-server", "simple-bus" -- ranges: describes the address mapping of a memory-mapped bus. -- reg: address and length of the register set for the device. - -Example: - -dfx-server { - compatible = "marvell,dfx-server", "simple-bus"; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0 MBUS_ID(0x08, 0x00) 0 0x100000>; - reg = <MBUS_ID(0x08, 0x00) 0 0x100000>; -}; - -Marvell Prestera SwitchDev bindings ------------------------------------ -Optional properties: -- compatible: must be "marvell,prestera" -- base-mac-provider: describes handle to node which provides base mac address, - might be a static base mac address or nvme cell provider. - -Example: - -eeprom_mac_addr: eeprom-mac-addr { - compatible = "eeprom,mac-addr-cell"; - status = "okay"; - - nvmem = <&eeprom_at24>; -}; - -prestera { - compatible = "marvell,prestera"; - status = "okay"; - - base-mac-provider = <&eeprom_mac_addr>; -}; - -The current implementation of Prestera Switchdev PCI interface driver requires -that BAR2 is assigned to 0xf6000000 as base address from the PCI IO range: - -&cp0_pcie0 { - ranges = <0x81000000 0x0 0xfb000000 0x0 0xfb000000 0x0 0xf0000 - 0x82000000 0x0 0xf6000000 0x0 0xf6000000 0x0 0x2000000 - 0x82000000 0x0 0xf9000000 0x0 0xf9000000 0x0 0x100000>; - phys = <&cp0_comphy0 0>; - status = "okay"; -}; diff --git a/Documentation/devicetree/bindings/net/marvell,prestera.yaml b/Documentation/devicetree/bindings/net/marvell,prestera.yaml new file mode 100644 index 000000000000..5ea8b73663a5 --- /dev/null +++ b/Documentation/devicetree/bindings/net/marvell,prestera.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/marvell,prestera.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell Prestera switch family + +maintainers: + - Miquel Raynal <miquel.raynal@bootlin.com> + +properties: + compatible: + oneOf: + - items: + - enum: + - marvell,prestera-98dx3236 + - marvell,prestera-98dx3336 + - marvell,prestera-98dx4251 + - const: marvell,prestera + - enum: + - pci11ab,c804 + - pci11ab,c80c + - pci11ab,cc1e + + reg: + maxItems: 1 + + interrupts: + maxItems: 3 + + dfx: + description: Reference to the DFX Server bus node. + $ref: /schemas/types.yaml#/definitions/phandle + + nvmem-cells: true + + nvmem-cell-names: true + +if: + properties: + compatible: + contains: + const: marvell,prestera + +# Memory mapped AlleyCat3 family +then: + properties: + nvmem-cells: false + nvmem-cell-names: false + required: + - interrupts + +# PCI Aldrin family +else: + properties: + interrupts: false + dfx: false + +required: + - compatible + - reg + +# Ports can also be described +additionalProperties: + type: object + +examples: + - | + packet-processor@0 { + compatible = "marvell,prestera-98dx3236", "marvell,prestera"; + reg = <0 0x4000000>; + interrupts = <33>, <34>, <35>; + dfx = <&dfx>; + }; + + - | + pcie@0 { + #address-cells = <3>; + #size-cells = <2>; + ranges = <0x0 0x0 0x0 0x0 0x0 0x0>; + reg = <0x0 0x0 0x0 0x0 0x0 0x0>; + device_type = "pci"; + + switch@0,0 { + reg = <0x0 0x0 0x0 0x0 0x0>; + compatible = "pci11ab,c80c"; + nvmem-cells = <&mac_address 0>; + nvmem-cell-names = "mac-address"; + }; + }; diff --git a/Documentation/devicetree/bindings/net/marvell-pp2.txt b/Documentation/devicetree/bindings/net/marvell-pp2.txt deleted file mode 100644 index ce15c173f43f..000000000000 --- a/Documentation/devicetree/bindings/net/marvell-pp2.txt +++ /dev/null @@ -1,141 +0,0 @@ -* Marvell Armada 375 Ethernet Controller (PPv2.1) - Marvell Armada 7K/8K Ethernet Controller (PPv2.2) - Marvell CN913X Ethernet Controller (PPv2.3) - -Required properties: - -- compatible: should be one of: - "marvell,armada-375-pp2" - "marvell,armada-7k-pp2" -- reg: addresses and length of the register sets for the device. - For "marvell,armada-375-pp2", must contain the following register - sets: - - common controller registers - - LMS registers - - one register area per Ethernet port - For "marvell,armada-7k-pp2" used by 7K/8K and CN913X, must contain the following register - sets: - - packet processor registers - - networking interfaces registers - - CM3 address space used for TX Flow Control - -- clocks: pointers to the reference clocks for this device, consequently: - - main controller clock (for both armada-375-pp2 and armada-7k-pp2) - - GOP clock (for both armada-375-pp2 and armada-7k-pp2) - - MG clock (only for armada-7k-pp2) - - MG Core clock (only for armada-7k-pp2) - - AXI clock (only for armada-7k-pp2) -- clock-names: names of used clocks, must be "pp_clk", "gop_clk", "mg_clk", - "mg_core_clk" and "axi_clk" (the 3 latter only for armada-7k-pp2). - -The ethernet ports are represented by subnodes. At least one port is -required. - -Required properties (port): - -- interrupts: interrupt(s) for the port -- port-id: ID of the port from the MAC point of view -- gop-port-id: only for marvell,armada-7k-pp2, ID of the port from the - GOP (Group Of Ports) point of view. This ID is used to index the - per-port registers in the second register area. -- phy-mode: See ethernet.txt file in the same directory - -Optional properties (port): - -- marvell,loopback: port is loopback mode -- phy: a phandle to a phy node defining the PHY address (as the reg - property, a single integer). -- interrupt-names: if more than a single interrupt for is given, must be the - name associated to the interrupts listed. Valid names are: - "hifX", with X in [0..8], and "link". The names "tx-cpu0", - "tx-cpu1", "tx-cpu2", "tx-cpu3" and "rx-shared" are supported - for backward compatibility but shouldn't be used for new - additions. -- marvell,system-controller: a phandle to the system controller. - -Example for marvell,armada-375-pp2: - -ethernet@f0000 { - compatible = "marvell,armada-375-pp2"; - reg = <0xf0000 0xa000>, - <0xc0000 0x3060>, - <0xc4000 0x100>, - <0xc5000 0x100>; - clocks = <&gateclk 3>, <&gateclk 19>; - clock-names = "pp_clk", "gop_clk"; - - eth0: eth0@c4000 { - interrupts = <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>; - port-id = <0>; - phy = <&phy0>; - phy-mode = "gmii"; - }; - - eth1: eth1@c5000 { - interrupts = <GIC_SPI 41 IRQ_TYPE_LEVEL_HIGH>; - port-id = <1>; - phy = <&phy3>; - phy-mode = "gmii"; - }; -}; - -Example for marvell,armada-7k-pp2: - -cpm_ethernet: ethernet@0 { - compatible = "marvell,armada-7k-pp22"; - reg = <0x0 0x100000>, <0x129000 0xb000>, <0x220000 0x800>; - clocks = <&cpm_syscon0 1 3>, <&cpm_syscon0 1 9>, - <&cpm_syscon0 1 5>, <&cpm_syscon0 1 6>, <&cpm_syscon0 1 18>; - clock-names = "pp_clk", "gop_clk", "mg_clk", "mg_core_clk", "axi_clk"; - - eth0: eth0 { - interrupts = <ICU_GRP_NSR 39 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 43 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 47 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 51 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 55 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 59 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 63 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 67 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 71 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 129 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "hif0", "hif1", "hif2", "hif3", "hif4", - "hif5", "hif6", "hif7", "hif8", "link"; - port-id = <0>; - gop-port-id = <0>; - }; - - eth1: eth1 { - interrupts = <ICU_GRP_NSR 40 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 44 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 48 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 52 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 56 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 60 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 64 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 68 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 72 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 128 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "hif0", "hif1", "hif2", "hif3", "hif4", - "hif5", "hif6", "hif7", "hif8", "link"; - port-id = <1>; - gop-port-id = <2>; - }; - - eth2: eth2 { - interrupts = <ICU_GRP_NSR 41 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 45 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 49 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 53 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 57 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 61 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 65 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 69 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 73 IRQ_TYPE_LEVEL_HIGH>, - <ICU_GRP_NSR 127 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "hif0", "hif1", "hif2", "hif3", "hif4", - "hif5", "hif6", "hif7", "hif8", "link"; - port-id = <2>; - gop-port-id = <3>; - }; -}; diff --git a/Documentation/devicetree/bindings/net/micrel,ks8851.yaml b/Documentation/devicetree/bindings/net/micrel,ks8851.yaml index 5aa7cf2eacb1..b44d83554ef5 100644 --- a/Documentation/devicetree/bindings/net/micrel,ks8851.yaml +++ b/Documentation/devicetree/bindings/net/micrel,ks8851.yaml @@ -44,6 +44,7 @@ required: allOf: - $ref: ethernet-controller.yaml# + - $ref: /schemas/memory-controllers/mc-peripheral-props.yaml# - if: properties: compatible: diff --git a/Documentation/devicetree/bindings/net/microchip,lan95xx.yaml b/Documentation/devicetree/bindings/net/microchip,lan95xx.yaml index cf91fecd8909..3715c5f8f0e0 100644 --- a/Documentation/devicetree/bindings/net/microchip,lan95xx.yaml +++ b/Documentation/devicetree/bindings/net/microchip,lan95xx.yaml @@ -39,7 +39,9 @@ properties: - usb424,9e08 # SMSC LAN89530 USB Ethernet Device - usb424,ec00 # SMSC9512/9514 USB Hub & Ethernet Device - reg: true + reg: + maxItems: 1 + local-mac-address: true mac-address: true diff --git a/Documentation/devicetree/bindings/net/nfc/nxp,nci.yaml b/Documentation/devicetree/bindings/net/nfc/nxp,nci.yaml index b2558421268a..6924aff0b2c5 100644 --- a/Documentation/devicetree/bindings/net/nfc/nxp,nci.yaml +++ b/Documentation/devicetree/bindings/net/nfc/nxp,nci.yaml @@ -14,7 +14,9 @@ properties: oneOf: - const: nxp,nxp-nci-i2c - items: - - const: nxp,pn547 + - enum: + - nxp,nq310 + - nxp,pn547 - const: nxp,nxp-nci-i2c enable-gpios: diff --git a/Documentation/devicetree/bindings/net/nxp,dwmac-imx.yaml b/Documentation/devicetree/bindings/net/nxp,dwmac-imx.yaml index 4c155441acbf..04df496af7e6 100644 --- a/Documentation/devicetree/bindings/net/nxp,dwmac-imx.yaml +++ b/Documentation/devicetree/bindings/net/nxp,dwmac-imx.yaml @@ -7,7 +7,9 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: NXP i.MX8 DWMAC glue layer maintainers: - - Joakim Zhang <qiangqing.zhang@nxp.com> + - Clark Wang <xiaoning.wang@nxp.com> + - Shawn Guo <shawnguo@kernel.org> + - NXP Linux Team <linux-imx@nxp.com> # We need a select here so we don't match all nodes with 'snps,dwmac' select: @@ -92,5 +94,4 @@ examples: <&clk IMX8MP_CLK_ENET_QOS>; clock-names = "stmmaceth", "pclk", "ptp_ref", "tx"; phy-mode = "rgmii"; - status = "disabled"; }; diff --git a/Documentation/devicetree/bindings/net/pcs/fsl,lynx-pcs.yaml b/Documentation/devicetree/bindings/net/pcs/fsl,lynx-pcs.yaml new file mode 100644 index 000000000000..fbedf696c555 --- /dev/null +++ b/Documentation/devicetree/bindings/net/pcs/fsl,lynx-pcs.yaml @@ -0,0 +1,40 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/pcs/fsl,lynx-pcs.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP Lynx PCS + +maintainers: + - Ioana Ciornei <ioana.ciornei@nxp.com> + +description: | + NXP Lynx 10G and 28G SerDes have Ethernet PCS devices which can be used as + protocol controllers. They are accessible over the Ethernet interface's MDIO + bus. + +properties: + compatible: + const: fsl,lynx-pcs + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + mdio-bus { + #address-cells = <1>; + #size-cells = <0>; + + qsgmii_pcs1: ethernet-pcs@1 { + compatible = "fsl,lynx-pcs"; + reg = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/qca,ar71xx.yaml b/Documentation/devicetree/bindings/net/qca,ar71xx.yaml index 1ebf9e8c8a1d..89f94b31b546 100644 --- a/Documentation/devicetree/bindings/net/qca,ar71xx.yaml +++ b/Documentation/devicetree/bindings/net/qca,ar71xx.yaml @@ -123,7 +123,6 @@ examples: switch_port0: port@0 { reg = <0x0>; - label = "cpu"; ethernet = <ð1>; phy-mode = "gmii"; diff --git a/Documentation/devicetree/bindings/net/qcom,ipa.yaml b/Documentation/devicetree/bindings/net/qcom,ipa.yaml index dd4bb2e74880..4aeda379726f 100644 --- a/Documentation/devicetree/bindings/net/qcom,ipa.yaml +++ b/Documentation/devicetree/bindings/net/qcom,ipa.yaml @@ -49,6 +49,7 @@ properties: - qcom,sc7280-ipa - qcom,sdm845-ipa - qcom,sdx55-ipa + - qcom,sm6350-ipa - qcom,sm8350-ipa reg: @@ -124,19 +125,31 @@ properties: - const: ipa-clock-enabled-valid - const: ipa-clock-enabled + qcom,gsi-loader: + enum: + - self + - modem + - skip + description: + Indicates how GSI firmware should be loaded. If the AP loads + and validates GSI firmware, this property has value "self". + If the modem does this, this property has value "modem". + Otherwise, "skip" means GSI firmware loading is not required. + modem-init: + deprecated: true type: boolean description: - If present, it indicates that the modem is responsible for - performing early IPA initialization, including loading and - validating firwmare used by the GSI. + This is the older (deprecated) way of indicating how GSI firmware + should be loaded. If present, the modem loads GSI firmware; if + absent, the AP loads GSI firmware. memory-region: maxItems: 1 description: If present, a phandle for a reserved memory area that holds the firmware passed to Trust Zone for authentication. Required - when Trust Zone (not the modem) performs early initialization. + when the AP (not the modem) performs early initialization. firmware-name: $ref: /schemas/types.yaml#/definitions/string @@ -155,22 +168,36 @@ required: - interconnects - qcom,smem-states -# Either modem-init is present, or memory-region must be present. -oneOf: - - required: - - modem-init - - required: - - memory-region - -# If memory-region is present, firmware-name may optionally be present. -# But if modem-init is present, firmware-name must not be present. -if: - required: - - modem-init -then: - not: - required: - - firmware-name +allOf: + # If qcom,gsi-loader is present, modem-init must not be present + - if: + required: + - qcom,gsi-loader + then: + properties: + modem-init: false + + # If qcom,gsi-loader is "self", the AP loads GSI firmware, and + # memory-region must be specified + if: + properties: + qcom,gsi-loader: + contains: + const: self + then: + required: + - memory-region + else: + # If qcom,gsi-loader is not present, we use deprecated behavior. + # If modem-init is not present, the AP loads GSI firmware, and + # memory-region must be specified. + if: + not: + required: + - modem-init + then: + required: + - memory-region additionalProperties: false @@ -201,14 +228,17 @@ examples: }; ipa@1e40000 { - compatible = "qcom,sdm845-ipa"; + compatible = "qcom,sc7180-ipa"; - modem-init; + qcom,gsi-loader = "self"; + memory-region = <&ipa_fw_mem>; + firmware-name = "qcom/sc7180-trogdor/modem/modem.mdt"; - iommus = <&apps_smmu 0x720 0x3>; + iommus = <&apps_smmu 0x440 0x0>, + <&apps_smmu 0x442 0x0>; reg = <0x1e40000 0x7000>, - <0x1e47000 0x2000>, - <0x1e04000 0x2c000>; + <0x1e47000 0x2000>, + <0x1e04000 0x2c000>; reg-names = "ipa-reg", "ipa-shared", "gsi"; @@ -226,9 +256,9 @@ examples: clock-names = "core"; interconnects = - <&rsc_hlos MASTER_IPA &rsc_hlos SLAVE_EBI1>, - <&rsc_hlos MASTER_IPA &rsc_hlos SLAVE_IMEM>, - <&rsc_hlos MASTER_APPSS_PROC &rsc_hlos SLAVE_IPA_CFG>; + <&aggre2_noc MASTER_IPA 0 &mc_virt SLAVE_EBI1 0>, + <&aggre2_noc MASTER_IPA 0 &system_noc SLAVE_IMEM 0>, + <&gem_noc MASTER_APPSS_PROC 0 &config_noc SLAVE_IPA_CFG 0>; interconnect-names = "memory", "imem", "config"; diff --git a/Documentation/devicetree/bindings/net/qcom,ipq4019-mdio.yaml b/Documentation/devicetree/bindings/net/qcom,ipq4019-mdio.yaml index ad8b2b41c140..7631ecc8fd01 100644 --- a/Documentation/devicetree/bindings/net/qcom,ipq4019-mdio.yaml +++ b/Documentation/devicetree/bindings/net/qcom,ipq4019-mdio.yaml @@ -9,14 +9,18 @@ title: Qualcomm IPQ40xx MDIO Controller maintainers: - Robert Marko <robert.marko@sartura.hr> -allOf: - - $ref: "mdio.yaml#" - properties: compatible: - enum: - - qcom,ipq4019-mdio - - qcom,ipq5018-mdio + oneOf: + - enum: + - qcom,ipq4019-mdio + - qcom,ipq5018-mdio + + - items: + - enum: + - qcom,ipq6018-mdio + - qcom,ipq8074-mdio + - const: qcom,ipq4019-mdio "#address-cells": const: 1 @@ -33,10 +37,12 @@ properties: address range is only required by the platform IPQ50xx. clocks: - maxItems: 1 - description: | - MDIO clock source frequency fixed to 100MHZ, this clock should be specified - by the platform IPQ807x, IPQ60xx and IPQ50xx. + items: + - description: MDIO clock source frequency fixed to 100MHZ + + clock-names: + items: + - const: gcc_mdio_ahb_clk required: - compatible @@ -44,6 +50,26 @@ required: - "#address-cells" - "#size-cells" +allOf: + - $ref: "mdio.yaml#" + + - if: + properties: + compatible: + contains: + enum: + - qcom,ipq5018-mdio + - qcom,ipq6018-mdio + - qcom,ipq8074-mdio + then: + required: + - clocks + - clock-names + else: + properties: + clocks: false + clock-names: false + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/net/realtek-bluetooth.yaml b/Documentation/devicetree/bindings/net/realtek-bluetooth.yaml index e329ef06e10f..143b5667abad 100644 --- a/Documentation/devicetree/bindings/net/realtek-bluetooth.yaml +++ b/Documentation/devicetree/bindings/net/realtek-bluetooth.yaml @@ -20,6 +20,7 @@ properties: enum: - realtek,rtl8723bs-bt - realtek,rtl8723cs-bt + - realtek,rtl8723ds-bt - realtek,rtl8822cs-bt device-wake-gpios: diff --git a/Documentation/devicetree/bindings/net/renesas,r8a779f0-ether-switch.yaml b/Documentation/devicetree/bindings/net/renesas,r8a779f0-ether-switch.yaml new file mode 100644 index 000000000000..e933a1e48d67 --- /dev/null +++ b/Documentation/devicetree/bindings/net/renesas,r8a779f0-ether-switch.yaml @@ -0,0 +1,262 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/renesas,r8a779f0-ether-switch.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas Ethernet Switch + +maintainers: + - Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com> + +properties: + compatible: + const: renesas,r8a779f0-ether-switch + + reg: + maxItems: 2 + + reg-names: + items: + - const: base + - const: secure_base + + interrupts: + maxItems: 47 + + interrupt-names: + items: + - const: mfwd_error + - const: race_error + - const: coma_error + - const: gwca0_error + - const: gwca1_error + - const: etha0_error + - const: etha1_error + - const: etha2_error + - const: gptp0_status + - const: gptp1_status + - const: mfwd_status + - const: race_status + - const: coma_status + - const: gwca0_status + - const: gwca1_status + - const: etha0_status + - const: etha1_status + - const: etha2_status + - const: rmac0_status + - const: rmac1_status + - const: rmac2_status + - const: gwca0_rxtx0 + - const: gwca0_rxtx1 + - const: gwca0_rxtx2 + - const: gwca0_rxtx3 + - const: gwca0_rxtx4 + - const: gwca0_rxtx5 + - const: gwca0_rxtx6 + - const: gwca0_rxtx7 + - const: gwca1_rxtx0 + - const: gwca1_rxtx1 + - const: gwca1_rxtx2 + - const: gwca1_rxtx3 + - const: gwca1_rxtx4 + - const: gwca1_rxtx5 + - const: gwca1_rxtx6 + - const: gwca1_rxtx7 + - const: gwca0_rxts0 + - const: gwca0_rxts1 + - const: gwca1_rxts0 + - const: gwca1_rxts1 + - const: rmac0_mdio + - const: rmac1_mdio + - const: rmac2_mdio + - const: rmac0_phy + - const: rmac1_phy + - const: rmac2_phy + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + + iommus: + maxItems: 16 + + power-domains: + maxItems: 1 + + ethernet-ports: + type: object + additionalProperties: false + + properties: + '#address-cells': + description: Port number of ETHA (TSNA). + const: 1 + + '#size-cells': + const: 0 + + patternProperties: + "^port@[0-9a-f]+$": + type: object + $ref: /schemas/net/ethernet-controller.yaml# + unevaluatedProperties: false + + properties: + reg: + maxItems: 1 + description: + Port number of ETHA (TSNA). + + phys: + maxItems: 1 + description: + Phandle of an Ethernet SERDES. + + mdio: + $ref: /schemas/net/mdio.yaml# + unevaluatedProperties: false + + required: + - reg + - phy-handle + - phy-mode + - phys + - mdio + +required: + - compatible + - reg + - reg-names + - interrupts + - interrupt-names + - clocks + - resets + - power-domains + - ethernet-ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a779f0-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a779f0-sysc.h> + + ethernet@e6880000 { + compatible = "renesas,r8a779f0-ether-switch"; + reg = <0xe6880000 0x20000>, <0xe68c0000 0x20000>; + reg-names = "base", "secure_base"; + interrupts = <GIC_SPI 256 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 257 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 258 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 259 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 260 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 261 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 262 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 263 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 265 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 266 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 267 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 268 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 269 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 270 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 271 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 272 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 273 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 274 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 276 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 277 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 278 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 280 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 281 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 282 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 283 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 284 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 285 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 286 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 287 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 288 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 289 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 290 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 291 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 292 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 293 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 294 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 295 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 296 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 297 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 298 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 299 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 300 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 301 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 302 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 304 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 305 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 306 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "mfwd_error", "race_error", + "coma_error", "gwca0_error", + "gwca1_error", "etha0_error", + "etha1_error", "etha2_error", + "gptp0_status", "gptp1_status", + "mfwd_status", "race_status", + "coma_status", "gwca0_status", + "gwca1_status", "etha0_status", + "etha1_status", "etha2_status", + "rmac0_status", "rmac1_status", + "rmac2_status", + "gwca0_rxtx0", "gwca0_rxtx1", + "gwca0_rxtx2", "gwca0_rxtx3", + "gwca0_rxtx4", "gwca0_rxtx5", + "gwca0_rxtx6", "gwca0_rxtx7", + "gwca1_rxtx0", "gwca1_rxtx1", + "gwca1_rxtx2", "gwca1_rxtx3", + "gwca1_rxtx4", "gwca1_rxtx5", + "gwca1_rxtx6", "gwca1_rxtx7", + "gwca0_rxts0", "gwca0_rxts1", + "gwca1_rxts0", "gwca1_rxts1", + "rmac0_mdio", "rmac1_mdio", + "rmac2_mdio", + "rmac0_phy", "rmac1_phy", + "rmac2_phy"; + clocks = <&cpg CPG_MOD 1505>; + power-domains = <&sysc R8A779F0_PD_ALWAYS_ON>; + resets = <&cpg 1505>; + + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + port@0 { + reg = <0>; + phy-handle = <ð_phy0>; + phy-mode = "sgmii"; + phys = <ð_serdes 0>; + mdio { + #address-cells = <1>; + #size-cells = <0>; + }; + }; + port@1 { + reg = <1>; + phy-handle = <ð_phy1>; + phy-mode = "sgmii"; + phys = <ð_serdes 1>; + mdio { + #address-cells = <1>; + #size-cells = <0>; + }; + }; + port@2 { + reg = <2>; + phy-handle = <ð_phy2>; + phy-mode = "sgmii"; + phys = <ð_serdes 2>; + mdio { + #address-cells = <1>; + #size-cells = <0>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/sff,sfp.yaml b/Documentation/devicetree/bindings/net/sff,sfp.yaml index 06c66ab81c01..231c4d75e4b1 100644 --- a/Documentation/devicetree/bindings/net/sff,sfp.yaml +++ b/Documentation/devicetree/bindings/net/sff,sfp.yaml @@ -22,7 +22,8 @@ properties: phandle of an I2C bus controller for the SFP two wire serial maximum-power-milliwatt: - maxItems: 1 + minimum: 1000 + default: 1000 description: Maximum module power consumption Specifies the maximum power consumption allowable by a module in the slot, in milli-Watts. Presently, modules can diff --git a/Documentation/devicetree/bindings/net/snps,dwmac.yaml b/Documentation/devicetree/bindings/net/snps,dwmac.yaml index 13b984076af5..e88a86623fce 100644 --- a/Documentation/devicetree/bindings/net/snps,dwmac.yaml +++ b/Documentation/devicetree/bindings/net/snps,dwmac.yaml @@ -167,56 +167,238 @@ properties: snps,mtl-rx-config: $ref: /schemas/types.yaml#/definitions/phandle description: - Multiple RX Queues parameters. Phandle to a node that can - contain the following properties - * snps,rx-queues-to-use, number of RX queues to be used in the - driver - * Choose one of these RX scheduling algorithms - * snps,rx-sched-sp, Strict priority - * snps,rx-sched-wsp, Weighted Strict priority - * For each RX queue - * Choose one of these modes - * snps,dcb-algorithm, Queue to be enabled as DCB - * snps,avb-algorithm, Queue to be enabled as AVB - * snps,map-to-dma-channel, Channel to map - * Specifiy specific packet routing - * snps,route-avcp, AV Untagged Control packets - * snps,route-ptp, PTP Packets - * snps,route-dcbcp, DCB Control Packets - * snps,route-up, Untagged Packets - * snps,route-multi-broad, Multicast & Broadcast Packets - * snps,priority, bitmask of the tagged frames priorities assigned to - the queue + Multiple RX Queues parameters. Phandle to a node that + implements the 'rx-queues-config' object described in + this binding. + + rx-queues-config: + type: object + properties: + snps,rx-queues-to-use: + $ref: /schemas/types.yaml#/definitions/uint32 + description: number of RX queues to be used in the driver + snps,rx-sched-sp: + type: boolean + description: Strict priority + snps,rx-sched-wsp: + type: boolean + description: Weighted Strict priority + allOf: + - if: + required: + - snps,rx-sched-sp + then: + properties: + snps,rx-sched-wsp: false + - if: + required: + - snps,rx-sched-wsp + then: + properties: + snps,rx-sched-sp: false + patternProperties: + "^queue[0-9]$": + description: Each subnode represents a queue. + type: object + properties: + snps,dcb-algorithm: + type: boolean + description: Queue to be enabled as DCB + snps,avb-algorithm: + type: boolean + description: Queue to be enabled as AVB + snps,map-to-dma-channel: + $ref: /schemas/types.yaml#/definitions/uint32 + description: DMA channel id to map + snps,route-avcp: + type: boolean + description: AV Untagged Control packets + snps,route-ptp: + type: boolean + description: PTP Packets + snps,route-dcbcp: + type: boolean + description: DCB Control Packets + snps,route-up: + type: boolean + description: Untagged Packets + snps,route-multi-broad: + type: boolean + description: Multicast & Broadcast Packets + snps,priority: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Bitmask of the tagged frames priorities assigned to the queue + allOf: + - if: + required: + - snps,dcb-algorithm + then: + properties: + snps,avb-algorithm: false + - if: + required: + - snps,avb-algorithm + then: + properties: + snps,dcb-algorithm: false + - if: + required: + - snps,route-avcp + then: + properties: + snps,route-ptp: false + snps,route-dcbcp: false + snps,route-up: false + snps,route-multi-broad: false + - if: + required: + - snps,route-ptp + then: + properties: + snps,route-avcp: false + snps,route-dcbcp: false + snps,route-up: false + snps,route-multi-broad: false + - if: + required: + - snps,route-dcbcp + then: + properties: + snps,route-avcp: false + snps,route-ptp: false + snps,route-up: false + snps,route-multi-broad: false + - if: + required: + - snps,route-up + then: + properties: + snps,route-avcp: false + snps,route-ptp: false + snps,route-dcbcp: false + snps,route-multi-broad: false + - if: + required: + - snps,route-multi-broad + then: + properties: + snps,route-avcp: false + snps,route-ptp: false + snps,route-dcbcp: false + snps,route-up: false + additionalProperties: false + additionalProperties: false snps,mtl-tx-config: $ref: /schemas/types.yaml#/definitions/phandle description: - Multiple TX Queues parameters. Phandle to a node that can - contain the following properties - * snps,tx-queues-to-use, number of TX queues to be used in the - driver - * Choose one of these TX scheduling algorithms - * snps,tx-sched-wrr, Weighted Round Robin - * snps,tx-sched-wfq, Weighted Fair Queuing - * snps,tx-sched-dwrr, Deficit Weighted Round Robin - * snps,tx-sched-sp, Strict priority - * For each TX queue - * snps,weight, TX queue weight (if using a DCB weight - algorithm) - * Choose one of these modes - * snps,dcb-algorithm, TX queue will be working in DCB - * snps,avb-algorithm, TX queue will be working in AVB - [Attention] Queue 0 is reserved for legacy traffic - and so no AVB is available in this queue. - * Configure Credit Base Shaper (if AVB Mode selected) - * snps,send_slope, enable Low Power Interface - * snps,idle_slope, unlock on WoL - * snps,high_credit, max write outstanding req. limit - * snps,low_credit, max read outstanding req. limit - * snps,priority, bitmask of the priorities assigned to the queue. - When a PFC frame is received with priorities matching the bitmask, - the queue is blocked from transmitting for the pause time specified - in the PFC frame. + Multiple TX Queues parameters. Phandle to a node that + implements the 'tx-queues-config' object described in + this binding. + + tx-queues-config: + type: object + properties: + snps,tx-queues-to-use: + $ref: /schemas/types.yaml#/definitions/uint32 + description: number of TX queues to be used in the driver + snps,tx-sched-wrr: + type: boolean + description: Weighted Round Robin + snps,tx-sched-wfq: + type: boolean + description: Weighted Fair Queuing + snps,tx-sched-dwrr: + type: boolean + description: Deficit Weighted Round Robin + snps,tx-sched-sp: + type: boolean + description: Strict priority + allOf: + - if: + required: + - snps,tx-sched-wrr + then: + properties: + snps,tx-sched-wfq: false + snps,tx-sched-dwrr: false + snps,tx-sched-sp: false + - if: + required: + - snps,tx-sched-wfq + then: + properties: + snps,tx-sched-wrr: false + snps,tx-sched-dwrr: false + snps,tx-sched-sp: false + - if: + required: + - snps,tx-sched-dwrr + then: + properties: + snps,tx-sched-wrr: false + snps,tx-sched-wfq: false + snps,tx-sched-sp: false + - if: + required: + - snps,tx-sched-sp + then: + properties: + snps,tx-sched-wrr: false + snps,tx-sched-wfq: false + snps,tx-sched-dwrr: false + patternProperties: + "^queue[0-9]$": + description: Each subnode represents a queue. + type: object + properties: + snps,weight: + $ref: /schemas/types.yaml#/definitions/uint32 + description: TX queue weight (if using a DCB weight algorithm) + snps,dcb-algorithm: + type: boolean + description: TX queue will be working in DCB + snps,avb-algorithm: + type: boolean + description: + TX queue will be working in AVB. + Queue 0 is reserved for legacy traffic and so no AVB is + available in this queue. + snps,send_slope: + $ref: /schemas/types.yaml#/definitions/uint32 + description: enable Low Power Interface + snps,idle_slope: + $ref: /schemas/types.yaml#/definitions/uint32 + description: unlock on WoL + snps,high_credit: + $ref: /schemas/types.yaml#/definitions/uint32 + description: max write outstanding req. limit + snps,low_credit: + $ref: /schemas/types.yaml#/definitions/uint32 + description: max read outstanding req. limit + snps,priority: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Bitmask of the tagged frames priorities assigned to the queue. + When a PFC frame is received with priorities matching the bitmask, + the queue is blocked from transmitting for the pause time specified + in the PFC frame. + allOf: + - if: + required: + - snps,dcb-algorithm + then: + properties: + snps,avb-algorithm: false + - if: + required: + - snps,avb-algorithm + then: + properties: + snps,dcb-algorithm: false + snps,weight: false + additionalProperties: false + additionalProperties: false snps,reset-gpio: deprecated: true @@ -463,41 +645,6 @@ additionalProperties: true examples: - | - stmmac_axi_setup: stmmac-axi-config { - snps,wr_osr_lmt = <0xf>; - snps,rd_osr_lmt = <0xf>; - snps,blen = <256 128 64 32 0 0 0>; - }; - - mtl_rx_setup: rx-queues-config { - snps,rx-queues-to-use = <1>; - snps,rx-sched-sp; - queue0 { - snps,dcb-algorithm; - snps,map-to-dma-channel = <0x0>; - snps,priority = <0x0>; - }; - }; - - mtl_tx_setup: tx-queues-config { - snps,tx-queues-to-use = <2>; - snps,tx-sched-wrr; - queue0 { - snps,weight = <0x10>; - snps,dcb-algorithm; - snps,priority = <0x0>; - }; - - queue1 { - snps,avb-algorithm; - snps,send_slope = <0x1000>; - snps,idle_slope = <0x1000>; - snps,high_credit = <0x3E800>; - snps,low_credit = <0xFFC18000>; - snps,priority = <0x1>; - }; - }; - gmac0: ethernet@e0800000 { compatible = "snps,dwxgmac-2.10", "snps,dwxgmac"; reg = <0xe0800000 0x8000>; @@ -516,6 +663,42 @@ examples: snps,axi-config = <&stmmac_axi_setup>; snps,mtl-rx-config = <&mtl_rx_setup>; snps,mtl-tx-config = <&mtl_tx_setup>; + + stmmac_axi_setup: stmmac-axi-config { + snps,wr_osr_lmt = <0xf>; + snps,rd_osr_lmt = <0xf>; + snps,blen = <256 128 64 32 0 0 0>; + }; + + mtl_rx_setup: rx-queues-config { + snps,rx-queues-to-use = <1>; + snps,rx-sched-sp; + queue0 { + snps,dcb-algorithm; + snps,map-to-dma-channel = <0x0>; + snps,priority = <0x0>; + }; + }; + + mtl_tx_setup: tx-queues-config { + snps,tx-queues-to-use = <2>; + snps,tx-sched-wrr; + queue0 { + snps,weight = <0x10>; + snps,dcb-algorithm; + snps,priority = <0x0>; + }; + + queue1 { + snps,avb-algorithm; + snps,send_slope = <0x1000>; + snps,idle_slope = <0x1000>; + snps,high_credit = <0x3E800>; + snps,low_credit = <0xFFC18000>; + snps,priority = <0x1>; + }; + }; + mdio0 { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/net/socionext,synquacer-netsec.yaml b/Documentation/devicetree/bindings/net/socionext,synquacer-netsec.yaml new file mode 100644 index 000000000000..a65e6aa215a7 --- /dev/null +++ b/Documentation/devicetree/bindings/net/socionext,synquacer-netsec.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/socionext,synquacer-netsec.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext NetSec Ethernet Controller IP + +maintainers: + - Jassi Brar <jaswinder.singh@linaro.org> + - Ilias Apalodimas <ilias.apalodimas@linaro.org> + +allOf: + - $ref: ethernet-controller.yaml# + +properties: + compatible: + const: socionext,synquacer-netsec + + reg: + items: + - description: control register area + - description: EEPROM holding the MAC address and microengine firmware + + clocks: + maxItems: 1 + + clock-names: + const: phy_ref_clk + + dma-coherent: true + + interrupts: + maxItems: 1 + + mdio: + $ref: mdio.yaml# + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + - mdio + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + ethernet@522d0000 { + compatible = "socionext,synquacer-netsec"; + reg = <0x522d0000 0x10000>, <0x10000000 0x10000>; + interrupts = <GIC_SPI 176 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk_netsec>; + clock-names = "phy_ref_clk"; + phy-mode = "rgmii"; + max-speed = <1000>; + max-frame-size = <9000>; + phy-handle = <&phy1>; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + phy1: ethernet-phy@1 { + compatible = "ethernet-phy-ieee802.3-c22"; + reg = <1>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/net/socionext-netsec.txt b/Documentation/devicetree/bindings/net/socionext-netsec.txt deleted file mode 100644 index a3c1dffaa4bb..000000000000 --- a/Documentation/devicetree/bindings/net/socionext-netsec.txt +++ /dev/null @@ -1,56 +0,0 @@ -* Socionext NetSec Ethernet Controller IP - -Required properties: -- compatible: Should be "socionext,synquacer-netsec" -- reg: Address and length of the control register area, followed by the - address and length of the EEPROM holding the MAC address and - microengine firmware -- interrupts: Should contain ethernet controller interrupt -- clocks: phandle to the PHY reference clock -- clock-names: Should be "phy_ref_clk" -- phy-mode: See ethernet.txt file in the same directory -- phy-handle: See ethernet.txt in the same directory. - -- mdio device tree subnode: When the Netsec has a phy connected to its local - mdio, there must be device tree subnode with the following - required properties: - - - #address-cells: Must be <1>. - - #size-cells: Must be <0>. - - For each phy on the mdio bus, there must be a node with the following - fields: - - compatible: Refer to phy.txt - - reg: phy id used to communicate to phy. - -Optional properties: (See ethernet.txt file in the same directory) -- dma-coherent: Boolean property, must only be present if memory - accesses performed by the device are cache coherent. -- max-speed: See ethernet.txt in the same directory. -- max-frame-size: See ethernet.txt in the same directory. - -The MAC address will be determined using the optional properties -defined in ethernet.txt. The 'phy-mode' property is required, but may -be set to the empty string if the PHY configuration is programmed by -the firmware or set by hardware straps, and needs to be preserved. - -Example: - eth0: ethernet@522d0000 { - compatible = "socionext,synquacer-netsec"; - reg = <0 0x522d0000 0x0 0x10000>, <0 0x10000000 0x0 0x10000>; - interrupts = <GIC_SPI 176 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clk_netsec>; - clock-names = "phy_ref_clk"; - phy-mode = "rgmii"; - max-speed = <1000>; - max-frame-size = <9000>; - phy-handle = <&phy1>; - - mdio { - #address-cells = <1>; - #size-cells = <0>; - phy1: ethernet-phy@1 { - compatible = "ethernet-phy-ieee802.3-c22"; - reg = <1>; - }; - }; diff --git a/Documentation/devicetree/bindings/net/xilinx_axienet.txt b/Documentation/devicetree/bindings/net/xilinx_axienet.txt index 1aa4c6006cd0..80e505a2fda1 100644 --- a/Documentation/devicetree/bindings/net/xilinx_axienet.txt +++ b/Documentation/devicetree/bindings/net/xilinx_axienet.txt @@ -68,6 +68,8 @@ Optional properties: - mdio : Child node for MDIO bus. Must be defined if PHY access is required through the core's MDIO interface (i.e. always, unless the PHY is accessed through a different bus). + Non-standard MDIO bus frequency is supported via + "clock-frequency", see mdio.yaml. - pcs-handle: Phandle to the internal PCS/PMA PHY in SGMII or 1000Base-X modes, where "pcs-handle" should be used to point diff --git a/Documentation/devicetree/bindings/nvmem/snvs-lpgpr.yaml b/Documentation/devicetree/bindings/nvmem/snvs-lpgpr.yaml index e374aa7891ae..ec20e33d9b8f 100644 --- a/Documentation/devicetree/bindings/nvmem/snvs-lpgpr.yaml +++ b/Documentation/devicetree/bindings/nvmem/snvs-lpgpr.yaml @@ -11,14 +11,18 @@ maintainers: properties: compatible: - enum: - - fsl,imx6q-snvs-lpgpr - - fsl,imx6ul-snvs-lpgpr - - fsl,imx7d-snvs-lpgpr - - fsl,imx8mm-snvs-lpgpr - - fsl,imx8mn-snvs-lpgpr - - fsl,imx8mp-snvs-lpgpr - - fsl,imx8mq-snvs-lpgpr + oneOf: + - items: + - enum: + - fsl,imx8mm-snvs-lpgpr + - fsl,imx8mn-snvs-lpgpr + - fsl,imx8mp-snvs-lpgpr + - fsl,imx8mq-snvs-lpgpr + - const: fsl,imx7d-snvs-lpgpr + - enum: + - fsl,imx6q-snvs-lpgpr + - fsl,imx6ul-snvs-lpgpr + - fsl,imx7d-snvs-lpgpr required: - compatible diff --git a/Documentation/devicetree/bindings/nvmem/u-boot,env.yaml b/Documentation/devicetree/bindings/nvmem/u-boot,env.yaml index e96bca99f2d9..cbc5c69fd405 100644 --- a/Documentation/devicetree/bindings/nvmem/u-boot,env.yaml +++ b/Documentation/devicetree/bindings/nvmem/u-boot,env.yaml @@ -38,6 +38,8 @@ properties: const: u-boot,env-redundant-bool - description: Two redundant blocks with active having higher counter const: u-boot,env-redundant-count + - description: Broadcom's variant with custom header + const: brcm,env reg: maxItems: 1 @@ -73,3 +75,22 @@ examples: }; }; }; + - | + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + partition@0 { + reg = <0x0 0x100000>; + compatible = "brcm,u-boot"; + label = "u-boot"; + + partition-u-boot-env { + compatible = "brcm,env"; + + ethaddr { + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/opp/allwinner,sun50i-h6-operating-points.yaml b/Documentation/devicetree/bindings/opp/allwinner,sun50i-h6-operating-points.yaml index 385b0692261c..51f62c3ae194 100644 --- a/Documentation/devicetree/bindings/opp/allwinner,sun50i-h6-operating-points.yaml +++ b/Documentation/devicetree/bindings/opp/allwinner,sun50i-h6-operating-points.yaml @@ -41,7 +41,7 @@ required: - nvmem-cells patternProperties: - "opp-[0-9]+": + "^opp-[0-9]+$": type: object properties: @@ -49,7 +49,7 @@ patternProperties: clock-latency-ns: true patternProperties: - "opp-microvolt-.*": true + "^opp-microvolt-speed[0-9]$": true required: - opp-hz diff --git a/Documentation/devicetree/bindings/opp/opp-v2-base.yaml b/Documentation/devicetree/bindings/opp/opp-v2-base.yaml index 66d0ec763f0b..cf9c2f7bddc2 100644 --- a/Documentation/devicetree/bindings/opp/opp-v2-base.yaml +++ b/Documentation/devicetree/bindings/opp/opp-v2-base.yaml @@ -108,7 +108,7 @@ patternProperties: The power for the OPP in micro-Watts. Entries for multiple regulators shall be provided in the same field - separated by angular brackets <>. If current values aren't required + separated by angular brackets <>. If power values aren't required for a regulator, then it shall be filled with 0. If power values aren't required for any of the regulators, then this field is not required. The OPP binding doesn't provide any provisions to relate the @@ -230,9 +230,9 @@ patternProperties: minItems: 1 maxItems: 8 # Should be enough regulators - '^opp-microwatt': + '^opp-microwatt-': description: - Named opp-microwatt property. Similar to opp-microamp property, + Named opp-microwatt property. Similar to opp-microamp-<name> property, but for microwatt instead. $ref: /schemas/types.yaml#/definitions/uint32-array minItems: 1 diff --git a/Documentation/devicetree/bindings/opp/opp-v2.yaml b/Documentation/devicetree/bindings/opp/opp-v2.yaml index eaf8fba2c691..2f05920fce79 100644 --- a/Documentation/devicetree/bindings/opp/opp-v2.yaml +++ b/Documentation/devicetree/bindings/opp/opp-v2.yaml @@ -155,7 +155,7 @@ examples: opp-hz = /bits/ 64 <1200000000>; opp-microvolt = <1025000>; opp-microamp = <90000>; - lock-latency-ns = <290000>; + clock-latency-ns = <290000>; turbo-mode; }; }; diff --git a/Documentation/devicetree/bindings/pci/baikal,bt1-pcie.yaml b/Documentation/devicetree/bindings/pci/baikal,bt1-pcie.yaml new file mode 100644 index 000000000000..8eaa07ae9774 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/baikal,bt1-pcie.yaml @@ -0,0 +1,168 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/baikal,bt1-pcie.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Baikal-T1 PCIe Root Port Controller + +maintainers: + - Serge Semin <fancer.lancer@gmail.com> + +description: + Embedded into Baikal-T1 SoC Root Complex controller with a single port + activated. It's based on the DWC RC PCIe v4.60a IP-core, which is configured + to have just a single Root Port function and is capable of establishing the + link up to Gen.3 speed on x4 lanes. It doesn't have embedded clock and reset + control module, so the proper interface initialization is supposed to be + performed by software. There four in- and four outbound iATU regions + which can be used to emit all required TLP types on the PCIe bus. + +allOf: + - $ref: /schemas/pci/snps,dw-pcie.yaml# + +properties: + compatible: + const: baikal,bt1-pcie + + reg: + description: + DBI, DBI2 and at least 4KB outbound iATU-capable region for the + peripheral devices CFG-space access. + maxItems: 3 + + reg-names: + items: + - const: dbi + - const: dbi2 + - const: config + + interrupts: + description: + MSI, AER, PME, Hot-plug, Link Bandwidth Management, Link Equalization + request and eight Read/Write eDMA IRQ lines are available. + maxItems: 14 + + interrupt-names: + items: + - const: dma0 + - const: dma1 + - const: dma2 + - const: dma3 + - const: dma4 + - const: dma5 + - const: dma6 + - const: dma7 + - const: msi + - const: aer + - const: pme + - const: hp + - const: bw_mg + - const: l_eq + + clocks: + description: + DBI (attached to the APB bus), AXI-bus master and slave interfaces + are fed up by the dedicated application clocks. A common reference + clock signal is supposed to be attached to the corresponding Ref-pad + of the SoC. It will be redistributed amongst the controller core + sub-modules (pipe, core, aux, etc). + maxItems: 4 + + clock-names: + items: + - const: dbi + - const: mstr + - const: slv + - const: ref + + resets: + description: + A comprehensive controller reset logic is supposed to be implemented + by software, so almost all the possible application and core reset + signals are exposed via the system CCU module. + maxItems: 9 + + reset-names: + items: + - const: mstr + - const: slv + - const: pwr + - const: hot + - const: phy + - const: core + - const: pipe + - const: sticky + - const: non-sticky + + baikal,bt1-syscon: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to the Baikal-T1 System Controller DT node. It's required to + access some additional PM, Reset-related and LTSSM signals. + + num-lanes: + maximum: 4 + + max-link-speed: + maximum: 3 + +required: + - compatible + - reg + - reg-names + - interrupts + - interrupt-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/mips-gic.h> + #include <dt-bindings/gpio/gpio.h> + + pcie@1f052000 { + compatible = "baikal,bt1-pcie"; + device_type = "pci"; + reg = <0x1f052000 0x1000>, <0x1f053000 0x1000>, <0x1bdbf000 0x1000>; + reg-names = "dbi", "dbi2", "config"; + #address-cells = <3>; + #size-cells = <2>; + ranges = <0x81000000 0 0x00000000 0x1bdb0000 0 0x00008000>, + <0x82000000 0 0x20000000 0x08000000 0 0x13db0000>; + bus-range = <0x0 0xff>; + + interrupts = <GIC_SHARED 80 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SHARED 81 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SHARED 82 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SHARED 83 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SHARED 84 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SHARED 85 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SHARED 86 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SHARED 87 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SHARED 88 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SHARED 89 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SHARED 90 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SHARED 91 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SHARED 92 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SHARED 93 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "dma0", "dma1", "dma2", "dma3", + "dma4", "dma5", "dma6", "dma7", + "msi", "aer", "pme", "hp", "bw_mg", + "l_eq"; + + clocks = <&ccu_sys 1>, <&ccu_axi 6>, <&ccu_axi 7>, <&clk_pcie>; + clock-names = "dbi", "mstr", "slv", "ref"; + + resets = <&ccu_axi 6>, <&ccu_axi 7>, <&ccu_sys 7>, <&ccu_sys 10>, + <&ccu_sys 4>, <&ccu_sys 6>, <&ccu_sys 5>, <&ccu_sys 8>, + <&ccu_sys 9>; + reset-names = "mstr", "slv", "pwr", "hot", "phy", "core", "pipe", + "sticky", "non-sticky"; + + reset-gpios = <&port0 0 GPIO_ACTIVE_LOW>; + + num-lanes = <4>; + max-link-speed = <3>; + }; +... diff --git a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.yaml b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.yaml index 376e739bcad4..49b4f7a32e71 100644 --- a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.yaml @@ -14,9 +14,6 @@ description: |+ This PCIe host controller is based on the Synopsys DesignWare PCIe IP and thus inherits all the common properties defined in snps,dw-pcie.yaml. -allOf: - - $ref: /schemas/pci/snps,dw-pcie.yaml# - properties: compatible: enum: @@ -61,7 +58,7 @@ properties: - const: pcie - const: pcie_bus - const: pcie_phy - - const: pcie_inbound_axi for imx6sx-pcie, pcie_aux for imx8mq-pcie + - enum: [ pcie_inbound_axi, pcie_aux ] num-lanes: const: 1 @@ -175,6 +172,47 @@ required: - clocks - clock-names +allOf: + - $ref: /schemas/pci/snps,dw-pcie.yaml# + - if: + properties: + compatible: + contains: + const: fsl,imx6sx-pcie + then: + properties: + clock-names: + items: + - {} + - {} + - {} + - const: pcie_inbound_axi + - if: + properties: + compatible: + contains: + const: fsl,imx8mq-pcie + then: + properties: + clock-names: + items: + - {} + - {} + - {} + - const: pcie_aux + - if: + properties: + compatible: + not: + contains: + enum: + - fsl,imx6sx-pcie + - fsl,imx8mq-pcie + then: + properties: + clock-names: + maxItems: 3 + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/pci/mediatek,mt7621-pcie.yaml b/Documentation/devicetree/bindings/pci/mediatek,mt7621-pcie.yaml index d60f43fd9c5a..e63e6458cea8 100644 --- a/Documentation/devicetree/bindings/pci/mediatek,mt7621-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/mediatek,mt7621-pcie.yaml @@ -31,7 +31,7 @@ properties: maxItems: 2 patternProperties: - 'pcie@[0-2],0': + '^pcie@[0-2],0$': type: object $ref: /schemas/pci/pci-bus.yaml# diff --git a/Documentation/devicetree/bindings/pci/mediatek-pcie-gen3.yaml b/Documentation/devicetree/bindings/pci/mediatek-pcie-gen3.yaml index c00be39af64e..7e8c7a2a5f9b 100644 --- a/Documentation/devicetree/bindings/pci/mediatek-pcie-gen3.yaml +++ b/Documentation/devicetree/bindings/pci/mediatek-pcie-gen3.yaml @@ -43,14 +43,12 @@ description: |+ each set has its own address for MSI message, and supports 32 MSI vectors to generate interrupt. -allOf: - - $ref: /schemas/pci/pci-bus.yaml# - properties: compatible: oneOf: - items: - enum: + - mediatek,mt7986-pcie - mediatek,mt8188-pcie - mediatek,mt8195-pcie - const: mediatek,mt8192-pcie @@ -70,29 +68,29 @@ properties: minItems: 1 maxItems: 8 + iommu-map: + maxItems: 1 + + iommu-map-mask: + const: 0 + resets: minItems: 1 maxItems: 2 reset-names: minItems: 1 + maxItems: 2 items: - - const: phy - - const: mac + enum: [ phy, mac ] clocks: + minItems: 4 maxItems: 6 clock-names: - items: - - const: pl_250m - - const: tl_26m - - const: tl_96m - - const: tl_32k - - const: peri_26m - - enum: - - top_133m # for MT8192 - - peri_mem # for MT8188/MT8195 + minItems: 4 + maxItems: 6 assigned-clocks: maxItems: 1 @@ -107,6 +105,9 @@ properties: items: - const: pcie-phy + power-domains: + maxItems: 1 + '#interrupt-cells': const: 1 @@ -138,6 +139,54 @@ required: - '#interrupt-cells' - interrupt-controller +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + - if: + properties: + compatible: + const: mediatek,mt8192-pcie + then: + properties: + clock-names: + items: + - const: pl_250m + - const: tl_26m + - const: tl_96m + - const: tl_32k + - const: peri_26m + - const: top_133m + - if: + properties: + compatible: + contains: + enum: + - mediatek,mt8188-pcie + - mediatek,mt8195-pcie + then: + properties: + clock-names: + items: + - const: pl_250m + - const: tl_26m + - const: tl_96m + - const: tl_32k + - const: peri_26m + - const: peri_mem + - if: + properties: + compatible: + contains: + enum: + - mediatek,mt7986-pcie + then: + properties: + clock-names: + items: + - const: pl_250m + - const: tl_26m + - const: peri_26m + - const: top_133m + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie.yaml b/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie.yaml index 75da3e8eecb9..fe81d52c7277 100644 --- a/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie.yaml @@ -27,6 +27,7 @@ properties: - nvidia,tegra234-pcie reg: + minItems: 4 items: - description: controller's application logic registers - description: configuration registers @@ -35,13 +36,16 @@ properties: available for software access. - description: aperture where the Root Port's own configuration registers are available. + - description: aperture to access the configuration space through ECAM. reg-names: + minItems: 4 items: - const: appl - const: config - const: atu_dma - const: dbi + - const: ecam interrupts: items: @@ -202,6 +206,31 @@ properties: allOf: - $ref: /schemas/pci/snps,dw-pcie.yaml# + - if: + properties: + compatible: + contains: + enum: + - nvidia,tegra194-pcie + then: + properties: + reg: + maxItems: 4 + reg-names: + maxItems: 4 + + - if: + properties: + compatible: + contains: + enum: + - nvidia,tegra234-pcie + then: + properties: + reg: + minItems: 5 + reg-names: + minItems: 5 unevaluatedProperties: false @@ -305,8 +334,9 @@ examples: reg = <0x00 0x14160000 0x0 0x00020000>, /* appl registers (128K) */ <0x00 0x36000000 0x0 0x00040000>, /* configuration space (256K) */ <0x00 0x36040000 0x0 0x00040000>, /* iATU_DMA reg space (256K) */ - <0x00 0x36080000 0x0 0x00040000>; /* DBI reg space (256K) */ - reg-names = "appl", "config", "atu_dma", "dbi"; + <0x00 0x36080000 0x0 0x00040000>, /* DBI reg space (256K) */ + <0x24 0x30000000 0x0 0x10000000>; /* ECAM (256MB) */ + reg-names = "appl", "config", "atu_dma", "dbi", "ecam"; #address-cells = <3>; #size-cells = <2>; diff --git a/Documentation/devicetree/bindings/pci/qcom,pcie.yaml b/Documentation/devicetree/bindings/pci/qcom,pcie.yaml index 54f07852d279..a5859bb3dc28 100644 --- a/Documentation/devicetree/bindings/pci/qcom,pcie.yaml +++ b/Documentation/devicetree/bindings/pci/qcom,pcie.yaml @@ -62,6 +62,16 @@ properties: minItems: 3 maxItems: 13 + dma-coherent: true + + interconnects: + maxItems: 2 + + interconnect-names: + items: + - const: pcie-mem + - const: cpu-pcie + resets: minItems: 1 maxItems: 12 @@ -632,6 +642,18 @@ allOf: - const: pci # PCIe core reset - if: + properties: + compatible: + contains: + enum: + - qcom,pcie-sa8540p + - qcom,pcie-sc8280xp + then: + required: + - interconnects + - interconnect-names + + - if: not: properties: compatible: diff --git a/Documentation/devicetree/bindings/pci/renesas,pci-rcar-gen2.yaml b/Documentation/devicetree/bindings/pci/renesas,pci-rcar-gen2.yaml index 0f18cceba3d5..5a0d64d3ae6b 100644 --- a/Documentation/devicetree/bindings/pci/renesas,pci-rcar-gen2.yaml +++ b/Documentation/devicetree/bindings/pci/renesas,pci-rcar-gen2.yaml @@ -65,7 +65,7 @@ properties: maxItems: 1 patternProperties: - 'usb@[0-1],0': + '^usb@[0-1],0$': type: object description: diff --git a/Documentation/devicetree/bindings/pci/rockchip-dw-pcie.yaml b/Documentation/devicetree/bindings/pci/rockchip-dw-pcie.yaml index bc0a9d1db750..2be72ae1169f 100644 --- a/Documentation/devicetree/bindings/pci/rockchip-dw-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/rockchip-dw-pcie.yaml @@ -14,10 +14,10 @@ maintainers: description: |+ RK3568 SoC PCIe host controller is based on the Synopsys DesignWare PCIe IP and thus inherits all the common properties defined in - designware-pcie.txt. + snps,dw-pcie.yaml. allOf: - - $ref: /schemas/pci/pci-bus.yaml# + - $ref: /schemas/pci/snps,dw-pcie.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/pci/snps,dw-pcie-common.yaml b/Documentation/devicetree/bindings/pci/snps,dw-pcie-common.yaml new file mode 100644 index 000000000000..d87e13496834 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/snps,dw-pcie-common.yaml @@ -0,0 +1,266 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/snps,dw-pcie-common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Synopsys DWC PCIe RP/EP controller + +maintainers: + - Jingoo Han <jingoohan1@gmail.com> + - Gustavo Pimentel <gustavo.pimentel@synopsys.com> + +description: + Generic Synopsys DesignWare PCIe Root Port and Endpoint controller + properties. + +select: false + +properties: + reg: + description: + DWC PCIe CSR space is normally accessed over the dedicated Data Bus + Interface - DBI. In accordance with the reference manual the register + configuration space belongs to the Configuration-Dependent Module (CDM) + and is split up into several sub-parts Standard PCIe configuration + space, Port Logic Registers (PL), Shadow Config-space Registers, + iATU/eDMA registers. The particular sub-space is selected by the + CDM/ELBI (dbi_cs) and CS2 (dbi_cs2) signals (selector bits). Such + configuration provides a flexible interface for the system engineers to + either map the particular space at a desired MMIO address or just leave + them in a contiguous memory space if pure Native or AXI Bridge DBI access + is selected. Note the PCIe CFG-space, PL and Shadow registers are + specific for each activated function, while the rest of the sub-spaces + are common for all of them (if there are more than one). + minItems: 2 + maxItems: 6 + + reg-names: + minItems: 2 + maxItems: 6 + + interrupts: + description: + There are two main sub-blocks which are normally capable of + generating interrupts. It's System Information Interface and MSI + interface. While the former one has some common for the Host and + Endpoint controllers IRQ-signals, the later interface is obviously + Root Complex specific since it's responsible for the incoming MSI + messages signalling. The System Information IRQ signals are mainly + responsible for reporting the generic PCIe hierarchy and Root + Complex events like VPD IO request, general AER, PME, Hot-plug, link + bandwidth change, link equalization request, INTx asserted/deasserted + Message detection, embedded DMA Tx/Rx/Error. + minItems: 1 + maxItems: 26 + + interrupt-names: + minItems: 1 + maxItems: 26 + + clocks: + description: + DWC PCIe reference manual explicitly defines a set of the clocks required + to get the controller working correctly. In general all of them can + be divided into two groups':' application and core clocks. Note the + platforms may have some of the clock sources unspecified in case if the + corresponding domains are fed up from a common clock source. + minItems: 1 + maxItems: 7 + + clock-names: + minItems: 1 + maxItems: 7 + items: + oneOf: + - description: + Data Bus Interface (DBI) clock. Clock signal for the AXI-bus + interface of the Configuration-Dependent Module, which is + basically the set of the controller CSRs. + const: dbi + - description: + Application AXI-bus Master interface clock. Basically this is + a clock for the controller DMA interface (PCI-to-CPU). + const: mstr + - description: + Application AXI-bus Slave interface clock. This is a clock for + the CPU-to-PCI memory IO interface. + const: slv + - description: + Controller Core-PCS PIPE interface clock. It's normally + supplied by an external PCS-PHY. + const: pipe + - description: + Controller Primary clock. It's assumed that all controller input + signals (except resets) are synchronous to this clock. + const: core + - description: + Auxiliary clock for the controller PMC domain. The controller + partitioning implies having some parts to operate with this + clock in some power management states. + const: aux + - description: + Generic reference clock. In case if there are several + interfaces fed up with a common clock source it's advisable to + define it with this name (for instance pipe, core and aux can + be connected to a single source of the periodic signal). + const: ref + - description: + Clock for the PHY registers interface. Originally this is + a PHY-viewport-based interface, but some platform may have + specifically designed one. + const: phy_reg + - description: + Vendor-specific clock names. Consider using the generic names + above for new bindings. + oneOf: + - description: See native 'dbi' clock for details + enum: [ pcie, pcie_apb_sys, aclk_dbi ] + - description: See native 'mstr/slv' clock for details + enum: [ pcie_bus, pcie_inbound_axi, pcie_aclk, aclk_mst, aclk_slv ] + - description: See native 'pipe' clock for details + enum: [ pcie_phy, pcie_phy_ref, link ] + - description: See native 'aux' clock for details + enum: [ pcie_aux ] + - description: See native 'ref' clock for details. + enum: [ gio ] + - description: See nativs 'phy_reg' clock for details + enum: [ pcie_apb_phy, pclk ] + + resets: + description: + DWC PCIe reference manual explicitly defines a set of the reset + signals required to be de-asserted to properly activate the controller + sub-parts. All of these signals can be divided into two sub-groups':' + application and core resets with respect to the main sub-domains they + are supposed to reset. Note the platforms may have some of these signals + unspecified in case if they are automatically handled or aggregated into + a comprehensive control module. + minItems: 1 + maxItems: 10 + + reset-names: + minItems: 1 + maxItems: 10 + items: + oneOf: + - description: Data Bus Interface (DBI) domain reset + const: dbi + - description: AXI-bus Master interface reset + const: mstr + - description: AXI-bus Slave interface reset + const: slv + - description: Application-dependent interface reset + const: app + - description: Controller Non-sticky CSR flags reset + const: non-sticky + - description: Controller sticky CSR flags reset + const: sticky + - description: PIPE-interface (Core-PCS) logic reset + const: pipe + - description: + Controller primary reset (resets everything except PMC module) + const: core + - description: PCS/PHY block reset + const: phy + - description: PMC hot reset signal + const: hot + - description: Cold reset signal + const: pwr + - description: + Vendor-specific reset names. Consider using the generic names + above for new bindings. + oneOf: + - description: See native 'app' reset for details + enum: [ apps, gio, apb ] + - description: See native 'phy' reset for details + enum: [ pciephy, link ] + - description: See native 'pwr' reset for details + enum: [ turnoff ] + + phys: + description: + There can be up to the number of possible lanes PHYs specified placed in + the phandle array in the line-based order. Obviously each the specified + PHYs are supposed to be able to work in the PCIe mode with a speed + implied by the DWC PCIe controller they are attached to. + minItems: 1 + maxItems: 16 + + phy-names: + minItems: 1 + maxItems: 16 + oneOf: + - description: Generic PHY names + items: + pattern: '^pcie[0-9]+$' + - description: + Vendor-specific PHY names. Consider using the generic + names above for new bindings. + items: + oneOf: + - pattern: '^pcie(-?phy[0-9]*)?$' + - pattern: '^p2u-[0-7]$' + + reset-gpio: + deprecated: true + description: + Reference to the GPIO-controlled PERST# signal. It is used to reset all + the peripheral devices available on the PCIe bus. + maxItems: 1 + + reset-gpios: + description: + Reference to the GPIO-controlled PERST# signal. It is used to reset all + the peripheral devices available on the PCIe bus. + maxItems: 1 + + max-link-speed: + maximum: 5 + + num-lanes: + description: + Number of PCIe link lanes to use. Can be omitted if the already brought + up link is supposed to be preserved. + maximum: 16 + + num-ob-windows: + $ref: /schemas/types.yaml#/definitions/uint32 + deprecated: true + description: + Number of outbound address translation windows. This parameter can be + auto-detected based on the iATU memory writability. So there is no + point in having a dedicated DT-property for it. + maximum: 256 + + num-ib-windows: + $ref: /schemas/types.yaml#/definitions/uint32 + deprecated: true + description: + Number of inbound address translation windows. In the same way as + for the outbound AT windows, this parameter can be auto-detected based + on the iATU memory writability. There is no point having a dedicated + DT-property for it either. + maximum: 256 + + num-viewport: + $ref: /schemas/types.yaml#/definitions/uint32 + deprecated: true + description: + Number of outbound view ports configured in hardware. It's the same as + the number of outbound AT windows. + maximum: 256 + + snps,enable-cdm-check: + $ref: /schemas/types.yaml#/definitions/flag + description: + Enable automatic checking of CDM (Configuration Dependent Module) + registers for data corruption. CDM registers include standard PCIe + configuration space registers, Port Logic registers, DMA and iATU + registers. This feature has been available since DWC PCIe v4.80a. + + dma-coherent: true + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml b/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml index b78535040f04..8fc2151691a4 100644 --- a/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml +++ b/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml @@ -13,76 +13,182 @@ maintainers: description: | Synopsys DesignWare PCIe host controller endpoint +# Please create a separate DT-schema for your DWC PCIe Endpoint controller +# and make sure it's assigned with the vendor-specific compatible string. +select: + properties: + compatible: + const: snps,dw-pcie-ep + required: + - compatible + allOf: - $ref: /schemas/pci/pci-ep.yaml# + - $ref: /schemas/pci/snps,dw-pcie-common.yaml# properties: - compatible: - anyOf: - - {} - - const: snps,dw-pcie-ep - reg: - description: | - It should contain Data Bus Interface (dbi) and config registers for all - versions. - For designware core version >= 4.80, it may contain ATU address space. + description: + DBI, DBI2 reg-spaces and outbound memory window are required for the + normal controller functioning. iATU memory IO region is also required + if the space is unrolled (IP-core version >= 4.80a). minItems: 2 - maxItems: 4 + maxItems: 5 reg-names: minItems: 2 - maxItems: 4 + maxItems: 5 items: - enum: [dbi, dbi2, config, atu, addr_space, link, atu_dma, appl] - - reset-gpio: - description: GPIO pin number of PERST# signal - maxItems: 1 - deprecated: true - - reset-gpios: - description: GPIO controlled connection to PERST# signal - maxItems: 1 - - snps,enable-cdm-check: - type: boolean - description: | - This is a boolean property and if present enables - automatic checking of CDM (Configuration Dependent Module) registers - for data corruption. CDM registers include standard PCIe configuration - space registers, Port Logic registers, DMA and iATU (internal Address - Translation Unit) registers. - - num-ib-windows: - $ref: /schemas/types.yaml#/definitions/uint32 - maximum: 256 - description: number of inbound address translation windows - deprecated: true - - num-ob-windows: - $ref: /schemas/types.yaml#/definitions/uint32 - maximum: 256 - description: number of outbound address translation windows - deprecated: true + oneOf: + - description: + Basic DWC PCIe controller configuration-space accessible over + the DBI interface. This memory space is either activated with + CDM/ELBI = 0 and CS2 = 0 or is a contiguous memory region + with all spaces. Note iATU/eDMA CSRs are indirectly accessible + via the PL viewports on the DWC PCIe controllers older than + v4.80a. + const: dbi + - description: + Shadow DWC PCIe config-space registers. This space is selected + by setting CDM/ELBI = 0 and CS2 = 1. This is an intermix of + the PCI-SIG PCIe CFG-space with the shadow registers for some + PCI Header space, PCI Standard and Extended Structures. It's + mainly relevant for the end-point controller configuration, + but still there are some shadow registers available for the + Root Port mode too. + const: dbi2 + - description: + External Local Bus registers. It's an application-dependent + registers normally defined by the platform engineers. The space + can be selected by setting CDM/ELBI = 1 and CS2 = 0 wires or can + be accessed over some platform-specific means (for instance + as a part of a system controller). + enum: [ elbi, app ] + - description: + iATU/eDMA registers common for all device functions. It's an + unrolled memory space with the internal Address Translation + Unit and Enhanced DMA, which is selected by setting CDM/ELBI = 1 + and CS2 = 1. For IP-core releases prior v4.80a, these registers + have been programmed via an indirect addressing scheme using a + set of viewport CSRs mapped into the PL space. Note iATU is + normally mapped to the 0x0 address of this region, while eDMA + is available at 0x80000 base address. + const: atu + - description: + Platform-specific eDMA registers. Some platforms may have eDMA + CSRs mapped in a non-standard base address. The registers offset + can be changed or the MS/LS-bits of the address can be attached + in an additional RTL block before the MEM-IO transactions reach + the DW PCIe slave interface. + const: dma + - description: + PHY/PCS configuration registers. Some platforms can have the + PCS and PHY CSRs accessible over a dedicated memory mapped + region, but mainly these registers are indirectly accessible + either by means of the embedded PHY viewport schema or by some + platform-specific method. + const: phy + - description: + Outbound iATU-capable memory-region which will be used to + generate various application-specific traffic on the PCIe bus + hierarchy. It's usage scenario depends on the endpoint + functionality, for instance it can be used to create MSI(X) + messages. + const: addr_space + - description: + Vendor-specific CSR names. Consider using the generic names above + for new bindings. + oneOf: + - description: See native 'elbi/app' CSR region for details. + enum: [ link, appl ] + - description: See native 'atu' CSR region for details. + enum: [ atu_dma ] + allOf: + - contains: + const: dbi + - contains: + const: addr_space + + interrupts: + description: + There is no mandatory IRQ signals for the normal controller functioning, + but in addition to the native set the platforms may have a link- or + PM-related IRQs specified. + minItems: 1 + maxItems: 20 + + interrupt-names: + minItems: 1 + maxItems: 20 + items: + oneOf: + - description: + Controller request to read or write virtual product data + from/to the VPD capability registers. + const: vpd + - description: + Link Equalization Request flag is set in the Link Status 2 + register (applicable if the corresponding IRQ is enabled in + the Link Control 3 register). + const: l_eq + - description: + Indicates that the eDMA Tx/Rx transfer is complete or that an + error has occurred on the corresponding channel. eDMA can have + eight Tx (Write) and Rx (Read) eDMA channels thus supporting up + to 16 IRQ signals all together. Write eDMA channels shall go + first in the ordered row as per default edma_int[*] bus setup. + pattern: '^dma([0-9]|1[0-5])?$' + - description: + PCIe protocol correctable error or a Data Path protection + correctable error is detected by the automotive/safety + feature. + const: sft_ce + - description: + Indicates that the internal safety mechanism has detected an + uncorrectable error. + const: sft_ue + - description: + Application-specific IRQ raised depending on the vendor-specific + events basis. + const: app + - description: + Vendor-specific IRQ names. Consider using the generic names above + for new bindings. + oneOf: + - description: See native "app" IRQ for details + enum: [ intr ] + + max-functions: + maximum: 32 required: + - compatible - reg - reg-names - - compatible additionalProperties: true examples: - | - bus { - #address-cells = <1>; - #size-cells = <1>; - pcie-ep@dfd00000 { - compatible = "snps,dw-pcie-ep"; - reg = <0xdfc00000 0x0001000>, /* IP registers 1 */ - <0xdfc01000 0x0001000>, /* IP registers 2 */ - <0xd0000000 0x2000000>; /* Configuration space */ - reg-names = "dbi", "dbi2", "addr_space"; - }; + pcie-ep@dfd00000 { + compatible = "snps,dw-pcie-ep"; + reg = <0xdfc00000 0x0001000>, /* IP registers 1 */ + <0xdfc01000 0x0001000>, /* IP registers 2 */ + <0xd0000000 0x2000000>; /* Configuration space */ + reg-names = "dbi", "dbi2", "addr_space"; + + interrupts = <23>, <24>; + interrupt-names = "dma0", "dma1"; + + clocks = <&sys_clk 12>, <&sys_clk 24>; + clock-names = "dbi", "ref"; + + resets = <&sys_rst 12>, <&sys_rst 24>; + reset-names = "dbi", "phy"; + + phys = <&pcie_phy0>, <&pcie_phy1>, <&pcie_phy2>, <&pcie_phy3>; + phy-names = "pcie0", "pcie1", "pcie2", "pcie3"; + + max-link-speed = <3>; + max-functions = /bits/ 8 <4>; }; diff --git a/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml b/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml index 7287d395e1b6..1a83f0f65f19 100644 --- a/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml @@ -13,20 +13,25 @@ maintainers: description: | Synopsys DesignWare PCIe host controller +# Please create a separate DT-schema for your DWC PCIe Root Port controller +# and make sure it's assigned with the vendor-specific compatible string. +select: + properties: + compatible: + const: snps,dw-pcie + required: + - compatible + allOf: - $ref: /schemas/pci/pci-bus.yaml# + - $ref: /schemas/pci/snps,dw-pcie-common.yaml# properties: - compatible: - anyOf: - - {} - - const: snps,dw-pcie - reg: - description: | - It should contain Data Bus Interface (dbi) and config registers for all - versions. - For designware core version >= 4.80, it may contain ATU address space. + description: + At least DBI reg-space and peripheral devices CFG-space outbound window + are required for the normal controller work. iATU memory IO region is + also required if the space is unrolled (IP-core version >= 4.80a). minItems: 2 maxItems: 5 @@ -34,71 +39,194 @@ properties: minItems: 2 maxItems: 5 items: - enum: [ dbi, dbi2, config, atu, atu_dma, app, appl, elbi, mgmt, ctrl, - parf, cfg, link, ulreg, smu, mpu, apb, phy ] - - num-lanes: - description: | - number of lanes to use (this property should be specified unless - the link is brought already up in firmware) - maximum: 16 - - reset-gpio: - description: GPIO pin number of PERST# signal - maxItems: 1 - deprecated: true - - reset-gpios: - description: GPIO controlled connection to PERST# signal - maxItems: 1 - - interrupts: true - - interrupt-names: true - - clocks: true - - snps,enable-cdm-check: - type: boolean - description: | - This is a boolean property and if present enables - automatic checking of CDM (Configuration Dependent Module) registers - for data corruption. CDM registers include standard PCIe configuration - space registers, Port Logic registers, DMA and iATU (internal Address - Translation Unit) registers. - - num-viewport: - $ref: /schemas/types.yaml#/definitions/uint32 - maximum: 256 - description: | - number of view ports configured in hardware. If a platform - does not specify it, the driver autodetects it. - deprecated: true + oneOf: + - description: + Basic DWC PCIe controller configuration-space accessible over + the DBI interface. This memory space is either activated with + CDM/ELBI = 0 and CS2 = 0 or is a contiguous memory region + with all spaces. Note iATU/eDMA CSRs are indirectly accessible + via the PL viewports on the DWC PCIe controllers older than + v4.80a. + const: dbi + - description: + Shadow DWC PCIe config-space registers. This space is selected + by setting CDM/ELBI = 0 and CS2 = 1. This is an intermix of + the PCI-SIG PCIe CFG-space with the shadow registers for some + PCI Header space, PCI Standard and Extended Structures. It's + mainly relevant for the end-point controller configuration, + but still there are some shadow registers available for the + Root Port mode too. + const: dbi2 + - description: + External Local Bus registers. It's an application-dependent + registers normally defined by the platform engineers. The space + can be selected by setting CDM/ELBI = 1 and CS2 = 0 wires or can + be accessed over some platform-specific means (for instance + as a part of a system controller). + enum: [ elbi, app ] + - description: + iATU/eDMA registers common for all device functions. It's an + unrolled memory space with the internal Address Translation + Unit and Enhanced DMA, which is selected by setting CDM/ELBI = 1 + and CS2 = 1. For IP-core releases prior v4.80a, these registers + have been programmed via an indirect addressing scheme using a + set of viewport CSRs mapped into the PL space. Note iATU is + normally mapped to the 0x0 address of this region, while eDMA + is available at 0x80000 base address. + const: atu + - description: + Platform-specific eDMA registers. Some platforms may have eDMA + CSRs mapped in a non-standard base address. The registers offset + can be changed or the MS/LS-bits of the address can be attached + in an additional RTL block before the MEM-IO transactions reach + the DW PCIe slave interface. + const: dma + - description: + PHY/PCS configuration registers. Some platforms can have the + PCS and PHY CSRs accessible over a dedicated memory mapped + region, but mainly these registers are indirectly accessible + either by means of the embedded PHY viewport schema or by some + platform-specific method. + const: phy + - description: + Outbound iATU-capable memory-region which will be used to access + the peripheral PCIe devices configuration space. + const: config + - description: + Vendor-specific CSR names. Consider using the generic names above + for new bindings. + oneOf: + - description: See native 'elbi/app' CSR region for details. + enum: [ apb, mgmt, link, ulreg, appl ] + - description: See native 'atu' CSR region for details. + enum: [ atu_dma ] + - description: Syscon-related CSR regions. + enum: [ smu, mpu ] + - description: Tegra234 aperture + enum: [ ecam ] + allOf: + - contains: + const: dbi + - contains: + const: config + + interrupts: + description: + DWC PCIe Root Port/Complex specific IRQ signals. At least MSI interrupt + signal is supposed to be specified for the host controller. + minItems: 1 + maxItems: 26 + + interrupt-names: + minItems: 1 + maxItems: 26 + items: + oneOf: + - description: + Controller request to read or write virtual product data + from/to the VPD capability registers. + const: vpd + - description: + Link Equalization Request flag is set in the Link Status 2 + register (applicable if the corresponding IRQ is enabled in + the Link Control 3 register). + const: l_eq + - description: + Indicates that the eDMA Tx/Rx transfer is complete or that an + error has occurred on the corresponding channel. eDMA can have + eight Tx (Write) and Rx (Read) eDMA channels thus supporting up + to 16 IRQ signals all together. Write eDMA channels shall go + first in the ordered row as per default edma_int[*] bus setup. + pattern: '^dma([0-9]|1[0-5])?$' + - description: + PCIe protocol correctable error or a Data Path protection + correctable error is detected by the automotive/safety + feature. + const: sft_ce + - description: + Indicates that the internal safety mechanism has detected an + uncorrectable error. + const: sft_ue + - description: + Application-specific IRQ raised depending on the vendor-specific + events basis. + const: app + - description: + DSP AXI MSI Interrupt detected. It gets de-asserted when there is + no more MSI interrupt pending. The interrupt is relevant to the + iMSI-RX - Integrated MSI Receiver (AXI bridge). + const: msi + - description: + Legacy A/B/C/D interrupt signal. Basically it's triggered by + receiving a Assert_INT{A,B,C,D}/Desassert_INT{A,B,C,D} message + from the downstream device. + pattern: "^int(a|b|c|d)$" + - description: + Error condition detected and a flag is set in the Root Error Status + register of the AER capability. It's asserted when the RC + internally generated an error or an error message is received by + the RC. + const: aer + - description: + PME message is received by the port. That means having the PME + status bit set in the Root Status register (the event is + supposed to be unmasked in the Root Control register). + const: pme + - description: + Hot-plug event is detected. That is a bit has been set in the + Slot Status register and the corresponding event is enabled in + the Slot Control register. + const: hp + - description: + Link Autonomous Bandwidth Status flag has been set in the Link + Status register (the event is supposed to be unmasked in the + Link Control register). + const: bw_au + - description: + Bandwidth Management Status flag has been set in the Link + Status register (the event is supposed to be unmasked in the + Link Control register). + const: bw_mg + - description: + Vendor-specific IRQ names. Consider using the generic names above + for new bindings. + oneOf: + - description: See native "app" IRQ for details + enum: [ intr ] + allOf: + - contains: + const: msi additionalProperties: true required: + - compatible - reg - reg-names - - compatible examples: - | - bus { - #address-cells = <1>; - #size-cells = <1>; - pcie@dfc00000 { - device_type = "pci"; - compatible = "snps,dw-pcie"; - reg = <0xdfc00000 0x0001000>, /* IP registers */ - <0xd0000000 0x0002000>; /* Configuration space */ - reg-names = "dbi", "config"; - #address-cells = <3>; - #size-cells = <2>; - ranges = <0x81000000 0 0x00000000 0xde000000 0 0x00010000>, - <0x82000000 0 0xd0400000 0xd0400000 0 0x0d000000>; - interrupts = <25>, <24>; - #interrupt-cells = <1>; - num-lanes = <1>; - }; + pcie@dfc00000 { + compatible = "snps,dw-pcie"; + device_type = "pci"; + reg = <0xdfc00000 0x0001000>, /* IP registers */ + <0xd0000000 0x0002000>; /* Configuration space */ + reg-names = "dbi", "config"; + #address-cells = <3>; + #size-cells = <2>; + ranges = <0x81000000 0 0x00000000 0xde000000 0 0x00010000>, + <0x82000000 0 0xd0400000 0xd0400000 0 0x0d000000>; + bus-range = <0x0 0xff>; + + interrupts = <25>, <24>; + interrupt-names = "msi", "hp"; + #interrupt-cells = <1>; + + reset-gpios = <&port0 0 1>; + + phys = <&pcie_phy>; + phy-names = "pcie"; + + num-lanes = <1>; + max-link-speed = <3>; }; diff --git a/Documentation/devicetree/bindings/pci/ti,j721e-pci-ep.yaml b/Documentation/devicetree/bindings/pci/ti,j721e-pci-ep.yaml index aed437dac363..10e6eabdff53 100644 --- a/Documentation/devicetree/bindings/pci/ti,j721e-pci-ep.yaml +++ b/Documentation/devicetree/bindings/pci/ti,j721e-pci-ep.yaml @@ -58,6 +58,13 @@ properties: dma-coherent: description: Indicates that the PCIe IP block can ensure the coherency + interrupts: + maxItems: 1 + + interrupt-names: + items: + - const: link_state + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml b/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml index 2115d5a3f0e1..b0513b197d08 100644 --- a/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml +++ b/Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml @@ -73,9 +73,31 @@ properties: - const: 0xb00f - items: - const: 0xb010 + - items: + - const: 0xb013 msi-map: true + interrupts: + maxItems: 1 + + interrupt-names: + items: + - const: link_state + + interrupt-controller: + type: object + additionalProperties: false + + properties: + interrupt-controller: true + + '#interrupt-cells': + const: 1 + + interrupts: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/pci/toshiba,visconti-pcie.yaml b/Documentation/devicetree/bindings/pci/toshiba,visconti-pcie.yaml index 48ed227fc5b9..53da2edd7c9a 100644 --- a/Documentation/devicetree/bindings/pci/toshiba,visconti-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/toshiba,visconti-pcie.yaml @@ -36,7 +36,7 @@ properties: - const: mpu interrupts: - maxItems: 1 + maxItems: 2 clocks: items: @@ -94,8 +94,9 @@ examples: #interrupt-cells = <1>; ranges = <0x81000000 0 0x40000000 0 0x40000000 0 0x00010000>, <0x82000000 0 0x50000000 0 0x50000000 0 0x20000000>; - interrupts = <GIC_SPI 215 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "intr"; + interrupts = <GIC_SPI 211 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 215 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "msi", "intr"; interrupt-map-mask = <0 0 0 7>; interrupt-map = <0 0 0 1 &gic GIC_SPI 215 IRQ_TYPE_LEVEL_HIGH diff --git a/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt b/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt deleted file mode 100644 index f56f8c58c5d9..000000000000 --- a/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt +++ /dev/null @@ -1,73 +0,0 @@ -* Xilinx NWL PCIe Root Port Bridge DT description - -Required properties: -- compatible: Should contain "xlnx,nwl-pcie-2.11" -- #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. -- reg: Should contain Bridge, PCIe Controller registers location, - configuration space, and length -- reg-names: Must include the following entries: - "breg": bridge registers - "pcireg": PCIe controller registers - "cfg": configuration space region -- device_type: must be "pci" -- interrupts: Should contain NWL PCIe interrupt -- interrupt-names: Must include the following entries: - "msi1, msi0": interrupt asserted when an MSI is received - "intx": interrupt asserted when a legacy interrupt is received - "misc": interrupt asserted when miscellaneous interrupt is received -- interrupt-map-mask and interrupt-map: standard PCI properties to define the - mapping of the PCI interface to interrupt numbers. -- ranges: ranges for the PCI memory regions (I/O space region is not - supported by hardware) - Please refer to the standard PCI bus binding document for a more - detailed explanation -- msi-controller: indicates that this is MSI controller node -- msi-parent: MSI parent of the root complex itself -- legacy-interrupt-controller: Interrupt controller device node for Legacy - interrupts - - interrupt-controller: identifies the node as an interrupt controller - - #interrupt-cells: should be set to 1 - - #address-cells: specifies the number of cells needed to encode an - address. The value must be 0. - -Optional properties: -- dma-coherent: present if DMA operations are coherent -- clocks: Input clock specifier. Refer to common clock bindings - -Example: -++++++++ - -nwl_pcie: pcie@fd0e0000 { - #address-cells = <3>; - #size-cells = <2>; - compatible = "xlnx,nwl-pcie-2.11"; - #interrupt-cells = <1>; - msi-controller; - device_type = "pci"; - interrupt-parent = <&gic>; - interrupts = <0 114 4>, <0 115 4>, <0 116 4>, <0 117 4>, <0 118 4>; - interrupt-names = "msi0", "msi1", "intx", "dummy", "misc"; - interrupt-map-mask = <0x0 0x0 0x0 0x7>; - interrupt-map = <0x0 0x0 0x0 0x1 &pcie_intc 0x1>, - <0x0 0x0 0x0 0x2 &pcie_intc 0x2>, - <0x0 0x0 0x0 0x3 &pcie_intc 0x3>, - <0x0 0x0 0x0 0x4 &pcie_intc 0x4>; - - msi-parent = <&nwl_pcie>; - reg = <0x0 0xfd0e0000 0x0 0x1000>, - <0x0 0xfd480000 0x0 0x1000>, - <0x80 0x00000000 0x0 0x1000000>; - reg-names = "breg", "pcireg", "cfg"; - ranges = <0x02000000 0x00000000 0xe0000000 0x00000000 0xe0000000 0x00000000 0x10000000 /* non-prefetchable memory */ - 0x43000000 0x00000006 0x00000000 0x00000006 0x00000000 0x00000002 0x00000000>;/* prefetchable memory */ - - pcie_intc: legacy-interrupt-controller { - interrupt-controller; - #address-cells = <0>; - #interrupt-cells = <1>; - }; - -}; diff --git a/Documentation/devicetree/bindings/pci/xilinx-pcie.txt b/Documentation/devicetree/bindings/pci/xilinx-pcie.txt deleted file mode 100644 index fd57a81180a4..000000000000 --- a/Documentation/devicetree/bindings/pci/xilinx-pcie.txt +++ /dev/null @@ -1,88 +0,0 @@ -* Xilinx 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 "xlnx,axi-pcie-host-1.00.a" -- reg: Should contain AXI PCIe registers location and length -- device_type: must be "pci" -- interrupts: Should contain AXI PCIe interrupt -- interrupt-map-mask, - interrupt-map: standard PCI properties to define the mapping of the - PCI interface to interrupt numbers. -- ranges: ranges for the PCI memory regions (I/O space region is not - supported by hardware) - Please refer to the standard PCI bus binding document for a more - detailed explanation - -Optional properties for Zynq/Microblaze: -- bus-range: PCI bus numbers covered - -Interrupt controller child node -+++++++++++++++++++++++++++++++ -Required properties: -- 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. - -NOTE: -The core provides a single interrupt for both INTx/MSI messages. So, -created a interrupt controller node to support 'interrupt-map' DT -functionality. The driver will create an IRQ domain for this map, decode -the four INTx interrupts in ISR and route them to this domain. - - -Example: -++++++++ -Zynq: - pci_express: axi-pcie@50000000 { - #address-cells = <3>; - #size-cells = <2>; - #interrupt-cells = <1>; - compatible = "xlnx,axi-pcie-host-1.00.a"; - reg = < 0x50000000 0x1000000 >; - device_type = "pci"; - interrupts = < 0 52 4 >; - interrupt-map-mask = <0 0 0 7>; - interrupt-map = <0 0 0 1 &pcie_intc 1>, - <0 0 0 2 &pcie_intc 2>, - <0 0 0 3 &pcie_intc 3>, - <0 0 0 4 &pcie_intc 4>; - ranges = < 0x02000000 0 0x60000000 0x60000000 0 0x10000000 >; - - pcie_intc: interrupt-controller { - interrupt-controller; - #address-cells = <0>; - #interrupt-cells = <1>; - }; - }; - - -Microblaze: - pci_express: axi-pcie@10000000 { - #address-cells = <3>; - #size-cells = <2>; - #interrupt-cells = <1>; - compatible = "xlnx,axi-pcie-host-1.00.a"; - reg = <0x10000000 0x4000000>; - device_type = "pci"; - interrupt-parent = <µblaze_0_intc>; - interrupts = <1 2>; - interrupt-map-mask = <0 0 0 7>; - interrupt-map = <0 0 0 1 &pcie_intc 1>, - <0 0 0 2 &pcie_intc 2>, - <0 0 0 3 &pcie_intc 3>, - <0 0 0 4 &pcie_intc 4>; - ranges = <0x02000000 0x00000000 0x80000000 0x80000000 0x00000000 0x10000000>; - - pcie_intc: interrupt-controller { - interrupt-controller; - #address-cells = <0>; - #interrupt-cells = <1>; - }; - - }; diff --git a/Documentation/devicetree/bindings/pci/xlnx,axi-pcie-host.yaml b/Documentation/devicetree/bindings/pci/xlnx,axi-pcie-host.yaml new file mode 100644 index 000000000000..69b7decabd45 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/xlnx,axi-pcie-host.yaml @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/xlnx,axi-pcie-host.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx AXI PCIe Root Port Bridge + +maintainers: + - Thippeswamy Havalige <thippeswamy.havalige@amd.com> + +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + +properties: + compatible: + const: xlnx,axi-pcie-host-1.00.a + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + ranges: + items: + - description: | + ranges for the PCI memory regions (I/O space region is not + supported by hardware) + + "#interrupt-cells": + const: 1 + + interrupt-controller: + description: identifies the node as an interrupt controller + type: object + properties: + interrupt-controller: true + + "#address-cells": + const: 0 + + "#interrupt-cells": + const: 1 + + required: + - interrupt-controller + - "#address-cells" + - "#interrupt-cells" + + additionalProperties: false + +required: + - compatible + - reg + - ranges + - interrupts + - interrupt-map + - "#interrupt-cells" + - interrupt-controller + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + pcie@50000000 { + compatible = "xlnx,axi-pcie-host-1.00.a"; + reg = <0x50000000 0x1000000>; + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + device_type = "pci"; + interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0 0 0 1 &pcie_intc 1>, + <0 0 0 2 &pcie_intc 2>, + <0 0 0 3 &pcie_intc 3>, + <0 0 0 4 &pcie_intc 4>; + ranges = <0x02000000 0 0x60000000 0x60000000 0 0x10000000>; + pcie_intc: interrupt-controller { + interrupt-controller; + #address-cells = <0>; + #interrupt-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/pci/xlnx,nwl-pcie.yaml b/Documentation/devicetree/bindings/pci/xlnx,nwl-pcie.yaml new file mode 100644 index 000000000000..897602559b37 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/xlnx,nwl-pcie.yaml @@ -0,0 +1,149 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/xlnx,nwl-pcie.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx NWL PCIe Root Port Bridge + +maintainers: + - Thippeswamy Havalige <thippeswamy.havalige@amd.com> + +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + - $ref: /schemas/interrupt-controller/msi-controller.yaml# + +properties: + compatible: + const: xlnx,nwl-pcie-2.11 + + reg: + items: + - description: PCIe bridge registers location. + - description: PCIe Controller registers location. + - description: PCIe Configuration space region. + + reg-names: + items: + - const: breg + - const: pcireg + - const: cfg + + interrupts: + items: + - description: interrupt asserted when miscellaneous interrupt is received + - description: unused interrupt(dummy) + - description: interrupt asserted when a legacy interrupt is received + - description: msi1 interrupt asserted when an MSI is received + - description: msi0 interrupt asserted when an MSI is received + + interrupt-names: + items: + - const: misc + - const: dummy + - const: intx + - const: msi1 + - const: msi0 + + interrupt-map-mask: + items: + - const: 0 + - const: 0 + - const: 0 + - const: 7 + + "#interrupt-cells": + const: 1 + + msi-parent: + description: MSI controller the device is capable of using. + + interrupt-map: + maxItems: 4 + + power-domains: + maxItems: 1 + + iommus: + maxItems: 1 + + dma-coherent: + description: optional, only needed if DMA operations are coherent. + + clocks: + maxItems: 1 + description: optional, input clock specifier. + + legacy-interrupt-controller: + description: Interrupt controller node for handling legacy PCI interrupts. + type: object + properties: + "#address-cells": + const: 0 + + "#interrupt-cells": + const: 1 + + "interrupt-controller": true + + required: + - "#address-cells" + - "#interrupt-cells" + - interrupt-controller + + additionalProperties: false + +required: + - compatible + - reg + - reg-names + - interrupts + - "#interrupt-cells" + - interrupt-map + - interrupt-map-mask + - msi-controller + - power-domains + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/power/xlnx-zynqmp-power.h> + soc { + #address-cells = <2>; + #size-cells = <2>; + nwl_pcie: pcie@fd0e0000 { + compatible = "xlnx,nwl-pcie-2.11"; + reg = <0x0 0xfd0e0000 0x0 0x1000>, + <0x0 0xfd480000 0x0 0x1000>, + <0x80 0x00000000 0x0 0x1000000>; + reg-names = "breg", "pcireg", "cfg"; + ranges = <0x02000000 0x0 0xe0000000 0x0 0xe0000000 0x0 0x10000000>, + <0x43000000 0x00000006 0x0 0x00000006 0x0 0x00000002 0x0>; + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + msi-controller; + device_type = "pci"; + interrupt-parent = <&gic>; + interrupts = <GIC_SPI 118 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 116 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 116 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 115 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 114 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "misc", "dummy", "intx", "msi1", "msi0"; + interrupt-map-mask = <0x0 0x0 0x0 0x7>; + interrupt-map = <0x0 0x0 0x0 0x1 &pcie_intc 0x1>, + <0x0 0x0 0x0 0x2 &pcie_intc 0x2>, + <0x0 0x0 0x0 0x3 &pcie_intc 0x3>, + <0x0 0x0 0x0 0x4 &pcie_intc 0x4>; + msi-parent = <&nwl_pcie>; + power-domains = <&zynqmp_firmware PD_PCIE>; + iommus = <&smmu 0x4d0>; + pcie_intc: legacy-interrupt-controller { + interrupt-controller; + #address-cells = <0>; + #interrupt-cells = <1>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/perf/amlogic,g12-ddr-pmu.yaml b/Documentation/devicetree/bindings/perf/amlogic,g12-ddr-pmu.yaml new file mode 100644 index 000000000000..50f46a6898b1 --- /dev/null +++ b/Documentation/devicetree/bindings/perf/amlogic,g12-ddr-pmu.yaml @@ -0,0 +1,54 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/perf/amlogic,g12-ddr-pmu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic G12 DDR performance monitor + +maintainers: + - Jiucheng Xu <jiucheng.xu@amlogic.com> + +description: | + Amlogic G12 series SoC integrate DDR bandwidth monitor. + A timer is inside and can generate interrupt when timeout. + The bandwidth is counted in the timer ISR. Different platform + has different subset of event format attribute. + +properties: + compatible: + enum: + - amlogic,g12a-ddr-pmu + - amlogic,g12b-ddr-pmu + - amlogic,sm1-ddr-pmu + + reg: + items: + - description: DMC bandwidth register space. + - description: DMC PLL register space. + + interrupts: + items: + - description: The IRQ of the inside timer timeout. + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + pmu { + #address-cells=<2>; + #size-cells=<2>; + + pmu@ff638000 { + compatible = "amlogic,g12a-ddr-pmu"; + reg = <0x0 0xff638000 0x0 0x100>, + <0x0 0xff638c00 0x0 0x100>; + interrupts = <GIC_SPI 52 IRQ_TYPE_EDGE_RISING>; + }; + }; diff --git a/Documentation/devicetree/bindings/perf/arm,dsu-pmu.yaml b/Documentation/devicetree/bindings/perf/arm,dsu-pmu.yaml index c87821be158b..a740378ed592 100644 --- a/Documentation/devicetree/bindings/perf/arm,dsu-pmu.yaml +++ b/Documentation/devicetree/bindings/perf/arm,dsu-pmu.yaml @@ -32,11 +32,8 @@ properties: - description: nCLUSTERPMUIRQ interrupt cpus: - $ref: /schemas/types.yaml#/definitions/phandle-array minItems: 1 maxItems: 12 - items: - maxItems: 1 description: List of phandles for the CPUs connected to this DSU instance. required: diff --git a/Documentation/devicetree/bindings/phy/intel,phy-thunderbay-emmc.yaml b/Documentation/devicetree/bindings/phy/intel,phy-thunderbay-emmc.yaml index 34bdb5c4cae8..b09e5ba5e127 100644 --- a/Documentation/devicetree/bindings/phy/intel,phy-thunderbay-emmc.yaml +++ b/Documentation/devicetree/bindings/phy/intel,phy-thunderbay-emmc.yaml @@ -36,11 +36,10 @@ additionalProperties: false examples: - | - mmc_phy@80440800 { - #phy-cells = <0x0>; - compatible = "intel,thunderbay-emmc-phy"; - status = "okay"; - reg = <0x80440800 0x100>; - clocks = <&emmc>; - clock-names = "emmcclk"; - }; + mmc_phy@80440800 { + #phy-cells = <0x0>; + compatible = "intel,thunderbay-emmc-phy"; + reg = <0x80440800 0x100>; + clocks = <&emmc>; + clock-names = "emmcclk"; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imxrt1050.yaml b/Documentation/devicetree/bindings/pinctrl/fsl,imxrt1050.yaml index 1278f7293560..db5fe66ad873 100644 --- a/Documentation/devicetree/bindings/pinctrl/fsl,imxrt1050.yaml +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imxrt1050.yaml @@ -35,7 +35,7 @@ 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 <include/dt-bindings/pinctrl/pins-imxrt1050.h>. The last + be found in <arch/arm/boot/dts/imxrt1050-pinfunc.h>. The last integer CONFIG is the pad setting value like pull-up on this pin. Please refer to i.MXRT1050 Reference Manual for detailed CONFIG settings. $ref: /schemas/types.yaml#/definitions/uint32-matrix diff --git a/Documentation/devicetree/bindings/pinctrl/loongson,ls2k-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/loongson,ls2k-pinctrl.yaml new file mode 100644 index 000000000000..bd8a45843566 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/loongson,ls2k-pinctrl.yaml @@ -0,0 +1,123 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/loongson,ls2k-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Loongson-2 SoC Pinctrl Controller + +maintainers: + - zhanghongchen <zhanghongchen@loongson.cn> + - Yinbo Zhu <zhuyinbo@loongson.cn> + +allOf: + - $ref: pinctrl.yaml# + +properties: + compatible: + const: loongson,ls2k-pinctrl + + reg: + maxItems: 1 + +patternProperties: + '-pins$': + type: object + + additionalProperties: false + + patternProperties: + 'pinmux$': + type: object + description: node for pinctrl. + $ref: pinmux-node.yaml# + + unevaluatedProperties: false + + properties: + groups: + description: + One or more groups of pins to mux to a certain function + items: + enum: [gpio, sdio, can1, can0, pwm3, pwm2, pwm1, pwm0, i2c1, i2c0, + nand, sata_led, i2s, hda] + function: + description: + The function that a group of pins is muxed to + enum: [gpio, sdio, can1, can0, pwm3, pwm2, pwm1, pwm0, i2c1, i2c0, + nand, sata_led, i2s, hda] + + required: + - groups + - function + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + pctrl: pinctrl@1fe00420 { + compatible = "loongson,ls2k-pinctrl"; + reg = <0x1fe00420 0x18>; + sdio_pins_default: sdio-pins { + sdio-pinmux { + groups = "sdio"; + function = "sdio"; + }; + + sdio-det-pinmux { + groups = "pwm2"; + function = "gpio"; + }; + }; + + pwm1_pins_default: pwm1-pins { + pinmux { + groups = "pwm1"; + function = "pwm1"; + }; + }; + + pwm0_pins_default: pwm0-pins { + pinmux { + groups = "pwm0"; + function = "pwm0"; + }; + }; + + i2c1_pins_default: i2c1-pins { + pinmux { + groups = "i2c1"; + function = "i2c1"; + }; + }; + + i2c0_pins_default: i2c0-pins { + pinmux { + groups = "i2c0"; + function = "i2c0"; + }; + }; + + nand_pins_default: nand-pins { + pinmux { + groups = "nand"; + function = "nand"; + }; + }; + + hda_pins_default: hda-pins { + grp0-pinmux { + groups = "hda"; + function = "hda"; + }; + + grp1-pinmux { + groups = "i2s"; + function = "gpio"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt65xx-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt65xx-pinctrl.yaml index 33b5f79e741a..1b44335b1e94 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt65xx-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt65xx-pinctrl.yaml @@ -31,7 +31,8 @@ properties: pins-are-numbered: $ref: /schemas/types.yaml#/definitions/flag description: | - Specify the subnodes are using numbered pinmux to specify pins. + Specify the subnodes are using numbered pinmux to specify pins. (UNUSED) + deprecated: true gpio-controller: true @@ -62,7 +63,6 @@ properties: required: - compatible - - pins-are-numbered - gpio-controller - "#gpio-cells" @@ -150,7 +150,6 @@ examples: compatible = "mediatek,mt8135-pinctrl"; reg = <0 0x1000B000 0 0x1000>; mediatek,pctl-regmap = <&syscfg_pctl_a>, <&syscfg_pctl_b>; - pins-are-numbered; gpio-controller; #gpio-cells = <2>; interrupt-controller; diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt6779-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt6779-pinctrl.yaml index 8c79fcef7c52..a2141eb0854e 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt6779-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt6779-pinctrl.yaml @@ -8,31 +8,22 @@ title: Mediatek MT6779 Pin Controller maintainers: - Andy Teng <andy.teng@mediatek.com> + - Sean Wang <sean.wang@kernel.org> -description: |+ - The pin controller node should be the child of a syscon node with the - required property: - - compatible: "syscon" +description: + The MediaTek pin controller on MT6779 is used to control pin + functions, pull up/down resistance and drive strength options. properties: compatible: - const: mediatek,mt6779-pinctrl + enum: + - mediatek,mt6779-pinctrl + - mediatek,mt6797-pinctrl reg: - minItems: 9 - maxItems: 9 - - reg-names: - items: - - const: "gpio" - - const: "iocfg_rm" - - const: "iocfg_br" - - const: "iocfg_lm" - - const: "iocfg_lb" - - const: "iocfg_rt" - - const: "iocfg_lt" - - const: "iocfg_tl" - - const: "eint" + description: Physical addresses for GPIO base(s) and EINT registers. + + reg-names: true gpio-controller: true @@ -59,19 +50,65 @@ properties: "#interrupt-cells": const: 2 -allOf: - - $ref: "pinctrl.yaml#" - required: - compatible - reg - reg-names - gpio-controller - "#gpio-cells" - - gpio-ranges - - interrupt-controller - - interrupts - - "#interrupt-cells" + +allOf: + - $ref: "pinctrl.yaml#" + - if: + properties: + compatible: + contains: + const: mediatek,mt6779-pinctrl + then: + properties: + reg: + minItems: 9 + maxItems: 9 + + reg-names: + items: + - const: gpio + - const: iocfg_rm + - const: iocfg_br + - const: iocfg_lm + - const: iocfg_lb + - const: iocfg_rt + - const: iocfg_lt + - const: iocfg_tl + - const: eint + - if: + properties: + compatible: + contains: + const: mediatek,mt6797-pinctrl + then: + properties: + reg: + minItems: 5 + maxItems: 5 + + reg-names: + items: + - const: gpio + - const: iocfgl + - const: iocfgb + - const: iocfgr + - const: iocfgt + - if: + properties: + reg-names: + contains: + const: eint + then: + required: + - interrupts + - interrupt-controller + - "#interrupt-cells" patternProperties: '-[0-9]*$': @@ -113,6 +150,12 @@ patternProperties: input-schmitt-disable: true + drive-strength: + enum: [2, 4, 8, 12, 16] + + slew-rate: + enum: [0, 1] + mediatek,pull-up-adv: description: | Pull up setings for 2 pull resistors, R0 and R1. User can diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt6797-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt6797-pinctrl.yaml deleted file mode 100644 index 637a8386e23e..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt6797-pinctrl.yaml +++ /dev/null @@ -1,176 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/pinctrl/mediatek,mt6797-pinctrl.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Mediatek MT6797 Pin Controller - -maintainers: - - Sean Wang <sean.wang@kernel.org> - -description: |+ - The MediaTek's MT6797 Pin controller is used to control SoC pins. - -properties: - compatible: - const: mediatek,mt6797-pinctrl - - reg: - minItems: 5 - maxItems: 5 - - reg-names: - items: - - const: gpio - - const: iocfgl - - const: iocfgb - - const: iocfgr - - const: iocfgt - - 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 - -allOf: - - $ref: "pinctrl.yaml#" - -required: - - compatible - - reg - - reg-names - - gpio-controller - - "#gpio-cells" - -patternProperties: - '-[0-9]+$': - type: object - additionalProperties: false - patternProperties: - 'pins': - type: object - additionalProperties: false - description: | - A pinctrl node should contain at least one subnodes representing the - pinctrl groups available on the machine. Each subnode will list the - pins it needs, and how they should be configured, with regard to muxer - configuration, pullups, drive strength, input enable/disable and input - schmitt. - $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: true - - bias-pull-down: true - - 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, 8, 12, 16] - - slew-rate: - enum: [0, 1] - - 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 - -additionalProperties: false - -examples: - - | - #include <dt-bindings/interrupt-controller/irq.h> - #include <dt-bindings/interrupt-controller/arm-gic.h> - #include <dt-bindings/pinctrl/mt6797-pinfunc.h> - - soc { - #address-cells = <2>; - #size-cells = <2>; - - pio: pinctrl@10005000 { - compatible = "mediatek,mt6797-pinctrl"; - reg = <0 0x10005000 0 0x1000>, - <0 0x10002000 0 0x400>, - <0 0x10002400 0 0x400>, - <0 0x10002800 0 0x400>, - <0 0x10002C00 0 0x400>; - reg-names = "gpio", "iocfgl", "iocfgb", "iocfgr", "iocfgt"; - gpio-controller; - #gpio-cells = <2>; - - uart_pins_a: uart-0 { - pins1 { - pinmux = <MT6797_GPIO232__FUNC_URXD1>, - <MT6797_GPIO233__FUNC_UTXD1>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,mt7986-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,mt7986-pinctrl.yaml index 89b8f3dd67a1..216b356cd519 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,mt7986-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,mt7986-pinctrl.yaml @@ -87,6 +87,8 @@ patternProperties: "wifi_led" "led" 1, 2 "i2c" "i2c" 3, 4 "uart1_0" "uart" 7, 8, 9, 10 + "uart1_rx_tx" "uart" 42, 43 + "uart1_cts_rts" "uart" 44, 45 "pcie_clk" "pcie" 9 "pcie_wake" "pcie" 10 "spi1_0" "spi" 11, 12, 13, 14 @@ -98,9 +100,11 @@ patternProperties: "emmc_45" "emmc" 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32 "spi1_1" "spi" 23, 24, 25, 26 - "uart1_2" "uart" 29, 30, 31, 32 + "uart1_2_rx_tx" "uart" 29, 30 + "uart1_2_cts_rts" "uart" 31, 32 "uart1_1" "uart" 23, 24, 25, 26 - "uart2_0" "uart" 29, 30, 31, 32 + "uart2_0_rx_tx" "uart" 29, 30 + "uart2_0_cts_rts" "uart" 31, 32 "spi0" "spi" 33, 34, 35, 36 "spi0_wp_hold" "spi" 37, 38 "uart1_3_rx_tx" "uart" 35, 36 @@ -157,7 +161,7 @@ patternProperties: then: properties: groups: - enum: [emmc, emmc_rst] + enum: [emmc_45, emmc_51] - if: properties: function: @@ -197,7 +201,9 @@ patternProperties: then: properties: groups: - enum: [pcie_clk, pcie_wake, pcie_pereset] + items: + enum: [pcie_clk, pcie_wake, pcie_pereset] + maxItems: 3 - if: properties: function: @@ -205,7 +211,9 @@ patternProperties: then: properties: groups: - enum: [pwm0, pwm1_0, pwm1_1] + items: + enum: [pwm0, pwm1_0, pwm1_1] + maxItems: 2 - if: properties: function: @@ -213,7 +221,9 @@ patternProperties: then: properties: groups: - enum: [spi0, spi0_wp_hold, spi1_0, spi1_1, spi1_2, spi1_3] + items: + enum: [spi0, spi0_wp_hold, spi1_0, spi1_1, spi1_2, spi1_3] + maxItems: 2 - if: properties: function: @@ -221,8 +231,12 @@ patternProperties: then: properties: groups: - enum: [uart1_0, uart1_1, uart1_2, uart1_3_rx_tx, - uart1_3_cts_rts, uart2_0, uart2_1, uart0, uart1, uart2] + items: + enum: [uart1_0, uart1_rx_tx, uart1_cts_rts, uart1_1, + uart1_2_rx_tx, uart1_2_cts_rts, uart1_3_rx_tx, + uart1_3_cts_rts, uart2_0_rx_tx, uart2_0_cts_rts, + uart2_1, uart0, uart1, uart2] + maxItems: 2 - if: properties: function: @@ -278,9 +292,23 @@ patternProperties: bias-disable: true - bias-pull-up: true - - bias-pull-down: 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 @@ -332,6 +360,7 @@ 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>; @@ -356,6 +385,27 @@ examples: interrupt-parent = <&gic>; #interrupt-cells = <2>; + pcie_pins: pcie-pins { + mux { + function = "pcie"; + groups = "pcie_clk", "pcie_wake", "pcie_pereset"; + }; + }; + + pwm_pins: pwm-pins { + mux { + function = "pwm"; + groups = "pwm0", "pwm1_0"; + }; + }; + + spi0_pins: spi0-pins { + mux { + function = "spi"; + groups = "spi0", "spi0_wp_hold"; + }; + }; + uart1_pins: uart1-pins { mux { function = "uart"; @@ -363,6 +413,13 @@ examples: }; }; + uart1_3_pins: uart1-3-pins { + mux { + function = "uart"; + groups = "uart1_3_rx_tx", "uart1_3_cts_rts"; + }; + }; + uart2_pins: uart2-pins { mux { function = "uart"; @@ -370,5 +427,34 @@ examples: }; }; + mmc0_pins_default: mmc0-pins { + mux { + function = "emmc"; + groups = "emmc_51"; + }; + conf-cmd-dat { + pins = "EMMC_DATA_0", "EMMC_DATA_1", "EMMC_DATA_2", + "EMMC_DATA_3", "EMMC_DATA_4", "EMMC_DATA_5", + "EMMC_DATA_6", "EMMC_DATA_7", "EMMC_CMD"; + input-enable; + drive-strength = <4>; + bias-pull-up = <MTK_PUPD_SET_R1R0_01>; /* pull-up 10K */ + }; + conf-clk { + pins = "EMMC_CK"; + drive-strength = <6>; + bias-pull-down = <MTK_PUPD_SET_R1R0_10>; /* pull-down 50K */ + }; + conf-ds { + pins = "EMMC_DSL"; + bias-pull-down = <MTK_PUPD_SET_R1R0_10>; /* pull-down 50K */ + }; + conf-rst { + pins = "EMMC_RSTB"; + drive-strength = <4>; + bias-pull-up = <MTK_PUPD_SET_R1R0_01>; /* pull-up 10K */ + }; + }; + }; }; diff --git a/Documentation/devicetree/bindings/pinctrl/mediatek,pinctrl-mt6795.yaml b/Documentation/devicetree/bindings/pinctrl/mediatek,pinctrl-mt6795.yaml index 73ae6e11410b..9399e0215526 100644 --- a/Documentation/devicetree/bindings/pinctrl/mediatek,pinctrl-mt6795.yaml +++ b/Documentation/devicetree/bindings/pinctrl/mediatek,pinctrl-mt6795.yaml @@ -46,8 +46,11 @@ properties: const: 2 interrupts: - description: The interrupt outputs to sysirq. - maxItems: 1 + description: Interrupt outputs to the system interrupt controller (sysirq). + minItems: 1 + items: + - description: EINT interrupt + - description: EINT event_b interrupt # PIN CONFIGURATION NODES patternProperties: diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra-pinmux-common.yaml b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra-pinmux-common.yaml new file mode 100644 index 000000000000..96c608bcb87e --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra-pinmux-common.yaml @@ -0,0 +1,178 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/nvidia,tegra-pinmux-common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra Pinmux Controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jonathan Hunter <jonathanh@nvidia.com> + +description: | + Please refer to pinctrl-bindings.txt in this directory for details of the + common pinctrl bindings used by client devices, including the meaning of + the phrase "pin configuration node". + + Tegra's pin configuration nodes act as a container for an arbitrary number + of subnodes. Each of these subnodes represents some desired configuration + for a pin, a group, or a list of pins or groups. This configuration can + include the mux function to select on those pin(s)/ group(s), and various + pin configuration parameters, such as pull-up, tristate, drive strength, + etc. + + The name of each subnode is not important; all subnodes should be + enumerated and processed purely based on their content. + + Each subnode only affects those parameters that are explicitly listed. In + other words, a subnode that lists a mux function but no pin configuration + parameters implies no information about any pin configuration parameters. + + Similarly, a pin subnode that describes a pullup parameter implies no + information about e.g. the mux function or tristate parameter. For this + reason, even seemingly boolean values are actually tristates in this + binding: unspecified, off, or on. Unspecified is represented as an absent + property, and off/on are represented as integer values 0 and 1. + + Note that many of these properties are only valid for certain specific pins + or groups. See the Tegra TRM and various pinmux spreadsheets for complete + details regarding which groups support which functionality. The Linux + pinctrl driver may also be a useful reference, since it consolidates, + disambiguates, and corrects data from all those sources. + +properties: + nvidia,pins: + $ref: /schemas/types.yaml#/definitions/string-array + description: An array of strings. Each string contains the name of a pin + or group. Valid values for these names are listed below. + + nvidia,function: + $ref: /schemas/types.yaml#/definitions/string + description: A string containing the name of the function to mux to the + pin or group. Valid values for function names are listed below. See the + Tegra TRM to determine which are valid for each pin or group. + + nvidia,pull: + description: Pull-down/up setting to apply to the pin. + $ref: /schemas/types.yaml#/definitions/uint32 + oneOf: + - description: none + const: 0 + - description: down + const: 1 + - description: up + const: 2 + + nvidia,tristate: + description: Tristate setting to apply to the pin. + $ref: /schemas/types.yaml#/definitions/uint32 + oneOf: + - description: drive + const: 0 + - description: tristate + const: 1 + + nvidia,schmitt: + description: Enable Schmitt trigger on the input. + $ref: /schemas/types.yaml#/definitions/uint32 + oneOf: + - description: disable Schmitt trigger on the input + const: 0 + - description: enable Schmitt trigger on the input + const: 1 + + nvidia,pull-down-strength: + description: Controls drive strength. 0 is weakest. The range of valid + values depends on the pingroup. See "CAL_DRVDN" in the Tegra TRM. + $ref: /schemas/types.yaml#/definitions/uint32 + + nvidia,pull-up-strength: + description: Controls drive strength. 0 is weakest. The range of valid + values depends on the pingroup. See "CAL_DRVUP" in the Tegra TRM. + $ref: /schemas/types.yaml#/definitions/uint32 + + nvidia,high-speed-mode: + description: Enable high speed mode the pins. + $ref: /schemas/types.yaml#/definitions/uint32 + oneOf: + - description: normal speed mode + const: 0 + - description: high speed mode + const: 1 + + nvidia,low-power-mode: + description: Controls the drive power or current. Valid values are from 0 + through 3, where 0 specifies the least power and 3 specifies the most + power. See "Low Power Mode" or "LPMD1" and "LPMD0" in the Tegra TRM. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1, 2, 3 ] + + nvidia,enable-input: + description: Enable the pin's input path. + $ref: /schemas/types.yaml#/definitions/uint32 + oneOf: + - description: disable input (i.e. output only) + const: 0 + - description: enable input + const: 1 + + nvidia,open-drain: + description: Open-drain configuration for the pin. + $ref: /schemas/types.yaml#/definitions/uint32 + oneOf: + - description: disable open-drain + const: 0 + - description: enable open-drain + const: 1 + + nvidia,lock: + description: Lock the pin configuration against further changes until + reset. + $ref: /schemas/types.yaml#/definitions/uint32 + oneOf: + - description: disable pin configuration lock + const: 0 + - description: enable pin configuration lock + const: 1 + + nvidia,io-reset: + description: reset the I/O path + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1 ] + + nvidia,rcv-sel: + description: select VIL/VIH receivers + $ref: /schemas/types.yaml#/definitions/uint32 + oneOf: + - description: normal receivers + const: 0 + - description: high-voltage receivers + const: 1 + + nvidia,drive-type: + description: Drive type to configure for the pin. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1, 2, 3 ] + + nvidia,io-hv: + description: Select high-voltage receivers. + $ref: /schemas/types.yaml#/definitions/uint32 + oneOf: + - description: Use normal receivers. + const: 0 + - description: Use high-voltage receivers. + const: 1 + + nvidia,slew-rate-rising: + description: Controls rising signal slew rate. 0 is fastest. The range of + valid values depends on the pingroup. See "DRVDN_SLWR" in the Tegra TRM. + $ref: /schemas/types.yaml#/definitions/uint32 + + nvidia,slew-rate-falling: + description: Controls falling signal slew rate. 0 is fastest. The range of + valid values depends on the pingroup. See "DRVUP_SLWF" in the Tegra TRM. + $ref: /schemas/types.yaml#/definitions/uint32 + +additionalProperties: true +... diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra114-pinmux.txt b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra114-pinmux.txt deleted file mode 100644 index fb70856c5b51..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra114-pinmux.txt +++ /dev/null @@ -1,131 +0,0 @@ -NVIDIA Tegra114 pinmux controller - -The Tegra114 pinctrl binding is very similar to the Tegra20 and Tegra30 -pinctrl binding, as described in nvidia,tegra20-pinmux.txt and -nvidia,tegra30-pinmux.txt. In fact, this document assumes that binding as -a baseline, and only documents the differences between the two bindings. - -Required properties: -- compatible: "nvidia,tegra114-pinmux" -- reg: Should contain the register physical address and length for each of - the pad control and mux registers. The first bank of address must be the - driver strength pad control register address and second bank address must - be pinmux register address. - -Tegra114 adds the following optional properties for pin configuration subnodes: -- nvidia,enable-input: Integer. Enable the pin's input path. 0: no, 1: yes. -- nvidia,open-drain: Integer. Enable open drain mode. 0: no, 1: yes. -- nvidia,lock: Integer. Lock the pin configuration against further changes - until reset. 0: no, 1: yes. -- nvidia,io-reset: Integer. Reset the IO path. 0: no, 1: yes. -- nvidia,rcv-sel: Integer. Select VIL/VIH receivers. 0: normal, 1: high. -- nvidia,drive-type: Integer. Valid range 0...3. - -As with Tegra20 and Terga30, see the Tegra TRM for complete details regarding -which groups support which functionality. - -Valid values for pin and group names are: - - per-pin mux groups: - - These all support nvidia,function, nvidia,tristate, nvidia,pull, - nvidia,enable-input, nvidia,lock. Some support nvidia,open-drain, - nvidia,io-reset and nvidia,rcv-sel. - - ulpi_data0_po1, ulpi_data1_po2, ulpi_data2_po3, ulpi_data3_po4, - ulpi_data4_po5, ulpi_data5_po6, ulpi_data6_po7, ulpi_data7_po0, - ulpi_clk_py0, ulpi_dir_py1, ulpi_nxt_py2, ulpi_stp_py3, dap3_fs_pp0, - dap3_din_pp1, dap3_dout_pp2, dap3_sclk_pp3, pv0, pv1, sdmmc1_clk_pz0, - sdmmc1_cmd_pz1, sdmmc1_dat3_py4, sdmmc1_dat2_py5, sdmmc1_dat1_py6, - sdmmc1_dat0_py7, clk2_out_pw5, clk2_req_pcc5, hdmi_int_pn7, ddc_scl_pv4, - ddc_sda_pv5, uart2_rxd_pc3, uart2_txd_pc2, uart2_rts_n_pj6, - uart2_cts_n_pj5, uart3_txd_pw6, uart3_rxd_pw7, uart3_cts_n_pa1, - uart3_rts_n_pc0, pu0, pu1, pu2, pu3, pu4, pu5, pu6, gen1_i2c_sda_pc5, - gen1_i2c_scl_pc4, dap4_fs_pp4, dap4_din_pp5, dap4_dout_pp6, dap4_sclk_pp7, - clk3_out_pee0, clk3_req_pee1, gmi_wp_n_pc7, gmi_iordy_pi5, gmi_wait_pi7, - gmi_adv_n_pk0, gmi_clk_pk1, gmi_cs0_n_pj0, gmi_cs1_n_pj2, gmi_cs2_n_pk3, - gmi_cs3_n_pk4, gmi_cs4_n_pk2, gmi_cs6_n_pi3, gmi_cs7_n_pi6, gmi_ad0_pg0, - gmi_ad1_pg1, gmi_ad2_pg2, gmi_ad3_pg3, gmi_ad4_pg4, gmi_ad5_pg5, - gmi_ad6_pg6, gmi_ad7_pg7, gmi_ad8_ph0, gmi_ad9_ph1, gmi_ad10_ph2, - gmi_ad11_ph3, gmi_ad12_ph4, gmi_ad13_ph5, gmi_ad14_ph6, gmi_ad15_ph7, - gmi_a16_pj7, gmi_a17_pb0, gmi_a18_pb1, gmi_a19_pk7, gmi_wr_n_pi0, - gmi_oe_n_pi1, gmi_dqs_p_pj3, gmi_rst_n_pi4, gen2_i2c_scl_pt5, - gen2_i2c_sda_pt6, sdmmc4_clk_pcc4, sdmmc4_cmd_pt7, sdmmc4_dat0_paa0, - sdmmc4_dat1_paa1, sdmmc4_dat2_paa2, sdmmc4_dat3_paa3, sdmmc4_dat4_paa4, - sdmmc4_dat5_paa5, sdmmc4_dat6_paa6, sdmmc4_dat7_paa7, cam_mclk_pcc0, - pcc1, pbb0, cam_i2c_scl_pbb1, cam_i2c_sda_pbb2, pbb3, pbb4, pbb5, pbb6, - pbb7, pcc2, pwr_i2c_scl_pz6, pwr_i2c_sda_pz7, kb_row0_pr0, kb_row1_pr1, - kb_row2_pr2, kb_row3_pr3, kb_row4_pr4, kb_row5_pr5, kb_row6_pr6, - kb_row7_pr7, kb_row8_ps0, kb_row9_ps1, kb_row10_ps2, kb_col0_pq0, - kb_col1_pq1, kb_col2_pq2, kb_col3_pq3, kb_col4_pq4, kb_col5_pq5, - kb_col6_pq6, kb_col7_pq7, clk_32k_out_pa0, sys_clk_req_pz5, core_pwr_req, - cpu_pwr_req, pwr_int_n, owr, dap1_fs_pn0, dap1_din_pn1, dap1_dout_pn2, - dap1_sclk_pn3, clk1_req_pee2, clk1_out_pw4, spdif_in_pk6, spdif_out_pk5, - dap2_fs_pa2, dap2_din_pa4, dap2_dout_pa5, dap2_sclk_pa3, dvfs_pwm_px0, - gpio_x1_aud_px1, gpio_x3_aud_px3, dvfs_clk_px2, gpio_x4_aud_px4, - gpio_x5_aud_px5, gpio_x6_aud_px6, gpio_x7_aud_px7, sdmmc3_clk_pa6, - sdmmc3_cmd_pa7, sdmmc3_dat0_pb7, sdmmc3_dat1_pb6, sdmmc3_dat2_pb5, - sdmmc3_dat3_pb4, hdmi_cec_pee3, sdmmc1_wp_n_pv3, sdmmc3_cd_n_pv2, - gpio_w2_aud_pw2, gpio_w3_aud_pw3, usb_vbus_en0_pn4, usb_vbus_en1_pn5, - sdmmc3_clk_lb_in_pee5, sdmmc3_clk_lb_out_pee4, reset_out_n. - - drive groups: - - These all support nvidia,pull-down-strength, nvidia,pull-up-strength, - nvidia,slew-rate-rising, nvidia,slew-rate-falling. Most but not all - support nvidia,high-speed-mode, nvidia,schmitt, nvidia,low-power-mode - and nvidia,drive-type. - - ao1, ao2, at1, at2, at3, at4, at5, cdev1, cdev2, dap1, dap2, dap3, dap4, - dbg, sdio3, spi, uaa, uab, uart2, uart3, sdio1, ddc, gma, gme, gmf, gmg, - gmh, owr, uda. - -Valid values for nvidia,functions are: - - blink, cec, cldvfs, clk12, cpu, dap, dap1, dap2, dev3, displaya, - displaya_alt, displayb, dtv, emc_dll, extperiph1, extperiph2, - extperiph3, gmi, gmi_alt, hda, hsi, i2c1, i2c2, i2c3, i2c4, i2cpwr, - i2s0, i2s1, i2s2, i2s3, i2s4, irda, kbc, nand, nand_alt, owr, pmi, - pwm0, pwm1, pwm2, pwm3, pwron, reset_out_n, rsvd1, rsvd2, rsvd3, - rsvd4, sdmmc1, sdmmc2, sdmmc3, sdmmc4, soc, spdif, spi1, spi2, spi3, - spi4, spi5, spi6, sysclk, trace, uarta, uartb, uartc, uartd, ulpi, - usb, vgp1, vgp2, vgp3, vgp4, vgp5, vgp6, vi, vi_alt1, vi_alt3 - -Example: - - pinmux: pinmux { - compatible = "nvidia,tegra114-pinmux"; - reg = <0x70000868 0x148 /* Pad control registers */ - 0x70003000 0x40c>; /* PinMux registers */ - }; - -Example board file extract: - - pinctrl { - sdmmc4_default: pinmux { - sdmmc4_clk_pcc4 { - nvidia,pins = "sdmmc4_clk_pcc4", - nvidia,function = "sdmmc4"; - nvidia,pull = <0>; - nvidia,tristate = <0>; - }; - sdmmc4_dat0_paa0 { - nvidia,pins = "sdmmc4_dat0_paa0", - "sdmmc4_dat1_paa1", - "sdmmc4_dat2_paa2", - "sdmmc4_dat3_paa3", - "sdmmc4_dat4_paa4", - "sdmmc4_dat5_paa5", - "sdmmc4_dat6_paa6", - "sdmmc4_dat7_paa7"; - nvidia,function = "sdmmc4"; - nvidia,pull = <2>; - nvidia,tristate = <0>; - }; - }; - }; - - sdhci@78000400 { - pinctrl-names = "default"; - pinctrl-0 = <&sdmmc4_default>; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra114-pinmux.yaml b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra114-pinmux.yaml new file mode 100644 index 000000000000..065dedb3573a --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra114-pinmux.yaml @@ -0,0 +1,155 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/nvidia,tegra114-pinmux.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra114 pinmux Controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + const: nvidia,tegra114-pinmux + + reg: + items: + - description: pad control registers + - description: mux registers + +patternProperties: + "^pinmux(-[a-z0-9-_]+)?$": + type: object + properties: + phandle: true + + # pin groups + additionalProperties: + $ref: nvidia,tegra-pinmux-common.yaml + additionalProperties: false + properties: + nvidia,pins: + items: + enum: [ ulpi_data0_po1, ulpi_data1_po2, ulpi_data2_po3, + ulpi_data3_po4, ulpi_data4_po5, ulpi_data5_po6, + ulpi_data6_po7, ulpi_data7_po0, ulpi_clk_py0, ulpi_dir_py1, + ulpi_nxt_py2, ulpi_stp_py3, dap3_fs_pp0, dap3_din_pp1, + dap3_dout_pp2, dap3_sclk_pp3, pv0, pv1, sdmmc1_clk_pz0, + sdmmc1_cmd_pz1, sdmmc1_dat3_py4, sdmmc1_dat2_py5, + sdmmc1_dat1_py6, sdmmc1_dat0_py7, clk2_out_pw5, + clk2_req_pcc5, hdmi_int_pn7, ddc_scl_pv4, ddc_sda_pv5, + uart2_rxd_pc3, uart2_txd_pc2, uart2_rts_n_pj6, + uart2_cts_n_pj5, uart3_txd_pw6, uart3_rxd_pw7, + uart3_cts_n_pa1, uart3_rts_n_pc0, pu0, pu1, pu2, pu3, pu4, + pu5, pu6, gen1_i2c_sda_pc5, gen1_i2c_scl_pc4, dap4_fs_pp4, + dap4_din_pp5, dap4_dout_pp6, dap4_sclk_pp7, clk3_out_pee0, + clk3_req_pee1, gmi_wp_n_pc7, gmi_iordy_pi5, gmi_wait_pi7, + gmi_adv_n_pk0, gmi_clk_pk1, gmi_cs0_n_pj0, gmi_cs1_n_pj2, + gmi_cs2_n_pk3, gmi_cs3_n_pk4, gmi_cs4_n_pk2, gmi_cs6_n_pi3, + gmi_cs7_n_pi6, gmi_ad0_pg0, gmi_ad1_pg1, gmi_ad2_pg2, + gmi_ad3_pg3, gmi_ad4_pg4, gmi_ad5_pg5, gmi_ad6_pg6, + gmi_ad7_pg7, gmi_ad8_ph0, gmi_ad9_ph1, gmi_ad10_ph2, + gmi_ad11_ph3, gmi_ad12_ph4, gmi_ad13_ph5, gmi_ad14_ph6, + gmi_ad15_ph7, gmi_a16_pj7, gmi_a17_pb0, gmi_a18_pb1, + gmi_a19_pk7, gmi_wr_n_pi0, gmi_oe_n_pi1, gmi_dqs_p_pj3, + gmi_rst_n_pi4, gen2_i2c_scl_pt5, gen2_i2c_sda_pt6, + sdmmc4_clk_pcc4, sdmmc4_cmd_pt7, sdmmc4_dat0_paa0, + sdmmc4_dat1_paa1, sdmmc4_dat2_paa2, sdmmc4_dat3_paa3, + sdmmc4_dat4_paa4, sdmmc4_dat5_paa5, sdmmc4_dat6_paa6, + sdmmc4_dat7_paa7, cam_mclk_pcc0, pcc1, pbb0, + cam_i2c_scl_pbb1, cam_i2c_sda_pbb2, pbb3, pbb4, pbb5, pbb6, + pbb7, pcc2, pwr_i2c_scl_pz6, pwr_i2c_sda_pz7, kb_row0_pr0, + kb_row1_pr1, kb_row2_pr2, kb_row3_pr3, kb_row4_pr4, + kb_row5_pr5, kb_row6_pr6, kb_row7_pr7, kb_row8_ps0, + kb_row9_ps1, kb_row10_ps2, kb_col0_pq0, kb_col1_pq1, + kb_col2_pq2, kb_col3_pq3, kb_col4_pq4, kb_col5_pq5, + kb_col6_pq6, kb_col7_pq7, clk_32k_out_pa0, sys_clk_req_pz5, + core_pwr_req, cpu_pwr_req, pwr_int_n, owr, dap1_fs_pn0, + dap1_din_pn1, dap1_dout_pn2, dap1_sclk_pn3, clk1_req_pee2, + clk1_out_pw4, spdif_in_pk6, spdif_out_pk5, dap2_fs_pa2, + dap2_din_pa4, dap2_dout_pa5, dap2_sclk_pa3, dvfs_pwm_px0, + gpio_x1_aud_px1, gpio_x3_aud_px3, dvfs_clk_px2, + gpio_x4_aud_px4, gpio_x5_aud_px5, gpio_x6_aud_px6, + gpio_x7_aud_px7, sdmmc3_clk_pa6, sdmmc3_cmd_pa7, + sdmmc3_dat0_pb7, sdmmc3_dat1_pb6, sdmmc3_dat2_pb5, + sdmmc3_dat3_pb4, hdmi_cec_pee3, sdmmc1_wp_n_pv3, + sdmmc3_cd_n_pv2, gpio_w2_aud_pw2, gpio_w3_aud_pw3, + usb_vbus_en0_pn4, usb_vbus_en1_pn5, sdmmc3_clk_lb_in_pee5, + sdmmc3_clk_lb_out_pee4, reset_out_n, + # drive groups + drive_ao1, drive_ao2, drive_at1, drive_at2, drive_at3, + drive_at4, drive_at5, drive_cdev1, drive_cdev2, drive_dap1, + drive_dap2, drive_dap3, drive_dap4, drive_dbg, drive_sdio3, + drive_spi, drive_uaa, drive_uab, drive_uart2, drive_uart3, + drive_sdio1, drive_ddc, drive_gma, drive_gme, drive_gmf, + drive_gmg, drive_gmh, drive_owr, drive_uda ] + + nvidia,function: + enum: [ blink, cec, cldvfs, clk12, cpu, dap, dap1, dap2, dev3, + displaya, displaya_alt, displayb, dtv, emc_dll, extperiph1, + extperiph2, extperiph3, gmi, gmi_alt, hda, hsi, i2c1, i2c2, + i2c3, i2c4, i2cpwr, i2s0, i2s1, i2s2, i2s3, i2s4, irda, kbc, + nand, nand_alt, owr, pmi, pwm0, pwm1, pwm2, pwm3, pwron, + reset_out_n, rsvd1, rsvd2, rsvd3, rsvd4, sdmmc1, sdmmc2, + sdmmc3, sdmmc4, soc, spdif, spi1, spi2, spi3, spi4, spi5, + spi6, sysclk, trace, uarta, uartb, uartc, uartd, ulpi, usb, + vgp1, vgp2, vgp3, vgp4, vgp5, vgp6, vi, vi_alt1, vi_alt3 ] + + nvidia,pull: true + nvidia,tristate: true + nvidia,schmitt: true + nvidia,pull-down-strength: true + nvidia,pull-up-strength: true + nvidia,high-speed-mode: true + nvidia,low-power-mode: true + nvidia,enable-input: true + nvidia,open-drain: true + nvidia,lock: true + nvidia,io-reset: true + nvidia,rcv-sel: true + nvidia,drive-type: true + nvidia,slew-rate-rising: true + nvidia,slew-rate-falling: true + + required: + - nvidia,pins + +additionalProperties: false + +required: + - compatible + - reg + +examples: + - | + pinmux@70000868 { + compatible = "nvidia,tegra114-pinmux"; + reg = <0x70000868 0x148>, /* Pad control registers */ + <0x70003000 0x40c>; /* PinMux registers */ + + pinmux { + sdmmc4_clk_pcc4 { + nvidia,pins = "sdmmc4_clk_pcc4"; + nvidia,function = "sdmmc4"; + nvidia,pull = <0>; + nvidia,tristate = <0>; + }; + + sdmmc4_dat0_paa0 { + nvidia,pins = "sdmmc4_dat0_paa0", + "sdmmc4_dat1_paa1", + "sdmmc4_dat2_paa2", + "sdmmc4_dat3_paa3", + "sdmmc4_dat4_paa4", + "sdmmc4_dat5_paa5", + "sdmmc4_dat6_paa6", + "sdmmc4_dat7_paa7"; + nvidia,function = "sdmmc4"; + nvidia,pull = <2>; + nvidia,tristate = <0>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.txt b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.txt deleted file mode 100644 index f4d06bb0b55a..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.txt +++ /dev/null @@ -1,153 +0,0 @@ -NVIDIA Tegra124 pinmux controller - -The Tegra124 pinctrl binding is very similar to the Tegra20 and Tegra30 -pinctrl binding, as described in nvidia,tegra20-pinmux.txt and -nvidia,tegra30-pinmux.txt. In fact, this document assumes that binding as -a baseline, and only documents the differences between the two bindings. - -Required properties: -- compatible: For Tegra124, must contain "nvidia,tegra124-pinmux". For - Tegra132, must contain '"nvidia,tegra132-pinmux", "nvidia-tegra124-pinmux"'. -- reg: Should contain a list of base address and size pairs for: - -- first entry - the drive strength and pad control registers. - -- second entry - the pinmux registers - -- third entry - the MIPI_PAD_CTRL register - -Tegra124 adds the following optional properties for pin configuration subnodes. -The macros for options are defined in the - include/dt-binding/pinctrl/pinctrl-tegra.h. -- nvidia,enable-input: Integer. Enable the pin's input path. - enable :TEGRA_PIN_ENABLE and - disable or output only: TEGRA_PIN_DISABLE. -- nvidia,open-drain: Integer. - enable: TEGRA_PIN_ENABLE. - disable: TEGRA_PIN_DISABLE. -- nvidia,lock: Integer. Lock the pin configuration against further changes - until reset. - enable: TEGRA_PIN_ENABLE. - disable: TEGRA_PIN_DISABLE. -- nvidia,io-reset: Integer. Reset the IO path. - enable: TEGRA_PIN_ENABLE. - disable: TEGRA_PIN_DISABLE. -- nvidia,rcv-sel: Integer. Select VIL/VIH receivers. - normal: TEGRA_PIN_DISABLE - high: TEGRA_PIN_ENABLE - -Please refer the Tegra TRM for complete details regarding which groups -support which functionality. - -Valid values for pin and group names are: - - per-pin mux groups: - - These all support nvidia,function, nvidia,tristate, nvidia,pull, - nvidia,enable-input. Some support nvidia,lock nvidia,open-drain, - nvidia,io-reset and nvidia,rcv-sel. - - ulpi_data0_po1, ulpi_data1_po2, ulpi_data2_po3, ulpi_data3_po4, - ulpi_data4_po5, ulpi_data5_po6, ulpi_data6_po7, ulpi_data7_po0, - ulpi_clk_py0, ulpi_dir_py1, ulpi_nxt_py2, ulpi_stp_py3, dap3_fs_pp0, - dap3_din_pp1, dap3_dout_pp2, dap3_sclk_pp3, pv0, pv1, sdmmc1_clk_pz0, - sdmmc1_cmd_pz1, sdmmc1_dat3_py4, sdmmc1_dat2_py5, sdmmc1_dat1_py6, - sdmmc1_dat0_py7, clk2_out_pw5, clk2_req_pcc5, hdmi_int_pn7, ddc_scl_pv4, - ddc_sda_pv5, uart2_rxd_pc3, uart2_txd_pc2, uart2_rts_n_pj6, - uart2_cts_n_pj5, uart3_txd_pw6, uart3_rxd_pw7, uart3_cts_n_pa1, - uart3_rts_n_pc0, pu0, pu1, pu2, pu3, pu4, pu5, pu6, gen1_i2c_scl_pc4, - gen1_i2c_sda_pc5, dap4_fs_pp4, dap4_din_pp5, dap4_dout_pp6, - dap4_sclk_pp7, clk3_out_pee0, clk3_req_pee1, pc7, pi5, pi7, pk0, pk1, - pj0, pj2, pk3, pk4, pk2, pi3, pi6, pg0, pg1, pg2, pg3, pg4, pg5, pg6, - pg7, ph0, ph1, ph2, ph3, ph4, ph5, ph6, ph7, pj7, pb0, pb1, pk7, pi0, - pi1, pi2, pi4, gen2_i2c_scl_pt5, gen2_i2c_sda_pt6, sdmmc4_clk_pcc4, - sdmmc4_cmd_pt7, sdmmc4_dat0_paa0, sdmmc4_dat1_paa1, sdmmc4_dat2_paa2, - sdmmc4_dat3_paa3, sdmmc4_dat4_paa4, sdmmc4_dat5_paa5, sdmmc4_dat6_paa6, - sdmmc4_dat7_paa7, cam_mclk_pcc0, pcc1, pbb0, cam_i2c_scl_pbb1, - cam_i2c_sda_pbb2, pbb3, pbb4, pbb5, pbb6, pbb7, pcc2, jtag_rtck, - pwr_i2c_scl_pz6, pwr_i2c_sda_pz7, kb_row0_pr0, kb_row1_pr1, kb_row2_pr2, - kb_row3_pr3, kb_row4_pr4, kb_row5_pr5, kb_row6_pr6, kb_row7_pr7, - kb_row8_ps0, kb_row9_ps1, kb_row10_ps2, kb_row11_ps3, kb_row12_ps4, - kb_row13_ps5, kb_row14_ps6, kb_row15_ps7, kb_col0_pq0, kb_col1_pq1, - kb_col2_pq2, kb_col3_pq3, kb_col4_pq4, kb_col5_pq5, kb_col6_pq6, - kb_col7_pq7, clk_32k_out_pa0, core_pwr_req, cpu_pwr_req, pwr_int_n, - clk_32k_in, owr, dap1_fs_pn0, dap1_din_pn1, dap1_dout_pn2, - dap1_sclk_pn3, dap_mclk1_req_pee2, dap_mclk1_pw4, spdif_in_pk6, - spdif_out_pk5, dap2_fs_pa2, dap2_din_pa4, dap2_dout_pa5, dap2_sclk_pa3, - dvfs_pwm_px0, gpio_x1_aud_px1, gpio_x3_aud_px3, dvfs_clk_px2, - gpio_x4_aud_px4, gpio_x5_aud_px5, gpio_x6_aud_px6, gpio_x7_aud_px7, - sdmmc3_clk_pa6, sdmmc3_cmd_pa7, sdmmc3_dat0_pb7, sdmmc3_dat1_pb6, - sdmmc3_dat2_pb5, sdmmc3_dat3_pb4, pex_l0_rst_n_pdd1, - pex_l0_clkreq_n_pdd2, pex_wake_n_pdd3, pex_l1_rst_n_pdd5, - pex_l1_clkreq_n_pdd6, hdmi_cec_pee3, sdmmc1_wp_n_pv3, - sdmmc3_cd_n_pv2, gpio_w2_aud_pw2, gpio_w3_aud_pw3, usb_vbus_en0_pn4, - usb_vbus_en1_pn5, sdmmc3_clk_lb_out_pee4, sdmmc3_clk_lb_in_pee5, - gmi_clk_lb, reset_out_n, kb_row16_pt0, kb_row17_pt1, usb_vbus_en2_pff1, - pff2, dp_hpd_pff0, - - drive groups: - - These all support nvidia,pull-down-strength, nvidia,pull-up-strength, - nvidia,slew-rate-rising, nvidia,slew-rate-falling. Most but not all - support nvidia,high-speed-mode, nvidia,schmitt, nvidia,low-power-mode - and nvidia,drive-type. - - ao1, ao2, at1, at2, at3, at4, at5, cdev1, cdev2, dap1, dap2, dap3, dap4, - dbg, sdio3, spi, uaa, uab, uart2, uart3, sdio1, ddc, gma, gme, gmf, gmg, - gmh, owr, uda, gpv, dev3, cec, usb_vbus_en, ao3, ao0, hv0, sdio4, ao4. - - MIPI pad control groups: - - These support only the nvidia,function property. - - dsi_b - -Valid values for nvidia,functions are: - - blink, cec, cldvfs, clk12, cpu, dap, dap1, dap2, dev3, displaya, - displaya_alt, displayb, dtv, extperiph1, extperiph2, extperiph3, - gmi, gmi_alt, hda, hsi, i2c1, i2c2, i2c3, i2c4, i2cpwr, i2s0, - i2s1, i2s2, i2s3, i2s4, irda, kbc, owr, pmi, pwm0, pwm1, pwm2, pwm3, - pwron, reset_out_n, rsvd1, rsvd2, rsvd3, rsvd4, sdmmc1, sdmmc2, sdmmc3, - sdmmc4, soc, spdif, spi1, spi2, spi3, spi4, spi5, spi6, trace, uarta, - uartb, uartc, uartd, ulpi, usb, vgp1, vgp2, vgp3, vgp4, vgp5, vgp6, - vi, vi_alt1, vi_alt3, vimclk2, vimclk2_alt, sata, ccla, pe0, pe, pe1, - dp, rtck, sys, clk tmds, csi, dsi_b - -Example: - - pinmux: pinmux { - compatible = "nvidia,tegra124-pinmux"; - reg = <0x0 0x70000868 0x0 0x164>, /* Pad control registers */ - <0x0 0x70003000 0x0 0x434>, /* Mux registers */ - <0x0 0x70000820 0x0 0x8>; /* MIPI pad control */ - }; - -Example pinmux entries: - - pinctrl { - sdmmc4_default: pinmux { - sdmmc4_clk_pcc4 { - nvidia,pins = "sdmmc4_clk_pcc4", - nvidia,function = "sdmmc4"; - nvidia,pull = <TEGRA_PIN_PULL_NONE>; - nvidia,tristate = <TEGRA_PIN_DISABLE>; - }; - - sdmmc4_dat0_paa0 { - nvidia,pins = "sdmmc4_dat0_paa0", - "sdmmc4_dat1_paa1", - "sdmmc4_dat2_paa2", - "sdmmc4_dat3_paa3", - "sdmmc4_dat4_paa4", - "sdmmc4_dat5_paa5", - "sdmmc4_dat6_paa6", - "sdmmc4_dat7_paa7"; - nvidia,function = "sdmmc4"; - nvidia,pull = <TEGRA_PIN_PULL_UP>; - nvidia,tristate = <TEGRA_PIN_DISABLE>; - }; - }; - }; - - sdhci@78000400 { - pinctrl-names = "default"; - pinctrl-0 = <&sdmmc4_default>; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.yaml b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.yaml new file mode 100644 index 000000000000..f924652bef0d --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.yaml @@ -0,0 +1,176 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/nvidia,tegra124-pinmux.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra124 Pinmux Controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +description: The Tegra124 pinctrl binding is very similar to the Tegra20 and + Tegra30 pinctrl binding, as described in nvidia,tegra20-pinmux.yaml and + nvidia,tegra30-pinmux.yaml. In fact, this document assumes that binding as a + baseline, and only documents the differences between the two bindings. + +properties: + compatible: + oneOf: + - const: nvidia,tegra124-pinmux + - items: + - const: nvidia,tegra132-pinmux + - const: nvidia,tegra124-pinmux + + reg: + items: + - description: driver strength and pad control registers + - description: pinmux registers + - description: MIPI_PAD_CTRL registers + +patternProperties: + "^pinmux(-[a-z0-9-_]+)?$": + type: object + properties: + phandle: true + + # pin groups + additionalProperties: + $ref: nvidia,tegra-pinmux-common.yaml + additionalProperties: false + properties: + nvidia,pins: + $ref: /schemas/types.yaml#/definitions/string-array + items: + enum: [ ulpi_data0_po1, ulpi_data1_po2, ulpi_data2_po3, + ulpi_data3_po4, ulpi_data4_po5, ulpi_data5_po6, + ulpi_data6_po7, ulpi_data7_po0, ulpi_clk_py0, ulpi_dir_py1, + ulpi_nxt_py2, ulpi_stp_py3, dap3_fs_pp0, dap3_din_pp1, + dap3_dout_pp2, dap3_sclk_pp3, pv0, pv1, sdmmc1_clk_pz0, + sdmmc1_cmd_pz1, sdmmc1_dat3_py4, sdmmc1_dat2_py5, + sdmmc1_dat1_py6, sdmmc1_dat0_py7, clk2_out_pw5, + clk2_req_pcc5, hdmi_int_pn7, ddc_scl_pv4, ddc_sda_pv5, + uart2_rxd_pc3, uart2_txd_pc2, uart2_rts_n_pj6, + uart2_cts_n_pj5, uart3_txd_pw6, uart3_rxd_pw7, + uart3_cts_n_pa1, uart3_rts_n_pc0, pu0, pu1, pu2, pu3, pu4, + pu5, pu6, gen1_i2c_scl_pc4, gen1_i2c_sda_pc5, dap4_fs_pp4, + dap4_din_pp5, dap4_dout_pp6, dap4_sclk_pp7, clk3_out_pee0, + clk3_req_pee1, pc7, pi5, pi7, pk0, pk1, pj0, pj2, pk3, pk4, + pk2, pi3, pi6, pg0, pg1, pg2, pg3, pg4, pg5, pg6, pg7, ph0, + ph1, ph2, ph3, ph4, ph5, ph6, ph7, pj7, pb0, pb1, pk7, pi0, + pi1, pi2, pi4, gen2_i2c_scl_pt5, gen2_i2c_sda_pt6, + sdmmc4_clk_pcc4, sdmmc4_cmd_pt7, sdmmc4_dat0_paa0, + sdmmc4_dat1_paa1, sdmmc4_dat2_paa2, sdmmc4_dat3_paa3, + sdmmc4_dat4_paa4, sdmmc4_dat5_paa5, sdmmc4_dat6_paa6, + sdmmc4_dat7_paa7, cam_mclk_pcc0, pcc1, pbb0, + cam_i2c_scl_pbb1, cam_i2c_sda_pbb2, pbb3, pbb4, pbb5, pbb6, + pbb7, pcc2, jtag_rtck, pwr_i2c_scl_pz6, pwr_i2c_sda_pz7, + kb_row0_pr0, kb_row1_pr1, kb_row2_pr2, kb_row3_pr3, + kb_row4_pr4, kb_row5_pr5, kb_row6_pr6, kb_row7_pr7, + kb_row8_ps0, kb_row9_ps1, kb_row10_ps2, kb_row11_ps3, + kb_row12_ps4, kb_row13_ps5, kb_row14_ps6, kb_row15_ps7, + kb_col0_pq0, kb_col1_pq1, kb_col2_pq2, kb_col3_pq3, + kb_col4_pq4, kb_col5_pq5, kb_col6_pq6, kb_col7_pq7, + clk_32k_out_pa0, core_pwr_req, cpu_pwr_req, pwr_int_n, + clk_32k_in, owr, dap1_fs_pn0, dap1_din_pn1, dap1_dout_pn2, + dap1_sclk_pn3, dap_mclk1_req_pee2, dap_mclk1_pw4, + spdif_in_pk6, spdif_out_pk5, dap2_fs_pa2, dap2_din_pa4, + dap2_dout_pa5, dap2_sclk_pa3, dvfs_pwm_px0, + gpio_x1_aud_px1, gpio_x3_aud_px3, dvfs_clk_px2, + gpio_x4_aud_px4, gpio_x5_aud_px5, gpio_x6_aud_px6, + gpio_x7_aud_px7, sdmmc3_clk_pa6, sdmmc3_cmd_pa7, + sdmmc3_dat0_pb7, sdmmc3_dat1_pb6, sdmmc3_dat2_pb5, + sdmmc3_dat3_pb4, pex_l0_rst_n_pdd1, pex_l0_clkreq_n_pdd2, + pex_wake_n_pdd3, pex_l1_rst_n_pdd5, pex_l1_clkreq_n_pdd6, + hdmi_cec_pee3, sdmmc1_wp_n_pv3, sdmmc3_cd_n_pv2, + gpio_w2_aud_pw2, gpio_w3_aud_pw3, usb_vbus_en0_pn4, + usb_vbus_en1_pn5, sdmmc3_clk_lb_out_pee4, + sdmmc3_clk_lb_in_pee5, gmi_clk_lb, reset_out_n, + kb_row16_pt0, kb_row17_pt1, usb_vbus_en2_pff1, pff2, + dp_hpd_pff0, + # drive groups + drive_ao1, drive_ao2, drive_at1, drive_at2, drive_at3, + drive_at4, drive_at5, drive_cdev1, drive_cdev2, drive_dap1, + drive_dap2, drive_dap3, drive_dap4, drive_dbg, drive_sdio3, + drive_spi, drive_uaa, drive_uab, drive_uart2, drive_uart3, + drive_sdio1, drive_ddc, drive_gma, drive_gme, drive_gmf, + drive_gmg, drive_gmh, drive_owr, drive_uda, drive_gpv, + drive_dev3, drive_cec, drive_usb_vbus_en, drive_ao3, + drive_ao0, drive_hv0, drive_sdio4, drive_ao4, + # MIPI pad control groups + mipi_pad_ctrl_dsi_b ] + + nvidia,function: + enum: [ blink, cec, cldvfs, clk12, cpu, dap, dap1, dap2, dev3, + displaya, displaya_alt, displayb, dtv, extperiph1, + extperiph2, extperiph3, gmi, gmi_alt, hda, hsi, i2c1, i2c2, + i2c3, i2c4, i2cpwr, i2s0, i2s1, i2s2, i2s3, i2s4, irda, kbc, + owr, pmi, pwm0, pwm1, pwm2, pwm3, pwron, reset_out_n, rsvd1, + rsvd2, rsvd3, rsvd4, sdmmc1, sdmmc2, sdmmc3, sdmmc4, soc, + spdif, spi1, spi2, spi3, spi4, spi5, spi6, trace, uarta, + uartb, uartc, uartd, ulpi, usb, vgp1, vgp2, vgp3, vgp4, vgp5, + vgp6, vi, vi_alt1, vi_alt3, vimclk2, vimclk2_alt, sata, ccla, + pe0, pe, pe1, dp, rtck, sys, clk, tmds, csi, dsi_b ] + + nvidia,pull: true + nvidia,tristate: true + nvidia,schmitt: true + nvidia,pull-down-strength: true + nvidia,pull-up-strength: true + nvidia,high-speed-mode: true + nvidia,low-power-mode: true + nvidia,enable-input: true + nvidia,open-drain: true + nvidia,lock: true + nvidia,io-reset: true + nvidia,rcv-sel: true + nvidia,drive-type: true + nvidia,slew-rate-rising: true + nvidia,slew-rate-falling: true + + required: + - nvidia,pins + +additionalProperties: false + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/clock/tegra124-car.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/pinctrl/pinctrl-tegra.h> + + pinmux@70000868 { + compatible = "nvidia,tegra124-pinmux"; + reg = <0x70000868 0x164>, /* Pad control registers */ + <0x70003000 0x434>, /* Mux registers */ + <0x70000820 0x8>; /* MIPI pad control */ + + sdmmc4_default: pinmux { + sdmmc4_clk_pcc4 { + nvidia,pins = "sdmmc4_clk_pcc4"; + nvidia,function = "sdmmc4"; + nvidia,pull = <TEGRA_PIN_PULL_NONE>; + nvidia,tristate = <TEGRA_PIN_DISABLE>; + }; + + sdmmc4_dat0_paa0 { + nvidia,pins = "sdmmc4_dat0_paa0", + "sdmmc4_dat1_paa1", + "sdmmc4_dat2_paa2", + "sdmmc4_dat3_paa3", + "sdmmc4_dat4_paa4", + "sdmmc4_dat5_paa5", + "sdmmc4_dat6_paa6", + "sdmmc4_dat7_paa7"; + nvidia,function = "sdmmc4"; + nvidia,pull = <TEGRA_PIN_PULL_UP>; + nvidia,tristate = <TEGRA_PIN_DISABLE>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra194-pinmux.txt b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra194-pinmux.txt deleted file mode 100644 index 90d38f710635..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra194-pinmux.txt +++ /dev/null @@ -1,107 +0,0 @@ -NVIDIA Tegra194 pinmux controller - -Required properties: -- compatible: "nvidia,tegra194-pinmux" -- reg: Should contain a list of base address and size pairs for: - - first entry: The APB_MISC_GP_*_PADCTRL registers (pad control) - - second entry: The PINMUX_AUX_* registers (pinmux) - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -Tegra's pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, tristate, drive strength, etc. - -See the TRM to determine which properties and values apply to each pin/group. -Macro values for property values are defined in -include/dt-binding/pinctrl/pinctrl-tegra.h. - -Required subnode-properties: -- nvidia,pins : An array of strings. Each string contains the name of a pin or - group. Valid values for these names are listed below. - -Optional subnode-properties: -- nvidia,function: A string containing the name of the function to mux to the - pin or group. -- nvidia,pull: Integer, representing the pull-down/up to apply to the pin. - 0: none, 1: down, 2: up. -- nvidia,tristate: Integer. - 0: drive, 1: tristate. -- nvidia,enable-input: Integer. Enable the pin's input path. - enable :TEGRA_PIN_ENABLE and - disable or output only: TEGRA_PIN_DISABLE. -- nvidia,open-drain: Integer. - enable: TEGRA_PIN_ENABLE. - disable: TEGRA_PIN_DISABLE. -- nvidia,lock: Integer. Lock the pin configuration against further changes - until reset. - enable: TEGRA_PIN_ENABLE. - disable: TEGRA_PIN_DISABLE. -- nvidia,io-hv: Integer. Select high-voltage receivers. - normal: TEGRA_PIN_DISABLE - high: TEGRA_PIN_ENABLE -- nvidia,schmitt: Integer. Enables Schmitt Trigger on the input. - normal: TEGRA_PIN_DISABLE - high: TEGRA_PIN_ENABLE -- nvidia,drive-type: Integer. Valid range 0...3. -- nvidia,pull-down-strength: Integer. Controls drive strength. 0 is weakest. - The range of valid values depends on the pingroup. See "CAL_DRVDN" in the - Tegra TRM. -- nvidia,pull-up-strength: Integer. Controls drive strength. 0 is weakest. - The range of valid values depends on the pingroup. See "CAL_DRVUP" in the - Tegra TRM. - -Valid values for pin and group names (nvidia,pin) are: - - These correspond to Tegra PADCTL_* (pinmux) registers. - - Mux groups: - - These correspond to Tegra PADCTL_* (pinmux) registers. Any property - that exists in those registers may be set for the following pin names. - - pex_l5_clkreq_n_pgg0, pex_l5_rst_n_pgg1 - - Drive groups: - - These registers controls a single pin for which a mux group exists. - See the list above for the pin name to use when configuring the pinmux. - - pex_l5_clkreq_n_pgg0, pex_l5_rst_n_pgg1 - -Valid values for nvidia,functions are: - - pe5 - -Power Domain: - pex_l5_clkreq_n_pgg0 and pex_l5_rst_n_pgg1 are part of PCIE C5 power - partition. Client devices must enable this partition before accessing - these pins here. - - -Example: - - tegra_pinctrl: pinmux: pinmux@2430000 { - compatible = "nvidia,tegra194-pinmux"; - reg = <0x2430000 0x17000 - 0xc300000 0x4000>; - - pinctrl-names = "pex_rst"; - pinctrl-0 = <&pex_rst_c5_out_state>; - - pex_rst_c5_out_state: pex_rst_c5_out { - pex_rst { - nvidia,pins = "pex_l5_rst_n_pgg1"; - nvidia,schmitt = <TEGRA_PIN_DISABLE>; - nvidia,lpdr = <TEGRA_PIN_ENABLE>; - nvidia,enable-input = <TEGRA_PIN_DISABLE>; - nvidia,io-hv = <TEGRA_PIN_ENABLE>; - nvidia,tristate = <TEGRA_PIN_DISABLE>; - nvidia,pull = <TEGRA_PIN_PULL_NONE>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra194-pinmux.yaml b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra194-pinmux.yaml new file mode 100644 index 000000000000..60a4bdf01bf2 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra194-pinmux.yaml @@ -0,0 +1,284 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/nvidia,tegra194-pinmux.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra194 Pinmux Controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + enum: + - nvidia,tegra194-pinmux + - nvidia,tegra194-pinmux-aon + + reg: + items: + - description: pinmux registers + +patternProperties: + "^pinmux(-[a-z0-9-_]+)?$": + type: object + properties: + phandle: true + + # pin groups + additionalProperties: + $ref: nvidia,tegra-pinmux-common.yaml + unevaluatedProperties: false + properties: + nvidia,function: + enum: [ aud, can0, can1, ccla, dca, dcb, dgpu, directdc, directdc1, + displaya, displayb, dmic1, dmic2, dmic3, dmic4, dmic5, dp, + dspk0, dspk1, eqos, extperiph1, extperiph2, extperiph3, + extperiph4, gp, gpio, hdmi, i2c1, i2c2, i2c3, i2c5, i2c8, + i2s1, i2s2, i2s3, i2s4, i2s5, i2s6, igpu, iqc1, iqc2, mipi, + nv, pe0, pe1, pe2, pe3, pe4, pe5, qspi, qspi0, qspi1, rsvd0, + rsvd1, rsvd2, rsvd3, sata, sce, sdmmc1, sdmmc3, sdmmc4, slvs, + soc, spdif, spi1, spi2, spi3, touch, uarta, uartb, uartc, + uartd, uarte, uartg, ufs0, usb, vgp1, vgp2, vgp3, vgp4, vgp5, + vgp6, wdt ] + + nvidia,pull: true + nvidia,tristate: true + nvidia,schmitt: true + nvidia,enable-input: true + nvidia,open-drain: true + nvidia,lock: true + nvidia,drive-type: true + nvidia,io-hv: true + + required: + - nvidia,pins + +additionalProperties: false + +allOf: + - if: + properties: + compatible: + const: nvidia,tegra194-pinmux + then: + patternProperties: + "^pinmux(-[a-z0-9-_]+)?$": + type: object + additionalProperties: + properties: + nvidia,pins: + description: An array of strings. Each string contains the name + of a pin or group. Valid values for these names are listed + below. + + Note that the pex_l5_clkreq_n_pgg0 and pex_l5_rst_n_pgg1 pins + are part of PCIE C5 power partition. Client devices must + enable this partition before accessing the configuration for + these pins. + items: + enum: [ dap6_sclk_pa0, dap6_dout_pa1, dap6_din_pa2, + dap6_fs_pa3, dap4_sclk_pa4, dap4_dout_pa5, + dap4_din_pa6, dap4_fs_pa7, cpu_pwr_req_0_pb0, + cpu_pwr_req_1_pb1, qspi0_sck_pc0, qspi0_cs_n_pc1, + qspi0_io0_pc2, qspi0_io1_pc3, qspi0_io2_pc4, + qspi0_io3_pc5, qspi1_sck_pc6, qspi1_cs_n_pc7, + qspi1_io0_pd0, qspi1_io1_pd1, qspi1_io2_pd2, + qspi1_io3_pd3, eqos_txc_pe0, eqos_td0_pe1, + eqos_td1_pe2, eqos_td2_pe3, eqos_td3_pe4, + eqos_tx_ctl_pe5, eqos_rd0_pe6, eqos_rd1_pe7, + eqos_rd2_pf0, eqos_rd3_pf1, eqos_rx_ctl_pf2, + eqos_rxc_pf3, eqos_sma_mdio_pf4, eqos_sma_mdc_pf5, + soc_gpio00_pg0, soc_gpio01_pg1, soc_gpio02_pg2, + soc_gpio03_pg3, soc_gpio08_pg4, soc_gpio09_pg5, + soc_gpio10_pg6, soc_gpio11_pg7, soc_gpio12_ph0, + soc_gpio13_ph1, soc_gpio14_ph2, uart4_tx_ph3, + uart4_rx_ph4, uart4_rts_ph5, uart4_cts_ph6, + dap2_sclk_ph7, dap2_dout_pi0, dap2_din_pi1, + dap2_fs_pi2, gen1_i2c_scl_pi3, gen1_i2c_sda_pi4, + sdmmc1_clk_pj0, sdmmc1_cmd_pj1, sdmmc1_dat0_pj2, + sdmmc1_dat1_pj3, sdmmc1_dat2_pj4, sdmmc1_dat3_pj5, + pex_l0_clkreq_n_pk0, pex_l0_rst_n_pk1, + pex_l1_clkreq_n_pk2, pex_l1_rst_n_pk3, + pex_l2_clkreq_n_pk4, pex_l2_rst_n_pk5, + pex_l3_clkreq_n_pk6, pex_l3_rst_n_pk7, + pex_l4_clkreq_n_pl0, pex_l4_rst_n_pl1, + pex_wake_n_pl2, sata_dev_slp_pl3, dp_aux_ch0_hpd_pm0, + dp_aux_ch1_hpd_pm1, dp_aux_ch2_hpd_pm2, + dp_aux_ch3_hpd_pm3, hdmi_cec_pm4, soc_gpio50_pm5, + soc_gpio51_pm6, soc_gpio52_pm7, soc_gpio53_pn0, + soc_gpio54_pn1, soc_gpio55_pn2, sdmmc3_clk_po0, + sdmmc3_cmd_po1, sdmmc3_dat0_po2, sdmmc3_dat1_po3, + sdmmc3_dat2_po4, sdmmc3_dat3_po5, extperiph1_clk_pp0, + extperiph2_clk_pp1, cam_i2c_scl_pp2, cam_i2c_sda_pp3, + soc_gpio04_pp4, soc_gpio05_pp5, soc_gpio06_pp6, + soc_gpio07_pp7, soc_gpio20_pq0, soc_gpio21_pq1, + soc_gpio22_pq2, soc_gpio23_pq3, soc_gpio40_pq4, + soc_gpio41_pq5, soc_gpio42_pq6, soc_gpio43_pq7, + soc_gpio44_pr0, soc_gpio45_pr1, uart1_tx_pr2, + uart1_rx_pr3, uart1_rts_pr4, uart1_cts_pr5, + dap1_sclk_ps0, dap1_dout_ps1, dap1_din_ps2, + dap1_fs_ps3, aud_mclk_ps4, soc_gpio30_ps5, + soc_gpio31_ps6, soc_gpio32_ps7, soc_gpio33_pt0, + dap3_sclk_pt1, dap3_dout_pt2, dap3_din_pt3, + dap3_fs_pt4, dap5_sclk_pt5, dap5_dout_pt6, + dap5_din_pt7, dap5_fs_pu0, directdc1_clk_pv0, + directdc1_in_pv1, directdc1_out0_pv2, + directdc1_out1_pv3, directdc1_out2_pv4, + directdc1_out3_pv5, directdc1_out4_pv6, + directdc1_out5_pv7, directdc1_out6_pw0, + directdc1_out7_pw1, gpu_pwr_req_px0, cv_pwr_req_px1, + gp_pwm2_px2, gp_pwm3_px3, uart2_tx_px4, uart2_rx_px5, + uart2_rts_px6, uart2_cts_px7, spi3_sck_py0, + spi3_miso_py1, spi3_mosi_py2, spi3_cs0_py3, + spi3_cs1_py4, uart5_tx_py5, uart5_rx_py6, + uart5_rts_py7, uart5_cts_pz0, usb_vbus_en0_pz1, + usb_vbus_en1_pz2, spi1_sck_pz3, spi1_miso_pz4, + spi1_mosi_pz5, spi1_cs0_pz6, spi1_cs1_pz7, + ufs0_ref_clk_pff0, ufs0_rst_pff1, + pex_l5_clkreq_n_pgg0, pex_l5_rst_n_pgg1, + directdc_comp, sdmmc4_clk, sdmmc4_cmd, sdmmc4_dqs, + sdmmc4_dat7, sdmmc4_dat6, sdmmc4_dat5, sdmmc4_dat4, + sdmmc4_dat3, sdmmc4_dat2, sdmmc4_dat1, sdmmc4_dat0, + sdmmc1_comp, sdmmc1_hv_trim, sdmmc3_comp, + sdmmc3_hv_trim, eqos_comp, qspi_comp, + # drive groups + drive_soc_gpio33_pt0, drive_soc_gpio32_ps7, + drive_soc_gpio31_ps6, drive_soc_gpio30_ps5, + drive_aud_mclk_ps4, drive_dap1_fs_ps3, + drive_dap1_din_ps2, drive_dap1_dout_ps1, + drive_dap1_sclk_ps0, drive_dap3_fs_pt4, + drive_dap3_din_pt3, drive_dap3_dout_pt2, + drive_dap3_sclk_pt1, drive_dap5_fs_pu0, + drive_dap5_din_pt7, drive_dap5_dout_pt6, + drive_dap5_sclk_pt5, drive_dap6_fs_pa3, + drive_dap6_din_pa2, drive_dap6_dout_pa1, + drive_dap6_sclk_pa0, drive_dap4_fs_pa7, + drive_dap4_din_pa6, drive_dap4_dout_pa5, + drive_dap4_sclk_pa4, drive_extperiph2_clk_pp1, + drive_extperiph1_clk_pp0, drive_cam_i2c_sda_pp3, + drive_cam_i2c_scl_pp2, drive_soc_gpio40_pq4, + drive_soc_gpio41_pq5, drive_soc_gpio42_pq6, + drive_soc_gpio43_pq7, drive_soc_gpio44_pr0, + drive_soc_gpio45_pr1, drive_soc_gpio20_pq0, + drive_soc_gpio21_pq1, drive_soc_gpio22_pq2, + drive_soc_gpio23_pq3, drive_soc_gpio04_pp4, + drive_soc_gpio05_pp5, drive_soc_gpio06_pp6, + drive_soc_gpio07_pp7, drive_uart1_cts_pr5, + drive_uart1_rts_pr4, drive_uart1_rx_pr3, + drive_uart1_tx_pr2, drive_dap2_din_pi1, + drive_dap2_dout_pi0, drive_dap2_fs_pi2, + drive_dap2_sclk_ph7, drive_uart4_cts_ph6, + drive_uart4_rts_ph5, drive_uart4_rx_ph4, + drive_uart4_tx_ph3, drive_soc_gpio03_pg3, + drive_soc_gpio02_pg2, drive_soc_gpio01_pg1, + drive_soc_gpio00_pg0, drive_gen1_i2c_scl_pi3, + drive_gen1_i2c_sda_pi4, drive_soc_gpio08_pg4, + drive_soc_gpio09_pg5, drive_soc_gpio10_pg6, + drive_soc_gpio11_pg7, drive_soc_gpio12_ph0, + drive_soc_gpio13_ph1, drive_soc_gpio14_ph2, + drive_soc_gpio50_pm5, drive_soc_gpio51_pm6, + drive_soc_gpio52_pm7, drive_soc_gpio53_pn0, + drive_soc_gpio54_pn1, drive_soc_gpio55_pn2, + drive_dp_aux_ch0_hpd_pm0, drive_dp_aux_ch1_hpd_pm1, + drive_dp_aux_ch2_hpd_pm2, drive_dp_aux_ch3_hpd_pm3, + drive_hdmi_cec_pm4, drive_pex_l2_clkreq_n_pk4, + drive_pex_wake_n_pl2, drive_pex_l1_clkreq_n_pk2, + drive_pex_l1_rst_n_pk3, drive_pex_l0_clkreq_n_pk0, + drive_pex_l0_rst_n_pk1, drive_pex_l2_rst_n_pk5, + drive_pex_l3_clkreq_n_pk6, drive_pex_l3_rst_n_pk7, + drive_pex_l4_clkreq_n_pl0, drive_pex_l4_rst_n_pl1, + drive_sata_dev_slp_pl3, drive_pex_l5_clkreq_n_pgg0, + drive_pex_l5_rst_n_pgg1, drive_cpu_pwr_req_1_pb1, + drive_cpu_pwr_req_0_pb0, drive_sdmmc1_clk_pj0, + drive_sdmmc1_cmd_pj1, drive_sdmmc1_dat3_pj5, + drive_sdmmc1_dat2_pj4, drive_sdmmc1_dat1_pj3, + drive_sdmmc1_dat0_pj2, drive_sdmmc3_dat3_po5, + drive_sdmmc3_dat2_po4, drive_sdmmc3_dat1_po3, + drive_sdmmc3_dat0_po2, drive_sdmmc3_cmd_po1, + drive_sdmmc3_clk_po0, drive_gpu_pwr_req_px0, + drive_spi3_miso_py1, drive_spi1_cs0_pz6, + drive_spi3_cs0_py3, drive_spi1_miso_pz4, + drive_spi3_cs1_py4, drive_gp_pwm3_px3, + drive_gp_pwm2_px2, drive_spi1_sck_pz3, + drive_spi3_sck_py0, drive_spi1_cs1_pz7, + drive_spi1_mosi_pz5, drive_spi3_mosi_py2, + drive_cv_pwr_req_px1, drive_uart2_tx_px4, + drive_uart2_rx_px5, drive_uart2_rts_px6, + drive_uart2_cts_px7, drive_uart5_rx_py6, + drive_uart5_tx_py5, drive_uart5_rts_py7, + drive_uart5_cts_pz0, drive_usb_vbus_en0_pz1, + drive_usb_vbus_en1_pz2, drive_ufs0_rst_pff1, + drive_ufs0_ref_clk_pff0 ] + + - if: + properties: + compatible: + const: nvidia,tegra194-pinmux-aon + then: + patternProperties: + "^pinmux(-[a-z0-9-_]+)?$": + type: object + additionalProperties: + properties: + nvidia,pins: + items: + enum: [ can1_dout_paa0, can1_din_paa1, can0_dout_paa2, + can0_din_paa3, can0_stb_paa4, can0_en_paa5, + can0_wake_paa6, can0_err_paa7, can1_stb_pbb0, + can1_en_pbb1, can1_wake_pbb2, can1_err_pbb3, + spi2_sck_pcc0, spi2_miso_pcc1, spi2_mosi_pcc2, + spi2_cs0_pcc3, touch_clk_pcc4, uart3_tx_pcc5, + uart3_rx_pcc6, gen2_i2c_scl_pcc7, gen2_i2c_sda_pdd0, + gen8_i2c_scl_pdd1, gen8_i2c_sda_pdd2, + safe_state_pee0, vcomp_alert_pee1, + ao_retention_n_pee2, batt_oc_pee3, power_on_pee4, + pwr_i2c_scl_pee5, pwr_i2c_sda_pee6, sys_reset_n, + shutdown_n, pmu_int_n, soc_pwr_req, clk_32k_in, + # drive groups + drive_shutdown_n, drive_pmu_int_n, + drive_safe_state_pee0, drive_vcomp_alert_pee1, + drive_soc_pwr_req, drive_batt_oc_pee3, + drive_clk_32k_in, drive_power_on_pee4, + drive_pwr_i2c_scl_pee5, drive_pwr_i2c_sda_pee6, + drive_ao_retention_n_pee2, drive_touch_clk_pcc4, + drive_uart3_rx_pcc6, drive_uart3_tx_pcc5, + drive_gen8_i2c_sda_pdd2, drive_gen8_i2c_scl_pdd1, + drive_spi2_mosi_pcc2, drive_gen2_i2c_scl_pcc7, + drive_spi2_cs0_pcc3, drive_gen2_i2c_sda_pdd0, + drive_spi2_sck_pcc0, drive_spi2_miso_pcc1, + drive_can1_dout_paa0, drive_can1_din_paa1, + drive_can0_dout_paa2, drive_can0_din_paa3, + drive_can0_stb_paa4, drive_can0_en_paa5, + drive_can0_wake_paa6, drive_can0_err_paa7, + drive_can1_stb_pbb0, drive_can1_en_pbb1, + drive_can1_wake_pbb2, drive_can1_err_pbb3 ] + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/pinctrl/pinctrl-tegra.h> + + pinmux@2430000 { + compatible = "nvidia,tegra194-pinmux"; + reg = <0x2430000 0x17000>; + + pinctrl-names = "pex_rst"; + pinctrl-0 = <&pex_rst_c5_out_state>; + + pex_rst_c5_out_state: pinmux-pex-rst-c5-out { + pex_rst { + nvidia,pins = "pex_l5_rst_n_pgg1"; + nvidia,schmitt = <TEGRA_PIN_DISABLE>; + nvidia,enable-input = <TEGRA_PIN_DISABLE>; + nvidia,io-hv = <TEGRA_PIN_ENABLE>; + nvidia,tristate = <TEGRA_PIN_DISABLE>; + nvidia,pull = <TEGRA_PIN_PULL_NONE>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra20-pinmux.txt b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra20-pinmux.txt deleted file mode 100644 index 3c8ce28baad6..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra20-pinmux.txt +++ /dev/null @@ -1,143 +0,0 @@ -NVIDIA Tegra20 pinmux controller - -Required properties: -- compatible: "nvidia,tegra20-pinmux" -- reg: Should contain the register physical address and length for each of - the tri-state, mux, pull-up/down, and pad control register sets. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -Tegra's pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, tristate, drive strength, etc. - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function or tristate parameter. For this -reason, even seemingly boolean values are actually tristates in this binding: -unspecified, off, or on. Unspecified is represented as an absent property, -and off/on are represented as integer values 0 and 1. - -Required subnode-properties: -- nvidia,pins : An array of strings. Each string contains the name of a pin or - group. Valid values for these names are listed below. - -Optional subnode-properties: -- nvidia,function: A string containing the name of the function to mux to the - pin or group. Valid values for function names are listed below. See the Tegra - TRM to determine which are valid for each pin or group. -- nvidia,pull: Integer, representing the pull-down/up to apply to the pin. - 0: none, 1: down, 2: up. -- nvidia,tristate: Integer. - 0: drive, 1: tristate. -- nvidia,high-speed-mode: Integer. Enable high speed mode the pins. - 0: no, 1: yes. -- nvidia,schmitt: Integer. Enables Schmitt Trigger on the input. - 0: no, 1: yes. -- nvidia,low-power-mode: Integer. Valid values 0-3. 0 is least power, 3 is - most power. Controls the drive power or current. See "Low Power Mode" - or "LPMD1" and "LPMD0" in the Tegra TRM. -- nvidia,pull-down-strength: Integer. Controls drive strength. 0 is weakest. - The range of valid values depends on the pingroup. See "CAL_DRVDN" in the - Tegra TRM. -- nvidia,pull-up-strength: Integer. Controls drive strength. 0 is weakest. - The range of valid values depends on the pingroup. See "CAL_DRVUP" in the - Tegra TRM. -- nvidia,slew-rate-rising: Integer. Controls rising signal slew rate. 0 is - fastest. The range of valid values depends on the pingroup. See - "DRVDN_SLWR" in the Tegra TRM. -- nvidia,slew-rate-falling: Integer. Controls falling signal slew rate. 0 is - fastest. The range of valid values depends on the pingroup. See - "DRVUP_SLWF" in the Tegra TRM. - -Note that many of these properties are only valid for certain specific pins -or groups. See the Tegra TRM and various pinmux spreadsheets for complete -details regarding which groups support which functionality. The Linux pinctrl -driver may also be a useful reference, since it consolidates, disambiguates, -and corrects data from all those sources. - -Valid values for pin and group names are: - - mux groups: - - These all support nvidia,function, nvidia,tristate, and many support - nvidia,pull. - - ata, atb, atc, atd, ate, cdev1, cdev2, crtp, csus, dap1, dap2, dap3, dap4, - ddc, dta, dtb, dtc, dtd, dte, dtf, gma, gmb, gmc, gmd, gme, gpu, gpu7, - gpv, hdint, i2cp, irrx, irtx, kbca, kbcb, kbcc, kbcd, kbce, kbcf, lcsn, - ld0, ld1, ld2, ld3, ld4, ld5, ld6, ld7, ld8, ld9, ld10, ld11, ld12, ld13, - ld14, ld15, ld16, ld17, ldc, ldi, lhp0, lhp1, lhp2, lhs, lm0, lm1, lpp, - lpw0, lpw1, lpw2, lsc0, lsc1, lsck, lsda, lsdi, lspi, lvp0, lvp1, lvs, - owc, pmc, pta, rm, sdb, sdc, sdd, sdio1, slxa, slxc, slxd, slxk, spdi, - spdo, spia, spib, spic, spid, spie, spif, spig, spih, uaa, uab, uac, uad, - uca, ucb, uda. - - tristate groups: - - These only support nvidia,pull. - - ck32, ddrc, pmca, pmcb, pmcc, pmcd, pmce, xm2c, xm2d, ls, lc, ld17_0, - ld19_18, ld21_20, ld23_22. - - drive groups: - - With some exceptions, these support nvidia,high-speed-mode, - nvidia,schmitt, nvidia,low-power-mode, nvidia,pull-down-strength, - nvidia,pull-up-strength, nvidia,slew-rate-rising, nvidia,slew-rate-falling. - - drive_ao1, drive_ao2, drive_at1, drive_at2, drive_cdev1, drive_cdev2, - drive_csus, drive_dap1, drive_dap2, drive_dap3, drive_dap4, drive_dbg, - drive_lcd1, drive_lcd2, drive_sdmmc2, drive_sdmmc3, drive_spi, drive_uaa, - drive_uab, drive_uart2, drive_uart3, drive_vi1, drive_vi2, drive_xm2a, - drive_xm2c, drive_xm2d, drive_xm2clk, drive_sdio1, drive_crt, drive_ddc, - drive_gma, drive_gmb, drive_gmc, drive_gmd, drive_gme, drive_owr, - drive_uda. - -Valid values for nvidia,functions are: - - ahb_clk, apb_clk, audio_sync, crt, dap1, dap2, dap3, dap4, dap5, - displaya, displayb, emc_test0_dll, emc_test1_dll, gmi, gmi_int, - hdmi, i2cp, i2c1, i2c2, i2c3, ide, irda, kbc, mio, mipi_hs, nand, - osc, owr, pcie, plla_out, pllc_out1, pllm_out1, pllp_out2, pllp_out3, - pllp_out4, pwm, pwr_intr, pwr_on, rsvd1, rsvd2, rsvd3, rsvd4, rtck, - sdio1, sdio2, sdio3, sdio4, sflash, spdif, spi1, spi2, spi2_alt, - spi3, spi4, trace, twc, uarta, uartb, uartc, uartd, uarte, ulpi, - vi, vi_sensor_clk, xio - -Example: - - pinctrl@70000000 { - compatible = "nvidia,tegra20-pinmux"; - reg = < 0x70000014 0x10 /* Tri-state registers */ - 0x70000080 0x20 /* Mux registers */ - 0x700000a0 0x14 /* Pull-up/down registers */ - 0x70000868 0xa8 >; /* Pad control registers */ - }; - -Example board file extract: - - pinctrl@70000000 { - sdio4_default: sdio4_default { - atb { - nvidia,pins = "atb", "gma", "gme"; - nvidia,function = "sdio4"; - nvidia,pull = <0>; - nvidia,tristate = <0>; - }; - }; - }; - - sdhci@c8000600 { - pinctrl-names = "default"; - pinctrl-0 = <&sdio4_default>; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra20-pinmux.yaml b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra20-pinmux.yaml new file mode 100644 index 000000000000..432ea40209a8 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra20-pinmux.yaml @@ -0,0 +1,112 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/nvidia,tegra20-pinmux.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra20 Pinmux Controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + const: nvidia,tegra20-pinmux + + reg: + items: + - description: tri-state registers + - description: mux register + - description: pull-up/down registers + - description: pad control registers + +patternProperties: + "^pinmux(-[a-z0-9-_]+)?$": + type: object + properties: + phandle: true + + # pin groups + additionalProperties: + $ref: nvidia,tegra-pinmux-common.yaml + additionalProperties: false + properties: + nvidia,pins: + items: + enum: [ ata, atb, atc, atd, ate, cdev1, cdev2, crtp, csus, dap1, + dap2, dap3, dap4, ddc, dta, dtb, dtc, dtd, dte, dtf, gma, + gmb, gmc, gmd, gme, gpu, gpu7, gpv, hdint, i2cp, irrx, + irtx, kbca, kbcb, kbcc, kbcd, kbce, kbcf, lcsn, ld0, ld1, + ld2, ld3, ld4, ld5, ld6, ld7, ld8, ld9, ld10, ld11, ld12, + ld13, ld14, ld15, ld16, ld17, ldc, ldi, lhp0, lhp1, lhp2, + lhs, lm0, lm1, lpp, lpw0, lpw1, lpw2, lsc0, lsc1, lsck, + lsda, lsdi, lspi, lvp0, lvp1, lvs, owc, pmc, pta, rm, sdb, + sdc, sdd, sdio1, slxa, slxc, slxd, slxk, spdi, spdo, spia, + spib, spic, spid, spie, spif, spig, spih, uaa, uab, uac, + uad, uca, ucb, uda, + # tristate groups + ck32, ddrc, pmca, pmcb, pmcc, pmcd, pmce, xm2c, xm2d, ls, + lc, ld17_0, ld19_18, ld21_20, ld23_22, + # drive groups + drive_ao1, drive_ao2, drive_at1, drive_at2, drive_cdev1, + drive_cdev2, drive_csus, drive_dap1, drive_dap2, + drive_dap3, drive_dap4, drive_dbg, drive_lcd1, drive_lcd2, + drive_sdmmc2, drive_sdmmc3, drive_spi, drive_uaa, + drive_uab, drive_uart2, drive_uart3, drive_vi1, drive_vi2, + drive_xm2a, drive_xm2c, drive_xm2d, drive_xm2clk, + drive_sdio1, drive_crt, drive_ddc, drive_gma, drive_gmb, + drive_gmc, drive_gmd, drive_gme, drive_owr, drive_uda ] + + nvidia,function: + enum: [ ahb_clk, apb_clk, audio_sync, crt, dap1, dap2, dap3, dap4, + dap5, displaya, displayb, emc_test0_dll, emc_test1_dll, gmi, + gmi_int, hdmi, i2cp, i2c1, i2c2, i2c3, ide, irda, kbc, mio, + mipi_hs, nand, osc, owr, pcie, plla_out, pllc_out1, + pllm_out1, pllp_out2, pllp_out3, pllp_out4, pwm, pwr_intr, + pwr_on, rsvd1, rsvd2, rsvd3, rsvd4, rtck, sdio1, sdio2, + sdio3, sdio4, sflash, spdif, spi1, spi2, spi2_alt, spi3, + spi4, trace, twc, uarta, uartb, uartc, uartd, uarte, ulpi, + vi, vi_sensor_clk, xio ] + + nvidia,pull: true + nvidia,tristate: true + nvidia,schmitt: true + nvidia,pull-down-strength: true + nvidia,pull-up-strength: true + nvidia,high-speed-mode: true + nvidia,low-power-mode: true + nvidia,slew-rate-rising: true + nvidia,slew-rate-falling: true + + required: + - nvidia,pins + +additionalProperties: false + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/clock/tegra20-car.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + pinctrl@70000000 { + compatible = "nvidia,tegra20-pinmux"; + reg = <0x70000014 0x10>, /* Tri-state registers */ + <0x70000080 0x20>, /* Mux registers */ + <0x700000a0 0x14>, /* Pull-up/down registers */ + <0x70000868 0xa8>; /* Pad control registers */ + + pinmux { + atb { + nvidia,pins = "atb", "gma", "gme"; + nvidia,function = "sdio4"; + nvidia,pull = <0>; + nvidia,tristate = <0>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra210-pinmux.txt b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra210-pinmux.txt deleted file mode 100644 index 85f211436b8e..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra210-pinmux.txt +++ /dev/null @@ -1,166 +0,0 @@ -NVIDIA Tegra210 pinmux controller - -Required properties: -- compatible: "nvidia,tegra210-pinmux" -- reg: Should contain a list of base address and size pairs for: - - first entry: The APB_MISC_GP_*_PADCTRL registers (pad control) - - second entry: The PINMUX_AUX_* registers (pinmux) - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -Tegra's pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, tristate, drive strength, etc. - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function or tristate parameter. For this -reason, even seemingly boolean values are actually tristates in this binding: -unspecified, off, or on. Unspecified is represented as an absent property, -and off/on are represented as integer values 0 and 1. - -See the TRM to determine which properties and values apply to each pin/group. -Macro values for property values are defined in -include/dt-binding/pinctrl/pinctrl-tegra.h. - -Required subnode-properties: -- nvidia,pins : An array of strings. Each string contains the name of a pin or - group. Valid values for these names are listed below. - -Optional subnode-properties: -- nvidia,function: A string containing the name of the function to mux to the - pin or group. -- nvidia,pull: Integer, representing the pull-down/up to apply to the pin. - 0: none, 1: down, 2: up. -- nvidia,tristate: Integer. - 0: drive, 1: tristate. -- nvidia,enable-input: Integer. Enable the pin's input path. - enable :TEGRA_PIN_ENABLE and - disable or output only: TEGRA_PIN_DISABLE. -- nvidia,open-drain: Integer. - enable: TEGRA_PIN_ENABLE. - disable: TEGRA_PIN_DISABLE. -- nvidia,lock: Integer. Lock the pin configuration against further changes - until reset. - enable: TEGRA_PIN_ENABLE. - disable: TEGRA_PIN_DISABLE. -- nvidia,io-hv: Integer. Select high-voltage receivers. - normal: TEGRA_PIN_DISABLE - high: TEGRA_PIN_ENABLE -- nvidia,high-speed-mode: Integer. Enable high speed mode the pins. - normal: TEGRA_PIN_DISABLE - high: TEGRA_PIN_ENABLE -- nvidia,schmitt: Integer. Enables Schmitt Trigger on the input. - normal: TEGRA_PIN_DISABLE - high: TEGRA_PIN_ENABLE -- nvidia,drive-type: Integer. Valid range 0...3. -- nvidia,pull-down-strength: Integer. Controls drive strength. 0 is weakest. - The range of valid values depends on the pingroup. See "CAL_DRVDN" in the - Tegra TRM. -- nvidia,pull-up-strength: Integer. Controls drive strength. 0 is weakest. - The range of valid values depends on the pingroup. See "CAL_DRVUP" in the - Tegra TRM. -- nvidia,slew-rate-rising: Integer. Controls rising signal slew rate. 0 is - fastest. The range of valid values depends on the pingroup. See - "DRVDN_SLWR" in the Tegra TRM. -- nvidia,slew-rate-falling: Integer. Controls falling signal slew rate. 0 is - fastest. The range of valid values depends on the pingroup. See - "DRVUP_SLWF" in the Tegra TRM. - -Valid values for pin and group names (nvidia,pin) are: - - Mux groups: - - These correspond to Tegra PINMUX_AUX_* (pinmux) registers. Any property - that exists in those registers may be set for the following pin names. - - In Tegra210, many pins also have a dedicated APB_MISC_GP_*_PADCTRL - register. Where that is true, and property that exists in that register - may also be set on the following pin names. - - als_prox_int_px3, ap_ready_pv5, ap_wake_bt_ph3, ap_wake_nfc_ph7, - aud_mclk_pbb0, batt_bcl, bt_rst_ph4, bt_wake_ap_ph5, button_home_py1, - button_power_on_px5, button_slide_sw_py0, button_vol_down_px7, - button_vol_up_px6, cam1_mclk_ps0, cam1_pwdn_ps7, cam1_strobe_pt1, - cam2_mclk_ps1, cam2_pwdn_pt0, cam_af_en_ps5, cam_flash_en_ps6, - cam_i2c_scl_ps2, cam_i2c_sda_ps3, cam_rst_ps4cam_rst_ps4, clk_32k_in, - clk_32k_out_py5, clk_req, core_pwr_req, cpu_pwr_req, dap1_din_pb1, - dap1_dout_pb2, dap1_fs_pb0, dap1_sclk_pb3, dap2_din_paa2, dap2_dout_paa3, - dap2_fs_paa0, dap2_sclk_paa1, dap4_din_pj5, dap4_dout_pj6, dap4_fs_pj4, - dap4_sclk_pj7, dmic1_clk_pe0, dmic1_dat_pe1, dmic2_clk_pe2, dmic2_dat_pe3, - dmic3_clk_pe4, dmic3_dat_pe5, dp_hpd0_pcc6, dvfs_clk_pbb2, dvfs_pwm_pbb1, - gen1_i2c_scl_pj1, gen1_i2c_sda_pj0, gen2_i2c_scl_pj2, gen2_i2c_sda_pj3, - gen3_i2c_scl_pf0, gen3_i2c_sda_pf1, gpio_x1_aud_pbb3, gpio_x3_aud_pbb4, - gps_en_pi2, gps_rst_pi3, hdmi_cec_pcc0, hdmi_int_dp_hpd_pcc1, jtag_rtck, - lcd_bl_en_pv1, lcd_bl_pwm_pv0, lcd_gpio1_pv3, lcd_gpio2_pv4, lcd_rst_pv2, - lcd_te_py2, modem_wake_ap_px0, motion_int_px2, nfc_en_pi0, nfc_int_pi1, - pa6, pcc7, pe6, pe7, pex_l0_clkreq_n_pa1, pex_l0_rst_n_pa0, - pex_l1_clkreq_n_pa4, pex_l1_rst_n_pa3, pex_wake_n_pa2, ph6, pk0, pk1, pk2, - pk3, pk4, pk5, pk6, pk7, pl0, pl1, pwr_i2c_scl_py3, pwr_i2c_sda_py4, - pwr_int_n, pz0, pz1, pz2, pz3, pz4, pz5, qspi_cs_n_pee1, qspi_io0_pee2, - qspi_io1_pee3, qspi_io2_pee4, qspi_io3_pee5, qspi_sck_pee0, - sata_led_active_pa5, sdmmc1_clk_pm0, sdmmc1_cmd_pm1, sdmmc1_dat0_pm5, - sdmmc1_dat1_pm4, sdmmc1_dat2_pm3, sdmmc1_dat3_pm2, sdmmc3_clk_pp0, - sdmmc3_cmd_pp1, sdmmc3_dat0_pp5, sdmmc3_dat1_pp4, sdmmc3_dat2_pp3, - sdmmc3_dat3_pp2, shutdown, spdif_in_pcc3, spdif_out_pcc2, spi1_cs0_pc3, - spi1_cs1_pc4, spi1_miso_pc1, spi1_mosi_pc0, spi1_sck_pc2, spi2_cs0_pb7, - spi2_cs1_pdd0, spi2_miso_pb5, spi2_mosi_pb4, spi2_sck_pb6, spi4_cs0_pc6, - spi4_miso_pd0, spi4_mosi_pc7, spi4_sck_pc5, temp_alert_px4, touch_clk_pv7, - touch_int_px1, touch_rst_pv6, uart1_cts_pu3, uart1_rts_pu2, uart1_rx_pu1, - uart1_tx_pu0, uart2_cts_pg3, uart2_rts_pg2, uart2_rx_pg1, uart2_tx_pg0, - uart3_cts_pd4, uart3_rts_pd3, uart3_rx_pd2, uart3_tx_pd1, uart4_cts_pi7, - uart4_rts_pi6, uart4_rx_pi5, uart4_tx_pi4, usb_vbus_en0_pcc4, - usb_vbus_en1_pcc5, wifi_en_ph0, wifi_rst_ph1, wifi_wake_ap_ph2 - - Drive groups: - - These correspond to the Tegra APB_MISC_GP_*_PADCTRL (pad control) - registers. Note that where one of these registers controls a single pin - for which a PINMUX_AUX_* exists, see the list above for the pin name to - use when configuring the pinmux. - - pa6, pcc7, pe6, pe7, ph6, pk0, pk1, pk2, pk3, pk4, pk5, pk6, pk7, pl0, pl1, - pz0, pz1, pz2, pz3, pz4, pz5, sdmmc1, sdmmc2, sdmmc3, sdmmc4 - -Valid values for nvidia,functions are: - - aud, bcl, blink, ccla, cec, cldvfs, clk, core, cpu, displaya, displayb, - dmic1, dmic2, dmic3, dp, dtv, extperiph3, i2c1, i2c2, i2c3, i2cpmu, i2cvi, - i2s1, i2s2, i2s3, i2s4a, i2s4b, i2s5a, i2s5b, iqc0, iqc1, jtag, pe, pe0, - pe1, pmi, pwm0, pwm1, pwm2, pwm3, qspi, rsvd0, rsvd1, rsvd2, rsvd3, sata, - sdmmc1, sdmmc3, shutdown, soc, sor0, sor1, spdif, spi1, spi2, spi3, spi4, - sys, touch, uart, uarta, uartb, uartc, uartd, usb, vgp1, vgp2, vgp3, vgp4, - vgp5, vgp6, vimclk, vimclk2 - -Example: - - pinmux: pinmux@70000800 { - compatible = "nvidia,tegra210-pinmux"; - reg = <0x0 0x700008d4 0x0 0x2a8>, /* Pad control registers */ - <0x0 0x70003000 0x0 0x1000>; /* Mux registers */ - - pinctrl-names = "boot"; - pinctrl-0 = <&state_boot>; - - state_boot: pinmux { - gen1_i2c_scl_pj1 { - nvidia,pins = "gen1_i2c_scl_pj1", - nvidia,function = "i2c1"; - nvidia,pull = <TEGRA_PIN_PULL_NONE>; - nvidia,tristate = <TEGRA_PIN_DISABLE>; - nvidia,enable-input = <TEGRA_PIN_ENABLE>; - nvidia,open-drain = <TEGRA_PIN_ENABLE>; - nvidia,io-hv = <TEGRA_PIN_ENABLE>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra210-pinmux.yaml b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra210-pinmux.yaml new file mode 100644 index 000000000000..28ae2e6d0cbc --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra210-pinmux.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/nvidia,tegra210-pinmux.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra210 Pinmux Controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + const: nvidia,tegra210-pinmux + + reg: + items: + - description: APB_MISC_GP_*_PADCTRL register (pad control) + - description: PINMUX_AUX_* registers (pinmux) + +patternProperties: + "^pinmux(-[a-z0-9-_]+)?$": + type: object + properties: + phandle: true + + # pin groups + additionalProperties: + $ref: nvidia,tegra-pinmux-common.yaml + additionalProperties: false + properties: + nvidia,pins: + items: + enum: [ als_prox_int_px3, ap_ready_pv5, ap_wake_bt_ph3, + ap_wake_nfc_ph7, aud_mclk_pbb0, batt_bcl, bt_rst_ph4, + bt_wake_ap_ph5, button_home_py1, button_power_on_px5, + button_slide_sw_py0, button_vol_down_px7, + button_vol_up_px6, cam1_mclk_ps0, cam1_pwdn_ps7, + cam1_strobe_pt1, cam2_mclk_ps1, cam2_pwdn_pt0, + cam_af_en_ps5, cam_flash_en_ps6, cam_i2c_scl_ps2, + cam_i2c_sda_ps3, cam_rst_ps4, clk_32k_in, clk_32k_out_py5, + clk_req, core_pwr_req, cpu_pwr_req, dap1_din_pb1, + dap1_dout_pb2, dap1_fs_pb0, dap1_sclk_pb3, dap2_din_paa2, + dap2_dout_paa3, dap2_fs_paa0, dap2_sclk_paa1, dap4_din_pj5, + dap4_dout_pj6, dap4_fs_pj4, dap4_sclk_pj7, dmic1_clk_pe0, + dmic1_dat_pe1, dmic2_clk_pe2, dmic2_dat_pe3, dmic3_clk_pe4, + dmic3_dat_pe5, dp_hpd0_pcc6, dvfs_clk_pbb2, dvfs_pwm_pbb1, + gen1_i2c_scl_pj1, gen1_i2c_sda_pj0, gen2_i2c_scl_pj2, + gen2_i2c_sda_pj3, gen3_i2c_scl_pf0, gen3_i2c_sda_pf1, + gpio_x1_aud_pbb3, gpio_x3_aud_pbb4, gps_en_pi2, + gps_rst_pi3, hdmi_cec_pcc0, hdmi_int_dp_hpd_pcc1, + jtag_rtck, lcd_bl_en_pv1, lcd_bl_pwm_pv0, lcd_gpio1_pv3, + lcd_gpio2_pv4, lcd_rst_pv2, lcd_te_py2, modem_wake_ap_px0, + motion_int_px2, nfc_en_pi0, nfc_int_pi1, pa6, pcc7, pe6, + pe7, pex_l0_clkreq_n_pa1, pex_l0_rst_n_pa0, + pex_l1_clkreq_n_pa4, pex_l1_rst_n_pa3, pex_wake_n_pa2, ph6, + pk0, pk1, pk2, pk3, pk4, pk5, pk6, pk7, pl0, pl1, + pwr_i2c_scl_py3, pwr_i2c_sda_py4, pwr_int_n, pz0, pz1, pz2, + pz3, pz4, pz5, qspi_cs_n_pee1, qspi_io0_pee2, + qspi_io1_pee3, qspi_io2_pee4, qspi_io3_pee5, qspi_sck_pee0, + sata_led_active_pa5, sdmmc1_clk_pm0, sdmmc1_cmd_pm1, + sdmmc1_dat0_pm5, sdmmc1_dat1_pm4, sdmmc1_dat2_pm3, + sdmmc1_dat3_pm2, sdmmc3_clk_pp0, sdmmc3_cmd_pp1, + sdmmc3_dat0_pp5, sdmmc3_dat1_pp4, sdmmc3_dat2_pp3, + sdmmc3_dat3_pp2, shutdown, spdif_in_pcc3, spdif_out_pcc2, + spi1_cs0_pc3, spi1_cs1_pc4, spi1_miso_pc1, spi1_mosi_pc0, + spi1_sck_pc2, spi2_cs0_pb7, spi2_cs1_pdd0, spi2_miso_pb5, + spi2_mosi_pb4, spi2_sck_pb6, spi4_cs0_pc6, spi4_miso_pd0, + spi4_mosi_pc7, spi4_sck_pc5, temp_alert_px4, touch_clk_pv7, + touch_int_px1, touch_rst_pv6, uart1_cts_pu3, uart1_rts_pu2, + uart1_rx_pu1, uart1_tx_pu0, uart2_cts_pg3, uart2_rts_pg2, + uart2_rx_pg1, uart2_tx_pg0, uart3_cts_pd4, uart3_rts_pd3, + uart3_rx_pd2, uart3_tx_pd1, uart4_cts_pi7, uart4_rts_pi6, + uart4_rx_pi5, uart4_tx_pi4, usb_vbus_en0_pcc4, + usb_vbus_en1_pcc5, wifi_en_ph0, wifi_rst_ph1, + wifi_wake_ap_ph2, + # drive groups + drive_pa6, drive_pcc7, drive_pe6, drive_pe7, drive_ph6, + drive_pk0, drive_pk1, drive_pk2, drive_pk3, drive_pk4, + drive_pk5, drive_pk6, drive_pk7, drive_pl0, drive_pl1, + drive_pz0, drive_pz1, drive_pz2, drive_pz3, drive_pz4, + drive_pz5, drive_sdmmc1, drive_sdmmc2, drive_sdmmc3, + drive_sdmmc4 ] + + nvidia,function: + enum: [ aud, bcl, blink, ccla, cec, cldvfs, clk, core, cpu, displaya, + displayb, dmic1, dmic2, dmic3, dp, dtv, extperiph3, i2c1, + i2c2, i2c3, i2cpmu, i2cvi, i2s1, i2s2, i2s3, i2s4a, i2s4b, + i2s5a, i2s5b, iqc0, iqc1, jtag, pe, pe0, pe1, pmi, pwm0, + pwm1, pwm2, pwm3, qspi, rsvd0, rsvd1, rsvd2, rsvd3, sata, + sdmmc1, sdmmc3, shutdown, soc, sor0, sor1, spdif, spi1, spi2, + spi3, spi4, sys, touch, uart, uarta, uartb, uartc, uartd, + usb, vgp1, vgp2, vgp3, vgp4, vgp5, vgp6, vimclk, vimclk2 ] + + nvidia,pull: true + nvidia,tristate: true + nvidia,pull-down-strength: true + nvidia,pull-up-strength: true + nvidia,high-speed-mode: true + nvidia,enable-input: true + nvidia,open-drain: true + nvidia,lock: true + nvidia,drive-type: true + nvidia,io-hv: true + nvidia,slew-rate-rising: true + nvidia,slew-rate-falling: true + + required: + - nvidia,pins + +additionalProperties: false + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/pinctrl/pinctrl-tegra.h> + + pinmux: pinmux@70000800 { + compatible = "nvidia,tegra210-pinmux"; + reg = <0x700008d4 0x02a8>, /* Pad control registers */ + <0x70003000 0x1000>; /* Mux registers */ + + pinctrl-names = "boot"; + pinctrl-0 = <&state_boot>; + + state_boot: pinmux { + gen1_i2c_scl_pj1 { + nvidia,pins = "gen1_i2c_scl_pj1"; + nvidia,function = "i2c1"; + nvidia,pull = <TEGRA_PIN_PULL_NONE>; + nvidia,tristate = <TEGRA_PIN_DISABLE>; + nvidia,enable-input = <TEGRA_PIN_ENABLE>; + nvidia,open-drain = <TEGRA_PIN_ENABLE>; + nvidia,io-hv = <TEGRA_PIN_ENABLE>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra30-pinmux.txt b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra30-pinmux.txt deleted file mode 100644 index 0e6354c11e6d..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra30-pinmux.txt +++ /dev/null @@ -1,144 +0,0 @@ -NVIDIA Tegra30 pinmux controller - -The Tegra30 pinctrl binding is very similar to the Tegra20 pinctrl binding, -as described in nvidia,tegra20-pinmux.txt. In fact, this document assumes -that binding as a baseline, and only documents the differences between the -two bindings. - -Required properties: -- compatible: "nvidia,tegra30-pinmux" -- reg: Should contain the register physical address and length for each of - the pad control and mux registers. - -Tegra30 adds the following optional properties for pin configuration subnodes: -- nvidia,enable-input: Integer. Enable the pin's input path. 0: no, 1: yes. -- nvidia,open-drain: Integer. Enable open drain mode. 0: no, 1: yes. -- nvidia,lock: Integer. Lock the pin configuration against further changes - until reset. 0: no, 1: yes. -- nvidia,io-reset: Integer. Reset the IO path. 0: no, 1: yes. - -As with Tegra20, see the Tegra TRM for complete details regarding which groups -support which functionality. - -Valid values for pin and group names are: - - per-pin mux groups: - - These all support nvidia,function, nvidia,tristate, nvidia,pull, - nvidia,enable-input, nvidia,lock. Some support nvidia,open-drain, - nvidia,io-reset. - - clk_32k_out_pa0, uart3_cts_n_pa1, dap2_fs_pa2, dap2_sclk_pa3, - dap2_din_pa4, dap2_dout_pa5, sdmmc3_clk_pa6, sdmmc3_cmd_pa7, gmi_a17_pb0, - gmi_a18_pb1, lcd_pwr0_pb2, lcd_pclk_pb3, sdmmc3_dat3_pb4, sdmmc3_dat2_pb5, - sdmmc3_dat1_pb6, sdmmc3_dat0_pb7, uart3_rts_n_pc0, lcd_pwr1_pc1, - uart2_txd_pc2, uart2_rxd_pc3, gen1_i2c_scl_pc4, gen1_i2c_sda_pc5, - lcd_pwr2_pc6, gmi_wp_n_pc7, sdmmc3_dat5_pd0, sdmmc3_dat4_pd1, lcd_dc1_pd2, - sdmmc3_dat6_pd3, sdmmc3_dat7_pd4, vi_d1_pd5, vi_vsync_pd6, vi_hsync_pd7, - lcd_d0_pe0, lcd_d1_pe1, lcd_d2_pe2, lcd_d3_pe3, lcd_d4_pe4, lcd_d5_pe5, - lcd_d6_pe6, lcd_d7_pe7, lcd_d8_pf0, lcd_d9_pf1, lcd_d10_pf2, lcd_d11_pf3, - lcd_d12_pf4, lcd_d13_pf5, lcd_d14_pf6, lcd_d15_pf7, gmi_ad0_pg0, - gmi_ad1_pg1, gmi_ad2_pg2, gmi_ad3_pg3, gmi_ad4_pg4, gmi_ad5_pg5, - gmi_ad6_pg6, gmi_ad7_pg7, gmi_ad8_ph0, gmi_ad9_ph1, gmi_ad10_ph2, - gmi_ad11_ph3, gmi_ad12_ph4, gmi_ad13_ph5, gmi_ad14_ph6, gmi_ad15_ph7, - gmi_wr_n_pi0, gmi_oe_n_pi1, gmi_dqs_pi2, gmi_cs6_n_pi3, gmi_rst_n_pi4, - gmi_iordy_pi5, gmi_cs7_n_pi6, gmi_wait_pi7, gmi_cs0_n_pj0, lcd_de_pj1, - gmi_cs1_n_pj2, lcd_hsync_pj3, lcd_vsync_pj4, uart2_cts_n_pj5, - uart2_rts_n_pj6, gmi_a16_pj7, gmi_adv_n_pk0, gmi_clk_pk1, gmi_cs4_n_pk2, - gmi_cs2_n_pk3, gmi_cs3_n_pk4, spdif_out_pk5, spdif_in_pk6, gmi_a19_pk7, - vi_d2_pl0, vi_d3_pl1, vi_d4_pl2, vi_d5_pl3, vi_d6_pl4, vi_d7_pl5, - vi_d8_pl6, vi_d9_pl7, lcd_d16_pm0, lcd_d17_pm1, lcd_d18_pm2, lcd_d19_pm3, - lcd_d20_pm4, lcd_d21_pm5, lcd_d22_pm6, lcd_d23_pm7, dap1_fs_pn0, - dap1_din_pn1, dap1_dout_pn2, dap1_sclk_pn3, lcd_cs0_n_pn4, lcd_sdout_pn5, - lcd_dc0_pn6, hdmi_int_pn7, ulpi_data7_po0, ulpi_data0_po1, ulpi_data1_po2, - ulpi_data2_po3, ulpi_data3_po4, ulpi_data4_po5, ulpi_data5_po6, - ulpi_data6_po7, dap3_fs_pp0, dap3_din_pp1, dap3_dout_pp2, dap3_sclk_pp3, - dap4_fs_pp4, dap4_din_pp5, dap4_dout_pp6, dap4_sclk_pp7, kb_col0_pq0, - kb_col1_pq1, kb_col2_pq2, kb_col3_pq3, kb_col4_pq4, kb_col5_pq5, - kb_col6_pq6, kb_col7_pq7, kb_row0_pr0, kb_row1_pr1, kb_row2_pr2, - kb_row3_pr3, kb_row4_pr4, kb_row5_pr5, kb_row6_pr6, kb_row7_pr7, - kb_row8_ps0, kb_row9_ps1, kb_row10_ps2, kb_row11_ps3, kb_row12_ps4, - kb_row13_ps5, kb_row14_ps6, kb_row15_ps7, vi_pclk_pt0, vi_mclk_pt1, - vi_d10_pt2, vi_d11_pt3, vi_d0_pt4, gen2_i2c_scl_pt5, gen2_i2c_sda_pt6, - sdmmc4_cmd_pt7, pu0, pu1, pu2, pu3, pu4, pu5, pu6, jtag_rtck_pu7, pv0, - pv1, pv2, pv3, ddc_scl_pv4, ddc_sda_pv5, crt_hsync_pv6, crt_vsync_pv7, - lcd_cs1_n_pw0, lcd_m1_pw1, spi2_cs1_n_pw2, spi2_cs2_n_pw3, clk1_out_pw4, - clk2_out_pw5, uart3_txd_pw6, uart3_rxd_pw7, spi2_mosi_px0, spi2_miso_px1, - spi2_sck_px2, spi2_cs0_n_px3, spi1_mosi_px4, spi1_sck_px5, spi1_cs0_n_px6, - spi1_miso_px7, ulpi_clk_py0, ulpi_dir_py1, ulpi_nxt_py2, ulpi_stp_py3, - sdmmc1_dat3_py4, sdmmc1_dat2_py5, sdmmc1_dat1_py6, sdmmc1_dat0_py7, - sdmmc1_clk_pz0, sdmmc1_cmd_pz1, lcd_sdin_pz2, lcd_wr_n_pz3, lcd_sck_pz4, - sys_clk_req_pz5, pwr_i2c_scl_pz6, pwr_i2c_sda_pz7, sdmmc4_dat0_paa0, - sdmmc4_dat1_paa1, sdmmc4_dat2_paa2, sdmmc4_dat3_paa3, sdmmc4_dat4_paa4, - sdmmc4_dat5_paa5, sdmmc4_dat6_paa6, sdmmc4_dat7_paa7, pbb0, - cam_i2c_scl_pbb1, cam_i2c_sda_pbb2, pbb3, pbb4, pbb5, pbb6, pbb7, - cam_mclk_pcc0, pcc1, pcc2, sdmmc4_rst_n_pcc3, sdmmc4_clk_pcc4, - clk2_req_pcc5, pex_l2_rst_n_pcc6, pex_l2_clkreq_n_pcc7, - pex_l0_prsnt_n_pdd0, pex_l0_rst_n_pdd1, pex_l0_clkreq_n_pdd2, - pex_wake_n_pdd3, pex_l1_prsnt_n_pdd4, pex_l1_rst_n_pdd5, - pex_l1_clkreq_n_pdd6, pex_l2_prsnt_n_pdd7, clk3_out_pee0, clk3_req_pee1, - clk1_req_pee2, hdmi_cec_pee3, clk_32k_in, core_pwr_req, cpu_pwr_req, owr, - pwr_int_n. - - drive groups: - - These all support nvidia,pull-down-strength, nvidia,pull-up-strength, - nvidia,slew-rate-rising, nvidia,slew-rate-falling. Most but not all - support nvidia,high-speed-mode, nvidia,schmitt, nvidia,low-power-mode. - - ao1, ao2, at1, at2, at3, at4, at5, cdev1, cdev2, cec, crt, csus, dap1, - dap2, dap3, dap4, dbg, ddc, dev3, gma, gmb, gmc, gmd, gme, gmf, gmg, - gmh, gpv, lcd1, lcd2, owr, sdio1, sdio2, sdio3, spi, uaa, uab, uart2, - uart3, uda, vi1. - -Valid values for nvidia,functions are: - - blink, cec, clk_12m_out, clk_32k_in, core_pwr_req, cpu_pwr_req, crt, - dap, ddr, dev3, displaya, displayb, dtv, extperiph1, extperiph2, - extperiph3, gmi, gmi_alt, hda, hdcp, hdmi, hsi, i2c1, i2c2, i2c3, - i2c4, i2cpwr, i2s0, i2s1, i2s2, i2s3, i2s4, invalid, kbc, mio, nand, - nand_alt, owr, pcie, pwm0, pwm1, pwm2, pwm3, pwr_int_n, rsvd1, rsvd2, - rsvd3, rsvd4, rtck, sata, sdmmc1, sdmmc2, sdmmc3, sdmmc4, spdif, spi1, - spi2, spi2_alt, spi3, spi4, spi5, spi6, sysclk, test, trace, uarta, - uartb, uartc, uartd, uarte, ulpi, vgp1, vgp2, vgp3, vgp4, vgp5, vgp6, - vi, vi_alt1, vi_alt2, vi_alt3 - -Example: - - pinctrl@70000000 { - compatible = "nvidia,tegra30-pinmux"; - reg = < 0x70000868 0xd0 /* Pad control registers */ - 0x70003000 0x3e0 >; /* Mux registers */ - }; - -Example board file extract: - - pinctrl@70000000 { - sdmmc4_default: pinmux { - sdmmc4_clk_pcc4 { - nvidia,pins = "sdmmc4_clk_pcc4", - "sdmmc4_rst_n_pcc3"; - nvidia,function = "sdmmc4"; - nvidia,pull = <0>; - nvidia,tristate = <0>; - }; - sdmmc4_dat0_paa0 { - nvidia,pins = "sdmmc4_dat0_paa0", - "sdmmc4_dat1_paa1", - "sdmmc4_dat2_paa2", - "sdmmc4_dat3_paa3", - "sdmmc4_dat4_paa4", - "sdmmc4_dat5_paa5", - "sdmmc4_dat6_paa6", - "sdmmc4_dat7_paa7"; - nvidia,function = "sdmmc4"; - nvidia,pull = <2>; - nvidia,tristate = <0>; - }; - }; - }; - - sdhci@78000400 { - pinctrl-names = "default"; - pinctrl-0 = <&sdmmc4_default>; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra30-pinmux.yaml b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra30-pinmux.yaml new file mode 100644 index 000000000000..c0eda7848767 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra30-pinmux.yaml @@ -0,0 +1,176 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/nvidia,tegra30-pinmux.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra30 pinmux Controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + const: nvidia,tegra30-pinmux + + reg: + items: + - description: pad control registers + - description: mux registers + +patternProperties: + "^pinmux(-[a-z0-9-_]+)?$": + type: object + properties: + phandle: true + + # pin groups + additionalProperties: + $ref: nvidia,tegra-pinmux-common.yaml + additionalProperties: false + properties: + nvidia,pins: + items: + enum: [ clk_32k_out_pa0, uart3_cts_n_pa1, dap2_fs_pa2, + dap2_sclk_pa3, dap2_din_pa4, dap2_dout_pa5, sdmmc3_clk_pa6, + sdmmc3_cmd_pa7, gmi_a17_pb0, gmi_a18_pb1, lcd_pwr0_pb2, + lcd_pclk_pb3, sdmmc3_dat3_pb4, sdmmc3_dat2_pb5, + sdmmc3_dat1_pb6, sdmmc3_dat0_pb7, uart3_rts_n_pc0, + lcd_pwr1_pc1, uart2_txd_pc2, uart2_rxd_pc3, + gen1_i2c_scl_pc4, gen1_i2c_sda_pc5, lcd_pwr2_pc6, + gmi_wp_n_pc7, sdmmc3_dat5_pd0, sdmmc3_dat4_pd1, + lcd_dc1_pd2, sdmmc3_dat6_pd3, sdmmc3_dat7_pd4, vi_d1_pd5, + vi_vsync_pd6, vi_hsync_pd7, lcd_d0_pe0, lcd_d1_pe1, + lcd_d2_pe2, lcd_d3_pe3, lcd_d4_pe4, lcd_d5_pe5, lcd_d6_pe6, + lcd_d7_pe7, lcd_d8_pf0, lcd_d9_pf1, lcd_d10_pf2, + lcd_d11_pf3, lcd_d12_pf4, lcd_d13_pf5, lcd_d14_pf6, + lcd_d15_pf7, gmi_ad0_pg0, gmi_ad1_pg1, gmi_ad2_pg2, + gmi_ad3_pg3, gmi_ad4_pg4, gmi_ad5_pg5, gmi_ad6_pg6, + gmi_ad7_pg7, gmi_ad8_ph0, gmi_ad9_ph1, gmi_ad10_ph2, + gmi_ad11_ph3, gmi_ad12_ph4, gmi_ad13_ph5, gmi_ad14_ph6, + gmi_ad15_ph7, gmi_wr_n_pi0, gmi_oe_n_pi1, gmi_dqs_pi2, + gmi_cs6_n_pi3, gmi_rst_n_pi4, gmi_iordy_pi5, gmi_cs7_n_pi6, + gmi_wait_pi7, gmi_cs0_n_pj0, lcd_de_pj1, gmi_cs1_n_pj2, + lcd_hsync_pj3, lcd_vsync_pj4, uart2_cts_n_pj5, + uart2_rts_n_pj6, gmi_a16_pj7, gmi_adv_n_pk0, gmi_clk_pk1, + gmi_cs4_n_pk2, gmi_cs2_n_pk3, gmi_cs3_n_pk4, spdif_out_pk5, + spdif_in_pk6, gmi_a19_pk7, vi_d2_pl0, vi_d3_pl1, vi_d4_pl2, + vi_d5_pl3, vi_d6_pl4, vi_d7_pl5, vi_d8_pl6, vi_d9_pl7, + lcd_d16_pm0, lcd_d17_pm1, lcd_d18_pm2, lcd_d19_pm3, + lcd_d20_pm4, lcd_d21_pm5, lcd_d22_pm6, lcd_d23_pm7, + dap1_fs_pn0, dap1_din_pn1, dap1_dout_pn2, dap1_sclk_pn3, + lcd_cs0_n_pn4, lcd_sdout_pn5, lcd_dc0_pn6, hdmi_int_pn7, + ulpi_data7_po0, ulpi_data0_po1, ulpi_data1_po2, + ulpi_data2_po3, ulpi_data3_po4, ulpi_data4_po5, + ulpi_data5_po6, ulpi_data6_po7, dap3_fs_pp0, dap3_din_pp1, + dap3_dout_pp2, dap3_sclk_pp3, dap4_fs_pp4, dap4_din_pp5, + dap4_dout_pp6, dap4_sclk_pp7, kb_col0_pq0, kb_col1_pq1, + kb_col2_pq2, kb_col3_pq3, kb_col4_pq4, kb_col5_pq5, + kb_col6_pq6, kb_col7_pq7, kb_row0_pr0, kb_row1_pr1, + kb_row2_pr2, kb_row3_pr3, kb_row4_pr4, kb_row5_pr5, + kb_row6_pr6, kb_row7_pr7, kb_row8_ps0, kb_row9_ps1, + kb_row10_ps2, kb_row11_ps3, kb_row12_ps4, kb_row13_ps5, + kb_row14_ps6, kb_row15_ps7, vi_pclk_pt0, vi_mclk_pt1, + vi_d10_pt2, vi_d11_pt3, vi_d0_pt4, gen2_i2c_scl_pt5, + gen2_i2c_sda_pt6, sdmmc4_cmd_pt7, pu0, pu1, pu2, pu3, pu4, + pu5, pu6, jtag_rtck_pu7, pv0, pv1, pv2, pv3, ddc_scl_pv4, + ddc_sda_pv5, crt_hsync_pv6, crt_vsync_pv7, lcd_cs1_n_pw0, + lcd_m1_pw1, spi2_cs1_n_pw2, spi2_cs2_n_pw3, clk1_out_pw4, + clk2_out_pw5, uart3_txd_pw6, uart3_rxd_pw7, spi2_mosi_px0, + spi2_miso_px1, spi2_sck_px2, spi2_cs0_n_px3, spi1_mosi_px4, + spi1_sck_px5, spi1_cs0_n_px6, spi1_miso_px7, ulpi_clk_py0, + ulpi_dir_py1, ulpi_nxt_py2, ulpi_stp_py3, sdmmc1_dat3_py4, + sdmmc1_dat2_py5, sdmmc1_dat1_py6, sdmmc1_dat0_py7, + sdmmc1_clk_pz0, sdmmc1_cmd_pz1, lcd_sdin_pz2, lcd_wr_n_pz3, + lcd_sck_pz4, sys_clk_req_pz5, pwr_i2c_scl_pz6, + pwr_i2c_sda_pz7, sdmmc4_dat0_paa0, sdmmc4_dat1_paa1, + sdmmc4_dat2_paa2, sdmmc4_dat3_paa3, sdmmc4_dat4_paa4, + sdmmc4_dat5_paa5, sdmmc4_dat6_paa6, sdmmc4_dat7_paa7, pbb0, + cam_i2c_scl_pbb1, cam_i2c_sda_pbb2, pbb3, pbb4, pbb5, pbb6, + pbb7, cam_mclk_pcc0, pcc1, pcc2, sdmmc4_rst_n_pcc3, + sdmmc4_clk_pcc4, clk2_req_pcc5, pex_l2_rst_n_pcc6, + pex_l2_clkreq_n_pcc7, pex_l0_prsnt_n_pdd0, + pex_l0_rst_n_pdd1, pex_l0_clkreq_n_pdd2, pex_wake_n_pdd3, + pex_l1_prsnt_n_pdd4, pex_l1_rst_n_pdd5, + pex_l1_clkreq_n_pdd6, pex_l2_prsnt_n_pdd7, clk3_out_pee0, + clk3_req_pee1, clk1_req_pee2, hdmi_cec_pee3, clk_32k_in, + core_pwr_req, cpu_pwr_req, owr, pwr_int_n, + # drive groups + drive_ao1, drive_ao2, drive_at1, drive_at2, drive_at3, + drive_at4, drive_at5, drive_cdev1, drive_cdev2, drive_cec, + drive_crt, drive_csus, drive_dap1, drive_dap2, drive_dap3, + drive_dap4, drive_dbg, drive_ddc, drive_dev3, drive_gma, + drive_gmb, drive_gmc, drive_gmd, drive_gme, drive_gmf, + drive_gmg, drive_gmh, drive_gpv, drive_lcd1, drive_lcd2, + drive_owr, drive_sdio1, drive_sdio2, drive_sdio3, + drive_spi, drive_uaa, drive_uab, drive_uart2, drive_uart3, + drive_uda, drive_vi1 ] + + nvidia,function: + enum: [ blink, cec, clk_12m_out, clk_32k_in, core_pwr_req, + cpu_pwr_req, crt, dap, ddr, dev3, displaya, displayb, dtv, + extperiph1, extperiph2, extperiph3, gmi, gmi_alt, hda, hdcp, + hdmi, hsi, i2c1, i2c2, i2c3, i2c4, i2cpwr, i2s0, i2s1, i2s2, + i2s3, i2s4, invalid, kbc, mio, nand, nand_alt, owr, pcie, + pwm0, pwm1, pwm2, pwm3, pwr_int_n, rsvd1, rsvd2, rsvd3, + rsvd4, rtck, sata, sdmmc1, sdmmc2, sdmmc3, sdmmc4, spdif, + spi1, spi2, spi2_alt, spi3, spi4, spi5, spi6, sysclk, test, + trace, uarta, uartb, uartc, uartd, uarte, ulpi, vgp1, vgp2, + vgp3, vgp4, vgp5, vgp6, vi, vi_alt1, vi_alt2, vi_alt3 ] + + nvidia,pull: true + nvidia,tristate: true + nvidia,schmitt: true + nvidia,pull-down-strength: true + nvidia,pull-up-strength: true + nvidia,high-speed-mode: true + nvidia,low-power-mode: true + nvidia,enable-input: true + nvidia,open-drain: true + nvidia,lock: true + nvidia,io-reset: true + nvidia,slew-rate-rising: true + nvidia,slew-rate-falling: true + + required: + - nvidia,pins + +additionalProperties: false + +required: + - compatible + - reg + +examples: + - | + pinctrl@70000000 { + compatible = "nvidia,tegra30-pinmux"; + reg = <0x70000868 0x0d0>, /* Pad control registers */ + <0x70003000 0x3e0>; /* Mux registers */ + + pinmux { + sdmmc4_clk_pcc4 { + nvidia,pins = "sdmmc4_clk_pcc4", + "sdmmc4_rst_n_pcc3"; + nvidia,function = "sdmmc4"; + nvidia,pull = <0>; + nvidia,tristate = <0>; + }; + + sdmmc4_dat0_paa0 { + nvidia,pins = "sdmmc4_dat0_paa0", + "sdmmc4_dat1_paa1", + "sdmmc4_dat2_paa2", + "sdmmc4_dat3_paa3", + "sdmmc4_dat4_paa4", + "sdmmc4_dat5_paa5", + "sdmmc4_dat6_paa6", + "sdmmc4_dat7_paa7"; + nvidia,function = "sdmmc4"; + nvidia,pull = <2>; + nvidia,tristate = <0>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-sx150x.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-sx150x.txt deleted file mode 100644 index 4023bad2fe39..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-sx150x.txt +++ /dev/null @@ -1,72 +0,0 @@ -SEMTECH SX150x GPIO expander bindings - -Please refer to pinctrl-bindings.txt, ../gpio/gpio.txt, and -../interrupt-controller/interrupts.txt for generic information regarding -pin controller, GPIO, and interrupt bindings. - -Required properties: -- compatible: should be one of : - "semtech,sx1501q", - "semtech,sx1502q", - "semtech,sx1503q", - "semtech,sx1504q", - "semtech,sx1505q", - "semtech,sx1506q", - "semtech,sx1507q", - "semtech,sx1508q", - "semtech,sx1509q". - -- reg: The I2C slave address for this device. - -- #gpio-cells: Should be 2. The first cell is the GPIO number and the - second cell is used to specify optional parameters: - bit 0: polarity (0: normal, 1: inverted) - -- gpio-controller: Marks the device as a GPIO controller. - -Optional properties : -- interrupts: Interrupt specifier for the controllers interrupt. - -- interrupt-controller: Marks the device as a interrupt controller. - -- semtech,probe-reset: Will trigger a reset of the GPIO expander on probe, - only for sx1507q, sx1508q and sx1509q - -The GPIO expander can optionally be used as an interrupt controller, in -which case it uses the default two cell specifier. - -Required properties for pin configuration sub-nodes: - - pins: List of pins to which the configuration applies. - -Optional properties for pin configuration sub-nodes: ----------------------------------------------------- - - bias-disable: disable any pin bias, except the OSCIO pin - - bias-pull-up: pull up the pin, except the OSCIO pin - - bias-pull-down: pull down the pin, except the OSCIO pin - - bias-pull-pin-default: use pin-default pull state, except the OSCIO pin - - drive-push-pull: drive actively high and low - - drive-open-drain: drive with open drain only for sx1507q, sx1508q and sx1509q and except the OSCIO pin - - output-low: set the pin to output mode with low level - - output-high: set the pin to output mode with high level - -Example: - - i2c0gpio-expander@20{ - #gpio-cells = <2>; - #interrupt-cells = <2>; - compatible = "semtech,sx1506q"; - reg = <0x20>; - interrupt-parent = <&gpio_1>; - interrupts = <16 0>; - - gpio-controller; - interrupt-controller; - - pinctrl-names = "default"; - pinctrl-0 = <&gpio1_cfg_pins>; - - gpio1_cfg_pins: gpio1-cfg { - pins = "gpio1"; - bias-pull-up; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,ipq6018-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,ipq6018-pinctrl.yaml index 931e5c190ead..93f231c7a3b4 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,ipq6018-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,ipq6018-pinctrl.yaml @@ -7,11 +7,10 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. IPQ6018 TLMM block maintainers: - - Sricharan R <sricharan@codeaurora.org> + - Bjorn Andersson <andersson@kernel.org> -description: | - This binding describes the Top Level Mode Multiplexer block found in the - IPQ6018 platform. +description: + Top Level Mode Multiplexer pin controller in Qualcomm IPQ6018 SoC. properties: compatible: @@ -20,36 +19,28 @@ properties: reg: maxItems: 1 - interrupts: - description: Specifies the TLMM summary IRQ - maxItems: 1 - + interrupts: true interrupt-controller: true - - '#interrupt-cells': - description: - Specifies the PIN numbers and Flags, as defined in defined in - include/dt-bindings/interrupt-controller/irq.h - const: 2 - + "#interrupt-cells": true gpio-controller: true + "#gpio-cells": true + gpio-ranges: 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 - -#PIN CONFIGURATION NODES patternProperties: - '-pinmux$': - type: object + "-state$": + oneOf: + - $ref: "#/$defs/qcom-ipq6018-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-ipq6018-tlmm-state" + additionalProperties: false + +$defs: + qcom-ipq6018-tlmm-state: 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" + $ref: qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state properties: pins: @@ -63,7 +54,7 @@ patternProperties: sdc2_data, qdsd_cmd, qdsd_data0, qdsd_data1, qdsd_data2, qdsd_data3 ] minItems: 1 - maxItems: 4 + maxItems: 16 function: description: @@ -72,12 +63,12 @@ patternProperties: enum: [ adsp_ext, alsp_int, atest_bbrx0, atest_bbrx1, atest_char, atest_char0, atest_char1, atest_char2, atest_char3, atest_combodac, atest_gpsadc0, atest_gpsadc1, atest_tsens, atest_wlan0, - atest_wlan1, backlight_en, bimc_dte0, bimc_dte1, blsp1_i2c, - blsp2_i2c, blsp3_i2c, blsp4_i2c, blsp5_i2c, blsp6_i2c, blsp1_spi, + atest_wlan1, backlight_en, bimc_dte0, bimc_dte1, blsp0_i2c, blsp1_i2c, + blsp2_i2c, blsp3_i2c, blsp4_i2c, blsp5_i2c, blsp0_spi, blsp1_spi, blsp1_spi_cs1, blsp1_spi_cs2, blsp1_spi_cs3, blsp2_spi, blsp2_spi_cs1, blsp2_spi_cs2, blsp2_spi_cs3, blsp3_spi, blsp3_spi_cs1, blsp3_spi_cs2, blsp3_spi_cs3, blsp4_spi, blsp5_spi, - blsp6_spi, blsp1_uart, blsp2_uart, blsp1_uim, blsp2_uim, cam1_rst, + blsp0_uart, blsp1_uart, blsp2_uart, blsp1_uim, blsp2_uim, cam1_rst, cam1_standby, cam_mclk0, cam_mclk1, cci_async, cci_i2c, cci_timer0, cci_timer1, cci_timer2, cdc_pdm0, codec_mad, dbg_out, display_5v, dmic0_clk, dmic0_data, dsi_rst, ebi0_wrcdc, euro_us, ext_lpass, @@ -92,64 +83,48 @@ patternProperties: qdss_ctitrig_in_b0, qdss_ctitrig_in_b1, qdss_ctitrig_out_a0, qdss_ctitrig_out_a1, qdss_ctitrig_out_b0, qdss_ctitrig_out_b1, qdss_traceclk_a, qdss_traceclk_b, qdss_tracectl_a, qdss_tracectl_b, - qdss_tracedata_a, qdss_tracedata_b, reset_n, sd_card, sd_write, - sec_mi2s, smb_int, ssbi_wtr0, ssbi_wtr1, uim1, uim2, uim3, - uim_batt, wcss_bt, wcss_fm, wcss_wlan, webcam1_rst ] - - drive-strength: - enum: [2, 4, 6, 8, 10, 12, 14, 16] - default: 2 - description: - Selects the drive strength for the specified pins, in mA. + qdss_tracedata_a, qdss_tracedata_b, qpic_pad, reset_n, sd_card, + sd_write, sec_mi2s, smb_int, ssbi_wtr0, ssbi_wtr1, uim1, uim2, + uim3, uim_batt, wcss_bt, wcss_fm, wcss_wlan, webcam1_rst ] bias-pull-down: true - bias-pull-up: true - bias-disable: true - + drive-strength: true output-high: true - output-low: true required: - pins - - function additionalProperties: false allOf: - - $ref: "pinctrl.yaml#" + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# required: - compatible - reg - - interrupts - - interrupt-controller - - '#interrupt-cells' - - gpio-controller - - '#gpio-cells' - - gpio-ranges additionalProperties: false examples: - | - #include <dt-bindings/interrupt-controller/arm-gic.h> - tlmm: pinctrl@1000000 { - compatible = "qcom,ipq6018-pinctrl"; - reg = <0x01000000 0x300000>; - interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; - interrupt-controller; - #interrupt-cells = <2>; - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&tlmm 0 0 80>; - - serial3-pinmux { - pins = "gpio44", "gpio45"; - function = "blsp2_uart"; - drive-strength = <8>; - bias-pull-down; - }; + #include <dt-bindings/interrupt-controller/arm-gic.h> + tlmm: pinctrl@1000000 { + compatible = "qcom,ipq6018-pinctrl"; + reg = <0x01000000 0x300000>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&tlmm 0 0 80>; + + serial3-state { + pins = "gpio44", "gpio45"; + function = "blsp2_uart"; + drive-strength = <8>; + bias-pull-down; }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.txt deleted file mode 100644 index 7b151894f5a0..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.txt +++ /dev/null @@ -1,181 +0,0 @@ -Qualcomm Technologies, Inc. IPQ8074 TLMM block - -This binding describes the Top Level Mode Multiplexer block found in the -IPQ8074 platform. - -- compatible: - Usage: required - Value type: <string> - Definition: must be "qcom,ipq8074-pinctrl" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: the base address and size of the TLMM register space. - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: should specify the TLMM summary IRQ. - -- interrupt-controller: - Usage: required - Value type: <none> - Definition: identifies this node as an interrupt controller - -- #interrupt-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/interrupt-controller/irq.h> - -- gpio-controller: - Usage: required - Value type: <none> - Definition: identifies this node as a gpio controller - -- #gpio-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/gpio/gpio.h> - -- gpio-ranges: - Usage: required - Definition: see ../gpio/gpio.txt - -- gpio-reserved-ranges: - Usage: optional - Definition: see ../gpio/gpio.txt - -Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for -a general description of GPIO and interrupt bindings. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -The pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - - -PIN CONFIGURATION NODES: - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. - - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pin configuration subnode: - -- pins: - Usage: required - Value type: <string-array> - Definition: List of gpio pins affected by the properties specified in - this subnode. Valid pins are: - gpio0-gpio69 - -- function: - Usage: required - Value type: <string> - Definition: Specify the alternative function to be configured for the - specified pins. Functions are only valid for gpio pins. - Valid values are: - atest_char, atest_char0, atest_char1, atest_char2, - atest_char3, audio_rxbclk, audio_rxd, audio_rxfsync, - audio_rxmclk, audio_txbclk, audio_txd, audio_txfsync, - audio_txmclk, blsp0_i2c, blsp0_spi, blsp0_uart, blsp1_i2c, - blsp1_spi, blsp1_uart, blsp2_i2c, blsp2_spi, blsp2_uart, - blsp3_i2c, blsp3_spi, blsp3_spi0, blsp3_spi1, blsp3_spi2, - blsp3_spi3, blsp3_uart, blsp4_i2c0, blsp4_i2c1, blsp4_spi0, - blsp4_spi1, blsp4_uart0, blsp4_uart1, blsp5_i2c, blsp5_spi, - blsp5_uart, burn0, burn1, cri_trng, cri_trng0, cri_trng1, - cxc0, cxc1, dbg_out, gcc_plltest, gcc_tlmm, gpio, ldo_en, - ldo_update, led0, led1, led2, mac0_sa0, mac0_sa1, mac1_sa0, - mac1_sa1, mac1_sa2, mac1_sa3, mac2_sa0, mac2_sa1, mdc, - mdio, pcie0_clk, pcie0_rst, pcie0_wake, pcie1_clk, - pcie1_rst, pcie1_wake, pcm_drx, pcm_dtx, pcm_fsync, - pcm_pclk, pcm_zsi0, pcm_zsi1, prng_rosc, pta1_0, pta1_1, - pta1_2, pta2_0, pta2_1, pta2_2, 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, - qpic, rx0, rx1, rx2, sd_card, sd_write, tsens_max, wci2a, - wci2b, wci2c, wci2d - -- bias-disable: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as no pull. - -- bias-pull-down: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull down. - -- bias-pull-up: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull up. - -- output-high: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - high. - -- output-low: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - low. - -- drive-strength: - Usage: optional - Value type: <u32> - Definition: Selects the drive strength for the specified pins, in mA. - Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16 - -Example: - - tlmm: pinctrl@1000000 { - compatible = "qcom,ipq8074-pinctrl"; - reg = <0x1000000 0x300000>; - interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&tlmm 0 0 70>; - interrupt-controller; - #interrupt-cells = <2>; - - uart2: uart2-default { - mux { - pins = "gpio23", "gpio24"; - function = "blsp4_uart1"; - }; - - rx { - pins = "gpio23"; - drive-strength = <4>; - bias-disable; - }; - - tx { - pins = "gpio24"; - drive-strength = <2>; - bias-pull-up; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.yaml new file mode 100644 index 000000000000..5687acaf19bf --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.yaml @@ -0,0 +1,135 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,ipq8074-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm IPQ8074 TLMM pin controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in Qualcomm IPQ8074 SoC. + +properties: + compatible: + const: qcom,ipq8074-pinctrl + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 35 + + gpio-line-names: + maxItems: 70 + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-ipq8074-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-ipq8074-tlmm-state" + additionalProperties: false + +$defs: + qcom-ipq8074-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-6][0-9]|70)$" + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ gpio, atest_char, atest_char0, atest_char1, atest_char2, + atest_char3, audio_rxbclk, audio_rxd, audio_rxfsync, + audio_rxmclk, audio_txbclk, audio_txd, audio_txfsync, + audio_txmclk, blsp0_i2c, blsp0_spi, blsp0_uart, blsp1_i2c, + blsp1_spi, blsp1_uart, blsp2_i2c, blsp2_spi, blsp2_uart, + blsp3_i2c, blsp3_spi, blsp3_spi0, blsp3_spi1, blsp3_spi2, + blsp3_spi3, blsp3_uart, blsp4_i2c0, blsp4_i2c1, blsp4_spi0, + blsp4_spi1, blsp4_uart0, blsp4_uart1, blsp5_i2c, blsp5_spi, + blsp5_uart, burn0, burn1, cri_trng, cri_trng0, cri_trng1, cxc0, + cxc1, dbg_out, gcc_plltest, gcc_tlmm, ldo_en, ldo_update, led0, + led1, led2, mac0_sa0, mac0_sa1, mac1_sa0, mac1_sa1, mac1_sa2, + mac1_sa3, mac2_sa0, mac2_sa1, mdc, mdio, pcie0_clk, pcie0_rst, + pcie0_wake, pcie1_clk, pcie1_rst, pcie1_wake, pcm_drx, pcm_dtx, + pcm_fsync, pcm_pclk, pcm_zsi0, pcm_zsi1, prng_rosc, pta1_0, + pta1_1, pta1_2, pta2_0, pta2_1, pta2_2, 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, qpic, rx0, rx1, rx2, sd_card, sd_write, + tsens_max, wci2a, wci2b, wci2c, wci2d ] + + 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 + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + tlmm: pinctrl@1000000 { + compatible = "qcom,ipq8074-pinctrl"; + reg = <0x01000000 0x300000>; + gpio-controller; + #gpio-cells = <0x2>; + gpio-ranges = <&tlmm 0 0 70>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <0x2>; + + serial4-state { + pins = "gpio23", "gpio24"; + function = "blsp4_uart1"; + drive-strength = <8>; + bias-disable; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-tlmm.yaml index f7bd4be1739e..a0a12171b6d0 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-tlmm.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/pinctrl/qcom,mdm9607-pinctrl.yaml# +$id: http://devicetree.org/schemas/pinctrl/qcom,mdm9607-tlmm.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. MDM9607 TLMM block @@ -9,12 +9,10 @@ title: Qualcomm Technologies, Inc. MDM9607 TLMM block maintainers: - Konrad Dybcio <konrad.dybcio@somainline.org> -description: | - This binding describes the Top Level Mode Multiplexer block found in the - MDM9607 platform. +description: + Top Level Mode Multiplexer pin controller in Qualcomm MDM9607 SoC. allOf: - - $ref: "pinctrl.yaml#" - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# properties: @@ -26,10 +24,10 @@ properties: interrupts: true interrupt-controller: true - '#interrupt-cells': true + "#interrupt-cells": true gpio-controller: true gpio-reserved-ranges: true - '#gpio-cells': true + "#gpio-cells": true gpio-ranges: true wakeup-parent: true @@ -40,20 +38,20 @@ required: additionalProperties: false patternProperties: - '-state$': + "-state$": oneOf: - $ref: "#/$defs/qcom-mdm9607-tlmm-state" - patternProperties: ".*": $ref: "#/$defs/qcom-mdm9607-tlmm-state" -'$defs': +$defs: qcom-mdm9607-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" + $ref: qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state properties: pins: @@ -115,20 +113,19 @@ patternProperties: required: - pins - - function additionalProperties: false examples: - | - #include <dt-bindings/interrupt-controller/arm-gic.h> - tlmm: pinctrl@1000000 { - compatible = "qcom,mdm9607-tlmm"; - reg = <0x01000000 0x300000>; - interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - gpio-ranges = <&msmgpio 0 0 80>; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; - }; + #include <dt-bindings/interrupt-controller/arm-gic.h> + tlmm: pinctrl@1000000 { + compatible = "qcom,mdm9607-tlmm"; + reg = <0x01000000 0x300000>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + gpio-ranges = <&msmgpio 0 0 80>; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.txt deleted file mode 100644 index d46973968873..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.txt +++ /dev/null @@ -1,161 +0,0 @@ -Qualcomm MDM9615 TLMM block - -This binding describes the Top Level Mode Multiplexer block found in the -MDM9615 platform. - -- compatible: - Usage: required - Value type: <string> - Definition: must be "qcom,mdm9615-pinctrl" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: the base address and size of the TLMM register space. - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: should specify the TLMM summary IRQ. - -- interrupt-controller: - Usage: required - Value type: <none> - Definition: identifies this node as an interrupt controller - -- #interrupt-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/interrupt-controller/irq.h> - -- gpio-controller: - Usage: required - Value type: <none> - Definition: identifies this node as a gpio controller - -- #gpio-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/gpio/gpio.h> - -- gpio-ranges: - Usage: required - Definition: see ../gpio/gpio.txt - -- gpio-reserved-ranges: - Usage: optional - Definition: see ../gpio/gpio.txt - -Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for -a general description of GPIO and interrupt bindings. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -The pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - - -PIN CONFIGURATION NODES: - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. - - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pin configuration subnode: - -- pins: - Usage: required - Value type: <string-array> - Definition: List of gpio pins affected by the properties specified in - this subnode. Valid pins are: - gpio0-gpio87 - -- function: - Usage: required - Value type: <string> - Definition: Specify the alternative function to be configured for the - specified pins. - Valid values are: - gpio, gsbi2_i2c, gsbi3, gsbi4, gsbi5_i2c, gsbi5_uart, - sdc2, ebi2_lcdc, ps_hold, prim_audio, sec_audio, - cdc_mclk - -- bias-disable: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as no pull. - -- bias-pull-down: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull down. - -- bias-pull-up: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull up. - -- output-high: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - high. - -- output-low: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - low. - -- drive-strength: - Usage: optional - Value type: <u32> - Definition: Selects the drive strength for the specified pins, in mA. - Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16 - -Example: - - msmgpio: pinctrl@800000 { - compatible = "qcom,mdm9615-pinctrl"; - reg = <0x800000 0x4000>; - - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&msmgpio 0 0 88>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = <0 16 0x4>; - - gsbi8_uart: gsbi8-uart { - mux { - pins = "gpio34", "gpio35"; - function = "gsbi8"; - }; - - tx { - pins = "gpio34"; - drive-strength = <4>; - bias-disable; - }; - - rx { - pins = "gpio35"; - drive-strength = <2>; - bias-pull-up; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.yaml new file mode 100644 index 000000000000..a4f6e4c588f4 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.yaml @@ -0,0 +1,119 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,mdm9615-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. MDM9615 TLMM block + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + +description: Top Level Mode Multiplexer pin controller in Qualcomm MDM9615 SoC. + +$ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +properties: + compatible: + const: qcom,mdm9615-pinctrl + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + '#interrupt-cells': true + gpio-controller: true + '#gpio-cells': true + gpio-ranges: true + +required: + - compatible + - reg + +additionalProperties: false + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-mdm9615-pinctrl-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-mdm9615-pinctrl-state" + additionalProperties: false + +$defs: + qcom-mdm9615-pinctrl-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-7][0-9]|8[0-7])$" + minItems: 1 + maxItems: 16 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ gpio, gsbi2_i2c, gsbi3, gsbi4, gsbi5_i2c, gsbi5_uart, + sdc2, ebi2_lcdc, ps_hold, prim_audio, sec_audio, cdc_mclk, ] + + bias-disable: true + bias-pull-down: true + bias-pull-up: true + drive-strength: true + output-high: true + output-low: true + input-enable: true + + required: + - pins + + additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + tlmm: pinctrl@1000000 { + compatible = "qcom,mdm9615-pinctrl"; + reg = <0x01000000 0x300000>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + gpio-ranges = <&msmgpio 0 0 88>; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + + gsbi3-state { + pins = "gpio8", "gpio9", "gpio10", "gpio11"; + function = "gsbi3"; + drive-strength = <8>; + bias-disable; + }; + + gsbi5-i2c-state { + sda-pins { + pins = "gpio16"; + function = "gsbi5_i2c"; + drive-strength = <8>; + bias-disable; + }; + + scl-pins { + pins = "gpio17"; + function = "gsbi5_i2c"; + drive-strength = <2>; + bias-disable; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml index ab4a2b4cfda2..3b79f5be860b 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml @@ -9,9 +9,8 @@ title: Qualcomm Technologies, Inc. MSM8226 TLMM block maintainers: - Bjorn Andersson <bjorn.andersson@linaro.org> -description: | - This binding describes the Top Level Mode Multiplexer block found in the - MSM8226 platform. +description: + Top Level Mode Multiplexer pin controller in Qualcomm MSM8226 SoC. properties: compatible: @@ -21,38 +20,32 @@ properties: description: Specifies the base address and size of the TLMM register space maxItems: 1 - interrupts: - description: Specifies the TLMM summary IRQ - maxItems: 1 - + interrupts: true interrupt-controller: true - - '#interrupt-cells': - description: Specifies the PIN numbers and Flags, as defined in - include/dt-bindings/interrupt-controller/irq.h - const: 2 - + "#interrupt-cells": true 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 + "#gpio-cells": true + gpio-ranges: true gpio-reserved-ranges: maxItems: 1 -#PIN CONFIGURATION NODES patternProperties: - '-pins$': + "-state$": + oneOf: + - $ref: "#/$defs/qcom-msm8226-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-msm8226-tlmm-state" + additionalProperties: false + +$defs: + qcom-msm8226-tlmm-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" + $ref: qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state properties: pins: @@ -71,65 +64,51 @@ patternProperties: Specify the alternative function to be configured for the specified pins. Functions are only valid for gpio pins. enum: [ gpio, cci_i2c0, blsp_uim1, blsp_uim2, blsp_uim3, blsp_uim5, - blsp_i2c1, blsp_i2c2, blsp_i2c3, blsp_i2c5, blsp_spi1, + 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_uart5, cam_mclk0, cam_mclk1, wlan ] - - drive-strength: - enum: [2, 4, 6, 8, 10, 12, 14, 16] - default: 2 - description: - Selects the drive strength for the specified pins, in mA. + blsp_uart3, blsp_uart4, blsp_uart5, cam_mclk0, cam_mclk1, sdc3, + wlan ] 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 - - function additionalProperties: false allOf: - - $ref: "pinctrl.yaml#" + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# required: - compatible - reg - - interrupts - - interrupt-controller - - '#interrupt-cells' - - gpio-controller - - '#gpio-cells' - - gpio-ranges additionalProperties: false examples: - | - #include <dt-bindings/interrupt-controller/arm-gic.h> - msmgpio: pinctrl@fd510000 { - compatible = "qcom,msm8226-pinctrl"; - reg = <0xfd510000 0x4000>; - - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&msmgpio 0 0 117>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; - - serial-pins { - pins = "gpio8", "gpio9"; - function = "blsp_uart3"; - drive-strength = <8>; - bias-disable; - }; + #include <dt-bindings/interrupt-controller/arm-gic.h> + msmgpio: pinctrl@fd510000 { + compatible = "qcom,msm8226-pinctrl"; + reg = <0xfd510000 0x4000>; + + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&msmgpio 0 0 117>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + + serial-state { + pins = "gpio8", "gpio9"; + function = "blsp_uart3"; + drive-strength = <8>; + bias-disable; }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8660-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8660-pinctrl.txt deleted file mode 100644 index f095209848c8..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8660-pinctrl.txt +++ /dev/null @@ -1,96 +0,0 @@ -Qualcomm MSM8660 TLMM block - -Required properties: -- compatible: "qcom,msm8660-pinctrl" -- reg: Should be the base address and length of the TLMM block. -- interrupts: Should be the parent IRQ of the TLMM block. -- interrupt-controller: Marks the device node as an interrupt controller. -- #interrupt-cells: Should be two. -- gpio-controller: Marks the device node as a GPIO controller. -- #gpio-cells : Should be two. - The first cell is the gpio pin number and the - second cell is used for optional parameters. -- gpio-ranges: see ../gpio/gpio.txt - -Optional properties: - -- gpio-reserved-ranges: see ../gpio/gpio.txt - -Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for -a general description of GPIO and interrupt bindings. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -Qualcomm's pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. - - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pin configuration subnode: - - pins, function, bias-disable, bias-pull-down, bias-pull-up, drive-strength, - output-low, output-high. - -Non-empty subnodes must specify the 'pins' property. - -Valid values for pins are: - gpio0-gpio172, sdc3_clk, sdc3_cmd, sdc3_data sdc4_clk, sdc4_cmd, sdc4_data - -Valid values for function are: - gpio, cam_mclk, dsub, ext_gps, gp_clk_0a, gp_clk_0b, gp_clk_1a, gp_clk_1b, - gp_clk_2a, gp_clk_2b, gp_mn, gsbi1, gsbi1_spi_cs1_n, gsbi1_spi_cs2a_n, - gsbi1_spi_cs2b_n, gsbi1_spi_cs3_n, gsbi2, gsbi2_spi_cs1_n, gsbi2_spi_cs2_n, - gsbi2_spi_cs3_n, gsbi3, gsbi3_spi_cs1_n, gsbi3_spi_cs2_n, gsbi3_spi_cs3_n, - gsbi4, gsbi5, gsbi6, gsbi7, gsbi8, gsbi9, gsbi10, gsbi11, gsbi12, hdmi, i2s, - lcdc, mdp_vsync, mi2s, pcm, ps_hold, sdc1, sdc2, sdc5, tsif1, tsif2, usb_fs1, - usb_fs1_oe_n, usb_fs2, usb_fs2_oe_n, vfe, vsens_alarm, ebi2, ebi2cs - -Example: - - msmgpio: pinctrl@800000 { - compatible = "qcom,msm8660-pinctrl"; - reg = <0x800000 0x4000>; - - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&msmgpio 0 0 173>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = <0 16 0x4>; - - pinctrl-names = "default"; - pinctrl-0 = <&gsbi12_uart>; - - gsbi12_uart: gsbi12-uart { - mux { - pins = "gpio117", "gpio118"; - function = "gsbi12"; - }; - - tx { - pins = "gpio118"; - drive-strength = <8>; - bias-disable; - }; - - rx { - pins = "gpio117"; - drive-strength = <2>; - bias-pull-up; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8660-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8660-pinctrl.yaml new file mode 100644 index 000000000000..ad0cad4694c0 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8660-pinctrl.yaml @@ -0,0 +1,125 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,msm8660-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm MSM8660 TLMM pin controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in Qualcomm MSM8660 SoC. + +properties: + compatible: + const: qcom,msm8660-pinctrl + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 86 + + gpio-line-names: + maxItems: 173 + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-msm8660-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-msm8660-tlmm-state" + additionalProperties: false + +$defs: + qcom-msm8660-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-6][0-9]|17[0-2])$" + - enum: [ sdc3_clk, sdc3_cmd, sdc3_data, sdc4_clk, sdc4_cmd, sdc4_data ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ gpio, cam_mclk, dsub, ext_gps, gp_clk_0a, gp_clk_0b, gp_clk_1a, + gp_clk_1b, gp_clk_2a, gp_clk_2b, gp_mn, gsbi1, gsbi1_spi_cs1_n, + gsbi1_spi_cs2a_n, gsbi1_spi_cs2b_n, gsbi1_spi_cs3_n, gsbi2, + gsbi2_spi_cs1_n, gsbi2_spi_cs2_n, gsbi2_spi_cs3_n, gsbi3, + gsbi3_spi_cs1_n, gsbi3_spi_cs2_n, gsbi3_spi_cs3_n, gsbi4, + gsbi5, gsbi6, gsbi7, gsbi8, gsbi9, gsbi10, gsbi11, gsbi12, + hdmi, i2s, lcdc, mdp_vsync, mi2s, pcm, ps_hold, sdc1, sdc2, + sdc5, tsif1, tsif2, usb_fs1, usb_fs1_oe_n, usb_fs2, + usb_fs2_oe_n, vfe, vsens_alarm, ebi2, ebi2cs ] + + + 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 + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + tlmm: pinctrl@800000 { + compatible = "qcom,msm8660-pinctrl"; + reg = <0x800000 0x4000>; + + gpio-controller; + gpio-ranges = <&tlmm 0 0 173>; + #gpio-cells = <2>; + interrupts = <0 16 0x4>; + interrupt-controller; + #interrupt-cells = <2>; + + gsbi3-i2c-state { + pins = "gpio43", "gpio44"; + function = "gsbi3"; + drive-strength = <8>; + bias-disable; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8909-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8909-tlmm.yaml index e03530091478..cc6d0c9c5100 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8909-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8909-tlmm.yaml @@ -10,8 +10,7 @@ maintainers: - Stephan Gerhold <stephan@gerhold.net> description: | - This binding describes the Top Level Mode Multiplexer (TLMM) block found - in the MSM8909 platform. + Top Level Mode Multiplexer pin controller in Qualcomm MSM8909 SoC. allOf: - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# @@ -25,10 +24,10 @@ properties: interrupts: true interrupt-controller: true - '#interrupt-cells': true + "#interrupt-cells": true gpio-controller: true gpio-reserved-ranges: true - '#gpio-cells': true + "#gpio-cells": true gpio-ranges: true wakeup-parent: true @@ -39,12 +38,13 @@ required: additionalProperties: false patternProperties: - '-state$': + "-state$": oneOf: - $ref: "#/$defs/qcom-msm8909-tlmm-state" - patternProperties: - ".*": + "-pins$": $ref: "#/$defs/qcom-msm8909-tlmm-state" + additionalProperties: false $defs: qcom-msm8909-tlmm-state: @@ -52,7 +52,7 @@ $defs: 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" + $ref: qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state properties: pins: @@ -112,41 +112,40 @@ $defs: required: - pins - - function additionalProperties: false examples: - | - #include <dt-bindings/interrupt-controller/arm-gic.h> - - pinctrl@1000000 { - compatible = "qcom,msm8909-tlmm"; - reg = <0x1000000 0x300000>; - interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&tlmm 0 0 117>; - interrupt-controller; - #interrupt-cells = <2>; - - gpio-wo-subnode-state { - pins = "gpio1"; - function = "gpio"; - }; - - uart-w-subnodes-state { - rx { - pins = "gpio4"; - function = "blsp_uart1"; - bias-pull-up; - }; - - tx { - pins = "gpio5"; - function = "blsp_uart1"; - bias-disable; - }; - }; + #include <dt-bindings/interrupt-controller/arm-gic.h> + + pinctrl@1000000 { + compatible = "qcom,msm8909-tlmm"; + reg = <0x1000000 0x300000>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&tlmm 0 0 117>; + interrupt-controller; + #interrupt-cells = <2>; + + gpio-wo-subnode-state { + pins = "gpio1"; + function = "gpio"; }; + + uart-w-subnodes-state { + rx-pins { + pins = "gpio4"; + function = "blsp_uart1"; + bias-pull-up; + }; + + tx-pins { + pins = "gpio5"; + function = "blsp_uart1"; + bias-disable; + }; + }; + }; ... diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.txt deleted file mode 100644 index 3354a63296d9..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.txt +++ /dev/null @@ -1,195 +0,0 @@ -Qualcomm MSM8916 TLMM block - -This binding describes the Top Level Mode Multiplexer block found in the -MSM8916 platform. - -- compatible: - Usage: required - Value type: <string> - Definition: must be "qcom,msm8916-pinctrl" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: the base address and size of the TLMM register space. - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: should specify the TLMM summary IRQ. - -- interrupt-controller: - Usage: required - Value type: <none> - Definition: identifies this node as an interrupt controller - -- #interrupt-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/interrupt-controller/irq.h> - -- gpio-controller: - Usage: required - Value type: <none> - Definition: identifies this node as a gpio controller - -- #gpio-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/gpio/gpio.h> - -- gpio-ranges: - Usage: required - Definition: see ../gpio/gpio.txt - -- gpio-reserved-ranges: - Usage: optional - Definition: see ../gpio/gpio.txt - -Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for -a general description of GPIO and interrupt bindings. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -The pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - - -PIN CONFIGURATION NODES: - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. - - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pin configuration subnode: - -- pins: - Usage: required - Value type: <string-array> - Definition: List of gpio pins affected by the properties specified in - this subnode. Valid pins are: - gpio0-gpio121, - sdc1_clk, - sdc1_cmd, - sdc1_data - sdc2_clk, - sdc2_cmd, - sdc2_data, - qdsd_cmd, - qdsd_data0, - qdsd_data1, - qdsd_data2, - qdsd_data3 - -- function: - Usage: required - Value type: <string> - Definition: Specify the alternative function to be configured for the - specified pins. Functions are only valid for gpio pins. - Valid values are: - adsp_ext, alsp_int, atest_bbrx0, atest_bbrx1, atest_char, atest_char0, - atest_char1, atest_char2, atest_char3, atest_combodac, atest_gpsadc0, - atest_gpsadc1, atest_tsens, atest_wlan0, atest_wlan1, backlight_en, - bimc_dte0,bimc_dte1, blsp_i2c1, blsp_i2c2, blsp_i2c3, blsp_i2c4, - blsp_i2c5, blsp_i2c6, blsp_spi1, blsp_spi1_cs1, blsp_spi1_cs2, - blsp_spi1_cs3, blsp_spi2, blsp_spi2_cs1, blsp_spi2_cs2, blsp_spi2_cs3, - blsp_spi3, blsp_spi3_cs1, blsp_spi3_cs2, blsp_spi3_cs3, blsp_spi4, - blsp_spi5, blsp_spi6, blsp_uart1, blsp_uart2, blsp_uim1, blsp_uim2, - cam1_rst, cam1_standby, cam_mclk0, cam_mclk1, cci_async, cci_i2c, - cci_timer0, cci_timer1, cci_timer2, cdc_pdm0, codec_mad, dbg_out, - display_5v, dmic0_clk, dmic0_data, dsi_rst, ebi0_wrcdc, euro_us, - ext_lpass, flash_strobe, gcc_gp1_clk_a, gcc_gp1_clk_b, gcc_gp2_clk_a, - gcc_gp2_clk_b, gcc_gp3_clk_a, gcc_gp3_clk_b, gpio, gsm0_tx0, gsm0_tx1, - gsm1_tx0, gsm1_tx1, gyro_accl, kpsns0, kpsns1, kpsns2, ldo_en, - ldo_update, mag_int, mdp_vsync, modem_tsync, m_voc, nav_pps, nav_tsync, - pa_indicator, pbs0, pbs1, pbs2, pri_mi2s, pri_mi2s_ws, prng_rosc, - pwr_crypto_enabled_a, pwr_crypto_enabled_b, pwr_modem_enabled_a, - pwr_modem_enabled_b, pwr_nav_enabled_a, pwr_nav_enabled_b, - qdss_ctitrig_in_a0, qdss_ctitrig_in_a1, qdss_ctitrig_in_b0, - qdss_ctitrig_in_b1, qdss_ctitrig_out_a0, qdss_ctitrig_out_a1, - qdss_ctitrig_out_b0, qdss_ctitrig_out_b1, qdss_traceclk_a, - qdss_traceclk_b, qdss_tracectl_a, qdss_tracectl_b, qdss_tracedata_a, - qdss_tracedata_b, reset_n, sd_card, sd_write, sec_mi2s, smb_int, - ssbi_wtr0, ssbi_wtr1, uim1, uim2, uim3, uim_batt, wcss_bt, wcss_fm, - wcss_wlan, webcam1_rst - -- bias-disable: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as no pull. - -- bias-pull-down: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull down. - -- bias-pull-up: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull up. - -- output-high: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - high. - Not valid for sdc pins. - -- output-low: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - low. - Not valid for sdc pins. - -- drive-strength: - Usage: optional - Value type: <u32> - Definition: Selects the drive strength for the specified pins, in mA. - Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16 - -Example: - - tlmm: pinctrl@1000000 { - compatible = "qcom,msm8916-pinctrl"; - reg = <0x1000000 0x300000>; - interrupts = <0 208 0>; - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&tlmm 0 0 122>; - interrupt-controller; - #interrupt-cells = <2>; - - uart2: uart2-default { - mux { - pins = "gpio4", "gpio5"; - function = "blsp_uart2"; - }; - - tx { - pins = "gpio4"; - drive-strength = <4>; - bias-disable; - }; - - rx { - pins = "gpio5"; - drive-strength = <2>; - bias-pull-up; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.yaml new file mode 100644 index 000000000000..5495f58905af --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.yaml @@ -0,0 +1,166 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,msm8916-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm MSM8916 TLMM pin controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in Qualcomm MSM8916 SoC. + +properties: + compatible: + const: qcom,msm8916-pinctrl + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 61 + + gpio-line-names: + maxItems: 122 + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-msm8916-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-msm8916-tlmm-state" + additionalProperties: false + +$defs: + qcom-msm8916-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-1][0-9]|12[01])$" + - enum: [ qdsd_clk, qdsd_cmd, qdsd_data0, qdsd_data1, qdsd_data2, + qdsd_data3, sdc1_clk, sdc1_cmd, sdc1_data, sdc2_clk, + sdc2_cmd, sdc2_data ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ gpio, adsp_ext, alsp_int, atest_bbrx0, atest_bbrx1, atest_char, + atest_char0, atest_char1, atest_char2, atest_char3, + atest_combodac, atest_gpsadc0, atest_gpsadc1, atest_tsens, + atest_wlan0, atest_wlan1, backlight_en, bimc_dte0, bimc_dte1, + blsp_i2c1, blsp_i2c2, blsp_i2c3, blsp_i2c4, blsp_i2c5, + blsp_i2c6, blsp_spi1, blsp_spi1_cs1, blsp_spi1_cs2, + blsp_spi1_cs3, blsp_spi2, blsp_spi2_cs1, blsp_spi2_cs2, + blsp_spi2_cs3, blsp_spi3, blsp_spi3_cs1, blsp_spi3_cs2, + blsp_spi3_cs3, blsp_spi4, blsp_spi5, blsp_spi6, blsp_uart1, + blsp_uart2, blsp_uim1, blsp_uim2, cam1_rst, cam1_standby, + cam_mclk0, cam_mclk1, cci_async, cci_i2c, cci_timer0, + cci_timer1, cci_timer2, cdc_pdm0, codec_mad, dbg_out, + display_5v, dmic0_clk, dmic0_data, dsi_rst, ebi0_wrcdc, + euro_us, ext_lpass, flash_strobe, gcc_gp1_clk_a, gcc_gp1_clk_b, + gcc_gp2_clk_a, gcc_gp2_clk_b, gcc_gp3_clk_a, gcc_gp3_clk_b, + gsm0_tx0, gsm0_tx1, gsm1_tx0, gsm1_tx1, gyro_accl, kpsns0, + kpsns1, kpsns2, ldo_en, ldo_update, mag_int, mdp_vsync, + modem_tsync, m_voc, nav_pps, nav_tsync, pa_indicator, pbs0, + pbs1, pbs2, pri_mi2s, pri_mi2s_ws, prng_rosc, + pwr_crypto_enabled_a, pwr_crypto_enabled_b, + pwr_modem_enabled_a, pwr_modem_enabled_b, pwr_nav_enabled_a, + pwr_nav_enabled_b, qdss_ctitrig_in_a0, qdss_ctitrig_in_a1, + qdss_ctitrig_in_b0, qdss_ctitrig_in_b1, qdss_ctitrig_out_a0, + qdss_ctitrig_out_a1, qdss_ctitrig_out_b0, qdss_ctitrig_out_b1, + qdss_traceclk_a, qdss_traceclk_b, qdss_tracectl_a, + qdss_tracectl_b, qdss_tracedata_a, qdss_tracedata_b, reset_n, + sd_card, sd_write, sec_mi2s, smb_int, ssbi_wtr0, ssbi_wtr1, + uim1, uim2, uim3, uim_batt, wcss_bt, wcss_fm, wcss_wlan, + webcam1_rst ] + + 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 + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + msmgpio: pinctrl@1000000 { + compatible = "qcom,msm8916-pinctrl"; + reg = <0x01000000 0x300000>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + gpio-ranges = <&msmgpio 0 0 122>; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + + blsp1-uart2-sleep-state { + pins = "gpio4", "gpio5"; + function = "gpio"; + + drive-strength = <2>; + bias-pull-down; + }; + + spi1-default-state { + spi-pins { + pins = "gpio0", "gpio1", "gpio3"; + function = "blsp_spi1"; + + drive-strength = <12>; + bias-disable; + }; + + cs-pins { + pins = "gpio2"; + function = "gpio"; + + drive-strength = <16>; + bias-disable; + output-high; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8953-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8953-pinctrl.yaml index d4da558cde54..c9a4a79e8d01 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8953-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8953-pinctrl.yaml @@ -9,9 +9,8 @@ title: Qualcomm Technologies, Inc. MSM8953 TLMM block maintainers: - Bjorn Andersson <bjorn.andersson@linaro.org> -description: | - This binding describes the Top Level Mode Multiplexer block found in the - MSM8953 platform. +description: + Top Level Mode Multiplexer pin controller in Qualcomm MSM8953 SoC. properties: compatible: @@ -20,38 +19,30 @@ properties: reg: maxItems: 1 - interrupts: - description: Specifies the TLMM summary IRQ - maxItems: 1 - + interrupts: true interrupt-controller: true - - '#interrupt-cells': - description: - Specifies the PIN numbers and Flags, as defined in defined in - include/dt-bindings/interrupt-controller/irq.h - const: 2 - + "#interrupt-cells": true gpio-controller: true - gpio-reserved-ranges: true + "#gpio-cells": true + gpio-ranges: 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 - -#PIN CONFIGURATION NODES patternProperties: - '-pins$': + "-state$": + oneOf: + - $ref: "#/$defs/qcom-msm8953-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-msm8953-tlmm-state" + additionalProperties: false + +$defs: + qcom-msm8953-tlmm-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" + $ref: qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state properties: pins: @@ -113,60 +104,44 @@ patternProperties: uim_batt, us_emitter, us_euro, wcss_bt, wcss_fm, wcss_wlan, wcss_wlan0, wcss_wlan1, wcss_wlan2, wsa_en, wsa_io, wsa_irq ] - drive-strength: - enum: [2, 4, 6, 8, 10, 12, 14, 16] - default: 2 - description: - Selects the drive strength for the specified pins, in mA. - bias-pull-down: true - bias-pull-up: true - bias-disable: true - + drive-strength: true output-high: true - output-low: true required: - pins - - function additionalProperties: false allOf: - - $ref: "pinctrl.yaml#" + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# required: - compatible - reg - - interrupts - - interrupt-controller - - '#interrupt-cells' - - gpio-controller - - '#gpio-cells' - - gpio-ranges additionalProperties: false examples: - | - #include <dt-bindings/interrupt-controller/arm-gic.h> - tlmm: pinctrl@1000000 { - compatible = "qcom,msm8953-pinctrl"; - reg = <0x01000000 0x300000>; - interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; - interrupt-controller; - #interrupt-cells = <2>; - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&tlmm 0 0 142>; - - serial_default: serial-pins { - pins = "gpio4", "gpio5"; - function = "blsp_uart2"; - drive-strength = <2>; - bias-disable; - }; + #include <dt-bindings/interrupt-controller/arm-gic.h> + tlmm: pinctrl@1000000 { + compatible = "qcom,msm8953-pinctrl"; + reg = <0x01000000 0x300000>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&tlmm 0 0 142>; + + serial_default: serial-state { + pins = "gpio4", "gpio5"; + function = "blsp_uart2"; + drive-strength = <2>; + bias-disable; }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.txt deleted file mode 100644 index a7dd213c77c6..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.txt +++ /dev/null @@ -1,190 +0,0 @@ -Qualcomm MSM8960 TLMM block - -This binding describes the Top Level Mode Multiplexer block found in the -MSM8960 platform. - -- compatible: - Usage: required - Value type: <string> - Definition: must be "qcom,msm8960-pinctrl" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: the base address and size of the TLMM register space. - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: should specify the TLMM summary IRQ. - -- interrupt-controller: - Usage: required - Value type: <none> - Definition: identifies this node as an interrupt controller - -- #interrupt-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/interrupt-controller/irq.h> - -- gpio-controller: - Usage: required - Value type: <none> - Definition: identifies this node as a gpio controller - -- #gpio-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/gpio/gpio.h> - -- gpio-ranges: - Usage: required - Definition: see ../gpio/gpio.txt - -- gpio-reserved-ranges: - Usage: optional - Definition: see ../gpio/gpio.txt - -Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for -a general description of GPIO and interrupt bindings. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -The pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - - -PIN CONFIGURATION NODES: - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. - - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pin configuration subnode: - -- pins: - Usage: required - Value type: <string-array> - Definition: List of gpio pins affected by the properties specified in - this subnode. Valid pins are: - gpio0-gpio151, - sdc1_clk, - sdc1_cmd, - sdc1_data - sdc3_clk, - sdc3_cmd, - sdc3_data - -- function: - Usage: required - Value type: <string> - Definition: Specify the alternative function to be configured for the - specified pins. Functions are only valid for gpio pins. - Valid values are: - audio_pcm, bt, cam_mclk0, cam_mclk1, cam_mclk2, - codec_mic_i2s, codec_spkr_i2s, ext_gps, fm, gps_blanking, - gps_pps_in, gps_pps_out, gp_clk_0a, gp_clk_0b, gp_clk_1a, - gp_clk_1b, gp_clk_2a, gp_clk_2b, gp_mn, gp_pdm_0a, - gp_pdm_0b, gp_pdm_1a, gp_pdm_1b, gp_pdm_2a, gp_pdm_2b, gpio, - gsbi1, gsbi1_spi_cs1_n, gsbi1_spi_cs2a_n, gsbi1_spi_cs2b_n, - gsbi1_spi_cs3_n, gsbi2, gsbi2_spi_cs1_n, gsbi2_spi_cs2_n, - gsbi2_spi_cs3_n, gsbi3, gsbi4, gsbi4_3d_cam_i2c_l, - gsbi4_3d_cam_i2c_r, gsbi5, gsbi5_3d_cam_i2c_l, - gsbi5_3d_cam_i2c_r, gsbi6, gsbi7, gsbi8, gsbi9, gsbi10, - gsbi11, gsbi11_spi_cs1a_n, gsbi11_spi_cs1b_n, - gsbi11_spi_cs2a_n, gsbi11_spi_cs2b_n, gsbi11_spi_cs3_n, - gsbi12, hdmi_cec, hdmi_ddc_clock, hdmi_ddc_data, - hdmi_hot_plug_detect, hsic, mdp_vsync, mi2s, mic_i2s, - pmb_clk, pmb_ext_ctrl, ps_hold, rpm_wdog, sdc2, sdc4, sdc5, - slimbus1, slimbus2, spkr_i2s, ssbi1, ssbi2, ssbi_ext_gps, - ssbi_pmic2, ssbi_qpa1, ssbi_ts, tsif1, tsif2, ts_eoc, - usb_fs1, usb_fs1_oe, usb_fs1_oe_n, usb_fs2, usb_fs2_oe, - usb_fs2_oe_n, vfe_camif_timer1_a, vfe_camif_timer1_b, - vfe_camif_timer2, vfe_camif_timer3_a, vfe_camif_timer3_b, - vfe_camif_timer4_a, vfe_camif_timer4_b, vfe_camif_timer4_c, - vfe_camif_timer5_a, vfe_camif_timer5_b, vfe_camif_timer6_a, - vfe_camif_timer6_b, vfe_camif_timer6_c, vfe_camif_timer7_a, - vfe_camif_timer7_b, vfe_camif_timer7_c, wlan - -- bias-disable: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as no pull. - -- bias-pull-down: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull down. - -- bias-pull-up: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull up. - -- output-high: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - high. - Not valid for sdc pins. - -- output-low: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - low. - Not valid for sdc pins. - -- drive-strength: - Usage: optional - Value type: <u32> - Definition: Selects the drive strength for the specified pins, in mA. - Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16 - -Example: - - msmgpio: pinctrl@800000 { - compatible = "qcom,msm8960-pinctrl"; - reg = <0x800000 0x4000>; - - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&msmgpio 0 0 152>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = <0 16 0x4>; - - gsbi8_uart: gsbi8-uart { - mux { - pins = "gpio34", "gpio35"; - function = "gsbi8"; - }; - - tx { - pins = "gpio34"; - drive-strength = <4>; - bias-disable; - }; - - rx { - pins = "gpio35"; - drive-strength = <2>; - bias-pull-up; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.yaml new file mode 100644 index 000000000000..33d07d531273 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.yaml @@ -0,0 +1,164 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,msm8960-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm MSM8960 TLMM pin controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in Qualcomm MSM8960 SoC. + +properties: + compatible: + const: qcom,msm8960-pinctrl + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 76 + + gpio-line-names: + maxItems: 152 + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-msm8960-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-msm8960-tlmm-state" + additionalProperties: false + +$defs: + qcom-msm8960-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]|15[0-1])$" + - enum: [ sdc1_clk, sdc1_cmd, sdc1_data, sdc3_clk, sdc3_cmd, + sdc3_data ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ gpio, audio_pcm, bt, cam_mclk0, cam_mclk1, cam_mclk2, + codec_mic_i2s, codec_spkr_i2s, ext_gps, fm, gps_blanking, + gps_pps_in, gps_pps_out, gp_clk_0a, gp_clk_0b, gp_clk_1a, + gp_clk_1b, gp_clk_2a, gp_clk_2b, gp_mn, gp_pdm_0a, gp_pdm_0b, + gp_pdm_1a, gp_pdm_1b, gp_pdm_2a, gp_pdm_2b, gsbi1, + gsbi1_spi_cs1_n, gsbi1_spi_cs2a_n, gsbi1_spi_cs2b_n, + gsbi1_spi_cs3_n, gsbi2, gsbi2_spi_cs1_n, gsbi2_spi_cs2_n, + gsbi2_spi_cs3_n, gsbi3, gsbi4, gsbi4_3d_cam_i2c_l, + gsbi4_3d_cam_i2c_r, gsbi5, gsbi5_3d_cam_i2c_l, + gsbi5_3d_cam_i2c_r, gsbi6, gsbi7, gsbi8, gsbi9, gsbi10, gsbi11, + gsbi11_spi_cs1a_n, gsbi11_spi_cs1b_n, gsbi11_spi_cs2a_n, + gsbi11_spi_cs2b_n, gsbi11_spi_cs3_n, gsbi12, hdmi_cec, + hdmi_ddc_clock, hdmi_ddc_data, hdmi_hot_plug_detect, hsic, + mdp_vsync, mi2s, mic_i2s, pmb_clk, pmb_ext_ctrl, ps_hold, + rpm_wdog, sdc2, sdc4, sdc5, slimbus1, slimbus2, spkr_i2s, + ssbi1, ssbi2, ssbi_ext_gps, ssbi_pmic2, ssbi_qpa1, ssbi_ts, + tsif1, tsif2, ts_eoc, usb_fs1, usb_fs1_oe, usb_fs1_oe_n, + usb_fs2, usb_fs2_oe, usb_fs2_oe_n, vfe_camif_timer1_a, + vfe_camif_timer1_b, vfe_camif_timer2, vfe_camif_timer3_a, + vfe_camif_timer3_b, vfe_camif_timer4_a, vfe_camif_timer4_b, + vfe_camif_timer4_c, vfe_camif_timer5_a, vfe_camif_timer5_b, + vfe_camif_timer6_a, vfe_camif_timer6_b, vfe_camif_timer6_c, + vfe_camif_timer7_a, vfe_camif_timer7_b, vfe_camif_timer7_c, + wlan ] + + 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 + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + msmgpio: pinctrl@800000 { + compatible = "qcom,msm8960-pinctrl"; + reg = <0x800000 0x4000>; + #gpio-cells = <2>; + gpio-controller; + gpio-ranges = <&msmgpio 0 0 152>; + interrupts = <GIC_SPI 16 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <2>; + + spi1-default-state { + mosi-pins { + pins = "gpio6"; + function = "gsbi1"; + drive-strength = <12>; + bias-disable; + }; + + miso-pins { + pins = "gpio7"; + function = "gsbi1"; + drive-strength = <12>; + bias-disable; + }; + + cs-pins { + pins = "gpio8"; + function = "gpio"; + drive-strength = <12>; + bias-disable; + output-low; + }; + + clk-pins { + pins = "gpio9"; + function = "gsbi1"; + drive-strength = <12>; + bias-disable; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.txt deleted file mode 100644 index 004056506679..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.txt +++ /dev/null @@ -1,121 +0,0 @@ -Qualcomm MSM8974 TLMM block - -Required properties: -- compatible: "qcom,msm8974-pinctrl" -- reg: Should be the base address and length of the TLMM block. -- interrupts: Should be the parent IRQ of the TLMM block. -- interrupt-controller: Marks the device node as an interrupt controller. -- #interrupt-cells: Should be two. -- gpio-controller: Marks the device node as a GPIO controller. -- #gpio-cells : Should be two. - The first cell is the gpio pin number and the - second cell is used for optional parameters. -- gpio-ranges: see ../gpio/gpio.txt - -Optional properties: - -- gpio-reserved-ranges: see ../gpio/gpio.txt - -Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for -a general description of GPIO and interrupt bindings. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -Qualcomm's pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. - - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pin configuration subnode: - pins, function, bias-disable, bias-pull-down, bias-pull-up, drive-strength. - -Non-empty subnodes must specify the 'pins' property. -Note that not all properties are valid for all pins. - - -Valid values for pins are: - gpio0-gpio145 - Supports mux, bias and drive-strength - - sdc1_clk, sdc1_cmd, sdc1_data, sdc2_clk, sdc2_cmd, sdc2_data - Supports bias and drive-strength - - hsic_data, hsic_strobe - Supports only mux - -Valid values for function are: - cci_i2c0, cci_i2c1, uim1, uim2, uim_batt_alarm, - blsp_uim1, blsp_uart1, blsp_i2c1, blsp_spi1, - blsp_uim2, blsp_uart2, blsp_i2c2, blsp_spi2, - blsp_uim3, blsp_uart3, blsp_i2c3, blsp_spi3, - blsp_uim4, blsp_uart4, blsp_i2c4, blsp_spi4, - blsp_uim5, blsp_uart5, blsp_i2c5, blsp_spi5, - blsp_uim6, blsp_uart6, blsp_i2c6, blsp_spi6, - blsp_uim7, blsp_uart7, blsp_i2c7, blsp_spi7, - blsp_uim8, blsp_uart8, blsp_i2c8, blsp_spi8, - blsp_uim9, blsp_uart9, blsp_i2c9, blsp_spi9, - blsp_uim10, blsp_uart10, blsp_i2c10, blsp_spi10, - blsp_uim11, blsp_uart11, blsp_i2c11, blsp_spi11, - blsp_uim12, blsp_uart12, blsp_i2c12, blsp_spi12, - blsp_spi1_cs1, blsp_spi2_cs2, blsp_spi_cs3, blsp_spi2_cs1, blsp_spi2_cs2 - blsp_spi2_cs3, blsp_spi10_cs1, blsp_spi10_cs2, blsp_spi10_cs3, - sdc3, sdc4, gcc_gp_clk1, gcc_gp_clk2, gcc_gp_clk3, cci_timer0, cci_timer1, - cci_timer2, cci_timer3, cci_async_in0, cci_async_in1, cci_async_in2, - cam_mckl0, cam_mclk1, cam_mclk2, cam_mclk3, mdp_vsync, hdmi_cec, hdmi_ddc, - hdmi_hpd, edp_hpd, gp_pdm0, gp_pdm1, gp_pdm2, gp_pdm3, gp0_clk, gp1_clk, - gp_mn, tsif1, tsif2, hsic, grfc, audio_ref_clk, qua_mi2s, pri_mi2s, spkr_mi2s, - ter_mi2s, sec_mi2s, bt, fm, wlan, slimbus, hsic_ctl, gpio - - (Note that this is not yet the complete list of functions) - - - -Example: - - msmgpio: pinctrl@fd510000 { - compatible = "qcom,msm8974-pinctrl"; - reg = <0xfd510000 0x4000>; - - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&msmgpio 0 0 146>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = <0 208 0>; - - pinctrl-names = "default"; - pinctrl-0 = <&uart2_default>; - - uart2_default: uart2_default { - mux { - pins = "gpio4", "gpio5"; - function = "blsp_uart2"; - }; - - tx { - pins = "gpio4"; - drive-strength = <4>; - bias-disable; - }; - - rx { - pins = "gpio5"; - drive-strength = <2>; - bias-pull-up; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.yaml new file mode 100644 index 000000000000..9287cbbff711 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.yaml @@ -0,0 +1,179 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,msm8974-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm MSM8974 TLMM pin controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in Qualcomm MSM8974 SoC. + +properties: + compatible: + const: qcom,msm8974-pinctrl + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 73 + + gpio-line-names: + maxItems: 146 + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-msm8974-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-msm8974-tlmm-state" + additionalProperties: false + +$defs: + qcom-msm8974-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-5])$" + - enum: [ hsic_data, hsic_strobe, sdc1_clk, sdc1_cmd, sdc1_data, + sdc2_clk, sdc2_cmd, sdc2_data ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ gpio, cci_i2c0, cci_i2c1, uim1, uim2, uim_batt_alarm, + blsp_uim1, blsp_uart1, blsp_i2c1, blsp_spi1, blsp_uim2, + blsp_uart2, blsp_i2c2, blsp_spi2, blsp_uim3, blsp_uart3, + blsp_i2c3, blsp_spi3, blsp_uim4, blsp_uart4, blsp_i2c4, + blsp_spi4, blsp_uim5, blsp_uart5, blsp_i2c5, blsp_spi5, + blsp_uim6, blsp_uart6, blsp_i2c6, blsp_spi6, blsp_uim7, + blsp_uart7, blsp_i2c7, blsp_spi7, blsp_uim8, blsp_uart8, + blsp_i2c8, blsp_spi8, blsp_uim9, blsp_uart9, blsp_i2c9, + blsp_spi9, blsp_uim10, blsp_uart10, blsp_i2c10, blsp_spi10, + blsp_uim11, blsp_uart11, blsp_i2c11, blsp_spi11, blsp_uim12, + blsp_uart12, blsp_i2c12, blsp_spi12, blsp_spi1_cs1, + blsp_spi2_cs2, blsp_spi_cs3, blsp_spi2_cs1, blsp_spi2_cs2 + blsp_spi2_cs3, blsp_spi10_cs1, blsp_spi10_cs2, blsp_spi10_cs3, + sdc3, sdc4, gcc_gp_clk1, gcc_gp_clk2, gcc_gp_clk3, cci_timer0, + cci_timer1, cci_timer2, cci_timer3, cci_async_in0, + cci_async_in1, cci_async_in2, cam_mckl0, cam_mclk1, cam_mclk2, + cam_mclk3, mdp_vsync, hdmi_cec, hdmi_ddc, hdmi_hpd, edp_hpd, + gp_pdm0, gp_pdm1, gp_pdm2, gp_pdm3, gp0_clk, gp1_clk, gp_mn, + tsif1, tsif2, hsic, grfc, audio_ref_clk, qua_mi2s, pri_mi2s, + spkr_mi2s, ter_mi2s, sec_mi2s, bt, fm, wlan, slimbus, hsic_ctl ] + + 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 + + allOf: + - if: + properties: + pins: + contains: + enum: + - hsic_data + - hsic_strobe + required: + - pins + then: + properties: + bias-pull-down: false + bias-pull-up: false + bias-disable: false + drive-strength: false + input-enable: false + output-high: false + output-low: false + + additionalProperties: false + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + tlmm: pinctrl@fd510000 { + compatible = "qcom,msm8974-pinctrl"; + reg = <0xfd510000 0x4000>; + gpio-controller; + gpio-ranges = <&tlmm 0 0 146>; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + + sdc1-off-state { + clk-pins { + pins = "sdc1_clk"; + bias-disable; + drive-strength = <2>; + }; + + cmd-pins { + pins = "sdc1_cmd"; + bias-pull-up; + drive-strength = <2>; + }; + + data-pins { + pins = "sdc1_data"; + bias-pull-up; + drive-strength = <2>; + }; + }; + + blsp2-uart1-sleep-state { + pins = "gpio41", "gpio42", "gpio43", "gpio44"; + function = "gpio"; + drive-strength = <2>; + bias-pull-down; + }; + + hsic-state { + pins = "hsic_data", "hsic_strobe"; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8976-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8976-pinctrl.txt deleted file mode 100644 index 70d04d12f136..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8976-pinctrl.txt +++ /dev/null @@ -1,183 +0,0 @@ -Qualcomm MSM8976 TLMM block - -This binding describes the Top Level Mode Multiplexer block found in the -MSM8956 and MSM8976 platforms. - -- compatible: - Usage: required - Value type: <string> - Definition: must be "qcom,msm8976-pinctrl" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: the base address and size of the TLMM register space. - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: should specify the TLMM summary IRQ. - -- interrupt-controller: - Usage: required - Value type: <none> - Definition: identifies this node as an interrupt controller - -- #interrupt-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/interrupt-controller/irq.h> - -- gpio-controller: - Usage: required - Value type: <none> - Definition: identifies this node as a gpio controller - -- #gpio-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/gpio/gpio.h> - -- gpio-ranges: - Usage: required - Definition: see ../gpio/gpio.txt - -- gpio-reserved-ranges: - Usage: optional - Definition: see ../gpio/gpio.txt - -Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for -a general description of GPIO and interrupt bindings. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -The pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - - -PIN CONFIGURATION NODES: - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. - - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pin configuration subnode: - -- pins: - Usage: required - Value type: <string-array> - Definition: List of gpio pins affected by the properties specified in - this subnode. - - Valid pins are: - gpio0-gpio145 - Supports mux, bias and drive-strength - - sdc1_clk, sdc1_cmd, sdc1_data, - sdc2_clk, sdc2_cmd, sdc2_data, - sdc3_clk, sdc3_cmd, sdc3_data - Supports bias and drive-strength - -- function: - Usage: required - Value type: <string> - Definition: Specify the alternative function to be configured for the - specified pins. Functions are only valid for gpio pins. - Valid values are: - - gpio, blsp_uart1, blsp_spi1, smb_int, blsp_i2c1, blsp_spi2, - blsp_uart2, blsp_i2c2, gcc_gp1_clk_b, blsp_spi3, - qdss_tracedata_b, blsp_i2c3, gcc_gp2_clk_b, gcc_gp3_clk_b, - blsp_spi4, cap_int, blsp_i2c4, blsp_spi5, blsp_uart5, - qdss_traceclk_a, m_voc, blsp_i2c5, qdss_tracectl_a, - qdss_tracedata_a, blsp_spi6, blsp_uart6, qdss_tracectl_b, - blsp_i2c6, qdss_traceclk_b, mdp_vsync, pri_mi2s_mclk_a, - sec_mi2s_mclk_a, cam_mclk, cci0_i2c, cci1_i2c, blsp1_spi, - blsp3_spi, gcc_gp1_clk_a, gcc_gp2_clk_a, gcc_gp3_clk_a, - uim_batt, sd_write, uim1_data, uim1_clk, uim1_reset, - uim1_present, uim2_data, uim2_clk, uim2_reset, - uim2_present, ts_xvdd, mipi_dsi0, us_euro, ts_resout, - ts_sample, sec_mi2s_mclk_b, pri_mi2s, codec_reset, - cdc_pdm0, us_emitter, pri_mi2s_mclk_b, pri_mi2s_mclk_c, - lpass_slimbus, lpass_slimbus0, lpass_slimbus1, codec_int1, - codec_int2, wcss_bt, sdc3, wcss_wlan2, wcss_wlan1, - wcss_wlan0, wcss_wlan, wcss_fm, key_volp, key_snapshot, - key_focus, key_home, pwr_down, dmic0_clk, hdmi_int, - dmic0_data, wsa_vi, wsa_en, blsp_spi8, wsa_irq, blsp_i2c8, - pa_indicator, modem_tsync, ssbi_wtr1, gsm1_tx, gsm0_tx, - sdcard_det, sec_mi2s, ss_switch, - -- bias-disable: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as no pull. - -- bias-pull-down: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull down. - -- bias-pull-up: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull up. - -- output-high: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - high. - Not valid for sdc pins. - -- output-low: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - low. - Not valid for sdc pins. - -- drive-strength: - Usage: optional - Value type: <u32> - Definition: Selects the drive strength for the specified pins, in mA. - Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16 - -Example: - - tlmm: pinctrl@1000000 { - compatible = "qcom,msm8976-pinctrl"; - reg = <0x1000000 0x300000>; - interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&tlmm 0 0 145>; - interrupt-controller; - #interrupt-cells = <2>; - - blsp1_uart2_active: blsp1_uart2_active { - mux { - pins = "gpio4", "gpio5", "gpio6", "gpio7"; - function = "blsp_uart2"; - }; - - config { - pins = "gpio4", "gpio5", "gpio6", "gpio7"; - drive-strength = <2>; - bias-disable; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8976-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8976-pinctrl.yaml new file mode 100644 index 000000000000..858f45710fe2 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8976-pinctrl.yaml @@ -0,0 +1,136 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,msm8976-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm MSM8976 TLMM pin controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in Qualcomm MSM8976 SoC. + +properties: + compatible: + const: qcom,msm8976-pinctrl + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 73 + + gpio-line-names: + maxItems: 145 + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-msm8976-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-msm8976-tlmm-state" + additionalProperties: false + +$defs: + qcom-msm8976-tlmm-state: + type: object + description: + Desired pin configuration for a device or its specific state (like sleep + or active). + $ref: qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state + + properties: + pins: + description: + List of gpio pins affected by the properties specified in this state. + items: + oneOf: + - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-3][0-9]|14[0-4])$" + - enum: [ qdsd_clk, qdsd_cmd, qdsd_data0, qdsd_data1, qdsd_data2, + qdsd_data3, sdc1_clk, sdc1_cmd, sdc1_data, sdc1_rclk, + sdc2_clk, sdc2_cmd, sdc2_data ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ gpio, blsp_uart1, blsp_spi1, smb_int, blsp_i2c1, blsp_spi2, + blsp_uart2, blsp_i2c2, gcc_gp1_clk_b, blsp_spi3, + qdss_tracedata_b, blsp_i2c3, gcc_gp2_clk_b, gcc_gp3_clk_b, + blsp_spi4, cap_int, blsp_i2c4, blsp_spi5, blsp_uart5, + qdss_traceclk_a, m_voc, blsp_i2c5, qdss_tracectl_a, + qdss_tracedata_a, blsp_spi6, blsp_uart6, qdss_tracectl_b, + blsp_i2c6, qdss_traceclk_b, mdp_vsync, pri_mi2s_mclk_a, + sec_mi2s_mclk_a, cam_mclk, cci0_i2c, cci1_i2c, blsp1_spi, + blsp3_spi, gcc_gp1_clk_a, gcc_gp2_clk_a, gcc_gp3_clk_a, + uim_batt, sd_write, uim1_data, uim1_clk, uim1_reset, + uim1_present, uim2_data, uim2_clk, uim2_reset, uim2_present, + ts_xvdd, mipi_dsi0, us_euro, ts_resout, ts_sample, + sec_mi2s_mclk_b, pri_mi2s, codec_reset, cdc_pdm0, us_emitter, + pri_mi2s_mclk_b, pri_mi2s_mclk_c, lpass_slimbus, + lpass_slimbus0, lpass_slimbus1, codec_int1, codec_int2, + wcss_bt, sdc3, wcss_wlan2, wcss_wlan1, wcss_wlan0, wcss_wlan, + wcss_fm, key_volp, key_snapshot, key_focus, key_home, pwr_down, + dmic0_clk, hdmi_int, dmic0_data, wsa_vi, wsa_en, blsp_spi8, + wsa_irq, blsp_i2c8, pa_indicator, modem_tsync, ssbi_wtr1, + gsm1_tx, gsm0_tx, sdcard_det, sec_mi2s, ss_switch ] + + 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 + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + tlmm: pinctrl@1000000 { + compatible = "qcom,msm8976-pinctrl"; + reg = <0x1000000 0x300000>; + #gpio-cells = <2>; + gpio-controller; + gpio-ranges = <&tlmm 0 0 145>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <2>; + + blsp1-uart2-active-state { + pins = "gpio4", "gpio5", "gpio6", "gpio7"; + function = "blsp_uart2"; + drive-strength = <2>; + bias-disable; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.txt deleted file mode 100644 index da52df6273bc..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.txt +++ /dev/null @@ -1,186 +0,0 @@ -Qualcomm MSM8994 TLMM block - -This binding describes the Top Level Mode Multiplexer block found in the -MSM8994 platform. - -- compatible: - Usage: required - Value type: <string> - Definition: Should contain one of: - "qcom,msm8992-pinctrl", - "qcom,msm8994-pinctrl". - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: the base address and size of the TLMM register space. - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: should specify the TLMM summary IRQ. - -- interrupt-controller: - Usage: required - Value type: <none> - Definition: identifies this node as an interrupt controller - -- #interrupt-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/interrupt-controller/irq.h> - -- gpio-controller: - Usage: required - Value type: <none> - Definition: identifies this node as a gpio controller - -- #gpio-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/gpio/gpio.h> - -- gpio-ranges: - Usage: required - Definition: see ../gpio/gpio.txt - -- gpio-reserved-ranges: - Usage: optional - Definition: see ../gpio/gpio.txt - -Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for -a general description of GPIO and interrupt bindings. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -The pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - - -PIN CONFIGURATION NODES: - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. - - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pin configuration subnode: - -- pins: - Usage: required - Value type: <string-array> - Definition: List of gpio pins affected by the properties specified in - this subnode. - - Valid pins are: - gpio0-gpio145 - Supports mux, bias and drive-strength - - sdc1_clk, sdc1_cmd, sdc1_data sdc1_rclk, sdc2_clk, - sdc2_cmd, sdc2_data - Supports bias and drive-strength - -- function: - Usage: required - Value type: <string> - Definition: Specify the alternative function to be configured for the - specified pins. Functions are only valid for gpio pins. - Valid values are: - - audio_ref_clk, blsp_i2c1, blsp_i2c2, blsp_i2c3, blsp_i2c4, blsp_i2c5, - blsp_i2c6, blsp_i2c7, blsp_i2c8, blsp_i2c9, blsp_i2c10, blsp_i2c11, - blsp_i2c12, blsp_spi1, blsp_spi1_cs1, blsp_spi1_cs2, blsp_spi1_cs3, - blsp_spi2, blsp_spi2_cs1, blsp_spi2_cs2, blsp_spi2_cs3, blsp_spi3, - blsp_spi4, blsp_spi5, blsp_spi6, blsp_spi7, blsp_spi8, blsp_spi9, - blsp_spi10, blsp_spi10_cs1, blsp_spi10_cs2, blsp_spi10_cs3, blsp_spi11, - blsp_spi12, blsp_uart1, blsp_uart2, blsp_uart3, blsp_uart4, blsp_uart5, - blsp_uart6, blsp_uart7, blsp_uart8, blsp_uart9, blsp_uart10, blsp_uart11, - blsp_uart12, blsp_uim1, blsp_uim2, blsp_uim3, blsp_uim4, blsp_uim5, - blsp_uim6, blsp_uim7, blsp_uim8, blsp_uim9, blsp_uim10, blsp_uim11, - blsp_uim12, blsp11_i2c_scl_b, blsp11_i2c_sda_b, blsp11_uart_rx_b, - blsp11_uart_tx_b, cam_mclk0, cam_mclk1, cam_mclk2, cam_mclk3, - cci_async_in0, cci_async_in1, cci_async_in2, cci_i2c0, cci_i2c1, - cci_timer0, cci_timer1, cci_timer2, cci_timer3, cci_timer4, - gcc_gp1_clk_a, gcc_gp1_clk_b, gcc_gp2_clk_a, gcc_gp2_clk_b, gcc_gp3_clk_a, - gcc_gp3_clk_b, gp_mn, gp_pdm0, gp_pdm1, gp_pdm2, gp0_clk, - gp1_clk, gps_tx, gsm_tx, hdmi_cec, hdmi_ddc, hdmi_hpd, hdmi_rcv, - mdp_vsync, mss_lte, nav_pps, nav_tsync, qdss_cti_trig_in_a, - qdss_cti_trig_in_b, qdss_cti_trig_in_c, qdss_cti_trig_in_d, - qdss_cti_trig_out_a, qdss_cti_trig_out_b, qdss_cti_trig_out_c, - qdss_cti_trig_out_d, qdss_traceclk_a, qdss_traceclk_b, qdss_tracectl_a, - qdss_tracectl_b, qdss_tracedata_a, qdss_tracedata_b, qua_mi2s, pci_e0, - pci_e1, pri_mi2s, sdc4, sec_mi2s, slimbus, spkr_i2s, ter_mi2s, tsif1, - tsif2, uim_batt_alarm, uim1, uim2, uim3, uim4, gpio - -- bias-disable: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as no pull. - -- bias-pull-down: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull down. - -- bias-pull-up: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull up. - -- output-high: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - high. - Not valid for sdc pins. - -- output-low: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - low. - Not valid for sdc pins. - -- drive-strength: - Usage: optional - Value type: <u32> - Definition: Selects the drive strength for the specified pins, in mA. - Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16 - -Example: - - msmgpio: pinctrl@fd510000 { - compatible = "qcom,msm8994-pinctrl"; - reg = <0xfd510000 0x4000>; - interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&msmgpio 0 0 146>; - interrupt-controller; - #interrupt-cells = <2>; - - blsp1_uart2_default: blsp1_uart2_default { - pinmux { - pins = "gpio4", "gpio5"; - function = "blsp_uart2"; - }; - pinconf { - pins = "gpio4", "gpio5"; - drive-strength = <16>; - bias-disable; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.yaml new file mode 100644 index 000000000000..55d5439c6c24 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.yaml @@ -0,0 +1,162 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,msm8994-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm MSM8994 TLMM pin controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in Qualcomm MSM8994 SoC. + +properties: + compatible: + enum: + - qcom,msm8992-pinctrl + - qcom,msm8994-pinctrl + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 75 + + gpio-line-names: + maxItems: 150 + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-msm8994-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-msm8994-tlmm-state" + additionalProperties: false + +$defs: + qcom-msm8994-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])$" + - enum: [ sdc1_clk, sdc1_cmd, sdc1_data, sdc1_rclk, sdc2_clk, + sdc2_cmd, sdc2_data, sdc3_clk, sdc3_cmd, sdc3_data ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ gpio, audio_ref_clk, blsp_i2c1, blsp_i2c2, blsp_i2c3, + blsp_i2c4, blsp_i2c5, blsp_i2c6, blsp_i2c7, blsp_i2c8, + blsp_i2c9, blsp_i2c10, blsp_i2c11, blsp_i2c12, blsp_spi1, + blsp_spi1_cs1, blsp_spi1_cs2, blsp_spi1_cs3, blsp_spi2, + blsp_spi2_cs1, blsp_spi2_cs2, blsp_spi2_cs3, blsp_spi3, + blsp_spi4, blsp_spi5, blsp_spi6, blsp_spi7, blsp_spi8, + blsp_spi9, blsp_spi10, blsp_spi10_cs1, blsp_spi10_cs2, + blsp_spi10_cs3, blsp_spi11, blsp_spi12, blsp_uart1, blsp_uart2, + blsp_uart3, blsp_uart4, blsp_uart5, blsp_uart6, blsp_uart7, + blsp_uart8, blsp_uart9, blsp_uart10, blsp_uart11, blsp_uart12, + blsp_uim1, blsp_uim2, blsp_uim3, blsp_uim4, blsp_uim5, + blsp_uim6, blsp_uim7, blsp_uim8, blsp_uim9, blsp_uim10, + blsp_uim11, blsp_uim12, blsp11_i2c_scl_b, blsp11_i2c_sda_b, + blsp11_uart_rx_b, blsp11_uart_tx_b, cam_mclk0, cam_mclk1, + cam_mclk2, cam_mclk3, cci_async_in0, cci_async_in1, + cci_async_in2, cci_i2c0, cci_i2c1, cci_timer0, cci_timer1, + cci_timer2, cci_timer3, cci_timer4, gcc_gp1_clk_a, + gcc_gp1_clk_b, gcc_gp2_clk_a, gcc_gp2_clk_b, gcc_gp3_clk_a, + gcc_gp3_clk_b, gp_mn, gp_pdm0, gp_pdm1, gp_pdm2, gp0_clk, + gp1_clk, gps_tx, gsm_tx, hdmi_cec, hdmi_ddc, hdmi_hpd, + hdmi_rcv, mdp_vsync, mss_lte, nav_pps, nav_tsync, + qdss_cti_trig_in_a, qdss_cti_trig_in_b, qdss_cti_trig_in_c, + qdss_cti_trig_in_d, qdss_cti_trig_out_a, qdss_cti_trig_out_b, + qdss_cti_trig_out_c, qdss_cti_trig_out_d, qdss_traceclk_a, + qdss_traceclk_b, qdss_tracectl_a, qdss_tracectl_b, + qdss_tracedata_a, qdss_tracedata_b, qua_mi2s, pci_e0, pci_e1, + pri_mi2s, sdc4, sec_mi2s, slimbus, spkr_i2s, ter_mi2s, tsif1, + tsif2, uim_batt_alarm, uim1, uim2, uim3, uim4 ] + + 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 + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + tlmm: pinctrl@fd510000 { + compatible = "qcom,msm8994-pinctrl"; + reg = <0xfd510000 0x4000>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + gpio-ranges = <&tlmm 0 0 146>; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + + blsp1-uart2-default-state { + function = "blsp_uart2"; + pins = "gpio4", "gpio5"; + drive-strength = <16>; + bias-disable; + }; + + blsp1-spi1-default-state { + default-pins { + pins = "gpio0", "gpio1", "gpio3"; + function = "blsp_spi1"; + drive-strength = <10>; + bias-pull-down; + }; + + cs-pins { + pins = "gpio8"; + function = "gpio"; + drive-strength = <2>; + bias-disable; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.txt deleted file mode 100644 index a56cb882830c..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.txt +++ /dev/null @@ -1,208 +0,0 @@ -Qualcomm MSM8996 TLMM block - -This binding describes the Top Level Mode Multiplexer block found in the -MSM8996 platform. - -- compatible: - Usage: required - Value type: <string> - Definition: must be "qcom,msm8996-pinctrl" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: the base address and size of the TLMM register space. - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: should specify the TLMM summary IRQ. - -- interrupt-controller: - Usage: required - Value type: <none> - Definition: identifies this node as an interrupt controller - -- #interrupt-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/interrupt-controller/irq.h> - -- gpio-controller: - Usage: required - Value type: <none> - Definition: identifies this node as a gpio controller - -- #gpio-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/gpio/gpio.h> - -- gpio-ranges: - Usage: required - Definition: see ../gpio/gpio.txt - -- gpio-reserved-ranges: - Usage: optional - Definition: see ../gpio/gpio.txt - -Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for -a general description of GPIO and interrupt bindings. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -The pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - - -PIN CONFIGURATION NODES: - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. - - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pin configuration subnode: - -- pins: - Usage: required - Value type: <string-array> - Definition: List of gpio pins affected by the properties specified in - this subnode. - - Valid pins are: - gpio0-gpio149 - Supports mux, bias and drive-strength - - sdc1_clk, sdc1_cmd, sdc1_data sdc2_clk, sdc2_cmd, - sdc2_data sdc1_rclk - Supports bias and drive-strength - -- function: - Usage: required - Value type: <string> - Definition: Specify the alternative function to be configured for the - specified pins. Functions are only valid for gpio pins. - Valid values are: - - blsp_uart1, blsp_spi1, blsp_i2c1, blsp_uim1, atest_tsens, - bimc_dte1, dac_calib0, blsp_spi8, blsp_uart8, blsp_uim8, - qdss_cti_trig_out_b, bimc_dte0, dac_calib1, qdss_cti_trig_in_b, - dac_calib2, atest_tsens2, atest_usb1, blsp_spi10, blsp_uart10, - blsp_uim10, atest_bbrx1, atest_usb13, atest_bbrx0, atest_usb12, - mdp_vsync, edp_lcd, blsp_i2c10, atest_gpsadc1, atest_usb11, - atest_gpsadc0, edp_hot, atest_usb10, m_voc, dac_gpio, atest_char, - cam_mclk, pll_bypassnl, qdss_stm7, blsp_i2c8, qdss_tracedata_b, - pll_reset, qdss_stm6, qdss_stm5, qdss_stm4, atest_usb2, cci_i2c, - qdss_stm3, dac_calib3, atest_usb23, atest_char3, dac_calib4, - qdss_stm2, atest_usb22, atest_char2, qdss_stm1, dac_calib5, - atest_usb21, atest_char1, dbg_out, qdss_stm0, dac_calib6, - atest_usb20, atest_char0, dac_calib10, qdss_stm10, - qdss_cti_trig_in_a, cci_timer4, blsp_spi6, blsp_uart6, blsp_uim6, - blsp2_spi, qdss_stm9, qdss_cti_trig_out_a, dac_calib11, - qdss_stm8, cci_timer0, qdss_stm13, dac_calib7, cci_timer1, - qdss_stm12, dac_calib8, cci_timer2, blsp1_spi, qdss_stm11, - dac_calib9, cci_timer3, cci_async, dac_calib12, blsp_i2c6, - qdss_tracectl_a, dac_calib13, qdss_traceclk_a, dac_calib14, - dac_calib15, hdmi_rcv, dac_calib16, hdmi_cec, pwr_modem, - dac_calib17, hdmi_ddc, pwr_nav, dac_calib18, pwr_crypto, - dac_calib19, hdmi_hot, dac_calib20, dac_calib21, pci_e0, - dac_calib22, dac_calib23, dac_calib24, tsif1_sync, dac_calib25, - sd_write, tsif1_error, blsp_spi2, blsp_uart2, blsp_uim2, - qdss_cti, blsp_i2c2, blsp_spi3, blsp_uart3, blsp_uim3, blsp_i2c3, - uim3, blsp_spi9, blsp_uart9, blsp_uim9, blsp10_spi, blsp_i2c9, - blsp_spi7, blsp_uart7, blsp_uim7, qdss_tracedata_a, blsp_i2c7, - qua_mi2s, gcc_gp1_clk_a, ssc_irq, uim4, blsp_spi11, blsp_uart11, - blsp_uim11, gcc_gp2_clk_a, gcc_gp3_clk_a, blsp_i2c11, cri_trng0, - cri_trng1, cri_trng, qdss_stm18, pri_mi2s, qdss_stm17, blsp_spi4, - blsp_uart4, blsp_uim4, qdss_stm16, qdss_stm15, blsp_i2c4, - qdss_stm14, dac_calib26, spkr_i2s, audio_ref, lpass_slimbus, - isense_dbg, tsense_pwm1, tsense_pwm2, btfm_slimbus, ter_mi2s, - qdss_stm22, qdss_stm21, qdss_stm20, qdss_stm19, gcc_gp1_clk_b, - sec_mi2s, blsp_spi5, blsp_uart5, blsp_uim5, gcc_gp2_clk_b, - gcc_gp3_clk_b, blsp_i2c5, blsp_spi12, blsp_uart12, blsp_uim12, - qdss_stm25, qdss_stm31, blsp_i2c12, qdss_stm30, qdss_stm29, - tsif1_clk, qdss_stm28, tsif1_en, tsif1_data, sdc4_cmd, qdss_stm27, - qdss_traceclk_b, tsif2_error, sdc43, vfr_1, qdss_stm26, tsif2_clk, - sdc4_clk, qdss_stm24, tsif2_en, sdc42, qdss_stm23, qdss_tracectl_b, - sd_card, tsif2_data, sdc41, tsif2_sync, sdc40, mdp_vsync_p_b, - ldo_en, mdp_vsync_s_b, ldo_update, blsp11_uart_tx_b, blsp11_uart_rx_b, - blsp11_i2c_sda_b, prng_rosc, blsp11_i2c_scl_b, uim2, uim1, uim_batt, - pci_e2, pa_indicator, adsp_ext, ddr_bist, qdss_tracedata_11, - qdss_tracedata_12, modem_tsync, nav_dr, nav_pps, pci_e1, gsm_tx, - qspi_cs, ssbi2, ssbi1, mss_lte, qspi_clk, qspi0, qspi1, qspi2, qspi3, - gpio - -- bias-disable: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as no pull. - -- bias-pull-down: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull down. - -- bias-pull-up: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull up. - -- output-high: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - high. - Not valid for sdc pins. - -- output-low: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - low. - Not valid for sdc pins. - -- drive-strength: - Usage: optional - Value type: <u32> - Definition: Selects the drive strength for the specified pins, in mA. - Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16 - -Example: - - tlmm: pinctrl@1010000 { - compatible = "qcom,msm8996-pinctrl"; - reg = <0x01010000 0x300000>; - interrupts = <0 208 0>; - gpio-controller; - gpio-ranges = <&tlmm 0 0 150>; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; - - uart_console_active: uart_console_active { - mux { - pins = "gpio4", "gpio5"; - function = "blsp_uart8"; - }; - - config { - pins = "gpio4", "gpio5"; - drive-strength = <2>; - bias-disable; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.yaml new file mode 100644 index 000000000000..8e1cd4ba1116 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.yaml @@ -0,0 +1,182 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,msm8996-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm MSM8996 TLMM pin controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in Qualcomm MSM8996 SoC. + +properties: + compatible: + const: qcom,msm8996-pinctrl + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 75 + + gpio-line-names: + maxItems: 150 + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-msm8996-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-msm8996-tlmm-state" + additionalProperties: false + +$defs: + qcom-msm8996-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])$" + - enum: [ sdc1_clk, sdc1_cmd, sdc1_data, sdc1_rclk, sdc2_clk, + sdc2_cmd, sdc2_data ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ gpio, blsp_uart1, blsp_spi1, blsp_i2c1, blsp_uim1, atest_tsens, + bimc_dte1, dac_calib0, blsp_spi8, blsp_uart8, blsp_uim8, + qdss_cti_trig_out_b, bimc_dte0, dac_calib1, qdss_cti_trig_in_b, + dac_calib2, atest_tsens2, atest_usb1, blsp_spi10, blsp_uart10, + blsp_uim10, atest_bbrx1, atest_usb13, atest_bbrx0, atest_usb12, + mdp_vsync, edp_lcd, blsp_i2c10, atest_gpsadc1, atest_usb11, + atest_gpsadc0, edp_hot, atest_usb10, m_voc, dac_gpio, + atest_char, cam_mclk, pll_bypassnl, qdss_stm7, blsp_i2c8, + qdss_tracedata_b, pll_reset, qdss_stm6, qdss_stm5, qdss_stm4, + atest_usb2, cci_i2c, qdss_stm3, dac_calib3, atest_usb23, + atest_char3, dac_calib4, qdss_stm2, atest_usb22, atest_char2, + qdss_stm1, dac_calib5, atest_usb21, atest_char1, dbg_out, + qdss_stm0, dac_calib6, atest_usb20, atest_char0, dac_calib10, + qdss_stm10, qdss_cti_trig_in_a, cci_timer4, blsp_spi6, + blsp_uart6, blsp_uim6, blsp2_spi, qdss_stm9, + qdss_cti_trig_out_a, dac_calib11, qdss_stm8, cci_timer0, + qdss_stm13, dac_calib7, cci_timer1, qdss_stm12, dac_calib8, + cci_timer2, blsp1_spi, qdss_stm11, dac_calib9, cci_timer3, + cci_async, dac_calib12, blsp_i2c6, qdss_tracectl_a, + dac_calib13, qdss_traceclk_a, dac_calib14, dac_calib15, + hdmi_rcv, dac_calib16, hdmi_cec, pwr_modem, dac_calib17, + hdmi_ddc, pwr_nav, dac_calib18, pwr_crypto, dac_calib19, + hdmi_hot, dac_calib20, dac_calib21, pci_e0, dac_calib22, + dac_calib23, dac_calib24, tsif1_sync, dac_calib25, sd_write, + tsif1_error, blsp_spi2, blsp_uart2, blsp_uim2, qdss_cti, + blsp_i2c2, blsp_spi3, blsp_uart3, blsp_uim3, blsp_i2c3, uim3, + blsp_spi9, blsp_uart9, blsp_uim9, blsp10_spi, blsp_i2c9, + blsp_spi7, blsp_uart7, blsp_uim7, qdss_tracedata_a, blsp_i2c7, + qua_mi2s, gcc_gp1_clk_a, ssc_irq, uim4, blsp_spi11, + blsp_uart11, blsp_uim11, gcc_gp2_clk_a, gcc_gp3_clk_a, + blsp_i2c11, cri_trng0, cri_trng1, cri_trng, qdss_stm18, + pri_mi2s, qdss_stm17, blsp_spi4, blsp_uart4, blsp_uim4, + qdss_stm16, qdss_stm15, blsp_i2c4, qdss_stm14, dac_calib26, + spkr_i2s, audio_ref, lpass_slimbus, isense_dbg, tsense_pwm1, + tsense_pwm2, btfm_slimbus, ter_mi2s, qdss_stm22, qdss_stm21, + qdss_stm20, qdss_stm19, gcc_gp1_clk_b, sec_mi2s, blsp_spi5, + blsp_uart5, blsp_uim5, gcc_gp2_clk_b, gcc_gp3_clk_b, blsp_i2c5, + blsp_spi12, blsp_uart12, blsp_uim12, qdss_stm25, qdss_stm31, + blsp_i2c12, qdss_stm30, qdss_stm29, tsif1_clk, qdss_stm28, + tsif1_en, tsif1_data, sdc4_cmd, qdss_stm27, qdss_traceclk_b, + tsif2_error, sdc43, vfr_1, qdss_stm26, tsif2_clk, sdc4_clk, + qdss_stm24, tsif2_en, sdc42, qdss_stm23, qdss_tracectl_b, + sd_card, tsif2_data, sdc41, tsif2_sync, sdc40, mdp_vsync_p_b, + ldo_en, mdp_vsync_s_b, ldo_update, blsp11_uart_tx_b, + blsp11_uart_rx_b, blsp11_i2c_sda_b, prng_rosc, + blsp11_i2c_scl_b, uim2, uim1, uim_batt, pci_e2, pa_indicator, + adsp_ext, ddr_bist, qdss_tracedata_11, qdss_tracedata_12, + modem_tsync, nav_dr, nav_pps, pci_e1, gsm_tx, qspi_cs, ssbi2, + ssbi1, mss_lte, qspi_clk, qspi0, qspi1, qspi2, qspi3 ] + + 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 + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + tlmm: pinctrl@1010000 { + compatible = "qcom,msm8996-pinctrl"; + reg = <0x01010000 0x300000>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + gpio-ranges = <&tlmm 0 0 150>; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + + blsp1-spi1-default-state { + spi-pins { + pins = "gpio0", "gpio1", "gpio3"; + function = "blsp_spi1"; + drive-strength = <12>; + bias-disable; + }; + + cs-pins { + pins = "gpio2"; + function = "gpio"; + drive-strength = <16>; + bias-disable; + output-high; + }; + }; + + blsp1-spi1-sleep-state { + pins = "gpio0", "gpio1", "gpio2", "gpio3"; + function = "gpio"; + drive-strength = <2>; + bias-pull-down; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt deleted file mode 100644 index c4de930f2406..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt +++ /dev/null @@ -1,202 +0,0 @@ -Qualcomm MSM8998 TLMM block - -This binding describes the Top Level Mode Multiplexer block found in the -MSM8998 platform. - -- compatible: - Usage: required - Value type: <string> - Definition: must be "qcom,msm8998-pinctrl" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: the base address and size of the TLMM register space. - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: should specify the TLMM summary IRQ. - -- interrupt-controller: - Usage: required - Value type: <none> - Definition: identifies this node as an interrupt controller - -- #interrupt-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/interrupt-controller/irq.h> - -- gpio-controller: - Usage: required - Value type: <none> - Definition: identifies this node as a gpio controller - -- #gpio-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/gpio/gpio.h> - -- gpio-ranges: - Usage: required - Definition: see ../gpio/gpio.txt - -- gpio-reserved-ranges: - Usage: optional - Definition: see ../gpio/gpio.txt - -Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for -a general description of GPIO and interrupt bindings. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -The pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - - -PIN CONFIGURATION NODES: - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. - - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pin configuration subnode: - -- pins: - Usage: required - Value type: <string-array> - Definition: List of gpio pins affected by the properties specified in - this subnode. - - Valid pins are: - gpio0-gpio149 - Supports mux, bias and drive-strength - - sdc2_clk, sdc2_cmd, sdc2_data - Supports bias and drive-strength - - ufs_reset - Supports bias and drive-strength - -- function: - Usage: required - Value type: <string> - Definition: Specify the alternative function to be configured for the - specified pins. Functions are only valid for gpio pins. - Valid values are: - - gpio, adsp_ext, agera_pll, atest_char, atest_gpsadc0, - atest_gpsadc1, atest_tsens, atest_tsens2, atest_usb1, - atest_usb10, atest_usb11, atest_usb12, atest_usb13, - audio_ref, bimc_dte0, bimc_dte1, blsp10_spi, blsp10_spi_a, - blsp10_spi_b, blsp11_i2c, blsp1_spi, blsp1_spi_a, - blsp1_spi_b, blsp2_spi, blsp9_spi, blsp_i2c1, blsp_i2c2, - blsp_i2c3, blsp_i2c4, blsp_i2c5, blsp_i2c6, blsp_i2c7, - blsp_i2c8, blsp_i2c9, blsp_i2c10, blsp_i2c11, blsp_i2c12, - blsp_spi1, blsp_spi2, blsp_spi3, blsp_spi4, blsp_spi5, - blsp_spi6, blsp_spi7, blsp_spi8, blsp_spi9, blsp_spi10, - blsp_spi11, blsp_spi12, blsp_uart1_a, blsp_uart1_b, - blsp_uart2_a, blsp_uart2_b, blsp_uart3_a, blsp_uart3_b, - blsp_uart7_a, blsp_uart7_b, blsp_uart8, blsp_uart8_a, - blsp_uart8_b, blsp_uart9_a, blsp_uart9_b, blsp_uim1_a, - blsp_uim1_b, blsp_uim2_a, blsp_uim2_b, blsp_uim3_a, - blsp_uim3_b, blsp_uim7_a, blsp_uim7_b, blsp_uim8_a, - blsp_uim8_b, blsp_uim9_a, blsp_uim9_b, bt_reset, - btfm_slimbus, cam_mclk, cci_async, cci_i2c, cci_timer0, - cci_timer1, cci_timer2, cci_timer3, cci_timer4, cri_trng, - cri_trng0, cri_trng1, dbg_out, ddr_bist, edp_hot, edp_lcd, - gcc_gp1_a, gcc_gp1_b, gcc_gp2_a, gcc_gp2_b, gcc_gp3_a, - gcc_gp3_b, hdmi_cec, hdmi_ddc, hdmi_hot, hdmi_rcv, - isense_dbg, jitter_bist, ldo_en, ldo_update, lpass_slimbus, - m_voc, mdp_vsync, mdp_vsync0, mdp_vsync1, mdp_vsync2, - mdp_vsync3, mdp_vsync_a, mdp_vsync_b, modem_tsync, mss_lte, - nav_dr, nav_pps, pa_indicator, pci_e0, phase_flag, - pll_bypassnl, pll_reset, pri_mi2s, pri_mi2s_ws, prng_rosc, - pwr_crypto, pwr_modem, pwr_nav, qdss_cti0_a, qdss_cti0_b, - qdss_cti1_a, qdss_cti1_b, qdss, qlink_enable, - qlink_request, qua_mi2s, sd_card, sd_write, sdc40, sdc41, - sdc42, sdc43, sdc4_clk, sdc4_cmd, sec_mi2s, sp_cmu, - spkr_i2s, ssbi1, ssc_irq, ter_mi2s, tgu_ch0, tgu_ch1, - tsense_pwm1, tsense_pwm2, tsif0, tsif1, - uim1_clk, uim1_data, uim1_present, - uim1_reset, uim2_clk, uim2_data, uim2_present, uim2_reset, - uim_batt, usb_phy, vfr_1, vsense_clkout, vsense_data0, - vsense_data1, vsense_mode, wlan1_adc0, wlan1_adc1, - wlan2_adc0, wlan2_adc1, - -- bias-disable: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as no pull. - -- bias-pull-down: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull down. - -- bias-pull-up: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull up. - -- output-high: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - high. - Not valid for sdc pins. - -- output-low: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - low. - Not valid for sdc pins. - -- drive-strength: - Usage: optional - Value type: <u32> - Definition: Selects the drive strength for the specified pins, in mA. - Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16 - -Example: - - tlmm: pinctrl@03400000 { - compatible = "qcom,msm8998-pinctrl"; - reg = <0x03400000 0xc00000>; - interrupts = <0 208 0>; - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&tlmm 0 0 175>; - gpio-reserved-ranges = <0 4>, <81 4>; - interrupt-controller; - #interrupt-cells = <2>; - - uart_console_active: uart_console_active { - mux { - pins = "gpio4", "gpio5"; - function = "blsp_uart8_a"; - }; - - config { - pins = "gpio4", "gpio5"; - drive-strength = <2>; - bias-disable; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.yaml new file mode 100644 index 000000000000..21ba32cc204a --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.yaml @@ -0,0 +1,171 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,msm8998-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm MSM8998 TLMM pin controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in Qualcomm MSM8998 SoC. + +properties: + compatible: + const: qcom,msm8998-pinctrl + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 75 + + gpio-line-names: + maxItems: 150 + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-msm8998-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-msm8998-tlmm-state" + additionalProperties: false + +$defs: + qcom-msm8998-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])$" + - enum: [ sdc2_clk, sdc2_cmd, sdc2_data, ufs_reset ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ gpio, adsp_ext, agera_pll, atest_char, atest_gpsadc0, + atest_gpsadc1, atest_tsens, atest_tsens2, atest_usb1, + atest_usb10, atest_usb11, atest_usb12, atest_usb13, audio_ref, + bimc_dte0, bimc_dte1, blsp10_spi, blsp10_spi_a, blsp10_spi_b, + blsp11_i2c, blsp1_spi, blsp1_spi_a, blsp1_spi_b, blsp2_spi, + blsp9_spi, blsp_i2c1, blsp_i2c2, blsp_i2c3, blsp_i2c4, + blsp_i2c5, blsp_i2c6, blsp_i2c7, blsp_i2c8, blsp_i2c9, + blsp_i2c10, blsp_i2c11, blsp_i2c12, blsp_spi1, blsp_spi2, + blsp_spi3, blsp_spi4, blsp_spi5, blsp_spi6, blsp_spi7, + blsp_spi8, blsp_spi9, blsp_spi10, blsp_spi11, blsp_spi12, + blsp_uart1_a, blsp_uart1_b, blsp_uart2_a, blsp_uart2_b, + blsp_uart3_a, blsp_uart3_b, blsp_uart7_a, blsp_uart7_b, + blsp_uart8, blsp_uart8_a, blsp_uart8_b, blsp_uart9_a, + blsp_uart9_b, blsp_uim1_a, blsp_uim1_b, blsp_uim2_a, + blsp_uim2_b, blsp_uim3_a, blsp_uim3_b, blsp_uim7_a, + blsp_uim7_b, blsp_uim8_a, blsp_uim8_b, blsp_uim9_a, + blsp_uim9_b, bt_reset, btfm_slimbus, cam_mclk, cci_async, + cci_i2c, cci_timer0, cci_timer1, cci_timer2, cci_timer3, + cci_timer4, cri_trng, cri_trng0, cri_trng1, dbg_out, ddr_bist, + edp_hot, edp_lcd, gcc_gp1_a, gcc_gp1_b, gcc_gp2_a, gcc_gp2_b, + gcc_gp3_a, gcc_gp3_b, hdmi_cec, hdmi_ddc, hdmi_hot, hdmi_rcv, + isense_dbg, jitter_bist, ldo_en, ldo_update, lpass_slimbus, + m_voc, mdp_vsync, mdp_vsync0, mdp_vsync1, mdp_vsync2, + mdp_vsync3, mdp_vsync_a, mdp_vsync_b, modem_tsync, mss_lte, + nav_dr, nav_pps, pa_indicator, pci_e0, phase_flag, + pll_bypassnl, pll_reset, pri_mi2s, pri_mi2s_ws, prng_rosc, + pwr_crypto, pwr_modem, pwr_nav, qdss_cti0_a, qdss_cti0_b, + qdss_cti1_a, qdss_cti1_b, qdss, qlink_enable, qlink_request, + qua_mi2s, sd_card, sd_write, sdc40, sdc41, sdc42, sdc43, + sdc4_clk, sdc4_cmd, sec_mi2s, sp_cmu, spkr_i2s, ssbi1, ssc_irq, + ter_mi2s, tgu_ch0, tgu_ch1, tsense_pwm1, tsense_pwm2, tsif0, + tsif1, uim1_clk, uim1_data, uim1_present, uim1_reset, uim2_clk, + uim2_data, uim2_present, uim2_reset, uim_batt, usb_phy, vfr_1, + vsense_clkout, vsense_data0, vsense_data1, vsense_mode, + wlan1_adc0, wlan1_adc1, wlan2_adc0, wlan2_adc1 ] + + 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 + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + tlmm: pinctrl@3400000 { + compatible = "qcom,msm8998-pinctrl"; + reg = <0x03400000 0xc00000>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-ranges = <&tlmm 0 0 150>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-reserved-ranges = <0 4>, <81 4>; + + sdc2-off-state { + clk-pins { + pins = "sdc2_clk"; + drive-strength = <2>; + bias-disable; + }; + + cmd-pins { + pins = "sdc2_cmd"; + drive-strength = <2>; + bias-pull-up; + }; + + data-pins { + pins = "sdc2_data"; + drive-strength = <2>; + bias-pull-up; + }; + }; + + sdc2-cd-state { + pins = "gpio95"; + function = "gpio"; + bias-pull-up; + drive-strength = <2>; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.yaml index df79274d0ec3..72cce38bc1ce 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.yaml @@ -15,28 +15,29 @@ description: properties: compatible: - items: - - enum: - - qcom,pm8018-mpp - - qcom,pm8019-mpp - - qcom,pm8038-mpp - - qcom,pm8058-mpp - - qcom,pm8226-mpp - - qcom,pm8821-mpp - - qcom,pm8841-mpp - - qcom,pm8916-mpp - - qcom,pm8917-mpp - - qcom,pm8921-mpp - - qcom,pm8941-mpp - - qcom,pm8950-mpp - - qcom,pmi8950-mpp - - qcom,pm8994-mpp - - qcom,pma8084-mpp - - qcom,pmi8994-mpp - - - enum: - - qcom,spmi-mpp - - qcom,ssbi-mpp + oneOf: + - items: + - enum: + - qcom,pm8019-mpp + - qcom,pm8226-mpp + - qcom,pm8841-mpp + - qcom,pm8916-mpp + - qcom,pm8941-mpp + - qcom,pm8950-mpp + - qcom,pmi8950-mpp + - qcom,pm8994-mpp + - qcom,pma8084-mpp + - qcom,pmi8994-mpp + - const: qcom,spmi-mpp + - items: + - enum: + - qcom,pm8018-mpp + - qcom,pm8038-mpp + - qcom,pm8058-mpp + - qcom,pm8821-mpp + - qcom,pm8917-mpp + - qcom,pm8921-mpp + - const: qcom,ssbi-mpp reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,qcm2290-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,qcm2290-tlmm.yaml index 3f4f1c0360b5..adf64bfaa4ed 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,qcm2290-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,qcm2290-tlmm.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/pinctrl/qcom,qcm2290-pinctrl.yaml# +$id: http://devicetree.org/schemas/pinctrl/qcom,qcm2290-tlmm.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. QCM2290 TLMM block @@ -10,8 +10,7 @@ maintainers: - Shawn Guo <shawn.guo@linaro.org> description: - This binding describes the Top Level Mode Multiplexer block found in the - QCM2290 platform. + Top Level Mode Multiplexer pin controller in Qualcomm QCM2290 SoC. properties: compatible: @@ -20,46 +19,30 @@ properties: reg: maxItems: 1 - interrupts: - description: Specifies the TLMM summary IRQ - maxItems: 1 - + interrupts: true interrupt-controller: true - - '#interrupt-cells': - description: - Specifies the PIN numbers and Flags, as defined in defined in - include/dt-bindings/interrupt-controller/irq.h - const: 2 - + "#interrupt-cells": true 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 - + "#gpio-cells": true + gpio-ranges: true wakeup-parent: true -#PIN CONFIGURATION NODES patternProperties: - '-state$': + "-state$": oneOf: - $ref: "#/$defs/qcom-qcm2290-tlmm-state" - patternProperties: - ".*": + "-pins$": $ref: "#/$defs/qcom-qcm2290-tlmm-state" + additionalProperties: false -'$defs': +$defs: qcom-qcm2290-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" + $ref: qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state properties: pins: @@ -96,20 +79,11 @@ patternProperties: uim2_data, uim2_present, uim2_reset, usb_phy, vfr_1, vsense_trigger, wlan1_adc0, wlan1_adc1 ] - drive-strength: - enum: [2, 4, 6, 8, 10, 12, 14, 16] - default: 2 - description: - Selects the drive strength for the specified pins, in mA. - bias-pull-down: true - bias-pull-up: true - bias-disable: true - + drive-strength: true output-high: true - output-low: true required: @@ -118,17 +92,11 @@ patternProperties: additionalProperties: false allOf: - - $ref: "pinctrl.yaml#" + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# required: - compatible - reg - - interrupts - - interrupt-controller - - '#interrupt-cells' - - gpio-controller - - '#gpio-cells' - - gpio-ranges additionalProperties: false @@ -146,19 +114,19 @@ examples: gpio-ranges = <&tlmm 0 0 127>; sdc2_on_state: sdc2-on-state { - clk { + clk-pins { pins = "sdc2_clk"; bias-disable; drive-strength = <16>; }; - cmd { + cmd-pins { pins = "sdc2_cmd"; bias-pull-up; drive-strength = <10>; }; - data { + data-pins { pins = "sdc2_data"; bias-pull-up; drive-strength = <10>; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.txt deleted file mode 100644 index a50e74684195..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.txt +++ /dev/null @@ -1,199 +0,0 @@ -Qualcomm QCS404 TLMM block - -This binding describes the Top Level Mode Multiplexer block found in the -QCS404 platform. - -- compatible: - Usage: required - Value type: <string> - Definition: must be "qcom,qcs404-pinctrl" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: the base address and size of the north, south and east TLMM - tiles. - -- reg-names: - Usage: required - Value type: <stringlist> - Defintiion: names for the cells of reg, must contain "north", "south" - and "east". - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: should specify the TLMM summary IRQ. - -- interrupt-controller: - Usage: required - Value type: <none> - Definition: identifies this node as an interrupt controller - -- #interrupt-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/interrupt-controller/irq.h> - -- gpio-controller: - Usage: required - Value type: <none> - Definition: identifies this node as a gpio controller - -- #gpio-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/gpio/gpio.h> - -- gpio-ranges: - Usage: required - Definition: see ../gpio/gpio.txt - -Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for -a general description of GPIO and interrupt bindings. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -The pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - - -PIN CONFIGURATION NODES: - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. - - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pin configuration subnode: - -- pins: - Usage: required - Value type: <string-array> - Definition: List of gpio pins affected by the properties specified in - this subnode. - - Valid pins are: - gpio0-gpio119 - Supports mux, bias and drive-strength - - sdc1_clk, sdc1_cmd, sdc1_data, sdc2_clk, sdc2_cmd, - sdc2_data - Supports bias and drive-strength - - ufs_reset - Supports bias and drive-strength - -- function: - Usage: required - Value type: <string> - Definition: Specify the alternative function to be configured for the - specified pins. Functions are only valid for gpio pins. - Valid values are: - - gpio, hdmi_tx, hdmi_ddc, blsp_uart_tx_a2, blsp_spi2, m_voc, - qdss_cti_trig_in_a0, blsp_uart_rx_a2, qdss_tracectl_a, - blsp_uart2, aud_cdc, blsp_i2c_sda_a2, qdss_tracedata_a, - blsp_i2c_scl_a2, qdss_tracectl_b, qdss_cti_trig_in_b0, - blsp_uart1, blsp_spi_mosi_a1, blsp_spi_miso_a1, - qdss_tracedata_b, blsp_i2c1, blsp_spi_cs_n_a1, gcc_plltest, - blsp_spi_clk_a1, rgb_data0, blsp_uart5, blsp_spi5, - adsp_ext, rgb_data1, prng_rosc, rgb_data2, blsp_i2c5, - gcc_gp1_clk_b, rgb_data3, gcc_gp2_clk_b, blsp_spi0, - blsp_uart0, gcc_gp3_clk_b, blsp_i2c0, qdss_traceclk_b, - pcie_clk, nfc_irq, blsp_spi4, nfc_dwl, audio_ts, rgb_data4, - spi_lcd, blsp_uart_tx_b2, gcc_gp3_clk_a, rgb_data5, - blsp_uart_rx_b2, blsp_i2c_sda_b2, blsp_i2c_scl_b2, - pwm_led11, i2s_3_data0_a, ebi2_lcd, i2s_3_data1_a, - i2s_3_data2_a, atest_char, pwm_led3, i2s_3_data3_a, - pwm_led4, i2s_4, ebi2_a, dsd_clk_b, pwm_led5, pwm_led6, - pwm_led7, pwm_led8, pwm_led24, spkr_dac0, blsp_i2c4, - pwm_led9, pwm_led10, spdifrx_opt, pwm_led12, pwm_led13, - pwm_led14, wlan1_adc1, rgb_data_b0, pwm_led15, - blsp_spi_mosi_b1, wlan1_adc0, rgb_data_b1, pwm_led16, - blsp_spi_miso_b1, qdss_cti_trig_out_b0, wlan2_adc1, - rgb_data_b2, pwm_led17, blsp_spi_cs_n_b1, wlan2_adc0, - rgb_data_b3, pwm_led18, blsp_spi_clk_b1, rgb_data_b4, - pwm_led19, ext_mclk1_b, qdss_traceclk_a, rgb_data_b5, - pwm_led20, atest_char3, i2s_3_sck_b, ldo_update, bimc_dte0, - rgb_hsync, pwm_led21, i2s_3_ws_b, dbg_out, rgb_vsync, - i2s_3_data0_b, ldo_en, hdmi_dtest, rgb_de, i2s_3_data1_b, - hdmi_lbk9, rgb_clk, atest_char1, i2s_3_data2_b, ebi_cdc, - hdmi_lbk8, rgb_mdp, atest_char0, i2s_3_data3_b, hdmi_lbk7, - rgb_data_b6, rgb_data_b7, hdmi_lbk6, rgmii_int, cri_trng1, - rgmii_wol, cri_trng0, gcc_tlmm, rgmii_ck, rgmii_tx, - hdmi_lbk5, hdmi_pixel, hdmi_rcv, hdmi_lbk4, rgmii_ctl, - ext_lpass, rgmii_rx, cri_trng, hdmi_lbk3, hdmi_lbk2, - qdss_cti_trig_out_b1, rgmii_mdio, hdmi_lbk1, rgmii_mdc, - hdmi_lbk0, ir_in, wsa_en, rgb_data6, rgb_data7, - atest_char2, ebi_ch0, blsp_uart3, blsp_spi3, sd_write, - blsp_i2c3, gcc_gp1_clk_a, qdss_cti_trig_in_b1, - gcc_gp2_clk_a, ext_mclk0, mclk_in1, i2s_1, dsd_clk_a, - qdss_cti_trig_in_a1, rgmi_dll1, pwm_led22, pwm_led23, - qdss_cti_trig_out_a0, rgmi_dll2, pwm_led1, - qdss_cti_trig_out_a1, pwm_led2, i2s_2, pll_bist, - ext_mclk1_a, mclk_in2, bimc_dte1, i2s_3_sck_a, i2s_3_ws_a - -- bias-disable: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as no pull. - -- bias-pull-down: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull down. - -- bias-pull-up: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull up. - -- output-high: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - high. - Not valid for sdc pins. - -- output-low: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - low. - Not valid for sdc pins. - -- drive-strength: - Usage: optional - Value type: <u32> - Definition: Selects the drive strength for the specified pins, in mA. - Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16 - -Example: - - tlmm: pinctrl@1000000 { - compatible = "qcom,qcs404-pinctrl"; - reg = <0x01000000 0x200000>, - <0x01300000 0x200000>, - <0x07b00000 0x200000>; - reg-names = "south", "north", "east"; - interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&tlmm 0 0 120>; - interrupt-controller; - #interrupt-cells = <2>; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.yaml new file mode 100644 index 000000000000..29d50c4a0034 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.yaml @@ -0,0 +1,176 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,qcs404-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm QCS404 TLMM pin controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in Qualcomm QCS404 SoC. + +properties: + compatible: + const: qcom,qcs404-pinctrl + + reg: + maxItems: 3 + + reg-names: + items: + - const: south + - const: north + - const: east + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 60 + + gpio-line-names: + maxItems: 120 + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-qcs404-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-qcs404-tlmm-state" + additionalProperties: false + +$defs: + qcom-qcs404-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-1][0-9])$" + - enum: [ sdc1_clk, sdc1_cmd, sdc1_data, sdc1_rclk, sdc2_clk, + sdc2_cmd, sdc2_data, ufs_reset ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ gpio, adsp_ext, atest_char, atest_char0, atest_char1, + atest_char2, atest_char3, aud_cdc, audio_ts, bimc_dte0, + bimc_dte1, blsp_i2c0, blsp_i2c1, blsp_i2c3, blsp_i2c4, + blsp_i2c5, blsp_i2c_scl_a2, blsp_i2c_scl_b2, blsp_i2c_sda_a2, + blsp_i2c_sda_b2, blsp_spi0, blsp_spi2, blsp_spi3, blsp_spi4, + blsp_spi5, blsp_spi_clk_a1, blsp_spi_clk_b1, blsp_spi_cs_n_a1, + blsp_spi_cs_n_b1, blsp_spi_miso_a1, blsp_spi_miso_b1, + blsp_spi_mosi_a1, blsp_spi_mosi_b1, blsp_uart0, blsp_uart1, + blsp_uart2, blsp_uart3, blsp_uart5, blsp_uart_rx_a2, + blsp_uart_rx_b2, blsp_uart_tx_a2, blsp_uart_tx_b2, cri_trng, + cri_trng0, cri_trng1, dbg_out, dsd_clk_a, dsd_clk_b, ebi2_a, + ebi2_lcd, ebi_cdc, ebi_ch0, ext_lpass, ext_mclk0, ext_mclk1_a, + ext_mclk1_b, gcc_gp1_clk_a, gcc_gp1_clk_b, gcc_gp2_clk_a, + gcc_gp2_clk_b, gcc_gp3_clk_a, gcc_gp3_clk_b, gcc_plltest, + gcc_tlmm, hdmi_ddc, hdmi_dtest, hdmi_lbk0, hdmi_lbk1, + hdmi_lbk2, hdmi_lbk3, hdmi_lbk4, hdmi_lbk5, hdmi_lbk6, + hdmi_lbk7, hdmi_lbk8, hdmi_lbk9, hdmi_pixel, hdmi_rcv, hdmi_tx, + i2s_1, i2s_2, i2s_3_data0_a, i2s_3_data0_b, i2s_3_data1_a, + i2s_3_data1_b, i2s_3_data2_a, i2s_3_data2_b, i2s_3_data3_a, + i2s_3_data3_b, i2s_3_sck_a, i2s_3_sck_b, i2s_3_ws_a, + i2s_3_ws_b, i2s_4, ir_in, ldo_en, ldo_update, mclk_in1, + mclk_in2, m_voc, nfc_dwl, nfc_irq, pcie_clk, pll_bist, + prng_rosc, pwm_led1, pwm_led10, pwm_led11, pwm_led12, + pwm_led13, pwm_led14, pwm_led15, pwm_led16, pwm_led17, + pwm_led18, pwm_led19, pwm_led2, pwm_led20, pwm_led21, + pwm_led22, pwm_led23, pwm_led24, pwm_led3, pwm_led4, pwm_led5, + pwm_led6, pwm_led7, pwm_led8, pwm_led9, 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, rgb_clk, rgb_data0, + rgb_data1, rgb_data2, rgb_data3, rgb_data4, rgb_data5, + rgb_data6, rgb_data7, rgb_data_b0, rgb_data_b1, rgb_data_b2, + rgb_data_b3, rgb_data_b4, rgb_data_b5, rgb_data_b6, + rgb_data_b7, rgb_de, rgb_hsync, rgb_mdp, rgb_vsync, rgmi_dll1, + rgmi_dll2, rgmii_ck, rgmii_ctl, rgmii_int, rgmii_mdc, + rgmii_mdio, rgmii_rx, rgmii_tx, rgmii_wol, sd_write, + spdifrx_opt, spi_lcd, spkr_dac0, wlan1_adc0, wlan1_adc1, + wlan2_adc0, wlan2_adc1, wsa_en ] + + 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 + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + tlmm: pinctrl@1000000 { + compatible = "qcom,qcs404-pinctrl"; + reg = <0x01000000 0x200000>, + <0x01300000 0x200000>, + <0x07b00000 0x200000>; + reg-names = "south", "north", "east"; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-ranges = <&tlmm 0 0 120>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + + + blsp1-i2c1-default-state { + pins = "gpio24", "gpio25"; + function = "blsp_i2c1"; + }; + + blsp1-i2c2-default-state { + sda-pins { + pins = "gpio19"; + function = "blsp_i2c_sda_a2"; + }; + + scl-pins { + pins = "gpio20"; + function = "blsp_i2c_scl_a2"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.txt deleted file mode 100644 index 6ffeac9801df..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.txt +++ /dev/null @@ -1,187 +0,0 @@ -Qualcomm Technologies, Inc. SC7180 TLMM block - -This binding describes the Top Level Mode Multiplexer block found in the -SC7180 platform. - -- compatible: - Usage: required - Value type: <string> - Definition: must be "qcom,sc7180-pinctrl" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: the base address and size of the north, south and west - TLMM tiles - -- reg-names: - Usage: required - Value type: <prop-encoded-array> - Definition: names for the cells of reg, must contain "north", "south" - and "west". - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: should specify the TLMM summary IRQ. - -- interrupt-controller: - Usage: required - Value type: <none> - Definition: identifies this node as an interrupt controller - -- #interrupt-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/interrupt-controller/irq.h> - -- gpio-controller: - Usage: required - Value type: <none> - Definition: identifies this node as a gpio controller - -- #gpio-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/gpio/gpio.h> - -- gpio-ranges: - Usage: required - Value type: <prop-encoded-array> - Definition: see ../gpio/gpio.txt - -- gpio-reserved-ranges: - Usage: optional - Value type: <prop-encoded-array> - Definition: see ../gpio/gpio.txt - -Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for -a general description of GPIO and interrupt bindings. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -The pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - - -PIN CONFIGURATION NODES: - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. - - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pin configuration subnode: - -- pins: - Usage: required - Value type: <string-array> - Definition: List of gpio pins affected by the properties specified in - this subnode. - - Valid pins are: - gpio0-gpio118 - Supports mux, bias and drive-strength - - sdc1_clk, sdc1_cmd, sdc1_data sdc2_clk, sdc2_cmd, - sdc2_data sdc1_rclk - Supports bias and drive-strength - - ufs_reset - Supports bias and drive-strength - -- function: - Usage: required - Value type: <string> - Definition: Specify the alternative function to be configured for the - specified pins. Functions are only valid for gpio pins. - Valid values are: - - adsp_ext, agera_pll, aoss_cti, atest_char, atest_char0, - atest_char1, atest_char2, atest_char3, atest_tsens, - atest_tsens2, atest_usb1, atest_usb10, atest_usb11, - atest_usb12, atest_usb13, atest_usb2, atest_usb20, - atest_usb21, atest_usb22, atest_usb23, audio_ref, - btfm_slimbus, cam_mclk, cci_async, cci_i2c, cci_timer0, - cci_timer1, cci_timer2, cci_timer3, cci_timer4, - cri_trng, dbg_out, ddr_bist, ddr_pxi0, ddr_pxi1, - ddr_pxi2, ddr_pxi3, dp_hot, edp_lcd, gcc_gp1, gcc_gp2, - gcc_gp3, gpio, gp_pdm0, gp_pdm1, gp_pdm2, gps_tx, - jitter_bist, ldo_en, ldo_update, lpass_ext, mdp_vsync, - mdp_vsync0, mdp_vsync1, mdp_vsync2, mdp_vsync3, mi2s_0, - mi2s_1, mi2s_2, mss_lte, m_voc, pa_indicator, phase_flag, - PLL_BIST, pll_bypassnl, pll_reset, prng_rosc, qdss, - qdss_cti, qlink_enable, qlink_request, qspi_clk, qspi_cs, - qspi_data, qup00, qup01, qup02_i2c, qup02_uart, qup03, - qup04_i2c, qup04_uart, qup05, qup10, qup11_i2c, qup11_uart, - qup12, qup13_i2c, qup13_uart, qup14, qup15, sdc1_tb, - sdc2_tb, sd_write, sp_cmu, tgu_ch0, tgu_ch1, tgu_ch2, - tgu_ch3, tsense_pwm1, tsense_pwm2, uim1, uim2, uim_batt, - usb_phy, vfr_1, _V_GPIO, _V_PPS_IN, _V_PPS_OUT, - vsense_trigger, wlan1_adc0, wlan1_adc1, wlan2_adc0, - wlan2_adc1, - -- bias-disable: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as no pull. - -- bias-pull-down: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull down. - -- bias-pull-up: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull up. - -- output-high: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - high. - Not valid for sdc pins. - -- output-low: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - low. - Not valid for sdc pins. - -- drive-strength: - Usage: optional - Value type: <u32> - Definition: Selects the drive strength for the specified pins, in mA. - Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16 - -Example: - - tlmm: pinctrl@3500000 { - compatible = "qcom,sc7180-pinctrl"; - reg = <0x3500000 0x300000>, - <0x3900000 0x300000>, - <0x3D00000 0x300000>; - reg-names = "west", "north", "south"; - interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&tlmm 0 0 119>; - gpio-reserved-ranges = <0 4>, <106 4>; - interrupt-controller; - #interrupt-cells = <2>; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.yaml new file mode 100644 index 000000000000..b40f6dc6adae --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.yaml @@ -0,0 +1,158 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,sc7180-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SC7180 TLMM pin controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in Qualcomm SC7180 SoC. + +properties: + compatible: + const: qcom,sc7180-pinctrl + + reg: + maxItems: 3 + + reg-names: + items: + - const: west + - const: north + - const: south + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 60 + + gpio-line-names: + maxItems: 119 + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-sc7180-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sc7180-tlmm-state" + additionalProperties: false + +$defs: + qcom-sc7180-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]|10[0-9]|11[0-8])$" + - enum: [ sdc1_rclk, sdc1_clk, sdc1_cmd, sdc1_data, sdc2_clk, + sdc2_cmd, sdc2_data, ufs_reset ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ adsp_ext, agera_pll, aoss_cti, atest_char, atest_char0, + atest_char1, atest_char2, atest_char3, atest_tsens, + atest_tsens2, atest_usb1, atest_usb10, atest_usb11, + atest_usb12, atest_usb13, atest_usb2, atest_usb20, atest_usb21, + atest_usb22, atest_usb23, audio_ref, btfm_slimbus, cam_mclk, + cci_async, cci_i2c, cci_timer0, cci_timer1, cci_timer2, + cci_timer3, cci_timer4, cri_trng, dbg_out, ddr_bist, ddr_pxi0, + ddr_pxi1, ddr_pxi2, ddr_pxi3, dp_hot, edp_lcd, gcc_gp1, + gcc_gp2, gcc_gp3, gpio, gp_pdm0, gp_pdm1, gp_pdm2, gps_tx, + jitter_bist, ldo_en, ldo_update, lpass_ext, mdp_vsync, + mdp_vsync0, mdp_vsync1, mdp_vsync2, mdp_vsync3, mi2s_0, mi2s_1, + mi2s_2, mss_lte, m_voc, pa_indicator, phase_flag, PLL_BIST, + pll_bypassnl, pll_reset, prng_rosc, qdss, qdss_cti, + qlink_enable, qlink_request, qspi_clk, qspi_cs, qspi_data, + qup00, qup01, qup02_i2c, qup02_uart, qup03, qup04_i2c, + qup04_uart, qup05, qup10, qup11_i2c, qup11_uart, qup12, + qup13_i2c, qup13_uart, qup14, qup15, sdc1_tb, sdc2_tb, + sd_write, sp_cmu, tgu_ch0, tgu_ch1, tgu_ch2, tgu_ch3, + tsense_pwm1, tsense_pwm2, uim1, uim2, uim_batt, usb_phy, vfr_1, + _V_GPIO, _V_PPS_IN, _V_PPS_OUT, vsense_trigger, wlan1_adc0, + wlan1_adc1, wlan2_adc0, wlan2_adc1 ] + + 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 + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +required: + - compatible + - reg + - reg-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + tlmm: pinctrl@3500000 { + compatible = "qcom,sc7180-pinctrl"; + reg = <0x03500000 0x300000>, + <0x03900000 0x300000>, + <0x03d00000 0x300000>; + reg-names = "west", "north", "south"; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-ranges = <&tlmm 0 0 120>; + wakeup-parent = <&pdc>; + + dp_hot_plug_det: dp-hot-plug-det-state { + pins = "gpio117"; + function = "dp_hot"; + }; + + qup_spi11_cs_gpio: qup-spi11-cs-gpio-state { + spi-pins { + pins = "gpio53", "gpio54", "gpio55"; + function = "qup15"; + }; + + cs-pins { + pins = "gpio56"; + function = "gpio"; + }; + }; + }; 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 624e14f00790..f7ec8a4f664f 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-lpass-lpi-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-lpass-lpi-pinctrl.yaml @@ -4,15 +4,14 @@ $id: http://devicetree.org/schemas/pinctrl/qcom,sc7280-lpass-lpi-pinctrl.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Technologies, Inc. Low Power Audio SubSystem (LPASS) - Low Power Island (LPI) TLMM block +title: Qualcomm SC7280 SoC LPASS LPI TLMM maintainers: - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> -description: | - This binding describes the Top Level Mode Multiplexer block found in the - LPASS LPI IP on most Qualcomm SoCs +description: + Top Level Mode Multiplexer pin controller in the Low Power Audio SubSystem + (LPASS) Low Power Island (LPI) of Qualcomm SC7280 SoC. properties: compatible: @@ -24,12 +23,11 @@ properties: type: boolean reg: - minItems: 2 maxItems: 2 gpio-controller: true - '#gpio-cells': + "#gpio-cells": description: Specifying the pin number and flags, as defined in include/dt-bindings/gpio/gpio.h const: 2 @@ -37,9 +35,17 @@ properties: gpio-ranges: maxItems: 1 -#PIN CONFIGURATION NODES patternProperties: - '-pins$': + "-state$": + oneOf: + - $ref: "#/$defs/qcom-sc7280-lpass-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sc7280-lpass-state" + additionalProperties: false + +$defs: + qcom-sc7280-lpass-state: type: object description: Pinctrl node's client devices use subnodes for desired pin configuration. @@ -83,13 +89,10 @@ patternProperties: 3: Reserved (No adjustments) bias-pull-down: true - bias-pull-up: true - + bias-bus-hold: true bias-disable: true - output-high: true - output-low: true required: @@ -102,7 +105,7 @@ required: - compatible - reg - gpio-controller - - '#gpio-cells' + - "#gpio-cells" - gpio-ranges additionalProperties: false @@ -116,4 +119,21 @@ examples: gpio-controller; #gpio-cells = <2>; gpio-ranges = <&lpass_tlmm 0 0 15>; + + dmic01-state { + dmic01-clk-pins { + pins = "gpio6"; + function = "dmic1_clk"; + }; + + dmic01-clk-sleep-pins { + pins = "gpio6"; + function = "dmic1_clk"; + }; + }; + + tx-swr-data-sleep-state { + pins = "gpio1", "gpio2", "gpio14"; + function = "swr_tx_data"; + }; }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml index ad3496784678..36502173cb79 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml @@ -9,9 +9,8 @@ title: Qualcomm Technologies, Inc. SC7280 TLMM block maintainers: - Bjorn Andersson <andersson@kernel.org> -description: | - This binding describes the Top Level Mode Multiplexer block found in the - SC7280 platform. +description: + Top Level Mode Multiplexer pin controller in Qualcomm SC7280 SoC. properties: compatible: @@ -43,17 +42,26 @@ properties: maxItems: 1 gpio-line-names: - maxItems: 174 + maxItems: 175 wakeup-parent: true -#PIN CONFIGURATION NODES patternProperties: - '-pins$': + "-state$": + oneOf: + - $ref: "#/$defs/qcom-sc7280-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sc7280-tlmm-state" + additionalProperties: false + +$defs: + qcom-sc7280-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: @@ -62,7 +70,7 @@ patternProperties: subnode. items: oneOf: - - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-7][0-9]|18[0-2])$" + - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-6][0-9]|17[0-4])$" - enum: [ sdc1_rclk, sdc1_clk, sdc1_cmd, sdc1_data, sdc2_clk, sdc2_cmd, sdc2_data, ufs_reset ] minItems: 1 @@ -102,35 +110,18 @@ patternProperties: uim1_clk, uim1_data, uim1_present, uim1_reset, usb2phy_ac, usb_phy, vfr_0, vfr_1, vsense_trigger ] - drive-strength: - enum: [2, 4, 6, 8, 10, 12, 14, 16] - default: 2 - description: - Selects the drive strength for the specified pins, in mA. - bias-pull-down: true - bias-pull-up: true - + bias-bus-hold: true bias-disable: true - + drive-strength: true + input-enable: true output-high: true - output-low: true required: - pins - allOf: - - $ref: /schemas/pinctrl/pincfg-node.yaml - - if: - properties: - pins: - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-7][0-9]|18[0-2])$" - then: - required: - - function - additionalProperties: false allOf: @@ -162,7 +153,7 @@ examples: gpio-ranges = <&tlmm 0 0 175>; wakeup-parent = <&pdc>; - qup_uart5_default: qup-uart5-pins { + qup_uart5_default: qup-uart5-state { pins = "gpio46", "gpio47"; function = "qup13"; drive-strength = <2>; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc8180x-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sc8180x-tlmm.yaml index b98eeba2c530..24191d5f64ac 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc8180x-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc8180x-tlmm.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/pinctrl/qcom,sc8180x-pinctrl.yaml# +$id: http://devicetree.org/schemas/pinctrl/qcom,sc8180x-tlmm.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. SC8180X TLMM block @@ -9,12 +9,10 @@ title: Qualcomm Technologies, Inc. SC8180X TLMM block maintainers: - Bjorn Andersson <bjorn.andersson@linaro.org> -description: | - This binding describes the Top Level Mode Multiplexer block found in the - SC8180X platform. +description: + Top Level Mode Multiplexer pin controller in Qualcomm SC8180X SoC. allOf: - - $ref: "pinctrl.yaml#" - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# properties: @@ -26,9 +24,9 @@ properties: reg-names: items: - - const: "west" - - const: "east" - - const: "south" + - const: west + - const: east + - const: south interrupts: true interrupt-controller: true @@ -47,7 +45,7 @@ required: additionalProperties: false patternProperties: - '-state$': + "-state$": oneOf: - $ref: "#/$defs/qcom-sc8180x-tlmm-state" - patternProperties: @@ -55,12 +53,13 @@ patternProperties: $ref: "#/$defs/qcom-sc8180x-tlmm-state" additionalProperties: false -'$defs': +$defs: qcom-sc8180x-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: @@ -112,16 +111,6 @@ patternProperties: required: - pins - allOf: - - $ref: "qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state" - - if: - properties: - pins: - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-8][0-9])$" - then: - required: - - function - additionalProperties: false examples: 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 1f468303bb08..7d2589387e1a 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc8280xp-lpass-lpi-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc8280xp-lpass-lpi-pinctrl.yaml @@ -4,15 +4,14 @@ $id: http://devicetree.org/schemas/pinctrl/qcom,sc8280xp-lpass-lpi-pinctrl.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Technologies, Inc. Low Power Audio SubSystem (LPASS) - Low Power Island (LPI) TLMM block +title: Qualcomm SC8280XP SoC LPASS LPI TLMM maintainers: - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> -description: | - This binding describes the Top Level Mode Multiplexer block found in the - LPASS LPI IP on most Qualcomm SoCs +description: + Top Level Mode Multiplexer pin controller in the Low Power Audio SubSystem + (LPASS) Low Power Island (LPI) of Qualcomm SC8280XP SoC. properties: compatible: @@ -35,7 +34,7 @@ properties: gpio-controller: true - '#gpio-cells': + "#gpio-cells": description: Specifying the pin number and flags, as defined in include/dt-bindings/gpio/gpio.h const: 2 @@ -43,9 +42,17 @@ properties: gpio-ranges: maxItems: 1 -#PIN CONFIGURATION NODES patternProperties: - '-pins$': + "-state$": + oneOf: + - $ref: "#/$defs/qcom-sc8280xp-lpass-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sc8280xp-lpass-state" + additionalProperties: false + +$defs: + qcom-sc8280xp-lpass-state: type: object description: Pinctrl node's client devices use subnodes for desired pin configuration. @@ -58,7 +65,7 @@ patternProperties: List of gpio pins affected by the properties specified in this subnode. items: - pattern: "^gpio([0-1]|1[0-8]])$" + pattern: "^gpio([0-1]|1[0-8])$" function: enum: [ swr_tx_clk, swr_tx_data, swr_rx_clk, swr_rx_data, @@ -112,7 +119,7 @@ required: - clocks - clock-names - gpio-controller - - '#gpio-cells' + - "#gpio-cells" - gpio-ranges additionalProperties: false @@ -130,4 +137,21 @@ examples: gpio-controller; #gpio-cells = <2>; gpio-ranges = <&lpi_tlmm 0 0 18>; + + dmic01-state { + dmic01-clk-pins { + pins = "gpio16"; + function = "dmic1_clk"; + }; + + dmic01-clk-sleep-pins { + pins = "gpio16"; + function = "dmic1_clk"; + }; + }; + + tx-swr-data-sleep-state { + pins = "gpio0", "gpio1"; + function = "swr_tx_data"; + }; }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc8280xp-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sc8280xp-tlmm.yaml index b9ab130cd558..4efde29c36a2 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc8280xp-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc8280xp-tlmm.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/pinctrl/qcom,sc8280xp-pinctrl.yaml# +$id: http://devicetree.org/schemas/pinctrl/qcom,sc8280xp-tlmm.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. SC8280XP TLMM block @@ -10,8 +10,7 @@ maintainers: - Bjorn Andersson <bjorn.andersson@linaro.org> description: | - This binding describes the Top Level Mode Multiplexer block found in the - SC8280XP platform. + Top Level Mode Multiplexer pin controller in Qualcomm SC8280XP SoC. allOf: - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# @@ -25,10 +24,10 @@ properties: interrupts: true interrupt-controller: true - '#interrupt-cells': true + "#interrupt-cells": true gpio-controller: true gpio-reserved-ranges: true - '#gpio-cells': true + "#gpio-cells": true gpio-ranges: true wakeup-parent: true @@ -39,7 +38,7 @@ required: additionalProperties: false patternProperties: - '-state$': + "-state$": oneOf: - $ref: "#/$defs/qcom-sc8280xp-tlmm-state" - patternProperties: @@ -47,12 +46,13 @@ patternProperties: $ref: "#/$defs/qcom-sc8280xp-tlmm-state" additionalProperties: false -'$defs': +$defs: qcom-sc8280xp-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: @@ -113,16 +113,6 @@ patternProperties: required: - pins - allOf: - - $ref: "qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state" - - if: - properties: - pins: - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-1][0-9]|22[0-7])$" - then: - required: - - function - additionalProperties: false examples: @@ -139,8 +129,8 @@ examples: gpio-ranges = <&tlmm 0 0 230>; gpio-wo-subnode-state { - pins = "gpio1"; - function = "gpio"; + pins = "gpio1"; + function = "gpio"; }; uart-w-subnodes-state { diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdm630-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sdm630-pinctrl.yaml new file mode 100644 index 000000000000..bd4fd8404aa4 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sdm630-pinctrl.yaml @@ -0,0 +1,188 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,sdm630-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SDM630 and SDM660 TLMM pin controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in Qualcomm SDM630 and SDM660 SoC. + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +properties: + compatible: + enum: + - qcom,sdm630-pinctrl + - qcom,sdm660-pinctrl + + reg: + maxItems: 3 + + reg-names: + items: + - const: south + - const: center + - const: north + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 57 + + gpio-line-names: + maxItems: 114 + + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-sdm630-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sdm630-tlmm-state" + additionalProperties: false + +$defs: + qcom-sdm630-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]|10[0-9]|11[0-3])$" + - enum: [ sdc1_clk, sdc1_cmd, sdc1_data, sdc1_rclk, sdc2_clk, + sdc2_cmd, sdc2_data ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + enum: [ adsp_ext, agera_pll, atest_char, atest_char0, atest_char1, + atest_char2, atest_char3, atest_gpsadc0, atest_gpsadc1, + atest_tsens, atest_tsens2, atest_usb1, atest_usb10, + atest_usb11, atest_usb12, atest_usb13, atest_usb2, atest_usb20, + atest_usb21, atest_usb22, atest_usb23, audio_ref, bimc_dte0, + bimc_dte1, blsp_i2c1, blsp_i2c2, blsp_i2c3, blsp_i2c4, + blsp_i2c5, blsp_i2c6, blsp_i2c7, blsp_i2c8_a, blsp_i2c8_b, + blsp_spi1, blsp_spi2, blsp_spi3, blsp_spi3_cs1, blsp_spi3_cs2, + blsp_spi4, blsp_spi5, blsp_spi6, blsp_spi7, blsp_spi8_a, + blsp_spi8_b, blsp_spi8_cs1, blsp_spi8_cs2, blsp_uart1, + blsp_uart2, blsp_uart5, blsp_uart6_a, blsp_uart6_b, blsp_uim1, + blsp_uim2, blsp_uim5, blsp_uim6, cam_mclk, cci_async, cci_i2c, + cri_trng, cri_trng0, cri_trng1, dbg_out, ddr_bist, gcc_gp1, + gcc_gp2, gcc_gp3, gpio, gps_tx_a, gps_tx_b, gps_tx_c, + isense_dbg, jitter_bist, ldo_en, ldo_update, m_voc, mdp_vsync, + mdss_vsync0, mdss_vsync1, mdss_vsync2, mdss_vsync3, mss_lte, + nav_pps_a, nav_pps_b, nav_pps_c, pa_indicator, phase_flag0, + phase_flag1, phase_flag10, phase_flag11, phase_flag12, + phase_flag13, phase_flag14, phase_flag15, phase_flag16, + phase_flag17, phase_flag18, phase_flag19, phase_flag2, + phase_flag20, phase_flag21, phase_flag22, phase_flag23, + phase_flag24, phase_flag25, phase_flag26, phase_flag27, + phase_flag28, phase_flag29, phase_flag3, phase_flag30, + phase_flag31, phase_flag4, phase_flag5, phase_flag6, + phase_flag7, phase_flag8, phase_flag9, pll_bypassnl, pll_reset, + pri_mi2s, pri_mi2s_ws, prng_rosc, pwr_crypto, pwr_modem, + pwr_nav, qdss_cti0_a, qdss_cti0_b, qdss_cti1_a, qdss_cti1_b, + qdss_gpio, qdss_gpio0, qdss_gpio1, qdss_gpio10, qdss_gpio11, + qdss_gpio12, qdss_gpio13, qdss_gpio14, qdss_gpio15, qdss_gpio2, + qdss_gpio3, qdss_gpio4, qdss_gpio5, qdss_gpio6, qdss_gpio7, + qdss_gpio8, qdss_gpio9, qlink_enable, qlink_request, qspi_clk, + qspi_cs, qspi_data0, qspi_data1, qspi_data2, qspi_data3, + qspi_resetn, sec_mi2s, sndwire_clk, sndwire_data, sp_cmu, + ssc_irq, tgu_ch0, tgu_ch1, tsense_pwm1, tsense_pwm2, uim1_clk, + uim1_data, uim1_present, uim1_reset, uim2_clk, uim2_data, + uim2_present, uim2_reset, uim_batt, vfr_1, vsense_clkout, + vsense_data0, vsense_data1, vsense_mode, wlan1_adc0, + wlan1_adc1, wlan2_adc0, wlan2_adc1 ] + + 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@3100000 { + compatible = "qcom,sdm630-pinctrl"; + reg = <0x03100000 0x400000>, + <0x03500000 0x400000>, + <0x03900000 0x400000>; + reg-names = "south", "center", "north"; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + gpio-ranges = <&tlmm 0 0 114>; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + + blsp1-uart1-default-state { + pins = "gpio0", "gpio1", "gpio2", "gpio3"; + function = "gpio"; + drive-strength = <2>; + bias-disable; + }; + + blsp2_uart1_default: blsp2-uart1-active-state { + tx-rts-pins { + pins = "gpio16", "gpio19"; + function = "blsp_uart5"; + drive-strength = <2>; + bias-disable; + }; + + rx-pins { + pins = "gpio17"; + function = "blsp_uart5"; + drive-strength = <2>; + bias-pull-up; + }; + + cts-pins { + pins = "gpio18"; + function = "blsp_uart5"; + drive-strength = <2>; + bias-pull-down; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdm660-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,sdm660-pinctrl.txt deleted file mode 100644 index be034d329e10..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sdm660-pinctrl.txt +++ /dev/null @@ -1,191 +0,0 @@ -Qualcomm Technologies, Inc. SDM660 TLMM block - -This binding describes the Top Level Mode Multiplexer block found in the -SDM660 platform. - -- compatible: - Usage: required - Value type: <string> - Definition: must be "qcom,sdm660-pinctrl" or - "qcom,sdm630-pinctrl". - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: the base address and size of the north, center and south - TLMM tiles. - -- reg-names: - Usage: required - Value type: <stringlist> - Definition: names for the cells of reg, must contain "north", "center" - and "south". - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: should specify the TLMM summary IRQ. - -- interrupt-controller: - Usage: required - Value type: <none> - Definition: identifies this node as an interrupt controller - -- #interrupt-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/interrupt-controller/irq.h> - -- gpio-controller: - Usage: required - Value type: <none> - Definition: identifies this node as a gpio controller - -- gpio-ranges: - Usage: required - Value type: <prop-encoded-array> - Definition: Specifies the mapping between gpio controller and - pin-controller pins. - -- #gpio-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/gpio/gpio.h> - -Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for -a general description of GPIO and interrupt bindings. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -The pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - - -PIN CONFIGURATION NODES: - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. - - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pin configuration subnode: - -- pins: - Usage: required - Value type: <string-array> - Definition: List of gpio pins affected by the properties specified in - this subnode. Valid pins are: - gpio0-gpio113, - Supports mux, bias and drive-strength - sdc1_clk, sdc1_cmd, sdc1_data sdc2_clk, sdc2_cmd, sdc2_data sdc1_rclk, - Supports bias and drive-strength - -- function: - Usage: required - Value type: <string> - Definition: Specify the alternative function to be configured for the - specified pins. Functions are only valid for gpio pins. - Valid values are: - adsp_ext, agera_pll, atest_char, atest_char0, atest_char1, - atest_char2, atest_char3, atest_gpsadc0, atest_gpsadc1, - atest_tsens, atest_tsens2, atest_usb1, atest_usb10, - atest_usb11, atest_usb12, atest_usb13, atest_usb2, - atest_usb20, atest_usb21, atest_usb22, atest_usb23, - audio_ref, bimc_dte0, bimc_dte1, blsp_i2c1, blsp_i2c2, - blsp_i2c3, blsp_i2c4, blsp_i2c5, blsp_i2c6, blsp_i2c7, - blsp_i2c8_a, blsp_i2c8_b, blsp_spi1, blsp_spi2, blsp_spi3, - blsp_spi3_cs1, blsp_spi3_cs2, blsp_spi4, blsp_spi5, - blsp_spi6, blsp_spi7, blsp_spi8_a, blsp_spi8_b, - blsp_spi8_cs1, blsp_spi8_cs2, blsp_uart1, blsp_uart2, - blsp_uart5, blsp_uart6_a, blsp_uart6_b, blsp_uim1, - blsp_uim2, blsp_uim5, blsp_uim6, cam_mclk, cci_async, - cci_i2c, cri_trng, cri_trng0, cri_trng1, dbg_out, ddr_bist, - gcc_gp1, gcc_gp2, gcc_gp3, gpio, gps_tx_a, gps_tx_b, gps_tx_c, - isense_dbg, jitter_bist, ldo_en, ldo_update, m_voc, mdp_vsync, - mdss_vsync0, mdss_vsync1, mdss_vsync2, mdss_vsync3, mss_lte, - nav_pps_a, nav_pps_b, nav_pps_c, pa_indicator, phase_flag0, - phase_flag1, phase_flag10, phase_flag11, phase_flag12, - phase_flag13, phase_flag14, phase_flag15, phase_flag16, - phase_flag17, phase_flag18, phase_flag19, phase_flag2, - phase_flag20, phase_flag21, phase_flag22, phase_flag23, - phase_flag24, phase_flag25, phase_flag26, phase_flag27, - phase_flag28, phase_flag29, phase_flag3, phase_flag30, - phase_flag31, phase_flag4, phase_flag5, phase_flag6, - phase_flag7, phase_flag8, phase_flag9, pll_bypassnl, - pll_reset, pri_mi2s, pri_mi2s_ws, prng_rosc, pwr_crypto, - pwr_modem, pwr_nav, qdss_cti0_a, qdss_cti0_b, qdss_cti1_a, - qdss_cti1_b, qdss_gpio, qdss_gpio0, qdss_gpio1, qdss_gpio10, - qdss_gpio11, qdss_gpio12, qdss_gpio13, qdss_gpio14, qdss_gpio15, - qdss_gpio2, qdss_gpio3, qdss_gpio4, qdss_gpio5, qdss_gpio6, - qdss_gpio7, qdss_gpio8, qdss_gpio9, qlink_enable, qlink_request, - qspi_clk, qspi_cs, qspi_data0, qspi_data1, qspi_data2, - qspi_data3, qspi_resetn, sec_mi2s, sndwire_clk, sndwire_data, - sp_cmu, ssc_irq, tgu_ch0, tgu_ch1, tsense_pwm1, tsense_pwm2, - uim1_clk, uim1_data, uim1_present, uim1_reset, uim2_clk, - uim2_data, uim2_present, uim2_reset, uim_batt, vfr_1, - vsense_clkout, vsense_data0, vsense_data1, vsense_mode, - wlan1_adc0, wlan1_adc1, wlan2_adc0, wlan2_adc1 - -- bias-disable: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as no pull. - -- bias-pull-down: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull down. - -- bias-pull-up: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull up. - -- output-high: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - high. - Not valid for sdc pins. - -- output-low: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - low. - Not valid for sdc pins. - -- drive-strength: - Usage: optional - Value type: <u32> - Definition: Selects the drive strength for the specified pins, in mA. - Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16 - -Example: - - tlmm: pinctrl@3100000 { - compatible = "qcom,sdm660-pinctrl"; - reg = <0x3100000 0x200000>, - <0x3500000 0x200000>, - <0x3900000 0x200000>; - reg-names = "south", "center", "north"; - interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - gpio-ranges = <&tlmm 0 0 114>; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdm670-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sdm670-tlmm.yaml new file mode 100644 index 000000000000..7585117c0f06 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sdm670-tlmm.yaml @@ -0,0 +1,127 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,sdm670-tlmm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. SDM670 TLMM block + +maintainers: + - Richard Acayan <mailingradian@gmail.com> + +description: | + The Top Level Mode Multiplexer (TLMM) block found in the SDM670 platform. + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +properties: + compatible: + const: qcom,sdm670-tlmm + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + gpio-reserved-ranges: + minItems: 1 + maxItems: 75 + + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + +required: + - compatible + - reg + +additionalProperties: false + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-sdm670-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sdm670-tlmm-state" + additionalProperties: false + +$defs: + qcom-sdm670-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])$" + - enum: [ ufs_reset, sdc1_rclk, sdc1_clk, sdc1_cmd, sdc1_data, + sdc2_clk, sdc2_cmd, sdc2_data ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ adsp_ext, agera_pll, atest_char, atest_tsens, atest_tsens2, atest_usb1, atest_usb10, + atest_usb11, atest_usb12, atest_usb13, atest_usb2, atest_usb20, atest_usb21, + atest_usb22, atest_usb23, cam_mclk, cci_async, cci_i2c, cci_timer0, cci_timer1, + cci_timer2, cci_timer3, cci_timer4, copy_gp, copy_phase, dbg_out, ddr_bist, + ddr_pxi0, ddr_pxi1, ddr_pxi2, ddr_pxi3, edp_hot, edp_lcd, gcc_gp1, gcc_gp2, gcc_gp3, + gp_pdm0, gp_pdm1, gp_pdm2, gpio, gps_tx, jitter_bist, ldo_en, ldo_update, + lpass_slimbus, m_voc, mdp_vsync, mdp_vsync0, mdp_vsync1, mdp_vsync2, mdp_vsync3, + mss_lte, nav_pps, pa_indicator, pci_e0, pci_e1, phase_flag, pll_bist, pll_bypassnl, + pll_reset, pri_mi2s, pri_mi2s_ws, prng_rosc, qdss_cti, qdss, qlink_enable, + qlink_request, qua_mi2s, qup0, qup1, qup10, qup11, qup12, qup13, qup14, qup15, qup2, + qup3, qup4, qup5, qup6, qup7, qup8, qup9, qup_l4, qup_l5, qup_l6, sdc4_clk, + sdc4_cmd, sdc4_data, sd_write, sec_mi2s, ter_mi2s, tgu_ch0, tgu_ch1, tgu_ch2, + tgu_ch3, tsif1_clk, tsif1_data, tsif1_en, tsif1_error, tsif1_sync, tsif2_clk, + tsif2_data, tsif2_en, tsif2_error, tsif2_sync, uim1_clk, uim1_data, uim1_present, + uim1_reset, uim2_clk, uim2_data, uim2_present, uim2_reset, uim_batt, usb_phy, vfr_1, + vsense_trigger, wlan1_adc0, wlan1_adc1, wlan2_adc0, wlan2_adc1, wsa_clk, wsa_data, ] + + + 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> + pinctrl@3400000 { + compatible = "qcom,sdm670-tlmm"; + reg = <0x03400000 0x300000>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-ranges = <&tlmm 0 0 151>; + + qup-i2c9-state { + pins = "gpio6", "gpio7"; + function = "qup9"; + }; + }; +... diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.txt deleted file mode 100644 index 7462e3743c68..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.txt +++ /dev/null @@ -1,176 +0,0 @@ -Qualcomm SDM845 TLMM block - -This binding describes the Top Level Mode Multiplexer block found in the -SDM845 platform. - -- compatible: - Usage: required - Value type: <string> - Definition: must be "qcom,sdm845-pinctrl" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: the base address and size of the TLMM register space. - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: should specify the TLMM summary IRQ. - -- interrupt-controller: - Usage: required - Value type: <none> - Definition: identifies this node as an interrupt controller - -- #interrupt-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/interrupt-controller/irq.h> - -- gpio-controller: - Usage: required - Value type: <none> - Definition: identifies this node as a gpio controller - -- #gpio-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/gpio/gpio.h> - -Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for -a general description of GPIO and interrupt bindings. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -The pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - - -PIN CONFIGURATION NODES: - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. - - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pin configuration subnode: - -- pins: - Usage: required - Value type: <string-array> - Definition: List of gpio pins affected by the properties specified in - this subnode. - - Valid pins are: - gpio0-gpio149 - Supports mux, bias and drive-strength - - sdc2_clk, sdc2_cmd, sdc2_data, ufs_reset - Supports bias and drive-strength - -- function: - Usage: required - Value type: <string> - Definition: Specify the alternative function to be configured for the - specified pins. Functions are only valid for gpio pins. - Valid values are: - - gpio, adsp_ext, agera_pll, atest_char, atest_tsens, - atest_tsens2, atest_usb1, atest_usb10, atest_usb11, - atest_usb12, atest_usb13, atest_usb2, atest_usb20, - atest_usb21, atest_usb22, atest_usb23, audio_ref, - btfm_slimbus, cam_mclk, cci_async, cci_i2c, cci_timer0, - cci_timer1, cci_timer2, cci_timer3, cci_timer4, cri_trng, - cri_trng0, cri_trng1, dbg_out, ddr_bist, ddr_pxi0, - ddr_pxi1, ddr_pxi2, ddr_pxi3, edp_hot, edp_lcd, gcc_gp1, - gcc_gp2, gcc_gp3, jitter_bist, ldo_en, ldo_update, - lpass_slimbus, m_voc, mdp_vsync, mdp_vsync0, mdp_vsync1, - mdp_vsync2, mdp_vsync3, mss_lte, nav_pps, pa_indicator, - pci_e0, pci_e1, phase_flag, pll_bist, pll_bypassnl, - pll_reset, pri_mi2s, pri_mi2s_ws, prng_rosc, qdss_cti, - qdss, qlink_enable, qlink_request, qua_mi2s, qup0, qup1, - qup10, qup11, qup12, qup13, qup14, qup15, qup2, qup3, qup4, - qup5, qup6, qup7, qup8, qup9, qup_l4, qup_l5, qup_l6, - qspi_clk, qspi_cs, qspi_data, sd_write, sdc4_clk, sdc4_cmd, - sdc4_data, sec_mi2s, sp_cmu, spkr_i2s, ter_mi2s, tgu_ch0, - tgu_ch1, tgu_ch2, tgu_ch3, tsense_pwm1, tsense_pwm2, - tsif1_clk, tsif1_data, tsif1_en, tsif1_error, tsif1_sync, - tsif2_clk, tsif2_data, tsif2_en, tsif2_error, tsif2_sync, - uim1_clk, uim1_data, uim1_present, uim1_reset, uim2_clk, - uim2_data, uim2_present, uim2_reset, uim_batt, usb_phy, - vfr_1, vsense_trigger, wlan1_adc0, wlan1_adc1, wlan2_adc0, - wlan2_adc1, - -- bias-disable: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as no pull. - -- bias-pull-down: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull down. - -- bias-pull-up: - Usage: optional - Value type: <none> - Definition: The specified pins should be configured as pull up. - -- output-high: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - high. - Not valid for sdc pins. - -- output-low: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - low. - Not valid for sdc pins. - -- drive-strength: - Usage: optional - Value type: <u32> - Definition: Selects the drive strength for the specified pins, in mA. - Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16 - -Example: - - tlmm: pinctrl@3400000 { - compatible = "qcom,sdm845-pinctrl"; - reg = <0x03400000 0xc00000>; - interrupts = <GIC_SPI 208 0>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; - - qup9_active: qup9-active { - mux { - pins = "gpio4", "gpio5"; - function = "qup9"; - }; - - config { - pins = "gpio4", "gpio5"; - drive-strength = <2>; - bias-disable; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.yaml new file mode 100644 index 000000000000..c9627777ceb3 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.yaml @@ -0,0 +1,158 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,sdm845-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SDM845 TLMM pin controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in Qualcomm SDM845 SoC. + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +properties: + compatible: + const: qcom,sdm845-pinctrl + + reg: + maxItems: 1 + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 75 + + gpio-line-names: + maxItems: 150 + + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-sdm845-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sdm845-tlmm-state" + additionalProperties: false + +$defs: + qcom-sdm845-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])$" + - 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: [ adsp_ext, agera_pll, atest_char, atest_tsens, atest_tsens2, + atest_usb1, atest_usb10, atest_usb11, atest_usb12, atest_usb13, + atest_usb2, atest_usb20, atest_usb21, atest_usb22, atest_usb23, + audio_ref, btfm_slimbus, cam_mclk, cci_async, cci_i2c, + cci_timer0, cci_timer1, cci_timer2, cci_timer3, cci_timer4, + cri_trng, cri_trng0, cri_trng1, dbg_out, ddr_bist, ddr_pxi0, + ddr_pxi1, ddr_pxi2, ddr_pxi3, edp_hot, edp_lcd, gcc_gp1, + gcc_gp2, gcc_gp3, gpio, jitter_bist, ldo_en, ldo_update, + lpass_slimbus, mdp_vsync, mdp_vsync0, mdp_vsync1, mdp_vsync2, + mdp_vsync3, mss_lte, m_voc, nav_pps, pa_indicator, pci_e0, + pci_e1, phase_flag, pll_bist, pll_bypassnl, pll_reset, + pri_mi2s, pri_mi2s_ws, prng_rosc, qdss, qdss_cti, qlink_enable, + qlink_request, qspi_clk, qspi_cs, qspi_data, qua_mi2s, qup0, + qup1, qup10, qup11, qup12, qup13, qup14, qup15, qup2, qup3, + qup4, qup5, qup6, qup7, qup8, qup9, qup_l4, qup_l5, qup_l6, + sdc4_clk, sdc4_cmd, sdc4_data, sd_write, sec_mi2s, sp_cmu, + spkr_i2s, ter_mi2s, tgu_ch0, tgu_ch1, tgu_ch2, tgu_ch3, + tsense_pwm1, tsense_pwm2, tsif1_clk, tsif1_data, tsif1_en, + tsif1_error, tsif1_sync, tsif2_clk, tsif2_data, tsif2_en, + tsif2_error, tsif2_sync, uim1_clk, uim1_data, uim1_present, + uim1_reset, uim2_clk, uim2_data, uim2_present, uim2_reset, + uim_batt, usb_phy, vfr_1, vsense_trigger, wlan1_adc0, + wlan1_adc1, wlan2_adc0, wlan2_adc1] + + 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@3400000 { + compatible = "qcom,sdm845-pinctrl"; + reg = <0x03400000 0xc00000>; + 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_intc>; + + cci0-default-state { + pins = "gpio17", "gpio18"; + function = "cci_i2c"; + + bias-pull-up; + drive-strength = <2>; + }; + + cam0-default-state { + rst-pins { + pins = "gpio9"; + function = "gpio"; + + drive-strength = <16>; + bias-disable; + }; + + mclk0-pins { + pins = "gpio13"; + function = "cam_mclk"; + + drive-strength = <16>; + bias-disable; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdx55-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sdx55-pinctrl.yaml index a38090b14aab..a76117e41d93 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sdx55-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sdx55-pinctrl.yaml @@ -9,9 +9,8 @@ title: Qualcomm Technologies, Inc. SDX55 TLMM block maintainers: - Vinod Koul <vkoul@kernel.org> -description: | - This binding describes the Top Level Mode Multiplexer block found in the - SDX55 platform. +description: + Top Level Mode Multiplexer pin controller in Qualcomm SDX55 SoC. properties: compatible: @@ -21,38 +20,32 @@ properties: description: Specifies the base address and size of the TLMM register space maxItems: 1 - interrupts: - description: Specifies the TLMM summary IRQ - maxItems: 1 - + interrupts: true interrupt-controller: true - - '#interrupt-cells': - description: Specifies the PIN numbers and Flags, as defined in - include/dt-bindings/interrupt-controller/irq.h - const: 2 - + "#interrupt-cells": true 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 + "#gpio-cells": true + gpio-ranges: true gpio-reserved-ranges: maxItems: 1 -#PIN CONFIGURATION NODES patternProperties: - '-pins$': + "-state$": + oneOf: + - $ref: "#/$defs/qcom-sdx55-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sdx55-tlmm-state" + additionalProperties: false + +$defs: + qcom-sdx55-tlmm-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" + $ref: qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state properties: pins: @@ -96,62 +89,46 @@ patternProperties: uim1_present, uim1_reset, uim2_clk, uim2_data, uim2_present, uim2_reset, usb2phy_ac, vsense_trigger ] - drive-strength: - enum: [2, 4, 6, 8, 10, 12, 14, 16] - default: 2 - description: - Selects the drive strength for the specified pins, in mA. - bias-pull-down: true - bias-pull-up: true - bias-disable: true - + drive-strength: true output-high: true - output-low: true required: - pins - - function additionalProperties: false allOf: - - $ref: "pinctrl.yaml#" + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# required: - compatible - reg - - interrupts - - interrupt-controller - - '#interrupt-cells' - - gpio-controller - - '#gpio-cells' - - gpio-ranges additionalProperties: false examples: - | - #include <dt-bindings/interrupt-controller/arm-gic.h> - tlmm: pinctrl@1f00000 { - compatible = "qcom,sdx55-pinctrl"; - reg = <0x0f100000 0x300000>; - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&tlmm 0 0 108>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = <GIC_SPI 212 IRQ_TYPE_LEVEL_HIGH>; - - serial-pins { - pins = "gpio8", "gpio9"; - function = "blsp_uart3"; - drive-strength = <8>; - bias-disable; - }; + #include <dt-bindings/interrupt-controller/arm-gic.h> + tlmm: pinctrl@1f00000 { + compatible = "qcom,sdx55-pinctrl"; + reg = <0x0f100000 0x300000>; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&tlmm 0 0 108>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 212 IRQ_TYPE_LEVEL_HIGH>; + + serial-state { + pins = "gpio8", "gpio9"; + function = "blsp_uart3"; + drive-strength = <8>; + bias-disable; }; + }; ... diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdx65-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sdx65-tlmm.yaml index cdfcf29dffee..2f53905260e6 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sdx65-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sdx65-tlmm.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/pinctrl/qcom,sdx65-pinctrl.yaml# +$id: http://devicetree.org/schemas/pinctrl/qcom,sdx65-tlmm.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. SDX65 TLMM block @@ -10,8 +10,7 @@ maintainers: - Vamsi krishna Lanka <quic_vamslank@quicinc.com> description: - This binding describes the Top Level Mode Multiplexer block found in the - SDX65 platform. + Top Level Mode Multiplexer pin controller in Qualcomm SDX65 SoC. properties: compatible: @@ -20,44 +19,32 @@ properties: reg: maxItems: 1 - interrupts: - maxItems: 1 - + interrupts: true interrupt-controller: true - - '#interrupt-cells': - description: Specifies the PIN numbers and Flags, as defined in - include/dt-bindings/interrupt-controller/irq.h - const: 2 - + "#interrupt-cells": true 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 + "#gpio-cells": true + gpio-ranges: true gpio-reserved-ranges: maxItems: 1 -#PIN CONFIGURATION NODES patternProperties: - '-state$': + "-state$": oneOf: - $ref: "#/$defs/qcom-sdx65-tlmm-state" - patternProperties: - ".*": + "-pins$": $ref: "#/$defs/qcom-sdx65-tlmm-state" -'$defs': + additionalProperties: false + +$defs: qcom-sdx65-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" + $ref: qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state properties: pins: @@ -122,37 +109,24 @@ patternProperties: qspi_cs, ssbi2, ssbi1, mss_lte, qspi_clk, qspi0, qspi1, qspi2, qspi3, gpio ] - drive-strength: - enum: [2, 4, 6, 8, 10, 12, 14, 16] - default: 2 - description: - Selects the drive strength for the specified pins, in mA. - bias-pull-down: true - bias-pull-up: true - bias-disable: true - + drive-strength: true output-high: true - output-low: true required: - pins - - function additionalProperties: false +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + required: - compatible - reg - - interrupts - - interrupt-controller - - '#interrupt-cells' - - gpio-controller - - '#gpio-cells' - - gpio-ranges additionalProperties: false @@ -175,13 +149,13 @@ examples: }; uart-w-subnodes-state { - rx { + rx-pins { pins = "gpio4"; function = "blsp_uart1"; bias-pull-up; }; - tx { + tx-pins { pins = "gpio5"; function = "blsp_uart1"; bias-disable; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-tlmm.yaml index e39fbb36d8c1..164f24db8b2b 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm6115-tlmm.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/pinctrl/qcom,sm6115-pinctrl.yaml# +$id: http://devicetree.org/schemas/pinctrl/qcom,sm6115-tlmm.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. SM6115, SM4250 TLMM block @@ -10,15 +10,14 @@ maintainers: - Iskren Chernev <iskren.chernev@gmail.com> description: - This binding describes the Top Level Mode Multiplexer block found in the - SM4250/6115 platforms. + Top Level Mode Multiplexer pin controller in Qualcomm SM4250 and SM6115 + SoCs. properties: compatible: const: qcom,sm6115-tlmm reg: - minItems: 3 maxItems: 3 reg-names: @@ -27,35 +26,17 @@ properties: - const: south - const: east - interrupts: - description: Specifies the TLMM summary IRQ - maxItems: 1 - + interrupts: true interrupt-controller: true - - '#interrupt-cells': - description: - Specifies the PIN numbers and Flags, as defined in defined in - include/dt-bindings/interrupt-controller/irq.h - const: 2 - + "#interrupt-cells": true 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 - + "#gpio-cells": true + gpio-ranges: true gpio-reserved-ranges: true - wakeup-parent: true -#PIN CONFIGURATION NODES patternProperties: - '-state$': + "-state$": oneOf: - $ref: "#/$defs/qcom-sm6115-tlmm-state" - patternProperties: @@ -63,12 +44,13 @@ patternProperties: $ref: "#/$defs/qcom-sm6115-tlmm-state" additionalProperties: false -'$defs': +$defs: qcom-sm6115-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: @@ -101,50 +83,25 @@ patternProperties: uim2_present, uim2_reset, usb_phy, vfr_1, vsense_trigger, wlan1_adc0, elan1_adc1 ] - drive-strength: - enum: [2, 4, 6, 8, 10, 12, 14, 16] - default: 2 - description: - Selects the drive strength for the specified pins, in mA. - bias-pull-down: true - bias-pull-up: true - bias-disable: true - + drive-strength: true output-high: true - output-low: true required: - pins - allOf: - - $ref: "qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state" - - if: - properties: - pins: - pattern: "^gpio([0-9]|[1-9][0-9]|10[0-9]|11[0-2])$" - then: - required: - - function - additionalProperties: false allOf: - - $ref: "pinctrl.yaml#" + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# required: - compatible - reg - reg-names - - interrupts - - interrupt-controller - - '#interrupt-cells' - - gpio-controller - - '#gpio-cells' - - gpio-ranges additionalProperties: false diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm6125-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm6125-tlmm.yaml index 5cb8b272cb7d..e1dd54a160d5 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm6125-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm6125-tlmm.yaml @@ -1,19 +1,17 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/pinctrl/qcom,sm6125-pinctrl.yaml# +$id: http://devicetree.org/schemas/pinctrl/qcom,sm6125-tlmm.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. SM6125 TLMM block maintainers: - Martin Botka <martin.botka@somainline.org> -description: | - This binding describes the Top Level Mode Multiplexer (TLMM) block found - in the SM6125 platform. +description: + Top Level Mode Multiplexer pin controller in Qualcomm SM6125 SoC. allOf: - - $ref: "pinctrl.yaml#" - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# properties: @@ -21,21 +19,20 @@ properties: const: qcom,sm6125-tlmm reg: - minItems: 3 maxItems: 3 reg-names: items: - - const: "west" - - const: "south" - - const: "east" + - const: west + - const: south + - const: east interrupts: true interrupt-controller: true - '#interrupt-cells': true + "#interrupt-cells": true gpio-controller: true gpio-reserved-ranges: true - '#gpio-cells': true + "#gpio-cells": true gpio-ranges: true wakeup-parent: true @@ -47,7 +44,7 @@ required: additionalProperties: false patternProperties: - '-state$': + "-state$": oneOf: - $ref: "#/$defs/qcom-sm6125-tlmm-state" - patternProperties: @@ -61,6 +58,7 @@ $defs: 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: @@ -112,16 +110,6 @@ $defs: required: - pins - allOf: - - $ref: "qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state" - - if: - properties: - pins: - pattern: "^gpio[0-9]|[1-9][0-9]|1[0-2][0-9]|13[0-2]$" - then: - required: - - function - additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm6350-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm6350-tlmm.yaml index 856b9c567ecb..41e3e0afc9a8 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm6350-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm6350-tlmm.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/pinctrl/qcom,sm6350-pinctrl.yaml# +$id: http://devicetree.org/schemas/pinctrl/qcom,sm6350-tlmm.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. SM6350 TLMM block @@ -9,12 +9,10 @@ title: Qualcomm Technologies, Inc. SM6350 TLMM block maintainers: - Konrad Dybcio <konrad.dybcio@somainline.org> -description: | - This binding describes the Top Level Mode Multiplexer (TLMM) block found - in the SM6350 platform. +description: + Top Level Mode Multiplexer pin controller in Qualcomm SM6350 SoC. allOf: - - $ref: "pinctrl.yaml#" - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# properties: @@ -26,10 +24,10 @@ properties: interrupts: true interrupt-controller: true - '#interrupt-cells': true + "#interrupt-cells": true gpio-controller: true gpio-reserved-ranges: true - '#gpio-cells': true + "#gpio-cells": true gpio-ranges: true wakeup-parent: true @@ -40,7 +38,7 @@ required: additionalProperties: false patternProperties: - '-state$': + "-state$": oneOf: - $ref: "#/$defs/qcom-sm6350-tlmm-state" - patternProperties: @@ -54,6 +52,7 @@ $defs: 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: @@ -111,16 +110,6 @@ $defs: required: - pins - allOf: - - $ref: "qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state" - - if: - properties: - pins: - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-4][0-9]|15[0-7])$" - then: - required: - - function - additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm6375-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm6375-tlmm.yaml index 025faf87d147..d54ebb2bd5a8 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm6375-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm6375-tlmm.yaml @@ -9,12 +9,10 @@ title: Qualcomm Technologies, Inc. SM6375 TLMM block maintainers: - Konrad Dybcio <konrad.dybcio@somainline.org> -description: | - This binding describes the Top Level Mode Multiplexer (TLMM) block found - in the SM6375 platform. +description: + Top Level Mode Multiplexer pin controller in Qualcomm SM6375 SoC. allOf: - - $ref: "pinctrl.yaml#" - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# properties: @@ -26,10 +24,10 @@ properties: interrupts: true interrupt-controller: true - '#interrupt-cells': true + "#interrupt-cells": true gpio-controller: true gpio-reserved-ranges: true - '#gpio-cells': true + "#gpio-cells": true gpio-ranges: true wakeup-parent: true @@ -40,7 +38,7 @@ required: additionalProperties: false patternProperties: - '-state$': + "-state$": oneOf: - $ref: "#/$defs/qcom-sm6375-tlmm-state" - patternProperties: @@ -54,6 +52,7 @@ $defs: 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: @@ -120,16 +119,6 @@ $defs: required: - pins - allOf: - - $ref: "qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state" - - if: - properties: - pins: - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-4][0-9]|15[0-6])$" - then: - required: - - function - additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm8150-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,sm8150-pinctrl.txt deleted file mode 100644 index fa37733e5102..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm8150-pinctrl.txt +++ /dev/null @@ -1,190 +0,0 @@ -Qualcomm SM8150 TLMM block - -This binding describes the Top Level Mode Multiplexer block found in the -QCS404 platform. - -- compatible: - Usage: required - Value type: <string> - Definition: must be "qcom,sm8150-pinctrl" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: the base address and size of the north, south, west - and east TLMM tiles. - -- reg-names: - Usage: required - Value type: <prop-encoded-array> - Defintiion: names for the cells of reg, must contain "north", "south" - "west" and "east". - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: should specify the TLMM summary IRQ. - -- interrupt-controller: - Usage: required - Value type: <none> - Definition: identifies this node as an interrupt controller - -- #interrupt-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/interrupt-controller/irq.h> - -- gpio-controller: - Usage: required - Value type: <none> - Definition: identifies this node as a gpio controller - -- #gpio-cells: - Usage: required - Value type: <u32> - Definition: must be 2. Specifying the pin number and flags, as defined - in <dt-bindings/gpio/gpio.h> - -- gpio-ranges: - Usage: required - Value type: <prop-encoded-array> - Definition: see ../gpio/gpio.txt - -- gpio-reserved-ranges: - Usage: optional - Value type: <prop-encoded-array> - Definition: see ../gpio/gpio.txt - -Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for -a general description of GPIO and interrupt bindings. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -The pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - - -PIN CONFIGURATION NODES: - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. - - -The following generic properties as defined in pinctrl-bindings.txt are valid -to specify in a pin configuration subnode: - -- pins: - Usage: required - Value type: <string-array> - Definition: List of gpio pins affected by the properties specified in - this subnode. - - Valid pins are: - gpio0-gpio149 - Supports mux, bias and drive-strength - - sdc1_clk, sdc1_cmd, sdc1_data sdc2_clk, sdc2_cmd, - sdc2_data sdc1_rclk - Supports bias and drive-strength - - ufs_reset - Supports bias and drive-strength - -- function: - Usage: required - Value type: <string> - Definition: Specify the alternative function to be configured for the - specified pins. Functions are only valid for gpio pins. - Valid values are: - - adsp_ext, agera_pll, aoss_cti, ddr_pxi2, atest_char, - atest_char0, atest_char1, atest_char2, atest_char3, - audio_ref, atest_usb1, atest_usb2, atest_usb10, - atest_usb11, atest_usb12, atest_usb13, atest_usb20, - atest_usb21, atest_usb22, atest_usb2, atest_usb23, - btfm_slimbus, cam_mclk, cci_async, cci_i2c, cci_timer0, - cci_timer1, cci_timer2, cci_timer3, cci_timer4, - cri_trng, cri_trng0, cri_trng1, dbg_out, ddr_bist, - ddr_pxi0, ddr_pxi1, ddr_pxi3, edp_hot, edp_lcd, - emac_phy, emac_pps, gcc_gp1, gcc_gp2, gcc_gp3, gpio, - hs1_mi2s, hs2_mi2s, hs3_mi2s, jitter_bist, - lpass_slimbus, mdp_vsync, mdp_vsync0, mdp_vsync1, - mdp_vsync2, mdp_vsync3, mss_lte, m_voc, nav_pps, - pa_indicator, pci_e0, phase_flag, pll_bypassnl, - pll_bist, pci_e1, pll_reset, pri_mi2s, pri_mi2s_ws, - prng_rosc, qdss, qdss_cti, qlink_request, qlink_enable, - qspi0, qspi1, qspi2, qspi3, qspi_clk, qspi_cs, qua_mi2s, - qup0, qup1, qup2, qup3, qup4, qup5, qup6, qup7, qup8, - qup9, qup10, qup11, qup12, qup13, qup14, qup15, qup16, - qup17, qup18, qup19, qup_l4, qup_l5, qup_l6, rgmii, - sdc4, sd_write, sec_mi2s, spkr_i2s, sp_cmu, ter_mi2s, - tgu_ch0, tgu_ch1, tgu_ch2, tgu_ch3, tsense_pwm1, - tsense_pwm2, tsif1, tsif2, uim1, uim2, uim_batt, - usb2phy_ac, usb_phy, vfr_1, vsense_trigger, wlan1_adc0, - wlan1_adc1, wlan2_adc0, wlan2_adc1, wmss_reset - -- bias-disable: - Usage: optional - Value type: <none> - Definition: The specified pins should be configued as no pull. - -- bias-pull-down: - Usage: optional - Value type: <none> - Definition: The specified pins should be configued as pull down. - -- bias-pull-up: - Usage: optional - Value type: <none> - Definition: The specified pins should be configued as pull up. - -- output-high: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - high. - Not valid for sdc pins. - -- output-low: - Usage: optional - Value type: <none> - Definition: The specified pins are configured in output mode, driven - low. - Not valid for sdc pins. - -- drive-strength: - Usage: optional - Value type: <u32> - Definition: Selects the drive strength for the specified pins, in mA. - Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16 - -Example: - - tlmm: pinctrl@3000000 { - compatible = "qcom,sm8150-pinctrl"; - reg = <0x03100000 0x300000>, - <0x03500000 0x300000>, - <0x03900000 0x300000>, - <0x03D00000 0x300000>; - reg-names = "west", "east", "north", "south"; - interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - #gpio-cells = <2>; - gpio-ranges = <&tlmm 0 0 175>; - gpio-reserved-ranges = <0 4>, <126 4>; - interrupt-controller; - #interrupt-cells = <2>; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm8150-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm8150-pinctrl.yaml new file mode 100644 index 000000000000..85adddbdee56 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8150-pinctrl.yaml @@ -0,0 +1,173 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/qcom,sm8150-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM8150 TLMM pin controller + +maintainers: + - Bjorn Andersson <andersson@kernel.org> + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: + Top Level Mode Multiplexer pin controller in Qualcomm SM8150 SoC. + +properties: + compatible: + const: qcom,sm8150-pinctrl + + reg: + maxItems: 4 + + reg-names: + items: + - const: west + - const: east + - const: north + - const: south + + interrupts: true + interrupt-controller: true + "#interrupt-cells": true + gpio-controller: true + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: true + + gpio-reserved-ranges: + minItems: 1 + maxItems: 88 + + gpio-line-names: + maxItems: 175 + +patternProperties: + "-state$": + oneOf: + - $ref: "#/$defs/qcom-sm8150-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sm8150-tlmm-state" + additionalProperties: false + +$defs: + qcom-sm8150-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-6][0-9]|17[0-4])$" + - enum: [ sdc2_clk, sdc2_cmd, sdc2_data, ufs_reset ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ adsp_ext, agera_pll, aoss_cti, ddr_pxi2, atest_char, + atest_char0, atest_char1, atest_char2, atest_char3, audio_ref, + atest_usb1, atest_usb2, atest_usb10, atest_usb11, atest_usb12, + atest_usb13, atest_usb20, atest_usb21, atest_usb22, atest_usb2, + atest_usb23, btfm_slimbus, cam_mclk, cci_async, cci_i2c, + cci_timer0, cci_timer1, cci_timer2, cci_timer3, cci_timer4, + cri_trng, cri_trng0, cri_trng1, dbg_out, ddr_bist, ddr_pxi0, + ddr_pxi1, ddr_pxi3, edp_hot, edp_lcd, emac_phy, emac_pps, + gcc_gp1, gcc_gp2, gcc_gp3, gpio, hs1_mi2s, hs2_mi2s, hs3_mi2s, + jitter_bist, lpass_slimbus, mdp_vsync, mdp_vsync0, mdp_vsync1, + mdp_vsync2, mdp_vsync3, mss_lte, m_voc, nav_pps, pa_indicator, + pci_e0, phase_flag, pll_bypassnl, pll_bist, pci_e1, pll_reset, + pri_mi2s, pri_mi2s_ws, prng_rosc, qdss, qdss_cti, + qlink_request, qlink_enable, qspi0, qspi1, qspi2, qspi3, + qspi_clk, qspi_cs, qua_mi2s, qup0, qup1, qup2, qup3, qup4, + qup5, qup6, qup7, qup8, qup9, qup10, qup11, qup12, qup13, + qup14, qup15, qup16, qup17, qup18, qup19, qup_l4, qup_l5, + qup_l6, rgmii, sdc4, sd_write, sec_mi2s, spkr_i2s, sp_cmu, + ter_mi2s, tgu_ch0, tgu_ch1, tgu_ch2, tgu_ch3, tsense_pwm1, + tsense_pwm2, tsif1, tsif2, uim1, uim2, uim_batt, usb2phy_ac, + usb_phy, vfr_1, vsense_trigger, wlan1_adc0, wlan1_adc1, + wlan2_adc0, wlan2_adc1, wmss_reset ] + + 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 + +allOf: + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# + +required: + - compatible + - reg + - reg-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + tlmm: pinctrl@3100000 { + compatible = "qcom,sm8150-pinctrl"; + reg = <0x03100000 0x300000>, + <0x03500000 0x300000>, + <0x03900000 0x300000>, + <0x03d00000 0x300000>; + reg-names = "west", "east", "north", "south"; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-ranges = <&tlmm 0 0 176>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + wakeup-parent = <&pdc>; + + qup-spi0-default-state { + pins = "gpio0", "gpio1", "gpio2", "gpio3"; + function = "qup0"; + drive-strength = <6>; + bias-disable; + }; + + pcie1-default-state { + perst-pins { + pins = "gpio102"; + function = "gpio"; + drive-strength = <2>; + bias-pull-down; + }; + + clkreq-pins { + pins = "gpio103"; + function = "pci_e1"; + drive-strength = <2>; + bias-pull-up; + }; + + wake-pins { + pins = "gpio104"; + function = "gpio"; + drive-strength = <2>; + bias-pull-up; + }; + }; + }; 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 06efb1382876..bd45faa3f078 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-lpass-lpi-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-lpass-lpi-pinctrl.yaml @@ -4,22 +4,20 @@ $id: http://devicetree.org/schemas/pinctrl/qcom,sm8250-lpass-lpi-pinctrl.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Technologies, Inc. Low Power Audio SubSystem (LPASS) - Low Power Island (LPI) TLMM block +title: Qualcomm SM8250 SoC LPASS LPI TLMM maintainers: - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> -description: | - This binding describes the Top Level Mode Multiplexer block found in the - LPASS LPI IP on most Qualcomm SoCs +description: + Top Level Mode Multiplexer pin controller in the Low Power Audio SubSystem + (LPASS) Low Power Island (LPI) of Qualcomm SM8250 SoC. properties: compatible: const: qcom,sm8250-lpass-lpi-pinctrl reg: - minItems: 2 maxItems: 2 clocks: @@ -34,7 +32,7 @@ properties: gpio-controller: true - '#gpio-cells': + "#gpio-cells": description: Specifying the pin number and flags, as defined in include/dt-bindings/gpio/gpio.h const: 2 @@ -42,9 +40,17 @@ properties: gpio-ranges: maxItems: 1 -#PIN CONFIGURATION NODES patternProperties: - '-pins$': + "-state$": + oneOf: + - $ref: "#/$defs/qcom-sm8250-lpass-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sm8250-lpass-state" + additionalProperties: false + +$defs: + qcom-sm8250-lpass-state: type: object description: Pinctrl node's client devices use subnodes for desired pin configuration. @@ -88,13 +94,11 @@ patternProperties: 3: Reserved (No adjustments) bias-pull-down: true - bias-pull-up: true - + bias-bus-hold: true bias-disable: true - + input-enable: true output-high: true - output-low: true required: @@ -104,7 +108,7 @@ patternProperties: additionalProperties: false allOf: - - $ref: "pinctrl.yaml#" + - $ref: pinctrl.yaml# required: - compatible @@ -112,7 +116,7 @@ required: - clocks - clock-names - gpio-controller - - '#gpio-cells' + - "#gpio-cells" - gpio-ranges additionalProperties: false @@ -130,4 +134,28 @@ examples: gpio-controller; #gpio-cells = <2>; gpio-ranges = <&lpi_tlmm 0 0 14>; + + wsa-swr-active-state { + clk-pins { + pins = "gpio10"; + function = "wsa_swr_clk"; + drive-strength = <2>; + slew-rate = <1>; + bias-disable; + }; + + data-pins { + pins = "gpio11"; + function = "wsa_swr_data"; + drive-strength = <2>; + slew-rate = <1>; + }; + }; + + 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,sm8250-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-pinctrl.yaml index c44d02d28bc9..c80f3847ac08 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8250-pinctrl.yaml @@ -9,133 +9,109 @@ title: Qualcomm Technologies, Inc. SM8250 TLMM block maintainers: - Bjorn Andersson <bjorn.andersson@linaro.org> -description: | - This binding describes the Top Level Mode Multiplexer block found in the - SM8250 platform. +description: + Top Level Mode Multiplexer pin controller in the Qualcomm SM8250 SoC. properties: compatible: const: qcom,sm8250-pinctrl reg: - minItems: 3 maxItems: 3 reg-names: items: - - const: "west" - - const: "south" - - const: "north" - - interrupts: - description: Specifies the TLMM summary IRQ - maxItems: 1 + - const: west + - const: south + - const: north + interrupts: true interrupt-controller: true - - '#interrupt-cells': - description: - Specifies the PIN numbers and Flags, as defined in defined in - include/dt-bindings/interrupt-controller/irq.h - const: 2 - + "#interrupt-cells": true gpio-controller: true + "#gpio-cells": true + gpio-ranges: true + wakeup-parent: 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 + gpio-reserved-ranges: + minItems: 1 + maxItems: 90 - wakeup-parent: true + gpio-line-names: + maxItems: 180 -#PIN CONFIGURATION NODES patternProperties: - '^.*$': - if: - type: object - then: - 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-7][0-9])$" - - enum: [ sdc2_clk, sdc2_cmd, sdc2_data, ufs_reset ] - minItems: 1 - maxItems: 36 - - function: - description: - Specify the alternative function to be configured for the specified - pins. - - enum: [ aoss_cti, atest, audio_ref, cam_mclk, cci_async, cci_i2c, - cci_timer0, cci_timer1, cci_timer2, cci_timer3, cci_timer4, cri_trng, - cri_trng0, cri_trng1, dbg_out, ddr_bist, ddr_pxi0, ddr_pxi1, - ddr_pxi2, ddr_pxi3, dp_hot, dp_lcd, gcc_gp1, gcc_gp2, gcc_gp3, gpio, - ibi_i3c, jitter_bist, lpass_slimbus, mdp_vsync, mdp_vsync0, - mdp_vsync1, mdp_vsync2, mdp_vsync3, mi2s0_data0, mi2s0_data1, - mi2s0_sck, mi2s0_ws, mi2s1_data0, mi2s1_data1, mi2s1_sck, mi2s1_ws, - mi2s2_data0, mi2s2_data1, mi2s2_sck, mi2s2_ws, pci_e0, pci_e1, - pci_e2, phase_flag, pll_bist, pll_bypassnl, pll_clk, pll_reset, - pri_mi2s, prng_rosc, qdss_cti, qdss_gpio, qspi0, qspi1, qspi2, qspi3, - qspi_clk, qspi_cs, qup0, qup1, qup10, qup11, qup12, qup13, qup14, - qup15, qup16, qup17, qup18, qup19, qup2, qup3, qup4, qup5, qup6, - qup7, qup8, qup9, qup_l4, qup_l5, qup_l6, sd_write, sdc40, sdc41, - sdc42, sdc43, sdc4_clk, sdc4_cmd, sec_mi2s, sp_cmu, tgu_ch0, tgu_ch1, - tgu_ch2, tgu_ch3, tsense_pwm1, tsense_pwm2, tsif0_clk, tsif0_data, - tsif0_en, tsif0_error, tsif0_sync, tsif1_clk, tsif1_data, tsif1_en, - tsif1_error, tsif1_sync, usb2phy_ac, usb_phy, vsense_trigger ] - - drive-strength: - enum: [2, 4, 6, 8, 10, 12, 14, 16] - default: 2 - description: - Selects the drive strength for the specified pins, in mA. - - bias-pull-down: true - - bias-pull-up: true - - bias-disable: true - - output-high: true - - output-low: true - - required: - - pins - - allOf: - - $ref: "qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state" - - if: - properties: - pins: - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-7][0-9])$" - then: - required: - - function - - additionalProperties: false + "-state$": + oneOf: + - $ref: "#/$defs/qcom-sm8250-tlmm-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sm8250-tlmm-state" + additionalProperties: false + +$defs: + qcom-sm8250-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-7][0-9])$" + - enum: [ sdc2_clk, sdc2_cmd, sdc2_data, ufs_reset ] + minItems: 1 + maxItems: 36 + + function: + description: + Specify the alternative function to be configured for the specified + pins. + + enum: [ aoss_cti, atest, audio_ref, cam_mclk, cci_async, cci_i2c, + cci_timer0, cci_timer1, cci_timer2, cci_timer3, cci_timer4, cri_trng, + cri_trng0, cri_trng1, dbg_out, ddr_bist, ddr_pxi0, ddr_pxi1, + ddr_pxi2, ddr_pxi3, dp_hot, dp_lcd, gcc_gp1, gcc_gp2, gcc_gp3, gpio, + ibi_i3c, jitter_bist, lpass_slimbus, mdp_vsync, mdp_vsync0, + mdp_vsync1, mdp_vsync2, mdp_vsync3, mi2s0_data0, mi2s0_data1, + mi2s0_sck, mi2s0_ws, mi2s1_data0, mi2s1_data1, mi2s1_sck, mi2s1_ws, + mi2s2_data0, mi2s2_data1, mi2s2_sck, mi2s2_ws, pci_e0, pci_e1, + pci_e2, phase_flag, pll_bist, pll_bypassnl, pll_clk, pll_reset, + pri_mi2s, prng_rosc, qdss_cti, qdss_gpio, qspi0, qspi1, qspi2, qspi3, + qspi_clk, qspi_cs, qup0, qup1, qup10, qup11, qup12, qup13, qup14, + qup15, qup16, qup17, qup18, qup19, qup2, qup3, qup4, qup5, qup6, + qup7, qup8, qup9, qup_l4, qup_l5, qup_l6, sd_write, sdc40, sdc41, + sdc42, sdc43, sdc4_clk, sdc4_cmd, sec_mi2s, sp_cmu, tgu_ch0, tgu_ch1, + tgu_ch2, tgu_ch3, tsense_pwm1, tsense_pwm2, tsif0_clk, tsif0_data, + tsif0_en, tsif0_error, tsif0_sync, tsif1_clk, tsif1_data, tsif1_en, + tsif1_error, tsif1_sync, usb2phy_ac, usb_phy, vsense_trigger ] + + 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 allOf: - - $ref: "pinctrl.yaml#" + - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# required: - compatible - reg - reg-names - - interrupts - - interrupt-controller - - '#interrupt-cells' - - gpio-controller - - '#gpio-cells' - - gpio-ranges additionalProperties: false @@ -143,16 +119,16 @@ examples: - | #include <dt-bindings/interrupt-controller/arm-gic.h> pinctrl@1f00000 { - compatible = "qcom,sm8250-pinctrl"; - reg = <0x0f100000 0x300000>, - <0x0f500000 0x300000>, - <0x0f900000 0x300000>; - reg-names = "west", "south", "north"; - interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; - gpio-ranges = <&tlmm 0 0 180>; - wakeup-parent = <&pdc>; + compatible = "qcom,sm8250-pinctrl"; + reg = <0x0f100000 0x300000>, + <0x0f500000 0x300000>, + <0x0f900000 0x300000>; + reg-names = "west", "south", "north"; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-ranges = <&tlmm 0 0 180>; + wakeup-parent = <&pdc>; }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm8350-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm8350-tlmm.yaml index 6ae5571f60da..0b1e4aa5819e 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm8350-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8350-tlmm.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/pinctrl/qcom,sm8350-pinctrl.yaml# +$id: http://devicetree.org/schemas/pinctrl/qcom,sm8350-tlmm.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. SM8350 TLMM block @@ -9,12 +9,10 @@ title: Qualcomm Technologies, Inc. SM8350 TLMM block maintainers: - Vinod Koul <vkoul@kernel.org> -description: | - This binding describes the Top Level Mode Multiplexer (TLMM) block found - in the SM8350 platform. +description: + Top Level Mode Multiplexer pin controller in Qualcomm SM8350 SoC. allOf: - - $ref: "pinctrl.yaml#" - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# properties: @@ -26,10 +24,10 @@ properties: interrupts: true interrupt-controller: true - '#interrupt-cells': true + "#interrupt-cells": true gpio-controller: true gpio-reserved-ranges: true - '#gpio-cells': true + "#gpio-cells": true gpio-ranges: true wakeup-parent: true @@ -40,7 +38,7 @@ required: additionalProperties: false patternProperties: - '-state$': + "-state$": oneOf: - $ref: "#/$defs/qcom-sm8350-tlmm-state" - patternProperties: @@ -54,6 +52,7 @@ $defs: 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: @@ -108,16 +107,6 @@ $defs: required: - pins - allOf: - - $ref: "qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state" - - if: - properties: - pins: - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-9][0-9]|20[0-3])$" - then: - required: - - function - additionalProperties: false examples: 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 3694795ec793..01a0a4a40ba5 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm8450-lpass-lpi-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8450-lpass-lpi-pinctrl.yaml @@ -4,15 +4,14 @@ $id: http://devicetree.org/schemas/pinctrl/qcom,sm8450-lpass-lpi-pinctrl.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Technologies, Inc. Low Power Audio SubSystem (LPASS) - Low Power Island (LPI) TLMM block +title: Qualcomm SM8450 SoC LPASS LPI TLMM maintainers: - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> -description: | - This binding describes the Top Level Mode Multiplexer block found in the - LPASS LPI IP on most Qualcomm SoCs +description: + Top Level Mode Multiplexer pin controller in the Low Power Audio SubSystem + (LPASS) Low Power Island (LPI) of Qualcomm SM8450 SoC. properties: compatible: @@ -35,7 +34,7 @@ properties: gpio-controller: true - '#gpio-cells': + "#gpio-cells": description: Specifying the pin number and flags, as defined in include/dt-bindings/gpio/gpio.h const: 2 @@ -43,9 +42,17 @@ properties: gpio-ranges: maxItems: 1 -#PIN CONFIGURATION NODES patternProperties: - '-pins$': + "-state$": + oneOf: + - $ref: "#/$defs/qcom-sm8450-lpass-state" + - patternProperties: + "-pins$": + $ref: "#/$defs/qcom-sm8450-lpass-state" + additionalProperties: false + +$defs: + qcom-sm8450-lpass-state: type: object description: Pinctrl node's client devices use subnodes for desired pin configuration. @@ -58,7 +65,7 @@ patternProperties: 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-2][0-9])$" function: enum: [ swr_tx_clk, swr_tx_data, swr_rx_clk, swr_rx_data, @@ -114,7 +121,7 @@ required: - clocks - clock-names - gpio-controller - - '#gpio-cells' + - "#gpio-cells" - gpio-ranges additionalProperties: false @@ -132,4 +139,28 @@ examples: gpio-controller; #gpio-cells = <2>; gpio-ranges = <&lpi_tlmm 0 0 23>; + + wsa-swr-active-state { + clk-pins { + pins = "gpio10"; + function = "wsa_swr_clk"; + drive-strength = <2>; + slew-rate = <1>; + bias-disable; + }; + + data-pins { + pins = "gpio11"; + function = "wsa_swr_data"; + drive-strength = <2>; + slew-rate = <1>; + }; + }; + + 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,sm8450-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sm8450-tlmm.yaml index 9cd97a467648..4a1d10d6c5e7 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sm8450-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8450-tlmm.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/pinctrl/qcom,sm8450-pinctrl.yaml# +$id: http://devicetree.org/schemas/pinctrl/qcom,sm8450-tlmm.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. SM8450 TLMM block @@ -9,9 +9,8 @@ title: Qualcomm Technologies, Inc. SM8450 TLMM block maintainers: - Vinod Koul <vkoul@kernel.org> -description: | - This binding describes the Top Level Mode Multiplexer (TLMM) block found - in the SM8450 platform. +description: + Top Level Mode Multiplexer pin controller in Qualcomm SM8450 SoC. allOf: - $ref: /schemas/pinctrl/qcom,tlmm-common.yaml# @@ -25,7 +24,7 @@ properties: interrupts: true interrupt-controller: true - '#interrupt-cells': true + "#interrupt-cells": true gpio-controller: true gpio-reserved-ranges: @@ -35,7 +34,7 @@ properties: gpio-line-names: maxItems: 209 - '#gpio-cells': true + "#gpio-cells": true gpio-ranges: true wakeup-parent: true @@ -46,7 +45,7 @@ required: additionalProperties: false patternProperties: - '-state$': + "-state$": oneOf: - $ref: "#/$defs/qcom-sm8450-tlmm-state" - patternProperties: @@ -60,6 +59,7 @@ $defs: 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: @@ -112,16 +112,6 @@ $defs: required: - pins - allOf: - - $ref: "qcom,tlmm-common.yaml#/$defs/qcom-tlmm-state" - - if: - properties: - pins: - pattern: "^gpio([0-9]|[1-9][0-9]|1[0-9][0-9]|20[0-9])$" - then: - required: - - function - additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,tlmm-common.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,tlmm-common.yaml index c88c8dcb69d9..e1354f0c64f8 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,tlmm-common.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,tlmm-common.yaml @@ -65,10 +65,6 @@ additionalProperties: true $defs: qcom-tlmm-state: - allOf: - - $ref: pincfg-node.yaml# - - $ref: pinmux-node.yaml# - properties: drive-strength: enum: [2, 4, 6, 8, 10, 12, 14, 16] @@ -82,5 +78,21 @@ $defs: output-high: true output-low: true + allOf: + - $ref: pincfg-node.yaml# + - $ref: pinmux-node.yaml# + + - if: + properties: + pins: + items: + pattern: "^gpio" + then: + required: + - function + else: + properties: + function: false + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml index b486f41df65f..d6539723f354 100644 --- a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml @@ -132,7 +132,7 @@ additionalProperties: description: Pin bank index. - minimum: 0 - maximum: 10 + maximum: 13 description: Mux 0 means GPIO and mux 1 to N means the specific device function. diff --git a/Documentation/devicetree/bindings/pinctrl/semtech,sx1501q.yaml b/Documentation/devicetree/bindings/pinctrl/semtech,sx1501q.yaml new file mode 100644 index 000000000000..0719c03d6f4b --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/semtech,sx1501q.yaml @@ -0,0 +1,208 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright 2022 Linaro Ltd. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/semtech,sx1501q.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Semtech SX150x GPIO expander + +maintainers: + - Neil Armstrong <neil.armstrong@linaro.org> + +properties: + compatible: + enum: + - semtech,sx1501q + - semtech,sx1502q + - semtech,sx1503q + - semtech,sx1504q + - semtech,sx1505q + - semtech,sx1506q + - semtech,sx1507q + - semtech,sx1508q + - semtech,sx1509q + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + '#interrupt-cells': + const: 2 + + interrupt-controller: true + + '#gpio-cells': + const: 2 + + gpio-controller: true + + semtech,probe-reset: + description: Will trigger a reset of the GPIO expander on probe + type: boolean + +patternProperties: + '-cfg$': + type: object + properties: + pins: true + + bias-disable: true + bias-pull-up: true + bias-pull-down: true + bias-pull-pin-default: true + drive-push-pull: true + output-low: true + output-high: true + drive-open-drain: true + + required: + - pins + + allOf: + - $ref: "pincfg-node.yaml#" + - $ref: "pinmux-node.yaml#" + - if: + properties: + pins: + contains: + const: oscio + then: + properties: + bias-disable: false + bias-pull-up: false + bias-pull-down: false + bias-pull-pin-default: false + drive-open-drain: false + + additionalProperties: false + +required: + - compatible + - reg + - '#gpio-cells' + - gpio-controller + +allOf: + - $ref: "pinctrl.yaml#" + - if: + not: + properties: + compatible: + contains: + enum: + - semtech,sx1507q + - semtech,sx1508q + - semtech,sx1509q + then: + properties: + semtech,probe-reset: false + - if: + properties: + compatible: + contains: + enum: + - semtech,sx1501q + - semtech,sx1504q + then: + patternProperties: + '-cfg$': + properties: + pins: + items: + pattern: '^gpio[0-3]$' + - if: + properties: + compatible: + contains: + enum: + - semtech,sx1502q + - semtech,sx1505q + then: + patternProperties: + '-cfg$': + properties: + pins: + items: + pattern: '^gpio[0-7]$' + - if: + properties: + compatible: + contains: + enum: + - semtech,sx1503q + - semtech,sx1506q + then: + patternProperties: + '-cfg$': + properties: + pins: + items: + pattern: '^(gpio[0-9]|gpio1[0-5])$' + - if: + properties: + compatible: + contains: + const: semtech,sx1507q + then: + patternProperties: + '-cfg$': + properties: + pins: + items: + pattern: '^(oscio|gpio[0-3])$' + - if: + properties: + compatible: + contains: + const: semtech,sx1508q + then: + patternProperties: + '-cfg$': + properties: + pins: + items: + pattern: '^(oscio|gpio[0-7])$' + - if: + properties: + compatible: + contains: + const: semtech,sx1509q + then: + patternProperties: + '-cfg$': + properties: + pins: + items: + pattern: '^(oscio|gpio[0-9]|gpio1[0-5])$' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c@1000 { + reg = <0x1000 0x80>; + #address-cells = <1>; + #size-cells = <0>; + + pinctrl@20 { + compatible = "semtech,sx1501q"; + reg = <0x20>; + + #gpio-cells = <2>; + #interrupt-cells = <2>; + + interrupts = <16 IRQ_TYPE_EDGE_FALLING>; + + gpio-controller; + interrupt-controller; + + gpio1-cfg { + pins = "gpio1"; + bias-pull-up; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml index 9d59208d83c1..eeb29b4ad4d1 100644 --- a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml @@ -34,7 +34,9 @@ properties: const: 1 ranges: true - pins-are-numbered: true + pins-are-numbered: + $ref: /schemas/types.yaml#/definitions/flag + deprecated: true hwlocks: true interrupts: @@ -206,7 +208,6 @@ required: - '#address-cells' - '#size-cells' - ranges - - pins-are-numbered additionalProperties: false @@ -220,7 +221,6 @@ examples: #size-cells = <1>; compatible = "st,stm32f429-pinctrl"; ranges = <0 0x40020000 0x3000>; - pins-are-numbered; gpioa: gpio@0 { gpio-controller; @@ -238,7 +238,6 @@ examples: #size-cells = <1>; compatible = "st,stm32f429-pinctrl"; ranges = <0 0x50020000 0x3000>; - pins-are-numbered; gpiob: gpio@1000 { gpio-controller; diff --git a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml index 5b4eda919911..633d49884019 100644 --- a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml +++ b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml @@ -28,15 +28,18 @@ properties: - qcom,msm8998-rpmpd - qcom,qcm2290-rpmpd - qcom,qcs404-rpmpd + - qcom,qdu1000-rpmhpd - qcom,sa8540p-rpmhpd - qcom,sdm660-rpmpd - qcom,sc7180-rpmhpd - qcom,sc7280-rpmhpd - qcom,sc8180x-rpmhpd - qcom,sc8280xp-rpmhpd + - qcom,sdm670-rpmhpd - qcom,sdm845-rpmhpd - qcom,sdx55-rpmhpd - qcom,sdx65-rpmhpd + - qcom,sm4250-rpmpd - qcom,sm6115-rpmpd - qcom,sm6125-rpmpd - qcom,sm6350-rpmhpd @@ -45,6 +48,7 @@ properties: - qcom,sm8250-rpmhpd - qcom,sm8350-rpmhpd - qcom,sm8450-rpmhpd + - qcom,sm8550-rpmhpd '#power-domain-cells': const: 1 diff --git a/Documentation/devicetree/bindings/power/renesas,apmu.yaml b/Documentation/devicetree/bindings/power/renesas,apmu.yaml index f2cc89e7f4e4..2b4d802ef4b2 100644 --- a/Documentation/devicetree/bindings/power/renesas,apmu.yaml +++ b/Documentation/devicetree/bindings/power/renesas,apmu.yaml @@ -34,10 +34,8 @@ properties: maxItems: 1 cpus: - $ref: /schemas/types.yaml#/definitions/phandle-array - items: - minItems: 1 - maxItems: 4 + minItems: 1 + maxItems: 4 description: | Array of phandles pointing to CPU cores, which should match the order of CPU cores used by the WUPCR and PSTR registers in the Advanced Power diff --git a/Documentation/devicetree/bindings/power/supply/mt6360_charger.yaml b/Documentation/devicetree/bindings/power/supply/mt6360_charger.yaml index b89b15a5bfa4..4c74cc78729e 100644 --- a/Documentation/devicetree/bindings/power/supply/mt6360_charger.yaml +++ b/Documentation/devicetree/bindings/power/supply/mt6360_charger.yaml @@ -26,6 +26,7 @@ properties: type: object description: OTG boost regulator. $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false required: - compatible @@ -39,7 +40,6 @@ examples: richtek,vinovp-microvolt = <14500000>; otg_vbus_regulator: usb-otg-vbus-regulator { - regulator-compatible = "usb-otg-vbus"; regulator-name = "usb-otg-vbus"; regulator-min-microvolt = <4425000>; regulator-max-microvolt = <5825000>; diff --git a/Documentation/devicetree/bindings/power/wakeup-source.txt b/Documentation/devicetree/bindings/power/wakeup-source.txt index cfd74659fbed..697333a56d5e 100644 --- a/Documentation/devicetree/bindings/power/wakeup-source.txt +++ b/Documentation/devicetree/bindings/power/wakeup-source.txt @@ -17,15 +17,14 @@ interrupt. List of legacy properties and respective binding document --------------------------------------------------------- -1. "enable-sdio-wakeup" Documentation/devicetree/bindings/mmc/mmc.txt -2. "gpio-key,wakeup" Documentation/devicetree/bindings/input/gpio-keys{,-polled}.txt -3. "has-tpo" Documentation/devicetree/bindings/rtc/rtc-opal.txt -4. "linux,wakeup" Documentation/devicetree/bindings/input/gpio-matrix-keypad.txt +1. "gpio-key,wakeup" Documentation/devicetree/bindings/input/gpio-keys{,-polled}.txt +2. "has-tpo" Documentation/devicetree/bindings/rtc/rtc-opal.txt +3. "linux,wakeup" Documentation/devicetree/bindings/input/gpio-matrix-keypad.txt Documentation/devicetree/bindings/mfd/tc3589x.txt Documentation/devicetree/bindings/input/touchscreen/ads7846.txt -5. "linux,keypad-wakeup" Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt -6. "linux,input-wakeup" Documentation/devicetree/bindings/input/samsung-keypad.txt -7. "nvidia,wakeup-source" Documentation/devicetree/bindings/input/nvidia,tegra20-kbc.txt +4. "linux,keypad-wakeup" Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt +5. "linux,input-wakeup" Documentation/devicetree/bindings/input/samsung-keypad.txt +6. "nvidia,wakeup-source" Documentation/devicetree/bindings/input/nvidia,tegra20-kbc.txt Examples -------- diff --git a/Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml b/Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml index 4cc3cc7c50be..66e400f2a3a4 100644 --- a/Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml @@ -25,7 +25,9 @@ properties: - const: allwinner,sun8i-a83t-pwm - const: allwinner,sun8i-h3-pwm - items: - - const: allwinner,sun8i-v3s-pwm + - enum: + - allwinner,suniv-f1c100s-pwm + - allwinner,sun8i-v3s-pwm - const: allwinner,sun7i-a20-pwm - items: - const: allwinner,sun50i-a64-pwm diff --git a/Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml b/Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml index c8577bdf6c94..3afe1480df52 100644 --- a/Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml @@ -48,6 +48,7 @@ examples: cros-ec@0 { compatible = "google,cros-ec-spi"; reg = <0>; + interrupts = <101 0>; cros_ec_pwm: pwm { compatible = "google,cros-ec-pwm"; diff --git a/Documentation/devicetree/bindings/pwm/microchip,corepwm.yaml b/Documentation/devicetree/bindings/pwm/microchip,corepwm.yaml index a7fae1772a81..cd8e9a8907f8 100644 --- a/Documentation/devicetree/bindings/pwm/microchip,corepwm.yaml +++ b/Documentation/devicetree/bindings/pwm/microchip,corepwm.yaml @@ -30,7 +30,9 @@ properties: maxItems: 1 "#pwm-cells": - const: 2 + enum: [2, 3] + description: + The only flag supported by the controller is PWM_POLARITY_INVERTED. microchip,sync-update-mask: description: | diff --git a/Documentation/devicetree/bindings/pwm/nvidia,tegra20-pwm.txt b/Documentation/devicetree/bindings/pwm/nvidia,tegra20-pwm.txt deleted file mode 100644 index 74c41e34c3b6..000000000000 --- a/Documentation/devicetree/bindings/pwm/nvidia,tegra20-pwm.txt +++ /dev/null @@ -1,77 +0,0 @@ -Tegra SoC PWFM controller - -Required properties: -- compatible: Must be: - - "nvidia,tegra20-pwm": for Tegra20 - - "nvidia,tegra30-pwm", "nvidia,tegra20-pwm": for Tegra30 - - "nvidia,tegra114-pwm", "nvidia,tegra20-pwm": for Tegra114 - - "nvidia,tegra124-pwm", "nvidia,tegra20-pwm": for Tegra124 - - "nvidia,tegra132-pwm", "nvidia,tegra20-pwm": for Tegra132 - - "nvidia,tegra210-pwm", "nvidia,tegra20-pwm": for Tegra210 - - "nvidia,tegra186-pwm": for Tegra186 - - "nvidia,tegra194-pwm": for Tegra194 -- reg: physical base address and length of the controller's registers -- #pwm-cells: should be 2. See pwm.yaml in this directory for a description of - the cells format. -- clocks: Must contain one entry, for the module clock. - See ../clocks/clock-bindings.txt for details. -- resets: Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names: Must include the following entries: - - pwm - -Optional properties: -============================ -In some of the interface like PWM based regulator device, it is required -to configure the pins differently in different states, especially in suspend -state of the system. The configuration of pin is provided via the pinctrl -DT node as detailed in the pinctrl DT binding document - Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt - -The PWM node will have following optional properties. -pinctrl-names: Pin state names. Must be "default" and "sleep". -pinctrl-0: phandle for the default/active state of pin configurations. -pinctrl-1: phandle for the sleep state of pin configurations. - -Example: - - pwm: pwm@7000a000 { - compatible = "nvidia,tegra20-pwm"; - reg = <0x7000a000 0x100>; - #pwm-cells = <2>; - clocks = <&tegra_car 17>; - resets = <&tegra_car 17>; - reset-names = "pwm"; - }; - - -Example with the pin configuration for suspend and resume: -========================================================= -Suppose pin PE7 (On Tegra210) interfaced with the regulator device and -it requires PWM output to be tristated when system enters suspend. -Following will be DT binding to achieve this: - -#include <dt-bindings/pinctrl/pinctrl-tegra.h> - - pinmux@700008d4 { - pwm_active_state: pwm_active_state { - pe7 { - nvidia,pins = "pe7"; - nvidia,tristate = <TEGRA_PIN_DISABLE>; - }; - }; - - pwm_sleep_state: pwm_sleep_state { - pe7 { - nvidia,pins = "pe7"; - nvidia,tristate = <TEGRA_PIN_ENABLE>; - }; - }; - }; - - pwm@7000a000 { - /* Mandatory PWM properties */ - pinctrl-names = "default", "sleep"; - pinctrl-0 = <&pwm_active_state>; - pinctrl-1 = <&pwm_sleep_state>; - }; diff --git a/Documentation/devicetree/bindings/pwm/nvidia,tegra20-pwm.yaml b/Documentation/devicetree/bindings/pwm/nvidia,tegra20-pwm.yaml new file mode 100644 index 000000000000..739d3155dd32 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/nvidia,tegra20-pwm.yaml @@ -0,0 +1,96 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pwm/nvidia,tegra20-pwm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra PWFM controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + +properties: + compatible: + oneOf: + - enum: + - nvidia,tegra20-pwm + - nvidia,tegra186-pwm + + - items: + - enum: + - nvidia,tegra30-pwm + - nvidia,tegra114-pwm + - nvidia,tegra124-pwm + - nvidia,tegra132-pwm + - nvidia,tegra210-pwm + - enum: + - nvidia,tegra20-pwm + + - items: + - const: nvidia,tegra194-pwm + - const: nvidia,tegra186-pwm + + - items: + - const: nvidia,tegra234-pwm + - const: nvidia,tegra194-pwm + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + items: + - description: module reset + + reset-names: + items: + - const: pwm + + "#pwm-cells": + const: 2 + + pinctrl-names: + items: + - const: default + - const: sleep + + pinctrl-0: + description: configuration for the default/active state + + pinctrl-1: + description: configuration for the sleep state + + operating-points-v2: + $ref: /schemas/types.yaml#/definitions/phandle + + power-domains: + items: + - description: phandle to the core power domain + +allOf: + - $ref: pwm.yaml + +required: + - compatible + - reg + - clocks + - resets + - reset-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/tegra20-car.h> + + pwm: pwm@7000a000 { + compatible = "nvidia,tegra20-pwm"; + reg = <0x7000a000 0x100>; + #pwm-cells = <2>; + clocks = <&tegra_car TEGRA20_CLK_PWM>; + resets = <&tegra_car 17>; + reset-names = "pwm"; + }; diff --git a/Documentation/devicetree/bindings/regulator/google,cros-ec-regulator.yaml b/Documentation/devicetree/bindings/regulator/google,cros-ec-regulator.yaml index 69e5402da761..0921f012c901 100644 --- a/Documentation/devicetree/bindings/regulator/google,cros-ec-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/google,cros-ec-regulator.yaml @@ -41,6 +41,7 @@ examples: reg = <0>; #address-cells = <1>; #size-cells = <0>; + interrupts = <99 0>; regulator@0 { compatible = "google,cros-ec-regulator"; diff --git a/Documentation/devicetree/bindings/regulator/max77650-regulator.yaml b/Documentation/devicetree/bindings/regulator/max77650-regulator.yaml index ce0a4021ae7f..01b9775a92d1 100644 --- a/Documentation/devicetree/bindings/regulator/max77650-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/max77650-regulator.yaml @@ -26,6 +26,7 @@ properties: patternProperties: "^regulator-(ldo|sbb[0-2])$": $ref: "regulator.yaml#" + unevaluatedProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/regulator/max8660.yaml b/Documentation/devicetree/bindings/regulator/max8660.yaml index 9c038698f880..35792a927b03 100644 --- a/Documentation/devicetree/bindings/regulator/max8660.yaml +++ b/Documentation/devicetree/bindings/regulator/max8660.yaml @@ -24,8 +24,9 @@ properties: type: object patternProperties: - "regulator-.+": + "^regulator-.+$": $ref: "regulator.yaml#" + unevaluatedProperties: false additionalProperties: false @@ -43,31 +44,26 @@ examples: regulators { regulator-V3 { - regulator-compatible= "V3(DCDC)"; regulator-min-microvolt = <725000>; regulator-max-microvolt = <1800000>; }; regulator-V4 { - regulator-compatible= "V4(DCDC)"; regulator-min-microvolt = <725000>; regulator-max-microvolt = <1800000>; }; regulator-V5 { - regulator-compatible= "V5(LDO)"; regulator-min-microvolt = <1700000>; regulator-max-microvolt = <2000000>; }; regulator-V6 { - regulator-compatible= "V6(LDO)"; regulator-min-microvolt = <1800000>; regulator-max-microvolt = <3300000>; }; regulator-V7 { - regulator-compatible= "V7(LDO)"; regulator-min-microvolt = <1800000>; regulator-max-microvolt = <3300000>; }; diff --git a/Documentation/devicetree/bindings/regulator/maxim,max77802.yaml b/Documentation/devicetree/bindings/regulator/maxim,max77802.yaml index 71138c611b6c..b704f05ea454 100644 --- a/Documentation/devicetree/bindings/regulator/maxim,max77802.yaml +++ b/Documentation/devicetree/bindings/regulator/maxim,max77802.yaml @@ -77,7 +77,7 @@ patternProperties: regulator-initial-mode: false patternProperties: - regulator-state-(standby|mem|disk): + "^regulator-state-(standby|mem|disk)$": type: object additionalProperties: true properties: diff --git a/Documentation/devicetree/bindings/regulator/mediatek,mt6357-regulator.yaml b/Documentation/devicetree/bindings/regulator/mediatek,mt6357-regulator.yaml new file mode 100644 index 000000000000..6327bb2f6ee0 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/mediatek,mt6357-regulator.yaml @@ -0,0 +1,294 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/mediatek,mt6357-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek MT6357 Regulators + +maintainers: + - Chen Zhong <chen.zhong@mediatek.com> + - Fabien Parent <fabien.parent@linaro.org> + - Alexandre Mergnat <amergnat@baylibre.com> + +description: | + The MT6357 PMIC provides 5 BUCK and 29 LDO. + Regulators and nodes are named according to the regulator type: + - buck-<name> + - ldo-<name>. + MT6357 regulators node should be sub node of the MT6397 MFD node. + +patternProperties: + "^buck-v(core|modem|pa|proc|s1)$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: + Properties for single BUCK regulator. + + required: + - regulator-name + - regulator-min-microvolt + - regulator-max-microvolt + + "^ldo-v(camio18|aud28|aux18|io18|io28|rf12|rf18|cn18|cn28|fe28)$": + type: object + $ref: fixed-regulator.yaml# + unevaluatedProperties: false + description: + Properties for single fixed LDO regulator. + + required: + - regulator-name + - regulator-min-microvolt + - regulator-max-microvolt + + "^ldo-v(efuse|ibr|ldo28|mch|cama|camd|cn33-bt|cn33-wifi)$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: + Properties for single LDO regulator. + + required: + - regulator-name + - regulator-min-microvolt + - regulator-max-microvolt + + "^ldo-v(xo22|emc|mc|sim1|sim2|sram-others|sram-proc|dram|usb33)$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: + Properties for single LDO regulator. + + required: + - regulator-name + - regulator-min-microvolt + - regulator-max-microvolt + +additionalProperties: false + +examples: + - | + pmic { + regulators { + mt6357_vproc_reg: buck-vproc { + regulator-name = "vproc"; + regulator-min-microvolt = <518750>; + regulator-max-microvolt = <1312500>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <220>; + regulator-always-on; + }; + mt6357_vcore_reg: buck-vcore { + regulator-name = "vcore"; + regulator-min-microvolt = <518750>; + regulator-max-microvolt = <1312500>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <220>; + regulator-always-on; + }; + mt6357_vmodem_reg: buck-vmodem { + regulator-name = "vmodem"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <1193750>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <220>; + }; + mt6357_vs1_reg: buck-vs1 { + regulator-name = "vs1"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <2200000>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <220>; + regulator-always-on; + }; + mt6357_vpa_reg: buck-vpa { + regulator-name = "vpa"; + regulator-min-microvolt = <500000>; + regulator-max-microvolt = <3650000>; + regulator-ramp-delay = <50000>; + regulator-enable-ramp-delay = <220>; + }; + mt6357_vfe28_reg: ldo-vfe28 { + compatible = "regulator-fixed"; + regulator-name = "vfe28"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-enable-ramp-delay = <264>; + }; + mt6357_vxo22_reg: ldo-vxo22 { + regulator-name = "vxo22"; + regulator-min-microvolt = <2200000>; + regulator-max-microvolt = <2400000>; + regulator-enable-ramp-delay = <110>; + }; + mt6357_vrf18_reg: ldo-vrf18 { + compatible = "regulator-fixed"; + regulator-name = "vrf18"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-enable-ramp-delay = <110>; + }; + mt6357_vrf12_reg: ldo-vrf12 { + compatible = "regulator-fixed"; + regulator-name = "vrf12"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-enable-ramp-delay = <110>; + }; + mt6357_vefuse_reg: ldo-vefuse { + regulator-name = "vefuse"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <264>; + }; + mt6357_vcn33_bt_reg: ldo-vcn33-bt { + regulator-name = "vcn33-bt"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3500000>; + regulator-enable-ramp-delay = <264>; + }; + mt6357_vcn33_wifi_reg: ldo-vcn33-wifi { + regulator-name = "vcn33-wifi"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3500000>; + regulator-enable-ramp-delay = <264>; + }; + mt6357_vcn28_reg: ldo-vcn28 { + compatible = "regulator-fixed"; + regulator-name = "vcn28"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-enable-ramp-delay = <264>; + }; + mt6357_vcn18_reg: ldo-vcn18 { + compatible = "regulator-fixed"; + regulator-name = "vcn18"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-enable-ramp-delay = <264>; + }; + mt6357_vcama_reg: ldo-vcama { + regulator-name = "vcama"; + regulator-min-microvolt = <2500000>; + regulator-max-microvolt = <2800000>; + regulator-enable-ramp-delay = <264>; + }; + mt6357_vcamd_reg: ldo-vcamd { + regulator-name = "vcamd"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1800000>; + regulator-enable-ramp-delay = <264>; + }; + mt6357_vcamio_reg: ldo-vcamio18 { + compatible = "regulator-fixed"; + regulator-name = "vcamio"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-enable-ramp-delay = <264>; + }; + mt6357_vldo28_reg: ldo-vldo28 { + regulator-name = "vldo28"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <3000000>; + regulator-enable-ramp-delay = <264>; + }; + mt6357_vsram_others_reg: ldo-vsram-others { + regulator-name = "vsram-others"; + regulator-min-microvolt = <518750>; + regulator-max-microvolt = <1312500>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <110>; + regulator-always-on; + }; + mt6357_vsram_proc_reg: ldo-vsram-proc { + regulator-name = "vsram-proc"; + regulator-min-microvolt = <518750>; + regulator-max-microvolt = <1312500>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <110>; + regulator-always-on; + }; + mt6357_vaux18_reg: ldo-vaux18 { + compatible = "regulator-fixed"; + regulator-name = "vaux18"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-enable-ramp-delay = <264>; + }; + mt6357_vaud28_reg: ldo-vaud28 { + compatible = "regulator-fixed"; + regulator-name = "vaud28"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-enable-ramp-delay = <264>; + }; + mt6357_vio28_reg: ldo-vio28 { + compatible = "regulator-fixed"; + regulator-name = "vio28"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-enable-ramp-delay = <264>; + }; + mt6357_vio18_reg: ldo-vio18 { + compatible = "regulator-fixed"; + regulator-name = "vio18"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-enable-ramp-delay = <264>; + regulator-always-on; + }; + mt6357_vdram_reg: ldo-vdram { + regulator-name = "vdram"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1200000>; + regulator-enable-ramp-delay = <3300>; + }; + mt6357_vmc_reg: ldo-vmc { + regulator-name = "vmc"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <44>; + }; + mt6357_vmch_reg: ldo-vmch { + regulator-name = "vmch"; + regulator-min-microvolt = <2900000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <44>; + }; + mt6357_vemc_reg: ldo-vemc { + regulator-name = "vemc"; + regulator-min-microvolt = <2900000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <44>; + regulator-always-on; + }; + mt6357_vsim1_reg: ldo-vsim1 { + regulator-name = "vsim1"; + regulator-min-microvolt = <1700000>; + regulator-max-microvolt = <3100000>; + regulator-enable-ramp-delay = <264>; + }; + mt6357_vsim2_reg: ldo-vsim2 { + regulator-name = "vsim2"; + regulator-min-microvolt = <1700000>; + regulator-max-microvolt = <3100000>; + regulator-enable-ramp-delay = <264>; + }; + mt6357_vibr_reg: ldo-vibr { + regulator-name = "vibr"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3300000>; + regulator-enable-ramp-delay = <44>; + }; + mt6357_vusb33_reg: ldo-vusb33 { + regulator-name = "vusb33"; + regulator-min-microvolt = <3000000>; + regulator-max-microvolt = <3100000>; + regulator-enable-ramp-delay = <264>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/mt6360-regulator.yaml b/Documentation/devicetree/bindings/regulator/mt6360-regulator.yaml index a462d99a25cc..8a0931dc2f30 100644 --- a/Documentation/devicetree/bindings/regulator/mt6360-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/mt6360-regulator.yaml @@ -27,9 +27,11 @@ properties: patternProperties: "^buck[12]$": $ref: "regulator.yaml#" + unevaluatedProperties: false "^ldo[123567]$": $ref: "regulator.yaml#" + unevaluatedProperties: false required: - compatible @@ -44,7 +46,6 @@ examples: compatible = "mediatek,mt6360-regulator"; LDO_VIN3-supply = <&BUCK2>; buck1 { - regulator-compatible = "BUCK1"; regulator-name = "mt6360,buck1"; regulator-min-microvolt = <300000>; regulator-max-microvolt = <1300000>; @@ -53,7 +54,6 @@ examples: MT6360_OPMODE_ULP>; }; BUCK2: buck2 { - regulator-compatible = "BUCK2"; regulator-name = "mt6360,buck2"; regulator-min-microvolt = <300000>; regulator-max-microvolt = <1300000>; @@ -62,7 +62,6 @@ examples: MT6360_OPMODE_ULP>; }; ldo6 { - regulator-compatible = "LDO6"; regulator-name = "mt6360,ldo6"; regulator-min-microvolt = <500000>; regulator-max-microvolt = <2100000>; @@ -70,7 +69,6 @@ examples: MT6360_OPMODE_LP>; }; ldo7 { - regulator-compatible = "LDO7"; regulator-name = "mt6360,ldo7"; regulator-min-microvolt = <500000>; regulator-max-microvolt = <2100000>; @@ -78,15 +76,13 @@ examples: MT6360_OPMODE_LP>; }; ldo1 { - regulator-compatible = "LDO1"; regulator-name = "mt6360,ldo1"; regulator-min-microvolt = <1200000>; regulator-max-microvolt = <3600000>; regulator-allowed-modes = <MT6360_OPMODE_NORMAL MT6360_OPMODE_LP>; }; - ldo2 { - regulator-compatible = "LDO2"; + ldo2 { regulator-name = "mt6360,ldo2"; regulator-min-microvolt = <1200000>; regulator-max-microvolt = <3600000>; @@ -94,7 +90,6 @@ examples: MT6360_OPMODE_LP>; }; ldo3 { - regulator-compatible = "LDO3"; regulator-name = "mt6360,ldo3"; regulator-min-microvolt = <1200000>; regulator-max-microvolt = <3600000>; @@ -102,7 +97,6 @@ examples: MT6360_OPMODE_LP>; }; ldo5 { - regulator-compatible = "LDO5"; regulator-name = "mt6360,ldo5"; regulator-min-microvolt = <2700000>; regulator-max-microvolt = <3600000>; diff --git a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml index 90c3bda31c23..297a75069f60 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml @@ -47,6 +47,7 @@ description: | For PM8350, smps1 - smps12, ldo1 - ldo10 For PM8350C, smps1 - smps10, ldo1 - ldo13, bob For PM8450, smps1 - smps6, ldo1 - ldo4 + For PM8550, smps1 - smps6, ldo1 - ldo17, bob1 - bob2 For PM8998, smps1 - smps13, ldo1 - ldo28, lvs1 - lvs2 For PMI8998, bob For PMR735A, smps1 - smps3, ldo1 - ldo7 @@ -70,6 +71,9 @@ properties: - qcom,pm8350-rpmh-regulators - qcom,pm8350c-rpmh-regulators - qcom,pm8450-rpmh-regulators + - qcom,pm8550-rpmh-regulators + - qcom,pm8550ve-rpmh-regulators + - qcom,pm8550vs-rpmh-regulators - qcom,pm8998-rpmh-regulators - qcom,pmg1110-rpmh-regulators - qcom,pmi8998-rpmh-regulators @@ -83,7 +87,7 @@ properties: RPMh resource name suffix used for the regulators found on this PMIC. $ref: /schemas/types.yaml#/definitions/string - enum: [a, b, c, d, e, f, h, k] + enum: [a, b, c, d, e, f, g, h, k] qcom,always-wait-for-ack: description: | @@ -107,7 +111,7 @@ properties: regulator-allow-set-load: ["regulator-allowed-modes"] patternProperties: - "^(smps|ldo|lvs)[0-9]+$": + "^(smps|ldo|lvs|bob)[0-9]+$": type: object $ref: "regulator.yaml#" description: smps/ldo regulator nodes(s). @@ -303,6 +307,24 @@ allOf: properties: compatible: enum: + - qcom,pm8550-rpmh-regulators + - qcom,pm8550ve-rpmh-regulators + - qcom,pm8550vs-rpmh-regulators + then: + properties: + vdd-l2-l13-l14-supply: true + vdd-l5-l16-supply: true + vdd-l6-l7-supply: true + vdd-l8-l9-supply: true + patternProperties: + "^vdd-l([1-4]|1[0-7])-supply$": true + "^vdd-s[1-6]-supply$": true + "^vdd-bob[1-2]-supply$": true + + - if: + properties: + compatible: + enum: - qcom,pm8998-rpmh-regulators then: properties: @@ -412,9 +434,8 @@ examples: regulator-min-microvolt = <1800000>; regulator-max-microvolt = <1800000>; regulator-initial-mode = <RPMH_REGULATOR_MODE_HPM>; - regulator-allowed-modes = - <RPMH_REGULATOR_MODE_LPM - RPMH_REGULATOR_MODE_HPM>; + regulator-allowed-modes = <RPMH_REGULATOR_MODE_LPM + RPMH_REGULATOR_MODE_HPM>; regulator-allow-set-load; }; @@ -431,9 +452,8 @@ examples: bob { regulator-min-microvolt = <3312000>; regulator-max-microvolt = <3600000>; - regulator-allowed-modes = - <RPMH_REGULATOR_MODE_AUTO - RPMH_REGULATOR_MODE_HPM>; + regulator-allowed-modes = <RPMH_REGULATOR_MODE_AUTO + RPMH_REGULATOR_MODE_HPM>; regulator-initial-mode = <RPMH_REGULATOR_MODE_AUTO>; }; }; diff --git a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml index 961eed51912c..8c45f53212b1 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml @@ -71,6 +71,8 @@ description: For pmi8998, bob + For pmr735a, s1, s2, s3, l1, l2, l3, l4, l5, l6, l7 + For pms405, s1, s2, s3, s4, s5, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13 @@ -98,6 +100,7 @@ properties: - qcom,rpm-pma8084-regulators - qcom,rpm-pmi8994-regulators - qcom,rpm-pmi8998-regulators + - qcom,rpm-pmr735a-regulators - qcom,rpm-pms405-regulators patternProperties: diff --git a/Documentation/devicetree/bindings/regulator/regulator-output.yaml b/Documentation/devicetree/bindings/regulator/regulator-output.yaml new file mode 100644 index 000000000000..078b37a1a71a --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/regulator-output.yaml @@ -0,0 +1,39 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- + +$id: http://devicetree.org/schemas/regulator/regulator-output.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Regulator output connector + +maintainers: + - Zev Weiss <zev@bewilderbeest.net> + +description: | + This describes a power output connector supplied by a regulator, + such as a power outlet on a power distribution unit (PDU). The + connector may be standalone or merely one channel or set of pins + within a ganged physical connector carrying multiple independent + power outputs. + +properties: + compatible: + const: regulator-output + + vout-supply: + description: + Phandle of the regulator supplying the output. + +required: + - compatible + - vout-supply + +additionalProperties: false + +examples: + - | + output { + compatible = "regulator-output"; + vout-supply = <&output_reg>; + }; diff --git a/Documentation/devicetree/bindings/regulator/regulator.yaml b/Documentation/devicetree/bindings/regulator/regulator.yaml index 6e8aa9eed3aa..53b81d8a2d41 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/regulator.yaml @@ -231,7 +231,7 @@ patternProperties: ".*-supply$": description: Input supply phandle(s) for this node - regulator-state-(standby|mem|disk): + "^regulator-state-(standby|mem|disk)$": type: object description: sub-nodes for regulator state in Standby, Suspend-to-RAM, and diff --git a/Documentation/devicetree/bindings/regulator/richtek,rt6190.yaml b/Documentation/devicetree/bindings/regulator/richtek,rt6190.yaml new file mode 100644 index 000000000000..29f7d3d5d658 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/richtek,rt6190.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/richtek,rt6190.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Richtek RT6190 4-Switch BuckBoost controller + +maintainers: + - ChiYuan Huang <cy_huang@richtek.com> + +description: | + The RT6190 is 4-Switch BuckBoost controller designed for converting input + voltage to output voltage that can be equal to, higher or lower than input + voltage. It operates with wide input voltage range from 4.5V to 36V, and + the output voltage can be set from 3V to 36V by external FB pin. It's commonly + used for the application like as BuckBoost bus supply, docking station and USB + power delivery product. + + Datasheet is available at + https://www.richtek.com/assets/product_file/RT6190/DS6190-02.pdf + +allOf: + - $ref: regulator.yaml# + +properties: + compatible: + enum: + - richtek,rt6190 + + reg: + maxItems: 1 + + enable-gpios: + maxItems: 1 + + wakeup-source: true + + interrupts: + maxItems: 1 + + regulator-allowed-modes: + description: | + buck allowed operating mode + 0: PSM mode (light load Power Saving Mode) + 1: FCCM mode (Forced-CCM mode) + maxItems: 2 + items: + enum: [0, 1] + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + regulator@2c { + compatible = "richtek,rt6190"; + reg = <0x2c>; + wakeup-source; + interrupts-extended = <&gpio26 0 IRQ_TYPE_LEVEL_LOW>; + enable-gpios = <&gpio26 1 GPIO_ACTIVE_HIGH>; + regulator-name = "richtek,rt6190-buckboost"; + regulator-min-microvolt = <3000000>; + regulator-max-microvolt = <32000000>; + regulator-min-microamp = <306000>; + regulator-max-microamp = <12114000>; + regulator-allowed-modes = <0 1>; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/rohm,bd9576-regulator.yaml b/Documentation/devicetree/bindings/regulator/rohm,bd9576-regulator.yaml index 7cb74cc8c5d9..54be194bb244 100644 --- a/Documentation/devicetree/bindings/regulator/rohm,bd9576-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/rohm,bd9576-regulator.yaml @@ -21,7 +21,7 @@ description: | regulator-voutl1, regulator-vouts1 patternProperties: - "regulator-.+": + "^regulator-.+$": type: object description: Properties for single regulator. diff --git a/Documentation/devicetree/bindings/regulator/ti,tps65219.yaml b/Documentation/devicetree/bindings/regulator/ti,tps65219.yaml index 78be79930fda..78e64521d401 100644 --- a/Documentation/devicetree/bindings/regulator/ti,tps65219.yaml +++ b/Documentation/devicetree/bindings/regulator/ti,tps65219.yaml @@ -51,13 +51,6 @@ properties: where the board has a button wired to the pin and triggers an interrupt on pressing it. -patternProperties: - "^buck[1-3]-supply$": - description: Input supply phandle of one regulator. - - "^ldo[1-4]-supply$": - description: Input supply phandle of one regulator. - regulators: type: object description: | @@ -82,6 +75,13 @@ patternProperties: additionalProperties: false +patternProperties: + "^buck[1-3]-supply$": + description: Input supply phandle of one regulator. + + "^ldo[1-4]-supply$": + description: Input supply phandle of one regulator. + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/riscv/cpus.yaml b/Documentation/devicetree/bindings/riscv/cpus.yaml index 90a7cabf58fe..83ad177a9043 100644 --- a/Documentation/devicetree/bindings/riscv/cpus.yaml +++ b/Documentation/devicetree/bindings/riscv/cpus.yaml @@ -28,17 +28,20 @@ properties: oneOf: - items: - enum: - - sifive,rocket0 + - andestech,ax45mp + - canaan,k210 - sifive,bullet0 - sifive,e5 - sifive,e7 - sifive,e71 - - sifive,u74-mc - - sifive,u54 - - sifive,u74 + - sifive,rocket0 - sifive,u5 + - sifive,u54 - sifive,u7 - - canaan,k210 + - sifive,u74 + - sifive,u74-mc + - thead,c906 + - thead,c910 - const: riscv - items: - enum: diff --git a/Documentation/devicetree/bindings/riscv/starfive.yaml b/Documentation/devicetree/bindings/riscv/starfive.yaml index 5b36243fd674..5d3fcee52d59 100644 --- a/Documentation/devicetree/bindings/riscv/starfive.yaml +++ b/Documentation/devicetree/bindings/riscv/starfive.yaml @@ -19,7 +19,9 @@ properties: compatible: oneOf: - items: - - const: beagle,beaglev-starlight-jh7100-r0 + - enum: + - beagle,beaglev-starlight-jh7100-r0 + - starfive,visionfive-v1 - const: starfive,jh7100 additionalProperties: true diff --git a/Documentation/devicetree/bindings/rng/nuvoton,npcm-rng.yaml b/Documentation/devicetree/bindings/rng/nuvoton,npcm-rng.yaml index abd134c9d400..e8e4ab1e5b95 100644 --- a/Documentation/devicetree/bindings/rng/nuvoton,npcm-rng.yaml +++ b/Documentation/devicetree/bindings/rng/nuvoton,npcm-rng.yaml @@ -16,7 +16,9 @@ maintainers: properties: compatible: - const: nuvoton,npcm750-rng + enum: + - nuvoton,npcm750-rng + - nuvoton,npcm845-rng reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml b/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml index 30eaa62e1aed..74f75f669e77 100644 --- a/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml +++ b/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml @@ -32,6 +32,9 @@ properties: - fsl,imx8qm-lpuart - fsl,imx8dxl-lpuart - const: fsl,imx8qxp-lpuart + - items: + - const: fsl,imxrt1050-lpuart + - const: fsl,imxrt1170-lpuart reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/soc/mediatek/mediatek,mt7986-wo-ccif.yaml b/Documentation/devicetree/bindings/soc/mediatek/mediatek,mt7986-wo-ccif.yaml new file mode 100644 index 000000000000..8e6ba2ec8a43 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/mediatek/mediatek,mt7986-wo-ccif.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/mediatek/mediatek,mt7986-wo-ccif.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek Wireless Ethernet Dispatch (WED) WO controller interface for MT7986 + +maintainers: + - Lorenzo Bianconi <lorenzo@kernel.org> + - Felix Fietkau <nbd@nbd.name> + +description: + The MediaTek wo-ccif provides a configuration interface for WED WO + controller used to perfrom offload rx packet processing (e.g. 802.11 + aggregation packet reordering or rx header translation) on MT7986 soc. + +properties: + compatible: + items: + - enum: + - mediatek,mt7986-wo-ccif + - const: syscon + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + soc { + #address-cells = <2>; + #size-cells = <2>; + + syscon@151a5000 { + compatible = "mediatek,mt7986-wo-ccif", "syscon"; + reg = <0 0x151a5000 0 0x1000>; + interrupts = <GIC_SPI 205 IRQ_TYPE_LEVEL_HIGH>; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/mediatek/pwrap.txt b/Documentation/devicetree/bindings/soc/mediatek/pwrap.txt index d24e2bc444be..12e4b4260b40 100644 --- a/Documentation/devicetree/bindings/soc/mediatek/pwrap.txt +++ b/Documentation/devicetree/bindings/soc/mediatek/pwrap.txt @@ -30,6 +30,7 @@ Required properties in pwrap device node. "mediatek,mt8186-pwrap" for MT8186 SoCs "mediatek,mt8188-pwrap", "mediatek,mt8195-pwrap" for MT8188 SoCs "mediatek,mt8195-pwrap" for MT8195 SoCs + "mediatek,mt8365-pwrap" for MT8365 SoCs "mediatek,mt8516-pwrap" for MT8516 SoCs - interrupts: IRQ for pwrap in SOC - reg-names: "pwrap" is required; "pwrap-bridge" is optional. @@ -39,6 +40,8 @@ Required properties in pwrap device node. - clock-names: Must include the following entries: "spi": SPI bus clock "wrap": Main module clock + "sys": Optional system module clock + "tmr": Optional timer module clock - clocks: Must contain an entry for each entry in clock-names. Optional properities: diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml index a4eeb7e158e5..98d087cf4fc0 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml @@ -28,12 +28,14 @@ properties: - qcom,sc7180-aoss-qmp - qcom,sc7280-aoss-qmp - qcom,sc8180x-aoss-qmp + - qcom,sc8280xp-aoss-qmp - qcom,sdm845-aoss-qmp - qcom,sm6350-aoss-qmp - qcom,sm8150-aoss-qmp - qcom,sm8250-aoss-qmp - qcom,sm8350-aoss-qmp - qcom,sm8450-aoss-qmp + - qcom,sm8550-aoss-qmp - const: qcom,aoss-qmp reg: diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,apr-services.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,apr-services.yaml new file mode 100644 index 000000000000..290555426c39 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,apr-services.yaml @@ -0,0 +1,54 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/qcom/qcom,apr-services.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm APR/GPR services shared parts + +maintainers: + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +description: + Common parts of a static service in Qualcomm APR/GPR (Asynchronous/Generic + Packet Router). + +properties: + reg: + minimum: 1 + maximum: 13 + description: | + APR Service ID + 3 = DSP Core Service + 4 = Audio Front End Service. + 5 = Voice Stream Manager Service. + 6 = Voice processing manager. + 7 = Audio Stream Manager Service. + 8 = Audio Device Manager Service. + 9 = Multimode voice manager. + 10 = Core voice stream. + 11 = Core voice processor. + 12 = Ultrasound stream manager. + 13 = Listen stream manager. + GPR Service ID + 1 = Audio Process Manager Service + 2 = Proxy Resource Manager Service. + 3 = AMDB Service. + 4 = Voice processing manager. + + qcom,protection-domain: + $ref: /schemas/types.yaml#/definitions/string-array + description: | + Protection domain service name and path for APR service + possible values are:: + "avs/audio", "msm/adsp/audio_pd". + "kernel/elf_loader", "msm/modem/wlan_pd". + "tms/servreg", "msm/adsp/audio_pd". + "tms/servreg", "msm/modem/wlan_pd". + "tms/servreg", "msm/slpi/sensor_pd". + +required: + - reg + - qcom,protection-domain + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,apr.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,apr.yaml index f47491aab3b1..a6bc3197d5dd 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,apr.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,apr.yaml @@ -17,6 +17,7 @@ description: | properties: compatible: enum: + - qcom,apr - qcom,apr-v2 - qcom,gpr @@ -58,8 +59,7 @@ properties: qcom,glink-channels: $ref: /schemas/types.yaml#/definitions/string-array description: Channel name used for the communication - items: - - const: apr_audio_svc + maxItems: 1 qcom,intents: $ref: /schemas/types.yaml#/definitions/uint32-array @@ -81,12 +81,13 @@ properties: '#size-cells': const: 0 -#APR/GPR Services patternProperties: "^service@[1-9a-d]$": type: object + $ref: /schemas/soc/qcom/qcom,apr-services.yaml + additionalProperties: true description: - APR/GPR node's client devices use subnodes for desired static port services. + APR/GPR static port services. properties: compatible: @@ -98,99 +99,6 @@ patternProperties: - qcom,q6apm - qcom,q6prm - reg: - minimum: 1 - maximum: 13 - description: - APR Service ID - 3 = DSP Core Service - 4 = Audio Front End Service. - 5 = Voice Stream Manager Service. - 6 = Voice processing manager. - 7 = Audio Stream Manager Service. - 8 = Audio Device Manager Service. - 9 = Multimode voice manager. - 10 = Core voice stream. - 11 = Core voice processor. - 12 = Ultrasound stream manager. - 13 = Listen stream manager. - GPR Service ID - 1 = Audio Process Manager Service - 2 = Proxy Resource Manager Service. - 3 = AMDB Service. - 4 = Voice processing manager. - - clock-controller: - $ref: /schemas/sound/qcom,q6dsp-lpass-clocks.yaml# - description: Qualcomm DSP LPASS clock controller - unevaluatedProperties: false - - dais: - type: object - oneOf: - - $ref: /schemas/sound/qcom,q6apm-dai.yaml# - - $ref: /schemas/sound/qcom,q6dsp-lpass-ports.yaml# - - $ref: /schemas/sound/qcom,q6asm-dais.yaml# - unevaluatedProperties: false - description: Qualcomm DSP audio ports - - routing: - type: object - $ref: /schemas/sound/qcom,q6adm-routing.yaml# - unevaluatedProperties: false - description: Qualcomm DSP LPASS audio routing - - qcom,protection-domain: - $ref: /schemas/types.yaml#/definitions/string-array - description: protection domain service name and path for apr service - possible values are - "avs/audio", "msm/adsp/audio_pd". - "kernel/elf_loader", "msm/modem/wlan_pd". - "tms/servreg", "msm/adsp/audio_pd". - "tms/servreg", "msm/modem/wlan_pd". - "tms/servreg", "msm/slpi/sensor_pd". - - allOf: - - if: - properties: - compatible: - enum: - - qcom,q6afe - then: - properties: - dais: - properties: - compatible: - const: qcom,q6afe-dais - - - if: - properties: - compatible: - enum: - - qcom,q6apm - then: - properties: - dais: - properties: - compatible: - enum: - - qcom,q6apm-dais - - qcom,q6apm-lpass-dais - - - if: - properties: - compatible: - enum: - - qcom,q6asm - then: - properties: - dais: - properties: - compatible: - const: qcom,q6asm-dais - - additionalProperties: false - required: - compatible - qcom,domain @@ -203,7 +111,15 @@ allOf: - qcom,gpr then: properties: + qcom,glink-channels: + items: + - const: adsp_apps power-domains: false + else: + properties: + qcom,glink-channels: + items: + - const: apr_audio_svc - if: required: @@ -227,31 +143,35 @@ examples: apr { compatible = "qcom,apr-v2"; qcom,domain = <APR_DOMAIN_ADSP>; + qcom,glink-channels = "apr_audio_svc"; + qcom,intents = <512 20>; #address-cells = <1>; #size-cells = <0>; q6core: service@3 { - compatible = "qcom,q6core"; - reg = <APR_SVC_ADSP_CORE>; - qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; - }; - - q6afe: service@4 { - compatible = "qcom,q6afe"; - reg = <APR_SVC_AFE>; - qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; - }; - - q6asm: service@7 { - compatible = "qcom,q6asm"; - reg = <APR_SVC_ASM>; - qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; + compatible = "qcom,q6core"; + reg = <APR_SVC_ADSP_CORE>; + qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; }; - q6adm: service@8 { - compatible = "qcom,q6adm"; - reg = <APR_SVC_ADM>; - qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; + service@4 { + compatible = "qcom,q6afe"; + reg = <APR_SVC_AFE>; + qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; + + clock-controller { + compatible = "qcom,q6afe-clocks"; + #clock-cells = <2>; + }; + + dais { + compatible = "qcom,q6afe-dais"; + #address-cells = <1>; + #size-cells = <0>; + #sound-dai-cells = <1>; + /* ... */ + }; + /* ... */ }; }; @@ -260,12 +180,25 @@ examples: gpr { compatible = "qcom,gpr"; qcom,domain = <GPR_DOMAIN_ID_ADSP>; + qcom,glink-channels = "adsp_apps"; + qcom,intents = <512 20>; #address-cells = <1>; #size-cells = <0>; service@1 { - compatible = "qcom,q6apm"; - reg = <GPR_APM_MODULE_IID>; - qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; + compatible = "qcom,q6apm"; + reg = <GPR_APM_MODULE_IID>; + #sound-dai-cells = <0>; + qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; + + dais { + compatible = "qcom,q6apm-dais"; + iommus = <&apps_smmu 0x1801 0x0>; + }; + + bedais { + compatible = "qcom,q6apm-lpass-dais"; + #sound-dai-cells = <1>; + }; }; }; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,rpmh-rsc.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,rpmh-rsc.yaml index 4a50f1d27724..b246500d3d5d 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,rpmh-rsc.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,rpmh-rsc.yaml @@ -99,6 +99,9 @@ properties: - const: drv-2 - const: drv-3 + power-domains: + maxItems: 1 + bcm-voter: $ref: /schemas/interconnect/qcom,bcm-voter.yaml# @@ -151,6 +154,7 @@ examples: <SLEEP_TCS 3>, <WAKE_TCS 3>, <CONTROL_TCS 1>; + power-domains = <&CLUSTER_PD>; }; - | @@ -197,6 +201,7 @@ examples: <SLEEP_TCS 3>, <WAKE_TCS 3>, <CONTROL_TCS 0>; + power-domains = <&CLUSTER_PD>; clock-controller { compatible = "qcom,sm8350-rpmh-clk"; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml index 09d5bfa920f2..11c0f4dd797c 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml @@ -4,7 +4,7 @@ $id: "http://devicetree.org/schemas/soc/qcom/qcom,smd-rpm.yaml#" $schema: "http://devicetree.org/meta-schemas/core.yaml#" -title: Qualcomm Resource Power Manager (RPM) over SMD +title: Qualcomm Resource Power Manager (RPM) over SMD/GLINK description: | This driver is used to interface with the Resource Power Manager (RPM) found @@ -12,9 +12,9 @@ description: | to vote for state of the system resources, such as clocks, regulators and bus frequencies. - The SMD information for the RPM edge should be filled out. See qcom,smd.yaml - for the required edge properties. All SMD related properties will reside - within the RPM node itself. + The SMD or GLINK information for the RPM edge should be filled out. See + qcom,smd.yaml for the required edge properties. All SMD/GLINK related + properties will reside within the RPM node itself. The RPM exposes resources to its subnodes. The rpm_requests node must be present and this subnode may contain children that designate regulator @@ -45,6 +45,7 @@ properties: - qcom,rpm-sdm660 - qcom,rpm-sm6115 - qcom,rpm-sm6125 + - qcom,rpm-sm6375 - qcom,rpm-qcm2290 - qcom,rpm-qcs404 @@ -55,12 +56,23 @@ properties: power-controller: $ref: /schemas/power/qcom,rpmpd.yaml# + qcom,glink-channels: + $ref: /schemas/types.yaml#/definitions/string-array + description: Channel name used for the RPM communication + items: + - const: rpm_requests + qcom,smd-channels: $ref: /schemas/types.yaml#/definitions/string-array description: Channel name used for the RPM communication items: - const: rpm_requests +patternProperties: + "^regulators(-[01])?$": + $ref: /schemas/regulator/qcom,smd-rpm-regulator.yaml# + unevaluatedProperties: false + if: properties: compatible: @@ -69,10 +81,18 @@ if: - qcom,rpm-apq8084 - qcom,rpm-msm8916 - qcom,rpm-msm8974 + - qcom,rpm-msm8976 - qcom,rpm-msm8953 then: + properties: + qcom,glink-channels: false required: - qcom,smd-channels +else: + properties: + qcom,smd-channels: false + required: + - qcom,glink-channels required: - compatible diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.yaml index 795bd8cd4104..58500529b90f 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.yaml @@ -60,7 +60,7 @@ properties: Two identifiers of the inbound and outbound smem items used for this edge. patternProperties: - "^master-kernel|slave-kernel|ipa-ap-to-modem|ipa-modem-to-ap$": + "^master-kernel|slave-kernel|ipa-ap-to-modem|ipa-modem-to-ap|wlan-ap-to-wpss|wlan-wpss-to-ap$": type: object description: Each SMP2P pair contain a set of inbound and outbound entries, these are diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,spm.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,spm.yaml index f433e6e0a19f..38818c37c3ea 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,spm.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,spm.yaml @@ -24,8 +24,11 @@ properties: - qcom,msm8998-silver-saw2-v4.1-l2 - qcom,msm8909-saw2-v3.0-cpu - qcom,msm8916-saw2-v3.0-cpu + - qcom,msm8939-saw2-v3.0-cpu - qcom,msm8226-saw2-v2.1-cpu - qcom,msm8974-saw2-v2.1-cpu + - qcom,msm8976-gold-saw2-v2.3-l2 + - qcom,msm8976-silver-saw2-v2.3-l2 - qcom,apq8084-saw2-v2.1-cpu - qcom,apq8064-saw2-v1.1-cpu - const: qcom,saw2 diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.yaml index 5320504bb5e0..0e6fd57d658d 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.yaml @@ -42,15 +42,13 @@ properties: bluetooth: type: object additionalProperties: false + allOf: + - $ref: /schemas/net/bluetooth/bluetooth-controller.yaml# properties: compatible: const: qcom,wcnss-bt - local-bd-address: - $ref: /schemas/types.yaml#/definitions/uint8-array - maxItems: 6 - description: - See Documentation/devicetree/bindings/net/bluetooth.txt + local-bd-address: true required: - compatible diff --git a/Documentation/devicetree/bindings/soc/renesas/renesas,r9a09g011-sys.yaml b/Documentation/devicetree/bindings/soc/renesas/renesas,r9a09g011-sys.yaml new file mode 100644 index 000000000000..1cac3cb5226c --- /dev/null +++ b/Documentation/devicetree/bindings/soc/renesas/renesas,r9a09g011-sys.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/renesas/renesas,r9a09g011-sys.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/V2M System Configuration (SYS) + +maintainers: + - Geert Uytterhoeven <geert+renesas@glider.be> + +description: + The RZ/V2M-alike SYS (System Configuration) controls the overall + configuration of the LSI and supports the following functions, + - Bank address settings for DMAC + - Bank address settings of the units for ICB + - ETHER AxCACHE[1] (C bit) control function + - RAMA initialization control + - MD[7:0] pin monitoring + - LSI version + - PCIe related settings + - WDT stop control + - Temperature sensor (TSU) monitor + +properties: + compatible: + const: renesas,r9a09g011-sys + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + sys: system-controller@a3f03000 { + compatible = "renesas,r9a09g011-sys"; + reg = <0xa3f03000 0x400>; + }; diff --git a/Documentation/devicetree/bindings/arm/renesas.yaml b/Documentation/devicetree/bindings/soc/renesas/renesas.yaml index f51464a08aff..2789022b52eb 100644 --- a/Documentation/devicetree/bindings/arm/renesas.yaml +++ b/Documentation/devicetree/bindings/soc/renesas/renesas.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0 %YAML 1.2 --- -$id: http://devicetree.org/schemas/arm/renesas.yaml# +$id: http://devicetree.org/schemas/soc/renesas/renesas.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Renesas SH-Mobile, R-Mobile, and R-Car Platform @@ -431,11 +431,12 @@ properties: - renesas,rzn1d400-db # RZN1D-DB (RZ/N1D Demo Board for the RZ/N1D 400 pins package) - const: renesas,r9a06g032 - - description: RZ/G2UL (R9A07G043) + - description: RZ/Five and RZ/G2UL (R9A07G043) items: - enum: - renesas,smarc-evk # SMARC EVK - enum: + - renesas,r9a07g043f01 # RZ/Five - renesas,r9a07g043u11 # RZ/G2UL Type-1 - renesas,r9a07g043u12 # RZ/G2UL Type-2 - const: renesas,r9a07g043 diff --git a/Documentation/devicetree/bindings/sound/adi,adau1372.yaml b/Documentation/devicetree/bindings/sound/adi,adau1372.yaml index 59f7c60a14ba..044bcd370d49 100644 --- a/Documentation/devicetree/bindings/sound/adi,adau1372.yaml +++ b/Documentation/devicetree/bindings/sound/adi,adau1372.yaml @@ -8,12 +8,15 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Analog Devices ADAU1372 CODEC maintainers: - - Alexandre Belloni <alexandre.belloni@bootlin.om> + - Alexandre Belloni <alexandre.belloni@bootlin.com> description: | Analog Devices ADAU1372 four inputs and two outputs codec. https://www.analog.com/media/en/technical-documentation/data-sheets/ADAU1372.pdf +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -42,7 +45,7 @@ required: - clocks - clock-names -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/adi,adau1977.yaml b/Documentation/devicetree/bindings/sound/adi,adau1977.yaml index 847b83398d3d..dba3023a45e5 100644 --- a/Documentation/devicetree/bindings/sound/adi,adau1977.yaml +++ b/Documentation/devicetree/bindings/sound/adi,adau1977.yaml @@ -51,6 +51,7 @@ required: - AVDD-supply allOf: + - $ref: dai-common.yaml# - $ref: /schemas/spi/spi-peripheral-props.yaml# unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/sound/adi,adau7118.yaml b/Documentation/devicetree/bindings/sound/adi,adau7118.yaml index fb78967ee17b..12f60507aed7 100644 --- a/Documentation/devicetree/bindings/sound/adi,adau7118.yaml +++ b/Documentation/devicetree/bindings/sound/adi,adau7118.yaml @@ -15,6 +15,9 @@ description: | standalone mode. https://www.analog.com/media/en/technical-documentation/data-sheets/ADAU7118.pdf +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -57,7 +60,7 @@ required: - iovdd-supply - dvdd-supply -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/ak4375.yaml b/Documentation/devicetree/bindings/sound/ak4375.yaml index 5f0fc584bb38..587598e122c6 100644 --- a/Documentation/devicetree/bindings/sound/ak4375.yaml +++ b/Documentation/devicetree/bindings/sound/ak4375.yaml @@ -9,6 +9,9 @@ title: AK4375 DAC and headphones amplifier maintainers: - Vincent Knecht <vincent.knecht@mailoo.org> +allOf: + - $ref: dai-common.yaml# + properties: compatible: const: asahi-kasei,ak4375 @@ -35,7 +38,7 @@ required: - avdd-supply - tvdd-supply -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/ak4613.yaml b/Documentation/devicetree/bindings/sound/ak4613.yaml index aa8a258a9f1c..010574645e6a 100644 --- a/Documentation/devicetree/bindings/sound/ak4613.yaml +++ b/Documentation/devicetree/bindings/sound/ak4613.yaml @@ -9,6 +9,9 @@ title: AK4613 I2C transmitter maintainers: - Kuninori Morimoto <kuninori.morimoto.gx@renesas.com> +allOf: + - $ref: dai-common.yaml# + properties: compatible: const: asahi-kasei,ak4613 @@ -35,7 +38,7 @@ required: - compatible - reg -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/ak4642.yaml b/Documentation/devicetree/bindings/sound/ak4642.yaml index 48a5b2c3934e..437fe5d7cae1 100644 --- a/Documentation/devicetree/bindings/sound/ak4642.yaml +++ b/Documentation/devicetree/bindings/sound/ak4642.yaml @@ -9,6 +9,9 @@ title: AK4642 I2C transmitter maintainers: - Kuninori Morimoto <kuninori.morimoto.gx@renesas.com> +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -37,7 +40,7 @@ required: - compatible - reg -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-codec.yaml b/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-codec.yaml index 292fcb643999..78273647f766 100644 --- a/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-codec.yaml +++ b/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-codec.yaml @@ -102,6 +102,7 @@ required: - dma-names allOf: + - $ref: dai-common.yaml# - if: properties: compatible: @@ -228,7 +229,7 @@ allOf: - Mic - Speaker -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-i2s.yaml b/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-i2s.yaml index dd30881ad2f5..739114fb6549 100644 --- a/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-i2s.yaml @@ -61,6 +61,7 @@ properties: maxItems: 1 allOf: + - $ref: dai-common.yaml# - if: properties: compatible: @@ -128,7 +129,7 @@ required: - dmas - dma-names -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml b/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml index 68c84e29ce57..8108c564dd78 100644 --- a/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml +++ b/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml @@ -54,6 +54,7 @@ properties: maxItems: 1 allOf: + - $ref: dai-common.yaml# - if: properties: compatible: @@ -104,7 +105,7 @@ required: - dmas - dma-names -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/allwinner,sun50i-h6-dmic.yaml b/Documentation/devicetree/bindings/sound/allwinner,sun50i-h6-dmic.yaml index 2f12cabe4c71..763b876047c1 100644 --- a/Documentation/devicetree/bindings/sound/allwinner,sun50i-h6-dmic.yaml +++ b/Documentation/devicetree/bindings/sound/allwinner,sun50i-h6-dmic.yaml @@ -9,9 +9,17 @@ title: Allwinner H6 DMIC maintainers: - Ban Tao <fengzheng923@gmail.com> +allOf: + - $ref: dai-common.yaml# + properties: compatible: - const: allwinner,sun50i-h6-dmic + oneOf: + - items: + - enum: + - allwinner,sun20i-d1-dmic + - const: allwinner,sun50i-h6-dmic + - const: allwinner,sun50i-h6-dmic "#sound-dai-cells": const: 0 @@ -54,7 +62,7 @@ required: - dma-names - resets -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/allwinner,sun8i-a33-codec.yaml b/Documentation/devicetree/bindings/sound/allwinner,sun8i-a33-codec.yaml index 4eb11a8e622b..63eadc4200ac 100644 --- a/Documentation/devicetree/bindings/sound/allwinner,sun8i-a33-codec.yaml +++ b/Documentation/devicetree/bindings/sound/allwinner,sun8i-a33-codec.yaml @@ -10,6 +10,9 @@ maintainers: - Chen-Yu Tsai <wens@csie.org> - Maxime Ripard <mripard@kernel.org> +allOf: + - $ref: dai-common.yaml# + properties: "#sound-dai-cells": minimum: 0 @@ -49,7 +52,7 @@ required: - clocks - clock-names -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/amlogic,aiu.yaml b/Documentation/devicetree/bindings/sound/amlogic,aiu.yaml index 0705f91199a0..6350dfc0a926 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,aiu.yaml +++ b/Documentation/devicetree/bindings/sound/amlogic,aiu.yaml @@ -10,7 +10,7 @@ maintainers: - Jerome Brunet <jbrunet@baylibre.com> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: $nodename: diff --git a/Documentation/devicetree/bindings/sound/amlogic,g12a-toacodec.yaml b/Documentation/devicetree/bindings/sound/amlogic,g12a-toacodec.yaml index 77469a45bb7a..23f82bb89750 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,g12a-toacodec.yaml +++ b/Documentation/devicetree/bindings/sound/amlogic,g12a-toacodec.yaml @@ -10,7 +10,7 @@ maintainers: - Jerome Brunet <jbrunet@baylibre.com> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: $nodename: diff --git a/Documentation/devicetree/bindings/sound/amlogic,t9015.yaml b/Documentation/devicetree/bindings/sound/amlogic,t9015.yaml index 580a3d040abc..5f5cccdbeb34 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,t9015.yaml +++ b/Documentation/devicetree/bindings/sound/amlogic,t9015.yaml @@ -10,7 +10,7 @@ maintainers: - Jerome Brunet <jbrunet@baylibre.com> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: $nodename: diff --git a/Documentation/devicetree/bindings/sound/apple,mca.yaml b/Documentation/devicetree/bindings/sound/apple,mca.yaml index d5dc92b5b654..40e3a202f443 100644 --- a/Documentation/devicetree/bindings/sound/apple,mca.yaml +++ b/Documentation/devicetree/bindings/sound/apple,mca.yaml @@ -14,6 +14,9 @@ description: | maintainers: - Martin Povišer <povik+lin@cutebit.org> +allOf: + - $ref: dai-common.yaml# + properties: compatible: items: @@ -106,7 +109,7 @@ required: - power-domains - '#sound-dai-cells' -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/awinic,aw8738.yaml b/Documentation/devicetree/bindings/sound/awinic,aw8738.yaml index dce86dafe382..bc6c6b172238 100644 --- a/Documentation/devicetree/bindings/sound/awinic,aw8738.yaml +++ b/Documentation/devicetree/bindings/sound/awinic,aw8738.yaml @@ -15,7 +15,7 @@ description: function (primarily the power limit for the amplifier). allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/sound/cirrus,cs35l41.yaml b/Documentation/devicetree/bindings/sound/cirrus,cs35l41.yaml index 51d815d0c696..82062d80d700 100644 --- a/Documentation/devicetree/bindings/sound/cirrus,cs35l41.yaml +++ b/Documentation/devicetree/bindings/sound/cirrus,cs35l41.yaml @@ -146,6 +146,7 @@ required: - "#sound-dai-cells" allOf: + - $ref: dai-common.yaml# - if: properties: cirrus,boost-type: @@ -171,7 +172,7 @@ allOf: cirrus,gpio1-src-select: enum: [1] -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/cirrus,cs35l45.yaml b/Documentation/devicetree/bindings/sound/cirrus,cs35l45.yaml index 184a1344ea76..88a0ca474c3d 100644 --- a/Documentation/devicetree/bindings/sound/cirrus,cs35l45.yaml +++ b/Documentation/devicetree/bindings/sound/cirrus,cs35l45.yaml @@ -14,6 +14,9 @@ description: | CS35L45 is a Boosted Mono Class D Amplifier with DSP Speaker Protection and Adaptive Battery Management. +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -52,7 +55,7 @@ required: - reg - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/cirrus,cs42l51.yaml b/Documentation/devicetree/bindings/sound/cirrus,cs42l51.yaml index 963a871e74da..422cbf38bfdb 100644 --- a/Documentation/devicetree/bindings/sound/cirrus,cs42l51.yaml +++ b/Documentation/devicetree/bindings/sound/cirrus,cs42l51.yaml @@ -9,6 +9,9 @@ title: CS42L51 audio codec DT bindings maintainers: - Olivier Moysan <olivier.moysan@foss.st.com> +allOf: + - $ref: dai-common.yaml# + properties: compatible: const: cirrus,cs42l51 @@ -46,7 +49,7 @@ required: - reg - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/cirrus,lochnagar.yaml b/Documentation/devicetree/bindings/sound/cirrus,lochnagar.yaml index cea612d3d4a7..52f024f5302a 100644 --- a/Documentation/devicetree/bindings/sound/cirrus,lochnagar.yaml +++ b/Documentation/devicetree/bindings/sound/cirrus,lochnagar.yaml @@ -24,6 +24,9 @@ description: | This binding must be part of the Lochnagar MFD binding: [1] ../mfd/cirrus,lochnagar.yaml +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -49,4 +52,4 @@ required: - clocks - clock-names -additionalProperties: false +unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/sound/cirrus,madera.yaml b/Documentation/devicetree/bindings/sound/cirrus,madera.yaml index 23138ddcb62d..014d4eaa8793 100644 --- a/Documentation/devicetree/bindings/sound/cirrus,madera.yaml +++ b/Documentation/devicetree/bindings/sound/cirrus,madera.yaml @@ -22,6 +22,9 @@ description: | The properties are all contained in the parent MFD node. +allOf: + - $ref: dai-common.yaml# + properties: '#sound-dai-cells': description: diff --git a/Documentation/devicetree/bindings/sound/name-prefix.yaml b/Documentation/devicetree/bindings/sound/dai-common.yaml index 2fe57f87ac52..d858eea73ed7 100644 --- a/Documentation/devicetree/bindings/sound/name-prefix.yaml +++ b/Documentation/devicetree/bindings/sound/dai-common.yaml @@ -1,10 +1,10 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/sound/name-prefix.yaml# +$id: http://devicetree.org/schemas/sound/dai-common.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Component sound name prefix +title: Digital Audio Interface Common Properties maintainers: - Jerome Brunet <jbrunet@baylibre.com> @@ -18,4 +18,6 @@ properties: sink/source names may use this property to prepend the name of their sinks/sources with the provided string. + '#sound-dai-cells': true + additionalProperties: true diff --git a/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.yaml b/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.yaml index f46c66bc6b2d..7735e08d35ba 100644 --- a/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.yaml +++ b/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.yaml @@ -167,6 +167,7 @@ required: - interrupt-names allOf: + - $ref: dai-common.yaml# - if: properties: opmode: @@ -177,7 +178,7 @@ allOf: required: - tdm-slots -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/dmic-codec.yaml b/Documentation/devicetree/bindings/sound/dmic-codec.yaml new file mode 100644 index 000000000000..59ef0cf6b6e5 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/dmic-codec.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/dmic-codec.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic PDM Digital microphone (DMIC) codec + +maintainers: + - Arnaud Pouliquen <arnaud.pouliquen@foss.st.com> + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + const: dmic-codec + + '#sound-dai-cells': + const: 0 + + dmicen-gpios: + description: GPIO specifier for DMIC to control start and stop + maxItems: 1 + + num-channels: + description: Number of microphones on this DAI + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + maximum: 8 + default: 8 + + modeswitch-delay-ms: + description: Delay (in ms) to complete DMIC mode switch + + wakeup-delay-ms: + description: Delay (in ms) after enabling the DMIC + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + dmic { + compatible = "dmic-codec"; + dmicen-gpios = <&gpio4 3 GPIO_ACTIVE_HIGH>; + num-channels = <1>; + wakeup-delay-ms = <50>; + modeswitch-delay-ms = <35>; + }; +... diff --git a/Documentation/devicetree/bindings/sound/dmic.txt b/Documentation/devicetree/bindings/sound/dmic.txt deleted file mode 100644 index 32e871037269..000000000000 --- a/Documentation/devicetree/bindings/sound/dmic.txt +++ /dev/null @@ -1,22 +0,0 @@ -Device-Tree bindings for Digital microphone (DMIC) codec - -This device support generic PDM digital microphone. - -Required properties: - - compatible: should be "dmic-codec". - -Optional properties: - - dmicen-gpios: GPIO specifier for dmic to control start and stop - - num-channels: Number of microphones on this DAI - - wakeup-delay-ms: Delay (in ms) after enabling the DMIC - - modeswitch-delay-ms: Delay (in ms) to complete DMIC mode switch - -Example node: - - dmic_codec: dmic@0 { - compatible = "dmic-codec"; - dmicen-gpios = <&gpio4 3 GPIO_ACTIVE_HIGH>; - num-channels = <1>; - wakeup-delay-ms <50>; - modeswitch-delay-ms <35>; - }; diff --git a/Documentation/devicetree/bindings/sound/everest,es8316.yaml b/Documentation/devicetree/bindings/sound/everest,es8316.yaml index 3b752bba748b..d9f8f0c7f6bb 100644 --- a/Documentation/devicetree/bindings/sound/everest,es8316.yaml +++ b/Documentation/devicetree/bindings/sound/everest,es8316.yaml @@ -10,6 +10,9 @@ maintainers: - Daniel Drake <drake@endlessm.com> - Katsuhiro Suzuki <katsuhiro@katsuster.net> +allOf: + - $ref: dai-common.yaml# + properties: compatible: const: everest,es8316 @@ -33,7 +36,7 @@ required: - reg - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/fsl,micfil.yaml b/Documentation/devicetree/bindings/sound/fsl,micfil.yaml index 64d57758ee67..4b99a18c79a0 100644 --- a/Documentation/devicetree/bindings/sound/fsl,micfil.yaml +++ b/Documentation/devicetree/bindings/sound/fsl,micfil.yaml @@ -18,6 +18,7 @@ properties: enum: - fsl,imx8mm-micfil - fsl,imx8mp-micfil + - fsl,imx93-micfil reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/fsl,rpmsg.yaml b/Documentation/devicetree/bindings/sound/fsl,rpmsg.yaml index d370c98a62c7..e847611a85f7 100644 --- a/Documentation/devicetree/bindings/sound/fsl,rpmsg.yaml +++ b/Documentation/devicetree/bindings/sound/fsl,rpmsg.yaml @@ -11,8 +11,11 @@ maintainers: description: | fsl_rpmsg is a virtual audio device. Mapping to real hardware devices - are SAI, DMA controlled by Cortex M core. What we see from Linux - side is a device which provides audio service by rpmsg channel. + are SAI, MICFIL, DMA controlled by Cortex M core. What we see from + Linux side is a device which provides audio service by rpmsg channel. + We can create different sound cards which access different hardwares + such as SAI, MICFIL, .etc through building rpmsg channels between + Cortex-A and Cortex-M. properties: compatible: @@ -85,6 +88,16 @@ properties: This is a boolean property. If present, the receiving function will be enabled. + fsl,rpmsg-channel-name: + $ref: /schemas/types.yaml#/definitions/string + description: | + A string property to assign rpmsg channel this sound card sits on. + This property can be omitted if there is only one sound card and it sits + on "rpmsg-audio-channel". + enum: + - rpmsg-audio-channel + - rpmsg-micfil-channel + required: - compatible - model @@ -107,3 +120,22 @@ examples: <&clk IMX8MN_AUDIO_PLL2_OUT>; clock-names = "ipg", "mclk", "dma", "pll8k", "pll11k"; }; + + - | + #include <dt-bindings/clock/imx8mm-clock.h> + + rpmsg_micfil: audio-controller { + compatible = "fsl,imx8mm-rpmsg-audio"; + model = "micfil-audio"; + fsl,rpmsg-channel-name = "rpmsg-micfil-channel"; + fsl,enable-lpa; + fsl,rpmsg-in; + clocks = <&clk IMX8MM_CLK_PDM_IPG>, + <&clk IMX8MM_CLK_PDM_ROOT>, + <&clk IMX8MM_CLK_SDMA3_ROOT>, + <&clk IMX8MM_AUDIO_PLL1_OUT>, + <&clk IMX8MM_AUDIO_PLL2_OUT>; + clock-names = "ipg", "mclk", "dma", "pll8k", "pll11k"; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/fsl,sai.yaml b/Documentation/devicetree/bindings/sound/fsl,sai.yaml index 70c4111d59c7..5b28d2d51327 100644 --- a/Documentation/devicetree/bindings/sound/fsl,sai.yaml +++ b/Documentation/devicetree/bindings/sound/fsl,sai.yaml @@ -18,14 +18,12 @@ description: | properties: compatible: oneOf: - - enum: - - fsl,vf610-sai - - fsl,imx6sx-sai - - fsl,imx6ul-sai - - fsl,imx7ulp-sai - - fsl,imx8mq-sai - - fsl,imx8qm-sai - - fsl,imx8ulp-sai + - items: + - enum: + - fsl,imx6ul-sai + - fsl,imx7d-sai + - const: fsl,imx6sx-sai + - items: - enum: - fsl,imx8mm-sai @@ -33,19 +31,18 @@ properties: - fsl,imx8mp-sai - const: fsl,imx8mq-sai + - items: + - enum: + - fsl,imx6sx-sai + - fsl,imx7ulp-sai + - fsl,imx8mq-sai + - fsl,imx8qm-sai + - fsl,imx8ulp-sai + - fsl,vf610-sai + reg: maxItems: 1 - interrupts: - items: - - description: receive and transmit interrupt - - dmas: - maxItems: 2 - - dma-names: - maxItems: 2 - clocks: items: - description: The ipg clock for register access @@ -67,7 +64,7 @@ properties: - const: mclk3 - const: pll8k - const: pll11k - minItems: 4 + minItems: 5 - items: - const: bus - const: mclk1 @@ -77,19 +74,37 @@ properties: - const: pll11k minItems: 4 - lsb-first: - description: | - Configures whether the LSB or the MSB is transmitted - first for the fifo data. If this property is absent, - the MSB is transmitted first as default, or the LSB - is transmitted first. - type: boolean + dmas: + maxItems: 2 + + dma-names: + maxItems: 2 + + interrupts: + items: + - description: receive and transmit interrupt big-endian: description: | required if all the SAI registers are big-endian rather than little-endian. type: boolean + fsl,dataline: + $ref: /schemas/types.yaml#/definitions/uint32-matrix + description: | + Configure the dataline. It has 3 value for each configuration + maxItems: 16 + items: + items: + - description: format Default(0), I2S(1) or PDM(2) + enum: [0, 1, 2] + - description: dataline mask for 'rx' + - description: dataline mask for 'tx' + + fsl,sai-mclk-direction-output: + description: SAI will output the SAI MCLK clock. + type: boolean + fsl,sai-synchronous-rx: description: | SAI will work in the synchronous mode (sync Tx with Rx) which means @@ -108,31 +123,24 @@ properties: of transmitter. type: boolean - fsl,dataline: - $ref: /schemas/types.yaml#/definitions/uint32-matrix - description: | - Configure the dataline. It has 3 value for each configuration - maxItems: 16 - items: - items: - - description: format Default(0), I2S(1) or PDM(2) - enum: [0, 1, 2] - - description: dataline mask for 'rx' - - description: dataline mask for 'tx' - - fsl,sai-mclk-direction-output: - description: SAI will output the SAI MCLK clock. - type: boolean - fsl,shared-interrupt: description: Interrupt is shared with other modules. type: boolean + lsb-first: + description: | + Configures whether the LSB or the MSB is transmitted + first for the fifo data. If this property is absent, + the MSB is transmitted first as default, or the LSB + is transmitted first. + type: boolean + "#sound-dai-cells": const: 0 description: optional, some dts node didn't add it. allOf: + - $ref: dai-common.yaml# - if: properties: compatible: @@ -168,13 +176,13 @@ allOf: required: - compatible - reg - - interrupts - - dmas - - dma-names - clocks - clock-names + - dmas + - dma-names + - interrupts -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml b/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml index c3e9f3485449..1434f4433738 100644 --- a/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml +++ b/Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml @@ -8,7 +8,7 @@ title: Audio codec controlled by ChromeOS EC maintainers: - Cheng-Yi Chiang <cychiang@chromium.org> - - Tzung-Bi Shih <tzungbi@google.com> + - Tzung-Bi Shih <tzungbi@kernel.org> description: | Google's ChromeOS EC codec is a digital mic codec provided by the @@ -17,6 +17,9 @@ description: | subnode of a cros-ec node. (see Documentation/devicetree/bindings/mfd/google,cros-ec.yaml). +allOf: + - $ref: dai-common.yaml# + properties: compatible: const: google,cros-ec-codec @@ -42,7 +45,7 @@ required: - compatible - '#sound-dai-cells' -additionalProperties: false +unevaluatedProperties: false examples: - | @@ -57,6 +60,7 @@ examples: cros-ec@0 { compatible = "google,cros-ec-spi"; reg = <0>; + interrupts = <93 0>; codecs { #address-cells = <2>; diff --git a/Documentation/devicetree/bindings/sound/ingenic,aic.yaml b/Documentation/devicetree/bindings/sound/ingenic,aic.yaml index d607325f2f15..ba44406c9caf 100644 --- a/Documentation/devicetree/bindings/sound/ingenic,aic.yaml +++ b/Documentation/devicetree/bindings/sound/ingenic,aic.yaml @@ -9,6 +9,9 @@ title: Ingenic SoCs AC97 / I2S Controller (AIC) DT bindings maintainers: - Paul Cercueil <paul@crapouillou.net> +allOf: + - $ref: dai-common.yaml# + properties: $nodename: pattern: '^audio-controller@' @@ -37,15 +40,11 @@ properties: items: - description: AIC clock - description: I2S clock - - description: EXT clock - - description: PLL/2 clock clock-names: items: - const: aic - const: i2s - - const: ext - - const: pll half dmas: items: @@ -57,7 +56,7 @@ properties: - const: rx - const: tx -additionalProperties: false +unevaluatedProperties: false required: - compatible @@ -82,10 +81,8 @@ examples: interrupts = <18>; clocks = <&cgu JZ4740_CLK_AIC>, - <&cgu JZ4740_CLK_I2S>, - <&cgu JZ4740_CLK_EXT>, - <&cgu JZ4740_CLK_PLL_HALF>; - clock-names = "aic", "i2s", "ext", "pll half"; + <&cgu JZ4740_CLK_I2S>; + clock-names = "aic", "i2s"; dmas = <&dmac 25 0xffffffff>, <&dmac 24 0xffffffff>; dma-names = "rx", "tx"; diff --git a/Documentation/devicetree/bindings/sound/ingenic,codec.yaml b/Documentation/devicetree/bindings/sound/ingenic,codec.yaml index 48aae54dd643..a07d607e9b93 100644 --- a/Documentation/devicetree/bindings/sound/ingenic,codec.yaml +++ b/Documentation/devicetree/bindings/sound/ingenic,codec.yaml @@ -9,6 +9,9 @@ title: Ingenic JZ47xx internal codec DT bindings maintainers: - Paul Cercueil <paul@crapouillou.net> +allOf: + - $ref: dai-common.yaml# + properties: $nodename: pattern: '^audio-codec@.*' @@ -37,7 +40,7 @@ properties: '#sound-dai-cells': const: 0 -additionalProperties: false +unevaluatedProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml b/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml index b2603f611af9..76b6f2cf25df 100644 --- a/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml @@ -8,11 +8,15 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Intel KeemBay I2S maintainers: - - Sia, Jee Heng <jee.heng.sia@intel.com> + - Daniele Alessandrelli <daniele.alessandrelli@intel.com> + - Paul J. Murphy <paul.j.murphy@intel.com> description: | Intel KeemBay I2S +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -64,7 +68,7 @@ required: - clock-names - interrupts -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/linux,bt-sco.yaml b/Documentation/devicetree/bindings/sound/linux,bt-sco.yaml index b97e0fcbdba3..a67b79cbe006 100644 --- a/Documentation/devicetree/bindings/sound/linux,bt-sco.yaml +++ b/Documentation/devicetree/bindings/sound/linux,bt-sco.yaml @@ -9,6 +9,9 @@ title: Bluetooth SCO Audio Codec maintainers: - Mark Brown <broonie@kernel.org> +allOf: + - $ref: dai-common.yaml# + properties: '#sound-dai-cells': enum: @@ -26,7 +29,7 @@ required: - '#sound-dai-cells' - compatible -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/linux,spdif-dit.yaml b/Documentation/devicetree/bindings/sound/linux,spdif-dit.yaml index 808f6d2736c7..fe5f0756af2f 100644 --- a/Documentation/devicetree/bindings/sound/linux,spdif-dit.yaml +++ b/Documentation/devicetree/bindings/sound/linux,spdif-dit.yaml @@ -10,7 +10,7 @@ maintainers: - Mark Brown <broonie@kernel.org> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/sound/marvell,mmp-sspa.yaml b/Documentation/devicetree/bindings/sound/marvell,mmp-sspa.yaml index 81f266d66ec5..92d896e0d323 100644 --- a/Documentation/devicetree/bindings/sound/marvell,mmp-sspa.yaml +++ b/Documentation/devicetree/bindings/sound/marvell,mmp-sspa.yaml @@ -9,6 +9,9 @@ title: Marvel SSPA Digital Audio Interface Bindings maintainers: - Lubomir Rintel <lkundrak@v3.sk> +allOf: + - $ref: dai-common.yaml# + properties: $nodename: pattern: "^audio-controller(@.*)?$" @@ -73,7 +76,7 @@ required: - dma-names - port -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/max98357a.txt b/Documentation/devicetree/bindings/sound/max98357a.txt deleted file mode 100644 index 75db84d06240..000000000000 --- a/Documentation/devicetree/bindings/sound/max98357a.txt +++ /dev/null @@ -1,28 +0,0 @@ -Maxim MAX98357A/MAX98360A audio DAC - -This node models the Maxim MAX98357A/MAX98360A DAC. - -Required properties: -- compatible : "maxim,max98357a" for MAX98357A. - "maxim,max98360a" for MAX98360A. - -Optional properties: -- sdmode-gpios : GPIO specifier for the chip's SD_MODE pin. - If this option is not specified then driver does not manage - the pin state (e.g. chip is always on). -- sdmode-delay : specify delay time for SD_MODE pin. - If this option is specified, which means it's required i2s clocks - ready before SD_MODE is unmuted in order to avoid the speaker pop noise. - It's observed that 5ms is sufficient. - -Example: - -max98357a { - compatible = "maxim,max98357a"; - sdmode-gpios = <&qcom_pinmux 25 0>; -}; - -max98360a { - compatible = "maxim,max98360a"; - sdmode-gpios = <&qcom_pinmux 25 0>; -}; diff --git a/Documentation/devicetree/bindings/sound/max98504.txt b/Documentation/devicetree/bindings/sound/max98504.txt deleted file mode 100644 index 583ed5fdfb28..000000000000 --- a/Documentation/devicetree/bindings/sound/max98504.txt +++ /dev/null @@ -1,44 +0,0 @@ -Maxim MAX98504 class D mono speaker amplifier - -This device supports I2C control interface and an IRQ output signal. It features -a PCM and PDM digital audio interface (DAI) and a differential analog input. - -Required properties: - - - compatible : "maxim,max98504" - - reg : should contain the I2C slave device address - - DVDD-supply, DIOVDD-supply, PVDD-supply: power supplies for the device, - as covered in ../regulator/regulator.txt - - interrupts : should specify the interrupt line the device is connected to, - as described in ../interrupt-controller/interrupts.txt - -Optional properties: - - - maxim,brownout-threshold - the PVDD brownout threshold, the value must be - from 0, 1...21 range, corresponding to 2.6V, 2.65V...3.65V voltage range - - maxim,brownout-attenuation - the brownout attenuation to the speaker gain - applied during the "attack hold" and "timed hold" phase, the value must be - from 0...6 (dB) range - - maxim,brownout-attack-hold-ms - the brownout attack hold phase time in ms, - 0...255 (VBATBROWN_ATTK_HOLD, register 0x0018) - - maxim,brownout-timed-hold-ms - the brownout timed hold phase time in ms, - 0...255 (VBATBROWN_TIME_HOLD, register 0x0019) - - maxim,brownout-release-rate-ms - the brownout release phase step time in ms, - 0...255 (VBATBROWN_RELEASE, register 0x001A) - -The default value when the above properties are not specified is 0, -the maxim,brownout-threshold property must be specified to actually enable -the PVDD brownout protection. - -Example: - - max98504@31 { - compatible = "maxim,max98504"; - reg = <0x31>; - interrupt-parent = <&gpio_bank_0>; - interrupts = <2 0>; - - DVDD-supply = <®ulator>; - DIOVDD-supply = <®ulator>; - PVDD-supply = <®ulator>; -}; diff --git a/Documentation/devicetree/bindings/sound/maxim,max98357a.yaml b/Documentation/devicetree/bindings/sound/maxim,max98357a.yaml new file mode 100644 index 000000000000..83ba8666fbb4 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/maxim,max98357a.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/maxim,max98357a.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated MAX98357A/MAX98360A amplifier + +maintainers: + - Tzung-Bi Shih <tzungbi@kernel.org> + +description: + Maxim Integrated MAX98357A/MAX98360A is a digital pulse-code modulation (PCM) + input Class D amplifier. + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + enum: + - maxim,max98357a + - maxim,max98360a + + '#sound-dai-cells': + const: 0 + + sdmode-gpios: + maxItems: 1 + description: + Chip's SD_MODE pin. If missing the chip is always on. + + sdmode-delay: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Delay time for SD_MODE pin changes intended to make I2S clocks ready + before SD_MODE is unmuted in order to avoid the speaker pop noise. + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + amplifier { + compatible = "maxim,max98360a"; + #sound-dai-cells = <0>; + sdmode-gpios = <&qcom_pinmux 25 GPIO_ACTIVE_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/sound/maxim,max98504.yaml b/Documentation/devicetree/bindings/sound/maxim,max98504.yaml new file mode 100644 index 000000000000..23f19a9d2c06 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/maxim,max98504.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/maxim,max98504.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated MAX98504 class D mono speaker amplifier + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: + Maxim Integrated MAX98504 speaker amplifier supports I2C control interface + with an IRQ output signal, PCM and PDM digital audio interface (DAI) and a + differential analog input. + +properties: + compatible: + const: maxim,max98504 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + DIOVDD-supply: true + DVDD-supply: true + PVDD-supply: true + + maxim,brownout-threshold: + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 21 + default: 0 + description: + PVDD brownout threshold, where values correspond to 2.6V, 2.65V...3.65V + voltage range. Property also enables the PVDD brownout protection. + + maxim,brownout-attenuation: + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 6 + default: 0 + description: + Brownout attenuation to the speaker gain applied during the "attack hold" + and "timed hold" phase, the value must be from 0...6 (dB) range. + + maxim,brownout-attack-hold-ms: + maximum: 255 + default: 0 + description: + Brownout attack hold phase time in ms, VBATBROWN_ATTK_HOLD, register 0x0018. + + maxim,brownout-timed-hold-ms: + maximum: 255 + default: 0 + description: + Brownout timed hold phase time in ms, VBATBROWN_TIME_HOLD, register 0x0019. + + maxim,brownout-release-rate-ms: + maximum: 255 + default: 0 + description: + Brownout release phase step time in ms, VBATBROWN_RELEASE, register 0x001A. + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + amplifier@31 { + compatible = "maxim,max98504"; + reg = <0x31>; + + DIOVDD-supply = <&ldo3_reg>; + DVDD-supply = <&ldo3_reg>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/mchp,i2s-mcc.yaml b/Documentation/devicetree/bindings/sound/mchp,i2s-mcc.yaml index 0481315cb5f2..621022872c8d 100644 --- a/Documentation/devicetree/bindings/sound/mchp,i2s-mcc.yaml +++ b/Documentation/devicetree/bindings/sound/mchp,i2s-mcc.yaml @@ -66,13 +66,15 @@ properties: enum: [0, 1, 2, 3] default: 0 -if: - properties: - compatible: - const: microchip,sam9x60-i2smcc -then: - properties: - microchip,tdm-data-pair: false +allOf: + - $ref: dai-common.yaml# + - if: + properties: + compatible: + const: microchip,sam9x60-i2smcc + then: + properties: + microchip,tdm-data-pair: false required: - "#sound-dai-cells" @@ -84,7 +86,7 @@ required: - dmas - dma-names -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/mchp,spdiftx.yaml b/Documentation/devicetree/bindings/sound/mchp,spdiftx.yaml index d218e4ab9a7a..c383162140bb 100644 --- a/Documentation/devicetree/bindings/sound/mchp,spdiftx.yaml +++ b/Documentation/devicetree/bindings/sound/mchp,spdiftx.yaml @@ -13,6 +13,9 @@ description: The Microchip Sony/Philips Digital Interface Transmitter is a serial port compliant with the IEC-60958 standard. +allOf: + - $ref: dai-common.yaml# + properties: "#sound-dai-cells": const: 0 @@ -53,7 +56,7 @@ required: - dmas - dma-names -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/microchip,pdmc.yaml b/Documentation/devicetree/bindings/sound/microchip,pdmc.yaml index 04414eb4ada9..c37b89d94c12 100644 --- a/Documentation/devicetree/bindings/sound/microchip,pdmc.yaml +++ b/Documentation/devicetree/bindings/sound/microchip,pdmc.yaml @@ -13,6 +13,9 @@ description: The Microchip Pulse Density Microphone Controller (PDMC) interfaces up to 4 digital microphones having Pulse Density Modulated (PDM) outputs. +allOf: + - $ref: dai-common.yaml# + properties: compatible: const: microchip,sama7g5-pdmc @@ -75,7 +78,7 @@ required: - dma-names - microchip,mic-pos -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml b/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml index 4fc5b045d3cf..9d3139990237 100644 --- a/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml +++ b/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml @@ -21,6 +21,13 @@ properties: $ref: "/schemas/types.yaml#/definitions/phandle" description: The phandle of MT8186 ASoC platform. + dmic-gpios: + maxItems: 1 + description: + dmic-gpios optional prop for switching between two DMICs. + Ex, the GPIO can control a MUX HW component to select + dmic clk and data form a Front or Rear dmic. + headset-codec: type: object additionalProperties: false @@ -63,14 +70,19 @@ required: examples: - | + #include <dt-bindings/gpio/gpio.h> sound: mt8186-sound { compatible = "mediatek,mt8186-mt6366-rt1019-rt5682s-sound"; mediatek,platform = <&afe>; pinctrl-names = "aud_clk_mosi_off", - "aud_clk_mosi_on"; + "aud_clk_mosi_on", + "aud_gpio_dmic_sec"; pinctrl-0 = <&aud_clk_mosi_off>; pinctrl-1 = <&aud_clk_mosi_on>; + pinctrl-2 = <&aud_gpio_dmic_sec>; + + dmic-gpios = <&pio 23 GPIO_ACTIVE_HIGH>; headset-codec { sound-dai = <&rt5682s>; diff --git a/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml b/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml index 478be7e3fa29..c6e614c1c30b 100644 --- a/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml +++ b/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml @@ -34,7 +34,7 @@ properties: properties: sound-dai: - $ref: /schemas/types.yaml#/definitions/phandle + maxItems: 1 required: - sound-dai @@ -48,7 +48,6 @@ properties: maxItems: 2 items: maxItems: 1 - $ref: /schemas/types.yaml#/definitions/phandle-array required: - sound-dai diff --git a/Documentation/devicetree/bindings/sound/mvebu-audio.txt b/Documentation/devicetree/bindings/sound/mvebu-audio.txt index cb8c07c81ce4..4f5dec5cb3c2 100644 --- a/Documentation/devicetree/bindings/sound/mvebu-audio.txt +++ b/Documentation/devicetree/bindings/sound/mvebu-audio.txt @@ -6,9 +6,14 @@ Required properties: "marvell,kirkwood-audio" for Kirkwood platforms "marvell,dove-audio" for Dove platforms "marvell,armada370-audio" for Armada 370 platforms + "marvell,armada-380-audio" for Armada 38x platforms - reg: physical base address of the controller and length of memory mapped - region. + region (named "i2s_regs"). + With "marvell,armada-380-audio" two other regions are required: + first of those is dedicated for Audio PLL Configuration registers + (named "pll_regs") and the second one ("soc_ctrl") - for register + where one of exceptive I/O types (I2S or S/PDIF) is set. - interrupts: with "marvell,kirkwood-audio", the audio interrupt @@ -23,6 +28,13 @@ Required properties: "internal" for the internal clock "extclk" for the external clock +Optional properties: + +- spdif-mode: + Enable S/PDIF mode on Armada 38x SoC. Using this property + disables standard I2S I/O. Valid only with "marvell,armada-380-audio" + compatible string. + Example: i2s1: audio-controller@b4000 { diff --git a/Documentation/devicetree/bindings/sound/nau8315.txt b/Documentation/devicetree/bindings/sound/nau8315.txt index 6eaec46f384c..1cd94517d45e 100644 --- a/Documentation/devicetree/bindings/sound/nau8315.txt +++ b/Documentation/devicetree/bindings/sound/nau8315.txt @@ -2,6 +2,7 @@ Nuvoton NAU8315 Mono Class-D Amplifier Required properties: - compatible : "nuvoton,nau8315" + "nuvoton,nau8318" Optional properties: - enable-gpios : GPIO specifier for the chip's device enable input(EN) pin. @@ -16,3 +17,8 @@ nau8315 { compatible = "nuvoton,nau8315"; enable-gpios = <&gpio1 5 GPIO_ACTIVE_HIGH>; }; + +nau8318 { + compatible = "nuvoton,nau8318"; + enable-gpios = <&gpio1 5 GPIO_ACTIVE_HIGH>; +}; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra186-asrc.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra186-asrc.yaml index d82415c21271..e15f387c4c29 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra186-asrc.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra186-asrc.yaml @@ -23,7 +23,7 @@ maintainers: - Sameer Pujar <spujar@nvidia.com> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: $nodename: diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml index 3d538df878ea..e1362c77472b 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml @@ -18,7 +18,7 @@ maintainers: - Sameer Pujar <spujar@nvidia.com> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: $nodename: diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra20-spdif.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra20-spdif.yaml index 60a368a132b8..dc76a4dc0ed2 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra20-spdif.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra20-spdif.yaml @@ -16,6 +16,9 @@ maintainers: - Thierry Reding <treding@nvidia.com> - Jon Hunter <jonathanh@nvidia.com> +allOf: + - $ref: dai-common.yaml# + properties: compatible: const: nvidia,tegra20-spdif @@ -66,7 +69,7 @@ required: - dma-names - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-adx.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-adx.yaml index ea0dc0ece1bc..e4c871797fa6 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-adx.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-adx.yaml @@ -19,7 +19,7 @@ maintainers: - Sameer Pujar <spujar@nvidia.com> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: $nodename: diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-amx.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-amx.yaml index 1aff61f072bb..021b72546ba4 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-amx.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-amx.yaml @@ -18,7 +18,7 @@ maintainers: - Sameer Pujar <spujar@nvidia.com> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: $nodename: diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml index 0f9d2b461e02..bff551c35da7 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml @@ -17,7 +17,7 @@ maintainers: - Sameer Pujar <spujar@nvidia.com> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: $nodename: diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml index 12cd17eede99..a82f11fb6c9a 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml @@ -17,7 +17,7 @@ maintainers: - Sameer Pujar <spujar@nvidia.com> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: $nodename: diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-mixer.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-mixer.yaml index 570b03282aeb..049898f02e85 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-mixer.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-mixer.yaml @@ -17,7 +17,7 @@ maintainers: - Sameer Pujar <spujar@nvidia.com> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: $nodename: diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-mvc.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-mvc.yaml index 4aecbc847b98..d0280d8aa3af 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-mvc.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-mvc.yaml @@ -20,7 +20,7 @@ maintainers: - Sameer Pujar <spujar@nvidia.com> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: $nodename: diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-ope.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-ope.yaml index 9dc9ba590fa3..5fc03b8771b1 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-ope.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-ope.yaml @@ -17,7 +17,7 @@ maintainers: - Sameer Pujar <spujar@nvidia.com> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-sfc.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-sfc.yaml index 694f890d6305..185ca0be4f02 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-sfc.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-sfc.yaml @@ -17,7 +17,7 @@ maintainers: - Sameer Pujar <spujar@nvidia.com> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: $nodename: diff --git a/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml b/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml index 7f2e68ff6d34..fd2415e231eb 100644 --- a/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml +++ b/Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml @@ -10,7 +10,7 @@ maintainers: - Stephan Gerhold <stephan@gerhold.net> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml index ef18a572a1ff..5e26b3e9db2c 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml @@ -109,9 +109,10 @@ required: - interrupt-names - '#sound-dai-cells' -additionalProperties: false +unevaluatedProperties: false allOf: + - $ref: dai-common.yaml# - if: properties: compatible: diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml index 1de11e7f33bb..23564fd394a2 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml @@ -9,6 +9,9 @@ title: LPASS(Low Power Audio Subsystem) RX Macro audio codec DT bindings maintainers: - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -43,8 +46,7 @@ properties: - const: fsgen clock-output-names: - items: - - const: mclk + maxItems: 1 power-domains: maxItems: 2 @@ -59,7 +61,7 @@ required: - reg - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml index de8297b358e8..38708578ee29 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml @@ -9,6 +9,9 @@ title: LPASS(Low Power Audio Subsystem) TX Macro audio codec DT bindings maintainers: - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -43,8 +46,7 @@ properties: - const: fsgen clock-output-names: - items: - - const: mclk + maxItems: 1 power-domains: maxItems: 2 @@ -63,7 +65,7 @@ required: - reg - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml index 9f473c08cb2e..188883a2e671 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml @@ -9,6 +9,9 @@ title: LPASS(Low Power Audio Subsystem) VA Macro audio codec DT bindings maintainers: - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -39,8 +42,7 @@ properties: - const: mclk clock-output-names: - items: - - const: fsgen + maxItems: 1 power-domains: maxItems: 2 @@ -62,7 +64,7 @@ required: - reg - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml index 4959ad658eac..bebca3e3f86f 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml @@ -9,6 +9,9 @@ title: LPASS(Low Power Audio Subsystem) VA Macro audio codec DT bindings maintainers: - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -38,8 +41,7 @@ properties: - const: fsgen clock-output-names: - items: - - const: mclk + maxItems: 1 qcom,dmic-sample-rate: description: dmic sample rate @@ -53,7 +55,7 @@ required: - reg - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/qcom,q6adm-routing.yaml b/Documentation/devicetree/bindings/sound/qcom,q6adm-routing.yaml index d0f7a79e240a..3f11d2e183e1 100644 --- a/Documentation/devicetree/bindings/sound/qcom,q6adm-routing.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,q6adm-routing.yaml @@ -14,6 +14,9 @@ description: Qualcomm Audio Device Manager (Q6ADM) routing node represents routing specific configuration. +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -26,27 +29,11 @@ required: - compatible - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | - #include <dt-bindings/soc/qcom,apr.h> - #include <dt-bindings/sound/qcom,q6asm.h> - - apr { - compatible = "qcom,apr-v2"; - qcom,domain = <APR_DOMAIN_ADSP>; - #address-cells = <1>; - #size-cells = <0>; - - service@8 { - compatible = "qcom,q6adm"; - reg = <APR_SVC_ADM>; - qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; - - routing { - compatible = "qcom,q6adm-routing"; - #sound-dai-cells = <0>; - }; - }; + routing { + compatible = "qcom,q6adm-routing"; + #sound-dai-cells = <0>; }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6adm.yaml b/Documentation/devicetree/bindings/sound/qcom,q6adm.yaml new file mode 100644 index 000000000000..fe14a97ea616 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,q6adm.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,q6adm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Audio Device Manager (Q6ADM) + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +allOf: + - $ref: /schemas/soc/qcom/qcom,apr-services.yaml# + +properties: + compatible: + enum: + - qcom,q6adm + + routing: + type: object + $ref: /schemas/sound/qcom,q6adm-routing.yaml# + unevaluatedProperties: false + description: Qualcomm DSP LPASS audio routing + +required: + - compatible + - routing + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/soc/qcom,apr.h> + + apr { + #address-cells = <1>; + #size-cells = <0>; + + service@8 { + compatible = "qcom,q6adm"; + reg = <APR_SVC_ADM>; + qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; + + routing { + compatible = "qcom,q6adm-routing"; + #sound-dai-cells = <0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6afe.yaml b/Documentation/devicetree/bindings/sound/qcom,q6afe.yaml new file mode 100644 index 000000000000..297aa362aa54 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,q6afe.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,q6afe.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Audio FrontEnd (Q6AFE) + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +allOf: + - $ref: /schemas/soc/qcom/qcom,apr-services.yaml# + +properties: + compatible: + enum: + - qcom,q6afe + + clock-controller: + $ref: /schemas/sound/qcom,q6dsp-lpass-clocks.yaml# + unevaluatedProperties: false + description: Qualcomm DSP LPASS clock controller + + dais: + type: object + $ref: /schemas/sound/qcom,q6dsp-lpass-ports.yaml# + unevaluatedProperties: false + description: Qualcomm DSP audio ports + +required: + - compatible + - dais + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/soc/qcom,apr.h> + #include <dt-bindings/sound/qcom,q6afe.h> + apr { + #address-cells = <1>; + #size-cells = <0>; + + service@4 { + compatible = "qcom,q6afe"; + reg = <APR_SVC_AFE>; + qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; + + clock-controller { + compatible = "qcom,q6afe-clocks"; + #clock-cells = <2>; + }; + + dais { + compatible = "qcom,q6afe-dais"; + #address-cells = <1>; + #size-cells = <0>; + #sound-dai-cells = <1>; + + dai@22 { + reg = <QUATERNARY_MI2S_RX>; + qcom,sd-lines = <0 1 2 3>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6apm-dai.yaml b/Documentation/devicetree/bindings/sound/qcom,q6apm-dai.yaml index 24f7bf2bfd95..73a4afad5a74 100644 --- a/Documentation/devicetree/bindings/sound/qcom,q6apm-dai.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,q6apm-dai.yaml @@ -27,20 +27,7 @@ additionalProperties: false examples: - | - #include <dt-bindings/soc/qcom,gpr.h> - gpr { - compatible = "qcom,gpr"; - #address-cells = <1>; - #size-cells = <0>; - qcom,domain = <GPR_DOMAIN_ID_ADSP>; - - service@1 { - compatible = "qcom,q6apm"; - reg = <1>; - - dais { - compatible = "qcom,q6apm-dais"; - iommus = <&apps_smmu 0x1801 0x0>; - }; - }; + dais { + compatible = "qcom,q6apm-dais"; + iommus = <&apps_smmu 0x1801 0x0>; }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6apm-lpass-dais.yaml b/Documentation/devicetree/bindings/sound/qcom,q6apm-lpass-dais.yaml new file mode 100644 index 000000000000..894e653d37d7 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,q6apm-lpass-dais.yaml @@ -0,0 +1,35 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,q6apm-lpass-dais.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm DSP LPASS (Low Power Audio SubSystem) Audio Ports + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + enum: + - qcom,q6apm-lpass-dais + + '#sound-dai-cells': + const: 1 + +required: + - compatible + - '#sound-dai-cells' + +unevaluatedProperties: false + +examples: + - | + dais { + compatible = "qcom,q6apm-lpass-dais"; + #sound-dai-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6apm.yaml b/Documentation/devicetree/bindings/sound/qcom,q6apm.yaml new file mode 100644 index 000000000000..ef1965aca254 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,q6apm.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,q6apm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Audio Process Manager (Q6APM) + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +allOf: + - $ref: dai-common.yaml# + - $ref: /schemas/soc/qcom/qcom,apr-services.yaml# + +properties: + compatible: + enum: + - qcom,q6apm + + bedais: + type: object + $ref: /schemas/sound/qcom,q6apm-lpass-dais.yaml# + unevaluatedProperties: false + description: Qualcomm DSP audio ports + + dais: + type: object + $ref: /schemas/sound/qcom,q6apm-dai.yaml# + unevaluatedProperties: false + description: Qualcomm DSP audio ports + + '#sound-dai-cells': + const: 0 + +required: + - compatible + - bedais + - dais + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/soc/qcom,gpr.h> + + gpr { + #address-cells = <1>; + #size-cells = <0>; + + service@1 { + reg = <GPR_APM_MODULE_IID>; + compatible = "qcom,q6apm"; + #sound-dai-cells = <0>; + qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; + + dais { + compatible = "qcom,q6apm-dais"; + iommus = <&apps_smmu 0x1801 0x0>; + }; + + bedais { + compatible = "qcom,q6apm-lpass-dais"; + #sound-dai-cells = <1>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6asm-dais.yaml b/Documentation/devicetree/bindings/sound/qcom,q6asm-dais.yaml index 8deb8ffb143b..0110b38f6de9 100644 --- a/Documentation/devicetree/bindings/sound/qcom,q6asm-dais.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,q6asm-dais.yaml @@ -73,40 +73,24 @@ additionalProperties: false examples: - | - #include <dt-bindings/soc/qcom,apr.h> - #include <dt-bindings/sound/qcom,q6asm.h> - - apr { - compatible = "qcom,apr-v2"; - qcom,domain = <APR_DOMAIN_ADSP>; + dais { + compatible = "qcom,q6asm-dais"; + iommus = <&apps_smmu 0x1821 0x0>; #address-cells = <1>; #size-cells = <0>; + #sound-dai-cells = <1>; + + dai@0 { + reg = <0>; + }; + + dai@1 { + reg = <1>; + }; - service@7 { - compatible = "qcom,q6asm"; - reg = <APR_SVC_ASM>; - qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; - - dais { - compatible = "qcom,q6asm-dais"; - iommus = <&apps_smmu 0x1821 0x0>; - #address-cells = <1>; - #size-cells = <0>; - #sound-dai-cells = <1>; - - dai@0 { - reg = <0>; - }; - - dai@1 { - reg = <1>; - }; - - dai@2 { - reg = <2>; - is-compress-dai; - direction = <1>; - }; - }; + dai@2 { + reg = <2>; + is-compress-dai; + direction = <1>; }; }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6asm.yaml b/Documentation/devicetree/bindings/sound/qcom,q6asm.yaml new file mode 100644 index 000000000000..cb49f9667cca --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,q6asm.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,q6asm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Audio Stream Manager (Q6ASM) + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +allOf: + - $ref: /schemas/soc/qcom/qcom,apr-services.yaml# + +properties: + compatible: + enum: + - qcom,q6asm + + dais: + type: object + $ref: /schemas/sound/qcom,q6asm-dais.yaml# + unevaluatedProperties: false + description: Qualcomm DSP audio ports + +required: + - compatible + - dais + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/soc/qcom,apr.h> + + apr { + #address-cells = <1>; + #size-cells = <0>; + + service@7 { + compatible = "qcom,q6asm"; + reg = <APR_SVC_ASM>; + qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; + + dais { + compatible = "qcom,q6asm-dais"; + iommus = <&apps_smmu 0x1821 0x0>; + #address-cells = <1>; + #size-cells = <0>; + #sound-dai-cells = <1>; + + dai@0 { + reg = <0>; + }; + + dai@1 { + reg = <1>; + }; + + dai@2 { + reg = <2>; + is-compress-dai; + direction = <1>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6core.yaml b/Documentation/devicetree/bindings/sound/qcom,q6core.yaml new file mode 100644 index 000000000000..e240712de9ca --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,q6core.yaml @@ -0,0 +1,39 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,q6core.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Audio Core (Q6Core) + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +allOf: + - $ref: /schemas/soc/qcom/qcom,apr-services.yaml# + +properties: + compatible: + enum: + - qcom,q6core + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/soc/qcom,apr.h> + + apr { + #address-cells = <1>; + #size-cells = <0>; + + service@3 { + compatible = "qcom,q6core"; + reg = <APR_SVC_ADSP_CORE>; + qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-clocks.yaml b/Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-clocks.yaml index fd567d20417d..aa6c0ecba5cf 100644 --- a/Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-clocks.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-clocks.yaml @@ -35,41 +35,7 @@ additionalProperties: false examples: - | - #include <dt-bindings/soc/qcom,apr.h> - #include <dt-bindings/sound/qcom,q6afe.h> - apr { - compatible = "qcom,apr-v2"; - qcom,domain = <APR_DOMAIN_ADSP>; - #address-cells = <1>; - #size-cells = <0>; - - service@4 { - compatible = "qcom,q6afe"; - reg = <APR_SVC_AFE>; - qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; - - clock-controller { - compatible = "qcom,q6afe-clocks"; - #clock-cells = <2>; - }; - }; - }; - - - | - #include <dt-bindings/soc/qcom,gpr.h> - gpr { - compatible = "qcom,gpr"; - qcom,domain = <GPR_DOMAIN_ID_ADSP>; - #address-cells = <1>; - #size-cells = <0>; - - service@2 { - reg = <GPR_PRM_MODULE_IID>; - compatible = "qcom,q6prm"; - - clock-controller { - compatible = "qcom,q6prm-lpass-clocks"; - #clock-cells = <2>; - }; - }; + clock-controller { + compatible = "qcom,q6afe-clocks"; + #clock-cells = <2>; }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-ports.yaml b/Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-ports.yaml index e53fc0960a14..d8ebf2e528d2 100644 --- a/Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-ports.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-ports.yaml @@ -16,7 +16,6 @@ properties: compatible: enum: - qcom,q6afe-dais - - qcom,q6apm-lpass-dais '#sound-dai-cells': const: 1 @@ -150,54 +149,16 @@ additionalProperties: false examples: - | - #include <dt-bindings/soc/qcom,apr.h> - #include <dt-bindings/sound/qcom,q6afe.h> - apr { - compatible = "qcom,apr-v2"; - #address-cells = <1>; - #size-cells = <0>; - qcom,domain = <APR_DOMAIN_ADSP>; - - service@4 { - compatible = "qcom,q6afe"; - reg = <APR_SVC_AFE>; - qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; - - dais { - compatible = "qcom,q6afe-dais"; - #address-cells = <1>; - #size-cells = <0>; - #sound-dai-cells = <1>; - - dai@22 { - reg = <QUATERNARY_MI2S_RX>; - qcom,sd-lines = <0 1 2 3>; - }; - }; - }; - }; - - | - #include <dt-bindings/soc/qcom,gpr.h> - gpr { - compatible = "qcom,gpr"; + #include <dt-bindings/sound/qcom,q6dsp-lpass-ports.h> + + dais { + compatible = "qcom,q6afe-dais"; #address-cells = <1>; #size-cells = <0>; - qcom,domain = <GPR_DOMAIN_ID_ADSP>; - - service@1 { - compatible = "qcom,q6apm"; - reg = <GPR_APM_MODULE_IID>; - - dais { - compatible = "qcom,q6apm-lpass-dais"; - #address-cells = <1>; - #size-cells = <0>; - #sound-dai-cells = <1>; - - dai@22 { - reg = <QUATERNARY_MI2S_RX>; - qcom,sd-lines = <0 1 2 3>; - }; - }; + #sound-dai-cells = <1>; + + dai@22 { + reg = <QUATERNARY_MI2S_RX>; + qcom,sd-lines = <0 1 2 3>; }; }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6prm.yaml b/Documentation/devicetree/bindings/sound/qcom,q6prm.yaml new file mode 100644 index 000000000000..f6dbb1267bfe --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,q6prm.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,q6prm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Proxy Resource Manager (Q6PRM) + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +allOf: + - $ref: /schemas/soc/qcom/qcom,apr-services.yaml# + +properties: + compatible: + enum: + - qcom,q6prm + + clock-controller: + $ref: /schemas/sound/qcom,q6dsp-lpass-clocks.yaml# + unevaluatedProperties: false + description: Qualcomm DSP LPASS clock controller + +required: + - compatible + - clock-controller + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/soc/qcom,gpr.h> + + gpr { + #address-cells = <1>; + #size-cells = <0>; + + service@2 { + reg = <GPR_PRM_MODULE_IID>; + compatible = "qcom,q6prm"; + qcom,protection-domain = "avs/audio", "msm/adsp/audio_pd"; + + clock-controller { + compatible = "qcom,q6prm-lpass-clocks"; + #clock-cells = <2>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/qcom,wcd9335.txt b/Documentation/devicetree/bindings/sound/qcom,wcd9335.txt index 5d6ea66a863f..1f75feec3dec 100644 --- a/Documentation/devicetree/bindings/sound/qcom,wcd9335.txt +++ b/Documentation/devicetree/bindings/sound/qcom,wcd9335.txt @@ -109,7 +109,7 @@ audio-codec@1{ reg = <1 0>; interrupts = <&msmgpio 54 IRQ_TYPE_LEVEL_HIGH>; interrupt-names = "intr2" - reset-gpios = <&msmgpio 64 0>; + reset-gpios = <&msmgpio 64 GPIO_ACTIVE_LOW>; slim-ifc-dev = <&wc9335_ifd>; clock-names = "mclk", "native"; clocks = <&rpmcc RPM_SMD_DIV_CLK1>, diff --git a/Documentation/devicetree/bindings/sound/qcom,wcd938x.yaml b/Documentation/devicetree/bindings/sound/qcom,wcd938x.yaml index 51547190f709..67d84463eaeb 100644 --- a/Documentation/devicetree/bindings/sound/qcom,wcd938x.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,wcd938x.yaml @@ -13,6 +13,9 @@ description: | Qualcomm WCD9380/WCD9385 Codec is a standalone Hi-Fi audio codec IC. It has RX and TX Soundwire slave devices. +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -106,7 +109,7 @@ required: - qcom,micbias4-microvolt - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/qcom,wsa883x.yaml b/Documentation/devicetree/bindings/sound/qcom,wsa883x.yaml index 6113f65f2990..65b0e67f82a3 100644 --- a/Documentation/devicetree/bindings/sound/qcom,wsa883x.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,wsa883x.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: sdw10217020200 @@ -23,7 +26,7 @@ properties: maxItems: 1 powerdown-gpios: - description: GPIO spec for Powerdown/Shutdown line to use + description: GPIO spec for Powerdown/Shutdown line to use (pin SD_N) maxItems: 1 vdd-supply: @@ -43,10 +46,12 @@ required: - "#thermal-sensor-cells" - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | + #include <dt-bindings/gpio/gpio.h> + soundwire-controller@3250000 { #address-cells = <2>; #size-cells = <0>; @@ -55,19 +60,21 @@ examples: speaker@0,1 { compatible = "sdw10217020200"; reg = <0 1>; - powerdown-gpios = <&tlmm 1 0>; + powerdown-gpios = <&tlmm 1 GPIO_ACTIVE_LOW>; vdd-supply = <&vreg_s10b_1p8>; #thermal-sensor-cells = <0>; #sound-dai-cells = <0>; + sound-name-prefix = "SpkrLeft"; }; speaker@0,2 { compatible = "sdw10217020200"; reg = <0 2>; - powerdown-gpios = <&tlmm 89 0>; + powerdown-gpios = <&tlmm 89 GPIO_ACTIVE_LOW>; vdd-supply = <&vreg_s10b_1p8>; #thermal-sensor-cells = <0>; #sound-dai-cells = <0>; + sound-name-prefix = "SpkrRight"; }; }; diff --git a/Documentation/devicetree/bindings/sound/realtek,rt1015p.yaml b/Documentation/devicetree/bindings/sound/realtek,rt1015p.yaml index 1d73204451b1..ea7d4900ee4a 100644 --- a/Documentation/devicetree/bindings/sound/realtek,rt1015p.yaml +++ b/Documentation/devicetree/bindings/sound/realtek,rt1015p.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Realtek rt1015p codec devicetree bindings maintainers: - - Tzung-Bi Shih <tzungbi@google.com> + - Tzung-Bi Shih <tzungbi@kernel.org> description: | Rt1015p is a rt1015 variant which does not support I2C and diff --git a/Documentation/devicetree/bindings/sound/realtek,rt5682s.yaml b/Documentation/devicetree/bindings/sound/realtek,rt5682s.yaml index ca5b8987b749..e631ace7aad1 100644 --- a/Documentation/devicetree/bindings/sound/realtek,rt5682s.yaml +++ b/Documentation/devicetree/bindings/sound/realtek,rt5682s.yaml @@ -12,6 +12,9 @@ maintainers: description: | Rt5682s(ALC5682I-VS) is a rt5682i variant which supports I2C only. +allOf: + - $ref: dai-common.yaml# + properties: compatible: const: realtek,rt5682s @@ -87,11 +90,32 @@ properties: maxItems: 2 description: Name given for DAI word clock and bit clock outputs. -additionalProperties: false + "#sound-dai-cells": + const: 1 + + AVDD-supply: + description: Regulator supplying analog power through the AVDD pin. + + MICVDD-supply: + description: Regulator supplying power for the microphone bias through the + MICVDD pin. + + DBVDD-supply: + description: Regulator supplying I/O power through the DBVDD pin. + + LDO1-IN-supply: + description: Regulator supplying power to the digital core and charge pump + through the LDO1_IN pin. + +unevaluatedProperties: false required: - compatible - reg + - AVDD-supply + - MICVDD-supply + - DBVDD-supply + - LDO1-IN-supply examples: - | @@ -117,5 +141,10 @@ examples: clocks = <&osc>; clock-names = "mclk"; + + AVDD-supply = <&avdd_reg>; + MICVDD-supply = <&micvdd_reg>; + DBVDD-supply = <&dbvdd_reg>; + LDO1-IN-supply = <&ldo1_in_reg>; }; }; diff --git a/Documentation/devicetree/bindings/sound/renesas,fsi.yaml b/Documentation/devicetree/bindings/sound/renesas,fsi.yaml index 0dd3f7361399..df91991699a7 100644 --- a/Documentation/devicetree/bindings/sound/renesas,fsi.yaml +++ b/Documentation/devicetree/bindings/sound/renesas,fsi.yaml @@ -9,6 +9,9 @@ title: Renesas FIFO-buffered Serial Interface (FSI) maintainers: - Kuninori Morimoto <kuninori.morimoto.gx@renesas.com> +allOf: + - $ref: dai-common.yaml# + properties: $nodename: pattern: "^sound@.*" @@ -64,7 +67,7 @@ required: - power-domains - '#sound-dai-cells' -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml index 679a246dd666..cb90463c7297 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml @@ -115,7 +115,7 @@ properties: ports: $ref: /schemas/graph.yaml#/properties/ports patternProperties: - port(@[0-9a-f]+)?: + '^port(@[0-9a-f]+)?$': $ref: audio-graph-port.yaml# unevaluatedProperties: false @@ -274,6 +274,7 @@ required: - "#sound-dai-cells" allOf: + - $ref: dai-common.yaml# - if: properties: compatible: @@ -304,7 +305,7 @@ allOf: - ssi - audmapp -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml b/Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml index 0d9840375132..196881d94396 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml +++ b/Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml @@ -9,6 +9,9 @@ title: Renesas RZ/{G2L,V2L} ASoC Sound Serial Interface (SSIF-2) maintainers: - Biju Das <biju.das.jz@bp.renesas.com> +allOf: + - $ref: dai-common.yaml# + properties: compatible: items: @@ -90,7 +93,7 @@ required: - resets - '#sound-dai-cells' -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/richtek,rt9120.yaml b/Documentation/devicetree/bindings/sound/richtek,rt9120.yaml index 5655ca568240..a1242e8e0687 100644 --- a/Documentation/devicetree/bindings/sound/richtek,rt9120.yaml +++ b/Documentation/devicetree/bindings/sound/richtek,rt9120.yaml @@ -16,6 +16,9 @@ description: | applications like as TV, monitors. home entertainment, electronic music equipment. +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -42,7 +45,7 @@ required: - dvdd-supply - '#sound-dai-cells' -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/rockchip,i2s-tdm.yaml b/Documentation/devicetree/bindings/sound/rockchip,i2s-tdm.yaml index 6a7c004bef17..4c95895de75e 100644 --- a/Documentation/devicetree/bindings/sound/rockchip,i2s-tdm.yaml +++ b/Documentation/devicetree/bindings/sound/rockchip,i2s-tdm.yaml @@ -14,6 +14,9 @@ description: maintainers: - Nicolas Frattaroli <frattaroli.nicolas@gmail.com> +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -21,6 +24,7 @@ properties: - rockchip,rk1808-i2s-tdm - rockchip,rk3308-i2s-tdm - rockchip,rk3568-i2s-tdm + - rockchip,rk3588-i2s-tdm - rockchip,rv1126-i2s-tdm reg: @@ -135,10 +139,9 @@ required: - clock-names - resets - reset-names - - rockchip,grf - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/rockchip,pdm.yaml b/Documentation/devicetree/bindings/sound/rockchip,pdm.yaml index 22e1cf6c0592..ff9e400494f3 100644 --- a/Documentation/devicetree/bindings/sound/rockchip,pdm.yaml +++ b/Documentation/devicetree/bindings/sound/rockchip,pdm.yaml @@ -16,6 +16,9 @@ description: maintainers: - Heiko Stuebner <heiko@sntech.de> +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -83,7 +86,7 @@ required: - dma-names - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.yaml b/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.yaml index 75b3b33b5f1f..5cdb8bcc687b 100644 --- a/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.yaml +++ b/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.yaml @@ -8,6 +8,9 @@ title: Rockchip rk3328 internal codec maintainers: - Heiko Stuebner <heiko@sntech.de> +allOf: + - $ref: dai-common.yaml# + properties: compatible: @@ -53,7 +56,7 @@ required: - rockchip,grf - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/rockchip-i2s.yaml b/Documentation/devicetree/bindings/sound/rockchip-i2s.yaml index 7e36e389e976..1cb4da300607 100644 --- a/Documentation/devicetree/bindings/sound/rockchip-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/rockchip-i2s.yaml @@ -13,6 +13,9 @@ description: maintainers: - Heiko Stuebner <heiko@sntech.de> +allOf: + - $ref: dai-common.yaml# + properties: compatible: oneOf: @@ -111,7 +114,7 @@ required: - dma-names - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/rockchip-spdif.yaml b/Documentation/devicetree/bindings/sound/rockchip-spdif.yaml index d0a24bf928d6..4f51b2fa82db 100644 --- a/Documentation/devicetree/bindings/sound/rockchip-spdif.yaml +++ b/Documentation/devicetree/bindings/sound/rockchip-spdif.yaml @@ -75,17 +75,18 @@ required: - dma-names - "#sound-dai-cells" -if: - properties: - compatible: - contains: - const: rockchip,rk3288-spdif - -then: - required: - - rockchip,grf - -additionalProperties: false +allOf: + - $ref: dai-common.yaml# + - if: + properties: + compatible: + contains: + const: rockchip,rk3288-spdif + then: + required: + - rockchip,grf + +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/rohm,bd28623.yaml b/Documentation/devicetree/bindings/sound/rohm,bd28623.yaml index 859ce64da152..5abcf92bc484 100644 --- a/Documentation/devicetree/bindings/sound/rohm,bd28623.yaml +++ b/Documentation/devicetree/bindings/sound/rohm,bd28623.yaml @@ -14,6 +14,9 @@ description: maintainers: - Katsuhiro Suzuki <katsuhiro@katsuster.net> +allOf: + - $ref: dai-common.yaml# + properties: compatible: const: rohm,bd28623 @@ -50,7 +53,7 @@ required: - VCCP2-supply - "#sound-dai-cells" -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/rt5659.txt b/Documentation/devicetree/bindings/sound/rt5659.txt index 013f534fa059..8f3f62c0226a 100644 --- a/Documentation/devicetree/bindings/sound/rt5659.txt +++ b/Documentation/devicetree/bindings/sound/rt5659.txt @@ -42,7 +42,7 @@ Optional properties: - realtek,ldo1-en-gpios : The GPIO that controls the CODEC's LDO1_EN pin. - realtek,reset-gpios : The GPIO that controls the CODEC's RESET pin. -- sound-name-prefix: Please refer to name-prefix.yaml +- sound-name-prefix: Please refer to dai-common.yaml - ports: A Codec may have a single or multiple I2S interfaces. These interfaces on Codec side can be described under 'ports' or 'port'. diff --git a/Documentation/devicetree/bindings/sound/rt5682.txt b/Documentation/devicetree/bindings/sound/rt5682.txt index c5f2b8febcee..5e1d08de18a5 100644 --- a/Documentation/devicetree/bindings/sound/rt5682.txt +++ b/Documentation/devicetree/bindings/sound/rt5682.txt @@ -8,6 +8,21 @@ Required properties: - reg : The I2C address of the device. +- AVDD-supply: phandle to the regulator supplying analog power through the + AVDD pin + +- MICVDD-supply: phandle to the regulator supplying power for the microphone + bias through the MICVDD pin. Either MICVDD or VBAT should be present. + +- VBAT-supply: phandle to the regulator supplying battery power through the + VBAT pin. Either MICVDD or VBAT should be present. + +- DBVDD-supply: phandle to the regulator supplying I/O power through the DBVDD + pin. + +- LDO1-IN-supply: phandle to the regulator supplying power to the digital core + and charge pump through the LDO1_IN pin. + Optional properties: - interrupts : The CODEC's interrupt output. @@ -46,7 +61,7 @@ Optional properties: - realtek,dmic-clk-driving-high : Set the high driving of the DMIC clock out. -- #sound-dai-cells: Should be set to '<0>'. +- #sound-dai-cells: Should be set to '<1>'. Pins on the device (for linking into audio routes) for RT5682: @@ -75,4 +90,9 @@ rt5682 { clocks = <&osc>; clock-names = "mclk"; + + AVDD-supply = <&avdd_reg>; + MICVDD-supply = <&micvdd_reg>; + DBVDD-supply = <&dbvdd_reg>; + LDO1-IN-supply = <&ldo1_in_reg>; }; diff --git a/Documentation/devicetree/bindings/sound/samsung-i2s.yaml b/Documentation/devicetree/bindings/sound/samsung-i2s.yaml index 84c4d6cba521..8d5dcf9cd43e 100644 --- a/Documentation/devicetree/bindings/sound/samsung-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/samsung-i2s.yaml @@ -10,6 +10,9 @@ maintainers: - Krzysztof Kozlowski <krzk@kernel.org> - Sylwester Nawrocki <s.nawrocki@samsung.com> +allOf: + - $ref: dai-common.yaml# + properties: compatible: description: | @@ -124,7 +127,7 @@ required: - clocks - clock-names -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/sgtl5000.yaml b/Documentation/devicetree/bindings/sound/sgtl5000.yaml index 2bc7f00ce4a2..02059d66b084 100644 --- a/Documentation/devicetree/bindings/sound/sgtl5000.yaml +++ b/Documentation/devicetree/bindings/sound/sgtl5000.yaml @@ -9,6 +9,9 @@ title: Freescale SGTL5000 Stereo Codec maintainers: - Fabio Estevam <festevam@gmail.com> +allOf: + - $ref: dai-common.yaml# + properties: compatible: const: fsl,sgtl5000 @@ -88,7 +91,7 @@ required: - VDDA-supply - VDDIO-supply -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/simple-audio-amplifier.yaml b/Documentation/devicetree/bindings/sound/simple-audio-amplifier.yaml index 5428ba9e23a6..5db1f989d050 100644 --- a/Documentation/devicetree/bindings/sound/simple-audio-amplifier.yaml +++ b/Documentation/devicetree/bindings/sound/simple-audio-amplifier.yaml @@ -10,7 +10,7 @@ maintainers: - Jerome Brunet <jbrunet@baylibre.com> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/sound/simple-audio-mux.yaml b/Documentation/devicetree/bindings/sound/simple-audio-mux.yaml index b5fc35ee9b65..9f319caf3db7 100644 --- a/Documentation/devicetree/bindings/sound/simple-audio-mux.yaml +++ b/Documentation/devicetree/bindings/sound/simple-audio-mux.yaml @@ -14,7 +14,7 @@ description: | their input line is connected to the output line. allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/sound/snps,designware-i2s.yaml b/Documentation/devicetree/bindings/sound/snps,designware-i2s.yaml index 4b0795819064..56e623d4e168 100644 --- a/Documentation/devicetree/bindings/sound/snps,designware-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/snps,designware-i2s.yaml @@ -50,21 +50,21 @@ properties: - const: rx minItems: 1 -if: - properties: - compatible: - contains: - const: canaan,k210-i2s - -then: - properties: - "#sound-dai-cells": - const: 1 - -else: - properties: - "#sound-dai-cells": - const: 0 +allOf: + - $ref: dai-common.yaml# + - if: + properties: + compatible: + contains: + const: canaan,k210-i2s + then: + properties: + "#sound-dai-cells": + const: 1 + else: + properties: + "#sound-dai-cells": + const: 0 required: - compatible diff --git a/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml b/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml index 70f62ecd6eb2..9cf0efaed88e 100644 --- a/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml +++ b/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml @@ -9,6 +9,9 @@ title: UniPhier AIO audio system maintainers: - <alsa-devel@alsa-project.org> +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -70,7 +73,7 @@ patternProperties: $ref: audio-graph-port.yaml# unevaluatedProperties: false -additionalProperties: false +unevaluatedProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/sound/socionext,uniphier-evea.yaml b/Documentation/devicetree/bindings/sound/socionext,uniphier-evea.yaml index be6acfda9999..985277648de1 100644 --- a/Documentation/devicetree/bindings/sound/socionext,uniphier-evea.yaml +++ b/Documentation/devicetree/bindings/sound/socionext,uniphier-evea.yaml @@ -9,6 +9,9 @@ title: UniPhier EVEA SoC-internal sound codec maintainers: - <alsa-devel@alsa-project.org> +allOf: + - $ref: dai-common.yaml# + properties: compatible: const: socionext,uniphier-evea @@ -48,7 +51,7 @@ patternProperties: $ref: audio-graph-port.yaml# unevaluatedProperties: false -additionalProperties: false +unevaluatedProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/sound/st,stm32-i2s.yaml b/Documentation/devicetree/bindings/sound/st,stm32-i2s.yaml index d3966ae04ad0..a040d4d31412 100644 --- a/Documentation/devicetree/bindings/sound/st,stm32-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/st,stm32-i2s.yaml @@ -13,6 +13,9 @@ description: The SPI/I2S block supports I2S/PCM protocols when configured on I2S mode. Only some SPI instances support I2S. +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -68,7 +71,7 @@ required: - dmas - dma-names -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/st,stm32-spdifrx.yaml b/Documentation/devicetree/bindings/sound/st,stm32-spdifrx.yaml index 837e830c47ac..bc48151b9adb 100644 --- a/Documentation/devicetree/bindings/sound/st,stm32-spdifrx.yaml +++ b/Documentation/devicetree/bindings/sound/st,stm32-spdifrx.yaml @@ -13,6 +13,9 @@ description: | The SPDIFRX peripheral, is designed to receive an S/PDIF flow compliant with IEC-60958 and IEC-61937. +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -57,7 +60,7 @@ required: - dmas - dma-names -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/tas2562.yaml b/Documentation/devicetree/bindings/sound/tas2562.yaml index 30f6b029ac08..1085592cefcc 100644 --- a/Documentation/devicetree/bindings/sound/tas2562.yaml +++ b/Documentation/devicetree/bindings/sound/tas2562.yaml @@ -22,6 +22,9 @@ description: | https://www.ti.com/lit/gpn/tas2564 https://www.ti.com/lit/gpn/tas2110 +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -58,7 +61,7 @@ required: - compatible - reg -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/tas2770.yaml b/Documentation/devicetree/bindings/sound/tas2770.yaml index bc90e72bf7cf..982949ba8a4b 100644 --- a/Documentation/devicetree/bindings/sound/tas2770.yaml +++ b/Documentation/devicetree/bindings/sound/tas2770.yaml @@ -16,6 +16,9 @@ description: | Integrated speaker voltage and current sense provides for real time monitoring of loudspeaker behavior. +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -60,7 +63,7 @@ required: - compatible - reg -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/tas27xx.yaml b/Documentation/devicetree/bindings/sound/tas27xx.yaml index 66a0df8850ea..0957dd435bb4 100644 --- a/Documentation/devicetree/bindings/sound/tas27xx.yaml +++ b/Documentation/devicetree/bindings/sound/tas27xx.yaml @@ -16,6 +16,9 @@ description: | loudspeakers. Integrated speaker voltage and current sense provides for real time monitoring of loudspeaker behavior. +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -53,7 +56,7 @@ required: - compatible - reg -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/ti,src4xxx.yaml b/Documentation/devicetree/bindings/sound/ti,src4xxx.yaml index 9681b72b4918..988ce8d8028f 100644 --- a/Documentation/devicetree/bindings/sound/ti,src4xxx.yaml +++ b/Documentation/devicetree/bindings/sound/ti,src4xxx.yaml @@ -14,7 +14,7 @@ maintainers: - Matt Flax <flatmax@flatmax.com> allOf: - - $ref: name-prefix.yaml# + - $ref: dai-common.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/sound/ti,tlv320adc3xxx.yaml b/Documentation/devicetree/bindings/sound/ti,tlv320adc3xxx.yaml index 83936f594d1a..ede14ca2c07a 100644 --- a/Documentation/devicetree/bindings/sound/ti,tlv320adc3xxx.yaml +++ b/Documentation/devicetree/bindings/sound/ti,tlv320adc3xxx.yaml @@ -14,6 +14,9 @@ description: | https://www.ti.com/product/TLV320ADC3001 https://www.ti.com/product/TLV320ADC3101 +allOf: + - $ref: dai-common.yaml# + properties: compatible: enum: @@ -106,7 +109,7 @@ required: - reg - clocks -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml b/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml index ee698614862e..6b8214071115 100644 --- a/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml +++ b/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml @@ -109,38 +109,6 @@ properties: maximum: 7 default: [0, 0, 0, 0] - ti,asi-tx-drive: - type: boolean - description: | - When set the device will set the Tx ASI output to a Hi-Z state for unused - data cycles. Default is to drive the output low on unused ASI cycles. - -patternProperties: - '^ti,gpo-config-[1-4]$': - $ref: /schemas/types.yaml#/definitions/uint32-array - description: | - Defines the configuration and output driver for the general purpose - output pins (GPO). These values are pairs, the first value is for the - configuration type and the second value is for the output drive type. - The array is defined as <GPO_CFG GPO_DRV> - - GPO output configuration can be one of the following: - - 0 - (default) disabled - 1 - GPOX is configured as a general-purpose output (GPO) - 2 - GPOX is configured as a device interrupt output (IRQ) - 3 - GPOX is configured as a secondary ASI output (SDOUT2) - 4 - GPOX is configured as a PDM clock output (PDMCLK) - - GPO output drive configuration for the GPO pins can be one of the following: - - 0d - (default) Hi-Z output - 1d - Drive active low and active high - 2d - Drive active low and weak high - 3d - Drive active low and Hi-Z - 4d - Drive weak low and active high - 5d - Drive Hi-Z and active high - ti,gpio-config: description: | Defines the configuration and output drive for the General Purpose @@ -183,6 +151,38 @@ patternProperties: maximum: 15 default: [2, 2] + ti,asi-tx-drive: + type: boolean + description: | + When set the device will set the Tx ASI output to a Hi-Z state for unused + data cycles. Default is to drive the output low on unused ASI cycles. + +patternProperties: + '^ti,gpo-config-[1-4]$': + $ref: /schemas/types.yaml#/definitions/uint32-array + description: | + Defines the configuration and output driver for the general purpose + output pins (GPO). These values are pairs, the first value is for the + configuration type and the second value is for the output drive type. + The array is defined as <GPO_CFG GPO_DRV> + + GPO output configuration can be one of the following: + + 0 - (default) disabled + 1 - GPOX is configured as a general-purpose output (GPO) + 2 - GPOX is configured as a device interrupt output (IRQ) + 3 - GPOX is configured as a secondary ASI output (SDOUT2) + 4 - GPOX is configured as a PDM clock output (PDMCLK) + + GPO output drive configuration for the GPO pins can be one of the following: + + 0d - (default) Hi-Z output + 1d - Drive active low and active high + 2d - Drive active low and weak high + 3d - Drive active low and Hi-Z + 4d - Drive weak low and active high + 5d - Drive Hi-Z and active high + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/sound/wlf,arizona.yaml b/Documentation/devicetree/bindings/sound/wlf,arizona.yaml index 1627c0bb69be..8156f30eadd6 100644 --- a/Documentation/devicetree/bindings/sound/wlf,arizona.yaml +++ b/Documentation/devicetree/bindings/sound/wlf,arizona.yaml @@ -16,6 +16,9 @@ description: | This document lists sound specific bindings, see the primary binding document ../mfd/arizona.yaml +allOf: + - $ref: dai-common.yaml# + properties: '#sound-dai-cells': description: diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8731.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8731.yaml index 15795f63b5a3..858c0f689581 100644 --- a/Documentation/devicetree/bindings/sound/wlf,wm8731.yaml +++ b/Documentation/devicetree/bindings/sound/wlf,wm8731.yaml @@ -61,6 +61,7 @@ required: - DCVDD-supply allOf: + - $ref: dai-common.yaml# - $ref: /schemas/spi/spi-peripheral-props.yaml# unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8940.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8940.yaml index 7386abb3a250..3e809217c4ca 100644 --- a/Documentation/devicetree/bindings/sound/wlf,wm8940.yaml +++ b/Documentation/devicetree/bindings/sound/wlf,wm8940.yaml @@ -9,6 +9,9 @@ title: Wolfson WM8940 Codec maintainers: - patches@opensource.cirrus.com +allOf: + - $ref: dai-common.yaml# + properties: '#sound-dai-cells': const: 0 @@ -27,7 +30,7 @@ required: - compatible - reg -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8961.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8961.yaml new file mode 100644 index 000000000000..f58078545569 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/wlf,wm8961.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/wlf,wm8961.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Wolfson WM8961 Ultra-Low Power Stereo CODEC + +maintainers: + - patches@opensource.cirrus.com + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + const: wlf,wm8961 + + reg: + maxItems: 1 + + '#sound-dai-cells': + const: 0 + +required: + - compatible + - reg + - '#sound-dai-cells' + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + wm8961: codec@4a { + compatible = "wlf,wm8961"; + reg = <0x4a>; + #sound-dai-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8962.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8962.yaml index 5e172e9462b9..5fe0b2c9f99f 100644 --- a/Documentation/devicetree/bindings/sound/wlf,wm8962.yaml +++ b/Documentation/devicetree/bindings/sound/wlf,wm8962.yaml @@ -9,6 +9,9 @@ title: Wolfson WM8962 Ultra-Low Power Stereo CODEC maintainers: - patches@opensource.cirrus.com +allOf: + - $ref: dai-common.yaml# + properties: compatible: const: wlf,wm8962 @@ -87,7 +90,7 @@ required: - SPKVDD1-supply - SPKVDD2-supply -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8978.yaml b/Documentation/devicetree/bindings/sound/wlf,wm8978.yaml index 1c8985d4dd5a..efb5f9f6cc7a 100644 --- a/Documentation/devicetree/bindings/sound/wlf,wm8978.yaml +++ b/Documentation/devicetree/bindings/sound/wlf,wm8978.yaml @@ -9,6 +9,9 @@ title: Wolfson WM8978 Codec maintainers: - patches@opensource.cirrus.com +allOf: + - $ref: dai-common.yaml# + properties: '#sound-dai-cells': const: 0 @@ -27,7 +30,7 @@ required: - compatible - reg -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/zl38060.yaml b/Documentation/devicetree/bindings/sound/zl38060.yaml index 338e2a13c775..2c5c02e34573 100644 --- a/Documentation/devicetree/bindings/sound/zl38060.yaml +++ b/Documentation/devicetree/bindings/sound/zl38060.yaml @@ -15,6 +15,9 @@ maintainers: - Jaroslav Kysela <perex@perex.cz> - Takashi Iwai <tiwai@suse.com> +allOf: + - $ref: dai-common.yaml# + properties: compatible: const: mscc,zl38060 @@ -48,7 +51,7 @@ required: - gpio-controller - '#sound-dai-cells' -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml b/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml index 0c10f7678178..53eb6562b979 100644 --- a/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml +++ b/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml @@ -10,9 +10,6 @@ title: Amlogic Meson SPI Communication Controller maintainers: - Neil Armstrong <neil.armstrong@linaro.org> -allOf: - - $ref: "spi-controller.yaml#" - description: | The Meson SPICC is a generic SPI controller for general purpose Full-Duplex communications with dedicated 16 words RX/TX PIO FIFOs. @@ -43,31 +40,53 @@ properties: minItems: 1 maxItems: 2 -if: - properties: - compatible: - contains: - enum: - - amlogic,meson-g12a-spicc - -then: - properties: - clocks: - minItems: 2 - - clock-names: - items: - - const: core - - const: pclk - -else: - properties: - clocks: - maxItems: 1 - - clock-names: - items: - - const: core +allOf: + - $ref: "spi-controller.yaml#" + - if: + properties: + compatible: + contains: + enum: + - amlogic,meson-g12a-spicc + + then: + properties: + clocks: + minItems: 2 + + clock-names: + items: + - const: core + - const: pclk + + else: + properties: + clocks: + maxItems: 1 + + clock-names: + items: + - const: core + + - if: + properties: + compatible: + contains: + enum: + - amlogic,meson-gx-spicc + + then: + properties: + pinctrl-0: true + pinctrl-1: true + pinctrl-2: true + + pinctrl-names: + minItems: 1 + items: + - const: default + - const: idle-high + - const: idle-low required: - compatible diff --git a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml index 50df1a40bbe3..12cb76711000 100644 --- a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml +++ b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml @@ -23,6 +23,9 @@ properties: - const: fsl,imx51-ecspi - const: fsl,imx53-ecspi - items: + - const: fsl,imx8mp-ecspi + - const: fsl,imx6ul-ecspi + - items: - enum: - fsl,imx50-ecspi - fsl,imx6q-ecspi @@ -34,7 +37,6 @@ properties: - fsl,imx8mq-ecspi - fsl,imx8mm-ecspi - fsl,imx8mn-ecspi - - fsl,imx8mp-ecspi - const: fsl,imx51-ecspi reg: diff --git a/Documentation/devicetree/bindings/spi/nuvoton,npcm-fiu.txt b/Documentation/devicetree/bindings/spi/nuvoton,npcm-fiu.txt index c63ce4cc0a80..fb38e96d395f 100644 --- a/Documentation/devicetree/bindings/spi/nuvoton,npcm-fiu.txt +++ b/Documentation/devicetree/bindings/spi/nuvoton,npcm-fiu.txt @@ -51,7 +51,7 @@ fiu3: spi@c00000000 { clocks = <&clk NPCM7XX_CLK_AHB>; pinctrl-names = "default"; pinctrl-0 = <&spi3_pins>; - spi-nor@0 { + flash@0 { ... }; }; diff --git a/Documentation/devicetree/bindings/spi/nuvoton,wpcm450-fiu.yaml b/Documentation/devicetree/bindings/spi/nuvoton,wpcm450-fiu.yaml new file mode 100644 index 000000000000..4e0d391e1d69 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/nuvoton,wpcm450-fiu.yaml @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/nuvoton,wpcm450-fiu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nuvoton WPCM450 Flash Interface Unit (FIU) + +maintainers: + - Jonathan Neuschäfer <j.neuschaefer@gmx.net> + +allOf: + - $ref: /schemas/spi/spi-controller.yaml# + +properties: + compatible: + const: nuvoton,wpcm450-fiu + + reg: + items: + - description: FIU registers + - description: Memory-mapped flash contents + + reg-names: + items: + - const: control + - const: memory + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + nuvoton,shm: + $ref: /schemas/types.yaml#/definitions/phandle + description: a phandle to the SHM block (see ../arm/nuvoton,shm.yaml) + +required: + - compatible + - reg + - clocks + +unevaluatedProperties: false + +examples: + - | + spi@c8000000 { + compatible = "nuvoton,wpcm450-fiu"; + reg = <0xc8000000 0x1000>, <0xc0000000 0x4000000>; + #address-cells = <1>; + #size-cells = <0>; + reg-names = "control", "memory"; + clocks = <&clk 0>; + nuvoton,shm = <&shm>; + + flash@0 { + compatible = "jedec,spi-nor"; + reg = <0>; + }; + }; + + shm: syscon@c8001000 { + compatible = "nuvoton,wpcm450-shm", "syscon"; + reg = <0xc8001000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml b/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml index 6b733e5c1163..899100e783c9 100644 --- a/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml +++ b/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml @@ -48,7 +48,7 @@ properties: - const: tx patternProperties: - "@[0-9a-f]+": + "@[0-9a-f]+$": type: object properties: diff --git a/Documentation/devicetree/bindings/spi/socionext,f-ospi.yaml b/Documentation/devicetree/bindings/spi/socionext,f-ospi.yaml new file mode 100644 index 000000000000..9878d1446552 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/socionext,f-ospi.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/socionext,f-ospi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext F_OSPI controller + +description: | + The Socionext F_OSPI is a controller used to interface with flash + memories using the SPI communication interface. + +maintainers: + - Kunihiko Hayashi <hayashi.kunihiko@socionext.com> + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + const: socionext,f-ospi + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + num-cs: + minimum: 1 + maximum: 4 + +required: + - compatible + - reg + - clocks + - "#address-cells" + - "#size-cells" + +unevaluatedProperties: false + +examples: + - | + ospi0: spi@80000000 { + compatible = "socionext,f-ospi"; + reg = <0x80000000 0x1000>; + clocks = <&clks 0>; + num-cs = <1>; + #address-cells = <1>; + #size-cells = <0>; + + flash@0 { + compatible = "spansion,s25fl128s", "jedec,spi-nor"; + reg = <0>; + spi-max-frequency = <50000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/spi/socionext,synquacer-spi.yaml b/Documentation/devicetree/bindings/spi/socionext,synquacer-spi.yaml new file mode 100644 index 000000000000..45cbe744c7ff --- /dev/null +++ b/Documentation/devicetree/bindings/spi/socionext,synquacer-spi.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/socionext,synquacer-spi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Socionext SynQuacer HS-SPI Controller + +maintainers: + - Masahisa Kojima <masahisa.kojima@linaro.org> + - Jassi Brar <jaswinder.singh@linaro.org> + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + const: socionext,synquacer-spi + + reg: + maxItems: 1 + + clocks: + minItems: 1 + items: + - description: core clock + - description: rate clock + + clock-names: + minItems: 1 + items: + - const: iHCLK + - const: iPCLK + + interrupts: + items: + - description: Receive Interrupt + - description: Transmit Interrupt + - description: Fault Interrupt + + socionext,use-rtm: + type: boolean + description: Enable using "retimed clock" for RX + + socionext,set-aces: + type: boolean + description: Enable same active clock edges field to be set + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + spi@ff110000 { + compatible = "socionext,synquacer-spi"; + reg = <0xff110000 0x1000>; + interrupts = <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 161 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 162 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk_hsspi>; + clock-names = "iHCLK"; + socionext,use-rtm; + socionext,set-aces; + }; +... diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml index 8b44284d30c6..94caa2b7e241 100644 --- a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml +++ b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml @@ -56,6 +56,13 @@ properties: this property to re-config the chipselect value in the LPSPI driver. type: boolean + num-cs: + description: + number of chip selects. + minimum: 1 + maximum: 2 + default: 1 + required: - compatible - reg @@ -80,4 +87,5 @@ examples: clock-names = "per", "ipg"; spi-slave; fsl,spi-only-use-cs1-sel; + num-cs = <2>; }; diff --git a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml index dca677f9e1b9..ead2cccf658f 100644 --- a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml +++ b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml @@ -44,6 +44,11 @@ properties: description: Maximum SPI clocking speed of the device in Hz. + spi-cs-setup-ns: + description: + Delay in nanosecods to be introduced by the controller after CS is + asserted. + spi-rx-bus-width: description: Bus width to the SPI bus used for read transfers. diff --git a/Documentation/devicetree/bindings/spi/spi-synquacer.txt b/Documentation/devicetree/bindings/spi/spi-synquacer.txt deleted file mode 100644 index 291dfa692d0a..000000000000 --- a/Documentation/devicetree/bindings/spi/spi-synquacer.txt +++ /dev/null @@ -1,27 +0,0 @@ -* Socionext Synquacer HS-SPI bindings - -Required Properties: -- compatible: should be "socionext,synquacer-spi" -- reg: physical base address of the controller and length of memory mapped - region. -- interrupts: should contain the "spi_rx", "spi_tx" and "spi_fault" interrupts. -- clocks: core clock iHCLK. Optional rate clock iPCLK (default is iHCLK) -- clock-names: Shall be "iHCLK" and "iPCLK" respectively - -Optional Properties: -- socionext,use-rtm: boolean, if required to use "retimed clock" for RX -- socionext,set-aces: boolean, if same active clock edges field to be set. - -Example: - - spi0: spi@ff110000 { - compatible = "socionext,synquacer-spi"; - reg = <0xff110000 0x1000>; - interrupts = <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 161 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 162 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clk_hsspi>; - clock-names = "iHCLK"; - socionext,use-rtm; - socionext,set-aces; - }; diff --git a/Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml b/Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml index 6bf0edc57f4a..546c416cdb55 100644 --- a/Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml +++ b/Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml @@ -14,7 +14,9 @@ allOf: properties: compatible: - const: xlnx,zynqmp-qspi-1.0 + enum: + - xlnx,versal-qspi-1.0 + - xlnx,zynqmp-qspi-1.0 reg: maxItems: 2 diff --git a/Documentation/devicetree/bindings/sram/qcom,imem.yaml b/Documentation/devicetree/bindings/sram/qcom,imem.yaml index e9199190198d..665c06e14f79 100644 --- a/Documentation/devicetree/bindings/sram/qcom,imem.yaml +++ b/Documentation/devicetree/bindings/sram/qcom,imem.yaml @@ -25,6 +25,7 @@ properties: - qcom,sdm630-imem - qcom,sdm845-imem - qcom,sdx55-imem + - qcom,sdx65-imem - const: syscon - const: simple-mfd diff --git a/Documentation/devicetree/bindings/thermal/generic-adc-thermal.yaml b/Documentation/devicetree/bindings/thermal/generic-adc-thermal.yaml new file mode 100644 index 000000000000..f1fc3b0d8608 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/generic-adc-thermal.yaml @@ -0,0 +1,84 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/generic-adc-thermal.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: General Purpose Analog To Digital Converter (ADC) based thermal sensor + +maintainers: + - Laxman Dewangan <ldewangan@nvidia.com> + +description: + On some of platforms, thermal sensor like thermistors are connected to + one of ADC channel and sensor resistance is read via voltage across the + sensor resistor. The voltage read across the sensor is mapped to + temperature using voltage-temperature lookup table. + +properties: + compatible: + const: generic-adc-thermal + + '#thermal-sensor-cells': + const: 0 + + io-channels: + maxItems: 1 + + io-channel-names: + const: sensor-channel + + temperature-lookup-table: + description: | + Lookup table to map the relation between ADC value and temperature. + When ADC is read, the value is looked up on the table to get the + equivalent temperature. + + If not specified, driver assumes the ADC channel gives milliCelsius + directly. + $ref: /schemas/types.yaml#/definitions/int32-matrix + items: + items: + - description: Temperature in milliCelsius + - description: ADC read value + +required: + - compatible + - '#thermal-sensor-cells' + - io-channels + - io-channel-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/thermal/thermal.h> + + thermal-sensor { + compatible = "generic-adc-thermal"; + #thermal-sensor-cells = <0>; + io-channels = <&ads1015 1>; + io-channel-names = "sensor-channel"; + temperature-lookup-table = < + (-40000) 2578 + (-39000) 2577 + (-38000) 2576 + (-37000) 2575 + (-36000) 2574 + (-35000) 2573 + (-34000) 2572 + (-33000) 2571 + (-32000) 2569 + (-31000) 2568 + (-30000) 2567 + /* skip */ + 118000 254 + 119000 247 + 120000 240 + 121000 233 + 122000 226 + 123000 220 + 124000 214 + 125000 208>; + }; +... diff --git a/Documentation/devicetree/bindings/thermal/imx8mm-thermal.yaml b/Documentation/devicetree/bindings/thermal/imx8mm-thermal.yaml index 89c54e08ee61..b90726229ac9 100644 --- a/Documentation/devicetree/bindings/thermal/imx8mm-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/imx8mm-thermal.yaml @@ -32,6 +32,13 @@ properties: clocks: maxItems: 1 + nvmem-cells: + maxItems: 1 + description: Phandle to the calibration data provided by ocotp + + nvmem-cell-names: + const: calib + "#thermal-sensor-cells": description: | Number of cells required to uniquely identify the thermal diff --git a/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt b/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt index 5c7e7bdd029a..38b32bb447e3 100644 --- a/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt @@ -13,6 +13,8 @@ Required properties: - "mediatek,mt2701-thermal" : For MT2701 family of SoCs - "mediatek,mt2712-thermal" : For MT2712 family of SoCs - "mediatek,mt7622-thermal" : For MT7622 SoC + - "mediatek,mt7981-thermal", "mediatek,mt7986-thermal" : For MT7981 SoC + - "mediatek,mt7986-thermal" : For MT7986 SoC - "mediatek,mt8183-thermal" : For MT8183 family of SoCs - "mediatek,mt8516-thermal", "mediatek,mt2701-thermal : For MT8516 family of SoCs - reg: Address range of the thermal controller diff --git a/Documentation/devicetree/bindings/thermal/qcom-lmh.yaml b/Documentation/devicetree/bindings/thermal/qcom-lmh.yaml index e1587ddf7de3..92762efc2120 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-lmh.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-lmh.yaml @@ -37,7 +37,7 @@ properties: cpus: description: phandle of the first cpu in the LMh cluster - $ref: /schemas/types.yaml#/definitions/phandle + maxItems: 1 qcom,lmh-temp-arm-millicelsius: description: diff --git a/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml b/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml index feb390d50696..d20569b9b763 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml @@ -222,8 +222,8 @@ examples: qcom,hw-settle-time = <200>; }; - conn-therm@47 { - reg = <PM8350_ADC7_AMUX_THM4_100K_PU>; + conn-therm@147 { + reg = <PM8350_ADC7_AMUX_THM4_100K_PU(1)>; qcom,ratiometric; qcom,hw-settle-time = <200>; }; @@ -247,7 +247,7 @@ examples: conn-therm@1 { reg = <1>; - io-channels = <&pmk8350_vadc PM8350_ADC7_AMUX_THM4_100K_PU>; + io-channels = <&pmk8350_vadc PM8350_ADC7_AMUX_THM4_100K_PU(1)>; qcom,avg-samples = <2>; qcom,ratiometric; qcom,hw-settle-time-us = <200>; diff --git a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml index 038d81338fcf..0231f187b097 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml @@ -53,12 +53,19 @@ properties: - qcom,sc8280xp-tsens - qcom,sdm630-tsens - qcom,sdm845-tsens + - qcom,sm6115-tsens - qcom,sm6350-tsens - qcom,sm8150-tsens - qcom,sm8250-tsens - qcom,sm8350-tsens + - qcom,sm8450-tsens + - qcom,sm8550-tsens - const: qcom,tsens-v2 + - description: v2 of TSENS with combined interrupt + enum: + - qcom,ipq8074-tsens + reg: items: - description: TM registers @@ -66,15 +73,11 @@ properties: interrupts: minItems: 1 - items: - - description: Combined interrupt if upper or lower threshold crossed - - description: Interrupt if critical threshold crossed + maxItems: 2 interrupt-names: minItems: 1 - items: - - const: uplow - - const: critical + maxItems: 2 nvmem-cells: minItems: 1 @@ -128,22 +131,64 @@ allOf: then: properties: interrupts: - maxItems: 1 + items: + - description: Combined interrupt if upper or lower threshold crossed interrupt-names: - maxItems: 1 + items: + - const: uplow - else: + - if: + properties: + compatible: + contains: + enum: + - qcom,msm8953-tsens + - qcom,msm8996-tsens + - qcom,msm8998-tsens + - qcom,sc7180-tsens + - qcom,sc7280-tsens + - qcom,sc8180x-tsens + - qcom,sc8280xp-tsens + - qcom,sdm630-tsens + - qcom,sdm845-tsens + - qcom,sm6350-tsens + - qcom,sm8150-tsens + - qcom,sm8250-tsens + - qcom,sm8350-tsens + - qcom,sm8450-tsens + - qcom,tsens-v2 + then: properties: interrupts: - minItems: 2 + items: + - description: Combined interrupt if upper or lower threshold crossed + - description: Interrupt if critical threshold crossed interrupt-names: - minItems: 2 + items: + - const: uplow + - const: critical - if: properties: compatible: contains: enum: + - qcom,ipq8074-tsens + then: + properties: + interrupts: + items: + - description: Combined interrupt if upper, lower or critical thresholds crossed + interrupt-names: + items: + - const: combined + + - if: + properties: + compatible: + contains: + enum: + - qcom,ipq8074-tsens - qcom,tsens-v0_1 - qcom,tsens-v1 - qcom,tsens-v2 @@ -226,4 +271,19 @@ examples: #qcom,sensors = <13>; #thermal-sensor-cells = <1>; }; + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + // Example 4 (for any IPQ8074 based SoC-s): + tsens4: thermal-sensor@4a9000 { + compatible = "qcom,ipq8074-tsens"; + reg = <0x4a9000 0x1000>, + <0x4a8000 0x1000>; + + interrupts = <GIC_SPI 184 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "combined"; + + #qcom,sensors = <16>; + #thermal-sensor-cells = <1>; + }; ... diff --git a/Documentation/devicetree/bindings/thermal/rzg2l-thermal.yaml b/Documentation/devicetree/bindings/thermal/rzg2l-thermal.yaml index 1d8373397848..03f4b926e53c 100644 --- a/Documentation/devicetree/bindings/thermal/rzg2l-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/rzg2l-thermal.yaml @@ -17,7 +17,7 @@ properties: compatible: items: - enum: - - renesas,r9a07g043-tsu # RZ/G2UL + - renesas,r9a07g043-tsu # RZ/G2UL and RZ/Five - renesas,r9a07g044-tsu # RZ/G2{L,LC} - renesas,r9a07g054-tsu # RZ/V2L - const: renesas,rzg2l-tsu diff --git a/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml b/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml index 850a9841b110..7bb9327caa13 100644 --- a/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml +++ b/Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml @@ -76,9 +76,13 @@ examples: next-level-cache = <&L2_0>; L2_0: l2-cache { compatible = "cache"; + cache-unified; + cache-level = <2>; next-level-cache = <&L3_0>; L3_0: l3-cache { compatible = "cache"; + cache-unified; + cache-level = <3>; }; }; }; diff --git a/Documentation/devicetree/bindings/thermal/thermal-generic-adc.txt b/Documentation/devicetree/bindings/thermal/thermal-generic-adc.txt deleted file mode 100644 index e136946a2f4f..000000000000 --- a/Documentation/devicetree/bindings/thermal/thermal-generic-adc.txt +++ /dev/null @@ -1,95 +0,0 @@ -General Purpose Analog To Digital Converter (ADC) based thermal sensor. - -On some of platforms, thermal sensor like thermistors are connected to -one of ADC channel and sensor resistance is read via voltage across the -sensor resistor. The voltage read across the sensor is mapped to -temperature using voltage-temperature lookup table. - -Required properties: -=================== -- compatible: Must be "generic-adc-thermal". -- #thermal-sensor-cells: Should be 1. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for a description - of this property. -Optional properties: -=================== -- temperature-lookup-table: Two dimensional array of Integer; lookup table - to map the relation between ADC value and - temperature. When ADC is read, the value is - looked up on the table to get the equivalent - temperature. - - The first value of the each row of array is the - temperature in milliCelsius and second value of - the each row of array is the ADC read value. - - If not specified, driver assumes the ADC channel - gives milliCelsius directly. - -Example : -#include <dt-bindings/thermal/thermal.h> - -i2c@7000c400 { - ads1015: ads1015@4a { - reg = <0x4a>; - compatible = "ads1015"; - sampling-frequency = <3300>; - #io-channel-cells = <1>; - }; -}; - -tboard_thermistor: thermal-sensor { - compatible = "generic-adc-thermal"; - #thermal-sensor-cells = <0>; - io-channels = <&ads1015 1>; - io-channel-names = "sensor-channel"; - temperature-lookup-table = < (-40000) 2578 - (-39000) 2577 - (-38000) 2576 - (-37000) 2575 - (-36000) 2574 - (-35000) 2573 - (-34000) 2572 - (-33000) 2571 - (-32000) 2569 - (-31000) 2568 - (-30000) 2567 - :::::::::: - 118000 254 - 119000 247 - 120000 240 - 121000 233 - 122000 226 - 123000 220 - 124000 214 - 125000 208>; -}; - -dummy_cool_dev: dummy-cool-dev { - compatible = "dummy-cooling-dev"; - #cooling-cells = <2>; /* min followed by max */ -}; - -thermal-zones { - Tboard { - polling-delay = <15000>; /* milliseconds */ - polling-delay-passive = <0>; /* milliseconds */ - thermal-sensors = <&tboard_thermistor>; - - trips { - therm_est_trip: therm_est_trip { - temperature = <40000>; - type = "active"; - hysteresis = <1000>; - }; - }; - - cooling-maps { - map0 { - trip = <&therm_est_trip>; - cooling-device = <&dummy_cool_dev THERMAL_NO_LIMIT THERMAL_NO_LIMIT>; - contribution = <100>; - }; - - }; - }; -}; diff --git a/Documentation/devicetree/bindings/thermal/thermal-idle.yaml b/Documentation/devicetree/bindings/thermal/thermal-idle.yaml index cc938d7ad1f3..0fd6d9ae6196 100644 --- a/Documentation/devicetree/bindings/thermal/thermal-idle.yaml +++ b/Documentation/devicetree/bindings/thermal/thermal-idle.yaml @@ -48,99 +48,105 @@ additionalProperties: false examples: - | - #include <dt-bindings/thermal/thermal.h> + /{ + #include <dt-bindings/thermal/thermal.h> - // Example: Combining idle cooling device on big CPUs with cpufreq cooling device - cpus { + compatible = "foo"; + model = "foo"; + #address-cells = <1>; + #size-cells = <1>; + + // Example: Combining idle cooling device on big CPUs with cpufreq cooling device + cpus { #address-cells = <2>; #size-cells = <0>; /* ... */ - cpu_b0: cpu@100 { - device_type = "cpu"; - compatible = "arm,cortex-a72"; - reg = <0x0 0x100>; - enable-method = "psci"; - capacity-dmips-mhz = <1024>; - dynamic-power-coefficient = <436>; - #cooling-cells = <2>; /* min followed by max */ - cpu-idle-states = <&CPU_SLEEP>, <&CLUSTER_SLEEP>; - thermal-idle { - #cooling-cells = <2>; - duration-us = <10000>; - exit-latency-us = <500>; - }; + cpu_b0: cpu@100 { + device_type = "cpu"; + compatible = "arm,cortex-a72"; + reg = <0x0 0x100>; + enable-method = "psci"; + capacity-dmips-mhz = <1024>; + dynamic-power-coefficient = <436>; + #cooling-cells = <2>; /* min followed by max */ + cpu-idle-states = <&CPU_SLEEP>, <&CLUSTER_SLEEP>; + cpu_b0_therm: thermal-idle { + #cooling-cells = <2>; + duration-us = <10000>; + exit-latency-us = <500>; + }; + }; + + cpu_b1: cpu@101 { + device_type = "cpu"; + compatible = "arm,cortex-a72"; + reg = <0x0 0x101>; + enable-method = "psci"; + capacity-dmips-mhz = <1024>; + dynamic-power-coefficient = <436>; + #cooling-cells = <2>; /* min followed by max */ + cpu-idle-states = <&CPU_SLEEP>, <&CLUSTER_SLEEP>; + cpu_b1_therm: thermal-idle { + #cooling-cells = <2>; + duration-us = <10000>; + exit-latency-us = <500>; }; + }; - cpu_b1: cpu@101 { - device_type = "cpu"; - compatible = "arm,cortex-a72"; - reg = <0x0 0x101>; - enable-method = "psci"; - capacity-dmips-mhz = <1024>; - dynamic-power-coefficient = <436>; - #cooling-cells = <2>; /* min followed by max */ - cpu-idle-states = <&CPU_SLEEP>, <&CLUSTER_SLEEP>; - thermal-idle { - #cooling-cells = <2>; - duration-us = <10000>; - exit-latency-us = <500>; - }; - }; - - /* ... */ + /* ... */ - }; + }; - /* ... */ + /* ... */ - thermal_zones { - cpu_thermal: cpu { + thermal_zones { + cpu_thermal: cpu { polling-delay-passive = <100>; polling-delay = <1000>; /* ... */ trips { - cpu_alert0: cpu_alert0 { - temperature = <65000>; - hysteresis = <2000>; - type = "passive"; - }; - - cpu_alert1: cpu_alert1 { - temperature = <70000>; - hysteresis = <2000>; - type = "passive"; - }; - - cpu_alert2: cpu_alert2 { - temperature = <75000>; - hysteresis = <2000>; - type = "passive"; - }; - - cpu_crit: cpu_crit { - temperature = <95000>; - hysteresis = <2000>; - type = "critical"; - }; + cpu_alert0: cpu_alert0 { + temperature = <65000>; + hysteresis = <2000>; + type = "passive"; + }; + + cpu_alert1: cpu_alert1 { + temperature = <70000>; + hysteresis = <2000>; + type = "passive"; + }; + + cpu_alert2: cpu_alert2 { + temperature = <75000>; + hysteresis = <2000>; + type = "passive"; + }; + + cpu_crit: cpu_crit { + temperature = <95000>; + hysteresis = <2000>; + type = "critical"; + }; }; cooling-maps { - map0 { - trip = <&cpu_alert1>; - cooling-device = <&{/cpus/cpu@100/thermal-idle} 0 15 >, - <&{/cpus/cpu@101/thermal-idle} 0 15>; - }; - - map1 { - trip = <&cpu_alert2>; - cooling-device = - <&cpu_b0 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>, - <&cpu_b1 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>; - }; + map0 { + trip = <&cpu_alert1>; + cooling-device = <&cpu_b0_therm 0 15 >, + <&cpu_b1_therm 0 15>; + }; + + map1 { + trip = <&cpu_alert2>; + cooling-device = <&cpu_b0 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>, + <&cpu_b1 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>; + }; }; - }; + }; + }; }; diff --git a/Documentation/devicetree/bindings/thermal/ti,j72xx-thermal.yaml b/Documentation/devicetree/bindings/thermal/ti,j72xx-thermal.yaml index c74f124ebfc0..0509c9cec224 100644 --- a/Documentation/devicetree/bindings/thermal/ti,j72xx-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/ti,j72xx-thermal.yaml @@ -9,6 +9,19 @@ title: Texas Instruments J72XX VTM (DTS) binding maintainers: - Keerthy <j-keerthy@ti.com> +description: | + The TI K3 family of SoCs typically have a Voltage & Thermal + Management (VTM) device to control up to 8 temperature diode + sensors to measure silicon junction temperatures from different + hotspots of the chip as well as provide temperature, interrupt + and alerting information. + + The following polynomial equation can then be used to convert + value returned by this device into a temperature in Celsius + + Temp(C) = (-9.2627e-12) * x^4 + (6.0373e-08) * x^3 + \ + (-1.7058e-04) * x^2 + (3.2512e-01) * x + (-4.9003e+01) + properties: compatible: enum: @@ -19,7 +32,12 @@ properties: items: - description: VTM cfg1 register space - description: VTM cfg2 register space - - description: VTM efuse register space + - description: | + A software trimming method must be applied to some Jacinto + devices to function properly. This eFuse region provides + the information needed for these SoCs to report + temperatures accurately. + minItems: 2 power-domains: maxItems: 1 @@ -27,6 +45,21 @@ properties: "#thermal-sensor-cells": const: 1 +allOf: + - if: + properties: + compatible: + contains: + const: ti,j721e-vtm + then: + properties: + reg: + minItems: 3 + else: + properties: + reg: + maxItems: 2 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/timer/fsl,imxgpt.yaml b/Documentation/devicetree/bindings/timer/fsl,imxgpt.yaml index a4f51f46b7a1..716c6afcca1f 100644 --- a/Documentation/devicetree/bindings/timer/fsl,imxgpt.yaml +++ b/Documentation/devicetree/bindings/timer/fsl,imxgpt.yaml @@ -31,6 +31,8 @@ properties: - enum: - fsl,imx6sl-gpt - fsl,imx6sx-gpt + - fsl,imxrt1050-gpt + - fsl,imxrt1170-gpt - const: fsl,imx6dl-gpt reg: diff --git a/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.yaml b/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.yaml index 737af78ad70c..d53e1bb98b8a 100644 --- a/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.yaml +++ b/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.yaml @@ -25,7 +25,13 @@ properties: - description: The timer interrupt of timer 0 clocks: - maxItems: 1 + items: + - description: The reference clock for timer 0 + - description: The reference clock for timer 1 + - description: The reference clock for timer 2 + - description: The reference clock for timer 3 + - description: The reference clock for timer 4 + minItems: 1 required: - compatible diff --git a/Documentation/devicetree/bindings/timer/renesas,cmt.yaml b/Documentation/devicetree/bindings/timer/renesas,cmt.yaml index bde6c9b66bf4..a0be1755ea28 100644 --- a/Documentation/devicetree/bindings/timer/renesas,cmt.yaml +++ b/Documentation/devicetree/bindings/timer/renesas,cmt.yaml @@ -102,12 +102,14 @@ properties: - enum: - renesas,r8a779a0-cmt0 # 32-bit CMT0 on R-Car V3U - renesas,r8a779f0-cmt0 # 32-bit CMT0 on R-Car S4-8 + - renesas,r8a779g0-cmt0 # 32-bit CMT0 on R-Car V4H - const: renesas,rcar-gen4-cmt0 # 32-bit CMT0 on R-Car Gen4 - items: - enum: - renesas,r8a779a0-cmt1 # 48-bit CMT on R-Car V3U - renesas,r8a779f0-cmt1 # 48-bit CMT on R-Car S4-8 + - renesas,r8a779g0-cmt1 # 48-bit CMT on R-Car V4H - const: renesas,rcar-gen4-cmt1 # 48-bit CMT on R-Car Gen4 reg: diff --git a/Documentation/devicetree/bindings/timer/renesas,tmu.yaml b/Documentation/devicetree/bindings/timer/renesas,tmu.yaml index 60f4c059bcff..a67e427a9e7e 100644 --- a/Documentation/devicetree/bindings/timer/renesas,tmu.yaml +++ b/Documentation/devicetree/bindings/timer/renesas,tmu.yaml @@ -38,6 +38,7 @@ properties: - renesas,tmu-r8a77995 # R-Car D3 - renesas,tmu-r8a779a0 # R-Car V3U - renesas,tmu-r8a779f0 # R-Car S4-8 + - renesas,tmu-r8a779g0 # R-Car V4H - const: renesas,tmu reg: diff --git a/Documentation/devicetree/bindings/timer/rockchip,rk-timer.yaml b/Documentation/devicetree/bindings/timer/rockchip,rk-timer.yaml index dc3bc1e62fe9..b61ed1a431bb 100644 --- a/Documentation/devicetree/bindings/timer/rockchip,rk-timer.yaml +++ b/Documentation/devicetree/bindings/timer/rockchip,rk-timer.yaml @@ -18,6 +18,7 @@ properties: - enum: - rockchip,rv1108-timer - rockchip,rk3036-timer + - rockchip,rk3128-timer - rockchip,rk3188-timer - rockchip,rk3228-timer - rockchip,rk3229-timer diff --git a/Documentation/devicetree/bindings/ufs/cdns,ufshc.yaml b/Documentation/devicetree/bindings/ufs/cdns,ufshc.yaml index fb45f66d6454..835e17269d2d 100644 --- a/Documentation/devicetree/bindings/ufs/cdns,ufshc.yaml +++ b/Documentation/devicetree/bindings/ufs/cdns,ufshc.yaml @@ -49,6 +49,8 @@ properties: reg: maxItems: 1 + dma-coherent: true + required: - compatible - clocks diff --git a/Documentation/devicetree/bindings/usb/generic-ehci.yaml b/Documentation/devicetree/bindings/usb/generic-ehci.yaml index c5f629c5bc61..994818cb6044 100644 --- a/Documentation/devicetree/bindings/usb/generic-ehci.yaml +++ b/Documentation/devicetree/bindings/usb/generic-ehci.yaml @@ -30,6 +30,7 @@ properties: - allwinner,sun4i-a10-ehci - allwinner,sun50i-a64-ehci - allwinner,sun50i-h6-ehci + - allwinner,sun50i-h616-ehci - allwinner,sun5i-a13-ehci - allwinner,sun6i-a31-ehci - allwinner,sun7i-a20-ehci diff --git a/Documentation/devicetree/bindings/usb/generic-ohci.yaml b/Documentation/devicetree/bindings/usb/generic-ohci.yaml index f838f78d6164..4fcbd0add49d 100644 --- a/Documentation/devicetree/bindings/usb/generic-ohci.yaml +++ b/Documentation/devicetree/bindings/usb/generic-ohci.yaml @@ -20,6 +20,7 @@ properties: - allwinner,sun4i-a10-ohci - allwinner,sun50i-a64-ohci - allwinner,sun50i-h6-ohci + - allwinner,sun50i-h616-ohci - allwinner,sun5i-a13-ohci - allwinner,sun6i-a31-ohci - allwinner,sun7i-a20-ohci diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra124-xusb.txt b/Documentation/devicetree/bindings/usb/nvidia,tegra124-xusb.txt deleted file mode 100644 index 5bfcc0b4d6b9..000000000000 --- a/Documentation/devicetree/bindings/usb/nvidia,tegra124-xusb.txt +++ /dev/null @@ -1,132 +0,0 @@ -NVIDIA Tegra xHCI controller -============================ - -The Tegra xHCI controller supports both USB2 and USB3 interfaces exposed by -the Tegra XUSB pad controller. - -Required properties: --------------------- -- compatible: Must be: - - Tegra124: "nvidia,tegra124-xusb" - - Tegra132: "nvidia,tegra132-xusb", "nvidia,tegra124-xusb" - - Tegra210: "nvidia,tegra210-xusb" - - Tegra186: "nvidia,tegra186-xusb" -- reg: Must contain the base and length of the xHCI host registers, XUSB FPCI - registers and XUSB IPFS registers. -- reg-names: Must contain the following entries: - - "hcd" - - "fpci" - - "ipfs" -- interrupts: Must contain the xHCI host interrupt and the mailbox interrupt. -- clocks: Must contain an entry for each entry in clock-names. - See ../clock/clock-bindings.txt for details. -- clock-names: Must include the following entries: - - xusb_host - - xusb_host_src - - xusb_falcon_src - - xusb_ss - - xusb_ss_src - - xusb_ss_div2 - - xusb_hs_src - - xusb_fs_src - - pll_u_480m - - clk_m - - pll_e -- resets: Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names: Must include the following entries: - - xusb_host - - xusb_ss - - xusb_src - Note that xusb_src is the shared reset for xusb_{ss,hs,fs,falcon,host}_src. -- nvidia,xusb-padctl: phandle to the XUSB pad controller that is used to - configure the USB pads used by the XHCI controller - -For Tegra124 and Tegra132: -- avddio-pex-supply: PCIe/USB3 analog logic power supply. Must supply 1.05 V. -- dvddio-pex-supply: PCIe/USB3 digital logic power supply. Must supply 1.05 V. -- avdd-usb-supply: USB controller power supply. Must supply 3.3 V. -- avdd-pll-utmip-supply: UTMI PLL power supply. Must supply 1.8 V. -- avdd-pll-erefe-supply: PLLE reference PLL power supply. Must supply 1.05 V. -- avdd-usb-ss-pll-supply: PCIe/USB3 PLL power supply. Must supply 1.05 V. -- hvdd-usb-ss-supply: High-voltage PCIe/USB3 power supply. Must supply 3.3 V. -- hvdd-usb-ss-pll-e-supply: High-voltage PLLE power supply. Must supply 3.3 V. - -For Tegra210: -- dvddio-pex-supply: PCIe/USB3 analog logic power supply. Must supply 1.05 V. -- hvddio-pex-supply: High-voltage PCIe/USB3 power supply. Must supply 1.8 V. -- avdd-usb-supply: USB controller power supply. Must supply 3.3 V. -- avdd-pll-utmip-supply: UTMI PLL power supply. Must supply 1.8 V. -- avdd-pll-uerefe-supply: PLLE reference PLL power supply. Must supply 1.05 V. -- dvdd-pex-pll-supply: PCIe/USB3 PLL power supply. Must supply 1.05 V. -- hvdd-pex-pll-e-supply: High-voltage PLLE power supply. Must supply 1.8 V. - -For Tegra210 and Tegra186: -- power-domains: A list of PM domain specifiers that reference each power-domain - used by the xHCI controller. This list must comprise of a specifier for the - XUSBA and XUSBC power-domains. See ../power/power_domain.txt and - ../arm/tegra/nvidia,tegra20-pmc.txt for details. -- power-domain-names: A list of names that represent each of the specifiers in - the 'power-domains' property. Must include 'xusb_ss' and 'xusb_host' which - represent the power-domains XUSBA and XUSBC, respectively. See - ../power/power_domain.txt for details. - -Optional properties: --------------------- -- phys: Must contain an entry for each entry in phy-names. - See ../phy/phy-bindings.txt for details. -- phy-names: Should include an entry for each PHY used by the controller. The - following PHYs are available: - - Tegra124: usb2-0, usb2-1, usb2-2, hsic-0, hsic-1, usb3-0, usb3-1 - - Tegra132: usb2-0, usb2-1, usb2-2, hsic-0, hsic-1, usb3-0, usb3-1 - - Tegra210: usb2-0, usb2-1, usb2-2, usb2-3, hsic-0, usb3-0, usb3-1, usb3-2, - usb3-3 - - Tegra186: usb2-0, usb2-1, usb2-2, hsic-0, usb3-0, usb3-1, usb3-2 - -Example: --------- - - usb@0,70090000 { - compatible = "nvidia,tegra124-xusb"; - reg = <0x0 0x70090000 0x0 0x8000>, - <0x0 0x70098000 0x0 0x1000>, - <0x0 0x70099000 0x0 0x1000>; - reg-names = "hcd", "fpci", "ipfs"; - - interrupts = <GIC_SPI 39 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 40 IRQ_TYPE_LEVEL_HIGH>; - - clocks = <&tegra_car TEGRA124_CLK_XUSB_HOST>, - <&tegra_car TEGRA124_CLK_XUSB_HOST_SRC>, - <&tegra_car TEGRA124_CLK_XUSB_FALCON_SRC>, - <&tegra_car TEGRA124_CLK_XUSB_SS>, - <&tegra_car TEGRA124_CLK_XUSB_SS_DIV2>, - <&tegra_car TEGRA124_CLK_XUSB_SS_SRC>, - <&tegra_car TEGRA124_CLK_XUSB_HS_SRC>, - <&tegra_car TEGRA124_CLK_XUSB_FS_SRC>, - <&tegra_car TEGRA124_CLK_PLL_U_480M>, - <&tegra_car TEGRA124_CLK_CLK_M>, - <&tegra_car TEGRA124_CLK_PLL_E>; - clock-names = "xusb_host", "xusb_host_src", "xusb_falcon_src", - "xusb_ss", "xusb_ss_div2", "xusb_ss_src", - "xusb_hs_src", "xusb_fs_src", "pll_u_480m", - "clk_m", "pll_e"; - resets = <&tegra_car 89>, <&tegra_car 156>, <&tegra_car 143>; - reset-names = "xusb_host", "xusb_ss", "xusb_src"; - - nvidia,xusb-padctl = <&padctl>; - - phys = <&{/padctl@0,7009f000/pads/usb2/lanes/usb2-1}>, /* mini-PCIe USB */ - <&{/padctl@0,7009f000/pads/usb2/lanes/usb2-2}>, /* USB A */ - <&{/padctl@0,7009f000/pads/pcie/lanes/pcie-0}>; /* USB A */ - phy-names = "usb2-1", "usb2-2", "usb3-0"; - - avddio-pex-supply = <&vdd_1v05_run>; - dvddio-pex-supply = <&vdd_1v05_run>; - avdd-usb-supply = <&vdd_3v3_lp0>; - avdd-pll-utmip-supply = <&vddio_1v8>; - avdd-pll-erefe-supply = <&avdd_1v05_run>; - avdd-usb-ss-pll-supply = <&vdd_1v05_run>; - hvdd-usb-ss-supply = <&vdd_3v3_lp0>; - hvdd-usb-ss-pll-e-supply = <&vdd_3v3_lp0>; - }; diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra124-xusb.yaml b/Documentation/devicetree/bindings/usb/nvidia,tegra124-xusb.yaml new file mode 100644 index 000000000000..4a6616bf9bab --- /dev/null +++ b/Documentation/devicetree/bindings/usb/nvidia,tegra124-xusb.yaml @@ -0,0 +1,202 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/nvidia,tegra124-xusb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra124 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. + +properties: + # required + compatible: + oneOf: + - description: NVIDIA Tegra124 + const: nvidia,tegra124-xusb + + - description: NVIDIA Tegra132 + items: + - const: nvidia,tegra132-xusb + - const: nvidia,tegra124-xusb + + reg: + items: + - description: base and length of the xHCI host registers + - description: base and length of the XUSB FPCI registers + - description: base and length of the XUSB IPFS registers + + reg-names: + items: + - const: hcd + - const: fpci + - const: ipfs + + interrupts: + items: + - description: xHCI host interrupt + - description: mailbox interrupt + + clocks: + items: + - description: XUSB host clock + - description: XUSB host source clock + - description: XUSB Falcon source clock + - description: XUSB SuperSpeed clock + - description: XUSB SuperSpeed clock divider + - 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_host_src + - const: xusb_falcon_src + - const: xusb_ss + - const: xusb_ss_div2 + - const: xusb_ss_src + - const: xusb_hs_src + - const: xusb_fs_src + - const: pll_u_480m + - const: clk_m + - const: pll_e + + resets: + items: + - description: reset for the XUSB host controller + - description: reset for the SuperSpeed logic + - description: shared reset for xusb_{ss,hs,fs,falcon,host}_src. + + reset-names: + items: + - const: xusb_host + - const: xusb_ss + - const: xusb_src + + 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 + + # optional + phys: + minItems: 1 + maxItems: 7 + + phy-names: + minItems: 1 + maxItems: 7 + items: + enum: + - usb2-0 + - usb2-1 + - usb2-2 + - hsic-0 + - hsic-1 + - usb3-0 + - usb3-1 + + avddio-pex-supply: + description: PCIe/USB3 analog logic power supply. Must supply 1.05 V. + + dvddio-pex-supply: + description: PCIe/USB3 digital logic power supply. Must supply 1.05 V. + + avdd-usb-supply: + description: USB controller power supply. Must supply 3.3 V. + + avdd-pll-utmip-supply: + description: UTMI PLL power supply. Must supply 1.8 V. + + avdd-pll-erefe-supply: + description: PLLE reference PLL power supply. Must supply 1.05 V. + + avdd-usb-ss-pll-supply: + description: PCIe/USB3 PLL power supply. Must supply 1.05 V. + + hvdd-usb-ss-supply: + description: High-voltage PCIe/USB3 power supply. Must supply 3.3 V. + + hvdd-usb-ss-pll-e-supply: + description: High-voltage PLLE power supply. Must supply 3.3 V. + +allOf: + - $ref: usb-xhci.yaml + +unevaluatedProperties: false + +required: + - compatible + - reg + - reg-names + - interrupts + - clocks + - clock-names + - resets + - reset-names + - nvidia,xusb-padctl + - phys + - phy-names + - avddio-pex-supply + - dvddio-pex-supply + - avdd-usb-supply + - hvdd-usb-ss-supply + +examples: + - | + #include <dt-bindings/clock/tegra124-car.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + usb@70090000 { + compatible = "nvidia,tegra124-xusb"; + reg = <0x70090000 0x8000>, + <0x70098000 0x1000>, + <0x70099000 0x1000>; + reg-names = "hcd", "fpci", "ipfs"; + + interrupts = <GIC_SPI 39 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 40 IRQ_TYPE_LEVEL_HIGH>; + + clocks = <&tegra_car TEGRA124_CLK_XUSB_HOST>, + <&tegra_car TEGRA124_CLK_XUSB_HOST_SRC>, + <&tegra_car TEGRA124_CLK_XUSB_FALCON_SRC>, + <&tegra_car TEGRA124_CLK_XUSB_SS>, + <&tegra_car TEGRA124_CLK_XUSB_SS_DIV2>, + <&tegra_car TEGRA124_CLK_XUSB_SS_SRC>, + <&tegra_car TEGRA124_CLK_XUSB_HS_SRC>, + <&tegra_car TEGRA124_CLK_XUSB_FS_SRC>, + <&tegra_car TEGRA124_CLK_PLL_U_480M>, + <&tegra_car TEGRA124_CLK_CLK_M>, + <&tegra_car TEGRA124_CLK_PLL_E>; + clock-names = "xusb_host", "xusb_host_src", "xusb_falcon_src", + "xusb_ss", "xusb_ss_div2", "xusb_ss_src", + "xusb_hs_src", "xusb_fs_src", "pll_u_480m", + "clk_m", "pll_e"; + resets = <&tegra_car 89>, <&tegra_car 156>, <&tegra_car 143>; + reset-names = "xusb_host", "xusb_ss", "xusb_src"; + + nvidia,xusb-padctl = <&padctl>; + + phys = <&{/padctl@0,7009f000/pads/usb2/lanes/usb2-1}>, /* mini-PCIe USB */ + <&{/padctl@0,7009f000/pads/usb2/lanes/usb2-2}>, /* USB A */ + <&{/padctl@0,7009f000/pads/pcie/lanes/pcie-0}>; /* USB A */ + phy-names = "usb2-1", "usb2-2", "usb3-0"; + + avddio-pex-supply = <&vdd_1v05_run>; + dvddio-pex-supply = <&vdd_1v05_run>; + avdd-usb-supply = <&vdd_3v3_lp0>; + avdd-pll-utmip-supply = <&vddio_1v8>; + avdd-pll-erefe-supply = <&avdd_1v05_run>; + avdd-usb-ss-pll-supply = <&vdd_1v05_run>; + hvdd-usb-ss-supply = <&vdd_3v3_lp0>; + hvdd-usb-ss-pll-e-supply = <&vdd_3v3_lp0>; + }; diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra186-xusb.yaml b/Documentation/devicetree/bindings/usb/nvidia,tegra186-xusb.yaml new file mode 100644 index 000000000000..6f62944fc597 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/nvidia,tegra186-xusb.yaml @@ -0,0 +1,173 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/nvidia,tegra186-xusb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra186 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. + +properties: + compatible: + const: nvidia,tegra186-xusb + + reg: + items: + - description: base and length of the xHCI host registers + - description: base and length of the XUSB FPCI registers + + reg-names: + items: + - const: hcd + - const: fpci + + 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: 7 + + phy-names: + minItems: 1 + maxItems: 7 + items: + enum: + - usb2-0 + - usb2-1 + - usb2-2 + - hsic-0 + - usb3-0 + - usb3-1 + - usb3-2 + + 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 + + dvddio-pex-supply: + description: PCIe/USB3 analog logic power supply. Must supply 1.05 V. + + hvddio-pex-supply: + description: High-voltage PCIe/USB3 power supply. Must supply 1.8 V. + + avdd-usb-supply: + description: USB controller power supply. Must supply 3.3 V. + + avdd-pll-utmip-supply: + description: UTMI PLL power supply. Must supply 1.8 V. + + avdd-pll-uerefe-supply: + description: PLLE reference PLL power supply. Must supply 1.05 V. + + dvdd-usb-ss-pll-supply: + description: PCIe/USB3 PLL power supply. Must supply 1.05 V. + + hvdd-usb-ss-pll-e-supply: + description: High-voltage PLLE power supply. Must supply 1.8 V. + +allOf: + - $ref: usb-xhci.yaml + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/tegra186-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/memory/tegra186-mc.h> + #include <dt-bindings/power/tegra186-powergate.h> + #include <dt-bindings/reset/tegra186-reset.h> + + usb@3530000 { + compatible = "nvidia,tegra186-xusb"; + reg = <0x03530000 0x8000>, + <0x03538000 0x1000>; + reg-names = "hcd", "fpci"; + interrupts = <GIC_SPI 163 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 164 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&bpmp TEGRA186_CLK_XUSB_HOST>, + <&bpmp TEGRA186_CLK_XUSB_FALCON>, + <&bpmp TEGRA186_CLK_XUSB_SS>, + <&bpmp TEGRA186_CLK_XUSB_CORE_SS>, + <&bpmp TEGRA186_CLK_CLK_M>, + <&bpmp TEGRA186_CLK_XUSB_FS>, + <&bpmp TEGRA186_CLK_PLLU>, + <&bpmp TEGRA186_CLK_CLK_M>, + <&bpmp TEGRA186_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"; + power-domains = <&bpmp TEGRA186_POWER_DOMAIN_XUSBC>, + <&bpmp TEGRA186_POWER_DOMAIN_XUSBA>; + power-domain-names = "xusb_host", "xusb_ss"; + interconnects = <&mc TEGRA186_MEMORY_CLIENT_XUSB_HOSTR &emc>, + <&mc TEGRA186_MEMORY_CLIENT_XUSB_HOSTW &emc>; + interconnect-names = "dma-mem", "write"; + iommus = <&smmu TEGRA186_SID_XUSB_HOST>; + nvidia,xusb-padctl = <&padctl>; + + #address-cells = <1>; + #size-cells = <0>; + + phys = <&{/padctl@3520000/pads/usb2/lanes/usb2-0}>, + <&{/padctl@3520000/pads/usb2/lanes/usb2-1}>, + <&{/padctl@3520000/pads/usb3/lanes/usb3-0}>; + phy-names = "usb2-0", "usb2-1", "usb3-0"; + }; diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra194-xusb.yaml b/Documentation/devicetree/bindings/usb/nvidia,tegra194-xusb.yaml new file mode 100644 index 000000000000..65ae9ae9b0b7 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/nvidia,tegra194-xusb.yaml @@ -0,0 +1,179 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/nvidia,tegra194-xusb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra194 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. + +properties: + compatible: + const: nvidia,tegra194-xusb + + reg: + items: + - description: base and length of the xHCI host registers + - description: base and length of the XUSB FPCI registers + + reg-names: + items: + - const: hcd + - const: fpci + + 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 + + dvddio-pex-supply: + description: PCIe/USB3 analog logic power supply. Must supply 1.05 V. + + hvddio-pex-supply: + description: High-voltage PCIe/USB3 power supply. Must supply 1.8 V. + + avdd-usb-supply: + description: USB controller power supply. Must supply 3.3 V. + + avdd-pll-utmip-supply: + description: UTMI PLL power supply. Must supply 1.8 V. + + avdd-pll-uerefe-supply: + description: PLLE reference PLL power supply. Must supply 1.05 V. + + dvdd-usb-ss-pll-supply: + description: PCIe/USB3 PLL power supply. Must supply 1.05 V. + + hvdd-usb-ss-pll-e-supply: + description: High-voltage PLLE power supply. Must supply 1.8 V. + +allOf: + - $ref: usb-xhci.yaml + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/tegra194-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/memory/tegra194-mc.h> + #include <dt-bindings/power/tegra194-powergate.h> + #include <dt-bindings/reset/tegra194-reset.h> + + usb@3610000 { + compatible = "nvidia,tegra194-xusb"; + reg = <0x03610000 0x40000>, + <0x03600000 0x10000>; + reg-names = "hcd", "fpci"; + + interrupts = <GIC_SPI 163 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 164 IRQ_TYPE_LEVEL_HIGH>; + + clocks = <&bpmp TEGRA194_CLK_XUSB_CORE_HOST>, + <&bpmp TEGRA194_CLK_XUSB_FALCON>, + <&bpmp TEGRA194_CLK_XUSB_CORE_SS>, + <&bpmp TEGRA194_CLK_XUSB_SS>, + <&bpmp TEGRA194_CLK_CLK_M>, + <&bpmp TEGRA194_CLK_XUSB_FS>, + <&bpmp TEGRA194_CLK_UTMIPLL>, + <&bpmp TEGRA194_CLK_CLK_M>, + <&bpmp TEGRA194_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 TEGRA194_MEMORY_CLIENT_XUSB_HOSTR &emc>, + <&mc TEGRA194_MEMORY_CLIENT_XUSB_HOSTW &emc>; + interconnect-names = "dma-mem", "write"; + iommus = <&smmu TEGRA194_SID_XUSB_HOST>; + + power-domains = <&bpmp TEGRA194_POWER_DOMAIN_XUSBC>, + <&bpmp TEGRA194_POWER_DOMAIN_XUSBA>; + power-domain-names = "xusb_host", "xusb_ss"; + + nvidia,xusb-padctl = <&xusb_padctl>; + + phys = <&{/bus@0/padctl@3520000/pads/usb2/lanes/usb2-0}>, + <&{/bus@0/padctl@3520000/pads/usb2/lanes/usb2-1}>, + <&{/bus@0/padctl@3520000/pads/usb2/lanes/usb2-3}>, + <&{/bus@0/padctl@3520000/pads/usb3/lanes/usb3-0}>, + <&{/bus@0/padctl@3520000/pads/usb3/lanes/usb3-2}>, + <&{/bus@0/padctl@3520000/pads/usb3/lanes/usb3-3}>; + phy-names = "usb2-0", "usb2-1", "usb2-3", "usb3-0", "usb3-2", "usb3-3"; + }; diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra210-xusb.yaml b/Documentation/devicetree/bindings/usb/nvidia,tegra210-xusb.yaml new file mode 100644 index 000000000000..da1e1ec0e7c8 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/nvidia,tegra210-xusb.yaml @@ -0,0 +1,199 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/nvidia,tegra210-xusb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra210 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. + +properties: + compatible: + const: nvidia,tegra210-xusb + + reg: + items: + - description: base and length of the xHCI host registers + - description: base and length of the XUSB FPCI registers + - description: base and length of the XUSB IPFS registers + + reg-names: + items: + - const: hcd + - const: fpci + - const: ipfs + + interrupts: + items: + - description: xHCI host interrupt + - description: mailbox interrupt + + clocks: + items: + - description: XUSB host clock + - description: XUSB host source clock + - description: XUSB Falcon source clock + - description: XUSB SuperSpeed clock + - description: XUSB SuperSpeed clock divider + - 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_host_src + - const: xusb_falcon_src + - const: xusb_ss + - const: xusb_ss_div2 + - const: xusb_ss_src + - const: xusb_hs_src + - const: xusb_fs_src + - const: pll_u_480m + - const: clk_m + - const: pll_e + + resets: + items: + - description: reset for the XUSB host controller + - description: reset for the SuperSpeed logic + - description: shared reset for xusb_{ss,hs,fs,falcon,host}_src. + + reset-names: + items: + - const: xusb_host + - const: xusb_ss + - const: xusb_src + + 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: 9 + + phy-names: + minItems: 1 + maxItems: 9 + items: + enum: + - usb2-0 + - usb2-1 + - usb2-2 + - usb2-3 + - hsic-0 + - 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 + + dvddio-pex-supply: + description: PCIe/USB3 analog logic power supply. Must supply 1.05 V. + + hvddio-pex-supply: + description: High-voltage PCIe/USB3 power supply. Must supply 1.8 V. + + avdd-usb-supply: + description: USB controller power supply. Must supply 3.3 V. + + avdd-pll-utmip-supply: + description: UTMI PLL power supply. Must supply 1.8 V. + + avdd-pll-uerefe-supply: + description: PLLE reference PLL power supply. Must supply 1.05 V. + + dvdd-usb-ss-pll-supply: + description: PCIe/USB3 PLL power supply. Must supply 1.05 V. + + hvdd-usb-ss-pll-e-supply: + description: High-voltage PLLE power supply. Must supply 1.8 V. + +allOf: + - $ref: usb-xhci.yaml + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/tegra210-car.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + usb@70090000 { + compatible = "nvidia,tegra210-xusb"; + reg = <0x70090000 0x8000>, + <0x70098000 0x1000>, + <0x70099000 0x1000>; + reg-names = "hcd", "fpci", "ipfs"; + + interrupts = <GIC_SPI 39 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 40 IRQ_TYPE_LEVEL_HIGH>; + + clocks = <&tegra_car TEGRA210_CLK_XUSB_HOST>, + <&tegra_car TEGRA210_CLK_XUSB_HOST_SRC>, + <&tegra_car TEGRA210_CLK_XUSB_FALCON_SRC>, + <&tegra_car TEGRA210_CLK_XUSB_SS>, + <&tegra_car TEGRA210_CLK_XUSB_SS_DIV2>, + <&tegra_car TEGRA210_CLK_XUSB_SS_SRC>, + <&tegra_car TEGRA210_CLK_XUSB_HS_SRC>, + <&tegra_car TEGRA210_CLK_XUSB_FS_SRC>, + <&tegra_car TEGRA210_CLK_PLL_U_480M>, + <&tegra_car TEGRA210_CLK_CLK_M>, + <&tegra_car TEGRA210_CLK_PLL_E>; + clock-names = "xusb_host", "xusb_host_src", + "xusb_falcon_src", "xusb_ss", + "xusb_ss_div2", "xusb_ss_src", + "xusb_hs_src", "xusb_fs_src", + "pll_u_480m", "clk_m", "pll_e"; + resets = <&tegra_car 89>, <&tegra_car 156>, + <&tegra_car 143>; + reset-names = "xusb_host", "xusb_ss", "xusb_src"; + power-domains = <&pd_xusbhost>, <&pd_xusbss>; + power-domain-names = "xusb_host", "xusb_ss"; + + nvidia,xusb-padctl = <&padctl>; + + phys = <&{/padctl@7009f000/pads/usb2/lanes/usb2-0}>, + <&{/padctl@7009f000/pads/usb2/lanes/usb2-1}>, + <&{/padctl@7009f000/pads/usb2/lanes/usb2-2}>, + <&{/padctl@7009f000/pads/usb2/lanes/usb2-3}>, + <&{/padctl@7009f000/pads/pcie/lanes/pcie-6}>, + <&{/padctl@7009f000/pads/pcie/lanes/pcie-5}>; + phy-names = "usb2-0", "usb2-1", "usb2-2", "usb2-3", "usb3-0", + "usb3-1"; + dvddio-pex-supply = <&vdd_pex_1v05>; + hvddio-pex-supply = <&vdd_1v8>; + avdd-usb-supply = <&vdd_3v3_sys>; + avdd-pll-utmip-supply = <&vdd_1v8>; + avdd-pll-uerefe-supply = <&vdd_pex_1v05>; + dvdd-usb-ss-pll-supply = <&vdd_pex_1v05>; + hvdd-usb-ss-pll-e-supply = <&vdd_1v8>; + + #address-cells = <1>; + #size-cells = <0>; + + ethernet@1 { + compatible = "usb955,9ff"; + reg = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 6e323a380294..d5f1c4c1ef45 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 + "^alfa-network,.*": + description: ALFA Network Inc. "^allegro,.*": description: Allegro DVT "^allo,.*": @@ -246,6 +248,8 @@ patternProperties: description: ChipOne "^chipspark,.*": description: ChipSPARK + "^chongzhou,.*": + description: Shenzhen Chongzhou Electronic Technology Co., Ltd "^chrontel,.*": description: Chrontel, Inc. "^chrp,.*": @@ -260,6 +264,8 @@ patternProperties: description: Cirrus Logic, Inc. "^cisco,.*": description: Cisco Systems, Inc. + "^cloos,.*": + description: Carl Cloos Schweisstechnik GmbH. "^cloudengines,.*": description: Cloud Engines, Inc. "^cnm,.*": @@ -567,6 +573,8 @@ patternProperties: description: Hycon Technology Corp. "^hydis,.*": description: Hydis Technologies + "^hynitron,.*": + description: Shanghai Hynitron Microelectronics Co. Ltd. "^hynix,.*": description: SK Hynix Inc. "^hyundai,.*": @@ -605,6 +613,8 @@ patternProperties: description: Ingenic Semiconductor "^injoinic,.*": description: Injoinic Technology Corp. + "^innocomm,.*": + description: InnoComm Mobile Technology Corp. "^innolux,.*": description: Innolux Corporation "^inside-secure,.*": @@ -639,6 +649,8 @@ patternProperties: description: ITian Corporation "^iwave,.*": description: iWave Systems Technologies Pvt. Ltd. + "^jadard,.*": + description: Jadard Technology Inc. "^jdi,.*": description: Japan Display Inc. "^jedec,.*": @@ -883,6 +895,8 @@ patternProperties: description: Shenzhen Netxeon Technology CO., LTD "^neweast,.*": description: Guangdong Neweast Optoelectronics CO., LTD + "^newvision,.*": + description: New Vision Display (Shenzhen) Co., Ltd. "^nexbox,.*": description: Nexbox "^nextthing,.*": diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index c708cec889af..23edb427e76f 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -147,11 +147,9 @@ section of ``make help``. The generated documentation is placed in format-specific subdirectories under ``Documentation/output``. To generate documentation, Sphinx (``sphinx-build``) must obviously be -installed. For prettier HTML output, the Read the Docs Sphinx theme -(``sphinx_rtd_theme``) is used if available. For PDF output you'll also need -``XeLaTeX`` and ``convert(1)`` from ImageMagick -(https://www.imagemagick.org).\ [#ink]_ -All of these are widely available and packaged in distributions. +installed. For PDF output you'll also need ``XeLaTeX`` and ``convert(1)`` +from ImageMagick (https://www.imagemagick.org).\ [#ink]_ All of these are +widely available and packaged in distributions. To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose @@ -160,12 +158,8 @@ output. It is also possible to pass an extra DOCS_CSS overlay file, in order to customize the html layout, by using the ``DOCS_CSS`` make variable. -By default, the build will try to use the Read the Docs sphinx theme: - - https://github.com/readthedocs/sphinx_rtd_theme - -If the theme is not available, it will fall-back to the classic one. - +By default, the "Alabaster" theme is used to build the HTML documentation; +this theme is bundled with Sphinx and need not be installed separately. The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable. There is another make variable ``SPHINXDIRS``, which is useful when test diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index 36a76cbe9095..622b8156d212 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -119,6 +119,12 @@ DMA Buffer ioctls .. kernel-doc:: include/uapi/linux/dma-buf.h +DMA-BUF locking convention +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/dma-buf.c + :doc: locking convention + Kernel Functions and Structures Reference ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index 56082265e8e5..8abf9dda3241 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -287,12 +287,16 @@ IIO devm_iio_device_register() devm_iio_dmaengine_buffer_setup() devm_iio_kfifo_buffer_setup() + devm_iio_kfifo_buffer_setup_ext() devm_iio_map_array_register() devm_iio_triggered_buffer_setup() + devm_iio_triggered_buffer_setup_ext() devm_iio_trigger_alloc() devm_iio_trigger_register() devm_iio_channel_get() devm_iio_channel_get_all() + devm_iio_hw_consumer_alloc() + devm_fwnode_iio_channel_get_by_name() INPUT devm_input_allocate_device() @@ -339,7 +343,10 @@ IRQ LED devm_led_classdev_register() + devm_led_classdev_register_ext() devm_led_classdev_unregister() + devm_led_trigger_register() + devm_of_led_get() MDIO devm_mdiobus_alloc() @@ -403,12 +410,14 @@ POWER devm_reboot_mode_unregister() PWM + devm_pwmchip_add() devm_pwm_get() devm_fwnode_pwm_get() REGULATOR devm_regulator_bulk_register_supply_alias() devm_regulator_bulk_get() + devm_regulator_bulk_get_const() devm_regulator_bulk_get_enable() devm_regulator_bulk_put() devm_regulator_get() diff --git a/Documentation/driver-api/eisa.rst b/Documentation/driver-api/eisa.rst index c07565ba57da..3eac11b7eb01 100644 --- a/Documentation/driver-api/eisa.rst +++ b/Documentation/driver-api/eisa.rst @@ -189,7 +189,7 @@ eisa_bus.enable_dev initialize the device in such conditions. eisa_bus.disable_dev - A comma-separated list of slots to be enabled, even if the firmware + A comma-separated list of slots to be disabled, even if the firmware set the card as enabled. The driver won't be called to handle this device. diff --git a/Documentation/driver-api/gpio/legacy.rst b/Documentation/driver-api/gpio/legacy.rst index 9b12eeb89170..e17910cc3271 100644 --- a/Documentation/driver-api/gpio/legacy.rst +++ b/Documentation/driver-api/gpio/legacy.rst @@ -558,11 +558,6 @@ Platform Support To force-enable this framework, a platform's Kconfig will "select" GPIOLIB, else it is up to the user to configure support for GPIO. -It may also provide a custom value for ARCH_NR_GPIOS, so that it better -reflects the number of GPIOs in actual use on that platform, without -wasting static table space. (It should count both built-in/SoC GPIOs and -also ones on GPIO expanders. - If neither of these options are selected, the platform does not support GPIOs through GPIO-lib and the code cannot be enabled by the user. diff --git a/Documentation/driver-api/miscellaneous.rst b/Documentation/driver-api/miscellaneous.rst index 304ffb146cf9..4a5104a368ac 100644 --- a/Documentation/driver-api/miscellaneous.rst +++ b/Documentation/driver-api/miscellaneous.rst @@ -16,12 +16,11 @@ Parallel Port Devices 16x50 UART Driver ================= -.. kernel-doc:: drivers/tty/serial/serial_core.c - :export: - .. kernel-doc:: drivers/tty/serial/8250/8250_core.c :export: +See serial/driver.rst for related APIs. + Pulse-Width Modulation (PWM) ============================ diff --git a/Documentation/driver-api/pin-control.rst b/Documentation/driver-api/pin-control.rst index 71eefe5a023f..0022e930e93e 100644 --- a/Documentation/driver-api/pin-control.rst +++ b/Documentation/driver-api/pin-control.rst @@ -1238,7 +1238,7 @@ default state like this:: return PTR_ERR(foo->s); } - ret = pinctrl_select_state(foo->s); + ret = pinctrl_select_state(foo->p, foo->s); if (ret < 0) { /* FIXME: clean up "foo" here */ return ret; @@ -1399,11 +1399,11 @@ on the pins defined by group B:: if (IS_ERR(p)) ... - s1 = pinctrl_lookup_state(foo->p, "pos-A"); + s1 = pinctrl_lookup_state(p, "pos-A"); if (IS_ERR(s1)) ... - s2 = pinctrl_lookup_state(foo->p, "pos-B"); + s2 = pinctrl_lookup_state(p, "pos-B"); if (IS_ERR(s2)) ... } @@ -1411,14 +1411,14 @@ on the pins defined by group B:: foo_switch() { /* Enable on position A */ - ret = pinctrl_select_state(s1); + ret = pinctrl_select_state(p, s1); if (ret < 0) ... ... /* Enable on position B */ - ret = pinctrl_select_state(s2); + ret = pinctrl_select_state(p, s2); if (ret < 0) ... diff --git a/Documentation/driver-api/spi.rst b/Documentation/driver-api/spi.rst index f64cb666498a..f28887045049 100644 --- a/Documentation/driver-api/spi.rst +++ b/Documentation/driver-api/spi.rst @@ -25,8 +25,8 @@ hardware, which may be as simple as a set of GPIO pins or as complex as a pair of FIFOs connected to dual DMA engines on the other side of the SPI shift register (maximizing throughput). Such drivers bridge between whatever bus they sit on (often the platform bus) and SPI, and expose -the SPI side of their device as a :c:type:`struct spi_master -<spi_master>`. SPI devices are children of that master, +the SPI side of their device as a :c:type:`struct spi_controller +<spi_controller>`. SPI devices are children of that master, represented as a :c:type:`struct spi_device <spi_device>` and manufactured from :c:type:`struct spi_board_info <spi_board_info>` descriptors which are usually provided by diff --git a/Documentation/fault-injection/fault-injection.rst b/Documentation/fault-injection/fault-injection.rst index 17779a2772e5..5f6454b9dbd4 100644 --- a/Documentation/fault-injection/fault-injection.rst +++ b/Documentation/fault-injection/fault-injection.rst @@ -83,9 +83,7 @@ configuration of fault-injection capabilities. - /sys/kernel/debug/fail*/times: specifies how many times failures may happen at most. A value of -1 - means "no limit". Note, though, that this file only accepts unsigned - values. So, if you want to specify -1, you better use 'printf' instead - of 'echo', e.g.: $ printf %#x -1 > times + means "no limit". - /sys/kernel/debug/fail*/space: @@ -284,7 +282,7 @@ Application Examples echo Y > /sys/kernel/debug/$FAILTYPE/task-filter echo 10 > /sys/kernel/debug/$FAILTYPE/probability echo 100 > /sys/kernel/debug/$FAILTYPE/interval - printf %#x -1 > /sys/kernel/debug/$FAILTYPE/times + echo -1 > /sys/kernel/debug/$FAILTYPE/times echo 0 > /sys/kernel/debug/$FAILTYPE/space echo 2 > /sys/kernel/debug/$FAILTYPE/verbose echo Y > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait @@ -338,7 +336,7 @@ Application Examples echo N > /sys/kernel/debug/$FAILTYPE/task-filter echo 10 > /sys/kernel/debug/$FAILTYPE/probability echo 100 > /sys/kernel/debug/$FAILTYPE/interval - printf %#x -1 > /sys/kernel/debug/$FAILTYPE/times + echo -1 > /sys/kernel/debug/$FAILTYPE/times echo 0 > /sys/kernel/debug/$FAILTYPE/space echo 2 > /sys/kernel/debug/$FAILTYPE/verbose echo Y > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait @@ -369,7 +367,7 @@ Application Examples echo N > /sys/kernel/debug/$FAILTYPE/task-filter echo 100 > /sys/kernel/debug/$FAILTYPE/probability echo 0 > /sys/kernel/debug/$FAILTYPE/interval - printf %#x -1 > /sys/kernel/debug/$FAILTYPE/times + echo -1 > /sys/kernel/debug/$FAILTYPE/times echo 0 > /sys/kernel/debug/$FAILTYPE/space echo 1 > /sys/kernel/debug/$FAILTYPE/verbose diff --git a/Documentation/fb/modedb.rst b/Documentation/fb/modedb.rst index 4d2411e32ebb..e53375033146 100644 --- a/Documentation/fb/modedb.rst +++ b/Documentation/fb/modedb.rst @@ -26,6 +26,11 @@ Valid mode specifiers (mode_option argument):: with <xres>, <yres>, <bpp> and <refresh> decimal numbers and <name> a string. Things between square brackets are optional. +Valid names are:: + + - NSTC: 480i output, with the CCIR System-M TV mode and NTSC color encoding + - PAL: 576i output, with the CCIR System-B 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 VESA(TM) Coordinated Video Timings instead of looking up the mode from a table. diff --git a/Documentation/features/core/cBPF-JIT/arch-support.txt b/Documentation/features/core/cBPF-JIT/arch-support.txt index a053667a7a8c..0a1f5bb7eeb9 100644 --- a/Documentation/features/core/cBPF-JIT/arch-support.txt +++ b/Documentation/features/core/cBPF-JIT/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/core/eBPF-JIT/arch-support.txt b/Documentation/features/core/eBPF-JIT/arch-support.txt index c0bb9c92937f..6c0f3d759e6a 100644 --- a/Documentation/features/core/eBPF-JIT/arch-support.txt +++ b/Documentation/features/core/eBPF-JIT/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/core/generic-idle-thread/arch-support.txt b/Documentation/features/core/generic-idle-thread/arch-support.txt index c9bfff292816..0b94099cf6ac 100644 --- a/Documentation/features/core/generic-idle-thread/arch-support.txt +++ b/Documentation/features/core/generic-idle-thread/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | ok | | ia64: | ok | - | loong: | ok | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/core/jump-labels/arch-support.txt b/Documentation/features/core/jump-labels/arch-support.txt index 35e2a44b1448..2328eada3a49 100644 --- a/Documentation/features/core/jump-labels/arch-support.txt +++ b/Documentation/features/core/jump-labels/arch-support.txt @@ -10,10 +10,10 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | csky: | TODO | + | csky: | ok | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/core/thread-info-in-task/arch-support.txt b/Documentation/features/core/thread-info-in-task/arch-support.txt index 9b3e2ce12b44..9c5d39eebef2 100644 --- a/Documentation/features/core/thread-info-in-task/arch-support.txt +++ b/Documentation/features/core/thread-info-in-task/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | TODO | diff --git a/Documentation/features/core/tracehook/arch-support.txt b/Documentation/features/core/tracehook/arch-support.txt index 9c7ffec5d51d..aed5679da651 100644 --- a/Documentation/features/core/tracehook/arch-support.txt +++ b/Documentation/features/core/tracehook/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | ok | | ia64: | ok | - | loong: | ok | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/debug/KASAN/arch-support.txt b/Documentation/features/debug/KASAN/arch-support.txt index 2fd5fb6f5f23..bf0124fae643 100644 --- a/Documentation/features/debug/KASAN/arch-support.txt +++ b/Documentation/features/debug/KASAN/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | TODO | @@ -25,7 +25,7 @@ | s390: | ok | | sh: | TODO | | sparc: | TODO | - | um: | TODO | + | um: | ok | | x86: | ok | | xtensa: | ok | ----------------------- diff --git a/Documentation/features/debug/debug-vm-pgtable/arch-support.txt b/Documentation/features/debug/debug-vm-pgtable/arch-support.txt index c45711e55c7b..9ec5d13f4939 100644 --- a/Documentation/features/debug/debug-vm-pgtable/arch-support.txt +++ b/Documentation/features/debug/debug-vm-pgtable/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | TODO | diff --git a/Documentation/features/debug/gcov-profile-all/arch-support.txt b/Documentation/features/debug/gcov-profile-all/arch-support.txt index 0b3ba2415fac..dc4014f7e1f8 100644 --- a/Documentation/features/debug/gcov-profile-all/arch-support.txt +++ b/Documentation/features/debug/gcov-profile-all/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | ok | | mips: | ok | diff --git a/Documentation/features/debug/kcov/arch-support.txt b/Documentation/features/debug/kcov/arch-support.txt index 0a91f5ce34a9..ffcc9f2b1d74 100644 --- a/Documentation/features/debug/kcov/arch-support.txt +++ b/Documentation/features/debug/kcov/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/debug/kgdb/arch-support.txt b/Documentation/features/debug/kgdb/arch-support.txt index 04120d278c22..958498f9f2a4 100644 --- a/Documentation/features/debug/kgdb/arch-support.txt +++ b/Documentation/features/debug/kgdb/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | ok | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | ok | | mips: | ok | diff --git a/Documentation/features/debug/kmemleak/arch-support.txt b/Documentation/features/debug/kmemleak/arch-support.txt index e487c356ab20..0cfa5f0e4db1 100644 --- a/Documentation/features/debug/kmemleak/arch-support.txt +++ b/Documentation/features/debug/kmemleak/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | ok | | mips: | ok | diff --git a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt index b3697f4c806e..bcc29d3aba9a 100644 --- a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt +++ b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | TODO | diff --git a/Documentation/features/debug/kprobes/arch-support.txt b/Documentation/features/debug/kprobes/arch-support.txt index 452385ac9e06..8a77d62a42c5 100644 --- a/Documentation/features/debug/kprobes/arch-support.txt +++ b/Documentation/features/debug/kprobes/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | TODO | | ia64: | ok | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/debug/kretprobes/arch-support.txt b/Documentation/features/debug/kretprobes/arch-support.txt index daecf046e72b..cf4723c5ac55 100644 --- a/Documentation/features/debug/kretprobes/arch-support.txt +++ b/Documentation/features/debug/kretprobes/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | TODO | | ia64: | ok | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/debug/optprobes/arch-support.txt b/Documentation/features/debug/optprobes/arch-support.txt index adb1bd055bfd..83a4639a5c0a 100644 --- a/Documentation/features/debug/optprobes/arch-support.txt +++ b/Documentation/features/debug/optprobes/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | TODO | diff --git a/Documentation/features/debug/stackprotector/arch-support.txt b/Documentation/features/debug/stackprotector/arch-support.txt index ddcd7161d14c..71cd4ba18f7d 100644 --- a/Documentation/features/debug/stackprotector/arch-support.txt +++ b/Documentation/features/debug/stackprotector/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/debug/uprobes/arch-support.txt b/Documentation/features/debug/uprobes/arch-support.txt index 25121200f9f9..d53f2f94fbda 100644 --- a/Documentation/features/debug/uprobes/arch-support.txt +++ b/Documentation/features/debug/uprobes/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/debug/user-ret-profiler/arch-support.txt b/Documentation/features/debug/user-ret-profiler/arch-support.txt index f2fcff8e77b7..059110a5fa6e 100644 --- a/Documentation/features/debug/user-ret-profiler/arch-support.txt +++ b/Documentation/features/debug/user-ret-profiler/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | TODO | diff --git a/Documentation/features/io/dma-contiguous/arch-support.txt b/Documentation/features/io/dma-contiguous/arch-support.txt index 95e485c87e36..bfe0921a3853 100644 --- a/Documentation/features/io/dma-contiguous/arch-support.txt +++ b/Documentation/features/io/dma-contiguous/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | TODO | | ia64: | TODO | - | loong: | ok | + | loongarch: | ok | | m68k: | TODO | | microblaze: | ok | | mips: | ok | diff --git a/Documentation/features/locking/cmpxchg-local/arch-support.txt b/Documentation/features/locking/cmpxchg-local/arch-support.txt index 8b1a8d9e1c79..68329e96dffa 100644 --- a/Documentation/features/locking/cmpxchg-local/arch-support.txt +++ b/Documentation/features/locking/cmpxchg-local/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | TODO | diff --git a/Documentation/features/locking/lockdep/arch-support.txt b/Documentation/features/locking/lockdep/arch-support.txt index ab69e8f56a37..ddb945278589 100644 --- a/Documentation/features/locking/lockdep/arch-support.txt +++ b/Documentation/features/locking/lockdep/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | ok | | ia64: | TODO | - | loong: | ok | + | loongarch: | ok | | m68k: | TODO | | microblaze: | ok | | mips: | ok | diff --git a/Documentation/features/locking/queued-rwlocks/arch-support.txt b/Documentation/features/locking/queued-rwlocks/arch-support.txt index 0bfb72a08d82..5deb845477e4 100644 --- a/Documentation/features/locking/queued-rwlocks/arch-support.txt +++ b/Documentation/features/locking/queued-rwlocks/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | TODO | | ia64: | TODO | - | loong: | ok | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/locking/queued-spinlocks/arch-support.txt b/Documentation/features/locking/queued-spinlocks/arch-support.txt index d2f2201febc8..2d3961bfef5d 100644 --- a/Documentation/features/locking/queued-spinlocks/arch-support.txt +++ b/Documentation/features/locking/queued-spinlocks/arch-support.txt @@ -10,10 +10,10 @@ | arc: | TODO | | arm: | TODO | | arm64: | ok | - | csky: | TODO | + | csky: | ok | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/perf/kprobes-event/arch-support.txt b/Documentation/features/perf/kprobes-event/arch-support.txt index 0d0647b06762..641a7d2ff2a3 100644 --- a/Documentation/features/perf/kprobes-event/arch-support.txt +++ b/Documentation/features/perf/kprobes-event/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | ok | | ia64: | TODO | - | loong: | ok | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/perf/perf-regs/arch-support.txt b/Documentation/features/perf/perf-regs/arch-support.txt index 13c297bbf05c..33866eb242c1 100644 --- a/Documentation/features/perf/perf-regs/arch-support.txt +++ b/Documentation/features/perf/perf-regs/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/perf/perf-stackdump/arch-support.txt b/Documentation/features/perf/perf-stackdump/arch-support.txt index 931687eec671..c8e4c7c65012 100644 --- a/Documentation/features/perf/perf-stackdump/arch-support.txt +++ b/Documentation/features/perf/perf-stackdump/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/sched/membarrier-sync-core/arch-support.txt b/Documentation/features/sched/membarrier-sync-core/arch-support.txt index 336d728b8a45..1e51614c136e 100644 --- a/Documentation/features/sched/membarrier-sync-core/arch-support.txt +++ b/Documentation/features/sched/membarrier-sync-core/arch-support.txt @@ -36,7 +36,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | TODO | diff --git a/Documentation/features/sched/numa-balancing/arch-support.txt b/Documentation/features/sched/numa-balancing/arch-support.txt index 76d012118372..532cc67cdf92 100644 --- a/Documentation/features/sched/numa-balancing/arch-support.txt +++ b/Documentation/features/sched/numa-balancing/arch-support.txt @@ -13,7 +13,7 @@ | csky: | .. | | hexagon: | .. | | ia64: | TODO | - | loong: | ok | + | loongarch: | ok | | m68k: | .. | | microblaze: | .. | | mips: | TODO | diff --git a/Documentation/features/scripts/features-refresh.sh b/Documentation/features/scripts/features-refresh.sh index 9e72d38a0720..c2288124e94a 100755 --- a/Documentation/features/scripts/features-refresh.sh +++ b/Documentation/features/scripts/features-refresh.sh @@ -60,7 +60,7 @@ for F_FILE in Documentation/features/*/*/arch-support.txt; do echo " | arch |status|" >> $T_FILE echo " -----------------------" >> $T_FILE for ARCH_DIR in arch/*/; do - ARCH=$(echo $ARCH_DIR | sed -e 's/arch//g' | sed -e 's/\///g') + ARCH=$(echo $ARCH_DIR | sed -e 's/^arch//g' | sed -e 's/\///g') K_FILES=$(find $ARCH_DIR -name "Kconfig*") K_GREP=$(grep "$K" $K_FILES) # diff --git a/Documentation/features/seccomp/seccomp-filter/arch-support.txt b/Documentation/features/seccomp/seccomp-filter/arch-support.txt index a86b8b1f3d10..dc71bf7b1a7e 100644 --- a/Documentation/features/seccomp/seccomp-filter/arch-support.txt +++ b/Documentation/features/seccomp/seccomp-filter/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | TODO | | ia64: | TODO | - | loong: | ok | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/time/arch-tick-broadcast/arch-support.txt b/Documentation/features/time/arch-tick-broadcast/arch-support.txt index 364169f00ee2..9bffac80019e 100644 --- a/Documentation/features/time/arch-tick-broadcast/arch-support.txt +++ b/Documentation/features/time/arch-tick-broadcast/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | - | loong: | ok | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/time/clockevents/arch-support.txt b/Documentation/features/time/clockevents/arch-support.txt index 6ea274790e47..625160048f68 100644 --- a/Documentation/features/time/clockevents/arch-support.txt +++ b/Documentation/features/time/clockevents/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | ok | | ia64: | TODO | - | loong: | ok | + | loongarch: | ok | | m68k: | TODO | | microblaze: | ok | | mips: | ok | diff --git a/Documentation/features/time/context-tracking/arch-support.txt b/Documentation/features/time/context-tracking/arch-support.txt index e59071a49090..72bc5bad0348 100644 --- a/Documentation/features/time/context-tracking/arch-support.txt +++ b/Documentation/features/time/context-tracking/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | TODO | | ia64: | TODO | - | loong: | ok | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/time/irq-time-acct/arch-support.txt b/Documentation/features/time/irq-time-acct/arch-support.txt index fd17d8de5ef1..ceb036610d09 100644 --- a/Documentation/features/time/irq-time-acct/arch-support.txt +++ b/Documentation/features/time/irq-time-acct/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | .. | - | loong: | ok | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/time/virt-cpuacct/arch-support.txt b/Documentation/features/time/virt-cpuacct/arch-support.txt index 1a859ac05e9e..c063dffd5261 100644 --- a/Documentation/features/time/virt-cpuacct/arch-support.txt +++ b/Documentation/features/time/virt-cpuacct/arch-support.txt @@ -13,7 +13,7 @@ | csky: | ok | | hexagon: | TODO | | ia64: | ok | - | loong: | ok | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/vm/ELF-ASLR/arch-support.txt b/Documentation/features/vm/ELF-ASLR/arch-support.txt index b1229953391b..15164f36f224 100644 --- a/Documentation/features/vm/ELF-ASLR/arch-support.txt +++ b/Documentation/features/vm/ELF-ASLR/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/vm/PG_uncached/arch-support.txt b/Documentation/features/vm/PG_uncached/arch-support.txt index 02f325fbfcd0..5acd64b97dba 100644 --- a/Documentation/features/vm/PG_uncached/arch-support.txt +++ b/Documentation/features/vm/PG_uncached/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | ok | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | TODO | diff --git a/Documentation/features/vm/THP/arch-support.txt b/Documentation/features/vm/THP/arch-support.txt index 9bfff977ef55..9dd7d75d0465 100644 --- a/Documentation/features/vm/THP/arch-support.txt +++ b/Documentation/features/vm/THP/arch-support.txt @@ -13,7 +13,7 @@ | csky: | .. | | hexagon: | .. | | ia64: | TODO | - | loong: | ok | + | loongarch: | ok | | m68k: | .. | | microblaze: | .. | | mips: | ok | diff --git a/Documentation/features/vm/TLB/arch-support.txt b/Documentation/features/vm/TLB/arch-support.txt index 039e4e91ada3..7f049c251a79 100644 --- a/Documentation/features/vm/TLB/arch-support.txt +++ b/Documentation/features/vm/TLB/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | .. | | microblaze: | .. | | mips: | TODO | diff --git a/Documentation/features/vm/huge-vmap/arch-support.txt b/Documentation/features/vm/huge-vmap/arch-support.txt index 13b4940e0c3a..34647d9bdca4 100644 --- a/Documentation/features/vm/huge-vmap/arch-support.txt +++ b/Documentation/features/vm/huge-vmap/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | - | loong: | TODO | + | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | | mips: | TODO | @@ -21,7 +21,7 @@ | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | - | riscv: | TODO | + | riscv: | ok | | s390: | TODO | | sh: | TODO | | sparc: | TODO | diff --git a/Documentation/features/vm/ioremap_prot/arch-support.txt b/Documentation/features/vm/ioremap_prot/arch-support.txt index 6bd78eb4dc6e..a24149e59d73 100644 --- a/Documentation/features/vm/ioremap_prot/arch-support.txt +++ b/Documentation/features/vm/ioremap_prot/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | - | loong: | ok | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/features/vm/pte_special/arch-support.txt b/Documentation/features/vm/pte_special/arch-support.txt index fc3687b5e89b..d2b22a06945e 100644 --- a/Documentation/features/vm/pte_special/arch-support.txt +++ b/Documentation/features/vm/pte_special/arch-support.txt @@ -13,7 +13,7 @@ | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | - | loong: | ok | + | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | | mips: | ok | diff --git a/Documentation/filesystems/configfs.rst b/Documentation/filesystems/configfs.rst index 1d3d6f4a82a9..8c9342ed6d25 100644 --- a/Documentation/filesystems/configfs.rst +++ b/Documentation/filesystems/configfs.rst @@ -289,7 +289,6 @@ config_item_type:: const char *name); struct config_group *(*make_group)(struct config_group *group, const char *name); - int (*commit_item)(struct config_item *item); void (*disconnect_notify)(struct config_group *group, struct config_item *item); void (*drop_item)(struct config_group *group, @@ -486,50 +485,3 @@ up. Here, the heartbeat code calls configfs_depend_item(). If it succeeds, then heartbeat knows the region is safe to give to ocfs2. If it fails, it was being torn down anyway, and heartbeat can gracefully pass up an error. - -Committable Items -================= - -Note: - Committable items are currently unimplemented. - -Some config_items cannot have a valid initial state. That is, no -default values can be specified for the item's attributes such that the -item can do its work. Userspace must configure one or more attributes, -after which the subsystem can start whatever entity this item -represents. - -Consider the FakeNBD device from above. Without a target address *and* -a target device, the subsystem has no idea what block device to import. -The simple example assumes that the subsystem merely waits until all the -appropriate attributes are configured, and then connects. This will, -indeed, work, but now every attribute store must check if the attributes -are initialized. Every attribute store must fire off the connection if -that condition is met. - -Far better would be an explicit action notifying the subsystem that the -config_item is ready to go. More importantly, an explicit action allows -the subsystem to provide feedback as to whether the attributes are -initialized in a way that makes sense. configfs provides this as -committable items. - -configfs still uses only normal filesystem operations. An item is -committed via rename(2). The item is moved from a directory where it -can be modified to a directory where it cannot. - -Any group that provides the ct_group_ops->commit_item() method has -committable items. When this group appears in configfs, mkdir(2) will -not work directly in the group. Instead, the group will have two -subdirectories: "live" and "pending". The "live" directory does not -support mkdir(2) or rmdir(2) either. It only allows rename(2). The -"pending" directory does allow mkdir(2) and rmdir(2). An item is -created in the "pending" directory. Its attributes can be modified at -will. Userspace commits the item by renaming it into the "live" -directory. At this point, the subsystem receives the ->commit_item() -callback. If all required attributes are filled to satisfaction, the -method returns zero and the item is moved to the "live" directory. - -As rmdir(2) does not work in the "live" directory, an item must be -shutdown, or "uncommitted". Again, this is done via rename(2), this -time from the "live" directory back to the "pending" one. The subsystem -is notified by the ct_group_ops->uncommit_object() method. diff --git a/Documentation/filesystems/debugfs.rst b/Documentation/filesystems/debugfs.rst index 71b1fee56d2a..dc35da8b8792 100644 --- a/Documentation/filesystems/debugfs.rst +++ b/Documentation/filesystems/debugfs.rst @@ -155,8 +155,8 @@ any code which does so in the mainline. Note that all files created with debugfs_create_blob() are read-only. If you want to dump a block of registers (something that happens quite -often during development, even if little such code reaches mainline. -Debugfs offers two functions: one to make a registers-only file, and +often during development, even if little such code reaches mainline), +debugfs offers two functions: one to make a registers-only file, and another to insert a register block in the middle of another sequential file:: @@ -183,7 +183,7 @@ The "base" argument may be 0, but you may want to build the reg32 array using __stringify, and a number of register names (macros) are actually byte offsets over a base for the register block. -If you want to dump an u32 array in debugfs, you can create file with:: +If you want to dump a u32 array in debugfs, you can create a file with:: struct debugfs_u32_array { u32 *array; @@ -197,7 +197,7 @@ If you want to dump an u32 array in debugfs, you can create file with:: The "array" argument wraps a pointer to the array's data and the number of its elements. Note: Once array is created its size can not be changed. -There is a helper function to create device related seq_file:: +There is a helper function to create a device-related seq_file:: void debugfs_create_devm_seqfile(struct device *dev, const char *name, diff --git a/Documentation/filesystems/erofs.rst b/Documentation/filesystems/erofs.rst index 05e03d54af1a..067fd1670b1f 100644 --- a/Documentation/filesystems/erofs.rst +++ b/Documentation/filesystems/erofs.rst @@ -30,12 +30,18 @@ It is implemented to be a better choice for the following scenarios: especially for those embedded devices with limited memory and high-density hosts with numerous containers. -Here is the main features of EROFS: +Here are the main features of EROFS: - Little endian on-disk design; - - 4KiB block size and 32-bit block addresses, therefore 16TiB address space - at most for now; + - Block-based distribution and file-based distribution over fscache are + supported; + + - Support multiple devices to refer to external blobs, which can be used + for container images; + + - 4KiB block size and 32-bit block addresses for each device, therefore + 16TiB address space at most for now; - Two inode layouts for different requirements: @@ -50,28 +56,31 @@ Here is the main features of EROFS: Metadata reserved 8 bytes 18 bytes ===================== ============ ====================================== - - Metadata and data could be mixed as an option; - - - Support extended attributes (xattrs) as an option; + - Support extended attributes as an option; - - Support tailpacking data and xattr inline compared to byte-addressed - unaligned metadata or smaller block size alternatives; - - - Support POSIX.1e ACLs by using xattrs; + - Support POSIX.1e ACLs by using extended attributes; - Support transparent data compression as an option: LZ4 and MicroLZMA algorithms can be used on a per-file basis; In addition, inplace decompression is also supported to avoid bounce compressed buffers and page cache thrashing. + - Support chunk-based data deduplication and rolling-hash compressed data + deduplication; + + - Support tailpacking inline compared to byte-addressed unaligned metadata + or smaller block size alternatives; + + - Support merging tail-end data into a special inode as fragments. + + - Support large folios for uncompressed files. + - Support direct I/O on uncompressed files to avoid double caching for loop devices; - Support FSDAX on uncompressed images for secure containers and ramdisks in order to get rid of unnecessary page cache. - - Support multiple devices for multi blob container images; - - Support file-based on-demand loading with the Fscache infrastructure. The following git tree provides the file system user-space tools under @@ -259,7 +268,7 @@ By the way, chunk-based files are all uncompressed for now. Data compression ---------------- -EROFS implements LZ4 fixed-sized output compression which generates fixed-sized +EROFS implements fixed-sized output compression which generates fixed-sized compressed data blocks from variable-sized input in contrast to other existing fixed-sized input solutions. Relatively higher compression ratios can be gotten by using fixed-sized output compression since nowadays popular data compression @@ -314,3 +323,6 @@ to understand its delta0 is constantly 1, as illustrated below:: If another HEAD follows a HEAD lcluster, there is no room to record CBLKCNT, but it's easy to know the size of such pcluster is 1 lcluster as well. + +Since Linux v6.1, each pcluster can be used for multiple variable-sized extents, +therefore it can be used for compressed data deduplication. diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index 17df9a02ccff..220f3e0d3f55 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -25,10 +25,14 @@ a consistency checking tool (fsck.f2fs), and a debugging tool (dump.f2fs). - git://git.kernel.org/pub/scm/linux/kernel/git/jaegeuk/f2fs-tools.git -For reporting bugs and sending patches, please use the following mailing list: +For sending patches, please use the following mailing list: - linux-f2fs-devel@lists.sourceforge.net +For reporting bugs, please use the following f2fs bug tracker link: + +- https://bugzilla.kernel.org/enter_bug.cgi?product=File%20System&component=f2fs + Background and Design issues ============================ @@ -154,6 +158,8 @@ nobarrier This option can be used if underlying storage guarantees If this option is set, no cache_flush commands are issued but f2fs still guarantees the write ordering of all the data writes. +barrier If this option is set, cache_flush commands are allowed to be + issued. fastboot This option is used when a system wants to reduce mount time as much as possible, even though normal performance can be sacrificed. @@ -199,6 +205,7 @@ fault_type=%d Support configuring fault injection type, should be FAULT_SLAB_ALLOC 0x000008000 FAULT_DQUOT_INIT 0x000010000 FAULT_LOCK_OP 0x000020000 + FAULT_BLKADDR 0x000040000 =================== =========== mode=%s Control block allocation mode which supports "adaptive" and "lfs". In "lfs" mode, there should be no random @@ -340,6 +347,10 @@ memory=%s Control memory mode. This supports "normal" and "low" modes. Because of the nature of low memory devices, in this mode, f2fs will try to save memory sometimes by sacrificing performance. "normal" mode is the default mode and same as before. +age_extent_cache Enable an age extent cache based on rb-tree. It records + data block update frequency of the extent per inode, in + order to provide better temperature hints for data block + allocation. ======================== ============================================================ Debugfs Entries diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index 5ba5817c17c2..ef183387da20 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -338,6 +338,7 @@ Currently, the following pairs of encryption modes are supported: - AES-128-CBC for contents and AES-128-CTS-CBC for filenames - Adiantum for both contents and filenames - AES-256-XTS for contents and AES-256-HCTR2 for filenames (v2 policies only) +- SM4-XTS for contents and SM4-CTS-CBC for filenames (v2 policies only) If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair. @@ -369,6 +370,12 @@ CONFIG_CRYPTO_HCTR2 must be enabled. Also, fast implementations of XCTR and POLYVAL should be enabled, e.g. CRYPTO_POLYVAL_ARM64_CE and CRYPTO_AES_ARM64_CE_BLK for ARM64. +SM4 is a Chinese block cipher that is an alternative to AES. It has +not seen as much security review as AES, and it only has a 128-bit key +size. It may be useful in cases where its use is mandated. +Otherwise, it should not be used. For SM4 support to be available, it +also needs to be enabled in the kernel crypto API. + New encryption modes can be added relatively easily, without changes to individual filesystems. However, authenticated encryption (AE) modes are not currently supported because of the difficulty of dealing diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index 8f737e76935c..36fa2a83d714 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -70,7 +70,7 @@ prototypes:: const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *); void (*truncate) (struct inode *); int (*permission) (struct inode *, int, unsigned int); - struct posix_acl * (*get_acl)(struct inode *, int, bool); + 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); ssize_t (*listxattr) (struct dentry *, char *, size_t); @@ -84,13 +84,14 @@ prototypes:: int (*fileattr_set)(struct user_namespace *mnt_userns, 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); locking rules: all may block -============= ============================================= +============== ============================================= ops i_rwsem(inode) -============= ============================================= +============== ============================================= lookup: shared create: exclusive link: exclusive (both) @@ -104,6 +105,7 @@ readlink: no get_link: no setattr: exclusive permission: no (may not block if called in rcu-walk mode) +get_inode_acl: no get_acl: no getattr: no listxattr: no @@ -113,7 +115,7 @@ atomic_open: shared (exclusive if O_CREAT is set in open flags) tmpfile: no fileattr_get: no or exclusive fileattr_set: exclusive -============= ============================================= +============== ============================================= Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem diff --git a/Documentation/filesystems/mount_api.rst b/Documentation/filesystems/mount_api.rst index eb358a00be27..63204d2094fd 100644 --- a/Documentation/filesystems/mount_api.rst +++ b/Documentation/filesystems/mount_api.rst @@ -562,17 +562,6 @@ or looking up of superblocks. The following helpers all wrap sget_fc(): - * :: - - int vfs_get_super(struct fs_context *fc, - enum vfs_get_super_keying keying, - int (*fill_super)(struct super_block *sb, - struct fs_context *fc)) - - This creates/looks up a deviceless superblock. The keying indicates how - many superblocks of this type may exist and in what manner they may be - shared: - (1) vfs_get_single_super Only one such superblock may exist in the system. Any further @@ -814,6 +803,7 @@ process the parameters it is given. int fs_lookup_param(struct fs_context *fc, struct fs_parameter *value, bool want_bdev, + unsigned int flags, struct path *_path); This takes a parameter that carries a string or filename type and attempts diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst index df0dc37e6f58..d2d684ae7798 100644 --- a/Documentation/filesystems/porting.rst +++ b/Documentation/filesystems/porting.rst @@ -462,8 +462,8 @@ ERR_PTR(...). argument; instead of passing IPERM_FLAG_RCU we add MAY_NOT_BLOCK into mask. generic_permission() has also lost the check_acl argument; ACL checking -has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl -to read an ACL from disk. +has been taken to VFS and filesystems need to provide a non-NULL +->i_op->get_inode_acl to read an ACL from disk. --- diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 898c99eae8e4..e224b6d5b642 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -47,6 +47,7 @@ fixes/update part 1.1 Stefani Seibold <stefani@seibold.net> June 9 2009 3.10 /proc/<pid>/timerslack_ns - Task timerslack value 3.11 /proc/<pid>/patch_state - Livepatch patch operation state 3.12 /proc/<pid>/arch_status - Task architecture specific information + 3.13 /proc/<pid>/fd - List of symlinks to open files 4 Configuring procfs 4.1 Mount options @@ -245,7 +246,8 @@ It's slow but very precise. Ngid NUMA group ID (0 if none) Pid process id PPid process id of the parent process - TracerPid PID of process tracing this process (0 if not) + TracerPid PID of process tracing this process (0 if not, or + the tracer is outside of the current pid namespace) Uid Real, effective, saved set, and file system UIDs Gid Real, effective, saved set, and file system GIDs FDSize number of file descriptor slots currently allocated @@ -426,14 +428,16 @@ with the memory region, as the case would be with BSS (uninitialized data). The "pathname" shows the name associated file for this mapping. If the mapping is not associated with a file: - ============= ==================================== + =================== =========================================== [heap] the heap of the program [stack] the stack of the main process [vdso] the "virtual dynamic shared object", the kernel system call handler - [anon:<name>] an anonymous mapping that has been + [anon:<name>] a private anonymous mapping that has been named by userspace - ============= ==================================== + [anon_shmem:<name>] an anonymous shared memory mapping that has + been named by userspace + =================== =========================================== or if empty, the mapping is anonymous. @@ -2149,6 +2153,22 @@ AVX512_elapsed_ms the task is unlikely an AVX512 user, but depends on the workload and the scheduling scenario, it also could be a false negative mentioned above. +3.13 /proc/<pid>/fd - List of symlinks to open files +------------------------------------------------------- +This directory contains symbolic links which represent open files +the process is maintaining. Example output:: + + lr-x------ 1 root root 64 Sep 20 17:53 0 -> /dev/null + l-wx------ 1 root root 64 Sep 20 17:53 1 -> /dev/null + lrwx------ 1 root root 64 Sep 20 17:53 10 -> 'socket:[12539]' + lrwx------ 1 root root 64 Sep 20 17:53 11 -> 'socket:[12540]' + lrwx------ 1 root root 64 Sep 20 17:53 12 -> 'socket:[12542]' + +The number of open files for the process is stored in 'size' member +of stat() output for /proc/<pid>/fd for fast access. +------------------------------------------------------- + + Chapter 4: Configuring procfs ============================= diff --git a/Documentation/filesystems/sysfs.rst b/Documentation/filesystems/sysfs.rst index 8bba676b1365..f8187d466b97 100644 --- a/Documentation/filesystems/sysfs.rst +++ b/Documentation/filesystems/sysfs.rst @@ -12,10 +12,10 @@ Mike Murphy <mamurph@cs.clemson.edu> :Original: 10 January 2003 -What it is: -~~~~~~~~~~~ +What it is +~~~~~~~~~~ -sysfs is a ram-based filesystem initially based on ramfs. It provides +sysfs is a RAM-based filesystem initially based on ramfs. It provides a means to export kernel data structures, their attributes, and the linkages between them to userspace. @@ -43,7 +43,7 @@ userspace. Top-level directories in sysfs represent the common ancestors of object hierarchies; i.e. the subsystems the objects belong to. -Sysfs internally stores a pointer to the kobject that implements a +sysfs internally stores a pointer to the kobject that implements a directory in the kernfs_node object associated with the directory. In the past this kobject pointer has been used by sysfs to do reference counting directly on the kobject whenever the file is opened or closed. @@ -55,7 +55,7 @@ Attributes ~~~~~~~~~~ Attributes can be exported for kobjects in the form of regular files in -the filesystem. Sysfs forwards file I/O operations to methods defined +the filesystem. sysfs forwards file I/O operations to methods defined for the attributes, providing a means to read and write kernel attributes. @@ -72,8 +72,8 @@ you publicly humiliated and your code rewritten without notice. An attribute definition is simply:: struct attribute { - char * name; - struct module *owner; + char *name; + struct module *owner; umode_t mode; }; @@ -138,7 +138,7 @@ __ATTR_WO(name): assumes a name_store only and is restricted to mode 0200 that is root write access only. __ATTR_RO_MODE(name, mode): - fore more restrictive RO access currently + for more restrictive RO access; currently only use case is the EFI System Resource Table (see drivers/firmware/efi/esrt.c) __ATTR_RW(name): @@ -207,7 +207,7 @@ IOW, they should take only an object, an attribute, and a buffer as parameters. sysfs allocates a buffer of size (PAGE_SIZE) and passes it to the -method. Sysfs will call the method exactly once for each read or +method. sysfs will call the method exactly once for each read or write. This forces the following behavior on the method implementations: @@ -221,7 +221,7 @@ implementations: be called again, rearmed, to fill the buffer. - On write(2), sysfs expects the entire buffer to be passed during the - first write. Sysfs then passes the entire buffer to the store() method. + first write. sysfs then passes the entire buffer to the store() method. A terminating null is added after the data on stores. This makes functions like sysfs_streq() safe to use. @@ -237,7 +237,7 @@ Other notes: - Writing causes the show() method to be rearmed regardless of current file position. -- The buffer will always be PAGE_SIZE bytes in length. On i386, this +- The buffer will always be PAGE_SIZE bytes in length. On x86, this is 4096. - show() methods should return the number of bytes printed into the @@ -253,7 +253,7 @@ Other notes: through, be sure to return an error. - The object passed to the methods will be pinned in memory via sysfs - referencing counting its embedded object. However, the physical + reference counting its embedded object. However, the physical entity (e.g. device) the object represents may not be present. Be sure to have a way to check this, if necessary. @@ -295,8 +295,12 @@ The top level sysfs directory looks like:: dev/ devices/ firmware/ - net/ fs/ + hypervisor/ + kernel/ + module/ + net/ + power/ devices/ contains a filesystem representation of the device tree. It maps directly to the internal kernel device tree, which is a hierarchy of @@ -317,15 +321,18 @@ span multiple bus types). fs/ contains a directory for some filesystems. Currently each filesystem wanting to export attributes must create its own hierarchy -below fs/ (see ./fuse.txt for an example). +below fs/ (see ./fuse.rst for an example). + +module/ contains parameter values and state information for all +loaded system modules, for both builtin and loadable modules. -dev/ contains two directories char/ and block/. Inside these two +dev/ contains two directories: char/ and block/. Inside these two directories there are symlinks named <major>:<minor>. These symlinks point to the sysfs directory for the given device. /sys/dev provides a quick way to lookup the sysfs interface for a device from the result of a stat(2) operation. -More information can driver-model specific features can be found in +More information on driver-model specific features can be found in Documentation/driver-api/driver-model/. @@ -335,7 +342,7 @@ TODO: Finish this section. Current Interfaces ~~~~~~~~~~~~~~~~~~ -The following interface layers currently exist in sysfs: +The following interface layers currently exist in sysfs. devices (include/linux/device.h) diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index 2b55f71e2ae1..2c15e7053113 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -435,7 +435,7 @@ As of kernel 2.6.22, the following members are defined: const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *); int (*permission) (struct user_namespace *, struct inode *, int); - struct posix_acl * (*get_acl)(struct inode *, int, bool); + 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); ssize_t (*listxattr) (struct dentry *, char *, size_t); @@ -443,7 +443,8 @@ As of kernel 2.6.22, the following members are defined: 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); - int (*set_acl)(struct user_namespace *, struct inode *, struct posix_acl *, int); + 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, struct dentry *dentry, struct fileattr *fa); int (*fileattr_get)(struct dentry *dentry, struct fileattr *fa); diff --git a/Documentation/gpu/amdgpu/amdgpu-glossary.rst b/Documentation/gpu/amdgpu/amdgpu-glossary.rst index 326896e9800d..00a47ebb0b0f 100644 --- a/Documentation/gpu/amdgpu/amdgpu-glossary.rst +++ b/Documentation/gpu/amdgpu/amdgpu-glossary.rst @@ -30,12 +30,35 @@ we have a dedicated glossary for Display Core at EOP End Of Pipe/Pipeline + GART + Graphics Address Remapping Table. This is the name we use for the GPUVM + page table used by the GPU kernel driver. It remaps system resources + (memory or MMIO space) into the GPU's address space so the GPU can access + them. The name GART harkens back to the days of AGP when the platform + provided an MMU that the GPU could use to get a contiguous view of + scattered pages for DMA. The MMU has since moved on to the GPU, but the + name stuck. + GC Graphics and Compute GMC Graphic Memory Controller + GPUVM + GPU Virtual Memory. This is the GPU's MMU. The GPU supports multiple + virtual address spaces that can be in flight at any given time. These + allow the GPU to remap VRAM and system resources into GPU virtual address + spaces for use by the GPU kernel driver and applications using the GPU. + These provide memory protection for different applications using the GPU. + + GTT + Graphics Translation Tables. This is a memory pool managed through TTM + which provides access to system resources (memory or MMIO space) for + use by the GPU. These addresses can be mapped into the "GART" GPUVM page + table for use by the kernel driver or into per process GPUVM page tables + for application usage. + IH Interrupt Handler diff --git a/Documentation/gpu/amdgpu/driver-core.rst b/Documentation/gpu/amdgpu/driver-core.rst index ebf5932845a9..467e6843aef6 100644 --- a/Documentation/gpu/amdgpu/driver-core.rst +++ b/Documentation/gpu/amdgpu/driver-core.rst @@ -148,10 +148,10 @@ PRIME Buffer Sharing MMU Notifier ============ -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_mn.c +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_hmm.c :doc: MMU Notifier -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_mn.c +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_hmm.c :internal: AMDGPU Virtual Memory diff --git a/Documentation/gpu/amdgpu/index.rst b/Documentation/gpu/amdgpu/index.rst index a24e1cfa7407..03c2966cae79 100644 --- a/Documentation/gpu/amdgpu/index.rst +++ b/Documentation/gpu/amdgpu/index.rst @@ -3,7 +3,7 @@ ========================== The drm/amdgpu driver supports all AMD Radeon GPUs based on the Graphics Core -Next (GCN) architecture. +Next (GCN), Radeon DNA (RDNA), and Compute DNA (CDNA) architectures. .. toctree:: diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index dbc85fd7a971..a4860ffd6e86 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -116,6 +116,9 @@ fbdev Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c :export: +.. kernel-doc:: drivers/gpu/drm/drm_fbdev_generic.c + :export: + format Helper Functions Reference ================================= diff --git a/Documentation/gpu/drm-usage-stats.rst b/Documentation/gpu/drm-usage-stats.rst index 92c5117368d7..b46327356e80 100644 --- a/Documentation/gpu/drm-usage-stats.rst +++ b/Documentation/gpu/drm-usage-stats.rst @@ -126,7 +126,6 @@ percentage utilization of the engine, whereas drm-engine-<str> only reflects time active without considering what frequency the engine is operating as a percentage of it's maximum frequency. -=============================== Driver specific implementations =============================== diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 4e59db1cfb00..60ea21734902 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -494,7 +494,7 @@ WOPCM WOPCM Layout ~~~~~~~~~~~~ -.. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.c +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_wopcm.c :doc: WOPCM Layout GuC diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 393d218e4a0c..b2c6aaf1edf2 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -651,17 +651,6 @@ See drivers/gpu/drm/amd/display/TODO for tasks. Contact: Harry Wentland, Alex Deucher -vmwgfx: Replace hashtable with Linux' implementation ----------------------------------------------------- - -The vmwgfx driver uses its own hashtable implementation. Replace the -code with Linux' implementation and update the callers. It's mostly a -refactoring task, but the interfaces are different. - -Contact: Zack Rusin, Thomas Zimmermann <tzimmermann@suse.de> - -Level: Intermediate - Bootsplash ========== diff --git a/Documentation/hwmon/aquacomputer_d5next.rst b/Documentation/hwmon/aquacomputer_d5next.rst index e238533b5fe0..637bdbc8fcad 100644 --- a/Documentation/hwmon/aquacomputer_d5next.rst +++ b/Documentation/hwmon/aquacomputer_d5next.rst @@ -39,7 +39,7 @@ current. The Quadro exposes four physical and sixteen virtual temperature sensors, a flow sensor and four PWM controllable fans, along with their speed (in RPM), power, -voltage and current. +voltage and current. Flow sensor pulses are also available. The Farbwerk and Farbwerk 360 expose four temperature sensors. Additionally, sixteen virtual temperature sensors of the Farbwerk 360 are exposed. @@ -62,7 +62,9 @@ Sysfs entries ================ ============================================================== temp[1-20]_input Physical/virtual temperature sensors (in millidegrees Celsius) +temp[1-4]_offset Temperature sensor correction offset (in millidegrees Celsius) fan[1-8]_input Pump/fan speed (in RPM) / Flow speed (in dL/h) +fan5_pulses Quadro flow sensor pulses power[1-8]_input Pump/fan power (in micro Watts) in[0-7]_input Pump/fan voltage (in milli Volts) curr[1-8]_input Pump/fan current (in milli Amperes) diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index c1d11cf13eef..fe2cc6b73634 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -160,6 +160,7 @@ Hardware Monitoring Kernel Drivers nzxt-kraken2 nzxt-smart2 occ + oxp-sensors pc87360 pc87427 pcf8591 @@ -187,6 +188,7 @@ Hardware Monitoring Kernel Drivers sis5595 sl28cpld smm665 + smpro-hwmon smsc47b397 smsc47m192 smsc47m1 diff --git a/Documentation/hwmon/oxp-sensors.rst b/Documentation/hwmon/oxp-sensors.rst new file mode 100644 index 000000000000..39c588ec5c50 --- /dev/null +++ b/Documentation/hwmon/oxp-sensors.rst @@ -0,0 +1,44 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver oxp-sensors +========================= + +Author: + - 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. + +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. + +Supported devices +----------------- + +Currently the driver supports the following handhelds: + + - AOK ZOE A1 + - OneXPlayer AMD + - OneXPlayer mini AMD + - OneXPlayer mini AMD PRO + +Sysfs entries +------------- + +The following attributes are supported: + +fan1_input + Read Only. Reads current fan RMP. + +pwm1_enable + Read Write. Enable manual fan control. Write "1" to set to manual, write "0" + to let the EC control de fan speed. Read this attribute to see current status. + +pwm1 + Read Write. Read this attribute to see current duty cycle in the range [0-255]. + When pwm1_enable is set to "1" (manual) write any value in the range [0-255] + to set fan speed. diff --git a/Documentation/hwmon/smpro-hwmon.rst b/Documentation/hwmon/smpro-hwmon.rst new file mode 100644 index 000000000000..fb7b3665735b --- /dev/null +++ b/Documentation/hwmon/smpro-hwmon.rst @@ -0,0 +1,102 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +Kernel driver Ampere(R)'s Altra(R) SMpro hwmon +============================================== + +Supported chips: + + * Ampere(R) Altra(R) + + Prefix: ``smpro`` + + Reference: `Altra SoC BMC Interface Specification` + +Author: Thu Nguyen <thu@os.amperecomputing.com> + +Description +----------- +The smpro-hwmon driver supports hardware monitoring for Ampere(R) Altra(R) +SoCs based on the SMpro co-processor (SMpro). The following sensor metrics +are supported by the driver: + + * temperature + * voltage + * current + * power + +The interface provides the registers to query the various sensors and +their values which are then exported to userspace by this driver. + +Usage Notes +----------- + +The driver creates at least two sysfs files for each sensor. + +* ``<sensor_type><idx>_label`` reports the sensor label. +* ``<sensor_type><idx>_input`` returns the sensor value. + +The sysfs files are allocated in the SMpro rootfs folder, with one root +directory for each instance. + +When the SoC is turned off, the driver will fail to read registers and +return ``-ENXIO``. + +Sysfs entries +------------- + +The following sysfs files are supported: + +* Ampere(R) Altra(R): + + ============ ============= ====== =============================================== + Name Unit Perm Description + ============ ============= ====== =============================================== + temp1_input millicelsius RO SoC temperature + temp2_input millicelsius RO Max temperature reported among SoC VRDs + temp2_crit millicelsius RO SoC VRD HOT Threshold temperature + temp3_input millicelsius RO Max temperature reported among DIMM VRDs + temp4_input millicelsius RO Max temperature reported among Core VRDs + temp5_input millicelsius RO Temperature of DIMM0 on CH0 + temp5_crit millicelsius RO MEM HOT Threshold for all DIMMs + temp6_input millicelsius RO Temperature of DIMM0 on CH1 + temp6_crit millicelsius RO MEM HOT Threshold for all DIMMs + temp7_input millicelsius RO Temperature of DIMM0 on CH2 + temp7_crit millicelsius RO MEM HOT Threshold for all DIMMs + temp8_input millicelsius RO Temperature of DIMM0 on CH3 + temp8_crit millicelsius RO MEM HOT Threshold for all DIMMs + temp9_input millicelsius RO Temperature of DIMM0 on CH4 + temp9_crit millicelsius RO MEM HOT Threshold for all DIMMs + temp10_input millicelsius RO Temperature of DIMM0 on CH5 + temp10_crit millicelsius RO MEM HOT Threshold for all DIMMs + temp11_input millicelsius RO Temperature of DIMM0 on CH6 + temp11_crit millicelsius RO MEM HOT Threshold for all DIMMs + temp12_input millicelsius RO Temperature of DIMM0 on CH7 + temp12_crit millicelsius RO MEM HOT Threshold for all DIMMs + temp13_input millicelsius RO Max temperature reported among RCA VRDs + in0_input millivolts RO Core voltage + in1_input millivolts RO SoC voltage + in2_input millivolts RO DIMM VRD1 voltage + in3_input millivolts RO DIMM VRD2 voltage + in4_input millivolts RO RCA VRD voltage + cur1_input milliamperes RO Core VRD current + cur2_input milliamperes RO SoC VRD current + cur3_input milliamperes RO DIMM VRD1 current + cur4_input milliamperes RO DIMM VRD2 current + cur5_input milliamperes RO RCA VRD current + power1_input microwatts RO Core VRD power + power2_input microwatts RO SoC VRD power + power3_input microwatts RO DIMM VRD1 power + power4_input microwatts RO DIMM VRD2 power + power5_input microwatts RO RCA VRD power + ============ ============= ====== =============================================== + + Example:: + + # cat in0_input + 830 + # cat temp1_input + 37000 + # cat curr1_input + 9000 + # cat power5_input + 19500000 diff --git a/Documentation/ia64/aliasing.rst b/Documentation/ia64/aliasing.rst index a08b36aba015..36a1e1d4842b 100644 --- a/Documentation/ia64/aliasing.rst +++ b/Documentation/ia64/aliasing.rst @@ -61,7 +61,7 @@ Memory Map The efi_memmap table is preserved unmodified because the original boot-time information is required for kexec. -Kernel Identify Mappings +Kernel Identity Mappings ======================== Linux/ia64 identity mappings are done with large pages, currently diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst index 6805ae6e86e6..c756786e17ae 100644 --- a/Documentation/kernel-hacking/locking.rst +++ b/Documentation/kernel-hacking/locking.rst @@ -967,7 +967,7 @@ you might do the following:: while (list) { struct foo *next = list->next; - del_timer(&list->timer); + timer_delete(&list->timer); kfree(list); list = next; } @@ -981,7 +981,7 @@ the lock after we spin_unlock_bh(), and then try to free the element (which has already been freed!). This can be avoided by checking the result of -del_timer(): if it returns 1, the timer has been deleted. +timer_delete(): if it returns 1, the timer has been deleted. If 0, it means (in this case) that it is currently running, so we can do:: @@ -990,7 +990,7 @@ do:: while (list) { struct foo *next = list->next; - if (!del_timer(&list->timer)) { + if (!timer_delete(&list->timer)) { /* Give timer a chance to delete this */ spin_unlock_bh(&list_lock); goto retry; @@ -1005,9 +1005,12 @@ do:: Another common problem is deleting timers which restart themselves (by calling add_timer() at the end of their timer function). Because this is a fairly common case which is prone to races, you should -use del_timer_sync() (``include/linux/timer.h``) to -handle this case. It returns the number of times the timer had to be -deleted before we finally stopped it from adding itself back in. +use timer_delete_sync() (``include/linux/timer.h``) to handle this case. + +Before freeing a timer, timer_shutdown() or timer_shutdown_sync() should be +called which will keep it from being rearmed. Any subsequent attempt to +rearm the timer will be silently ignored by the core code. + Locking Speed ============= @@ -1335,7 +1338,7 @@ lock. - kfree() -- add_timer() and del_timer() +- add_timer() and timer_delete() Mutex API reference =================== diff --git a/Documentation/loongarch/booting.rst b/Documentation/loongarch/booting.rst new file mode 100644 index 000000000000..91eccd410478 --- /dev/null +++ b/Documentation/loongarch/booting.rst @@ -0,0 +1,42 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================= +Booting Linux/LoongArch +======================= + +:Author: Yanteng Si <siyanteng@loongson.cn> +:Date: 18 Nov 2022 + +Information passed from BootLoader to kernel +============================================ + +LoongArch supports ACPI and FDT. The information that needs to be passed +to the kernel includes the memmap, the initrd, the command line, optionally +the ACPI/FDT tables, and so on. + +The kernel is passed the following arguments on `kernel_entry` : + + - a0 = efi_boot: `efi_boot` is a flag indicating whether + this boot environment is fully UEFI-compliant. + + - a1 = cmdline: `cmdline` is a pointer to the kernel command line. + + - a2 = systemtable: `systemtable` points to the EFI system table. + All pointers involved at this stage are in physical addresses. + +Header of Linux/LoongArch kernel images +======================================= + +Linux/LoongArch kernel images are EFI images. Being PE files, they have +a 64-byte header structured like:: + + u32 MZ_MAGIC /* "MZ", MS-DOS header */ + u32 res0 = 0 /* Reserved */ + u64 kernel_entry /* Kernel entry point */ + u64 _end - _text /* Kernel image effective size */ + u64 load_offset /* Kernel image load offset from start of RAM */ + u64 res1 = 0 /* Reserved */ + u64 res2 = 0 /* Reserved */ + u64 res3 = 0 /* Reserved */ + u32 LINUX_PE_MAGIC /* Magic number */ + u32 pe_header - _head /* Offset to the PE header */ diff --git a/Documentation/loongarch/index.rst b/Documentation/loongarch/index.rst index aaba648db907..c779bfa00c05 100644 --- a/Documentation/loongarch/index.rst +++ b/Documentation/loongarch/index.rst @@ -9,6 +9,7 @@ LoongArch Architecture :numbered: introduction + booting irq-chip-model features diff --git a/Documentation/loongarch/introduction.rst b/Documentation/loongarch/introduction.rst index 6c9160c4e9be..49135d451ced 100644 --- a/Documentation/loongarch/introduction.rst +++ b/Documentation/loongarch/introduction.rst @@ -375,15 +375,15 @@ Developer web site of Loongson and LoongArch (Software and Documentation): Documentation of LoongArch ISA: - https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.00-CN.pdf (in Chinese) + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.02-CN.pdf (in Chinese) - https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.00-EN.pdf (in English) + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.02-EN.pdf (in English) Documentation of LoongArch ELF psABI: - https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v1.00-CN.pdf (in Chinese) + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.00-CN.pdf (in Chinese) - https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v1.00-EN.pdf (in English) + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.00-EN.pdf (in English) Linux kernel repository of Loongson and LoongArch: diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index 06f80e3785c5..cc621decd943 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -1966,7 +1966,7 @@ There are some more advanced barrier functions: (*) io_stop_wc(); For memory accesses with write-combining attributes (e.g. those returned - by ioremap_wc(), the CPU may wait for prior accesses to be merged with + by ioremap_wc()), the CPU may wait for prior accesses to be merged with subsequent ones. io_stop_wc() can be used to prevent the merging of write-combining memory accesses before this macro with those after it when such wait has performance implications. diff --git a/Documentation/mm/arch_pgtable_helpers.rst b/Documentation/mm/arch_pgtable_helpers.rst index cbaee9e59241..fd2a19df884e 100644 --- a/Documentation/mm/arch_pgtable_helpers.rst +++ b/Documentation/mm/arch_pgtable_helpers.rst @@ -94,7 +94,7 @@ PMD Page Table Helpers +---------------------------+--------------------------------------------------+ | pmd_trans_huge | Tests a Transparent Huge Page (THP) at PMD | +---------------------------+--------------------------------------------------+ -| pmd_present | Tests a valid mapped PMD | +| pmd_present | Tests whether pmd_page() points to valid memory | +---------------------------+--------------------------------------------------+ | pmd_young | Tests a young PMD | +---------------------------+--------------------------------------------------+ diff --git a/Documentation/mm/slub.rst b/Documentation/mm/slub.rst index 4e1578186b4f..7f652216dabe 100644 --- a/Documentation/mm/slub.rst +++ b/Documentation/mm/slub.rst @@ -116,6 +116,8 @@ options from the ``slub_debug`` parameter translate to the following files:: T trace A failslab +failslab file is writable, so writing 1 or 0 will enable or disable +the option at runtime. Write returns -EINVAL if cache is an alias. Careful with tracing: It may spew out lots of information and never stop if used on the wrong slab. diff --git a/Documentation/mm/transhuge.rst b/Documentation/mm/transhuge.rst index 216db1d67d04..ec3dc5b04226 100644 --- a/Documentation/mm/transhuge.rst +++ b/Documentation/mm/transhuge.rst @@ -117,31 +117,15 @@ pages: - ->_refcount in tail pages is always zero: get_page_unless_zero() never succeeds on tail pages. - - map/unmap of the pages with PTE entry increment/decrement ->_mapcount - on relevant sub-page of the compound page. - - - map/unmap of the whole compound page is accounted for in compound_mapcount - (stored in first tail page). For file huge pages, we also increment - ->_mapcount of all sub-pages in order to have race-free detection of - last unmap of subpages. - -PageDoubleMap() indicates that the page is *possibly* mapped with PTEs. - -For anonymous pages, PageDoubleMap() also indicates ->_mapcount in all -subpages is offset up by one. This additional reference is required to -get race-free detection of unmap of subpages when we have them mapped with -both PMDs and PTEs. - -This optimization is required to lower the overhead of per-subpage mapcount -tracking. The alternative is to alter ->_mapcount in all subpages on each -map/unmap of the whole compound page. - -For anonymous pages, we set PG_double_map when a PMD of the page is split -for the first time, but still have a PMD mapping. The additional references -go away with the last compound_mapcount. - -File pages get PG_double_map set on the first map of the page with PTE and -goes away when the page gets evicted from the page cache. + - 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 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. 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 diff --git a/Documentation/networking/bonding.rst b/Documentation/networking/bonding.rst index 96cd7a26f3d9..adc4bf4f3c50 100644 --- a/Documentation/networking/bonding.rst +++ b/Documentation/networking/bonding.rst @@ -566,7 +566,8 @@ miimon link monitoring. A value of 100 is a good starting point. The use_carrier option, below, affects how the link state is determined. See the High Availability section for additional - information. The default value is 0. + information. The default value is 100 if arp_interval is not + set. min_links @@ -956,6 +957,7 @@ xmit_hash_policy hash = hash XOR source IP XOR destination IP hash = hash XOR (hash RSHIFT 16) hash = hash XOR (hash RSHIFT 8) + hash = hash RSHIFT 1 And then hash is reduced modulo slave count. If the protocol is IPv6 then the source and destination diff --git a/Documentation/networking/can.rst b/Documentation/networking/can.rst index ebc822e605f5..90121deef217 100644 --- a/Documentation/networking/can.rst +++ b/Documentation/networking/can.rst @@ -1148,6 +1148,39 @@ tuning on deep embedded systems'. The author is running a MPC603e load without any problems ... +Switchable Termination Resistors +-------------------------------- + +CAN bus requires a specific impedance across the differential pair, +typically provided by two 120Ohm resistors on the farthest nodes of +the bus. Some CAN controllers support activating / deactivating a +termination resistor(s) to provide the correct impedance. + +Query the available resistances:: + + $ ip -details link show can0 + ... + termination 120 [ 0, 120 ] + +Activate the terminating resistor:: + + $ ip link set dev can0 type can termination 120 + +Deactivate the terminating resistor:: + + $ ip link set dev can0 type can termination 0 + +To enable termination resistor support to a can-controller, either +implement in the controller's struct can-priv:: + + termination_const + termination_const_cnt + do_set_termination + +or add gpio control with the device tree entries from +Documentation/devicetree/bindings/net/can/can-controller.yaml + + The Virtual CAN Driver (vcan) ----------------------------- 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 51e6624fb774..1d2f55feca24 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 @@ -181,10 +181,13 @@ when necessary using the below listed API:: - int dpaa2_mac_connect(struct dpaa2_mac *mac); - void dpaa2_mac_disconnect(struct dpaa2_mac *mac); -A phylink integration is necessary only when the partner DPMAC is not of TYPE_FIXED. -One can check for this condition using the below API:: +A phylink integration is necessary only when the partner DPMAC is not of +``TYPE_FIXED``. This means it is either of ``TYPE_PHY``, or of +``TYPE_BACKPLANE`` (the difference being the two that in the ``TYPE_BACKPLANE`` +mode, the MC firmware does not access the PCS registers). One can check for +this condition using the following helper:: - - bool dpaa2_mac_is_type_fixed(struct fsl_mc_device *dpmac_dev,struct fsl_mc_io *mc_io); + - static inline bool dpaa2_mac_is_type_phy(struct dpaa2_mac *mac); Before connection to a MAC, the caller must allocate and populate the dpaa2_mac structure with the associated net_device, a pointer to the MC portal diff --git a/Documentation/networking/device_drivers/ethernet/marvell/octeon_ep.rst b/Documentation/networking/device_drivers/ethernet/marvell/octeon_ep.rst index bc562c49011b..cad96c8d1f97 100644 --- a/Documentation/networking/device_drivers/ethernet/marvell/octeon_ep.rst +++ b/Documentation/networking/device_drivers/ethernet/marvell/octeon_ep.rst @@ -23,6 +23,7 @@ Supported Devices ================= Currently, this driver support following devices: * Network controller: Cavium, Inc. Device b200 + * Network controller: Cavium, Inc. Device b400 Interface Control ================= diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst index 5edf50d7dbd5..6969652f593c 100644 --- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst @@ -25,7 +25,7 @@ Enabling the driver and kconfig options | 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. +| For the list of advanced features, please see below. **CONFIG_MLX5_CORE=(y/m/n)** (module mlx5_core.ko) @@ -89,11 +89,11 @@ Enabling the driver and kconfig options **CONFIG_MLX5_EN_IPSEC=(y/n)** -| Enables `IPSec XFRM cryptography-offload accelaration <http://www.mellanox.com/related-docs/prod_software/Mellanox_Innova_IPsec_Ethernet_Adapter_Card_User_Manual.pdf>`_. +| 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 accelaration. +| TLS cryptography-offload acceleration. **CONFIG_MLX5_INFINIBAND=(y/n/m)** (module mlx5_ib.ko) @@ -139,14 +139,14 @@ 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. +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. +the driver directly into hardware without firmware intervention. -SMFS mode is faster and provides better rule inserstion rate compared to default DMFS mode. +SMFS mode is faster and provides better rule insertion rate compared to default DMFS mode. User command examples: @@ -165,9 +165,9 @@ User command examples: 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. +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. +To change RoCE enablement state, a user must change the driverinit cmode value and run devlink reload. User command examples: @@ -186,7 +186,7 @@ User command examples: esw_port_metadata: Eswitch port metadata state ---------------------------------------------- -When applicable, disabling Eswitch metadata can increase packet rate +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 @@ -253,26 +253,26 @@ 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 +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 +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 ther other subfunctions or the parent PCI function. This ensures that all -devices (netdev, rdma, vdpa etc.) of the subfunction accesses only assigned +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 +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:: +Example mlx5 software, system, and device view:: _______ | admin | @@ -310,7 +310,7 @@ Example mlx5 software, system and device view:: | (device add/del) _____|____ ____|________ | | | subfunction | - | PCI NIC |---- activate/deactive events---->| host driver | + | PCI NIC |--- activate/deactivate events--->| host driver | |__________| | (mlx5_core) | |_____________| @@ -320,7 +320,7 @@ Subfunction is created using devlink port interface. $ devlink dev eswitch set pci/0000:06:00.0 mode switchdev -- Add a devlink port of subfunction flaovur:: +- 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 @@ -351,46 +351,30 @@ driver. MAC address setup ----------------- -mlx5 driver provides mechanism to setup the MAC address of the PCI VF/SF. +mlx5 driver support devlink port function attr mechanism to setup MAC +address. (refer to Documentation/networking/devlink/devlink-port.rst) -The configured MAC address of the PCI VF/SF will be used by netdevice and rdma -device created for the PCI VF/SF. +RoCE capability setup +--------------------- +Not all mlx5 PCI devices/SFs require RoCE capability. -- Get the MAC address of the VF identified by its unique devlink port index:: +When RoCE capability is disabled, it saves 1 Mbytes worth of system memory per +PCI devices/SF. - $ devlink port show pci/0000:06:00.0/2 - pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1 - function: - hw_addr 00:00:00:00:00:00 - -- Set the MAC address of the VF identified by its unique devlink port index:: - - $ devlink port function set pci/0000:06:00.0/2 hw_addr 00:11:22:33:44:55 - - $ devlink port show pci/0000:06:00.0/2 - pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1 - function: - hw_addr 00:11:22:33:44:55 +mlx5 driver support devlink port function attr mechanism to setup RoCE +capability. (refer to Documentation/networking/devlink/devlink-port.rst) -- Get the MAC address of the SF identified by its unique devlink port index:: +migratable capability setup +--------------------------- +User who wants mlx5 PCI VFs to be able to perform live migration need to +explicitly enable the VF migratable capability. - $ 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 - -- Set the MAC address of the VF identified by its unique devlink port index:: - - $ devlink port function set pci/0000:06:00.0/32768 hw_addr 00:00:00:00:88:88 - - $ devlink port show pci/0000:06:00.0/32768 - pci/0000:06:00.0/32768: type eth netdev enp6s0pf0sf88 flavour pcivf pfnum 0 sfnum 88 - function: - hw_addr 00:00:00:00:88:88 +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 active the SF using the SF function state +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:: @@ -447,7 +431,7 @@ for it. 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 visiblity to the user to decide when is it +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:: @@ -464,14 +448,14 @@ tx reporter ----------- The tx reporter is responsible for reporting and recovering of the following two error scenarios: -- TX timeout +- tx timeout Report on kernel tx timeout detection. Recover by searching lost interrupts. -- TX error completion +- tx error completion Report on error tx completion. - Recover by flushing the TX queue and reset it. + Recover by flushing the tx queue and reset it. -TX reporter also support on demand diagnose callback, on which it provides +tx reporter also support on demand diagnose callback, on which it provides real time information of its send queues status. User commands examples: @@ -491,32 +475,32 @@ rx reporter ----------- The rx reporter is responsible for reporting and recovering of the following two error scenarios: -- RX queues initialization (population) timeout - RX queues descriptors population 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 it - could be recoverable by polling the EQ (Event Queue). -- RX completions with errors (reported by HW on interrupt context) +- 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. +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:: +- 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. +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:: + 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. +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 @@ -537,7 +521,7 @@ 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. +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. @@ -552,7 +536,7 @@ User commands examples: $ devlink health recover pci/0000:82:00.0 reporter fw_fatal -- Read FW CR-space dump if already strored or trigger new one:: +- Read FW CR-space dump if already stored or trigger new one:: $ devlink health dump show pci/0000:82:00.1 reporter fw_fatal @@ -561,10 +545,10 @@ NOTE: This command can run only on PF. mlx5 tracepoints ================ -mlx5 driver provides internal trace points for tracking and debugging using +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/ +For the list of support mlx5 events, check `/sys/kernel/debug/tracing/events/mlx5/`. tc and eswitch offloads tracepoints: diff --git a/Documentation/networking/device_drivers/ethernet/netronome/nfp.rst b/Documentation/networking/device_drivers/ethernet/netronome/nfp.rst index ada611fb427c..650b57742d51 100644 --- a/Documentation/networking/device_drivers/ethernet/netronome/nfp.rst +++ b/Documentation/networking/device_drivers/ethernet/netronome/nfp.rst @@ -1,50 +1,57 @@ .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +.. include:: <isonum.txt> -============================================= -Netronome Flow Processor (NFP) Kernel Drivers -============================================= +=========================================== +Network Flow Processor (NFP) Kernel Drivers +=========================================== -Copyright (c) 2019, Netronome Systems, Inc. +:Copyright: |copy| 2019, Netronome Systems, Inc. +:Copyright: |copy| 2022, Corigine, Inc. Contents ======== - `Overview`_ - `Acquiring Firmware`_ +- `Devlink Info`_ +- `Configure Device`_ +- `Statistics`_ Overview ======== -This driver supports Netronome's line of Flow Processor devices, -including the NFP4000, NFP5000, and NFP6000 models, which are also -incorporated in the company's family of Agilio SmartNICs. The SR-IOV -physical and virtual functions for these devices are supported by -the driver. +This driver supports Netronome and Corigine's line of Network Flow Processor +devices, including the NFP3800, NFP4000, NFP5000, and NFP6000 models, which +are also incorporated in the companies' family of Agilio SmartNICs. The SR-IOV +physical and virtual functions for these devices are supported by the driver. Acquiring Firmware ================== -The NFP4000 and NFP6000 devices require application specific firmware -to function. Application firmware can be located either on the host file system +The NFP3800, NFP4000 and NFP6000 devices require application specific firmware +to function. Application firmware can be located either on the host file system or in the device flash (if supported by management firmware). Firmware files on the host filesystem contain card type (`AMDA-*` string), media -config etc. They should be placed in `/lib/firmware/netronome` directory to +config etc. They should be placed in `/lib/firmware/netronome` directory to load firmware from the host file system. Firmware for basic NIC operation is available in the upstream `linux-firmware.git` repository. +A more comprehensive list of firmware can be downloaded from the +`Corigine Support site <https://www.corigine.com/DPUDownload.html>`_. + Firmware in NVRAM ----------------- Recent versions of management firmware supports loading application -firmware from flash when the host driver gets probed. The firmware loading +firmware from flash when the host driver gets probed. The firmware loading policy configuration may be used to configure this feature appropriately. Devlink or ethtool can be used to update the application firmware on the device flash by providing the appropriate `nic_AMDA*.nffw` file to the respective -command. Users need to take care to write the correct firmware image for the +command. Users need to take care to write the correct firmware image for the card and media configuration to flash. Available storage space in flash depends on the card being used. @@ -79,9 +86,9 @@ You may need to use hard instead of symbolic links on distributions which use old `mkinitrd` command instead of `dracut` (e.g. Ubuntu). After changing firmware files you may need to regenerate the initramfs -image. Initramfs contains drivers and firmware files your system may -need to boot. Refer to the documentation of your distribution to find -out how to update initramfs. Good indication of stale initramfs +image. Initramfs contains drivers and firmware files your system may +need to boot. Refer to the documentation of your distribution to find +out how to update initramfs. Good indication of stale initramfs is system loading wrong driver or firmware on boot, but when driver is later reloaded manually everything works correctly. @@ -89,9 +96,9 @@ Selecting firmware per device ----------------------------- Most commonly all cards on the system use the same type of firmware. -If you want to load specific firmware image for a specific card, you -can use either the PCI bus address or serial number. Driver will print -which files it's looking for when it recognizes a NFP device:: +If you want to load a specific firmware image for a specific card, you +can use either the PCI bus address or serial number. The driver will +print which files it's looking for when it recognizes a NFP device:: nfp: Looking for firmware file in order of priority: nfp: netronome/serial-00-12-34-aa-bb-cc-10-ff.nffw: not found @@ -106,6 +113,15 @@ Note that `serial-*` and `pci-*` files are **not** automatically included in initramfs, you will have to refer to documentation of appropriate tools to find out how to include them. +Running firmware version +------------------------ + +The version of the loaded firmware for a particular <netdev> interface, +(e.g. enp4s0), or an interface's port <netdev port> (e.g. enp4s0np0) can +be displayed with the ethtool command:: + + $ ethtool -i <netdev> + Firmware loading policy ----------------------- @@ -132,6 +148,115 @@ abi_drv_load_ifc Defines a list of PF devices allowed to load FW on the device. This variable is not currently user configurable. +Devlink Info +============ + +The devlink info command displays the running and stored firmware versions +on the device, serial number and board information. + +Devlink info command example (replace PCI address):: + + $ devlink dev info pci/0000:03:00.0 + pci/0000:03:00.0: + driver nfp + serial_number CSAAMDA2001-1003000111 + versions: + fixed: + board.id AMDA2001-1003 + board.rev 01 + board.manufacture CSA + board.model mozart + running: + fw.mgmt 22.10.0-rc3 + fw.cpld 0x1000003 + fw.app nic-22.09.0 + chip.init AMDA-2001-1003 1003000111 + stored: + fw.bundle_id bspbundle_1003000111 + fw.mgmt 22.10.0-rc3 + fw.cpld 0x0 + chip.init AMDA-2001-1003 1003000111 + +Configure Device +================ + +This section explains how to use Agilio SmartNICs running basic NIC firmware. + +Configure interface link-speed +------------------------------ +The following steps explains how to change between 10G mode and 25G mode on +Agilio CX 2x25GbE cards. The changing of port speed must be done in order, +port 0 (p0) must be set to 10G before port 1 (p1) may be set to 10G. + +Down the respective interface(s):: + + $ ip link set dev <netdev port 0> down + $ ip link set dev <netdev port 1> down + +Set interface link-speed to 10G:: + + $ ethtool -s <netdev port 0> speed 10000 + $ ethtool -s <netdev port 1> speed 10000 + +Set interface link-speed to 25G:: + + $ ethtool -s <netdev port 0> speed 25000 + $ ethtool -s <netdev port 1> speed 25000 + +Reload driver for changes to take effect:: + + $ rmmod nfp; modprobe nfp + +Configure interface Maximum Transmission Unit (MTU) +--------------------------------------------------- + +The MTU of interfaces can temporarily be set using the iproute2, ip link or +ifconfig tools. Note that this change will not persist. Setting this via +Network Manager, or another appropriate OS configuration tool, is +recommended as changes to the MTU using Network Manager can be made to +persist. + +Set interface MTU to 9000 bytes:: + + $ ip link set dev <netdev port> mtu 9000 + +It is the responsibility of the user or the orchestration layer to set +appropriate MTU values when handling jumbo frames or utilizing tunnels. For +example, if packets sent from a VM are to be encapsulated on the card and +egress a physical port, then the MTU of the VF should be set to lower than +that of the physical port to account for the extra bytes added by the +additional header. If a setup is expected to see fallback traffic between +the SmartNIC and the kernel then the user should also ensure that the PF MTU +is appropriately set to avoid unexpected drops on this path. + +Configure Forward Error Correction (FEC) modes +---------------------------------------------- + +Agilio SmartNICs support FEC mode configuration, e.g. Auto, Firecode Base-R, +ReedSolomon and Off modes. Each physical port's FEC mode can be set +independently using ethtool. The supported FEC modes for an interface can +be viewed using:: + + $ ethtool <netdev> + +The currently configured FEC mode can be viewed using:: + + $ ethtool --show-fec <netdev> + +To force the FEC mode for a particular port, auto-negotiation must be disabled +(see the `Auto-negotiation`_ section). An example of how to set the FEC mode +to Reed-Solomon is:: + + $ ethtool --set-fec <netdev> encoding rs + +Auto-negotiation +---------------- + +To change auto-negotiation settings, the link must first be put down. After the +link is down, auto-negotiation can be enabled or disabled using:: + + ethtool -s <netdev> autoneg <on|off> + Statistics ========== diff --git a/Documentation/networking/devlink/devlink-info.rst b/Documentation/networking/devlink/devlink-info.rst index 7572bf6de5c1..1242b0e6826b 100644 --- a/Documentation/networking/devlink/devlink-info.rst +++ b/Documentation/networking/devlink/devlink-info.rst @@ -198,6 +198,11 @@ fw.bundle_id Unique identifier of the entire firmware bundle. +fw.bootloader +------------- + +Version of the bootloader. + Future work =========== diff --git a/Documentation/networking/devlink/devlink-port.rst b/Documentation/networking/devlink/devlink-port.rst index 7627b1da01f2..3da590953ce8 100644 --- a/Documentation/networking/devlink/devlink-port.rst +++ b/Documentation/networking/devlink/devlink-port.rst @@ -110,7 +110,7 @@ devlink ports for both the controllers. Function configuration ====================== -A user can configure the function attribute before enumerating the PCI +Users can configure one or more function attributes before enumerating the PCI function. Usually it means, user should configure function attribute before a bus specific device for the function is created. However, when SRIOV is enabled, virtual function devices are created on the PCI bus. @@ -119,9 +119,127 @@ function device to the driver. For subfunctions, this means user should configure port function attribute before activating the port function. A user may set the hardware address of the function using -'devlink port function set hw_addr' command. For Ethernet port function +`devlink port function set hw_addr` command. For Ethernet port function this means a MAC address. +Users may also set the RoCE capability of the function using +`devlink port function set roce` command. + +Users may also set the function as migratable using +'devlink port function set migratable' command. + +Function attributes +=================== + +MAC address setup +----------------- +The configured MAC address of the PCI VF/SF will be used by netdevice and rdma +device created for the PCI VF/SF. + +- Get the MAC address of the VF identified by its unique devlink port index:: + + $ devlink port show pci/0000:06:00.0/2 + pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1 + function: + hw_addr 00:00:00:00:00:00 + +- Set the MAC address of the VF identified by its unique devlink port index:: + + $ devlink port function set pci/0000:06:00.0/2 hw_addr 00:11:22:33:44:55 + + $ devlink port show pci/0000:06:00.0/2 + pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1 + function: + hw_addr 00:11:22:33:44:55 + +- Get the MAC address of the SF identified by its unique devlink port index:: + + $ 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 + +- Set the MAC address of the SF identified by its unique devlink port index:: + + $ devlink port function set pci/0000:06:00.0/32768 hw_addr 00:00:00:00:88:88 + + $ 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:88:88 + +RoCE capability setup +--------------------- +Not all PCI VFs/SFs require RoCE capability. + +When RoCE capability is disabled, it saves system memory per PCI VF/SF. + +When user disables RoCE capability for a VF/SF, user application cannot send or +receive any RoCE packets through this VF/SF and RoCE GID table for this PCI +will be empty. + +When RoCE capability is disabled in the device using port function attribute, +VF/SF driver cannot override it. + +- Get RoCE capability of the VF device:: + + $ devlink port show pci/0000:06:00.0/2 + pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1 + function: + hw_addr 00:00:00:00:00:00 roce enable + +- Set RoCE capability of the VF device:: + + $ devlink port function set pci/0000:06:00.0/2 roce disable + + $ devlink port show pci/0000:06:00.0/2 + pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1 + function: + hw_addr 00:00:00:00:00:00 roce disable + +migratable capability setup +--------------------------- +Live migration is the process of transferring a live virtual machine +from one physical host to another without disrupting its normal +operation. + +User who want PCI VFs to be able to perform live migration need to +explicitly enable the VF migratable capability. + +When user enables migratable capability for a VF, and the HV binds the VF to VFIO driver +with migration support, the user can migrate the VM with this VF from one HV to a +different one. + +However, when migratable capability is enable, device will disable features which cannot +be migrated. Thus migratable cap can impose limitations on a VF so let the user decide. + +Example of LM with migratable function configuration: +- Get migratable capability of the VF device:: + + $ devlink port show pci/0000:06:00.0/2 + pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1 + function: + hw_addr 00:00:00:00:00:00 migratable disable + +- Set migratable capability of the VF device:: + + $ devlink port function set pci/0000:06:00.0/2 migratable enable + + $ devlink port show pci/0000:06:00.0/2 + pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1 + function: + hw_addr 00:00:00:00:00:00 migratable enable + +- Bind VF to VFIO driver with migration support:: + + $ echo <pci_id> > /sys/bus/pci/devices/0000:08:00.0/driver/unbind + $ echo mlx5_vfio_pci > /sys/bus/pci/devices/0000:08:00.0/driver_override + $ echo <pci_id> > /sys/bus/pci/devices/0000:08:00.0/driver/bind + +Attach VF to the VM. +Start the VM. +Perform live migration. + Subfunction ============ @@ -130,10 +248,11 @@ it is deployed. Subfunction is created and deployed in unit of 1. Unlike SRIOV VFs, a subfunction doesn't require its own PCI virtual function. A subfunction communicates with the hardware through the parent PCI function. -To use a subfunction, 3 steps setup sequence is followed. -(1) create - create a subfunction; -(2) configure - configure subfunction attributes; -(3) deploy - deploy the subfunction; +To use a subfunction, 3 steps setup sequence is followed: + +1) create - create a subfunction; +2) configure - configure subfunction attributes; +3) deploy - deploy the subfunction; Subfunction management is done using devlink port user interface. User performs setup on the subfunction management device. @@ -191,13 +310,48 @@ API allows to configure following rate object's parameters: ``tx_max`` Maximum TX rate value. +``tx_priority`` + Allows for usage of strict priority arbiter among siblings. This + arbitration scheme attempts to schedule nodes based on their priority + as long as the nodes remain within their bandwidth limit. The higher the + priority the higher the probability that the node will get selected for + scheduling. + +``tx_weight`` + Allows for usage of Weighted Fair Queuing arbitration scheme among + siblings. This arbitration scheme can be used simultaneously with the + strict priority. As a node is configured with a higher rate it gets more + BW relative to it's siblings. Values are relative like a percentage + points, they basically tell how much BW should node take relative to + it's siblings. + ``parent`` Parent node name. Parent node rate limits are considered as additional limits to all node children limits. ``tx_max`` is an upper limit for children. ``tx_share`` is a total bandwidth distributed among children. +``tx_priority`` and ``tx_weight`` can be used simultaneously. In that case +nodes with the same priority form a WFQ subgroup in the sibling group +and arbitration among them is based on assigned weights. + +Arbitration flow from the high level: + +#. Choose a node, or group of nodes with the highest priority that stays + within the BW limit and are not blocked. Use ``tx_priority`` as a + parameter for this arbitration. + +#. If group of nodes have the same priority perform WFQ arbitration on + that subgroup. Use ``tx_weight`` as a parameter for this arbitration. + +#. Select the winner node, and continue arbitration flow among it's children, + until leaf node is reached, and the winner is established. + +#. If all the nodes from the highest priority sub-group are satisfied, or + overused their assigned BW, move to the lower priority nodes. + Driver implementations are allowed to support both or either rate object types -and setting methods of their parameters. +and setting methods of their parameters. Additionally driver implementation +may export nodes/leafs and their child-parent relationships. Terms and Definitions ===================== diff --git a/Documentation/networking/devlink/devlink-region.rst b/Documentation/networking/devlink/devlink-region.rst index f06dca9a1eb6..9232cd7da301 100644 --- a/Documentation/networking/devlink/devlink-region.rst +++ b/Documentation/networking/devlink/devlink-region.rst @@ -31,6 +31,15 @@ in its ``devlink_region_ops`` structure. If snapshot id is not set in the ``DEVLINK_CMD_REGION_NEW`` request kernel will allocate one and send the snapshot information to user space. +Regions may optionally allow directly reading from their contents without a +snapshot. Direct read requests are not atomic. In particular a read request +of size 256 bytes or larger will be split into multiple chunks. If atomic +access is required, use a snapshot. A driver wishing to enable this for a +region should implement the ``.read`` callback in the ``devlink_region_ops`` +structure. User space can request a direct read by using the +``DEVLINK_ATTR_REGION_DIRECT`` attribute instead of specifying a snapshot +id. + example usage ------------- @@ -65,6 +74,10 @@ example usage $ devlink region read pci/0000:00:05.0/fw-health snapshot 1 address 0 length 16 0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30 + # Read from the region without a snapshot + $ devlink region read pci/0000:00:05.0/fw-health address 16 length 16 + 0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8 + As regions are likely very device or driver specific, no generic regions are defined. See the driver-specific documentation files for information on the specific regions a driver supports. diff --git a/Documentation/networking/devlink/devlink-trap.rst b/Documentation/networking/devlink/devlink-trap.rst index 90d1381b88de..2c14dfe69b3a 100644 --- a/Documentation/networking/devlink/devlink-trap.rst +++ b/Documentation/networking/devlink/devlink-trap.rst @@ -485,6 +485,16 @@ be added to the following table: - Traps incoming packets that the device decided to drop because the destination MAC is not configured in the MAC table and the interface is not in promiscuous mode + * - ``eapol`` + - ``control`` + - Traps "Extensible Authentication Protocol over LAN" (EAPOL) packets + specified in IEEE 802.1X + * - ``locked_port`` + - ``drop`` + - Traps packets that the device decided to drop because they failed the + locked bridge port check. That is, packets that were received via a + locked port and whose {SMAC, VID} does not correspond to an FDB entry + pointing to the port Driver-specific Packet Traps ============================ @@ -589,6 +599,9 @@ narrow. The description of these groups must be added to the following table: * - ``parser_error_drops`` - Contains packet traps for packets that were marked by the device during parsing as erroneous + * - ``eapol`` + - Contains packet traps for "Extensible Authentication Protocol over LAN" + (EAPOL) packets specified in IEEE 802.1X Packet Trap Policers ==================== diff --git a/Documentation/networking/devlink/etas_es58x.rst b/Documentation/networking/devlink/etas_es58x.rst new file mode 100644 index 000000000000..3b857d82a44c --- /dev/null +++ b/Documentation/networking/devlink/etas_es58x.rst @@ -0,0 +1,36 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================== +etas_es58x devlink support +========================== + +This document describes the devlink features implemented by the +``etas_es58x`` device driver. + +Info versions +============= + +The ``etas_es58x`` driver reports the following versions + +.. list-table:: devlink info versions implemented + :widths: 5 5 90 + + * - Name + - Type + - Description + * - ``fw`` + - running + - Version of the firmware running on the device. Also available + through ``ethtool -i`` as the first member of the + ``firmware-version``. + * - ``fw.bootloader`` + - running + - Version of the bootloader running on the device. Also available + through ``ethtool -i`` as the second member of the + ``firmware-version``. + * - ``board.rev`` + - fixed + - The hardware revision of the device. + * - ``serial_number`` + - fixed + - The USB serial number. Also available through ``lsusb -v``. diff --git a/Documentation/networking/devlink/ice.rst b/Documentation/networking/devlink/ice.rst index 0c89ceb8986d..625efb3777d5 100644 --- a/Documentation/networking/devlink/ice.rst +++ b/Documentation/networking/devlink/ice.rst @@ -189,12 +189,21 @@ device data. * - ``nvm-flash`` - The contents of the entire flash chip, sometimes referred to as the device's Non Volatile Memory. + * - ``shadow-ram`` + - The contents of the Shadow RAM, which is loaded from the beginning + of the flash. Although the contents are primarily from the flash, + this area also contains data generated during device boot which is + not stored in flash. * - ``device-caps`` - The contents of the device firmware's capabilities buffer. Useful to determine the current state and configuration of the device. -Users can request an immediate capture of a snapshot via the -``DEVLINK_CMD_REGION_NEW`` +Both the ``nvm-flash`` and ``shadow-ram`` regions can be accessed without a +snapshot. The ``device-caps`` region requires a snapshot as the contents are +sent by firmware and can't be split into separate reads. + +Users can request an immediate capture of a snapshot for all three regions +via the ``DEVLINK_CMD_REGION_NEW`` command. .. code:: shell @@ -254,3 +263,118 @@ Users can request an immediate capture of a snapshot via the 0000000000000210 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 $ devlink region delete pci/0000:01:00.0/device-caps snapshot 1 + +Devlink Rate +============ + +The ``ice`` driver implements devlink-rate API. It allows for offload of +the Hierarchical QoS to the hardware. It enables user to group Virtual +Functions in a tree structure and assign supported parameters: tx_share, +tx_max, tx_priority and tx_weight to each node in a tree. So effectively +user gains an ability to control how much bandwidth is allocated for each +VF group. This is later enforced by the HW. + +It is assumed that this feature is mutually exclusive with DCB performed +in FW and ADQ, or any driver feature that would trigger changes in QoS, +for example creation of the new traffic class. The driver will prevent DCB +or ADQ configuration if user started making any changes to the nodes using +devlink-rate API. To configure those features a driver reload is necessary. +Correspondingly if ADQ or DCB will get configured the driver won't export +hierarchy at all, or will remove the untouched hierarchy if those +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 +present, and those objects are only created in switchdev mode. + +If the driver is set to the switchdev mode, it will export internal +hierarchy the moment VF's are created. Root of the tree is always +represented by the node_0. This node can't be deleted by the user. Leaf +nodes and nodes with children also can't be deleted. + +.. list-table:: Attributes supported + :widths: 15 85 + + * - Name + - Description + * - ``tx_max`` + - maximum bandwidth to be consumed by the tree Node. Rate Limit is + an absolute number specifying a maximum amount of bytes a Node may + consume during the course of one second. Rate limit guarantees + that a link will not oversaturate the receiver on the remote end + and also enforces an SLA between the subscriber and network + provider. + * - ``tx_share`` + - minimum bandwidth allocated to a tree node when it is not blocked. + It specifies an absolute BW. While tx_max defines the maximum + bandwidth the node may consume, the tx_share marks committed BW + for the Node. + * - ``tx_priority`` + - allows for usage of strict priority arbiter among siblings. This + arbitration scheme attempts to schedule nodes based on their + priority as long as the nodes remain within their bandwidth limit. + Range 0-7. Nodes with priority 7 have the highest priority and are + selected first, while nodes with priority 0 have the lowest + priority. Nodes that have the same priority are treated equally. + * - ``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 + arbitration. + +``tx_priority`` and ``tx_weight`` can be used simultaneously. In that case +nodes with the same priority form a WFQ subgroup in the sibling group +and arbitration among them is based on assigned weights. + +.. code:: shell + + # enable switchdev + $ devlink dev eswitch set pci/0000:4b:00.0 mode switchdev + + # at this point driver should export internal hierarchy + $ echo 2 > /sys/class/net/ens785np0/device/sriov_numvfs + + $ devlink port function rate show + pci/0000:4b:00.0/node_25: type node parent node_24 + pci/0000:4b:00.0/node_24: type node parent node_0 + pci/0000:4b:00.0/node_32: type node parent node_31 + pci/0000:4b:00.0/node_31: type node parent node_30 + pci/0000:4b:00.0/node_30: type node parent node_16 + pci/0000:4b:00.0/node_19: type node parent node_18 + pci/0000:4b:00.0/node_18: type node parent node_17 + pci/0000:4b:00.0/node_17: type node parent node_16 + pci/0000:4b:00.0/node_14: type node parent node_5 + pci/0000:4b:00.0/node_5: type node parent node_3 + pci/0000:4b:00.0/node_13: type node parent node_4 + pci/0000:4b:00.0/node_12: type node parent node_4 + pci/0000:4b:00.0/node_11: type node parent node_4 + pci/0000:4b:00.0/node_10: type node parent node_4 + pci/0000:4b:00.0/node_9: type node parent node_4 + pci/0000:4b:00.0/node_8: type node parent node_4 + pci/0000:4b:00.0/node_7: type node parent node_4 + pci/0000:4b:00.0/node_6: type node parent node_4 + pci/0000:4b:00.0/node_4: type node parent node_3 + pci/0000:4b:00.0/node_3: type node parent node_16 + pci/0000:4b:00.0/node_16: type node parent node_15 + pci/0000:4b:00.0/node_15: type node parent node_0 + pci/0000:4b:00.0/node_2: type node parent node_1 + pci/0000:4b:00.0/node_1: type node parent node_0 + pci/0000:4b:00.0/node_0: type node + pci/0000:4b:00.0/1: type leaf parent node_25 + pci/0000:4b:00.0/2: type leaf parent node_25 + + # let's create some custom node + $ devlink port function rate add pci/0000:4b:00.0/node_custom parent node_0 + + # second custom node + $ devlink port function rate add pci/0000:4b:00.0/node_custom_1 parent node_custom + + # reassign second VF to newly created branch + $ devlink port function rate set pci/0000:4b:00.0/2 parent node_custom_1 + + # assign tx_weight to the VF + $ devlink port function rate set pci/0000:4b:00.0/2 tx_weight 5 + + # assign tx_share to the VF + $ devlink port function rate set pci/0000:4b:00.0/2 tx_share 500Mbps diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst index d578b8bcd8a4..f10f8eb44255 100644 --- a/Documentation/networking/ethtool-netlink.rst +++ b/Documentation/networking/ethtool-netlink.rst @@ -222,6 +222,7 @@ Userspace to kernel: ``ETHTOOL_MSG_MODULE_GET`` get transceiver module parameters ``ETHTOOL_MSG_PSE_SET`` set PSE parameters ``ETHTOOL_MSG_PSE_GET`` get PSE parameters + ``ETHTOOL_MSG_RSS_GET`` get RSS settings ===================================== ================================= Kernel to userspace: @@ -263,6 +264,7 @@ Kernel to userspace: ``ETHTOOL_MSG_PHC_VCLOCKS_GET_REPLY`` PHC virtual clocks info ``ETHTOOL_MSG_MODULE_GET_REPLY`` transceiver module parameters ``ETHTOOL_MSG_PSE_GET_REPLY`` PSE parameters + ``ETHTOOL_MSG_RSS_GET_REPLY`` RSS settings ======================================== ================================= ``GET`` requests are sent by userspace applications to retrieve device @@ -491,6 +493,7 @@ Kernel response contents: ``ETHTOOL_A_LINKSTATE_SQI_MAX`` u32 Max support SQI value ``ETHTOOL_A_LINKSTATE_EXT_STATE`` u8 link extended state ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE`` u8 link extended substate + ``ETHTOOL_A_LINKSTATE_EXT_DOWN_CNT`` u32 count of link down events ==================================== ====== ============================ For most NIC drivers, the value of ``ETHTOOL_A_LINKSTATE_LINK`` returns @@ -1686,6 +1689,33 @@ to control PoDL PSE Admin functions. This option is implementing ``IEEE 802.3-2018`` 30.15.1.2.1 acPoDLPSEAdminControl. See ``ETHTOOL_A_PODL_PSE_ADMIN_STATE`` for supported values. +RSS_GET +======= + +Get indirection table, hash key and hash function info associated with a +RSS context of an interface similar to ``ETHTOOL_GRSSH`` ioctl request. + +Request contents: + +===================================== ====== ========================== + ``ETHTOOL_A_RSS_HEADER`` nested request header + ``ETHTOOL_A_RSS_CONTEXT`` u32 context number +===================================== ====== ========================== + +Kernel response contents: + +===================================== ====== ========================== + ``ETHTOOL_A_RSS_HEADER`` nested reply header + ``ETHTOOL_A_RSS_HFUNC`` u32 RSS hash func + ``ETHTOOL_A_RSS_INDIR`` binary Indir table bytes + ``ETHTOOL_A_RSS_HKEY`` binary Hash key bytes +===================================== ====== ========================== + +ETHTOOL_A_RSS_HFUNC attribute is bitmap indicating the hash function +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. + Request translation =================== @@ -1767,7 +1797,7 @@ are netlink only. ``ETHTOOL_GMODULEEEPROM`` ``ETHTOOL_MSG_MODULE_EEPROM_GET`` ``ETHTOOL_GEEE`` ``ETHTOOL_MSG_EEE_GET`` ``ETHTOOL_SEEE`` ``ETHTOOL_MSG_EEE_SET`` - ``ETHTOOL_GRSSH`` n/a + ``ETHTOOL_GRSSH`` ``ETHTOOL_MSG_RSS_GET`` ``ETHTOOL_SRSSH`` n/a ``ETHTOOL_GTUNABLE`` n/a ``ETHTOOL_STUNABLE`` n/a diff --git a/Documentation/networking/generic_netlink.rst b/Documentation/networking/generic_netlink.rst index 59e04ccf80c1..d960dbd7e80e 100644 --- a/Documentation/networking/generic_netlink.rst +++ b/Documentation/networking/generic_netlink.rst @@ -6,4 +6,4 @@ Generic Netlink A wiki document on how to use Generic Netlink can be found here: - * http://www.linuxfoundation.org/collaborate/workgroups/networking/generic_netlink_howto + * https://wiki.linuxfoundation.org/networking/generic_netlink_howto diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 16a153bcc5fe..4f2d1f682a18 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -104,6 +104,7 @@ Contents: switchdev sysfs-tagging tc-actions-env-rules + tc-queue-filters tcp-thin team timestamping diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst index e7b3fa7bb3f7..7fbd060d6047 100644 --- a/Documentation/networking/ip-sysctl.rst +++ b/Documentation/networking/ip-sysctl.rst @@ -1069,6 +1069,81 @@ tcp_child_ehash_entries - INTEGER Default: 0 +tcp_plb_enabled - BOOLEAN + If set and the underlying congestion control (e.g. DCTCP) supports + and enables PLB feature, TCP PLB (Protective Load Balancing) is + enabled. PLB is described in the following paper: + https://doi.org/10.1145/3544216.3544226. Based on PLB parameters, + upon sensing sustained congestion, TCP triggers a change in + flow label field for outgoing IPv6 packets. A change in flow label + field potentially changes the path of outgoing packets for switches + that use ECMP/WCMP for routing. + + PLB changes socket txhash which results in a change in IPv6 Flow Label + field, and currently no-op for IPv4 headers. It is possible + to apply PLB for IPv4 with other network header fields (e.g. TCP + or IPv4 options) or using encapsulation where outer header is used + by switches to determine next hop. In either case, further host + and switch side changes will be needed. + + When set, PLB assumes that congestion signal (e.g. ECN) is made + available and used by congestion control module to estimate a + congestion measure (e.g. ce_ratio). PLB needs a congestion measure to + make repathing decisions. + + Default: FALSE + +tcp_plb_idle_rehash_rounds - INTEGER + Number of consecutive congested rounds (RTT) seen after which + a rehash can be performed, given there are no packets in flight. + This is referred to as M in PLB paper: + https://doi.org/10.1145/3544216.3544226. + + Possible Values: 0 - 31 + + Default: 3 + +tcp_plb_rehash_rounds - INTEGER + Number of consecutive congested rounds (RTT) seen after which + a forced rehash can be performed. Be careful when setting this + parameter, as a small value increases the risk of retransmissions. + This is referred to as N in PLB paper: + https://doi.org/10.1145/3544216.3544226. + + Possible Values: 0 - 31 + + Default: 12 + +tcp_plb_suspend_rto_sec - INTEGER + Time, in seconds, to suspend PLB in event of an RTO. In order to avoid + having PLB repath onto a connectivity "black hole", after an RTO a TCP + connection suspends PLB repathing for a random duration between 1x and + 2x of this parameter. Randomness is added to avoid concurrent rehashing + of multiple TCP connections. This should be set corresponding to the + amount of time it takes to repair a failed link. + + Possible Values: 0 - 255 + + Default: 60 + +tcp_plb_cong_thresh - INTEGER + Fraction of packets marked with congestion over a round (RTT) to + tag that round as congested. This is referred to as K in the PLB paper: + https://doi.org/10.1145/3544216.3544226. + + The 0-1 fraction range is mapped to 0-256 range to avoid floating + point operations. For example, 128 means that if at least 50% of + the packets in a round were marked as congested then the round + will be tagged as congested. + + Setting threshold to 0 means that PLB repaths every RTT regardless + of congestion. This is not intended behavior for PLB and should be + used only for experimentation purpose. + + Possible Values: 0 - 256 + + Default: 128 + UDP variables ============= @@ -1102,6 +1177,33 @@ udp_rmem_min - INTEGER udp_wmem_min - INTEGER UDP does not have tx memory accounting and this tunable has no effect. +udp_hash_entries - INTEGER + Show the number of hash buckets for UDP sockets in the current + networking namespace. + + A negative value means the networking namespace does not own its + hash buckets and shares the initial networking namespace's one. + +udp_child_ehash_entries - INTEGER + Control the number of hash buckets for UDP sockets in the child + networking namespace, which must be set before clone() or unshare(). + + If the value is not 0, the kernel uses a value rounded up to 2^n + as the actual hash bucket size. 0 is a special value, meaning + the child networking namespace will share the initial networking + namespace's hash buckets. + + Note that the child will use the global one in case the kernel + fails to allocate enough memory. In addition, the global hash + buckets are spread over available NUMA nodes, but the allocation + of the child hash table depends on the current process's NUMA + policy, which could result in performance differences. + + Possible values: 0, 2^n (n: 7 (128) - 16 (64K)) + + Default: 0 + + RAW variables ============= @@ -3025,6 +3127,15 @@ ecn_enable - BOOLEAN Default: 1 +l3mdev_accept - BOOLEAN + Enabling this option allows a "global" bound socket to work + across L3 master domains (e.g., VRFs) with packets capable of + being received regardless of the L3 domain in which they + originated. Only valid when the kernel was compiled with + CONFIG_NET_L3_MASTER_DEV. + + Default: 1 (enabled) + ``/proc/sys/net/core/*`` ======================== diff --git a/Documentation/networking/ipvs-sysctl.rst b/Documentation/networking/ipvs-sysctl.rst index 387fda80f05f..3fb5fa142eef 100644 --- a/Documentation/networking/ipvs-sysctl.rst +++ b/Documentation/networking/ipvs-sysctl.rst @@ -129,6 +129,26 @@ drop_packet - INTEGER threshold. When the mode 3 is set, the always mode drop rate is controlled by the /proc/sys/net/ipv4/vs/am_droprate. +est_cpulist - CPULIST + Allowed CPUs for estimation kthreads + + Syntax: standard cpulist format + empty list - stop kthread tasks and estimation + default - the system's housekeeping CPUs for kthreads + + Example: + "all": all possible CPUs + "0-N": all possible CPUs, N denotes last CPU number + "0,1-N:1/2": first and all CPUs with odd number + "": empty list + +est_nice - INTEGER + default 0 + Valid range: -20 (more favorable) .. 19 (less favorable) + + Niceness value to use for the estimation kthreads (scheduling + priority) + expire_nodest_conn - BOOLEAN - 0 - disabled (default) - not 0 - enabled @@ -304,8 +324,8 @@ run_estimation - BOOLEAN 0 - disabled not 0 - enabled (default) - If disabled, the estimation will be stop, and you can't see - any update on speed estimation data. + If disabled, the estimation will be suspended and kthread tasks + stopped. You can always re-enable estimation by setting this value to 1. But be careful, the first estimation after re-enable is not diff --git a/Documentation/networking/tc-queue-filters.rst b/Documentation/networking/tc-queue-filters.rst new file mode 100644 index 000000000000..6b417092276f --- /dev/null +++ b/Documentation/networking/tc-queue-filters.rst @@ -0,0 +1,37 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +TC queue based filtering +========================= + +TC can be used for directing traffic to either a set of queues or +to a single queue on both the transmit and receive side. + +On the transmit side: + +1) TC filter directing traffic to a set of queues is achieved + using the action skbedit priority for Tx priority selection, + the priority maps to a traffic class (set of queues) when + the queue-sets are configured using mqprio. + +2) TC filter directs traffic to a transmit queue with the action + skbedit queue_mapping $tx_qid. The action skbedit queue_mapping + for transmit queue is executed in software only and cannot be + offloaded. + +Likewise, on the receive side, the two filters for selecting set of +queues and/or a single queue are supported as below: + +1) TC flower filter directs incoming traffic to a set of queues using + the 'hw_tc' option. + hw_tc $TCID - Specify a hardware traffic class to pass matching + packets on to. TCID is in the range 0 through 15. + +2) TC filter with action skbedit queue_mapping $rx_qid selects a + receive queue. The action skbedit queue_mapping for receive queue + is supported only in hardware. Multiple filters may compete in + the hardware for queue selection. In such case, the hardware + pipeline resolves conflicts based on priority. On Intel E810 + devices, TC filter directing traffic to a queue have higher + priority over flow director filter assigning a queue. The hash + filter has lowest priority. diff --git a/Documentation/networking/timestamping.rst b/Documentation/networking/timestamping.rst index be4eb1242057..f17c01834a12 100644 --- a/Documentation/networking/timestamping.rst +++ b/Documentation/networking/timestamping.rst @@ -179,7 +179,8 @@ SOF_TIMESTAMPING_OPT_ID: identifier and returns that along with the timestamp. The identifier is derived from a per-socket u32 counter (that wraps). For datagram sockets, the counter increments with each sent packet. For stream - sockets, it increments with every byte. + sockets, it increments with every byte. For stream sockets, also set + SOF_TIMESTAMPING_OPT_ID_TCP, see the section below. The counter starts at zero. It is initialized the first time that the socket option is enabled. It is reset each time the option is @@ -192,6 +193,35 @@ SOF_TIMESTAMPING_OPT_ID: among all possibly concurrently outstanding timestamp requests for that socket. +SOF_TIMESTAMPING_OPT_ID_TCP: + Pass this modifier along with SOF_TIMESTAMPING_OPT_ID for new TCP + timestamping applications. SOF_TIMESTAMPING_OPT_ID defines how the + counter increments for stream sockets, but its starting point is + not entirely trivial. This option fixes that. + + For stream sockets, if SOF_TIMESTAMPING_OPT_ID is set, this should + always be set too. On datagram sockets the option has no effect. + + A reasonable expectation is that the counter is reset to zero with + the system call, so that a subsequent write() of N bytes generates + a timestamp with counter N-1. SOF_TIMESTAMPING_OPT_ID_TCP + implements this behavior under all conditions. + + SOF_TIMESTAMPING_OPT_ID without modifier often reports the same, + especially when the socket option is set when no data is in + transmission. If data is being transmitted, it may be off by the + length of the output queue (SIOCOUTQ). + + The difference is due to being based on snd_una versus write_seq. + snd_una is the offset in the stream acknowledged by the peer. This + depends on factors outside of process control, such as network RTT. + write_seq is the last byte written by the process. This offset is + not affected by external inputs. + + The difference is subtle and unlikely to be noticed when configured + at initial socket creation, when no data is queued or sent. But + SOF_TIMESTAMPING_OPT_ID_TCP behavior is more robust regardless of + when the socket option is set. SOF_TIMESTAMPING_OPT_CMSG: Support recv() cmsg for all timestamped packets. Control messages diff --git a/Documentation/networking/xfrm_device.rst b/Documentation/networking/xfrm_device.rst index 01391dfd37d9..c43ace79e320 100644 --- a/Documentation/networking/xfrm_device.rst +++ b/Documentation/networking/xfrm_device.rst @@ -5,6 +5,7 @@ XFRM device - offloading the IPsec computations =============================================== Shannon Nelson <shannon.nelson@oracle.com> +Leon Romanovsky <leonro@nvidia.com> Overview @@ -18,10 +19,21 @@ can radically increase throughput and decrease CPU utilization. The XFRM Device interface allows NIC drivers to offer to the stack access to the hardware offload. +Right now, there are two types of hardware offload that kernel supports. + * IPsec crypto offload: + * NIC performs encrypt/decrypt + * Kernel does everything else + * IPsec packet offload: + * NIC performs encrypt/decrypt + * NIC does encapsulation + * Kernel and NIC have SA and policy in-sync + * NIC handles the SA and policies states + * The Kernel talks to the keymanager + Userland access to the offload is typically through a system such as libreswan or KAME/raccoon, but the iproute2 'ip xfrm' command set can be handy when experimenting. An example command might look something -like this:: +like this for crypto offload: ip x s add proto esp dst 14.0.0.70 src 14.0.0.52 spi 0x07 mode transport \ reqid 0x07 replay-window 32 \ @@ -29,6 +41,17 @@ like this:: sel src 14.0.0.52/24 dst 14.0.0.70/24 proto tcp \ offload dev eth4 dir in +and for packet offload + + ip x s add proto esp dst 14.0.0.70 src 14.0.0.52 spi 0x07 mode transport \ + reqid 0x07 replay-window 32 \ + aead 'rfc4106(gcm(aes))' 0x44434241343332312423222114131211f4f3f2f1 128 \ + sel src 14.0.0.52/24 dst 14.0.0.70/24 proto tcp \ + offload packet dev eth4 dir in + + ip x p add src 14.0.0.70 dst 14.0.0.52 offload packet dev eth4 dir in + tmpl src 14.0.0.70 dst 14.0.0.52 proto esp reqid 10000 mode transport + Yes, that's ugly, but that's what shell scripts and/or libreswan are for. @@ -40,17 +63,24 @@ 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); 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, struct xfrm_state *x); void (*xdo_dev_state_advance_esn) (struct xfrm_state *x); + + /* Solely packet offload callbacks */ + void (*xdo_dev_state_update_curlft) (struct xfrm_state *x); + int (*xdo_dev_policy_add) (struct xfrm_policy *x); + void (*xdo_dev_policy_delete) (struct xfrm_policy *x); + void (*xdo_dev_policy_free) (struct xfrm_policy *x); }; -The NIC driver offering ipsec offload will need to implement these -callbacks to make the offload available to the network stack's -XFRM subsystem. Additionally, the feature bits NETIF_F_HW_ESP and +The NIC driver offering ipsec offload will need to implement callbacks +relevant to supported offload to make the offload available to the network +stack's XFRM subsystem. Additionally, the feature bits NETIF_F_HW_ESP and NETIF_F_HW_ESP_TX_CSUM will signal the availability of the offload. @@ -79,7 +109,8 @@ and an indication of whether it is for Rx or Tx. The driver should =========== =================================== 0 success - -EOPNETSUPP offload not supported, try SW IPsec + -EOPNETSUPP offload not supported, try SW IPsec, + not applicable for packet offload mode other fail the request =========== =================================== @@ -96,6 +127,7 @@ will serviceable. This can check the packet information to be sure the offload can be supported (e.g. IPv4 or IPv6, no IPv4 options, etc) and return true of false to signify its support. +Crypto offload mode: When ready to send, the driver needs to inspect the Tx packet for the offload information, including the opaque context, and set up the packet send accordingly:: @@ -139,13 +171,25 @@ the stack in xfrm_input(). In ESN mode, xdo_dev_state_advance_esn() is called from xfrm_replay_advance_esn(). Driver will check packet seq number and update HW ESN state machine if needed. +Packet offload mode: +HW adds and deletes XFRM headers. So in RX path, XFRM stack is bypassed if HW +reported success. In TX path, the packet lefts kernel without extra header +and not encrypted, the HW is responsible to perform it. + When the SA is removed by the user, the driver's xdo_dev_state_delete() -is asked to disable the offload. Later, xdo_dev_state_free() is called -from a garbage collection routine after all reference counts to the state +and xdo_dev_policy_delete() are asked to disable the offload. Later, +xdo_dev_state_free() and xdo_dev_policy_free() are called from a garbage +collection routine after all reference counts to the state and policy have been removed and any remaining resources can be cleared for the offload state. How these are used by the driver will depend on specific hardware needs. As a netdev is set to DOWN the XFRM stack's netdev listener will call -xdo_dev_state_delete() and xdo_dev_state_free() on any remaining offloaded -states. +xdo_dev_state_delete(), xdo_dev_policy_delete(), xdo_dev_state_free() and +xdo_dev_policy_free() on any remaining offloaded states. + +Outcome of HW handling packets, the XFRM core can't count hard, soft limits. +The HW/driver are responsible to perform it and provide accurate data when +xdo_dev_state_update_curlft() is called. In case of one of these limits +occuried, the driver needs to call to xfrm_state_check_expire() to make sure +that XFRM performs rekeying sequence. diff --git a/Documentation/process/code-of-conduct-interpretation.rst b/Documentation/process/code-of-conduct-interpretation.rst index 922e0b547bc3..66b07f14714c 100644 --- a/Documentation/process/code-of-conduct-interpretation.rst +++ b/Documentation/process/code-of-conduct-interpretation.rst @@ -51,7 +51,7 @@ the Technical Advisory Board (TAB) or other maintainers if you're uncertain how to handle situations that come up. It will not be considered a violation report unless you want it to be. If you are uncertain about approaching the TAB or any other maintainers, please -reach out to our conflict mediator, Joanna Lee <joanna.lee@gesmer.com>. +reach out to our conflict mediator, Joanna Lee <jlee@linuxfoundation.org>. In the end, "be kind to each other" is really what the end goal is for everybody. We know everyone is human and we all fail at times, but the diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index 306ad373a002..1c6e2ab92f4e 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -3,9 +3,6 @@ Index of Further Kernel Documentation ===================================== -Initial Author: Juan-Mariano de Goyeneche (<jmseyas@dit.upm.es>; -email address is defunct now.) - The need for a document like this one became apparent in the linux-kernel mailing list as the same questions, asking for pointers to information, appeared again and again. @@ -31,7 +28,9 @@ All documents are cataloged with the following fields: the document's .. note:: The documents on each section of this document are ordered by its - published date, from the newest to the oldest. + published date, from the newest to the oldest. The maintainer(s) should + periodically retire resources as they become obsolte or outdated; with + the exception of foundational books. Docs at the Linux Kernel tree ----------------------------- @@ -61,24 +60,6 @@ On-line docs a brief description of some of the acronyms and terms you may hear during discussion of the Linux kernel". - * Title: **Tracing the Way of Data in a TCP Connection through the Linux Kernel** - - :Author: Richard Sailer - :URL: https://archive.org/details/linux_kernel_data_flow_short_paper - :Date: 2016 - :Keywords: Linux Kernel Networking, TCP, tracing, ftrace - :Description: A seminar paper explaining ftrace and how to use it for - understanding linux kernel internals, - illustrated at tracing the way of a TCP packet through the kernel. - :Abstract: *This short paper outlines the usage of ftrace a tracing framework - as a tool to understand a running Linux system. - Having obtained a trace-log a kernel hacker can read and understand - source code more determined and with context. - In a detailed example this approach is demonstrated in tracing - and the way of data in a TCP Connection through the kernel. - Finally this trace-log is used as base for more a exact conceptual - exploration and description of the Linux TCP/IP implementation.* - * Title: **The Linux Kernel Module Programming Guide** :Author: Peter Jay Salzman, Michael Burian, Ori Pomerantz, Bob Mottram, @@ -91,379 +72,16 @@ On-line docs programming. Lots of examples. Currently the new version is being actively maintained at https://github.com/sysprog21/lkmpg. - * Title: **On submitting kernel Patches** - - :Author: Andi Kleen - :URL: http://halobates.de/on-submitting-kernel-patches.pdf - :Date: 2008 - :Keywords: patches, review process, types of submissions, basic rules, case studies - :Description: This paper gives several experience values on what types of patches - there are and how likely they get merged. - :Abstract: - [...]. This paper examines some common problems for - submitting larger changes and some strategies to avoid problems. - - * Title: **Linux Device Drivers, Third Edition** - - :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman - :URL: https://lwn.net/Kernel/LDD3/ - :Date: 2005 - :Description: A 600-page book covering the (2.6.10) driver - programming API and kernel hacking in general. Available under the - Creative Commons Attribution-ShareAlike 2.0 license. - :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere <ldd3_published>`. - - * Title: **Writing an ALSA Driver** - - :Author: Takashi Iwai <tiwai@suse.de> - :URL: https://www.kernel.org/doc/html/latest/sound/kernel-api/writing-an-alsa-driver.html - :Date: 2005 - :Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware. - :Description: Advanced Linux Sound Architecture for developers, - both at kernel and user-level sides. ALSA is the Linux kernel - sound architecture in the 2.6 kernel version. - - * Title: **Linux PCMCIA Programmer's Guide** - - :Author: David Hinds. - :URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html - :Date: 2003 - :Keywords: PCMCIA. - :Description: "This document describes how to write kernel device - drivers for the Linux PCMCIA Card Services interface. It also - describes how to write user-mode utilities for communicating with - Card Services. - - * Title: **How NOT to write kernel drivers** - - :Author: Arjan van de Ven. - :URL: https://landley.net/kdocs/ols/2002/ols2002-pages-545-555.pdf - :Date: 2002 - :Keywords: driver. - :Description: Programming bugs and Do-nots in kernel driver development - :Abstract: *Quit a few tutorials, articles and books give an introduction - on how to write Linux kernel drivers. Unfortunately the things one - should NOT do in Linux kernel code is either only a minor appendix - or, more commonly, completely absent. This paper tries to briefly touch - the areas in which the most common and serious bugs and do-nots are - encountered.* - - * Title: **Global spinlock list and usage** - - :Author: Rick Lindsley. - :URL: http://lse.sourceforge.net/lockhier/global-spin-lock - :Date: 2001 - :Keywords: spinlock. - :Description: This is an attempt to document both the existence and - usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive - list of spinlocks showing when they are used, which functions - access them, how each lock is acquired, under what conditions it - is held, whether interrupts can occur or not while it is held... - - * Title: **A Linux vm README** - - :Author: Kanoj Sarcar. - :URL: http://kos.enix.org/pub/linux-vmm.html - :Date: 2001 - :Keywords: virtual memory, mm, pgd, vma, page, page flags, page - cache, swap cache, kswapd. - :Description: Telegraphic, short descriptions and definitions - relating the Linux virtual memory implementation. - - * Title: **Video4linux Drivers, Part 1: Video-Capture Device** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/406 - :Date: 2000 - :Keywords: video4linux, driver, video capture, capture devices, - camera driver. - :Description: The title says it all. - - * Title: **Video4linux Drivers, Part 2: Video-capture Devices** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/429 - :Date: 2000 - :Keywords: video4linux, driver, video capture, capture devices, - camera driver, control, query capabilities, capability, facility. - :Description: The title says it all. - - * Title: **Linux IP Networking. A Guide to the Implementation and Modification of the Linux Protocol Stack.** - - :Author: Glenn Herrin. - :URL: http://www.cs.unh.edu/cnrg/gherrin - :Date: 2000 - :Keywords: network, networking, protocol, IP, UDP, TCP, connection, - socket, receiving, transmitting, forwarding, routing, packets, - modules, /proc, sk_buff, FIB, tags. - :Description: Excellent paper devoted to the Linux IP Networking, - explaining anything from the kernel's to the user space - configuration tools' code. Very good to get a general overview of - the kernel networking implementation and understand all steps - packets follow from the time they are received at the network - device till they are delivered to applications. The studied kernel - code is from 2.2.14 version. Provides code for a working packet - dropper example. - - * Title: **How To Make Sure Your Driver Will Work On The Power Macintosh** - - :Author: Paul Mackerras. - :URL: http://www.linux-mag.com/id/261 - :Date: 1999 - :Keywords: Mac, Power Macintosh, porting, drivers, compatibility. - :Description: The title says it all. - - * Title: **An Introduction to SCSI Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/284 - :Date: 1999 - :Keywords: SCSI, device, driver. - :Description: The title says it all. - - * Title: **Advanced SCSI Drivers And Other Tales** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/307 - :Date: 1999 - :Keywords: SCSI, device, driver, advanced. - :Description: The title says it all. - - * Title: **Writing Linux Mouse Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/330 - :Date: 1999 - :Keywords: mouse, driver, gpm. - :Description: The title says it all. - - * Title: **More on Mouse Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/356 - :Date: 1999 - :Keywords: mouse, driver, gpm, races, asynchronous I/O. - :Description: The title still says it all. - - * Title: **Writing Video4linux Radio Driver** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/381 - :Date: 1999 - :Keywords: video4linux, driver, radio, radio devices. - :Description: The title says it all. - - * Title: **I/O Event Handling Under Linux** - - :Author: Richard Gooch. - :URL: https://web.mit.edu/~yandros/doc/io-events.html - :Date: 1999 - :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness - event queues. - :Description: From the Introduction: "I/O Event handling is about - how your Operating System allows you to manage a large number of - open files (file descriptors in UNIX/POSIX, or FDs) in your - application. You want the OS to notify you when FDs become active - (have data ready to be read or are ready for writing). Ideally you - want a mechanism that is scalable. This means a large number of - inactive FDs cost very little in memory and CPU time to manage". - - * Title: **(nearly) Complete Linux Loadable Kernel Modules. The definitive guide for hackers, virus coders and system administrators.** - - :Author: pragmatic/THC. - :URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html - :Date: 1999 - :Keywords: syscalls, intercept, hide, abuse, symbol table. - :Description: Interesting paper on how to abuse the Linux kernel in - order to intercept and modify syscalls, make - files/directories/processes invisible, become root, hijack ttys, - write kernel modules based virus... and solutions for admins to - avoid all those abuses. - :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x - kernels. - - * Name: **Linux Virtual File System** - - :Author: Peter J. Braam. - :URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ - :Date: 1998 - :Keywords: slides, VFS, inode, superblock, dentry, dcache. - :Description: Set of slides, presumably from a presentation on the - Linux VFS layer. Covers version 2.1.x, with dentries and the - dcache. - - * Title: **The Venus kernel interface** - - :Author: Peter J. Braam. - :URL: http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html - :Date: 1998 - :Keywords: coda, filesystem, venus, cache manager. - :Description: "This document describes the communication between - Venus and kernel level file system code needed for the operation - of the Coda filesystem. This version document is meant to describe - the current interface (version 1.0) as well as improvements we - envisage". - - * Title: **Design and Implementation of the Second Extended Filesystem** - - :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. - :URL: https://web.mit.edu/tytso/www/linux/ext2intro.html - :Date: 1998 - :Keywords: ext2, linux fs history, inode, directory, link, devices, - VFS, physical structure, performance, benchmarks, ext2fs library, - ext2fs tools, e2fsck. - :Description: Paper written by three of the top ext2 hackers. - Covers Linux filesystems history, ext2 motivation, ext2 features, - design, physical structure on disk, performance, benchmarks, - e2fsck's passes description... A must read! - :Notes: This paper was first published in the Proceedings of the - First Dutch International Symposium on Linux, ISBN 90-367-0385-9. - - * Title: **The Linux RAID-1, 4, 5 Code** - - :Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza. - :URL: http://www.linuxjournal.com/article.php?sid=2391 - :Date: 1997 - :Keywords: RAID, MD driver. - :Description: Linux Journal Kernel Korner article. - :Abstract: *A description of the implementation of the RAID-1, - RAID-4 and RAID-5 personalities of the MD device driver in the - Linux kernel, providing users with high performance and reliable, - secondary-storage capability using software*. - - * Title: **Linux Kernel Hackers' Guide** - - :Author: Michael K. Johnson. - :URL: https://www.tldp.org/LDP/khg/HyperNews/get/khg.html - :Date: 1997 - :Keywords: device drivers, files, VFS, kernel interface, character vs - block devices, hardware interrupts, scsi, DMA, access to user memory, - memory allocation, timers. - :Description: A guide designed to help you get up to speed on the - concepts that are not intuitively obvious, and to document the internal - structures of Linux. - - * Title: **Dynamic Kernels: Modularized Device Drivers** - - :Author: Alessandro Rubini. - :URL: http://www.linuxjournal.com/article.php?sid=1219 - :Date: 1996 - :Keywords: device driver, module, loading/unloading modules, - allocating resources. - :Description: Linux Journal Kernel Korner article. - :Abstract: *This is the first of a series of four articles - co-authored by Alessandro Rubini and Georg Zezchwitz which present - a practical approach to writing Linux device drivers as kernel - loadable modules. This installment presents an introduction to the - topic, preparing the reader to understand next month's - installment*. - - * Title: **Dynamic Kernels: Discovery** - - :Author: Alessandro Rubini. - :URL: http://www.linuxjournal.com/article.php?sid=1220 - :Date: 1996 - :Keywords: character driver, init_module, clean_up module, - autodetection, mayor number, minor number, file operations, - open(), close(). - :Description: Linux Journal Kernel Korner article. - :Abstract: *This article, the second of four, introduces part of - the actual code to create custom module implementing a character - device driver. It describes the code for module initialization and - cleanup, as well as the open() and close() system calls*. - - * Title: **The Devil's in the Details** - - :Author: Georg v. Zezschwitz and Alessandro Rubini. - :URL: http://www.linuxjournal.com/article.php?sid=1221 - :Date: 1996 - :Keywords: read(), write(), select(), ioctl(), blocking/non - blocking mode, interrupt handler. - :Description: Linux Journal Kernel Korner article. - :Abstract: *This article, the third of four on writing character - device drivers, introduces concepts of reading, writing, and using - ioctl-calls*. - - * Title: **Dissecting Interrupts and Browsing DMA** - - :Author: Alessandro Rubini and Georg v. Zezschwitz. - :URL: https://www.linuxjournal.com/article.php?sid=1222 - :Date: 1996 - :Keywords: interrupts, irqs, DMA, bottom halves, task queues. - :Description: Linux Journal Kernel Korner article. - :Abstract: *This is the fourth in a series of articles about - writing character device drivers as loadable kernel modules. This - month, we further investigate the field of interrupt handling. - Though it is conceptually simple, practical limitations and - constraints make this an ''interesting'' part of device driver - writing, and several different facilities have been provided for - different situations. We also investigate the complex topic of - DMA*. - - * Title: **Device Drivers Concluded** - - :Author: Georg v. Zezschwitz. - :URL: https://www.linuxjournal.com/article.php?sid=1287 - :Date: 1996 - :Keywords: address spaces, pages, pagination, page management, - demand loading, swapping, memory protection, memory mapping, mmap, - virtual memory areas (VMAs), vremap, PCI. - :Description: Finally, the above turned out into a five articles - series. This latest one's introduction reads: "This is the last of - five articles about character device drivers. In this final - section, Georg deals with memory mapping devices, beginning with - an overall description of the Linux memory management concepts". - - * Title: **Network Buffers And Memory Management** - - :Author: Alan Cox. - :URL: https://www.linuxjournal.com/article.php?sid=1312 - :Date: 1996 - :Keywords: sk_buffs, network devices, protocol/link layer - variables, network devices flags, transmit, receive, - configuration, multicast. - :Description: Linux Journal Kernel Korner. - :Abstract: *Writing a network device driver for Linux is fundamentally - simple---most of the complexity (other than talking to the - hardware) involves managing network packets in memory*. - - * Title: **Analysis of the Ext2fs structure** - - :Author: Louis-Dominique Dubeau. - :URL: https://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ - :Date: 1994 - :Keywords: ext2, filesystem, ext2fs. - :Description: Description of ext2's blocks, directories, inodes, - bitmaps, invariants... - Published books --------------- - * Title: **Linux Treiber entwickeln** - - :Author: Jürgen Quade, Eva-Katharina Kunst - :Publisher: dpunkt.verlag - :Date: Oct 2015 (4th edition) - :Pages: 688 - :ISBN: 978-3-86490-288-8 - :Note: German. The third edition from 2011 is - much cheaper and still quite up-to-date. - - * Title: **Linux Kernel Networking: Implementation and Theory** - - :Author: Rami Rosen - :Publisher: Apress - :Date: December 22, 2013 - :Pages: 648 - :ISBN: 978-1430261964 - - * Title: **Embedded Linux Primer: A practical Real-World Approach, 2nd Edition** + * Title: **Linux Kernel Programming: A Comprehensive Guide to Kernel Internals, Writing Kernel Modules, and Kernel Synchronization** - :Author: Christopher Hallinan - :Publisher: Pearson - :Date: November, 2010 - :Pages: 656 - :ISBN: 978-0137017836 + :Author: Kaiwan N. Billimoria + :Publisher: Packt Publishing Ltd + :Date: 2021 + :Pages: 754 + :ISBN: 978-1789953435 * Title: **Linux Kernel Development, 3rd Edition** @@ -472,14 +90,7 @@ Published books :Date: July, 2010 :Pages: 440 :ISBN: 978-0672329463 - - * Title: **Essential Linux Device Drivers** - - :Author: Sreekrishnan Venkateswaran - :Published: Prentice Hall - :Date: April, 2008 - :Pages: 744 - :ISBN: 978-0132396554 + :Notes: Foundational book .. _ldd3_published: @@ -490,68 +101,10 @@ Published books :Date: 2005 :Pages: 636 :ISBN: 0-596-00590-3 - :Notes: Further information in + :Notes: Foundational book. Further information in http://www.oreilly.com/catalog/linuxdrive3/ PDF format, URL: https://lwn.net/Kernel/LDD3/ - * Title: **Linux Kernel Internals** - - :Author: Michael Beck - :Publisher: Addison-Wesley - :Date: 1997 - :ISBN: 0-201-33143-8 (second edition) - - * Title: **Programmation Linux 2.0 API systeme et fonctionnement du noyau** - - :Author: Remy Card, Eric Dumas, Franck Mevel - :Publisher: Eyrolles - :Date: 1997 - :Pages: 520 - :ISBN: 2-212-08932-5 - :Notes: French - - * Title: **The Design and Implementation of the 4.4 BSD UNIX Operating System** - - :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, - John S. Quarterman - :Publisher: Addison-Wesley - :Date: 1996 - :ISBN: 0-201-54979-4 - - * Title: **Unix internals -- the new frontiers** - - :Author: Uresh Vahalia - :Publisher: Prentice Hall - :Date: 1996 - :Pages: 600 - :ISBN: 0-13-101908-2 - - * Title: **Programming for the real world - POSIX.4** - - :Author: Bill O. Gallmeister - :Publisher: O'Reilly & Associates, Inc - :Date: 1995 - :Pages: 552 - :ISBN: I-56592-074-0 - :Notes: Though not being directly about Linux, Linux aims to be - POSIX. Good reference. - - * Title: **UNIX Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers** - - :Author: Curt Schimmel - :Publisher: Addison Wesley - :Date: June, 1994 - :Pages: 432 - :ISBN: 0-201-63338-8 - - * Title: **The Design and Implementation of the 4.3 BSD UNIX Operating System** - - :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J - Karels, John S. Quarterman - :Publisher: Addison-Wesley - :Date: 1989 (reprinted with corrections on October, 1990) - :ISBN: 0-201-06196-1 - * Title: **The Design of the UNIX Operating System** :Author: Maurice J. Bach @@ -559,6 +112,7 @@ Published books :Date: 1986 :Pages: 471 :ISBN: 0-13-201757-1 + :Notes: Foundational book Miscellaneous ------------- @@ -577,7 +131,7 @@ Miscellaneous :Keywords: latest kernel news. :Description: The title says it all. There's a fixed kernel section summarizing developers' work, bug fixes, new features and versions - produced during the week. Published every Thursday. + produced during the week. * Name: **The home page of Linux-MM** @@ -614,7 +168,8 @@ Miscellaneous ------- -Document last updated on Tue 2016-Sep-20 +This document was originally based on: -This document is based on: https://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html + +and written by Juan-Mariano de Goyeneche diff --git a/Documentation/riscv/patch-acceptance.rst b/Documentation/riscv/patch-acceptance.rst index dfe0ac5624fb..07d5a5623e2a 100644 --- a/Documentation/riscv/patch-acceptance.rst +++ b/Documentation/riscv/patch-acceptance.rst @@ -20,16 +20,22 @@ Submit Checklist Addendum ------------------------- We'll only accept patches for new modules or extensions if the specifications for those modules or extensions are listed as being -"Frozen" or "Ratified" by the RISC-V Foundation. (Developers may, of -course, maintain their own Linux kernel trees that contain code for -any draft extensions that they wish.) +unlikely to be incompatibly changed in the future. For +specifications from the RISC-V foundation this means "Frozen" or +"Ratified", for the UEFI forum specifications this means a published +ECR. (Developers may, of course, maintain their own Linux kernel trees +that contain code for any draft extensions that they wish.) -Additionally, the RISC-V specification allows implementors to create +Additionally, the RISC-V specification allows implementers to create their own custom extensions. These custom extensions aren't required to go through any review or ratification process by the RISC-V Foundation. To avoid the maintenance complexity and potential performance impact of adding kernel code for implementor-specific -RISC-V extensions, we'll only to accept patches for extensions that -have been officially frozen or ratified by the RISC-V Foundation. -(Implementors, may, of course, maintain their own Linux kernel trees -containing code for any custom extensions that they wish.) +RISC-V extensions, we'll only consider patches for extensions that either: + +- Have been officially frozen or ratified by the RISC-V Foundation, or +- Have been implemented in hardware that is widely available, per standard + Linux practice. + +(Implementers, may, of course, maintain their own Linux kernel trees containing +code for any custom extensions that they wish.) diff --git a/Documentation/riscv/vm-layout.rst b/Documentation/riscv/vm-layout.rst index 5b36e45fef60..3be44e74ec5d 100644 --- a/Documentation/riscv/vm-layout.rst +++ b/Documentation/riscv/vm-layout.rst @@ -97,3 +97,39 @@ RISC-V Linux Kernel SV48 ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | modules, BPF ffffffff80000000 | -2 GB | ffffffffffffffff | 2 GB | kernel __________________|____________|__________________|_________|____________________________________________________________ + + +RISC-V Linux Kernel SV57 +------------------------ + +:: + + ======================================================================================================================== + Start addr | Offset | End addr | Size | VM area description + ======================================================================================================================== + | | | | + 0000000000000000 | 0 | 00ffffffffffffff | 64 PB | user-space virtual memory, different per mm + __________________|____________|__________________|_________|___________________________________________________________ + | | | | + 0100000000000000 | +64 PB | feffffffffffffff | ~16K PB | ... huge, almost 64 bits wide hole of non-canonical + | | | | virtual memory addresses up to the -64 PB + | | | | starting offset of kernel mappings. + __________________|____________|__________________|_________|___________________________________________________________ + | + | Kernel-space virtual memory, shared between all processes: + ____________________________________________________________|___________________________________________________________ + | | | | + ff1bfffffee00000 | -57 PB | ff1bfffffeffffff | 2 MB | fixmap + ff1bffffff000000 | -57 PB | ff1bffffffffffff | 16 MB | PCI io + ff1c000000000000 | -57 PB | ff1fffffffffffff | 1 PB | vmemmap + ff20000000000000 | -56 PB | ff5fffffffffffff | 16 PB | vmalloc/ioremap space + ff60000000000000 | -40 PB | ffdeffffffffffff | 32 PB | direct mapping of all physical memory + ffdf000000000000 | -8 PB | fffffffeffffffff | 8 PB | kasan + __________________|____________|__________________|_________|____________________________________________________________ + | + | Identical layout to the 39-bit one from here on: + ____________________________________________________________|____________________________________________________________ + | | | | + ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | modules, BPF + ffffffff80000000 | -2 GB | ffffffffffffffff | 2 GB | kernel + __________________|____________|__________________|_________|____________________________________________________________ diff --git a/Documentation/scsi/scsi_eh.rst b/Documentation/scsi/scsi_eh.rst index bad624fab823..104d09e9af09 100644 --- a/Documentation/scsi/scsi_eh.rst +++ b/Documentation/scsi/scsi_eh.rst @@ -92,14 +92,17 @@ The timeout handler is scsi_timeout(). When a timeout occurs, this function 1. invokes optional hostt->eh_timed_out() callback. Return value can be one of - - BLK_EH_RESET_TIMER + - SCSI_EH_RESET_TIMER This indicates that more time is required to finish the command. Timer is restarted. - - BLK_EH_DONE + - SCSI_EH_NOT_HANDLED eh_timed_out() callback did not handle the command. Step #2 is taken. + - SCSI_EH_DONE + eh_timed_out() completed the command. + 2. scsi_abort_command() is invoked to schedule an asynchronous abort which may issue a retry scmd->allowed + 1 times. Asynchronous aborts are not invoked for commands for which the SCSI_EH_ABORT_SCHEDULED flag is set (this diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst index 0bfb4c339748..9bc9db8ec651 100644 --- a/Documentation/security/keys/trusted-encrypted.rst +++ b/Documentation/security/keys/trusted-encrypted.rst @@ -350,7 +350,8 @@ Load an encrypted key "evm" from saved blob:: Instantiate an encrypted key "evm" using user-provided decrypted data:: - $ keyctl add encrypted evm "new default user:kmk 32 `cat evm_decrypted_data.blob`" @u + $ evmkey=$(dd if=/dev/urandom bs=1 count=32 | xxd -c32 -p) + $ keyctl add encrypted evm "new default user:kmk 32 $evmkey" @u 794890253 $ keyctl print 794890253 diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css new file mode 100644 index 000000000000..45a624fdcf2c --- /dev/null +++ b/Documentation/sphinx-static/custom.css @@ -0,0 +1,29 @@ +/* SPDX-License-Identifier: GPL-2.0 */ +/* + * CSS tweaks for the Alabaster theme + */ + +/* Shrink the headers a bit */ +div.body h1 { font-size: 180%; } +div.body h2 { font-size: 150%; } +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; } +/* Tweak document margins and don't force width */ +div.document { + margin: 20px 10px 0 10px; + width: auto; +} + +/* + * Parameters for the display of function prototypes and such included + * from C source files. + */ +dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; } +/* indent lines 2+ of multi-line function prototypes */ +dl.function dt { margin-left: 10em; text-indent: -10em; } +dt.sig-object { font-size: larger; } +div.kernelindent { margin-left: 2em; margin-right: 4em; } diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt index 2c573541ab71..335b53df35e2 100644 --- a/Documentation/sphinx/requirements.txt +++ b/Documentation/sphinx/requirements.txt @@ -1,4 +1,3 @@ # jinja2>=3.1 is not compatible with Sphinx<4.0 jinja2<3.1 -sphinx_rtd_theme Sphinx==2.4.4 diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst index af65004a80aa..b51f38527e14 100644 --- a/Documentation/subsystem-apis.rst +++ b/Documentation/subsystem-apis.rst @@ -43,6 +43,7 @@ needed). input/index hwmon/index gpu/index + accel/index security/index sound/index crypto/index diff --git a/Documentation/timers/hrtimers.rst b/Documentation/timers/hrtimers.rst index c1c20a693e8f..7ac448908d1f 100644 --- a/Documentation/timers/hrtimers.rst +++ b/Documentation/timers/hrtimers.rst @@ -118,7 +118,7 @@ existing timer wheel code, as it is mature and well suited. Sharing code was not really a win, due to the different data structures. Also, the hrtimer functions now have clearer behavior and clearer names - such as hrtimer_try_to_cancel() and hrtimer_cancel() [which are roughly -equivalent to del_timer() and del_timer_sync()] - so there's no direct +equivalent to timer_delete() and timer_delete_sync()] - so there's no direct 1:1 mapping between them on the algorithmic level, and thus no real potential for code sharing either. diff --git a/Documentation/tools/index.rst b/Documentation/tools/index.rst index 0bb1e61bdcc0..80488e290e10 100644 --- a/Documentation/tools/index.rst +++ b/Documentation/tools/index.rst @@ -11,6 +11,7 @@ more additions are needed here: :maxdepth: 1 rtla/index + rv/index .. only:: subproject and html diff --git a/Documentation/tools/rv/Makefile b/Documentation/tools/rv/Makefile new file mode 100644 index 000000000000..ec8713c1b35f --- /dev/null +++ b/Documentation/tools/rv/Makefile @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0-only + +INSTALL ?= install +RM ?= rm -f +RMDIR ?= rmdir --ignore-fail-on-non-empty + +PREFIX ?= /usr/share +MANDIR ?= $(PREFIX)/man +MAN1DIR = $(MANDIR)/man1 + +MAN1_RST = $(wildcard rv*.rst) + +_DOC_MAN1 = $(patsubst %.rst,%.1,$(MAN1_RST)) +DOC_MAN1 = $(addprefix $(OUTPUT),$(_DOC_MAN1)) + +RST2MAN_DEP := $(shell command -v rst2man 2>/dev/null) +RST2MAN_OPTS += --verbose + +TEST_RST2MAN = $(shell sh -c "rst2man --version > /dev/null 2>&1 || echo n") + +$(OUTPUT)%.1: %.rst +ifndef RST2MAN_DEP + $(info ********************************************) + $(info ** NOTICE: rst2man not found) + $(info **) + $(info ** Consider installing the latest rst2man from your) + $(info ** distribution, e.g., 'dnf install python3-docutils' on Fedora,) + $(info ** or from source:) + $(info **) + $(info ** https://docutils.sourceforge.io/docs/dev/repository.html ) + $(info **) + $(info ********************************************) + $(error NOTICE: rst2man required to generate man pages) +endif + rst2man $(RST2MAN_OPTS) $< > $@ + +man1: $(DOC_MAN1) +man: man1 + +clean: + $(RM) $(DOC_MAN1) + +install: man + $(INSTALL) -d -m 755 $(DESTDIR)$(MAN1DIR) + $(INSTALL) -m 644 $(DOC_MAN1) $(DESTDIR)$(MAN1DIR) + +uninstall: + $(RM) $(addprefix $(DESTDIR)$(MAN1DIR)/,$(_DOC_MAN1)) + $(RMDIR) $(DESTDIR)$(MAN1DIR) + +.PHONY: man man1 clean install uninstall +.DEFAULT_GOAL := man diff --git a/Documentation/tools/rv/common_appendix.rst b/Documentation/tools/rv/common_appendix.rst new file mode 100644 index 000000000000..f4239192bee8 --- /dev/null +++ b/Documentation/tools/rv/common_appendix.rst @@ -0,0 +1,16 @@ +REPORTING BUGS +============== + +Report bugs to <linux-kernel@vger.kernel.org> +and <linux-trace-devel@vger.kernel.org> + +LICENSE +======= + +**rv** is Free Software licensed under the GNU GPLv2 + +COPYING +======= + +Copyright \(C) 2022 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/tools/rv/common_ikm.rst b/Documentation/tools/rv/common_ikm.rst new file mode 100644 index 000000000000..e50a5f8a7142 --- /dev/null +++ b/Documentation/tools/rv/common_ikm.rst @@ -0,0 +1,21 @@ +**-h**, **--help** + + Print the monitor's options and the available reactors list. + +**-r**, **--reactor** *reactor* + + Enables the *reactor*. See **-h** for a list of available reactors. + +**-s**, **--self** + + When tracing (**-t**), also print the events that happened during the **rv** + command itself. If the **rv** command itself generates too many events, + the tool might get busy processing its own events only. + +**-t**, **--trace** + + Trace monitor's events and error. + +**-v**, **--verbose** + + Print debug messages. diff --git a/Documentation/tools/rv/index.rst b/Documentation/tools/rv/index.rst new file mode 100644 index 000000000000..8fd16d91d639 --- /dev/null +++ b/Documentation/tools/rv/index.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== +Runtime verification (rv) tool +============================== + +**rv** tool provides the interface for a collection of runtime verification +(rv) monitors. + +.. toctree:: + :maxdepth: 1 + + rv + rv-list + rv-mon + rv-mon-wip + rv-mon-wwnr + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/tools/rv/rv-list.rst b/Documentation/tools/rv/rv-list.rst new file mode 100644 index 000000000000..51e4608f9e99 --- /dev/null +++ b/Documentation/tools/rv/rv-list.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======= +rv-list +======= +----------------------- +List available monitors +----------------------- + +:Manual section: 1 + +SYNOPSIS +======== + +**rv list** [*OPTIONS*] + +DESCRIPTION +=========== + +The **rv list** command prints all available monitors. These monitors +can be enabled using the **rv mon** command. + +OPTIONS +======= + +**-h**, **--help** + + Print help menu. + +SEE ALSO +======== + +**rv**\(1), **rv-mon**\(1) + +Linux kernel *RV* documentation: +<https://www.kernel.org/doc/html/latest/trace/rv/index.html> + +AUTHOR +====== + +Written by Daniel Bristot de Oliveira <bristot@kernel.org> + +.. include:: common_appendix.rst diff --git a/Documentation/tools/rv/rv-mon-wip.rst b/Documentation/tools/rv/rv-mon-wip.rst new file mode 100644 index 000000000000..2d42104d63d1 --- /dev/null +++ b/Documentation/tools/rv/rv-mon-wip.rst @@ -0,0 +1,44 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========== +rv-mon-wip +========== +---------------------------- +Wakeup In Preemptive monitor +---------------------------- + +:Manual section: 1 + +SYNOPSIS +======== + +**rv mon wip** [*OPTIONS*] + +DESCRIPTION +=========== + +The wakeup in preemptive (**wip**) monitor is a sample per-cpu monitor that +checks if the wakeup events always take place with preemption disabled. + +See kernel documentation for further information about this monitor: +<https://docs.kernel.org/trace/rv/monitor_wip.html> + +OPTIONS +======= + +.. include:: common_ikm.rst + +SEE ALSO +======== + +**rv**\(1), **rv-mon**\(1) + +Linux kernel *RV* documentation: +<https://www.kernel.org/doc/html/latest/trace/rv/index.html> + +AUTHOR +====== + +Written by Daniel Bristot de Oliveira <bristot@kernel.org> + +.. include:: common_appendix.rst diff --git a/Documentation/tools/rv/rv-mon-wwnr.rst b/Documentation/tools/rv/rv-mon-wwnr.rst new file mode 100644 index 000000000000..a18f3fd54af4 --- /dev/null +++ b/Documentation/tools/rv/rv-mon-wwnr.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========== +rv-mon-wwnr +=========== +-------------------------------- +Wakeup While Not Running monitor +-------------------------------- + +:Manual section: 1 + +SYNOPSIS +======== + +**rv mon wip** [*OPTIONS*] + +DESCRIPTION +=========== + +The wakeup while not running (**wwnr**) is a per-task sample monitor. + +See kernel documentation for further information about this monitor: +<https://docs.kernel.org/trace/rv/monitor_wwnr.html> + +OPTIONS +======= + +.. include:: common_ikm.rst + +SEE ALSO +======== + +**rv**\(1), **rv-mon**\(1) + +Linux kernel *RV* documentation: +<https://www.kernel.org/doc/html/latest/trace/rv/index.html> + +AUTHOR +====== + +Written by Daniel Bristot de Oliveira <bristot@kernel.org> + +.. include:: common_appendix.rst diff --git a/Documentation/tools/rv/rv-mon.rst b/Documentation/tools/rv/rv-mon.rst new file mode 100644 index 000000000000..af0f329a7c9c --- /dev/null +++ b/Documentation/tools/rv/rv-mon.rst @@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======= +rv-list +======= +----------------------- +List available monitors +----------------------- + +:Manual section: 1 + +SYNOPSIS +======== + +**rv mon** [*-h*] **monitor_name** [*-h*] [*MONITOR OPTIONS*] + +DESCRIPTION +=========== + +The **rv mon** command runs the monitor named *monitor_name*. Each monitor +has its own set of options. The **rv list** command shows all available +monitors. + +OPTIONS +======= + +**-h**, **--help** + + Print help menu. + +AVAILABLE MONITORS +================== + +The **rv** tool provides the interface for a set of monitors. Use the +**rv list** command to list all available monitors. + +Each monitor has its own set of options. See man **rv-mon**-*monitor_name* +for details about each specific monitor. Also, running **rv mon** +**monitor_name** **-h** display the help menu with the available +options. + +SEE ALSO +======== + +**rv**\(1), **rv-mon**\(1) + +Linux kernel *RV* documentation: +<https://www.kernel.org/doc/html/latest/trace/rv/index.html> + +AUTHOR +====== + +Written by Daniel Bristot de Oliveira <bristot@kernel.org> + +.. include:: common_appendix.rst diff --git a/Documentation/tools/rv/rv.rst b/Documentation/tools/rv/rv.rst new file mode 100644 index 000000000000..cee93dc21a76 --- /dev/null +++ b/Documentation/tools/rv/rv.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: GPL-2.0 + +== +rv +== +-------------------- +Runtime Verification +-------------------- + +:Manual section: 1 + +SYNOPSIS +======== + +**rv** *COMMAND* [*OPTIONS*] + +DESCRIPTION +=========== + +Runtime Verification (**RV**) is a lightweight (yet rigorous) method +for formal verification with a practical approach for complex systems. +Instead of relying on a fine-grained model of a system (e.g., a +re-implementation a instruction level), RV works by analyzing the trace +of the system's actual execution, comparing it against a formal +specification of the system behavior. + +The **rv** tool provides the interface for a collection of runtime +verification (rv) monitors. + +COMMANDS +======== + +**list** + + List all available monitors. + +**mon** + + Run monitor. + +OPTIONS +======= + +**-h**, **--help** + + Display the help text. + +For other options, see the man page for the corresponding command. + +SEE ALSO +======== + +**rv-list**\(1), **rv-mon**\(1) + +Linux kernel *RV* documentation: +<https://www.kernel.org/doc/html/latest/trace/rv/index.html> + +AUTHOR +====== + +Daniel Bristot de Oliveira <bristot@kernel.org> + +.. include:: common_appendix.rst diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index 60bceb018d6a..21f01d32c959 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -2940,7 +2940,7 @@ Produces:: bash-1994 [000] .... 4342.324898: ima_get_action <-process_measurement bash-1994 [000] .... 4342.324898: ima_match_policy <-ima_get_action bash-1994 [000] .... 4342.324899: do_truncate <-do_last - bash-1994 [000] .... 4342.324899: should_remove_suid <-do_truncate + bash-1994 [000] .... 4342.324899: setattr_should_drop_suidgid <-do_truncate bash-1994 [000] .... 4342.324899: notify_change <-do_truncate bash-1994 [000] .... 4342.324900: current_fs_time <-notify_change bash-1994 [000] .... 4342.324900: current_kernel_time <-current_fs_time diff --git a/Documentation/translations/index.rst b/Documentation/translations/index.rst index 1175a47d07f0..b826c34791c0 100644 --- a/Documentation/translations/index.rst +++ b/Documentation/translations/index.rst @@ -12,6 +12,7 @@ Translations it_IT/index ko_KR/index ja_JP/index + sp_SP/index .. _translations_disclaimer: diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst index 51af37f2d621..b8ecf41273c5 100644 --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst @@ -990,7 +990,7 @@ potreste fare come segue:: while (list) { struct foo *next = list->next; - del_timer(&list->timer); + timer_delete(&list->timer); kfree(list); list = next; } @@ -1003,7 +1003,7 @@ e prenderà il *lock* solo dopo spin_unlock_bh(), e cercherà di eliminare il suo oggetto (che però è già stato eliminato). Questo può essere evitato controllando il valore di ritorno di -del_timer(): se ritorna 1, il temporizzatore è stato già +timer_delete(): se ritorna 1, il temporizzatore è stato già rimosso. Se 0, significa (in questo caso) che il temporizzatore è in esecuzione, quindi possiamo fare come segue:: @@ -1012,7 +1012,7 @@ esecuzione, quindi possiamo fare come segue:: while (list) { struct foo *next = list->next; - if (!del_timer(&list->timer)) { + if (!timer_delete(&list->timer)) { /* Give timer a chance to delete this */ spin_unlock_bh(&list_lock); goto retry; @@ -1026,10 +1026,8 @@ esecuzione, quindi possiamo fare come segue:: Un altro problema è l'eliminazione dei temporizzatori che si riavviano da soli (chiamando add_timer() alla fine della loro esecuzione). Dato che questo è un problema abbastanza comune con una propensione -alle corse critiche, dovreste usare del_timer_sync() -(``include/linux/timer.h``) per gestire questo caso. Questa ritorna il -numero di volte che il temporizzatore è stato interrotto prima che -fosse in grado di fermarlo senza che si riavviasse. +alle corse critiche, dovreste usare timer_delete_sync() +(``include/linux/timer.h``) per gestire questo caso. Velocità della sincronizzazione =============================== @@ -1374,7 +1372,7 @@ contesto, o trattenendo un qualsiasi *lock*. - kfree() -- add_timer() e del_timer() +- add_timer() e timer_delete() Riferimento per l'API dei Mutex =============================== diff --git a/Documentation/translations/ja_JP/howto.rst b/Documentation/translations/ja_JP/howto.rst index b8eeb45a02d4..9b0b3436dfcf 100644 --- a/Documentation/translations/ja_JP/howto.rst +++ b/Documentation/translations/ja_JP/howto.rst @@ -86,9 +86,14 @@ info ページ( info gcc )を見てください。 -------- Linux カーネルのソースコードは GPL ライセンスの下でリリースされていま -す。ライセンスの詳細については、ソースツリーのメインディレクトリに存在 -する、COPYING のファイルを見てください。もしライセンスについてさらに質 -問があれば、Linux Kernel メーリングリストに質問するのではなく、どうぞ +す。ソースツリーのメインディレクトリにある COPYING のファイルを見てく +ださい。Linux カーネルのライセンスルールとソースコード内の +`SPDX <https://spdx.org/>`_ 識別子の使い方は +:ref:`Documentation/process/license-rules.rst <kernel_licensing>` +に説明されています。 + +もしライセンスについてさらに質問があれば、 +Linux Kernel メーリングリストに質問するのではなく、どうぞ 法律家に相談してください。メーリングリストの人達は法律家ではなく、法的 問題については彼らの声明はあてにするべきではありません。 @@ -111,7 +116,7 @@ linux-api@vger.kernel.org に送ることを勧めます。 以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で す- - README + :ref:`Documentation/admin-guide/README.rst <readme>` このファイルは Linuxカーネルの簡単な背景とカーネルを設定(訳注 configure )し、生成(訳注 build )するために必要なことは何かが書かれ ています。 カーネルに関して初めての人はここからスタートすると良い @@ -145,7 +150,8 @@ linux-api@vger.kernel.org に送ることを勧めます。 この他にパッチを作る方法についてのよくできた記述は- "The Perfect Patch" - http://www.ozlabs.org/~akpm/stuff/tpp.txt + https://www.ozlabs.org/~akpm/stuff/tpp.txt + "Linux kernel patch submission format" https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html @@ -237,13 +243,6 @@ Linux カーネルソースツリーの中に含まれる、きれいにし、 れるための基礎を学ぶことができ、そしてもしあなたがまだアイディアを持っ ていない場合には、次にやる仕事の方向性が見えてくるかもしれません。 -もしあなたが、すでにひとまとまりコードを書いていて、カーネルツリーに入 -れたいと思っていたり、それに関する適切な支援を求めたい場合、カーネルメ -ンターズプロジェクトはそのような皆さんを助けるためにできました。ここに -はメーリングリストがあり、以下から参照できます - - - https://selenic.com/mailman/listinfo/kernel-mentors - 実際に Linux カーネルのコードについて修正を加える前に、どうやってその コードが動作するのかを理解することが必要です。そのためには、特別なツー ルの助けを借りてでも、それを直接よく読むことが最良の方法です(ほとんど @@ -280,9 +279,11 @@ https://kernel.org のリポジトリに存在します。 大きな変更は git(カーネルのソース管理ツール、詳細は http://git-scm.com/ 参照) を使って送るのが好ましいやり方ですが、パッ チファイルの形式のまま送るのでも十分です。 - - 2週間後、-rc1 カーネルがリリースされ、この後にはカーネル全体の安定 - 性に影響をあたえるような新機能は含まない類のパッチしか取り込むこと - はできません。新しいドライバ(もしくはファイルシステム)のパッチは + - 2週間後 -rc1 カーネルがリリースされ、新しいカーネルを可能な限り堅牢に + することに焦点が移ります。この期間のパッチのほとんどは退行を修正する + ものとなります。以前から存在していたバグは退行には当たらないため、 + 送るのは重要な修正だけにしてください。 + 新しいドライバ (もしくはファイルシステム) のパッチは -rc1 の後で受け付けられることもあることを覚えておいてください。な ぜなら、変更が独立していて、追加されたコードの外の領域に影響を与え ない限り、退行のリスクは無いからです。-rc1 がリリースされた後、 @@ -308,9 +309,12 @@ Andrew Morton が Linux-kernel メーリングリストにカーネルリリー バージョン番号が3つの数字に分かれているカーネルは -stable カーネルです。 これには最初の2つのバージョン番号の数字に対応した、 -メインラインリリースで見つかったセキュリティ問題や +メジャーメインラインリリースで見つかったセキュリティ問題や 重大な後戻りに対する比較的小さい重要な修正が含まれます。 +メジャー安定版シリーズのそれぞれのリリースは +バージョン番号の3番目を増加させ、最初の2つの番号は同じ値を保ちます。 + これは、開発/実験的バージョンのテストに協力することに興味が無く、最新 の安定したカーネルを使いたいユーザに推奨するブランチです。 @@ -366,16 +370,10 @@ linux-next の実行テストを行う冒険好きなテスターは大いに歓 バグレポート ------------- -https://bugzilla.kernel.org は Linux カーネル開発者がカーネルのバグを追跡する -場所です。ユーザは見つけたバグの全てをこのツールで報告すべきです。どう -kernel bugzilla を使うかの詳細は、以下を参照してください - - - https://bugzilla.kernel.org/page.cgi?id=faq.html - メインカーネルソースディレクトリにあるファイル -admin-guide/reporting-bugs.rstはカーネルバグらしいものについてどうレポー -トするかの良いテンプレートであり、問題の追跡を助けるためにカーネル開発 -者にとってどんな情報が必要なのかの詳細が書かれています。 +'Documentation/admin-guide/reporting-issues.rst' +は、カーネルバグらしきものの報告の仕方、および、カーネル開発者が問題を +追跡する際の手がかりとなる情報についての詳細を説明しています。 バグレポートの管理 ------------------- @@ -388,15 +386,13 @@ admin-guide/reporting-bugs.rstはカーネルバグらしいものについて 道です、なぜなら多くの人は他人のバグの修正に時間を浪費することを好まな いからです。 -すでにレポートされたバグのために仕事をするためには、 -https://bugzilla.kernel.org に行ってください。もし今後のバグレポートに -ついてアドバイスを受けたいのであれば、bugme-new メーリングリスト(新し -いバグレポートだけがここにメールされる) または bugme-janitor メーリン -グリスト(bugzilla の変更毎にここにメールされる)を購読できます。 - - https://lists.linux-foundation.org/mailman/listinfo/bugme-new - - https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors +すでにレポートされたバグの作業をするためには、興味のあるサブシステムを +見つけ、そのサブシステムのバグの報告先 (多くの場合メーリングリスト、 +稀にバグトラッカー) を MAINTAINERS ファイルで調べてください。 +そのアーカイブで最近の報告を検索し、できそうなものに力を貸してください。 +https://bugzilla.kernel.org でバグ報告を調べようとする人もいるでしょう。 +これは限られた一部のサブシステムのバグ報告と追跡に利用されるとともに、 +とりわけ、カーネル全体に対するバグの登録先となっています。 メーリングリスト ---------------- @@ -621,7 +617,7 @@ Linux カーネルコミュニティは、一度に大量のコードの塊を ントの ChangeLog セクションを見てください - "The Perfect Patch" - http://www.ozlabs.org/~akpm/stuff/tpp.txt + https://www.ozlabs.org/~akpm/stuff/tpp.txt これらはどれも、実行することが時にはとても困難です。これらの例を完璧に 実施するには数年かかるかもしれません。これは継続的な改善のプロセスであ diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt index 75aa5531cc7d..7165927a708e 100644 --- a/Documentation/translations/ko_KR/memory-barriers.txt +++ b/Documentation/translations/ko_KR/memory-barriers.txt @@ -80,7 +80,7 @@ Documentation/memory-barriers.txt - 메모리 배리어의 종류. - 메모리 배리어에 대해 가정해선 안될 것. - - 데이터 의존성 배리어 (역사적). + - 주소 데이터 의존성 배리어 (역사적). - 컨트롤 의존성. - SMP 배리어 짝맞추기. - 메모리 배리어 시퀀스의 예. @@ -217,7 +217,7 @@ Documentation/memory-barriers.txt P = &B D = *Q; D 로 읽혀지는 값은 CPU 2 에서 P 로부터 읽혀진 주소값에 의존적이기 때문에 여기엔 -분명한 데이터 의존성이 있습니다. 하지만 이 이벤트들의 실행 결과로는 아래의 +분명한 주소 의존성이 있습니다. 하지만 이 이벤트들의 실행 결과로는 아래의 결과들이 모두 나타날 수 있습니다: (Q == &A) and (D == 1) @@ -416,19 +416,19 @@ CPU 에게 기대할 수 있는 최소한의 보장사항 몇가지가 있습니 하나씩 요청해 집어넣습니다. 쓰기 배리어 앞의 모든 스토어 오퍼레이션들은 쓰기 배리어 뒤의 모든 스토어 오퍼레이션들보다 _앞서_ 수행될 겁니다. - [!] 쓰기 배리어들은 읽기 또는 데이터 의존성 배리어와 함께 짝을 맞춰 + [!] 쓰기 배리어들은 읽기 또는 주소 의존성 배리어와 함께 짝을 맞춰 사용되어야만 함을 알아두세요; "SMP 배리어 짝맞추기" 서브섹션을 참고하세요. - (2) 데이터 의존성 배리어. + (2) 주소 의존성 배리어 (역사적). - 데이터 의존성 배리어는 읽기 배리어의 보다 완화된 형태입니다. 두개의 로드 + 주소 의존성 배리어는 읽기 배리어의 보다 완화된 형태입니다. 두개의 로드 오퍼레이션이 있고 두번째 것이 첫번째 것의 결과에 의존하고 있을 때(예: 두번째 로드가 참조할 주소를 첫번째 로드가 읽는 경우), 두번째 로드가 읽어올 데이터는 첫번째 로드에 의해 그 주소가 얻어진 뒤에 업데이트 됨을 보장하기 - 위해서 데이터 의존성 배리어가 필요할 수 있습니다. + 위해서 주소 의존성 배리어가 필요할 수 있습니다. - 데이터 의존성 배리어는 상호 의존적인 로드 오퍼레이션들 사이의 부분적 순서 + 주소 의존성 배리어는 상호 의존적인 로드 오퍼레이션들 사이의 부분적 순서 세우기입니다; 스토어 오퍼레이션들이나 독립적인 로드들, 또는 중복되는 로드들에 대해서는 어떤 영향도 끼치지 않습니다. @@ -436,37 +436,41 @@ CPU 에게 기대할 수 있는 최소한의 보장사항 몇가지가 있습니 오퍼레이션들을 던져 넣고 있으며, 거기에 관심이 있는 다른 CPU 는 그 오퍼레이션들을 메모리 시스템이 실행한 결과를 인지할 수 있습니다. 이처럼 다른 CPU 의 스토어 오퍼레이션의 결과에 관심을 두고 있는 CPU 가 수행 요청한 - 데이터 의존성 배리어는, 배리어 앞의 어떤 로드 오퍼레이션이 다른 CPU 에서 + 주소 의존성 배리어는, 배리어 앞의 어떤 로드 오퍼레이션이 다른 CPU 에서 던져 넣은 스토어 오퍼레이션과 같은 영역을 향했다면, 그런 스토어 - 오퍼레이션들이 만들어내는 결과가 데이터 의존성 배리어 뒤의 로드 + 오퍼레이션들이 만들어내는 결과가 주소 의존성 배리어 뒤의 로드 오퍼레이션들에게는 보일 것을 보장합니다. 이 순서 세우기 제약에 대한 그림을 보기 위해선 "메모리 배리어 시퀀스의 예" 서브섹션을 참고하시기 바랍니다. - [!] 첫번째 로드는 반드시 _데이터_ 의존성을 가져야지 컨트롤 의존성을 가져야 + [!] 첫번째 로드는 반드시 _주소_ 의존성을 가져야지 컨트롤 의존성을 가져야 하는게 아님을 알아두십시오. 만약 두번째 로드를 위한 주소가 첫번째 로드에 의존적이지만 그 의존성은 조건적이지 그 주소 자체를 가져오는게 아니라면, 그것은 _컨트롤_ 의존성이고, 이 경우에는 읽기 배리어나 그보다 강력한 무언가가 필요합니다. 더 자세한 내용을 위해서는 "컨트롤 의존성" 서브섹션을 참고하시기 바랍니다. - [!] 데이터 의존성 배리어는 보통 쓰기 배리어들과 함께 짝을 맞춰 사용되어야 + [!] 주소 의존성 배리어는 보통 쓰기 배리어들과 함께 짝을 맞춰 사용되어야 합니다; "SMP 배리어 짝맞추기" 서브섹션을 참고하세요. + [!] 커널 v5.9 릴리즈에서 명시적 주소 의존성 배리어를 위한 커널 API 들이 + 삭제되었습니다. 오늘날에는 공유된 변수들의 로드를 표시하는 READ_ONCE() 나 + rcu_dereference() 와 같은 API 들은 묵시적으로 주소 의존성 배리어를 제공합니다. + (3) 읽기 (또는 로드) 메모리 배리어. - 읽기 배리어는 데이터 의존성 배리어 기능의 보장사항에 더해서 배리어보다 - 앞서 명시된 모든 LOAD 오퍼레이션들이 배리어 뒤에 명시되는 모든 LOAD + 읽기 배리어는 주소 의존성 배리어 기능의 보장사항에 더해서 배리어보다 앞서 + 명시된 모든 LOAD 오퍼레이션들이 배리어 뒤에 명시되는 모든 LOAD 오퍼레이션들보다 먼저 행해진 것으로 시스템의 다른 컴포넌트들에 보여질 것을 보장합니다. 읽기 배리어는 로드 오퍼레이션에 행해지는 부분적 순서 세우기입니다; 스토어 오퍼레이션에 대해서는 어떤 영향도 끼치지 않습니다. - 읽기 메모리 배리어는 데이터 의존성 배리어를 내장하므로 데이터 의존성 - 배리어를 대신할 수 있습니다. + 읽기 메모리 배리어는 주소 의존성 배리어를 내장하므로 주소 의존성 배리어를 + 대신할 수 있습니다. [!] 읽기 배리어는 일반적으로 쓰기 배리어들과 함께 짝을 맞춰 사용되어야 합니다; "SMP 배리어 짝맞추기" 서브섹션을 참고하세요. @@ -571,16 +575,20 @@ ACQUIRE 는 해당 오퍼레이션의 로드 부분에만 적용되고 RELEASE Documentation/core-api/dma-api.rst -데이터 의존성 배리어 (역사적) ------------------------------ +주소 의존성 배리어 (역사적) +--------------------------- 리눅스 커널 v4.15 기준으로, smp_mb() 가 DEC Alpha 용 READ_ONCE() 코드에 추가되었는데, 이는 이 섹션에 주의를 기울여야 하는 사람들은 DEC Alpha 아키텍쳐 전용 코드를 만드는 사람들과 READ_ONCE() 자체를 만드는 사람들 뿐임을 의미합니다. -그런 분들을 위해, 그리고 역사에 관심 있는 분들을 위해, 여기 데이터 의존성 +그런 분들을 위해, 그리고 역사에 관심 있는 분들을 위해, 여기 주소 의존성 배리어에 대한 이야기를 적습니다. -데이터 의존성 배리어의 사용에 있어 지켜야 하는 사항들은 약간 미묘하고, 데이터 +[!] 주소 의존성은 로드에서 로드로와 로드에서 스토어로의 관계들 모두에서 +나타나지만, 주소 의존성 배리어는 로드에서 스토어로의 상황에서는 필요하지 +않습니다. + +주소 의존성 배리어의 사용에 있어 지켜야 하는 사항들은 약간 미묘하고, 데이터 의존성 배리어가 사용되어야 하는 상황도 항상 명백하지는 않습니다. 설명을 위해 다음의 이벤트 시퀀스를 생각해 봅시다: @@ -590,10 +598,13 @@ ACQUIRE 는 해당 오퍼레이션의 로드 부분에만 적용되고 RELEASE B = 4; <쓰기 배리어> WRITE_ONCE(P, &B) - Q = READ_ONCE(P); + Q = READ_ONCE_OLD(P); D = *Q; -여기엔 분명한 데이터 의존성이 존재하므로, 이 시퀀스가 끝났을 때 Q 는 &A 또는 &B +[!] READ_ONCE_OLD() 는 4.15 커널 전의 버전에서의, 주소 의존성 배리어를 내포하지 +않는 READ_ONCE() 에 해당합니다. + +여기엔 분명한 주소 의존성이 존재하므로, 이 시퀀스가 끝났을 때 Q 는 &A 또는 &B 일 것이고, 따라서: (Q == &A) 는 (D == 1) 를, @@ -608,8 +619,8 @@ ACQUIRE 는 해당 오퍼레이션의 로드 부분에만 적용되고 RELEASE 그렇지 않습니다, 그리고 이 현상은 (DEC Alpha 와 같은) 여러 CPU 에서 실제로 발견될 수 있습니다. -이 문제 상황을 제대로 해결하기 위해, 데이터 의존성 배리어나 그보다 강화된 -무언가가 주소를 읽어올 때와 데이터를 읽어올 때 사이에 추가되어야만 합니다: +이 문제 상황을 제대로 해결하기 위해, READ_ONCE() 는 커널 v4.15 릴리즈 부터 +묵시적 주소 의존성 배리어를 제공합니다: CPU 1 CPU 2 =============== =============== @@ -618,7 +629,7 @@ ACQUIRE 는 해당 오퍼레이션의 로드 부분에만 적용되고 RELEASE <쓰기 배리어> WRITE_ONCE(P, &B); Q = READ_ONCE(P); - <데이터 의존성 배리어> + <묵시적 주소 의존성 배리어> D = *Q; 이 변경은 앞의 처음 두가지 결과 중 하나만이 발생할 수 있고, 세번째의 결과는 @@ -634,7 +645,7 @@ P 는 짝수 번호 캐시 라인에 저장되어 있고, 변수 B 는 홀수 중이라면 포인터 P (&B) 의 새로운 값과 변수 B 의 기존 값 (2) 를 볼 수 있습니다. -의존적 쓰기들의 순서를 맞추는데에는 데이터 의존성 배리어가 필요치 않은데, 이는 +의존적 쓰기들의 순서를 맞추는데에는 주소 의존성 배리어가 필요치 않은데, 이는 리눅스 커널이 지원하는 CPU 들은 (1) 쓰기가 정말로 일어날지, (2) 쓰기가 어디에 이루어질지, 그리고 (3) 쓰여질 값을 확실히 알기 전까지는 쓰기를 수행하지 않기 때문입니다. 하지만 "컨트롤 의존성" 섹션과 @@ -647,12 +658,12 @@ Documentation/RCU/rcu_dereference.rst 파일을 주의 깊게 읽어 주시기 B = 4; <쓰기 배리어> WRITE_ONCE(P, &B); - Q = READ_ONCE(P); + Q = READ_ONCE_OLD(P); WRITE_ONCE(*Q, 5); -따라서, Q 로의 읽기와 *Q 로의 쓰기 사이에는 데이터 종속성 배리어가 필요치 -않습니다. 달리 말하면, 데이터 종속성 배리어가 없더라도 다음 결과는 생기지 -않습니다: +따라서, Q 로의 읽기와 *Q 로의 쓰기 사이에는 주소 의존성 배리어가 필요치 +않습니다. 달리 말하면, 오늘날의 READ_ONCE() 의 묵시적 주소 의존성 배리어가 +없더라도 다음 결과는 생기지 않습니다: (Q == &B) && (B == 4) @@ -663,16 +674,16 @@ Documentation/RCU/rcu_dereference.rst 파일을 주의 깊게 읽어 주시기 해줍니다. -데이터 의존성에 의해 제공되는 이 순서규칙은 이를 포함하고 있는 CPU 에 +주소 의존성에 의해 제공되는 이 순서규칙은 이를 포함하고 있는 CPU 에 지역적임을 알아두시기 바랍니다. 더 많은 정보를 위해선 "Multicopy 원자성" 섹션을 참고하세요. -데이터 의존성 배리어는 매우 중요한데, 예를 들어 RCU 시스템에서 그렇습니다. +주소 의존성 배리어는 매우 중요한데, 예를 들어 RCU 시스템에서 그렇습니다. include/linux/rcupdate.h 의 rcu_assign_pointer() 와 rcu_dereference() 를 -참고하세요. 여기서 데이터 의존성 배리어는 RCU 로 관리되는 포인터의 타겟을 현재 -타겟에서 수정된 새로운 타겟으로 바꾸는 작업에서 새로 수정된 타겟이 초기화가 -완료되지 않은 채로 보여지는 일이 일어나지 않게 해줍니다. +참고하세요. 이것들은 RCU 로 관리되는 포인터의 타겟을 현재 타겟에서 수정된 +새로운 타겟으로 바꾸는 작업에서 새로 수정된 타겟이 초기화가 완료되지 않은 채로 +보여지는 일이 일어나지 않게 해줍니다. 더 많은 예를 위해선 "캐시 일관성" 서브섹션을 참고하세요. @@ -684,16 +695,17 @@ include/linux/rcupdate.h 의 rcu_assign_pointer() 와 rcu_dereference() 를 약간 다루기 어려울 수 있습니다. 이 섹션의 목적은 여러분이 컴파일러의 무시로 인해 여러분의 코드가 망가지는 걸 막을 수 있도록 돕는겁니다. -로드-로드 컨트롤 의존성은 데이터 의존성 배리어만으로는 정확히 동작할 수가 -없어서 읽기 메모리 배리어를 필요로 합니다. 아래의 코드를 봅시다: +로드-로드 컨트롤 의존성은 (묵시적인) 주소 의존성 배리어만으로는 정확히 동작할 +수가 없어서 읽기 메모리 배리어를 필요로 합니다. 아래의 코드를 봅시다: q = READ_ONCE(a); + <묵시적 주소 의존성 배리어> if (q) { - <데이터 의존성 배리어> /* BUG: No data dependency!!! */ + /* BUG: No address dependency!!! */ p = READ_ONCE(b); } -이 코드는 원하는 대로의 효과를 내지 못할 수 있는데, 이 코드에는 데이터 의존성이 +이 코드는 원하는 대로의 효과를 내지 못할 수 있는데, 이 코드에는 주소 의존성이 아니라 컨트롤 의존성이 존재하기 때문으로, 이런 상황에서 CPU 는 실행 속도를 더 빠르게 하기 위해 분기 조건의 결과를 예측하고 코드를 재배치 할 수 있어서 다른 CPU 는 b 로부터의 로드 오퍼레이션이 a 로부터의 로드 오퍼레이션보다 먼저 발생한 @@ -930,9 +942,9 @@ CPU 간 상호작용을 다룰 때에 일부 타입의 메모리 배리어는 범용 배리어들은 범용 배리어끼리도 짝을 맞추지만 multicopy 원자성이 없는 대부분의 다른 타입의 배리어들과도 짝을 맞춥니다. ACQUIRE 배리어는 RELEASE 배리어와 짝을 맞춥니다만, 둘 다 범용 배리어를 포함해 다른 배리어들과도 짝을 -맞출 수 있습니다. 쓰기 배리어는 데이터 의존성 배리어나 컨트롤 의존성, ACQUIRE +맞출 수 있습니다. 쓰기 배리어는 주소 의존성 배리어나 컨트롤 의존성, ACQUIRE 배리어, RELEASE 배리어, 읽기 배리어, 또는 범용 배리어와 짝을 맞춥니다. -비슷하게 읽기 배리어나 컨트롤 의존성, 또는 데이터 의존성 배리어는 쓰기 배리어나 +비슷하게 읽기 배리어나 컨트롤 의존성, 또는 주소 의존성 배리어는 쓰기 배리어나 ACQUIRE 배리어, RELEASE 배리어, 또는 범용 배리어와 짝을 맞추는데, 다음과 같습니다: @@ -951,7 +963,7 @@ ACQUIRE 배리어, RELEASE 배리어, 또는 범용 배리어와 짝을 맞추 a = 1; <쓰기 배리어> WRITE_ONCE(b, &a); x = READ_ONCE(b); - <데이터 의존성 배리어> + <묵시적 주소 의존성 배리어> y = *x; 또는: @@ -970,8 +982,8 @@ ACQUIRE 배리어, RELEASE 배리어, 또는 범용 배리어와 짝을 맞추 기본적으로, 여기서의 읽기 배리어는 "더 완화된" 타입일 순 있어도 항상 존재해야 합니다. -[!] 쓰기 배리어 앞의 스토어 오퍼레이션은 일반적으로 읽기 배리어나 데이터 -의존성 배리어 뒤의 로드 오퍼레이션과 매치될 것이고, 반대도 마찬가지입니다: +[!] 쓰기 배리어 앞의 스토어 오퍼레이션은 일반적으로 읽기 배리어나 주소 의존성 +배리어 뒤의 로드 오퍼레이션과 매치될 것이고, 반대도 마찬가지입니다: CPU 1 CPU 2 =================== =================== @@ -1023,7 +1035,7 @@ ACQUIRE 배리어, RELEASE 배리어, 또는 범용 배리어와 짝을 맞추 V -둘째, 데이터 의존성 배리어는 데이터 의존적 로드 오퍼레이션들의 부분적 순서 +둘째, 주소 의존성 배리어는 데이터 의존적 로드 오퍼레이션들의 부분적 순서 세우기로 동작합니다. 다음 일련의 이벤트들을 보세요: CPU 1 CPU 2 @@ -1069,7 +1081,7 @@ ACQUIRE 배리어, RELEASE 배리어, 또는 범용 배리어와 짝을 맞추 앞의 예에서, CPU 2 는 (B 의 값이 될) *C 의 값 읽기가 C 의 LOAD 뒤에 이어짐에도 B 가 7 이라는 결과를 얻습니다. -하지만, 만약 데이터 의존성 배리어가 C 의 로드와 *C (즉, B) 의 로드 사이에 +하지만, 만약 주소 의존성 배리어가 C 의 로드와 *C (즉, B) 의 로드 사이에 있었다면: CPU 1 CPU 2 @@ -1080,7 +1092,7 @@ B 가 7 이라는 결과를 얻습니다. <쓰기 배리어> STORE C = &B LOAD X STORE D = 4 LOAD C (gets &B) - <데이터 의존성 배리어> + <주소 의존성 배리어> LOAD *C (reads B) 다음과 같이 됩니다: @@ -1103,7 +1115,7 @@ B 가 7 이라는 결과를 얻습니다. | +-------+ | | | | X->9 |------>| | | +-------+ | | - C 로의 스토어 앞의 ---> \ ddddddddddddddddd | | + C 로의 스토어 앞의 ---> \ aaaaaaaaaaaaaaaaa | | 모든 이벤트 결과가 \ +-------+ | | 뒤의 로드에게 ----->| B->2 |------>| | 보이게 강제한다 +-------+ | | @@ -1291,7 +1303,7 @@ A 의 로드 두개가 모두 B 의 로드 뒤에 있지만, 서로 다른 값 즉각 완료한다 : : +-------+ -읽기 배리어나 데이터 의존성 배리어를 두번째 로드 직전에 놓는다면: +읽기 배리어나 주소 의존성 배리어를 두번째 로드 직전에 놓는다면: CPU 1 CPU 2 ======================= ======================= @@ -1785,21 +1797,20 @@ READ_ONCE(jiffies) 라고 할 필요가 없습니다. READ_ONCE() 와 WRITE_ONC CPU 메모리 배리어 ----------------- -리눅스 커널은 다음의 여덟개 기본 CPU 메모리 배리어를 가지고 있습니다: +리눅스 커널은 다음의 일곱개 기본 CPU 메모리 배리어를 가지고 있습니다: TYPE MANDATORY SMP CONDITIONAL - =============== ======================= =========================== + =============== ======================= =============== 범용 mb() smp_mb() 쓰기 wmb() smp_wmb() 읽기 rmb() smp_rmb() - 데이터 의존성 READ_ONCE() + 주소 의존성 READ_ONCE() -데이터 의존성 배리어를 제외한 모든 메모리 배리어는 컴파일러 배리어를 -포함합니다. 데이터 의존성은 컴파일러에의 추가적인 순서 보장을 포함하지 -않습니다. +주소 의존성 배리어를 제외한 모든 메모리 배리어는 컴파일러 배리어를 포함합니다. +주소 의존성은 컴파일러에의 추가적인 순서 보장을 포함하지 않습니다. -방백: 데이터 의존성이 있는 경우, 컴파일러는 해당 로드를 올바른 순서로 일으킬 +방백: 주소 의존성이 있는 경우, 컴파일러는 해당 로드를 올바른 순서로 일으킬 것으로 (예: `a[b]` 는 a[b] 를 로드 하기 전에 b 의 값을 먼저 로드한다) 기대되지만, C 언어 사양에는 컴파일러가 b 의 값을 추측 (예: 1 과 같음) 해서 b 로드 전에 a 로드를 하는 코드 (예: tmp = a[1]; if (b != 1) tmp = a[b]; ) 를 @@ -1863,6 +1874,7 @@ Mandatory 배리어들은 SMP 시스템에서도 UP 시스템에서도 SMP 효 (*) dma_wmb(); (*) dma_rmb(); + (*) dma_mb(); 이것들은 CPU 와 DMA 가능한 디바이스에서 모두 액세스 가능한 공유 메모리의 읽기, 쓰기 작업들의 순서를 보장하기 위해 consistent memory 에서 사용하기 @@ -1893,12 +1905,13 @@ Mandatory 배리어들은 SMP 시스템에서도 UP 시스템에서도 SMP 효 dma_rmb() 는 디스크립터로부터 데이터를 읽어오기 전에 디바이스가 소유권을 내려놓았을 것을 보장하고, dma_wmb() 는 디바이스가 자신이 소유권을 다시 - 가졌음을 보기 전에 디스크립터에 데이터가 쓰였을 것을 보장합니다. 참고로, - writel() 을 사용하면 캐시 일관성이 있는 메모리 (cache coherent memory) - 쓰기가 MMIO 영역에의 쓰기 전에 완료되었을 것을 보장하므로 writel() 앞에 - wmb() 를 실행할 필요가 없음을 알아두시기 바랍니다. writel() 보다 비용이 - 저렴한 writel_relaxed() 는 이런 보장을 제공하지 않으므로 여기선 사용되지 - 않아야 합니다. + 가졌음을 보기 전에 디스크립터에 데이터가 쓰였을 것을 보장합니다. dma_mb() + 는 dma_rmb() 와 dma_wmb() 를 모두 내포합니다. 참고로, writel() 을 + 사용하면 캐시 일관성이 있는 메모리 (cache coherent memory) 쓰기가 MMIO + 영역에의 쓰기 전에 완료되었을 것을 보장하므로 writel() 앞에 wmb() 를 + 실행할 필요가 없음을 알아두시기 바랍니다. writel() 보다 비용이 저렴한 + writel_relaxed() 는 이런 보장을 제공하지 않으므로 여기선 사용되지 않아야 + 합니다. writel_relaxed() 와 같은 완화된 I/O 접근자들에 대한 자세한 내용을 위해서는 "커널 I/O 배리어의 효과" 섹션을, consistent memory 에 대한 자세한 내용을 @@ -1918,6 +1931,14 @@ Mandatory 배리어들은 SMP 시스템에서도 UP 시스템에서도 SMP 효 Persistent memory 에서의 로드를 위해선 현재의 읽기 메모리 배리어로도 읽기 순서를 보장하는데 충분합니다. + (*) io_stop_wc(); + + 쓰기와 결합된 특성을 갖는 메모리 액세스의 경우 (예: ioremap_wc() 에 의해 + 리턴되는 것들), CPU 는 앞의 액세스들이 뒤따르는 것들과 병합되게끔 기다릴 + 수 있습니다. io_stop_wc() 는 그런 기다림이 성능에 영향을 끼칠 수 있을 때, + 이 매크로 앞의 쓰기-결합된 메모리 액세스들이 매크로 뒤의 것들과 병합되는 + 것을 방지하기 위해 사용될 수 있습니다. + ========================= 암묵적 커널 메모리 배리어 ========================= @@ -2827,9 +2848,9 @@ ld.acq 와 stl.rel 인스트럭션을 각각 만들어 내도록 합니다. DEC Alpha CPU 는 가장 완화된 메모리 순서의 CPU 중 하나입니다. 뿐만 아니라, Alpha CPU 의 일부 버전은 분할된 데이터 캐시를 가지고 있어서, 의미적으로 관계되어 있는 두개의 캐시 라인이 서로 다른 시간에 업데이트 되는게 가능합니다. -이게 데이터 의존성 배리어가 정말 필요해지는 부분인데, 데이터 의존성 배리어는 -메모리 일관성 시스템과 함께 두개의 캐시를 동기화 시켜서, 포인터 변경과 새로운 -데이터의 발견을 올바른 순서로 일어나게 하기 때문입니다. +이게 주소 의존성 배리어가 정말 필요해지는 부분인데, 주소 의존성 배리어는 메모리 +일관성 시스템과 함께 두개의 캐시를 동기화 시켜서, 포인터 변경과 새로운 데이터의 +발견을 올바른 순서로 일어나게 하기 때문입니다. 리눅스 커널의 메모리 배리어 모델은 Alpha 에 기초해서 정의되었습니다만, v4.15 부터는 Alpha 용 READ_ONCE() 코드 내에 smp_mb() 가 추가되어서 메모리 모델로의 diff --git a/Documentation/translations/sp_SP/disclaimer-sp.rst b/Documentation/translations/sp_SP/disclaimer-sp.rst new file mode 100644 index 000000000000..a400034e95f9 --- /dev/null +++ b/Documentation/translations/sp_SP/disclaimer-sp.rst @@ -0,0 +1,6 @@ +:orphan: + +.. warning:: + Si tiene alguna duda sobre la exactitud del contenido de esta + traducción, la única referencia válida es la documentación oficial en + inglés. diff --git a/Documentation/translations/sp_SP/howto.rst b/Documentation/translations/sp_SP/howto.rst new file mode 100644 index 000000000000..f9818d687b54 --- /dev/null +++ b/Documentation/translations/sp_SP/howto.rst @@ -0,0 +1,617 @@ +.. include:: ./disclaimer-sp.rst + +:Original: :ref:`Documentation/process/howto.rst <process_howto>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_process_howto: + +Cómo participar en el desarrollo del kernel de Linux +==================================================== + +Este documento es el principal punto de partida. Contiene instrucciones +sobre cómo convertirse en desarrollador del kernel de Linux y explica cómo +trabajar con el y en su desarrollo. El documento no tratará ningún aspecto +técnico relacionado con la programación del kernel, pero le ayudará +guiándole por el camino correcto. + +Si algo en este documento quedara obsoleto, envíe parches al maintainer de +este archivo, que se encuentra en la parte superior del documento. + +Introducción +------------ +¿De modo que quiere descubrir como convertirse en un/a desarrollador/a del +kernel de Linux? Tal vez su jefe le haya dicho, "Escriba un driver de +Linux para este dispositivo." El objetivo de este documento en enseñarle +todo cuanto necesita para conseguir esto, describiendo el proceso por el +que debe pasar, y con indicaciones de como trabajar con la comunidad. +También trata de explicar las razones por las cuales la comunidad trabaja +de la forma en que lo hace. + +El kernel esta principalmente escrito en C, con algunas partes que son +dependientes de la arquitectura en ensamblador. Un buen conocimiento de C +es necesario para desarrollar en el kernel. Lenguaje ensamblador (en +cualquier arquitectura) no es necesario excepto que planee realizar +desarrollo de bajo nivel para dicha arquitectura. Aunque no es un perfecto +sustituto para una educación sólida en C y/o años de experiencia, los +siguientes libros sirven, como mínimo, como referencia: + +- "The C Programming Language" de Kernighan e Ritchie [Prentice Hall] +- "Practical C Programming" de Steve Oualline [O'Reilly] +- "C: A Reference Manual" de Harbison and Steele [Prentice Hall] + +El kernel está escrito usando GNU C y la cadena de herramientas GNU. Si +bien se adhiere al estándar ISO C89, utiliza una serie de extensiones que +no aparecen en dicho estándar. El kernel usa un C independiente de entorno, +sin depender de la biblioteca C estándar, por lo que algunas partes del +estándar C no son compatibles. Divisiones de long long arbitrarios o +de coma flotante no son permitidas. En ocasiones, puede ser difícil de +entender las suposiciones que el kernel hace respecto a la cadena de +herramientas y las extensiones que usa, y desafortunadamente no hay +referencia definitiva para estas. Consulte las páginas de información de +gcc (`info gcc`) para obtener información al respecto. + +Recuerde que está tratando de aprender a trabajar con una comunidad de +desarrollo existente. Es un grupo diverso de personas, con altos estándares +de código, estilo y procedimiento. Estas normas han sido creadas a lo +largo del tiempo en función de lo que se ha encontrado que funciona mejor +para un equipo tan grande y geográficamente disperso. Trate de aprender +tanto como le sea posible acerca de estos estándares antes de tiempo, ya +que están bien documentados; no espere que la gente se adapte a usted o a +la forma de hacer las cosas en su empresa. + +Cuestiones legales +------------------ +El código fuente del kernel de Linux se publica bajo licencia GPL. Por +favor, revise el archivo COPYING, presente en la carpeta principal del +código fuente, para detalles de la licencia. Si tiene alguna otra pregunta +sobre licencias, contacte a un abogado, no pregunte en listas de discusión +del kernel de Linux. La gente en estas listas no son abogadas, y no debe +confiar en sus opiniones en materia legal. + +Para preguntas y respuestas más frecuentes sobre la licencia GPL, consulte: + + https://www.gnu.org/licenses/gpl-faq.html + +Documentación +-------------- +El código fuente del kernel de Linux tiene una gran variedad de documentos +que son increíblemente valiosos para aprender a interactuar con la +comunidad del kernel. Cuando se agregan nuevas funciones al kernel, se +recomienda que se incluyan nuevos archivos de documentación que expliquen +cómo usar la función. Cuando un cambio en el kernel hace que la interfaz +que el kernel expone espacio de usuario cambie, se recomienda que envíe la +información o un parche en las páginas del manual que expliquen el cambio +a mtk.manpages@gmail.com, y CC la lista linux-api@vger.kernel.org. + +Esta es la lista de archivos que están en el código fuente del kernel y son +de obligada lectura: + + :ref:`Documentation/admin-guide/README.rst <readme>` + Este archivo ofrece una breve descripción del kernel de Linux y + describe lo que es necesario hacer para configurar y compilar el + kernel. Quienes sean nuevos en el kernel deben comenzar aquí. + + :ref:`Documentation/process/changes.rst <changes>` + Este archivo proporciona una lista de los niveles mínimos de varios + paquetes que son necesarios para construir y ejecutar el kernel + exitosamente. + + :ref:`Documentation/process/coding-style.rst <codingstyle>` + Esto describe el estilo de código del kernel de Linux y algunas de los + razones detrás de esto. Se espera que todo el código nuevo siga las + directrices de este documento. La mayoría de los maintainers solo + aceptarán parches si se siguen estas reglas, y muchas personas solo + revisan el código si tiene el estilo adecuado. + + :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` + Este archivo describe en gran detalle cómo crear con éxito y enviar un + parche, que incluye (pero no se limita a): + + - Contenidos del correo electrónico (email) + - Formato del email + - A quien se debe enviar + + Seguir estas reglas no garantiza el éxito (ya que todos los parches son + sujetos a escrutinio de contenido y estilo), pero en caso de no seguir + dichas reglas, el fracaso es prácticamente garantizado. + Otras excelentes descripciones de cómo crear parches correctamente son: + + "The Perfect Patch" + https://www.ozlabs.org/~akpm/stuff/tpp.txt + + "Linux kernel patch submission format" + https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html + + :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>` + Este archivo describe la lógica detrás de la decisión consciente de + no tener una API estable dentro del kernel, incluidas cosas como: + + - Capas intermedias del subsistema (por compatibilidad?) + - Portabilidad de drivers entre sistemas operativos + - Mitigar el cambio rápido dentro del árbol de fuentes del kernel (o + prevenir cambios rápidos) + + Este documento es crucial para comprender la filosofía del desarrollo + de Linux y es muy importante para las personas que se mudan a Linux + tras desarrollar otros sistemas operativos. + + :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` + Si cree que ha encontrado un problema de seguridad en el kernel de + Linux, siga los pasos de este documento para ayudar a notificar a los + desarrolladores del kernel y ayudar a resolver el problema. + + :ref:`Documentation/process/management-style.rst <managementstyle>` + Este documento describe cómo operan los maintainers del kernel de Linux + y los valores compartidos detrás de sus metodologías. Esta es una + lectura importante para cualquier persona nueva en el desarrollo del + kernel (o cualquier persona que simplemente sienta curiosidad por + el campo IT), ya que clarifica muchos conceptos erróneos y confusiones + comunes sobre el comportamiento único de los maintainers del kernel. + + :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` + Este archivo describe las reglas sobre cómo se suceden las versiones + del kernel estable, y qué hacer si desea obtener un cambio en una de + estas publicaciones. + + :ref:`Documentation/process/kernel-docs.rst <kernel_docs>` + Una lista de documentación externa relativa al desarrollo del kernel. + Por favor consulte esta lista si no encuentra lo que están buscando + dentro de la documentación del kernel. + + :ref:`Documentation/process/applying-patches.rst <applying_patches>` + Una buena introducción que describe exactamente qué es un parche y cómo + aplicarlo a las diferentes ramas de desarrollo del kernel. + +El kernel también tiene una gran cantidad de documentos que pueden ser +generados automáticamente desde el propio código fuente o desde +ReStructuredText markups (ReST), como este. Esto incluye un descripción +completa de la API en el kernel y reglas sobre cómo manejar cerrojos +(locking) correctamente. + +Todos estos documentos se pueden generar como PDF o HTML ejecutando:: + + make pdfdocs + make htmldocs + +respectivamente desde el directorio fuente principal del kernel. + +Los documentos que utilizan el markup ReST se generarán en +Documentation/output. También se pueden generar en formatos LaTeX y ePub +con:: + + make latexdocs + make epubdocs + +Convertirse en un/a desarrollador/a de kernel +--------------------------------------------- + +Si no sabe nada sobre el desarrollo del kernel de Linux, debería consultar +el proyecto Linux KernelNewbies: + + https://kernelnewbies.org + +Consiste en una útil lista de correo donde puede preguntar casi cualquier +tipo de pregunta básica de desarrollo del kernel (asegúrese de buscar en +los archivos primero, antes de preguntar algo que ya ha sido respondido en +el pasado.) También tiene un canal IRC que puede usar para hacer preguntas +en tiempo real, y una gran cantidad de documentación útil para ir +aprendiendo sobre el desarrollo del kernel de Linux. + +El sitio web tiene información básica sobre la organización del código, +subsistemas, y proyectos actuales (tanto dentro como fuera del árbol). +También describe alguna información logística básica, como cómo compilar +un kernel y aplicar un parche. + +Si no sabe por dónde quiere empezar, pero quieres buscar alguna tarea que +comenzar a hacer para unirse a la comunidad de desarrollo del kernel, +acuda al proyecto Linux Kernel Janitor: + + https://kernelnewbies.org/KernelJanitors + +Es un gran lugar para comenzar. Describe una lista de problemas +relativamente simples que deben limpiarse y corregirse dentro del código +fuente del kernel de Linux árbol de fuentes. Trabajando con los +desarrolladores a cargo de este proyecto, aprenderá los conceptos básicos +para incluir su parche en el árbol del kernel de Linux, y posiblemente +descubrir en la dirección en que trabajar a continuación, si no tiene ya +una idea. + +Antes de realizar cualquier modificación real al código del kernel de +Linux, es imperativo entender cómo funciona el código en cuestión. Para +este propósito, nada es mejor que leerlo directamente (lo más complicado +está bien comentado), tal vez incluso con la ayuda de herramientas +especializadas. Una de esas herramientas que se recomienda especialmente +es el proyecto Linux Cross-Reference, que es capaz de presentar el código +fuente en un formato de página web indexada y autorreferencial. Una +excelente puesta al día del repositorio del código del kernel se puede +encontrar en: + + https://elixir.bootlin.com/ + +El proceso de desarrollo +------------------------ + +El proceso de desarrollo del kernel de Linux consiste actualmente de +diferentes "branches" (ramas) con muchos distintos subsistemas específicos +a cada una de ellas. Las diferentes ramas son: + + - El código principal de Linus (mainline tree) + - Varios árboles estables con múltiples major numbers + - Subsistemas específicos + - linux-next, para integración y testing + +Mainline tree (Árbol principal) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +El mainline tree es mantenido por Linus Torvalds, y puede encontrarse en +https://kernel.org o en su repo. El proceso de desarrollo es el siguiente: + + - Tan pronto como se lanza un nuevo kernel, se abre una ventana de dos + semanas, durante este período de tiempo, los maintainers pueden enviar + grandes modificaciones a Linus, por lo general los parches que ya se + han incluido en el linux-next durante unas semanas. La forma preferida + de enviar grandes cambios es usando git (la herramienta de + administración de código fuente del kernel, más información al respecto + en https://git-scm.com/), pero los parches simples también son validos. + - Después de dos semanas, se lanza un kernel -rc1 y la atención se centra + en hacer el kernel nuevo lo más estable ("solido") posible. La mayoría + de los parches en este punto deben arreglar una regresión. Los errores + que siempre han existido no son regresiones, por lo tanto, solo envíe + este tipo de correcciones si son importantes. Tenga en cuenta que se + podría aceptar un controlador (o sistema de archivos) completamente + nuevo después de -rc1 porque no hay riesgo de causar regresiones con + tal cambio, siempre y cuando el cambio sea autónomo y no afecte áreas + fuera del código que se está agregando. git se puede usar para enviar + parches a Linus después de que se lance -rc1, pero los parches también + deben ser enviado a una lista de correo pública para su revisión. + - Se lanza un nuevo -rc cada vez que Linus considera que el árbol git + actual esta en un estado razonablemente sano y adecuado para la prueba. + La meta es lanzar un nuevo kernel -rc cada semana. + - El proceso continúa hasta que el kernel se considera "listo", y esto + puede durar alrededor de 6 semanas. + +Vale la pena mencionar lo que Andrew Morton escribió en las listas de +correo del kernel de Linux, sobre lanzamientos del kernel (traducido): + + *"Nadie sabe cuándo se publicara un nuevo kernel, pues esto sucede + según el estado de los bugs, no de una cronología preconcebida."* + +Varios árboles estables con múltiples major numbers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Los kernels con versiones de 3 partes son kernels estables. Estos contienen +correcciones relativamente pequeñas y críticas para problemas de seguridad +o importantes regresiones descubiertas para una publicación de código. +Cada lanzamiento en una gran serie estable incrementa la tercera parte de +la versión número, manteniendo las dos primeras partes iguales. + +Esta es la rama recomendada para los usuarios que quieren la versión +estable más reciente del kernel, y no están interesados en ayudar a probar +versiones en desarrollo/experimentales. + +Los árboles estables son mantenidos por el equipo "estable" +<stable@vger.kernel.org>, y se liberan (publican) según lo dicten las +necesidades. El período de liberación normal es de aproximadamente dos +semanas, pero puede ser más largo si no hay problemas apremiantes. Un +problema relacionado con la seguridad, en cambio, puede causar un +lanzamiento casi instantáneamente. + +El archivo :ref:`Documentación/proceso/stable-kernel-rules.rst <stable_kernel_rules>` +en el árbol del kernel documenta qué tipos de cambios son aceptables para +el árbol estable y cómo funciona el proceso de lanzamiento. + +Subsistemas específicos +~~~~~~~~~~~~~~~~~~~~~~~~ +Los maintainers de los diversos subsistemas del kernel --- y también muchos +desarrolladores de subsistemas del kernel --- exponen su estado actual de +desarrollo en repositorios fuente. De esta manera, otros pueden ver lo que +está sucediendo en las diferentes áreas del kernel. En áreas donde el +desarrollo es rápido, se le puede pedir a un desarrollador que base sus +envíos en tal árbol del subsistema del kernel, para evitar conflictos entre +este y otros trabajos ya en curso. + +La mayoría de estos repositorios son árboles git, pero también hay otros +SCM en uso, o colas de parches que se publican como series quilt. Las +direcciones de estos repositorios de subsistemas se enumeran en el archivo +MAINTAINERS. Muchos de estos se pueden ver en https://git.kernel.org/. + +Antes de que un parche propuesto se incluya con dicho árbol de subsistemas, +es sujeto a revisión, que ocurre principalmente en las listas de correo +(ver la sección respectiva a continuación). Para varios subsistemas del +kernel, esta revisión se rastrea con la herramienta patchwork. Patchwork +ofrece una interfaz web que muestra publicaciones de parches, cualquier +comentario sobre un parche o revisiones a él, y los maintainers pueden +marcar los parches como en revisión, aceptado, o rechazado. La mayoría de +estos sitios de trabajo de parches se enumeran en + +https://patchwork.kernel.org/. + +linux-next, para integración y testing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Antes de que las actualizaciones de los árboles de subsistemas se combinen +con el árbol principal, necesitan probar su integración. Para ello, existe +un repositorio especial de pruebas en el que se encuentran casi todos los +árboles de subsistema, actualizado casi a diario: + + https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git + +De esta manera, linux-next ofrece una perspectiva resumida de lo que se +espera que entre en el kernel principal en el próximo período de "merge" +(fusión de código). Los testers aventureros son bienvenidos a probar +linux-next en ejecución. + +Reportar bugs +------------- + +El archivo 'Documentación/admin-guide/reporting-issues.rst' en el +directorio principal del kernel describe cómo informar un posible bug del +kernel y detalles sobre qué tipo de información necesitan los +desarrolladores del kernel para ayudar a rastrear la fuente del problema. + +Gestión de informes de bugs +------------------------------ + +Una de las mejores formas de poner en práctica sus habilidades de hacking +es arreglando errores reportados por otras personas. No solo ayudará a +hacer el kernel más estable, también aprenderá a solucionar problemas del +mundo real y mejora sus habilidades, y otros desarrolladores se darán +cuenta de tu presencia. La corrección de errores es una de las mejores +formas de ganar méritos entre desarrolladores, porque no a muchas personas +les gusta perder el tiempo arreglando los errores de otras personas. + +Para trabajar en informes de errores ya reportados, busque un subsistema +que le interese. Verifique el archivo MAINTAINERS donde se informan los +errores de ese subsistema; con frecuencia será una lista de correo, rara +vez un rastreador de errores (bugtracker). Busque en los archivos de dicho +lugar para informes recientes y ayude donde lo crea conveniente. También es +posible que desee revisar https://bugzilla.kernel.org para informes de +errores; solo un puñado de subsistemas del kernel lo emplean activamente +para informar o rastrear; sin embargo, todos los errores para todo el kernel +se archivan allí. + +Listas de correo +----------------- + +Como se explica en algunos de los documentos anteriores, la mayoría de +desarrolladores del kernel participan en la lista de correo del kernel de +Linux. Detalles sobre cómo para suscribirse y darse de baja de la lista se +pueden encontrar en: + + http://vger.kernel.org/vger-lists.html#linux-kernel + +Existen archivos de la lista de correo en la web en muchos lugares +distintos. Utilice un motor de búsqueda para encontrar estos archivos. Por +ejemplo: + + http://dir.gmane.org/gmane.linux.kernel + +Es muy recomendable que busque en los archivos sobre el tema que desea +tratar, antes de publicarlo en la lista. Un montón de cosas ya discutidas +en detalle solo se registran en los archivos de la lista de correo. + +La mayoría de los subsistemas individuales del kernel también tienen sus +propias lista de correo donde hacen sus esfuerzos de desarrollo. Revise el +archivo MAINTAINERS para obtener referencias de lo que estas listas para +los diferentes grupos. + +Muchas de las listas están alojadas en kernel.org. La información sobre +estas puede ser encontrada en: + + http://vger.kernel.org/vger-lists.html + +Recuerde mantener buenos hábitos de comportamiento al usar las listas. +Aunque un poco cursi, la siguiente URL tiene algunas pautas simples para +interactuar con la lista (o cualquier lista): + + http://www.albion.com/netiquette/ + +Si varias personas responden a su correo, el CC (lista de destinatarios) +puede hacerse bastante grande. No elimine a nadie de la lista CC: sin una +buena razón, o no responda solo a la dirección de la lista. Acostúmbrese +a recibir correos dos veces, una del remitente y otra de la lista, y no +intente ajustar esto agregando encabezados de correo astutos, a la gente no +le gustará. + +Recuerde mantener intacto el contexto y la atribución de sus respuestas, +mantenga las líneas "El hacker John Kernel escribió ...:" en la parte +superior de su respuesta, y agregue sus declaraciones entre las secciones +individuales citadas en lugar de escribiendo en la parte superior del +correo electrónico. + +Si incluye parches en su correo, asegúrese de que sean texto legible sin +formato como se indica en :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`. +Los desarrolladores del kernel no quieren lidiar con archivos adjuntos o +parches comprimidos; y pueden querer comentar líneas individuales de su +parche, que funciona sólo de esa manera. Asegúrese de emplear un programa +de correo que no altere los espacios ni los tabuladores. Una buena primera +prueba es enviarse el correo a usted mismo, e intentar aplicar su +propio parche. Si eso no funciona, arregle su programa de correo o +reemplace hasta que funcione. + +Sobretodo, recuerde de ser respetuoso con otros subscriptores. + +Colaborando con la comunidad +---------------------------- + +El objetivo de la comunidad del kernel es proporcionar el mejor kernel +posible. Cuando envíe un parche para su aceptación, se revisará en sus +méritos técnicos solamente. Entonces, ¿qué deberías ser? + + - críticas + - comentarios + - peticiones de cambios + - peticiones de justificaciones + - silencio + +Recuerde, esto es parte de introducir su parche en el kernel. Tiene que ser +capaz de recibir críticas y comentarios sobre sus parches, evaluar +a nivel técnico y re-elaborar sus parches o proporcionar razonamiento claro +y conciso de por qué no se deben hacer tales cambios. Si no hay respuestas +a su publicación, espere unos días e intente de nuevo, a veces las cosas se +pierden dado el gran volumen. + +¿Qué no debería hacer? + + - esperar que su parche se acepte sin preguntas + - actuar de forma defensiva + - ignorar comentarios + - enviar el parche de nuevo, sin haber aplicados los cambios pertinentes + +En una comunidad que busca la mejor solución técnica posible, siempre habrá +diferentes opiniones sobre lo beneficioso que es un parche. Tiene que ser +cooperativo y estar dispuesto a adaptar su idea para que encaje dentro +del kernel, o al menos esté dispuesto a demostrar que su idea vale la pena. +Recuerde, estar equivocado es aceptable siempre y cuando estés dispuesto a +trabajar hacia una solución que sea correcta. + +Es normal que las respuestas a su primer parche sean simplemente una lista +de una docena de cosas que debe corregir. Esto **no** implica que su +parche no será aceptado, y **no** es personal. Simplemente corrija todos +los problemas planteados en su parche, y envié otra vez. + +Diferencias entre la comunidad kernel y las estructuras corporativas +-------------------------------------------------------------------- + +La comunidad del kernel funciona de manera diferente a la mayoría de los +entornos de desarrollo tradicionales en empresas. Aquí hay una lista de +cosas que puede intentar hacer para evitar problemas: + + Cosas buenas que decir respecto a los cambios propuestos: + + - "Esto arregla múltiples problemas." + - "Esto elimina 2000 lineas de código." + - "Aquí hay un parche que explica lo que intento describir." + - "Lo he testeado en 5 arquitecturas distintas..." + - "Aquí hay una serie de parches menores que..." + - "Esto mejora el rendimiento en maquinas típicas..." + + Cosas negativas que debe evitar decir: + + - "Lo hicimos así en AIX/ptx/Solaris, de modo que debe ser bueno..." + - "Llevo haciendo esto 20 años, de modo que..." + - "Esto lo necesita mi empresa para ganar dinero" + - "Esto es para la linea de nuestros productos Enterprise" + - "Aquí esta el documento de 1000 paginas describiendo mi idea" + - "Llevo 6 meses trabajando en esto..." + - "Aquí esta un parche de 5000 lineas que..." + - "He rescrito todo el desastre actual, y aquí esta..." + - "Tengo un deadline, y este parche debe aplicarse ahora." + +Otra forma en que la comunidad del kernel es diferente a la mayoría de los +entornos de trabajo tradicionales en ingeniería de software, es la +naturaleza sin rostro de interacción. Una de las ventajas de utilizar el +correo electrónico y el IRC como formas principales de comunicación es la +no discriminación por motivos de género o raza. El entorno de trabajo del +kernel de Linux acepta a mujeres y minorías porque todo lo que eres es una +dirección de correo electrónico. El aspecto internacional también ayuda a +nivelar el campo de juego porque no puede adivinar el género basado en +el nombre de una persona. Un hombre puede llamarse Andrea y una mujer puede +llamarse Pat. La mayoría de las mujeres que han trabajado en el kernel de +Linux y han expresado una opinión han tenido experiencias positivas. + +La barrera del idioma puede causar problemas a algunas personas que no se +sientes cómodas con el inglés. Un buen dominio del idioma puede ser +necesario para transmitir ideas correctamente en las listas de correo, por +lo que le recomendamos que revise sus correos electrónicos para asegurarse +de que tengan sentido en inglés antes de enviarlos. + +Divida sus cambios +--------------------- + +La comunidad del kernel de Linux no acepta con gusto grandes fragmentos de +código, sobretodo a la vez. Los cambios deben introducirse correctamente, +discutidos y divididos en pequeñas porciones individuales. Esto es casi +exactamente lo contrario de lo que las empresas están acostumbradas a hacer. +Su propuesta también debe introducirse muy temprano en el proceso de +desarrollo, de modo que pueda recibir comentarios sobre lo que está +haciendo. También deje que la comunidad sienta que está trabajando con +ellos, y no simplemente usándolos como un vertedero para su función. Sin +embargo, no envíe 50 correos electrónicos a una vez a una lista de correo, +su serie de parches debe casi siempre ser más pequeña que eso. + +Las razones para dividir las cosas son las siguientes: + +1) Los cambios pequeños aumentan la probabilidad de que sus parches sean + aplicados, ya que no requieren mucho tiempo o esfuerzo para verificar su + exactitud. Un parche de 5 líneas puede ser aplicado por un maintainer + con apenas una segunda mirada. Sin embargo, un parche de 500 líneas + puede tardar horas en ser revisado en términos de corrección (el tiempo + que toma es exponencialmente proporcional al tamaño del parche, o algo + así). + + Los parches pequeños también facilitan la depuración cuando algo falla. + Es mucho más fácil retirar los parches uno por uno que diseccionar un + parche muy grande después de haber sido aplicado (y roto alguna cosa). + +2) Es importante no solo enviar pequeños parches, sino también reescribir + y simplificar (o simplemente reordenar) los parches antes de enviarlos. + +Esta es una analogía del desarrollador del kernel Al Viro (traducida): + + *"Piense en un maestro que califica la tarea de un estudiante de + matemáticas. El maestro no quiere ver los intentos y errores del + estudiante antes de que se les ocurriera la solución. Quiere ver la + respuesta más limpia y elegante. Un buen estudiante lo sabe, y nunca + presentaría su trabajo intermedio antes de tener la solución final.* + + *Lo mismo ocurre con el desarrollo del kernel. Los maintainers y + revisores no quieren ver el proceso de pensamiento detrás de la solución + al problema que se está resolviendo. Quieren ver un solución simple y + elegante."* + +Puede resultar un reto mantener el equilibrio entre presentar una solución +elegante y trabajar junto a la comunidad, discutiendo su trabajo inacabado. +Por lo tanto, es bueno comenzar temprano en el proceso para obtener +"feedback" y mejorar su trabajo, pero también mantenga sus cambios en +pequeños trozos que pueden ser aceptados, incluso cuando toda su labor no +está listo para inclusión en un momento dado. + +También tenga en cuenta que no es aceptable enviar parches para su +inclusión que están sin terminar y serán "arreglados más tarde". + +Justifique sus cambios +---------------------- + +Además de dividir sus parches, es muy importante que deje a la comunidad de +Linux sabe por qué deberían agregar este cambio. Nuevas características +debe justificarse como necesarias y útiles. + +Documente sus cambios +--------------------- + +Cuando envíe sus parches, preste especial atención a lo que dice en el +texto de su correo electrónico. Esta información se convertirá en el +ChangeLog del parche, y se conservará para que todos la vean, todo el +tiempo. Debe describir el parche por completo y contener: + + - por qué los cambios son necesarios + - el diseño general de su propuesta + - detalles de implementación + - resultados de sus experimentos + +Para obtener más detalles sobre cómo debería quedar todo esto, consulte la +sección ChangeLog del documento: + + "The Perfect Patch" + https://www.ozlabs.org/~akpm/stuff/tpp.txt + +Todas estas cuestiones son a veces son muy difíciles de conseguir. Puede +llevar años perfeccionar estas prácticas (si es que lo hace). Es un proceso +continuo de mejora que requiere mucha paciencia y determinación. Pero no se +rinda, es posible. Muchos lo han hecho antes, y cada uno tuvo que comenzar +exactamente donde está usted ahora. + +---------- + +Gracias a Paolo Ciarrocchi que permitió que la sección "Development Process" +se basara en el texto que había escrito (https://lwn.net/Articles/94386/), +y a Randy Dunlap y Gerrit Huizenga por algunas de la lista de cosas que +debes y no debes decir. También gracias a Pat Mochel, Hanna Linder, Randy +Dunlap, Kay Sievers, Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, +Andrew Morton, Andi Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, +Keri Harris, Frans Pop, David A. Wheeler, Junio Hamano, Michael Kerrisk y +Alex Shepard por su revisión, comentarios y contribuciones. Sin su ayuda, +este documento no hubiera sido posible. + +Maintainer: Greg Kroah-Hartman <greg@kroah.com> diff --git a/Documentation/translations/sp_SP/index.rst b/Documentation/translations/sp_SP/index.rst new file mode 100644 index 000000000000..5c2a2131524b --- /dev/null +++ b/Documentation/translations/sp_SP/index.rst @@ -0,0 +1,81 @@ + +===================== +Traducción al español +===================== + +.. raw:: latex + + \kerneldocCJKoff + +:maintainer: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_disclaimer: + +Advertencia +=========== + +El objetivo de esta traducción es facilitar la lectura y comprensión para +aquellos que no entiendan inglés o duden de sus interpretaciones, o +simplemente para aquellos que prefieran leer en el idioma español. Sin +embargo, tenga en cuenta que la *única* documentación oficial es la que +está en inglés: :ref:`linux_doc` + +La propagación simultánea de la traducción de una modificación en +:ref:`linux_doc` es altamente improbable. Los maintainers y colaboradores +de la traducción intentan mantener sus traducciones al día, en tanto les +es posible. Por tanto, no existe ninguna garantía de que una traducción +esté actualizada con las últimas modificaciones. Si lo que lee en una +traducción no se corresponde con lo que ve en el código fuente, informe +al maintainer de la traducción y, si puede, consulte la documentación en +inglés. + +Una traducción no es una * bifurcación * de la documentación oficial, por +lo que los usuarios no encontrarán aquí ninguna información que no sea la +versión oficial. Cualquier adición, supresión o modificación de los +contenidos deberá ser realizada anteriormente en los documentos en inglés. +Posteriormente, y cuando sea posible, dicho cambio debería aplicarse +también a las traducciones. Los maintainers de las traducciones aceptan +contribuciones que son puramente de interés relativo a la traducción (por +ejemplo, nuevas traducciones, actualizaciones, correcciones, etc.). + +Las traducciones tratan de ser lo más precisas posible pero no es posible +convertir directamente un idioma a otro. Cada idioma tiene su propia +gramática, y una cultura tras ella, por lo tanto, la traducción de una +oración al inglés se podría modificar para adaptarla al español. Por esta +razón, cuando lea esta traducción, puede encontrar algunas diferencias en +la forma, pero todavía transmiten el mensaje original. A pesar de la gran +difusión del inglés en el idioma hablado, cuando sea posible, expresiones +en inglés serán reemplazadas por las palabras correspondientes en español. + +Si necesita ayuda para comunicarse con la comunidad de Linux pero no se +siente cómodo escribiendo en inglés, puede pedir ayuda al maintainer para +obtener una traducción. + +Muchos países hablan español, cada uno con su propia cultura, expresiones, +y diferencias gramaticales en ocasiones significativas. Las traducciones de +los maintainers pueden utilizar el español con el que dichos maintainers se +sientan más cómodos. En principio, estas pequeñas diferencias no deberían +suponer una gran barrera para hablantes de distintas versiones del español, +pero en caso de duda se puede consultar a los maintainers. + +La documentación del kernel Linux +================================= + +Este es el nivel superior de la documentación del kernel en idioma español. +La traducción es incompleta, y podría encontrar advertencias que indiquen +la falta de una traducción o de un grupo de traducciones. + +En términos más generales, la documentación, como el kernel mismo, están en +constante desarrollo. Las mejoras en la documentación siempre son +bienvenidas; de modo que, si desea ayudar, únase a la lista de correo +linux-doc en vger.kernel.org. + +Traducciones al español +======================= + +.. toctree:: + :maxdepth: 1 + + howto + process/index + wrappers/memory-barriers diff --git a/Documentation/translations/sp_SP/memory-barriers.txt b/Documentation/translations/sp_SP/memory-barriers.txt new file mode 100644 index 000000000000..f62bd797216d --- /dev/null +++ b/Documentation/translations/sp_SP/memory-barriers.txt @@ -0,0 +1,3134 @@ +NOTE: +This is a version of Documentation/memory-barriers.txt translated into +Spanish by Carlos Bilbao <carlos.bilbao@amd.com>. If you find any +difference between this document and the original file or a problem with +the translation, please contact the maintainer of this file. Please also +note that the purpose of this file is to be easier to read for non English +(read: Spanish) speakers and is not intended as a fork. So if you have any +comments or updates for this file please update the original English file +first. The English version is definitive, and readers should look there if +they have any doubt. + + ====================================== + BARRERAS DE MEMORIA EN EL KERNEL LINUX + ====================================== + +Documento original: David Howells <dhowells@redhat.com> + Paul E. McKenney <paulmck@linux.ibm.com> + Will Deacon <will.deacon@arm.com> + Peter Zijlstra <peterz@infradead.org> + +Traducido por: Carlos Bilbao <carlos.bilbao@amd.com> +Nota: Si tiene alguna duda sobre la exactitud del contenido de esta +traducción, la única referencia válida es la documentación oficial en +inglés. + +=========== +ADVERTENCIA +=========== + +Este documento no es una especificación; es intencionalmente (por motivos +de brevedad) y sin querer (por ser humanos) incompleta. Este documento +pretende ser una guía para usar las diversas barreras de memoria +proporcionadas por Linux, pero ante cualquier duda (y hay muchas) por favor +pregunte. Algunas dudas pueden ser resueltas refiriéndose al modelo de +consistencia de memoria formal y documentación en tools/memory-model/. Sin +embargo, incluso este modelo debe ser visto como la opinión colectiva de +sus maintainers en lugar de que como un oráculo infalible. + +De nuevo, este documento no es una especificación de lo que Linux espera +del hardware. + +El propósito de este documento es doble: + + (1) especificar la funcionalidad mínima en la que se puede confiar para + cualquier barrera en concreto, y + + (2) proporcionar una guía sobre cómo utilizar las barreras disponibles. + +Tenga en cuenta que una arquitectura puede proporcionar más que el +requisito mínimo para cualquier barrera en particular, pero si la +arquitectura proporciona menos de eso, dicha arquitectura es incorrecta. + +Tenga en cuenta también que es posible que una barrera no valga (sea no-op) +para alguna arquitectura porque por la forma en que funcione dicha +arquitectura, la barrera explícita resulte innecesaria en ese caso. + +========== +CONTENIDOS +========== + + (*) Modelo abstracto de acceso a memoria. + + - Operaciones del dispositivo. + - Garantías. + + (*) ¿Qué son las barreras de memoria? + + - Variedades de barrera de memoria. + - ¿Qué no se puede asumir sobre las barreras de memoria? + - Barreras de dirección-dependencia (históricas). + - Dependencias de control. + - Emparejamiento de barreras smp. + - Ejemplos de secuencias de barrera de memoria. + - Barreras de memoria de lectura frente a especulación de carga. + - Atomicidad multicopia. + + (*) Barreras explícitas del kernel. + + - Barrera del compilador. + - Barreras de memoria de la CPU. + + (*) Barreras de memoria implícitas del kernel. + + - Funciones de adquisición de cerrojo. + - Funciones de desactivación de interrupciones. + - Funciones de dormir y despertar. + - Funciones varias. + + (*) Efectos de barrera adquiriendo intra-CPU. + + - Adquisición vs accesos a memoria. + + (*) ¿Dónde se necesitan barreras de memoria? + + - Interacción entre procesadores. + - Operaciones atómicas. + - Acceso a dispositivos. + - Interrupciones. + + (*) Efectos de barrera de E/S del kernel. + + (*) Modelo de orden mínimo de ejecución asumido. + + (*) Efectos de la memoria caché de la CPU. + + - Coherencia de caché. + - Coherencia de caché frente a DMA. + - Coherencia de caché frente a MMIO. + + (*) Cosas que hacen las CPU. + + - Y luego está el Alfa. + - Guests de máquinas virtuales. + + (*) Ejemplos de usos. + + - Buffers circulares. + + (*) Referencias. + + +==================================== +MODELO ABSTRACTO DE ACCESO A MEMORIA +==================================== + +Considere el siguiente modelo abstracto del sistema: + + : : + : : + : : + +-------+ : +--------+ : +-------+ + | | : | | : | | + | | : | | : | | + | CPU 1 |<----->| Memoria|<----->| CPU 2 | + | | : | | : | | + | | : | | : | | + +-------+ : +--------+ : +-------+ + ^ : ^ : ^ + | : | : | + | : | : | + | : v : | + | : +--------+ : | + | : | | : | + | : | Disposi| : | + +---------->| tivo |<----------+ + : | | : + : | | : + : +--------+ : + : : + +Cada CPU ejecuta un programa que genera operaciones de acceso a la memoria. +En la CPU abstracta, el orden de las operaciones de memoria es muy +relajado, y una CPU en realidad puede realizar las operaciones de memoria +en el orden que desee, siempre que la causalidad del programa parezca +mantenerse. De manera similar, el compilador también puede organizar las +instrucciones que emite en el orden que quiera, siempre que no afecte al +funcionamiento aparente del programa. + +Entonces, en el diagrama anterior, los efectos de las operaciones de +memoria realizadas por un CPU son percibidos por el resto del sistema a +medida que las operaciones cruzan la interfaz entre la CPU y el resto del +sistema (las líneas discontinuas a puntos). + +Por ejemplo, considere la siguiente secuencia de eventos: + + CPU 1 CPU 2 + =============== =============== + { A == 1; B == 2 } + A = 3; x = B; + B = 4; y = A; + +El conjunto de accesos visto por el sistema de memoria en el medio se puede +organizar en 24 combinaciones diferentes (donde LOAD es cargar y STORE es +guardar): + +STORE A=3, STORE B=4, y=LOAD A->3, x=LOAD B->4 +STORE A=3, STORE B=4, x=LOAD B->4, y=LOAD A->3 +STORE A=3, y=LOAD A->3, STORE B=4, x=LOAD B->4 +STORE A=3, y=LOAD A->3, x=LOAD B->2, STORE B=4 +STORE A=3, x=LOAD B->2, STORE B=4, y=LOAD A->3 +STORE A=3, x=LOAD B->2, y=LOAD A->3, STORE B=4 +STORE B=4, STORE A=3, y=LOAD A->3, x=LOAD B->4 +STORE B=4, ... +... + +y por lo tanto puede resultar en cuatro combinaciones diferentes de +valores: + +x == 2, y == 1 +x == 2, y == 3 +x == 4, y == 1 +x == 4, y == 3 + +Además, los stores asignados por una CPU al sistema de memoria pueden no +ser percibidos por los loads realizados por otra CPU en el mismo orden en +que fueron realizados. + +Como otro ejemplo, considere esta secuencia de eventos: + + CPU 1 CPU 2 + =============== =============== + { A == 1, B == 2, C == 3, P == &A, Q == &C } + B = 4; Q = P; + P = &B; D = *Q; + +Aquí hay una dependencia obvia de la dirección, ya que el valor cargado en +D depende en la dirección recuperada de P por la CPU 2. Al final de la +secuencia, cualquiera de los siguientes resultados son posibles: + + (Q == &A) y (D == 1) + (Q == &B) y (D == 2) + (Q == &B) y (D == 4) + +Tenga en cuenta que la CPU 2 nunca intentará cargar C en D porque la CPU +cargará P en Q antes de emitir la carga de *Q. + +OPERACIONES DEL DISPOSITIVO +--------------------------- + +Algunos dispositivos presentan sus interfaces de control como colecciones +de ubicaciones de memoria, pero el orden en que se accede a los registros +de control es muy importante. Por ejemplo, imagine una tarjeta ethernet con +un conjunto de registros a los que se accede a través de un registro de +puerto de dirección (A) y un registro de datos del puerto (D). Para leer el +registro interno 5, el siguiente código podría entonces ser usado: + + *A = 5; + x = *D; + +pero esto podría aparecer como cualquiera de las siguientes dos secuencias: + + STORE *A = 5, x = LOAD *D + x = LOAD *D, STORE *A = 5 + +el segundo de las cuales casi con certeza resultará en mal funcionamiento, +ya que se estableció la dirección _después_ de intentar leer el registro. + + +GARANTÍAS +--------- + +Hay algunas garantías mínimas que se pueden esperar de una CPU: + + (*) En cualquier CPU dada, los accesos a la memoria dependiente se + emitirán en orden, con respeto a sí mismo. Esto significa que para: + + Q = READ_ONCE(P); D = READ_ONCE(*Q); + + donde READ_ONCE() es LEER_UNA_VEZ(), la CPU emitirá las siguientes + operaciones de memoria: + + Q = LOAD P, D = LOAD *Q + + y siempre en ese orden. Sin embargo, en DEC Alpha, READ_ONCE() también + emite una instrucción de barrera de memoria, de modo que una CPU DEC + Alpha, sin embargo emite las siguientes operaciones de memoria: + + Q = LOAD P, MEMORY_BARRIER, D = LOAD *Q, MEMORY_BARRIER + + Ya sea en DEC Alpha o no, READ_ONCE() también evita que el compilador + haga cosas inapropiadas. + + (*) Los loads y stores superpuestos dentro de una CPU en particular + parecerán ser ordenados dentro de esa CPU. Esto significa que para: + + a = READ_ONCE(*X); WRITE_ONCE(*X, b); + + donde WRITE_ONCE() es ESCRIBIR_UNA_VEZ(), la CPU solo emitirá la + siguiente secuencia de operaciones de memoria: + + a = LOAD *X, STORE *X = b + + Y para: + + WRITE_ONCE(*X, c); d = READ_ONCE(*X); + + la CPU solo emitirá: + + STORE *X = c, d = LOAD *X + + (Los loads y stores se superponen si están destinados a piezas + superpuestas de memoria). + +Y hay una serie de cosas que _deben_ o _no_ deben asumirse: + + (*) _No_debe_ asumirse que el compilador hará lo que usted quiera + con referencias de memoria que no están protegidas por READ_ONCE() y + WRITE ONCE(). Sin ellos, el compilador tiene derecho a hacer todo tipo + de transformaciones "creativas", que se tratan en la sección BARRERA + DEL COMPILADOR. + + (*) _No_debe_ suponerse que se emitirán loads y stores independientes + en el orden dado. Esto significa que para: + + X = *A; Y = *B; *D = Z; + + podemos obtener cualquiera de las siguientes secuencias: + + X = LOAD *A, Y = LOAD *B, STORE *D = Z + X = LOAD *A, STORE *D = Z, Y = LOAD *B + Y = LOAD *B, X = LOAD *A, STORE *D = Z + Y = LOAD *B, STORE *D = Z, X = LOAD *A + STORE *D = Z, X = LOAD *A, Y = LOAD *B + STORE *D = Z, Y = LOAD *B, X = LOAD *A + + (*) Se _debe_ suponer que los accesos de memoria superpuestos pueden + fusionarse o ser descartados. Esto significa que para: + + X = *A; Y = *(A + 4); + + podemos obtener cualquiera de las siguientes secuencias: + +X = LOAD *A; Y = LOAD *(A + 4); +Y = LOAD *(A + 4); X = LOAD *A; +{X, Y} = LOAD {*A, *(A + 4) }; + + Y para: + +*A = X; *(A + 4) = Y; + + podemos obtener cualquiera de: + +STORE *A = X; STORE *(A + 4) = Y; +STORE *(A + 4) = Y; STORE *A = X; +STORE {*A, *(A + 4) } = {X, Y}; + +Y hay anti-garantías: + +(*) Estas garantías no se aplican a los campos de bits, porque los + compiladores a menudo generan código para modificarlos usando + secuencias de lectura-modificación-escritura no atómica. No intente + utilizar campos de bits para sincronizar algoritmos paralelos. + +(*) Incluso en los casos en que los campos de bits están protegidos por + cerrojos (o "cerrojos", o "locks"), todos los componentes en un campo + de bits dado deben estar protegidos por un candado. Si dos campos en un + campo de bits dado están protegidos por diferentes locks, las + secuencias de lectura-modificación-escritura no atómicas del lock + pueden causar una actualización a una campo para corromper el valor de + un campo adyacente. + +(*) Estas garantías se aplican solo a escalares correctamente alineados y + dimensionados. De "tamaño adecuado" significa actualmente variables que + son del mismo tamaño que "char", "short", "int" y "long". + "Adecuadamente alineado" significa la alineación natural, por lo tanto, + no hay restricciones para "char", alineación de dos bytes para "short", + alineación de cuatro bytes para "int", y alineación de cuatro u ocho + bytes para "long", en sistemas de 32 y 64 bits, respectivamente. Tenga + en cuenta que estos garantías se introdujeron en el estándar C11, así + que tenga cuidado cuando utilice compiladores anteriores a C11 (por + ejemplo, gcc 4.6). La parte de la norma que contiene esta garantía es + la Sección 3.14, que define "ubicación de memoria" de la siguiente + manera: + + ubicación de memoria + ya sea un objeto de tipo escalar, o una secuencia máxima + de campos de bits adyacentes, todos con ancho distinto de cero + + NOTE 1: Dos hilos de ejecución pueden actualizar y acceder + ubicaciones de memoria separadas sin interferir entre + ellos. + + NOTE 2: Un campo de bits y un miembro adyacente que no es un campo de + bits están en ubicaciones de memoria separadas. Lo mismo sucede con + dos campos de bits, si uno se declara dentro de un declaración de + estructura anidada y el otro no, o si las dos están separados por una + declaración de campo de bits de longitud cero, o si están separados por + un miembro no declarado como campo de bits. No es seguro actualizar + simultáneamente dos campos de bits en la misma estructura si entre + todos los miembros declarados también hay campos de bits, sin importar + cuál resulta ser el tamaño de estos campos de bits intermedios. + + +================================== +¿QUÉ SON LAS BARRERAS DE MEMORIA? +================================== + +Como se puede leer arriba, las operaciones independientes de memoria se +realizan de manera efectiva en orden aleatorio, pero esto puede ser un +problema para la interacción CPU-CPU y para la E/S ("I/O"). Lo que se +requiere es alguna forma de intervenir para instruir al compilador y al +CPU para restringir el orden. + +Las barreras de memoria son este tipo de intervenciones. Imponen una +percepción de orden parcial, sobre las operaciones de memoria a ambos lados +de la barrera. + +Tal cumplimiento es importante porque las CPUs y otros dispositivos en un +sistema pueden usar una variedad de trucos para mejorar el rendimiento, +incluido el reordenamiento, diferimiento y combinación de operaciones de +memoria; cargas especulativas; predicción de "branches" especulativos y +varios tipos de almacenamiento en caché. Las barreras de memoria se +utilizan para anular o suprimir estos trucos, permitiendo que el código +controle sensatamente la interacción de múltiples CPU y/o dispositivos. + + +VARIEDADES DE BARRERA DE MEMORIA +--------------------------------- + +Las barreras de memoria vienen en cuatro variedades básicas: + + (1) Barreras de memoria al escribir o almacenar (Write or store memory + barriers). + + Una barrera de memoria de escritura garantiza que todas las + operaciones de STORE especificadas antes de que la barrera aparezca + suceden antes de todas las operaciones STORE especificadas después + de la barrera, con respecto a los otros componentes del sistema. + + Una barrera de escritura es un orden parcial solo en los stores; No + es requerido que tenga ningún efecto sobre los loads. + + Se puede considerar que una CPU envía una secuencia de operaciones de + store al sistema de memoria a medida que pasa el tiempo. Todos los + stores _antes_ de una barrera de escritura ocurrirán _antes_ de todos + los stores después de la barrera de escritura. + + [!] Tenga en cuenta que las barreras de escritura normalmente deben + combinarse con read o barreras de address-dependency barriers + (dependencia de dirección); consulte la subsección + "Emparejamiento de barreras smp". + + + (2) Barrera de dependencia de dirección (histórico). + + Una barrera de dependencia de dirección es una forma más débil de + barrera de lectura. En el caso de que se realicen dos loads de manera + que la segunda dependa del resultado de la primera (por ejemplo: el + primer load recupera la dirección a la que se dirigirá el segundo + load), una barrera de dependencia de dirección sería necesaria para + asegurarse de que el objetivo de la segunda carga esté actualizado + después de acceder a la dirección obtenida por la primera carga. + + Una barrera de dependencia de direcciones es una ordenación parcial en + laods de direcciones interdependientes; no se requiere que tenga + ningún efecto en los stores, ya sean cargas de memoria o cargas + de memoria superpuestas. + + Como se mencionó en (1), las otras CPU en el sistema pueden verse como + secuencias de stores en el sistema de memoria que la considerada CPU + puede percibir. Una barrera de dependencia de dirección emitida por + la CPU en cuestión garantiza que para cualquier carga que la preceda, + si esa carga toca alguna secuencia de stores de otra CPU, entonces + en el momento en que la barrera se complete, los efectos de todos los + stores antes del cambio del load serán perceptibles por cualquier + carga emitida después la barrera de la dependencia de la dirección. + + Consulte la subsección "Ejemplos de secuencias de barrera de memoria" + para ver los diagramas mostrando las restricciones de orden. + + [!] Tenga en cuenta que la primera carga realmente tiene que tener una + dependencia de _dirección_ y no es una dependencia de control. Si la + dirección para la segunda carga depende de la primera carga, pero la + dependencia es a través de un condicional en lugar de -en realidad- + cargando la dirección en sí, entonces es una dependencia de _control_ + y se requiere una barrera de lectura completa o superior. Consulte la + subsección "Dependencias de control" para más información. + + [!] Tenga en cuenta que las barreras de dependencia de dirección + normalmente deben combinarse con barreras de escritura; consulte la + subsección "Emparejamiento de barreras smp". + + [!] Desde el kernel v5.9, se eliminó la API del kernel para barreras + de memoria de direcciones explícitas. Hoy en día, las APIs para marcar + cargas de variables compartidas, como READ_ONCE() y rcu_dereference(), + proporcionan barreras de dependencia de dirección implícitas. + + (3) Barreras de memoria al leer o cargar (Read or load memory + barriers). + + Una barrera de lectura es una barrera de dependencia de direcciones, + más una garantía de que todas las operaciones de LOAD especificadas + antes de la barrera parecerán ocurrir antes de todas las operaciones + de LOAD especificadas después de la barrera con respecto a los demás + componentes del sistema. + + Una barrera de lectura es un orden parcial solo en cargas; no es + necesario que tenga ningún efecto en los stores. + + Las barreras de memoria de lectura implican barreras de dependencia de + direcciones, y por tanto puede sustituirlas por estas. + + [!] Tenga en mente que las barreras de lectura normalmente deben + combinarse con barreras de escritura; consulte la subsección + "Emparejamiento de barreras smp". + + (4) Barreras de memoria generales + + Una barrera de memoria general proporciona la garantía de que todas + las operaciones LOAD y STORE especificadas antes de que la barrera + aparezca suceden antes de que todas las operaciones LOAD y STORE + especificadas después de la barrera con respecto a los demás + componentes del sistema. + + Una barrera de memoria general es un orden parcial tanto en + operaciones de carga como de almacenamiento. + + Las barreras de memoria generales implican barreras de memoria tanto + de lectura como de escritura, de modo que pueden sustituir a + cualquiera. + +Y un par de variedades implícitas: + + (5) ACQUIRE (de adquisición). + + Esto actúa como una barrera permeable unidireccional. Garantiza que + toda las operaciones de memoria después de la operación ACQUIRE + parezcan suceder después de la ACQUIRE con respecto a los demás + componentes del sistema. Las operaciones ACQUIRE incluyen operaciones + LOCK y smp_load_acquire(), y operaciones smp_cond_load_acquire(). + + Las operaciones de memoria que ocurren antes de una operación ACQUIRE + pueden parecer suceder después de que se complete. + + Una operación ACQUIRE casi siempre debe estar emparejada con una + operación RELEASE (de liberación). + + + (6) Operaciones RELEASE (de liberación). + + Esto también actúa como una barrera permeable unidireccional. + Garantiza que todas las operaciones de memoria antes de la operación + RELEASE parecerán ocurrir antes de la operación RELEASE con respecto a + los demás componentes del sistema. Las operaciones de RELEASE incluyen + operaciones de UNLOCK y operaciones smp_store_release(). + + Las operaciones de memoria que ocurren después de una operación + RELEASE pueden parecer suceder antes de que se complete. + + El uso de las operaciones ACQUIRE y RELEASE generalmente excluye la + necesidad de otros tipos de barrera de memoria. Además, un par + RELEASE+ACQUIRE NO garantiza actuar como una barrera de memoria + completa. Sin embargo, después de un ACQUIRE de una variable dada, + todos los accesos a la memoria que preceden a cualquier anterior + RELEASE en esa misma variable están garantizados como visibles. En + otras palabras, dentro de la sección crítica de una variable dada, + todos los accesos de todas las secciones críticas anteriores para esa + variable habrán terminado de forma garantizada. + + Esto significa que ACQUIRE actúa como una operación mínima de + "adquisición" y RELEASE actúa como una operación mínima de + "liberación". + +Un subconjunto de las operaciones atómicas descritas en atomic_t.txt +contiene variantes de ACQUIRE y RELEASE, además de definiciones +completamente ordenadas o relajadas (sin barrera semántica). Para +composiciones atómicas que realizan tanto un load como store, la semántica +ACQUIRE se aplica solo a la carga y la semántica RELEASE se aplica sólo a +la parte de la operación del store. + +Las barreras de memoria solo son necesarias cuando existe la posibilidad de +interacción entre dos CPU o entre una CPU y un dispositivo. Si se puede +garantizar que no habrá tal interacción en ninguna pieza de código en +particular, entonces las barreras de memoria son innecesarias en ese +fragmento de código. + +Tenga en cuenta que estas son las garantías _mínimas_. Diferentes +arquitecturas pueden proporcionar garantías más sustanciales, pero no se +puede confiar en estas fuera de esa arquitectura en específico. + + +¿QUÉ NO SE PUEDE ASUMIR SOBRE LAS BARRERAS DE LA MEMORIA? +--------------------------------------------------------- + +Hay ciertas cosas que las barreras de memoria del kernel Linux no +garantizan: + + (*) No hay garantía de que ninguno de los accesos a la memoria + especificados antes de una barrera de memoria estará _completo_ al + completarse una instrucción de barrera de memoria; se puede considerar + que la barrera dibuja una línea en la cola de acceso del CPU que no + pueden cruzar los accesos del tipo correspondiente. + + (*) No hay garantía de que la emisión de una barrera de memoria en una CPU + tenga cualquier efecto directo en otra CPU o cualquier otro hardware + en el sistema. El efecto indirecto será el orden en que la segunda CPU + ve los efectos de los primeros accesos que ocurren de la CPU, pero lea + el siguiente argumento: + + (*) No hay garantía de que una CPU vea el orden correcto de los efectos + de los accesos de una segunda CPU, incluso _si_ la segunda CPU usa una + barrera de memoria, a menos que la primera CPU _también_ use una + barrera de memoria coincidente (vea el subapartado "Emparejamiento de + barrera SMP"). + + (*) No hay garantía de que alguna pieza intermedia fuera del hardware[*] + del CPU no reordenará los accesos a la memoria. Los mecanismos de + coherencia de caché del CPU deben propagar los efectos indirectos de + una barrera de memoria entre las CPU, pero es posible que no lo hagan + en orden. + + [*] Para obtener información sobre bus mastering DMA y coherencia, lea: + + Documentation/driver-api/pci/pci.rst + Documentation/core-api/dma-api-howto.rst + Documentation/core-api/dma-api.rst + + +BARRERA DE DEPENDENCIA DE DIRECCIÓN (HISTÓRICO) +----------------------------------------------- + +A partir de la versión 4.15 del kernel Linux, se agregó un smp_mb() a +READ_ONCE() para DEC Alpha, lo que significa que las únicas personas que +necesitan prestar atención a esta sección son aquellas que trabajan en el +código específico de la arquitectura DEC Alpha y aquellas que trabajan en +READ_ONCE() por dentro. Para aquellos que lo necesitan, y para aquellos que +estén interesados desde un punto de vista histórico, aquí está la historia +de las barreras de dependencia de dirección. + +[!] Si bien las dependencias de direcciones se observan tanto en carga a +carga como en relaciones de carga a store, las barreras de dependencia de +dirección no son necesarias para situaciones de carga a store. + +El requisito de las barreras de dependencia de dirección es un poco sutil, +y no siempre es obvio que sean necesarias. Para ilustrar, considere la +siguiente secuencia de eventos: + + CPU 1 CPU 2 + =============== =============== + { A == 1, B == 2, C == 3, P == &A, Q == &C } + B = 4; + <barrera de escritura> + WRITE_ONCE(P, &B); + Q = READ_ONCE_OLD(P); + D = *Q; + +[!] READ_ONCE_OLD() corresponde a READ_ONCE() del kernel anterior a 4.15, +que no implica una barrera de dependencia de direcciones. + +Hay una clara dependencia de dirección aquí, y parecería que al final de +la secuencia, Q debe ser &A o &B, y que: + + (Q == &A) implica (D == 1) + (Q == &B) implica (D == 4) + +¡Pero! La percepción de la CPU 2 de P puede actualizarse _antes_ de su +percepción de B, por lo tanto dando lugar a la siguiente situación: + + (Q == &B) y (D == 2) ???? + +Si bien esto puede parecer una falla en el mantenimiento de la coherencia +o la causalidad, no lo es, y este comportamiento se puede observar en +ciertas CPU reales (como DEC Alfa). + +Para lidiar con esto, READ_ONCE() proporciona una barrera de dependencia +de dirección implícita desde el lanzamiento del kernel v4.15: + + CPU 1 CPU 2 + =============== =============== + { A == 1, B == 2, C == 3, P == &A, Q == &C } + B = 4; + <barrera de escritura> + WRITE_ONCE(P, &B); + Q = READ_ONCE(P); + <barrera de dependencia de dirección implícita> + D = *Q; + +Esto refuerza la ocurrencia de una de las dos implicaciones, y previene la +tercera posibilidad de surgir. + + +[!] Tenga en cuenta que esta situación extremadamente contraria a la +intuición surge más fácilmente en máquinas con cachés divididos, de modo +que, por ejemplo, un banco de caché procesa líneas de caché pares y el otro +banco procesa líneas impares de caché. El puntero P podría almacenarse en +una línea de caché impar y la variable B podría almacenarse en una línea de +caché con número par. Entonces, si el banco de números pares de la memoria +caché de la CPU de lectura está extremadamente ocupado mientras que el +banco impar está inactivo, uno podría ver el nuevo valor del puntero P +(&B), pero el antiguo valor de la variable B (2). + + +No se requiere una barrera de dependencia de dirección para ordenar +escrituras dependientes porque las CPU que admite el kernel Linux no +escriben hasta que están seguros (1) de que la escritura realmente +sucederá, (2) de la ubicación de la escritura, y (3) del valor a escribir. +Pero, por favor, lea atentamente la sección "DEPENDENCIAS DEL CONTROL" y el +archivo Documentation/RCU/rcu_dereference.rst: el compilador puede romperse +y romper dependencias en muchas formas altamente creativas. + + CPU 1 CPU 2 + =============== =============== + { A == 1, B == 2, C = 3, P == &A, Q == &C } + B = 4; + <barrera de escritura> + WRITE_ONCE(P, &B); + Q = READ_ONCE_OLD(P); + WRITE_ONCE(*Q, 5); + +Por lo tanto, no se requiere ninguna barrera de dependencia de direcciones +para ordenar la lectura en Q con el load en *Q. En otras palabras, este +resultado está prohibido, incluso sin una barrera de dependencia de +dirección implícita del READ_ONCE() moderno: + + (Q == &B) && (B == 4) + +Tenga en cuenta que este patrón debe ser raro. Después de todo, el objetivo +del orden de dependencia es -prevenir- escrituras en la estructura de +datos, junto con los costosos errores de caché asociados con tales +escrituras. Este patrón se puede utilizar para registrar raras condiciones +de error y similares, y el orden natural de las CPUs evita que se pierdan +tales registros. + + +Tenga en cuenta que el orden proporcionado por una dependencia de dirección +es local para la CPU que lo contiene. Lea la sección sobre "Atomicidad +multicopia" para más información. + + +La barrera de dependencia de dirección es muy importante para el sistema +RCU, por ejemplo. Vea rcu_assign_pointer() y rcu_dereference() en +include/linux/rcupdate.h. Esto permite que el objetivo actual de un puntero +RCU sea reemplazado con un nuevo objetivo modificado, sin que el objetivo +del reemplazo parezca estar inicializado de manera incompleta. + +Consulte también la subsección sobre "Coherencia de caché" para obtener un +ejemplo más completo. + +DEPENDENCIAS DE CONTROL +----------------------- + +Las dependencias de control pueden ser un poco complicadas porque los +compiladores actuales no las entienden. El propósito de esta sección es +ayudarle a prevenir que la ignorancia del compilador rompa su código. + +Una dependencia de control load-load (de carga a carga) requiere una +barrera de memoria de lectura completa, no simplemente una barrera +(implícita) de dependencia de direcciones para que funcione correctamente. +Considere el siguiente fragmento de código: + + q = READ_ONCE(a); + <barrera implícita de dependencia de direcciones> + if (q) { + /* BUG: No hay dependencia de dirección!!! */ + p = READ_ONCE(b); + } + +Esto no tendrá el efecto deseado porque no hay una dependencia de dirección +real, sino más bien una dependencia de control que la CPU puede +cortocircuitar al intentar predecir el resultado por adelantado, para que +otras CPU vean la carga de b como si hubiera ocurrido antes que la carga de +a. En cuyo caso lo que realmente se requiere es: + + q = READ_ONCE(a); + if (q) { + <barrera de lectura> + p = READ_ONCE(b); + } + +Sin embargo, los stores no se especulan. Esto significa que ordenar -es- +provisto para dependencias de control de load-store, como en el siguiente +ejemplo: + + q = READ_ONCE(a); + if (q) { + WRITE_ONCE(b, 1); + } + +Las dependencias de control se emparejan normalmente con otros tipos de +barreras. Dicho esto, tenga en cuenta que ni READ_ONCE() ni WRITE_ONCE() +son opcionales! Sin READ_ONCE(), el compilador podría combinar la carga de +'a' con otras cargas de 'a'. Sin WRITE_ONCE(), el compilador podría +combinar el store de 'b' con otros stores de 'b'. Cualquiera de estos casos +puede dar lugar a efectos en el orden muy contrarios a la intuición. + +Peor aún, si el compilador puede probar (decir) que el valor de la +variable 'a' siempre es distinta de cero, estaría dentro de sus derechos +para optimizar el ejemplo original eliminando la declaración "if", como: + + q = a; + b = 1; /* BUG: Compilador y CPU pueden ambos reordernar!!! */ + +Así que no deje de lado READ_ONCE(). + +Es tentador tratar de hacer cumplir el orden en stores idénticos en ambos +caminos del "if" de la siguiente manera: + + q = READ_ONCE(a); + if (q) { + barrier(); + WRITE_ONCE(b, 1); + hacer_algo(); + } else { + barrier(); + WRITE_ONCE(b, 1); + hacer_otra_cosa(); + } + +Desafortunadamente, los compiladores actuales transformarán esto de la +siguiente manera en casos de alto nivel de optimización: + + q = READ_ONCE(a); + barrier(); + WRITE_ONCE(b, 1); /* BUG: No hay orden en load de a!!! */ + if (q) { + /* WRITE_ONCE(b, 1); -- movido arriba, BUG!!! */ + hacer_algo(); + } else { + /* WRITE_ONCE(b, 1); -- movido arriba, BUG!!! */ + hacer_otra_cosa(); + } + +Ahora no hay condicional entre la carga de 'a' y el store de 'b', lo que +significa que la CPU está en su derecho de reordenarlos: El condicional es +absolutamente necesario y debe estar presente en el código ensamblador +incluso después de que se hayan aplicado todas las optimizaciones del +compilador. Por lo tanto, si necesita ordenar en este ejemplo, necesita +explícitamente barreras de memoria, por ejemplo, smp_store_release(): + + + q = READ_ONCE(a); + if (q) { + smp_store_release(&b, 1); + hacer_algo(); + } else { + smp_store_release(&b, 1); + hacer_otra_cosa(); + } + +Por el contrario, sin barreras de memoria explícita, el control de un if +con dos opciones está garantizado solo cuando los stores difieren, por +ejemplo: + + q = READ_ONCE(a); + if (q) { + WRITE_ONCE(b, 1); + hacer_algo(); + } else { + WRITE_ONCE(b, 2); + hacer_otra_cosa(); + } + +Aún se requiere el inicial READ_ONCE() para evitar que el compilador toque +el valor de 'a'. + +Además, debe tener cuidado con lo que hace con la variable local 'q', de lo +contrario, el compilador podría adivinar el valor y volver a eliminar el +necesario condicional. Por ejemplo: + + q = READ_ONCE(a); + if (q % MAX) { + WRITE_ONCE(b, 1); + hacer_algo(); + } else { + WRITE_ONCE(b, 2); + hacer_otra_cosa(); + } + +Si MAX se define como 1, entonces el compilador sabe que (q % MAX) es igual +a cero, en cuyo caso el compilador tiene derecho a transformar el código +anterior en el siguiente: + + q = READ_ONCE(a); + WRITE_ONCE(b, 2); + hacer_otra_cosa(); + +Dada esta transformación, la CPU no está obligada a respetar el orden entre +la carga de la variable 'a' y el store de la variable 'b'. Es tentador +agregar una barrier(), pero esto no ayuda. El condicional se ha ido, y la +barrera no lo traerá de vuelta. Por lo tanto, si confia en este orden, debe +asegurarse de que MAX sea mayor que uno, tal vez de la siguiente manera: + + q = READ_ONCE(a); + BUILD_BUG_ON(MAX <= 1); /* Orden de carga de a con store de b */ + if (q % MAX) { + WRITE_ONCE(b, 1); + hacer_algo(); + } else { + WRITE_ONCE(b, 2); + hacer_otra_cosa(); + } + +Tenga en cuenta una vez más que los stores de 'b' difieren. Si fueran +idénticos, como se señaló anteriormente, el compilador podría sacar ese +store fuera de la declaración 'if'. + +También debe tener cuidado de no confiar demasiado en el cortocircuito +de la evaluación booleana. Considere este ejemplo: + + q = READ_ONCE(a); + if (q || 1 > 0) + WRITE_ONCE(b, 1); + +Debido a que la primera condición no puede fallar y la segunda condición es +siempre cierta, el compilador puede transformar este ejemplo de la +siguiente manera, rompiendo la dependencia del control: + + q = READ_ONCE(a); + WRITE_ONCE(b, 1); + +Este ejemplo subraya la necesidad de asegurarse de que el compilador no +pueda adivinar su código. Más generalmente, aunque READ_ONCE() fuerza +al compilador para emitir código para una carga dada, no fuerza al +compilador para usar los resultados. + +Además, las dependencias de control se aplican solo a la cláusula then y +la cláusula else de la sentencia if en cuestión. En particular, no se +aplica necesariamente al código que sigue a la declaración if: + + q = READ_ONCE(a); + if (q) { + WRITE_ONCE(b, 1); + } else { + WRITE_ONCE(b, 2); + } + WRITE_ONCE(c, 1); /* BUG: No hay orden para la lectura de 'a'. */ + +Es tentador argumentar que, de hecho, existe un orden porque el compilador +no puede reordenar accesos volátiles y tampoco puede reordenar escrituras +en 'b' con la condición. Desafortunadamente para esta línea de +razonamiento, el compilador podría compilar las dos escrituras en 'b' como +instrucciones de movimiento condicional, como en este fantástico idioma +pseudo-ensamblador: + + ld r1,a + cmp r1,$0 + cmov,ne r4,$1 + cmov,eq r4,$2 + st r4,b + st $1,c + +Una CPU débilmente ordenada no tendría dependencia de ningún tipo entre la +carga de 'a' y el store de 'c'. Las dependencias de control se extenderían +solo al par de instrucciones cmov y el store dependiente de ellas. En +resumen, las dependencias de control se aplican solo a los stores en la +cláusula then y la cláusula else de la sentencia if en cuestión (incluidas +las funciones invocado por esas dos cláusulas), no al código que sigue a +esa declaración if. + + +Tenga muy en cuenta que el orden proporcionado por una dependencia de +control es local a la CPU que lo contiene. Vea el apartado de "Atomicidad +multicopia" para más información. + + +En resumen: + + (*) Las dependencias de control pueden ordenar cargas anteriores para + stores posteriores. Sin embargo, no garantizan ningún otro tipo de + orden: No cargas previas contra cargas posteriores, ni + almacenamientos previos y luego nada. Si necesita tales formas de + orden, use smp_rmb(), smp_wmb() o, en el caso de stores anteriores y + cargas posteriores, smp_mb(). + + (*) Si ambos caminos de la declaración "if" comienzan con stores + idénticos de la misma variable, entonces esos stores deben ser + ordenados, ya sea precediéndoles a ambos con smp_mb() o usando + smp_store_release() para realizar el store. Tenga en cuenta que -no- + es suficiente usar barrier() al comienzo de cada caso de la + declaración "if" porque, como se muestra en el ejemplo anterior, la + optimización de los compiladores puede destruir la dependencia de + control respetando al pie de la letra la ley de barrier(). + + (*) Las dependencias de control requieren al menos un condicional en + tiempo de ejecución entre la carga anterior y el almacenamiento + posterior, y este condicional debe implicar la carga previa. Si el + compilador es capaz de optimizar el condicional y quitarlo, también + habrá optimizado el ordenar. El uso cuidadoso de READ_ONCE() y + WRITE_ONCE() puede ayudar a preservar el necesario condicional. + + (*) Las dependencias de control requieren que el compilador evite + reordenar las dependencia hasta su inexistencia. El uso cuidadoso de + READ_ONCE() o atomic{,64}_read() puede ayudarle a preservar la + dependencia de control. Consulte la sección BARRERA DEL COMPILADOR + para obtener más información al respecto. + + (*) Las dependencias de control se aplican solo a la cláusula then y la + cláusula else de la sentencia "if" que contiene la dependencia de + control, incluyendo cualquier función a la que llamen dichas dos + cláusulas. Las dependencias de control no se aplican al código que + sigue a la instrucción if que contiene la dependencia de control. + + (*) Las dependencias de control se emparejan normalmente con otros tipos + de barreras. + + (*) Las dependencias de control no proporcionan atomicidad multicopia. Si + usted necesita todas las CPU para ver un store dado al mismo tiempo, + emplee smp_mb(). + + (*) Los compiladores no entienden las dependencias de control. Por lo + tanto es su trabajo asegurarse de que no rompan su código. + + +EMPAREJAMIENTO DE BARRERAS SMP +------------------------------ + +Cuando se trata de interacciones CPU-CPU, ciertos tipos de barrera de +memoria deben estar siempre emparejados. La falta del apropiado +emparejamiento es casi seguro un error. + +Las barreras generales se emparejan entre sí, aunque también se emparejan +con la mayoría de otro tipo de barreras, aunque sin atomicidad multicopia. +Una barrera de adquisición se empareja con una barrera de liberación, pero +ambas también pueden emparejarse con otras barreras, incluidas, por +supuesto, las barreras generales. Una barrera de escritura se empareja con +una barrera de dependencia de dirección, una dependencia de control, una +barrera de adquisición, una barrera de liberación, una barrera de lectura +o una barrera general. Del mismo modo, una barrera de lectura se empareja +con una de dependencia de control o barrera de dependencia de dirección con +una barrera de escritura, una barrera de adquisición, una barrera de +liberación o una barrera general: + + CPU 1 CPU 2 + =============== =============== + WRITE_ONCE(a, 1); + <barrera de escritura> + WRITE_ONCE(b, 2); x = READ_ONCE(b); + <barrera de lectura> + y = READ_ONCE(a); + +O bien: + + CPU 1 CPU 2 + =============== =============================== + a = 1; + <barrera de escritura> + WRITE_ONCE(b, &a); x = READ_ONCE(b); + <barrera de dependencia de dirección implícita> + y = *x; + +O incluso: + + CPU 1 CPU 2 + =============== =============================== + r1 = READ_ONCE(y); + <barrera general> + WRITE_ONCE(x, 1); if (r2 = READ_ONCE(x)) { + <barrera de control implícita> + WRITE_ONCE(y, 1); + } + + assert(r1 == 0 || r2 == 0); + +Básicamente, la barrera de lectura siempre tiene que estar ahí, aunque +puede ser del tipo "más débil". + +[!] Tenga en cuenta que normalmente se esperaría que los stores antes de la +barrera de escritura se hagan coincidir con los stores después de la +barrera de lectura o la barrera de dependencia de dirección, y viceversa: + + CPU 1 CPU 2 + =================== =================== + WRITE_ONCE(a, 1); }---- --->{ v = READ_ONCE(c); + WRITE_ONCE(b, 2); } \ / { w = READ_ONCE(d); + <barrera de escritura> \ <barrera de lectura> + WRITE_ONCE(c, 3); } / \ { x = READ_ONCE(a); + WRITE_ONCE(d, 4); }---- --->{ y = READ_ONCE(b); + + +EJEMPLOS DE SECUENCIAS DE BARRERA DE MEMORIA +-------------------------------------------- + +En primer lugar, las barreras de escritura actúan como orden parcial en las +operaciones de store. Considere la siguiente secuencia de eventos: + + CPU 1 + ======================= + STORE A = 1 + STORE B = 2 + STORE C = 3 + <barrera de escritura> + STORE D = 4 + STORE E = 5 + +Esta secuencia de eventos es finalizado para con el sistema de coherencia +de memoria en un orden que el resto del sistema podría percibir como el +conjunto desordenado { STORE A, STORE B, STORE C} todo ocurriendo antes del +conjunto desordenado { STORE D, STORE E}: + + + +-------+ : : + | | +------+ + | |------>| C=3 | } /\ + | | : +------+ }----- \ -----> Eventos perceptibles para + | | : | A=1 | } \/ el resto del sistema + | | : +------+ } + | CPU 1 | : | B=2 | } + | | +------+ } + | | wwwwwwwwwwwwwwww } <--- En este momento la barrera de + | | +------+ } escritura requiere que todos los + | | : | E=5 | } stores anteriores a la barrera + | | : +------+ } sean confirmados antes de que otros + | |------>| D=4 | } store puedan suceder + | | +------+ + +-------+ : : + | + | Secuencia por la cual los stores son confirmados al + | sistema de memoria por parte del CPU 1 + V + +En segundo lugar, las barreras de dependencia de dirección actúan como +órdenes parciales sobre la dirección de cargas dependientes. Considere la +siguiente secuencia de eventos: + + CPU 1 CPU 2 + ======================= ======================= + { B = 7; X = 9; Y = 8; C = &Y } + STORE A = 1 + STORE B = 2 + <barrera de escritura> + STORE C = &B LOAD X + STORE D = 4 LOAD C (consigue &B) + LOAD *C (lee B) + +Sin intervención, la CPU 2 puede percibir los eventos en la CPU 1 en orden +aleatorio a efectos prácticos, a pesar de la barrera de escritura emitida +por la CPU 1: + + +-------+ : : : : + | | +------+ +-------+ | Secuencia de + | |------>| B=2 |----- --->| Y->8 | | actualizado de + | | : +------+ \ +-------+ | percepción en CPU 2 + | CPU 1 | : | A=1 | \ --->| C->&Y | V + | | +------+ | +-------+ + | | wwwwwwwwwwwwwwww | : : + | | +------+ | : : + | | : | C=&B |--- | : : +-------+ + | | : +------+ \ | +-------+ | | + | |------>| D=4 | ----------->| C->&B |------>| | + | | +------+ | +-------+ | | + +-------+ : : | : : | | + | : : | | + | : : | CPU 2 | + | +-------+ | | + Percepción de B ---> | | B->7 |------>| | + aparentemente incorrecta! | +-------+ | | + | : : | | + | +-------+ | | + La carga de X frena ---> \ | X->9 |------>| | + el mantenimiento de \ +-------+ | | + la coherencia de B ----->| B->2 | +-------+ + +-------+ + : : + + +En el ejemplo anterior, la CPU 2 percibe que B es 7, a pesar de la carga de +*C (que sería B) viniendo después del LOAD de C. + +Sin embargo, si se colocara una barrera de dependencia de dirección entre +la carga de C y la carga de *C (es decir: B) en la CPU 2: + + CPU 1 CPU 2 + ======================= ======================= + { B = 7; X = 9; Y = 8; C = &Y } + STORE A = 1 + STORE B = 2 + <barrera de escritura> + STORE C = &B LOAD X + STORE D = 4 LOAD C (consigue &B) + <barrera de dependencia de dirección> + LOAD *C (reads B) + +entonces ocurrirá lo siguiente: + + +-------+ : : : : + | | +------+ +-------+ + | |------>| B=2 |----- --->| Y->8 | + | | : +------+ \ +-------+ + | CPU 1 | : | A=1 | \ --->| C->&Y | + | | +------+ | +-------+ + | | wwwwwwwwwwwwwwww | : : + | | +------+ | : : + | | : | C=&B |--- | : : +-------+ + | | : +------+ \ | +-------+ | | + | |------>| D=4 | ----------->| C->&B |------>| | + | | +------+ | +-------+ | | + +-------+ : : | : : | | + | : : | | + | : : | CPU 2 | + | +-------+ | | + | | X->9 |------>| | + | +-------+ | | + Se asegura de que ---> \ aaaaaaaaaaaaaaaaa | | + los efectos anteriores al \ +-------+ | | + store de C sean percibidos ----->| B->2 |------>| | + por los siguientes loads +-------+ | | + : : +-------+ + + +Y en tercer lugar, una barrera de lectura actúa como un orden parcial sobre +las cargas. Considere la siguiente secuencia de eventos: + + CPU 1 CPU 2 + ======================= ======================= + { A = 0, B = 9 } + STORE A=1 + <barrera de escritura> + STORE B=2 + LOAD B + LOAD A + +Sin intervención, la CPU 2 puede elegir percibir los eventos en la CPU 1 en +algún orden aleatorio a efectos prácticos, a pesar de la barrera de +escritura emitida por la CPU 1: + + +-------+ : : : : + | | +------+ +-------+ + | |------>| A=1 |------ --->| A->0 | + | | +------+ \ +-------+ + | CPU 1 | wwwwwwwwwwwwwwww \ --->| B->9 | + | | +------+ | +-------+ + | |------>| B=2 |--- | : : + | | +------+ \ | : : +-------+ + +-------+ : : \ | +-------+ | | + ---------->| B->2 |------>| | + | +-------+ | CPU 2 | + | | A->0 |------>| | + | +-------+ | | + | : : +-------+ + \ : : + \ +-------+ + ---->| A->1 | + +-------+ + : : + +Sin embargo, si se colocara una barrera de lectura entre la carga de B y la +carga de A en la CPU 2: + + CPU 1 CPU 2 + ======================= ======================= + { A = 0, B = 9 } + STORE A=1 + <barrera de escritura> + STORE B=2 + LOAD B + <barrera de lectura> + LOAD A + +entonces el orden parcial impuesto por la CPU 1 será percibido +correctamente por la CPU 2: + + +-------+ : : : : + | | +------+ +-------+ + | |------>| A=1 |------ --->| A->0 | + | | +------+ \ +-------+ + | CPU 1 | wwwwwwwwwwwwwwww \ --->| B->9 | + | | +------+ | +-------+ + | |------>| B=2 |--- | : : + | | +------+ \ | : : +-------+ + +-------+ : : \ | +-------+ | | + ---------->| B->2 |------>| | + | +-------+ | CPU 2 | + | : : | | + | : : | | + En este punto la barrera ----> \ rrrrrrrrrrrrrrrrr | | + de lectura consigue que \ +-------+ | | + todos los efectos anteriores ---->| A->1 |------>| | + al almacenamiento de B sean +-------+ | | + perceptibles por la CPU 2 : : +-------+ + + +Para ilustrar esto de manera más completa, considere lo que podría pasar si +el código contenía una carga de A a cada lado de la barrera de lectura: + + CPU 1 CPU 2 + ======================= ======================= + { A = 0, B = 9 } + STORE A=1 + <barrera de escritura> + STORE B=2 + LOAD B + LOAD A [primer load de A] + <rbarrera de lectura> + LOAD A [segundo load de A] + +Aunque las dos cargas de A ocurren después de la carga de B, ambas pueden +obtener diferentes valores: + + +-------+ : : : : + | | +------+ +-------+ + | |------>| A=1 |------ --->| A->0 | + | | +------+ \ +-------+ + | CPU 1 | wwwwwwwwwwwwwwww \ --->| B->9 | + | | +------+ | +-------+ + | |------>| B=2 |--- | : : + | | +------+ \ | : : +-------+ + +-------+ : : \ | +-------+ | | + ---------->| B->2 |------>| | + | +-------+ | CPU 2 | + | : : | | + | : : | | + | +-------+ | | + | | A->0 |------>| 1st | + | +-------+ | | + En este punto la barrera ----> \ rrrrrrrrrrrrrrrrr | | + de lectura consigue que \ +-------+ | | + todos los efectos anteriores ---->| A->1 |------>| | + al almacenamiento de B sean +-------+ | | + perceptibles por la CPU 2 : : +-------+ + +Pero puede ser que la actualización a A desde la CPU 1 se vuelva +perceptible para la CPU 2 antes de que la barrera de lectura se complete de +todos modos: + + +-------+ : : : : + | | +------+ +-------+ + | |------>| A=1 |------ --->| A->0 | + | | +------+ \ +-------+ + | CPU 1 | wwwwwwwwwwwwwwww \ --->| B->9 | + | | +------+ | +-------+ + | |------>| B=2 |--- | : : + | | +------+ \ | : : +-------+ + +-------+ : : \ | +-------+ | | + ---------->| B->2 |------>| | + | +-------+ | CPU 2 | + | : : | | + \ : : | | + \ +-------+ | | + ---->| A->1 |------>| 1st | + +-------+ | | + rrrrrrrrrrrrrrrrr | | + +-------+ | | + | A->1 |------>| 2nd | + +-------+ | | + : : +-------+ + +La garantía es que la segunda carga siempre dará como resultado A == 1 si +la carga de B resultó en B == 2. No existe tal garantía para la primera +carga de A; esto puede dar como resultado A == 0 o A == 1. + + +BARRERAS DE MEMORIA DE LECTURA FRENTE A ESPECULACIÓN DE CARGA +------------------------------------------------------------- + +Muchas CPU especulan con las cargas: es decir, ven que necesitarán cargar +un elemento de la memoria, y encuentran un momento en el que no están +usando el bus para ningún otra carga, y también en la carga por adelantado, +aunque en realidad no lo hayan llegado a ese punto en el flujo de ejecución +de instrucciones todavía. Esto permite que la instrucción de carga real +potencialmente complete de inmediato, porque la CPU ya tiene el valor a +mano. + +Puede resultar que la CPU en realidad no necesitara el valor, tal vez +porque una condición eludió la carga, en cuyo caso puede descartar el valor +o simplemente almacenar en caché para su uso posterior. + +Considere: + + CPU 1 CPU 2 + ======================= ======================= + LOAD B + DIVIDE } Instrucciones de división + DIVIDE } tardan mucho en terminar + LOAD A + +donde DIVIDE es DIVIDIR. Que podría aparecer como esto: + + : : +-------+ + +-------+ | | + --->| B->2 |------>| | + +-------+ | CPU 2 | + : :DIVIDE | | + +-------+ | | + La CPU ocupada con la división ---> --->| A->0 |~~~~ | | + especula sobre el LOAD de A +-------+ ~ | | + : : ~ | | + : :DIVIDE | | + : : ~ | | + Una vez completadas las divisiones --> : : ~-->| | + la CPU puede realizar el : : | | + LOAD con efecto inmediato : : +-------+ + + +Colocando una barrera de lectura o una barrera de dependencia de dirección +justo antes de la segundo carga: + + + + CPU 1 CPU 2 + ======================= ======================= + LOAD B + DIVIDE + DIVIDE + <rbarrera de lectura> + LOAD A + +obligará a reconsiderar cualquier valor obtenido especulativamente en una +medida dependiente del tipo de barrera utilizada. Si no se hizo ningún +cambio en la ubicación de memoria especulada, entonces el valor especulado +solo se usará: + + : : +-------+ + +-------+ | | + --->| B->2 |------>| | + +-------+ | CPU 2 | + : :DIVIDE | | + +-------+ | | + La CPU ocupada con la división ---> --->| A->0 |~~~~ | | + especula sobre el LOAD de A +-------+ ~ | | + : : ~ | | + : :DIVIDE | | + : : ~ | | + : : ~ | | + rrrrrrrrrrrrrrrr~ | | + : : ~ | | + : : ~-->| | + : : | | + : : +-------+ + + +pero si había una actualización o una invalidación de otra CPU pendiente, +entonces la especulación será cancelada y el valor recargado: + + : : +-------+ + +-------+ | | + --->| B->2 |------>| | + +-------+ | CPU 2 | + : :DIVIDE | | + +-------+ | | + La CPU ocupada con la división ---> --->| A->0 |~~~~ | | + especula sobre el LOAD de A +-------+ ~ | | + : : ~ | | + : :DIVIDE | | + : : ~ | | + : : ~ | | + rrrrrrrrrrrrrrrrr | | + +-------+ | | + La especulación es descartada ---> --->| A->1 |------>| | + y un valor actualizado +-------+ | | + es conseguido : : +-------+ + +ATOMICIDAD MULTICOPIA +--------------------- + +La atomicidad multicopia es una noción profundamente intuitiva sobre el +orden que no es siempre proporcionada por los sistemas informáticos reales, +a saber, que un determinada store se vuelve visible al mismo tiempo para +todos las CPU o, alternativamente, que todas las CPU acuerdan el orden en +que todos los stores se vuelven visibles. Sin embargo, el soporte para +atomicidad multicopia completa descartaría valiosas optimizaciones +hardware, por lo que una versión más débil conocida como ``otra atomicidad +multicopia'' en cambio, solo garantiza que un store dado se vuelva visible +al mismo tiempo en todas las -otras- CPUs. El resto de este documento +discute esta versión más débil, pero por brevedad lo llamaremos simplemente +``atomicidad multicopia''. + +El siguiente ejemplo demuestra la atomicidad multicopia: + + CPU 1 CPU 2 CPU 3 + ======================= ======================= ======================= + { X = 0, Y = 0 } + STORE X=1 r1=LOAD X (reads 1) LOAD Y (reads 1) + <barrera general> <barrera de lectura> + STORE Y=r1 LOAD X + +Suponga que la carga de la CPU 2 desde X devuelve 1, que luego almacena en +Y, y la carga de la CPU 3 desde Y devuelve 1. Esto indica que el store de +la CPU 1 a X precede a la carga de la CPU 2 desde X y el store de esa CPU 2 +a Y precede la carga de la CPU 3 desde Y. Además, las barreras de memoria +garantizan que la CPU 2 ejecuta su carga antes que su almacenamiento, y la +CPU 3 carga desde Y antes de cargar desde X. La pregunta entonces es +"¿Puede la carga de la CPU 3 desde X devolver 0?" + +Debido a que la carga de la CPU 3 desde X en cierto sentido viene después +de la carga de la CPU 2, es natural esperar que la carga de la CPU 3 desde +X deba devolver 1. Esta expectativa se deriva de la atomicidad multicopia: +si una carga que se ejecuta en la CPU B sigue una carga de la misma +variable que se ejecuta en la CPU A (y la CPU A no almacenó originalmente +el valor que leyó), entonces en sistemas atómicos multicopia, la carga de +la CPU B debe devolver el mismo valor que hizo la carga de la CPU A o algún +valor posterior. Sin embargo, el kernel Linux no requiere que los sistemas +sean atómicos multicopia. + +El uso de una barrera de memoria general en el ejemplo anterior compensa +cualquier falta de atomicidad multicopia. En el ejemplo, si la carga de la +CPU 2 de X devuelve 1 y la carga de la CPU 3 de Y devuelve 1, entonces la +carga de la CPU 3 desde X debe de hecho también devolver 1. + +Sin embargo, las dependencias, las barreras de lectura y las barreras de +escritura no siempre son capaces de compensar la atomicidad no multicopia. +Por ejemplo, supongamos que la barrera general de la CPU 2 se elimina del +ejemplo anterior, dejando solo la dependencia de datos que se muestra a +continuación: + + CPU 1 CPU 2 CPU 3 + ======================= ======================= ======================= + { X = 0, Y = 0 } + STORE X=1 r1=LOAD X (escribe 1) LOAD Y (lee 1) + <dependencia de datos> <barrera de lectura> + STORE Y=r1 LOAD X (lee 0) + +Esta sustitución permite que la atomicidad no multicopia se desenfrene: en +este ejemplo, es perfectamente legal que la carga de la CPU 2 desde X +devuelva 1, la carga de la CPU 3 desde Y devuelva 1, y su carga desde X +tenga valor 0. + +El punto clave es que aunque la dependencia de datos de la CPU 2 ordena su +carga y store, no garantiza ordenar el store de la CPU 1. De forma que, si +este ejemplo se ejecuta en un sistema atómico no multicopia donde las CPU 1 +y 2 comparten un buffer de almacenamiento o un nivel de caché, la CPU 2 +podría tener acceso anticipado de escritura a CPU 1. Por lo tanto, se +requieren barreras generales para garantizar que todas las CPU acurden el +orden combinado de accesos múltiples. + +Las barreras generales pueden compensar no solo la atomicidad no +multicopia, pero también pueden generar orden adicional que puede asegurar +que -todas- las CPU percibirán el mismo orden de -todas- las operaciones. +Por el contrario, una cadena de parejas de liberación-adquisición no +proporciona este orden adicional, lo que significa que solo se garantiza +que las CPU de la cadena estén de acuerdo en el orden combinado de los +accesos. Por ejemplo, cambiando a código C en deferencia al fantasma de +Herman Hollerith: + + int u, v, x, y, z; + + void cpu0(void) + { + r0 = smp_load_acquire(&x); + WRITE_ONCE(u, 1); + smp_store_release(&y, 1); + } + + void cpu1(void) + { + r1 = smp_load_acquire(&y); + r4 = READ_ONCE(v); + r5 = READ_ONCE(u); + smp_store_release(&z, 1); + } + + void cpu2(void) + { + r2 = smp_load_acquire(&z); + smp_store_release(&x, 1); + } + + void cpu3(void) + { + WRITE_ONCE(v, 1); + smp_mb(); + r3 = READ_ONCE(u); + } + +Dado que cpu0(), cpu1() y cpu2() participan en una cadena de parejas +smp_store_release()/smp_load_acquire(), el siguiente resultado estaría +prohibido: + + r0 == 1 && r1 == 1 && r2 == 1 + +Además, debido a la relación liberación-adquisición entre cpu0() y cpu1(), +cpu1() debe ver las escrituras de cpu0(), de modo que el siguiente +resultado estaría prohibido: + + r1 == 1 && r5 == 0 + +Sin embargo, el orden proporcionado por una cadena de +liberación-adquisición es local a las CPU que participan en esa cadena y no +se aplica a cpu3(), al menos aparte de los stores. Por lo tanto, es posible +el siguiente resultado: + + r0 == 0 && r1 == 1 && r2 == 1 && r3 == 0 && r4 == 0 + +Por otro lado, también el siguiente resultado es posible: + + r0 == 0 && r1 == 1 && r2 == 1 && r3 == 0 && r4 == 0 && r5 == 1 + +Aunque cpu0(), cpu1() y cpu2() verán sus respectivas lecturas y escrituras +en orden, las CPU que no participan en la cadena de liberación-adquisición +pueden estar en desacuerdo con el orden. Este desacuerdo se debe al hecho +de que las instrucciones de barrera de memoria débiles utilizadas para +implementar smp_load_acquire() y smp_store_release() no son necesarios para +ordenar stores anteriores contra cargas posteriores en todos los casos. +Esto significa que cpu3() puede ver el store de cpu0() suceder -después- de +la carga de cpu1() desde v, aunque tanto cpu0() como cpu1() están de +acuerdo en que estas dos operaciones ocurrieron en el orden previsto. + +Sin embargo, tenga en cuenta que smp_load_acquire() no es mágico. En +particular, simplemente lee de su argumento en orden. Es decir, -no- +asegura que se leerá cualquier valor en particular. Por lo tanto, los +siguiente resultados son posibles: + + r0 == 0 && r1 == 0 && r2 == 0 && r5 == 0 + +Tenga en cuenta que este resultado puede ocurrir incluso en un mítico +sistema, consistente en secuencia, donde nunca se reordena nada. + +Para reiterar, si su código requiere un orden completo de todas las +operaciones, utilice barreras generales en todo momento. + + +============================== +BARRERAS EXPLÍCITAS DEL KERNEL +============================== + +El kernel Linux tiene una variedad de diferentes barreras que actúan a +diferentes niveles: + + (*) Barrera del compilador. + + (*) Barreras de memoria de la CPU. + + +BARRERA DEL COMPILADOR +----------------------- + +El kernel de Linux tiene una función de barrera del compilador explícita +que evita que el el compilador mueva los accesos a la memoria de cualquier +lado al otro: + + barrier(); + +Esta es una barrera general: no hay variantes de barrier() para casos de +lectura-lectura o escritura-escritura. Sin embargo, READ_ONCE() y +WRITE_ONCE() pueden ser considerado como formas débiles de barrier() que +afectan solo específicos accesos marcados por READ_ONCE() o WRITE_ONCE(). + +La función barrier() produce los siguientes efectos: + + (*) Evita que el compilador reordene los accesos tras barrier() para + preceder a cualquier acceso que preceda a barrier(). Un ejemplo de uso + de esta propiedad es facilitar la comunicación entre código del + interrupt-handler (encargo de gestionar interrupciones) y el código + que fue interrumpido. + + (*) Dentro de un bucle ("loop"), obliga al compilador a cargar las + variables utilizadas en ese loop condicional en cada paso a través de + ese loop. + +Las funciones READ_ONCE() y WRITE_ONCE() pueden evitar cualquier cantidad +de optimizaciones que, si bien son perfectamente seguras en código de un +solo subproceso, pueden resultar fatales en código concurrente. Aquí hay +algunos ejemplos de tal tipo de optimizaciones: + +(*) El compilador está en su derecho de reordenar cargas y stores de la + misma variable, y en algunos casos, la CPU está dentro de su + derecho de reordenar cargas a la misma variable. Esto significa que + el siguiente código: + + a[0] = x; + a[1] = x; + + Podría resultar en un valor más antiguo de x almacenado en a[1] que en + a[0]. Evite que tanto el compilador como la CPU hagan esto de la + siguiente manera: + + a[0] = READ_ONCE(x); + a[1] = READ_ONCE(x); + + En resumen, READ_ONCE() y WRITE_ONCE() proporcionan coherencia de + caché para accesos desde múltiples CPUs a una sola variable. + + (*) El compilador tiene derecho a juntar cargas sucesivas de la misma + variable. Tal fusión puede hacer que el compilador "optimice" el + siguiente código: + + while (tmp = a) + hacer_algo_con(tmp); + + en el siguiente código, que, aunque en cierto sentido es legítimo + para un código de un solo subproceso, es casi seguro que no es lo + que el desarrollador pretendía: + + if (tmp = a) + for (;;) + hacer_algo_con(tmp); + + Use READ_ONCE() para evitar que el compilador le haga esto: + + while (tmp = READ_ONCE(a)) + hacer_algo_con(tmp); + + (*) El compilador tiene derecho a recargar una variable, por ejemplo, + en los casos en que la alta presión de los registros impida que el + compilador mantenga todos los datos de interés en registros. El + compilador podría por lo tanto, optimizar la variable 'tmp' de nuestro + ejemplo anterior: + + while (tmp = a) + hacer_algo_con(tmp); + + Esto podría resultar en el siguiente código, que es perfectamente + seguro en código de subproceso único, pero puede ser fatal en código + concurrente: + + while (a) + hacer_algo_con(a); + + Por ejemplo, la versión optimizada de este código podría resultar en + pasar un cero a hacer_algo_con() en el caso de que la variable a sea + modificada por alguna otra CPU, entre la instrucción "while" y la + llamada a hacer_algo_con(). + + De nuevo, use READ_ONCE() para evitar que el compilador haga esto: + + while (tmp = READ_ONCE(a)) + hacer_algo_con(tmp); + + Tenga en cuenta que si el compilador se queda sin registros, podría + guardar tmp en la pila ("stack"). El overhead (coste en eficiencia) de + este guardado y posterior restauración es por lo que los compiladores + recargan las variables. Hacerlo es perfectamente seguro para código de + subproceso único, por lo que debe informar al compilador sobre los + casos donde no sea seguro. + + (*) El compilador está en su derecho de omitir una carga por completo si + sabe cual será su valor. Por ejemplo, si el compilador puede probar + que el valor de la variable 'a' siempre es cero, puede optimizar este + código: + + while (tmp = a) + hacer_algo_con(tmp); + + En esto: + + do { } while (0); + + Esta transformación es una victoria para un código de un solo + subproceso, porque se deshace de una carga y un branch. El problema es + que el compilador llevará a cabo su prueba asumiendo que la CPU actual + es la única actualizando la variable 'a'. Si la variable 'a' es + compartida, entonces la prueba del compilador será errónea. Use + READ_ONCE() para decirle al compilador que no sabe tanto como cree: + + while (tmp = READ_ONCE(a)) + hacer_algo_con(tmp); + + Pero, por favor, tenga en cuenta que el compilador también está + observando de cerca lo que usted hace con el valor después de + READ_ONCE(). Por ejemplo, suponga que Ud. hace lo siguiente y MAX es + una macro de preprocesador con el valor 1: + + while ((tmp = READ_ONCE(a)) % MAX) + hacer_algo_con(tmp); + + Entonces el compilador sabe que el resultado del operador "%" aplicado + a MAX siempre será cero, nuevamente permitiendo que el compilador + optimice el código hasta su casi inexistencia. (Aún se cargará desde + la variable 'a'.) + + (*) De manera similar, el compilador tiene derecho a omitir un store por + completo si sabe que la variable ya tiene el valor almacenado. + Nuevamente, el compilador asume que la CPU actual es la única que + almacena la variable, lo que puede hacer que el compilador haga + algo incorrecto para las variables compartidas. Por ejemplo, suponga + que tiene lo siguiente: + + a = 0; + ... Código que no almacena la variable a ... + a = 0; + + El compilador observa que el valor de la variable 'a' ya es cero, por + lo que bien podría omitir el segundo store. Esto supondría una fatal + sorpresa, si alguna otra CPU hubiera almacenado la variable 'a' + mientras tanto. + + Use WRITE_ONCE() para evitar que el compilador haga este tipo de + suposición equivocada: + + WRITE_ONCE(a, 0); + ... Código que no almacena la variable a ... + WRITE_ONCE(a, 0); + + (*) El compilador tiene derecho a reordenar los accesos a memoria a menos + que le diga que no. Por ejemplo, considere la siguiente interacción + entre el código de nivel de proceso y un controlador de interrupción: + + void nivel_de_procesamiento(void) + { + msg = ACQUIRE_mensaje(); + flag = true; + } + + void controlador_interrupcion(void) + { + if (flag) + procesar_mensaje(msg); + } + + No hay nada que impida que el compilador transforme + nivel_de_procesamiento() a lo siguiente, que de hecho, bien podría ser + una victoria para código de un solo subproceso: + + void nivel_de_procesamiento(void) + { + flag = true; + msg = ACQUIRE_mensaje(); + } + + Si la interrupción ocurre entre estas dos declaraciones, entonces + controlador_interrupcion() podría recibir un mensaje ilegible. Use + READ_ONCE() para evitar esto de la siguiente manera: + + void nivel_de_procesamiento(void) + { + WRITE_ONCE(msg, ACQUIRE_mensaje()); + WRITE_ONCE(flag, true); + } + + void controlador_interrupcion(void) + { + if (READ_ONCE(flag)) + procesar_mensaje(READ_ONCE(msg)); + } + + Tenga en cuenta que los envoltorios ("wrappers") READ_ONCE() y + WRITE_ONCE() en controlador_interrupcion() son necesarios si este + controlador de interrupciones puede ser interrumpido por algo que + también accede a 'flag' y 'msg', por ejemplo, una interrupción anidada + o un NMI. De lo contrario, READ_ONCE() y WRITE_ONCE() no son + necesarios en controlador_interrupcion() aparte de con fines de + documentación. (Tenga también en cuenta que las interrupciones + anidadas no ocurren típicamente en los kernels Linux modernos, de + hecho, si un controlador de interrupciones regresa con interrupciones + habilitadas, obtendrá un WARN_ONCE().) + + Debe suponer que el compilador puede mover READ_ONCE() y WRITE_ONCE() + a código que no contiene READ_ONCE(), WRITE_ONCE(), barrier(), o + primitivas similares. + + Este efecto también podría lograrse usando barrier(), pero READ_ONCE() + y WRITE_ONCE() son más selectivos: Con READ_ONCE() y WRITE_ONCE(), el + compilador solo necesita olvidar el contenido de ubicaciones de + memoria indicadas, mientras que con barrier() el compilador debe + descartar el valor de todas las ubicaciones de memoria que tiene + actualmente almacenadas en caché, en cualquier registro de la máquina. + Por supuesto, el compilador también debe respetar el orden en que + ocurren READ_ONCE() y WRITE_ONCE(), aunque la CPU, efectivamente, no + necesita hacerlo. + + (*) El compilador tiene derecho a inventar stores para una variable, + como en el siguiente ejemplo: + + if (a) + b = a; + else + b = 42; + + El compilador podría ahorrar un branch al optimizar esto de la + siguiente manera: + + b = 42; + if (a) + b = a; + + En el código de un solo subproceso, esto no solo es seguro, sino que + también ahorra un branch. Desafortunadamente, en código concurrente, + esta optimización podría causar que alguna otra CPU vea un valor falso + de 42, incluso si la variable 'a' nunca fue cero, al cargar la + variable 'b'. Use WRITE_ONCE() para evitar esto de la siguiente + manera: + + if (a) + WRITE_ONCE(b, a); + else + WRITE_ONCE(b, 42); + + El compilador también puede inventar cargas. Estos casos suelen ser + menos perjudiciales, pero pueden dar como resultado "bouncing" de la + línea de caché y, por lo tanto, bajo rendimiento y escalabilidad. + Utilice READ_ONCE() para evitar cargas inventadas. + + (*) Para ubicaciones de memoria alineadas cuyo tamaño les permita + acceder con una sola instrucción de referencia de memoria, evite el + "desgarro de la carga" (load tearing) y "desgarro del store" (store + tearing), en el que un solo gran acceso es reemplazado por múltiples + accesos menores. Por ejemplo, dada una arquitectura que tiene + instrucciones de almacenamiento de 16 bits con campos inmediatos de 7 + bits, el compilador podría tener la tentación de usar dos + instrucciones inmediatas de almacenamiento de 16 bits para implementar + el siguiente store de 32 bits: + + p = 0x00010002; + + Tenga en cuenta que GCC realmente usa este tipo de optimización, lo + cual no es sorprendente dado que probablemente costaría más de dos + instrucciones el construir la constante y luego almacenarla. Por lo + tanto, esta optimización puede ser una victoria en un código de un + solo subproceso. De hecho, un error reciente (desde que se solucionó) + hizo que GCC usara incorrectamente esta optimización en un store + volátil. En ausencia de tales errores, el uso de WRITE_ONCE() evita el + desgarro del store en el siguiente ejemplo: + + struct __attribute__((__packed__)) foo { + short a; + int b; + short c; + }; + struct foo foo1, foo2; + ... + + foo2.a = foo1.a; + foo2.b = foo1.b; + foo2.c = foo1.c; + + Debido a que no hay envoltorios READ_ONCE() o WRITE_ONCE() y no + hay markings volátiles, el compilador estaría en su derecho de + implementar estas tres declaraciones de asignación como un par de + cargas de 32 bits, seguido de un par de stores de 32 bits. Esto + resultaría en una carga con desgarro en 'foo1.b' y store del desgarro + en 'foo2.b'. READ_ONCE() y WRITE_ONCE() nuevamente evitan el desgarro + en este ejemplo: + + foo2.a = foo1.a; + WRITE_ONCE(foo2.b, READ_ONCE(foo1.b)); + foo2.c = foo1.c; + +Aparte de esto, nunca es necesario usar READ_ONCE() y WRITE_ONCE() en una +variable que se ha marcado como volátil. Por ejemplo, dado que 'jiffies' +está marcado como volátil, nunca es necesario usar READ_ONCE(jiffies). La +razón de esto es que READ_ONCE() y WRITE_ONCE() se implementan como +conversiones volátiles, lo que no tiene efecto cuando su argumento ya está +marcado como volátil. + +Tenga en cuenta que estas barreras del compilador no tienen un efecto +directo en la CPU, que luego puede reordenar las cosas como quiera. + + +BARRERAS DE MEMORIA DE LA CPU +----------------------------- + +El kernel de Linux tiene siete barreras básicas de memoria de CPU: + +TIPO OBLIGATORIO SMP CONDICIONAL +======================= =============== =============== +GENERAL mb() smp_mb() +WRITE wmb() smp_wmb() +READ rmb() smp_rmb() +DEPEDENCIA DE DIRECCIÓN READ_ONCE() + + +Todas las barreras de memoria, excepto las barreras de dependencia de +direcciones, implican una barrera del compilador. Las dependencias de +direcciones no imponen ningún orden de compilación adicional. + +Además: en el caso de las dependencias de direcciones, se esperaría que el +compilador emita las cargas en el orden correcto (por ejemplo, `a[b]` +tendría que cargar el valor de b antes de cargar a[b]), sin embargo, no hay +garantía alguna en la especificación de C sobre que el compilador no puede +especular el valor de b (por ejemplo, es igual a 1) y carga a[b] antes que +b (ej. tmp = a[1]; if (b != 1) tmp = a[b]; ). También existe el problema de +que un compilador vuelva a cargar b después de haber cargado a[b], teniendo +así una copia más nueva de b que a[b]. Aún no se ha conseguido un consenso +acerca de estos problemas, sin embargo, el macro READ_ONCE() es un buen +lugar para empezar a buscar. + +Las barreras de memoria SMP se reducen a barreras de compilador cuando se +compila a monoprocesador, porque se supone que una CPU parecerá ser +auto-consistente, y ordenará correctamente los accesos superpuestos +respecto a sí misma. Sin embargo, consulte la subsección "Guests de +máquinas virtuales" mas adelante. + +[!] Tenga en cuenta que las barreras de memoria SMP _deben_ usarse para +controlar el orden de referencias a memoria compartida en sistemas SMP, +aunque el uso de bloqueo en su lugar sea suficiente. + +Las barreras obligatorias no deben usarse para controlar los efectos de +SMP, ya que dichas barreras imponen una sobrecarga innecesaria en los +sistemas SMP y UP. Se pueden, sin embargo, usar para controlar los efectos +MMIO en los accesos a través de ventanas E/S de memoria relajada. Estas +barreras son necesarias incluso en sistemas que no son SMP, ya que afectan +al orden en que las operaciones de memoria aparecen en un dispositivo, al +prohibir tanto al compilador como a la CPU que sean reordenados. + + +Hay algunas funciones de barrera más avanzadas: + + (*) smp_store_mb(var, valor) + + Asigna el valor a la variable y luego inserta una barrera de memoria + completa después de ella. No se garantiza insertar nada más que una + barrera del compilador en una compilación UP. + + + (*) smp_mb__before_atomic(); + (*) smp_mb__after_atomic(); + + Estos se pueden usar con funciones RMW atómicas que no implican + barreras de memoria, pero donde el código necesita una barrera de + memoria. Ejemplos de funciones RMW atómicas que no implican una + barrera de memoria son, por ejemplo, agregar, restar, operaciones + condicionales (fallidas), funciones _relaxed, pero no atomic_read o + atomic_set. Un ejemplo común donde se puede requerir una barrera es + cuando se usan operaciones atómicas como referencia de contador. + + Estos también se utilizan para funciones atómicas RMW bitop que no + implican una barrera de memoria (como set_bit y clear_bit). + + Como ejemplo, considere una pieza de código que marca un objeto como + muerto y luego disminuye el contador de referencias del objeto: + + obj->dead = 1; + smp_mb__before_atomic(); + atomic_dec(&obj->ref_count); + + Esto asegura que la marca de muerte en el objeto se perciba como + fijada *antes* de que disminuya el contador de referencia. + + Consulte Documentation/atomic_{t,bitops}.txt para obtener más + información. + + + (*) dma_wmb(); + (*) dma_rmb(); + (*) dma_mb(); + + Estos son usados con memoria consistente para garantizar el orden de + escrituras o lecturas de memoria compartida accesible tanto para la + CPU como para un dispositivo compatible con DMA. + + Por ejemplo, considere un controlador de dispositivo que comparte + memoria con otro dispositivo y usa un valor de estado del descriptor + para indicar si el descriptor pertenece al dispositivo o a la CPU, y + un "doorbell" (timbre, punto de acceso) para avisarle cuando haya + nuevos descriptores disponibles: + + if (desc->status != DEVICE_OWN) { + /* no leer los datos hasta que tengamos el descriptor */ + dma_rmb(); + + /* leer/modificar datos */ + read_data = desc->data; + desc->data = write_data; + + /* flush de modificaciones antes de la actualización de estado */ + dma_wmb(); + + /* asignar propiedad */ + desc->status = DEVICE_OWN; + + /* notificar al dispositivo de nuevos descriptores */ + writel(DESC_NOTIFY, doorbell); + } + + El dma_rmb() nos permite garantizar que el dispositivo ha liberado su + propiedad antes de que leamos los datos del descriptor, y el dma_wmb() + permite garantizar que los datos se escriben en el descriptor antes de + que el dispositivo pueda ver que ahora tiene la propiedad. El dma_mb() + implica tanto un dma_rmb() como un dma_wmb(). Tenga en cuenta que, al + usar writel(), no se necesita un wmb() anterior para garantizar que + las escrituras de la memoria caché coherente se hayan completado antes + escribiendo a la región MMIO. El writel_relaxed() más barato no + proporciona esta garantía y no debe utilizarse aquí. + + Consulte la subsección "Efectos de barrera de E/S del kernel" para + obtener más información sobre accesorios de E/S relajados y el archivo + Documentation/core-api/dma-api.rst para más información sobre memoria + consistente. + + (*) pmem_wmb(); + + Es es para uso con memoria persistente para garantizar que los stores + para los que las modificaciones se escriben en el almacenamiento + persistente llegaron a dominio de durabilidad de la plataforma. + + Por ejemplo, después de una escritura no temporal en la región pmem, + usamos pmem_wmb() para garantizar que los stores hayan alcanzado el + dominio de durabilidad de la plataforma. Esto garantiza que los stores + han actualizado el almacenamiento persistente antes de cualquier + acceso a datos o transferencia de datos causada por instrucciones + posteriores. Esto es además del orden realizado por wmb(). + + Para la carga desde memoria persistente, las barreras de memoria de + lectura existentes son suficientes para garantizar el orden de + lectura. + + (*) io_stop_wc(); + + Para accesos a memoria con atributos de combinación de escritura (por + ejemplo, los devueltos por ioremap_wc(), la CPU puede esperar a que + los accesos anteriores se junten con posteriores. io_stop_wc() se + puede utilizar para evitar la combinación de accesos a memoria de + de escritura antes de esta macro, con los posteriores, cuando dicha + espera tenga implicaciones en el rendimiento. + +========================================= +BARRERAS DE MEMORIA IMPLÍCITAS DEL KERNEL +========================================= + +Algunas de las otras funciones en el kernel Linux implican barreras de +memoria, entre estas encontramos funciones de bloqueo y planificación +("scheduling"). + +Esta especificación es una garantía _mínima_; cualquier arquitectura +particular puede proporcionar garantías más sustanciales, pero no se puede +confiar en estas fuera de código específico de arquitectura. + + +FUNCIONES DE ADQUISICIÓN DE CERROJO +----------------------------------- + +El kernel Linux tiene una serie de abstracciones de bloqueo: + + (*) spin locks (cerrojos en loop) + (*) R/W spin lock (cerrojos de escritura/lectura) + (*) mutex + (*) semáforos + (*) R/W semáforos + +En todos los casos existen variantes de las operaciones "ACQUIRE" y +"RELEASE" para cada uno de ellos. Todas estas operaciones implican ciertas +barreras: + + (1) Implicaciones de la operación ACQUIRE: + + Las operaciones de memoria emitidas después del ACQUIRE se completarán + después de que la operación ACQUIRE haya finalizado. + + Las operaciones de memoria emitidas antes de ACQUIRE pueden + completarse después que la operación ACQUIRE se ha completado. + + (2) Implicaciones de la operación RELEASE: + + Las operaciones de memoria emitidas antes de la RELEASE se + completarán antes de que la operación de RELEASE se haya completado. + + Las operaciones de memoria emitidas después de la RELEASE pueden + completarse antes de que la operación de RELEASE se haya completado. + + (3) Implicación de ACQUIRE vs ACQUIRE: + + Todas las operaciones ACQUIRE emitidas antes de otra operación + ACQUIRE serán completadas antes de esa operación ACQUIRE. + + (4) Implicación de ACQUIRE vs RELEASE: + + Todas las operaciones ACQUIRE emitidas antes de una operación RELEASE + serán completadas antes de la operación RELEASE. + + (5) Implicación de ACQUIRE condicional fallido: + + Ciertas variantes de bloqueo de la operación ACQUIRE pueden fallar, ya + sea debido a no poder obtener el bloqueo de inmediato, o debido a que + recibieron una señal de desbloqueo mientras dormían esperando que el + cerrojo estuviera disponible. Los fallos en cerrojos no implican + ningún tipo de barrera. + +[!] Nota: una de las consecuencias de que los cerrojos en ACQUIRE y RELEASE +sean barreras unidireccionales, es que los efectos de las instrucciones +fuera de una sección crítica pueden filtrarse al interior de la sección +crítica. + +No se puede suponer que un ACQUIRE seguido de una RELEASE sea una barrera +de memoria completa dado que es posible que un acceso anterior a ACQUIRE +suceda después del ACQUIRE, y un acceso posterior a la RELEASE suceda antes +del RELEASE, y los dos accesos puedan entonces cruzarse: + + *A = a; + ACQUIRE M + RELEASE M + *B = b; + +puede ocurrir como: + + ACQUIRE M, STORE *B, STORE *A, RELEASE M + +Cuando ACQUIRE y RELEASE son bloqueo de adquisición y liberación, +respectivamente, este mismo orden puede ocurrir si el cerrojo ACQUIRE y +RELEASE son para la misma variable de bloqueo, pero solo desde la +perspectiva de otra CPU que no tiene ese bloqueo. En resumen, un ACQUIRE +seguido de un RELEASE NO puede entenderse como una barrera de memoria +completa. + +De manera similar, el caso inverso de un RELEASE seguido de un ACQUIRE no +implica una barrera de memoria completa. Por lo tanto, la ejecución de la +CPU de los tramos críticos correspondientes a la RELEASE y la ACQUIRE +pueden cruzarse, de modo que: + + *A = a; + RELEASE M + ACQUIRE N + *B = b; + +puede ocurrir como: + + ACQUIRE N, STORE *B, STORE *A, RELEASE M + +Podría parecer que este nuevo orden podría introducir un punto muerto. +Sin embargo, esto no puede suceder porque si tal punto muerto amenazara +con suceder, el RELEASE simplemente se completaría, evitando así el +interbloqueo ("deadlock", punto muerto). + + ¿Por qué funciona esto? + + Un punto clave es que solo estamos hablando de la CPU re-haciendo el + orden, no el compilador. Si el compilador (o, ya puestos, el + desarrollador) cambió las operaciones, un deadlock -podría- ocurrir. + + Pero supongamos que la CPU reordenó las operaciones. En este caso, el + desbloqueo precede al bloqueo en el código ensamblador. La CPU + simplemente eligió intentar ejecutar primero la última operación de + bloqueo. Si hay un interbloqueo, esta operación de bloqueo simplemente + esperará (o tratará de dormir, pero hablaremos de eso más adelante). La + CPU eventualmente ejecutará la operación de desbloqueo (que precedió a la + operación de bloqueo en el código ensamblador), lo que desenmascará el + potencial punto muerto, permitiendo que la operación de bloqueo tenga + éxito. + + Pero, ¿y si el cerrojo es un cerrojo que duerme ("sleeplock")? En tal + caso, el código intentará entrar al scheduler, donde eventualmente + encontrará una barrera de memoria, que forzará la operación de desbloqueo + anterior para completar, nuevamente desentrañando el punto muerto. Podría + haber una carrera de desbloqueo del sueño ("sleep-unlock race"), pero la + primitiva de bloqueo necesita resolver tales carreras correctamente en + cualquier caso. + +Es posible que los cerrojos y los semáforos no proporcionen ninguna +garantía de orden en sistemas compilados en UP, por lo que no se puede +contar con tal situación para lograr realmente nada en absoluto, +especialmente con respecto a los accesos de E/S, a menos que se combinen +con operaciones de inhabilitación de interrupciones. + +Consulte también la sección "Efectos de barrera adquiriendo intra-CPU". + + +Como ejemplo, considere lo siguiente: + + *A = a; + *B = b; + ACQUIRE + *C = c; + *D = d; + RELEASE + *E = e; + *F = f; + +La siguiente secuencia de eventos es aceptable: + + ACQUIRE, {*F,*A}, *E, {*C,*D}, *B, RELEASE + + [+] Tenga en cuenta que {*F,*A} indica un acceso combinado. + +Pero ninguno de los siguientes lo son: + + {*F,*A}, *B, ACQUIRE, *C, *D, RELEASE, *E + *A, *B, *C, ACQUIRE, *D, RELEASE, *E, *F + *A, *B, ACQUIRE, *C, RELEASE, *D, *E, *F + *B, ACQUIRE, *C, *D, RELEASE, {*F,*A}, *E + + + +FUNCIONES DE DESACTIVACIÓN DE INTERRUPCIONES +-------------------------------------------- + +Las funciones que deshabilitan interrupciones (equivalentes a ACQUIRE) y +habilitan interrupciones (equivalentes a RELEASE) actuarán únicamente como +barrera del compilador. Por consiguiente, si la memoria o la E/S requieren +barreras en tal situación, deben ser provistas por algún otro medio. + + +FUNCIONES DE DORMIR Y DESPERTAR +------------------------------- + +Dormir y despertar son eventos marcados ("flagged") en los datos globales +que se pueden ver como una interacción entre dos piezas de datos: el estado +de la task (hilo, proceso, tarea) que espera el evento y los datos globales +utilizados para indicar el evento. Para asegurarse de que estos parezcan +suceder en el orden correcto, las primitivas para comenzar el proceso de ir +a dormir, y las primitivas para iniciar un despertar implican ciertas +barreras. + +En primer lugar, el agente durmiente normalmente sigue algo similar a esta +secuencia de eventos: + + for (;;) { + set_current_state(TASK_UNINTERRUPTIBLE); + if (evento_indicado) + break; + schedule(); // planificar + } + +Una barrera de memoria general se obtiene automáticamente mediante +set_current_state() después de haber alterado el estado de la tarea: + + CPU 1 + =============================== + set_current_state(); // hacer_estado_actual() + smp_store_mb(); + STORE current->state + <barrera general> + LOAD evento_indicado + +set_current_state() puede estar envuelto por: + + prepare_to_wait(); // preparese_para_esperar(); + prepare_to_wait_exclusive(); // prepararse_para_solo_esperar(); + +que por lo tanto también implican una barrera de memoria general después de +establecer el estado. Toda la secuencia anterior está disponible en varias +formas, todas las cuales obtienen la barrera de memoria en el lugar +correcto: + + wait_event(); + wait_event_interruptible(); + wait_event_interruptible_exclusive(); + wait_event_interruptible_timeout(); + wait_event_killable(); + wait_event_timeout(); + wait_on_bit(); + wait_on_bit_lock(); + + +En segundo lugar, el código que realiza una activación normalmente se +asemeja a algo como esto: + + evento_indicado = 1; + wake_up(&event_wait_queue); // despertar + +o: + + evento_indicado = 1; + wake_up_process(event_daemon); // despertar proceso + +wake_up() ejecuta una barrera de memoria general si despierta algo. Si no +despierta nada, entonces una barrera de memoria puede o no ser ejecutada; +no debe confiar en ello. La barrera se produce antes del acceso al estado +de la tarea. En particular, se encuentra entre el STORE para indicar el +evento y el STORE para configurar TASK_RUNNING (hilo ejecutando): + + CPU 1 (Durmiente) CPU 2 (Despertadora) + =============================== =============================== + set_current_state(); STORE evento_indicado + smp_store_mb(); wake_up(); + STORE current->state ... + <barrera general> <barrera general> + LOAD evento_indicado if ((LOAD task->state) & TASK_NORMAL) + STORE task->state + +donde "task" es el subproceso que se está despertando y es igual al +"current" (hilo actual) de la CPU 1. + +Para reiterar, se garantiza la ejecución de una barrera de memoria general +mediante wake_up() si algo está realmente despierto, pero de lo contrario +no existe tal garantía. Para entender esto, considere la siguiente +secuencia de eventos, donde X e Y son ambos cero inicialmente: + + CPU 1 CPU 2 + =============================== =============================== + X = 1; Y = 1; + smp_mb(); wake_up(); + LOAD Y LOAD X + +Si ocurre una reactivación ("wakeup"), una (al menos) de las dos cargas +debe ver 1. Si, por otro lado, no ocurre una reactivación, ambas cargas +pueden ver 0. + +wake_up_process() siempre ejecuta una barrera de memoria general. La +barrera, de nuevo, ocurre antes de que se acceda al estado del hilo. En +particular, si wake_up(), en el fragmento anterior, fuera reemplazado por +una llamada a wake_up_process(), las dos cargas verían 1, garantizado. + +Las funciones de activación disponibles incluyen: + + complete(); + wake_up(); + wake_up_all(); + wake_up_bit(); + wake_up_interruptible(); + wake_up_interruptible_all(); + wake_up_interruptible_nr(); + wake_up_interruptible_poll(); + wake_up_interruptible_sync(); + wake_up_interruptible_sync_poll(); + wake_up_locked(); + wake_up_locked_poll(); + wake_up_nr(); + wake_up_poll(); + wake_up_process(); + +En términos de orden de la memoria, todas estas funciones proporcionan las +mismas garantías que un wake_up() (o más fuertes). + +[!] Tenga en cuenta que las barreras de la memoria implicadas por el +durmiente y el despierto _no_ ordenan varios stores antes del despertar con +respecto a cargas de los valores guardados después de que el durmiente haya +llamado a set_current_state(). Por ejemplo, si el durmiente hace: + + set_current_state(TASK_INTERRUPTIBLE); + if (evento_indicado) + break; + __set_current_state(TASK_RUNNING); + hacer_algo(my_data); + +y el que despierta hace: + + my_data = valor; + evento_indicado = 1; + wake_up(&event_wait_queue); + +no existe garantía de que el cambio a event_indicated sea percibido por +el durmiente de manera que venga después del cambio a my_data. En tal +circunstancia, el código en ambos lados debe sacar sus propias barreras de +memoria entre los separados accesos a datos. Por lo tanto, el durmiente +anterior debería hacer: + + set_current_state(TASK_INTERRUPTIBLE); + if (evento_indicado) { + smp_rmb(); + hacer_algo(my_data); + } + +y el que despierta debería hacer: + + my_data = value; + smp_wmb(); + evento_indicado = 1; + wake_up(&event_wait_queue); + +FUNCIONES VARIAS +---------------- + +Otras funciones que implican barreras: + + (*) schedule() y similares implican barreras completas de memoria. + + +======================================== +EFECTOS DE BARRERA ADQUIRIENDO INTRA-CPU +======================================== + +En los sistemas SMP, las primitivas de bloqueo proveen una forma más +sustancial de barrera: una que afecta el orden de acceso a la memoria en +otras CPU, dentro del contexto de conflicto en cualquier bloqueo en +particular. + + +ADQUISICIÓN VS ACCESOS A MEMORIA +-------------------------------- + +Considere lo siguiente: el sistema tiene un par de spinlocks (M) y (Q), y +tres CPU; entonces la siguiente secuencia de eventos debería ocurrir: + + CPU 1 CPU 2 + =============================== =============================== + WRITE_ONCE(*A, a); WRITE_ONCE(*E, e); + ACQUIRE M ACQUIRE Q + WRITE_ONCE(*B, b); WRITE_ONCE(*F, f); + WRITE_ONCE(*C, c); WRITE_ONCE(*G, g); + RELEASE M RELEASE Q + WRITE_ONCE(*D, d); WRITE_ONCE(*H, h); + +Entonces no hay garantía sobre en qué orden verá la CPU 3 los accesos a *A +hasta que *H ocurra, además de las restricciones impuestas por los bloqueos +separados en las distintas CPUs. Podría, por ejemplo, ver: + + *E, ACQUIRE M, ACQUIRE Q, *G, *C, *F, *A, *B, RELEASE Q, *D, *H, RELEASE M + +Pero no verá ninguno de: + + *B, *C or *D preceding ACQUIRE M + *A, *B or *C following RELEASE M + *F, *G or *H preceding ACQUIRE Q + *E, *F or *G following RELEASE Q + +======================================== +¿DÓNDE SE NECESITAN BARRERAS DE MEMORIA? +======================================== + +Bajo operación normal, el re-ordenamiento de una operación de memoria +generalmente no va a suponer un problema, ya que para una pieza de código +lineal de un solo subproceso seguirá pareciendo que funciona correctamente, +incluso si está en un kernel SMP. Existen, sin embargo, cuatro +circunstancias en las que reordenar definitivamente _podría_ ser un +problema: + + (*) Interacción entre procesadores. + + (*) Operaciones atómicas. + + (*) Acceso a dispositivos. + + (*) Interrupciones. + + +INTERACCIÓN ENTRE PROCESADORES +------------------------------ + +Cuando se da un sistema con más de un procesador, más de una CPU en el +sistema puede estar trabajando en el mismo conjunto de datos al mismo +tiempo. Esto puede causar problemas de sincronización, y la forma habitual +de tratar con estos es utilizar cerrojos. Sin embargo, los cerrojos son +bastante caros, por lo que puede ser preferible operar sin el uso de un +cerrojo a ser posible. En cuyo caso, es posible que las operaciones que +afectan a ambas CPU deban ordenarse cuidadosamente para evitar un +funcionamiento incorrecto. + +Considere, por ejemplo, la ruta lenta del semáforo R/W. Aquí hay un proceso +de espera en cola del semáforo, en virtud de que tiene una parte de su pila +vinculada a la lista de procesos en espera del semáforo: + + struct rw_semaphore { + ... + spinlock_t lock; + struct list_head waiters; + }; + + struct rwsem_waiter { + struct list_head list; + struct task_struct *task; + }; + +Para despertar a un proceso que espera ("waiter") en particular, las +funciones up_read() o up_write() tienen que: + + (1) leer el siguiente puntero del registro de este proceso que espera, + para saber dónde está el registro del siguiente waiter; + + (2) leer el puntero a la estructura de tareas del waiter; + + (3) borrar el puntero de la tarea para decirle al waiter que se le ha dado + el semáforo; + + (4) llamar a wake_up_process() en la tarea; y + + (5) liberar la referencia retenida en la estructura de tareas del waiter. + +En otras palabras, tiene que realizar esta secuencia de eventos: + + LOAD waiter->list.next; + LOAD waiter->task; + STORE waiter->task; + CALL wakeup + RELEASE task + +y si alguno de estos pasos ocurre fuera de orden, entonces todo puede que +funcione defectuosamente. + +Una vez que se ha puesto en cola y soltado el bloqueo de semáforo, el +proceso que espera no consigue el candado de nuevo; en cambio, solo espera +a que se borre su puntero de tarea antes de continuar. Dado que el registro +está en la pila del proceso que espera, esto significa que si el puntero de +la tarea se borra _antes_ de que se lea el siguiente puntero de la lista, +otra CPU podría comenzar a procesar el proceso que espera y podría romper +el stack del proceso que espera antes de que la función up*() tenga la +oportunidad de leer el puntero que sigue. + +Considere entonces lo que podría suceder con la secuencia de eventos +anterior: + + CPU 1 CPU 2 + =============================== =============================== + down_xxx() + Poner waiter en la "queue" (cola) + Dormir + up_yyy() + LOAD waiter->task; + STORE waiter->task; + Despertado por otro evento + <preempt> + Reanudar el procesamiento + down_xxx() regresa + llamada a foo() + foo() estropea *waiter + </preempt> + LOAD waiter->list.next; + --- OOPS --- + +Esto podría solucionarse usando el bloqueo de semáforo, pero luego la +función down_xxx() tiene que obtener innecesariamente el spinlock +nuevamente, después de ser despertado el hilo. + +La forma de lidiar con esto es insertar una barrera de memoria SMP general: + + LOAD waiter->list.next; + LOAD waiter->task; + smp_mb(); + STORE waiter->task; + CALL wakeup + RELEASE task + +En este caso, la barrera garantiza que todos los accesos a memoria antes de +la barrera parecerán suceder antes de todos los accesos a memoria después +de dicha barrera con respecto a las demás CPU del sistema. _No_ garantiza +que todos los accesos a memoria antes de la barrera se completarán en el +momento en que la instrucción de la barrera en sí se complete. + +En un sistema UP, donde esto no sería un problema, la función smp_mb() es +solo una barrera del compilador, asegurándose así de que el compilador +emita las instrucciones en el orden correcto sin realmente intervenir en la +CPU. Como solo hay un CPU, la lógica de orden de dependencias de esa CPU se +encargará de todo lo demás. + + +OPERACIONES ATÓMICAS +-------------------- + +Si bien son, técnicamente, consideraciones de interacción entre +procesadores, las operaciones atómicas se destacan especialmente porque +algunas de ellas implican barreras de memoria completa y algunas otras no, +pero se confía mucho en ellos en su conjunto a lo largo del kernel. + +Consulte Documentation/atomic_t.txt para obtener más información. + + +ACCESO A DISPOSITIVOS +--------------------- + +Un driver puede ser interrumpido por su propia rutina de servicio de +interrupción y, por lo tanto, las dos partes del driver pueden interferir +con los intentos de controlar o acceder al dispositivo. + +Esto puede aliviarse, al menos en parte, desactivando las interrupciones +locales (una forma de bloqueo), de modo que las operaciones críticas sean +todas contenidas dentro la sección de interrupción desactivada en el +controlador. Mientras la interrupción del driver está ejecutando la rutina, +es posible que el "core" del controlador no se ejecute en la misma CPU y no +se permita que su interrupción vuelva a ocurrir hasta que la interrupción +actual haya sido resuelta, por lo tanto, el controlador de interrupción no +necesita bloquearse contra esto. + +Sin embargo, considere un driver que estaba hablando con una tarjeta +ethernet que tiene un registro de direcciones y un registro de datos. Si +el core de ese controlador habla con la tarjeta estando en desactivación de +interrupción y luego se invoca el controlador de interrupción del +controlador: + + IRQ LOCALES DESACTIVADAS + writew(ADDR, 3); + writew(DATA, y); + IRQ LOCALES ACTIVADAS + <interrupción> + writew(ADDR, 4); + q = readw(DATA); + </interrupción> + +El almacenamiento en el registro de datos puede ocurrir después del segundo +almacenamiento en el registro de direcciones si las reglas de orden son lo +suficientemente relajadas: + + STORE *ADDR = 3, STORE *ADDR = 4, STORE *DATA = y, q = LOAD *DATA + +Si se relajan las reglas de orden, se debe asumir que los accesos +realizados dentro de la sección con interrupción deshabilitada pueden +filtrarse fuera de esta y pueden intercalarse con accesos realizados en una +interrupción - y viceversa - a menos que se utilicenn barreras implícita o +explícitas. + +Normalmente, esto no será un problema porque los accesos de E/S realizados +dentro de tales secciones incluirán operaciones de carga síncronas en +registros E/S estrictamente ordenados, que forman barreras de E/S +implícitas. + + +Una situación similar puede ocurrir entre una rutina de interrupción y dos +rutinas ejecutándose en separadas CPU que se comunican entre sí. Si tal +caso es probable, entonces se deben usar bloqueos de desactivación de +interrupciones para garantizar el orden. + + +===================================== + Efectos de barrera de E/S del kernel +===================================== + +La interfaz con periféricos a través de accesos de E/S es profundamente +específica para cada arquitectura y dispositivo. Por lo tanto, los drivers +que son inherentemente no portátiles pueden depender de comportamientos +específicos de sus sistemas de destino, con el fin de lograr la +sincronización de la manera más ligera posible. Para drivers que deseen ser +portátiles entre múltiples arquitecturas e implementaciones de bus, el +kernel ofrece una serie de funciones de acceso que proporcionan varios +grados de garantías de orden: + + (*) readX(), writeX(): + + Las funciones de acceso MMIO readX() y writeX() usan un puntero al + periférico al que se accede como un parámetro __iomem *. para punteros + asignados los atributos de E/S predeterminados (por ejemplo, los + devueltos por ioremap()), las garantías de orden son las siguientes: + + 1. Se ordenan todos los accesos readX() y writeX() a un mismo periférico + entre estos. Esto asegura que los registros de acceso MMIO por el + mismo subproceso de la CPU a un dispositivo en particular llegarán en + el orden del programa. + + 2. Se ordena un writeX() emitido por un subproceso de CPU que contiene un + spinlock antes de un writeX() al mismo periférico desde otro + subproceso de CPU, si emitido después de una adquisición posterior del + mismo spinlock. Esto garantiza que ese registro MMIO escribe en un + dispositivo en particular, mientras que se obtiene un spinlock en un + orden consistente con las adquisiciones del cerrojo. + + 3. Un writeX() por un subproceso de la CPU al periférico primero esperará + a la finalización de todas las escrituras anteriores en la memoria + emitidas por, o bien propagadas por, el mismo subproceso. Esto asegura + que las escrituras de la CPU a un búfer DMA de salida asignadas por + dma_alloc_coherent() serán visibles para un motor ("engine") DMA + cuando la CPU escriba en sus registros de control MMIO, para activar + la transferencia. + + 4. Un readX() de un subproceso del CPU, desde el periférico, se + completará antes de que cualquier lectura subsiguiente de memoria por + el mismo subproceso pueda comenzar. Esto asegura que las lecturas de + la CPU desde un búfer DMA entrantes asignadas por + dma_alloc_coherent(), no verán datos obsoletos después de leer el + registro de estado MMIO del motor DMA, para establecer que la + transferencia DMA se haya completado. + + 5. Un readX() por un subproceso del CPU, desde el periférico, se + completará antes de que cualquier bucle delay() subsiguiente pueda + comenzar a ejecutarse en el mismo subproceso. Esto asegura que dos + escrituras del CPU a registros MMIO en un periférico llegarán al menos + con 1us de diferencia, si la primera escritura se lee inmediatamente + de vuelta con readX() y se llama a udelay(1) antes del segundo + writeX(): + + writel(42, DEVICE_REGISTER_0); // Llega al dispositivo ... + readl(DEVICE_REGISTER_0); + udelay(1); + writel(42, DEVICE_REGISTER_1); // al menos 1us antes de esto.... + +Las propiedades de orden de los punteros __iomem obtenidos con valores de +atributos que no sean los valores por defecto (por ejemplo, los devueltos +por ioremap_wc()) son específicos de la arquitectura subyacente y, por lo +tanto, las garantías enumeradas anteriormente no pueden por lo general ser +aseguradas para accesos a este tipo de "mappings" (asignaciones). + + (*) readX_relaxed(), writeX_relaxed(): + + Son similares a readX() y writeX(), pero proporcionan una garantía de + orden de memoria más débil. Específicamente, no garantizan orden con + respecto al bloqueo, los accesos normales a la memoria o los bucles + delay() (es decir, los puntos 2-5 arriba) pero todavía se garantiza que + se ordenarán con respecto a otros accesos desde el mismo hilo de la CPU, + al mismo periférico, cuando se opera en punteros __iomem asignados con el + valor predeterminado para los atributos de E/S. + + (*) readsX(), writesX(): + + Los puntos de entrada readsX() y writesX() MMIO están diseñados para + acceder FIFOs mapeados en memoria y basados en registros que residen en + periféricos, que no son capaces de realizar DMA. Por tanto, sólo + proporcionan garantías de orden readX_relaxed() y writeX_relaxed(), como + se documentó anteriormente. + + (*) inX(), outX(): + + Los puntos de entrada inX() y outX() están destinados a acceder a mapas + de puertos "legacy" (antiguos) de periféricos de E/S, que pueden requerir + instrucciones especiales en algunas arquitecturas (especialmente, en + x86). El número de puerto del periférico que se está accedido se pasa + como un argumento. + + Dado que muchas arquitecturas de CPU acceden finalmente a estos + periféricos a través de un mapeo interno de memoria virtual, las + garantías de orden portátiles proporcionadas por inX() y outX() son las + mismas que las proporcionadas por readX() y writeX(), respectivamente, al + acceder a una asignación con los valores de atributos de E/S + predeterminados (los que haya por defecto). + + Los drivers de dispositivos pueden esperar que outX() emita una + transacción de escritura no publicada, que espera una respuesta de + finalización del periférico de E/S antes de regresar. Esto no está + garantizado por todas las arquitecturas y por lo tanto no forma parte de + la semántica de orden portátil. + + (*) insX(), outsX(): + + Como arriba, los puntos de entrada insX() y outsX() proporcionan el mismo + orden garantizado por readsX() y writesX() respectivamente, al acceder a + un mapping con los atributos de E/S predeterminados. + + (*) ioreadX(), iowriteX(): + + Estos funcionarán adecuadamente para el tipo de acceso que realmente están + haciendo, ya sea inX()/outX() o readX()/writeX(). + +Con la excepción de los puntos de entrada (insX(), outsX(), readsX() y +writesX()), todo lo anterior supone que el periférico subyacente es +little-endian y, por lo tanto, realizará operaciones de intercambio de +bytes en arquitecturas big-endian. + + +=========================================== +MODELO DE ORDEN MÍNIMO DE EJECUCIÓN ASUMIDO +=========================================== + +Debe suponerse que la CPU conceptual está débilmente ordenada, pero que +mantiene la apariencia de causalidad del programa con respecto a sí misma. +Algunas CPU (como i386 o x86_64) están más limitadas que otras (como +powerpc o frv), por lo que el caso más relajado (es decir, DEC Alpha) se +debe asumir fuera de código específico de arquitectura. + +Esto significa que se debe considerar que la CPU ejecutará su flujo de +instrucciones en el orden que se quiera - o incluso en paralelo - siempre +que si una instrucción en el flujo depende de una instrucción anterior, +entonces dicha instrucción anterior debe ser lo suficientemente completa[*] +antes de que la posterior instrucción puede proceder; en otras palabras: +siempre que la apariencia de causalidad se mantenga. + + [*] Algunas instrucciones tienen más de un efecto, como cambiar el + código de condición, cambio de registros o cambio de memoria - y + distintas instrucciones pueden depender de diferentes efectos. + +Una CPU puede también descartar cualquier secuencia de instrucciones que +termine sin tener efecto final. Por ejemplo, si dos instrucciones +adyacentes cargan un valor inmediato en el mismo registro, la primera puede +descartarse. + + +De manera similar, se debe suponer que el compilador podría reordenar la +corriente de instrucciones de la manera que crea conveniente, nuevamente +siempre que la apariencia de causalidad se mantenga. + + +===================================== +EFECTOS DE LA MEMORIA CACHÉ DE LA CPU +===================================== + +La forma en que se perciben las operaciones de memoria caché en todo el +sistema se ve afectada, hasta cierto punto, por los cachés que se +encuentran entre las CPU y la memoria, y por el sistema de coherencia en +memoria que mantiene la consistencia de estado en el sistema. + +En cuanto a la forma en que una CPU interactúa con otra parte del sistema a +través del caché, el sistema de memoria tiene que incluir los cachés de la +CPU y barreras de memoria, que en su mayor parte actúan en la interfaz +entre la CPU y su caché (las barreras de memoria lógicamente actúan sobre +la línea de puntos en el siguiente diagrama): + + <--- CPU ---> : <----------- Memoria -----------> + : + +--------+ +--------+ : +--------+ +-----------+ + | Core | | Cola | : | Cache | | | +---------+ + | CPU | | de | : | CPU | | | | | + | |--->| acceso |----->| |<-->| | | | + | | | a | : | | | |--->| Memoria | + | | | memoria| : | | | | | | + +--------+ +--------+ : +--------+ | Mecanismo | | | + : | de | +---------+ + : | Coherencia| + : | de la | +--------+ + +--------+ +--------+ : +--------+ | cache | | | + | Core | | Cola | : | Cache | | | | | + | CPU | | de | : | CPU | | |--->| Dispos | + | |--->| acceso |----->| |<-->| | | itivo | + | | | a | : | | | | | | + | | | memoria| : | | | | +--------+ + +--------+ +--------+ : +--------+ +-----------+ + : + : + +Aunque es posible que una carga o store en particular no aparezca fuera de +la CPU que lo emitió, ya que puede haber sido satisfecha dentro del propio +caché de la CPU, seguirá pareciendo como si el acceso total a la memoria +hubiera tenido lugar para las otras CPUs, ya que los mecanismos de +coherencia de caché migrarán la cacheline sobre la CPU que accede y se +propagarán los efectos en caso de conflicto. + +El núcleo de la CPU puede ejecutar instrucciones en el orden que considere +adecuado, siempre que parezca mantenerse la causalidad esperada del +programa. Algunas de las instrucciones generan operaciones de carga y +almacenamiento que luego van a la cola de accesos a memoria a realizar. El +núcleo puede colocarlos en la cola en cualquier orden que desee, y +continuar su ejecución hasta que se vea obligado a esperar que una +instrucción sea completada. + +De lo que se ocupan las barreras de la memoria es de controlar el orden en +que los accesos cruzan, desde el lado de la CPU, hasta el lado de memoria, +y el orden en que los otros observadores perciben los efectos en el sistema +que sucedan por esto. + +[!] Las barreras de memoria _no_ son necesarias dentro de una CPU +determinada, ya que las CPU siempre ven sus propias cargas y stores como si +hubieran sucedido en el orden del programa. + +[!] Los accesos a MMIO u otros dispositivos pueden pasar por alto el +sistema de caché. Esto depende de las propiedades de la ventana de memoria +a través de la cual se accede a los dispositivos y/o el uso de +instrucciones especiales de comunicación con dispositivo que pueda tener la +CPU. + + +COHERENCIA DE CACHÉ FRENTE A DMA +--------------------------------- + +No todos los sistemas mantienen coherencia de caché con respecto a los +dispositivos que realizan DMA. En tales casos, un dispositivo que intente +DMA puede obtener datos obsoletos de la RAM, porque las líneas de caché +"sucias" pueden residir en los cachés de varias CPU, y es posible que no +se hayan vuelto a escribir en la RAM todavía. Para hacer frente a esto, la +parte apropiada del kernel debe vaciar los bits superpuestos de caché en +cada CPU (y tal vez también invalidarlos). + +Además, los datos enviados por DMA a RAM, por un dispositivo, pueden ser +sobrescritos por líneas de caché sucias que se escriben de nuevo en la RAM +desde el caché de una CPU, después de que el dispositivo haya puesto sus +propios datos, o las líneas de caché presentes en el caché de la CPU pueden +simplemente ocultar el hecho de que la memoria RAM se haya actualizado, +hasta el momento en que la caché se descarta de la memoria caché de la CPU +y se vuelve a cargar. Para hacer frente a esto, la parte apropiada del +kernel debe invalidar los bits superpuestos del caché en cada CPU. + +Consulte Documentation/core-api/cachetlb.rst para obtener más información +sobre administración de la memoria caché. + + +COHERENCIA DE CACHÉ FRENTE A MMIO +--------------------------------- + +La E/S mapeada en memoria generalmente se lleva a cabo a través de +ubicaciones de memoria que forman parte de una ventana del espacio de +memoria de la CPU, que tiene diferentes propiedades asignadas que la +ventana habitual dirigida a RAM. + +Entre dichas propiedades, suele existir el hecho de que tales accesos +eluden el almacenamiento en caché por completo e ir directamente a los +buses del dispositivo. Esto significa que los accesos MMIO pueden, en +efecto, superar los accesos a la memoria caché que se emitieron +anteriormente. Una barrera de memoria no es suficiente en tal caso, sino +que el caché debe ser vaciado entre la escritura de la memoria caché, y el +acceso MMIO, si los dos son de cualquier manera dependiente. + + +======================= +COSAS QUE HACEN LAS CPU +======================= + +Un programador podría dar por sentado que la CPU realizará las operaciones +de memoria exactamente en el orden especificado, de modo que si a la CPU se +entrega, por ejemplo, el siguiente fragmento de código a ejecutar: + + a = READ_ONCE(*A); + WRITE_ONCE(*B, b); + c = READ_ONCE(*C); + d = READ_ONCE(*D); + WRITE_ONCE(*E, e); + +esperarían entonces que la CPU complete la operación de memoria para cada +instrucción antes de pasar a la siguiente, lo que lleva a una definida +secuencia de operaciones vistas por observadores externos en el sistema: + + LOAD *A, STORE *B, LOAD *C, LOAD *D, STORE *E. + +La realidad es, por supuesto, mucho más intrincada. Para muchas CPU y +compiladores, la anterior suposición no se sostiene porque: + + (*) es más probable que las cargas deban completarse de inmediato para + permitir progreso en la ejecución, mientras que los stores a menudo se + pueden aplazar sin problema; + + (*) las cargas se pueden hacer especulativamente, y el resultado es + descartado si resulta innecesario; + + (*) las cargas se pueden hacer de forma especulativa, lo que lleva a que + se haya obtenido el resultado en el momento equivocado de la secuencia + de eventos esperada; + + (*) el orden de los accesos a memoria se puede reorganizar para promover + un mejor uso de los buses y cachés de la CPU; + + (*) las cargas y los stores se pueden combinar para mejorar el rendimiento + cuando se habla con memoria o hardware de E/S, que puede realizar + accesos por lotes a ubicaciones adyacentes, reduciendo así los costes + de configuración de transacciones (la memoria y los dispositivos PCI + pueden ambos pueden hacer esto); y + + (*) la caché de datos de la CPU puede afectar al orden, y mientras sus + mecanismos de coherencia pueden aliviar esto, una vez que el store + haya accedido al caché- no hay garantía de que la gestión de la + coherencia se propague en orden a otras CPU. + +Entonces, digamos que lo que otra CPU podría observar en el fragmento de +código anterior es: + + LOAD *A, ..., LOAD {*C,*D}, STORE *E, STORE *B + + (Donde "LOAD {*C,*D}" es una carga combinada) + + +Sin embargo, se garantiza que una CPU es autoconsistente: verá que sus + _propios_ accesos parecen estar correctamente ordenados, sin necesidad de +barrera de memoria. Por ejemplo con el siguiente código: + + U = READ_ONCE(*A); + WRITE_ONCE(*A, V); + WRITE_ONCE(*A, W); + X = READ_ONCE(*A); + WRITE_ONCE(*A, Y); + Z = READ_ONCE(*A); + +y asumiendo que no hay intervención de una influencia externa, se puede +suponer que el resultado final se parecerá a: + + U == el valor original de *A + X == W + Z == Y + *A == Y + +El código anterior puede hacer que la CPU genere la secuencia completa de +accesos de memoria: + + U=LOAD *A, STORE *A=V, STORE *A=W, X=LOAD *A, STORE *A=Y, Z=LOAD *A + +en ese orden, pero, sin intervención, la secuencia puede contener casi +cualquier combinación de elementos combinados o descartados, siempre que la +perspectiva del programa del mundo siga siendo consistente. Tenga en cuenta +que READ_ONCE() y WRITE_ONCE() -no- son opcionales en el ejemplo anterior, +ya que hay arquitecturas donde una CPU determinada podría reordenar cargas +sucesivas en la misma ubicación. En tales arquitecturas, READ_ONCE() y +WRITE_ONCE() hacen lo que sea necesario para evitar esto, por ejemplo, en +Itanium los casts volátiles utilizados por READ_ONCE() y WRITE_ONCE() hacen +que GCC emita las instrucciones especiales ld.acq y st.rel +(respectivamente) que impiden dicha reordenación. + +El compilador también puede combinar, descartar o diferir elementos de la +secuencia antes incluso de que la CPU los vea. + +Por ejemplo: + + *A = V; + *A = W; + +puede reducirse a: + + *A = W; + +ya que, sin una barrera de escritura o WRITE_ONCE(), puede que se asuma +que el efecto del almacenamiento de V a *A se pierde. Similarmente: + + *A = Y; + Z = *A; + +puede, sin una barrera de memoria o un READ_ONCE() y WRITE_ONCE(), esto +sea reducido a: + + *A = Y; + Z = Y; + +y la operación LOAD nunca aparezca fuera de la CPU. + + +Y LUEGO ESTÁ EL ALFA +-------------------- + +La CPU DEC Alpha es una de las CPU más relajadas que existen. No solo eso, +algunas versiones de la CPU Alpha tienen un caché de datos dividido, lo que +les permite tener dos líneas de caché relacionadas semánticamente, +actualizadas en momentos separados. Aquí es donde la barrera de dependencia +de dirección realmente se vuelve necesaria, ya que se sincronizan ambos +cachés con el sistema de coherencia de memoria, lo que hace que parezca un +cambio en el puntero, frente a que los nuevos datos se produzcan en el +orden correcto. + +Alpha define el modelo de memoria del kernel Linux, aunque a partir de +v4.15, la adición al kernel de Linux de smp_mb() a READ_ONCE() en Alpha +redujo en gran medida su impacto en el modelo de memoria. + + +GUESTS DE MÁQUINAS VIRTUALES +----------------------------- + +Los "guests" (invitados) que se ejecutan en máquinas virtuales pueden verse +afectados por los efectos de SMP incluso si el "host" (huésped) en sí se +compila sin compatibilidad con SMP. Este es un efecto de la interacción con +un host SMP mientras ejecuta un kernel UP. El uso obligatorio de barreras +para este caso de uso sería posible, pero a menudo no son óptimas. + +Para hacer frente a este caso de manera óptima, están disponibles macros de +bajo nivel virt_mb() etc. Estas tienen el mismo efecto que smp_mb(), etc. +cuando SMP está habilitado, pero generan código idéntico para sistemas SMP +y no SMP. Por ejemplo, los invitados de máquinas virtuales debería usar +virt_mb() en lugar de smp_mb() al sincronizar contra un (posiblemente SMP) +anfitrión. + +Estos son equivalentes a sus contrapartes smp_mb() etc. en todos los demás +aspectos, en particular, no controlan los efectos MMIO: para controlar los +efectos MMIO, utilice barreras obligatorias. + + +================ +EJEMPLOS DE USOS +================ + +BUFFERS CIRCULARES +------------------ + +Las barreras de memoria se pueden utilizar para implementar almacenamiento +en búfer circular, sin necesidad de un cerrojo para serializar al productor +con el consumidor. Vea: + + Documentation/core-api/circular-buffers.rst + +para más detalles. + + +=========== +REFERENCIAS +=========== + +Alpha AXP Architecture Reference Manual, Segunda Edición (por Sites & Witek, +Digital Press) + Capítulo 5.2: Physical Address Space Characteristics + Capítulo 5.4: Caches and Write Buffers + Capítulo 5.5: Data Sharing + Capítulo 5.6: Read/Write Ordering + +AMD64 Architecture Programmer's Manual Volumen 2: System Programming + Capítulo 7.1: Memory-Access Ordering + Capítulo 7.4: Buffering and Combining Memory Writes + +ARM Architecture Reference Manual (ARMv8, for ARMv8-A architecture profile) + Capítulo B2: The AArch64 Application Level Memory Model + +IA-32 Intel Architecture Software Developer's Manual, Volumen 3: +System Programming Guide + Capítulo 7.1: Locked Atomic Operations + Capítulo 7.2: Memory Ordering + Capítulo 7.4: Serializing Instructions + +The SPARC Architecture Manual, Version 9 + Capítulo 8: Memory Models + Appendix D: Formal Specification of the Memory Models + Appendix J: Programming with the Memory Models + +Storage in the PowerPC (por Stone and Fitzgerald) + +UltraSPARC Programmer Reference Manual + Capítulo 5: Memory Accesses and Cacheability + Capítulo 15: Sparc-V9 Memory Models + +UltraSPARC III Cu User's Manual + Capítulo 9: Memory Models + +UltraSPARC IIIi Processor User's Manual + Capítulo 8: Memory Models + +UltraSPARC Architecture 2005 + Capítulo 9: Memory + Appendix D: Formal Specifications of the Memory Models + +UltraSPARC T1 Supplement to the UltraSPARC Architecture 2005 + Capítulo 8: Memory Models + Appendix F: Caches and Cache Coherency + +Solaris Internals, Core Kernel Architecture, p63-68: + Capítulo 3.3: Hardware Considerations for Locks and + Synchronization + +Unix Systems for Modern Architectures, Symmetric Multiprocessing and Caching +for Kernel Programmers: + Capítulo 13: Other Memory Models + +Intel Itanium Architecture Software Developer's Manual: Volumen 1: + Sección 2.6: Speculation + Sección 4.4: Memory Access diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst new file mode 100644 index 000000000000..a0261ba5b902 --- /dev/null +++ b/Documentation/translations/sp_SP/process/coding-style.rst @@ -0,0 +1,1315 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/coding-style.rst <submittingpatches>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_codingstyle: + +Estilo en el código del kernel Linux +===================================== + +Este es un breve documento que describe el estilo preferido en el código +del kernel Linux. El estilo de código es muy personal y no **forzaré** mi +puntos de vista sobre nadie, pero esto vale para todo lo que tengo que +mantener, y preferiría que para la mayoría de otras cosas también. Por +favor, por lo menos considere los argumentos expuestos aquí. + +En primer lugar, sugeriría imprimir una copia de los estándares de código +GNU, y NO leerlo. Quémelos, es un gran gesto simbólico. + +De todos modos, aquí va: + + +1) Sangría +----------- + +Las tabulaciones tienen 8 caracteres y, por lo tanto, las sangrías también +tienen 8 caracteres. Hay movimientos heréticos que intentan hacer sangría +de 4 (¡o incluso 2!) caracteres de longitud, y eso es similar a tratar de +definir el valor de PI como 3. + +Justificación: La idea detrás de la sangría es definir claramente dónde +comienza y termina un bloque de control. Especialmente, cuando ha estado +buscando en su pantalla durante 20 horas seguidas, le resultará mucho más +fácil ver cómo funciona la sangría si tiene sangrías grandes. + +Bueno, algunas personas dirán que tener sangrías de 8 caracteres hace que +el código se mueva demasiado a la derecha y dificulta la lectura en una +pantalla de terminal de 80 caracteres. La respuesta a eso es que si +necesita más de 3 niveles de sangría, está en apuros de todos modos y +debería arreglar su programa. + +En resumen, las sangrías de 8 caracteres facilitan la lectura y tienen la +ventaja añadida de advertirle cuando está anidando sus funciones demasiado +profundo. Preste atención a esa advertencia. + +La forma preferida de facilitar múltiples niveles de sangría en una +declaración de switch es para alinear el ``switch`` y sus etiquetas +``case`` subordinadas en la misma columna, en lugar de hacer ``doble +sangría`` (``double-indenting``) en etiquetas ``case``. Por ejemplo: + +.. code-block:: c + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + fallthrough; + default: + break; + } + +No ponga varias declaraciones en una sola línea a menos que tenga algo que +ocultar: + +.. code-block:: c + + if (condición) haz_esto; + haz_otra_cosa; + +No use comas para evitar el uso de llaves: + +.. code-block:: c + + if (condición) + haz_esto(), haz_eso(); + +Siempre use llaves para múltiples declaraciones: + +.. code-block:: c + + if (condición) { + haz_esto(); + haz_eso(); + } + +Tampoco ponga varias asignaciones en una sola línea. El estilo de código +del kernel es súper simple. Evite las expresiones engañosas. + + +Aparte de los comentarios, la documentación y excepto en Kconfig, los +espacios nunca se utilizan para la sangría, y el ejemplo anterior se rompe +deliberadamente. + +Consiga un editor decente y no deje espacios en blanco al final de las +líneas. + +2) Rompiendo líneas y strings largos +------------------------------------ + +El estilo de código tiene todo que ver con la legibilidad y la +mantenibilidad usando herramientas disponibles comúnmente. + +El límite preferido en la longitud de una sola línea es de 80 columnas. + +Las declaraciones de más de 80 columnas deben dividirse en partes, a menos +que exceder las 80 columnas aumente significativamente la legibilidad y no +oculte información. + +Los descendientes siempre son sustancialmente más cortos que el padre y +se colocan sustancialmente a la derecha. Un estilo muy usado es alinear +descendientes a un paréntesis de función abierto. + +Estas mismas reglas se aplican a los encabezados de funciones con una larga +lista de argumentos. + +Sin embargo, nunca rompa los strings visibles para el usuario, como los +mensajes printk, porque eso rompe la capacidad de grep a estos. + + +3) Colocación de llaves y espacios +---------------------------------- + +El otro problema que siempre surge en el estilo C es la colocación de +llaves. A diferencia del tamaño de la sangría, existen pocas razones +técnicas para elegir una estrategia de ubicación sobre la otra, pero la +forma preferida, como mostraron los profetas Kernighan y Ritchie, es poner +la llave de apertura en la línea, y colocar la llave de cierre primero, +así: + +.. code-block:: c + + if (x es verdad) { + hacemos y + } + +Esto se aplica a todos los bloques de declaraciones que no son funciones +(if, switch, for, while, do). Por ejemplo: + +.. code-block:: c + + switch (action) { + case KOBJ_ADD: + return "add"; + case KOBJ_REMOVE: + return "remove"; + case KOBJ_CHANGE: + return "change"; + default: + return NULL; + } + +Sin embargo, hay un caso especial, a saber, las funciones: tienen la llave +de apertura al comienzo de la siguiente línea, así: + +.. code-block:: c + + int funcion(int x) + { + cuerpo de la función + } + +Gente hereje de todo el mundo ha afirmado que esta inconsistencia es... +bueno... inconsistente, pero todas las personas sensatas saben que +(a) K&R tienen **razón** y (b) K&R tienen razón. Además, las funciones son +especiales de todos modos (no puede anidarlas en C). + +Tenga en cuenta que la llave de cierre está vacía en su línea propia, +**excepto** en los casos en que es seguida por una continuación de la misma +declaración, es decir, un ``while`` en una sentencia do o un ``else`` en +una sentencia if, como en: + +.. code-block:: c + + do { + cuerpo del bucle do + } while (condition); + +y + +.. code-block:: c + + if (x == y) { + .. + } else if (x > y) { + ... + } else { + .... + } + +Justificación: K&R. + +Además, tenga en cuenta que esta colocación de llaves también minimiza el +número de líneas vacías (o casi vacías), sin pérdida de legibilidad. Así, +como el suministro de nuevas líneas en su pantalla no es un recurso +renovable (piense en pantallas de terminal de 25 líneas), tienes más líneas +vacías para poner comentarios. + +No use llaves innecesariamente donde una sola declaración sea suficiente. + +.. code-block:: c + + if (condition) + accion(); + +y + +.. code-block:: none + + if (condición) + haz_esto(); + else + haz_eso(); + +Esto no aplica si solo una rama de una declaración condicional es una sola +declaración; en este último caso utilice llaves en ambas ramas: + +.. code-block:: c + + if (condición) { + haz_esto(); + haz_eso(); + } else { + en_otro_caso(); + } + +Además, use llaves cuando un bucle contenga más de una declaración simple: + +.. code-block:: c + + while (condición) { + if (test) + haz_eso(); + } + +3.1) Espacios +************* + +El estilo del kernel Linux para el uso de espacios depende (principalmente) +del uso de función versus uso de palabra clave. Utilice un espacio después +de (la mayoría de) las palabras clave. Las excepciones notables son sizeof, +typeof, alignof y __attribute__, que parecen algo así como funciones (y +generalmente se usan con paréntesis en Linux, aunque no son requeridos en +el idioma, como en: ``sizeof info`` después de que ``struct fileinfo info;`` +se declare). + +Así que use un espacio después de estas palabras clave:: + + if, switch, case, for, do, while + +pero no con sizeof, typeof, alignof, o __attribute__. Por ejemplo, + +.. code-block:: c + + + s = sizeof(struct file); + +No agregue espacios alrededor (dentro) de expresiones entre paréntesis. +Este ejemplo es **malo**: + +.. code-block:: c + + + s = sizeof( struct file ); + +Al declarar datos de puntero o una función que devuelve un tipo de puntero, +el uso preferido de ``*`` es adyacente al nombre del dato o nombre de la +función y no junto al nombre del tipo. Ejemplos: + +.. code-block:: c + + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + +Use un espacio alrededor (a cada lado de) la mayoría de los operadores +binarios y ternarios, como cualquiera de estos:: + + = + - < > * / % | & ^ <= >= == != ? : + +pero sin espacio después de los operadores unarios:: + + & * + - ~ ! sizeof typeof alignof __attribute__ defined + +sin espacio antes de los operadores unarios de incremento y decremento del +sufijo:: + + ++ -- + +y sin espacio alrededor de los operadores de miembros de estructura ``.`` y +``->``. + +No deje espacios en blanco al final de las líneas. Algunos editores con +``inteligente`` sangría insertarán espacios en blanco al comienzo de las +nuevas líneas como sea apropiado, para que pueda comenzar a escribir la +siguiente línea de código de inmediato. Sin embargo, algunos de estos +editores no eliminan los espacios en blanco si finalmente no termina +poniendo una línea de código allí, como si dejara una línea en blanco. Como +resultado, termina con líneas que contienen espacios en blanco al final. + +Git le advertirá sobre los parches que introducen espacios en blanco al +final y puede, opcionalmente, eliminar los espacios en blanco finales por +usted; sin embargo, si se aplica una serie de parches, esto puede hacer que +los parches posteriores de la serie fallen al cambiar sus líneas de +contexto. + + +4) Nomenclatura +--------------- + +C es un lenguaje espartano, y sus convenciones de nomenclatura deberían +seguir su ejemplo. A diferencia de los programadores de Modula-2 y Pascal, +los programadores de C no usan nombres cuquis como +EstaVariableEsUnContadorTemporal. Un programador de C lo llamaría +variable ``tmp``, que es mucho más fácil de escribir, y no es mas difícil +de comprender. + +SIN EMBARGO, mientras que los nombres de mayúsculas y minúsculas están mal +vistos, los nombres descriptivos para las variables globales son +imprescindibles. Llamar a una función global ``foo`` es un delito. + +Una variable GLOBAL (para usar solo si **realmente** las necesita) necesita +tener un nombre descriptivo, al igual que las funciones globales. Si tiene +una función que cuenta el número de usuarios activos, debe llamar a esta +``contar_usuarios_activos()`` o similar, **no** debe llamarlo ``cntusr()``. + +Codificar el tipo de una función en el nombre (lo llamado notación húngara) +es estúpido: el compilador conoce los tipos de todos modos y puede +verificar estos, y solo confunde al programador. + +Los nombres de las variables LOCALES deben ser breves y directos. Si usted +tiene algún contador aleatorio de tipo entero, probablemente debería +llamarse ``i``. Llamarlo ``loop_counter`` no es productivo, si no hay +posibilidad de ser mal entendido. De manera similar, ``tmp`` puede ser casi +cualquier tipo de variable que se utiliza para contener un valor temporal. + +Si tiene miedo de mezclar los nombres de las variables locales, tiene otro +problema, que se denomina síndrome de +función-crecimiento-desequilibrio-de-hormona. Vea el capítulo 6 (Funciones). + +Para nombres de símbolos y documentación, evite introducir nuevos usos de +'master / slave' (maestro / esclavo) (o 'slave' independientemente de +'master') y 'lista negra / lista blanca' (backlist / whitelist). + +Los reemplazos recomendados para 'maestro / esclavo' son: + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader / follower' + 'director / performer' + +Los reemplazos recomendados para 'backlist / whitelist' son: + 'denylist / allowlist' + 'blocklist / passlist' + +Las excepciones para la introducción de nuevos usos son mantener en espacio +de usuario una ABI/API, o al actualizar la especificación del código de un +hardware o protocolo existente (a partir de 2020) que requiere esos +términos. Para nuevas especificaciones, traduzca el uso de la terminología +de la especificación al estándar de código del kernel donde sea posible. + +5) Typedefs +----------- + +Por favor no use cosas como ``vps_t``. +Es un **error** usar typedef para estructuras y punteros. cuando ve un + +.. code-block:: c + + + vps_t a; + +en el código fuente, ¿qué significa? +En cambio, si dice + +.. code-block:: c + + struct virtual_container *a; + +puede decir qué es ``a`` en realidad. + +Mucha gente piensa que los typedefs ``ayudan a la legibilidad``. No. Son +útiles solamente para: + + (a) objetos totalmente opacos (donde el typedef se usa activamente para + **ocultar** cuál es el objeto). + + Ejemplo: ``pte_t`` etc. objetos opacos a los que solo puede acceder + usando las funciones de acceso adecuadas. + + .. note:: + + La opacidad y las ``funciones de acceso`` no son buenas por sí + mismas. La razón por la que los tenemos para cosas como pte_t, etc. + es que hay real y absolutamente **cero** información accesible de + forma portátil allí. + + (b) Tipos enteros claros, donde la abstracción **ayuda** a evitar + confusiones, ya sea ``int`` o ``long``. + + u8/u16/u32 son definiciones tipográficas perfectamente correctas + aunque encajan en la categoría (d) mejor que aquí. + + .. note:: + + De nuevo - debe haber una **razón** para esto. si algo es + ``unsigned long``, entonces no hay razón para hacerlo + + typedef unsigned long mis_flags_t; + + pero si hay una razón clara de por qué bajo ciertas circunstancias + podría ser un ``unsigned int`` y bajo otras configuraciones podría + ser ``unsigned long``, entonces, sin duda, adelante y use un typedef. + + (c) cuando lo use para crear literalmente un tipo **nuevo** para + comprobación de tipos. + + (d) Nuevos tipos que son idénticos a los tipos estándar C99, en ciertas + circunstancias excepcionales. + + Aunque sólo costaría un corto período de tiempo para los ojos y + cerebro para acostumbrarse a los tipos estándar como ``uint32_t``, + algunas personas se oponen a su uso de todos modos. + + Por lo tanto, los tipos ``u8/u16/u32/u64`` específicos de Linux y sus + equivalentes con signo, que son idénticos a los tipos estándar son + permitidos, aunque no son obligatorios en el nuevo código de su + elección. + + Al editar código existente que ya usa uno u otro conjunto de tipos, + debe ajustarse a las opciones existentes en ese código. + + (e) Tipos seguros para usar en el espacio de usuario. + + En ciertas estructuras que son visibles para el espacio de usuario, no + podemos requerir tipos C99 y o utilizat el ``u32`` anterior. Por lo + tanto, usamos __u32 y tipos similares en todas las estructuras que se + comparten con espacio de usuario. + +Tal vez también haya otros casos, pero la regla básicamente debería ser +NUNCA JAMÁS use un typedef a menos que pueda coincidir claramente con una +de estas reglas. + +En general, un puntero o una estructura que tiene elementos que pueden +ser razonablemente accedidos directamente, **nunca** deben ser un typedef. + +6) Funciones +------------ + +Las funciones deben ser cortas y dulces, y hacer una sola cosa. Deberían +caber en una o dos pantallas de texto (el tamaño de pantalla ISO/ANSI es +80x24, como todos sabemos), y hacer una cosa y hacerla bien. + +La longitud máxima de una función es inversamente proporcional a la +complejidad y el nivel de sangría de esa función. Entonces, si tiene una +función conceptualmente simple que es solo una larga (pero simple) +declaración de case, donde tiene que hacer un montón de pequeñas cosas para +un montón de diferentes casos, está bien tener una función más larga. + +Sin embargo, si tiene una función compleja y sospecha que un estudiante de +primer año de secundaria menos que dotado podría no comprender de qué se +trata la función, debe adherirse a los límites máximos tanto más de +cerca. Use funciones auxiliares con nombres descriptivos (puede pedirle al +compilador que los alinee si cree que es crítico para el rendimiento, y +probablemente lo hará mejor de lo que usted hubiera hecho). + +Otra medida de la función es el número de variables locales. Estas no deben +exceder de 5 a 10, o está haciendo algo mal. Piense de nuevo en la función +y divida en partes más pequeñas. Un cerebro humano puede generalmente +realiza un seguimiento de aproximadamente 7 cosas diferentes, cualquier +elemento más y se confunde. Usted sabe que es brillante, pero tal vez le +gustaría entender lo que hizo dentro de 2 semanas. + +En los archivos fuente, separe las funciones con una línea en blanco. Si la +función es exportada, la macro **EXPORT** debería ponerse inmediatamente +después de la función de cierre de línea de llave. Por ejemplo: + +.. code-block:: c + + int sistema_corriendo(void) + { + return estado_sistema == SISTEMA_CORRIENDO; + } + EXPORT_SYMBOL(sistema_corriendo); + +6.1) Prototipos de funciones +**************************** + +En los prototipos de funciones, incluya nombres de parámetros con sus tipos +de datos. Aunque esto no es requerido por el lenguaje C, se prefiere en +Linux porque es una forma sencilla de añadir información valiosa para el +lector. + +No utilice la palabra clave ``extern`` con declaraciones de función ya que +esto hace las líneas más largas y no es estrictamente necesario. + +Al escribir prototipos de funciones, mantenga el `orden de los elementos regular +<https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_. +Por ejemplo, usando este ejemplo de declaración de función:: + + __init void * __must_check action(enum magic value, size_t size, u8 count, + char *fmt, ...) __printf(4, 5) __malloc; + +El orden preferido de elementos para un prototipo de función es: + +- clase de almacenamiento (a continuación, ``static __always_inline``, + teniendo en cuenta que ``__always_inline`` es técnicamente un atributo + pero se trata como ``inline``) +- atributos de clase de almacenamiento (aquí, ``__init`` -- es decir, + declaraciones de sección, pero también cosas como ``__cold``) +- tipo de retorno (aquí, ``void *``) +- atributos de tipo de retorno (aquí, ``__must_check``) +- nombre de la función (aquí, ``action``) +- parámetros de la función (aquí, ``(enum magic value, size_t size, u8 count, char *fmt, ...)``, + teniendo en cuenta que los nombres de los parámetros siempre deben + incluirse) +- atributos de parámetros de función (aquí, ``__printf(4, 5)``) +- atributos de comportamiento de la función (aquí, ``__malloc``) + +Tenga en cuenta que para una **definición** de función (es decir, el cuerpo +real de la función), el compilador no permite atributos de parámetros de +función después de parámetros de la función. En estos casos, deberán ir +tras los atributos de clase (por ejemplo, tenga en cuenta el cambio de +posición de ``__printf(4, 5)`` a continuación, en comparación con el +ejemplo de **declaración** anterior):: + + static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value, + size_t size, u8 count, char *fmt, ...) __malloc + { + ... + } + +7) Salida centralizada de funciones +----------------------------------- + +Aunque desaprobado por algunas personas, el equivalente de la instrucción +goto es utilizado con frecuencia por los compiladores, en forma de +instrucción de salto incondicional. + +La declaración goto es útil cuando una función sale desde múltiples +ubicaciones y se deben realizar algunos trabajos comunes, como la limpieza. +Si no se necesita limpieza, entonces simplemente haga return directamente. + +Elija nombres de etiquetas que digan qué hace el goto o por qué existe el +goto. Un ejemplo de un buen nombre podría ser ``out_free_buffer:`` +(``salida_liberar_buffer``) si al irse libera ``buffer``. Evite usar +nombres GW-BASIC como ``err1:`` y ``err2:``, ya que tendría que volver a +numerarlos si alguna vez agrega o elimina rutas de salida, y hacen que sea +difícil de verificar que sean correctos, de todos modos. + +La razón para usar gotos es: + +- Las declaraciones incondicionales son más fáciles de entender y seguir. +- se reduce el anidamiento +- errores al no actualizar los puntos de salida individuales al hacer + modificaciones son evitados +- ahorra el trabajo del compilador de optimizar código redundante ;) + +.. code-block:: c + + int fun(int a) + { + int result = 0; + char *buffer; + + buffer = kmalloc(SIZE, GFP_KERNEL); + if (!buffer) + return -ENOMEM; + + if (condition1) { + while (loop1) { + ... + } + result = 1; + goto out_free_buffer; + } + ... + out_free_buffer: + kfree(buffer); + return result; + } + +Un tipo común de error a tener en cuenta es "un error de error" que es algo +así: + +.. code-block:: c + + err: + kfree(foo->bar); + kfree(foo); + return ret; + +El error en este código es que en algunas rutas de salida, ``foo`` es NULL. +Normalmente la solución para esto es dividirlo en dos etiquetas de error +``err_free_bar:`` y ``err_free_foo:``: + +.. code-block:: c + + err_free_bar: + kfree(foo->bar); + err_free_foo: + kfree(foo); + return ret; + +Idealmente, debería simular errores para probar todas las rutas de salida. + + +8) Comentarios +-------------- + +Los comentarios son buenos, pero también existe el peligro de comentar +demasiado. NUNCA trate de explicar CÓMO funciona su código en un +comentario: es mucho mejor escribir el código para que el +**funcionamiento** sea obvio y es una pérdida de tiempo explicar código mal +escrito. + +Generalmente, desea que sus comentarios digan QUÉ hace su código, no CÓMO. +Además, trate de evitar poner comentarios dentro del cuerpo de una función: +si la función es tan compleja que necesita comentar por separado partes de +esta, probablemente debería volver al capítulo 6 una temporada. Puede +hacer pequeños comentarios para notar o advertir sobre algo particularmente +inteligente (o feo), pero trate de evitar el exceso. En su lugar, ponga los +comentarios al principio de la función, diga a la gente lo que hace y +posiblemente POR QUÉ hace esto. + +Al comentar las funciones de la API del kernel, utilice el formato +kernel-doc. Consulte los archivos en :ref:`Documentation/doc-guide/ <doc_guide>` +y ``scripts/kernel-doc`` para más detalles. + +El estilo preferido para comentarios largos (de varias líneas) es: + +.. code-block:: c + + /* + * Este es el estilo preferido para comentarios + * multilínea en el código fuente del kernel Linux. + * Por favor, utilícelo constantemente. + * + * Descripción: Una columna de asteriscos en el lado izquierdo, + * con líneas iniciales y finales casi en blanco. + */ + +Para archivos en net/ y drivers/net/, el estilo preferido para comentarios +largos (multi-linea) es un poco diferente. + +.. code-block:: c + + /* El estilo de comentario preferido para archivos en net/ y drivers/net + * se asemeja a esto. + * + * Es casi lo mismo que el estilo de comentario generalmente preferido, + * pero no hay una línea inicial casi en blanco. + */ + +También es importante comentar los datos, ya sean tipos básicos o +derivados. Para este fin, use solo una declaración de datos por línea (sin +comas para múltiples declaraciones de datos). Esto le deja espacio para un +pequeño comentario sobre cada elemento, explicando su uso. + +9) Has hecho un desastre +--------------------------- + +Está bien, todos lo hacemos. Probablemente un antiguo usuario de Unix le +haya dicho que ``GNU emacs`` formatea automáticamente las fuentes C por +usted, y ha notado que sí, lo hace, pero los por defecto que tiene son +menos que deseables (de hecho, son peores que los aleatorios) escribiendo - +un número infinito de monos escribiendo en GNU emacs nunca harán un buen +programa). + +Por lo tanto, puede deshacerse de GNU emacs o cambiarlo y usar valores más +sanos. Para hacer esto último, puede pegar lo siguiente en su archivo +.emacs: + +.. code-block:: none + + (defun c-lineup-arglist-tabs-only (ignored) + "Line up argument lists by tabs, not spaces" + (let* ((anchor (c-langelem-pos c-syntactic-element)) + (column (c-langelem-2nd-pos c-syntactic-element)) + (offset (- (1+ column) anchor)) + (steps (floor offset c-basic-offset))) + (* (max steps 1) + c-basic-offset))) + + (dir-locals-set-class-variables + 'linux-kernel + '((c-mode . ( + (c-basic-offset . 8) + (c-label-minimum-indentation . 0) + (c-offsets-alist . ( + (arglist-close . c-lineup-arglist-tabs-only) + (arglist-cont-nonempty . + (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) + (arglist-intro . +) + (brace-list-intro . +) + (c . c-lineup-C-comments) + (case-label . 0) + (comment-intro . c-lineup-comment) + (cpp-define-intro . +) + (cpp-macro . -1000) + (cpp-macro-cont . +) + (defun-block-intro . +) + (else-clause . 0) + (func-decl-cont . +) + (inclass . +) + (inher-cont . c-lineup-multi-inher) + (knr-argdecl-intro . 0) + (label . -1000) + (statement . 0) + (statement-block-intro . +) + (statement-case-intro . +) + (statement-cont . +) + (substatement . +) + )) + (indent-tabs-mode . t) + (show-trailing-whitespace . t) + )))) + + (dir-locals-set-directory-class + (expand-file-name "~/src/linux-trees") + 'linux-kernel) + +Esto hará que emacs funcione mejor con el estilo de código del kernel para +C en archivos bajo ``~/src/linux-trees``. + +Pero incluso si no logra que emacs realice un formateo correcto, no todo +está perdido: use ``indent``. + +Ahora bien, de nuevo, la sangría de GNU tiene la misma configuración de +muerte cerebral que GNU emacs tiene, por lo que necesita darle algunas +opciones de línea de comando. Sin embargo, eso no es tan malo, porque +incluso los creadores de GNU indent reconocen la autoridad de K&R (la gente +de GNU no es mala, solo están gravemente equivocados en este asunto), por +lo que simplemente de a la sangría las opciones ``-kr -i8`` (significa +``K&R, guiones de 8 caracteres``), o use ``scripts/Lindent``, que indenta +con ese estilo. + +``indent`` tiene muchas opciones, y especialmente cuando se trata de +comentar reformateos, es posible que desee echar un vistazo a la página del +manual. Pero recuerde: ``indent`` no es la solución para una mala +programación. + +Tenga en cuenta que también puede usar la herramienta ``clang-format`` para +ayudarlo con estas reglas, para volver a formatear rápidamente partes de su +código automáticamente, y revisar archivos completos para detectar errores +de estilo del código, errores tipográficos y posibles mejoras. También es +útil para ordenar ``#includes``, para alinear variables/macros, para +redistribuir texto y otras tareas similares. Vea el archivo +:ref:`Documentation/process/clang-format.rst <clangformat>` para más +detalles. + +10) Archivos de configuración de Kconfig +---------------------------------------- + +Para todos los archivos de configuración de Kconfig* en todo el árbol +fuente, la sangría es algo diferente. Las líneas bajo una definición +``config`` están indentadas con una tabulación, mientras que el texto de +ayuda tiene una sangría adicional de dos espacios. Ejemplo:: + + config AUDIT + bool "Soporte para auditar" + depends on NET + help + Habilita la infraestructura de auditoría que se puede usar con otro + subsistema kernel, como SELinux (que requiere esto para + registro de salida de mensajes avc). No hace auditoría de llamadas al + sistema sin CONFIG_AUDITSYSCALL. + +Características seriamente peligrosas (como soporte de escritura para +ciertos filesystems) deben anunciar esto de forma destacada en su cadena de +solicitud:: + + config ADFS_FS_RW + bool "ADFS write support (DANGEROUS)" + depends on ADFS_FS + ... + +Para obtener la documentación completa sobre los archivos de configuración, +consulte el archivo Documentation/kbuild/kconfig-language.rst. + + +11) Estructuras de datos +------------------------ + +Las estructuras de datos que tienen visibilidad fuera del contexto de un +solo subproceso en el que son creadas y destruidas, siempre debe tener +contadores de referencia. En el kernel, la recolección de basura no existe +(y fuera, la recolección de basura del kernel es lenta e ineficiente), lo +que significa que absolutamente **tiene** para hacer referencia y contar +todos sus usos. + +El conteo de referencias significa que puede evitar el bloqueo y permite +que múltiples usuarios tengan acceso a la estructura de datos en paralelo - +y no tengan que preocuparse de que la estructura, de repente, desaparezca +debajo de su control, solo porque durmieron o hicieron otra cosa por un +tiempo. + +Tenga en cuenta que el bloqueo **no** reemplaza el recuento de referencia. +El bloqueo se utiliza para mantener la coherencia de las estructuras de +datos, mientras que la referencia y contar es una técnica de gestión de +memoria. Por lo general, ambos son necesarios, y no deben confundirse entre +sí. + +De hecho, muchas estructuras de datos pueden tener dos niveles de conteo de +referencias, cuando hay usuarios de diferentes ``clases``. El conteo de +subclases cuenta el número de usuarios de la subclase y disminuye el conteo +global solo una vez, cuando el recuento de subclases llega a cero. + +Se pueden encontrar ejemplos de este tipo de ``recuento de referencias de +niveles múltiples`` en la gestión de memoria (``struct mm_struct``: +mm_users y mm_count), y en código del sistema de archivos +(``struct super_block``: s_count y s_active). + +Recuerde: si otro hilo puede encontrar su estructura de datos y usted no +tiene un recuento de referencias, es casi seguro que tiene un error. + +12) Macros, Enums y RTL +------------------------ + +Los nombres de macros que definen constantes y etiquetas en enumeraciones +(enums) están en mayúsculas. + +.. code-block:: c + + #define CONSTANTE 0x12345 + +Se prefieren los enums cuando se definen varias constantes relacionadas. + +Se aprecian los nombres de macro en MAYÚSCULAS, pero las macros que se +asemejan a funciones puede ser nombradas en minúscula. + +Generalmente, las funciones en línea son preferibles a las macros que se +asemejan a funciones. + +Las macros con varias instrucciones deben contenerse en un bloque do-while: + +.. code-block:: c + + #define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + haz_esto(b, c); \ + } while (0) + +Cosas a evitar al usar macros: + +1) macros que afectan el flujo de control: + +.. code-block:: c + + #define FOO(x) \ + do { \ + if (blah(x) < 0) \ + return -EBUGGERED; \ + } while (0) + +es una **muy** mala idea. Parece una llamada de función pero sale de la +función de ``llamada``; no rompa los analizadores internos de aquellos que +leerán el código. + +2) macros que dependen de tener una variable local con un nombre mágico: + +.. code-block:: c + + #define FOO(val) bar(index, val) + +puede parecer algo bueno, pero es confuso como el infierno cuando uno lee +el código, y es propenso a romperse por cambios aparentemente inocentes. + +3) macros con argumentos que se usan como valores l: FOO(x) = y; le van +a morder si alguien, por ejemplo, convierte FOO en una función en línea. + +4) olvidarse de la precedencia: las macros que definen constantes usando +expresiones deben encerrar la expresión entre paréntesis. Tenga cuidado con +problemas similares con macros usando parámetros. + +.. code-block:: c + + #define CONSTANTE 0x4000 + #define CONSTEXP (CONSTANTE | 3) + +5) colisiones de espacio de nombres ("namespace") al definir variables +locales en macros que se asemejan a funciones: + +.. code-block:: c + + #define FOO(x) \ + ({ \ + typeof(x) ret; \ + ret = calc_ret(x); \ + (ret); \ + }) + +ret es un nombre común para una variable local -es menos probable que +__foo_ret colisione (coincida) con una variable existente. + +El manual de cpp trata las macros de forma exhaustiva. El manual interno de +gcc también cubre RTL, que se usa frecuentemente con lenguaje ensamblador +en el kernel. + +13) Imprimir mensajes del kernel +-------------------------------- + +A los desarrolladores del kernel les gusta ser vistos como alfabetizados. +Cuide la ortografía de los mensajes del kernel para causar una buena +impresión. No utilice contracciones incorrectas como ``dont``; use +``do not`` o ``don't`` en su lugar. Haga sus mensajes concisos, claros e +inequívocos. + +Los mensajes del kernel no tienen que terminar con un punto. + +Imprimir números entre paréntesis (%d) no agrega valor y debe evitarse. + +Hay varias modelos de macros de diagnóstico de driver en <linux/dev_printk.h> +que debe usar para asegurarse de que los mensajes coincidan con el +dispositivo correcto y driver, y están etiquetados con el nivel correcto: +dev_err(), dev_warn(), dev_info(), y así sucesivamente. Para mensajes que +no están asociados con un dispositivo particular, <linux/printk.h> define +pr_notice(), pr_info(), pr_warn(), pr_err(), etc. + +Crear buenos mensajes de depuración puede ser todo un desafío; y una vez +los tiene, pueden ser de gran ayuda para la resolución remota de problemas. +Sin embargo, la impresión de mensajes de depuración se maneja de manera +diferente a la impresión de otros mensajes que no son de depuración. +Mientras que las otras funciones pr_XXX() se imprimen incondicionalmente, +pr_debug() no lo hace; se compila fuera por defecto, a menos que DEBUG sea +definido o se establezca CONFIG_DYNAMIC_DEBUG. Eso es cierto para dev_dbg() +también, y una convención relacionada usa VERBOSE_DEBUG para agregar +mensajes dev_vdbg() a los ya habilitados por DEBUG. + +Muchos subsistemas tienen opciones de depuración de Kconfig para activar +-DDEBUG en el Makefile correspondiente; en otros casos, los archivos +usan #define DEBUG. Y cuando un mensaje de depuración debe imprimirse +incondicionalmente, por ejemplo si es ya dentro de una sección #ifdef +relacionada con la depuración, printk(KERN_DEBUG ...) puede ser usado. + +14) Reservando memoria +---------------------- + +El kernel proporciona los siguientes asignadores de memoria de propósito +general: kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() y +vzalloc(). Consulte la documentación de la API para obtener más información. +a cerca de ellos. :ref:`Documentation/core-api/memory-allocation.rst +<memory_allocation>` + +La forma preferida para pasar el tamaño de una estructura es la siguiente: + +.. code-block:: c + + p = kmalloc(sizeof(*p), ...); + +La forma alternativa donde se deletrea el nombre de la estructura perjudica +la legibilidad, y presenta una oportunidad para un error cuando se cambia +el tipo de variable de puntero, pero el tamaño correspondiente de eso que +se pasa a un asignador de memoria no. + +Convertir el valor devuelto, que es un puntero vacío, es redundante. La +conversión desde el puntero vacío a cualquier otro tipo de puntero está +garantizado por la programación en idioma C. + +La forma preferida para asignar una matriz es la siguiente: + +.. code-block:: c + + p = kmalloc_array(n, sizeof(...), ...); + +La forma preferida para asignar una matriz a cero es la siguiente: + +.. code-block:: c + + p = kcalloc(n, sizeof(...), ...); + +Ambos casos verifican el desbordamiento en el tamaño de asignación n * +sizeof (...), y devuelven NULL si esto ocurrió. + +Todas estas funciones de asignación genéricas emiten un volcado de pila +(" stack dump") en caso de fallo cuando se usan sin __GFP_NOWARN, por lo +que no sirve de nada emitir un mensaje de fallo adicional cuando se +devuelva NULL. + +15) La enfermedad de inline +---------------------------- + +Parece haber una común percepción errónea de que gcc tiene una magica +opción "hazme más rápido" de aceleración, llamada ``inline`` (en línea). +Mientras que el uso de inlines puede ser apropiado (por ejemplo, como un +medio para reemplazar macros, consulte el Capítulo 12), muy a menudo no lo +es. El uso abundante de la palabra clave inline conduce a una mayor kernel, +que a su vez ralentiza el sistema en su conjunto, debido a una mayor huella +de icache para la CPU, y sencillamente porque hay menos memoria disponible +para el pagecache. Solo piense en esto; un fallo en la memoria caché de la +página provoca una búsqueda de disco, que tarda fácilmente 5 milisegundos. +Hay MUCHOS ciclos de CPU que puede entrar en estos 5 milisegundos. + +Una razonable regla general es no poner funciones inline que tengan más de +3 líneas de código en ellas. Una excepción a esta regla son los casos en +que se sabe que un parámetro es una constante en tiempo de compilación, y +como resultado de esto, usted *sabe*, el compilador podrá optimizar la +mayor parte de su función en tiempo de compilación. Para un buen ejemplo de +este último caso, véase la función en línea kmalloc(). + +A menudo, la gente argumenta que agregar funciones en línea que son +estáticas y se usan solo una vez, es siempre una victoria ya que no hay +perdida de espacio. Mientras esto es técnicamente correcto, gcc es capaz de +incorporarlos automáticamente sin ayuda, y esta el problema de +mantenimiento de eliminar el inline, cuando un segundo usuario supera el +valor potencial de la pista que le dice a gcc que haga algo que habría +hecho de todos modos. + +16) Valores devueltos por función y sus nombres +----------------------------------------------- + +Las funciones pueden devolver valores de muchos tipos diferentes, y uno de +lo más común es un valor que indica si la función tuvo éxito o ha fallado. +Dicho valor se puede representar como un número entero de código de error +(-Exxx = falla, 0 = éxito) o un booleano ``con éxito`` (0 = falla, distinto +de cero = éxito). + +La mezcla de estos dos tipos de representaciones es una fuente fértil de +errores difíciles de encontrar. Si el lenguaje C incluyera una fuerte +distinción entre enteros y booleanos, el compilador encontraría estos +errores por nosotros... pero no lo hace. Para ayudar a prevenir tales +errores, siga siempre esta convención:: + + Si el nombre de una función es una acción o un comando imperativo, + la función debe devolver un número entero de código de error. si el nombre + es un predicado, la función debe devolver un valor booleano "exitoso". + +Por ejemplo, ``agregar trabajo`` es un comando, y la función +agregar_trabajo() devuelve 0 en caso de éxito o -EBUSY en caso de fracaso. +De la misma manera, ``dispositivo PCI presente`` es un predicado, y la +función pci_dev_present() devuelve 1 si tiene éxito en encontrar un +dispositivo coincidente o 0 si no es así. + +Todas las funciones EXPORTed (exportadas) deben respetar esta convención, +al igual que todas las funciones publicas. Las funciones privadas +(estáticas) no lo necesitan, pero es recomendado que lo hagan. + +Las funciones cuyo valor devuelto es el resultado real de un cálculo, en +lugar de una indicación de si el cómputo tuvo éxito, no están sujetas a +esta regla. Generalmente indican fallo al devolver valores fuera del rango +de resultados. Los ejemplos típicos serían funciones que devuelven +punteros; estos usan NULL o el mecanismo ERR_PTR para informar de fallos. + +17) Usando bool +---------------- + +El tipo bool del kernel Linux es un alias para el tipo C99 _Bool. Los +valores booleanos pueden solo evaluar a 0 o 1, y la conversión implícita o +explícita a bool convierte automáticamente el valor en verdadero o falso. +Cuando se utilizan tipos booleanos, +!! no se necesita construcción, lo que elimina una clase de errores. + +Cuando se trabaja con valores booleanos, se deben usar las definiciones +verdadera y falsa, en lugar de 1 y 0. + +Los tipos de devolución de función bool y las variables de pila siempre +se pueden usar cuando esto sea adecuado. Se recomienda el uso de bool para +mejorar la legibilidad y, a menudo, es una mejor opción que 'int' para +almacenar valores booleanos. + +No use bool si el diseño de la línea de caché o el tamaño del valor son +importantes, ya que su tamaño y la alineación varía según la arquitectura +compilada. Las estructuras que son optimizadas para la alineación y el +tamaño no debe usar bool. + +Si una estructura tiene muchos valores verdadero/falso, considere +consolidarlos en un bitfield con miembros de 1 bit, o usando un tipo de +ancho fijo apropiado, como u8. + +De manera similar, para los argumentos de función, se pueden consolidar +muchos valores verdaderos/falsos en un solo argumento bit a bit 'flags' y +'flags' a menudo, puede ser una alternativa de argumento más legible si los +sitios de llamada tienen constantes desnudas de tipo verdaderas/falsas. + +De lo contrario, el uso limitado de bool en estructuras y argumentos puede +mejorar la legibilidad. + +18) No reinvente las macros del kernel +--------------------------------------- + +El archivo de cabecera include/linux/kernel.h contiene una serie de macros +que debe usar, en lugar de programar explícitamente alguna variante de +estos por usted mismo. Por ejemplo, si necesita calcular la longitud de una +matriz, aproveche la macro + +.. code-block:: c + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + +De manera similar, si necesita calcular el tamaño de algún miembro de la +estructura, use + +.. code-block:: c + + #define sizeof_field(t, f) (sizeof(((t*)0)->f)) + +También hay macros min() y max() que realizan una verificación estricta de +tipos si lo necesita. Siéntase libre de leer detenidamente ese archivo de +encabezado para ver qué más ya está definido y que no debe reproducir en su +código. + +19) Editores modeline y otros desastres +--------------------------------------- + +Algunos editores pueden interpretar la información de configuración +incrustada en los archivos fuente, indicado con marcadores especiales. Por +ejemplo, emacs interpreta las líneas marcadas como esto: + +.. code-block:: c + + -*- mode: c -*- + +O así: + +.. code-block:: c + + /* + Local Variables: + compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" + End: + */ + +Vim interpreta los marcadores que se ven así: + +.. code-block:: c + + /* vim:set sw=8 noet */ + +No incluya ninguno de estos en los archivos fuente. La gente tiene sus +propias configuraciones del editor, y sus archivos de origen no deben +anularlos. Esto incluye marcadores para sangría y configuración de modo. +La gente puede usar su propio modo personalizado, o puede tener algún otro +método mágico para que la sangría funcione correctamente. + + +20) Ensamblador inline +----------------------- + +En el código específico de arquitectura, es posible que deba usar +ensamblador en línea para interactuar con funcionalidades de CPU o +plataforma. No dude en hacerlo cuando sea necesario. Sin embargo, no use +ensamblador en línea de forma gratuita cuando C puede hacer el trabajo. +Puede y debe empujar el hardware desde C cuando sea posible. + +Considere escribir funciones auxiliares simples que envuelvan bits comunes +de ensamblador, en lugar de escribirlos repetidamente con ligeras +variaciones. Recuerde que el ensamblador en línea puede usar parámetros C. + +Las funciones de ensamblador grandes y no triviales deben ir en archivos .S, +con su correspondientes prototipos de C definidos en archivos de encabezado +en C. Los prototipos de C para el ensamblador deben usar ``asmlinkage``. + +Es posible que deba marcar su declaración asm como volátil, para evitar que +GCC la elimine si GCC no nota ningún efecto secundario. No siempre es +necesario hacerlo, sin embargo, y hacerlo innecesariamente puede limitar la +optimización. + +Al escribir una sola declaración de ensamblador en línea que contiene +múltiples instrucciones, ponga cada instrucción en una línea separada en +una string separada, y termine cada string excepto la última con ``\n\t`` +para indentar correctamente la siguiente instrucción en la salida en +ensamblador: + +.. code-block:: c + + asm ("magic %reg1, #42\n\t" + "more_magic %reg2, %reg3" + : /* outputs */ : /* inputs */ : /* clobbers */); + +21) Compilación condicional +--------------------------- + +Siempre que sea posible, no use condicionales de preprocesador (#if, +#ifdef) en archivos .c; de lo contrario, el código es más difícil de leer y +la lógica más difícil de seguir. En cambio, use dichos condicionales en un +archivo de encabezado que defina funciones para usar en esos archivos .c, +proporcionando versiones de código auxiliar sin operación en el caso #else, +y luego llame a estas funciones incondicionalmente desde archivos .c. El +compilador evitará generar cualquier código para las llamadas restantes, +produciendo resultados idénticos, pero la lógica es fácil de seguir. + +Prefiera compilar funciones completas, en lugar de porciones de funciones o +porciones de expresiones. En lugar de poner un ifdef en una expresión, +divida la totalidad de la expresión con una función de ayuda independiente +y aplique el condicional a esa función. + +Si tiene una función o variable que puede potencialmente quedar sin usar en +una configuración en particular, y el compilador advertiría sobre su +definición sin usar, marque la definición como __maybe_unused en lugar de +envolverla en un preprocesador condicional. (Sin embargo, si una función o +variable *siempre* acaba sin ser usada, bórrela.) + +Dentro del código, cuando sea posible, use la macro IS_ENABLED para +convertir un símbolo Kconfig en una expresión booleana de C, y utilícelo en +un condicional de C normal: + +.. code-block:: c + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +El compilador "doblará"" constantemente el condicional e incluirá o +excluirá el bloque de código al igual que con un #ifdef, por lo que esto no +agregará ningún tiempo de gastos generales en ejecución. Sin embargo, este +enfoque todavía permite que el compilador de C vea el código dentro del +bloque, y verifique que sea correcto (sintaxis, tipos, símbolo, referencias, +etc.). Por lo tanto, aún debe usar un #ifdef si el código dentro del bloque +hace referencia a símbolos que no existirán si no se cumple la condición. + +Al final de cualquier bloque #if o #ifdef no trivial (más de unas pocas +líneas), incluya un comentario después de #endif en la misma línea, +anotando la expresión condicional utilizada. Por ejemplo: + +.. code-block:: c + + #ifdef CONFIG_SOMETHING + ... + #endif /* CONFIG_SOMETHING */ + +22) No rompa el kernel +----------------------- + +En general, la decisión de romper el kernel pertenece al usuario, más que +al desarrollador del kernel. + +Evite el panic() +**************** + +panic() debe usarse con cuidado y principalmente solo durante el arranque +del sistema. panic() es, por ejemplo, aceptable cuando se queda sin memoria +durante el arranque y no puede continuar. + +Use WARN() en lugar de BUG() +**************************** + +No agregue código nuevo que use cualquiera de las variantes BUG(), como +BUG(), BUG_ON() o VM_BUG_ON(). En su lugar, use una variante WARN*(), +preferiblemente WARN_ON_ONCE(), y posiblemente con código de recuperación. +El código de recuperación no es requerido si no hay una forma razonable de +recuperar, al menos parcialmente. + +"Soy demasiado perezoso para tener en cuenta los errores" no es una excusa +para usar BUG(). Importantes corrupciones internas sin forma de continuar +aún pueden usar BUG(), pero necesitan una buena justificación. + +Use WARN_ON_ONCE() en lugar de WARN() o WARN_ON() +************************************************* + +Generalmente, se prefiere WARN_ON_ONCE() a WARN() o WARN_ON(), porque es +común que una condición de advertencia dada, si ocurre, ocurra varias +veces. Esto puede llenar el registro del kernel, e incluso puede ralentizar +el sistema lo suficiente como para que el registro excesivo se convierta en +su propio, adicional problema. + +No haga WARN a la ligera +************************ + +WARN*() está diseñado para situaciones inesperadas que nunca deberían +suceder. Las macros WARN*() no deben usarse para nada que se espera que +suceda durante un funcionamiento normal. No hay "checkeos" previos o +posteriores a la condición, por ejemplo. De nuevo: WARN*() no debe usarse +para una condición esperada que vaya a activarse fácilmente, por ejemplo, +mediante acciones en el espacio del usuario. pr_warn_once() es una +alternativa posible, si necesita notificar al usuario de un problema. + +No se preocupe sobre panic_on_warn de usuarios +********************************************** + +Algunas palabras más sobre panic_on_warn: Recuerde que ``panic_on_warn`` es +una opción disponible del kernel, y que muchos usuarios configuran esta +opción. Esta es la razón por la que hay un artículo de "No haga WARN a la +ligera", arriba. Sin embargo, la existencia de panic_on_warn de usuarios no +es una razón válida para evitar el uso juicioso de WARN*(). Esto se debe a +que quien habilita panic_on_warn, explícitamente pidió al kernel que +fallara si se dispara un WARN*(), y tales usuarios deben estar preparados +para afrontar las consecuencias de un sistema que es algo más probable que +se rompa. + +Use BUILD_BUG_ON() para aserciones en tiempo de compilación +*********************************************************** + +El uso de BUILD_BUG_ON() es aceptable y recomendado, porque es una aserción +en tiempo de compilación, que no tiene efecto en tiempo de ejecución. + +Apéndice I) Referencias +----------------------- + +The C Programming Language, Segunda edicion +por Brian W. Kernighan and Dennis M. Ritchie. +Prentice Hall, Inc., 1988. +ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback). + +The Practice of Programming +por Brian W. Kernighan and Rob Pike. +Addison-Wesley, Inc., 1999. +ISBN 0-201-61586-X. + +manuales GCC - en cumplimiento con K&R y este texto - para cpp, gcc, +detalles de gcc y sangría, todo disponible en https://www.gnu.org/manual/ + +WG14 es el grupo de trabajo de estandarización internacional de la +programación en lenguaje C, URL: http://www.open-std.org/JTC1/SC22/WG14/ + +:ref:`process/coding-style.rst <codingstyle>` del kernel, por greg@kroah.com at OLS 2002: +http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/translations/sp_SP/process/index.rst b/Documentation/translations/sp_SP/process/index.rst new file mode 100644 index 000000000000..49a05f6a5544 --- /dev/null +++ b/Documentation/translations/sp_SP/process/index.rst @@ -0,0 +1,15 @@ +.. raw:: latex + + \renewcommand\thesection* + \renewcommand\thesubsection* + +.. include:: ../disclaimer-sp.rst + +.. _sp_process_index: + +.. toctree:: + :maxdepth: 1 + + submitting-patches + kernel-docs + coding-style diff --git a/Documentation/translations/sp_SP/process/kernel-docs.rst b/Documentation/translations/sp_SP/process/kernel-docs.rst new file mode 100644 index 000000000000..2f9b3df8f8fa --- /dev/null +++ b/Documentation/translations/sp_SP/process/kernel-docs.rst @@ -0,0 +1,187 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/kernel-docs.rst <kernel_docs>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_kernel_docs: + +Índice de documentación adicional del kernel +============================================ + +La necesidad de un documento como este se hizo evidente en la lista de +correo de linux-kernel cuando las mismas preguntas, solicitando sugerencias +e información, aparecieron una y otra vez. + +Afortunadamente, a medida que más y más gente accede a GNU/Linux, más +desarrolladores se interesan por el kernel. Sin embargo, leer las fuentes +no siempre es suficiente. Es fácil entender el código, pero se pierden los +conceptos, la filosofía y decisiones de diseño detrás de dicho código. + +Desafortunadamente, no existen muchos documentos disponibles para que los +principiantes comiencen. Y, aunque existieran, no habría ningún lugar +"conocido" que les pudiera seguir la pista. Estas líneas tratan de cubrir +esta carencia. + +POR FAVOR, si conoce algún documento que no figura aquí, o si escribe un +nuevo documento, incluya una referencia aquí, siguiendo el proceso de envío +de parches del kernel. Cualquier corrección, idea o comentario también es +bienvenida. + +Todos los documentos se catalogan con los siguientes campos: el "Título", +el "Autor"/es, la "URL" donde se encuentran, algunas "Palabras clave" +útiles para buscar temas específicos, y una breve "Descripción" del +documento en cuestión. + +.. note:: + + Los documentos de cada sección en este documento están ordenados por su + fecha de publicación, del más reciente al más antiguo. Los maintainers + deben ir retirando recursos obsoletos o anticuados. + +Documentos en el árbol del kernel Linux +----------------------------------------- + +Los libros de Sphinx deben compilarse con ``make {htmldocs | pdfdocs | epubdocs}``. + + * Título: **linux/Documentation** + + :Autor: Many. + :Ubicación: Documentation/ + :Palabras Clave: archivos de texto, Sphinx. + :Descripción: Documentación que viene con las fuentes del kernel, + dentro del directorio Documentation. Algunas páginas de este documento + (incluido este documento en sí) se han trasladado allí, y podrían + estar más actualizadas que la versión web. + +Documentos en línea +------------------- + + * Título: **Linux Kernel Mailing List Glossary** + + :Autor: various + :URL: https://kernelnewbies.org/KernelGlossary + :Fecha: rolling version + :Palabras Clave: glosario terminos, linux-kernel. + :Descripción: De la Introducción: "This glossary is intended as + a brief description of some of the acronyms and terms you may hear + during discussion of the Linux kernel". + + * Título: **The Linux Kernel Module Programming Guide** + + :Autor: Peter Jay Salzman, Michael Burian, Ori Pomerantz, Bob Mottram, + Jim Huang. + :URL: https://sysprog21.github.io/lkmpg/ + :Fecha: 2021 + :Palabras Clave: modules, GPL book, /proc, ioctls, system calls, + interrupt handlers, llamadas al sistema, interrupciones. + :Descripción: Un muy buen libro GPL sobre el tema de la programación + de módulos. Muchos ejemplos. Actualmente la nueva versión está + siendo mantenida activamente ent https://github.com/sysprog21/lkmpg. + +Libros publicados +----------------- + + * Título: **Linux Kernel Programming: A Comprehensive Guide to Kernel Internals, Writing Kernel Modules, and Kernel Synchronization** + + :Autor: Kaiwan N. Billimoria + :Publica: Packt Publishing Ltd + :Fecha: 2021 + :Paginas: 754 + :ISBN: 978-1789953435 + + * Título: **Linux Kernel Development, 3rd Edition** + + :Autor: Robert Love + :Publica: Addison-Wesley + :Fecha: July, 2010 + :Paginas: 440 + :ISBN: 978-0672329463 + :Notas: Libro fundacional + +.. _sp_ldd3_published: + + * Título: **Linux Device Drivers, 3rd Edition** + + :Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman + :Publica: O'Reilly & Associates + :Fecha: 2005 + :Paginas: 636 + :ISBN: 0-596-00590-3 + :Notas: Libro fundacional. Más información en + http://www.oreilly.com/catalog/linuxdrive3/ + formato PDF, URL: https://lwn.net/Kernel/LDD3/ + + * Título: **The Design of the UNIX Operating System** + + :Autor: Maurice J. Bach + :Publica: Prentice Hall + :Fecha: 1986 + :Paginas: 471 + :ISBN: 0-13-201757-1 + :Notas: Libro fundacional + +Recursos varios +--------------- + + * Título: **Cross-Referencing Linux** + + :URL: https://elixir.bootlin.com/ + :Palabras Clave: Browsing source code. + :Descripción: Otro navegador de código fuente del kernel Linux que se + encuentra en la web. Muchas referencias cruzadas a variables y + funciones. Puedes ver dónde se definen y dónde se utilizan. + + * Título: **Linux Weekly News** + + :URL: https://lwn.net + :Palabras Clave: latest kernel news, noticias del kernel Linux. + :Descripción: El título lo dice todo (Noticias Semanales de Linux). + Hay una sección fija sobre el kernel, resumiendo el trabajo de sus + desarrolladores, correcciones de errores, nuevas funciones y + versiones, producido durante la semana. + + * Título: **The home page of Linux-MM** + + :Autor: The Linux-MM team. + :URL: https://linux-mm.org/ + :Palabras Clave: memory management, Linux-MM, mm patches, TODO, docs, + mailing list, administración de memoria, Linux-MM, parches mm, listas + de correo. + :Descripción: Sitio dedicado al desarrollo de la gestión de memoria + de Linux. Parches relacionados con la memoria, HOWTOs, enlaces, + desarrolladores de mm... ¡Si está interesado en el desarrollo de la + gestión de memoria no te lo pierdas! + + * Título: **Kernel Newbies IRC Channel and Website** + + :URL: https://www.kernelnewbies.org + :Palabras Clave: IRC, newbies, channel, asking doubts, canal, dudas, + novatos, preguntar. + :Descripción: #kernelnewbies en irc.oftc.net. + #kernelnewbies es una red de IRC dedicada al hacker del kernel + 'novato'. La audiencia se compone principalmente de personas que + quieren aprender sobre el kernel, trabajar en proyectos del kernel + o hackers profesionales del kernel que quieren ayudar a la gente + menos experimentada. + #kernelnewbies es parte de la red OFTC IRC. + Pruebe con irc.oftc.net como su servidor y luego haga /join + #kernelnewbies. + El sitio web kernelnewbies también alberga artículos, documentos, FAQs... + + * Título: **linux-kernel mailing list archives and search engines** + + :URL: http://vger.kernel.org/vger-lists.html + :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html + :URL: http://groups.google.com/group/mlist.linux.kernel + :Palabras Clave: linux-kernel, archives, buscar, search, archivos. + :Descripción: Algunos de los archivadores de listas de correo del + kernel de Linux. Si usted tiene uno mejor/otro, por favor hágamelo + saber. + +------- + +Este documento se basaba originalmente en: + + https://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html + +escrito por Juan-Mariano de Goyenche diff --git a/Documentation/translations/sp_SP/process/submitting-patches.rst b/Documentation/translations/sp_SP/process/submitting-patches.rst new file mode 100644 index 000000000000..bf95ceb5e865 --- /dev/null +++ b/Documentation/translations/sp_SP/process/submitting-patches.rst @@ -0,0 +1,894 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_submittingpatches: + +Envío de parches: la guía esencial para incluir su código en el kernel +======================================================================= + +Para una persona o empresa que desee enviar un cambio al kernel Linux, +el proceso puede en ocasiones resultar desalentador si no se está +familiarizado con "el sistema". Este texto es una colección de sugerencias +que pueden aumentar considerablemente las posibilidades de que se acepte su +cambio. + +Este documento contiene una gran cantidad de sugerencias en un formato +relativamente conciso. Para obtener información detallada sobre cómo +funciona el proceso de desarrollo del kernel, consulte +Documentation/process/development-process.rst. Además, lea +Documentation/process/submit-checklist.rst para obtener una lista de +elementos a verificar antes de enviar código. Para los parches de +"binding" del árbol de dispositivos, lea +Documentation/devicetree/bindings/submitting-patches.rst. + +Esta documentación asume que está usando ``git`` para preparar sus parches. +Si no está familiarizado con ``git``, le recomendamos que aprenda a +usarlo, le hará la vida como desarrollador del kernel y en general mucho +más sencilla. + +Algunos subsistemas y árboles de mantenimiento cuentan con información +adicional sobre su flujo de trabajo y expectativas, consulte +:ref:`Documentation/process/maintainer-handbooks.rst <maintainer_handbooks_main>`. + +Obtenga el código fuente actual +-------------------------------- + +Si no tiene a mano un repositorio con el código fuente actual del kernel, +use ``git`` para obtener uno. Querrá comenzar con el repositorio principal, +que se puede descargar con:: + + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + +Tenga en cuenta, sin embargo, que es posible que no desee desarrollar con +el árbol principal directamente. La mayoría de los maintainers de +subsistemas usan sus propios árboles de código fuente y quieren ver parches +preparados para esos árboles. Revise el campo **T:** para el subsistema +en el archivo MAINTAINERS para encontrar dicho árbol, o simplemente +pregunte al maintainer si el árbol no está listado allí. + +.. _sp_describe_changes: + +Describa sus cambios +--------------------- + +Describa su problema. Sea su parche una corrección de un error de una +línea o 5000 líneas para una nuevo "feature", debe haber un problema +subyacente que le motivó a hacer ese trabajo. Convenza al revisor de que +hay un problema que merece la pena solucionar y de que tiene sentido que +lea más allá del primer párrafo. + +Describa el impacto relativo al usuario. Cosas que estropeen el kernel y +los bloqueos son bastante convincentes, pero no todos los errores son tan +evidentes. Incluso si se detectó un problema durante la revisión del +código, describa el impacto que cree pueda tener en los usuarios. Tenga en +cuenta que la mayoría de instalaciones de Linux ejecutan kernels desde +árboles estables secundarios o árboles específicos de proveedor/producto +que seleccionan ("cherry-pick") solo parches específicos de upstream, así +que incluya cualquier cosa que pueda ayudar a dirigir su cambio +aguas abajo: circunstancias que producen cierta situación, extractos de +dmesg, descripciones del error fatal, regresiones de rendimiento, picos de +latencia, bloqueos, etc. + +Cuantifique optimizaciones y beneficios/perdidas. Si asegura mejoras en +rendimiento, consumo de memoria, huella del stack o tamaño de binario, +incluya números que lo respalden. Pero también describa costes no obvios. +Las optimizaciones generalmente no son gratuitas, sino un equilibrio entre +CPU, memoria y legibilidad; o, cuando se trata de heurísticas, entre +diferentes cargas de trabajo. Describa las desventajas esperadas de su +optimización para que el revisor pueda comparar las perdidas con los +beneficios. + +Una vez establecido el problema, describa lo que realmente está haciendo +al respecto en detalles técnicos. Es importante describir el cambio en +lenguaje sencillo para que el revisor verifique que el código se está +comportando como se pretende. + +El maintainer le agradecerá que escriba la descripción de su parche en un +formato que se pueda incorporar fácilmente en la gestión del código fuente +del sistema, ``git``, como un "commit log" (registros de los commits). +Consulte :ref:`sp_the_canonical_patch_format`. + +Resuelva solo un problema por parche. Si su descripción comienza a ser muy +larga, eso es una señal de que probablemente necesite dividir su parche. +Lea :ref:`split_changes`. + +Cuando envíe o vuelva a enviar un parche o una serie de parches, incluya la +descripción completa del parche y justificación del mismo. No se limite a +decir que esa es la versión N del parche (serie). No espere que el +maintainer del subsistema referencie versiones de parches anteriores o use +referencias URL para encontrar la descripción del parche y colocarla en el +parche. Es decir, el parche (serie) y su descripción deben ser +independientes. Esto beneficia tanto a los maintainers como a los +revisores. Algunos revisores probablemente ni siquiera recibieran versiones +anteriores del parche. + +Describa sus cambios en la forma imperativa, por ejemplo, "hacer que xyzzy +haga frotz" en lugar de "[Este parche] hace que xyzzy haga frotz" o "[Yo] +Cambié xyzzy para que haga frotz", como si estuviera dando órdenes al +código fuente para cambiar su comportamiento. + +Si desea hacer referencia a un commit específico, no se limite a hacer +referencia al ID SHA-1 del commit. Incluya también el resumen de una línea +del commit, para que sea más fácil para los revisores saber de qué se +trata. +Ejemplo:: + + Commit e21d2170f36602ae2708 ("video: quitar platform_set_drvdata() + innecesario") eliminó innecesario platform_set_drvdata(), pero dejó la + variable "dev" sin usar, bórrese. + +También debe asegurarse de utilizar al menos los primeros doce caracteres +del identificador SHA-1. El repositorio del kernel contiene muchos *muchos* +objetos, por lo que las colisiones con identificaciones más cortas son una +posibilidad real. Tenga en cuenta que, aunque no hay colisión con su +identificación de seis caracteres ahora, esa condición puede cambiar dentro +de cinco años. + +Si las discusiones relacionadas o cualquier otra información relativa al +cambio se pueden encontrar en la web, agregue las etiquetas 'Link:' que +apunten a estos. En caso de que su parche corrija un error, por poner un +ejemplo, agregue una etiqueta con una URL que haga referencia al informe en +los archivos de las listas de correo o un rastreador de errores; si el +parche es el resultado de alguna discusión anterior de la lista de correo o +algo documentado en la web, referencie esto. + +Cuando se vincule a archivos de listas de correo, preferiblemente use el +servicio de archivador de mensajes lore.kernel.org. Para crear la URL del +enlace, utilice el contenido del encabezado ("header") ``Message-Id`` del +mensaje sin los corchetes angulares que lo rodean. +Por ejemplo:: + + Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + +Verifique el enlace para asegurarse de que realmente funciona y apunta al +mensaje correspondiente. + +Sin embargo, intente que su explicación sea comprensible sin recursos +externos. Además de dar una URL a un archivo o error de la lista de correo, +resuma los puntos relevantes de la discusión que condujeron al parche tal y +como se envió. + +Si su parche corrige un error en un commit específico, por ejemplo +encontró un problema usando ``git bisect``, utilice la etiqueta 'Fixes:' +con los primeros 12 caracteres del ID SHA-1 y el resumen de una línea. No +divida la etiqueta en varias líneas, las etiquetas están exentas de la +regla "ajustar a 75 columnas" para simplificar análisis de scripts. Por +ejemplo:: + + Fixes: 54a4f0239f2e ("KVM: MMU: hacer que kvm_mmu_zap_page() + devuelva la cantidad de páginas que realmente liberó") + +Las siguientes configuraciones de ``git config`` se pueden usar para +agregar un bonito formato y generar este estilo con los comandos +``git log`` o ``git show``:: + + [core] + abbrev = 12 + [pretty] + fixes = Fixes: %h (\"%s\") + +Un ejemplo de uso:: + + $ git log -1 --pretty=fixes 54a4f0239f2e + Fixes: 54a4f0239f2e ("KVM: MMU: hacer que kvm_mmu_zap_page() devuelva la cantidad de páginas que realmente liberó") + +.. _sp_split_changes: + +Separe sus cambios +------------------- + +Separe cada **cambio lógico** en un parche separado. + +Por ejemplo, si sus cambios incluyen correcciones de errores y mejoras en +el rendimiento de un controlador, separe esos cambios en dos o más parches. +Si sus cambios incluyen una actualización de la API y una nueva controlador +que usa esta nueva API, sepárelos en dos parches. + +Por otro lado, si realiza un solo cambio en numerosos archivos, agrupe esos +cambios en un solo parche. Por lo tanto, un solo cambio lógico estará +contenido en un solo parche. + +El punto a recordar es que cada parche debe realizar un cambio que puede +ser verificado por los revisores fácilmente. Cada parche debe ser +justificable por sus propios méritos. + +Si un parche depende de otro parche para que un cambio sea completo, eso +está bien. Simplemente incluya que **"este parche depende del parche X"** +en la descripción de su parche. + +Cuando divida su cambio en una serie de parches, tenga especial cuidado en +asegurarse de que el kernel se compila y ejecuta correctamente después de +cada parche en la serie. Los desarrolladores que usan ``git bisect`` +para rastrear un problema pueden terminar dividiendo su serie de parches en +cualquier punto; no le agradecerán si introdujo errores a la mitad. + +Si no puede condensar su conjunto de parches en un conjunto más pequeño de +parches, solo publique, más o menos 15 a la vez, y espere la revisión e +integración. + + +Revise el estilo en sus cambios +-------------------------------- + +Revise su parche para ver si hay violaciones de estilo básico, cuyos +detalles pueden ser encontrados en Documentation/process/coding-style.rst. +No hacerlo simplemente desperdicia el tiempo de los revisores y su parche +será rechazado, probablemente sin siquiera ser leído. + +Una excepción importante es cuando se mueve código de un archivo a otro. +En tal caso, en absoluto debe modificar el código movido en el mismo parche +en que lo mueve. Esto divide claramente el acto de mover el código y sus +cambios. Esto ayuda mucho a la revisión de la diferencias reales y permite +que las herramientas rastreen mejor el historial del código en sí. + +Verifique sus parches con el verificador de estilo de parches antes de +enviarlos (scripts/checkpatch.pl). Tenga en cuenta, sin embargo, que el +verificador de estilo debe ser visto como una guía, no como un reemplazo +del juicio humano. Si su código es mejor con una violación entonces +probablemente sea mejor dejarlo estar. + +El verificador informa a tres niveles: + - ERROR: cosas que es muy probable que estén mal + - WARNING: Advertencia. Cosas que requieren una revisión cuidadosa + - CHECK: Revisar. Cosas que requieren pensarlo + +Debe poder justificar todas las violaciones que permanezcan en su parche. + + +Seleccione los destinatarios de su parche +------------------------------------------ + +Siempre debe incluir en copia a los apropiados maintainers del subsistema +en cualquier parche con código que mantengan; revise a través del archivo +MAINTAINERS y el historial de revisión del código fuente para ver quiénes +son esos maintainers. El script scripts/get_maintainer.pl puede ser muy +útil en este paso (pase rutas a sus parches como argumentos para +scripts/get_maintainer.pl). Si no puede encontrar un maintainer del +subsistema en el que está trabajando, Andrew Morton +(akpm@linux-foundation.org) sirve como maintainer de último recurso. + +Normalmente, también debe elegir al menos una lista de correo para recibir +una copia de su conjunto de parches. linux-kernel@vger.kernel.org debe +usarse de forma predeterminada para todos los parches, pero el volumen en +esta lista ha hecho que muchos desarrolladores se desconecten. Busque en el +archivo MAINTAINERS una lista específica de los subsistemas; su parche +probablemente recibirá más atención allí. Sin embargo, no envíe spam a +listas no relacionadas. + +Muchas listas relacionadas con el kernel están alojadas en vger.kernel.org; +puedes encontrar un listado de estas en +http://vger.kernel.org/vger-lists.html. Existen listas relacionadas con el +kernel alojadas en otros lugares, no obstante. + +¡No envíe más de 15 parches a la vez a las listas de correo de vger! + +Linus Torvalds es el árbitro final de todos los cambios aceptados en el +kernel de Linux. Su dirección de correo electrónico es +<torvalds@linux-foundation.org>. Recibe muchos correos electrónicos y, en +este momento, muy pocos parches pasan por Linus directamente, por lo que +normalmente debe hacer todo lo posible para -evitar- enviarle un correo +electrónico. + +Si tiene un parche que corrige un error de seguridad explotable, envíe ese +parche a security@kernel.org. Para errores graves, se debe mantener un +poco de discreción y permitir que los distribuidores entreguen el parche a +los usuarios; en esos casos, obviamente, el parche no debe enviarse a +ninguna lista pública. Revise también +Documentation/admin-guide/security-bugs.rst. + +Los parches que corrigen un error grave en un kernel en uso deben dirigirse +hacia los maintainers estables poniendo una línea como esta:: + + CC: stable@vger.kernel.org + +en el área de sign-off de su parche (es decir, NO un destinatario de correo +electrónico). También debe leer +Documentation/process/stable-kernel-rules.rst además de este documento. + +Si los cambios afectan las interfaces del kernel para el usuario, envíe al +maintainer de las MAN-PAGES (como se indica en el archivo MAINTAINERS) un +parche de páginas de manual, o al menos una notificación del cambio, para +que alguna información se abra paso en las páginas del manual. Los cambios +de la API del espacio de usuario también deben copiarse en +linux-api@vger.kernel.org. + + +Sin MIME, enlaces, compresión o archivos adjuntos. Solo texto plano +-------------------------------------------------------------------- + +Linus y otros desarrolladores del kernel deben poder leer y comentar sobre +los cambios que está enviando. Es importante para un desarrollador kernel +poder "citar" sus cambios, utilizando herramientas estándar de correo +electrónico, de modo que puedan comentar sobre partes específicas de su +código. + +Por este motivo, todos los parches deben enviarse por correo electrónico +"inline". La forma más sencilla de hacerlo es con ``git send-email``, que +es muy recomendable. Un tutorial interactivo para ``git send-email`` está +disponible en https://git-send-email.io. + +Si elige no usar ``git send-email``: + +.. warning:: + + Tenga cuidado con el ajuste de palabras de su editor que corrompe su + parche, si elige cortar y pegar su parche. + +No adjunte el parche como un archivo adjunto MIME, comprimido o no. Muchas +populares aplicaciones de correo electrónico no siempre transmiten un MIME +archivo adjunto como texto sin formato, por lo que es imposible comentar +en su código. Linus también necesita un poco más de tiempo para procesar un +archivo adjunto MIME, disminuyendo la probabilidad de que se acepte su +cambio adjunto en MIME. + +Excepción: si su proveedor de correo está destrozando parches, entonces +alguien puede pedir que los vuelva a enviar usando MIME. + +Consulte Documentation/process/email-clients.rst para obtener sugerencias +sobre cómo configurar su cliente de correo electrónico para que envíe sus +parches intactos. + +Responda a los comentarios de revisión +--------------------------------------- + +Es casi seguro que su parche recibirá comentarios de los revisores sobre +maneras en que se pueda mejorar el parche, en forma de respuesta a su +correo electrónico. Debe responder a esos comentarios; ignorar a los +revisores es una buena manera de ser ignorado de vuelta. Simplemente puede +responder a sus correos electrónicos para contestar a sus comentarios. +Revisiones a los comentarios o preguntas que no conduzcan a un cambio de +código deben casi con certeza generar un comentario o una entrada en el +"changelog" para que el próximo revisor entienda lo que está pasando. + +Asegúrese de decirles a los revisores qué cambios está haciendo y de +agradecerles que dediquen su tiempo. La revisión del código es un proceso +agotador y lento, y los revisores a veces se ponen de mal humor. Sin +embargo, incluso en ese caso, responda cortésmente y aborde los problemas +que hayan señalado. Al enviar un siguiente versión, agregue un +``patch changelog`` (registro de cambios en los parches) a la carta de +presentación ("cover letter") o a parches individuales explicando la +diferencia con la presentación anterior (ver +:ref:`sp_the_canonical_patch_format`). + +Consulte Documentation/process/email-clients.rst para obtener +recomendaciones sobre clientes de correo electrónico y normas de etiqueta +en la lista de correo. + +.. _sp_resend_reminders: + +No se desanime o impaciente +--------------------------- + +Después de haber entregado su cambio, sea paciente y espere. Los revisores +son personas ocupadas y es posible que no lleguen a su parche de inmediato. + +Érase una vez, los parches solían desaparecer en el vacío sin comentarios, +pero el proceso de desarrollo funciona mejor que eso ahora. Debería +recibir comentarios dentro de una semana más o menos; si eso no sucede, +asegúrese de que ha enviado sus parches al lugar correcto. Espere un mínimo +de una semana antes de volver a enviar o hacer ping a los revisores, +posiblemente más durante periodos de mucho trabajo ocupados como "merge +windows". + +También está bien volver a enviar el parche o la serie de parches después +de un par de semanas con la palabra "RESEND" (reenviar) añadida a la línea +de asunto:: + + [PATCH Vx RESEND] sub/sys: Resumen condensado de parche + +No incluya "RESEND" cuando envíe una versión modificada de su parche o +serie de parches: "RESEND" solo se aplica al reenvío de un parche o serie +de parches que no hayan sido modificados de ninguna manera con respecto a +la presentación anterior. + + +Incluya PATCH en el asunto +-------------------------- + +Debido al alto tráfico de correo electrónico a Linus y al kernel de Linux, +es común prefijar su línea de asunto con [PATCH]. Esto le permite a Linus +y otros desarrolladores del kernel distinguir más fácilmente los parches de +otras discusiones por correo electrónico. + +``git send-email`` lo hará automáticamente. + + +Firme su trabajo: el Certificado de Origen del Desarrollador +------------------------------------------------------------ + +Para mejorar el seguimiento de quién hizo qué, especialmente con parches +que pueden filtrarse hasta su destino final a través de varias capas de +maintainers, hemos introducido un procedimiento de "sign-off" (aprobación) +en parches que se envían por correo electrónico. + +La aprobación es una simple línea al final de la explicación del parche, +que certifica que usted lo escribió o que tiene derecho a enviarlo como un +parche de código abierto. Las reglas son bastante simples: si usted puede +certificar lo siguiente: + +Certificado de Origen del Desarrollador 1.1 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Al hacer una contribución a este proyecto, certifico que: + + (a) La contribución fue creada en su totalidad o en parte por mí y + tengo derecho a enviarlo bajo la licencia de código abierto + indicada en el documento; o + + (b) La contribución se basa en trabajo previo que, hasta donde yo + soy consciente, está cubierto por una licencia de código + abierto apropiada y tengo el derecho bajo esa licencia de + presentar tal trabajo con modificaciones, ya sean creadas en su + totalidad o en parte por mí, bajo la misma licencia de código + (salvo que sea permitido presentar bajo una licencia diferente), + tal y como se indica en el documento; o + + (c) La contribución me fue proporcionada directamente por alguna + otra persona que certificó (a), (b) o (c) y no he modificado + esto. + + (d) Entiendo y acepto que este proyecto y la contribución + son públicos y que un registro de la contribución (incluyendo + toda la información personal que envío con él, incluida mi + firma) es mantenida indefinidamente y puede ser redistribuida + de manera consistente con este proyecto o la(s) licencia(s) de + código abierto involucradas. + +entonces simplemente incluya una línea que rece:: + + Signed-off-by: Random J Developer <random@developer.example.org> + +usando su nombre real (lamentablemente, no pseudónimos ni contribuciones +anónimas). Esto se hará por usted automáticamente si usa ``git commit -s``. +Las reversiones de código también deben incluir "Signed-off-by". +``git revert -s`` hace eso por usted. + +Algunas personas también ponen etiquetas adicionales al final. Simplemente +serán ignoradas por ahora, pero puede hacer esto para marcar procedimientos +internos de su empresa o simplemente señalar algún detalle especial sobre +la firma. + +Cualquier otro SoB (Signed-off-by:) después del SoB del autor es de +personas que manipulen y transporten el parche, pero no participaron en su +desarrollo. Las cadenas de SoB deben reflejar la ruta **real** del parche +de cómo se propagó a los maintainers y, en última instancia, a Linus, con +la primera entrada de SoB que señala la autoría principal de un solo autor. + + +Cuándo usar Acked-by:, Cc: y Co-developed-by por: +------------------------------------------------- + +La etiqueta Signed-off-by: indica que el firmante estuvo involucrado en el +desarrollo del parche, o que él/ella se encontraba en el camino de entrega +del parche. + +Si una persona no estuvo directamente involucrada en la preparación o +administración de un parche pero desea expresar y registrar su aprobación, +entonces puede pedir que se agregue una línea Acked-by: al registro de +cambios del parche. + +Acked-by: a menudo lo usa el maintainer del código afectado cuando ese +maintainer no contribuyó ni envió el parche. + +Acked-by: no es tan formal como Signed-off-by:. Es una manera de marcar que +el "acker" ha revisado al menos ese parche y ha indicado su aceptación. Por +los merge de parches a veces convertirán manualmente el "sí, me parece bien" +de un acker en un Acked-by: (pero tenga en cuenta que por lo general es +mejor pedir un acuse de recibo explícito). + +Acked-by: no necesariamente indica el reconocimiento de todo el parche. +Por ejemplo, si un parche afecta a varios subsistemas y tiene un +Acked-by: de un maintainer del subsistema, entonces esto generalmente +indica el reconocimiento de solo la parte que afecta el código de ese +maintainer. Buen juicio debe ejercitarse aquí. En caso de duda, la gente +debe consultar la discusión original en los archivos de la lista de correo. + +Si una persona ha tenido la oportunidad de comentar un parche, pero no lo +ha hecho, puede incluir opcionalmente una etiqueta ``Cc:`` al parche. +Esta es la única etiqueta que se puede agregar sin una acción explícita por +parte de la persona a la que se nombre - pero debe indicar que esta persona +fue copiada en el parche. Esta etiqueta documenta que las partes +potencialmente interesadas han sido incluidas en la discusión. + +Co-developed-by: establece que el parche fue co-creado por múltiples +desarrolladores; se utiliza para dar atribución a los coautores (además del +autor atribuido por la etiqueta From:) cuando varias personas trabajan en +un solo parche. Ya que Co-developed-by: denota autoría, cada +Co-developed-by: debe ser inmediatamente seguido de Signed-off-by: del +coautor asociado. Se mantiene el procedimiento estándar, es decir, el orden +de las etiquetas Signed-off-by: debe reflejar el historial cronológico del +parche en la medida de lo posible, independientemente de si el autor se +atribuye a través de From: o Co-developed-by:. Cabe destacar que el último +Signed-off-by: siempre debe ser del desarrollador que envía el parche. + +Tenga en cuenta que la etiqueta From: es opcional cuando el autor From: es +también la persona (y correo electrónico) enumerados en la línea From: del +encabezado del correo electrónico. + +Ejemplo de un parche enviado por el From: autor:: + + <changelog> + + Co-developed-by: Primer coautor <primer@coauthor.example.org> + Signed-off-by: Primer coautor <primer@coauthor.example.org> + Co-developed-by: Segundo coautor <segundo@coautor.ejemplo.org> + Signed-off-by: Segundo coautor <segundo@coautor.ejemplo.org> + Signed-off-by: Autor del From <from@author.example.org> + +Ejemplo de un parche enviado por un Co-developed-by: autor:: + + From: Autor del From <from@author.example.org> + + <changelog> + + Co-developed-by: Co-Autor aleatorio <aleatorio@coauthor.example.org> + Signed-off-by: Coautor aleatorio <aleatorio@coauthor.example.org> + Signed-off-by: Autor del From <from@author.example.org> + Co-developed-by: Coautor que envió <sub@coauthor.example.org> + Signed-off-by: Coautor que envía <sub@coauthor.example.org> + +Uso de Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: y Fixes: +---------------------------------------------------------------------- + +La etiqueta Reported-by (Reportado-por) otorga crédito a las personas que +encuentran errores y los reportan. Por favor, tenga en cuenta que si se +informó de un error en privado, debe pedir primero permiso antes de usar la +etiqueta Reported-by. La etiqueta está destinada a errores; por favor no la +use para acreditar peticiones de características. + +Una etiqueta Tested-by: indica que el parche se probó con éxito (en algún +entorno) por la persona nombrada. Esta etiqueta informa a los maintainers +de que se han realizado algunas pruebas, proporciona un medio para ubicar +"testers" (gente que pruebe) otros parches futuros y asegura el crédito +para los testers. + +Reviewed-by: en cambio, indica que el parche ha sido revisado y encontrado +aceptable de acuerdo con la Declaración del Revisor: + +Declaración de Supervisión del Revisor +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Al ofrecer mi etiqueta Reviewed-by:, afirmo que: + +(a) He llevado a cabo una revisión técnica de este parche para +evaluar su idoneidad y preparación para su inclusión en +el kernel principal. + +(b) Cualquier problema, inquietud o pregunta relacionada con el parche +han sido comunicados al remitente. Estoy satisfecho +con la respuesta del remitente a mis comentarios. + +(c) Si bien puede haber cosas que podrían mejorarse con esta +entrega, creo que es, en este momento, (1) una +modificación valiosa al kernel, y (2) libre de conocidas +cuestiones que argumentarían en contra de su inclusión. + +(d) Si bien he revisado el parche y creo que es correcto, +no hago (a menos que se indique explícitamente en otro lugar) ninguna +garantía o avales de que logrará su definido +propósito o función en cualquier situación dada. + +Una etiqueta Reviewed-by es una declaración de opinión de que el parche es +una modificación apropiada al kernel sin que haya ningún problema grave +a nivel técnico. Cualquier revisor interesado (que haya hecho el trabajo) +puede ofrecer una etiqueta Reviewed-by para un parche. Esta etiqueta sirve +para dar crédito a revisores e informar a los maintainers del grado de +revisión que se ha hecho en el parche. Las etiquetas Reviewed-by, cuando +las otorgan revisores conocidos por entender del tema y realizar +revisiones exhaustivas, normalmente aumentan la probabilidad de que su +parche entre en el kernel. + +Las etiquetas Tested-by y Reviewed-by, una vez recibidas en la lista de +correo por el tester o revisor, deben ser incluidas por el autor de los +parches pertinentes al enviar próximas versiones. Sin embargo, si el parche +ha cambiado sustancialmente en la siguiente versión, es posible que estas +etiquetas ya no sean aplicables y, por lo tanto, deben eliminarse. Por lo +general, se debe mencionar la eliminación de las etiquetas Tested-by o +Reviewed-by de alguien en el registro de cambios del parche (después del +separador '---'). + +Una etiqueta Suggested-by: indica que la idea del parche es sugerida por la +persona nombrada y asegura el crédito a la persona por la idea. Tenga en +cuenta que esto no debe agregarse sin el permiso del "reporter", +especialmente si la idea no fue publicada en un foro público. Dicho esto, +si diligentemente acreditamos a los reporters de ideas, con suerte, se +sentirán inspirados para ayudarnos nuevamente en el futuro. + +Una etiqueta Fixes: indica que el parche corrige un problema en un commit +anterior. Esto se utiliza para facilitar descubrir dónde se originó un +error, lo que puede ayudar a revisar una corrección de errores. Esta +etiqueta también ayuda al equipo del kernel estable a determinar qué +versiones estables del kernel deberían recibir su corrección. Este es el +método preferido para indicar un error corregido por el parche. Revise +:ref:`describe_changes` para más detalles. + +Nota: Adjuntar una etiqueta Fixes: no subvierte las reglas estables del +proceso del kernel ni el requisito de CC: stable@vger.kernel.org en todos +los parches candidatos de ramas estables. Para obtener más información, lea +Documentation/process/stable-kernel-rules.rst. + +.. _sp_the_canonical_patch_format: + +Formato de parche canónico +--------------------------- + +Esta sección describe cómo debe darse formato al propio parche. Tenga en +cuenta que, si tiene sus parches almacenados en un repositorio ``git``, el +parche con formato adecuado se puede obtener con ``git format-patch``. Las +herramientas no pueden crear el texto necesario, sin embargo, así que lea +las instrucciones a continuación de todos modos. + +La línea de asunto del parche canónico es:: + + Asunto: [PATCH 001/123] subsistema: frase de resumen + +El cuerpo del mensaje del parche canónico contiene lo siguiente: + + - Una línea ``from`` que especifica el autor del parche, seguida de una + línea vacía (solo es necesario si la persona que envía el parche no es + el autor). + + - El cuerpo de la explicación, línea envuelta en 75 columnas, que se + copiara en el registro de cambios permanente para describir este parche. + + - Una línea vacía. + + - Las líneas ``Signed-off-by:``, descritas anteriormente, que + también vaya en el registro de cambios. + + - Una línea de marcador que contiene simplemente ``---``. + + - Cualquier comentario adicional que no sea adecuado para el registro de + cambios. + + - El parche real (output de ``diff``). + +El formato de la línea de asunto hace que sea muy fácil ordenar los correos +electrónicos alfabéticamente por línea de asunto - prácticamente cualquier +lector de correo electrónico permite esto, ya que debido a que el número de +secuencia se rellena con ceros, el orden numérico y alfabético es el mismo. + +El ``subsistema`` en el asunto del correo electrónico debe identificar qué +área o subsistema del kernel está siendo parcheado. + +La ``frase de resumen`` en el Asunto del correo electrónico debe describir +de forma concisa el parche que contiene ese correo electrónico. La +``frase resumen`` no debe ser un nombre de archivo. No use la mismo ``frase +resumen`` para cada parche en una serie completa de parches (donde una +`` serie de parches`` (patch series) es una secuencia ordenada de múltiples +parches relacionados). + +Tenga en cuenta que la ``frase de resumen`` de su correo electrónico se +convierte en un identificador global único para ese parche. Se propaga por +hasta el registro de cambios de ``git``. La ``frase resumida`` se puede +usar más adelante en discusiones de desarrolladores que se refieran al +parche. La gente querrá buscar en Google la ``frase de resumen`` para leer +la discusión al respecto del parche. También será lo único que la gente +podrá ver rápidamente cuando, dos o tres meses después, estén pasando por +quizás miles de parches usando herramientas como ``gitk`` o ``git log +--oneline``. + +Por estas razones, el ``resumen`` no debe tener más de 70-75 caracteres, y +debe describir tanto lo que cambia el parche como por qué el parche podría +ser necesario. Es un reto ser tanto sucinto como descriptivo, pero eso es +lo que un resumen bien escrito debería hacer. + +La ``frase de resumen`` puede estar precedida por etiquetas encerradas en +corchetes: "Asunto: [PATCH <etiqueta>...] <frase de resumen>". Las +etiquetas no se consideran parte de la frase de resumen, pero describen +cómo debería ser tratado el parche. Las etiquetas comunes pueden incluir un +descriptor de versión si las múltiples versiones del parche se han enviado +en respuesta a comentarios (es decir, "v1, v2, v3") o "RFC" para indicar +una solicitud de comentarios. + +Si hay cuatro parches en una serie de parches, los parches individuales +pueden enumerarse así: 1/4, 2/4, 3/4, 4/4. Esto asegura que los +desarrolladores entiendan el orden en que se deben aplicar los parches y +que han revisado o aplicado todos los parches de la serie de parches. + +Aquí hay algunos buenos ejemplos de Asuntos:: + + Asunto: [PATCH 2/5] ext2: mejorar la escalabilidad de la búsqueda de mapas de bits + Asunto: [PATCH v2 27/01] x86: corregir el seguimiento de eflags + Asunto: [PATCH v2] sub/sys: resumen conciso del parche + Asunto: [PATCH v2 M/N] sub/sys: resumen conciso del parche + +La línea ``from`` debe ser la primera línea en el cuerpo del mensaje, +y tiene la forma:: + + From: Autor del parche <autor@ejemplo.com> + +La línea ``From`` especifica quién será acreditado como el autor del parche +en el registro de cambios permanente. Si falta la línea ``from``, entonces +la línea ``From:`` del encabezado del correo electrónico se usará para +determinar el autor del parche en el registro de cambios. + +La explicación estará incluida en el commit del changelog permanente, por +lo que debería tener sentido para un lector competente que hace mucho tiempo +ha olvidado los detalles de la discusión que podrían haber llevado a +este parche. Incluidos los síntomas del fallo que el parche trate +(mensajes de registro del kernel, mensajes de oops, etc.) son especialmente +útiles para personas que podrían estar buscando en los registros de +commits en busca de la aplicación del parche. El texto debe estar escrito +con tal detalle que cuando se lea semanas, meses o incluso años después, +pueda dar al lector la información necesaria y detalles para comprender el +razonamiento de **por qué** se creó el parche. + +Si un parche corrige una falla de compilación, puede que no sea necesario +incluir _todos_ los errores de compilación; pero lo suficiente como para +que sea probable que alguien que busque el parche puede encontrarlo. Como +en la ``frase de resumen``, es importante ser tanto sucinto como +descriptivo. + +La línea marcadora ``---`` cumple el propósito esencial de marcar para +herramientas de manejo de parches donde termina el mensaje de registro de +cambios. + +Un buen uso de los comentarios adicionales después del marcador ``---`` es +para ``diffstat``, para mostrar qué archivos han cambiado, y el número de +líneas insertadas y eliminadas por archivo. Un ``diffstat`` es +especialmente útil en parches más grandes. Si va a incluir un ``diffstat`` +después del marcador ``---``, utilice las opciones ``diffstat`` +``-p 1 -w 70`` para que los nombres de archivo se enumeran desde la parte +superior del árbol de fuentes del kernel y no use demasiado espacio +horizontal (que encaje fácilmente en 80 columnas, tal vez con alguna +indentación). (``git`` genera diffstats apropiados por defecto). + +Otros comentarios relevantes solo en el momento o para el maintainer, pero +no adecuados para el registro de cambios permanente, también debe ir aquí. +Un buen ejemplo de tales comentarios podría ser ``registros de cambios de +parches`` que describen qué ha cambiado entre la versión v1 y v2 del +parche. + +Por favor, ponga esta información **después** de la línea ``---`` que +separa el registro de cambios del resto del parche. La información de la +versión no forma parte del registro de cambios que se incluye con el árbol +git. Es información adicional para los revisores. Si se coloca encima de la +etiquetas de commit, necesita interacción manual para eliminarlo. Si esta +debajo de la línea de separación, se quita automáticamente al aplicar el +parche:: + + <mensaje de commit> + ... + Signed-off-by: Autor <autor@correo> + --- + V2 -> V3: función auxiliar redundante eliminada + V1 -> V2: estilo de código limpio y comentarios de revisión abordados + + ruta/al/archivo | 5+++-- + ... + +Revise más detalles sobre el formato de parche adecuado en las siguientes +referencias + +.. _sp_backtraces: + +Retrocesos en mensajes de confirmación +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Los "backtraces" (deshacer el camino) ayuda a documentar la cadena de +llamadas que conducen a un problema. Sin embargo, no todos los rastreos son +útiles. Por ejemplo, las tempranas cadenas de llamadas de inicio son únicas +y obvias. Sin embargo, al copiar la salida completa de dmesg textualmente, +incluye información que distrae, como marcas de tiempo, listas de módulos, +registro y volcados de pila. + +Por lo tanto, los backtraces más útiles deben contener los datos +relevantes de la información vertida, lo que hace que sea más fácil +centrarse en el verdadero tema. Este es un ejemplo de un backtrace bien +recortado:: + + error de acceso de MSR no verificado: WRMSR a 0xd51 (intentó escribir 0x0000000000000064) + en rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) + Rastreo de llamadas: + mba_wrmsr + update_domains + rdtgroup_mkdir + +.. _sp_explicit_in_reply_to: + +In-Reply-To explicitos en las cabeceras +--------------------------------------- + +Puede ser útil agregar manualmente encabezados In-Reply-To: a un parche +(por ejemplo, al usar ``git send-email``) para asociar el parche con una +discusión anterior relevante, por ejemplo para vincular una corrección de +errores al correo electrónico con el informe de errores. Sin embargo, para +una serie de parches múltiples, generalmente es mejor evitar usar +In-Reply-To: para vincular a versiones anteriores de la serie. De esta +forma, varias versiones del parche no se convierten en un inmanejable +bosque de referencias en clientes de correo electrónico. Si un enlace es +útil, puede usar el redirector https://lore.kernel.org/ (por ejemplo, en +el texto de la carta de introducción del correo electrónico) para vincular +a una versión anterior de la serie de parches. + + +Proporcionar información de árbol base +-------------------------------------- + +Cuando otros desarrolladores reciben sus parches y comienzan el proceso de +revisión, a menudo es útil para ellos saber en qué parte del historial del +árbol deben colocar su trabajo. Esto es particularmente útil para CI +automatizado de procesos que intentan ejecutar una serie de pruebas para +establecer la calidad de su envío antes de que el maintainer comience la +revisión. + +Si está utilizando ``git format-patch`` para generar sus parches, puede +incluir automáticamente la información del árbol base en su envío usando el +parámetro ``--base``. La forma más fácil y conveniente de usar esta opción +es con "topical branches" (ramas de temas):: + + $ git checkout -t -b my-topical-branch master + Branch 'my-topical-branch' set up to track local branch 'master'. + Switched to a new branch 'my-topical-branch' + + [realice sus cambios y ediciones] + + $ git format-patch --base=auto --cover-letter -o outgoing/ master + outgoing/0000-cover-letter.patch + outgoing/0001-First-Commit.patch + outgoing/... + +Cuando abra ``outgoing/0000-cover-letter.patch`` para editar, tenga en +cuenta que tendrá el tráiler ``base-commit:`` al final, que proporciona al +revisor y a las herramientas de CI suficiente información para realizar +correctamente ``git am`` sin preocuparse por los conflictos:: + + $ git checkout -b patch-review [base-commit-id] + Switched to a new branch 'patch-review' + $ git am patches.mbox + Applying: First Commit + Applying: ... + +Consulte ``man git-format-patch`` para obtener más información al respecto +de esta opción. + +.. Note:: + + La función ``--base`` se introdujo en la versión 2.9.0 de git. + +Si no está utilizando git para dar forma a sus parches, aún puede incluir +el mismo tráiler ``base-commit`` para indicar el hash de confirmación del +árbol en que se basa su trabajo. Debe agregarlo en la carta de presentación +o en el primer parche de la serie y debe colocarse ya sea bajo la línea +``---`` o en la parte inferior de todos los demás contenido, justo antes de +su firma del correo electrónico. + + +Referencias +----------- + +"The perfect patch" (tpp) por Andrew Morton. + <https://www.ozlabs.org/~akpm/stuff/tpp.txt> + +"Linux kernel patch submission format" por Jeff Garzik. + <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> + +"How to piss off a kernel subsystem maintainer" por Greg Kroah-Hartman. + <http://www.kroah.com/log/linux/maintainer.html> + + <http://www.kroah.com/log/linux/maintainer-02.html> + + <http://www.kroah.com/log/linux/maintainer-03.html> + + <http://www.kroah.com/log/linux/maintainer-04.html> + + <http://www.kroah.com/log/linux/maintainer-05.html> + + <http://www.kroah.com/log/linux/maintainer-06.html> + +NO!!!! Gente, no mas bombas enormes de parches a linux-kernel@vger.kernel.org! + <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net> + +Kernel Documentation/process/coding-style.rst + +Email de Linus Torvalds sobre la forma canónica de los parches: + <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org> + +"On submitting kernel patches" por Andi Kleen + Algunas estrategias para conseguir incluir cambios complicados o + controvertidos. + + http://halobates.de/on-submitting-patches.pdf diff --git a/Documentation/translations/sp_SP/wrappers/memory-barriers.rst b/Documentation/translations/sp_SP/wrappers/memory-barriers.rst new file mode 100644 index 000000000000..50715b7d51b9 --- /dev/null +++ b/Documentation/translations/sp_SP/wrappers/memory-barriers.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0 + This is a simple wrapper to bring memory-barriers.txt (Spanish + translation) into the RST world until such a time as that file can be + converted directly. + +==================================== +Barreras de Memoria del kernel Linux +==================================== + +.. raw:: latex + + \footnotesize + +.. include:: ../memory-barriers.txt + :literal: + +.. raw:: latex + + \normalsize diff --git a/Documentation/translations/zh_CN/core-api/errseq.rst b/Documentation/translations/zh_CN/core-api/errseq.rst new file mode 100644 index 000000000000..815fb303ea2f --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/errseq.rst @@ -0,0 +1,145 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/errseq.rst + +:翻译: + + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> + +:校译: + + 吴想成 Wu Xiangcheng <bobwxc@email.cn> + +================ +errseq_t数据类型 +================ + +``errseq_t`` 是一种在一个地方记录错误的方法，并允许任意数量的 ``订阅者`` 判断自上 +次采样点以来是否发生了变化。 + +最初的用例是跟踪文件同步系统调用（ ``fsync``, ``fdatasync``, ``msync`` 和 +``sync_file_range`` ）的错误，但它也可以用于其他情况。 + +它被实现为一个无符号的32位值。低位被指定保存错误代码（在1和MAX_ERRNO之间）。高位 +用作计数器。这里是用原子操作而不是锁来完成的，因此可以从任何上下文中调用这些函数。 + +请注意，如果频繁记录新错误，则存在冲突风险，因为我们用作计数器的位很少。 + +为了缓解这种情况，错误值和计数器之间的位被用作一个标志，以判断自记录新值以来是否 +对该值进行了采样。这使我们能够避免在上次记录错误后没有人取样的情况下碰撞计数器。 + +因此，我们得到了一个类似这样的值： + ++--------------------------------------+------+------------------------+ +| 31..13 | 12 | 11..0 | ++--------------------------------------+------+------------------------+ +| 计数器 | 标志 | 错误值 | ++--------------------------------------+------+------------------------+ + +总体思路是让 ``观察者`` 对errseq_t值进行采样，并将其保留为运行游标。该值稍后可用 +于判断自采样完成后是否发生了任何新错误，并原子地记录检查时的状态。这使得我们能在 +一个地方记录错误，然后有许多 ``观察者`` 可以判断自上次检查以来该值是否发生了变化。 + +新的errseq_t应始终清零。全零的errseq_t值是从未出现错误的特殊（但常见）情况。因此， +如果您希望知道自首次初始化以来是否曾经有过错误集，则全零值被用作 ``纪元`` 。 + +API的使用方法 +============= + +让我给你们讲一个关于员工drone的故事。现在，他总体上是个好员工，但公司有点...管理 +繁重。他今天必须向77名主管汇报，明天 ``大老板`` 要从外地赶来，他肯定也会考验这个 +可怜的家伙。 + +他们都把工作交给他去做---多到他都记不住谁交给他什么了，但这并不是什么大问题。主管 +们只想知道他什么时候完成他们迄今为止交给他的所有工作，以及自从他们上次询问以来他 +是否犯了任何错误。 + +他可能在他们实际上并没有交给他的工作上犯了错误，但他无法在那么详细的层面上记录事 +情，他所能记得的只是他最近犯的错误。 + +下面是我们 ``worker_drone`` 的表达式:: + + struct worker_drone { + errseq_t wd_err; /* 用来记录错误 */ + }; + +每天， ``worker_drone`` 都是以一张白纸开始的:: + + struct worker_drone wd; + + wd.wd_err = (errseq_t)0; + +主管们进来后对当天的工作进行初步了解。他们并不关心在他们观察开始之前发生的任何事 +情:: + + struct supervisor { + errseq_t s_wd_err; /* wd_err的私有“游标” */ + spinlock_t s_wd_err_lock; /* 保护s_wd_err */ + } + + struct supervisor su; + + su.s_wd_err = errseq_sample(&wd.wd_err); + spin_lock_init(&su.s_wd_err_lock); + +现在他们开始给他布置任务。每隔几分钟，他们就要求他完成迄今为止交给他的所有工作。 +然后问他是否有犯任何错误:: + + spin_lock(&su.su_wd_err_lock); + err = errseq_check_and_advance(&wd.wd_err, &su.s_wd_err); + spin_unlock(&su.su_wd_err_lock); + +到目前为止，它只是不断返回0。 + +现在，这家公司的老板非常吝啬，给了他不合格的设备来完成他的工作。偶尔设备会出现故 +障，导致他犯错。他重重地叹了一口气，并把它记录下来:: + + errseq_set(&wd.wd_err, -EIO); + +...然后继续工作。主管们最终会再次检查，他们在下次检查时都会发现这个错误。后续的调 +用将返回0，直到记录下另一个错误，此时将向每个调用报告一次。 + +请注意，主管们无法知道他们犯了多少错误，只能知道自上次检查以来是否犯了一个错误， +以及记录的最新值。 + +偶尔，大老板会来抽查，要求员工为他做一次性的工作。他并不像主管们那样全职观察员工， +但他确实需要知道在他的工作处理过程中是否发生了错误。 + +他只需对员工当前的errseq_t进行采样，然后用它来判断后来是否发生了错误:: + + errseq_t since = errseq_sample(&wd.wd_err); + /* 提交一些工作，等待完成 */ + err = errseq_check(&wd.wd_err, since); + +由于他只是要在那个点之后丢弃 ``since`` ，所以他不需要在这里推进它。同时他也不需要 +任何锁，因为它不能被其他人使用。 + +序列化更新errseq_t游标 +====================== + +请注意，errseq_t API在check_and_advance_operation期间不保护errseq_t游标。只有典型 +的错误代码是被原子化处理的。在多任务同时使用同一个errseq_t游标的情况下，对该游标 +的更新进行序列化是很重要的。 + +如果不这样做，那么游标就有可能向后移动。在这种情况下，同一个错误可能被报告多次。 + +因此，通常先执行errseq_check检查是否有任何变化，然后在获取锁后才执行 +errseq_check_and_advance。例如:: + + if (errseq_check(&wd.wd_err, READ_ONCE(su.s_wd_err)) { + /* su.s_wd_err被s_wd_err_lock保护 */ + spin_lock(&su.s_wd_err_lock); + err = errseq_check_and_advance(&wd.wd_err, &su.s_wd_err); + spin_unlock(&su.s_wd_err_lock); + } + +这就避免了自上次检查以来没有任何变化的常见情况下的自旋锁。 + +函数 +==== + +该API在以下内核代码中: + +lib/errseq.c diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst index 37756d240b5e..922cabf7b5dd 100644 --- a/Documentation/translations/zh_CN/core-api/index.rst +++ b/Documentation/translations/zh_CN/core-api/index.rst @@ -48,12 +48,12 @@ circular-buffers generic-radix-tree packing + this_cpu_ops -Todolist: - +======= +Todolist: - this_cpu_ops timekeeping errseq diff --git a/Documentation/translations/zh_CN/core-api/local_ops.rst b/Documentation/translations/zh_CN/core-api/local_ops.rst index 41e4525038e8..eb5423f60f17 100644 --- a/Documentation/translations/zh_CN/core-api/local_ops.rst +++ b/Documentation/translations/zh_CN/core-api/local_ops.rst @@ -185,7 +185,7 @@ UP之间没有不同的行为，在你的架构的 ``local.h`` 中包括 ``asm-g static void __exit test_exit(void) { - del_timer_sync(&test_timer); + timer_shutdown_sync(&test_timer); } module_init(test_init); diff --git a/Documentation/translations/zh_CN/core-api/this_cpu_ops.rst b/Documentation/translations/zh_CN/core-api/this_cpu_ops.rst new file mode 100644 index 000000000000..bea5ee8eb8a0 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/this_cpu_ops.rst @@ -0,0 +1,285 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/this_cpu_ops.rst + +:翻译: + + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> + +:校译: + + 吴想成 Wu Xiangcheng <bobwxc@email.cn> + +============ +this_cpu操作 +============ + +:作者: Christoph Lameter, 2014年8月4日 +:作者: Pranith Kumar, 2014年8月2日 + +this_cpu操作是一种优化访问与当前执行处理器相关的每CPU变量的方法。这是通过使用段寄 +存器（或专用寄存器，cpu在其中永久存储特定处理器的每CPU区域的起始）来完成的。 + +this_cpu操作将每CPU变量的偏移量添加到处理器特定的每CPU基址上，并将该操作编码到对 +每CPU变量进行操作的指令中。 + +这意味着在偏移量的计算和对数据的操作之间不存在原子性问题。因此，没有必要禁用抢占 +或中断来确保处理器在计算地址和数据操作之间不被改变。 + +读取-修改-写入操作特别值得关注。通常处理器具有特殊的低延迟指令，可以在没有典型同 +步开销的情况下运行，但仍提供某种宽松的原子性保证。例如，x86可以执行RMW（读取， +修改，写入）指令，如同inc/dec/cmpxchg，而无需锁前缀和相关的延迟损失。 + +对没有锁前缀的变量的访问是不同步的，也不需要同步，因为我们处理的是当前执行的处理 +器所特有的每CPU数据。只有当前的处理器可以访问该变量，因此系统中的其他处理器不存在 +并发性问题。 + +请注意，远程处理器对每CPU区域的访问是特殊情况，可能会影响通过 ``this_cpu_*`` 的本 +地RMW操作的性能和正确性（远程写操作）。 + +this_cpu操作的主要用途是优化计数器操作。 + +定义了以下具有隐含抢占保护的this_cpu()操作。可以使用这些操作而不用担心抢占和中断:: + + this_cpu_read(pcp) + this_cpu_write(pcp, val) + this_cpu_add(pcp, val) + this_cpu_and(pcp, val) + this_cpu_or(pcp, val) + this_cpu_add_return(pcp, val) + this_cpu_xchg(pcp, nval) + this_cpu_cmpxchg(pcp, oval, nval) + this_cpu_cmpxchg_double(pcp1, pcp2, oval1, oval2, nval1, nval2) + this_cpu_sub(pcp, val) + this_cpu_inc(pcp) + this_cpu_dec(pcp) + this_cpu_sub_return(pcp, val) + this_cpu_inc_return(pcp) + this_cpu_dec_return(pcp) + + +this_cpu操作的内部工作 +---------------------- + +在x86上，fs:或gs:段寄存器包含每CPU区域的基址。这样就可以简单地使用段覆盖，将每CPU +相对地址重定位到处理器适当的每CPU区域。所以对每CPU基址的重定位是通过段寄存器前缀 +在指令中编码完成的。 + +例如:: + + DEFINE_PER_CPU(int, x); + int z; + + z = this_cpu_read(x); + +产生的单指令为:: + + mov ax, gs:[x] + +而不是像每CPU操作那样，先是一系列的地址计算，然后从该地址获取。在this_cpu_ops之前， +这样的序列还需要先禁用/启用抢占功能，以防止内核在计算过程中将线程移动到不同的处理 +器上。 + +请思考下面this_cpu操作:: + + this_cpu_inc(x) + +这将产生如下单指令（无锁前缀！）:: + + inc gs:[x] + +而不是在没有段寄存器的情况下所需要的以下操作:: + + int *y; + int cpu; + + cpu = get_cpu(); + y = per_cpu_ptr(&x, cpu); + (*y)++; + put_cpu(); + +请注意，这些操作只能用于为特定处理器保留的每CPU数据。如果不在上下文代码中禁用抢占， +``this_cpu_inc()`` 将仅保证每CPU的某一个计数器被正确地递增，但不能保证操作系统不 +会在this_cpu指令执行的前后直接移动该进程。一般来说，这意味着每个处理器的单个计数 +器的值是没有意义的。所有每CPU计数器的总和才是唯一有意义的值。 + +每CPU变量的使用是出于性能的考虑。如果多个处理器同时处理相同的代码路径，可以避免缓 +存行跳转。每个处理器都有自己的每CPU变量，因此不会发生并发缓存行更新。为这种优化必 +须付出的代价是，当需要计数器的值时要将每CPU计数器相加。 + + +特殊的操作 +---------- + +:: + + y = this_cpu_ptr(&x) + +使用每CPU变量的偏移量(&x!)，并返回属于当前执行处理器的每CPU变量的地址。 +``this_cpu_ptr`` 避免了通用 ``get_cpu``/``put_cpu`` 序列所需的多个步骤。没有可用 +的处理器编号。相反，本地每CPU区域的偏移量只是简单地添加到每CPU偏移量上。 + +请注意，这个操作通常是在抢占被禁用后再在代码段中使用。然后该指针用来访问临界区中 +的本地每CPU数据。当重新启用抢占时，此指针通常不再有用，因为它可能不再指向当前处理 +器的每CPU数据。 + +每CPU变量和偏移量 +----------------- + +每CPU变量相对于每CPU区域的起始点是有偏移的。它们没有地址，尽管代码里看起来像有一 +样。不能直接对偏移量解引用，必须用处理器每CPU区域基指针加上偏移量，以构成有效地址。 + +因此，在每CPU操作的上下文之外使用x或&x是无效的，这种行为通常会被当作一个空指针的 +解引用来处理。 + +:: + + DEFINE_PER_CPU(int, x); + +在每CPU操作的上下文中，上面表达式说明x是一个每CPU变量。大多数this_cpu操作都需要一 +个cpu变量。 + +:: + + int __percpu *p = &x; + +&x和p是每CPU变量的偏移量。 ``this_cpu_ptr()`` 使用每CPU变量的偏移量，这让它看起来 +有点奇怪。 + + +每CPU结构体字段的操作 +--------------------- + +假设我们有一个每CPU结构:: + + struct s { + int n,m; + }; + + DEFINE_PER_CPU(struct s, p); + + +这些字段的操作非常简单:: + + this_cpu_inc(p.m) + + z = this_cpu_cmpxchg(p.m, 0, 1); + + +如果我们有一个相对于结构体s的偏移量:: + + struct s __percpu *ps = &p; + + this_cpu_dec(ps->m); + + z = this_cpu_inc_return(ps->n); + + +如果我们后面不使用 ``this_cpu ops`` 来操作字段，则指针的计算可能需要使用 +``this_cpu_ptr()``:: + + struct s *pp; + + pp = this_cpu_ptr(&p); + + pp->m--; + + z = pp->n++; + + +this_cpu ops的变体 +------------------ + +this_cpu的操作是中断安全的。一些架构不支持这些每CPU的本地操作。在这种情况下，该操 +作必须被禁用中断的代码所取代，然后做那些保证是原子的操作，再重新启用中断。当然这 +样做是很昂贵的。如果有其他原因导致调度器不能改变我们正在执行的处理器，那么就没有 +理由禁用中断了。为此，我们提供了以下__this_cpu操作。 + +这些操作不能保证并发中断或抢占。如果在中断上下文中不使用每CPU变量并且调度程序无法 +抢占，那么它们是安全的。如果在操作进行时仍有中断发生，并且中断也修改了变量，则无 +法保证RMW操作是安全的:: + + __this_cpu_read(pcp) + __this_cpu_write(pcp, val) + __this_cpu_add(pcp, val) + __this_cpu_and(pcp, val) + __this_cpu_or(pcp, val) + __this_cpu_add_return(pcp, val) + __this_cpu_xchg(pcp, nval) + __this_cpu_cmpxchg(pcp, oval, nval) + __this_cpu_cmpxchg_double(pcp1, pcp2, oval1, oval2, nval1, nval2) + __this_cpu_sub(pcp, val) + __this_cpu_inc(pcp) + __this_cpu_dec(pcp) + __this_cpu_sub_return(pcp, val) + __this_cpu_inc_return(pcp) + __this_cpu_dec_return(pcp) + + +将增加x，并且不会回退到在无法通过地址重定位和同一指令中的读取-修改-写入操作实现原 +子性的平台上禁用中断的代码。 + + +&this_cpu_ptr(pp)->n 对比 this_cpu_ptr(&pp->n) +---------------------------------------------- + +第一个操作使用偏移量并形成一个地址，然后再加上n字段的偏移量。这可能会导致编译器产 +生两条加法指令。 + +第二个操作先加上两个偏移量，然后进行重定位。恕我直言，第二种形式看起来更干净，而 +且更容易与 ``()`` 结合。第二种形式也与 ``this_cpu_read()`` 和大家的使用方式一致。 + + +远程访问每CPU数据 +----------------- + +每CPU数据结构被设计为由一个CPU独占使用。如果您按预期使用变量，则 ``this_cpu_ops()`` +保证是 ``原子的`` ，因为没有其他CPU可以访问这些数据结构。 + +在某些特殊情况下，您可能需要远程访问每CPU数据结构。通常情况下，进行远程读访问是安 +全的，这经常是为了统计计数器值。远程写访问可能会出现问题，因为this_cpu操作没有锁 +语义。远程写可能会干扰this_cpu RMW操作。 + +除非绝对必要，否则强烈建议不要对每CPU数据结构进行远程写访问。请考虑使用IPI来唤醒 +远程CPU，并对其每CPU区域进行更新。 + +要远程访问每CPU数据结构，通常使用 ``per_cpu_ptr()`` 函数:: + + + DEFINE_PER_CPU(struct data, datap); + + struct data *p = per_cpu_ptr(&datap, cpu); + +这清楚地表明，我们正准备远程访问每CPU区域。 + +您还可以执行以下操作以将datap偏移量转换为地址:: + + struct data *p = this_cpu_ptr(&datap); + +但是，将通过this_cpu_ptr计算的指针传递给其他cpu是不寻常的，应该避免。 + +远程访问通常只用于读取另一个cpu的每CPU数据状态。由于this_cpu操作宽松的同步要求， +写访问可能会导致奇特的问题。 + +下面的情况说明了写入操作的一些问题，由于两个每CPU变量共享一个缓存行，但宽松的同步 +仅应用于更新缓存行的一个进程。 + +考虑以下示例:: + + + struct test { + atomic_t a; + int b; + }; + + DEFINE_PER_CPU(struct test, onecacheline); + +如果一个处理器远程更新字段 ``a`` ，而本地处理器将使用this_cpu ops来更新字段 ``b`` ， +会发生什么情况，这一点值得注意。应避免在同一缓存行内同时访问数据。此外，可能还需 +要进行代价高昂的同步。在这种情况下，通常建议使用IPI，而不是远程写入另一个处理器的 +每CPU区域。 + +即使在远程写很少的情况下，请记住远程写将从最有可能访问它的处理器中逐出缓存行。如 +果处理器唤醒时发现每CPU区域缺少本地缓存行，其性能和唤醒时间将受到影响。 diff --git a/Documentation/translations/zh_CN/doc-guide/index.rst b/Documentation/translations/zh_CN/doc-guide/index.rst index 5151953c196f..78c2e9a1697f 100644 --- a/Documentation/translations/zh_CN/doc-guide/index.rst +++ b/Documentation/translations/zh_CN/doc-guide/index.rst @@ -19,7 +19,7 @@ contributing maintainer-profile -.. only:: 子项目与HTML +.. only:: subproject and html 目录 ==== diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index ec99ef5fe990..3660a3451c86 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -71,6 +71,7 @@ TODOList: dev-tools/index dev-tools/testing-overview kernel-hacking/index + rust/index TODOList: @@ -90,12 +91,12 @@ TODOList: admin-guide/index admin-guide/reporting-issues.rst + userspace-api/index TODOList: * 内核构建系统 <kbuild/index> * 用户空间工具 <tools/index> -* userspace-api/index 也可参考独立于内核文档的 `Linux 手册页 <https://www.kernel.org/doc/man-pages/>`_ 。 @@ -124,13 +125,13 @@ TODOList: 其他文档 -------- -有几份未排序的文档似乎不适合放在文档的其他部分，或者可能需要进行一些调整和/或 +有几份未分类的文档似乎不适合放在文档的其他部分，或者可能需要进行一些调整和/或 转换为reStructureText格式，也有可能太旧。 -TODOList: - -* staging/index +.. toctree:: + :maxdepth: 2 + staging/index 索引和表格 ---------- diff --git a/Documentation/translations/zh_CN/loongarch/booting.rst b/Documentation/translations/zh_CN/loongarch/booting.rst new file mode 100644 index 000000000000..fb6440c438f0 --- /dev/null +++ b/Documentation/translations/zh_CN/loongarch/booting.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/loongarch/booting.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +==================== +启动 Linux/LoongArch +==================== + +:作者: 司延腾 <siyanteng@loongson.cn> +:日期: 2022年11月18日 + +BootLoader传递给内核的信息 +========================== + +LoongArch支持ACPI和FDT启动，需要传递给内核的信息包括memmap、initrd、cmdline、可 +选的ACPI/FDT表等。 + +内核在 `kernel_entry` 入口处被传递以下参数: + + - a0 = efi_boot: `efi_boot` 是一个标志，表示这个启动环境是否完全符合UEFI + 的要求。 + + - a1 = cmdline: `cmdline` 是一个指向内核命令行的指针。 + + - a2 = systemtable: `systemtable` 指向EFI的系统表，在这个阶段涉及的所有 + 指针都是物理地址。 + +Linux/LoongArch内核镜像文件头 +============================= + +内核镜像是EFI镜像。作为PE文件，它们有一个64字节的头部结构体，如下所示:: + + u32 MZ_MAGIC /* "MZ", MS-DOS 头 */ + u32 res0 = 0 /* 保留 */ + u64 kernel_entry /* 内核入口点 */ + u64 _end - _text /* 内核镜像有效大小 */ + u64 load_offset /* 加载内核镜像相对内存起始地址的偏移量 */ + u64 res1 = 0 /* 保留 */ + u64 res2 = 0 /* 保留 */ + u64 res3 = 0 /* 保留 */ + u32 LINUX_PE_MAGIC /* 魔术数 */ + u32 pe_header - _head /* 到PE头的偏移量 */ diff --git a/Documentation/translations/zh_CN/loongarch/index.rst b/Documentation/translations/zh_CN/loongarch/index.rst index 7d23eb78379d..0273a08342f7 100644 --- a/Documentation/translations/zh_CN/loongarch/index.rst +++ b/Documentation/translations/zh_CN/loongarch/index.rst @@ -14,6 +14,7 @@ LoongArch体系结构 :numbered: introduction + booting irq-chip-model features diff --git a/Documentation/translations/zh_CN/loongarch/introduction.rst b/Documentation/translations/zh_CN/loongarch/introduction.rst index 128878f5bb70..470c38ae2caf 100644 --- a/Documentation/translations/zh_CN/loongarch/introduction.rst +++ b/Documentation/translations/zh_CN/loongarch/introduction.rst @@ -70,8 +70,8 @@ LA64中每个寄存器为64位宽。 ``$r0`` 的内容总是固定为0，而其 ================= ================== =================== ========== .. note:: - 注意：在一些遗留代码中有时可能见到 ``$v0`` 和 ``$v1`` ，它们是 - ``$a0`` 和 ``$a1`` 的别名，属于已经废弃的用法。 + 注意：在一些遗留代码中有时可能见到 ``$fv0`` 和 ``$fv1`` ，它们是 + ``$fa0`` 和 ``$fa1`` 的别名，属于已经废弃的用法。 向量寄存器 @@ -338,15 +338,15 @@ Loongson与LoongArch的开发者网站（软件与文档资源）： LoongArch指令集架构的文档： - https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.00-CN.pdf （中文版） + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.02-CN.pdf （中文版） - https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.00-EN.pdf （英文版） + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.02-EN.pdf （英文版） LoongArch的ELF psABI文档： - https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v1.00-CN.pdf （中文版） + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.00-CN.pdf （中文版） - https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v1.00-EN.pdf （英文版） + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.00-EN.pdf （英文版） Loongson与LoongArch的Linux内核源码仓库： diff --git a/Documentation/translations/zh_CN/rust/arch-support.rst b/Documentation/translations/zh_CN/rust/arch-support.rst new file mode 100644 index 000000000000..afbd02afec45 --- /dev/null +++ b/Documentation/translations/zh_CN/rust/arch-support.rst @@ -0,0 +1,23 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/rust/arch-support.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +架构支持 +======== + +目前，Rust编译器（``rustc``）使用LLVM进行代码生成，这限制了可以支持的目标架构。此外，对 +使用LLVM/Clang构建内核的支持也有所不同（请参见 Documentation/kbuild/llvm.rst ）。这 +种支持对于使用 ``libclang`` 的 ``bindgen`` 来说是必需的。 + +下面是目前可以工作的架构的一般总结。支持程度与 ``MAINTAINERS`` 文件中的``S`` 值相对应: + +============ ================ ============================================== +架构 支持水平 限制因素 +============ ================ ============================================== +``x86`` Maintained 只有 ``x86_64`` +============ ================ ============================================== diff --git a/Documentation/translations/zh_CN/rust/coding-guidelines.rst b/Documentation/translations/zh_CN/rust/coding-guidelines.rst new file mode 100644 index 000000000000..6c0bdbbc5a2a --- /dev/null +++ b/Documentation/translations/zh_CN/rust/coding-guidelines.rst @@ -0,0 +1,192 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/rust/coding-guidelines.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +编码指南 +======== + +本文档描述了如何在内核中编写Rust代码。 + + +风格和格式化 +------------ + +代码应该使用 ``rustfmt`` 进行格式化。这样一来，一个不时为内核做贡献的人就不需要再去学 +习和记忆一个样式指南了。更重要的是，审阅者和维护者不需要再花时间指出风格问题，这样就可以 +减少补丁落地所需的邮件往返。 + +.. note:: ``rustfmt`` 不检查注释和文档的约定。因此，这些仍然需要照顾到。 + +使用 ``rustfmt`` 的默认设置。这意味着遵循Rust的习惯性风格。例如，缩进时使用4个空格而 +不是制表符。 + +在输入、保存或提交时告知编辑器/IDE进行格式化是很方便的。然而，如果因为某些原因需要在某 +个时候重新格式化整个内核Rust的源代码，可以运行以下程序:: + + make LLVM=1 rustfmt + +也可以检查所有的东西是否都是格式化的（否则就打印一个差异），例如对于一个CI，用:: + + make LLVM=1 rustfmtcheck + +像内核其他部分的 ``clang-format`` 一样， ``rustfmt`` 在单个文件上工作，并且不需要 +内核配置。有时，它甚至可以与破碎的代码一起工作。 + + +注释 +---- + +“普通”注释（即以 ``//`` 开头，而不是 ``///`` 或 ``//!`` 开头的代码文档）的写法与文 +档注释相同，使用Markdown语法，尽管它们不会被渲染。这提高了一致性，简化了规则，并允许在 +这两种注释之间更容易地移动内容。比如说: + +.. code-block:: rust + + // `object` is ready to be handled now. + f(object); + +此外，就像文档一样，注释在句子的开头要大写，并以句号结束（即使是单句）。这包括 ``// SAFETY:``, +``// TODO:`` 和其他“标记”的注释，例如: + +.. code-block:: rust + + // FIXME: The error should be handled properly. + +注释不应该被用于文档的目的：注释是为了实现细节，而不是为了用户。即使源文件的读者既是API +的实现者又是用户，这种区分也是有用的。事实上，有时同时使用注释和文档是很有用的。例如，用 +于 ``TODO`` 列表或对文档本身的注释。对于后一种情况，注释可以插在中间；也就是说，离要注 +释的文档行更近。对于其他情况，注释会写在文档之后，例如: + +.. code-block:: rust + + /// Returns a new [`Foo`]. + /// + /// # Examples + /// + // TODO: Find a better example. + /// ``` + /// let foo = f(42); + /// ``` + // FIXME: Use fallible approach. + pub fn f(x: i32) -> Foo { + // ... + } + +一种特殊的注释是 ``// SAFETY:`` 注释。这些注释必须出现在每个 ``unsafe`` 块之前，它们 +解释了为什么该块内的代码是正确/健全的，即为什么它在任何情况下都不会触发未定义行为，例如: + +.. code-block:: rust + + // SAFETY: `p` is valid by the safety requirements. + unsafe { *p = 0; } + +``// SAFETY:`` 注释不能与代码文档中的 ``# Safety`` 部分相混淆。 ``# Safety`` 部 +分指定了（函数）调用者或（特性）实现者需要遵守的契约。 +``// SAFETY:`` 注释显示了为什么一个（函数）调用者或（特性）实现者实际上尊重了 +``# Safety`` 部分或语言参考中的前提条件。 + + +代码文档 +-------- + +Rust内核代码不像C内核代码那样被记录下来（即通过kernel-doc）。取而代之的是用于记录Rust +代码的常用系统：rustdoc工具，它使用Markdown（一种轻量级的标记语言）。 + +要学习Markdown，外面有很多指南。例如： + +https://commonmark.org/help/ + +一个记录良好的Rust函数可能是这样的: + +.. code-block:: rust + + /// Returns the contained [`Some`] value, consuming the `self` value, + /// without checking that the value is not [`None`]. + /// + /// # Safety + /// + /// Calling this method on [`None`] is *[undefined behavior]*. + /// + /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html + /// + /// # Examples + /// + /// ``` + /// let x = Some("air"); + /// assert_eq!(unsafe { x.unwrap_unchecked() }, "air"); + /// ``` + pub unsafe fn unwrap_unchecked(self) -> T { + match self { + Some(val) => val, + + // SAFETY: The safety contract must be upheld by the caller. + None => unsafe { hint::unreachable_unchecked() }, + } + } + +这个例子展示了一些 ``rustdoc`` 的特性和内核中遵循的一些惯例: + + - 第一段必须是一个简单的句子，简要地描述被记录的项目的作用。进一步的解释必须放在额 + 外的段落中。 + + - 不安全的函数必须在 ``# Safety`` 部分记录其安全前提条件。 + + - 虽然这里没有显示，但如果一个函数可能会恐慌，那么必须在 ``# Panics`` 部分描述发 + 生这种情况的条件。 + + 请注意，恐慌应该是非常少见的，只有在有充分理由的情况下才会使用。几乎在所有的情况下， + 都应该使用一个可失败的方法，通常是返回一个 ``Result``。 + + - 如果提供使用实例对读者有帮助的话，必须写在一个叫做``# Examples``的部分。 + + - Rust项目（函数、类型、常量……）必须有适当的链接(``rustdoc`` 会自动创建一个 + 链接)。 + + - 任何 ``unsafe`` 的代码块都必须在前面加上一个 ``// SAFETY:`` 的注释，描述里面 + 的代码为什么是正确的。 + + 虽然有时原因可能看起来微不足道，但写这些注释不仅是记录已经考虑到的问题的好方法， + 最重要的是，它提供了一种知道没有额外隐含约束的方法。 + +要了解更多关于如何编写Rust和拓展功能的文档，请看看 ``rustdoc`` 这本书，网址是: + + https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html + + +命名 +---- + +Rust内核代码遵循通常的Rust命名空间: + + https://rust-lang.github.io/api-guidelines/naming.html + +当现有的C语言概念（如宏、函数、对象......）被包装成Rust抽象时，应该使用尽可能接近C语 +言的名称，以避免混淆，并在C语言和Rust语言之间来回切换时提高可读性。例如，C语言中的 +``pr_info`` 这样的宏在Rust中的命名是一样的。 + +说到这里，应该调整大小写以遵循Rust的命名惯例，模块和类型引入的命名间隔不应该在项目名称 +中重复。例如，在包装常量时，如: + +.. code-block:: c + + #define GPIO_LINE_DIRECTION_IN 0 + #define GPIO_LINE_DIRECTION_OUT 1 + +在Rust中的等价物可能是这样的（忽略文档）。: + +.. code-block:: rust + + pub mod gpio { + pub enum LineDirection { + In = bindings::GPIO_LINE_DIRECTION_IN as _, + Out = bindings::GPIO_LINE_DIRECTION_OUT as _, + } + } + +也就是说， ``GPIO_LINE_DIRECTION_IN`` 的等价物将被称为 ``gpio::LineDirection::In`` 。 +特别是，它不应该被命名为 ``gpio::gpio_line_direction::GPIO_LINE_DIRECTION_IN`` 。 diff --git a/Documentation/translations/zh_CN/rust/general-information.rst b/Documentation/translations/zh_CN/rust/general-information.rst new file mode 100644 index 000000000000..6b91dfe1834a --- /dev/null +++ b/Documentation/translations/zh_CN/rust/general-information.rst @@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/rust/general-information.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + + +基本信息 +======== + +本文档包含了在内核中使用Rust支持时需要了解的有用信息。 + + +代码文档 +-------- + +Rust内核代码使用其内置的文档生成器 ``rustdoc`` 进行记录。 + +生成的HTML文档包括集成搜索、链接项（如类型、函数、常量）、源代码等。它们可以在以下地址阅读 +（TODO：当在主线中时链接，与其他文档一起生成）： + + http://kernel.org/ + +这些文档也可以很容易地在本地生成和阅读。这相当快（与编译代码本身的顺序相同），而且不需要特 +殊的工具或环境。这有一个额外的好处，那就是它们将根据所使用的特定内核配置进行定制。要生成它 +们，请使用 ``rustdoc`` 目标，并使用编译时使用的相同调用，例如:: + + make LLVM=1 rustdoc + +要在你的网络浏览器中本地阅读该文档，请运行如:: + + xdg-open rust/doc/kernel/index.html + +要了解如何编写文档，请看 coding-guidelines.rst 。 + + +额外的lints +----------- + +虽然 ``rustc`` 是一个非常有用的编译器，但一些额外的lints和分析可以通过 ``clippy`` +（一个Rust linter）来实现。要启用它，请将CLIPPY=1传递到用于编译的同一调用中，例如:: + + make LLVM=1 CLIPPY=1 + +请注意，Clippy可能会改变代码生成，因此在构建产品内核时不应该启用它。 + +抽象和绑定 +---------- + +抽象是用Rust代码包装来自C端的内核功能。 + +为了使用来自C端的函数和类型，需要创建绑定。绑定是Rust对那些来自C端的函数和类型的声明。 + +例如，人们可以在Rust中写一个 ``Mutex`` 抽象，它从C端包装一个 ``Mutex结构体`` ，并 +通过绑定调用其函数。 + +抽象并不能用于所有的内核内部API和概念，但随着时间的推移，我们打算扩大覆盖范围。“Leaf” +模块（例如，驱动程序）不应该直接使用C语言的绑定。相反，子系统应该根据需要提供尽可能安 +全的抽象。 + + +有条件的编译 +------------ + +Rust代码可以访问基于内核配置的条件性编译: + +.. code-block:: rust + + #[cfg(CONFIG_X)] // Enabled (`y` or `m`) + #[cfg(CONFIG_X="y")] // Enabled as a built-in (`y`) + #[cfg(CONFIG_X="m")] // Enabled as a module (`m`) + #[cfg(not(CONFIG_X))] // Disabled diff --git a/Documentation/translations/zh_CN/rust/index.rst b/Documentation/translations/zh_CN/rust/index.rst new file mode 100644 index 000000000000..b01f887e7167 --- /dev/null +++ b/Documentation/translations/zh_CN/rust/index.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/rust/index.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +Rust +==== + +与内核中的Rust有关的文档。若要开始在内核中使用Rust，请阅读quick-start.rst指南。 + +.. toctree:: + :maxdepth: 1 + + quick-start + general-information + coding-guidelines + arch-support + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/rust/quick-start.rst b/Documentation/translations/zh_CN/rust/quick-start.rst new file mode 100644 index 000000000000..a4b8e8a50a89 --- /dev/null +++ b/Documentation/translations/zh_CN/rust/quick-start.rst @@ -0,0 +1,211 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/rust/quick-start.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + + +快速入门 +======== + +本文介绍了如何开始使用Rust进行内核开发。 + + +构建依赖 +-------- + +本节描述了如何获取构建所需的工具。 + +其中一些依赖也许可以从Linux发行版中获得，包名可能是 ``rustc`` , ``rust-src`` , +``rust-bindgen`` 等。然而，在写这篇文章的时候，它们很可能还不够新，除非发行版跟踪最 +新的版本。 + +为了方便检查是否满足要求，可以使用以下目标:: + + make LLVM=1 rustavailable + +这会触发与Kconfig用来确定是否应该启用 ``RUST_IS_AVAILABLE`` 相同的逻辑；不过，如 +果Kconfig认为不该启用，它会列出未满足的条件。 + + +rustc +***** + +需要一个特定版本的Rust编译器。较新的版本可能会也可能不会工作，因为就目前而言，内核依赖 +于一些不稳定的Rust特性。 + +如果使用的是 ``rustup`` ，请进入检出的源代码目录并运行:: + + rustup override set $(scripts/min-tool-version.sh rustc) + +或者从以下网址获取一个独立的安装程序或安装 ``rustup`` ： + + https://www.rust-lang.org + + +Rust标准库源代码 +**************** + +Rust标准库的源代码是必需的，因为构建系统会交叉编译 ``core`` 和 ``alloc`` 。 + +如果正在使用 ``rustup`` ，请运行:: + + rustup component add rust-src + +这些组件是按工具链安装的，因此以后升级Rust编译器版本需要重新添加组件。 + +否则，如果使用独立的安装程序，可以将Rust仓库克隆到工具链的安装文件夹中:: + + git clone --recurse-submodules \ + --branch $(scripts/min-tool-version.sh rustc) \ + https://github.com/rust-lang/rust \ + $(rustc --print sysroot)/lib/rustlib/src/rust + +在这种情况下，以后升级Rust编译器版本需要手动更新这个克隆的仓库。 + + +libclang +******** + +``bindgen`` 使用 ``libclang`` （LLVM的一部分）来理解内核中的C代码，这意味着需要安 +装LLVM；同在开启 ``CC=clang`` 或 ``LLVM=1`` 时编译内核一样。 + +Linux发行版中可能会有合适的包，所以最好先检查一下。 + +适用于部分系统和架构的二进制文件也可到以下网址下载： + + https://releases.llvm.org/download.html + +或者自行构建LLVM，这需要相当长的时间，但并不是一个复杂的过程： + + https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm + +请参阅 Documentation/kbuild/llvm.rst 了解更多信息，以及获取预构建版本和发行包 +的进一步方法。 + + +bindgen +******* + +内核的C端绑定是在构建时使用 ``bindgen`` 工具生成的。这需要特定的版本。 + +通过以下方式安装它（注意，这将从源码下载并构建该工具）:: + + cargo install --locked --version $(scripts/min-tool-version.sh bindgen) bindgen + + +开发依赖 +-------- + +本节解释了如何获取开发所需的工具。也就是说，在构建内核时不需要这些工具。 + + +rustfmt +******* + +``rustfmt`` 工具被用来自动格式化所有的Rust内核代码，包括生成的C绑定（详情请见 +coding-guidelines.rst ）。 + +如果使用的是 ``rustup`` ，它的 ``默认`` 配置文件已经安装了这个工具，因此不需要做什么。 +如果使用的是其他配置文件，可以手动安装该组件:: + + rustup component add rustfmt + +独立的安装程序也带有 ``rustfmt`` 。 + + +clippy +****** + +``clippy`` 是一个Rust linter。运行它可以为Rust代码提供额外的警告。它可以通过向 ``make`` +传递 ``CLIPPY=1`` 来运行（关于细节，详见 general-information.rst ）。 + +如果正在使用 ``rustup`` ，它的 ``默认`` 配置文件已经安装了这个工具，因此不需要做什么。 +如果使用的是另一个配置文件，该组件可以被手动安装:: + + rustup component add clippy + +独立的安装程序也带有 ``clippy`` 。 + + +cargo +***** + +``cargo`` 是Rust的本地构建系统。目前需要它来运行测试，因为它被用来构建一个自定义的标准 +库，其中包含了内核中自定义 ``alloc`` 所提供的设施。测试可以使用 ``rusttest`` Make 目标 +来运行。 + +如果使用的是 ``rustup`` ，所有的配置文件都已经安装了该工具，因此不需要再做什么。 + +独立的安装程序也带有 ``cargo`` 。 + + +rustdoc +******* + +``rustdoc`` 是Rust的文档工具。它为Rust代码生成漂亮的HTML文档（详情请见 general-information.rst ）。 + +``rustdoc`` 也被用来测试文档化的Rust代码中提供的例子（称为doctests或文档测试）。 +``rusttest`` 是本功能的Make目标。 + +如果使用的是 ``rustup`` ，所有的配置文件都已经安装了这个工具，因此不需要做什么。 + +独立的安装程序也带有 ``rustdoc`` 。 + + +rust-analyzer +************* + +`rust-analyzer <https://rust-analyzer.github.io/>`_ 语言服务器可以和许多编辑器 +一起使用，以实现语法高亮、补全、转到定义和其他功能。 + +``rust-analyzer`` 需要一个配置文件， ``rust-project.json``, 它可以由 ``rust-analyzer`` +Make 目标生成。 + + +配置 +---- + +Rust支持（CONFIG_RUST）需要在 ``General setup`` 菜单中启用。在其他要求得到满足的情 +况下，该选项只有在找到合适的Rust工具链时才会显示（见上文）。相应的，这将使依赖Rust的其 +他选项可见。 + +之后，进入:: + + Kernel hacking + -> Sample kernel code + -> Rust samples + +并启用一些内置或可加载的样例模块。 + + +构建 +---- + +用完整的LLVM工具链构建内核是目前支持的最佳设置。即:: + + make LLVM=1 + +对于不支持完整LLVM工具链的架构，使用:: + + make CC=clang + +使用GCC对某些配置也是可行的，但目前它是非常试验性的。 + + +折腾 +---- + +要想深入了解，请看 ``samples/rust/`` 下的样例源代码、 ``rust/`` 下的Rust支持代码和 +``Kernel hacking`` 下的 ``Rust hacking`` 菜单。 + +如果使用的是GDB/Binutils，而Rust符号没有被demangled，原因是工具链还不支持Rust的新v0 +mangling方案。有几个办法可以解决： + + - 安装一个较新的版本（GDB >= 10.2, Binutils >= 2.36）。 + + - 一些版本的GDB（例如vanilla GDB 10.1）能够使用嵌入在调试信息(``CONFIG_DEBUG_INFO``) + 中的pre-demangled的名字。 diff --git a/Documentation/translations/zh_CN/staging/index.rst b/Documentation/translations/zh_CN/staging/index.rst new file mode 100644 index 000000000000..bb55c81c84a3 --- /dev/null +++ b/Documentation/translations/zh_CN/staging/index.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/staging/index.rst + +:翻译: + + 李睿 Rui Li <me@lirui.org> + +未分类文档 +========== + +.. toctree:: + :maxdepth: 2 + + xz + +TODOList: + +* crc32 +* lzo +* remoteproc +* rpmsg +* speculation +* static-keys +* tee diff --git a/Documentation/translations/zh_CN/staging/xz.rst b/Documentation/translations/zh_CN/staging/xz.rst new file mode 100644 index 000000000000..211c487bcb62 --- /dev/null +++ b/Documentation/translations/zh_CN/staging/xz.rst @@ -0,0 +1,100 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/staging/xz.rst + +:翻译: + + 李睿 Rui Li <me@lirui.org> + +=================== +Linux中的XZ数据压缩 +=================== + +介绍 +==== + +XZ是一种通用的数据压缩格式，其具有高压缩率和相对快的解压速度。主要的压缩算法（ +过滤器）是LZMA2。额外的过滤器可以被用来进一步提高压缩率，比如用来提高可执行数据 +压缩率的Branch/Call/Jump (BCJ)过滤器。 + +XZ解压器在Linux中被称作XZ Embedded。它支持LZMA2过滤器和可选的BCJ过滤器，并支持 +CRC32完整性校验。你可以在XZ Embedded的主页<https://tukaani.org/xz/embedded.html> +中找到最新版本和关于在Linux内核之外使用源码的信息。 + +对于用户空间来说，XZ Utils提供了类似于zlib的压缩库和类似于gzip的命令行工具。 +XZ Utils可以从<https://tukaani.org/xz/>下载。 + +内核中的XZ相关组件 +================== + +xz_dec模块为XZ解压器提供了单次调用（缓冲区到缓冲区）和多次调用（有状态）的 +API。xz_dec模块的用法记录在include/linux/xz.h中。 + +xz_dec_test模块用于测试xz_dec。除非你想魔改XZ解压器，否则xz_dec_test是 +没有用的。xz_dec_test会动态分配一个字符设备主设备号，你可以从用户空间向它 +写入.xz文件，解压的输出会被丢弃。关注dmesg可以找到xz_dec_test输出的诊断信息。 +详细内容请查看xz_dec_test的源码。 + +为了解压内核镜像、初始ram文件系统和初始ram磁盘，lib/decompress_unxz.c实现 +了一个包装函数。它的API与其他 decompress_*.c 文件相同，那些API定义在 +include/linux/decompress/generic.h中。 + +scripts/xz_wrap.sh是一个XZ Utils中的xz命令行工具包装器。这个包装器会 +设置合适的压缩选项来压缩内核镜像。 + +在内核的makefiles中，提供了使用$(call if_needed)的两个命令。内核镜像应该 +使用$(call if_needed,xzkern)来压缩，它会使用BCJ过滤器和一个大LZMA2字典。 +它还会附加一个四字节的包含源文件大小的预告，这会在启动代码中被用到。其他文件 +应该使用$(call if_needed,xzmisc)来压缩，它会使用1 MiB的LZMA2字典并禁用 +BCJ过滤器。 + +关于压缩选项的说明 +================== + +因为XZ Embedded只支持没有完整性校验的数据流或者CRC32，请确保你在编码未来将被 +内核解码的文件时没有使用其他完整性校验方式。使用liblzma时，你需要使用LZMA_CHECK_NONE +或LZMA_CHECK_CRC32。使用xz命令行工具时，使用--check=none或--check=crc32。 + +除非有其他环节会验证解压数据的完整性，否则强烈使用CRC32。双重验证可能会浪费 +CPU周期。请注意头部总是会包含用于解压器验证的CRC32，你只能修改或禁用解压后数据 +的完整性校验方式。 + +在用户中间中，LZMA2通常使用几兆字节大小的字典。解码器需要在RAM中放置字典， +因此大字典不能被用于那些意在被内核解码的文件。1 MiB在内核中大概是可接受的最大 +字典大小（可能对初始ram文件系统也适用）。XZ Utils中的预设值可能并不适合创建 +内核文件，所以请别犹豫使用自定义设置。比如:: + + xz --check=crc32 --lzma2=dict=512KiB inputfile + +使用上面字典大小的一个例外是在单一调用模式下使用解码器。解压内核自身就是一个例 +子。在单一调用模式下，内存用量并不和字典大小有关，这种情况就是使用大字典的好地 +方：为了最大化压缩，字典至少应该和解压后的数据一样大。 + +未来计划 +======== + +如果有人认为有用的话，可能会考虑创建一个受限的XZ编码器。LZMA2的压缩速率比Deflate +或LZO等要慢，即使在最快的配置选项下。所以并不清楚LZMA2编码器是否需要并入内核。 + +有计划在解压代码中支持有限的随机访问读数据。不知道这能否在内核中有任何用，但是我 +知道这会在一些Linux内核以外的嵌入式项目中有用。 + +.xz文件格式规范的一致性 +======================= + +在一些边缘情况下，为了简化事情牺牲了尽早地检测错误。因为并不会导致安全问题，实际 +上是没有关系的。但在测试代码的时候知道这一点很好，比如测试来自XZ Utils的文件。 + +报告错误 +======== + +请在报告错误前确认是否已经在上游修复。可以从<https://tukaani.org/xz/embedded.html> +获取最新的源码。 + +可以通过联系<lasse.collin@tukaani.org>或者访问Freenode上的#tukaani +联系Larhzu。我并不经常阅读LKML或者其他内核相关的邮件列表，所以如果要告知我什么事情 +，你应该通过我的私人邮箱或者IRC联系我。 + +请不要因为内核中XZ的实现或关于XZ Utils的问题打扰Igor Pavlov。虽然这两种实现 +包含了建立在Igor Pavlov的代码上的重要源码，但并不由他维护和提供支持。 diff --git a/Documentation/translations/zh_CN/userspace-api/accelerators/ocxl.rst b/Documentation/translations/zh_CN/userspace-api/accelerators/ocxl.rst new file mode 100644 index 000000000000..845b932bf935 --- /dev/null +++ b/Documentation/translations/zh_CN/userspace-api/accelerators/ocxl.rst @@ -0,0 +1,168 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/userspace-api/accelerators/ocxl.rst + +:翻译: + + 李睿 Rui Li <me@lirui.org> + +===================================== +OpenCAPI （开放相干加速器处理器接口） +===================================== + +*OpenCAPI: Open Coherent Accelerator Processor Interface* + +OpenCAPI是处理器和加速器之间的一个接口，致力于达到低延迟和高带宽。该规范 +由 `OpenCAPI Consortium <http://opencapi.org/>`_ 开发。 + +它允许加速器（可以是FPGA、ASIC等）使用虚拟地址连贯地访问主机内存。一个OpenCAPI +设备也可以托管它自己的内存，并可以由主机访问。 + +OpenCAPI在Linux中称为“ocxl”，它作为“cxl”（用于powerpc的IBM CAPI接口的驱动）的 +开放、处理器无关的演进，这么命名是为了避免与ISDN CAPI子系统相混淆。 + + +高层视角 +======== + +OpenCAPI定义了一个在物理链路层上实现的数据链路层（TL）和传输层（TL）。任何 +实现DL和TL的处理器或者设备都可以开始共享内存。 + +:: + + +-----------+ +-------------+ + | | | | + | | | Accelerated | + | Processor | | Function | + | | +--------+ | Unit | +--------+ + | |--| Memory | | (AFU) |--| Memory | + | | +--------+ | | +--------+ + +-----------+ +-------------+ + | | + +-----------+ +-------------+ + | TL | | TLX | + +-----------+ +-------------+ + | | + +-----------+ +-------------+ + | DL | | DLX | + +-----------+ +-------------+ + | | + | PHY | + +---------------------------------------+ + + Processor：处理器 + Memory：内存 + Accelerated Function Unit：加速函数单元 + + + +设备发现 +======== + +OpenCAPI依赖一个在设备上实现的与PCI类似的配置空间。因此主机可以通过查询 +配置空间来发现AFU。 + +OpenCAPI设备在Linux中被当作类PCI设备（有一些注意事项）。固件需要对硬件进行 +抽象，就好像它是一个PCI链路。许多已有的PCI架构被重用：在模拟标准PCI时， +设备被扫描并且BAR（基址寄存器）被分配。像“lspci”的命令因此可以被用于查看 +哪些设备可用。 + +配置空间定义了可以在物理适配器上可以被找到的AFU，比如它的名字、支持多少内 +存上下文、内存映射IO（MMIO）区域的大小等。 + + + +MMIO +==== + +OpenCAPI为每个AFU定义了两个MMIO区域： + +* 全局MMIO区域，保存和整个AFU相关的寄存器。 +* 每个进程的MMIO区域，对于每个上下文固定大小。 + + + +AFU中断 +======= + +OpenCAPI拥有AFU向主机进程发送中断的可能性。它通过定义在传输层的“intrp_req” +来完成，指定一个定义中断的64位对象句柄。 + +驱动允许一个进程分配中断并获取可以传递给AFU的64位对象句柄。 + + + +字符设备 +======== + +驱动为每个在物理设备上发现的AFU创建一个字符设备。一个物理设备可能拥有多个 +函数，一个函数可以拥有多个AFU。不过编写这篇文档之时，只对导出一个AFU的设备 +测试过。 + +字符设备可以在 /dev/ocxl/ 中被找到，其命名为： +/dev/ocxl/<AFU 名称>.<位置>.<索引> + +<AFU 名称> 是一个最长20个字符的名称，和在AFU配置空间中找到的相同。 +<位置>由驱动添加，可在系统有不止一个相同的OpenCAPI设备时帮助区分设备。 +<索引>也是为了在少见情况下帮助区分AFU，即设备携带多个同样的AFU副本时。 + + + +Sysfs类 +======= + +添加了代表AFU的ocxl类。查看/sys/class/ocxl。布局在 +Documentation/ABI/testing/sysfs-class-ocxl 中描述。 + + + +用户API +======= + +打开 +---- + +基于在配置空间中找到的AFU定义，AFU可能支持在多个内存上下文中工作，这种情况 +下相关的字符设备可以被不同进程多次打开。 + + +ioctl +----- + +OCXL_IOCTL_ATTACH: + + 附加调用进程的内存上下文到AFU，以允许AFU访问其内存。 + +OCXL_IOCTL_IRQ_ALLOC: + + 分配AFU中断，返回标识符。 + +OCXL_IOCTL_IRQ_FREE: + + 释放之前分配的AFU中断。 + +OCXL_IOCTL_IRQ_SET_FD: + + 将一个事件文件描述符和AFU中断关联，因此用户进程可以在AFU发送中断时收到通 + 知。 + +OCXL_IOCTL_GET_METADATA: + + 从卡中获取配置信息，比如内存映射IO区域的大小、AFU版本和当前上下文的进程 + 地址空间ID（PASID）。 + +OCXL_IOCTL_ENABLE_P9_WAIT: + + 允许AFU唤醒执行“等待”的用户空间进程。返回信息给用户空间，允许其配置AFU。 + 注意这只在POWER9上可用。 + +OCXL_IOCTL_GET_FEATURES: + + 报告用户空间可用的影响OpenCAPI的CPU特性。 + + +mmap +---- + +一个进程可以mmap每个进程的MMIO区域来和AFU交互。 diff --git a/Documentation/translations/zh_CN/userspace-api/ebpf/index.rst b/Documentation/translations/zh_CN/userspace-api/ebpf/index.rst new file mode 100644 index 000000000000..d52c7052f101 --- /dev/null +++ b/Documentation/translations/zh_CN/userspace-api/ebpf/index.rst @@ -0,0 +1,22 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/userspace-api/ebpf/index.rst + +:翻译: + + 李睿 Rui Li <me@lirui.org> + +eBPF 用户空间API +================ + +eBPF是一种在Linux内核中提供沙箱化运行环境的机制，它可以在不改变内核源码或加载 +内核模块的情况下扩展运行时和编写工具。eBPF程序能够被附加到各种内核子系统中，包 +括网络，跟踪和Linux安全模块(LSM)等。 + +关于eBPF的内部内核文档，请查看 Documentation/bpf/index.rst 。 + +.. toctree:: + :maxdepth: 1 + + syscall diff --git a/Documentation/translations/zh_CN/userspace-api/ebpf/syscall.rst b/Documentation/translations/zh_CN/userspace-api/ebpf/syscall.rst new file mode 100644 index 000000000000..47e2a59ae45d --- /dev/null +++ b/Documentation/translations/zh_CN/userspace-api/ebpf/syscall.rst @@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/userspace-api/ebpf/syscall.rst + +:翻译: + + 李睿 Rui Li <me@lirui.org> + +eBPF Syscall +------------ + +:作者: + - Alexei Starovoitov <ast@kernel.org> + - Joe Stringer <joe@wand.net.nz> + - Michael Kerrisk <mtk.manpages@gmail.com> + +bpf syscall的主要信息可以在 `man-pages`_ 中的 `bpf(2)`_ 找到。 + +bpf() 子命令参考 +~~~~~~~~~~~~~~~~ + +子命令在以下内核代码中： + +include/uapi/linux/bpf.h + +.. Links: +.. _man-pages: https://www.kernel.org/doc/man-pages/ +.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html diff --git a/Documentation/translations/zh_CN/userspace-api/futex2.rst b/Documentation/translations/zh_CN/userspace-api/futex2.rst new file mode 100644 index 000000000000..04f9d62db1f7 --- /dev/null +++ b/Documentation/translations/zh_CN/userspace-api/futex2.rst @@ -0,0 +1,80 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/userspace-api/futex2.rst + +:翻译: + + 李睿 Rui Li <me@lirui.org> + +====== +futex2 +====== + +:作者: André Almeida <andrealmeid@collabora.com> + +futex，或者称为快速用户互斥锁（fast user mutex），是一组允许用户空间创建高性能同步 +机制的系统调用，比如用户空间中的互斥锁，信号量和条件变量。C标准库，如glibc，使用它作 +为实现更多高级接口的方式，如pthreads。 + +futex2是初代futex系统调用的后续版本，旨在克服原有接口的限制。 + +用户API +======= + +``futex_waitv()`` +----------------- + +等待一个futex数组，可由其中任意一个唤醒:: + + futex_waitv(struct futex_waitv *waiters, unsigned int nr_futexes, + unsigned int flags, struct timespec *timeout, clockid_t clockid) + + struct futex_waitv { + __u64 val; + __u64 uaddr; + __u32 flags; + __u32 __reserved; + }; + +用户空间设置一个struct futex_waitv数组（最多128项），设置 ``uaddr`` 为等待的 +地址， ``val`` 为期望值， ``flags`` 为指定的类型（如private）和futex的大小。 +``__reserved`` 需要置为0，但是它可用作未来扩展。指向数组第一个元素的指针作为 +``waiters`` 传递。如果 ``waiters`` 或任何的 ``uaddr`` 地址无效，将返回 ``-EFAULT`` 。 + +如果用户空间拥有32位的指针，那么需要做显式转换来保证高位清零。 ``uintptr_t`` 设计 +得很精巧，在32/64位的指针上都正常工作。 + +``nr_futexes`` 指定了数组的大小。不在[1,128]区间内的值会使系统调用返回 ``-EINVAL`` 。 + +系统调用的 ``flags`` 参数需要置0，但可用作未来扩展。 + +对于每个 ``waiters`` 数组中的项，在 ``uaddr`` 的当前值会和 ``val`` 比较。如果 +不一致，系统调用会撤销截至目前完成的所有工作，并返回 ``-EAGAIN`` 。如果所有测试 +和验证都通过，系统调用会等待直到以下情况之一发生： + +- 指定的timeout超时，返回 ``-ETIMEOUT`` 。 +- 一个信号被传递给睡眠中的任务，返回 ``-ERESTARTSYS`` 。 +- 某个列表中的futex被唤醒，返回那个被唤醒的futex的索引。 + +关于如何使用接口的例子可以在 ``tools/testing/selftests/futex/functional/futex_waitv.c`` +中找到。 + +超时 +---- + +``struct timespec *timeout`` 是一个指向绝对超时时间的可选参数。你需要在 ``clockid`` +参数中指定要使用的时钟类型。支持 ``CLOCK_MONOTONIC`` 和 ``CLOCK_REALTIME`` 。这个 +系统调用只接受64位的timespec结构体。 + +futex的类型 +----------- + +futex既可以是私有的也可以是共享的。私有用于多个进程共享同样的内存空间，并且futex的虚拟 +地址对所有进程都是一样的。这允许在内核中进行优化。要使用私有futex，需要在futex标志中指定 +``FUTEX_PRIVATE_FLAG`` 。对于那些不在同一内存空间共享的进程，可以让同一个futex拥有不同 +的虚拟地址（例如使用基于文件的共享内存），这需要不同的内部机制来使得正确进入队列。这是默认 +的行为，而且对私有futex和共享futex都适用。 + +futex可以是不同的大小：8，16，32或64位。目前只支持32位大小的futex，并且需要通过 ``FUTEX_32`` +标志指定。 diff --git a/Documentation/translations/zh_CN/userspace-api/index.rst b/Documentation/translations/zh_CN/userspace-api/index.rst new file mode 100644 index 000000000000..5dc0f2e69c17 --- /dev/null +++ b/Documentation/translations/zh_CN/userspace-api/index.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/userspace-api/index.rst + +:翻译: + + 李睿 Rui Li <me@lirui.org> + +========================= +Linux 内核用户空间API指南 +========================= + +.. _man-pages: https://www.kernel.org/doc/man-pages/ + +尽管许多用户空间API的文档被记录在别处（特别是在 man-pages_ 项目中）， +在代码树中仍然可以找到有关用户空间的部分信息。这个手册意在成为这些信息 +聚集的地方。 + +.. class:: toc-title + + 目录 + +.. toctree:: + :maxdepth: 2 + + no_new_privs + seccomp_filter + accelerators/ocxl + ebpf/index + sysfs-platform_profile + futex2 + +TODOList: + +* landlock +* unshare +* spec_ctrl +* ioctl/index +* iommu +* media/index +* netlink/index +* vduse + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/userspace-api/no_new_privs.rst b/Documentation/translations/zh_CN/userspace-api/no_new_privs.rst new file mode 100644 index 000000000000..81bd16ce3ad2 --- /dev/null +++ b/Documentation/translations/zh_CN/userspace-api/no_new_privs.rst @@ -0,0 +1,57 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/userspace-api/no_new_privs.rst + +:翻译: + + 李睿 Rui Li <me@lirui.org> + +============ +无新权限标志 +============ + +execve系统调用可以给一个新启动的程序授予它的父程序本没有的权限。最明显的两个 +例子就是setuid/setgid控制程序和文件的能力。为了避免父程序也获得这些权限，内 +核和用户代码必须小心避免任何父程序可以颠覆子程序的情况。比如： + + - 程序在setuid后，动态装载器处理 ``LD_*`` 环境变量的不同方式。 + + - 对于非特权程序，chroot是不允许的，因为这会允许 ``/etc/passwd`` 在继承 + chroot的程序眼中被替换。 + + - 执行代码对ptrace有特殊处理。 + +这些都是临时性的修复。 ``no_new_privs`` 位（从 Linux 3.5 起）是一个新的通 +用的机制来保证一个进程安全地修改其执行环境并跨execve持久化。任何任务都可以设 +置 ``no_new_privs`` 。一旦该位被设置，它会在fork、clone和execve中继承下去 +，并且不能被撤销。在 ``no_new_privs`` 被设置的情况下， ``execve()`` 将保证 +不会授予权限去做任何没有execve调用就不能做的事情。比如， setuid 和 setgid +位不会再改变 uid 或 gid；文件能力不会被添加到授权集合中，并且Linux安全模块（ +LSM）不会在execve调用后放松限制。 + +设置 ``no_new_privs`` 使用:: + + prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0); + +不过要小心，Linux安全模块（LSM）也可能不会在 ``no_new_privs`` 模式下收紧约束。 +（这意味着一个一般的服务启动器在执行守护进程前就去设置 ``no_new_privs`` 可能 +会干扰基于LSM的沙箱。） + +请注意， ``no_new_privs`` 并不能阻止不涉及 ``execve()`` 的权限变化。一个拥有 +适当权限的任务仍然可以调用 ``setuid(2)`` 并接收 SCM_RIGHTS 数据报。 + +目前来说， ``no_new_privs`` 有两大使用场景： + + - 为seccomp模式2沙箱安装的过滤器会跨execve持久化，并能够改变新执行程序的行为。 + 非特权用户因此在 ``no_new_privs`` 被设置的情况下只允许安装这样的过滤器。 + + - ``no_new_privs`` 本身就能被用于减少非特权用户的攻击面。如果所有以某个 uid + 运行的程序都设置了 ``no_new_privs`` ，那么那个 uid 将无法通过攻击 setuid， + setgid 和使用文件能力的二进制来提权；它需要先攻击一些没有被设置 ``no_new_privs`` + 位的东西。 + +将来，其他潜在的危险的内核特性可能被非特权任务利用，即使 ``no_new_privs`` 被置位。 +原则上，当 ``no_new_privs`` 被置位时， ``unshare(2)`` 和 ``clone(2)`` 的几个选 +项将是安全的，并且 ``no_new_privs`` 加上 ``chroot`` 是可以被认为比 chroot本身危 +险性小得多的。 diff --git a/Documentation/translations/zh_CN/userspace-api/seccomp_filter.rst b/Documentation/translations/zh_CN/userspace-api/seccomp_filter.rst new file mode 100644 index 000000000000..ede8b37c953f --- /dev/null +++ b/Documentation/translations/zh_CN/userspace-api/seccomp_filter.rst @@ -0,0 +1,293 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/userspace-api/seccomp_filter.rst + +:翻译: + + 李睿 Rui Li <me@lirui.org> + +================================== +Seccomp BPF (基于过滤器的安全计算) +================================== + +*Seccomp: SECure COMPuting* + +介绍 +==== + +大量系统调用被暴露给每个用户空间进程，但其中又有许多系统调用在进程的整个生命 +周期中都没被使用。随着系统调用的改变和成熟，缺陷被找到并消除。允许某一部分应 +用程序仅能访问一部分系统调用是有好处的，这会缩小内核暴露给应用程序的面积。 +系统调用过滤器就是为这些应用程序而生的。 + +Seccomp过滤提供了一种为进程指定一个处理系统调用的过滤器的方法。这个过滤器体 +现为一个伯克利包过滤器（BPF）程序，就像套接字过滤器一样，不同在于前者处理的 +数据和正在进行的系统调用有关：系统调用号和系统调用参数。这样使用一种长期与 +用户空间和直接数据打交道的语言来表达系统调用过滤成为了可能。 + +此外，BPF让seccomp用户不再成为在系统调用干预框架（system call interposition +frameworks）中常见的检查-使用竞态攻击（TOCTOU）的受害者。BPF程序可能无法解引 +用指针，这就限制了所有过滤器仅能直接评估系统调用参数。 + +这不是什么 +========== + +系统调用过滤并不是一个沙箱。它提供了一种明确定义的机制来最小化内核暴露面。它 +旨在成为一个沙箱开发者使用的工具。除此之外，逻辑行为和信息流的策略应该结合其他 +系统加固手段或者可能由你选择的内核安全模块（LSM）来管理。易于表达的动态过滤器 +为这条路提供了更多选择（比如避免病态的大小或者选择允许 socketcall() 中的多路 +系统调用），但将其理解为更完整的沙箱解决方案是错误的。 + +用法 +==== + +添加了一个额外的seccomp模式，它可以使用和严格seccomp相同的 prctl(2) 调用来启用。 +如果架构有 ``CONFIG_HAVE_ARCH_SECCOMP_FILTER`` 标志，那么可以添加以下过滤器： + +``PR_SET_SECCOMP``: + 现在需要添加一个额外的参数来指定使用BPF程序的新过滤器。 + BPF程序将在反应系统调用号、参数和其他元数据的seccomp_data结构体之上执行。 + BPF程序必须返回允许的值之一来告知内核应该采取什么行动。 + + 用法:: + + prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, prog); + + 'prog' 参数是一个指向 sock_fprog 结构体的指针，其中包含了过滤器程序。如 + 果程序是无效的，该调用会返回 -1 并设置 errno 为 ``EINVAL`` 。 + + 如果 ``fork`` / ``clone`` 和 ``execve`` 被 @prog 所允许，任何子进程都将 + 受到和父进程相同的过滤器和系统调用ABI的约束。 + + 在调用之前，进程必须调用 ``prctl(PR_SET_NO_NEW_PRIVS, 1)`` 或者在它的 + 命名空间内以 ``CAP_SYS_ADMIN`` 权限运行。如果以上条件不满足，会返回 + ``-EACCES`` 。这一要求保证了过滤器程序不能用于比安装过滤器的进程拥有更高 + 权限的子进程。 + + 另外，如果 ``prctl(2)`` 被安装的过滤器所允许，就可以叠加额外的过滤器。这会增 + 加评估时间，但是可以进一步降低执行进程时的攻击面。 + +以上调用在成功时返回0，失败时返回一个非零的值。 + +返回值 +====== + +一个seccomp过滤器可能返回下列任意值。如果多个过滤器存在，评估一个指定系统调用的 +返回值总会使用最高优先级的值。（比如 ``SECCOMP_RET_KILL_PROCESS`` 总是被优先 +返回。） + +按照优先级排序，它们是： + +``SECCOMP_RET_KILL_PROCESS``: + 使得整个进程立即结束而不执行系统调用。进程的退出状态 (``status & 0x7f``) 将 + 是 ``SIGSYS`` ，而不是 ``SIGKILL`` 。 + +``SECCOMP_RET_KILL_THREAD``: + 使得线程立即结束而不执行系统调用。线程的退出状态 (``status & 0x7f``) 将是 + 是 ``SIGSYS`` ，而不是 ``SIGKILL`` 。 + +``SECCOMP_RET_TRAP``: + 使得内核向触发进程发送一个 ``SIGSYS`` 信号而不执行系统调用。 + ``siginfo->si_call_addr`` 会展示系统调用指令的位置， ``siginfo->si_syscall`` + 和 ``siginfo->si_arch`` 会指出试图进行的系统调用。程序计数器会和发生了系统 + 调用的一样（即它不会指向系统调用指令）。返回值寄存器会包含一个与架构相关的值—— + 如果恢复执行，需要将其设为合理的值。（架构依赖性是因为将其替换为 ``-ENOSYS`` + 会导致一些有用的信息被覆盖。） + + 返回值的 ``SECCOMP_RET_DATA`` 部分会作为 ``si_errno`` 传递。 + + 由seccomp触发的 ``SIGSYS`` 会有一个 ``SYS_SECCOMP`` 的 si_code 。 + +``SECCOMP_RET_ERRNO``: + 使得返回值的低16位作为errno传递给用户空间，而不执行系统调用。 + +``SECCOMP_RET_USER_NOTIF``: + 使得一个 ``struct seccomp_notif`` 消息被发送到已附加的用户空间通知文件描述 + 符。如果没有被附加则返回 ``-ENOSYS`` 。下面会讨论如何处理用户通知。 + +``SECCOMP_RET_TRACE``: + 当返回的时候，这个值会使得内核在执行系统调用前尝试去通知一个基于 ``ptrace()`` + 的追踪器。如果没有追踪器， ``-ENOSYS`` 会返回给用户空间，并且系统调用不会执行。 + + 如果追踪器通过 ``ptrace(PTRACE_SETOPTIONS)`` 请求了 ``PTRACE_O_TRACESECCOMP``， + 那么它会收到 ``PTRACE_EVENT_SECCOMP`` 通知。BPF程序返回值的 ``SECCOMP_RET_DATA`` + 部分会通过 ``PTRACE_GETEVENTMSG`` 提供给追踪器。 + + 追踪器可以通过改变系统调用号到-1来跳过系统调用。或者追踪器可以改变系统调用号到 + 一个有效值来改变请求的系统调用。如果追踪器请求跳过系统调用，那么系统调用将返回 + 追踪器放在返回值寄存器中的值。 + + 在追踪器被通知后，seccomp检查不会再次运行。（这意味着基于seccomp的沙箱必须禁止 + ptrace的使用，甚至其他沙箱进程也不行，除非非常小心；ptrace可以通过这个机制来逃 + 逸。） + +``SECCOMP_RET_LOG``: + 使得系统调用在被记录之后再运行。这应该被应用开发者用来检查他们的程序需要哪些 + 系统调用，而不需要反复通过多个测试和开发周期来建立清单。 + + 只有在 actions_logged sysctl 字符串中出现 "log" 时，这个操作才会被记录。 + +``SECCOMP_RET_ALLOW``: + 使得系统调用被执行。 + +如果多个追踪器存在，评估系统调用的返回值将永远使用最高优先级的值。 + +优先级只通过 ``SECCOMP_RET_ACTION`` 掩码来决定。当多个过滤器返回相同优先级的返回 +值时，只有来自最近安装的过滤器的 ``SECCOMP_RET_DATA`` 会被返回。 + +隐患 +==== + +最需要避免的隐患是在过滤系统调用号时却不检查架构值。因为在任何支持多个系统调用 +约定的架构上，系统调用号可能根据具体调用而不同。如果不同调用约定中的调用号有重叠， +那么过滤器的检查可能被滥用。请总是检查架构值！ + +例子 +==== + +``samples/seccomp/`` 文件夹包含了x86专用和更通用的使用高层宏接口来生成BPF程序的 +例子。 + +用户空间通知 +============ + +``SECCOMP_RET_USER_NOTIF`` 返回值会让seccomp过滤器传递一个特定的系统调用给用户 +空间处理。这可能会对像容器管理器的程序有用，它们希望拦截特定的系统调用（如 ``mount()``， +``finit_module()`` 等等）并改变其行为。 + +传递 ``SECCOMP_FILTER_FLAG_NEW_LISTENER`` 参数给 ``seccomp()`` 系统调用可以取 +得通知文件描述符： + +.. code-block:: c + + fd = seccomp(SECCOMP_SET_MODE_FILTER, SECCOMP_FILTER_FLAG_NEW_LISTENER, &prog); + +成功情况下会返回一个对过滤器监听的文件描述符，然后可以通过 ``SCM_RIGHTS`` 或类似 +的方式传递。需要注意的是，过滤器文件描述符针对的是一个特定的过滤器而不是特定的进程。 +所以如果这个进程后来fork了，来自两个进程的通知都会出现在同一个过滤器文件描述符中。 +对于过滤器文件描述符的读写也是同步的，所以一个过滤器文件描述符可以安全地拥有多个读者。 + +seccomp通知文件描述符由两个结构体组成： + +.. code-block:: c + + struct seccomp_notif_sizes { + __u16 seccomp_notif; + __u16 seccomp_notif_resp; + __u16 seccomp_data; + }; + + struct seccomp_notif { + __u64 id; + __u32 pid; + __u32 flags; + struct seccomp_data data; + }; + + struct seccomp_notif_resp { + __u64 id; + __s64 val; + __s32 error; + __u32 flags; + }; + +``struct seccomp_notif_sizes`` 结构体可以用于确定seccomp通知中各种结构体的大小。 +``struct seccomp_data`` 的大小可能未来会改变，所以需要使用下面的代码： + +.. code-block:: c + + struct seccomp_notif_sizes sizes; + seccomp(SECCOMP_GET_NOTIF_SIZES, 0, &sizes); + +来决定需要分配的多种结构体的大小。请查看 samples/seccomp/user-trap.c 中的例子。 + +用户可以通过 ``ioctl(SECCOMP_IOCTL_NOTIF_RECV)`` (或 ``poll()``) 读取seccomp +通知文件描述符来接收一个 ``struct seccomp_notif`` ，其中包含五个成员：结构体的 +输入长度，每个过滤器唯一的 ``id`` ， 触发请求进程的 ``pid`` （如果进程的pid命名空 +间对于监听者的pid命名空间不可见的话，可能为0）。通知还包含传递给seccomp的 ``data`` +和一个过滤器标志。在调用ioctl前结构体应该被清空。 + +之后用户空间可以根据这些信息决定做什么，并通过 ``ioctl(SECCOMP_IOCTL_NOTIF_SEND)`` +发送一个响应，表示应该给用户空间返回什么。 ``struct seccomp_notif_resp`` 的 ``id`` +成员应该和 ``struct seccomp_notif`` 的 ``id`` 一致。 + +用户空间也可以通过 ``ioctl(SECCOMP_IOCTL_NOTIF_ADDFD)`` 向通知进程添加文件描述 +符。 ``struct seccomp_notif_addfd`` 的 ``id`` 成员应该和 ``struct seccomp_notif`` +的 ``id`` 保持一致。 ``newfd_flags`` 标志可以被用于在通知进程的文件描述符上设置 +O_CLOEXEC 等标志。如果监督者（supervisor）向文件描述符注入一个特定的数字，可以使用 +``SECCOMP_ADDFD_FLAG_SETFD`` 标志，并设置 ``newfd`` 成员为要使用的特定数字。 +如果文件描述符已经在通知进程中打开，那它将被替换。监督者也可以添加一个文件描述符， +并使用 ``SECCOMP_ADDFD_FLAG_SEND`` 标志原子响应，返回值将是注入的文件描述符编号。 + +通知进程可以被抢占，导致通知被终止。这可能在尝试代表通知进程执行长时间且通常可重试 +（如挂载文件系统）的操作时导致问题。另外，在安装过滤器的时候， +``SECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV`` 可以被设置。这个标志使得当监督者收到用 +户通知时，通知进程会忽略非致命信号，直到响应被发送。在用户空间收到通知之前发出的信号 +将被正常处理。 + +值得注意的是， ``struct seccomp_data`` 包含了系统调用寄存器参数的值，但是不包含指向 +内存的指针。进程的内存可以通过 ``ptrace()`` 或 ``/proc/pid/mem`` 由合适的特权跟踪 +访问。但是，需要注意避免之前提到的TOCTOU攻击：所有从被跟踪者内存中读到的参数都应该先 +读到追踪器的内存中，再做出策略决定。这样就可以对系统调用的参数做原子决定。 + +Sysctls +======= + +Seccomp的sysctl文件可以在 ``/proc/sys/kernel/seccomp/`` 文件夹中找到。这里有对文件 +夹中每个文件的描述： + +``actions_avail``: + 以字符串形式保存seccomp返回值（参考上文的 ``SECCOMP_RET_*`` 宏）的只读有序 + 列表。从左往右按照最少许可返回值到最多许可返回值排序。 + + 这个列表代表了内核支持的seccomp返回值集合。一个用户空间程序可以使用这个列表来在 + 程序建立时确定在 ``seccomp.h`` 中找到的动作是否和当前运行内核实际支持的动作有所 + 不同。 + +``actions_logged``: + 允许被记录的seccomp返回值（参考上文的 ``SECCOMP_RET_*`` 宏）的可读写有序列表。 + 对文件写入不需要是有序的，但从文件读取将采用与actions_avail sysctl一致的方式排序。 + + ``allow`` 字符串在 ``actions_logged`` sysctl中不被接收，因为不可能记录 + ``SECCOMP_RET_ALLOW`` 动作。尝试向sysctl写入 ``allow`` 会导致返回一个EINVAL。 + +添加架构支持 +============ + +请查看 ``arch/Kconfig`` 了解权威要求。总的来说如果一个架构同时支持ptrace_event和 +seccomp，那么它将可以通过较小的修改支持seccomp过滤器： ``SIGSYS`` 支持和seccomp +返回值检查。然后必须将 ``CONFIG_HAVE_ARCH_SECCOMP_FILTER`` 添加到它的架构特定 +的Kconfig中。 + +注意事项 +======== + +vDSO可能导致一些系统调用完全在用户空间中运行，当你在不同机器上跑程序时可能导致回退 +到真正系统调用的意外发生。为了在x86上最小化这些意外的发生，请确保你在测试时把 +``/sys/devices/system/clocksource/clocksource0/current_clocksource`` 设置为 +``acpi_pm`` 之类的值。 + +在x86-64上，vsyscall模拟默认开启。（vsyscalls是vDSO调用的传统变体。）目前，模拟 +vsyscalls会遵守seccomp，但是有一些奇怪情况： + +- ``SECCOMP_RET_TRAP`` 的返回值会设置一个指向给定vsyscall入口的 ``si_call_addr``， + 而不是'syscall'指令之后的地址。任何想重新开始调用的代码都需要注意 (a) ret指令 + 已被模拟，(b) 试图恢复系统调用将再次触发标准vsyscall模拟安全检查，使得恢复系统 + 调用在大部分情况下没有意义。 + +- ``SECCOMP_RET_TRACE`` 的返回值将像往常一样给追踪器发出信号，但是系统调用可能不能 + 使用orig_rax寄存器改变为另一个系统调用。可能只能改变为-1来跳过当前模拟的调用。 + 任何其他改变都可能终止进程。追踪器看到的rip值将是系统调用的入口地址；这和正常行为 + 不同。追踪器禁止修改rip或者rsp。（不要依赖其他改变来终止进程，它们可能正常工作。 + 比如在一些内核中，选择一个只存在于未来内核中的系统调用将被正确模拟，返回一个 + ``-ENOSYS`` 。） + +要检测这个古怪的行为，可以检查 ``addr & ~0x0C00 == 0xFFFFFFFFFF600000``。（对于 +``SECCOMP_RET_TRACE`` ，使用rip。对于 ``SECCOMP_RET_TRAP`` ，使用 +``siginfo->si_call_addr`` 。）不要检测其他条件：未来内核可能会改进vsyscall模拟， +当前内核在vsyscall=native模式下会有不同表现，但在这些情况下， ``0xF...F600{0,4,8,C}00`` +处的指令将不是系统调用。 + +请注意，现代系统根本不可能使用vsyscalls —— 它们是一种遗留功能，而且比标准系统调用 +慢得多。 新的代码将使用vDSO，而vDSO发出的系统调用与正常的系统调用没有区别。 diff --git a/Documentation/translations/zh_CN/userspace-api/sysfs-platform_profile.rst b/Documentation/translations/zh_CN/userspace-api/sysfs-platform_profile.rst new file mode 100644 index 000000000000..7d21740db125 --- /dev/null +++ b/Documentation/translations/zh_CN/userspace-api/sysfs-platform_profile.rst @@ -0,0 +1,40 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/userspace-api/sysfs-platform_profile.rst + +:翻译: + + 李睿 Rui Li <me@lirui.org> + +========================================================== +平台配置文件选择（如 /sys/firmware/acpi/platform_profile） +========================================================== + +现代系统中平台性能、温度、风扇和其他硬件相关的特性通常是可以动态配置的。平台 +配置通常会根据当前的状态由一些自动机制（很可能存在于内核之外）来自动调整。 + +这些平台自动调整机制通常能够被配置成多个平台配置文件中的一个，要么偏向节能运 +行，要么偏向性能运行。 + +platform_profile属性的目的是提供一个通用的sysfs API来选择这些平台自动配置 +机制的配置文件。 + +需要注意的是，这个API只能用作选择平台配置文件，用来监测所产生的性能特征并不 +是其目标。监测性能最好使用设备/供应商提供的工具，比如turbostat。 + +具体来说，当选择高性能配置文件时，真实能达到的性能可能受制于多种因素，比如： +其他组件的发热，房间温度，笔记本底部的自由空气流动等。让用户空间知道任何阻碍 +达到要求性能水平的局部最优条件，显然不是这个API的目标。 + +由于数字本身并不能代表一个配置文件会调整的多个变量（功耗，发热等），这个API +使用字符串来描述多种配置文件。为了保证用户空间能够获得一致的体验， +sysfs-platform_profile ABI 文档定义了一个固定的配置文件名集合。驱动程序 +*必须* 将它们内置的配置文件表示映射到这个固定的集合中。 + +如果映射时没有很好的匹配，可以添加一个新的配置文件名称。驱动希望引入的新配置 +文件名称时必须： + + 1. 解释为什么无法使用已有的配置文件名称。 + 2. 添加一个新的配置文件名称，以及预期行为的清晰描述，保存到 + sysfs-platform_profile ABI文档中。 diff --git a/Documentation/usb/CREDITS b/Documentation/usb/CREDITS index 67c59cdc9959..81ea3eb29e96 100644 --- a/Documentation/usb/CREDITS +++ b/Documentation/usb/CREDITS @@ -1,7 +1,7 @@ Credits for the Simple Linux USB Driver: The following people have contributed to this code (in alphabetical -order by last name). I'm sure this list should be longer, its +order by last name). I'm sure this list should be longer, it's difficult to maintain, add yourself with a patch if desired. Georg Acher <acher@informatik.tu-muenchen.de> @@ -126,7 +126,7 @@ THANKS file in Inaky's driver): - Jochen Karrer <karrer@wpfd25.physik.uni-wuerzburg.de>, for pointing out mortal bugs and giving advice. - - Edmund Humemberger <ed@atnet.at>, for it's great work on + - Edmund Humemberger <ed@atnet.at>, for his great work on public relationships and general management stuff for the Linux-USB effort. @@ -136,7 +136,7 @@ THANKS file in Inaky's driver): - Ric Klaren <ia_ric@cs.utwente.nl> for doing nice introductory documents (competing with Alberto's :). - - Christian Groessler <cpg@aladdin.de>, for it's help on those + - Christian Groessler <cpg@aladdin.de>, for his help on those itchy bits ... :) - Paul MacKerras for polishing OHCI and pushing me harder for diff --git a/Documentation/usb/functionfs.rst b/Documentation/usb/functionfs.rst index 7fdc6d840ac5..a3054bea38f3 100644 --- a/Documentation/usb/functionfs.rst +++ b/Documentation/usb/functionfs.rst @@ -49,7 +49,7 @@ level it would look like this:: $ ( cd /dev/ffs-hid && hid-daemon ) & On kernel level the gadget checks ffs_data->dev_name to identify -whether it's FunctionFS designed for MTP ("mtp") or HID ("hid"). +whether its FunctionFS is designed for MTP ("mtp") or HID ("hid"). If no "functions" module parameters is supplied, the driver accepts just one function with any name. diff --git a/Documentation/usb/gadget_multi.rst b/Documentation/usb/gadget_multi.rst index 3a22c1b2f39e..f78a51ff2324 100644 --- a/Documentation/usb/gadget_multi.rst +++ b/Documentation/usb/gadget_multi.rst @@ -9,7 +9,7 @@ The Multifunction Composite Gadget (or g_multi) is a composite gadget that makes extensive use of the composite framework to provide a... multifunction gadget. -In it's standard configuration it provides a single USB configuration +In its standard configuration it provides a single USB configuration with RNDIS[1] (that is Ethernet), USB CDC[2] ACM (that is serial) and USB Mass Storage functions. diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index c78da9ce0ec4..f16337bdb852 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -25,6 +25,7 @@ place where this information is gathered. ebpf/index ioctl/index iommu + iommufd media/index netlink/index sysfs-platform_profile diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index 5f81e2a24a5c..eb045fc495a4 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -105,6 +105,7 @@ Code Seq# Include File Comments '8' all SNP8023 advanced NIC card <mailto:mcr@solidum.com> ';' 64-7F linux/vfio.h +';' 80-FF linux/iommufd.h '=' 00-3f uapi/linux/ptp_clock.h <mailto:richardcochran@gmail.com> '@' 00-0F linux/radeonfb.h conflict! '@' 00-0F drivers/video/aty/aty128fb.c conflict! diff --git a/Documentation/userspace-api/iommufd.rst b/Documentation/userspace-api/iommufd.rst new file mode 100644 index 000000000000..79dd9eb51587 --- /dev/null +++ b/Documentation/userspace-api/iommufd.rst @@ -0,0 +1,223 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +======= +IOMMUFD +======= + +:Author: Jason Gunthorpe +:Author: Kevin Tian + +Overview +======== + +IOMMUFD is the user API to control the IOMMU subsystem as it relates to managing +IO page tables from userspace using file descriptors. It intends to be general +and consumable by any driver that wants to expose DMA to userspace. These +drivers are eventually expected to deprecate any internal IOMMU logic +they may already/historically implement (e.g. vfio_iommu_type1.c). + +At minimum iommufd provides universal support of managing I/O address spaces and +I/O page tables for all IOMMUs, with room in the design to add non-generic +features to cater to specific hardware functionality. + +In this context the capital letter (IOMMUFD) refers to the subsystem while the +small letter (iommufd) refers to the file descriptors created via /dev/iommu for +use by userspace. + +Key Concepts +============ + +User Visible Objects +-------------------- + +Following IOMMUFD objects are exposed to userspace: + +- IOMMUFD_OBJ_IOAS, representing an I/O address space (IOAS), allowing map/unmap + of user space memory into ranges of I/O Virtual Address (IOVA). + + The IOAS is a functional replacement for the VFIO container, and like the VFIO + container it copies an IOVA map to a list of iommu_domains held within it. + +- IOMMUFD_OBJ_DEVICE, representing a device that is bound to iommufd by an + external driver. + +- IOMMUFD_OBJ_HW_PAGETABLE, representing an actual hardware I/O page table + (i.e. a single struct iommu_domain) managed by the iommu driver. + + The IOAS has a list of HW_PAGETABLES that share the same IOVA mapping and + it will synchronize its mapping with each member HW_PAGETABLE. + +All user-visible objects are destroyed via the IOMMU_DESTROY uAPI. + +The diagram below shows relationship between user-visible objects and kernel +datastructures (external to iommufd), with numbers referred to operations +creating the objects and links:: + + _________________________________________________________ + | iommufd | + | [1] | + | _________________ | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | [3] [2] | + | | | ____________ __________ | + | | IOAS |<--| |<------| | | + | | | |HW_PAGETABLE| | DEVICE | | + | | | |____________| |__________| | + | | | | | | + | | | | | | + | | | | | | + | | | | | | + | | | | | | + | |_________________| | | | + | | | | | + |_________|___________________|___________________|_______| + | | | + | _____v______ _______v_____ + | PFN storage | | | | + |------------>|iommu_domain| |struct device| + |____________| |_____________| + +1. IOMMUFD_OBJ_IOAS is created via the IOMMU_IOAS_ALLOC uAPI. An iommufd can + hold multiple IOAS objects. IOAS is the most generic object and does not + expose interfaces that are specific to single IOMMU drivers. All operations + on the IOAS must operate equally on each of the iommu_domains inside of it. + +2. IOMMUFD_OBJ_DEVICE is created when an external driver calls the IOMMUFD kAPI + to bind a device to an iommufd. The driver is expected to implement a set of + ioctls to allow userspace to initiate the binding operation. Successful + completion of this operation establishes the desired DMA ownership over the + device. The driver must also set the driver_managed_dma flag and must not + touch the device until this operation succeeds. + +3. IOMMUFD_OBJ_HW_PAGETABLE is created when an external driver calls the IOMMUFD + kAPI to attach a bound device to an IOAS. Similarly the external driver uAPI + allows userspace to initiate the attaching operation. If a compatible + pagetable already exists then it is reused for the attachment. Otherwise a + new pagetable object and iommu_domain is created. Successful completion of + this operation sets up the linkages among IOAS, device and iommu_domain. Once + this completes the device could do DMA. + + Every iommu_domain inside the IOAS is also represented to userspace as a + HW_PAGETABLE object. + + .. note:: + + Future IOMMUFD updates will provide an API to create and manipulate the + HW_PAGETABLE directly. + +A device can only bind to an iommufd due to DMA ownership claim and attach to at +most one IOAS object (no support of PASID yet). + +Kernel Datastructure +-------------------- + +User visible objects are backed by following datastructures: + +- iommufd_ioas for IOMMUFD_OBJ_IOAS. +- iommufd_device for IOMMUFD_OBJ_DEVICE. +- iommufd_hw_pagetable for IOMMUFD_OBJ_HW_PAGETABLE. + +Several terminologies when looking at these datastructures: + +- Automatic domain - refers to an iommu domain created automatically when + attaching a device to an IOAS object. This is compatible to the semantics of + VFIO type1. + +- Manual domain - refers to an iommu domain designated by the user as the + target pagetable to be attached to by a device. Though currently there are + no uAPIs to directly create such domain, the datastructure and algorithms + are ready for handling that use case. + +- In-kernel user - refers to something like a VFIO mdev that is using the + IOMMUFD access interface to access the IOAS. This starts by creating an + iommufd_access object that is similar to the domain binding a physical device + would do. The access object will then allow converting IOVA ranges into struct + page * lists, or doing direct read/write to an IOVA. + +iommufd_ioas serves as the metadata datastructure to manage how IOVA ranges are +mapped to memory pages, composed of: + +- struct io_pagetable holding the IOVA map +- struct iopt_area's representing populated portions of IOVA +- struct iopt_pages representing the storage of PFNs +- struct iommu_domain representing the IO page table in the IOMMU +- struct iopt_pages_access representing in-kernel users of PFNs +- struct xarray pinned_pfns holding a list of pages pinned by in-kernel users + +Each iopt_pages represents a logical linear array of full PFNs. The PFNs are +ultimately derived from userspace VAs via an mm_struct. Once they have been +pinned the PFNs are stored in IOPTEs of an iommu_domain or inside the pinned_pfns +xarray if they have been pinned through an iommufd_access. + +PFN have to be copied between all combinations of storage locations, depending +on what domains are present and what kinds of in-kernel "software access" users +exist. The mechanism ensures that a page is pinned only once. + +An io_pagetable is composed of iopt_areas pointing at iopt_pages, along with a +list of iommu_domains that mirror the IOVA to PFN map. + +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 +devices managed by different subsystems are bound to a same iommufd. + +IOMMUFD User API +================ + +.. kernel-doc:: include/uapi/linux/iommufd.h + +IOMMUFD Kernel API +================== + +The IOMMUFD kAPI is device-centric with group-related tricks managed behind the +scene. This allows the external drivers calling such kAPI to implement a simple +device-centric uAPI for connecting its device to an iommufd, instead of +explicitly imposing the group semantics in its uAPI as VFIO does. + +.. kernel-doc:: drivers/iommu/iommufd/device.c + :export: + +.. kernel-doc:: drivers/iommu/iommufd/main.c + :export: + +VFIO and IOMMUFD +---------------- + +Connecting a VFIO device to iommufd can be done in two ways. + +First is a VFIO compatible way by directly implementing the /dev/vfio/vfio +container IOCTLs by mapping them into io_pagetable operations. Doing so allows +the use of iommufd in legacy VFIO applications by symlinking /dev/vfio/vfio to +/dev/iommufd or extending VFIO to SET_CONTAINER using an iommufd instead of a +container fd. + +The second approach directly extends VFIO to support a new set of device-centric +user API based on aforementioned IOMMUFD kernel API. It requires userspace +change but better matches the IOMMUFD API semantics and easier to support new +iommufd features when comparing it to the first approach. + +Currently both approaches are still work-in-progress. + +There are still a few gaps to be resolved to catch up with VFIO type1, as +documented in iommufd_vfio_check_extension(). + +Future TODOs +============ + +Currently IOMMUFD supports only kernel-managed I/O page table, similar to VFIO +type1. New features on the radar include: + + - Binding iommu_domain's to PASID/SSID + - Userspace page tables, for ARM, x86 and S390 + - Kernel bypass'd invalidation of user page tables + - Re-use of the KVM page table in the IOMMU + - Dirty page tracking in the IOMMU + - Runtime Increase/Decrease of IOPTE size + - PRI support with faults resolved in userspace diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst index cec780c2f497..d8cd8cd9ce25 100644 --- a/Documentation/userspace-api/landlock.rst +++ b/Documentation/userspace-api/landlock.rst @@ -8,7 +8,7 @@ Landlock: unprivileged access control ===================================== :Author: Mickaël Salaün -:Date: September 2022 +:Date: October 2022 The goal of Landlock is to enable to restrict ambient rights (e.g. global filesystem access) for a set of processes. Because Landlock is a stackable @@ -60,7 +60,8 @@ the need to be explicit about the denied-by-default access rights. LANDLOCK_ACCESS_FS_MAKE_FIFO | LANDLOCK_ACCESS_FS_MAKE_BLOCK | LANDLOCK_ACCESS_FS_MAKE_SYM | - LANDLOCK_ACCESS_FS_REFER, + LANDLOCK_ACCESS_FS_REFER | + LANDLOCK_ACCESS_FS_TRUNCATE, }; Because we may not know on which kernel version an application will be @@ -69,16 +70,28 @@ should try to protect users as much as possible whatever the kernel they are using. To avoid binary enforcement (i.e. either all security features or none), we can leverage a dedicated Landlock command to get the current version of the Landlock ABI and adapt the handled accesses. Let's check if we should -remove the ``LANDLOCK_ACCESS_FS_REFER`` access right which is only supported -starting with the second version of the ABI. +remove the ``LANDLOCK_ACCESS_FS_REFER`` or ``LANDLOCK_ACCESS_FS_TRUNCATE`` +access rights, which are only supported starting with the second and third +version of the ABI. .. code-block:: c int abi; abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION); - if (abi < 2) { + if (abi < 0) { + /* Degrades gracefully if Landlock is not handled. */ + perror("The running kernel does not enable to use Landlock"); + return 0; + } + switch (abi) { + case 1: + /* Removes LANDLOCK_ACCESS_FS_REFER for ABI < 2 */ ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_REFER; + __attribute__((fallthrough)); + case 2: + /* Removes LANDLOCK_ACCESS_FS_TRUNCATE for ABI < 3 */ + ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_TRUNCATE; } This enables to create an inclusive ruleset that will contain our rules. @@ -127,8 +140,8 @@ descriptor. It may also be required to create rules following the same logic as explained for the ruleset creation, by filtering access rights according to the Landlock -ABI version. In this example, this is not required because -``LANDLOCK_ACCESS_FS_REFER`` is not allowed by any rule. +ABI version. In this example, this is not required because all of the requested +``allowed_access`` rights are already available in ABI 1. We now have a ruleset with one rule allowing read access to ``/usr`` while denying all other handled accesses for the filesystem. The next step is to @@ -252,6 +265,37 @@ To be allowed to use :manpage:`ptrace(2)` and related syscalls on a target process, a sandboxed process should have a subset of the target process rules, which means the tracee must be in a sub-domain of the tracer. +Truncating files +---------------- + +The operations covered by ``LANDLOCK_ACCESS_FS_WRITE_FILE`` and +``LANDLOCK_ACCESS_FS_TRUNCATE`` both change the contents of a file and sometimes +overlap in non-intuitive ways. It is recommended to always specify both of +these together. + +A particularly surprising example is :manpage:`creat(2)`. The name suggests +that this system call requires the rights to create and write files. However, +it also requires the truncate right if an existing file under the same name is +already present. + +It should also be noted that truncating files does not require the +``LANDLOCK_ACCESS_FS_WRITE_FILE`` right. Apart from the :manpage:`truncate(2)` +system call, this can also be done through :manpage:`open(2)` with the flags +``O_RDONLY | O_TRUNC``. + +When opening a file, the availability of the ``LANDLOCK_ACCESS_FS_TRUNCATE`` +right is associated with the newly created file descriptor and will be used for +subsequent truncation attempts using :manpage:`ftruncate(2)`. The behavior is +similar to opening a file for reading or writing, where permissions are checked +during :manpage:`open(2)`, but not during the subsequent :manpage:`read(2)` and +:manpage:`write(2)` calls. + +As a consequence, it is possible to have multiple open file descriptors for the +same file, where one grants the right to truncate the file and the other does +not. It is also possible to pass such file descriptors between processes, +keeping their Landlock properties, even when these processes do not have an +enforced Landlock ruleset. + Compatibility ============= @@ -398,6 +442,15 @@ Starting with the Landlock ABI version 2, it is now possible to securely control renaming and linking thanks to the new ``LANDLOCK_ACCESS_FS_REFER`` access right. +File truncation (ABI < 3) +------------------------- + +File truncation could not be denied before the third Landlock ABI, so it is +always allowed when using a kernel that only supports the first or second ABI. + +Starting with the Landlock ABI version 3, it is now possible to securely control +truncation thanks to the new ``LANDLOCK_ACCESS_FS_TRUNCATE`` access right. + .. _kernel_support: Kernel support diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile index 00922aa7efde..3d8aaf5c253b 100644 --- a/Documentation/userspace-api/media/Makefile +++ b/Documentation/userspace-api/media/Makefile @@ -47,10 +47,11 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception # Media build rules -.PHONY: all html epub xml latex +.PHONY: all html texinfo epub xml latex all: $(IMGDOT) $(BUILDDIR) ${TARGETS} html: all +texinfo: all epub: all xml: all latex: $(IMGPDF) all diff --git a/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst b/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst index b0efce40471f..411d42a742f3 100644 --- a/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst +++ b/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. _cec_pin_error_inj: + CEC Pin Framework Error Injection ================================= diff --git a/Documentation/userspace-api/media/drivers/aspeed-video.rst b/Documentation/userspace-api/media/drivers/aspeed-video.rst new file mode 100644 index 000000000000..1b0cb1e3eba8 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/aspeed-video.rst @@ -0,0 +1,65 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: <isonum.txt> + +ASPEED video driver +=================== + +ASPEED Video Engine found on AST2400/2500/2600 SoC supports high performance +video compressions with a wide range of video quality and compression ratio +options. The adopted compressing algorithm is a modified JPEG algorithm. + +There are 2 types of compressions in this IP. + +* JPEG JFIF standard mode: for single frame and management compression +* ASPEED proprietary mode: for multi-frame and differential compression. + Support 2-pass (high quality) video compression scheme (Patent pending by + ASPEED). Provide visually lossless video compression quality or to reduce + the network average loading under intranet KVM applications. + +VIDIOC_S_FMT can be used to choose which format you want. V4L2_PIX_FMT_JPEG +stands for JPEG JFIF standard mode; V4L2_PIX_FMT_AJPG stands for ASPEED +proprietary mode. + +More details on the ASPEED video hardware operations can be found in +*chapter 6.2.16 KVM Video Driver* of SDK_User_Guide which available on +AspeedTech-BMC/openbmc/releases. + +The ASPEED video driver implements the following driver-specific control: + +``V4L2_CID_ASPEED_HQ_MODE`` +--------------------------- + Enable/Disable ASPEED's High quality mode. This is a private control + that can be used to enable high quality for aspeed proprietary mode. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - ``(0)`` + - ASPEED HQ mode is disabled. + * - ``(1)`` + - ASPEED HQ mode is enabled. + +``V4L2_CID_ASPEED_HQ_JPEG_QUALITY`` +----------------------------------- + Define the quality of ASPEED's High quality mode. This is a private control + that can be used to decide compression quality if High quality mode enabled + . Higher the value, better the quality and bigger the size. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - ``(1)`` + - minimum + * - ``(12)`` + - maximum + * - ``(1)`` + - step + * - ``(1)`` + - default + +**Copyright** |copy| 2022 ASPEED Technology Inc. diff --git a/Documentation/userspace-api/media/drivers/index.rst b/Documentation/userspace-api/media/drivers/index.rst index 32f82aed47d9..915dbf0f4db5 100644 --- a/Documentation/userspace-api/media/drivers/index.rst +++ b/Documentation/userspace-api/media/drivers/index.rst @@ -31,6 +31,7 @@ For more details see the file COPYING in the source distribution of Linux. :maxdepth: 5 :numbered: + aspeed-video ccs cx2341x-uapi dw100 @@ -38,4 +39,5 @@ For more details see the file COPYING in the source distribution of Linux. max2175 meye-uapi omap3isp-uapi + st-vgxy61 uvcvideo diff --git a/Documentation/userspace-api/media/drivers/st-vgxy61.rst b/Documentation/userspace-api/media/drivers/st-vgxy61.rst new file mode 100644 index 000000000000..d9e3b80e3a96 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/st-vgxy61.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 + +ST VGXY61 camera sensor driver +============================== + +The ST VGXY61 driver implements the following controls: + +``V4L2_CID_HDR_SENSOR_MODE`` +------------------------------- + Change the sensor HDR mode. A HDR picture is obtained by merging two + captures of the same scene using two different exposure periods. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - HDR linearize + - The merger outputs a long exposure capture as long as it is not + saturated. + * - HDR substraction + - This involves subtracting the short exposure frame from the long + exposure frame. + * - No HDR + - This mode is used for standard dynamic range (SDR) exposures. diff --git a/Documentation/userspace-api/media/dvb/fe_property_parameters.rst b/Documentation/userspace-api/media/dvb/fe_property_parameters.rst index ecd84a8790a2..1717a0565fe8 100644 --- a/Documentation/userspace-api/media/dvb/fe_property_parameters.rst +++ b/Documentation/userspace-api/media/dvb/fe_property_parameters.rst @@ -89,16 +89,21 @@ ATSC (version 1) 8-VSB and 16-VSB. DMTB 4-QAM, 16-QAM, 32-QAM, 64-QAM and 4-QAM-NR. DVB-C Annex A/C 16-QAM, 32-QAM, 64-QAM and 256-QAM. DVB-C Annex B 64-QAM. +DVB-C2 QPSK, 16-QAM, 64-QAM, 256-QAM, 1024-QAM and 4096-QAM. DVB-T QPSK, 16-QAM and 64-QAM. DVB-T2 QPSK, 16-QAM, 64-QAM and 256-QAM. DVB-S No need to set. It supports only QPSK. DVB-S2 QPSK, 8-PSK, 16-APSK and 32-APSK. +DVB-S2X 8-APSK-L, 16-APSK-L, 32-APSK-L, 64-APSK and 64-APSK-L. ISDB-T QPSK, DQPSK, 16-QAM and 64-QAM. ISDB-S 8-PSK, QPSK and BPSK. ======================= ======================================================= .. note:: + As DVB-S2X specifies extensions to the DVB-S2 standard, the same + delivery system enum value is used (SYS_DVBS2). + Please notice that some of the above modulation types may not be defined currently at the Kernel. The reason is simple: no driver needed such definition yet. @@ -854,9 +859,10 @@ The acceptable values are defined by :c:type:`fe_guard_interval`. #. If ``DTV_GUARD_INTERVAL`` is set the ``GUARD_INTERVAL_AUTO`` the hardware will try to find the correct guard interval (if capable) and will use TMCC to fill in the missing parameters. - #. Intervals ``GUARD_INTERVAL_1_128``, ``GUARD_INTERVAL_19_128`` - and ``GUARD_INTERVAL_19_256`` are used only for DVB-T2 at - present. + #. Interval ``GUARD_INTERVAL_1_64`` is used only for DVB-C2. + #. Interval ``GUARD_INTERVAL_1_128`` is used for both DVB-C2 and DVB_T2. + #. Intervals ``GUARD_INTERVAL_19_128`` and ``GUARD_INTERVAL_19_256`` are + used only for DVB-T2. #. Intervals ``GUARD_INTERVAL_PN420``, ``GUARD_INTERVAL_PN595`` and ``GUARD_INTERVAL_PN945`` are used only for DMTB at the present. On such standard, only those intervals and ``GUARD_INTERVAL_AUTO`` @@ -916,14 +922,15 @@ The acceptable values are defined by :c:type:`fe_hierarchy`. DTV_STREAM_ID ============= -Used on DVB-S2, DVB-T2 and ISDB-S. +Used on DVB-C2, DVB-S2, DVB-T2 and ISDB-S. -DVB-S2, DVB-T2 and ISDB-S support the transmission of several streams on -a single transport stream. This property enables the digital TV driver to -handle substream filtering, when supported by the hardware. By default, -substream filtering is disabled. +DVB-C2, DVB-S2, DVB-T2 and ISDB-S support the transmission of several +streams on a single transport stream. This property enables the digital +TV driver to handle substream filtering, when supported by the hardware. +By default, substream filtering is disabled. -For DVB-S2 and DVB-T2, the valid substream id range is from 0 to 255. +For DVB-C2, DVB-S2 and DVB-T2, the valid substream id range is from 0 to +255. For ISDB, the valid substream id range is from 1 to 65535. diff --git a/Documentation/userspace-api/media/frontend.h.rst.exceptions b/Documentation/userspace-api/media/frontend.h.rst.exceptions index 6283702c08c8..8b73fee11a79 100644 --- a/Documentation/userspace-api/media/frontend.h.rst.exceptions +++ b/Documentation/userspace-api/media/frontend.h.rst.exceptions @@ -86,6 +86,13 @@ ignore symbol APSK_16 ignore symbol APSK_32 ignore symbol DQPSK ignore symbol QAM_4_NR +ignore symbol QAM_1024 +ignore symbol QAM_4096 +ignore symbol APSK_8_L +ignore symbol APSK_16_L +ignore symbol APSK_32_L +ignore symbol APSK_64 +ignore symbol APSK_64_L ignore symbol SEC_VOLTAGE_13 ignore symbol SEC_VOLTAGE_18 @@ -119,6 +126,22 @@ ignore symbol FEC_AUTO ignore symbol FEC_3_5 ignore symbol FEC_9_10 ignore symbol FEC_2_5 +ignore symbol FEC_1_3 +ignore symbol FEC_1_4 +ignore symbol FEC_5_9 +ignore symbol FEC_7_9 +ignore symbol FEC_8_15 +ignore symbol FEC_11_15 +ignore symbol FEC_13_18 +ignore symbol FEC_9_20 +ignore symbol FEC_11_20 +ignore symbol FEC_23_36 +ignore symbol FEC_25_36 +ignore symbol FEC_13_45 +ignore symbol FEC_26_45 +ignore symbol FEC_28_45 +ignore symbol FEC_32_45 +ignore symbol FEC_77_90 ignore symbol TRANSMISSION_MODE_AUTO ignore symbol TRANSMISSION_MODE_1K @@ -143,6 +166,7 @@ ignore symbol GUARD_INTERVAL_19_256 ignore symbol GUARD_INTERVAL_PN420 ignore symbol GUARD_INTERVAL_PN595 ignore symbol GUARD_INTERVAL_PN945 +ignore symbol GUARD_INTERVAL_1_64 ignore symbol HIERARCHY_NONE ignore symbol HIERARCHY_AUTO @@ -163,6 +187,9 @@ ignore symbol ROLLOFF_35 ignore symbol ROLLOFF_20 ignore symbol ROLLOFF_25 ignore symbol ROLLOFF_AUTO +ignore symbol ROLLOFF_15 +ignore symbol ROLLOFF_10 +ignore symbol ROLLOFF_5 ignore symbol INVERSION_ON ignore symbol INVERSION_OFF @@ -187,6 +214,7 @@ ignore symbol SYS_DAB ignore symbol SYS_DSS ignore symbol SYS_CMMB ignore symbol SYS_DVBH +ignore symbol SYS_DVBC2 ignore symbol ATSCMH_SCCC_BLK_SEP ignore symbol ATSCMH_SCCC_BLK_COMB diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst index 4638ec64db00..04dec3e570ed 100644 --- a/Documentation/userspace-api/media/v4l/buffer.rst +++ b/Documentation/userspace-api/media/v4l/buffer.rst @@ -187,10 +187,8 @@ struct v4l2_buffer on the negotiated data format and may change with each buffer for compressed variable size data like JPEG images. Drivers must set this field when ``type`` refers to a capture stream, applications - when it refers to an output stream. If the application sets this - to 0 for an output stream, then ``bytesused`` will be set to the - size of the buffer (see the ``length`` field of this struct) by - the driver. For multiplanar formats this field is ignored and the + when it refers to an output stream. For multiplanar formats this field + is ignored and the ``planes`` pointer is used instead. * - __u32 - ``flags`` @@ -327,10 +325,7 @@ struct v4l2_plane - ``bytesused`` - The number of bytes occupied by data in the plane (its payload). Drivers must set this field when ``type`` refers to a capture - stream, applications when it refers to an output stream. If the - application sets this to 0 for an output stream, then - ``bytesused`` will be set to the size of the plane (see the - ``length`` field of this struct) by the driver. + stream, applications when it refers to an output stream. .. note:: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst index 4c5061aa9cd4..daa4f40869f8 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst @@ -661,3 +661,11 @@ enum v4l2_scene_mode - .. [#f1] This control may be changed to a menu control in the future, if more options are required. + +``V4L2_CID_HDR_SENSOR_MODE (menu)`` + Change the sensor HDR mode. A HDR picture is obtained by merging two + captures of the same scene using two different exposure periods. HDR mode + describes the way these two captures are merged in the sensor. + + As modes differ for each sensor, menu items are not standardized by this + control and are left to the programmer. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst index 0ff68cd8cf62..73cd99828010 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst @@ -258,6 +258,23 @@ please make a proposal on the linux-media mailing list. and it is used by various multimedia hardware blocks like GPU, display controllers, ISP and video accelerators. It contains four planes for progressive video. + * .. _V4L2-PIX-FMT-AJPG: + + - ``V4L2_PIX_FMT_AJPG`` + - 'AJPG' + - ASPEED JPEG format used by the aspeed-video driver on Aspeed platforms, + which is generally adapted for remote KVM. + On each frame compression, I will compare the new frame with previous + one to decide which macroblock's data is changed, and only the changed + macroblocks will be compressed. + + The implementation is based on AST2600 A3 datasheet, revision 0.9, which + is not publicly available. Or you can reference Video stream data format + – ASPEED mode compression of SDK_User_Guide which available on + AspeedTech-BMC/openbmc/releases. + + Decoder's implementation can be found here, + `aspeed_codec <https://github.com/AspeedTech-BMC/aspeed_codec/>`__ .. raw:: latex \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst index 10b1feeb0b57..f1d5bb7b806d 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst @@ -273,7 +273,9 @@ of the luma plane. .. _V4L2-PIX-FMT-NV12-16L16: .. _V4L2-PIX-FMT-NV12-32L32: .. _V4L2-PIX-FMT-NV12M-8L128: +.. _V4L2-PIX-FMT-NV12-8L128: .. _V4L2-PIX-FMT-NV12M-10BE-8L128: +.. _V4L2-PIX-FMT-NV12-10BE-8L128: .. _V4L2-PIX-FMT-MM21: Tiled NV12 @@ -319,6 +321,9 @@ pixels in 2D 8x128 tiles, and stores tiles linearly in memory. The image height must be aligned to a multiple of 128. The layouts of the luma and chroma planes are identical. +``V4L2_PIX_FMT_NV12_8L128`` is similar to ``V4L2_PIX_FMT_NV12M_8L128`` but stores +two planes in one memory. + ``V4L2_PIX_FMT_NV12M_10BE_8L128`` is similar to ``V4L2_PIX_FMT_NV12M`` but stores 10 bits pixels in 2D 8x128 tiles, and stores tiles linearly in memory. the data is arranged in big endian order. @@ -334,6 +339,9 @@ byte 2: Y1(bits 3-0) Y2(bits 9-6) byte 3: Y2(bits 5-0) Y3(bits 9-8) byte 4: Y3(bits 7-0) +``V4L2_PIX_FMT_NV12_10BE_8L128`` is similar to ``V4L2_PIX_FMT_NV12M_10BE_8L128`` but stores +two planes in one memory. + ``V4L2_PIX_FMT_MM21`` store luma pixel in 16x32 tiles, and chroma pixels in 16x16 tiles. The line stride must be aligned to a multiple of 16 and the image height must be aligned to a multiple of 32. The number of luma and chroma diff --git a/Documentation/userspace-api/media/v4l/subdev-formats.rst b/Documentation/userspace-api/media/v4l/subdev-formats.rst index d21d532eee15..16ef3b41932e 100644 --- a/Documentation/userspace-api/media/v4l/subdev-formats.rst +++ b/Documentation/userspace-api/media/v4l/subdev-formats.rst @@ -6057,6 +6057,43 @@ the following codes. - y\ :sub:`2` - y\ :sub:`1` - y\ :sub:`0` + * .. _MEDIA-BUS-FMT-Y16-1X16: + + - MEDIA_BUS_FMT_Y16_1X16 + - 0x202e + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - y\ :sub:`15` + - y\ :sub:`14` + - y\ :sub:`13` + - y\ :sub:`12` + - y\ :sub:`11` + - y\ :sub:`10` + - y\ :sub:`9` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` * .. _MEDIA-BUS-FMT-UYVY8-1X16: - MEDIA_BUS_FMT_UYVY8_1X16 diff --git a/Documentation/virt/coco/tdx-guest.rst b/Documentation/virt/coco/tdx-guest.rst new file mode 100644 index 000000000000..46e316db6bb4 --- /dev/null +++ b/Documentation/virt/coco/tdx-guest.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================================================== +TDX Guest API Documentation +=================================================================== + +1. General description +====================== + +The TDX guest driver exposes IOCTL interfaces via the /dev/tdx-guest misc +device to allow userspace to get certain TDX guest-specific details. + +2. API description +================== + +In this section, for each supported IOCTL, the following information is +provided along with a generic description. + +:Input parameters: Parameters passed to the IOCTL and related details. +:Output: Details about output data and return value (with details about + the non common error values). + +2.1 TDX_CMD_GET_REPORT0 +----------------------- + +:Input parameters: struct tdx_report_req +:Output: Upon successful execution, TDREPORT data is copied to + tdx_report_req.tdreport and return 0. Return -EINVAL for invalid + operands, -EIO on TDCALL failure or standard error number on other + common failures. + +The TDX_CMD_GET_REPORT0 IOCTL can be used by the attestation software to get +the TDREPORT0 (a.k.a. TDREPORT subtype 0) from the TDX module using +TDCALL[TDG.MR.REPORT]. + +A subtype index is added at the end of this IOCTL CMD to uniquely identify the +subtype-specific TDREPORT request. Although the subtype option is mentioned in +the TDX Module v1.0 specification, section titled "TDG.MR.REPORT", it is not +currently used, and it expects this value to be 0. So to keep the IOCTL +implementation simple, the subtype option was not included as part of the input +ABI. However, in the future, if the TDX Module supports more than one subtype, +a new IOCTL CMD will be created to handle it. To keep the IOCTL naming +consistent, a subtype index is added as part of the IOCTL CMD. + +Reference +--------- + +TDX reference material is collected here: + +https://www.intel.com/content/www/us/en/developer/articles/technical/intel-trust-domain-extensions.html + +The driver is based on TDX module specification v1.0 and TDX GHCI specification v1.0. diff --git a/Documentation/virt/index.rst b/Documentation/virt/index.rst index 2f1cffa87b1b..56e003ff28ff 100644 --- a/Documentation/virt/index.rst +++ b/Documentation/virt/index.rst @@ -14,6 +14,7 @@ Linux Virtualization Support ne_overview acrn/index coco/sev-guest + coco/tdx-guest hyperv/index .. only:: html and subproject diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 778c6460d1de..0dd5d8733dd5 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -7225,14 +7225,13 @@ veto the transition. :Parameters: args[0] is the maximum poll time in nanoseconds :Returns: 0 on success; -1 on error -This capability overrides the kvm module parameter halt_poll_ns for the -target VM. - -VCPU polling allows a VCPU to poll for wakeup events instead of immediately -scheduling during guest halts. The maximum time a VCPU can spend polling is -controlled by the kvm module parameter halt_poll_ns. This capability allows -the maximum halt time to specified on a per-VM basis, effectively overriding -the module parameter for the target VM. +KVM_CAP_HALT_POLL overrides the kvm.halt_poll_ns module parameter to set the +maximum halt-polling time for all vCPUs in the target VM. This capability can +be invoked at any time and any number of times to dynamically change the +maximum halt-polling time. + +See Documentation/virt/kvm/halt-polling.rst for more information on halt +polling. 7.21 KVM_CAP_X86_USER_SPACE_MSR ------------------------------- diff --git a/Documentation/virt/kvm/x86/halt-polling.rst b/Documentation/virt/kvm/halt-polling.rst index 4922e4a15f18..3fae39b1a5ba 100644 --- a/Documentation/virt/kvm/x86/halt-polling.rst +++ b/Documentation/virt/kvm/halt-polling.rst @@ -119,6 +119,19 @@ These module parameters can be set from the debugfs files in: Note: that these module parameters are system wide values and are not able to be tuned on a per vm basis. +Any changes to these parameters will be picked up by new and existing vCPUs the +next time they halt, with the notable exception of VMs using KVM_CAP_HALT_POLL +(see next section). + +KVM_CAP_HALT_POLL +================= + +KVM_CAP_HALT_POLL is a VM capability that allows userspace to override halt_poll_ns +on a per-VM basis. VMs using KVM_CAP_HALT_POLL ignore halt_poll_ns completely (but +still obey halt_poll_ns_grow, halt_poll_ns_grow_start, and halt_poll_ns_shrink). + +See Documentation/virt/kvm/api.rst for more information on this capability. + Further Notes ============= diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst index e0a2c74e1043..ad13ec55ddfe 100644 --- a/Documentation/virt/kvm/index.rst +++ b/Documentation/virt/kvm/index.rst @@ -17,4 +17,5 @@ KVM locking vcpu-requests + halt-polling review-checklist diff --git a/Documentation/virt/kvm/x86/index.rst b/Documentation/virt/kvm/x86/index.rst index 7ff588826b9f..9ece6b8dc817 100644 --- a/Documentation/virt/kvm/x86/index.rst +++ b/Documentation/virt/kvm/x86/index.rst @@ -10,7 +10,6 @@ KVM for x86 systems amd-memory-encryption cpuid errata - halt-polling hypercalls mmu msr diff --git a/Documentation/x86/boot.rst b/Documentation/x86/boot.rst index 894a19897005..240d084782a6 100644 --- a/Documentation/x86/boot.rst +++ b/Documentation/x86/boot.rst @@ -455,6 +455,7 @@ Protocol: 2.00+ 11 Minimal Linux Bootloader <http://sebastian-plotz.blogspot.de> 12 OVMF UEFI virtualization stack + 13 barebox == ======================================= Please contact <hpa@zytor.com> if you need a bootloader ID value assigned. diff --git a/Documentation/x86/tdx.rst b/Documentation/x86/tdx.rst index b8fa4329e1a5..dc8d9fd2c3f7 100644 --- a/Documentation/x86/tdx.rst +++ b/Documentation/x86/tdx.rst @@ -210,6 +210,49 @@ converted to shared on boot. For coherent DMA allocation, the DMA buffer gets converted on the allocation. Check force_dma_unencrypted() for details. +Attestation +=========== + +Attestation is used to verify the TDX guest trustworthiness to other +entities before provisioning secrets to the guest. For example, a key +server may want to use attestation to verify that the guest is the +desired one before releasing the encryption keys to mount the encrypted +rootfs or a secondary drive. + +The TDX module records the state of the TDX guest in various stages of +the guest boot process using the build time measurement register (MRTD) +and runtime measurement registers (RTMR). Measurements related to the +guest initial configuration and firmware image are recorded in the MRTD +register. Measurements related to initial state, kernel image, firmware +image, command line options, initrd, ACPI tables, etc are recorded in +RTMR registers. For more details, as an example, please refer to TDX +Virtual Firmware design specification, section titled "TD Measurement". +At TDX guest runtime, the attestation process is used to attest to these +measurements. + +The attestation process consists of two steps: TDREPORT generation and +Quote generation. + +TDX guest uses TDCALL[TDG.MR.REPORT] to get the TDREPORT (TDREPORT_STRUCT) +from the TDX module. TDREPORT is a fixed-size data structure generated by +the TDX module which contains guest-specific information (such as build +and boot measurements), platform security version, and the MAC to protect +the integrity of the TDREPORT. A user-provided 64-Byte REPORTDATA is used +as input and included in the TDREPORT. Typically it can be some nonce +provided by attestation service so the TDREPORT can be verified uniquely. +More details about the TDREPORT can be found in Intel TDX Module +specification, section titled "TDG.MR.REPORT Leaf". + +After getting the TDREPORT, the second step of the attestation process +is to send it to the Quoting Enclave (QE) to generate the Quote. TDREPORT +by design can only be verified on the local platform as the MAC key is +bound to the platform. To support remote verification of the TDREPORT, +TDX leverages Intel SGX Quoting Enclave to verify the TDREPORT locally +and convert it to a remotely verifiable Quote. Method of sending TDREPORT +to QE is implementation specific. Attestation software can choose +whatever communication channel available (i.e. vsock or TCP/IP) to +send the TDREPORT to QE and receive the Quote. + References ========== |