diff options
Diffstat (limited to 'Documentation')
409 files changed, 12749 insertions, 5374 deletions
diff --git a/Documentation/ABI/stable/sysfs-bus-vmbus b/Documentation/ABI/stable/sysfs-bus-vmbus index c27b7b89477c..42599d9fa161 100644 --- a/Documentation/ABI/stable/sysfs-bus-vmbus +++ b/Documentation/ABI/stable/sysfs-bus-vmbus @@ -1,3 +1,10 @@ +What: /sys/bus/vmbus/hibernation +Date: Jan 2021 +KernelVersion: 5.12 +Contact: Dexuan Cui <decui@microsoft.com> +Description: Whether the host supports hibernation for the VM. +Users: Daemon that sets up swap partition/file for hibernation. + What: /sys/bus/vmbus/devices/<UUID>/id Date: Jul 2009 KernelVersion: 2.6.31 diff --git a/Documentation/ABI/stable/sysfs-class-tpm b/Documentation/ABI/stable/sysfs-class-tpm index 91ca63ec7581..d897ecb9615f 100644 --- a/Documentation/ABI/stable/sysfs-class-tpm +++ b/Documentation/ABI/stable/sysfs-class-tpm @@ -194,3 +194,17 @@ Description: The "tpm_version_major" property shows the TCG spec major version Example output:: 2 + +What: /sys/class/tpm/tpmX/pcr-H/N +Date: March 2021 +KernelVersion: 5.12 +Contact: linux-integrity@vger.kernel.org +Description: produces output in compact hex representation for PCR + number N from hash bank H. N is the numeric value of + the PCR number and H is the crypto string + representation of the hash + + Example output:: + + cat /sys/class/tpm/tpm0/pcr-sha256/7 + 2ED93F199692DC6788EFA6A1FE74514AB9760B2A6CEEAEF6C808C13E4ABB0D42 diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy index e35263f97fc1..bc8e1cbe5e61 100644 --- a/Documentation/ABI/testing/ima_policy +++ b/Documentation/ABI/testing/ima_policy @@ -32,7 +32,7 @@ Description: func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK]MODULE_CHECK] [FIRMWARE_CHECK] [KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK] - [KEXEC_CMDLINE] [KEY_CHECK] + [KEXEC_CMDLINE] [KEY_CHECK] [CRITICAL_DATA] mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND] [[^]MAY_EXEC] fsmagic:= hex value @@ -52,6 +52,9 @@ Description: template:= name of a defined IMA template type (eg, ima-ng). Only valid when action is "measure". pcr:= decimal value + label:= [selinux]|[kernel_info]|[data_label] + data_label:= a unique string used for grouping and limiting critical data. + For example, "selinux" to measure critical data for SELinux. default policy: # PROC_SUPER_MAGIC diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index 35289d47d6cb..d957f5da5c04 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -198,6 +198,7 @@ Description: Units after application of scale and offset are m/s^2. What: /sys/bus/iio/devices/iio:deviceX/in_angl_raw +What: /sys/bus/iio/devices/iio:deviceX/in_anglY_raw KernelVersion: 4.17 Contact: linux-iio@vger.kernel.org Description: @@ -1812,3 +1813,13 @@ Contact: linux-iio@vger.kernel.org Description: Unscaled light intensity according to CIE 1931/DIN 5033 color space. Units after application of scale are nano nanowatts per square meter. + +What: /sys/bus/iio/devices/iio:deviceX/in_anglY_label +KernelVersion: 5.12 +Contact: linux-iio@vger.kernel.org +Description: + Optional symbolic label for channel Y. + For Intel hid hinge sensor, the label values are: + hinge, keyboard, screen. It means the three channels + each correspond respectively to hinge angle, keyboard angle, + and screen angle. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-dac-ad5766 b/Documentation/ABI/testing/sysfs-bus-iio-dac-ad5766 new file mode 100644 index 000000000000..7fbcba15bf1e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-dac-ad5766 @@ -0,0 +1,31 @@ +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_dither_enable +KernelVersion: 5.12 +Contact: linux-iio@vger.kernel.org +Description: + Dither enable. Write 1 to enable dither or 0 to disable it. + +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_dither_invert +KernelVersion: 5.12 +Contact: linux-iio@vger.kernel.org +Description: + Inverts the dither applied to the selected DAC channel. Dither is not + inverted by default. Write "1" to invert dither. + +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_dither_scale_available +KernelVersion: 5.12 +Contact: linux-iio@vger.kernel.org +Description: + Returns possible scalings available for the current channel. + +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_dither_scale +KernelVersion: 5.12 +Contact: linux-iio@vger.kernel.org +Description: + Scales the dither before it is applied to the selected channel. + +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_dither_source +KernelVersion: 5.12 +Contact: linux-iio@vger.kernel.org +Description: + Selects dither source applied to the selected channel. Write "0" to + select N0 source, write "1" to select N1 source. diff --git a/Documentation/ABI/testing/sysfs-bus-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt index a91b4b24496e..d7f09d011b6d 100644 --- a/Documentation/ABI/testing/sysfs-bus-thunderbolt +++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt @@ -49,6 +49,15 @@ Description: Holds a comma separated list of device unique_ids that If a device is authorized automatically during boot its boot attribute is set to 1. +What: /sys/bus/thunderbolt/devices/.../domainX/deauthorization +Date: May 2021 +KernelVersion: 5.12 +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> +Description: This attribute tells whether the system supports + de-authorization of devices. Value of 1 means user can + de-authorize PCIe tunnel by writing 0 to authorized + attribute under each device. + What: /sys/bus/thunderbolt/devices/.../domainX/iommu_dma_protection Date: Mar 2019 KernelVersion: 4.21 @@ -76,6 +85,8 @@ Description: This attribute holds current Thunderbolt security level usbonly Automatically tunnel USB controller of the connected Thunderbolt dock (and Display Port). All PCIe links downstream of the dock are removed. + nopcie USB4 system where PCIe tunneling is disabled from + the BIOS. ======= ================================================== What: /sys/bus/thunderbolt/devices/.../authorized @@ -84,22 +95,25 @@ KernelVersion: 4.13 Contact: thunderbolt-software@lists.01.org Description: This attribute is used to authorize Thunderbolt devices after they have been connected. If the device is not - authorized, no devices such as PCIe and Display port are - available to the system. + authorized, no PCIe devices are available to the system. Contents of this attribute will be 0 when the device is not yet authorized. Possible values are supported: - == =========================================== + == =================================================== + 0 The device will be de-authorized (only supported if + deauthorization attribute under domain contains 1) 1 The device will be authorized and connected - == =========================================== + == =================================================== When key attribute contains 32 byte hex string the possible values are: == ======================================================== + 0 The device will be de-authorized (only supported if + deauthorization attribute under domain contains 1) 1 The 32 byte hex string is added to the device NVM and the device is authorized. 2 Send a challenge based on the 32 byte hex string. If the diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-tty b/Documentation/ABI/testing/sysfs-class-led-trigger-tty new file mode 100644 index 000000000000..2bf6b24e781b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led-trigger-tty @@ -0,0 +1,6 @@ +What: /sys/class/leds/<led>/ttyname +Date: Dec 2020 +KernelVersion: 5.10 +Contact: linux-leds@vger.kernel.org +Description: + Specifies the tty device name of the triggering tty diff --git a/Documentation/ABI/testing/sysfs-class-net b/Documentation/ABI/testing/sysfs-class-net index 1f2002df5ba2..1419103d11f9 100644 --- a/Documentation/ABI/testing/sysfs-class-net +++ b/Documentation/ABI/testing/sysfs-class-net @@ -337,3 +337,18 @@ Contact: netdev@vger.kernel.org Description: 32-bit unsigned integer counting the number of times the link has been down + +What: /sys/class/net/<iface>/threaded +Date: Jan 2021 +KernelVersion: 5.12 +Contact: netdev@vger.kernel.org +Description: + Boolean value to control the threaded mode per device. User could + set this value to enable/disable threaded mode for all napi + belonging to this device, without the need to do device up/down. + + Possible values: + == ================================== + 0 threaded mode disabled for this dev + 1 threaded mode enabled for this dev + == ================================== diff --git a/Documentation/ABI/testing/sysfs-class-net-dsa b/Documentation/ABI/testing/sysfs-class-net-dsa index 985d84c585c6..e2da26b44dd0 100644 --- a/Documentation/ABI/testing/sysfs-class-net-dsa +++ b/Documentation/ABI/testing/sysfs-class-net-dsa @@ -3,5 +3,12 @@ Date: August 2018 KernelVersion: 4.20 Contact: netdev@vger.kernel.org Description: - String indicating the type of tagging protocol used by the - DSA slave network device. + On read, this file returns a string indicating the type of + tagging protocol used by the DSA network devices that are + attached to this master interface. + On write, this file changes the tagging protocol of the + attached DSA switches, if this operation is supported by the + driver. Changing the tagging protocol must be done with the DSA + interfaces and the master interface all administratively down. + See the "name" field of each registered struct dsa_device_ops + for a list of valid values. diff --git a/Documentation/ABI/testing/sysfs-class-net-qmi b/Documentation/ABI/testing/sysfs-class-net-qmi index c310db4ccbc2..ed79f5893421 100644 --- a/Documentation/ABI/testing/sysfs-class-net-qmi +++ b/Documentation/ABI/testing/sysfs-class-net-qmi @@ -48,3 +48,13 @@ Description: Write a number ranging from 1 to 254 to delete a previously created qmap mux based network device. + +What: /sys/class/net/<qmimux iface>/qmap/mux_id +Date: January 2021 +KernelVersion: 5.12 +Contact: Daniele Palmas <dnlplm@gmail.com> +Description: + Unsigned integer + + Indicates the mux id associated to the qmimux network interface + during its creation. diff --git a/Documentation/ABI/testing/sysfs-class-typec b/Documentation/ABI/testing/sysfs-class-typec index 8eab41e79ce6..40122d915ae1 100644 --- a/Documentation/ABI/testing/sysfs-class-typec +++ b/Documentation/ABI/testing/sysfs-class-typec @@ -105,7 +105,25 @@ Date: April 2017 Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> Description: Revision number of the supported USB Power Delivery - specification, or 0 when USB Power Delivery is not supported. + specification, or 0.0 when USB Power Delivery is not supported. + + Example values: + - "2.0": USB Power Delivery Release 2.0 + - "3.0": USB Power Delivery Release 3.0 + - "3.1": USB Power Delivery Release 3.1 + +What: /sys/class/typec/<port>-{partner|cable}/usb_power_delivery_revision +Date: January 2021 +Contact: Benson Leung <bleung@chromium.org> +Description: + Revision number of the supported USB Power Delivery + specification of the port partner or cable, or 0.0 when USB + Power Delivery is not supported. + + Example values: + - "2.0": USB Power Delivery Release 2.0 + - "3.0": USB Power Delivery Release 3.0 + - "3.1": USB Power Delivery Release 3.1 What: /sys/class/typec/<port>/usb_typec_revision Date: April 2017 diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index 3dfee94e0618..cbeac1bebe2f 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -377,3 +377,35 @@ Description: This gives a control to limit the bio size in f2fs. Default is zero, which will follow underlying block layer limit, whereas, if it has a certain bytes value, f2fs won't submit a bio larger than that size. + +What: /sys/fs/f2fs/<disk>/stat/sb_status +Date: December 2020 +Contact: "Chao Yu" <yuchao0@huawei.com> +Description: Show status of f2fs superblock in real time. + + ====== ===================== ================================= + value sb status macro description + 0x1 SBI_IS_DIRTY dirty flag for checkpoint + 0x2 SBI_IS_CLOSE specify unmounting + 0x4 SBI_NEED_FSCK need fsck.f2fs to fix + 0x8 SBI_POR_DOING recovery is doing or not + 0x10 SBI_NEED_SB_WRITE need to recover superblock + 0x20 SBI_NEED_CP need to checkpoint + 0x40 SBI_IS_SHUTDOWN shutdown by ioctl + 0x80 SBI_IS_RECOVERED recovered orphan/data + 0x100 SBI_CP_DISABLED CP was disabled last mount + 0x200 SBI_CP_DISABLED_QUICK CP was disabled quickly + 0x400 SBI_QUOTA_NEED_FLUSH need to flush quota info in CP + 0x800 SBI_QUOTA_SKIP_FLUSH skip flushing quota in current CP + 0x1000 SBI_QUOTA_NEED_REPAIR quota file may be corrupted + 0x2000 SBI_IS_RESIZEFS resizefs is in process + ====== ===================== ================================= + +What: /sys/fs/f2fs/<disk>/ckpt_thread_ioprio +Date: January 2021 +Contact: "Daeho Jeong" <daehojeong@google.com> +Description: Give a way to change checkpoint merge daemon's io priority. + Its default value is "be,3", which means "BE" I/O class and + I/O priority "3". We can select the class between "rt" and "be", + and set the I/O priority within valid range of it. "," delimiter + is necessary in between I/O class and priority number. diff --git a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop index fd2ac02bc5bd..4989ab266682 100644 --- a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop +++ b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop @@ -1,11 +1,11 @@ -What: /sys/devices/platform/ideapad/camera_power +What: /sys/bus/platform/devices/VPC2004:*/camera_power Date: Dec 2010 KernelVersion: 2.6.37 Contact: "Ike Panhc <ike.pan@canonical.com>" Description: Control the power of camera module. 1 means on, 0 means off. -What: /sys/devices/platform/ideapad/fan_mode +What: /sys/bus/platform/devices/VPC2004:*/fan_mode Date: June 2012 KernelVersion: 3.6 Contact: "Maxim Mikityanskiy <maxtram95@gmail.com>" @@ -18,7 +18,7 @@ Description: * 2 -> Dust Cleaning * 4 -> Efficient Thermal Dissipation Mode -What: /sys/devices/platform/ideapad/touchpad +What: /sys/bus/platform/devices/VPC2004:*/touchpad Date: May 2017 KernelVersion: 4.13 Contact: "Ritesh Raj Sarraf <rrs@debian.org>" @@ -27,7 +27,16 @@ Description: * 1 -> Switched On * 0 -> Switched Off -What: /sys/bus/pci/devices/<bdf>/<device>/VPC2004:00/fn_lock +What: /sys/bus/platform/devices/VPC2004:*/conservation_mode +Date: Aug 2017 +KernelVersion: 4.14 +Contact: platform-driver-x86@vger.kernel.org +Description: + Controls whether the conservation mode is enabled or not. + This feature limits the maximum battery charge percentage to + around 50-60% in order to prolong the lifetime of the battery. + +What: /sys/bus/platform/devices/VPC2004:*/fn_lock Date: May 2018 KernelVersion: 4.18 Contact: "Oleg Keri <ezhi99@gmail.com>" @@ -41,3 +50,12 @@ Description: # echo "0" > \ /sys/bus/pci/devices/0000:00:1f.0/PNP0C09:00/VPC2004:00/fn_lock + +What: /sys/bus/platform/devices/VPC2004:*/usb_charging +Date: Feb 2021 +KernelVersion: 5.12 +Contact: platform-driver-x86@vger.kernel.org +Description: + Controls whether the "always on USB charging" feature is + enabled or not. This feature enables charging USB devices + even if the computer is not turned on. diff --git a/Documentation/ABI/testing/sysfs-platform_profile b/Documentation/ABI/testing/sysfs-platform_profile new file mode 100644 index 000000000000..9d6b89b66cca --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform_profile @@ -0,0 +1,24 @@ +What: /sys/firmware/acpi/platform_profile_choices +Date: October 2020 +Contact: Hans de Goede <hdegoede@redhat.com> +Description: This file contains a space-separated list of profiles supported for this device. + + Drivers must use the following standard profile-names: + + ============ ============================================ + low-power Low power consumption + cool Cooler operation + quiet Quieter operation + balanced Balance between low power consumption and performance + performance High performance operation + ============ ============================================ + + Userspace may expect drivers to offer more than one of these + standard profile names. + +What: /sys/firmware/acpi/platform_profile +Date: October 2020 +Contact: Hans de Goede <hdegoede@redhat.com> +Description: Reading this file gives the current selected profile for this + device. Writing this file with one of the strings from + platform_profile_choices changes the profile to the new value. diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst index 72f0f6fbd53c..6f89cf1e567d 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst @@ -38,7 +38,7 @@ sections. RCU-preempt Expedited Grace Periods =================================== -``CONFIG_PREEMPT=y`` kernels implement RCU-preempt. +``CONFIG_PREEMPTION=y`` kernels implement RCU-preempt. The overall flow of the handling of a given CPU by an RCU-preempt expedited grace period is shown in the following diagram: @@ -112,7 +112,7 @@ things. RCU-sched Expedited Grace Periods --------------------------------- -``CONFIG_PREEMPT=n`` kernels implement RCU-sched. The overall flow of +``CONFIG_PREEMPTION=n`` kernels implement RCU-sched. The overall flow of the handling of a given CPU by an RCU-sched expedited grace period is shown in the following diagram: diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst index d4c9a016074b..38a39476fc24 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.rst +++ b/Documentation/RCU/Design/Requirements/Requirements.rst @@ -72,13 +72,13 @@ understanding of this guarantee. RCU's grace-period guarantee allows updaters to wait for the completion of all pre-existing RCU read-side critical sections. An RCU read-side -critical section begins with the marker ``rcu_read_lock()`` and ends -with the marker ``rcu_read_unlock()``. These markers may be nested, and +critical section begins with the marker rcu_read_lock() and ends +with the marker rcu_read_unlock(). These markers may be nested, and RCU treats a nested set as one big RCU read-side critical section. -Production-quality implementations of ``rcu_read_lock()`` and -``rcu_read_unlock()`` are extremely lightweight, and in fact have +Production-quality implementations of rcu_read_lock() and +rcu_read_unlock() are extremely lightweight, and in fact have exactly zero overhead in Linux kernels built for production use with -``CONFIG_PREEMPT=n``. +``CONFIG_PREEMPTION=n``. This guarantee allows ordering to be enforced with extremely low overhead to readers, for example: @@ -102,12 +102,12 @@ overhead to readers, for example: 15 WRITE_ONCE(y, 1); 16 } -Because the ``synchronize_rcu()`` on line 14 waits for all pre-existing -readers, any instance of ``thread0()`` that loads a value of zero from -``x`` must complete before ``thread1()`` stores to ``y``, so that +Because the synchronize_rcu() on line 14 waits for all pre-existing +readers, any instance of thread0() that loads a value of zero from +``x`` must complete before thread1() stores to ``y``, so that instance must also load a value of zero from ``y``. Similarly, any -instance of ``thread0()`` that loads a value of one from ``y`` must have -started after the ``synchronize_rcu()`` started, and must therefore also +instance of thread0() that loads a value of one from ``y`` must have +started after the synchronize_rcu() started, and must therefore also load a value of one from ``x``. Therefore, the outcome: :: @@ -121,14 +121,14 @@ cannot happen. +-----------------------------------------------------------------------+ | Wait a minute! You said that updaters can make useful forward | | progress concurrently with readers, but pre-existing readers will | -| block ``synchronize_rcu()``!!! | +| block synchronize_rcu()!!! | | Just who are you trying to fool??? | +-----------------------------------------------------------------------+ | **Answer**: | +-----------------------------------------------------------------------+ | First, if updaters do not wish to be blocked by readers, they can use | -| ``call_rcu()`` or ``kfree_rcu()``, which will be discussed later. | -| Second, even when using ``synchronize_rcu()``, the other update-side | +| call_rcu() or kfree_rcu(), which will be discussed later. | +| Second, even when using synchronize_rcu(), the other update-side | | code does run concurrently with readers, whether pre-existing or not. | +-----------------------------------------------------------------------+ @@ -170,34 +170,34 @@ recovery from node failure, more or less as follows: 29 WRITE_ONCE(state, STATE_NORMAL); 30 } -The RCU read-side critical section in ``do_something_dlm()`` works with -the ``synchronize_rcu()`` in ``start_recovery()`` to guarantee that -``do_something()`` never runs concurrently with ``recovery()``, but with -little or no synchronization overhead in ``do_something_dlm()``. +The RCU read-side critical section in do_something_dlm() works with +the synchronize_rcu() in start_recovery() to guarantee that +do_something() never runs concurrently with recovery(), but with +little or no synchronization overhead in do_something_dlm(). +-----------------------------------------------------------------------+ | **Quick Quiz**: | +-----------------------------------------------------------------------+ -| Why is the ``synchronize_rcu()`` on line 28 needed? | +| Why is the synchronize_rcu() on line 28 needed? | +-----------------------------------------------------------------------+ | **Answer**: | +-----------------------------------------------------------------------+ | Without that extra grace period, memory reordering could result in | -| ``do_something_dlm()`` executing ``do_something()`` concurrently with | -| the last bits of ``recovery()``. | +| do_something_dlm() executing do_something() concurrently with | +| the last bits of recovery(). | +-----------------------------------------------------------------------+ In order to avoid fatal problems such as deadlocks, an RCU read-side -critical section must not contain calls to ``synchronize_rcu()``. +critical section must not contain calls to synchronize_rcu(). Similarly, an RCU read-side critical section must not contain anything that waits, directly or indirectly, on completion of an invocation of -``synchronize_rcu()``. +synchronize_rcu(). Although RCU's grace-period guarantee is useful in and of itself, with `quite a few use cases <https://lwn.net/Articles/573497/>`__, it would be good to be able to use RCU to coordinate read-side access to linked data structures. For this, the grace-period guarantee is not sufficient, -as can be seen in function ``add_gp_buggy()`` below. We will look at the +as can be seen in function add_gp_buggy() below. We will look at the reader's code later, but in the meantime, just think of the reader as locklessly picking up the ``gp`` pointer, and, if the value loaded is non-\ ``NULL``, locklessly accessing the ``->a`` and ``->b`` fields. @@ -256,8 +256,8 @@ Publish/Subscribe Guarantee RCU's publish-subscribe guarantee allows data to be inserted into a linked data structure without disrupting RCU readers. The updater uses -``rcu_assign_pointer()`` to insert the new data, and readers use -``rcu_dereference()`` to access data, whether new or old. The following +rcu_assign_pointer() to insert the new data, and readers use +rcu_dereference() to access data, whether new or old. The following shows an example of insertion: :: @@ -279,7 +279,7 @@ shows an example of insertion: 15 return true; 16 } -The ``rcu_assign_pointer()`` on line 13 is conceptually equivalent to a +The rcu_assign_pointer() on line 13 is conceptually equivalent to a simple assignment statement, but also guarantees that its assignment will happen after the two assignments in lines 11 and 12, similar to the C11 ``memory_order_release`` store operation. It also prevents any @@ -289,7 +289,7 @@ number of “interesting” compiler optimizations, for example, the use of +-----------------------------------------------------------------------+ | **Quick Quiz**: | +-----------------------------------------------------------------------+ -| But ``rcu_assign_pointer()`` does nothing to prevent the two | +| But rcu_assign_pointer() does nothing to prevent the two | | assignments to ``p->a`` and ``p->b`` from being reordered. Can't that | | also cause problems? | +-----------------------------------------------------------------------+ @@ -303,7 +303,7 @@ number of “interesting” compiler optimizations, for example, the use of It is tempting to assume that the reader need not do anything special to control its accesses to the RCU-protected data, as shown in -``do_something_gp_buggy()`` below: +do_something_gp_buggy() below: :: @@ -321,11 +321,10 @@ control its accesses to the RCU-protected data, as shown in 12 } However, this temptation must be resisted because there are a -surprisingly large number of ways that the compiler (to say nothing of -`DEC Alpha CPUs <https://h71000.www7.hp.com/wizard/wiz_2637.html>`__) -can trip this code up. For but one example, if the compiler were short -of registers, it might choose to refetch from ``gp`` rather than keeping -a separate copy in ``p`` as follows: +surprisingly large number of ways that the compiler (or weak ordering +CPUs like the DEC Alpha) can trip this code up. For but one example, if +the compiler were short of registers, it might choose to refetch from +``gp`` rather than keeping a separate copy in ``p`` as follows: :: @@ -345,7 +344,7 @@ If this function ran concurrently with a series of updates that replaced the current structure with a new one, the fetches of ``gp->a`` and ``gp->b`` might well come from two different structures, which could cause serious confusion. To prevent this (and much else besides), -``do_something_gp()`` uses ``rcu_dereference()`` to fetch from ``gp``: +do_something_gp() uses rcu_dereference() to fetch from ``gp``: :: @@ -362,21 +361,21 @@ cause serious confusion. To prevent this (and much else besides), 11 return false; 12 } -The ``rcu_dereference()`` uses volatile casts and (for DEC Alpha) memory +The rcu_dereference() uses volatile casts and (for DEC Alpha) memory barriers in the Linux kernel. Should a `high-quality implementation of C11 ``memory_order_consume`` [PDF] <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__ -ever appear, then ``rcu_dereference()`` could be implemented as a +ever appear, then rcu_dereference() could be implemented as a ``memory_order_consume`` load. Regardless of the exact implementation, a -pointer fetched by ``rcu_dereference()`` may not be used outside of the +pointer fetched by rcu_dereference() may not be used outside of the outermost RCU read-side critical section containing that -``rcu_dereference()``, unless protection of the corresponding data +rcu_dereference(), unless protection of the corresponding data element has been passed from RCU to some other synchronization mechanism, most commonly locking or `reference counting <https://www.kernel.org/doc/Documentation/RCU/rcuref.txt>`__. -In short, updaters use ``rcu_assign_pointer()`` and readers use -``rcu_dereference()``, and these two RCU API elements work together to +In short, updaters use rcu_assign_pointer() and readers use +rcu_dereference(), and these two RCU API elements work together to ensure that readers have a consistent view of newly added data elements. Of course, it is also necessary to remove elements from RCU-protected @@ -388,9 +387,9 @@ data structures, for example, using the following process: the newly removed data element). #. At this point, only the updater has a reference to the newly removed data element, so it can safely reclaim the data element, for example, - by passing it to ``kfree()``. + by passing it to kfree(). -This process is implemented by ``remove_gp_synchronous()``: +This process is implemented by remove_gp_synchronous(): :: @@ -413,16 +412,16 @@ This process is implemented by ``remove_gp_synchronous()``: This function is straightforward, with line 13 waiting for a grace period before line 14 frees the old data element. This waiting ensures -that readers will reach line 7 of ``do_something_gp()`` before the data -element referenced by ``p`` is freed. The ``rcu_access_pointer()`` on -line 6 is similar to ``rcu_dereference()``, except that: +that readers will reach line 7 of do_something_gp() before the data +element referenced by ``p`` is freed. The rcu_access_pointer() on +line 6 is similar to rcu_dereference(), except that: -#. The value returned by ``rcu_access_pointer()`` cannot be +#. The value returned by rcu_access_pointer() cannot be dereferenced. If you want to access the value pointed to as well as - the pointer itself, use ``rcu_dereference()`` instead of - ``rcu_access_pointer()``. -#. The call to ``rcu_access_pointer()`` need not be protected. In - contrast, ``rcu_dereference()`` must either be within an RCU + the pointer itself, use rcu_dereference() instead of + rcu_access_pointer(). +#. The call to rcu_access_pointer() need not be protected. In + contrast, rcu_dereference() must either be within an RCU read-side critical section or in a code segment where the pointer cannot change, for example, in code protected by the corresponding update-side lock. @@ -430,13 +429,13 @@ line 6 is similar to ``rcu_dereference()``, except that: +-----------------------------------------------------------------------+ | **Quick Quiz**: | +-----------------------------------------------------------------------+ -| Without the ``rcu_dereference()`` or the ``rcu_access_pointer()``, | +| Without the rcu_dereference() or the rcu_access_pointer(), | | what destructive optimizations might the compiler make use of? | +-----------------------------------------------------------------------+ | **Answer**: | +-----------------------------------------------------------------------+ -| Let's start with what happens to ``do_something_gp()`` if it fails to | -| use ``rcu_dereference()``. It could reuse a value formerly fetched | +| Let's start with what happens to do_something_gp() if it fails to | +| use rcu_dereference(). It could reuse a value formerly fetched | | from this same pointer. It could also fetch the pointer from ``gp`` | | in a byte-at-a-time manner, resulting in *load tearing*, in turn | | resulting a bytewise mash-up of two distinct pointer values. It might | @@ -445,15 +444,15 @@ line 6 is similar to ``rcu_dereference()``, except that: | update has changed the pointer to match the wrong guess. Too bad | | about any dereferences that returned pre-initialization garbage in | | the meantime! | -| For ``remove_gp_synchronous()``, as long as all modifications to | +| For remove_gp_synchronous(), as long as all modifications to | | ``gp`` are carried out while holding ``gp_lock``, the above | | optimizations are harmless. However, ``sparse`` will complain if you | | define ``gp`` with ``__rcu`` and then access it without using either | -| ``rcu_access_pointer()`` or ``rcu_dereference()``. | +| rcu_access_pointer() or rcu_dereference(). | +-----------------------------------------------------------------------+ In short, RCU's publish-subscribe guarantee is provided by the -combination of ``rcu_assign_pointer()`` and ``rcu_dereference()``. This +combination of rcu_assign_pointer() and rcu_dereference(). This guarantee allows data elements to be safely added to RCU-protected linked data structures without disrupting RCU readers. This guarantee can be used in combination with the grace-period guarantee to also allow @@ -462,9 +461,9 @@ again without disrupting RCU readers. This guarantee was only partially premeditated. DYNIX/ptx used an explicit memory barrier for publication, but had nothing resembling -``rcu_dereference()`` for subscription, nor did it have anything +rcu_dereference() for subscription, nor did it have anything resembling the dependency-ordering barrier that was later subsumed -into ``rcu_dereference()`` and later still into ``READ_ONCE()``. The +into rcu_dereference() and later still into READ_ONCE(). The need for these operations made itself known quite suddenly at a late-1990s meeting with the DEC Alpha architects, back in the days when DEC was still a free-standing company. It took the Alpha architects a @@ -474,7 +473,7 @@ documentation did not make this point clear. More recent work with the C and C++ standards committees have provided much education on tricks and traps from the compiler. In short, compilers were much less tricky in the early 1990s, but in 2015, don't even think about omitting -``rcu_dereference()``! +rcu_dereference()! Memory-Barrier Guarantees ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -484,31 +483,31 @@ demonstrates the need for RCU's stringent memory-ordering guarantees on systems with more than one CPU: #. Each CPU that has an RCU read-side critical section that begins - before ``synchronize_rcu()`` starts is guaranteed to execute a full + before synchronize_rcu() starts is guaranteed to execute a full memory barrier between the time that the RCU read-side critical - section ends and the time that ``synchronize_rcu()`` returns. Without + section ends and the time that synchronize_rcu() returns. Without this guarantee, a pre-existing RCU read-side critical section might hold a reference to the newly removed ``struct foo`` after the - ``kfree()`` on line 14 of ``remove_gp_synchronous()``. + kfree() on line 14 of remove_gp_synchronous(). #. Each CPU that has an RCU read-side critical section that ends after - ``synchronize_rcu()`` returns is guaranteed to execute a full memory - barrier between the time that ``synchronize_rcu()`` begins and the + synchronize_rcu() returns is guaranteed to execute a full memory + barrier between the time that synchronize_rcu() begins and the time that the RCU read-side critical section begins. Without this guarantee, a later RCU read-side critical section running after the - ``kfree()`` on line 14 of ``remove_gp_synchronous()`` might later run - ``do_something_gp()`` and find the newly deleted ``struct foo``. -#. If the task invoking ``synchronize_rcu()`` remains on a given CPU, + kfree() on line 14 of remove_gp_synchronous() might later run + do_something_gp() and find the newly deleted ``struct foo``. +#. If the task invoking synchronize_rcu() remains on a given CPU, then that CPU is guaranteed to execute a full memory barrier sometime - during the execution of ``synchronize_rcu()``. This guarantee ensures - that the ``kfree()`` on line 14 of ``remove_gp_synchronous()`` really + during the execution of synchronize_rcu(). This guarantee ensures + that the kfree() on line 14 of remove_gp_synchronous() really does execute after the removal on line 11. -#. If the task invoking ``synchronize_rcu()`` migrates among a group of +#. If the task invoking synchronize_rcu() migrates among a group of CPUs during that invocation, then each of the CPUs in that group is guaranteed to execute a full memory barrier sometime during the - execution of ``synchronize_rcu()``. This guarantee also ensures that - the ``kfree()`` on line 14 of ``remove_gp_synchronous()`` really does + execution of synchronize_rcu(). This guarantee also ensures that + the kfree() on line 14 of remove_gp_synchronous() really does execute after the removal on line 11, but also in the case where the - thread executing the ``synchronize_rcu()`` migrates in the meantime. + thread executing the synchronize_rcu() migrates in the meantime. +-----------------------------------------------------------------------+ | **Quick Quiz**: | @@ -516,19 +515,19 @@ systems with more than one CPU: | Given that multiple CPUs can start RCU read-side critical sections at | | any time without any ordering whatsoever, how can RCU possibly tell | | whether or not a given RCU read-side critical section starts before a | -| given instance of ``synchronize_rcu()``? | +| given instance of synchronize_rcu()? | +-----------------------------------------------------------------------+ | **Answer**: | +-----------------------------------------------------------------------+ | If RCU cannot tell whether or not a given RCU read-side critical | -| section starts before a given instance of ``synchronize_rcu()``, then | +| section starts before a given instance of synchronize_rcu(), then | | it must assume that the RCU read-side critical section started first. | -| In other words, a given instance of ``synchronize_rcu()`` can avoid | +| In other words, a given instance of synchronize_rcu() can avoid | | waiting on a given RCU read-side critical section only if it can | -| prove that ``synchronize_rcu()`` started first. | -| A related question is “When ``rcu_read_lock()`` doesn't generate any | +| prove that synchronize_rcu() started first. | +| A related question is “When rcu_read_lock() doesn't generate any | | code, why does it matter how it relates to a grace period?” The | -| answer is that it is not the relationship of ``rcu_read_lock()`` | +| answer is that it is not the relationship of rcu_read_lock() | | itself that is important, but rather the relationship of the code | | within the enclosed RCU read-side critical section to the code | | preceding and following the grace period. If we take this viewpoint, | @@ -556,14 +555,14 @@ systems with more than one CPU: | Yes, they really are required. To see why the first guarantee is | | required, consider the following sequence of events: | | | -| #. CPU 1: ``rcu_read_lock()`` | +| #. CPU 1: rcu_read_lock() | | #. CPU 1: ``q = rcu_dereference(gp); /* Very likely to return p. */`` | | #. CPU 0: ``list_del_rcu(p);`` | -| #. CPU 0: ``synchronize_rcu()`` starts. | +| #. CPU 0: synchronize_rcu() starts. | | #. CPU 1: ``do_something_with(q->a);`` | | ``/* No smp_mb(), so might happen after kfree(). */`` | -| #. CPU 1: ``rcu_read_unlock()`` | -| #. CPU 0: ``synchronize_rcu()`` returns. | +| #. CPU 1: rcu_read_unlock() | +| #. CPU 0: synchronize_rcu() returns. | | #. CPU 0: ``kfree(p);`` | | | | Therefore, there absolutely must be a full memory barrier between the | @@ -574,14 +573,14 @@ systems with more than one CPU: | is roughly similar: | | | | #. CPU 0: ``list_del_rcu(p);`` | -| #. CPU 0: ``synchronize_rcu()`` starts. | -| #. CPU 1: ``rcu_read_lock()`` | +| #. CPU 0: synchronize_rcu() starts. | +| #. CPU 1: rcu_read_lock() | | #. CPU 1: ``q = rcu_dereference(gp);`` | | ``/* Might return p if no memory barrier. */`` | -| #. CPU 0: ``synchronize_rcu()`` returns. | +| #. CPU 0: synchronize_rcu() returns. | | #. CPU 0: ``kfree(p);`` | | #. CPU 1: ``do_something_with(q->a); /* Boom!!! */`` | -| #. CPU 1: ``rcu_read_unlock()`` | +| #. CPU 1: rcu_read_unlock() | | | | And similarly, without a memory barrier between the beginning of the | | grace period and the beginning of the RCU read-side critical section, | @@ -597,7 +596,7 @@ systems with more than one CPU: +-----------------------------------------------------------------------+ | **Quick Quiz**: | +-----------------------------------------------------------------------+ -| You claim that ``rcu_read_lock()`` and ``rcu_read_unlock()`` generate | +| You claim that rcu_read_lock() and rcu_read_unlock() generate | | absolutely no code in some kernel builds. This means that the | | compiler might arbitrarily rearrange consecutive RCU read-side | | critical sections. Given such rearrangement, if a given RCU read-side | @@ -607,11 +606,11 @@ systems with more than one CPU: +-----------------------------------------------------------------------+ | **Answer**: | +-----------------------------------------------------------------------+ -| In cases where ``rcu_read_lock()`` and ``rcu_read_unlock()`` generate | +| In cases where rcu_read_lock() and rcu_read_unlock() generate | | absolutely no code, RCU infers quiescent states only at special | | locations, for example, within the scheduler. Because calls to | -| ``schedule()`` had better prevent calling-code accesses to shared | -| variables from being rearranged across the call to ``schedule()``, if | +| schedule() had better prevent calling-code accesses to shared | +| variables from being rearranged across the call to schedule(), if | | RCU detects the end of a given RCU read-side critical section, it | | will necessarily detect the end of all prior RCU read-side critical | | sections, no matter how aggressively the compiler scrambles the code. | @@ -655,8 +654,8 @@ read-side critical section might search for a given data element, and then might acquire the update-side spinlock in order to update that element, all while remaining in that RCU read-side critical section. Of course, it is necessary to exit the RCU read-side critical section -before invoking ``synchronize_rcu()``, however, this inconvenience can -be avoided through use of the ``call_rcu()`` and ``kfree_rcu()`` API +before invoking synchronize_rcu(), however, this inconvenience can +be avoided through use of the call_rcu() and kfree_rcu() API members described later in this document. +-----------------------------------------------------------------------+ @@ -694,10 +693,10 @@ these non-guarantees were premeditated. Readers Impose Minimal Ordering ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Reader-side markers such as ``rcu_read_lock()`` and -``rcu_read_unlock()`` provide absolutely no ordering guarantees except +Reader-side markers such as rcu_read_lock() and +rcu_read_unlock() provide absolutely no ordering guarantees except through their interaction with the grace-period APIs such as -``synchronize_rcu()``. To see this, consider the following pair of +synchronize_rcu(). To see this, consider the following pair of threads: :: @@ -722,7 +721,7 @@ threads: 18 rcu_read_unlock(); 19 } -After ``thread0()`` and ``thread1()`` execute concurrently, it is quite +After thread0() and thread1() execute concurrently, it is quite possible to have :: @@ -730,7 +729,7 @@ possible to have (r1 == 1 && r2 == 0) (that is, ``y`` appears to have been assigned before ``x``), which would -not be possible if ``rcu_read_lock()`` and ``rcu_read_unlock()`` had +not be possible if rcu_read_lock() and rcu_read_unlock() had much in the way of ordering properties. But they do not, so the CPU is within its rights to do significant reordering. This is by design: Any significant ordering constraints would slow down these fast-path APIs. @@ -742,14 +741,14 @@ significant ordering constraints would slow down these fast-path APIs. +-----------------------------------------------------------------------+ | **Answer**: | +-----------------------------------------------------------------------+ -| No, the volatile casts in ``READ_ONCE()`` and ``WRITE_ONCE()`` | +| No, the volatile casts in READ_ONCE() and WRITE_ONCE() | | prevent the compiler from reordering in this particular case. | +-----------------------------------------------------------------------+ Readers Do Not Exclude Updaters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Neither ``rcu_read_lock()`` nor ``rcu_read_unlock()`` exclude updates. +Neither rcu_read_lock() nor rcu_read_unlock() exclude updates. All they do is to prevent grace periods from ending. The following example illustrates this: @@ -775,19 +774,19 @@ example illustrates this: 18 spin_unlock(&my_lock); 19 } -If the ``thread0()`` function's ``rcu_read_lock()`` excluded the -``thread1()`` function's update, the ``WARN_ON()`` could never fire. But -the fact is that ``rcu_read_lock()`` does not exclude much of anything -aside from subsequent grace periods, of which ``thread1()`` has none, so -the ``WARN_ON()`` can and does fire. +If the thread0() function's rcu_read_lock() excluded the +thread1() function's update, the WARN_ON() could never fire. But +the fact is that rcu_read_lock() does not exclude much of anything +aside from subsequent grace periods, of which thread1() has none, so +the WARN_ON() can and does fire. Updaters Only Wait For Old Readers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -It might be tempting to assume that after ``synchronize_rcu()`` +It might be tempting to assume that after synchronize_rcu() completes, there are no readers executing. This temptation must be avoided because new readers can start immediately after -``synchronize_rcu()`` starts, and ``synchronize_rcu()`` is under no +synchronize_rcu() starts, and synchronize_rcu() is under no obligation to wait for these new readers. +-----------------------------------------------------------------------+ @@ -799,10 +798,10 @@ obligation to wait for these new readers. +-----------------------------------------------------------------------+ | **Answer**: | +-----------------------------------------------------------------------+ -| For no time at all. Even if ``synchronize_rcu()`` were to wait until | +| For no time at all. Even if synchronize_rcu() were to wait until | | all readers had completed, a new reader might start immediately after | -| ``synchronize_rcu()`` completed. Therefore, the code following | -| ``synchronize_rcu()`` can *never* rely on there being no readers. | +| synchronize_rcu() completed. Therefore, the code following | +| synchronize_rcu() can *never* rely on there being no readers. | +-----------------------------------------------------------------------+ Grace Periods Don't Partition Read-Side Critical Sections @@ -892,12 +891,12 @@ period is known to end before the second grace period starts: 28 rcu_read_unlock(); 29 } -Here, if ``(r1 == 1)``, then ``thread0()``'s write to ``b`` must happen -before the end of ``thread1()``'s grace period. If in addition -``(r4 == 1)``, then ``thread3()``'s read from ``b`` must happen after -the beginning of ``thread2()``'s grace period. If it is also the case -that ``(r2 == 1)``, then the end of ``thread1()``'s grace period must -precede the beginning of ``thread2()``'s grace period. This mean that +Here, if ``(r1 == 1)``, then thread0()'s write to ``b`` must happen +before the end of thread1()'s grace period. If in addition +``(r4 == 1)``, then thread3()'s read from ``b`` must happen after +the beginning of thread2()'s grace period. If it is also the case +that ``(r2 == 1)``, then the end of thread1()'s grace period must +precede the beginning of thread2()'s grace period. This mean that the two RCU read-side critical sections cannot overlap, guaranteeing that ``(r3 == 1)``. As a result, the outcome: @@ -1076,8 +1075,8 @@ is captured by the following list of situations: b. Wait-free read-side primitives for real-time use. This focus on read-mostly situations means that RCU must interoperate -with other synchronization primitives. For example, the ``add_gp()`` and -``remove_gp_synchronous()`` examples discussed earlier use RCU to +with other synchronization primitives. For example, the add_gp() and +remove_gp_synchronous() examples discussed earlier use RCU to protect readers and locking to coordinate updaters. However, the need extends much farther, requiring that a variety of synchronization primitives be legal within RCU read-side critical sections, including @@ -1104,11 +1103,11 @@ memory barriers. | sections. | | Note that it *is* legal for a normal RCU read-side critical section | | to conditionally acquire a sleeping locks (as in | -| ``mutex_trylock()``), but only as long as it does not loop | +| mutex_trylock()), but only as long as it does not loop | | indefinitely attempting to conditionally acquire that sleeping locks. | -| The key point is that things like ``mutex_trylock()`` either return | +| The key point is that things like mutex_trylock() either return | | with the mutex held, or return an error indication if the mutex was | -| not immediately available. Either way, ``mutex_trylock()`` returns | +| not immediately available. Either way, mutex_trylock() returns | | immediately without sleeping. | +-----------------------------------------------------------------------+ @@ -1182,8 +1181,8 @@ and has become decreasingly so as memory sizes have expanded and memory costs have plummeted. However, as I learned from Matt Mackall's `bloatwatch <http://elinux.org/Linux_Tiny-FAQ>`__ efforts, memory footprint is critically important on single-CPU systems with -non-preemptible (``CONFIG_PREEMPT=n``) kernels, and thus `tiny -RCU <https://lkml.kernel.org/g/20090113221724.GA15307@linux.vnet.ibm.com>`__ +non-preemptible (``CONFIG_PREEMPTION=n``) kernels, and thus `tiny +RCU <https://lore.kernel.org/r/20090113221724.GA15307@linux.vnet.ibm.com>`__ was born. Josh Triplett has since taken over the small-memory banner with his `Linux kernel tinification <https://tiny.wiki.kernel.org/>`__ project, which resulted in `SRCU <Sleepable RCU_>`__ becoming optional @@ -1191,57 +1190,57 @@ for those kernels not needing it. The remaining performance requirements are, for the most part, unsurprising. For example, in keeping with RCU's read-side -specialization, ``rcu_dereference()`` should have negligible overhead +specialization, rcu_dereference() should have negligible overhead (for example, suppression of a few minor compiler optimizations). -Similarly, in non-preemptible environments, ``rcu_read_lock()`` and -``rcu_read_unlock()`` should have exactly zero overhead. +Similarly, in non-preemptible environments, rcu_read_lock() and +rcu_read_unlock() should have exactly zero overhead. In preemptible environments, in the case where the RCU read-side critical section was not preempted (as will be the case for the -highest-priority real-time process), ``rcu_read_lock()`` and -``rcu_read_unlock()`` should have minimal overhead. In particular, they +highest-priority real-time process), rcu_read_lock() and +rcu_read_unlock() should have minimal overhead. In particular, they should not contain atomic read-modify-write operations, memory-barrier instructions, preemption disabling, interrupt disabling, or backwards branches. However, in the case where the RCU read-side critical section -was preempted, ``rcu_read_unlock()`` may acquire spinlocks and disable +was preempted, rcu_read_unlock() may acquire spinlocks and disable interrupts. This is why it is better to nest an RCU read-side critical section within a preempt-disable region than vice versa, at least in cases where that critical section is short enough to avoid unduly degrading real-time latencies. -The ``synchronize_rcu()`` grace-period-wait primitive is optimized for +The synchronize_rcu() grace-period-wait primitive is optimized for throughput. It may therefore incur several milliseconds of latency in addition to the duration of the longest RCU read-side critical section. On the other hand, multiple concurrent invocations of -``synchronize_rcu()`` are required to use batching optimizations so that +synchronize_rcu() are required to use batching optimizations so that they can be satisfied by a single underlying grace-period-wait operation. For example, in the Linux kernel, it is not unusual for a single grace-period-wait operation to serve more than `1,000 separate invocations <https://www.usenix.org/conference/2004-usenix-annual-technical-conference/making-rcu-safe-deep-sub-millisecond-response>`__ -of ``synchronize_rcu()``, thus amortizing the per-invocation overhead +of synchronize_rcu(), thus amortizing the per-invocation overhead down to nearly zero. However, the grace-period optimization is also required to avoid measurable degradation of real-time scheduling and interrupt latencies. -In some cases, the multi-millisecond ``synchronize_rcu()`` latencies are -unacceptable. In these cases, ``synchronize_rcu_expedited()`` may be +In some cases, the multi-millisecond synchronize_rcu() latencies are +unacceptable. In these cases, synchronize_rcu_expedited() may be used instead, reducing the grace-period latency down to a few tens of microseconds on small systems, at least in cases where the RCU read-side critical sections are short. There are currently no special latency -requirements for ``synchronize_rcu_expedited()`` on large systems, but, +requirements for synchronize_rcu_expedited() on large systems, but, consistent with the empirical nature of the RCU specification, that is subject to change. However, there most definitely are scalability -requirements: A storm of ``synchronize_rcu_expedited()`` invocations on +requirements: A storm of synchronize_rcu_expedited() invocations on 4096 CPUs should at least make reasonable forward progress. In return -for its shorter latencies, ``synchronize_rcu_expedited()`` is permitted +for its shorter latencies, synchronize_rcu_expedited() is permitted to impose modest degradation of real-time latency on non-idle online CPUs. Here, “modest” means roughly the same latency degradation as a scheduling-clock interrupt. There are a number of situations where even -``synchronize_rcu_expedited()``'s reduced grace-period latency is -unacceptable. In these situations, the asynchronous ``call_rcu()`` can -be used in place of ``synchronize_rcu()`` as follows: +synchronize_rcu_expedited()'s reduced grace-period latency is +unacceptable. In these situations, the asynchronous call_rcu() can +be used in place of synchronize_rcu() as follows: :: @@ -1275,19 +1274,19 @@ be used in place of ``synchronize_rcu()`` as follows: 28 } A definition of ``struct foo`` is finally needed, and appears on -lines 1-5. The function ``remove_gp_cb()`` is passed to ``call_rcu()`` +lines 1-5. The function remove_gp_cb() is passed to call_rcu() on line 25, and will be invoked after the end of a subsequent grace -period. This gets the same effect as ``remove_gp_synchronous()``, but +period. This gets the same effect as remove_gp_synchronous(), but without forcing the updater to wait for a grace period to elapse. The -``call_rcu()`` function may be used in a number of situations where -neither ``synchronize_rcu()`` nor ``synchronize_rcu_expedited()`` would -be legal, including within preempt-disable code, ``local_bh_disable()`` +call_rcu() function may be used in a number of situations where +neither synchronize_rcu() nor synchronize_rcu_expedited() would +be legal, including within preempt-disable code, local_bh_disable() code, interrupt-disable code, and interrupt handlers. However, even -``call_rcu()`` is illegal within NMI handlers and from idle and offline -CPUs. The callback function (``remove_gp_cb()`` in this case) will be +call_rcu() is illegal within NMI handlers and from idle and offline +CPUs. The callback function (remove_gp_cb() in this case) will be executed within softirq (software interrupt) environment within the Linux kernel, either within a real softirq handler or under the -protection of ``local_bh_disable()``. In both the Linux kernel and in +protection of local_bh_disable(). In both the Linux kernel and in userspace, it is bad practice to write an RCU callback function that takes too long. Long-running operations should be relegated to separate threads or (in the Linux kernel) workqueues. @@ -1295,23 +1294,23 @@ threads or (in the Linux kernel) workqueues. +-----------------------------------------------------------------------+ | **Quick Quiz**: | +-----------------------------------------------------------------------+ -| Why does line 19 use ``rcu_access_pointer()``? After all, | -| ``call_rcu()`` on line 25 stores into the structure, which would | +| Why does line 19 use rcu_access_pointer()? After all, | +| call_rcu() on line 25 stores into the structure, which would | | interact badly with concurrent insertions. Doesn't this mean that | -| ``rcu_dereference()`` is required? | +| rcu_dereference() is required? | +-----------------------------------------------------------------------+ | **Answer**: | +-----------------------------------------------------------------------+ | Presumably the ``->gp_lock`` acquired on line 18 excludes any | -| changes, including any insertions that ``rcu_dereference()`` would | +| changes, including any insertions that rcu_dereference() would | | protect against. Therefore, any insertions will be delayed until | | after ``->gp_lock`` is released on line 25, which in turn means that | -| ``rcu_access_pointer()`` suffices. | +| rcu_access_pointer() suffices. | +-----------------------------------------------------------------------+ -However, all that ``remove_gp_cb()`` is doing is invoking ``kfree()`` on +However, all that remove_gp_cb() is doing is invoking kfree() on the data element. This is a common idiom, and is supported by -``kfree_rcu()``, which allows “fire and forget” operation as shown +kfree_rcu(), which allows “fire and forget” operation as shown below: :: @@ -1338,20 +1337,20 @@ below: 20 return true; 21 } -Note that ``remove_gp_faf()`` simply invokes ``kfree_rcu()`` and +Note that remove_gp_faf() simply invokes kfree_rcu() and proceeds, without any need to pay any further attention to the -subsequent grace period and ``kfree()``. It is permissible to invoke -``kfree_rcu()`` from the same environments as for ``call_rcu()``. -Interestingly enough, DYNIX/ptx had the equivalents of ``call_rcu()`` -and ``kfree_rcu()``, but not ``synchronize_rcu()``. This was due to the +subsequent grace period and kfree(). It is permissible to invoke +kfree_rcu() from the same environments as for call_rcu(). +Interestingly enough, DYNIX/ptx had the equivalents of call_rcu() +and kfree_rcu(), but not synchronize_rcu(). This was due to the fact that RCU was not heavily used within DYNIX/ptx, so the very few -places that needed something like ``synchronize_rcu()`` simply +places that needed something like synchronize_rcu() simply open-coded it. +-----------------------------------------------------------------------+ | **Quick Quiz**: | +-----------------------------------------------------------------------+ -| Earlier it was claimed that ``call_rcu()`` and ``kfree_rcu()`` | +| Earlier it was claimed that call_rcu() and kfree_rcu() | | allowed updaters to avoid being blocked by readers. But how can that | | be correct, given that the invocation of the callback and the freeing | | of the memory (respectively) must still wait for a grace period to | @@ -1363,16 +1362,16 @@ open-coded it. | definition would say that updates in garbage-collected languages | | cannot complete until the next time the garbage collector runs, which | | does not seem at all reasonable. The key point is that in most cases, | -| an updater using either ``call_rcu()`` or ``kfree_rcu()`` can proceed | -| to the next update as soon as it has invoked ``call_rcu()`` or | -| ``kfree_rcu()``, without having to wait for a subsequent grace | +| an updater using either call_rcu() or kfree_rcu() can proceed | +| to the next update as soon as it has invoked call_rcu() or | +| kfree_rcu(), without having to wait for a subsequent grace | | period. | +-----------------------------------------------------------------------+ But what if the updater must wait for the completion of code to be executed after the end of the grace period, but has other tasks that can be carried out in the meantime? The polling-style -``get_state_synchronize_rcu()`` and ``cond_synchronize_rcu()`` functions +get_state_synchronize_rcu() and cond_synchronize_rcu() functions may be used for this purpose, as shown below: :: @@ -1397,11 +1396,11 @@ may be used for this purpose, as shown below: 18 return true; 19 } -On line 14, ``get_state_synchronize_rcu()`` obtains a “cookie” from RCU, +On line 14, get_state_synchronize_rcu() obtains a “cookie” from RCU, then line 15 carries out other tasks, and finally, line 16 returns immediately if a grace period has elapsed in the meantime, but otherwise waits as required. The need for ``get_state_synchronize_rcu`` and -``cond_synchronize_rcu()`` has appeared quite recently, so it is too +cond_synchronize_rcu() has appeared quite recently, so it is too early to tell whether they will stand the test of time. RCU thus provides a range of tools to allow updaters to strike the @@ -1421,8 +1420,8 @@ example, an infinite loop in an RCU read-side critical section must by definition prevent later grace periods from ever completing. For a more involved example, consider a 64-CPU system built with ``CONFIG_RCU_NOCB_CPU=y`` and booted with ``rcu_nocbs=1-63``, where -CPUs 1 through 63 spin in tight loops that invoke ``call_rcu()``. Even -if these tight loops also contain calls to ``cond_resched()`` (thus +CPUs 1 through 63 spin in tight loops that invoke call_rcu(). Even +if these tight loops also contain calls to cond_resched() (thus allowing grace periods to complete), CPU 0 simply will not be able to invoke callbacks as fast as the other 63 CPUs can register them, at least not until the system runs out of memory. In both of these @@ -1435,21 +1434,21 @@ RCU takes the following steps to encourage timely completion of grace periods: #. If a grace period fails to complete within 100 milliseconds, RCU - causes future invocations of ``cond_resched()`` on the holdout CPUs + causes future invocations of cond_resched() on the holdout CPUs to provide an RCU quiescent state. RCU also causes those CPUs' - ``need_resched()`` invocations to return ``true``, but only after the + need_resched() invocations to return ``true``, but only after the corresponding CPU's next scheduling-clock. #. CPUs mentioned in the ``nohz_full`` kernel boot parameter can run indefinitely in the kernel without scheduling-clock interrupts, which - defeats the above ``need_resched()`` strategem. RCU will therefore - invoke ``resched_cpu()`` on any ``nohz_full`` CPUs still holding out + defeats the above need_resched() strategem. RCU will therefore + invoke resched_cpu() on any ``nohz_full`` CPUs still holding out after 109 milliseconds. #. In kernels built with ``CONFIG_RCU_BOOST=y``, if a given task that has been preempted within an RCU read-side critical section is holding out for more than 500 milliseconds, RCU will resort to priority boosting. #. If a CPU is still holding out 10 seconds into the grace period, RCU - will invoke ``resched_cpu()`` on it regardless of its ``nohz_full`` + will invoke resched_cpu() on it regardless of its ``nohz_full`` state. The above values are defaults for systems running with ``HZ=1000``. They @@ -1460,7 +1459,7 @@ caution when changing them. Note that these forward-progress measures are provided only for RCU, not for `SRCU <Sleepable RCU_>`__ or `Tasks RCU`_. -RCU takes the following steps in ``call_rcu()`` to encourage timely +RCU takes the following steps in call_rcu() to encourage timely invocation of callbacks when any given non-\ ``rcu_nocbs`` CPU has 10,000 callbacks, or has 10,000 more callbacks than it had the last time encouragement was provided: @@ -1481,8 +1480,8 @@ RCU, not for `SRCU <Sleepable RCU_>`__ or `Tasks RCU`_. Even for RCU, callback-invocation forward progress for ``rcu_nocbs`` CPUs is much less well-developed, in part because workloads benefiting from ``rcu_nocbs`` CPUs tend to invoke -``call_rcu()`` relatively infrequently. If workloads emerge that need -both ``rcu_nocbs`` CPUs and high ``call_rcu()`` invocation rates, then +call_rcu() relatively infrequently. If workloads emerge that need +both ``rcu_nocbs`` CPUs and high call_rcu() invocation rates, then additional forward-progress work will be required. Composability @@ -1496,11 +1495,11 @@ in fact may be nested arbitrarily deeply. In practice, as with all real-world implementations of composable constructs, there are limitations. -Implementations of RCU for which ``rcu_read_lock()`` and -``rcu_read_unlock()`` generate no code, such as Linux-kernel RCU when -``CONFIG_PREEMPT=n``, can be nested arbitrarily deeply. After all, there +Implementations of RCU for which rcu_read_lock() and +rcu_read_unlock() generate no code, such as Linux-kernel RCU when +``CONFIG_PREEMPTION=n``, can be nested arbitrarily deeply. After all, there is no overhead. Except that if all these instances of -``rcu_read_lock()`` and ``rcu_read_unlock()`` are visible to the +rcu_read_lock() and rcu_read_unlock() are visible to the compiler, compilation will eventually fail due to exhausting memory, mass storage, or user patience, whichever comes first. If the nesting is not visible to the compiler, as is the case with mutually recursive @@ -1558,11 +1557,11 @@ argue that such workloads should instead use something other than RCU, the fact remains that RCU must handle such workloads gracefully. This requirement is another factor driving batching of grace periods, but it is also the driving force behind the checks for large numbers of queued -RCU callbacks in the ``call_rcu()`` code path. Finally, high update +RCU callbacks in the call_rcu() code path. Finally, high update rates should not delay RCU read-side critical sections, although some small read-side delays can occur when using -``synchronize_rcu_expedited()``, courtesy of this function's use of -``smp_call_function_single()``. +synchronize_rcu_expedited(), courtesy of this function's use of +smp_call_function_single(). Although all three of these corner cases were understood in the early 1990s, a simple user-level test consisting of ``close(open(path))`` in a @@ -1583,48 +1582,48 @@ Software-Engineering Requirements Between Murphy's Law and “To err is human”, it is necessary to guard against mishaps and misuse: -#. It is all too easy to forget to use ``rcu_read_lock()`` everywhere +#. It is all too easy to forget to use rcu_read_lock() everywhere that it is needed, so kernels built with ``CONFIG_PROVE_RCU=y`` will - splat if ``rcu_dereference()`` is used outside of an RCU read-side + splat if rcu_dereference() is used outside of an RCU read-side critical section. Update-side code can use - ``rcu_dereference_protected()``, which takes a `lockdep + rcu_dereference_protected(), which takes a `lockdep expression <https://lwn.net/Articles/371986/>`__ to indicate what is providing the protection. If the indicated protection is not provided, a lockdep splat is emitted. Code shared between readers and updaters can use - ``rcu_dereference_check()``, which also takes a lockdep expression, - and emits a lockdep splat if neither ``rcu_read_lock()`` nor the + rcu_dereference_check(), which also takes a lockdep expression, + and emits a lockdep splat if neither rcu_read_lock() nor the indicated protection is in place. In addition, - ``rcu_dereference_raw()`` is used in those (hopefully rare) cases + rcu_dereference_raw() is used in those (hopefully rare) cases where the required protection cannot be easily described. Finally, - ``rcu_read_lock_held()`` is provided to allow a function to verify + rcu_read_lock_held() is provided to allow a function to verify that it has been invoked within an RCU read-side critical section. I was made aware of this set of requirements shortly after Thomas Gleixner audited a number of RCU uses. #. A given function might wish to check for RCU-related preconditions upon entry, before using any other RCU API. The - ``rcu_lockdep_assert()`` does this job, asserting the expression in + rcu_lockdep_assert() does this job, asserting the expression in kernels having lockdep enabled and doing nothing otherwise. -#. It is also easy to forget to use ``rcu_assign_pointer()`` and - ``rcu_dereference()``, perhaps (incorrectly) substituting a simple +#. It is also easy to forget to use rcu_assign_pointer() and + rcu_dereference(), perhaps (incorrectly) substituting a simple assignment. To catch this sort of error, a given RCU-protected pointer may be tagged with ``__rcu``, after which sparse will complain about simple-assignment accesses to that pointer. Arnd Bergmann made me aware of this requirement, and also supplied the needed `patch series <https://lwn.net/Articles/376011/>`__. #. Kernels built with ``CONFIG_DEBUG_OBJECTS_RCU_HEAD=y`` will splat if - a data element is passed to ``call_rcu()`` twice in a row, without a + a data element is passed to call_rcu() twice in a row, without a grace period in between. (This error is similar to a double free.) The corresponding ``rcu_head`` structures that are dynamically allocated are automatically tracked, but ``rcu_head`` structures allocated on the stack must be initialized with - ``init_rcu_head_on_stack()`` and cleaned up with - ``destroy_rcu_head_on_stack()``. Similarly, statically allocated + init_rcu_head_on_stack() and cleaned up with + destroy_rcu_head_on_stack(). Similarly, statically allocated non-stack ``rcu_head`` structures must be initialized with - ``init_rcu_head()`` and cleaned up with ``destroy_rcu_head()``. + init_rcu_head() and cleaned up with destroy_rcu_head(). Mathieu Desnoyers made me aware of this requirement, and also supplied the needed - `patch <https://lkml.kernel.org/g/20100319013024.GA28456@Krystal>`__. + `patch <https://lore.kernel.org/r/20100319013024.GA28456@Krystal>`__. #. An infinite loop in an RCU read-side critical section will eventually trigger an RCU CPU stall warning splat, with the duration of “eventually” being controlled by the ``RCU_CPU_STALL_TIMEOUT`` @@ -1638,9 +1637,9 @@ against mishaps and misuse: ``rcupdate.rcu_cpu_stall_suppress`` to suppress the splats. This kernel parameter may also be set via ``sysfs``. Furthermore, RCU CPU stall warnings are counter-productive during sysrq dumps and during - panics. RCU therefore supplies the ``rcu_sysrq_start()`` and - ``rcu_sysrq_end()`` API members to be called before and after long - sysrq dumps. RCU also supplies the ``rcu_panic()`` notifier that is + panics. RCU therefore supplies the rcu_sysrq_start() and + rcu_sysrq_end() API members to be called before and after long + sysrq dumps. RCU also supplies the rcu_panic() notifier that is automatically invoked at the beginning of a panic to suppress further RCU CPU stall warnings. @@ -1656,7 +1655,7 @@ against mishaps and misuse: synchronization mechanism, for example, reference counting. #. In kernels built with ``CONFIG_RCU_TRACE=y``, RCU-related information is provided via event tracing. -#. Open-coded use of ``rcu_assign_pointer()`` and ``rcu_dereference()`` +#. Open-coded use of rcu_assign_pointer() and rcu_dereference() to create typical linked data structures can be surprisingly error-prone. Therefore, RCU-protected `linked lists <https://lwn.net/Articles/609973/#RCU%20List%20APIs>`__ and, @@ -1665,12 +1664,11 @@ against mishaps and misuse: other special-purpose RCU-protected data structures are available in the Linux kernel and the userspace RCU library. #. Some linked structures are created at compile time, but still require - ``__rcu`` checking. The ``RCU_POINTER_INITIALIZER()`` macro serves + ``__rcu`` checking. The RCU_POINTER_INITIALIZER() macro serves this purpose. -#. It is not necessary to use ``rcu_assign_pointer()`` when creating +#. It is not necessary to use rcu_assign_pointer() when creating linked structures that are to be published via a single external - pointer. The ``RCU_INIT_POINTER()`` macro is provided for this task - and also for assigning ``NULL`` pointers at runtime. + pointer. The RCU_INIT_POINTER() macro is provided for this task. This not a hard-and-fast list: RCU's diagnostic capabilities will continue to be guided by the number and type of usage bugs found in @@ -1716,7 +1714,7 @@ requires almost all of them be hidden behind a ``CONFIG_RCU_EXPERT`` This all should be quite obvious, but the fact remains that Linus Torvalds recently had to -`remind <https://lkml.kernel.org/g/CA+55aFy4wcCwaL4okTs8wXhGZ5h-ibecy_Meg9C4MNQrUnwMcg@mail.gmail.com>`__ +`remind <https://lore.kernel.org/r/CA+55aFy4wcCwaL4okTs8wXhGZ5h-ibecy_Meg9C4MNQrUnwMcg@mail.gmail.com>`__ me of this requirement. Firmware Interface @@ -1743,17 +1741,17 @@ Early Boot ~~~~~~~~~~ The Linux kernel's boot sequence is an interesting process, and RCU is -used early, even before ``rcu_init()`` is invoked. In fact, a number of +used early, even before rcu_init() is invoked. In fact, a number of RCU's primitives can be used as soon as the initial task's ``task_struct`` is available and the boot CPU's per-CPU variables are -set up. The read-side primitives (``rcu_read_lock()``, -``rcu_read_unlock()``, ``rcu_dereference()``, and -``rcu_access_pointer()``) will operate normally very early on, as will -``rcu_assign_pointer()``. +set up. The read-side primitives (rcu_read_lock(), +rcu_read_unlock(), rcu_dereference(), and +rcu_access_pointer()) will operate normally very early on, as will +rcu_assign_pointer(). -Although ``call_rcu()`` may be invoked at any time during boot, +Although call_rcu() may be invoked at any time during boot, callbacks are not guaranteed to be invoked until after all of RCU's -kthreads have been spawned, which occurs at ``early_initcall()`` time. +kthreads have been spawned, which occurs at early_initcall() time. This delay in callback invocation is due to the fact that RCU does not invoke callbacks until it is fully initialized, and this full initialization cannot occur until after the scheduler has initialized @@ -1762,22 +1760,22 @@ it would be possible to invoke callbacks earlier, however, this is not a panacea because there would be severe restrictions on what operations those callbacks could invoke. -Perhaps surprisingly, ``synchronize_rcu()`` and -``synchronize_rcu_expedited()``, will operate normally during very early +Perhaps surprisingly, synchronize_rcu() and +synchronize_rcu_expedited(), will operate normally during very early boot, the reason being that there is only one CPU and preemption is -disabled. This means that the call ``synchronize_rcu()`` (or friends) +disabled. This means that the call synchronize_rcu() (or friends) itself is a quiescent state and thus a grace period, so the early-boot implementation can be a no-op. However, once the scheduler has spawned its first kthread, this early -boot trick fails for ``synchronize_rcu()`` (as well as for -``synchronize_rcu_expedited()``) in ``CONFIG_PREEMPT=y`` kernels. The +boot trick fails for synchronize_rcu() (as well as for +synchronize_rcu_expedited()) in ``CONFIG_PREEMPTION=y`` kernels. The reason is that an RCU read-side critical section might be preempted, -which means that a subsequent ``synchronize_rcu()`` really does have to +which means that a subsequent synchronize_rcu() really does have to wait for something, as opposed to simply returning immediately. -Unfortunately, ``synchronize_rcu()`` can't do this until all of its +Unfortunately, synchronize_rcu() can't do this until all of its kthreads are spawned, which doesn't happen until some time during -``early_initcalls()`` time. But this is no excuse: RCU is nevertheless +early_initcalls() time. But this is no excuse: RCU is nevertheless required to correctly handle synchronous grace periods during this time period. Once all of its kthreads are up and running, RCU starts running normally. @@ -1820,7 +1818,7 @@ Interrupts and NMIs The Linux kernel has interrupts, and RCU read-side critical sections are legal within interrupt handlers and within interrupt-disabled regions of -code, as are invocations of ``call_rcu()``. +code, as are invocations of call_rcu(). Some Linux-kernel architectures can enter an interrupt handler from non-idle process context, and then just never leave it, instead @@ -1832,22 +1830,22 @@ way during a rewrite of RCU's dyntick-idle code. The Linux kernel has non-maskable interrupts (NMIs), and RCU read-side critical sections are legal within NMI handlers. Thankfully, RCU -update-side primitives, including ``call_rcu()``, are prohibited within +update-side primitives, including call_rcu(), are prohibited within NMI handlers. The name notwithstanding, some Linux-kernel architectures can have nested NMIs, which RCU must handle correctly. Andy Lutomirski `surprised -me <https://lkml.kernel.org/r/CALCETrXLq1y7e_dKFPgou-FKHB6Pu-r8+t-6Ds+8=va7anBWDA@mail.gmail.com>`__ +me <https://lore.kernel.org/r/CALCETrXLq1y7e_dKFPgou-FKHB6Pu-r8+t-6Ds+8=va7anBWDA@mail.gmail.com>`__ with this requirement; he also kindly surprised me with `an -algorithm <https://lkml.kernel.org/r/CALCETrXSY9JpW3uE6H8WYk81sg56qasA2aqmjMPsq5dOtzso=g@mail.gmail.com>`__ +algorithm <https://lore.kernel.org/r/CALCETrXSY9JpW3uE6H8WYk81sg56qasA2aqmjMPsq5dOtzso=g@mail.gmail.com>`__ that meets this requirement. Furthermore, NMI handlers can be interrupted by what appear to RCU to be normal interrupts. One way that this can happen is for code that -directly invokes ``rcu_irq_enter()`` and ``rcu_irq_exit()`` to be called +directly invokes rcu_irq_enter() and rcu_irq_exit() to be called from an NMI handler. This astonishing fact of life prompted the current -code structure, which has ``rcu_irq_enter()`` invoking -``rcu_nmi_enter()`` and ``rcu_irq_exit()`` invoking ``rcu_nmi_exit()``. +code structure, which has rcu_irq_enter() invoking +rcu_nmi_enter() and rcu_irq_exit() invoking rcu_nmi_exit(). And yes, I also learned of this requirement the hard way. Loadable Modules @@ -1857,45 +1855,45 @@ The Linux kernel has loadable modules, and these modules can also be 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. +functions, for example, any outstanding mod_timer() must be dealt +with via del_timer_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 +invoke call_rcu(), the callback function is eventually going to be invoked, unless the system goes down first. Because it is normally considered socially irresponsible to crash the system in response to a module unload request, we need some other way to deal with in-flight RCU callbacks. -RCU therefore provides ``rcu_barrier()``, which waits until all +RCU therefore provides rcu_barrier(), which waits until all in-flight RCU callbacks have been invoked. If a module uses -``call_rcu()``, its exit function should therefore prevent any future -invocation of ``call_rcu()``, then invoke ``rcu_barrier()``. In theory, -the underlying module-unload code could invoke ``rcu_barrier()`` +call_rcu(), its exit function should therefore prevent any future +invocation of call_rcu(), then invoke rcu_barrier(). In theory, +the underlying module-unload code could invoke rcu_barrier() unconditionally, but in practice this would incur unacceptable latencies. Nikita Danilov noted this requirement for an analogous filesystem-unmount situation, and Dipankar Sarma incorporated -``rcu_barrier()`` into RCU. The need for ``rcu_barrier()`` for module +rcu_barrier() into RCU. The need for rcu_barrier() for module unloading became apparent later. .. important:: - The ``rcu_barrier()`` function is not, repeat, + The rcu_barrier() function is not, repeat, *not*, obligated to wait for a grace period. It is instead only required to wait for RCU callbacks that have already been posted. Therefore, if there are no RCU callbacks posted anywhere in the system, - ``rcu_barrier()`` is within its rights to return immediately. Even if - there are callbacks posted, ``rcu_barrier()`` does not necessarily need + rcu_barrier() is within its rights to return immediately. Even if + there are callbacks posted, rcu_barrier() does not necessarily need to wait for a grace period. +-----------------------------------------------------------------------+ | **Quick Quiz**: | +-----------------------------------------------------------------------+ | Wait a minute! Each RCU callbacks must wait for a grace period to | -| complete, and ``rcu_barrier()`` must wait for each pre-existing | -| callback to be invoked. Doesn't ``rcu_barrier()`` therefore need to | +| complete, and rcu_barrier() must wait for each pre-existing | +| callback to be invoked. Doesn't rcu_barrier() therefore need to | | wait for a full grace period if there is even one callback posted | | anywhere in the system? | +-----------------------------------------------------------------------+ @@ -1904,14 +1902,14 @@ unloading became apparent later. | Absolutely not!!! | | Yes, each RCU callbacks must wait for a grace period to complete, but | | it might well be partly (or even completely) finished waiting by the | -| time ``rcu_barrier()`` is invoked. In that case, ``rcu_barrier()`` | +| time rcu_barrier() is invoked. In that case, rcu_barrier() | | need only wait for the remaining portion of the grace period to | | elapse. So even if there are quite a few callbacks posted, | -| ``rcu_barrier()`` might well return quite quickly. | +| rcu_barrier() might well return quite quickly. | | | | So if you need to wait for a grace period as well as for all | | pre-existing callbacks, you will need to invoke both | -| ``synchronize_rcu()`` and ``rcu_barrier()``. If latency is a concern, | +| synchronize_rcu() and rcu_barrier(). If latency is a concern, | | you can always use workqueues to invoke them concurrently. | +-----------------------------------------------------------------------+ @@ -1929,18 +1927,18 @@ The Linux-kernel CPU-hotplug implementation has notifiers that are used to allow the various kernel subsystems (including RCU) to respond appropriately to a given CPU-hotplug operation. Most RCU operations may be invoked from CPU-hotplug notifiers, including even synchronous -grace-period operations such as (``synchronize_rcu()`` and -``synchronize_rcu_expedited()``). However, these synchronous operations +grace-period operations such as (synchronize_rcu() and +synchronize_rcu_expedited()). However, these synchronous operations do block and therefore cannot be invoked from notifiers that execute via -``stop_machine()``, specifically those between the ``CPUHP_AP_OFFLINE`` +stop_machine(), specifically those between the ``CPUHP_AP_OFFLINE`` and ``CPUHP_AP_ONLINE`` states. -In addition, all-callback-wait operations such as ``rcu_barrier()`` may +In addition, all-callback-wait operations such as rcu_barrier() may not be invoked from any CPU-hotplug notifier. This restriction is due to the fact that there are phases of CPU-hotplug operations where the outgoing CPU's callbacks will not be invoked until after the CPU-hotplug operation ends, which could also result in deadlock. Furthermore, -``rcu_barrier()`` blocks CPU-hotplug operations during its execution, +rcu_barrier() blocks CPU-hotplug operations during its execution, which results in another type of deadlock when invoked from a CPU-hotplug notifier. @@ -1955,12 +1953,12 @@ if offline CPUs block an RCU grace period for too long. An offline CPU's quiescent state will be reported either: -1. As the CPU goes offline using RCU's hotplug notifier (``rcu_report_dead()``). -2. When grace period initialization (``rcu_gp_init()``) detects a +1. As the CPU goes offline using RCU's hotplug notifier (rcu_report_dead()). +2. When grace period initialization (rcu_gp_init()) detects a race either with CPU offlining or with a task unblocking on a leaf ``rcu_node`` structure whose CPUs are all offline. -The CPU-online path (``rcu_cpu_starting()``) should never need to report +The CPU-online path (rcu_cpu_starting()) should never need to report a quiescent state for an offline CPU. However, as a debugging measure, it does emit a warning if a quiescent state was not already reported for that CPU. @@ -1984,11 +1982,11 @@ room for further improvement. There is no longer any prohibition against holding any of scheduler's runqueue or priority-inheritance spinlocks across an -``rcu_read_unlock()``, even if interrupts and preemption were enabled +rcu_read_unlock(), even if interrupts and preemption were enabled somewhere within the corresponding RCU read-side critical section. -Therefore, it is now perfectly legal to execute ``rcu_read_lock()`` +Therefore, it is now perfectly legal to execute rcu_read_lock() with preemption enabled, acquire one of the scheduler locks, and hold -that lock across the matching ``rcu_read_unlock()``. +that lock across the matching rcu_read_unlock(). Similarly, the RCU flavor consolidation has removed the need for negative nesting. The fact that interrupt-disabled regions of code act as RCU @@ -1999,7 +1997,7 @@ Tracing and RCU ~~~~~~~~~~~~~~~ It is possible to use tracing on RCU code, but tracing itself uses RCU. -For this reason, ``rcu_dereference_raw_check()`` is provided for use +For this reason, rcu_dereference_raw_check() is provided for use by tracing, which avoids the destructive recursion that could otherwise ensue. This API is also used by virtualization in some architectures, where RCU readers execute in environments in which tracing cannot be @@ -2010,12 +2008,12 @@ Accesses to User Memory and RCU ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The kernel needs to access user-space memory, for example, to access data -referenced by system-call parameters. The ``get_user()`` macro does this job. +referenced by system-call parameters. The get_user() macro does this job. However, user-space memory might well be paged out, which means that -``get_user()`` might well page-fault and thus block while waiting for the +get_user() might well page-fault and thus block while waiting for the resulting I/O to complete. It would be a very bad thing for the compiler to -reorder a ``get_user()`` invocation into an RCU read-side critical section. +reorder a get_user() invocation into an RCU read-side critical section. For example, suppose that the source code looked like this: @@ -2040,23 +2038,23 @@ the following: 5 rcu_read_unlock(); 6 do_something_with(v, user_v); -If the compiler did make this transformation in a ``CONFIG_PREEMPT=n`` kernel -build, and if ``get_user()`` did page fault, the result would be a quiescent +If the compiler did make this transformation in a ``CONFIG_PREEMPTION=n`` kernel +build, and if get_user() did page fault, the result would be a quiescent state in the middle of an RCU read-side critical section. This misplaced quiescent state could result in line 4 being a use-after-free access, which could be bad for your kernel's actuarial statistics. Similar examples -can be constructed with the call to ``get_user()`` preceding the -``rcu_read_lock()``. +can be constructed with the call to get_user() preceding the +rcu_read_lock(). -Unfortunately, ``get_user()`` doesn't have any particular ordering properties, +Unfortunately, get_user() doesn't have any particular ordering properties, and in some architectures the underlying ``asm`` isn't even marked ``volatile``. And even if it was marked ``volatile``, the above access to ``p->value`` is not volatile, so the compiler would not have any reason to keep those two accesses in order. -Therefore, the Linux-kernel definitions of ``rcu_read_lock()`` and -``rcu_read_unlock()`` must act as compiler barriers, at least for outermost -instances of ``rcu_read_lock()`` and ``rcu_read_unlock()`` within a nested set +Therefore, the Linux-kernel definitions of rcu_read_lock() and +rcu_read_unlock() must act as compiler barriers, at least for outermost +instances of rcu_read_lock() and rcu_read_unlock() within a nested set of RCU read-side critical sections. Energy Efficiency @@ -2071,26 +2069,26 @@ call. Because RCU avoids interrupting idle CPUs, it is illegal to execute an RCU read-side critical section on an idle CPU. (Kernels built with -``CONFIG_PROVE_RCU=y`` will splat if you try it.) The ``RCU_NONIDLE()`` +``CONFIG_PROVE_RCU=y`` will splat if you try it.) The RCU_NONIDLE() macro and ``_rcuidle`` event tracing is provided to work around this -restriction. In addition, ``rcu_is_watching()`` may be used to test +restriction. In addition, rcu_is_watching() may be used to test whether or not it is currently legal to run RCU read-side critical sections on this CPU. I learned of the need for diagnostics on the one -hand and ``RCU_NONIDLE()`` on the other while inspecting idle-loop code. +hand and RCU_NONIDLE() on the other while inspecting idle-loop code. Steven Rostedt supplied ``_rcuidle`` event tracing, which is used quite heavily in the idle loop. However, there are some restrictions on the -code placed within ``RCU_NONIDLE()``: +code placed within RCU_NONIDLE(): #. Blocking is prohibited. In practice, this is not a serious restriction given that idle tasks are prohibited from blocking to begin with. -#. Although nesting ``RCU_NONIDLE()`` is permitted, they cannot nest +#. Although nesting RCU_NONIDLE() is permitted, they cannot nest indefinitely deeply. However, given that they can be nested on the order of a million deep, even on 32-bit systems, this should not be a serious restriction. This nesting limit would probably be reached long after the compiler OOMed or the stack overflowed. -#. Any code path that enters ``RCU_NONIDLE()`` must sequence out of that - same ``RCU_NONIDLE()``. For example, the following is grossly +#. Any code path that enters RCU_NONIDLE() must sequence out of that + same RCU_NONIDLE(). For example, the following is grossly illegal: :: @@ -2103,7 +2101,7 @@ code placed within ``RCU_NONIDLE()``: It is just as illegal to transfer control into the middle of - ``RCU_NONIDLE()``'s argument. Yes, in theory, you could transfer in + RCU_NONIDLE()'s argument. Yes, in theory, you could transfer in as long as you also transferred out, but in practice you could also expect to get sharply worded review comments. @@ -2195,9 +2193,9 @@ scheduling-clock interrupt be enabled when RCU needs it to be: sections, and RCU believes this CPU to be idle, no problem. This sort of thing is used by some architectures for light-weight exception handlers, which can then avoid the overhead of - ``rcu_irq_enter()`` and ``rcu_irq_exit()`` at exception entry and + rcu_irq_enter() and rcu_irq_exit() at exception entry and exit, respectively. Some go further and avoid the entireties of - ``irq_enter()`` and ``irq_exit()``. + irq_enter() and irq_exit(). Just make very sure you are running some of your tests with ``CONFIG_PROVE_RCU=y``, just in case one of your code paths was in fact joking about not doing RCU read-side critical sections. @@ -2221,7 +2219,7 @@ scheduling-clock interrupt be enabled when RCU needs it to be: | **Quick Quiz**: | +-----------------------------------------------------------------------+ | But what if my driver has a hardware interrupt handler that can run | -| for many seconds? I cannot invoke ``schedule()`` from an hardware | +| for many seconds? I cannot invoke schedule() from an hardware | | interrupt handler, after all! | +-----------------------------------------------------------------------+ | **Answer**: | @@ -2243,8 +2241,8 @@ Memory Efficiency Although small-memory non-realtime systems can simply use Tiny RCU, code size is only one aspect of memory efficiency. Another aspect is the size -of the ``rcu_head`` structure used by ``call_rcu()`` and -``kfree_rcu()``. Although this structure contains nothing more than a +of the ``rcu_head`` structure used by call_rcu() and +kfree_rcu(). Although this structure contains nothing more than a pair of pointers, it does appear in many RCU-protected data structures, including some that are size critical. The ``page`` structure is a case in point, as evidenced by the many occurrences of the ``union`` keyword @@ -2254,7 +2252,7 @@ This need for memory efficiency is one reason that RCU uses hand-crafted singly linked lists to track the ``rcu_head`` structures that are waiting for a grace period to elapse. It is also the reason why ``rcu_head`` structures do not contain debug information, such as fields -tracking the file and line of the ``call_rcu()`` or ``kfree_rcu()`` that +tracking the file and line of the call_rcu() or kfree_rcu() that posted them. Although this information might appear in debug-only kernel builds at some point, in the meantime, the ``->func`` field will often provide the needed debug information. @@ -2264,18 +2262,18 @@ more extreme measures. Returning to the ``page`` structure, the ``rcu_head`` field shares storage with a great many other structures that are used at various points in the corresponding page's lifetime. In order to correctly resolve certain `race -conditions <https://lkml.kernel.org/g/1439976106-137226-1-git-send-email-kirill.shutemov@linux.intel.com>`__, +conditions <https://lore.kernel.org/r/1439976106-137226-1-git-send-email-kirill.shutemov@linux.intel.com>`__, the Linux kernel's memory-management subsystem needs a particular bit to remain zero during all phases of grace-period processing, and that bit happens to map to the bottom bit of the ``rcu_head`` structure's -``->next`` field. RCU makes this guarantee as long as ``call_rcu()`` is -used to post the callback, as opposed to ``kfree_rcu()`` or some future -“lazy” variant of ``call_rcu()`` that might one day be created for +``->next`` field. RCU makes this guarantee as long as call_rcu() is +used to post the callback, as opposed to kfree_rcu() or some future +“lazy” variant of call_rcu() that might one day be created for energy-efficiency purposes. That said, there are limits. RCU requires that the ``rcu_head`` structure be aligned to a two-byte boundary, and passing a misaligned -``rcu_head`` structure to one of the ``call_rcu()`` family of functions +``rcu_head`` structure to one of the call_rcu() family of functions will result in a splat. It is therefore necessary to exercise caution when packing structures containing fields of type ``rcu_head``. Why not a four-byte or even eight-byte alignment requirement? Because the m68k @@ -2299,7 +2297,7 @@ hot code paths in performance-critical portions of the Linux kernel's networking, security, virtualization, and scheduling code paths. RCU must therefore use efficient implementations, especially in its read-side primitives. To that end, it would be good if preemptible RCU's -implementation of ``rcu_read_lock()`` could be inlined, however, doing +implementation of rcu_read_lock() could be inlined, however, doing this requires resolving ``#include`` issues with the ``task_struct`` structure. @@ -2312,23 +2310,23 @@ on the ``rcu_node`` structure. RCU is required to tolerate all CPUs continuously invoking any combination of RCU's runtime primitives with minimal per-operation overhead. In fact, in many cases, increasing load must *decrease* the per-operation overhead, witness the batching -optimizations for ``synchronize_rcu()``, ``call_rcu()``, -``synchronize_rcu_expedited()``, and ``rcu_barrier()``. As a general +optimizations for synchronize_rcu(), call_rcu(), +synchronize_rcu_expedited(), and rcu_barrier(). As a general rule, RCU must cheerfully accept whatever the rest of the Linux kernel decides to throw at it. The Linux kernel is used for real-time workloads, especially in conjunction with the `-rt -patchset <https://rt.wiki.kernel.org/index.php/Main_Page>`__. The +patchset <https://wiki.linuxfoundation.org/realtime/>`__. The real-time-latency response requirements are such that the traditional approach of disabling preemption across RCU read-side critical sections -is inappropriate. Kernels built with ``CONFIG_PREEMPT=y`` therefore use +is inappropriate. Kernels built with ``CONFIG_PREEMPTION=y`` therefore use an RCU implementation that allows RCU read-side critical sections to be preempted. This requirement made its presence known after users made it clear that an earlier `real-time patch <https://lwn.net/Articles/107930/>`__ did not meet their needs, in conjunction with some `RCU -issues <https://lkml.kernel.org/g/20050318002026.GA2693@us.ibm.com>`__ +issues <https://lore.kernel.org/r/20050318002026.GA2693@us.ibm.com>`__ encountered by a very early version of the -rt patchset. In addition, RCU must make do with a sub-100-microsecond real-time @@ -2346,7 +2344,7 @@ number of race conditions. RCU must avoid degrading real-time response for CPU-bound threads, whether executing in usermode (which is one use case for ``CONFIG_NO_HZ_FULL=y``) or in the kernel. That said, CPU-bound loops in -the kernel must execute ``cond_resched()`` at least once per few tens of +the kernel must execute cond_resched() at least once per few tens of milliseconds in order to avoid receiving an IPI from RCU. Finally, RCU's status as a synchronization primitive means that any RCU @@ -2412,7 +2410,7 @@ grace periods from ever ending. The result was an out-of-memory condition and a system hang. The solution was the creation of RCU-bh, which does -``local_bh_disable()`` across its read-side critical sections, and which +local_bh_disable() across its read-side critical sections, and which uses the transition from one type of softirq processing to another as a quiescent state in addition to context switch, idle, user mode, and offline. This means that RCU-bh grace periods can complete even when @@ -2420,31 +2418,31 @@ some of the CPUs execute in softirq indefinitely, thus allowing algorithms based on RCU-bh to withstand network-based denial-of-service attacks. -Because ``rcu_read_lock_bh()`` and ``rcu_read_unlock_bh()`` disable and +Because rcu_read_lock_bh() and rcu_read_unlock_bh() disable and re-enable softirq handlers, any attempt to start a softirq handlers during the RCU-bh read-side critical section will be deferred. In this -case, ``rcu_read_unlock_bh()`` will invoke softirq processing, which can +case, rcu_read_unlock_bh() will invoke softirq processing, which can take considerable time. One can of course argue that this softirq overhead should be associated with the code following the RCU-bh -read-side critical section rather than ``rcu_read_unlock_bh()``, but the +read-side critical section rather than rcu_read_unlock_bh(), but the fact is that most profiling tools cannot be expected to make this sort of fine distinction. For example, suppose that a three-millisecond-long RCU-bh read-side critical section executes during a time of heavy networking load. There will very likely be an attempt to invoke at least one softirq handler during that three milliseconds, but any such invocation will be delayed until the time of the -``rcu_read_unlock_bh()``. This can of course make it appear at first -glance as if ``rcu_read_unlock_bh()`` was executing very slowly. +rcu_read_unlock_bh(). This can of course make it appear at first +glance as if rcu_read_unlock_bh() was executing very slowly. The `RCU-bh API <https://lwn.net/Articles/609973/#RCU%20Per-Flavor%20API%20Table>`__ -includes ``rcu_read_lock_bh()``, ``rcu_read_unlock_bh()``, -``rcu_dereference_bh()``, ``rcu_dereference_bh_check()``, -``synchronize_rcu_bh()``, ``synchronize_rcu_bh_expedited()``, -``call_rcu_bh()``, ``rcu_barrier_bh()``, and -``rcu_read_lock_bh_held()``. However, the update-side APIs are now -simple wrappers for other RCU flavors, namely RCU-sched in -CONFIG_PREEMPT=n kernels and RCU-preempt otherwise. +includes rcu_read_lock_bh(), rcu_read_unlock_bh(), rcu_dereference_bh(), +rcu_dereference_bh_check(), and rcu_read_lock_bh_held(). However, the +old RCU-bh update-side APIs are now gone, replaced by synchronize_rcu(), +synchronize_rcu_expedited(), call_rcu(), and rcu_barrier(). In addition, +anything that disables bottom halves also marks an RCU-bh read-side +critical section, including local_bh_disable() and local_bh_enable(), +local_irq_save() and local_irq_restore(), and so on. Sched Flavor (Historical) ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2462,32 +2460,32 @@ not have this property, given that any point in the code outside of an RCU read-side critical section can be a quiescent state. Therefore, *RCU-sched* was created, which follows “classic” RCU in that an RCU-sched grace period waits for pre-existing interrupt and NMI -handlers. In kernels built with ``CONFIG_PREEMPT=n``, the RCU and +handlers. In kernels built with ``CONFIG_PREEMPTION=n``, the RCU and RCU-sched APIs have identical implementations, while kernels built with -``CONFIG_PREEMPT=y`` provide a separate implementation for each. +``CONFIG_PREEMPTION=y`` provide a separate implementation for each. -Note well that in ``CONFIG_PREEMPT=y`` kernels, -``rcu_read_lock_sched()`` and ``rcu_read_unlock_sched()`` disable and +Note well that in ``CONFIG_PREEMPTION=y`` kernels, +rcu_read_lock_sched() and rcu_read_unlock_sched() disable and re-enable preemption, respectively. This means that if there was a preemption attempt during the RCU-sched read-side critical section, -``rcu_read_unlock_sched()`` will enter the scheduler, with all the -latency and overhead entailed. Just as with ``rcu_read_unlock_bh()``, -this can make it look as if ``rcu_read_unlock_sched()`` was executing +rcu_read_unlock_sched() will enter the scheduler, with all the +latency and overhead entailed. Just as with rcu_read_unlock_bh(), +this can make it look as if rcu_read_unlock_sched() was executing very slowly. However, the highest-priority task won't be preempted, so -that task will enjoy low-overhead ``rcu_read_unlock_sched()`` +that task will enjoy low-overhead rcu_read_unlock_sched() invocations. The `RCU-sched API <https://lwn.net/Articles/609973/#RCU%20Per-Flavor%20API%20Table>`__ -includes ``rcu_read_lock_sched()``, ``rcu_read_unlock_sched()``, -``rcu_read_lock_sched_notrace()``, ``rcu_read_unlock_sched_notrace()``, -``rcu_dereference_sched()``, ``rcu_dereference_sched_check()``, -``synchronize_sched()``, ``synchronize_rcu_sched_expedited()``, -``call_rcu_sched()``, ``rcu_barrier_sched()``, and -``rcu_read_lock_sched_held()``. However, anything that disables -preemption also marks an RCU-sched read-side critical section, including -``preempt_disable()`` and ``preempt_enable()``, ``local_irq_save()`` and -``local_irq_restore()``, and so on. +includes rcu_read_lock_sched(), rcu_read_unlock_sched(), +rcu_read_lock_sched_notrace(), rcu_read_unlock_sched_notrace(), +rcu_dereference_sched(), rcu_dereference_sched_check(), and +rcu_read_lock_sched_held(). However, the old RCU-sched update-side APIs +are now gone, replaced by synchronize_rcu(), synchronize_rcu_expedited(), +call_rcu(), and rcu_barrier(). In addition, anything that disables +preemption also marks an RCU-sched read-side critical section, +including preempt_disable() and preempt_enable(), local_irq_save() +and local_irq_restore(), and so on. Sleepable RCU ~~~~~~~~~~~~~ @@ -2509,7 +2507,7 @@ this structure must be passed in to each SRCU function, for example, structure. The key benefit of these domains is that a slow SRCU reader in one domain does not delay an SRCU grace period in some other domain. That said, one consequence of these domains is that read-side code must -pass a “cookie” from ``srcu_read_lock()`` to ``srcu_read_unlock()``, for +pass a “cookie” from srcu_read_lock() to srcu_read_unlock(), for example, as follows: :: @@ -2539,24 +2537,24 @@ period to elapse. For example, this results in a self-deadlock: 6 srcu_read_unlock(&ss, idx); However, if line 5 acquired a mutex that was held across a -``synchronize_srcu()`` for domain ``ss``, deadlock would still be +synchronize_srcu() for domain ``ss``, deadlock would still be possible. Furthermore, if line 5 acquired a mutex that was held across a -``synchronize_srcu()`` for some other domain ``ss1``, and if an +synchronize_srcu() for some other domain ``ss1``, and if an ``ss1``-domain SRCU read-side critical section acquired another mutex -that was held across as ``ss``-domain ``synchronize_srcu()``, deadlock +that was held across as ``ss``-domain synchronize_srcu(), deadlock would again be possible. Such a deadlock cycle could extend across an arbitrarily large number of different SRCU domains. Again, with great power comes great responsibility. Unlike the other RCU flavors, SRCU read-side critical sections can run on idle and even offline CPUs. This ability requires that -``srcu_read_lock()`` and ``srcu_read_unlock()`` contain memory barriers, +srcu_read_lock() and srcu_read_unlock() contain memory barriers, which means that SRCU readers will run a bit slower than would RCU -readers. It also motivates the ``smp_mb__after_srcu_read_unlock()`` API, -which, in combination with ``srcu_read_unlock()``, guarantees a full +readers. It also motivates the smp_mb__after_srcu_read_unlock() API, +which, in combination with srcu_read_unlock(), guarantees a full memory barrier. -Also unlike other RCU flavors, ``synchronize_srcu()`` may **not** be +Also unlike other RCU flavors, synchronize_srcu() may **not** be invoked from CPU-hotplug notifiers, due to the fact that SRCU grace periods make use of timers and the possibility of timers being temporarily “stranded” on the outgoing CPU. This stranding of timers @@ -2565,7 +2563,7 @@ the CPU-hotplug process. The problem is that if a notifier is waiting on an SRCU grace period, that grace period is waiting on a timer, and that timer is stranded on the outgoing CPU, then the notifier will never be awakened, in other words, deadlock has occurred. This same situation of -course also prohibits ``srcu_barrier()`` from being invoked from +course also prohibits srcu_barrier() from being invoked from CPU-hotplug notifiers. SRCU also differs from other RCU flavors in that SRCU's expedited and @@ -2576,12 +2574,12 @@ have not yet completed. (But please note that this is a property of the current implementation, not necessarily of future implementations.) In addition, if SRCU has been idle for longer than the interval specified by the ``srcutree.exp_holdoff`` kernel boot parameter (25 microseconds -by default), and if a ``synchronize_srcu()`` invocation ends this idle +by default), and if a synchronize_srcu() invocation ends this idle period, that invocation will be automatically expedited. As of v4.12, SRCU's callbacks are maintained per-CPU, eliminating a locking bottleneck present in prior kernel versions. Although this will -allow users to put much heavier stress on ``call_srcu()``, it is +allow users to put much heavier stress on call_srcu(), it is important to note that SRCU does not yet take any special steps to deal with callback flooding. So if you are posting (say) 10,000 SRCU callbacks per second per CPU, you are probably totally OK, but if you @@ -2592,14 +2590,32 @@ of your CPUs and the size of your memory. The `SRCU API <https://lwn.net/Articles/609973/#RCU%20Per-Flavor%20API%20Table>`__ -includes ``srcu_read_lock()``, ``srcu_read_unlock()``, -``srcu_dereference()``, ``srcu_dereference_check()``, -``synchronize_srcu()``, ``synchronize_srcu_expedited()``, -``call_srcu()``, ``srcu_barrier()``, and ``srcu_read_lock_held()``. It -also includes ``DEFINE_SRCU()``, ``DEFINE_STATIC_SRCU()``, and -``init_srcu_struct()`` APIs for defining and initializing +includes srcu_read_lock(), srcu_read_unlock(), +srcu_dereference(), srcu_dereference_check(), +synchronize_srcu(), synchronize_srcu_expedited(), +call_srcu(), srcu_barrier(), and srcu_read_lock_held(). It +also includes DEFINE_SRCU(), DEFINE_STATIC_SRCU(), and +init_srcu_struct() APIs for defining and initializing ``srcu_struct`` structures. +More recently, the SRCU API has added polling interfaces: + +#. start_poll_synchronize_srcu() returns a cookie identifying + the completion of a future SRCU grace period and ensures + that this grace period will be started. +#. poll_state_synchronize_srcu() returns ``true`` iff the + specified cookie corresponds to an already-completed + SRCU grace period. +#. get_state_synchronize_srcu() returns a cookie just like + start_poll_synchronize_srcu() does, but differs in that + it does nothing to ensure that any future SRCU grace period + will be started. + +These functions are used to avoid unnecessary SRCU grace periods in +certain types of buffer-cache algorithms having multi-stage age-out +mechanisms. The idea is that by the time the block has aged completely +from the cache, an SRCU grace period will be very likely to have elapsed. + Tasks RCU ~~~~~~~~~ @@ -2608,11 +2624,11 @@ required to install different types of probes. It would be good to be able to free old trampolines, which sounds like a job for some form of RCU. However, because it is necessary to be able to install a trace anywhere in the code, it is not possible to use read-side markers such -as ``rcu_read_lock()`` and ``rcu_read_unlock()``. In addition, it does +as rcu_read_lock() and rcu_read_unlock(). In addition, it does not work to have these markers in the trampoline itself, because there -would need to be instructions following ``rcu_read_unlock()``. Although -``synchronize_rcu()`` would guarantee that execution reached the -``rcu_read_unlock()``, it would not be able to guarantee that execution +would need to be instructions following rcu_read_unlock(). Although +synchronize_rcu() would guarantee that execution reached the +rcu_read_unlock(), it would not be able to guarantee that execution had completely left the trampoline. Worse yet, in some situations the trampoline's protection must extend a few instructions *prior* to execution reaching the trampoline. For example, these few instructions @@ -2623,16 +2639,16 @@ actually reached the trampoline itself. The solution, in the form of `Tasks RCU <https://lwn.net/Articles/607117/>`__, is to have implicit read-side critical sections that are delimited by voluntary context switches, that -is, calls to ``schedule()``, ``cond_resched()``, and -``synchronize_rcu_tasks()``. In addition, transitions to and from +is, calls to schedule(), cond_resched(), and +synchronize_rcu_tasks(). In addition, transitions to and from userspace execution also delimit tasks-RCU read-side critical sections. The tasks-RCU API is quite compact, consisting only of -``call_rcu_tasks()``, ``synchronize_rcu_tasks()``, and -``rcu_barrier_tasks()``. In ``CONFIG_PREEMPT=n`` kernels, trampolines -cannot be preempted, so these APIs map to ``call_rcu()``, -``synchronize_rcu()``, and ``rcu_barrier()``, respectively. In -``CONFIG_PREEMPT=y`` kernels, trampolines can be preempted, and these +call_rcu_tasks(), synchronize_rcu_tasks(), and +rcu_barrier_tasks(). In ``CONFIG_PREEMPTION=n`` kernels, trampolines +cannot be preempted, so these APIs map to call_rcu(), +synchronize_rcu(), and rcu_barrier(), respectively. In +``CONFIG_PREEMPTION=y`` kernels, trampolines can be preempted, and these three APIs are therefore implemented by separate functions that check for voluntary context switches. @@ -2646,8 +2662,8 @@ grace-period state machine so as to avoid the need for the additional latency. RCU disables CPU hotplug in a few places, perhaps most notably in the -``rcu_barrier()`` operations. If there is a strong reason to use -``rcu_barrier()`` in CPU-hotplug notifiers, it will be necessary to +rcu_barrier() operations. If there is a strong reason to use +rcu_barrier() in CPU-hotplug notifiers, it will be necessary to avoid disabling CPU hotplug. This would introduce some complexity, so there had better be a *very* good reason. @@ -2664,7 +2680,7 @@ However, this combining tree does not spread its memory across NUMA nodes nor does it align the CPU groups with hardware features such as sockets or cores. Such spreading and alignment is currently believed to be unnecessary because the hotpath read-side primitives do not access -the combining tree, nor does ``call_rcu()`` in the common case. If you +the combining tree, nor does call_rcu() in the common case. If you believe that your architecture needs such spreading and alignment, then your architecture should also benefit from the ``rcutree.rcu_fanout_leaf`` boot parameter, which can be set to the @@ -2685,7 +2701,7 @@ likely that adjustments will be required to more gracefully handle extreme loads. It might also be necessary to be able to relate CPU utilization by RCU's kthreads and softirq handlers to the code that instigated this CPU utilization. For example, RCU callback overhead -might be charged back to the originating ``call_rcu()`` instance, though +might be charged back to the originating call_rcu() instance, though probably not in production kernels. Additional work may be required to provide reasonable forward-progress diff --git a/Documentation/RCU/NMI-RCU.rst b/Documentation/RCU/NMI-RCU.rst index 180958388ff9..2a92bc685ef1 100644 --- a/Documentation/RCU/NMI-RCU.rst +++ b/Documentation/RCU/NMI-RCU.rst @@ -8,8 +8,7 @@ Although RCU is usually used to protect read-mostly data structures, it is possible to use RCU to provide dynamic non-maskable interrupt handlers, as well as dynamic irq handlers. This document describes how to do this, drawing loosely from Zwane Mwaikambo's NMI-timer -work in "arch/x86/oprofile/nmi_timer_int.c" and in -"arch/x86/kernel/traps.c". +work in "arch/x86/kernel/traps.c". The relevant pieces of code are listed below, each followed by a brief explanation:: diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst index bb7128eb322e..1030119294d0 100644 --- a/Documentation/RCU/checklist.rst +++ b/Documentation/RCU/checklist.rst @@ -70,7 +70,7 @@ over a rather long period of time, but improvements are always welcome! is less readable and prevents lockdep from detecting locking issues. Letting RCU-protected pointers "leak" out of an RCU read-side - critical section is every bid as bad as letting them leak out + critical section is every bit as bad as letting them leak out from under a lock. Unless, of course, you have arranged some other means of protection, such as a lock or a reference count -before- letting them out of the RCU read-side critical section. @@ -129,9 +129,7 @@ over a rather long period of time, but improvements are always welcome! accesses. The rcu_dereference() primitive ensures that the CPU picks up the pointer before it picks up the data that the pointer points to. This really is necessary - on Alpha CPUs. If you don't believe me, see: - - http://www.openvms.compaq.com/wizard/wiz_2637.html + on Alpha CPUs. The rcu_dereference() primitive is also an excellent documentation aid, letting the person reading the @@ -214,9 +212,9 @@ over a rather long period of time, but improvements are always welcome! the rest of the system. 7. As of v4.20, a given kernel implements only one RCU flavor, - which is RCU-sched for PREEMPT=n and RCU-preempt for PREEMPT=y. + which is RCU-sched for PREEMPTION=n and RCU-preempt for PREEMPTION=y. If the updater uses call_rcu() or synchronize_rcu(), - then the corresponding readers my use rcu_read_lock() and + then the corresponding readers may use rcu_read_lock() and rcu_read_unlock(), rcu_read_lock_bh() and rcu_read_unlock_bh(), or any pair of primitives that disables and re-enables preemption, for example, rcu_read_lock_sched() and rcu_read_unlock_sched(). diff --git a/Documentation/RCU/rcubarrier.rst b/Documentation/RCU/rcubarrier.rst index f64f4413a47c..3b4a24877496 100644 --- a/Documentation/RCU/rcubarrier.rst +++ b/Documentation/RCU/rcubarrier.rst @@ -9,7 +9,7 @@ RCU (read-copy update) is a synchronization mechanism that can be thought of as a replacement for read-writer locking (among other things), but with very low-overhead readers that are immune to deadlock, priority inversion, and unbounded latency. RCU read-side critical sections are delimited -by rcu_read_lock() and rcu_read_unlock(), which, in non-CONFIG_PREEMPT +by rcu_read_lock() and rcu_read_unlock(), which, in non-CONFIG_PREEMPTION kernels, generate no code whatsoever. This means that RCU writers are unaware of the presence of concurrent @@ -329,10 +329,10 @@ Answer: This cannot happen. The reason is that on_each_cpu() has its last to smp_call_function() and further to smp_call_function_on_cpu(), causing this latter to spin until the cross-CPU invocation of rcu_barrier_func() has completed. This by itself would prevent - a grace period from completing on non-CONFIG_PREEMPT kernels, + a grace period from completing on non-CONFIG_PREEMPTION kernels, since each CPU must undergo a context switch (or other quiescent state) before the grace period can complete. However, this is - of no use in CONFIG_PREEMPT kernels. + of no use in CONFIG_PREEMPTION kernels. Therefore, on_each_cpu() disables preemption across its call to smp_call_function() and also across the local call to diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst index c9ab6af4d3be..7148e9be08c3 100644 --- a/Documentation/RCU/stallwarn.rst +++ b/Documentation/RCU/stallwarn.rst @@ -25,7 +25,7 @@ warnings: - A CPU looping with bottom halves disabled. -- For !CONFIG_PREEMPT kernels, a CPU looping anywhere in the kernel +- For !CONFIG_PREEMPTION kernels, a CPU looping anywhere in the kernel without invoking schedule(). If the looping in the kernel is really expected and desirable behavior, you might need to add some calls to cond_resched(). @@ -44,7 +44,7 @@ warnings: result in the ``rcu_.*kthread starved for`` console-log message, which will include additional debugging information. -- A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might +- A CPU-bound real-time task in a CONFIG_PREEMPTION kernel, which might happen to preempt a low-priority task in the middle of an RCU read-side critical section. This is especially damaging if that low-priority task is not permitted to run on any other CPU, @@ -92,7 +92,9 @@ warnings: buggy timer hardware through bugs in the interrupt or exception path (whether hardware, firmware, or software) through bugs in Linux's timer subsystem through bugs in the scheduler, and, - yes, even including bugs in RCU itself. + yes, even including bugs in RCU itself. It can also result in + the ``rcu_.*timer wakeup didn't happen for`` console-log message, + which will include additional debugging information. - A bug in the RCU implementation. @@ -292,6 +294,25 @@ kthread is waiting for a short timeout, the "state" precedes value of the task_struct ->state field, and the "cpu" indicates that the grace-period kthread last ran on CPU 5. +If the relevant grace-period kthread does not wake from FQS wait in a +reasonable time, then the following additional line is printed:: + + kthread timer wakeup didn't happen for 23804 jiffies! g7076 f0x0 RCU_GP_WAIT_FQS(5) ->state=0x402 + +The "23804" indicates that kthread's timer expired more than 23 thousand +jiffies ago. The rest of the line has meaning similar to the kthread +starvation case. + +Additionally, the following line is printed:: + + Possible timer handling issue on cpu=4 timer-softirq=11142 + +Here "cpu" indicates that the grace-period kthread last ran on CPU 4, +where it queued the fqs timer. The number following the "timer-softirq" +is the current ``TIMER_SOFTIRQ`` count on cpu 4. If this value does not +change on successive RCU CPU stall warnings, there is further reason to +suspect a timer problem. + Multiple Warnings From One Stall ================================ diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst index 1a4723f48bd9..17e95ab2a201 100644 --- a/Documentation/RCU/whatisRCU.rst +++ b/Documentation/RCU/whatisRCU.rst @@ -683,7 +683,7 @@ Quick Quiz #1: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This section presents a "toy" RCU implementation that is based on "classic RCU". It is also short on performance (but only for updates) and -on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT +on features such as hotplug CPU and the ability to run in CONFIG_PREEMPTION kernels. The definitions of rcu_dereference() and rcu_assign_pointer() are the same as those shown in the preceding section, so they are omitted. :: @@ -739,7 +739,7 @@ Quick Quiz #2: Quick Quiz #3: If it is illegal to block in an RCU read-side critical section, what the heck do you do in - PREEMPT_RT, where normal spinlocks can block??? + CONFIG_PREEMPT_RT, where normal spinlocks can block??? :ref:`Answers to Quick Quiz <8_whatisRCU>` @@ -1093,7 +1093,7 @@ Quick Quiz #2: overhead is **negative**. Answer: - Imagine a single-CPU system with a non-CONFIG_PREEMPT + Imagine a single-CPU system with a non-CONFIG_PREEMPTION kernel where a routing table is used by process-context code, but can be updated by irq-context code (for example, by an "ICMP REDIRECT" packet). The usual way of handling @@ -1120,10 +1120,10 @@ Answer: Quick Quiz #3: If it is illegal to block in an RCU read-side critical section, what the heck do you do in - PREEMPT_RT, where normal spinlocks can block??? + CONFIG_PREEMPT_RT, where normal spinlocks can block??? Answer: - Just as PREEMPT_RT permits preemption of spinlock + Just as CONFIG_PREEMPT_RT permits preemption of spinlock critical sections, it permits preemption of RCU read-side critical sections. It also permits spinlocks blocking while in RCU read-side critical diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 63521cd36ce5..1de8695c264b 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -1029,7 +1029,7 @@ All time durations are in microseconds. one number is written, $MAX is updated. cpu.pressure - A read-only nested-key file which exists on non-root cgroups. + A read-write nested-keyed file. Shows pressure stall information for CPU. See :ref:`Documentation/accounting/psi.rst <psi>` for details. @@ -1475,7 +1475,7 @@ PAGE_SIZE multiple when read back. reduces the impact on the workload and memory management. memory.pressure - A read-only nested-key file which exists on non-root cgroups. + A read-only nested-keyed file. Shows pressure stall information for memory. See :ref:`Documentation/accounting/psi.rst <psi>` for details. @@ -1714,7 +1714,7 @@ IO Interface Files 8:16 rbps=2097152 wbps=max riops=max wiops=max io.pressure - A read-only nested-key file which exists on non-root cgroups. + A read-only nested-keyed file. Shows pressure stall information for IO. See :ref:`Documentation/accounting/psi.rst <psi>` for details. diff --git a/Documentation/admin-guide/device-mapper/dm-integrity.rst b/Documentation/admin-guide/device-mapper/dm-integrity.rst index 2cc5488acbd9..cd198ccf4292 100644 --- a/Documentation/admin-guide/device-mapper/dm-integrity.rst +++ b/Documentation/admin-guide/device-mapper/dm-integrity.rst @@ -143,8 +143,8 @@ recalculate journal_crypt:algorithm(:key) (the key is optional) Encrypt the journal using given algorithm to make sure that the attacker can't read the journal. You can use a block cipher here - (such as "cbc(aes)") or a stream cipher (for example "chacha20", - "salsa20" or "ctr(aes)"). + (such as "cbc(aes)") or a stream cipher (for example "chacha20" + or "ctr(aes)"). The journal contains history of last writes to the block device, an attacker reading the journal could see the last sector numbers diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index a10b545c2070..4fc20f9af2fb 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -373,6 +373,12 @@ arcrimi= [HW,NET] ARCnet - "RIM I" (entirely mem-mapped) cards Format: <io>,<irq>,<nodeID> + arm64.nobti [ARM64] Unconditionally disable Branch Target + Identification support + + arm64.nopauth [ARM64] Unconditionally disable Pointer Authentication + support + ataflop= [HW,M68k] atarimouse= [HW,MOUSE] Atari Mouse @@ -802,13 +808,14 @@ insecure, please do not use on production kernels. debug_locks_verbose= - [KNL] verbose self-tests - Format=<0|1> + [KNL] verbose locking self-tests + Format: <int> Print debugging info while doing the locking API self-tests. - We default to 0 (no extra messages), setting it to - 1 will print _a lot_ more information - normally - only useful to kernel developers. + Bitmask for the various LOCKTYPE_ tests. Defaults to 0 + (no extra messages), setting it to -1 (all bits set) + will print _a_lot_ more information - normally only + useful to lockdep developers. debug_objects [KNL] Enable object debugging @@ -944,12 +951,6 @@ causing system reset or hang due to sending INIT from AP to BSP. - perf_v4_pmi= [X86,INTEL] - Format: <bool> - Disable Intel PMU counter freezing feature. - The feature only exists starting from - Arch Perfmon v4 (Skylake and newer). - disable_ddw [PPC/PSERIES] Disable Dynamic DMA Window support. Use this to workaround buggy firmware. @@ -1746,7 +1747,7 @@ ima_policy= [IMA] The builtin policies to load during IMA setup. Format: "tcb | appraise_tcb | secure_boot | - fail_securely" + fail_securely | critical_data" The "tcb" policy measures all programs exec'd, files mmap'd for exec, and all files opened with the read @@ -1765,6 +1766,9 @@ filesystems with the SB_I_UNVERIFIABLE_SIGNATURE flag. + The "critical_data" policy measures kernel integrity + critical data. + ima_tcb [IMA] Deprecated. Use ima_policy= instead. Load a policy which meets the needs of the Trusted Computing Base. This means IMA will measure all @@ -2257,6 +2261,9 @@ kvm-arm.mode= [KVM,ARM] Select one of KVM/arm64's modes of operation. + nvhe: Standard nVHE-based mode, without support for + protected guests. + protected: nVHE-based mode with support for guests whose state is kept private from the host. Not valid if the kernel is running in EL2. @@ -3458,20 +3465,6 @@ For example, to override I2C bus2: omap_mux=i2c2_scl.i2c2_scl=0x100,i2c2_sda.i2c2_sda=0x100 - oprofile.timer= [HW] - Use timer interrupt instead of performance counters - - oprofile.cpu_type= Force an oprofile cpu type - This might be useful if you have an older oprofile - userland or if you want common events. - Format: { arch_perfmon } - arch_perfmon: [X86] Force use of architectural - perfmon on Intel CPUs instead of the - CPU specific event set. - timer: [X86] Force use of architectural NMI - timer mode (see also oprofile.timer - for generic hr timer mode) - oops=panic Always panic on oopses. Default is to just kill the process, but there is a small probability of deadlocking the machine. @@ -3916,6 +3909,13 @@ Format: {"off"} Disable Hardware Transactional Memory + preempt= [KNL] + Select preemption mode if you have CONFIG_PREEMPT_DYNAMIC + none - Limited to cond_resched() calls + voluntary - Limited to cond_resched() and might_sleep() calls + full - Any section that isn't explicitly preempt disabled + can be preempted anytime. + print-fatal-signals= [KNL] debug: print fatal signals @@ -4092,6 +4092,10 @@ value, meaning that RCU_SOFTIRQ is used by default. Specify rcutree.use_softirq=0 to use rcuc kthreads. + But note that CONFIG_PREEMPT_RT=y kernels disable + this kernel boot parameter, forcibly setting it + to zero. + rcutree.rcu_fanout_exact= [KNL] Disable autobalancing of the rcu_node combining tree. This is used by rcutorture, and might @@ -4179,12 +4183,6 @@ Set wakeup interval for idle CPUs that have RCU callbacks (RCU_FAST_NO_HZ=y). - rcutree.rcu_idle_lazy_gp_delay= [KNL] - Set wakeup interval for idle CPUs that have - only "lazy" RCU callbacks (RCU_FAST_NO_HZ=y). - Lazy RCU callbacks are those which RCU can - prove do nothing more than free memory. - rcutree.rcu_kick_kthreads= [KNL] Cause the grace-period kthread to get an extra wake_up() if it sleeps three times longer than @@ -4338,6 +4336,14 @@ stress RCU, they don't participate in the actual test, hence the "fake". + rcutorture.nocbs_nthreads= [KNL] + Set number of RCU callback-offload togglers. + Zero (the default) disables toggling. + + rcutorture.nocbs_toggle= [KNL] + Set the delay in milliseconds between successive + callback-offload toggling attempts. + rcutorture.nreaders= [KNL] Set number of RCU readers. The value -1 selects N-1, where N is the number of CPUs. A value @@ -4470,6 +4476,13 @@ only normal grace-period primitives. No effect on CONFIG_TINY_RCU kernels. + But note that CONFIG_PREEMPT_RT=y kernels enables + this kernel boot parameter, forcibly setting + it to the value one, that is, converting any + post-boot attempt at an expedited RCU grace + period to instead use normal non-expedited + grace-period processing. + rcupdate.rcu_task_ipi_delay= [KNL] Set time in jiffies during which RCU tasks will avoid sending IPIs, starting with the beginning @@ -4557,6 +4570,12 @@ refscale.verbose= [KNL] Enable additional printk() statements. + refscale.verbose_batched= [KNL] + Batch the additional printk() statements. If zero + (the default) or negative, print everything. Otherwise, + print every Nth verbose statement, where N is the value + specified. + relax_domain_level= [KNL, SMP] Set scheduler's default relax_domain_level. See Documentation/admin-guide/cgroup-v1/cpusets.rst. @@ -5331,6 +5350,14 @@ are running concurrently, especially on systems with rotating-rust storage. + torture.verbose_sleep_frequency= [KNL] + Specifies how many verbose printk()s should be + emitted between each sleep. The default of zero + disables verbose-printk() sleeping. + + torture.verbose_sleep_duration= [KNL] + Duration of each verbose-printk() sleep in jiffies. + tp720= [HW,PS2] tpm_suspend_pcr=[HW,TPM] diff --git a/Documentation/admin-guide/laptops/thinkpad-acpi.rst b/Documentation/admin-guide/laptops/thinkpad-acpi.rst index 5fe1ade88c17..91fd6846ce17 100644 --- a/Documentation/admin-guide/laptops/thinkpad-acpi.rst +++ b/Documentation/admin-guide/laptops/thinkpad-acpi.rst @@ -51,6 +51,7 @@ detailed description): - UWB enable and disable - LCD Shadow (PrivacyGuard) enable and disable - Lap mode sensor + - Setting keyboard language A compatibility table by model and feature is maintained on the web site, http://ibm-acpi.sf.net/. I appreciate any success or failure @@ -1466,6 +1467,30 @@ Sysfs notes rfkill controller switch "tpacpi_uwb_sw": refer to Documentation/driver-api/rfkill.rst for details. + +Setting keyboard language +------------------------- + +sysfs: keyboard_lang + +This feature is used to set keyboard language to ECFW using ASL interface. +Fewer thinkpads models like T580 , T590 , T15 Gen 1 etc.. has "=", "(', +")" numeric keys, which are not displaying correctly, when keyboard language +is other than "english". This is because the default keyboard language in ECFW +is set as "english". Hence using this sysfs, user can set the correct keyboard +language to ECFW and then these key's will work correctly. + +Example of command to set keyboard language is mentioned below:: + + echo jp > /sys/devices/platform/thinkpad_acpi/keyboard_lang + +Text corresponding to keyboard layout to be set in sysfs are: be(Belgian), +cz(Czech), da(Danish), de(German), en(English), es(Spain), et(Estonian), +fr(French), fr-ch(French(Switzerland)), hu(Hungarian), it(Italy), jp (Japan), +nl(Dutch), nn(Norway), pl(Polish), pt(portugese), sl(Slovenian), sv(Sweden), +tr(Turkey) + + Adaptive keyboard ----------------- diff --git a/Documentation/admin-guide/perf/arm-cmn.rst b/Documentation/admin-guide/perf/arm-cmn.rst index 0e4809346014..796e25b7027b 100644 --- a/Documentation/admin-guide/perf/arm-cmn.rst +++ b/Documentation/admin-guide/perf/arm-cmn.rst @@ -17,7 +17,7 @@ PMU events ---------- The PMU driver registers a single PMU device for the whole interconnect, -see /sys/bus/event_source/devices/arm_cmn. Multi-chip systems may link +see /sys/bus/event_source/devices/arm_cmn_0. Multi-chip systems may link more than one CMN together via external CCIX links - in this situation, each mesh counts its own events entirely independently, and additional PMU devices will be named arm_cmn_{1..n}. diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst index 613cb24c76c7..f18e881373c4 100644 --- a/Documentation/admin-guide/thunderbolt.rst +++ b/Documentation/admin-guide/thunderbolt.rst @@ -47,6 +47,9 @@ be DMA masters and thus read contents of the host memory without CPU and OS knowing about it. There are ways to prevent this by setting up an IOMMU but it is not always available for various reasons. +Some USB4 systems have a BIOS setting to disable PCIe tunneling. This is +treated as another security level (nopcie). + The security levels are as follows: none @@ -77,6 +80,10 @@ The security levels are as follows: Display Port in a dock. All PCIe links downstream of the dock are removed. + nopcie + PCIe tunneling is disabled/forbidden from the BIOS. Available in some + USB4 systems. + The current security level can be read from ``/sys/bus/thunderbolt/devices/domainX/security`` where ``domainX`` is the Thunderbolt domain the host controller manages. There is typically @@ -153,6 +160,22 @@ If the user still wants to connect the device they can either approve the device without a key or write a new key and write 1 to the ``authorized`` file to get the new key stored on the device NVM. +De-authorizing devices +---------------------- +It is possible to de-authorize devices by writing ``0`` to their +``authorized`` attribute. This requires support from the connection +manager implementation and can be checked by reading domain +``deauthorization`` attribute. If it reads ``1`` then the feature is +supported. + +When a device is de-authorized the PCIe tunnel from the parent device +PCIe downstream (or root) port to the device PCIe upstream port is torn +down. This is essentially the same thing as PCIe hot-remove and the PCIe +toplogy in question will not be accessible anymore until the device is +authorized again. If there is storage such as NVMe or similar involved, +there is a risk for data loss if the filesystem on that storage is not +properly shut down. You have been warned! + DMA protection utilizing IOMMU ------------------------------ Recent systems from 2018 and forward with Thunderbolt ports may natively diff --git a/Documentation/admin-guide/xfs.rst b/Documentation/admin-guide/xfs.rst index 86de8a1ad91c..6178153d3320 100644 --- a/Documentation/admin-guide/xfs.rst +++ b/Documentation/admin-guide/xfs.rst @@ -495,3 +495,45 @@ the class and error context. For example, the default values for "metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults to "fail immediately" behaviour. This is done because ENODEV is a fatal, unrecoverable error no matter how many times the metadata IO is retried. + +Workqueue Concurrency +===================== + +XFS uses kernel workqueues to parallelize metadata update processes. This +enables it to take advantage of storage hardware that can service many IO +operations simultaneously. This interface exposes internal implementation +details of XFS, and as such is explicitly not part of any userspace API/ABI +guarantee the kernel may give userspace. These are undocumented features of +the generic workqueue implementation XFS uses for concurrency, and they are +provided here purely for diagnostic and tuning purposes and may change at any +time in the future. + +The control knobs for a filesystem's workqueues are organized by task at hand +and the short name of the data device. They all can be found in: + + /sys/bus/workqueue/devices/${task}!${device} + +================ =========== + Task Description +================ =========== + xfs_iwalk-$pid Inode scans of the entire filesystem. Currently limited to + mount time quotacheck. + xfs-blockgc Background garbage collection of disk space that have been + speculatively allocated beyond EOF or for staging copy on + write operations. +================ =========== + +For example, the knobs for the quotacheck workqueue for /dev/nvme0n1 would be +found in /sys/bus/workqueue/devices/xfs_iwalk-1111!nvme0n1/. + +The interesting knobs for XFS workqueues are as follows: + +============ =========== + Knob Description +============ =========== + max_active Maximum number of background threads that can be started to + run the work. + cpumask CPUs upon which the threads are allowed to run. + nice Relative priority of scheduling the threads. These are the + same nice levels that can be applied to userspace processes. +============ =========== diff --git a/Documentation/block/biovecs.rst b/Documentation/block/biovecs.rst index 36771a131b56..ddb867e0185b 100644 --- a/Documentation/block/biovecs.rst +++ b/Documentation/block/biovecs.rst @@ -40,6 +40,8 @@ normal code doesn't have to deal with bi_bvec_done. There is a lower level advance function - bvec_iter_advance() - which takes a pointer to a biovec, not a bio; this is used by the bio integrity code. +As of 5.12 bvec segments with zero bv_len are not supported. + What's all this get us? ======================= diff --git a/Documentation/block/inline-encryption.rst b/Documentation/block/inline-encryption.rst index e75151e467d3..7f9b40d6b416 100644 --- a/Documentation/block/inline-encryption.rst +++ b/Documentation/block/inline-encryption.rst @@ -182,8 +182,9 @@ API presented to device drivers A :c:type:``struct blk_keyslot_manager`` should be set up by device drivers in the ``request_queue`` of the device. The device driver needs to call -``blk_ksm_init`` on the ``blk_keyslot_manager``, which specifying the number of -keyslots supported by the hardware. +``blk_ksm_init`` (or its resource-managed variant ``devm_blk_ksm_init``) on the +``blk_keyslot_manager``, while specifying the number of keyslots supported by +the hardware. The device driver also needs to tell the KSM how to actually manipulate the IE hardware in the device to do things like programming the crypto key into @@ -202,10 +203,9 @@ needs each and every of its keyslots to be reprogrammed with the key it "should have" at the point in time when the function is called. This is useful e.g. if a device loses all its keys on runtime power down/up. -``blk_ksm_destroy`` should be called to free up all resources used by a keyslot -manager upon ``blk_ksm_init``, once the ``blk_keyslot_manager`` is no longer -needed. - +If the driver used ``blk_ksm_init`` instead of ``devm_blk_ksm_init``, then +``blk_ksm_destroy`` should be called to free up all resources used by a +``blk_keyslot_manager`` once it is no longer needed. Layered Devices =============== diff --git a/Documentation/block/queue-sysfs.rst b/Documentation/block/queue-sysfs.rst index 2638d3446b79..4dc7f0d499a8 100644 --- a/Documentation/block/queue-sysfs.rst +++ b/Documentation/block/queue-sysfs.rst @@ -261,6 +261,12 @@ For block drivers that support REQ_OP_WRITE_ZEROES, the maximum number of bytes that can be zeroed at once. The value 0 means that REQ_OP_WRITE_ZEROES is not supported. +zone_append_max_bytes (RO) +-------------------------- +This is the maximum number of bytes that can be written to a sequential +zone of a zoned block device using a zone append write operation +(REQ_OP_ZONE_APPEND). This value is always 0 for regular block devices. + zoned (RO) ---------- This indicates if the device is a zoned block device and the zone model of the @@ -273,4 +279,11 @@ devices are described in the ZBC (Zoned Block Commands) and ZAC do not support zone commands, they will be treated as regular block devices and zoned will report "none". +zone_write_granularity (RO) +--------------------------- +This indicates the alignment constraint, in bytes, for write operations in +sequential zones of zoned block devices (devices with a zoned attributed +that reports "host-managed" or "host-aware"). This value is always 0 for +regular block devices. + Jens Axboe <jens.axboe@oracle.com>, February 2009 diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst index 2df7b067ab93..0e15f9b05c9d 100644 --- a/Documentation/bpf/bpf_design_QA.rst +++ b/Documentation/bpf/bpf_design_QA.rst @@ -208,6 +208,12 @@ data structures and compile with kernel internal headers. Both of these kernel internals are subject to change and can break with newer kernels such that the program needs to be adapted accordingly. +Q: Are tracepoints part of the stable ABI? +------------------------------------------ +A: NO. Tracepoints are tied to internal implementation details hence they are +subject to change and can break with newer kernels. BPF programs need to change +accordingly when this happens. + Q: How much stack space a BPF program uses? ------------------------------------------- A: Currently all program types are limited to 512 bytes of stack diff --git a/Documentation/bpf/bpf_devel_QA.rst b/Documentation/bpf/bpf_devel_QA.rst index 5b613d2a5f1a..2ed89abbf9a4 100644 --- a/Documentation/bpf/bpf_devel_QA.rst +++ b/Documentation/bpf/bpf_devel_QA.rst @@ -501,16 +501,19 @@ All LLVM releases can be found at: http://releases.llvm.org/ Q: Got it, so how do I build LLVM manually anyway? -------------------------------------------------- -A: You need cmake and gcc-c++ as build requisites for LLVM. Once you have -that set up, proceed with building the latest LLVM and clang version +A: We recommend that developers who want the fastest incremental builds +use the Ninja build system, you can find it in your system's package +manager, usually the package is ninja or ninja-build. + +You need ninja, cmake and gcc-c++ as build requisites for LLVM. Once you +have that set up, proceed with building the latest LLVM and clang version from the git repositories:: $ git clone https://github.com/llvm/llvm-project.git - $ mkdir -p llvm-project/llvm/build/install + $ mkdir -p llvm-project/llvm/build $ cd llvm-project/llvm/build $ cmake .. -G "Ninja" -DLLVM_TARGETS_TO_BUILD="BPF;X86" \ -DLLVM_ENABLE_PROJECTS="clang" \ - -DBUILD_SHARED_LIBS=OFF \ -DCMAKE_BUILD_TYPE=Release \ -DLLVM_BUILD_RUNTIME=OFF $ ninja diff --git a/Documentation/crypto/api-skcipher.rst b/Documentation/crypto/api-skcipher.rst index 1aaf8985894b..04d6cc5357c8 100644 --- a/Documentation/crypto/api-skcipher.rst +++ b/Documentation/crypto/api-skcipher.rst @@ -28,8 +28,8 @@ Symmetric Key Cipher Request Handle Single Block Cipher API ----------------------- -.. kernel-doc:: include/linux/crypto.h +.. kernel-doc:: include/crypto/internal/cipher.h :doc: Single Block Cipher API -.. kernel-doc:: include/linux/crypto.h +.. kernel-doc:: include/crypto/internal/cipher.h :functions: crypto_alloc_cipher crypto_free_cipher crypto_has_cipher crypto_cipher_blocksize crypto_cipher_setkey crypto_cipher_encrypt_one crypto_cipher_decrypt_one diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index 1651d961f06a..a248ac3941be 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -163,8 +163,7 @@ particular KASAN features. - ``kasan=off`` or ``=on`` controls whether KASAN is enabled (default: ``on``). - ``kasan.stacktrace=off`` or ``=on`` disables or enables alloc and free stack - traces collection (default: ``on`` for ``CONFIG_DEBUG_KERNEL=y``, otherwise - ``off``). + traces collection (default: ``on``). - ``kasan.fault=report`` or ``=panic`` controls whether to only print a KASAN report or also panic the kernel (default: ``report``). diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml index 3341788d1096..5f6769bf45bd 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -151,6 +151,7 @@ properties: - description: Boards with the Amlogic Meson G12B S922X SoC items: - enum: + - azw,gsking-x - azw,gtking - azw,gtking-pro - hardkernel,odroid-n2 @@ -163,9 +164,10 @@ properties: - description: Boards with the Amlogic Meson SM1 S905X3/D3/Y3 SoC items: - enum: - - seirobotics,sei610 - - khadas,vim3l - hardkernel,odroid-c4 + - hardkernel,odroid-hc4 + - khadas,vim3l + - seirobotics,sei610 - const: amlogic,sm1 - description: Boards with the Amlogic Meson A1 A113L SoC diff --git a/Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-mx-secbus2.yaml b/Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-mx-secbus2.yaml new file mode 100644 index 000000000000..eee7cda9f91b --- /dev/null +++ b/Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-mx-secbus2.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/arm/amlogic/amlogic,meson-mx-secbus2.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Amlogic Meson8/Meson8b/Meson8m2 SECBUS2 register interface + +maintainers: + - Martin Blumenstingl <martin.blumenstingl@googlemail.com> + +description: | + The Meson8/Meson8b/Meson8m2 SoCs have a register bank called SECBUS2 which + contains registers for various IP blocks such as pin-controller bits for + the BSD_EN and TEST_N GPIOs as well as some AO ARC core control bits. + The registers can be accessed directly when not running in "secure mode". + When "secure mode" is enabled then these registers have to be accessed + through secure monitor calls. + +properties: + compatible: + items: + - enum: + - amlogic,meson8-secbus2 + - amlogic,meson8b-secbus2 + - const: syscon + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + secbus2: system-controller@4000 { + compatible = "amlogic,meson8-secbus2", "syscon"; + reg = <0x4000 0x2000>; + }; diff --git a/Documentation/devicetree/bindings/arm/arm,scmi.txt b/Documentation/devicetree/bindings/arm/arm,scmi.txt index b5ce5b39bb9c..667d58e0a659 100644 --- a/Documentation/devicetree/bindings/arm/arm,scmi.txt +++ b/Documentation/devicetree/bindings/arm/arm,scmi.txt @@ -31,6 +31,14 @@ Optional properties: - mbox-names: shall be "tx" or "rx" depending on mboxes entries. +- interrupts : when using smc or hvc transports, this optional + property indicates that msg completion by the platform is indicated + by an interrupt rather than by the return of the smc call. This + should not be used except when the platform requires such behavior. + +- interrupt-names : if "interrupts" is present, interrupt-names must also + be present and have the value "a2p". + See Documentation/devicetree/bindings/mailbox/mailbox.txt for more details about the generic mailbox controller and client driver bindings. diff --git a/Documentation/devicetree/bindings/arm/atmel-sysregs.txt b/Documentation/devicetree/bindings/arm/atmel-sysregs.txt index 62cd4e89817c..67719f15eb4c 100644 --- a/Documentation/devicetree/bindings/arm/atmel-sysregs.txt +++ b/Documentation/devicetree/bindings/arm/atmel-sysregs.txt @@ -1,7 +1,7 @@ Atmel system registers Chipid required properties: -- compatible: Should be "atmel,sama5d2-chipid" +- compatible: Should be "atmel,sama5d2-chipid" or "microchip,sama7g5-chipid" - reg : Should contain registers location and length PIT Timer required properties: diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4908.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4908.yaml index 5fec063d9a13..e55731f43c84 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4908.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4908.yaml @@ -19,6 +19,8 @@ properties: oneOf: - description: BCM4906 based boards items: + - enum: + - netgear,r8000p - const: brcm,bcm4906 - const: brcm,bcm4908 diff --git a/Documentation/devicetree/bindings/arm/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml index f02fd10de604..26b886b20b27 100644 --- a/Documentation/devicetree/bindings/arm/cpus.yaml +++ b/Documentation/devicetree/bindings/arm/cpus.yaml @@ -169,6 +169,7 @@ properties: - qcom,kryo385 - qcom,kryo468 - qcom,kryo485 + - qcom,kryo685 - qcom,scorpion enable-method: diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index 34000f7fbe02..297c87f45db8 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -210,6 +210,7 @@ properties: - kiebackpeter,imx6q-tpc # K+P i.MX6 Quad TPC Board - kontron,imx6q-samx6i # Kontron i.MX6 Dual/Quad SMARC Module - kosagi,imx6q-novena # Kosagi Novena Dual/Quad + - kvg,vicut1q # Kverneland UT1Q board - logicpd,imx6q-logicpd - lwn,display5 # Liebherr Display5 i.MX6 Quad Board - lwn,mccmon6 # Liebherr Monitor6 i.MX6 Quad Board @@ -331,6 +332,7 @@ properties: - fsl,imx6qp-sabreauto # i.MX6 Quad Plus SABRE Automotive Board - fsl,imx6qp-sabresd # i.MX6 Quad Plus SABRE Smart Device Board - karo,imx6qp-tx6qp # Ka-Ro electronics TX6QP-8037 Module + - kvg,vicutp # Kverneland UT1P board - prt,prtwd3 # Protonic WD3 board - wand,imx6qp-wandboard # Wandboard i.MX6 QuadPlus Board - zii,imx6qp-zii-rdu2 # ZII RDU2+ Board @@ -364,7 +366,12 @@ properties: - fsl,imx6dl-sabresd # i.MX6 DualLite SABRE Smart Device Board - karo,imx6dl-tx6dl # Ka-Ro electronics TX6U Modules - kontron,imx6dl-samx6i # Kontron i.MX6 Solo SMARC Module + - kvg,victgo # Kverneland TGO + - kvg,vicut1 # Kverneland UT1 board + - ply,plybas # Plymovent BAS board + - ply,plym2m # Plymovent M2M board - poslab,imx6dl-savageboard # Poslab SavageBoard Dual + - prt,prtmvt # Protonic MVT board - prt,prtrvt # Protonic RVT board - prt,prtvt7 # Protonic VT7 board - rex,imx6dl-rex-basic # Rex Basic i.MX6 Dual Lite Board @@ -488,6 +495,7 @@ properties: - karo,imx6ul-tx6ul # Ka-Ro electronics TXUL-0010 Module - kontron,imx6ul-n6310-som # Kontron N6310 SOM - kontron,imx6ul-n6311-som # Kontron N6311 SOM + - prt,prti6g # Protonic PRTI6G Board - technexion,imx6ul-pico-dwarf # TechNexion i.MX6UL Pico-Dwarf - technexion,imx6ul-pico-hobbit # TechNexion i.MX6UL Pico-Hobbit - technexion,imx6ul-pico-pi # TechNexion i.MX6UL Pico-Pi @@ -670,8 +678,12 @@ properties: items: - enum: - beacon,imx8mm-beacon-kit # i.MX8MM Beacon Development Kit + - boundary,imx8mm-nitrogen8mm # i.MX8MM Nitrogen Board - fsl,imx8mm-ddr4-evk # i.MX8MM DDR4 EVK Board - fsl,imx8mm-evk # i.MX8MM EVK Board + - gw,imx8mm-gw71xx-0x # i.MX8MM Gateworks Development Kit + - gw,imx8mm-gw72xx-0x # i.MX8MM Gateworks Development Kit + - gw,imx8mm-gw73xx-0x # i.MX8MM Gateworks Development Kit - kontron,imx8mm-n801x-som # i.MX8MM Kontron SL (N801X) SOM - variscite,var-som-mx8mm # i.MX8MM Variscite VAR-SOM-MX8MM module - const: fsl,imx8mm @@ -691,6 +703,7 @@ properties: - description: i.MX8MN based Boards items: - enum: + - beacon,imx8mn-beacon-kit # i.MX8MN Beacon Development Kit - fsl,imx8mn-ddr4-evk # i.MX8MN DDR4 EVK Board - fsl,imx8mn-evk # i.MX8MN LPDDR4 EVK Board - const: fsl,imx8mn @@ -707,6 +720,12 @@ properties: - fsl,imx8mp-evk # i.MX8MP EVK Board - const: fsl,imx8mp + - description: PHYTEC phyCORE-i.MX8MP SoM based boards + items: + - const: phytec,imx8mp-phyboard-pollux-rdk # phyBOARD-Pollux RDK + - const: phytec,imx8mp-phycore-som # phyCORE-i.MX8MP SoM + - const: fsl,imx8mp + - description: i.MX8MQ based Boards items: - enum: @@ -724,6 +743,7 @@ properties: - enum: - purism,librem5r2 # Purism Librem5 phone "Chestnut" - purism,librem5r3 # Purism Librem5 phone "Dogwood" + - purism,librem5r4 # Purism Librem5 phone "Evergreen" - const: purism,librem5 - const: fsl,imx8mq @@ -834,10 +854,12 @@ properties: Kontron SMARC-sAL28 board on the SMARC Eval Carrier 2.0 items: - enum: + - kontron,sl28-var1-ads2 - kontron,sl28-var2-ads2 - kontron,sl28-var3-ads2 - kontron,sl28-var4-ads2 - enum: + - kontron,sl28-var1 - kontron,sl28-var2 - kontron,sl28-var3 - kontron,sl28-var4 @@ -848,6 +870,7 @@ properties: Kontron SMARC-sAL28 board (on a generic/undefined carrier) items: - enum: + - kontron,sl28-var1 - kontron,sl28-var2 - kontron,sl28-var3 - kontron,sl28-var4 diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml index 53f0d4e3ea98..93b3bdf6eaeb 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek.yaml @@ -120,7 +120,9 @@ properties: - const: mediatek,mt8183 - description: Google Krane (Lenovo IdeaPad Duet, 10e,...) items: - - const: google,krane-sku176 + - enum: + - google,krane-sku0 + - google,krane-sku176 - const: google,krane - const: mediatek,mt8183 diff --git a/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml b/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml index 0a9889debc7c..c299dc907f6c 100644 --- a/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml +++ b/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml @@ -24,6 +24,7 @@ properties: - qcom,sc7180-llcc - qcom,sdm845-llcc - qcom,sm8150-llcc + - qcom,sm8250-llcc reg: items: diff --git a/Documentation/devicetree/bindings/arm/pmu.yaml b/Documentation/devicetree/bindings/arm/pmu.yaml index 693ef3f185a8..e17ac049e890 100644 --- a/Documentation/devicetree/bindings/arm/pmu.yaml +++ b/Documentation/devicetree/bindings/arm/pmu.yaml @@ -43,6 +43,7 @@ properties: - arm,cortex-a75-pmu - arm,cortex-a76-pmu - arm,cortex-a77-pmu + - arm,cortex-a78-pmu - arm,neoverse-e1-pmu - arm,neoverse-n1-pmu - brcm,vulcan-pmu diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index c97d4a580f47..174134f920e1 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -40,7 +40,9 @@ description: | sdm630 sdm660 sdm845 + sdx55 sm8250 + sm8350 The 'board' element must be one of the following strings: @@ -169,6 +171,11 @@ properties: - items: - enum: + - qcom,sdx55-mtp + - const: qcom,sdx55 + + - items: + - enum: - qcom,ipq6018-cp01-c1 - const: qcom,ipq6018 @@ -178,6 +185,11 @@ properties: - qcom,sm8250-mtp - const: qcom,sm8250 + - items: + - enum: + - qcom,sm8350-mtp + - const: qcom,sm8350 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/arm/renesas.yaml b/Documentation/devicetree/bindings/arm/renesas.yaml index fe11be65039a..5fd0696a9f91 100644 --- a/Documentation/devicetree/bindings/arm/renesas.yaml +++ b/Documentation/devicetree/bindings/arm/renesas.yaml @@ -130,6 +130,7 @@ properties: - description: RZ/G2N (R8A774B1) items: - enum: + - beacon,beacon-rzg2n # Beacon EmbeddedWorks RZ/G2N Kit - hoperun,hihope-rzg2n # HopeRun HiHope RZ/G2N platform - const: renesas,r8a774b1 @@ -154,6 +155,7 @@ properties: - description: RZ/G2H (R8A774E1) items: - enum: + - beacon,beacon-rzg2h # Beacon EmbeddedWorks RZ/G2H Kit - hoperun,hihope-rzg2h # HopeRun HiHope RZ/G2H platform - const: renesas,r8a774e1 diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml index ef4544ad6f82..8a2dd9f1cff2 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -467,6 +467,11 @@ properties: - const: radxa,rockpi4 - const: rockchip,rk3399 + - description: Radxa ROCK Pi E + items: + - const: radxa,rockpi-e + - const: rockchip,rk3328 + - description: Radxa ROCK Pi N8 items: - const: radxa,rockpi-n8 diff --git a/Documentation/devicetree/bindings/arm/sirf.yaml b/Documentation/devicetree/bindings/arm/sirf.yaml deleted file mode 100644 index b25eb35d1b66..000000000000 --- a/Documentation/devicetree/bindings/arm/sirf.yaml +++ /dev/null @@ -1,30 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/arm/sirf.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: CSR SiRFprimaII and SiRFmarco device tree bindings. - -maintainers: - - Binghua Duan <binghua.duan@csr.com> - - Barry Song <Baohua.Song@csr.com> - -properties: - $nodename: - const: '/' - compatible: - oneOf: - - items: - - const: sirf,atlas6-cb - - const: sirf,atlas6 - - items: - - const: sirf,atlas7-cb - - const: sirf,atlas7 - - items: - - const: sirf,prima2-cb - - const: sirf,prima2 - -additionalProperties: true - -... diff --git a/Documentation/devicetree/bindings/arm/ste-u300.txt b/Documentation/devicetree/bindings/arm/ste-u300.txt deleted file mode 100644 index d11d80006a19..000000000000 --- a/Documentation/devicetree/bindings/arm/ste-u300.txt +++ /dev/null @@ -1,46 +0,0 @@ -ST-Ericsson U300 Device Tree Bindings - -For various board the "board" node may contain specific properties -that pertain to this particular board, such as board-specific GPIOs -or board power regulator supplies. - -Required root node property: - -compatible="stericsson,u300"; - -Required node: syscon -This contains the system controller. -- compatible: must be "stericsson,u300-syscon". -- reg: the base address and size of the system controller. - -Boards with the U300 SoC include: - -S365 "Small Board U365": - -Required node: s365 -This contains the board-specific information. -- compatible: must be "stericsson,s365". -- vana15-supply: the regulator supplying the 1.5V to drive the - board. -- syscon: a pointer to the syscon node so we can access the - syscon registers to set the board as self-powered. - -Example: - -/ { - model = "ST-Ericsson U300"; - compatible = "stericsson,u300"; - #address-cells = <1>; - #size-cells = <1>; - - s365 { - compatible = "stericsson,s365"; - vana15-supply = <&ab3100_ldo_d_reg>; - syscon = <&syscon>; - }; - - syscon: syscon@c0011000 { - compatible = "stericsson,u300-syscon"; - reg = <0xc0011000 0x1000>; - }; -}; diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml index 6db32fbf813f..08607c7ec1bf 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -657,7 +657,8 @@ properties: - description: Pine64 PineCube items: - const: pine64,pinecube - - const: allwinner,sun8i-s3 + - const: sochip,s3 + - const: allwinner,sun8i-v3 - description: Pine64 PineH64 model A items: @@ -683,23 +684,31 @@ properties: - description: Pine64 PinePhone Developer Batch (1.0) items: - const: pine64,pinephone-1.0 + - const: pine64,pinephone - const: allwinner,sun50i-a64 - description: Pine64 PinePhone Braveheart (1.1) items: - const: pine64,pinephone-1.1 + - const: pine64,pinephone - const: allwinner,sun50i-a64 - description: Pine64 PinePhone (1.2) items: - const: pine64,pinephone-1.2 + - const: pine64,pinephone - const: allwinner,sun50i-a64 - - description: Pine64 PineTab + - description: Pine64 PineTab, Development Sample items: - const: pine64,pinetab - const: allwinner,sun50i-a64 + - description: Pine64 PineTab, Early Adopter's batch (and maybe later ones) + items: + - const: pine64,pinetab-early-adopter + - const: allwinner,sun50i-a64 + - description: Pine64 SoPine Baseboard items: - const: pine64,sopine-baseboard @@ -777,6 +786,12 @@ properties: - const: sinlinx,sina33 - const: allwinner,sun8i-a33 + - description: SL631 Action Camera with IMX179 + items: + - const: allwinner,sl631-imx179 + - const: allwinner,sl631 + - const: allwinner,sun8i-v3 + - description: Tanix TX6 items: - const: oranth,tanix-tx6 diff --git a/Documentation/devicetree/bindings/arm/tegra.yaml b/Documentation/devicetree/bindings/arm/tegra.yaml index c5fbf869aa93..b9f75e20fef5 100644 --- a/Documentation/devicetree/bindings/arm/tegra.yaml +++ b/Documentation/devicetree/bindings/arm/tegra.yaml @@ -120,10 +120,18 @@ properties: items: - const: nvidia,p3668-0000 - const: nvidia,tegra194 + - description: Jetson Xavier NX (eMMC) + items: + - const: nvidia,p3668-0001 + - const: nvidia,tegra194 - description: Jetson Xavier NX Developer Kit items: - const: nvidia,p3509-0000+p3668-0000 - const: nvidia,tegra194 + - description: Jetson Xavier NX Developer Kit (eMMC) + items: + - const: nvidia,p3509-0000+p3668-0001 + - const: nvidia,tegra194 - items: - enum: - nvidia,tegra234-vdk diff --git a/Documentation/devicetree/bindings/arm/xilinx.yaml b/Documentation/devicetree/bindings/arm/xilinx.yaml index e0c6787f6e94..f52c7e8ce654 100644 --- a/Documentation/devicetree/bindings/arm/xilinx.yaml +++ b/Documentation/devicetree/bindings/arm/xilinx.yaml @@ -22,6 +22,9 @@ properties: - adapteva,parallella - digilent,zynq-zybo - digilent,zynq-zybo-z7 + - ebang,ebaz4205 + - myir,zynq-zturn-v5 + - myir,zynq-zturn - xlnx,zynq-cc108 - xlnx,zynq-zc702 - xlnx,zynq-zc706 @@ -91,6 +94,7 @@ properties: items: - enum: - xlnx,zynqmp-zcu104-revA + - xlnx,zynqmp-zcu104-revC - xlnx,zynqmp-zcu104-rev1.0 - const: xlnx,zynqmp-zcu104 - const: xlnx,zynqmp @@ -107,7 +111,7 @@ properties: items: - enum: - xlnx,zynqmp-zcu111-revA - - xlnx,zynqmp-zcu11-rev1.0 + - xlnx,zynqmp-zcu111-rev1.0 - const: xlnx,zynqmp-zcu111 - const: xlnx,zynqmp diff --git a/Documentation/devicetree/bindings/arm/zte,sysctrl.txt b/Documentation/devicetree/bindings/arm/zte,sysctrl.txt deleted file mode 100644 index 7e66b7f7ba96..000000000000 --- a/Documentation/devicetree/bindings/arm/zte,sysctrl.txt +++ /dev/null @@ -1,30 +0,0 @@ -ZTE sysctrl Registers - -Registers for 'zte,zx296702' SoC: - -System management required properties: - - compatible = "zte,sysctrl" - -Low power management required properties: - - compatible = "zte,zx296702-pcu" - -Bus matrix required properties: - - compatible = "zte,zx-bus-matrix" - - -Registers for 'zte,zx296718' SoC: - -System management required properties: - - compatible = "zte,zx296718-aon-sysctrl" - - compatible = "zte,zx296718-sysctrl" - -Example: -aon_sysctrl: aon-sysctrl@116000 { - compatible = "zte,zx296718-aon-sysctrl", "syscon"; - reg = <0x116000 0x1000>; -}; - -sysctrl: sysctrl@1463000 { - compatible = "zte,zx296718-sysctrl", "syscon"; - reg = <0x1463000 0x1000>; -}; diff --git a/Documentation/devicetree/bindings/arm/zte.yaml b/Documentation/devicetree/bindings/arm/zte.yaml deleted file mode 100644 index 672f8129cd31..000000000000 --- a/Documentation/devicetree/bindings/arm/zte.yaml +++ /dev/null @@ -1,28 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/arm/zte.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: ZTE platforms device tree bindings - -maintainers: - - Jun Nie <jun.nie@linaro.org> - -properties: - $nodename: - const: '/' - compatible: - oneOf: - - items: - - enum: - - zte,zx296702-ad1 - - const: zte,zx296702 - - items: - - enum: - - zte,zx296718-evb - - const: zte,zx296718 - -additionalProperties: true - -... diff --git a/Documentation/devicetree/bindings/bus/allwinner,sun8i-a23-rsb.yaml b/Documentation/devicetree/bindings/bus/allwinner,sun8i-a23-rsb.yaml index 32d33b983d66..3d719f468a5b 100644 --- a/Documentation/devicetree/bindings/bus/allwinner,sun8i-a23-rsb.yaml +++ b/Documentation/devicetree/bindings/bus/allwinner,sun8i-a23-rsb.yaml @@ -21,7 +21,9 @@ properties: oneOf: - const: allwinner,sun8i-a23-rsb - items: - - const: allwinner,sun8i-a83t-rsb + - enum: + - allwinner,sun8i-a83t-rsb + - allwinner,sun50i-h616-rsb - const: allwinner,sun8i-a23-rsb reg: diff --git a/Documentation/devicetree/bindings/c6x/clocks.txt b/Documentation/devicetree/bindings/c6x/clocks.txt deleted file mode 100644 index a04f5fd30122..000000000000 --- a/Documentation/devicetree/bindings/c6x/clocks.txt +++ /dev/null @@ -1,40 +0,0 @@ -C6X PLL Clock Controllers -------------------------- - -This is a first-cut support for the SoC clock controllers. This is still -under development and will probably change as the common device tree -clock support is added to the kernel. - -Required properties: - -- compatible: "ti,c64x+pll" - May also have SoC-specific value to support SoC-specific initialization - in the driver. One of: - "ti,c6455-pll" - "ti,c6457-pll" - "ti,c6472-pll" - "ti,c6474-pll" - -- reg: base address and size of register area -- clock-frequency: input clock frequency in hz - - -Optional properties: - -- ti,c64x+pll-bypass-delay: CPU cycles to delay when entering bypass mode - -- ti,c64x+pll-reset-delay: CPU cycles to delay after PLL reset - -- ti,c64x+pll-lock-delay: CPU cycles to delay after PLL frequency change - -Example: - - clock-controller@29a0000 { - compatible = "ti,c6472-pll", "ti,c64x+pll"; - reg = <0x029a0000 0x200>; - clock-frequency = <25000000>; - - ti,c64x+pll-bypass-delay = <200>; - ti,c64x+pll-reset-delay = <12000>; - ti,c64x+pll-lock-delay = <80000>; - }; diff --git a/Documentation/devicetree/bindings/c6x/dscr.txt b/Documentation/devicetree/bindings/c6x/dscr.txt deleted file mode 100644 index 92672235de57..000000000000 --- a/Documentation/devicetree/bindings/c6x/dscr.txt +++ /dev/null @@ -1,127 +0,0 @@ -Device State Configuration Registers ------------------------------------- - -TI C6X SoCs contain a region of miscellaneous registers which provide various -function for SoC control or status. Details vary considerably among from SoC -to SoC with no two being alike. - -In general, the Device State Configuration Registers (DSCR) will provide one or -more configuration registers often protected by a lock register where one or -more key values must be written to a lock register in order to unlock the -configuration register for writes. These configuration register may be used to -enable (and disable in some cases) SoC pin drivers, select peripheral clock -sources (internal or pin), etc. In some cases, a configuration register is -write once or the individual bits are write once. In addition to device config, -the DSCR block may provide registers which are used to reset peripherals, -provide device ID information, provide ethernet MAC addresses, as well as other -miscellaneous functions. - -For device state control (enable/disable), each device control is assigned an -id which is used by individual device drivers to control the state as needed. - -Required properties: - -- compatible: must be "ti,c64x+dscr" -- reg: register area base and size - -Optional properties: - - NOTE: These are optional in that not all SoCs will have all properties. For - SoCs which do support a given property, leaving the property out of the - device tree will result in reduced functionality or possibly driver - failure. - -- ti,dscr-devstat - offset of the devstat register - -- ti,dscr-silicon-rev - offset, start bit, and bitsize of silicon revision field - -- ti,dscr-rmii-resets - offset and bitmask of RMII reset field. May have multiple tuples if more - than one ethernet port is available. - -- ti,dscr-locked-regs - possibly multiple tuples describing registers which are write protected by - a lock register. Each tuple consists of the register offset, lock register - offsset, and the key value used to unlock the register. - -- ti,dscr-kick-regs - offset and key values of two "kick" registers used to write protect other - registers in DSCR. On SoCs using kick registers, the first key must be - written to the first kick register and the second key must be written to - the second register before other registers in the area are write-enabled. - -- ti,dscr-mac-fuse-regs - MAC addresses are contained in two registers. Each element of a MAC address - is contained in a single byte. This property has two tuples. Each tuple has - a register offset and four cells representing bytes in the register from - most significant to least. The value of these four cells is the MAC byte - index (1-6) of the byte within the register. A value of 0 means the byte - is unused in the MAC address. - -- ti,dscr-devstate-ctl-regs - This property describes the bitfields used to control the state of devices. - Each tuple describes a range of identical bitfields used to control one or - more devices (one bitfield per device). The layout of each tuple is: - - start_id num_ids reg enable disable start_bit nbits - - Where: - start_id is device id for the first device control in the range - num_ids is the number of device controls in the range - reg is the offset of the register holding the control bits - enable is the value to enable a device - disable is the value to disable a device (0xffffffff if cannot disable) - start_bit is the bit number of the first bit in the range - nbits is the number of bits per device control - -- ti,dscr-devstate-stat-regs - This property describes the bitfields used to provide device state status - for device states controlled by the DSCR. Each tuple describes a range of - identical bitfields used to provide status for one or more devices (one - bitfield per device). The layout of each tuple is: - - start_id num_ids reg enable disable start_bit nbits - - Where: - start_id is device id for the first device status in the range - num_ids is the number of devices covered by the range - reg is the offset of the register holding the status bits - enable is the value indicating device is enabled - disable is the value indicating device is disabled - start_bit is the bit number of the first bit in the range - nbits is the number of bits per device status - -- ti,dscr-privperm - Offset and default value for register used to set access privilege for - some SoC devices. - - -Example: - - device-state-config-regs@2a80000 { - compatible = "ti,c64x+dscr"; - reg = <0x02a80000 0x41000>; - - ti,dscr-devstat = <0>; - ti,dscr-silicon-rev = <8 28 0xf>; - ti,dscr-rmii-resets = <0x40020 0x00040000>; - - ti,dscr-locked-regs = <0x40008 0x40004 0x0f0a0b00>; - ti,dscr-devstate-ctl-regs = - <0 12 0x40008 1 0 0 2 - 12 1 0x40008 3 0 30 2 - 13 2 0x4002c 1 0xffffffff 0 1>; - ti,dscr-devstate-stat-regs = - <0 10 0x40014 1 0 0 3 - 10 2 0x40018 1 0 0 3>; - - ti,dscr-mac-fuse-regs = <0x700 1 2 3 4 - 0x704 5 6 0 0>; - - ti,dscr-privperm = <0x41c 0xaaaaaaaa>; - - ti,dscr-kick-regs = <0x38 0x83E70B13 - 0x3c 0x95A4F1E0>; - }; diff --git a/Documentation/devicetree/bindings/c6x/emifa.txt b/Documentation/devicetree/bindings/c6x/emifa.txt deleted file mode 100644 index 0ff6e9b9a13f..000000000000 --- a/Documentation/devicetree/bindings/c6x/emifa.txt +++ /dev/null @@ -1,62 +0,0 @@ -External Memory Interface -------------------------- - -The emifa node describes a simple external bus controller found on some C6X -SoCs. This interface provides external busses with a number of chip selects. - -Required properties: - -- compatible: must be "ti,c64x+emifa", "simple-bus" -- reg: register area base and size -- #address-cells: must be 2 (chip-select + offset) -- #size-cells: must be 1 -- ranges: mapping from EMIFA space to parent space - - -Optional properties: - -- ti,dscr-dev-enable: Device ID if EMIF is enabled/disabled from DSCR - -- ti,emifa-burst-priority: - Number of memory transfers after which the EMIF will elevate the priority - of the oldest command in the command FIFO. Setting this field to 255 - disables this feature, thereby allowing old commands to stay in the FIFO - indefinitely. - -- ti,emifa-ce-config: - Configuration values for each of the supported chip selects. - -Example: - - emifa@70000000 { - compatible = "ti,c64x+emifa", "simple-bus"; - #address-cells = <2>; - #size-cells = <1>; - reg = <0x70000000 0x100>; - ranges = <0x2 0x0 0xa0000000 0x00000008 - 0x3 0x0 0xb0000000 0x00400000 - 0x4 0x0 0xc0000000 0x10000000 - 0x5 0x0 0xD0000000 0x10000000>; - - ti,dscr-dev-enable = <13>; - ti,emifa-burst-priority = <255>; - ti,emifa-ce-config = <0x00240120 - 0x00240120 - 0x00240122 - 0x00240122>; - - flash@3,0 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "cfi-flash"; - reg = <0x3 0x0 0x400000>; - bank-width = <1>; - device-width = <1>; - partition@0 { - reg = <0x0 0x400000>; - label = "NOR"; - }; - }; - }; - -This shows a flash chip attached to chip select 3. diff --git a/Documentation/devicetree/bindings/c6x/soc.txt b/Documentation/devicetree/bindings/c6x/soc.txt deleted file mode 100644 index b1e4973b5769..000000000000 --- a/Documentation/devicetree/bindings/c6x/soc.txt +++ /dev/null @@ -1,28 +0,0 @@ -C6X System-on-Chip ------------------- - -Required properties: - -- compatible: "simple-bus" -- #address-cells: must be 1 -- #size-cells: must be 1 -- ranges - -Optional properties: - -- model: specific SoC model - -- nodes for IP blocks within SoC - - -Example: - - soc { - compatible = "simple-bus"; - model = "tms320c6455"; - #address-cells = <1>; - #size-cells = <1>; - ranges; - - ... - }; diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml index 4286ed767a0a..ce11b2027199 100644 --- a/Documentation/devicetree/bindings/connector/usb-connector.yaml +++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml @@ -137,6 +137,18 @@ properties: maxItems: 7 $ref: /schemas/types.yaml#/definitions/uint32-array + sink-vdos: + description: An array of u32 with each entry, a Vendor Defined Message Object (VDO), + providing additional information corresponding to the product, the detailed bit + definitions and the order of each VDO can be found in + "USB Power Delivery Specification Revision 3.0, Version 2.0 + ECNs 2020-12-10" + chapter 6.4.4.3.1 Discover Identity. User can specify the VDO array via + VDO_IDH/_CERT/_PRODUCT/_UFP/_DFP/_PCABLE/_ACABLE(1/2)/_VPD() defined in + dt-bindings/usb/pd.h. + minItems: 3 + maxItems: 6 + $ref: /schemas/types.yaml#/definitions/uint32-array + op-sink-microwatt: description: Sink required operating power in microwatt, if source can't offer the power, Capability Mismatch is set. Required for power sink and diff --git a/Documentation/devicetree/bindings/crypto/intel,keembay-ocs-hcu.yaml b/Documentation/devicetree/bindings/crypto/intel,keembay-ocs-hcu.yaml new file mode 100644 index 000000000000..acb92706d280 --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/intel,keembay-ocs-hcu.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/crypto/intel,keembay-ocs-hcu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel Keem Bay OCS HCU Device Tree Bindings + +maintainers: + - Declan Murphy <declan.murphy@intel.com> + - Daniele Alessandrelli <daniele.alessandrelli@intel.com> + +description: + The Intel Keem Bay Offload and Crypto Subsystem (OCS) Hash Control Unit (HCU) + provides hardware-accelerated hashing and HMAC. + +properties: + compatible: + const: intel,keembay-ocs-hcu + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + crypto@3000b000 { + compatible = "intel,keembay-ocs-hcu"; + reg = <0x3000b000 0x1000>; + interrupts = <GIC_SPI 121 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&scmi_clk 94>; + }; diff --git a/Documentation/devicetree/bindings/crypto/samsung-slimsss.yaml b/Documentation/devicetree/bindings/crypto/samsung-slimsss.yaml index 7743eae049ab..676950bb7b37 100644 --- a/Documentation/devicetree/bindings/crypto/samsung-slimsss.yaml +++ b/Documentation/devicetree/bindings/crypto/samsung-slimsss.yaml @@ -8,7 +8,6 @@ title: Samsung Exynos SoC SlimSSS (Slim Security SubSystem) module maintainers: - Krzysztof Kozlowski <krzk@kernel.org> - - Kamil Konieczny <k.konieczny@partner.samsung.com> description: |+ The SlimSSS module in Exynos5433 SoC supports the following: diff --git a/Documentation/devicetree/bindings/crypto/samsung-sss.yaml b/Documentation/devicetree/bindings/crypto/samsung-sss.yaml index cf1c47a81d7f..6d62b0e42fc9 100644 --- a/Documentation/devicetree/bindings/crypto/samsung-sss.yaml +++ b/Documentation/devicetree/bindings/crypto/samsung-sss.yaml @@ -8,7 +8,6 @@ title: Samsung Exynos SoC SSS (Security SubSystem) module maintainers: - Krzysztof Kozlowski <krzk@kernel.org> - - Kamil Konieczny <k.konieczny@partner.samsung.com> description: |+ The SSS module in S5PV210 SoC supports the following: diff --git a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-backend.yaml b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-backend.yaml index 86057d541065..12a7df0e38b2 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-backend.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-backend.yaml @@ -84,36 +84,23 @@ properties: const: dma-mem ports: - type: object - description: | - A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. + $ref: /schemas/graph.yaml#/properties/ports properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - port@0: - type: object - description: | + $ref: /schemas/graph.yaml#/properties/port + description: Input endpoints of the controller. port@1: - type: object - description: | + $ref: /schemas/graph.yaml#/properties/port + description: Output endpoints of the controller. required: - - "#address-cells" - - "#size-cells" - port@0 - port@1 - additionalProperties: false - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-frontend.yaml b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-frontend.yaml index 3eb1c2bbf4e7..055157fbf3bf 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-frontend.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-frontend.yaml @@ -57,35 +57,22 @@ properties: maxItems: 1 ports: - type: object - description: | - A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. + $ref: /schemas/graph.yaml#/properties/ports properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Input endpoints of the controller. port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Output endpoints of the controller. required: - - "#address-cells" - - "#size-cells" - port@1 - additionalProperties: false - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-hdmi.yaml b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-hdmi.yaml index 75e6479397a5..7f11452539f4 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-hdmi.yaml @@ -76,37 +76,24 @@ properties: - const: audio-tx ports: - type: object - description: | - A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. + $ref: /schemas/graph.yaml#/properties/ports properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Input endpoints of the controller. port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Output endpoints of the controller. Usually an HDMI connector. required: - - "#address-cells" - - "#size-cells" - port@0 - port@1 - additionalProperties: false - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tcon.yaml b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tcon.yaml index 4c15a2644a7c..c13faf3e6581 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tcon.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tcon.yaml @@ -115,31 +115,24 @@ properties: - const: lvds ports: - type: object - description: | - A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. + $ref: /schemas/graph.yaml#/properties/ports properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Input endpoints of the controller. port@1: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: | Output endpoints of the controller. patternProperties: "^endpoint(@[0-9])$": - type: object + $ref: /schemas/graph.yaml#/$defs/endpoint-base + unevaluatedProperties: false properties: allwinner,tcon-channel: @@ -156,16 +149,10 @@ properties: property is not present, the endpoint number will be used as the channel number. - unevaluatedProperties: true - required: - - "#address-cells" - - "#size-cells" - port@0 - port@1 - additionalProperties: false - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tv-encoder.yaml b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tv-encoder.yaml index 6009324be967..afc0ed799e0e 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tv-encoder.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tv-encoder.yaml @@ -24,11 +24,9 @@ properties: maxItems: 1 port: - type: object + $ref: /schemas/graph.yaml#/properties/port description: - A port node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. The - first port should be the input endpoint, usually coming from the + The first port should be the input endpoint, usually coming from the associated TCON. required: diff --git a/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-drc.yaml b/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-drc.yaml index 0c1ce55940e1..71cce5687580 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-drc.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-drc.yaml @@ -46,36 +46,23 @@ properties: maxItems: 1 ports: - type: object - description: | - A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. + $ref: /schemas/graph.yaml#/properties/ports properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Input endpoints of the controller. port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Output endpoints of the controller. required: - - "#address-cells" - - "#size-cells" - port@0 - port@1 - additionalProperties: false - 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 7aa330dabc44..a738d7c12a97 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-mipi-dsi.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-mipi-dsi.yaml @@ -47,11 +47,9 @@ properties: const: dphy port: - type: object + $ref: /schemas/graph.yaml#/properties/port description: - A port node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. That - port should be the input endpoint, usually coming from the + The port should be the input endpoint, usually coming from the associated TCON. required: diff --git a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-de2-mixer.yaml b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-de2-mixer.yaml index c040eef56518..4f91eec26de9 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-de2-mixer.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-de2-mixer.yaml @@ -43,35 +43,22 @@ properties: maxItems: 1 ports: - type: object - description: | - A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. + $ref: /schemas/graph.yaml#/properties/ports properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Input endpoints of the controller. port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Output endpoints of the controller. required: - - "#address-cells" - - "#size-cells" - port@1 - additionalProperties: false - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml index fa4769a0b26e..b3e9992525c2 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml @@ -93,38 +93,25 @@ properties: The VCC power supply of the controller ports: - type: object - description: | - A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. + $ref: /schemas/graph.yaml#/properties/ports properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Input endpoints of the controller. Usually the associated TCON. port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Output endpoints of the controller. Usually an HDMI connector. required: - - "#address-cells" - - "#size-cells" - port@0 - port@1 - additionalProperties: false - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/allwinner,sun8i-r40-tcon-top.yaml b/Documentation/devicetree/bindings/display/allwinner,sun8i-r40-tcon-top.yaml index b98ca609824b..ec21e8bf2767 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun8i-r40-tcon-top.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun8i-r40-tcon-top.yaml @@ -80,141 +80,45 @@ properties: maxItems: 1 ports: - type: object - description: | - A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. - All ports should have only one endpoint connected to - remote endpoint. + $ref: /schemas/graph.yaml#/properties/ports properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Input endpoint for Mixer 0 mux. port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Output endpoint for Mixer 0 mux - properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - - reg: true - - patternProperties: - "^endpoint@[0-9]$": - type: object - - properties: - reg: - description: | - ID of the target TCON - - required: - - reg - - required: - - "#address-cells" - - "#size-cells" - - additionalProperties: false - port@2: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Input endpoint for Mixer 1 mux. port@3: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Output endpoint for Mixer 1 mux - properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - - reg: true - - patternProperties: - "^endpoint@[0-9]$": - type: object - - properties: - reg: - description: | - ID of the target TCON - - required: - - reg - - required: - - "#address-cells" - - "#size-cells" - - additionalProperties: false - port@4: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Input endpoint for HDMI mux. - properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - - reg: true - - patternProperties: - "^endpoint@[0-9]$": - type: object - - properties: - reg: - description: | - ID of the target TCON - - required: - - reg - - required: - - "#address-cells" - - "#size-cells" - - additionalProperties: false - port@5: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Output endpoint for HDMI mux required: - - "#address-cells" - - "#size-cells" - port@0 - port@1 - port@4 - port@5 - additionalProperties: false - required: - "#clock-cells" - compatible diff --git a/Documentation/devicetree/bindings/display/allwinner,sun9i-a80-deu.yaml b/Documentation/devicetree/bindings/display/allwinner,sun9i-a80-deu.yaml index 96de41d32b3e..637372ec4614 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun9i-a80-deu.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun9i-a80-deu.yaml @@ -40,36 +40,23 @@ properties: maxItems: 1 ports: - type: object - description: | - A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. + $ref: /schemas/graph.yaml#/properties/ports properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Input endpoints of the controller. port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Output endpoints of the controller. required: - - "#address-cells" - - "#size-cells" - port@0 - port@1 - additionalProperties: false - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml index 0da42ab8fd3a..cf5a208f2f10 100644 --- a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml @@ -81,12 +81,12 @@ properties: description: phandle to an external 5V regulator to power the HDMI logic port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: A port node pointing to the VENC Input port node. port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: A port node pointing to the TMDS Output port node. diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml index a8d202c9d004..851cb0781217 100644 --- a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml +++ b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml @@ -83,12 +83,12 @@ properties: description: phandle to the associated power domain port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: A port node pointing to the CVBS VDAC port node. port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: A port node pointing to the HDMI-TX port node. diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml index 7ce06f9f9f8e..6e8ac910bdd8 100644 --- a/Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml @@ -53,6 +53,24 @@ properties: - const: audio - const: cec + interrupts: + items: + - description: CEC TX interrupt + - description: CEC RX interrupt + - description: CEC stuck at low interrupt + - description: Wake-up interrupt + - description: Hotplug connected interrupt + - description: Hotplug removed interrupt + + interrupt-names: + items: + - const: cec-tx + - const: cec-rx + - const: cec-low + - const: wakeup + - const: hpd-connected + - const: hpd-removed + ddc: allOf: - $ref: /schemas/types.yaml#/definitions/phandle @@ -90,7 +108,7 @@ required: - resets - ddc -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-dpi.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-dpi.yaml index 5c1024bbc1b3..c9ad0ecc9b6d 100644 --- a/Documentation/devicetree/bindings/display/brcm,bcm2835-dpi.yaml +++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-dpi.yaml @@ -27,10 +27,9 @@ properties: - const: pixel port: - type: object - description: > - Port node with a single endpoint connecting to the panel, as - defined in Documentation/devicetree/bindings/media/video-interfaces.txt. + $ref: /schemas/graph.yaml#/properties/port + description: + Port node with a single endpoint connecting to the panel. required: - compatible diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-dsi0.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-dsi0.yaml index eb44e072b6e5..55c60919991f 100644 --- a/Documentation/devicetree/bindings/display/brcm,bcm2835-dsi0.yaml +++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-dsi0.yaml @@ -18,6 +18,7 @@ properties: compatible: enum: + - brcm,bcm2711-dsi1 - brcm,bcm2835-dsi0 - brcm,bcm2835-dsi1 diff --git a/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml b/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml index 9392b5502a32..c789784efe30 100644 --- a/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml +++ b/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml @@ -35,16 +35,16 @@ properties: maxItems: 1 ports: - type: object + $ref: /schemas/graph.yaml#/properties/ports properties: port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Video port for MIPI DSI input. port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Video port for panel or connector. diff --git a/Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml b/Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml index 3ba477aefdd7..8e13f27b28ed 100644 --- a/Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml +++ b/Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml @@ -42,31 +42,18 @@ properties: description: Regulator for 1.0V digital core power. ports: - type: object - description: - A node containing input and output port nodes with endpoint - definitions as documented in - Documentation/devicetree/bindings/media/video-interfaces.txt - Documentation/devicetree/bindings/graph.txt + $ref: /schemas/graph.yaml#/properties/ports properties: port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Video port for HDMI input. - properties: - reg: - const: 0 - port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Video port for SlimPort, DisplayPort, eDP or MyDP output. - properties: - reg: - const: 1 - required: - port@0 - port@1 diff --git a/Documentation/devicetree/bindings/display/bridge/anx6345.yaml b/Documentation/devicetree/bindings/display/bridge/anx6345.yaml index fccd63521a8c..1c0406c38fe5 100644 --- a/Documentation/devicetree/bindings/display/bridge/anx6345.yaml +++ b/Documentation/devicetree/bindings/display/bridge/anx6345.yaml @@ -32,31 +32,23 @@ properties: description: Regulator for 2.5V digital core power. ports: - type: object + $ref: /schemas/graph.yaml#/properties/ports properties: - '#address-cells': - const: 1 - - '#size-cells': - const: 0 - port@0: - type: object - description: | + $ref: /schemas/graph.yaml#/properties/port + description: Video port for LVTTL input port@1: - type: object - description: | + $ref: /schemas/graph.yaml#/properties/port + description: Video port for eDP output (panel or connector). May be omitted if EDID works reliably. required: - port@0 - additionalProperties: false - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/bridge/cdns,mhdp8546.yaml b/Documentation/devicetree/bindings/display/bridge/cdns,mhdp8546.yaml index 74d675fc6e7b..63427878715e 100644 --- a/Documentation/devicetree/bindings/display/bridge/cdns,mhdp8546.yaml +++ b/Documentation/devicetree/bindings/display/bridge/cdns,mhdp8546.yaml @@ -57,47 +57,37 @@ properties: maxItems: 1 ports: - type: object - description: - Ports as described in Documentation/devicetree/bindings/graph.txt. + $ref: /schemas/graph.yaml#/properties/ports properties: - '#address-cells': - const: 1 - - '#size-cells': - const: 0 - port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: First input port representing the DP bridge input. port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Second input port representing the DP bridge input. port@2: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Third input port representing the DP bridge input. port@3: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Fourth input port representing the DP bridge input. port@4: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Output port representing the DP bridge output. required: - port@0 - port@4 - - '#address-cells' - - '#size-cells' allOf: - if: diff --git a/Documentation/devicetree/bindings/display/bridge/chrontel,ch7033.yaml b/Documentation/devicetree/bindings/display/bridge/chrontel,ch7033.yaml index 9f38f55fc990..bb6289c7d375 100644 --- a/Documentation/devicetree/bindings/display/bridge/chrontel,ch7033.yaml +++ b/Documentation/devicetree/bindings/display/bridge/chrontel,ch7033.yaml @@ -19,16 +19,16 @@ properties: description: I2C address of the device ports: - type: object + $ref: /schemas/graph.yaml#/properties/ports properties: port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Video port for RGB input. port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | DVI port, should be connected to a node compatible with the dvi-connector binding. diff --git a/Documentation/devicetree/bindings/display/bridge/intel,keembay-dsi.yaml b/Documentation/devicetree/bindings/display/bridge/intel,keembay-dsi.yaml index 35c9dfd86650..dcb1336ee2a5 100644 --- a/Documentation/devicetree/bindings/display/bridge/intel,keembay-dsi.yaml +++ b/Documentation/devicetree/bindings/display/bridge/intel,keembay-dsi.yaml @@ -35,29 +35,21 @@ properties: - const: clk_mipi_cfg ports: - type: object + $ref: /schemas/graph.yaml#/properties/ports properties: - '#address-cells': - const: 1 - - '#size-cells': - const: 0 - port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: MIPI DSI input port. port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: DSI output port. required: - port@0 - port@1 - additionalProperties: false - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/bridge/ite,it6505.yaml b/Documentation/devicetree/bindings/display/bridge/ite,it6505.yaml index 02cfc0a3b550..833d11b2303a 100644 --- a/Documentation/devicetree/bindings/display/bridge/ite,it6505.yaml +++ b/Documentation/devicetree/bindings/display/bridge/ite,it6505.yaml @@ -53,7 +53,7 @@ properties: description: extcon specifier for the Power Delivery port: - type: object + $ref: /schemas/graph.yaml#/properties/port description: A port node pointing to DPI host port node required: diff --git a/Documentation/devicetree/bindings/display/bridge/lontium,lt9611.yaml b/Documentation/devicetree/bindings/display/bridge/lontium,lt9611.yaml index 7a1c89b995e2..5b9d36f7af30 100644 --- a/Documentation/devicetree/bindings/display/bridge/lontium,lt9611.yaml +++ b/Documentation/devicetree/bindings/display/bridge/lontium,lt9611.yaml @@ -38,82 +38,26 @@ properties: description: Regulator for 3.3V IO power. ports: - type: object + $ref: /schemas/graph.yaml#/properties/ports properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - port@0: - type: object - description: | + $ref: /schemas/graph.yaml#/properties/port + description: Primary MIPI port-1 for MIPI input - properties: - reg: - const: 0 - - patternProperties: - "^endpoint(@[0-9])$": - type: object - additionalProperties: false - - properties: - remote-endpoint: - $ref: /schemas/types.yaml#/definitions/phandle - - required: - - reg - port@1: - type: object - description: | + $ref: /schemas/graph.yaml#/properties/port + description: Additional MIPI port-2 for MIPI input, used in combination with primary MIPI port-1 to drive higher resolution displays - properties: - reg: - const: 1 - - patternProperties: - "^endpoint(@[0-9])$": - type: object - additionalProperties: false - - properties: - remote-endpoint: - $ref: /schemas/types.yaml#/definitions/phandle - - required: - - reg - port@2: - type: object - description: | + $ref: /schemas/graph.yaml#/properties/port + description: HDMI port for HDMI output - properties: - reg: - const: 2 - - patternProperties: - "^endpoint(@[0-9])$": - type: object - additionalProperties: false - - properties: - remote-endpoint: - $ref: /schemas/types.yaml#/definitions/phandle - - required: - - reg - required: - - "#address-cells" - - "#size-cells" - port@0 - port@2 diff --git a/Documentation/devicetree/bindings/display/bridge/lvds-codec.yaml b/Documentation/devicetree/bindings/display/bridge/lvds-codec.yaml index 66a14d60ce1d..304a1367faaa 100644 --- a/Documentation/devicetree/bindings/display/bridge/lvds-codec.yaml +++ b/Documentation/devicetree/bindings/display/bridge/lvds-codec.yaml @@ -45,25 +45,17 @@ properties: - thine,thc63lvdm83d # For the THC63LVDM83D LVDS serializer ports: - type: object - description: | - This device has two video ports. Their connections are modeled using the - OF graph bindings specified in Documentation/devicetree/bindings/graph.txt - properties: - '#address-cells': - const: 1 - - '#size-cells': - const: 0 + $ref: /schemas/graph.yaml#/properties/ports + properties: port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | For LVDS encoders, port 0 is the parallel input For LVDS decoders, port 0 is the LVDS input port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | For LVDS encoders, port 1 is the LVDS output For LVDS decoders, port 1 is the parallel output @@ -72,8 +64,6 @@ properties: - port@0 - port@1 - additionalProperties: false - powerdown-gpios: description: The GPIO used to control the power down line of this device. diff --git a/Documentation/devicetree/bindings/display/bridge/nwl-dsi.yaml b/Documentation/devicetree/bindings/display/bridge/nwl-dsi.yaml index a125b2dd3a2f..350fb8f400f0 100644 --- a/Documentation/devicetree/bindings/display/bridge/nwl-dsi.yaml +++ b/Documentation/devicetree/bindings/display/bridge/nwl-dsi.yaml @@ -84,40 +84,23 @@ properties: - const: pclk ports: - type: object - description: - A node containing DSI input & output port nodes with endpoint - definitions as documented in - Documentation/devicetree/bindings/graph.txt. + $ref: /schemas/graph.yaml#/properties/ports + properties: port@0: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base description: Input port node to receive pixel data from the display controller. Exactly one endpoint must be specified. properties: - '#address-cells': - const: 1 - - '#size-cells': - const: 0 - endpoint@0: + $ref: /schemas/graph.yaml#/properties/endpoint description: sub-node describing the input from LCDIF - type: object endpoint@1: + $ref: /schemas/graph.yaml#/properties/endpoint description: sub-node describing the input from DCSS - type: object - - reg: - const: 0 - - required: - - '#address-cells' - - '#size-cells' - - reg oneOf: - required: @@ -125,28 +108,18 @@ properties: - required: - endpoint@1 - additionalProperties: false + unevaluatedProperties: false port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: DSI output port node to the panel or the next bridge in the chain - '#address-cells': - const: 1 - - '#size-cells': - const: 0 - required: - - '#address-cells' - - '#size-cells' - port@0 - port@1 - additionalProperties: false - required: - '#address-cells' - '#size-cells' diff --git a/Documentation/devicetree/bindings/display/bridge/ps8640.yaml b/Documentation/devicetree/bindings/display/bridge/ps8640.yaml index 763c7909473e..fce82b605c8b 100644 --- a/Documentation/devicetree/bindings/display/bridge/ps8640.yaml +++ b/Documentation/devicetree/bindings/display/bridge/ps8640.yaml @@ -41,34 +41,22 @@ properties: description: Regulator for 3.3V digital core power. ports: - type: object - description: - A node containing DSI input & output port nodes with endpoint - definitions as documented in - Documentation/devicetree/bindings/media/video-interfaces.txt - Documentation/devicetree/bindings/graph.txt - properties: - '#address-cells': - const: 1 - - '#size-cells': - const: 0 + $ref: /schemas/graph.yaml#/properties/ports + properties: port@0: - type: object - description: | + $ref: /schemas/graph.yaml#/properties/port + description: Video port for DSI input port@1: - type: object - description: | + $ref: /schemas/graph.yaml#/properties/port + description: Video port for eDP output (panel or connector). required: - port@0 - additionalProperties: false - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,lvds.yaml b/Documentation/devicetree/bindings/display/bridge/renesas,lvds.yaml index e5b163951b91..acfc327f70a7 100644 --- a/Documentation/devicetree/bindings/display/bridge/renesas,lvds.yaml +++ b/Documentation/devicetree/bindings/display/bridge/renesas,lvds.yaml @@ -49,33 +49,21 @@ properties: maxItems: 1 ports: - type: object - description: | - This device has two video ports. Their connections are modelled using the - OF graph bindings specified in Documentation/devicetree/bindings/graph.txt. - Each port shall have a single endpoint. + $ref: /schemas/graph.yaml#/properties/ports properties: - '#address-cells': - const: 1 - - '#size-cells': - const: 0 - port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Parallel RGB input port port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: LVDS output port required: - port@0 - port@1 - additionalProperties: false - power-domains: maxItems: 1 @@ -83,9 +71,9 @@ properties: $ref: /schemas/types.yaml#/definitions/phandle description: phandle to the companion LVDS encoder. This property is mandatory - for the first LVDS encoder on D3 and E3 SoCs, and shall point to - the second encoder to be used as a companion in dual-link mode. It - shall not be set for any other LVDS encoder. + for the first LVDS encoder on R-Car D3 and E3, and RZ/G2E SoCs, and shall + point to the second encoder to be used as a companion in dual-link mode. + It shall not be set for any other LVDS encoder. required: - compatible diff --git a/Documentation/devicetree/bindings/display/bridge/simple-bridge.yaml b/Documentation/devicetree/bindings/display/bridge/simple-bridge.yaml index 64e8a1c24b40..6c7b577fd471 100644 --- a/Documentation/devicetree/bindings/display/bridge/simple-bridge.yaml +++ b/Documentation/devicetree/bindings/display/bridge/simple-bridge.yaml @@ -30,31 +30,21 @@ properties: - ti,ths8135 ports: - type: object - description: | - This device has two video ports. Their connections are modeled using the - OF graph bindings specified in Documentation/devicetree/bindings/graph.txt. - properties: - '#address-cells': - const: 1 - - '#size-cells': - const: 0 + $ref: /schemas/graph.yaml#/properties/ports + properties: port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: The bridge input port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: The bridge output required: - port@0 - port@1 - additionalProperties: false - enable-gpios: maxItems: 1 description: GPIO controlling bridge enable diff --git a/Documentation/devicetree/bindings/display/bridge/snps,dw-mipi-dsi.yaml b/Documentation/devicetree/bindings/display/bridge/snps,dw-mipi-dsi.yaml index e42cb610f545..3c3e51af154b 100644 --- a/Documentation/devicetree/bindings/display/bridge/snps,dw-mipi-dsi.yaml +++ b/Documentation/devicetree/bindings/display/bridge/snps,dw-mipi-dsi.yaml @@ -47,14 +47,15 @@ properties: const: apb ports: - type: object + $ref: /schemas/graph.yaml#/properties/ports properties: port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Input node to receive pixel data. + port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: DSI output node to panel. required: diff --git a/Documentation/devicetree/bindings/display/bridge/thine,thc63lvd1024.yaml b/Documentation/devicetree/bindings/display/bridge/thine,thc63lvd1024.yaml index 3d5ce08a5792..8ae382429d2b 100644 --- a/Documentation/devicetree/bindings/display/bridge/thine,thc63lvd1024.yaml +++ b/Documentation/devicetree/bindings/display/bridge/thine,thc63lvd1024.yaml @@ -25,46 +25,41 @@ properties: const: thine,thc63lvd1024 ports: - type: object + $ref: /schemas/graph.yaml#/properties/ports description: | - This device has four video ports. Their connections are modeled using the - OF graph bindings specified in Documentation/devicetree/bindings/graph.txt. + The device can operate in single or dual input and output modes. - The device can operate in single-link mode or dual-link mode. In - single-link mode, all pixels are received on port@0, and port@1 shall not - contain any endpoint. In dual-link mode, even-numbered pixels are - received on port@0 and odd-numbered pixels on port@1, and both port@0 and - port@1 shall contain endpoints. + When operating in single input mode, all pixels are received on port@0, + and port@1 shall not contain any endpoint. In dual input mode, + even-numbered pixels are received on port@0 and odd-numbered pixels on + port@1, and both port@0 and port@1 shall contain endpoints. - properties: - '#address-cells': - const: 1 - - '#size-cells': - const: 0 + When operating in single output mode all pixels are output from the first + CMOS/TTL port and port@3 shall not contain any endpoint. In dual output + mode pixels are output from both CMOS/TTL ports and both port@2 and + port@3 shall contain endpoints. + properties: port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: First LVDS input port port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Second LVDS input port port@2: - type: object + $ref: /schemas/graph.yaml#/properties/port description: First digital CMOS/TTL parallel output port@3: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Second digital CMOS/TTL parallel output required: - port@0 - port@2 - additionalProperties: false - oe-gpios: maxItems: 1 description: Output enable GPIO signal, pin name "OE", active high. diff --git a/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml b/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml index f8622bd0f61e..26932d2e86ab 100644 --- a/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml +++ b/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml @@ -71,54 +71,26 @@ properties: description: See ../../pwm/pwm.yaml for description of the cell formats. ports: - type: object - additionalProperties: false + $ref: /schemas/graph.yaml#/properties/ports properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - port@0: - type: object - additionalProperties: false - + $ref: /schemas/graph.yaml#/properties/port description: Video port for MIPI DSI input - properties: - reg: - const: 0 - - endpoint: - type: object - additionalProperties: false - properties: - remote-endpoint: true - - required: - - reg - port@1: - type: object - additionalProperties: false - + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: Video port for eDP output (panel or connector). properties: - reg: - const: 1 - endpoint: - type: object - additionalProperties: false + $ref: /schemas/graph.yaml#/$defs/endpoint-base + unevaluatedProperties: false properties: - remote-endpoint: true - data-lanes: oneOf: - minItems: 1 @@ -171,12 +143,7 @@ properties: dependencies: lane-polarities: [data-lanes] - required: - - reg - required: - - "#address-cells" - - "#size-cells" - port@0 - port@1 diff --git a/Documentation/devicetree/bindings/display/bridge/ti,tfp410.yaml b/Documentation/devicetree/bindings/display/bridge/ti,tfp410.yaml index 605831c1e836..4c5dd8ec2951 100644 --- a/Documentation/devicetree/bindings/display/bridge/ti,tfp410.yaml +++ b/Documentation/devicetree/bindings/display/bridge/ti,tfp410.yaml @@ -31,23 +31,18 @@ properties: maximum: 7 ports: - description: - A node containing input and output port nodes with endpoint - definitions as documented in - Documentation/devicetree/bindings/media/video-interfaces.txt - type: object + $ref: /schemas/graph.yaml#/properties/ports properties: port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: DPI input port. - type: object properties: - reg: - const: 0 - endpoint: - type: object + $ref: /schemas/graph.yaml#/$defs/endpoint-base + unevaluatedProperties: false properties: pclk-sample: @@ -67,15 +62,8 @@ properties: default: 24 port@1: + $ref: /schemas/graph.yaml#/properties/port description: DVI output port. - type: object - - properties: - reg: - const: 1 - - endpoint: - type: object required: - port@0 diff --git a/Documentation/devicetree/bindings/display/bridge/toshiba,tc358762.yaml b/Documentation/devicetree/bindings/display/bridge/toshiba,tc358762.yaml index 195025e6803c..5216c27fc0ad 100644 --- a/Documentation/devicetree/bindings/display/bridge/toshiba,tc358762.yaml +++ b/Documentation/devicetree/bindings/display/bridge/toshiba,tc358762.yaml @@ -25,62 +25,20 @@ properties: description: Regulator for 1.2V internal core power. ports: - type: object + $ref: /schemas/graph.yaml#/properties/ports properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - port@0: - type: object - additionalProperties: false - - description: | + $ref: /schemas/graph.yaml#/properties/port + description: Video port for MIPI DSI input - properties: - reg: - const: 0 - - patternProperties: - endpoint: - type: object - additionalProperties: false - - properties: - remote-endpoint: true - - required: - - reg - port@1: - type: object - additionalProperties: false - - description: | + $ref: /schemas/graph.yaml#/properties/port + description: Video port for MIPI DPI output (panel or connector). - properties: - reg: - const: 1 - - patternProperties: - endpoint: - type: object - additionalProperties: false - - properties: - remote-endpoint: true - - required: - - reg - required: - - "#address-cells" - - "#size-cells" - port@0 - port@1 diff --git a/Documentation/devicetree/bindings/display/bridge/toshiba,tc358768.yaml b/Documentation/devicetree/bindings/display/bridge/toshiba,tc358768.yaml index c036a75db8f7..eacfe7165083 100644 --- a/Documentation/devicetree/bindings/display/bridge/toshiba,tc358768.yaml +++ b/Documentation/devicetree/bindings/display/bridge/toshiba,tc358768.yaml @@ -42,65 +42,30 @@ properties: const: refclk ports: - type: object + $ref: /schemas/graph.yaml#/properties/ports properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - port@0: - type: object - additionalProperties: false - + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: | Video port for RGB input properties: - reg: - const: 0 - - patternProperties: endpoint: - type: object - additionalProperties: false + $ref: /schemas/graph.yaml#/$defs/endpoint-base + unevaluatedProperties: false properties: data-lines: enum: [ 16, 18, 24 ] - remote-endpoint: true - - required: - - reg - port@1: - type: object - additionalProperties: false - + $ref: /schemas/graph.yaml#/properties/port description: | Video port for DSI output (panel or connector). - properties: - reg: - const: 1 - - patternProperties: - endpoint: - type: object - additionalProperties: false - - properties: - remote-endpoint: true - - required: - - reg - required: - - "#address-cells" - - "#size-cells" - port@0 - port@1 @@ -156,4 +121,3 @@ examples: }; }; }; - diff --git a/Documentation/devicetree/bindings/display/bridge/toshiba,tc358775.yaml b/Documentation/devicetree/bindings/display/bridge/toshiba,tc358775.yaml index b5959cc78b8d..10471c6c1ff9 100644 --- a/Documentation/devicetree/bindings/display/bridge/toshiba,tc358775.yaml +++ b/Documentation/devicetree/bindings/display/bridge/toshiba,tc358775.yaml @@ -42,31 +42,22 @@ properties: description: Hardware reset, Low active ports: - type: object - description: - A node containing input and output port nodes with endpoint definitions - as documented in - Documentation/devicetree/bindings/media/video-interfaces.txt - properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 + $ref: /schemas/graph.yaml#/properties/ports + properties: port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | DSI Input. The remote endpoint phandle should be a reference to a valid mipi_dsi_host device node. port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Video port for LVDS output (panel or connector). port@2: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Video port for Dual link LVDS output (panel or connector). diff --git a/Documentation/devicetree/bindings/display/connector/analog-tv-connector.yaml b/Documentation/devicetree/bindings/display/connector/analog-tv-connector.yaml index eebe88fed999..a31ca2d52b86 100644 --- a/Documentation/devicetree/bindings/display/connector/analog-tv-connector.yaml +++ b/Documentation/devicetree/bindings/display/connector/analog-tv-connector.yaml @@ -25,6 +25,7 @@ properties: $ref: /schemas/types.yaml#/definitions/uint32 port: + $ref: /schemas/graph.yaml#/properties/port description: Connection to controller providing analog TV signals required: diff --git a/Documentation/devicetree/bindings/display/connector/dp-connector.yaml b/Documentation/devicetree/bindings/display/connector/dp-connector.yaml new file mode 100644 index 000000000000..1c17d60e7760 --- /dev/null +++ b/Documentation/devicetree/bindings/display/connector/dp-connector.yaml @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/connector/dp-connector.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: DisplayPort Connector + +maintainers: + - Tomi Valkeinen <tomi.valkeinen@ti.com> + +properties: + compatible: + const: dp-connector + + label: true + + type: + enum: + - full-size + - mini + + hpd-gpios: + description: A GPIO line connected to HPD + maxItems: 1 + + dp-pwr-supply: + description: Power supply for the DP_PWR pin + maxItems: 1 + + port: + $ref: /schemas/graph.yaml#/properties/port + description: Connection to controller providing DP signals + +required: + - compatible + - type + - port + +additionalProperties: false + +examples: + - | + connector { + compatible = "dp-connector"; + label = "dp0"; + type = "full-size"; + + port { + dp_connector_in: endpoint { + remote-endpoint = <&dp_out>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/connector/dvi-connector.yaml b/Documentation/devicetree/bindings/display/connector/dvi-connector.yaml index 71cb9220fa59..93eb14294e68 100644 --- a/Documentation/devicetree/bindings/display/connector/dvi-connector.yaml +++ b/Documentation/devicetree/bindings/display/connector/dvi-connector.yaml @@ -36,6 +36,7 @@ properties: description: the connector has pins for DVI dual-link port: + $ref: /schemas/graph.yaml#/properties/port description: Connection to controller providing DVI signals required: diff --git a/Documentation/devicetree/bindings/display/connector/hdmi-connector.yaml b/Documentation/devicetree/bindings/display/connector/hdmi-connector.yaml index 14d7128af592..83c0d008265b 100644 --- a/Documentation/devicetree/bindings/display/connector/hdmi-connector.yaml +++ b/Documentation/devicetree/bindings/display/connector/hdmi-connector.yaml @@ -37,6 +37,7 @@ properties: maxItems: 1 port: + $ref: /schemas/graph.yaml#/properties/port description: Connection to controller providing HDMI signals required: diff --git a/Documentation/devicetree/bindings/display/connector/vga-connector.yaml b/Documentation/devicetree/bindings/display/connector/vga-connector.yaml index 5782c4bb3252..25f868002000 100644 --- a/Documentation/devicetree/bindings/display/connector/vga-connector.yaml +++ b/Documentation/devicetree/bindings/display/connector/vga-connector.yaml @@ -20,6 +20,7 @@ properties: $ref: /schemas/types.yaml#/definitions/phandle port: + $ref: /schemas/graph.yaml#/properties/port description: Connection to controller providing VGA signals required: diff --git a/Documentation/devicetree/bindings/display/imx/nxp,imx8mq-dcss.yaml b/Documentation/devicetree/bindings/display/imx/nxp,imx8mq-dcss.yaml index f1f25aa794d9..0091df9dd73b 100644 --- a/Documentation/devicetree/bindings/display/imx/nxp,imx8mq-dcss.yaml +++ b/Documentation/devicetree/bindings/display/imx/nxp,imx8mq-dcss.yaml @@ -74,7 +74,7 @@ properties: - description: Must be 400 MHz port: - type: object + $ref: /schemas/graph.yaml#/properties/port description: A port node pointing to the input port of a HDMI/DP or MIPI display bridge. diff --git a/Documentation/devicetree/bindings/display/ingenic,ipu.yaml b/Documentation/devicetree/bindings/display/ingenic,ipu.yaml index 12064a8e7a92..e679f48a3886 100644 --- a/Documentation/devicetree/bindings/display/ingenic,ipu.yaml +++ b/Documentation/devicetree/bindings/display/ingenic,ipu.yaml @@ -31,9 +31,8 @@ properties: clock-names: const: ipu -patternProperties: - "^ports?$": - description: OF graph bindings (specified in bindings/graph.txt). + port: + $ref: /schemas/graph.yaml#/properties/port required: - compatible diff --git a/Documentation/devicetree/bindings/display/ingenic,lcd.yaml b/Documentation/devicetree/bindings/display/ingenic,lcd.yaml index 768050f30dba..50d2b0a50e8a 100644 --- a/Documentation/devicetree/bindings/display/ingenic,lcd.yaml +++ b/Documentation/devicetree/bindings/display/ingenic,lcd.yaml @@ -39,18 +39,18 @@ properties: minItems: 1 port: - description: OF graph bindings (specified in bindings/graph.txt). + $ref: /schemas/graph.yaml#/properties/port ports: - description: OF graph bindings (specified in bindings/graph.txt). - type: object + $ref: /schemas/graph.yaml#/properties/ports + properties: port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: DPI output, to interface with TFT panels. port@8: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Link to the Image Processing Unit (IPU). (See ingenic,ipu.yaml). diff --git a/Documentation/devicetree/bindings/display/intel,keembay-display.yaml b/Documentation/devicetree/bindings/display/intel,keembay-display.yaml index 0a697d45c2ad..bc6622b010ca 100644 --- a/Documentation/devicetree/bindings/display/intel,keembay-display.yaml +++ b/Documentation/devicetree/bindings/display/intel,keembay-display.yaml @@ -36,7 +36,7 @@ properties: maxItems: 1 port: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Display output node to DSI. required: diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt b/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt index ed76332ec01e..93b160df3eec 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt @@ -37,13 +37,14 @@ Required properties (all function blocks): "mediatek,<chip>-disp-aal" - adaptive ambient light controller "mediatek,<chip>-disp-gamma" - gamma correction "mediatek,<chip>-disp-merge" - merge streams from two RDMA sources + "mediatek,<chip>-disp-postmask" - control round corner for display frame "mediatek,<chip>-disp-split" - split stream to two encoders "mediatek,<chip>-disp-ufoe" - data compression engine "mediatek,<chip>-dsi" - DSI controller, see mediatek,dsi.txt "mediatek,<chip>-dpi" - DPI controller, see mediatek,dpi.txt "mediatek,<chip>-disp-mutex" - display mutex "mediatek,<chip>-disp-od" - overdrive - the supported chips are mt2701, mt7623, mt2712, mt8167 and mt8173. + the supported chips are mt2701, mt7623, mt2712, mt8167, mt8173, mt8183 and mt8192. - reg: Physical base address and length of the function block register space - interrupts: The interrupt signal from the function block (required, except for merge and split function blocks). @@ -66,6 +67,14 @@ Required properties (DMA function blocks): argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.txt for details. +Optional properties (RDMA function blocks): +- mediatek,rdma-fifo-size: rdma fifo size may be different even in same SOC, add this + property to the corresponding rdma + the value is the Max value which defined in hardware data sheet. + mediatek,rdma-fifo-size of mt8173-rdma0 is 8K + mediatek,rdma-fifo-size of mt8183-rdma0 is 5K + mediatek,rdma-fifo-size of mt8183-rdma1 is 2K + Examples: mmsys: clock-controller@14000000 { @@ -103,6 +112,7 @@ rdma0: rdma@1400e000 { clocks = <&mmsys CLK_MM_DISP_RDMA0>; iommus = <&iommu M4U_PORT_DISP_RDMA0>; mediatek,larb = <&larb0>; + mediatek,rdma-fifosize = <8192>; }; rdma1: rdma@1400f000 { diff --git a/Documentation/devicetree/bindings/display/panel/advantech,idk-2121wr.yaml b/Documentation/devicetree/bindings/display/panel/advantech,idk-2121wr.yaml index 6b7fddc80c41..67682fe77f10 100644 --- a/Documentation/devicetree/bindings/display/panel/advantech,idk-2121wr.yaml +++ b/Documentation/devicetree/bindings/display/panel/advantech,idk-2121wr.yaml @@ -37,34 +37,33 @@ properties: panel-timing: true ports: - type: object + $ref: /schemas/graph.yaml#/properties/ports + properties: port@0: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: The sink for odd pixels. properties: - reg: - const: 0 - dual-lvds-odd-pixels: true required: - - reg - dual-lvds-odd-pixels port@1: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: The sink for even pixels. properties: - reg: - const: 1 - dual-lvds-even-pixels: true required: - - reg - dual-lvds-even-pixels + required: + - port@0 + - port@1 + additionalProperties: false required: diff --git a/Documentation/devicetree/bindings/display/panel/mantix,mlaf057we51-x.yaml b/Documentation/devicetree/bindings/display/panel/mantix,mlaf057we51-x.yaml index 51f423297ec8..9e78f2e60f99 100644 --- a/Documentation/devicetree/bindings/display/panel/mantix,mlaf057we51-x.yaml +++ b/Documentation/devicetree/bindings/display/panel/mantix,mlaf057we51-x.yaml @@ -20,6 +20,7 @@ properties: compatible: enum: - mantix,mlaf057we51-x + - ys,ys57pss36bh5gq port: true reg: diff --git a/Documentation/devicetree/bindings/display/panel/panel-common.yaml b/Documentation/devicetree/bindings/display/panel/panel-common.yaml index cd6dc5461721..5b38dc89cb21 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-common.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-common.yaml @@ -68,16 +68,7 @@ properties: # Connectivity port: - type: object - - ports: - type: object - description: - Panels receive video data through one or multiple connections. While - the nature of those connections is specific to the panel type, the - connectivity is expressed in a standard fashion using ports as specified - in the device graph bindings defined in - Documentation/devicetree/bindings/graph.txt. + $ref: /schemas/graph.yaml#/properties/port ddc-i2c-bus: $ref: /schemas/types.yaml#/definitions/phandle diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml index 72e4b6d4d5e1..fbd71669248f 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml @@ -35,6 +35,8 @@ properties: - boe,tv080wum-nl0 # Innolux P079ZCA 7.85" 768x1024 TFT LCD panel - innolux,p079zca + # Khadas TS050 5" 1080x1920 LCD panel + - khadas,ts050 # Kingdisplay KD097D04 9.7" 1536x2048 TFT LCD panel - kingdisplay,kd097d04 # LG ACX467AKM-7 4.95" 1080×1920 LCD Panel diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml index 27fffafe5b5c..62b0d54d87b7 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -76,6 +76,8 @@ properties: # BOE OPTOELECTRONICS TECHNOLOGY 10.1" WXGA TFT LCD panel - boe,nv101wxmn51 # BOE NV133FHM-N61 13.3" FHD (1920x1080) TFT LCD Panel + - boe,nv110wtm-n61 + # BOE NV110WTM-N61 11.0" 2160x1440 TFT LCD Panel - boe,nv133fhm-n61 # BOE NV133FHM-N62 13.3" FHD (1920x1080) TFT LCD Panel - boe,nv133fhm-n62 @@ -105,26 +107,27 @@ properties: - dlc,dlc1010gig # Emerging Display Technology Corp. 3.5" QVGA TFT LCD panel - edt,et035012dm6 + # Emerging Display Technology Corp. 5.7" VGA TFT LCD panel + - edt,et057090dhu + - edt,et070080dh6 # Emerging Display Technology Corp. 480x272 TFT Display with capacitive touch - edt,etm043080dh6gp # Emerging Display Technology Corp. 480x272 TFT Display - edt,etm0430g0dh6 - # Emerging Display Technology Corp. 5.7" VGA TFT LCD panel - - edt,et057090dhu - # Emerging Display Technology Corp. WVGA TFT Display with capacitive touch - - edt,etm070080dh6 - # Emerging Display Technology Corp. WVGA TFT Display with capacitive touch - - edt,etm0700g0dh6 # Emerging Display Technology Corp. WVGA TFT Display with capacitive touch # Same as ETM0700G0DH6 but with inverted pixel clock. - edt,etm070080bdh6 # Emerging Display Technology Corp. WVGA TFT Display with capacitive touch + # Same timings as the ETM0700G0DH6, but with resistive touch. + - edt,etm070080dh6 + # Emerging Display Technology Corp. WVGA TFT Display with capacitive touch # Same display as the ETM0700G0BDH6, but with changed hardware for the # backlight and the touch interface. - edt,etm070080edh6 + - edt,etm0700g0bdh6 # Emerging Display Technology Corp. WVGA TFT Display with capacitive touch - # Same timings as the ETM0700G0DH6, but with resistive touch. - - edt,etm070080dh6 + - edt,etm0700g0dh6 + - edt,etm0700g0edh6 # Evervision Electronics Co. Ltd. VGG804821 5.0" WVGA TFT LCD Panel - evervision,vgg804821 # Foxlink Group 5" WVGA TFT LCD panel @@ -173,6 +176,8 @@ properties: - koe,tx26d202vm0bwa # Kaohsiung Opto-Electronics. TX31D200VM0BAA 12.3" HSXGA LVDS panel - koe,tx31d200vm0baa + # Kyocera Corporation 7" WVGA (800x480) transmissive color TFT + - kyo,tcg070wvlq # Kyocera Corporation 12.1" XGA (1024x768) TFT LCD panel - kyo,tcg121xglp # LeMaker BL035-RGB-002 3.5" QVGA TFT LCD panel diff --git a/Documentation/devicetree/bindings/display/panel/samsung,s6e63m0.yaml b/Documentation/devicetree/bindings/display/panel/samsung,s6e63m0.yaml index 1dab80ae1d0a..ea58df49263a 100644 --- a/Documentation/devicetree/bindings/display/panel/samsung,s6e63m0.yaml +++ b/Documentation/devicetree/bindings/display/panel/samsung,s6e63m0.yaml @@ -11,6 +11,7 @@ maintainers: allOf: - $ref: panel-common.yaml# + - $ref: /schemas/leds/backlight/common.yaml# properties: compatible: @@ -19,6 +20,8 @@ properties: reg: true reset-gpios: true port: true + default-brightness: true + max-brightness: true vdd3-supply: description: VDD regulator @@ -31,7 +34,6 @@ required: - reset-gpios - vdd3-supply - vci-supply - - port unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip,rk3066-hdmi.yaml b/Documentation/devicetree/bindings/display/rockchip/rockchip,rk3066-hdmi.yaml index 4110d003ce1f..008c144257cb 100644 --- a/Documentation/devicetree/bindings/display/rockchip/rockchip,rk3066-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip,rk3066-hdmi.yaml @@ -43,34 +43,24 @@ properties: This soc uses GRF regs to switch the HDMI TX input between vop0 and vop1. ports: - type: object + $ref: /schemas/graph.yaml#/properties/ports properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Port node with two endpoints, numbered 0 and 1, connected respectively to vop0 and vop1. port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Port node with one endpoint connected to a hdmi-connector node. required: - - "#address-cells" - - "#size-cells" - port@0 - port@1 - additionalProperties: false - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.yaml b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.yaml index ed8148e26e24..6f43d885c9b3 100644 --- a/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.yaml +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.yaml @@ -70,10 +70,7 @@ properties: - const: dclk port: - type: object - description: - A port node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. + $ref: /schemas/graph.yaml#/properties/port assigned-clocks: maxItems: 2 diff --git a/Documentation/devicetree/bindings/display/st,stm32-dsi.yaml b/Documentation/devicetree/bindings/display/st,stm32-dsi.yaml index 327a14d85df8..679daed4124e 100644 --- a/Documentation/devicetree/bindings/display/st,stm32-dsi.yaml +++ b/Documentation/devicetree/bindings/display/st,stm32-dsi.yaml @@ -51,20 +51,16 @@ properties: Phandle of the regulator that provides the supply voltage. ports: - type: object - description: - A node containing DSI input & output port nodes with endpoint - definitions as documented in - Documentation/devicetree/bindings/media/video-interfaces.txt - Documentation/devicetree/bindings/graph.txt + $ref: /schemas/graph.yaml#/properties/ports + properties: port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: DSI input port node, connected to the ltdc rgb output port. port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: DSI output port node, connected to a panel or a bridge input port" diff --git a/Documentation/devicetree/bindings/display/st,stm32-ltdc.yaml b/Documentation/devicetree/bindings/display/st,stm32-ltdc.yaml index bf8ad916e9b0..d54f9ca207af 100644 --- a/Documentation/devicetree/bindings/display/st,stm32-ltdc.yaml +++ b/Documentation/devicetree/bindings/display/st,stm32-ltdc.yaml @@ -35,15 +35,13 @@ properties: maxItems: 1 port: - type: object - description: - "Video port for DPI RGB output. + $ref: /schemas/graph.yaml#/properties/port + description: | + Video port for DPI RGB output. ltdc has one video port with up to 2 endpoints: - for external dpi rgb panel or bridge, using gpios. - for internal dpi input of the MIPI DSI host controller. Note: These 2 endpoints cannot be activated simultaneously. - Please refer to the bindings defined in - Documentation/devicetree/bindings/media/video-interfaces.txt." required: - compatible diff --git a/Documentation/devicetree/bindings/display/ste,mcde.txt b/Documentation/devicetree/bindings/display/ste,mcde.txt deleted file mode 100644 index 4c33c692bd5f..000000000000 --- a/Documentation/devicetree/bindings/display/ste,mcde.txt +++ /dev/null @@ -1,104 +0,0 @@ -ST-Ericsson Multi Channel Display Engine MCDE - -The ST-Ericsson MCDE is a display controller with support for compositing -and displaying several channels memory resident graphics data on DSI or -LCD displays or bridges. It is used in the ST-Ericsson U8500 platform. - -Required properties: - -- compatible: must be: - "ste,mcde" -- reg: register base for the main MCDE control registers, should be - 0x1000 in size -- interrupts: the interrupt line for the MCDE -- epod-supply: a phandle to the EPOD regulator -- vana-supply: a phandle to the analog voltage regulator -- clocks: an array of the MCDE clocks in this strict order: - MCDECLK (main MCDE clock), LCDCLK (LCD clock), PLLDSI - (HDMI clock), DSI0ESCLK (DSI0 energy save clock), - DSI1ESCLK (DSI1 energy save clock), DSI2ESCLK (DSI2 energy - save clock) -- clock-names: must be the following array: - "mcde", "lcd", "hdmi" - to match the required clock inputs above. -- #address-cells: should be <1> (for the DSI hosts that will be children) -- #size-cells: should be <1> (for the DSI hosts that will be children) -- ranges: this should always be stated - -Required subnodes: - -The devicetree must specify subnodes for the DSI host adapters. -These must have the following characteristics: - -- compatible: must be: - "ste,mcde-dsi" -- reg: must specify the register range for the DSI host -- vana-supply: phandle to the VANA voltage regulator -- clocks: phandles to the high speed and low power (energy save) clocks - the high speed clock is not present on the third (dsi2) block, so it - should only have the "lp" clock -- clock-names: "hs" for the high speed clock and "lp" for the low power - (energy save) clock -- #address-cells: should be <1> -- #size-cells: should be <0> - -Display panels and bridges will appear as children on the DSI hosts, and -the displays are connected to the DSI hosts using the common binding -for video transmitter interfaces; see -Documentation/devicetree/bindings/media/video-interfaces.txt - -If a DSI host is unused (not connected) it will have no children defined. - -Example: - -mcde@a0350000 { - compatible = "ste,mcde"; - reg = <0xa0350000 0x1000>; - interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>; - epod-supply = <&db8500_b2r2_mcde_reg>; - vana-supply = <&ab8500_ldo_ana_reg>; - clocks = <&prcmu_clk PRCMU_MCDECLK>, /* Main MCDE clock */ - <&prcmu_clk PRCMU_LCDCLK>, /* LCD clock */ - <&prcmu_clk PRCMU_PLLDSI>; /* HDMI clock */ - clock-names = "mcde", "lcd", "hdmi"; - #address-cells = <1>; - #size-cells = <1>; - ranges; - - dsi0: dsi@a0351000 { - compatible = "ste,mcde-dsi"; - reg = <0xa0351000 0x1000>; - vana-supply = <&ab8500_ldo_ana_reg>; - clocks = <&prcmu_clk PRCMU_DSI0CLK>, <&prcmu_clk PRCMU_DSI0ESCCLK>; - clock-names = "hs", "lp"; - #address-cells = <1>; - #size-cells = <0>; - - panel { - compatible = "samsung,s6d16d0"; - reg = <0>; - vdd1-supply = <&ab8500_ldo_aux1_reg>; - reset-gpios = <&gpio2 1 GPIO_ACTIVE_LOW>; - }; - - }; - dsi1: dsi@a0352000 { - compatible = "ste,mcde-dsi"; - reg = <0xa0352000 0x1000>; - vana-supply = <&ab8500_ldo_ana_reg>; - clocks = <&prcmu_clk PRCMU_DSI1CLK>, <&prcmu_clk PRCMU_DSI1ESCCLK>; - clock-names = "hs", "lp"; - #address-cells = <1>; - #size-cells = <0>; - }; - dsi2: dsi@a0353000 { - compatible = "ste,mcde-dsi"; - reg = <0xa0353000 0x1000>; - vana-supply = <&ab8500_ldo_ana_reg>; - /* This DSI port only has the Low Power / Energy Save clock */ - clocks = <&prcmu_clk PRCMU_DSI2ESCCLK>; - clock-names = "lp"; - #address-cells = <1>; - #size-cells = <0>; - }; -}; diff --git a/Documentation/devicetree/bindings/display/ste,mcde.yaml b/Documentation/devicetree/bindings/display/ste,mcde.yaml new file mode 100644 index 000000000000..de0c678b3c29 --- /dev/null +++ b/Documentation/devicetree/bindings/display/ste,mcde.yaml @@ -0,0 +1,168 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/ste,mcde.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ST-Ericsson Multi Channel Display Engine MCDE + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +properties: + compatible: + const: ste,mcde + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + description: an array of the MCDE clocks + items: + - description: MCDECLK (main MCDE clock) + - description: LCDCLK (LCD clock) + - description: PLLDSI (HDMI clock) + + clock-names: + items: + - const: mcde + - const: lcd + - const: hdmi + + resets: + maxItems: 1 + + epod-supply: + description: a phandle to the EPOD regulator + + vana-supply: + description: a phandle to the analog voltage regulator + + port: + $ref: /schemas/graph.yaml#/properties/port + description: + A DPI port node + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + ranges: true + +patternProperties: + "^dsi@[0-9a-f]+$": + description: subnodes for the three DSI host adapters + type: object + allOf: + - $ref: dsi-controller.yaml# + properties: + compatible: + const: ste,mcde-dsi + + reg: + maxItems: 1 + + vana-supply: + description: a phandle to the analog voltage regulator + + clocks: + description: phandles to the high speed and low power (energy save) clocks + the high speed clock is not present on the third (dsi2) block, so it + should only have the "lp" clock + minItems: 1 + maxItems: 2 + + clock-names: + oneOf: + - items: + - const: hs + - const: lp + - items: + - const: lp + + required: + - compatible + - reg + - vana-supply + - clocks + - clock-names + + unevaluatedProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - epod-supply + - vana-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/mfd/dbx500-prcmu.h> + #include <dt-bindings/gpio/gpio.h> + + mcde@a0350000 { + compatible = "ste,mcde"; + reg = <0xa0350000 0x1000>; + interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>; + epod-supply = <&db8500_b2r2_mcde_reg>; + vana-supply = <&ab8500_ldo_ana_reg>; + clocks = <&prcmu_clk PRCMU_MCDECLK>, + <&prcmu_clk PRCMU_LCDCLK>, + <&prcmu_clk PRCMU_PLLDSI>; + clock-names = "mcde", "lcd", "hdmi"; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + dsi0: dsi@a0351000 { + compatible = "ste,mcde-dsi"; + reg = <0xa0351000 0x1000>; + vana-supply = <&ab8500_ldo_ana_reg>; + clocks = <&prcmu_clk PRCMU_DSI0CLK>, <&prcmu_clk PRCMU_DSI0ESCCLK>; + clock-names = "hs", "lp"; + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "samsung,s6d16d0"; + reg = <0>; + vdd1-supply = <&ab8500_ldo_aux1_reg>; + reset-gpios = <&gpio2 1 GPIO_ACTIVE_LOW>; + }; + }; + + dsi1: dsi@a0352000 { + compatible = "ste,mcde-dsi"; + reg = <0xa0352000 0x1000>; + vana-supply = <&ab8500_ldo_ana_reg>; + clocks = <&prcmu_clk PRCMU_DSI1CLK>, <&prcmu_clk PRCMU_DSI1ESCCLK>; + clock-names = "hs", "lp"; + #address-cells = <1>; + #size-cells = <0>; + }; + + dsi2: dsi@a0353000 { + compatible = "ste,mcde-dsi"; + reg = <0xa0353000 0x1000>; + vana-supply = <&ab8500_ldo_ana_reg>; + /* This DSI port only has the Low Power / Energy Save clock */ + clocks = <&prcmu_clk PRCMU_DSI2ESCCLK>; + clock-names = "lp"; + #address-cells = <1>; + #size-cells = <0>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt index 34d993338453..8a6d3e1ee306 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt @@ -111,8 +111,8 @@ of the following host1x client modules: endpoint (required node) Required properties: - - data-lanes: an array of data lane from 1 to 4. Valid array - lengths are 1/2/4. + - data-lanes: an array of data lane from 1 to 8. Valid array + lengths are 1/2/4/8. - remote-endpoint: phandle to sensor 'endpoint' node. port@1 (required node) diff --git a/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml b/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml index 4dc30738ee57..781c1868b0b8 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml +++ b/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml @@ -74,30 +74,19 @@ properties: type: boolean ports: - type: object - description: - Ports as described in Documentation/devicetree/bindings/graph.txt - properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 + $ref: /schemas/graph.yaml#/properties/ports + properties: port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: The DSS OLDI output port node form video port 1 port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: The DSS DPI output port node from video port 2 - required: - - "#address-cells" - - "#size-cells" - ti,am65x-oldi-io-ctrl: $ref: "/schemas/types.yaml#/definitions/phandle-array" maxItems: 1 diff --git a/Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml b/Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml index c9a947d55fa4..2986f9acc9f0 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml +++ b/Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml @@ -107,40 +107,29 @@ properties: type: boolean ports: - type: object - description: - Ports as described in Documentation/devicetree/bindings/graph.txt - properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 + $ref: /schemas/graph.yaml#/properties/ports + properties: port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: The output port node form video port 1 port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: The output port node from video port 2 port@2: - type: object + $ref: /schemas/graph.yaml#/properties/port description: The output port node from video port 3 port@3: - type: object + $ref: /schemas/graph.yaml#/properties/port description: The output port node from video port 4 - required: - - "#address-cells" - - "#size-cells" - max-memory-bandwidth: $ref: /schemas/types.yaml#/definitions/uint32 description: diff --git a/Documentation/devicetree/bindings/display/ti/ti,k2g-dss.yaml b/Documentation/devicetree/bindings/display/ti/ti,k2g-dss.yaml index 8f87b82c6695..7ce7bbad5780 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,k2g-dss.yaml +++ b/Documentation/devicetree/bindings/display/ti/ti,k2g-dss.yaml @@ -54,9 +54,8 @@ properties: description: phandle to the associated power domain port: - type: object + $ref: /schemas/graph.yaml#/properties/port description: - Port as described in Documentation/devicetree/bindings/graph.txt. The DSS DPI output port node max-memory-bandwidth: diff --git a/Documentation/devicetree/bindings/eeprom/at24.yaml b/Documentation/devicetree/bindings/eeprom/at24.yaml index d5117c638b75..021d8ae42da3 100644 --- a/Documentation/devicetree/bindings/eeprom/at24.yaml +++ b/Documentation/devicetree/bindings/eeprom/at24.yaml @@ -96,9 +96,6 @@ properties: # These are special cases that don't conform to the above pattern. # Each requires a standard at24 model as fallback. - items: - - const: rohm,br24t01 - - const: atmel,24c01 - - items: - const: nxp,se97b - const: atmel,24c02 - items: @@ -113,6 +110,12 @@ properties: - items: - const: renesas,r1ex24128 - const: atmel,24c128 + - items: + - const: rohm,br24g01 + - const: atmel,24c01 + - items: + - const: rohm,br24t01 + - const: atmel,24c01 label: description: Descriptive name of the EEPROM. diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.txt b/Documentation/devicetree/bindings/firmware/qcom,scm.txt index 78456437df5f..a884955f861e 100644 --- a/Documentation/devicetree/bindings/firmware/qcom,scm.txt +++ b/Documentation/devicetree/bindings/firmware/qcom,scm.txt @@ -22,6 +22,8 @@ Required properties: * "qcom,scm-sc7180" * "qcom,scm-sdm845" * "qcom,scm-sm8150" + * "qcom,scm-sm8250" + * "qcom,scm-sm8350" and: * "qcom,scm" - clocks: Specifies clocks needed by the SCM interface, if any: diff --git a/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml b/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml index 4db3b8a3332c..9cf6137dd524 100644 --- a/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml @@ -82,8 +82,7 @@ properties: '#gpio-cells': const: 2 - gpio-ranges: - maxItems: 1 + gpio-ranges: true interrupts: true diff --git a/Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml b/Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml new file mode 100644 index 000000000000..3bc8e73dfbf0 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- + +$id: http://devicetree.org/schemas/hwmon/ti,tps23861.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI TPS23861 PoE PSE + +maintainers: + - Robert Marko <robert.marko@sartura.hr> + +description: | + The TPS23861 is a IEEE 802.3at Quad Port Power-over-Ethernet PSE Controller. + + Datasheets: + https://www.ti.com/lit/gpn/tps23861 + + +properties: + compatible: + enum: + - ti,tps23861 + + reg: + maxItems: 1 + + shunt-resistor-micro-ohms: + description: The value of curent sense resistor in microohms. + default: 255000 + minimum: 250000 + maximum: 255000 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + tps23861@30 { + compatible = "ti,tps23861"; + reg = <0x30>; + shunt-resistor-micro-ohms = <255000>; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-sirf.txt b/Documentation/devicetree/bindings/i2c/i2c-sirf.txt deleted file mode 100644 index 2701eefb00f7..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-sirf.txt +++ /dev/null @@ -1,19 +0,0 @@ -I2C for SiRFprimaII platforms - -Required properties : -- compatible : Must be "sirf,prima2-i2c" -- reg: physical base address of the controller and length of memory mapped - region. -- interrupts: interrupt number to the cpu. - -Optional properties: -- clock-frequency : Constains desired I2C/HS-I2C bus clock frequency in Hz. - The absence of the property indicates the default frequency 100 kHz. - -Examples : - -i2c0: i2c@b00e0000 { - compatible = "sirf,prima2-i2c"; - reg = <0xb00e0000 0x10000>; - interrupts = <24>; -}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-stu300.txt b/Documentation/devicetree/bindings/i2c/i2c-stu300.txt deleted file mode 100644 index bd81a482634f..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-stu300.txt +++ /dev/null @@ -1,15 +0,0 @@ -ST Microelectronics DDC I2C - -Required properties : -- compatible : Must be "st,ddci2c" -- reg: physical base address of the controller and length of memory mapped - region. -- interrupts: interrupt number to the cpu. -- #address-cells = <1>; -- #size-cells = <0>; - -Optional properties: -- Child nodes conforming to i2c bus binding - -Examples : - diff --git a/Documentation/devicetree/bindings/i2c/i2c-zx2967.txt b/Documentation/devicetree/bindings/i2c/i2c-zx2967.txt deleted file mode 100644 index cb806d1ae4c9..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-zx2967.txt +++ /dev/null @@ -1,22 +0,0 @@ -ZTE zx2967 I2C controller - -Required properties: - - compatible: must be "zte,zx296718-i2c" - - reg: physical address and length of the device registers - - interrupts: a single interrupt specifier - - clocks: clock for the device - - #address-cells: should be <1> - - #size-cells: should be <0> - - clock-frequency: the desired I2C bus clock frequency. - -Examples: - - i2c@112000 { - compatible = "zte,zx296718-i2c"; - reg = <0x00112000 0x1000>; - interrupts = <GIC_SPI 112 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&osc24m>; - #address-cells = <1> - #size-cells = <0>; - clock-frequency = <1600000>; - }; diff --git a/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml index 5b5ae402f97a..eb72dd571def 100644 --- a/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml @@ -18,21 +18,14 @@ properties: - const: allwinner,sun4i-a10-i2c - const: allwinner,sun6i-a31-i2c - items: - - const: allwinner,sun8i-a23-i2c + - enum: + - allwinner,sun8i-a23-i2c + - allwinner,sun8i-a83t-i2c + - allwinner,sun50i-a64-i2c + - allwinner,sun50i-a100-i2c + - allwinner,sun50i-h6-i2c + - allwinner,sun50i-h616-i2c - const: allwinner,sun6i-a31-i2c - - items: - - const: allwinner,sun8i-a83t-i2c - - const: allwinner,sun6i-a31-i2c - - items: - - const: allwinner,sun50i-a64-i2c - - const: allwinner,sun6i-a31-i2c - - items: - - const: allwinner,sun50i-a100-i2c - - const: allwinner,sun6i-a31-i2c - - items: - - const: allwinner,sun50i-h6-i2c - - const: allwinner,sun6i-a31-i2c - - const: marvell,mv64xxx-i2c - const: marvell,mv78230-i2c - const: marvell,mv78230-a0-i2c diff --git a/Documentation/devicetree/bindings/i2c/renesas,i2c.txt b/Documentation/devicetree/bindings/i2c/renesas,i2c.txt index 96d869ac3839..5762d2d1ab9c 100644 --- a/Documentation/devicetree/bindings/i2c/renesas,i2c.txt +++ b/Documentation/devicetree/bindings/i2c/renesas,i2c.txt @@ -26,6 +26,7 @@ Required properties: "renesas,i2c-r8a77980" if the device is a part of a R8A77980 SoC. "renesas,i2c-r8a77990" if the device is a part of a R8A77990 SoC. "renesas,i2c-r8a77995" if the device is a part of a R8A77995 SoC. + "renesas,i2c-r8a779a0" if the device is a part of a R8A779A0 SoC. "renesas,rcar-gen1-i2c" for a generic R-Car Gen1 compatible device. "renesas,rcar-gen2-i2c" for a generic R-Car Gen2 or RZ/G1 compatible device. diff --git a/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.yaml b/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.yaml index 5667d09dfe6a..fbb714431e3d 100644 --- a/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.yaml +++ b/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.yaml @@ -20,6 +20,9 @@ properties: reg: maxItems: 1 + vdd-supply: true + vddio-supply: true + mount-matrix: description: an optional 3x3 mounting rotation matrix. diff --git a/Documentation/devicetree/bindings/iio/adc/x-powers,axp209-adc.yaml b/Documentation/devicetree/bindings/iio/adc/x-powers,axp209-adc.yaml index 5ccbb1f81960..e759a5da708d 100644 --- a/Documentation/devicetree/bindings/iio/adc/x-powers,axp209-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/x-powers,axp209-adc.yaml @@ -46,10 +46,14 @@ description: | properties: compatible: - enum: - - x-powers,axp209-adc - - x-powers,axp221-adc - - x-powers,axp813-adc + oneOf: + - const: x-powers,axp209-adc + - const: x-powers,axp221-adc + - const: x-powers,axp813-adc + + - items: + - const: x-powers,axp803-adc + - const: x-powers,axp813-adc "#io-channel-cells": const: 1 diff --git a/Documentation/devicetree/bindings/iio/adc/xilinx-xadc.txt b/Documentation/devicetree/bindings/iio/adc/xilinx-xadc.txt index e0e0755cabd8..f42e18078376 100644 --- a/Documentation/devicetree/bindings/iio/adc/xilinx-xadc.txt +++ b/Documentation/devicetree/bindings/iio/adc/xilinx-xadc.txt @@ -1,13 +1,22 @@ Xilinx XADC device driver -This binding document describes the bindings for both of them since the -bindings are very similar. The Xilinx XADC is a ADC that can be found in the -series 7 FPGAs from Xilinx. The XADC has a DRP interface for communication. -Currently two different frontends for the DRP interface exist. One that is only -available on the ZYNQ family as a hardmacro in the SoC portion of the ZYNQ. The -other one is available on all series 7 platforms and is a softmacro with a AXI -interface. This binding document describes the bindings for both of them since -the bindings are very similar. +This binding document describes the bindings for the Xilinx 7 Series XADC as well +as the UltraScale/UltraScale+ System Monitor. + +The Xilinx XADC is an ADC that can be found in the Series 7 FPGAs from Xilinx. +The XADC has a DRP interface for communication. Currently two different +frontends for the DRP interface exist. One that is only available on the ZYNQ +family as a hardmacro in the SoC portion of the ZYNQ. The other one is available +on all series 7 platforms and is a softmacro with a AXI interface. This binding +document describes the bindings for both of them since the bindings are very +similar. + +The Xilinx System Monitor is an ADC that is found in the UltraScale and +UltraScale+ FPGAs from Xilinx. The System Monitor provides a DRP interface for +communication. Xilinx provides a standard IP core that can be used to access the +System Monitor through an AXI interface in the FPGA fabric. This IP core is +called the Xilinx System Management Wizard. This document describes the bindings +for this IP. Required properties: - compatible: Should be one of @@ -15,11 +24,14 @@ Required properties: configuration interface to interface to the XADC hardmacro. * "xlnx,axi-xadc-1.00.a": When using the axi-xadc pcore to interface to the XADC hardmacro. + * "xlnx,system-management-wiz-1.3": When using the + Xilinx System Management Wizard fabric IP core to access the + UltraScale and UltraScale+ System Monitor. - reg: Address and length of the register set for the device - interrupts: Interrupt for the XADC control interface. - clocks: When using the ZYNQ this must be the ZYNQ PCAP clock, - when using the AXI-XADC pcore this must be the clock that provides the - clock to the AXI bus interface of the core. + when using the axi-xadc or the axi-system-management-wizard this must be + the clock that provides the clock to the AXI bus interface of the core. Optional properties: - xlnx,external-mux: @@ -110,3 +122,20 @@ Examples: }; }; }; + + adc@80000000 { + compatible = "xlnx,system-management-wiz-1.3"; + reg = <0x80000000 0x1000>; + interrupts = <0 81 4>; + interrupt-parent = <&gic>; + clocks = <&fpga1_clk>; + + xlnx,channels { + #address-cells = <1>; + #size-cells = <0>; + channel@0 { + reg = <0>; + xlnx,bipolar; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5766.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5766.yaml new file mode 100644 index 000000000000..d5c54813ce87 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5766.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2020 Analog Devices Inc. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/adi,ad5766.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD5766 DAC device driver + +maintainers: + - Cristian Pop <cristian.pop@analog.com> + +description: | + Bindings for the Analog Devices AD5766 current DAC device. Datasheet can be + found here: + https://www.analog.com/media/en/technical-documentation/data-sheets/ad5766-5767.pdf + +properties: + compatible: + enum: + - adi,ad5766 + - adi,ad5767 + + output-range-microvolts: + description: Select converter output range. + + reg: + maxItems: 1 + + spi-max-frequency: + maximum: 1000000 + + spi-cpol: true + + reset-gpios: + description: GPIO spec for the RESET pin. As the line is active low, it + should be marked GPIO_ACTIVE_LOW. + maxItems: 1 + +required: + - compatible + - output-range-microvolts + - reg + - spi-max-frequency + - spi-cpol + +additionalProperties: false + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + ad5766@0 { + compatible = "adi,ad5766"; + output-range-microvolts = <(-5000) 5000>; + reg = <0>; + spi-cpol; + spi-max-frequency = <1000000>; + reset-gpios = <&gpio 22 0>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/dac/microchip,mcp4725.yaml b/Documentation/devicetree/bindings/iio/dac/microchip,mcp4725.yaml index 271998610ceb..5f5b578316bc 100644 --- a/Documentation/devicetree/bindings/iio/dac/microchip,mcp4725.yaml +++ b/Documentation/devicetree/bindings/iio/dac/microchip,mcp4725.yaml @@ -39,20 +39,39 @@ properties: allOf: - if: - not: - properties: - compatible: - contains: - const: microchip,mcp4726 + properties: + compatible: + contains: + const: microchip,mcp4725 then: properties: vref-supply: false + required: + - vdd-supply + + - if: + properties: + compatible: + contains: + const: microchip,mcp4726 + then: + anyOf: + - required: + - vdd-supply + - required: + - vref-supply + + - if: + not: + required: + - vref-supply + then: + properties: microchip,vref-buffered: false required: - compatible - reg - - vdd-supply additionalProperties: false diff --git a/Documentation/devicetree/bindings/iio/gyroscope/bosch,bmg160.yaml b/Documentation/devicetree/bindings/iio/gyroscope/bosch,bmg160.yaml index 0466483be6bb..b6bbc312a7cf 100644 --- a/Documentation/devicetree/bindings/iio/gyroscope/bosch,bmg160.yaml +++ b/Documentation/devicetree/bindings/iio/gyroscope/bosch,bmg160.yaml @@ -19,6 +19,9 @@ properties: reg: maxItems: 1 + vdd-supply: true + vddio-supply: true + interrupts: minItems: 1 description: diff --git a/Documentation/devicetree/bindings/iio/gyroscope/invensense,mpu3050.txt b/Documentation/devicetree/bindings/iio/gyroscope/invensense,mpu3050.txt deleted file mode 100644 index 233fe207aded..000000000000 --- a/Documentation/devicetree/bindings/iio/gyroscope/invensense,mpu3050.txt +++ /dev/null @@ -1,45 +0,0 @@ -Invensense MPU-3050 Gyroscope device tree bindings - -Required properties: - - compatible : should be "invensense,mpu3050" - - reg : the I2C address of the sensor - -Optional properties: - - interrupts : interrupt mapping for the trigger interrupt from the - internal oscillator. The following IRQ modes are supported: - IRQ_TYPE_EDGE_RISING, IRQ_TYPE_EDGE_FALLING, IRQ_TYPE_LEVEL_HIGH and - IRQ_TYPE_LEVEL_LOW. The driver should detect and configure the hardware - for the desired interrupt type. - - vdd-supply : supply regulator for the main power voltage. - - vlogic-supply : supply regulator for the signal voltage. - - mount-matrix : see iio/mount-matrix.txt - -Optional subnodes: - - The MPU-3050 will pass through and forward the I2C signals from the - incoming I2C bus, alternatively drive traffic to a slave device (usually - an accelerometer) on its own initiative. Therefore is supports a subnode - i2c gate node. For details see: i2c/i2c-gate.txt - -Example: - -mpu3050@68 { - compatible = "invensense,mpu3050"; - reg = <0x68>; - interrupt-parent = <&foo>; - interrupts = <12 IRQ_TYPE_EDGE_FALLING>; - vdd-supply = <&bar>; - vlogic-supply = <&baz>; - - /* External I2C interface */ - i2c-gate { - #address-cells = <1>; - #size-cells = <0>; - - fnord@18 { - compatible = "fnord"; - reg = <0x18>; - interrupt-parent = <&foo>; - interrupts = <13 IRQ_TYPE_EDGE_FALLING>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/iio/gyroscope/invensense,mpu3050.yaml b/Documentation/devicetree/bindings/iio/gyroscope/invensense,mpu3050.yaml new file mode 100644 index 000000000000..7e2accc3d5ce --- /dev/null +++ b/Documentation/devicetree/bindings/iio/gyroscope/invensense,mpu3050.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/gyroscope/invensense,mpu3050.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Invensense MPU-3050 Gyroscope + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +properties: + compatible: + const: invensense,mpu3050 + + reg: + maxItems: 1 + + vdd-supply: true + + vlogic-supply: true + + interrupts: + minItems: 1 + description: + Interrupt mapping for the trigger interrupt from the internal oscillator. + + mount-matrix: true + + i2c-gate: + $ref: /schemas/i2c/i2c-controller.yaml + unevaluatedProperties: false + description: | + The MPU-3050 will pass through and forward the I2C signals from the + incoming I2C bus, alternatively drive traffic to a slave device (usually + an accelerometer) on its own initiative. Therefore is supports an + i2c-gate subnode. + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + gyroscope@68 { + compatible = "invensense,mpu3050"; + reg = <0x68>; + interrupt-parent = <&foo>; + interrupts = <12 IRQ_TYPE_EDGE_FALLING>; + vdd-supply = <&bar>; + vlogic-supply = <&baz>; + + i2c-gate { + #address-cells = <1>; + #size-cells = <0>; + + magnetometer@c { + compatible = "ak,ak8975"; + reg = <0x0c>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/imu/inv_mpu6050.txt b/Documentation/devicetree/bindings/iio/imu/inv_mpu6050.txt deleted file mode 100644 index f2f64749e818..000000000000 --- a/Documentation/devicetree/bindings/iio/imu/inv_mpu6050.txt +++ /dev/null @@ -1,67 +0,0 @@ -InvenSense MPU-6050 Six-Axis (Gyro + Accelerometer) MEMS MotionTracking Device - -http://www.invensense.com/mems/gyro/mpu6050.html - -Required properties: - - compatible : should be one of - "invensense,mpu6000" - "invensense,mpu6050" - "invensense,mpu6500" - "invensense,mpu6515" - "invensense,mpu9150" - "invensense,mpu9250" - "invensense,mpu9255" - "invensense,icm20608" - "invensense,icm20609" - "invensense,icm20689" - "invensense,icm20602" - "invensense,icm20690" - "invensense,iam20680" - - reg : the I2C address of the sensor - - interrupts: interrupt mapping for IRQ. It should be configured with flags - IRQ_TYPE_LEVEL_HIGH, IRQ_TYPE_EDGE_RISING, IRQ_TYPE_LEVEL_LOW or - IRQ_TYPE_EDGE_FALLING. - - Refer to interrupt-controller/interrupts.txt for generic interrupt client node - bindings. - -Optional properties: - - vdd-supply: regulator phandle for VDD supply - - vddio-supply: regulator phandle for VDDIO supply - - mount-matrix: an optional 3x3 mounting rotation matrix - - i2c-gate node. These devices also support an auxiliary i2c bus. This is - simple enough to be described using the i2c-gate binding. See - i2c/i2c-gate.txt for more details. - -Example: - mpu6050@68 { - compatible = "invensense,mpu6050"; - reg = <0x68>; - interrupt-parent = <&gpio1>; - interrupts = <18 IRQ_TYPE_EDGE_RISING>; - mount-matrix = "-0.984807753012208", /* x0 */ - "0", /* y0 */ - "-0.173648177666930", /* z0 */ - "0", /* x1 */ - "-1", /* y1 */ - "0", /* z1 */ - "-0.173648177666930", /* x2 */ - "0", /* y2 */ - "0.984807753012208"; /* z2 */ - }; - - - mpu9250@68 { - compatible = "invensense,mpu9250"; - reg = <0x68>; - interrupt-parent = <&gpio3>; - interrupts = <21 IRQ_TYPE_LEVEL_HIGH>; - i2c-gate { - #address-cells = <1>; - #size-cells = <0>; - ax8975@c { - compatible = "ak,ak8975"; - reg = <0x0c>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml b/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml new file mode 100644 index 000000000000..edbc2921aabd --- /dev/null +++ b/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml @@ -0,0 +1,104 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/imu/invensense,mpu6050.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: InvenSense MPU-6050 Six-Axis (Gyro + Accelerometer) MEMS MotionTracking Device + +maintainers: + - Jean-Baptiste Maneyrol <jmaneyrol@invensense.com> + +description: | + These devices support both I2C and SPI bus interfaces. + +properties: + compatible: + enum: + - invensense,iam20680 + - invensense,icm20608 + - invensense,icm20609 + - invensense,icm20689 + - invensense,icm20602 + - invensense,icm20690 + - invensense,mpu6000 + - invensense,mpu6050 + - invensense,mpu6500 + - invensense,mpu6515 + - invensense,mpu6880 + - invensense,mpu9150 + - invensense,mpu9250 + - invensense,mpu9255 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + spi-max-frequency: true + + vdd-supply: true + vddio-supply: true + + mount-matrix: true + + i2c-gate: + $ref: /schemas/i2c/i2c-controller.yaml + unevaluatedProperties: false + description: | + These devices also support an auxiliary i2c bus via an i2c-gate. + +allOf: + - if: + not: + properties: + compatible: + contains: + enum: + - invensense,mpu9150 + - invensense,mpu9250 + - invensense,mpu9255 + then: + properties: + i2c-gate: false + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + imu@68 { + compatible = "invensense,mpu9250"; + reg = <0x68>; + interrupt-parent = <&gpio3>; + interrupts = <21 IRQ_TYPE_LEVEL_HIGH>; + mount-matrix = "-0.984807753012208", /* x0 */ + "0", /* y0 */ + "-0.173648177666930", /* z0 */ + "0", /* x1 */ + "-1", /* y1 */ + "0", /* z1 */ + "-0.173648177666930", /* x2 */ + "0", /* y2 */ + "0.984807753012208"; /* z2 */ + i2c-gate { + #address-cells = <1>; + #size-cells = <0>; + magnetometer@c { + compatible = "ak,ak8975"; + reg = <0x0c>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/magnetometer/bosch,bmc150_magn.yaml b/Documentation/devicetree/bindings/iio/magnetometer/bosch,bmc150_magn.yaml index cdef7aeba708..2867ab6bf9b0 100644 --- a/Documentation/devicetree/bindings/iio/magnetometer/bosch,bmc150_magn.yaml +++ b/Documentation/devicetree/bindings/iio/magnetometer/bosch,bmc150_magn.yaml @@ -30,6 +30,9 @@ properties: reg: maxItems: 1 + vdd-supply: true + vddio-supply: true + interrupts: maxItems: 1 diff --git a/Documentation/devicetree/bindings/iio/magnetometer/yamaha,yas530.yaml b/Documentation/devicetree/bindings/iio/magnetometer/yamaha,yas530.yaml new file mode 100644 index 000000000000..4b0ef1ef5445 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/magnetometer/yamaha,yas530.yaml @@ -0,0 +1,112 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/magnetometer/yamaha,yas530.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Yamaha YAS530 family of magnetometer sensors + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +description: + The Yamaha YAS530 magnetometers is a line of 3-axis magnetometers + first introduced by Yamaha in 2009 with the YAS530. They are successors + of Yamaha's first magnetometer YAS529. Over the years this magnetometer + has been miniaturized and appeared in a number of different variants. + +properties: + $nodename: + pattern: '^magnetometer@[0-9a-f]+$' + + compatible: + items: + - enum: + - yamaha,yas530 + - yamaha,yas532 + - yamaha,yas533 + - yamaha,yas535 + - yamaha,yas536 + - yamaha,yas537 + - yamaha,yas539 + + reg: + maxItems: 1 + + reset-gpios: + maxItems: 1 + description: The YAS530 sensor has a RSTN pin used to reset + the logic inside the sensor. This GPIO line should connect + to that pin and be marked as GPIO_ACTIVE_LOW. + + interrupts: + maxItems: 1 + description: Interrupt for INT pin for interrupt generation. + The polarity, whether the interrupt is active on the rising + or the falling edge, is software-configurable in the hardware. + + vdd-supply: + description: An optional regulator providing core power supply + on the VDD pin, typically 1.8 V or 3.0 V. + + iovdd-supply: + description: An optional regulator providing I/O power supply + for the I2C interface on the IOVDD pin, typically 1.8 V. + + mount-matrix: + description: An optional 3x3 mounting rotation matrix. + +allOf: + - if: + not: + properties: + compatible: + items: + const: yamaha,yas530 + then: + properties: + reset-gpios: false + + - if: + properties: + compatible: + items: + const: yamaha,yas539 + then: + properties: + interrupts: false + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/gpio/gpio.h> + i2c-0 { + #address-cells = <1>; + #size-cells = <0>; + + magnetometer@2e { + compatible = "yamaha,yas530"; + reg = <0x2e>; + vdd-supply = <&ldo1_reg>; + iovdd-supply = <&ldo2_reg>; + reset-gpios = <&gpio6 12 GPIO_ACTIVE_LOW>; + interrupts = <&gpio6 13 IRQ_TYPE_EDGE_RISING>; + }; + }; + + i2c-1 { + #address-cells = <1>; + #size-cells = <0>; + + magnetometer@2e { + compatible = "yamaha,yas539"; + reg = <0x2e>; + vdd-supply = <&ldo1_reg>; + }; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun6i-a31-r-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun6i-a31-r-intc.yaml new file mode 100644 index 000000000000..4db24b8a9ffe --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun6i-a31-r-intc.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/allwinner,sun6i-a31-r-intc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A31 NMI/Wakeup Interrupt Controller Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <mripard@kernel.org> + +allOf: + - $ref: /schemas/interrupt-controller.yaml# + +properties: + "#interrupt-cells": + const: 3 + description: + The first cell is GIC_SPI (0), the second cell is the IRQ number, and + the third cell is the trigger type as defined in interrupt.txt in this + directory. + + compatible: + oneOf: + - const: allwinner,sun6i-a31-r-intc + - items: + - enum: + - allwinner,sun8i-a83t-r-intc + - allwinner,sun8i-h3-r-intc + - allwinner,sun50i-a64-r-intc + - const: allwinner,sun6i-a31-r-intc + - const: allwinner,sun50i-h6-r-intc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + description: + The GIC interrupt labeled as "External NMI". + + interrupt-controller: true + +required: + - "#interrupt-cells" + - compatible + - reg + - interrupts + - interrupt-controller + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + r_intc: interrupt-controller@1f00c00 { + compatible = "allwinner,sun50i-a64-r-intc", + "allwinner,sun6i-a31-r-intc"; + interrupt-controller; + #interrupt-cells = <3>; + reg = <0x01f00c00 0x400>; + interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; + }; + +... diff --git a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml index 8acca0ae3129..7fc9ad5ef38c 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml @@ -22,23 +22,16 @@ properties: compatible: oneOf: - - const: allwinner,sun6i-a31-r-intc - const: allwinner,sun6i-a31-sc-nmi deprecated: true - const: allwinner,sun7i-a20-sc-nmi - items: - - const: allwinner,sun8i-a83t-r-intc - - const: allwinner,sun6i-a31-r-intc + - const: allwinner,sun8i-v3s-nmi + - const: allwinner,sun9i-a80-nmi - const: allwinner,sun9i-a80-nmi - items: - - const: allwinner,sun50i-a64-r-intc - - const: allwinner,sun6i-a31-r-intc - - items: - const: allwinner,sun50i-a100-nmi - const: allwinner,sun9i-a80-nmi - - items: - - const: allwinner,sun50i-h6-r-intc - - const: allwinner,sun6i-a31-r-intc reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt index 1df293953327..e9afb48182c7 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt @@ -20,6 +20,8 @@ Properties: Definition: Should contain "qcom,<soc>-pdc" and "qcom,pdc" - "qcom,sc7180-pdc": For SC7180 - "qcom,sdm845-pdc": For SDM845 + - "qcom,sdm8250-pdc": For SM8250 + - "qcom,sdm8350-pdc": For SM8350 - reg: Usage: required diff --git a/Documentation/devicetree/bindings/interrupt-controller/realtek,rtl-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/realtek,rtl-intc.yaml new file mode 100644 index 000000000000..9e76fff20323 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/realtek,rtl-intc.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/realtek,rtl-intc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Realtek RTL SoC interrupt controller devicetree bindings + +maintainers: + - Birger Koblitz <mail@birger-koblitz.de> + - Bert Vermeulen <bert@biot.com> + - John Crispin <john@phrozen.org> + +properties: + compatible: + const: realtek,rtl-intc + + "#interrupt-cells": + const: 1 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + "#address-cells": + const: 0 + + interrupt-map: + description: Describes mapping from SoC interrupts to CPU interrupts + +required: + - compatible + - reg + - "#interrupt-cells" + - interrupt-controller + - "#address-cells" + - interrupt-map + +additionalProperties: false + +examples: + - | + intc: interrupt-controller@3000 { + compatible = "realtek,rtl-intc"; + #interrupt-cells = <1>; + interrupt-controller; + reg = <0x3000 0x20>; + #address-cells = <0>; + interrupt-map = + <31 &cpuintc 2>, + <30 &cpuintc 1>, + <29 &cpuintc 5>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/sigma,smp8642-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/sigma,smp8642-intc.txt deleted file mode 100644 index 355c18a3a4d3..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/sigma,smp8642-intc.txt +++ /dev/null @@ -1,48 +0,0 @@ -Sigma Designs SMP86xx/SMP87xx secondary interrupt controller - -Required properties: -- compatible: should be "sigma,smp8642-intc" -- reg: physical address of MMIO region -- ranges: address space mapping of child nodes -- interrupt-controller: boolean -- #address-cells: should be <1> -- #size-cells: should be <1> - -One child node per control block with properties: -- reg: address of registers for this control block -- interrupt-controller: boolean -- #interrupt-cells: should be <2>, interrupt index and flags per interrupts.txt -- interrupts: interrupt spec of primary interrupt controller - -Example: - -interrupt-controller@6e000 { - compatible = "sigma,smp8642-intc"; - reg = <0x6e000 0x400>; - ranges = <0x0 0x6e000 0x400>; - interrupt-parent = <&gic>; - interrupt-controller; - #address-cells = <1>; - #size-cells = <1>; - - irq0: interrupt-controller@0 { - reg = <0x000 0x100>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = <GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>; - }; - - irq1: interrupt-controller@100 { - reg = <0x100 0x100>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>; - }; - - irq2: interrupt-controller@300 { - reg = <0x300 0x100>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = <GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>; - }; -}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,c64x+megamod-pic.txt b/Documentation/devicetree/bindings/interrupt-controller/ti,c64x+megamod-pic.txt deleted file mode 100644 index ee3f9c351501..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/ti,c64x+megamod-pic.txt +++ /dev/null @@ -1,103 +0,0 @@ -C6X Interrupt Chips -------------------- - -* C64X+ Core Interrupt Controller - - The core interrupt controller provides 16 prioritized interrupts to the - C64X+ core. Priority 0 and 1 are used for reset and NMI respectively. - Priority 2 and 3 are reserved. Priority 4-15 are used for interrupt - sources coming from outside the core. - - Required properties: - -------------------- - - compatible: Should be "ti,c64x+core-pic"; - - #interrupt-cells: <1> - - Interrupt Specifier Definition - ------------------------------ - Single cell specifying the core interrupt priority level (4-15) where - 4 is highest priority and 15 is lowest priority. - - Example - ------- - core_pic: interrupt-controller@0 { - interrupt-controller; - #interrupt-cells = <1>; - compatible = "ti,c64x+core-pic"; - }; - - - -* C64x+ Megamodule Interrupt Controller - - The megamodule PIC consists of four interrupt mupliplexers each of which - combine up to 32 interrupt inputs into a single interrupt output which - may be cascaded into the core interrupt controller. The megamodule PIC - has a total of 12 outputs cascading into the core interrupt controller. - One for each core interrupt priority level. In addition to the combined - interrupt sources, individual megamodule interrupts may be cascaded to - the core interrupt controller. When an individual interrupt is cascaded, - it is no longer handled through a megamodule interrupt combiner and is - considered to have the core interrupt controller as the parent. - - Required properties: - -------------------- - - compatible: "ti,c64x+megamod-pic" - - interrupt-controller - - #interrupt-cells: <1> - - reg: base address and size of register area - - interrupts: This should have four cells; one for each interrupt combiner. - The cells contain the core priority interrupt to which the - corresponding combiner output is wired. - - Optional properties: - -------------------- - - ti,c64x+megamod-pic-mux: Array of 12 cells correspnding to the 12 core - priority interrupts. The first cell corresponds to - core priority 4 and the last cell corresponds to - core priority 15. The value of each cell is the - megamodule interrupt source which is MUXed to - the core interrupt corresponding to the cell - position. Allowed values are 4 - 127. Mapping for - interrupts 0 - 3 (combined interrupt sources) are - ignored. - - Interrupt Specifier Definition - ------------------------------ - Single cell specifying the megamodule interrupt source (4-127). Note that - interrupts mapped directly to the core with "ti,c64x+megamod-pic-mux" will - use the core interrupt controller as their parent and the specifier will - be the core priority level, not the megamodule interrupt number. - - Examples - -------- - megamod_pic: interrupt-controller@1800000 { - compatible = "ti,c64x+megamod-pic"; - interrupt-controller; - #interrupt-cells = <1>; - reg = <0x1800000 0x1000>; - interrupt-parent = <&core_pic>; - interrupts = < 12 13 14 15 >; - }; - - This is a minimal example where all individual interrupts go through a - combiner. Combiner-0 is mapped to core interrupt 12, combiner-1 is mapped - to interrupt 13, etc. - - - megamod_pic: interrupt-controller@1800000 { - compatible = "ti,c64x+megamod-pic"; - interrupt-controller; - #interrupt-cells = <1>; - reg = <0x1800000 0x1000>; - interrupt-parent = <&core_pic>; - interrupts = < 12 13 14 15 >; - ti,c64x+megamod-pic-mux = < 0 0 0 0 - 32 0 0 0 - 0 0 0 0 >; - }; - - This the same as the first example except that megamodule interrupt 32 is - mapped directly to core priority interrupt 8. The node using this interrupt - must set the core controller as its interrupt parent and use 8 in the - interrupt specifier value. diff --git a/Documentation/devicetree/bindings/media/allegro,al5e.yaml b/Documentation/devicetree/bindings/media/allegro,al5e.yaml new file mode 100644 index 000000000000..135bea94b587 --- /dev/null +++ b/Documentation/devicetree/bindings/media/allegro,al5e.yaml @@ -0,0 +1,105 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/allegro,al5e.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allegro DVT Video IP Codecs Device Tree Bindings + +maintainers: + - Michael Tretter <m.tretter@pengutronix.de> + +description: |- + Allegro DVT video IP codecs present in the Xilinx ZynqMP SoC. The IP core may + either be a H.264/H.265 encoder or H.264/H.265 decoder ip core. + + Each actual codec engine is controlled by a microcontroller (MCU). Host + software uses a provided mailbox interface to communicate with the MCU. The + MCUs share an interrupt. + +properties: + compatible: + oneOf: + - items: + - const: allegro,al5e-1.1 + - const: allegro,al5e + - items: + - const: allegro,al5d-1.1 + - const: allegro,al5d + + reg: + items: + - description: The registers + - description: The SRAM + + reg-names: + items: + - const: regs + - const: sram + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Core clock + - description: MCU clock + - description: Core AXI master port clock + - description: MCU AXI master port clock + - description: AXI4-Lite slave port clock + + clock-names: + items: + - const: core_clk + - const: mcu_clk + - const: m_axi_core_aclk + - const: m_axi_mcu_aclk + - const: s_axi_lite_aclk + +required: + - compatible + - reg + - reg-names + - interrupts + - clocks + - clock-names + +additionalProperties: False + +examples: + - | + fpga { + #address-cells = <2>; + #size-cells = <2>; + + al5e: video-codec@a0009000 { + compatible = "allegro,al5e-1.1", "allegro,al5e"; + reg = <0 0xa0009000 0 0x1000>, + <0 0xa0000000 0 0x8000>; + reg-names = "regs", "sram"; + interrupts = <0 96 4>; + clocks = <&xlnx_vcu 0>, <&xlnx_vcu 1>, + <&clkc 71>, <&clkc 71>, <&clkc 71>; + clock-names = "core_clk", "mcu_clk", "m_axi_core_aclk", + "m_axi_mcu_aclk", "s_axi_lite_aclk"; + }; + }; + - | + fpga { + #address-cells = <2>; + #size-cells = <2>; + + al5d: video-codec@a0029000 { + compatible = "allegro,al5d-1.1", "allegro,al5d"; + reg = <0 0xa0029000 0 0x1000>, + <0 0xa0020000 0 0x8000>; + reg-names = "regs", "sram"; + interrupts = <0 96 4>; + clocks = <&xlnx_vcu 2>, <&xlnx_vcu 3>, + <&clkc 71>, <&clkc 71>, <&clkc 71>; + clock-names = "core_clk", "mcu_clk", "m_axi_core_aclk", + "m_axi_mcu_aclk", "s_axi_lite_aclk"; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/allegro.txt b/Documentation/devicetree/bindings/media/allegro.txt deleted file mode 100644 index a92e2fbf26c9..000000000000 --- a/Documentation/devicetree/bindings/media/allegro.txt +++ /dev/null @@ -1,43 +0,0 @@ -Device-tree bindings for the Allegro DVT video IP codecs present in the Xilinx -ZynqMP SoC. The IP core may either be a H.264/H.265 encoder or H.264/H.265 -decoder ip core. - -Each actual codec engines is controlled by a microcontroller (MCU). Host -software uses a provided mailbox interface to communicate with the MCU. The -MCU share an interrupt. - -Required properties: - - compatible: value should be one of the following - "allegro,al5e-1.1", "allegro,al5e": encoder IP core - "allegro,al5d-1.1", "allegro,al5d": decoder IP core - - reg: base and length of the memory mapped register region and base and - length of the memory mapped sram - - reg-names: must include "regs" and "sram" - - interrupts: shared interrupt from the MCUs to the processing system - - clocks: must contain an entry for each entry in clock-names - - clock-names: must include "core_clk", "mcu_clk", "m_axi_core_aclk", - "m_axi_mcu_aclk", "s_axi_lite_aclk" - -Example: - al5e: video-codec@a0009000 { - compatible = "allegro,al5e-1.1", "allegro,al5e"; - reg = <0 0xa0009000 0 0x1000>, - <0 0xa0000000 0 0x8000>; - reg-names = "regs", "sram"; - interrupts = <0 96 4>; - clocks = <&xlnx_vcu 0>, <&xlnx_vcu 1>, - <&clkc 71>, <&clkc 71>, <&clkc 71>; - clock-names = "core_clk", "mcu_clk", "m_axi_core_aclk", - "m_axi_mcu_aclk", "s_axi_lite_aclk" - }; - al5d: video-codec@a0029000 { - compatible = "allegro,al5d-1.1", "allegro,al5d"; - reg = <0 0xa0029000 0 0x1000>, - <0 0xa0020000 0 0x8000>; - reg-names = "regs", "sram"; - interrupts = <0 96 4>; - clocks = <&xlnx_vcu 2>, <&xlnx_vcu 3>, - <&clkc 71>, <&clkc 71>, <&clkc 71>; - clock-names = "core_clk", "mcu_clk", "m_axi_core_aclk", - "m_axi_mcu_aclk", "s_axi_lite_aclk" - }; diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml index 09318830db47..6ced94064215 100644 --- a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml +++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml @@ -67,14 +67,14 @@ properties: interconnect-names: const: dma-mem - # See ./video-interfaces.txt for details port: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base additionalProperties: false properties: endpoint: - type: object + $ref: video-interfaces.yaml# + unevaluatedProperties: false properties: bus-width: @@ -83,7 +83,6 @@ properties: data-active: true hsync-active: true pclk-sample: true - remote-endpoint: true vsync-active: true required: @@ -91,12 +90,8 @@ properties: - data-active - hsync-active - pclk-sample - - remote-endpoint - vsync-active - required: - - endpoint - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-csi.yaml b/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-csi.yaml index 1fd9b5532a21..8b568072a069 100644 --- a/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-csi.yaml +++ b/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-csi.yaml @@ -40,17 +40,15 @@ properties: resets: maxItems: 1 - # See ./video-interfaces.txt for details port: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base properties: endpoint: - type: object + $ref: video-interfaces.yaml# + unevaluatedProperties: false properties: - remote-endpoint: true - bus-width: enum: [ 8, 10, 12, 16 ] @@ -60,10 +58,6 @@ properties: required: - bus-width - - remote-endpoint - - required: - - endpoint additionalProperties: false diff --git a/Documentation/devicetree/bindings/media/allwinner,sun8i-h3-deinterlace.yaml b/Documentation/devicetree/bindings/media/allwinner,sun8i-h3-deinterlace.yaml index 6a56214c6cfd..b80980b1908e 100644 --- a/Documentation/devicetree/bindings/media/allwinner,sun8i-h3-deinterlace.yaml +++ b/Documentation/devicetree/bindings/media/allwinner,sun8i-h3-deinterlace.yaml @@ -20,6 +20,9 @@ properties: oneOf: - const: allwinner,sun8i-h3-deinterlace - items: + - const: allwinner,sun8i-r40-deinterlace + - const: allwinner,sun8i-h3-deinterlace + - items: - const: allwinner,sun50i-a64-deinterlace - const: allwinner,sun8i-h3-deinterlace diff --git a/Documentation/devicetree/bindings/media/i2c/adv7180.yaml b/Documentation/devicetree/bindings/media/i2c/adv7180.yaml index d8c54f9d9506..bcfd93739b4f 100644 --- a/Documentation/devicetree/bindings/media/i2c/adv7180.yaml +++ b/Documentation/devicetree/bindings/media/i2c/adv7180.yaml @@ -36,17 +36,9 @@ properties: maxItems: 1 port: - type: object - description: - A node containing a single endpoint as doucmented in - Documentation/devicetree/bindings/media/video-interfaces.txt - - ports: - type: object - description: - A node containing input and output port nodes with endpoint definitions - as documented in - Documentation/devicetree/bindings/media/video-interfaces.txt + $ref: /schemas/graph.yaml#/properties/port + + ports: true additionalProperties: false @@ -80,25 +72,20 @@ allOf: then: properties: ports: + $ref: /schemas/graph.yaml#/properties/ports properties: - '#address-cells': - const: 1 - '#size-cells': - const: 0 port@3: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Output port patternProperties: "^port@[0-2]$": - type: object + $ref: /schemas/graph.yaml#/properties/port description: Input port required: - port@3 - additionalProperties: false - required: - ports @@ -110,25 +97,20 @@ allOf: then: properties: ports: + $ref: /schemas/graph.yaml#/properties/ports properties: - '#address-cells': - const: 1 - '#size-cells': - const: 0 port@6: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Output port patternProperties: "^port@[0-5]$": - type: object + $ref: /schemas/graph.yaml#/properties/port description: Input port required: - port@6 - additionalProperties: false - required: - ports diff --git a/Documentation/devicetree/bindings/media/i2c/adv7604.yaml b/Documentation/devicetree/bindings/media/i2c/adv7604.yaml index 407baddfaa1d..df634b0c1f8c 100644 --- a/Documentation/devicetree/bindings/media/i2c/adv7604.yaml +++ b/Documentation/devicetree/bindings/media/i2c/adv7604.yaml @@ -64,16 +64,12 @@ properties: description: Select which input is selected after reset. - ports: - type: object - description: - A node containing input and output port nodes with endpoint definitions - as documented in - Documentation/devicetree/bindings/media/video-interfaces.txt + ports: true required: - compatible - reg + - ports additionalProperties: false @@ -86,26 +82,19 @@ allOf: then: properties: ports: + $ref: /schemas/graph.yaml#/properties/ports properties: - '#address-cells': - const: 1 - '#size-cells': - const: 0 port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Input port + port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Output port required: - port@1 - additionalProperties: false - - required: - - ports - - if: properties: compatible: @@ -114,28 +103,20 @@ allOf: then: properties: ports: + $ref: /schemas/graph.yaml#/properties/ports properties: - '#address-cells': - const: 1 - '#size-cells': - const: 0 port@2: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Output port patternProperties: "^port@[0-1]$": - type: object + $ref: /schemas/graph.yaml#/properties/port description: Input port required: - port@2 - additionalProperties: false - - required: - - ports - examples: - | #include <dt-bindings/gpio/gpio.h> diff --git a/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.yaml b/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.yaml index ff9546e95d05..e53b8d65f381 100644 --- a/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.yaml +++ b/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.yaml @@ -41,9 +41,9 @@ properties: maxItems: 1 port: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | - Output video port. See ../video-interfaces.txt. + Output video port. required: - compatible diff --git a/Documentation/devicetree/bindings/media/i2c/imi,rdacm2x-gmsl.yaml b/Documentation/devicetree/bindings/media/i2c/imi,rdacm2x-gmsl.yaml index 3dc06c628e64..e57575c44930 100644 --- a/Documentation/devicetree/bindings/media/i2c/imi,rdacm2x-gmsl.yaml +++ b/Documentation/devicetree/bindings/media/i2c/imi,rdacm2x-gmsl.yaml @@ -86,33 +86,9 @@ properties: maxItems: 3 port: - type: object - additionalProperties: false - description: -| - Connection to the remote GMSL endpoint are modelled using the OF graph - bindings in accordance with the video interface bindings defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. - - The device node contains a single "port" child node with a single - "endpoint" sub-device. - - properties: - endpoint: - type: object - additionalProperties: false - - properties: - remote-endpoint: - description: -| - phandle to the remote GMSL endpoint sub-node in the remote node - port. - maxItems: 1 - - required: - - remote-endpoint - - required: - - endpoint + $ref: /schemas/graph.yaml#/properties/port + description: + Connection to the remote GMSL endpoint. required: - compatible diff --git a/Documentation/devicetree/bindings/media/i2c/imx219.yaml b/Documentation/devicetree/bindings/media/i2c/imx219.yaml index dfc4d29a4f04..012c0565d8ae 100644 --- a/Documentation/devicetree/bindings/media/i2c/imx219.yaml +++ b/Documentation/devicetree/bindings/media/i2c/imx219.yaml @@ -44,12 +44,15 @@ properties: Reference to the GPIO connected to the xclr pin, if any. Must be released (set high) after all supplies are applied. - # See ../video-interfaces.txt for more details port: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base + additionalProperties: false + properties: endpoint: - type: object + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + properties: data-lanes: description: |- @@ -60,16 +63,8 @@ properties: - const: 1 - const: 2 - clock-noncontinuous: - type: boolean - description: |- - MIPI CSI-2 clock is non-continuous if this property is present, - otherwise it's continuous. - - link-frequencies: - $ref: /schemas/types.yaml#/definitions/uint64-array - description: - Allowed data bus frequencies. + clock-noncontinuous: true + link-frequencies: true required: - link-frequencies diff --git a/Documentation/devicetree/bindings/media/i2c/imx258.yaml b/Documentation/devicetree/bindings/media/i2c/imx258.yaml new file mode 100644 index 000000000000..eaf77866ed9b --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/imx258.yaml @@ -0,0 +1,134 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/imx258.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sony IMX258 13 Mpixel CMOS Digital Image Sensor + +maintainers: + - Krzysztof Kozlowski <krzk@kernel.org> + +description: |- + IMX258 is a diagonal 5.867mm (Type 1/3.06) 13 Mega-pixel CMOS active pixel + type stacked image sensor with a square pixel array of size 4208 x 3120. It + is programmable through I2C interface. Image data is sent through MIPI + CSI-2. + +properties: + compatible: + const: sony,imx258 + + assigned-clocks: true + assigned-clock-parents: true + assigned-clock-rates: true + + clocks: + description: + Clock frequency from 6 to 27 MHz. + maxItems: 1 + + reg: + maxItems: 1 + + reset-gpios: + description: |- + Reference to the GPIO connected to the XCLR pin, if any. + + vana-supply: + description: + Analog voltage (VANA) supply, 2.7 V + + vdig-supply: + description: + Digital I/O voltage (VDIG) supply, 1.2 V + + vif-supply: + description: + Interface voltage (VIF) supply, 1.8 V + + # See ../video-interfaces.txt for more details + port: + type: object + properties: + endpoint: + type: object + properties: + data-lanes: + oneOf: + - items: + - const: 1 + - const: 2 + - const: 3 + - const: 4 + - items: + - const: 1 + - const: 2 + + link-frequencies: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint64-array + description: + Allowed data bus frequencies. + + required: + - data-lanes + - link-frequencies + +required: + - compatible + - reg + - port + +additionalProperties: false + +examples: + - | + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + sensor@6c { + compatible = "sony,imx258"; + reg = <0x6c>; + clocks = <&imx258_clk>; + + port { + endpoint { + remote-endpoint = <&csi1_ep>; + data-lanes = <1 2 3 4>; + link-frequencies = /bits/ 64 <320000000>; + }; + }; + }; + }; + + /* Oscillator on the camera board */ + imx258_clk: clk { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <19200000>; + }; + + - | + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + sensor@6c { + compatible = "sony,imx258"; + reg = <0x6c>; + clocks = <&imx258_clk>; + + assigned-clocks = <&imx258_clk>; + assigned-clock-rates = <19200000>; + + port { + endpoint { + remote-endpoint = <&csi1_ep>; + data-lanes = <1 2 3 4>; + link-frequencies = /bits/ 64 <633600000>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml b/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml index 68ee8c7d9e79..ee16102fdfe7 100644 --- a/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml +++ b/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml @@ -50,82 +50,62 @@ properties: '#gpio-cells': const: 2 - ports: - type: object + maxim,reverse-channel-microvolt: + minimum: 30000 + maximum: 200000 + default: 170000 description: | - The connections to the MAX9286 GMSL and its endpoint nodes are modelled - using the OF graph bindings in accordance with the video interface - bindings defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. - - The following table lists the port number corresponding to each device - port. - - Port Description - ---------------------------------------- - Port 0 GMSL Input 0 - Port 1 GMSL Input 1 - Port 2 GMSL Input 2 - Port 3 GMSL Input 3 - Port 4 CSI-2 Output + Initial amplitude of the reverse control channel, in micro volts. - properties: - '#address-cells': - const: 1 + The initial amplitude shall be adjusted to a value compatible with the + configuration of the connected remote serializer. - '#size-cells': - const: 0 + Some camera modules (for example RDACM20) include an on-board MCU that + pre-programs the embedded serializer with power supply noise immunity + (high-threshold) enabled. A typical value of the deserializer's reverse + channel amplitude to communicate with pre-programmed serializers is + 170000 micro volts. - port@[0-3]: - type: object - properties: - reg: - enum: [ 0, 1, 2, 3 ] + A typical value for the reverse channel amplitude to communicate with + a remote serializer whose high-threshold noise immunity is not enabled + is 100000 micro volts - endpoint: - type: object + ports: + $ref: /schemas/graph.yaml#/properties/ports - properties: - remote-endpoint: - description: | - phandle to the remote GMSL source endpoint subnode in the - remote node port. + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: GMSL Input 0 - required: - - remote-endpoint + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: GMSL Input 1 - required: - - reg - - endpoint + port@2: + $ref: /schemas/graph.yaml#/properties/port + description: GMSL Input 2 - additionalProperties: false + port@3: + $ref: /schemas/graph.yaml#/properties/port + description: GMSL Input 3 port@4: - type: object - properties: - reg: - const: 4 + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: CSI-2 Output + properties: endpoint: - type: object + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false properties: - remote-endpoint: - description: phandle to the remote CSI-2 sink endpoint. - - data-lanes: - description: array of physical CSI-2 data lane indexes. + data-lanes: true required: - - remote-endpoint - data-lanes - required: - - reg - - endpoint - - additionalProperties: false - required: - port@4 @@ -183,25 +163,8 @@ properties: requirements of the currently connected remote device. port: - type: object - - properties: - endpoint: - type: object - - properties: - remote-endpoint: - description: phandle to the MAX9286 sink endpoint. - - required: - - remote-endpoint - - additionalProperties: false - - required: - - endpoint - - additionalProperties: false + $ref: /schemas/graph.yaml#/properties/port + description: Connection to the MAX9286 sink. required: - compatible @@ -242,6 +205,8 @@ examples: gpio-controller; #gpio-cells = <2>; + maxim,reverse-channel-microvolt = <170000>; + ports { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml b/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml index bb3528315f20..701f4e0d138f 100644 --- a/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml +++ b/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml @@ -71,19 +71,18 @@ properties: enum: [ 0, 180 ] port: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base + additionalProperties: false + properties: endpoint: - type: object + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + properties: - link-frequencies: - $ref: /schemas/types.yaml#/definitions/uint64-array - description: List of allowed data link frequencies. - data-lanes: - minItems: 1 - maxItems: 8 + link-frequencies: true + data-lanes: true bus-type: - description: The type of the data bus. oneOf: - const: 1 # CSI-2 C-PHY - const: 3 # CCP2 diff --git a/Documentation/devicetree/bindings/media/i2c/ov8856.yaml b/Documentation/devicetree/bindings/media/i2c/ov8856.yaml index cde85553fd01..baf92aaaf049 100644 --- a/Documentation/devicetree/bindings/media/i2c/ov8856.yaml +++ b/Documentation/devicetree/bindings/media/i2c/ov8856.yaml @@ -57,16 +57,13 @@ properties: active low. port: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base additionalProperties: false - description: - A node containing an output port node with an endpoint definition - as documented in - Documentation/devicetree/bindings/media/video-interfaces.txt properties: endpoint: - type: object + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false properties: data-lanes: @@ -79,18 +76,14 @@ properties: - const: 4 link-frequencies: - $ref: /schemas/types.yaml#/definitions/uint64-array - description: - Allowed data bus frequencies. 360000000, 180000000 Hz or both - are supported by the driver. - + description: Frequencies listed are driver, not h/w limitations. + maxItems: 2 + items: + enum: [ 360000000, 180000000 ] required: - link-frequencies - required: - - endpoint - required: - compatible - reg @@ -139,4 +132,3 @@ examples: }; }; ... - diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml index 1c3879ec4122..63a040944f3d 100644 --- a/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml @@ -17,6 +17,9 @@ description: |- @ 1600x1200 (UXGA) resolution transferred over a 1-lane MIPI interface. The sensor output is available via CSI-2 serial data output. +allOf: + - $ref: /schemas/media/video-interface-devices.yaml# + properties: compatible: const: ovti,ov02a10 @@ -66,42 +69,34 @@ properties: maxItems: 1 rotation: - description: - Definition of the sensor's placement. - allOf: - - $ref: "/schemas/types.yaml#/definitions/uint32" - - enum: - - 0 # Sensor Mounted Upright - - 180 # Sensor Mounted Upside Down - default: 0 - - # See ../video-interfaces.txt for details + enum: + - 0 # Sensor Mounted Upright + - 180 # Sensor Mounted Upside Down + default: 0 + port: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base additionalProperties: false description: Output port node, single endpoint describing the CSI-2 transmitter. properties: endpoint: - type: object - additionalProperties: false + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false properties: link-frequencies: true ovti,mipi-clock-voltage: - allOf: - - $ref: "/schemas/types.yaml#/definitions/uint32" + $ref: "/schemas/types.yaml#/definitions/uint32" description: Definition of MIPI clock voltage unit. This entry corresponds to the link speed defined by the 'link-frequencies' property. If present, the value shall be in the range of 0-4. default: 4 - remote-endpoint: true required: - link-frequencies - - remote-endpoint required: - endpoint diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov2680.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov2680.yaml index 43bf749807e1..cf456f8d9ddc 100644 --- a/Documentation/devicetree/bindings/media/i2c/ovti,ov2680.yaml +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov2680.yaml @@ -50,11 +50,9 @@ properties: Definition of the regulator used as digital power supply. port: - type: object + $ref: /schemas/graph.yaml#/properties/port description: - A node containing an output port node with an endpoint definition - as documented in - Documentation/devicetree/bindings/media/video-interfaces.txt + A node containing an output port node. required: - compatible diff --git a/Documentation/devicetree/bindings/media/i2c/ov5647.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5647.yaml index 280c62afae13..1ab22e75d3c6 100644 --- a/Documentation/devicetree/bindings/media/i2c/ov5647.yaml +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5647.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/media/i2c/ov5647.yaml# +$id: http://devicetree.org/schemas/media/i2c/ovti,ov5647.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Omnivision OV5647 raw image sensor @@ -31,27 +31,15 @@ properties: maxItems: 1 port: - type: object - description: |- - Should contain one endpoint sub-node used to model connection to the - video receiver according to the specification defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. + $ref: /schemas/graph.yaml#/$defs/port-base properties: endpoint: - type: object + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false properties: - remote-endpoint: - description: |- - phandle to the video receiver input port. - - clock-noncontinuous: - type: boolean - description: |- - Set to true to allow MIPI CSI-2 non-continuous clock operations. - - additionalProperties: false + clock-noncontinuous: true additionalProperties: false diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov5648.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5648.yaml new file mode 100644 index 000000000000..f8783f77cc54 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5648.yaml @@ -0,0 +1,115 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/ovti,ov5648.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: OmniVision OV5648 Image Sensor Device Tree Bindings + +maintainers: + - Paul Kocialkowski <paul.kocialkowski@bootlin.com> + +properties: + compatible: + const: ovti,ov5648 + + reg: + maxItems: 1 + + clocks: + items: + - description: XVCLK Clock + + assigned-clocks: + maxItems: 1 + + assigned-clock-rates: + maxItems: 1 + + dvdd-supply: + description: Digital Domain Power Supply + + avdd-supply: + description: Analog Domain Power Supply (internal AVDD is used if missing) + + dovdd-supply: + description: I/O Domain Power Supply + + powerdown-gpios: + maxItems: 1 + description: Power Down Pin GPIO Control (active low) + + reset-gpios: + maxItems: 1 + description: Reset Pin GPIO Control (active low) + + port: + type: object + description: MIPI CSI-2 transmitter port + + properties: + endpoint: + type: object + + properties: + remote-endpoint: true + + link-frequencies: + $ref: /schemas/types.yaml#/definitions/uint64-array + description: Allowed MIPI CSI-2 link frequencies + + data-lanes: + minItems: 1 + maxItems: 2 + + required: + - data-lanes + - link-frequencies + - remote-endpoint + + required: + - endpoint + +required: + - compatible + - reg + - clocks + - assigned-clocks + - assigned-clock-rates + - dvdd-supply + - dovdd-supply + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/sun8i-v3s-ccu.h> + #include <dt-bindings/gpio/gpio.h> + + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + ov5648: camera@36 { + compatible = "ovti,ov5648"; + reg = <0x36>; + + dvdd-supply = <&ov5648_dvdd>; + avdd-supply = <&ov5648_avdd>; + dovdd-supply = <&ov5648_dovdd>; + clocks = <&ov5648_xvclk 0>; + assigned-clocks = <&ov5648_xvclk 0>; + assigned-clock-rates = <24000000>; + + + ov5648_out: port { + ov5648_out_mipi_csi2: endpoint { + data-lanes = <1 2>; + link-frequencies = /bits/ 64 <210000000 168000000>; + + remote-endpoint = <&mipi_csi2_in_ov5648>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml index 6866c2cdac50..44529425ce3a 100644 --- a/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml @@ -37,13 +37,14 @@ properties: maxItems: 1 port: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base description: | - Video output port. See ../video-interfaces.txt. + Video output port. properties: endpoint: - type: object + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false properties: bus-type: @@ -91,8 +92,6 @@ properties: required: - bus-type - unevaluatedProperties: false - additionalProperties: false required: diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov8865.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov8865.yaml new file mode 100644 index 000000000000..c0ba28aa30c4 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov8865.yaml @@ -0,0 +1,124 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/ovti,ov8865.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: OmniVision OV8865 Image Sensor Device Tree Bindings + +maintainers: + - Paul Kocialkowski <paul.kocialkowski@bootlin.com> + +properties: + compatible: + const: ovti,ov8865 + + reg: + maxItems: 1 + + clocks: + items: + - description: EXTCLK Clock + + assigned-clocks: + maxItems: 1 + + assigned-clock-rates: + maxItems: 1 + + dvdd-supply: + description: Digital Domain Power Supply + + avdd-supply: + description: Analog Domain Power Supply + + dovdd-supply: + description: I/O Domain Power Supply + + powerdown-gpios: + maxItems: 1 + description: Power Down Pin GPIO Control (active low) + + reset-gpios: + maxItems: 1 + description: Reset Pin GPIO Control (active low) + + port: + type: object + description: MIPI CSI-2 transmitter port + + properties: + endpoint: + type: object + + properties: + remote-endpoint: true + + link-frequencies: + $ref: /schemas/types.yaml#/definitions/uint64-array + description: Allowed MIPI CSI-2 link frequencies + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - data-lanes + - link-frequencies + - remote-endpoint + + required: + - endpoint + +required: + - compatible + - reg + - clocks + - assigned-clocks + - assigned-clock-rates + - dvdd-supply + - avdd-supply + - dovdd-supply + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/sun8i-a83t-ccu.h> + #include <dt-bindings/gpio/gpio.h> + + i2c2 { + #address-cells = <1>; + #size-cells = <0>; + + ov8865: camera@36 { + compatible = "ovti,ov8865"; + reg = <0x36>; + + pinctrl-names = "default"; + pinctrl-0 = <&csi_mclk_pin>; + + clocks = <&ccu CLK_CSI_MCLK>; + assigned-clocks = <&ccu CLK_CSI_MCLK>; + assigned-clock-rates = <24000000>; + + avdd-supply = <®_ov8865_avdd>; + dovdd-supply = <®_ov8865_dovdd>; + dvdd-supply = <®_ov8865_dvdd>; + + powerdown-gpios = <&pio 4 17 GPIO_ACTIVE_LOW>; /* PE17 */ + reset-gpios = <&pio 4 16 GPIO_ACTIVE_LOW>; /* PE16 */ + + port { + ov8865_out_mipi_csi2: endpoint { + data-lanes = <1 2 3 4>; + link-frequencies = /bits/ 64 <360000000>; + + remote-endpoint = <&mipi_csi2_in_ov8865>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml index eb12526a462f..c9760f895b3e 100644 --- a/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml +++ b/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml @@ -15,6 +15,9 @@ description: | interface. Image data is sent through MIPI CSI-2, through 2 or 4 lanes at a maximum throughput of 1.2Gbps/lane. +allOf: + - $ref: ../video-interface-devices.yaml# + properties: compatible: const: sony,imx214 @@ -44,25 +47,21 @@ properties: vddd-supply: description: Chip digital core regulator (1.12V). - flash-leds: - description: See ../video-interfaces.txt - - lens-focus: - description: See ../video-interfaces.txt + flash-leds: true + lens-focus: true port: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base description: | - Video output port. See ../video-interfaces.txt. + Video output port. properties: endpoint: - type: object + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false properties: data-lanes: - $ref: /schemas/types.yaml#/definitions/uint32-array - description: See ../video-interfaces.txt anyOf: - items: - const: 1 @@ -73,16 +72,12 @@ properties: - const: 3 - const: 4 - link-frequencies: - $ref: /schemas/types.yaml#/definitions/uint64-array - description: See ../video-interfaces.txt + link-frequencies: true required: - data-lanes - link-frequencies - unevaluatedProperties: false - additionalProperties: false required: diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx274.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx274.yaml index a66acb20d59b..4271fc3cc623 100644 --- a/Documentation/devicetree/bindings/media/i2c/sony,imx274.yaml +++ b/Documentation/devicetree/bindings/media/i2c/sony,imx274.yaml @@ -41,8 +41,7 @@ properties: description: Sensor digital IO 1.2 V supply. port: - type: object - description: Output video port. See ../video-interfaces.txt. + $ref: /schemas/graph.yaml#/properties/port required: - compatible diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx334.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx334.yaml new file mode 100644 index 000000000000..24e689314bde --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/sony,imx334.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2021 Intel Corporation +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/sony,imx334.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sony IMX334 Sensor + +maintainers: + - Paul J. Murphy <paul.j.murphy@intel.com> + - Daniele Alessandrelli <daniele.alessandrelli@intel.com> + +description: + IMX334 sensor is a Sony CMOS active pixel digital image sensor with an active + array size of 3864H x 2202V. It is programmable through I2C interface. The + I2C client address is fixed to 0x1a as per sensor data sheet. Image data is + sent through MIPI CSI-2. + +properties: + compatible: + const: sony,imx334 + reg: + description: I2C address + maxItems: 1 + + assigned-clocks: true + assigned-clock-parents: true + assigned-clock-rates: true + + clocks: + description: Clock frequency from 6 to 27 MHz, 37.125MHz, 74.25MHz + maxItems: 1 + + reset-gpios: + description: Reference to the GPIO connected to the XCLR pin, if any. + + port: + type: object + additionalProperties: false + $ref: /schemas/graph.yaml#/properties/port + + properties: + endpoint: + type: object + properties: + data-lanes: + $ref: ../video-interfaces.yaml#/properties/data-lanes + link-frequencies: + $ref: ../video-interfaces.yaml#/properties/link-frequencies + + required: + - data-lanes + - link-frequencies + + required: + - endpoint + +required: + - compatible + - reg + - clocks + - port + +additionalProperties: false + +examples: + - | + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + camera@1a { + compatible = "sony,imx334"; + reg = <0x1a>; + clocks = <&imx334_clk>; + + assigned-clocks = <&imx334_clk>; + assigned-clock-parents = <&imx334_clk_parent>; + assigned-clock-rates = <24000000>; + + port { + imx334: endpoint { + remote-endpoint = <&cam>; + data-lanes = <1 2 3 4>; + link-frequencies = /bits/ 64 <891000000>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/marvell,mmp2-ccic.yaml b/Documentation/devicetree/bindings/media/marvell,mmp2-ccic.yaml index 49bff738aca5..c14c7d827b00 100644 --- a/Documentation/devicetree/bindings/media/marvell,mmp2-ccic.yaml +++ b/Documentation/devicetree/bindings/media/marvell,mmp2-ccic.yaml @@ -23,30 +23,24 @@ properties: interrupts: maxItems: 1 + power-domains: + maxItems: 1 + port: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base additionalProperties: false properties: endpoint: - type: object - additionalProperties: false + $ref: video-interfaces.yaml# + unevaluatedProperties: false - # Properties described in - # Documentation/devicetree/bindings/media/video-interfaces.txt properties: - remote-endpoint: true hsync-active: true vsync-active: true pclk-sample: true bus-type: true - required: - - remote-endpoint - - required: - - endpoint - clocks: minItems: 1 maxItems: 3 @@ -75,6 +69,7 @@ additionalProperties: false examples: - | #include <dt-bindings/clock/marvell,mmp2.h> + #include <dt-bindings/power/marvell,mmp2.h> camera@d420a000 { compatible = "marvell,mmp2-ccic"; @@ -84,6 +79,7 @@ examples: clock-names = "axi"; #clock-cells = <0>; clock-output-names = "mclk"; + power-domains = <&soc_clocks MMP3_POWER_DOMAIN_CAMERA>; port { camera0_0: endpoint { diff --git a/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml b/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml index 4e81a47e60ac..d91575b8ebb9 100644 --- a/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml +++ b/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml @@ -33,10 +33,7 @@ properties: - const: mclk port: - type: object - description: - A node containing input port nodes with endpoint definitions as documented - in Documentation/devicetree/bindings/media/video-interfaces.txt + $ref: /schemas/graph.yaml#/properties/port required: - compatible diff --git a/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml index 0668332959e7..be47a7b62ca9 100644 --- a/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml +++ b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml @@ -58,35 +58,22 @@ properties: Differential receiver (HS-RX) settle time ports: - type: object - description: - A node containing input and output port nodes with endpoint definitions - as documented in - Documentation/devicetree/bindings/media/video-interfaces.txt + $ref: /schemas/graph.yaml#/properties/ports properties: - '#address-cells': - const: 1 - - '#size-cells': - const: 0 - port@0: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: Input port node, single endpoint describing the CSI-2 transmitter. properties: - reg: - const: 0 - endpoint: - type: object + $ref: video-interfaces.yaml# + unevaluatedProperties: false properties: data-lanes: - $ref: /schemas/types.yaml#/definitions/uint32-array - description: See ../video-interfaces.txt oneOf: - items: - const: 1 @@ -94,18 +81,11 @@ properties: - const: 1 - const: 2 - remote-endpoint: true - required: - data-lanes - - remote-endpoint - - additionalProperties: false - - additionalProperties: false port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Output port node diff --git a/Documentation/devicetree/bindings/media/renesas,ceu.yaml b/Documentation/devicetree/bindings/media/renesas,ceu.yaml index c7e1e4fe67e6..50e0740af15a 100644 --- a/Documentation/devicetree/bindings/media/renesas,ceu.yaml +++ b/Documentation/devicetree/bindings/media/renesas,ceu.yaml @@ -34,18 +34,15 @@ properties: maxItems: 1 port: - type: object - additionalProperties: false + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false properties: endpoint: - type: object - additionalProperties: false + $ref: video-interfaces.yaml# + unevaluatedProperties: false - # Properties described in - # Documentation/devicetree/bindings/media/video-interfaces.txt properties: - remote-endpoint: true hsync-active: true vsync-active: true field-even-active: false @@ -53,12 +50,6 @@ properties: enum: [8, 16] default: 8 - required: - - remote-endpoint - - required: - - endpoint - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/media/renesas,csi2.yaml b/Documentation/devicetree/bindings/media/renesas,csi2.yaml index 533c2f181db7..20396f1be999 100644 --- a/Documentation/devicetree/bindings/media/renesas,csi2.yaml +++ b/Documentation/devicetree/bindings/media/renesas,csi2.yaml @@ -46,24 +46,19 @@ properties: maxItems: 1 ports: - type: object - description: - A node containing input and output port nodes with endpoint definitions - as documented in - Documentation/devicetree/bindings/media/video-interfaces.txt + $ref: /schemas/graph.yaml#/properties/ports properties: port@0: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: Input port node, single endpoint describing the CSI-2 transmitter. properties: - reg: - const: 0 - endpoint: - type: object + $ref: video-interfaces.yaml# + unevaluatedProperties: false properties: clock-lanes: @@ -72,50 +67,19 @@ properties: data-lanes: maxItems: 1 - remote-endpoint: true - required: - clock-lanes - data-lanes - - remote-endpoint - - additionalProperties: false - - additionalProperties: false port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Output port node, multiple endpoints describing all the R-Car VIN modules connected the CSI-2 receiver. - properties: - '#address-cells': - const: 1 - - '#size-cells': - const: 0 - - reg: - const: 1 - - patternProperties: - "^endpoint@[0-9a-f]$": - type: object - - properties: - reg: - maxItems: 1 - - remote-endpoint: true - - required: - - reg - - remote-endpoint - - additionalProperties: false - - additionalProperties: false + required: + - port@0 + - port@1 required: - compatible diff --git a/Documentation/devicetree/bindings/media/renesas,vin.yaml b/Documentation/devicetree/bindings/media/renesas,vin.yaml index ad2fe660364b..fe7c4cbfe4ba 100644 --- a/Documentation/devicetree/bindings/media/renesas,vin.yaml +++ b/Documentation/devicetree/bindings/media/renesas,vin.yaml @@ -69,15 +69,15 @@ properties: #The per-board settings for Gen2 and RZ/G1 platforms: port: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: - A node containing a parallel input with a single endpoint definitions as - documented in - Documentation/devicetree/bindings/media/video-interfaces.txt + A node containing a parallel input properties: endpoint: - type: object + $ref: video-interfaces.yaml# + unevaluatedProperties: false properties: hsync-active: @@ -106,15 +106,6 @@ properties: data-active: true - remote-endpoint: true - - required: - - remote-endpoint - - additionalProperties: false - - additionalProperties: false - #The per-board settings for Gen3 and RZ/G2 platforms: renesas,id: description: VIN channel number @@ -123,23 +114,18 @@ properties: maximum: 15 ports: - type: object - description: - A node containing input nodes with endpoint definitions as documented in - Documentation/devicetree/bindings/media/video-interfaces.txt + $ref: /schemas/graph.yaml#/properties/ports properties: port@0: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Input port node, single endpoint describing a parallel input source. properties: - reg: - const: 0 - endpoint: - type: object + $ref: video-interfaces.yaml# + unevaluatedProperties: false properties: hsync-active: @@ -168,98 +154,29 @@ properties: data-active: true - remote-endpoint: true - - required: - - remote-endpoint - - additionalProperties: false - - required: - - endpoint - - additionalProperties: false - port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: Input port node, multiple endpoints describing all the R-Car CSI-2 modules connected the VIN. properties: - '#address-cells': - const: 1 - - '#size-cells': - const: 0 - - reg: - const: 1 - endpoint@0: - type: object + $ref: /schemas/graph.yaml#/properties/endpoint description: Endpoint connected to CSI20. - properties: - reg: - const: 0 - - remote-endpoint: true - - required: - - reg - - remote-endpoint - - additionalProperties: false - endpoint@1: - type: object + $ref: /schemas/graph.yaml#/properties/endpoint description: Endpoint connected to CSI21. - properties: - reg: - const: 1 - - remote-endpoint: true - - required: - - reg - - remote-endpoint - - additionalProperties: false - endpoint@2: - type: object + $ref: /schemas/graph.yaml#/properties/endpoint description: Endpoint connected to CSI40. - properties: - reg: - const: 2 - - remote-endpoint: true - - required: - - reg - - remote-endpoint - - additionalProperties: false - endpoint@3: - type: object + $ref: /schemas/graph.yaml#/properties/endpoint description: Endpoint connected to CSI41. - properties: - reg: - const: 3 - - remote-endpoint: true - - required: - - reg - - remote-endpoint - - additionalProperties: false - anyOf: - required: - endpoint@0 @@ -270,8 +187,6 @@ properties: - required: - endpoint@3 - additionalProperties: false - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/media/rockchip-isp1.yaml b/Documentation/devicetree/bindings/media/rockchip-isp1.yaml index 2004c054ed1a..a6b1eff879ed 100644 --- a/Documentation/devicetree/bindings/media/rockchip-isp1.yaml +++ b/Documentation/devicetree/bindings/media/rockchip-isp1.yaml @@ -56,56 +56,26 @@ properties: power-domains: maxItems: 1 - # See ./video-interfaces.txt for details ports: - type: object - additionalProperties: false + $ref: /schemas/graph.yaml#/properties/ports properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - port@0: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: connection point for sensors at MIPI-DPHY RX0 - additionalProperties: false properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - - reg: - const: 0 - - patternProperties: endpoint: - type: object - additionalProperties: false + $ref: video-interfaces.yaml# + unevaluatedProperties: false properties: - reg: - maxItems: 1 - data-lanes: minItems: 1 maxItems: 4 - remote-endpoint: true - - required: - - reg - - "#address-cells" - - "#size-cells" - required: - - "#address-cells" - - "#size-cells" - port@0 required: diff --git a/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml b/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml index c18574bb3e81..41e1d0cd80e5 100644 --- a/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml +++ b/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml @@ -37,16 +37,15 @@ properties: maxItems: 1 port: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false description: - DCMI supports a single port node with parallel bus. It should contain - one 'port' child node with child 'endpoint' node. Please refer to the - bindings defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. + DCMI supports a single port node with parallel bus. properties: endpoint: - type: object + $ref: video-interfaces.yaml# + unevaluatedProperties: false properties: bus-type: @@ -57,8 +56,6 @@ properties: enum: [8, 10, 12, 14] default: 8 - remote-endpoint: true - allOf: - if: properties: @@ -73,14 +70,9 @@ properties: enum: [8] required: - - remote-endpoint - bus-type - pclk-sample - unevaluatedProperties: false - - additionalProperties: false - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/media/ti,cal.yaml b/Documentation/devicetree/bindings/media/ti,cal.yaml index 5e066629287d..65177cd69514 100644 --- a/Documentation/devicetree/bindings/media/ti,cal.yaml +++ b/Documentation/devicetree/bindings/media/ti,cal.yaml @@ -15,10 +15,7 @@ description: |- processing capability to connect CSI2 image-sensor modules to the DRA72x device. - CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes - should contain a 'port' child node with child 'endpoint' node. Please - refer to the bindings defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. + CAL supports 2 camera port nodes on MIPI bus. properties: compatible: @@ -67,31 +64,19 @@ properties: Documentation/devicetree/bindings/power/power_domain.txt maxItems: 1 - # See ./video-interfaces.txt for details ports: - type: object - additionalProperties: false + $ref: /schemas/graph.yaml#/properties/ports properties: - "#address-cells": - const: 1 - - "#size-cells": - const: 0 - port@0: - type: object - additionalProperties: false + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: CSI2 Port #0 properties: - reg: - const: 0 - description: CSI2 Port #0 - - patternProperties: endpoint: - type: object - additionalProperties: false + $ref: video-interfaces.yaml# + unevaluatedProperties: false properties: clock-lanes: @@ -101,24 +86,15 @@ properties: minItems: 1 maxItems: 4 - remote-endpoint: true - - required: - - reg - port@1: - type: object - additionalProperties: false + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: CSI2 Port #1 properties: - reg: - const: 1 - description: CSI2 Port #1 - - patternProperties: endpoint: - type: object - additionalProperties: false + $ref: video-interfaces.yaml# + unevaluatedProperties: false properties: clock-lanes: @@ -128,14 +104,7 @@ properties: minItems: 1 maxItems: 4 - remote-endpoint: true - - required: - - reg - required: - - "#address-cells" - - "#size-cells" - port@0 required: diff --git a/Documentation/devicetree/bindings/media/video-interface-devices.yaml b/Documentation/devicetree/bindings/media/video-interface-devices.yaml new file mode 100644 index 000000000000..4527f56a5a6e --- /dev/null +++ b/Documentation/devicetree/bindings/media/video-interface-devices.yaml @@ -0,0 +1,406 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/video-interface-devices.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common bindings for video receiver and transmitter devices + +maintainers: + - Jacopo Mondi <jacopo@jmondi.org> + - Sakari Ailus <sakari.ailus@linux.intel.com> + +properties: + flash-leds: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + An array of phandles, each referring to a flash LED, a sub-node of the LED + driver device node. + + lens-focus: + $ref: /schemas/types.yaml#/definitions/phandle + description: + A phandle to the node of the focus lens controller. + + rotation: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 90, 180, 270 ] + description: | + The camera rotation is expressed as the angular difference in degrees + between two reference systems, one relative to the camera module, and one + defined on the external world scene to be captured when projected on the + image sensor pixel array. + + A camera sensor has a 2-dimensional reference system 'Rc' defined by its + pixel array read-out order. The origin is set to the first pixel being + read out, the X-axis points along the column read-out direction towards + the last columns, and the Y-axis along the row read-out direction towards + the last row. + + A typical example for a sensor with a 2592x1944 pixel array matrix + observed from the front is: + + 2591 X-axis 0 + <------------------------+ 0 + .......... ... ..........! + .......... ... ..........! Y-axis + ... ! + .......... ... ..........! + .......... ... ..........! 1943 + V + + The external world scene reference system 'Rs' is a 2-dimensional + reference system on the focal plane of the camera module. The origin is + placed on the top-left corner of the visible scene, the X-axis points + towards the right, and the Y-axis points towards the bottom of the scene. + The top, bottom, left and right directions are intentionally not defined + and depend on the environment in which the camera is used. + + A typical example of a (very common) picture of a shark swimming from left + to right, as seen from the camera, is: + + 0 X-axis + 0 +-------------------------------------> + ! + ! + ! + ! |\____)\___ + ! ) _____ __`< + ! |/ )/ + ! + ! + ! + V + Y-axis + + with the reference system 'Rs' placed on the camera focal plane: + + ¸.·˙! + ¸.·˙ ! + _ ¸.·˙ ! + +-/ \-+¸.·˙ ! + | (o) | ! Camera focal plane + +-----+˙·.¸ ! + ˙·.¸ ! + ˙·.¸ ! + ˙·.¸! + + When projected on the sensor's pixel array, the image and the associated + reference system 'Rs' are typically (but not always) inverted, due to the + camera module's lens optical inversion effect. + + Assuming the above represented scene of the swimming shark, the lens + inversion projects the scene and its reference system onto the sensor + pixel array, seen from the front of the camera sensor, as follows: + + Y-axis + ^ + ! + ! + ! + ! |\_____)\__ + ! ) ____ ___.< + ! |/ )/ + ! + ! + ! + 0 +-------------------------------------> + 0 X-axis + + Note the shark being upside-down. + + The resulting projected reference system is named 'Rp'. + + The camera rotation property is then defined as the angular difference in + the counter-clockwise direction between the camera reference system 'Rc' + and the projected scene reference system 'Rp'. It is expressed in degrees + as a number in the range [0, 360[. + + Examples + + 0 degrees camera rotation: + + + Y-Rp + ^ + Y-Rc ! + ^ ! + ! ! + ! ! + ! ! + ! ! + ! ! + ! ! + ! ! + ! 0 +-------------------------------------> + ! 0 X-Rp + 0 +-------------------------------------> + 0 X-Rc + + + X-Rc 0 + <------------------------------------+ 0 + X-Rp 0 ! + <------------------------------------+ 0 ! + ! ! + ! ! + ! ! + ! ! + ! ! + ! ! + ! ! + ! V + ! Y-Rc + V + Y-Rp + + 90 degrees camera rotation: + + 0 Y-Rc + 0 +--------------------> + ! Y-Rp + ! ^ + ! ! + ! ! + ! ! + ! ! + ! ! + ! ! + ! ! + ! ! + ! ! + ! 0 +-------------------------------------> + ! 0 X-Rp + ! + ! + ! + ! + V + X-Rc + + 180 degrees camera rotation: + + 0 + <------------------------------------+ 0 + X-Rc ! + Y-Rp ! + ^ ! + ! ! + ! ! + ! ! + ! ! + ! ! + ! ! + ! V + ! Y-Rc + 0 +-------------------------------------> + 0 X-Rp + + 270 degrees camera rotation: + + 0 Y-Rc + 0 +--------------------> + ! 0 + ! <-----------------------------------+ 0 + ! X-Rp ! + ! ! + ! ! + ! ! + ! ! + ! ! + ! ! + ! ! + ! ! + ! V + ! Y-Rp + ! + ! + ! + ! + V + X-Rc + + + Example one - Webcam + + A camera module installed on the user facing part of a laptop screen + casing used for video calls. The captured images are meant to be displayed + in landscape mode (width > height) on the laptop screen. + + The camera is typically mounted upside-down to compensate the lens optical + inversion effect: + + Y-Rp + Y-Rc ^ + ^ ! + ! ! + ! ! |\_____)\__ + ! ! ) ____ ___.< + ! ! |/ )/ + ! ! + ! ! + ! ! + ! 0 +-------------------------------------> + ! 0 X-Rp + 0 +-------------------------------------> + 0 X-Rc + + The two reference systems are aligned, the resulting camera rotation is + 0 degrees, no rotation correction needs to be applied to the resulting + image once captured to memory buffers to correctly display it to users: + + +--------------------------------------+ + ! ! + ! ! + ! ! + ! |\____)\___ ! + ! ) _____ __`< ! + ! |/ )/ ! + ! ! + ! ! + ! ! + +--------------------------------------+ + + If the camera sensor is not mounted upside-down to compensate for the lens + optical inversion, the two reference systems will not be aligned, with + 'Rp' being rotated 180 degrees relatively to 'Rc': + + + X-Rc 0 + <------------------------------------+ 0 + ! + Y-Rp ! + ^ ! + ! ! + ! |\_____)\__ ! + ! ) ____ ___.< ! + ! |/ )/ ! + ! ! + ! ! + ! V + ! Y-Rc + 0 +-------------------------------------> + 0 X-Rp + + The image once captured to memory will then be rotated by 180 degrees: + + +--------------------------------------+ + ! ! + ! ! + ! ! + ! __/(_____/| ! + ! >.___ ____ ( ! + ! \( \| ! + ! ! + ! ! + ! ! + +--------------------------------------+ + + A software rotation correction of 180 degrees should be applied to + correctly display the image: + + +--------------------------------------+ + ! ! + ! ! + ! ! + ! |\____)\___ ! + ! ) _____ __`< ! + ! |/ )/ ! + ! ! + ! ! + ! ! + +--------------------------------------+ + + Example two - Phone camera + + A camera installed on the back side of a mobile device facing away from + the user. The captured images are meant to be displayed in portrait mode + (height > width) to match the device screen orientation and the device + usage orientation used when taking the picture. + + The camera sensor is typically mounted with its pixel array longer side + aligned to the device longer side, upside-down mounted to compensate for + the lens optical inversion effect: + + 0 Y-Rc + 0 +--------------------> + ! Y-Rp + ! ^ + ! ! + ! ! + ! ! + ! ! |\_____)\__ + ! ! ) ____ ___.< + ! ! |/ )/ + ! ! + ! ! + ! ! + ! 0 +-------------------------------------> + ! 0 X-Rp + ! + ! + ! + ! + V + X-Rc + + The two reference systems are not aligned and the 'Rp' reference system is + rotated by 90 degrees in the counter-clockwise direction relatively to the + 'Rc' reference system. + + The image once captured to memory will be rotated: + + +-------------------------------------+ + | _ _ | + | \ / | + | | | | + | | | | + | | > | + | < | | + | | | | + | . | + | V | + +-------------------------------------+ + + A correction of 90 degrees in counter-clockwise direction has to be + applied to correctly display the image in portrait mode on the device + screen: + + +--------------------+ + | | + | | + | | + | | + | | + | | + | |\____)\___ | + | ) _____ __`< | + | |/ )/ | + | | + | | + | | + | | + | | + +--------------------+ + + orientation: + description: + The orientation of a device (typically an image sensor or a flash LED) + describing its mounting position relative to the usage orientation of the + system where the device is installed on. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + # Front. The device is mounted on the front facing side of the system. For + # mobile devices such as smartphones, tablets and laptops the front side + # is the user facing side. + - 0 + # Back. The device is mounted on the back side of the system, which is + # defined as the opposite side of the front facing one. + - 1 + # External. The device is not attached directly to the system but is + # attached in a way that allows it to move freely. + - 2 + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/media/video-interfaces.txt b/Documentation/devicetree/bindings/media/video-interfaces.txt index 3920f25a9123..8fcf5f52bf5b 100644 --- a/Documentation/devicetree/bindings/media/video-interfaces.txt +++ b/Documentation/devicetree/bindings/media/video-interfaces.txt @@ -1,639 +1 @@ -Common bindings for video receiver and transmitter interfaces - -General concept ---------------- - -Video data pipelines usually consist of external devices, e.g. camera sensors, -controlled over an I2C, SPI or UART bus, and SoC internal IP blocks, including -video DMA engines and video data processors. - -SoC internal blocks are described by DT nodes, placed similarly to other SoC -blocks. External devices are represented as child nodes of their respective -bus controller nodes, e.g. I2C. - -Data interfaces on all video devices are described by their child 'port' nodes. -Configuration of a port depends on other devices participating in the data -transfer and is described by 'endpoint' subnodes. - -device { - ... - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - ... - endpoint@0 { ... }; - endpoint@1 { ... }; - }; - port@1 { ... }; - }; -}; - -If a port can be configured to work with more than one remote device on the same -bus, an 'endpoint' child node must be provided for each of them. If more than -one port is present in a device node or there is more than one endpoint at a -port, or port node needs to be associated with a selected hardware interface, -a common scheme using '#address-cells', '#size-cells' and 'reg' properties is -used. - -All 'port' nodes can be grouped under optional 'ports' node, which allows to -specify #address-cells, #size-cells properties independently for the 'port' -and 'endpoint' nodes and any child device nodes a device might have. - -Two 'endpoint' nodes are linked with each other through their 'remote-endpoint' -phandles. An endpoint subnode of a device contains all properties needed for -configuration of this device for data exchange with other device. In most -cases properties at the peer 'endpoint' nodes will be identical, however they -might need to be different when there is any signal modifications on the bus -between two devices, e.g. there are logic signal inverters on the lines. - -It is allowed for multiple endpoints at a port to be active simultaneously, -where supported by a device. For example, in case where a data interface of -a device is partitioned into multiple data busses, e.g. 16-bit input port -divided into two separate ITU-R BT.656 8-bit busses. In such case bus-width -and data-shift properties can be used to assign physical data lines to each -endpoint node (logical bus). - -Documenting bindings for devices --------------------------------- - -All required and optional bindings the device supports shall be explicitly -documented in device DT binding documentation. This also includes port and -endpoint nodes for the device, including unit-addresses and reg properties where -relevant. - -Please also see Documentation/devicetree/bindings/graph.txt . - -Required properties -------------------- - -If there is more than one 'port' or more than one 'endpoint' node or 'reg' -property is present in port and/or endpoint nodes the following properties -are required in a relevant parent node: - - - #address-cells : number of cells required to define port/endpoint - identifier, should be 1. - - #size-cells : should be zero. - - -Optional properties -------------------- - -- flash-leds: An array of phandles, each referring to a flash LED, a sub-node - of the LED driver device node. - -- lens-focus: A phandle to the node of the focus lens controller. - -- rotation: The camera rotation is expressed as the angular difference in - degrees between two reference systems, one relative to the camera module, and - one defined on the external world scene to be captured when projected on the - image sensor pixel array. - - A camera sensor has a 2-dimensional reference system 'Rc' defined by - its pixel array read-out order. The origin is set to the first pixel - being read out, the X-axis points along the column read-out direction - towards the last columns, and the Y-axis along the row read-out - direction towards the last row. - - A typical example for a sensor with a 2592x1944 pixel array matrix - observed from the front is: - - 2591 X-axis 0 - <------------------------+ 0 - .......... ... ..........! - .......... ... ..........! Y-axis - ... ! - .......... ... ..........! - .......... ... ..........! 1943 - V - - The external world scene reference system 'Rs' is a 2-dimensional - reference system on the focal plane of the camera module. The origin is - placed on the top-left corner of the visible scene, the X-axis points - towards the right, and the Y-axis points towards the bottom of the - scene. The top, bottom, left and right directions are intentionally not - defined and depend on the environment in which the camera is used. - - A typical example of a (very common) picture of a shark swimming from - left to right, as seen from the camera, is: - - 0 X-axis - 0 +-------------------------------------> - ! - ! - ! - ! |\____)\___ - ! ) _____ __`< - ! |/ )/ - ! - ! - ! - V - Y-axis - - with the reference system 'Rs' placed on the camera focal plane: - - ¸.·˙! - ¸.·˙ ! - _ ¸.·˙ ! - +-/ \-+¸.·˙ ! - | (o) | ! Camera focal plane - +-----+˙·.¸ ! - ˙·.¸ ! - ˙·.¸ ! - ˙·.¸! - - When projected on the sensor's pixel array, the image and the associated - reference system 'Rs' are typically (but not always) inverted, due to - the camera module's lens optical inversion effect. - - Assuming the above represented scene of the swimming shark, the lens - inversion projects the scene and its reference system onto the sensor - pixel array, seen from the front of the camera sensor, as follows: - - Y-axis - ^ - ! - ! - ! - ! |\_____)\__ - ! ) ____ ___.< - ! |/ )/ - ! - ! - ! - 0 +-------------------------------------> - 0 X-axis - - Note the shark being upside-down. - - The resulting projected reference system is named 'Rp'. - - The camera rotation property is then defined as the angular difference - in the counter-clockwise direction between the camera reference system - 'Rc' and the projected scene reference system 'Rp'. It is expressed in - degrees as a number in the range [0, 360[. - - Examples - - 0 degrees camera rotation: - - - Y-Rp - ^ - Y-Rc ! - ^ ! - ! ! - ! ! - ! ! - ! ! - ! ! - ! ! - ! ! - ! 0 +-------------------------------------> - ! 0 X-Rp - 0 +-------------------------------------> - 0 X-Rc - - - X-Rc 0 - <------------------------------------+ 0 - X-Rp 0 ! - <------------------------------------+ 0 ! - ! ! - ! ! - ! ! - ! ! - ! ! - ! ! - ! ! - ! V - ! Y-Rc - V - Y-Rp - - 90 degrees camera rotation: - - 0 Y-Rc - 0 +--------------------> - ! Y-Rp - ! ^ - ! ! - ! ! - ! ! - ! ! - ! ! - ! ! - ! ! - ! ! - ! ! - ! 0 +-------------------------------------> - ! 0 X-Rp - ! - ! - ! - ! - V - X-Rc - - 180 degrees camera rotation: - - 0 - <------------------------------------+ 0 - X-Rc ! - Y-Rp ! - ^ ! - ! ! - ! ! - ! ! - ! ! - ! ! - ! ! - ! V - ! Y-Rc - 0 +-------------------------------------> - 0 X-Rp - - 270 degrees camera rotation: - - 0 Y-Rc - 0 +--------------------> - ! 0 - ! <-----------------------------------+ 0 - ! X-Rp ! - ! ! - ! ! - ! ! - ! ! - ! ! - ! ! - ! ! - ! ! - ! V - ! Y-Rp - ! - ! - ! - ! - V - X-Rc - - - Example one - Webcam - - A camera module installed on the user facing part of a laptop screen - casing used for video calls. The captured images are meant to be - displayed in landscape mode (width > height) on the laptop screen. - - The camera is typically mounted upside-down to compensate the lens - optical inversion effect: - - Y-Rp - Y-Rc ^ - ^ ! - ! ! - ! ! |\_____)\__ - ! ! ) ____ ___.< - ! ! |/ )/ - ! ! - ! ! - ! ! - ! 0 +-------------------------------------> - ! 0 X-Rp - 0 +-------------------------------------> - 0 X-Rc - - The two reference systems are aligned, the resulting camera rotation is - 0 degrees, no rotation correction needs to be applied to the resulting - image once captured to memory buffers to correctly display it to users: - - +--------------------------------------+ - ! ! - ! ! - ! ! - ! |\____)\___ ! - ! ) _____ __`< ! - ! |/ )/ ! - ! ! - ! ! - ! ! - +--------------------------------------+ - - If the camera sensor is not mounted upside-down to compensate for the - lens optical inversion, the two reference systems will not be aligned, - with 'Rp' being rotated 180 degrees relatively to 'Rc': - - - X-Rc 0 - <------------------------------------+ 0 - ! - Y-Rp ! - ^ ! - ! ! - ! |\_____)\__ ! - ! ) ____ ___.< ! - ! |/ )/ ! - ! ! - ! ! - ! V - ! Y-Rc - 0 +-------------------------------------> - 0 X-Rp - - The image once captured to memory will then be rotated by 180 degrees: - - +--------------------------------------+ - ! ! - ! ! - ! ! - ! __/(_____/| ! - ! >.___ ____ ( ! - ! \( \| ! - ! ! - ! ! - ! ! - +--------------------------------------+ - - A software rotation correction of 180 degrees should be applied to - correctly display the image: - - +--------------------------------------+ - ! ! - ! ! - ! ! - ! |\____)\___ ! - ! ) _____ __`< ! - ! |/ )/ ! - ! ! - ! ! - ! ! - +--------------------------------------+ - - Example two - Phone camera - - A camera installed on the back side of a mobile device facing away from - the user. The captured images are meant to be displayed in portrait mode - (height > width) to match the device screen orientation and the device - usage orientation used when taking the picture. - - The camera sensor is typically mounted with its pixel array longer side - aligned to the device longer side, upside-down mounted to compensate for - the lens optical inversion effect: - - 0 Y-Rc - 0 +--------------------> - ! Y-Rp - ! ^ - ! ! - ! ! - ! ! - ! ! |\_____)\__ - ! ! ) ____ ___.< - ! ! |/ )/ - ! ! - ! ! - ! ! - ! 0 +-------------------------------------> - ! 0 X-Rp - ! - ! - ! - ! - V - X-Rc - - The two reference systems are not aligned and the 'Rp' reference - system is rotated by 90 degrees in the counter-clockwise direction - relatively to the 'Rc' reference system. - - The image once captured to memory will be rotated: - - +-------------------------------------+ - | _ _ | - | \ / | - | | | | - | | | | - | | > | - | < | | - | | | | - | . | - | V | - +-------------------------------------+ - - A correction of 90 degrees in counter-clockwise direction has to be - applied to correctly display the image in portrait mode on the device - screen: - - +--------------------+ - | | - | | - | | - | | - | | - | | - | |\____)\___ | - | ) _____ __`< | - | |/ )/ | - | | - | | - | | - | | - | | - +--------------------+ - -- orientation: The orientation of a device (typically an image sensor or a flash - LED) describing its mounting position relative to the usage orientation of the - system where the device is installed on. - Possible values are: - 0 - Front. The device is mounted on the front facing side of the system. - For mobile devices such as smartphones, tablets and laptops the front side is - the user facing side. - 1 - Back. The device is mounted on the back side of the system, which is - defined as the opposite side of the front facing one. - 2 - External. The device is not attached directly to the system but is - attached in a way that allows it to move freely. - -Optional endpoint properties ----------------------------- - -- remote-endpoint: phandle to an 'endpoint' subnode of a remote device node. -- slave-mode: a boolean property indicating that the link is run in slave mode. - The default when this property is not specified is master mode. In the slave - mode horizontal and vertical synchronization signals are provided to the - slave device (data source) by the master device (data sink). In the master - mode the data source device is also the source of the synchronization signals. -- bus-type: data bus type. Possible values are: - 1 - MIPI CSI-2 C-PHY - 2 - MIPI CSI1 - 3 - CCP2 - 4 - MIPI CSI-2 D-PHY - 5 - Parallel - 6 - Bt.656 -- bus-width: number of data lines actively used, valid for the parallel busses. -- data-shift: on the parallel data busses, if bus-width is used to specify the - number of data lines, data-shift can be used to specify which data lines are - used, e.g. "bus-width=<8>; data-shift=<2>;" means, that lines 9:2 are used. -- hsync-active: active state of the HSYNC signal, 0/1 for LOW/HIGH respectively. -- vsync-active: active state of the VSYNC signal, 0/1 for LOW/HIGH respectively. - Note, that if HSYNC and VSYNC polarities are not specified, embedded - synchronization may be required, where supported. -- data-active: similar to HSYNC and VSYNC, specifies data line polarity. -- data-enable-active: similar to HSYNC and VSYNC, specifies the data enable - signal polarity. -- field-even-active: field signal level during the even field data transmission. -- pclk-sample: sample data on rising (1) or falling (0) edge of the pixel clock - signal. -- sync-on-green-active: active state of Sync-on-green (SoG) signal, 0/1 for - LOW/HIGH respectively. -- data-lanes: an array of physical data lane indexes. Position of an entry - determines the logical lane number, while the value of an entry indicates - physical lane, e.g. for 2-lane MIPI CSI-2 bus we could have - "data-lanes = <1 2>;", assuming the clock lane is on hardware lane 0. - If the hardware does not support lane reordering, monotonically - incremented values shall be used from 0 or 1 onwards, depending on - whether or not there is also a clock lane. This property is valid for - serial busses only (e.g. MIPI CSI-2). -- clock-lanes: an array of physical clock lane indexes. Position of an entry - determines the logical lane number, while the value of an entry indicates - physical lane, e.g. for a MIPI CSI-2 bus we could have "clock-lanes = <0>;", - which places the clock lane on hardware lane 0. This property is valid for - serial busses only (e.g. MIPI CSI-2). Note that for the MIPI CSI-2 bus this - array contains only one entry. -- clock-noncontinuous: a boolean property to allow MIPI CSI-2 non-continuous - clock mode. -- link-frequencies: Allowed data bus frequencies. For MIPI CSI-2, for - instance, this is the actual frequency of the bus, not bits per clock per - lane value. An array of 64-bit unsigned integers. -- lane-polarities: an array of polarities of the lanes starting from the clock - lane and followed by the data lanes in the same order as in data-lanes. - Valid values are 0 (normal) and 1 (inverted). The length of the array - should be the combined length of data-lanes and clock-lanes properties. - If the lane-polarities property is omitted, the value must be interpreted - as 0 (normal). This property is valid for serial busses only. -- strobe: Whether the clock signal is used as clock (0) or strobe (1). Used - with CCP2, for instance. - -Example -------- - -The example snippet below describes two data pipelines. ov772x and imx074 are -camera sensors with a parallel and serial (MIPI CSI-2) video bus respectively. -Both sensors are on the I2C control bus corresponding to the i2c0 controller -node. ov772x sensor is linked directly to the ceu0 video host interface. -imx074 is linked to ceu0 through the MIPI CSI-2 receiver (csi2). ceu0 has a -(single) DMA engine writing captured data to memory. ceu0 node has a single -'port' node which may indicate that at any time only one of the following data -pipelines can be active: ov772x -> ceu0 or imx074 -> csi2 -> ceu0. - - ceu0: ceu@fe910000 { - compatible = "renesas,sh-mobile-ceu"; - reg = <0xfe910000 0xa0>; - interrupts = <0x880>; - - mclk: master_clock { - compatible = "renesas,ceu-clock"; - #clock-cells = <1>; - clock-frequency = <50000000>; /* Max clock frequency */ - clock-output-names = "mclk"; - }; - - port { - #address-cells = <1>; - #size-cells = <0>; - - /* Parallel bus endpoint */ - ceu0_1: endpoint@1 { - reg = <1>; /* Local endpoint # */ - remote = <&ov772x_1_1>; /* Remote phandle */ - bus-width = <8>; /* Used data lines */ - data-shift = <2>; /* Lines 9:2 are used */ - - /* If hsync-active/vsync-active are missing, - embedded BT.656 sync is used */ - hsync-active = <0>; /* Active low */ - vsync-active = <0>; /* Active low */ - data-active = <1>; /* Active high */ - pclk-sample = <1>; /* Rising */ - }; - - /* MIPI CSI-2 bus endpoint */ - ceu0_0: endpoint@0 { - reg = <0>; - remote = <&csi2_2>; - }; - }; - }; - - i2c0: i2c@fff20000 { - ... - ov772x_1: camera@21 { - compatible = "ovti,ov772x"; - reg = <0x21>; - vddio-supply = <®ulator1>; - vddcore-supply = <®ulator2>; - - clock-frequency = <20000000>; - clocks = <&mclk 0>; - clock-names = "xclk"; - - port { - /* With 1 endpoint per port no need for addresses. */ - ov772x_1_1: endpoint { - bus-width = <8>; - remote-endpoint = <&ceu0_1>; - hsync-active = <1>; - vsync-active = <0>; /* Who came up with an - inverter here ?... */ - data-active = <1>; - pclk-sample = <1>; - }; - }; - }; - - imx074: camera@1a { - compatible = "sony,imx074"; - reg = <0x1a>; - vddio-supply = <®ulator1>; - vddcore-supply = <®ulator2>; - - clock-frequency = <30000000>; /* Shared clock with ov772x_1 */ - clocks = <&mclk 0>; - clock-names = "sysclk"; /* Assuming this is the - name in the datasheet */ - port { - imx074_1: endpoint { - clock-lanes = <0>; - data-lanes = <1 2>; - remote-endpoint = <&csi2_1>; - }; - }; - }; - }; - - csi2: csi2@ffc90000 { - compatible = "renesas,sh-mobile-csi2"; - reg = <0xffc90000 0x1000>; - interrupts = <0x17a0>; - #address-cells = <1>; - #size-cells = <0>; - - port@1 { - compatible = "renesas,csi2c"; /* One of CSI2I and CSI2C. */ - reg = <1>; /* CSI-2 PHY #1 of 2: PHY_S, - PHY_M has port address 0, - is unused. */ - csi2_1: endpoint { - clock-lanes = <0>; - data-lanes = <2 1>; - remote-endpoint = <&imx074_1>; - }; - }; - port@2 { - reg = <2>; /* port 2: link to the CEU */ - - csi2_2: endpoint { - remote-endpoint = <&ceu0_0>; - }; - }; - }; +This file has moved to video-interfaces.yaml and video-interface-devices.yaml. diff --git a/Documentation/devicetree/bindings/media/video-interfaces.yaml b/Documentation/devicetree/bindings/media/video-interfaces.yaml new file mode 100644 index 000000000000..0a7a73fd59f2 --- /dev/null +++ b/Documentation/devicetree/bindings/media/video-interfaces.yaml @@ -0,0 +1,344 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/video-interfaces.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common bindings for video receiver and transmitter interface endpoints + +maintainers: + - Sakari Ailus <sakari.ailus@linux.intel.com> + - Laurent Pinchart <laurent.pinchart@ideasonboard.com> + +description: | + Video data pipelines usually consist of external devices, e.g. camera sensors, + controlled over an I2C, SPI or UART bus, and SoC internal IP blocks, including + video DMA engines and video data processors. + + SoC internal blocks are described by DT nodes, placed similarly to other SoC + blocks. External devices are represented as child nodes of their respective + bus controller nodes, e.g. I2C. + + Data interfaces on all video devices are described by their child 'port' nodes. + Configuration of a port depends on other devices participating in the data + transfer and is described by 'endpoint' subnodes. + + device { + ... + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + ... + endpoint@0 { ... }; + endpoint@1 { ... }; + }; + port@1 { ... }; + }; + }; + + If a port can be configured to work with more than one remote device on the same + bus, an 'endpoint' child node must be provided for each of them. If more than + one port is present in a device node or there is more than one endpoint at a + port, or port node needs to be associated with a selected hardware interface, + a common scheme using '#address-cells', '#size-cells' and 'reg' properties is + used. + + All 'port' nodes can be grouped under optional 'ports' node, which allows to + specify #address-cells, #size-cells properties independently for the 'port' + and 'endpoint' nodes and any child device nodes a device might have. + + Two 'endpoint' nodes are linked with each other through their 'remote-endpoint' + phandles. An endpoint subnode of a device contains all properties needed for + configuration of this device for data exchange with other device. In most + cases properties at the peer 'endpoint' nodes will be identical, however they + might need to be different when there is any signal modifications on the bus + between two devices, e.g. there are logic signal inverters on the lines. + + It is allowed for multiple endpoints at a port to be active simultaneously, + where supported by a device. For example, in case where a data interface of + a device is partitioned into multiple data busses, e.g. 16-bit input port + divided into two separate ITU-R BT.656 8-bit busses. In such case bus-width + and data-shift properties can be used to assign physical data lines to each + endpoint node (logical bus). + + Documenting bindings for devices + -------------------------------- + + All required and optional bindings the device supports shall be explicitly + documented in device DT binding documentation. This also includes port and + endpoint nodes for the device, including unit-addresses and reg properties + where relevant. + +allOf: + - $ref: /schemas/graph.yaml#/$defs/endpoint-base + +properties: + slave-mode: + type: boolean + description: + Indicates that the link is run in slave mode. The default when this + property is not specified is master mode. In the slave mode horizontal and + vertical synchronization signals are provided to the slave device (data + source) by the master device (data sink). In the master mode the data + source device is also the source of the synchronization signals. + + bus-type: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 1 # MIPI CSI-2 C-PHY + - 2 # MIPI CSI1 + - 3 # CCP2 + - 4 # MIPI CSI-2 D-PHY + - 5 # Parallel + - 6 # BT.656 + description: + Data bus type. + + bus-width: + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 64 + description: + Number of data lines actively used, valid for the parallel busses. + + data-shift: + $ref: /schemas/types.yaml#/definitions/uint32 + maximum: 64 + description: + On the parallel data busses, if bus-width is used to specify the number of + data lines, data-shift can be used to specify which data lines are used, + e.g. "bus-width=<8>; data-shift=<2>;" means, that lines 9:2 are used. + + hsync-active: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1 ] + description: + Active state of the HSYNC signal, 0/1 for LOW/HIGH respectively. + + vsync-active: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1 ] + description: + Active state of the VSYNC signal, 0/1 for LOW/HIGH respectively. Note, + that if HSYNC and VSYNC polarities are not specified, embedded + synchronization may be required, where supported. + + data-active: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1 ] + description: + Similar to HSYNC and VSYNC, specifies data line polarity. + + data-enable-active: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1 ] + description: + Similar to HSYNC and VSYNC, specifies the data enable signal polarity. + + field-even-active: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1 ] + description: + Field signal level during the even field data transmission. + + pclk-sample: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1 ] + description: + Sample data on rising (1) or falling (0) edge of the pixel clock signal. + + sync-on-green-active: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1 ] + description: + Active state of Sync-on-green (SoG) signal, 0/1 for LOW/HIGH respectively. + + data-lanes: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 8 + items: + # Assume up to 9 physical lane indices + maximum: 8 + description: + An array of physical data lane indexes. Position of an entry determines + the logical lane number, while the value of an entry indicates physical + lane, e.g. for 2-lane MIPI CSI-2 bus we could have "data-lanes = <1 2>;", + assuming the clock lane is on hardware lane 0. If the hardware does not + support lane reordering, monotonically incremented values shall be used + from 0 or 1 onwards, depending on whether or not there is also a clock + lane. This property is valid for serial busses only (e.g. MIPI CSI-2). + + clock-lanes: + $ref: /schemas/types.yaml#/definitions/uint32 + # Assume up to 9 physical lane indices + maximum: 8 + description: + Physical clock lane index. Position of an entry determines the logical + lane number, while the value of an entry indicates physical lane, e.g. for + a MIPI CSI-2 bus we could have "clock-lanes = <0>;", which places the + clock lane on hardware lane 0. This property is valid for serial busses + only (e.g. MIPI CSI-2). + + clock-noncontinuous: + type: boolean + description: + Allow MIPI CSI-2 non-continuous clock mode. + + link-frequencies: + $ref: /schemas/types.yaml#/definitions/uint64-array + description: + Allowed data bus frequencies. For MIPI CSI-2, for instance, this is the + actual frequency of the bus, not bits per clock per lane value. An array + of 64-bit unsigned integers. + + lane-polarities: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 9 + items: + enum: [ 0, 1 ] + description: + An array of polarities of the lanes starting from the clock lane and + followed by the data lanes in the same order as in data-lanes. Valid + values are 0 (normal) and 1 (inverted). The length of the array should be + the combined length of data-lanes and clock-lanes properties. If the + lane-polarities property is omitted, the value must be interpreted as 0 + (normal). This property is valid for serial busses only. + + strobe: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1 ] + description: + Whether the clock signal is used as clock (0) or strobe (1). Used with + CCP2, for instance. + +additionalProperties: true + +examples: + # The example snippet below describes two data pipelines. ov772x and imx074 + # are camera sensors with a parallel and serial (MIPI CSI-2) video bus + # respectively. Both sensors are on the I2C control bus corresponding to the + # i2c0 controller node. ov772x sensor is linked directly to the ceu0 video + # host interface. imx074 is linked to ceu0 through the MIPI CSI-2 receiver + # (csi2). ceu0 has a (single) DMA engine writing captured data to memory. + # ceu0 node has a single 'port' node which may indicate that at any time + # only one of the following data pipelines can be active: + # ov772x -> ceu0 or imx074 -> csi2 -> ceu0. + - | + ceu@fe910000 { + compatible = "renesas,sh-mobile-ceu"; + reg = <0xfe910000 0xa0>; + interrupts = <0x880>; + + mclk: master_clock { + compatible = "renesas,ceu-clock"; + #clock-cells = <1>; + clock-frequency = <50000000>; /* Max clock frequency */ + clock-output-names = "mclk"; + }; + + port { + #address-cells = <1>; + #size-cells = <0>; + + /* Parallel bus endpoint */ + ceu0_1: endpoint@1 { + reg = <1>; /* Local endpoint # */ + remote-endpoint = <&ov772x_1_1>; /* Remote phandle */ + bus-width = <8>; /* Used data lines */ + data-shift = <2>; /* Lines 9:2 are used */ + + /* If hsync-active/vsync-active are missing, + embedded BT.656 sync is used */ + hsync-active = <0>; /* Active low */ + vsync-active = <0>; /* Active low */ + data-active = <1>; /* Active high */ + pclk-sample = <1>; /* Rising */ + }; + + /* MIPI CSI-2 bus endpoint */ + ceu0_0: endpoint@0 { + reg = <0>; + remote-endpoint = <&csi2_2>; + }; + }; + }; + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + camera@21 { + compatible = "ovti,ov772x"; + reg = <0x21>; + vddio-supply = <®ulator1>; + vddcore-supply = <®ulator2>; + + clock-frequency = <20000000>; + clocks = <&mclk 0>; + clock-names = "xclk"; + + port { + /* With 1 endpoint per port no need for addresses. */ + ov772x_1_1: endpoint { + bus-width = <8>; + remote-endpoint = <&ceu0_1>; + hsync-active = <1>; + vsync-active = <0>; /* Who came up with an + inverter here ?... */ + data-active = <1>; + pclk-sample = <1>; + }; + }; + }; + + camera@1a { + compatible = "sony,imx074"; + reg = <0x1a>; + vddio-supply = <®ulator1>; + vddcore-supply = <®ulator2>; + + clock-frequency = <30000000>; /* Shared clock with ov772x_1 */ + clocks = <&mclk 0>; + clock-names = "sysclk"; /* Assuming this is the + name in the datasheet */ + port { + imx074_1: endpoint { + clock-lanes = <0>; + data-lanes = <1 2>; + remote-endpoint = <&csi2_1>; + }; + }; + }; + }; + + csi2: csi2@ffc90000 { + compatible = "renesas,sh-mobile-csi2"; + reg = <0xffc90000 0x1000>; + interrupts = <0x17a0>; + #address-cells = <1>; + #size-cells = <0>; + + port@1 { + compatible = "renesas,csi2c"; /* One of CSI2I and CSI2C. */ + reg = <1>; /* CSI-2 PHY #1 of 2: PHY_S, + PHY_M has port address 0, + is unused. */ + csi2_1: endpoint { + clock-lanes = <0>; + data-lanes = <2 1>; + remote-endpoint = <&imx074_1>; + }; + }; + port@2 { + reg = <2>; /* port 2: link to the CEU */ + + csi2_2: endpoint { + remote-endpoint = <&ceu0_0>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/xilinx/xlnx,csi2rxss.yaml b/Documentation/devicetree/bindings/media/xilinx/xlnx,csi2rxss.yaml index 2961a5b6872f..7d77823dbb7a 100644 --- a/Documentation/devicetree/bindings/media/xilinx/xlnx,csi2rxss.yaml +++ b/Documentation/devicetree/bindings/media/xilinx/xlnx,csi2rxss.yaml @@ -97,24 +97,21 @@ properties: maxItems: 1 ports: - type: object + $ref: /schemas/graph.yaml#/properties/ports properties: port@0: - type: object + $ref: /schemas/graph.yaml#/$defs/port-base description: | Input / sink port node, single endpoint describing the CSI-2 transmitter. properties: - reg: - const: 0 - endpoint: - type: object + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false properties: - data-lanes: description: | This is required only in the sink port 0 endpoint which @@ -130,41 +127,17 @@ properties: - const: 3 - const: 4 - remote-endpoint: true - required: - data-lanes - - remote-endpoint - - additionalProperties: false - additionalProperties: false + unevaluatedProperties: false port@1: - type: object + $ref: /schemas/graph.yaml#/properties/port description: | Output / source port node, endpoint describing modules connected the CSI-2 receiver. - properties: - - reg: - const: 1 - - endpoint: - type: object - - properties: - - remote-endpoint: true - - required: - - remote-endpoint - - additionalProperties: false - - additionalProperties: false - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml index 6d6ba608fd22..990489fdd2ac 100644 --- a/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml @@ -26,10 +26,14 @@ properties: compatible: items: - enum: + - renesas,r8a774a1-rpc-if # RZ/G2M + - renesas,r8a774b1-rpc-if # RZ/G2N + - renesas,r8a774c0-rpc-if # RZ/G2E + - renesas,r8a774e1-rpc-if # RZ/G2H - renesas,r8a77970-rpc-if # R-Car V3M - renesas,r8a77980-rpc-if # R-Car V3H - renesas,r8a77995-rpc-if # R-Car D3 - - const: renesas,rcar-gen3-rpc-if # a generic R-Car gen3 device + - const: renesas,rcar-gen3-rpc-if # a generic R-Car gen3 or RZ/G2 device reg: items: diff --git a/Documentation/devicetree/bindings/mips/lantiq/lantiq,cgu.yaml b/Documentation/devicetree/bindings/mips/lantiq/lantiq,cgu.yaml new file mode 100644 index 000000000000..d5805725befb --- /dev/null +++ b/Documentation/devicetree/bindings/mips/lantiq/lantiq,cgu.yaml @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mips/lantiq/lantiq,cgu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Lantiq Xway SoC series Clock Generation Unit (CGU) + +maintainers: + - John Crispin <john@phrozen.org> + +properties: + compatible: + items: + - enum: + - lantiq,cgu-xway + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + cgu@103000 { + compatible = "lantiq,cgu-xway"; + reg = <0x103000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/mips/lantiq/lantiq,dma-xway.yaml b/Documentation/devicetree/bindings/mips/lantiq/lantiq,dma-xway.yaml new file mode 100644 index 000000000000..40130fefa2b4 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/lantiq/lantiq,dma-xway.yaml @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mips/lantiq/lantiq,dma-xway.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Lantiq Xway SoCs DMA Controller DT bindings + +maintainers: + - John Crispin <john@phrozen.org> + +properties: + compatible: + items: + - enum: + - lantiq,dma-xway + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + dma@e104100 { + compatible = "lantiq,dma-xway"; + reg = <0xe104100 0x800>; + }; diff --git a/Documentation/devicetree/bindings/mips/lantiq/lantiq,ebu.yaml b/Documentation/devicetree/bindings/mips/lantiq/lantiq,ebu.yaml new file mode 100644 index 000000000000..0fada1f085a9 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/lantiq/lantiq,ebu.yaml @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mips/lantiq/lantiq,ebu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Lantiq Xway SoC series External Bus Unit (EBU) + +maintainers: + - John Crispin <john@phrozen.org> + +properties: + compatible: + items: + - enum: + - lantiq,ebu-xway + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + ebu@105300 { + compatible = "lantiq,ebu-xway"; + reg = <0x105300 0x100>; + }; diff --git a/Documentation/devicetree/bindings/mips/lantiq/lantiq,pmu.yaml b/Documentation/devicetree/bindings/mips/lantiq/lantiq,pmu.yaml new file mode 100644 index 000000000000..4982b458ac12 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/lantiq/lantiq,pmu.yaml @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mips/lantiq/lantiq,pmu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Lantiq Xway SoC series Power Management Unit (PMU) + +maintainers: + - John Crispin <john@phrozen.org> + +properties: + compatible: + items: + - enum: + - lantiq,pmu-xway + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + pmu@102000 { + compatible = "lantiq,pmu-xway"; + reg = <0x102000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/mips/realtek-rtl.yaml b/Documentation/devicetree/bindings/mips/realtek-rtl.yaml new file mode 100644 index 000000000000..aadff8ce0f49 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/realtek-rtl.yaml @@ -0,0 +1,24 @@ +# SPDX-License-Identifier: GPL-2.0-or-later OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mips/realtek-rtl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Realtek RTL83xx/93xx SoC series device tree bindings + +maintainers: + - Bert Vermeulen <bert@biot.com> + - Sander Vanheule <sander@svanheule.net> + +properties: + $nodename: + const: "/" + compatible: + oneOf: + # RTL8382-based boards + - items: + - enum: + - cisco,sg220-26 + - const: realtek,rtl8382-soc + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/mmc/allwinner,sun4i-a10-mmc.yaml b/Documentation/devicetree/bindings/mmc/allwinner,sun4i-a10-mmc.yaml index e82c9a07b6fb..e75b3a8ba816 100644 --- a/Documentation/devicetree/bindings/mmc/allwinner,sun4i-a10-mmc.yaml +++ b/Documentation/devicetree/bindings/mmc/allwinner,sun4i-a10-mmc.yaml @@ -26,6 +26,8 @@ properties: - const: allwinner,sun9i-a80-mmc - const: allwinner,sun50i-a64-emmc - const: allwinner,sun50i-a64-mmc + - const: allwinner,sun50i-a100-emmc + - const: allwinner,sun50i-a100-mmc - items: - const: allwinner,sun8i-a83t-mmc - const: allwinner,sun7i-a20-mmc @@ -47,6 +49,12 @@ properties: - items: - const: allwinner,sun50i-h6-mmc - const: allwinner,sun50i-a64-mmc + - items: + - const: allwinner,sun50i-h616-emmc + - const: allwinner,sun50i-a100-emmc + - items: + - const: allwinner,sun50i-h616-mmc + - const: allwinner,sun50i-a100-mmc reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml b/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml new file mode 100644 index 000000000000..47595cb483be --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml @@ -0,0 +1,223 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/arm,pl18x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ARM PrimeCell MultiMedia Card Interface (MMCI) PL180 and PL181 + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + - Ulf Hansson <ulf.hansson@linaro.org> + +description: + The ARM PrimeCells MMCI PL180 and PL181 provides an interface for + reading and writing to MultiMedia and SD cards alike. Over the years + vendors have use the VHDL code from ARM to create derivative MMC/SD/SDIO + host controllers with very similar characteristics. + +allOf: + - $ref: /schemas/arm/primecell.yaml# + - $ref: mmc-controller.yaml# + +# We need a select here so we don't match all nodes with 'arm,primecell' +select: + properties: + compatible: + contains: + enum: + - arm,pl180 + - arm,pl181 + - arm,pl18x + required: + - compatible + +properties: + compatible: + oneOf: + - description: The first version of the block, simply called + PL180 and found in the ARM Integrator IM/PD1 logic module. + items: + - const: arm,pl180 + - const: arm,primecell + - description: The improved version of the block, found in the + ARM Versatile and later reference designs. Further revisions + exist but get detected at runtime by reading some magic numbers + in the PrimeCell ID registers. + items: + - const: arm,pl181 + - const: arm,primecell + - description: Wildcard entry that will let the operating system + inspect the PrimeCell ID registers to determine which hardware + variant of PL180 or PL181 this is. + items: + - const: arm,pl18x + - const: arm,primecell + + clocks: + description: One or two clocks, the "apb_pclk" and the "MCLK" + which is the core block clock. The names are not compulsory. + minItems: 1 + maxItems: 2 + + power-domains: true + + resets: + maxItems: 1 + + reg: + description: the MMIO memory window must be exactly 4KB (0x1000) and the + layout should provide the PrimeCell ID registers so that the device can + be discovered. On ST Micro variants, a second register window may be + defined if a delay block is present and used for tuning. + + interrupts: + description: The first interrupt is the command interrupt and corresponds + to the event at the end of a command. The second interrupt is the + 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. + minItems: 1 + maxItems: 2 + + st,sig-dir-dat0: + $ref: /schemas/types.yaml#/definitions/flag + description: ST Micro-specific property, bus signal direction pins used for + DAT[0]. + + st,sig-dir-dat2: + $ref: /schemas/types.yaml#/definitions/flag + description: ST Micro-specific property, bus signal direction pins used for + DAT[2]. + + st,sig-dir-dat31: + $ref: /schemas/types.yaml#/definitions/flag + description: ST Micro-specific property, bus signal direction pins used for + DAT[3] and DAT[1]. + + st,sig-dir-dat74: + $ref: /schemas/types.yaml#/definitions/flag + description: ST Micro-specific property, bus signal direction pins used for + DAT[7] and DAT[4]. + + st,sig-dir-cmd: + $ref: /schemas/types.yaml#/definitions/flag + description: ST Micro-specific property, CMD signal direction used for + pin CMD. + + st,sig-pin-fbclk: + $ref: /schemas/types.yaml#/definitions/flag + description: ST Micro-specific property, feedback clock FBCLK signal pin + in use. + + st,sig-dir: + $ref: /schemas/types.yaml#/definitions/flag + description: ST Micro-specific property, signal direction polarity used for + pins CMD, DAT[0], DAT[1], DAT[2] and DAT[3]. + + st,neg-edge: + $ref: /schemas/types.yaml#/definitions/flag + description: ST Micro-specific property, data and command phase relation, + generated on the sd clock falling edge. + + st,use-ckin: + $ref: /schemas/types.yaml#/definitions/flag + description: ST Micro-specific property, use CKIN pin from an external + driver to sample the receive data (for example with a voltage switch + transceiver). + + st,cmd-gpios: + maxItems: 1 + description: + The GPIO matching the CMD pin. + + st,ck-gpios: + maxItems: 1 + description: + The GPIO matching the CK pin. + + st,ckin-gpios: + maxItems: 1 + description: + The GPIO matching the CKIN pin. + +dependencies: + st,cmd-gpios: [ "st,use-ckin" ] + st,ck-gpios: [ "st,use-ckin" ] + st,ckin-gpios: [ "st,use-ckin" ] + +unevaluatedProperties: false + +required: + - compatible + - reg + - interrupts + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/gpio/gpio.h> + + mmc@5000 { + compatible = "arm,pl180", "arm,primecell"; + reg = <0x5000 0x1000>; + interrupts-extended = <&vic 22 &sic 1>; + clocks = <&xtal24mhz>, <&pclk>; + clock-names = "mclk", "apb_pclk"; + }; + + mmc@80126000 { + compatible = "arm,pl18x", "arm,primecell"; + reg = <0x80126000 0x1000>; + interrupts = <0 60 IRQ_TYPE_LEVEL_HIGH>; + dmas = <&dma 29 0 0x2>, <&dma 29 0 0x0>; + dma-names = "rx", "tx"; + clocks = <&prcc_kclk 1 5>, <&prcc_pclk 1 5>; + clock-names = "sdi", "apb_pclk"; + max-frequency = <100000000>; + bus-width = <4>; + cap-sd-highspeed; + cap-mmc-highspeed; + cd-gpios = <&gpio2 31 0x4>; + st,sig-dir-dat0; + st,sig-dir-dat2; + st,sig-dir-cmd; + st,sig-pin-fbclk; + vmmc-supply = <&ab8500_ldo_aux3_reg>; + vqmmc-supply = <&vmmci>; + }; + + mmc@101f6000 { + compatible = "arm,pl18x", "arm,primecell"; + reg = <0x101f6000 0x1000>; + clocks = <&sdiclk>, <&pclksdi>; + clock-names = "mclk", "apb_pclk"; + interrupt-parent = <&vica>; + interrupts = <22>; + max-frequency = <400000>; + bus-width = <4>; + cap-mmc-highspeed; + cap-sd-highspeed; + full-pwr-cycle; + st,sig-dir-dat0; + st,sig-dir-dat2; + st,sig-dir-dat31; + st,sig-dir-cmd; + st,sig-pin-fbclk; + vmmc-supply = <&vmmc_regulator>; + }; + + mmc@52007000 { + compatible = "arm,pl18x", "arm,primecell"; + arm,primecell-periphid = <0x10153180>; + reg = <0x52007000 0x1000>; + interrupts = <49>; + interrupt-names = "cmd_irq"; + clocks = <&rcc 0>; + clock-names = "apb_pclk"; + resets = <&rcc 1>; + cap-sd-highspeed; + cap-mmc-highspeed; + max-frequency = <120000000>; + }; diff --git a/Documentation/devicetree/bindings/mmc/marvell,xenon-sdhci.txt b/Documentation/devicetree/bindings/mmc/marvell,xenon-sdhci.txt index ed1456f5c94d..c51a62d751dc 100644 --- a/Documentation/devicetree/bindings/mmc/marvell,xenon-sdhci.txt +++ b/Documentation/devicetree/bindings/mmc/marvell,xenon-sdhci.txt @@ -12,6 +12,7 @@ Required Properties: - "marvell,armada-3700-sdhci": For controllers on Armada-3700 SoC. Must provide a second register area and marvell,pad-type. - "marvell,armada-ap806-sdhci": For controllers on Armada AP806. + - "marvell,armada-ap807-sdhci": For controllers on Armada AP807. - "marvell,armada-cp110-sdhci": For controllers on Armada CP110. - clocks: diff --git a/Documentation/devicetree/bindings/mmc/mmci.txt b/Documentation/devicetree/bindings/mmc/mmci.txt deleted file mode 100644 index 4ec921e4bf34..000000000000 --- a/Documentation/devicetree/bindings/mmc/mmci.txt +++ /dev/null @@ -1,74 +0,0 @@ -* ARM PrimeCell MultiMedia Card Interface (MMCI) PL180/1 - -The ARM PrimeCell MMCI PL180 and PL181 provides an interface for -reading and writing to MultiMedia and SD cards alike. - -This file documents differences between the core properties described -by mmc.txt and the properties used by the mmci driver. Using "st" as -the prefix for a property, indicates support by the ST Micro variant. - -Required properties: -- compatible : contains "arm,pl18x", "arm,primecell". -- vmmc-supply : phandle to the regulator device tree node, mentioned - as the VCC/VDD supply in the eMMC/SD specs. - -Optional properties: -- arm,primecell-periphid : contains the PrimeCell Peripheral ID, it overrides - the ID provided by the HW -- resets : phandle to internal reset line. - Should be defined for sdmmc variant. -- vqmmc-supply : phandle to the regulator device tree node, mentioned - as the VCCQ/VDD_IO supply in the eMMC/SD specs. -specific for ux500 variant: -- st,sig-dir-dat0 : bus signal direction pin used for DAT[0]. -- st,sig-dir-dat2 : bus signal direction pin used for DAT[2]. -- st,sig-dir-dat31 : bus signal direction pin used for DAT[3] and DAT[1]. -- st,sig-dir-dat74 : bus signal direction pin used for DAT[4] to DAT[7]. -- st,sig-dir-cmd : cmd signal direction pin used for CMD. -- st,sig-pin-fbclk : feedback clock signal pin used. - -specific for sdmmc variant: -- reg : a second base register may be defined if a delay - block is present and used for tuning. -- st,sig-dir : signal direction polarity used for cmd, dat0 dat123. -- st,neg-edge : data & command phase relation, generated on - sd clock falling edge. -- st,use-ckin : use ckin pin from an external driver to sample - the receive data (example: with voltage - switch transceiver). - -Deprecated properties: -- mmc-cap-mmc-highspeed : indicates whether MMC is high speed capable. -- mmc-cap-sd-highspeed : indicates whether SD is high speed capable. - -Example: - -sdi0_per1@80126000 { - compatible = "arm,pl18x", "arm,primecell"; - reg = <0x80126000 0x1000>; - interrupts = <0 60 IRQ_TYPE_LEVEL_HIGH>; - - dmas = <&dma 29 0 0x2>, /* Logical - DevToMem */ - <&dma 29 0 0x0>; /* Logical - MemToDev */ - dma-names = "rx", "tx"; - - clocks = <&prcc_kclk 1 5>, <&prcc_pclk 1 5>; - clock-names = "sdi", "apb_pclk"; - - max-frequency = <100000000>; - bus-width = <4>; - cap-sd-highspeed; - cap-mmc-highspeed; - cd-gpios = <&gpio2 31 0x4>; // 95 - st,sig-dir-dat0; - st,sig-dir-dat2; - st,sig-dir-cmd; - st,sig-pin-fbclk; - - vmmc-supply = <&ab8500_ldo_aux3_reg>; - vqmmc-supply = <&vmmci>; - - pinctrl-names = "default", "sleep"; - pinctrl-0 = <&sdi0_default_mode>; - pinctrl-1 = <&sdi0_sleep_mode>; -}; diff --git a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml index 6bbf29b5c239..5908a717d2e8 100644 --- a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml +++ b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml @@ -59,6 +59,7 @@ properties: - renesas,sdhi-r8a77980 # R-Car V3H - renesas,sdhi-r8a77990 # R-Car E3 - renesas,sdhi-r8a77995 # R-Car D3 + - renesas,sdhi-r8a779a0 # R-Car V3U - const: renesas,rcar-gen3-sdhi # R-Car Gen3 or RZ/G2 reg: diff --git a/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml b/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml index 1ae945434c53..3a79e39253d2 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml +++ b/Documentation/devicetree/bindings/mmc/sdhci-am654.yaml @@ -15,12 +15,19 @@ allOf: properties: compatible: - enum: - - ti,am654-sdhci-5.1 - - ti,j721e-sdhci-8bit - - ti,j721e-sdhci-4bit - - ti,j7200-sdhci-8bit - - ti,j721e-sdhci-4bit + oneOf: + - const: ti,am654-sdhci-5.1 + - const: ti,j721e-sdhci-8bit + - const: ti,j721e-sdhci-4bit + - const: ti,j721e-sdhci-4bit + - const: ti,am64-sdhci-8bit + - const: ti,am64-sdhci-4bit + - items: + - const: ti,j7200-sdhci-8bit + - const: ti,j721e-sdhci-8bit + - items: + - const: ti,j7200-sdhci-4bit + - const: ti,j721e-sdhci-4bit reg: maxItems: 2 diff --git a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt index 3b602fd6180b..4c7fa6a4ed15 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt @@ -17,10 +17,11 @@ Required properties: "qcom,msm8916-sdhci", "qcom,sdhci-msm-v4" "qcom,msm8992-sdhci", "qcom,sdhci-msm-v4" "qcom,msm8996-sdhci", "qcom,sdhci-msm-v4" - "qcom,sm8250-sdhci", "qcom,sdhci-msm-v5" - "qcom,sdm845-sdhci", "qcom,sdhci-msm-v5" "qcom,qcs404-sdhci", "qcom,sdhci-msm-v5" "qcom,sc7180-sdhci", "qcom,sdhci-msm-v5"; + "qcom,sdm845-sdhci", "qcom,sdhci-msm-v5" + "qcom,sdx55-sdhci", "qcom,sdhci-msm-v5"; + "qcom,sm8250-sdhci", "qcom,sdhci-msm-v5" NOTE that some old device tree files may be floating around that only have the string "qcom,sdhci-msm-v4" without the SoC compatible string but doing that should be considered a deprecated practice. @@ -30,10 +31,12 @@ Required properties: - SD Core register map (required for controllers earlier than msm-v5) - CQE register map (Optional, CQE support is present on SDHC instance meant for eMMC and version v4.2 and above) + - Inline Crypto Engine register map (optional) - reg-names: When CQE register map is supplied, below reg-names are required - "hc" for Host controller register map - "core" for SD core register map - "cqhci" for CQE register map + - "ice" for Inline Crypto Engine register map (optional) - interrupts: Should contain an interrupt-specifiers for the interrupts: - Host controller interrupt (required) - pinctrl-names: Should contain only one value - "default". @@ -46,6 +49,7 @@ Required properties: "xo" - TCXO clock (optional) "cal" - reference clock for RCLK delay calibration (optional) "sleep" - sleep clock for RCLK delay calibration (optional) + "ice" - clock for Inline Crypto Engine (optional) - qcom,ddr-config: Certain chipsets and platforms require particular settings for the DDR_CONFIG register. Use this field to specify the register diff --git a/Documentation/devicetree/bindings/mmc/sdhci-sirf.txt b/Documentation/devicetree/bindings/mmc/sdhci-sirf.txt deleted file mode 100644 index dd6ed464bcb8..000000000000 --- a/Documentation/devicetree/bindings/mmc/sdhci-sirf.txt +++ /dev/null @@ -1,18 +0,0 @@ -* SiRFprimII/marco/atlas6 SDHCI Controller - -This file documents differences between the core properties in mmc.txt -and the properties used by the sdhci-sirf driver. - -Required properties: -- compatible: sirf,prima2-sdhc - -Optional properties: -- cd-gpios: card detect gpio, with zero flags. - -Example: - - sd0: sdhci@56000000 { - compatible = "sirf,prima2-sdhc"; - reg = <0xcd000000 0x100000>; - cd-gpios = <&gpio 6 0>; - }; diff --git a/Documentation/devicetree/bindings/mmc/zx-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/zx-dw-mshc.txt deleted file mode 100644 index 0f59bd5361f5..000000000000 --- a/Documentation/devicetree/bindings/mmc/zx-dw-mshc.txt +++ /dev/null @@ -1,31 +0,0 @@ -* ZTE specific extensions to the Synopsys Designware Mobile Storage - Host Controller - -The Synopsys designware mobile storage host controller is used to interface -a SoC with storage medium such as eMMC or SD/MMC cards. This file documents -differences between the core Synopsys dw mshc controller properties described -by synopsys-dw-mshc.txt and the properties used by the ZTE specific -extensions to the Synopsys Designware Mobile Storage Host Controller. - -Required Properties: - -* compatible: should be - - "zte,zx296718-dw-mshc": for ZX SoCs - -Example: - - mmc1: mmc@1110000 { - compatible = "zte,zx296718-dw-mshc"; - reg = <0x01110000 0x1000>; - interrupts = <GIC_SPI 15 IRQ_TYPE_LEVEL_HIGH>; - fifo-depth = <32>; - data-addr = <0x200>; - fifo-watermark-aligned; - bus-width = <4>; - clock-frequency = <50000000>; - clocks = <&topcrm SD0_AHB>, <&topcrm SD0_WCLK>; - clock-names = "biu", "ciu"; - max-frequency = <50000000>; - cap-sdio-irq; - cap-sd-highspeed; - }; diff --git a/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm4908-partitions.yaml b/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm4908-partitions.yaml new file mode 100644 index 000000000000..7b113e5e3421 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm4908-partitions.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/partitions/brcm,bcm4908-partitions.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM4908 partitioning + +description: | + Broadcom BCM4908 CFE bootloader supports two firmware partitions. One is used + for regular booting, the other is treated as fallback. + + This binding allows defining all fixed partitions and marking those containing + firmware. System can use that information e.g. for booting or flashing + purposes. + +maintainers: + - Rafał Miłecki <rafal@milecki.pl> + +properties: + compatible: + const: brcm,bcm4908-partitions + + "#address-cells": + enum: [ 1, 2 ] + + "#size-cells": + enum: [ 1, 2 ] + +patternProperties: + "^partition@[0-9a-f]+$": + $ref: "partition.yaml#" + properties: + compatible: + const: brcm,bcm4908-firmware + unevaluatedProperties: false + +required: + - "#address-cells" + - "#size-cells" + +additionalProperties: false + +examples: + - | + partitions { + compatible = "brcm,bcm4908-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + partition@0 { + label = "cferom"; + reg = <0x0 0x100000>; + }; + + partition@100000 { + compatible = "brcm,bcm4908-firmware"; + reg = <0x100000 0xf00000>; + }; + + partition@1000000 { + compatible = "brcm,bcm4908-firmware"; + reg = <0x1000000 0xf00000>; + }; + + partition@1f00000 { + label = "calibration"; + reg = <0x1f00000 0x100000>; + }; + }; diff --git a/Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml b/Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml index 6d4a3450e064..ea4cace6a955 100644 --- a/Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml +++ b/Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml @@ -27,38 +27,7 @@ properties: patternProperties: "@[0-9a-f]+$": - description: node describing a single flash partition - type: object - - properties: - reg: - description: partition's offset and size within the flash - maxItems: 1 - - label: - description: The label / name for this partition. If omitted, the label - is taken from the node name (excluding the unit address). - - read-only: - description: This parameter, if present, is a hint that this partition - should only be mounted read-only. This is usually used for flash - partitions containing early-boot firmware images or data which should - not be clobbered. - type: boolean - - lock: - description: Do not unlock the partition at initialization time (not - supported on all devices) - type: boolean - - slc-mode: - description: This parameter, if present, allows one to emulate SLC mode - on a partition attached to an MLC NAND thus making this partition - immune to paired-pages corruptions - type: boolean - - required: - - reg + $ref: "partition.yaml#" required: - "#address-cells" diff --git a/Documentation/devicetree/bindings/mtd/partitions/partition.yaml b/Documentation/devicetree/bindings/mtd/partitions/partition.yaml new file mode 100644 index 000000000000..e1ac08064425 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/partitions/partition.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/partitions/partition.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Partition + +description: | + This binding describes a single flash partition. Each partition must have its + relative offset and size specified. Depending on partition function extra + properties can be used. + +maintainers: + - Rafał Miłecki <rafal@milecki.pl> + +properties: + reg: + description: partition's offset and size within the flash + maxItems: 1 + + label: + description: The label / name for this partition. If omitted, the label + is taken from the node name (excluding the unit address). + + read-only: + description: This parameter, if present, is a hint that this partition + should only be mounted read-only. This is usually used for flash + partitions containing early-boot firmware images or data which should + not be clobbered. + type: boolean + + lock: + description: Do not unlock the partition at initialization time (not + supported on all devices) + type: boolean + + slc-mode: + description: This parameter, if present, allows one to emulate SLC mode + on a partition attached to an MLC NAND thus making this partition + immune to paired-pages corruptions + type: boolean + +required: + - reg + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/mtd/partitions/qcom,smem-part.yaml b/Documentation/devicetree/bindings/mtd/partitions/qcom,smem-part.yaml new file mode 100644 index 000000000000..cf3f8c1e035d --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/partitions/qcom,smem-part.yaml @@ -0,0 +1,33 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/partitions/qcom,smem-part.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SMEM NAND flash partition parser binding + +maintainers: + - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org> + +description: | + The Qualcomm SoCs supporting the NAND controller interface features a Shared + Memory (SMEM) based partition table scheme. The maximum partitions supported + varies between partition table revisions. V3 supports maximum 16 partitions + and V4 supports 48 partitions. + +properties: + compatible: + const: qcom,smem-part + +required: + - compatible + +additionalProperties: false + +examples: + - | + flash { + partitions { + compatible = "qcom,smem-part"; + }; + }; diff --git a/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml b/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml index 1f133f4a2924..0467441d7037 100644 --- a/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml +++ b/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml @@ -74,17 +74,60 @@ allOf: Any configuration is ignored when the phy-mode is set to "rmii". amlogic,rx-delay-ns: + deprecated: true enum: - 0 - 2 default: 0 description: - The internal RGMII RX clock delay (provided by this IP block) in - nanoseconds. When phy-mode is set to "rgmii" then the RX delay - should be explicitly configured. When the phy-mode is set to - either "rgmii-id" or "rgmii-rxid" the RX clock delay is already - provided by the PHY. Any configuration is ignored when the - phy-mode is set to "rmii". + The internal RGMII RX clock delay in nanoseconds. Deprecated, use + rx-internal-delay-ps instead. + + rx-internal-delay-ps: + default: 0 + + - if: + properties: + compatible: + contains: + enum: + - amlogic,meson8b-dwmac + - amlogic,meson8m2-dwmac + - amlogic,meson-gxbb-dwmac + - amlogic,meson-axg-dwmac + then: + properties: + rx-internal-delay-ps: + enum: + - 0 + - 2000 + + - if: + properties: + compatible: + contains: + enum: + - amlogic,meson-g12a-dwmac + then: + properties: + rx-internal-delay-ps: + enum: + - 0 + - 200 + - 400 + - 600 + - 800 + - 1000 + - 1200 + - 1400 + - 1600 + - 1800 + - 2000 + - 2200 + - 2400 + - 2600 + - 2800 + - 3000 properties: compatible: diff --git a/Documentation/devicetree/bindings/net/brcm,bcm4908-enet.yaml b/Documentation/devicetree/bindings/net/brcm,bcm4908-enet.yaml new file mode 100644 index 000000000000..79c38ea14237 --- /dev/null +++ b/Documentation/devicetree/bindings/net/brcm,bcm4908-enet.yaml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/brcm,bcm4908-enet.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM4908 Ethernet controller + +description: Broadcom's Ethernet controller integrated into BCM4908 family SoCs + +maintainers: + - Rafał Miłecki <rafal@milecki.pl> + +allOf: + - $ref: ethernet-controller.yaml# + +properties: + compatible: + const: brcm,bcm4908-enet + + reg: + maxItems: 1 + + interrupts: + description: RX interrupt + + interrupt-names: + const: rx + +required: + - reg + - interrupts + - interrupt-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + ethernet@80002000 { + compatible = "brcm,bcm4908-enet"; + reg = <0x80002000 0x1000>; + + interrupts = <GIC_SPI 86 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "rx"; + }; diff --git a/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt b/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt index 97ca62b0e14d..d0935d2afef8 100644 --- a/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt +++ b/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt @@ -1,108 +1,13 @@ * Broadcom Starfighter 2 integrated swich -Required properties: +See dsa/brcm,bcm7445-switch-v4.0.yaml for the documentation. -- compatible: should be one of - "brcm,bcm7445-switch-v4.0" - "brcm,bcm7278-switch-v4.0" - "brcm,bcm7278-switch-v4.8" -- reg: addresses and length of the register sets for the device, must be 6 - pairs of register addresses and lengths -- interrupts: interrupts for the devices, must be two interrupts -- #address-cells: must be 1, see dsa/dsa.txt -- #size-cells: must be 0, see dsa/dsa.txt - -Deprecated binding required properties: +*Deprecated* binding required properties: - dsa,mii-bus: phandle to the MDIO bus controller, see dsa/dsa.txt - dsa,ethernet: phandle to the CPU network interface controller, see dsa/dsa.txt - #address-cells: must be 2, see dsa/dsa.txt -Subnodes: - -The integrated switch subnode should be specified according to the binding -described in dsa/dsa.txt. - -Optional properties: - -- reg-names: litteral names for the device base register addresses, when present - must be: "core", "reg", "intrl2_0", "intrl2_1", "fcb", "acb" - -- interrupt-names: litternal names for the device interrupt lines, when present - must be: "switch_0" and "switch_1" - -- brcm,num-gphy: specify the maximum number of integrated gigabit PHYs in the - switch - -- brcm,num-rgmii-ports: specify the maximum number of RGMII interfaces supported - by the switch - -- brcm,fcb-pause-override: boolean property, if present indicates that the switch - supports Failover Control Block pause override capability - -- brcm,acb-packets-inflight: boolean property, if present indicates that the switch - Admission Control Block supports reporting the number of packets in-flight in a - switch queue - -- resets: a single phandle and reset identifier pair. See - Documentation/devicetree/bindings/reset/reset.txt for details. - -- reset-names: If the "reset" property is specified, this property should have - the value "switch" to denote the switch reset line. - -- clocks: when provided, the first phandle is to the switch's main clock and - is valid for both BCM7445 and BCM7278. The second phandle is only applicable - to BCM7445 and is to support dividing the switch core clock. - -- clock-names: when provided, the first phandle must be "sw_switch", and the - second must be named "sw_switch_mdiv". - -Port subnodes: - -Optional properties: - -- brcm,use-bcm-hdr: boolean property, if present, indicates that the switch - port has Broadcom tags enabled (per-packet metadata) - -Example: - -switch_top@f0b00000 { - compatible = "simple-bus"; - #size-cells = <1>; - #address-cells = <1>; - ranges = <0 0xf0b00000 0x40804>; - - ethernet_switch@0 { - compatible = "brcm,bcm7445-switch-v4.0"; - #size-cells = <0>; - #address-cells = <1>; - reg = <0x0 0x40000 - 0x40000 0x110 - 0x40340 0x30 - 0x40380 0x30 - 0x40400 0x34 - 0x40600 0x208>; - reg-names = "core", "reg", intrl2_0", "intrl2_1", - "fcb, "acb"; - interrupts = <0 0x18 0 - 0 0x19 0>; - brcm,num-gphy = <1>; - brcm,num-rgmii-ports = <2>; - brcm,fcb-pause-override; - brcm,acb-packets-inflight; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - label = "gphy"; - reg = <0>; - }; - }; - }; -}; - Example using the old DSA DeviceTree binding: switch_top@f0b00000 { @@ -132,7 +37,7 @@ switch_top@f0b00000 { switch@0 { reg = <0 0>; #size-cells = <0>; - #address-cells <1>; + #address-cells = <1>; port@0 { label = "gphy"; diff --git a/Documentation/devicetree/bindings/net/btusb.txt b/Documentation/devicetree/bindings/net/btusb.txt index b1ad6ee68e90..f546b1f7dd6d 100644 --- a/Documentation/devicetree/bindings/net/btusb.txt +++ b/Documentation/devicetree/bindings/net/btusb.txt @@ -4,7 +4,7 @@ Generic Bluetooth controller over USB (btusb driver) Required properties: - compatible : should comply with the format "usbVID,PID" specified in - Documentation/devicetree/bindings/usb/usb-device.txt + Documentation/devicetree/bindings/usb/usb-device.yaml At the time of writing, the only OF supported devices (more may be added later) are: @@ -38,7 +38,7 @@ Following example uses irq pin number 3 of gpio0 for out of band wake-on-bt: compatible = "usb1286,204e"; reg = <1>; interrupt-parent = <&gpio0>; - interrupt-name = "wakeup"; + interrupt-names = "wakeup"; interrupts = <3 IRQ_TYPE_LEVEL_LOW>; }; }; diff --git a/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml b/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml index 0d2df30f19db..fe6a949a2eab 100644 --- a/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml +++ b/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml @@ -110,6 +110,16 @@ properties: description: Enable CAN remote wakeup. + fsl,scu-index: + description: | + The scu index of CAN instance. + For SoCs with SCU support, need setup stop mode via SCU firmware, so this + property can help indicate a resource. It supports up to 3 CAN instances + now. + $ref: /schemas/types.yaml#/definitions/uint8 + minimum: 0 + maximum: 2 + required: - compatible - reg @@ -137,4 +147,5 @@ examples: clocks = <&clks 1>, <&clks 2>; clock-names = "ipg", "per"; fsl,stop-mode = <&gpr 0x34 28>; + fsl,scu-index = /bits/ 8 <1>; }; diff --git a/Documentation/devicetree/bindings/net/dsa/arrow,xrs700x.yaml b/Documentation/devicetree/bindings/net/dsa/arrow,xrs700x.yaml new file mode 100644 index 000000000000..3f01b65f3b22 --- /dev/null +++ b/Documentation/devicetree/bindings/net/dsa/arrow,xrs700x.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/dsa/arrow,xrs700x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Arrow SpeedChips XRS7000 Series Switch Device Tree Bindings + +allOf: + - $ref: dsa.yaml# + +maintainers: + - George McCollister <george.mccollister@gmail.com> + +description: + The Arrow SpeedChips XRS7000 Series of single chip gigabit Ethernet switches + are designed for critical networking applications. They have up to three + RGMII ports and one RMII port and are managed via i2c or mdio. + +properties: + compatible: + oneOf: + - enum: + - arrow,xrs7003e + - arrow,xrs7003f + - arrow,xrs7004e + - arrow,xrs7004f + + reg: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + switch@8 { + compatible = "arrow,xrs7004e"; + reg = <0x8>; + + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + ethernet-port@1 { + reg = <1>; + label = "lan0"; + phy-handle = <&swphy0>; + phy-mode = "rgmii-id"; + }; + ethernet-port@2 { + reg = <2>; + label = "lan1"; + phy-handle = <&swphy1>; + phy-mode = "rgmii-id"; + }; + ethernet-port@3 { + reg = <3>; + label = "cpu"; + ethernet = <&fec1>; + fixed-link { + speed = <1000>; + full-duplex; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml b/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml new file mode 100644 index 000000000000..d730fe5a4355 --- /dev/null +++ b/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml @@ -0,0 +1,173 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/dsa/brcm,sf2.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom Starfighter 2 integrated swich + +maintainers: + - Florian Fainelli <f.fainelli@gmail.com> + +properties: + compatible: + items: + - enum: + - brcm,bcm4908-switch + - brcm,bcm7278-switch-v4.0 + - brcm,bcm7278-switch-v4.8 + - brcm,bcm7445-switch-v4.0 + + reg: + minItems: 6 + maxItems: 6 + + reg-names: + items: + - const: core + - const: reg + - const: intrl2_0 + - const: intrl2_1 + - const: fcb + - const: acb + + interrupts: + minItems: 2 + maxItems: 2 + + interrupt-names: + items: + - const: switch_0 + - const: switch_1 + + resets: + maxItems: 1 + + reset-names: + const: switch + + clocks: + minItems: 1 + maxItems: 2 + items: + - description: switch's main clock + - description: dividing of the switch core clock + + clock-names: + minItems: 1 + maxItems: 2 + items: + - const: sw_switch + - const: sw_switch_mdiv + + brcm,num-gphy: + $ref: /schemas/types.yaml#/definitions/uint32 + description: maximum number of integrated gigabit PHYs in the switch + + brcm,num-rgmii-ports: + $ref: /schemas/types.yaml#/definitions/uint32 + description: maximum number of RGMII interfaces supported by the switch + + brcm,fcb-pause-override: + description: if present indicates that the switch supports Failover Control + Block pause override capability + type: boolean + + brcm,acb-packets-inflight: + description: if present indicates that the switch Admission Control Block + supports reporting the number of packets in-flight in a switch queue + type: boolean + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + ports: + type: object + + properties: + brcm,use-bcm-hdr: + description: if present, indicates that the switch port has Broadcom + tags enabled (per-packet metadata) + type: boolean + +required: + - reg + - interrupts + - "#address-cells" + - "#size-cells" + +allOf: + - $ref: "dsa.yaml#" + - if: + properties: + compatible: + contains: + enum: + - brcm,bcm7278-switch-v4.0 + - brcm,bcm7278-switch-v4.8 + then: + properties: + clocks: + minItems: 1 + maxItems: 1 + clock-names: + minItems: 1 + maxItems: 1 + required: + - clocks + - clock-names + - if: + properties: + compatible: + contains: + const: brcm,bcm7445-switch-v4.0 + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + minItems: 2 + maxItems: 2 + required: + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + switch@f0b00000 { + compatible = "brcm,bcm7445-switch-v4.0"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xf0b00000 0x40000>, + <0xf0b40000 0x110>, + <0xf0b40340 0x30>, + <0xf0b40380 0x30>, + <0xf0b40400 0x34>, + <0xf0b40600 0x208>; + reg-names = "core", "reg", "intrl2_0", "intrl2_1", + "fcb", "acb"; + interrupts = <0 0x18 0>, + <0 0x19 0>; + clocks = <&sw_switch>, <&sw_switch_mdiv>; + clock-names = "sw_switch", "sw_switch_mdiv"; + brcm,num-gphy = <1>; + brcm,num-rgmii-ports = <2>; + brcm,fcb-pause-override; + brcm,acb-packets-inflight; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + label = "gphy"; + reg = <0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/dsa/mt7530.txt b/Documentation/devicetree/bindings/net/dsa/mt7530.txt index 560369efad6c..de04626a8e9d 100644 --- a/Documentation/devicetree/bindings/net/dsa/mt7530.txt +++ b/Documentation/devicetree/bindings/net/dsa/mt7530.txt @@ -76,6 +76,12 @@ phy-mode must be set, see also example 2 below! * mt7621: phy-mode = "rgmii-txid"; * mt7623: phy-mode = "rgmii"; +Optional properties: + +- gpio-controller: Boolean; if defined, MT7530's LED controller will run on + GPIO mode. +- #gpio-cells: Must be 2 if gpio-controller is defined. + See Documentation/devicetree/bindings/net/dsa/dsa.txt for a list of additional required, optional properties and how the integrated switch subnodes must be specified. diff --git a/Documentation/devicetree/bindings/net/ethernet-controller.yaml b/Documentation/devicetree/bindings/net/ethernet-controller.yaml index dac4aadb6e2e..f599c1d9c961 100644 --- a/Documentation/devicetree/bindings/net/ethernet-controller.yaml +++ b/Documentation/devicetree/bindings/net/ethernet-controller.yaml @@ -89,6 +89,7 @@ properties: - trgmii - 1000base-x - 2500base-x + - 5gbase-r - rxaui - xaui diff --git a/Documentation/devicetree/bindings/net/marvell-pp2.txt b/Documentation/devicetree/bindings/net/marvell-pp2.txt index b78397669320..ce15c173f43f 100644 --- a/Documentation/devicetree/bindings/net/marvell-pp2.txt +++ b/Documentation/devicetree/bindings/net/marvell-pp2.txt @@ -1,5 +1,6 @@ * Marvell Armada 375 Ethernet Controller (PPv2.1) Marvell Armada 7K/8K Ethernet Controller (PPv2.2) + Marvell CN913X Ethernet Controller (PPv2.3) Required properties: @@ -12,10 +13,11 @@ Required properties: - common controller registers - LMS registers - one register area per Ethernet port - For "marvell,armada-7k-pp2", must contain the following register + 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) @@ -81,7 +83,7 @@ Example for marvell,armada-7k-pp2: cpm_ethernet: ethernet@0 { compatible = "marvell,armada-7k-pp22"; - reg = <0x0 0x100000>, <0x129000 0xb000>; + 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"; diff --git a/Documentation/devicetree/bindings/net/qca,ar803x.yaml b/Documentation/devicetree/bindings/net/qca,ar803x.yaml index 64b3357ade8a..b3d4013b7ca6 100644 --- a/Documentation/devicetree/bindings/net/qca,ar803x.yaml +++ b/Documentation/devicetree/bindings/net/qca,ar803x.yaml @@ -28,6 +28,10 @@ properties: $ref: /schemas/types.yaml#/definitions/uint32 enum: [0, 1, 2] + qca,disable-smarteee: + description: Disable Atheros SmartEEE feature. + type: boolean + qca,keep-pll-enabled: description: | If set, keep the PLL enabled even if there is no link. Useful if you @@ -36,6 +40,18 @@ properties: Only supported on the AR8031. type: boolean + qca,smarteee-tw-us-100m: + description: EEE Tw parameter for 100M links. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + maximum: 255 + + qca,smarteee-tw-us-1g: + description: EEE Tw parameter for gigabit links. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + maximum: 255 + vddio-supply: description: | RGMII I/O voltage regulator (see regulator/regulator.yaml). diff --git a/Documentation/devicetree/bindings/net/qcom,ipa.yaml b/Documentation/devicetree/bindings/net/qcom,ipa.yaml index 8a2d12644675..8f86084bf12e 100644 --- a/Documentation/devicetree/bindings/net/qcom,ipa.yaml +++ b/Documentation/devicetree/bindings/net/qcom,ipa.yaml @@ -113,13 +113,6 @@ properties: performing early IPA initialization, including loading and validating firwmare used by the GSI. - modem-remoteproc: - $ref: /schemas/types.yaml#/definitions/phandle - description: - This defines the phandle to the remoteproc node representing - the modem subsystem. This is requied so the IPA driver can - receive and act on notifications of modem up/down events. - memory-region: maxItems: 1 description: @@ -135,7 +128,6 @@ required: - interrupts - interconnects - qcom,smem-states - - modem-remoteproc oneOf: - required: @@ -147,7 +139,7 @@ additionalProperties: false examples: - | - #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/clock/qcom,rpmh.h> #include <dt-bindings/interconnect/qcom,sdm845.h> @@ -168,7 +160,6 @@ examples: compatible = "qcom,sdm845-ipa"; modem-init; - modem-remoteproc = <&mss_pil>; iommus = <&apps_smmu 0x720 0x3>; reg = <0x1e40000 0x7000>, @@ -178,8 +169,8 @@ examples: "ipa-shared", "gsi"; - interrupts-extended = <&intc 0 311 IRQ_TYPE_EDGE_RISING>, - <&intc 0 432 IRQ_TYPE_LEVEL_HIGH>, + interrupts-extended = <&intc GIC_SPI 311 IRQ_TYPE_EDGE_RISING>, + <&intc GIC_SPI 432 IRQ_TYPE_LEVEL_HIGH>, <&ipa_smp2p_in 0 IRQ_TYPE_EDGE_RISING>, <&ipa_smp2p_in 1 IRQ_TYPE_EDGE_RISING>; interrupt-names = "ipa", diff --git a/Documentation/devicetree/bindings/net/renesas,etheravb.yaml b/Documentation/devicetree/bindings/net/renesas,etheravb.yaml index de9dd574a2f9..91ba96d43c6c 100644 --- a/Documentation/devicetree/bindings/net/renesas,etheravb.yaml +++ b/Documentation/devicetree/bindings/net/renesas,etheravb.yaml @@ -40,6 +40,7 @@ properties: - renesas,etheravb-r8a77980 # R-Car V3H - renesas,etheravb-r8a77990 # R-Car E3 - renesas,etheravb-r8a77995 # R-Car D3 + - renesas,etheravb-r8a779a0 # R-Car V3U - const: renesas,etheravb-rcar-gen3 # R-Car Gen3 and RZ/G2 reg: true @@ -170,6 +171,7 @@ allOf: - renesas,etheravb-r8a77965 - renesas,etheravb-r8a77970 - renesas,etheravb-r8a77980 + - renesas,etheravb-r8a779a0 then: required: - tx-internal-delay-ps diff --git a/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml b/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml index c47b58f3e3f6..3fae9a5f0c6a 100644 --- a/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml +++ b/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/net/ti,k3-am654-cpsw-nuss.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: The TI AM654x/J721E SoC Gigabit Ethernet MAC (Media Access Controller) Device Tree Bindings +title: The TI AM654x/J721E/AM642x SoC Gigabit Ethernet MAC (Media Access Controller) Device Tree Bindings maintainers: - Grygorii Strashko <grygorii.strashko@ti.com> @@ -13,19 +13,16 @@ maintainers: description: The TI AM654x/J721E SoC Gigabit Ethernet MAC (CPSW2G NUSS) has two ports (one external) and provides Ethernet packet communication for the device. - CPSW2G NUSS features - the Reduced Gigabit Media Independent Interface (RGMII), - Reduced Media Independent Interface (RMII), the Management Data - Input/Output (MDIO) interface for physical layer device (PHY) management, - new version of Common Platform Time Sync (CPTS), updated Address Lookup - Engine (ALE). - One external Ethernet port (port 1) with selectable RGMII/RMII interfaces and - an internal Communications Port Programming Interface (CPPI5) (Host port 0). + The TI AM642x SoC Gigabit Ethernet MAC (CPSW3G NUSS) has three ports + (two external) and provides Ethernet packet communication and switching. + + The internal Communications Port Programming Interface (CPPI5) (Host port 0). Host Port 0 CPPI Packet Streaming Interface interface supports 8 TX channels - and one RX channels and operating by TI AM654x/J721E NAVSS Unified DMA - Peripheral Root Complex (UDMA-P) controller. - The CPSW2G NUSS is integrated into device MCU domain named MCU_CPSW0. + and one RX channels and operating by NAVSS Unified DMA Peripheral Root + Complex (UDMA-P) controller. - Additional features + CPSWxG features + updated Address Lookup Engine (ALE). priority level Quality Of Service (QOS) support (802.1p) Support for Audio/Video Bridging (P802.1Qav/D6.0) Support for IEEE 1588 Clock Synchronization (2008 Annex D, Annex E and Annex F) @@ -38,10 +35,18 @@ description: VLAN support, 802.1Q compliant, Auto add port VLAN for untagged frames on ingress, Auto VLAN removal on egress and auto pad to minimum frame size. RX/TX csum offload + Management Data Input/Output (MDIO) interface for PHYs management + RMII/RGMII Interfaces support + new version of Common Platform Time Sync (CPTS) + + The CPSWxG NUSS is integrated into + device MCU domain named MCU_CPSW0 on AM654x/J721E SoC. + device MAIN domain named CPSW0 on AM642x SoC. Specifications can be found at - http://www.ti.com/lit/ug/spruid7e/spruid7e.pdf - http://www.ti.com/lit/ug/spruil1a/spruil1a.pdf + https://www.ti.com/lit/pdf/spruid7 + https://www.ti.com/lit/zip/spruil1 + https://www.ti.com/lit/pdf/spruim2 properties: "#address-cells": true @@ -51,11 +56,12 @@ properties: oneOf: - const: ti,am654-cpsw-nuss - const: ti,j721e-cpsw-nuss + - const: ti,am642-cpsw-nuss reg: maxItems: 1 description: - The physical base address and size of full the CPSW2G NUSS IO range + The physical base address and size of full the CPSWxG NUSS IO range reg-names: items: @@ -66,12 +72,16 @@ properties: dma-coherent: true clocks: - description: CPSW2G NUSS functional clock + description: CPSWxG NUSS functional clock clock-names: items: - const: fck + assigned-clock-parents: true + + assigned-clocks: true + power-domains: maxItems: 1 @@ -99,16 +109,16 @@ properties: const: 0 patternProperties: - port@1: + port@[1-2]: type: object - description: CPSW2G NUSS external ports + description: CPSWxG NUSS external ports $ref: ethernet-controller.yaml# properties: reg: - items: - - const: 1 + minimum: 1 + maximum: 2 description: CPSW port number phys: diff --git a/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml b/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml index 9b7117920d90..ce43a1c58a57 100644 --- a/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml +++ b/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml @@ -73,6 +73,13 @@ properties: items: - const: cpts + assigned-clock-parents: true + + assigned-clocks: true + + power-domains: + maxItems: 1 + ti,cpts-ext-ts-inputs: $ref: /schemas/types.yaml#/definitions/uint32 maximum: 8 diff --git a/Documentation/devicetree/bindings/net/toshiba,visconti-dwmac.yaml b/Documentation/devicetree/bindings/net/toshiba,visconti-dwmac.yaml new file mode 100644 index 000000000000..59724d18e6f3 --- /dev/null +++ b/Documentation/devicetree/bindings/net/toshiba,visconti-dwmac.yaml @@ -0,0 +1,85 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/net/toshiba,visconti-dwmac.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Toshiba Visconti DWMAC Ethernet controller + +maintainers: + - Nobuhiro Iwamatsu <nobuhiro1.iwamatsu@toshiba.co.jp> + +select: + properties: + compatible: + contains: + enum: + - toshiba,visconti-dwmac + required: + - compatible + +allOf: + - $ref: "snps,dwmac.yaml#" + +properties: + compatible: + oneOf: + - items: + - enum: + - toshiba,visconti-dwmac + - const: snps,dwmac-4.20a + + reg: + maxItems: 1 + + clocks: + items: + - description: main clock + - description: PHY reference clock + + clock-names: + items: + - const: stmmaceth + - const: phy_ref_clk + +required: + - compatible + - reg + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + piether: ethernet@28000000 { + compatible = "toshiba,visconti-dwmac", "snps,dwmac-4.20a"; + reg = <0 0x28000000 0 0x10000>; + interrupts = <GIC_SPI 156 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "macirq"; + clocks = <&clk300mhz>, <&clk125mhz>; + clock-names = "stmmaceth", "phy_ref_clk"; + snps,txpbl = <4>; + snps,rxpbl = <4>; + snps,tso; + phy-mode = "rgmii-id"; + phy-handle = <&phy0>; + + mdio0 { + #address-cells = <0x1>; + #size-cells = <0x0>; + compatible = "snps,dwmac-mdio"; + + phy0: ethernet-phy@1 { + device_type = "ethernet-phy"; + reg = <0x1>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/xilinx_axienet.txt b/Documentation/devicetree/bindings/net/xilinx_axienet.txt index 7360617cdedb..2cd452419ed0 100644 --- a/Documentation/devicetree/bindings/net/xilinx_axienet.txt +++ b/Documentation/devicetree/bindings/net/xilinx_axienet.txt @@ -38,6 +38,10 @@ Optional properties: 1 to enable partial TX checksum offload, 2 to enable full TX checksum offload - xlnx,rxcsum : Same values as xlnx,txcsum but for RX checksum offload +- xlnx,switch-x-sgmii : Boolean to indicate the Ethernet core is configured to + support both 1000BaseX and SGMII modes. If set, the phy-mode + should be set to match the mode selected on core reset (i.e. + by the basex_or_sgmii core input line). - clocks : AXI bus clock for the device. Refer to common clock bindings. Used to calculate MDIO clock divisor. If not specified, it is auto-detected from the CPU clock (but only on platforms where diff --git a/Documentation/devicetree/bindings/power/brcm,bcm-pmb.yaml b/Documentation/devicetree/bindings/power/brcm,bcm-pmb.yaml new file mode 100644 index 000000000000..40b08d83c80b --- /dev/null +++ b/Documentation/devicetree/bindings/power/brcm,bcm-pmb.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/brcm,bcm-pmb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom PMB (Power Management Bus) controller + +description: This document describes Broadcom's PMB controller. It supports + powering various types of connected devices (e.g. PCIe, USB, SATA). + +maintainers: + - Rafał Miłecki <rafal@milecki.pl> + +properties: + compatible: + enum: + - brcm,bcm4908-pmb + + reg: + description: register space of one or more buses + maxItems: 1 + + big-endian: + $ref: /schemas/types.yaml#/definitions/flag + description: Flag to use for block working in big endian mode. + + "#power-domain-cells": + description: cell specifies device ID (see bcm-pmb.h) + const: 1 + +required: + - reg + - "#power-domain-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/soc/bcm-pmb.h> + + pmb: power-controller@802800e0 { + compatible = "brcm,bcm4908-pmb"; + reg = <0x802800e0 0x40>; + #power-domain-cells = <1>; + }; + + foo { + power-domains = <&pmb BCM_PMB_PCIE0>; + }; diff --git a/Documentation/devicetree/bindings/power/mediatek,power-controller.yaml b/Documentation/devicetree/bindings/power/mediatek,power-controller.yaml index d14cb9bac849..f234a756c193 100644 --- a/Documentation/devicetree/bindings/power/mediatek,power-controller.yaml +++ b/Documentation/devicetree/bindings/power/mediatek,power-controller.yaml @@ -23,6 +23,7 @@ properties: compatible: enum: + - mediatek,mt8167-power-controller - mediatek,mt8173-power-controller - mediatek,mt8183-power-controller - mediatek,mt8192-power-controller @@ -59,6 +60,7 @@ patternProperties: reg: description: | Power domain index. Valid values are defined in: + "include/dt-bindings/power/mt8167-power.h" - for MT8167 type power domain. "include/dt-bindings/power/mt8173-power.h" - for MT8173 type power domain. "include/dt-bindings/power/mt8183-power.h" - for MT8183 type power domain. "include/dt-bindings/power/mt8192-power.h" - for MT8192 type power domain. @@ -82,6 +84,9 @@ patternProperties: be specified by order, adding first the BASIC clocks followed by the SUSBSYS clocks. + domain-supply: + description: domain regulator supply. + mediatek,infracfg: $ref: /schemas/types.yaml#/definitions/phandle description: phandle to the device containing the INFRACFG register range. @@ -130,6 +135,9 @@ patternProperties: be specified by order, adding first the BASIC clocks followed by the SUSBSYS clocks. + domain-supply: + description: domain regulator supply. + mediatek,infracfg: $ref: /schemas/types.yaml#/definitions/phandle description: phandle to the device containing the INFRACFG register range. @@ -178,6 +186,9 @@ patternProperties: be specified by order, adding first the BASIC clocks followed by the SUSBSYS clocks. + domain-supply: + description: domain regulator supply. + mediatek,infracfg: $ref: /schemas/types.yaml#/definitions/phandle description: phandle to the device containing the INFRACFG register range. diff --git a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml index 64825128ee97..1ea21acbbd55 100644 --- a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml +++ b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml @@ -19,6 +19,7 @@ properties: - qcom,msm8916-rpmpd - qcom,msm8939-rpmpd - qcom,msm8976-rpmpd + - qcom,msm8994-rpmpd - qcom,msm8996-rpmpd - qcom,msm8998-rpmpd - qcom,qcs404-rpmpd diff --git a/Documentation/devicetree/bindings/reset/brcm,bcm4908-misc-pcie-reset.yaml b/Documentation/devicetree/bindings/reset/brcm,bcm4908-misc-pcie-reset.yaml new file mode 100644 index 000000000000..88aebb370838 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/brcm,bcm4908-misc-pcie-reset.yaml @@ -0,0 +1,39 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reset/brcm,bcm4908-misc-pcie-reset.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom MISC block PCIe reset controller + +description: This document describes reset controller handling PCIe PERST# + signals. On BCM4908 it's a part of the MISC block. + +maintainers: + - Rafał Miłecki <rafal@milecki.pl> + +properties: + compatible: + const: brcm,bcm4908-misc-pcie-reset + + reg: + maxItems: 1 + + "#reset-cells": + description: PCIe core id + const: 1 + +required: + - compatible + - reg + - "#reset-cells" + +additionalProperties: false + +examples: + - | + reset-controller@ff802644 { + compatible = "brcm,bcm4908-misc-pcie-reset"; + reg = <0xff802644 0x04>; + #reset-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.txt b/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.txt deleted file mode 100644 index 2df4bddeb688..000000000000 --- a/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.txt +++ /dev/null @@ -1,44 +0,0 @@ -Hisilicon System Reset Controller -====================================== - -Please also refer to reset.txt in this directory for common reset -controller binding usage. - -The reset controller registers are part of the system-ctl block on -hi3660 and hi3670 SoCs. - -Required properties: -- compatible: should be one of the following: - "hisilicon,hi3660-reset" for HI3660 - "hisilicon,hi3670-reset", "hisilicon,hi3660-reset" for HI3670 -- hisi,rst-syscon: phandle of the reset's syscon. -- #reset-cells : Specifies the number of cells needed to encode a - reset source. The type shall be a <u32> and the value shall be 2. - - Cell #1 : offset of the reset assert control - register from the syscon register base - offset + 4: deassert control register - offset + 8: status control register - Cell #2 : bit position of the reset in the reset control register - -Example: - iomcu: iomcu@ffd7e000 { - compatible = "hisilicon,hi3660-iomcu", "syscon"; - reg = <0x0 0xffd7e000 0x0 0x1000>; - }; - - iomcu_rst: iomcu_rst_controller { - compatible = "hisilicon,hi3660-reset"; - hisi,rst-syscon = <&iomcu>; - #reset-cells = <2>; - }; - -Specifying reset lines connected to IP modules -============================================== -example: - - i2c0: i2c@..... { - ... - resets = <&iomcu_rst 0x20 3>; /* offset: 0x20; bit: 3 */ - ... - }; diff --git a/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.yaml b/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.yaml new file mode 100644 index 000000000000..9bf40952e5b7 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.yaml @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reset/hisilicon,hi3660-reset.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Hisilicon System Reset Controller + +maintainers: + - Wei Xu <xuwei5@hisilicon.com> + +description: | + Please also refer to reset.txt in this directory for common reset + controller binding usage. + The reset controller registers are part of the system-ctl block on + hi3660 and hi3670 SoCs. + +properties: + compatible: + oneOf: + - items: + - const: hisilicon,hi3660-reset + - items: + - const: hisilicon,hi3670-reset + - const: hisilicon,hi3660-reset + + hisilicon,rst-syscon: + description: phandle of the reset's syscon. + $ref: /schemas/types.yaml#/definitions/phandle + + '#reset-cells': + description: | + Specifies the number of cells needed to encode a reset source. + Cell #1 : offset of the reset assert control register from the syscon + register base + offset + 4: deassert control register + offset + 8: status control register + Cell #2 : bit position of the reset in the reset control register + const: 2 + +required: + - compatible + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/hi3660-clock.h> + + iomcu: iomcu@ffd7e000 { + compatible = "hisilicon,hi3660-iomcu", "syscon"; + reg = <0xffd7e000 0x1000>; + }; + + iomcu_rst: iomcu_rst_controller { + compatible = "hisilicon,hi3660-reset"; + hisilicon,rst-syscon = <&iomcu>; + #reset-cells = <2>; + }; + + /* Specifying reset lines connected to IP modules */ + i2c@ffd71000 { + compatible = "snps,designware-i2c"; + reg = <0xffd71000 0x1000>; + interrupts = <GIC_SPI 118 IRQ_TYPE_LEVEL_HIGH>; + #address-cells = <1>; + #size-cells = <0>; + clock-frequency = <400000>; + clocks = <&crg_ctrl HI3660_CLK_GATE_I2C0>; + resets = <&iomcu_rst 0x20 3>; + pinctrl-names = "default"; + pinctrl-0 = <&i2c0_pmx_func &i2c0_cfg_func>; + status = "disabled"; + }; +... diff --git a/Documentation/devicetree/bindings/reset/sirf,rstc.txt b/Documentation/devicetree/bindings/reset/sirf,rstc.txt deleted file mode 100644 index 0505de742d30..000000000000 --- a/Documentation/devicetree/bindings/reset/sirf,rstc.txt +++ /dev/null @@ -1,42 +0,0 @@ -CSR SiRFSoC Reset Controller -====================================== - -Please also refer to reset.txt in this directory for common reset -controller binding usage. - -Required properties: -- compatible: Should be "sirf,prima2-rstc" or "sirf,marco-rstc" -- reg: should be register base and length as documented in the - datasheet -- #reset-cells: 1, see below - -example: - -rstc: reset-controller@88010000 { - compatible = "sirf,prima2-rstc"; - reg = <0x88010000 0x1000>; - #reset-cells = <1>; -}; - -Specifying reset lines connected to IP modules -============================================== - -The reset controller(rstc) manages various reset sources. This module provides -reset signals for most blocks in system. Those device nodes should specify the -reset line on the rstc in their resets property, containing a phandle to the -rstc device node and a RESET_INDEX specifying which module to reset, as described -in reset.txt. - -For SiRFSoC, RESET_INDEX is just reset_bit defined in SW_RST0 and SW_RST1 registers. -For modules whose rest_bit is in SW_RST0, its RESET_INDEX is 0~31. For modules whose -rest_bit is in SW_RST1, its RESET_INDEX is 32~63. - -example: - -vpp@90020000 { - compatible = "sirf,prima2-vpp"; - reg = <0x90020000 0x10000>; - interrupts = <31>; - clocks = <&clks 35>; - resets = <&rstc 6>; -}; diff --git a/Documentation/devicetree/bindings/reset/zte,zx2967-reset.txt b/Documentation/devicetree/bindings/reset/zte,zx2967-reset.txt deleted file mode 100644 index b015508f9780..000000000000 --- a/Documentation/devicetree/bindings/reset/zte,zx2967-reset.txt +++ /dev/null @@ -1,20 +0,0 @@ -ZTE zx2967 SoCs Reset Controller -======================================= - -Please also refer to reset.txt in this directory for common reset -controller binding usage. - -Required properties: -- compatible: should be one of the following. - * zte,zx296718-reset -- reg: physical base address of the controller and length of memory mapped - region. -- #reset-cells: must be 1. - -example: - - reset: reset-controller@1461060 { - compatible = "zte,zx296718-reset"; - reg = <0x01461060 0x8>; - #reset-cells = <1>; - }; diff --git a/Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml b/Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml index 37c2a601c3fa..b1b0ee769b71 100644 --- a/Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml +++ b/Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml @@ -128,7 +128,6 @@ required: - compatible - reg - interrupts - - clocks - clock-output-names additionalProperties: false diff --git a/Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml b/Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml index 9702c07a6b6c..2b06c6ce4a75 100644 --- a/Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml +++ b/Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Freescale i.MX Universal Asynchronous Receiver/Transmitter (UART) maintainers: - - Fabio Estevam <fabio.estevam@nxp.com> + - Fabio Estevam <festevam@gmail.com> allOf: - $ref: "serial.yaml" diff --git a/Documentation/devicetree/bindings/serial/fsl-mxs-auart.yaml b/Documentation/devicetree/bindings/serial/fsl-mxs-auart.yaml index ce1d89496342..14c7594c88c6 100644 --- a/Documentation/devicetree/bindings/serial/fsl-mxs-auart.yaml +++ b/Documentation/devicetree/bindings/serial/fsl-mxs-auart.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Freescale MXS Application UART (AUART) maintainers: - - Fabio Estevam <fabio.estevam@nxp.com> + - Fabio Estevam <festevam@gmail.com> allOf: - $ref: "serial.yaml" diff --git a/Documentation/devicetree/bindings/serial/pl011.yaml b/Documentation/devicetree/bindings/serial/pl011.yaml index 07fa6d26f2b4..1f8e9f2644b6 100644 --- a/Documentation/devicetree/bindings/serial/pl011.yaml +++ b/Documentation/devicetree/bindings/serial/pl011.yaml @@ -19,7 +19,6 @@ select: contains: enum: - arm,pl011 - - zte,zx296702-uart required: - compatible @@ -30,7 +29,6 @@ properties: - const: arm,pl011 - const: arm,primecell - items: - - const: zte,zx296702-uart - const: arm,primecell reg: diff --git a/Documentation/devicetree/bindings/serial/renesas,hscif.yaml b/Documentation/devicetree/bindings/serial/renesas,hscif.yaml index c139c5edb93e..512a84942f78 100644 --- a/Documentation/devicetree/bindings/serial/renesas,hscif.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,hscif.yaml @@ -51,6 +51,7 @@ properties: - renesas,hscif-r8a77980 # R-Car V3H - renesas,hscif-r8a77990 # R-Car E3 - renesas,hscif-r8a77995 # R-Car D3 + - renesas,hscif-r8a779a0 # R-Car V3U - const: renesas,rcar-gen3-hscif # R-Car Gen3 and RZ/G2 - const: renesas,hscif # generic HSCIF compatible UART diff --git a/Documentation/devicetree/bindings/serial/sirf-uart.txt b/Documentation/devicetree/bindings/serial/sirf-uart.txt deleted file mode 100644 index 1e48bbbeecc6..000000000000 --- a/Documentation/devicetree/bindings/serial/sirf-uart.txt +++ /dev/null @@ -1,34 +0,0 @@ -* CSR SiRFprimaII/atlasVI Universal Synchronous Asynchronous Receiver/Transmitter * - -Required properties: -- compatible : Should be "sirf,prima2-uart", "sirf, prima2-usp-uart", - "sirf,atlas7-uart" or "sirf,atlas7-usp-uart". -- reg : Offset and length of the register set for the device -- interrupts : Should contain uart interrupt -- fifosize : Should define hardware rx/tx fifo size -- clocks : Should contain uart clock number - -Optional properties: -- uart-has-rtscts: we have hardware flow controller pins in hardware -- rts-gpios: RTS pin for USP-based UART if uart-has-rtscts is true -- cts-gpios: CTS pin for USP-based UART if uart-has-rtscts is true - -Example: - -uart0: uart@b0050000 { - cell-index = <0>; - compatible = "sirf,prima2-uart"; - reg = <0xb0050000 0x1000>; - interrupts = <17>; - fifosize = <128>; - clocks = <&clks 13>; -}; - -On the board-specific dts, we can put rts-gpios and cts-gpios like - -usp@b0090000 { - compatible = "sirf,prima2-usp-uart"; - uart-has-rtscts; - rts-gpios = <&gpio 15 0>; - cts-gpios = <&gpio 46 0>; -}; diff --git a/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml b/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml index 06d5f251ec88..8631678283f9 100644 --- a/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml +++ b/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml @@ -50,11 +50,14 @@ properties: minItems: 1 maxItems: 2 - cts-gpios: - maxItems: 1 - - rts-gpios: - maxItems: 1 +# cts-gpios and rts-gpios properties can be used instead of 'uart-has-rtscts' +# or 'st,hw-flow-ctrl' (deprecated) for making use of any gpio pins for flow +# control instead of dedicated pins. +# +# It should be noted that both cts-gpios/rts-gpios and 'uart-has-rtscts' or +# 'st,hw-flow-ctrl' (deprecated) properties cannot co-exist in a design. + cts-gpios: true + rts-gpios: true wakeup-source: true diff --git a/Documentation/devicetree/bindings/soc/imx/imx8m-soc.yaml b/Documentation/devicetree/bindings/soc/imx/imx8m-soc.yaml new file mode 100644 index 000000000000..effcc72f9425 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/imx/imx8m-soc.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/imx/imx8m-soc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP i.MX8M Series SoC + +maintainers: + - Alice Guo <alice.guo@nxp.com> + +description: | + NXP i.MX8M series SoCs contain fuse entries from which SoC Unique ID can be + obtained. + +select: + properties: + compatible: + contains: + enum: + - fsl,imx8mm + - fsl,imx8mn + - fsl,imx8mp + - fsl,imx8mq + required: + - compatible + +patternProperties: + "^soc@[0-9a-f]+$": + type: object + properties: + compatible: + items: + - enum: + - fsl,imx8mm-soc + - fsl,imx8mn-soc + - fsl,imx8mp-soc + - fsl,imx8mq-soc + - const: simple-bus + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + ranges: true + + dma-ranges: true + + nvmem-cells: + maxItems: 1 + description: Phandle to the SOC Unique ID provided by a nvmem node + + nvmem-cell-names: + const: soc_unique_id + + required: + - compatible + - nvmem-cells + - nvmem-cell-names + + additionalProperties: + type: object + +additionalProperties: true + +examples: + - | + / { + model = "FSL i.MX8MM EVK board"; + compatible = "fsl,imx8mm-evk", "fsl,imx8mm"; + #address-cells = <2>; + #size-cells = <2>; + + soc@0 { + compatible = "fsl,imx8mm-soc", "simple-bus"; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0x0 0x0 0x3e000000>; + nvmem-cells = <&imx8mm_uid>; + nvmem-cell-names = "soc_unique_id"; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt index 953add19e937..19c059e44681 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt @@ -20,6 +20,7 @@ power-domains. "qcom,sdm845-aoss-qmp" "qcom,sm8150-aoss-qmp" "qcom,sm8250-aoss-qmp" + "qcom,sm8350-aoss-qmp" - reg: Usage: required diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smem.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,smem.txt deleted file mode 100644 index 9326cdf6e1b1..000000000000 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,smem.txt +++ /dev/null @@ -1,57 +0,0 @@ -Qualcomm Shared Memory Manager binding - -This binding describes the Qualcomm Shared Memory Manager, used to share data -between various subsystems and OSes in Qualcomm platforms. - -- compatible: - Usage: required - Value type: <stringlist> - Definition: must be: - "qcom,smem" - -- memory-region: - Usage: required - Value type: <prop-encoded-array> - Definition: handle to memory reservation for main SMEM memory region. - -- qcom,rpm-msg-ram: - Usage: required - Value type: <prop-encoded-array> - Definition: handle to RPM message memory resource - -- hwlocks: - Usage: required - Value type: <prop-encoded-array> - Definition: reference to a hwspinlock used to protect allocations from - the shared memory - -= EXAMPLE -The following example shows the SMEM setup for MSM8974, with a main SMEM region -at 0xfa00000 and the RPM message ram at 0xfc428000: - - reserved-memory { - #address-cells = <1>; - #size-cells = <1>; - ranges; - - smem_region: smem@fa00000 { - reg = <0xfa00000 0x200000>; - no-map; - }; - }; - - smem@fa00000 { - compatible = "qcom,smem"; - - memory-region = <&smem_region>; - qcom,rpm-msg-ram = <&rpm_msg_ram>; - - hwlocks = <&tcsr_mutex 3>; - }; - - soc { - rpm_msg_ram: memory@fc428000 { - compatible = "qcom,rpm-msg-ram"; - reg = <0xfc428000 0x4000>; - }; - }; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smem.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,smem.yaml new file mode 100644 index 000000000000..f7e17713b3d8 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smem.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/soc/qcom/qcom,smem.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Qualcomm Shared Memory Manager binding + +maintainers: + - Andy Gross <agross@kernel.org> + - Bjorn Andersson <bjorn.andersson@linaro.org> + +description: | + This binding describes the Qualcomm Shared Memory Manager, used to share data + between various subsystems and OSes in Qualcomm platforms. + +properties: + compatible: + const: qcom,smem + + memory-region: + maxItems: 1 + description: handle to memory reservation for main SMEM memory region. + + hwlocks: + maxItems: 1 + + qcom,rpm-msg-ram: + $ref: /schemas/types.yaml#/definitions/phandle + description: handle to RPM message memory resource + +required: + - compatible + - memory-region + - hwlocks + +additionalProperties: false + +examples: + - | + reserved-memory { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + smem_region: smem@fa00000 { + reg = <0xfa00000 0x200000>; + no-map; + }; + }; + + smem { + compatible = "qcom,smem"; + + memory-region = <&smem_region>; + qcom,rpm-msg-ram = <&rpm_msg_ram>; + + hwlocks = <&tcsr_mutex 3>; + }; + + soc { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + rpm_msg_ram: sram@fc428000 { + compatible = "qcom,rpm-msg-ram"; + reg = <0xfc428000 0x4000>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/soc/ti/ti,pruss.yaml b/Documentation/devicetree/bindings/soc/ti/ti,pruss.yaml index 037c51b2f972..dbc62821c60b 100644 --- a/Documentation/devicetree/bindings/soc/ti/ti,pruss.yaml +++ b/Documentation/devicetree/bindings/soc/ti/ti,pruss.yaml @@ -81,6 +81,9 @@ properties: ranges: maxItems: 1 + dma-ranges: + maxItems: 1 + power-domains: description: | This property is as per sci-pm-domain.txt. @@ -278,6 +281,9 @@ patternProperties: that is common to all the PRU cores. This should be represented as an interrupt-controller node. + allOf: + - $ref: /schemas/interrupt-controller/ti,pruss-intc.yaml# + type: object mdio@[a-f0-9]+$: @@ -299,6 +305,9 @@ patternProperties: present on K3 SoCs have additional auxiliary PRU cores with slightly different IP integration. + allOf: + - $ref: /schemas/remoteproc/ti,pru-rproc.yaml# + type: object required: @@ -371,6 +380,36 @@ examples: reg = <0x32000 0x58>; }; + pruss_intc: interrupt-controller@20000 { + compatible = "ti,pruss-intc"; + reg = <0x20000 0x2000>; + interrupt-controller; + #interrupt-cells = <3>; + interrupts = <20 21 22 23 24 25 26 27>; + interrupt-names = "host_intr0", "host_intr1", + "host_intr2", "host_intr3", + "host_intr4", "host_intr5", + "host_intr6", "host_intr7"; + }; + + pru0: pru@34000 { + compatible = "ti,am3356-pru"; + reg = <0x34000 0x2000>, + <0x22000 0x400>, + <0x22400 0x100>; + reg-names = "iram", "control", "debug"; + firmware-name = "am335x-pru0-fw"; + }; + + pru1: pru@38000 { + compatible = "ti,am3356-pru"; + reg = <0x38000 0x2000>, + <0x24000 0x400>, + <0x24400 0x100>; + reg-names = "iram", "control", "debug"; + firmware-name = "am335x-pru1-fw"; + }; + pruss_mdio: mdio@32400 { compatible = "ti,davinci_mdio"; reg = <0x32400 0x90>; @@ -425,6 +464,43 @@ examples: reg = <0x32000 0x58>; }; + pruss1_intc: interrupt-controller@20000 { + compatible = "ti,pruss-intc"; + reg = <0x20000 0x2000>; + interrupt-controller; + #interrupt-cells = <3>; + interrupts = <GIC_SPI 20 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 21 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 22 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 23 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 24 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 27 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "host_intr0", "host_intr1", + "host_intr2", "host_intr3", + "host_intr4", + "host_intr6", "host_intr7"; + ti,irqs-reserved = /bits/ 8 <0x20>; /* BIT(5) */ + }; + + pru1_0: pru@34000 { + compatible = "ti,am4376-pru"; + reg = <0x34000 0x3000>, + <0x22000 0x400>, + <0x22400 0x100>; + reg-names = "iram", "control", "debug"; + firmware-name = "am437x-pru1_0-fw"; + }; + + pru1_1: pru@38000 { + compatible = "ti,am4376-pru"; + reg = <0x38000 0x3000>, + <0x24000 0x400>, + <0x24400 0x100>; + reg-names = "iram", "control", "debug"; + firmware-name = "am437x-pru1_1-fw"; + }; + pruss1_mdio: mdio@32400 { compatible = "ti,davinci_mdio"; reg = <0x32400 0x90>; diff --git a/Documentation/devicetree/bindings/soc/zte/pd-2967xx.txt b/Documentation/devicetree/bindings/soc/zte/pd-2967xx.txt deleted file mode 100644 index 7629de1c2c72..000000000000 --- a/Documentation/devicetree/bindings/soc/zte/pd-2967xx.txt +++ /dev/null @@ -1,19 +0,0 @@ -* ZTE zx2967 family Power Domains - -zx2967 family includes support for multiple power domains which are used -to gate power to one or more peripherals on the processor. - -Required Properties: - - compatible: should be one of the following. - * zte,zx296718-pcu - for zx296718 power domain. - - reg: physical base address of the controller and length of memory mapped - region. - - #power-domain-cells: Must be 1. - -Example: - - pcu_domain: pcu@117000 { - compatible = "zte,zx296718-pcu"; - reg = <0x00117000 0x1000>; - #power-domain-cells = <1>; - }; diff --git a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml index 2005014161be..766e9109b2f7 100644 --- a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml +++ b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml @@ -71,9 +71,6 @@ properties: description: CPU to Codec rate channels. $ref: /schemas/types.yaml#/definitions/uint32 - required: - - remote-endpoint - ports: description: multi OF-Graph subnode type: object diff --git a/Documentation/devicetree/bindings/sound/ingenic,codec.yaml b/Documentation/devicetree/bindings/sound/ingenic,codec.yaml index eb4be86464bb..97d5f3819b27 100644 --- a/Documentation/devicetree/bindings/sound/ingenic,codec.yaml +++ b/Documentation/devicetree/bindings/sound/ingenic,codec.yaml @@ -15,9 +15,14 @@ properties: compatible: oneOf: - - const: ingenic,jz4770-codec - - const: ingenic,jz4725b-codec - - const: ingenic,jz4740-codec + - enum: + - ingenic,jz4770-codec + - ingenic,jz4760-codec + - ingenic,jz4725b-codec + - ingenic,jz4740-codec + - items: + - const: ingenic,jz4760b-codec + - const: ingenic,jz4760-codec reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml b/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml index d346e61ab708..6f71294909a5 100644 --- a/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml @@ -18,6 +18,7 @@ properties: enum: - intel,keembay-i2s - intel,keembay-tdm + - intel,keembay-hdmi-i2s "#sound-dai-cells": const: 0 @@ -45,6 +46,16 @@ properties: - const: osc - const: apb_clk + dmas: + items: + - description: DMA TX channel + - description: DMA RX channel + + dma-names: + items: + - const: tx + - const: rx + required: - compatible - "#sound-dai-cells" @@ -70,4 +81,6 @@ examples: interrupts = <GIC_SPI 120 IRQ_TYPE_LEVEL_HIGH>; clock-names = "osc", "apb_clk"; clocks = <&scmi_clk KEEM_BAY_PSS_AUX_I2S3>, <&scmi_clk KEEM_BAY_PSS_I2S3>; + dmas = <&axi_dma0 29 &axi_dma0 33>; + dma-names = "tx", "rx"; }; diff --git a/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml b/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml index 54650823b29a..5a5b765b859a 100644 --- a/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml +++ b/Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml @@ -23,6 +23,10 @@ properties: $ref: "/schemas/types.yaml#/definitions/phandle" description: The phandle of MT8192 ASoC platform. + mediatek,hdmi-codec: + $ref: "/schemas/types.yaml#/definitions/phandle" + description: The phandle of HDMI codec. + additionalProperties: false required: @@ -35,6 +39,7 @@ examples: sound: mt8192-sound { compatible = "mediatek,mt8192_mt6359_rt1015_rt5682"; mediatek,platform = <&afe>; + mediatek,hdmi-codec = <&anx_bridge_dp>; pinctrl-names = "aud_clk_mosi_off", "aud_clk_mosi_on"; pinctrl-0 = <&aud_clk_mosi_off>; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml new file mode 100644 index 000000000000..249970952202 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml @@ -0,0 +1,190 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra-audio-graph-card.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Audio Graph based Tegra sound card driver + +description: | + This is based on generic audio graph card driver along with additional + customizations for Tegra platforms. It uses the same bindings with + additional standard clock DT bindings required for Tegra. + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Sameer Pujar <spujar@nvidia.com> + +allOf: + - $ref: audio-graph.yaml# + +properties: + compatible: + enum: + - nvidia,tegra210-audio-graph-card + - nvidia,tegra186-audio-graph-card + + clocks: + minItems: 2 + + clock-names: + minItems: 2 + items: + - const: pll_a + - const: plla_out0 + + assigned-clocks: + minItems: 1 + maxItems: 3 + + assigned-clock-parents: + minItems: 1 + maxItems: 3 + + assigned-clock-rates: + minItems: 1 + maxItems: 3 + + iommus: + maxItems: 1 + +required: + - clocks + - clock-names + - assigned-clocks + - assigned-clock-parents + +unevaluatedProperties: false + +examples: + - | + #include<dt-bindings/clock/tegra210-car.h> + + tegra_sound { + compatible = "nvidia,tegra210-audio-graph-card"; + + clocks = <&tegra_car TEGRA210_CLK_PLL_A>, + <&tegra_car TEGRA210_CLK_PLL_A_OUT0>; + clock-names = "pll_a", "plla_out0"; + + assigned-clocks = <&tegra_car TEGRA210_CLK_PLL_A>, + <&tegra_car TEGRA210_CLK_PLL_A_OUT0>, + <&tegra_car TEGRA210_CLK_EXTERN1>; + assigned-clock-parents = <0>, <0>, <&tegra_car TEGRA210_CLK_PLL_A_OUT0>; + assigned-clock-rates = <368640000>, <49152000>, <12288000>; + + dais = /* FE */ + <&admaif1_port>, + /* Router */ + <&xbar_i2s1_port>, + /* I/O DAP Ports */ + <&i2s1_port>; + + label = "jetson-tx1-ape"; + }; + + // The ports are defined for AHUB and its child devices. + ahub@702d0800 { + compatible = "nvidia,tegra210-ahub"; + reg = <0x702d0800 0x800>; + clocks = <&tegra_car TEGRA210_CLK_D_AUDIO>; + clock-names = "ahub"; + assigned-clocks = <&tegra_car TEGRA210_CLK_D_AUDIO>; + assigned-clock-parents = <&tegra_car TEGRA210_CLK_PLL_A_OUT0>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x702d0000 0x702d0000 0x0000e400>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0x0>; + xbar_admaif1_ep: endpoint { + remote-endpoint = <&admaif1_ep>; + }; + }; + + // ... + + xbar_i2s1_port: port@a { + reg = <0xa>; + xbar_i2s1_ep: endpoint { + remote-endpoint = <&i2s1_cif_ep>; + }; + }; + }; + + admaif@702d0000 { + compatible = "nvidia,tegra210-admaif"; + reg = <0x702d0000 0x800>; + dmas = <&adma 1>, <&adma 1>, + <&adma 2>, <&adma 2>, + <&adma 3>, <&adma 3>, + <&adma 4>, <&adma 4>, + <&adma 5>, <&adma 5>, + <&adma 6>, <&adma 6>, + <&adma 7>, <&adma 7>, + <&adma 8>, <&adma 8>, + <&adma 9>, <&adma 9>, + <&adma 10>, <&adma 10>; + dma-names = "rx1", "tx1", + "rx2", "tx2", + "rx3", "tx3", + "rx4", "tx4", + "rx5", "tx5", + "rx6", "tx6", + "rx7", "tx7", + "rx8", "tx8", + "rx9", "tx9", + "rx10", "tx10"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + admaif1_port: port@0 { + reg = <0x0>; + admaif1_ep: endpoint { + remote-endpoint = <&xbar_admaif1_ep>; + }; + }; + + // More ADMAIF ports to follow + }; + }; + + i2s@702d1000 { + compatible = "nvidia,tegra210-i2s"; + clocks = <&tegra_car TEGRA210_CLK_I2S0>; + clock-names = "i2s"; + assigned-clocks = <&tegra_car TEGRA210_CLK_I2S0>; + assigned-clock-parents = <&tegra_car TEGRA210_CLK_PLL_A_OUT0>; + assigned-clock-rates = <1536000>; + reg = <0x702d1000 0x100>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0x0>; + + i2s1_cif_ep: endpoint { + remote-endpoint = <&xbar_i2s1_ep>; + }; + }; + + i2s1_port: port@1 { + reg = <0x1>; + + i2s1_dap: endpoint { + dai-format = "i2s"; + }; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml index ed2fb32fcdd4..b8645d9c38ac 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml @@ -17,6 +17,9 @@ maintainers: - Jon Hunter <jonathanh@nvidia.com> - Sameer Pujar <spujar@nvidia.com> +allOf: + - $ref: audio-graph-port.yaml# + properties: $nodename: pattern: "^dspk@[0-9a-f]*$" @@ -55,6 +58,19 @@ properties: The name can be "DSPK1" or "DSPKx", where x depends on the maximum available instances on a Tegra SoC. + ports: + type: object + properties: + port@0: + description: | + DSPK ACIF (Audio Client Interface) port connected to the + corresponding AHUB (Audio Hub) ACIF port. + + port@1: + description: | + DSPK DAP (Digital Audio Port) interface which can be connected + to external audio codec for playback. + required: - compatible - reg @@ -64,7 +80,7 @@ required: - assigned-clock-parents - sound-name-prefix -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-admaif.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-admaif.yaml index c028b259e822..7cee7722df41 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-admaif.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-admaif.yaml @@ -17,6 +17,9 @@ maintainers: - Jon Hunter <jonathanh@nvidia.com> - Sameer Pujar <spujar@nvidia.com> +allOf: + - $ref: audio-graph-port.yaml# + properties: $nodename: pattern: "^admaif@[0-9a-f]*$" @@ -37,6 +40,14 @@ properties: dma-names: true + ports: + description: | + Contains list of ACIF (Audio CIF) port nodes for ADMAIF channels. + The number of port nodes depends on the number of ADMAIF channels + that SoC may have. These are interfaced with respective ACIF ports + in AHUB (Audio Hub). Each port is capable of data transfers in + both directions. + if: properties: compatible: @@ -81,7 +92,7 @@ required: - dmas - dma-names -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml index d77219727768..31f3e51974bb 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml @@ -17,6 +17,9 @@ maintainers: - Jon Hunter <jonathanh@nvidia.com> - Sameer Pujar <spujar@nvidia.com> +allOf: + - $ref: audio-graph-port.yaml# + properties: $nodename: pattern: "^ahub@[0-9a-f]*$" @@ -56,6 +59,13 @@ properties: ranges: true + ports: + description: | + Contains list of ACIF (Audio CIF) port nodes for AHUB (Audio Hub). + These are connected to ACIF interfaces of AHUB clients. Thus the + number of port nodes depend on the number of clients that AHUB may + have depending on the SoC revision. + required: - compatible - reg @@ -67,8 +77,7 @@ required: - "#size-cells" - ranges -additionalProperties: - type: object +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml index 2a3207b550e7..89f4f471be24 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml @@ -16,6 +16,9 @@ maintainers: - Jon Hunter <jonathanh@nvidia.com> - Sameer Pujar <spujar@nvidia.com> +allOf: + - $ref: audio-graph-port.yaml# + properties: $nodename: pattern: "^dmic@[0-9a-f]*$" @@ -56,6 +59,19 @@ properties: The name can be "DMIC1" or "DMIC2" ... "DMICx", where x depends on the maximum available instances on a Tegra SoC. + ports: + type: object + properties: + port@0: + description: | + DMIC ACIF (Audio Client Interface) port connected to the + corresponding AHUB (Audio Hub) ACIF port. + + port@1: + description: | + DMIC DAP (Digital Audio Port) interface which can be connected + to external audio codec for capture. + required: - compatible - reg @@ -64,7 +80,7 @@ required: - assigned-clocks - assigned-clock-parents -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml index dfc1bf7b7722..556460332ffb 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml @@ -16,6 +16,9 @@ maintainers: - Jon Hunter <jonathanh@nvidia.com> - Sameer Pujar <spujar@nvidia.com> +allOf: + - $ref: audio-graph-port.yaml# + properties: $nodename: pattern: "^i2s@[0-9a-f]*$" @@ -74,6 +77,19 @@ properties: The name can be "I2S1" or "I2S2" ... "I2Sx", where x depends on the maximum available instances on a Tegra SoC. + ports: + type: object + properties: + port@0: + description: | + I2S ACIF (Audio Client Interface) port connected to the + corresponding AHUB (Audio Hub) ACIF port. + + port@1: + description: | + I2S DAP (Digital Audio Port) interface which can be connected + to external audio codec for playback or capture. + required: - compatible - reg @@ -82,7 +98,7 @@ required: - assigned-clocks - assigned-clock-parents -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml new file mode 100644 index 000000000000..443d556caa69 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,lpass-rx-macro.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: LPASS(Low Power Audio Subsystem) RX Macro audio codec DT bindings + +maintainers: + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +properties: + compatible: + const: qcom,sm8250-lpass-rx-macro + + reg: + maxItems: 1 + + "#sound-dai-cells": + const: 1 + + '#clock-cells': + const: 0 + + clocks: + maxItems: 5 + + clock-names: + items: + - const: mclk + - const: npl + - const: macro + - const: dcodec + - const: fsgen + + clock-output-names: + items: + - const: mclk + +required: + - compatible + - reg + - "#sound-dai-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/sound/qcom,q6afe.h> + codec@3200000 { + compatible = "qcom,sm8250-lpass-rx-macro"; + reg = <0x3200000 0x1000>; + #sound-dai-cells = <1>; + #clock-cells = <0>; + clocks = <&audiocc 0>, + <&audiocc 1>, + <&q6afecc LPASS_HW_MACRO_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>, + <&q6afecc LPASS_HW_DCODEC_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>, + <&vamacro>; + clock-names = "mclk", "npl", "macro", "dcodec", "fsgen"; + clock-output-names = "mclk"; + }; diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml new file mode 100644 index 000000000000..6b5ca02ccce4 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,lpass-tx-macro.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: LPASS(Low Power Audio Subsystem) TX Macro audio codec DT bindings + +maintainers: + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +properties: + compatible: + const: qcom,sm8250-lpass-tx-macro + + reg: + maxItems: 1 + + "#sound-dai-cells": + const: 1 + + '#clock-cells': + const: 0 + + clocks: + maxItems: 5 + + clock-names: + items: + - const: mclk + - const: npl + - const: macro + - const: dcodec + - const: fsgen + + clock-output-names: + items: + - const: mclk + + qcom,dmic-sample-rate: + description: dmic sample rate + $ref: /schemas/types.yaml#/definitions/uint32 + +required: + - compatible + - reg + - "#sound-dai-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/sound/qcom,q6afe.h> + codec@3220000 { + compatible = "qcom,sm8250-lpass-tx-macro"; + reg = <0x3220000 0x1000>; + #sound-dai-cells = <1>; + #clock-cells = <0>; + clocks = <&aoncc 0>, + <&aoncc 1>, + <&q6afecc LPASS_HW_MACRO_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>, + <&q6afecc LPASS_HW_DCODEC_VOTE LPASS_CLK_ATTRIBUTE_COUPLE_NO>, + <&vamacro>; + clock-names = "mclk", "npl", "macro", "dcodec", "fsgen"; + clock-output-names = "mclk"; + qcom,dmic-sample-rate = <600000>; + }; diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml index 0fd37aa84947..2e1046513603 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml @@ -404,7 +404,7 @@ examples: /* DAI base */ rcar_sound,dai { dai0 { - playback = <&ssi5 &src5>; + playback = <&ssi5>, <&src5>; capture = <&ssi6>; }; dai1 { @@ -430,8 +430,8 @@ examples: bitclock-master = <&rsnd_endpoint0>; frame-master = <&rsnd_endpoint0>; - playback = <&ssi0 &src0 &dvc0>; - capture = <&ssi1 &src1 &dvc1>; + playback = <&ssi0>, <&src0>, <&dvc0>; + capture = <&ssi1>, <&src1>, <&dvc1>; }; }; }; diff --git a/Documentation/devicetree/bindings/sound/rt5659.txt b/Documentation/devicetree/bindings/sound/rt5659.txt index 56788f50b6cf..c473df5c878c 100644 --- a/Documentation/devicetree/bindings/sound/rt5659.txt +++ b/Documentation/devicetree/bindings/sound/rt5659.txt @@ -37,10 +37,21 @@ Optional properties: - realtek,jd-src 0: No JD is used 1: using JD3 as JD source + 2: JD source for Intel HDA header - 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.txt + +- ports: A Codec may have a single or multiple I2S interfaces. These + interfaces on Codec side can be described under 'ports' or 'port'. + When the SoC or host device is connected to multiple interfaces of + the Codec, the connectivity can be described using 'ports' property. + If a single interface is used, then 'port' can be used. The usage + depends on the platform or board design. + Please refer to Documentation/devicetree/bindings/graph.txt + Pins on the device (for linking into audio routes) for RT5659/RT5658: * DMIC L1 diff --git a/Documentation/devicetree/bindings/sound/sirf-audio-codec.txt b/Documentation/devicetree/bindings/sound/sirf-audio-codec.txt deleted file mode 100644 index 062f5ec36f9b..000000000000 --- a/Documentation/devicetree/bindings/sound/sirf-audio-codec.txt +++ /dev/null @@ -1,17 +0,0 @@ -SiRF internal audio CODEC - -Required properties: - - - compatible : "sirf,atlas6-audio-codec" or "sirf,prima2-audio-codec" - - - reg : the register address of the device. - - - clocks: the clock of SiRF internal audio codec - -Example: - -audiocodec: audiocodec@b0040000 { - compatible = "sirf,atlas6-audio-codec"; - reg = <0xb0040000 0x10000>; - clocks = <&clks 27>; -}; diff --git a/Documentation/devicetree/bindings/sound/sirf-usp.txt b/Documentation/devicetree/bindings/sound/sirf-usp.txt deleted file mode 100644 index 02f85b32d359..000000000000 --- a/Documentation/devicetree/bindings/sound/sirf-usp.txt +++ /dev/null @@ -1,27 +0,0 @@ -* SiRF SoC USP module - -Required properties: -- compatible: "sirf,prima2-usp-pcm" -- reg: Base address and size entries: -- dmas: List of DMA controller phandle and DMA request line ordered pairs. -- dma-names: Identifier string for each DMA request line in the dmas property. - These strings correspond 1:1 with the ordered pairs in dmas. - - One of the DMA channels will be responsible for transmission (should be - named "tx") and one for reception (should be named "rx"). - -- clocks: USP controller clock source -- pinctrl-names: Must contain a "default" entry. -- pinctrl-NNN: One property must exist for each entry in pinctrl-names. - -Example: -usp0: usp@b0080000 { - compatible = "sirf,prima2-usp-pcm"; - reg = <0xb0080000 0x10000>; - clocks = <&clks 28>; - dmas = <&dmac1 1>, <&dmac1 2>; - dma-names = "rx", "tx"; - pinctrl-names = "default"; - pinctrl-0 = <&usp0_only_utfs_pins_a>; -}; - diff --git a/Documentation/devicetree/bindings/sound/st,stm32-i2s.yaml b/Documentation/devicetree/bindings/sound/st,stm32-i2s.yaml index f32410890589..6feb5a09c184 100644 --- a/Documentation/devicetree/bindings/sound/st,stm32-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/st,stm32-i2s.yaml @@ -54,6 +54,10 @@ properties: resets: maxItems: 1 + "#clock-cells": + description: Configure the I2S device as MCLK clock provider. + const: 0 + required: - compatible - "#sound-dai-cells" diff --git a/Documentation/devicetree/bindings/sound/wm8962.txt b/Documentation/devicetree/bindings/sound/wm8962.txt index dcfa9a3369fd..c36c649ddfd0 100644 --- a/Documentation/devicetree/bindings/sound/wm8962.txt +++ b/Documentation/devicetree/bindings/sound/wm8962.txt @@ -9,6 +9,9 @@ Required properties: - reg : the I2C address of the device. Optional properties: + + - clocks : The clock source of the mclk + - spk-mono: This is a boolean property. If present, the SPK_MONO bit of R51 (Class D Control 2) gets set, indicating that the speaker is in mono mode. @@ -27,6 +30,7 @@ Example: wm8962: codec@1a { compatible = "wlf,wm8962"; reg = <0x1a>; + clocks = <&clks IMX6QDL_CLK_CKO>; gpio-cfg = < 0x0000 /* 0:Default */ diff --git a/Documentation/devicetree/bindings/sound/zte,tdm.txt b/Documentation/devicetree/bindings/sound/zte,tdm.txt deleted file mode 100644 index 2a07ca655264..000000000000 --- a/Documentation/devicetree/bindings/sound/zte,tdm.txt +++ /dev/null @@ -1,30 +0,0 @@ -ZTE TDM DAI driver - -Required properties: - -- compatible : should be one of the following. - * zte,zx296718-tdm -- reg : physical base address of the controller and length of memory mapped - region. -- clocks : Pairs of phandle and specifier referencing the controller's clocks. -- clock-names: "wclk" for the wclk. - "pclk" for the pclk. --#clock-cells: should be 1. -- zte,tdm-dma-sysctrl : Reference to the sysctrl controller controlling - the dma. includes: - phandle of sysctrl. - register offset in sysctrl for control dma. - mask of the register that be written to sysctrl. - -Example: - - tdm: tdm@1487000 { - compatible = "zte,zx296718-tdm"; - reg = <0x01487000 0x1000>; - clocks = <&audiocrm AUDIO_TDM_WCLK>, <&audiocrm AUDIO_TDM_PCLK>; - clock-names = "wclk", "pclk"; - #clock-cells = <1>; - pinctrl-names = "default"; - pinctrl-0 = <&tdm_global_pin>; - zte,tdm-dma-sysctrl = <&sysctrl 0x10c 4>; - }; diff --git a/Documentation/devicetree/bindings/sound/zte,zx-aud96p22.txt b/Documentation/devicetree/bindings/sound/zte,zx-aud96p22.txt deleted file mode 100644 index 41bb1040eb71..000000000000 --- a/Documentation/devicetree/bindings/sound/zte,zx-aud96p22.txt +++ /dev/null @@ -1,24 +0,0 @@ -ZTE ZX AUD96P22 Audio Codec - -Required properties: - - compatible: Must be "zte,zx-aud96p22" - - #sound-dai-cells: Should be 0 - - reg: I2C bus slave address of AUD96P22 - -Example: - - i2c0: i2c@1486000 { - compatible = "zte,zx296718-i2c"; - reg = <0x01486000 0x1000>; - interrupts = <GIC_SPI 35 IRQ_TYPE_LEVEL_HIGH>; - #address-cells = <1>; - #size-cells = <0>; - clocks = <&audiocrm AUDIO_I2C0_WCLK>; - clock-frequency = <1600000>; - - aud96p22: codec@22 { - compatible = "zte,zx-aud96p22"; - #sound-dai-cells = <0>; - reg = <0x22>; - }; - }; diff --git a/Documentation/devicetree/bindings/sound/zte,zx-i2s.txt b/Documentation/devicetree/bindings/sound/zte,zx-i2s.txt deleted file mode 100644 index 3927251464f0..000000000000 --- a/Documentation/devicetree/bindings/sound/zte,zx-i2s.txt +++ /dev/null @@ -1,45 +0,0 @@ -ZTE ZX296702 I2S controller - -Required properties: - - compatible : Must be one of: - "zte,zx296718-i2s", "zte,zx296702-i2s" - "zte,zx296702-i2s" - - reg : Must contain I2S core's registers location and length - - clocks : Pairs of phandle and specifier referencing the controller's clocks. - - clock-names: "wclk" for the wclk, "pclk" for the pclk to the I2S interface. - - dmas: Pairs of phandle and specifier for the DMA channel that is used by - the core. The core expects two dma channels for transmit. - - dma-names : Must be "tx" and "rx" - -For more details on the 'dma', 'dma-names', 'clock' and 'clock-names' properties -please check: - * resource-names.txt - * clock/clock-bindings.txt - * dma/dma.txt - -Example: - i2s0: i2s@b005000 { - #sound-dai-cells = <0>; - compatible = "zte,zx296718-i2s", "zte,zx296702-i2s"; - reg = <0x0b005000 0x1000>; - clocks = <&audiocrm AUDIO_I2S0_WCLK>, <&audiocrm AUDIO_I2S0_PCLK>; - clock-names = "wclk", "pclk"; - interrupts = <GIC_SPI 22 IRQ_TYPE_LEVEL_HIGH>; - dmas = <&dma 5>, <&dma 6>; - dma-names = "tx", "rx"; - }; - - sound { - compatible = "simple-audio-card"; - simple-audio-card,name = "zx296702_snd"; - simple-audio-card,format = "left_j"; - simple-audio-card,bitclock-master = <&sndcodec>; - simple-audio-card,frame-master = <&sndcodec>; - sndcpu: simple-audio-card,cpu { - sound-dai = <&i2s0>; - }; - - sndcodec: simple-audio-card,codec { - sound-dai = <&acodec>; - }; - }; diff --git a/Documentation/devicetree/bindings/sound/zte,zx-spdif.txt b/Documentation/devicetree/bindings/sound/zte,zx-spdif.txt deleted file mode 100644 index 09231d7586b2..000000000000 --- a/Documentation/devicetree/bindings/sound/zte,zx-spdif.txt +++ /dev/null @@ -1,27 +0,0 @@ -ZTE ZX296702 SPDIF controller - -Required properties: - - compatible : Must be "zte,zx296702-spdif" - - reg : Must contain SPDIF core's registers location and length - - clocks : Pairs of phandle and specifier referencing the controller's clocks. - - clock-names: "tx" for the clock to the SPDIF interface. - - dmas: Pairs of phandle and specifier for the DMA channel that is used by - the core. The core expects one dma channel for transmit. - - dma-names : Must be "tx" - -For more details on the 'dma', 'dma-names', 'clock' and 'clock-names' properties -please check: - * resource-names.txt - * clock/clock-bindings.txt - * dma/dma.txt - -Example: - spdif0: spdif0@b004000 { - compatible = "zte,zx296702-spdif"; - reg = <0x0b004000 0x1000>; - clocks = <&lsp0clk ZX296702_SPDIF0_DIV>; - clock-names = "tx"; - interrupts = <GIC_SPI 21 IRQ_TYPE_LEVEL_HIGH>; - dmas = <&dma 4>; - dma-names = "tx"; - }; diff --git a/Documentation/devicetree/bindings/spi/spi-zynq-qspi.txt b/Documentation/devicetree/bindings/spi/spi-zynq-qspi.txt deleted file mode 100644 index 16b734ad3102..000000000000 --- a/Documentation/devicetree/bindings/spi/spi-zynq-qspi.txt +++ /dev/null @@ -1,25 +0,0 @@ -Xilinx Zynq QSPI controller Device Tree Bindings -------------------------------------------------------------------- - -Required properties: -- compatible : Should be "xlnx,zynq-qspi-1.0". -- reg : Physical base address and size of QSPI registers map. -- interrupts : Property with a value describing the interrupt - number. -- clock-names : List of input clock names - "ref_clk", "pclk" - (See clock bindings for details). -- clocks : Clock phandles (see clock bindings for details). - -Optional properties: -- num-cs : Number of chip selects used. - -Example: - qspi: spi@e000d000 { - compatible = "xlnx,zynq-qspi-1.0"; - reg = <0xe000d000 0x1000>; - interrupt-parent = <&intc>; - interrupts = <0 19 4>; - clock-names = "ref_clk", "pclk"; - clocks = <&clkc 10>, <&clkc 43>; - num-cs = <1>; - }; diff --git a/Documentation/devicetree/bindings/spi/xlnx,zynq-qspi.yaml b/Documentation/devicetree/bindings/spi/xlnx,zynq-qspi.yaml new file mode 100644 index 000000000000..1f1c40a9f320 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/xlnx,zynq-qspi.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/xlnx,zynq-qspi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx Zynq QSPI controller + +description: + The Xilinx Zynq QSPI controller is used to access multi-bit serial flash + memory devices. + +allOf: + - $ref: "spi-controller.yaml#" + +maintainers: + - Michal Simek <michal.simek@xilinx.com> + +# Everything else is described in the common file +properties: + compatible: + const: xlnx,zynq-qspi-1.0 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: reference clock + - description: peripheral clock + + clock-names: + items: + - const: ref_clk + - const: pclk + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + spi@e000d000 { + compatible = "xlnx,zynq-qspi-1.0"; + reg = <0xe000d000 0x1000>; + interrupt-parent = <&intc>; + interrupts = <0 19 4>; + clock-names = "ref_clk", "pclk"; + clocks = <&clkc 10>, <&clkc 43>; + num-cs = <1>; + }; diff --git a/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml b/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml index b66a07e21d1e..1c426c211e36 100644 --- a/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml +++ b/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml @@ -49,6 +49,7 @@ properties: - items: - const: allwinner,suniv-f1c100s-system-control - const: allwinner,sun4i-a10-system-control + - const: allwinner,sun50i-h616-system-control reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sram/sram.yaml b/Documentation/devicetree/bindings/sram/sram.yaml index 19d116ff9ddc..6d65771e979c 100644 --- a/Documentation/devicetree/bindings/sram/sram.yaml +++ b/Documentation/devicetree/bindings/sram/sram.yaml @@ -72,6 +72,8 @@ patternProperties: - allwinner,sun4i-a10-sram-d - allwinner,sun9i-a80-smp-sram - allwinner,sun50i-a64-sram-c + - amlogic,meson8-ao-arc-sram + - amlogic,meson8b-ao-arc-sram - amlogic,meson8-smp-sram - amlogic,meson8b-smp-sram - amlogic,meson-gxbb-scp-shmem diff --git a/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.txt b/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.txt index ea22dfe485be..97258f1a1505 100644 --- a/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.txt +++ b/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.txt @@ -6,8 +6,7 @@ timer counters. Required properties: - compatible : "nuvoton,npcm750-timer" for Poleg NPCM750. - reg : Offset and length of the register set for the device. -- interrupts : Contain the timer interrupt with flags for - falling edge. +- interrupts : Contain the timer interrupt of timer 0. - clocks : phandle of timer reference clock (usually a 25 MHz clock). Example: diff --git a/Documentation/devicetree/bindings/timer/stericsson-u300-apptimer.txt b/Documentation/devicetree/bindings/timer/stericsson-u300-apptimer.txt deleted file mode 100644 index 9499bc8ee9e3..000000000000 --- a/Documentation/devicetree/bindings/timer/stericsson-u300-apptimer.txt +++ /dev/null @@ -1,18 +0,0 @@ -ST-Ericsson U300 apptimer - -Required properties: - -- compatible : should be "stericsson,u300-apptimer" -- reg : Specifies base physical address and size of the registers. -- interrupts : A list of 4 interrupts; one for each subtimer. These - are, in order: OS (operating system), DD (device driver) both - adopted for EPOC/Symbian with two specific IRQs for these tasks, - then GP1 and GP2, which are general-purpose timers. - -Example: - -timer { - compatible = "stericsson,u300-apptimer"; - reg = <0xc0014000 0x1000>; - interrupts = <24 25 26 27>; -}; diff --git a/Documentation/devicetree/bindings/timer/ti,c64x+timer64.txt b/Documentation/devicetree/bindings/timer/ti,c64x+timer64.txt deleted file mode 100644 index d96c1e283e73..000000000000 --- a/Documentation/devicetree/bindings/timer/ti,c64x+timer64.txt +++ /dev/null @@ -1,25 +0,0 @@ -Timer64 -------- - -The timer64 node describes C6X event timers. - -Required properties: - -- compatible: must be "ti,c64x+timer64" -- reg: base address and size of register region -- interrupts: interrupt id - -Optional properties: - -- ti,dscr-dev-enable: Device ID used to enable timer IP through DSCR interface. - -- ti,core-mask: on multi-core SoCs, bitmask of cores allowed to use this timer. - -Example: - timer0: timer@25e0000 { - compatible = "ti,c64x+timer64"; - ti,core-mask = < 0x01 >; - reg = <0x25e0000 0x40>; - interrupt-parent = <&megamod_pic>; - interrupts = < 16 >; - }; diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index bdc2dc318178..a327130d1faa 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -148,15 +148,13 @@ properties: - maxim,max31730 # mCube 3-axis 8-bit digital accelerometer - mcube,mc3230 - # MEMSIC magnetometer - - memsic,mmc35240 - # MEMSIC 2-axis 8-bit digital accelerometer - - memsic,mxc6225 # Measurement Specialities I2C temperature and humidity sensor - meas,htu21 # Measurement Specialities I2C pressure and temperature sensor - meas,ms5637 # Measurement Specialities I2C pressure and temperature sensor + - meas,ms5803 + # Measurement Specialities I2C pressure and temperature sensor - meas,ms5805 # Measurement Specialities I2C pressure and temperature sensor - meas,ms5837 @@ -166,6 +164,10 @@ properties: - meas,ms8607-temppressure # Measurement Specialties temperature sensor - meas,tsys01 + # MEMSIC magnetometer + - memsic,mmc35240 + # MEMSIC 2-axis 8-bit digital accelerometer + - memsic,mxc6225 # Microchip differential I2C ADC, 1 Channel, 18 bit - microchip,mcp3421 # Microchip differential I2C ADC, 2 Channel, 18 bit diff --git a/Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml b/Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml index c0058332b967..e349fa5de606 100644 --- a/Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml +++ b/Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml @@ -79,7 +79,9 @@ properties: patternProperties: "^usb@[0-9a-f]+$": - type: object + oneOf: + - $ref: dwc2.yaml# + - $ref: snps,dwc3.yaml# additionalProperties: false @@ -229,6 +231,6 @@ examples: interrupts = <30>; dr_mode = "host"; snps,dis_u2_susphy_quirk; - snps,quirk-frame-length-adjustment; + snps,quirk-frame-length-adjustment = <0x20>; }; }; diff --git a/Documentation/devicetree/bindings/usb/dwc3-st.txt b/Documentation/devicetree/bindings/usb/dwc3-st.txt index df0e02e1ee43..bf73de0d5b4a 100644 --- a/Documentation/devicetree/bindings/usb/dwc3-st.txt +++ b/Documentation/devicetree/bindings/usb/dwc3-st.txt @@ -31,13 +31,13 @@ See: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt Sub-nodes: The dwc3 core should be added as subnode to ST DWC3 glue as shown in the example below. The DT binding details of dwc3 can be found in: -Documentation/devicetree/bindings/usb/dwc3.txt +Documentation/devicetree/bindings/usb/snps,dwc3.yaml NB: The dr_mode property described in [1] is NOT optional for this driver, as the default value is "otg", which isn't supported by this SoC. Valid dr_mode values for dwc3-st are either "host" or "device". -[1] Documentation/devicetree/bindings/usb/generic.txt +[1] Documentation/devicetree/bindings/usb/usb-drd.yaml Example: diff --git a/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt b/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt index 4aae5b2cef56..a668f43bedf5 100644 --- a/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt +++ b/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt @@ -19,7 +19,7 @@ Example device node: #address-cells = <0x2>; #size-cells = <0x1>; compatible = "xlnx,zynqmp-dwc3"; - clock-names = "bus_clk" "ref_clk"; + clock-names = "bus_clk", "ref_clk"; clocks = <&clk125>, <&clk125>; ranges; diff --git a/Documentation/devicetree/bindings/usb/dwc3.txt b/Documentation/devicetree/bindings/usb/dwc3.txt deleted file mode 100644 index 1aae2b6160c1..000000000000 --- a/Documentation/devicetree/bindings/usb/dwc3.txt +++ /dev/null @@ -1,128 +0,0 @@ -synopsys DWC3 CORE - -DWC3- USB3 CONTROLLER. Complies to the generic USB binding properties - as described in 'usb/generic.txt' - -Required properties: - - compatible: must be "snps,dwc3" - - reg : Address and length of the register set for the device - - interrupts: Interrupts used by the dwc3 controller. - - clock-names: list of clock names. Ideally should be "ref", - "bus_early", "suspend" but may be less or more. - - clocks: list of phandle and clock specifier pairs corresponding to - entries in the clock-names property. - -Exception for clocks: - clocks are optional if the parent node (i.e. glue-layer) is compatible to - one of the following: - "cavium,octeon-7130-usb-uctl" - "qcom,dwc3" - "samsung,exynos5250-dwusb3" - "samsung,exynos5433-dwusb3" - "samsung,exynos7-dwusb3" - "sprd,sc9860-dwc3" - "st,stih407-dwc3" - "ti,am437x-dwc3" - "ti,dwc3" - "ti,keystone-dwc3" - "rockchip,rk3399-dwc3" - "xlnx,zynqmp-dwc3" - -Optional properties: - - usb-phy : array of phandle for the PHY device. The first element - in the array is expected to be a handle to the USB2/HS PHY and - the second element is expected to be a handle to the USB3/SS PHY - - phys: from the *Generic PHY* bindings - - phy-names: from the *Generic PHY* bindings; supported names are "usb2-phy" - or "usb3-phy". - - resets: set of phandle and reset specifier pairs - - snps,usb2-lpm-disable: indicate if we don't want to enable USB2 HW LPM - - snps,usb3_lpm_capable: determines if platform is USB3 LPM capable - - snps,dis-start-transfer-quirk: when set, disable isoc START TRANSFER command - failure SW work-around for DWC_usb31 version 1.70a-ea06 - and prior. - - snps,disable_scramble_quirk: true when SW should disable data scrambling. - Only really useful for FPGA builds. - - snps,has-lpm-erratum: true when DWC3 was configured with LPM Erratum enabled - - snps,lpm-nyet-threshold: LPM NYET threshold - - snps,u2exit_lfps_quirk: set if we want to enable u2exit lfps quirk - - snps,u2ss_inp3_quirk: set if we enable P3 OK for U2/SS Inactive quirk - - snps,req_p1p2p3_quirk: when set, the core will always request for - P1/P2/P3 transition sequence. - - snps,del_p1p2p3_quirk: when set core will delay P1/P2/P3 until a certain - amount of 8B10B errors occur. - - snps,del_phy_power_chg_quirk: when set core will delay PHY power change - from P0 to P1/P2/P3. - - snps,lfps_filter_quirk: when set core will filter LFPS reception. - - snps,rx_detect_poll_quirk: when set core will disable a 400us delay to start - Polling LFPS after RX.Detect. - - snps,tx_de_emphasis_quirk: when set core will set Tx de-emphasis value. - - snps,tx_de_emphasis: the value driven to the PHY is controlled by the - LTSSM during USB3 Compliance mode. - - snps,dis_u3_susphy_quirk: when set core will disable USB3 suspend phy. - - snps,dis_u2_susphy_quirk: when set core will disable USB2 suspend phy. - - snps,dis_enblslpm_quirk: when set clears the enblslpm in GUSB2PHYCFG, - disabling the suspend signal to the PHY. - - snps,dis-u1-entry-quirk: set if link entering into U1 needs to be disabled. - - snps,dis-u2-entry-quirk: set if link entering into U2 needs to be disabled. - - snps,dis_rxdet_inp3_quirk: when set core will disable receiver detection - in PHY P3 power state. - - snps,dis-u2-freeclk-exists-quirk: when set, clear the u2_freeclk_exists - in GUSB2PHYCFG, specify that USB2 PHY doesn't provide - a free-running PHY clock. - - snps,dis-del-phy-power-chg-quirk: when set core will change PHY power - from P0 to P1/P2/P3 without delay. - - snps,dis-tx-ipgap-linecheck-quirk: when set, disable u2mac linestate check - during HS transmit. - - snps,parkmode-disable-ss-quirk: when set, all SuperSpeed bus instances in - park mode are disabled. - - snps,dis_metastability_quirk: when set, disable metastability workaround. - CAUTION: use only if you are absolutely sure of it. - - snps,dis-split-quirk: when set, change the way URBs are handled by the - driver. Needed to avoid -EPROTO errors with usbhid - on some devices (Hikey 970). - - snps,is-utmi-l1-suspend: true when DWC3 asserts output signal - utmi_l1_suspend_n, false when asserts utmi_sleep_n - - snps,hird-threshold: HIRD threshold - - snps,hsphy_interface: High-Speed PHY interface selection between "utmi" for - UTMI+ and "ulpi" for ULPI when the DWC_USB3_HSPHY_INTERFACE has value 3. - - snps,quirk-frame-length-adjustment: Value for GFLADJ_30MHZ field of GFLADJ - register for post-silicon frame length adjustment when the - fladj_30mhz_sdbnd signal is invalid or incorrect. - - snps,rx-thr-num-pkt-prd: periodic ESS RX packet threshold count - host mode - only. Set this and rx-max-burst-prd to a valid, - non-zero value 1-16 (DWC_usb31 programming guide - section 1.2.4) to enable periodic ESS RX threshold. - - snps,rx-max-burst-prd: max periodic ESS RX burst size - host mode only. Set - this and rx-thr-num-pkt-prd to a valid, non-zero value - 1-16 (DWC_usb31 programming guide section 1.2.4) to - enable periodic ESS RX threshold. - - snps,tx-thr-num-pkt-prd: periodic ESS TX packet threshold count - host mode - only. Set this and tx-max-burst-prd to a valid, - non-zero value 1-16 (DWC_usb31 programming guide - section 1.2.3) to enable periodic ESS TX threshold. - - snps,tx-max-burst-prd: max periodic ESS TX burst size - host mode only. Set - this and tx-thr-num-pkt-prd to a valid, non-zero value - 1-16 (DWC_usb31 programming guide section 1.2.3) to - enable periodic ESS TX threshold. - - - <DEPRECATED> tx-fifo-resize: determines if the FIFO *has* to be reallocated. - - snps,incr-burst-type-adjustment: Value for INCR burst type of GSBUSCFG0 - register, undefined length INCR burst type enable and INCRx type. - When just one value, which means INCRX burst mode enabled. When - more than one value, which means undefined length INCR burst type - enabled. The values can be 1, 4, 8, 16, 32, 64, 128 and 256. - - - in addition all properties from usb-xhci.txt from the current directory are - supported as well - - -This is usually a subnode to DWC3 glue to which it is connected. - -dwc3@4a030000 { - compatible = "snps,dwc3"; - reg = <0x4a030000 0xcfff>; - interrupts = <0 92 4> - usb-phy = <&usb2_phy>, <&usb3,phy>; - snps,incr-burst-type-adjustment = <1>, <4>, <8>, <16>; -}; diff --git a/Documentation/devicetree/bindings/usb/exynos-usb.txt b/Documentation/devicetree/bindings/usb/exynos-usb.txt index 6aae1544f240..f7ae79825d7d 100644 --- a/Documentation/devicetree/bindings/usb/exynos-usb.txt +++ b/Documentation/devicetree/bindings/usb/exynos-usb.txt @@ -93,7 +93,7 @@ Sub-nodes: The dwc3 core should be added as subnode to Exynos dwc3 glue. - dwc3 : The binding details of dwc3 can be found in: - Documentation/devicetree/bindings/usb/dwc3.txt + Documentation/devicetree/bindings/usb/snps,dwc3.yaml Example: usb@12000000 { diff --git a/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml b/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml new file mode 100644 index 000000000000..cb4c6f6d3a33 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml @@ -0,0 +1,105 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (c) 2020 NXP +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/fsl,imx8mp-dwc3.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP iMX8MP Soc USB Controller + +maintainers: + - Li Jun <jun.li@nxp.com> + +properties: + compatible: + const: fsl,imx8mp-dwc3 + + reg: + maxItems: 1 + description: Address and length of the register set for the wrapper of + dwc3 core on the SOC. + + "#address-cells": + enum: [ 1, 2 ] + + "#size-cells": + enum: [ 1, 2 ] + + dma-ranges: + description: + See section 2.3.9 of the DeviceTree Specification. + + ranges: true + + interrupts: + maxItems: 1 + description: The interrupt that is asserted when a wakeup event is + received. + + clocks: + description: + A list of phandle and clock-specifier pairs for the clocks + listed in clock-names. + items: + - description: system hsio root clock. + - description: suspend clock, used for usb wakeup logic. + + clock-names: + items: + - const: hsio + - const: suspend + +# Required child node: + +patternProperties: + "^dwc3@[0-9a-f]+$": + type: object + description: + A child node must exist to represent the core DWC3 IP block + The content of the node is defined in dwc3.txt. + +required: + - compatible + - reg + - "#address-cells" + - "#size-cells" + - dma-ranges + - ranges + - clocks + - clock-names + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx8mp-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + usb3_0: usb@32f10100 { + compatible = "fsl,imx8mp-dwc3"; + reg = <0x32f10100 0x8>; + clocks = <&clk IMX8MP_CLK_HSIO_ROOT>, + <&clk IMX8MP_CLK_USB_ROOT>; + clock-names = "hsio", "suspend"; + interrupts = <GIC_SPI 148 IRQ_TYPE_LEVEL_HIGH>; + #address-cells = <1>; + #size-cells = <1>; + dma-ranges = <0x40000000 0x40000000 0xc0000000>; + ranges; + + dwc3@38100000 { + compatible = "snps,dwc3"; + reg = <0x38100000 0x10000>; + clocks = <&clk IMX8MP_CLK_HSIO_AXI>, + <&clk IMX8MP_CLK_USB_CORE_REF>, + <&clk IMX8MP_CLK_USB_ROOT>; + clock-names = "bus_early", "ref", "suspend"; + assigned-clocks = <&clk IMX8MP_CLK_HSIO_AXI>; + assigned-clock-parents = <&clk IMX8MP_SYS_PLL2_500M>; + assigned-clock-rates = <500000000>; + interrupts = <GIC_SPI 40 IRQ_TYPE_LEVEL_HIGH>; + phys = <&usb3_phy0>, <&usb3_phy0>; + phy-names = "usb2-phy", "usb3-phy"; + snps,dis-u2-freeclk-exists-quirk; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/generic-ehci.yaml b/Documentation/devicetree/bindings/usb/generic-ehci.yaml index 247ef00381ea..6816de7dfc00 100644 --- a/Documentation/devicetree/bindings/usb/generic-ehci.yaml +++ b/Documentation/devicetree/bindings/usb/generic-ehci.yaml @@ -24,8 +24,53 @@ allOf: properties: compatible: - contains: - const: generic-ehci + oneOf: + - items: + - enum: + - allwinner,sun4i-a10-ehci + - allwinner,sun50i-a64-ehci + - allwinner,sun50i-h6-ehci + - allwinner,sun5i-a13-ehci + - allwinner,sun6i-a31-ehci + - allwinner,sun7i-a20-ehci + - allwinner,sun8i-a23-ehci + - allwinner,sun8i-h3-ehci + - allwinner,sun8i-r40-ehci + - allwinner,sun9i-a80-ehci + - aspeed,ast2400-ehci + - aspeed,ast2500-ehci + - aspeed,ast2600-ehci + - brcm,bcm3384-ehci + - brcm,bcm63268-ehci + - brcm,bcm6328-ehci + - brcm,bcm6358-ehci + - brcm,bcm6362-ehci + - brcm,bcm6368-ehci + - brcm,bcm7125-ehci + - brcm,bcm7346-ehci + - brcm,bcm7358-ehci + - brcm,bcm7360-ehci + - brcm,bcm7362-ehci + - brcm,bcm7420-ehci + - brcm,bcm7425-ehci + - brcm,bcm7435-ehci + - ibm,476gtr-ehci + - nxp,lpc1850-ehci + - qca,ar7100-ehci + - snps,hsdk-v1.0-ehci + - socionext,uniphier-ehci + - const: generic-ehci + - items: + - enum: + - cavium,octeon-6335-ehci + - ibm,usb-ehci-440epx + - ibm,usb-ehci-460ex + - nintendo,hollywood-usb-ehci + - st,spear600-ehci + - const: usb-ehci + - enum: + - generic-ehci + - usb-ehci reg: minItems: 1 @@ -101,7 +146,7 @@ additionalProperties: false examples: - | usb@e0000300 { - compatible = "ibm,usb-ehci-440epx", "generic-ehci"; + compatible = "ibm,usb-ehci-440epx", "usb-ehci"; interrupt-parent = <&UIC0>; interrupts = <0x1a 4>; reg = <0xe0000300 90>, <0xe0000390 70>; diff --git a/Documentation/devicetree/bindings/usb/generic-ohci.yaml b/Documentation/devicetree/bindings/usb/generic-ohci.yaml index 2178bcc401bc..53df281f618c 100644 --- a/Documentation/devicetree/bindings/usb/generic-ohci.yaml +++ b/Documentation/devicetree/bindings/usb/generic-ohci.yaml @@ -14,8 +14,38 @@ maintainers: properties: compatible: - contains: - const: generic-ohci + oneOf: + - items: + - enum: + - allwinner,sun4i-a10-ohci + - allwinner,sun50i-a64-ohci + - allwinner,sun50i-h6-ohci + - allwinner,sun5i-a13-ohci + - allwinner,sun6i-a31-ohci + - allwinner,sun7i-a20-ohci + - allwinner,sun8i-a23-ohci + - allwinner,sun8i-h3-ohci + - allwinner,sun8i-r40-ohci + - allwinner,sun9i-a80-ohci + - brcm,bcm3384-ohci + - brcm,bcm63268-ohci + - brcm,bcm6328-ohci + - brcm,bcm6358-ohci + - brcm,bcm6362-ohci + - brcm,bcm6368-ohci + - brcm,bcm7125-ohci + - brcm,bcm7346-ohci + - brcm,bcm7358-ohci + - brcm,bcm7360-ohci + - brcm,bcm7362-ohci + - brcm,bcm7420-ohci + - brcm,bcm7425-ohci + - brcm,bcm7435-ohci + - ibm,476gtr-ohci + - ingenic,jz4740-ohci + - snps,hsdk-v1.0-ohci + - const: generic-ohci + - const: generic-ohci reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/usb/generic-xhci.yaml b/Documentation/devicetree/bindings/usb/generic-xhci.yaml new file mode 100644 index 000000000000..23d73df96ea3 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/generic-xhci.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/generic-xhci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: USB xHCI Controller Device Tree Bindings + +maintainers: + - Mathias Nyman <mathias.nyman@intel.com> + +allOf: + - $ref: "usb-xhci.yaml#" + +properties: + compatible: + oneOf: + - description: Generic xHCI device + const: generic-xhci + - description: Armada 37xx/375/38x/8k SoCs + items: + - enum: + - marvell,armada3700-xhci + - marvell,armada-375-xhci + - marvell,armada-380-xhci + - marvell,armada-8k-xhci + - const: generic-xhci + - description: Broadcom STB SoCs with xHCI + enum: + - brcm,xhci-brcm-v2 + - brcm,bcm7445-xhci + - description: Generic xHCI device + const: xhci-platform + deprecated: true + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 2 + + clock-names: + minItems: 1 + items: + - const: core + - const: reg + +unevaluatedProperties: false + +required: + - compatible + - reg + - interrupts + +examples: + - | + usb@f0931000 { + compatible = "generic-xhci"; + reg = <0xf0931000 0x8c8>; + interrupts = <0x0 0x4e 0x0>; + }; diff --git a/Documentation/devicetree/bindings/usb/generic.txt b/Documentation/devicetree/bindings/usb/generic.txt deleted file mode 100644 index ba472e7aefc9..000000000000 --- a/Documentation/devicetree/bindings/usb/generic.txt +++ /dev/null @@ -1,57 +0,0 @@ -Generic USB Properties - -Optional properties: - - maximum-speed: tells USB controllers we want to work up to a certain - speed. Valid arguments are "super-speed-plus", - "super-speed", "high-speed", "full-speed" and - "low-speed". In case this isn't passed via DT, USB - controllers should default to their maximum HW - capability. - - dr_mode: tells Dual-Role USB controllers that we want to work on a - particular mode. Valid arguments are "host", - "peripheral" and "otg". In case this attribute isn't - passed via DT, USB DRD controllers should default to - OTG. - - phy_type: tells USB controllers that we want to configure the core to support - a UTMI+ PHY with an 8- or 16-bit interface if UTMI+ is - selected. Valid arguments are "utmi" and "utmi_wide". - In case this isn't passed via DT, USB controllers should - default to HW capability. - - otg-rev: tells usb driver the release number of the OTG and EH supplement - with which the device and its descriptors are compliant, - in binary-coded decimal (i.e. 2.0 is 0200H). This - property is used if any real OTG features(HNP/SRP/ADP) - is enabled, if ADP is required, otg-rev should be - 0x0200 or above. - - companion: phandle of a companion - - hnp-disable: tells OTG controllers we want to disable OTG HNP, normally HNP - is the basic function of real OTG except you want it - to be a srp-capable only B device. - - srp-disable: tells OTG controllers we want to disable OTG SRP, SRP is - optional for OTG device. - - adp-disable: tells OTG controllers we want to disable OTG ADP, ADP is - optional for OTG device. - - usb-role-switch: boolean, indicates that the device is capable of assigning - the USB data role (USB host or USB device) for a given - USB connector, such as Type-C, Type-B(micro). - see connector/usb-connector.yaml. - - role-switch-default-mode: indicating if usb-role-switch is enabled, the - device default operation mode of controller while usb - role is USB_ROLE_NONE. Valid arguments are "host" and - "peripheral". Defaults to "peripheral" if not - specified. - - -This is an attribute to a USB controller such as: - -dwc3@4a030000 { - compatible = "synopsys,dwc3"; - reg = <0x4a030000 0xcfff>; - interrupts = <0 92 4> - usb-phy = <&usb2_phy>, <&usb3,phy>; - maximum-speed = "super-speed"; - dr_mode = "otg"; - phy_type = "utmi_wide"; - otg-rev = <0x0200>; - adp-disable; -}; diff --git a/Documentation/devicetree/bindings/usb/intel,keembay-dwc3.yaml b/Documentation/devicetree/bindings/usb/intel,keembay-dwc3.yaml index dd32c10ce6c7..43b91ab62004 100644 --- a/Documentation/devicetree/bindings/usb/intel,keembay-dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/intel,keembay-dwc3.yaml @@ -34,11 +34,8 @@ properties: # Required child node: patternProperties: - "^dwc3@[0-9a-f]+$": - type: object - description: - A child node must exist to represent the core DWC3 IP block. - The content of the node is defined in dwc3.txt. + "^usb@[0-9a-f]+$": + $ref: snps,dwc3.yaml# required: - compatible @@ -68,7 +65,7 @@ examples: #address-cells = <1>; #size-cells = <1>; - dwc3@34000000 { + usb@34000000 { compatible = "snps,dwc3"; reg = <0x34000000 0x10000>; interrupts = <GIC_SPI 91 IRQ_TYPE_LEVEL_HIGH>; diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt deleted file mode 100644 index 42d8814f903a..000000000000 --- a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt +++ /dev/null @@ -1,121 +0,0 @@ -MT8173 xHCI - -The device node for Mediatek SOC USB3.0 host controller - -There are two scenarios: the first one only supports xHCI driver; -the second one supports dual-role mode, and the host is based on xHCI -driver. Take account of backward compatibility, we divide bindings -into two parts. - -1st: only supports xHCI driver ------------------------------------------------------------------------- - -Required properties: - - compatible : should be "mediatek,<soc-model>-xhci", "mediatek,mtk-xhci", - soc-model is the name of SoC, such as mt8173, mt2712 etc, when using - "mediatek,mtk-xhci" compatible string, you need SoC specific ones in - addition, one of: - - "mediatek,mt8173-xhci" - - reg : specifies physical base address and size of the registers - - reg-names: should be "mac" for xHCI MAC and "ippc" for IP port control - - interrupts : interrupt used by the controller - - power-domains : a phandle to USB power domain node to control USB's - mtcmos - - vusb33-supply : regulator of USB avdd3.3v - - - clocks : a list of phandle + clock-specifier pairs, one for each - entry in clock-names - - clock-names : must contain - "sys_ck": controller clock used by normal mode, - the following ones are optional: - "ref_ck": reference clock used by low power mode etc, - "mcu_ck": mcu_bus clock for register access, - "dma_ck": dma_bus clock for data transfer by DMA, - "xhci_ck": controller clock - - - phys : see usb-hcd.yaml in the current directory - -Optional properties: - - wakeup-source : enable USB remote wakeup; - - mediatek,syscon-wakeup : phandle to syscon used to access the register - of the USB wakeup glue layer between xHCI and SPM; it depends on - "wakeup-source", and has two arguments: - - the first one : register base address of the glue layer in syscon; - - the second one : hardware version of the glue layer - - 1 : used by mt8173 etc - - 2 : used by mt2712 etc - - mediatek,u3p-dis-msk : mask to disable u3ports, bit0 for u3port0, - bit1 for u3port1, ... etc; - - vbus-supply : reference to the VBUS regulator; - - usb3-lpm-capable : supports USB3.0 LPM - - pinctrl-names : a pinctrl state named "default" must be defined - - pinctrl-0 : pin control group - See: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt - - imod-interval-ns: default interrupt moderation interval is 5000ns - -additionally the properties from usb-hcd.yaml (in the current directory) are -supported. - -Example: -usb30: usb@11270000 { - compatible = "mediatek,mt8173-xhci"; - reg = <0 0x11270000 0 0x1000>, - <0 0x11280700 0 0x0100>; - reg-names = "mac", "ippc"; - interrupts = <GIC_SPI 115 IRQ_TYPE_LEVEL_LOW>; - power-domains = <&scpsys MT8173_POWER_DOMAIN_USB>; - clocks = <&topckgen CLK_TOP_USB30_SEL>, <&clk26m>, - <&pericfg CLK_PERI_USB0>, - <&pericfg CLK_PERI_USB1>; - clock-names = "sys_ck", "ref_ck"; - phys = <&phy_port0 PHY_TYPE_USB3>, - <&phy_port1 PHY_TYPE_USB2>; - vusb33-supply = <&mt6397_vusb_reg>; - vbus-supply = <&usb_p1_vbus>; - usb3-lpm-capable; - mediatek,syscon-wakeup = <&pericfg 0x400 1>; - wakeup-source; - imod-interval-ns = <10000>; -}; - -2nd: dual-role mode with xHCI driver ------------------------------------------------------------------------- - -In the case, xhci is added as subnode to mtu3. An example and the DT binding -details of mtu3 can be found in: -Documentation/devicetree/bindings/usb/mediatek,mtu3.txt - -Required properties: - - compatible : should be "mediatek,<soc-model>-xhci", "mediatek,mtk-xhci", - soc-model is the name of SoC, such as mt8173, mt2712 etc, when using - "mediatek,mtk-xhci" compatible string, you need SoC specific ones in - addition, one of: - - "mediatek,mt8173-xhci" - - reg : specifies physical base address and size of the registers - - reg-names: should be "mac" for xHCI MAC - - interrupts : interrupt used by the host controller - - power-domains : a phandle to USB power domain node to control USB's - mtcmos - - vusb33-supply : regulator of USB avdd3.3v - - - clocks : a list of phandle + clock-specifier pairs, one for each - entry in clock-names - - clock-names : must contain "sys_ck", and the following ones are optional: - "ref_ck", "mcu_ck" and "dma_ck", "xhci_ck" - -Optional properties: - - vbus-supply : reference to the VBUS regulator; - - usb3-lpm-capable : supports USB3.0 LPM - -Example: -usb30: usb@11270000 { - compatible = "mediatek,mt8173-xhci"; - reg = <0 0x11270000 0 0x1000>; - reg-names = "mac"; - interrupts = <GIC_SPI 115 IRQ_TYPE_LEVEL_LOW>; - power-domains = <&scpsys MT8173_POWER_DOMAIN_USB>; - clocks = <&topckgen CLK_TOP_USB30_SEL>, <&clk26m>; - clock-names = "sys_ck", "ref_ck"; - vusb33-supply = <&mt6397_vusb_reg>; - usb3-lpm-capable; -}; diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml new file mode 100644 index 000000000000..14f40efb3b22 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml @@ -0,0 +1,188 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (c) 2020 MediaTek +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/mediatek,mtk-xhci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek USB3 xHCI Device Tree Bindings + +maintainers: + - Chunfeng Yun <chunfeng.yun@mediatek.com> + +allOf: + - $ref: "usb-xhci.yaml" + +description: | + There are two scenarios: + case 1: only supports xHCI driver; + case 2: supports dual-role mode, and the host is based on xHCI driver. + +properties: + # common properties for both case 1 and case 2 + compatible: + items: + - enum: + - mediatek,mt2701-xhci + - mediatek,mt2712-xhci + - mediatek,mt7622-xhci + - mediatek,mt7623-xhci + - mediatek,mt7629-xhci + - mediatek,mt8173-xhci + - mediatek,mt8183-xhci + - const: mediatek,mtk-xhci + + reg: + minItems: 1 + items: + - description: the registers of xHCI MAC + - description: the registers of IP Port Control + + reg-names: + minItems: 1 + items: + - const: mac + - const: ippc # optional, only needed for case 1. + + interrupts: + maxItems: 1 + + power-domains: + description: A phandle to USB power domain node to control USB's MTCMOS + maxItems: 1 + + clocks: + minItems: 1 + items: + - description: Controller clock used by normal mode + - description: Reference clock used by low power mode etc + - description: Mcu bus clock for register access + - description: DMA bus clock for data transfer + - description: controller clock + + clock-names: + minItems: 1 + items: + - const: sys_ck # required, the following ones are optional + - const: ref_ck + - const: mcu_ck + - const: dma_ck + - const: xhci_ck + + assigned-clocks: + minItems: 1 + maxItems: 5 + + assigned-clock-parents: + minItems: 1 + maxItems: 5 + + phys: + description: + List of all PHYs used on this HCD, it's better to keep PHYs in order + as the hardware layout + minItems: 1 + items: + - description: USB2/HS PHY # required, others are optional + - description: USB3/SS(P) PHY + - description: USB2/HS PHY + - description: USB3/SS(P) PHY + - description: USB2/HS PHY + - description: USB3/SS(P) PHY + - description: USB2/HS PHY + - description: USB3/SS(P) PHY + - description: USB2/HS PHY + + vusb33-supply: + description: Regulator of USB AVDD3.3v + + vbus-supply: + description: Regulator of USB VBUS5v + + usb3-lpm-capable: + description: supports USB3.0 LPM + type: boolean + + imod-interval-ns: + description: + Interrupt moderation interval value, it is 8 times as much as that + defined in the xHCI spec on MTK's controller. + default: 5000 + + # the following properties are only used for case 1 + wakeup-source: + description: enable USB remote wakeup, see power/wakeup-source.txt + type: boolean + + mediatek,syscon-wakeup: + $ref: /schemas/types.yaml#/definitions/phandle-array + maxItems: 1 + description: + A phandle to syscon used to access the register of the USB wakeup glue + layer between xHCI and SPM, the field should always be 3 cells long. + items: + items: + - description: + The first cell represents a phandle to syscon + - description: + The second cell represents the register base address of the glue + layer in syscon + - description: + The third cell represents the hardware version of the glue layer, + 1 is used by mt8173 etc, 2 is used by mt2712 etc + enum: [1, 2] + + mediatek,u3p-dis-msk: + $ref: /schemas/types.yaml#/definitions/uint32 + description: The mask to disable u3ports, bit0 for u3port0, + bit1 for u3port1, ... etc + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + +patternProperties: + "@[0-9a-f]{1}$": + type: object + description: The hard wired USB devices. + +dependencies: + wakeup-source: [ 'mediatek,syscon-wakeup' ] + +required: + - compatible + - reg + - reg-names + - interrupts + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/mt8173-clk.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/phy/phy.h> + #include <dt-bindings/power/mt8173-power.h> + + usb@11270000 { + compatible = "mediatek,mt8173-xhci", "mediatek,mtk-xhci"; + reg = <0x11270000 0x1000>, <0x11280700 0x0100>; + reg-names = "mac", "ippc"; + interrupts = <GIC_SPI 115 IRQ_TYPE_LEVEL_LOW>; + power-domains = <&scpsys MT8173_POWER_DOMAIN_USB>; + clocks = <&topckgen CLK_TOP_USB30_SEL>, <&clk26m>; + clock-names = "sys_ck", "ref_ck"; + phys = <&u3port0 PHY_TYPE_USB3>, <&u2port1 PHY_TYPE_USB2>; + vusb33-supply = <&mt6397_vusb_reg>; + vbus-supply = <&usb_p1_vbus>; + imod-interval-ns = <10000>; + mediatek,syscon-wakeup = <&pericfg 0x400 1>; + wakeup-source; + usb3-lpm-capable; + }; +... diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt b/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt deleted file mode 100644 index a82ca438aec1..000000000000 --- a/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt +++ /dev/null @@ -1,108 +0,0 @@ -The device node for Mediatek USB3.0 DRD controller - -Required properties: - - compatible : should be "mediatek,<soc-model>-mtu3", "mediatek,mtu3", - soc-model is the name of SoC, such as mt8173, mt2712 etc, - when using "mediatek,mtu3" compatible string, you need SoC specific - ones in addition, one of: - - "mediatek,mt8173-mtu3" - - reg : specifies physical base address and size of the registers - - reg-names: should be "mac" for device IP and "ippc" for IP port control - - interrupts : interrupt used by the device IP - - power-domains : a phandle to USB power domain node to control USB's - mtcmos - - vusb33-supply : regulator of USB avdd3.3v - - clocks : a list of phandle + clock-specifier pairs, one for each - entry in clock-names - - clock-names : must contain "sys_ck" for clock of controller, - the following clocks are optional: - "ref_ck", "mcu_ck" and "dma_ck"; - - phys : see usb-hcd.yaml in the current directory - - dr_mode : should be one of "host", "peripheral" or "otg", - refer to usb/generic.txt - -Optional properties: - - #address-cells, #size-cells : should be '2' if the device has sub-nodes - with 'reg' property - - ranges : allows valid 1:1 translation between child's address space and - parent's address space - - extcon : external connector for vbus and idpin changes detection, needed - when supports dual-role mode. - it's considered valid for compatibility reasons, not allowed for - new bindings, and use "usb-role-switch" property instead. - - vbus-supply : reference to the VBUS regulator, needed when supports - dual-role mode. - it's considered valid for compatibility reasons, not allowed for - new bindings, and put into a usb-connector node. - see connector/usb-connector.yaml. - - pinctrl-names : a pinctrl state named "default" is optional, and need be - defined if auto drd switch is enabled, that means the property dr_mode - is set as "otg", and meanwhile the property "mediatek,enable-manual-drd" - is not set. - - pinctrl-0 : pin control group - See: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt - - - maximum-speed : valid arguments are "super-speed", "high-speed" and - "full-speed"; refer to usb/generic.txt - - usb-role-switch : use USB Role Switch to support dual-role switch, but - not extcon; see usb/generic.txt. - - enable-manual-drd : supports manual dual-role switch via debugfs; usually - used when receptacle is TYPE-A and also wants to support dual-role - mode. - - wakeup-source: enable USB remote wakeup of host mode. - - mediatek,syscon-wakeup : phandle to syscon used to access the register - of the USB wakeup glue layer between SSUSB and SPM; it depends on - "wakeup-source", and has two arguments: - - the first one : register base address of the glue layer in syscon; - - the second one : hardware version of the glue layer - - 1 : used by mt8173 etc - - 2 : used by mt2712 etc - - mediatek,u3p-dis-msk : mask to disable u3ports, bit0 for u3port0, - bit1 for u3port1, ... etc; - -additionally the properties from usb-hcd.yaml (in the current directory) are -supported. - -Sub-nodes: -The xhci should be added as subnode to mtu3 as shown in the following example -if host mode is enabled. The DT binding details of xhci can be found in: -Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt - -The port would be added as subnode if use "usb-role-switch" property. - see graph.txt - -Example: -ssusb: usb@11271000 { - compatible = "mediatek,mt8173-mtu3"; - reg = <0 0x11271000 0 0x3000>, - <0 0x11280700 0 0x0100>; - reg-names = "mac", "ippc"; - interrupts = <GIC_SPI 64 IRQ_TYPE_LEVEL_LOW>; - phys = <&phy_port0 PHY_TYPE_USB3>, - <&phy_port1 PHY_TYPE_USB2>; - power-domains = <&scpsys MT8173_POWER_DOMAIN_USB>; - clocks = <&topckgen CLK_TOP_USB30_SEL>, <&clk26m>, - <&pericfg CLK_PERI_USB0>, - <&pericfg CLK_PERI_USB1>; - clock-names = "sys_ck", "ref_ck"; - vusb33-supply = <&mt6397_vusb_reg>; - vbus-supply = <&usb_p0_vbus>; - extcon = <&extcon_usb>; - dr_mode = "otg"; - wakeup-source; - mediatek,syscon-wakeup = <&pericfg 0x400 1>; - #address-cells = <2>; - #size-cells = <2>; - ranges; - - usb_host: xhci@11270000 { - compatible = "mediatek,mt8173-xhci"; - reg = <0 0x11270000 0 0x1000>; - reg-names = "mac"; - interrupts = <GIC_SPI 115 IRQ_TYPE_LEVEL_LOW>; - power-domains = <&scpsys MT8173_POWER_DOMAIN_USB>; - clocks = <&topckgen CLK_TOP_USB30_SEL>, <&clk26m>; - clock-names = "sys_ck", "ref_ck"; - vusb33-supply = <&mt6397_vusb_reg>; - }; -}; diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml new file mode 100644 index 000000000000..f5c04b9d2de9 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml @@ -0,0 +1,287 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (c) 2020 MediaTek +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/mediatek,mtu3.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek USB3 DRD Controller Device Tree Bindings + +maintainers: + - Chunfeng Yun <chunfeng.yun@mediatek.com> + +allOf: + - $ref: "usb-drd.yaml" + +description: | + The DRD controller has a glue layer IPPC (IP Port Control), and its host is + based on xHCI. + +properties: + compatible: + items: + - enum: + - mediatek,mt2712-mtu3 + - mediatek,mt8173-mtu3 + - mediatek,mt8183-mtu3 + - const: mediatek,mtu3 + + reg: + items: + - description: the registers of device MAC + - description: the registers of IP Port Control + + reg-names: + items: + - const: mac + - const: ippc + + interrupts: + maxItems: 1 + + power-domains: + description: A phandle to USB power domain node to control USB's MTCMOS + maxItems: 1 + + clocks: + minItems: 1 + items: + - description: Controller clock used by normal mode + - description: Reference clock used by low power mode etc + - description: Mcu bus clock for register access + - description: DMA bus clock for data transfer + + clock-names: + minItems: 1 + items: + - const: sys_ck # required, others are optional + - const: ref_ck + - const: mcu_ck + - const: dma_ck + + phys: + description: + List of all the USB PHYs used, it's better to keep the sequence + as the hardware layout. + minItems: 1 + items: + - description: USB2/HS PHY # required, others are optional + - description: USB3/SS(P) PHY + - description: USB2/HS PHY # the following for backward compatible + - description: USB3/SS(P) PHY + - description: USB2/HS PHY + - description: USB3/SS(P) PHY + - description: USB2/HS PHY + - description: USB3/SS(P) PHY + - description: USB2/HS PHY + + vusb33-supply: + description: Regulator of USB AVDD3.3v + + vbus-supply: + deprecated: true + description: | + Regulator of USB VBUS5v, needed when supports dual-role mode. + Particularly, if use an output GPIO to control a VBUS regulator, should + model it as a regulator. See bindings/regulator/fixed-regulator.yaml + It's considered valid for compatibility reasons, not allowed for + new bindings, and put into a usb-connector node. + + dr_mode: + enum: [host, peripheral, otg] + default: otg + + maximum-speed: + enum: [super-speed-plus, super-speed, high-speed, full-speed] + + "#address-cells": + enum: [1, 2] + + "#size-cells": + enum: [1, 2] + + ranges: true + + extcon: + deprecated: true + description: | + Phandle to the extcon device detecting the IDDIG/VBUS state, neede + when supports dual-role mode. + It's considered valid for compatibility reasons, not allowed for + new bindings, and use "usb-role-switch" property instead. + + usb-role-switch: + $ref: /schemas/types.yaml#/definitions/flag + description: Support role switch. + type: boolean + + connector: + $ref: /connector/usb-connector.yaml# + description: + Connector for dual role switch, especially for "gpio-usb-b-connector" + type: object + + port: + description: + Any connector to the data bus of this controller should be modelled + using the OF graph bindings specified, if the "usb-role-switch" + property is used. See graph.txt + type: object + + enable-manual-drd: + $ref: /schemas/types.yaml#/definitions/flag + description: + supports manual dual-role switch via debugfs; usually used when + receptacle is TYPE-A and also wants to support dual-role mode. + type: boolean + + wakeup-source: + description: enable USB remote wakeup, see power/wakeup-source.txt + type: boolean + + mediatek,syscon-wakeup: + $ref: /schemas/types.yaml#/definitions/phandle-array + maxItems: 1 + description: + A phandle to syscon used to access the register of the USB wakeup glue + layer between xHCI and SPM, the field should always be 3 cells long. + items: + items: + - description: + The first cell represents a phandle to syscon + - description: + The second cell represents the register base address of the glue + layer in syscon + - description: + The third cell represents the hardware version of the glue layer, + 1 is used by mt8173 etc, 2 is used by mt2712 etc + enum: [1, 2] + + mediatek,u3p-dis-msk: + $ref: /schemas/types.yaml#/definitions/uint32 + description: The mask to disable u3ports, bit0 for u3port0, + bit1 for u3port1, ... etc + +# Required child node when support dual-role +patternProperties: + "^usb@[0-9a-f]+$": + type: object + $ref: /usb/mediatek,mtk-xhci.yaml# + description: + The xhci should be added as subnode to mtu3 as shown in the following + example if the host mode is enabled. + +dependencies: + connector: [ 'usb-role-switch' ] + port: [ 'usb-role-switch' ] + wakeup-source: [ 'mediatek,syscon-wakeup' ] + +required: + - compatible + - reg + - reg-names + - interrupts + - clocks + - clock-names + +additionalProperties: false + +examples: + # Dual role switch by extcon + - | + #include <dt-bindings/clock/mt8173-clk.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/phy/phy.h> + #include <dt-bindings/power/mt8173-power.h> + + usb@11271000 { + compatible = "mediatek,mt8173-mtu3", "mediatek,mtu3"; + reg = <0x11271000 0x3000>, <0x11280700 0x0100>; + reg-names = "mac", "ippc"; + interrupts = <GIC_SPI 64 IRQ_TYPE_LEVEL_LOW>; + phys = <&phy_port0 PHY_TYPE_USB3>, <&phy_port1 PHY_TYPE_USB2>; + power-domains = <&scpsys MT8173_POWER_DOMAIN_USB>; + clocks = <&topckgen CLK_TOP_USB30_SEL>; + clock-names = "sys_ck"; + vusb33-supply = <&mt6397_vusb_reg>; + vbus-supply = <&usb_p0_vbus>; + extcon = <&extcon_usb>; + dr_mode = "otg"; + wakeup-source; + mediatek,syscon-wakeup = <&pericfg 0x400 1>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + xhci: usb@11270000 { + compatible = "mediatek,mt8173-xhci", "mediatek,mtk-xhci"; + reg = <0x11270000 0x1000>; + reg-names = "mac"; + interrupts = <GIC_SPI 115 IRQ_TYPE_LEVEL_LOW>; + power-domains = <&scpsys MT8173_POWER_DOMAIN_USB>; + clocks = <&topckgen CLK_TOP_USB30_SEL>, <&clk26m>; + clock-names = "sys_ck", "ref_ck"; + vusb33-supply = <&mt6397_vusb_reg>; + }; + }; + + # Enable/disable device by an input gpio for VBUS pin + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/power/mt2712-power.h> + + usb@112c1000 { + compatible = "mediatek,mt2712-mtu3", "mediatek,mtu3"; + reg = <0x112c1000 0x3000>, <0x112d0700 0x0100>; + reg-names = "mac", "ippc"; + interrupts = <GIC_SPI 248 IRQ_TYPE_LEVEL_LOW>; + phys = <&u2port2 PHY_TYPE_USB2>; + power-domains = <&scpsys MT2712_POWER_DOMAIN_USB2>; + clocks = <&topckgen CLK_TOP_USB30_SEL>; + clock-names = "sys_ck"; + dr_mode = "peripheral"; + usb-role-switch; + + connector { + compatible = "gpio-usb-b-connector", "usb-b-connector"; + type = "micro"; + vbus-gpios = <&pio 13 GPIO_ACTIVE_HIGH>; + }; + }; + + # Dual role switch with type-c + - | + usb@11201000 { + compatible ="mediatek,mt8183-mtu3", "mediatek,mtu3"; + reg = <0x11201000 0x2e00>, <0x11203e00 0x0100>; + reg-names = "mac", "ippc"; + interrupts = <GIC_SPI 72 IRQ_TYPE_LEVEL_LOW>; + phys = <&u2port0 PHY_TYPE_USB2>; + clocks = <&clk26m>; + clock-names = "sys_ck"; + mediatek,syscon-wakeup = <&pericfg 0x400 1>; + wakeup-source; + dr_mode = "otg"; + usb-role-switch; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + host: usb@11200000 { + compatible = "mediatek,mt8183-xhci", "mediatek,mtk-xhci"; + reg = <0x11200000 0x1000>; + reg-names = "mac"; + interrupts = <GIC_SPI 73 IRQ_TYPE_LEVEL_LOW>; + clocks = <&clk26m>; + clock-names = "sys_ck"; + }; + + port { + usb_role_sw: endpoint { + remote-endpoint = <&hs_ep>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/usb/mediatek,musb.txt b/Documentation/devicetree/bindings/usb/mediatek,musb.txt deleted file mode 100644 index 5eedb0296562..000000000000 --- a/Documentation/devicetree/bindings/usb/mediatek,musb.txt +++ /dev/null @@ -1,57 +0,0 @@ -MediaTek musb DRD/OTG controller -------------------------------------------- - -Required properties: - - compatible : should be one of: - "mediatek,mt2701-musb" - ... - followed by "mediatek,mtk-musb" - - reg : specifies physical base address and size of - the registers - - interrupts : interrupt used by musb controller - - interrupt-names : must be "mc" - - phys : PHY specifier for the OTG phy - - dr_mode : should be one of "host", "peripheral" or "otg", - refer to usb/generic.txt - - clocks : a list of phandle + clock-specifier pairs, one for - each entry in clock-names - - clock-names : must contain "main", "mcu", "univpll" - for clocks of controller - -Optional properties: - - power-domains : a phandle to USB power domain node to control USB's - MTCMOS - -Required child nodes: - usb connector node as defined in bindings/connector/usb-connector.yaml -Optional properties: - - id-gpios : input GPIO for USB ID pin. - - vbus-gpios : input GPIO for USB VBUS pin. - - vbus-supply : reference to the VBUS regulator, needed when supports - dual-role mode - - usb-role-switch : use USB Role Switch to support dual-role switch, see - usb/generic.txt. - -Example: - -usb2: usb@11200000 { - compatible = "mediatek,mt2701-musb", - "mediatek,mtk-musb"; - reg = <0 0x11200000 0 0x1000>; - interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_LOW>; - interrupt-names = "mc"; - phys = <&u2port2 PHY_TYPE_USB2>; - dr_mode = "otg"; - clocks = <&pericfg CLK_PERI_USB0>, - <&pericfg CLK_PERI_USB0_MCU>, - <&pericfg CLK_PERI_USB_SLV>; - clock-names = "main","mcu","univpll"; - power-domains = <&scpsys MT2701_POWER_DOMAIN_IFR_MSC>; - usb-role-switch; - connector{ - compatible = "gpio-usb-b-connector", "usb-b-connector"; - type = "micro"; - id-gpios = <&pio 44 GPIO_ACTIVE_HIGH>; - vbus-supply = <&usb_vbus>; - }; -}; diff --git a/Documentation/devicetree/bindings/usb/mediatek,musb.yaml b/Documentation/devicetree/bindings/usb/mediatek,musb.yaml new file mode 100644 index 000000000000..84ddacfdbe9b --- /dev/null +++ b/Documentation/devicetree/bindings/usb/mediatek,musb.yaml @@ -0,0 +1,114 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (c) 2020 MediaTek +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/mediatek,musb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek MUSB DRD/OTG Controller Device Tree Bindings + +maintainers: + - Min Guo <min.guo@mediatek.com> + +properties: + $nodename: + pattern: '^usb@[0-9a-f]+$' + + compatible: + items: + - enum: + - mediatek,mt8516-musb + - mediatek,mt2701-musb + - const: mediatek,mtk-musb + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-names: + items: + - const: mc + + clocks: + items: + - description: The main/core clock + - description: The system bus clock + - description: The 48Mhz clock + + clock-names: + items: + - const: main + - const: mcu + - const: univpll + + phys: + maxItems: 1 + + usb-role-switch: + $ref: /schemas/types.yaml#/definitions/flag + description: Support role switch. See usb/generic.txt + type: boolean + + dr_mode: + enum: + - host + - otg + - peripheral + + power-domains: + description: A phandle to USB power domain node to control USB's MTCMOS + maxItems: 1 + + connector: + $ref: /connector/usb-connector.yaml# + description: Connector for dual role switch + type: object + +dependencies: + usb-role-switch: [ 'connector' ] + connector: [ 'usb-role-switch' ] + +required: + - compatible + - reg + - interrupts + - interrupt-names + - phys + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/mt2701-clk.h> + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/phy/phy.h> + #include <dt-bindings/power/mt2701-power.h> + + usb@11200000 { + compatible = "mediatek,mt2701-musb", "mediatek,mtk-musb"; + reg = <0x11200000 0x1000>; + interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_LOW>; + interrupt-names = "mc"; + phys = <&u2port2 PHY_TYPE_USB2>; + dr_mode = "otg"; + clocks = <&pericfg CLK_PERI_USB0>, + <&pericfg CLK_PERI_USB0_MCU>, + <&pericfg CLK_PERI_USB_SLV>; + clock-names = "main","mcu","univpll"; + power-domains = <&scpsys MT2701_POWER_DOMAIN_IFR_MSC>; + usb-role-switch; + + connector { + compatible = "gpio-usb-b-connector", "usb-b-connector"; + type = "micro"; + id-gpios = <&pio 44 GPIO_ACTIVE_HIGH>; + vbus-supply = <&usb_vbus>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/usb/omap-usb.txt b/Documentation/devicetree/bindings/usb/omap-usb.txt index 38d9bb8507cf..f0dbc5ae45ae 100644 --- a/Documentation/devicetree/bindings/usb/omap-usb.txt +++ b/Documentation/devicetree/bindings/usb/omap-usb.txt @@ -65,7 +65,7 @@ Sub-nodes: The dwc3 core should be added as subnode to omap dwc3 glue. - dwc3 : The binding details of dwc3 can be found in: - Documentation/devicetree/bindings/usb/dwc3.txt + Documentation/devicetree/bindings/usb/snps,dwc3.yaml omap_dwc3 { compatible = "ti,dwc3"; diff --git a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml index 2cf525d21e05..c3cbd1fa9944 100644 --- a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml @@ -17,6 +17,10 @@ properties: - qcom,msm8998-dwc3 - qcom,sc7180-dwc3 - qcom,sdm845-dwc3 + - qcom,sdx55-dwc3 + - qcom,sm8150-dwc3 + - qcom,sm8250-dwc3 + - qcom,sm8350-dwc3 - const: qcom,dwc3 reg: @@ -103,11 +107,8 @@ properties: # Required child node: patternProperties: - "^dwc3@[0-9a-f]+$": - type: object - description: - A child node must exist to represent the core DWC3 IP block - The content of the node is defined in dwc3.txt. + "^usb@[0-9a-f]+$": + $ref: snps,dwc3.yaml# required: - compatible @@ -162,7 +163,7 @@ examples: resets = <&gcc GCC_USB30_PRIM_BCR>; - dwc3@a600000 { + usb@a600000 { compatible = "snps,dwc3"; reg = <0 0x0a600000 0 0xcd00>; interrupts = <GIC_SPI 133 IRQ_TYPE_LEVEL_HIGH>; diff --git a/Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml b/Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml index 22603256ddf8..4c5efaf02308 100644 --- a/Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml +++ b/Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml @@ -11,7 +11,7 @@ maintainers: - Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com> allOf: - - $ref: "usb-hcd.yaml" + - $ref: "usb-xhci.yaml" properties: compatible: @@ -68,7 +68,7 @@ required: - power-domains - resets -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/usb/rockchip,dwc3.txt b/Documentation/devicetree/bindings/usb/rockchip,dwc3.txt deleted file mode 100644 index 94520493233b..000000000000 --- a/Documentation/devicetree/bindings/usb/rockchip,dwc3.txt +++ /dev/null @@ -1,56 +0,0 @@ -Rockchip SuperSpeed DWC3 USB SoC controller - -Required properties: -- compatible: should contain "rockchip,rk3399-dwc3" for rk3399 SoC -- clocks: A list of phandle + clock-specifier pairs for the - clocks listed in clock-names -- clock-names: Should contain the following: - "ref_clk" Controller reference clk, have to be 24 MHz - "suspend_clk" Controller suspend clk, have to be 24 MHz or 32 KHz - "bus_clk" Master/Core clock, have to be >= 62.5 MHz for SS - operation and >= 30MHz for HS operation - "grf_clk" Controller grf clk - -Required child node: -A child node must exist to represent the core DWC3 IP block. The name of -the node is not important. The content of the node is defined in dwc3.txt. - -Phy documentation is provided in the following places: -Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.yaml - USB2.0 PHY -Documentation/devicetree/bindings/phy/phy-rockchip-typec.txt - Type-C PHY - -Example device nodes: - - usbdrd3_0: usb@fe800000 { - compatible = "rockchip,rk3399-dwc3"; - clocks = <&cru SCLK_USB3OTG0_REF>, <&cru SCLK_USB3OTG0_SUSPEND>, - <&cru ACLK_USB3OTG0>, <&cru ACLK_USB3_GRF>; - clock-names = "ref_clk", "suspend_clk", - "bus_clk", "grf_clk"; - #address-cells = <2>; - #size-cells = <2>; - ranges; - usbdrd_dwc3_0: dwc3@fe800000 { - compatible = "snps,dwc3"; - reg = <0x0 0xfe800000 0x0 0x100000>; - interrupts = <GIC_SPI 105 IRQ_TYPE_LEVEL_HIGH>; - dr_mode = "otg"; - }; - }; - - usbdrd3_1: usb@fe900000 { - compatible = "rockchip,rk3399-dwc3"; - clocks = <&cru SCLK_USB3OTG1_REF>, <&cru SCLK_USB3OTG1_SUSPEND>, - <&cru ACLK_USB3OTG1>, <&cru ACLK_USB3_GRF>; - clock-names = "ref_clk", "suspend_clk", - "bus_clk", "grf_clk"; - #address-cells = <2>; - #size-cells = <2>; - ranges; - usbdrd_dwc3_1: dwc3@fe900000 { - compatible = "snps,dwc3"; - reg = <0x0 0xfe900000 0x0 0x100000>; - interrupts = <GIC_SPI 110 IRQ_TYPE_LEVEL_HIGH>; - dr_mode = "otg"; - }; - }; diff --git a/Documentation/devicetree/bindings/usb/rockchip,dwc3.yaml b/Documentation/devicetree/bindings/usb/rockchip,dwc3.yaml new file mode 100644 index 000000000000..04077f2d7faf --- /dev/null +++ b/Documentation/devicetree/bindings/usb/rockchip,dwc3.yaml @@ -0,0 +1,108 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/rockchip,dwc3.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip SuperSpeed DWC3 USB SoC controller + +maintainers: + - Heiko Stuebner <heiko@sntech.de> + +description: + The common content of the node is defined in snps,dwc3.yaml. + + Phy documentation is provided in the following places. + + USB2.0 PHY + Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.yaml + + Type-C PHY + Documentation/devicetree/bindings/phy/phy-rockchip-typec.txt + +allOf: + - $ref: snps,dwc3.yaml# + +select: + properties: + compatible: + contains: + enum: + - rockchip,rk3328-dwc3 + - rockchip,rk3399-dwc3 + required: + - compatible + +properties: + compatible: + items: + - enum: + - rockchip,rk3328-dwc3 + - rockchip,rk3399-dwc3 + - const: snps,dwc3 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 3 + items: + - description: + Controller reference clock, must to be 24 MHz + - description: + Controller suspend clock, must to be 24 MHz or 32 KHz + - description: + Master/Core clock, must to be >= 62.5 MHz for SS + operation and >= 30MHz for HS operation + - description: + Controller grf clock + + clock-names: + minItems: 3 + items: + - const: ref_clk + - const: suspend_clk + - const: bus_clk + - const: grf_clk + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + reset-names: + const: usb3-otg + +unevaluatedProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +examples: + - | + #include <dt-bindings/clock/rk3399-cru.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + bus { + #address-cells = <2>; + #size-cells = <2>; + + usbdrd3_0: usb@fe800000 { + compatible = "rockchip,rk3399-dwc3", "snps,dwc3"; + reg = <0x0 0xfe800000 0x0 0x100000>; + interrupts = <GIC_SPI 105 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru SCLK_USB3OTG0_REF>, <&cru SCLK_USB3OTG0_SUSPEND>, + <&cru ACLK_USB3OTG0>, <&cru ACLK_USB3_GRF>; + clock-names = "ref_clk", "suspend_clk", + "bus_clk", "grf_clk"; + dr_mode = "otg"; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/snps,dwc3.yaml b/Documentation/devicetree/bindings/usb/snps,dwc3.yaml new file mode 100644 index 000000000000..2247da77eac1 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/snps,dwc3.yaml @@ -0,0 +1,332 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/snps,dwc3.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Synopsys DesignWare USB3 Controller + +maintainers: + - Felipe Balbi <balbi@kernel.org> + +description: + This is usually a subnode to DWC3 glue to which it is connected, but can also + be presented as a standalone DT node with an optional vendor-specific + compatible string. + +allOf: + - $ref: usb-drd.yaml# + - if: + properties: + dr_mode: + const: peripheral + + required: + - dr_mode + then: + $ref: usb.yaml# + else: + $ref: usb-xhci.yaml# + +properties: + compatible: + contains: + oneOf: + - const: snps,dwc3 + - const: synopsys,dwc3 + deprecated: true + + interrupts: + description: + It's either a single common DWC3 interrupt (dwc_usb3) or individual + interrupts for the host, gadget and DRD modes. + minItems: 1 + maxItems: 3 + + interrupt-names: + minItems: 1 + maxItems: 3 + oneOf: + - const: dwc_usb3 + - items: + enum: [host, peripheral, otg] + + clocks: + description: + In general the core supports three types of clocks. bus_early is a + SoC Bus Clock (AHB/AXI/Native). ref generates ITP when the UTMI/ULPI + PHY is suspended. suspend clocks a small part of the USB3 core when + SS PHY in P3. But particular cases may differ from that having less + or more clock sources with another names. + + clock-names: + contains: + anyOf: + - enum: [bus_early, ref, suspend] + - true + + usb-phy: + minItems: 1 + items: + - description: USB2/HS PHY + - description: USB3/SS PHY + + phys: + minItems: 1 + items: + - description: USB2/HS PHY + - description: USB3/SS PHY + + phy-names: + minItems: 1 + items: + - const: usb2-phy + - const: usb3-phy + + resets: + minItems: 1 + + snps,usb2-lpm-disable: + description: Indicate if we don't want to enable USB2 HW LPM + type: boolean + + snps,usb3_lpm_capable: + description: Determines if platform is USB3 LPM capable + type: boolean + + snps,dis-start-transfer-quirk: + description: + When set, disable isoc START TRANSFER command failure SW work-around + for DWC_usb31 version 1.70a-ea06 and prior. + type: boolean + + snps,disable_scramble_quirk: + description: + True when SW should disable data scrambling. Only really useful for FPGA + builds. + type: boolean + + snps,has-lpm-erratum: + description: True when DWC3 was configured with LPM Erratum enabled + type: boolean + + snps,lpm-nyet-threshold: + description: LPM NYET threshold + $ref: /schemas/types.yaml#/definitions/uint8 + + snps,u2exit_lfps_quirk: + description: Set if we want to enable u2exit lfps quirk + type: boolean + + snps,u2ss_inp3_quirk: + description: Set if we enable P3 OK for U2/SS Inactive quirk + type: boolean + + snps,req_p1p2p3_quirk: + description: + When set, the core will always request for P1/P2/P3 transition sequence. + type: boolean + + snps,del_p1p2p3_quirk: + description: + When set core will delay P1/P2/P3 until a certain amount of 8B10B errors + occur. + type: boolean + + snps,del_phy_power_chg_quirk: + description: When set core will delay PHY power change from P0 to P1/P2/P3. + type: boolean + + snps,lfps_filter_quirk: + description: When set core will filter LFPS reception. + type: boolean + + snps,rx_detect_poll_quirk: + description: + when set core will disable a 400us delay to start Polling LFPS after + RX.Detect. + type: boolean + + snps,tx_de_emphasis_quirk: + description: When set core will set Tx de-emphasis value + type: boolean + + snps,tx_de_emphasis: + description: + The value driven to the PHY is controlled by the LTSSM during USB3 + Compliance mode. + $ref: /schemas/types.yaml#/definitions/uint8 + enum: + - 0 # -6dB de-emphasis + - 1 # -3.5dB de-emphasis + - 2 # No de-emphasis + + snps,dis_u3_susphy_quirk: + description: When set core will disable USB3 suspend phy + type: boolean + + snps,dis_u2_susphy_quirk: + description: When set core will disable USB2 suspend phy + type: boolean + + snps,dis_enblslpm_quirk: + description: + When set clears the enblslpm in GUSB2PHYCFG, disabling the suspend signal + to the PHY. + type: boolean + + snps,dis-u1-entry-quirk: + description: Set if link entering into U1 needs to be disabled + type: boolean + + snps,dis-u2-entry-quirk: + description: Set if link entering into U2 needs to be disabled + type: boolean + + snps,dis_rxdet_inp3_quirk: + description: + When set core will disable receiver detection in PHY P3 power state. + type: boolean + + snps,dis-u2-freeclk-exists-quirk: + description: + When set, clear the u2_freeclk_exists in GUSB2PHYCFG, specify that USB2 + PHY doesn't provide a free-running PHY clock. + type: boolean + + snps,dis-del-phy-power-chg-quirk: + description: + When set core will change PHY power from P0 to P1/P2/P3 without delay. + type: boolean + + snps,dis-tx-ipgap-linecheck-quirk: + description: When set, disable u2mac linestate check during HS transmit + type: boolean + + snps,parkmode-disable-ss-quirk: + description: + When set, all SuperSpeed bus instances in park mode are disabled. + type: boolean + + snps,dis_metastability_quirk: + description: + When set, disable metastability workaround. CAUTION! Use only if you are + absolutely sure of it. + type: boolean + + snps,dis-split-quirk: + description: + When set, change the way URBs are handled by the driver. Needed to + avoid -EPROTO errors with usbhid on some devices (Hikey 970). + type: boolean + + snps,is-utmi-l1-suspend: + description: + True when DWC3 asserts output signal utmi_l1_suspend_n, false when + asserts utmi_sleep_n. + type: boolean + + snps,hird-threshold: + description: HIRD threshold + $ref: /schemas/types.yaml#/definitions/uint8 + + snps,hsphy_interface: + description: + High-Speed PHY interface selection between UTMI+ and ULPI when the + DWC_USB3_HSPHY_INTERFACE has value 3. + $ref: /schemas/types.yaml#/definitions/uint8 + enum: [utmi, ulpi] + + snps,quirk-frame-length-adjustment: + description: + Value for GFLADJ_30MHZ field of GFLADJ register for post-silicon frame + length adjustment when the fladj_30mhz_sdbnd signal is invalid or + incorrect. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 0x3f + + snps,rx-thr-num-pkt-prd: + description: + Periodic ESS RX packet threshold count (host mode only). Set this and + snps,rx-max-burst-prd to a valid, non-zero value 1-16 (DWC_usb31 + programming guide section 1.2.4) to enable periodic ESS RX threshold. + $ref: /schemas/types.yaml#/definitions/uint8 + minimum: 1 + maximum: 16 + + snps,rx-max-burst-prd: + description: + Max periodic ESS RX burst size (host mode only). Set this and + snps,rx-thr-num-pkt-prd to a valid, non-zero value 1-16 (DWC_usb31 + programming guide section 1.2.4) to enable periodic ESS RX threshold. + $ref: /schemas/types.yaml#/definitions/uint8 + minimum: 1 + maximum: 16 + + snps,tx-thr-num-pkt-prd: + description: + Periodic ESS TX packet threshold count (host mode only). Set this and + snps,tx-max-burst-prd to a valid, non-zero value 1-16 (DWC_usb31 + programming guide section 1.2.3) to enable periodic ESS TX threshold. + $ref: /schemas/types.yaml#/definitions/uint8 + minimum: 1 + maximum: 16 + + snps,tx-max-burst-prd: + description: + Max periodic ESS TX burst size (host mode only). Set this and + snps,tx-thr-num-pkt-prd to a valid, non-zero value 1-16 (DWC_usb31 + programming guide section 1.2.3) to enable periodic ESS TX threshold. + $ref: /schemas/types.yaml#/definitions/uint8 + minimum: 1 + maximum: 16 + + tx-fifo-resize: + description: Determines if the FIFO *has* to be reallocated + deprecated: true + type: boolean + + snps,incr-burst-type-adjustment: + description: + Value for INCR burst type of GSBUSCFG0 register, undefined length INCR + burst type enable and INCRx type. A single value means INCRX burst mode + enabled. If more than one value specified, undefined length INCR burst + type will be enabled with burst lengths utilized up to the maximum + of the values passed in this property. + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 8 + uniqueItems: true + items: + enum: [1, 4, 8, 16, 32, 64, 128, 256] + +unevaluatedProperties: false + +required: + - compatible + - reg + - interrupts + +examples: + - | + usb@4a030000 { + compatible = "snps,dwc3"; + reg = <0x4a030000 0xcfff>; + interrupts = <0 92 4>; + usb-phy = <&usb2_phy>, <&usb3_phy>; + snps,incr-burst-type-adjustment = <1>, <4>, <8>, <16>; + }; + - | + usb@4a000000 { + compatible = "snps,dwc3"; + reg = <0x4a000000 0xcfff>; + interrupts = <0 92 4>; + clocks = <&clk 1>, <&clk 2>, <&clk 3>; + clock-names = "bus_early", "ref", "suspend"; + phys = <&usb2_phy>, <&usb3_phy>; + phy-names = "usb2-phy", "usb3-phy"; + snps,dis_u2_susphy_quirk; + snps,dis_enblslpm_quirk; + }; +... diff --git a/Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml b/Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml index c1b19fc5d0a2..ca7fbe3ed22e 100644 --- a/Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml @@ -64,9 +64,7 @@ properties: patternProperties: "usb@[a-f0-9]+$": - type: object - description: This is the node representing the DWC3 controller instance - Documentation/devicetree/bindings/usb/dwc3.txt + $ref: snps,dwc3.yaml# required: - compatible diff --git a/Documentation/devicetree/bindings/usb/usb-device.txt b/Documentation/devicetree/bindings/usb/usb-device.txt deleted file mode 100644 index 036be172b1ae..000000000000 --- a/Documentation/devicetree/bindings/usb/usb-device.txt +++ /dev/null @@ -1,102 +0,0 @@ -Generic USB Device Properties - -Usually, we only use device tree for hard wired USB device. -The reference binding doc is from: -http://www.devicetree.org/open-firmware/bindings/usb/usb-1_0.ps - -Four types of device-tree nodes are defined: "host-controller nodes" -representing USB host controllers, "device nodes" representing USB devices, -"interface nodes" representing USB interfaces and "combined nodes" -representing simple USB devices. - -A combined node shall be used instead of a device node and an interface node -for devices of class 0 or 9 (hub) with a single configuration and a single -interface. - -A "hub node" is a combined node or an interface node that represents a USB -hub. - - -Required properties for device nodes: -- compatible: "usbVID,PID", where VID is the vendor id and PID the product id. - The textual representation of VID and PID shall be in lower case hexadecimal - with leading zeroes suppressed. The other compatible strings from the above - standard binding could also be used, but a device adhering to this binding - may leave out all except for "usbVID,PID". -- reg: the number of the USB hub port or the USB host-controller port to which - this device is attached. The range is 1-255. - - -Required properties for device nodes with interface nodes: -- #address-cells: shall be 2 -- #size-cells: shall be 0 - - -Required properties for interface nodes: -- compatible: "usbifVID,PID.configCN.IN", where VID is the vendor id, PID is - the product id, CN is the configuration value and IN is the interface - number. The textual representation of VID, PID, CN and IN shall be in lower - case hexadecimal with leading zeroes suppressed. The other compatible - strings from the above standard binding could also be used, but a device - adhering to this binding may leave out all except for - "usbifVID,PID.configCN.IN". -- reg: the interface number and configuration value - -The configuration component is not included in the textual representation of -an interface-node unit address for configuration 1. - - -Required properties for combined nodes: -- compatible: "usbVID,PID", where VID is the vendor id and PID the product id. - The textual representation of VID and PID shall be in lower case hexadecimal - with leading zeroes suppressed. The other compatible strings from the above - standard binding could also be used, but a device adhering to this binding - may leave out all except for "usbVID,PID". -- reg: the number of the USB hub port or the USB host-controller port to which - this device is attached. The range is 1-255. - - -Required properties for hub nodes with device nodes: -- #address-cells: shall be 1 -- #size-cells: shall be 0 - - -Required properties for host-controller nodes with device nodes: -- #address-cells: shall be 1 -- #size-cells: shall be 0 - - -Example: - -&usb1 { /* host controller */ - #address-cells = <1>; - #size-cells = <0>; - - hub@1 { /* hub connected to port 1 */ - compatible = "usb5e3,608"; - reg = <1>; - }; - - device@2 { /* device connected to port 2 */ - compatible = "usb123,4567"; - reg = <2>; - }; - - device@3 { /* device connected to port 3 */ - compatible = "usb123,abcd"; - reg = <3>; - - #address-cells = <2>; - #size-cells = <0>; - - interface@0 { /* interface 0 of configuration 1 */ - compatible = "usbif123,abcd.config1.0"; - reg = <0 1>; - }; - - interface@0,2 { /* interface 0 of configuration 2 */ - compatible = "usbif123,abcd.config2.0"; - reg = <0 2>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/usb/usb-device.yaml b/Documentation/devicetree/bindings/usb/usb-device.yaml new file mode 100644 index 000000000000..d4c99809ee9a --- /dev/null +++ b/Documentation/devicetree/bindings/usb/usb-device.yaml @@ -0,0 +1,124 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/usb-device.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: The device tree bindings for the Generic USB Device + +maintainers: + - Greg Kroah-Hartman <gregkh@linuxfoundation.org> + +description: | + Usually, we only use device tree for hard wired USB device. + The reference binding doc is from: + http://www.devicetree.org/open-firmware/bindings/usb/usb-1_0.ps + + Four types of device-tree nodes are defined: "host-controller nodes" + representing USB host controllers, "device nodes" representing USB devices, + "interface nodes" representing USB interfaces and "combined nodes" + representing simple USB devices. + + A combined node shall be used instead of a device node and an interface node + for devices of class 0 or 9 (hub) with a single configuration and a single + interface. + + A "hub node" is a combined node or an interface node that represents a USB + hub. + +properties: + compatible: + pattern: "^usb[0-9a-f]{1,4},[0-9a-f]{1,4}$" + description: Device nodes or combined nodes. + "usbVID,PID", where VID is the vendor id and PID the product id. + The textual representation of VID and PID shall be in lower case + hexadecimal with leading zeroes suppressed. The other compatible + strings from the above standard binding could also be used, + but a device adhering to this binding may leave out all except + for "usbVID,PID". + + reg: + description: the number of the USB hub port or the USB host-controller + port to which this device is attached. The range is 1-255. + maxItems: 1 + + "#address-cells": + description: should be 1 for hub nodes with device nodes, + should be 2 for device nodes with interface nodes. + enum: [1, 2] + + "#size-cells": + const: 0 + +patternProperties: + "^interface@[0-9a-f]{1,2}(,[0-9a-f]{1,2})$": + type: object + description: USB interface nodes. + The configuration component is not included in the textual + representation of an interface-node unit address for configuration 1. + + properties: + compatible: + pattern: "^usbif[0-9a-f]{1,4},[0-9a-f]{1,4}.config[0-9a-f]{1,2}.[0-9a-f]{1,2}$" + description: Interface nodes. + "usbifVID,PID.configCN.IN", where VID is the vendor id, PID is + the product id, CN is the configuration value and IN is the interface + number. The textual representation of VID, PID, CN and IN shall be + in lower case hexadecimal with leading zeroes suppressed. + The other compatible strings from the above standard binding could + also be used, but a device adhering to this binding may leave out + all except for "usbifVID,PID.configCN.IN". + + reg: + description: should be 2 cells long, the first cell represents + the interface number and the second cell represents the + configuration value. + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: true + +examples: + #hub connected to port 1 + #device connected to port 2 + #device connected to port 3 + # interface 0 of configuration 1 + # interface 0 of configuration 2 + - | + usb@11270000 { + reg = <0x11270000 0x1000>; + interrupts = <0x0 0x4e 0x0>; + #address-cells = <1>; + #size-cells = <0>; + + hub@1 { + compatible = "usb5e3,608"; + reg = <1>; + }; + + device@2 { + compatible = "usb123,4567"; + reg = <2>; + }; + + device@3 { + compatible = "usb123,abcd"; + reg = <3>; + + #address-cells = <2>; + #size-cells = <0>; + + interface@0 { + compatible = "usbif123,abcd.config1.0"; + reg = <0 1>; + }; + + interface@0,2 { + compatible = "usbif123,abcd.config2.0"; + reg = <0 2>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/usb-drd.yaml b/Documentation/devicetree/bindings/usb/usb-drd.yaml new file mode 100644 index 000000000000..f229fc8068d9 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/usb-drd.yaml @@ -0,0 +1,78 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/usb-drd.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic USB OTG Controller Device Tree Bindings + +maintainers: + - Greg Kroah-Hartman <gregkh@linuxfoundation.org> + +properties: + otg-rev: + description: + Tells usb driver the release number of the OTG and EH supplement with + which the device and its descriptors are compliant, in binary-coded + decimal (i.e. 2.0 is 0200H). This property is used if any real OTG + features (HNP/SRP/ADP) is enabled. If ADP is required, otg-rev should be + 0x0200 or above. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0x0100, 0x0120, 0x0130, 0x0200] + + dr_mode: + description: + Tells Dual-Role USB controllers that we want to work on a particular + mode. In case this attribute isn't passed via DT, USB DRD controllers + should default to OTG. + $ref: /schemas/types.yaml#/definitions/string + enum: [host, peripheral, otg] + + hnp-disable: + description: + Tells OTG controllers we want to disable OTG HNP. Normally HNP is the + basic function of real OTG except you want it to be a srp-capable only B + device. + type: boolean + + srp-disable: + description: + Tells OTG controllers we want to disable OTG SRP. SRP is optional for OTG + device. + type: boolean + + adp-disable: + description: + Tells OTG controllers we want to disable OTG ADP. ADP is optional for OTG + device. + type: boolean + + usb-role-switch: + description: + Indicates that the device is capable of assigning the USB data role + (USB host or USB device) for a given USB connector, such as Type-C, + Type-B(micro). See connector/usb-connector.yaml. + + role-switch-default-mode: + description: + Indicates if usb-role-switch is enabled, the device default operation + mode of controller while usb role is USB_ROLE_NONE. + $ref: /schemas/types.yaml#/definitions/string + enum: [host, peripheral] + default: peripheral + +additionalProperties: true + +examples: + - | + usb@4a030000 { + compatible = "snps,dwc3"; + reg = <0x4a030000 0xcfff>; + interrupts = <0 92 4>; + usb-phy = <&usb2_phy>, <&usb3_phy>; + maximum-speed = "super-speed"; + dr_mode = "otg"; + phy_type = "utmi_wide"; + otg-rev = <0x0200>; + adp-disable; + }; diff --git a/Documentation/devicetree/bindings/usb/usb-hcd.yaml b/Documentation/devicetree/bindings/usb/usb-hcd.yaml index b545b087b342..56853c17af66 100644 --- a/Documentation/devicetree/bindings/usb/usb-hcd.yaml +++ b/Documentation/devicetree/bindings/usb/usb-hcd.yaml @@ -9,18 +9,31 @@ title: Generic USB Host Controller Device Tree Bindings maintainers: - Greg Kroah-Hartman <gregkh@linuxfoundation.org> +allOf: + - $ref: usb.yaml# + properties: - $nodename: - pattern: "^usb(@.*)?" + companion: + description: Phandle of a companion device + $ref: /schemas/types.yaml#/definitions/phandle - phys: - $ref: /schemas/types.yaml#/definitions/phandle-array + tpl-support: description: - List of all the USB PHYs on this HCD + Indicates if the Targeted Peripheral List is supported for given + targeted hosts (non-PC hosts). + type: boolean - phy-names: - description: - Name specifier for the USB PHY + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + +patternProperties: + "^.*@[0-9a-f]{1,2}$": + description: The hard wired USB devices + type: object + $ref: /usb/usb-device.yaml additionalProperties: true @@ -29,4 +42,11 @@ examples: usb { phys = <&usb2_phy1>, <&usb3_phy1>; phy-names = "usb"; + #address-cells = <1>; + #size-cells = <0>; + + hub@1 { + compatible = "usb5e3,610"; + reg = <1>; + }; }; diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.txt b/Documentation/devicetree/bindings/usb/usb-xhci.txt deleted file mode 100644 index 0c5cff84a969..000000000000 --- a/Documentation/devicetree/bindings/usb/usb-xhci.txt +++ /dev/null @@ -1,41 +0,0 @@ -USB xHCI controllers - -Required properties: - - compatible: should be one or more of - - - "generic-xhci" for generic XHCI device - - "marvell,armada3700-xhci" for Armada 37xx SoCs - - "marvell,armada-375-xhci" for Armada 375 SoCs - - "marvell,armada-380-xhci" for Armada 38x SoCs - - "brcm,bcm7445-xhci" for Broadcom STB SoCs with XHCI - - "xhci-platform" (deprecated) - - When compatible with the generic version, nodes must list the - SoC-specific version corresponding to the platform first - followed by the generic version. - - - reg: should contain address and length of the standard XHCI - register set for the device. - - interrupts: one XHCI interrupt should be described here. - -Optional properties: - - clocks: reference to the clocks - - clock-names: mandatory if there is a second clock, in this case - the name must be "core" for the first clock and "reg" for the - second one - - usb2-lpm-disable: indicate if we don't want to enable USB2 HW LPM - - usb3-lpm-capable: determines if platform is USB3 LPM capable - - quirk-broken-port-ped: set if the controller has broken port disable mechanism - - imod-interval-ns: default interrupt moderation interval is 5000ns - - phys : see usb-hcd.yaml in the current directory - -additionally the properties from usb-hcd.yaml (in the current directory) are -supported. - - -Example: - usb@f0931000 { - compatible = "generic-xhci"; - reg = <0xf0931000 0x8c8>; - interrupts = <0x0 0x4e 0x0>; - }; diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.yaml b/Documentation/devicetree/bindings/usb/usb-xhci.yaml new file mode 100644 index 000000000000..965f87fef702 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/usb-xhci.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/usb-xhci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic USB xHCI Controller Device Tree Bindings + +maintainers: + - Mathias Nyman <mathias.nyman@intel.com> + +allOf: + - $ref: "usb-hcd.yaml#" + +properties: + usb2-lpm-disable: + description: Indicates if we don't want to enable USB2 HW LPM + type: boolean + + usb3-lpm-capable: + description: Determines if platform is USB3 LPM capable + type: boolean + + quirk-broken-port-ped: + description: Set if the controller has broken port disable mechanism + type: boolean + + imod-interval-ns: + description: Interrupt moderation interval + default: 5000 + +additionalProperties: true + +examples: + - | + usb@f0930000 { + compatible = "generic-xhci"; + reg = <0xf0930000 0x8c8>; + interrupts = <0x0 0x4e 0x0>; + usb2-lpm-disable; + usb3-lpm-capable; + }; diff --git a/Documentation/devicetree/bindings/usb/usb.yaml b/Documentation/devicetree/bindings/usb/usb.yaml new file mode 100644 index 000000000000..78491e66ed24 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/usb.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/usb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic USB Controller Device Tree Bindings + +maintainers: + - Greg Kroah-Hartman <gregkh@linuxfoundation.org> + +select: false + +properties: + $nodename: + pattern: "^usb(@.*)?" + + phys: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + List of all the USB PHYs on this HCD + + phy-names: + description: + Name specifier for the USB PHY + + usb-phy: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + List of all the USB PHYs on this HCD to be accepted by the legacy USB + Physical Layer subsystem. + deprecated: true + + phy_type: + description: + Tells USB controllers that we want to configure the core to support a + UTMI+ PHY with an 8- or 16-bit interface if UTMI+ is selected, UTMI+ low + pin interface if ULPI is specified, Serial core/PHY interconnect if + serial is specified and High-Speed Inter-Chip feature if HSIC is + selected. In case this isn't passed via DT, USB controllers should + default to HW capability. + $ref: /schemas/types.yaml#/definitions/string + enum: [utmi, utmi_wide, ulpi, serial, hsic] + + maximum-speed: + description: + Tells USB controllers we want to work up to a certain speed. In case this + isn't passed via DT, USB controllers should default to their maximum HW + capability. + $ref: /schemas/types.yaml#/definitions/string + enum: + - low-speed + - full-speed + - high-speed + - super-speed + - super-speed-plus + - super-speed-plus-gen2x1 + - super-speed-plus-gen1x2 + - super-speed-plus-gen2x2 + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/usb/usbmisc-imx.txt b/Documentation/devicetree/bindings/usb/usbmisc-imx.txt index b353b9816487..b796836d2ce7 100644 --- a/Documentation/devicetree/bindings/usb/usbmisc-imx.txt +++ b/Documentation/devicetree/bindings/usb/usbmisc-imx.txt @@ -1,7 +1,7 @@ * Freescale i.MX non-core registers Required properties: -- #index-cells: Cells used to descibe usb controller index. Should be <1> +- #index-cells: Cells used to describe usb controller index. Should be <1> - compatible: Should be one of below: "fsl,imx6q-usbmisc" for imx6q "fsl,vf610-usbmisc" for Vybrid vf610 diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 041ae90b0d8f..9d5680c7c853 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -59,6 +59,8 @@ patternProperties: description: Aeroflex Gaisler AB "^al,.*": description: Annapurna Labs + "^alcatel,.*": + description: Alcatel "^allegro,.*": description: Allegro DVT "^allo,.*": @@ -229,6 +231,8 @@ patternProperties: description: Computadora Industrial Abierta Argentina "^cirrus,.*": description: Cirrus Logic, Inc. + "^cisco,.*": + description: Cisco Systems, Inc. "^cloudengines,.*": description: Cloud Engines, Inc. "^cnm,.*": @@ -311,6 +315,8 @@ patternProperties: description: Dyna-Image "^ea,.*": description: Embedded Artists AB + "^ebang,.*": + description: Zhejiang Ebang Communication Co., Ltd "^ebs-systart,.*": description: EBS-SYSTART GmbH "^ebv,.*": @@ -467,10 +473,10 @@ patternProperties: description: Hitex Development Tools "^holt,.*": description: Holt Integrated Circuits, Inc. - "^honeywell,.*": - description: Honeywell "^honestar,.*": description: Honestar Technologies Co., Ltd. + "^honeywell,.*": + description: Honeywell "^hoperun,.*": description: Jiangsu HopeRun Software Co., Ltd. "^hp,.*": @@ -581,6 +587,8 @@ patternProperties: description: Kontron S&T AG "^kosagi,.*": description: Sutajio Ko-Usagi PTE Ltd. + "^kvg,.*": + description: Kverneland Group "^kyo,.*": description: Kyocera Corporation "^lacie,.*": @@ -866,6 +874,8 @@ patternProperties: description: PLDA "^plx,.*": description: Broadcom Corporation (formerly PLX Technology) + "^ply,.*": + description: Plymovent Group BV "^pni,.*": description: PNI Sensor Corporation "^pocketbook,.*": @@ -1252,6 +1262,8 @@ patternProperties: description: Shenzhen Xunlong Software CO.,Limited "^xylon,.*": description: Xylon + "^yamaha,.*": + description: Yamaha Corporation "^yes-optoelectronics,.*": description: Yes Optoelectronics Co.,Ltd. "^ylm,.*": @@ -1260,6 +1272,8 @@ patternProperties: description: YSH & ATIL "^yones-toptech,.*": description: Yones Toptech Co., Ltd. + "^ys,.*": + description: Shenzhen Yashi Changhua Intelligent Technology Co., Ltd. "^ysoft,.*": description: Y Soft Corporation a.s. "^zealz,.*": diff --git a/Documentation/devicetree/bindings/watchdog/allwinner,sun4i-a10-wdt.yaml b/Documentation/devicetree/bindings/watchdog/allwinner,sun4i-a10-wdt.yaml index 5ac607de8be4..9aa3c313c49f 100644 --- a/Documentation/devicetree/bindings/watchdog/allwinner,sun4i-a10-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/allwinner,sun4i-a10-wdt.yaml @@ -19,13 +19,11 @@ properties: - const: allwinner,sun4i-a10-wdt - const: allwinner,sun6i-a31-wdt - items: - - const: allwinner,sun50i-a64-wdt - - const: allwinner,sun6i-a31-wdt - - items: - - const: allwinner,sun50i-a100-wdt - - const: allwinner,sun6i-a31-wdt - - items: - - const: allwinner,sun50i-h6-wdt + - enum: + - allwinner,sun50i-a64-wdt + - allwinner,sun50i-a100-wdt + - allwinner,sun50i-h6-wdt + - allwinner,sun50i-h616-wdt - const: allwinner,sun6i-a31-wdt - items: - const: allwinner,suniv-f1c100s-wdt diff --git a/Documentation/devicetree/bindings/watchdog/intel,keembay-wdt.yaml b/Documentation/devicetree/bindings/watchdog/intel,keembay-wdt.yaml new file mode 100644 index 000000000000..1437ff8a122f --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/intel,keembay-wdt.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/watchdog/intel,keembay-wdt.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel Keem Bay SoC non-secure Watchdog Timer + +maintainers: + - Wan Ahmad Zainie <wan.ahmad.zainie.wan.mohamad@intel.com> + +properties: + compatible: + enum: + - intel,keembay-wdt + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + interrupts: + items: + - description: interrupt specifier for threshold interrupt line + - description: interrupt specifier for timeout interrupt line + + interrupt-names: + items: + - const: threshold + - const: timeout + +required: + - compatible + - reg + - interrupts + - interrupt-names + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + #define KEEM_BAY_A53_TIM + + watchdog: watchdog@2033009c { + compatible = "intel,keembay-wdt"; + reg = <0x2033009c 0x10>; + interrupts = <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "threshold", "timeout"; + clocks = <&scmi_clk KEEM_BAY_A53_TIM>; + }; + +... diff --git a/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt b/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt index 4dd36bd3f1ad..e36ba60de829 100644 --- a/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt @@ -4,14 +4,15 @@ Required properties: - compatible should contain: "mediatek,mt2701-wdt", "mediatek,mt6589-wdt": for MT2701 - "mediatek,mt2712-wdt", "mediatek,mt6589-wdt": for MT2712 + "mediatek,mt2712-wdt": for MT2712 "mediatek,mt6589-wdt": for MT6589 "mediatek,mt6797-wdt", "mediatek,mt6589-wdt": for MT6797 "mediatek,mt7622-wdt", "mediatek,mt6589-wdt": for MT7622 "mediatek,mt7623-wdt", "mediatek,mt6589-wdt": for MT7623 "mediatek,mt7629-wdt", "mediatek,mt6589-wdt": for MT7629 - "mediatek,mt8183-wdt", "mediatek,mt6589-wdt": for MT8183 + "mediatek,mt8183-wdt": for MT8183 "mediatek,mt8516-wdt", "mediatek,mt6589-wdt": for MT8516 + "mediatek,mt8192-wdt": for MT8192 - reg : Specifies base physical address and size of the registers. diff --git a/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml b/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml index 8e3760a3822b..b8e4118945a0 100644 --- a/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml @@ -18,6 +18,7 @@ properties: - qcom,apss-wdt-qcs404 - qcom,apss-wdt-sc7180 - qcom,apss-wdt-sdm845 + - qcom,apss-wdt-sdx55 - qcom,apss-wdt-sm8150 - qcom,kpss-timer - qcom,kpss-wdt diff --git a/Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml b/Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml index 6933005b52bd..ab66d3f0c476 100644 --- a/Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml @@ -50,6 +50,7 @@ properties: - renesas,r8a77980-wdt # R-Car V3H - renesas,r8a77990-wdt # R-Car E3 - renesas,r8a77995-wdt # R-Car D3 + - renesas,r8a779a0-wdt # R-Car V3U - const: renesas,rcar-gen3-wdt # R-Car Gen3 and RZ/G2 reg: diff --git a/Documentation/devicetree/bindings/watchdog/sigma,smp8642-wdt.txt b/Documentation/devicetree/bindings/watchdog/sigma,smp8642-wdt.txt deleted file mode 100644 index 5b7ec2c707d8..000000000000 --- a/Documentation/devicetree/bindings/watchdog/sigma,smp8642-wdt.txt +++ /dev/null @@ -1,18 +0,0 @@ -Sigma Designs SMP86xx/SMP87xx watchdog - -Required properties: -- compatible: Should be "sigma,smp8642-wdt" -- reg: Specifies the physical address region -- clocks: Should be a phandle to the clock - -Optional properties: -- timeout-sec: watchdog timeout in seconds - -Example: - -watchdog@1fd00 { - compatible = "sigma,smp8642-wdt"; - reg = <0x1fd00 8>; - clocks = <&xtal_in_clk>; - timeout-sec = <30>; -}; diff --git a/Documentation/devicetree/bindings/watchdog/sirfsoc_wdt.txt b/Documentation/devicetree/bindings/watchdog/sirfsoc_wdt.txt deleted file mode 100644 index 0dce5e3100b4..000000000000 --- a/Documentation/devicetree/bindings/watchdog/sirfsoc_wdt.txt +++ /dev/null @@ -1,18 +0,0 @@ -SiRFSoC Timer and Watchdog Timer(WDT) Controller - -Required properties: -- compatible: "sirf,prima2-tick" -- reg: Address range of tick timer/WDT register set -- interrupts: interrupt number to the cpu - -Optional properties: -- timeout-sec : Contains the watchdog timeout in seconds - -Example: - -timer@b0020000 { - compatible = "sirf,prima2-tick"; - reg = <0xb0020000 0x1000>; - interrupts = <0>; - timeout-sec = <30>; -}; diff --git a/Documentation/devicetree/bindings/watchdog/snps,dw-wdt.yaml b/Documentation/devicetree/bindings/watchdog/snps,dw-wdt.yaml index f7ee9229c29f..b58596b1831d 100644 --- a/Documentation/devicetree/bindings/watchdog/snps,dw-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/snps,dw-wdt.yaml @@ -18,10 +18,16 @@ properties: - const: snps,dw-wdt - items: - enum: + - rockchip,px30-wdt - rockchip,rk3066-wdt - rockchip,rk3188-wdt + - rockchip,rk3228-wdt - rockchip,rk3288-wdt + - rockchip,rk3308-wdt + - rockchip,rk3328-wdt - rockchip,rk3368-wdt + - rockchip,rk3399-wdt + - rockchip,rv1108-wdt - const: snps,dw-wdt reg: diff --git a/Documentation/devicetree/bindings/watchdog/stericsson-coh901327.txt b/Documentation/devicetree/bindings/watchdog/stericsson-coh901327.txt deleted file mode 100644 index 8ffb88e39e76..000000000000 --- a/Documentation/devicetree/bindings/watchdog/stericsson-coh901327.txt +++ /dev/null @@ -1,19 +0,0 @@ -ST-Ericsson COH 901 327 Watchdog timer - -Required properties: -- compatible: must be "stericsson,coh901327". -- reg: physical base address of the controller and length of memory mapped - region. -- interrupts: the interrupt used for the watchdog timeout warning. - -Optional properties: -- timeout-sec: contains the watchdog timeout in seconds. - -Example: - -watchdog: watchdog@c0012000 { - compatible = "stericsson,coh901327"; - reg = <0xc0012000 0x1000>; - interrupts = <3>; - timeout-sec = <60>; -}; diff --git a/Documentation/devicetree/bindings/watchdog/zte,zx2967-wdt.txt b/Documentation/devicetree/bindings/watchdog/zte,zx2967-wdt.txt deleted file mode 100644 index 06ce67766756..000000000000 --- a/Documentation/devicetree/bindings/watchdog/zte,zx2967-wdt.txt +++ /dev/null @@ -1,32 +0,0 @@ -ZTE zx2967 Watchdog timer - -Required properties: - -- compatible : should be one of the following. - * zte,zx296718-wdt -- reg : Specifies base physical address and size of the registers. -- clocks : Pairs of phandle and specifier referencing the controller's clocks. -- resets : Reference to the reset controller controlling the watchdog - controller. - -Optional properties: - -- timeout-sec : Contains the watchdog timeout in seconds. -- zte,wdt-reset-sysctrl : Directs how to reset system by the watchdog. - if we don't want to restart system when watchdog been triggered, - it's not required, vice versa. - It should include following fields. - * phandle of aon-sysctrl. - * offset of register that be written, should be 0xb0. - * configure value that be written to aon-sysctrl. - * bit mask, corresponding bits will be affected. - -Example: - -wdt: watchdog@1465000 { - compatible = "zte,zx296718-wdt"; - reg = <0x1465000 0x1000>; - clocks = <&topcrm WDT_WCLK>; - resets = <&toprst 35>; - zte,wdt-reset-sysctrl = <&aon_sysctrl 0xb0 1 0x115>; -}; diff --git a/Documentation/driver-api/auxiliary_bus.rst b/Documentation/driver-api/auxiliary_bus.rst index 2312506b0674..fff96c7ba7a8 100644 --- a/Documentation/driver-api/auxiliary_bus.rst +++ b/Documentation/driver-api/auxiliary_bus.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0-only +.. _auxiliary_bus: + ============= Auxiliary Bus ============= diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 2456d0a97ed8..9d9af54d68c5 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -99,6 +99,7 @@ available subsections can be seen below. rfkill serial/index sm501 + surface_aggregator/index switchtec sync_file vfio-mediated-device diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index ffb0cad8137a..3fc378b3b269 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -15,7 +15,7 @@ Camera sensors have an internal clock tree including a PLL and a number of divisors. The clock tree is generally configured by the driver based on a few input parameters that are specific to the hardware:: the external clock frequency and the link frequency. The two parameters generally are obtained from system -firmware. No other frequencies should be used in any circumstances. +firmware. **No other frequencies should be used in any circumstances.** The reason why the clock frequencies are so important is that the clock signals come out of the SoC, and in many cases a specific frequency is designed to be @@ -23,6 +23,24 @@ used in the system. Using another frequency may cause harmful effects elsewhere. Therefore only the pre-determined frequencies are configurable by the user. +ACPI +~~~~ + +Read the "clock-frequency" _DSD property to denote the frequency. The driver can +rely on this frequency being used. + +Devicetree +~~~~~~~~~~ + +The currently preferred way to achieve this is using "assigned-clock-rates" +property. See Documentation/devicetree/bindings/clock/clock-bindings.txt for +more information. The driver then gets the frequency using clk_get_rate(). + +This approach has the drawback that there's no guarantee that the frequency +hasn't been modified directly or indirectly by another driver, or supported by +the board's clock tree to begin with. Changes to the Common Clock Framework API +are required to ensure reliability. + Frame size ---------- diff --git a/Documentation/driver-api/media/cec-core.rst b/Documentation/driver-api/media/cec-core.rst index a26dc87eee8f..56345eae9a26 100644 --- a/Documentation/driver-api/media/cec-core.rst +++ b/Documentation/driver-api/media/cec-core.rst @@ -26,7 +26,7 @@ It is documented in the HDMI 1.4 specification with the new 2.0 bits documented in the HDMI 2.0 specification. But for most of the features the freely available HDMI 1.3a specification is sufficient: -http://www.microprocessor.org/HDMISpecification13a.pdf +https://www.hdmi.org/spec/index CEC Adapter Interface diff --git a/Documentation/driver-api/media/csi2.rst b/Documentation/driver-api/media/csi2.rst index e3bbc6baf0f0..11c52b0be8b8 100644 --- a/Documentation/driver-api/media/csi2.rst +++ b/Documentation/driver-api/media/csi2.rst @@ -35,7 +35,7 @@ ability to start and stop the stream. The value of the V4L2_CID_PIXEL_RATE is calculated as follows:: - pixel_rate = link_freq * 2 * nr_of_lanes / bits_per_sample + pixel_rate = link_freq * 2 * nr_of_lanes * 16 / k / bits_per_sample where @@ -53,6 +53,8 @@ where - Two bits are transferred per clock cycle per lane. * - bits_per_sample - Number of bits per sample. + * - k + - 16 for D-PHY and 7 for C-PHY The transmitter drivers must, if possible, configure the CSI-2 transmitter to *LP-11 mode* whenever the transmitter is powered on but diff --git a/Documentation/driver-api/media/drivers/ccs/ccs.rst b/Documentation/driver-api/media/drivers/ccs/ccs.rst index f49e971f2d92..b461c8aa2a16 100644 --- a/Documentation/driver-api/media/drivers/ccs/ccs.rst +++ b/Documentation/driver-api/media/drivers/ccs/ccs.rst @@ -79,4 +79,17 @@ definitions: -l drivers/media/i2c/ccs/ccs-limits.c \ -c Documentation/driver-api/media/drivers/ccs/ccs-regs.asc +CCS PLL calculator +================== + +The CCS PLL calculator is used to compute the PLL configuration, given sensor's +capabilities as well as board configuration and user specified configuration. As +the configuration space that encompasses all these configurations is vast, the +PLL calculator isn't entirely trivial. Yet it is relatively simple to use for a +driver. + +The PLL model implemented by the PLL calculator corresponds to MIPI CCS 1.1. + +.. kernel-doc:: drivers/media/i2c/ccs-pll.h + **Copyright** |copy| 2020 Intel Corporation diff --git a/Documentation/driver-api/media/v4l2-clocks.rst b/Documentation/driver-api/media/v4l2-clocks.rst deleted file mode 100644 index 5c22eecab7ba..000000000000 --- a/Documentation/driver-api/media/v4l2-clocks.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -V4L2 clocks ------------ - -.. attention:: - - This is a temporary API and it shall be replaced by the generic - clock API, when the latter becomes widely available. - -Many subdevices, like camera sensors, TV decoders and encoders, need a clock -signal to be supplied by the system. Often this clock is supplied by the -respective bridge device. The Linux kernel provides a Common Clock Framework for -this purpose. However, it is not (yet) available on all architectures. Besides, -the nature of the multi-functional (clock, data + synchronisation, I2C control) -connection of subdevices to the system might impose special requirements on the -clock API usage. E.g. V4L2 has to support clock provider driver unregistration -while a subdevice driver is holding a reference to the clock. For these reasons -a V4L2 clock helper API has been developed and is provided to bridge and -subdevice drivers. - -The API consists of two parts: two functions to register and unregister a V4L2 -clock source: v4l2_clk_register() and v4l2_clk_unregister() and calls to control -a clock object, similar to the respective generic clock API calls: -v4l2_clk_get(), v4l2_clk_put(), v4l2_clk_enable(), v4l2_clk_disable(), -v4l2_clk_get_rate(), and v4l2_clk_set_rate(). Clock suppliers have to provide -clock operations that will be called when clock users invoke respective API -methods. - -It is expected that once the CCF becomes available on all relevant -architectures this API will be removed. diff --git a/Documentation/driver-api/media/v4l2-core.rst b/Documentation/driver-api/media/v4l2-core.rst index 0dcad7a23141..1a8c4a5f256b 100644 --- a/Documentation/driver-api/media/v4l2-core.rst +++ b/Documentation/driver-api/media/v4l2-core.rst @@ -15,7 +15,6 @@ Video4Linux devices v4l2-controls v4l2-videobuf v4l2-videobuf2 - v4l2-clocks v4l2-dv-timings v4l2-flash-led-class v4l2-mc diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst index bb5b1a7cdfd9..8b53da2f9c74 100644 --- a/Documentation/driver-api/media/v4l2-subdev.rst +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -122,15 +122,12 @@ Don't forget to cleanup the media entity before the sub-device is destroyed: media_entity_cleanup(&sd->entity); -If the subdev driver intends to process video and integrate with the media -framework, it must implement format related functionality using -:c:type:`v4l2_subdev_pad_ops` instead of :c:type:`v4l2_subdev_video_ops`. - -In that case, the subdev driver may set the link_validate field to provide -its own link validation function. The link validation function is called for -every link in the pipeline where both of the ends of the links are V4L2 -sub-devices. The driver is still responsible for validating the correctness -of the format configuration between sub-devices and video nodes. +If a sub-device driver implements sink pads, the subdev driver may set the +link_validate field in :c:type:`v4l2_subdev_pad_ops` to provide its own link +validation function. For every link in the pipeline, the link_validate pad +operation of the sink end of the link is called. In both cases the driver is +still responsible for validating the correctness of the format configuration +between sub-devices and video nodes. If link_validate op is not set, the default function :c:func:`v4l2_subdev_link_validate_default` is used instead. This function @@ -200,15 +197,45 @@ unregister the notifier the driver has to call takes two arguments: a pointer to struct :c:type:`v4l2_device` and a pointer to struct :c:type:`v4l2_async_notifier`. -Before registering the notifier, bridge drivers must do two things: -first, the notifier must be initialized using the -:c:func:`v4l2_async_notifier_init`. Second, bridge drivers can then -begin to form a list of subdevice descriptors that the bridge device -needs for its operation. Subdevice descriptors are added to the notifier -using the :c:func:`v4l2_async_notifier_add_subdev` call. This function -takes two arguments: a pointer to struct :c:type:`v4l2_async_notifier`, -and a pointer to the subdevice descripter, which is of type struct -:c:type:`v4l2_async_subdev`. +Before registering the notifier, bridge drivers must do two things: first, the +notifier must be initialized using the :c:func:`v4l2_async_notifier_init`. +Second, bridge drivers can then begin to form a list of subdevice descriptors +that the bridge device needs for its operation. Several functions are available +to add subdevice descriptors to a notifier, depending on the type of device and +the needs of the driver. + +:c:func:`v4l2_async_notifier_add_fwnode_remote_subdev` and +:c:func:`v4l2_async_notifier_add_i2c_subdev` are for bridge and ISP drivers for +registering their async sub-devices with the notifier. + +:c:func:`v4l2_async_register_subdev_sensor_common` is a helper function for +sensor drivers registering their own async sub-device, but it also registers a +notifier and further registers async sub-devices for lens and flash devices +found in firmware. The notifier for the sub-device is unregistered with the +async sub-device. + +These functions allocate an async sub-device descriptor which is of type struct +:c:type:`v4l2_async_subdev` embedded in a driver-specific struct. The &struct +:c:type:`v4l2_async_subdev` shall be the first member of this struct: + +.. code-block:: c + + struct my_async_subdev { + struct v4l2_async_subdev asd; + ... + }; + + struct my_async_subdev *my_asd; + struct fwnode_handle *ep; + + ... + + my_asd = v4l2_async_notifier_add_fwnode_remote_subdev(¬ifier, ep, + struct my_async_subdev); + fwnode_handle_put(ep); + + if (IS_ERR(asd)) + return PTR_ERR(asd); The V4L2 core will then use these descriptors to match asynchronously registered subdevices to them. If a match is detected the ``.bound()`` diff --git a/Documentation/driver-api/surface_aggregator/client-api.rst b/Documentation/driver-api/surface_aggregator/client-api.rst new file mode 100644 index 000000000000..8e0b000d0e64 --- /dev/null +++ b/Documentation/driver-api/surface_aggregator/client-api.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +=============================== +Client Driver API Documentation +=============================== + +.. contents:: + :depth: 2 + + +Serial Hub Communication +======================== + +.. kernel-doc:: include/linux/surface_aggregator/serial_hub.h + +.. kernel-doc:: drivers/platform/surface/aggregator/ssh_packet_layer.c + :export: + + +Controller and Core Interface +============================= + +.. kernel-doc:: include/linux/surface_aggregator/controller.h + +.. kernel-doc:: drivers/platform/surface/aggregator/controller.c + :export: + +.. kernel-doc:: drivers/platform/surface/aggregator/core.c + :export: + + +Client Bus and Client Device API +================================ + +.. kernel-doc:: include/linux/surface_aggregator/device.h + +.. kernel-doc:: drivers/platform/surface/aggregator/bus.c + :export: diff --git a/Documentation/driver-api/surface_aggregator/client.rst b/Documentation/driver-api/surface_aggregator/client.rst new file mode 100644 index 000000000000..26d13085a117 --- /dev/null +++ b/Documentation/driver-api/surface_aggregator/client.rst @@ -0,0 +1,393 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. |ssam_controller| replace:: :c:type:`struct ssam_controller <ssam_controller>` +.. |ssam_device| replace:: :c:type:`struct ssam_device <ssam_device>` +.. |ssam_device_driver| replace:: :c:type:`struct ssam_device_driver <ssam_device_driver>` +.. |ssam_client_bind| replace:: :c:func:`ssam_client_bind` +.. |ssam_client_link| replace:: :c:func:`ssam_client_link` +.. |ssam_get_controller| replace:: :c:func:`ssam_get_controller` +.. |ssam_controller_get| replace:: :c:func:`ssam_controller_get` +.. |ssam_controller_put| replace:: :c:func:`ssam_controller_put` +.. |ssam_device_alloc| replace:: :c:func:`ssam_device_alloc` +.. |ssam_device_add| replace:: :c:func:`ssam_device_add` +.. |ssam_device_remove| replace:: :c:func:`ssam_device_remove` +.. |ssam_device_driver_register| replace:: :c:func:`ssam_device_driver_register` +.. |ssam_device_driver_unregister| replace:: :c:func:`ssam_device_driver_unregister` +.. |module_ssam_device_driver| replace:: :c:func:`module_ssam_device_driver` +.. |SSAM_DEVICE| replace:: :c:func:`SSAM_DEVICE` +.. |ssam_notifier_register| replace:: :c:func:`ssam_notifier_register` +.. |ssam_notifier_unregister| replace:: :c:func:`ssam_notifier_unregister` +.. |ssam_request_sync| replace:: :c:func:`ssam_request_sync` +.. |ssam_event_mask| replace:: :c:type:`enum ssam_event_mask <ssam_event_mask>` + + +====================== +Writing Client Drivers +====================== + +For the API documentation, refer to: + +.. toctree:: + :maxdepth: 2 + + client-api + + +Overview +======== + +Client drivers can be set up in two main ways, depending on how the +corresponding device is made available to the system. We specifically +differentiate between devices that are presented to the system via one of +the conventional ways, e.g. as platform devices via ACPI, and devices that +are non-discoverable and instead need to be explicitly provided by some +other mechanism, as discussed further below. + + +Non-SSAM Client Drivers +======================= + +All communication with the SAM EC is handled via the |ssam_controller| +representing that EC to the kernel. Drivers targeting a non-SSAM device (and +thus not being a |ssam_device_driver|) need to explicitly establish a +connection/relation to that controller. This can be done via the +|ssam_client_bind| function. Said function returns a reference to the SSAM +controller, but, more importantly, also establishes a device link between +client device and controller (this can also be done separate via +|ssam_client_link|). It is important to do this, as it, first, guarantees +that the returned controller is valid for use in the client driver for as +long as this driver is bound to its device, i.e. that the driver gets +unbound before the controller ever becomes invalid, and, second, as it +ensures correct suspend/resume ordering. This setup should be done in the +driver's probe function, and may be used to defer probing in case the SSAM +subsystem is not ready yet, for example: + +.. code-block:: c + + static int client_driver_probe(struct platform_device *pdev) + { + struct ssam_controller *ctrl; + + ctrl = ssam_client_bind(&pdev->dev); + if (IS_ERR(ctrl)) + return PTR_ERR(ctrl) == -ENODEV ? -EPROBE_DEFER : PTR_ERR(ctrl); + + // ... + + return 0; + } + +The controller may be separately obtained via |ssam_get_controller| and its +lifetime be guaranteed via |ssam_controller_get| and |ssam_controller_put|. +Note that none of these functions, however, guarantee that the controller +will not be shut down or suspended. These functions essentially only operate +on the reference, i.e. only guarantee a bare minimum of accessibility +without any guarantees at all on practical operability. + + +Adding SSAM Devices +=================== + +If a device does not already exist/is not already provided via conventional +means, it should be provided as |ssam_device| via the SSAM client device +hub. New devices can be added to this hub by entering their UID into the +corresponding registry. SSAM devices can also be manually allocated via +|ssam_device_alloc|, subsequently to which they have to be added via +|ssam_device_add| and eventually removed via |ssam_device_remove|. By +default, the parent of the device is set to the controller device provided +for allocation, however this may be changed before the device is added. Note +that, when changing the parent device, care must be taken to ensure that the +controller lifetime and suspend/resume ordering guarantees, in the default +setup provided through the parent-child relation, are preserved. If +necessary, by use of |ssam_client_link| as is done for non-SSAM client +drivers and described in more detail above. + +A client device must always be removed by the party which added the +respective device before the controller shuts down. Such removal can be +guaranteed by linking the driver providing the SSAM device to the controller +via |ssam_client_link|, causing it to unbind before the controller driver +unbinds. Client devices registered with the controller as parent are +automatically removed when the controller shuts down, but this should not be +relied upon, especially as this does not extend to client devices with a +different parent. + + +SSAM Client Drivers +=================== + +SSAM client device drivers are, in essence, no different than other device +driver types. They are represented via |ssam_device_driver| and bind to a +|ssam_device| via its UID (:c:type:`struct ssam_device.uid <ssam_device>`) +member and the match table +(:c:type:`struct ssam_device_driver.match_table <ssam_device_driver>`), +which should be set when declaring the driver struct instance. Refer to the +|SSAM_DEVICE| macro documentation for more details on how to define members +of the driver's match table. + +The UID for SSAM client devices consists of a ``domain``, a ``category``, +a ``target``, an ``instance``, and a ``function``. The ``domain`` is used +differentiate between physical SAM devices +(:c:type:`SSAM_DOMAIN_SERIALHUB <ssam_device_domain>`), i.e. devices that can +be accessed via the Surface Serial Hub, and virtual ones +(:c:type:`SSAM_DOMAIN_VIRTUAL <ssam_device_domain>`), such as client-device +hubs, that have no real representation on the SAM EC and are solely used on +the kernel/driver-side. For physical devices, ``category`` represents the +target category, ``target`` the target ID, and ``instance`` the instance ID +used to access the physical SAM device. In addition, ``function`` references +a specific device functionality, but has no meaning to the SAM EC. The +(default) name of a client device is generated based on its UID. + +A driver instance can be registered via |ssam_device_driver_register| and +unregistered via |ssam_device_driver_unregister|. For convenience, the +|module_ssam_device_driver| macro may be used to define module init- and +exit-functions registering the driver. + +The controller associated with a SSAM client device can be found in its +:c:type:`struct ssam_device.ctrl <ssam_device>` member. This reference is +guaranteed to be valid for at least as long as the client driver is bound, +but should also be valid for as long as the client device exists. Note, +however, that access outside of the bound client driver must ensure that the +controller device is not suspended while making any requests or +(un-)registering event notifiers (and thus should generally be avoided). This +is guaranteed when the controller is accessed from inside the bound client +driver. + + +Making Synchronous Requests +=========================== + +Synchronous requests are (currently) the main form of host-initiated +communication with the EC. There are a couple of ways to define and execute +such requests, however, most of them boil down to something similar as shown +in the example below. This example defines a write-read request, meaning +that the caller provides an argument to the SAM EC and receives a response. +The caller needs to know the (maximum) length of the response payload and +provide a buffer for it. + +Care must be taken to ensure that any command payload data passed to the SAM +EC is provided in little-endian format and, similarly, any response payload +data received from it is converted from little-endian to host endianness. + +.. code-block:: c + + int perform_request(struct ssam_controller *ctrl, u32 arg, u32 *ret) + { + struct ssam_request rqst; + struct ssam_response resp; + int status; + + /* Convert request argument to little-endian. */ + __le32 arg_le = cpu_to_le32(arg); + __le32 ret_le = cpu_to_le32(0); + + /* + * Initialize request specification. Replace this with your values. + * The rqst.payload field may be NULL if rqst.length is zero, + * indicating that the request does not have any argument. + * + * Note: The request parameters used here are not valid, i.e. + * they do not correspond to an actual SAM/EC request. + */ + rqst.target_category = SSAM_SSH_TC_SAM; + rqst.target_id = 0x01; + rqst.command_id = 0x02; + rqst.instance_id = 0x03; + rqst.flags = SSAM_REQUEST_HAS_RESPONSE; + rqst.length = sizeof(arg_le); + rqst.payload = (u8 *)&arg_le; + + /* Initialize request response. */ + resp.capacity = sizeof(ret_le); + resp.length = 0; + resp.pointer = (u8 *)&ret_le; + + /* + * Perform actual request. The response pointer may be null in case + * the request does not have any response. This must be consistent + * with the SSAM_REQUEST_HAS_RESPONSE flag set in the specification + * above. + */ + status = ssam_request_sync(ctrl, &rqst, &resp); + + /* + * Alternatively use + * + * ssam_request_sync_onstack(ctrl, &rqst, &resp, sizeof(arg_le)); + * + * to perform the request, allocating the message buffer directly + * on the stack as opposed to allocation via kzalloc(). + */ + + /* + * Convert request response back to native format. Note that in the + * error case, this value is not touched by the SSAM core, i.e. + * 'ret_le' will be zero as specified in its initialization. + */ + *ret = le32_to_cpu(ret_le); + + return status; + } + +Note that |ssam_request_sync| in its essence is a wrapper over lower-level +request primitives, which may also be used to perform requests. Refer to its +implementation and documentation for more details. + +An arguably more user-friendly way of defining such functions is by using +one of the generator macros, for example via: + +.. code-block:: c + + SSAM_DEFINE_SYNC_REQUEST_W(__ssam_tmp_perf_mode_set, __le32, { + .target_category = SSAM_SSH_TC_TMP, + .target_id = 0x01, + .command_id = 0x03, + .instance_id = 0x00, + }); + +This example defines a function + +.. code-block:: c + + int __ssam_tmp_perf_mode_set(struct ssam_controller *ctrl, const __le32 *arg); + +executing the specified request, with the controller passed in when calling +said function. In this example, the argument is provided via the ``arg`` +pointer. Note that the generated function allocates the message buffer on +the stack. Thus, if the argument provided via the request is large, these +kinds of macros should be avoided. Also note that, in contrast to the +previous non-macro example, this function does not do any endianness +conversion, which has to be handled by the caller. Apart from those +differences the function generated by the macro is similar to the one +provided in the non-macro example above. + +The full list of such function-generating macros is + +- :c:func:`SSAM_DEFINE_SYNC_REQUEST_N` for requests without return value and + without argument. +- :c:func:`SSAM_DEFINE_SYNC_REQUEST_R` for requests with return value but no + argument. +- :c:func:`SSAM_DEFINE_SYNC_REQUEST_W` for requests without return value but + with argument. + +Refer to their respective documentation for more details. For each one of +these macros, a special variant is provided, which targets request types +applicable to multiple instances of the same device type: + +- :c:func:`SSAM_DEFINE_SYNC_REQUEST_MD_N` +- :c:func:`SSAM_DEFINE_SYNC_REQUEST_MD_R` +- :c:func:`SSAM_DEFINE_SYNC_REQUEST_MD_W` + +The difference of those macros to the previously mentioned versions is, that +the device target and instance IDs are not fixed for the generated function, +but instead have to be provided by the caller of said function. + +Additionally, variants for direct use with client devices, i.e. +|ssam_device|, are also provided. These can, for example, be used as +follows: + +.. code-block:: c + + SSAM_DEFINE_SYNC_REQUEST_CL_R(ssam_bat_get_sta, __le32, { + .target_category = SSAM_SSH_TC_BAT, + .command_id = 0x01, + }); + +This invocation of the macro defines a function + +.. code-block:: c + + int ssam_bat_get_sta(struct ssam_device *sdev, __le32 *ret); + +executing the specified request, using the device IDs and controller given +in the client device. The full list of such macros for client devices is: + +- :c:func:`SSAM_DEFINE_SYNC_REQUEST_CL_N` +- :c:func:`SSAM_DEFINE_SYNC_REQUEST_CL_R` +- :c:func:`SSAM_DEFINE_SYNC_REQUEST_CL_W` + + +Handling Events +=============== + +To receive events from the SAM EC, an event notifier must be registered for +the desired event via |ssam_notifier_register|. The notifier must be +unregistered via |ssam_notifier_unregister| once it is not required any +more. + +Event notifiers are registered by providing (at minimum) a callback to call +in case an event has been received, the registry specifying how the event +should be enabled, an event ID specifying for which target category and, +optionally and depending on the registry used, for which instance ID events +should be enabled, and finally, flags describing how the EC will send these +events. If the specific registry does not enable events by instance ID, the +instance ID must be set to zero. Additionally, a priority for the respective +notifier may be specified, which determines its order in relation to any +other notifier registered for the same target category. + +By default, event notifiers will receive all events for the specific target +category, regardless of the instance ID specified when registering the +notifier. The core may be instructed to only call a notifier if the target +ID or instance ID (or both) of the event match the ones implied by the +notifier IDs (in case of target ID, the target ID of the registry), by +providing an event mask (see |ssam_event_mask|). + +In general, the target ID of the registry is also the target ID of the +enabled event (with the notable exception being keyboard input events on the +Surface Laptop 1 and 2, which are enabled via a registry with target ID 1, +but provide events with target ID 2). + +A full example for registering an event notifier and handling received +events is provided below: + +.. code-block:: c + + u32 notifier_callback(struct ssam_event_notifier *nf, + const struct ssam_event *event) + { + int status = ... + + /* Handle the event here ... */ + + /* Convert return value and indicate that we handled the event. */ + return ssam_notifier_from_errno(status) | SSAM_NOTIF_HANDLED; + } + + int setup_notifier(struct ssam_device *sdev, + struct ssam_event_notifier *nf) + { + /* Set priority wrt. other handlers of same target category. */ + nf->base.priority = 1; + + /* Set event/notifier callback. */ + nf->base.fn = notifier_callback; + + /* Specify event registry, i.e. how events get enabled/disabled. */ + nf->event.reg = SSAM_EVENT_REGISTRY_KIP; + + /* Specify which event to enable/disable */ + nf->event.id.target_category = sdev->uid.category; + nf->event.id.instance = sdev->uid.instance; + + /* + * Specify for which events the notifier callback gets executed. + * This essentially tells the core if it can skip notifiers that + * don't have target or instance IDs matching those of the event. + */ + nf->event.mask = SSAM_EVENT_MASK_STRICT; + + /* Specify event flags. */ + nf->event.flags = SSAM_EVENT_SEQUENCED; + + return ssam_notifier_register(sdev->ctrl, nf); + } + +Multiple event notifiers can be registered for the same event. The event +handler core takes care of enabling and disabling events when notifiers are +registered and unregistered, by keeping track of how many notifiers for a +specific event (combination of registry, event target category, and event +instance ID) are currently registered. This means that a specific event will +be enabled when the first notifier for it is being registered and disabled +when the last notifier for it is being unregistered. Note that the event +flags are therefore only used on the first registered notifier, however, one +should take care that notifiers for a specific event are always registered +with the same flag and it is considered a bug to do otherwise. diff --git a/Documentation/driver-api/surface_aggregator/clients/cdev.rst b/Documentation/driver-api/surface_aggregator/clients/cdev.rst new file mode 100644 index 000000000000..248c1372d879 --- /dev/null +++ b/Documentation/driver-api/surface_aggregator/clients/cdev.rst @@ -0,0 +1,87 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. |u8| replace:: :c:type:`u8 <u8>` +.. |u16| replace:: :c:type:`u16 <u16>` +.. |ssam_cdev_request| replace:: :c:type:`struct ssam_cdev_request <ssam_cdev_request>` +.. |ssam_cdev_request_flags| replace:: :c:type:`enum ssam_cdev_request_flags <ssam_cdev_request_flags>` + +============================== +User-Space EC Interface (cdev) +============================== + +The ``surface_aggregator_cdev`` module provides a misc-device for the SSAM +controller to allow for a (more or less) direct connection from user-space to +the SAM EC. It is intended to be used for development and debugging, and +therefore should not be used or relied upon in any other way. Note that this +module is not loaded automatically, but instead must be loaded manually. + +The provided interface is accessible through the ``/dev/surface/aggregator`` +device-file. All functionality of this interface is provided via IOCTLs. +These IOCTLs and their respective input/output parameter structs are defined in +``include/uapi/linux/surface_aggregator/cdev.h``. + +A small python library and scripts for accessing this interface can be found +at https://github.com/linux-surface/surface-aggregator-module/tree/master/scripts/ssam. + + +Controller IOCTLs +================= + +The following IOCTLs are provided: + +.. flat-table:: Controller IOCTLs + :widths: 1 1 1 1 4 + :header-rows: 1 + + * - Type + - Number + - Direction + - Name + - Description + + * - ``0xA5`` + - ``1`` + - ``WR`` + - ``REQUEST`` + - Perform synchronous SAM request. + + +``REQUEST`` +----------- + +Defined as ``_IOWR(0xA5, 1, struct ssam_cdev_request)``. + +Executes a synchronous SAM request. The request specification is passed in +as argument of type |ssam_cdev_request|, which is then written to/modified +by the IOCTL to return status and result of the request. + +Request payload data must be allocated separately and is passed in via the +``payload.data`` and ``payload.length`` members. If a response is required, +the response buffer must be allocated by the caller and passed in via the +``response.data`` member. The ``response.length`` member must be set to the +capacity of this buffer, or if no response is required, zero. Upon +completion of the request, the call will write the response to the response +buffer (if its capacity allows it) and overwrite the length field with the +actual size of the response, in bytes. + +Additionally, if the request has a response, this must be indicated via the +request flags, as is done with in-kernel requests. Request flags can be set +via the ``flags`` member and the values correspond to the values found in +|ssam_cdev_request_flags|. + +Finally, the status of the request itself is returned in the ``status`` +member (a negative errno value indicating failure). Note that failure +indication of the IOCTL is separated from failure indication of the request: +The IOCTL returns a negative status code if anything failed during setup of +the request (``-EFAULT``) or if the provided argument or any of its fields +are invalid (``-EINVAL``). In this case, the status value of the request +argument may be set, providing more detail on what went wrong (e.g. +``-ENOMEM`` for out-of-memory), but this value may also be zero. The IOCTL +will return with a zero status code in case the request has been set up, +submitted, and completed (i.e. handed back to user-space) successfully from +inside the IOCTL, but the request ``status`` member may still be negative in +case the actual execution of the request failed after it has been submitted. + +A full definition of the argument struct is provided below: + +.. kernel-doc:: include/uapi/linux/surface_aggregator/cdev.h diff --git a/Documentation/driver-api/surface_aggregator/clients/index.rst b/Documentation/driver-api/surface_aggregator/clients/index.rst new file mode 100644 index 000000000000..3ccabce23271 --- /dev/null +++ b/Documentation/driver-api/surface_aggregator/clients/index.rst @@ -0,0 +1,21 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +=========================== +Client Driver Documentation +=========================== + +This is the documentation for client drivers themselves. Refer to +:doc:`../client` for documentation on how to write client drivers. + +.. toctree:: + :maxdepth: 1 + + cdev + san + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/driver-api/surface_aggregator/clients/san.rst b/Documentation/driver-api/surface_aggregator/clients/san.rst new file mode 100644 index 000000000000..38c2580e7758 --- /dev/null +++ b/Documentation/driver-api/surface_aggregator/clients/san.rst @@ -0,0 +1,44 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. |san_client_link| replace:: :c:func:`san_client_link` +.. |san_dgpu_notifier_register| replace:: :c:func:`san_dgpu_notifier_register` +.. |san_dgpu_notifier_unregister| replace:: :c:func:`san_dgpu_notifier_unregister` + +=================== +Surface ACPI Notify +=================== + +The Surface ACPI Notify (SAN) device provides the bridge between ACPI and +SAM controller. Specifically, ACPI code can execute requests and handle +battery and thermal events via this interface. In addition to this, events +relating to the discrete GPU (dGPU) of the Surface Book 2 can be sent from +ACPI code (note: the Surface Book 3 uses a different method for this). The +only currently known event sent via this interface is a dGPU power-on +notification. While this driver handles the former part internally, it only +relays the dGPU events to any other driver interested via its public API and +does not handle them. + +The public interface of this driver is split into two parts: Client +registration and notifier-block registration. + +A client to the SAN interface can be linked as consumer to the SAN device +via |san_client_link|. This can be used to ensure that the a client +receiving dGPU events does not miss any events due to the SAN interface not +being set up as this forces the client driver to unbind once the SAN driver +is unbound. + +Notifier-blocks can be registered by any device for as long as the module is +loaded, regardless of being linked as client or not. Registration is done +with |san_dgpu_notifier_register|. If the notifier is not needed any more, it +should be unregistered via |san_dgpu_notifier_unregister|. + +Consult the API documentation below for more details. + + +API Documentation +================= + +.. kernel-doc:: include/linux/surface_acpi_notify.h + +.. kernel-doc:: drivers/platform/surface/surface_acpi_notify.c + :export: diff --git a/Documentation/driver-api/surface_aggregator/index.rst b/Documentation/driver-api/surface_aggregator/index.rst new file mode 100644 index 000000000000..6f3e1094904d --- /dev/null +++ b/Documentation/driver-api/surface_aggregator/index.rst @@ -0,0 +1,21 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +======================================= +Surface System Aggregator Module (SSAM) +======================================= + +.. toctree:: + :maxdepth: 2 + + overview + client + clients/index + ssh + internal + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/driver-api/surface_aggregator/internal-api.rst b/Documentation/driver-api/surface_aggregator/internal-api.rst new file mode 100644 index 000000000000..639a67b5a392 --- /dev/null +++ b/Documentation/driver-api/surface_aggregator/internal-api.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +========================== +Internal API Documentation +========================== + +.. contents:: + :depth: 2 + + +Packet Transport Layer +====================== + +.. kernel-doc:: drivers/platform/surface/aggregator/ssh_parser.h + :internal: + +.. kernel-doc:: drivers/platform/surface/aggregator/ssh_parser.c + :internal: + +.. kernel-doc:: drivers/platform/surface/aggregator/ssh_msgb.h + :internal: + +.. kernel-doc:: drivers/platform/surface/aggregator/ssh_packet_layer.h + :internal: + +.. kernel-doc:: drivers/platform/surface/aggregator/ssh_packet_layer.c + :internal: + + +Request Transport Layer +======================= + +.. kernel-doc:: drivers/platform/surface/aggregator/ssh_request_layer.h + :internal: + +.. kernel-doc:: drivers/platform/surface/aggregator/ssh_request_layer.c + :internal: + + +Controller +========== + +.. kernel-doc:: drivers/platform/surface/aggregator/controller.h + :internal: + +.. kernel-doc:: drivers/platform/surface/aggregator/controller.c + :internal: + + +Client Device Bus +================= + +.. kernel-doc:: drivers/platform/surface/aggregator/bus.c + :internal: + + +Core +==== + +.. kernel-doc:: drivers/platform/surface/aggregator/core.c + :internal: + + +Trace Helpers +============= + +.. kernel-doc:: drivers/platform/surface/aggregator/trace.h diff --git a/Documentation/driver-api/surface_aggregator/internal.rst b/Documentation/driver-api/surface_aggregator/internal.rst new file mode 100644 index 000000000000..72704734982a --- /dev/null +++ b/Documentation/driver-api/surface_aggregator/internal.rst @@ -0,0 +1,577 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. |ssh_ptl| replace:: :c:type:`struct ssh_ptl <ssh_ptl>` +.. |ssh_ptl_submit| replace:: :c:func:`ssh_ptl_submit` +.. |ssh_ptl_cancel| replace:: :c:func:`ssh_ptl_cancel` +.. |ssh_ptl_shutdown| replace:: :c:func:`ssh_ptl_shutdown` +.. |ssh_ptl_rx_rcvbuf| replace:: :c:func:`ssh_ptl_rx_rcvbuf` +.. |ssh_rtl| replace:: :c:type:`struct ssh_rtl <ssh_rtl>` +.. |ssh_rtl_submit| replace:: :c:func:`ssh_rtl_submit` +.. |ssh_rtl_cancel| replace:: :c:func:`ssh_rtl_cancel` +.. |ssh_rtl_shutdown| replace:: :c:func:`ssh_rtl_shutdown` +.. |ssh_packet| replace:: :c:type:`struct ssh_packet <ssh_packet>` +.. |ssh_packet_get| replace:: :c:func:`ssh_packet_get` +.. |ssh_packet_put| replace:: :c:func:`ssh_packet_put` +.. |ssh_packet_ops| replace:: :c:type:`struct ssh_packet_ops <ssh_packet_ops>` +.. |ssh_packet_base_priority| replace:: :c:type:`enum ssh_packet_base_priority <ssh_packet_base_priority>` +.. |ssh_packet_flags| replace:: :c:type:`enum ssh_packet_flags <ssh_packet_flags>` +.. |SSH_PACKET_PRIORITY| replace:: :c:func:`SSH_PACKET_PRIORITY` +.. |ssh_frame| replace:: :c:type:`struct ssh_frame <ssh_frame>` +.. |ssh_command| replace:: :c:type:`struct ssh_command <ssh_command>` +.. |ssh_request| replace:: :c:type:`struct ssh_request <ssh_request>` +.. |ssh_request_get| replace:: :c:func:`ssh_request_get` +.. |ssh_request_put| replace:: :c:func:`ssh_request_put` +.. |ssh_request_ops| replace:: :c:type:`struct ssh_request_ops <ssh_request_ops>` +.. |ssh_request_init| replace:: :c:func:`ssh_request_init` +.. |ssh_request_flags| replace:: :c:type:`enum ssh_request_flags <ssh_request_flags>` +.. |ssam_controller| replace:: :c:type:`struct ssam_controller <ssam_controller>` +.. |ssam_device| replace:: :c:type:`struct ssam_device <ssam_device>` +.. |ssam_device_driver| replace:: :c:type:`struct ssam_device_driver <ssam_device_driver>` +.. |ssam_client_bind| replace:: :c:func:`ssam_client_bind` +.. |ssam_client_link| replace:: :c:func:`ssam_client_link` +.. |ssam_request_sync| replace:: :c:type:`struct ssam_request_sync <ssam_request_sync>` +.. |ssam_event_registry| replace:: :c:type:`struct ssam_event_registry <ssam_event_registry>` +.. |ssam_event_id| replace:: :c:type:`struct ssam_event_id <ssam_event_id>` +.. |ssam_nf| replace:: :c:type:`struct ssam_nf <ssam_nf>` +.. |ssam_nf_refcount_inc| replace:: :c:func:`ssam_nf_refcount_inc` +.. |ssam_nf_refcount_dec| replace:: :c:func:`ssam_nf_refcount_dec` +.. |ssam_notifier_register| replace:: :c:func:`ssam_notifier_register` +.. |ssam_notifier_unregister| replace:: :c:func:`ssam_notifier_unregister` +.. |ssam_cplt| replace:: :c:type:`struct ssam_cplt <ssam_cplt>` +.. |ssam_event_queue| replace:: :c:type:`struct ssam_event_queue <ssam_event_queue>` +.. |ssam_request_sync_submit| replace:: :c:func:`ssam_request_sync_submit` + +===================== +Core Driver Internals +===================== + +Architectural overview of the Surface System Aggregator Module (SSAM) core +and Surface Serial Hub (SSH) driver. For the API documentation, refer to: + +.. toctree:: + :maxdepth: 2 + + internal-api + + +Overview +======== + +The SSAM core implementation is structured in layers, somewhat following the +SSH protocol structure: + +Lower-level packet transport is implemented in the *packet transport layer +(PTL)*, directly building on top of the serial device (serdev) +infrastructure of the kernel. As the name indicates, this layer deals with +the packet transport logic and handles things like packet validation, packet +acknowledgment (ACKing), packet (retransmission) timeouts, and relaying +packet payloads to higher-level layers. + +Above this sits the *request transport layer (RTL)*. This layer is centered +around command-type packet payloads, i.e. requests (sent from host to EC), +responses of the EC to those requests, and events (sent from EC to host). +It, specifically, distinguishes events from request responses, matches +responses to their corresponding requests, and implements request timeouts. + +The *controller* layer is building on top of this and essentially decides +how request responses and, especially, events are dealt with. It provides an +event notifier system, handles event activation/deactivation, provides a +workqueue for event and asynchronous request completion, and also manages +the message counters required for building command messages (``SEQ``, +``RQID``). This layer basically provides a fundamental interface to the SAM +EC for use in other kernel drivers. + +While the controller layer already provides an interface for other kernel +drivers, the client *bus* extends this interface to provide support for +native SSAM devices, i.e. devices that are not defined in ACPI and not +implemented as platform devices, via |ssam_device| and |ssam_device_driver| +simplify management of client devices and client drivers. + +Refer to :doc:`client` for documentation regarding the client device/driver +API and interface options for other kernel drivers. It is recommended to +familiarize oneself with that chapter and the :doc:`ssh` before continuing +with the architectural overview below. + + +Packet Transport Layer +====================== + +The packet transport layer is represented via |ssh_ptl| and is structured +around the following key concepts: + +Packets +------- + +Packets are the fundamental transmission unit of the SSH protocol. They are +managed by the packet transport layer, which is essentially the lowest layer +of the driver and is built upon by other components of the SSAM core. +Packets to be transmitted by the SSAM core are represented via |ssh_packet| +(in contrast, packets received by the core do not have any specific +structure and are managed entirely via the raw |ssh_frame|). + +This structure contains the required fields to manage the packet inside the +transport layer, as well as a reference to the buffer containing the data to +be transmitted (i.e. the message wrapped in |ssh_frame|). Most notably, it +contains an internal reference count, which is used for managing its +lifetime (accessible via |ssh_packet_get| and |ssh_packet_put|). When this +counter reaches zero, the ``release()`` callback provided to the packet via +its |ssh_packet_ops| reference is executed, which may then deallocate the +packet or its enclosing structure (e.g. |ssh_request|). + +In addition to the ``release`` callback, the |ssh_packet_ops| reference also +provides a ``complete()`` callback, which is run once the packet has been +completed and provides the status of this completion, i.e. zero on success +or a negative errno value in case of an error. Once the packet has been +submitted to the packet transport layer, the ``complete()`` callback is +always guaranteed to be executed before the ``release()`` callback, i.e. the +packet will always be completed, either successfully, with an error, or due +to cancellation, before it will be released. + +The state of a packet is managed via its ``state`` flags +(|ssh_packet_flags|), which also contains the packet type. In particular, +the following bits are noteworthy: + +* ``SSH_PACKET_SF_LOCKED_BIT``: This bit is set when completion, either + through error or success, is imminent. It indicates that no further + references of the packet should be taken and any existing references + should be dropped as soon as possible. The process setting this bit is + responsible for removing any references to this packet from the packet + queue and pending set. + +* ``SSH_PACKET_SF_COMPLETED_BIT``: This bit is set by the process running the + ``complete()`` callback and is used to ensure that this callback only runs + once. + +* ``SSH_PACKET_SF_QUEUED_BIT``: This bit is set when the packet is queued on + the packet queue and cleared when it is dequeued. + +* ``SSH_PACKET_SF_PENDING_BIT``: This bit is set when the packet is added to + the pending set and cleared when it is removed from it. + +Packet Queue +------------ + +The packet queue is the first of the two fundamental collections in the +packet transport layer. It is a priority queue, with priority of the +respective packets based on the packet type (major) and number of tries +(minor). See |SSH_PACKET_PRIORITY| for more details on the priority value. + +All packets to be transmitted by the transport layer must be submitted to +this queue via |ssh_ptl_submit|. Note that this includes control packets +sent by the transport layer itself. Internally, data packets can be +re-submitted to this queue due to timeouts or NAK packets sent by the EC. + +Pending Set +----------- + +The pending set is the second of the two fundamental collections in the +packet transport layer. It stores references to packets that have already +been transmitted, but wait for acknowledgment (e.g. the corresponding ACK +packet) by the EC. + +Note that a packet may both be pending and queued if it has been +re-submitted due to a packet acknowledgment timeout or NAK. On such a +re-submission, packets are not removed from the pending set. + +Transmitter Thread +------------------ + +The transmitter thread is responsible for most of the actual work regarding +packet transmission. In each iteration, it (waits for and) checks if the +next packet on the queue (if any) can be transmitted and, if so, removes it +from the queue and increments its counter for the number of transmission +attempts, i.e. tries. If the packet is sequenced, i.e. requires an ACK by +the EC, the packet is added to the pending set. Next, the packet's data is +submitted to the serdev subsystem. In case of an error or timeout during +this submission, the packet is completed by the transmitter thread with the +status value of the callback set accordingly. In case the packet is +unsequenced, i.e. does not require an ACK by the EC, the packet is completed +with success on the transmitter thread. + +Transmission of sequenced packets is limited by the number of concurrently +pending packets, i.e. a limit on how many packets may be waiting for an ACK +from the EC in parallel. This limit is currently set to one (see :doc:`ssh` +for the reasoning behind this). Control packets (i.e. ACK and NAK) can +always be transmitted. + +Receiver Thread +--------------- + +Any data received from the EC is put into a FIFO buffer for further +processing. This processing happens on the receiver thread. The receiver +thread parses and validates the received message into its |ssh_frame| and +corresponding payload. It prepares and submits the necessary ACK (and on +validation error or invalid data NAK) packets for the received messages. + +This thread also handles further processing, such as matching ACK messages +to the corresponding pending packet (via sequence ID) and completing it, as +well as initiating re-submission of all currently pending packets on +receival of a NAK message (re-submission in case of a NAK is similar to +re-submission due to timeout, see below for more details on that). Note that +the successful completion of a sequenced packet will always run on the +receiver thread (whereas any failure-indicating completion will run on the +process where the failure occurred). + +Any payload data is forwarded via a callback to the next upper layer, i.e. +the request transport layer. + +Timeout Reaper +-------------- + +The packet acknowledgment timeout is a per-packet timeout for sequenced +packets, started when the respective packet begins (re-)transmission (i.e. +this timeout is armed once per transmission attempt on the transmitter +thread). It is used to trigger re-submission or, when the number of tries +has been exceeded, cancellation of the packet in question. + +This timeout is handled via a dedicated reaper task, which is essentially a +work item (re-)scheduled to run when the next packet is set to time out. The +work item then checks the set of pending packets for any packets that have +exceeded the timeout and, if there are any remaining packets, re-schedules +itself to the next appropriate point in time. + +If a timeout has been detected by the reaper, the packet will either be +re-submitted if it still has some remaining tries left, or completed with +``-ETIMEDOUT`` as status if not. Note that re-submission, in this case and +triggered by receival of a NAK, means that the packet is added to the queue +with a now incremented number of tries, yielding a higher priority. The +timeout for the packet will be disabled until the next transmission attempt +and the packet remains on the pending set. + +Note that due to transmission and packet acknowledgment timeouts, the packet +transport layer is always guaranteed to make progress, if only through +timing out packets, and will never fully block. + +Concurrency and Locking +----------------------- + +There are two main locks in the packet transport layer: One guarding access +to the packet queue and one guarding access to the pending set. These +collections may only be accessed and modified under the respective lock. If +access to both collections is needed, the pending lock must be acquired +before the queue lock to avoid deadlocks. + +In addition to guarding the collections, after initial packet submission +certain packet fields may only be accessed under one of the locks. +Specifically, the packet priority must only be accessed while holding the +queue lock and the packet timestamp must only be accessed while holding the +pending lock. + +Other parts of the packet transport layer are guarded independently. State +flags are managed by atomic bit operations and, if necessary, memory +barriers. Modifications to the timeout reaper work item and expiration date +are guarded by their own lock. + +The reference of the packet to the packet transport layer (``ptl``) is +somewhat special. It is either set when the upper layer request is submitted +or, if there is none, when the packet is first submitted. After it is set, +it will not change its value. Functions that may run concurrently with +submission, i.e. cancellation, can not rely on the ``ptl`` reference to be +set. Access to it in these functions is guarded by ``READ_ONCE()``, whereas +setting ``ptl`` is equally guarded with ``WRITE_ONCE()`` for symmetry. + +Some packet fields may be read outside of the respective locks guarding +them, specifically priority and state for tracing. In those cases, proper +access is ensured by employing ``WRITE_ONCE()`` and ``READ_ONCE()``. Such +read-only access is only allowed when stale values are not critical. + +With respect to the interface for higher layers, packet submission +(|ssh_ptl_submit|), packet cancellation (|ssh_ptl_cancel|), data receival +(|ssh_ptl_rx_rcvbuf|), and layer shutdown (|ssh_ptl_shutdown|) may always be +executed concurrently with respect to each other. Note that packet +submission may not run concurrently with itself for the same packet. +Equally, shutdown and data receival may also not run concurrently with +themselves (but may run concurrently with each other). + + +Request Transport Layer +======================= + +The request transport layer is represented via |ssh_rtl| and builds on top +of the packet transport layer. It deals with requests, i.e. SSH packets sent +by the host containing a |ssh_command| as frame payload. This layer +separates responses to requests from events, which are also sent by the EC +via a |ssh_command| payload. While responses are handled in this layer, +events are relayed to the next upper layer, i.e. the controller layer, via +the corresponding callback. The request transport layer is structured around +the following key concepts: + +Request +------- + +Requests are packets with a command-type payload, sent from host to EC to +query data from or trigger an action on it (or both simultaneously). They +are represented by |ssh_request|, wrapping the underlying |ssh_packet| +storing its message data (i.e. SSH frame with command payload). Note that +all top-level representations, e.g. |ssam_request_sync| are built upon this +struct. + +As |ssh_request| extends |ssh_packet|, its lifetime is also managed by the +reference counter inside the packet struct (which can be accessed via +|ssh_request_get| and |ssh_request_put|). Once the counter reaches zero, the +``release()`` callback of the |ssh_request_ops| reference of the request is +called. + +Requests can have an optional response that is equally sent via a SSH +message with command-type payload (from EC to host). The party constructing +the request must know if a response is expected and mark this in the request +flags provided to |ssh_request_init|, so that the request transport layer +can wait for this response. + +Similar to |ssh_packet|, |ssh_request| also has a ``complete()`` callback +provided via its request ops reference and is guaranteed to be completed +before it is released once it has been submitted to the request transport +layer via |ssh_rtl_submit|. For a request without a response, successful +completion will occur once the underlying packet has been successfully +transmitted by the packet transport layer (i.e. from within the packet +completion callback). For a request with response, successful completion +will occur once the response has been received and matched to the request +via its request ID (which happens on the packet layer's data-received +callback running on the receiver thread). If the request is completed with +an error, the status value will be set to the corresponding (negative) errno +value. + +The state of a request is again managed via its ``state`` flags +(|ssh_request_flags|), which also encode the request type. In particular, +the following bits are noteworthy: + +* ``SSH_REQUEST_SF_LOCKED_BIT``: This bit is set when completion, either + through error or success, is imminent. It indicates that no further + references of the request should be taken and any existing references + should be dropped as soon as possible. The process setting this bit is + responsible for removing any references to this request from the request + queue and pending set. + +* ``SSH_REQUEST_SF_COMPLETED_BIT``: This bit is set by the process running the + ``complete()`` callback and is used to ensure that this callback only runs + once. + +* ``SSH_REQUEST_SF_QUEUED_BIT``: This bit is set when the request is queued on + the request queue and cleared when it is dequeued. + +* ``SSH_REQUEST_SF_PENDING_BIT``: This bit is set when the request is added to + the pending set and cleared when it is removed from it. + +Request Queue +------------- + +The request queue is the first of the two fundamental collections in the +request transport layer. In contrast to the packet queue of the packet +transport layer, it is not a priority queue and the simple first come first +serve principle applies. + +All requests to be transmitted by the request transport layer must be +submitted to this queue via |ssh_rtl_submit|. Once submitted, requests may +not be re-submitted, and will not be re-submitted automatically on timeout. +Instead, the request is completed with a timeout error. If desired, the +caller can create and submit a new request for another try, but it must not +submit the same request again. + +Pending Set +----------- + +The pending set is the second of the two fundamental collections in the +request transport layer. This collection stores references to all pending +requests, i.e. requests awaiting a response from the EC (similar to what the +pending set of the packet transport layer does for packets). + +Transmitter Task +---------------- + +The transmitter task is scheduled when a new request is available for +transmission. It checks if the next request on the request queue can be +transmitted and, if so, submits its underlying packet to the packet +transport layer. This check ensures that only a limited number of +requests can be pending, i.e. waiting for a response, at the same time. If +the request requires a response, the request is added to the pending set +before its packet is submitted. + +Packet Completion Callback +-------------------------- + +The packet completion callback is executed once the underlying packet of a +request has been completed. In case of an error completion, the +corresponding request is completed with the error value provided in this +callback. + +On successful packet completion, further processing depends on the request. +If the request expects a response, it is marked as transmitted and the +request timeout is started. If the request does not expect a response, it is +completed with success. + +Data-Received Callback +---------------------- + +The data received callback notifies the request transport layer of data +being received by the underlying packet transport layer via a data-type +frame. In general, this is expected to be a command-type payload. + +If the request ID of the command is one of the request IDs reserved for +events (one to ``SSH_NUM_EVENTS``, inclusively), it is forwarded to the +event callback registered in the request transport layer. If the request ID +indicates a response to a request, the respective request is looked up in +the pending set and, if found and marked as transmitted, completed with +success. + +Timeout Reaper +-------------- + +The request-response-timeout is a per-request timeout for requests expecting +a response. It is used to ensure that a request does not wait indefinitely +on a response from the EC and is started after the underlying packet has +been successfully completed. + +This timeout is, similar to the packet acknowledgment timeout on the packet +transport layer, handled via a dedicated reaper task. This task is +essentially a work-item (re-)scheduled to run when the next request is set +to time out. The work item then scans the set of pending requests for any +requests that have timed out and completes them with ``-ETIMEDOUT`` as +status. Requests will not be re-submitted automatically. Instead, the issuer +of the request must construct and submit a new request, if so desired. + +Note that this timeout, in combination with packet transmission and +acknowledgment timeouts, guarantees that the request layer will always make +progress, even if only through timing out packets, and never fully block. + +Concurrency and Locking +----------------------- + +Similar to the packet transport layer, there are two main locks in the +request transport layer: One guarding access to the request queue and one +guarding access to the pending set. These collections may only be accessed +and modified under the respective lock. + +Other parts of the request transport layer are guarded independently. State +flags are (again) managed by atomic bit operations and, if necessary, memory +barriers. Modifications to the timeout reaper work item and expiration date +are guarded by their own lock. + +Some request fields may be read outside of the respective locks guarding +them, specifically the state for tracing. In those cases, proper access is +ensured by employing ``WRITE_ONCE()`` and ``READ_ONCE()``. Such read-only +access is only allowed when stale values are not critical. + +With respect to the interface for higher layers, request submission +(|ssh_rtl_submit|), request cancellation (|ssh_rtl_cancel|), and layer +shutdown (|ssh_rtl_shutdown|) may always be executed concurrently with +respect to each other. Note that request submission may not run concurrently +with itself for the same request (and also may only be called once per +request). Equally, shutdown may also not run concurrently with itself. + + +Controller Layer +================ + +The controller layer extends on the request transport layer to provide an +easy-to-use interface for client drivers. It is represented by +|ssam_controller| and the SSH driver. While the lower level transport layers +take care of transmitting and handling packets and requests, the controller +layer takes on more of a management role. Specifically, it handles device +initialization, power management, and event handling, including event +delivery and registration via the (event) completion system (|ssam_cplt|). + +Event Registration +------------------ + +In general, an event (or rather a class of events) has to be explicitly +requested by the host before the EC will send it (HID input events seem to +be the exception). This is done via an event-enable request (similarly, +events should be disabled via an event-disable request once no longer +desired). + +The specific request used to enable (or disable) an event is given via an +event registry, i.e. the governing authority of this event (so to speak), +represented by |ssam_event_registry|. As parameters to this request, the +target category and, depending on the event registry, instance ID of the +event to be enabled must be provided. This (optional) instance ID must be +zero if the registry does not use it. Together, target category and instance +ID form the event ID, represented by |ssam_event_id|. In short, both, event +registry and event ID, are required to uniquely identify a respective class +of events. + +Note that a further *request ID* parameter must be provided for the +enable-event request. This parameter does not influence the class of events +being enabled, but instead is set as the request ID (RQID) on each event of +this class sent by the EC. It is used to identify events (as a limited +number of request IDs is reserved for use in events only, specifically one +to ``SSH_NUM_EVENTS`` inclusively) and also map events to their specific +class. Currently, the controller always sets this parameter to the target +category specified in |ssam_event_id|. + +As multiple client drivers may rely on the same (or overlapping) classes of +events and enable/disable calls are strictly binary (i.e. on/off), the +controller has to manage access to these events. It does so via reference +counting, storing the counter inside an RB-tree based mapping with event +registry and ID as key (there is no known list of valid event registry and +event ID combinations). See |ssam_nf|, |ssam_nf_refcount_inc|, and +|ssam_nf_refcount_dec| for details. + +This management is done together with notifier registration (described in +the next section) via the top-level |ssam_notifier_register| and +|ssam_notifier_unregister| functions. + +Event Delivery +-------------- + +To receive events, a client driver has to register an event notifier via +|ssam_notifier_register|. This increments the reference counter for that +specific class of events (as detailed in the previous section), enables the +class on the EC (if it has not been enabled already), and installs the +provided notifier callback. + +Notifier callbacks are stored in lists, with one (RCU) list per target +category (provided via the event ID; NB: there is a fixed known number of +target categories). There is no known association from the combination of +event registry and event ID to the command data (target ID, target category, +command ID, and instance ID) that can be provided by an event class, apart +from target category and instance ID given via the event ID. + +Note that due to the way notifiers are (or rather have to be) stored, client +drivers may receive events that they have not requested and need to account +for them. Specifically, they will, by default, receive all events from the +same target category. To simplify dealing with this, filtering of events by +target ID (provided via the event registry) and instance ID (provided via +the event ID) can be requested when registering a notifier. This filtering +is applied when iterating over the notifiers at the time they are executed. + +All notifier callbacks are executed on a dedicated workqueue, the so-called +completion workqueue. After an event has been received via the callback +installed in the request layer (running on the receiver thread of the packet +transport layer), it will be put on its respective event queue +(|ssam_event_queue|). From this event queue the completion work item of that +queue (running on the completion workqueue) will pick up the event and +execute the notifier callback. This is done to avoid blocking on the +receiver thread. + +There is one event queue per combination of target ID and target category. +This is done to ensure that notifier callbacks are executed in sequence for +events of the same target ID and target category. Callbacks can be executed +in parallel for events with a different combination of target ID and target +category. + +Concurrency and Locking +----------------------- + +Most of the concurrency related safety guarantees of the controller are +provided by the lower-level request transport layer. In addition to this, +event (un-)registration is guarded by its own lock. + +Access to the controller state is guarded by the state lock. This lock is a +read/write semaphore. The reader part can be used to ensure that the state +does not change while functions depending on the state to stay the same +(e.g. |ssam_notifier_register|, |ssam_notifier_unregister|, +|ssam_request_sync_submit|, and derivatives) are executed and this guarantee +is not already provided otherwise (e.g. through |ssam_client_bind| or +|ssam_client_link|). The writer part guards any transitions that will change +the state, i.e. initialization, destruction, suspension, and resumption. + +The controller state may be accessed (read-only) outside the state lock for +smoke-testing against invalid API usage (e.g. in |ssam_request_sync_submit|). +Note that such checks are not supposed to (and will not) protect against all +invalid usages, but rather aim to help catch them. In those cases, proper +variable access is ensured by employing ``WRITE_ONCE()`` and ``READ_ONCE()``. + +Assuming any preconditions on the state not changing have been satisfied, +all non-initialization and non-shutdown functions may run concurrently with +each other. This includes |ssam_notifier_register|, |ssam_notifier_unregister|, +|ssam_request_sync_submit|, as well as all functions building on top of those. diff --git a/Documentation/driver-api/surface_aggregator/overview.rst b/Documentation/driver-api/surface_aggregator/overview.rst new file mode 100644 index 000000000000..1e9d57e50063 --- /dev/null +++ b/Documentation/driver-api/surface_aggregator/overview.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +======== +Overview +======== + +The Surface/System Aggregator Module (SAM, SSAM) is an (arguably *the*) +embedded controller (EC) on Microsoft Surface devices. It has been originally +introduced on 4th generation devices (Surface Pro 4, Surface Book 1), but +its responsibilities and feature-set have since been expanded significantly +with the following generations. + + +Features and Integration +======================== + +Not much is currently known about SAM on 4th generation devices (Surface Pro +4, Surface Book 1), due to the use of a different communication interface +between host and EC (as detailed below). On 5th (Surface Pro 2017, Surface +Book 2, Surface Laptop 1) and later generation devices, SAM is responsible +for providing battery information (both current status and static values, +such as maximum capacity etc.), as well as an assortment of temperature +sensors (e.g. skin temperature) and cooling/performance-mode setting to the +host. On the Surface Book 2, specifically, it additionally provides an +interface for properly handling clipboard detachment (i.e. separating the +display part from the keyboard part of the device), on the Surface Laptop 1 +and 2 it is required for keyboard HID input. This HID subsystem has been +restructured for 7th generation devices and on those, specifically Surface +Laptop 3 and Surface Book 3, is responsible for all major HID input (i.e. +keyboard and touchpad). + +While features have not changed much on a coarse level since the 5th +generation, internal interfaces have undergone some rather large changes. On +5th and 6th generation devices, both battery and temperature information is +exposed to ACPI via a shim driver (referred to as Surface ACPI Notify, or +SAN), translating ACPI generic serial bus write-/read-accesses to SAM +requests. On 7th generation devices, this additional layer is gone and these +devices require a driver hooking directly into the SAM interface. Equally, +on newer generations, less devices are declared in ACPI, making them a bit +harder to discover and requiring us to hard-code a sort of device registry. +Due to this, a SSAM bus and subsystem with client devices +(:c:type:`struct ssam_device <ssam_device>`) has been implemented. + + +Communication +============= + +The type of communication interface between host and EC depends on the +generation of the Surface device. On 4th generation devices, host and EC +communicate via HID, specifically using a HID-over-I2C device, whereas on +5th and later generations, communication takes place via a USART serial +device. In accordance to the drivers found on other operating systems, we +refer to the serial device and its driver as Surface Serial Hub (SSH). When +needed, we differentiate between both types of SAM by referring to them as +SAM-over-SSH and SAM-over-HID. + +Currently, this subsystem only supports SAM-over-SSH. The SSH communication +interface is described in more detail below. The HID interface has not been +reverse engineered yet and it is, at the moment, unclear how many (and +which) concepts of the SSH interface detailed below can be transferred to +it. + +Surface Serial Hub +------------------ + +As already elaborated above, the Surface Serial Hub (SSH) is the +communication interface for SAM on 5th- and all later-generation Surface +devices. On the highest level, communication can be separated into two main +types: Requests, messages sent from host to EC that may trigger a direct +response from the EC (explicitly associated with the request), and events +(sometimes also referred to as notifications), sent from EC to host without +being a direct response to a previous request. We may also refer to requests +without response as commands. In general, events need to be enabled via one +of multiple dedicated requests before they are sent by the EC. + +See :doc:`ssh` for a more technical protocol documentation and +:doc:`internal` for an overview of the internal driver architecture. diff --git a/Documentation/driver-api/surface_aggregator/ssh.rst b/Documentation/driver-api/surface_aggregator/ssh.rst new file mode 100644 index 000000000000..bf007d6c9873 --- /dev/null +++ b/Documentation/driver-api/surface_aggregator/ssh.rst @@ -0,0 +1,344 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. |u8| replace:: :c:type:`u8 <u8>` +.. |u16| replace:: :c:type:`u16 <u16>` +.. |TYPE| replace:: ``TYPE`` +.. |LEN| replace:: ``LEN`` +.. |SEQ| replace:: ``SEQ`` +.. |SYN| replace:: ``SYN`` +.. |NAK| replace:: ``NAK`` +.. |ACK| replace:: ``ACK`` +.. |DATA| replace:: ``DATA`` +.. |DATA_SEQ| replace:: ``DATA_SEQ`` +.. |DATA_NSQ| replace:: ``DATA_NSQ`` +.. |TC| replace:: ``TC`` +.. |TID| replace:: ``TID`` +.. |IID| replace:: ``IID`` +.. |RQID| replace:: ``RQID`` +.. |CID| replace:: ``CID`` + +=========================== +Surface Serial Hub Protocol +=========================== + +The Surface Serial Hub (SSH) is the central communication interface for the +embedded Surface Aggregator Module controller (SAM or EC), found on newer +Surface generations. We will refer to this protocol and interface as +SAM-over-SSH, as opposed to SAM-over-HID for the older generations. + +On Surface devices with SAM-over-SSH, SAM is connected to the host via UART +and defined in ACPI as device with ID ``MSHW0084``. On these devices, +significant functionality is provided via SAM, including access to battery +and power information and events, thermal read-outs and events, and many +more. For Surface Laptops, keyboard input is handled via HID directed +through SAM, on the Surface Laptop 3 and Surface Book 3 this also includes +touchpad input. + +Note that the standard disclaimer for this subsystem also applies to this +document: All of this has been reverse-engineered and may thus be erroneous +and/or incomplete. + +All CRCs used in the following are two-byte ``crc_ccitt_false(0xffff, ...)``. +All multi-byte values are little-endian, there is no implicit padding between +values. + + +SSH Packet Protocol: Definitions +================================ + +The fundamental communication unit of the SSH protocol is a frame +(:c:type:`struct ssh_frame <ssh_frame>`). A frame consists of the following +fields, packed together and in order: + +.. flat-table:: SSH Frame + :widths: 1 1 4 + :header-rows: 1 + + * - Field + - Type + - Description + + * - |TYPE| + - |u8| + - Type identifier of the frame. + + * - |LEN| + - |u16| + - Length of the payload associated with the frame. + + * - |SEQ| + - |u8| + - Sequence ID (see explanation below). + +Each frame structure is followed by a CRC over this structure. The CRC over +the frame structure (|TYPE|, |LEN|, and |SEQ| fields) is placed directly +after the frame structure and before the payload. The payload is followed by +its own CRC (over all payload bytes). If the payload is not present (i.e. +the frame has ``LEN=0``), the CRC of the payload is still present and will +evaluate to ``0xffff``. The |LEN| field does not include any of the CRCs, it +equals the number of bytes inbetween the CRC of the frame and the CRC of the +payload. + +Additionally, the following fixed two-byte sequences are used: + +.. flat-table:: SSH Byte Sequences + :widths: 1 1 4 + :header-rows: 1 + + * - Name + - Value + - Description + + * - |SYN| + - ``[0xAA, 0x55]`` + - Synchronization bytes. + +A message consists of |SYN|, followed by the frame (|TYPE|, |LEN|, |SEQ| and +CRC) and, if specified in the frame (i.e. ``LEN > 0``), payload bytes, +followed finally, regardless if the payload is present, the payload CRC. The +messages corresponding to an exchange are, in part, identified by having the +same sequence ID (|SEQ|), stored inside the frame (more on this in the next +section). The sequence ID is a wrapping counter. + +A frame can have the following types +(:c:type:`enum ssh_frame_type <ssh_frame_type>`): + +.. flat-table:: SSH Frame Types + :widths: 1 1 4 + :header-rows: 1 + + * - Name + - Value + - Short Description + + * - |NAK| + - ``0x04`` + - Sent on error in previously received message. + + * - |ACK| + - ``0x40`` + - Sent to acknowledge receival of |DATA| frame. + + * - |DATA_SEQ| + - ``0x80`` + - Sent to transfer data. Sequenced. + + * - |DATA_NSQ| + - ``0x00`` + - Same as |DATA_SEQ|, but does not need to be ACKed. + +Both |NAK|- and |ACK|-type frames are used to control flow of messages and +thus do not carry a payload. |DATA_SEQ|- and |DATA_NSQ|-type frames on the +other hand must carry a payload. The flow sequence and interaction of +different frame types will be described in more depth in the next section. + + +SSH Packet Protocol: Flow Sequence +================================== + +Each exchange begins with |SYN|, followed by a |DATA_SEQ|- or +|DATA_NSQ|-type frame, followed by its CRC, payload, and payload CRC. In +case of a |DATA_NSQ|-type frame, the exchange is then finished. In case of a +|DATA_SEQ|-type frame, the receiving party has to acknowledge receival of +the frame by responding with a message containing an |ACK|-type frame with +the same sequence ID of the |DATA| frame. In other words, the sequence ID of +the |ACK| frame specifies the |DATA| frame to be acknowledged. In case of an +error, e.g. an invalid CRC, the receiving party responds with a message +containing an |NAK|-type frame. As the sequence ID of the previous data +frame, for which an error is indicated via the |NAK| frame, cannot be relied +upon, the sequence ID of the |NAK| frame should not be used and is set to +zero. After receival of an |NAK| frame, the sending party should re-send all +outstanding (non-ACKed) messages. + +Sequence IDs are not synchronized between the two parties, meaning that they +are managed independently for each party. Identifying the messages +corresponding to a single exchange thus relies on the sequence ID as well as +the type of the message, and the context. Specifically, the sequence ID is +used to associate an ``ACK`` with its ``DATA_SEQ``-type frame, but not +``DATA_SEQ``- or ``DATA_NSQ``-type frames with other ``DATA``- type frames. + +An example exchange might look like this: + +:: + + tx: -- SYN FRAME(D) CRC(F) PAYLOAD CRC(P) ----------------------------- + rx: ------------------------------------- SYN FRAME(A) CRC(F) CRC(P) -- + +where both frames have the same sequence ID (``SEQ``). Here, ``FRAME(D)`` +indicates a |DATA_SEQ|-type frame, ``FRAME(A)`` an ``ACK``-type frame, +``CRC(F)`` the CRC over the previous frame, ``CRC(P)`` the CRC over the +previous payload. In case of an error, the exchange would look like this: + +:: + + tx: -- SYN FRAME(D) CRC(F) PAYLOAD CRC(P) ----------------------------- + rx: ------------------------------------- SYN FRAME(N) CRC(F) CRC(P) -- + +upon which the sender should re-send the message. ``FRAME(N)`` indicates an +|NAK|-type frame. Note that the sequence ID of the |NAK|-type frame is fixed +to zero. For |DATA_NSQ|-type frames, both exchanges are the same: + +:: + + tx: -- SYN FRAME(DATA_NSQ) CRC(F) PAYLOAD CRC(P) ---------------------- + rx: ------------------------------------------------------------------- + +Here, an error can be detected, but not corrected or indicated to the +sending party. These exchanges are symmetric, i.e. switching ``rx`` and +``tx`` results again in a valid exchange. Currently, no longer exchanges are +known. + + +Commands: Requests, Responses, and Events +========================================= + +Commands are sent as payload inside a data frame. Currently, this is the +only known payload type of |DATA| frames, with a payload-type value of +``0x80`` (:c:type:`SSH_PLD_TYPE_CMD <ssh_payload_type>`). + +The command-type payload (:c:type:`struct ssh_command <ssh_command>`) +consists of an eight-byte command structure, followed by optional and +variable length command data. The length of this optional data is derived +from the frame payload length given in the corresponding frame, i.e. it is +``frame.len - sizeof(struct ssh_command)``. The command struct contains the +following fields, packed together and in order: + +.. flat-table:: SSH Command + :widths: 1 1 4 + :header-rows: 1 + + * - Field + - Type + - Description + + * - |TYPE| + - |u8| + - Type of the payload. For commands always ``0x80``. + + * - |TC| + - |u8| + - Target category. + + * - |TID| (out) + - |u8| + - Target ID for outgoing (host to EC) commands. + + * - |TID| (in) + - |u8| + - Target ID for incoming (EC to host) commands. + + * - |IID| + - |u8| + - Instance ID. + + * - |RQID| + - |u16| + - Request ID. + + * - |CID| + - |u8| + - Command ID. + +The command struct and data, in general, does not contain any failure +detection mechanism (e.g. CRCs), this is solely done on the frame level. + +Command-type payloads are used by the host to send commands and requests to +the EC as well as by the EC to send responses and events back to the host. +We differentiate between requests (sent by the host), responses (sent by the +EC in response to a request), and events (sent by the EC without a preceding +request). + +Commands and events are uniquely identified by their target category +(``TC``) and command ID (``CID``). The target category specifies a general +category for the command (e.g. system in general, vs. battery and AC, vs. +temperature, and so on), while the command ID specifies the command inside +that category. Only the combination of |TC| + |CID| is unique. Additionally, +commands have an instance ID (``IID``), which is used to differentiate +between different sub-devices. For example ``TC=3`` ``CID=1`` is a +request to get the temperature on a thermal sensor, where |IID| specifies +the respective sensor. If the instance ID is not used, it should be set to +zero. If instance IDs are used, they, in general, start with a value of one, +whereas zero may be used for instance independent queries, if applicable. A +response to a request should have the same target category, command ID, and +instance ID as the corresponding request. + +Responses are matched to their corresponding request via the request ID +(``RQID``) field. This is a 16 bit wrapping counter similar to the sequence +ID on the frames. Note that the sequence ID of the frames for a +request-response pair does not match. Only the request ID has to match. +Frame-protocol wise these are two separate exchanges, and may even be +separated, e.g. by an event being sent after the request but before the +response. Not all commands produce a response, and this is not detectable by +|TC| + |CID|. It is the responsibility of the issuing party to wait for a +response (or signal this to the communication framework, as is done in +SAN/ACPI via the ``SNC`` flag). + +Events are identified by unique and reserved request IDs. These IDs should +not be used by the host when sending a new request. They are used on the +host to, first, detect events and, second, match them with a registered +event handler. Request IDs for events are chosen by the host and directed to +the EC when setting up and enabling an event source (via the +enable-event-source request). The EC then uses the specified request ID for +events sent from the respective source. Note that an event should still be +identified by its target category, command ID, and, if applicable, instance +ID, as a single event source can send multiple different event types. In +general, however, a single target category should map to a single reserved +event request ID. + +Furthermore, requests, responses, and events have an associated target ID +(``TID``). This target ID is split into output (host to EC) and input (EC to +host) fields, with the respecting other field (e.g. output field on incoming +messages) set to zero. Two ``TID`` values are known: Primary (``0x01``) and +secondary (``0x02``). In general, the response to a request should have the +same ``TID`` value, however, the field (output vs. input) should be used in +accordance to the direction in which the response is sent (i.e. on the input +field, as responses are generally sent from the EC to the host). + +Note that, even though requests and events should be uniquely identifiable +by target category and command ID alone, the EC may require specific +target ID and instance ID values to accept a command. A command that is +accepted for ``TID=1``, for example, may not be accepted for ``TID=2`` +and vice versa. + + +Limitations and Observations +============================ + +The protocol can, in theory, handle up to ``U8_MAX`` frames in parallel, +with up to ``U16_MAX`` pending requests (neglecting request IDs reserved for +events). In practice, however, this is more limited. From our testing +(although via a python and thus a user-space program), it seems that the EC +can handle up to four requests (mostly) reliably in parallel at a certain +time. With five or more requests in parallel, consistent discarding of +commands (ACKed frame but no command response) has been observed. For five +simultaneous commands, this reproducibly resulted in one command being +dropped and four commands being handled. + +However, it has also been noted that, even with three requests in parallel, +occasional frame drops happen. Apart from this, with a limit of three +pending requests, no dropped commands (i.e. command being dropped but frame +carrying command being ACKed) have been observed. In any case, frames (and +possibly also commands) should be re-sent by the host if a certain timeout +is exceeded. This is done by the EC for frames with a timeout of one second, +up to two re-tries (i.e. three transmissions in total). The limit of +re-tries also applies to received NAKs, and, in a worst case scenario, can +lead to entire messages being dropped. + +While this also seems to work fine for pending data frames as long as no +transmission failures occur, implementation and handling of these seems to +depend on the assumption that there is only one non-acknowledged data frame. +In particular, the detection of repeated frames relies on the last sequence +number. This means that, if a frame that has been successfully received by +the EC is sent again, e.g. due to the host not receiving an |ACK|, the EC +will only detect this if it has the sequence ID of the last frame received +by the EC. As an example: Sending two frames with ``SEQ=0`` and ``SEQ=1`` +followed by a repetition of ``SEQ=0`` will not detect the second ``SEQ=0`` +frame as such, and thus execute the command in this frame each time it has +been received, i.e. twice in this example. Sending ``SEQ=0``, ``SEQ=1`` and +then repeating ``SEQ=1`` will detect the second ``SEQ=1`` as repetition of +the first one and ignore it, thus executing the contained command only once. + +In conclusion, this suggests a limit of at most one pending un-ACKed frame +(per party, effectively leading to synchronous communication regarding +frames) and at most three pending commands. The limit to synchronous frame +transfers seems to be consistent with behavior observed on Windows. diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index dae15c96e659..35ed01a5fbc9 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -179,7 +179,6 @@ fault_type=%d Support configuring fault injection type, should be FAULT_KVMALLOC 0x000000002 FAULT_PAGE_ALLOC 0x000000004 FAULT_PAGE_GET 0x000000008 - FAULT_ALLOC_BIO 0x000000010 FAULT_ALLOC_NID 0x000000020 FAULT_ORPHAN 0x000000040 FAULT_BLOCK 0x000000080 @@ -247,8 +246,24 @@ checkpoint=%s[:%u[%]] Set to "disable" to turn off checkpointing. Set to "enabl hide up to all remaining free space. The actual space that would be unusable can be viewed at /sys/fs/f2fs/<disk>/unusable This space is reclaimed once checkpoint=enable. +checkpoint_merge When checkpoint is enabled, this can be used to create a kernel + daemon and make it to merge concurrent checkpoint requests as + much as possible to eliminate redundant checkpoint issues. Plus, + we can eliminate the sluggish issue caused by slow checkpoint + operation when the checkpoint is done in a process context in + a cgroup having low i/o budget and cpu shares. To make this + do better, we set the default i/o priority of the kernel daemon + to "3", to give one higher priority than other kernel threads. + This is the same way to give a I/O priority to the jbd2 + journaling thread of ext4 filesystem. +nocheckpoint_merge Disable checkpoint merge feature. compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo", "lz4", "zstd" and "lzo-rle" algorithm. +compress_algorithm=%s:%d Control compress algorithm and its compress level, now, only + "lz4" and "zstd" support compress level config. + algorithm level range + lz4 3 - 16 + zstd 1 - 22 compress_log_size=%u Support configuring compress cluster size, the size will be 4KB * (1 << %u), 16KB is minimum size, also it's default size. @@ -831,7 +846,7 @@ This is the default option. f2fs does automatic compression in the writeback of compression enabled files. 2) compress_mode=user -This disables the automaic compression and gives the user discretion of choosing the +This disables the automatic compression and gives the user discretion of choosing the target file and the timing. The user can do manual compression/decompression on the compression enabled files using F2FS_IOC_DECOMPRESS_FILE and F2FS_IOC_COMPRESS_FILE ioctls like the below. diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst index e0204a23e997..1d831e3cbcb3 100644 --- a/Documentation/filesystems/fsverity.rst +++ b/Documentation/filesystems/fsverity.rst @@ -217,6 +217,82 @@ FS_IOC_MEASURE_VERITY can fail with the following errors: - ``EOVERFLOW``: the digest is longer than the specified ``digest_size`` bytes. Try providing a larger buffer. +FS_IOC_READ_VERITY_METADATA +--------------------------- + +The FS_IOC_READ_VERITY_METADATA ioctl reads verity metadata from a +verity file. This ioctl is available since Linux v5.12. + +This ioctl allows writing a server program that takes a verity file +and serves it to a client program, such that the client can do its own +fs-verity compatible verification of the file. This only makes sense +if the client doesn't trust the server and if the server needs to +provide the storage for the client. + +This is a fairly specialized use case, and most fs-verity users won't +need this ioctl. + +This ioctl takes in a pointer to the following structure:: + + #define FS_VERITY_METADATA_TYPE_MERKLE_TREE 1 + #define FS_VERITY_METADATA_TYPE_DESCRIPTOR 2 + #define FS_VERITY_METADATA_TYPE_SIGNATURE 3 + + struct fsverity_read_metadata_arg { + __u64 metadata_type; + __u64 offset; + __u64 length; + __u64 buf_ptr; + __u64 __reserved; + }; + +``metadata_type`` specifies the type of metadata to read: + +- ``FS_VERITY_METADATA_TYPE_MERKLE_TREE`` reads the blocks of the + Merkle tree. The blocks are returned in order from the root level + to the leaf level. Within each level, the blocks are returned in + the same order that their hashes are themselves hashed. + See `Merkle tree`_ for more information. + +- ``FS_VERITY_METADATA_TYPE_DESCRIPTOR`` reads the fs-verity + descriptor. See `fs-verity descriptor`_. + +- ``FS_VERITY_METADATA_TYPE_SIGNATURE`` reads the signature which was + passed to FS_IOC_ENABLE_VERITY, if any. See `Built-in signature + verification`_. + +The semantics are similar to those of ``pread()``. ``offset`` +specifies the offset in bytes into the metadata item to read from, and +``length`` specifies the maximum number of bytes to read from the +metadata item. ``buf_ptr`` is the pointer to the buffer to read into, +cast to a 64-bit integer. ``__reserved`` must be 0. On success, the +number of bytes read is returned. 0 is returned at the end of the +metadata item. The returned length may be less than ``length``, for +example if the ioctl is interrupted. + +The metadata returned by FS_IOC_READ_VERITY_METADATA isn't guaranteed +to be authenticated against the file digest that would be returned by +`FS_IOC_MEASURE_VERITY`_, as the metadata is expected to be used to +implement fs-verity compatible verification anyway (though absent a +malicious disk, the metadata will indeed match). E.g. to implement +this ioctl, the filesystem is allowed to just read the Merkle tree +blocks from disk without actually verifying the path to the root node. + +FS_IOC_READ_VERITY_METADATA can fail with the following errors: + +- ``EFAULT``: the caller provided inaccessible memory +- ``EINTR``: the ioctl was interrupted before any data was read +- ``EINVAL``: reserved fields were set, or ``offset + length`` + overflowed +- ``ENODATA``: the file is not a verity file, or + FS_VERITY_METADATA_TYPE_SIGNATURE was requested but the file doesn't + have a built-in signature +- ``ENOTTY``: this type of filesystem does not implement fs-verity, or + this ioctl is not yet implemented on it +- ``EOPNOTSUPP``: the kernel was not configured with fs-verity + support, or the filesystem superblock has not had the 'verity' + feature enabled on it. (See `Filesystem support`_.) + FS_IOC_GETFLAGS --------------- diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst index 867036aa90b8..1f8cf8e10b34 100644 --- a/Documentation/filesystems/porting.rst +++ b/Documentation/filesystems/porting.rst @@ -865,3 +865,19 @@ no matter what. Everything is handled by the caller. clone_private_mount() returns a longterm mount now, so the proper destructor of its result is kern_unmount() or kern_unmount_array(). + +--- + +**mandatory** + +zero-length bvec segments are disallowed, they must be filtered out before +passed on to an iterator. + +--- + +**mandatory** + +For bvec based itererators bio_iov_iter_get_pages() now doesn't copy bvecs but +uses the one provided. Anyone issuing kiocb-I/O should ensure that the bvec and +page references stay until I/O has completed, i.e. until ->ki_complete() has +been called or returned with non -EIOCBQUEUED code. diff --git a/Documentation/firmware-guide/acpi/debug.rst b/Documentation/firmware-guide/acpi/debug.rst index 1a152dd1d765..03cd4e25fc45 100644 --- a/Documentation/firmware-guide/acpi/debug.rst +++ b/Documentation/firmware-guide/acpi/debug.rst @@ -52,19 +52,12 @@ shows the supported mask values, currently these:: ACPI_CA_DISASSEMBLER 0x00000800 ACPI_COMPILER 0x00001000 ACPI_TOOLS 0x00002000 - ACPI_BUS_COMPONENT 0x00010000 - ACPI_AC_COMPONENT 0x00020000 - ACPI_BATTERY_COMPONENT 0x00040000 - ACPI_BUTTON_COMPONENT 0x00080000 ACPI_SBS_COMPONENT 0x00100000 ACPI_FAN_COMPONENT 0x00200000 ACPI_PCI_COMPONENT 0x00400000 - ACPI_POWER_COMPONENT 0x00800000 ACPI_CONTAINER_COMPONENT 0x01000000 ACPI_SYSTEM_COMPONENT 0x02000000 - ACPI_THERMAL_COMPONENT 0x04000000 ACPI_MEMORY_DEVICE_COMPONENT 0x08000000 - ACPI_VIDEO_COMPONENT 0x10000000 ACPI_PROCESSOR_COMPONENT 0x20000000 debug_level @@ -118,15 +111,15 @@ currently these:: Examples ======== -For example, drivers/acpi/bus.c contains this:: +For example, drivers/acpi/acpica/evxfevnt.c contains this:: - #define _COMPONENT ACPI_BUS_COMPONENT + #define _COMPONENT ACPI_EVENTS ... - ACPI_DEBUG_PRINT((ACPI_DB_INFO, "Device insertion detected\n")); + ACPI_DEBUG_PRINT((ACPI_DB_INIT, "ACPI mode disabled\n")); -To turn on this message, set the ACPI_BUS_COMPONENT bit in acpi.debug_layer -and the ACPI_LV_INFO bit in acpi.debug_level. (The ACPI_DEBUG_PRINT -statement uses ACPI_DB_INFO, which is macro based on the ACPI_LV_INFO +To turn on this message, set the ACPI_EVENTS bit in acpi.debug_layer +and the ACPI_LV_INIT bit in acpi.debug_level. (The ACPI_DEBUG_PRINT +statement uses ACPI_DB_INIT, which is a macro based on the ACPI_LV_INIT definition.) Enable all AML "Debug" output (stores to the Debug object while interpreting diff --git a/Documentation/firmware-guide/acpi/gpio-properties.rst b/Documentation/firmware-guide/acpi/gpio-properties.rst index b36aa3e743d8..4e264c16ddff 100644 --- a/Documentation/firmware-guide/acpi/gpio-properties.rst +++ b/Documentation/firmware-guide/acpi/gpio-properties.rst @@ -146,6 +146,7 @@ following rules (see also the examples): other words, it is not mandatory to fill all the GPIO lines - empty names are allowed (two quotation marks ``""`` correspond to an empty name) + - names inside one GPIO controller/expander must be unique Example of a GPIO controller of 16 lines, with an incomplete list with two empty names:: diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 3c5ae4f6dfd2..87e5023e3f55 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -319,6 +319,15 @@ CRTC Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_crtc.c :export: +Color Management Functions Reference +------------------------------------ + +.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c + :export: + +.. kernel-doc:: include/drm/drm_color_mgmt.h + :internal: + Frame Buffer Abstraction ======================== @@ -370,6 +379,21 @@ Plane Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_plane.c :export: +Plane Composition Functions Reference +------------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_blend.c + :export: + +Plane Damage Tracking Functions Reference +----------------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c + :export: + +.. kernel-doc:: include/drm/drm_damage_helper.h + :internal: + Display Modes Function Reference ================================ @@ -436,6 +460,9 @@ KMS Locking KMS Properties ============== +This section of the documentation is primarily aimed at user-space developers. +For the driver APIs, see the other sections. + Property Types and Blob Property Support ---------------------------------------- @@ -466,39 +493,30 @@ Standard CRTC Properties .. kernel-doc:: drivers/gpu/drm/drm_crtc.c :doc: standard CRTC properties +Standard Plane Properties +------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_plane.c + :doc: standard plane properties + Plane Composition Properties ---------------------------- .. kernel-doc:: drivers/gpu/drm/drm_blend.c :doc: overview -.. kernel-doc:: drivers/gpu/drm/drm_blend.c - :export: - -FB_DAMAGE_CLIPS -~~~~~~~~~~~~~~~ +Damage Tracking Properties +-------------------------- .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c :doc: overview -.. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c - :export: - -.. kernel-doc:: include/drm/drm_damage_helper.h - :internal: - Color Management Properties --------------------------- .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c :doc: overview -.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c - :export: - -.. kernel-doc:: include/drm/drm_color_mgmt.h - :internal: - Tile Group Property ------------------- diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 7dce175f6d75..04bdc7a91d53 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -457,5 +457,8 @@ Userspace API Structures .. kernel-doc:: include/uapi/drm/drm_mode.h :doc: overview +.. kernel-doc:: include/uapi/drm/drm.h + :internal: + .. kernel-doc:: include/uapi/drm/drm_mode.h :internal: diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 20868f3d0123..486c720f3890 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -428,7 +428,7 @@ User Batchbuffer Execution Logical Rings, Logical Ring Contexts and Execlists -------------------------------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_lrc.c +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_execlists_submission.c :doc: Logical Rings, Logical Ring Contexts and Execlists Global GTT views diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 009d8e6c7e3c..77fbfe93df56 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -23,6 +23,9 @@ Advanced: Tricky tasks that need fairly good understanding of the DRM subsystem and graphics topics. Generally need the relevant hardware for development and testing. +Expert: Only attempt these if you've successfully completed some tricky +refactorings already and are an expert in the specific area + Subsystem-wide refactorings =========================== @@ -168,6 +171,22 @@ Contact: Daniel Vetter, respective driver maintainers Level: Advanced +Move Buffer Object Locking to dma_resv_lock() +--------------------------------------------- + +Many drivers have their own per-object locking scheme, usually using +mutex_lock(). This causes all kinds of trouble for buffer sharing, since +depending which driver is the exporter and importer, the locking hierarchy is +reversed. + +To solve this we need one standard per-object locking mechanism, which is +dma_resv_lock(). This lock needs to be called as the outermost lock, with all +other driver specific per-object locks removed. The problem is tha rolling out +the actual change to the locking contract is a flag day, due to struct dma_buf +buffer sharing. + +Level: Expert + Convert logging to drm_* functions with drm_device paramater ------------------------------------------------------------ diff --git a/Documentation/gpu/vkms.rst b/Documentation/gpu/vkms.rst index 13bab1d93bb3..2c9b376da5ca 100644 --- a/Documentation/gpu/vkms.rst +++ b/Documentation/gpu/vkms.rst @@ -7,6 +7,88 @@ .. kernel-doc:: drivers/gpu/drm/vkms/vkms_drv.c :doc: vkms (Virtual Kernel Modesetting) +Setup +===== + +The VKMS driver can be setup with the following steps: + +To check if VKMS is loaded, run:: + + lsmod | grep vkms + +This should list the VKMS driver. If no output is obtained, then +you need to enable and/or load the VKMS driver. +Ensure that the VKMS driver has been set as a loadable module in your +kernel config file. Do:: + + make nconfig + + Go to `Device Drivers> Graphics support` + + Enable `Virtual KMS (EXPERIMENTAL)` + +Compile and build the kernel for the changes to get reflected. +Now, to load the driver, use:: + + sudo modprobe vkms + +On running the lsmod command now, the VKMS driver will appear listed. +You can also observe the driver being loaded in the dmesg logs. + +The VKMS driver has optional features to simulate different kinds of hardware, +which are exposed as module options. You can use the `modinfo` command +to see the module options for vkms:: + + modinfo vkms + +Module options are helpful when testing, and enabling modules +can be done while loading vkms. For example, to load vkms with cursor enabled, +use:: + + sudo modprobe vkms enable_cursor=1 + +To disable the driver, use :: + + sudo modprobe -r vkms + +Testing With IGT +================ + +The IGT GPU Tools is a test suite used specifically for debugging and +development of the DRM drivers. +The IGT Tools can be installed from +`here <https://gitlab.freedesktop.org/drm/igt-gpu-tools>`_ . + +The tests need to be run without a compositor, so you need to switch to text +only mode. You can do this by:: + + sudo systemctl isolate multi-user.target + +To return to graphical mode, do:: + + sudo systemctl isolate graphical.target + +Once you are in text only mode, you can run tests using the --device switch +or IGT_DEVICE variable to specify the device filter for the driver we want +to test. IGT_DEVICE can also be used with the run-test.sh script to run the +tests for a specific driver:: + + sudo ./build/tests/<name of test> --device "sys:/sys/devices/platform/vkms" + sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/<name of test> + sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./scripts/run-tests.sh -t <name of test> + +For example, to test the functionality of the writeback library, +we can run the kms_writeback test:: + + sudo ./build/tests/kms_writeback --device "sys:/sys/devices/platform/vkms" + sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/kms_writeback + sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./scripts/run-tests.sh -t kms_writeback + +You can also run subtests if you do not want to run the entire test:: + + sudo ./build/tests/kms_flip --run-subtest basic-plain-flip --device "sys:/sys/devices/platform/vkms" + sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/kms_flip --run-subtest basic-plain-flip + TODO ==== diff --git a/Documentation/hwmon/ab8500.rst b/Documentation/hwmon/ab8500.rst deleted file mode 100644 index 33f93a9cec04..000000000000 --- a/Documentation/hwmon/ab8500.rst +++ /dev/null @@ -1,26 +0,0 @@ -Kernel driver ab8500 -==================== - -Supported chips: - - * ST-Ericsson AB8500 - - Prefix: 'ab8500' - - Addresses scanned: - - - Datasheet: http://www.stericsson.com/developers/documentation.jsp - -Authors: - - Martin Persson <martin.persson@stericsson.com> - - Hongbo Zhang <hongbo.zhang@linaro.org> - -Description ------------ - -See also Documentation/hwmon/abx500.rst. This is the ST-Ericsson AB8500 specific -driver. - -Currently only the AB8500 internal sensor and one external sensor for battery -temperature are monitored. Other GPADC channels can also be monitored if needed -in future. diff --git a/Documentation/hwmon/abx500.rst b/Documentation/hwmon/abx500.rst deleted file mode 100644 index 3d88b2ce0f00..000000000000 --- a/Documentation/hwmon/abx500.rst +++ /dev/null @@ -1,32 +0,0 @@ -Kernel driver abx500 -==================== - -Supported chips: - - * ST-Ericsson ABx500 series - - Prefix: 'abx500' - - Addresses scanned: - - - Datasheet: http://www.stericsson.com/developers/documentation.jsp - -Authors: - Martin Persson <martin.persson@stericsson.com> - Hongbo Zhang <hongbo.zhang@linaro.org> - -Description ------------ - -Every ST-Ericsson Ux500 SOC consists of both ABx500 and DBx500 physically, -this is kernel hwmon driver for ABx500. - -There are some GPADCs inside ABx500 which are designed for connecting to -thermal sensors, and there is also a thermal sensor inside ABx500 too, which -raises interrupt when critical temperature reached. - -This abx500 is a common layer which can monitor all of the sensors, every -specific abx500 chip has its special configurations in its own file, e.g. some -sensors can be configured invisible if they are not available on that chip, and -the corresponding gpadc_addr should be set to 0, thus this sensor won't be -polled. diff --git a/Documentation/hwmon/aht10.rst b/Documentation/hwmon/aht10.rst new file mode 100644 index 000000000000..482262ca117c --- /dev/null +++ b/Documentation/hwmon/aht10.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver aht10 +===================== + +Supported chips: + + * Aosong AHT10 + + Prefix: 'aht10' + + Addresses scanned: None + + Datasheet: + + Chinese: http://www.aosong.com/userfiles/files/media/AHT10%E4%BA%A7%E5%93%81%E6%89%8B%E5%86%8C%20A3%2020201210.pdf + English: https://server4.eca.ir/eshop/AHT10/Aosong_AHT10_en_draft_0c.pdf + +Author: Johannes Cornelis Draaijer <jcdra1@gmail.com> + + +Description +----------- + +The AHT10 is a Temperature and Humidity sensor + +The address of this i2c device may only be 0x38 + +Usage Notes +----------- + +This driver does not probe for AHT10 devices, as there is no reliable +way to determine if an i2c chip is or isn't an AHT10. The device has +to be instantiated explicitly with the address 0x38. See +Documentation/i2c/instantiating-devices.rst for details. + +Sysfs entries +------------- + +=============== ============================================ +temp1_input Measured temperature in millidegrees Celcius +humidity1_input Measured humidity in %H +update_interval The minimum interval for polling the sensor, + in milliseconds. Writable. Must be at + least 2000. +=============== ============================================ diff --git a/Documentation/hwmon/ina2xx.rst b/Documentation/hwmon/ina2xx.rst index f78a5cd44c4c..27d2e39bc8ac 100644 --- a/Documentation/hwmon/ina2xx.rst +++ b/Documentation/hwmon/ina2xx.rst @@ -74,7 +74,7 @@ bus supply voltage. The shunt value in micro-ohms can be set via platform data or device tree at compile-time or via the shunt_resistor attribute in sysfs at run-time. Please -refer to the Documentation/devicetree/bindings/hwmon/ina2xx.txt for bindings +refer to the Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml for bindings if the device tree is used. Additionally ina226 supports update_interval attribute as described in diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index fcb870ce6286..8d5a2df1ecb6 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -18,10 +18,8 @@ Hardware Monitoring Kernel Drivers .. toctree:: :maxdepth: 1 - ab8500 abituguru abituguru3 - abx500 acpi_power_meter ad7314 adc128d818 @@ -39,6 +37,7 @@ Hardware Monitoring Kernel Drivers adt7462 adt7470 adt7475 + aht10 amc6821 amd_energy asb100 @@ -178,6 +177,7 @@ Hardware Monitoring Kernel Drivers tmp401 tmp421 tmp513 + tps23861 tps40422 tps53679 twl4030-madc-hwmon diff --git a/Documentation/hwmon/max16601.rst b/Documentation/hwmon/max16601.rst index 346e74674c51..92c0a7d7808c 100644 --- a/Documentation/hwmon/max16601.rst +++ b/Documentation/hwmon/max16601.rst @@ -5,6 +5,14 @@ Kernel driver max16601 Supported chips: + * Maxim MAX16508 + + Prefix: 'max16508' + + Addresses scanned: - + + Datasheet: Not published + * Maxim MAX16601 Prefix: 'max16601' @@ -19,8 +27,8 @@ Author: Guenter Roeck <linux@roeck-us.net> Description ----------- -This driver supports the MAX16601 VR13.HC Dual-Output Voltage Regulator -Chipset. +This driver supports the MAX16508 VR13 Dual-Output Voltage Regulator +as well as the MAX16601 VR13.HC Dual-Output Voltage Regulator chipsets. The driver is a client driver to the core PMBus driver. Please see Documentation/hwmon/pmbus.rst for details on PMBus client drivers. @@ -45,115 +53,76 @@ Sysfs entries The following attributes are supported. -======================= ======================================================= -in1_label "vin1" -in1_input VCORE input voltage. -in1_alarm Input voltage alarm. - -in2_label "vout1" -in2_input VCORE output voltage. -in2_alarm Output voltage alarm. - -curr1_label "iin1" -curr1_input VCORE input current, derived from duty cycle and output - current. -curr1_max Maximum input current. -curr1_max_alarm Current high alarm. - -curr2_label "iin1.0" -curr2_input VCORE phase 0 input current. - -curr3_label "iin1.1" -curr3_input VCORE phase 1 input current. - -curr4_label "iin1.2" -curr4_input VCORE phase 2 input current. - -curr5_label "iin1.3" -curr5_input VCORE phase 3 input current. - -curr6_label "iin1.4" -curr6_input VCORE phase 4 input current. - -curr7_label "iin1.5" -curr7_input VCORE phase 5 input current. - -curr8_label "iin1.6" -curr8_input VCORE phase 6 input current. - -curr9_label "iin1.7" -curr9_input VCORE phase 7 input current. - -curr10_label "iin2" -curr10_input VCORE input current, derived from sensor element. - -curr11_label "iin3" -curr11_input VSA input current. - -curr12_label "iout1" -curr12_input VCORE output current. -curr12_crit Critical output current. -curr12_crit_alarm Output current critical alarm. -curr12_max Maximum output current. -curr12_max_alarm Output current high alarm. - -curr13_label "iout1.0" -curr13_input VCORE phase 0 output current. - -curr14_label "iout1.1" -curr14_input VCORE phase 1 output current. - -curr15_label "iout1.2" -curr15_input VCORE phase 2 output current. - -curr16_label "iout1.3" -curr16_input VCORE phase 3 output current. - -curr17_label "iout1.4" -curr17_input VCORE phase 4 output current. - -curr18_label "iout1.5" -curr18_input VCORE phase 5 output current. - -curr19_label "iout1.6" -curr19_input VCORE phase 6 output current. - -curr20_label "iout1.7" -curr20_input VCORE phase 7 output current. - -curr21_label "iout3" -curr21_input VSA output current. -curr21_highest Historical maximum VSA output current. -curr21_reset_history Write any value to reset curr21_highest. -curr21_crit Critical output current. -curr21_crit_alarm Output current critical alarm. -curr21_max Maximum output current. -curr21_max_alarm Output current high alarm. - -power1_label "pin1" -power1_input Input power, derived from duty cycle and output current. -power1_alarm Input power alarm. - -power2_label "pin2" -power2_input Input power, derived from input current sensor. - -power3_label "pout" -power3_input Output power. - -temp1_input VCORE temperature. -temp1_crit Critical high temperature. -temp1_crit_alarm Chip temperature critical high alarm. -temp1_max Maximum temperature. -temp1_max_alarm Chip temperature high alarm. - -temp2_input TSENSE_0 temperature -temp3_input TSENSE_1 temperature -temp4_input TSENSE_2 temperature -temp5_input TSENSE_3 temperature - -temp6_input VSA temperature. -temp6_crit Critical high temperature. -temp6_crit_alarm Chip temperature critical high alarm. -temp6_max Maximum temperature. -temp6_max_alarm Chip temperature high alarm. -======================= ======================================================= +=============================== =============================================== +in1_label "vin1" +in1_input VCORE input voltage. +in1_alarm Input voltage alarm. + +in2_label "vout1" +in2_input VCORE output voltage. +in2_alarm Output voltage alarm. + +curr1_label "iin1" +curr1_input VCORE input current, derived from duty cycle + and output current. +curr1_max Maximum input current. +curr1_max_alarm Current high alarm. + +curr[P+2]_label "iin1.P" +curr[P+2]_input VCORE phase P input current. + +curr[N+2]_label "iin2" +curr[N+2]_input VCORE input current, derived from sensor + element. + 'N' is the number of enabled/populated phases. + +curr[N+3]_label "iin3" +curr[N+3]_input VSA input current. + +curr[N+4]_label "iout1" +curr[N+4]_input VCORE output current. +curr[N+4]_crit Critical output current. +curr[N+4]_crit_alarm Output current critical alarm. +curr[N+4]_max Maximum output current. +curr[N+4]_max_alarm Output current high alarm. + +curr[N+P+5]_label "iout1.P" +curr[N+P+5]_input VCORE phase P output current. + +curr[2*N+5]_label "iout3" +curr[2*N+5]_input VSA output current. +curr[2*N+5]_highest Historical maximum VSA output current. +curr[2*N+5]_reset_history Write any value to reset curr21_highest. +curr[2*N+5]_crit Critical output current. +curr[2*N+5]_crit_alarm Output current critical alarm. +curr[2*N+5]_max Maximum output current. +curr[2*N+5]_max_alarm Output current high alarm. + +power1_label "pin1" +power1_input Input power, derived from duty cycle and output + current. +power1_alarm Input power alarm. + +power2_label "pin2" +power2_input Input power, derived from input current sensor. + +power3_label "pout" +power3_input Output power. + +temp1_input VCORE temperature. +temp1_crit Critical high temperature. +temp1_crit_alarm Chip temperature critical high alarm. +temp1_max Maximum temperature. +temp1_max_alarm Chip temperature high alarm. + +temp2_input TSENSE_0 temperature +temp3_input TSENSE_1 temperature +temp4_input TSENSE_2 temperature +temp5_input TSENSE_3 temperature + +temp6_input VSA temperature. +temp6_crit Critical high temperature. +temp6_crit_alarm Chip temperature critical high alarm. +temp6_max Maximum temperature. +temp6_max_alarm Chip temperature high alarm. +=============================== =============================================== diff --git a/Documentation/hwmon/nct6683.rst b/Documentation/hwmon/nct6683.rst index 8646ad519fcd..2e1408d174bd 100644 --- a/Documentation/hwmon/nct6683.rst +++ b/Documentation/hwmon/nct6683.rst @@ -61,5 +61,6 @@ Board Firmware version Intel DH87RL NCT6683D EC firmware version 1.0 build 04/03/13 Intel DH87MC NCT6683D EC firmware version 1.0 build 04/03/13 Intel DB85FL NCT6683D EC firmware version 1.0 build 04/03/13 +ASRock X570 NCT6683D EC firmware version 1.0 build 06/28/19 MSI B550 NCT6687D EC firmware version 1.0 build 05/07/20 =============== =============================================== diff --git a/Documentation/hwmon/tps23861.rst b/Documentation/hwmon/tps23861.rst new file mode 100644 index 000000000000..46d121ff3f31 --- /dev/null +++ b/Documentation/hwmon/tps23861.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +Kernel driver tps23861 +====================== + +Supported chips: + * Texas Instruments TPS23861 + + Prefix: 'tps23861' + + Datasheet: https://www.ti.com/lit/gpn/tps23861 + +Author: Robert Marko <robert.marko@sartura.hr> + +Description +----------- + +This driver supports hardware monitoring for Texas Instruments TPS23861 PoE PSE. + +TPS23861 is a quad port IEEE802.3at PSE controller with optional I2C control +and monitoring capabilities. + +TPS23861 offers three modes of operation: Auto, Semi-Auto and Manual. + +This driver only supports the Auto mode of operation providing monitoring +as well as enabling/disabling the four ports. + +Sysfs entries +------------- + +======================= ===================================================================== +in[0-3]_input Voltage on ports [1-4] +in[0-3]_label "Port[1-4]" +in4_input IC input voltage +in4_label "Input" +temp1_input IC die temperature +temp1_label "Die" +curr[1-4]_input Current on ports [1-4] +in[1-4]_label "Port[1-4]" +in[0-3]_enable Enable/disable ports [1-4] +======================= ===================================================================== diff --git a/Documentation/i2c/slave-testunit-backend.rst b/Documentation/i2c/slave-testunit-backend.rst index 2c38e64f0bac..ecfc2abec32d 100644 --- a/Documentation/i2c/slave-testunit-backend.rst +++ b/Documentation/i2c/slave-testunit-backend.rst @@ -22,8 +22,9 @@ Instantiating the device is regular. Example for bus 0, address 0x30: After that, you will have a write-only device listening. Reads will just return an 8-bit version number of the testunit. When writing, the device consists of 4 -8-bit registers and all must be written to start a testcase, i.e. you must -always write 4 bytes to the device. The registers are: +8-bit registers and, except for some "partial" commands, all registers must be +written to start a testcase, i.e. you usually write 4 bytes to the device. The +registers are: 0x00 CMD - which test to trigger 0x01 DATAL - configuration byte 1 for the test @@ -67,3 +68,21 @@ status word is currently ignored in the Linux Kernel. Example to send a notification after 10ms: # i2cset -y 0 0x30 0x02 0x42 0x64 0x01 i + +0x03 SMBUS_BLOCK_PROC_CALL (partial command) + DATAL - must be '1', i.e. one further byte will be written + DATAH - number of bytes to be sent back + DELAY - not applicable, partial command! + +This test will respond to a block process call as defined by the SMBus +specification. The one data byte written specifies how many bytes will be sent +back in the following read transfer. Note that in this read transfer, the +testunit will prefix the length of the bytes to follow. So, if your host bus +driver emulates SMBus calls like the majority does, it needs to support the +I2C_M_RECV_LEN flag of an i2c_msg. This is a good testcase for it. The returned +data consists of the length first, and then of an array of bytes from length-1 +to 0. Here is an example which emulates i2c_smbus_block_process_call() using +i2ctransfer (you need i2c-tools v4.2 or later): + +# i2ctransfer -y 0 w3@0x30 0x03 0x01 0x10 r? +0x10 0x0f 0x0e 0x0d 0x0c 0x0b 0x0a 0x09 0x08 0x07 0x06 0x05 0x04 0x03 0x02 0x01 0x00 diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index 300d8edcb994..910c6303c7ea 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -1317,7 +1317,6 @@ When kbuild executes, the following steps are followed (roughly): libs-y += arch/sparc/lib/ drivers-$(CONFIG_PM) += arch/sparc/power/ - drivers-$(CONFIG_OPROFILE) += arch/sparc/oprofile/ 7.5 Architecture-specific boot images ------------------------------------- diff --git a/Documentation/networking/bonding.rst b/Documentation/networking/bonding.rst index adc314639085..5f690f0ad0e4 100644 --- a/Documentation/networking/bonding.rst +++ b/Documentation/networking/bonding.rst @@ -951,6 +951,19 @@ xmit_hash_policy packets will be distributed according to the encapsulated flows. + vlan+srcmac + + This policy uses a very rudimentary vlan ID and source mac + hash to load-balance traffic per-vlan, with failover + should one leg fail. The intended use case is for a bond + shared by multiple virtual machines, all configured to + use their own vlan, to give lacp-like functionality + without requiring lacp-capable switching hardware. + + The formula for the hash is simply + + hash = (vlan ID) XOR (source MAC vendor) XOR (source MAC dev) + The default value is layer2. This option was added in bonding version 2.6.3. In earlier versions of bonding, this parameter does not exist, and the layer2 policy is the only policy. The diff --git a/Documentation/networking/caif/caif.rst b/Documentation/networking/caif/caif.rst index a07213030ccf..81a14373d780 100644 --- a/Documentation/networking/caif/caif.rst +++ b/Documentation/networking/caif/caif.rst @@ -68,7 +68,6 @@ There are debugfs parameters provided for serial communication. * tty_status: Prints the bit-mask tty status information - 0x01 - tty->warned is on. - - 0x02 - tty->low_latency is on. - 0x04 - tty->packed is on. - 0x08 - tty->flow_stopped is on. - 0x10 - tty->hw_stopped is on. diff --git a/Documentation/networking/device_drivers/ethernet/index.rst b/Documentation/networking/device_drivers/ethernet/index.rst index cbb75a1818c0..6b5dc203da2b 100644 --- a/Documentation/networking/device_drivers/ethernet/index.rst +++ b/Documentation/networking/device_drivers/ethernet/index.rst @@ -49,6 +49,7 @@ Contents: stmicro/stmmac ti/cpsw ti/cpsw_switchdev + ti/am65_nuss_cpsw_switchdev ti/tlan toshiba/spider_net diff --git a/Documentation/networking/device_drivers/ethernet/intel/ice.rst b/Documentation/networking/device_drivers/ethernet/intel/ice.rst index ee43ea57d443..e7d9cbff771b 100644 --- a/Documentation/networking/device_drivers/ethernet/intel/ice.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/ice.rst @@ -1,46 +1,1031 @@ .. SPDX-License-Identifier: GPL-2.0+ -================================================================== -Linux Base Driver for the Intel(R) Ethernet Connection E800 Series -================================================================== +================================================================= +Linux Base Driver for the Intel(R) Ethernet Controller 800 Series +================================================================= Intel ice Linux driver. -Copyright(c) 2018 Intel Corporation. +Copyright(c) 2018-2021 Intel Corporation. Contents ======== -- Enabling the driver -- Support +- Overview +- Identifying Your Adapter +- Important Notes +- Additional Features & Configurations +- Performance Optimization -The driver in this release supports Intel's E800 Series of products. For -more information, visit Intel's support page at https://support.intel.com. -Enabling the driver -=================== -The driver is enabled via the standard kernel configuration system, -using the make command:: +The associated Virtual Function (VF) driver for this driver is iavf. - make oldconfig/menuconfig/etc. +Driver information can be obtained using ethtool and lspci. -The driver is located in the menu structure at: +For questions related to hardware requirements, refer to the documentation +supplied with your Intel adapter. All hardware requirements listed apply to use +with Linux. + +This driver supports XDP (Express Data Path) and AF_XDP zero-copy. Note that +XDP is blocked for frame sizes larger than 3KB. + + +Identifying Your Adapter +======================== +For information on how to identify your adapter, and for the latest Intel +network drivers, refer to the Intel Support website: +https://www.intel.com/support + + +Important Notes +=============== + +Packet drops may occur under receive stress +------------------------------------------- +Devices based on the Intel(R) Ethernet Controller 800 Series are designed to +tolerate a limited amount of system latency during PCIe and DMA transactions. +If these transactions take longer than the tolerated latency, it can impact the +length of time the packets are buffered in the device and associated memory, +which may result in dropped packets. These packets drops typically do not have +a noticeable impact on throughput and performance under standard workloads. + +If these packet drops appear to affect your workload, the following may improve +the situation: + +1) Make sure that your system's physical memory is in a high-performance + configuration, as recommended by the platform vendor. A common + recommendation is for all channels to be populated with a single DIMM + module. +2) In your system's BIOS/UEFI settings, select the "Performance" profile. +3) Your distribution may provide tools like "tuned," which can help tweak + kernel settings to achieve better standard settings for different workloads. + + +Configuring SR-IOV for improved network security +------------------------------------------------ +In a virtualized environment, on Intel(R) Ethernet Network Adapters that +support SR-IOV, the virtual function (VF) may be subject to malicious behavior. +Software-generated layer two frames, like IEEE 802.3x (link flow control), IEEE +802.1Qbb (priority based flow-control), and others of this type, are not +expected and can throttle traffic between the host and the virtual switch, +reducing performance. To resolve this issue, and to ensure isolation from +unintended traffic streams, configure all SR-IOV enabled ports for VLAN tagging +from the administrative interface on the PF. This configuration allows +unexpected, and potentially malicious, frames to be dropped. + +See "Configuring VLAN Tagging on SR-IOV Enabled Adapter Ports" later in this +README for configuration instructions. + + +Do not unload port driver if VF with active VM is bound to it +------------------------------------------------------------- +Do not unload a port's driver if a Virtual Function (VF) with an active Virtual +Machine (VM) is bound to it. Doing so will cause the port to appear to hang. +Once the VM shuts down, or otherwise releases the VF, the command will +complete. + + +Important notes for SR-IOV and Link Aggregation +----------------------------------------------- +Link Aggregation is mutually exclusive with SR-IOV. + +- If Link Aggregation is active, SR-IOV VFs cannot be created on the PF. +- If SR-IOV is active, you cannot set up Link Aggregation on the interface. + +Bridging and MACVLAN are also affected by this. If you wish to use bridging or +MACVLAN with SR-IOV, you must set up bridging or MACVLAN before enabling +SR-IOV. If you are using bridging or MACVLAN in conjunction with SR-IOV, and +you want to remove the interface from the bridge or MACVLAN, you must follow +these steps: + +1. Destroy SR-IOV VFs if they exist +2. Remove the interface from the bridge or MACVLAN +3. Recreate SRIOV VFs as needed + + +Additional Features and Configurations +====================================== + +ethtool +------- +The driver utilizes the ethtool interface for driver configuration and +diagnostics, as well as displaying statistical information. The latest ethtool +version is required for this functionality. Download it at: +https://kernel.org/pub/software/network/ethtool/ + +NOTE: The rx_bytes value of ethtool does not match the rx_bytes value of +Netdev, due to the 4-byte CRC being stripped by the device. The difference +between the two rx_bytes values will be 4 x the number of Rx packets. For +example, if Rx packets are 10 and Netdev (software statistics) displays +rx_bytes as "X", then ethtool (hardware statistics) will display rx_bytes as +"X+40" (4 bytes CRC x 10 packets). + + +Viewing Link Messages +--------------------- +Link messages will not be displayed to the console if the distribution is +restricting system messages. In order to see network driver link messages on +your console, set dmesg to eight by entering the following:: + + # dmesg -n 8 + +NOTE: This setting is not saved across reboots. + + +Dynamic Device Personalization +------------------------------ +Dynamic Device Personalization (DDP) allows you to change the packet processing +pipeline of a device by applying a profile package to the device at runtime. +Profiles can be used to, for example, add support for new protocols, change +existing protocols, or change default settings. DDP profiles can also be rolled +back without rebooting the system. + +The DDP package loads during device initialization. The driver looks for +``intel/ice/ddp/ice.pkg`` in your firmware root (typically ``/lib/firmware/`` +or ``/lib/firmware/updates/``) and checks that it contains a valid DDP package +file. + +NOTE: Your distribution should likely have provided the latest DDP file, but if +ice.pkg is missing, you can find it in the linux-firmware repository or from +intel.com. + +If the driver is unable to load the DDP package, the device will enter Safe +Mode. Safe Mode disables advanced and performance features and supports only +basic traffic and minimal functionality, such as updating the NVM or +downloading a new driver or DDP package. Safe Mode only applies to the affected +physical function and does not impact any other PFs. See the "Intel(R) Ethernet +Adapters and Devices User Guide" for more details on DDP and Safe Mode. + +NOTES: + +- If you encounter issues with the DDP package file, you may need to download + an updated driver or DDP package file. See the log messages for more + information. + +- The ice.pkg file is a symbolic link to the default DDP package file. + +- You cannot update the DDP package if any PF drivers are already loaded. To + overwrite a package, unload all PFs and then reload the driver with the new + package. + +- Only the first loaded PF per device can download a package for that device. + +You can install specific DDP package files for different physical devices in +the same system. To install a specific DDP package file: + +1. Download the DDP package file you want for your device. + +2. Rename the file ice-xxxxxxxxxxxxxxxx.pkg, where 'xxxxxxxxxxxxxxxx' is the + unique 64-bit PCI Express device serial number (in hex) of the device you + want the package downloaded on. The filename must include the complete + serial number (including leading zeros) and be all lowercase. For example, + if the 64-bit serial number is b887a3ffffca0568, then the file name would be + ice-b887a3ffffca0568.pkg. + + To find the serial number from the PCI bus address, you can use the + following command:: + + # lspci -vv -s af:00.0 | grep -i Serial + Capabilities: [150 v1] Device Serial Number b8-87-a3-ff-ff-ca-05-68 + + You can use the following command to format the serial number without the + dashes:: + + # lspci -vv -s af:00.0 | grep -i Serial | awk '{print $7}' | sed s/-//g + b887a3ffffca0568 + +3. Copy the renamed DDP package file to + ``/lib/firmware/updates/intel/ice/ddp/``. If the directory does not yet + exist, create it before copying the file. + +4. Unload all of the PFs on the device. + +5. Reload the driver with the new package. + +NOTE: The presence of a device-specific DDP package file overrides the loading +of the default DDP package file (ice.pkg). + + +Intel(R) Ethernet Flow Director +------------------------------- +The Intel Ethernet Flow Director performs the following tasks: + +- Directs receive packets according to their flows to different queues +- Enables tight control on routing a flow in the platform +- Matches flows and CPU cores for flow affinity + +NOTE: This driver supports the following flow types: + +- IPv4 +- TCPv4 +- UDPv4 +- SCTPv4 +- IPv6 +- TCPv6 +- UDPv6 +- SCTPv6 + +Each flow type supports valid combinations of IP addresses (source or +destination) and UDP/TCP/SCTP ports (source and destination). You can supply +only a source IP address, a source IP address and a destination port, or any +combination of one or more of these four parameters. + +NOTE: This driver allows you to filter traffic based on a user-defined flexible +two-byte pattern and offset by using the ethtool user-def and mask fields. Only +L3 and L4 flow types are supported for user-defined flexible filters. For a +given flow type, you must clear all Intel Ethernet Flow Director filters before +changing the input set (for that flow type). + + +Flow Director Filters +--------------------- +Flow Director filters are used to direct traffic that matches specified +characteristics. They are enabled through ethtool's ntuple interface. To enable +or disable the Intel Ethernet Flow Director and these filters:: + + # ethtool -K <ethX> ntuple <off|on> + +NOTE: When you disable ntuple filters, all the user programmed filters are +flushed from the driver cache and hardware. All needed filters must be re-added +when ntuple is re-enabled. + +To display all of the active filters:: + + # ethtool -u <ethX> + +To add a new filter:: + + # ethtool -U <ethX> flow-type <type> src-ip <ip> [m <ip_mask>] dst-ip <ip> + [m <ip_mask>] src-port <port> [m <port_mask>] dst-port <port> [m <port_mask>] + action <queue> + + Where: + <ethX> - the Ethernet device to program + <type> - can be ip4, tcp4, udp4, sctp4, ip6, tcp6, udp6, sctp6 + <ip> - the IP address to match on + <ip_mask> - the IPv4 address to mask on + NOTE: These filters use inverted masks. + <port> - the port number to match on + <port_mask> - the 16-bit integer for masking + NOTE: These filters use inverted masks. + <queue> - the queue to direct traffic toward (-1 discards the + matched traffic) + +To delete a filter:: + + # ethtool -U <ethX> delete <N> + + Where <N> is the filter ID displayed when printing all the active filters, + and may also have been specified using "loc <N>" when adding the filter. + +EXAMPLES: + +To add a filter that directs packet to queue 2:: + + # ethtool -U <ethX> flow-type tcp4 src-ip 192.168.10.1 dst-ip \ + 192.168.10.2 src-port 2000 dst-port 2001 action 2 [loc 1] + +To set a filter using only the source and destination IP address:: + + # ethtool -U <ethX> flow-type tcp4 src-ip 192.168.10.1 dst-ip \ + 192.168.10.2 action 2 [loc 1] + +To set a filter based on a user-defined pattern and offset:: + + # ethtool -U <ethX> flow-type tcp4 src-ip 192.168.10.1 dst-ip \ + 192.168.10.2 user-def 0x4FFFF action 2 [loc 1] + + where the value of the user-def field contains the offset (4 bytes) and + the pattern (0xffff). + +To match TCP traffic sent from 192.168.0.1, port 5300, directed to 192.168.0.5, +port 80, and then send it to queue 7:: + + # ethtool -U enp130s0 flow-type tcp4 src-ip 192.168.0.1 dst-ip 192.168.0.5 + src-port 5300 dst-port 80 action 7 + +To add a TCPv4 filter with a partial mask for a source IP subnet:: + + # ethtool -U <ethX> flow-type tcp4 src-ip 192.168.0.0 m 0.255.255.255 dst-ip + 192.168.5.12 src-port 12600 dst-port 31 action 12 + +NOTES: + +For each flow-type, the programmed filters must all have the same matching +input set. For example, issuing the following two commands is acceptable:: + + # ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.1 src-port 5300 action 7 + # ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.5 src-port 55 action 10 + +Issuing the next two commands, however, is not acceptable, since the first +specifies src-ip and the second specifies dst-ip:: + + # ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.1 src-port 5300 action 7 + # ethtool -U enp130s0 flow-type ip4 dst-ip 192.168.0.5 src-port 55 action 10 + +The second command will fail with an error. You may program multiple filters +with the same fields, using different values, but, on one device, you may not +program two tcp4 filters with different matching fields. + +The ice driver does not support matching on a subportion of a field, thus +partial mask fields are not supported. + + +Flex Byte Flow Director Filters +------------------------------- +The driver also supports matching user-defined data within the packet payload. +This flexible data is specified using the "user-def" field of the ethtool +command in the following way: + +.. table:: + + ============================== ============================ + ``31 28 24 20 16`` ``15 12 8 4 0`` + ``offset into packet payload`` ``2 bytes of flexible data`` + ============================== ============================ + +For example, + +:: + + ... user-def 0x4FFFF ... + +tells the filter to look 4 bytes into the payload and match that value against +0xFFFF. The offset is based on the beginning of the payload, and not the +beginning of the packet. Thus + +:: + + flow-type tcp4 ... user-def 0x8BEAF ... + +would match TCP/IPv4 packets which have the value 0xBEAF 8 bytes into the +TCP/IPv4 payload. + +Note that ICMP headers are parsed as 4 bytes of header and 4 bytes of payload. +Thus to match the first byte of the payload, you must actually add 4 bytes to +the offset. Also note that ip4 filters match both ICMP frames as well as raw +(unknown) ip4 frames, where the payload will be the L3 payload of the IP4 +frame. + +The maximum offset is 64. The hardware will only read up to 64 bytes of data +from the payload. The offset must be even because the flexible data is 2 bytes +long and must be aligned to byte 0 of the packet payload. + +The user-defined flexible offset is also considered part of the input set and +cannot be programmed separately for multiple filters of the same type. However, +the flexible data is not part of the input set and multiple filters may use the +same offset but match against different data. + + +RSS Hash Flow +------------- +Allows you to set the hash bytes per flow type and any combination of one or +more options for Receive Side Scaling (RSS) hash byte configuration. + +:: + + # ethtool -N <ethX> rx-flow-hash <type> <option> + + Where <type> is: + tcp4 signifying TCP over IPv4 + udp4 signifying UDP over IPv4 + tcp6 signifying TCP over IPv6 + udp6 signifying UDP over IPv6 + And <option> is one or more of: + s Hash on the IP source address of the Rx packet. + d Hash on the IP destination address of the Rx packet. + f Hash on bytes 0 and 1 of the Layer 4 header of the Rx packet. + n Hash on bytes 2 and 3 of the Layer 4 header of the Rx packet. + + +Accelerated Receive Flow Steering (aRFS) +---------------------------------------- +Devices based on the Intel(R) Ethernet Controller 800 Series support +Accelerated Receive Flow Steering (aRFS) on the PF. aRFS is a load-balancing +mechanism that allows you to direct packets to the same CPU where an +application is running or consuming the packets in that flow. + +NOTES: + +- aRFS requires that ntuple filtering is enabled via ethtool. +- aRFS support is limited to the following packet types: + + - TCP over IPv4 and IPv6 + - UDP over IPv4 and IPv6 + - Nonfragmented packets + +- aRFS only supports Flow Director filters, which consist of the + source/destination IP addresses and source/destination ports. +- aRFS and ethtool's ntuple interface both use the device's Flow Director. aRFS + and ntuple features can coexist, but you may encounter unexpected results if + there's a conflict between aRFS and ntuple requests. See "Intel(R) Ethernet + Flow Director" for additional information. + +To set up aRFS: + +1. Enable the Intel Ethernet Flow Director and ntuple filters using ethtool. + +:: + + # ethtool -K <ethX> ntuple on + +2. Set up the number of entries in the global flow table. For example: + +:: + + # NUM_RPS_ENTRIES=16384 + # echo $NUM_RPS_ENTRIES > /proc/sys/net/core/rps_sock_flow_entries + +3. Set up the number of entries in the per-queue flow table. For example: + +:: + + # NUM_RX_QUEUES=64 + # for file in /sys/class/net/$IFACE/queues/rx-*/rps_flow_cnt; do + # echo $(($NUM_RPS_ENTRIES/$NUM_RX_QUEUES)) > $file; + # done + +4. Disable the IRQ balance daemon (this is only a temporary stop of the service + until the next reboot). + +:: + + # systemctl stop irqbalance + +5. Configure the interrupt affinity. + + See ``/Documentation/core-api/irq/irq-affinity.rst`` + + +To disable aRFS using ethtool:: + + # ethtool -K <ethX> ntuple off + +NOTE: This command will disable ntuple filters and clear any aRFS filters in +software and hardware. + +Example Use Case: + +1. Set the server application on the desired CPU (e.g., CPU 4). + +:: + + # taskset -c 4 netserver + +2. Use netperf to route traffic from the client to CPU 4 on the server with + aRFS configured. This example uses TCP over IPv4. + +:: + + # netperf -H <Host IPv4 Address> -t TCP_STREAM + + +Enabling Virtual Functions (VFs) +-------------------------------- +Use sysfs to enable virtual functions (VF). + +For example, you can create 4 VFs as follows:: + + # echo 4 > /sys/class/net/<ethX>/device/sriov_numvfs + +To disable VFs, write 0 to the same file:: + + # echo 0 > /sys/class/net/<ethX>/device/sriov_numvfs + +The maximum number of VFs for the ice driver is 256 total (all ports). To check +how many VFs each PF supports, use the following command:: + + # cat /sys/class/net/<ethX>/device/sriov_totalvfs + +Note: You cannot use SR-IOV when link aggregation (LAG)/bonding is active, and +vice versa. To enforce this, the driver checks for this mutual exclusion. + + +Displaying VF Statistics on the PF +---------------------------------- +Use the following command to display the statistics for the PF and its VFs:: + + # ip -s link show dev <ethX> + +NOTE: The output of this command can be very large due to the maximum number of +possible VFs. + +The PF driver will display a subset of the statistics for the PF and for all +VFs that are configured. The PF will always print a statistics block for each +of the possible VFs, and it will show zero for all unconfigured VFs. + + +Configuring VLAN Tagging on SR-IOV Enabled Adapter Ports +-------------------------------------------------------- +To configure VLAN tagging for the ports on an SR-IOV enabled adapter, use the +following command. The VLAN configuration should be done before the VF driver +is loaded or the VM is booted. The VF is not aware of the VLAN tag being +inserted on transmit and removed on received frames (sometimes called "port +VLAN" mode). + +:: + + # ip link set dev <ethX> vf <id> vlan <vlan id> + +For example, the following will configure PF eth0 and the first VF on VLAN 10:: + + # ip link set dev eth0 vf 0 vlan 10 + + +Enabling a VF link if the port is disconnected +---------------------------------------------- +If the physical function (PF) link is down, you can force link up (from the +host PF) on any virtual functions (VF) bound to the PF. + +For example, to force link up on VF 0 bound to PF eth0:: + + # ip link set eth0 vf 0 state enable + +Note: If the command does not work, it may not be supported by your system. + + +Setting the MAC Address for a VF +-------------------------------- +To change the MAC address for the specified VF:: + + # ip link set <ethX> vf 0 mac <address> + +For example:: + + # ip link set <ethX> vf 0 mac 00:01:02:03:04:05 + +This setting lasts until the PF is reloaded. + +NOTE: Assigning a MAC address for a VF from the host will disable any +subsequent requests to change the MAC address from within the VM. This is a +security feature. The VM is not aware of this restriction, so if this is +attempted in the VM, it will trigger MDD events. + + +Trusted VFs and VF Promiscuous Mode +----------------------------------- +This feature allows you to designate a particular VF as trusted and allows that +trusted VF to request selective promiscuous mode on the Physical Function (PF). + +To set a VF as trusted or untrusted, enter the following command in the +Hypervisor:: + + # ip link set dev <ethX> vf 1 trust [on|off] + +NOTE: It's important to set the VF to trusted before setting promiscuous mode. +If the VM is not trusted, the PF will ignore promiscuous mode requests from the +VF. If the VM becomes trusted after the VF driver is loaded, you must make a +new request to set the VF to promiscuous. + +Once the VF is designated as trusted, use the following commands in the VM to +set the VF to promiscuous mode. + +For promiscuous all:: + + # ip link set <ethX> promisc on + Where <ethX> is a VF interface in the VM + +For promiscuous Multicast:: + + # ip link set <ethX> allmulticast on + Where <ethX> is a VF interface in the VM + +NOTE: By default, the ethtool private flag vf-true-promisc-support is set to +"off," meaning that promiscuous mode for the VF will be limited. To set the +promiscuous mode for the VF to true promiscuous and allow the VF to see all +ingress traffic, use the following command:: + + # ethtool --set-priv-flags <ethX> vf-true-promisc-support on + +The vf-true-promisc-support private flag does not enable promiscuous mode; +rather, it designates which type of promiscuous mode (limited or true) you will +get when you enable promiscuous mode using the ip link commands above. Note +that this is a global setting that affects the entire device. However, the +vf-true-promisc-support private flag is only exposed to the first PF of the +device. The PF remains in limited promiscuous mode regardless of the +vf-true-promisc-support setting. + +Next, add a VLAN interface on the VF interface. For example:: + + # ip link add link eth2 name eth2.100 type vlan id 100 + +Note that the order in which you set the VF to promiscuous mode and add the +VLAN interface does not matter (you can do either first). The result in this +example is that the VF will get all traffic that is tagged with VLAN 100. + + +Malicious Driver Detection (MDD) for VFs +---------------------------------------- +Some Intel Ethernet devices use Malicious Driver Detection (MDD) to detect +malicious traffic from the VF and disable Tx/Rx queues or drop the offending +packet until a VF driver reset occurs. You can view MDD messages in the PF's +system log using the dmesg command. + +- If the PF driver logs MDD events from the VF, confirm that the correct VF + driver is installed. +- To restore functionality, you can manually reload the VF or VM or enable + automatic VF resets. +- When automatic VF resets are enabled, the PF driver will immediately reset + the VF and reenable queues when it detects MDD events on the receive path. +- If automatic VF resets are disabled, the PF will not automatically reset the + VF when it detects MDD events. + +To enable or disable automatic VF resets, use the following command:: + + # ethtool --set-priv-flags <ethX> mdd-auto-reset-vf on|off + + +MAC and VLAN Anti-Spoofing Feature for VFs +------------------------------------------ +When a malicious driver on a Virtual Function (VF) interface attempts to send a +spoofed packet, it is dropped by the hardware and not transmitted. + +NOTE: This feature can be disabled for a specific VF:: + + # ip link set <ethX> vf <vf id> spoofchk {off|on} + + +Jumbo Frames +------------ +Jumbo Frames support is enabled by changing the Maximum Transmission Unit (MTU) +to a value larger than the default value of 1500. + +Use the ifconfig command to increase the MTU size. For example, enter the +following where <ethX> is the interface number:: + + # ifconfig <ethX> mtu 9000 up + +Alternatively, you can use the ip command as follows:: + + # ip link set mtu 9000 dev <ethX> + # ip link set up dev <ethX> + +This setting is not saved across reboots. + + +NOTE: The maximum MTU setting for jumbo frames is 9702. This corresponds to the +maximum jumbo frame size of 9728 bytes. + +NOTE: This driver will attempt to use multiple page sized buffers to receive +each jumbo packet. This should help to avoid buffer starvation issues when +allocating receive packets. + +NOTE: Packet loss may have a greater impact on throughput when you use jumbo +frames. If you observe a drop in performance after enabling jumbo frames, +enabling flow control may mitigate the issue. + + +Speed and Duplex Configuration +------------------------------ +In addressing speed and duplex configuration issues, you need to distinguish +between copper-based adapters and fiber-based adapters. + +In the default mode, an Intel(R) Ethernet Network Adapter using copper +connections will attempt to auto-negotiate with its link partner to determine +the best setting. If the adapter cannot establish link with the link partner +using auto-negotiation, you may need to manually configure the adapter and link +partner to identical settings to establish link and pass packets. This should +only be needed when attempting to link with an older switch that does not +support auto-negotiation or one that has been forced to a specific speed or +duplex mode. Your link partner must match the setting you choose. 1 Gbps speeds +and higher cannot be forced. Use the autonegotiation advertising setting to +manually set devices for 1 Gbps and higher. + +Speed, duplex, and autonegotiation advertising are configured through the +ethtool utility. For the latest version, download and install ethtool from the +following website: + + https://kernel.org/pub/software/network/ethtool/ + +To see the speed configurations your device supports, run the following:: + + # ethtool <ethX> + +Caution: Only experienced network administrators should force speed and duplex +or change autonegotiation advertising manually. The settings at the switch must +always match the adapter settings. Adapter performance may suffer or your +adapter may not operate if you configure the adapter differently from your +switch. + + +Data Center Bridging (DCB) +-------------------------- +NOTE: The kernel assumes that TC0 is available, and will disable Priority Flow +Control (PFC) on the device if TC0 is not available. To fix this, ensure TC0 is +enabled when setting up DCB on your switch. + +DCB is a configuration Quality of Service implementation in hardware. It uses +the VLAN priority tag (802.1p) to filter traffic. That means that there are 8 +different priorities that traffic can be filtered into. It also enables +priority flow control (802.1Qbb) which can limit or eliminate the number of +dropped packets during network stress. Bandwidth can be allocated to each of +these priorities, which is enforced at the hardware level (802.1Qaz). + +DCB is normally configured on the network using the DCBX protocol (802.1Qaz), a +specialization of LLDP (802.1AB). The ice driver supports the following +mutually exclusive variants of DCBX support: + +1) Firmware-based LLDP Agent +2) Software-based LLDP Agent + +In firmware-based mode, firmware intercepts all LLDP traffic and handles DCBX +negotiation transparently for the user. In this mode, the adapter operates in +"willing" DCBX mode, receiving DCB settings from the link partner (typically a +switch). The local user can only query the negotiated DCB configuration. For +information on configuring DCBX parameters on a switch, please consult the +switch manufacturer's documentation. + +In software-based mode, LLDP traffic is forwarded to the network stack and user +space, where a software agent can handle it. In this mode, the adapter can +operate in either "willing" or "nonwilling" DCBX mode and DCB configuration can +be both queried and set locally. This mode requires the FW-based LLDP Agent to +be disabled. + +NOTE: + +- You can enable and disable the firmware-based LLDP Agent using an ethtool + private flag. Refer to the "FW-LLDP (Firmware Link Layer Discovery Protocol)" + section in this README for more information. +- In software-based DCBX mode, you can configure DCB parameters using software + LLDP/DCBX agents that interface with the Linux kernel's DCB Netlink API. We + recommend using OpenLLDP as the DCBX agent when running in software mode. For + more information, see the OpenLLDP man pages and + https://github.com/intel/openlldp. +- The driver implements the DCB netlink interface layer to allow the user space + to communicate with the driver and query DCB configuration for the port. +- iSCSI with DCB is not supported. + + +FW-LLDP (Firmware Link Layer Discovery Protocol) +------------------------------------------------ +Use ethtool to change FW-LLDP settings. The FW-LLDP setting is per port and +persists across boots. + +To enable LLDP:: + + # ethtool --set-priv-flags <ethX> fw-lldp-agent on + +To disable LLDP:: + + # ethtool --set-priv-flags <ethX> fw-lldp-agent off + +To check the current LLDP setting:: + + # ethtool --show-priv-flags <ethX> + +NOTE: You must enable the UEFI HII "LLDP Agent" attribute for this setting to +take effect. If "LLDP AGENT" is set to disabled, you cannot enable it from the +OS. + + +Flow Control +------------ +Ethernet Flow Control (IEEE 802.3x) can be configured with ethtool to enable +receiving and transmitting pause frames for ice. When transmit is enabled, +pause frames are generated when the receive packet buffer crosses a predefined +threshold. When receive is enabled, the transmit unit will halt for the time +delay specified when a pause frame is received. + +NOTE: You must have a flow control capable link partner. + +Flow Control is disabled by default. + +Use ethtool to change the flow control settings. + +To enable or disable Rx or Tx Flow Control:: + + # ethtool -A <ethX> rx <on|off> tx <on|off> + +Note: This command only enables or disables Flow Control if auto-negotiation is +disabled. If auto-negotiation is enabled, this command changes the parameters +used for auto-negotiation with the link partner. + +Note: Flow Control auto-negotiation is part of link auto-negotiation. Depending +on your device, you may not be able to change the auto-negotiation setting. + +NOTE: + +- The ice driver requires flow control on both the port and link partner. If + flow control is disabled on one of the sides, the port may appear to hang on + heavy traffic. +- You may encounter issues with link-level flow control (LFC) after disabling + DCB. The LFC status may show as enabled but traffic is not paused. To resolve + this issue, disable and reenable LFC using ethtool:: + + # ethtool -A <ethX> rx off tx off + # ethtool -A <ethX> rx on tx on + + +NAPI +---- +This driver supports NAPI (Rx polling mode). +For more information on NAPI, see +https://www.linuxfoundation.org/collaborate/workgroups/networking/napi + + +MACVLAN +------- +This driver supports MACVLAN. Kernel support for MACVLAN can be tested by +checking if the MACVLAN driver is loaded. You can run 'lsmod | grep macvlan' to +see if the MACVLAN driver is loaded or run 'modprobe macvlan' to try to load +the MACVLAN driver. + +NOTE: + +- In passthru mode, you can only set up one MACVLAN device. It will inherit the + MAC address of the underlying PF (Physical Function) device. + + +IEEE 802.1ad (QinQ) Support +--------------------------- +The IEEE 802.1ad standard, informally known as QinQ, allows for multiple VLAN +IDs within a single Ethernet frame. VLAN IDs are sometimes referred to as +"tags," and multiple VLAN IDs are thus referred to as a "tag stack." Tag stacks +allow L2 tunneling and the ability to segregate traffic within a particular +VLAN ID, among other uses. + +NOTES: + +- Receive checksum offloads and VLAN acceleration are not supported for 802.1ad + (QinQ) packets. + +- 0x88A8 traffic will not be received unless VLAN stripping is disabled with + the following command:: + + # ethool -K <ethX> rxvlan off + +- 0x88A8/0x8100 double VLANs cannot be used with 0x8100 or 0x8100/0x8100 VLANS + configured on the same port. 0x88a8/0x8100 traffic will not be received if + 0x8100 VLANs are configured. + +- The VF can only transmit 0x88A8/0x8100 (i.e., 802.1ad/802.1Q) traffic if: + + 1) The VF is not assigned a port VLAN. + 2) spoofchk is disabled from the PF. If you enable spoofchk, the VF will + not transmit 0x88A8/0x8100 traffic. + +- The VF may not receive all network traffic based on the Inner VLAN header + when VF true promiscuous mode (vf-true-promisc-support) and double VLANs are + enabled in SR-IOV mode. + +The following are examples of how to configure 802.1ad (QinQ):: + + # ip link add link eth0 eth0.24 type vlan proto 802.1ad id 24 + # ip link add link eth0.24 eth0.24.371 type vlan proto 802.1Q id 371 + + Where "24" and "371" are example VLAN IDs. + + +Tunnel/Overlay Stateless Offloads +--------------------------------- +Supported tunnels and overlays include VXLAN, GENEVE, and others depending on +hardware and software configuration. Stateless offloads are enabled by default. + +To view the current state of all offloads:: + + # ethtool -k <ethX> + + +UDP Segmentation Offload +------------------------ +Allows the adapter to offload transmit segmentation of UDP packets with +payloads up to 64K into valid Ethernet frames. Because the adapter hardware is +able to complete data segmentation much faster than operating system software, +this feature may improve transmission performance. +In addition, the adapter may use fewer CPU resources. + +NOTE: + +- The application sending UDP packets must support UDP segmentation offload. + +To enable/disable UDP Segmentation Offload, issue the following command:: + + # ethtool -K <ethX> tx-udp-segmentation [off|on] + + +Performance Optimization +======================== +Driver defaults are meant to fit a wide variety of workloads, but if further +optimization is required, we recommend experimenting with the following +settings. + + +Rx Descriptor Ring Size +----------------------- +To reduce the number of Rx packet discards, increase the number of Rx +descriptors for each Rx ring using ethtool. + + Check if the interface is dropping Rx packets due to buffers being full + (rx_dropped.nic can mean that there is no PCIe bandwidth):: + + # ethtool -S <ethX> | grep "rx_dropped" + + If the previous command shows drops on queues, it may help to increase + the number of descriptors using 'ethtool -G':: + + # ethtool -G <ethX> rx <N> + Where <N> is the desired number of ring entries/descriptors + + This can provide temporary buffering for issues that create latency while + the CPUs process descriptors. + + +Interrupt Rate Limiting +----------------------- +This driver supports an adaptive interrupt throttle rate (ITR) mechanism that +is tuned for general workloads. The user can customize the interrupt rate +control for specific workloads, via ethtool, adjusting the number of +microseconds between interrupts. + +To set the interrupt rate manually, you must disable adaptive mode:: + + # ethtool -C <ethX> adaptive-rx off adaptive-tx off + +For lower CPU utilization: + + Disable adaptive ITR and lower Rx and Tx interrupts. The examples below + affect every queue of the specified interface. + + Setting rx-usecs and tx-usecs to 80 will limit interrupts to about + 12,500 interrupts per second per queue:: + + # ethtool -C <ethX> adaptive-rx off adaptive-tx off rx-usecs 80 tx-usecs 80 + +For reduced latency: + + Disable adaptive ITR and ITR by setting rx-usecs and tx-usecs to 0 + using ethtool:: + + # ethtool -C <ethX> adaptive-rx off adaptive-tx off rx-usecs 0 tx-usecs 0 + +Per-queue interrupt rate settings: + + The following examples are for queues 1 and 3, but you can adjust other + queues. + + To disable Rx adaptive ITR and set static Rx ITR to 10 microseconds or + about 100,000 interrupts/second, for queues 1 and 3:: + + # ethtool --per-queue <ethX> queue_mask 0xa --coalesce adaptive-rx off + rx-usecs 10 + + To show the current coalesce settings for queues 1 and 3:: + + # ethtool --per-queue <ethX> queue_mask 0xa --show-coalesce + +Bounding interrupt rates using rx-usecs-high: + + :Valid Range: 0-236 (0=no limit) + + The range of 0-236 microseconds provides an effective range of 4,237 to + 250,000 interrupts per second. The value of rx-usecs-high can be set + independently of rx-usecs and tx-usecs in the same ethtool command, and is + also independent of the adaptive interrupt moderation algorithm. The + underlying hardware supports granularity in 4-microsecond intervals, so + adjacent values may result in the same interrupt rate. + + The following command would disable adaptive interrupt moderation, and allow + a maximum of 5 microseconds before indicating a receive or transmit was + complete. However, instead of resulting in as many as 200,000 interrupts per + second, it limits total interrupts per second to 50,000 via the rx-usecs-high + parameter. + + :: + + # ethtool -C <ethX> adaptive-rx off adaptive-tx off rx-usecs-high 20 + rx-usecs 5 tx-usecs 5 + + +Virtualized Environments +------------------------ +In addition to the other suggestions in this section, the following may be +helpful to optimize performance in VMs. + + Using the appropriate mechanism (vcpupin) in the VM, pin the CPUs to + individual LCPUs, making sure to use a set of CPUs included in the + device's local_cpulist: ``/sys/class/net/<ethX>/device/local_cpulist``. + + Configure as many Rx/Tx queues in the VM as available. (See the iavf driver + documentation for the number of queues supported.) For example:: + + # ethtool -L <virt_interface> rx <max> tx <max> - -> Device Drivers - -> Network device support (NETDEVICES [=y]) - -> Ethernet driver support - -> Intel devices - -> Intel(R) Ethernet Connection E800 Series Support Support ======= For general information, go to the Intel support website at: - https://www.intel.com/support/ or the Intel Wired Networking project hosted by Sourceforge at: - https://sourceforge.net/projects/e1000 If an issue is identified with the released source code on a supported kernel with a supported adapter, email the specific information related to the issue to e1000-devel@lists.sf.net. + + +Trademarks +========== +Intel is a trademark or registered trademark of Intel Corporation or its +subsidiaries in the United States and/or other countries. + +* Other names and brands may be claimed as the property of others. diff --git a/Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst b/Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst index 61e850460e18..dd5cd69467be 100644 --- a/Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst +++ b/Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst @@ -217,3 +217,73 @@ For example:: NPA_AF_ERR: NPA Error Interrupt Reg : 4096 AQ Doorbell Error + + +NIX Reporters +------------- +The NIX reporters are responsible for reporting and recovering the following group of errors: + +1. GENERAL events + + - Receive mirror/multicast packet drop due to insufficient buffer. + - SMQ Flush operation. + +2. ERROR events + + - Memory Fault due to WQE read/write from multicast/mirror buffer. + - Receive multicast/mirror replication list error. + - Receive packet on an unmapped PF. + - Fault due to NIX_AQ_INST_S read or NIX_AQ_RES_S write. + - AQ Doorbell Error. + +3. RAS events + + - RAS Error Reporting for NIX Receive Multicast/Mirror Entry Structure. + - RAS Error Reporting for WQE/Packet Data read from Multicast/Mirror Buffer.. + - RAS Error Reporting for NIX_AQ_INST_S/NIX_AQ_RES_S. + +4. RVU events + + - Error due to unmapped slot. + +Sample Output:: + + ~# ./devlink health + pci/0002:01:00.0: + reporter hw_npa_intr + state healthy error 0 recover 0 grace_period 0 auto_recover true auto_dump true + reporter hw_npa_gen + state healthy error 0 recover 0 grace_period 0 auto_recover true auto_dump true + reporter hw_npa_err + state healthy error 0 recover 0 grace_period 0 auto_recover true auto_dump true + reporter hw_npa_ras + state healthy error 0 recover 0 grace_period 0 auto_recover true auto_dump true + reporter hw_nix_intr + state healthy error 1121 recover 1121 last_dump_date 2021-01-19 last_dump_time 05:42:26 grace_period 0 auto_recover true auto_dump true + reporter hw_nix_gen + state healthy error 949 recover 949 last_dump_date 2021-01-19 last_dump_time 05:42:43 grace_period 0 auto_recover true auto_dump true + reporter hw_nix_err + state healthy error 1147 recover 1147 last_dump_date 2021-01-19 last_dump_time 05:42:59 grace_period 0 auto_recover true auto_dump true + reporter hw_nix_ras + state healthy error 409 recover 409 last_dump_date 2021-01-19 last_dump_time 05:43:16 grace_period 0 auto_recover true auto_dump true + +Each reporter dumps the + + - Error Type + - Error Register value + - Reason in words + +For example:: + + ~# devlink health dump show pci/0002:01:00.0 reporter hw_nix_intr + NIX_AF_RVU: + NIX RVU Interrupt Reg : 1 + Unmap Slot Error + ~# devlink health dump show pci/0002:01:00.0 reporter hw_nix_gen + NIX_AF_GENERAL: + NIX General Interrupt Reg : 1 + Rx multicast pkt drop + ~# devlink health dump show pci/0002:01:00.0 reporter hw_nix_err + NIX_AF_ERR: + NIX Error Interrupt Reg : 64 + Rx on unmapped PF_FUNC diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst index e9b65035cd47..1b7e32d8a61b 100644 --- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst @@ -12,11 +12,13 @@ Contents - `Enabling the driver and kconfig options`_ - `Devlink info`_ - `Devlink parameters`_ +- `mlx5 subfunction`_ +- `mlx5 function attributes`_ - `Devlink health reporters`_ - `mlx5 tracepoints`_ Enabling the driver and kconfig options -================================================ +======================================= | mlx5 core is modular and most of the major mlx5 core driver features can be selected (compiled in/out) | at build time via kernel Kconfig flags. @@ -97,6 +99,11 @@ Enabling the driver and kconfig options | Provides low-level InfiniBand/RDMA and `RoCE <https://community.mellanox.com/s/article/recommended-network-configuration-examples-for-roce-deployment>`_ support. +**CONFIG_MLX5_SF=(y/n)** + +| Build support for subfunction. +| Subfunctons are more light weight than PCI SRIOV VFs. Choosing this option +| will enable support for creating subfunction devices. **External options** ( Choose if the corresponding mlx5 feature is required ) @@ -176,6 +183,214 @@ User command examples: values: cmode driverinit value true +mlx5 subfunction +================ +mlx5 supports subfunction management using devlink port (see :ref:`Documentation/networking/devlink/devlink-port.rst <devlink_port>`) interface. + +A Subfunction has its own function capabilities and its own resources. This +means a subfunction has its own dedicated queues (txq, rxq, cq, eq). These +queues are neither shared nor stolen from the parent PCI function. + +When a subfunction is RDMA capable, it has its own QP1, GID table and rdma +resources neither shared nor stolen from the parent PCI function. + +A subfunction has a dedicated window in PCI BAR space that is not shared +with ther other subfunctions or the parent PCI function. This ensures that all +devices (netdev, rdma, vdpa etc.) of the subfunction accesses only assigned +PCI BAR space. + +A Subfunction supports eswitch representation through which it supports tc +offloads. The user configures eswitch to send/receive packets from/to +the subfunction port. + +Subfunctions share PCI level resources such as PCI MSI-X IRQs with +other subfunctions and/or with its parent PCI function. + +Example mlx5 software, system and device view:: + + _______ + | admin | + | user |---------- + |_______| | + | | + ____|____ __|______ _________________ + | | | | | | + | devlink | | tc tool | | user | + | tool | |_________| | applications | + |_________| | |_________________| + | | | | + | | | | Userspace + +---------|-------------|-------------------|----------|--------------------+ + | | +----------+ +----------+ Kernel + | | | netdev | | rdma dev | + | | +----------+ +----------+ + (devlink port add/del | ^ ^ + port function set) | | | + | | +---------------| + _____|___ | | _______|_______ + | | | | | mlx5 class | + | devlink | +------------+ | | drivers | + | kernel | | rep netdev | | |(mlx5_core,ib) | + |_________| +------------+ | |_______________| + | | | ^ + (devlink ops) | | (probe/remove) + _________|________ | | ____|________ + | subfunction | | +---------------+ | subfunction | + | management driver|----- | subfunction |---| driver | + | (mlx5_core) | | auxiliary dev | | (mlx5_core) | + |__________________| +---------------+ |_____________| + | ^ + (sf add/del, vhca events) | + | (device add/del) + _____|____ ____|________ + | | | subfunction | + | PCI NIC |---- activate/deactive events---->| host driver | + |__________| | (mlx5_core) | + |_____________| + +Subfunction is created using devlink port interface. + +- Change device to switchdev mode:: + + $ devlink dev eswitch set pci/0000:06:00.0 mode switchdev + +- Add a devlink port of subfunction flaovur:: + + $ devlink port add pci/0000:06:00.0 flavour pcisf pfnum 0 sfnum 88 + pci/0000:06:00.0/32768: type eth netdev eth6 flavour pcisf controller 0 pfnum 0 sfnum 88 external false splittable false + function: + hw_addr 00:00:00:00:00:00 state inactive opstate detached + +- Show a devlink port of the subfunction:: + + $ devlink port show pci/0000:06:00.0/32768 + pci/0000:06:00.0/32768: type eth netdev enp6s0pf0sf88 flavour pcisf pfnum 0 sfnum 88 + function: + hw_addr 00:00:00:00:00:00 state inactive opstate detached + +- Delete a devlink port of subfunction after use:: + + $ devlink port del pci/0000:06:00.0/32768 + +mlx5 function attributes +======================== +The mlx5 driver provides a mechanism to setup PCI VF/SF function attributes in +a unified way for SmartNIC and non-SmartNIC. + +This is supported only when the eswitch mode is set to switchdev. Port function +configuration of the PCI VF/SF is supported through devlink eswitch port. + +Port function attributes should be set before PCI VF/SF is enumerated by the +driver. + +MAC address setup +----------------- +mlx5 driver provides mechanism to setup the MAC address of the PCI VF/SF. + +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 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 + +SF state setup +-------------- +To use the SF, the user must active the SF using the SF function state +attribute. + +- Get the state of the SF identified by its unique devlink port index:: + + $ devlink port show ens2f0npf0sf88 + pci/0000:06:00.0/32768: type eth netdev ens2f0npf0sf88 flavour pcisf controller 0 pfnum 0 sfnum 88 external false splittable false + function: + hw_addr 00:00:00:00:88:88 state inactive opstate detached + +- Activate the function and verify its state is active:: + + $ devlink port function set ens2f0npf0sf88 state active + + $ devlink port show ens2f0npf0sf88 + pci/0000:06:00.0/32768: type eth netdev ens2f0npf0sf88 flavour pcisf controller 0 pfnum 0 sfnum 88 external false splittable false + function: + hw_addr 00:00:00:00:88:88 state active opstate detached + +Upon function activation, the PF driver instance gets the event from the device +that a particular SF was activated. It's the cue to put the device on bus, probe +it and instantiate the devlink instance and class specific auxiliary devices +for it. + +- Show the auxiliary device and port of the subfunction:: + + $ devlink dev show + devlink dev show auxiliary/mlx5_core.sf.4 + + $ devlink port show auxiliary/mlx5_core.sf.4/1 + auxiliary/mlx5_core.sf.4/1: type eth netdev p0sf88 flavour virtual port 0 splittable false + + $ rdma link show mlx5_0/1 + link mlx5_0/1 state ACTIVE physical_state LINK_UP netdev p0sf88 + + $ rdma dev show + 8: rocep6s0f1: node_type ca fw 16.29.0550 node_guid 248a:0703:00b3:d113 sys_image_guid 248a:0703:00b3:d112 + 13: mlx5_0: node_type ca fw 16.29.0550 node_guid 0000:00ff:fe00:8888 sys_image_guid 248a:0703:00b3:d112 + +- Subfunction auxiliary device and class device hierarchy:: + + mlx5_core.sf.4 + (subfunction auxiliary device) + /\ + / \ + / \ + / \ + / \ + mlx5_core.eth.4 mlx5_core.rdma.4 + (sf eth aux dev) (sf rdma aux dev) + | | + | | + p0sf88 mlx5_0 + (sf netdev) (sf rdma device) + +Additionally, the SF port also gets the event when the driver attaches to the +auxiliary device of the subfunction. This results in changing the operational +state of the function. This provides visiblity to the user to decide when is it +safe to delete the SF port for graceful termination of the subfunction. + +- Show the SF port operational state:: + + $ devlink port show ens2f0npf0sf88 + pci/0000:06:00.0/32768: type eth netdev ens2f0npf0sf88 flavour pcisf controller 0 pfnum 0 sfnum 88 external false splittable false + function: + hw_addr 00:00:00:00:88:88 state active opstate attached + Devlink health reporters ======================== diff --git a/Documentation/networking/device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst b/Documentation/networking/device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst new file mode 100644 index 000000000000..f24adfab6a1b --- /dev/null +++ b/Documentation/networking/device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst @@ -0,0 +1,143 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================================================== +Texas Instruments K3 AM65 CPSW NUSS switchdev based ethernet driver +=================================================================== + +:Version: 1.0 + +Port renaming +============= + +In order to rename via udev:: + + ip -d link show dev sw0p1 | grep switchid + + SUBSYSTEM=="net", ACTION=="add", ATTR{phys_switch_id}==<switchid>, \ + ATTR{phys_port_name}!="", NAME="sw0$attr{phys_port_name}" + + +Multi mac mode +============== + +- The driver is operating in multi-mac mode by default, thus + working as N individual network interfaces. + +Devlink configuration parameters +================================ + +See Documentation/networking/devlink/am65-nuss-cpsw-switch.rst + +Enabling "switch" +================= + +The Switch mode can be enabled by configuring devlink driver parameter +"switch_mode" to 1/true:: + + devlink dev param set platform/c000000.ethernet \ + name switch_mode value true cmode runtime + +This can be done regardless of the state of Port's netdev devices - UP/DOWN, but +Port's netdev devices have to be in UP before joining to the bridge to avoid +overwriting of bridge configuration as CPSW switch driver completely reloads its +configuration when first port changes its state to UP. + +When the both interfaces joined the bridge - CPSW switch driver will enable +marking packets with offload_fwd_mark flag. + +All configuration is implemented via switchdev API. + +Bridge setup +============ + +:: + + devlink dev param set platform/c000000.ethernet \ + name switch_mode value true cmode runtime + + ip link add name br0 type bridge + ip link set dev br0 type bridge ageing_time 1000 + ip link set dev sw0p1 up + ip link set dev sw0p2 up + ip link set dev sw0p1 master br0 + ip link set dev sw0p2 master br0 + + [*] bridge vlan add dev br0 vid 1 pvid untagged self + + [*] if vlan_filtering=1. where default_pvid=1 + + Note. Steps [*] are mandatory. + + +On/off STP +========== + +:: + + ip link set dev BRDEV type bridge stp_state 1/0 + +VLAN configuration +================== + +:: + + bridge vlan add dev br0 vid 1 pvid untagged self <---- add cpu port to VLAN 1 + +Note. This step is mandatory for bridge/default_pvid. + +Add extra VLANs +=============== + + 1. untagged:: + + bridge vlan add dev sw0p1 vid 100 pvid untagged master + bridge vlan add dev sw0p2 vid 100 pvid untagged master + bridge vlan add dev br0 vid 100 pvid untagged self <---- Add cpu port to VLAN100 + + 2. tagged:: + + bridge vlan add dev sw0p1 vid 100 master + bridge vlan add dev sw0p2 vid 100 master + bridge vlan add dev br0 vid 100 pvid tagged self <---- Add cpu port to VLAN100 + +FDBs +---- + +FDBs are automatically added on the appropriate switch port upon detection + +Manually adding FDBs:: + + bridge fdb add aa:bb:cc:dd:ee:ff dev sw0p1 master vlan 100 + bridge fdb add aa:bb:cc:dd:ee:fe dev sw0p2 master <---- Add on all VLANs + +MDBs +---- + +MDBs are automatically added on the appropriate switch port upon detection + +Manually adding MDBs:: + + bridge mdb add dev br0 port sw0p1 grp 239.1.1.1 permanent vid 100 + bridge mdb add dev br0 port sw0p1 grp 239.1.1.1 permanent <---- Add on all VLANs + +Multicast flooding +================== +CPU port mcast_flooding is always on + +Turning flooding on/off on swithch ports: +bridge link set dev sw0p1 mcast_flood on/off + +Access and Trunk port +===================== + +:: + + bridge vlan add dev sw0p1 vid 100 pvid untagged master + bridge vlan add dev sw0p2 vid 100 master + + + bridge vlan add dev br0 vid 100 self + ip link add link br0 name br0.100 type vlan id 100 + +Note. Setting PVID on Bridge device itself works only for +default VLAN (default_pvid). diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index a3113ffd7a16..d8279de7bf25 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -15,6 +15,7 @@ Contents: ethernet/index fddi/index hamradio/index + qlogic/index wan/index wifi/index diff --git a/Documentation/networking/device_drivers/qlogic/index.rst b/Documentation/networking/device_drivers/qlogic/index.rst new file mode 100644 index 000000000000..ad05b04286e4 --- /dev/null +++ b/Documentation/networking/device_drivers/qlogic/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +QLogic QLGE Device Drivers +=============================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + qlge + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/networking/device_drivers/qlogic/qlge.rst b/Documentation/networking/device_drivers/qlogic/qlge.rst new file mode 100644 index 000000000000..0b888253d152 --- /dev/null +++ b/Documentation/networking/device_drivers/qlogic/qlge.rst @@ -0,0 +1,118 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================= +QLogic QLGE 10Gb Ethernet device driver +======================================= + +This driver use drgn and devlink for debugging. + +Dump kernel data structures in drgn +----------------------------------- + +To dump kernel data structures, the following Python script can be used +in drgn: + +.. code-block:: python + + def align(x, a): + """the alignment a should be a power of 2 + """ + mask = a - 1 + return (x+ mask) & ~mask + + def struct_size(struct_type): + struct_str = "struct {}".format(struct_type) + return sizeof(Object(prog, struct_str, address=0x0)) + + def netdev_priv(netdevice): + NETDEV_ALIGN = 32 + return netdevice.value_() + align(struct_size("net_device"), NETDEV_ALIGN) + + name = 'xxx' + qlge_device = None + netdevices = prog['init_net'].dev_base_head.address_of_() + for netdevice in list_for_each_entry("struct net_device", netdevices, "dev_list"): + if netdevice.name.string_().decode('ascii') == name: + print(netdevice.name) + + ql_adapter = Object(prog, "struct ql_adapter", address=netdev_priv(qlge_device)) + +The struct ql_adapter will be printed in drgn as follows, + + >>> ql_adapter + (struct ql_adapter){ + .ricb = (struct ricb){ + .base_cq = (u8)0, + .flags = (u8)120, + .mask = (__le16)26637, + .hash_cq_id = (u8 [1024]){ 172, 142, 255, 255 }, + .ipv6_hash_key = (__le32 [10]){}, + .ipv4_hash_key = (__le32 [4]){}, + }, + .flags = (unsigned long)0, + .wol = (u32)0, + .nic_stats = (struct nic_stats){ + .tx_pkts = (u64)0, + .tx_bytes = (u64)0, + .tx_mcast_pkts = (u64)0, + .tx_bcast_pkts = (u64)0, + .tx_ucast_pkts = (u64)0, + .tx_ctl_pkts = (u64)0, + .tx_pause_pkts = (u64)0, + ... + }, + .active_vlans = (unsigned long [64]){ + 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 52780853100545, 18446744073709551615, + 18446619461681283072, 0, 42949673024, 2147483647, + }, + .rx_ring = (struct rx_ring [17]){ + { + .cqicb = (struct cqicb){ + .msix_vect = (u8)0, + .reserved1 = (u8)0, + .reserved2 = (u8)0, + .flags = (u8)0, + .len = (__le16)0, + .rid = (__le16)0, + ... + }, + .cq_base = (void *)0x0, + .cq_base_dma = (dma_addr_t)0, + } + ... + } + } + +coredump via devlink +-------------------- + + +And the coredump obtained via devlink in json format looks like, + +.. code:: shell + + $ devlink health dump show DEVICE reporter coredump -p -j + { + "Core Registers": { + "segment": 1, + "values": [ 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ] + }, + "Test Logic Regs": { + "segment": 2, + "values": [ 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ] + }, + "RMII Registers": { + "segment": 3, + "values": [ 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ] + }, + ... + "Sem Registers": { + "segment": 50, + "values": [ 0,0,0,0 ] + } + } + +When the module parameter qlge_force_coredump is set to be true, the MPI +RISC reset before coredumping. So coredumping will much longer since +devlink tool has to wait for 5 secs for the resetting to be +finished. diff --git a/Documentation/networking/devlink/am65-nuss-cpsw-switch.rst b/Documentation/networking/devlink/am65-nuss-cpsw-switch.rst new file mode 100644 index 000000000000..1e589c26abff --- /dev/null +++ b/Documentation/networking/devlink/am65-nuss-cpsw-switch.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== +am65-cpsw-nuss devlink support +============================== + +This document describes the devlink features implemented by the ``am65-cpsw-nuss`` +device driver. + +Parameters +========== + +The ``am65-cpsw-nuss`` driver implements the following driver-specific +parameters. + +.. list-table:: Driver-specific parameters implemented + :widths: 5 5 5 85 + + * - Name + - Type + - Mode + - Description + * - ``switch_mode`` + - Boolean + - runtime + - Enable switch mode diff --git a/Documentation/networking/devlink/devlink-port.rst b/Documentation/networking/devlink/devlink-port.rst new file mode 100644 index 000000000000..e99b41599465 --- /dev/null +++ b/Documentation/networking/devlink/devlink-port.rst @@ -0,0 +1,199 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _devlink_port: + +============ +Devlink Port +============ + +``devlink-port`` is a port that exists on the device. It has a logically +separate ingress/egress point of the device. A devlink port can be any one +of many flavours. A devlink port flavour along with port attributes +describe what a port represents. + +A device driver that intends to publish a devlink port sets the +devlink port attributes and registers the devlink port. + +Devlink port flavours are described below. + +.. list-table:: List of devlink port flavours + :widths: 33 90 + + * - Flavour + - Description + * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL`` + - Any kind of physical port. This can be an eswitch physical port or any + other physical port on the device. + * - ``DEVLINK_PORT_FLAVOUR_DSA`` + - This indicates a DSA interconnect port. + * - ``DEVLINK_PORT_FLAVOUR_CPU`` + - This indicates a CPU port applicable only to DSA. + * - ``DEVLINK_PORT_FLAVOUR_PCI_PF`` + - This indicates an eswitch port representing a port of PCI + physical function (PF). + * - ``DEVLINK_PORT_FLAVOUR_PCI_VF`` + - This indicates an eswitch port representing a port of PCI + virtual function (VF). + * - ``DEVLINK_PORT_FLAVOUR_PCI_SF`` + - This indicates an eswitch port representing a port of PCI + subfunction (SF). + * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL`` + - This indicates a virtual port for the PCI virtual function. + +Devlink port can have a different type based on the link layer described below. + +.. list-table:: List of devlink port types + :widths: 23 90 + + * - Type + - Description + * - ``DEVLINK_PORT_TYPE_ETH`` + - Driver should set this port type when a link layer of the port is + Ethernet. + * - ``DEVLINK_PORT_TYPE_IB`` + - Driver should set this port type when a link layer of the port is + InfiniBand. + * - ``DEVLINK_PORT_TYPE_AUTO`` + - This type is indicated by the user when driver should detect the port + type automatically. + +PCI controllers +--------------- +In most cases a PCI device has only one controller. A controller consists of +potentially multiple physical, virtual functions and subfunctions. A function +consists of one or more ports. This port is represented by the devlink eswitch +port. + +A PCI device connected to multiple CPUs or multiple PCI root complexes or a +SmartNIC, however, may have multiple controllers. For a device with multiple +controllers, each controller is distinguished by a unique controller number. +An eswitch is on the PCI device which supports ports of multiple controllers. + +An example view of a system with two controllers:: + + --------------------------------------------------------- + | | + | --------- --------- ------- ------- | + ----------- | | vf(s) | | sf(s) | |vf(s)| |sf(s)| | + | server | | ------- ----/---- ---/----- ------- ---/--- ---/--- | + | pci rc |=== | pf0 |______/________/ | pf1 |___/_______/ | + | connect | | ------- ------- | + ----------- | | controller_num=1 (no eswitch) | + ------|-------------------------------------------------- + (internal wire) + | + --------------------------------------------------------- + | devlink eswitch ports and reps | + | ----------------------------------------------------- | + | |ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 |ctrl-0 | | + | |pf0 | pf0vfN | pf0sfN | pf1 | pf1vfN |pf1sfN | | + | ----------------------------------------------------- | + | |ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 |ctrl-1 | | + | |pf0 | pf0vfN | pf0sfN | pf1 | pf1vfN |pf1sfN | | + | ----------------------------------------------------- | + | | + | | + ----------- | --------- --------- ------- ------- | + | smartNIC| | | vf(s) | | sf(s) | |vf(s)| |sf(s)| | + | pci rc |==| ------- ----/---- ---/----- ------- ---/--- ---/--- | + | connect | | | pf0 |______/________/ | pf1 |___/_______/ | + ----------- | ------- ------- | + | | + | local controller_num=0 (eswitch) | + --------------------------------------------------------- + +In the above example, the external controller (identified by controller number = 1) +doesn't have the eswitch. Local controller (identified by controller number = 0) +has the eswitch. The Devlink instance on the local controller has eswitch +devlink ports for both the controllers. + +Function configuration +====================== + +A user can configure the function attribute 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. +Hence, function attribute should be configured before binding virtual +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 +this means a MAC address. + +Subfunction +============ + +Subfunction is a lightweight function that has a parent PCI function on which +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; + +Subfunction management is done using devlink port user interface. +User performs setup on the subfunction management device. + +(1) Create +---------- +A subfunction is created using a devlink port interface. A user adds the +subfunction by adding a devlink port of subfunction flavour. The devlink +kernel code calls down to subfunction management driver (devlink ops) and asks +it to create a subfunction devlink port. Driver then instantiates the +subfunction port and any associated objects such as health reporters and +representor netdevice. + +(2) Configure +------------- +A subfunction devlink port is created but it is not active yet. That means the +entities are created on devlink side, the e-switch port representor is created, +but the subfunction device itself it not created. A user might use e-switch port +representor to do settings, putting it into bridge, adding TC rules, etc. A user +might as well configure the hardware address (such as MAC address) of the +subfunction while subfunction is inactive. + +(3) Deploy +---------- +Once a subfunction is configured, user must activate it to use it. Upon +activation, subfunction management driver asks the subfunction management +device to instantiate the subfunction device on particular PCI function. +A subfunction device is created on the :ref:`Documentation/driver-api/auxiliary_bus.rst <auxiliary_bus>`. +At this point a matching subfunction driver binds to the subfunction's auxiliary device. + +Terms and Definitions +===================== + +.. list-table:: Terms and Definitions + :widths: 22 90 + + * - Term + - Definitions + * - ``PCI device`` + - A physical PCI device having one or more PCI bus consists of one or + more PCI controllers. + * - ``PCI controller`` + - A controller consists of potentially multiple physical functions, + virtual functions and subfunctions. + * - ``Port function`` + - An object to manage the function of a port. + * - ``Subfunction`` + - A lightweight function that has parent PCI function on which it is + deployed. + * - ``Subfunction device`` + - A bus device of the subfunction, usually on a auxiliary bus. + * - ``Subfunction driver`` + - A device driver for the subfunction auxiliary device. + * - ``Subfunction management device`` + - A PCI physical function that supports subfunction management. + * - ``Subfunction management driver`` + - A device driver for PCI physical function that supports + subfunction management using devlink port interface. + * - ``Subfunction host driver`` + - A device driver for PCI physical function that hosts subfunction + devices. In most cases it is same as subfunction management driver. When + subfunction is used on external controller, subfunction management and + host drivers are different. diff --git a/Documentation/networking/devlink/devlink-resource.rst b/Documentation/networking/devlink/devlink-resource.rst index 93e92d2f0752..3d5ae51e65a2 100644 --- a/Documentation/networking/devlink/devlink-resource.rst +++ b/Documentation/networking/devlink/devlink-resource.rst @@ -23,6 +23,20 @@ current size and related sub resources. To access a sub resource, you specify the path of the resource. For example ``/IPv4/fib`` is the id for the ``fib`` sub-resource under the ``IPv4`` resource. +Generic Resources +================= + +Generic resources are used to describe resources that can be shared by multiple +device drivers and their description must be added to the following table: + +.. list-table:: List of Generic Resources + :widths: 10 90 + + * - Name + - Description + * - ``physical_ports`` + - A limited capacity of physical ports that the switch ASIC can support + example usage ------------- diff --git a/Documentation/networking/devlink/devlink-trap.rst b/Documentation/networking/devlink/devlink-trap.rst index d875f3e1e9cf..935b6397e8cf 100644 --- a/Documentation/networking/devlink/devlink-trap.rst +++ b/Documentation/networking/devlink/devlink-trap.rst @@ -480,6 +480,11 @@ be added to the following table: - ``drop`` - Traps packets that the device decided to drop in case they hit a blackhole nexthop + * - ``dmac_filter`` + - ``drop`` + - 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 Driver-specific Packet Traps ============================ diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst index d82874760ae2..8428a1220723 100644 --- a/Documentation/networking/devlink/index.rst +++ b/Documentation/networking/devlink/index.rst @@ -18,6 +18,7 @@ general. devlink-info devlink-flash devlink-params + devlink-port devlink-region devlink-resource devlink-reload @@ -44,3 +45,4 @@ parameters, info versions, and other features it supports. sja1105 qed ti-cpsw-switch + am65-nuss-cpsw-switch diff --git a/Documentation/networking/dsa/dsa.rst b/Documentation/networking/dsa/dsa.rst index a8d15dd2b42b..e9517af5fe02 100644 --- a/Documentation/networking/dsa/dsa.rst +++ b/Documentation/networking/dsa/dsa.rst @@ -273,10 +273,6 @@ will not make us go through the switch tagging protocol transmit function, so the Ethernet switch on the other end, expecting a tag will typically drop this frame. -Slave network devices check that the master network device is UP before allowing -you to administratively bring UP these slave network devices. A common -configuration mistake is forgetting to bring UP the master network device first. - Interactions with other subsystems ================================== diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst index 30b98245979f..05073482db05 100644 --- a/Documentation/networking/ethtool-netlink.rst +++ b/Documentation/networking/ethtool-netlink.rst @@ -431,16 +431,17 @@ Request contents: ``ETHTOOL_A_LINKMODES_SPEED`` u32 link speed (Mb/s) ``ETHTOOL_A_LINKMODES_DUPLEX`` u8 duplex mode ``ETHTOOL_A_LINKMODES_MASTER_SLAVE_CFG`` u8 Master/slave port mode + ``ETHTOOL_A_LINKMODES_LANES`` u32 lanes ========================================== ====== ========================== ``ETHTOOL_A_LINKMODES_OURS`` bit set allows setting advertised link modes. If autonegotiation is on (either set now or kept from before), advertised modes are not changed (no ``ETHTOOL_A_LINKMODES_OURS`` attribute) and at least one -of speed and duplex is specified, kernel adjusts advertised modes to all -supported modes matching speed, duplex or both (whatever is specified). This -autoselection is done on ethtool side with ioctl interface, netlink interface -is supposed to allow requesting changes without knowing what exactly kernel -supports. +of speed, duplex and lanes is specified, kernel adjusts advertised modes to all +supported modes matching speed, duplex, lanes or all (whatever is specified). +This autoselection is done on ethtool side with ioctl interface, netlink +interface is supposed to allow requesting changes without knowing what exactly +kernel supports. LINKSTATE_GET diff --git a/Documentation/networking/filter.rst b/Documentation/networking/filter.rst index debb59e374de..251c6bd73d15 100644 --- a/Documentation/networking/filter.rst +++ b/Documentation/networking/filter.rst @@ -1006,13 +1006,13 @@ Size modifier is one of ... Mode modifier is one of:: - BPF_IMM 0x00 /* used for 32-bit mov in classic BPF and 64-bit in eBPF */ - BPF_ABS 0x20 - BPF_IND 0x40 - BPF_MEM 0x60 - BPF_LEN 0x80 /* classic BPF only, reserved in eBPF */ - BPF_MSH 0xa0 /* classic BPF only, reserved in eBPF */ - BPF_XADD 0xc0 /* eBPF only, exclusive add */ + BPF_IMM 0x00 /* used for 32-bit mov in classic BPF and 64-bit in eBPF */ + BPF_ABS 0x20 + BPF_IND 0x40 + BPF_MEM 0x60 + BPF_LEN 0x80 /* classic BPF only, reserved in eBPF */ + BPF_MSH 0xa0 /* classic BPF only, reserved in eBPF */ + BPF_ATOMIC 0xc0 /* eBPF only, atomic operations */ eBPF has two non-generic instructions: (BPF_ABS | <size> | BPF_LD) and (BPF_IND | <size> | BPF_LD) which are used to access packet data. @@ -1044,16 +1044,57 @@ Unlike classic BPF instruction set, eBPF has generic load/store operations:: BPF_MEM | <size> | BPF_STX: *(size *) (dst_reg + off) = src_reg BPF_MEM | <size> | BPF_ST: *(size *) (dst_reg + off) = imm32 BPF_MEM | <size> | BPF_LDX: dst_reg = *(size *) (src_reg + off) - BPF_XADD | BPF_W | BPF_STX: lock xadd *(u32 *)(dst_reg + off16) += src_reg - BPF_XADD | BPF_DW | BPF_STX: lock xadd *(u64 *)(dst_reg + off16) += src_reg -Where size is one of: BPF_B or BPF_H or BPF_W or BPF_DW. Note that 1 and -2 byte atomic increments are not supported. +Where size is one of: BPF_B or BPF_H or BPF_W or BPF_DW. -eBPF has one 16-byte instruction: BPF_LD | BPF_DW | BPF_IMM which consists +It also includes atomic operations, which use the immediate field for extra +encoding:: + + .imm = BPF_ADD, .code = BPF_ATOMIC | BPF_W | BPF_STX: lock xadd *(u32 *)(dst_reg + off16) += src_reg + .imm = BPF_ADD, .code = BPF_ATOMIC | BPF_DW | BPF_STX: lock xadd *(u64 *)(dst_reg + off16) += src_reg + +The basic atomic operations supported are:: + + BPF_ADD + BPF_AND + BPF_OR + BPF_XOR + +Each having equivalent semantics with the ``BPF_ADD`` example, that is: the +memory location addresed by ``dst_reg + off`` is atomically modified, with +``src_reg`` as the other operand. If the ``BPF_FETCH`` flag is set in the +immediate, then these operations also overwrite ``src_reg`` with the +value that was in memory before it was modified. + +The more special operations are:: + + BPF_XCHG + +This atomically exchanges ``src_reg`` with the value addressed by ``dst_reg + +off``. :: + + BPF_CMPXCHG + +This atomically compares the value addressed by ``dst_reg + off`` with +``R0``. If they match it is replaced with ``src_reg``. In either case, the +value that was there before is zero-extended and loaded back to ``R0``. + +Note that 1 and 2 byte atomic operations are not supported. + +Clang can generate atomic instructions by default when ``-mcpu=v3`` is +enabled. If a lower version for ``-mcpu`` is set, the only atomic instruction +Clang can generate is ``BPF_ADD`` *without* ``BPF_FETCH``. If you need to enable +the atomics features, while keeping a lower ``-mcpu`` version, you can use +``-Xclang -target-feature -Xclang +alu32``. + +You may encounter ``BPF_XADD`` - this is a legacy name for ``BPF_ATOMIC``, +referring to the exclusive-add operation encoded when the immediate field is +zero. + +eBPF has one 16-byte instruction: ``BPF_LD | BPF_DW | BPF_IMM`` which consists of two consecutive ``struct bpf_insn`` 8-byte blocks and interpreted as single instruction that loads 64-bit immediate value into a dst_reg. -Classic BPF has similar instruction: BPF_LD | BPF_W | BPF_IMM which loads +Classic BPF has similar instruction: ``BPF_LD | BPF_W | BPF_IMM`` which loads 32-bit immediate value into a register. eBPF verifier diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst index fa544e9037b9..c7952ac5bd2f 100644 --- a/Documentation/networking/ip-sysctl.rst +++ b/Documentation/networking/ip-sysctl.rst @@ -178,6 +178,27 @@ min_adv_mss - INTEGER The advertised MSS depends on the first hop route MTU, but will never be lower than this setting. +fib_notify_on_flag_change - INTEGER + Whether to emit RTM_NEWROUTE notifications whenever RTM_F_OFFLOAD/ + RTM_F_TRAP/RTM_F_OFFLOAD_FAILED flags are changed. + + After installing a route to the kernel, user space receives an + acknowledgment, which means the route was installed in the kernel, + but not necessarily in hardware. + It is also possible for a route already installed in hardware to change + its action and therefore its flags. For example, a host route that is + trapping packets can be "promoted" to perform decapsulation following + the installation of an IPinIP/VXLAN tunnel. + The notifications will indicate to user-space the state of the route. + + Default: 0 (Do not emit notifications.) + + Possible values: + + - 0 - Do not emit notifications. + - 1 - Emit notifications. + - 2 - Emit notifications only for RTM_F_OFFLOAD_FAILED flag change. + IP Fragmentation: ipfrag_high_thresh - LONG INTEGER @@ -630,16 +651,15 @@ tcp_rmem - vector of 3 INTEGERs: min, default, max default: initial size of receive buffer used by TCP sockets. This value overrides net.core.rmem_default used by other protocols. - Default: 87380 bytes. This value results in window of 65535 with - default setting of tcp_adv_win_scale and tcp_app_win:0 and a bit - less for default tcp_app_win. See below about these variables. + Default: 131072 bytes. + This value results in initial window of 65535. max: maximal size of receive buffer allowed for automatically selected receiver buffers for TCP socket. This value does not override net.core.rmem_max. Calling setsockopt() with SO_RCVBUF disables automatic tuning of that socket's receive buffer size, in which case this value is ignored. - Default: between 87380B and 6MB, depending on RAM size. + Default: between 131072 and 6MB, depending on RAM size. tcp_sack - BOOLEAN Enable select acknowledgments (SACKS). @@ -1425,6 +1445,25 @@ rp_filter - INTEGER Default value is 0. Note that some distributions enable it in startup scripts. +src_valid_mark - BOOLEAN + - 0 - The fwmark of the packet is not included in reverse path + route lookup. This allows for asymmetric routing configurations + utilizing the fwmark in only one direction, e.g., transparent + proxying. + + - 1 - The fwmark of the packet is included in reverse path route + lookup. This permits rp_filter to function when the fwmark is + used for routing traffic in both directions. + + This setting also affects the utilization of fmwark when + performing source address selection for ICMP replies, or + determining addresses stored for the IPOPT_TS_TSANDADDR and + IPOPT_RR IP options. + + The max value from conf/{all,interface}/src_valid_mark is used. + + Default value is 0. + arp_filter - BOOLEAN - 1 - Allows you to have multiple network interfaces on the same subnet, and have the ARPs for each interface be answered @@ -1775,6 +1814,27 @@ nexthop_compat_mode - BOOLEAN and extraneous notifications. Default: true (backward compat mode) +fib_notify_on_flag_change - INTEGER + Whether to emit RTM_NEWROUTE notifications whenever RTM_F_OFFLOAD/ + RTM_F_TRAP/RTM_F_OFFLOAD_FAILED flags are changed. + + After installing a route to the kernel, user space receives an + acknowledgment, which means the route was installed in the kernel, + but not necessarily in hardware. + It is also possible for a route already installed in hardware to change + its action and therefore its flags. For example, a host route that is + trapping packets can be "promoted" to perform decapsulation following + the installation of an IPinIP/VXLAN tunnel. + The notifications will indicate to user-space the state of the route. + + Default: 0 (Do not emit notifications.) + + Possible values: + + - 0 - Do not emit notifications. + - 1 - Emit notifications. + - 2 - Emit notifications only for RTM_F_OFFLOAD_FAILED flag change. + IPv6 Fragmentation: ip6frag_high_thresh - INTEGER @@ -1883,6 +1943,16 @@ accept_ra_defrtr - BOOLEAN - enabled if accept_ra is enabled. - disabled if accept_ra is disabled. +ra_defrtr_metric - UNSIGNED INTEGER + Route metric for default route learned in Router Advertisement. This value + will be assigned as metric for the default route learned via IPv6 Router + Advertisement. Takes affect only if accept_ra_defrtr is enabled. + + Possible values: + 1 to 0xFFFFFFFF + + Default: IP6_RT_PRIO_USER i.e. 1024. + accept_ra_from_local - BOOLEAN Accept RA with source-address that is found on local machine if the RA is otherwise proper and able to be accepted. diff --git a/Documentation/networking/netdev-FAQ.rst b/Documentation/networking/netdev-FAQ.rst index ae2ae37cd921..a64c01b52b4c 100644 --- a/Documentation/networking/netdev-FAQ.rst +++ b/Documentation/networking/netdev-FAQ.rst @@ -272,6 +272,22 @@ to the mailing list, e.g.:: Posting as one thread is discouraged because it confuses patchwork (as of patchwork 2.2.2). +Can I reproduce the checks from patchwork on my local machine? +-------------------------------------------------------------- + +Checks in patchwork are mostly simple wrappers around existing kernel +scripts, the sources are available at: + +https://github.com/kuba-moo/nipa/tree/master/tests + +Running all the builds and checks locally is a pain, can I post my patches and have the patchwork bot validate them? +-------------------------------------------------------------------------------------------------------------------- + +No, you must ensure that your patches are ready by testing them locally +before posting to the mailing list. The patchwork build bot instance +gets overloaded very easily and netdev@vger really doesn't need more +traffic if we can help it. + Any other tips to help ensure my net/net-next patch gets OK'd? -------------------------------------------------------------- Attention to detail. Re-read your own work as if you were the diff --git a/Documentation/networking/netdev-features.rst b/Documentation/networking/netdev-features.rst index a2d7d7160e39..d7b15bb64deb 100644 --- a/Documentation/networking/netdev-features.rst +++ b/Documentation/networking/netdev-features.rst @@ -182,3 +182,24 @@ stricter than Hardware LRO. A packet stream merged by Hardware GRO must be re-segmentable by GSO or TSO back to the exact original packet stream. Hardware GRO is dependent on RXCSUM since every packet successfully merged by hardware must also have the checksum verified by hardware. + +* hsr-tag-ins-offload + +This should be set for devices which insert an HSR (High-availability Seamless +Redundancy) or PRP (Parallel Redundancy Protocol) tag automatically. + +* hsr-tag-rm-offload + +This should be set for devices which remove HSR (High-availability Seamless +Redundancy) or PRP (Parallel Redundancy Protocol) tags automatically. + +* hsr-fwd-offload + +This should be set for devices which forward HSR (High-availability Seamless +Redundancy) frames from one port to another in hardware. + +* hsr-dup-offload + +This should be set for devices which duplicate outgoing HSR (High-availability +Seamless Redundancy) or PRP (Parallel Redundancy Protocol) tags automatically +frames in hardware. diff --git a/Documentation/networking/phy.rst b/Documentation/networking/phy.rst index b2f7ec794bc8..06adfc2afcf0 100644 --- a/Documentation/networking/phy.rst +++ b/Documentation/networking/phy.rst @@ -216,7 +216,7 @@ put into an unsupported state. Lastly, once the controller is ready to handle network traffic, you call phy_start(phydev). This tells the PAL that you are ready, and configures the PHY to connect to the network. If the MAC interrupt of your network driver -also handles PHY status changes, just set phydev->irq to PHY_IGNORE_INTERRUPT +also handles PHY status changes, just set phydev->irq to PHY_MAC_INTERRUPT before you call phy_start and use phy_mac_interrupt() from the network driver. If you don't want to use interrupts, set phydev->irq to PHY_POLL. phy_start() enables the PHY interrupts (if applicable) and starts the @@ -267,6 +267,12 @@ Some of the interface modes are described below: duplex, pause or other settings. This is dependent on the MAC and/or PHY behaviour. +``PHY_INTERFACE_MODE_5GBASER`` + This is the IEEE 802.3 Clause 129 defined 5GBASE-R protocol. It is + identical to the 10GBASE-R protocol defined in Clause 49, with the + exception that it operates at half the frequency. Please refer to the + IEEE standard for the definition. + ``PHY_INTERFACE_MODE_10GBASER`` This is the IEEE 802.3 Clause 49 defined 10GBASE-R protocol used with various different mediums. Please refer to the IEEE standard for a @@ -286,6 +292,11 @@ Some of the interface modes are described below: Note: due to legacy usage, some 10GBASE-R usage incorrectly makes use of this definition. +``PHY_INTERFACE_MODE_100BASEX`` + This defines IEEE 802.3 Clause 24. The link operates at a fixed data + rate of 125Mpbs using a 4B/5B encoding scheme, resulting in an underlying + data rate of 100Mpbs. + Pause frames / flow control =========================== diff --git a/Documentation/networking/sfp-phylink.rst b/Documentation/networking/sfp-phylink.rst index 5aec7c8857d0..328f8d39eeb3 100644 --- a/Documentation/networking/sfp-phylink.rst +++ b/Documentation/networking/sfp-phylink.rst @@ -163,7 +163,7 @@ this documentation. err = phylink_of_phy_connect(priv->phylink, node, flags); For the most part, ``flags`` can be zero; these flags are passed to - the of_phy_attach() inside this function call if a PHY is specified + the phy_attach_direct() inside this function call if a PHY is specified in the DT node ``node``. ``node`` should be the DT node which contains the network phy property, diff --git a/Documentation/networking/snmp_counter.rst b/Documentation/networking/snmp_counter.rst index 4edd0d38779e..423d138b5ff3 100644 --- a/Documentation/networking/snmp_counter.rst +++ b/Documentation/networking/snmp_counter.rst @@ -314,7 +314,7 @@ https://lwn.net/Articles/576263/ * TcpExtTCPOrigDataSent This counter is explained by `kernel commit f19c29e3e391`_, I pasted the -explaination below:: +explanation below:: TCPOrigDataSent: number of outgoing packets with original data (excluding retransmission but including data-in-SYN). This counter is different from @@ -324,7 +324,7 @@ explaination below:: * TCPSynRetrans This counter is explained by `kernel commit f19c29e3e391`_, I pasted the -explaination below:: +explanation below:: TCPSynRetrans: number of SYN and SYN/ACK retransmits to break down retransmissions into SYN, fast-retransmits, timeout retransmits, etc. @@ -332,7 +332,7 @@ explaination below:: * TCPFastOpenActiveFail This counter is explained by `kernel commit f19c29e3e391`_, I pasted the -explaination below:: +explanation below:: TCPFastOpenActiveFail: Fast Open attempts (SYN/data) failed because the remote does not accept it or the attempts timed out. @@ -382,7 +382,7 @@ Defined in `RFC1213 tcpAttemptFails`_. Defined in `RFC1213 tcpOutRsts`_. The RFC says this counter indicates the 'segments sent containing the RST flag', but in linux kernel, this -couner indicates the segments kerenl tried to send. The sending +counter indicates the segments kernel tried to send. The sending process might be failed due to some errors (e.g. memory alloc failed). .. _RFC1213 tcpOutRsts: https://tools.ietf.org/html/rfc1213#page-52 @@ -700,7 +700,7 @@ SACK option could have up to 4 blocks, they are checked individually. E.g., if 3 blocks of a SACk is invalid, the corresponding counter would be updated 3 times. The comment of the `Add counters for discarded SACK blocks`_ patch has additional -explaination: +explanation: .. _Add counters for discarded SACK blocks: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=18f02545a9a16c9a89778b91a162ad16d510bb32 @@ -829,7 +829,7 @@ PAWS check fails or the received sequence number is out of window. * TcpExtTCPACKSkippedTimeWait -Tha ACK is skipped in Time-Wait status, the reason would be either +The ACK is skipped in Time-Wait status, the reason would be either PAWS check failed or the received sequence number is out of window. * TcpExtTCPACKSkippedChallenge @@ -984,7 +984,7 @@ TcpExtSyncookiesRecv counter wont be updated. Challenge ACK ============= -For details of challenge ACK, please refer the explaination of +For details of challenge ACK, please refer the explanation of TcpExtTCPACKSkippedChallenge. * TcpExtTCPChallengeACK @@ -1002,7 +1002,7 @@ prune ===== When a socket is under memory pressure, the TCP stack will try to reclaim memory from the receiving queue and out of order queue. One of -the reclaiming method is 'collapse', which means allocate a big sbk, +the reclaiming method is 'collapse', which means allocate a big skb, copy the contiguous skbs to the single big skb, and free these contiguous skbs. @@ -1163,7 +1163,7 @@ The server side nstat output:: IpExtOutOctets 52 0.0 IpExtInNoECTPkts 1 0.0 -Input a string in nc client side again ('world' in our exmaple):: +Input a string in nc client side again ('world' in our example):: nstatuser@nstat-a:~$ nc -v nstat-b 9000 Connection to nstat-b 9000 port [tcp/*] succeeded! @@ -1211,7 +1211,7 @@ replied an ACK. But kernel handled them in different ways. When the TCP window scale option is not used, kernel will try to enable fast path immediately when the connection comes into the established state, but if the TCP window scale option is used, kernel will disable the -fast path at first, and try to enable it after kerenl receives +fast path at first, and try to enable it after kernel receives packets. We could use the 'ss' command to verify whether the window scale option is used. e.g. run below command on either server or client:: @@ -1343,7 +1343,7 @@ Check TcpExtTCPAbortOnMemory on client:: nstatuser@nstat-a:~$ nstat | grep -i abort TcpExtTCPAbortOnMemory 54 0.0 -Check orphane socket count on client:: +Check orphaned socket count on client:: nstatuser@nstat-a:~$ ss -s Total: 131 (kernel 0) @@ -1685,7 +1685,7 @@ Send 3 SYN repeatly to nstat-b:: nstatuser@nstat-a:~$ for i in {1..3}; do sudo tcpreplay -i ens3 /tmp/syn_fixcsum.pcap; done -Check snmp cunter on nstat-b:: +Check snmp counter on nstat-b:: nstatuser@nstat-b:~$ nstat | grep -i skip TcpExtTCPACKSkippedSynRecv 1 0.0 @@ -1770,7 +1770,7 @@ string 'foo' in our example:: Connection from nstat-a 42132 received! foo -On nstat-a, the tcpdump should have caputred the ACK. We should check +On nstat-a, the tcpdump should have captured the ACK. We should check the source port numbers of the two nc clients:: nstatuser@nstat-a:~$ ss -ta '( dport = :9000 || dport = :9001 )' | tee @@ -1778,7 +1778,7 @@ the source port numbers of the two nc clients:: ESTAB 0 0 192.168.122.250:50208 192.168.122.251:9000 ESTAB 0 0 192.168.122.250:42132 192.168.122.251:9001 -Run tcprewrite, change port 9001 to port 9000, chagne port 42132 to +Run tcprewrite, change port 9001 to port 9000, change port 42132 to port 50208:: nstatuser@nstat-a:~$ tcprewrite --infile /tmp/seq_pre.pcap --outfile /tmp/seq.pcap -r 9001:9000 -r 42132:50208 --fixcsum diff --git a/Documentation/networking/timestamping.rst b/Documentation/networking/timestamping.rst index 03f7beade470..f682e88fa87e 100644 --- a/Documentation/networking/timestamping.rst +++ b/Documentation/networking/timestamping.rst @@ -55,7 +55,8 @@ struct __kernel_sock_timeval format. SO_TIMESTAMP_OLD returns incorrect timestamps after the year 2038 on 32 bit machines. -1.2 SO_TIMESTAMPNS (also SO_TIMESTAMPNS_OLD and SO_TIMESTAMPNS_NEW): +1.2 SO_TIMESTAMPNS (also SO_TIMESTAMPNS_OLD and SO_TIMESTAMPNS_NEW) +------------------------------------------------------------------- This option is identical to SO_TIMESTAMP except for the returned data type. Its struct timespec allows for higher resolution (ns) timestamps than the diff --git a/Documentation/power/index.rst b/Documentation/power/index.rst index ced8a8007434..a0f5244fb427 100644 --- a/Documentation/power/index.rst +++ b/Documentation/power/index.rst @@ -30,6 +30,7 @@ Power Management userland-swsusp powercap/powercap + powercap/dtpm regulator/consumer regulator/design diff --git a/Documentation/power/powercap/dtpm.rst b/Documentation/power/powercap/dtpm.rst new file mode 100644 index 000000000000..a38dee3d815b --- /dev/null +++ b/Documentation/power/powercap/dtpm.rst @@ -0,0 +1,212 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================================== +Dynamic Thermal Power Management framework +========================================== + +On the embedded world, the complexity of the SoC leads to an +increasing number of hotspots which need to be monitored and mitigated +as a whole in order to prevent the temperature to go above the +normative and legally stated 'skin temperature'. + +Another aspect is to sustain the performance for a given power budget, +for example virtual reality where the user can feel dizziness if the +performance is capped while a big CPU is processing something else. Or +reduce the battery charging because the dissipated power is too high +compared with the power consumed by other devices. + +The user space is the most adequate place to dynamically act on the +different devices by limiting their power given an application +profile: it has the knowledge of the platform. + +The Dynamic Thermal Power Management (DTPM) is a technique acting on +the device power by limiting and/or balancing a power budget among +different devices. + +The DTPM framework provides an unified interface to act on the +device power. + +Overview +======== + +The DTPM framework relies on the powercap framework to create the +powercap entries in the sysfs directory and implement the backend +driver to do the connection with the power manageable device. + +The DTPM is a tree representation describing the power constraints +shared between devices, not their physical positions. + +The nodes of the tree are a virtual description aggregating the power +characteristics of the children nodes and their power limitations. + +The leaves of the tree are the real power manageable devices. + +For instance:: + + SoC + | + `-- pkg + | + |-- pd0 (cpu0-3) + | + `-- pd1 (cpu4-5) + +The pkg power will be the sum of pd0 and pd1 power numbers:: + + SoC (400mW - 3100mW) + | + `-- pkg (400mW - 3100mW) + | + |-- pd0 (100mW - 700mW) + | + `-- pd1 (300mW - 2400mW) + +When the nodes are inserted in the tree, their power characteristics are propagated to the parents:: + + SoC (600mW - 5900mW) + | + |-- pkg (400mW - 3100mW) + | | + | |-- pd0 (100mW - 700mW) + | | + | `-- pd1 (300mW - 2400mW) + | + `-- pd2 (200mW - 2800mW) + +Each node have a weight on a 2^10 basis reflecting the percentage of power consumption along the siblings:: + + SoC (w=1024) + | + |-- pkg (w=538) + | | + | |-- pd0 (w=231) + | | + | `-- pd1 (w=794) + | + `-- pd2 (w=486) + + Note the sum of weights at the same level are equal to 1024. + +When a power limitation is applied to a node, then it is distributed along the children given their weights. For example, if we set a power limitation of 3200mW at the 'SoC' root node, the resulting tree will be:: + + SoC (w=1024) <--- power_limit = 3200mW + | + |-- pkg (w=538) --> power_limit = 1681mW + | | + | |-- pd0 (w=231) --> power_limit = 378mW + | | + | `-- pd1 (w=794) --> power_limit = 1303mW + | + `-- pd2 (w=486) --> power_limit = 1519mW + + +Flat description +---------------- + +A root node is created and it is the parent of all the nodes. This +description is the simplest one and it is supposed to give to user +space a flat representation of all the devices supporting the power +limitation without any power limitation distribution. + +Hierarchical description +------------------------ + +The different devices supporting the power limitation are represented +hierarchically. There is one root node, all intermediate nodes are +grouping the child nodes which can be intermediate nodes also or real +devices. + +The intermediate nodes aggregate the power information and allows to +set the power limit given the weight of the nodes. + +User space API +============== + +As stated in the overview, the DTPM framework is built on top of the +powercap framework. Thus the sysfs interface is the same, please refer +to the powercap documentation for further details. + + * power_uw: Instantaneous power consumption. If the node is an + intermediate node, then the power consumption will be the sum of all + children power consumption. + + * max_power_range_uw: The power range resulting of the maximum power + minus the minimum power. + + * name: The name of the node. This is implementation dependent. Even + if it is not recommended for the user space, several nodes can have + the same name. + + * constraint_X_name: The name of the constraint. + + * constraint_X_max_power_uw: The maximum power limit to be applicable + to the node. + + * constraint_X_power_limit_uw: The power limit to be applied to the + node. If the value contained in constraint_X_max_power_uw is set, + the constraint will be removed. + + * constraint_X_time_window_us: The meaning of this file will depend + on the constraint number. + +Constraints +----------- + + * Constraint 0: The power limitation is immediately applied, without + limitation in time. + +Kernel API +========== + +Overview +-------- + +The DTPM framework has no power limiting backend support. It is +generic and provides a set of API to let the different drivers to +implement the backend part for the power limitation and create the +power constraints tree. + +It is up to the platform to provide the initialization function to +allocate and link the different nodes of the tree. + +A special macro has the role of declaring a node and the corresponding +initialization function via a description structure. This one contains +an optional parent field allowing to hook different devices to an +already existing tree at boot time. + +For instance:: + + struct dtpm_descr my_descr = { + .name = "my_name", + .init = my_init_func, + }; + + DTPM_DECLARE(my_descr); + +The nodes of the DTPM tree are described with dtpm structure. The +steps to add a new power limitable device is done in three steps: + + * Allocate the dtpm node + * Set the power number of the dtpm node + * Register the dtpm node + +The registration of the dtpm node is done with the powercap +ops. Basically, it must implements the callbacks to get and set the +power and the limit. + +Alternatively, if the node to be inserted is an intermediate one, then +a simple function to insert it as a future parent is available. + +If a device has its power characteristics changing, then the tree must +be updated with the new power numbers and weights. + +Nomenclature +------------ + + * dtpm_alloc() : Allocate and initialize a dtpm structure + + * dtpm_register() : Add the dtpm node to the tree + + * dtpm_unregister() : Remove the dtpm node from the tree + + * dtpm_update_power() : Update the power characteristics of the dtpm node diff --git a/Documentation/power/runtime_pm.rst b/Documentation/power/runtime_pm.rst index 0553008b6279..d9c777b18f7a 100644 --- a/Documentation/power/runtime_pm.rst +++ b/Documentation/power/runtime_pm.rst @@ -579,7 +579,7 @@ should be used. Of course, for this purpose the device's runtime PM has to be enabled earlier by calling pm_runtime_enable(). Note, if the device may execute pm_runtime calls during the probe (such as -if it is registers with a subsystem that may call back in) then the +if it is registered with a subsystem that may call back in) then the pm_runtime_get_sync() call paired with a pm_runtime_put() call will be appropriate to ensure that the device is not put back to sleep during the probe. This can happen with systems such as the network device layer. @@ -587,11 +587,11 @@ probe. This can happen with systems such as the network device layer. It may be desirable to suspend the device once ->probe() has finished. Therefore the driver core uses the asynchronous pm_request_idle() to submit a request to execute the subsystem-level idle callback for the device at that -time. A driver that makes use of the runtime autosuspend feature, may want to +time. A driver that makes use of the runtime autosuspend feature may want to update the last busy mark before returning from ->probe(). Moreover, the driver core prevents runtime PM callbacks from racing with the bus -notifier callback in __device_release_driver(), which is necessary, because the +notifier callback in __device_release_driver(), which is necessary because the notifier is used by some subsystems to carry out operations affecting the runtime PM functionality. It does so by calling pm_runtime_get_sync() before driver_sysfs_remove() and the BUS_NOTIFY_UNBIND_DRIVER notifications. This @@ -603,7 +603,7 @@ calling pm_runtime_suspend() from their ->remove() routines, the driver core executes pm_runtime_put_sync() after running the BUS_NOTIFY_UNBIND_DRIVER notifications in __device_release_driver(). This requires bus types and drivers to make their ->remove() callbacks avoid races with runtime PM directly, -but also it allows of more flexibility in the handling of devices during the +but it also allows more flexibility in the handling of devices during the removal of their drivers. Drivers in ->remove() callback should undo the runtime PM changes done @@ -693,7 +693,7 @@ that the device appears to be runtime-suspended and its state is fine, so it may be left in runtime suspend provided that all of its descendants are also left in runtime suspend. If that happens, the PM core will not execute any system suspend and resume callbacks for all of those devices, except for the -complete callback, which is then entirely responsible for handling the device +.complete() callback, which is then entirely responsible for handling the device as appropriate. This only applies to system suspend transitions that are not related to hibernation (see Documentation/driver-api/pm/devices.rst for more information). @@ -706,7 +706,7 @@ out the following operations: right before executing the subsystem-level .prepare() callback for it and pm_runtime_barrier() is called for every device right before executing the subsystem-level .suspend() callback for it. In addition to that the PM core - calls __pm_runtime_disable() with 'false' as the second argument for every + calls __pm_runtime_disable() with 'false' as the second argument for every device right before executing the subsystem-level .suspend_late() callback for it. @@ -783,7 +783,7 @@ driver/base/power/generic_ops.c: `int pm_generic_restore_noirq(struct device *dev);` - invoke the ->restore_noirq() callback provided by the device's driver -These functions are the defaults used by the PM core, if a subsystem doesn't +These functions are the defaults used by the PM core if a subsystem doesn't provide its own callbacks for ->runtime_idle(), ->runtime_suspend(), ->runtime_resume(), ->suspend(), ->suspend_noirq(), ->resume(), ->resume_noirq(), ->freeze(), ->freeze_noirq(), ->thaw(), ->thaw_noirq(), diff --git a/Documentation/process/magic-number.rst b/Documentation/process/magic-number.rst index e02ff5ffb653..c6dfe060ec2f 100644 --- a/Documentation/process/magic-number.rst +++ b/Documentation/process/magic-number.rst @@ -135,7 +135,6 @@ FW_HEADER_MAGIC 0x65726F66 fw_header ``drivers/atm/fo SLOT_MAGIC 0x67267321 slot ``drivers/hotplug/cpqphp.h`` SLOT_MAGIC 0x67267322 slot ``drivers/hotplug/acpiphp.h`` LO_MAGIC 0x68797548 nbd_device ``include/linux/nbd.h`` -OPROFILE_MAGIC 0x6f70726f super_block ``drivers/oprofile/oprofilefs.h`` M3_STATE_MAGIC 0x734d724d m3_state ``sound/oss/maestro3.c`` VMALLOC_MAGIC 0x87654320 snd_alloc_track ``sound/core/memory.c`` KMALLOC_MAGIC 0x87654321 snd_alloc_track ``sound/core/memory.c`` diff --git a/Documentation/scheduler/schedutil.txt b/Documentation/scheduler/schedutil.txt new file mode 100644 index 000000000000..78f6b91e2291 --- /dev/null +++ b/Documentation/scheduler/schedutil.txt @@ -0,0 +1,169 @@ + + +NOTE; all this assumes a linear relation between frequency and work capacity, +we know this is flawed, but it is the best workable approximation. + + +PELT (Per Entity Load Tracking) +------------------------------- + +With PELT we track some metrics across the various scheduler entities, from +individual tasks to task-group slices to CPU runqueues. As the basis for this +we use an Exponentially Weighted Moving Average (EWMA), each period (1024us) +is decayed such that y^32 = 0.5. That is, the most recent 32ms contribute +half, while the rest of history contribute the other half. + +Specifically: + + ewma_sum(u) := u_0 + u_1*y + u_2*y^2 + ... + + ewma(u) = ewma_sum(u) / ewma_sum(1) + +Since this is essentially a progression of an infinite geometric series, the +results are composable, that is ewma(A) + ewma(B) = ewma(A+B). This property +is key, since it gives the ability to recompose the averages when tasks move +around. + +Note that blocked tasks still contribute to the aggregates (task-group slices +and CPU runqueues), which reflects their expected contribution when they +resume running. + +Using this we track 2 key metrics: 'running' and 'runnable'. 'Running' +reflects the time an entity spends on the CPU, while 'runnable' reflects the +time an entity spends on the runqueue. When there is only a single task these +two metrics are the same, but once there is contention for the CPU 'running' +will decrease to reflect the fraction of time each task spends on the CPU +while 'runnable' will increase to reflect the amount of contention. + +For more detail see: kernel/sched/pelt.c + + +Frequency- / CPU Invariance +--------------------------- + +Because consuming the CPU for 50% at 1GHz is not the same as consuming the CPU +for 50% at 2GHz, nor is running 50% on a LITTLE CPU the same as running 50% on +a big CPU, we allow architectures to scale the time delta with two ratios, one +Dynamic Voltage and Frequency Scaling (DVFS) ratio and one microarch ratio. + +For simple DVFS architectures (where software is in full control) we trivially +compute the ratio as: + + f_cur + r_dvfs := ----- + f_max + +For more dynamic systems where the hardware is in control of DVFS we use +hardware counters (Intel APERF/MPERF, ARMv8.4-AMU) to provide us this ratio. +For Intel specifically, we use: + + APERF + f_cur := ----- * P0 + MPERF + + 4C-turbo; if available and turbo enabled + f_max := { 1C-turbo; if turbo enabled + P0; otherwise + + f_cur + r_dvfs := min( 1, ----- ) + f_max + +We pick 4C turbo over 1C turbo to make it slightly more sustainable. + +r_cpu is determined as the ratio of highest performance level of the current +CPU vs the highest performance level of any other CPU in the system. + + r_tot = r_dvfs * r_cpu + +The result is that the above 'running' and 'runnable' metrics become invariant +of DVFS and CPU type. IOW. we can transfer and compare them between CPUs. + +For more detail see: + + - kernel/sched/pelt.h:update_rq_clock_pelt() + - arch/x86/kernel/smpboot.c:"APERF/MPERF frequency ratio computation." + - Documentation/scheduler/sched-capacity.rst:"1. CPU Capacity + 2. Task utilization" + + +UTIL_EST / UTIL_EST_FASTUP +-------------------------- + +Because periodic tasks have their averages decayed while they sleep, even +though when running their expected utilization will be the same, they suffer a +(DVFS) ramp-up after they are running again. + +To alleviate this (a default enabled option) UTIL_EST drives an Infinite +Impulse Response (IIR) EWMA with the 'running' value on dequeue -- when it is +highest. A further default enabled option UTIL_EST_FASTUP modifies the IIR +filter to instantly increase and only decay on decrease. + +A further runqueue wide sum (of runnable tasks) is maintained of: + + util_est := \Sum_t max( t_running, t_util_est_ewma ) + +For more detail see: kernel/sched/fair.c:util_est_dequeue() + + +UCLAMP +------ + +It is possible to set effective u_min and u_max clamps on each CFS or RT task; +the runqueue keeps an max aggregate of these clamps for all running tasks. + +For more detail see: include/uapi/linux/sched/types.h + + +Schedutil / DVFS +---------------- + +Every time the scheduler load tracking is updated (task wakeup, task +migration, time progression) we call out to schedutil to update the hardware +DVFS state. + +The basis is the CPU runqueue's 'running' metric, which per the above it is +the frequency invariant utilization estimate of the CPU. From this we compute +a desired frequency like: + + max( running, util_est ); if UTIL_EST + u_cfs := { running; otherwise + + clamp( u_cfs + u_rt , u_min, u_max ); if UCLAMP_TASK + u_clamp := { u_cfs + u_rt; otherwise + + u := u_clamp + u_irq + u_dl; [approx. see source for more detail] + + f_des := min( f_max, 1.25 u * f_max ) + +XXX IO-wait; when the update is due to a task wakeup from IO-completion we +boost 'u' above. + +This frequency is then used to select a P-state/OPP or directly munged into a +CPPC style request to the hardware. + +XXX: deadline tasks (Sporadic Task Model) allows us to calculate a hard f_min +required to satisfy the workload. + +Because these callbacks are directly from the scheduler, the DVFS hardware +interaction should be 'fast' and non-blocking. Schedutil supports +rate-limiting DVFS requests for when hardware interaction is slow and +expensive, this reduces effectiveness. + +For more information see: kernel/sched/cpufreq_schedutil.c + + +NOTES +----- + + - On low-load scenarios, where DVFS is most relevant, the 'running' numbers + will closely reflect utilization. + + - In saturated scenarios task movement will cause some transient dips, + suppose we have a CPU saturated with 4 tasks, then when we migrate a task + to an idle CPU, the old CPU will have a 'running' value of 0.75 while the + new CPU will gain 0.25. This is inevitable and time progression will + correct this. XXX do we still guarantee f_max due to no idle-time? + + - Much of the above is about avoiding DVFS dips, and independent DVFS domains + having to re-learn / ramp-up when load shifts. + diff --git a/Documentation/scsi/scsi-parameters.rst b/Documentation/scsi/scsi-parameters.rst index e5f68b431f5c..dea5803f5c62 100644 --- a/Documentation/scsi/scsi-parameters.rst +++ b/Documentation/scsi/scsi-parameters.rst @@ -94,7 +94,7 @@ parameters may be changed at runtime by the command (/proc/sys/dev/scsi/logging_level). There is also a nice 'scsi_logging_level' script in the S390-tools package, available for download at - https://github.com/ibm-s390-tools/s390-tools/blob/master/scripts/scsi_logging_level + https://github.com/ibm-s390-linux/s390-tools/blob/master/scripts/scsi_logging_level scsi_mod.scan= [SCSI] sync (default) scans SCSI busses as they are discovered. async scans them in kernel threads, diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst index f0749943ccb2..1eb08e7bae52 100644 --- a/Documentation/sound/designs/index.rst +++ b/Documentation/sound/designs/index.rst @@ -14,3 +14,4 @@ Designs and Implementations powersave oss-emulation seq-oss + jack-injection diff --git a/Documentation/sound/designs/jack-injection.rst b/Documentation/sound/designs/jack-injection.rst new file mode 100644 index 000000000000..f9790521523e --- /dev/null +++ b/Documentation/sound/designs/jack-injection.rst @@ -0,0 +1,166 @@ +============================ +ALSA Jack Software Injection +============================ + +Simple Introduction On Jack Injection +===================================== + +Here jack injection means users could inject plugin or plugout events +to the audio jacks through debugfs interface, it is helpful to +validate ALSA userspace changes. For example, we change the audio +profile switching code in the pulseaudio, and we want to verify if the +change works as expected and if the change introduce the regression, +in this case, we could inject plugin or plugout events to an audio +jack or to some audio jacks, we don't need to physically access the +machine and plug/unplug physical devices to the audio jack. + +In this design, an audio jack doesn't equal to a physical audio jack. +Sometimes a physical audio jack contains multi functions, and the +ALSA driver creates multi ``jack_kctl`` for a ``snd_jack``, here the +``snd_jack`` represents a physical audio jack and the ``jack_kctl`` +represents a function, for example a physical jack has two functions: +headphone and mic_in, the ALSA ASoC driver will build 2 ``jack_kctl`` +for this jack. The jack injection is implemented based on the +``jack_kctl`` instead of ``snd_jack``. + +To inject events to audio jacks, we need to enable the jack injection +via ``sw_inject_enable`` first, once it is enabled, this jack will not +change the state by hardware events anymore, we could inject plugin or +plugout events via ``jackin_inject`` and check the jack state via +``status``, after we finish our test, we need to disable the jack +injection via ``sw_inject_enable`` too, once it is disabled, the jack +state will be restored according to the last reported hardware events +and will change by future hardware events. + +The Layout of Jack Injection Interface +====================================== + +If users enable the SND_JACK_INJECTION_DEBUG in the kernel, the audio +jack injection interface will be created as below: +:: + + $debugfs_mount_dir/sound + |-- card0 + |-- |-- HDMI_DP_pcm_10_Jack + |-- |-- |-- jackin_inject + |-- |-- |-- kctl_id + |-- |-- |-- mask_bits + |-- |-- |-- status + |-- |-- |-- sw_inject_enable + |-- |-- |-- type + ... + |-- |-- HDMI_DP_pcm_9_Jack + |-- |-- jackin_inject + |-- |-- kctl_id + |-- |-- mask_bits + |-- |-- status + |-- |-- sw_inject_enable + |-- |-- type + |-- card1 + |-- HDMI_DP_pcm_5_Jack + |-- |-- jackin_inject + |-- |-- kctl_id + |-- |-- mask_bits + |-- |-- status + |-- |-- sw_inject_enable + |-- |-- type + ... + |-- Headphone_Jack + |-- |-- jackin_inject + |-- |-- kctl_id + |-- |-- mask_bits + |-- |-- status + |-- |-- sw_inject_enable + |-- |-- type + |-- Headset_Mic_Jack + |-- jackin_inject + |-- kctl_id + |-- mask_bits + |-- status + |-- sw_inject_enable + |-- type + +The Explanation Of The Nodes +====================================== + +kctl_id + read-only, get jack_kctl->kctl's id + :: + + sound/card1/Headphone_Jack# cat kctl_id + Headphone Jack + +mask_bits + read-only, get jack_kctl's supported events mask_bits + :: + + sound/card1/Headphone_Jack# cat mask_bits + 0x0001 HEADPHONE(0x0001) + +status + read-only, get jack_kctl's current status + +- headphone unplugged: + + :: + + sound/card1/Headphone_Jack# cat status + Unplugged + +- headphone plugged: + + :: + + sound/card1/Headphone_Jack# cat status + Plugged + +type + read-only, get snd_jack's supported events from type (all supported events on the physical audio jack) + :: + + sound/card1/Headphone_Jack# cat type + 0x7803 HEADPHONE(0x0001) MICROPHONE(0x0002) BTN_3(0x0800) BTN_2(0x1000) BTN_1(0x2000) BTN_0(0x4000) + +sw_inject_enable + read-write, enable or disable injection + +- injection disabled: + + :: + + sound/card1/Headphone_Jack# cat sw_inject_enable + Jack: Headphone Jack Inject Enabled: 0 + +- injection enabled: + + :: + + sound/card1/Headphone_Jack# cat sw_inject_enable + Jack: Headphone Jack Inject Enabled: 1 + +- to enable jack injection: + + :: + + sound/card1/Headphone_Jack# echo 1 > sw_inject_enable + +- to disable jack injection: + + :: + + sound/card1/Headphone_Jack# echo 0 > sw_inject_enable + +jackin_inject + write-only, inject plugin or plugout + +- to inject plugin: + + :: + + sound/card1/Headphone_Jack# echo 1 > jackin_inject + +- to inject plugout: + + :: + + sound/card1/Headphone_Jack# echo 0 > jackin_inject diff --git a/Documentation/translations/it_IT/process/magic-number.rst b/Documentation/translations/it_IT/process/magic-number.rst index 0243d32a0b59..1af30f4228f2 100644 --- a/Documentation/translations/it_IT/process/magic-number.rst +++ b/Documentation/translations/it_IT/process/magic-number.rst @@ -141,7 +141,6 @@ FW_HEADER_MAGIC 0x65726F66 fw_header ``drivers/atm/fo SLOT_MAGIC 0x67267321 slot ``drivers/hotplug/cpqphp.h`` SLOT_MAGIC 0x67267322 slot ``drivers/hotplug/acpiphp.h`` LO_MAGIC 0x68797548 nbd_device ``include/linux/nbd.h`` -OPROFILE_MAGIC 0x6f70726f super_block ``drivers/oprofile/oprofilefs.h`` M3_STATE_MAGIC 0x734d724d m3_state ``sound/oss/maestro3.c`` VMALLOC_MAGIC 0x87654320 snd_alloc_track ``sound/core/memory.c`` KMALLOC_MAGIC 0x87654321 snd_alloc_track ``sound/core/memory.c`` diff --git a/Documentation/translations/zh_CN/process/magic-number.rst b/Documentation/translations/zh_CN/process/magic-number.rst index de182bf4191c..7bb9d4165ed3 100644 --- a/Documentation/translations/zh_CN/process/magic-number.rst +++ b/Documentation/translations/zh_CN/process/magic-number.rst @@ -124,7 +124,6 @@ FW_HEADER_MAGIC 0x65726F66 fw_header ``drivers/atm/fo SLOT_MAGIC 0x67267321 slot ``drivers/hotplug/cpqphp.h`` SLOT_MAGIC 0x67267322 slot ``drivers/hotplug/acpiphp.h`` LO_MAGIC 0x68797548 nbd_device ``include/linux/nbd.h`` -OPROFILE_MAGIC 0x6f70726f super_block ``drivers/oprofile/oprofilefs.h`` M3_STATE_MAGIC 0x734d724d m3_state ``sound/oss/maestro3.c`` VMALLOC_MAGIC 0x87654320 snd_alloc_track ``sound/core/memory.c`` KMALLOC_MAGIC 0x87654321 snd_alloc_track ``sound/core/memory.c`` diff --git a/Documentation/usb/gadget-testing.rst b/Documentation/usb/gadget-testing.rst index 2eeb3e9299e4..2085e7b24eeb 100644 --- a/Documentation/usb/gadget-testing.rst +++ b/Documentation/usb/gadget-testing.rst @@ -91,9 +91,9 @@ The ECM function provides these attributes in its function directory: and after creating the functions/ecm.<instance name> they contain default values: qmult is 5, dev_addr and host_addr are randomly selected. -Except for ifname they can be written to until the function is linked to a -configuration. The ifname is read-only and contains the name of the interface -which was assigned by the net core, e. g. usb0. +The ifname can be written to if the function is not bound. A write must be an +interface pattern such as "usb%d", which will cause the net core to choose the +next free usbX interface. By default, it is set to "usb%d". Testing the ECM function ------------------------ @@ -131,9 +131,9 @@ The ECM subset function provides these attributes in its function directory: and after creating the functions/ecm.<instance name> they contain default values: qmult is 5, dev_addr and host_addr are randomly selected. -Except for ifname they can be written to until the function is linked to a -configuration. The ifname is read-only and contains the name of the interface -which was assigned by the net core, e. g. usb0. +The ifname can be written to if the function is not bound. A write must be an +interface pattern such as "usb%d", which will cause the net core to choose the +next free usbX interface. By default, it is set to "usb%d". Testing the ECM subset function ------------------------------- @@ -171,9 +171,9 @@ The EEM function provides these attributes in its function directory: and after creating the functions/eem.<instance name> they contain default values: qmult is 5, dev_addr and host_addr are randomly selected. -Except for ifname they can be written to until the function is linked to a -configuration. The ifname is read-only and contains the name of the interface -which was assigned by the net core, e. g. usb0. +The ifname can be written to if the function is not bound. A write must be an +interface pattern such as "usb%d", which will cause the net core to choose the +next free usbX interface. By default, it is set to "usb%d". Testing the EEM function ------------------------ @@ -453,9 +453,9 @@ The NCM function provides these attributes in its function directory: and after creating the functions/ncm.<instance name> they contain default values: qmult is 5, dev_addr and host_addr are randomly selected. -Except for ifname they can be written to until the function is linked to a -configuration. The ifname is read-only and contains the name of the interface -which was assigned by the net core, e. g. usb0. +The ifname can be written to if the function is not bound. A write must be an +interface pattern such as "usb%d", which will cause the net core to choose the +next free usbX interface. By default, it is set to "usb%d". Testing the NCM function ------------------------ @@ -591,9 +591,9 @@ The RNDIS function provides these attributes in its function directory: and after creating the functions/rndis.<instance name> they contain default values: qmult is 5, dev_addr and host_addr are randomly selected. -Except for ifname they can be written to until the function is linked to a -configuration. The ifname is read-only and contains the name of the interface -which was assigned by the net core, e. g. usb0. +The ifname can be written to if the function is not bound. A write must be an +interface pattern such as "usb%d", which will cause the net core to choose the +next free usbX interface. By default, it is set to "usb%d". Testing the RNDIS function -------------------------- diff --git a/Documentation/usb/raw-gadget.rst b/Documentation/usb/raw-gadget.rst index 68d879a8009e..818a1648b387 100644 --- a/Documentation/usb/raw-gadget.rst +++ b/Documentation/usb/raw-gadget.rst @@ -2,83 +2,93 @@ USB Raw Gadget ============== -USB Raw Gadget is a kernel module that provides a userspace interface for -the USB Gadget subsystem. Essentially it allows to emulate USB devices -from userspace. Enabled with CONFIG_USB_RAW_GADGET. Raw Gadget is -currently a strictly debugging feature and shouldn't be used in -production, use GadgetFS instead. +USB Raw Gadget is a gadget driver that gives userspace low-level control over +the gadget's communication process. + +Like any other gadget driver, Raw Gadget implements USB devices via the +USB gadget API. Unlike most gadget drivers, Raw Gadget does not implement +any concrete USB functions itself but requires userspace to do that. + +Raw Gadget is currently a strictly debugging feature and should not be used +in production. Use GadgetFS instead. + +Enabled with CONFIG_USB_RAW_GADGET. Comparison to GadgetFS ~~~~~~~~~~~~~~~~~~~~~~ -Raw Gadget is similar to GadgetFS, but provides a more low-level and -direct access to the USB Gadget layer for the userspace. The key -differences are: +Raw Gadget is similar to GadgetFS but provides more direct access to the +USB gadget layer for userspace. The key differences are: -1. Every USB request is passed to the userspace to get a response, while +1. Raw Gadget passes every USB request to userspace to get a response, while GadgetFS responds to some USB requests internally based on the provided - descriptors. However note, that the UDC driver might respond to some - requests on its own and never forward them to the Gadget layer. + descriptors. Note that the UDC driver might respond to some requests on + its own and never forward them to the gadget layer. -2. GadgetFS performs some sanity checks on the provided USB descriptors, - while Raw Gadget allows you to provide arbitrary data as responses to - USB requests. +2. Raw Gadget allows providing arbitrary data as responses to USB requests, + while GadgetFS performs sanity checks on the provided USB descriptors. + This makes Raw Gadget suitable for fuzzing by providing malformed data as + responses to USB requests. 3. Raw Gadget provides a way to select a UDC device/driver to bind to, - while GadgetFS currently binds to the first available UDC. + while GadgetFS currently binds to the first available UDC. This allows + having multiple Raw Gadget instances bound to different UDCs. 4. Raw Gadget explicitly exposes information about endpoints addresses and - capabilities allowing a user to write UDC-agnostic gadgets. + capabilities. This allows the user to write UDC-agnostic gadgets. -5. Raw Gadget has ioctl-based interface instead of a filesystem-based one. +5. Raw Gadget has an ioctl-based interface instead of a filesystem-based + one. Userspace interface ~~~~~~~~~~~~~~~~~~~ -To create a Raw Gadget instance open /dev/raw-gadget. Multiple raw-gadget -instances (bound to different UDCs) can be used at the same time. The -interaction with the opened file happens through the ioctl() calls, see -comments in include/uapi/linux/usb/raw_gadget.h for details. +The user can interact with Raw Gadget by opening ``/dev/raw-gadget`` and +issuing ioctl calls; see the comments in include/uapi/linux/usb/raw_gadget.h +for details. Multiple Raw Gadget instances (bound to different UDCs) can be +used at the same time. -The typical usage of Raw Gadget looks like: +A typical usage scenario of Raw Gadget: -1. Open Raw Gadget instance via /dev/raw-gadget. -2. Initialize the instance via USB_RAW_IOCTL_INIT. -3. Launch the instance with USB_RAW_IOCTL_RUN. -4. In a loop issue USB_RAW_IOCTL_EVENT_FETCH calls to receive events from - Raw Gadget and react to those depending on what kind of USB device - needs to be emulated. +1. Create a Raw Gadget instance by opening ``/dev/raw-gadget``. +2. Initialize the instance via ``USB_RAW_IOCTL_INIT``. +3. Launch the instance with ``USB_RAW_IOCTL_RUN``. +4. In a loop issue ``USB_RAW_IOCTL_EVENT_FETCH`` to receive events from + Raw Gadget and react to those depending on what kind of USB gadget must + be implemented. -Note, that some UDC drivers have fixed addresses assigned to endpoints, and -therefore arbitrary endpoint addresses can't be used in the descriptors. -Nevertheles, Raw Gadget provides a UDC-agnostic way to write USB gadgets. -Once a USB_RAW_EVENT_CONNECT event is received via USB_RAW_IOCTL_EVENT_FETCH, -the USB_RAW_IOCTL_EPS_INFO ioctl can be used to find out information about -endpoints that the UDC driver has. Based on that information, the user must -chose UDC endpoints that will be used for the gadget being emulated, and -properly assign addresses in endpoint descriptors. +Note that some UDC drivers have fixed addresses assigned to endpoints, and +therefore arbitrary endpoint addresses cannot be used in the descriptors. +Nevertheless, Raw Gadget provides a UDC-agnostic way to write USB gadgets. +Once ``USB_RAW_EVENT_CONNECT`` is received via ``USB_RAW_IOCTL_EVENT_FETCH``, +``USB_RAW_IOCTL_EPS_INFO`` can be used to find out information about the +endpoints that the UDC driver has. Based on that, userspace must choose UDC +endpoints for the gadget and assign addresses in the endpoint descriptors +correspondingly. -You can find usage examples (along with a test suite) here: +Raw Gadget usage examples and a test suite: https://github.com/xairy/raw-gadget Internal details ~~~~~~~~~~~~~~~~ -Currently every endpoint read/write ioctl submits a USB request and waits until -its completion. This is the desired mode for coverage-guided fuzzing (as we'd -like all USB request processing happen during the lifetime of a syscall), -and must be kept in the implementation. (This might be slow for real world -applications, thus the O_NONBLOCK improvement suggestion below.) +Every Raw Gadget endpoint read/write ioctl submits a USB request and waits +until its completion. This is done deliberately to assist with coverage-guided +fuzzing by having a single syscall fully process a single USB request. This +feature must be kept in the implementation. Potential future improvements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Report more events (suspend, resume, etc.) through USB_RAW_IOCTL_EVENT_FETCH. +- Report more events (suspend, resume, etc.) through + ``USB_RAW_IOCTL_EVENT_FETCH``. -- Support O_NONBLOCK I/O. +- Support ``O_NONBLOCK`` I/O. This would be another mode of operation, where + Raw Gadget would not wait until the completion of each USB request. - Support USB 3 features (accept SS endpoint companion descriptor when - enabling endpoints; allow providing stream_id for bulk transfers). + enabling endpoints; allow providing ``stream_id`` for bulk transfers). -- Support ISO transfer features (expose frame_number for completed requests). +- Support ISO transfer features (expose ``frame_number`` for completed + requests). diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index acd2cc2a538d..d29b020e5622 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -24,6 +24,7 @@ place where this information is gathered. ioctl/index iommu media/index + sysfs-platform_profile .. only:: subproject and html diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index a4c75a28c839..b5231d7f9200 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -324,6 +324,8 @@ Code Seq# Include File Comments 0xA3 90-9F linux/dtlk.h 0xA4 00-1F uapi/linux/tee.h Generic TEE subsystem 0xA4 00-1F uapi/asm/sgx.h <mailto:linux-sgx@vger.kernel.org> +0xA5 01 linux/surface_aggregator/cdev.h Microsoft Surface Platform System Aggregator + <mailto:luzmaximilian@gmail.com> 0xAA 00-3F linux/uapi/linux/userfaultfd.h 0xAB 00-1F linux/nbd.h 0xAC 00-1F linux/raw.h diff --git a/Documentation/userspace-api/media/drivers/ccs.rst b/Documentation/userspace-api/media/drivers/ccs.rst new file mode 100644 index 000000000000..161cb65f4d98 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/ccs.rst @@ -0,0 +1,110 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +.. include:: <isonum.txt> + +MIPI CCS camera sensor driver +============================= + +The MIPI CCS camera sensor driver is a generic driver for `MIPI CCS +<https://www.mipi.org/specifications/camera-command-set>`_ compliant +camera sensors. It exposes three sub-devices representing the pixel array, +the binner and the scaler. + +As the capabilities of individual devices vary, the driver exposes +interfaces based on the capabilities that exist in hardware. + +Pixel Array sub-device +---------------------- + +The pixel array sub-device represents the camera sensor's pixel matrix, as well +as analogue crop functionality present in many compliant devices. The analogue +crop is configured using the ``V4L2_SEL_TGT_CROP`` on the source pad (0) of the +entity. The size of the pixel matrix can be obtained by getting the +``V4L2_SEL_TGT_NATIVE_SIZE`` target. + +Binner +------ + +The binner sub-device represents the binning functionality on the sensor. For +that purpose, selection target ``V4L2_SEL_TGT_COMPOSE`` is supported on the +sink pad (0). + +Additionally, if a device has no scaler or digital crop functionality, the +source pad (1) expses another digital crop selection rectangle that can only +crop at the end of the lines and frames. + +Scaler +------ + +The scaler sub-device represents the digital crop and scaling functionality of +the sensor. The V4L2 selection target ``V4L2_SEL_TGT_CROP`` is used to +configure the digital crop on the sink pad (0) when digital crop is supported. +Scaling is configured using selection target ``V4L2_SEL_TGT_COMPOSE`` on the +sink pad (0) as well. + +Additionally, if the scaler sub-device exists, its source pad (1) exposes +another digital crop selection rectangle that can only crop at the end of the +lines and frames. + +Digital and analogue crop +------------------------- + +Digital crop functionality is referred to as cropping that effectively works by +dropping some data on the floor. Analogue crop, on the other hand, means that +the cropped information is never retrieved. In case of camera sensors, the +analogue data is never read from the pixel matrix that are outside the +configured selection rectangle that designates crop. The difference has an +effect in device timing and likely also in power consumption. + +Private controls +---------------- + +The MIPI CCS driver implements a number of private controls under +``V4L2_CID_USER_BASE_CCS`` to control the MIPI CCS compliant camera sensors. + +Analogue gain model +~~~~~~~~~~~~~~~~~~~ + +The CCS defines an analogue gain model where the gain can be calculated using +the following formula: + + gain = m0 * x + c0 / (m1 * x + c1) + +Either m0 or c0 will be zero. The constants that are device specific, can be +obtained from the following controls: + + V4L2_CID_CCS_ANALOGUE_GAIN_M0 + V4L2_CID_CCS_ANALOGUE_GAIN_M1 + V4L2_CID_CCS_ANALOGUE_GAIN_C0 + V4L2_CID_CCS_ANALOGUE_GAIN_C1 + +The analogue gain (``x`` in the formula) is controlled through +``V4L2_CID_ANALOGUE_GAIN`` in this case. + +Alternate analogue gain model +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The CCS defines another analogue gain model called alternate analogue gain. In +this case, the formula to calculate actual gain consists of linear and +exponential parts: + + gain = linear * 2 ^ exponent + +The ``linear`` and ``exponent`` factors can be set using the +``V4L2_CID_CCS_ANALOGUE_LINEAR_GAIN`` and +``V4L2_CID_CCS_ANALOGUE_EXPONENTIAL_GAIN`` controls, respectively + +Shading correction +~~~~~~~~~~~~~~~~~~ + +The CCS standard supports lens shading correction. The feature can be controlled +using ``V4L2_CID_CCS_SHADING_CORRECTION``. Additionally, the luminance +correction level may be changed using +``V4L2_CID_CCS_LUMINANCE_CORRECTION_LEVEL``, where value 0 indicates no +correction and 128 indicates correcting the luminance in corners to 10 % less +than in the centre. + +Shading correction needs to be enabled for luminance correction level to have an +effect. + +**Copyright** |copy| 2020 Intel Corporation diff --git a/Documentation/userspace-api/media/drivers/index.rst b/Documentation/userspace-api/media/drivers/index.rst index 05a82f8c0c99..1a9038f5f9fa 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: + ccs cx2341x-uapi imx-uapi max2175 diff --git a/Documentation/userspace-api/media/dvb/dvbstb.svg b/Documentation/userspace-api/media/dvb/dvbstb.svg index 87e68baa056b..6f0ba98f9bf9 100644 --- a/Documentation/userspace-api/media/dvb/dvbstb.svg +++ b/Documentation/userspace-api/media/dvb/dvbstb.svg @@ -2,7 +2,7 @@ <!-- SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later --> <svg id="svg2" width="15.847cm" height="8.4187cm" fill-rule="evenodd" stroke-linejoin="round" stroke-width="28.222" preserveAspectRatio="xMidYMid" version="1.2" viewBox="0 0 23770.123 12628.122" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><defs id="defs142"><marker id="Arrow1Lend" overflow="visible" orient="auto"><path id="path954" transform="matrix(-.8 0 0 -.8 -10 0)" d="m0 0 5-5-17.5 5 17.5 5z" fill-rule="evenodd" stroke="#000" stroke-width="1pt"/></marker><marker id="marker1243" overflow="visible" orient="auto"><path id="path1241" transform="matrix(-.8 0 0 -.8 -10 0)" d="m0 0 5-5-17.5 5 17.5 5z" fill-rule="evenodd" stroke="#000" stroke-width="1pt"/></marker></defs><metadata id="metadata519"><rdf:RDF><cc:Work rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/><dc:title/></cc:Work></rdf:RDF></metadata><rect id="rect197" class="BoundingBox" x="5355.1" y="13.122" width="18403" height="9603" fill="none"/><path id="path199" d="m14556 9614.1h-9200v-9600h18400v9600z" fill="#fff"/><path id="path201" d="m14556 9614.1h-9200v-9600h18400v9600z" fill="none" stroke="#000"/><rect id="rect206" class="BoundingBox" x="13.122" y="4013.1" width="4544" height="2403" fill="none"/><path id="path208" d="m2285.1 6414.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path210" d="m2285.1 6414.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text212" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan214" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan216" class="TextPosition" -x="1281.1219" y="5435.1221"><tspan id="tspan218" fill="#000000">Antena</tspan></tspan></tspan></text> +x="1013.1317" y="5435.1221"><tspan id="tspan218" fill="#000000">Antenna</tspan></tspan></tspan></text> <rect id="rect223" class="BoundingBox" x="6213.1" y="1813.1" width="4544" height="2403" fill="none"/><path id="path225" d="m8485.1 4214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path227" d="m8485.1 4214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text229" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan231" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan233" class="TextPosition" x="7217.1221" y="3235.1221"><tspan id="tspan235" fill="#000000">Frontend</tspan></tspan></tspan></text> <rect id="rect240" class="BoundingBox" x="12113" y="1813.1" width="4544" height="2403" fill="none"/><path id="path242" d="m14385 4214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path244" d="m14385 4214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text246" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan248" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan250" class="TextPosition" x="13944.122" y="3235.1221"><tspan id="tspan252" fill="#000000">CA</tspan></tspan></tspan></text> <rect id="rect257" class="BoundingBox" x="18113" y="1813.1" width="4544" height="2403" fill="none"/><path id="path259" d="m20385 4214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path261" d="m20385 4214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text263" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan265" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan267" class="TextPosition" x="19384.123" y="3235.1221"><tspan id="tspan269" fill="#000000">Demux</tspan></tspan></tspan></text> diff --git a/Documentation/userspace-api/media/mediactl/media-types.rst b/Documentation/userspace-api/media/mediactl/media-types.rst index 7b24a213cae7..e1e4043b3b1c 100644 --- a/Documentation/userspace-api/media/mediactl/media-types.rst +++ b/Documentation/userspace-api/media/mediactl/media-types.rst @@ -39,6 +39,7 @@ Types and flags used to represent the media graph elements .. _MEDIA-ENT-F-PROC-VIDEO-STATISTICS: .. _MEDIA-ENT-F-PROC-VIDEO-ENCODER: .. _MEDIA-ENT-F-PROC-VIDEO-DECODER: +.. _MEDIA-ENT-F-PROC-VIDEO-ISP: .. _MEDIA-ENT-F-VID-MUX: .. _MEDIA-ENT-F-VID-IF-BRIDGE: .. _MEDIA-ENT-F-DV-DECODER: @@ -201,6 +202,12 @@ Types and flags used to represent the media graph elements decompressing a compressed video stream into uncompressed video frames. Must have one sink pad and at least one source pad. + * - ``MEDIA_ENT_F_PROC_VIDEO_ISP`` + - An Image Signal Processor (ISP) device. ISPs generally are one of a + kind devices that have their specific control interfaces using a + combination of custom V4L2 controls and IOCTLs, and parameters + supplied in a metadata buffer. + * - ``MEDIA_ENT_F_VID_MUX`` - Video multiplexer. An entity capable of multiplexing must have at least two sink pads and one source pad, and must pass the video diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst index 454ecd9a0f83..00944e97d638 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst @@ -1182,6 +1182,18 @@ enum v4l2_mpeg_video_h264_entropy_mode - V4L2_CID_MPEG_VIDEO_H264_MAX_QP is also set, the quantization parameter should be chosen to meet both requirements. +``V4L2_CID_MPEG_VIDEO_H264_B_FRAME_MIN_QP (integer)`` + Minimum quantization parameter for the H264 B frame to limit B frame + quality to a range. Valid range: from 0 to 51. If + V4L2_CID_MPEG_VIDEO_H264_MIN_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_H264_B_FRAME_MAX_QP (integer)`` + Maximum quantization parameter for the H264 B frame to limit B frame + quality to a range. Valid range: from 0 to 51. If + V4L2_CID_MPEG_VIDEO_H264_MAX_QP is also set, the quantization parameter + should be chosen to meet both requirements. + ``V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP (integer)`` Quantization parameter for an I frame for MPEG4. Valid range: from 1 to 31. @@ -1501,6 +1513,26 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - * - Bit 16:32 - Layer number +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L0_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 0 for H264 encoder. + +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L1_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 1 for H264 encoder. + +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L2_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 2 for H264 encoder. + +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L3_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 3 for H264 encoder. + +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L4_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 4 for H264 encoder. + +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L5_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 5 for H264 encoder. + +``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L6_BR (integer)`` + Indicates bit rate (bps) for hierarchical coding layer 6 for H264 encoder. .. _v4l2-mpeg-mpeg2: @@ -2628,11 +2660,11 @@ HEVC/H.265 Control IDs ``V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP (integer)`` Minimum quantization parameter for HEVC. - Valid range: from 0 to 51. + Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. ``V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP (integer)`` Maximum quantization parameter for HEVC. - Valid range: from 0 to 51. + Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. ``V4L2_CID_MPEG_VIDEO_HEVC_I_FRAME_QP (integer)`` Quantization parameter for an I frame for HEVC. @@ -2649,6 +2681,42 @@ HEVC/H.265 Control IDs Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. +``V4L2_CID_MPEG_VIDEO_HEVC_I_FRAME_MIN_QP (integer)`` + Minimum quantization parameter for the HEVC I frame to limit I frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_HEVC_I_FRAME_MAX_QP (integer)`` + Maximum quantization parameter for the HEVC I frame to limit I frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_HEVC_P_FRAME_MIN_QP (integer)`` + Minimum quantization parameter for the HEVC P frame to limit P frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_HEVC_P_FRAME_MAX_QP (integer)`` + Maximum quantization parameter for the HEVC P frame to limit P frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_HEVC_B_FRAME_MIN_QP (integer)`` + Minimum quantization parameter for the HEVC B frame to limit B frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_HEVC_B_FRAME_MAX_QP (integer)`` + Maximum quantization parameter for the HEVC B frame to limit B frame + quality to a range. Valid range: from 0 to 51 for 8 bit and from 0 to 63 for 10 bit. + If V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP is also set, the quantization parameter + should be chosen to meet both requirements. + ``V4L2_CID_MPEG_VIDEO_HEVC_HIER_QP (boolean)`` HIERARCHICAL_QP allows the host to specify the quantization parameter values for each temporal layer through HIERARCHICAL_QP_LAYER. This is @@ -3569,3 +3637,12 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - - Selecting this value specifies that HEVC slices are expected to be prefixed by Annex B start codes. According to :ref:`hevc` valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001. + +``V4L2_CID_MPEG_VIDEO_BASELAYER_PRIORITY_ID (integer)`` + Specifies a priority identifier for the NAL unit, which will be applied to + the base layer. By default this value is set to 0 for the base layer, + and the next layer will have the priority ID assigned as 1, 2, 3 and so on. + The video encoder can't decide the priority id to be applied to a layer, + so this has to come from client. + This is applicable to H264 and valid Range is from 0 to 63. + Source Rec. ITU-T H.264 (06/2019); G.7.4.1.1, G.8.8.1. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst index 7d4d39201a3f..1e0db602cc1b 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst @@ -396,9 +396,9 @@ number of lines as the luma plane. NV24 and NV42 ------------- -Semi-planar YUV 4:4:4 formats. The chroma plane is subsampled by 2 in the -horizontal direction. Chroma lines contain half the number of pixels and the -same number of bytes as luma lines, and the chroma plane contains the same +Semi-planar YUV 4:4:4 formats. The chroma plane is not subsampled. +Chroma lines contain the same number of pixels and twice the +number of bytes as luma lines, and the chroma plane contains the same number of lines as the luma plane. .. flat-table:: Sample 4x4 NV24 Image diff --git a/Documentation/userspace-api/sysfs-platform_profile.rst b/Documentation/userspace-api/sysfs-platform_profile.rst new file mode 100644 index 000000000000..c33a71263d9e --- /dev/null +++ b/Documentation/userspace-api/sysfs-platform_profile.rst @@ -0,0 +1,42 @@ +===================================================================== +Platform Profile Selection (e.g. /sys/firmware/acpi/platform_profile) +===================================================================== + +On modern systems the platform performance, temperature, fan and other +hardware related characteristics are often dynamically configurable. The +platform configuration is often automatically adjusted to the current +conditions by some automatic mechanism (which may very well live outside +the kernel). + +These auto platform adjustment mechanisms often can be configured with +one of several platform profiles, with either a bias towards low power +operation or towards performance. + +The purpose of the platform_profile attribute is to offer a generic sysfs +API for selecting the platform profile of these automatic mechanisms. + +Note that this API is only for selecting the platform profile, it is +NOT a goal of this API to allow monitoring the resulting performance +characteristics. Monitoring performance is best done with device/vendor +specific tools such as e.g. turbostat. + +Specifically when selecting a high performance profile the actual achieved +performance may be limited by various factors such as: the heat generated +by other components, room temperature, free air flow at the bottom of a +laptop, etc. It is explicitly NOT a goal of this API to let userspace know +about any sub-optimal conditions which are impeding reaching the requested +performance level. + +Since numbers on their own cannot represent the multiple variables that a +profile will adjust (power consumption, heat generation, etc) this API +uses strings to describe the various profiles. To make sure that userspace +gets a consistent experience the sysfs-platform_profile ABI document defines +a fixed set of profile names. Drivers *must* map their internal profile +representation onto this fixed set. + +If there is no good match when mapping then a new profile name may be +added. Drivers which wish to introduce new profile names must: + + 1. Explain why the existing profile names canot be used. + 2. Add the new profile name, along with a clear description of the + expected behaviour, to the sysfs-platform_profile ABI documentation. diff --git a/Documentation/virt/kvm/amd-memory-encryption.rst b/Documentation/virt/kvm/amd-memory-encryption.rst index 09a8f2a34e39..469a6308765b 100644 --- a/Documentation/virt/kvm/amd-memory-encryption.rst +++ b/Documentation/virt/kvm/amd-memory-encryption.rst @@ -263,6 +263,27 @@ Returns: 0 on success, -negative on error __u32 trans_len; }; +10. KVM_SEV_GET_ATTESTATION_REPORT +---------------------------------- + +The KVM_SEV_GET_ATTESTATION_REPORT command can be used by the hypervisor to query the attestation +report containing the SHA-256 digest of the guest memory and VMSA passed through the KVM_SEV_LAUNCH +commands and signed with the PEK. The digest returned by the command should match the digest +used by the guest owner with the KVM_SEV_LAUNCH_MEASURE. + +Parameters (in): struct kvm_sev_attestation + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_attestation_report { + __u8 mnonce[16]; /* A random mnonce that will be placed in the report */ + + __u64 uaddr; /* userspace address where the report should be copied */ + __u32 len; + }; + References ========== diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 99ceb978c8b0..45fd862ac128 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -960,6 +960,14 @@ memory. __u8 pad2[30]; }; +If the KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL flag is returned from the +KVM_CAP_XEN_HVM check, it may be set in the flags field of this ioctl. +This requests KVM to generate the contents of the hypercall page +automatically; hypercalls will be intercepted and passed to userspace +through KVM_EXIT_XEN. In this case, all of the blob size and address +fields must be zero. + +No other flags are currently valid in the struct kvm_xen_hvm_config. 4.29 KVM_GET_CLOCK ------------------ @@ -2268,6 +2276,8 @@ registers, find a list below: PPC KVM_REG_PPC_PSSCR 64 PPC KVM_REG_PPC_DEC_EXPIRY 64 PPC KVM_REG_PPC_PTCR 64 + PPC KVM_REG_PPC_DAWR1 64 + PPC KVM_REG_PPC_DAWRX1 64 PPC KVM_REG_PPC_TM_GPR0 64 ... PPC KVM_REG_PPC_TM_GPR31 64 @@ -4831,6 +4841,101 @@ into user space. If a vCPU is in running state while this ioctl is invoked, the vCPU may experience inconsistent filtering behavior on MSR accesses. +4.127 KVM_XEN_HVM_SET_ATTR +-------------------------- + +:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_xen_hvm_attr +:Returns: 0 on success, < 0 on error + +:: + + struct kvm_xen_hvm_attr { + __u16 type; + __u16 pad[3]; + union { + __u8 long_mode; + __u8 vector; + struct { + __u64 gfn; + } shared_info; + __u64 pad[4]; + } u; + }; + +type values: + +KVM_XEN_ATTR_TYPE_LONG_MODE + Sets the ABI mode of the VM to 32-bit or 64-bit (long mode). This + determines the layout of the shared info pages exposed to the VM. + +KVM_XEN_ATTR_TYPE_SHARED_INFO + Sets the guest physical frame number at which the Xen "shared info" + page resides. Note that although Xen places vcpu_info for the first + 32 vCPUs in the shared_info page, KVM does not automatically do so + and instead requires that KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO be used + explicitly even when the vcpu_info for a given vCPU resides at the + "default" location in the shared_info page. This is because KVM is + not aware of the Xen CPU id which is used as the index into the + vcpu_info[] array, so cannot know the correct default location. + +KVM_XEN_ATTR_TYPE_UPCALL_VECTOR + Sets the exception vector used to deliver Xen event channel upcalls. + +4.128 KVM_XEN_HVM_GET_ATTR +-------------------------- + +:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO +:Architectures: x86 +:Type: vm ioctl +:Parameters: struct kvm_xen_hvm_attr +:Returns: 0 on success, < 0 on error + +Allows Xen VM attributes to be read. For the structure and types, +see KVM_XEN_HVM_SET_ATTR above. + +4.129 KVM_XEN_VCPU_SET_ATTR +--------------------------- + +:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_xen_vcpu_attr +:Returns: 0 on success, < 0 on error + +:: + + struct kvm_xen_vcpu_attr { + __u16 type; + __u16 pad[3]; + union { + __u64 gpa; + __u64 pad[4]; + } u; + }; + +type values: + +KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO + Sets the guest physical address of the vcpu_info for a given vCPU. + +KVM_XEN_VCPU_ATTR_TYPE_VCPU_TIME_INFO + Sets the guest physical address of an additional pvclock structure + for a given vCPU. This is typically used for guest vsyscall support. + +4.130 KVM_XEN_VCPU_GET_ATTR +--------------------------- + +:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO +:Architectures: x86 +:Type: vcpu ioctl +:Parameters: struct kvm_xen_vcpu_attr +:Returns: 0 on success, < 0 on error + +Allows Xen vCPU attributes to be read. For the structure and types, +see KVM_XEN_VCPU_SET_ATTR above. 5. The kvm_run structure ======================== @@ -4893,9 +4998,11 @@ local APIC is not used. __u16 flags; More architecture-specific flags detailing state of the VCPU that may -affect the device's behavior. The only currently defined flag is -KVM_RUN_X86_SMM, which is valid on x86 machines and is set if the -VCPU is in system management mode. +affect the device's behavior. Current defined flags: + /* x86, set if the VCPU is in system management mode */ + #define KVM_RUN_X86_SMM (1 << 0) + /* x86, set if bus lock detected in VM */ + #define KVM_RUN_BUS_LOCK (1 << 1) :: @@ -4996,13 +5103,18 @@ to the byte array. .. note:: - For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR, + For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR, KVM_EXIT_XEN, KVM_EXIT_EPR, KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR the corresponding operations are complete (and guest state is consistent) only after userspace has re-entered the kernel with KVM_RUN. The kernel side will first finish - incomplete operations and then check for pending signals. Userspace - can re-enter the guest with an unmasked signal pending to complete - pending operations. + incomplete operations and then check for pending signals. + + The pending state of the operation is not preserved in state which is + visible to userspace, thus userspace should ensure that the operation is + completed before performing a live migration. Userspace can re-enter the + guest with an unmasked signal pending or with the immediate_exit field set + to complete pending operations without allowing any further instructions + to be executed. :: @@ -5329,6 +5441,34 @@ vCPU execution. If the MSR write was unsuccessful, user space also sets the :: + + struct kvm_xen_exit { + #define KVM_EXIT_XEN_HCALL 1 + __u32 type; + union { + struct { + __u32 longmode; + __u32 cpl; + __u64 input; + __u64 result; + __u64 params[6]; + } hcall; + } u; + }; + /* KVM_EXIT_XEN */ + struct kvm_hyperv_exit xen; + +Indicates that the VCPU exits into userspace to process some tasks +related to Xen emulation. + +Valid values for 'type' are: + + - KVM_EXIT_XEN_HCALL -- synchronously notify user-space about Xen hypercall. + Userspace is expected to place the hypercall result into the appropriate + field before invoking KVM_RUN again. + +:: + /* Fix the size of the union. */ char padding[256]; }; @@ -6038,6 +6178,53 @@ KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR exit notifications which user space can then handle to implement model specific MSR handling and/or user notifications to inform a user that an MSR was not handled. +7.22 KVM_CAP_X86_BUS_LOCK_EXIT +------------------------------- + +:Architectures: x86 +:Target: VM +:Parameters: args[0] defines the policy used when bus locks detected in guest +:Returns: 0 on success, -EINVAL when args[0] contains invalid bits + +Valid bits in args[0] are:: + + #define KVM_BUS_LOCK_DETECTION_OFF (1 << 0) + #define KVM_BUS_LOCK_DETECTION_EXIT (1 << 1) + +Enabling this capability on a VM provides userspace with a way to select +a policy to handle the bus locks detected in guest. Userspace can obtain +the supported modes from the result of KVM_CHECK_EXTENSION and define it +through the KVM_ENABLE_CAP. + +KVM_BUS_LOCK_DETECTION_OFF and KVM_BUS_LOCK_DETECTION_EXIT are supported +currently and mutually exclusive with each other. More bits can be added in +the future. + +With KVM_BUS_LOCK_DETECTION_OFF set, bus locks in guest will not cause vm exits +so that no additional actions are needed. This is the default mode. + +With KVM_BUS_LOCK_DETECTION_EXIT set, vm exits happen when bus lock detected +in VM. KVM just exits to userspace when handling them. Userspace can enforce +its own throttling or other policy based mitigations. + +This capability is aimed to address the thread that VM can exploit bus locks to +degree the performance of the whole system. Once the userspace enable this +capability and select the KVM_BUS_LOCK_DETECTION_EXIT mode, KVM will set the +KVM_RUN_BUS_LOCK flag in vcpu-run->flags field and exit to userspace. Concerning +the bus lock vm exit can be preempted by a higher priority VM exit, the exit +notifications to userspace can be KVM_EXIT_BUS_LOCK or other reasons. +KVM_RUN_BUS_LOCK flag is used to distinguish between them. + +7.22 KVM_CAP_PPC_DAWR1 +---------------------- + +:Architectures: ppc +:Parameters: none +:Returns: 0 on success, -EINVAL when CPU doesn't support 2nd DAWR + +This capability can be used to check / enable 2nd DAWR feature provided +by POWER10 processor. + 8. Other capabilities. ====================== @@ -6415,7 +6602,6 @@ guest according to the bits in the KVM_CPUID_FEATURES CPUID leaf (0x40000001). Otherwise, a guest may use the paravirtual features regardless of what has actually been exposed through the CPUID leaf. - 8.29 KVM_CAP_DIRTY_LOG_RING --------------------------- @@ -6502,3 +6688,29 @@ KVM_GET_DIRTY_LOG and KVM_CLEAR_DIRTY_LOG. After enabling KVM_CAP_DIRTY_LOG_RING with an acceptable dirty ring size, the virtual machine will switch to ring-buffer dirty page tracking and further KVM_GET_DIRTY_LOG or KVM_CLEAR_DIRTY_LOG ioctls will fail. + +8.30 KVM_CAP_XEN_HVM +-------------------- + +:Architectures: x86 + +This capability indicates the features that Xen supports for hosting Xen +PVHVM guests. Valid flags are:: + + #define KVM_XEN_HVM_CONFIG_HYPERCALL_MSR (1 << 0) + #define KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL (1 << 1) + #define KVM_XEN_HVM_CONFIG_SHARED_INFO (1 << 2) + +The KVM_XEN_HVM_CONFIG_HYPERCALL_MSR flag indicates that the KVM_XEN_HVM_CONFIG +ioctl is available, for the guest to set its hypercall page. + +If KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL is also set, the same flag may also be +provided in the flags to KVM_XEN_HVM_CONFIG, without providing hypercall page +contents, to request that KVM generate hypercall page content automatically +and also enable interception of guest hypercalls with KVM_EXIT_XEN. + +The KVM_XEN_HVM_CONFIG_SHARED_INFO flag indicates the availability of the +KVM_XEN_HVM_SET_ATTR, KVM_XEN_HVM_GET_ATTR, KVM_XEN_VCPU_SET_ATTR and +KVM_XEN_VCPU_GET_ATTR ioctls, as well as the delivery of exception vectors +for event channel upcalls when the evtchn_upcall_pending field of a vcpu's +vcpu_info is set. diff --git a/Documentation/virt/kvm/arm/hyp-abi.rst b/Documentation/virt/kvm/arm/hyp-abi.rst index 83cadd8186fa..4d43fbc25195 100644 --- a/Documentation/virt/kvm/arm/hyp-abi.rst +++ b/Documentation/virt/kvm/arm/hyp-abi.rst @@ -58,6 +58,15 @@ these functions (see arch/arm{,64}/include/asm/virt.h): into place (arm64 only), and jump to the restart address while at HYP/EL2. This hypercall is not expected to return to its caller. +* :: + + x0 = HVC_VHE_RESTART (arm64 only) + + Attempt to upgrade the kernel's exception level from EL1 to EL2 by enabling + the VHE mode. This is conditioned by the CPU supporting VHE, the EL2 MMU + being off, and VHE not being disabled by any other means (command line + option, for example). + Any other value of r0/x0 triggers a hypervisor-specific handling, which is not documented here. diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/locking.rst index b21a34c34a21..0aa4817b466d 100644 --- a/Documentation/virt/kvm/locking.rst +++ b/Documentation/virt/kvm/locking.rst @@ -16,7 +16,14 @@ The acquisition orders for mutexes are as follows: - kvm->slots_lock is taken outside kvm->irq_lock, though acquiring them together is quite rare. -On x86, vcpu->mutex is taken outside kvm->arch.hyperv.hv_lock. +On x86: + +- vcpu->mutex is taken outside kvm->arch.hyperv.hv_lock + +- kvm->arch.mmu_lock is an rwlock. kvm->arch.tdp_mmu_pages_lock is + taken inside kvm->arch.mmu_lock, and cannot be taken without already + holding kvm->arch.mmu_lock (typically with ``read_lock``, otherwise + there's no need to take kvm->arch.tdp_mmu_pages_lock at all). Everything else is a leaf: no other lock is taken inside the critical sections. diff --git a/Documentation/virt/kvm/s390-pv-boot.rst b/Documentation/virt/kvm/s390-pv-boot.rst index 8b8fa0390409..ad1f7866c001 100644 --- a/Documentation/virt/kvm/s390-pv-boot.rst +++ b/Documentation/virt/kvm/s390-pv-boot.rst @@ -80,5 +80,5 @@ Keys ---- Every CEC will have a unique public key to enable tooling to build encrypted images. -See `s390-tools <https://github.com/ibm-s390-tools/s390-tools/>`_ +See `s390-tools <https://github.com/ibm-s390-linux/s390-tools/>`_ for the tooling. |
