diff options
Diffstat (limited to 'Documentation')
106 files changed, 3575 insertions, 2610 deletions
diff --git a/Documentation/ABI/stable/sysfs-block b/Documentation/ABI/stable/sysfs-block index 831f19a32e08..cea8856f798d 100644 --- a/Documentation/ABI/stable/sysfs-block +++ b/Documentation/ABI/stable/sysfs-block @@ -21,6 +21,59 @@ Description: device is offset from the internal allocation unit's natural alignment. +What: /sys/block/<disk>/atomic_write_max_bytes +Date: February 2024 +Contact: Himanshu Madhani <himanshu.madhani@oracle.com> +Description: + [RO] This parameter specifies the maximum atomic write + size reported by the device. This parameter is relevant + for merging of writes, where a merged atomic write + operation must not exceed this number of bytes. + This parameter may be greater than the value in + atomic_write_unit_max_bytes as + atomic_write_unit_max_bytes will be rounded down to a + power-of-two and atomic_write_unit_max_bytes may also be + limited by some other queue limits, such as max_segments. + This parameter - along with atomic_write_unit_min_bytes + and atomic_write_unit_max_bytes - will not be larger than + max_hw_sectors_kb, but may be larger than max_sectors_kb. + + +What: /sys/block/<disk>/atomic_write_unit_min_bytes +Date: February 2024 +Contact: Himanshu Madhani <himanshu.madhani@oracle.com> +Description: + [RO] This parameter specifies the smallest block which can + be written atomically with an atomic write operation. All + atomic write operations must begin at a + atomic_write_unit_min boundary and must be multiples of + atomic_write_unit_min. This value must be a power-of-two. + + +What: /sys/block/<disk>/atomic_write_unit_max_bytes +Date: February 2024 +Contact: Himanshu Madhani <himanshu.madhani@oracle.com> +Description: + [RO] This parameter defines the largest block which can be + written atomically with an atomic write operation. This + value must be a multiple of atomic_write_unit_min and must + be a power-of-two. This value will not be larger than + atomic_write_max_bytes. + + +What: /sys/block/<disk>/atomic_write_boundary_bytes +Date: February 2024 +Contact: Himanshu Madhani <himanshu.madhani@oracle.com> +Description: + [RO] A device may need to internally split an atomic write I/O + which straddles a given logical block address boundary. This + parameter specifies the size in bytes of the atomic boundary if + one is reported by the device. This value must be a + power-of-two and at least the size as in + atomic_write_unit_max_bytes. + Any attempt to merge atomic write I/Os must not result in a + merged I/O which crosses this boundary (if any). + What: /sys/block/<disk>/diskseq Date: February 2021 diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index e7e160954e79..53ed1a803422 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -694,3 +694,9 @@ Description: (RO) indicates whether or not the kernel directly supports modifying the crash elfcorehdr for CPU hot un/plug and/or on/offline changes. + +What: /sys/devices/system/cpu/enabled +Date: Nov 2022 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: + (RO) the list of CPUs that can be brought online. diff --git a/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst index 5750f125361b..728b1e690c64 100644 --- a/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst +++ b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst @@ -149,9 +149,9 @@ This case is handled by calls to the strongly ordered ``atomic_add_return()`` read-modify-write atomic operation that is invoked within ``rcu_dynticks_eqs_enter()`` at idle-entry time and within ``rcu_dynticks_eqs_exit()`` at idle-exit time. -The grace-period kthread invokes ``rcu_dynticks_snap()`` and -``rcu_dynticks_in_eqs_since()`` (both of which invoke -an ``atomic_add_return()`` of zero) to detect idle CPUs. +The grace-period kthread invokes first ``ct_dynticks_cpu_acquire()`` +(preceded by a full memory barrier) and ``rcu_dynticks_in_eqs_since()`` +(both of which rely on acquire semantics) to detect idle CPUs. +-----------------------------------------------------------------------+ | **Quick Quiz**: | diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst index cccafdaa1f84..f511476b4550 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.rst +++ b/Documentation/RCU/Design/Requirements/Requirements.rst @@ -2357,6 +2357,7 @@ section. #. `Sched Flavor (Historical)`_ #. `Sleepable RCU`_ #. `Tasks RCU`_ +#. `Tasks Trace RCU`_ Bottom-Half Flavor (Historical) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2610,6 +2611,16 @@ 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 userspace execution also delimit tasks-RCU read-side critical sections. +Idle tasks are ignored by Tasks RCU, and Tasks Rude RCU may be used to +interact with them. + +Note well that involuntary context switches are *not* Tasks-RCU quiescent +states. After all, in preemptible kernels, a task executing code in a +trampoline might be preempted. In this case, the Tasks-RCU grace period +clearly cannot end until that task resumes and its execution leaves that +trampoline. This means, among other things, that cond_resched() does +not provide a Tasks RCU quiescent state. (Instead, use rcu_softirq_qs() +from softirq or rcu_tasks_classic_qs() otherwise.) The tasks-RCU API is quite compact, consisting only of call_rcu_tasks(), synchronize_rcu_tasks(), and @@ -2632,6 +2643,11 @@ moniker. And this operation is considered to be quite rude by real-time workloads that don't want their ``nohz_full`` CPUs receiving IPIs and by battery-powered systems that don't want their idle CPUs to be awakened. +Once kernel entry/exit and deep-idle functions have been properly tagged +``noinstr``, Tasks RCU can start paying attention to idle tasks (except +those that are idle from RCU's perspective) and then Tasks Rude RCU can +be removed from the kernel. + The tasks-rude-RCU API is also reader-marking-free and thus quite compact, consisting of call_rcu_tasks_rude(), synchronize_rcu_tasks_rude(), and rcu_barrier_tasks_rude(). diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst index 94838c65c7d9..d585a5490aee 100644 --- a/Documentation/RCU/whatisRCU.rst +++ b/Documentation/RCU/whatisRCU.rst @@ -250,21 +250,25 @@ rcu_assign_pointer() ^^^^^^^^^^^^^^^^^^^^ void rcu_assign_pointer(p, typeof(p) v); - Yes, rcu_assign_pointer() **is** implemented as a macro, though it - would be cool to be able to declare a function in this manner. - (Compiler experts will no doubt disagree.) + Yes, rcu_assign_pointer() **is** implemented as a macro, though + it would be cool to be able to declare a function in this manner. + (And there has been some discussion of adding overloaded functions + to the C language, so who knows?) The updater uses this spatial macro to assign a new value to an RCU-protected pointer, in order to safely communicate the change in value from the updater to the reader. This is a spatial (as opposed to temporal) macro. It does not evaluate to an rvalue, - but it does execute any memory-barrier instructions required - for a given CPU architecture. Its ordering properties are that - of a store-release operation. - - Perhaps just as important, it serves to document (1) which - pointers are protected by RCU and (2) the point at which a - given structure becomes accessible to other CPUs. That said, + but it does provide any compiler directives and memory-barrier + instructions required for a given compile or CPU architecture. + Its ordering properties are that of a store-release operation, + that is, any prior loads and stores required to initialize the + structure are ordered before the store that publishes the pointer + to that structure. + + Perhaps just as important, rcu_assign_pointer() serves to document + (1) which pointers are protected by RCU and (2) the point at which + a given structure becomes accessible to other CPUs. That said, rcu_assign_pointer() is most frequently used indirectly, via the _rcu list-manipulation primitives such as list_add_rcu(). @@ -283,7 +287,11 @@ rcu_dereference() executes any needed memory-barrier instructions for a given CPU architecture. Currently, only Alpha needs memory barriers within rcu_dereference() -- on other CPUs, it compiles to a - volatile load. + volatile load. However, no mainstream C compilers respect + address dependencies, so rcu_dereference() uses volatile casts, + which, in combination with the coding guidelines listed in + rcu_dereference.rst, prevent current compilers from breaking + these dependencies. Common coding practice uses rcu_dereference() to copy an RCU-protected pointer to a local variable, then dereferences diff --git a/Documentation/admin-guide/cgroup-v1/pids.rst b/Documentation/admin-guide/cgroup-v1/pids.rst index 6acebd9e72c8..0f9f9a7b1f6c 100644 --- a/Documentation/admin-guide/cgroup-v1/pids.rst +++ b/Documentation/admin-guide/cgroup-v1/pids.rst @@ -36,7 +36,8 @@ superset of parent/child/pids.current. The pids.events file contains event counters: - - max: Number of times fork failed because limit was hit. + - max: Number of times fork failed in the cgroup because limit was hit in + self or ancestors. Example ------- diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 8fbb0519d556..05862f06ed26 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -239,6 +239,13 @@ cgroup v2 currently supports the following mount options. will not be tracked by the memory controller (even if cgroup v2 is remounted later on). + pids_localevents + The option restores v1-like behavior of pids.events:max, that is only + local (inside cgroup proper) fork failures are counted. Without this + option pids.events.max represents any pids.max enforcemnt across + cgroup's subtree. + + Organizing Processes and Threads -------------------------------- @@ -2205,12 +2212,18 @@ PID Interface Files descendants has ever reached. pids.events - A read-only flat-keyed file which exists on non-root cgroups. The - following entries are defined. Unless specified otherwise, a value - change in this file generates a file modified event. + A read-only flat-keyed file which exists on non-root cgroups. Unless + specified otherwise, a value change in this file generates a file + modified event. The following entries are defined. max - Number of times fork failed because limit was hit. + The number of times the cgroup's total number of processes hit the pids.max + limit (see also pids_localevents). + + pids.events.local + Similar to pids.events but the fields in the file are local + to the cgroup i.e. not hierarchical. The file modified event + generated on this file reflects only the local events. Organisational operations are not blocked by cgroup policies, so it is possible to have pids.current > pids.max. This can be done by either @@ -2346,8 +2359,12 @@ Cpuset Interface Files is always a subset of it. Users can manually set it to a value that is different from - "cpuset.cpus". The only constraint in setting it is that the - list of CPUs must be exclusive with respect to its sibling. + "cpuset.cpus". One constraint in setting it is that the list of + CPUs must be exclusive with respect to "cpuset.cpus.exclusive" + of its sibling. If "cpuset.cpus.exclusive" of a sibling cgroup + isn't set, its "cpuset.cpus" value, if set, cannot be a subset + of it to leave at least one CPU available when the exclusive + CPUs are taken away. For a parent cgroup, any one of its exclusive CPUs can only be distributed to at most one of its child cgroups. Having an @@ -2363,8 +2380,8 @@ Cpuset Interface Files cpuset-enabled cgroups. This file shows the effective set of exclusive CPUs that - can be used to create a partition root. The content of this - file will always be a subset of "cpuset.cpus" and its parent's + can be used to create a partition root. The content + of this file will always be a subset of its parent's "cpuset.cpus.exclusive.effective" if its parent is not the root cgroup. It will also be a subset of "cpuset.cpus.exclusive" if it is set. If "cpuset.cpus.exclusive" is not set, it is @@ -2625,6 +2642,15 @@ Miscellaneous controller provides 3 interface files. If two misc resources (res_ res_a 3 res_b 0 + misc.peak + A read-only flat-keyed file shown in all cgroups. It shows the + historical maximum usage of the resources in the cgroup and its + children.:: + + $ cat misc.peak + res_a 10 + res_b 8 + misc.max A read-write flat-keyed file shown in the non root cgroups. Allowed maximum usage of the resources in the cgroup and its children.:: @@ -2654,6 +2680,11 @@ Miscellaneous controller provides 3 interface files. If two misc resources (res_ The number of times the cgroup's resource usage was about to go over the max boundary. + misc.events.local + Similar to misc.events but the fields in the file are local to the + cgroup i.e. not hierarchical. The file modified event generated on + this file reflects only the local events. + Migration and Ownership ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/admin-guide/cifs/usage.rst b/Documentation/admin-guide/cifs/usage.rst index aa8290a29dc8..fd4b56c0996f 100644 --- a/Documentation/admin-guide/cifs/usage.rst +++ b/Documentation/admin-guide/cifs/usage.rst @@ -723,40 +723,26 @@ Configuration pseudo-files: ======================= ======================================================= SecurityFlags Flags which control security negotiation and also packet signing. Authentication (may/must) - flags (e.g. for NTLM and/or NTLMv2) may be combined with + flags (e.g. for NTLMv2) may be combined with the signing flags. Specifying two different password hashing mechanisms (as "must use") on the other hand does not make much sense. Default flags are:: - 0x07007 - - (NTLM, NTLMv2 and packet signing allowed). The maximum - allowable flags if you want to allow mounts to servers - using weaker password hashes is 0x37037 (lanman, - plaintext, ntlm, ntlmv2, signing allowed). Some - SecurityFlags require the corresponding menuconfig - options to be enabled. Enabling plaintext - authentication currently requires also enabling - lanman authentication in the security flags - because the cifs module only supports sending - laintext passwords using the older lanman dialect - form of the session setup SMB. (e.g. for authentication - using plain text passwords, set the SecurityFlags - to 0x30030):: + 0x00C5 + + (NTLMv2 and packet signing allowed). Some SecurityFlags + may require enabling a corresponding menuconfig option. may use packet signing 0x00001 must use packet signing 0x01001 - may use NTLM (most common password hash) 0x00002 - must use NTLM 0x02002 may use NTLMv2 0x00004 must use NTLMv2 0x04004 - may use Kerberos security 0x00008 - must use Kerberos 0x08008 - may use lanman (weak) password hash 0x00010 - must use lanman password hash 0x10010 - may use plaintext passwords 0x00020 - must use plaintext passwords 0x20020 - (reserved for future packet encryption) 0x00040 + may use Kerberos security (krb5) 0x00008 + must use Kerberos 0x08008 + may use NTLMSSP 0x00080 + must use NTLMSSP 0x80080 + seal (packet encryption) 0x00040 + must seal (not implemented yet) 0x40040 cifsFYI If set to non-zero value, additional debug information will be logged to the system error log. This field diff --git a/Documentation/admin-guide/gpio/gpio-virtuser.rst b/Documentation/admin-guide/gpio/gpio-virtuser.rst new file mode 100644 index 000000000000..2aca70db9f3b --- /dev/null +++ b/Documentation/admin-guide/gpio/gpio-virtuser.rst @@ -0,0 +1,177 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +Virtual GPIO Consumer +===================== + +The virtual GPIO Consumer module allows users to instantiate virtual devices +that request GPIOs and then control their behavior over debugfs. Virtual +consumer devices can be instantiated from device-tree or over configfs. + +A virtual consumer uses the driver-facing GPIO APIs and allows to cover it with +automated tests driven by user-space. The GPIOs are requested using +``gpiod_get_array()`` and so we support multiple GPIOs per connector ID. + +Creating GPIO consumers +----------------------- + +The gpio-consumer module registers a configfs subsystem called +``'gpio-virtuser'``. For details of the configfs filesystem, please refer to +the configfs documentation. + +The user can create a hierarchy of configfs groups and items as well as modify +values of exposed attributes. Once the consumer is instantiated, this hierarchy +will be translated to appropriate device properties. The general structure is: + +**Group:** ``/config/gpio-virtuser`` + +This is the top directory of the gpio-consumer configfs tree. + +**Group:** ``/config/gpio-consumer/example-name`` + +**Attribute:** ``/config/gpio-consumer/example-name/live`` + +**Attribute:** ``/config/gpio-consumer/example-name/dev_name`` + +This is a directory representing a GPIO consumer device. + +The read-only ``dev_name`` attribute exposes the name of the device as it will +appear in the system on the platform bus. This is useful for locating the +associated debugfs directory under +``/sys/kernel/debug/gpio-virtuser/$dev_name``. + +The ``'live'`` attribute allows to trigger the actual creation of the device +once it's fully configured. The accepted values are: ``'1'`` to enable the +virtual device and ``'0'`` to disable and tear it down. + +Creating GPIO lookup tables +--------------------------- + +Users can create a number of configfs groups under the device group: + +**Group:** ``/config/gpio-consumer/example-name/con_id`` + +The ``'con_id'`` directory represents a single GPIO lookup and its value maps +to the ``'con_id'`` argument of the ``gpiod_get()`` function. For example: +``con_id`` == ``'reset'`` maps to the ``reset-gpios`` device property. + +Users can assign a number of GPIOs to each lookup. Each GPIO is a sub-directory +with a user-defined name under the ``'con_id'`` group. + +**Attribute:** ``/config/gpio-consumer/example-name/con_id/0/key`` + +**Attribute:** ``/config/gpio-consumer/example-name/con_id/0/offset`` + +**Attribute:** ``/config/gpio-consumer/example-name/con_id/0/drive`` + +**Attribute:** ``/config/gpio-consumer/example-name/con_id/0/pull`` + +**Attribute:** ``/config/gpio-consumer/example-name/con_id/0/active_low`` + +**Attribute:** ``/config/gpio-consumer/example-name/con_id/0/transitory`` + +This is a group describing a single GPIO in the ``con_id-gpios`` property. + +For virtual consumers created using configfs we use machine lookup tables so +this group can be considered as a mapping between the filesystem and the fields +of a single entry in ``'struct gpiod_lookup'``. + +The ``'key'`` attribute represents either the name of the chip this GPIO +belongs to or the GPIO line name. This depends on the value of the ``'offset'`` +attribute: if its value is >= 0, then ``'key'`` represents the label of the +chip to lookup while ``'offset'`` represents the offset of the line in that +chip. If ``'offset'`` is < 0, then ``'key'`` represents the name of the line. + +The remaining attributes map to the ``'flags'`` field of the GPIO lookup +struct. The first two take string values as arguments: + +**``'drive'``:** ``'push-pull'``, ``'open-drain'``, ``'open-source'`` +**``'pull'``:** ``'pull-up'``, ``'pull-down'``, ``'pull-disabled'``, ``'as-is'`` + +``'active_low'`` and ``'transitory'`` are boolean attributes. + +Activating GPIO consumers +------------------------- + +Once the confiuration is complete, the ``'live'`` attribute must be set to 1 in +order to instantiate the consumer. It can be set back to 0 to destroy the +virtual device. The module will synchronously wait for the new simulated device +to be successfully probed and if this doesn't happen, writing to ``'live'`` will +result in an error. + +Device-tree +----------- + +Virtual GPIO consumers can also be defined in device-tree. The compatible string +must be: ``"gpio-virtuser"`` with at least one property following the +standardized GPIO pattern. + +An example device-tree code defining a virtual GPIO consumer: + +.. code-block :: none + + gpio-virt-consumer { + compatible = "gpio-virtuser"; + + foo-gpios = <&gpio0 5 GPIO_ACTIVE_LOW>, <&gpio1 2 0>; + bar-gpios = <&gpio0 6 0>; + }; + +Controlling virtual GPIO consumers +---------------------------------- + +Once active, the device will export debugfs attributes for controlling GPIO +arrays as well as each requested GPIO line separately. Let's consider the +following device property: ``foo-gpios = <&gpio0 0 0>, <&gpio0 4 0>;``. + +The following debugfs attribute groups will be created: + +**Group:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo/`` + +This is the group that will contain the attributes for the entire GPIO array. + +**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo/values`` + +**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo/values_atomic`` + +Both attributes allow to read and set arrays of GPIO values. User must pass +exactly the number of values that the array contains in the form of a string +containing zeroes and ones representing inactive and active GPIO states +respectively. In this example: ``echo 11 > values``. + +The ``values_atomic`` attribute works the same as ``values`` but the kernel +will execute the GPIO driver callbacks in interrupt context. + +**Group:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/`` + +This is a group that represents a single GPIO with ``$index`` being its offset +in the array. + +**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/consumer`` + +Allows to set and read the consumer label of the GPIO line. + +**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/debounce`` + +Allows to set and read the debounce period of the GPIO line. + +**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/direction`` + +**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/direction_atomic`` + +These two attributes allow to set the direction of the GPIO line. They accept +"input" and "output" as values. The atomic variant executes the driver callback +in interrupt context. + +**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/interrupts`` + +If the line is requested in input mode, writing ``1`` to this attribute will +make the module listen for edge interrupts on the GPIO. Writing ``0`` disables +the monitoring. Reading this attribute returns the current number of registered +interrupts (both edges). + +**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/value`` + +**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/value_atomic`` + +Both attributes allow to read and set values of individual requested GPIO lines. +They accept the following values: ``1`` and ``0``. diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst index 460afd29617e..712f379731cb 100644 --- a/Documentation/admin-guide/gpio/index.rst +++ b/Documentation/admin-guide/gpio/index.rst @@ -10,6 +10,7 @@ GPIO Character Device Userspace API <../../userspace-api/gpio/chardev> gpio-aggregator gpio-sim + gpio-virtuser Obsolete APIs <obsolete> .. only:: subproject and html diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 11e57ba2985c..ee9f203438d9 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -12,7 +12,7 @@ acpi= [HW,ACPI,X86,ARM64,RISCV64,EARLY] Advanced Configuration and Power Interface Format: { force | on | off | strict | noirq | rsdt | - copy_dsdt } + copy_dsdt | nospcr } force -- enable ACPI if default was off on -- enable ACPI but allow fallback to DT [arm64,riscv64] off -- disable ACPI if default was on @@ -21,8 +21,12 @@ strictly ACPI specification compliant. rsdt -- prefer RSDT over (default) XSDT copy_dsdt -- copy DSDT to memory - For ARM64 and RISCV64, ONLY "acpi=off", "acpi=on" or - "acpi=force" are available + nospcr -- disable console in ACPI SPCR table as + default _serial_ console on ARM64 + For ARM64, ONLY "acpi=off", "acpi=on", "acpi=force" or + "acpi=nospcr" are available + For RISCV64, ONLY "acpi=off", "acpi=on" or "acpi=force" + are available See also Documentation/power/runtime_pm.rst, pci=noacpi @@ -788,25 +792,6 @@ Documentation/networking/netconsole.rst for an alternative. - <DEVNAME>:<n>.<n>[,options] - Use the specified serial port on the serial core bus. - The addressing uses DEVNAME of the physical serial port - device, followed by the serial core controller instance, - and the serial port instance. The options are the same - as documented for the ttyS addressing above. - - The mapping of the serial ports to the tty instances - can be viewed with: - - $ ls -d /sys/bus/serial-base/devices/*:*.*/tty/* - /sys/bus/serial-base/devices/00:04:0.0/tty/ttyS0 - - In the above example, the console can be addressed with - console=00:04:0.0. Note that a console addressed this - way will only get added when the related device driver - is ready. The use of an earlycon parameter in addition to - the console may be desired for console output early on. - uart[8250],io,<addr>[,options] uart[8250],mmio,<addr>[,options] uart[8250],mmio16,<addr>[,options] @@ -5034,6 +5019,14 @@ the ->nocb_bypass queue. The definition of "too many" is supplied by this kernel boot parameter. + rcutree.nohz_full_patience_delay= [KNL] + On callback-offloaded (rcu_nocbs) CPUs, avoid + disturbing RCU unless the grace period has + reached the specified age in milliseconds. + Defaults to zero. Large values will be capped + at five seconds. All values will be rounded down + to the nearest value representable by jiffies. + rcutree.qhimark= [KNL] Set threshold of queued RCU callbacks beyond which batch limiting is disabled. diff --git a/Documentation/arch/arm64/cpu-hotplug.rst b/Documentation/arch/arm64/cpu-hotplug.rst new file mode 100644 index 000000000000..76ba8d932c72 --- /dev/null +++ b/Documentation/arch/arm64/cpu-hotplug.rst @@ -0,0 +1,79 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. _cpuhp_index: + +==================== +CPU Hotplug and ACPI +==================== + +CPU hotplug in the arm64 world is commonly used to describe the kernel taking +CPUs online/offline using PSCI. This document is about ACPI firmware allowing +CPUs that were not available during boot to be added to the system later. + +``possible`` and ``present`` refer to the state of the CPU as seen by linux. + + +CPU Hotplug on physical systems - CPUs not present at boot +---------------------------------------------------------- + +Physical systems need to mark a CPU that is ``possible`` but not ``present`` as +being ``present``. An example would be a dual socket machine, where the package +in one of the sockets can be replaced while the system is running. + +This is not supported. + +In the arm64 world CPUs are not a single device but a slice of the system. +There are no systems that support the physical addition (or removal) of CPUs +while the system is running, and ACPI is not able to sufficiently describe +them. + +e.g. New CPUs come with new caches, but the platform's cache toplogy is +described in a static table, the PPTT. How caches are shared between CPUs is +not discoverable, and must be described by firmware. + +e.g. The GIC redistributor for each CPU must be accessed by the driver during +boot to discover the system wide supported features. ACPI's MADT GICC +structures can describe a redistributor associated with a disabled CPU, but +can't describe whether the redistributor is accessible, only that it is not +'always on'. + +arm64's ACPI tables assume that everything described is ``present``. + + +CPU Hotplug on virtual systems - CPUs not enabled at boot +--------------------------------------------------------- + +Virtual systems have the advantage that all the properties the system will +ever have can be described at boot. There are no power-domain considerations +as such devices are emulated. + +CPU Hotplug on virtual systems is supported. It is distinct from physical +CPU Hotplug as all resources are described as ``present``, but CPUs may be +marked as disabled by firmware. Only the CPU's online/offline behaviour is +influenced by firmware. An example is where a virtual machine boots with a +single CPU, and additional CPUs are added once a cloud orchestrator deploys +the workload. + +For a virtual machine, the VMM (e.g. Qemu) plays the part of firmware. + +Virtual hotplug is implemented as a firmware policy affecting which CPUs can be +brought online. Firmware can enforce its policy via PSCI's return codes. e.g. +``DENIED``. + +The ACPI tables must describe all the resources of the virtual machine. CPUs +that firmware wishes to disable either from boot (or later) should not be +``enabled`` in the MADT GICC structures, but should have the ``online capable`` +bit set, to indicate they can be enabled later. The boot CPU must be marked as +``enabled``. The 'always on' GICR structure must be used to describe the +redistributors. + +CPUs described as ``online capable`` but not ``enabled`` can be set to enabled +by the DSDT's Processor object's _STA method. On virtual systems the _STA method +must always report the CPU as ``present``. Changes to the firmware policy can +be notified to the OS via device-check or eject-request. + +CPUs described as ``enabled`` in the static table, should not have their _STA +modified dynamically by firmware. Soft-restart features such as kexec will +re-read the static properties of the system from these static tables, and +may malfunction if these no longer describe the running system. Linux will +re-discover the dynamic properties of the system from the _STA method later +during boot. diff --git a/Documentation/arch/arm64/index.rst b/Documentation/arch/arm64/index.rst index d08e924204bf..78544de0a8a9 100644 --- a/Documentation/arch/arm64/index.rst +++ b/Documentation/arch/arm64/index.rst @@ -13,6 +13,7 @@ ARM64 Architecture asymmetric-32bit booting cpu-feature-registers + cpu-hotplug elf_hwcaps hugetlbpage kdump diff --git a/Documentation/arch/arm64/memory.rst b/Documentation/arch/arm64/memory.rst index 55a55f30eed8..8a658984b8bb 100644 --- a/Documentation/arch/arm64/memory.rst +++ b/Documentation/arch/arm64/memory.rst @@ -18,12 +18,10 @@ ARMv8.2 adds optional support for Large Virtual Address space. This is only available when running with a 64KB page size and expands the number of descriptors in the first level of translation. -User addresses have bits 63:48 set to 0 while the kernel addresses have -the same bits set to 1. TTBRx selection is given by bit 63 of the -virtual address. The swapper_pg_dir contains only kernel (global) -mappings while the user pgd contains only user (non-global) mappings. -The swapper_pg_dir address is written to TTBR1 and never written to -TTBR0. +TTBRx selection is given by bit 55 of the virtual address. The +swapper_pg_dir contains only kernel (global) mappings while the user pgd +contains only user (non-global) mappings. The swapper_pg_dir address is +written to TTBR1 and never written to TTBR0. AArch64 Linux memory layout with 4KB pages + 4 levels (48-bit):: @@ -65,14 +63,14 @@ Translation table lookup with 4KB pages:: +--------+--------+--------+--------+--------+--------+--------+--------+ |63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0| +--------+--------+--------+--------+--------+--------+--------+--------+ - | | | | | | - | | | | | v - | | | | | [11:0] in-page offset - | | | | +-> [20:12] L3 index - | | | +-----------> [29:21] L2 index - | | +---------------------> [38:30] L1 index - | +-------------------------------> [47:39] L0 index - +-------------------------------------------------> [63] TTBR0/1 + | | | | | | + | | | | | v + | | | | | [11:0] in-page offset + | | | | +-> [20:12] L3 index + | | | +-----------> [29:21] L2 index + | | +---------------------> [38:30] L1 index + | +-------------------------------> [47:39] L0 index + +----------------------------------------> [55] TTBR0/1 Translation table lookup with 64KB pages:: @@ -80,14 +78,14 @@ Translation table lookup with 64KB pages:: +--------+--------+--------+--------+--------+--------+--------+--------+ |63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0| +--------+--------+--------+--------+--------+--------+--------+--------+ - | | | | | - | | | | v - | | | | [15:0] in-page offset - | | | +----------> [28:16] L3 index - | | +--------------------------> [41:29] L2 index - | +-------------------------------> [47:42] L1 index (48-bit) - | [51:42] L1 index (52-bit) - +-------------------------------------------------> [63] TTBR0/1 + | | | | | + | | | | v + | | | | [15:0] in-page offset + | | | +----------> [28:16] L3 index + | | +--------------------------> [41:29] L2 index + | +-------------------------------> [47:42] L1 index (48-bit) + | [51:42] L1 index (52-bit) + +----------------------------------------> [55] TTBR0/1 When using KVM without the Virtualization Host Extensions, the diff --git a/Documentation/arch/arm64/silicon-errata.rst b/Documentation/arch/arm64/silicon-errata.rst index eb8af8032c31..bb83c5d8c675 100644 --- a/Documentation/arch/arm64/silicon-errata.rst +++ b/Documentation/arch/arm64/silicon-errata.rst @@ -132,16 +132,26 @@ stable kernels. +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A710 | #2224489 | ARM64_ERRATUM_2224489 | +----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A710 | #3324338 | ARM64_ERRATUM_3194386 | ++----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A715 | #2645198 | ARM64_ERRATUM_2645198 | +----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A720 | #3456091 | ARM64_ERRATUM_3194386 | ++----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-X1 | #1502854 | N/A | +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-X2 | #2119858 | ARM64_ERRATUM_2119858 | +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-X2 | #2224489 | ARM64_ERRATUM_2224489 | +----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-X2 | #3324338 | ARM64_ERRATUM_3194386 | ++----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-X3 | #3324335 | ARM64_ERRATUM_3194386 | ++----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-X4 | #3194386 | ARM64_ERRATUM_3194386 | +----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-X925 | #3324334 | ARM64_ERRATUM_3194386 | ++----------------+-----------------+-----------------+-----------------------------+ | ARM | Neoverse-N1 | #1188873,1418040| ARM64_ERRATUM_1418040 | +----------------+-----------------+-----------------+-----------------------------+ | ARM | Neoverse-N1 | #1349291 | N/A | @@ -156,9 +166,13 @@ stable kernels. +----------------+-----------------+-----------------+-----------------------------+ | ARM | Neoverse-N2 | #2253138 | ARM64_ERRATUM_2253138 | +----------------+-----------------+-----------------+-----------------------------+ +| ARM | Neoverse-N2 | #3324339 | ARM64_ERRATUM_3194386 | ++----------------+-----------------+-----------------+-----------------------------+ | ARM | Neoverse-V1 | #1619801 | N/A | +----------------+-----------------+-----------------+-----------------------------+ -| ARM | Neoverse-V3 | #3312417 | ARM64_ERRATUM_3312417 | +| ARM | Neoverse-V2 | #3324336 | ARM64_ERRATUM_3194386 | ++----------------+-----------------+-----------------+-----------------------------+ +| ARM | Neoverse-V3 | #3312417 | ARM64_ERRATUM_3194386 | +----------------+-----------------+-----------------+-----------------------------+ | ARM | MMU-500 | #841119,826419 | N/A | +----------------+-----------------+-----------------+-----------------------------+ diff --git a/Documentation/arch/riscv/cmodx.rst b/Documentation/arch/riscv/cmodx.rst index 1c0ca06b6c97..8c48bcff3df9 100644 --- a/Documentation/arch/riscv/cmodx.rst +++ b/Documentation/arch/riscv/cmodx.rst @@ -62,10 +62,10 @@ cmodx.c:: printf("Value before cmodx: %d\n", value); // Call prctl before first fence.i is called inside modify_instruction - prctl(PR_RISCV_SET_ICACHE_FLUSH_CTX_ON, PR_RISCV_CTX_SW_FENCEI, PR_RISCV_SCOPE_PER_PROCESS); + prctl(PR_RISCV_SET_ICACHE_FLUSH_CTX, PR_RISCV_CTX_SW_FENCEI_ON, PR_RISCV_SCOPE_PER_PROCESS); modify_instruction(); // Call prctl after final fence.i is called in process - prctl(PR_RISCV_SET_ICACHE_FLUSH_CTX_OFF, PR_RISCV_CTX_SW_FENCEI, PR_RISCV_SCOPE_PER_PROCESS); + prctl(PR_RISCV_SET_ICACHE_FLUSH_CTX, PR_RISCV_CTX_SW_FENCEI_OFF, PR_RISCV_SCOPE_PER_PROCESS); value = get_value(); printf("Value after cmodx: %d\n", value); diff --git a/Documentation/block/data-integrity.rst b/Documentation/block/data-integrity.rst index 6a760c0eb192..99905e880a0e 100644 --- a/Documentation/block/data-integrity.rst +++ b/Documentation/block/data-integrity.rst @@ -153,18 +153,11 @@ bio_free() will automatically free the bip. 4.2 Block Device ---------------- -Because the format of the protection data is tied to the physical -disk, each block device has been extended with a block integrity -profile (struct blk_integrity). This optional profile is registered -with the block layer using blk_integrity_register(). - -The profile contains callback functions for generating and verifying -the protection data, as well as getting and setting application tags. -The profile also contains a few constants to aid in completing, -merging and splitting the integrity metadata. +Block devices can set up the integrity information in the integrity +sub-struture of the queue_limits structure. Layered block devices will need to pick a profile that's appropriate -for all subdevices. blk_integrity_compare() can help with that. DM +for all subdevices. queue_limits_stack_integrity() can help with that. DM and MD linear, RAID0 and RAID1 are currently supported. RAID4/5/6 will require extra work due to the application tag. @@ -250,42 +243,6 @@ will require extra work due to the application tag. integrity upon completion. -5.4 Registering A Block Device As Capable Of Exchanging Integrity Metadata --------------------------------------------------------------------------- - - To enable integrity exchange on a block device the gendisk must be - registered as capable: - - `int blk_integrity_register(gendisk, blk_integrity);` - - The blk_integrity struct is a template and should contain the - following:: - - static struct blk_integrity my_profile = { - .name = "STANDARDSBODY-TYPE-VARIANT-CSUM", - .generate_fn = my_generate_fn, - .verify_fn = my_verify_fn, - .tuple_size = sizeof(struct my_tuple_size), - .tag_size = <tag bytes per hw sector>, - }; - - 'name' is a text string which will be visible in sysfs. This is - part of the userland API so chose it carefully and never change - it. The format is standards body-type-variant. - E.g. T10-DIF-TYPE1-IP or T13-EPP-0-CRC. - - 'generate_fn' generates appropriate integrity metadata (for WRITE). - - 'verify_fn' verifies that the data buffer matches the integrity - metadata. - - 'tuple_size' must be set to match the size of the integrity - metadata per sector. I.e. 8 for DIF and EPP. - - 'tag_size' must be set to identify how many bytes of tag space - are available per hardware sector. For DIF this is either 2 or - 0 depending on the value of the Control Mode Page ATO bit. - ---------------------------------------------------------------------- 2007-12-24 Martin K. Petersen <martin.petersen@oracle.com> diff --git a/Documentation/block/writeback_cache_control.rst b/Documentation/block/writeback_cache_control.rst index b208488d0aae..c3707d071780 100644 --- a/Documentation/block/writeback_cache_control.rst +++ b/Documentation/block/writeback_cache_control.rst @@ -46,41 +46,50 @@ worry if the underlying devices need any explicit cache flushing and how the Forced Unit Access is implemented. The REQ_PREFLUSH and REQ_FUA flags may both be set on a single bio. +Feature settings for block drivers +---------------------------------- -Implementation details for bio based block drivers --------------------------------------------------------------- +For devices that do not support volatile write caches there is no driver +support required, the block layer completes empty REQ_PREFLUSH requests before +entering the driver and strips off the REQ_PREFLUSH and REQ_FUA bits from +requests that have a payload. -These drivers will always see the REQ_PREFLUSH and REQ_FUA bits as they sit -directly below the submit_bio interface. For remapping drivers the REQ_FUA -bits need to be propagated to underlying devices, and a global flush needs -to be implemented for bios with the REQ_PREFLUSH bit set. For real device -drivers that do not have a volatile cache the REQ_PREFLUSH and REQ_FUA bits -on non-empty bios can simply be ignored, and REQ_PREFLUSH requests without -data can be completed successfully without doing any work. Drivers for -devices with volatile caches need to implement the support for these -flags themselves without any help from the block layer. +For devices with volatile write caches the driver needs to tell the block layer +that it supports flushing caches by setting the + BLK_FEAT_WRITE_CACHE -Implementation details for request_fn based block drivers ---------------------------------------------------------- +flag in the queue_limits feature field. For devices that also support the FUA +bit the block layer needs to be told to pass on the REQ_FUA bit by also setting +the -For devices that do not support volatile write caches there is no driver -support required, the block layer completes empty REQ_PREFLUSH requests before -entering the driver and strips off the REQ_PREFLUSH and REQ_FUA bits from -requests that have a payload. For devices with volatile write caches the -driver needs to tell the block layer that it supports flushing caches by -doing:: + BLK_FEAT_FUA + +flag in the features field of the queue_limits structure. + +Implementation details for bio based block drivers +-------------------------------------------------- + +For bio based drivers the REQ_PREFLUSH and REQ_FUA bit are simply passed on to +the driver if the driver sets the BLK_FEAT_WRITE_CACHE flag and the driver +needs to handle them. + +*NOTE*: The REQ_FUA bit also gets passed on when the BLK_FEAT_FUA flags is +_not_ set. Any bio based driver that sets BLK_FEAT_WRITE_CACHE also needs to +handle REQ_FUA. - blk_queue_write_cache(sdkp->disk->queue, true, false); +For remapping drivers the REQ_FUA bits need to be propagated to underlying +devices, and a global flush needs to be implemented for bios with the +REQ_PREFLUSH bit set. -and handle empty REQ_OP_FLUSH requests in its prep_fn/request_fn. Note that -REQ_PREFLUSH requests with a payload are automatically turned into a sequence -of an empty REQ_OP_FLUSH request followed by the actual write by the block -layer. For devices that also support the FUA bit the block layer needs -to be told to pass through the REQ_FUA bit using:: +Implementation details for blk-mq drivers +----------------------------------------- - blk_queue_write_cache(sdkp->disk->queue, true, true); +When the BLK_FEAT_WRITE_CACHE flag is set, REQ_OP_WRITE | REQ_PREFLUSH requests +with a payload are automatically turned into a sequence of a REQ_OP_FLUSH +request followed by the actual write by the block layer. -and the driver must handle write requests that have the REQ_FUA bit set -in prep_fn/request_fn. If the FUA bit is not natively supported the block -layer turns it into an empty REQ_OP_FLUSH request after the actual write. +When the BLK_FEAT_FUA flags is set, the REQ_FUA bit is simply passed on for the +REQ_OP_WRITE request, else a REQ_OP_FLUSH request is sent by the block layer +after the completion of the write request for bio submissions with the REQ_FUA +bit set. diff --git a/Documentation/dev-tools/gpio-sloppy-logic-analyzer.rst b/Documentation/dev-tools/gpio-sloppy-logic-analyzer.rst new file mode 100644 index 000000000000..d69f24c0d9e1 --- /dev/null +++ b/Documentation/dev-tools/gpio-sloppy-logic-analyzer.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================= +Linux Kernel GPIO based sloppy logic analyzer +============================================= + +:Author: Wolfram Sang + +Introduction +============ + +This document briefly describes how to run the GPIO based in-kernel sloppy +logic analyzer running on an isolated CPU. + +The sloppy logic analyzer will utilize a few GPIO lines in input mode on a +system to rapidly sample these digital lines, which will, if the Nyquist +criteria is met, result in a time series log with approximate waveforms as they +appeared on these lines. One way to use it is to analyze external traffic +connected to these GPIO lines with wires (i.e. digital probes), acting as a +common logic analyzer. + +Another feature is to snoop on on-chip peripherals if the I/O cells of these +peripherals can be used in GPIO input mode at the same time as they are being +used as inputs or outputs for the peripheral. That means you could e.g. snoop +I2C traffic without any wiring (if your hardware supports it). In the pin +control subsystem such pin controllers are called "non-strict": a certain pin +can be used with a certain peripheral and as a GPIO input line at the same +time. + +Note that this is a last resort analyzer which can be affected by latencies, +non-deterministic code paths and non-maskable interrupts. It is called 'sloppy' +for a reason. However, for e.g. remote development, it may be useful to get a +first view and aid further debugging. + +Setup +===== + +Your kernel must have CONFIG_DEBUG_FS and CONFIG_CPUSETS enabled. Ideally, your +runtime environment does not utilize cpusets otherwise, then isolation of a CPU +core is easiest. If you do need cpusets, check that helper script for the +sloppy logic analyzer does not interfere with your other settings. + +Tell the kernel which GPIOs are used as probes. For a Device Tree based system, +you need to use the following bindings. Because these bindings are only for +debugging, there is no official schema:: + + i2c-analyzer { + compatible = "gpio-sloppy-logic-analyzer"; + probe-gpios = <&gpio6 21 GPIO_OPEN_DRAIN>, <&gpio6 4 GPIO_OPEN_DRAIN>; + probe-names = "SCL", "SDA"; + }; + +Note that you must provide a name for every GPIO specified. Currently a +maximum of 8 probes are supported. 32 are likely possible but are not +implemented yet. + +Usage +===== + +The logic analyzer is configurable via files in debugfs. However, it is +strongly recommended to not use them directly, but to use the script +``tools/gpio/gpio-sloppy-logic-analyzer``. Besides checking parameters more +extensively, it will isolate the CPU core so you will have the least +disturbance while measuring. + +The script has a help option explaining the parameters. For the above DT +snippet which analyzes an I2C bus at 400kHz on a Renesas Salvator-XS board, the +following settings are used: The isolated CPU shall be CPU1 because it is a big +core in a big.LITTLE setup. Because CPU1 is the default, we don't need a +parameter. The bus speed is 400kHz. So, the sampling theorem says we need to +sample at least at 800kHz. However, falling edges of both signals in an I2C +start condition happen faster, so we need a higher sampling frequency, e.g. +``-s 1500000`` for 1.5MHz. Also, we don't want to sample right away but wait +for a start condition on an idle bus. So, we need to set a trigger to a falling +edge on SDA while SCL stays high, i.e. ``-t 1H+2F``. Last is the duration, let +us assume 15ms here which results in the parameter ``-d 15000``. So, +altogether:: + + gpio-sloppy-logic-analyzer -s 1500000 -t 1H+2F -d 15000 + +Note that the process will return you back to the prompt but a sub-process is +still sampling in the background. Unless this has finished, you will not find a +result file in the current or specified directory. For the above example, we +will then need to trigger I2C communication:: + + i2cdetect -y -r <your bus number> + +Result is a .sr file to be consumed with PulseView or sigrok-cli from the free +`sigrok`_ project. It is a zip file which also contains the binary sample data +which may be consumed by other software. The filename is the logic analyzer +instance name plus a since-epoch timestamp. + +.. _sigrok: https://sigrok.org/ diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index efa49cdc8e2e..6971ed581c08 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -32,6 +32,7 @@ Documentation/dev-tools/testing-overview.rst kunit/index ktap checkuapi + gpio-sloppy-logic-analyzer .. only:: subproject and html diff --git a/Documentation/devicetree/bindings/arm/bcm/bcm2835.yaml b/Documentation/devicetree/bindings/arm/bcm/bcm2835.yaml index 162a39dab218..e4ff71f006b8 100644 --- a/Documentation/devicetree/bindings/arm/bcm/bcm2835.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/bcm2835.yaml @@ -23,6 +23,12 @@ properties: - raspberrypi,4-model-b - const: brcm,bcm2711 + - description: BCM2712 based Boards + items: + - enum: + - raspberrypi,5-model-b + - const: brcm,bcm2712 + - description: BCM2835 based Boards items: - enum: diff --git a/Documentation/devicetree/bindings/arm/pmu.yaml b/Documentation/devicetree/bindings/arm/pmu.yaml index 99b5e9530707..528544d0a161 100644 --- a/Documentation/devicetree/bindings/arm/pmu.yaml +++ b/Documentation/devicetree/bindings/arm/pmu.yaml @@ -53,14 +53,20 @@ properties: - arm,cortex-a710-pmu - arm,cortex-a715-pmu - arm,cortex-a720-pmu + - arm,cortex-a725-pmu - arm,cortex-x1-pmu - arm,cortex-x2-pmu - arm,cortex-x3-pmu - arm,cortex-x4-pmu + - arm,cortex-x925-pmu - arm,neoverse-e1-pmu - arm,neoverse-n1-pmu - arm,neoverse-n2-pmu + - arm,neoverse-n3-pmu - arm,neoverse-v1-pmu + - arm,neoverse-v2-pmu + - arm,neoverse-v3-pmu + - arm,neoverse-v3ae-pmu - brcm,vulcan-pmu - cavium,thunder-pmu - nvidia,denver-pmu diff --git a/Documentation/devicetree/bindings/cache/qcom,llcc.yaml b/Documentation/devicetree/bindings/cache/qcom,llcc.yaml index 07ccbda4a0ab..b9a9f2cf32a1 100644 --- a/Documentation/devicetree/bindings/cache/qcom,llcc.yaml +++ b/Documentation/devicetree/bindings/cache/qcom,llcc.yaml @@ -66,7 +66,6 @@ allOf: compatible: contains: enum: - - qcom,qdu1000-llcc - qcom,sc7180-llcc - qcom,sm6350-llcc then: @@ -104,6 +103,7 @@ allOf: compatible: contains: enum: + - qcom,qdu1000-llcc - qcom,sc8180x-llcc - qcom,sc8280xp-llcc - qcom,x1e80100-llcc diff --git a/Documentation/devicetree/bindings/gpio/aspeed,sgpio.yaml b/Documentation/devicetree/bindings/gpio/aspeed,sgpio.yaml index 46bb121360dc..1046f0331c09 100644 --- a/Documentation/devicetree/bindings/gpio/aspeed,sgpio.yaml +++ b/Documentation/devicetree/bindings/gpio/aspeed,sgpio.yaml @@ -33,6 +33,11 @@ properties: gpio-controller: true + # Each SGPIO is represented as a pair of input and output GPIOs + gpio-line-names: + minItems: 160 + maxItems: 256 + '#gpio-cells': const: 2 @@ -41,6 +46,9 @@ properties: interrupt-controller: true + '#interrupt-cells': + const: 2 + clocks: maxItems: 1 @@ -55,6 +63,7 @@ required: - '#gpio-cells' - interrupts - interrupt-controller + - '#interrupt-cells' - ngpios - clocks - bus-frequency @@ -72,6 +81,7 @@ examples: reg = <0x1e780200 0x0100>; clocks = <&syscon ASPEED_CLK_APB>; interrupt-controller; + #interrupt-cells = <2>; ngpios = <80>; bus-frequency = <12000000>; }; diff --git a/Documentation/devicetree/bindings/gpio/atmel,at91rm9200-gpio.yaml b/Documentation/devicetree/bindings/gpio/atmel,at91rm9200-gpio.yaml new file mode 100644 index 000000000000..3dd70933ed8e --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/atmel,at91rm9200-gpio.yaml @@ -0,0 +1,81 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/atmel,at91rm9200-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip GPIO controller (PIO) + +maintainers: + - Manikandan Muralidharan <manikandan.m@microchip.com> + +properties: + compatible: + oneOf: + - items: + - enum: + - atmel,at91sam9x5-gpio + - microchip,sam9x60-gpio + - const: atmel,at91rm9200-gpio + - items: + - enum: + - microchip,sam9x7-gpio + - const: microchip,sam9x60-gpio + - const: atmel,at91rm9200-gpio + - items: + - const: atmel,at91rm9200-gpio + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + "#interrupt-cells": + const: 2 + + gpio-controller: true + gpio-line-names: true + + "#gpio-cells": + const: 2 + + clocks: + maxItems: 1 + + "#gpio-lines": + description: + Number of gpio, 32 by default if absent + maxItems: 1 + default: 32 + +required: + - compatible + - reg + - interrupts + - interrupt-controller + - "#interrupt-cells" + - gpio-controller + - "#gpio-cells" + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/at91.h> + #include <dt-bindings/interrupt-controller/irq.h> + + gpio@fffff400 { + compatible = "atmel,at91rm9200-gpio"; + reg = <0xfffff400 0x200>; + interrupts = <2 IRQ_TYPE_LEVEL_HIGH 1>; + #gpio-cells = <2>; + gpio-controller; + interrupt-controller; + #interrupt-cells = <2>; + clocks = <&pmc PMC_TYPE_PERIPHERAL 2>; + }; +... diff --git a/Documentation/devicetree/bindings/gpio/fsl,qoriq-gpio.yaml b/Documentation/devicetree/bindings/gpio/fsl,qoriq-gpio.yaml new file mode 100644 index 000000000000..84fd82291ee4 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/fsl,qoriq-gpio.yaml @@ -0,0 +1,87 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/fsl,qoriq-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale MPC512x/MPC8xxx/QorIQ/Layerscape GPIO controller + +maintainers: + - Frank Li <Frank.Li@nxp.com> + +properties: + compatible: + oneOf: + - enum: + - fsl,mpc5121-gpio + - fsl,mpc5125-gpio + - fsl,mpc8349-gpio + - fsl,mpc8572-gpio + - fsl,mpc8610-gpio + - fsl,pq3-gpio + - items: + - enum: + - fsl,ls1021a-gpio + - fsl,ls1028a-gpio + - fsl,ls1043a-gpio + - fsl,ls1046a-gpio + - fsl,ls1088a-gpio + - fsl,ls2080a-gpio + - const: fsl,qoriq-gpio + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + "#gpio-cells": + const: 2 + + gpio-controller: true + + interrupt-controller: true + + "#interrupt-cells": + const: 2 + + gpio-line-names: + minItems: 1 + maxItems: 32 + + little-endian: + $ref: /schemas/types.yaml#/definitions/flag + description: + GPIO registers are used as little endian. If not + present registers are used as big endian by default. + +required: + - compatible + - reg + - interrupts + - "#gpio-cells" + +additionalProperties: false + +examples: + - | + gpio@1100 { + compatible = "fsl,mpc5125-gpio"; + reg = <0x1100 0x080>; + interrupts = <78 0x8>; + gpio-controller; + #gpio-cells = <2>; + }; + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + gpio@2300000 { + compatible = "fsl,ls2080a-gpio", "fsl,qoriq-gpio"; + reg = <0x2300000 0x10000>; + interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>; + little-endian; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt b/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt deleted file mode 100644 index cd28e932bf50..000000000000 --- a/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt +++ /dev/null @@ -1,53 +0,0 @@ -* Freescale MPC512x/MPC8xxx/QorIQ/Layerscape GPIO controller - -Required properties: -- compatible : Should be "fsl,<soc>-gpio" - The following <soc>s are known to be supported: - mpc5121, mpc5125, mpc8349, mpc8572, mpc8610, pq3, qoriq, - ls1021a, ls1043a, ls2080a, ls1028a, ls1088a. -- reg : Address and length of the register set for the device -- interrupts : Should be the port interrupt shared by all 32 pins. -- #gpio-cells : Should be two. The first cell is the pin number and - the second cell is used to specify the gpio polarity: - 0 = active high - 1 = active low - -Optional properties: -- little-endian : GPIO registers are used as little endian. If not - present registers are used as big endian by default. - -Example of gpio-controller node for a mpc5125 SoC: - -gpio0: gpio@1100 { - compatible = "fsl,mpc5125-gpio"; - #gpio-cells = <2>; - reg = <0x1100 0x080>; - interrupts = <78 0x8>; -}; - -Example of gpio-controller node for a ls2080a SoC: - -gpio0: gpio@2300000 { - compatible = "fsl,ls2080a-gpio", "fsl,qoriq-gpio"; - reg = <0x0 0x2300000 0x0 0x10000>; - interrupts = <0 36 0x4>; /* Level high type */ - gpio-controller; - little-endian; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; -}; - - -Example of gpio-controller node for a ls1028a/ls1088a SoC: - -gpio1: gpio@2300000 { - compatible = "fsl,ls1028a-gpio", "fsl,ls1088a-gpio", "fsl,qoriq-gpio"; - reg = <0x0 0x2300000 0x0 0x10000>; - interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; - little-endian; -}; diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml b/Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml index 99febb8ea1b6..51e8390d6b32 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml +++ b/Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml @@ -66,6 +66,7 @@ properties: - ti,tca6408 - ti,tca6416 - ti,tca6424 + - ti,tca9535 - ti,tca9538 - ti,tca9539 - ti,tca9554 diff --git a/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml b/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml index a27f92950257..cabda2eab4a2 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml +++ b/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml @@ -51,6 +51,10 @@ properties: gpio-controller: true + gpio-line-names: + minItems: 1 + maxItems: 32 + clocks: items: - description: SoC GPIO clock diff --git a/Documentation/devicetree/bindings/gpio/gpio-zevio.txt b/Documentation/devicetree/bindings/gpio/gpio-zevio.txt deleted file mode 100644 index a37bd9ae2730..000000000000 --- a/Documentation/devicetree/bindings/gpio/gpio-zevio.txt +++ /dev/null @@ -1,16 +0,0 @@ -Zevio GPIO controller - -Required properties: -- compatible: Should be "lsi,zevio-gpio" -- reg: Address and length of the register set for the device -- #gpio-cells: Should be two. The first cell is the pin number and the - second cell is used to specify optional parameters (currently unused). -- gpio-controller: Marks the device node as a GPIO controller. - -Example: - gpio: gpio@90000000 { - compatible = "lsi,zevio-gpio"; - reg = <0x90000000 0x1000>; - gpio-controller; - #gpio-cells = <2>; - }; diff --git a/Documentation/devicetree/bindings/gpio/gpio_atmel.txt b/Documentation/devicetree/bindings/gpio/gpio_atmel.txt deleted file mode 100644 index 29416f9c3220..000000000000 --- a/Documentation/devicetree/bindings/gpio/gpio_atmel.txt +++ /dev/null @@ -1,31 +0,0 @@ -* Atmel GPIO controller (PIO) - -Required properties: -- compatible: "atmel,<chip>-gpio", where <chip> is at91rm9200 or at91sam9x5. -- reg: Should contain GPIO controller registers location and length -- interrupts: Should be the port interrupt shared by all the pins. -- #gpio-cells: Should be two. The first cell is the pin number and - the second cell is used to specify optional parameters to declare if the GPIO - is active high or low. See gpio.txt. -- gpio-controller: Marks the device node as a GPIO controller. -- interrupt-controller: Marks the device node as an interrupt controller. -- #interrupt-cells: Should be two. The first cell is the pin number and the - second cell is used to specify irq type flags, see the two cell description - in interrupt-controller/interrupts.txt for details. - -optional properties: -- #gpio-lines: Number of gpio if absent 32. - - -Example: - pioA: gpio@fffff200 { - compatible = "atmel,at91rm9200-gpio"; - reg = <0xfffff200 0x100>; - interrupts = <2 4>; - #gpio-cells = <2>; - gpio-controller; - #gpio-lines = <19>; - interrupt-controller; - #interrupt-cells = <2>; - }; - diff --git a/Documentation/devicetree/bindings/gpio/lsi,zevio-gpio.yaml b/Documentation/devicetree/bindings/gpio/lsi,zevio-gpio.yaml new file mode 100644 index 000000000000..e9e201a489e5 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/lsi,zevio-gpio.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/lsi,zevio-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Zevio GPIO controller + +maintainers: + - Pratik Farkase <pratikfarkase94@gmail.com> + +properties: + compatible: + items: + - const: lsi,zevio-gpio + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + "#gpio-cells": + const: 2 + + gpio-controller: true + +required: + - compatible + - reg + - "#gpio-cells" + - gpio-controller + +unevaluatedProperties: false + +examples: + - | + gpio@90000000 { + compatible = "lsi,zevio-gpio"; + reg = <0x90000000 0x1000>; + gpio-controller; + #gpio-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/hwmon/g762.txt b/Documentation/devicetree/bindings/hwmon/g762.txt deleted file mode 100644 index 6d154c4923de..000000000000 --- a/Documentation/devicetree/bindings/hwmon/g762.txt +++ /dev/null @@ -1,47 +0,0 @@ -GMT G762/G763 PWM Fan controller - -Required node properties: - - - "compatible": must be either "gmt,g762" or "gmt,g763" - - "reg": I2C bus address of the device - - "clocks": a fixed clock providing input clock frequency - on CLK pin of the chip. - -Optional properties: - - - "fan_startv": fan startup voltage. Accepted values are 0, 1, 2 and 3. - The higher the more. - - - "pwm_polarity": pwm polarity. Accepted values are 0 (positive duty) - and 1 (negative duty). - - - "fan_gear_mode": fan gear mode. Supported values are 0, 1 and 2. - -If an optional property is not set in .dts file, then current value is kept -unmodified (e.g. u-boot installed value). - -Additional information on operational parameters for the device is available -in Documentation/hwmon/g762.rst. A detailed datasheet for the device is available -at http://natisbad.org/NAS/refs/GMT_EDS-762_763-080710-0.2.pdf. - -Example g762 node: - - clocks { - #address-cells = <1>; - #size-cells = <0>; - - g762_clk: fixedclk { - compatible = "fixed-clock"; - #clock-cells = <0>; - clock-frequency = <8192>; - } - } - - g762: g762@3e { - compatible = "gmt,g762"; - reg = <0x3e>; - clocks = <&g762_clk> - fan_gear_mode = <0>; /* chip default */ - fan_startv = <1>; /* chip default */ - pwm_polarity = <0>; /* chip default */ - }; diff --git a/Documentation/devicetree/bindings/hwmon/gmt,g762.yaml b/Documentation/devicetree/bindings/hwmon/gmt,g762.yaml new file mode 100644 index 000000000000..8e1bffd252e6 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/gmt,g762.yaml @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/hwmon/gmt,g762.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: GMT G761/G762/G763 PWM Fan controller + +maintainers: + - Christian Marangi <ansuelsmth@gmail.com> + +description: | + GMT G761/G762/G763 PWM Fan controller. + + G761 supports an internal-clock hence the clocks property is optional. + If not defined, internal-clock will be used. (31KHz is the clock of + the internal crystal oscillator) + + If an optional property is not set in DT, then current value is kept + unmodified (e.g. bootloader installed value). + + Additional information on operational parameters for the device is available + in Documentation/hwmon/g762.rst. A detailed datasheet for the device is available + at http://natisbad.org/NAS/refs/GMT_EDS-762_763-080710-0.2.pdf. + +properties: + compatible: + enum: + - gmt,g761 + - gmt,g762 + - gmt,g763 + + reg: + maxItems: 1 + + clocks: + description: a fixed clock providing input clock frequency on CLK + pin of the chip. + maxItems: 1 + + fan_startv: + description: Fan startup voltage step + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + + pwm_polarity: + description: PWM polarity (positive or negative duty) + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + + fan_gear_mode: + description: FAN gear mode. Configure High speed fan setting factor + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2] + +required: + - compatible + - reg + +if: + properties: + compatible: + contains: + enum: + - gmt,g762 + - gmt,g763 +then: + required: + - clocks + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + g762@3e { + compatible = "gmt,g762"; + reg = <0x3e>; + clocks = <&g762_clk>; + fan_gear_mode = <0>; + fan_startv = <1>; + pwm_polarity = <0>; + }; + + g761@1e { + compatible = "gmt,g761"; + reg = <0x1e>; + fan_gear_mode = <0>; + fan_startv = <1>; + pwm_polarity = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/hwmon/maxim,max6639.yaml b/Documentation/devicetree/bindings/hwmon/maxim,max6639.yaml new file mode 100644 index 000000000000..4f5837a30773 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/maxim,max6639.yaml @@ -0,0 +1,92 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- + +$id: http://devicetree.org/schemas/hwmon/maxim,max6639.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim max6639 + +maintainers: + - Naresh Solanki <naresh.solanki@9elements.com> + +description: | + The MAX6639 is a 2-channel temperature monitor with dual, automatic, PWM + fan-speed controller. It monitors its own temperature and one external + diode-connected transistor or the temperatures of two external diode-connected + transistors, typically available in CPUs, FPGAs, or GPUs. + + Datasheets: + https://datasheets.maximintegrated.com/en/ds/MAX6639-MAX6639F.pdf + +properties: + compatible: + enum: + - maxim,max6639 + + reg: + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + '#pwm-cells': + const: 3 + +required: + - compatible + - reg + +patternProperties: + "^fan@[0-1]$": + type: object + description: + Represents the two fans and their specific configuration. + + $ref: fan-common.yaml# + + unevaluatedProperties: false + + properties: + reg: + description: + The fan number. + + required: + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + fan1: fan-controller@10 { + compatible = "maxim,max6639"; + reg = <0x10>; + #address-cells = <1>; + #size-cells = <0>; + #pwm-cells = <3>; + + fan@0 { + reg = <0x0>; + pulses-per-revolution = <2>; + max-rpm = <4000>; + target-rpm = <1000>; + pwms = <&fan1 0 25000 0>; + }; + + fan@1 { + reg = <0x1>; + pulses-per-revolution = <2>; + max-rpm = <8000>; + pwms = <&fan1 1 25000 0>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml b/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml index df86c2c92037..6ae961732e6b 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml @@ -66,6 +66,14 @@ properties: description: phandle to the regulator that provides the VS supply typically in range from 2.7 V to 5.5 V. + ti,alert-polarity-active-high: + description: Alert pin is asserted based on the value of Alert polarity Bit + of Mask/Enable register. Default value is Normal (0 which maps to + active-low open collector). The other value is Inverted + (1 which maps to active-high open collector). Specify this property to set + the alert polarity to active-high. + $ref: /schemas/types.yaml#/definitions/flag + required: - compatible - reg @@ -88,5 +96,6 @@ examples: label = "vdd_3v0"; shunt-resistor = <1000>; vs-supply = <&vdd_3v0>; + ti,alert-polarity-active-high; }; }; diff --git a/Documentation/devicetree/bindings/hwmon/ti,tmp108.yaml b/Documentation/devicetree/bindings/hwmon/ti,tmp108.yaml index 8b5307c875ff..0ad10d43fac0 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,tmp108.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,tmp108.yaml @@ -9,6 +9,14 @@ title: TMP108 temperature sensor maintainers: - Krzysztof Kozlowski <krzk@kernel.org> +description: | + The TMP108 is a digital-output temperature sensor with a + dynamically-programmable limit window, and under- and overtemperature + alert functions. + + Datasheets: + https://www.ti.com/product/TMP108 + properties: compatible: enum: @@ -24,6 +32,9 @@ properties: "#thermal-sensor-cells": const: 0 + vcc-supply: + description: phandle to the regulator that provides the V+ supply + required: - compatible - reg @@ -45,6 +56,7 @@ examples: interrupts = <7 IRQ_TYPE_LEVEL_LOW>; pinctrl-names = "default"; pinctrl-0 = <&tmp_alrt>; + vcc-supply = <&supply>; #thermal-sensor-cells = <0>; }; }; diff --git a/Documentation/devicetree/bindings/mmc/amlogic,meson-gx-mmc.yaml b/Documentation/devicetree/bindings/mmc/amlogic,meson-gx-mmc.yaml index bc403ae9e5d9..57646575a13f 100644 --- a/Documentation/devicetree/bindings/mmc/amlogic,meson-gx-mmc.yaml +++ b/Documentation/devicetree/bindings/mmc/amlogic,meson-gx-mmc.yaml @@ -51,6 +51,9 @@ properties: set when controller's internal DMA engine cannot access the DRAM memory, like on the G12A dedicated SDIO controller. + power-domains: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.yaml b/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.yaml index cbd3d6c6c77f..eee6be7a7867 100644 --- a/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.yaml +++ b/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.yaml @@ -20,6 +20,7 @@ properties: - const: brcm,sdhci-brcmstb - items: - enum: + - brcm,bcm2712-sdhci - brcm,bcm74165b0-sdhci - brcm,bcm7445-sdhci - brcm,bcm7425-sdhci diff --git a/Documentation/devicetree/bindings/mmc/fsl,esdhc.yaml b/Documentation/devicetree/bindings/mmc/fsl,esdhc.yaml new file mode 100644 index 000000000000..b86ffb53b18b --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/fsl,esdhc.yaml @@ -0,0 +1,105 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/fsl,esdhc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale Enhanced Secure Digital Host Controller (eSDHC) + +description: + The Enhanced Secure Digital Host Controller provides an interface + for MMC, SD, and SDIO types of memory cards. + +maintainers: + - Frank Li <Frank.Li@nxp.com> + +properties: + compatible: + items: + - enum: + - fsl,mpc8536-esdhc + - fsl,mpc8378-esdhc + - fsl,p2020-esdhc + - fsl,p4080-esdhc + - fsl,t1040-esdhc + - fsl,t4240-esdhc + - fsl,ls1012a-esdhc + - fsl,ls1028a-esdhc + - fsl,ls1088a-esdhc + - fsl,ls1043a-esdhc + - fsl,ls1046a-esdhc + - fsl,ls2080a-esdhc + - const: fsl,esdhc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-frequency: + $ref: /schemas/types.yaml#/definitions/uint32 + description: specifies eSDHC base clock frequency. + + sdhci,wp-inverted: + $ref: /schemas/types.yaml#/definitions/flag + deprecated: true + description: + specifies that eSDHC controller reports + inverted write-protect state; New devices should use the generic + "wp-inverted" property. + + sdhci,1-bit-only: + $ref: /schemas/types.yaml#/definitions/flag + deprecated: true + description: + specifies that a controller can only handle + 1-bit data transfers. New devices should use the generic + "bus-width = <1>" property. + + sdhci,auto-cmd12: + $ref: /schemas/types.yaml#/definitions/flag + description: + specifies that a controller can only handle auto CMD12. + + voltage-ranges: + $ref: /schemas/types.yaml#/definitions/uint32-matrix + items: + items: + - description: specifies minimum slot voltage (mV). + - description: specifies maximum slot voltage (mV). + minItems: 1 + maxItems: 8 + + dma-coherent: true + + little-endian: + $ref: /schemas/types.yaml#/definitions/flag + description: + If the host controller is little-endian mode, specify + this property. The default endian mode is big-endian. + +required: + - compatible + - reg + - interrupts + +allOf: + - $ref: sdhci-common.yaml# + +unevaluatedProperties: false + +examples: + - | + mmc@2e000 { + compatible = "fsl,mpc8378-esdhc", "fsl,esdhc"; + reg = <0x2e000 0x1000>; + interrupts = <42 0x8>; + interrupt-parent = <&ipic>; + /* Filled in by U-Boot */ + clock-frequency = <100000000>; + voltage-ranges = <3300 3300>; + }; diff --git a/Documentation/devicetree/bindings/mmc/fsl-esdhc.txt b/Documentation/devicetree/bindings/mmc/fsl-esdhc.txt deleted file mode 100644 index edb8cadb9541..000000000000 --- a/Documentation/devicetree/bindings/mmc/fsl-esdhc.txt +++ /dev/null @@ -1,52 +0,0 @@ -* Freescale Enhanced Secure Digital Host Controller (eSDHC) - -The Enhanced Secure Digital Host Controller provides an interface -for MMC, SD, and SDIO types of memory cards. - -This file documents differences between the core properties described -by mmc.txt and the properties used by the sdhci-esdhc driver. - -Required properties: - - compatible : should be "fsl,esdhc", or "fsl,<chip>-esdhc". - Possible compatibles for PowerPC: - "fsl,mpc8536-esdhc" - "fsl,mpc8378-esdhc" - "fsl,p2020-esdhc" - "fsl,p4080-esdhc" - "fsl,t1040-esdhc" - "fsl,t4240-esdhc" - Possible compatibles for ARM: - "fsl,ls1012a-esdhc" - "fsl,ls1028a-esdhc" - "fsl,ls1088a-esdhc" - "fsl,ls1043a-esdhc" - "fsl,ls1046a-esdhc" - "fsl,ls2080a-esdhc" - - clock-frequency : specifies eSDHC base clock frequency. - -Optional properties: - - sdhci,wp-inverted : specifies that eSDHC controller reports - inverted write-protect state; New devices should use the generic - "wp-inverted" property. - - sdhci,1-bit-only : specifies that a controller can only handle - 1-bit data transfers. New devices should use the generic - "bus-width = <1>" property. - - sdhci,auto-cmd12: specifies that a controller can only handle auto - CMD12. - - voltage-ranges : two cells are required, first cell specifies minimum - slot voltage (mV), second cell specifies maximum slot voltage (mV). - Several ranges could be specified. - - little-endian : If the host controller is little-endian mode, specify - this property. The default endian mode is big-endian. - -Example: - -sdhci@2e000 { - compatible = "fsl,mpc8378-esdhc", "fsl,esdhc"; - reg = <0x2e000 0x1000>; - interrupts = <42 0x8>; - interrupt-parent = <&ipic>; - /* Filled in by U-Boot */ - clock-frequency = <0>; - voltage-ranges = <3300 3300>; -}; diff --git a/Documentation/devicetree/bindings/mmc/mmc-spi-slot.yaml b/Documentation/devicetree/bindings/mmc/mmc-spi-slot.yaml index 36acc40c7d18..6e2cdac6a85d 100644 --- a/Documentation/devicetree/bindings/mmc/mmc-spi-slot.yaml +++ b/Documentation/devicetree/bindings/mmc/mmc-spi-slot.yaml @@ -27,17 +27,19 @@ properties: maxItems: 1 voltage-ranges: - $ref: /schemas/types.yaml#/definitions/uint32-array + $ref: /schemas/types.yaml#/definitions/uint32-matrix description: | Two cells are required, first cell specifies minimum slot voltage (mV), second cell specifies maximum slot voltage (mV). items: - - description: | - value for minimum slot voltage in mV - default: 3200 - - description: | - value for maximum slot voltage in mV - default: 3400 + items: + - description: | + value for minimum slot voltage in mV + default: 3200 + - description: | + value for maximum slot voltage in mV + default: 3400 + maxItems: 1 gpios: description: | diff --git a/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml b/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml index c24c537f62b1..11979b026d21 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml +++ b/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml @@ -51,6 +51,7 @@ properties: - qcom,sdm845-sdhci - qcom,sdx55-sdhci - qcom,sdx65-sdhci + - qcom,sdx75-sdhci - qcom,sm6115-sdhci - qcom,sm6125-sdhci - qcom,sm6350-sdhci diff --git a/Documentation/devicetree/bindings/mmc/sdhci-sprd.txt b/Documentation/devicetree/bindings/mmc/sdhci-sprd.txt deleted file mode 100644 index eb7eb1b529f0..000000000000 --- a/Documentation/devicetree/bindings/mmc/sdhci-sprd.txt +++ /dev/null @@ -1,67 +0,0 @@ -* Spreadtrum SDHCI controller (sdhci-sprd) - -The Secure Digital (SD) Host controller on Spreadtrum SoCs provides an interface -for MMC, SD and SDIO types of cards. - -This file documents differences between the core properties in mmc.txt -and the properties used by the sdhci-sprd driver. - -Required properties: -- compatible: Should contain "sprd,sdhci-r11". -- reg: physical base address of the controller and length. -- interrupts: Interrupts used by the SDHCI controller. -- clocks: Should contain phandle for the clock feeding the SDHCI controller -- clock-names: Should contain the following: - "sdio" - SDIO source clock (required) - "enable" - gate clock which used for enabling/disabling the device (required) - "2x_enable" - gate clock controlling the device for some special platforms (optional) - -Optional properties: -- assigned-clocks: the same with "sdio" clock -- assigned-clock-parents: the default parent of "sdio" clock -- pinctrl-names: should be "default", "state_uhs" -- pinctrl-0: should contain default/high speed pin control -- pinctrl-1: should contain uhs mode pin control - -PHY DLL delays are used to delay the data valid window, and align the window -to sampling clock. PHY DLL delays can be configured by following properties, -and each property contains 4 cells which are used to configure the clock data -write line delay value, clock read command line delay value, clock read data -positive edge delay value and clock read data negative edge delay value. -Each cell's delay value unit is cycle of the PHY clock. - -- sprd,phy-delay-legacy: Delay value for legacy timing. -- sprd,phy-delay-sd-highspeed: Delay value for SD high-speed timing. -- sprd,phy-delay-sd-uhs-sdr50: Delay value for SD UHS SDR50 timing. -- sprd,phy-delay-sd-uhs-sdr104: Delay value for SD UHS SDR50 timing. -- sprd,phy-delay-mmc-highspeed: Delay value for MMC high-speed timing. -- sprd,phy-delay-mmc-ddr52: Delay value for MMC DDR52 timing. -- sprd,phy-delay-mmc-hs200: Delay value for MMC HS200 timing. -- sprd,phy-delay-mmc-hs400: Delay value for MMC HS400 timing. -- sprd,phy-delay-mmc-hs400es: Delay value for MMC HS400 enhanced strobe timing. - -Examples: - -sdio0: sdio@20600000 { - compatible = "sprd,sdhci-r11"; - reg = <0 0x20600000 0 0x1000>; - interrupts = <GIC_SPI 60 IRQ_TYPE_LEVEL_HIGH>; - - clock-names = "sdio", "enable"; - clocks = <&ap_clk CLK_EMMC_2X>, - <&apahb_gate CLK_EMMC_EB>; - assigned-clocks = <&ap_clk CLK_EMMC_2X>; - assigned-clock-parents = <&rpll CLK_RPLL_390M>; - - pinctrl-names = "default", "state_uhs"; - pinctrl-0 = <&sd0_pins_default>; - pinctrl-1 = <&sd0_pins_uhs>; - - sprd,phy-delay-sd-uhs-sdr104 = <0x3f 0x7f 0x2e 0x2e>; - bus-width = <8>; - non-removable; - no-sdio; - no-sd; - cap-mmc-hw-reset; - status = "okay"; -}; diff --git a/Documentation/devicetree/bindings/mmc/sprd,sdhci-r11.yaml b/Documentation/devicetree/bindings/mmc/sprd,sdhci-r11.yaml new file mode 100644 index 000000000000..b08081bc018b --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/sprd,sdhci-r11.yaml @@ -0,0 +1,112 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/sprd,sdhci-r11.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Spreadtrum SDHCI controller + +maintainers: + - Orson Zhai <orsonzhai@gmail.com> + - Baolin Wang <baolin.wang7@gmail.com> + - Chunyan Zhang <zhang.lyra@gmail.com> + +properties: + compatible: + const: sprd,sdhci-r11 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 2 + items: + - description: SDIO source clock + - description: gate clock for enabling/disabling the device + - description: gate clock controlling the device for some special platforms (optional) + + clock-names: + minItems: 2 + items: + - const: sdio + - const: enable + - const: 2x_enable + + pinctrl-0: + description: default/high speed pin control + maxItems: 1 + + pinctrl-1: + description: UHS mode pin control + maxItems: 1 + + pinctrl-names: + minItems: 1 + items: + - const: default + - const: state_uhs + +patternProperties: + "^sprd,phy-delay-(legacy|mmc-(ddr52|highspeed|hs[24]00|hs400es)|sd-(highspeed|uhs-sdr(50|104)))$": + $ref: /schemas/types.yaml#/definitions/uint32-array + items: + - description: clock data write line delay value + - description: clock read command line delay value + - description: clock read data positive edge delay value + - description: clock read data negative edge delay value + description: + PHY DLL delays are used to delay the data valid window, and align + the window to the sampling clock. Each cell's delay value unit is + cycle of the PHY clock. + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +allOf: + - $ref: sdhci-common.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/sprd,sc9860-clk.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + mmc@50430000 { + compatible = "sprd,sdhci-r11"; + reg = <0x50430000 0x1000>; + interrupts = <GIC_SPI 41 IRQ_TYPE_LEVEL_HIGH>; + + clocks = <&aon_prediv CLK_EMMC_2X>, + <&apahb_gate CLK_EMMC_EB>, + <&aon_gate CLK_EMMC_2X_EN>; + clock-names = "sdio", "enable", "2x_enable"; + + pinctrl-0 = <&sd0_pins_default>; + pinctrl-1 = <&sd0_pins_uhs>; + pinctrl-names = "default", "state_uhs"; + + bus-width = <8>; + cap-mmc-hw-reset; + mmc-hs400-enhanced-strobe; + mmc-hs400-1_8v; + mmc-hs200-1_8v; + mmc-ddr-1_8v; + non-removable; + no-sdio; + no-sd; + + sprd,phy-delay-mmc-ddr52 = <0x3f 0x75 0x14 0x14>; + sprd,phy-delay-mmc-hs200 = <0x0 0x8c 0x8c 0x8c>; + sprd,phy-delay-mmc-hs400 = <0x44 0x7f 0x2e 0x2e>; + sprd,phy-delay-mmc-hs400es = <0x3f 0x3f 0x2e 0x2e>; + }; +... diff --git a/Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml b/Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml index c80c880a9dab..60aaf30d68ed 100644 --- a/Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml +++ b/Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml @@ -128,7 +128,6 @@ required: - cell-index - reg - fsl,fman-ports - - ptp-timer dependencies: pcs-handle-names: diff --git a/Documentation/devicetree/bindings/perf/fsl-imx-ddr.yaml b/Documentation/devicetree/bindings/perf/fsl-imx-ddr.yaml index 6c96a4204e5d..37e8b98f2cdc 100644 --- a/Documentation/devicetree/bindings/perf/fsl-imx-ddr.yaml +++ b/Documentation/devicetree/bindings/perf/fsl-imx-ddr.yaml @@ -30,6 +30,9 @@ properties: - items: - const: fsl,imx8dxl-ddr-pmu - const: fsl,imx8-ddr-pmu + - items: + - const: fsl,imx95-ddr-pmu + - const: fsl,imx93-ddr-pmu reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml index 50846a2d09c8..0bf2d9f093b5 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml @@ -29,7 +29,6 @@ properties: - qcom,pm7325-gpio - qcom,pm7550ba-gpio - qcom,pm8005-gpio - - qcom,pm8008-gpio - qcom,pm8018-gpio - qcom,pm8019-gpio - qcom,pm8038-gpio @@ -126,7 +125,6 @@ allOf: compatible: contains: enum: - - qcom,pm8008-gpio - qcom,pmi8950-gpio - qcom,pmr735d-gpio then: @@ -448,7 +446,6 @@ $defs: - gpio1-gpio10 for pm7325 - gpio1-gpio8 for pm7550ba - gpio1-gpio4 for pm8005 - - gpio1-gpio2 for pm8008 - gpio1-gpio6 for pm8018 - gpio1-gpio12 for pm8038 - gpio1-gpio40 for pm8058 diff --git a/Documentation/devicetree/bindings/power/amlogic,meson-sec-pwrc.yaml b/Documentation/devicetree/bindings/power/amlogic,meson-sec-pwrc.yaml index dab3d92bc273..15d74138baa3 100644 --- a/Documentation/devicetree/bindings/power/amlogic,meson-sec-pwrc.yaml +++ b/Documentation/devicetree/bindings/power/amlogic,meson-sec-pwrc.yaml @@ -20,6 +20,8 @@ properties: enum: - amlogic,meson-a1-pwrc - amlogic,meson-s4-pwrc + - amlogic,a4-pwrc + - amlogic,a5-pwrc - amlogic,c3-pwrc - amlogic,t7-pwrc diff --git a/Documentation/devicetree/bindings/pwm/adi,axi-pwmgen.yaml b/Documentation/devicetree/bindings/pwm/adi,axi-pwmgen.yaml new file mode 100644 index 000000000000..ec6115d3796b --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/adi,axi-pwmgen.yaml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pwm/adi,axi-pwmgen.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AXI PWM generator + +maintainers: + - Michael Hennerich <Michael.Hennerich@analog.com> + - Nuno Sá <nuno.sa@analog.com> + +description: + The Analog Devices AXI PWM generator can generate PWM signals + with variable pulse width and period. + + https://wiki.analog.com/resources/fpga/docs/axi_pwm_gen + +allOf: + - $ref: pwm.yaml# + +properties: + compatible: + const: adi,axi-pwmgen-2.00.a + + reg: + maxItems: 1 + + "#pwm-cells": + const: 2 + + clocks: + maxItems: 1 + +required: + - reg + - clocks + +unevaluatedProperties: false + +examples: + - | + pwm@44b00000 { + compatible = "adi,axi-pwmgen-2.00.a"; + reg = <0x44b00000 0x1000>; + clocks = <&spi_clk>; + #pwm-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/pwm/atmel,at91sam-pwm.yaml b/Documentation/devicetree/bindings/pwm/atmel,at91sam-pwm.yaml index 96cd6f3c3546..d20ad27657aa 100644 --- a/Documentation/devicetree/bindings/pwm/atmel,at91sam-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/atmel,at91sam-pwm.yaml @@ -23,7 +23,9 @@ properties: - atmel,sama5d2-pwm - microchip,sam9x60-pwm - items: - - const: microchip,sama7g5-pwm + - enum: + - microchip,sama7d65-pwm + - microchip,sama7g5-pwm - const: atmel,sama5d2-pwm - items: - const: microchip,sam9x7-pwm diff --git a/Documentation/devicetree/bindings/pwm/fsl,vf610-ftm-pwm.yaml b/Documentation/devicetree/bindings/pwm/fsl,vf610-ftm-pwm.yaml new file mode 100644 index 000000000000..7f9f72d95e7a --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/fsl,vf610-ftm-pwm.yaml @@ -0,0 +1,92 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pwm/fsl,vf610-ftm-pwm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale FlexTimer Module (FTM) PWM controller + +description: | + The same FTM PWM device can have a different endianness on different SoCs. The + device tree provides a property to describing this so that an operating system + device driver can handle all variants of the device. Refer to the table below + for the endianness of the FTM PWM block as integrated into the existing SoCs: + + SoC | FTM-PWM endianness + --------+------------------- + Vybrid | LE + LS1 | BE + LS2 | LE + + Please see ../regmap/regmap.txt for more detail about how to specify endian + modes in device tree. + +maintainers: + - Frank Li <Frank.Li@nxp.com> + +properties: + compatible: + enum: + - fsl,vf610-ftm-pwm + - fsl,imx8qm-ftm-pwm + + reg: + maxItems: 1 + + "#pwm-cells": + const: 3 + + clocks: + minItems: 4 + maxItems: 4 + + clock-names: + items: + - const: ftm_sys + - const: ftm_ext + - const: ftm_fix + - const: ftm_cnt_clk_en + + pinctrl-0: true + pinctrl-1: true + + pinctrl-names: + minItems: 1 + items: + - const: default + - const: sleep + + big-endian: + $ref: /schemas/types.yaml#/definitions/flag + description: + Boolean property, required if the FTM PWM registers use a big- + endian rather than little-endian layout. + +required: + - compatible + - reg + - clocks + - clock-names + +allOf: + - $ref: pwm.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/vf610-clock.h> + + pwm@40038000 { + compatible = "fsl,vf610-ftm-pwm"; + reg = <0x40038000 0x1000>; + #pwm-cells = <3>; + clocks = <&clks VF610_CLK_FTM0>, + <&clks VF610_CLK_FTM0_EXT_SEL>, + <&clks VF610_CLK_FTM0_FIX_SEL>, + <&clks VF610_CLK_FTM0_EXT_FIX_EN>; + clock-names = "ftm_sys", "ftm_ext", "ftm_fix", "ftm_cnt_clk_en"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_pwm0_1>; + big-endian; + }; diff --git a/Documentation/devicetree/bindings/pwm/imx-pwm.yaml b/Documentation/devicetree/bindings/pwm/imx-pwm.yaml index a84a240a61dc..04148198e34d 100644 --- a/Documentation/devicetree/bindings/pwm/imx-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/imx-pwm.yaml @@ -68,7 +68,6 @@ required: - reg - clocks - clock-names - - interrupts additionalProperties: false diff --git a/Documentation/devicetree/bindings/pwm/pwm-fsl-ftm.txt b/Documentation/devicetree/bindings/pwm/pwm-fsl-ftm.txt deleted file mode 100644 index 36532cd5ab25..000000000000 --- a/Documentation/devicetree/bindings/pwm/pwm-fsl-ftm.txt +++ /dev/null @@ -1,55 +0,0 @@ -Freescale FlexTimer Module (FTM) PWM controller - -The same FTM PWM device can have a different endianness on different SoCs. The -device tree provides a property to describing this so that an operating system -device driver can handle all variants of the device. Refer to the table below -for the endianness of the FTM PWM block as integrated into the existing SoCs: - - SoC | FTM-PWM endianness - --------+------------------- - Vybrid | LE - LS1 | BE - LS2 | LE - -Please see ../regmap/regmap.txt for more detail about how to specify endian -modes in device tree. - - -Required properties: -- compatible : should be "fsl,<soc>-ftm-pwm" and one of the following - compatible strings: - - "fsl,vf610-ftm-pwm" for PWM compatible with the one integrated on VF610 - - "fsl,imx8qm-ftm-pwm" for PWM compatible with the one integrated on i.MX8QM -- reg: Physical base address and length of the controller's registers -- #pwm-cells: Should be 3. See pwm.yaml in this directory for a description of - the cells format. -- clock-names: Should include the following module clock source entries: - "ftm_sys" (module clock, also can be used as counter clock), - "ftm_ext" (external counter clock), - "ftm_fix" (fixed counter clock), - "ftm_cnt_clk_en" (external and fixed counter clock enable/disable). -- clocks: Must contain a phandle and clock specifier for each entry in - clock-names, please see clock/clock-bindings.txt for details of the property - values. -- pinctrl-names: Must contain a "default" entry. -- pinctrl-NNN: One property must exist for each entry in pinctrl-names. - See pinctrl/pinctrl-bindings.txt for details of the property values. -- big-endian: Boolean property, required if the FTM PWM registers use a big- - endian rather than little-endian layout. - -Example: - -pwm0: pwm@40038000 { - compatible = "fsl,vf610-ftm-pwm"; - reg = <0x40038000 0x1000>; - #pwm-cells = <3>; - clock-names = "ftm_sys", "ftm_ext", - "ftm_fix", "ftm_cnt_clk_en"; - clocks = <&clks VF610_CLK_FTM0>, - <&clks VF610_CLK_FTM0_EXT_SEL>, - <&clks VF610_CLK_FTM0_FIX_SEL>, - <&clks VF610_CLK_FTM0_EXT_FIX_EN>; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_pwm0_1>; - big-endian; -}; diff --git a/Documentation/devicetree/bindings/pwm/pwm-gpio.yaml b/Documentation/devicetree/bindings/pwm/pwm-gpio.yaml new file mode 100644 index 000000000000..1576c193f2ab --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/pwm-gpio.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pwm/pwm-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic software PWM for modulating GPIOs + +maintainers: + - Stefan Wahren <wahrenst@gmx.net> + +allOf: + - $ref: pwm.yaml# + +properties: + compatible: + const: pwm-gpio + + "#pwm-cells": + const: 3 + description: + See pwm.yaml in this directory for a description of the cells format. + The first cell which represents the PWM instance number must always + be zero. + + gpios: + description: + GPIO to be modulated + maxItems: 1 + +required: + - compatible + - "#pwm-cells" + - gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + pwm { + #pwm-cells = <3>; + compatible = "pwm-gpio"; + gpios = <&gpio 1 GPIO_ACTIVE_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/pwm/pwm.yaml b/Documentation/devicetree/bindings/pwm/pwm.yaml index abd9fa873354..f2206ec3c7c4 100644 --- a/Documentation/devicetree/bindings/pwm/pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/pwm.yaml @@ -16,8 +16,10 @@ properties: pattern: "^pwm(@.*|-([0-9]|[1-9][0-9]+))?$" "#pwm-cells": - description: - Number of cells in a PWM specifier. + description: | + Number of cells in a PWM specifier. Typically the cells represent, in + order: the chip-relative PWM number, the PWM period in nanoseconds and + optionally a number of flags (defined in <dt-bindings/pwm/pwm.h>). required: - "#pwm-cells" diff --git a/Documentation/devicetree/bindings/timer/realtek,otto-timer.yaml b/Documentation/devicetree/bindings/timer/realtek,otto-timer.yaml new file mode 100644 index 000000000000..7b6ec2c69484 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/realtek,otto-timer.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/realtek,otto-timer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Realtek Otto SoCs Timer/Counter + +description: + Realtek SoCs support a number of timers/counters. These are used + as a per CPU clock event generator and an overall CPU clocksource. + +maintainers: + - Chris Packham <chris.packham@alliedtelesis.co.nz> + +properties: + $nodename: + pattern: "^timer@[0-9a-f]+$" + + compatible: + items: + - enum: + - realtek,rtl9302-timer + - const: realtek,otto-timer + + reg: + items: + - description: timer0 registers + - description: timer1 registers + - description: timer2 registers + - description: timer3 registers + - description: timer4 registers + + clocks: + maxItems: 1 + + interrupts: + items: + - description: timer0 interrupt + - description: timer1 interrupt + - description: timer2 interrupt + - description: timer3 interrupt + - description: timer4 interrupt + +required: + - compatible + - reg + - clocks + - interrupts + +additionalProperties: false + +examples: + - | + timer@3200 { + compatible = "realtek,rtl9302-timer", "realtek,otto-timer"; + reg = <0x3200 0x10>, <0x3210 0x10>, <0x3220 0x10>, + <0x3230 0x10>, <0x3240 0x10>; + + interrupt-parent = <&intc>; + interrupts = <7>, <8>, <9>, <10>, <11>; + clocks = <&lx_clk>; + }; diff --git a/Documentation/devicetree/bindings/timer/renesas,tmu.yaml b/Documentation/devicetree/bindings/timer/renesas,tmu.yaml index 360a5cf1ae9c..b6dd98d956f3 100644 --- a/Documentation/devicetree/bindings/timer/renesas,tmu.yaml +++ b/Documentation/devicetree/bindings/timer/renesas,tmu.yaml @@ -21,13 +21,24 @@ properties: compatible: items: - enum: + - renesas,tmu-r8a73a4 # R-Mobile APE6 - renesas,tmu-r8a7740 # R-Mobile A1 + - renesas,tmu-r8a7742 # RZ/G1H + - renesas,tmu-r8a7743 # RZ/G1M + - renesas,tmu-r8a7744 # RZ/G1N + - renesas,tmu-r8a7745 # RZ/G1E + - renesas,tmu-r8a77470 # RZ/G1C - renesas,tmu-r8a774a1 # RZ/G2M - renesas,tmu-r8a774b1 # RZ/G2N - renesas,tmu-r8a774c0 # RZ/G2E - renesas,tmu-r8a774e1 # RZ/G2H - renesas,tmu-r8a7778 # R-Car M1A - renesas,tmu-r8a7779 # R-Car H1 + - renesas,tmu-r8a7790 # R-Car H2 + - renesas,tmu-r8a7791 # R-Car M2-W + - renesas,tmu-r8a7792 # R-Car V2H + - renesas,tmu-r8a7793 # R-Car M2-N + - renesas,tmu-r8a7794 # R-Car E2 - renesas,tmu-r8a7795 # R-Car H3 - renesas,tmu-r8a7796 # R-Car M3-W - renesas,tmu-r8a77961 # R-Car M3-W+ @@ -94,6 +105,7 @@ if: compatible: contains: enum: + - renesas,tmu-r8a73a4 - renesas,tmu-r8a7740 - renesas,tmu-r8a7778 - renesas,tmu-r8a7779 diff --git a/Documentation/devicetree/bindings/timer/sifive,clint.yaml b/Documentation/devicetree/bindings/timer/sifive,clint.yaml index fced6f2d8ecb..b42d43d2de48 100644 --- a/Documentation/devicetree/bindings/timer/sifive,clint.yaml +++ b/Documentation/devicetree/bindings/timer/sifive,clint.yaml @@ -40,6 +40,7 @@ properties: - allwinner,sun20i-d1-clint - sophgo,cv1800b-clint - sophgo,cv1812h-clint + - sophgo,sg2002-clint - thead,th1520-clint - const: thead,c900-clint - items: diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index 0a419453d183..03e290cb65c3 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -168,6 +168,8 @@ properties: - isil,isl69269 # Intersil ISL76682 Ambient Light Sensor - isil,isl76682 + # JEDEC JESD300 (SPD5118) Hub and Serial Presence Detect + - jedec,spd5118 # Linear Technology LTC2488 - lineartechnology,ltc2488 # 5 Bit Programmable, Pulse-Width Modulator @@ -286,14 +288,22 @@ properties: - mps,mp2857 # Monolithic Power Systems Inc. multi-phase controller mp2888 - mps,mp2888 + # Monolithic Power Systems Inc. multi-phase controller mp2891 + - mps,mp2891 # Monolithic Power Systems Inc. multi-phase controller mp2971 - mps,mp2971 # Monolithic Power Systems Inc. multi-phase controller mp2973 - mps,mp2973 # Monolithic Power Systems Inc. multi-phase controller mp2975 - mps,mp2975 + # Monolithic Power Systems Inc. multi-phase controller mp2993 + - mps,mp2993 + # Monolithic Power Systems Inc. multi-phase hot-swap controller mp5920 + - mps,mp5920 # Monolithic Power Systems Inc. multi-phase hot-swap controller mp5990 - mps,mp5990 + # Monolithic Power Systems Inc. digital step-down converter mp9941 + - mps,mp9941 # Monolithic Power Systems Inc. synchronous step-down converter mpq8785 - mps,mpq8785 # Temperature sensor with integrated fan control diff --git a/Documentation/driver-api/cxl/memory-devices.rst b/Documentation/driver-api/cxl/memory-devices.rst index 5149ecdc53c7..d732c42526df 100644 --- a/Documentation/driver-api/cxl/memory-devices.rst +++ b/Documentation/driver-api/cxl/memory-devices.rst @@ -328,6 +328,12 @@ CXL Memory Device .. kernel-doc:: drivers/cxl/mem.c :doc: cxl mem +.. kernel-doc:: drivers/cxl/cxlmem.h + :internal: + +.. kernel-doc:: drivers/cxl/core/memdev.c + :identifiers: + CXL Port -------- .. kernel-doc:: drivers/cxl/port.c @@ -341,6 +347,15 @@ CXL Core .. kernel-doc:: drivers/cxl/cxl.h :internal: +.. kernel-doc:: drivers/cxl/core/hdm.c + :doc: cxl core hdm + +.. kernel-doc:: drivers/cxl/core/hdm.c + :identifiers: + +.. kernel-doc:: drivers/cxl/core/cdat.c + :identifiers: + .. kernel-doc:: drivers/cxl/core/port.c :doc: cxl core diff --git a/Documentation/driver-api/gpio/board.rst b/Documentation/driver-api/gpio/board.rst index b33aa04f213f..4fd1cbd8296e 100644 --- a/Documentation/driver-api/gpio/board.rst +++ b/Documentation/driver-api/gpio/board.rst @@ -4,12 +4,6 @@ GPIO Mappings This document explains how GPIOs can be assigned to given devices and functions. -Note that it only applies to the new descriptor-based interface. For a -description of the deprecated integer-based GPIO interface please refer to -legacy.rst (actually, there is no real mapping possible with the old -interface; you just fetch an integer from somewhere and request the -corresponding GPIO). - All platforms can enable the GPIO library, but if the platform strictly requires GPIO functionality to be present, it needs to select GPIOLIB from its Kconfig. Then, how GPIOs are mapped depends on what the platform uses to diff --git a/Documentation/driver-api/gpio/consumer.rst b/Documentation/driver-api/gpio/consumer.rst index ab56ab0dd7a6..bb3366047fad 100644 --- a/Documentation/driver-api/gpio/consumer.rst +++ b/Documentation/driver-api/gpio/consumer.rst @@ -2,9 +2,7 @@ GPIO Descriptor Consumer Interface ================================== -This document describes the consumer interface of the GPIO framework. Note that -it describes the new descriptor-based interface. For a description of the -deprecated integer-based GPIO interface please refer to legacy.rst. +This document describes the consumer interface of the GPIO framework. Guidelines for GPIOs consumers diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst index e541bd2e898b..ae433261e11a 100644 --- a/Documentation/driver-api/gpio/driver.rst +++ b/Documentation/driver-api/gpio/driver.rst @@ -69,9 +69,8 @@ driver code: The code implementing a gpio_chip should support multiple instances of the controller, preferably using the driver model. That code will configure each -gpio_chip and issue gpiochip_add(), gpiochip_add_data(), or -devm_gpiochip_add_data(). Removing a GPIO controller should be rare; use -gpiochip_remove() when it is unavoidable. +gpio_chip and issue gpiochip_add_data() or devm_gpiochip_add_data(). Removing +a GPIO controller should be rare; use gpiochip_remove() when it is unavoidable. Often a gpio_chip is part of an instance-specific structure with states not exposed by the GPIO interfaces, such as addressing, power management, and more. diff --git a/Documentation/driver-api/gpio/drivers-on-gpio.rst b/Documentation/driver-api/gpio/drivers-on-gpio.rst index af632d764ac6..95572d2a94ce 100644 --- a/Documentation/driver-api/gpio/drivers-on-gpio.rst +++ b/Documentation/driver-api/gpio/drivers-on-gpio.rst @@ -27,7 +27,12 @@ hardware descriptions such as device tree or ACPI: to the lines for a more permanent solution of this type. - gpio-beeper: drivers/input/misc/gpio-beeper.c is used to provide a beep from - an external speaker connected to a GPIO line. + an external speaker connected to a GPIO line. (If the beep is controlled by + off/on, for an actual PWM waveform, see pwm-gpio below.) + +- pwm-gpio: drivers/pwm/pwm-gpio.c is used to toggle a GPIO with a high + resolution timer producing a PWM waveform on the GPIO line, as well as + Linux high resolution timers can do. - extcon-gpio: drivers/extcon/extcon-gpio.c is used when you need to read an external connector status, such as a headset line for an audio driver or an diff --git a/Documentation/driver-api/gpio/index.rst b/Documentation/driver-api/gpio/index.rst index 1d48fe248f05..34b57cee3391 100644 --- a/Documentation/driver-api/gpio/index.rst +++ b/Documentation/driver-api/gpio/index.rst @@ -13,7 +13,6 @@ Contents: consumer board drivers-on-gpio - legacy bt8xxgpio Core diff --git a/Documentation/driver-api/gpio/intro.rst b/Documentation/driver-api/gpio/intro.rst index c9c19243b97f..5936a9c57df3 100644 --- a/Documentation/driver-api/gpio/intro.rst +++ b/Documentation/driver-api/gpio/intro.rst @@ -10,18 +10,6 @@ The documents in this directory give detailed instructions on how to access GPIOs in drivers, and how to write a driver for a device that provides GPIOs itself. -Due to the history of GPIO interfaces in the kernel, there are two different -ways to obtain and use GPIOs: - - - The descriptor-based interface is the preferred way to manipulate GPIOs, - and is described by all the files in this directory excepted legacy.rst. - - The legacy integer-based interface which is considered deprecated (but still - usable for compatibility reasons) is documented in legacy.rst. - -The remainder of this document applies to the new descriptor-based interface. -legacy.rst contains the same information applied to the legacy -integer-based interface. - What is a GPIO? =============== diff --git a/Documentation/driver-api/gpio/legacy.rst b/Documentation/driver-api/gpio/legacy.rst deleted file mode 100644 index 534dfe95d128..000000000000 --- a/Documentation/driver-api/gpio/legacy.rst +++ /dev/null @@ -1,679 +0,0 @@ -====================== -Legacy GPIO Interfaces -====================== - -This provides an overview of GPIO access conventions on Linux. - -These calls use the gpio_* naming prefix. No other calls should use that -prefix, or the related __gpio_* prefix. - - -What is a GPIO? -=============== -A "General Purpose Input/Output" (GPIO) is a flexible software-controlled -digital signal. They are provided from many kinds of chip, and are familiar -to Linux developers working with embedded and custom hardware. Each GPIO -represents a bit connected to a particular pin, or "ball" on Ball Grid Array -(BGA) packages. Board schematics show which external hardware connects to -which GPIOs. Drivers can be written generically, so that board setup code -passes such pin configuration data to drivers. - -System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every -non-dedicated pin can be configured as a GPIO; and most chips have at least -several dozen of them. Programmable logic devices (like FPGAs) can easily -provide GPIOs; multifunction chips like power managers, and audio codecs -often have a few such pins to help with pin scarcity on SOCs; and there are -also "GPIO Expander" chips that connect using the I2C or SPI serial busses. -Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS -firmware knowing how they're used). - -The exact capabilities of GPIOs vary between systems. Common options: - - - Output values are writable (high=1, low=0). Some chips also have - options about how that value is driven, so that for example only one - value might be driven ... supporting "wire-OR" and similar schemes - for the other value (notably, "open drain" signaling). - - - Input values are likewise readable (1, 0). Some chips support readback - of pins configured as "output", which is very useful in such "wire-OR" - cases (to support bidirectional signaling). GPIO controllers may have - input de-glitch/debounce logic, sometimes with software controls. - - - Inputs can often be used as IRQ signals, often edge triggered but - sometimes level triggered. Such IRQs may be configurable as system - wakeup events, to wake the system from a low power state. - - - Usually a GPIO will be configurable as either input or output, as needed - by different product boards; single direction ones exist too. - - - Most GPIOs can be accessed while holding spinlocks, but those accessed - through a serial bus normally can't. Some systems support both types. - -On a given board each GPIO is used for one specific purpose like monitoring -MMC/SD card insertion/removal, detecting card writeprotect status, driving -a LED, configuring a transceiver, bitbanging a serial bus, poking a hardware -watchdog, sensing a switch, and so on. - - -GPIO conventions -================ -Note that this is called a "convention" because you don't need to do it this -way, and it's no crime if you don't. There **are** cases where portability -is not the main issue; GPIOs are often used for the kind of board-specific -glue logic that may even change between board revisions, and can't ever be -used on a board that's wired differently. Only least-common-denominator -functionality can be very portable. Other features are platform-specific, -and that can be critical for glue logic. - -Plus, this doesn't require any implementation framework, just an interface. -One platform might implement it as simple inline functions accessing chip -registers; another might implement it by delegating through abstractions -used for several very different kinds of GPIO controller. (There is some -optional code supporting such an implementation strategy, described later -in this document, but drivers acting as clients to the GPIO interface must -not care how it's implemented.) - -That said, if the convention is supported on their platform, drivers should -use it when possible. Platforms must select GPIOLIB if GPIO functionality -is strictly required. Drivers that can't work without -standard GPIO calls should have Kconfig entries which depend on GPIOLIB. The -GPIO calls are available, either as "real code" or as optimized-away stubs, -when drivers use the include file: - - #include <linux/gpio.h> - -If you stick to this convention then it'll be easier for other developers to -see what your code is doing, and help maintain it. - -Note that these operations include I/O barriers on platforms which need to -use them; drivers don't need to add them explicitly. - - -Identifying GPIOs ------------------ -GPIOs are identified by unsigned integers in the range 0..MAX_INT. That -reserves "negative" numbers for other purposes like marking signals as -"not available on this board", or indicating faults. Code that doesn't -touch the underlying hardware treats these integers as opaque cookies. - -Platforms define how they use those integers, and usually #define symbols -for the GPIO lines so that board-specific setup code directly corresponds -to the relevant schematics. In contrast, drivers should only use GPIO -numbers passed to them from that setup code, using platform_data to hold -board-specific pin configuration data (along with other board specific -data they need). That avoids portability problems. - -So for example one platform uses numbers 32-159 for GPIOs; while another -uses numbers 0..63 with one set of GPIO controllers, 64-79 with another -type of GPIO controller, and on one particular board 80-95 with an FPGA. -The numbers need not be contiguous; either of those platforms could also -use numbers 2000-2063 to identify GPIOs in a bank of I2C GPIO expanders. - -If you want to initialize a structure with an invalid GPIO number, use -some negative number (perhaps "-EINVAL"); that will never be valid. To -test if such number from such a structure could reference a GPIO, you -may use this predicate: - - int gpio_is_valid(int number); - -A number that's not valid will be rejected by calls which may request -or free GPIOs (see below). Other numbers may also be rejected; for -example, a number might be valid but temporarily unused on a given board. - -Whether a platform supports multiple GPIO controllers is a platform-specific -implementation issue, as are whether that support can leave "holes" in the space -of GPIO numbers, and whether new controllers can be added at runtime. Such issues -can affect things including whether adjacent GPIO numbers are both valid. - -Using GPIOs ------------ -The first thing a system should do with a GPIO is allocate it, using -the gpio_request() call; see later. - -One of the next things to do with a GPIO, often in board setup code when -setting up a platform_device using the GPIO, is mark its direction:: - - /* set as input or output, returning 0 or negative errno */ - int gpio_direction_input(unsigned gpio); - int gpio_direction_output(unsigned gpio, int value); - -The return value is zero for success, else a negative errno. It should -be checked, since the get/set calls don't have error returns and since -misconfiguration is possible. You should normally issue these calls from -a task context. However, for spinlock-safe GPIOs it's OK to use them -before tasking is enabled, as part of early board setup. - -For output GPIOs, the value provided becomes the initial output value. -This helps avoid signal glitching during system startup. - -For compatibility with legacy interfaces to GPIOs, setting the direction -of a GPIO implicitly requests that GPIO (see below) if it has not been -requested already. That compatibility is being removed from the optional -gpiolib framework. - -Setting the direction can fail if the GPIO number is invalid, or when -that particular GPIO can't be used in that mode. It's generally a bad -idea to rely on boot firmware to have set the direction correctly, since -it probably wasn't validated to do more than boot Linux. (Similarly, -that board setup code probably needs to multiplex that pin as a GPIO, -and configure pullups/pulldowns appropriately.) - - -Spinlock-Safe GPIO access -------------------------- -Most GPIO controllers can be accessed with memory read/write instructions. -Those don't need to sleep, and can safely be done from inside hard -(nonthreaded) IRQ handlers and similar contexts. - -Use the following calls to access such GPIOs:: - - /* GPIO INPUT: return zero or nonzero */ - int gpio_get_value(unsigned gpio); - - /* GPIO OUTPUT */ - void gpio_set_value(unsigned gpio, int value); - -The values are boolean, zero for low, nonzero for high. When reading the -value of an output pin, the value returned should be what's seen on the -pin ... that won't always match the specified output value, because of -issues including open-drain signaling and output latencies. - -The get/set calls have no error returns because "invalid GPIO" should have -been reported earlier from gpio_direction_*(). However, note that not all -platforms can read the value of output pins; those that can't should always -return zero. Also, using these calls for GPIOs that can't safely be accessed -without sleeping (see below) is an error. - -Platform-specific implementations are encouraged to optimize the two -calls to access the GPIO value in cases where the GPIO number (and for -output, value) are constant. It's normal for them to need only a couple -of instructions in such cases (reading or writing a hardware register), -and not to need spinlocks. Such optimized calls can make bitbanging -applications a lot more efficient (in both space and time) than spending -dozens of instructions on subroutine calls. - - -GPIO access that may sleep --------------------------- -Some GPIO controllers must be accessed using message based busses like I2C -or SPI. Commands to read or write those GPIO values require waiting to -get to the head of a queue to transmit a command and get its response. -This requires sleeping, which can't be done from inside IRQ handlers. -To access such GPIOs, a different set of accessors is defined:: - - /* GPIO INPUT: return zero or nonzero, might sleep */ - int gpio_get_value_cansleep(unsigned gpio); - - /* GPIO OUTPUT, might sleep */ - void gpio_set_value_cansleep(unsigned gpio, int value); - -Accessing such GPIOs requires a context which may sleep, for example -a threaded IRQ handler, and those accessors must be used instead of -spinlock-safe accessors without the cansleep() name suffix. - -Other than the fact that these accessors might sleep, and will work -on GPIOs that can't be accessed from hardIRQ handlers, these calls act -the same as the spinlock-safe calls. - -**IN ADDITION** calls to setup and configure such GPIOs must be made -from contexts which may sleep, since they may need to access the GPIO -controller chip too (These setup calls are usually made from board -setup or driver probe/teardown code, so this is an easy constraint.):: - - gpio_direction_input() - gpio_direction_output() - gpio_request() - - ## gpio_request_one() - - gpio_free() - - -Claiming and Releasing GPIOs ----------------------------- -To help catch system configuration errors, two calls are defined:: - - /* request GPIO, returning 0 or negative errno. - * non-null labels may be useful for diagnostics. - */ - int gpio_request(unsigned gpio, const char *label); - - /* release previously-claimed GPIO */ - void gpio_free(unsigned gpio); - -Passing invalid GPIO numbers to gpio_request() will fail, as will requesting -GPIOs that have already been claimed with that call. The return value of -gpio_request() must be checked. You should normally issue these calls from -a task context. However, for spinlock-safe GPIOs it's OK to request GPIOs -before tasking is enabled, as part of early board setup. - -These calls serve two basic purposes. One is marking the signals which -are actually in use as GPIOs, for better diagnostics; systems may have -several hundred potential GPIOs, but often only a dozen are used on any -given board. Another is to catch conflicts, identifying errors when -(a) two or more drivers wrongly think they have exclusive use of that -signal, or (b) something wrongly believes it's safe to remove drivers -needed to manage a signal that's in active use. That is, requesting a -GPIO can serve as a kind of lock. - -Some platforms may also use knowledge about what GPIOs are active for -power management, such as by powering down unused chip sectors and, more -easily, gating off unused clocks. - -For GPIOs that use pins known to the pinctrl subsystem, that subsystem should -be informed of their use; a gpiolib driver's .request() operation may call -pinctrl_gpio_request(), and a gpiolib driver's .free() operation may call -pinctrl_gpio_free(). The pinctrl subsystem allows a pinctrl_gpio_request() -to succeed concurrently with a pin or pingroup being "owned" by a device for -pin multiplexing. - -Any programming of pin multiplexing hardware that is needed to route the -GPIO signal to the appropriate pin should occur within a GPIO driver's -.direction_input() or .direction_output() operations, and occur after any -setup of an output GPIO's value. This allows a glitch-free migration from a -pin's special function to GPIO. This is sometimes required when using a GPIO -to implement a workaround on signals typically driven by a non-GPIO HW block. - -Some platforms allow some or all GPIO signals to be routed to different pins. -Similarly, other aspects of the GPIO or pin may need to be configured, such as -pullup/pulldown. Platform software should arrange that any such details are -configured prior to gpio_request() being called for those GPIOs, e.g. using -the pinctrl subsystem's mapping table, so that GPIO users need not be aware -of these details. - -Also note that it's your responsibility to have stopped using a GPIO -before you free it. - -Considering in most cases GPIOs are actually configured right after they -are claimed, three additional calls are defined:: - - /* request a single GPIO, with initial configuration specified by - * 'flags', identical to gpio_request() wrt other arguments and - * return value - */ - int gpio_request_one(unsigned gpio, unsigned long flags, const char *label); - -where 'flags' is currently defined to specify the following properties: - - * GPIOF_DIR_IN - to configure direction as input - * GPIOF_DIR_OUT - to configure direction as output - - * GPIOF_INIT_LOW - as output, set initial level to LOW - * GPIOF_INIT_HIGH - as output, set initial level to HIGH - -since GPIOF_INIT_* are only valid when configured as output, so group valid -combinations as: - - * GPIOF_IN - configure as input - * GPIOF_OUT_INIT_LOW - configured as output, initial level LOW - * GPIOF_OUT_INIT_HIGH - configured as output, initial level HIGH - -Further more, to ease the claim/release of multiple GPIOs, 'struct gpio' is -introduced to encapsulate all three fields as:: - - struct gpio { - unsigned gpio; - unsigned long flags; - const char *label; - }; - -A typical example of usage:: - - static struct gpio leds_gpios[] = { - { 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* default to ON */ - { 33, GPIOF_OUT_INIT_LOW, "Green LED" }, /* default to OFF */ - { 34, GPIOF_OUT_INIT_LOW, "Red LED" }, /* default to OFF */ - { 35, GPIOF_OUT_INIT_LOW, "Blue LED" }, /* default to OFF */ - { ... }, - }; - - err = gpio_request_one(31, GPIOF_IN, "Reset Button"); - if (err) - ... - - -GPIOs mapped to IRQs --------------------- -GPIO numbers are unsigned integers; so are IRQ numbers. These make up -two logically distinct namespaces (GPIO 0 need not use IRQ 0). You can -map between them using calls like:: - - /* map GPIO numbers to IRQ numbers */ - int gpio_to_irq(unsigned gpio); - -Those return either the corresponding number in the other namespace, or -else a negative errno code if the mapping can't be done. (For example, -some GPIOs can't be used as IRQs.) It is an unchecked error to use a GPIO -number that wasn't set up as an input using gpio_direction_input(), or -to use an IRQ number that didn't originally come from gpio_to_irq(). - -These two mapping calls are expected to cost on the order of a single -addition or subtraction. They're not allowed to sleep. - -Non-error values returned from gpio_to_irq() can be passed to request_irq() -or free_irq(). They will often be stored into IRQ resources for platform -devices, by the board-specific initialization code. Note that IRQ trigger -options are part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as are -system wakeup capabilities. - - -Emulating Open Drain Signals ----------------------------- -Sometimes shared signals need to use "open drain" signaling, where only the -low signal level is actually driven. (That term applies to CMOS transistors; -"open collector" is used for TTL.) A pullup resistor causes the high signal -level. This is sometimes called a "wire-AND"; or more practically, from the -negative logic (low=true) perspective this is a "wire-OR". - -One common example of an open drain signal is a shared active-low IRQ line. -Also, bidirectional data bus signals sometimes use open drain signals. - -Some GPIO controllers directly support open drain outputs; many don't. When -you need open drain signaling but your hardware doesn't directly support it, -there's a common idiom you can use to emulate it with any GPIO pin that can -be used as either an input or an output: - - LOW: gpio_direction_output(gpio, 0) ... this drives the signal - and overrides the pullup. - - HIGH: gpio_direction_input(gpio) ... this turns off the output, - so the pullup (or some other device) controls the signal. - -If you are "driving" the signal high but gpio_get_value(gpio) reports a low -value (after the appropriate rise time passes), you know some other component -is driving the shared signal low. That's not necessarily an error. As one -common example, that's how I2C clocks are stretched: a slave that needs a -slower clock delays the rising edge of SCK, and the I2C master adjusts its -signaling rate accordingly. - - -GPIO controllers and the pinctrl subsystem ------------------------------------------- - -A GPIO controller on a SOC might be tightly coupled with the pinctrl -subsystem, in the sense that the pins can be used by other functions -together with an optional gpio feature. We have already covered the -case where e.g. a GPIO controller need to reserve a pin or set the -direction of a pin by calling any of:: - - pinctrl_gpio_request() - pinctrl_gpio_free() - pinctrl_gpio_direction_input() - pinctrl_gpio_direction_output() - -But how does the pin control subsystem cross-correlate the GPIO -numbers (which are a global business) to a certain pin on a certain -pin controller? - -This is done by registering "ranges" of pins, which are essentially -cross-reference tables. These are described in -Documentation/driver-api/pin-control.rst - -While the pin allocation is totally managed by the pinctrl subsystem, -gpio (under gpiolib) is still maintained by gpio drivers. It may happen -that different pin ranges in a SoC is managed by different gpio drivers. - -This makes it logical to let gpio drivers announce their pin ranges to -the pin ctrl subsystem before it will call 'pinctrl_gpio_request' in order -to request the corresponding pin to be prepared by the pinctrl subsystem -before any gpio usage. - -For this, the gpio controller can register its pin range with pinctrl -subsystem. There are two ways of doing it currently: with or without DT. - -For with DT support refer to Documentation/devicetree/bindings/gpio/gpio.txt. - -For non-DT support, user can call gpiochip_add_pin_range() with appropriate -parameters to register a range of gpio pins with a pinctrl driver. For this -exact name string of pinctrl device has to be passed as one of the -argument to this routine. - - -What do these conventions omit? -=============================== -One of the biggest things these conventions omit is pin multiplexing, since -this is highly chip-specific and nonportable. One platform might not need -explicit multiplexing; another might have just two options for use of any -given pin; another might have eight options per pin; another might be able -to route a given GPIO to any one of several pins. (Yes, those examples all -come from systems that run Linux today.) - -Related to multiplexing is configuration and enabling of the pullups or -pulldowns integrated on some platforms. Not all platforms support them, -or support them in the same way; and any given board might use external -pullups (or pulldowns) so that the on-chip ones should not be used. -(When a circuit needs 5 kOhm, on-chip 100 kOhm resistors won't do.) -Likewise drive strength (2 mA vs 20 mA) and voltage (1.8V vs 3.3V) is a -platform-specific issue, as are models like (not) having a one-to-one -correspondence between configurable pins and GPIOs. - -There are other system-specific mechanisms that are not specified here, -like the aforementioned options for input de-glitching and wire-OR output. -Hardware may support reading or writing GPIOs in gangs, but that's usually -configuration dependent: for GPIOs sharing the same bank. (GPIOs are -commonly grouped in banks of 16 or 32, with a given SOC having several such -banks.) Some systems can trigger IRQs from output GPIOs, or read values -from pins not managed as GPIOs. Code relying on such mechanisms will -necessarily be nonportable. - -Dynamic definition of GPIOs is not currently standard; for example, as -a side effect of configuring an add-on board with some GPIO expanders. - - -GPIO implementor's framework (OPTIONAL) -======================================= -As noted earlier, there is an optional implementation framework making it -easier for platforms to support different kinds of GPIO controller using -the same programming interface. This framework is called "gpiolib". - -As a debugging aid, if debugfs is available a /sys/kernel/debug/gpio file -will be found there. That will list all the controllers registered through -this framework, and the state of the GPIOs currently in use. - - -Controller Drivers: gpio_chip ------------------------------ -In this framework each GPIO controller is packaged as a "struct gpio_chip" -with information common to each controller of that type: - - - methods to establish GPIO direction - - methods used to access GPIO values - - flag saying whether calls to its methods may sleep - - optional debugfs dump method (showing extra state like pullup config) - - label for diagnostics - -There is also per-instance data, which may come from device.platform_data: -the number of its first GPIO, and how many GPIOs it exposes. - -The code implementing a gpio_chip should support multiple instances of the -controller, possibly using the driver model. That code will configure each -gpio_chip and issue gpiochip_add(). Removing a GPIO controller should be -rare; use gpiochip_remove() when it is unavoidable. - -Most often a gpio_chip is part of an instance-specific structure with state -not exposed by the GPIO interfaces, such as addressing, power management, -and more. Chips such as codecs will have complex non-GPIO state. - -Any debugfs dump method should normally ignore signals which haven't been -requested as GPIOs. They can use gpiochip_is_requested(), which returns -either NULL or the label associated with that GPIO when it was requested. - - -Platform Support ----------------- -To force-enable this framework, a platform's Kconfig will "select" GPIOLIB, -else it is up to the user to configure support for GPIO. - -If neither of these options are selected, the platform does not support -GPIOs through GPIO-lib and the code cannot be enabled by the user. - -Trivial implementations of those functions can directly use framework -code, which always dispatches through the gpio_chip:: - - #define gpio_get_value __gpio_get_value - #define gpio_set_value __gpio_set_value - -Fancier implementations could instead define those as inline functions with -logic optimizing access to specific SOC-based GPIOs. For example, if the -referenced GPIO is the constant "12", getting or setting its value could -cost as little as two or three instructions, never sleeping. When such an -optimization is not possible those calls must delegate to the framework -code, costing at least a few dozen instructions. For bitbanged I/O, such -instruction savings can be significant. - -For SOCs, platform-specific code defines and registers gpio_chip instances -for each bank of on-chip GPIOs. Those GPIOs should be numbered/labeled to -match chip vendor documentation, and directly match board schematics. They -may well start at zero and go up to a platform-specific limit. Such GPIOs -are normally integrated into platform initialization to make them always be -available, from arch_initcall() or earlier; they can often serve as IRQs. - - -Board Support -------------- -For external GPIO controllers -- such as I2C or SPI expanders, ASICs, multi -function devices, FPGAs or CPLDs -- most often board-specific code handles -registering controller devices and ensures that their drivers know what GPIO -numbers to use with gpiochip_add(). Their numbers often start right after -platform-specific GPIOs. - -For example, board setup code could create structures identifying the range -of GPIOs that chip will expose, and passes them to each GPIO expander chip -using platform_data. Then the chip driver's probe() routine could pass that -data to gpiochip_add(). - -Initialization order can be important. For example, when a device relies on -an I2C-based GPIO, its probe() routine should only be called after that GPIO -becomes available. That may mean the device should not be registered until -calls for that GPIO can work. One way to address such dependencies is for -such gpio_chip controllers to provide setup() and teardown() callbacks to -board specific code; those board specific callbacks would register devices -once all the necessary resources are available, and remove them later when -the GPIO controller device becomes unavailable. - - -Sysfs Interface for Userspace (OPTIONAL) -======================================== -Platforms which use the "gpiolib" implementors framework may choose to -configure a sysfs user interface to GPIOs. This is different from the -debugfs interface, since it provides control over GPIO direction and -value instead of just showing a gpio state summary. Plus, it could be -present on production systems without debugging support. - -Given appropriate hardware documentation for the system, userspace could -know for example that GPIO #23 controls the write protect line used to -protect boot loader segments in flash memory. System upgrade procedures -may need to temporarily remove that protection, first importing a GPIO, -then changing its output state, then updating the code before re-enabling -the write protection. In normal use, GPIO #23 would never be touched, -and the kernel would have no need to know about it. - -Again depending on appropriate hardware documentation, on some systems -userspace GPIO can be used to determine system configuration data that -standard kernels won't know about. And for some tasks, simple userspace -GPIO drivers could be all that the system really needs. - -Note that standard kernel drivers exist for common "LEDs and Buttons" -GPIO tasks: "leds-gpio" and "gpio_keys", respectively. Use those -instead of talking directly to the GPIOs; they integrate with kernel -frameworks better than your userspace code could. - - -Paths in Sysfs --------------- -There are three kinds of entry in /sys/class/gpio: - - - Control interfaces used to get userspace control over GPIOs; - - - GPIOs themselves; and - - - GPIO controllers ("gpio_chip" instances). - -That's in addition to standard files including the "device" symlink. - -The control interfaces are write-only: - - /sys/class/gpio/ - - "export" ... Userspace may ask the kernel to export control of - a GPIO to userspace by writing its number to this file. - - Example: "echo 19 > export" will create a "gpio19" node - for GPIO #19, if that's not requested by kernel code. - - "unexport" ... Reverses the effect of exporting to userspace. - - Example: "echo 19 > unexport" will remove a "gpio19" - node exported using the "export" file. - -GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42) -and have the following read/write attributes: - - /sys/class/gpio/gpioN/ - - "direction" ... reads as either "in" or "out". This value may - normally be written. Writing as "out" defaults to - initializing the value as low. To ensure glitch free - operation, values "low" and "high" may be written to - configure the GPIO as an output with that initial value. - - Note that this attribute *will not exist* if the kernel - doesn't support changing the direction of a GPIO, or - it was exported by kernel code that didn't explicitly - allow userspace to reconfigure this GPIO's direction. - - "value" ... reads as either 0 (low) or 1 (high). If the GPIO - is configured as an output, this value may be written; - any nonzero value is treated as high. - - If the pin can be configured as interrupt-generating interrupt - and if it has been configured to generate interrupts (see the - description of "edge"), you can poll(2) on that file and - poll(2) will return whenever the interrupt was triggered. If - you use poll(2), set the events POLLPRI. If you use select(2), - set the file descriptor in exceptfds. After poll(2) returns, - either lseek(2) to the beginning of the sysfs file and read the - new value or close the file and re-open it to read the value. - - "edge" ... reads as either "none", "rising", "falling", or - "both". Write these strings to select the signal edge(s) - that will make poll(2) on the "value" file return. - - This file exists only if the pin can be configured as an - interrupt generating input pin. - - "active_low" ... reads as either 0 (false) or 1 (true). Write - any nonzero value to invert the value attribute both - for reading and writing. Existing and subsequent - poll(2) support configuration via the edge attribute - for "rising" and "falling" edges will follow this - setting. - -GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the -controller implementing GPIOs starting at #42) and have the following -read-only attributes: - - /sys/class/gpio/gpiochipN/ - - "base" ... same as N, the first GPIO managed by this chip - - "label" ... provided for diagnostics (not always unique) - - "ngpio" ... how many GPIOs this manges (N to N + ngpio - 1) - -Board documentation should in most cases cover what GPIOs are used for -what purposes. However, those numbers are not always stable; GPIOs on -a daughtercard might be different depending on the base board being used, -or other cards in the stack. In such cases, you may need to use the -gpiochip nodes (possibly in conjunction with schematics) to determine -the correct GPIO number to use for a given signal. - - -API Reference -============= - -The functions listed in this section are deprecated. The GPIO descriptor based -API should be used in new code. - -.. kernel-doc:: drivers/gpio/gpiolib-legacy.c - :export: diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 8f5c1ee02e2f..e8e496d23e1d 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -34,6 +34,7 @@ algorithms work. seq_file sharedsubtree idmappings + iomap/index automount-support diff --git a/Documentation/filesystems/iomap/design.rst b/Documentation/filesystems/iomap/design.rst new file mode 100644 index 000000000000..f8ee3427bc1a --- /dev/null +++ b/Documentation/filesystems/iomap/design.rst @@ -0,0 +1,441 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. _iomap_design: + +.. + Dumb style notes to maintain the author's sanity: + Please try to start sentences on separate lines so that + sentence changes don't bleed colors in diff. + Heading decorations are documented in sphinx.rst. + +============== +Library Design +============== + +.. contents:: Table of Contents + :local: + +Introduction +============ + +iomap is a filesystem library for handling common file operations. +The library has two layers: + + 1. A lower layer that provides an iterator over ranges of file offsets. + This layer tries to obtain mappings of each file ranges to storage + from the filesystem, but the storage information is not necessarily + required. + + 2. An upper layer that acts upon the space mappings provided by the + lower layer iterator. + +The iteration can involve mappings of file's logical offset ranges to +physical extents, but the storage layer information is not necessarily +required, e.g. for walking cached file information. +The library exports various APIs for implementing file operations such +as: + + * Pagecache reads and writes + * Folio write faults to the pagecache + * Writeback of dirty folios + * Direct I/O reads and writes + * fsdax I/O reads, writes, loads, and stores + * FIEMAP + * lseek ``SEEK_DATA`` and ``SEEK_HOLE`` + * swapfile activation + +This origins of this library is the file I/O path that XFS once used; it +has now been extended to cover several other operations. + +Who Should Read This? +===================== + +The target audience for this document are filesystem, storage, and +pagecache programmers and code reviewers. + +If you are working on PCI, machine architectures, or device drivers, you +are most likely in the wrong place. + +How Is This Better? +=================== + +Unlike the classic Linux I/O model which breaks file I/O into small +units (generally memory pages or blocks) and looks up space mappings on +the basis of that unit, the iomap model asks the filesystem for the +largest space mappings that it can create for a given file operation and +initiates operations on that basis. +This strategy improves the filesystem's visibility into the size of the +operation being performed, which enables it to combat fragmentation with +larger space allocations when possible. +Larger space mappings improve runtime performance by amortizing the cost +of mapping function calls into the filesystem across a larger amount of +data. + +At a high level, an iomap operation `looks like this +<https://lore.kernel.org/all/ZGbVaewzcCysclPt@dread.disaster.area/>`_: + +1. For each byte in the operation range... + + 1. Obtain a space mapping via ``->iomap_begin`` + + 2. For each sub-unit of work... + + 1. Revalidate the mapping and go back to (1) above, if necessary. + So far only the pagecache operations need to do this. + + 2. Do the work + + 3. Increment operation cursor + + 4. Release the mapping via ``->iomap_end``, if necessary + +Each iomap operation will be covered in more detail below. +This library was covered previously by an `LWN article +<https://lwn.net/Articles/935934/>`_ and a `KernelNewbies page +<https://kernelnewbies.org/KernelProjects/iomap>`_. + +The goal of this document is to provide a brief discussion of the +design and capabilities of iomap, followed by a more detailed catalog +of the interfaces presented by iomap. +If you change iomap, please update this design document. + +File Range Iterator +=================== + +Definitions +----------- + + * **buffer head**: Shattered remnants of the old buffer cache. + + * ``fsblock``: The block size of a file, also known as ``i_blocksize``. + + * ``i_rwsem``: The VFS ``struct inode`` rwsemaphore. + Processes hold this in shared mode to read file state and contents. + Some filesystems may allow shared mode for writes. + Processes often hold this in exclusive mode to change file state and + contents. + + * ``invalidate_lock``: The pagecache ``struct address_space`` + rwsemaphore that protects against folio insertion and removal for + filesystems that support punching out folios below EOF. + Processes wishing to insert folios must hold this lock in shared + mode to prevent removal, though concurrent insertion is allowed. + Processes wishing to remove folios must hold this lock in exclusive + mode to prevent insertions. + Concurrent removals are not allowed. + + * ``dax_read_lock``: The RCU read lock that dax takes to prevent a + device pre-shutdown hook from returning before other threads have + released resources. + + * **filesystem mapping lock**: This synchronization primitive is + internal to the filesystem and must protect the file mapping data + from updates while a mapping is being sampled. + The filesystem author must determine how this coordination should + happen; it does not need to be an actual lock. + + * **iomap internal operation lock**: This is a general term for + synchronization primitives that iomap functions take while holding a + mapping. + A specific example would be taking the folio lock while reading or + writing the pagecache. + + * **pure overwrite**: A write operation that does not require any + metadata or zeroing operations to perform during either submission + or completion. + This implies that the fileystem must have already allocated space + on disk as ``IOMAP_MAPPED`` and the filesystem must not place any + constaints on IO alignment or size. + The only constraints on I/O alignment are device level (minimum I/O + size and alignment, typically sector size). + +``struct iomap`` +---------------- + +The filesystem communicates to the iomap iterator the mapping of +byte ranges of a file to byte ranges of a storage device with the +structure below: + +.. code-block:: c + + struct iomap { + u64 addr; + loff_t offset; + u64 length; + u16 type; + u16 flags; + struct block_device *bdev; + struct dax_device *dax_dev; + voidw *inline_data; + void *private; + const struct iomap_folio_ops *folio_ops; + u64 validity_cookie; + }; + +The fields are as follows: + + * ``offset`` and ``length`` describe the range of file offsets, in + bytes, covered by this mapping. + These fields must always be set by the filesystem. + + * ``type`` describes the type of the space mapping: + + * **IOMAP_HOLE**: No storage has been allocated. + This type must never be returned in response to an ``IOMAP_WRITE`` + operation because writes must allocate and map space, and return + the mapping. + The ``addr`` field must be set to ``IOMAP_NULL_ADDR``. + iomap does not support writing (whether via pagecache or direct + I/O) to a hole. + + * **IOMAP_DELALLOC**: A promise to allocate space at a later time + ("delayed allocation"). + If the filesystem returns IOMAP_F_NEW here and the write fails, the + ``->iomap_end`` function must delete the reservation. + The ``addr`` field must be set to ``IOMAP_NULL_ADDR``. + + * **IOMAP_MAPPED**: The file range maps to specific space on the + storage device. + The device is returned in ``bdev`` or ``dax_dev``. + The device address, in bytes, is returned via ``addr``. + + * **IOMAP_UNWRITTEN**: The file range maps to specific space on the + storage device, but the space has not yet been initialized. + The device is returned in ``bdev`` or ``dax_dev``. + The device address, in bytes, is returned via ``addr``. + Reads from this type of mapping will return zeroes to the caller. + For a write or writeback operation, the ioend should update the + mapping to MAPPED. + Refer to the sections about ioends for more details. + + * **IOMAP_INLINE**: The file range maps to the memory buffer + specified by ``inline_data``. + For write operation, the ``->iomap_end`` function presumably + handles persisting the data. + The ``addr`` field must be set to ``IOMAP_NULL_ADDR``. + + * ``flags`` describe the status of the space mapping. + These flags should be set by the filesystem in ``->iomap_begin``: + + * **IOMAP_F_NEW**: The space under the mapping is newly allocated. + Areas that will not be written to must be zeroed. + If a write fails and the mapping is a space reservation, the + reservation must be deleted. + + * **IOMAP_F_DIRTY**: The inode will have uncommitted metadata needed + to access any data written. + fdatasync is required to commit these changes to persistent + storage. + This needs to take into account metadata changes that *may* be made + at I/O completion, such as file size updates from direct I/O. + + * **IOMAP_F_SHARED**: The space under the mapping is shared. + Copy on write is necessary to avoid corrupting other file data. + + * **IOMAP_F_BUFFER_HEAD**: This mapping requires the use of buffer + heads for pagecache operations. + Do not add more uses of this. + + * **IOMAP_F_MERGED**: Multiple contiguous block mappings were + coalesced into this single mapping. + This is only useful for FIEMAP. + + * **IOMAP_F_XATTR**: The mapping is for extended attribute data, not + regular file data. + This is only useful for FIEMAP. + + * **IOMAP_F_PRIVATE**: Starting with this value, the upper bits can + be set by the filesystem for its own purposes. + + These flags can be set by iomap itself during file operations. + The filesystem should supply an ``->iomap_end`` function if it needs + to observe these flags: + + * **IOMAP_F_SIZE_CHANGED**: The file size has changed as a result of + using this mapping. + + * **IOMAP_F_STALE**: The mapping was found to be stale. + iomap will call ``->iomap_end`` on this mapping and then + ``->iomap_begin`` to obtain a new mapping. + + Currently, these flags are only set by pagecache operations. + + * ``addr`` describes the device address, in bytes. + + * ``bdev`` describes the block device for this mapping. + This only needs to be set for mapped or unwritten operations. + + * ``dax_dev`` describes the DAX device for this mapping. + This only needs to be set for mapped or unwritten operations, and + only for a fsdax operation. + + * ``inline_data`` points to a memory buffer for I/O involving + ``IOMAP_INLINE`` mappings. + This value is ignored for all other mapping types. + + * ``private`` is a pointer to `filesystem-private information + <https://lore.kernel.org/all/20180619164137.13720-7-hch@lst.de/>`_. + This value will be passed unchanged to ``->iomap_end``. + + * ``folio_ops`` will be covered in the section on pagecache operations. + + * ``validity_cookie`` is a magic freshness value set by the filesystem + that should be used to detect stale mappings. + For pagecache operations this is critical for correct operation + because page faults can occur, which implies that filesystem locks + should not be held between ``->iomap_begin`` and ``->iomap_end``. + Filesystems with completely static mappings need not set this value. + Only pagecache operations revalidate mappings; see the section about + ``iomap_valid`` for details. + +``struct iomap_ops`` +-------------------- + +Every iomap function requires the filesystem to pass an operations +structure to obtain a mapping and (optionally) to release the mapping: + +.. code-block:: c + + struct iomap_ops { + int (*iomap_begin)(struct inode *inode, loff_t pos, loff_t length, + unsigned flags, struct iomap *iomap, + struct iomap *srcmap); + + int (*iomap_end)(struct inode *inode, loff_t pos, loff_t length, + ssize_t written, unsigned flags, + struct iomap *iomap); + }; + +``->iomap_begin`` +~~~~~~~~~~~~~~~~~ + +iomap operations call ``->iomap_begin`` to obtain one file mapping for +the range of bytes specified by ``pos`` and ``length`` for the file +``inode``. +This mapping should be returned through the ``iomap`` pointer. +The mapping must cover at least the first byte of the supplied file +range, but it does not need to cover the entire requested range. + +Each iomap operation describes the requested operation through the +``flags`` argument. +The exact value of ``flags`` will be documented in the +operation-specific sections below. +These flags can, at least in principle, apply generally to iomap +operations: + + * ``IOMAP_DIRECT`` is set when the caller wishes to issue file I/O to + block storage. + + * ``IOMAP_DAX`` is set when the caller wishes to issue file I/O to + memory-like storage. + + * ``IOMAP_NOWAIT`` is set when the caller wishes to perform a best + effort attempt to avoid any operation that would result in blocking + the submitting task. + This is similar in intent to ``O_NONBLOCK`` for network APIs - it is + intended for asynchronous applications to keep doing other work + instead of waiting for the specific unavailable filesystem resource + to become available. + Filesystems implementing ``IOMAP_NOWAIT`` semantics need to use + trylock algorithms. + They need to be able to satisfy the entire I/O request range with a + single iomap mapping. + They need to avoid reading or writing metadata synchronously. + They need to avoid blocking memory allocations. + They need to avoid waiting on transaction reservations to allow + modifications to take place. + They probably should not be allocating new space. + And so on. + If there is any doubt in the filesystem developer's mind as to + whether any specific ``IOMAP_NOWAIT`` operation may end up blocking, + then they should return ``-EAGAIN`` as early as possible rather than + start the operation and force the submitting task to block. + ``IOMAP_NOWAIT`` is often set on behalf of ``IOCB_NOWAIT`` or + ``RWF_NOWAIT``. + +If it is necessary to read existing file contents from a `different +<https://lore.kernel.org/all/20191008071527.29304-9-hch@lst.de/>`_ +device or address range on a device, the filesystem should return that +information via ``srcmap``. +Only pagecache and fsdax operations support reading from one mapping and +writing to another. + +``->iomap_end`` +~~~~~~~~~~~~~~~ + +After the operation completes, the ``->iomap_end`` function, if present, +is called to signal that iomap is finished with a mapping. +Typically, implementations will use this function to tear down any +context that were set up in ``->iomap_begin``. +For example, a write might wish to commit the reservations for the bytes +that were operated upon and unreserve any space that was not operated +upon. +``written`` might be zero if no bytes were touched. +``flags`` will contain the same value passed to ``->iomap_begin``. +iomap ops for reads are not likely to need to supply this function. + +Both functions should return a negative errno code on error, or zero on +success. + +Preparing for File Operations +============================= + +iomap only handles mapping and I/O. +Filesystems must still call out to the VFS to check input parameters +and file state before initiating an I/O operation. +It does not handle obtaining filesystem freeze protection, updating of +timestamps, stripping privileges, or access control. + +Locking Hierarchy +================= + +iomap requires that filesystems supply their own locking model. +There are three categories of synchronization primitives, as far as +iomap is concerned: + + * The **upper** level primitive is provided by the filesystem to + coordinate access to different iomap operations. + The exact primitive is specifc to the filesystem and operation, + but is often a VFS inode, pagecache invalidation, or folio lock. + For example, a filesystem might take ``i_rwsem`` before calling + ``iomap_file_buffered_write`` and ``iomap_file_unshare`` to prevent + these two file operations from clobbering each other. + Pagecache writeback may lock a folio to prevent other threads from + accessing the folio until writeback is underway. + + * The **lower** level primitive is taken by the filesystem in the + ``->iomap_begin`` and ``->iomap_end`` functions to coordinate + access to the file space mapping information. + The fields of the iomap object should be filled out while holding + this primitive. + The upper level synchronization primitive, if any, remains held + while acquiring the lower level synchronization primitive. + For example, XFS takes ``ILOCK_EXCL`` and ext4 takes ``i_data_sem`` + while sampling mappings. + Filesystems with immutable mapping information may not require + synchronization here. + + * The **operation** primitive is taken by an iomap operation to + coordinate access to its own internal data structures. + The upper level synchronization primitive, if any, remains held + while acquiring this primitive. + The lower level primitive is not held while acquiring this + primitive. + For example, pagecache write operations will obtain a file mapping, + then grab and lock a folio to copy new contents. + It may also lock an internal folio state object to update metadata. + +The exact locking requirements are specific to the filesystem; for +certain operations, some of these locks can be elided. +All further mention of locking are *recommendations*, not mandates. +Each filesystem author must figure out the locking for themself. + +Bugs and Limitations +==================== + + * No support for fscrypt. + * No support for compression. + * No support for fsverity yet. + * Strong assumptions that IO should work the way it does on XFS. + * Does iomap *actually* work for non-regular file data? + +Patches welcome! diff --git a/Documentation/filesystems/iomap/index.rst b/Documentation/filesystems/iomap/index.rst new file mode 100644 index 000000000000..3c6a52440250 --- /dev/null +++ b/Documentation/filesystems/iomap/index.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================= +VFS iomap Documentation +======================= + +.. toctree:: + :maxdepth: 2 + :numbered: + + design + operations + porting diff --git a/Documentation/filesystems/iomap/operations.rst b/Documentation/filesystems/iomap/operations.rst new file mode 100644 index 000000000000..8e6c721d2330 --- /dev/null +++ b/Documentation/filesystems/iomap/operations.rst @@ -0,0 +1,713 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. _iomap_operations: + +.. + Dumb style notes to maintain the author's sanity: + Please try to start sentences on separate lines so that + sentence changes don't bleed colors in diff. + Heading decorations are documented in sphinx.rst. + +========================= +Supported File Operations +========================= + +.. contents:: Table of Contents + :local: + +Below are a discussion of the high level file operations that iomap +implements. + +Buffered I/O +============ + +Buffered I/O is the default file I/O path in Linux. +File contents are cached in memory ("pagecache") to satisfy reads and +writes. +Dirty cache will be written back to disk at some point that can be +forced via ``fsync`` and variants. + +iomap implements nearly all the folio and pagecache management that +filesystems have to implement themselves under the legacy I/O model. +This means that the filesystem need not know the details of allocating, +mapping, managing uptodate and dirty state, or writeback of pagecache +folios. +Under the legacy I/O model, this was managed very inefficiently with +linked lists of buffer heads instead of the per-folio bitmaps that iomap +uses. +Unless the filesystem explicitly opts in to buffer heads, they will not +be used, which makes buffered I/O much more efficient, and the pagecache +maintainer much happier. + +``struct address_space_operations`` +----------------------------------- + +The following iomap functions can be referenced directly from the +address space operations structure: + + * ``iomap_dirty_folio`` + * ``iomap_release_folio`` + * ``iomap_invalidate_folio`` + * ``iomap_is_partially_uptodate`` + +The following address space operations can be wrapped easily: + + * ``read_folio`` + * ``readahead`` + * ``writepages`` + * ``bmap`` + * ``swap_activate`` + +``struct iomap_folio_ops`` +-------------------------- + +The ``->iomap_begin`` function for pagecache operations may set the +``struct iomap::folio_ops`` field to an ops structure to override +default behaviors of iomap: + +.. code-block:: c + + struct iomap_folio_ops { + struct folio *(*get_folio)(struct iomap_iter *iter, loff_t pos, + unsigned len); + void (*put_folio)(struct inode *inode, loff_t pos, unsigned copied, + struct folio *folio); + bool (*iomap_valid)(struct inode *inode, const struct iomap *iomap); + }; + +iomap calls these functions: + + - ``get_folio``: Called to allocate and return an active reference to + a locked folio prior to starting a write. + If this function is not provided, iomap will call + ``iomap_get_folio``. + This could be used to `set up per-folio filesystem state + <https://lore.kernel.org/all/20190429220934.10415-5-agruenba@redhat.com/>`_ + for a write. + + - ``put_folio``: Called to unlock and put a folio after a pagecache + operation completes. + If this function is not provided, iomap will ``folio_unlock`` and + ``folio_put`` on its own. + This could be used to `commit per-folio filesystem state + <https://lore.kernel.org/all/20180619164137.13720-6-hch@lst.de/>`_ + that was set up by ``->get_folio``. + + - ``iomap_valid``: The filesystem may not hold locks between + ``->iomap_begin`` and ``->iomap_end`` because pagecache operations + can take folio locks, fault on userspace pages, initiate writeback + for memory reclamation, or engage in other time-consuming actions. + If a file's space mapping data are mutable, it is possible that the + mapping for a particular pagecache folio can `change in the time it + takes + <https://lore.kernel.org/all/20221123055812.747923-8-david@fromorbit.com/>`_ + to allocate, install, and lock that folio. + + For the pagecache, races can happen if writeback doesn't take + ``i_rwsem`` or ``invalidate_lock`` and updates mapping information. + Races can also happen if the filesytem allows concurrent writes. + For such files, the mapping *must* be revalidated after the folio + lock has been taken so that iomap can manage the folio correctly. + + fsdax does not need this revalidation because there's no writeback + and no support for unwritten extents. + + Filesystems subject to this kind of race must provide a + ``->iomap_valid`` function to decide if the mapping is still valid. + If the mapping is not valid, the mapping will be sampled again. + + To support making the validity decision, the filesystem's + ``->iomap_begin`` function may set ``struct iomap::validity_cookie`` + at the same time that it populates the other iomap fields. + A simple validation cookie implementation is a sequence counter. + If the filesystem bumps the sequence counter every time it modifies + the inode's extent map, it can be placed in the ``struct + iomap::validity_cookie`` during ``->iomap_begin``. + If the value in the cookie is found to be different to the value + the filesystem holds when the mapping is passed back to + ``->iomap_valid``, then the iomap should considered stale and the + validation failed. + +These ``struct kiocb`` flags are significant for buffered I/O with iomap: + + * ``IOCB_NOWAIT``: Turns on ``IOMAP_NOWAIT``. + +Internal per-Folio State +------------------------ + +If the fsblock size matches the size of a pagecache folio, it is assumed +that all disk I/O operations will operate on the entire folio. +The uptodate (memory contents are at least as new as what's on disk) and +dirty (memory contents are newer than what's on disk) status of the +folio are all that's needed for this case. + +If the fsblock size is less than the size of a pagecache folio, iomap +tracks the per-fsblock uptodate and dirty state itself. +This enables iomap to handle both "bs < ps" `filesystems +<https://lore.kernel.org/all/20230725122932.144426-1-ritesh.list@gmail.com/>`_ +and large folios in the pagecache. + +iomap internally tracks two state bits per fsblock: + + * ``uptodate``: iomap will try to keep folios fully up to date. + If there are read(ahead) errors, those fsblocks will not be marked + uptodate. + The folio itself will be marked uptodate when all fsblocks within the + folio are uptodate. + + * ``dirty``: iomap will set the per-block dirty state when programs + write to the file. + The folio itself will be marked dirty when any fsblock within the + folio is dirty. + +iomap also tracks the amount of read and write disk IOs that are in +flight. +This structure is much lighter weight than ``struct buffer_head`` +because there is only one per folio, and the per-fsblock overhead is two +bits vs. 104 bytes. + +Filesystems wishing to turn on large folios in the pagecache should call +``mapping_set_large_folios`` when initializing the incore inode. + +Buffered Readahead and Reads +---------------------------- + +The ``iomap_readahead`` function initiates readahead to the pagecache. +The ``iomap_read_folio`` function reads one folio's worth of data into +the pagecache. +The ``flags`` argument to ``->iomap_begin`` will be set to zero. +The pagecache takes whatever locks it needs before calling the +filesystem. + +Buffered Writes +--------------- + +The ``iomap_file_buffered_write`` function writes an ``iocb`` to the +pagecache. +``IOMAP_WRITE`` or ``IOMAP_WRITE`` | ``IOMAP_NOWAIT`` will be passed as +the ``flags`` argument to ``->iomap_begin``. +Callers commonly take ``i_rwsem`` in either shared or exclusive mode +before calling this function. + +mmap Write Faults +~~~~~~~~~~~~~~~~~ + +The ``iomap_page_mkwrite`` function handles a write fault to a folio in +the pagecache. +``IOMAP_WRITE | IOMAP_FAULT`` will be passed as the ``flags`` argument +to ``->iomap_begin``. +Callers commonly take the mmap ``invalidate_lock`` in shared or +exclusive mode before calling this function. + +Buffered Write Failures +~~~~~~~~~~~~~~~~~~~~~~~ + +After a short write to the pagecache, the areas not written will not +become marked dirty. +The filesystem must arrange to `cancel +<https://lore.kernel.org/all/20221123055812.747923-6-david@fromorbit.com/>`_ +such `reservations +<https://lore.kernel.org/linux-xfs/20220817093627.GZ3600936@dread.disaster.area/>`_ +because writeback will not consume the reservation. +The ``iomap_file_buffered_write_punch_delalloc`` can be called from a +``->iomap_end`` function to find all the clean areas of the folios +caching a fresh (``IOMAP_F_NEW``) delalloc mapping. +It takes the ``invalidate_lock``. + +The filesystem must supply a function ``punch`` to be called for +each file range in this state. +This function must *only* remove delayed allocation reservations, in +case another thread racing with the current thread writes successfully +to the same region and triggers writeback to flush the dirty data out to +disk. + +Zeroing for File Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Filesystems can call ``iomap_zero_range`` to perform zeroing of the +pagecache for non-truncation file operations that are not aligned to +the fsblock size. +``IOMAP_ZERO`` will be passed as the ``flags`` argument to +``->iomap_begin``. +Callers typically hold ``i_rwsem`` and ``invalidate_lock`` in exclusive +mode before calling this function. + +Unsharing Reflinked File Data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Filesystems can call ``iomap_file_unshare`` to force a file sharing +storage with another file to preemptively copy the shared data to newly +allocate storage. +``IOMAP_WRITE | IOMAP_UNSHARE`` will be passed as the ``flags`` argument +to ``->iomap_begin``. +Callers typically hold ``i_rwsem`` and ``invalidate_lock`` in exclusive +mode before calling this function. + +Truncation +---------- + +Filesystems can call ``iomap_truncate_page`` to zero the bytes in the +pagecache from EOF to the end of the fsblock during a file truncation +operation. +``truncate_setsize`` or ``truncate_pagecache`` will take care of +everything after the EOF block. +``IOMAP_ZERO`` will be passed as the ``flags`` argument to +``->iomap_begin``. +Callers typically hold ``i_rwsem`` and ``invalidate_lock`` in exclusive +mode before calling this function. + +Pagecache Writeback +------------------- + +Filesystems can call ``iomap_writepages`` to respond to a request to +write dirty pagecache folios to disk. +The ``mapping`` and ``wbc`` parameters should be passed unchanged. +The ``wpc`` pointer should be allocated by the filesystem and must +be initialized to zero. + +The pagecache will lock each folio before trying to schedule it for +writeback. +It does not lock ``i_rwsem`` or ``invalidate_lock``. + +The dirty bit will be cleared for all folios run through the +``->map_blocks`` machinery described below even if the writeback fails. +This is to prevent dirty folio clots when storage devices fail; an +``-EIO`` is recorded for userspace to collect via ``fsync``. + +The ``ops`` structure must be specified and is as follows: + +``struct iomap_writeback_ops`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + struct iomap_writeback_ops { + int (*map_blocks)(struct iomap_writepage_ctx *wpc, struct inode *inode, + loff_t offset, unsigned len); + int (*prepare_ioend)(struct iomap_ioend *ioend, int status); + void (*discard_folio)(struct folio *folio, loff_t pos); + }; + +The fields are as follows: + + - ``map_blocks``: Sets ``wpc->iomap`` to the space mapping of the file + range (in bytes) given by ``offset`` and ``len``. + iomap calls this function for each dirty fs block in each dirty folio, + though it will `reuse mappings + <https://lore.kernel.org/all/20231207072710.176093-15-hch@lst.de/>`_ + for runs of contiguous dirty fsblocks within a folio. + Do not return ``IOMAP_INLINE`` mappings here; the ``->iomap_end`` + function must deal with persisting written data. + Do not return ``IOMAP_DELALLOC`` mappings here; iomap currently + requires mapping to allocated space. + Filesystems can skip a potentially expensive mapping lookup if the + mappings have not changed. + This revalidation must be open-coded by the filesystem; it is + unclear if ``iomap::validity_cookie`` can be reused for this + purpose. + This function must be supplied by the filesystem. + + - ``prepare_ioend``: Enables filesystems to transform the writeback + ioend or perform any other preparatory work before the writeback I/O + is submitted. + This might include pre-write space accounting updates, or installing + a custom ``->bi_end_io`` function for internal purposes, such as + deferring the ioend completion to a workqueue to run metadata update + transactions from process context. + This function is optional. + + - ``discard_folio``: iomap calls this function after ``->map_blocks`` + fails to schedule I/O for any part of a dirty folio. + The function should throw away any reservations that may have been + made for the write. + The folio will be marked clean and an ``-EIO`` recorded in the + pagecache. + Filesystems can use this callback to `remove + <https://lore.kernel.org/all/20201029163313.1766967-1-bfoster@redhat.com/>`_ + delalloc reservations to avoid having delalloc reservations for + clean pagecache. + This function is optional. + +Pagecache Writeback Completion +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To handle the bookkeeping that must happen after disk I/O for writeback +completes, iomap creates chains of ``struct iomap_ioend`` objects that +wrap the ``bio`` that is used to write pagecache data to disk. +By default, iomap finishes writeback ioends by clearing the writeback +bit on the folios attached to the ``ioend``. +If the write failed, it will also set the error bits on the folios and +the address space. +This can happen in interrupt or process context, depending on the +storage device. + +Filesystems that need to update internal bookkeeping (e.g. unwritten +extent conversions) should provide a ``->prepare_ioend`` function to +set ``struct iomap_end::bio::bi_end_io`` to its own function. +This function should call ``iomap_finish_ioends`` after finishing its +own work (e.g. unwritten extent conversion). + +Some filesystems may wish to `amortize the cost of running metadata +transactions +<https://lore.kernel.org/all/20220120034733.221737-1-david@fromorbit.com/>`_ +for post-writeback updates by batching them. +They may also require transactions to run from process context, which +implies punting batches to a workqueue. +iomap ioends contain a ``list_head`` to enable batching. + +Given a batch of ioends, iomap has a few helpers to assist with +amortization: + + * ``iomap_sort_ioends``: Sort all the ioends in the list by file + offset. + + * ``iomap_ioend_try_merge``: Given an ioend that is not in any list and + a separate list of sorted ioends, merge as many of the ioends from + the head of the list into the given ioend. + ioends can only be merged if the file range and storage addresses are + contiguous; the unwritten and shared status are the same; and the + write I/O outcome is the same. + The merged ioends become their own list. + + * ``iomap_finish_ioends``: Finish an ioend that possibly has other + ioends linked to it. + +Direct I/O +========== + +In Linux, direct I/O is defined as file I/O that is issued directly to +storage, bypassing the pagecache. +The ``iomap_dio_rw`` function implements O_DIRECT (direct I/O) reads and +writes for files. + +.. code-block:: c + + ssize_t iomap_dio_rw(struct kiocb *iocb, struct iov_iter *iter, + const struct iomap_ops *ops, + const struct iomap_dio_ops *dops, + unsigned int dio_flags, void *private, + size_t done_before); + +The filesystem can provide the ``dops`` parameter if it needs to perform +extra work before or after the I/O is issued to storage. +The ``done_before`` parameter tells the how much of the request has +already been transferred. +It is used to continue a request asynchronously when `part of the +request +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=c03098d4b9ad76bca2966a8769dcfe59f7f85103>`_ +has already been completed synchronously. + +The ``done_before`` parameter should be set if writes for the ``iocb`` +have been initiated prior to the call. +The direction of the I/O is determined from the ``iocb`` passed in. + +The ``dio_flags`` argument can be set to any combination of the +following values: + + * ``IOMAP_DIO_FORCE_WAIT``: Wait for the I/O to complete even if the + kiocb is not synchronous. + + * ``IOMAP_DIO_OVERWRITE_ONLY``: Perform a pure overwrite for this range + or fail with ``-EAGAIN``. + This can be used by filesystems with complex unaligned I/O + write paths to provide an optimised fast path for unaligned writes. + If a pure overwrite can be performed, then serialisation against + other I/Os to the same filesystem block(s) is unnecessary as there is + no risk of stale data exposure or data loss. + If a pure overwrite cannot be performed, then the filesystem can + perform the serialisation steps needed to provide exclusive access + to the unaligned I/O range so that it can perform allocation and + sub-block zeroing safely. + Filesystems can use this flag to try to reduce locking contention, + but a lot of `detailed checking + <https://lore.kernel.org/linux-ext4/20230314130759.642710-1-bfoster@redhat.com/>`_ + is required to do it `correctly + <https://lore.kernel.org/linux-ext4/20230810165559.946222-1-bfoster@redhat.com/>`_. + + * ``IOMAP_DIO_PARTIAL``: If a page fault occurs, return whatever + progress has already been made. + The caller may deal with the page fault and retry the operation. + If the caller decides to retry the operation, it should pass the + accumulated return values of all previous calls as the + ``done_before`` parameter to the next call. + +These ``struct kiocb`` flags are significant for direct I/O with iomap: + + * ``IOCB_NOWAIT``: Turns on ``IOMAP_NOWAIT``. + + * ``IOCB_SYNC``: Ensure that the device has persisted data to disk + before completing the call. + In the case of pure overwrites, the I/O may be issued with FUA + enabled. + + * ``IOCB_HIPRI``: Poll for I/O completion instead of waiting for an + interrupt. + Only meaningful for asynchronous I/O, and only if the entire I/O can + be issued as a single ``struct bio``. + + * ``IOCB_DIO_CALLER_COMP``: Try to run I/O completion from the caller's + process context. + See ``linux/fs.h`` for more details. + +Filesystems should call ``iomap_dio_rw`` from ``->read_iter`` and +``->write_iter``, and set ``FMODE_CAN_ODIRECT`` in the ``->open`` +function for the file. +They should not set ``->direct_IO``, which is deprecated. + +If a filesystem wishes to perform its own work before direct I/O +completion, it should call ``__iomap_dio_rw``. +If its return value is not an error pointer or a NULL pointer, the +filesystem should pass the return value to ``iomap_dio_complete`` after +finishing its internal work. + +Return Values +------------- + +``iomap_dio_rw`` can return one of the following: + + * A non-negative number of bytes transferred. + + * ``-ENOTBLK``: Fall back to buffered I/O. + iomap itself will return this value if it cannot invalidate the page + cache before issuing the I/O to storage. + The ``->iomap_begin`` or ``->iomap_end`` functions may also return + this value. + + * ``-EIOCBQUEUED``: The asynchronous direct I/O request has been + queued and will be completed separately. + + * Any of the other negative error codes. + +Direct Reads +------------ + +A direct I/O read initiates a read I/O from the storage device to the +caller's buffer. +Dirty parts of the pagecache are flushed to storage before initiating +the read io. +The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DIRECT`` with +any combination of the following enhancements: + + * ``IOMAP_NOWAIT``, as defined previously. + +Callers commonly hold ``i_rwsem`` in shared mode before calling this +function. + +Direct Writes +------------- + +A direct I/O write initiates a write I/O to the storage device from the +caller's buffer. +Dirty parts of the pagecache are flushed to storage before initiating +the write io. +The pagecache is invalidated both before and after the write io. +The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DIRECT | +IOMAP_WRITE`` with any combination of the following enhancements: + + * ``IOMAP_NOWAIT``, as defined previously. + + * ``IOMAP_OVERWRITE_ONLY``: Allocating blocks and zeroing partial + blocks is not allowed. + The entire file range must map to a single written or unwritten + extent. + The file I/O range must be aligned to the filesystem block size + if the mapping is unwritten and the filesystem cannot handle zeroing + the unaligned regions without exposing stale contents. + +Callers commonly hold ``i_rwsem`` in shared or exclusive mode before +calling this function. + +``struct iomap_dio_ops:`` +------------------------- +.. code-block:: c + + struct iomap_dio_ops { + void (*submit_io)(const struct iomap_iter *iter, struct bio *bio, + loff_t file_offset); + int (*end_io)(struct kiocb *iocb, ssize_t size, int error, + unsigned flags); + struct bio_set *bio_set; + }; + +The fields of this structure are as follows: + + - ``submit_io``: iomap calls this function when it has constructed a + ``struct bio`` object for the I/O requested, and wishes to submit it + to the block device. + If no function is provided, ``submit_bio`` will be called directly. + Filesystems that would like to perform additional work before (e.g. + data replication for btrfs) should implement this function. + + - ``end_io``: This is called after the ``struct bio`` completes. + This function should perform post-write conversions of unwritten + extent mappings, handle write failures, etc. + The ``flags`` argument may be set to a combination of the following: + + * ``IOMAP_DIO_UNWRITTEN``: The mapping was unwritten, so the ioend + should mark the extent as written. + + * ``IOMAP_DIO_COW``: Writing to the space in the mapping required a + copy on write operation, so the ioend should switch mappings. + + - ``bio_set``: This allows the filesystem to provide a custom bio_set + for allocating direct I/O bios. + This enables filesystems to `stash additional per-bio information + <https://lore.kernel.org/all/20220505201115.937837-3-hch@lst.de/>`_ + for private use. + If this field is NULL, generic ``struct bio`` objects will be used. + +Filesystems that want to perform extra work after an I/O completion +should set a custom ``->bi_end_io`` function via ``->submit_io``. +Afterwards, the custom endio function must call +``iomap_dio_bio_end_io`` to finish the direct I/O. + +DAX I/O +======= + +Some storage devices can be directly mapped as memory. +These devices support a new access mode known as "fsdax" that allows +loads and stores through the CPU and memory controller. + +fsdax Reads +----------- + +A fsdax read performs a memcpy from storage device to the caller's +buffer. +The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DAX`` with any +combination of the following enhancements: + + * ``IOMAP_NOWAIT``, as defined previously. + +Callers commonly hold ``i_rwsem`` in shared mode before calling this +function. + +fsdax Writes +------------ + +A fsdax write initiates a memcpy to the storage device from the caller's +buffer. +The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DAX | +IOMAP_WRITE`` with any combination of the following enhancements: + + * ``IOMAP_NOWAIT``, as defined previously. + + * ``IOMAP_OVERWRITE_ONLY``: The caller requires a pure overwrite to be + performed from this mapping. + This requires the filesystem extent mapping to already exist as an + ``IOMAP_MAPPED`` type and span the entire range of the write I/O + request. + If the filesystem cannot map this request in a way that allows the + iomap infrastructure to perform a pure overwrite, it must fail the + mapping operation with ``-EAGAIN``. + +Callers commonly hold ``i_rwsem`` in exclusive mode before calling this +function. + +fsdax mmap Faults +~~~~~~~~~~~~~~~~~ + +The ``dax_iomap_fault`` function handles read and write faults to fsdax +storage. +For a read fault, ``IOMAP_DAX | IOMAP_FAULT`` will be passed as the +``flags`` argument to ``->iomap_begin``. +For a write fault, ``IOMAP_DAX | IOMAP_FAULT | IOMAP_WRITE`` will be +passed as the ``flags`` argument to ``->iomap_begin``. + +Callers commonly hold the same locks as they do to call their iomap +pagecache counterparts. + +fsdax Truncation, fallocate, and Unsharing +------------------------------------------ + +For fsdax files, the following functions are provided to replace their +iomap pagecache I/O counterparts. +The ``flags`` argument to ``->iomap_begin`` are the same as the +pagecache counterparts, with ``IOMAP_DAX`` added. + + * ``dax_file_unshare`` + * ``dax_zero_range`` + * ``dax_truncate_page`` + +Callers commonly hold the same locks as they do to call their iomap +pagecache counterparts. + +fsdax Deduplication +------------------- + +Filesystems implementing the ``FIDEDUPERANGE`` ioctl must call the +``dax_remap_file_range_prep`` function with their own iomap read ops. + +Seeking Files +============= + +iomap implements the two iterating whence modes of the ``llseek`` system +call. + +SEEK_DATA +--------- + +The ``iomap_seek_data`` function implements the SEEK_DATA "whence" value +for llseek. +``IOMAP_REPORT`` will be passed as the ``flags`` argument to +``->iomap_begin``. + +For unwritten mappings, the pagecache will be searched. +Regions of the pagecache with a folio mapped and uptodate fsblocks +within those folios will be reported as data areas. + +Callers commonly hold ``i_rwsem`` in shared mode before calling this +function. + +SEEK_HOLE +--------- + +The ``iomap_seek_hole`` function implements the SEEK_HOLE "whence" value +for llseek. +``IOMAP_REPORT`` will be passed as the ``flags`` argument to +``->iomap_begin``. + +For unwritten mappings, the pagecache will be searched. +Regions of the pagecache with no folio mapped, or a !uptodate fsblock +within a folio will be reported as sparse hole areas. + +Callers commonly hold ``i_rwsem`` in shared mode before calling this +function. + +Swap File Activation +==================== + +The ``iomap_swapfile_activate`` function finds all the base-page aligned +regions in a file and sets them up as swap space. +The file will be ``fsync()``'d before activation. +``IOMAP_REPORT`` will be passed as the ``flags`` argument to +``->iomap_begin``. +All mappings must be mapped or unwritten; cannot be dirty or shared, and +cannot span multiple block devices. +Callers must hold ``i_rwsem`` in exclusive mode; this is already +provided by ``swapon``. + +File Space Mapping Reporting +============================ + +iomap implements two of the file space mapping system calls. + +FS_IOC_FIEMAP +------------- + +The ``iomap_fiemap`` function exports file extent mappings to userspace +in the format specified by the ``FS_IOC_FIEMAP`` ioctl. +``IOMAP_REPORT`` will be passed as the ``flags`` argument to +``->iomap_begin``. +Callers commonly hold ``i_rwsem`` in shared mode before calling this +function. + +FIBMAP (deprecated) +------------------- + +``iomap_bmap`` implements FIBMAP. +The calling conventions are the same as for FIEMAP. +This function is only provided to maintain compatibility for filesystems +that implemented FIBMAP prior to conversion. +This ioctl is deprecated; do **not** add a FIBMAP implementation to +filesystems that do not have it. +Callers should probably hold ``i_rwsem`` in shared mode before calling +this function, but this is unclear. diff --git a/Documentation/filesystems/iomap/porting.rst b/Documentation/filesystems/iomap/porting.rst new file mode 100644 index 000000000000..3d49a32c0fff --- /dev/null +++ b/Documentation/filesystems/iomap/porting.rst @@ -0,0 +1,120 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. _iomap_porting: + +.. + Dumb style notes to maintain the author's sanity: + Please try to start sentences on separate lines so that + sentence changes don't bleed colors in diff. + Heading decorations are documented in sphinx.rst. + +======================= +Porting Your Filesystem +======================= + +.. contents:: Table of Contents + :local: + +Why Convert? +============ + +There are several reasons to convert a filesystem to iomap: + + 1. The classic Linux I/O path is not terribly efficient. + Pagecache operations lock a single base page at a time and then call + into the filesystem to return a mapping for only that page. + Direct I/O operations build I/O requests a single file block at a + time. + This worked well enough for direct/indirect-mapped filesystems such + as ext2, but is very inefficient for extent-based filesystems such + as XFS. + + 2. Large folios are only supported via iomap; there are no plans to + convert the old buffer_head path to use them. + + 3. Direct access to storage on memory-like devices (fsdax) is only + supported via iomap. + + 4. Lower maintenance overhead for individual filesystem maintainers. + iomap handles common pagecache related operations itself, such as + allocating, instantiating, locking, and unlocking of folios. + No ->write_begin(), ->write_end() or direct_IO + address_space_operations are required to be implemented by + filesystem using iomap. + +How Do I Convert a Filesystem? +============================== + +First, add ``#include <linux/iomap.h>`` from your source code and add +``select FS_IOMAP`` to your filesystem's Kconfig option. +Build the kernel, run fstests with the ``-g all`` option across a wide +variety of your filesystem's supported configurations to build a +baseline of which tests pass and which ones fail. + +The recommended approach is first to implement ``->iomap_begin`` (and +``->iomap_end`` if necessary) to allow iomap to obtain a read-only +mapping of a file range. +In most cases, this is a relatively trivial conversion of the existing +``get_block()`` function for read-only mappings. +``FS_IOC_FIEMAP`` is a good first target because it is trivial to +implement support for it and then to determine that the extent map +iteration is correct from userspace. +If FIEMAP is returning the correct information, it's a good sign that +other read-only mapping operations will do the right thing. + +Next, modify the filesystem's ``get_block(create = false)`` +implementation to use the new ``->iomap_begin`` implementation to map +file space for selected read operations. +Hide behind a debugging knob the ability to switch on the iomap mapping +functions for selected call paths. +It is necessary to write some code to fill out the bufferhead-based +mapping information from the ``iomap`` structure, but the new functions +can be tested without needing to implement any iomap APIs. + +Once the read-only functions are working like this, convert each high +level file operation one by one to use iomap native APIs instead of +going through ``get_block()``. +Done one at a time, regressions should be self evident. +You *do* have a regression test baseline for fstests, right? +It is suggested to convert swap file activation, ``SEEK_DATA``, and +``SEEK_HOLE`` before tackling the I/O paths. +A likely complexity at this point will be converting the buffered read +I/O path because of bufferheads. +The buffered read I/O paths doesn't need to be converted yet, though the +direct I/O read path should be converted in this phase. + +At this point, you should look over your ``->iomap_begin`` function. +If it switches between large blocks of code based on dispatching of the +``flags`` argument, you should consider breaking it up into +per-operation iomap ops with smaller, more cohesive functions. +XFS is a good example of this. + +The next thing to do is implement ``get_blocks(create == true)`` +functionality in the ``->iomap_begin``/``->iomap_end`` methods. +It is strongly recommended to create separate mapping functions and +iomap ops for write operations. +Then convert the direct I/O write path to iomap, and start running fsx +w/ DIO enabled in earnest on filesystem. +This will flush out lots of data integrity corner case bugs that the new +write mapping implementation introduces. + +Now, convert any remaining file operations to call the iomap functions. +This will get the entire filesystem using the new mapping functions, and +they should largely be debugged and working correctly after this step. + +Most likely at this point, the buffered read and write paths will still +need to be converted. +The mapping functions should all work correctly, so all that needs to be +done is rewriting all the code that interfaces with bufferheads to +interface with iomap and folios. +It is much easier first to get regular file I/O (without any fancy +features like fscrypt, fsverity, compression, or data=journaling) +converted to use iomap. +Some of those fancy features (fscrypt and compression) aren't +implemented yet in iomap. +For unjournalled filesystems that use the pagecache for symbolic links +and directories, you might also try converting their handling to iomap. + +The rest is left as an exercise for the reader, as it will be different +for every filesystem. +If you encounter problems, email the people and lists in +``get_maintainers.pl`` for help. diff --git a/Documentation/filesystems/mount_api.rst b/Documentation/filesystems/mount_api.rst index 9aaf6ef75eb5..317934c9e8fc 100644 --- a/Documentation/filesystems/mount_api.rst +++ b/Documentation/filesystems/mount_api.rst @@ -645,6 +645,8 @@ The members are as follows: fs_param_is_blockdev Blockdev path * Needs lookup fs_param_is_path Path * Needs lookup fs_param_is_fd File descriptor result->int_32 + fs_param_is_uid User ID (u32) result->uid + fs_param_is_gid Group ID (u32) result->gid ======================= ======================= ===================== Note that if the value is of fs_param_is_bool type, fs_parse() will try @@ -678,6 +680,8 @@ The members are as follows: fsparam_bdev() fs_param_is_blockdev fsparam_path() fs_param_is_path fsparam_fd() fs_param_is_fd + fsparam_uid() fs_param_is_uid + fsparam_gid() fs_param_is_gid ======================= =============================================== all of which take two arguments, name string and option number - for @@ -784,8 +788,9 @@ process the parameters it is given. option number (which it returns). If successful, and if the parameter type indicates the result is a - boolean, integer or enum type, the value is converted by this function and - the result stored in result->{boolean,int_32,uint_32,uint_64}. + boolean, integer, enum, uid, or gid type, the value is converted by this + function and the result stored in + result->{boolean,int_32,uint_32,uint_64,uid,gid}. If a match isn't initially made, the key is prefixed with "no" and no value is present then an attempt will be made to look up the key with the diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 7c3a565ffbef..82d142de3461 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -571,6 +571,7 @@ encoded manner. The codes are the following: um userfaultfd missing tracking uw userfaultfd wr-protect tracking ss shadow stack page + sl sealed == ======================================= Note that there is no guarantee that every flag and associated mnemonic will diff --git a/Documentation/hwmon/adm1021.rst b/Documentation/hwmon/adm1021.rst deleted file mode 100644 index 116fb2019956..000000000000 --- a/Documentation/hwmon/adm1021.rst +++ /dev/null @@ -1,153 +0,0 @@ -Kernel driver adm1021 -===================== - -Supported chips: - - * Analog Devices ADM1021 - - Prefix: 'adm1021' - - Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e - - Datasheet: Publicly available at the Analog Devices website - - * Analog Devices ADM1021A/ADM1023 - - Prefix: 'adm1023' - - Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e - - Datasheet: Publicly available at the Analog Devices website - - * Genesys Logic GL523SM - - Prefix: 'gl523sm' - - Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e - - Datasheet: - - * Maxim MAX1617 - - Prefix: 'max1617' - - Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e - - Datasheet: Publicly available at the Maxim website - - * Maxim MAX1617A - - Prefix: 'max1617a' - - Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e - - Datasheet: Publicly available at the Maxim website - - * National Semiconductor LM84 - - Prefix: 'lm84' - - Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e - - Datasheet: Publicly available at the National Semiconductor website - - * Philips NE1617 - - Prefix: 'max1617' (probably detected as a max1617) - - Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e - - Datasheet: Publicly available at the Philips website - - * Philips NE1617A - - Prefix: 'max1617' (probably detected as a max1617) - - Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e - - Datasheet: Publicly available at the Philips website - - * TI THMC10 - - Prefix: 'thmc10' - - Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e - - Datasheet: Publicly available at the TI website - - * Onsemi MC1066 - - Prefix: 'mc1066' - - Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e - - Datasheet: Publicly available at the Onsemi website - - -Authors: - - Frodo Looijaard <frodol@dds.nl>, - - Philip Edelbrock <phil@netroedge.com> - -Module Parameters ------------------ - -* read_only: int - Don't set any values, read only mode - - -Description ------------ - -The chips supported by this driver are very similar. The Maxim MAX1617 is -the oldest; it has the problem that it is not very well detectable. The -MAX1617A solves that. The ADM1021 is a straight clone of the MAX1617A. -Ditto for the THMC10. From here on, we will refer to all these chips as -ADM1021-clones. - -The ADM1021 and MAX1617A reports a die code, which is a sort of revision -code. This can help us pinpoint problems; it is not very useful -otherwise. - -ADM1021-clones implement two temperature sensors. One of them is internal, -and measures the temperature of the chip itself; the other is external and -is realised in the form of a transistor-like device. A special alarm -indicates whether the remote sensor is connected. - -Each sensor has its own low and high limits. When they are crossed, the -corresponding alarm is set and remains on as long as the temperature stays -out of range. Temperatures are measured in degrees Celsius. Measurements -are possible between -65 and +127 degrees, with a resolution of one degree. - -If an alarm triggers, it will remain triggered until the hardware register -is read at least once. This means that the cause for the alarm may already -have disappeared! - -This driver only updates its values each 1.5 seconds; reading it more often -will do no harm, but will return 'old' values. It is possible to make -ADM1021-clones do faster measurements, but there is really no good reason -for that. - - -Netburst-based Xeon support ---------------------------- - -Some Xeon processors based on the Netburst (early Pentium 4, from 2001 to -2003) microarchitecture had real MAX1617, ADM1021, or compatible chips -within them, with two temperature sensors. Other Xeon processors of this -era (with 400 MHz FSB) had chips with only one temperature sensor. - -If you have such an old Xeon, and you get two valid temperatures when -loading the adm1021 module, then things are good. - -If nothing happens when loading the adm1021 module, and you are certain -that your specific Xeon processor model includes compatible sensors, you -will have to explicitly instantiate the sensor chips from user-space. See -method 4 in Documentation/i2c/instantiating-devices.rst. Possible slave -addresses are 0x18, 0x1a, 0x29, 0x2b, 0x4c, or 0x4e. It is likely that -only temp2 will be correct and temp1 will have to be ignored. - -Previous generations of the Xeon processor (based on Pentium II/III) -didn't have these sensors. Next generations of Xeon processors (533 MHz -FSB and faster) lost them, until the Core-based generation which -introduced integrated digital thermal sensors. These are supported by -the coretemp driver. diff --git a/Documentation/hwmon/amc6821.rst b/Documentation/hwmon/amc6821.rst index 5ddb2849da90..dbd544cd1160 100644 --- a/Documentation/hwmon/amc6821.rst +++ b/Documentation/hwmon/amc6821.rst @@ -47,13 +47,18 @@ fan1_input ro tachometer speed fan1_min rw " fan1_max rw " fan1_fault ro " -fan1_div rw Fan divisor can be either 2 or 4. +fan1_pulses rw Pulses per revolution can be either 2 or 4. +fan1_target rw Target fan speed, to be used with pwm1_enable + mode 4. pwm1 rw pwm1 pwm1_enable rw regulator mode, 1=open loop, 2=fan controlled by remote temperature, 3=fan controlled by combination of the on-chip temperature and remote-sensor temperature, + 4=fan controlled by target rpm set with + fan1_target attribute. +pwm1_mode rw Fan duty control mode (0=DC, 1=PWM) pwm1_auto_channels_temp ro 1 if pwm_enable==2, 3 if pwm_enable==3 pwm1_auto_point1_pwm ro Hardwired to 0, shared for both temperature channels. diff --git a/Documentation/hwmon/asus_ec_sensors.rst b/Documentation/hwmon/asus_ec_sensors.rst index 0bf99ba406dd..ca38922f4ec5 100644 --- a/Documentation/hwmon/asus_ec_sensors.rst +++ b/Documentation/hwmon/asus_ec_sensors.rst @@ -8,6 +8,7 @@ Supported boards: * PRIME X570-PRO * Pro WS X570-ACE * ProArt X570-CREATOR WIFI + * ProArt X670E-CREATOR WIFI * ProArt B550-CREATOR * ROG CROSSHAIR VIII DARK HERO * ROG CROSSHAIR VIII HERO (WI-FI) diff --git a/Documentation/hwmon/corsair-cpro.rst b/Documentation/hwmon/corsair-cpro.rst index 751f95476b57..15077203a2f8 100644 --- a/Documentation/hwmon/corsair-cpro.rst +++ b/Documentation/hwmon/corsair-cpro.rst @@ -39,3 +39,11 @@ fan[1-6]_target Sets fan speed target rpm. pwm[1-6] Sets the fan speed. Values from 0-255. Can only be read if pwm was set directly. ======================= ===================================================================== + +Debugfs entries +--------------- + +======================= =================== +firmware_version Firmware version +bootloader_version Bootloader version +======================= =================== diff --git a/Documentation/hwmon/corsair-psu.rst b/Documentation/hwmon/corsair-psu.rst index 16db34d464dd..7ed794087f84 100644 --- a/Documentation/hwmon/corsair-psu.rst +++ b/Documentation/hwmon/corsair-psu.rst @@ -15,11 +15,11 @@ Supported devices: Corsair HX850i - Corsair HX1000i (Series 2022 and 2023) + Corsair HX1000i (Legacy and Series 2023) - Corsair HX1200i + Corsair HX1200i (Legacy and Series 2023) - Corsair HX1500i (Series 2022 and 2023) + Corsair HX1500i (Legacy and Series 2023) Corsair RM550i diff --git a/Documentation/hwmon/cros_ec_hwmon.rst b/Documentation/hwmon/cros_ec_hwmon.rst new file mode 100644 index 000000000000..47ecae983bdb --- /dev/null +++ b/Documentation/hwmon/cros_ec_hwmon.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver cros_ec_hwmon +=========================== + +Supported chips: + + * ChromeOS embedded controllers. + + Prefix: 'cros_ec' + + Addresses scanned: - + +Author: + + - Thomas Weißschuh <linux@weissschuh.net> + +Description +----------- + +This driver implements support for hardware monitoring commands exposed by the +ChromeOS embedded controller used in Chromebooks and other devices. + +The channel labels exposed via hwmon are retrieved from the EC itself. + +Fan and temperature readings are supported. diff --git a/Documentation/hwmon/dell-smm-hwmon.rst b/Documentation/hwmon/dell-smm-hwmon.rst index 977263cb57a8..74905675d71f 100644 --- a/Documentation/hwmon/dell-smm-hwmon.rst +++ b/Documentation/hwmon/dell-smm-hwmon.rst @@ -360,6 +360,8 @@ Firmware Bug Affected Machines ======================================================= ================= Reading of fan states return spurious errors. Precision 490 + OptiPlex 7060 + Reading of fan types causes erratic fan behaviour. Studio XPS 8000 Studio XPS 8100 diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index 03d313af469a..913c11390a45 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -25,7 +25,6 @@ Hardware Monitoring Kernel Drivers acpi_power_meter ad7314 adc128d818 - adm1021 adm1025 adm1026 adm1031 @@ -58,6 +57,7 @@ Hardware Monitoring Kernel Drivers coretemp corsair-cpro corsair-psu + cros_ec_hwmon da9052 da9055 dell-smm-hwmon @@ -154,7 +154,6 @@ Hardware Monitoring Kernel Drivers max34440 max6620 max6639 - max6642 max6650 max6697 max8688 @@ -165,9 +164,13 @@ Hardware Monitoring Kernel Drivers mlxreg-fan mp2856 mp2888 + mp2891 mp2975 + mp2993 mp5023 + mp5920 mp5990 + mp9941 mpq8785 nct6683 nct6775 @@ -215,6 +218,7 @@ Hardware Monitoring Kernel Drivers smsc47m192 smsc47m1 sparx5-temp + spd5118 stpddc60 surface_fan sy7636a-hwmon diff --git a/Documentation/hwmon/max31827.rst b/Documentation/hwmon/max31827.rst index 44ab9dc064cb..9c11a9518c67 100644 --- a/Documentation/hwmon/max31827.rst +++ b/Documentation/hwmon/max31827.rst @@ -131,7 +131,14 @@ The Fault Queue bits select how many consecutive temperature faults must occur before overtemperature or undertemperature faults are indicated in the corresponding status bits. -Notes ------ +PEC Support +----------- + +When reading a register value, the PEC byte is computed and sent by the chip. + +PEC on word data transaction respresents a signifcant increase in bandwitdh +usage (+33% for both write and reads) in normal conditions. -PEC is not implemented. +Since this operation implies there will be an extra delay to each +transaction, PEC can be disabled or enabled through sysfs. +Just write 1 to the "pec" file for enabling PEC and 0 for disabling it. diff --git a/Documentation/hwmon/max6642.rst b/Documentation/hwmon/max6642.rst deleted file mode 100644 index 7e5b7d4f9492..000000000000 --- a/Documentation/hwmon/max6642.rst +++ /dev/null @@ -1,27 +0,0 @@ -Kernel driver max6642 -===================== - -Supported chips: - - * Maxim MAX6642 - - Prefix: 'max6642' - - Addresses scanned: I2C 0x48-0x4f - - Datasheet: Publicly available at the Maxim website - - http://datasheets.maxim-ic.com/en/ds/MAX6642.pdf - -Authors: - - Per Dalen <per.dalen@appeartv.com> - -Description ------------ - -The MAX6642 is a digital temperature sensor. It senses its own temperature as -well as the temperature on one external diode. - -All temperature values are given in degrees Celsius. Resolution -is 0.25 degree for the local temperature and for the remote temperature. diff --git a/Documentation/hwmon/mp2891.rst b/Documentation/hwmon/mp2891.rst new file mode 100644 index 000000000000..55944d1b5457 --- /dev/null +++ b/Documentation/hwmon/mp2891.rst @@ -0,0 +1,179 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver mp2891 +==================== + +Supported chips: + + * MPS mp2891 + + Prefix: 'mp2891' + + * Datasheet + + Publicly available at the MPS website : https://www.monolithicpower.com/en/mp2891.html + +Author: + + Noah Wang <noahwang.wang@outlook.com> + +Description +----------- + +This driver implements support for Monolithic Power Systems, Inc. (MPS) +MP2891 Multi-phase Digital VR Controller. + +Device compliant with: + +- PMBus rev 1.3 interface. + +Device supports direct and linear format for reading input voltage, +output voltage, input current, output current, input power, output +power, and temperature. + +The driver exports the following attributes via the 'sysfs' files +for input voltage: + +**in1_input** + +**in1_label** + +**in1_crit** + +**in1_crit_alarm** + +**in1_lcrit** + +**in1_lcrit_alarm** + +**in1_min** + +**in1_min_alarm** + +The driver provides the following attributes for output voltage: + +**in2_input** + +**in2_label** + +**in2_crit** + +**in2_crit_alarm** + +**in2_lcrit** + +**in2_lcrit_alarm** + +**in2_min** + +**in2_min_alarm** + +**in3_input** + +**in3_label** + +**in3_crit** + +**in3_crit_alarm** + +**in3_lcrit** + +**in3_lcrit_alarm** + +**in3_min** + +**in3_min_alarm** + +The driver provides the following attributes for input current: + +**curr1_input** + +**curr1_label** + +**curr1_max** + +**curr1_max_alarm** + +**curr2_input** + +**curr2_label** + +**curr2_max** + +**curr2_max_alarm** + +The driver provides the following attributes for output current: + +**curr3_input** + +**curr3_label** + +**curr3_crit** + +**curr3_crit_alarm** + +**curr3_max** + +**curr3_max_alarm** + +**curr4_input** + +**curr4_label** + +**curr4_crit** + +**curr4_crit_alarm** + +**curr4_max** + +**curr4_max_alarm** + +The driver provides the following attributes for input power: + +**power1_input** + +**power1_label** + +**power1_max** + +**power1_alarm** + +**power2_input** + +**power2_label** + +**power2_max** + +**power2_alarm** + +The driver provides the following attributes for output power: + +**power3_input** + +**power3_label** + +**power4_input** + +**power4_label** + +The driver provides the following attributes for temperature: + +**temp1_input** + +**temp1_crit** + +**temp1_crit_alarm** + +**temp1_max** + +**temp1_max_alarm** + +**temp2_input** + +**temp2_crit** + +**temp2_crit_alarm** + +**temp2_max** + +**temp2_max_alarm** diff --git a/Documentation/hwmon/mp2993.rst b/Documentation/hwmon/mp2993.rst new file mode 100644 index 000000000000..7a4fe0d946e0 --- /dev/null +++ b/Documentation/hwmon/mp2993.rst @@ -0,0 +1,150 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver mp2993 +==================== + +Supported chips: + + * MPS mp2993 + + Prefix: 'mp2993' + + * Datasheet + https://scnbwymvp-my.sharepoint.com/:f:/g/personal/admin_scnbwy_com/Eth4kX1_J1hMsaASHiOYL4QBHU5a75r-tRfLKbHnJFdKLQ?e=vxj3DF + +Author: + + Noah Wang <noahwang.wang@outlook.com> + +Description +----------- + +This driver implements support for Monolithic Power Systems, Inc. (MPS) +MP2993 Dual Loop Digital Multi-phase Controller. + +Device compliant with: + +- PMBus rev 1.3 interface. + +The driver exports the following attributes via the 'sysfs' files +for input voltage: + +**in1_input** + +**in1_label** + +**in1_crit** + +**in1_crit_alarm** + +**in1_lcrit** + +**in1_lcrit_alarm** + +**in1_max** + +**in1_max_alarm** + +**in1_min** + +**in1_min_alarm** + +The driver provides the following attributes for output voltage: + +**in2_input** + +**in2_label** + +**in2_crit** + +**in2_crit_alarm** + +**in2_lcrit** + +**in2_lcrit_alarm** + +**in3_input** + +**in3_label** + +**in3_crit** + +**in3_crit_alarm** + +**in3_lcrit** + +**in3_lcrit_alarm** + +The driver provides the following attributes for input current: + +**curr1_input** + +**curr1_label** + +**curr1_max** + +**curr1_max_alarm** + +The driver provides the following attributes for output current: + +**curr2_input** + +**curr2_label** + +**curr2_crit** + +**curr2_crit_alarm** + +**curr2_max** + +**curr2_max_alarm** + +**curr3_input** + +**curr3_label** + +**curr3_crit** + +**curr3_crit_alarm** + +**curr3_max** + +**curr3_max_alarm** + +The driver provides the following attributes for input power: + +**power1_input** + +**power1_label** + +The driver provides the following attributes for output power: + +**power2_input** + +**power2_label** + +**power3_input** + +**power3_label** + +The driver provides the following attributes for temperature: + +**temp1_input** + +**temp1_crit** + +**temp1_crit_alarm** + +**temp1_max** + +**temp1_max_alarm** + +**temp2_input** + +**temp2_crit** + +**temp2_crit_alarm** + +**temp2_max** + +**temp2_max_alarm** diff --git a/Documentation/hwmon/mp5920.rst b/Documentation/hwmon/mp5920.rst new file mode 100644 index 000000000000..98946e7cf54e --- /dev/null +++ b/Documentation/hwmon/mp5920.rst @@ -0,0 +1,91 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver mp5920 +==================== + +Supported chips: + + * MPS MP5920 + + Prefix: 'mp5920' + + * Datasheet + + Publicly available at the MPS website : https://www.monolithicpower.com/en/mp5920.html + +Authors: + + Tony Ao <tony_ao@wiwynn.com> + Alex Vdovydchenko <xzeol@yahoo.com> + +Description +----------- + +This driver implements support for Monolithic Power Systems, Inc. (MPS) +MP5920 Hot-Swap Controller. + +Device compliant with: + +- PMBus rev 1.3 interface. + +Device supports direct and linear format for reading input voltage, +output voltage, output current, input power and temperature. + +The driver exports the following attributes via the 'sysfs' files +for input voltage: + +**in1_input** + +**in1_label** + +**in1_rated_max** + +**in1_rated_min** + +**in1_crit** + +**in1_alarm** + +The driver provides the following attributes for output voltage: + +**in2_input** + +**in2_label** + +**in2_rated_max** + +**in2_rated_min** + +**in2_alarm** + +The driver provides the following attributes for output current: + +**curr1_input** + +**curr1_label** + +**curr1_crit** + +**curr1_alarm** + +**curr1_rated_max** + +The driver provides the following attributes for input power: + +**power1_input** + +**power1_label** + +**power1_max** + +**power1_rated_max** + +The driver provides the following attributes for temperature: + +**temp1_input** + +**temp1_max** + +**temp1_crit** + +**temp1_alarm** diff --git a/Documentation/hwmon/mp9941.rst b/Documentation/hwmon/mp9941.rst new file mode 100644 index 000000000000..1274fa20e256 --- /dev/null +++ b/Documentation/hwmon/mp9941.rst @@ -0,0 +1,92 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver mp9941 +==================== + +Supported chips: + + * MPS mp9941 + + Prefix: 'mp9941' + + * Datasheet + https://scnbwymvp-my.sharepoint.com/:f:/g/personal/admin_scnbwy_com/Eth4kX1_J1hMsaASHiOYL4QBHU5a75r-tRfLKbHnJFdKLQ?e=vxj3DF + +Author: + + Noah Wang <noahwang.wang@outlook.com> + +Description +----------- + +This driver implements support for Monolithic Power Systems, Inc. (MPS) +MP9941 digital step-down converter. + +Device compliant with: + +- PMBus rev 1.3 interface. + +The driver exports the following attributes via the 'sysfs' files +for input voltage: + +**in1_input** + +**in1_label** + +**in1_crit** + +**in1_crit_alarm** + +The driver provides the following attributes for output voltage: + +**in2_input** + +**in2_label** + +**in2_lcrit** + +**in2_lcrit_alarm** + +**in2_rated_max** + +**in2_rated_min** + +The driver provides the following attributes for input current: + +**curr1_input** + +**curr1_label** + +**curr1_max** + +**curr1_max_alarm** + +The driver provides the following attributes for output current: + +**curr2_input** + +**curr2_label** + +The driver provides the following attributes for input power: + +**power1_input** + +**power1_label** + +The driver provides the following attributes for output power: + +**power2_input** + +**power2_label** + +The driver provides the following attributes for temperature: + +**temp1_input** + +**temp1_crit** + +**temp1_crit_alarm** + +**temp1_max** + +**temp1_max_alarm** diff --git a/Documentation/hwmon/spd5118.rst b/Documentation/hwmon/spd5118.rst new file mode 100644 index 000000000000..ef7338f46575 --- /dev/null +++ b/Documentation/hwmon/spd5118.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver spd5118 +===================== + +Supported chips: + + * SPD5118 (JEDEC JESD300) compliant temperature sensor chips + + JEDEC standard download: + https://www.jedec.org/standards-documents/docs/jesd300-5b01 + (account required) + + + Prefix: 'spd5118' + + Addresses scanned: I2C 0x50 - 0x57 + +Author: + Guenter Roeck <linux@roeck-us.net> + + +Description +----------- + +This driver implements support for SPD5118 (JEDEC JESD300) compliant temperature +sensors, which are used on many DDR5 memory modules. Some systems use the sensor +to prevent memory overheating by automatically throttling the memory controller. + +The driver auto-detects SPD5118 compliant chips, but can also be instantiated +using devicetree/firmware nodes. + +A SPD5118 compliant chip supports a single temperature sensor. Critical minimum, +minimum, maximum, and critical temperature can be configured. There are alarms +for low critical, low, high, and critical thresholds. + + +Hardware monitoring sysfs entries +--------------------------------- + +======================= ================================== +temp1_input Temperature (RO) +temp1_lcrit Low critical high temperature (RW) +temp1_min Minimum temperature (RW) +temp1_max Maximum temperature (RW) +temp1_crit Critical high temperature (RW) + +temp1_lcrit_alarm Temperature low critical alarm +temp1_min_alarm Temperature low alarm +temp1_max_alarm Temperature high alarm +temp1_crit_alarm Temperature critical alarm +======================= ================================== + +Alarm attributes are sticky until read and will be cleared afterwards +unless the alarm condition still applies. + + +SPD (Serial Presence Detect) support +------------------------------------ + +The driver also supports reading the SPD NVRAM on SPD5118 compatible chips. +SPD data is available from the 'eeprom' binary attribute file attached to the +chip's I2C device. diff --git a/Documentation/kbuild/modules.rst b/Documentation/kbuild/modules.rst index a1f3eb7a43e2..131863142cbb 100644 --- a/Documentation/kbuild/modules.rst +++ b/Documentation/kbuild/modules.rst @@ -128,7 +128,7 @@ executed to make module versioning work. modules_install Install the external module(s). The default location is - /lib/modules/<kernel_release>/extra/, but a prefix may + /lib/modules/<kernel_release>/updates/, but a prefix may be added with INSTALL_MOD_PATH (discussed in section 5). clean @@ -417,7 +417,7 @@ directory: And external modules are installed in: - /lib/modules/$(KERNELRELEASE)/extra/ + /lib/modules/$(KERNELRELEASE)/updates/ 5.1 INSTALL_MOD_PATH -------------------- @@ -438,10 +438,10 @@ And external modules are installed in: ------------------- External modules are by default installed to a directory under - /lib/modules/$(KERNELRELEASE)/extra/, but you may wish to + /lib/modules/$(KERNELRELEASE)/updates/, but you may wish to locate modules for a specific functionality in a separate directory. For this purpose, use INSTALL_MOD_DIR to specify an - alternative name to "extra.":: + alternative name to "updates.":: $ make INSTALL_MOD_DIR=gandalf -C $KDIR \ M=$PWD modules_install diff --git a/Documentation/netlink/specs/ethtool.yaml b/Documentation/netlink/specs/ethtool.yaml index 00dc61358be8..4510e8d1adcb 100644 --- a/Documentation/netlink/specs/ethtool.yaml +++ b/Documentation/netlink/specs/ethtool.yaml @@ -1603,7 +1603,7 @@ operations: attributes: - header reply: - attributes: &pse + attributes: - header - podl-pse-admin-state - podl-pse-admin-control @@ -1620,7 +1620,10 @@ operations: do: request: - attributes: *pse + attributes: + - header + - podl-pse-admin-control + - c33-pse-admin-control - name: rss-get doc: Get RSS params. diff --git a/Documentation/networking/devlink/devlink-region.rst b/Documentation/networking/devlink/devlink-region.rst index 9232cd7da301..5d0b68f752c0 100644 --- a/Documentation/networking/devlink/devlink-region.rst +++ b/Documentation/networking/devlink/devlink-region.rst @@ -49,7 +49,7 @@ example usage $ devlink region show [ DEV/REGION ] $ devlink region del DEV/REGION snapshot SNAPSHOT_ID $ devlink region dump DEV/REGION [ snapshot SNAPSHOT_ID ] - $ devlink region read DEV/REGION [ snapshot SNAPSHOT_ID ] address ADDRESS length length + $ devlink region read DEV/REGION [ snapshot SNAPSHOT_ID ] address ADDRESS length LENGTH # Show all of the exposed regions with region sizes: $ devlink region show diff --git a/Documentation/translations/zh_CN/driver-api/gpio/index.rst b/Documentation/translations/zh_CN/driver-api/gpio/index.rst index 9a6a14162a6c..e4d54724a1b5 100644 --- a/Documentation/translations/zh_CN/driver-api/gpio/index.rst +++ b/Documentation/translations/zh_CN/driver-api/gpio/index.rst @@ -18,8 +18,6 @@ :caption: 目录 :maxdepth: 2 - legacy - Todolist: * intro diff --git a/Documentation/translations/zh_CN/driver-api/gpio/legacy.rst b/Documentation/translations/zh_CN/driver-api/gpio/legacy.rst deleted file mode 100644 index 0faf042001d2..000000000000 --- a/Documentation/translations/zh_CN/driver-api/gpio/legacy.rst +++ /dev/null @@ -1,618 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. include:: ../../disclaimer-zh_CN.rst - -:Original: Documentation/driver-api/gpio/legacy.rst - -:翻译: - - 傅炜 Fu Wei <tekkamanninja@gmail.com> - 司延腾 Yanteng Si <siyanteng@loongson.cn> - -:校译: - - -传统GPIO接口 -============ - -本文档概述了Linux下的GPIO访问公约。 - -这些函数以 gpio_* 作为前缀。其他的函数不允许使用这样的前缀或相关的 -__gpio_* 前缀。 - - -什么是GPIO？ -============ -"通用输入/输出口"(GPIO)是一个灵活的由软件控制的数字信号。他们可 -由多种芯片提供,且对于从事嵌入式和定制硬件的 Linux 开发者来说是 -比较熟悉。每个GPIO 都代表一个连接到特定引脚或球栅阵列(BGA)封装中 -“球珠”的一个位。电路板原理图显示了 GPIO 与外部硬件的连接关系。 -驱动可以编写成通用代码，以使板级启动代码可传递引脚配置数据给驱动。 - -片上系统 (SOC) 处理器对 GPIO 有很大的依赖。在某些情况下,每个 -非专用引脚都可配置为 GPIO,且大多数芯片都最少有一些 GPIO。 -可编程逻辑器件(类似 FPGA) 可以方便地提供 GPIO。像电源管理和 -音频编解码器这样的多功能芯片经常留有一些这样的引脚来帮助那些引脚 -匮乏的 SOC。同时还有通过 I2C 或 SPI 串行总线连接的“GPIO扩展器” -芯片。大多数 PC 的南桥有一些拥有 GPIO 能力的引脚 (只有BIOS -固件才知道如何使用他们)。 - -GPIO 的实际功能因系统而异。通常用法有: - - - 输出值可写 (高电平=1，低电平=0)。一些芯片也有如何驱动这些值的选项, - 例如只允许输出一个值、支持“线与”及其他取值类似的模式(值得注意的是 - “开漏”信号) - - - 输入值可读(1、0)。一些芯片支持引脚在配置为“输出”时回读，这对于类似 - “线与”的情况(以支持双向信号)是非常有用的。GPIO 控制器可能有输入 - 去毛刺/消抖逻辑,这有时需要软件控制。 - - - 输入通常可作为 IRQ 信号,一般是沿触发,但有时是电平触发。这样的 IRQ - 可能配置为系统唤醒事件,以将系统从低功耗状态下唤醒。 - - - 通常一个 GPIO 根据不同产品电路板的需求,可以配置为输入或输出,也有仅 - 支持单向的。 - - - 大部分 GPIO 可以在持有自旋锁时访问,但是通常由串行总线扩展的 GPIO - 不允许持有自旋锁。但某些系统也支持这种类型。 - -对于给定的电路板,每个 GPIO 都用于某个特定的目的,如监控 MMC/SD 卡的 -插入/移除、检测卡的写保护状态、驱动 LED、配置收发器、模拟串行总线、 -复位硬件看门狗、感知开关状态等等。 - - -GPIO 公约 -========= -注意,这个叫做“公约”，因为这不是强制性的，不遵循这个公约是无伤大雅的， -因为此时可移植性并不重要。GPIO 常用于板级特定的电路逻辑,甚至可能 -随着电路板的版本而改变，且不可能在不同走线的电路板上使用。仅有在少数 -功能上才具有可移植性，其他功能是平台特定。这也是由于“胶合”的逻辑造成的。 - -此外，这不需要任何的执行框架，只是一个接口。某个平台可能通过一个简单地 -访问芯片寄存器的内联函数来实现它，其他平台可能通过委托一系列不同的GPIO -控制器的抽象函数来实现它。(有一些可选的代码能支持这种策略的实现,本文档 -后面会介绍，但作为 GPIO 接口的客户端驱动程序必须与它的实现无关。) - -也就是说,如果在他们的平台上支持这个公约，驱动应尽可能的使用它。同时，平台 -必须在 Kconfig 中选择 ARCH_REQUIRE_GPIOLIB 或者 ARCH_WANT_OPTIONAL_GPIOLIB -选项。那些调用标准 GPIO 函数的驱动应该在 Kconfig 入口中声明依赖GENERIC_GPIO。 -当驱动包含文件: - - #include <linux/gpio.h> - -则 GPIO 函数是可用,无论是“真实代码”还是经优化过的语句。如果你遵守 -这个公约，当你的代码完成后，对其他的开发者来说会更容易看懂和维护。 - -注意，这些操作包含所用平台的 I/O 屏障代码，驱动无须显式地调用他们。 - - -标识 GPIO ---------- - -GPIO 是通过无符号整型来标识的,范围是 0 到 MAX_INT。保留“负”数 -用于其他目的,例如标识信号“在这个板子上不可用”或指示错误。未接触底层 -硬件的代码会忽略这些整数。 - -平台会定义这些整数的用法,且通常使用 #define 来定义 GPIO，这样 -板级特定的启动代码可以直接关联相应的原理图。相对来说，驱动应该仅使用 -启动代码传递过来的 GPIO 编号，使用 platform_data 保存板级特定 -引脚配置数据 (同时还有其他须要的板级特定数据)，避免可能出现的问题。 - -例如一个平台使用编号 32-159 来标识 GPIO,而在另一个平台使用编号0-63 -标识一组 GPIO 控制器,64-79标识另一类 GPIO 控制器,且在一个含有 -FPGA 的特定板子上使用 80-95。编号不一定要连续,那些平台中，也可以 -使用编号2000-2063来标识一个 I2C 接口的 GPIO 扩展器中的 GPIO。 - -如果你要初始化一个带有无效 GPIO 编号的结构体,可以使用一些负编码 -(如"-EINVAL")，那将使其永远不会是有效。来测试这样一个结构体中的编号 -是否关联一个 GPIO，你可使用以下断言:: - - int gpio_is_valid(int number); - -如果编号不存在，则请求和释放 GPIO 的函数将拒绝执行相关操作(见下文)。 -其他编号也可能被拒绝,比如一个编号可能存在，但暂时在给定的电路上不可用。 - -一个平台是否支持多个 GPIO 控制器为平台特定的实现问题，就像是否可以 -在 GPIO 编号空间中有“空洞”和是否可以在运行时添加新的控制器一样。 -这些问题会影响其他事情，包括相邻的 GPIO 编号是否存在等。 - -使用 GPIO ---------- - -对于一个 GPIO，系统应该做的第一件事情就是通过 gpio_request() -函数分配它，见下文。 - -接下来是设置I/O方向，这通常是在板级启动代码中为所使用的 GPIO 设置 -platform_device 时完成:: - - /* 设置为输入或输出, 返回 0 或负的错误代码 */ - int gpio_direction_input(unsigned gpio); - int gpio_direction_output(unsigned gpio, int value); - -返回值为零代表成功，否则返回一个负的错误代码。这个返回值需要检查，因为 -get/set(获取/设置)函数调用没法返回错误,且有可能是配置错误。通常， -你应该在进程上下文中调用这些函数。然而,对于自旋锁安全的 GPIO，在板子 -启动的早期、进程启动前使用他们也是可以的。 - -对于作为输出的 GPIO，为其提供初始输出值，对于避免在系统启动期间出现 -信号毛刺是很有帮助的。 - -为了与传统的 GPIO 接口兼容, 在设置一个 GPIO 方向时，如果它还未被申请， -则隐含了申请那个 GPIO 的操作(见下文)。这种兼容性正在从可选的 gpiolib -框架中移除。 - -如果这个 GPIO 编码不存在，或者特定的 GPIO 不能用于那种模式，则方向 -设置可能失败。依赖启动固件来正确地设置方向通常是一个坏主意，因为它可能 -除了启动Linux，并没有做更多的验证工作。(同理, 板子的启动代码可能需要 -将这个复用的引脚设置为 GPIO，并正确地配置上拉/下拉电阻。) - - -访问自旋锁安全的 GPIO ---------------------- - -大多数 GPIO 控制器可以通过内存读/写指令来访问。这些指令不会休眠,可以 -安全地在硬(非线程)中断例程和类似的上下文中完成。 - -对于那些 GPIO，使用以下的函数访问:: - - /* GPIO 输入:返回零或非零 */ - int gpio_get_value(unsigned gpio); - - /* GPIO 输出 */ - void gpio_set_value(unsigned gpio, int value); - -GPIO值是布尔值，零表示低电平，非零表示高电平。当读取一个输出引脚的值时， -返回值应该是引脚上的值。这个值不总是和输出值相符，因为存在开漏输出信号和 -输出延迟问题。 - -以上的 get/set 函数无错误返回值，因为之前 gpio_direction_*()应已检查过 -其是否为“无效GPIO”。此外，还需要注意的是并不是所有平台都可以从输出引脚 -中读取数据，对于不能读取的引脚应总返回零。另外，对那些在原子上下文中无法 -安全访问的 GPIO (译者注：因为访问可能导致休眠)使用这些函数是不合适的 -(见下文)。 - -在 GPIO 编号(还有输出、值)为常数的情况下,鼓励通过平台特定的实现来优化 -这两个函数来访问 GPIO 值。这种情况(读写一个硬件寄存器)下只需要几条指令 -是很正常的,且无须自旋锁。这种优化函数比起那些在子程序上花费许多指令的 -函数可以使得模拟接口(译者注:例如 GPIO 模拟 I2C、1-wire 或 SPI)的 -应用(在空间和时间上都)更具效率。 - - -访问可能休眠的 GPIO -------------------- - -某些 GPIO 控制器必须通过基于总线(如 I2C 或 SPI)的消息访问。读或写这些 -GPIO 值的命令需要等待其信息排到队首才发送命令，再获得其反馈。期间需要 -休眠，这不能在 IRQ 例程(中断上下文)中执行。 - -为了访问这种 GPIO,内核定义了一套不同的函数:: - - /* GPIO 输入:返回零或非零 ,可能会休眠 */ - int gpio_get_value_cansleep(unsigned gpio); - - /* GPIO 输出,可能会休眠 */ - void gpio_set_value_cansleep(unsigned gpio, int value); - -访问这样的 GPIO 需要一个允许休眠的上下文，例如线程 IRQ 处理例程，并用以上的 -访问函数替换那些没有 cansleep()后缀的自旋锁安全访问函数。 - -除了这些访问函数可能休眠，且它们操作的 GPIO 不能在硬件 IRQ 处理例程中访问的 -事实，这些处理例程实际上和自旋锁安全的函数是一样的。 - -** 除此之外 ** 调用设置和配置此类 GPIO 的函数也必须在允许休眠的上下文中， -因为它们可能也需要访问 GPIO 控制器芯片 (这些设置函数通常在板级启动代码或者 -驱动探测/断开代码中，所以这是一个容易满足的约束条件。) :: - - gpio_direction_input() - gpio_direction_output() - gpio_request() - - ## gpio_request_one() - - gpio_free() - - - -声明和释放 GPIO ----------------- - -为了有助于捕获系统配置错误,定义了两个函数:: - - /* 申请 GPIO, 返回 0 或负的错误代码. - * 非空标签可能有助于诊断. - */ - int gpio_request(unsigned gpio, const char *label); - - /* 释放之前声明的 GPIO */ - void gpio_free(unsigned gpio); - -将无效的 GPIO 编码传递给 gpio_request()会导致失败，申请一个已使用这个 -函数声明过的 GPIO 也会失败。gpio_request()的返回值必须检查。你应该在 -进程上下文中调用这些函数。然而,对于自旋锁安全的 GPIO,在板子启动的早期、 -进入进程之前是可以申请的。 - -这个函数完成两个基本的目标。一是标识那些实际上已作为 GPIO 使用的信号线， -这样便于更好地诊断;系统可能需要服务几百个可用的 GPIO，但是对于任何一个 -给定的电路板通常只有一些被使用。另一个目的是捕获冲突，查明错误:如两个或 -更多驱动错误地认为他们已经独占了某个信号线,或是错误地认为移除一个管理着 -某个已激活信号的驱动是安全的。也就是说，申请 GPIO 的作用类似一种锁机制。 - -某些平台可能也使用 GPIO 作为电源管理激活信号(例如通过关闭未使用芯片区和 -简单地关闭未使用时钟)。 - -对于 GPIO 使用引脚控制子系统已知的引脚，子系统应该被告知其使用情况； -一个 gpiolib 驱动的 .request()操作应调用 pinctrl_gpio_request()， -而 gpiolib 驱动的 .free()操作应调用 pinctrl_gpio_free()。引脚控制 -子系统允许 pinctrl_gpio_request()在某个引脚或引脚组以复用形式“属于” -一个设备时都成功返回。 - -任何须将 GPIO 信号导向适当引脚的引脚复用硬件的编程应该发生在 GPIO -驱动的 .direction_input()或 .direction_output()函数中，以及 -任何输出 GPIO 值的设置之后。这样可使从引脚特殊功能到 GPIO 的转换 -不会在引脚产生毛刺波形。有时当用一个 GPIO 实现其信号驱动一个非 GPIO -硬件模块的解决方案时，就需要这种机制。 - -某些平台允许部分或所有 GPIO 信号使用不同的引脚。类似的，GPIO 或引脚的 -其他方面也需要配置，如上拉/下拉。平台软件应该在对这些 GPIO 调用 -gpio_request()前将这类细节配置好，例如使用引脚控制子系统的映射表， -使得 GPIO 的用户无须关注这些细节。 - -还有一个值得注意的是在释放 GPIO 前，你必须停止使用它。 - - -注意:申请一个 GPIO 并没有以任何方式配置它，只不过标识那个 GPIO 处于使用 -状态。必须有另外的代码来处理引脚配置(如控制 GPIO 使用的引脚、上拉/下拉)。 -考虑到大多数情况下声明 GPIO 之后就会立即配置它们,所以定义了以下三个辅助函数:: - - /* 申请一个 GPIO 信号, 同时通过特定的'flags'初始化配置, - * 其他和 gpio_request()的参数和返回值相同 - * - */ - int gpio_request_one(unsigned gpio, unsigned long flags, const char *label); - -这里 'flags' 当前定义可指定以下属性: - - * GPIOF_DIR_IN - 配置方向为输入 - * GPIOF_DIR_OUT - 配置方向为输出 - - * GPIOF_INIT_LOW - 在作为输出时,初始值为低电平 - * GPIOF_INIT_HIGH - 在作为输出时,初始值为高电平 - -因为 GPIOF_INIT_* 仅有在配置为输出的时候才存在,所以有效的组合为: - - * GPIOF_IN - 配置为输入 - * GPIOF_OUT_INIT_LOW - 配置为输出,并初始化为低电平 - * GPIOF_OUT_INIT_HIGH - 配置为输出,并初始化为高电平 - -更进一步,为了更简单地声明/释放多个 GPIO,'struct gpio'被引进来封装所有 -这三个领域:: - - struct gpio { - unsigned gpio; - unsigned long flags; - const char *label; - }; - -一个典型的用例:: - - static struct gpio leds_gpios[] = { - { 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* 默认开启 */ - { 33, GPIOF_OUT_INIT_LOW, "Green LED" }, /* 默认关闭 */ - { 34, GPIOF_OUT_INIT_LOW, "Red LED" }, /* 默认关闭 */ - { 35, GPIOF_OUT_INIT_LOW, "Blue LED" }, /* 默认关闭 */ - { ... }, - }; - - err = gpio_request_one(31, GPIOF_IN, "Reset Button"); - if (err) - ... - - -GPIO 映射到 IRQ ----------------- - -GPIO 编号是无符号整数;IRQ 编号也是。这些构成了两个逻辑上不同的命名空间 -(GPIO 0 不一定使用 IRQ 0)。你可以通过以下函数在它们之间实现映射:: - - /* 映射 GPIO 编号到 IRQ 编号 */ - int gpio_to_irq(unsigned gpio); - -它们的返回值为对应命名空间的相关编号，或是负的错误代码(如果无法映射)。 -(例如,某些 GPIO 无法做为 IRQ 使用。)以下的编号错误是未经检测的:使用一个 -未通过 gpio_direction_input()配置为输入的 GPIO 编号，或者使用一个 -并非来源于gpio_to_irq()的 IRQ 编号。 - -这两个映射函数可能会在信号编号的加减计算过程上花些时间。它们不可休眠。 - -gpio_to_irq()返回的非错误值可以传递给 request_irq()或者 free_irq()。 -它们通常通过板级特定的初始化代码存放到平台设备的 IRQ 资源中。注意:IRQ -触发选项是 IRQ 接口的一部分，如 IRQF_TRIGGER_FALLING，系统唤醒能力 -也是如此。 - - -模拟开漏信号 ------------- - -有时在只有低电平信号作为实际驱动结果(译者注:多个输出连接于一点，逻辑电平 -结果为所有输出的逻辑与)的时候,共享的信号线需要使用“开漏”信号。(该术语 -适用于 CMOS 管；而 TTL 用“集电极开路”。)一个上拉电阻使信号为高电平。这 -有时被称为“线与”。实际上，从负逻辑(低电平为真)的角度来看，这是一个“线或”。 - -一个开漏信号的常见例子是共享的低电平使能 IRQ 信号线。此外,有时双向数据总线 -信号也使用漏极开路信号。 - -某些 GPIO 控制器直接支持开漏输出，还有许多不支持。当你需要开漏信号，但 -硬件又不直接支持的时候，一个常用的方法是用任何即可作输入也可作输出的 GPIO -引脚来模拟: - - LOW: gpio_direction_output(gpio, 0) ... 这代码驱动信号并覆盖 - 上拉配置。 - - HIGH: gpio_direction_input(gpio) ... 这代码关闭输出,所以上拉电阻 - (或其他的一些器件)控制了信号。 - -如果你将信号线“驱动”为高电平，但是 gpio_get_value(gpio)报告了一个 -低电平(在适当的上升时间后)，你就可以知道是其他的一些组件将共享信号线拉低了。 -这不一定是错误的。一个常见的例子就是 I2C 时钟的延长：一个需要较慢时钟的 -从设备延迟 SCK 的上升沿，而 I2C 主设备相应地调整其信号传输速率。 - -GPIO控制器和引脚控制子系统 --------------------------- - -SOC上的GPIO控制器可能与引脚控制子系统紧密结合，即引脚可以与可选的gpio功 -能一起被其他功能使用。我们已经涵盖了这样的情况，例如一个GPIO控制器需要保 -留一个引脚或通过调用以下任何一个引脚来设置其方向:: - - pinctrl_gpio_request() - pinctrl_gpio_free() - pinctrl_gpio_direction_input() - pinctrl_gpio_direction_output() - -但是，引脚控制子系统是如何将GPIO号码（这是一个全局事项）与某个引脚控制器 -上的某个引脚交叉关联的？ - -这是通过注册引脚的“范围”来实现的，这基本上是交叉参考表。这些描述是在 -Documentation/driver-api/pin-control.rst - -虽然引脚分配完全由引脚控制子系统管理，但gpio（在gpiolib下）仍由gpio驱动 -维护。可能发生的情况是，SoC中的不同引脚范围由不同的gpio驱动器管理。 - -这使得在调用 "pinctrl_gpio_request" 之前，让gpio驱动向pin ctrl子系 -统宣布它们的引脚范围是合理的，以便在使用任何gpio之前要求引脚控制子系统准 -备相应的引脚。 - -为此，gpio控制器可以用引脚控制子系统注册其引脚范围。目前有两种方法：有或 -无DT。 - -关于对DT的支持，请参考 Documentation/devicetree/bindings/gpio/gpio.txt. - -对于非DT支持，用户可以用适当的参数调用gpiochip_add_pin_range()，将一 -系列的gpio引脚注册到引脚控制驱动上。为此，必须将引脚控制设备的名称字符串 -作为参数之一传给这个程序。 - - -这些公约忽略了什么？ -==================== - -这些公约忽略的最大一件事就是引脚复用，因为这属于高度芯片特定的属性且 -没有可移植性。某个平台可能不需要明确的复用信息；有的对于任意给定的引脚 -可能只有两个功能选项；有的可能每个引脚有八个功能选项；有的可能可以将 -几个引脚中的任何一个作为给定的 GPIO。(是的，这些例子都来自于当前运行 -Linux 的系统。) - -在某些系统中,与引脚复用相关的是配置和使能集成的上、下拉模式。并不是所有 -平台都支持这种模式,或者不会以相同的方式来支持这种模式；且任何给定的电路板 -可能使用外置的上拉(或下拉)电阻,这时芯片上的就不应该使用。(当一个电路需要 -5kOhm 的拉动电阻,芯片上的 100 kOhm 电阻就不能做到。)同样的，驱动能力 -(2 mA vs 20 mA)和电压(1.8V vs 3.3V)是平台特定问题,就像模型一样在 -可配置引脚和 GPIO 之间(没)有一一对应的关系。 - -还有其他一些系统特定的机制没有在这里指出，例如上述的输入去毛刺和线与输出 -选项。硬件可能支持批量读或写 GPIO，但是那一般是配置相关的：对于处于同一 -块区(bank)的GPIO。(GPIO 通常以 16 或 32 个组成一个区块，一个给定的 -片上系统一般有几个这样的区块。)某些系统可以通过输出 GPIO 触发 IRQ， -或者从并非以 GPIO 管理的引脚取值。这些机制的相关代码没有必要具有可移植性。 - -当前，动态定义 GPIO 并不是标准的，例如作为配置一个带有某些 GPIO 扩展器的 -附加电路板的副作用。 - -GPIO 实现者的框架（可选） -========================= - -前面提到了，有一个可选的实现框架，让平台使用相同的编程接口，更加简单地支持 -不同种类的 GPIO 控制器。这个框架称为"gpiolib"。 - -作为一个辅助调试功能，如果 debugfs 可用，就会有一个 /sys/kernel/debug/gpio -文件。通过这个框架，它可以列出所有注册的控制器,以及当前正在使用中的 GPIO -的状态。 - - -控制器驱动: gpio_chip ---------------------- - -在框架中每个 GPIO 控制器都包装为一个 "struct gpio_chip"，他包含了 -该类型的每个控制器的常用信息: - - - 设置 GPIO 方向的方法 - - 用于访问 GPIO 值的方法 - - 告知调用其方法是否可能休眠的标志 - - 可选的 debugfs 信息导出方法 (显示类似上拉配置一样的额外状态) - - 诊断标签 - -也包含了来自 device.platform_data 的每个实例的数据：它第一个 GPIO 的 -编号和它可用的 GPIO 的数量。 - -实现 gpio_chip 的代码应支持多控制器实例，这可能使用驱动模型。那些代码要 -配置每个 gpio_chip，并发起gpiochip_add()。卸载一个 GPIO 控制器很少见， -但在必要的时候可以使用 gpiochip_remove()。 - -大部分 gpio_chip 是一个实例特定结构体的一部分，而并不将 GPIO 接口单独 -暴露出来,比如编址、电源管理等。类似编解码器这样的芯片会有复杂的非 GPIO -状态。 - -任何一个 debugfs 信息导出方法通常应该忽略还未申请作为 GPIO 的信号线。 -他们可以使用 gpiochip_is_requested()测试，当这个 GPIO 已经申请过了 -就返回相关的标签，否则返回 NULL。 - - -平台支持 --------- - -为了支持这个框架，一个平台的 Kconfig 文件将会 "select"(选择) -ARCH_REQUIRE_GPIOLIB 或 ARCH_WANT_OPTIONAL_GPIOLIB，并让它的 -<asm/gpio.h> 包含 <asm-generic/gpio.h>，同时定义两个方法: -gpio_get_value()、gpio_set_value()。 - -它也应提供一个 ARCH_NR_GPIOS 的定义值，这样可以更好地反映该平台 GPIO -的实际数量,节省静态表的空间。(这个定义值应该包含片上系统内建 GPIO 和 -GPIO 扩展器中的数据。) - -ARCH_REQUIRE_GPIOLIB 意味着 gpiolib 核心在这个构架中将总是编译进内核。 - -ARCH_WANT_OPTIONAL_GPIOLIB 意味着 gpiolib 核心默认关闭,且用户可以 -使能它,并将其编译进内核(可选)。 - -如果这些选项都没被选择,该平台就不通过 GPIO-lib 支持 GPIO,且代码不可以 -被用户使能。 - -以下这些方法的实现可以直接使用框架代码,并总是通过 gpio_chip 调度:: - - #define gpio_get_value __gpio_get_value - #define gpio_set_value __gpio_set_value - -这些定义可以用更理想的实现方法替代，那就是使用经过逻辑优化的内联函数来访问 -基于特定片上系统的 GPIO。例如,若引用的 GPIO (寄存器位偏移)是常量“12”， -读取或设置它可能只需少则两或三个指令，且不会休眠。当这样的优化无法实现时， -那些函数必须使用框架提供的代码，那就至少要几十条指令才可以实现。对于用 GPIO -模拟的 I/O 接口, 如此精简指令是很有意义的。 - -对于片上系统，平台特定代码为片上 GPIO 每个区(bank)定义并注册 gpio_chip -实例。那些 GPIO 应该根据芯片厂商的文档进行编码/标签,并直接和电路板原理图 -对应。他们应该开始于零并终止于平台特定的限制。这些 GPIO(代码)通常从 -arch_initcall()或者更早的地方集成进平台初始化代码，使这些 GPIO 总是可用， -且他们通常可以作为 IRQ 使用。 - -板级支持 --------- - -对于外部 GPIO 控制器(例如 I2C 或 SPI 扩展器、专用芯片、多功能器件、FPGA -或 CPLD)，大多数常用板级特定代码都可以注册控制器设备，并保证他们的驱动知道 -gpiochip_add()所使用的 GPIO 编号。他们的起始编号通常跟在平台特定的 GPIO -编号之后。 - -例如板级启动代码应该创建结构体指明芯片公开的 GPIO 范围，并使用 platform_data -将其传递给每个 GPIO 扩展器芯片。然后芯片驱动中的 probe()例程可以将这个 -数据传递给 gpiochip_add()。 - -初始化顺序很重要。例如，如果一个设备依赖基于 I2C 的(扩展)GPIO，那么它的 -probe()例程就应该在那个 GPIO 有效以后才可以被调用。这意味着设备应该在 -GPIO 可以工作之后才可被注册。解决这类依赖的的一种方法是让这种 gpio_chip -控制器向板级特定代码提供 setup()和 teardown()回调函数。一旦所有必须的 -资源可用之后，这些板级特定的回调函数将会注册设备，并可以在这些 GPIO 控制器 -设备变成无效时移除它们。 - - -用户空间的 Sysfs 接口（可选） -============================= - -使用“gpiolib”实现框架的平台可以选择配置一个 GPIO 的 sysfs 用户接口。 -这不同于 debugfs 接口，因为它提供的是对 GPIO方向和值的控制，而不只显示 -一个GPIO 的状态摘要。此外,它可以出现在没有调试支持的产品级系统中。 - -例如，通过适当的系统硬件文档，用户空间可以知道 GIOP #23 控制 Flash -存储器的写保护(用于保护其中 Bootloader 分区)。产品的系统升级可能需要 -临时解除这个保护：首先导入一个 GPIO，改变其输出状态，然后在重新使能写保护 -前升级代码。通常情况下,GPIO #23 是不会被触及的，并且内核也不需要知道他。 - -根据适当的硬件文档，某些系统的用户空间 GPIO 可以用于确定系统配置数据， -这些数据是标准内核不知道的。在某些任务中，简单的用户空间 GPIO 驱动可能是 -系统真正需要的。 - -注意：标准内核驱动中已经存在通用的“LED 和按键”GPIO 任务，分别是: -"leds-gpio" 和 "gpio_keys"。请使用这些来替代直接访问 GPIO，因为集成在 -内核框架中的这类驱动比你在用户空间的代码更好。 - - -Sysfs 中的路径 --------------- - -在/sys/class/gpio 中有 3 类入口: - - - 用于在用户空间控制 GPIO 的控制接口; - - - GPIOs 本身;以及 - - - GPIO 控制器 ("gpio_chip" 实例)。 - -除了这些标准的文件,还包含“device”符号链接。 - -控制接口是只写的: - - /sys/class/gpio/ - - "export" ... 用户空间可以通过写其编号到这个文件，要求内核导出 - 一个 GPIO 的控制到用户空间。 - - 例如: 如果内核代码没有申请 GPIO #19,"echo 19 > export" - 将会为 GPIO #19 创建一个 "gpio19" 节点。 - - "unexport" ... 导出到用户空间的逆操作。 - - 例如: "echo 19 > unexport" 将会移除使用"export"文件导出的 - "gpio19" 节点。 - -GPIO 信号的路径类似 /sys/class/gpio/gpio42/ (对于 GPIO #42 来说)， -并有如下的读/写属性: - - /sys/class/gpio/gpioN/ - - "direction" ... 读取得到 "in" 或 "out"。这个值通常运行写入。 - 写入"out" 时,其引脚的默认输出为低电平。为了确保无故障运行， - "low" 或 "high" 的电平值应该写入 GPIO 的配置，作为初始输出值。 - - 注意:如果内核不支持改变 GPIO 的方向，或者在导出时内核代码没有 - 明确允许用户空间可以重新配置 GPIO 方向，那么这个属性将不存在。 - - "value" ... 读取得到 0 (低电平) 或 1 (高电平)。如果 GPIO 配置为 - 输出,这个值允许写操作。任何非零值都以高电平看待。 - - 如果引脚可以配置为中断信号，且如果已经配置了产生中断的模式 - （见"edge"的描述），你可以对这个文件使用轮询操作(poll(2))， - 且轮询操作会在任何中断触发时返回。如果你使用轮询操作(poll(2))， - 请在 events 中设置 POLLPRI 和 POLLERR。如果你使用轮询操作 - (select(2))，请在 exceptfds 设置你期望的文件描述符。在 - 轮询操作(poll(2))返回之后，既可以通过 lseek(2)操作读取 - sysfs 文件的开始部分，也可以关闭这个文件并重新打开它来读取数据。 - - "edge" ... 读取得到“none”、“rising”、“falling”或者“both”。 - 将这些字符串写入这个文件可以选择沿触发模式，会使得轮询操作 - (select(2))在"value"文件中返回。 - - 这个文件仅有在这个引脚可以配置为可产生中断输入引脚时，才存在。 - - "active_low" ... 读取得到 0 (假) 或 1 (真)。写入任何非零值可以 - 翻转这个属性的(读写)值。已存在或之后通过"edge"属性设置了"rising" - 和 "falling" 沿触发模式的轮询操作(poll(2))将会遵循这个设置。 - -GPIO 控制器的路径类似 /sys/class/gpio/gpiochip42/ (对于从#42 GPIO -开始实现控制的控制器),并有着以下只读属性: - - /sys/class/gpio/gpiochipN/ - - "base" ... 与以上的 N 相同,代表此芯片管理的第一个 GPIO 的编号 - - "label" ... 用于诊断 (并不总是只有唯一值) - - "ngpio" ... 此控制器所管理的 GPIO 数量(而 GPIO 编号从 N 到 - N + ngpio - 1) - -大多数情况下,电路板的文档应当标明每个 GPIO 的使用目的。但是那些编号并不总是 -固定的,例如在扩展卡上的 GPIO会根据所使用的主板或所在堆叠架构中其他的板子而 -有所不同。在这种情况下,你可能需要使用 gpiochip 节点(尽可能地结合电路图)来 -确定给定信号所用的 GPIO 编号。 - - -API参考 -======= - -本节中列出的函数已被废弃。在新的代码中应该使用基于GPIO描述符的API。 diff --git a/Documentation/translations/zh_TW/gpio.txt b/Documentation/translations/zh_TW/gpio.txt deleted file mode 100644 index 77d69d381316..000000000000 --- a/Documentation/translations/zh_TW/gpio.txt +++ /dev/null @@ -1,574 +0,0 @@ -Chinese translated version of Documentation/admin-guide/gpio - -If you have any comment or update to the content, please contact the -original document maintainer directly. However, if you have a problem -communicating in English you can also ask the Chinese maintainer for -help. Contact the Chinese maintainer if this translation is outdated -or if there is a problem with the translation. - -Maintainer: Grant Likely <grant.likely@secretlab.ca> - Linus Walleij <linus.walleij@linaro.org> -Traditional Chinese maintainer: Hu Haowen <2023002089@link.tyut.edu.cn> ---------------------------------------------------------------------- -Documentation/admin-guide/gpio 的繁體中文翻譯 - -如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 -交流有困難的話，也可以向繁體中文版維護者求助。如果本翻譯更新不及時或 -者翻譯存在問題，請聯繫繁體中文版維護者。 - -英文版維護者： Grant Likely <grant.likely@secretlab.ca> - Linus Walleij <linus.walleij@linaro.org> -繁體中文版維護者： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> -繁體中文版翻譯者： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> -繁體中文版校譯者： 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn> - -以下爲正文 ---------------------------------------------------------------------- -GPIO 接口 - -本文檔提供了一個在Linux下訪問GPIO的公約概述。 - -這些函數以 gpio_* 作爲前綴。其他的函數不允許使用這樣的前綴或相關的 -__gpio_* 前綴。 - - -什麼是GPIO? -========== -"通用輸入/輸出口"(GPIO)是一個靈活的由軟體控制的數位訊號。他們可 -由多種晶片提供,且對於從事嵌入式和定製硬體的 Linux 開發者來說是 -比較熟悉。每個GPIO 都代表一個連接到特定引腳或球柵陣列(BGA)封裝中 -「球珠」的一個位。電路板原理圖顯示了 GPIO 與外部硬體的連接關係。 -驅動可以編寫成通用代碼，以使板級啓動代碼可傳遞引腳配置數據給驅動。 - -片上系統 (SOC) 處理器對 GPIO 有很大的依賴。在某些情況下,每個 -非專用引腳都可配置爲 GPIO,且大多數晶片都最少有一些 GPIO。 -可編程邏輯器件(類似 FPGA) 可以方便地提供 GPIO。像電源管理和 -音頻編解碼器這樣的多功能晶片經常留有一些這樣的引腳來幫助那些引腳 -匱乏的 SOC。同時還有通過 I2C 或 SPI 串行總線連接的「GPIO擴展器」 -晶片。大多數 PC 的南橋有一些擁有 GPIO 能力的引腳 (只有BIOS -固件才知道如何使用他們)。 - -GPIO 的實際功能因系統而異。通常用法有: - - - 輸出值可寫 (高電平=1，低電平=0)。一些晶片也有如何驅動這些值的選項, - 例如只允許輸出一個值、支持「線與」及其他取值類似的模式(值得注意的是 - 「開漏」信號) - - - 輸入值可讀(1、0)。一些晶片支持引腳在配置爲「輸出」時回讀，這對於類似 - 「線與」的情況(以支持雙向信號)是非常有用的。GPIO 控制器可能有輸入 - 去毛刺/消抖邏輯,這有時需要軟體控制。 - - - 輸入通常可作爲 IRQ 信號,一般是沿觸發,但有時是電平觸發。這樣的 IRQ - 可能配置爲系統喚醒事件,以將系統從低功耗狀態下喚醒。 - - - 通常一個 GPIO 根據不同產品電路板的需求,可以配置爲輸入或輸出,也有僅 - 支持單向的。 - - - 大部分 GPIO 可以在持有自旋鎖時訪問,但是通常由串行總線擴展的 GPIO - 不允許持有自旋鎖。但某些系統也支持這種類型。 - -對於給定的電路板,每個 GPIO 都用於某個特定的目的,如監控 MMC/SD 卡的 -插入/移除、檢測卡的防寫狀態、驅動 LED、配置收發器、模擬串行總線、 -復位硬體看門狗、感知開關狀態等等。 - - -GPIO 公約 -========= -注意,這個叫做「公約」，因爲這不是強制性的，不遵循這個公約是無傷大雅的， -因爲此時可移植性並不重要。GPIO 常用於板級特定的電路邏輯,甚至可能 -隨著電路板的版本而改變，且不可能在不同走線的電路板上使用。僅有在少數 -功能上才具有可移植性，其他功能是平台特定。這也是由於「膠合」的邏輯造成的。 - -此外，這不需要任何的執行框架，只是一個接口。某個平台可能通過一個簡單地 -訪問晶片寄存器的內聯函數來實現它，其他平台可能通過委託一系列不同的GPIO -控制器的抽象函數來實現它。(有一些可選的代碼能支持這種策略的實現,本文檔 -後面會介紹，但作爲 GPIO 接口的客戶端驅動程序必須與它的實現無關。) - -也就是說,如果在他們的平台上支持這個公約，驅動應儘可能的使用它。同時，平台 -必須在 Kconfig 中選擇 ARCH_REQUIRE_GPIOLIB 或者 ARCH_WANT_OPTIONAL_GPIOLIB -選項。那些調用標準 GPIO 函數的驅動應該在 Kconfig 入口中聲明依賴GENERIC_GPIO。 -當驅動包含文件: - - #include <linux/gpio.h> - -則 GPIO 函數是可用,無論是「真實代碼」還是經優化過的語句。如果你遵守 -這個公約，當你的代碼完成後，對其他的開發者來說會更容易看懂和維護。 - -注意，這些操作包含所用平台的 I/O 屏障代碼，驅動無須顯式地調用他們。 - - -標識 GPIO ---------- -GPIO 是通過無符號整型來標識的,範圍是 0 到 MAX_INT。保留「負」數 -用於其他目的,例如標識信號「在這個板子上不可用」或指示錯誤。未接觸底層 -硬體的代碼會忽略這些整數。 - -平台會定義這些整數的用法,且通常使用 #define 來定義 GPIO，這樣 -板級特定的啓動代碼可以直接關聯相應的原理圖。相對來說，驅動應該僅使用 -啓動代碼傳遞過來的 GPIO 編號，使用 platform_data 保存板級特定 -引腳配置數據 (同時還有其他須要的板級特定數據)，避免可能出現的問題。 - -例如一個平台使用編號 32-159 來標識 GPIO,而在另一個平台使用編號0-63 -標識一組 GPIO 控制器,64-79標識另一類 GPIO 控制器,且在一個含有 -FPGA 的特定板子上使用 80-95。編號不一定要連續,那些平台中，也可以 -使用編號2000-2063來標識一個 I2C 接口的 GPIO 擴展器中的 GPIO。 - -如果你要初始化一個帶有無效 GPIO 編號的結構體,可以使用一些負編碼 -(如"-EINVAL")，那將使其永遠不會是有效。來測試這樣一個結構體中的編號 -是否關聯一個 GPIO，你可使用以下斷言: - - int gpio_is_valid(int number); - -如果編號不存在，則請求和釋放 GPIO 的函數將拒絕執行相關操作(見下文)。 -其他編號也可能被拒絕,比如一個編號可能存在，但暫時在給定的電路上不可用。 - -一個平台是否支持多個 GPIO 控制器爲平台特定的實現問題，就像是否可以 -在 GPIO 編號空間中有「空洞」和是否可以在運行時添加新的控制器一樣。 -這些問題會影響其他事情，包括相鄰的 GPIO 編號是否存在等。 - -使用 GPIO ---------- -對於一個 GPIO，系統應該做的第一件事情就是通過 gpio_request() -函數分配它，見下文。 - -接下來是設置I/O方向，這通常是在板級啓動代碼中爲所使用的 GPIO 設置 -platform_device 時完成。 - - /* 設置爲輸入或輸出, 返回 0 或負的錯誤代碼 */ - int gpio_direction_input(unsigned gpio); - int gpio_direction_output(unsigned gpio, int value); - -返回值爲零代表成功，否則返回一個負的錯誤代碼。這個返回值需要檢查，因爲 -get/set(獲取/設置)函數調用沒法返回錯誤,且有可能是配置錯誤。通常， -你應該在進程上下文中調用這些函數。然而,對於自旋鎖安全的 GPIO，在板子 -啓動的早期、進程啓動前使用他們也是可以的。 - -對於作爲輸出的 GPIO，爲其提供初始輸出值，對於避免在系統啓動期間出現 -信號毛刺是很有幫助的。 - -爲了與傳統的 GPIO 接口兼容, 在設置一個 GPIO 方向時，如果它還未被申請， -則隱含了申請那個 GPIO 的操作(見下文)。這種兼容性正在從可選的 gpiolib -框架中移除。 - -如果這個 GPIO 編碼不存在，或者特定的 GPIO 不能用於那種模式，則方向 -設置可能失敗。依賴啓動固件來正確地設置方向通常是一個壞主意，因爲它可能 -除了啓動Linux，並沒有做更多的驗證工作。(同理, 板子的啓動代碼可能需要 -將這個復用的引腳設置爲 GPIO，並正確地配置上拉/下拉電阻。) - - -訪問自旋鎖安全的 GPIO -------------------- -大多數 GPIO 控制器可以通過內存讀/寫指令來訪問。這些指令不會休眠,可以 -安全地在硬(非線程)中斷例程和類似的上下文中完成。 - -對於那些 GPIO，使用以下的函數訪問: - - /* GPIO 輸入:返回零或非零 */ - int gpio_get_value(unsigned gpio); - - /* GPIO 輸出 */ - void gpio_set_value(unsigned gpio, int value); - -GPIO值是布爾值，零表示低電平，非零表示高電平。當讀取一個輸出引腳的值時， -返回值應該是引腳上的值。這個值不總是和輸出值相符，因爲存在開漏輸出信號和 -輸出延遲問題。 - -以上的 get/set 函數無錯誤返回值，因爲之前 gpio_direction_*()應已檢查過 -其是否爲「無效GPIO」。此外，還需要注意的是並不是所有平台都可以從輸出引腳 -中讀取數據，對於不能讀取的引腳應總返回零。另外，對那些在原子上下文中無法 -安全訪問的 GPIO (譯者註：因爲訪問可能導致休眠)使用這些函數是不合適的 -(見下文)。 - -在 GPIO 編號(還有輸出、值)爲常數的情況下,鼓勵通過平台特定的實現來優化 -這兩個函數來訪問 GPIO 值。這種情況(讀寫一個硬體寄存器)下只需要幾條指令 -是很正常的,且無須自旋鎖。這種優化函數比起那些在子程序上花費許多指令的 -函數可以使得模擬接口(譯者注:例如 GPIO 模擬 I2C、1-wire 或 SPI)的 -應用(在空間和時間上都)更具效率。 - - -訪問可能休眠的 GPIO ------------------ -某些 GPIO 控制器必須通過基於總線(如 I2C 或 SPI)的消息訪問。讀或寫這些 -GPIO 值的命令需要等待其信息排到隊首才發送命令，再獲得其反饋。期間需要 -休眠，這不能在 IRQ 例程(中斷上下文)中執行。 - -爲了訪問這種 GPIO,內核定義了一套不同的函數: - - /* GPIO 輸入:返回零或非零 ,可能會休眠 */ - int gpio_get_value_cansleep(unsigned gpio); - - /* GPIO 輸出,可能會休眠 */ - void gpio_set_value_cansleep(unsigned gpio, int value); - -訪問這樣的 GPIO 需要一個允許休眠的上下文，例如線程 IRQ 處理例程，並用以上的 -訪問函數替換那些沒有 cansleep()後綴的自旋鎖安全訪問函數。 - -除了這些訪問函數可能休眠，且它們操作的 GPIO 不能在硬體 IRQ 處理例程中訪問的 -事實，這些處理例程實際上和自旋鎖安全的函數是一樣的。 - -** 除此之外 ** 調用設置和配置此類 GPIO 的函數也必須在允許休眠的上下文中， -因爲它們可能也需要訪問 GPIO 控制器晶片: (這些設置函數通常在板級啓動代碼或者 -驅動探測/斷開代碼中，所以這是一個容易滿足的約束條件。) - - gpio_direction_input() - gpio_direction_output() - gpio_request() - -## gpio_request_one() - - gpio_free() - - -聲明和釋放 GPIO ----------------------------- -爲了有助於捕獲系統配置錯誤,定義了兩個函數。 - - /* 申請 GPIO, 返回 0 或負的錯誤代碼. - * 非空標籤可能有助於診斷. - */ - int gpio_request(unsigned gpio, const char *label); - - /* 釋放之前聲明的 GPIO */ - void gpio_free(unsigned gpio); - -將無效的 GPIO 編碼傳遞給 gpio_request()會導致失敗，申請一個已使用這個 -函數聲明過的 GPIO 也會失敗。gpio_request()的返回值必須檢查。你應該在 -進程上下文中調用這些函數。然而,對於自旋鎖安全的 GPIO,在板子啓動的早期、 -進入進程之前是可以申請的。 - -這個函數完成兩個基本的目標。一是標識那些實際上已作爲 GPIO 使用的信號線， -這樣便於更好地診斷;系統可能需要服務幾百個可用的 GPIO，但是對於任何一個 -給定的電路板通常只有一些被使用。另一個目的是捕獲衝突，查明錯誤:如兩個或 -更多驅動錯誤地認爲他們已經獨占了某個信號線,或是錯誤地認爲移除一個管理著 -某個已激活信號的驅動是安全的。也就是說，申請 GPIO 的作用類似一種鎖機制。 - -某些平台可能也使用 GPIO 作爲電源管理激活信號(例如通過關閉未使用晶片區和 -簡單地關閉未使用時鐘)。 - -對於 GPIO 使用 pinctrl 子系統已知的引腳，子系統應該被告知其使用情況； -一個 gpiolib 驅動的 .request()操作應調用 pinctrl_gpio_request()， -而 gpiolib 驅動的 .free()操作應調用 pinctrl_gpio_free()。pinctrl -子系統允許 pinctrl_gpio_request()在某個引腳或引腳組以復用形式「屬於」 -一個設備時都成功返回。 - -任何須將 GPIO 信號導向適當引腳的引腳復用硬體的編程應該發生在 GPIO -驅動的 .direction_input()或 .direction_output()函數中，以及 -任何輸出 GPIO 值的設置之後。這樣可使從引腳特殊功能到 GPIO 的轉換 -不會在引腳產生毛刺波形。有時當用一個 GPIO 實現其信號驅動一個非 GPIO -硬體模塊的解決方案時，就需要這種機制。 - -某些平台允許部分或所有 GPIO 信號使用不同的引腳。類似的，GPIO 或引腳的 -其他方面也需要配置，如上拉/下拉。平台軟體應該在對這些 GPIO 調用 -gpio_request()前將這類細節配置好，例如使用 pinctrl 子系統的映射表， -使得 GPIO 的用戶無須關注這些細節。 - -還有一個值得注意的是在釋放 GPIO 前，你必須停止使用它。 - - -注意:申請一個 GPIO 並沒有以任何方式配置它，只不過標識那個 GPIO 處於使用 -狀態。必須有另外的代碼來處理引腳配置(如控制 GPIO 使用的引腳、上拉/下拉)。 -考慮到大多數情況下聲明 GPIO 之後就會立即配置它們,所以定義了以下三個輔助函數: - - /* 申請一個 GPIO 信號, 同時通過特定的'flags'初始化配置, - * 其他和 gpio_request()的參數和返回值相同 - * - */ - int gpio_request_one(unsigned gpio, unsigned long flags, const char *label); - -這裡 'flags' 當前定義可指定以下屬性: - - * GPIOF_DIR_IN - 配置方向爲輸入 - * GPIOF_DIR_OUT - 配置方向爲輸出 - - * GPIOF_INIT_LOW - 在作爲輸出時,初始值爲低電平 - * GPIOF_INIT_HIGH - 在作爲輸出時,初始值爲高電平 - -因爲 GPIOF_INIT_* 僅有在配置爲輸出的時候才存在,所以有效的組合爲: - - * GPIOF_IN - 配置爲輸入 - * GPIOF_OUT_INIT_LOW - 配置爲輸出,並初始化爲低電平 - * GPIOF_OUT_INIT_HIGH - 配置爲輸出,並初始化爲高電平 - -更進一步,爲了更簡單地聲明/釋放多個 GPIO,'struct gpio'被引進來封裝所有 -這三個領域: - - struct gpio { - unsigned gpio; - unsigned long flags; - const char *label; - }; - -一個典型的用例: - - static struct gpio leds_gpios[] = { - { 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* 默認開啓 */ - { 33, GPIOF_OUT_INIT_LOW, "Green LED" }, /* 默認關閉 */ - { 34, GPIOF_OUT_INIT_LOW, "Red LED" }, /* 默認關閉 */ - { 35, GPIOF_OUT_INIT_LOW, "Blue LED" }, /* 默認關閉 */ - { ... }, - }; - - err = gpio_request_one(31, GPIOF_IN, "Reset Button"); - if (err) - ... - - -GPIO 映射到 IRQ --------------------- -GPIO 編號是無符號整數;IRQ 編號也是。這些構成了兩個邏輯上不同的命名空間 -(GPIO 0 不一定使用 IRQ 0)。你可以通過以下函數在它們之間實現映射: - - /* 映射 GPIO 編號到 IRQ 編號 */ - int gpio_to_irq(unsigned gpio); - -它們的返回值爲對應命名空間的相關編號，或是負的錯誤代碼(如果無法映射)。 -(例如,某些 GPIO 無法做爲 IRQ 使用。)以下的編號錯誤是未經檢測的:使用一個 -未通過 gpio_direction_input()配置爲輸入的 GPIO 編號，或者使用一個 -並非來源於gpio_to_irq()的 IRQ 編號。 - -這兩個映射函數可能會在信號編號的加減計算過程上花些時間。它們不可休眠。 - -gpio_to_irq()返回的非錯誤值可以傳遞給 request_irq()或者 free_irq()。 -它們通常通過板級特定的初始化代碼存放到平台設備的 IRQ 資源中。注意:IRQ -觸發選項是 IRQ 接口的一部分，如 IRQF_TRIGGER_FALLING，系統喚醒能力 -也是如此。 - - -模擬開漏信號 ----------------------------- -有時在只有低電平信號作爲實際驅動結果(譯者注:多個輸出連接於一點，邏輯電平 -結果爲所有輸出的邏輯與)的時候,共享的信號線需要使用「開漏」信號。(該術語 -適用於 CMOS 管；而 TTL 用「集電極開路」。)一個上拉電阻使信號爲高電平。這 -有時被稱爲「線與」。實際上，從負邏輯(低電平爲真)的角度來看，這是一個「線或」。 - -一個開漏信號的常見例子是共享的低電平使能 IRQ 信號線。此外,有時雙向數據總線 -信號也使用漏極開路信號。 - -某些 GPIO 控制器直接支持開漏輸出，還有許多不支持。當你需要開漏信號，但 -硬體又不直接支持的時候，一個常用的方法是用任何即可作輸入也可作輸出的 GPIO -引腳來模擬: - - LOW: gpio_direction_output(gpio, 0) ... 這代碼驅動信號並覆蓋 - 上拉配置。 - - HIGH: gpio_direction_input(gpio) ... 這代碼關閉輸出,所以上拉電阻 - (或其他的一些器件)控制了信號。 - -如果你將信號線「驅動」爲高電平，但是 gpio_get_value(gpio)報告了一個 -低電平(在適當的上升時間後)，你就可以知道是其他的一些組件將共享信號線拉低了。 -這不一定是錯誤的。一個常見的例子就是 I2C 時鐘的延長：一個需要較慢時鐘的 -從設備延遲 SCK 的上升沿，而 I2C 主設備相應地調整其信號傳輸速率。 - - -這些公約忽略了什麼? -================ -這些公約忽略的最大一件事就是引腳復用，因爲這屬於高度晶片特定的屬性且 -沒有可移植性。某個平台可能不需要明確的復用信息；有的對於任意給定的引腳 -可能只有兩個功能選項；有的可能每個引腳有八個功能選項；有的可能可以將 -幾個引腳中的任何一個作爲給定的 GPIO。(是的，這些例子都來自於當前運行 -Linux 的系統。) - -在某些系統中,與引腳復用相關的是配置和使能集成的上、下拉模式。並不是所有 -平台都支持這種模式,或者不會以相同的方式來支持這種模式；且任何給定的電路板 -可能使用外置的上拉(或下拉)電阻,這時晶片上的就不應該使用。(當一個電路需要 -5kOhm 的拉動電阻,晶片上的 100 kOhm 電阻就不能做到。)同樣的，驅動能力 -(2 mA vs 20 mA)和電壓(1.8V vs 3.3V)是平台特定問題,就像模型一樣在 -可配置引腳和 GPIO 之間(沒)有一一對應的關係。 - -還有其他一些系統特定的機制沒有在這裡指出，例如上述的輸入去毛刺和線與輸出 -選項。硬體可能支持批量讀或寫 GPIO，但是那一般是配置相關的：對於處於同一 -塊區(bank)的GPIO。(GPIO 通常以 16 或 32 個組成一個區塊，一個給定的 -片上系統一般有幾個這樣的區塊。)某些系統可以通過輸出 GPIO 觸發 IRQ， -或者從並非以 GPIO 管理的引腳取值。這些機制的相關代碼沒有必要具有可移植性。 - -當前，動態定義 GPIO 並不是標準的，例如作爲配置一個帶有某些 GPIO 擴展器的 -附加電路板的副作用。 - -GPIO 實現者的框架 (可選) -===================== -前面提到了，有一個可選的實現框架，讓平台使用相同的編程接口，更加簡單地支持 -不同種類的 GPIO 控制器。這個框架稱爲"gpiolib"。 - -作爲一個輔助調試功能，如果 debugfs 可用，就會有一個 /sys/kernel/debug/gpio -文件。通過這個框架，它可以列出所有註冊的控制器,以及當前正在使用中的 GPIO -的狀態。 - - -控制器驅動: gpio_chip -------------------- -在框架中每個 GPIO 控制器都包裝爲一個 "struct gpio_chip"，他包含了 -該類型的每個控制器的常用信息: - - - 設置 GPIO 方向的方法 - - 用於訪問 GPIO 值的方法 - - 告知調用其方法是否可能休眠的標誌 - - 可選的 debugfs 信息導出方法 (顯示類似上拉配置一樣的額外狀態) - - 診斷標籤 - -也包含了來自 device.platform_data 的每個實例的數據：它第一個 GPIO 的 -編號和它可用的 GPIO 的數量。 - -實現 gpio_chip 的代碼應支持多控制器實例，這可能使用驅動模型。那些代碼要 -配置每個 gpio_chip，並發起gpiochip_add()。卸載一個 GPIO 控制器很少見， -但在必要的時候可以使用 gpiochip_remove()。 - -大部分 gpio_chip 是一個實例特定結構體的一部分，而並不將 GPIO 接口單獨 -暴露出來,比如編址、電源管理等。類似編解碼器這樣的晶片會有複雜的非 GPIO -狀態。 - -任何一個 debugfs 信息導出方法通常應該忽略還未申請作爲 GPIO 的信號線。 -他們可以使用 gpiochip_is_requested()測試，當這個 GPIO 已經申請過了 -就返回相關的標籤，否則返回 NULL。 - - -平台支持 -------- -爲了支持這個框架，一個平台的 Kconfig 文件將會 "select"(選擇) -ARCH_REQUIRE_GPIOLIB 或 ARCH_WANT_OPTIONAL_GPIOLIB，並讓它的 -<asm/gpio.h> 包含 <asm-generic/gpio.h>，同時定義二個方法: -gpio_get_value()、gpio_set_value()。 - -它也應提供一個 ARCH_NR_GPIOS 的定義值，這樣可以更好地反映該平台 GPIO -的實際數量,節省靜態表的空間。(這個定義值應該包含片上系統內建 GPIO 和 -GPIO 擴展器中的數據。) - -ARCH_REQUIRE_GPIOLIB 意味著 gpiolib 核心在這個構架中將總是編譯進內核。 - -ARCH_WANT_OPTIONAL_GPIOLIB 意味著 gpiolib 核心默認關閉,且用戶可以 -使能它,並將其編譯進內核(可選)。 - -如果這些選項都沒被選擇,該平台就不通過 GPIO-lib 支持 GPIO,且代碼不可以 -被用戶使能。 - -以下這些方法的實現可以直接使用框架代碼,並總是通過 gpio_chip 調度: - - #define gpio_get_value __gpio_get_value - #define gpio_set_value __gpio_set_value - -這些定義可以用更理想的實現方法替代，那就是使用經過邏輯優化的內聯函數來訪問 -基於特定片上系統的 GPIO。例如,若引用的 GPIO (寄存器位偏移)是常量「12」， -讀取或設置它可能只需少則兩或三個指令，且不會休眠。當這樣的優化無法實現時， -那些函數必須使用框架提供的代碼，那就至少要幾十條指令才可以實現。對於用 GPIO -模擬的 I/O 接口, 如此精簡指令是很有意義的。 - -對於片上系統，平台特定代碼爲片上 GPIO 每個區(bank)定義並註冊 gpio_chip -實例。那些 GPIO 應該根據晶片廠商的文檔進行編碼/標籤,並直接和電路板原理圖 -對應。他們應該開始於零並終止於平台特定的限制。這些 GPIO(代碼)通常從 -arch_initcall()或者更早的地方集成進平台初始化代碼，使這些 GPIO 總是可用， -且他們通常可以作爲 IRQ 使用。 - -板級支持 -------- -對於外部 GPIO 控制器(例如 I2C 或 SPI 擴展器、專用晶片、多功能器件、FPGA -或 CPLD)，大多數常用板級特定代碼都可以註冊控制器設備，並保證他們的驅動知道 -gpiochip_add()所使用的 GPIO 編號。他們的起始編號通常跟在平台特定的 GPIO -編號之後。 - -例如板級啓動代碼應該創建結構體指明晶片公開的 GPIO 範圍，並使用 platform_data -將其傳遞給每個 GPIO 擴展器晶片。然後晶片驅動中的 probe()例程可以將這個 -數據傳遞給 gpiochip_add()。 - -初始化順序很重要。例如，如果一個設備依賴基於 I2C 的(擴展)GPIO，那麼它的 -probe()例程就應該在那個 GPIO 有效以後才可以被調用。這意味著設備應該在 -GPIO 可以工作之後才可被註冊。解決這類依賴的的一種方法是讓這種 gpio_chip -控制器向板級特定代碼提供 setup()和 teardown()回調函數。一旦所有必須的 -資源可用之後，這些板級特定的回調函數將會註冊設備，並可以在這些 GPIO 控制器 -設備變成無效時移除它們。 - - -用戶空間的 Sysfs 接口(可選) -======================== -使用「gpiolib」實現框架的平台可以選擇配置一個 GPIO 的 sysfs 用戶接口。 -這不同於 debugfs 接口，因爲它提供的是對 GPIO方向和值的控制，而不只顯示 -一個GPIO 的狀態摘要。此外,它可以出現在沒有調試支持的產品級系統中。 - -例如，通過適當的系統硬體文檔，用戶空間可以知道 GIOP #23 控制 Flash -存儲器的防寫(用於保護其中 Bootloader 分區)。產品的系統升級可能需要 -臨時解除這個保護：首先導入一個 GPIO，改變其輸出狀態，然後在重新使能防寫 -前升級代碼。通常情況下,GPIO #23 是不會被觸及的，並且內核也不需要知道他。 - -根據適當的硬體文檔，某些系統的用戶空間 GPIO 可以用於確定系統配置數據， -這些數據是標準內核不知道的。在某些任務中，簡單的用戶空間 GPIO 驅動可能是 -系統真正需要的。 - -注意：標準內核驅動中已經存在通用的「LED 和按鍵」GPIO 任務，分別是: -"leds-gpio" 和 "gpio_keys"。請使用這些來替代直接訪問 GPIO，因爲集成在 -內核框架中的這類驅動比你在用戶空間的代碼更好。 - - -Sysfs 中的路徑 --------------- -在/sys/class/gpio 中有 3 類入口: - - - 用於在用戶空間控制 GPIO 的控制接口; - - - GPIOs 本身;以及 - - - GPIO 控制器 ("gpio_chip" 實例)。 - -除了這些標準的文件,還包含「device」符號連結。 - -控制接口是只寫的: - - /sys/class/gpio/ - - "export" ... 用戶空間可以通過寫其編號到這個文件，要求內核導出 - 一個 GPIO 的控制到用戶空間。 - - 例如: 如果內核代碼沒有申請 GPIO #19,"echo 19 > export" - 將會爲 GPIO #19 創建一個 "gpio19" 節點。 - - "unexport" ... 導出到用戶空間的逆操作。 - - 例如: "echo 19 > unexport" 將會移除使用"export"文件導出的 - "gpio19" 節點。 - -GPIO 信號的路徑類似 /sys/class/gpio/gpio42/ (對於 GPIO #42 來說)， -並有如下的讀/寫屬性: - - /sys/class/gpio/gpioN/ - - "direction" ... 讀取得到 "in" 或 "out"。這個值通常運行寫入。 - 寫入"out" 時,其引腳的默認輸出爲低電平。爲了確保無故障運行， - "low" 或 "high" 的電平值應該寫入 GPIO 的配置，作爲初始輸出值。 - - 注意:如果內核不支持改變 GPIO 的方向，或者在導出時內核代碼沒有 - 明確允許用戶空間可以重新配置 GPIO 方向，那麼這個屬性將不存在。 - - "value" ... 讀取得到 0 (低電平) 或 1 (高電平)。如果 GPIO 配置爲 - 輸出,這個值允許寫操作。任何非零值都以高電平看待。 - - 如果引腳可以配置爲中斷信號，且如果已經配置了產生中斷的模式 - （見"edge"的描述），你可以對這個文件使用輪詢操作(poll(2))， - 且輪詢操作會在任何中斷觸發時返回。如果你使用輪詢操作(poll(2))， - 請在 events 中設置 POLLPRI 和 POLLERR。如果你使用輪詢操作 - (select(2))，請在 exceptfds 設置你期望的文件描述符。在 - 輪詢操作(poll(2))返回之後，既可以通過 lseek(2)操作讀取 - sysfs 文件的開始部分，也可以關閉這個文件並重新打開它來讀取數據。 - - "edge" ... 讀取得到「none」、「rising」、「falling」或者「both」。 - 將這些字符串寫入這個文件可以選擇沿觸發模式，會使得輪詢操作 - (select(2))在"value"文件中返回。 - - 這個文件僅有在這個引腳可以配置爲可產生中斷輸入引腳時，才存在。 - - "active_low" ... 讀取得到 0 (假) 或 1 (真)。寫入任何非零值可以 - 翻轉這個屬性的(讀寫)值。已存在或之後通過"edge"屬性設置了"rising" - 和 "falling" 沿觸發模式的輪詢操作(poll(2))將會遵循這個設置。 - -GPIO 控制器的路徑類似 /sys/class/gpio/gpiochip42/ (對於從#42 GPIO -開始實現控制的控制器),並有著以下只讀屬性: - - /sys/class/gpio/gpiochipN/ - - "base" ... 與以上的 N 相同,代表此晶片管理的第一個 GPIO 的編號 - - "label" ... 用於診斷 (並不總是只有唯一值) - - "ngpio" ... 此控制器所管理的 GPIO 數量(而 GPIO 編號從 N 到 - N + ngpio - 1) - -大多數情況下,電路板的文檔應當標明每個 GPIO 的使用目的。但是那些編號並不總是 -固定的,例如在擴展卡上的 GPIO會根據所使用的主板或所在堆疊架構中其他的板子而 -有所不同。在這種情況下,你可能需要使用 gpiochip 節點(儘可能地結合電路圖)來 -確定給定信號所用的 GPIO 編號。 diff --git a/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst index 25263b8f0588..2e3a52c113d5 100644 --- a/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst +++ b/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst @@ -36,6 +36,13 @@ Description Get the values of all requested lines. +The values returned are logical, indicating if the line is active or inactive. +The ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` flag controls the mapping between physical +values (high/low) and logical values (active/inactive). +If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is not set then high is active and +low is inactive. If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is set then low is active +and high is inactive. + The values of both input and output lines may be read. For output lines, the value returned is driver and configuration dependent and diff --git a/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst b/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst index d002a84681ac..a03f30db63ab 100644 --- a/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst +++ b/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst @@ -43,7 +43,10 @@ The configuration applies to all requested lines. The same :ref:`gpio-get-linehandle-config-rules` and :ref:`gpio-get-linehandle-config-support` that apply when requesting the -lines also apply when updating the line configuration. +lines also apply when updating the line configuration, with the additional +restriction that a direction flag must be set. Requesting an invalid +configuration, including without a direction flag set, is an error +(**EINVAL**). The motivating use case for this command is changing direction of bi-directional lines between input and output, but it may be used more diff --git a/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst index 0aa05e623a6c..12862132b420 100644 --- a/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst +++ b/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst @@ -36,6 +36,13 @@ Description Set the values of all requested output lines. +The values set are logical, indicating if the line is to be active or inactive. +The ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` flag controls the mapping between logical +values (active/inactive) and physical values (high/low). +If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is not set then active is high and +inactive is low. If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is set then active is low +and inactive is high. + Only the values of output lines may be set. Attempting to set the value of input lines is an error (**EPERM**). diff --git a/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst b/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst index 68b8d4f9f604..d1e7e2383b0d 100644 --- a/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst +++ b/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst @@ -44,6 +44,11 @@ Edge detection must be enabled for the input line using either both. Edge events are then generated whenever edge interrupts are detected on the input line. +Edges are defined in terms of changes to the logical line value, so an inactive +to active transition is a rising edge. If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is +set then logical polarity is the opposite of physical polarity, and +``GPIOEVENT_REQUEST_RISING_EDGE`` then corresponds to a falling physical edge. + The kernel captures and timestamps edge events as close as possible to their occurrence and stores them in a buffer from where they can be read by userspace at its convenience using `read()`. diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst b/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst index 6513c23fb7ca..1312668e0f6a 100644 --- a/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst +++ b/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst @@ -40,6 +40,11 @@ Edge detection must be enabled for the input line using either both. Edge events are then generated whenever edge interrupts are detected on the input line. +Edges are defined in terms of changes to the logical line value, so an inactive +to active transition is a rising edge. If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is +set then logical polarity is the opposite of physical polarity, and +``GPIO_V2_LINE_FLAG_EDGE_RISING`` then corresponds to a falling physical edge. + The kernel captures and timestamps edge events as close as possible to their occurrence and stores them in a buffer from where they can be read by userspace at its convenience using `read()`. diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst index e4e74a1926d8..d7defd4ca397 100644 --- a/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst +++ b/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst @@ -34,6 +34,13 @@ Description Get the values of requested lines. +The values returned are logical, indicating if the line is active or inactive. +The ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` flag controls the mapping between physical +values (high/low) and logical values (active/inactive). +If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is not set then high is active and low is +inactive. If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is set then low is active and +high is inactive. + The values of both input and output lines may be read. For output lines, the value returned is driver and configuration dependent and diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst index 9b942a8a53ca..cfaab801556c 100644 --- a/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst +++ b/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst @@ -35,11 +35,14 @@ Description Update the configuration of previously requested lines, without releasing the line or introducing potential glitches. -The new configuration must specify the configuration of all requested lines. +The new configuration must specify a configuration for all requested lines. The same :ref:`gpio-v2-get-line-config-rules` and :ref:`gpio-v2-get-line-config-support` that apply when requesting the lines -also apply when updating the line configuration. +also apply when updating the line configuration, with the additional +restriction that a direction flag must be set to enable reconfiguration. +If no direction flag is set in the configuration for a given line then the +configuration for that line is left unchanged. The motivating use case for this command is changing direction of bi-directional lines between input and output, but it may also be used to diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst index 6d2d1886950b..16dd50fc60ca 100644 --- a/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst +++ b/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst @@ -35,6 +35,13 @@ Description Set the values of requested output lines. +The values set are logical, indicating if the line is to be active or inactive. +The ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` flag controls the mapping between logical +values (active/inactive) and physical values (high/low). +If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is not set then active is high and inactive +is low. If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is set then active is low and +inactive is high. + Only the values of output lines may be set. Attempting to set the value of an input line is an error (**EPERM**). diff --git a/Documentation/userspace-api/gpio/sysfs.rst b/Documentation/userspace-api/gpio/sysfs.rst index 116921048b18..bd64896de91a 100644 --- a/Documentation/userspace-api/gpio/sysfs.rst +++ b/Documentation/userspace-api/gpio/sysfs.rst @@ -97,9 +97,10 @@ and have the following read/write attributes: poll(2) will return whenever the interrupt was triggered. If you use poll(2), set the events POLLPRI and POLLERR. If you use select(2), set the file descriptor in exceptfds. After - poll(2) returns, either lseek(2) to the beginning of the sysfs - file and read the new value or close the file and re-open it - to read the value. + poll(2) returns, use pread(2) to read the value at offset + zero. Alternatively, either lseek(2) to the beginning of the + sysfs file and read the new value or close the file and + re-open it to read the value. "edge" ... reads as either "none", "rising", "falling", or diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index a141e8e65c5d..9a97030c6c8d 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -186,6 +186,7 @@ Code Seq# Include File Comments 'Q' all linux/soundcard.h 'R' 00-1F linux/random.h conflict! 'R' 01 linux/rfkill.h conflict! +'R' 20-2F linux/trace_mmap.h 'R' C0-DF net/bluetooth/rfcomm.h 'R' E0 uapi/linux/fsl_mc.h 'S' all linux/cdrom.h conflict! |