diff --git a/.clang-format b/.clang-format index 10dc5a9a61b3e33ba3c82e2059db2275e34efa63..01a341ceec6c04935529bb3bc4254a59ec651e93 100644 --- a/.clang-format +++ b/.clang-format @@ -122,6 +122,7 @@ ForEachMacros: - 'drm_for_each_bridge_in_chain' - 'drm_for_each_connector_iter' - 'drm_for_each_crtc' + - 'drm_for_each_crtc_reverse' - 'drm_for_each_encoder' - 'drm_for_each_encoder_mask' - 'drm_for_each_fb' @@ -203,14 +204,13 @@ ForEachMacros: - 'for_each_matching_node' - 'for_each_matching_node_and_match' - 'for_each_member' - - 'for_each_mem_region' - - 'for_each_memblock_type' - 'for_each_memcg_cache_index' - 'for_each_mem_pfn_range' - '__for_each_mem_range' - 'for_each_mem_range' - '__for_each_mem_range_rev' - 'for_each_mem_range_rev' + - 'for_each_mem_region' - 'for_each_migratetype_order' - 'for_each_msi_entry' - 'for_each_msi_entry_safe' @@ -276,10 +276,8 @@ ForEachMacros: - 'for_each_reserved_mem_range' - 'for_each_reserved_mem_region' - 'for_each_rtd_codec_dais' - - 'for_each_rtd_codec_dais_rollback' - 'for_each_rtd_components' - 'for_each_rtd_cpu_dais' - - 'for_each_rtd_cpu_dais_rollback' - 'for_each_rtd_dais' - 'for_each_set_bit' - 'for_each_set_bit_from' @@ -298,6 +296,7 @@ ForEachMacros: - '__for_each_thread' - 'for_each_thread' - 'for_each_unicast_dest_pgid' + - 'for_each_vsi' - 'for_each_wakeup_source' - 'for_each_zone' - 'for_each_zone_zonelist' @@ -330,6 +329,7 @@ ForEachMacros: - 'hlist_for_each_entry_rcu_bh' - 'hlist_for_each_entry_rcu_notrace' - 'hlist_for_each_entry_safe' + - 'hlist_for_each_entry_srcu' - '__hlist_for_each_rcu' - 'hlist_for_each_safe' - 'hlist_nulls_for_each_entry' @@ -378,6 +378,7 @@ ForEachMacros: - 'list_for_each_entry_safe_continue' - 'list_for_each_entry_safe_from' - 'list_for_each_entry_safe_reverse' + - 'list_for_each_entry_srcu' - 'list_for_each_prev' - 'list_for_each_prev_safe' - 'list_for_each_safe' @@ -411,6 +412,8 @@ ForEachMacros: - 'of_property_for_each_string' - 'of_property_for_each_u32' - 'pci_bus_for_each_resource' + - 'pcl_for_each_chunk' + - 'pcl_for_each_segment' - 'pcm_for_each_format' - 'ping_portaddr_for_each_entry' - 'plist_for_each' diff --git a/.mailmap b/.mailmap index cc4e91d3075e824d5188a7186648e57a6a729280..ade90fc9140a2787fbb7e5d4799d79e49ba245b0 100644 --- a/.mailmap +++ b/.mailmap @@ -37,6 +37,7 @@ Andrew Murray Andrew Murray Andrew Vasquez Andrey Ryabinin +Andrey Ryabinin Andy Adamson Antoine Tenart Antoine Tenart @@ -179,6 +180,8 @@ Kees Cook Kees Cook Kees Cook Kees Cook +Keith Busch +Keith Busch Kenneth W Chen Konstantin Khlebnikov Konstantin Khlebnikov @@ -199,6 +202,9 @@ Li Yang Li Yang Lukasz Luba Maciej W. Rozycki +Maciej W. Rozycki +Manivannan Sadhasivam +Manivannan Sadhasivam Marcin Nowakowski Marc Zyngier Mark Brown @@ -244,6 +250,7 @@ Morten Welinder Morten Welinder Morten Welinder Mythri P K +Nathan Chancellor Nguyen Anh Quynh Nicolas Ferre Nicolas Pitre @@ -334,6 +341,8 @@ Vinod Koul Viresh Kumar Viresh Kumar Viresh Kumar +Viresh Kumar +Viresh Kumar Vivien Didelot Vlad Dogaru Vladimir Davydov diff --git a/Documentation/ABI/stable/sysfs-bus-vmbus b/Documentation/ABI/stable/sysfs-bus-vmbus index c27b7b89477ce7778e3b4af0bcc3a36637bfd489..42599d9fa161f86bff3c358f8b58396da5f3714e 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 +Description: Whether the host supports hibernation for the VM. +Users: Daemon that sets up swap partition/file for hibernation. + What: /sys/bus/vmbus/devices//id Date: Jul 2009 KernelVersion: 2.6.31 diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index 35289d47d6cb79d24aec89c5e52318c85d831826..d957f5da5c046b2b07f0b096e693e51022c39c3a 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 0000000000000000000000000000000000000000..7fbcba15bf1ef596b327d1a3f858329bea0d1237 --- /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 a91b4b24496ef932619dad1a610ef8aaeb86ec39..d7f09d011b6d29bc693f42ea527abc8697913ae0 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 +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 0000000000000000000000000000000000000000..2bf6b24e781b061602b43ef5257fb56f096644d5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led-trigger-tty @@ -0,0 +1,6 @@ +What: /sys/class/leds//ttyname +Date: Dec 2020 +KernelVersion: 5.10 +Contact: linux-leds@vger.kernel.org +Description: + Specifies the tty device name of the triggering tty diff --git a/Documentation/ABI/testing/sysfs-class-net b/Documentation/ABI/testing/sysfs-class-net index 1f2002df5ba2378390a7c88573051fc2e1f511fb..1419103d11f97705178d0bf4f6ce6bf5782c2f83 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//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 985d84c585c669084d37fb3df5391a93b4094816..e2da26b44dd0d212a72d592d7288d694ea49a918 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 c310db4ccbc2eeb2aa7250438fd9f7b308b8fdbd..ed79f5893421300b1be0546e534d9a9d2351f44c 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//qmap/mux_id +Date: January 2021 +KernelVersion: 5.12 +Contact: Daniele Palmas +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 8eab41e79ce68cb3fba09977123e790d9460654b..40122d915ae1dfb4372f5d7efe02e7d8452027f2 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 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/-{partner|cable}/usb_power_delivery_revision +Date: January 2021 +Contact: Benson Leung +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//usb_typec_revision Date: April 2017 diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index 3dfee94e06181e0e480353c3d9e98827bc004bcf..cbeac1bebe2fe2983ed39db6b270c415c2d3b7ad 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//stat/sb_status +Date: December 2020 +Contact: "Chao Yu" +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//ckpt_thread_ioprio +Date: January 2021 +Contact: "Daeho Jeong" +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_profile b/Documentation/ABI/testing/sysfs-platform_profile new file mode 100644 index 0000000000000000000000000000000000000000..9d6b89b66cca7f0368830b7f14731872abd42aab --- /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 +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 +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/Makefile b/Documentation/Makefile index 61a7310b49e0ce355e8f73e4afa33d6026545387..9c42dde97671f21d42fc7f484b0eeb217e5c1014 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -75,7 +75,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \ PYTHONDONTWRITEBYTECODE=1 \ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ - $(PYTHON) $(srctree)/scripts/jobserver-exec \ + $(PYTHON3) $(srctree)/scripts/jobserver-exec \ $(SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \ $(SPHINXBUILD) \ -b $2 \ 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 72f0f6fbd53c08e147362ea520456f20f11a0c8f..6f89cf1e567d099aa3c4f963a7b8c628fe19a062 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 d4c9a016074b3c7476819d291cb8105597d3760b..38a39476fc248af893ab574bd13e4eed92278fdf 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 `__, 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 `__) -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] `__ -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 `__. -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 `__ efforts, memory footprint is critically important on single-CPU systems with -non-preemptible (``CONFIG_PREEMPT=n``) kernels, and thus `tiny -RCU `__ +non-preemptible (``CONFIG_PREEMPTION=n``) kernels, and thus `tiny +RCU `__ was born. Josh Triplett has since taken over the small-memory banner with his `Linux kernel tinification `__ project, which resulted in `SRCU `__ 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 `__ -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 `__ 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 `__ 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 `__ 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 `__. #. 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 `__. + `patch `__. #. 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 `__ 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 `__ +`remind `__ 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 `__ +me `__ with this requirement; he also kindly surprised me with `an -algorithm `__ +algorithm `__ 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 `__, +conditions `__, 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 `__. The +patchset `__. 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 `__ did not meet their needs, in conjunction with some `RCU -issues `__ +issues `__ 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 `__ -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 `__ -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 `__ -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 `__, 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 180958388ff94afb557b20922b720956900bab4b..2a92bc685ef1ac043f33e6cb04f61fd9705dddba 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 bb7128eb322ef8f42c0d76ea653da146355ebbb6..1030119294d085c6cabdabb0276e7795ad3a44af 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 f64f4413a47c4583d0de3ea94dc0f305cabbfcb0..3b4a248774961c37f9063195c411a520ce2b9ad7 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 c9ab6af4d3be9a00f4e57c956c6c109a989961c7..7148e9be08c34a4148808c8b742225be63a94115 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 1a4723f48bd9c527ca2f9f65064d9fdff92c64eb..17e95ab2a201434a6a138beaccd31c8174344889 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 63521cd36ce53633f73e5607142a438566b933ab..1de8695c264b25acbad1f6920a556862cfdc4b7d 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 ` 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 ` 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 ` for details. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index a10b545c2070a54455c3e7181cc43135dc68f611..07f9372b494aa134740facf4d2821a489545333c 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: ,, + 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: 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: - 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. @@ -2257,6 +2258,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 +3462,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 +3906,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 +4089,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 +4180,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 +4333,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 +4473,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 +4567,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 +5347,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/media/rkisp1.rst b/Documentation/admin-guide/media/rkisp1.rst index 2267e4fb475e58921b8fd60a6495a492e0570388..ccf418713623b676935cb422956c7418a15bd23c 100644 --- a/Documentation/admin-guide/media/rkisp1.rst +++ b/Documentation/admin-guide/media/rkisp1.rst @@ -13,6 +13,22 @@ This file documents the driver for the Rockchip ISP1 that is part of RK3288 and RK3399 SoCs. The driver is located under drivers/staging/media/rkisp1 and uses the Media-Controller API. +Revisions +========= + +There exist multiple smaller revisions to this ISP that got introduced in +later SoCs. Revisions can be found in the enum :c:type:`rkisp1_cif_isp_version` +in the UAPI and the revision of the ISP inside the running SoC can be read +in the field hw_revision of struct media_device_info as returned by +ioctl MEDIA_IOC_DEVICE_INFO. + +Versions in use are: + +- RKISP1_V10: used at least in rk3288 and rk3399 +- RKISP1_V11: declared in the original vendor code, but not used +- RKISP1_V12: used at least in rk3326 and px30 +- RKISP1_V13: used at least in rk1808 + Topology ======== .. _rkisp1_topology_graph: diff --git a/Documentation/admin-guide/perf/arm-cmn.rst b/Documentation/admin-guide/perf/arm-cmn.rst index 0e48093460140b8ca1542b7d5b62b1cf458d55d9..796e25b7027b29bf17a74f89a80ab3376defe232 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/syscall-user-dispatch.rst b/Documentation/admin-guide/syscall-user-dispatch.rst index a380d651577457c6a03060beb072085707517c2b..60314953c72841bb9c43149e168edcc91c8a9e46 100644 --- a/Documentation/admin-guide/syscall-user-dispatch.rst +++ b/Documentation/admin-guide/syscall-user-dispatch.rst @@ -70,8 +70,8 @@ trampoline code on the vDSO, that trampoline is never intercepted. [selector] is a pointer to a char-sized region in the process memory region, that provides a quick way to enable disable syscall redirection thread-wide, without the need to invoke the kernel directly. selector -can be set to PR_SYS_DISPATCH_ON or PR_SYS_DISPATCH_OFF. Any other -value should terminate the program with a SIGSYS. +can be set to SYSCALL_DISPATCH_FILTER_ALLOW or SYSCALL_DISPATCH_FILTER_BLOCK. +Any other value should terminate the program with a SIGSYS. Security Notes -------------- diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst index 613cb24c76c7cce99e4c0dcd772bdcff540697dd..f18e881373c4070b7ebd7bacdbb544a4625874d1 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 86de8a1ad91c2313f20e493dc775e1fcd90289c6..6178153d33200e8ebf5179b3fb8cdea497e74c46 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 36771a131b566087fdbc2c4a92982ce7ac9abe9b..ddb867e0185b41e3816d0033974078e0da6b683c 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/queue-sysfs.rst b/Documentation/block/queue-sysfs.rst index 2638d3446b79457d9772145e0d70a358349f9087..4dc7f0d499a8454f08f6d2187ced4f6482353721 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 , February 2009 diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst index 2df7b067ab93f532c4d34b4fdf7142b58f965502..0e15f9b05c9d6e191a7696076f8351d50f4bbebe 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 5b613d2a5f1a1fcec5635ad8546f3538897fff5e..2ed89abbf9a4131b24d81cbd62d2467ab0483247 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/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index 1651d961f06a67ab1d3fc5858023c761658c346c..a248ac3941bed10022329c14d15e29f157a0ec57 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 3341788d10965618e73117c574d2e7e22a55013c..5f6769bf45bd9f31723b997d45b1806f2f69a18a 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 0000000000000000000000000000000000000000..eee7cda9f91b670cfa404a26f64f4d266b9512cc --- /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 + +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 b5ce5b39bb9ca425531b8a3e15b5e00da5299209..667d58e0a659441d475ee0c2def630982d1d5017 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 62cd4e89817c3932c29971c1a97ce6945fd354e7..67719f15eb4c8ea89d1246d844b4f272bf2c7cf3 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 5fec063d9a13c11c3a6810102d248b0cdd0d62d1..e55731f43c845c347fbab538b8b788819ef3b8ae 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 f02fd10de604b90907e5b9336183457a8fcc33f3..26b886b20b27bb394cf3e489f1990a2ed7b0d7c3 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 34000f7fbe02be4a2104a30245bde07dee7421f7..297c87f45db845cc13d144d0f864bffb618d7377 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 53f0d4e3ea982f95466c1a1a63a0052ff6b2cc31..93b3bdf6eaeb7539ba94e228afec7a90c5140b44 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 0a9889debc7c1ec8508b1a5e44b8457e241675b1..c299dc907f6c132365c8bdab1f710c5a1f67bc03 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 693ef3f185a8d44ba7f3f184f85591eb757b5fac..e17ac049e890c8324cee05a597db4e1073c757a6 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 c97d4a580f47b0b1674b9f43b62e3d780f21a8cf..174134f920e1de97b1c71186a9296a13de1d47ab 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: @@ -167,6 +169,11 @@ properties: - xiaomi,lavender - const: qcom,sdm660 + - items: + - enum: + - qcom,sdx55-mtp + - const: qcom,sdx55 + - items: - enum: - qcom,ipq6018-cp01-c1 @@ -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 fe11be65039a059c10388beb28266e025fae3576..5fd0696a9f91f3830d59cf8587b74dfc7a970f08 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 ef4544ad6f82d5e054162edaa7f00b69a2f04c73..8a2dd9f1cff25e45357e1999a1c2c87bbef8c2e6 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 b25eb35d1b66354b7c0a1673177db80705c43f6c..0000000000000000000000000000000000000000 --- 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 - - Barry Song - -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 d11d80006a19037b50d0922054185ffe6371373c..0000000000000000000000000000000000000000 --- 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 6db32fbf813fdca0837f236dc5d806128040790b..08607c7ec1bfaebe604ee631d376677c8a0a970a 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 c5fbf869aa93a0405ddbde1793041a8907446955..b9f75e20fef5cc20d5e775c792ace63b863496df 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 e0c6787f6e9494785faacbd338209d6c2482bd8b..f52c7e8ce654b081ded138e299602247c896b43b 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 7e66b7f7ba963e871f56209835964f08ac4f70ec..0000000000000000000000000000000000000000 --- 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 672f8129cd3199a970c58ee69650cd8c1886dfe5..0000000000000000000000000000000000000000 --- 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 - -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 32d33b983d66f7bb81d87cd8c11b3ce360753a68..3d719f468a5bdb9d7e536ad7e75e9e86ecee0c70 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 a04f5fd30122064f2a03f24441cf7b37b5e537f2..0000000000000000000000000000000000000000 --- 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 92672235de57a50d346ae91db0530abb7df8becd..0000000000000000000000000000000000000000 --- 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 0ff6e9b9a13fa2f7abed53be7c74f4786af199ee..0000000000000000000000000000000000000000 --- 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 b1e4973b5769ddcb9c75817598f7d37f6b3ca03c..0000000000000000000000000000000000000000 --- 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 4286ed767a0a543d0f3268357e0e8291e1a30763..ce11b202719956f73966cac49ac8c16f10920334 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/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml index 27fffafe5b5c0b2b4b64d4d2c120f0188ad7742d..3207608d1178315f3379254263b87f2d153ebb3a 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -105,26 +105,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 +174,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/firmware/qcom,scm.txt b/Documentation/devicetree/bindings/firmware/qcom,scm.txt index 78456437df5f70a925439196561d3bb629a97170..a884955f861ecf905c57a204be14fc78a46947d9 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 4db3b8a3332c28dd18c11dce9ba0cc7b774feb2f..9cf6137dd52413f956ed8c46e6c024efde5e27be 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/iio/accel/kionix,kxcjk1013.yaml b/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.yaml index 5667d09dfe6a1643fdb8238be0cf44aabf91e997..fbb714431e3dee50de95bcd3cf38a95076028a14 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 5ccbb1f81960c371084bbfe240e3769f0aa4395d..e759a5da708d2a77b0343fbfd14af259d2b40ca1 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 e0e0755cabd8af9a80b68cb5f1df379e8971841b..f42e1807837628114da2f852eb58503ee3b0c030 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 0000000000000000000000000000000000000000..d5c54813ce872fb00724cfd12163580226363217 --- /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 + +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 271998610ceb1e5e4ebdeafe894e7842d797d29a..5f5b578316bc917547235ce5be927804d081390f 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 0466483be6bb1b40159981620736c0a2ce83e70f..b6bbc312a7cf7e3d4c6299cae38714b5a8d8267a 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 233fe207aded2f1df267722b59b5ce5ca05f27cc..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..7e2accc3d5ce7a0fb3ff2c02ce3c979545cd57da --- /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 + +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 + 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 f2f64749e81817c275e2710ddffcd76efc093f59..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..edbc2921aabd006b710b5ba949cbd42ef857ec70 --- /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 + +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 + 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 cdef7aeba708c3d91c4b12e314662b7e1928dca6..2867ab6bf9b081b614ca66252faf1e6db6fb5655 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 0000000000000000000000000000000000000000..4b0ef1ef5445ef66dc7015347595742f0ba60c1d --- /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 + +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 + #include + 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/input/adc-keys.txt b/Documentation/devicetree/bindings/input/adc-keys.txt index e551814629b48e3a0ece53bf226864a701d1ed61..6c8be6a9ace286c359c1ed50fca83879b01e18ed 100644 --- a/Documentation/devicetree/bindings/input/adc-keys.txt +++ b/Documentation/devicetree/bindings/input/adc-keys.txt @@ -5,7 +5,8 @@ Required properties: - compatible: "adc-keys" - io-channels: Phandle to an ADC channel - io-channel-names = "buttons"; - - keyup-threshold-microvolt: Voltage at which all the keys are considered up. + - keyup-threshold-microvolt: Voltage above or equal to which all the keys are + considered up. Optional properties: - poll-interval: Poll interval time in milliseconds @@ -17,7 +18,12 @@ Each button (key) is represented as a sub-node of "adc-keys": Required subnode-properties: - label: Descriptive name of the key. - linux,code: Keycode to emit. - - press-threshold-microvolt: Voltage ADC input when this key is pressed. + - press-threshold-microvolt: voltage above or equal to which this key is + considered pressed. + +No two values of press-threshold-microvolt may be the same. +All values of press-threshold-microvolt must be less than +keyup-threshold-microvolt. Example: @@ -47,3 +53,15 @@ Example: press-threshold-microvolt = <500000>; }; }; + ++--------------------------------+------------------------+ +| 2.000.000 <= value | no key pressed | ++--------------------------------+------------------------+ +| 1.500.000 <= value < 2.000.000 | KEY_VOLUMEUP pressed | ++--------------------------------+------------------------+ +| 1.000.000 <= value < 1.500.000 | KEY_VOLUMEDOWN pressed | ++--------------------------------+------------------------+ +| 500.000 <= value < 1.000.000 | KEY_ENTER pressed | ++--------------------------------+------------------------+ +| value < 500.000 | no key pressed | ++--------------------------------+------------------------+ diff --git a/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml b/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml index da5b0d87e16d08aefec0c59826ff2253b6852c2e..93f2ce3130ae7e9c55806162d994a0414c3e94b4 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml +++ b/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml @@ -26,6 +26,7 @@ properties: - goodix,gt927 - goodix,gt9271 - goodix,gt928 + - goodix,gt9286 - goodix,gt967 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 0000000000000000000000000000000000000000..4db24b8a9ffe225ba9db50f1fc53b25273927b16 --- /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 + - Maxime Ripard + +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 + + 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 = ; + }; + +... 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 8acca0ae3129877d80a5e02469f343a2c0bd4290..7fc9ad5ef38cc90a794237e12529dbbc6ed12b91 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 1df293953327be9fcda68e85c400d84fd2fb5df9..e9afb48182c78f8fa241ac0239782328210a2b3d 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,-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 0000000000000000000000000000000000000000..9e76fff20323c6f1508c5109925b752ecdf168d4 --- /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 + - Bert Vermeulen + - John Crispin + +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 355c18a3a4d30ddb3bdeedfd39e204c67cf7c896..0000000000000000000000000000000000000000 --- 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 = ; - }; - - irq1: interrupt-controller@100 { - reg = <0x100 0x100>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = ; - }; - - irq2: interrupt-controller@300 { - reg = <0x300 0x100>; - interrupt-controller; - #interrupt-cells = <2>; - interrupts = ; - }; -}; 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 ee3f9c35150115f548814c68f500662cbaf40bc6..0000000000000000000000000000000000000000 --- 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/allwinner,sun8i-h3-deinterlace.yaml b/Documentation/devicetree/bindings/media/allwinner,sun8i-h3-deinterlace.yaml index 6a56214c6cfdf6027cef6dc7d31e4c7ac6b42dcb..b80980b1908ede7048beaa651aa3aeb929f6e2cd 100644 --- a/Documentation/devicetree/bindings/media/allwinner,sun8i-h3-deinterlace.yaml +++ b/Documentation/devicetree/bindings/media/allwinner,sun8i-h3-deinterlace.yaml @@ -19,6 +19,9 @@ properties: compatible: 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/marvell,mmp2-ccic.yaml b/Documentation/devicetree/bindings/media/marvell,mmp2-ccic.yaml index 49bff738aca54006f92dbee5642228ff039673cb..52eab686a17745a4bae356cd2490a299e7d9eec4 100644 --- a/Documentation/devicetree/bindings/media/marvell,mmp2-ccic.yaml +++ b/Documentation/devicetree/bindings/media/marvell,mmp2-ccic.yaml @@ -23,6 +23,9 @@ properties: interrupts: maxItems: 1 + power-domains: + maxItems: 1 + port: type: object additionalProperties: false @@ -75,6 +78,7 @@ additionalProperties: false examples: - | #include + #include camera@d420a000 { compatible = "marvell,mmp2-ccic"; @@ -84,6 +88,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/memory-controllers/renesas,rpc-if.yaml b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml index 6d6ba608fd2215824963ebb5623925f1e4aa914a..990489fdd2ac33fe7d11e0311f5ffe99356b774c 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 0000000000000000000000000000000000000000..d5805725befb9ba7f00207a9b3d208d4dc3c75ec --- /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 + +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 0000000000000000000000000000000000000000..40130fefa2b413e67c5cda5fd60b02837c159daf --- /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 + +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 0000000000000000000000000000000000000000..0fada1f085a92b32de6851ce1ec1a74d1999acb1 --- /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 + +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 0000000000000000000000000000000000000000..4982b458ac12ba0af385a888941724d9d2d951f3 --- /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 + +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 0000000000000000000000000000000000000000..aadff8ce0f49c7e59b310ea83eb5ff93834efcaf --- /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 + - Sander Vanheule + +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/net/amlogic,meson-dwmac.yaml b/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml index 1f133f4a2924c0cd279b9263f43a6aa617d5412c..0467441d70370139218959db5554f93bba37ac91 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 0000000000000000000000000000000000000000..79c38ea142372ab6e5befa4a940ff5d522a919ea --- /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 + +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 + #include + + ethernet@80002000 { + compatible = "brcm,bcm4908-enet"; + reg = <0x80002000 0x1000>; + + interrupts = ; + 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 97ca62b0e14d854aa0bbfeed0f159023ba66e140..d0935d2afef8cf81f160673b2ace36578cb6916a 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 b1ad6ee68e909318bfa167967abcf49dcc59d0a4..f546b1f7dd6d24c637e156162ed12e4ec96704c3 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 0d2df30f19db6ac9911bec9ab396ce0bc13785f0..fe6a949a2eab2fcaa8e24e13ece7353750308370 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 0000000000000000000000000000000000000000..3f01b65f3b22705a31d7aee582431b7eb004f52f --- /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 + +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 0000000000000000000000000000000000000000..d730fe5a4355d9e47670c464498ec38445008604 --- /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 + +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 560369efad6cae253c1f88282122ca41b717b09b..de04626a8e9dbf24565f7ca18134be154a747c86 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 dac4aadb6e2e70ba6c147446481afb47a98d6479..f599c1d9c961763f9c3df2e14b22ac8259f1ced0 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 b78397669320d125a2578e578f7264360a8770d0..ce15c173f43fc5519c196d0278702145f7a2cbda 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 64b3357ade8a0c543f0b5f78e02e2e66339a6e72..b3d4013b7ca6cae38e467427e9ae7a39056c5fcf 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 8a2d12644675b0927064bb1c542c0c95c887a991..8f86084bf12e9af60061ed50cb0875df33e5a152 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 + #include #include #include @@ -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 de9dd574a2f954a3ba3f59406db98952c0acfcb2..91ba96d43c6c12359c9646c29c9f5e956fad3590 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 c47b58f3e3f6e62c38371ae5c54168511c1f527d..3fae9a5f0c6a4f264ce3692fac8be52767bc090c 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 @@ -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 9b7117920d9060ae7a5f087f877ec730efa85c74..ce43a1c58a57152bd0e2e6531ae276fc2204a633 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 0000000000000000000000000000000000000000..59724d18e6f32c2709718f9f080d5c57e0983c40 --- /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 + +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 + + soc { + #address-cells = <2>; + #size-cells = <2>; + + piether: ethernet@28000000 { + compatible = "toshiba,visconti-dwmac", "snps,dwmac-4.20a"; + reg = <0 0x28000000 0 0x10000>; + interrupts = ; + 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 7360617cdedb54deb56f31aacc3ab65e07ada886..2cd452419ed0cb4651818299a1e46a805f77aa3e 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 0000000000000000000000000000000000000000..40b08d83c80bf57c9cb9b032726648d11acb1d69 --- /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 + +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 + + 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 d14cb9bac8497989c7f4d4353882f78ecc295831..f234a756c193b7ef5f855b053b989fcc1da005dc 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 64825128ee972bbc947ad540b1ebf2f2d8d34680..1ea21acbbd55480bfb46868f81f826038d58b57a 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 0000000000000000000000000000000000000000..88aebb370838028636e23b7203e0377b676a7f61 --- /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 + +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 2df4bddeb688918126fd45d9325adf1f6d861988..0000000000000000000000000000000000000000 --- 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 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 0000000000000000000000000000000000000000..9bf40952e5b7d2866d872df9719856c2aef1460c --- /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 + +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 + #include + #include + + 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 = ; + #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 0505de742d30d4eb963985858343594dd60d0cab..0000000000000000000000000000000000000000 --- 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 b015508f978015b0395ac33e7b60dd552b394283..0000000000000000000000000000000000000000 --- 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 37c2a601c3fa8ab075cbc2a7817876386a0600f3..b1b0ee769b7146dd4b84df45adfb80bcdcb3b1cd 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 9702c07a6b6c77e564db9849d3911e6e553e9ad6..2b06c6ce4a75b29673d98f7b8cd99de12969c69e 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 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 ce1d89496342c9eef6825a4b7c57082cbd23013b..14c7594c88c68de4bc30b84a44fcf2d15173b433 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 allOf: - $ref: "serial.yaml" diff --git a/Documentation/devicetree/bindings/serial/pl011.yaml b/Documentation/devicetree/bindings/serial/pl011.yaml index 07fa6d26f2b43c8091f0a4d61701930bee44364c..1f8e9f2644b6b80e6fcba0b0fd670b1bcede06d7 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 c139c5edb93ef997a4572e786b0cc50c55b5dc1a..512a84942f78b2cc48e9e1a08ce6d73d4053af6e 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 1e48bbbeecc6dd277d21bfc67a8ea7393480aa41..0000000000000000000000000000000000000000 --- 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 06d5f251ec8805b0198226ed200ee37d5df0eb02..8631678283f9aaf2db31085722780dc1eecfee63 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 0000000000000000000000000000000000000000..effcc72f94253dcd14a5ded6a08f4555decf5a47 --- /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 + +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 953add19e937d110f7868f8cf1a69782bdf99e39..19c059e44681cc3e52fe9e6ba00e51bd8378aafd 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 9326cdf6e1b1c80083b04e12e95e9387bf48e3ec..0000000000000000000000000000000000000000 --- 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: - Definition: must be: - "qcom,smem" - -- memory-region: - Usage: required - Value type: - Definition: handle to memory reservation for main SMEM memory region. - -- qcom,rpm-msg-ram: - Usage: required - Value type: - Definition: handle to RPM message memory resource - -- hwlocks: - Usage: required - Value type: - 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 0000000000000000000000000000000000000000..f7e17713b3d886c6f1f0bf5cf4f0f43fc46fa985 --- /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 + - Bjorn Andersson + +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 037c51b2f972211e750d63d13d98b342d1f7b614..dbc62821c60b11e583a65315dd94693f0e18ba6a 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 = , + , + , + , + , + , + ; + 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 7629de1c2c727fa9c14117e8b591c4ccb778d8b8..0000000000000000000000000000000000000000 --- 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/spi/spi-zynq-qspi.txt b/Documentation/devicetree/bindings/spi/spi-zynq-qspi.txt deleted file mode 100644 index 16b734ad31027a18d03238c4032dfba33427ee3b..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..1f1c40a9f3203b3056fc4cf7eeb166dd90d9e403 --- /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 + +# 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 b66a07e21d1e5de756438bc5f690459aa00a00c1..1c426c211e3668baf3a44077026b07c3e0a7bc06 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 19d116ff9ddcb18a0b373269478920c9fa3f29e5..6d65771e979c8ab10ecda9f56acc8da69259c55f 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 ea22dfe485beec11253c502c85943faa32593217..97258f1a1505bf504fdda399945187e20c59b287 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 9499bc8ee9e33283561ddb1dcb0d8f2497346a94..0000000000000000000000000000000000000000 --- 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 d96c1e283e736c96c778b837efa5d80ee89991f3..0000000000000000000000000000000000000000 --- 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 bdc2dc318178d387a466ebd98b2b060a6d40c20b..a327130d1faa5b33d400b6168019b6812528f51d 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 c0058332b967101d49ceedb3da1941b59afa8609..e349fa5de60611e155333c8f9cec378b139139ba 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 df0e02e1ee43e7b8bf88486d26bea2ed92d8aeef..bf73de0d5b4af1fbaba0919029a19a13cc83357c 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 4aae5b2cef56e65d1d20f0a5a0960f19488a2001..a668f43bedf549b9ddb7d4a0ce56b942e324fd6b 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 1aae2b6160c13c54635293e996d9fea8ab4a3f73..0000000000000000000000000000000000000000 --- 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. - - - 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 6aae1544f240550b7a1eeb78b590ffa9a71adb0b..f7ae79825d7d33c022af19ea7753e890c7684b96 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 0000000000000000000000000000000000000000..cb4c6f6d3a33a3f50753b763f230475e0726f169 --- /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 + +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 + #include + 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 = ; + #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 = ; + 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 247ef00381ea04892f31bd40e5c38b48665f5d27..6816de7dfc0029999f86aee14931d30503e443e0 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 2178bcc401bcbe947fc87b6baa88655f4276f81c..53df281f618c0db0168eadae94dc15f0a587499a 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 0000000000000000000000000000000000000000..23d73df96ea3ad90cc9294e6fac8b97a377bb88e --- /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 + +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 ba472e7aefc9db716dfdf770ae0bef3a9486dc2c..0000000000000000000000000000000000000000 --- 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 dd32c10ce6c729082f3a811a1223ea89cccc7627..43b91ab62004b2661fb07247274adaeeb84a3e72 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 = ; 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 42d8814f903a9ca36ece3a0eec41bbdae9f555bd..0000000000000000000000000000000000000000 --- 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,-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 = ; - 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,-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 = ; - 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 0000000000000000000000000000000000000000..14f40efb3b22c2a060c9e649b78184b4386b1207 --- /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 + +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 + #include + #include + #include + #include + + usb@11270000 { + compatible = "mediatek,mt8173-xhci", "mediatek,mtk-xhci"; + reg = <0x11270000 0x1000>, <0x11280700 0x0100>; + reg-names = "mac", "ippc"; + interrupts = ; + 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 a82ca438aec1f1063953ec231ec58534911c24aa..0000000000000000000000000000000000000000 --- 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,-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 = ; - 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 = ; - 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 0000000000000000000000000000000000000000..f5c04b9d2de966ba30ef013912073a79ce053e2c --- /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 + +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 + #include + #include + #include + #include + + usb@11271000 { + compatible = "mediatek,mt8173-mtu3", "mediatek,mtu3"; + reg = <0x11271000 0x3000>, <0x11280700 0x0100>; + reg-names = "mac", "ippc"; + interrupts = ; + 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 = ; + 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 + #include + + usb@112c1000 { + compatible = "mediatek,mt2712-mtu3", "mediatek,mtu3"; + reg = <0x112c1000 0x3000>, <0x112d0700 0x0100>; + reg-names = "mac", "ippc"; + interrupts = ; + 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 = ; + 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 = ; + 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 5eedb02965622c0c6ffcc2bb29b028a03b229325..0000000000000000000000000000000000000000 --- 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 = ; - 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 0000000000000000000000000000000000000000..84ddacfdbe9b08fe342679181901c54d69f2cedd --- /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 + +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 + #include + #include + #include + #include + #include + + usb@11200000 { + compatible = "mediatek,mt2701-musb", "mediatek,mtk-musb"; + reg = <0x11200000 0x1000>; + interrupts = ; + 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 38d9bb8507cf16fd47ef0620b2514587d4ac742f..f0dbc5ae45ae8c351bfc722eb6a6cd67d814bb5f 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 2cf525d21e054ac760541fa7ec8b553c34c30ef7..c3cbd1fa994490f8073e81a0c4db3bb352da426a 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 = ; diff --git a/Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml b/Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml index 22603256ddf8f8d852c140f360f5bc8907c0d3f6..4c5efaf0230803175cfd0c6e374bc8f9f850cbcc 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 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 94520493233bb51ae663cc3b30f6ea1816474bd2..0000000000000000000000000000000000000000 --- 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 = ; - 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 = ; - 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 0000000000000000000000000000000000000000..04077f2d7faffdb694d7f891fada14e4bfbcfdf6 --- /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 + +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 + #include + + bus { + #address-cells = <2>; + #size-cells = <2>; + + usbdrd3_0: usb@fe800000 { + compatible = "rockchip,rk3399-dwc3", "snps,dwc3"; + reg = <0x0 0xfe800000 0x0 0x100000>; + interrupts = ; + 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 0000000000000000000000000000000000000000..2247da77eac1b66b8462965556c04ded59e44dc2 --- /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 + +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 c1b19fc5d0a2a8d231e6f1c840544acadddd654f..ca7fbe3ed22e3f43b2ea3da1e8e7116919bbf149 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 036be172b1ae8cf2ebd4bfde3a1a47898c9b38d2..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..d4c99809ee9a4ef7ff2eb7dac5065f722d9a4d96 --- /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 + +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 0000000000000000000000000000000000000000..f229fc8068d999ca6bc58309e9a7ec6189c41aff --- /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 + +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 b545b087b34221106d03e84d9b252311e6bd9245..56853c17af6677274c886a3731fbaac0754e8013 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 +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 0c5cff84a969f29e8dc59b8dfe93065169db47b0..0000000000000000000000000000000000000000 --- 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 0000000000000000000000000000000000000000..965f87fef70205abc41aacd3ac726ccca034be83 --- /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 + +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 0000000000000000000000000000000000000000..78491e66ed24378f6d08ad0a978f333dd8d78b3e --- /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 + +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 b353b9816487e6d8daeccde9d65b51eaf386e16d..b796836d2ce71bd1ff8ddb24d62bdbca14ee245c 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 041ae90b0d8fd20bd2fee50b89b4e3f75a612d65..b4e026f2d6c52d892bd3f1ad3ec556ce53630607 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,.*": diff --git a/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml b/Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml index 8e3760a3822b94f78153d3fd0b5af1257d09c539..b8e4118945a086cb34117c1309b075ba277e48f6 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/driver-api/auxiliary_bus.rst b/Documentation/driver-api/auxiliary_bus.rst index 2312506b067404b5cc52ed535dc02a593cd3b583..fff96c7ba7a858ca002587e422b19cfdd894dae2 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/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index dae15c96e659e2bdaaf24cf760912cec855f079e..35ed01a5fbc9ddf56d7a96f47b3c05779aa0ec3b 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//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 e0204a23e997e2feaf078bfb653165e2efc2c1d1..1d831e3cbcb33d0623844d83bddc607501e66c0a 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/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index 587a939739290628f7c236443493f570c6df7040..78240e29b0bb676963ffe1dfb023d5e501fd1e51 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -586,6 +586,14 @@ without significant effort. The advantage of mounting with the "volatile" option is that all forms of sync calls to the upper filesystem are omitted. +In order to avoid a giving a false sense of safety, the syncfs (and fsync) +semantics of volatile mounts are slightly different than that of the rest of +VFS. If any writeback error occurs on the upperdir's filesystem after a +volatile mount takes place, all sync functions will return an error. Once this +condition is reached, the filesystem will not recover, and every subsequent sync +call will return an error, even if the upperdir has not experience a new error +since the last sync call. + When overlay is mounted with "volatile" option, the directory "$workdir/work/incompat/volatile" is created. During next mount, overlay checks for this directory and refuses to mount if present. This is a strong diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst index 867036aa90b8394cea582fdbd183e747a630488a..1f8cf8e10b340acc7e315c3c9e166896567f5d2c 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 1a152dd1d7654ae8139caf69875291e06bc820f0..03cd4e25fc451edfb61720a20ae882033baa9aec 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 b36aa3e743d8479be91c739f4ed6c2a769748829..4e264c16ddff640e29251d5c6892cf9d3472a354 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/kbuild/gcc-plugins.rst b/Documentation/kbuild/gcc-plugins.rst index 4b1c10f88e304ee8e03bb0855e7491c4c123538c..3349966f213dcff110e855fcc42efbb638a9cae6 100644 --- a/Documentation/kbuild/gcc-plugins.rst +++ b/Documentation/kbuild/gcc-plugins.rst @@ -11,16 +11,13 @@ compiler [1]_. They are useful for runtime instrumentation and static analysis. We can analyse, change and add further code during compilation via callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_. -The GCC plugin infrastructure of the kernel supports all gcc versions from -4.5 to 6.0, building out-of-tree modules, cross-compilation and building in a -separate directory. -Plugin source files have to be compilable by both a C and a C++ compiler as well -because gcc versions 4.5 and 4.6 are compiled by a C compiler, -gcc-4.7 can be compiled by a C or a C++ compiler, -and versions 4.8+ can only be compiled by a C++ compiler. +The GCC plugin infrastructure of the kernel supports building out-of-tree +modules, cross-compilation and building in a separate directory. +Plugin source files have to be compilable by a C++ compiler. -Currently the GCC plugin infrastructure supports only the x86, arm, arm64 and -powerpc architectures. +Currently the GCC plugin infrastructure supports only some architectures. +Grep "select HAVE_GCC_PLUGINS" to find out which architectures support +GCC plugins. This infrastructure was ported from grsecurity [6]_ and PaX [7]_. @@ -47,20 +44,13 @@ Files This is a compatibility header for GCC plugins. It should be always included instead of individual gcc headers. -**$(src)/scripts/gcc-plugin.sh** - - This script checks the availability of the included headers in - gcc-common.h and chooses the proper host compiler to build the plugins - (gcc-4.7 can be built by either gcc or g++). - **$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h, $(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h, $(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h, $(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h** These headers automatically generate the registration structures for - GIMPLE, SIMPLE_IPA, IPA and RTL passes. They support all gcc versions - from 4.5 to 6.0. + GIMPLE, SIMPLE_IPA, IPA and RTL passes. They should be preferred to creating the structures by hand. @@ -68,21 +58,25 @@ Usage ===== You must install the gcc plugin headers for your gcc version, -e.g., on Ubuntu for gcc-4.9:: +e.g., on Ubuntu for gcc-10:: - apt-get install gcc-4.9-plugin-dev + apt-get install gcc-10-plugin-dev Or on Fedora:: dnf install gcc-plugin-devel -Enable a GCC plugin based feature in the kernel config:: +Enable the GCC plugin infrastructure and some plugin(s) you want to use +in the kernel config:: - CONFIG_GCC_PLUGIN_CYC_COMPLEXITY = y + CONFIG_GCC_PLUGINS=y + CONFIG_GCC_PLUGIN_CYC_COMPLEXITY=y + CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y + ... -To compile only the plugin(s):: +To compile the minimum tool set including the plugin(s):: - make gcc-plugins + make scripts or just run the kernel make and compile the whole kernel with the cyclomatic complexity GCC plugin. @@ -91,7 +85,8 @@ the cyclomatic complexity GCC plugin. 4. How to add a new GCC plugin ============================== -The GCC plugins are in $(src)/scripts/gcc-plugins/. You can use a file or a directory -here. It must be added to $(src)/scripts/gcc-plugins/Makefile, -$(src)/scripts/Makefile.gcc-plugins and $(src)/arch/Kconfig. +The GCC plugins are in scripts/gcc-plugins/. You need to put plugin source files +right under scripts/gcc-plugins/. Creating subdirectories is not supported. +It must be added to scripts/gcc-plugins/Makefile, scripts/Makefile.gcc-plugins +and a relevant Kconfig file. See the cyc_complexity_plugin.c (CONFIG_GCC_PLUGIN_CYC_COMPLEXITY) GCC plugin. diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst index 21c847890d03c4a337ec2824a1a152ede3b300f7..b18401d2ba8204bb66551f5e5c67bc22c13a52f4 100644 --- a/Documentation/kbuild/llvm.rst +++ b/Documentation/kbuild/llvm.rst @@ -63,6 +63,50 @@ They can be enabled individually. The full list of the parameters: :: Currently, the integrated assembler is disabled by default. You can pass ``LLVM_IAS=1`` to enable it. +Supported Architectures +----------------------- + +LLVM does not target all of the architectures that Linux supports and +just because a target is supported in LLVM does not mean that the kernel +will build or work without any issues. Below is a general summary of +architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level +of support corresponds to "S" values in the MAINTAINERS files. If an +architecture is not present, it either means that LLVM does not target +it or there are known issues. Using the latest stable version of LLVM or +even the development tree will generally yield the best results. +An architecture's ``defconfig`` is generally expected to work well, +certain configurations may have problems that have not been uncovered +yet. Bug reports are always welcome at the issue tracker below! + +.. list-table:: + :widths: 10 10 10 + :header-rows: 1 + + * - Architecture + - Level of support + - ``make`` command + * - arm + - Supported + - ``LLVM=1`` + * - arm64 + - Supported + - ``LLVM=1`` + * - mips + - Maintained + - ``CC=clang`` + * - powerpc + - Maintained + - ``CC=clang`` + * - riscv + - Maintained + - ``CC=clang`` + * - s390 + - Maintained + - ``CC=clang`` + * - x86 + - Supported + - ``LLVM=1`` + Getting Help ------------ diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index 9f6a1188195136089fda768bf2ab88cc60c5dae4..910c6303c7eaf2711c62b8f71d63acd4fc5fb18e 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -755,7 +755,7 @@ more details, with real examples. bits on the scripts nonetheless. Kbuild provides variables $(CONFIG_SHELL), $(AWK), $(PERL), - $(PYTHON) and $(PYTHON3) to refer to interpreters for the respective + and $(PYTHON3) to refer to interpreters for the respective scripts. Example:: @@ -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 adc314639085b273d9e99dd3fab97f387e4bffaf..5f690f0ad0e4f136b29da05e4475af0830eabf4f 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 a07213030ccf547d9e11a5269d9fa4af5219581f..81a14373d7801159156a06cbb55ac07bef010981 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 cbb75a1818c0076868300ca8ffd203b1960fd654..6b5dc203da2b5ed5bee789520874f1a83179857c 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 ee43ea57d4430ca78b98efa2e7807a3ec4dbaa42..e7d9cbff771bc238dcb5b7023fbfae0368260afb 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 ntuple + +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 + +To add a new filter:: + + # ethtool -U flow-type src-ip [m ] dst-ip + [m ] src-port [m ] dst-port [m ] + action + + Where: + - the Ethernet device to program + - can be ip4, tcp4, udp4, sctp4, ip6, tcp6, udp6, sctp6 + - the IP address to match on + - the IPv4 address to mask on + NOTE: These filters use inverted masks. + - the port number to match on + - the 16-bit integer for masking + NOTE: These filters use inverted masks. + - the queue to direct traffic toward (-1 discards the + matched traffic) + +To delete a filter:: + + # ethtool -U delete + + Where is the filter ID displayed when printing all the active filters, + and may also have been specified using "loc " when adding the filter. + +EXAMPLES: + +To add a filter that directs packet to queue 2:: + + # ethtool -U 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 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 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 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 rx-flow-hash