diff options
Diffstat (limited to 'Documentation')
345 files changed, 10302 insertions, 4131 deletions
diff --git a/Documentation/ABI/stable/sysfs-block b/Documentation/ABI/stable/sysfs-block index e8797cd09aff..cd14ecb3c9a5 100644 --- a/Documentation/ABI/stable/sysfs-block +++ b/Documentation/ABI/stable/sysfs-block @@ -260,6 +260,15 @@ Description: for discards, and don't read this file. +What: /sys/block/<disk>/queue/dma_alignment +Date: May 2022 +Contact: linux-block@vger.kernel.org +Description: + Reports the alignment that user space addresses must have to be + used for raw block device access with O_DIRECT and other driver + specific passthrough mechanisms. + + What: /sys/block/<disk>/queue/fua Date: May 2018 Contact: linux-block@vger.kernel.org diff --git a/Documentation/ABI/testing/sysfs-bus-iio-vf610 b/Documentation/ABI/testing/sysfs-bus-iio-vf610 index 308a6756d3bf..491ead804488 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-vf610 +++ b/Documentation/ABI/testing/sysfs-bus-iio-vf610 @@ -1,4 +1,4 @@ -What: /sys/bus/iio/devices/iio:deviceX/conversion_mode +What: /sys/bus/iio/devices/iio:deviceX/in_conversion_mode KernelVersion: 4.2 Contact: linux-iio@vger.kernel.org Description: diff --git a/Documentation/ABI/testing/sysfs-class-hwmon b/Documentation/ABI/testing/sysfs-class-hwmon index 653d4c75eddb..7271781a23b2 100644 --- a/Documentation/ABI/testing/sysfs-class-hwmon +++ b/Documentation/ABI/testing/sysfs-class-hwmon @@ -938,3 +938,12 @@ Description: - 1: enable RW + +What: /sys/class/hwmon/hwmonX/device/pec +Description: + PEC support on I2C devices + + - 0, off, n: disable + - 1, on, y: enable + + RW diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index 2ad01cad7f1c..df79e129d097 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -493,12 +493,13 @@ What: /sys/devices/system/cpu/cpuX/regs/ /sys/devices/system/cpu/cpuX/regs/identification/ /sys/devices/system/cpu/cpuX/regs/identification/midr_el1 /sys/devices/system/cpu/cpuX/regs/identification/revidr_el1 + /sys/devices/system/cpu/cpuX/regs/identification/smidr_el1 Date: June 2016 Contact: Linux ARM Kernel Mailing list <linux-arm-kernel@lists.infradead.org> Description: AArch64 CPU registers 'identification' directory exposes the CPU ID registers for - identifying model and revision of the CPU. + identifying model and revision of the CPU and SMCU. What: /sys/devices/system/cpu/aarch32_el0 Date: May 2021 @@ -526,6 +527,7 @@ What: /sys/devices/system/cpu/vulnerabilities /sys/devices/system/cpu/vulnerabilities/srbds /sys/devices/system/cpu/vulnerabilities/tsx_async_abort /sys/devices/system/cpu/vulnerabilities/itlb_multihit + /sys/devices/system/cpu/vulnerabilities/mmio_stale_data Date: January 2018 Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> Description: Information about CPU vulnerabilities diff --git a/Documentation/ABI/testing/sysfs-driver-qat b/Documentation/ABI/testing/sysfs-driver-qat new file mode 100644 index 000000000000..185f81a2aab3 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-qat @@ -0,0 +1,49 @@ +What: /sys/bus/pci/devices/<BDF>/qat/state +Date: June 2022 +KernelVersion: 5.20 +Contact: qat-linux@intel.com +Description: (RW) Reports the current state of the QAT device. Write to + the file to start or stop the device. + + The values are: + + * up: the device is up and running + * down: the device is down + + + It is possible to transition the device from up to down only + if the device is up and vice versa. + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat/cfg_services +Date: June 2022 +KernelVersion: 5.20 +Contact: qat-linux@intel.com +Description: (RW) Reports the current configuration of the QAT device. + Write to the file to change the configured services. + + The values are: + + * sym;asym: the device is configured for running crypto + services + * dc: the device is configured for running compression services + + It is possible to set the configuration only if the device + is in the `down` state (see /sys/bus/pci/devices/<BDF>/qat/state) + + The following example shows how to change the configuration of + a device configured for running crypto services in order to + run data compression:: + + # cat /sys/bus/pci/devices/<BDF>/qat/state + up + # cat /sys/bus/pci/devices/<BDF>/qat/cfg_services + sym;asym + # echo down > /sys/bus/pci/devices/<BDF>/qat/state + # echo dc > /sys/bus/pci/devices/<BDF>/qat/cfg_services + # echo up > /sys/bus/pci/devices/<BDF>/qat/state + # cat /sys/bus/pci/devices/<BDF>/qat/cfg_services + dc + + This attribute is only available for qat_4xxx devices. diff --git a/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg b/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg index ee0d6dbc810e..54d1bfd0db12 100644 --- a/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg +++ b/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg @@ -12,8 +12,9 @@ Description: configuration data to the guest userspace. The authoritative guest-side hardware interface documentation - to the fw_cfg device can be found in "docs/specs/fw_cfg.txt" - in the QEMU source tree. + to the fw_cfg device can be found in "docs/specs/fw_cfg.rst" + in the QEMU source tree, or online at: + https://qemu-project.gitlab.io/qemu/specs/fw_cfg.html **SysFS fw_cfg Interface** diff --git a/Documentation/Kconfig b/Documentation/Kconfig index e549a61f4d96..252bfc164dbd 100644 --- a/Documentation/Kconfig +++ b/Documentation/Kconfig @@ -1,23 +1,22 @@ config WARN_MISSING_DOCUMENTS - bool "Warn if there's a missing documentation file" depends on COMPILE_TEST help - It is not uncommon that a document gets renamed. - This option makes the Kernel to check for missing dependencies, - warning when something is missing. Works only if the Kernel - is built from a git tree. + It is not uncommon that a document gets renamed. + This option makes the Kernel to check for missing dependencies, + warning when something is missing. Works only if the Kernel + is built from a git tree. - If unsure, select 'N'. + If unsure, select 'N'. config WARN_ABI_ERRORS bool "Warn if there are errors at ABI files" depends on COMPILE_TEST help - The files under Documentation/ABI should follow what's - described at Documentation/ABI/README. Yet, as they're manually - written, it would be possible that some of those files would - have errors that would break them for being parsed by - scripts/get_abi.pl. Add a check to verify them. + The files under Documentation/ABI should follow what's + described at Documentation/ABI/README. Yet, as they're manually + written, it would be possible that some of those files would + have errors that would break them for being parsed by + scripts/get_abi.pl. Add a check to verify them. - If unsure, select 'N'. + If unsure, select 'N'. diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst index 04ed8bf27a0e..a0f8164c8513 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.rst +++ b/Documentation/RCU/Design/Requirements/Requirements.rst @@ -1844,10 +1844,10 @@ that meets this requirement. Furthermore, NMI handlers can be interrupted by what appear to RCU to be normal interrupts. One way that this can happen is for code that -directly invokes rcu_irq_enter() and rcu_irq_exit() to be called +directly invokes ct_irq_enter() and ct_irq_exit() to be called from an NMI handler. This astonishing fact of life prompted the current -code structure, which has rcu_irq_enter() invoking -rcu_nmi_enter() and rcu_irq_exit() invoking rcu_nmi_exit(). +code structure, which has ct_irq_enter() invoking +ct_nmi_enter() and ct_irq_exit() invoking ct_nmi_exit(). And yes, I also learned of this requirement the hard way. Loadable Modules @@ -2195,7 +2195,7 @@ scheduling-clock interrupt be enabled when RCU needs it to be: sections, and RCU believes this CPU to be idle, no problem. This sort of thing is used by some architectures for light-weight exception handlers, which can then avoid the overhead of - rcu_irq_enter() and rcu_irq_exit() at exception entry and + ct_irq_enter() and ct_irq_exit() at exception entry and exit, respectively. Some go further and avoid the entireties of irq_enter() and irq_exit(). Just make very sure you are running some of your tests with @@ -2226,7 +2226,7 @@ scheduling-clock interrupt be enabled when RCU needs it to be: +-----------------------------------------------------------------------+ | **Answer**: | +-----------------------------------------------------------------------+ -| One approach is to do ``rcu_irq_exit();rcu_irq_enter();`` every so | +| One approach is to do ``ct_irq_exit();ct_irq_enter();`` every so | | often. But given that long-running interrupt handlers can cause other | | problems, not least for response time, shouldn't you work to keep | | your interrupt handler's runtime within reasonable bounds? | diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst index 794837eb519b..e38c587067fc 100644 --- a/Documentation/RCU/stallwarn.rst +++ b/Documentation/RCU/stallwarn.rst @@ -97,12 +97,12 @@ warnings: which will include additional debugging information. - A low-level kernel issue that either fails to invoke one of the - variants of rcu_user_enter(), rcu_user_exit(), rcu_idle_enter(), - rcu_idle_exit(), rcu_irq_enter(), or rcu_irq_exit() on the one + variants of rcu_eqs_enter(true), rcu_eqs_exit(true), ct_idle_enter(), + ct_idle_exit(), ct_irq_enter(), or ct_irq_exit() on the one hand, or that invokes one of them too many times on the other. Historically, the most frequent issue has been an omission of either irq_enter() or irq_exit(), which in turn invoke - rcu_irq_enter() or rcu_irq_exit(), respectively. Building your + ct_irq_enter() or ct_irq_exit(), respectively. Building your kernel with CONFIG_RCU_EQS_DEBUG=y can help track down these types of issues, which sometimes arise in architecture-specific code. diff --git a/Documentation/admin-guide/cgroup-v1/memcg_test.rst b/Documentation/admin-guide/cgroup-v1/memcg_test.rst index 45b94f7b3beb..a402359abb99 100644 --- a/Documentation/admin-guide/cgroup-v1/memcg_test.rst +++ b/Documentation/admin-guide/cgroup-v1/memcg_test.rst @@ -97,7 +97,7 @@ Under below explanation, we assume CONFIG_MEM_RES_CTRL_SWAP=y. ============= Page Cache is charged at - - add_to_page_cache_locked(). + - filemap_add_folio(). The logic is very clear. (About migration, see below) diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 176298f2f4de..bf842b80bde9 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -184,6 +184,14 @@ cgroup v2 currently supports the following mount options. ignored on non-init namespace mounts. Please refer to the Delegation section for details. + favordynmods + Reduce the latencies of dynamic cgroup modifications such as + task migrations and controller on/offs at the cost of making + hot path operations such as forks and exits more expensive. + The static usage pattern of creating a cgroup, enabling + controllers, and then seeding it with CLONE_INTO_CGROUP is + not affected by this option. + memory_localevents Only populate memory.events with data for the current cgroup, and not any subtrees. This is legacy behaviour, the default diff --git a/Documentation/admin-guide/device-mapper/writecache.rst b/Documentation/admin-guide/device-mapper/writecache.rst index 10429779a91a..60c16b7fd5ac 100644 --- a/Documentation/admin-guide/device-mapper/writecache.rst +++ b/Documentation/admin-guide/device-mapper/writecache.rst @@ -20,6 +20,7 @@ Constructor parameters: size) 5. the number of optional parameters (the parameters with an argument count as two) + start_sector n (default: 0) offset from the start of cache device in 512-byte sectors high_watermark n (default: 50) @@ -74,20 +75,21 @@ Constructor parameters: the origin volume in the last n milliseconds Status: + 1. error indicator - 0 if there was no error, otherwise error number 2. the number of blocks 3. the number of free blocks 4. the number of blocks under writeback -5. the number of read requests -6. the number of read requests that hit the cache -7. the number of write requests -8. the number of write requests that hit uncommitted block -9. the number of write requests that hit committed block -10. the number of write requests that bypass the cache -11. the number of write requests that are allocated in the cache +5. the number of read blocks +6. the number of read blocks that hit the cache +7. the number of write blocks +8. the number of write blocks that hit uncommitted block +9. the number of write blocks that hit committed block +10. the number of write blocks that bypass the cache +11. the number of write blocks that are allocated in the cache 12. the number of write requests that are blocked on the freelist 13. the number of flush requests -14. the number of discard requests +14. the number of discarded blocks Messages: flush diff --git a/Documentation/admin-guide/devices.rst b/Documentation/admin-guide/devices.rst index 035275fedbdd..e3776d77374b 100644 --- a/Documentation/admin-guide/devices.rst +++ b/Documentation/admin-guide/devices.rst @@ -7,10 +7,9 @@ This list is the Linux Device List, the official registry of allocated device numbers and ``/dev`` directory nodes for the Linux operating system. -The LaTeX version of this document is no longer maintained, nor is -the document that used to reside at lanana.org. This version in the -mainline Linux kernel is the master document. Updates shall be sent -as patches to the kernel maintainers (see the +The version of this document at lanana.org is no longer maintained. This +version in the mainline Linux kernel is the master document. Updates +shall be sent as patches to the kernel maintainers (see the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` document). Specifically explore the sections titled "CHAR and MISC DRIVERS", and "BLOCK LAYER" in the MAINTAINERS file to find the right maintainers diff --git a/Documentation/admin-guide/efi-stub.rst b/Documentation/admin-guide/efi-stub.rst index 833edb0d0bc4..b24e7c40d832 100644 --- a/Documentation/admin-guide/efi-stub.rst +++ b/Documentation/admin-guide/efi-stub.rst @@ -7,10 +7,10 @@ as a PE/COFF image, thereby convincing EFI firmware loaders to load it as an EFI executable. The code that modifies the bzImage header, along with the EFI-specific entry point that the firmware loader jumps to are collectively known as the "EFI boot stub", and live in -arch/x86/boot/header.S and arch/x86/boot/compressed/eboot.c, +arch/x86/boot/header.S and drivers/firmware/efi/libstub/x86-stub.c, respectively. For ARM the EFI stub is implemented in arch/arm/boot/compressed/efi-header.S and -arch/arm/boot/compressed/efi-stub.c. EFI stub code that is shared +drivers/firmware/efi/libstub/arm32-stub.c. EFI stub code that is shared between architectures is in drivers/firmware/efi/libstub. For arm64, there is no compressed kernel support, so the Image itself diff --git a/Documentation/admin-guide/hw-vuln/index.rst b/Documentation/admin-guide/hw-vuln/index.rst index 8cbc711cda93..4df436e7c417 100644 --- a/Documentation/admin-guide/hw-vuln/index.rst +++ b/Documentation/admin-guide/hw-vuln/index.rst @@ -17,3 +17,4 @@ are configurable at compile, boot or run time. special-register-buffer-data-sampling.rst core-scheduling.rst l1d_flush.rst + processor_mmio_stale_data.rst diff --git a/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst b/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst new file mode 100644 index 000000000000..9393c50b5afc --- /dev/null +++ b/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst @@ -0,0 +1,246 @@ +========================================= +Processor MMIO Stale Data Vulnerabilities +========================================= + +Processor MMIO Stale Data Vulnerabilities are a class of memory-mapped I/O +(MMIO) vulnerabilities that can expose data. The sequences of operations for +exposing data range from simple to very complex. Because most of the +vulnerabilities require the attacker to have access to MMIO, many environments +are not affected. System environments using virtualization where MMIO access is +provided to untrusted guests may need mitigation. These vulnerabilities are +not transient execution attacks. However, these vulnerabilities may propagate +stale data into core fill buffers where the data can subsequently be inferred +by an unmitigated transient execution attack. Mitigation for these +vulnerabilities includes a combination of microcode update and software +changes, depending on the platform and usage model. Some of these mitigations +are similar to those used to mitigate Microarchitectural Data Sampling (MDS) or +those used to mitigate Special Register Buffer Data Sampling (SRBDS). + +Data Propagators +================ +Propagators are operations that result in stale data being copied or moved from +one microarchitectural buffer or register to another. Processor MMIO Stale Data +Vulnerabilities are operations that may result in stale data being directly +read into an architectural, software-visible state or sampled from a buffer or +register. + +Fill Buffer Stale Data Propagator (FBSDP) +----------------------------------------- +Stale data may propagate from fill buffers (FB) into the non-coherent portion +of the uncore on some non-coherent writes. Fill buffer propagation by itself +does not make stale data architecturally visible. Stale data must be propagated +to a location where it is subject to reading or sampling. + +Sideband Stale Data Propagator (SSDP) +------------------------------------- +The sideband stale data propagator (SSDP) is limited to the client (including +Intel Xeon server E3) uncore implementation. The sideband response buffer is +shared by all client cores. For non-coherent reads that go to sideband +destinations, the uncore logic returns 64 bytes of data to the core, including +both requested data and unrequested stale data, from a transaction buffer and +the sideband response buffer. As a result, stale data from the sideband +response and transaction buffers may now reside in a core fill buffer. + +Primary Stale Data Propagator (PSDP) +------------------------------------ +The primary stale data propagator (PSDP) is limited to the client (including +Intel Xeon server E3) uncore implementation. Similar to the sideband response +buffer, the primary response buffer is shared by all client cores. For some +processors, MMIO primary reads will return 64 bytes of data to the core fill +buffer including both requested data and unrequested stale data. This is +similar to the sideband stale data propagator. + +Vulnerabilities +=============== +Device Register Partial Write (DRPW) (CVE-2022-21166) +----------------------------------------------------- +Some endpoint MMIO registers incorrectly handle writes that are smaller than +the register size. Instead of aborting the write or only copying the correct +subset of bytes (for example, 2 bytes for a 2-byte write), more bytes than +specified by the write transaction may be written to the register. On +processors affected by FBSDP, this may expose stale data from the fill buffers +of the core that created the write transaction. + +Shared Buffers Data Sampling (SBDS) (CVE-2022-21125) +---------------------------------------------------- +After propagators may have moved data around the uncore and copied stale data +into client core fill buffers, processors affected by MFBDS can leak data from +the fill buffer. It is limited to the client (including Intel Xeon server E3) +uncore implementation. + +Shared Buffers Data Read (SBDR) (CVE-2022-21123) +------------------------------------------------ +It is similar to Shared Buffer Data Sampling (SBDS) except that the data is +directly read into the architectural software-visible state. It is limited to +the client (including Intel Xeon server E3) uncore implementation. + +Affected Processors +=================== +Not all the CPUs are affected by all the variants. For instance, most +processors for the server market (excluding Intel Xeon E3 processors) are +impacted by only Device Register Partial Write (DRPW). + +Below is the list of affected Intel processors [#f1]_: + + =================== ============ ========= + Common name Family_Model Steppings + =================== ============ ========= + HASWELL_X 06_3FH 2,4 + SKYLAKE_L 06_4EH 3 + BROADWELL_X 06_4FH All + SKYLAKE_X 06_55H 3,4,6,7,11 + BROADWELL_D 06_56H 3,4,5 + SKYLAKE 06_5EH 3 + ICELAKE_X 06_6AH 4,5,6 + ICELAKE_D 06_6CH 1 + ICELAKE_L 06_7EH 5 + ATOM_TREMONT_D 06_86H All + LAKEFIELD 06_8AH 1 + KABYLAKE_L 06_8EH 9 to 12 + ATOM_TREMONT 06_96H 1 + ATOM_TREMONT_L 06_9CH 0 + KABYLAKE 06_9EH 9 to 13 + COMETLAKE 06_A5H 2,3,5 + COMETLAKE_L 06_A6H 0,1 + ROCKETLAKE 06_A7H 1 + =================== ============ ========= + +If a CPU is in the affected processor list, but not affected by a variant, it +is indicated by new bits in MSR IA32_ARCH_CAPABILITIES. As described in a later +section, mitigation largely remains the same for all the variants, i.e. to +clear the CPU fill buffers via VERW instruction. + +New bits in MSRs +================ +Newer processors and microcode update on existing affected processors added new +bits to IA32_ARCH_CAPABILITIES MSR. These bits can be used to enumerate +specific variants of Processor MMIO Stale Data vulnerabilities and mitigation +capability. + +MSR IA32_ARCH_CAPABILITIES +-------------------------- +Bit 13 - SBDR_SSDP_NO - When set, processor is not affected by either the + Shared Buffers Data Read (SBDR) vulnerability or the sideband stale + data propagator (SSDP). +Bit 14 - FBSDP_NO - When set, processor is not affected by the Fill Buffer + Stale Data Propagator (FBSDP). +Bit 15 - PSDP_NO - When set, processor is not affected by Primary Stale Data + Propagator (PSDP). +Bit 17 - FB_CLEAR - When set, VERW instruction will overwrite CPU fill buffer + values as part of MD_CLEAR operations. Processors that do not + enumerate MDS_NO (meaning they are affected by MDS) but that do + enumerate support for both L1D_FLUSH and MD_CLEAR implicitly enumerate + FB_CLEAR as part of their MD_CLEAR support. +Bit 18 - FB_CLEAR_CTRL - Processor supports read and write to MSR + IA32_MCU_OPT_CTRL[FB_CLEAR_DIS]. On such processors, the FB_CLEAR_DIS + bit can be set to cause the VERW instruction to not perform the + FB_CLEAR action. Not all processors that support FB_CLEAR will support + FB_CLEAR_CTRL. + +MSR IA32_MCU_OPT_CTRL +--------------------- +Bit 3 - FB_CLEAR_DIS - When set, VERW instruction does not perform the FB_CLEAR +action. This may be useful to reduce the performance impact of FB_CLEAR in +cases where system software deems it warranted (for example, when performance +is more critical, or the untrusted software has no MMIO access). Note that +FB_CLEAR_DIS has no impact on enumeration (for example, it does not change +FB_CLEAR or MD_CLEAR enumeration) and it may not be supported on all processors +that enumerate FB_CLEAR. + +Mitigation +========== +Like MDS, all variants of Processor MMIO Stale Data vulnerabilities have the +same mitigation strategy to force the CPU to clear the affected buffers before +an attacker can extract the secrets. + +This is achieved by using the otherwise unused and obsolete VERW instruction in +combination with a microcode update. The microcode clears the affected CPU +buffers when the VERW instruction is executed. + +Kernel reuses the MDS function to invoke the buffer clearing: + + mds_clear_cpu_buffers() + +On MDS affected CPUs, the kernel already invokes CPU buffer clear on +kernel/userspace, hypervisor/guest and C-state (idle) transitions. No +additional mitigation is needed on such CPUs. + +For CPUs not affected by MDS or TAA, mitigation is needed only for the attacker +with MMIO capability. Therefore, VERW is not required for kernel/userspace. For +virtualization case, VERW is only needed at VMENTER for a guest with MMIO +capability. + +Mitigation points +----------------- +Return to user space +^^^^^^^^^^^^^^^^^^^^ +Same mitigation as MDS when affected by MDS/TAA, otherwise no mitigation +needed. + +C-State transition +^^^^^^^^^^^^^^^^^^ +Control register writes by CPU during C-state transition can propagate data +from fill buffer to uncore buffers. Execute VERW before C-state transition to +clear CPU fill buffers. + +Guest entry point +^^^^^^^^^^^^^^^^^ +Same mitigation as MDS when processor is also affected by MDS/TAA, otherwise +execute VERW at VMENTER only for MMIO capable guests. On CPUs not affected by +MDS/TAA, guest without MMIO access cannot extract secrets using Processor MMIO +Stale Data vulnerabilities, so there is no need to execute VERW for such guests. + +Mitigation control on the kernel command line +--------------------------------------------- +The kernel command line allows to control the Processor MMIO Stale Data +mitigations at boot time with the option "mmio_stale_data=". The valid +arguments for this option are: + + ========== ================================================================= + full If the CPU is vulnerable, enable mitigation; CPU buffer clearing + on exit to userspace and when entering a VM. Idle transitions are + protected as well. It does not automatically disable SMT. + full,nosmt Same as full, with SMT disabled on vulnerable CPUs. This is the + complete mitigation. + off Disables mitigation completely. + ========== ================================================================= + +If the CPU is affected and mmio_stale_data=off is not supplied on the kernel +command line, then the kernel selects the appropriate mitigation. + +Mitigation status information +----------------------------- +The Linux kernel provides a sysfs interface to enumerate the current +vulnerability status of the system: whether the system is vulnerable, and +which mitigations are active. The relevant sysfs file is: + + /sys/devices/system/cpu/vulnerabilities/mmio_stale_data + +The possible values in this file are: + + .. list-table:: + + * - 'Not affected' + - The processor is not vulnerable + * - 'Vulnerable' + - The processor is vulnerable, but no mitigation enabled + * - 'Vulnerable: Clear CPU buffers attempted, no microcode' + - The processor is vulnerable, but microcode is not updated. The + mitigation is enabled on a best effort basis. + * - 'Mitigation: Clear CPU buffers' + - The processor is vulnerable and the CPU buffer clearing mitigation is + enabled. + +If the processor is vulnerable then the following information is appended to +the above information: + + ======================== =========================================== + 'SMT vulnerable' SMT is enabled + 'SMT disabled' SMT is disabled + 'SMT Host state unknown' Kernel runs in a VM, Host SMT state unknown + ======================== =========================================== + +References +---------- +.. [#f1] Affected Processors + https://www.intel.com/content/www/us/en/developer/topic-technology/software-security-guidance/processors-affected-consolidated-product-cpu-model.html diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 8090130b544b..0e990f7c2aa3 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -400,6 +400,12 @@ arm64.nomte [ARM64] Unconditionally disable Memory Tagging Extension support + arm64.nosve [ARM64] Unconditionally disable Scalable Vector + Extension support + + arm64.nosme [ARM64] Unconditionally disable Scalable Matrix + Extension support + ataflop= [HW,M68k] atarimouse= [HW,MOUSE] Atari Mouse @@ -550,7 +556,7 @@ nosocket -- Disable socket memory accounting. nokmem -- Disable kernel memory accounting. - checkreqprot [SELINUX] Set initial checkreqprot flag value. + checkreqprot= [SELINUX] Set initial checkreqprot flag value. Format: { "0" | "1" } See security/selinux/Kconfig help text. 0 -- check protection applied by kernel (includes @@ -1439,7 +1445,7 @@ (in particular on some ATI chipsets). The kernel tries to set a reasonable default. - enforcing [SELINUX] Set initial enforcing status. + enforcing= [SELINUX] Set initial enforcing status. Format: {"0" | "1"} See security/selinux/Kconfig help text. 0 -- permissive (log only, no denials). @@ -2469,7 +2475,6 @@ protected: nVHE-based mode with support for guests whose state is kept private from the host. - Not valid if the kernel is running in EL2. Defaults to VHE/nVHE based on hardware support. Setting mode to "protected" will disable kexec and hibernation @@ -3104,7 +3109,7 @@ mem_encrypt=on: Activate SME mem_encrypt=off: Do not activate SME - Refer to Documentation/virt/kvm/amd-memory-encryption.rst + Refer to Documentation/virt/kvm/x86/amd-memory-encryption.rst for details on when memory encryption can be activated. mem_sleep_default= [SUSPEND] Default system suspend mode: @@ -3162,7 +3167,7 @@ improves system performance, but it may also expose users to several CPU vulnerabilities. Equivalent to: nopti [X86,PPC] - kpti=0 [ARM64] + if nokaslr then kpti=0 [ARM64] nospectre_v1 [X86,PPC] nobp=0 [S390] nospectre_v2 [X86,PPC,S390,ARM64] @@ -3176,6 +3181,8 @@ srbds=off [X86,INTEL] no_entry_flush [PPC] no_uaccess_flush [PPC] + mmio_stale_data=off [X86] + retbleed=off [X86] Exceptions: This does not have any effect on @@ -3197,6 +3204,8 @@ Equivalent to: l1tf=flush,nosmt [X86] mds=full,nosmt [X86] tsx_async_abort=full,nosmt [X86] + mmio_stale_data=full,nosmt [X86] + retbleed=auto,nosmt [X86] mminit_loglevel= [KNL] When CONFIG_DEBUG_MEMORY_INIT is set, this @@ -3206,6 +3215,40 @@ log everything. Information is printed at KERN_DEBUG so loglevel=8 may also need to be specified. + mmio_stale_data= + [X86,INTEL] Control mitigation for the Processor + MMIO Stale Data vulnerabilities. + + Processor MMIO Stale Data is a class of + vulnerabilities that may expose data after an MMIO + operation. Exposed data could originate or end in + the same CPU buffers as affected by MDS and TAA. + Therefore, similar to MDS and TAA, the mitigation + is to clear the affected CPU buffers. + + This parameter controls the mitigation. The + options are: + + full - Enable mitigation on vulnerable CPUs + + full,nosmt - Enable mitigation and disable SMT on + vulnerable CPUs. + + off - Unconditionally disable mitigation + + On MDS or TAA affected machines, + mmio_stale_data=off can be prevented by an active + MDS or TAA mitigation as these vulnerabilities are + mitigated with the same mechanism so in order to + disable this mitigation, you need to specify + mds=off and tsx_async_abort=off too. + + Not specifying this option is equivalent to + mmio_stale_data=full. + + For details see: + Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst + module.sig_enforce [KNL] When CONFIG_MODULE_SIG is set, this means that modules without (valid) signatures will fail to load. @@ -3624,6 +3667,9 @@ just as if they had also been called out in the rcu_nocbs= boot parameter. + Note that this argument takes precedence over + the CONFIG_RCU_NOCB_CPU_DEFAULT_ALL option. + noiotrap [SH] Disables trapped I/O port accesses. noirqdebug [X86-32] Disables the code which attempts to detect and @@ -3698,11 +3744,6 @@ noreplace-smp [X86-32,SMP] Don't replace SMP instructions with UP alternatives - nordrand [X86] Disable kernel use of the RDRAND and - RDSEED instructions even if they are supported - by the processor. RDRAND and RDSEED are still - available to user space applications. - noresume [SWSUSP] Disables resume and restores original swap space. @@ -4522,6 +4563,9 @@ no-callback mode from boot but the mode may be toggled at runtime via cpusets. + Note that this argument takes precedence over + the CONFIG_RCU_NOCB_CPU_DEFAULT_ALL option. + rcu_nocb_poll [KNL] Rather than requiring that offloaded CPUs (specified by rcu_nocbs= above) explicitly @@ -4631,6 +4675,34 @@ When RCU_NOCB_CPU is set, also adjust the priority of NOCB callback kthreads. + rcutree.rcu_divisor= [KNL] + Set the shift-right count to use to compute + the callback-invocation batch limit bl from + the number of callbacks queued on this CPU. + The result will be bounded below by the value of + the rcutree.blimit kernel parameter. Every bl + callbacks, the softirq handler will exit in + order to allow the CPU to do other work. + + Please note that this callback-invocation batch + limit applies only to non-offloaded callback + invocation. Offloaded callbacks are instead + invoked in the context of an rcuoc kthread, which + scheduler will preempt as it does any other task. + + rcutree.nocb_nobypass_lim_per_jiffy= [KNL] + On callback-offloaded (rcu_nocbs) CPUs, + RCU reduces the lock contention that would + otherwise be caused by callback floods through + use of the ->nocb_bypass list. However, in the + common non-flooded case, RCU queues directly to + the main ->cblist in order to avoid the extra + overhead of the ->nocb_bypass list and its lock. + But if there are too many callbacks queued during + a single jiffy, RCU pre-queues the callbacks into + the ->nocb_bypass queue. The definition of "too + many" is supplied by this kernel boot parameter. + rcutree.rcu_nocb_gp_stride= [KNL] Set the number of NOCB callback kthreads in each group, which defaults to the square root @@ -5162,6 +5234,30 @@ retain_initrd [RAM] Keep initrd memory after extraction + retbleed= [X86] Control mitigation of RETBleed (Arbitrary + Speculative Code Execution with Return Instructions) + vulnerability. + + off - no mitigation + auto - automatically select a migitation + auto,nosmt - automatically select a mitigation, + disabling SMT if necessary for + the full mitigation (only on Zen1 + and older without STIBP). + ibpb - mitigate short speculation windows on + basic block boundaries too. Safe, highest + perf impact. + unret - force enable untrained return thunks, + only effective on AMD f15h-f17h + based systems. + unret,nosmt - like unret, will disable SMT when STIBP + is not available. + + Selecting 'auto' will choose a mitigation method at run + time according to the CPU. + + Not specifying this option is equivalent to retbleed=auto. + rfkill.default_state= 0 "airplane mode". All wifi, bluetooth, wimax, gps, fm, etc. communication is blocked by default. @@ -5533,6 +5629,7 @@ eibrs - enhanced IBRS eibrs,retpoline - enhanced IBRS + Retpolines eibrs,lfence - enhanced IBRS + LFENCE + ibrs - use IBRS to protect kernel Not specifying this option is equivalent to spectre_v2=auto. @@ -5736,6 +5833,24 @@ expediting. Set to zero to disable automatic expediting. + srcutree.srcu_max_nodelay [KNL] + Specifies the number of no-delay instances + per jiffy for which the SRCU grace period + worker thread will be rescheduled with zero + delay. Beyond this limit, worker thread will + be rescheduled with a sleep delay of one jiffy. + + srcutree.srcu_max_nodelay_phase [KNL] + Specifies the per-grace-period phase, number of + non-sleeping polls of readers. Beyond this limit, + grace period worker thread will be rescheduled + with a sleep delay of one jiffy, between each + rescan of the readers, for a grace period phase. + + srcutree.srcu_retry_check_delay [KNL] + Specifies number of microseconds of non-sleeping + delay between each non-sleeping poll of readers. + srcutree.small_contention_lim [KNL] Specifies the number of update-side contention events per jiffy will be tolerated before diff --git a/Documentation/admin-guide/perf/hns3-pmu.rst b/Documentation/admin-guide/perf/hns3-pmu.rst new file mode 100644 index 000000000000..578407e487d6 --- /dev/null +++ b/Documentation/admin-guide/perf/hns3-pmu.rst @@ -0,0 +1,136 @@ +====================================== +HNS3 Performance Monitoring Unit (PMU) +====================================== + +HNS3(HiSilicon network system 3) Performance Monitoring Unit (PMU) is an +End Point device to collect performance statistics of HiSilicon SoC NIC. +On Hip09, each SICL(Super I/O cluster) has one PMU device. + +HNS3 PMU supports collection of performance statistics such as bandwidth, +latency, packet rate and interrupt rate. + +Each HNS3 PMU supports 8 hardware events. + +HNS3 PMU driver +=============== + +The HNS3 PMU driver registers a perf PMU with the name of its sicl id.:: + + /sys/devices/hns3_pmu_sicl_<sicl_id> + +PMU driver provides description of available events, filter modes, format, +identifier and cpumask in sysfs. + +The "events" directory describes the event code of all supported events +shown in perf list. + +The "filtermode" directory describes the supported filter modes of each +event. + +The "format" directory describes all formats of the config (events) and +config1 (filter options) fields of the perf_event_attr structure. + +The "identifier" file shows version of PMU hardware device. + +The "bdf_min" and "bdf_max" files show the supported bdf range of each +pmu device. + +The "hw_clk_freq" file shows the hardware clock frequency of each pmu +device. + +Example usage of checking event code and subevent code:: + + $# cat /sys/devices/hns3_pmu_sicl_0/events/dly_tx_normal_to_mac_time + config=0x00204 + $# cat /sys/devices/hns3_pmu_sicl_0/events/dly_tx_normal_to_mac_packet_num + config=0x10204 + +Each performance statistic has a pair of events to get two values to +calculate real performance data in userspace. + +The bits 0~15 of config (here 0x0204) are the true hardware event code. If +two events have same value of bits 0~15 of config, that means they are +event pair. And the bit 16 of config indicates getting counter 0 or +counter 1 of hardware event. + +After getting two values of event pair in usersapce, the formula of +computation to calculate real performance data is::: + + counter 0 / counter 1 + +Example usage of checking supported filter mode:: + + $# cat /sys/devices/hns3_pmu_sicl_0/filtermode/bw_ssu_rpu_byte_num + filter mode supported: global/port/port-tc/func/func-queue/ + +Example usage of perf:: + + $# perf list + hns3_pmu_sicl_0/bw_ssu_rpu_byte_num/ [kernel PMU event] + hns3_pmu_sicl_0/bw_ssu_rpu_time/ [kernel PMU event] + ------------------------------------------ + + $# perf stat -g -e hns3_pmu_sicl_0/bw_ssu_rpu_byte_num,global=1/ -e hns3_pmu_sicl_0/bw_ssu_rpu_time,global=1/ -I 1000 + or + $# perf stat -g -e hns3_pmu_sicl_0/config=0x00002,global=1/ -e hns3_pmu_sicl_0/config=0x10002,global=1/ -I 1000 + + +Filter modes +-------------- + +1. global mode +PMU collect performance statistics for all HNS3 PCIe functions of IO DIE. +Set the "global" filter option to 1 will enable this mode. +Example usage of perf:: + + $# perf stat -a -e hns3_pmu_sicl_0/config=0x1020F,global=1/ -I 1000 + +2. port mode +PMU collect performance statistic of one whole physical port. The port id +is same as mac id. The "tc" filter option must be set to 0xF in this mode, +here tc stands for traffic class. + +Example usage of perf:: + + $# perf stat -a -e hns3_pmu_sicl_0/config=0x1020F,port=0,tc=0xF/ -I 1000 + +3. port-tc mode +PMU collect performance statistic of one tc of physical port. The port id +is same as mac id. The "tc" filter option must be set to 0 ~ 7 in this +mode. +Example usage of perf:: + + $# perf stat -a -e hns3_pmu_sicl_0/config=0x1020F,port=0,tc=0/ -I 1000 + +4. func mode +PMU collect performance statistic of one PF/VF. The function id is BDF of +PF/VF, its conversion formula:: + + func = (bus << 8) + (device << 3) + (function) + +for example: + BDF func + 35:00.0 0x3500 + 35:00.1 0x3501 + 35:01.0 0x3508 + +In this mode, the "queue" filter option must be set to 0xFFFF. +Example usage of perf:: + + $# perf stat -a -e hns3_pmu_sicl_0/config=0x1020F,bdf=0x3500,queue=0xFFFF/ -I 1000 + +5. func-queue mode +PMU collect performance statistic of one queue of PF/VF. The function id +is BDF of PF/VF, the "queue" filter option must be set to the exact queue +id of function. +Example usage of perf:: + + $# perf stat -a -e hns3_pmu_sicl_0/config=0x1020F,bdf=0x3500,queue=0/ -I 1000 + +6. func-intr mode +PMU collect performance statistic of one interrupt of PF/VF. The function +id is BDF of PF/VF, the "intr" filter option must be set to the exact +interrupt id of function. +Example usage of perf:: + + $# perf stat -a -e hns3_pmu_sicl_0/config=0x00301,bdf=0x3500,intr=0/ -I 1000 diff --git a/Documentation/admin-guide/perf/index.rst b/Documentation/admin-guide/perf/index.rst index 69b23f087c05..9c9ece88ce53 100644 --- a/Documentation/admin-guide/perf/index.rst +++ b/Documentation/admin-guide/perf/index.rst @@ -9,6 +9,7 @@ Performance monitor support hisi-pmu hisi-pcie-pmu + hns3-pmu imx-ddr qcom_l2_pmu qcom_l3_pmu diff --git a/Documentation/admin-guide/pm/cpuidle.rst b/Documentation/admin-guide/pm/cpuidle.rst index aec2cd2aaea7..19754beb5a4e 100644 --- a/Documentation/admin-guide/pm/cpuidle.rst +++ b/Documentation/admin-guide/pm/cpuidle.rst @@ -612,8 +612,8 @@ the ``menu`` governor to be used on the systems that use the ``ladder`` governor by default this way, for example. The other kernel command line parameters controlling CPU idle time management -described below are only relevant for the *x86* architecture and some of -them affect Intel processors only. +described below are only relevant for the *x86* architecture and references +to ``intel_idle`` affect Intel processors only. The *x86* architecture support code recognizes three kernel command line options related to CPU idle time management: ``idle=poll``, ``idle=halt``, @@ -635,10 +635,13 @@ idle, so it very well may hurt single-thread computations performance as well as energy-efficiency. Thus using it for performance reasons may not be a good idea at all.] -The ``idle=nomwait`` option disables the ``intel_idle`` driver and causes -``acpi_idle`` to be used (as long as all of the information needed by it is -there in the system's ACPI tables), but it is not allowed to use the -``MWAIT`` instruction of the CPUs to ask the hardware to enter idle states. +The ``idle=nomwait`` option prevents the use of ``MWAIT`` instruction of +the CPU to enter idle states. When this option is used, the ``acpi_idle`` +driver will use the ``HLT`` instruction instead of ``MWAIT``. On systems +running Intel processors, this option disables the ``intel_idle`` driver +and forces the use of the ``acpi_idle`` driver instead. Note that in either +case, ``acpi_idle`` driver will function only if all the information needed +by it is in the system's ACPI tables. In addition to the architecture-level kernel command line options affecting CPU idle time management, there are parameters affecting individual ``CPUIdle`` diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index ddccd1077462..8ab042beeb76 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -38,8 +38,8 @@ acct If BSD-style process accounting is enabled these values control its behaviour. If free space on filesystem where the log lives -goes below ``lowwater``% accounting suspends. If free space gets -above ``highwater``% accounting resumes. ``frequency`` determines +goes below ``lowwater``\ % accounting suspends. If free space gets +above ``highwater``\ % accounting resumes. ``frequency`` determines how often do we check the amount of free space (value is in seconds). Default: diff --git a/Documentation/admin-guide/tainted-kernels.rst b/Documentation/admin-guide/tainted-kernels.rst index ceeed7b0798d..7d80e8c307d1 100644 --- a/Documentation/admin-guide/tainted-kernels.rst +++ b/Documentation/admin-guide/tainted-kernels.rst @@ -100,6 +100,7 @@ Bit Log Number Reason that got the kernel tainted 15 _/K 32768 kernel has been live patched 16 _/X 65536 auxiliary taint, defined for and used by distros 17 _/T 131072 kernel was built with the struct randomization plugin + 18 _/N 262144 an in-kernel test has been run === === ====== ======================================================== Note: The character ``_`` is representing a blank in this table to make reading diff --git a/Documentation/arm/google/chromebook-boot-flow.rst b/Documentation/arm/google/chromebook-boot-flow.rst new file mode 100644 index 000000000000..36da77684bba --- /dev/null +++ b/Documentation/arm/google/chromebook-boot-flow.rst @@ -0,0 +1,69 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================================== +Chromebook Boot Flow +====================================== + +Most recent Chromebooks that use device tree are using the opensource +depthcharge_ bootloader. Depthcharge_ expects the OS to be packaged as a `FIT +Image`_ which contains an OS image as well as a collection of device trees. It +is up to depthcharge_ to pick the right device tree from the `FIT Image`_ and +provide it to the OS. + +The scheme that depthcharge_ uses to pick the device tree takes into account +three variables: + +- Board name, specified at depthcharge_ compile time. This is $(BOARD) below. +- Board revision number, determined at runtime (perhaps by reading GPIO + strappings, perhaps via some other method). This is $(REV) below. +- SKU number, read from GPIO strappings at boot time. This is $(SKU) below. + +For recent Chromebooks, depthcharge_ creates a match list that looks like this: + +- google,$(BOARD)-rev$(REV)-sku$(SKU) +- google,$(BOARD)-rev$(REV) +- google,$(BOARD)-sku$(SKU) +- google,$(BOARD) + +Note that some older Chromebooks use a slightly different list that may +not include SKU matching or may prioritize SKU/rev differently. + +Note that for some boards there may be extra board-specific logic to inject +extra compatibles into the list, but this is uncommon. + +Depthcharge_ will look through all device trees in the `FIT Image`_ trying to +find one that matches the most specific compatible. It will then look +through all device trees in the `FIT Image`_ trying to find the one that +matches the *second most* specific compatible, etc. + +When searching for a device tree, depthcharge_ doesn't care where the +compatible string falls within a device tree's root compatible string array. +As an example, if we're on board "lazor", rev 4, SKU 0 and we have two device +trees: + +- "google,lazor-rev5-sku0", "google,lazor-rev4-sku0", "qcom,sc7180" +- "google,lazor", "qcom,sc7180" + +Then depthcharge_ will pick the first device tree even though +"google,lazor-rev4-sku0" was the second compatible listed in that device tree. +This is because it is a more specific compatible than "google,lazor". + +It should be noted that depthcharge_ does not have any smarts to try to +match board or SKU revisions that are "close by". That is to say that +if depthcharge_ knows it's on "rev4" of a board but there is no "rev4" +device tree then depthcharge_ *won't* look for a "rev3" device tree. + +In general when any significant changes are made to a board the board +revision number is increased even if none of those changes need to +be reflected in the device tree. Thus it's fairly common to see device +trees with multiple revisions. + +It should be noted that, taking into account the above system that +depthcharge_ has, the most flexibility is achieved if the device tree +supporting the newest revision(s) of a board omits the "-rev{REV}" +compatible strings. When this is done then if you get a new board +revision and try to run old software on it then we'll at pick the +newest device tree we know about. + +.. _depthcharge: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/depthcharge/ +.. _`FIT Image`: https://doc.coreboot.org/lib/payloads/fit.html diff --git a/Documentation/arm/index.rst b/Documentation/arm/index.rst index 2bda5461a80b..495ada7915e1 100644 --- a/Documentation/arm/index.rst +++ b/Documentation/arm/index.rst @@ -31,6 +31,8 @@ SoC-specific documents .. toctree:: :maxdepth: 1 + google/chromebook-boot-flow + ixp4xx marvell diff --git a/Documentation/arm64/elf_hwcaps.rst b/Documentation/arm64/elf_hwcaps.rst index 3d116fb536c5..52b75a25c205 100644 --- a/Documentation/arm64/elf_hwcaps.rst +++ b/Documentation/arm64/elf_hwcaps.rst @@ -171,96 +171,73 @@ HWCAP_PACG Documentation/arm64/pointer-authentication.rst. HWCAP2_DCPODP - Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0010. HWCAP2_SVE2 - Functionality implied by ID_AA64ZFR0_EL1.SVEVer == 0b0001. HWCAP2_SVEAES - Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0001. HWCAP2_SVEPMULL - Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0010. HWCAP2_SVEBITPERM - Functionality implied by ID_AA64ZFR0_EL1.BitPerm == 0b0001. HWCAP2_SVESHA3 - Functionality implied by ID_AA64ZFR0_EL1.SHA3 == 0b0001. HWCAP2_SVESM4 - Functionality implied by ID_AA64ZFR0_EL1.SM4 == 0b0001. HWCAP2_FLAGM2 - Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0010. HWCAP2_FRINT - Functionality implied by ID_AA64ISAR1_EL1.FRINTTS == 0b0001. HWCAP2_SVEI8MM - Functionality implied by ID_AA64ZFR0_EL1.I8MM == 0b0001. HWCAP2_SVEF32MM - Functionality implied by ID_AA64ZFR0_EL1.F32MM == 0b0001. HWCAP2_SVEF64MM - Functionality implied by ID_AA64ZFR0_EL1.F64MM == 0b0001. HWCAP2_SVEBF16 - Functionality implied by ID_AA64ZFR0_EL1.BF16 == 0b0001. HWCAP2_I8MM - Functionality implied by ID_AA64ISAR1_EL1.I8MM == 0b0001. HWCAP2_BF16 - Functionality implied by ID_AA64ISAR1_EL1.BF16 == 0b0001. HWCAP2_DGH - Functionality implied by ID_AA64ISAR1_EL1.DGH == 0b0001. HWCAP2_RNG - Functionality implied by ID_AA64ISAR0_EL1.RNDR == 0b0001. HWCAP2_BTI - Functionality implied by ID_AA64PFR0_EL1.BT == 0b0001. HWCAP2_MTE - Functionality implied by ID_AA64PFR1_EL1.MTE == 0b0010, as described by Documentation/arm64/memory-tagging-extension.rst. HWCAP2_ECV - Functionality implied by ID_AA64MMFR0_EL1.ECV == 0b0001. HWCAP2_AFP - Functionality implied by ID_AA64MFR1_EL1.AFP == 0b0001. HWCAP2_RPRES - Functionality implied by ID_AA64ISAR2_EL1.RPRES == 0b0001. HWCAP2_MTE3 - Functionality implied by ID_AA64PFR1_EL1.MTE == 0b0011, as described by Documentation/arm64/memory-tagging-extension.rst. @@ -301,6 +278,10 @@ HWCAP2_WFXT Functionality implied by ID_AA64ISAR2_EL1.WFXT == 0b0010. +HWCAP2_EBF16 + + Functionality implied by ID_AA64ISAR1_EL1.BF16 == 0b0010. + 4. Unused AT_HWCAP bits ----------------------- diff --git a/Documentation/arm64/memory.rst b/Documentation/arm64/memory.rst index 901cd094f4ec..2a641ba7be3b 100644 --- a/Documentation/arm64/memory.rst +++ b/Documentation/arm64/memory.rst @@ -33,9 +33,8 @@ AArch64 Linux memory layout with 4KB pages + 4 levels (48-bit):: 0000000000000000 0000ffffffffffff 256TB user ffff000000000000 ffff7fffffffffff 128TB kernel logical memory map [ffff600000000000 ffff7fffffffffff] 32TB [kasan shadow region] - ffff800000000000 ffff800007ffffff 128MB bpf jit region - ffff800008000000 ffff80000fffffff 128MB modules - ffff800010000000 fffffbffefffffff 124TB vmalloc + ffff800000000000 ffff800007ffffff 128MB modules + ffff800008000000 fffffbffefffffff 124TB vmalloc fffffbfff0000000 fffffbfffdffffff 224MB fixed mappings (top down) fffffbfffe000000 fffffbfffe7fffff 8MB [guard region] fffffbfffe800000 fffffbffff7fffff 16MB PCI I/O space @@ -51,9 +50,8 @@ AArch64 Linux memory layout with 64KB pages + 3 levels (52-bit with HW support): 0000000000000000 000fffffffffffff 4PB user fff0000000000000 ffff7fffffffffff ~4PB kernel logical memory map [fffd800000000000 ffff7fffffffffff] 512TB [kasan shadow region] - ffff800000000000 ffff800007ffffff 128MB bpf jit region - ffff800008000000 ffff80000fffffff 128MB modules - ffff800010000000 fffffbffefffffff 124TB vmalloc + ffff800000000000 ffff800007ffffff 128MB modules + ffff800008000000 fffffbffefffffff 124TB vmalloc fffffbfff0000000 fffffbfffdffffff 224MB fixed mappings (top down) fffffbfffe000000 fffffbfffe7fffff 8MB [guard region] fffffbfffe800000 fffffbffff7fffff 16MB PCI I/O space diff --git a/Documentation/arm64/silicon-errata.rst b/Documentation/arm64/silicon-errata.rst index d27db84d585e..33b04db8408f 100644 --- a/Documentation/arm64/silicon-errata.rst +++ b/Documentation/arm64/silicon-errata.rst @@ -82,10 +82,14 @@ stable kernels. +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A57 | #1319537 | ARM64_ERRATUM_1319367 | +----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A57 | #1742098 | ARM64_ERRATUM_1742098 | ++----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A72 | #853709 | N/A | +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A72 | #1319367 | ARM64_ERRATUM_1319367 | +----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A72 | #1655431 | ARM64_ERRATUM_1742098 | ++----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A73 | #858921 | ARM64_ERRATUM_858921 | +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A76 | #1188873,1418040| ARM64_ERRATUM_1418040 | @@ -102,6 +106,8 @@ stable kernels. +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A510 | #2077057 | ARM64_ERRATUM_2077057 | +----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A510 | #2441009 | ARM64_ERRATUM_2441009 | ++----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A710 | #2119858 | ARM64_ERRATUM_2119858 | +----------------+-----------------+-----------------+-----------------------------+ | ARM | Cortex-A710 | #2054223 | ARM64_ERRATUM_2054223 | diff --git a/Documentation/core-api/idr.rst b/Documentation/core-api/idr.rst index 2eb5afdb9931..18d724867064 100644 --- a/Documentation/core-api/idr.rst +++ b/Documentation/core-api/idr.rst @@ -17,6 +17,9 @@ solution to the problem to avoid everybody inventing their own. The IDR provides the ability to map an ID to a pointer, while the IDA provides only ID allocation, and as a result is much more memory-efficient. +The IDR interface is deprecated; please use the :doc:`XArray <xarray>` +instead. + IDR usage ========= diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index d6b3f94b9f1f..0793c400d4b0 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -223,7 +223,7 @@ Module Loading Inter Module support -------------------- -Refer to the file kernel/module.c for more information. +Refer to the files in kernel/module/ for more information. Hardware Interfaces =================== diff --git a/Documentation/core-api/protection-keys.rst b/Documentation/core-api/protection-keys.rst index ec575e72d0b2..bf28ac0401f3 100644 --- a/Documentation/core-api/protection-keys.rst +++ b/Documentation/core-api/protection-keys.rst @@ -4,31 +4,29 @@ Memory Protection Keys ====================== -Memory Protection Keys for Userspace (PKU aka PKEYs) is a feature -which is found on Intel's Skylake (and later) "Scalable Processor" -Server CPUs. It will be available in future non-server Intel parts -and future AMD processors. - -For anyone wishing to test or use this feature, it is available in -Amazon's EC2 C5 instances and is known to work there using an Ubuntu -17.04 image. - -Memory Protection Keys provides a mechanism for enforcing page-based -protections, but without requiring modification of the page tables -when an application changes protection domains. It works by -dedicating 4 previously ignored bits in each page table entry to a -"protection key", giving 16 possible keys. - -There is also a new user-accessible register (PKRU) with two separate -bits (Access Disable and Write Disable) for each key. Being a CPU -register, PKRU is inherently thread-local, potentially giving each +Memory Protection Keys provide a mechanism for enforcing page-based +protections, but without requiring modification of the page tables when an +application changes protection domains. + +Pkeys Userspace (PKU) is a feature which can be found on: + * Intel server CPUs, Skylake and later + * Intel client CPUs, Tiger Lake (11th Gen Core) and later + * Future AMD CPUs + +Pkeys work by dedicating 4 previously Reserved bits in each page table entry to +a "protection key", giving 16 possible keys. + +Protections for each key are defined with a per-CPU user-accessible register +(PKRU). Each of these is a 32-bit register storing two bits (Access Disable +and Write Disable) for each of 16 keys. + +Being a CPU register, PKRU is inherently thread-local, potentially giving each thread a different set of protections from every other thread. -There are two new instructions (RDPKRU/WRPKRU) for reading and writing -to the new register. The feature is only available in 64-bit mode, -even though there is theoretically space in the PAE PTEs. These -permissions are enforced on data access only and have no effect on -instruction fetches. +There are two instructions (RDPKRU/WRPKRU) for reading and writing to the +register. The feature is only available in 64-bit mode, even though there is +theoretically space in the PAE PTEs. These permissions are enforced on data +access only and have no effect on instruction fetches. Syscalls ======== diff --git a/Documentation/core-api/symbol-namespaces.rst b/Documentation/core-api/symbol-namespaces.rst index 5ad9e0abe42c..12e4aecdae94 100644 --- a/Documentation/core-api/symbol-namespaces.rst +++ b/Documentation/core-api/symbol-namespaces.rst @@ -51,8 +51,8 @@ namespace ``USB_STORAGE``, use:: The corresponding ksymtab entry struct ``kernel_symbol`` will have the member ``namespace`` set accordingly. A symbol that is exported without a namespace will refer to ``NULL``. There is no default namespace if none is defined. ``modpost`` -and kernel/module.c make use the namespace at build time or module load time, -respectively. +and kernel/module/main.c make use the namespace at build time or module load +time, respectively. 2.2 Using the DEFAULT_SYMBOL_NAMESPACE define ============================================= diff --git a/Documentation/dev-tools/coccinelle.rst b/Documentation/dev-tools/coccinelle.rst index 9c454de5a7f7..d9976069ed12 100644 --- a/Documentation/dev-tools/coccinelle.rst +++ b/Documentation/dev-tools/coccinelle.rst @@ -66,7 +66,7 @@ The wiki documentation always refers to the linux-next version of the script. For Semantic Patch Language(SmPL) grammar documentation refer to: -http://coccinelle.lip6.fr/documentation.php +https://coccinelle.gitlabpages.inria.fr/website/docs/main_grammar.html Using Coccinelle on the Linux kernel ------------------------------------ diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index a833ecf12fbc..e87973763b91 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -208,6 +208,14 @@ In general, the rules for selftests are Contributing new tests (details) ================================ + * In your Makefile, use facilities from lib.mk by including it instead of + reinventing the wheel. Specify flags and binaries generation flags on + need basis before including lib.mk. :: + + CFLAGS = $(KHDR_INCLUDES) + TEST_GEN_PROGS := close_range_test + include ../lib.mk + * Use TEST_GEN_XXX if such binaries or files are generated during compiling. @@ -230,13 +238,30 @@ Contributing new tests (details) * First use the headers inside the kernel source and/or git repo, and then the system headers. Headers for the kernel release as opposed to headers installed by the distro on the system should be the primary focus to be able - to find regressions. + to find regressions. Use KHDR_INCLUDES in Makefile to include headers from + the kernel source. * If a test needs specific kernel config options enabled, add a config file in the test directory to enable them. e.g: tools/testing/selftests/android/config + * Create a .gitignore file inside test directory and add all generated objects + in it. + + * Add new test name in TARGETS in selftests/Makefile:: + + TARGETS += android + + * All changes should pass:: + + kselftest-{all,install,clean,gen_tar} + kselftest-{all,install,clean,gen_tar} O=abo_path + kselftest-{all,install,clean,gen_tar} O=rel_path + make -C tools/testing/selftests {all,install,clean,gen_tar} + make -C tools/testing/selftests {all,install,clean,gen_tar} O=abs_path + make -C tools/testing/selftests {all,install,clean,gen_tar} O=rel_path + Test Module =========== @@ -250,6 +275,14 @@ assist writing kernel modules that are for use with kselftest: - ``tools/testing/selftests/kselftest_module.h`` - ``tools/testing/selftests/kselftest/module.sh`` +Note that test modules should taint the kernel with TAINT_TEST. This will +happen automatically for modules which are in the ``tools/testing/`` +directory, or for modules which use the ``kselftest_module.h`` header above. +Otherwise, you'll need to add ``MODULE_INFO(test, "Y")`` to your module +source. selftests which do not load modules typically should not taint the +kernel, but in cases where a non-test module is loaded, TEST_TAINT can be +applied from userspace by writing to ``/proc/sys/kernel/tainted``. + How to use ---------- @@ -308,6 +341,7 @@ A bare bones test module might look like this: KSTM_MODULE_LOADERS(test_foo); MODULE_AUTHOR("John Developer <jd@fooman.org>"); MODULE_LICENSE("GPL"); + MODULE_INFO(test, "Y"); Example test script ------------------- diff --git a/Documentation/dev-tools/kunit/run_wrapper.rst b/Documentation/dev-tools/kunit/run_wrapper.rst index 653985ce9cae..cce203138fb7 100644 --- a/Documentation/dev-tools/kunit/run_wrapper.rst +++ b/Documentation/dev-tools/kunit/run_wrapper.rst @@ -192,6 +192,21 @@ via UML. To run tests on qemu, by default it requires two flags: if we have downloaded the microblaze toolchain from the 0-day website to a directory in our home directory called toolchains. +This means that for most architectures, running under qemu is as simple as: + +.. code-block:: bash + + ./tools/testing/kunit/kunit.py run --arch=x86_64 + +When cross-compiling, we'll likely need to specify a different toolchain, for +example: + +.. code-block:: bash + + ./tools/testing/kunit/kunit.py run \ + --arch=s390 \ + --cross_compile=s390x-linux-gnu- + If we want to run KUnit tests on an architecture not supported by the ``--arch`` flag, or want to run KUnit tests on qemu using a non-default configuration; then we can write our own``QemuConfig``. @@ -214,14 +229,11 @@ as --jobs=12 \ --qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py -To run existing KUnit tests on non-UML architectures, see: -Documentation/dev-tools/kunit/non_uml.rst. - Command-Line Arguments ====================== kunit_tool has a number of other command-line arguments which can -be useful for our test environment. Below the most commonly used +be useful for our test environment. Below are the most commonly used command line arguments: - ``--help``: Lists all available options. To list common options, @@ -245,3 +257,64 @@ command line arguments: added or modified. Instead, enable all tests which have satisfied dependencies by adding ``CONFIG_KUNIT_ALL_TESTS=y`` to your ``.kunitconfig``. + +- ``--kunitconfig``: Specifies the path or the directory of the ``.kunitconfig`` + file. For example: + + - ``lib/kunit/.kunitconfig`` can be the path of the file. + + - ``lib/kunit`` can be the directory in which the file is located. + + This file is used to build and run with a predefined set of tests + and their dependencies. For example, to run tests for a given subsystem. + +- ``--kconfig_add``: Specifies additional configuration options to be + appended to the ``.kunitconfig`` file. For example: + + .. code-block:: + + ./tools/testing/kunit/kunit.py run --kconfig_add CONFIG_KASAN=y + +- ``--arch``: Runs tests on the specified architecture. The architecture + argument is same as the Kbuild ARCH environment variable. + For example, i386, x86_64, arm, um, etc. Non-UML architectures run on qemu. + Default is `um`. + +- ``--cross_compile``: Specifies the Kbuild toolchain. It passes the + same argument as passed to the ``CROSS_COMPILE`` variable used by + Kbuild. This will be the prefix for the toolchain + binaries such as GCC. For example: + + - ``sparc64-linux-gnu-`` if we have the sparc toolchain installed on + our system. + + - ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux`` + if we have downloaded the microblaze toolchain from the 0-day + website to a specified path in our home directory called toolchains. + +- ``--qemu_config``: Specifies the path to a file containing a + custom qemu architecture definition. This should be a python file + containing a `QemuArchParams` object. + +- ``--qemu_args``: Specifies additional qemu arguments, for example, ``-smp 8``. + +- ``--jobs``: Specifies the number of jobs (commands) to run simultaneously. + By default, this is set to the number of cores on your system. + +- ``--timeout``: Specifies the maximum number of seconds allowed for all tests to run. + This does not include the time taken to build the tests. + +- ``--kernel_args``: Specifies additional kernel command-line arguments. May be repeated. + +- ``--run_isolated``: If set, boots the kernel for each individual suite/test. + This is useful for debugging a non-hermetic test, one that + might pass/fail based on what ran before it. + +- ``--raw_output``: If set, generates unformatted output from kernel. Possible options are: + + - ``all``: To view the full kernel output, use ``--raw_output=all``. + + - ``kunit``: This is the default option and filters to KUnit output. Use ``--raw_output`` or ``--raw_output=kunit``. + +- ``--json``: If set, stores the test results in a JSON format and prints to `stdout` or + saves to a file if a filename is specified. diff --git a/Documentation/dev-tools/kunit/running_tips.rst b/Documentation/dev-tools/kunit/running_tips.rst index c36f6760087d..8e8c493f17d1 100644 --- a/Documentation/dev-tools/kunit/running_tips.rst +++ b/Documentation/dev-tools/kunit/running_tips.rst @@ -15,7 +15,7 @@ It can be handy to create a bash function like: .. code-block:: bash function run_kunit() { - ( cd "$(git rev-parse --show-toplevel)" && ./tools/testing/kunit/kunit.py run $@ ) + ( cd "$(git rev-parse --show-toplevel)" && ./tools/testing/kunit/kunit.py run "$@" ) } .. note:: @@ -123,8 +123,7 @@ Putting it together into a copy-pastable sequence of commands: .. code-block:: bash # Append coverage options to the current config - $ echo -e "CONFIG_DEBUG_KERNEL=y\nCONFIG_DEBUG_INFO=y\nCONFIG_DEBUG_INFO_DWARF_TOOLCHAIN_DEFAULT=y\nCONFIG_GCOV=y" >> .kunit/.kunitconfig - $ ./tools/testing/kunit/kunit.py run + $ ./tools/testing/kunit/kunit.py run --kunitconfig=.kunit/ --kunitconfig=tools/testing/kunit/configs/coverage_uml.config # Extract the coverage information from the build dir (.kunit/) $ lcov -t "my_kunit_tests" -o coverage.info -c -d .kunit/ diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index d62a04255c2e..44158eecb51e 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -505,7 +505,7 @@ By reusing the same ``cases`` array from above, we can write the test as a const char *str; const char *sha1; }; - struct sha1_test_case cases[] = { + const struct sha1_test_case cases[] = { { .str = "hello world", .sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed", diff --git a/Documentation/devicetree/bindings/arm/altera.yaml b/Documentation/devicetree/bindings/arm/altera.yaml index 5e2017c0a051..e6de1d7f516c 100644 --- a/Documentation/devicetree/bindings/arm/altera.yaml +++ b/Documentation/devicetree/bindings/arm/altera.yaml @@ -25,7 +25,14 @@ properties: items: - enum: - altr,socfpga-arria10-socdk - - enclustra,mercury-aa1 + - const: altr,socfpga-arria10 + - const: altr,socfpga + + - description: Mercury+ AA1 boards + items: + - enum: + - google,chameleon-v3 + - const: enclustra,mercury-aa1 - const: altr,socfpga-arria10 - const: altr,socfpga @@ -47,6 +54,7 @@ properties: items: - enum: - altr,socfpga-stratix10-socdk + - altr,socfpga-stratix10-swvp - const: altr,socfpga-stratix10 - description: SoCFPGA VT diff --git a/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml b/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml new file mode 100644 index 000000000000..1895ce9de461 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml @@ -0,0 +1,87 @@ +# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/aspeed/aspeed.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Aspeed SoC based boards + +maintainers: + - Joel Stanley <joel@jms.id.au> + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - description: AST2400 based boards + items: + - enum: + - facebook,galaxy100-bmc + - facebook,wedge100-bmc + - facebook,wedge40-bmc + - microsoft,olympus-bmc + - quanta,q71l-bmc + - tyan,palmetto-bmc + - yadro,vesnin-bmc + - const: aspeed,ast2400 + + - description: AST2500 based boards + items: + - enum: + - amd,ethanolx-bmc + - ampere,mtjade-bmc + - aspeed,ast2500-evb + - asrock,e3c246d4i-bmc + - asrock,romed8hm3-bmc + - bytedance,g220a-bmc + - facebook,cmm-bmc + - facebook,minipack-bmc + - facebook,tiogapass-bmc + - facebook,yamp-bmc + - facebook,yosemitev2-bmc + - facebook,wedge400-bmc + - hxt,stardragon4800-rep2-bmc + - ibm,mihawk-bmc + - ibm,mowgli-bmc + - ibm,romulus-bmc + - ibm,swift-bmc + - ibm,witherspoon-bmc + - ingrasys,zaius-bmc + - inspur,fp5280g2-bmc + - inspur,nf5280m6-bmc + - inspur,on5263m5-bmc + - intel,s2600wf-bmc + - inventec,lanyang-bmc + - lenovo,hr630-bmc + - lenovo,hr855xg2-bmc + - portwell,neptune-bmc + - qcom,centriq2400-rep-bmc + - supermicro,x11spi-bmc + - tyan,s7106-bmc + - tyan,s8036-bmc + - yadro,nicole-bmc + - yadro,vegman-n110-bmc + - yadro,vegman-rx20-bmc + - yadro,vegman-sx20-bmc + - const: aspeed,ast2500 + + - description: AST2600 based boards + items: + - enum: + - aspeed,ast2600-evb + - aspeed,ast2600-evb-a1 + - facebook,bletchley-bmc + - facebook,cloudripper-bmc + - facebook,elbert-bmc + - facebook,fuji-bmc + - ibm,everest-bmc + - ibm,rainier-bmc + - ibm,tacoma-bmc + - inventec,transformer-bmc + - jabil,rbp-bmc + - nuvia,dc-scm-bmc + - quanta,s6q-bmc + - const: aspeed,ast2600 + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/atmel-at91.yaml b/Documentation/devicetree/bindings/arm/atmel-at91.yaml index 4e495e03264b..2b7848bb7769 100644 --- a/Documentation/devicetree/bindings/arm/atmel-at91.yaml +++ b/Documentation/devicetree/bindings/arm/atmel-at91.yaml @@ -163,9 +163,11 @@ properties: - const: microchip,sama7g5 - const: microchip,sama7 - - description: Microchip LAN9662 PCB8291 Evaluation Board. + - description: Microchip LAN9662 Evaluation Boards. items: - - const: microchip,lan9662-pcb8291 + - enum: + - microchip,lan9662-pcb8291 + - microchip,lan9662-pcb8309 - const: microchip,lan9662 - const: microchip,lan966 diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml index 8b7e87fb6c34..958df32b4899 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml @@ -87,6 +87,13 @@ properties: - const: brcm,bcm53012 - const: brcm,bcm4708 + - description: BCM53015 based boards + items: + - enum: + - meraki,mr26 + - const: brcm,bcm53015 + - const: brcm,bcm4708 + - description: BCM53016 based boards items: - enum: diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcmbca.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcmbca.yaml index 5fb455840417..324e59104360 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcmbca.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcmbca.yaml @@ -28,6 +28,99 @@ properties: - const: brcm,bcm47622 - const: brcm,bcmbca + - description: BCM4912 based boards + items: + - enum: + - asus,gt-ax6000 + - brcm,bcm94912 + - const: brcm,bcm4912 + - const: brcm,bcmbca + + - description: BCM63138 based boards + items: + - enum: + - brcm,bcm963138 + - brcm,BCM963138DVT + - const: brcm,bcm63138 + - const: brcm,bcmbca + + - description: BCM63146 based boards + items: + - enum: + - brcm,bcm963146 + - const: brcm,bcm63146 + - const: brcm,bcmbca + + - description: BCM63148 based boards + items: + - enum: + - brcm,bcm963148 + - const: brcm,bcm63148 + - const: brcm,bcmbca + + - description: BCM63158 based boards + items: + - enum: + - brcm,bcm963158 + - const: brcm,bcm63158 + - const: brcm,bcmbca + + - description: BCM63178 based boards + items: + - enum: + - brcm,bcm963178 + - const: brcm,bcm63178 + - const: brcm,bcmbca + + - description: BCM6756 based boards + items: + - enum: + - brcm,bcm96756 + - const: brcm,bcm6756 + - const: brcm,bcmbca + + - description: BCM6813 based boards + items: + - enum: + - brcm,bcm96813 + - const: brcm,bcm6813 + - const: brcm,bcmbca + + - description: BCM6846 based boards + items: + - enum: + - brcm,bcm96846 + - const: brcm,bcm6846 + - const: brcm,bcmbca + + - description: BCM6855 based boards + items: + - enum: + - brcm,bcm96855 + - const: brcm,bcm6855 + - const: brcm,bcmbca + + - description: BCM6856 based boards + items: + - enum: + - brcm,bcm96856 + - const: brcm,bcm6856 + - const: brcm,bcmbca + + - description: BCM6858 based boards + items: + - enum: + - brcm,bcm96858 + - const: brcm,bcm6858 + - const: brcm,bcmbca + + - description: BCM6878 based boards + items: + - enum: + - brcm,bcm96878 + - const: brcm,bcm6878 + - const: brcm,bcmbca + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/arm/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml index ed04650291a8..5c2e3a5f3789 100644 --- a/Documentation/devicetree/bindings/arm/cpus.yaml +++ b/Documentation/devicetree/bindings/arm/cpus.yaml @@ -221,6 +221,7 @@ properties: - qcom,kpss-acc-v1 - qcom,kpss-acc-v2 - qcom,msm8226-smp + - qcom,msm8909-smp # Only valid on ARM 32-bit, see above for ARM v8 64-bit - qcom,msm8916-smp - renesas,apmu diff --git a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt deleted file mode 100644 index a87ec15e28d2..000000000000 --- a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt +++ /dev/null @@ -1,271 +0,0 @@ -NXP i.MX System Controller Firmware (SCFW) --------------------------------------------------------------------- - -The System Controller Firmware (SCFW) is a low-level system function -which runs on a dedicated Cortex-M core to provide power, clock, and -resource management. It exists on some i.MX8 processors. e.g. i.MX8QM -(QM, QP), and i.MX8QX (QXP, DX). - -The AP communicates with the SC using a multi-ported MU module found -in the LSIO subsystem. The current definition of this MU module provides -5 remote AP connections to the SC to support up to 5 execution environments -(TZ, HV, standard Linux, etc.). The SC side of this MU module interfaces -with the LSIO DSC IP bus. The SC firmware will communicate with this MU -using the MSI bus. - -System Controller Device Node: -============================================================ - -The scu node with the following properties shall be under the /firmware/ node. - -Required properties: -------------------- -- compatible: should be "fsl,imx-scu". -- mbox-names: should include "tx0", "tx1", "tx2", "tx3", - "rx0", "rx1", "rx2", "rx3"; - include "gip3" if want to support general MU interrupt. -- mboxes: List of phandle of 4 MU channels for tx, 4 MU channels for - rx, and 1 optional MU channel for general interrupt. - All MU channels must be in the same MU instance. - Cross instances are not allowed. The MU instance can only - be one of LSIO MU0~M4 for imx8qxp and imx8qm. Users need - to make sure use the one which is not conflict with other - execution environments. e.g. ATF. - Note: - Channel 0 must be "tx0" or "rx0". - Channel 1 must be "tx1" or "rx1". - Channel 2 must be "tx2" or "rx2". - Channel 3 must be "tx3" or "rx3". - General interrupt rx channel must be "gip3". - e.g. - mboxes = <&lsio_mu1 0 0 - &lsio_mu1 0 1 - &lsio_mu1 0 2 - &lsio_mu1 0 3 - &lsio_mu1 1 0 - &lsio_mu1 1 1 - &lsio_mu1 1 2 - &lsio_mu1 1 3 - &lsio_mu1 3 3>; - See Documentation/devicetree/bindings/mailbox/fsl,mu.yaml - for detailed mailbox binding. - -Note: Each mu which supports general interrupt should have an alias correctly -numbered in "aliases" node. -e.g. -aliases { - mu1 = &lsio_mu1; -}; - -i.MX SCU Client Device Node: -============================================================ - -Client nodes are maintained as children of the relevant IMX-SCU device node. - -Power domain bindings based on SCU Message Protocol ------------------------------------------------------------- - -This binding for the SCU power domain providers uses the generic power -domain binding[2]. - -Required properties: -- compatible: Should be one of: - "fsl,imx8qm-scu-pd", - "fsl,imx8qxp-scu-pd" - followed by "fsl,scu-pd" - -- #power-domain-cells: Must be 1. Contains the Resource ID used by - SCU commands. - See detailed Resource ID list from: - include/dt-bindings/firmware/imx/rsrc.h - -Clock bindings based on SCU Message Protocol ------------------------------------------------------------- - -This binding uses the common clock binding[1]. - -Required properties: -- compatible: Should be one of: - "fsl,imx8dxl-clk" - "fsl,imx8qm-clk" - "fsl,imx8qxp-clk" - followed by "fsl,scu-clk" -- #clock-cells: Should be 2. - Contains the Resource and Clock ID value. -- clocks: List of clock specifiers, must contain an entry for - each required entry in clock-names -- clock-names: Should include entries "xtal_32KHz", "xtal_24MHz" - -The clock consumer should specify the desired clock by having the clock -ID in its "clocks" phandle cell. - -See the full list of clock IDs from: -include/dt-bindings/clock/imx8qxp-clock.h - -Pinctrl bindings based on SCU Message Protocol ------------------------------------------------------------- - -This binding uses the i.MX common pinctrl binding[3]. - -Required properties: -- compatible: Should be one of: - "fsl,imx8qm-iomuxc", - "fsl,imx8qxp-iomuxc", - "fsl,imx8dxl-iomuxc". - -Required properties for Pinctrl sub nodes: -- fsl,pins: Each entry consists of 3 integers which represents - the mux and config setting for one pin. The first 2 - integers <pin_id mux_mode> are specified using a - PIN_FUNC_ID macro, which can be found in - <dt-bindings/pinctrl/pads-imx8qm.h>, - <dt-bindings/pinctrl/pads-imx8qxp.h>, - <dt-bindings/pinctrl/pads-imx8dxl.h>. - The last integer CONFIG is the pad setting value like - pull-up on this pin. - - Please refer to i.MX8QXP Reference Manual for detailed - CONFIG settings. - -[1] Documentation/devicetree/bindings/clock/clock-bindings.txt -[2] Documentation/devicetree/bindings/power/power-domain.yaml -[3] Documentation/devicetree/bindings/pinctrl/fsl,imx-pinctrl.txt - -RTC bindings based on SCU Message Protocol ------------------------------------------------------------- - -Required properties: -- compatible: should be "fsl,imx8qxp-sc-rtc"; - -OCOTP bindings based on SCU Message Protocol ------------------------------------------------------------- -Required properties: -- compatible: Should be one of: - "fsl,imx8qm-scu-ocotp", - "fsl,imx8qxp-scu-ocotp". -- #address-cells: Must be 1. Contains byte index -- #size-cells: Must be 1. Contains byte length - -Optional Child nodes: - -- Data cells of ocotp: - Detailed bindings are described in bindings/nvmem/nvmem.txt - -Watchdog bindings based on SCU Message Protocol ------------------------------------------------------------- - -Required properties: -- compatible: should be: - "fsl,imx8qxp-sc-wdt" - followed by "fsl,imx-sc-wdt"; -Optional properties: -- timeout-sec: contains the watchdog timeout in seconds. - -SCU key bindings based on SCU Message Protocol ------------------------------------------------------------- - -Required properties: -- compatible: should be: - "fsl,imx8qxp-sc-key" - followed by "fsl,imx-sc-key"; -- linux,keycodes: See Documentation/devicetree/bindings/input/input.yaml - -Thermal bindings based on SCU Message Protocol ------------------------------------------------------------- - -Required properties: -- compatible: Should be : - "fsl,imx8qxp-sc-thermal" - followed by "fsl,imx-sc-thermal"; - -- #thermal-sensor-cells: See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml - for a description. - -Example (imx8qxp): -------------- -aliases { - mu1 = &lsio_mu1; -}; - -lsio_mu1: mailbox@5d1c0000 { - ... - #mbox-cells = <2>; -}; - -firmware { - scu { - compatible = "fsl,imx-scu"; - mbox-names = "tx0", "tx1", "tx2", "tx3", - "rx0", "rx1", "rx2", "rx3", - "gip3"; - mboxes = <&lsio_mu1 0 0 - &lsio_mu1 0 1 - &lsio_mu1 0 2 - &lsio_mu1 0 3 - &lsio_mu1 1 0 - &lsio_mu1 1 1 - &lsio_mu1 1 2 - &lsio_mu1 1 3 - &lsio_mu1 3 3>; - - clk: clk { - compatible = "fsl,imx8qxp-clk", "fsl,scu-clk"; - #clock-cells = <2>; - }; - - iomuxc { - compatible = "fsl,imx8qxp-iomuxc"; - - pinctrl_lpuart0: lpuart0grp { - fsl,pins = < - SC_P_UART0_RX_ADMA_UART0_RX 0x06000020 - SC_P_UART0_TX_ADMA_UART0_TX 0x06000020 - >; - }; - ... - }; - - ocotp: imx8qx-ocotp { - compatible = "fsl,imx8qxp-scu-ocotp"; - #address-cells = <1>; - #size-cells = <1>; - - fec_mac0: mac@2c4 { - reg = <0x2c4 8>; - }; - }; - - pd: imx8qx-pd { - compatible = "fsl,imx8qxp-scu-pd", "fsl,scu-pd"; - #power-domain-cells = <1>; - }; - - rtc: rtc { - compatible = "fsl,imx8qxp-sc-rtc"; - }; - - scu_key: scu-key { - compatible = "fsl,imx8qxp-sc-key", "fsl,imx-sc-key"; - linux,keycodes = <KEY_POWER>; - }; - - watchdog { - compatible = "fsl,imx8qxp-sc-wdt", "fsl,imx-sc-wdt"; - timeout-sec = <60>; - }; - - tsens: thermal-sensor { - compatible = "fsl,imx8qxp-sc-thermal", "fsl,imx-sc-thermal"; - #thermal-sensor-cells = <1>; - }; - }; -}; - -serial@5a060000 { - ... - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_lpuart0>; - clocks = <&uart0_clk IMX_SC_R_UART_0 IMX_SC_PM_CLK_PER>; - clock-names = "ipg"; - power-domains = <&pd IMX_SC_R_UART_0>; -}; diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index ef524378d449..7431579ab0e8 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -321,6 +321,7 @@ properties: - enum: - toradex,apalis_imx6q-ixora # Apalis iMX6Q/D Module on Ixora Carrier Board - toradex,apalis_imx6q-ixora-v1.1 # Apalis iMX6Q/D Module on Ixora V1.1 Carrier Board + - toradex,apalis_imx6q-ixora-v1.2 # Apalis iMX6Q/D Module on Ixora V1.2 Carrier Board - toradex,apalis_imx6q-eval # Apalis iMX6Q/D Module on Apalis Evaluation Board - const: toradex,apalis_imx6q - const: fsl,imx6q @@ -670,30 +671,30 @@ properties: - description: i.MX6ULL Boards with Toradex Colibri iMX6ULL Modules items: - enum: - - toradex,colibri-imx6ull-aster # Colibri iMX6ULL Module on Aster Carrier Board - - toradex,colibri-imx6ull-eval # Colibri iMX6ULL Module on Colibri Evaluation Board V3 - - toradex,colibri-imx6ull-iris # Colibri iMX6ULL Module on Iris Carrier Board - - toradex,colibri-imx6ull-iris-v2 # Colibri iMX6ULL Module on Iris V2 Carrier Board + - toradex,colibri-imx6ull-aster # Aster Carrier Board + - toradex,colibri-imx6ull-eval # Colibri Evaluation Board V3 + - toradex,colibri-imx6ull-iris # Iris Carrier Board + - toradex,colibri-imx6ull-iris-v2 # Iris V2 Carrier Board - const: toradex,colibri-imx6ull # Colibri iMX6ULL Module - const: fsl,imx6ull - description: i.MX6ULL Boards with Toradex Colibri iMX6ULL 1GB (eMMC) Module items: - enum: - - toradex,colibri-imx6ull-emmc-aster # Colibri iMX6ULL 1G (eMMC) on Aster Carrier Board - - toradex,colibri-imx6ull-emmc-eval # Colibri iMX6ULL 1G (eMMC) on Colibri Evaluation B. V3 - - toradex,colibri-imx6ull-emmc-iris # Colibri iMX6ULL 1G (eMMC) on Iris Carrier Board - - toradex,colibri-imx6ull-emmc-iris-v2 # Colibri iMX6ULL 1G (eMMC) on Iris V2 Carrier Board + - toradex,colibri-imx6ull-emmc-aster # Aster Carrier Board + - toradex,colibri-imx6ull-emmc-eval # Colibri Evaluation B. V3 + - toradex,colibri-imx6ull-emmc-iris # Iris Carrier Board + - toradex,colibri-imx6ull-emmc-iris-v2 # Iris V2 Carrier Board - const: toradex,colibri-imx6ull-emmc # Colibri iMX6ULL 1GB (eMMC) Module - const: fsl,imx6ull - description: i.MX6ULL Boards with Toradex Colibri iMX6ULL Wi-Fi / BT Modules items: - enum: - - toradex,colibri-imx6ull-wifi-eval # Colibri iMX6ULL Wi-Fi / BT M. on Colibri Eval. B. V3 - - toradex,colibri-imx6ull-wifi-aster # Colibri iMX6ULL Wi-Fi / BT M. on Aster Carrier Board - - toradex,colibri-imx6ull-wifi-iris # Colibri iMX6ULL Wi-Fi / BT M. on Iris Carrier Board - - toradex,colibri-imx6ull-wifi-iris-v2 # Colibri iMX6ULL Wi-Fi / BT M. on Iris V2 Carrier Board + - toradex,colibri-imx6ull-wifi-eval # Colibri Eval. B. V3 + - toradex,colibri-imx6ull-wifi-aster # Aster Carrier Board + - toradex,colibri-imx6ull-wifi-iris # Iris Carrier Board + - toradex,colibri-imx6ull-wifi-iris-v2 # Iris V2 Carrier Board - const: toradex,colibri-imx6ull-wifi # Colibri iMX6ULL Wi-Fi / BT Module - const: fsl,imx6ull @@ -738,6 +739,8 @@ properties: - enum: - toradex,colibri-imx7s-aster # Module on Aster Carrier Board - toradex,colibri-imx7s-eval-v3 # Module on Colibri Evaluation Board V3 + - toradex,colibri-imx7s-iris # Module on Iris Carrier Board + - toradex,colibri-imx7s-iris-v2 # Module on Iris Carrier Board V2 - const: toradex,colibri-imx7s - const: fsl,imx7s @@ -789,8 +792,10 @@ properties: - description: i.MX7D Boards with Toradex Colibri i.MX7D Module items: - enum: - - toradex,colibri-imx7d-aster # Colibri iMX7D Module on Aster Carrier Board - - toradex,colibri-imx7d-eval-v3 # Colibri iMX7D Module on Colibri Evaluation Board V3 + - toradex,colibri-imx7d-aster # Aster Carrier Board + - toradex,colibri-imx7d-eval-v3 # Colibri Evaluation Board V3 + - toradex,colibri-imx7d-iris # Iris Carrier Board + - toradex,colibri-imx7d-iris-v2 # Iris Carrier Board V2 - const: toradex,colibri-imx7d - const: fsl,imx7d @@ -799,6 +804,8 @@ properties: - enum: - toradex,colibri-imx7d-emmc-aster # Module on Aster Carrier Board - toradex,colibri-imx7d-emmc-eval-v3 # Module on Colibri Evaluation Board V3 + - toradex,colibri-imx7d-emmc-iris # Module on Iris Carrier Board + - toradex,colibri-imx7d-emmc-iris-v2 # Module on Iris Carrier Board V2 - const: toradex,colibri-imx7d-emmc - const: fsl,imx7d @@ -865,6 +872,12 @@ properties: - const: toradex,verdin-imx8mm # Verdin iMX8M Mini Module - const: fsl,imx8mm + - description: PHYTEC phyCORE-i.MX8MM SoM based boards + items: + - const: phytec,imx8mm-phyboard-polis-rdk # phyBOARD-Polis RDK + - const: phytec,imx8mm-phycore-som # phyCORE-i.MX8MM SoM + - const: fsl,imx8mm + - description: Variscite VAR-SOM-MX8MM based boards items: - const: variscite,var-som-mx8mm-symphony @@ -914,6 +927,8 @@ properties: - description: i.MX8MP based Boards items: - enum: + - dh,imx8mp-dhcom-som # i.MX8MP DHCOM SoM + - dh,imx8mp-dhcom-pdk2 # i.MX8MP DHCOM SoM on PDK2 board - fsl,imx8mp-evk # i.MX8MP EVK Board - gateworks,imx8mp-gw74xx # i.MX8MP Gateworks Board - toradex,verdin-imx8mp # Verdin iMX8M Plus Modules @@ -952,6 +967,18 @@ properties: - const: toradex,verdin-imx8mp # Verdin iMX8M Plus Module - const: fsl,imx8mp + - description: + TQMa8MPxL is a series of LGA SOM featuring NXP i.MX8MP system-on-chip + variants. It is designed to be soldered on different carrier boards. + All CPU variants use the same device tree hence only one compatible + is needed. MBa8MPxL mainboard can be used as starterkit or in a boxed + version as an industrial computing device. + items: + - enum: + - tq,imx8mp-tqma8mpql-mba8mpxl # TQ-Systems GmbH i.MX8MP TQMa8MPQL SOM on MBa8MPxL + - const: tq,imx8mp-tqma8mpql # TQ-Systems GmbH i.MX8MP TQMa8MPQL SOM + - const: fsl,imx8mp + - description: i.MX8MQ based Boards items: - enum: @@ -1020,6 +1047,12 @@ properties: - fsl,imx8ulp-evk # i.MX8ULP EVK Board - const: fsl,imx8ulp + - description: i.MX93 based Boards + items: + - enum: + - fsl,imx93-11x11-evk # i.MX93 11x11 EVK Board + - const: fsl,imx93 + - description: Freescale Vybrid Platform Device Tree Bindings diff --git a/Documentation/devicetree/bindings/arm/marvell/marvell,ac5.yaml b/Documentation/devicetree/bindings/arm/marvell/marvell,ac5.yaml new file mode 100644 index 000000000000..8960fb8b2b2f --- /dev/null +++ b/Documentation/devicetree/bindings/arm/marvell/marvell,ac5.yaml @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/marvell/marvell,ac5.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell Alleycat5/5X Platforms + +maintainers: + - Chris Packham <chris.packham@alliedtelesis.co.nz> + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - description: Alleycat5 (98DX25xx) Reference Design + items: + - enum: + - marvell,rd-ac5 + - const: marvell,ac5 + + - description: Alleycat5X (98DX35xx) Reference Design + items: + - enum: + - marvell,rd-ac5x + - const: marvell,ac5x + - const: marvell,ac5 + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml index 4a2bd9759c47..07c0ea94e850 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek.yaml @@ -131,6 +131,36 @@ properties: - enum: - mediatek,mt8183-evb - const: mediatek,mt8183 + - description: Google Hayato + items: + - const: google,hayato-rev1 + - const: google,hayato + - const: mediatek,mt8192 + - description: Google Spherion (Acer Chromebook 514) + items: + - const: google,spherion-rev3 + - const: google,spherion-rev2 + - const: google,spherion-rev1 + - const: google,spherion-rev0 + - const: google,spherion + - const: mediatek,mt8192 + - description: Acer Tomato (Acer Chromebook Spin 513 CP513-2H) + items: + - enum: + - google,tomato-rev2 + - google,tomato-rev1 + - const: google,tomato + - const: mediatek,mt8195 + - description: Acer Tomato rev3 - 4 (Acer Chromebook Spin 513 CP513-2H) + items: + - const: google,tomato-rev4 + - const: google,tomato-rev3 + - const: google,tomato + - const: mediatek,mt8195 + - items: + - enum: + - mediatek,mt8186-evb + - const: mediatek,mt8186 - items: - enum: - mediatek,mt8192-evb diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.yaml b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.yaml index 611f666f359d..8585f6f18f69 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.yaml @@ -26,6 +26,7 @@ properties: - mediatek,mt8135-pericfg - mediatek,mt8173-pericfg - mediatek,mt8183-pericfg + - mediatek,mt8186-pericfg - mediatek,mt8195-pericfg - mediatek,mt8516-pericfg - const: syscon diff --git a/Documentation/devicetree/bindings/arm/npcm/npcm.yaml b/Documentation/devicetree/bindings/arm/npcm/npcm.yaml index 95e51378089c..43409e5721d5 100644 --- a/Documentation/devicetree/bindings/arm/npcm/npcm.yaml +++ b/Documentation/devicetree/bindings/arm/npcm/npcm.yaml @@ -8,6 +8,7 @@ title: NPCM Platforms Device Tree Bindings maintainers: - Jonathan Neuschäfer <j.neuschaefer@gmx.net> + - Tomer Maimon <tmaimon77@gmail.com> properties: $nodename: @@ -26,4 +27,10 @@ properties: - nuvoton,npcm750-evb # NPCM750 evaluation board - const: nuvoton,npcm750 + - description: NPCM845 based boards + items: + - enum: + - nuvoton,npcm845-evb # NPCM845 evaluation board + - const: nuvoton,npcm845 + additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/npcm/nuvoton,gcr.yaml b/Documentation/devicetree/bindings/arm/npcm/nuvoton,gcr.yaml index fcb211add7d3..94e72f25b331 100644 --- a/Documentation/devicetree/bindings/arm/npcm/nuvoton,gcr.yaml +++ b/Documentation/devicetree/bindings/arm/npcm/nuvoton,gcr.yaml @@ -8,6 +8,7 @@ title: Global Control Registers block in Nuvoton SoCs maintainers: - Jonathan Neuschäfer <j.neuschaefer@gmx.net> + - Tomer Maimon <tmaimon77@gmail.com> description: The Global Control Registers (GCR) are a block of registers in Nuvoton SoCs @@ -20,6 +21,7 @@ properties: - enum: - nuvoton,wpcm450-gcr - nuvoton,npcm750-gcr + - nuvoton,npcm845-gcr - const: syscon - const: simple-mfd diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index 5c06d1bfc046..fb1d00bcc847 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: QCOM device tree bindings maintainers: - - Stephen Boyd <sboyd@codeaurora.org> + - Bjorn Andersson <bjorn.andersson@linaro.org> description: | Some qcom based bootloaders identify the dtb blob based on a set of @@ -38,18 +38,24 @@ description: | msm8992 msm8994 msm8996 + msm8998 + qcs404 sa8155p sa8540p sc7180 sc7280 sc8180x sc8280xp + sda660 sdm630 sdm632 + sdm636 sdm660 sdm845 sdx55 sdx65 + sm6125 + sm6350 sm7225 sm8150 sm8250 @@ -90,6 +96,11 @@ description: | A dragonboard board v0.1 of subtype 1 with an apq8074 SoC version 2, made in foundry 2. + There are many devices in the list below that run the standard ChromeOS + bootloader setup and use the open source depthcharge bootloader to boot the + OS. These devices do not use the scheme described above. For details, see: + https://docs.kernel.org/arm/google/chromebook-boot-flow.html + properties: $nodename: const: "/" @@ -153,28 +164,50 @@ properties: - const: qcom,msm8974 - items: - - enum: - - alcatel,idol347 - - const: qcom,msm8916-mtp/1 - const: qcom,msm8916-mtp + - const: qcom,msm8916-mtp/1 - const: qcom,msm8916 - items: - enum: - - longcheer,l8150 + - alcatel,idol347 + - asus,z00l + - huawei,g7 + - longcheer,l8910 - samsung,a3u-eur - samsung,a5u-eur + - samsung,j5 + - samsung,serranove + - wingtech,wt88047 + - const: qcom,msm8916 + + - items: + - const: longcheer,l8150 + - const: qcom,msm8916-v1-qrd/9-v1 - const: qcom,msm8916 - items: - enum: + - lg,bullhead + - microsoft,talkman + - xiaomi,libra + - const: qcom,msm8992 + + - items: + - enum: - sony,karin_windy + - const: qcom,apq8094 + + - items: + - enum: + - huawei,angler + - microsoft,cityman + - sony,ivy-row - sony,karin-row - sony,satsuki-row - sony,sumire-row - sony,suzuran-row - - qcom,msm8994 - - const: qcom,apq8094 + - const: qcom,msm8994 - items: - enum: @@ -190,11 +223,26 @@ properties: - sony,kagura-row - sony,keyaki-row - xiaomi,gemini + - xiaomi,natrium - xiaomi,scorpio - const: qcom,msm8996 - items: - enum: + - asus,novago-tp370ql + - fxtec,pro1 + - hp,envy-x2 + - lenovo,miix-630 + - oneplus,cheeseburger + - oneplus,dumpling + - qcom,msm8998-mtp + - sony,xperia-lilac + - sony,xperia-maple + - sony,xperia-poplar + - const: qcom,msm8998 + + - items: + - enum: - qcom,ipq4019-ap-dk01.1-c1 - qcom,ipq4019-ap-dk04.1-c3 - qcom,ipq4019-ap-dk07.1-c1 @@ -214,19 +262,317 @@ properties: - qcom,ipq8074-hk10-c2 - const: qcom,ipq8074 - - items: + - description: Qualcomm Technologies, Inc. SC7180 IDP + items: - enum: - qcom,sc7180-idp - const: qcom,sc7180 - - items: - - enum: - - qcom,sc7280-crd - - qcom,sc7280-idp - - qcom,sc7280-idp2 - - google,hoglin - - google,piglin - - google,senor + - description: HP Chromebook x2 11c (rev1 - 2) + items: + - const: google,coachz-rev1 + - const: google,coachz-rev2 + - const: qcom,sc7180 + + - description: HP Chromebook x2 11c (newest rev) + items: + - const: google,coachz + - const: qcom,sc7180 + + - description: HP Chromebook x2 11c with LTE (rev1 - 2) + items: + - const: google,coachz-rev1-sku0 + - const: google,coachz-rev2-sku0 + - const: qcom,sc7180 + + - description: HP Chromebook x2 11c with LTE (newest rev) + items: + - const: google,coachz-sku0 + - const: qcom,sc7180 + + - description: Lenovo Chromebook Duet 5 13 (rev2) + items: + - const: google,homestar-rev2 + - const: google,homestar-rev23 + - const: qcom,sc7180 + + - description: Lenovo Chromebook Duet 5 13 (rev3) + items: + - const: google,homestar-rev3 + - const: qcom,sc7180 + + - description: Lenovo Chromebook Duet 5 13 (newest rev) + items: + - const: google,homestar + - const: qcom,sc7180 + + - description: Google Kingoftown (rev0) + items: + - const: google,kingoftown-rev0 + - const: qcom,sc7180 + + - description: Google Kingoftown (newest rev) + items: + - const: google,kingoftown + - const: qcom,sc7180 + + - description: Acer Chromebook Spin 513 (rev0) + items: + - const: google,lazor-rev0 + - const: qcom,sc7180 + + - description: Acer Chromebook Spin 513 (rev1 - 2) + items: + - const: google,lazor-rev1 + - const: google,lazor-rev2 + - const: qcom,sc7180 + + - description: Acer Chromebook Spin 513 (rev3 - 8) + items: + - const: google,lazor-rev3 + - const: google,lazor-rev4 + - const: google,lazor-rev5 + - const: google,lazor-rev6 + - const: google,lazor-rev7 + - const: google,lazor-rev8 + - const: qcom,sc7180 + + - description: Acer Chromebook Spin 513 (newest rev) + items: + - const: google,lazor + - const: qcom,sc7180 + + - description: Acer Chromebook Spin 513 with KB Backlight (rev1 - 2) + items: + - const: google,lazor-rev1-sku2 + - const: google,lazor-rev2-sku2 + - const: qcom,sc7180 + + - description: Acer Chromebook Spin 513 with KB Backlight (rev3 - 8) + items: + - const: google,lazor-rev3-sku2 + - const: google,lazor-rev4-sku2 + - const: google,lazor-rev5-sku2 + - const: google,lazor-rev6-sku2 + - const: google,lazor-rev7-sku2 + - const: google,lazor-rev8-sku2 + - const: qcom,sc7180 + + - description: Acer Chromebook Spin 513 with KB Backlight (newest rev) + items: + - const: google,lazor-sku2 + - const: qcom,sc7180 + + - description: Acer Chromebook Spin 513 with LTE (rev1 - 2) + items: + - const: google,lazor-rev1-sku0 + - const: google,lazor-rev2-sku0 + - const: qcom,sc7180 + + - description: Acer Chromebook Spin 513 with LTE (rev3 - 8) + items: + - const: google,lazor-rev3-sku0 + - const: google,lazor-rev4-sku0 + - const: google,lazor-rev5-sku0 + - const: google,lazor-rev6-sku0 + - const: google,lazor-rev7-sku0 + - const: google,lazor-rev8-sku0 + - const: qcom,sc7180 + + - description: Acer Chromebook Spin 513 with LTE (newest rev) + items: + - const: google,lazor-sku0 + - const: qcom,sc7180 + + - description: Acer Chromebook 511 (rev4 - rev8) + items: + - const: google,lazor-rev4-sku4 + - const: google,lazor-rev5-sku4 + - const: google,lazor-rev6-sku4 + - const: google,lazor-rev7-sku4 + - const: google,lazor-rev8-sku4 + - const: qcom,sc7180 + + - description: Acer Chromebook 511 (newest rev) + items: + - const: google,lazor-sku4 + - const: qcom,sc7180 + + - description: Acer Chromebook 511 without Touchscreen (rev4) + items: + - const: google,lazor-rev4-sku5 + - const: qcom,sc7180 + + - description: Acer Chromebook 511 without Touchscreen (rev5 - rev8) + items: + - const: google,lazor-rev5-sku5 + - const: google,lazor-rev5-sku6 + - const: google,lazor-rev6-sku6 + - const: google,lazor-rev7-sku6 + - const: google,lazor-rev8-sku6 + - const: qcom,sc7180 + + - description: Acer Chromebook 511 without Touchscreen (newest rev) + items: + - const: google,lazor-sku6 + - const: qcom,sc7180 + + - description: Google Mrbland with AUO panel (rev0) + items: + - const: google,mrbland-rev0-sku0 + - const: qcom,sc7180 + + - description: Google Mrbland with AUO panel (newest rev) + items: + - const: google,mrbland-sku1536 + - const: qcom,sc7180 + + - description: Google Mrbland with BOE panel (rev0) + items: + - const: google,mrbland-rev0-sku16 + - const: qcom,sc7180 + + - description: Google Mrbland with BOE panel (newest rev) + items: + - const: google,mrbland-sku1024 + - const: google,mrbland-sku768 + - const: qcom,sc7180 + + - description: Google Pazquel with Parade (newest rev) + items: + - const: google,pazquel-sku5 + - const: qcom,sc7180 + + - description: Google Pazquel with TI (newest rev) + items: + - const: google,pazquel-sku1 + - const: qcom,sc7180 + + - description: Google Pazquel with LTE and Parade (newest rev) + items: + - const: google,pazquel-sku4 + - const: qcom,sc7180 + + - description: Google Pazquel with LTE and TI (newest rev) + items: + - const: google,pazquel-sku0 + - const: google,pazquel-sku2 + - const: qcom,sc7180 + + - description: Sharp Dynabook Chromebook C1 (rev1) + items: + - const: google,pompom-rev1 + - const: qcom,sc7180 + + - description: Sharp Dynabook Chromebook C1 (rev2) + items: + - const: google,pompom-rev2 + - const: qcom,sc7180 + + - description: Sharp Dynabook Chromebook C1 (newest rev) + items: + - const: google,pompom + - const: qcom,sc7180 + + - description: Sharp Dynabook Chromebook C1 with LTE (rev1) + items: + - const: google,pompom-rev1-sku0 + - const: qcom,sc7180 + + - description: Sharp Dynabook Chromebook C1 with LTE (rev2) + items: + - const: google,pompom-rev2-sku0 + - const: qcom,sc7180 + + - description: Sharp Dynabook Chromebook C1 with LTE (newest rev) + items: + - const: google,pompom-sku0 + - const: qcom,sc7180 + + - description: Google Quackingstick (newest rev) + items: + - const: google,quackingstick-sku1537 + - const: qcom,sc7180 + + - description: Google Quackingstick with LTE (newest rev) + items: + - const: google,quackingstick-sku1536 + - const: qcom,sc7180 + + - description: Google Trogdor (newest rev) + items: + - const: google,trogdor + - const: qcom,sc7180 + + - description: Google Trogdor with LTE (newest rev) + items: + - const: google,trogdor-sku0 + - const: qcom,sc7180 + + - description: Lenovo IdeaPad Chromebook Duet 3 with BOE panel (rev0) + items: + - const: google,wormdingler-rev0-sku16 + - const: qcom,sc7180 + + - description: Lenovo IdeaPad Chromebook Duet 3 with BOE panel (newest rev) + items: + - const: google,wormdingler-sku1024 + - const: qcom,sc7180 + + - description: Lenovo IdeaPad Chromebook Duet 3 with BOE panel and rt5682s (newest rev) + items: + - const: google,wormdingler-sku1025 + - const: qcom,sc7180 + + - description: Lenovo IdeaPad Chromebook Duet 3 with INX panel (rev0) + items: + - const: google,wormdingler-rev0-sku0 + - const: qcom,sc7180 + + - description: Lenovo IdeaPad Chromebook Duet 3 with INX panel (newest rev) + items: + - const: google,wormdingler-sku0 + - const: qcom,sc7180 + + - description: Lenovo IdeaPad Chromebook Duet 3 with INX panel and rt5682s (newest rev) + items: + - const: google,wormdingler-sku1 + - const: qcom,sc7180 + + - description: Qualcomm Technologies, Inc. sc7280 CRD platform (rev3 - 4) + items: + - const: qcom,sc7280-crd + - const: google,hoglin-rev3 + - const: google,hoglin-rev4 + - const: google,piglin-rev3 + - const: google,piglin-rev4 + - const: qcom,sc7280 + + - description: Qualcomm Technologies, Inc. sc7280 CRD platform (newest rev) + items: + - const: google,hoglin + - const: qcom,sc7280 + + - description: Qualcomm Technologies, Inc. sc7280 IDP SKU1 platform + items: + - const: qcom,sc7280-idp + - const: google,senor + - const: qcom,sc7280 + + - description: Qualcomm Technologies, Inc. sc7280 IDP SKU2 platform + items: + - const: qcom,sc7280-idp2 + - const: google,piglin + - const: qcom,sc7280 + + - description: Google Herobrine (newest rev) + items: + - const: google,herobrine + - const: qcom,sc7280 + + - description: Google Villager (newest rev) + items: + - const: google,villager - const: qcom,sc7280 - items: @@ -238,16 +584,36 @@ properties: - items: - enum: + - lenovo,thinkpad-x13s + - qcom,sc8280xp-crd - qcom,sc8280xp-qrd - const: qcom,sc8280xp - items: - enum: + - sony,discovery-row + - sony,kirin-row + - sony,pioneer-row + - sony,voyager-row + - const: qcom,sdm630 + + - items: + - enum: + - inforce,ifc6560 + - const: qcom,sda660 + + - items: + - enum: - fairphone,fp3 - const: qcom,sdm632 - items: - enum: + - sony,mermaid-row + - const: qcom,sdm636 + + - items: + - enum: - xiaomi,lavender - const: qcom,sdm660 @@ -271,6 +637,13 @@ properties: - items: - enum: + - qcom,qcs404-evb-1000 + - qcom,qcs404-evb-4000 + - const: qcom,qcs404-evb + - const: qcom,qcs404 + + - items: + - enum: - qcom,sa8155p-adp - const: qcom,sa8155p @@ -281,24 +654,62 @@ properties: - items: - enum: + - lenovo,yoga-c630 + - lg,judyln + - lg,judyp + - oneplus,enchilada + - oneplus,fajita + - qcom,sdm845-mtp + - shift,axolotl + - samsung,w737 + - sony,akari-row + - sony,akatsuki-row + - sony,apollo-row + - thundercomm,db845c + - xiaomi,beryllium + - xiaomi,polaris + - const: qcom,sdm845 + + - items: + - enum: + - sony,pdx201 + - const: qcom,sm6125 + + - items: + - enum: + - sony,pdx213 + - const: qcom,sm6350 + + - items: + - enum: - fairphone,fp4 - const: qcom,sm7225 - items: - enum: + - microsoft,surface-duo + - qcom,sm8150-hdk - qcom,sm8150-mtp + - sony,bahamut-generic + - sony,griffin-generic - const: qcom,sm8150 - items: - enum: - qcom,qrb5165-rb5 + - qcom,sm8250-hdk - qcom,sm8250-mtp + - sony,pdx203-generic + - sony,pdx206-generic - const: qcom,sm8250 - items: - enum: + - microsoft,surface-duo2 - qcom,sm8350-hdk - qcom,sm8350-mtp + - sony,pdx214-generic + - sony,pdx215-generic - const: qcom,sm8350 - items: diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml index cf9eb1e8326a..7811ba64149c 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -554,6 +554,11 @@ properties: - const: vamrs,rk3399pro-vmarc-som - const: rockchip,rk3399pro + - description: Radxa ROCK Pi S + items: + - const: radxa,rockpis + - const: rockchip,rk3308 + - description: Radxa Rock2 Square items: - const: radxa,rock2-square diff --git a/Documentation/devicetree/bindings/arm/samsung/samsung-soc.yaml b/Documentation/devicetree/bindings/arm/samsung/samsung-soc.yaml new file mode 100644 index 000000000000..653f85997643 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/samsung/samsung-soc.yaml @@ -0,0 +1,40 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/samsung/samsung-soc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung S3C, S5P and Exynos SoC compatibles naming convention + +maintainers: + - Krzysztof Kozlowski <krzk@kernel.org> + +description: | + Guidelines for new compatibles for SoC blocks/components. + When adding new compatibles in new bindings, use the format:: + samsung,SoC-IP + + For example:: + samsung,exynos5433-cmu-isp + +select: + properties: + compatible: + pattern: "^samsung,.*(s3c|s5pv|exynos)[0-9a-z]+.*$" + required: + - compatible + +properties: + compatible: + oneOf: + - description: Preferred naming style for compatibles of SoC components + pattern: "^samsung,(s3c|s5pv|exynos|exynosautov)[0-9]+-.*$" + + # Legacy compatibles with wild-cards - list cannot grow with new bindings: + - enum: + - samsung,exynos4x12-pinctrl + - samsung,exynos4x12-usb2-phy + - samsung,s3c64xx-pinctrl + - samsung,s3c64xx-wakeup-eint + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml index 8b31565fee59..4c605bccc474 100644 --- a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml +++ b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml @@ -59,12 +59,18 @@ properties: - prt,prtt1s # Protonic PRTT1S - const: st,stm32mp151 - - description: DH STM32MP153 SoM based Boards + - description: DH STM32MP153 DHCOM SoM based Boards items: - const: dh,stm32mp153c-dhcom-drc02 - const: dh,stm32mp153c-dhcom-som - const: st,stm32mp153 + - description: DH STM32MP153 DHCOR SoM based Boards + items: + - const: dh,stm32mp153c-dhcor-drc-compact + - const: dh,stm32mp153c-dhcor-som + - const: st,stm32mp153 + - items: - enum: - shiratech,stm32mp157a-iot-box # IoT Box diff --git a/Documentation/devicetree/bindings/arm/sunplus,sp7021.yaml b/Documentation/devicetree/bindings/arm/sunplus,sp7021.yaml new file mode 100644 index 000000000000..def7d0cfeb31 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/sunplus,sp7021.yaml @@ -0,0 +1,29 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) Sunplus Co., Ltd. 2021 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/sunplus,sp7021.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sunplus SP7021 Boards + +maintainers: + - qinjian <qinjian@cqplus1.com> + +description: | + ARM platforms using Sunplus SP7021, an ARM Cortex A7 (4-cores) based SoC. + Wiki: https://sunplus-tibbo.atlassian.net/wiki/spaces/doc/overview + +properties: + $nodename: + const: '/' + compatible: + items: + - enum: + - sunplus,sp7021-achip + - sunplus,sp7021-demo-v3 + - const: sunplus,sp7021 + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml index 95278a6a9a8e..0c2356778208 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -863,6 +863,11 @@ properties: - const: yones-toptech,bs1078-v2 - const: allwinner,sun6i-a31s + - description: X96 Mate TV box + items: + - const: hechuang,x96-mate + - const: allwinner,sun50i-h616 + - description: Xunlong OrangePi items: - const: xunlong,orangepi @@ -963,4 +968,9 @@ properties: - const: xunlong,orangepi-zero-plus2-h3 - const: allwinner,sun8i-h3 + - description: Xunlong OrangePi Zero 2 + items: + - const: xunlong,orangepi-zero2 + - const: allwinner,sun50i-h616 + additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/sunxi/allwinner,sun4i-a10-mbus.yaml b/Documentation/devicetree/bindings/arm/sunxi/allwinner,sun4i-a10-mbus.yaml index 8eee312c2e6f..99566688d033 100644 --- a/Documentation/devicetree/bindings/arm/sunxi/allwinner,sun4i-a10-mbus.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi/allwinner,sun4i-a10-mbus.yaml @@ -29,10 +29,20 @@ properties: compatible: enum: - allwinner,sun5i-a13-mbus + - allwinner,sun8i-a33-mbus + - allwinner,sun8i-a50-mbus + - allwinner,sun8i-a83t-mbus - allwinner,sun8i-h3-mbus - allwinner,sun8i-r40-mbus + - allwinner,sun8i-v3s-mbus + - allwinner,sun8i-v536-mbus + - allwinner,sun20i-d1-mbus - allwinner,sun50i-a64-mbus + - allwinner,sun50i-a100-mbus - allwinner,sun50i-h5-mbus + - allwinner,sun50i-h6-mbus + - allwinner,sun50i-h616-mbus + - allwinner,sun50i-r329-mbus reg: minItems: 1 @@ -81,13 +91,13 @@ required: - dma-ranges if: - properties: - compatible: - contains: - enum: - - allwinner,sun8i-h3-mbus - - allwinner,sun50i-a64-mbus - - allwinner,sun50i-h5-mbus + not: + properties: + compatible: + contains: + enum: + - allwinner,sun5i-a13-mbus + - allwinner,sun8i-r40-mbus then: properties: diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra-ccplex-cluster.yaml b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra-ccplex-cluster.yaml index 8c6543b5c0dc..711bb4d08c60 100644 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra-ccplex-cluster.yaml +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra-ccplex-cluster.yaml @@ -40,7 +40,6 @@ required: - compatible - reg - nvidia,bpmp - - status examples: - | diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra194-axi2apb.yaml b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra194-axi2apb.yaml new file mode 100644 index 000000000000..788a13f8aa93 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra194-axi2apb.yaml @@ -0,0 +1,40 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/arm/tegra/nvidia,tegra194-axi2apb.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: NVIDIA Tegra194 AXI2APB bridge + +maintainers: + - Sumit Gupta <sumitg@nvidia.com> + +properties: + $nodename: + pattern: "^axi2apb@([0-9a-f]+)$" + + compatible: + enum: + - nvidia,tegra194-axi2apb + + reg: + maxItems: 6 + description: Physical base address and length of registers for all bridges + +additionalProperties: false + +required: + - compatible + - reg + +examples: + - | + axi2apb: axi2apb@2390000 { + compatible = "nvidia,tegra194-axi2apb"; + reg = <0x02390000 0x1000>, + <0x023a0000 0x1000>, + <0x023b0000 0x1000>, + <0x023c0000 0x1000>, + <0x023d0000 0x1000>, + <0x023e0000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra194-cbb.yaml b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra194-cbb.yaml new file mode 100644 index 000000000000..debb2b0c8013 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra194-cbb.yaml @@ -0,0 +1,97 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/arm/tegra/nvidia,tegra194-cbb.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: NVIDIA Tegra194 CBB 1.0 bindings + +maintainers: + - Sumit Gupta <sumitg@nvidia.com> + +description: |+ + The Control Backbone (CBB) is comprised of the physical path from an + initiator to a target's register configuration space. CBB 1.0 has + multiple hierarchical sub-NOCs (Network-on-Chip) and connects various + initiators and targets using different bridges like AXIP2P, AXI2APB. + + This driver handles errors due to illegal register accesses reported + by the NOCs inside the CBB. NOCs reporting errors are cluster NOCs + "AON-NOC, SCE-NOC, RCE-NOC, BPMP-NOC, CV-NOC" and "CBB Central NOC" + which is the main NOC. + + By default, the access issuing initiator is informed about the error + using SError or Data Abort exception unless the ERD (Error Response + Disable) is enabled/set for that initiator. If the ERD is enabled, then + SError or Data Abort is masked and the error is reported with interrupt. + + - For CCPLEX (CPU Complex) initiator, the driver sets ERD bit. So, the + errors due to illegal accesses from CCPLEX are reported by interrupts. + If ERD is not set, then error is reported by SError. + - For other initiators, the ERD is disabled. So, the access issuing + initiator is informed about the illegal access by Data Abort exception. + In addition, an interrupt is also generated to CCPLEX. These initiators + include all engines using Cortex-R5 (which is ARMv7 CPU cluster) and + engines like TSEC (Security co-processor), NVDEC (NVIDIA Video Decoder + engine) etc which can initiate transactions. + + The driver prints relevant debug information like Error Code, Error + Description, Master, Address, AXI ID, Cache, Protection, Security Group + etc on receiving error notification. + +properties: + $nodename: + pattern: "^[a-z]+-noc@[0-9a-f]+$" + + compatible: + enum: + - nvidia,tegra194-cbb-noc + - nvidia,tegra194-aon-noc + - nvidia,tegra194-bpmp-noc + - nvidia,tegra194-rce-noc + - nvidia,tegra194-sce-noc + + reg: + maxItems: 1 + + interrupts: + description: + CCPLEX receives secure or nonsecure interrupt depending on error type. + A secure interrupt is received for SEC(firewall) & SLV errors and a + non-secure interrupt is received for TMO & DEC errors. + items: + - description: non-secure interrupt + - description: secure interrupt + + nvidia,axi2apb: + $ref: '/schemas/types.yaml#/definitions/phandle' + description: + Specifies the node having all axi2apb bridges which need to be checked + for any error logged in their status register. + + nvidia,apbmisc: + $ref: '/schemas/types.yaml#/definitions/phandle' + description: + Specifies the apbmisc node which need to be used for reading the ERD + register. + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + - nvidia,apbmisc + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + cbb-noc@2300000 { + compatible = "nvidia,tegra194-cbb-noc"; + reg = <0x02300000 0x1000>; + interrupts = <GIC_SPI 230 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 231 IRQ_TYPE_LEVEL_HIGH>; + nvidia,axi2apb = <&axi2apb>; + nvidia,apbmisc = <&apbmisc>; + }; diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra234-cbb.yaml b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra234-cbb.yaml new file mode 100644 index 000000000000..7b1fe50ffbe0 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra234-cbb.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/arm/tegra/nvidia,tegra234-cbb.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: NVIDIA Tegra CBB 2.0 bindings + +maintainers: + - Sumit Gupta <sumitg@nvidia.com> + +description: |+ + The Control Backbone (CBB) is comprised of the physical path from an + initiator to a target's register configuration space. CBB 2.0 consists + of multiple sub-blocks connected to each other to create a topology. + The Tegra234 SoC has different fabrics based on CBB 2.0 architecture + which include cluster fabrics BPMP, AON, PSC, SCE, RCE, DCE, FSI and + "CBB central fabric". + + In CBB 2.0, each initiator which can issue transactions connects to a + Root Master Node (MN) before it connects to any other element of the + fabric. Each Root MN contains a Error Monitor (EM) which detects and + logs error. Interrupts from various EM blocks are collated by Error + Notifier (EN) which is per fabric and presents a single interrupt from + fabric to the SoC interrupt controller. + + The driver handles errors from CBB due to illegal register accesses + and prints debug information about failed transaction on receiving + the interrupt from EN. Debug information includes Error Code, Error + Description, MasterID, Fabric, SlaveID, Address, Cache, Protection, + Security Group etc on receiving error notification. + + If the Error Response Disable (ERD) is set/enabled for an initiator, + then SError or Data abort exception error response is masked and an + interrupt is used for reporting errors due to illegal accesses from + that initiator. The value returned on read failures is '0xFFFFFFFF' + for compatibility with PCIE. + +properties: + $nodename: + pattern: "^[a-z]+-fabric@[0-9a-f]+$" + + compatible: + enum: + - nvidia,tegra234-aon-fabric + - nvidia,tegra234-bpmp-fabric + - nvidia,tegra234-cbb-fabric + - nvidia,tegra234-dce-fabric + - nvidia,tegra234-rce-fabric + - nvidia,tegra234-sce-fabric + + reg: + maxItems: 1 + + interrupts: + items: + - description: secure interrupt from error notifier + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + cbb-fabric@1300000 { + compatible = "nvidia,tegra234-cbb-fabric"; + reg = <0x13a00000 0x400000>; + interrupts = <GIC_SPI 231 IRQ_TYPE_LEVEL_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/clock/allwinner,sun8i-a83t-de2-clk.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun8i-a83t-de2-clk.yaml index e79eeac5f086..17caf78f0ccf 100644 --- a/Documentation/devicetree/bindings/clock/allwinner,sun8i-a83t-de2-clk.yaml +++ b/Documentation/devicetree/bindings/clock/allwinner,sun8i-a83t-de2-clk.yaml @@ -28,6 +28,9 @@ properties: - items: - const: allwinner,sun8i-r40-de2-clk - const: allwinner,sun8i-h3-de2-clk + - items: + - const: allwinner,sun20i-d1-de2-clk + - const: allwinner,sun50i-h5-de2-clk reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/clock/fsl,scu-clk.yaml b/Documentation/devicetree/bindings/clock/fsl,scu-clk.yaml new file mode 100644 index 000000000000..f2c48460a399 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/fsl,scu-clk.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/fsl,scu-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: i.MX SCU Client Device Node - Clock bindings based on SCU Message Protocol + +maintainers: + - Abel Vesa <abel.vesa@nxp.com> + +description: i.MX SCU Client Device Node + Client nodes are maintained as children of the relevant IMX-SCU device node. + This binding uses the common clock binding. + (Documentation/devicetree/bindings/clock/clock-bindings.txt) + The clock consumer should specify the desired clock by having the clock + ID in its "clocks" phandle cell. See the full list of clock IDs from + include/dt-bindings/clock/imx8qxp-clock.h + +properties: + compatible: + items: + - enum: + - fsl,imx8dxl-clk + - fsl,imx8qm-clk + - fsl,imx8qxp-clk + - const: fsl,scu-clk + + '#clock-cells': + const: 2 + +required: + - compatible + - '#clock-cells' + +additionalProperties: false + +examples: + - | + clock-controller { + compatible = "fsl,imx8qxp-clk", "fsl,scu-clk"; + #clock-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/clock/nuvoton,npcm845-clk.yaml b/Documentation/devicetree/bindings/clock/nuvoton,npcm845-clk.yaml new file mode 100644 index 000000000000..771db2ddf026 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/nuvoton,npcm845-clk.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/nuvoton,npcm845-clk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nuvoton NPCM8XX Clock Controller Binding + +maintainers: + - Tomer Maimon <tmaimon77@gmail.com> + +description: | + Nuvoton Arbel BMC NPCM8XX contains an integrated clock controller, which + generates and supplies clocks to all modules within the BMC. + +properties: + compatible: + enum: + - nuvoton,npcm845-clk + + reg: + maxItems: 1 + + '#clock-cells': + const: 1 + description: + See include/dt-bindings/clock/nuvoton,npcm8xx-clock.h for the full + list of NPCM8XX clock IDs. + +required: + - compatible + - reg + - '#clock-cells' + +additionalProperties: false + +examples: + - | + ahb { + #address-cells = <2>; + #size-cells = <2>; + + clock-controller@f0801000 { + compatible = "nuvoton,npcm845-clk"; + reg = <0x0 0xf0801000 0x0 0x1000>; + #clock-cells = <1>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,dispcc-sm8x50.yaml b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm8x50.yaml index 31497677e8de..7a8d375e055e 100644 --- a/Documentation/devicetree/bindings/clock/qcom,dispcc-sm8x50.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,dispcc-sm8x50.yaml @@ -4,18 +4,19 @@ $id: http://devicetree.org/schemas/clock/qcom,dispcc-sm8x50.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Display Clock & Reset Controller Binding for SM8150/SM8250 +title: Qualcomm Display Clock & Reset Controller Binding for SM8150/SM8250/SM8350 maintainers: - Jonathan Marek <jonathan@marek.ca> description: | Qualcomm display clock control module which supports the clocks, resets and - power domains on SM8150 and SM8250. + power domains on SM8150/SM8250/SM8350. See also: dt-bindings/clock/qcom,dispcc-sm8150.h dt-bindings/clock/qcom,dispcc-sm8250.h + dt-bindings/clock/qcom,dispcc-sm8350.h properties: compatible: @@ -23,6 +24,7 @@ properties: - qcom,sc8180x-dispcc - qcom,sm8150-dispcc - qcom,sm8250-dispcc + - qcom,sm8350-dispcc clocks: items: diff --git a/Documentation/devicetree/bindings/clock/qcom,gpucc-sm8350.yaml b/Documentation/devicetree/bindings/clock/qcom,gpucc-sm8350.yaml new file mode 100644 index 000000000000..0a0546c079a9 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gpucc-sm8350.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,gpucc-sm8350.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Graphics Clock & Reset Controller Binding + +maintainers: + - Robert Foss <robert.foss@linaro.org> + +description: | + Qualcomm graphics clock control module which supports the clocks, resets and + power domains on Qualcomm SoCs. + + See also: + dt-bindings/clock/qcom,gpucc-sm8350.h + +properties: + compatible: + enum: + - qcom,sm8350-gpucc + + clocks: + items: + - description: Board XO source + - description: GPLL0 main branch source + - description: GPLL0 div branch source + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-sm8350.h> + #include <dt-bindings/clock/qcom,rpmh.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + clock-controller@3d90000 { + compatible = "qcom,sm8350-gpucc"; + reg = <0 0x03d90000 0 0x9000>; + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&gcc GCC_GPU_GPLL0_CLK_SRC>, + <&gcc GCC_GPU_GPLL0_DIV_CLK_SRC>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml new file mode 100644 index 000000000000..268f4c6ae0ee --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sm8450-camcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Camera Clock & Reset Controller Binding for SM8450 + +maintainers: + - Vladimir Zapolskiy <vladimir.zapolskiy@linaro.org> + +description: | + Qualcomm camera clock control module which supports the clocks, resets and + power domains on SM8450. + + See also include/dt-bindings/clock/qcom,sm8450-camcc.h + +properties: + compatible: + const: qcom,sm8450-camcc + + clocks: + items: + - description: Camera AHB clock from GCC + - description: Board XO source + - description: Board active XO source + - description: Sleep clock source + + power-domains: + maxItems: 1 + description: + A phandle and PM domain specifier for the MMCX power domain. + + required-opps: + description: + A phandle to an OPP node describing required MMCX performance point. + + '#clock-cells': + const: 1 + + '#reset-cells': + const: 1 + + '#power-domain-cells': + const: 1 + + reg: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - power-domains + - required-opps + - '#clock-cells' + - '#reset-cells' + - '#power-domain-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-sm8450.h> + #include <dt-bindings/clock/qcom,rpmh.h> + #include <dt-bindings/power/qcom-rpmpd.h> + clock-controller@ade0000 { + compatible = "qcom,sm8450-camcc"; + reg = <0xade0000 0x20000>; + clocks = <&gcc GCC_CAMERA_AHB_CLK>, + <&rpmhcc RPMH_CXO_CLK>, + <&rpmhcc RPMH_CXO_CLK_A>, + <&sleep_clk>; + power-domains = <&rpmhpd SM8450_MMCX>; + required-opps = <&rpmhpd_opp_low_svs>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/samsung,exynos7885-clock.yaml b/Documentation/devicetree/bindings/clock/samsung,exynos7885-clock.yaml index 5073e569a47f..006d33a9e0f1 100644 --- a/Documentation/devicetree/bindings/clock/samsung,exynos7885-clock.yaml +++ b/Documentation/devicetree/bindings/clock/samsung,exynos7885-clock.yaml @@ -33,6 +33,7 @@ properties: enum: - samsung,exynos7885-cmu-top - samsung,exynos7885-cmu-core + - samsung,exynos7885-cmu-fsys - samsung,exynos7885-cmu-peri clocks: @@ -92,6 +93,32 @@ allOf: properties: compatible: contains: + const: samsung,exynos7885-cmu-fsys + + then: + properties: + clocks: + items: + - description: External reference clock (26 MHz) + - description: CMU_FSYS bus clock (from CMU_TOP) + - description: MMC_CARD clock (from CMU_TOP) + - description: MMC_EMBD clock (from CMU_TOP) + - description: MMC_SDIO clock (from CMU_TOP) + - description: USB30DRD clock (from CMU_TOP) + + clock-names: + items: + - const: oscclk + - const: dout_fsys_bus + - const: dout_fsys_mmc_card + - const: dout_fsys_mmc_embd + - const: dout_fsys_mmc_sdio + - const: dout_fsys_usb30drd + + - if: + properties: + compatible: + contains: const: samsung,exynos7885-cmu-peri then: diff --git a/Documentation/devicetree/bindings/clock/st,stm32mp1-rcc.yaml b/Documentation/devicetree/bindings/clock/st,stm32mp1-rcc.yaml index f8c474227807..242fe922b035 100644 --- a/Documentation/devicetree/bindings/clock/st,stm32mp1-rcc.yaml +++ b/Documentation/devicetree/bindings/clock/st,stm32mp1-rcc.yaml @@ -78,6 +78,7 @@ if: contains: enum: - st,stm32mp1-rcc-secure + - st,stm32mp13-rcc then: properties: clocks: diff --git a/Documentation/devicetree/bindings/clock/sunplus,sp7021-clkc.yaml b/Documentation/devicetree/bindings/clock/sunplus,sp7021-clkc.yaml new file mode 100644 index 000000000000..bcc14088220a --- /dev/null +++ b/Documentation/devicetree/bindings/clock/sunplus,sp7021-clkc.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) Sunplus Co., Ltd. 2021 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/sunplus,sp7021-clkc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sunplus SP7021 SoC Clock Controller + +maintainers: + - Qin Jian <qinjian@cqplus1.com> + +properties: + compatible: + const: sunplus,sp7021-clkc + + reg: + maxItems: 3 + + clocks: + maxItems: 1 + + "#clock-cells": + const: 1 + +required: + - compatible + - reg + - clocks + - "#clock-cells" + +additionalProperties: false + +examples: + - | + extclk: osc0 { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <27000000>; + clock-output-names = "extclk"; + }; + + clkc: clock-controller@9c000004 { + compatible = "sunplus,sp7021-clkc"; + reg = <0x9c000004 0x28>, + <0x9c000200 0x44>, + <0x9c000268 0x08>; + clocks = <&extclk>; + #clock-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml b/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml index a9a776da5505..10b3a7a4af36 100644 --- a/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml +++ b/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml @@ -63,8 +63,8 @@ additionalProperties: true examples: - | / { - model = "Qualcomm Technologies, Inc. QCS404"; - compatible = "qcom,qcs404"; + model = "Qualcomm Technologies, Inc. QCS404 EVB 1000"; + compatible = "qcom,qcs404-evb-1000", "qcom,qcs404-evb", "qcom,qcs404"; #address-cells = <2>; #size-cells = <2>; diff --git a/Documentation/devicetree/bindings/devfreq/exynos-bus.txt b/Documentation/devicetree/bindings/devfreq/exynos-bus.txt deleted file mode 100644 index bcaa2c08ac11..000000000000 --- a/Documentation/devicetree/bindings/devfreq/exynos-bus.txt +++ /dev/null @@ -1,488 +0,0 @@ -* Generic Exynos Bus frequency device - -The Samsung Exynos SoC has many buses for data transfer between DRAM -and sub-blocks in SoC. Most Exynos SoCs share the common architecture -for buses. Generally, each bus of Exynos SoC includes a source clock -and a power line, which are able to change the clock frequency -of the bus in runtime. To monitor the usage of each bus in runtime, -the driver uses the PPMU (Platform Performance Monitoring Unit), which -is able to measure the current load of sub-blocks. - -The Exynos SoC includes the various sub-blocks which have the each AXI bus. -The each AXI bus has the owned source clock but, has not the only owned -power line. The power line might be shared among one more sub-blocks. -So, we can divide into two type of device as the role of each sub-block. -There are two type of bus devices as following: -- parent bus device -- passive bus device - -Basically, parent and passive bus device share the same power line. -The parent bus device can only change the voltage of shared power line -and the rest bus devices (passive bus device) depend on the decision of -the parent bus device. If there are three blocks which share the VDD_xxx -power line, Only one block should be parent device and then the rest blocks -should depend on the parent device as passive device. - - VDD_xxx |--- A block (parent) - |--- B block (passive) - |--- C block (passive) - -There are a little different composition among Exynos SoC because each Exynos -SoC has different sub-blocks. Therefore, such difference should be specified -in devicetree file instead of each device driver. In result, this driver -is able to support the bus frequency for all Exynos SoCs. - -Required properties for all bus devices: -- compatible: Should be "samsung,exynos-bus". -- clock-names : the name of clock used by the bus, "bus". -- clocks : phandles for clock specified in "clock-names" property. -- operating-points-v2: the OPP table including frequency/voltage information - to support DVFS (Dynamic Voltage/Frequency Scaling) feature. - -Required properties only for parent bus device: -- vdd-supply: the regulator to provide the buses with the voltage. -- devfreq-events: the devfreq-event device to monitor the current utilization - of buses. - -Required properties only for passive bus device: -- devfreq: the parent bus device. - -Optional properties only for parent bus device: -- exynos,saturation-ratio: the percentage value which is used to calibrate - the performance count against total cycle count. - -Optional properties for the interconnect functionality (QoS frequency -constraints): -- #interconnect-cells: should be 0. -- interconnects: as documented in ../interconnect.txt, describes a path at the - higher level interconnects used by this interconnect provider. - If this interconnect provider is directly linked to a top level interconnect - provider the property contains only one phandle. The provider extends - the interconnect graph by linking its node to a node registered by provider - pointed to by first phandle in the 'interconnects' property. - -- samsung,data-clock-ratio: ratio of the data throughput in B/s to minimum data - clock frequency in Hz, default value is 8 when this property is missing. - -Detailed correlation between sub-blocks and power line according to Exynos SoC: -- In case of Exynos3250, there are two power line as following: - VDD_MIF |--- DMC - - VDD_INT |--- LEFTBUS (parent device) - |--- PERIL - |--- MFC - |--- G3D - |--- RIGHTBUS - |--- PERIR - |--- FSYS - |--- LCD0 - |--- PERIR - |--- ISP - |--- CAM - -- In case of Exynos4210, there is one power line as following: - VDD_INT |--- DMC (parent device) - |--- LEFTBUS - |--- PERIL - |--- MFC(L) - |--- G3D - |--- TV - |--- LCD0 - |--- RIGHTBUS - |--- PERIR - |--- MFC(R) - |--- CAM - |--- FSYS - |--- GPS - |--- LCD0 - |--- LCD1 - -- In case of Exynos4x12, there are two power line as following: - VDD_MIF |--- DMC - - VDD_INT |--- LEFTBUS (parent device) - |--- PERIL - |--- MFC(L) - |--- G3D - |--- TV - |--- IMAGE - |--- RIGHTBUS - |--- PERIR - |--- MFC(R) - |--- CAM - |--- FSYS - |--- GPS - |--- LCD0 - |--- ISP - -- In case of Exynos5422, there are two power line as following: - VDD_MIF |--- DREX 0 (parent device, DRAM EXpress controller) - |--- DREX 1 - - VDD_INT |--- NoC_Core (parent device) - |--- G2D - |--- G3D - |--- DISP1 - |--- NoC_WCORE - |--- GSCL - |--- MSCL - |--- ISP - |--- MFC - |--- GEN - |--- PERIS - |--- PERIC - |--- FSYS - |--- FSYS2 - -- In case of Exynos5433, there is VDD_INT power line as following: - VDD_INT |--- G2D (parent device) - |--- MSCL - |--- GSCL - |--- JPEG - |--- MFC - |--- HEVC - |--- BUS0 - |--- BUS1 - |--- BUS2 - |--- PERIS (Fixed clock rate) - |--- PERIC (Fixed clock rate) - |--- FSYS (Fixed clock rate) - -Example 1: - Show the AXI buses of Exynos3250 SoC. Exynos3250 divides the buses to - power line (regulator). The MIF (Memory Interface) AXI bus is used to - transfer data between DRAM and CPU and uses the VDD_MIF regulator. - - - MIF (Memory Interface) block - : VDD_MIF |--- DMC (Dynamic Memory Controller) - - - INT (Internal) block - : VDD_INT |--- LEFTBUS (parent device) - |--- PERIL - |--- MFC - |--- G3D - |--- RIGHTBUS - |--- FSYS - |--- LCD0 - |--- PERIR - |--- ISP - |--- CAM - - - MIF bus's frequency/voltage table - ----------------------- - |Lv| Freq | Voltage | - ----------------------- - |L1| 50000 |800000 | - |L2| 100000 |800000 | - |L3| 134000 |800000 | - |L4| 200000 |825000 | - |L5| 400000 |875000 | - ----------------------- - - - INT bus's frequency/voltage table - ---------------------------------------------------------- - |Block|LEFTBUS|RIGHTBUS|MCUISP |ISP |PERIL ||VDD_INT | - | name| |LCD0 | | | || | - | | |FSYS | | | || | - | | |MFC | | | || | - ---------------------------------------------------------- - |Mode |*parent|passive |passive|passive|passive|| | - ---------------------------------------------------------- - |Lv |Frequency ||Voltage | - ---------------------------------------------------------- - |L1 |50000 |50000 |50000 |50000 |50000 ||900000 | - |L2 |80000 |80000 |80000 |80000 |80000 ||900000 | - |L3 |100000 |100000 |100000 |100000 |100000 ||1000000 | - |L4 |134000 |134000 |200000 |200000 | ||1000000 | - |L5 |200000 |200000 |400000 |300000 | ||1000000 | - ---------------------------------------------------------- - -Example 2: - The bus of DMC (Dynamic Memory Controller) block in exynos3250.dtsi - is listed below: - - bus_dmc: bus_dmc { - compatible = "samsung,exynos-bus"; - clocks = <&cmu_dmc CLK_DIV_DMC>; - clock-names = "bus"; - operating-points-v2 = <&bus_dmc_opp_table>; - status = "disabled"; - }; - - bus_dmc_opp_table: opp_table1 { - compatible = "operating-points-v2"; - opp-shared; - - opp-50000000 { - opp-hz = /bits/ 64 <50000000>; - opp-microvolt = <800000>; - }; - opp-100000000 { - opp-hz = /bits/ 64 <100000000>; - opp-microvolt = <800000>; - }; - opp-134000000 { - opp-hz = /bits/ 64 <134000000>; - opp-microvolt = <800000>; - }; - opp-200000000 { - opp-hz = /bits/ 64 <200000000>; - opp-microvolt = <825000>; - }; - opp-400000000 { - opp-hz = /bits/ 64 <400000000>; - opp-microvolt = <875000>; - }; - }; - - bus_leftbus: bus_leftbus { - compatible = "samsung,exynos-bus"; - clocks = <&cmu CLK_DIV_GDL>; - clock-names = "bus"; - operating-points-v2 = <&bus_leftbus_opp_table>; - status = "disabled"; - }; - - bus_rightbus: bus_rightbus { - compatible = "samsung,exynos-bus"; - clocks = <&cmu CLK_DIV_GDR>; - clock-names = "bus"; - operating-points-v2 = <&bus_leftbus_opp_table>; - status = "disabled"; - }; - - bus_lcd0: bus_lcd0 { - compatible = "samsung,exynos-bus"; - clocks = <&cmu CLK_DIV_ACLK_160>; - clock-names = "bus"; - operating-points-v2 = <&bus_leftbus_opp_table>; - status = "disabled"; - }; - - bus_fsys: bus_fsys { - compatible = "samsung,exynos-bus"; - clocks = <&cmu CLK_DIV_ACLK_200>; - clock-names = "bus"; - operating-points-v2 = <&bus_leftbus_opp_table>; - status = "disabled"; - }; - - bus_mcuisp: bus_mcuisp { - compatible = "samsung,exynos-bus"; - clocks = <&cmu CLK_DIV_ACLK_400_MCUISP>; - clock-names = "bus"; - operating-points-v2 = <&bus_mcuisp_opp_table>; - status = "disabled"; - }; - - bus_isp: bus_isp { - compatible = "samsung,exynos-bus"; - clocks = <&cmu CLK_DIV_ACLK_266>; - clock-names = "bus"; - operating-points-v2 = <&bus_isp_opp_table>; - status = "disabled"; - }; - - bus_peril: bus_peril { - compatible = "samsung,exynos-bus"; - clocks = <&cmu CLK_DIV_ACLK_100>; - clock-names = "bus"; - operating-points-v2 = <&bus_peril_opp_table>; - status = "disabled"; - }; - - bus_mfc: bus_mfc { - compatible = "samsung,exynos-bus"; - clocks = <&cmu CLK_SCLK_MFC>; - clock-names = "bus"; - operating-points-v2 = <&bus_leftbus_opp_table>; - status = "disabled"; - }; - - bus_leftbus_opp_table: opp_table1 { - compatible = "operating-points-v2"; - opp-shared; - - opp-50000000 { - opp-hz = /bits/ 64 <50000000>; - opp-microvolt = <900000>; - }; - opp-80000000 { - opp-hz = /bits/ 64 <80000000>; - opp-microvolt = <900000>; - }; - opp-100000000 { - opp-hz = /bits/ 64 <100000000>; - opp-microvolt = <1000000>; - }; - opp-134000000 { - opp-hz = /bits/ 64 <134000000>; - opp-microvolt = <1000000>; - }; - opp-200000000 { - opp-hz = /bits/ 64 <200000000>; - opp-microvolt = <1000000>; - }; - }; - - bus_mcuisp_opp_table: opp_table2 { - compatible = "operating-points-v2"; - opp-shared; - - opp-50000000 { - opp-hz = /bits/ 64 <50000000>; - }; - opp-80000000 { - opp-hz = /bits/ 64 <80000000>; - }; - opp-100000000 { - opp-hz = /bits/ 64 <100000000>; - }; - opp-200000000 { - opp-hz = /bits/ 64 <200000000>; - }; - opp-400000000 { - opp-hz = /bits/ 64 <400000000>; - }; - }; - - bus_isp_opp_table: opp_table3 { - compatible = "operating-points-v2"; - opp-shared; - - opp-50000000 { - opp-hz = /bits/ 64 <50000000>; - }; - opp-80000000 { - opp-hz = /bits/ 64 <80000000>; - }; - opp-100000000 { - opp-hz = /bits/ 64 <100000000>; - }; - opp-200000000 { - opp-hz = /bits/ 64 <200000000>; - }; - opp-300000000 { - opp-hz = /bits/ 64 <300000000>; - }; - }; - - bus_peril_opp_table: opp_table4 { - compatible = "operating-points-v2"; - opp-shared; - - opp-50000000 { - opp-hz = /bits/ 64 <50000000>; - }; - opp-80000000 { - opp-hz = /bits/ 64 <80000000>; - }; - opp-100000000 { - opp-hz = /bits/ 64 <100000000>; - }; - }; - - - Usage case to handle the frequency and voltage of bus on runtime - in exynos3250-rinato.dts is listed below: - - &bus_dmc { - devfreq-events = <&ppmu_dmc0_3>, <&ppmu_dmc1_3>; - vdd-supply = <&buck1_reg>; /* VDD_MIF */ - status = "okay"; - }; - - &bus_leftbus { - devfreq-events = <&ppmu_leftbus_3>, <&ppmu_rightbus_3>; - vdd-supply = <&buck3_reg>; - status = "okay"; - }; - - &bus_rightbus { - devfreq = <&bus_leftbus>; - status = "okay"; - }; - - &bus_lcd0 { - devfreq = <&bus_leftbus>; - status = "okay"; - }; - - &bus_fsys { - devfreq = <&bus_leftbus>; - status = "okay"; - }; - - &bus_mcuisp { - devfreq = <&bus_leftbus>; - status = "okay"; - }; - - &bus_isp { - devfreq = <&bus_leftbus>; - status = "okay"; - }; - - &bus_peril { - devfreq = <&bus_leftbus>; - status = "okay"; - }; - - &bus_mfc { - devfreq = <&bus_leftbus>; - status = "okay"; - }; - -Example 3: - An interconnect path "bus_display -- bus_leftbus -- bus_dmc" on - Exynos4412 SoC with video mixer as an interconnect consumer device. - - soc { - bus_dmc: bus_dmc { - compatible = "samsung,exynos-bus"; - clocks = <&clock CLK_DIV_DMC>; - clock-names = "bus"; - operating-points-v2 = <&bus_dmc_opp_table>; - samsung,data-clock-ratio = <4>; - #interconnect-cells = <0>; - }; - - bus_leftbus: bus_leftbus { - compatible = "samsung,exynos-bus"; - clocks = <&clock CLK_DIV_GDL>; - clock-names = "bus"; - operating-points-v2 = <&bus_leftbus_opp_table>; - #interconnect-cells = <0>; - interconnects = <&bus_dmc>; - }; - - bus_display: bus_display { - compatible = "samsung,exynos-bus"; - clocks = <&clock CLK_ACLK160>; - clock-names = "bus"; - operating-points-v2 = <&bus_display_opp_table>; - #interconnect-cells = <0>; - interconnects = <&bus_leftbus &bus_dmc>; - }; - - bus_dmc_opp_table: opp_table1 { - compatible = "operating-points-v2"; - /* ... */ - } - - bus_leftbus_opp_table: opp_table3 { - compatible = "operating-points-v2"; - /* ... */ - }; - - bus_display_opp_table: opp_table4 { - compatible = "operating-points-v2"; - /* .. */ - }; - - &mixer { - compatible = "samsung,exynos4212-mixer"; - interconnects = <&bus_display &bus_dmc>; - /* ... */ - }; - }; diff --git a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-engine.yaml b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-engine.yaml index c388ae5da1e4..c9c346e6228e 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-engine.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-engine.yaml @@ -94,6 +94,7 @@ if: - allwinner,sun8i-a83t-display-engine - allwinner,sun8i-r40-display-engine - allwinner,sun9i-a80-display-engine + - allwinner,sun20i-d1-display-engine - allwinner,sun50i-a64-display-engine then: diff --git a/Documentation/devicetree/bindings/display/panel/lgphilips,lb035q02.yaml b/Documentation/devicetree/bindings/display/panel/lgphilips,lb035q02.yaml index 5e4e0e552c2f..628c4b898111 100644 --- a/Documentation/devicetree/bindings/display/panel/lgphilips,lb035q02.yaml +++ b/Documentation/devicetree/bindings/display/panel/lgphilips,lb035q02.yaml @@ -21,6 +21,9 @@ properties: enable-gpios: true port: true + spi-cpha: true + spi-cpol: true + required: - compatible - enable-gpios diff --git a/Documentation/devicetree/bindings/display/panel/samsung,ld9040.yaml b/Documentation/devicetree/bindings/display/panel/samsung,ld9040.yaml index d525165d6d63..c0fabeb38628 100644 --- a/Documentation/devicetree/bindings/display/panel/samsung,ld9040.yaml +++ b/Documentation/devicetree/bindings/display/panel/samsung,ld9040.yaml @@ -42,6 +42,9 @@ properties: panel-height-mm: description: physical panel height [mm] + spi-cpha: true + spi-cpol: true + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/panel/sitronix,st7789v.yaml b/Documentation/devicetree/bindings/display/panel/sitronix,st7789v.yaml index 9e1d707c2ace..d984b59daa4a 100644 --- a/Documentation/devicetree/bindings/display/panel/sitronix,st7789v.yaml +++ b/Documentation/devicetree/bindings/display/panel/sitronix,st7789v.yaml @@ -23,6 +23,9 @@ properties: backlight: true port: true + spi-cpha: true + spi-cpol: true + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/display/panel/tpo,td.yaml b/Documentation/devicetree/bindings/display/panel/tpo,td.yaml index f902a9d74141..e8c8ee8d7c88 100644 --- a/Documentation/devicetree/bindings/display/panel/tpo,td.yaml +++ b/Documentation/devicetree/bindings/display/panel/tpo,td.yaml @@ -28,6 +28,9 @@ properties: backlight: true port: true + spi-cpha: true + spi-cpol: true + required: - compatible - port diff --git a/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml b/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml index ff0a5c58d78c..e712444abff1 100644 --- a/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml +++ b/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml @@ -67,7 +67,7 @@ if: then: properties: clocks: - maxItems: 2 + minItems: 2 required: - clock-names diff --git a/Documentation/devicetree/bindings/firmware/arm,scmi.yaml b/Documentation/devicetree/bindings/firmware/arm,scmi.yaml index 948e2a38beed..1c0388da6721 100644 --- a/Documentation/devicetree/bindings/firmware/arm,scmi.yaml +++ b/Documentation/devicetree/bindings/firmware/arm,scmi.yaml @@ -183,6 +183,12 @@ properties: required: - reg + protocol@18: + type: object + properties: + reg: + const: 0x18 + additionalProperties: false patternProperties: @@ -323,6 +329,10 @@ examples: }; }; }; + + scmi_powercap: protocol@18 { + reg = <0x18>; + }; }; }; diff --git a/Documentation/devicetree/bindings/firmware/fsl,scu.yaml b/Documentation/devicetree/bindings/firmware/fsl,scu.yaml new file mode 100644 index 000000000000..b40b0ef56978 --- /dev/null +++ b/Documentation/devicetree/bindings/firmware/fsl,scu.yaml @@ -0,0 +1,210 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/firmware/fsl,scu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP i.MX System Controller Firmware (SCFW) + +maintainers: + - Dong Aisheng <aisheng.dong@nxp.com> + +description: + The System Controller Firmware (SCFW) is a low-level system function + which runs on a dedicated Cortex-M core to provide power, clock, and + resource management. It exists on some i.MX8 processors. e.g. i.MX8QM + (QM, QP), and i.MX8QX (QXP, DX). + The AP communicates with the SC using a multi-ported MU module found + in the LSIO subsystem. The current definition of this MU module provides + 5 remote AP connections to the SC to support up to 5 execution environments + (TZ, HV, standard Linux, etc.). The SC side of this MU module interfaces + with the LSIO DSC IP bus. The SC firmware will communicate with this MU + using the MSI bus. + +properties: + compatible: + const: fsl,imx-scu + + clock-controller: + description: + Clock controller node that provides the clocks controlled by the SCU + $ref: /schemas/clock/fsl,scu-clk.yaml + + ocotp: + description: + OCOTP controller node provided by the SCU + $ref: /schemas/nvmem/fsl,scu-ocotp.yaml + + keys: + description: + Keys provided by the SCU + $ref: /schemas/input/fsl,scu-key.yaml + + mboxes: + description: + A list of phandles of TX MU channels followed by a list of phandles of + RX MU channels. The list may include at the end one more optional MU + channel for general interrupt. The number of expected tx and rx + channels is 1 TX and 1 RX channels if MU instance is "fsl,imx8-mu-scu" + compatible, 4 TX and 4 RX channels otherwise. All MU channels must be + within the same MU instance. Cross instances are not allowed. The MU + instance can only be one of LSIO MU0~M4 for imx8qxp and imx8qm. Users + need to ensure that one is used that does not conflict with other + execution environments such as ATF. + oneOf: + - items: + - description: TX0 MU channel + - description: RX0 MU channel + - items: + - description: TX0 MU channel + - description: RX0 MU channel + - description: optional MU channel for general interrupt + - items: + - description: TX0 MU channel + - description: TX1 MU channel + - description: TX2 MU channel + - description: TX3 MU channel + - description: RX0 MU channel + - description: RX1 MU channel + - description: RX2 MU channel + - description: RX3 MU channel + - items: + - description: TX0 MU channel + - description: TX1 MU channel + - description: TX2 MU channel + - description: TX3 MU channel + - description: RX0 MU channel + - description: RX1 MU channel + - description: RX2 MU channel + - description: RX3 MU channel + - description: optional MU channel for general interrupt + + mbox-names: + oneOf: + - items: + - const: tx0 + - const: rx0 + - items: + - const: tx0 + - const: rx0 + - const: gip3 + - items: + - const: tx0 + - const: tx1 + - const: tx2 + - const: tx3 + - const: rx0 + - const: rx1 + - const: rx2 + - const: rx3 + - items: + - const: tx0 + - const: tx1 + - const: tx2 + - const: tx3 + - const: rx0 + - const: rx1 + - const: rx2 + - const: rx3 + - const: gip3 + + pinctrl: + description: + Pin controller provided by the SCU + $ref: /schemas/pinctrl/fsl,scu-pinctrl.yaml + + power-controller: + description: + Power domains controller node that provides the power domains + controlled by the SCU + $ref: /schemas/power/fsl,scu-pd.yaml + + rtc: + description: + RTC controller provided by the SCU + $ref: /schemas/rtc/fsl,scu-rtc.yaml + + thermal-sensor: + description: + Thermal sensor provided by the SCU + $ref: /schemas/thermal/fsl,scu-thermal.yaml + + watchdog: + description: + Watchdog controller provided by the SCU + $ref: /schemas/watchdog/fsl,scu-wdt.yaml + +required: + - compatible + - mbox-names + - mboxes + +additionalProperties: false + +examples: + - | + #include <dt-bindings/firmware/imx/rsrc.h> + #include <dt-bindings/input/input.h> + #include <dt-bindings/pinctrl/pads-imx8qxp.h> + + firmware { + system-controller { + compatible = "fsl,imx-scu"; + mbox-names = "tx0", "tx1", "tx2", "tx3", + "rx0", "rx1", "rx2", "rx3", + "gip3"; + mboxes = <&lsio_mu1 0 0 &lsio_mu1 0 1 &lsio_mu1 0 2 &lsio_mu1 0 3 + &lsio_mu1 1 0 &lsio_mu1 1 1 &lsio_mu1 1 2 &lsio_mu1 1 3 + &lsio_mu1 3 3>; + + clock-controller { + compatible = "fsl,imx8qxp-clk", "fsl,scu-clk"; + #clock-cells = <2>; + }; + + pinctrl { + compatible = "fsl,imx8qxp-iomuxc"; + + pinctrl_lpuart0: lpuart0grp { + fsl,pins = < + IMX8QXP_UART0_RX_ADMA_UART0_RX 0x06000020 + IMX8QXP_UART0_TX_ADMA_UART0_TX 0x06000020 + >; + }; + }; + + ocotp { + compatible = "fsl,imx8qxp-scu-ocotp"; + #address-cells = <1>; + #size-cells = <1>; + + fec_mac0: mac@2c4 { + reg = <0x2c4 6>; + }; + }; + + power-controller { + compatible = "fsl,imx8qxp-scu-pd", "fsl,scu-pd"; + #power-domain-cells = <1>; + }; + + rtc { + compatible = "fsl,imx8qxp-sc-rtc"; + }; + + keys { + compatible = "fsl,imx8qxp-sc-key", "fsl,imx-sc-key"; + linux,keycodes = <KEY_POWER>; + }; + + watchdog { + compatible = "fsl,imx8qxp-sc-wdt", "fsl,imx-sc-wdt"; + timeout-sec = <60>; + }; + + thermal-sensor { + compatible = "fsl,imx8qxp-sc-thermal", "fsl,imx-sc-thermal"; + #thermal-sensor-cells = <1>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.txt b/Documentation/devicetree/bindings/firmware/qcom,scm.txt index 0f4e5ab26477..b3f702cbed87 100644 --- a/Documentation/devicetree/bindings/firmware/qcom,scm.txt +++ b/Documentation/devicetree/bindings/firmware/qcom,scm.txt @@ -23,10 +23,13 @@ Required properties: * "qcom,scm-msm8994" * "qcom,scm-msm8996" * "qcom,scm-msm8998" + * "qcom,scm-qcs404" * "qcom,scm-sc7180" * "qcom,scm-sc7280" + * "qcom,scm-sm6125" * "qcom,scm-sdm845" * "qcom,scm-sdx55" + * "qcom,scm-sdx65" * "qcom,scm-sm6350" * "qcom,scm-sm8150" * "qcom,scm-sm8250" @@ -43,6 +46,7 @@ Required properties: clock and "bus" for the bus clock per the requirements of the compatible. - qcom,dload-mode: phandle to the TCSR hardware block and offset of the download mode control register (optional) +- interconnects: Specifies the bandwidth requirements of the SCM interface (optional) Example for MSM8916: diff --git a/Documentation/devicetree/bindings/gpio/gpio-zynq.yaml b/Documentation/devicetree/bindings/gpio/gpio-zynq.yaml index 378da2649e66..29c27eadbac8 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-zynq.yaml +++ b/Documentation/devicetree/bindings/gpio/gpio-zynq.yaml @@ -11,7 +11,11 @@ maintainers: properties: compatible: - const: xlnx,zynq-gpio-1.0 + enum: + - xlnx,zynq-gpio-1.0 + - xlnx,zynqmp-gpio-1.0 + - xlnx,versal-gpio-1.0 + - xlnx,pmc-gpio-1.0 reg: maxItems: 1 @@ -24,6 +28,11 @@ properties: gpio-controller: true + gpio-line-names: + description: strings describing the names of each gpio line + minItems: 58 + maxItems: 174 + interrupt-controller: true "#interrupt-cells": @@ -32,6 +41,54 @@ properties: clocks: maxItems: 1 + power-domains: + maxItems: 1 + +allOf: + - if: + properties: + compatible: + enum: + - xlnx,zynqmp-gpio-1.0 + then: + properties: + gpio-line-names: + minItems: 174 + maxItems: 174 + + - if: + properties: + compatible: + enum: + - xlnx,zynq-gpio-1.0 + then: + properties: + gpio-line-names: + minItems: 118 + maxItems: 118 + + - if: + properties: + compatible: + enum: + - xlnx,versal-gpio-1.0 + then: + properties: + gpio-line-names: + minItems: 58 + maxItems: 58 + + - if: + properties: + compatible: + enum: + - xlnx,pmc-gpio-1.0 + then: + properties: + gpio-line-names: + minItems: 116 + maxItems: 116 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/arm/renesas,prr.yaml b/Documentation/devicetree/bindings/hwinfo/renesas,prr.yaml index 1f80767da38b..792f371cec03 100644 --- a/Documentation/devicetree/bindings/arm/renesas,prr.yaml +++ b/Documentation/devicetree/bindings/hwinfo/renesas,prr.yaml @@ -1,7 +1,7 @@ -# SPDX-License-Identifier: GPL-2.0 +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/arm/renesas,prr.yaml# +$id: http://devicetree.org/schemas/hwinfo/renesas,prr.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Renesas Product Register diff --git a/Documentation/devicetree/bindings/hwmon/national,lm90.yaml b/Documentation/devicetree/bindings/hwmon/national,lm90.yaml index b04657849852..e1719839faf0 100644 --- a/Documentation/devicetree/bindings/hwmon/national,lm90.yaml +++ b/Documentation/devicetree/bindings/hwmon/national,lm90.yaml @@ -16,6 +16,7 @@ properties: - adi,adm1032 - adi,adt7461 - adi,adt7461a + - adi,adt7481 - dallas,max6646 - dallas,max6647 - dallas,max6649 @@ -50,6 +51,12 @@ properties: "#thermal-sensor-cells": const: 1 + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + vcc-supply: description: phandle to the regulator that provides the +VCC supply @@ -61,6 +68,29 @@ required: - compatible - reg +patternProperties: + "^channel@([0-2])$": + type: object + description: Represents channels of the device and their specific configuration. + + properties: + reg: + description: The channel number. 0 is local channel, 1-2 are remote channels. + items: + minimum: 0 + maximum: 2 + + label: + description: A descriptive name for this channel, like "ambient" or "psu". + + temperature-offset-millicelsius: + description: Temperature offset to be added to or subtracted from remote temperature measurements. + + required: + - reg + + additionalProperties: false + allOf: - if: not: @@ -70,12 +100,84 @@ allOf: enum: - adi,adt7461 - adi,adt7461a + - adi,adt7481 - ti,tmp451 - ti,tmp461 then: properties: ti,extended-range-enable: false + - if: + properties: + compatible: + contains: + enum: + - dallas,max6646 + - dallas,max6647 + - dallas,max6649 + - dallas,max6657 + - dallas,max6658 + - dallas,max6659 + - dallas,max6695 + - dallas,max6696 + then: + patternProperties: + "^channel@([0-2])$": + properties: + temperature-offset-millicelsius: false + + - if: + properties: + compatible: + contains: + enum: + - adi,adt7461 + - adi,adt7461a + - adi,adt7481 + - onnn,nct1008 + then: + patternProperties: + "^channel@([0-2])$": + properties: + temperature-offset-millicelsius: + maximum: 127750 + + - if: + properties: + compatible: + contains: + enum: + - adi,adm1032 + - dallas,max6680 + - dallas,max6681 + - gmt,g781 + - national,lm86 + - national,lm89 + - national,lm90 + - national,lm99 + - nxp,sa56004 + - winbond,w83l771 + then: + patternProperties: + "^channel@([0-2])$": + properties: + temperature-offset-millicelsius: + maximum: 127875 + + - if: + properties: + compatible: + contains: + enum: + - ti,tmp451 + - ti,tmp461 + then: + patternProperties: + "^channel@([0-2])$": + properties: + temperature-offset-millicelsius: + maximum: 127937 + additionalProperties: false examples: @@ -94,3 +196,32 @@ examples: #thermal-sensor-cells = <1>; }; }; + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + sensor@4c { + compatible = "adi,adt7481"; + reg = <0x4c>; + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + reg = <0x0>; + label = "local"; + }; + + channel@1 { + reg = <0x1>; + label = "front"; + temperature-offset-millicelsius = <4000>; + }; + + channel@2 { + reg = <0x2>; + label = "back"; + temperature-offset-millicelsius = <750>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/hwmon/ti,tmp401.yaml b/Documentation/devicetree/bindings/hwmon/ti,tmp401.yaml index fe0ac08faa1a..0e8ddf0ad789 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,tmp401.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,tmp401.yaml @@ -40,9 +40,8 @@ properties: value to be used for converting remote channel measurements to temperature. $ref: /schemas/types.yaml#/definitions/int32 - items: - minimum: -128 - maximum: 127 + minimum: -128 + maximum: 127 ti,beta-compensation: description: diff --git a/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml index f771c09aabfc..0ec033e48830 100644 --- a/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml @@ -21,10 +21,18 @@ properties: - enum: - allwinner,sun8i-a23-i2c - allwinner,sun8i-a83t-i2c + - allwinner,sun8i-v536-i2c - allwinner,sun50i-a64-i2c - - allwinner,sun50i-a100-i2c - allwinner,sun50i-h6-i2c + - const: allwinner,sun6i-a31-i2c + - description: Allwinner SoCs with offload support + items: + - enum: + - allwinner,sun20i-d1-i2c + - allwinner,sun50i-a100-i2c - allwinner,sun50i-h616-i2c + - allwinner,sun50i-r329-i2c + - const: allwinner,sun8i-v536-i2c - const: allwinner,sun6i-a31-i2c - const: marvell,mv64xxx-i2c - const: marvell,mv78230-i2c diff --git a/Documentation/devicetree/bindings/input/da9062-onkey.txt b/Documentation/devicetree/bindings/input/da9062-onkey.txt index 5f9fbc68e58a..e5eef59a93dc 100644 --- a/Documentation/devicetree/bindings/input/da9062-onkey.txt +++ b/Documentation/devicetree/bindings/input/da9062-onkey.txt @@ -2,7 +2,7 @@ This module is part of the DA9061/DA9062/DA9063. For more details about entire DA9062 and DA9061 chips see Documentation/devicetree/bindings/mfd/da9062.txt -For DA9063 see Documentation/devicetree/bindings/mfd/da9063.txt +For DA9063 see Documentation/devicetree/bindings/mfd/dlg,da9063.yaml This module provides the KEY_POWER event. diff --git a/Documentation/devicetree/bindings/input/fsl,scu-key.yaml b/Documentation/devicetree/bindings/input/fsl,scu-key.yaml new file mode 100644 index 000000000000..e6266d188266 --- /dev/null +++ b/Documentation/devicetree/bindings/input/fsl,scu-key.yaml @@ -0,0 +1,40 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/fsl,scu-key.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: i.MX SCU Client Device Node - SCU key bindings based on SCU Message Protocol + +maintainers: + - Dong Aisheng <aisheng.dong@nxp.com> + +description: i.MX SCU Client Device Node + Client nodes are maintained as children of the relevant IMX-SCU device node. + +allOf: + - $ref: input.yaml# + +properties: + compatible: + items: + - const: fsl,imx8qxp-sc-key + - const: fsl,imx-sc-key + + linux,keycodes: + maxItems: 1 + +required: + - compatible + - linux,keycodes + +additionalProperties: false + +examples: + - | + #include <dt-bindings/input/input.h> + + keys { + compatible = "fsl,imx8qxp-sc-key", "fsl,imx-sc-key"; + linux,keycodes = <KEY_POWER>; + }; diff --git a/Documentation/devicetree/bindings/interconnect/mediatek,cci.yaml b/Documentation/devicetree/bindings/interconnect/mediatek,cci.yaml new file mode 100644 index 000000000000..449c7c988229 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/mediatek,cci.yaml @@ -0,0 +1,141 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/mediatek,cci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek Cache Coherent Interconnect (CCI) frequency and voltage scaling + +maintainers: + - Jia-Wei Chang <jia-wei.chang@mediatek.com> + - Johnson Wang <johnson.wang@mediatek.com> + +description: | + MediaTek Cache Coherent Interconnect (CCI) is a hardware engine used by + MT8183 and MT8186 SoCs to scale the frequency and adjust the voltage in + hardware. It can also optimize the voltage to reduce the power consumption. + +properties: + compatible: + enum: + - mediatek,mt8183-cci + - mediatek,mt8186-cci + + clocks: + items: + - description: + The multiplexer for clock input of the bus. + - description: + A parent of "bus" clock which is used as an intermediate clock source + when the original clock source (PLL) is under transition and not + stable yet. + + clock-names: + items: + - const: cci + - const: intermediate + + operating-points-v2: true + opp-table: true + + proc-supply: + description: + Phandle of the regulator for CCI that provides the supply voltage. + + sram-supply: + description: + Phandle of the regulator for sram of CCI that provides the supply + voltage. When it is present, the implementation needs to do + "voltage tracking" to step by step scale up/down Vproc and Vsram to fit + SoC specific needs. When absent, the voltage scaling flow is handled by + hardware, hence no software "voltage tracking" is needed. + +required: + - compatible + - clocks + - clock-names + - operating-points-v2 + - proc-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/mt8183-clk.h> + cci: cci { + compatible = "mediatek,mt8183-cci"; + clocks = <&mcucfg CLK_MCU_BUS_SEL>, + <&topckgen CLK_TOP_ARMPLL_DIV_PLL1>; + clock-names = "cci", "intermediate"; + operating-points-v2 = <&cci_opp>; + proc-supply = <&mt6358_vproc12_reg>; + }; + + cci_opp: opp-table-cci { + compatible = "operating-points-v2"; + opp-shared; + opp2_00: opp-273000000 { + opp-hz = /bits/ 64 <273000000>; + opp-microvolt = <650000>; + }; + opp2_01: opp-338000000 { + opp-hz = /bits/ 64 <338000000>; + opp-microvolt = <687500>; + }; + opp2_02: opp-403000000 { + opp-hz = /bits/ 64 <403000000>; + opp-microvolt = <718750>; + }; + opp2_03: opp-463000000 { + opp-hz = /bits/ 64 <463000000>; + opp-microvolt = <756250>; + }; + opp2_04: opp-546000000 { + opp-hz = /bits/ 64 <546000000>; + opp-microvolt = <800000>; + }; + opp2_05: opp-624000000 { + opp-hz = /bits/ 64 <624000000>; + opp-microvolt = <818750>; + }; + opp2_06: opp-689000000 { + opp-hz = /bits/ 64 <689000000>; + opp-microvolt = <850000>; + }; + opp2_07: opp-767000000 { + opp-hz = /bits/ 64 <767000000>; + opp-microvolt = <868750>; + }; + opp2_08: opp-845000000 { + opp-hz = /bits/ 64 <845000000>; + opp-microvolt = <893750>; + }; + opp2_09: opp-871000000 { + opp-hz = /bits/ 64 <871000000>; + opp-microvolt = <906250>; + }; + opp2_10: opp-923000000 { + opp-hz = /bits/ 64 <923000000>; + opp-microvolt = <931250>; + }; + opp2_11: opp-962000000 { + opp-hz = /bits/ 64 <962000000>; + opp-microvolt = <943750>; + }; + opp2_12: opp-1027000000 { + opp-hz = /bits/ 64 <1027000000>; + opp-microvolt = <975000>; + }; + opp2_13: opp-1092000000 { + opp-hz = /bits/ 64 <1092000000>; + opp-microvolt = <1000000>; + }; + opp2_14: opp-1144000000 { + opp-hz = /bits/ 64 <1144000000>; + opp-microvolt = <1025000>; + }; + opp2_15: opp-1196000000 { + opp-hz = /bits/ 64 <1196000000>; + opp-microvolt = <1050000>; + }; + }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml b/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml new file mode 100644 index 000000000000..c2e697f6e6cf --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/qcom,msm8998-bwmon.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Interconnect Bandwidth Monitor + +maintainers: + - Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> + +description: | + Bandwidth Monitor measures current throughput on buses between various NoC + fabrics and provides information when it crosses configured thresholds. + + Certain SoCs might have more than one Bandwidth Monitors, for example on SDM845:: + - Measuring the bandwidth between CPUs and Last Level Cache Controller - + called just BWMON, + - Measuring the bandwidth between Last Level Cache Controller and memory + (DDR) - called LLCC BWMON. + +properties: + compatible: + oneOf: + - items: + - enum: + - qcom,sdm845-bwmon + - const: qcom,msm8998-bwmon + - const: qcom,msm8998-bwmon # BWMON v4 + + interconnects: + maxItems: 1 + + interrupts: + maxItems: 1 + + operating-points-v2: true + opp-table: true + + reg: + # BWMON v4 (currently described) and BWMON v5 use one register address + # space. BWMON v2 uses two register spaces - not yet described. + maxItems: 1 + +required: + - compatible + - interconnects + - interrupts + - operating-points-v2 + - opp-table + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interconnect/qcom,sdm845.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + pmu@1436400 { + compatible = "qcom,sdm845-bwmon", "qcom,msm8998-bwmon"; + reg = <0x01436400 0x600>; + interrupts = <GIC_SPI 581 IRQ_TYPE_LEVEL_HIGH>; + interconnects = <&gladiator_noc MASTER_APPSS_PROC 3 &mem_noc SLAVE_LLCC 3>; + + operating-points-v2 = <&cpu_bwmon_opp_table>; + + cpu_bwmon_opp_table: opp-table { + compatible = "operating-points-v2"; + opp-0 { + opp-peak-kBps = <4800000>; + }; + opp-1 { + opp-peak-kBps = <9216000>; + }; + opp-2 { + opp-peak-kBps = <15052800>; + }; + opp-3 { + opp-peak-kBps = <20889600>; + }; + opp-4 { + opp-peak-kBps = <25497600>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/interconnect/samsung,exynos-bus.yaml b/Documentation/devicetree/bindings/interconnect/samsung,exynos-bus.yaml new file mode 100644 index 000000000000..ad9ed596dfef --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/samsung,exynos-bus.yaml @@ -0,0 +1,290 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/samsung,exynos-bus.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Exynos SoC Bus and Interconnect + +maintainers: + - Chanwoo Choi <cw00.choi@samsung.com> + - Krzysztof Kozlowski <krzk@kernel.org> + +description: | + The Samsung Exynos SoC has many buses for data transfer between DRAM and + sub-blocks in SoC. Most Exynos SoCs share the common architecture for buses. + Generally, each bus of Exynos SoC includes a source clock and a power line, + which are able to change the clock frequency of the bus in runtime. To + monitor the usage of each bus in runtime, the driver uses the PPMU (Platform + Performance Monitoring Unit), which is able to measure the current load of + sub-blocks. + + The Exynos SoC includes the various sub-blocks which have the each AXI bus. + The each AXI bus has the owned source clock but, has not the only owned power + line. The power line might be shared among one more sub-blocks. So, we can + divide into two type of device as the role of each sub-block. There are two + type of bus devices as following:: + - parent bus device + - passive bus device + + Basically, parent and passive bus device share the same power line. The + parent bus device can only change the voltage of shared power line and the + rest bus devices (passive bus device) depend on the decision of the parent + bus device. If there are three blocks which share the VDD_xxx power line, + Only one block should be parent device and then the rest blocks should depend + on the parent device as passive device. + + VDD_xxx |--- A block (parent) + |--- B block (passive) + |--- C block (passive) + + There are a little different composition among Exynos SoC because each Exynos + SoC has different sub-blocks. Therefore, such difference should be specified + in devicetree file instead of each device driver. In result, this driver is + able to support the bus frequency for all Exynos SoCs. + + Detailed correlation between sub-blocks and power line according + to Exynos SoC:: + - In case of Exynos3250, there are two power line as following:: + VDD_MIF |--- DMC (Dynamic Memory Controller) + + VDD_INT |--- LEFTBUS (parent device) + |--- PERIL + |--- MFC + |--- G3D + |--- RIGHTBUS + |--- PERIR + |--- FSYS + |--- LCD0 + |--- PERIR + |--- ISP + |--- CAM + + - MIF bus's frequency/voltage table + ----------------------- + |Lv| Freq | Voltage | + ----------------------- + |L1| 50000 |800000 | + |L2| 100000 |800000 | + |L3| 134000 |800000 | + |L4| 200000 |825000 | + |L5| 400000 |875000 | + ----------------------- + + - INT bus's frequency/voltage table + ---------------------------------------------------------- + |Block|LEFTBUS|RIGHTBUS|MCUISP |ISP |PERIL ||VDD_INT | + | name| |LCD0 | | | || | + | | |FSYS | | | || | + | | |MFC | | | || | + ---------------------------------------------------------- + |Mode |*parent|passive |passive|passive|passive|| | + ---------------------------------------------------------- + |Lv |Frequency ||Voltage | + ---------------------------------------------------------- + |L1 |50000 |50000 |50000 |50000 |50000 ||900000 | + |L2 |80000 |80000 |80000 |80000 |80000 ||900000 | + |L3 |100000 |100000 |100000 |100000 |100000 ||1000000 | + |L4 |134000 |134000 |200000 |200000 | ||1000000 | + |L5 |200000 |200000 |400000 |300000 | ||1000000 | + ---------------------------------------------------------- + + - In case of Exynos4210, there is one power line as following:: + VDD_INT |--- DMC (parent device, Dynamic Memory Controller) + |--- LEFTBUS + |--- PERIL + |--- MFC(L) + |--- G3D + |--- TV + |--- LCD0 + |--- RIGHTBUS + |--- PERIR + |--- MFC(R) + |--- CAM + |--- FSYS + |--- GPS + |--- LCD0 + |--- LCD1 + + - In case of Exynos4x12, there are two power line as following:: + VDD_MIF |--- DMC (Dynamic Memory Controller) + + VDD_INT |--- LEFTBUS (parent device) + |--- PERIL + |--- MFC(L) + |--- G3D + |--- TV + |--- IMAGE + |--- RIGHTBUS + |--- PERIR + |--- MFC(R) + |--- CAM + |--- FSYS + |--- GPS + |--- LCD0 + |--- ISP + + - In case of Exynos5422, there are two power line as following:: + VDD_MIF |--- DREX 0 (parent device, DRAM EXpress controller) + |--- DREX 1 + + VDD_INT |--- NoC_Core (parent device) + |--- G2D + |--- G3D + |--- DISP1 + |--- NoC_WCORE + |--- GSCL + |--- MSCL + |--- ISP + |--- MFC + |--- GEN + |--- PERIS + |--- PERIC + |--- FSYS + |--- FSYS2 + + - In case of Exynos5433, there is VDD_INT power line as following:: + VDD_INT |--- G2D (parent device) + |--- MSCL + |--- GSCL + |--- JPEG + |--- MFC + |--- HEVC + |--- BUS0 + |--- BUS1 + |--- BUS2 + |--- PERIS (Fixed clock rate) + |--- PERIC (Fixed clock rate) + |--- FSYS (Fixed clock rate) + +properties: + compatible: + enum: + - samsung,exynos-bus + + clocks: + maxItems: 1 + + clock-names: + items: + - const: bus + + devfreq: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Parent bus device. Valid and required only for the passive bus devices. + + devfreq-events: + $ref: /schemas/types.yaml#/definitions/phandle-array + minItems: 1 + maxItems: 4 + description: + Devfreq-event device to monitor the current utilization of buses. Valid + and required only for the parent bus devices. + + exynos,saturation-ratio: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Percentage value which is used to calibrate the performance count against + total cycle count. Valid only for the parent bus devices. + + '#interconnect-cells': + const: 0 + + interconnects: + minItems: 1 + maxItems: 2 + + operating-points-v2: true + + samsung,data-clock-ratio: + $ref: /schemas/types.yaml#/definitions/uint32 + default: 8 + description: + Ratio of the data throughput in B/s to minimum data clock frequency in + Hz. + + vdd-supply: + description: + Main bus power rail. Valid and required only for the parent bus devices. + +required: + - compatible + - clocks + - clock-names + - operating-points-v2 + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/exynos3250.h> + + bus-dmc { + compatible = "samsung,exynos-bus"; + clocks = <&cmu_dmc CLK_DIV_DMC>; + clock-names = "bus"; + operating-points-v2 = <&bus_dmc_opp_table>; + devfreq-events = <&ppmu_dmc0_3>, <&ppmu_dmc1_3>; + vdd-supply = <&buck1_reg>; + }; + + ppmu_dmc0: ppmu@106a0000 { + compatible = "samsung,exynos-ppmu"; + reg = <0x106a0000 0x2000>; + events { + ppmu_dmc0_3: ppmu-event3-dmc0 { + event-name = "ppmu-event3-dmc0"; + }; + }; + }; + + bus_leftbus: bus-leftbus { + compatible = "samsung,exynos-bus"; + clocks = <&cmu CLK_DIV_GDL>; + clock-names = "bus"; + operating-points-v2 = <&bus_leftbus_opp_table>; + devfreq-events = <&ppmu_leftbus_3>, <&ppmu_rightbus_3>; + vdd-supply = <&buck3_reg>; + }; + + bus-rightbus { + compatible = "samsung,exynos-bus"; + clocks = <&cmu CLK_DIV_GDR>; + clock-names = "bus"; + operating-points-v2 = <&bus_leftbus_opp_table>; + devfreq = <&bus_leftbus>; + }; + + - | + dmc: bus-dmc { + compatible = "samsung,exynos-bus"; + clocks = <&clock CLK_DIV_DMC>; + clock-names = "bus"; + operating-points-v2 = <&bus_dmc_opp_table>; + samsung,data-clock-ratio = <4>; + #interconnect-cells = <0>; + devfreq-events = <&ppmu_dmc0_3>, <&ppmu_dmc1_3>; + vdd-supply = <&buck1_reg>; + }; + + leftbus: bus-leftbus { + compatible = "samsung,exynos-bus"; + clocks = <&clock CLK_DIV_GDL>; + clock-names = "bus"; + operating-points-v2 = <&bus_leftbus_opp_table>; + interconnects = <&dmc>; + #interconnect-cells = <0>; + devfreq-events = <&ppmu_leftbus_3>, <&ppmu_rightbus_3>; + vdd-supply = <&buck3_reg>; + }; + + display: bus-display { + compatible = "samsung,exynos-bus"; + clocks = <&clock CLK_DIV_ACLK_266>; + clock-names = "bus"; + operating-points-v2 = <&bus_display_opp_table>; + interconnects = <&leftbus &dmc>; + #interconnect-cells = <0>; + devfreq = <&leftbus>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,rzg2l-irqc.yaml b/Documentation/devicetree/bindings/interrupt-controller/renesas,rzg2l-irqc.yaml new file mode 100644 index 000000000000..33b90e975e33 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/renesas,rzg2l-irqc.yaml @@ -0,0 +1,134 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/renesas,rzg2l-irqc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/G2L (and alike SoC's) Interrupt Controller (IA55) + +maintainers: + - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com> + - Geert Uytterhoeven <geert+renesas@glider.be> + +description: | + IA55 performs various interrupt controls including synchronization for the external + interrupts of NMI, IRQ, and GPIOINT and the interrupts of the built-in peripheral + interrupts output by each IP. And it notifies the interrupt to the GIC + - IRQ sense select for 8 external interrupts, mapped to 8 GIC SPI interrupts + - GPIO pins used as external interrupt input pins, mapped to 32 GIC SPI interrupts + - NMI edge select (NMI is not treated as NMI exception and supports fall edge and + stand-up edge detection interrupts) + +allOf: + - $ref: /schemas/interrupt-controller.yaml# + +properties: + compatible: + items: + - enum: + - renesas,r9a07g044-irqc # RZ/G2{L,LC} + - renesas,r9a07g054-irqc # RZ/V2L + - const: renesas,rzg2l-irqc + + '#interrupt-cells': + description: The first cell should contain external interrupt number (IRQ0-7) and the + second cell is used to specify the flag. + const: 2 + + '#address-cells': + const: 0 + + interrupt-controller: true + + reg: + maxItems: 1 + + interrupts: + maxItems: 41 + + clocks: + maxItems: 2 + + clock-names: + items: + - const: clk + - const: pclk + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - '#interrupt-cells' + - '#address-cells' + - interrupt-controller + - reg + - interrupts + - clocks + - clock-names + - power-domains + - resets + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/r9a07g044-cpg.h> + + irqc: interrupt-controller@110a0000 { + compatible = "renesas,r9a07g044-irqc", "renesas,rzg2l-irqc"; + reg = <0x110a0000 0x10000>; + #interrupt-cells = <2>; + #address-cells = <0>; + interrupt-controller; + interrupts = <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 444 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 445 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 446 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 447 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 448 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 449 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 450 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 451 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 452 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 453 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 454 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 455 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 456 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 457 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 458 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 459 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 460 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 461 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 462 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 463 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 464 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 465 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 466 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 467 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 468 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 469 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 470 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 471 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 472 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 473 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 474 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 475 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD R9A07G044_IA55_CLK>, + <&cpg CPG_MOD R9A07G044_IA55_PCLK>; + clock-names = "clk", "pclk"; + power-domains = <&cpg>; + resets = <&cpg R9A07G044_IA55_RESETN>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml b/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml index 27092c6a86c4..92e0f8c3eff2 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml @@ -26,9 +26,14 @@ description: with priority below this threshold will not cause the PLIC to raise its interrupt line leading to the context. - While the PLIC supports both edge-triggered and level-triggered interrupts, - interrupt handlers are oblivious to this distinction and therefore it is not - specified in the PLIC device-tree binding. + The PLIC supports both edge-triggered and level-triggered interrupts. For + edge-triggered interrupts, the RISC-V PLIC spec allows two responses to edges + seen while an interrupt handler is active; the PLIC may either queue them or + ignore them. In the first case, handlers are oblivious to the trigger type, so + it is not included in the interrupt specifier. In the second case, software + needs to know the trigger type, so it can reorder the interrupt flow to avoid + missing interrupts. This special handling is needed by at least the Renesas + RZ/Five SoC (AX45MP AndesCore with a NCEPLIC100) and the T-HEAD C900 PLIC. While the RISC-V ISA doesn't specify a memory layout for the PLIC, the "sifive,plic-1.0.0" device is a concrete implementation of the PLIC that @@ -49,6 +54,10 @@ properties: oneOf: - items: - enum: + - renesas,r9a07g043-plic + - const: andestech,nceplic100 + - items: + - enum: - sifive,fu540-c000-plic - starfive,jh7100-plic - canaan,k210-plic @@ -64,8 +73,7 @@ properties: '#address-cells': const: 0 - '#interrupt-cells': - const: 1 + '#interrupt-cells': true interrupt-controller: true @@ -82,6 +90,12 @@ properties: description: Specifies how many external interrupts are supported by this controller. + clocks: true + + power-domains: true + + resets: true + required: - compatible - '#address-cells' @@ -91,6 +105,47 @@ required: - interrupts-extended - riscv,ndev +allOf: + - if: + properties: + compatible: + contains: + enum: + - andestech,nceplic100 + - thead,c900-plic + + then: + properties: + '#interrupt-cells': + const: 2 + + else: + properties: + '#interrupt-cells': + const: 1 + + - if: + properties: + compatible: + contains: + const: renesas,r9a07g043-plic + + then: + properties: + clocks: + maxItems: 1 + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + required: + - clocks + - power-domains + - resets + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/interrupt-controller/socionext,uniphier-aidet.yaml b/Documentation/devicetree/bindings/interrupt-controller/socionext,uniphier-aidet.yaml index f89ebde76dab..de7c5e59bae1 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/socionext,uniphier-aidet.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/socionext,uniphier-aidet.yaml @@ -30,6 +30,7 @@ properties: - socionext,uniphier-ld11-aidet - socionext,uniphier-ld20-aidet - socionext,uniphier-pxs3-aidet + - socionext,uniphier-nx1-aidet reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/interrupt-controller/sunplus,sp7021-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/sunplus,sp7021-intc.yaml new file mode 100644 index 000000000000..bd0021dbab0b --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/sunplus,sp7021-intc.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) Sunplus Co., Ltd. 2021 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/sunplus,sp7021-intc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sunplus SP7021 SoC Interrupt Controller + +maintainers: + - Qin Jian <qinjian@cqplus1.com> + +properties: + compatible: + items: + - const: sunplus,sp7021-intc + + reg: + maxItems: 2 + description: + Specifies base physical address(s) and size of the controller regs. + The 1st region include type/polarity/priority/mask regs. + The 2nd region include clear/masked_ext0/masked_ext1/group regs. + + interrupt-controller: true + + "#interrupt-cells": + const: 2 + description: + The first cell is the IRQ number, the second cell is the trigger + type as defined in interrupt.txt in this directory. + + interrupts: + maxItems: 2 + description: + EXT_INT0 & EXT_INT1, 2 interrupts references to primary interrupt + controller. + +required: + - compatible + - reg + - interrupt-controller + - "#interrupt-cells" + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + intc: interrupt-controller@9c000780 { + compatible = "sunplus,sp7021-intc"; + reg = <0x9c000780 0x80>, <0x9c000a80 0x80>; + interrupt-controller; + #interrupt-cells = <2>; + interrupt-parent = <&gic>; + interrupts = <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>, /* EXT_INT0 */ + <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>; /* EXT_INT1 */ + }; + +... diff --git a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.yaml b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.yaml index a98b359bf909..71bc5cefb49c 100644 --- a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.yaml @@ -32,6 +32,7 @@ properties: - mediatek,mt2701-smi-common - mediatek,mt2712-smi-common - mediatek,mt6779-smi-common + - mediatek,mt6795-smi-common - mediatek,mt8167-smi-common - mediatek,mt8173-smi-common - mediatek,mt8183-smi-common diff --git a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml index c886681f62a7..59dcd163668f 100644 --- a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml @@ -20,6 +20,7 @@ properties: - mediatek,mt2701-smi-larb - mediatek,mt2712-smi-larb - mediatek,mt6779-smi-larb + - mediatek,mt6795-smi-larb - mediatek,mt8167-smi-larb - mediatek,mt8173-smi-larb - mediatek,mt8183-smi-larb diff --git a/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml b/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml index 6a4831fd3616..55fc620c72cd 100644 --- a/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml +++ b/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml @@ -22,6 +22,7 @@ properties: - enum: - allwinner,sun20i-d1-emac - allwinner,sun50i-h6-emac + - allwinner,sun50i-h616-emac0 - const: allwinner,sun50i-a64-emac reg: diff --git a/Documentation/devicetree/bindings/net/ethernet-controller.yaml b/Documentation/devicetree/bindings/net/ethernet-controller.yaml index 4f15463611f8..170cd201adc2 100644 --- a/Documentation/devicetree/bindings/net/ethernet-controller.yaml +++ b/Documentation/devicetree/bindings/net/ethernet-controller.yaml @@ -167,70 +167,65 @@ properties: - in-band-status fixed-link: - allOf: - - if: - type: array - then: - deprecated: true - items: - - minimum: 0 - maximum: 31 - description: - Emulated PHY ID, choose any but unique to the all - specified fixed-links - - - enum: [0, 1] - description: - Duplex configuration. 0 for half duplex or 1 for - full duplex - - - enum: [10, 100, 1000, 2500, 10000] - description: - Link speed in Mbits/sec. - - - enum: [0, 1] - description: - Pause configuration. 0 for no pause, 1 for pause - - - enum: [0, 1] - description: - Asymmetric pause configuration. 0 for no asymmetric - pause, 1 for asymmetric pause - - - - if: - type: object - then: - properties: - speed: - description: - Link speed. - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [10, 100, 1000, 2500, 10000] - - full-duplex: - $ref: /schemas/types.yaml#/definitions/flag - description: - Indicates that full-duplex is used. When absent, half - duplex is assumed. - - pause: - $ref: /schemas/types.yaml#definitions/flag - description: - Indicates that pause should be enabled. - - asym-pause: - $ref: /schemas/types.yaml#/definitions/flag - description: - Indicates that asym_pause should be enabled. - - link-gpios: - maxItems: 1 - description: - GPIO to determine if the link is up - - required: - - speed + oneOf: + - $ref: /schemas/types.yaml#/definitions/uint32-array + deprecated: true + items: + - minimum: 0 + maximum: 31 + description: + Emulated PHY ID, choose any but unique to the all + specified fixed-links + + - enum: [0, 1] + description: + Duplex configuration. 0 for half duplex or 1 for + full duplex + + - enum: [10, 100, 1000, 2500, 10000] + description: + Link speed in Mbits/sec. + + - enum: [0, 1] + description: + Pause configuration. 0 for no pause, 1 for pause + + - enum: [0, 1] + description: + Asymmetric pause configuration. 0 for no asymmetric + pause, 1 for asymmetric pause + - type: object + additionalProperties: false + properties: + speed: + description: + Link speed. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [10, 100, 1000, 2500, 10000] + + full-duplex: + $ref: /schemas/types.yaml#/definitions/flag + description: + Indicates that full-duplex is used. When absent, half + duplex is assumed. + + pause: + $ref: /schemas/types.yaml#definitions/flag + description: + Indicates that pause should be enabled. + + asym-pause: + $ref: /schemas/types.yaml#/definitions/flag + description: + Indicates that asym_pause should be enabled. + + link-gpios: + maxItems: 1 + description: + GPIO to determine if the link is up + + required: + - speed additionalProperties: true diff --git a/Documentation/devicetree/bindings/net/fsl,fec.yaml b/Documentation/devicetree/bindings/net/fsl,fec.yaml index daa2f79a294f..1b1853062cd3 100644 --- a/Documentation/devicetree/bindings/net/fsl,fec.yaml +++ b/Documentation/devicetree/bindings/net/fsl,fec.yaml @@ -183,6 +183,7 @@ properties: Should specify the gpio for phy reset. phy-reset-duration: + $ref: /schemas/types.yaml#/definitions/uint32 deprecated: true description: Reset duration in milliseconds. Should present only if property @@ -191,12 +192,14 @@ properties: and 1 millisecond will be used instead. phy-reset-active-high: + type: boolean deprecated: true description: If present then the reset sequence using the GPIO specified in the "phy-reset-gpios" property is reversed (H=reset state, L=operation state). phy-reset-post-delay: + $ref: /schemas/types.yaml#/definitions/uint32 deprecated: true description: Post reset delay in milliseconds. If present then a delay of phy-reset-post-delay diff --git a/Documentation/devicetree/bindings/net/pcs/renesas,rzn1-miic.yaml b/Documentation/devicetree/bindings/net/pcs/renesas,rzn1-miic.yaml new file mode 100644 index 000000000000..2d33bbab7163 --- /dev/null +++ b/Documentation/devicetree/bindings/net/pcs/renesas,rzn1-miic.yaml @@ -0,0 +1,171 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/pcs/renesas,rzn1-miic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/N1 MII converter + +maintainers: + - Clément Léger <clement.leger@bootlin.com> + +description: | + This MII converter is present on the Renesas RZ/N1 SoC family. It is + responsible to do MII passthrough or convert it to RMII/RGMII. + +properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + compatible: + items: + - enum: + - renesas,r9a06g032-miic + - const: renesas,rzn1-miic + + reg: + maxItems: 1 + + clocks: + items: + - description: MII reference clock + - description: RGMII reference clock + - description: RMII reference clock + - description: AHB clock used for the MII converter register interface + + clock-names: + items: + - const: mii_ref + - const: rgmii_ref + - const: rmii_ref + - const: hclk + + renesas,miic-switch-portin: + description: MII Switch PORTIN configuration. This value should use one of + the values defined in dt-bindings/net/pcs-rzn1-miic.h. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [1, 2] + + power-domains: + maxItems: 1 + +patternProperties: + "^mii-conv@[0-5]$": + type: object + description: MII converter port + + properties: + reg: + description: MII Converter port number. + enum: [1, 2, 3, 4, 5] + + renesas,miic-input: + description: Converter input port configuration. This value should use + one of the values defined in dt-bindings/net/pcs-rzn1-miic.h. + $ref: /schemas/types.yaml#/definitions/uint32 + + required: + - reg + - renesas,miic-input + + additionalProperties: false + + allOf: + - if: + properties: + reg: + const: 1 + then: + properties: + renesas,miic-input: + const: 0 + - if: + properties: + reg: + const: 2 + then: + properties: + renesas,miic-input: + enum: [1, 11] + - if: + properties: + reg: + const: 3 + then: + properties: + renesas,miic-input: + enum: [7, 10] + - if: + properties: + reg: + const: 4 + then: + properties: + renesas,miic-input: + enum: [4, 6, 9, 13] + - if: + properties: + reg: + const: 5 + then: + properties: + renesas,miic-input: + enum: [3, 5, 8, 12] + +required: + - '#address-cells' + - '#size-cells' + - compatible + - reg + - clocks + - clock-names + - power-domains + +additionalProperties: false + +examples: + - | + #include <dt-bindings/net/pcs-rzn1-miic.h> + #include <dt-bindings/clock/r9a06g032-sysctrl.h> + + eth-miic@44030000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "renesas,r9a06g032-miic", "renesas,rzn1-miic"; + reg = <0x44030000 0x10000>; + clocks = <&sysctrl R9A06G032_CLK_MII_REF>, + <&sysctrl R9A06G032_CLK_RGMII_REF>, + <&sysctrl R9A06G032_CLK_RMII_REF>, + <&sysctrl R9A06G032_HCLK_SWITCH_RG>; + clock-names = "mii_ref", "rgmii_ref", "rmii_ref", "hclk"; + renesas,miic-switch-portin = <MIIC_GMAC2_PORT>; + power-domains = <&sysctrl>; + + mii_conv1: mii-conv@1 { + renesas,miic-input = <MIIC_GMAC1_PORT>; + reg = <1>; + }; + + mii_conv2: mii-conv@2 { + renesas,miic-input = <MIIC_SWITCH_PORTD>; + reg = <2>; + }; + + mii_conv3: mii-conv@3 { + renesas,miic-input = <MIIC_SWITCH_PORTC>; + reg = <3>; + }; + + mii_conv4: mii-conv@4 { + renesas,miic-input = <MIIC_SWITCH_PORTB>; + reg = <4>; + }; + + mii_conv5: mii-conv@5 { + renesas,miic-input = <MIIC_SWITCH_PORTA>; + reg = <5>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/wireless/qca,ath9k.yaml b/Documentation/devicetree/bindings/net/wireless/qca,ath9k.yaml index 8cd0adbf7021..7029cb1f38ff 100644 --- a/Documentation/devicetree/bindings/net/wireless/qca,ath9k.yaml +++ b/Documentation/devicetree/bindings/net/wireless/qca,ath9k.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Atheros ath9k wireless devices Generic Binding maintainers: - - Kalle Valo <kvalo@codeaurora.org> + - Toke Høiland-Jørgensen <toke@toke.dk> description: | This node provides properties for configuring the ath9k wireless device. diff --git a/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml b/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml index 8c01fdba134b..a677b056f112 100644 --- a/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml +++ b/Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml @@ -9,7 +9,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies ath11k wireless devices Generic Binding maintainers: - - Kalle Valo <kvalo@codeaurora.org> + - Kalle Valo <kvalo@kernel.org> description: | These are dt entries for Qualcomm Technologies, Inc. IEEE 802.11ax diff --git a/Documentation/devicetree/bindings/nvmem/fsl,scu-ocotp.yaml b/Documentation/devicetree/bindings/nvmem/fsl,scu-ocotp.yaml new file mode 100644 index 000000000000..682688299b26 --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/fsl,scu-ocotp.yaml @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/nvmem/fsl,scu-ocotp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: i.MX SCU Client Device Node - OCOTP bindings based on SCU Message Protocol + +maintainers: + - Dong Aisheng <aisheng.dong@nxp.com> + +description: i.MX SCU Client Device Node + Client nodes are maintained as children of the relevant IMX-SCU device node. + +allOf: + - $ref: nvmem.yaml# + +properties: + compatible: + enum: + - fsl,imx8qm-scu-ocotp + - fsl,imx8qxp-scu-ocotp + +patternProperties: + '^mac@[0-9a-f]*$': + type: object + description: + MAC address. + + properties: + reg: + description: + Byte offset within OCOTP where the MAC address is stored + maxItems: 1 + + required: + - reg + + additionalProperties: false + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + ocotp { + compatible = "fsl,imx8qxp-scu-ocotp"; + #address-cells = <1>; + #size-cells = <1>; + + fec_mac0: mac@2c4 { + reg = <0x2c4 6>; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/allwinner,sun4i-a10-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/allwinner,sun4i-a10-pinctrl.yaml index bfce850c2035..0681b9a3965f 100644 --- a/Documentation/devicetree/bindings/pinctrl/allwinner,sun4i-a10-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/allwinner,sun4i-a10-pinctrl.yaml @@ -127,20 +127,17 @@ patternProperties: additionalProperties: false - "^vcc-p[a-hlm]-supply$": + "^vcc-p[a-ilm]-supply$": description: Power supplies for pin banks. required: - "#gpio-cells" - - "#interrupt-cells" - compatible - reg - - interrupts - clocks - clock-names - gpio-controller - - interrupt-controller allOf: # FIXME: We should have the pin bank supplies here, but not a lot of @@ -149,6 +146,19 @@ allOf: - $ref: "pinctrl.yaml#" - if: + not: + properties: + compatible: + enum: + - allwinner,sun50i-h616-r-pinctrl + + then: + required: + - "#interrupt-cells" + - interrupts + - interrupt-controller + + - if: properties: compatible: enum: diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,scu-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/fsl,scu-pinctrl.yaml new file mode 100644 index 000000000000..45ea565ce238 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/fsl,scu-pinctrl.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/fsl,scu-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: i.MX SCU Client Device Node - Pinctrl bindings based on SCU Message Protocol + +maintainers: + - Dong Aisheng <aisheng.dong@nxp.com> + +description: i.MX SCU Client Device Node + Client nodes are maintained as children of the relevant IMX-SCU device node. + This binding uses the i.MX common pinctrl binding. + (Documentation/devicetree/bindings/pinctrl/fsl,imx-pinctrl.txt) + +allOf: + - $ref: pinctrl.yaml# + +properties: + compatible: + enum: + - fsl,imx8qm-iomuxc + - fsl,imx8qxp-iomuxc + - fsl,imx8dxl-iomuxc + +patternProperties: + 'grp$': + type: object + description: + Pinctrl node's client devices use subnodes for desired pin configuration. + Client device subnodes use below standard properties. + + properties: + fsl,pins: + description: + each entry consists of 3 integers and represents the pin ID, the mux value + and pad setting for the pin. The first 2 integers - pin_id and mux_val - are + specified using a PIN_FUNC_ID macro, which can be found in + <include/dt-bindings/pinctrl/pads-imx8qxp.h>. The last integer is + the pad setting value like pull-up on this pin. Please refer to the + appropriate i.MX8 Reference Manual for detailed pad CONFIG settings. + $ref: /schemas/types.yaml#/definitions/uint32-matrix + items: + items: + - description: | + "pin_id" indicates the pin ID + - description: | + "mux_val" indicates the mux value to be applied. + - description: | + "pad_setting" indicates the pad configuration value to be applied. + + required: + - fsl,pins + + additionalProperties: false + +required: + - compatible + +additionalProperties: false + +examples: + - | + pinctrl { + compatible = "fsl,imx8qxp-iomuxc"; + + pinctrl_lpuart0: lpuart0grp { + fsl,pins = < + 111 0 0x06000020 + 112 0 0x06000020 + >; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml index 52df1b146174..997b74639112 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml @@ -47,6 +47,17 @@ properties: gpio-ranges: maxItems: 1 + interrupt-controller: true + + '#interrupt-cells': + const: 2 + description: + The first cell contains the global GPIO port index, constructed using the + RZG2L_GPIO() helper macro in <dt-bindings/pinctrl/rzg2l-pinctrl.h> and the + second cell is used to specify the flag. + E.g. "interrupts = <RZG2L_GPIO(43, 0) IRQ_TYPE_EDGE_FALLING>;" if P43_0 is + being used as an interrupt. + clocks: maxItems: 1 @@ -110,6 +121,8 @@ required: - gpio-controller - '#gpio-cells' - gpio-ranges + - interrupt-controller + - '#interrupt-cells' - clocks - power-domains - resets @@ -126,6 +139,8 @@ examples: gpio-controller; #gpio-cells = <2>; gpio-ranges = <&pinctrl 0 0 392>; + interrupt-controller; + #interrupt-cells = <2>; clocks = <&cpg CPG_MOD R9A07G044_GPIO_HCLK>; resets = <&cpg R9A07G044_GPIO_RSTN>, <&cpg R9A07G044_GPIO_PORT_RESETN>, diff --git a/Documentation/devicetree/bindings/power/fsl,scu-pd.yaml b/Documentation/devicetree/bindings/power/fsl,scu-pd.yaml new file mode 100644 index 000000000000..1f72b18ca0fc --- /dev/null +++ b/Documentation/devicetree/bindings/power/fsl,scu-pd.yaml @@ -0,0 +1,41 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/fsl,scu-pd.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: i.MX SCU Client Device Node - Power domain bindings based on SCU Message Protocol + +maintainers: + - Dong Aisheng <aisheng.dong@nxp.com> + +description: i.MX SCU Client Device Node + Client nodes are maintained as children of the relevant IMX-SCU device node. + Power domain bindings based on SCU Message Protocol + +allOf: + - $ref: power-domain.yaml# + +properties: + compatible: + items: + - enum: + - fsl,imx8qm-scu-pd + - fsl,imx8qxp-scu-pd + - const: fsl,scu-pd + + '#power-domain-cells': + const: 1 + +required: + - compatible + - '#power-domain-cells' + +additionalProperties: false + +examples: + - | + power-controller { + compatible = "fsl,imx8qxp-scu-pd", "fsl,scu-pd"; + #power-domain-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/power/mediatek,power-controller.yaml b/Documentation/devicetree/bindings/power/mediatek,power-controller.yaml index 135c6f722091..b448101fac43 100644 --- a/Documentation/devicetree/bindings/power/mediatek,power-controller.yaml +++ b/Documentation/devicetree/bindings/power/mediatek,power-controller.yaml @@ -23,6 +23,7 @@ properties: compatible: enum: + - mediatek,mt6795-power-controller - mediatek,mt8167-power-controller - mediatek,mt8173-power-controller - mediatek,mt8183-power-controller @@ -62,6 +63,7 @@ patternProperties: reg: description: | Power domain index. Valid values are defined in: + "include/dt-bindings/power/mt6795-power.h" - for MT8167 type power domain. "include/dt-bindings/power/mt8167-power.h" - for MT8167 type power domain. "include/dt-bindings/power/mt8173-power.h" - for MT8173 type power domain. "include/dt-bindings/power/mt8183-power.h" - for MT8183 type power domain. diff --git a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml index ad77a6380f38..0ccca493251a 100644 --- a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml +++ b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml @@ -18,6 +18,7 @@ properties: enum: - qcom,mdm9607-rpmpd - qcom,msm8226-rpmpd + - qcom,msm8909-rpmpd - qcom,msm8916-rpmpd - qcom,msm8939-rpmpd - qcom,msm8953-rpmpd diff --git a/Documentation/devicetree/bindings/pwm/clk-pwm.yaml b/Documentation/devicetree/bindings/pwm/clk-pwm.yaml new file mode 100644 index 000000000000..ec1768291503 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/clk-pwm.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/clk-pwm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Clock based PWM controller + +maintainers: + - Nikita Travkin <nikita@trvn.ru> + +description: | + Some systems have clocks that can be exposed to external devices. + (e.g. by muxing them to GPIO pins) + It's often possible to control duty-cycle of such clocks which makes them + suitable for generating PWM signal. + +allOf: + - $ref: pwm.yaml# + +properties: + compatible: + const: clk-pwm + + clocks: + description: Clock used to generate the signal. + maxItems: 1 + + "#pwm-cells": + const: 2 + +unevaluatedProperties: false + +required: + - compatible + - clocks + +examples: + - | + pwm { + compatible = "clk-pwm"; + #pwm-cells = <2>; + clocks = <&gcc 0>; + pinctrl-names = "default"; + pinctrl-0 = <&pwm_clk_flash_default>; + }; diff --git a/Documentation/devicetree/bindings/pwm/pwm-mediatek.txt b/Documentation/devicetree/bindings/pwm/pwm-mediatek.txt index 033d1fc0f405..554c96b6d0c3 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-mediatek.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-mediatek.txt @@ -9,6 +9,8 @@ Required properties: - "mediatek,mt7628-pwm": found on mt7628 SoC. - "mediatek,mt7629-pwm": found on mt7629 SoC. - "mediatek,mt8183-pwm": found on mt8183 SoC. + - "mediatek,mt8195-pwm", "mediatek,mt8183-pwm": found on mt8195 SoC. + - "mediatek,mt8365-pwm": found on mt8365 SoC. - "mediatek,mt8516-pwm": found on mt8516 SoC. - reg: physical base address and length of the controller's registers. - #pwm-cells: must be 2. See pwm.yaml in this directory for a description of @@ -18,6 +20,7 @@ Required properties: has no clocks - "top": the top clock generator - "main": clock used by the PWM core + - "pwm1-3": the three per PWM clocks for mt8365 - "pwm1-8": the eight per PWM clocks for mt2712 - "pwm1-6": the six per PWM clocks for mt7622 - "pwm1-5": the five per PWM clocks for mt7623 diff --git a/Documentation/devicetree/bindings/regulator/mps,mp5416.yaml b/Documentation/devicetree/bindings/regulator/mps,mp5416.yaml index 90727fdc1283..7023c597c3ed 100644 --- a/Documentation/devicetree/bindings/regulator/mps,mp5416.yaml +++ b/Documentation/devicetree/bindings/regulator/mps,mp5416.yaml @@ -15,6 +15,7 @@ properties: compatible: enum: - mps,mp5416 + - mps,mp5496 reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/regulator/pwm-regulator.txt b/Documentation/devicetree/bindings/regulator/pwm-regulator.txt deleted file mode 100644 index 3d78d507e29f..000000000000 --- a/Documentation/devicetree/bindings/regulator/pwm-regulator.txt +++ /dev/null @@ -1,92 +0,0 @@ -Bindings for the Generic PWM Regulator -====================================== - -Currently supports 2 modes of operation: - -Voltage Table: When in this mode, a voltage table (See below) of - predefined voltage <=> duty-cycle values must be - provided via DT. Limitations are that the regulator can - only operate at the voltages supplied in the table. - Intermediary duty-cycle values which would normally - allow finer grained voltage selection are ignored and - rendered useless. Although more control is given to - the user if the assumptions made in continuous-voltage - mode do not reign true. - -Continuous Voltage: This mode uses the regulator's maximum and minimum - supplied voltages specified in the - regulator-{min,max}-microvolt properties to calculate - appropriate duty-cycle values. This allows for a much - more fine grained solution when compared with - voltage-table mode above. This solution does make an - assumption that a %50 duty-cycle value will cause the - regulator voltage to run at half way between the - supplied max_uV and min_uV values. - -Required properties: --------------------- -- compatible: Should be "pwm-regulator" - -- pwms: PWM specification (See: ../pwm/pwm.txt) - -Only required for Voltage Table Mode: -- voltage-table: Voltage and Duty-Cycle table consisting of 2 cells - First cell is voltage in microvolts (uV) - Second cell is duty-cycle in percent (%) - -Optional properties for Continuous mode: -- pwm-dutycycle-unit: Integer value encoding the duty cycle unit. If not - defined, <100> is assumed, meaning that - pwm-dutycycle-range contains values expressed in - percent. - -- pwm-dutycycle-range: Should contain 2 entries. The first entry is encoding - the dutycycle for regulator-min-microvolt and the - second one the dutycycle for regulator-max-microvolt. - Duty cycle values are expressed in pwm-dutycycle-unit. - If not defined, <0 100> is assumed. - -NB: To be clear, if voltage-table is provided, then the device will be used -in Voltage Table Mode. If no voltage-table is provided, then the device will -be used in Continuous Voltage Mode. - -Optional properties: --------------------- -- enable-gpios: GPIO to use to enable/disable the regulator - -Any property defined as part of the core regulator binding can also be used. -(See: ../regulator/regulator.txt) - -Continuous Voltage With Enable GPIO Example: - pwm_regulator { - compatible = "pwm-regulator"; - pwms = <&pwm1 0 8448 0>; - enable-gpios = <&gpio0 23 GPIO_ACTIVE_HIGH>; - regulator-min-microvolt = <1016000>; - regulator-max-microvolt = <1114000>; - regulator-name = "vdd_logic"; - /* unit == per-mille */ - pwm-dutycycle-unit = <1000>; - /* - * Inverted PWM logic, and the duty cycle range is limited - * to 30%-70%. - */ - pwm-dutycycle-range = <700 300>; /* */ - }; - -Voltage Table Example: - pwm_regulator { - compatible = "pwm-regulator"; - pwms = <&pwm1 0 8448 0>; - regulator-min-microvolt = <1016000>; - regulator-max-microvolt = <1114000>; - regulator-name = "vdd_logic"; - - /* Voltage Duty-Cycle */ - voltage-table = <1114000 0>, - <1095000 10>, - <1076000 20>, - <1056000 30>, - <1036000 40>, - <1016000 50>; - }; diff --git a/Documentation/devicetree/bindings/regulator/pwm-regulator.yaml b/Documentation/devicetree/bindings/regulator/pwm-regulator.yaml new file mode 100644 index 000000000000..82b6f2fde422 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/pwm-regulator.yaml @@ -0,0 +1,126 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/pwm-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Bindings for the Generic PWM Regulator + +maintainers: + - Brian Norris <briannorris@chromium.org> + - Lee Jones <lee@kernel.org> + - Alexandre Courbot <acourbot@nvidia.com> + +description: | + Currently supports 2 modes of operation: + + Voltage Table: + When in this mode, a voltage table (See below) of predefined voltage <=> + duty-cycle values must be provided via DT. Limitations are that the + regulator can only operate at the voltages supplied in the table. + Intermediary duty-cycle values which would normally allow finer grained + voltage selection are ignored and rendered useless. Although more control + is given to the user if the assumptions made in continuous-voltage mode do + not reign true. + + Continuous Voltage: + This mode uses the regulator's maximum and minimum supplied voltages + specified in the regulator-{min,max}-microvolt properties to calculate + appropriate duty-cycle values. This allows for a much more fine grained + solution when compared with voltage-table mode above. This solution does + make an assumption that a %50 duty-cycle value will cause the regulator + voltage to run at half way between the supplied max_uV and min_uV values. + + If voltage-table is provided, then the device will be used in Voltage Table + Mode. If no voltage-table is provided, then the device will be used in + Continuous Voltage Mode. + +allOf: + - $ref: regulator.yaml# + +properties: + compatible: + const: pwm-regulator + + pwms: + maxItems: 1 + + voltage-table: + description: Voltage and Duty-Cycle table. + $ref: /schemas/types.yaml#/definitions/uint32-matrix + items: + items: + - description: voltage in microvolts (uV) + - description: duty-cycle in percent (%) + + enable-gpios: + description: Regulator enable GPIO + maxItems: 1 + + # Optional properties for Continuous mode: + pwm-dutycycle-unit: + description: + Integer value encoding the duty cycle unit. If not + defined, <100> is assumed, meaning that + pwm-dutycycle-range contains values expressed in + percent. + default: 100 + + pwm-dutycycle-range: + description: + Should contain 2 entries. The first entry is encoding + the dutycycle for regulator-min-microvolt and the + second one the dutycycle for regulator-max-microvolt. + Duty cycle values are expressed in pwm-dutycycle-unit. + If not defined, <0 100> is assumed. + $ref: /schemas/types.yaml#/definitions/uint32-array + items: + - description: the dutycycle for regulator-min-microvolt + - description: the dutycycle for regulator-max-microvolt + default: [ 0 100 ] + +required: + - compatible + - pwms + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + // Continuous Voltage With Enable GPIO Example: + regulator { + compatible = "pwm-regulator"; + pwms = <&pwm1 0 8448 0>; + enable-gpios = <&gpio0 23 GPIO_ACTIVE_HIGH>; + regulator-min-microvolt = <1016000>; + regulator-max-microvolt = <1114000>; + regulator-name = "vdd_logic"; + /* unit == per-mille */ + pwm-dutycycle-unit = <1000>; + /* + * Inverted PWM logic, and the duty cycle range is limited + * to 30%-70%. + */ + pwm-dutycycle-range = <700 300>; /* */ + }; + + - | + // Voltage Table Example: + regulator { + compatible = "pwm-regulator"; + pwms = <&pwm1 0 8448 0>; + regulator-min-microvolt = <1016000>; + regulator-max-microvolt = <1114000>; + regulator-name = "vdd_logic"; + + /* Voltage Duty-Cycle */ + voltage-table = <1114000 0>, + <1095000 10>, + <1076000 20>, + <1056000 30>, + <1036000 40>, + <1016000 50>; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml index 6a9a7eed466f..c233461cc980 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml @@ -30,6 +30,9 @@ description: For pm8841, s1, s2, s3, s4, s5, s6, s7, s8 + For pm8909, s1, s2, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, + l14, l15, l17, l18 + For pm8916, s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18 @@ -78,6 +81,7 @@ properties: - qcom,rpm-mp5496-regulators - qcom,rpm-pm8226-regulators - qcom,rpm-pm8841-regulators + - qcom,rpm-pm8909-regulators - qcom,rpm-pm8916-regulators - qcom,rpm-pm8941-regulators - qcom,rpm-pm8950-regulators diff --git a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt deleted file mode 100644 index c2a39b121b1b..000000000000 --- a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.txt +++ /dev/null @@ -1,347 +0,0 @@ -Qualcomm SPMI Regulators - -- compatible: - Usage: required - Value type: <string> - Definition: must be one of: - "qcom,pm8004-regulators" - "qcom,pm8005-regulators" - "qcom,pm8226-regulators" - "qcom,pm8841-regulators" - "qcom,pm8916-regulators" - "qcom,pm8941-regulators" - "qcom,pm8950-regulators" - "qcom,pm8994-regulators" - "qcom,pmi8994-regulators" - "qcom,pm660-regulators" - "qcom,pm660l-regulators" - "qcom,pms405-regulators" - -- interrupts: - Usage: optional - Value type: <prop-encoded-array> - Definition: List of OCP interrupts. - -- interrupt-names: - Usage: required if 'interrupts' property present - Value type: <string-array> - Definition: List of strings defining the names of the - interrupts in the 'interrupts' property 1-to-1. - Supported values are "ocp-<regulator_name>", where - <regulator_name> corresponds to a voltage switch - type regulator. - -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_s4-supply: -- vdd_s5-supply: -- vdd_s6-supply: -- vdd_s7-supply: -- vdd_s8-supply: - Usage: optional (pm8841 only) - Value type: <phandle> - Definition: Reference to regulator supplying the input pin, as - described in the data sheet. - -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_s4-supply: -- vdd_l1_l3-supply: -- vdd_l2-supply: -- vdd_l4_l5_l6-supply: -- vdd_l7-supply: -- vdd_l8_l11_l14_l15_l16-supply: -- vdd_l9_l10_l12_l13_l17_l18-supply: - Usage: optional (pm8916 only) - Value type: <phandle> - Definition: Reference to regulator supplying the input pin, as - described in the data sheet. - -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_l1_l3-supply: -- vdd_l2_lvs_1_2_3-supply: -- vdd_l4_l11-supply: -- vdd_l5_l7-supply: -- vdd_l6_l12_l14_l15-supply: -- vdd_l8_l16_l18_19-supply: -- vdd_l9_l10_l17_l22-supply: -- vdd_l13_l20_l23_l24-supply: -- vdd_l21-supply: -- vin_5vs-supply: - Usage: optional (pm8941 only) - Value type: <phandle> - Definition: Reference to regulator supplying the input pin, as - described in the data sheet. - -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_s4-supply: -- vdd_s4-supply: -- vdd_s5-supply: -- vdd_s6-supply: -- vdd_l1_l19-supply: -- vdd_l2_l23-supply: -- vdd_l3-supply: -- vdd_l4_l5_l6_l7_l16-supply: -- vdd_l8_l11_l12_l17_l22-supply: -- vdd_l9_l10_l13_l14_l15_l18-supply: -- vdd_l20-supply: -- vdd_l21-supply: - Usage: optional (pm8950 only) - Value type: <phandle> - Definition: reference to regulator supplying the input pin, as - described in the data sheet - -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_s4-supply: -- vdd_s5-supply: -- vdd_s6-supply: -- vdd_s7-supply: -- vdd_s8-supply: -- vdd_s9-supply: -- vdd_s10-supply: -- vdd_s11-supply: -- vdd_s12-supply: -- vdd_l1-supply: -- vdd_l2_l26_l28-supply: -- vdd_l3_l11-supply: -- vdd_l4_l27_l31-supply: -- vdd_l5_l7-supply: -- vdd_l6_l12_l32-supply: -- vdd_l8_l16_l30-supply: -- vdd_l9_l10_l18_l22-supply: -- vdd_l13_l19_l23_l24-supply: -- vdd_l14_l15-supply: -- vdd_l17_l29-supply: -- vdd_l20_l21-supply: -- vdd_l25-supply: -- vdd_lvs_1_2-supply: - Usage: optional (pm8994 only) - Value type: <phandle> - Definition: Reference to regulator supplying the input pin, as - described in the data sheet. - -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_l1-supply: - Usage: optional (pmi8994 only) - Value type: <phandle> - Definition: Reference to regulator supplying the input pin, as - described in the data sheet. - -- vdd_l1_l6_l7-supply: -- vdd_l2_l3-supply: -- vdd_l5-supply: -- vdd_l8_l9_l10_l11_l12_l13_l14-supply: -- vdd_l15_l16_l17_l18_l19-supply: -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_s5-supply: -- vdd_s6-supply: - Usage: optional (pm660 only) - Value type: <phandle> - Definition: Reference to regulator supplying the input pin, as - described in the data sheet. - -- vdd_l1_l9_l10-supply: -- vdd_l2-supply: -- vdd_l3_l5_l7_l8-supply: -- vdd_l4_l6-supply: -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_s4-supply: -- vdd_s5-supply: - Usage: optional (pm660l only) - Value type: <phandle> - Definition: Reference to regulator supplying the input pin, as - described in the data sheet. - -- vdd_l1_l2-supply: -- vdd_l3_l8-supply: -- vdd_l4-supply: -- vdd_l5_l6-supply: -- vdd_l10_l11_l12_l13-supply: -- vdd_l7-supply: -- vdd_l9-supply: -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_s4-supply: -- vdd_s5-supply - Usage: optional (pms405 only) - Value type: <phandle> - Definition: Reference to regulator supplying the input pin, as - described in the data sheet. - -- qcom,saw-reg: - Usage: optional - Value type: <phandle> - Description: Reference to syscon node defining the SAW registers. - - -The regulator node houses sub-nodes for each regulator within the device. Each -sub-node is identified using the node's name, with valid values listed for each -of the PMICs below. - -pm8004: - s2, s5 - -pm8005: - s1, s2, s3, s4 - -pm8841: - s1, s2, s3, s4, s5, s6, s7, s8 - -pm8916: - s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, - l14, l15, l16, l17, l18 - -pm8941: - s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, - l14, l15, l16, l17, l18, l19, l20, l21, l22, l23, l24, lvs1, lvs2, lvs3, - 5vs1, 5vs2 - -pm8994: - s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, l1, l2, l3, l4, l5, - l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, l20, - l21, l22, l23, l24, l25, l26, l27, l28, l29, l30, l31, l32, lvs1, lvs2 - -pmi8994: - s1, s2, s3, l1 - -The content of each sub-node is defined by the standard binding for regulators - -see regulator.txt - with additional custom properties described below: - -- regulator-initial-mode: - Usage: optional - Value type: <u32> - Description: 2 = Set initial mode to auto mode (automatically select - between HPM and LPM); not available on boost type - regulators. - - 1 = Set initial mode to high power mode (HPM), also referred - to as NPM. HPM consumes more ground current than LPM, but - it can source significantly higher load current. HPM is not - available on boost type regulators. For voltage switch type - regulators, HPM implies that over current protection and - soft start are active all the time. - - 0 = Set initial mode to low power mode (LPM). - -- qcom,ocp-max-retries: - Usage: optional - Value type: <u32> - Description: Maximum number of times to try toggling a voltage switch - off and back on as a result of consecutive over current - events. - -- qcom,ocp-retry-delay: - Usage: optional - Value type: <u32> - Description: Time to delay in milliseconds between each voltage switch - toggle after an over current event takes place. - -- qcom,pin-ctrl-enable: - Usage: optional - Value type: <u32> - Description: Bit mask specifying which hardware pins should be used to - enable the regulator, if any; supported bits are: - 0 = ignore all hardware enable signals - BIT(0) = follow HW0_EN signal - BIT(1) = follow HW1_EN signal - BIT(2) = follow HW2_EN signal - BIT(3) = follow HW3_EN signal - -- qcom,pin-ctrl-hpm: - Usage: optional - Value type: <u32> - Description: Bit mask specifying which hardware pins should be used to - force the regulator into high power mode, if any; - supported bits are: - 0 = ignore all hardware enable signals - BIT(0) = follow HW0_EN signal - BIT(1) = follow HW1_EN signal - BIT(2) = follow HW2_EN signal - BIT(3) = follow HW3_EN signal - BIT(4) = follow PMIC awake state - -- qcom,vs-soft-start-strength: - Usage: optional - Value type: <u32> - Description: This property sets the soft start strength for voltage - switch type regulators; supported values are: - 0 = 0.05 uA - 1 = 0.25 uA - 2 = 0.55 uA - 3 = 0.75 uA - -- qcom,saw-slave: - Usage: optional - Value type: <boo> - Description: SAW controlled gang slave. Will not be configured. - -- qcom,saw-leader: - Usage: optional - Value type: <boo> - Description: SAW controlled gang leader. Will be configured as - SAW regulator. - -Example: - - regulators { - compatible = "qcom,pm8941-regulators"; - vdd_l1_l3-supply = <&s1>; - - s1: s1 { - regulator-min-microvolt = <1300000>; - regulator-max-microvolt = <1400000>; - }; - - ... - - l1: l1 { - regulator-min-microvolt = <1225000>; - regulator-max-microvolt = <1300000>; - }; - - .... - }; - -Example 2: - - saw3: syscon@9A10000 { - compatible = "syscon"; - reg = <0x9A10000 0x1000>; - }; - - ... - - spm-regulators { - compatible = "qcom,pm8994-regulators"; - qcom,saw-reg = <&saw3>; - s8 { - qcom,saw-slave; - }; - s9 { - qcom,saw-slave; - }; - s10 { - qcom,saw-slave; - }; - pm8994_s11_saw: s11 { - qcom,saw-leader; - regulator-always-on; - regulator-min-microvolt = <900000>; - regulator-max-microvolt = <1140000>; - }; - }; diff --git a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml new file mode 100644 index 000000000000..8b7c4af4b551 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml @@ -0,0 +1,323 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/qcom,spmi-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SPMI Regulators + +maintainers: + - Robert Marko <robimarko@gmail.com> + +properties: + compatible: + enum: + - qcom,pm660-regulators + - qcom,pm660l-regulators + - qcom,pm8004-regulators + - qcom,pm8005-regulators + - qcom,pm8226-regulators + - qcom,pm8841-regulators + - qcom,pm8916-regulators + - qcom,pm8941-regulators + - qcom,pm8950-regulators + - qcom,pm8994-regulators + - qcom,pmi8994-regulators + - qcom,pmp8074-regulators + - qcom,pms405-regulators + + qcom,saw-reg: + description: Reference to syscon node defining the SAW registers + $ref: /schemas/types.yaml#/definitions/phandle + +patternProperties: + "^(5vs[1-2]|(l|s)[1-9][0-9]?|lvs[1-3])$": + description: List of regulators and its properties + type: object + $ref: regulator.yaml# + + properties: + qcom,ocp-max-retries: + description: + Maximum number of times to try toggling a voltage switch off and + back on as a result of consecutive over current events + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,ocp-retry-delay: + description: + Time to delay in milliseconds between each voltage switch toggle + after an over current event takes place + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,pin-ctrl-enable: + description: + Bit mask specifying which hardware pins should be used to enable the + regulator, if any. + Supported bits are + 0 = ignore all hardware enable signals + BIT(0) = follow HW0_EN signal + BIT(1) = follow HW1_EN signal + BIT(2) = follow HW2_EN signal + BIT(3) = follow HW3_EN signal + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 15 + + qcom,pin-ctrl-hpm: + description: + Bit mask specifying which hardware pins should be used to force the + regulator into high power mode, if any. + Supported bits are + 0 = ignore all hardware enable signals + BIT(0) = follow HW0_EN signal + BIT(1) = follow HW1_EN signal + BIT(2) = follow HW2_EN signal + BIT(3) = follow HW3_EN signal + BIT(4) = follow PMIC awake state + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 31 + + qcom,vs-soft-start-strength: + description: + This property sets the soft start strength for voltage switch type + regulators. + Supported values are + 0 = 0.05 uA + 1 = 0.25 uA + 2 = 0.55 uA + 3 = 0.75 uA + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 3 + + qcom,saw-slave: + description: SAW controlled gang slave. Will not be configured. + type: boolean + + qcom,saw-leader: + description: + SAW controlled gang leader. Will be configured as SAW regulator. + type: boolean + + unevaluatedProperties: false + +required: + - compatible + +allOf: + - if: + properties: + compatible: + contains: + enum: + - qcom,pm660-regulators + then: + properties: + vdd_l15_l16_l17_l18_l19-supply: true + vdd_l1_l6_l7-supply: true + vdd_l2_l3-supply: true + vdd_l5-supply: true + vdd_l8_l9_l10_l11_l12_l13_l14-supply: true + patternProperties: + "^vdd_s[1-6]-supply$": true + - if: + properties: + compatible: + contains: + enum: + - qcom,pm660l-regulators + then: + properties: + vdd_l1_l9_l10-supply: true + vdd_l2-supply: true + vdd_l3_l5_l7_l8-supply: true + vdd_l4_l6-supply: true + patternProperties: + "^vdd_s[1-5]-supply$": true + - if: + properties: + compatible: + contains: + enum: + - qcom,pm8004-regulators + then: + patternProperties: + "^vdd_s[25]-supply$": true + - if: + properties: + compatible: + contains: + enum: + - qcom,pm8005-regulators + then: + patternProperties: + "^vdd_s[1-4]-supply$": true + - if: + properties: + compatible: + contains: + enum: + - qcom,pm8226-regulators + then: + properties: + vdd_l10_l11_l13-supply: true + vdd_l12_l14-supply: true + vdd_l15_l16_l17_l18-supply: true + vdd_l19_l20_l21_l22_l23_l28-supply: true + vdd_l1_l2_l4_l5-supply: true + vdd_l25-supply: true + vdd_l3_l24_l26-supply: true + vdd_l6_l7_l8_l9_l27-supply: true + vdd_lvs1-supply: true + patternProperties: + "^vdd_s[1-5]-supply$": true + - if: + properties: + compatible: + contains: + enum: + - qcom,pm8841-regulators + then: + patternProperties: + "^vdd_s[1-8]-supply$": true + - if: + properties: + compatible: + contains: + enum: + - qcom,pm8916-regulators + then: + properties: + vdd_l1_l3-supply: true + vdd_l4_l5_l6-supply: true + vdd_l8_l11_l14_l15_l16-supply: true + vdd_l9_l10_l12_l13_l17_l18-supply: true + patternProperties: + "^vdd_l[27]-supply$": true + "^vdd_s[1-4]-supply$": true + - if: + properties: + compatible: + contains: + enum: + - qcom,pm8941-regulators + then: + properties: + interrupts: + items: + - description: Over-current protection interrupt for 5V S1 + - description: Over-current protection interrupt for 5V S2 + interrupt-names: + items: + - const: ocp-5vs1 + - const: ocp-5vs2 + vdd_l13_l20_l23_l24-supply: true + vdd_l1_l3-supply: true + vdd_l21-supply: true + vdd_l2_lvs_1_2_3-supply: true + vdd_l4_l11-supply: true + vdd_l5_l7-supply: true + vdd_l6_l12_l14_l15-supply: true + vdd_l8_l16_l18_19-supply: true + vdd_l9_l10_l17_l22-supply: true + vin_5vs-supply: true + patternProperties: + "^vdd_s[1-3]-supply$": true + - if: + properties: + compatible: + contains: + enum: + - qcom,pm8950-regulators + then: + properties: + vdd_l1_l19-supply: true + vdd_l20-supply: true + vdd_l21-supply: true + vdd_l2_l23-supply: true + vdd_l3-supply: true + vdd_l4_l5_l6_l7_l16-supply: true + vdd_l8_l11_l12_l17_l22-supply: true + vdd_l9_l10_l13_l14_l15_l18-supply: true + patternProperties: + "^vdd_s[1-6]-supply$": true + - if: + properties: + compatible: + contains: + enum: + - qcom,pm8994-regulators + then: + properties: + vdd_l1-supply: true + vdd_l13_l19_l23_l24-supply: true + vdd_l14_l15-supply: true + vdd_l17_l29-supply: true + vdd_l20_l21-supply: true + vdd_l25-supply: true + vdd_l2_l26_l28-supply: true + vdd_l3_l11-supply: true + vdd_l4_l27_l31-supply: true + vdd_l5_l7-supply: true + vdd_l6_l12_l32-supply: true + vdd_l8_l16_l30-supply: true + vdd_l9_l10_l18_l22-supply: true + vdd_lvs_1_2-supply: true + patternProperties: + "^vdd_s[1-9][0-2]?-supply$": true + - if: + properties: + compatible: + contains: + enum: + - qcom,pmi8994-regulators + then: + properties: + vdd_l1-supply: true + patternProperties: + "^vdd_s[1-3]-supply$": true + - if: + properties: + compatible: + contains: + enum: + - qcom,pmp8074-regulators + then: + properties: + vdd_l10_l11_l12_l13-supply: true + vdd_l1_l2-supply: true + vdd_l3_l8-supply: true + vdd_l5_l6_l15-supply: true + patternProperties: + "^vdd_l[479]-supply$": true + "^vdd_s[1-5]-supply$": true + - if: + properties: + compatible: + contains: + enum: + - qcom,pms405-regulators + then: + properties: + vdd_s3-supply: true + +unevaluatedProperties: false + +examples: + - | + regulators { + compatible = "qcom,pm8941-regulators"; + vdd_l1_l3-supply = <&s1>; + + s1: s1 { + regulator-min-microvolt = <1300000>; + regulator-max-microvolt = <1400000>; + }; + + l1: l1 { + regulator-min-microvolt = <1225000>; + regulator-max-microvolt = <1300000>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/regulator.yaml b/Documentation/devicetree/bindings/regulator/regulator.yaml index a9b66ececccf..6e8aa9eed3aa 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/regulator.yaml @@ -23,6 +23,7 @@ properties: regulator-microvolt-offset: description: Offset applied to voltages to compensate for voltage drops + $ref: "/schemas/types.yaml#/definitions/uint32" regulator-min-microamp: description: smallest current consumers may set diff --git a/Documentation/devicetree/bindings/reset/nuvoton,npcm750-reset.yaml b/Documentation/devicetree/bindings/reset/nuvoton,npcm750-reset.yaml index fa5e4ea6400e..d82e65e37cc0 100644 --- a/Documentation/devicetree/bindings/reset/nuvoton,npcm750-reset.yaml +++ b/Documentation/devicetree/bindings/reset/nuvoton,npcm750-reset.yaml @@ -11,7 +11,9 @@ maintainers: properties: compatible: - const: nuvoton,npcm750-reset + enum: + - nuvoton,npcm750-reset # Poleg NPCM7XX SoC + - nuvoton,npcm845-reset # Arbel NPCM8XX SoC reg: maxItems: 1 @@ -19,6 +21,10 @@ properties: '#reset-cells': const: 2 + nuvoton,sysgcr: + $ref: /schemas/types.yaml#/definitions/phandle + description: a phandle to access GCR registers. + nuvoton,sw-reset-number: $ref: /schemas/types.yaml#/definitions/uint32 minimum: 1 @@ -31,6 +37,7 @@ required: - compatible - reg - '#reset-cells' + - nuvoton,sysgcr additionalProperties: false @@ -41,6 +48,7 @@ examples: compatible = "nuvoton,npcm750-reset"; reg = <0xf0801000 0x70>; #reset-cells = <2>; + nuvoton,sysgcr = <&gcr>; nuvoton,sw-reset-number = <2>; }; diff --git a/Documentation/devicetree/bindings/reset/sunplus,reset.yaml b/Documentation/devicetree/bindings/reset/sunplus,reset.yaml new file mode 100644 index 000000000000..f24646ba9761 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/sunplus,reset.yaml @@ -0,0 +1,38 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) Sunplus Co., Ltd. 2021 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/reset/sunplus,reset.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Sunplus SoC Reset Controller + +maintainers: + - Qin Jian <qinjian@cqplus1.com> + +properties: + compatible: + const: sunplus,sp7021-reset + + reg: + maxItems: 1 + + "#reset-cells": + const: 1 + +required: + - compatible + - reg + - "#reset-cells" + +additionalProperties: false + +examples: + - | + rstc: reset@9c000054 { + compatible = "sunplus,sp7021-reset"; + reg = <0x9c000054 0x28>; + #reset-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/rtc/fsl,scu-rtc.yaml b/Documentation/devicetree/bindings/rtc/fsl,scu-rtc.yaml new file mode 100644 index 000000000000..8c102b70d735 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/fsl,scu-rtc.yaml @@ -0,0 +1,31 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/fsl,scu-rtc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: i.MX SCU Client Device Node - RTC bindings based on SCU Message Protocol + +maintainers: + - Dong Aisheng <aisheng.dong@nxp.com> + +description: i.MX SCU Client Device Node + Client nodes are maintained as children of the relevant IMX-SCU device node. + +allOf: + - $ref: rtc.yaml# + +properties: + compatible: + const: fsl,imx8qxp-sc-rtc + +required: + - compatible + +additionalProperties: false + +examples: + - | + rtc { + compatible = "fsl,imx8qxp-sc-rtc"; + }; diff --git a/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-pm.txt b/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-pm.txt deleted file mode 100644 index 72ff033565e5..000000000000 --- a/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-pm.txt +++ /dev/null @@ -1,46 +0,0 @@ -BCM2835 PM (Power domains, watchdog) - -The PM block controls power domains and some reset lines, and includes -a watchdog timer. This binding supersedes the brcm,bcm2835-pm-wdt -binding which covered some of PM's register range and functionality. - -Required properties: - -- compatible: Should be "brcm,bcm2835-pm" -- reg: Specifies base physical address and size of the two - register ranges ("PM" and "ASYNC_BRIDGE" in that - order) -- clocks: a) v3d: The V3D clock from CPRMAN - b) peri_image: The PERI_IMAGE clock from CPRMAN - c) h264: The H264 clock from CPRMAN - d) isp: The ISP clock from CPRMAN -- #reset-cells: Should be 1. This property follows the reset controller - bindings[1]. -- #power-domain-cells: Should be 1. This property follows the power domain - bindings[2]. - -Optional properties: - -- timeout-sec: Contains the watchdog timeout in seconds -- system-power-controller: Whether the watchdog is controlling the - system power. This node follows the power controller bindings[3]. - -[1] Documentation/devicetree/bindings/reset/reset.txt -[2] Documentation/devicetree/bindings/power/power-domain.yaml -[3] Documentation/devicetree/bindings/power/power-controller.txt - -Example: - -pm { - compatible = "brcm,bcm2835-pm", "brcm,bcm2835-pm-wdt"; - #power-domain-cells = <1>; - #reset-cells = <1>; - reg = <0x7e100000 0x114>, - <0x7e00a000 0x24>; - clocks = <&clocks BCM2835_CLOCK_V3D>, - <&clocks BCM2835_CLOCK_PERI_IMAGE>, - <&clocks BCM2835_CLOCK_H264>, - <&clocks BCM2835_CLOCK_ISP>; - clock-names = "v3d", "peri_image", "h264", "isp"; - system-power-controller; -}; diff --git a/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-pm.yaml b/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-pm.yaml new file mode 100644 index 000000000000..e28ef198a801 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-pm.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/bcm/brcm,bcm2835-pm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: BCM2835 PM (Power domains, watchdog) + +description: | + The PM block controls power domains and some reset lines, and includes a + watchdog timer. + +maintainers: + - Nicolas Saenz Julienne <nsaenz@kernel.org> + +allOf: + - $ref: /schemas/watchdog/watchdog.yaml# + +properties: + compatible: + items: + - enum: + - brcm,bcm2835-pm + - brcm,bcm2711-pm + - const: brcm,bcm2835-pm-wdt + + reg: + minItems: 2 + maxItems: 3 + + reg-names: + minItems: 2 + items: + - const: pm + - const: asb + - const: rpivid_asb + + "#power-domain-cells": + const: 1 + + "#reset-cells": + const: 1 + + clocks: + minItems: 4 + maxItems: 4 + + clock-names: + items: + - const: v3d + - const: peri_image + - const: h264 + - const: isp + + system-power-controller: + type: boolean + + timeout-sec: true + +required: + - compatible + - reg + - "#power-domain-cells" + - "#reset-cells" + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/bcm2835.h> + + watchdog@7e100000 { + compatible = "brcm,bcm2835-pm", "brcm,bcm2835-pm-wdt"; + #power-domain-cells = <1>; + #reset-cells = <1>; + reg = <0x7e100000 0x114>, + <0x7e00a000 0x24>; + reg-names = "pm", "asb"; + clocks = <&clocks BCM2835_CLOCK_V3D>, + <&clocks BCM2835_CLOCK_PERI_IMAGE>, + <&clocks BCM2835_CLOCK_H264>, + <&clocks BCM2835_CLOCK_ISP>; + clock-names = "v3d", "peri_image", "h264", "isp"; + system-power-controller; + }; diff --git a/Documentation/devicetree/bindings/soc/mediatek/devapc.yaml b/Documentation/devicetree/bindings/soc/mediatek/devapc.yaml index 31e4d3c339bf..d0a4bc3b03e9 100644 --- a/Documentation/devicetree/bindings/soc/mediatek/devapc.yaml +++ b/Documentation/devicetree/bindings/soc/mediatek/devapc.yaml @@ -20,6 +20,7 @@ properties: compatible: enum: - mediatek,mt6779-devapc + - mediatek,mt8186-devapc reg: description: The base address of devapc register bank diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,mutex.yaml b/Documentation/devicetree/bindings/soc/mediatek/mediatek,mutex.yaml index 3fdad71210b4..627dcc3e8b32 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,mutex.yaml +++ b/Documentation/devicetree/bindings/soc/mediatek/mediatek,mutex.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/display/mediatek/mediatek,mutex.yaml# +$id: http://devicetree.org/schemas/soc/mediatek/mediatek,mutex.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Mediatek mutex @@ -55,6 +55,18 @@ properties: include/dt-bindings/gce/<chip>-gce.h of each chips. $ref: /schemas/types.yaml#/definitions/uint32-array + mediatek,gce-client-reg: + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + items: + - description: phandle of GCE + - description: GCE subsys id + - description: register offset + - description: register size + description: The register of client driver can be configured by gce with + 4 arguments defined in this property. Each GCE subsys id is mapping to + a client defined in the header include/dt-bindings/gce/<chip>-gce.h. + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/soc/mediatek/mtk-svs.yaml b/Documentation/devicetree/bindings/soc/mediatek/mtk-svs.yaml new file mode 100644 index 000000000000..d911fa2d40ef --- /dev/null +++ b/Documentation/devicetree/bindings/soc/mediatek/mtk-svs.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/mediatek/mtk-svs.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek Smart Voltage Scaling (SVS) Device Tree Bindings + +maintainers: + - Roger Lu <roger.lu@mediatek.com> + - Matthias Brugger <matthias.bgg@gmail.com> + - Kevin Hilman <khilman@kernel.org> + +description: |+ + The SVS engine is a piece of hardware which has several + controllers(banks) for calculating suitable voltage to + different power domains(CPU/GPU/CCI) according to + chip process corner, temperatures and other factors. Then DVFS + driver could apply SVS bank voltage to PMIC/Buck. + +properties: + compatible: + enum: + - mediatek,mt8183-svs + - mediatek,mt8192-svs + + reg: + maxItems: 1 + description: Address range of the MTK SVS controller. + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + description: Main clock for MTK SVS controller to work. + + clock-names: + const: main + + nvmem-cells: + minItems: 1 + description: + Phandle to the calibration data provided by a nvmem device. + items: + - description: SVS efuse for SVS controller + - description: Thermal efuse for SVS controller + + nvmem-cell-names: + items: + - const: svs-calibration-data + - const: t-calibration-data + + resets: + maxItems: 1 + + reset-names: + items: + - const: svs_rst + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - nvmem-cells + - nvmem-cell-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/mt8183-clk.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + svs@1100b000 { + compatible = "mediatek,mt8183-svs"; + reg = <0 0x1100b000 0 0x1000>; + interrupts = <GIC_SPI 127 IRQ_TYPE_LEVEL_LOW>; + clocks = <&infracfg CLK_INFRA_THERM>; + clock-names = "main"; + nvmem-cells = <&svs_calibration>, <&thermal_calibration>; + nvmem-cell-names = "svs-calibration-data", "t-calibration-data"; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml b/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml index 597d67fba92f..33748a061898 100644 --- a/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml +++ b/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) %YAML 1.2 --- -$id: "http://devicetree.org/schemas/soc/microchip/atmel,at91rm9200-tcb.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/soc/microchip/atmel,at91rm9200-tcb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Atmel Timer Counter Block @@ -75,7 +75,7 @@ patternProperties: "^pwm@[0-2]$": description: The timer block channels that are used as PWMs. - $ref: ../../pwm/pwm.yaml# + $ref: /schemas/pwm/pwm.yaml# type: object properties: compatible: diff --git a/Documentation/devicetree/bindings/soc/microchip/microchip,mpfs-sys-controller.yaml b/Documentation/devicetree/bindings/soc/microchip/microchip,mpfs-sys-controller.yaml index b0dae51e1d42..04ffee3a7c59 100644 --- a/Documentation/devicetree/bindings/soc/microchip/microchip,mpfs-sys-controller.yaml +++ b/Documentation/devicetree/bindings/soc/microchip/microchip,mpfs-sys-controller.yaml @@ -1,8 +1,8 @@ # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- -$id: "http://devicetree.org/schemas/soc/microchip/microchip,mpfs-sys-controller.yaml#" -$schema: "http://devicetree.org/meta-schemas/core.yaml#" +$id: http://devicetree.org/schemas/soc/microchip/microchip,mpfs-sys-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# title: Microchip PolarFire SoC (MPFS) MSS (microprocessor subsystem) system controller diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml index e2e173dfada7..d01e98768153 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml @@ -33,6 +33,7 @@ properties: - qcom,sm8150-aoss-qmp - qcom,sm8250-aoss-qmp - qcom,sm8350-aoss-qmp + - qcom,sm8450-aoss-qmp - const: qcom,aoss-qmp reg: diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,rpmh-rsc.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,rpmh-rsc.yaml index f5ecf4a8c377..4a50f1d27724 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,rpmh-rsc.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,rpmh-rsc.yaml @@ -65,33 +65,22 @@ properties: qcom,tcs-config: $ref: /schemas/types.yaml#/definitions/uint32-matrix + minItems: 4 + maxItems: 4 items: - - items: - - description: TCS type - enum: [ 0, 1, 2, 3 ] - - description: Number of TCS - - items: - - description: TCS type - enum: [ 0, 1, 2, 3 ] - - description: Number of TCS - - items: - - description: TCS type - enum: [ 0, 1, 2, 3] - - description: Numbe r of TCS - - items: - - description: TCS type - enum: [ 0, 1, 2, 3 ] - - description: Number of TCS + items: + - description: | + TCS type:: + - ACTIVE_TCS + - SLEEP_TCS + - WAKE_TCS + - CONTROL_TCS + enum: [ 0, 1, 2, 3 ] + - description: Number of TCS description: | The tuple defining the configuration of TCS. Must have two cells which describe each TCS type. The order of the TCS must match the hardware configuration. - Cell 1 (TCS Type):: TCS types to be specified:: - - ACTIVE_TCS - - SLEEP_TCS - - WAKE_TCS - - CONTROL_TCS - Cell 2 (Number of TCS):: <u32> qcom,tcs-offset: $ref: /schemas/types.yaml#/definitions/uint32 diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml index f0f1bf06aea6..50f834563e19 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml @@ -34,6 +34,7 @@ properties: - qcom,rpm-apq8084 - qcom,rpm-ipq6018 - qcom,rpm-msm8226 + - qcom,rpm-msm8909 - qcom,rpm-msm8916 - qcom,rpm-msm8936 - qcom,rpm-msm8953 @@ -51,6 +52,9 @@ properties: $ref: /schemas/clock/qcom,rpmcc.yaml# unevaluatedProperties: false + power-controller: + $ref: /schemas/power/qcom,rpmpd.yaml# + qcom,smd-channels: $ref: /schemas/types.yaml#/definitions/string-array description: Channel name used for the RPM communication diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,spm.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,spm.yaml index 07d2d5398345..f433e6e0a19f 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,spm.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,spm.yaml @@ -22,6 +22,7 @@ properties: - qcom,sdm660-silver-saw2-v4.1-l2 - qcom,msm8998-gold-saw2-v4.1-l2 - qcom,msm8998-silver-saw2-v4.1-l2 + - qcom,msm8909-saw2-v3.0-cpu - qcom,msm8916-saw2-v3.0-cpu - qcom,msm8226-saw2-v2.1-cpu - qcom,msm8974-saw2-v2.1-cpu diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.yaml index d891ecfb2691..5320504bb5e0 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.yaml @@ -77,7 +77,6 @@ properties: Should reference the tx-enable and tx-rings-empty SMEM states. qcom,smem-state-names: - $ref: /schemas/types.yaml#/definitions/string-array items: - const: tx-enable - const: tx-rings-empty diff --git a/Documentation/devicetree/bindings/soc/samsung/exynos-pmu.yaml b/Documentation/devicetree/bindings/soc/samsung/exynos-pmu.yaml index c30a6437030d..13bb8dfcefe6 100644 --- a/Documentation/devicetree/bindings/soc/samsung/exynos-pmu.yaml +++ b/Documentation/devicetree/bindings/soc/samsung/exynos-pmu.yaml @@ -49,9 +49,6 @@ properties: reg: maxItems: 1 - assigned-clock-parents: true - assigned-clocks: true - '#clock-cells': const: 1 @@ -77,14 +74,20 @@ properties: Must be identical to the that of the parent interrupt controller. const: 3 + reboot-mode: + $ref: /schemas/power/reset/syscon-reboot-mode.yaml + type: object + description: + Reboot mode to alter bootloader behavior for the next boot + syscon-poweroff: - $ref: "../../power/reset/syscon-poweroff.yaml#" + $ref: /schemas/power/reset/syscon-poweroff.yaml# type: object description: Node for power off method syscon-reboot: - $ref: "../../power/reset/syscon-reboot.yaml#" + $ref: /schemas/power/reset/syscon-reboot.yaml# type: object description: Node for reboot method diff --git a/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml b/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml index fde886a8cf43..60b49562ff69 100644 --- a/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml +++ b/Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml @@ -22,8 +22,12 @@ properties: pattern: "^usi@[0-9a-f]+$" compatible: - enum: - - samsung,exynos850-usi # for USIv2 (Exynos850, ExynosAutoV9) + oneOf: + - items: + - const: samsung,exynosautov9-usi + - const: samsung,exynos850-usi + - enum: + - samsung,exynos850-usi reg: true diff --git a/Documentation/devicetree/bindings/soc/ti/ti,pruss.yaml b/Documentation/devicetree/bindings/soc/ti/ti,pruss.yaml index 64461d432004..847873289f25 100644 --- a/Documentation/devicetree/bindings/soc/ti/ti,pruss.yaml +++ b/Documentation/devicetree/bindings/soc/ti/ti,pruss.yaml @@ -65,10 +65,11 @@ properties: - ti,am4376-pruss0 # for AM437x SoC family and PRUSS unit 0 - ti,am4376-pruss1 # for AM437x SoC family and PRUSS unit 1 - ti,am5728-pruss # for AM57xx SoC family - - ti,k2g-pruss # for 66AK2G SoC family + - ti,am625-pruss # for K3 AM62x SoC family + - ti,am642-icssg # for K3 AM64x SoC family - ti,am654-icssg # for K3 AM65x SoC family - ti,j721e-icssg # for K3 J721E SoC family - - ti,am642-icssg # for K3 AM64x SoC family + - ti,k2g-pruss # for 66AK2G SoC family reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml index e9a533080b32..ef18a572a1ff 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml @@ -25,12 +25,12 @@ properties: - qcom,sc7280-lpass-cpu reg: - minItems: 2 + minItems: 1 maxItems: 6 description: LPAIF core registers reg-names: - minItems: 2 + minItems: 1 maxItems: 6 clocks: @@ -42,12 +42,12 @@ properties: maxItems: 10 interrupts: - minItems: 2 + minItems: 1 maxItems: 4 description: LPAIF DMA buffer interrupt interrupt-names: - minItems: 2 + minItems: 1 maxItems: 4 qcom,adsp: diff --git a/Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml b/Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml index 7e8d252f7bca..0d9840375132 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml +++ b/Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml @@ -13,6 +13,7 @@ properties: compatible: items: - enum: + - renesas,r9a07g043-ssi # RZ/G2UL - renesas,r9a07g044-ssi # RZ/G2{L,LC} - renesas,r9a07g054-ssi # RZ/V2L - const: renesas,rz-ssi @@ -50,7 +51,7 @@ properties: minItems: 1 maxItems: 2 description: - The first cell represents a phandle to dmac + The first cell represents a phandle to dmac. The second cell specifies the encoded MID/RID values of the SSI port connected to the DMA client and the slave channel configuration parameters. diff --git a/Documentation/devicetree/bindings/spi/atmel,at91rm9200-spi.yaml b/Documentation/devicetree/bindings/spi/atmel,at91rm9200-spi.yaml new file mode 100644 index 000000000000..d85d54024b2e --- /dev/null +++ b/Documentation/devicetree/bindings/spi/atmel,at91rm9200-spi.yaml @@ -0,0 +1,75 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2022 Microchip Technology, Inc. and its subsidiaries +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/atmel,at91rm9200-spi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Atmel SPI device + +maintainers: + - Tudor Ambarus <tudor.ambarus@microchip.com> + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + oneOf: + - const: atmel,at91rm9200-spi + - items: + - const: microchip,sam9x60-spi + - const: atmel,at91rm9200-spi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clock-names: + contains: + const: spi_clk + + clocks: + maxItems: 1 + + atmel,fifo-size: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Maximum number of data the RX and TX FIFOs can store for FIFO + capable SPI controllers. + enum: [ 16, 32 ] + +required: + - compatible + - reg + - interrupts + - clock-names + - clocks + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + spi1: spi@fffcc000 { + compatible = "atmel,at91rm9200-spi"; + reg = <0xfffcc000 0x4000>; + interrupts = <13 IRQ_TYPE_LEVEL_HIGH 5>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&spi1_clk>; + clock-names = "spi_clk"; + cs-gpios = <&pioB 3 GPIO_ACTIVE_HIGH>; + atmel,fifo-size = <32>; + + mmc@0 { + compatible = "mmc-spi-slot"; + reg = <0>; + gpios = <&pioC 4 GPIO_ACTIVE_HIGH>; /* CD */ + spi-max-frequency = <25000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/spi/hpe,gxp-spifi.yaml b/Documentation/devicetree/bindings/spi/hpe,gxp-spifi.yaml new file mode 100644 index 000000000000..7797c3123b7e --- /dev/null +++ b/Documentation/devicetree/bindings/spi/hpe,gxp-spifi.yaml @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/hpe,gxp-spifi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: HPE GXP spi controller flash interface + +maintainers: + - Nick Hawkins <nick.hawkins@hpe.com> + - Jean-Marie Verdun <verdun@hpe.com> + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + const: hpe,gxp-spifi + + reg: + items: + - description: cfg registers + - description: data registers + - description: mapped memory + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +unevaluatedProperties: false + +examples: + - | + + spi@200 { + compatible = "hpe,gxp-spifi"; + reg = <0x200 0x80>, <0xc000 0x100>, <0x38000000 0x800000>; + interrupts = <20>; + interrupt-parent = <&vic0>; + #address-cells = <1>; + #size-cells = <0>; + + flash@0 { + reg = <0>; + compatible = "jedec,spi-nor"; + }; + + flash@1 { + reg = <1>; + compatible = "jedec,spi-nor"; + }; + }; diff --git a/Documentation/devicetree/bindings/spi/mediatek,spi-mt65xx.yaml b/Documentation/devicetree/bindings/spi/mediatek,spi-mt65xx.yaml index 94ef0552bd42..8d2a6c084eab 100644 --- a/Documentation/devicetree/bindings/spi/mediatek,spi-mt65xx.yaml +++ b/Documentation/devicetree/bindings/spi/mediatek,spi-mt65xx.yaml @@ -18,6 +18,7 @@ properties: - items: - enum: - mediatek,mt7629-spi + - mediatek,mt8365-spi - const: mediatek,mt7622-spi - items: - enum: @@ -33,6 +34,7 @@ properties: - items: - enum: - mediatek,mt7986-spi-ipm + - mediatek,mt8188-spi-ipm - const: mediatek,spi-ipm - items: - enum: diff --git a/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml b/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml index 41e60fe4b09f..970b1119898b 100644 --- a/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml +++ b/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml @@ -23,6 +23,10 @@ allOf: properties: compatible: oneOf: + - enum: + - mediatek,mt8173-nor + - mediatek,mt8186-nor + - mediatek,mt8192-nor - items: - enum: - mediatek,mt2701-nor @@ -30,13 +34,13 @@ properties: - mediatek,mt7622-nor - mediatek,mt7623-nor - mediatek,mt7629-nor - - mediatek,mt8186-nor - - mediatek,mt8192-nor - mediatek,mt8195-nor - - enum: - - mediatek,mt8173-nor - - items: - const: mediatek,mt8173-nor + - items: + - enum: + - mediatek,mt8188-nor + - const: mediatek,mt8186-nor + reg: maxItems: 1 @@ -64,7 +68,6 @@ properties: required: - compatible - reg - - interrupts - clocks - clock-names diff --git a/Documentation/devicetree/bindings/spi/microchip,mpfs-spi.yaml b/Documentation/devicetree/bindings/spi/microchip,mpfs-spi.yaml index ece261b8e963..7326c0a28d16 100644 --- a/Documentation/devicetree/bindings/spi/microchip,mpfs-spi.yaml +++ b/Documentation/devicetree/bindings/spi/microchip,mpfs-spi.yaml @@ -47,6 +47,5 @@ examples: clocks = <&clkcfg CLK_SPI0>; interrupt-parent = <&plic>; interrupts = <54>; - spi-max-frequency = <25000000>; }; ... diff --git a/Documentation/devicetree/bindings/spi/nuvoton,npcm-fiu.txt b/Documentation/devicetree/bindings/spi/nuvoton,npcm-fiu.txt index a388005842ad..c63ce4cc0a80 100644 --- a/Documentation/devicetree/bindings/spi/nuvoton,npcm-fiu.txt +++ b/Documentation/devicetree/bindings/spi/nuvoton,npcm-fiu.txt @@ -6,8 +6,13 @@ The NPCM7XX supports three FIU modules, FIU0 and FIUx supports two chip selects, FIU3 support four chip select. +The NPCM8XX supports four FIU modules, +FIU0 and FIUx supports two chip selects, +FIU1 and FIU3 supports four chip selects. + Required properties: - - compatible : "nuvoton,npcm750-fiu" for the NPCM7XX BMC + - compatible : "nuvoton,npcm750-fiu" for Poleg NPCM7XX BMC + "nuvoton,npcm845-fiu" for Arbel NPCM8XX BMC - #address-cells : should be 1. - #size-cells : should be 0. - reg : the first contains the register location and length, @@ -30,6 +35,12 @@ Aliases: fiu1 represent fiu 3 controller fiu2 represent fiu x controller + In the NPCM8XX BMC: + fiu0 represent fiu 0 controller + fiu1 represent fiu 1 controller + fiu2 represent fiu 3 controller + fiu3 represent fiu x controller + Example: fiu3: spi@c00000000 { compatible = "nuvoton,npcm750-fiu"; diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad-peripheral-props.yaml new file mode 100644 index 000000000000..24e0c2181d25 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad-peripheral-props.yaml @@ -0,0 +1,33 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/nvidia,tegra210-quad-peripheral-props.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Peripheral properties for Tegra Quad SPI Controller + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jonathan Hunter <jonathanh@nvidia.com> + +properties: + nvidia,tx-clk-tap-delay: + description: + Delays the clock going out to device with this tap value. + Tap value varies based on platform design trace lengths from Tegra + QSPI to corresponding slave device. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 31 + + nvidia,rx-clk-tap-delay: + description: + Delays the clock coming in from the device with this tap value. + Tap value varies based on platform design trace lengths from Tegra + QSPI to corresponding slave device. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 255 + +unevaluatedProperties: true + diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml b/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml index 0296edd1de22..6b733e5c1163 100644 --- a/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml +++ b/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml @@ -20,6 +20,7 @@ properties: - nvidia,tegra186-qspi - nvidia,tegra194-qspi - nvidia,tegra234-qspi + - nvidia,tegra241-qspi reg: maxItems: 1 @@ -57,27 +58,6 @@ patternProperties: spi-tx-bus-width: enum: [1, 2, 4] - nvidia,tx-clk-tap-delay: - description: - Delays the clock going out to device with this tap value. - Tap value varies based on platform design trace lengths from Tegra - QSPI to corresponding slave device. - $ref: /schemas/types.yaml#/definitions/uint32 - minimum: 0 - maximum: 31 - - nvidia,rx-clk-tap-delay: - description: - Delays the clock coming in from the device with this tap value. - Tap value varies based on platform design trace lengths from Tegra - QSPI to corresponding slave device. - $ref: /schemas/types.yaml#/definitions/uint32 - minimum: 0 - maximum: 255 - - required: - - reg - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/spi/qcom,spi-geni-qcom.yaml b/Documentation/devicetree/bindings/spi/qcom,spi-geni-qcom.yaml index e2c7b934c50d..2e20ca313ec1 100644 --- a/Documentation/devicetree/bindings/spi/qcom,spi-geni-qcom.yaml +++ b/Documentation/devicetree/bindings/spi/qcom,spi-geni-qcom.yaml @@ -45,12 +45,15 @@ properties: - const: rx interconnects: - maxItems: 2 + minItems: 2 + maxItems: 3 interconnect-names: + minItems: 2 items: - const: qup-core - const: qup-config + - const: qup-memory interrupts: maxItems: 1 @@ -110,7 +113,6 @@ examples: pinctrl-names = "default"; pinctrl-0 = <&qup_spi1_default>; interrupts = <GIC_SPI 602 IRQ_TYPE_LEVEL_HIGH>; - spi-max-frequency = <50000000>; #address-cells = <1>; #size-cells = <0>; }; diff --git a/Documentation/devicetree/bindings/spi/samsung,spi.yaml b/Documentation/devicetree/bindings/spi/samsung,spi.yaml index a50f24f9359d..e0a465d70b0a 100644 --- a/Documentation/devicetree/bindings/spi/samsung,spi.yaml +++ b/Documentation/devicetree/bindings/spi/samsung,spi.yaml @@ -20,7 +20,9 @@ properties: - samsung,s3c2443-spi # for S3C2443, S3C2416 and S3C2450 - samsung,s3c6410-spi - samsung,s5pv210-spi # for S5PV210 and S5PC110 + - samsung,exynos4210-spi - samsung,exynos5433-spi + - samsung,exynosautov9-spi - tesla,fsd-spi - const: samsung,exynos7-spi deprecated: true @@ -85,7 +87,9 @@ allOf: properties: compatible: contains: - const: samsung,exynos5433-spi + enum: + - samsung,exynos5433-spi + - samsung,exynosautov9-spi then: properties: clocks: diff --git a/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml b/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml index d7e08b03e204..37c3c272407d 100644 --- a/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml +++ b/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml @@ -61,6 +61,8 @@ properties: - const: snps,dw-apb-ssi - description: Intel Keem Bay SPI Controller const: intel,keembay-ssi + - description: Intel Thunder Bay SPI Controller + const: intel,thunderbay-ssi - description: Baikal-T1 SPI Controller const: baikal,bt1-ssi - description: Baikal-T1 System Boot SPI Controller @@ -124,9 +126,16 @@ properties: rx-sample-delay-ns: default: 0 - description: Default value of the rx-sample-delay-ns property. + description: | + Default value of the rx-sample-delay-ns property. This value will be used if the property is not explicitly defined - for a SPI slave device. See below. + for a SPI slave device. + + SPI Rx sample delay offset, unit is nanoseconds. + The delay from the default sample time before the actual sample of the + rxd input signal occurs. The "rx_sample_delay" is an optional feature + of the designware controller, and the upper limit is also subject to + controller configuration. patternProperties: "^.*@[0-9a-f]+$": @@ -136,19 +145,6 @@ patternProperties: minimum: 0 maximum: 3 - spi-rx-bus-width: - const: 1 - - spi-tx-bus-width: - const: 1 - - rx-sample-delay-ns: - description: SPI Rx sample delay offset, unit is nanoseconds. - The delay from the default sample time before the actual - sample of the rxd input signal occurs. The "rx_sample_delay" - is an optional feature of the designware controller, and the - upper limit is also subject to controller configuration. - unevaluatedProperties: false required: diff --git a/Documentation/devicetree/bindings/spi/spi-cadence.yaml b/Documentation/devicetree/bindings/spi/spi-cadence.yaml index 9787be21318e..82d0ca5c00f3 100644 --- a/Documentation/devicetree/bindings/spi/spi-cadence.yaml +++ b/Documentation/devicetree/bindings/spi/spi-cadence.yaml @@ -49,6 +49,13 @@ properties: enum: [ 0, 1 ] default: 0 +required: + - compatible + - reg + - interrupts + - clock-names + - clocks + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/spi/spi-controller.yaml b/Documentation/devicetree/bindings/spi/spi-controller.yaml index ebb4d5f1cf4f..655713fba7e2 100644 --- a/Documentation/devicetree/bindings/spi/spi-controller.yaml +++ b/Documentation/devicetree/bindings/spi/spi-controller.yaml @@ -95,6 +95,17 @@ patternProperties: type: object $ref: spi-peripheral-props.yaml + properties: + spi-cpha: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires shifted clock phase (CPHA) mode. + + spi-cpol: + $ref: /schemas/types.yaml#/definitions/flag + description: + The device requires inverse clock polarity (CPOL) mode. + required: - compatible - reg @@ -139,9 +150,9 @@ examples: }; flash@2 { - compatible = "jedec,spi-nor"; - spi-max-frequency = <50000000>; - reg = <2>, <3>; - stacked-memories = /bits/ 64 <0x10000000 0x10000000>; + compatible = "jedec,spi-nor"; + spi-max-frequency = <50000000>; + reg = <2>, <3>; + stacked-memories = /bits/ 64 <0x10000000 0x10000000>; }; }; diff --git a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml index 5e32928c4fc3..ce048e782e80 100644 --- a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml +++ b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml @@ -34,16 +34,6 @@ properties: description: The device requires 3-wire mode. - spi-cpha: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires shifted clock phase (CPHA) mode. - - spi-cpol: - $ref: /schemas/types.yaml#/definitions/flag - description: - The device requires inverse clock polarity (CPOL) mode. - spi-cs-high: $ref: /schemas/types.yaml#/definitions/flag description: @@ -71,6 +61,11 @@ properties: description: Delay, in microseconds, after a read transfer. + rx-sample-delay-ns: + description: SPI Rx sample delay offset, unit is nanoseconds. + The delay from the default sample time before the actual + sample of the rxd input signal occurs. + spi-tx-bus-width: description: Bus width to the SPI bus used for write transfers. @@ -112,5 +107,6 @@ properties: allOf: - $ref: cdns,qspi-nor-peripheral-props.yaml# - $ref: samsung,spi-peripheral-props.yaml# + - $ref: nvidia,tegra210-quad-peripheral-props.yaml# additionalProperties: true diff --git a/Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml b/Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml index ea72c8001256..fafde1c06be6 100644 --- a/Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml +++ b/Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml @@ -30,6 +30,13 @@ properties: clocks: maxItems: 2 +required: + - compatible + - reg + - interrupts + - clock-names + - clocks + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/spi/spi_atmel.txt b/Documentation/devicetree/bindings/spi/spi_atmel.txt deleted file mode 100644 index 5bb4a8f1df7a..000000000000 --- a/Documentation/devicetree/bindings/spi/spi_atmel.txt +++ /dev/null @@ -1,36 +0,0 @@ -Atmel SPI device - -Required properties: -- compatible : should be "atmel,at91rm9200-spi" or "microchip,sam9x60-spi". -- reg: Address and length of the register set for the device -- interrupts: Should contain spi interrupt -- cs-gpios: chipselects (optional for SPI controller version >= 2 with the - Chip Select Active After Transfer feature). -- clock-names: tuple listing input clock names. - Required elements: "spi_clk" -- clocks: phandles to input clocks. - -Optional properties: -- atmel,fifo-size: maximum number of data the RX and TX FIFOs can store for FIFO - capable SPI controllers. - -Example: - -spi1: spi@fffcc000 { - compatible = "atmel,at91rm9200-spi"; - reg = <0xfffcc000 0x4000>; - interrupts = <13 4 5>; - #address-cells = <1>; - #size-cells = <0>; - clocks = <&spi1_clk>; - clock-names = "spi_clk"; - cs-gpios = <&pioB 3 0>; - atmel,fifo-size = <32>; - - mmc-slot@0 { - compatible = "mmc-spi-slot"; - reg = <0>; - gpios = <&pioC 4 0>; /* CD */ - spi-max-frequency = <25000000>; - }; -}; diff --git a/Documentation/devicetree/bindings/thermal/fsl,scu-thermal.yaml b/Documentation/devicetree/bindings/thermal/fsl,scu-thermal.yaml new file mode 100644 index 000000000000..f9e4b3c8d0ee --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/fsl,scu-thermal.yaml @@ -0,0 +1,38 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/fsl,scu-thermal.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: i.MX SCU Client Device Node - Thermal bindings based on SCU Message Protocol + +maintainers: + - Dong Aisheng <aisheng.dong@nxp.com> + +description: i.MX SCU Client Device Node + Client nodes are maintained as children of the relevant IMX-SCU device node. + +allOf: + - $ref: thermal-sensor.yaml# + +properties: + compatible: + items: + - const: fsl,imx8qxp-sc-thermal + - const: fsl,imx-sc-thermal + + '#thermal-sensor-cells': + const: 1 + +required: + - compatible + - '#thermal-sensor-cells' + +additionalProperties: false + +examples: + - | + thermal-sensor { + compatible = "fsl,imx8qxp-sc-thermal", "fsl,imx-sc-thermal"; + #thermal-sensor-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/thermal/qcom,spmi-temp-alarm.yaml b/Documentation/devicetree/bindings/thermal/qcom,spmi-temp-alarm.yaml new file mode 100644 index 000000000000..5f08b6e59b8a --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/qcom,spmi-temp-alarm.yaml @@ -0,0 +1,85 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/qcom,spmi-temp-alarm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm QPNP PMIC Temperature Alarm + +maintainers: + - Bjorn Andersson <bjorn.andersson@linaro.org> + +description: + QPNP temperature alarm peripherals are found inside of Qualcomm PMIC chips + that utilize the Qualcomm SPMI implementation. These peripherals provide an + interrupt signal and status register to identify high PMIC die temperature. + +allOf: + - $ref: thermal-sensor.yaml# + +properties: + compatible: + const: qcom,spmi-temp-alarm + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + io-channels: + items: + - description: ADC channel, which reports chip die temperature + + io-channel-names: + items: + - const: thermal + + '#thermal-sensor-cells': + const: 0 + +required: + - compatible + - reg + - interrupts + - '#thermal-sensor-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + pmic { + #address-cells = <1>; + #size-cells = <0>; + + pm8350_temp_alarm: temperature-sensor@a00 { + compatible = "qcom,spmi-temp-alarm"; + reg = <0xa00>; + interrupts = <0x1 0xa 0x0 IRQ_TYPE_EDGE_BOTH>; + #thermal-sensor-cells = <0>; + }; + }; + + thermal-zones { + pm8350_thermal: pm8350c-thermal { + polling-delay-passive = <100>; + polling-delay = <0>; + thermal-sensors = <&pm8350_temp_alarm>; + + trips { + pm8350_trip0: trip0 { + temperature = <95000>; + hysteresis = <0>; + type = "passive"; + }; + + pm8350_crit: pm8350c-crit { + temperature = <115000>; + hysteresis = <0>; + type = "critical"; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/thermal/qcom-spmi-temp-alarm.txt b/Documentation/devicetree/bindings/thermal/qcom-spmi-temp-alarm.txt deleted file mode 100644 index 2d5b2ad03314..000000000000 --- a/Documentation/devicetree/bindings/thermal/qcom-spmi-temp-alarm.txt +++ /dev/null @@ -1,51 +0,0 @@ -Qualcomm QPNP PMIC Temperature Alarm - -QPNP temperature alarm peripherals are found inside of Qualcomm PMIC chips -that utilize the Qualcomm SPMI implementation. These peripherals provide an -interrupt signal and status register to identify high PMIC die temperature. - -Required properties: -- compatible: Should contain "qcom,spmi-temp-alarm". -- reg: Specifies the SPMI address. -- interrupts: PMIC temperature alarm interrupt. -- #thermal-sensor-cells: Should be 0. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for a description. - -Optional properties: -- io-channels: Should contain IIO channel specifier for the ADC channel, - which report chip die temperature. -- io-channel-names: Should contain "thermal". - -Example: - - pm8941_temp: thermal-alarm@2400 { - compatible = "qcom,spmi-temp-alarm"; - reg = <0x2400>; - interrupts = <0 0x24 0 IRQ_TYPE_EDGE_RISING>; - #thermal-sensor-cells = <0>; - - io-channels = <&pm8941_vadc VADC_DIE_TEMP>; - io-channel-names = "thermal"; - }; - - thermal-zones { - pm8941 { - polling-delay-passive = <250>; - polling-delay = <1000>; - - thermal-sensors = <&pm8941_temp>; - - trips { - stage1 { - temperature = <105000>; - hysteresis = <2000>; - type = "passive"; - }; - stage2 { - temperature = <125000>; - hysteresis = <2000>; - type = "critical"; - }; - }; - }; - }; - diff --git a/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml b/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml index 1368d90da0e8..0f05f5c886c5 100644 --- a/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml @@ -8,9 +8,9 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Renesas R-Car Gen3 Thermal Sensor description: - On R-Car Gen3 SoCs, the thermal sensor controllers (TSC) control the thermal - sensors (THS) which are the analog circuits for measuring temperature (Tj) - inside the LSI. + On most R-Car Gen3 and later SoCs, the thermal sensor controllers (TSC) + control the thermal sensors (THS) which are the analog circuits for + measuring temperature (Tj) inside the LSI. maintainers: - Niklas Söderlund <niklas.soderlund@ragnatech.se> @@ -27,6 +27,7 @@ properties: - renesas,r8a77965-thermal # R-Car M3-N - renesas,r8a77980-thermal # R-Car V3H - renesas,r8a779a0-thermal # R-Car V3U + - renesas,r8a779f0-thermal # R-Car S4-8 reg: true @@ -57,31 +58,38 @@ required: - "#thermal-sensor-cells" if: - not: - properties: - compatible: - contains: - enum: - - renesas,r8a779a0-thermal + properties: + compatible: + contains: + enum: + - renesas,r8a779a0-thermal then: properties: reg: - minItems: 2 items: + - description: TSC0 registers - description: TSC1 registers - description: TSC2 registers - description: TSC3 registers - required: - - interrupts + - description: TSC4 registers else: properties: reg: + minItems: 2 items: - - description: TSC0 registers - description: TSC1 registers - description: TSC2 registers - description: TSC3 registers - - description: TSC4 registers + if: + not: + properties: + compatible: + contains: + enum: + - renesas,r8a779f0-thermal + then: + required: + - interrupts additionalProperties: false diff --git a/Documentation/devicetree/bindings/timer/allwinner,sun4i-a10-timer.yaml b/Documentation/devicetree/bindings/timer/allwinner,sun4i-a10-timer.yaml index 53fd24bdc34e..3711872b6b99 100644 --- a/Documentation/devicetree/bindings/timer/allwinner,sun4i-a10-timer.yaml +++ b/Documentation/devicetree/bindings/timer/allwinner,sun4i-a10-timer.yaml @@ -20,6 +20,7 @@ properties: - allwinner,suniv-f1c100s-timer - items: - enum: + - allwinner,sun20i-d1-timer - allwinner,sun50i-a64-timer - allwinner,sun50i-h6-timer - allwinner,sun50i-h616-timer diff --git a/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml b/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml index d541cf2067bc..0a01e4f5eddb 100644 --- a/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml +++ b/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml @@ -113,7 +113,7 @@ properties: patternProperties: "^watchdog@[a-f0-9]+$": type: object - $ref: ../watchdog/watchdog.yaml# + $ref: /schemas/watchdog/watchdog.yaml# properties: compatible: oneOf: @@ -145,7 +145,7 @@ patternProperties: "^pwm@[a-f0-9]+$": type: object - $ref: ../pwm/pwm.yaml# + $ref: /schemas/pwm/pwm.yaml# properties: compatible: oneOf: diff --git a/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt b/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt index 6f1f9dba6e88..f1c848af91d3 100644 --- a/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt +++ b/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt @@ -1,7 +1,8 @@ MediaTek Timers --------------- -MediaTek SoCs have two different timers on different platforms, +MediaTek SoCs have different timers on different platforms, +- CPUX (ARM/ARM64 System Timer) - GPT (General Purpose Timer) - SYST (System Timer) @@ -29,6 +30,9 @@ Required properties: * "mediatek,mt7629-timer" for MT7629 compatible timers (SYST) * "mediatek,mt6765-timer" for MT6765 and all above compatible timers (SYST) + For those SoCs that use CPUX + * "mediatek,mt6795-systimer" for MT6795 compatible timers (CPUX) + - reg: Should contain location and length for timer register. - clocks: Should contain system clock. diff --git a/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.yaml b/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.yaml index 0cbc26a72151..737af78ad70c 100644 --- a/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.yaml +++ b/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.yaml @@ -8,12 +8,14 @@ title: Nuvoton NPCM7xx timer maintainers: - Jonathan Neuschäfer <j.neuschaefer@gmx.net> + - Tomer Maimon <tmaimon77@gmail.com> properties: compatible: enum: - nuvoton,wpcm450-timer # for Hermon WPCM450 - nuvoton,npcm750-timer # for Poleg NPCM750 + - nuvoton,npcm845-timer # for Arbel NPCM845 reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/timer/nvidia,tegra186-timer.yaml b/Documentation/devicetree/bindings/timer/nvidia,tegra186-timer.yaml new file mode 100644 index 000000000000..db8b5595540f --- /dev/null +++ b/Documentation/devicetree/bindings/timer/nvidia,tegra186-timer.yaml @@ -0,0 +1,109 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/timer/nvidia,tegra186-timer.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: NVIDIA Tegra186 timer + +maintainers: + - Thierry Reding <treding@nvidia.com> + +description: > + The Tegra timer provides 29-bit timer counters and a 32-bit timestamp + counter. Each NV timer selects its timing reference signal from the 1 MHz + reference generated by USEC, TSC or either clk_m or OSC. Each TMR can be + programmed to generate one-shot, periodic, or watchdog interrupts. + + +properties: + compatible: + oneOf: + - const: nvidia,tegra186-timer + description: > + The Tegra186 timer provides ten 29-bit timer counters. + - const: nvidia,tegra234-timer + description: > + The Tegra234 timer provides sixteen 29-bit timer counters. + + reg: + maxItems: 1 + + interrupts: true + +allOf: + - if: + properties: + compatible: + contains: + const: nvidia,tegra186-timer + then: + properties: + interrupts: + maxItems: 10 + description: > + One per each timer channels 0 through 9. + + - if: + properties: + compatible: + contains: + const: nvidia,tegra234-timer + then: + properties: + interrupts: + maxItems: 16 + description: > + One per each timer channels 0 through 15. + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + timer@3010000 { + compatible = "nvidia,tegra186-timer"; + reg = <0x03010000 0x000e0000>; + interrupts = <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>; + }; + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + timer@2080000 { + compatible = "nvidia,tegra234-timer"; + reg = <0x02080000 0x00121000>; + interrupts = <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 10 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 13 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 14 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 15 IRQ_TYPE_LEVEL_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/timer/renesas,cmt.yaml b/Documentation/devicetree/bindings/timer/renesas,cmt.yaml index 53dd6d9f518f..bde6c9b66bf4 100644 --- a/Documentation/devicetree/bindings/timer/renesas,cmt.yaml +++ b/Documentation/devicetree/bindings/timer/renesas,cmt.yaml @@ -80,7 +80,6 @@ properties: - renesas,r8a77980-cmt0 # 32-bit CMT0 on R-Car V3H - renesas,r8a77990-cmt0 # 32-bit CMT0 on R-Car E3 - renesas,r8a77995-cmt0 # 32-bit CMT0 on R-Car D3 - - renesas,r8a779a0-cmt0 # 32-bit CMT0 on R-Car V3U - const: renesas,rcar-gen3-cmt0 # 32-bit CMT0 on R-Car Gen3 and RZ/G2 - items: @@ -97,9 +96,20 @@ properties: - renesas,r8a77980-cmt1 # 48-bit CMT on R-Car V3H - renesas,r8a77990-cmt1 # 48-bit CMT on R-Car E3 - renesas,r8a77995-cmt1 # 48-bit CMT on R-Car D3 - - renesas,r8a779a0-cmt1 # 48-bit CMT on R-Car V3U - const: renesas,rcar-gen3-cmt1 # 48-bit CMT on R-Car Gen3 and RZ/G2 + - items: + - enum: + - renesas,r8a779a0-cmt0 # 32-bit CMT0 on R-Car V3U + - renesas,r8a779f0-cmt0 # 32-bit CMT0 on R-Car S4-8 + - const: renesas,rcar-gen4-cmt0 # 32-bit CMT0 on R-Car Gen4 + + - items: + - enum: + - renesas,r8a779a0-cmt1 # 48-bit CMT on R-Car V3U + - renesas,r8a779f0-cmt1 # 48-bit CMT on R-Car S4-8 + - const: renesas,rcar-gen4-cmt1 # 48-bit CMT on R-Car Gen4 + reg: maxItems: 1 @@ -135,6 +145,7 @@ allOf: enum: - renesas,rcar-gen2-cmt0 - renesas,rcar-gen3-cmt0 + - renesas,rcar-gen4-cmt0 then: properties: interrupts: @@ -148,6 +159,7 @@ allOf: enum: - renesas,rcar-gen2-cmt1 - renesas,rcar-gen3-cmt1 + - renesas,rcar-gen4-cmt1 then: properties: interrupts: diff --git a/Documentation/devicetree/bindings/timer/st,nomadik-mtu.yaml b/Documentation/devicetree/bindings/timer/st,nomadik-mtu.yaml new file mode 100644 index 000000000000..901848d298ec --- /dev/null +++ b/Documentation/devicetree/bindings/timer/st,nomadik-mtu.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2022 Linaro Ltd. +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/timer/st,nomadik-mtu.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: ST Microelectronics Nomadik Multi-Timer Unit MTU Timer + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +description: This timer is found in the ST Microelectronics Nomadik + SoCs STn8800, STn8810 and STn8815 as well as in ST-Ericsson DB8500. + +properties: + compatible: + items: + - const: st,nomadik-mtu + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + description: The first clock named TIMCLK clocks the actual timers and + the second clock clocks the digital interface to the interconnect. + maxItems: 2 + + clock-names: + items: + - const: timclk + - const: apb_pclk + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/mfd/dbx500-prcmu.h> + timer@a03c6000 { + compatible = "st,nomadik-mtu"; + reg = <0xa03c6000 0x1000>; + interrupts = <GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>; + + clocks = <&prcmu_clk PRCMU_TIMCLK>, <&prcc_pclk 6 6>; + clock-names = "timclk", "apb_pclk"; + }; diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index 6aafa71806a3..5d87b8426ff4 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -41,6 +41,8 @@ properties: - adi,adp5585-02 # Analog Devices ADP5589 Keypad Decoder and I/O Expansion - adi,adp5589 + # Analog Devices LT7182S Dual Channel 6A, 20V PolyPhase Step-Down Silent Switcher + - adi,lt7182s # AMS iAQ-Core VOC Sensor - ams,iaq-core # i2c serial eeprom (24cxx) diff --git a/Documentation/devicetree/bindings/usb/allwinner,sun4i-a10-musb.yaml b/Documentation/devicetree/bindings/usb/allwinner,sun4i-a10-musb.yaml index 933fa356d2ce..e5dbf4169bc9 100644 --- a/Documentation/devicetree/bindings/usb/allwinner,sun4i-a10-musb.yaml +++ b/Documentation/devicetree/bindings/usb/allwinner,sun4i-a10-musb.yaml @@ -20,6 +20,7 @@ properties: - items: - enum: - allwinner,sun8i-a83t-musb + - allwinner,sun20i-d1-musb - allwinner,sun50i-h6-musb - const: allwinner,sun8i-a33-musb - items: diff --git a/Documentation/devicetree/bindings/usb/atmel-usb.txt b/Documentation/devicetree/bindings/usb/atmel-usb.txt index f512f0290728..12183ef47ee4 100644 --- a/Documentation/devicetree/bindings/usb/atmel-usb.txt +++ b/Documentation/devicetree/bindings/usb/atmel-usb.txt @@ -87,6 +87,9 @@ Required properties: "atmel,at91sam9g45-udc" "atmel,sama5d3-udc" "microchip,sam9x60-udc" + "microchip,lan9662-udc" + For "microchip,lan9662-udc" the fallback "atmel,sama5d3-udc" + is required. - reg: Address and length of the register set for the device - interrupts: Should contain usba interrupt - clocks: Should reference the peripheral and host clocks diff --git a/Documentation/devicetree/bindings/usb/generic-ehci.yaml b/Documentation/devicetree/bindings/usb/generic-ehci.yaml index 0b4524b6409e..25a6c14618e1 100644 --- a/Documentation/devicetree/bindings/usb/generic-ehci.yaml +++ b/Documentation/devicetree/bindings/usb/generic-ehci.yaml @@ -38,6 +38,7 @@ properties: - allwinner,sun8i-h3-ehci - allwinner,sun8i-r40-ehci - allwinner,sun9i-a80-ehci + - allwinner,sun20i-d1-ehci - aspeed,ast2400-ehci - aspeed,ast2500-ehci - aspeed,ast2600-ehci @@ -136,7 +137,8 @@ properties: Phandle of a companion. phys: - maxItems: 1 + minItems: 1 + maxItems: 3 phy-names: const: usb diff --git a/Documentation/devicetree/bindings/usb/generic-ohci.yaml b/Documentation/devicetree/bindings/usb/generic-ohci.yaml index e2ac84665316..180361b79f52 100644 --- a/Documentation/devicetree/bindings/usb/generic-ohci.yaml +++ b/Documentation/devicetree/bindings/usb/generic-ohci.yaml @@ -28,6 +28,7 @@ properties: - allwinner,sun8i-h3-ohci - allwinner,sun8i-r40-ohci - allwinner,sun9i-a80-ohci + - allwinner,sun20i-d1-ohci - brcm,bcm3384-ohci - brcm,bcm63268-ohci - brcm,bcm6328-ohci @@ -103,7 +104,8 @@ properties: Overrides the detected port count phys: - maxItems: 1 + minItems: 1 + maxItems: 3 phy-names: const: usb diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 0496773a3c4d..ff0ac853cb82 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -510,6 +510,8 @@ patternProperties: description: Haoyu Microelectronic Co. Ltd. "^hardkernel,.*": description: Hardkernel Co., Ltd + "^hechuang,.*": + description: Shenzhen Hechuang Intelligent Co. "^hideep,.*": description: HiDeep Inc. "^himax,.*": @@ -1101,6 +1103,8 @@ patternProperties: description: SGX Sensortech "^sharp,.*": description: Sharp Corporation + "^shift,.*": + description: SHIFT GmbH "^shimafuji,.*": description: Shimafuji Electric, Inc. "^shiratech,.*": diff --git a/Documentation/devicetree/bindings/watchdog/fsl,scu-wdt.yaml b/Documentation/devicetree/bindings/watchdog/fsl,scu-wdt.yaml new file mode 100644 index 000000000000..f84c45d687d7 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/fsl,scu-wdt.yaml @@ -0,0 +1,34 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/watchdog/fsl,scu-wdt.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: i.MX SCU Client Device Node - Watchdog bindings based on SCU Message Protocol + +maintainers: + - Dong Aisheng <aisheng.dong@nxp.com> + +description: i.MX SCU Client Device Node + Client nodes are maintained as children of the relevant IMX-SCU device node. + +allOf: + - $ref: watchdog.yaml# + +properties: + compatible: + items: + - const: fsl,imx8qxp-sc-wdt + - const: fsl,imx-sc-wdt + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + watchdog { + compatible = "fsl,imx8qxp-sc-wdt", "fsl,imx-sc-wdt"; + timeout-sec = <60>; + }; diff --git a/Documentation/devicetree/bindings/watchdog/nuvoton,npcm-wdt.txt b/Documentation/devicetree/bindings/watchdog/nuvoton,npcm-wdt.txt index 9059f54dc023..866a958b8a2b 100644 --- a/Documentation/devicetree/bindings/watchdog/nuvoton,npcm-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/nuvoton,npcm-wdt.txt @@ -6,7 +6,8 @@ expiry. Required properties: - compatible : "nuvoton,npcm750-wdt" for NPCM750 (Poleg), or - "nuvoton,wpcm450-wdt" for WPCM450 (Hermon). + "nuvoton,wpcm450-wdt" for WPCM450 (Hermon), or + "nuvoton,npcm845-wdt" for NPCM845 (Arbel). - reg : Offset and length of the register set for the device. - interrupts : Contain the timer interrupt with flags for falling edge. diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index a7cb2afd7990..9c779bd7a751 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -1,3 +1,5 @@ +.. title:: Kernel-doc comments + =========================== Writing kernel-doc comments =========================== diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index 2ff1ab4158d4..1228b85f6f77 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -132,7 +132,8 @@ format-specific subdirectories under ``Documentation/output``. To generate documentation, Sphinx (``sphinx-build``) must obviously be installed. For prettier HTML output, the Read the Docs Sphinx theme (``sphinx_rtd_theme``) is used if available. For PDF output you'll also need -``XeLaTeX`` and ``convert(1)`` from ImageMagick (https://www.imagemagick.org). +``XeLaTeX`` and ``convert(1)`` from ImageMagick +(https://www.imagemagick.org).\ [#ink]_ All of these are widely available and packaged in distributions. To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make @@ -150,8 +151,19 @@ If the theme is not available, it will fall-back to the classic one. The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable. +There is another make variable ``SPHINXDIRS``, which is useful when test +building a subset of documentation. For example, you can build documents +under ``Documentation/doc-guide`` by running +``make SPHINXDIRS=doc-guide htmldocs``. +The documentation section of ``make help`` will show you the list of +subdirectories you can specify. + To remove the generated documentation, run ``make cleandocs``. +.. [#ink] Having ``inkscape(1)`` from Inkscape (https://inkscape.org) + as well would improve the quality of images embedded in PDF + documents, especially for kernel releases 5.18 and later. + Writing Documentation ===================== diff --git a/Documentation/driver-api/firmware/other_interfaces.rst b/Documentation/driver-api/firmware/other_interfaces.rst index b81794e0cfbb..06ac89adaafb 100644 --- a/Documentation/driver-api/firmware/other_interfaces.rst +++ b/Documentation/driver-api/firmware/other_interfaces.rst @@ -13,6 +13,12 @@ EDD Interfaces .. kernel-doc:: drivers/firmware/edd.c :internal: +Generic System Framebuffers Interface +------------------------------------- + +.. kernel-doc:: drivers/firmware/sysfb.c + :export: + Intel Stratix10 SoC Service Layer --------------------------------- Some features of the Intel Stratix10 SoC require a level of privilege diff --git a/Documentation/driver-api/gpio/board.rst b/Documentation/driver-api/gpio/board.rst index 4e3adf31c8d1..b33aa04f213f 100644 --- a/Documentation/driver-api/gpio/board.rst +++ b/Documentation/driver-api/gpio/board.rst @@ -6,7 +6,7 @@ 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 -gpio-legacy.txt (actually, there is no real mapping possible with the old +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). diff --git a/Documentation/driver-api/gpio/consumer.rst b/Documentation/driver-api/gpio/consumer.rst index 47869ca8ccf0..de6fc79ad6f0 100644 --- a/Documentation/driver-api/gpio/consumer.rst +++ b/Documentation/driver-api/gpio/consumer.rst @@ -4,7 +4,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 gpio-legacy.txt. +deprecated integer-based GPIO interface please refer to legacy.rst. Guidelines for GPIOs consumers @@ -78,7 +78,7 @@ whether the line is configured active high or active low (see The two last flags are used for use cases where open drain is mandatory, such as I2C: if the line is not already configured as open drain in the mappings -(see board.txt), then open drain will be enforced anyway and a warning will be +(see board.rst), then open drain will be enforced anyway and a warning will be printed that the board configuration needs to be updated to match the use case. Both functions return either a valid GPIO descriptor, or an error code checkable @@ -114,7 +114,7 @@ For a function using multiple GPIOs all of those can be obtained with one call:: This function returns a struct gpio_descs which contains an array of descriptors. It also contains a pointer to a gpiolib private structure which, -if passed back to get/set array functions, may speed up I/O proocessing:: +if passed back to get/set array functions, may speed up I/O processing:: struct gpio_descs { struct gpio_array *info; @@ -270,7 +270,7 @@ driven. The same is applicable for open drain or open source output lines: those do not actively drive their output high (open drain) or low (open source), they just switch their output to a high impedance value. The consumer should not need to -care. (For details read about open drain in driver.txt.) +care. (For details read about open drain in driver.rst.) With this, all the gpiod_set_(array)_value_xxx() functions interpret the parameter "value" as "asserted" ("1") or "de-asserted" ("0"). The physical line diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst index 70ff43ac4fcc..6baaeab79534 100644 --- a/Documentation/driver-api/gpio/driver.rst +++ b/Documentation/driver-api/gpio/driver.rst @@ -119,7 +119,7 @@ GPIO lines with debounce support Debouncing is a configuration set to a pin indicating that it is connected to a mechanical switch or button, or similar that may bounce. Bouncing means the line is pulled high/low quickly at very short intervals for mechanical -reasons. This can result in the value being unstable or irqs fireing repeatedly +reasons. This can result in the value being unstable or irqs firing repeatedly unless the line is debounced. Debouncing in practice involves setting up a timer when something happens on @@ -219,7 +219,7 @@ use a trick: when a line is set as output, if the line is flagged as open drain, and the IN output value is low, it will be driven low as usual. But if the IN output value is set to high, it will instead *NOT* be driven high, instead it will be switched to input, as input mode is high impedance, thus -achieveing an "open drain emulation" of sorts: electrically the behaviour will +achieving an "open drain emulation" of sorts: electrically the behaviour will be identical, with the exception of possible hardware glitches when switching the mode of the line. @@ -642,7 +642,7 @@ In this case the typical set-up will look like this: As you can see pretty similar, but you do not supply a parent handler for the IRQ, instead a parent irqdomain, an fwnode for the hardware and -a funcion .child_to_parent_hwirq() that has the purpose of looking up +a function .child_to_parent_hwirq() that has the purpose of looking up the parent hardware irq from a child (i.e. this gpio chip) hardware irq. As always it is good to look at examples in the kernel tree for advice on how to find the required pieces. diff --git a/Documentation/driver-api/gpio/intro.rst b/Documentation/driver-api/gpio/intro.rst index 2e924fb5b3d5..c9c19243b97f 100644 --- a/Documentation/driver-api/gpio/intro.rst +++ b/Documentation/driver-api/gpio/intro.rst @@ -14,12 +14,12 @@ 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 gpio-legacy.txt. + 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 gpio-legacy.txt. + usable for compatibility reasons) is documented in legacy.rst. The remainder of this document applies to the new descriptor-based interface. -gpio-legacy.txt contains the same information applied to the legacy +legacy.rst contains the same information applied to the legacy integer-based interface. diff --git a/Documentation/driver-api/gpio/using-gpio.rst b/Documentation/driver-api/gpio/using-gpio.rst index 64c8d3f76c3a..894d88855d73 100644 --- a/Documentation/driver-api/gpio/using-gpio.rst +++ b/Documentation/driver-api/gpio/using-gpio.rst @@ -44,7 +44,7 @@ These devices will appear on the system as ``/dev/gpiochip0`` thru found in the kernel tree ``tools/gpio`` subdirectory. For structured and managed applications, we recommend that you make use of the -libgpiod_ library. This provides helper abstractions, command line utlities +libgpiod_ library. This provides helper abstractions, command line utilities and arbitration for multiple simultaneous consumers on the same GPIO chip. .. _libgpiod: https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/ diff --git a/Documentation/driver-api/hte/tegra194-hte.rst b/Documentation/driver-api/hte/tegra194-hte.rst index 41983e04d2a0..f2d617265546 100644 --- a/Documentation/driver-api/hte/tegra194-hte.rst +++ b/Documentation/driver-api/hte/tegra194-hte.rst @@ -25,8 +25,7 @@ and userspace consumers. The kernel space consumers can directly talk to HTE subsystem while userspace consumers timestamp requests go through GPIOLIB CDEV framework to HTE subsystem. -.. kernel-doc:: drivers/gpio/gpiolib.c - :functions: gpiod_enable_hw_timestamp_ns gpiod_disable_hw_timestamp_ns +See gpiod_enable_hw_timestamp_ns() and gpiod_disable_hw_timestamp_ns(). For userspace consumers, GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE flag must be specified during IOCTL calls. Refer to ``tools/gpio/gpio-event-mon.c``, which @@ -37,7 +36,7 @@ LIC (Legacy Interrupt Controller) IRQ GTE This GTE instance timestamps LIC IRQ lines in real time. There are 352 IRQ lines which this instance can add timestamps to in real time. The hte -devicetree binding described at ``Documentation/devicetree/bindings/hte/`` +devicetree binding described at ``Documentation/devicetree/bindings/timestamp`` provides an example of how a consumer can request an IRQ line. Since it is a one-to-one mapping with IRQ GTE provider, consumers can simply specify the IRQ number that they are interested in. There is no userspace consumer support for diff --git a/Documentation/features/time/context-tracking/arch-support.txt b/Documentation/features/time/context-tracking/arch-support.txt index c9e0a16290e6..e59071a49090 100644 --- a/Documentation/features/time/context-tracking/arch-support.txt +++ b/Documentation/features/time/context-tracking/arch-support.txt @@ -1,7 +1,7 @@ # -# Feature name: context-tracking -# Kconfig: HAVE_CONTEXT_TRACKING -# description: arch supports context tracking for NO_HZ_FULL +# Feature name: user-context-tracking +# Kconfig: HAVE_CONTEXT_TRACKING_USER +# description: arch supports user context tracking for NO_HZ_FULL # ----------------------- | arch |status| diff --git a/Documentation/features/vm/ioremap_prot/arch-support.txt b/Documentation/features/vm/ioremap_prot/arch-support.txt index b01bf7bca3e6..6bd78eb4dc6e 100644 --- a/Documentation/features/vm/ioremap_prot/arch-support.txt +++ b/Documentation/features/vm/ioremap_prot/arch-support.txt @@ -9,7 +9,7 @@ | alpha: | TODO | | arc: | ok | | arm: | TODO | - | arm64: | TODO | + | arm64: | ok | | csky: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/filesystems/btrfs.rst b/Documentation/filesystems/btrfs.rst index d0904f602819..992eddb0e11b 100644 --- a/Documentation/filesystems/btrfs.rst +++ b/Documentation/filesystems/btrfs.rst @@ -19,13 +19,23 @@ The main Btrfs features include: * Subvolumes (separate internal filesystem roots) * Object level mirroring and striping * Checksums on data and metadata (multiple algorithms available) - * Compression + * Compression (multiple algorithms available) + * Reflink, deduplication + * Scrub (on-line checksum verification) + * Hierarchical quota groups (subvolume and snapshot support) * Integrated multiple device support, with several raid algorithms * Offline filesystem check - * Efficient incremental backup and FS mirroring + * Efficient incremental backup and FS mirroring (send/receive) + * Trim/discard * Online filesystem defragmentation + * Swapfile support + * Zoned mode + * Read/write metadata verification + * Online resize (shrink, grow) -For more information please refer to the wiki +For more information please refer to the documentation site or wiki + + https://btrfs.readthedocs.io https://btrfs.wiki.kernel.org diff --git a/Documentation/filesystems/ext2.rst b/Documentation/filesystems/ext2.rst index 154101cf0e4f..92aae683e16a 100644 --- a/Documentation/filesystems/ext2.rst +++ b/Documentation/filesystems/ext2.rst @@ -59,8 +59,6 @@ acl Enable POSIX Access Control Lists support (requires CONFIG_EXT2_FS_POSIX_ACL). noacl Don't support POSIX ACLs. -nobh Do not attach buffer_heads to file pagecache. - quota, usrquota Enable user disk quota support (requires CONFIG_QUOTA). diff --git a/Documentation/filesystems/ext4/attributes.rst b/Documentation/filesystems/ext4/attributes.rst index 871d2da7a0a9..87814696a65b 100644 --- a/Documentation/filesystems/ext4/attributes.rst +++ b/Documentation/filesystems/ext4/attributes.rst @@ -13,8 +13,8 @@ disappeared as of Linux 3.0. There are two places where extended attributes can be found. The first place is between the end of each inode entry and the beginning of the -next inode entry. For example, if inode.i\_extra\_isize = 28 and -sb.inode\_size = 256, then there are 256 - (128 + 28) = 100 bytes +next inode entry. For example, if inode.i_extra_isize = 28 and +sb.inode_size = 256, then there are 256 - (128 + 28) = 100 bytes available for in-inode extended attribute storage. The second place where extended attributes can be found is in the block pointed to by ``inode.i_file_acl``. As of Linux 3.11, it is not possible for this @@ -38,8 +38,8 @@ Extended attributes, when stored after the inode, have a header - Name - Description * - 0x0 - - \_\_le32 - - h\_magic + - __le32 + - h_magic - Magic number for identification, 0xEA020000. This value is set by the Linux driver, though e2fsprogs doesn't seem to check it(?) @@ -55,28 +55,28 @@ The beginning of an extended attribute block is in - Name - Description * - 0x0 - - \_\_le32 - - h\_magic + - __le32 + - h_magic - Magic number for identification, 0xEA020000. * - 0x4 - - \_\_le32 - - h\_refcount + - __le32 + - h_refcount - Reference count. * - 0x8 - - \_\_le32 - - h\_blocks + - __le32 + - h_blocks - Number of disk blocks used. * - 0xC - - \_\_le32 - - h\_hash + - __le32 + - h_hash - Hash value of all attributes. * - 0x10 - - \_\_le32 - - h\_checksum + - __le32 + - h_checksum - Checksum of the extended attribute block. * - 0x14 - - \_\_u32 - - h\_reserved[3] + - __u32 + - h_reserved[3] - Zero. The checksum is calculated against the FS UUID, the 64-bit block number @@ -100,46 +100,46 @@ Attributes stored inside an inode do not need be stored in sorted order. - Name - Description * - 0x0 - - \_\_u8 - - e\_name\_len + - __u8 + - e_name_len - Length of name. * - 0x1 - - \_\_u8 - - e\_name\_index + - __u8 + - e_name_index - Attribute name index. There is a discussion of this below. * - 0x2 - - \_\_le16 - - e\_value\_offs + - __le16 + - e_value_offs - Location of this attribute's value on the disk block where it is stored. Multiple attributes can share the same value. For an inode attribute this value is relative to the start of the first entry; for a block this value is relative to the start of the block (i.e. the header). * - 0x4 - - \_\_le32 - - e\_value\_inum + - __le32 + - e_value_inum - The inode where the value is stored. Zero indicates the value is in the same block as this entry. This field is only used if the - INCOMPAT\_EA\_INODE feature is enabled. + INCOMPAT_EA_INODE feature is enabled. * - 0x8 - - \_\_le32 - - e\_value\_size + - __le32 + - e_value_size - Length of attribute value. * - 0xC - - \_\_le32 - - e\_hash + - __le32 + - e_hash - Hash value of attribute name and attribute value. The kernel doesn't update the hash for in-inode attributes, so for that case this value must be zero, because e2fsck validates any non-zero hash regardless of where the xattr lives. * - 0x10 - char - - e\_name[e\_name\_len] + - e_name[e_name_len] - Attribute name. Does not include trailing NULL. Attribute values can follow the end of the entry table. There appears to be a requirement that they be aligned to 4-byte boundaries. The values are stored starting at the end of the block and grow towards the -xattr\_header/xattr\_entry table. When the two collide, the overflow is +xattr_header/xattr_entry table. When the two collide, the overflow is put into a separate disk block. If the disk block fills up, the filesystem returns -ENOSPC. @@ -167,15 +167,15 @@ the key name. Here is a map of name index values to key prefixes: * - 1 - “user.†* - 2 - - “system.posix\_acl\_access†+ - “system.posix_acl_access†* - 3 - - “system.posix\_acl\_default†+ - “system.posix_acl_default†* - 4 - “trusted.†* - 6 - “security.†* - 7 - - “system.†(inline\_data only?) + - “system.†(inline_data only?) * - 8 - “system.richacl†(SuSE kernels only?) diff --git a/Documentation/filesystems/ext4/bigalloc.rst b/Documentation/filesystems/ext4/bigalloc.rst index 72075aa608e4..976a180b209c 100644 --- a/Documentation/filesystems/ext4/bigalloc.rst +++ b/Documentation/filesystems/ext4/bigalloc.rst @@ -23,7 +23,7 @@ means that a block group addresses 32 gigabytes instead of 128 megabytes, also shrinking the amount of file system overhead for metadata. The administrator can set a block cluster size at mkfs time (which is -stored in the s\_log\_cluster\_size field in the superblock); from then +stored in the s_log_cluster_size field in the superblock); from then on, the block bitmaps track clusters, not individual blocks. This means that block groups can be several gigabytes in size (instead of just 128MiB); however, the minimum allocation unit becomes a cluster, not a diff --git a/Documentation/filesystems/ext4/bitmaps.rst b/Documentation/filesystems/ext4/bitmaps.rst index c7546dbc197a..91c45d86e9bb 100644 --- a/Documentation/filesystems/ext4/bitmaps.rst +++ b/Documentation/filesystems/ext4/bitmaps.rst @@ -9,15 +9,15 @@ group. The inode bitmap records which entries in the inode table are in use. As with most bitmaps, one bit represents the usage status of one data -block or inode table entry. This implies a block group size of 8 \* -number\_of\_bytes\_in\_a\_logical\_block. +block or inode table entry. This implies a block group size of 8 * +number_of_bytes_in_a_logical_block. NOTE: If ``BLOCK_UNINIT`` is set for a given block group, various parts of the kernel and e2fsprogs code pretends that the block bitmap contains zeros (i.e. all blocks in the group are free). However, it is not necessarily the case that no blocks are in use -- if ``meta_bg`` is set, the bitmaps and group descriptor live inside the group. Unfortunately, -ext2fs\_test\_block\_bitmap2() will return '0' for those locations, +ext2fs_test_block_bitmap2() will return '0' for those locations, which produces confusing debugfs output. Inode Table diff --git a/Documentation/filesystems/ext4/blockgroup.rst b/Documentation/filesystems/ext4/blockgroup.rst index d5d652addce5..46d78f860623 100644 --- a/Documentation/filesystems/ext4/blockgroup.rst +++ b/Documentation/filesystems/ext4/blockgroup.rst @@ -56,39 +56,39 @@ established that the super block and the group descriptor table, if present, will be at the beginning of the block group. The bitmaps and the inode table can be anywhere, and it is quite possible for the bitmaps to come after the inode table, or for both to be in different -groups (flex\_bg). Leftover space is used for file data blocks, indirect +groups (flex_bg). Leftover space is used for file data blocks, indirect block maps, extent tree blocks, and extended attributes. Flexible Block Groups --------------------- Starting in ext4, there is a new feature called flexible block groups -(flex\_bg). In a flex\_bg, several block groups are tied together as one +(flex_bg). In a flex_bg, several block groups are tied together as one logical block group; the bitmap spaces and the inode table space in the -first block group of the flex\_bg are expanded to include the bitmaps -and inode tables of all other block groups in the flex\_bg. For example, -if the flex\_bg size is 4, then group 0 will contain (in order) the +first block group of the flex_bg are expanded to include the bitmaps +and inode tables of all other block groups in the flex_bg. For example, +if the flex_bg size is 4, then group 0 will contain (in order) the superblock, group descriptors, data block bitmaps for groups 0-3, inode bitmaps for groups 0-3, inode tables for groups 0-3, and the remaining space in group 0 is for file data. The effect of this is to group the block group metadata close together for faster loading, and to enable large files to be continuous on disk. Backup copies of the superblock and group descriptors are always at the beginning of block groups, even -if flex\_bg is enabled. The number of block groups that make up a -flex\_bg is given by 2 ^ ``sb.s_log_groups_per_flex``. +if flex_bg is enabled. The number of block groups that make up a +flex_bg is given by 2 ^ ``sb.s_log_groups_per_flex``. Meta Block Groups ----------------- -Without the option META\_BG, for safety concerns, all block group +Without the option META_BG, for safety concerns, all block group descriptors copies are kept in the first block group. Given the default 128MiB(2^27 bytes) block group size and 64-byte group descriptors, ext4 can have at most 2^27/64 = 2^21 block groups. This limits the entire filesystem size to 2^21 * 2^27 = 2^48bytes or 256TiB. The solution to this problem is to use the metablock group feature -(META\_BG), which is already in ext3 for all 2.6 releases. With the -META\_BG feature, ext4 filesystems are partitioned into many metablock +(META_BG), which is already in ext3 for all 2.6 releases. With the +META_BG feature, ext4 filesystems are partitioned into many metablock groups. Each metablock group is a cluster of block groups whose group descriptor structures can be stored in a single disk block. For ext4 filesystems with 4 KB block size, a single metablock group partition @@ -110,7 +110,7 @@ bytes, a meta-block group contains 32 block groups for filesystems with a 1KB block size, and 128 block groups for filesystems with a 4KB blocksize. Filesystems can either be created using this new block group descriptor layout, or existing filesystems can be resized on-line, and -the field s\_first\_meta\_bg in the superblock will indicate the first +the field s_first_meta_bg in the superblock will indicate the first block group using this new layout. Please see an important note about ``BLOCK_UNINIT`` in the section about @@ -121,15 +121,15 @@ Lazy Block Group Initialization A new feature for ext4 are three block group descriptor flags that enable mkfs to skip initializing other parts of the block group -metadata. Specifically, the INODE\_UNINIT and BLOCK\_UNINIT flags mean +metadata. Specifically, the INODE_UNINIT and BLOCK_UNINIT flags mean that the inode and block bitmaps for that group can be calculated and therefore the on-disk bitmap blocks are not initialized. This is generally the case for an empty block group or a block group containing -only fixed-location block group metadata. The INODE\_ZEROED flag means +only fixed-location block group metadata. The INODE_ZEROED flag means that the inode table has been initialized; mkfs will unset this flag and rely on the kernel to initialize the inode tables in the background. By not writing zeroes to the bitmaps and inode table, mkfs time is -reduced considerably. Note the feature flag is RO\_COMPAT\_GDT\_CSUM, -but the dumpe2fs output prints this as “uninit\_bgâ€. They are the same +reduced considerably. Note the feature flag is RO_COMPAT_GDT_CSUM, +but the dumpe2fs output prints this as “uninit_bgâ€. They are the same thing. diff --git a/Documentation/filesystems/ext4/blockmap.rst b/Documentation/filesystems/ext4/blockmap.rst index 30e25750d88a..2bd990402a5c 100644 --- a/Documentation/filesystems/ext4/blockmap.rst +++ b/Documentation/filesystems/ext4/blockmap.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 +---------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| i.i\_block Offset | Where It Points | +| i.i_block Offset | Where It Points | +=====================+==============================================================================================================================================================================================================================+ | 0 to 11 | Direct map to file blocks 0 to 11. | +---------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/Documentation/filesystems/ext4/checksums.rst b/Documentation/filesystems/ext4/checksums.rst index 5519e253810d..e232749daf5f 100644 --- a/Documentation/filesystems/ext4/checksums.rst +++ b/Documentation/filesystems/ext4/checksums.rst @@ -4,7 +4,7 @@ Checksums --------- Starting in early 2012, metadata checksums were added to all major ext4 -and jbd2 data structures. The associated feature flag is metadata\_csum. +and jbd2 data structures. The associated feature flag is metadata_csum. The desired checksum algorithm is indicated in the superblock, though as of October 2012 the only supported algorithm is crc32c. Some data structures did not have space to fit a full 32-bit checksum, so only the @@ -20,7 +20,7 @@ encounters directory blocks that lack sufficient empty space to add a checksum, it will request that you run ``e2fsck -D`` to have the directories rebuilt with checksums. This has the added benefit of removing slack space from the directory files and rebalancing the htree -indexes. If you \_ignore\_ this step, your directories will not be +indexes. If you _ignore_ this step, your directories will not be protected by a checksum! The following table describes the data elements that go into each type @@ -35,39 +35,39 @@ of checksum. The checksum function is whatever the superblock describes - Length - Ingredients * - Superblock - - \_\_le32 + - __le32 - The entire superblock up to the checksum field. The UUID lives inside the superblock. * - MMP - - \_\_le32 + - __le32 - UUID + the entire MMP block up to the checksum field. * - Extended Attributes - - \_\_le32 + - __le32 - UUID + the entire extended attribute block. The checksum field is set to zero. * - Directory Entries - - \_\_le32 + - __le32 - UUID + inode number + inode generation + the directory block up to the fake entry enclosing the checksum field. * - HTREE Nodes - - \_\_le32 + - __le32 - UUID + inode number + inode generation + all valid extents + HTREE tail. The checksum field is set to zero. * - Extents - - \_\_le32 + - __le32 - UUID + inode number + inode generation + the entire extent block up to the checksum field. * - Bitmaps - - \_\_le32 or \_\_le16 + - __le32 or __le16 - UUID + the entire bitmap. Checksums are stored in the group descriptor, and truncated if the group descriptor size is 32 bytes (i.e. ^64bit) * - Inodes - - \_\_le32 + - __le32 - UUID + inode number + inode generation + the entire inode. The checksum field is set to zero. Each inode has its own checksum. * - Group Descriptors - - \_\_le16 - - If metadata\_csum, then UUID + group number + the entire descriptor; - else if gdt\_csum, then crc16(UUID + group number + the entire + - __le16 + - If metadata_csum, then UUID + group number + the entire descriptor; + else if gdt_csum, then crc16(UUID + group number + the entire descriptor). In all cases, only the lower 16 bits are stored. diff --git a/Documentation/filesystems/ext4/directory.rst b/Documentation/filesystems/ext4/directory.rst index 55f618b37144..6eece8e31df8 100644 --- a/Documentation/filesystems/ext4/directory.rst +++ b/Documentation/filesystems/ext4/directory.rst @@ -42,24 +42,24 @@ is at most 263 bytes long, though on disk you'll need to reference - Name - Description * - 0x0 - - \_\_le32 + - __le32 - inode - Number of the inode that this directory entry points to. * - 0x4 - - \_\_le16 - - rec\_len + - __le16 + - rec_len - Length of this directory entry. Must be a multiple of 4. * - 0x6 - - \_\_le16 - - name\_len + - __le16 + - name_len - Length of the file name. * - 0x8 - char - - name[EXT4\_NAME\_LEN] + - name[EXT4_NAME_LEN] - File name. Since file names cannot be longer than 255 bytes, the new directory -entry format shortens the name\_len field and uses the space for a file +entry format shortens the name_len field and uses the space for a file type flag, probably to avoid having to load every inode during directory tree traversal. This format is ``ext4_dir_entry_2``, which is at most 263 bytes long, though on disk you'll need to reference @@ -74,24 +74,24 @@ tree traversal. This format is ``ext4_dir_entry_2``, which is at most - Name - Description * - 0x0 - - \_\_le32 + - __le32 - inode - Number of the inode that this directory entry points to. * - 0x4 - - \_\_le16 - - rec\_len + - __le16 + - rec_len - Length of this directory entry. * - 0x6 - - \_\_u8 - - name\_len + - __u8 + - name_len - Length of the file name. * - 0x7 - - \_\_u8 - - file\_type + - __u8 + - file_type - File type code, see ftype_ table below. * - 0x8 - char - - name[EXT4\_NAME\_LEN] + - name[EXT4_NAME_LEN] - File name. .. _ftype: @@ -137,19 +137,19 @@ entry uses this extension, it may be up to 271 bytes. - Name - Description * - 0x0 - - \_\_le32 + - __le32 - hash - The hash of the directory name * - 0x4 - - \_\_le32 - - minor\_hash + - __le32 + - minor_hash - The minor hash of the directory name In order to add checksums to these classic directory blocks, a phony ``struct ext4_dir_entry`` is placed at the end of each leaf block to hold the checksum. The directory entry is 12 bytes long. The inode -number and name\_len fields are set to zero to fool old software into +number and name_len fields are set to zero to fool old software into ignoring an apparently empty directory entry, and the checksum is stored in the place where the name normally goes. The structure is ``struct ext4_dir_entry_tail``: @@ -163,24 +163,24 @@ in the place where the name normally goes. The structure is - Name - Description * - 0x0 - - \_\_le32 - - det\_reserved\_zero1 + - __le32 + - det_reserved_zero1 - Inode number, which must be zero. * - 0x4 - - \_\_le16 - - det\_rec\_len + - __le16 + - det_rec_len - Length of this directory entry, which must be 12. * - 0x6 - - \_\_u8 - - det\_reserved\_zero2 + - __u8 + - det_reserved_zero2 - Length of the file name, which must be zero. * - 0x7 - - \_\_u8 - - det\_reserved\_ft + - __u8 + - det_reserved_ft - File type, which must be 0xDE. * - 0x8 - - \_\_le32 - - det\_checksum + - __le32 + - det_checksum - Directory leaf block checksum. The leaf directory block checksum is calculated against the FS UUID, the @@ -194,7 +194,7 @@ Hash Tree Directories A linear array of directory entries isn't great for performance, so a new feature was added to ext3 to provide a faster (but peculiar) balanced tree keyed off a hash of the directory entry name. If the -EXT4\_INDEX\_FL (0x1000) flag is set in the inode, this directory uses a +EXT4_INDEX_FL (0x1000) flag is set in the inode, this directory uses a hashed btree (htree) to organize and find directory entries. For backwards read-only compatibility with ext2, this tree is actually hidden inside the directory file, masquerading as “empty†directory data @@ -206,14 +206,14 @@ rest of the directory block is empty so that it moves on. The root of the tree always lives in the first data block of the directory. By ext2 custom, the '.' and '..' entries must appear at the beginning of this first block, so they are put here as two -``struct ext4_dir_entry_2``\ s and not stored in the tree. The rest of +``struct ext4_dir_entry_2`` s and not stored in the tree. The rest of the root node contains metadata about the tree and finally a hash->block map to find nodes that are lower in the htree. If ``dx_root.info.indirect_levels`` is non-zero then the htree has two levels; the data block pointed to by the root node's map is an interior node, which is indexed by a minor hash. Interior nodes in this tree contains a zeroed out ``struct ext4_dir_entry_2`` followed by a -minor\_hash->block map to find leafe nodes. Leaf nodes contain a linear +minor_hash->block map to find leafe nodes. Leaf nodes contain a linear array of all ``struct ext4_dir_entry_2``; all of these entries (presumably) hash to the same value. If there is an overflow, the entries simply overflow into the next leaf node, and the @@ -245,83 +245,83 @@ of a data block: - Name - Description * - 0x0 - - \_\_le32 + - __le32 - dot.inode - inode number of this directory. * - 0x4 - - \_\_le16 - - dot.rec\_len + - __le16 + - dot.rec_len - Length of this record, 12. * - 0x6 - u8 - - dot.name\_len + - dot.name_len - Length of the name, 1. * - 0x7 - u8 - - dot.file\_type + - dot.file_type - File type of this entry, 0x2 (directory) (if the feature flag is set). * - 0x8 - char - dot.name[4] - - “.\\0\\0\\0†+ - “.\0\0\0†* - 0xC - - \_\_le32 + - __le32 - dotdot.inode - inode number of parent directory. * - 0x10 - - \_\_le16 - - dotdot.rec\_len - - block\_size - 12. The record length is long enough to cover all htree + - __le16 + - dotdot.rec_len + - block_size - 12. The record length is long enough to cover all htree data. * - 0x12 - u8 - - dotdot.name\_len + - dotdot.name_len - Length of the name, 2. * - 0x13 - u8 - - dotdot.file\_type + - dotdot.file_type - File type of this entry, 0x2 (directory) (if the feature flag is set). * - 0x14 - char - - dotdot\_name[4] - - “..\\0\\0†+ - dotdot_name[4] + - “..\0\0†* - 0x18 - - \_\_le32 - - struct dx\_root\_info.reserved\_zero + - __le32 + - struct dx_root_info.reserved_zero - Zero. * - 0x1C - u8 - - struct dx\_root\_info.hash\_version + - struct dx_root_info.hash_version - Hash type, see dirhash_ table below. * - 0x1D - u8 - - struct dx\_root\_info.info\_length + - struct dx_root_info.info_length - Length of the tree information, 0x8. * - 0x1E - u8 - - struct dx\_root\_info.indirect\_levels - - Depth of the htree. Cannot be larger than 3 if the INCOMPAT\_LARGEDIR + - struct dx_root_info.indirect_levels + - Depth of the htree. Cannot be larger than 3 if the INCOMPAT_LARGEDIR feature is set; cannot be larger than 2 otherwise. * - 0x1F - u8 - - struct dx\_root\_info.unused\_flags + - struct dx_root_info.unused_flags - * - 0x20 - - \_\_le16 + - __le16 - limit - - Maximum number of dx\_entries that can follow this header, plus 1 for + - Maximum number of dx_entries that can follow this header, plus 1 for the header itself. * - 0x22 - - \_\_le16 + - __le16 - count - - Actual number of dx\_entries that follow this header, plus 1 for the + - Actual number of dx_entries that follow this header, plus 1 for the header itself. * - 0x24 - - \_\_le32 + - __le32 - block - The block number (within the directory file) that goes with hash=0. * - 0x28 - - struct dx\_entry + - struct dx_entry - entries[0] - As many 8-byte ``struct dx_entry`` as fits in the rest of the data block. @@ -362,38 +362,38 @@ also the full length of a data block: - Name - Description * - 0x0 - - \_\_le32 + - __le32 - fake.inode - Zero, to make it look like this entry is not in use. * - 0x4 - - \_\_le16 - - fake.rec\_len - - The size of the block, in order to hide all of the dx\_node data. + - __le16 + - fake.rec_len + - The size of the block, in order to hide all of the dx_node data. * - 0x6 - u8 - - name\_len + - name_len - Zero. There is no name for this “unused†directory entry. * - 0x7 - u8 - - file\_type + - file_type - Zero. There is no file type for this “unused†directory entry. * - 0x8 - - \_\_le16 + - __le16 - limit - - Maximum number of dx\_entries that can follow this header, plus 1 for + - Maximum number of dx_entries that can follow this header, plus 1 for the header itself. * - 0xA - - \_\_le16 + - __le16 - count - - Actual number of dx\_entries that follow this header, plus 1 for the + - Actual number of dx_entries that follow this header, plus 1 for the header itself. * - 0xE - - \_\_le32 + - __le32 - block - The block number (within the directory file) that goes with the lowest hash value of this block. This value is stored in the parent block. * - 0x12 - - struct dx\_entry + - struct dx_entry - entries[0] - As many 8-byte ``struct dx_entry`` as fits in the rest of the data block. @@ -410,11 +410,11 @@ long: - Name - Description * - 0x0 - - \_\_le32 + - __le32 - hash - Hash code. * - 0x4 - - \_\_le32 + - __le32 - block - Block number (within the directory file, not filesystem blocks) of the next node in the htree. @@ -423,13 +423,13 @@ long: author.) If metadata checksums are enabled, the last 8 bytes of the directory -block (precisely the length of one dx\_entry) are used to store a +block (precisely the length of one dx_entry) are used to store a ``struct dx_tail``, which contains the checksum. The ``limit`` and -``count`` entries in the dx\_root/dx\_node structures are adjusted as -necessary to fit the dx\_tail into the block. If there is no space for -the dx\_tail, the user is notified to run e2fsck -D to rebuild the +``count`` entries in the dx_root/dx_node structures are adjusted as +necessary to fit the dx_tail into the block. If there is no space for +the dx_tail, the user is notified to run e2fsck -D to rebuild the directory index (which will ensure that there's space for the checksum. -The dx\_tail structure is 8 bytes long and looks like this: +The dx_tail structure is 8 bytes long and looks like this: .. list-table:: :widths: 8 8 24 40 @@ -441,13 +441,13 @@ The dx\_tail structure is 8 bytes long and looks like this: - Description * - 0x0 - u32 - - dt\_reserved + - dt_reserved - Zero. * - 0x4 - - \_\_le32 - - dt\_checksum + - __le32 + - dt_checksum - Checksum of the htree directory block. The checksum is calculated against the FS UUID, the htree index header -(dx\_root or dx\_node), all of the htree indices (dx\_entry) that are in -use, and the tail block (dx\_tail). +(dx_root or dx_node), all of the htree indices (dx_entry) that are in +use, and the tail block (dx_tail). diff --git a/Documentation/filesystems/ext4/eainode.rst b/Documentation/filesystems/ext4/eainode.rst index ecc0d01a0a72..7a2ef26b064a 100644 --- a/Documentation/filesystems/ext4/eainode.rst +++ b/Documentation/filesystems/ext4/eainode.rst @@ -5,14 +5,14 @@ Large Extended Attribute Values To enable ext4 to store extended attribute values that do not fit in the inode or in the single extended attribute block attached to an inode, -the EA\_INODE feature allows us to store the value in the data blocks of +the EA_INODE feature allows us to store the value in the data blocks of a regular file inode. This “EA inode†is linked only from the extended attribute name index and must not appear in a directory entry. The -inode's i\_atime field is used to store a checksum of the xattr value; -and i\_ctime/i\_version store a 64-bit reference count, which enables +inode's i_atime field is used to store a checksum of the xattr value; +and i_ctime/i_version store a 64-bit reference count, which enables sharing of large xattr values between multiple owning inodes. For backward compatibility with older versions of this feature, the -i\_mtime/i\_generation *may* store a back-reference to the inode number -and i\_generation of the **one** owning inode (in cases where the EA +i_mtime/i_generation *may* store a back-reference to the inode number +and i_generation of the **one** owning inode (in cases where the EA inode is not referenced by multiple inodes) to verify that the EA inode is the correct one being accessed. diff --git a/Documentation/filesystems/ext4/group_descr.rst b/Documentation/filesystems/ext4/group_descr.rst index 7ba6114e7f5c..392ec44f8fb0 100644 --- a/Documentation/filesystems/ext4/group_descr.rst +++ b/Documentation/filesystems/ext4/group_descr.rst @@ -7,34 +7,34 @@ Each block group on the filesystem has one of these descriptors associated with it. As noted in the Layout section above, the group descriptors (if present) are the second item in the block group. The standard configuration is for each block group to contain a full copy of -the block group descriptor table unless the sparse\_super feature flag +the block group descriptor table unless the sparse_super feature flag is set. Notice how the group descriptor records the location of both bitmaps and the inode table (i.e. they can float). This means that within a block group, the only data structures with fixed locations are the superblock -and the group descriptor table. The flex\_bg mechanism uses this +and the group descriptor table. The flex_bg mechanism uses this property to group several block groups into a flex group and lay out all of the groups' bitmaps and inode tables into one long run in the first group of the flex group. -If the meta\_bg feature flag is set, then several block groups are -grouped together into a meta group. Note that in the meta\_bg case, +If the meta_bg feature flag is set, then several block groups are +grouped together into a meta group. Note that in the meta_bg case, however, the first and last two block groups within the larger meta group contain only group descriptors for the groups inside the meta group. -flex\_bg and meta\_bg do not appear to be mutually exclusive features. +flex_bg and meta_bg do not appear to be mutually exclusive features. In ext2, ext3, and ext4 (when the 64bit feature is not enabled), the block group descriptor was only 32 bytes long and therefore ends at -bg\_checksum. On an ext4 filesystem with the 64bit feature enabled, the +bg_checksum. On an ext4 filesystem with the 64bit feature enabled, the block group descriptor expands to at least the 64 bytes described below; the size is stored in the superblock. -If gdt\_csum is set and metadata\_csum is not set, the block group +If gdt_csum is set and metadata_csum is not set, the block group checksum is the crc16 of the FS UUID, the group number, and the group -descriptor structure. If metadata\_csum is set, then the block group +descriptor structure. If metadata_csum is set, then the block group checksum is the lower 16 bits of the checksum of the FS UUID, the group number, and the group descriptor structure. Both block and inode bitmap checksums are calculated against the FS UUID, the group number, and the @@ -51,59 +51,59 @@ The block group descriptor is laid out in ``struct ext4_group_desc``. - Name - Description * - 0x0 - - \_\_le32 - - bg\_block\_bitmap\_lo + - __le32 + - bg_block_bitmap_lo - Lower 32-bits of location of block bitmap. * - 0x4 - - \_\_le32 - - bg\_inode\_bitmap\_lo + - __le32 + - bg_inode_bitmap_lo - Lower 32-bits of location of inode bitmap. * - 0x8 - - \_\_le32 - - bg\_inode\_table\_lo + - __le32 + - bg_inode_table_lo - Lower 32-bits of location of inode table. * - 0xC - - \_\_le16 - - bg\_free\_blocks\_count\_lo + - __le16 + - bg_free_blocks_count_lo - Lower 16-bits of free block count. * - 0xE - - \_\_le16 - - bg\_free\_inodes\_count\_lo + - __le16 + - bg_free_inodes_count_lo - Lower 16-bits of free inode count. * - 0x10 - - \_\_le16 - - bg\_used\_dirs\_count\_lo + - __le16 + - bg_used_dirs_count_lo - Lower 16-bits of directory count. * - 0x12 - - \_\_le16 - - bg\_flags + - __le16 + - bg_flags - Block group flags. See the bgflags_ table below. * - 0x14 - - \_\_le32 - - bg\_exclude\_bitmap\_lo + - __le32 + - bg_exclude_bitmap_lo - Lower 32-bits of location of snapshot exclusion bitmap. * - 0x18 - - \_\_le16 - - bg\_block\_bitmap\_csum\_lo + - __le16 + - bg_block_bitmap_csum_lo - Lower 16-bits of the block bitmap checksum. * - 0x1A - - \_\_le16 - - bg\_inode\_bitmap\_csum\_lo + - __le16 + - bg_inode_bitmap_csum_lo - Lower 16-bits of the inode bitmap checksum. * - 0x1C - - \_\_le16 - - bg\_itable\_unused\_lo + - __le16 + - bg_itable_unused_lo - Lower 16-bits of unused inode count. If set, we needn't scan past the - ``(sb.s_inodes_per_group - gdt.bg_itable_unused)``\ th entry in the + ``(sb.s_inodes_per_group - gdt.bg_itable_unused)`` th entry in the inode table for this group. * - 0x1E - - \_\_le16 - - bg\_checksum - - Group descriptor checksum; crc16(sb\_uuid+group\_num+bg\_desc) if the - RO\_COMPAT\_GDT\_CSUM feature is set, or - crc32c(sb\_uuid+group\_num+bg\_desc) & 0xFFFF if the - RO\_COMPAT\_METADATA\_CSUM feature is set. The bg\_checksum - field in bg\_desc is skipped when calculating crc16 checksum, + - __le16 + - bg_checksum + - Group descriptor checksum; crc16(sb_uuid+group_num+bg_desc) if the + RO_COMPAT_GDT_CSUM feature is set, or + crc32c(sb_uuid+group_num+bg_desc) & 0xFFFF if the + RO_COMPAT_METADATA_CSUM feature is set. The bg_checksum + field in bg_desc is skipped when calculating crc16 checksum, and set to zero if crc32c checksum is used. * - - @@ -111,48 +111,48 @@ The block group descriptor is laid out in ``struct ext4_group_desc``. - These fields only exist if the 64bit feature is enabled and s_desc_size > 32. * - 0x20 - - \_\_le32 - - bg\_block\_bitmap\_hi + - __le32 + - bg_block_bitmap_hi - Upper 32-bits of location of block bitmap. * - 0x24 - - \_\_le32 - - bg\_inode\_bitmap\_hi + - __le32 + - bg_inode_bitmap_hi - Upper 32-bits of location of inodes bitmap. * - 0x28 - - \_\_le32 - - bg\_inode\_table\_hi + - __le32 + - bg_inode_table_hi - Upper 32-bits of location of inodes table. * - 0x2C - - \_\_le16 - - bg\_free\_blocks\_count\_hi + - __le16 + - bg_free_blocks_count_hi - Upper 16-bits of free block count. * - 0x2E - - \_\_le16 - - bg\_free\_inodes\_count\_hi + - __le16 + - bg_free_inodes_count_hi - Upper 16-bits of free inode count. * - 0x30 - - \_\_le16 - - bg\_used\_dirs\_count\_hi + - __le16 + - bg_used_dirs_count_hi - Upper 16-bits of directory count. * - 0x32 - - \_\_le16 - - bg\_itable\_unused\_hi + - __le16 + - bg_itable_unused_hi - Upper 16-bits of unused inode count. * - 0x34 - - \_\_le32 - - bg\_exclude\_bitmap\_hi + - __le32 + - bg_exclude_bitmap_hi - Upper 32-bits of location of snapshot exclusion bitmap. * - 0x38 - - \_\_le16 - - bg\_block\_bitmap\_csum\_hi + - __le16 + - bg_block_bitmap_csum_hi - Upper 16-bits of the block bitmap checksum. * - 0x3A - - \_\_le16 - - bg\_inode\_bitmap\_csum\_hi + - __le16 + - bg_inode_bitmap_csum_hi - Upper 16-bits of the inode bitmap checksum. * - 0x3C - - \_\_u32 - - bg\_reserved + - __u32 + - bg_reserved - Padding to 64 bytes. .. _bgflags: @@ -166,8 +166,8 @@ Block group flags can be any combination of the following: * - Value - Description * - 0x1 - - inode table and bitmap are not initialized (EXT4\_BG\_INODE\_UNINIT). + - inode table and bitmap are not initialized (EXT4_BG_INODE_UNINIT). * - 0x2 - - block bitmap is not initialized (EXT4\_BG\_BLOCK\_UNINIT). + - block bitmap is not initialized (EXT4_BG_BLOCK_UNINIT). * - 0x4 - - inode table is zeroed (EXT4\_BG\_INODE\_ZEROED). + - inode table is zeroed (EXT4_BG_INODE_ZEROED). diff --git a/Documentation/filesystems/ext4/ifork.rst b/Documentation/filesystems/ext4/ifork.rst index b9816d5a896b..dc31f505e6c8 100644 --- a/Documentation/filesystems/ext4/ifork.rst +++ b/Documentation/filesystems/ext4/ifork.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0 -The Contents of inode.i\_block +The Contents of inode.i_block ------------------------------ Depending on the type of file an inode describes, the 60 bytes of @@ -47,7 +47,7 @@ In ext4, the file to logical block map has been replaced with an extent tree. Under the old scheme, allocating a contiguous run of 1,000 blocks requires an indirect block to map all 1,000 entries; with extents, the mapping is reduced to a single ``struct ext4_extent`` with -``ee_len = 1000``. If flex\_bg is enabled, it is possible to allocate +``ee_len = 1000``. If flex_bg is enabled, it is possible to allocate very large files with a single extent, at a considerable reduction in metadata block use, and some improvement in disk efficiency. The inode must have the extents flag (0x80000) flag set for this feature to be in @@ -76,28 +76,28 @@ which is 12 bytes long: - Name - Description * - 0x0 - - \_\_le16 - - eh\_magic + - __le16 + - eh_magic - Magic number, 0xF30A. * - 0x2 - - \_\_le16 - - eh\_entries + - __le16 + - eh_entries - Number of valid entries following the header. * - 0x4 - - \_\_le16 - - eh\_max + - __le16 + - eh_max - Maximum number of entries that could follow the header. * - 0x6 - - \_\_le16 - - eh\_depth + - __le16 + - eh_depth - Depth of this extent node in the extent tree. 0 = this extent node points to data blocks; otherwise, this extent node points to other extent nodes. The extent tree can be at most 5 levels deep: a logical block number can be at most ``2^32``, and the smallest ``n`` that satisfies ``4*(((blocksize - 12)/12)^n) >= 2^32`` is 5. * - 0x8 - - \_\_le32 - - eh\_generation + - __le32 + - eh_generation - Generation of the tree. (Used by Lustre, but not standard ext4). Internal nodes of the extent tree, also known as index nodes, are @@ -112,22 +112,22 @@ recorded as ``struct ext4_extent_idx``, and are 12 bytes long: - Name - Description * - 0x0 - - \_\_le32 - - ei\_block + - __le32 + - ei_block - This index node covers file blocks from 'block' onward. * - 0x4 - - \_\_le32 - - ei\_leaf\_lo + - __le32 + - ei_leaf_lo - Lower 32-bits of the block number of the extent node that is the next level lower in the tree. The tree node pointed to can be either another internal node or a leaf node, described below. * - 0x8 - - \_\_le16 - - ei\_leaf\_hi + - __le16 + - ei_leaf_hi - Upper 16-bits of the previous field. * - 0xA - - \_\_u16 - - ei\_unused + - __u16 + - ei_unused - Leaf nodes of the extent tree are recorded as ``struct ext4_extent``, @@ -142,24 +142,24 @@ and are also 12 bytes long: - Name - Description * - 0x0 - - \_\_le32 - - ee\_block + - __le32 + - ee_block - First file block number that this extent covers. * - 0x4 - - \_\_le16 - - ee\_len + - __le16 + - ee_len - Number of blocks covered by extent. If the value of this field is <= 32768, the extent is initialized. If the value of the field is > 32768, the extent is uninitialized and the actual extent length is ``ee_len`` - 32768. Therefore, the maximum length of a initialized extent is 32768 blocks, and the maximum length of an uninitialized extent is 32767. * - 0x6 - - \_\_le16 - - ee\_start\_hi + - __le16 + - ee_start_hi - Upper 16-bits of the block number to which this extent points. * - 0x8 - - \_\_le32 - - ee\_start\_lo + - __le32 + - ee_start_lo - Lower 32-bits of the block number to which this extent points. Prior to the introduction of metadata checksums, the extent header + @@ -182,8 +182,8 @@ including) the checksum itself. - Name - Description * - 0x0 - - \_\_le32 - - eb\_checksum + - __le32 + - eb_checksum - Checksum of the extent block, crc32c(uuid+inum+igeneration+extentblock) Inline Data diff --git a/Documentation/filesystems/ext4/inlinedata.rst b/Documentation/filesystems/ext4/inlinedata.rst index d1075178ce0b..a728af0d2fd0 100644 --- a/Documentation/filesystems/ext4/inlinedata.rst +++ b/Documentation/filesystems/ext4/inlinedata.rst @@ -11,12 +11,12 @@ file is smaller than 60 bytes, then the data are stored inline in attribute space, then it might be found as an extended attribute “system.data†within the inode body (“ibody EAâ€). This of course constrains the amount of extended attributes one can attach to an inode. -If the data size increases beyond i\_block + ibody EA, a regular block +If the data size increases beyond i_block + ibody EA, a regular block is allocated and the contents moved to that block. Pending a change to compact the extended attribute key used to store inline data, one ought to be able to store 160 bytes of data in a -256-byte inode (as of June 2015, when i\_extra\_isize is 28). Prior to +256-byte inode (as of June 2015, when i_extra_isize is 28). Prior to that, the limit was 156 bytes due to inefficient use of inode space. The inline data feature requires the presence of an extended attribute @@ -25,12 +25,12 @@ for “system.dataâ€, even if the attribute value is zero length. Inline Directories ~~~~~~~~~~~~~~~~~~ -The first four bytes of i\_block are the inode number of the parent +The first four bytes of i_block are the inode number of the parent directory. Following that is a 56-byte space for an array of directory entries; see ``struct ext4_dir_entry``. If there is a “system.data†attribute in the inode body, the EA value is an array of ``struct ext4_dir_entry`` as well. Note that for inline directories, the -i\_block and EA space are treated as separate dirent blocks; directory +i_block and EA space are treated as separate dirent blocks; directory entries cannot span the two. Inline directory entries are not checksummed, as the inode checksum diff --git a/Documentation/filesystems/ext4/inodes.rst b/Documentation/filesystems/ext4/inodes.rst index 6c5ce666e63f..cfc6c1659931 100644 --- a/Documentation/filesystems/ext4/inodes.rst +++ b/Documentation/filesystems/ext4/inodes.rst @@ -38,138 +38,138 @@ The inode table entry is laid out in ``struct ext4_inode``. - Name - Description * - 0x0 - - \_\_le16 - - i\_mode + - __le16 + - i_mode - File mode. See the table i_mode_ below. * - 0x2 - - \_\_le16 - - i\_uid + - __le16 + - i_uid - Lower 16-bits of Owner UID. * - 0x4 - - \_\_le32 - - i\_size\_lo + - __le32 + - i_size_lo - Lower 32-bits of size in bytes. * - 0x8 - - \_\_le32 - - i\_atime - - Last access time, in seconds since the epoch. However, if the EA\_INODE + - __le32 + - i_atime + - Last access time, in seconds since the epoch. However, if the EA_INODE inode flag is set, this inode stores an extended attribute value and this field contains the checksum of the value. * - 0xC - - \_\_le32 - - i\_ctime + - __le32 + - i_ctime - Last inode change time, in seconds since the epoch. However, if the - EA\_INODE inode flag is set, this inode stores an extended attribute + EA_INODE inode flag is set, this inode stores an extended attribute value and this field contains the lower 32 bits of the attribute value's reference count. * - 0x10 - - \_\_le32 - - i\_mtime + - __le32 + - i_mtime - Last data modification time, in seconds since the epoch. However, if the - EA\_INODE inode flag is set, this inode stores an extended attribute + EA_INODE inode flag is set, this inode stores an extended attribute value and this field contains the number of the inode that owns the extended attribute. * - 0x14 - - \_\_le32 - - i\_dtime + - __le32 + - i_dtime - Deletion Time, in seconds since the epoch. * - 0x18 - - \_\_le16 - - i\_gid + - __le16 + - i_gid - Lower 16-bits of GID. * - 0x1A - - \_\_le16 - - i\_links\_count + - __le16 + - i_links_count - Hard link count. Normally, ext4 does not permit an inode to have more than 65,000 hard links. This applies to files as well as directories, which means that there cannot be more than 64,998 subdirectories in a directory (each subdirectory's '..' entry counts as a hard link, as does - the '.' entry in the directory itself). With the DIR\_NLINK feature + the '.' entry in the directory itself). With the DIR_NLINK feature enabled, ext4 supports more than 64,998 subdirectories by setting this field to 1 to indicate that the number of hard links is not known. * - 0x1C - - \_\_le32 - - i\_blocks\_lo - - Lower 32-bits of “block†count. If the huge\_file feature flag is not + - __le32 + - i_blocks_lo + - Lower 32-bits of “block†count. If the huge_file feature flag is not set on the filesystem, the file consumes ``i_blocks_lo`` 512-byte blocks - on disk. If huge\_file is set and EXT4\_HUGE\_FILE\_FL is NOT set in + on disk. If huge_file is set and EXT4_HUGE_FILE_FL is NOT set in ``inode.i_flags``, then the file consumes ``i_blocks_lo + (i_blocks_hi - << 32)`` 512-byte blocks on disk. If huge\_file is set and - EXT4\_HUGE\_FILE\_FL IS set in ``inode.i_flags``, then this file + << 32)`` 512-byte blocks on disk. If huge_file is set and + EXT4_HUGE_FILE_FL IS set in ``inode.i_flags``, then this file consumes (``i_blocks_lo + i_blocks_hi`` << 32) filesystem blocks on disk. * - 0x20 - - \_\_le32 - - i\_flags + - __le32 + - i_flags - Inode flags. See the table i_flags_ below. * - 0x24 - 4 bytes - - i\_osd1 + - i_osd1 - See the table i_osd1_ for more details. * - 0x28 - 60 bytes - - i\_block[EXT4\_N\_BLOCKS=15] - - Block map or extent tree. See the section “The Contents of inode.i\_blockâ€. + - i_block[EXT4_N_BLOCKS=15] + - Block map or extent tree. See the section “The Contents of inode.i_blockâ€. * - 0x64 - - \_\_le32 - - i\_generation + - __le32 + - i_generation - File version (for NFS). * - 0x68 - - \_\_le32 - - i\_file\_acl\_lo + - __le32 + - i_file_acl_lo - Lower 32-bits of extended attribute block. ACLs are of course one of many possible extended attributes; I think the name of this field is a result of the first use of extended attributes being for ACLs. * - 0x6C - - \_\_le32 - - i\_size\_high / i\_dir\_acl + - __le32 + - i_size_high / i_dir_acl - Upper 32-bits of file/directory size. In ext2/3 this field was named - i\_dir\_acl, though it was usually set to zero and never used. + i_dir_acl, though it was usually set to zero and never used. * - 0x70 - - \_\_le32 - - i\_obso\_faddr + - __le32 + - i_obso_faddr - (Obsolete) fragment address. * - 0x74 - 12 bytes - - i\_osd2 + - i_osd2 - See the table i_osd2_ for more details. * - 0x80 - - \_\_le16 - - i\_extra\_isize + - __le16 + - i_extra_isize - Size of this inode - 128. Alternately, the size of the extended inode fields beyond the original ext2 inode, including this field. * - 0x82 - - \_\_le16 - - i\_checksum\_hi + - __le16 + - i_checksum_hi - Upper 16-bits of the inode checksum. * - 0x84 - - \_\_le32 - - i\_ctime\_extra + - __le32 + - i_ctime_extra - Extra change time bits. This provides sub-second precision. See Inode Timestamps section. * - 0x88 - - \_\_le32 - - i\_mtime\_extra + - __le32 + - i_mtime_extra - Extra modification time bits. This provides sub-second precision. * - 0x8C - - \_\_le32 - - i\_atime\_extra + - __le32 + - i_atime_extra - Extra access time bits. This provides sub-second precision. * - 0x90 - - \_\_le32 - - i\_crtime + - __le32 + - i_crtime - File creation time, in seconds since the epoch. * - 0x94 - - \_\_le32 - - i\_crtime\_extra + - __le32 + - i_crtime_extra - Extra file creation time bits. This provides sub-second precision. * - 0x98 - - \_\_le32 - - i\_version\_hi + - __le32 + - i_version_hi - Upper 32-bits for version number. * - 0x9C - - \_\_le32 - - i\_projid + - __le32 + - i_projid - Project ID. .. _i_mode: @@ -183,45 +183,45 @@ The ``i_mode`` value is a combination of the following flags: * - Value - Description * - 0x1 - - S\_IXOTH (Others may execute) + - S_IXOTH (Others may execute) * - 0x2 - - S\_IWOTH (Others may write) + - S_IWOTH (Others may write) * - 0x4 - - S\_IROTH (Others may read) + - S_IROTH (Others may read) * - 0x8 - - S\_IXGRP (Group members may execute) + - S_IXGRP (Group members may execute) * - 0x10 - - S\_IWGRP (Group members may write) + - S_IWGRP (Group members may write) * - 0x20 - - S\_IRGRP (Group members may read) + - S_IRGRP (Group members may read) * - 0x40 - - S\_IXUSR (Owner may execute) + - S_IXUSR (Owner may execute) * - 0x80 - - S\_IWUSR (Owner may write) + - S_IWUSR (Owner may write) * - 0x100 - - S\_IRUSR (Owner may read) + - S_IRUSR (Owner may read) * - 0x200 - - S\_ISVTX (Sticky bit) + - S_ISVTX (Sticky bit) * - 0x400 - - S\_ISGID (Set GID) + - S_ISGID (Set GID) * - 0x800 - - S\_ISUID (Set UID) + - S_ISUID (Set UID) * - - These are mutually-exclusive file types: * - 0x1000 - - S\_IFIFO (FIFO) + - S_IFIFO (FIFO) * - 0x2000 - - S\_IFCHR (Character device) + - S_IFCHR (Character device) * - 0x4000 - - S\_IFDIR (Directory) + - S_IFDIR (Directory) * - 0x6000 - - S\_IFBLK (Block device) + - S_IFBLK (Block device) * - 0x8000 - - S\_IFREG (Regular file) + - S_IFREG (Regular file) * - 0xA000 - - S\_IFLNK (Symbolic link) + - S_IFLNK (Symbolic link) * - 0xC000 - - S\_IFSOCK (Socket) + - S_IFSOCK (Socket) .. _i_flags: @@ -234,56 +234,56 @@ The ``i_flags`` field is a combination of these values: * - Value - Description * - 0x1 - - This file requires secure deletion (EXT4\_SECRM\_FL). (not implemented) + - This file requires secure deletion (EXT4_SECRM_FL). (not implemented) * - 0x2 - This file should be preserved, should undeletion be desired - (EXT4\_UNRM\_FL). (not implemented) + (EXT4_UNRM_FL). (not implemented) * - 0x4 - - File is compressed (EXT4\_COMPR\_FL). (not really implemented) + - File is compressed (EXT4_COMPR_FL). (not really implemented) * - 0x8 - - All writes to the file must be synchronous (EXT4\_SYNC\_FL). + - All writes to the file must be synchronous (EXT4_SYNC_FL). * - 0x10 - - File is immutable (EXT4\_IMMUTABLE\_FL). + - File is immutable (EXT4_IMMUTABLE_FL). * - 0x20 - - File can only be appended (EXT4\_APPEND\_FL). + - File can only be appended (EXT4_APPEND_FL). * - 0x40 - - The dump(1) utility should not dump this file (EXT4\_NODUMP\_FL). + - The dump(1) utility should not dump this file (EXT4_NODUMP_FL). * - 0x80 - - Do not update access time (EXT4\_NOATIME\_FL). + - Do not update access time (EXT4_NOATIME_FL). * - 0x100 - - Dirty compressed file (EXT4\_DIRTY\_FL). (not used) + - Dirty compressed file (EXT4_DIRTY_FL). (not used) * - 0x200 - - File has one or more compressed clusters (EXT4\_COMPRBLK\_FL). (not used) + - File has one or more compressed clusters (EXT4_COMPRBLK_FL). (not used) * - 0x400 - - Do not compress file (EXT4\_NOCOMPR\_FL). (not used) + - Do not compress file (EXT4_NOCOMPR_FL). (not used) * - 0x800 - - Encrypted inode (EXT4\_ENCRYPT\_FL). This bit value previously was - EXT4\_ECOMPR\_FL (compression error), which was never used. + - Encrypted inode (EXT4_ENCRYPT_FL). This bit value previously was + EXT4_ECOMPR_FL (compression error), which was never used. * - 0x1000 - - Directory has hashed indexes (EXT4\_INDEX\_FL). + - Directory has hashed indexes (EXT4_INDEX_FL). * - 0x2000 - - AFS magic directory (EXT4\_IMAGIC\_FL). + - AFS magic directory (EXT4_IMAGIC_FL). * - 0x4000 - File data must always be written through the journal - (EXT4\_JOURNAL\_DATA\_FL). + (EXT4_JOURNAL_DATA_FL). * - 0x8000 - - File tail should not be merged (EXT4\_NOTAIL\_FL). (not used by ext4) + - File tail should not be merged (EXT4_NOTAIL_FL). (not used by ext4) * - 0x10000 - All directory entry data should be written synchronously (see - ``dirsync``) (EXT4\_DIRSYNC\_FL). + ``dirsync``) (EXT4_DIRSYNC_FL). * - 0x20000 - - Top of directory hierarchy (EXT4\_TOPDIR\_FL). + - Top of directory hierarchy (EXT4_TOPDIR_FL). * - 0x40000 - - This is a huge file (EXT4\_HUGE\_FILE\_FL). + - This is a huge file (EXT4_HUGE_FILE_FL). * - 0x80000 - - Inode uses extents (EXT4\_EXTENTS\_FL). + - Inode uses extents (EXT4_EXTENTS_FL). * - 0x100000 - - Verity protected file (EXT4\_VERITY\_FL). + - Verity protected file (EXT4_VERITY_FL). * - 0x200000 - Inode stores a large extended attribute value in its data blocks - (EXT4\_EA\_INODE\_FL). + (EXT4_EA_INODE_FL). * - 0x400000 - - This file has blocks allocated past EOF (EXT4\_EOFBLOCKS\_FL). + - This file has blocks allocated past EOF (EXT4_EOFBLOCKS_FL). (deprecated) * - 0x01000000 - Inode is a snapshot (``EXT4_SNAPFILE_FL``). (not in mainline) @@ -294,21 +294,21 @@ The ``i_flags`` field is a combination of these values: - Snapshot shrink has completed (``EXT4_SNAPFILE_SHRUNK_FL``). (not in mainline) * - 0x10000000 - - Inode has inline data (EXT4\_INLINE\_DATA\_FL). + - Inode has inline data (EXT4_INLINE_DATA_FL). * - 0x20000000 - - Create children with the same project ID (EXT4\_PROJINHERIT\_FL). + - Create children with the same project ID (EXT4_PROJINHERIT_FL). * - 0x80000000 - - Reserved for ext4 library (EXT4\_RESERVED\_FL). + - Reserved for ext4 library (EXT4_RESERVED_FL). * - - Aggregate flags: * - 0x705BDFFF - User-visible flags. * - 0x604BC0FF - - User-modifiable flags. Note that while EXT4\_JOURNAL\_DATA\_FL and - EXT4\_EXTENTS\_FL can be set with setattr, they are not in the kernel's - EXT4\_FL\_USER\_MODIFIABLE mask, since it needs to handle the setting of + - User-modifiable flags. Note that while EXT4_JOURNAL_DATA_FL and + EXT4_EXTENTS_FL can be set with setattr, they are not in the kernel's + EXT4_FL_USER_MODIFIABLE mask, since it needs to handle the setting of these flags in a special manner and they are masked out of the set of - flags that are saved directly to i\_flags. + flags that are saved directly to i_flags. .. _i_osd1: @@ -325,9 +325,9 @@ Linux: - Name - Description * - 0x0 - - \_\_le32 - - l\_i\_version - - Inode version. However, if the EA\_INODE inode flag is set, this inode + - __le32 + - l_i_version + - Inode version. However, if the EA_INODE inode flag is set, this inode stores an extended attribute value and this field contains the upper 32 bits of the attribute value's reference count. @@ -342,8 +342,8 @@ Hurd: - Name - Description * - 0x0 - - \_\_le32 - - h\_i\_translator + - __le32 + - h_i_translator - ?? Masix: @@ -357,8 +357,8 @@ Masix: - Name - Description * - 0x0 - - \_\_le32 - - m\_i\_reserved + - __le32 + - m_i_reserved - ?? .. _i_osd2: @@ -376,30 +376,30 @@ Linux: - Name - Description * - 0x0 - - \_\_le16 - - l\_i\_blocks\_high + - __le16 + - l_i_blocks_high - Upper 16-bits of the block count. Please see the note attached to - i\_blocks\_lo. + i_blocks_lo. * - 0x2 - - \_\_le16 - - l\_i\_file\_acl\_high + - __le16 + - l_i_file_acl_high - Upper 16-bits of the extended attribute block (historically, the file ACL location). See the Extended Attributes section below. * - 0x4 - - \_\_le16 - - l\_i\_uid\_high + - __le16 + - l_i_uid_high - Upper 16-bits of the Owner UID. * - 0x6 - - \_\_le16 - - l\_i\_gid\_high + - __le16 + - l_i_gid_high - Upper 16-bits of the GID. * - 0x8 - - \_\_le16 - - l\_i\_checksum\_lo + - __le16 + - l_i_checksum_lo - Lower 16-bits of the inode checksum. * - 0xA - - \_\_le16 - - l\_i\_reserved + - __le16 + - l_i_reserved - Unused. Hurd: @@ -413,24 +413,24 @@ Hurd: - Name - Description * - 0x0 - - \_\_le16 - - h\_i\_reserved1 + - __le16 + - h_i_reserved1 - ?? * - 0x2 - - \_\_u16 - - h\_i\_mode\_high + - __u16 + - h_i_mode_high - Upper 16-bits of the file mode. * - 0x4 - - \_\_le16 - - h\_i\_uid\_high + - __le16 + - h_i_uid_high - Upper 16-bits of the Owner UID. * - 0x6 - - \_\_le16 - - h\_i\_gid\_high + - __le16 + - h_i_gid_high - Upper 16-bits of the GID. * - 0x8 - - \_\_u32 - - h\_i\_author + - __u32 + - h_i_author - Author code? Masix: @@ -444,17 +444,17 @@ Masix: - Name - Description * - 0x0 - - \_\_le16 - - h\_i\_reserved1 + - __le16 + - h_i_reserved1 - ?? * - 0x2 - - \_\_u16 - - m\_i\_file\_acl\_high + - __u16 + - m_i_file_acl_high - Upper 16-bits of the extended attribute block (historically, the file ACL location). * - 0x4 - - \_\_u32 - - m\_i\_reserved2[2] + - __u32 + - m_i_reserved2[2] - ?? Inode Size @@ -466,11 +466,11 @@ In ext2 and ext3, the inode structure size was fixed at 128 bytes on-disk inode at format time for all inodes in the filesystem to provide space beyond the end of the original ext2 inode. The on-disk inode record size is recorded in the superblock as ``s_inode_size``. The -number of bytes actually used by struct ext4\_inode beyond the original +number of bytes actually used by struct ext4_inode beyond the original 128-byte ext2 inode is recorded in the ``i_extra_isize`` field for each -inode, which allows struct ext4\_inode to grow for a new kernel without +inode, which allows struct ext4_inode to grow for a new kernel without having to upgrade all of the on-disk inodes. Access to fields beyond -EXT2\_GOOD\_OLD\_INODE\_SIZE should be verified to be within +EXT2_GOOD_OLD_INODE_SIZE should be verified to be within ``i_extra_isize``. By default, ext4 inode records are 256 bytes, and (as of August 2019) the inode structure is 160 bytes (``i_extra_isize = 32``). The extra space between the end of the inode @@ -516,7 +516,7 @@ creation time (crtime); this field is 64-bits wide and decoded in the same manner as 64-bit [cma]time. Neither crtime nor dtime are accessible through the regular stat() interface, though debugfs will report them. -We use the 32-bit signed time value plus (2^32 \* (extra epoch bits)). +We use the 32-bit signed time value plus (2^32 * (extra epoch bits)). In other words: .. list-table:: @@ -525,8 +525,8 @@ In other words: * - Extra epoch bits - MSB of 32-bit time - - Adjustment for signed 32-bit to 64-bit tv\_sec - - Decoded 64-bit tv\_sec + - Adjustment for signed 32-bit to 64-bit tv_sec + - Decoded 64-bit tv_sec - valid time range * - 0 0 - 1 diff --git a/Documentation/filesystems/ext4/journal.rst b/Documentation/filesystems/ext4/journal.rst index 5fad38860f17..a6bef5293a60 100644 --- a/Documentation/filesystems/ext4/journal.rst +++ b/Documentation/filesystems/ext4/journal.rst @@ -63,8 +63,8 @@ Generally speaking, the journal has this format: :header-rows: 1 * - Superblock - - descriptor\_block (data\_blocks or revocation\_block) [more data or - revocations] commmit\_block + - descriptor_block (data_blocks or revocation_block) [more data or + revocations] commmit_block - [more transactions...] * - - One transaction @@ -93,8 +93,8 @@ superblock. * - 1024 bytes of padding - ext4 Superblock - Journal Superblock - - descriptor\_block (data\_blocks or revocation\_block) [more data or - revocations] commmit\_block + - descriptor_block (data_blocks or revocation_block) [more data or + revocations] commmit_block - [more transactions...] * - - @@ -117,17 +117,17 @@ Every block in the journal starts with a common 12-byte header - Name - Description * - 0x0 - - \_\_be32 - - h\_magic + - __be32 + - h_magic - jbd2 magic number, 0xC03B3998. * - 0x4 - - \_\_be32 - - h\_blocktype + - __be32 + - h_blocktype - Description of what this block contains. See the jbd2_blocktype_ table below. * - 0x8 - - \_\_be32 - - h\_sequence + - __be32 + - h_sequence - The transaction ID that goes with this block. .. _jbd2_blocktype: @@ -177,99 +177,99 @@ which is 1024 bytes long: - - Static information describing the journal. * - 0x0 - - journal\_header\_t (12 bytes) - - s\_header + - journal_header_t (12 bytes) + - s_header - Common header identifying this as a superblock. * - 0xC - - \_\_be32 - - s\_blocksize + - __be32 + - s_blocksize - Journal device block size. * - 0x10 - - \_\_be32 - - s\_maxlen + - __be32 + - s_maxlen - Total number of blocks in this journal. * - 0x14 - - \_\_be32 - - s\_first + - __be32 + - s_first - First block of log information. * - - - - Dynamic information describing the current state of the log. * - 0x18 - - \_\_be32 - - s\_sequence + - __be32 + - s_sequence - First commit ID expected in log. * - 0x1C - - \_\_be32 - - s\_start + - __be32 + - s_start - Block number of the start of log. Contrary to the comments, this field being zero does not imply that the journal is clean! * - 0x20 - - \_\_be32 - - s\_errno - - Error value, as set by jbd2\_journal\_abort(). + - __be32 + - s_errno + - Error value, as set by jbd2_journal_abort(). * - - - - The remaining fields are only valid in a v2 superblock. * - 0x24 - - \_\_be32 - - s\_feature\_compat; + - __be32 + - s_feature_compat; - Compatible feature set. See the table jbd2_compat_ below. * - 0x28 - - \_\_be32 - - s\_feature\_incompat + - __be32 + - s_feature_incompat - Incompatible feature set. See the table jbd2_incompat_ below. * - 0x2C - - \_\_be32 - - s\_feature\_ro\_compat + - __be32 + - s_feature_ro_compat - Read-only compatible feature set. There aren't any of these currently. * - 0x30 - - \_\_u8 - - s\_uuid[16] + - __u8 + - s_uuid[16] - 128-bit uuid for journal. This is compared against the copy in the ext4 super block at mount time. * - 0x40 - - \_\_be32 - - s\_nr\_users + - __be32 + - s_nr_users - Number of file systems sharing this journal. * - 0x44 - - \_\_be32 - - s\_dynsuper + - __be32 + - s_dynsuper - Location of dynamic super block copy. (Not used?) * - 0x48 - - \_\_be32 - - s\_max\_transaction + - __be32 + - s_max_transaction - Limit of journal blocks per transaction. (Not used?) * - 0x4C - - \_\_be32 - - s\_max\_trans\_data + - __be32 + - s_max_trans_data - Limit of data blocks per transaction. (Not used?) * - 0x50 - - \_\_u8 - - s\_checksum\_type + - __u8 + - s_checksum_type - Checksum algorithm used for the journal. See jbd2_checksum_type_ for more info. * - 0x51 - - \_\_u8[3] - - s\_padding2 + - __u8[3] + - s_padding2 - * - 0x54 - - \_\_be32 - - s\_num\_fc\_blocks + - __be32 + - s_num_fc_blocks - Number of fast commit blocks in the journal. * - 0x58 - - \_\_u32 - - s\_padding[42] + - __u32 + - s_padding[42] - * - 0xFC - - \_\_be32 - - s\_checksum + - __be32 + - s_checksum - Checksum of the entire superblock, with this field set to zero. * - 0x100 - - \_\_u8 - - s\_users[16\*48] + - __u8 + - s_users[16*48] - ids of all file systems sharing the log. e2fsprogs/Linux don't allow shared external journals, but I imagine Lustre (or ocfs2?), which use the jbd2 code, might. @@ -286,7 +286,7 @@ The journal compat features are any combination of the following: - Description * - 0x1 - Journal maintains checksums on the data blocks. - (JBD2\_FEATURE\_COMPAT\_CHECKSUM) + (JBD2_FEATURE_COMPAT_CHECKSUM) .. _jbd2_incompat: @@ -299,23 +299,23 @@ The journal incompat features are any combination of the following: * - Value - Description * - 0x1 - - Journal has block revocation records. (JBD2\_FEATURE\_INCOMPAT\_REVOKE) + - Journal has block revocation records. (JBD2_FEATURE_INCOMPAT_REVOKE) * - 0x2 - Journal can deal with 64-bit block numbers. - (JBD2\_FEATURE\_INCOMPAT\_64BIT) + (JBD2_FEATURE_INCOMPAT_64BIT) * - 0x4 - - Journal commits asynchronously. (JBD2\_FEATURE\_INCOMPAT\_ASYNC\_COMMIT) + - Journal commits asynchronously. (JBD2_FEATURE_INCOMPAT_ASYNC_COMMIT) * - 0x8 - This journal uses v2 of the checksum on-disk format. Each journal metadata block gets its own checksum, and the block tags in the descriptor table contain checksums for each of the data blocks in the - journal. (JBD2\_FEATURE\_INCOMPAT\_CSUM\_V2) + journal. (JBD2_FEATURE_INCOMPAT_CSUM_V2) * - 0x10 - This journal uses v3 of the checksum on-disk format. This is the same as v2, but the journal block tag size is fixed regardless of the size of - block numbers. (JBD2\_FEATURE\_INCOMPAT\_CSUM\_V3) + block numbers. (JBD2_FEATURE_INCOMPAT_CSUM_V3) * - 0x20 - - Journal has fast commit blocks. (JBD2\_FEATURE\_INCOMPAT\_FAST\_COMMIT) + - Journal has fast commit blocks. (JBD2_FEATURE_INCOMPAT_FAST_COMMIT) .. _jbd2_checksum_type: @@ -355,11 +355,11 @@ Descriptor blocks consume at least 36 bytes, but use a full block: - Name - Descriptor * - 0x0 - - journal\_header\_t + - journal_header_t - (open coded) - Common block header. * - 0xC - - struct journal\_block\_tag\_s + - struct journal_block_tag_s - open coded array[] - Enough tags either to fill up the block or to describe all the data blocks that follow this descriptor block. @@ -367,7 +367,7 @@ Descriptor blocks consume at least 36 bytes, but use a full block: Journal block tags have any of the following formats, depending on which journal feature and block tag flags are set. -If JBD2\_FEATURE\_INCOMPAT\_CSUM\_V3 is set, the journal block tag is +If JBD2_FEATURE_INCOMPAT_CSUM_V3 is set, the journal block tag is defined as ``struct journal_block_tag3_s``, which looks like the following. The size is 16 or 32 bytes. @@ -380,24 +380,24 @@ following. The size is 16 or 32 bytes. - Name - Descriptor * - 0x0 - - \_\_be32 - - t\_blocknr + - __be32 + - t_blocknr - Lower 32-bits of the location of where the corresponding data block should end up on disk. * - 0x4 - - \_\_be32 - - t\_flags + - __be32 + - t_flags - Flags that go with the descriptor. See the table jbd2_tag_flags_ for more info. * - 0x8 - - \_\_be32 - - t\_blocknr\_high + - __be32 + - t_blocknr_high - Upper 32-bits of the location of where the corresponding data block - should end up on disk. This is zero if JBD2\_FEATURE\_INCOMPAT\_64BIT is + should end up on disk. This is zero if JBD2_FEATURE_INCOMPAT_64BIT is not enabled. * - 0xC - - \_\_be32 - - t\_checksum + - __be32 + - t_checksum - Checksum of the journal UUID, the sequence number, and the data block. * - - @@ -433,7 +433,7 @@ The journal tag flags are any combination of the following: * - 0x8 - This is the last tag in this descriptor block. -If JBD2\_FEATURE\_INCOMPAT\_CSUM\_V3 is NOT set, the journal block tag +If JBD2_FEATURE_INCOMPAT_CSUM_V3 is NOT set, the journal block tag is defined as ``struct journal_block_tag_s``, which looks like the following. The size is 8, 12, 24, or 28 bytes: @@ -446,18 +446,18 @@ following. The size is 8, 12, 24, or 28 bytes: - Name - Descriptor * - 0x0 - - \_\_be32 - - t\_blocknr + - __be32 + - t_blocknr - Lower 32-bits of the location of where the corresponding data block should end up on disk. * - 0x4 - - \_\_be16 - - t\_checksum + - __be16 + - t_checksum - Checksum of the journal UUID, the sequence number, and the data block. Note that only the lower 16 bits are stored. * - 0x6 - - \_\_be16 - - t\_flags + - __be16 + - t_flags - Flags that go with the descriptor. See the table jbd2_tag_flags_ for more info. * - @@ -466,8 +466,8 @@ following. The size is 8, 12, 24, or 28 bytes: - This next field is only present if the super block indicates support for 64-bit block numbers. * - 0x8 - - \_\_be32 - - t\_blocknr\_high + - __be32 + - t_blocknr_high - Upper 32-bits of the location of where the corresponding data block should end up on disk. * - @@ -483,8 +483,8 @@ following. The size is 8, 12, 24, or 28 bytes: ``j_uuid`` field in ``struct journal_s``, but only tune2fs touches that field. -If JBD2\_FEATURE\_INCOMPAT\_CSUM\_V2 or -JBD2\_FEATURE\_INCOMPAT\_CSUM\_V3 are set, the end of the block is a +If JBD2_FEATURE_INCOMPAT_CSUM_V2 or +JBD2_FEATURE_INCOMPAT_CSUM_V3 are set, the end of the block is a ``struct jbd2_journal_block_tail``, which looks like this: .. list-table:: @@ -496,8 +496,8 @@ JBD2\_FEATURE\_INCOMPAT\_CSUM\_V3 are set, the end of the block is a - Name - Descriptor * - 0x0 - - \_\_be32 - - t\_checksum + - __be32 + - t_checksum - Checksum of the journal UUID + the descriptor block, with this field set to zero. @@ -538,25 +538,25 @@ length, but use a full block: - Name - Description * - 0x0 - - journal\_header\_t - - r\_header + - journal_header_t + - r_header - Common block header. * - 0xC - - \_\_be32 - - r\_count + - __be32 + - r_count - Number of bytes used in this block. * - 0x10 - - \_\_be32 or \_\_be64 + - __be32 or __be64 - blocks[0] - Blocks to revoke. -After r\_count is a linear array of block numbers that are effectively +After r_count is a linear array of block numbers that are effectively revoked by this transaction. The size of each block number is 8 bytes if the superblock advertises 64-bit block number support, or 4 bytes otherwise. -If JBD2\_FEATURE\_INCOMPAT\_CSUM\_V2 or -JBD2\_FEATURE\_INCOMPAT\_CSUM\_V3 are set, the end of the revocation +If JBD2_FEATURE_INCOMPAT_CSUM_V2 or +JBD2_FEATURE_INCOMPAT_CSUM_V3 are set, the end of the revocation block is a ``struct jbd2_journal_revoke_tail``, which has this format: .. list-table:: @@ -568,8 +568,8 @@ block is a ``struct jbd2_journal_revoke_tail``, which has this format: - Name - Description * - 0x0 - - \_\_be32 - - r\_checksum + - __be32 + - r_checksum - Checksum of the journal UUID + revocation block Commit Block @@ -592,38 +592,38 @@ bytes long (but uses a full block): - Name - Descriptor * - 0x0 - - journal\_header\_s + - journal_header_s - (open coded) - Common block header. * - 0xC - unsigned char - - h\_chksum\_type + - h_chksum_type - The type of checksum to use to verify the integrity of the data blocks in the transaction. See jbd2_checksum_type_ for more info. * - 0xD - unsigned char - - h\_chksum\_size + - h_chksum_size - The number of bytes used by the checksum. Most likely 4. * - 0xE - unsigned char - - h\_padding[2] + - h_padding[2] - * - 0x10 - - \_\_be32 - - h\_chksum[JBD2\_CHECKSUM\_BYTES] + - __be32 + - h_chksum[JBD2_CHECKSUM_BYTES] - 32 bytes of space to store checksums. If - JBD2\_FEATURE\_INCOMPAT\_CSUM\_V2 or JBD2\_FEATURE\_INCOMPAT\_CSUM\_V3 + JBD2_FEATURE_INCOMPAT_CSUM_V2 or JBD2_FEATURE_INCOMPAT_CSUM_V3 are set, the first ``__be32`` is the checksum of the journal UUID and the entire commit block, with this field zeroed. If - JBD2\_FEATURE\_COMPAT\_CHECKSUM is set, the first ``__be32`` is the + JBD2_FEATURE_COMPAT_CHECKSUM is set, the first ``__be32`` is the crc32 of all the blocks already written to the transaction. * - 0x30 - - \_\_be64 - - h\_commit\_sec + - __be64 + - h_commit_sec - The time that the transaction was committed, in seconds since the epoch. * - 0x38 - - \_\_be32 - - h\_commit\_nsec + - __be32 + - h_commit_nsec - Nanoseconds component of the above timestamp. Fast commits diff --git a/Documentation/filesystems/ext4/mmp.rst b/Documentation/filesystems/ext4/mmp.rst index 25660981d93c..174dd6538737 100644 --- a/Documentation/filesystems/ext4/mmp.rst +++ b/Documentation/filesystems/ext4/mmp.rst @@ -7,8 +7,8 @@ Multiple mount protection (MMP) is a feature that protects the filesystem against multiple hosts trying to use the filesystem simultaneously. When a filesystem is opened (for mounting, or fsck, etc.), the MMP code running on the node (call it node A) checks a -sequence number. If the sequence number is EXT4\_MMP\_SEQ\_CLEAN, the -open continues. If the sequence number is EXT4\_MMP\_SEQ\_FSCK, then +sequence number. If the sequence number is EXT4_MMP_SEQ_CLEAN, the +open continues. If the sequence number is EXT4_MMP_SEQ_FSCK, then fsck is (hopefully) running, and open fails immediately. Otherwise, the open code will wait for twice the specified MMP check interval and check the sequence number again. If the sequence number has changed, then the @@ -40,38 +40,38 @@ The MMP structure (``struct mmp_struct``) is as follows: - Name - Description * - 0x0 - - \_\_le32 - - mmp\_magic + - __le32 + - mmp_magic - Magic number for MMP, 0x004D4D50 (“MMPâ€). * - 0x4 - - \_\_le32 - - mmp\_seq + - __le32 + - mmp_seq - Sequence number, updated periodically. * - 0x8 - - \_\_le64 - - mmp\_time + - __le64 + - mmp_time - Time that the MMP block was last updated. * - 0x10 - char[64] - - mmp\_nodename + - mmp_nodename - Hostname of the node that opened the filesystem. * - 0x50 - char[32] - - mmp\_bdevname + - mmp_bdevname - Block device name of the filesystem. * - 0x70 - - \_\_le16 - - mmp\_check\_interval + - __le16 + - mmp_check_interval - The MMP re-check interval, in seconds. * - 0x72 - - \_\_le16 - - mmp\_pad1 + - __le16 + - mmp_pad1 - Zero. * - 0x74 - - \_\_le32[226] - - mmp\_pad2 + - __le32[226] + - mmp_pad2 - Zero. * - 0x3FC - - \_\_le32 - - mmp\_checksum + - __le32 + - mmp_checksum - Checksum of the MMP block. diff --git a/Documentation/filesystems/ext4/overview.rst b/Documentation/filesystems/ext4/overview.rst index 123ebfde47ee..0fad6eda6e15 100644 --- a/Documentation/filesystems/ext4/overview.rst +++ b/Documentation/filesystems/ext4/overview.rst @@ -7,7 +7,7 @@ An ext4 file system is split into a series of block groups. To reduce performance difficulties due to fragmentation, the block allocator tries very hard to keep each file's blocks within the same group, thereby reducing seek times. The size of a block group is specified in -``sb.s_blocks_per_group`` blocks, though it can also calculated as 8 \* +``sb.s_blocks_per_group`` blocks, though it can also calculated as 8 * ``block_size_in_bytes``. With the default block size of 4KiB, each group will contain 32,768 blocks, for a length of 128MiB. The number of block groups is the size of the device divided by the size of a block group. diff --git a/Documentation/filesystems/ext4/special_inodes.rst b/Documentation/filesystems/ext4/special_inodes.rst index 94f304e3a0a7..fc0636901fa0 100644 --- a/Documentation/filesystems/ext4/special_inodes.rst +++ b/Documentation/filesystems/ext4/special_inodes.rst @@ -34,7 +34,7 @@ ext4 reserves some inode for special features, as follows: * - 10 - Replica inode, used for some non-upstream feature? * - 11 - - Traditional first non-reserved inode. Usually this is the lost+found directory. See s\_first\_ino in the superblock. + - Traditional first non-reserved inode. Usually this is the lost+found directory. See s_first_ino in the superblock. Note that there are also some inodes allocated from non-reserved inode numbers for other filesystem features which are not referenced from standard directory @@ -47,9 +47,9 @@ hierarchy. These are generally reference from the superblock. They are: * - Superblock field - Description - * - s\_lpf\_ino + * - s_lpf_ino - Inode number of lost+found directory. - * - s\_prj\_quota\_inum + * - s_prj_quota_inum - Inode number of quota file tracking project quotas - * - s\_orphan\_file\_inum + * - s_orphan_file_inum - Inode number of file tracking orphan inodes. diff --git a/Documentation/filesystems/ext4/super.rst b/Documentation/filesystems/ext4/super.rst index f6a548e957bb..268888522e35 100644 --- a/Documentation/filesystems/ext4/super.rst +++ b/Documentation/filesystems/ext4/super.rst @@ -7,7 +7,7 @@ The superblock records various information about the enclosing filesystem, such as block counts, inode counts, supported features, maintenance information, and more. -If the sparse\_super feature flag is set, redundant copies of the +If the sparse_super feature flag is set, redundant copies of the superblock and group descriptors are kept only in the groups whose group number is either 0 or a power of 3, 5, or 7. If the flag is not set, redundant copies are kept in all groups. @@ -27,107 +27,107 @@ The ext4 superblock is laid out as follows in - Name - Description * - 0x0 - - \_\_le32 - - s\_inodes\_count + - __le32 + - s_inodes_count - Total inode count. * - 0x4 - - \_\_le32 - - s\_blocks\_count\_lo + - __le32 + - s_blocks_count_lo - Total block count. * - 0x8 - - \_\_le32 - - s\_r\_blocks\_count\_lo + - __le32 + - s_r_blocks_count_lo - This number of blocks can only be allocated by the super-user. * - 0xC - - \_\_le32 - - s\_free\_blocks\_count\_lo + - __le32 + - s_free_blocks_count_lo - Free block count. * - 0x10 - - \_\_le32 - - s\_free\_inodes\_count + - __le32 + - s_free_inodes_count - Free inode count. * - 0x14 - - \_\_le32 - - s\_first\_data\_block + - __le32 + - s_first_data_block - First data block. This must be at least 1 for 1k-block filesystems and is typically 0 for all other block sizes. * - 0x18 - - \_\_le32 - - s\_log\_block\_size - - Block size is 2 ^ (10 + s\_log\_block\_size). + - __le32 + - s_log_block_size + - Block size is 2 ^ (10 + s_log_block_size). * - 0x1C - - \_\_le32 - - s\_log\_cluster\_size - - Cluster size is 2 ^ (10 + s\_log\_cluster\_size) blocks if bigalloc is - enabled. Otherwise s\_log\_cluster\_size must equal s\_log\_block\_size. + - __le32 + - s_log_cluster_size + - Cluster size is 2 ^ (10 + s_log_cluster_size) blocks if bigalloc is + enabled. Otherwise s_log_cluster_size must equal s_log_block_size. * - 0x20 - - \_\_le32 - - s\_blocks\_per\_group + - __le32 + - s_blocks_per_group - Blocks per group. * - 0x24 - - \_\_le32 - - s\_clusters\_per\_group + - __le32 + - s_clusters_per_group - Clusters per group, if bigalloc is enabled. Otherwise - s\_clusters\_per\_group must equal s\_blocks\_per\_group. + s_clusters_per_group must equal s_blocks_per_group. * - 0x28 - - \_\_le32 - - s\_inodes\_per\_group + - __le32 + - s_inodes_per_group - Inodes per group. * - 0x2C - - \_\_le32 - - s\_mtime + - __le32 + - s_mtime - Mount time, in seconds since the epoch. * - 0x30 - - \_\_le32 - - s\_wtime + - __le32 + - s_wtime - Write time, in seconds since the epoch. * - 0x34 - - \_\_le16 - - s\_mnt\_count + - __le16 + - s_mnt_count - Number of mounts since the last fsck. * - 0x36 - - \_\_le16 - - s\_max\_mnt\_count + - __le16 + - s_max_mnt_count - Number of mounts beyond which a fsck is needed. * - 0x38 - - \_\_le16 - - s\_magic + - __le16 + - s_magic - Magic signature, 0xEF53 * - 0x3A - - \_\_le16 - - s\_state + - __le16 + - s_state - File system state. See super_state_ for more info. * - 0x3C - - \_\_le16 - - s\_errors + - __le16 + - s_errors - Behaviour when detecting errors. See super_errors_ for more info. * - 0x3E - - \_\_le16 - - s\_minor\_rev\_level + - __le16 + - s_minor_rev_level - Minor revision level. * - 0x40 - - \_\_le32 - - s\_lastcheck + - __le32 + - s_lastcheck - Time of last check, in seconds since the epoch. * - 0x44 - - \_\_le32 - - s\_checkinterval + - __le32 + - s_checkinterval - Maximum time between checks, in seconds. * - 0x48 - - \_\_le32 - - s\_creator\_os + - __le32 + - s_creator_os - Creator OS. See the table super_creator_ for more info. * - 0x4C - - \_\_le32 - - s\_rev\_level + - __le32 + - s_rev_level - Revision level. See the table super_revision_ for more info. * - 0x50 - - \_\_le16 - - s\_def\_resuid + - __le16 + - s_def_resuid - Default uid for reserved blocks. * - 0x52 - - \_\_le16 - - s\_def\_resgid + - __le16 + - s_def_resgid - Default gid for reserved blocks. * - - @@ -143,50 +143,50 @@ The ext4 superblock is laid out as follows in about a feature in either the compatible or incompatible feature set, it must abort and not try to meddle with things it doesn't understand... * - 0x54 - - \_\_le32 - - s\_first\_ino + - __le32 + - s_first_ino - First non-reserved inode. * - 0x58 - - \_\_le16 - - s\_inode\_size + - __le16 + - s_inode_size - Size of inode structure, in bytes. * - 0x5A - - \_\_le16 - - s\_block\_group\_nr + - __le16 + - s_block_group_nr - Block group # of this superblock. * - 0x5C - - \_\_le32 - - s\_feature\_compat + - __le32 + - s_feature_compat - Compatible feature set flags. Kernel can still read/write this fs even if it doesn't understand a flag; fsck should not do that. See the super_compat_ table for more info. * - 0x60 - - \_\_le32 - - s\_feature\_incompat + - __le32 + - s_feature_incompat - Incompatible feature set. If the kernel or fsck doesn't understand one of these bits, it should stop. See the super_incompat_ table for more info. * - 0x64 - - \_\_le32 - - s\_feature\_ro\_compat + - __le32 + - s_feature_ro_compat - Readonly-compatible feature set. If the kernel doesn't understand one of these bits, it can still mount read-only. See the super_rocompat_ table for more info. * - 0x68 - - \_\_u8 - - s\_uuid[16] + - __u8 + - s_uuid[16] - 128-bit UUID for volume. * - 0x78 - char - - s\_volume\_name[16] + - s_volume_name[16] - Volume label. * - 0x88 - char - - s\_last\_mounted[64] + - s_last_mounted[64] - Directory where filesystem was last mounted. * - 0xC8 - - \_\_le32 - - s\_algorithm\_usage\_bitmap + - __le32 + - s_algorithm_usage_bitmap - For compression (Not used in e2fsprogs/Linux) * - - @@ -194,18 +194,18 @@ The ext4 superblock is laid out as follows in - Performance hints. Directory preallocation should only happen if the EXT4_FEATURE_COMPAT_DIR_PREALLOC flag is on. * - 0xCC - - \_\_u8 - - s\_prealloc\_blocks + - __u8 + - s_prealloc_blocks - #. of blocks to try to preallocate for ... files? (Not used in e2fsprogs/Linux) * - 0xCD - - \_\_u8 - - s\_prealloc\_dir\_blocks + - __u8 + - s_prealloc_dir_blocks - #. of blocks to preallocate for directories. (Not used in e2fsprogs/Linux) * - 0xCE - - \_\_le16 - - s\_reserved\_gdt\_blocks + - __le16 + - s_reserved_gdt_blocks - Number of reserved GDT entries for future filesystem expansion. * - - @@ -213,281 +213,281 @@ The ext4 superblock is laid out as follows in - Journalling support is valid only if EXT4_FEATURE_COMPAT_HAS_JOURNAL is set. * - 0xD0 - - \_\_u8 - - s\_journal\_uuid[16] + - __u8 + - s_journal_uuid[16] - UUID of journal superblock * - 0xE0 - - \_\_le32 - - s\_journal\_inum + - __le32 + - s_journal_inum - inode number of journal file. * - 0xE4 - - \_\_le32 - - s\_journal\_dev + - __le32 + - s_journal_dev - Device number of journal file, if the external journal feature flag is set. * - 0xE8 - - \_\_le32 - - s\_last\_orphan + - __le32 + - s_last_orphan - Start of list of orphaned inodes to delete. * - 0xEC - - \_\_le32 - - s\_hash\_seed[4] + - __le32 + - s_hash_seed[4] - HTREE hash seed. * - 0xFC - - \_\_u8 - - s\_def\_hash\_version + - __u8 + - s_def_hash_version - Default hash algorithm to use for directory hashes. See super_def_hash_ for more info. * - 0xFD - - \_\_u8 - - s\_jnl\_backup\_type - - If this value is 0 or EXT3\_JNL\_BACKUP\_BLOCKS (1), then the + - __u8 + - s_jnl_backup_type + - If this value is 0 or EXT3_JNL_BACKUP_BLOCKS (1), then the ``s_jnl_blocks`` field contains a duplicate copy of the inode's ``i_block[]`` array and ``i_size``. * - 0xFE - - \_\_le16 - - s\_desc\_size + - __le16 + - s_desc_size - Size of group descriptors, in bytes, if the 64bit incompat feature flag is set. * - 0x100 - - \_\_le32 - - s\_default\_mount\_opts + - __le32 + - s_default_mount_opts - Default mount options. See the super_mountopts_ table for more info. * - 0x104 - - \_\_le32 - - s\_first\_meta\_bg - - First metablock block group, if the meta\_bg feature is enabled. + - __le32 + - s_first_meta_bg + - First metablock block group, if the meta_bg feature is enabled. * - 0x108 - - \_\_le32 - - s\_mkfs\_time + - __le32 + - s_mkfs_time - When the filesystem was created, in seconds since the epoch. * - 0x10C - - \_\_le32 - - s\_jnl\_blocks[17] + - __le32 + - s_jnl_blocks[17] - Backup copy of the journal inode's ``i_block[]`` array in the first 15 - elements and i\_size\_high and i\_size in the 16th and 17th elements, + elements and i_size_high and i_size in the 16th and 17th elements, respectively. * - - - - 64bit support is valid only if EXT4_FEATURE_COMPAT_64BIT is set. * - 0x150 - - \_\_le32 - - s\_blocks\_count\_hi + - __le32 + - s_blocks_count_hi - High 32-bits of the block count. * - 0x154 - - \_\_le32 - - s\_r\_blocks\_count\_hi + - __le32 + - s_r_blocks_count_hi - High 32-bits of the reserved block count. * - 0x158 - - \_\_le32 - - s\_free\_blocks\_count\_hi + - __le32 + - s_free_blocks_count_hi - High 32-bits of the free block count. * - 0x15C - - \_\_le16 - - s\_min\_extra\_isize + - __le16 + - s_min_extra_isize - All inodes have at least # bytes. * - 0x15E - - \_\_le16 - - s\_want\_extra\_isize + - __le16 + - s_want_extra_isize - New inodes should reserve # bytes. * - 0x160 - - \_\_le32 - - s\_flags + - __le32 + - s_flags - Miscellaneous flags. See the super_flags_ table for more info. * - 0x164 - - \_\_le16 - - s\_raid\_stride + - __le16 + - s_raid_stride - RAID stride. This is the number of logical blocks read from or written to the disk before moving to the next disk. This affects the placement of filesystem metadata, which will hopefully make RAID storage faster. * - 0x166 - - \_\_le16 - - s\_mmp\_interval + - __le16 + - s_mmp_interval - #. seconds to wait in multi-mount prevention (MMP) checking. In theory, MMP is a mechanism to record in the superblock which host and device have mounted the filesystem, in order to prevent multiple mounts. This feature does not seem to be implemented... * - 0x168 - - \_\_le64 - - s\_mmp\_block + - __le64 + - s_mmp_block - Block # for multi-mount protection data. * - 0x170 - - \_\_le32 - - s\_raid\_stripe\_width + - __le32 + - s_raid_stripe_width - RAID stripe width. This is the number of logical blocks read from or written to the disk before coming back to the current disk. This is used by the block allocator to try to reduce the number of read-modify-write operations in a RAID5/6. * - 0x174 - - \_\_u8 - - s\_log\_groups\_per\_flex + - __u8 + - s_log_groups_per_flex - Size of a flexible block group is 2 ^ ``s_log_groups_per_flex``. * - 0x175 - - \_\_u8 - - s\_checksum\_type + - __u8 + - s_checksum_type - Metadata checksum algorithm type. The only valid value is 1 (crc32c). * - 0x176 - - \_\_le16 - - s\_reserved\_pad + - __le16 + - s_reserved_pad - * - 0x178 - - \_\_le64 - - s\_kbytes\_written + - __le64 + - s_kbytes_written - Number of KiB written to this filesystem over its lifetime. * - 0x180 - - \_\_le32 - - s\_snapshot\_inum + - __le32 + - s_snapshot_inum - inode number of active snapshot. (Not used in e2fsprogs/Linux.) * - 0x184 - - \_\_le32 - - s\_snapshot\_id + - __le32 + - s_snapshot_id - Sequential ID of active snapshot. (Not used in e2fsprogs/Linux.) * - 0x188 - - \_\_le64 - - s\_snapshot\_r\_blocks\_count + - __le64 + - s_snapshot_r_blocks_count - Number of blocks reserved for active snapshot's future use. (Not used in e2fsprogs/Linux.) * - 0x190 - - \_\_le32 - - s\_snapshot\_list + - __le32 + - s_snapshot_list - inode number of the head of the on-disk snapshot list. (Not used in e2fsprogs/Linux.) * - 0x194 - - \_\_le32 - - s\_error\_count + - __le32 + - s_error_count - Number of errors seen. * - 0x198 - - \_\_le32 - - s\_first\_error\_time + - __le32 + - s_first_error_time - First time an error happened, in seconds since the epoch. * - 0x19C - - \_\_le32 - - s\_first\_error\_ino + - __le32 + - s_first_error_ino - inode involved in first error. * - 0x1A0 - - \_\_le64 - - s\_first\_error\_block + - __le64 + - s_first_error_block - Number of block involved of first error. * - 0x1A8 - - \_\_u8 - - s\_first\_error\_func[32] + - __u8 + - s_first_error_func[32] - Name of function where the error happened. * - 0x1C8 - - \_\_le32 - - s\_first\_error\_line + - __le32 + - s_first_error_line - Line number where error happened. * - 0x1CC - - \_\_le32 - - s\_last\_error\_time + - __le32 + - s_last_error_time - Time of most recent error, in seconds since the epoch. * - 0x1D0 - - \_\_le32 - - s\_last\_error\_ino + - __le32 + - s_last_error_ino - inode involved in most recent error. * - 0x1D4 - - \_\_le32 - - s\_last\_error\_line + - __le32 + - s_last_error_line - Line number where most recent error happened. * - 0x1D8 - - \_\_le64 - - s\_last\_error\_block + - __le64 + - s_last_error_block - Number of block involved in most recent error. * - 0x1E0 - - \_\_u8 - - s\_last\_error\_func[32] + - __u8 + - s_last_error_func[32] - Name of function where the most recent error happened. * - 0x200 - - \_\_u8 - - s\_mount\_opts[64] + - __u8 + - s_mount_opts[64] - ASCIIZ string of mount options. * - 0x240 - - \_\_le32 - - s\_usr\_quota\_inum + - __le32 + - s_usr_quota_inum - Inode number of user `quota <quota>`__ file. * - 0x244 - - \_\_le32 - - s\_grp\_quota\_inum + - __le32 + - s_grp_quota_inum - Inode number of group `quota <quota>`__ file. * - 0x248 - - \_\_le32 - - s\_overhead\_blocks + - __le32 + - s_overhead_blocks - Overhead blocks/clusters in fs. (Huh? This field is always zero, which means that the kernel calculates it dynamically.) * - 0x24C - - \_\_le32 - - s\_backup\_bgs[2] - - Block groups containing superblock backups (if sparse\_super2) + - __le32 + - s_backup_bgs[2] + - Block groups containing superblock backups (if sparse_super2) * - 0x254 - - \_\_u8 - - s\_encrypt\_algos[4] + - __u8 + - s_encrypt_algos[4] - Encryption algorithms in use. There can be up to four algorithms in use at any time; valid algorithm codes are given in the super_encrypt_ table below. * - 0x258 - - \_\_u8 - - s\_encrypt\_pw\_salt[16] + - __u8 + - s_encrypt_pw_salt[16] - Salt for the string2key algorithm for encryption. * - 0x268 - - \_\_le32 - - s\_lpf\_ino + - __le32 + - s_lpf_ino - Inode number of lost+found * - 0x26C - - \_\_le32 - - s\_prj\_quota\_inum + - __le32 + - s_prj_quota_inum - Inode that tracks project quotas. * - 0x270 - - \_\_le32 - - s\_checksum\_seed - - Checksum seed used for metadata\_csum calculations. This value is - crc32c(~0, $orig\_fs\_uuid). + - __le32 + - s_checksum_seed + - Checksum seed used for metadata_csum calculations. This value is + crc32c(~0, $orig_fs_uuid). * - 0x274 - - \_\_u8 - - s\_wtime_hi + - __u8 + - s_wtime_hi - Upper 8 bits of the s_wtime field. * - 0x275 - - \_\_u8 - - s\_mtime_hi + - __u8 + - s_mtime_hi - Upper 8 bits of the s_mtime field. * - 0x276 - - \_\_u8 - - s\_mkfs_time_hi + - __u8 + - s_mkfs_time_hi - Upper 8 bits of the s_mkfs_time field. * - 0x277 - - \_\_u8 - - s\_lastcheck_hi + - __u8 + - s_lastcheck_hi - Upper 8 bits of the s_lastcheck_hi field. * - 0x278 - - \_\_u8 - - s\_first_error_time_hi + - __u8 + - s_first_error_time_hi - Upper 8 bits of the s_first_error_time_hi field. * - 0x279 - - \_\_u8 - - s\_last_error_time_hi + - __u8 + - s_last_error_time_hi - Upper 8 bits of the s_last_error_time_hi field. * - 0x27A - - \_\_u8 - - s\_pad[2] + - __u8 + - s_pad[2] - Zero padding. * - 0x27C - - \_\_le16 - - s\_encoding + - __le16 + - s_encoding - Filename charset encoding. * - 0x27E - - \_\_le16 - - s\_encoding_flags + - __le16 + - s_encoding_flags - Filename charset encoding flags. * - 0x280 - - \_\_le32 - - s\_orphan\_file\_inum + - __le32 + - s_orphan_file_inum - Orphan file inode number. * - 0x284 - - \_\_le32 - - s\_reserved[94] + - __le32 + - s_reserved[94] - Padding to the end of the block. * - 0x3FC - - \_\_le32 - - s\_checksum + - __le32 + - s_checksum - Superblock checksum. .. _super_state: @@ -574,44 +574,44 @@ following: * - Value - Description * - 0x1 - - Directory preallocation (COMPAT\_DIR\_PREALLOC). + - Directory preallocation (COMPAT_DIR_PREALLOC). * - 0x2 - “imagic inodesâ€. Not clear from the code what this does - (COMPAT\_IMAGIC\_INODES). + (COMPAT_IMAGIC_INODES). * - 0x4 - - Has a journal (COMPAT\_HAS\_JOURNAL). + - Has a journal (COMPAT_HAS_JOURNAL). * - 0x8 - - Supports extended attributes (COMPAT\_EXT\_ATTR). + - Supports extended attributes (COMPAT_EXT_ATTR). * - 0x10 - Has reserved GDT blocks for filesystem expansion - (COMPAT\_RESIZE\_INODE). Requires RO\_COMPAT\_SPARSE\_SUPER. + (COMPAT_RESIZE_INODE). Requires RO_COMPAT_SPARSE_SUPER. * - 0x20 - - Has directory indices (COMPAT\_DIR\_INDEX). + - Has directory indices (COMPAT_DIR_INDEX). * - 0x40 - “Lazy BGâ€. Not in Linux kernel, seems to have been for uninitialized - block groups? (COMPAT\_LAZY\_BG) + block groups? (COMPAT_LAZY_BG) * - 0x80 - - “Exclude inodeâ€. Not used. (COMPAT\_EXCLUDE\_INODE). + - “Exclude inodeâ€. Not used. (COMPAT_EXCLUDE_INODE). * - 0x100 - “Exclude bitmapâ€. Seems to be used to indicate the presence of snapshot-related exclude bitmaps? Not defined in kernel or used in - e2fsprogs (COMPAT\_EXCLUDE\_BITMAP). + e2fsprogs (COMPAT_EXCLUDE_BITMAP). * - 0x200 - - Sparse Super Block, v2. If this flag is set, the SB field s\_backup\_bgs + - Sparse Super Block, v2. If this flag is set, the SB field s_backup_bgs points to the two block groups that contain backup superblocks - (COMPAT\_SPARSE\_SUPER2). + (COMPAT_SPARSE_SUPER2). * - 0x400 - Fast commits supported. Although fast commits blocks are backward incompatible, fast commit blocks are not always present in the journal. If fast commit blocks are present in the journal, JBD2 incompat feature - (JBD2\_FEATURE\_INCOMPAT\_FAST\_COMMIT) gets - set (COMPAT\_FAST\_COMMIT). + (JBD2_FEATURE_INCOMPAT_FAST_COMMIT) gets + set (COMPAT_FAST_COMMIT). * - 0x1000 - Orphan file allocated. This is the special file for more efficient tracking of unlinked but still open inodes. When there may be any entries in the file, we additionally set proper rocompat feature - (RO\_COMPAT\_ORPHAN\_PRESENT). + (RO_COMPAT_ORPHAN_PRESENT). .. _super_incompat: @@ -625,45 +625,45 @@ following: * - Value - Description * - 0x1 - - Compression (INCOMPAT\_COMPRESSION). + - Compression (INCOMPAT_COMPRESSION). * - 0x2 - - Directory entries record the file type. See ext4\_dir\_entry\_2 below - (INCOMPAT\_FILETYPE). + - Directory entries record the file type. See ext4_dir_entry_2 below + (INCOMPAT_FILETYPE). * - 0x4 - - Filesystem needs recovery (INCOMPAT\_RECOVER). + - Filesystem needs recovery (INCOMPAT_RECOVER). * - 0x8 - - Filesystem has a separate journal device (INCOMPAT\_JOURNAL\_DEV). + - Filesystem has a separate journal device (INCOMPAT_JOURNAL_DEV). * - 0x10 - Meta block groups. See the earlier discussion of this feature - (INCOMPAT\_META\_BG). + (INCOMPAT_META_BG). * - 0x40 - - Files in this filesystem use extents (INCOMPAT\_EXTENTS). + - Files in this filesystem use extents (INCOMPAT_EXTENTS). * - 0x80 - - Enable a filesystem size of 2^64 blocks (INCOMPAT\_64BIT). + - Enable a filesystem size of 2^64 blocks (INCOMPAT_64BIT). * - 0x100 - - Multiple mount protection (INCOMPAT\_MMP). + - Multiple mount protection (INCOMPAT_MMP). * - 0x200 - Flexible block groups. See the earlier discussion of this feature - (INCOMPAT\_FLEX\_BG). + (INCOMPAT_FLEX_BG). * - 0x400 - Inodes can be used to store large extended attribute values - (INCOMPAT\_EA\_INODE). + (INCOMPAT_EA_INODE). * - 0x1000 - - Data in directory entry (INCOMPAT\_DIRDATA). (Not implemented?) + - Data in directory entry (INCOMPAT_DIRDATA). (Not implemented?) * - 0x2000 - Metadata checksum seed is stored in the superblock. This feature enables - the administrator to change the UUID of a metadata\_csum filesystem + the administrator to change the UUID of a metadata_csum filesystem while the filesystem is mounted; without it, the checksum definition - requires all metadata blocks to be rewritten (INCOMPAT\_CSUM\_SEED). + requires all metadata blocks to be rewritten (INCOMPAT_CSUM_SEED). * - 0x4000 - - Large directory >2GB or 3-level htree (INCOMPAT\_LARGEDIR). Prior to + - Large directory >2GB or 3-level htree (INCOMPAT_LARGEDIR). Prior to this feature, directories could not be larger than 4GiB and could not have an htree more than 2 levels deep. If this feature is enabled, directories can be larger than 4GiB and have a maximum htree depth of 3. * - 0x8000 - - Data in inode (INCOMPAT\_INLINE\_DATA). + - Data in inode (INCOMPAT_INLINE_DATA). * - 0x10000 - - Encrypted inodes are present on the filesystem. (INCOMPAT\_ENCRYPT). + - Encrypted inodes are present on the filesystem. (INCOMPAT_ENCRYPT). .. _super_rocompat: @@ -678,54 +678,54 @@ the following: - Description * - 0x1 - Sparse superblocks. See the earlier discussion of this feature - (RO\_COMPAT\_SPARSE\_SUPER). + (RO_COMPAT_SPARSE_SUPER). * - 0x2 - This filesystem has been used to store a file greater than 2GiB - (RO\_COMPAT\_LARGE\_FILE). + (RO_COMPAT_LARGE_FILE). * - 0x4 - - Not used in kernel or e2fsprogs (RO\_COMPAT\_BTREE\_DIR). + - Not used in kernel or e2fsprogs (RO_COMPAT_BTREE_DIR). * - 0x8 - This filesystem has files whose sizes are represented in units of logical blocks, not 512-byte sectors. This implies a very large file - indeed! (RO\_COMPAT\_HUGE\_FILE) + indeed! (RO_COMPAT_HUGE_FILE) * - 0x10 - Group descriptors have checksums. In addition to detecting corruption, this is useful for lazy formatting with uninitialized groups - (RO\_COMPAT\_GDT\_CSUM). + (RO_COMPAT_GDT_CSUM). * - 0x20 - Indicates that the old ext3 32,000 subdirectory limit no longer applies - (RO\_COMPAT\_DIR\_NLINK). A directory's i\_links\_count will be set to 1 + (RO_COMPAT_DIR_NLINK). A directory's i_links_count will be set to 1 if it is incremented past 64,999. * - 0x40 - Indicates that large inodes exist on this filesystem - (RO\_COMPAT\_EXTRA\_ISIZE). + (RO_COMPAT_EXTRA_ISIZE). * - 0x80 - - This filesystem has a snapshot (RO\_COMPAT\_HAS\_SNAPSHOT). + - This filesystem has a snapshot (RO_COMPAT_HAS_SNAPSHOT). * - 0x100 - - `Quota <Quota>`__ (RO\_COMPAT\_QUOTA). + - `Quota <Quota>`__ (RO_COMPAT_QUOTA). * - 0x200 - This filesystem supports “bigallocâ€, which means that file extents are tracked in units of clusters (of blocks) instead of blocks - (RO\_COMPAT\_BIGALLOC). + (RO_COMPAT_BIGALLOC). * - 0x400 - This filesystem supports metadata checksumming. - (RO\_COMPAT\_METADATA\_CSUM; implies RO\_COMPAT\_GDT\_CSUM, though - GDT\_CSUM must not be set) + (RO_COMPAT_METADATA_CSUM; implies RO_COMPAT_GDT_CSUM, though + GDT_CSUM must not be set) * - 0x800 - Filesystem supports replicas. This feature is neither in the kernel nor - e2fsprogs. (RO\_COMPAT\_REPLICA) + e2fsprogs. (RO_COMPAT_REPLICA) * - 0x1000 - Read-only filesystem image; the kernel will not mount this image read-write and most tools will refuse to write to the image. - (RO\_COMPAT\_READONLY) + (RO_COMPAT_READONLY) * - 0x2000 - - Filesystem tracks project quotas. (RO\_COMPAT\_PROJECT) + - Filesystem tracks project quotas. (RO_COMPAT_PROJECT) * - 0x8000 - - Verity inodes may be present on the filesystem. (RO\_COMPAT\_VERITY) + - Verity inodes may be present on the filesystem. (RO_COMPAT_VERITY) * - 0x10000 - Indicates orphan file may have valid orphan entries and thus we need to clean them up when mounting the filesystem - (RO\_COMPAT\_ORPHAN\_PRESENT). + (RO_COMPAT_ORPHAN_PRESENT). .. _super_def_hash: @@ -761,36 +761,36 @@ The ``s_default_mount_opts`` field is any combination of the following: * - Value - Description * - 0x0001 - - Print debugging info upon (re)mount. (EXT4\_DEFM\_DEBUG) + - Print debugging info upon (re)mount. (EXT4_DEFM_DEBUG) * - 0x0002 - New files take the gid of the containing directory (instead of the fsgid - of the current process). (EXT4\_DEFM\_BSDGROUPS) + of the current process). (EXT4_DEFM_BSDGROUPS) * - 0x0004 - - Support userspace-provided extended attributes. (EXT4\_DEFM\_XATTR\_USER) + - Support userspace-provided extended attributes. (EXT4_DEFM_XATTR_USER) * - 0x0008 - - Support POSIX access control lists (ACLs). (EXT4\_DEFM\_ACL) + - Support POSIX access control lists (ACLs). (EXT4_DEFM_ACL) * - 0x0010 - - Do not support 32-bit UIDs. (EXT4\_DEFM\_UID16) + - Do not support 32-bit UIDs. (EXT4_DEFM_UID16) * - 0x0020 - All data and metadata are commited to the journal. - (EXT4\_DEFM\_JMODE\_DATA) + (EXT4_DEFM_JMODE_DATA) * - 0x0040 - All data are flushed to the disk before metadata are committed to the - journal. (EXT4\_DEFM\_JMODE\_ORDERED) + journal. (EXT4_DEFM_JMODE_ORDERED) * - 0x0060 - Data ordering is not preserved; data may be written after the metadata - has been written. (EXT4\_DEFM\_JMODE\_WBACK) + has been written. (EXT4_DEFM_JMODE_WBACK) * - 0x0100 - - Disable write flushes. (EXT4\_DEFM\_NOBARRIER) + - Disable write flushes. (EXT4_DEFM_NOBARRIER) * - 0x0200 - Track which blocks in a filesystem are metadata and therefore should not be used as data blocks. This option will be enabled by default on 3.18, - hopefully. (EXT4\_DEFM\_BLOCK\_VALIDITY) + hopefully. (EXT4_DEFM_BLOCK_VALIDITY) * - 0x0400 - Enable DISCARD support, where the storage device is told about blocks - becoming unused. (EXT4\_DEFM\_DISCARD) + becoming unused. (EXT4_DEFM_DISCARD) * - 0x0800 - - Disable delayed allocation. (EXT4\_DEFM\_NODELALLOC) + - Disable delayed allocation. (EXT4_DEFM_NODELALLOC) .. _super_flags: @@ -820,12 +820,12 @@ The ``s_encrypt_algos`` list can contain any of the following: * - Value - Description * - 0 - - Invalid algorithm (ENCRYPTION\_MODE\_INVALID). + - Invalid algorithm (ENCRYPTION_MODE_INVALID). * - 1 - - 256-bit AES in XTS mode (ENCRYPTION\_MODE\_AES\_256\_XTS). + - 256-bit AES in XTS mode (ENCRYPTION_MODE_AES_256_XTS). * - 2 - - 256-bit AES in GCM mode (ENCRYPTION\_MODE\_AES\_256\_GCM). + - 256-bit AES in GCM mode (ENCRYPTION_MODE_AES_256_GCM). * - 3 - - 256-bit AES in CBC mode (ENCRYPTION\_MODE\_AES\_256\_CBC). + - 256-bit AES in CBC mode (ENCRYPTION_MODE_AES_256_CBC). Total size of the superblock is 1024 bytes. diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index ad8dc8c040a2..98dc24f5c6f0 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -818,10 +818,11 @@ Compression implementation Instead, the main goal is to reduce data writes to flash disk as much as possible, resulting in extending disk life time as well as relaxing IO congestion. Alternatively, we've added ioctl(F2FS_IOC_RELEASE_COMPRESS_BLOCKS) - interface to reclaim compressed space and show it to user after putting the - immutable bit. Immutable bit, after release, it doesn't allow writing/mmaping - on the file, until reserving compressed space via - ioctl(F2FS_IOC_RESERVE_COMPRESS_BLOCKS) or truncating filesize to zero. + interface to reclaim compressed space and show it to user after setting a + special flag to the inode. Once the compressed space is released, the flag + will block writing data to the file until either the compressed space is + reserved via ioctl(F2FS_IOC_RESERVE_COMPRESS_BLOCKS) or the file size is + truncated to zero. Compress metadata layout:: @@ -830,12 +831,12 @@ Compress metadata layout:: | cluster 1 | cluster 2 | ......... | cluster N | +-----------------------------------------------+ . . . . - . . . . + . . . . . Compressed Cluster . . Normal Cluster . +----------+---------+---------+---------+ +---------+---------+---------+---------+ |compr flag| block 1 | block 2 | block 3 | | block 1 | block 2 | block 3 | block 4 | +----------+---------+---------+---------+ +---------+---------+---------+---------+ - . . + . . . . . . +-------------+-------------+----------+----------------------------+ diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index 2e9aaa295125..5ba5817c17c2 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -337,6 +337,7 @@ Currently, the following pairs of encryption modes are supported: - AES-256-XTS for contents and AES-256-CTS-CBC for filenames - AES-128-CBC for contents and AES-128-CTS-CBC for filenames - Adiantum for both contents and filenames +- AES-256-XTS for contents and AES-256-HCTR2 for filenames (v2 policies only) If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair. @@ -357,6 +358,17 @@ To use Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled. Also, fast implementations of ChaCha and NHPoly1305 should be enabled, e.g. CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM. +AES-256-HCTR2 is another true wide-block encryption mode that is intended for +use on CPUs with dedicated crypto instructions. AES-256-HCTR2 has the property +that a bitflip in the plaintext changes the entire ciphertext. This property +makes it desirable for filename encryption since initialization vectors are +reused within a directory. For more details on AES-256-HCTR2, see the paper +"Length-preserving encryption with HCTR2" +(https://eprint.iacr.org/2021/1441.pdf). To use AES-256-HCTR2, +CONFIG_CRYPTO_HCTR2 must be enabled. Also, fast implementations of XCTR and +POLYVAL should be enabled, e.g. CRYPTO_POLYVAL_ARM64_CE and +CRYPTO_AES_ARM64_CE_BLK for ARM64. + New encryption modes can be added relatively easily, without changes to individual filesystems. However, authenticated encryption (AE) modes are not currently supported because of the difficulty of dealing @@ -404,11 +416,11 @@ alternatively has the file's nonce (for `DIRECT_KEY policies`_) or inode number (for `IV_INO_LBLK_64 policies`_) included in the IVs. Thus, IV reuse is limited to within a single directory. -With CTS-CBC, the IV reuse means that when the plaintext filenames -share a common prefix at least as long as the cipher block size (16 -bytes for AES), the corresponding encrypted filenames will also share -a common prefix. This is undesirable. Adiantum does not have this -weakness, as it is a wide-block encryption mode. +With CTS-CBC, the IV reuse means that when the plaintext filenames share a +common prefix at least as long as the cipher block size (16 bytes for AES), the +corresponding encrypted filenames will also share a common prefix. This is +undesirable. Adiantum and HCTR2 do not have this weakness, as they are +wide-block encryption modes. All supported filenames encryption modes accept any plaintext length >= 16 bytes; cipher block alignment is not required. However, diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst index 756f2c215ba1..cb8e7573882a 100644 --- a/Documentation/filesystems/fsverity.rst +++ b/Documentation/filesystems/fsverity.rst @@ -11,9 +11,9 @@ Introduction fs-verity (``fs/verity/``) is a support layer that filesystems can hook into to support transparent integrity and authenticity protection -of read-only files. Currently, it is supported by the ext4 and f2fs -filesystems. Like fscrypt, not too much filesystem-specific code is -needed to support fs-verity. +of read-only files. Currently, it is supported by the ext4, f2fs, and +btrfs filesystems. Like fscrypt, not too much filesystem-specific +code is needed to support fs-verity. fs-verity is similar to `dm-verity <https://www.kernel.org/doc/Documentation/device-mapper/verity.txt>`_ @@ -473,9 +473,9 @@ files being swapped around. Filesystem support ================== -fs-verity is currently supported by the ext4 and f2fs filesystems. -The CONFIG_FS_VERITY kconfig option must be enabled to use fs-verity -on either filesystem. +fs-verity is supported by several filesystems, described below. The +CONFIG_FS_VERITY kconfig option must be enabled to use fs-verity on +any of these filesystems. ``include/linux/fsverity.h`` declares the interface between the ``fs/verity/`` support layer and filesystems. Briefly, filesystems @@ -544,6 +544,13 @@ Currently, f2fs verity only supports a Merkle tree block size of 4096. Also, f2fs doesn't support enabling verity on files that currently have atomic or volatile writes pending. +btrfs +----- + +btrfs supports fs-verity since Linux v5.15. Verity-enabled inodes are +marked with a RO_COMPAT inode flag, and the verity metadata is stored +in separate btree items. + Implementation details ====================== @@ -622,14 +629,14 @@ workqueue, and then the workqueue work does the decryption or verification. Finally, pages where no decryption or verity error occurred are marked Uptodate, and the pages are unlocked. -Files on ext4 and f2fs may contain holes. Normally, ``->readahead()`` -simply zeroes holes and sets the corresponding pages Uptodate; no bios -are issued. To prevent this case from bypassing fs-verity, these -filesystems use fsverity_verify_page() to verify hole pages. +On many filesystems, files can contain holes. Normally, +``->readahead()`` simply zeroes holes and sets the corresponding pages +Uptodate; no bios are issued. To prevent this case from bypassing +fs-verity, these filesystems use fsverity_verify_page() to verify hole +pages. -ext4 and f2fs disable direct I/O on verity files, since otherwise -direct I/O would bypass fs-verity. (They also do the same for -encrypted files.) +Filesystems also disable direct I/O on verity files, since otherwise +direct I/O would bypass fs-verity. Userspace utility ================= @@ -648,7 +655,7 @@ Tests To test fs-verity, use xfstests. For example, using `kvm-xfstests <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_:: - kvm-xfstests -c ext4,f2fs -g verity + kvm-xfstests -c ext4,f2fs,btrfs -g verity FAQ === @@ -771,15 +778,15 @@ weren't already directly answered in other parts of this document. e.g. magically trigger construction of a Merkle tree. :Q: Does fs-verity support remote filesystems? -:A: Only ext4 and f2fs support is implemented currently, but in - principle any filesystem that can store per-file verity metadata - can support fs-verity, regardless of whether it's local or remote. - Some filesystems may have fewer options of where to store the - verity metadata; one possibility is to store it past the end of - the file and "hide" it from userspace by manipulating i_size. The - data verification functions provided by ``fs/verity/`` also assume - that the filesystem uses the Linux pagecache, but both local and - remote filesystems normally do so. +:A: So far all filesystems that have implemented fs-verity support are + local filesystems, but in principle any filesystem that can store + per-file verity metadata can support fs-verity, regardless of + whether it's local or remote. Some filesystems may have fewer + options of where to store the verity metadata; one possibility is + to store it past the end of the file and "hide" it from userspace + by manipulating i_size. The data verification functions provided + by ``fs/verity/`` also assume that the filesystem uses the Linux + pagecache, but both local and remote filesystems normally do so. :Q: Why is anything filesystem-specific at all? Shouldn't fs-verity be implemented entirely at the VFS level? diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index c0fe711f14d3..4bb2627026ec 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -252,9 +252,8 @@ prototypes:: bool (*release_folio)(struct folio *, gfp_t); void (*free_folio)(struct folio *); int (*direct_IO)(struct kiocb *, struct iov_iter *iter); - bool (*isolate_page) (struct page *, isolate_mode_t); - int (*migratepage)(struct address_space *, struct page *, struct page *); - void (*putback_page) (struct page *); + int (*migrate_folio)(struct address_space *, struct folio *dst, + struct folio *src, enum migrate_mode); int (*launder_folio)(struct folio *); bool (*is_partially_uptodate)(struct folio *, size_t from, size_t count); int (*error_remove_page)(struct address_space *, struct page *); @@ -280,9 +279,7 @@ invalidate_folio: yes exclusive release_folio: yes free_folio: yes direct_IO: -isolate_page: yes -migratepage: yes (both) -putback_page: yes +migrate_folio: yes (both) launder_folio: yes is_partially_uptodate: yes error_remove_page: yes diff --git a/Documentation/filesystems/netfs_library.rst b/Documentation/filesystems/netfs_library.rst index 4d19b19bcc08..73a4176144b3 100644 --- a/Documentation/filesystems/netfs_library.rst +++ b/Documentation/filesystems/netfs_library.rst @@ -301,7 +301,7 @@ through which it can issue requests and negotiate:: void (*issue_read)(struct netfs_io_subrequest *subreq); bool (*is_still_valid)(struct netfs_io_request *rreq); int (*check_write_begin)(struct file *file, loff_t pos, unsigned len, - struct folio *folio, void **_fsdata); + struct folio **foliop, void **_fsdata); void (*done)(struct netfs_io_request *rreq); }; @@ -381,8 +381,10 @@ The operations are as follows: allocated/grabbed the folio to be modified to allow the filesystem to flush conflicting state before allowing it to be modified. - It should return 0 if everything is now fine, -EAGAIN if the folio should be - regrabbed and any other error code to abort the operation. + It may unlock and discard the folio it was given and set the caller's folio + pointer to NULL. It should return 0 if everything is now fine (``*foliop`` + left set) or the op should be retried (``*foliop`` cleared) and any other + error code to abort the operation. * ``done`` diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index 7da6c30ed596..4c76fda07645 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -607,7 +607,7 @@ can be removed. User xattr ---------- -The the "-o userxattr" mount option forces overlayfs to use the +The "-o userxattr" mount option forces overlayfs to use the "user.overlay." xattr namespace instead of "trusted.overlay.". This is useful for unprivileged mounting of overlayfs. diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst index 2e0e4f0e0c6f..aee9aaf9f3df 100644 --- a/Documentation/filesystems/porting.rst +++ b/Documentation/filesystems/porting.rst @@ -914,3 +914,11 @@ Calling conventions for file_open_root() changed; now it takes struct path * instead of passing mount and dentry separately. For callers that used to pass <mnt, mnt->mnt_root> pair (i.e. the root of given mount), a new helper is provided - file_open_root_mnt(). In-tree users adjusted. + +--- + +**mandatory** + +no_llseek is gone; don't set .llseek to that - just leave it NULL instead. +Checks for "does that file have llseek(2), or should it fail with ESPIPE" +should be done by looking at FMODE_LSEEK in file->f_mode. diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index 08069ecd49a6..6cd6953e175b 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -737,12 +737,8 @@ cache in your filesystem. The following members are defined: bool (*release_folio)(struct folio *, gfp_t); void (*free_folio)(struct folio *); ssize_t (*direct_IO)(struct kiocb *, struct iov_iter *iter); - /* isolate a page for migration */ - bool (*isolate_page) (struct page *, isolate_mode_t); - /* migrate the contents of a page to the specified target */ - int (*migratepage) (struct page *, struct page *); - /* put migration-failed page back to right list */ - void (*putback_page) (struct page *); + int (*migrate_folio)(struct mapping *, struct folio *dst, + struct folio *src, enum migrate_mode); int (*launder_folio) (struct folio *); bool (*is_partially_uptodate) (struct folio *, size_t from, @@ -774,13 +770,38 @@ cache in your filesystem. The following members are defined: See the file "Locking" for more details. ``read_folio`` - called by the VM to read a folio from backing store. The folio - will be locked when read_folio is called, and should be unlocked - and marked uptodate once the read completes. If ->read_folio - discovers that it cannot perform the I/O at this time, it can - unlock the folio and return AOP_TRUNCATED_PAGE. In this case, - the folio will be looked up again, relocked and if that all succeeds, - ->read_folio will be called again. + Called by the page cache to read a folio from the backing store. + The 'file' argument supplies authentication information to network + filesystems, and is generally not used by block based filesystems. + It may be NULL if the caller does not have an open file (eg if + the kernel is performing a read for itself rather than on behalf + of a userspace process with an open file). + + If the mapping does not support large folios, the folio will + contain a single page. The folio will be locked when read_folio + is called. If the read completes successfully, the folio should + be marked uptodate. The filesystem should unlock the folio + once the read has completed, whether it was successful or not. + The filesystem does not need to modify the refcount on the folio; + the page cache holds a reference count and that will not be + released until the folio is unlocked. + + Filesystems may implement ->read_folio() synchronously. + In normal operation, folios are read through the ->readahead() + method. Only if this fails, or if the caller needs to wait for + the read to complete will the page cache call ->read_folio(). + Filesystems should not attempt to perform their own readahead + in the ->read_folio() operation. + + If the filesystem cannot perform the read at this time, it can + unlock the folio, do whatever action it needs to ensure that the + read will succeed in the future and return AOP_TRUNCATED_PAGE. + In this case, the caller should look up the folio, lock it, + and call ->read_folio again. + + Callers may invoke the ->read_folio() method directly, but using + read_mapping_folio() will take care of locking, waiting for the + read to complete and handle cases such as AOP_TRUNCATED_PAGE. ``writepages`` called by the VM to write out pages associated with the @@ -905,20 +926,12 @@ cache in your filesystem. The following members are defined: data directly between the storage and the application's address space. -``isolate_page`` - Called by the VM when isolating a movable non-lru page. If page - is successfully isolated, VM marks the page as PG_isolated via - __SetPageIsolated. - -``migrate_page`` +``migrate_folio`` This is used to compact the physical memory usage. If the VM - wants to relocate a page (maybe off a memory card that is - signalling imminent failure) it will pass a new page and an old - page to this function. migrate_page should transfer any private - data across and update any references that it has to the page. - -``putback_page`` - Called by the VM when isolated page's migration fails. + wants to relocate a folio (maybe from a memory device that is + signalling imminent failure) it will pass a new folio and an old + folio to this function. migrate_folio should transfer any private + data across and update any references that it has to the folio. ``launder_folio`` Called before freeing a folio - it writes back the dirty folio. diff --git a/Documentation/firmware-guide/acpi/DSD-properties-rules.rst b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst index 8b2d8d0864c2..70442bc2521e 100644 --- a/Documentation/firmware-guide/acpi/DSD-properties-rules.rst +++ b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst @@ -21,7 +21,9 @@ specific type) associated with it. In the ACPI _DSD context it is an element of the sub-package following the generic Device Properties UUID in the _DSD return package as specified in the -Device Properties UUID definition document [1]_. +section titled "Well-Known _DSD UUIDs and Data Structure Formats" sub-section +"Device Properties UUID" in _DSD (Device Specific Data) Implementation Guide +document [1]_. It also may be regarded as the definition of a key and the associated data type that can be returned by _DSD in the Device Properties UUID sub-package for a @@ -36,7 +38,9 @@ Property subsets are nested collections of properties. Each of them is associated with an additional key (name) allowing the subset to be referred to as a whole (and to be treated as a separate entity). The canonical representation of property subsets is via the mechanism specified in the -Hierarchical Properties Extension UUID definition document [2]_. +section titled "Well-Known _DSD UUIDs and Data Structure Formats" sub-section +"Hierarchical Data Extension UUID" in _DSD (Device Specific Data) +Implementation Guide document [1]_. Property sets may be hierarchical. That is, a property set may contain multiple property subsets that each may contain property subsets of its @@ -96,5 +100,4 @@ contents. References ========== -.. [1] https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf -.. [2] https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf +.. [1] https://github.com/UEFI/DSD-Guide diff --git a/Documentation/firmware-guide/acpi/apei/einj.rst b/Documentation/firmware-guide/acpi/apei/einj.rst index 55e2331a6438..d6b61d22f525 100644 --- a/Documentation/firmware-guide/acpi/apei/einj.rst +++ b/Documentation/firmware-guide/acpi/apei/einj.rst @@ -168,7 +168,7 @@ An error injection example:: 0x00000008 Memory Correctable 0x00000010 Memory Uncorrectable non-fatal # echo 0x12345000 > param1 # Set memory address for injection - # echo $((-1 << 12)) > param2 # Mask 0xfffffffffffff000 - anywhere in this page + # echo 0xfffffffffffff000 > param2 # Mask - anywhere in this page # echo 0x8 > error_type # Choose correctable memory error # echo 1 > error_inject # Inject now diff --git a/Documentation/hwmon/aquacomputer_d5next.rst b/Documentation/hwmon/aquacomputer_d5next.rst index 717e28226cde..33649a1e3a05 100644 --- a/Documentation/hwmon/aquacomputer_d5next.rst +++ b/Documentation/hwmon/aquacomputer_d5next.rst @@ -9,6 +9,7 @@ Supported devices: * Aquacomputer Farbwerk RGB controller * Aquacomputer Farbwerk 360 RGB controller * Aquacomputer Octo fan controller +* Aquacomputer Quadro fan controller Author: Aleksa Savic @@ -33,6 +34,9 @@ better suited for userspace tools. The Octo exposes four temperature sensors and eight PWM controllable fans, along with their speed (in RPM), power, voltage and current. +The Quadro exposes four temperature sensors, a flow sensor and four PWM controllable +fans, along with their speed (in RPM), power, voltage and current. + The Farbwerk and Farbwerk 360 expose four temperature sensors. Depending on the device, not all sysfs and debugfs entries will be available. @@ -45,13 +49,14 @@ the kernel and supports hotswapping. Sysfs entries ------------- -================ ============================================= +================ ============================================== temp[1-4]_input Temperature sensors (in millidegrees Celsius) -fan[1-2]_input Pump/fan speed (in RPM) -power[1-2]_input Pump/fan power (in micro Watts) -in[0-2]_input Pump/fan voltage (in milli Volts) -curr[1-2]_input Pump/fan current (in milli Amperes) -================ ============================================= +fan[1-8]_input Pump/fan speed (in RPM) / Flow speed (in dL/h) +power[1-8]_input Pump/fan power (in micro Watts) +in[0-7]_input Pump/fan voltage (in milli Volts) +curr[1-8]_input Pump/fan current (in milli Amperes) +pwm[1-8] Fan PWM (0 - 255) +================ ============================================== Debugfs entries --------------- diff --git a/Documentation/hwmon/asus_ec_sensors.rst b/Documentation/hwmon/asus_ec_sensors.rst index 78ca69eda877..02f4ad314a1e 100644 --- a/Documentation/hwmon/asus_ec_sensors.rst +++ b/Documentation/hwmon/asus_ec_sensors.rst @@ -13,12 +13,16 @@ Supported boards: * ROG CROSSHAIR VIII FORMULA * ROG CROSSHAIR VIII HERO * ROG CROSSHAIR VIII IMPACT + * ROG MAXIMUS XI HERO + * ROG MAXIMUS XI HERO (WI-FI) * ROG STRIX B550-E GAMING * ROG STRIX B550-I GAMING * ROG STRIX X570-E GAMING * ROG STRIX X570-E GAMING WIFI II * ROG STRIX X570-F GAMING * ROG STRIX X570-I GAMING + * ROG STRIX Z690-A GAMING WIFI D4 + * ROG ZENITH II EXTREME Authors: - Eugene Shalygin <eugene.shalygin@gmail.com> diff --git a/Documentation/hwmon/dell-smm-hwmon.rst b/Documentation/hwmon/dell-smm-hwmon.rst index e5d85e40972c..d8f1d6859b96 100644 --- a/Documentation/hwmon/dell-smm-hwmon.rst +++ b/Documentation/hwmon/dell-smm-hwmon.rst @@ -46,6 +46,9 @@ temp[1-10]_input RO Temperature reading in milli-degrees temp[1-10]_label RO Temperature sensor label. =============================== ======= ======================================= +Due to the nature of the SMM interface, each pwmX attribute controls +fan number X. + Disabling automatic BIOS fan control ------------------------------------ diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index a72c16872ec2..f7113b0f8b2a 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -109,6 +109,7 @@ Hardware Monitoring Kernel Drivers lm95234 lm95245 lochnagar + lt7182s ltc2992 ltc2945 ltc2947 diff --git a/Documentation/hwmon/lm90.rst b/Documentation/hwmon/lm90.rst index 05391fb4042d..23af17a0ab44 100644 --- a/Documentation/hwmon/lm90.rst +++ b/Documentation/hwmon/lm90.rst @@ -3,6 +3,14 @@ Kernel driver lm90 Supported chips: + * National Semiconductor LM84 + + Prefix: 'lm84' + + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + + Datasheet: Publicly available at the National Semiconductor website + * National Semiconductor LM90 Prefix: 'lm90' @@ -43,6 +51,30 @@ Supported chips: http://www.national.com/mpf/LM/LM86.html + * Analog Devices ADM1020 + + Prefix: 'adm1020' + + Addresses scanned: I2C 0x4c - 0x4e + + Datasheet: Publicly available at the Analog Devices website + + * 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 + * Analog Devices ADM1032 Prefix: 'adm1032' @@ -73,6 +105,36 @@ Supported chips: https://www.onsemi.com/PowerSolutions/product.do?id=ADT7461A + * Analog Devices ADT7481 + + Prefix: 'adt7481' + + Addresses scanned: I2C 0x4b and 0x4c + + Datasheet: Publicly available at the ON Semiconductor website + + https://www.onsemi.com/PowerSolutions/product.do?id=ADT7481 + + * Analog Devices ADT7482 + + Prefix: 'adt7482' + + Addresses scanned: I2C 0x4c + + Datasheet: Publicly available at the ON Semiconductor website + + https://www.onsemi.com/PowerSolutions/product.do?id=ADT7482 + + * Analog Devices ADT7483A + + Prefix: 'adt7483a' + + Addresses scanned: I2C 0x18, 0x19, 0x1a, 0x29, 0x2a, 0x2b, 0x4c, 0x4d, 0x4e + + Datasheet: Publicly available at the ON Semiconductor website + + https://www.onsemi.com/PowerSolutions/product.do?id=ADT7483A + * ON Semiconductor NCT1008 Prefix: 'nct1008' @@ -83,6 +145,72 @@ Supported chips: https://www.onsemi.com/PowerSolutions/product.do?id=NCT1008 + * ON Semiconductor NCT210 + + Prefix: 'adm1021' + + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + + Datasheet: Publicly available at the ON Semiconductor website + + https://www.onsemi.com/PowerSolutions/product.do?id=NCT210 + + * ON Semiconductor NCT214 + + Prefix: 'nct214' + + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + + Datasheet: Publicly available at the ON Semiconductor website + + https://www.onsemi.com/PowerSolutions/product.do?id=NCT214 + + * ON Semiconductor NCT218 + + Prefix: 'nct218' + + Addresses scanned: I2C 0x4c - 0x4d + + Datasheet: Publicly available at the ON Semiconductor website + + https://www.onsemi.com/PowerSolutions/product.do?id=NCT218 + + * ON Semiconductor NCT72 + + Prefix: 'nct72' + + Addresses scanned: I2C 0x4c - 0x4d + + Datasheet: Publicly available at the ON Semiconductor website + + https://www.onsemi.com/PowerSolutions/product.do?id=NCT72 + + * 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 + + * 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 + * Maxim MAX6646 Prefix: 'max6646' @@ -105,7 +233,7 @@ Supported chips: * Maxim MAX6648 - Prefix: 'max6646' + Prefix: 'max6648' Addresses scanned: I2C 0x4c @@ -191,7 +319,7 @@ Supported chips: * Maxim MAX6692 - Prefix: 'max6646' + Prefix: 'max6648' Addresses scanned: I2C 0x4c @@ -275,6 +403,46 @@ Supported chips: https://www.ti.com/lit/gpn/tmp461 + * Philips NE1617, NE1617A + + Prefix: 'max1617' (probably detected as a max1617) + + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + + Datasheets: Publicly available at the Philips website + + * Philips NE1618 + + Prefix: 'ne1618' + + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + + Datasheets: Publicly available at the Philips website + + * Genesys Logic GL523SM + + Prefix: 'gl523sm' + + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + + Datasheet: + + * 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 + Author: Jean Delvare <jdelvare@suse.de> @@ -285,6 +453,12 @@ The LM90 is a digital temperature sensor. It senses its own temperature as well as the temperature of up to one external diode. It is compatible with many other devices, many of which are supported by this driver. +The family of chips supported by this driver is derived from MAX1617. +This chip as well as various compatible chips support a local and a remote +temperature sensor with 8 bit accuracy. Later chips provide improved accuracy +and other additional features such as hysteresis and temperature offset +registers. + Note that there is no easy way to differentiate between the MAX6657, MAX6658 and MAX6659 variants. The extra features of the MAX6659 are only supported by this driver if the chip is located at address 0x4d or 0x4e, @@ -292,15 +466,31 @@ or if the chip type is explicitly selected as max6659. The MAX6680 and MAX6681 only differ in their pinout, therefore they obviously can't (and don't need to) be distinguished. -The specificity of this family of chipsets over the ADM1021/LM84 -family is that it features critical limits with hysteresis, and an -increased resolution of the remote temperature measurement. - The different chipsets of the family are not strictly identical, although very similar. For reference, here comes a non-exhaustive list of specific features: +LM84: + * 8 bit sensor resolution + +ADM1020, ADM1021, GL523SM, MAX1617, NE1617, NE1617A, THMC10: + * 8 bit sensor resolution + * Low temperature limits + +NCT210, NE1618: + * 11 bit sensor resolution for remote temperature sensor + * Low temperature limits + +ADM1021A, ADM1023: + * Temperature offset register for remote temperature sensor + * 11 bit resolution for remote temperature sensor + * Low temperature limits + LM90: + * 11 bit resolution for remote temperature sensor + * Temperature offset register for remote temperature sensor + * Low and critical temperature limits + * Configurable conversion rate * Filter and alert configuration register at 0xBF. * ALERT is triggered by temperatures over critical limits. @@ -322,8 +512,31 @@ ADM1032: ADT7461, ADT7461A, NCT1008: * Extended temperature range (breaks compatibility) * Lower resolution for remote temperature + * SMBus PEC support for Write Byte and Receive Byte transactions. + * 10 bit temperature resolution + +ADT7481, ADT7482, ADT7483: + * Temperature offset register + * SMBus PEC support + * 10 bit temperature resolution for external sensors + * Two remote sensors + * Selectable address (ADT7483) + +MAX6642: + * No critical limit register + * Conversion rate not configurable + * Better local resolution (10 bit) + * 10 bit external sensor resolution + +MAX6646, MAX6647, MAX6649: + * Better local resolution + * Extended range unsigned external temperature + +MAX6648, MAX6692: + * Better local resolution + * Unsigned temperature -MAX6654: +MAX6654, MAX6690: * Better local resolution * Selectable address * Remote sensor type selection @@ -423,6 +636,6 @@ two transactions will typically mean twice as much delay waiting for transaction completion, effectively doubling the register cache refresh time. I guess reliability comes at a price, but it's quite expensive this time. -So, as not everyone might enjoy the slowdown, PEC can be disabled through -sysfs. Just write 0 to the "pec" file and PEC will be disabled. Write 1 -to that file to enable PEC again. +So, as not everyone might enjoy the slowdown, PEC is disabled by default and +can be enabled through sysfs. Just write 1 to the "pec" file and PEC will be +enabled. Write 0 to that file to disable PEC again. diff --git a/Documentation/hwmon/lt7182s.rst b/Documentation/hwmon/lt7182s.rst new file mode 100644 index 000000000000..f7268311b191 --- /dev/null +++ b/Documentation/hwmon/lt7182s.rst @@ -0,0 +1,92 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver lt7182s +===================== + +Supported chips: + + * ADI LT7182S + + Prefix: 'lt7182s' + + Addresses scanned: - + + Datasheet: https://www.analog.com/en/products/lt7182s.html + +Author: Guenter Roeck <linux@roeck-us.net> + + +Description +----------- + +LT7182S is a Dual Channel 6A, 20V PolyPhase Step-Down Silent Switcher with +Digital Power System Management support. + + +Usage Notes +----------- + +This driver does not probe for PMBus devices. You will have to instantiate +devices explicitly. + +Example: the following commands will load the driver for a LT7182S +at address 0x4f on I2C bus #4:: + + # modprobe lt7182s + # echo lt7182s 0x4f > /sys/bus/i2c/devices/i2c-4/new_device + +It can also be instantiated by declaring an entry in device tree. + + +Sysfs attributes +---------------- + +======================= ==================================== +curr[1-2]_label "iin[12]" +curr[1-2]_input Measured input current +curr[1-2]_max Maximum input current +curr[1-2]_max_alarm Current high alarm + +curr[3-4]_label "iout[1-2]" +curr[3-4]_input Measured output current +curr[3-4]_highest Highest measured output current +curr[3-4]_max Maximum output current +curr[3-4]_max_alarm Output current high alarm + +in[1-2]_label "vin[12]" +in[1-2]_input Measured input voltage +in[1-2]_highest Highest measured input voltage +in[1-2]_crit Critical maximum input voltage +in[1-2]_crit_alarm Input voltage critical high alarm +in[1-2]_min Minimum input voltage +in[1-2]_min_alarm Input voltage low alarm +in[1-2]_rated_min Rated minimum input voltage +in[1-2]_rated_max Rated maximum input voltage +in1_reset_history Write to reset history for all attributes + +in[3-5]_label "vmon[1-3]" +in[3-5]_input Measured voltage on ITH1/ITH2/EXTVCC pins + Only available if enabled with MFR_ADC_CONTROL_LT7182S + command. + +in[3-4|6-7]_label "vout[1-2]" +in[3-4|6-7]_input Measured output voltage +in[3-4|6-7]_highest Highest measured output voltage +in[3-4|6-7]_lcrit Critical minimum output voltage +in[3-4|6-7]_lcrit_alarm Output voltage critical low alarm +in[3-4|6-7]_min Minimum output voltage +in[3-4|6-7]_max_alarm Output voltage low alarm +in[3-4|6-7]_max Maximum output voltage +in[3-4|6-7]_max_alarm Output voltage high alarm +in[3-4|6-7]_crit Critical maximum output voltage +in[3-4|6-7]_crit_alarm Output voltage critical high alarm + +power[1-2]_label "pout[1-2]" +power[1-2]_input Measured output power + +temp1_input Measured temperature +temp1_crit Critical high temperature +temp1_crit_alarm Chip temperature critical high alarm +temp1_max Maximum temperature +temp1_max_alarm Chip temperature high alarm +======================= ==================================== diff --git a/Documentation/hwmon/pmbus-core.rst b/Documentation/hwmon/pmbus-core.rst index e7e0c9ef10be..84c5a4e40c40 100644 --- a/Documentation/hwmon/pmbus-core.rst +++ b/Documentation/hwmon/pmbus-core.rst @@ -121,6 +121,15 @@ Specifically, it provides the following information. non-standard PMBus commands to standard commands, or to augment standard command return values with device specific information. +PEC Support +=========== + +Many PMBus devices support SMBus PEC (Packet Error Checking). If supported +by both the I2C adapter and by the PMBus chip, it is by default enabled. +If PEC is supported, the PMBus core driver adds an attribute named 'pec' to +the I2C device. This attribute can be used to control PEC support in the +communication with the PMBus chip. + API functions ============= diff --git a/Documentation/hwmon/submitting-patches.rst b/Documentation/hwmon/submitting-patches.rst index 9a218ea996d8..d953ee763c96 100644 --- a/Documentation/hwmon/submitting-patches.rst +++ b/Documentation/hwmon/submitting-patches.rst @@ -12,7 +12,6 @@ increase the chances of your change being accepted. * It should be unnecessary to mention, but please read and follow: - Documentation/process/submit-checklist.rst - - Documentation/process/submitting-drivers.rst - Documentation/process/submitting-patches.rst - Documentation/process/coding-style.rst diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst index b854bb413164..6b2bac8e9ce0 100644 --- a/Documentation/kbuild/llvm.rst +++ b/Documentation/kbuild/llvm.rst @@ -129,18 +129,24 @@ yet. Bug reports are always welcome at the issue tracker below! * - arm64 - Supported - ``LLVM=1`` + * - hexagon + - Maintained + - ``LLVM=1`` * - mips - Maintained - - ``CC=clang`` + - ``LLVM=1`` * - powerpc - Maintained - ``CC=clang`` * - riscv - Maintained - - ``CC=clang`` + - ``LLVM=1`` * - s390 - Maintained - ``CC=clang`` + * - um (User Mode) + - Maintained + - ``LLVM=1`` * - x86 - Supported - ``LLVM=1`` diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst index ebd9d90882ea..9a1f020c8449 100644 --- a/Documentation/kernel-hacking/hacking.rst +++ b/Documentation/kernel-hacking/hacking.rst @@ -755,8 +755,7 @@ make a neat patch, there's administrative work to be done: it implies a more-than-passing commitment to some part of the code. - Finally, don't forget to read - ``Documentation/process/submitting-patches.rst`` and possibly - ``Documentation/process/submitting-drivers.rst``. + ``Documentation/process/submitting-patches.rst`` Kernel Cantrips =============== diff --git a/Documentation/livepatch/module-elf-format.rst b/Documentation/livepatch/module-elf-format.rst index dbe9b400e39f..7347638895a0 100644 --- a/Documentation/livepatch/module-elf-format.rst +++ b/Documentation/livepatch/module-elf-format.rst @@ -210,11 +210,11 @@ module->symtab. ===================================== Normally, a stripped down copy of a module's symbol table (containing only "core" symbols) is made available through module->symtab (See layout_symtab() -in kernel/module.c). For livepatch modules, the symbol table copied into memory -on module load must be exactly the same as the symbol table produced when the -patch module was compiled. This is because the relocations in each livepatch -relocation section refer to their respective symbols with their symbol indices, -and the original symbol indices (and thus the symtab ordering) must be +in kernel/module/kallsyms.c). For livepatch modules, the symbol table copied +into memory on module load must be exactly the same as the symbol table produced +when the patch module was compiled. This is because the relocations in each +livepatch relocation section refer to their respective symbols with their symbol +indices, and the original symbol indices (and thus the symtab ordering) must be preserved in order for apply_relocate_add() to find the right symbol. For example, take this particular rela from a livepatch module::: diff --git a/Documentation/loongarch/introduction.rst b/Documentation/loongarch/introduction.rst index 2bf40ad370df..216b3f390e80 100644 --- a/Documentation/loongarch/introduction.rst +++ b/Documentation/loongarch/introduction.rst @@ -45,10 +45,12 @@ Name Alias Usage Preserved ``$r23``-``$r31`` ``$s0``-``$s8`` Static registers Yes ================= =============== =================== ============ -Note: The register ``$r21`` is reserved in the ELF psABI, but used by the Linux -kernel for storing the percpu base address. It normally has no ABI name, but is -called ``$u0`` in the kernel. You may also see ``$v0`` or ``$v1`` in some old code, -however they are deprecated aliases of ``$a0`` and ``$a1`` respectively. +.. Note:: + The register ``$r21`` is reserved in the ELF psABI, but used by the Linux + kernel for storing the percpu base address. It normally has no ABI name, + but is called ``$u0`` in the kernel. You may also see ``$v0`` or ``$v1`` + in some old code,however they are deprecated aliases of ``$a0`` and ``$a1`` + respectively. FPRs ---- @@ -69,8 +71,9 @@ Name Alias Usage Preserved ``$f24``-``$f31`` ``$fs0``-``$fs7`` Static registers Yes ================= ================== =================== ============ -Note: You may see ``$fv0`` or ``$fv1`` in some old code, however they are deprecated -aliases of ``$fa0`` and ``$fa1`` respectively. +.. Note:: + You may see ``$fv0`` or ``$fv1`` in some old code, however they are + deprecated aliases of ``$fa0`` and ``$fa1`` respectively. VRs ---- diff --git a/Documentation/loongarch/irq-chip-model.rst b/Documentation/loongarch/irq-chip-model.rst index 8d88f7ab2e5e..7988f4192363 100644 --- a/Documentation/loongarch/irq-chip-model.rst +++ b/Documentation/loongarch/irq-chip-model.rst @@ -145,12 +145,16 @@ Documentation of Loongson's LS7A chipset: https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-7A1000-usermanual-2.00-EN.pdf (in English) -Note: CPUINTC is CSR.ECFG/CSR.ESTAT and its interrupt controller described -in Section 7.4 of "LoongArch Reference Manual, Vol 1"; LIOINTC is "Legacy I/O -Interrupts" described in Section 11.1 of "Loongson 3A5000 Processor Reference -Manual"; EIOINTC is "Extended I/O Interrupts" described in Section 11.2 of -"Loongson 3A5000 Processor Reference Manual"; HTVECINTC is "HyperTransport -Interrupts" described in Section 14.3 of "Loongson 3A5000 Processor Reference -Manual"; PCH-PIC/PCH-MSI is "Interrupt Controller" described in Section 5 of -"Loongson 7A1000 Bridge User Manual"; PCH-LPC is "LPC Interrupts" described in -Section 24.3 of "Loongson 7A1000 Bridge User Manual". +.. Note:: + - CPUINTC is CSR.ECFG/CSR.ESTAT and its interrupt controller described + in Section 7.4 of "LoongArch Reference Manual, Vol 1"; + - LIOINTC is "Legacy I/OInterrupts" described in Section 11.1 of + "Loongson 3A5000 Processor Reference Manual"; + - EIOINTC is "Extended I/O Interrupts" described in Section 11.2 of + "Loongson 3A5000 Processor Reference Manual"; + - HTVECINTC is "HyperTransport Interrupts" described in Section 14.3 of + "Loongson 3A5000 Processor Reference Manual"; + - PCH-PIC/PCH-MSI is "Interrupt Controller" described in Section 5 of + "Loongson 7A1000 Bridge User Manual"; + - PCH-LPC is "LPC Interrupts" described in Section 24.3 of + "Loongson 7A1000 Bridge User Manual". diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index b12df9137e1c..832b5d36e279 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -1894,6 +1894,7 @@ There are some more advanced barrier functions: (*) dma_wmb(); (*) dma_rmb(); + (*) dma_mb(); These are for use with consistent memory to guarantee the ordering of writes or reads of shared memory accessible to both the CPU and a @@ -1925,11 +1926,11 @@ There are some more advanced barrier functions: The dma_rmb() allows us guarantee the device has released ownership before we read the data from the descriptor, and the dma_wmb() allows us to guarantee the data is written to the descriptor before the device - can see it now has ownership. Note that, when using writel(), a prior - wmb() is not needed to guarantee that the cache coherent memory writes - have completed before writing to the MMIO region. The cheaper - writel_relaxed() does not provide this guarantee and must not be used - here. + can see it now has ownership. The dma_mb() implies both a dma_rmb() and + a dma_wmb(). Note that, when using writel(), a prior wmb() is not needed + to guarantee that the cache coherent memory writes have completed before + writing to the MMIO region. The cheaper writel_relaxed() does not provide + this guarantee and must not be used here. See the subsection "Kernel I/O barrier effects" for more information on relaxed I/O accessors and the Documentation/core-api/dma-api.rst file for diff --git a/Documentation/networking/dsa/dsa.rst b/Documentation/networking/dsa/dsa.rst index ed7fa76e7a40..d742ba6bd211 100644 --- a/Documentation/networking/dsa/dsa.rst +++ b/Documentation/networking/dsa/dsa.rst @@ -503,26 +503,108 @@ per-port PHY specific details: interface connection, MDIO bus location, etc. Driver development ================== -DSA switch drivers need to implement a dsa_switch_ops structure which will +DSA switch drivers need to implement a ``dsa_switch_ops`` structure which will contain the various members described below. -``register_switch_driver()`` registers this dsa_switch_ops in its internal list -of drivers to probe for. ``unregister_switch_driver()`` does the exact opposite. +Probing, registration and device lifetime +----------------------------------------- -Unless requested differently by setting the priv_size member accordingly, DSA -does not allocate any driver private context space. +DSA switches are regular ``device`` structures on buses (be they platform, SPI, +I2C, MDIO or otherwise). The DSA framework is not involved in their probing +with the device core. + +Switch registration from the perspective of a driver means passing a valid +``struct dsa_switch`` pointer to ``dsa_register_switch()``, usually from the +switch driver's probing function. The following members must be valid in the +provided structure: + +- ``ds->dev``: will be used to parse the switch's OF node or platform data. + +- ``ds->num_ports``: will be used to create the port list for this switch, and + to validate the port indices provided in the OF node. + +- ``ds->ops``: a pointer to the ``dsa_switch_ops`` structure holding the DSA + method implementations. + +- ``ds->priv``: backpointer to a driver-private data structure which can be + retrieved in all further DSA method callbacks. + +In addition, the following flags in the ``dsa_switch`` structure may optionally +be configured to obtain driver-specific behavior from the DSA core. Their +behavior when set is documented through comments in ``include/net/dsa.h``. + +- ``ds->vlan_filtering_is_global`` + +- ``ds->needs_standalone_vlan_filtering`` + +- ``ds->configure_vlan_while_not_filtering`` + +- ``ds->untag_bridge_pvid`` + +- ``ds->assisted_learning_on_cpu_port`` + +- ``ds->mtu_enforcement_ingress`` + +- ``ds->fdb_isolation`` + +Internally, DSA keeps an array of switch trees (group of switches) global to +the kernel, and attaches a ``dsa_switch`` structure to a tree on registration. +The tree ID to which the switch is attached is determined by the first u32 +number of the ``dsa,member`` property of the switch's OF node (0 if missing). +The switch ID within the tree is determined by the second u32 number of the +same OF property (0 if missing). Registering multiple switches with the same +switch ID and tree ID is illegal and will cause an error. Using platform data, +a single switch and a single switch tree is permitted. + +In case of a tree with multiple switches, probing takes place asymmetrically. +The first N-1 callers of ``dsa_register_switch()`` only add their ports to the +port list of the tree (``dst->ports``), each port having a backpointer to its +associated switch (``dp->ds``). Then, these switches exit their +``dsa_register_switch()`` call early, because ``dsa_tree_setup_routing_table()`` +has determined that the tree is not yet complete (not all ports referenced by +DSA links are present in the tree's port list). The tree becomes complete when +the last switch calls ``dsa_register_switch()``, and this triggers the effective +continuation of initialization (including the call to ``ds->ops->setup()``) for +all switches within that tree, all as part of the calling context of the last +switch's probe function. + +The opposite of registration takes place when calling ``dsa_unregister_switch()``, +which removes a switch's ports from the port list of the tree. The entire tree +is torn down when the first switch unregisters. + +It is mandatory for DSA switch drivers to implement the ``shutdown()`` callback +of their respective bus, and call ``dsa_switch_shutdown()`` from it (a minimal +version of the full teardown performed by ``dsa_unregister_switch()``). +The reason is that DSA keeps a reference on the master net device, and if the +driver for the master device decides to unbind on shutdown, DSA's reference +will block that operation from finalizing. + +Either ``dsa_switch_shutdown()`` or ``dsa_unregister_switch()`` must be called, +but not both, and the device driver model permits the bus' ``remove()`` method +to be called even if ``shutdown()`` was already called. Therefore, drivers are +expected to implement a mutual exclusion method between ``remove()`` and +``shutdown()`` by setting their drvdata to NULL after any of these has run, and +checking whether the drvdata is NULL before proceeding to take any action. + +After ``dsa_switch_shutdown()`` or ``dsa_unregister_switch()`` was called, no +further callbacks via the provided ``dsa_switch_ops`` may take place, and the +driver may free the data structures associated with the ``dsa_switch``. Switch configuration -------------------- -- ``tag_protocol``: this is to indicate what kind of tagging protocol is supported, - should be a valid value from the ``dsa_tag_protocol`` enum +- ``get_tag_protocol``: this is to indicate what kind of tagging protocol is + supported, should be a valid value from the ``dsa_tag_protocol`` enum. + The returned information does not have to be static; the driver is passed the + CPU port number, as well as the tagging protocol of a possibly stacked + upstream switch, in case there are hardware limitations in terms of supported + tag formats. -- ``probe``: probe routine which will be invoked by the DSA platform device upon - registration to test for the presence/absence of a switch device. For MDIO - devices, it is recommended to issue a read towards internal registers using - the switch pseudo-PHY and return whether this is a supported device. For other - buses, return a non-NULL string +- ``change_tag_protocol``: when the default tagging protocol has compatibility + problems with the master or other issues, the driver may support changing it + at runtime, either through a device tree property or through sysfs. In that + case, further calls to ``get_tag_protocol`` should report the protocol in + current use. - ``setup``: setup function for the switch, this function is responsible for setting up the ``dsa_switch_ops`` private structure with all it needs: register maps, @@ -535,7 +617,17 @@ Switch configuration fully configured and ready to serve any kind of request. It is recommended to issue a software reset of the switch during this setup function in order to avoid relying on what a previous software agent such as a bootloader/firmware - may have previously configured. + may have previously configured. The method responsible for undoing any + applicable allocations or operations done here is ``teardown``. + +- ``port_setup`` and ``port_teardown``: methods for initialization and + destruction of per-port data structures. It is mandatory for some operations + such as registering and unregistering devlink port regions to be done from + these methods, otherwise they are optional. A port will be torn down only if + it has been previously set up. It is possible for a port to be set up during + probing only to be torn down immediately afterwards, for example in case its + PHY cannot be found. In this case, probing of the DSA switch continues + without that particular port. PHY devices and link management ------------------------------- @@ -635,26 +727,198 @@ Power management ``BR_STATE_DISABLED`` and propagating changes to the hardware if this port is disabled while being a bridge member +Address databases +----------------- + +Switching hardware is expected to have a table for FDB entries, however not all +of them are active at the same time. An address database is the subset (partition) +of FDB entries that is active (can be matched by address learning on RX, or FDB +lookup on TX) depending on the state of the port. An address database may +occasionally be called "FID" (Filtering ID) in this document, although the +underlying implementation may choose whatever is available to the hardware. + +For example, all ports that belong to a VLAN-unaware bridge (which is +*currently* VLAN-unaware) are expected to learn source addresses in the +database associated by the driver with that bridge (and not with other +VLAN-unaware bridges). During forwarding and FDB lookup, a packet received on a +VLAN-unaware bridge port should be able to find a VLAN-unaware FDB entry having +the same MAC DA as the packet, which is present on another port member of the +same bridge. At the same time, the FDB lookup process must be able to not find +an FDB entry having the same MAC DA as the packet, if that entry points towards +a port which is a member of a different VLAN-unaware bridge (and is therefore +associated with a different address database). + +Similarly, each VLAN of each offloaded VLAN-aware bridge should have an +associated address database, which is shared by all ports which are members of +that VLAN, but not shared by ports belonging to different bridges that are +members of the same VID. + +In this context, a VLAN-unaware database means that all packets are expected to +match on it irrespective of VLAN ID (only MAC address lookup), whereas a +VLAN-aware database means that packets are supposed to match based on the VLAN +ID from the classified 802.1Q header (or the pvid if untagged). + +At the bridge layer, VLAN-unaware FDB entries have the special VID value of 0, +whereas VLAN-aware FDB entries have non-zero VID values. Note that a +VLAN-unaware bridge may have VLAN-aware (non-zero VID) FDB entries, and a +VLAN-aware bridge may have VLAN-unaware FDB entries. As in hardware, the +software bridge keeps separate address databases, and offloads to hardware the +FDB entries belonging to these databases, through switchdev, asynchronously +relative to the moment when the databases become active or inactive. + +When a user port operates in standalone mode, its driver should configure it to +use a separate database called a port private database. This is different from +the databases described above, and should impede operation as standalone port +(packet in, packet out to the CPU port) as little as possible. For example, +on ingress, it should not attempt to learn the MAC SA of ingress traffic, since +learning is a bridging layer service and this is a standalone port, therefore +it would consume useless space. With no address learning, the port private +database should be empty in a naive implementation, and in this case, all +received packets should be trivially flooded to the CPU port. + +DSA (cascade) and CPU ports are also called "shared" ports because they service +multiple address databases, and the database that a packet should be associated +to is usually embedded in the DSA tag. This means that the CPU port may +simultaneously transport packets coming from a standalone port (which were +classified by hardware in one address database), and from a bridge port (which +were classified to a different address database). + +Switch drivers which satisfy certain criteria are able to optimize the naive +configuration by removing the CPU port from the flooding domain of the switch, +and just program the hardware with FDB entries pointing towards the CPU port +for which it is known that software is interested in those MAC addresses. +Packets which do not match a known FDB entry will not be delivered to the CPU, +which will save CPU cycles required for creating an skb just to drop it. + +DSA is able to perform host address filtering for the following kinds of +addresses: + +- Primary unicast MAC addresses of ports (``dev->dev_addr``). These are + associated with the port private database of the respective user port, + and the driver is notified to install them through ``port_fdb_add`` towards + the CPU port. + +- Secondary unicast and multicast MAC addresses of ports (addresses added + through ``dev_uc_add()`` and ``dev_mc_add()``). These are also associated + with the port private database of the respective user port. + +- Local/permanent bridge FDB entries (``BR_FDB_LOCAL``). These are the MAC + addresses of the bridge ports, for which packets must be terminated locally + and not forwarded. They are associated with the address database for that + bridge. + +- Static bridge FDB entries installed towards foreign (non-DSA) interfaces + present in the same bridge as some DSA switch ports. These are also + associated with the address database for that bridge. + +- Dynamically learned FDB entries on foreign interfaces present in the same + bridge as some DSA switch ports, only if ``ds->assisted_learning_on_cpu_port`` + is set to true by the driver. These are associated with the address database + for that bridge. + +For various operations detailed below, DSA provides a ``dsa_db`` structure +which can be of the following types: + +- ``DSA_DB_PORT``: the FDB (or MDB) entry to be installed or deleted belongs to + the port private database of user port ``db->dp``. +- ``DSA_DB_BRIDGE``: the entry belongs to one of the address databases of bridge + ``db->bridge``. Separation between the VLAN-unaware database and the per-VID + databases of this bridge is expected to be done by the driver. +- ``DSA_DB_LAG``: the entry belongs to the address database of LAG ``db->lag``. + Note: ``DSA_DB_LAG`` is currently unused and may be removed in the future. + +The drivers which act upon the ``dsa_db`` argument in ``port_fdb_add``, +``port_mdb_add`` etc should declare ``ds->fdb_isolation`` as true. + +DSA associates each offloaded bridge and each offloaded LAG with a one-based ID +(``struct dsa_bridge :: num``, ``struct dsa_lag :: id``) for the purposes of +refcounting addresses on shared ports. Drivers may piggyback on DSA's numbering +scheme (the ID is readable through ``db->bridge.num`` and ``db->lag.id`` or may +implement their own. + +Only the drivers which declare support for FDB isolation are notified of FDB +entries on the CPU port belonging to ``DSA_DB_PORT`` databases. +For compatibility/legacy reasons, ``DSA_DB_BRIDGE`` addresses are notified to +drivers even if they do not support FDB isolation. However, ``db->bridge.num`` +and ``db->lag.id`` are always set to 0 in that case (to denote the lack of +isolation, for refcounting purposes). + +Note that it is not mandatory for a switch driver to implement physically +separate address databases for each standalone user port. Since FDB entries in +the port private databases will always point to the CPU port, there is no risk +for incorrect forwarding decisions. In this case, all standalone ports may +share the same database, but the reference counting of host-filtered addresses +(not deleting the FDB entry for a port's MAC address if it's still in use by +another port) becomes the responsibility of the driver, because DSA is unaware +that the port databases are in fact shared. This can be achieved by calling +``dsa_fdb_present_in_other_db()`` and ``dsa_mdb_present_in_other_db()``. +The down side is that the RX filtering lists of each user port are in fact +shared, which means that user port A may accept a packet with a MAC DA it +shouldn't have, only because that MAC address was in the RX filtering list of +user port B. These packets will still be dropped in software, however. + Bridge layer ------------ +Offloading the bridge forwarding plane is optional and handled by the methods +below. They may be absent, return -EOPNOTSUPP, or ``ds->max_num_bridges`` may +be non-zero and exceeded, and in this case, joining a bridge port is still +possible, but the packet forwarding will take place in software, and the ports +under a software bridge must remain configured in the same way as for +standalone operation, i.e. have all bridging service functions (address +learning etc) disabled, and send all received packets to the CPU port only. + +Concretely, a port starts offloading the forwarding plane of a bridge once it +returns success to the ``port_bridge_join`` method, and stops doing so after +``port_bridge_leave`` has been called. Offloading the bridge means autonomously +learning FDB entries in accordance with the software bridge port's state, and +autonomously forwarding (or flooding) received packets without CPU intervention. +This is optional even when offloading a bridge port. Tagging protocol drivers +are expected to call ``dsa_default_offload_fwd_mark(skb)`` for packets which +have already been autonomously forwarded in the forwarding domain of the +ingress switch port. DSA, through ``dsa_port_devlink_setup()``, considers all +switch ports part of the same tree ID to be part of the same bridge forwarding +domain (capable of autonomous forwarding to each other). + +Offloading the TX forwarding process of a bridge is a distinct concept from +simply offloading its forwarding plane, and refers to the ability of certain +driver and tag protocol combinations to transmit a single skb coming from the +bridge device's transmit function to potentially multiple egress ports (and +thereby avoid its cloning in software). + +Packets for which the bridge requests this behavior are called data plane +packets and have ``skb->offload_fwd_mark`` set to true in the tag protocol +driver's ``xmit`` function. Data plane packets are subject to FDB lookup, +hardware learning on the CPU port, and do not override the port STP state. +Additionally, replication of data plane packets (multicast, flooding) is +handled in hardware and the bridge driver will transmit a single skb for each +packet that may or may not need replication. + +When the TX forwarding offload is enabled, the tag protocol driver is +responsible to inject packets into the data plane of the hardware towards the +correct bridging domain (FID) that the port is a part of. The port may be +VLAN-unaware, and in this case the FID must be equal to the FID used by the +driver for its VLAN-unaware address database associated with that bridge. +Alternatively, the bridge may be VLAN-aware, and in that case, it is guaranteed +that the packet is also VLAN-tagged with the VLAN ID that the bridge processed +this packet in. It is the responsibility of the hardware to untag the VID on +the egress-untagged ports, or keep the tag on the egress-tagged ones. + - ``port_bridge_join``: bridge layer function invoked when a given switch port is added to a bridge, this function should do what's necessary at the switch level to permit the joining port to be added to the relevant logical domain for it to ingress/egress traffic with other members of the bridge. + By setting the ``tx_fwd_offload`` argument to true, the TX forwarding process + of this bridge is also offloaded. - ``port_bridge_leave``: bridge layer function invoked when a given switch port is removed from a bridge, this function should do what's necessary at the switch level to deny the leaving port from ingress/egress traffic from the - remaining bridge members. When the port leaves the bridge, it should be aged - out at the switch hardware for the switch to (re) learn MAC addresses behind - this port. + remaining bridge members. - ``port_stp_state_set``: bridge layer function invoked when a given switch port STP state is computed by the bridge layer and should be propagated to switch - hardware to forward/block/learn traffic. The switch driver is responsible for - computing a STP state change based on current and asked parameters and perform - the relevant ageing based on the intersection results + hardware to forward/block/learn traffic. - ``port_bridge_flags``: bridge layer function invoked when a port must configure its settings for e.g. flooding of unknown traffic or source address @@ -667,21 +931,11 @@ Bridge layer CPU port, and flooding towards the CPU port should also be enabled, due to a lack of an explicit address filtering mechanism in the DSA core. -- ``port_bridge_tx_fwd_offload``: bridge layer function invoked after - ``port_bridge_join`` when a driver sets ``ds->num_fwd_offloading_bridges`` to - a non-zero value. Returning success in this function activates the TX - forwarding offload bridge feature for this port, which enables the tagging - protocol driver to inject data plane packets towards the bridging domain that - the port is a part of. Data plane packets are subject to FDB lookup, hardware - learning on the CPU port, and do not override the port STP state. - Additionally, replication of data plane packets (multicast, flooding) is - handled in hardware and the bridge driver will transmit a single skb for each - packet that needs replication. The method is provided as a configuration - point for drivers that need to configure the hardware for enabling this - feature. - -- ``port_bridge_tx_fwd_unoffload``: bridge layer function invoked when a driver - leaves a bridge port which had the TX forwarding offload feature enabled. +- ``port_fast_age``: bridge layer function invoked when flushing the + dynamically learned FDB entries on the port is necessary. This is called when + transitioning from an STP state where learning should take place to an STP + state where it shouldn't, or when leaving a bridge, or when address learning + is turned off via ``port_bridge_flags``. Bridge VLAN filtering --------------------- @@ -697,55 +951,44 @@ Bridge VLAN filtering allowed. - ``port_vlan_add``: bridge layer function invoked when a VLAN is configured - (tagged or untagged) for the given switch port. If the operation is not - supported by the hardware, this function should return ``-EOPNOTSUPP`` to - inform the bridge code to fallback to a software implementation. + (tagged or untagged) for the given switch port. The CPU port becomes a member + of a VLAN only if a foreign bridge port is also a member of it (and + forwarding needs to take place in software), or the VLAN is installed to the + VLAN group of the bridge device itself, for termination purposes + (``bridge vlan add dev br0 vid 100 self``). VLANs on shared ports are + reference counted and removed when there is no user left. Drivers do not need + to manually install a VLAN on the CPU port. - ``port_vlan_del``: bridge layer function invoked when a VLAN is removed from the given switch port -- ``port_vlan_dump``: bridge layer function invoked with a switchdev callback - function that the driver has to call for each VLAN the given port is a member - of. A switchdev object is used to carry the VID and bridge flags. - - ``port_fdb_add``: bridge layer function invoked when the bridge wants to install a Forwarding Database entry, the switch hardware should be programmed with the specified address in the specified VLAN Id in the forwarding database - associated with this VLAN ID. If the operation is not supported, this - function should return ``-EOPNOTSUPP`` to inform the bridge code to fallback to - a software implementation. - -.. note:: VLAN ID 0 corresponds to the port private database, which, in the context - of DSA, would be its port-based VLAN, used by the associated bridge device. + associated with this VLAN ID. - ``port_fdb_del``: bridge layer function invoked when the bridge wants to remove a Forwarding Database entry, the switch hardware should be programmed to delete the specified MAC address from the specified VLAN ID if it was mapped into this port forwarding database -- ``port_fdb_dump``: bridge layer function invoked with a switchdev callback - function that the driver has to call for each MAC address known to be behind - the given port. A switchdev object is used to carry the VID and FDB info. +- ``port_fdb_dump``: bridge bypass function invoked by ``ndo_fdb_dump`` on the + physical DSA port interfaces. Since DSA does not attempt to keep in sync its + hardware FDB entries with the software bridge, this method is implemented as + a means to view the entries visible on user ports in the hardware database. + The entries reported by this function have the ``self`` flag in the output of + the ``bridge fdb show`` command. - ``port_mdb_add``: bridge layer function invoked when the bridge wants to install - a multicast database entry. If the operation is not supported, this function - should return ``-EOPNOTSUPP`` to inform the bridge code to fallback to a - software implementation. The switch hardware should be programmed with the + a multicast database entry. The switch hardware should be programmed with the specified address in the specified VLAN ID in the forwarding database associated with this VLAN ID. -.. note:: VLAN ID 0 corresponds to the port private database, which, in the context - of DSA, would be its port-based VLAN, used by the associated bridge device. - - ``port_mdb_del``: bridge layer function invoked when the bridge wants to remove a multicast database entry, the switch hardware should be programmed to delete the specified MAC address from the specified VLAN ID if it was mapped into this port forwarding database. -- ``port_mdb_dump``: bridge layer function invoked with a switchdev callback - function that the driver has to call for each MAC address known to be behind - the given port. A switchdev object is used to carry the VID and MDB info. - Link aggregation ---------------- diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst index 04216564a03c..d7a1bf1a55b5 100644 --- a/Documentation/networking/ip-sysctl.rst +++ b/Documentation/networking/ip-sysctl.rst @@ -1052,11 +1052,7 @@ udp_rmem_min - INTEGER Default: 4K udp_wmem_min - INTEGER - Minimal size of send buffer used by UDP sockets in moderation. - Each UDP socket is able to use the size for sending data, even if - total pages of UDP sockets exceed udp_mem pressure. The unit is byte. - - Default: 4K + UDP does not have tx memory accounting and this tunable has no effect. RAW variables ============= @@ -1085,7 +1081,7 @@ cipso_cache_enable - BOOLEAN cipso_cache_bucket_size - INTEGER The CIPSO label cache consists of a fixed size hash table with each hash bucket containing a number of cache entries. This variable limits - the number of entries in each hash bucket; the larger the value the + the number of entries in each hash bucket; the larger the value is, the more CIPSO label mappings that can be cached. When the number of entries in a given hash bucket reaches this limit adding new entries causes the oldest entry in the bucket to be removed to make room. @@ -1179,7 +1175,7 @@ ip_autobind_reuse - BOOLEAN option should only be set by experts. Default: 0 -ip_dynaddr - BOOLEAN +ip_dynaddr - INTEGER If set non-zero, enables support for dynamic addresses. If set to a non-zero value larger than 1, a kernel log message will be printed when dynamic address rewriting @@ -2870,7 +2866,14 @@ sctp_rmem - vector of 3 INTEGERs: min, default, max Default: 4K sctp_wmem - vector of 3 INTEGERs: min, default, max - Currently this tunable has no effect. + Only the first value ("min") is used, "default" and "max" are + ignored. + + min: Minimum size of send buffer that can be used by SCTP sockets. + It is guaranteed to each SCTP socket (but not association) even + under moderate memory pressure. + + Default: 4K addr_scope_policy - INTEGER Control IPv4 address scoping - draft-stewart-tsvwg-sctp-ipv4-00 @@ -2925,6 +2928,43 @@ plpmtud_probe_interval - INTEGER Default: 0 +reconf_enable - BOOLEAN + Enable or disable extension of Stream Reconfiguration functionality + specified in RFC6525. This extension provides the ability to "reset" + a stream, and it includes the Parameters of "Outgoing/Incoming SSN + Reset", "SSN/TSN Reset" and "Add Outgoing/Incoming Streams". + + - 1: Enable extension. + - 0: Disable extension. + + Default: 0 + +intl_enable - BOOLEAN + Enable or disable extension of User Message Interleaving functionality + specified in RFC8260. This extension allows the interleaving of user + messages sent on different streams. With this feature enabled, I-DATA + chunk will replace DATA chunk to carry user messages if also supported + by the peer. Note that to use this feature, one needs to set this option + to 1 and also needs to set socket options SCTP_FRAGMENT_INTERLEAVE to 2 + and SCTP_INTERLEAVING_SUPPORTED to 1. + + - 1: Enable extension. + - 0: Disable extension. + + Default: 0 + +ecn_enable - BOOLEAN + Control use of Explicit Congestion Notification (ECN) by SCTP. + Like in TCP, ECN is used only when both ends of the SCTP connection + indicate support for it. This feature is useful in avoiding losses + due to congestion by allowing supporting routers to signal congestion + before having to drop packets. + + 1: Enable ecn. + 0: Disable ecn. + + Default: 1 + ``/proc/sys/net/core/*`` ======================== diff --git a/Documentation/networking/phy.rst b/Documentation/networking/phy.rst index d43da709bf40..704f31da5167 100644 --- a/Documentation/networking/phy.rst +++ b/Documentation/networking/phy.rst @@ -104,7 +104,7 @@ Whenever possible, use the PHY side RGMII delay for these reasons: * PHY device drivers in PHYLIB being reusable by nature, being able to configure correctly a specified delay enables more designs with similar delay - requirements to be operate correctly + requirements to be operated correctly For cases where the PHY is not capable of providing this delay, but the Ethernet MAC driver is capable of doing so, the correct phy_interface_t value diff --git a/Documentation/power/energy-model.rst b/Documentation/power/energy-model.rst index feb257b7f350..ef341be2882b 100644 --- a/Documentation/power/energy-model.rst +++ b/Documentation/power/energy-model.rst @@ -20,20 +20,20 @@ possible source of information on its own, the EM framework intervenes as an abstraction layer which standardizes the format of power cost tables in the kernel, hence enabling to avoid redundant work. -The power values might be expressed in milli-Watts or in an 'abstract scale'. +The power values might be expressed in micro-Watts or in an 'abstract scale'. Multiple subsystems might use the EM and it is up to the system integrator to check that the requirements for the power value scale types are met. An example can be found in the Energy-Aware Scheduler documentation Documentation/scheduler/sched-energy.rst. For some subsystems like thermal or powercap power values expressed in an 'abstract scale' might cause issues. These subsystems are more interested in estimation of power used in the past, -thus the real milli-Watts might be needed. An example of these requirements can +thus the real micro-Watts might be needed. An example of these requirements can be found in the Intelligent Power Allocation in Documentation/driver-api/thermal/power_allocator.rst. Kernel subsystems might implement automatic detection to check whether EM registered devices have inconsistent scale (based on EM internal flag). Important thing to keep in mind is that when the power values are expressed in -an 'abstract scale' deriving real energy in milli-Joules would not be possible. +an 'abstract scale' deriving real energy in micro-Joules would not be possible. The figure below depicts an example of drivers (Arm-specific here, but the approach is applicable to any architecture) providing power costs to the EM @@ -98,7 +98,7 @@ Drivers are expected to register performance domains into the EM framework by calling the following API:: int em_dev_register_perf_domain(struct device *dev, unsigned int nr_states, - struct em_data_callback *cb, cpumask_t *cpus, bool milliwatts); + struct em_data_callback *cb, cpumask_t *cpus, bool microwatts); Drivers must provide a callback function returning <frequency, power> tuples for each performance state. The callback function provided by the driver is free @@ -106,10 +106,10 @@ to fetch data from any relevant location (DT, firmware, ...), and by any mean deemed necessary. Only for CPU devices, drivers must specify the CPUs of the performance domains using cpumask. For other devices than CPUs the last argument must be set to NULL. -The last argument 'milliwatts' is important to set with correct value. Kernel +The last argument 'microwatts' is important to set with correct value. Kernel subsystems which use EM might rely on this flag to check if all EM devices use the same scale. If there are different scales, these subsystems might decide -to: return warning/error, stop working or panic. +to return warning/error, stop working or panic. See Section 3. for an example of driver implementing this callback, or Section 2.4 for further documentation on this API @@ -137,7 +137,7 @@ The .get_cost() allows to provide the 'cost' values which reflect the efficiency of the CPUs. This would allow to provide EAS information which has different relation than what would be forced by the EM internal formulas calculating 'cost' values. To register an EM for such platform, the -driver must set the flag 'milliwatts' to 0, provide .get_power() callback +driver must set the flag 'microwatts' to 0, provide .get_power() callback and provide .get_cost() callback. The EM framework would handle such platform properly during registration. A flag EM_PERF_DOMAIN_ARTIFICIAL is set for such platform. Special care should be taken by other frameworks which are using EM diff --git a/Documentation/power/pci.rst b/Documentation/power/pci.rst index b04fb18cc4e2..a125544b4cb6 100644 --- a/Documentation/power/pci.rst +++ b/Documentation/power/pci.rst @@ -315,7 +315,7 @@ that these callbacks operate on:: configuration space */ unsigned int pme_support:5; /* Bitmask of states from which PME# can be generated */ - unsigned int pme_interrupt:1;/* Is native PCIe PME signaling used? */ + unsigned int pme_poll:1; /* Poll device's PME status bit */ unsigned int d1_support:1; /* Low power state D1 is supported */ unsigned int d2_support:1; /* Low power state D2 is supported */ unsigned int no_d1d2:1; /* D1 and D2 are forbidden */ diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index bd36ecb29409..906235c11c24 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -10,8 +10,7 @@ of conventions and procedures which are used in the posting of patches; following them will make life much easier for everybody involved. This document will attempt to cover these expectations in reasonable detail; more information can also be found in the files -:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`, -:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` +:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` and :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`. diff --git a/Documentation/process/8.Conclusion.rst b/Documentation/process/8.Conclusion.rst index b32a40215858..8c847dffe76b 100644 --- a/Documentation/process/8.Conclusion.rst +++ b/Documentation/process/8.Conclusion.rst @@ -5,15 +5,13 @@ For more information There are numerous sources of information on Linux kernel development and related topics. First among those will always be the Documentation -directory found in the kernel source distribution. The top-level :ref:`process/howto.rst <process_howto>` -file is an important starting point; :ref:`process/submitting-patches.rst <submittingpatches>` -and :ref:`process/submitting-drivers.rst <submittingdrivers>` -are also something which all kernel developers should -read. Many internal kernel APIs are documented using the kerneldoc -mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those -documents in HTML or PDF format (though the version of TeX shipped by some -distributions runs into internal limits and fails to process the documents -properly). +directory found in the kernel source distribution. Start with the +top-level :ref:`process/howto.rst <process_howto>`; also read +:ref:`process/submitting-patches.rst <submittingpatches>`. Many internal +kernel APIs are documented using the kerneldoc mechanism; "make htmldocs" +or "make pdfdocs" can be used to generate those documents in HTML or PDF +format (though the version of TeX shipped by some distributions runs into +internal limits and fails to process the documents properly). Various web sites discuss kernel development at all levels of detail. Your author would like to humbly suggest https://lwn.net/ as a source; diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst index 16586f6cc888..fc2c46f3f82d 100644 --- a/Documentation/process/email-clients.rst +++ b/Documentation/process/email-clients.rst @@ -277,36 +277,61 @@ Thunderbird (GUI) Thunderbird is an Outlook clone that likes to mangle text, but there are ways to coerce it into behaving. +After doing the modifications, this includes installing the extensions, +you need to restart Thunderbird. + - Allow use of an external editor: - The easiest thing to do with Thunderbird and patches is to use an - "external editor" extension and then just use your favorite ``$EDITOR`` - for reading/merging patches into the body text. To do this, download - and install the extension, then add a button for it using - :menuselection:`View-->Toolbars-->Customize...` and finally just click on it - when in the :menuselection:`Compose` dialog. - - Please note that "external editor" requires that your editor must not - fork, or in other words, the editor must not return before closing. - You may have to pass additional flags or change the settings of your - editor. Most notably if you are using gvim then you must pass the -f - option to gvim by putting ``/usr/bin/gvim -f`` (if the binary is in - ``/usr/bin``) to the text editor field in :menuselection:`external editor` - settings. If you are using some other editor then please read its manual - to find out how to do this. + + The easiest thing to do with Thunderbird and patches is to use extensions + which open your favorite external editor. + + Here are some example extensions which are capable of doing this. + + - "External Editor Revived" + + https://github.com/Frederick888/external-editor-revived + + https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor-revived/ + + It requires installing a "native messaging host". + Please read the wiki which can be found here: + https://github.com/Frederick888/external-editor-revived/wiki + + - "External Editor" + + https://github.com/exteditor/exteditor + + To do this, download and install the extension, then open the + :menuselection:`compose` window, add a button for it using + :menuselection:`View-->Toolbars-->Customize...` + then just click on the new button when you wish to use the external editor. + + Please note that "External Editor" requires that your editor must not + fork, or in other words, the editor must not return before closing. + You may have to pass additional flags or change the settings of your + editor. Most notably if you are using gvim then you must pass the -f + option to gvim by putting ``/usr/bin/gvim --nofork"`` (if the binary is in + ``/usr/bin``) to the text editor field in :menuselection:`external editor` + settings. If you are using some other editor then please read its manual + to find out how to do this. To beat some sense out of the internal editor, do this: -- Edit your Thunderbird config settings so that it won't use ``format=flowed``. - Go to :menuselection:`edit-->preferences-->advanced-->config editor` to bring up - the thunderbird's registry editor. +- Edit your Thunderbird config settings so that it won't use ``format=flowed``! + Go to your main window and find the button for your main dropdown menu. + :menuselection:`Main Menu-->Preferences-->General-->Config Editor...` + to bring up the thunderbird's registry editor. -- Set ``mailnews.send_plaintext_flowed`` to ``false`` + - Set ``mailnews.send_plaintext_flowed`` to ``false`` -- Set ``mailnews.wraplength`` from ``72`` to ``0`` + - Set ``mailnews.wraplength`` from ``72`` to ``0`` -- :menuselection:`View-->Message Body As-->Plain Text` +- Don't write HTML messages! Go to the main window + :menuselection:`Main Menu-->Account Settings-->youracc@server.something-->Composition & Addressing`! + There you can disable the option "Compose messages in HTML format". -- :menuselection:`View-->Character Encoding-->Unicode (UTF-8)` +- Open messages only as plain text! Go to the main window + :menuselection:`Main Menu-->View-->Message Body As-->Plain Text`! TkRat (GUI) *********** diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index e4beeca57e5f..cd6997a9d203 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -105,8 +105,8 @@ required reading: patches if these rules are followed, and many people will only review code if it is in the proper style. - :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` and :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` - These files describe in explicit detail how to successfully create + :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` + This file describes in explicit detail how to successfully create and send a patch, including (but not limited to): - Email contents diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 3587dae4d0ef..2ba2a1582bbe 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -40,7 +40,6 @@ Other guides to the community that are of interest to most developers are: :maxdepth: 1 changes - submitting-drivers stable-api-nonsense management-style stable-kernel-rules diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index da9527502ef0..502289d63385 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -1,9 +1,10 @@ .. _kernel_docs: -Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel -============================================================================================= +Index of Further Kernel Documentation +===================================== - Juan-Mariano de Goyeneche <jmseyas@dit.upm.es> +Initial Author: Juan-Mariano de Goyeneche (<jmseyas@dit.upm.es>; +email address is defunct now.) The need for a document like this one became apparent in the linux-kernel mailing list as the same questions, asking for pointers @@ -16,21 +17,16 @@ philosophy and design decisions behind this code. Unfortunately, not many documents are available for beginners to start. And, even if they exist, there was no "well-known" place which -kept track of them. These lines try to cover this lack. All documents -available on line known by the author are listed, while some reference -books are also mentioned. +kept track of them. These lines try to cover this lack. PLEASE, if you know any paper not listed here or write a new document, -send me an e-mail, and I'll include a reference to it here. Any -corrections, ideas or comments are also welcomed. +include a reference to it here, following the kernel's patch submission +process. Any corrections, ideas or comments are also welcome. -The papers that follow are listed in no particular order. All are -cataloged with the following fields: the document's "Title", the -"Author"/s, the "URL" where they can be found, some "Keywords" helpful -when searching for specific topics, and a brief "Description" of the -Document. - -Enjoy! +All documents are cataloged with the following fields: the document's +"Title", the "Author"/s, the "URL" where they can be found, some +"Keywords" helpful when searching for specific topics, and a brief +"Description" of the Document. .. note:: @@ -83,6 +79,18 @@ On-line docs Finally this trace-log is used as base for more a exact conceptual exploration and description of the Linux TCP/IP implementation.* + * Title: **The Linux Kernel Module Programming Guide** + + :Author: Peter Jay Salzman, Michael Burian, Ori Pomerantz, Bob Mottram, + Jim Huang. + :URL: https://sysprog21.github.io/lkmpg/ + :Date: 2021 + :Keywords: modules, GPL book, /proc, ioctls, system calls, + interrupt handlers . + :Description: A very nice GPL book on the topic of modules + programming. Lots of examples. Currently the new version is being + actively maintained at https://github.com/sysprog21/lkmpg. + * Title: **On submitting kernel Patches** :Author: Andi Kleen @@ -126,17 +134,19 @@ On-line docs describes how to write user-mode utilities for communicating with Card Services. - * Title: **The Linux Kernel Module Programming Guide** - - :Author: Peter Jay Salzman, Michael Burian, Ori Pomerantz, Bob Mottram, - Jim Huang. - :URL: https://sysprog21.github.io/lkmpg/ - :Date: 2021 - :Keywords: modules, GPL book, /proc, ioctls, system calls, - interrupt handlers . - :Description: A very nice GPL book on the topic of modules - programming. Lots of examples. Currently the new version is being - actively maintained at https://github.com/sysprog21/lkmpg. + * Title: **How NOT to write kernel drivers** + + :Author: Arjan van de Ven. + :URL: https://landley.net/kdocs/ols/2002/ols2002-pages-545-555.pdf + :Date: 2002 + :Keywords: driver. + :Description: Programming bugs and Do-nots in kernel driver development + :Abstract: *Quit a few tutorials, articles and books give an introduction + on how to write Linux kernel drivers. Unfortunately the things one + should NOT do in Linux kernel code is either only a minor appendix + or, more commonly, completely absent. This paper tries to briefly touch + the areas in which the most common and serious bugs and do-nots are + encountered.* * Title: **Global spinlock list and usage** diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst index c456b5225d66..d14007081595 100644 --- a/Documentation/process/maintainer-netdev.rst +++ b/Documentation/process/maintainer-netdev.rst @@ -6,6 +6,15 @@ netdev FAQ ========== +tl;dr +----- + + - designate your patch to a tree - ``[PATCH net]`` or ``[PATCH net-next]`` + - for fixes the ``Fixes:`` tag is required, regardless of the tree + - don't post large series (> 15 patches), break them up + - don't repost your patches within one 24h period + - reverse xmas tree + What is netdev? --------------- It is a mailing list for all network-related Linux stuff. This @@ -136,6 +145,20 @@ it to the maintainer to figure out what is the most recent and current version that should be applied. If there is any doubt, the maintainer will reply and ask what should be done. +How do I divide my work into patches? +------------------------------------- + +Put yourself in the shoes of the reviewer. Each patch is read separately +and therefore should constitute a comprehensible step towards your stated +goal. + +Avoid sending series longer than 15 patches. Larger series takes longer +to review as reviewers will defer looking at it until they find a large +chunk of time. A small series can be reviewed in a short time, so Maintainers +just do it. As a result, a sequence of smaller series gets merged quicker and +with better review coverage. Re-posting large series also increases the mailing +list traffic. + I made changes to only a few patches in a patch series should I resend only those changed? ------------------------------------------------------------------------------------------ No, please resend the entire patch series and make sure you do number your @@ -183,6 +206,19 @@ it is requested that you make it look like this:: * another line of text */ +What is "reverse xmas tree"? +---------------------------- + +Netdev has a convention for ordering local variables in functions. +Order the variable declaration lines longest to shortest, e.g.:: + + struct scatterlist *sg; + struct sk_buff *skb; + int err, i; + +If there are dependencies between the variables preventing the ordering +move the initialization out of line. + I am working in existing code which uses non-standard formatting. Which formatting should I use? ------------------------------------------------------------------------------------------------ Make your code follow the most recent guidelines, so that eventually all code diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst deleted file mode 100644 index 8413b693d10d..000000000000 --- a/Documentation/process/submitting-drivers.rst +++ /dev/null @@ -1,194 +0,0 @@ -.. _submittingdrivers: - -Submitting Drivers For The Linux Kernel -======================================= - -This document is intended to explain how to submit device drivers to the -various kernel trees. Note that if you are interested in video card drivers -you should probably talk to XFree86 (https://www.xfree86.org/) and/or X.Org -(https://x.org/) instead. - -.. note:: - - This document is old and has seen little maintenance in recent years; it - should probably be updated or, perhaps better, just deleted. Most of - what is here can be found in the other development documents anyway. - - Oh, and we don't really recommend submitting changes to XFree86 :) - -Also read the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` -document. - - -Allocating Device Numbers -------------------------- - -Major and minor numbers for block and character devices are allocated -by the Linux assigned name and number authority (currently this is -Torben Mathiasen). The site is https://www.lanana.org/. This -also deals with allocating numbers for devices that are not going to -be submitted to the mainstream kernel. -See :ref:`Documentation/admin-guide/devices.rst <admin_devices>` -for more information on this. - -If you don't use assigned numbers then when your device is submitted it will -be given an assigned number even if that is different from values you may -have shipped to customers before. - -Who To Submit Drivers To ------------------------- - -Linux 2.0: - No new drivers are accepted for this kernel tree. - -Linux 2.2: - No new drivers are accepted for this kernel tree. - -Linux 2.4: - If the code area has a general maintainer then please submit it to - the maintainer listed in MAINTAINERS in the kernel file. If the - maintainer does not respond or you cannot find the appropriate - maintainer then please contact Willy Tarreau <w@1wt.eu>. - -Linux 2.6 and upper: - The same rules apply as 2.4 except that you should follow linux-kernel - to track changes in API's. The final contact point for Linux 2.6+ - submissions is Andrew Morton. - -What Criteria Determine Acceptance ----------------------------------- - -Licensing: - The code must be released to us under the - GNU General Public License. If you wish the driver to be - useful to other communities such as BSD you may release - under multiple licenses. If you choose to release under - licenses other than the GPL, you should include your - rationale for your license choices in your cover letter. - See accepted licenses at include/linux/module.h - -Copyright: - The copyright owner must agree to use of GPL. - It's best if the submitter and copyright owner - are the same person/entity. If not, the name of - the person/entity authorizing use of GPL should be - listed in case it's necessary to verify the will of - the copyright owner. - -Interfaces: - If your driver uses existing interfaces and behaves like - other drivers in the same class it will be much more likely - to be accepted than if it invents gratuitous new ones. - If you need to implement a common API over Linux and NT - drivers do it in userspace. - -Code: - Please use the Linux style of code formatting as documented - in :ref:`Documentation/process/coding-style.rst <codingStyle>`. - If you have sections of code - that need to be in other formats, for example because they - are shared with a windows driver kit and you want to - maintain them just once separate them out nicely and note - this fact. - -Portability: - Pointers are not always 32bits, not all computers are little - endian, people do not all have floating point and you - shouldn't use inline x86 assembler in your driver without - careful thought. Pure x86 drivers generally are not popular. - If you only have x86 hardware it is hard to test portability - but it is easy to make sure the code can easily be made - portable. - -Clarity: - It helps if anyone can see how to fix the driver. It helps - you because you get patches not bug reports. If you submit a - driver that intentionally obfuscates how the hardware works - it will go in the bitbucket. - -PM support: - Since Linux is used on many portable and desktop systems, your - driver is likely to be used on such a system and therefore it - should support basic power management by implementing, if - necessary, the .suspend and .resume methods used during the - system-wide suspend and resume transitions. You should verify - that your driver correctly handles the suspend and resume, but - if you are unable to ensure that, please at least define the - .suspend method returning the -ENOSYS ("Function not - implemented") error. You should also try to make sure that your - driver uses as little power as possible when it's not doing - anything. For the driver testing instructions see - Documentation/power/drivers-testing.rst and for a relatively - complete overview of the power management issues related to - drivers see :ref:`Documentation/driver-api/pm/devices.rst <driverapi_pm_devices>`. - -Control: - In general if there is active maintenance of a driver by - the author then patches will be redirected to them unless - they are totally obvious and without need of checking. - If you want to be the contact and update point for the - driver it is a good idea to state this in the comments, - and include an entry in MAINTAINERS for your driver. - -What Criteria Do Not Determine Acceptance ------------------------------------------ - -Vendor: - Being the hardware vendor and maintaining the driver is - often a good thing. If there is a stable working driver from - other people already in the tree don't expect 'we are the - vendor' to get your driver chosen. Ideally work with the - existing driver author to build a single perfect driver. - -Author: - It doesn't matter if a large Linux company wrote the driver, - or you did. Nobody has any special access to the kernel - tree. Anyone who tells you otherwise isn't telling the - whole story. - - -Resources ---------- - -Linux kernel master tree: - ftp.\ *country_code*\ .kernel.org:/pub/linux/kernel/... - - where *country_code* == your country code, such as - **us**, **uk**, **fr**, etc. - - https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git - -Linux kernel mailing list: - linux-kernel@vger.kernel.org - [mail majordomo@vger.kernel.org to subscribe] - -Linux Device Drivers, Third Edition (covers 2.6.10): - https://lwn.net/Kernel/LDD3/ (free version) - -LWN.net: - Weekly summary of kernel development activity - https://lwn.net/ - - 2.6 API changes: - - https://lwn.net/Articles/2.6-kernel-api/ - - Porting drivers from prior kernels to 2.6: - - https://lwn.net/Articles/driver-porting/ - -KernelNewbies: - Documentation and assistance for new kernel programmers - - https://kernelnewbies.org/ - -Linux USB project: - http://www.linux-usb.org/ - -How to NOT write kernel driver by Arjan van de Ven: - https://landley.net/kdocs/ols/2002/ols2002-pages-545-555.pdf - -Kernel Janitor: - https://kernelnewbies.org/KernelJanitors - -GIT, Fast Version Control System: - https://git-scm.com/ diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index a1cb6280fbcf..be49d8f2601b 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -12,9 +12,8 @@ This document contains a large number of suggestions in a relatively terse format. For detailed information on how the kernel development process works, see Documentation/process/development-process.rst. Also, read Documentation/process/submit-checklist.rst -for a list of items to check before submitting code. If you are submitting -a driver, also read Documentation/process/submitting-drivers.rst; for device -tree binding patches, read +for a list of items to check before submitting code. +For device tree binding patches, read Documentation/devicetree/bindings/submitting-patches.rst. This documentation assumes that you're using ``git`` to prepare your patches. diff --git a/Documentation/scsi/scsi_eh.rst b/Documentation/scsi/scsi_eh.rst index 885395dc1f15..bad624fab823 100644 --- a/Documentation/scsi/scsi_eh.rst +++ b/Documentation/scsi/scsi_eh.rst @@ -87,8 +87,7 @@ with the command. 1.2.2 Completing a scmd w/ timeout ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The timeout handler is scsi_times_out(). When a timeout occurs, this -function +The timeout handler is scsi_timeout(). When a timeout occurs, this function 1. invokes optional hostt->eh_timed_out() callback. Return value can be one of diff --git a/Documentation/scsi/scsi_mid_low_api.rst b/Documentation/scsi/scsi_mid_low_api.rst index 63ddea2b9640..a8c5bd15a440 100644 --- a/Documentation/scsi/scsi_mid_low_api.rst +++ b/Documentation/scsi/scsi_mid_low_api.rst @@ -731,7 +731,7 @@ Details:: * Notes: If 'no_async_abort' is defined this callback * will be invoked from scsi_eh thread. No other commands * will then be queued on current host during eh. - * Otherwise it will be called whenever scsi_times_out() + * Otherwise it will be called whenever scsi_timeout() * is called due to a command timeout. * * Optionally defined in: LLD diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst index b3ed5c581034..811b905b56bf 100644 --- a/Documentation/security/keys/core.rst +++ b/Documentation/security/keys/core.rst @@ -1046,7 +1046,7 @@ The keyctl syscall functions are: "filter" is either NULL to remove a watch or a filter specification to indicate what events are required from the key. - See Documentation/watch_queue.rst for more information. + See Documentation/core-api/watch_queue.rst for more information. Note that only one watch may be emplaced for any particular { key, queue_fd } combination. diff --git a/Documentation/security/secrets/coco.rst b/Documentation/security/secrets/coco.rst index 262e7abb1b24..087e2d1ae38b 100644 --- a/Documentation/security/secrets/coco.rst +++ b/Documentation/security/secrets/coco.rst @@ -98,6 +98,6 @@ References See [sev-api-spec]_ for more info regarding SEV ``LAUNCH_SECRET`` operation. -.. [sev] Documentation/virt/kvm/amd-memory-encryption.rst +.. [sev] Documentation/virt/kvm/x86/amd-memory-encryption.rst .. [secrets-coco-abi] Documentation/ABI/testing/securityfs-secrets-coco .. [sev-api-spec] https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf diff --git a/Documentation/security/siphash.rst b/Documentation/security/siphash.rst index a10380cb78e5..023bd95c74a5 100644 --- a/Documentation/security/siphash.rst +++ b/Documentation/security/siphash.rst @@ -85,7 +85,7 @@ Often times the XuY functions will not be large enough, and instead you'll want to pass a pre-filled struct to siphash. When doing this, it's important to always ensure the struct has no padding holes. The easiest way to do this is to simply arrange the members of the struct in descending order of size, -and to use offsetendof() instead of sizeof() for getting the size. For +and to use offsetofend() instead of sizeof() for getting the size. For performance reasons, if possible, it's probably a good thing to align the struct to the right boundary. Here's an example:: diff --git a/Documentation/sound/soc/dai.rst b/Documentation/sound/soc/dai.rst index 009b07e5a0f3..bf8431386d26 100644 --- a/Documentation/sound/soc/dai.rst +++ b/Documentation/sound/soc/dai.rst @@ -10,7 +10,7 @@ AC97 ==== AC97 is a five wire interface commonly found on many PC sound cards. It is -now also popular in many portable devices. This DAI has a reset line and time +now also popular in many portable devices. This DAI has a RESET line and time multiplexes its data on its SDATA_OUT (playback) and SDATA_IN (capture) lines. The bit clock (BCLK) is always driven by the CODEC (usually 12.288MHz) and the frame (FRAME) (usually 48kHz) is always driven by the controller. Each AC97 diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index cc348b219fca..06b34740bf90 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -121,13 +121,20 @@ def markup_refs(docname, app, node): return repl # +# Keep track of cross-reference lookups that failed so we don't have to +# do them again. +# +failed_lookups = { } +def failure_seen(target): + return (target) in failed_lookups +def note_failure(target): + failed_lookups[target] = True + +# # In sphinx3 we can cross-reference to C macro and function, each one with its # own C role, but both match the same regex, so we try both. # def markup_func_ref_sphinx3(docname, app, match): - class_str = ['c-func', 'c-macro'] - reftype_str = ['function', 'macro'] - cdom = app.env.domains['c'] # # Go through the dance of getting an xref out of the C domain @@ -143,27 +150,28 @@ def markup_func_ref_sphinx3(docname, app, match): if base_target not in Skipnames: for target in possible_targets: - if target not in Skipfuncs: - for class_s, reftype_s in zip(class_str, reftype_str): - lit_text = nodes.literal(classes=['xref', 'c', class_s]) - lit_text += target_text - pxref = addnodes.pending_xref('', refdomain = 'c', - reftype = reftype_s, - reftarget = target, modname = None, - classname = None) - # - # XXX The Latex builder will throw NoUri exceptions here, - # work around that by ignoring them. - # - try: - xref = cdom.resolve_xref(app.env, docname, app.builder, - reftype_s, target, pxref, - lit_text) - except NoUri: - xref = None - - if xref: - return xref + if (target not in Skipfuncs) and not failure_seen(target): + lit_text = nodes.literal(classes=['xref', 'c', 'c-func']) + lit_text += target_text + pxref = addnodes.pending_xref('', refdomain = 'c', + reftype = 'function', + reftarget = target, + modname = None, + classname = None) + # + # XXX The Latex builder will throw NoUri exceptions here, + # work around that by ignoring them. + # + try: + xref = cdom.resolve_xref(app.env, docname, app.builder, + 'function', target, pxref, + lit_text) + except NoUri: + xref = None + + if xref: + return xref + note_failure(target) return target_text diff --git a/Documentation/staging/static-keys.rst b/Documentation/staging/static-keys.rst index 38290b9f25eb..b0a519f456cf 100644 --- a/Documentation/staging/static-keys.rst +++ b/Documentation/staging/static-keys.rst @@ -201,9 +201,6 @@ static_key->entry field makes use of the two least significant bits. * ``void arch_jump_label_transform(struct jump_entry *entry, enum jump_label_type type)``, see: arch/x86/kernel/jump_label.c -* ``__init_or_module void arch_jump_label_transform_static(struct jump_entry *entry, enum jump_label_type type)``, - see: arch/x86/kernel/jump_label.c - * ``struct jump_entry``, see: arch/x86/include/asm/jump_label.h diff --git a/Documentation/translations/it_IT/core-api/symbol-namespaces.rst b/Documentation/translations/it_IT/core-api/symbol-namespaces.rst index 42f5d04e38ec..0f6898860d6d 100644 --- a/Documentation/translations/it_IT/core-api/symbol-namespaces.rst +++ b/Documentation/translations/it_IT/core-api/symbol-namespaces.rst @@ -50,9 +50,9 @@ Di conseguenza, nella tabella dei simboli del kernel ci sarà una voce rappresentata dalla struttura ``kernel_symbol`` che avrà il campo ``namespace`` (spazio dei nomi) impostato. Un simbolo esportato senza uno spazio dei nomi avrà questo campo impostato a ``NULL``. Non esiste uno spazio dei nomi -di base. Il programma ``modpost`` e il codice in kernel/module.c usano lo spazio -dei nomi, rispettivamente, durante la compilazione e durante il caricamento -di un modulo. +di base. Il programma ``modpost`` e il codice in kernel/module/main.c usano lo +spazio dei nomi, rispettivamente, durante la compilazione e durante il +caricamento di un modulo. 2.2 Usare il simbolo di preprocessore DEFAULT_SYMBOL_NAMESPACE ============================================================== diff --git a/Documentation/translations/it_IT/devicetree/bindings/submitting-patches.rst b/Documentation/translations/it_IT/devicetree/bindings/submitting-patches.rst new file mode 100644 index 000000000000..b473cd2190be --- /dev/null +++ b/Documentation/translations/it_IT/devicetree/bindings/submitting-patches.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-ita.rst + +:Original: Documentation/devicetree/bindings/submitting-patches.rst + +================================================ +Sottomettere patch per devicetree (DT) *binding* +================================================ + +.. note:: to be translated diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst index 009cdac014b6..78082281acf9 100644 --- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst +++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst @@ -5,6 +5,7 @@ .. _it_kernel_doc: +================================= Scrivere i commenti in kernel-doc ================================= @@ -469,6 +470,7 @@ Il titolo che segue ``DOC:`` funziona da intestazione all'interno del file sorgente, ma anche come identificatore per l'estrazione di questi commenti di documentazione. Quindi, il titolo dev'essere unico all'interno del file. +======================================= Includere i commenti di tipo kernel-doc ======================================= diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst index 9762452c584c..64528790dc34 100644 --- a/Documentation/translations/it_IT/doc-guide/sphinx.rst +++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst @@ -5,8 +5,9 @@ .. _it_sphinxdoc: -Introduzione -============ +============================================= +Usare Sphinx per la documentazione del kernel +============================================= Il kernel Linux usa `Sphinx`_ per la generazione della documentazione a partire dai file `reStructuredText`_ che si trovano nella cartella ``Documentation``. @@ -158,6 +159,9 @@ Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``. +Potete anche personalizzare l'ouptut html passando un livello aggiuntivo +DOCS_CSS usando la rispettiva variabile d'ambiente ``DOCS_CSS``. + Potete eliminare la documentazione generata tramite il comando ``make cleandocs``. @@ -276,11 +280,11 @@ incrociato quando questa ha una voce nell'indice. Se trovate degli usi di Tabelle a liste --------------- -Raccomandiamo l'uso delle tabelle in formato lista (*list table*). Le tabelle -in formato lista sono liste di liste. In confronto all'ASCII-art potrebbero -non apparire di facile lettura nei file in formato testo. Il loro vantaggio è -che sono facili da creare o modificare e che la differenza di una modifica è -molto più significativa perché limitata alle modifiche del contenuto. +Il formato ``list-table`` può essere utile per tutte quelle tabelle che non +possono essere facilmente scritte usando il formato ASCII-art di Sphinx. Però, +questo genere di tabelle sono illeggibili per chi legge direttamente i file di +testo. Dunque, questo formato dovrebbe essere evitato senza forti argomenti che +ne giustifichino l'uso. La ``flat-table`` è anch'essa una lista di liste simile alle ``list-table`` ma con delle funzionalità aggiuntive: diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst index d5c521327f6a..560f1d0482d2 100644 --- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst @@ -129,8 +129,7 @@ eseguiti simultaneamente. .. warning:: Il nome 'tasklet' è ingannevole: non hanno niente a che fare - con i 'processi' ('tasks'), e probabilmente hanno più a che vedere - con qualche pessima vodka che Alexey Kuznetsov si fece a quel tempo. + con i 'processi' ('tasks'). Potete determinate se siete in un softirq (o tasklet) utilizzando la macro :c:func:`in_softirq()` (``include/linux/preempt.h``). @@ -308,7 +307,7 @@ esse copiano una quantità arbitraria di dati da e verso lo spazio utente. Al contrario di:c:func:`put_user()` e :c:func:`get_user()`, queste funzioni ritornano la quantità di dati copiati (0 è comunque un successo). -[Sì, questa stupida interfaccia mi imbarazza. La battaglia torna in auge anno +[Sì, questa interfaccia mi imbarazza. La battaglia torna in auge anno dopo anno. --RR] Le funzioni potrebbero dormire implicitamente. Queste non dovrebbero mai essere @@ -679,9 +678,8 @@ tutti sulle spine: questo riflette cambiamenti fondamentati (eg. la funzione non può più essere chiamata con le funzioni attive, o fa controlli aggiuntivi, o non fa più controlli che venivano fatti in precedenza). Solitamente a questo s'accompagna un'adeguata e completa nota sulla lista di discussone -linux-kernel; cercate negli archivi. -Solitamente eseguire una semplice sostituzione su tutto un file rendere -le cose **peggiori**. +più adatta; cercate negli archivi. Solitamente eseguire una semplice +sostituzione su tutto un file rendere le cose **peggiori**. Inizializzazione dei campi d'una struttura ------------------------------------------ @@ -759,14 +757,14 @@ Mettere le vostre cose nel kernel Al fine d'avere le vostre cose in ordine per l'inclusione ufficiale, o anche per avere patch pulite, c'è del lavoro amministrativo da fare: -- Trovare di chi è lo stagno in cui state pisciando. Guardare in cima +- Trovare chi è responsabile del codice che state modificando. Guardare in cima ai file sorgenti, all'interno del file ``MAINTAINERS``, ed alla fine di tutti nel file ``CREDITS``. Dovreste coordinarvi con queste persone per evitare di duplicare gli sforzi, o provare qualcosa che è già stato rigettato. Assicuratevi di mettere il vostro nome ed indirizzo email in cima a - tutti i file che create o che mangeggiate significativamente. Questo è + tutti i file che create o che maneggiate significativamente. Questo è il primo posto dove le persone guarderanno quando troveranno un baco, o quando **loro** vorranno fare una modifica. @@ -787,16 +785,15 @@ anche per avere patch pulite, c'è del lavoro amministrativo da fare: "obj-$(CONFIG_xxx) += xxx.o". La sintassi è documentata nel file ``Documentation/kbuild/makefiles.rst``. -- Aggiungete voi stessi in ``CREDITS`` se avete fatto qualcosa di notevole, - solitamente qualcosa che supera il singolo file (comunque il vostro nome - dovrebbe essere all'inizio dei file sorgenti). ``MAINTAINERS`` significa +- Aggiungete voi stessi in ``CREDITS`` se credete di aver fatto qualcosa di + notevole, solitamente qualcosa che supera il singolo file (comunque il vostro + nome dovrebbe essere all'inizio dei file sorgenti). ``MAINTAINERS`` significa che volete essere consultati quando vengono fatte delle modifiche ad un - sottosistema, e quando ci sono dei bachi; questo implica molto di più - di un semplice impegno su una parte del codice. + sottosistema, e quando ci sono dei bachi; questo implica molto di più di un + semplice impegno su una parte del codice. - Infine, non dimenticatevi di leggere - ``Documentation/process/submitting-patches.rst`` e possibilmente anche - ``Documentation/process/submitting-drivers.rst``. + ``Documentation/process/submitting-patches.rst``. Trucchetti del kernel ===================== diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst index 163f1bd4e857..51af37f2d621 100644 --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst @@ -102,16 +102,11 @@ che non esistano. Sincronizzazione nel kernel Linux ================================= -Se posso darvi un suggerimento: non dormite mai con qualcuno più pazzo di -voi. Ma se dovessi darvi un suggerimento sulla sincronizzazione: -**mantenetela semplice**. +Se dovessi darvi un suggerimento sulla sincronizzazione: **mantenetela +semplice**. Siate riluttanti nell'introduzione di nuovi *lock*. -Abbastanza strano, quest'ultimo è l'esatto opposto del mio suggerimento -su quando **avete** dormito con qualcuno più pazzo di voi. E dovreste -pensare a prendervi un cane bello grande. - I due principali tipi di *lock* nel kernel: spinlock e mutex ------------------------------------------------------------ @@ -316,7 +311,7 @@ Pete Zaitcev ci offre il seguente riassunto: - Se siete in un contesto utente (una qualsiasi chiamata di sistema) e volete sincronizzarvi con altri processi, usate i mutex. Potete trattenere - il mutex e dormire (``copy_from_user*(`` o ``kmalloc(x,GFP_KERNEL)``). + il mutex e dormire (``copy_from_user(`` o ``kmalloc(x,GFP_KERNEL)``). - Altrimenti (== i dati possono essere manipolati da un'interruzione) usate spin_lock_irqsave() e spin_unlock_irqrestore(). @@ -979,9 +974,6 @@ fallisce nel trovare quello che vuole, quindi rilascia il *lock* di lettura, trattiene un *lock* di scrittura ed inserisce un oggetto; questo genere di codice presenta una corsa critica. -Se non riuscite a capire il perché, per favore state alla larga dal mio -codice. - corsa fra temporizzatori: un passatempo del kernel -------------------------------------------------- diff --git a/Documentation/translations/it_IT/maintainer/configure-git.rst b/Documentation/translations/it_IT/maintainer/configure-git.rst new file mode 100644 index 000000000000..8316fa53946f --- /dev/null +++ b/Documentation/translations/it_IT/maintainer/configure-git.rst @@ -0,0 +1,10 @@ +.. include:: ../disclaimer-ita.rst + +:Original: Documentation/process/botching-up-ioctls.rst + +.. _it_configuregit: + +Configurare Git +=============== + +.. note:: To be translated diff --git a/Documentation/translations/it_IT/networking/netdev-FAQ.rst b/Documentation/translations/it_IT/networking/netdev-FAQ.rst index 7e2456bb7d92..8a1e049585c0 100644 --- a/Documentation/translations/it_IT/networking/netdev-FAQ.rst +++ b/Documentation/translations/it_IT/networking/netdev-FAQ.rst @@ -1,6 +1,6 @@ .. include:: ../disclaimer-ita.rst -:Original: :ref:`Documentation/networking/netdev-FAQ.rst <netdev-FAQ>` +:Original: :ref:`Documentation/process/maintainer-netdev.rst <netdev-FAQ>` .. _it_netdev-FAQ: diff --git a/Documentation/translations/it_IT/process/3.Early-stage.rst b/Documentation/translations/it_IT/process/3.Early-stage.rst index 443ac1e5558f..0809de39108a 100644 --- a/Documentation/translations/it_IT/process/3.Early-stage.rst +++ b/Documentation/translations/it_IT/process/3.Early-stage.rst @@ -168,14 +168,15 @@ in questa ricerca: .../scripts/get_maintainer.pl -Se questo script viene eseguito con l'opzione "-f" ritornerà il -manutentore(i) attuale per un dato file o cartella. Se viene passata una -patch sulla linea di comando, lo script elencherà i manutentori che -dovrebbero riceverne una copia. Ci sono svariate opzioni che regolano -quanto a fondo get_maintainer.pl debba cercare i manutentori; -siate quindi prudenti nell'utilizzare le opzioni più aggressive poiché -potreste finire per includere sviluppatori che non hanno un vero interesse -per il codice che state modificando. +Se questo script viene eseguito con l'opzione "-f" ritornerà il manutentore(i) +attuale per un dato file o cartella. Se viene passata una patch sulla linea di +comando, lo script elencherà i manutentori che dovrebbero riceverne una copia. +Questo è la maniera raccomandata (non quella con "-f") per ottenere la lista di +persone da aggiungere a Cc per le vostre patch. Ci sono svariate opzioni che +regolano quanto a fondo get_maintainer.pl debba cercare i manutentori; siate +quindi prudenti nell'utilizzare le opzioni più aggressive poiché potreste finire +per includere sviluppatori che non hanno un vero interesse per il codice che +state modificando. Se tutto ciò dovesse fallire, parlare con Andrew Morton potrebbe essere un modo efficace per capire chi è il manutentore di un dato pezzo di codice. diff --git a/Documentation/translations/it_IT/process/5.Posting.rst b/Documentation/translations/it_IT/process/5.Posting.rst index 1476d51eb5e5..cf92a16ed7e5 100644 --- a/Documentation/translations/it_IT/process/5.Posting.rst +++ b/Documentation/translations/it_IT/process/5.Posting.rst @@ -16,9 +16,8 @@ e di procedure per la pubblicazione delle patch; seguirle renderà la vita più facile a tutti quanti. Questo documento cercherà di coprire questi argomenti con un ragionevole livello di dettaglio; più informazioni possono essere trovare nella cartella 'Documentation', nei file -:ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`, -:ref:`translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>`, e -:ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`. +:ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>` +e :ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`. Quando pubblicarle @@ -214,13 +213,28 @@ irrilevanti (quelli generati dal processo di generazione, per esempio, o i file di backup del vostro editor). Il file "dontdiff" nella cartella Documentation potrà esservi d'aiuto su questo punto; passatelo a diff con l'opzione "-X". -Le etichette sopra menzionante sono usate per descrivere come i vari -sviluppatori sono stati associati allo sviluppo di una patch. Sono descritte -in dettaglio nel documento :ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`; -quello che segue è un breve riassunto. Ognuna di queste righe ha il seguente -formato: +Le etichette sopracitate danno un'idea di come una patch prende vita e sono +descritte nel dettaglio nel documento +:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`. +Qui di seguito un breve riassunto. -:: +Un'etichetta ci può dire quale commit ha introdotto il problema che viene corretto nella patch:: + + Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID") + +Un'altra etichetta viene usata per fornire collegamenti a pagine web contenenti +maggiori informazioni, per esempio un rapporto circa il baco risolto dalla +patch, oppure un documento con le specifiche implementate dalla patch:: + + Link: https://example.com/somewhere.html optional-other-stuff + +Alcuni manutentori aggiungono quest'etichetta alla patch per fare riferimento +alla più recente discussione pubblica. A volte questo è fatto automaticamente da +alcuni strumenti come b4 or un *hook* git come quello descritto qui +'Documentation/translations/it_IT/maintainer/configure-git.rst' + +Un terzo tipo di etichetta viene usato per indicare chi ha contribuito allo +sviluppo della patch. Tutte queste etichette seguono il formato:: tag: Full Name <email address> optional-other-stuff diff --git a/Documentation/translations/it_IT/process/8.Conclusion.rst b/Documentation/translations/it_IT/process/8.Conclusion.rst index 039bfc5a4108..32659ff467c0 100644 --- a/Documentation/translations/it_IT/process/8.Conclusion.rst +++ b/Documentation/translations/it_IT/process/8.Conclusion.rst @@ -13,9 +13,8 @@ e argomenti correlati. Primo tra questi sarà sempre la cartella Documentation che si trova nei sorgenti kernel. Il file :ref:`process/howto.rst <it_process_howto>` è un punto di partenza -importante; :ref:`process/submitting-patches.rst <it_submittingpatches>` e -:ref:`process/submitting-drivers.rst <it_submittingdrivers>` sono -anch'essi qualcosa che tutti gli sviluppatori del kernel dovrebbero leggere. +importante; :ref:`process/submitting-patches.rst <it_submittingpatches>` è +anch'esso qualcosa che tutti gli sviluppatori del kernel dovrebbero leggere. Molte API interne al kernel sono documentate utilizzando il meccanismo kerneldoc; "make htmldocs" o "make pdfdocs" possono essere usati per generare quei documenti in HTML o PDF (sebbene le versioni di TeX di alcune diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst index dc7193377b7f..10e0ef9c34b7 100644 --- a/Documentation/translations/it_IT/process/changes.rst +++ b/Documentation/translations/it_IT/process/changes.rst @@ -11,8 +11,8 @@ Requisiti minimi per compilare il kernel Introduzione ============ -Questo documento fornisce una lista dei software necessari per eseguire i -kernel 4.x. +Questo documento fornisce una lista dei software necessari per eseguire questa +versione del kernel. Questo documento è basato sul file "Changes" del kernel 2.0.x e quindi le persone che lo scrissero meritano credito (Jared Mauch, Axel Boldt, @@ -32,12 +32,13 @@ PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils. ====================== ================= ======================================== Programma Versione minima Comando per verificare la versione ====================== ================= ======================================== -GNU C 4.9 gcc --version -Clang/LLVM (optional) 10.0.1 clang --version +GNU C 5.1 gcc --version +Clang/LLVM (optional) 11.0.0 clang --version GNU make 3.81 make --version binutils 2.23 ld -v flex 2.5.35 flex --version bison 2.0 bison --version +pahole 1.16 pahole --version util-linux 2.10o fdformat --version kmod 13 depmod -V e2fsprogs 1.41.4 e2fsck -V @@ -58,6 +59,7 @@ iptables 1.4.2 iptables -V openssl & libcrypto 1.0.0 openssl version bc 1.06.95 bc --version Sphinx\ [#f1]_ 1.7 sphinx-build --version +cpio any cpio --version ====================== ================= ======================================== .. [#f1] Sphinx è necessario solo per produrre la documentazione del Kernel @@ -111,6 +113,16 @@ Bison Dalla versione 4.16, il sistema di compilazione, durante l'esecuzione, genera un parsificatore. Questo richiede bison 2.0 o successivo. +pahole +------ + +Dalla versione 5.2, quando viene impostato CONFIG_DEBUG_INFO_BTF, il sistema di +compilazione genera BTF (BPF Type Format) a partire da DWARF per vmlinux. Più +tardi anche per i moduli. Questo richiede pahole v1.16 o successivo. + +A seconda della distribuzione, lo si può trovare nei pacchetti 'dwarves' o +'pahole'. Oppure lo si può trovare qui: https://fedorapeople.org/~acme/dwarves/. + Perl ---- @@ -455,6 +467,11 @@ mcelog - <http://www.mcelog.org/> +cpio +---- + +- <https://www.gnu.org/software/cpio/> + Rete **** diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst index ecc74ba50d3e..a393ee4182af 100644 --- a/Documentation/translations/it_IT/process/coding-style.rst +++ b/Documentation/translations/it_IT/process/coding-style.rst @@ -466,14 +466,52 @@ la riga della parentesi graffa di chiusura. Ad esempio: } EXPORT_SYMBOL(system_is_up); +6.1) Prototipi di funzione +************************** + Nei prototipi di funzione, includete i nomi dei parametri e i loro tipi. Nonostante questo non sia richiesto dal linguaggio C, in Linux viene preferito perché è un modo semplice per aggiungere informazioni importanti per il lettore. -Non usate la parola chiave ``extern`` coi prototipi di funzione perché +Non usate la parola chiave ``extern`` con le dichiarazioni di funzione perché rende le righe più lunghe e non è strettamente necessario. +Quando scrivete i prototipi di funzione mantenete `l'ordine degli elementi <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_. + +Prendiamo questa dichiarazione di funzione come esempio:: + + __init void * __must_check action(enum magic value, size_t size, u8 count, + char *fmt, ...) __printf(4, 5) __malloc; + +L'ordine suggerito per gli elementi di un prototipo di funzione è il seguente: + +- classe d'archiviazione (in questo caso ``static __always_inline``. Da notare + che ``__always_inline`` è tecnicamente un attributo ma che viene trattato come + ``inline``) +- attributi della classe di archiviazione (in questo caso ``__init``, in altre + parole la sezione, ma anche cose tipo ``__cold``) +- il tipo di ritorno (in questo caso, ``void *``) +- attributi per il valore di ritorno (in questo caso, ``__must_check``) +- il nome della funzione (in questo caso, ``action``) +- i parametri della funzione(in questo caso, + ``(enum magic value, size_t size, u8 count, char *fmt, ...)``, + da notare che va messo anche il nome del parametro) +- attributi dei parametri (in questo caso, ``__printf(4, 5)``) +- attributi per il comportamento della funzione (in questo caso, ``__malloc_``) + +Notate che per la **definizione** di una funzione (il altre parole il corpo +della funzione), il compilatore non permette di usare gli attributi per i +parametri dopo i parametri. In questi casi, devono essere messi dopo gli +attributi della classe d'archiviazione (notate che la posizione di +``__printf(4,5)`` cambia rispetto alla **dichiarazione**):: + + static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value, + size_t size, u8 count, char *fmt, ...) __malloc + { + ... + }*)**``)**``)``)``*)``)``)``)``*``)``)``)*) + 7) Centralizzare il ritorno delle funzioni ------------------------------------------ @@ -855,7 +893,7 @@ I messaggi del kernel non devono terminare con un punto fermo. Scrivere i numeri fra parentesi (%d) non migliora alcunché e per questo dovrebbero essere evitati. -Ci sono alcune macro per la diagnostica in <linux/device.h> che dovreste +Ci sono alcune macro per la diagnostica in <linux/dev_printk.h> che dovreste usare per assicurarvi che i messaggi vengano associati correttamente ai dispositivi e ai driver, e che siano etichettati correttamente: dev_err(), dev_warn(), dev_info(), e così via. Per messaggi che non sono associati ad diff --git a/Documentation/translations/it_IT/process/deprecated.rst b/Documentation/translations/it_IT/process/deprecated.rst index 987f45ee1804..febf83897783 100644 --- a/Documentation/translations/it_IT/process/deprecated.rst +++ b/Documentation/translations/it_IT/process/deprecated.rst @@ -69,8 +69,8 @@ dovrebbero essere fatto negli argomenti di funzioni di allocazione di memoria piccoli di quelli che il chiamante si aspettava. L'uso di questo modo di allocare può portare ad un overflow della memoria di heap e altri malfunzionamenti. (Si fa eccezione per valori numerici per i quali il -compilatore può generare avvisi circa un potenziale overflow. Tuttavia usare -i valori numerici come suggerito di seguito è innocuo). +compilatore può generare avvisi circa un potenziale overflow. Tuttavia, anche in +questi casi è preferibile riscrivere il codice come suggerito di seguito). Per esempio, non usate ``count * size`` come argomento:: @@ -80,6 +80,9 @@ Al suo posto, si dovrebbe usare l'allocatore a due argomenti:: foo = kmalloc_array(count, size, GFP_KERNEL); +Nello specifico, kmalloc() può essere sostituta da kmalloc_array(), e kzalloc() +da kcalloc(). + Se questo tipo di allocatore non è disponibile, allora dovrebbero essere usate le funzioni del tipo *saturate-on-overflow*:: @@ -100,9 +103,20 @@ Invece, usate la seguente funzione:: invitati a riorganizzare il vostro codice usando il `flexible array member <#zero-length-and-one-element-arrays>`_. -Per maggiori dettagli fate riferimento a array_size(), -array3_size(), e struct_size(), così come la famiglia di -funzioni check_add_overflow() e check_mul_overflow(). +Per altri calcoli, usate le funzioni size_mul(), size_add(), e size_sub(). Per +esempio, al posto di:: + + foo = krealloc(current_size + chunk_size * (count - 3), GFP_KERNEL); + +dovreste scrivere: + + foo = krealloc(size_add(current_size, + size_mul(chunk_size, + size_sub(count, 3))), GFP_KERNEL); + +Per maggiori dettagli fate riferimento a array3_size() e flex_array_size(), ma +anche le funzioni della famiglia check_mul_overflow(), check_add_overflow(), +check_sub_overflow(), e check_shl_overflow(). simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull() ---------------------------------------------------------------------- diff --git a/Documentation/translations/it_IT/process/howto.rst b/Documentation/translations/it_IT/process/howto.rst index 9554368a2ae2..16ad5622d549 100644 --- a/Documentation/translations/it_IT/process/howto.rst +++ b/Documentation/translations/it_IT/process/howto.rst @@ -109,8 +109,7 @@ Di seguito una lista di file che sono presenti nei sorgente del kernel e che accetteranno patch solo se queste osserveranno tali regole, e molte persone revisioneranno il codice solo se scritto nello stile appropriato. - :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>` e - :ref:`Documentation/translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>` + :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>` Questo file descrive dettagliatamente come creare ed inviare una patch con successo, includendo (ma non solo questo): diff --git a/Documentation/translations/it_IT/process/index.rst b/Documentation/translations/it_IT/process/index.rst index c4c867132c88..8d4e36a07ff4 100644 --- a/Documentation/translations/it_IT/process/index.rst +++ b/Documentation/translations/it_IT/process/index.rst @@ -41,12 +41,12 @@ degli sviluppatori: :maxdepth: 1 changes - submitting-drivers stable-api-nonsense management-style stable-kernel-rules submit-checklist kernel-docs + maintainers Ed infine, qui ci sono alcune guide più tecniche che son state messe qua solo perché non si è trovato un posto migliore. diff --git a/Documentation/translations/it_IT/process/maintainer-handbooks.rst b/Documentation/translations/it_IT/process/maintainer-handbooks.rst new file mode 100644 index 000000000000..d840145bcceb --- /dev/null +++ b/Documentation/translations/it_IT/process/maintainer-handbooks.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-ita.rst + +:Original: Documentation/process/maintainer-handbooks.rst +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +.. _it_maintainer_handbooks_main: + +Note sul processo di sviluppo dei sottosistemi e dei sorgenti dei manutentori +============================================================================= + +Lo scopo di questo documento è quello di fornire informazioni sul processo di +sviluppo dedicate ai sottosistemi che vanno ad integrare quelle più generali +descritte in :ref:`Documentation/translations/it_IT/process +<it_development_process_main>`. + +Indice: + +.. toctree:: + :numbered: + :maxdepth: 2 + + maintainer-tip diff --git a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst index f3c8e8d377ee..a1e98ec9532e 100644 --- a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst +++ b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst @@ -931,12 +931,11 @@ che avete nel vostro portachiavi:: uid [ unknown] Linus Torvalds <torvalds@kernel.org> sub rsa2048 2011-09-20 [E] -Poi, aprite il `PGP pathfinder`_. Nel campo "From", incollate l'impronta -digitale della chiave di Linus Torvalds che si vede nell'output qui sopra. -Nel campo "to", incollate il key-id della chiave sconosciuta che avete -trovato con ``gpg --search``, e poi verificare il risultato: - -- `Finding paths to Linus`_ +Poi, cercate un percorso affidabile da Linux Torvalds alla chiave che avete +trovato con ``gpg --search`` usando la chiave sconosciuta.Per farlo potete usare +diversi strumenti come https://github.com/mricon/wotmate, +https://git.kernel.org/pub/scm/docs/kernel/pgpkeys.git/tree/graphs, e +https://the.earth.li/~noodles/pathfind.html. Se trovate un paio di percorsi affidabili è un buon segno circa la validità della chiave. Ora, potete aggiungerla al vostro portachiavi dal keyserver:: @@ -948,6 +947,3 @@ fiducia nell'amministratore del servizio *PGP Pathfinder* sperando che non sia malintenzionato (infatti, questo va contro :ref:`it_devs_not_infra`). Tuttavia, se mantenete con cura la vostra rete di fiducia sarà un deciso miglioramento rispetto alla cieca fiducia nei keyserver. - -.. _`PGP pathfinder`: https://pgp.cs.uu.nl/ -.. _`Finding paths to Linus`: https://pgp.cs.uu.nl/paths/79BE3E4300411886/to/C94035C21B4F2AEB.html diff --git a/Documentation/translations/it_IT/process/maintainer-tip.rst b/Documentation/translations/it_IT/process/maintainer-tip.rst new file mode 100644 index 000000000000..126f17ee541e --- /dev/null +++ b/Documentation/translations/it_IT/process/maintainer-tip.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-ita.rst + +:Original: Documentation/process/maintainer-tip.rst + +Il tascabile dei sorgenti tip +============================= + +.. note:: To be translated diff --git a/Documentation/translations/it_IT/process/maintainers.rst b/Documentation/translations/it_IT/process/maintainers.rst new file mode 100644 index 000000000000..3225f7c89fda --- /dev/null +++ b/Documentation/translations/it_IT/process/maintainers.rst @@ -0,0 +1,13 @@ +:Original: Documentation/process/maintainers.rst + +Lista dei manutentori e come inviare modifiche al kernel +======================================================== + +Questa pagina non verrà tradotta. Fate riferimento alla versione originale in +inglese. + +.. note:: La pagina originale usa una direttiva speciale per integrare il file + `MAINTAINERS` in sphinx. La parte di quel documento che si potrebbe + tradurre contiene comunque informazioni già presenti in + :ref:`Documentation/translations/it_IT/process/submitting-patches.rst + <it_submittingpatches>`. diff --git a/Documentation/translations/it_IT/process/stable-kernel-rules.rst b/Documentation/translations/it_IT/process/stable-kernel-rules.rst index 83f48afe48b9..0be675b03199 100644 --- a/Documentation/translations/it_IT/process/stable-kernel-rules.rst +++ b/Documentation/translations/it_IT/process/stable-kernel-rules.rst @@ -41,10 +41,10 @@ Regole sul tipo di patch che vengono o non vengono accettate nei sorgenti Procedura per sottomettere patch per i sorgenti -stable ------------------------------------------------------- - - Una patch di sicurezza non dovrebbero essere gestite (solamente) dal processo - di revisione -stable, ma dovrebbe seguire le procedure descritte in - :ref:`Documentation/translations/it_IT/admin-guide/security-bugs.rst <it_securitybugs>`. - +.. note:: + Una patch di sicurezza non dovrebbe essere gestita (solamente) dal processo + di revisione -stable, ma dovrebbe seguire le procedure descritte in + :ref:`Documentation/translations/it_IT/admin-guide/security-bugs.rst <it_securitybugs>`. Per tutte le altre sottomissioni, scegliere una delle seguenti procedure ------------------------------------------------------------------------ @@ -90,9 +90,9 @@ L':ref:`it_option_2` e l':ref:`it_option_3` sono più utili quando, al momento dell'inclusione dei sorgenti principali, si ritiene che non debbano essere incluse anche in quelli stabili (per esempio, perché si crede che si dovrebbero fare più verifiche per eventuali regressioni). L':ref:`it_option_3` è -particolarmente utile se la patch ha bisogno di qualche modifica per essere -applicata ad un kernel più vecchio (per esempio, perché nel frattempo l'API è -cambiata). +particolarmente utile se una patch dev'essere riportata su una versione +precedente (per esempio la patch richiede modifiche a causa di cambiamenti di +API). Notate che per l':ref:`it_option_3`, se la patch è diversa da quella nei sorgenti principali (per esempio perché è stato necessario un lavoro di @@ -167,9 +167,18 @@ Ciclo di una revisione della lista linux-kernel obietta la bontà della patch, sollevando problemi che i manutentori ed i membri non avevano compreso, allora la patch verrà rimossa dalla coda. - - Alla fine del ciclo di revisione tutte le patch che hanno ricevuto l'ACK - verranno aggiunte per il prossimo rilascio -stable, e successivamente - questo nuovo rilascio verrà fatto. + - Le patch che hanno ricevuto un ACK verranno inviate nuovamente come parte di + un rilascio candidato (-rc) al fine di essere verificate dagli sviluppatori e + dai testatori. + - Solitamente si pubblica solo una -rc, tuttavia se si riscontrano problemi + importanti, alcune patch potrebbero essere modificate o essere scartate, + oppure nuove patch potrebbero essere messe in coda. Dunque, verranno pubblicate + nuove -rc e così via finché non si ritiene che non vi siano più problemi. + - Si può rispondere ad una -rc scrivendo sulla lista di discussione un'email + con l'etichetta "Tested-by:". Questa etichetta verrà raccolta ed aggiunta al + commit rilascio. + - Alla fine del ciclo di revisione il nuovo rilascio -stable conterrà tutte le + patch che erano in coda e sono state verificate. - Le patch di sicurezza verranno accettate nei sorgenti -stable direttamente dalla squadra per la sicurezza del kernel, e non passerà per il normale ciclo di revisione. Contattate la suddetta squadra per maggiori dettagli @@ -186,8 +195,19 @@ Sorgenti - Il rilascio definitivo, e marchiato, di tutti i kernel stabili può essere trovato in rami distinti per versione al seguente indirizzo: - https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git + + - I rilasci candidati di tutti i kernel stabili possono essere trovati al + seguente indirizzo: + + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/ + + .. warning:: + I sorgenti -stable-rc sono un'istantanea dei sorgenti stable-queue e + subirà frequenti modifiche, dunque verrà anche trapiantato spesso. + Dovrebbe essere usato solo allo scopo di verifica (per esempio in un + sistema di CI) Comitato per la revisione ------------------------- diff --git a/Documentation/translations/it_IT/process/submitting-drivers.rst b/Documentation/translations/it_IT/process/submitting-drivers.rst deleted file mode 100644 index dadd77e47613..000000000000 --- a/Documentation/translations/it_IT/process/submitting-drivers.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. include:: ../disclaimer-ita.rst - -:Original: :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` -:Translator: Federico Vaga <federico.vaga@vaga.pv.it> - -.. _it_submittingdrivers: - -Sottomettere driver per il kernel Linux -======================================= - -.. note:: - - Questo documento è vecchio e negli ultimi anni non è stato più aggiornato; - dovrebbe essere aggiornato, o forse meglio, rimosso. La maggior parte di - quello che viene detto qui può essere trovato anche negli altri documenti - dedicati allo sviluppo. Per questo motivo il documento non verrà tradotto. diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index 4fb5b3aa306d..a3bb0008837a 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -18,16 +18,18 @@ Questo documento contiene un vasto numero di suggerimenti concisi. Per maggiori dettagli su come funziona il processo di sviluppo del kernel leggete Documentation/translations/it_IT/process/development-process.rst. Leggete anche Documentation/translations/it_IT/process/submit-checklist.rst per una lista di -punti da verificare prima di inviare del codice. Se state inviando un driver, -allora leggete anche -Documentation/translations/it_IT/process/submitting-drivers.rst; per delle patch -relative alle associazioni per Device Tree leggete +punti da verificare prima di inviare del codice. +Per delle patch relative alle associazioni per Device Tree leggete Documentation/translations/it_IT/process/submitting-patches.rst. Questa documentazione assume che sappiate usare ``git`` per preparare le patch. Se non siete pratici di ``git``, allora è bene che lo impariate; renderà la vostra vita di sviluppatore del kernel molto più semplice. +I sorgenti di alcuni sottosistemi e manutentori contengono più informazioni +riguardo al loro modo di lavorare ed aspettative. Consultate +:ref:`Documentation/translations/it_IT/process/maintainer-handbooks.rst <it_maintainer_handbooks_main>` + Ottenere i sorgenti attuali --------------------------- @@ -84,11 +86,11 @@ comporti come descritto. I manutentori vi saranno grati se scrivete la descrizione della patch in un formato che sia compatibile con il gestore dei sorgenti usato dal kernel, -``git``, come un "commit log". Leggete :ref:`it_explicit_in_reply_to`. +``git``, come un "commit log". Leggete :ref:`it_the_canonical_patch_format`. Risolvete solo un problema per patch. Se la vostra descrizione inizia ad essere lunga, potrebbe essere un segno che la vostra patch necessita d'essere -divisa. Leggete :ref:`split_changes`. +divisa. Leggete :ref:`it_split_changes`. Quando inviate o rinviate una patch o una serie, includete la descrizione completa delle modifiche e la loro giustificazione. Non limitatevi a dire che @@ -104,17 +106,28 @@ do frotz" piuttosto che "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", come se steste dando ordini al codice di cambiare il suo comportamento. -Se la patch corregge un baco conosciuto, fare riferimento a quel baco inserendo -il suo numero o il suo URL. Se la patch è la conseguenza di una discussione -su una lista di discussione, allora fornite l'URL all'archivio di quella -discussione; usate i collegamenti a https://lore.kernel.org/ con il -``Message-Id``, in questo modo vi assicurerete che il collegamento non diventi -invalido nel tempo. +Se ci sono delle discussioni, o altre informazioni d'interesse, che fanno +riferimento alla patch, allora aggiungete l'etichetta 'Link:' per farvi +riferimento. Per esempio, se la vostra patch corregge un baco potete aggiungere +quest'etichetta per fare riferimento ad un rapporto su una lista di discussione +o un *bug tracker*. Un altro esempio; potete usare quest'etichetta per far +riferimento ad una discussione precedentemente avvenuta su una lista di +discussione, o qualcosa di documentato sul web, da cui poi è nata la patch in +questione. + +Quando volete fare riferimento ad una lista di discussione, preferite il +servizio d'archiviazione lore.kernel.org. Per create un collegamento URL è +sufficiente usare il campo ``Message-Id``, presente nell'intestazione del +messaggio, senza parentesi angolari. Per esempio:: + + Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + +Prima d'inviare il messaggio ricordatevi di verificare che il collegamento così +creato funzioni e che indirizzi verso il messaggio desiderato. -Tuttavia, cercate di rendere la vostra spiegazione comprensibile anche senza -far riferimento a fonti esterne. In aggiunta ai collegamenti a bachi e liste -di discussione, riassumente i punti più importanti della discussione che hanno -portato alla creazione della patch. +Tuttavia, provate comunque a dare una spiegazione comprensibile anche senza +accedere alle fonti esterne. Inoltre, riassumente i punti più salienti che hanno +condotto all'invio della patch. Se volete far riferimento a uno specifico commit, non usate solo l'identificativo SHA-1. Per cortesia, aggiungete anche la breve riga @@ -226,10 +239,11 @@ nella vostra patch. Dovreste sempre inviare una copia della patch ai manutentori dei sottosistemi interessati dalle modifiche; date un'occhiata al file MAINTAINERS e alla storia -delle revisioni per scoprire chi si occupa del codice. Lo script -scripts/get_maintainer.pl può esservi d'aiuto. Se non riuscite a trovare un -manutentore per il sottosistema su cui state lavorando, allora Andrew Morton -(akpm@linux-foundation.org) sarà la vostra ultima possibilità . +delle revisioni per scoprire chi si occupa del codice. Lo script +scripts/get_maintainer.pl può esservi d'aiuto (passategli il percorso alle +vostre patch). Se non riuscite a trovare un manutentore per il sottosistema su +cui state lavorando, allora Andrew Morton (akpm@linux-foundation.org) sarà la +vostra ultima possibilità . Normalmente, dovreste anche scegliere una lista di discussione a cui inviare la vostra serie di patch. La lista di discussione linux-kernel@vger.kernel.org @@ -324,14 +338,19 @@ cosa stia accadendo. Assicuratevi di dire ai revisori quali cambiamenti state facendo e di ringraziarli per il loro tempo. Revisionare codice è un lavoro faticoso e che -richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche -in questo caso, rispondete con educazione e concentratevi sul problema che -hanno evidenziato. +richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche in +questo caso, rispondete con educazione e concentratevi sul problema che hanno +evidenziato. Quando inviate una version successiva ricordatevi di aggiungere un +``patch changelog`` alla email di intestazione o ad ogni singola patch spiegando +le differenze rispetto a sottomissioni precedenti (vedere +:ref:`it_the_canonical_patch_format`). Leggete Documentation/translations/it_IT/process/email-clients.rst per le raccomandazioni sui programmi di posta elettronica e l'etichetta da usare sulle liste di discussione. +.. _it_resend_reminders: + Non scoraggiatevi - o impazientitevi ------------------------------------ @@ -504,7 +523,8 @@ Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes: L'etichetta Reported-by da credito alle persone che trovano e riportano i bachi e si spera che questo possa ispirarli ad aiutarci nuovamente in futuro. Rammentate che se il baco è stato riportato in privato, dovrete chiedere il -permesso prima di poter utilizzare l'etichetta Reported-by. +permesso prima di poter utilizzare l'etichetta Reported-by. Questa etichetta va +usata per i bachi, dunque non usatela per richieste di nuove funzionalità . L'etichetta Tested-by: indica che la patch è stata verificata con successo (su un qualche sistema) dalla persona citata. Questa etichetta informa i @@ -574,6 +594,8 @@ previste per i kernel stabili, e nemmeno dalla necessità di aggiungere in copia conoscenza stable@vger.kernel.org su tutte le patch per suddetti kernel. +.. _it_the_canonical_patch_format: + Il formato canonico delle patch ------------------------------- @@ -719,6 +741,8 @@ messe correttamente oltre la riga.:: Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito. +.. _it_backtraces: + Aggiungere i *backtrace* nei messaggi di commit ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/translations/ja_JP/howto.rst b/Documentation/translations/ja_JP/howto.rst index 38fed6fe62fe..649e2ff2a407 100644 --- a/Documentation/translations/ja_JP/howto.rst +++ b/Documentation/translations/ja_JP/howto.rst @@ -129,8 +129,8 @@ linux-api@vger.kernel.org ã«é€ã‚‹ã“ã¨ã‚’勧ã‚ã¾ã™ã€‚ ルã«å¾“ã£ã¦ã„ã‚‹ã‚‚ã®ã ã‘ã‚’å—ã‘付ã‘ã€å¤šãã®äººã¯æ£ã—ã„スタイルã®ã‚³ãƒ¼ãƒ‰ ã ã‘をレビューã—ã¾ã™ã€‚ - :ref:`Documentation/process/submitting-patches.rst <codingstyle>` 㨠:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` - ã“れらã®ãƒ•ã‚¡ã‚¤ãƒ«ã«ã¯ã€ã©ã†ã‚„ã£ã¦ã†ã¾ãパッãƒã‚’作ã£ã¦æŠ•ç¨¿ã™ã‚‹ã‹ã«ã¤ + :ref:`Documentation/process/submitting-patches.rst <codingstyle>` + ã“ã®ãƒ•ã‚¡ã‚¤ãƒ«ã«ã¯ã€ã©ã†ã‚„ã£ã¦ã†ã¾ãパッãƒã‚’作ã£ã¦æŠ•ç¨¿ã™ã‚‹ã‹ã«ã¤ ã„ã¦éžå¸¸ã«è©³ã—ã書ã‹ã‚Œã¦ãŠã‚Šã€ä»¥ä¸‹ã‚’å«ã¿ã¾ã™ (ã“ã‚Œã ã‘ã«é™ã‚‰ãªã„ ã‘ã‚Œã©ã‚‚) diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst index e3cdf0c84892..e43970584ca4 100644 --- a/Documentation/translations/ko_KR/howto.rst +++ b/Documentation/translations/ko_KR/howto.rst @@ -124,7 +124,7 @@ mtk.manpages@gmail.comì˜ ë©”ì¸í…Œì´ë„ˆì—게 보낼 ê²ƒì„ ê¶Œìž¥í•œë‹¤. ë©”ì¸í…Œì´ë„ˆë“¤ì€ ì´ ê·œì¹™ì„ ë”°ë¥´ëŠ” íŒ¨ì¹˜ë“¤ë§Œì„ ë°›ì•„ë“¤ì¼ ê²ƒì´ê³ ë§Žì€ ì‚¬ëžŒë“¤ì´ ê·¸ 패치가 올바른 스타ì¼ì¼ 경우만 코드를 ê²€í† í• ê²ƒì´ë‹¤. - :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` 와 :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` + :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` ì´ íŒŒì¼ë“¤ì€ 성공ì 으로 패치를 ë§Œë“¤ê³ ë³´ë‚´ëŠ” ë²•ì„ ë‹¤ìŒì˜ 내용들로 굉장히 ìƒì„¸ížˆ ì„¤ëª…í•˜ê³ ìžˆë‹¤(그러나 다ìŒìœ¼ë¡œ í•œì •ë˜ì§„ 않는다). diff --git a/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst b/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst index fbc83dfdcead..fb023ea1374d 100644 --- a/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst +++ b/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst @@ -123,14 +123,14 @@ nr_virtfn'是è¦å¯ç”¨çš„VFçš„ç¼–å·ã€‚ ... } - static int dev_suspend(struct pci_dev *dev, pm_message_t state) + static int dev_suspend(struct device *dev) { ... return 0; } - static int dev_resume(struct pci_dev *dev) + static int dev_resume(struct device *dev) { ... @@ -163,8 +163,7 @@ nr_virtfn'是è¦å¯ç”¨çš„VFçš„ç¼–å·ã€‚ .id_table = dev_id_table, .probe = dev_probe, .remove = dev_remove, - .suspend = dev_suspend, - .resume = dev_resume, + .driver.pm = &dev_pm_ops .shutdown = dev_shutdown, .sriov_configure = dev_sriov_configure, }; diff --git a/Documentation/translations/zh_CN/PCI/pci.rst b/Documentation/translations/zh_CN/PCI/pci.rst index 520707787256..83c2a41d38d3 100644 --- a/Documentation/translations/zh_CN/PCI/pci.rst +++ b/Documentation/translations/zh_CN/PCI/pci.rst @@ -255,13 +255,13 @@ pci_set_master()将通过设置PCI_COMMAND寄å˜å™¨ä¸çš„总线主控ä½æ¥å¯ç” 虽然所有的驱动程åºéƒ½åº”该明确指出PCI总线主控的DMA功能（如32ä½æˆ–64ä½ï¼‰ï¼Œä½†å¯¹äºŽæµå¼ æ•°æ®æ¥è¯´ï¼Œå…·æœ‰è¶…过32ä½æ€»çº¿ä¸»ç«™åŠŸèƒ½çš„设备需è¦é©±åŠ¨ç¨‹åºé€šè¿‡è°ƒç”¨å¸¦æœ‰é€‚当å‚æ•°çš„ -``pci_set_dma_mask()`` æ¥â€œæ³¨å†Œâ€è¿™ç§åŠŸèƒ½ã€‚一般æ¥è¯´ï¼Œåœ¨ç³»ç»ŸRAM高于4G物ç†åœ°å€çš„情 +``dma_set_mask()`` æ¥â€œæ³¨å†Œâ€è¿™ç§åŠŸèƒ½ã€‚一般æ¥è¯´ï¼Œåœ¨ç³»ç»ŸRAM高于4G物ç†åœ°å€çš„情 况下，这å…许更有效的DMA。 -所有PCI-Xå’ŒPCIe兼容设备的驱动程åºå¿…须调用 ``pci_set_dma_mask()`` ï¼Œå› ä¸ºå®ƒä»¬ +所有PCI-Xå’ŒPCIe兼容设备的驱动程åºå¿…须调用 ``dma_set_mask()`` ï¼Œå› ä¸ºå®ƒä»¬ 是64ä½DMA设备。 -åŒæ ·ï¼Œå¦‚果设备å¯ä»¥é€šè¿‡è°ƒç”¨ ``pci_set_consistent_dma_mask()`` 直接寻å€åˆ° +åŒæ ·ï¼Œå¦‚果设备å¯ä»¥é€šè¿‡è°ƒç”¨ ``dma_set_coherent_mask()`` 直接寻å€åˆ° 4G物ç†åœ°å€ä»¥ä¸Šçš„系统RAMä¸çš„“一致性内å˜â€ï¼Œé‚£ä¹ˆé©±åŠ¨ç¨‹åºä¹Ÿå¿…须“注册â€è¿™ç§åŠŸèƒ½ã€‚åŒ æ ·ï¼Œè¿™åŒ…æ‹¬æ‰€æœ‰PCI-Xå’ŒPCIe兼容设备的驱动程åºã€‚许多64ä½â€œPCIâ€è®¾å¤‡ï¼ˆåœ¨PCI-X之å‰ï¼‰ 和一些PCI-X设备对有效载è·ï¼ˆâ€œæµå¼â€ï¼‰æ•°æ®å…·æœ‰64ä½DMA功能，但对控制（“一致性â€ï¼‰æ•° diff --git a/Documentation/translations/zh_CN/admin-guide/index.rst b/Documentation/translations/zh_CN/admin-guide/index.rst index be535ffaf4b0..2f6970d0a032 100644 --- a/Documentation/translations/zh_CN/admin-guide/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/index.rst @@ -36,6 +36,7 @@ Todolist: :maxdepth: 1 reporting-issues + reporting-regressions security-bugs bug-hunting bug-bisect @@ -44,7 +45,6 @@ Todolist: Todolist: -* reporting-bugs * ramoops * dynamic-debug-howto * kdump/index diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst index eee0e8c5c368..2c7d9106e399 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst @@ -210,6 +210,8 @@ schemes/<N>/ - ``pageout``: 为具有 ``MADV_PAGEOUT`` 的区域调用 ``madvise()`` 。 - ``hugepage``: 为带有 ``MADV_HUGEPAGE`` 的区域调用 ``madvise()`` 。 - ``nohugepage``: 为带有 ``MADV_NOHUGEPAGE`` 的区域调用 ``madvise()``。 + - ``lru_prio``: 在其LRU列表上对区域进行优先排åºã€‚ + - ``lru_deprio``: 对区域的LRU列表进行é™ä½Žä¼˜å…ˆå¤„ç†ã€‚ - ``stat``: 什么都ä¸åšï¼Œåªè®¡ç®—ç»Ÿè®¡æ•°æ® schemes/<N>/access_pattern/ diff --git a/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst b/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst index 6b4988da2c5a..59e51e3539b4 100644 --- a/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst +++ b/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst @@ -1,13 +1,6 @@ .. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) -.. - If you want to distribute this text under CC-BY-4.0 only, please use 'The - Linux kernel developers' for author attribution and link this as source: - https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst -.. - Note: Only the content of this RST file as found in the Linux kernel sources - is available under CC-BY-4.0, as versions of this text that were processed - (for example by the kernel's build system) might contain content taken from - files which use a more restrictive license. +.. See the bottom of this file for additional redistribution information. + .. include:: ../disclaimer-zh_CN.rst @@ -29,7 +22,9 @@ 请æœç´¢ `LKMLå†…æ ¸é‚®ä»¶åˆ—è¡¨ <https://lore.kernel.org/lkml/>`_ å’Œ `Linux稳定版邮件列表 <https://lore.kernel.org/stable/>`_ å˜æ¡£ä¸åŒ¹é…的报告并 åŠ å…¥è®¨è®ºã€‚å¦‚æžœæ‰¾ä¸åˆ°åŒ¹é…的报告，请安装该系列的最新版本。如果它ä»ç„¶å‡ºçŽ°é—®é¢˜ï¼Œ -报告给稳定版邮件列表（stable@vger.kernel.org）。 +请报告给稳定版邮件列表（stable@vger.kernel.org）并抄é€å›žå½’邮件列表 +（regressions@lists.linux.dev）；ç†æƒ³æƒ…况下，还å¯ä»¥æŠ„é€ç»´æŠ¤è€…和相关å系统的 +邮件列表。 在所有其他情况下，请尽å¯èƒ½çŒœæµ‹æ˜¯å“ªä¸ªå†…æ ¸éƒ¨åˆ†å¯¼è‡´äº†é—®é¢˜ã€‚æŸ¥çœ‹MAINTAINERS文件， 了解开å‘人员希望如何得知问题，大多数情况下，报告问题都是通过电åé‚®ä»¶å’ŒæŠ„é€ @@ -46,9 +41,10 @@ æœ‰ä½¿ç”¨é™„åŠ æ¨¡å—）。还è¦ç¡®ä¿å®ƒæ˜¯åœ¨ä¸€ä¸ªæ£å¸¸çš„环境ä¸æž„建和è¿è¡Œï¼Œå¹¶ä¸”在问题å‘生 之å‰æ²¡æœ‰è¢«æ±¡æŸ“（tainted）。 -在编写报告时，è¦æ¶µç›–与问题相关的所有信æ¯ï¼Œå¦‚ä½¿ç”¨çš„å†…æ ¸å’Œå‘行版。在碰è§å›žå½’时， -å°è¯•ç»™å‡ºå¼•å…¥å®ƒçš„更改的æ交ID，二分å¯ä»¥æ‰¾åˆ°å®ƒã€‚如果您åŒæ—¶é¢ä¸´Linuxå†…æ ¸çš„å¤šä¸ª -问题，请分别报告æ¯ä¸ªé—®é¢˜ã€‚ +å½“ä½ åŒæ—¶é¢ä¸´Linuxå†…æ ¸çš„å¤šä¸ªé—®é¢˜æ—¶ï¼Œè¯·åˆ†åˆ«æŠ¥å‘Šã€‚åœ¨ç¼–å†™æŠ¥å‘Šæ—¶ï¼Œè¦æ¶µç›–与问题 +相关的所有信æ¯ï¼Œå¦‚ä½¿ç”¨çš„å†…æ ¸å’Œå‘行版。如果碰è§å›žå½’，请把报告抄é€å›žå½’邮件列表 +（regressions@lists.linux.dev）。也请试试用二分法找出æºå¤´ï¼›å¦‚æžœæˆåŠŸæ‰¾åˆ°ï¼Œè¯· +在报告ä¸å†™ä¸Šå®ƒçš„æ交ID并抄é€sign-off-by链ä¸çš„所有人。 一旦报告å‘出，请回ç”任何出现的问题，并尽å¯èƒ½åœ°æ供帮助。这包括通过ä¸æ—¶é‡æ–° 测试新版本并å‘é€çŠ¶æ€æ›´æ–°æ¥æŽ¨åŠ¨è¿›å±•ã€‚ @@ -156,9 +152,10 @@ å˜åœ¨é—®é¢˜ï¼Œå› 为问题å¯èƒ½å·²ç»åœ¨é‚£é‡Œè¢«ä¿®å¤äº†ã€‚如果您第一次å‘çŽ°ä¾›åº”å•†å†…æ ¸çš„é—®é¢˜ï¼Œ 请检查已知最新版本的普通构建是å¦å¯ä»¥æ£å¸¸è¿è¡Œã€‚ - * å‘Linux稳定版邮件列表å‘é€ä¸€ä¸ªç®€çŸçš„问题报告(stable@vger.kernel.org)。大致 - æ述问题，并解释如何å¤çŽ°ã€‚讲清楚首个出现问题的版本和最åŽä¸€ä¸ªå·¥ä½œæ£å¸¸çš„版本。 - 然åŽç‰å¾…进一æ¥çš„指示。 + * å‘Linux稳定版邮件列表å‘é€ä¸€ä¸ªç®€çŸçš„问题报告（stable@vger.kernel.orgï¼‰å¹¶æŠ„é€ + Linux回归邮件列表（regressions@lists.linux.devï¼‰ï¼›å¦‚æžœä½ æ€€ç–‘æ˜¯ç”±æŸå系统 + 引起的，请抄é€å…¶ç»´æŠ¤äººå‘˜å’Œå系统邮件列表。大致æ述问题，并解释如何å¤çŽ°ã€‚ + 讲清楚首个出现问题的版本和最åŽä¸€ä¸ªå·¥ä½œæ£å¸¸çš„版本。然åŽç‰å¾…进一æ¥çš„指示。 下é¢çš„å‚è€ƒç« èŠ‚éƒ¨åˆ†è¯¦ç»†è§£é‡Šäº†è¿™äº›æ¥éª¤ä¸çš„æ¯ä¸€æ¥ã€‚ @@ -296,17 +293,14 @@ Linus Torvalds和主è¦çš„Linuxå†…æ ¸å¼€å‘人员希望看到一些问题尽快å 报告过程ä¸æœ‰ä¸€äº›â€œé«˜ä¼˜å…ˆçº§é—®é¢˜â€çš„处ç†ç•¥æœ‰ä¸åŒã€‚有三ç§æƒ…况符åˆæ¡ä»¶:回归ã€å®‰å…¨ 问题和éžå¸¸ä¸¥é‡çš„问题。 -如果在旧版本的Linuxå†…æ ¸ä¸å·¥ä½œçš„东西ä¸èƒ½åœ¨æ–°ç‰ˆæœ¬çš„Linuxå†…æ ¸ä¸å·¥ä½œï¼Œæˆ–者æŸç§ -程度上在新版本的Linuxå†…æ ¸ä¸å·¥ä½œå¾—æ›´å·®ï¼Œé‚£ä¹ˆä½ å°±éœ€è¦å¤„ç†â€œå›žå½’â€ã€‚å› æ¤ï¼Œå½“一个 -在Linux 5.7ä¸è¡¨çŽ°è‰¯å¥½çš„WiFi驱动程åºåœ¨5.8ä¸è¡¨çŽ°ä¸ä½³æˆ–æ ¹æœ¬ä¸èƒ½å·¥ä½œæ—¶ï¼Œè¿™æ˜¯ä¸€ -ç§å›žå½’。如果应用程åºåœ¨æ–°çš„å†…æ ¸ä¸å‡ºçŽ°ä¸ç¨³å®šçš„现象，这也是一ç§å›žå½’，这å¯èƒ½æ˜¯ -ç”±äºŽå†…æ ¸å’Œç”¨æˆ·ç©ºé—´ä¹‹é—´çš„æŽ¥å£ï¼ˆå¦‚procfså’Œsysfs）å‘生ä¸å…¼å®¹çš„æ›´æ”¹é€ æˆçš„。显著 -的性能é™ä½Žæˆ–åŠŸè€—å¢žåŠ ä¹Ÿå¯ä»¥ç§°ä¸ºå›žå½’。但是请记ä½:æ–°å†…æ ¸éœ€è¦ä½¿ç”¨ä¸Žæ—§å†…æ ¸ç›¸ä¼¼çš„ -é…ç½®æ¥æž„建（å‚è§ä¸‹é¢å¦‚ä½•å®žçŽ°è¿™ä¸€ç‚¹ï¼‰ã€‚è¿™æ˜¯å› ä¸ºå†…æ ¸å¼€å‘人员在实现新特性时有 -æ—¶æ— æ³•é¿å…ä¸å…¼å®¹æ€§ï¼›ä½†æ˜¯ä¸ºäº†é¿å…回归，这些特性必须在构建é…置期间显å¼åœ°å¯ç”¨ã€‚ +如果æŸä¸ªåº”用程åºæˆ–实际用例在原先的Linuxå†…æ ¸ä¸Šè¿è¡Œè‰¯å¥½ï¼Œä½†åœ¨ä½¿ç”¨ç±»ä¼¼é…置编译的 +较新版本上效果更差ã€æˆ–è€…æ ¹æœ¬ä¸èƒ½ç”¨ï¼Œé‚£ä¹ˆä½ 就需è¦å¤„ç†å›žå½’问题。 +Documentation/admin-guide/reporting-regressions.rst 对æ¤è¿›è¡Œäº†æ›´è¯¦ç»†çš„解释。 +它还æä¾›äº†å¾ˆå¤šä½ å¯èƒ½æƒ³çŸ¥é“的关于回归的其他信æ¯ï¼›ä¾‹å¦‚，它解释了如何将您的问题 +æ·»åŠ åˆ°å›žå½’è·Ÿè¸ªåˆ—è¡¨ä¸ï¼Œä»¥ç¡®ä¿å®ƒä¸ä¼šè¢«å¿½ç•¥ã€‚ 什么是安全问题留给您自己判æ–。在继ç»ä¹‹å‰ï¼Œè¯·è€ƒè™‘阅读 -“Documentation/translations/zh_CN/admin-guide/security-bugs.rstâ€ï¼Œ +Documentation/translations/zh_CN/admin-guide/security-bugs.rst ， å› ä¸ºå®ƒæ供了如何最æ°å½“地处ç†å®‰å…¨é—®é¢˜çš„é¢å¤–细节。 当å‘ç”Ÿäº†å®Œå…¨æ— æ³•æŽ¥å—的糟糕事情时，æ¤é—®é¢˜å°±æ˜¯ä¸€ä¸ªâ€œéžå¸¸ä¸¥é‡çš„问题â€ã€‚例如， @@ -390,7 +384,7 @@ Linuxå†…æ ¸ç ´å了它处ç†çš„æ•°æ®æˆ–æŸå了它è¿è¡Œçš„ç¡¬ä»¶ã€‚å½“å†…æ ¸ æ ¸æœªè¢«æ±¡æŸ“ï¼Œé‚£ä¹ˆå®ƒåº”è¯¥ä»¥â€œNot infectedâ€ç»“æŸï¼›å¦‚æžœä½ çœ‹åˆ°â€œTainted:â€ä¸”åŽè·Ÿä¸€äº› ç©ºæ ¼å’Œå—æ¯ï¼Œé‚£å°±è¢«æ±¡æŸ“了。 -å¦‚æžœä½ çš„å†…æ ¸è¢«æ±¡æŸ“äº†ï¼Œè¯·é˜…è¯»â€œDocumentation/translations/zh_CN/admin-guide/tainted-kernels.rst†+å¦‚æžœä½ çš„å†…æ ¸è¢«æ±¡æŸ“äº†ï¼Œè¯·é˜…è¯» Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst ä»¥æ‰¾å‡ºåŽŸå› ã€‚è®¾æ³•æ¶ˆé™¤æ±¡æŸ“å› ç´ ã€‚é€šå¸¸æ˜¯ç”±ä»¥ä¸‹ä¸‰ç§å› ç´ ä¹‹ä¸€å¼•èµ·çš„ï¼š 1. å‘生了一个å¯æ¢å¤çš„错误（“kernel Oopsâ€ï¼‰ï¼Œå†…æ ¸æ±¡æŸ“äº†è‡ªå·±ï¼Œå› ä¸ºå†…æ ¸çŸ¥é“在 @@ -591,7 +585,8 @@ ath10k@lists.infradead.orgâ€ï¼Œå°†å¼•å¯¼æ‚¨åˆ°ath10k邮件列表的信æ¯é¡µï¼Œ æœç´¢å¼•æ“Žï¼Œå¹¶æ·»åŠ 类似“site:lists.infadead.org/pipermail/ath10k/â€è¿™ æ ·çš„æœç´¢æ¡ä»¶ï¼Œè¿™ä¼šæŠŠç»“æžœé™åˆ¶åœ¨è¯¥é“¾æŽ¥ä¸çš„档案。 -也请进一æ¥æœç´¢ç½‘络ã€LKMLå’Œbugzilla.kernel.org网站。 +也请进一æ¥æœç´¢ç½‘络ã€LKMLå’Œbugzilla.kernel.orgç½‘ç«™ã€‚å¦‚æžœä½ çš„æŠ¥å‘Šéœ€è¦å‘é€åˆ°ç¼ºé™· +跟踪器ä¸ï¼Œé‚£ä¹ˆæ‚¨å¯èƒ½è¿˜éœ€è¦æ£€æŸ¥å系统的邮件列表å˜æ¡£ï¼Œå› 为å¯èƒ½æœ‰äººåªåœ¨é‚£é‡ŒæŠ¥å‘Šäº†å®ƒã€‚ 有关如何æœç´¢ä»¥åŠåœ¨æ‰¾åˆ°åŒ¹é…报告时如何æ“作的详细信æ¯ï¼Œè¯·å‚阅上é¢çš„“æœç´¢çŽ°æœ‰æŠ¥å‘Š （第一部分）â€ã€‚ @@ -802,10 +797,10 @@ Linux 首å¸å¼€å‘者 Linus Torvalds 认为 Linux å†…æ ¸æ°¸è¿œä¸åº”æ¶åŒ–，这 é‡çŽ°å®ƒã€‚ 有一个å«åšâ€œäºŒåˆ†â€çš„过程å¯ä»¥æ¥å¯»æ‰¾å˜åŒ–，这在 -“Documentation/translations/zh_CN/admin-guide/bug-bisect.rstâ€æ–‡æ¡£ä¸è¿›è¡Œäº†è¯¦ç»† +Documentation/translations/zh_CN/admin-guide/bug-bisect.rst 文档ä¸è¿›è¡Œäº†è¯¦ç»† çš„æ述，这个过程通常需è¦ä½ 构建å到二åä¸ªå†…æ ¸é•œåƒï¼Œæ¯æ¬¡éƒ½å°è¯•åœ¨æž„å»ºä¸‹ä¸€ä¸ªé•œåƒ ä¹‹å‰é‡çŽ°é—®é¢˜ã€‚是的，这需è¦èŠ±è´¹ä¸€äº›æ—¶é—´ï¼Œä½†ä¸ç”¨æ‹…心，它比大多数人想象的è¦å¿«å¾—多。 -多äºäº†â€œbinary search二进制æœç´¢â€ï¼Œè¿™å°†å¼•å¯¼ä½ 在æºä»£ç 管ç†ç³»ç»Ÿä¸æ‰¾åˆ°å¯¼è‡´å›žå½’çš„æ交。 +多äºäº†â€œbinary search二分æœç´¢â€ï¼Œè¿™å°†å¼•å¯¼ä½ 在æºä»£ç 管ç†ç³»ç»Ÿä¸æ‰¾åˆ°å¯¼è‡´å›žå½’çš„æ交。 ä¸€æ—¦ä½ æ‰¾åˆ°å®ƒï¼Œå°±åœ¨ç½‘ä¸Šæœç´¢å…¶ä¸»é¢˜ã€æ交ID和缩çŸçš„æ交ID（æ交IDçš„å‰12个å—符）。 如果有的è¯ï¼Œè¿™å°†å¼•å¯¼æ‚¨æ‰¾åˆ°å…³äºŽå®ƒçš„现有报告。 @@ -823,10 +818,10 @@ Linux 首å¸å¼€å‘者 Linus Torvalds 认为 Linux å†…æ ¸æ°¸è¿œä¸åº”æ¶åŒ–，这 当处ç†å›žå½’问题时，请确ä¿ä½ 所é¢ä¸´çš„é—®é¢˜çœŸçš„æ˜¯ç”±å†…æ ¸å¼•èµ·çš„ï¼Œè€Œä¸æ˜¯ç”±å…¶ä»–东西 引起的，如上文所述。 -在整个过程ä¸ï¼Œè¯·è®°ä½ï¼šåªæœ‰å½“æ—§å†…æ ¸å’Œæ–°å†…æ ¸çš„é…置相似时，问题æ‰ç®—回归。最好 -的方法是：把é…置文件（``.config``ï¼‰ä»Žæ—§çš„å·¥ä½œå†…æ ¸ç›´æŽ¥å¤åˆ¶åˆ°ä½ å°è¯•çš„æ¯ä¸ªæ–°å†… -æ ¸ç‰ˆæœ¬ã€‚ä¹‹åŽè¿è¡Œ ``make oldnoconfig`` æ¥è°ƒæ•´å®ƒä»¥é€‚应新版本的需è¦ï¼Œè€Œä¸å¯ç”¨ -ä»»ä½•æ–°çš„åŠŸèƒ½ï¼Œå› ä¸ºé‚£äº›åŠŸèƒ½ä¹Ÿå¯èƒ½å¯¼è‡´å›žå½’。 +在整个过程ä¸ï¼Œè¯·è®°ä½ï¼šåªæœ‰å½“æ—§å†…æ ¸å’Œæ–°å†…æ ¸çš„é…置相似时，问题æ‰ç®—回归。这å¯ä»¥ +通过 ``make olddefconfig`` æ¥å®žçŽ°ï¼Œè¯¦ç»†è§£é‡Šå‚è§ +Documentation/admin-guide/reporting-regressions.rst ；它还æ供了大é‡å…¶ä»–您 +å¯èƒ½å¸Œæœ›äº†è§£çš„有关回归的信æ¯ã€‚ 撰写并å‘é€æŠ¥å‘Š @@ -959,11 +954,19 @@ Linux 首å¸å¼€å‘者 Linus Torvalds 认为 Linux å†…æ ¸æ°¸è¿œä¸åº”æ¶åŒ–，这 **éžå¸¸ä¸¥é‡çš„缺陷** ：确ä¿åœ¨ä¸»é¢˜æˆ–å·¥å•æ ‡é¢˜ä»¥åŠç¬¬ä¸€æ®µä¸æ˜Žæ˜¾æ ‡å‡º severeness （éžå¸¸ä¸¥é‡çš„）。 -**回归** ï¼šå¦‚æžœé—®é¢˜æ˜¯ä¸€ä¸ªå›žå½’ï¼Œè¯·åœ¨é‚®ä»¶çš„ä¸»é¢˜æˆ–ç¼ºé™·è·Ÿè¸ªå™¨çš„æ ‡é¢˜ä¸æ·»åŠ -[REGRESSION]。如果您没有进行二分，请至少注明您测试的最新主线版本（比如 5.7） -和出现问题的最新版本（比如 5.8）。如果您æˆåŠŸåœ°è¿›è¡Œäº†äºŒåˆ†ï¼Œè¯·æ³¨æ˜Žå¯¼è‡´å›žå½’ -çš„æ交IDå’Œä¸»é¢˜ã€‚ä¹Ÿè¯·æ·»åŠ è¯¥å˜æ›´çš„ä½œè€…åˆ°ä½ çš„æŠ¥å‘Šä¸ï¼›å¦‚果您需è¦å°†æ‚¨çš„缺陷æ交 -到缺陷跟踪器ä¸ï¼Œè¯·å°†æŠ¥å‘Šä»¥ç§äººé‚®ä»¶çš„å½¢å¼è½¬å‘给他，并注明报告æ交地点。 +**回归** ：报告的主题应以“[REGRESSION]â€å¼€å¤´ã€‚ + +如果您æˆåŠŸç”¨äºŒåˆ†æ³•å®šä½äº†é—®é¢˜ï¼Œè¯·ä½¿ç”¨å¼•å…¥å›žå½’ä¹‹æ›´æ”¹çš„æ ‡é¢˜ä½œä¸ºä¸»é¢˜çš„ç¬¬äºŒéƒ¨åˆ†ã€‚ +请在报告ä¸å†™æ˜Žâ€œç½ªé祸首â€çš„æ交ID。如果未能æˆåŠŸäºŒåˆ†ï¼Œè¯·åœ¨æŠ¥å‘Šä¸è®²æ˜Žæœ€åŽä¸€ä¸ª +æ£å¸¸å·¥ä½œçš„版本（例如5.7）和最先å‘生问题的版本（例如5.8-rc1）。 + +通过邮件å‘é€æŠ¥å‘Šæ—¶ï¼Œè¯·æŠ„é€Linux回归邮件列表（regressions@lists.linux.dev）。 +如果报告需è¦æ交到æŸä¸ªweb追踪器，请继ç»æ交；并在æ交åŽï¼Œé€šè¿‡é‚®ä»¶å°†æŠ¥å‘Šè½¬å‘ +至回归列表；抄é€ç›¸å…³å系统的维护人员和邮件列表。请确ä¿æŠ¥å‘Šæ˜¯å†…è”转å‘的，ä¸è¦ +把它作为附件。å¦å¤–è¯·åœ¨é¡¶éƒ¨æ·»åŠ ä¸€ä¸ªç®€çŸçš„说明，在那里写上工å•çš„网å€ã€‚ + +在邮寄或转å‘报告时，如果æˆåŠŸäºŒåˆ†ï¼Œéœ€è¦å°†â€œç½ªé祸首â€çš„ä½œè€…æ·»åŠ åˆ°æ”¶ä»¶äººä¸ï¼›åŒæ—¶ +抄é€signed-off-by链ä¸çš„æ¯ä¸ªäººï¼Œæ‚¨å¯ä»¥åœ¨æ交消æ¯çš„末尾找到。 **安全问题** ：对于这ç§é—®é¢˜ï¼Œä½ 将必须评估：如果细节被公开披露，是å¦ä¼šå¯¹å…¶ä»– 用户产生çŸæœŸé£Žé™©ã€‚如果ä¸ä¼šï¼Œåªéœ€æŒ‰ç…§æ‰€è¿°ç»§ç»æŠ¥å‘Šé—®é¢˜ã€‚如果有æ¤é£Žé™©ï¼Œä½ éœ€è¦ @@ -980,7 +983,7 @@ Linux 首å¸å¼€å‘者 Linus Torvalds 认为 Linux å†…æ ¸æ°¸è¿œä¸åº”æ¶åŒ–，这 报告，请将报告的文本转å‘到这些地å€ï¼›ä½†è¯·åœ¨æŠ¥å‘Šçš„é¡¶éƒ¨åŠ ä¸Šæ³¨é‡Šï¼Œè¡¨æ˜Žæ‚¨æ交了 报告，并附上工å•é“¾æŽ¥ã€‚ -更多信æ¯è¯·å‚è§â€œDocumentation/translations/zh_CN/admin-guide/security-bugs.rstâ€ã€‚ +更多信æ¯è¯·å‚è§ Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。 å‘布报告åŽçš„责任 @@ -1173,14 +1176,18 @@ FLOSS 问题报告的人看，询问他们的æ„è§ã€‚åŒæ—¶å¾æ±‚ä»–ä»¬å…³äºŽå¦ æŠ¥å‘Šå›žå½’ ~~~~~~~~~~ - *å‘Linux稳定版邮件列表å‘é€ä¸€ä¸ªç®€çŸçš„问题报告(stable@vger.kernel.org)。 - 大致æ述问题，并解释如何å¤çŽ°ã€‚讲清楚首个出现问题的版本和最åŽä¸€ä¸ªå·¥ä½œæ£å¸¸ - 的版本。然åŽç‰å¾…进一æ¥çš„指示。* + *å‘Linux稳定版邮件列表å‘é€ä¸€ä¸ªç®€çŸçš„问题报告(stable@vger.kernel.org)并 + 抄é€Linux回归邮件列表（regressions@lists.linux.devï¼‰ï¼›å¦‚æžœä½ æ€€ç–‘æ˜¯ç”±æŸ + å系统引起的，请抄é€å…¶ç»´æŠ¤äººå‘˜å’Œå系统邮件列表。大致æ述问题，并解释如 + 何å¤çŽ°ã€‚讲清楚首个出现问题的版本和最åŽä¸€ä¸ªå·¥ä½œæ£å¸¸çš„版本。然åŽç‰å¾…进一 + æ¥çš„指示。* 当报告在稳定版或长期支æŒå†…æ ¸çº¿å†…å‘生的回归（例如在从5.10.4更新到5.10.5时）， -一份简çŸçš„æŠ¥å‘Šè¶³ä»¥å¿«é€ŸæŠ¥å‘Šé—®é¢˜ã€‚å› æ¤åªéœ€è¦ç²—略的æ述。 +一份简çŸçš„æŠ¥å‘Šè¶³ä»¥å¿«é€ŸæŠ¥å‘Šé—®é¢˜ã€‚å› æ¤åªéœ€å‘稳定版和回归邮件列表å‘é€ç²—略的æè¿°ï¼› +ä¸è¿‡å¦‚æžœä½ æ€€ç–‘æŸå系统导致æ¤é—®é¢˜çš„è¯ï¼Œè¯·ä¸€å¹¶æŠ„é€å…¶ç»´æŠ¤äººå‘˜å’Œå系统邮件列表， +è¿™ä¼šåŠ å¿«è¿›ç¨‹ã€‚ -但是请注æ„，如果您能够指明引入问题的确切版本，这将对开å‘äººå‘˜æœ‰å¾ˆå¤§å¸®åŠ©ã€‚å› æ¤ +请注æ„，如果您能够指明引入问题的确切版本，这将对开å‘äººå‘˜æœ‰å¾ˆå¤§å¸®åŠ©ã€‚å› æ¤ å¦‚æžœæœ‰æ—¶é—´çš„è¯ï¼Œè¯·å°è¯•ä½¿ç”¨æ™®é€šå†…æ ¸æ‰¾åˆ°è¯¥ç‰ˆæœ¬ã€‚è®©æˆ‘ä»¬å‡è®¾å‘行版å‘布Linuxå†…æ ¸ 5.10.5到5.10.8çš„æ›´æ–°æ—¶å‘生了故障。那么按照上é¢çš„指示，去检查该版本线ä¸çš„最新 å†…æ ¸ï¼Œæ¯”å¦‚5.10.9。如果问题出现，请å°è¯•æ™®é€š5.10.5，以确ä¿ä¾›åº”商应用的补ä¸ä¸ä¼š @@ -1190,7 +1197,9 @@ FLOSS 问题报告的人看，询问他们的æ„è§ã€‚åŒæ—¶å¾æ±‚ä»–ä»¬å…³äºŽå¦ å‰ä¸€æ®µåŸºæœ¬ç²—略地概述了“二分â€æ–¹æ³•ã€‚一旦报告出æ¥ï¼Œæ‚¨å¯èƒ½ä¼šè¢«è¦æ±‚åšä¸€ä¸ªæ£ç¡®çš„ æŠ¥å‘Šï¼Œå› ä¸ºå®ƒå…许精确地定ä½å¯¼è‡´é—®é¢˜çš„确切更改（然åŽå¾ˆå®¹æ˜“被æ¢å¤ä»¥å¿«é€Ÿä¿®å¤é—®é¢˜ï¼‰ã€‚ å› æ¤å¦‚果时间å…许，考虑立å³è¿›è¡Œé€‚当的二分。有关如何详细信æ¯ï¼Œè¯·å‚阅“对回归的 -特别关照â€éƒ¨åˆ†å’Œæ–‡æ¡£â€œDocumentation/translations/zh_CN/admin-guide/bug-bisect.rstâ€ã€‚ +特别关照â€éƒ¨åˆ†å’Œæ–‡æ¡£ Documentation/translations/zh_CN/admin-guide/bug-bisect.rst 。 +如果æˆåŠŸäºŒåˆ†çš„è¯ï¼Œè¯·å°†â€œç½ªé祸首â€çš„ä½œè€…æ·»åŠ åˆ°æ”¶ä»¶äººä¸ï¼›åŒæ—¶æŠ„é€æ‰€æœ‰åœ¨ +signed-off-by链ä¸çš„人，您å¯ä»¥åœ¨æ交消æ¯çš„末尾找到。 â€œæŠ¥å‘Šä»…åœ¨æ—§å†…æ ¸ç‰ˆæœ¬çº¿ä¸å‘生的问题â€çš„å‚考 @@ -1207,7 +1216,7 @@ FLOSS 问题报告的人看，询问他们的æ„è§ã€‚åŒæ—¶å¾æ±‚ä»–ä»¬å…³äºŽå¦ å³ä½¿æ˜¯å¾®å°çš„ã€çœ‹ä¼¼æ˜Žæ˜¾çš„代ç å˜åŒ–，有时也会带æ¥æ–°çš„ã€å®Œå…¨æ„想ä¸åˆ°çš„问题。稳 定版和长期支æŒå†…æ ¸çš„ç»´æŠ¤è€…éžå¸¸æ¸…æ¥šè¿™ä¸€ç‚¹ï¼Œå› æ¤ä»–们åªå¯¹è¿™äº›å†…æ ¸è¿›è¡Œç¬¦åˆ -“Documentation/translations/zh_CN/process/stable-kernel-rules.rstâ€ä¸æ‰€åˆ—出的 +Documentation/translations/zh_CN/process/stable-kernel-rules.rst ä¸æ‰€åˆ—出的 规则的修改。 å¤æ‚或有风险的修改ä¸ç¬¦åˆæ¡ä»¶ï¼Œå› æ¤åªèƒ½åº”用于主线。其他的修å¤å¾ˆå®¹æ˜“被回溯到 @@ -1333,3 +1342,27 @@ FLOSS 问题报告的人看，询问他们的æ„è§ã€‚åŒæ—¶å¾æ±‚ä»–ä»¬å…³äºŽå¦ å‘ Linux å†…æ ¸å¼€å‘者报告问题是很难的：这个文档的长度和å¤æ‚性以åŠå—里行间的内 涵都说明了这一点。但目å‰å°±æ˜¯è¿™æ ·äº†ã€‚这篇文å—的主è¦ä½œè€…希望通过记录现状æ¥ä¸º 以åŽæ”¹å–„è¿™ç§çŠ¶å†µæ‰“下一些基础。 + + +.. + end-of-content +.. + This English version of this document is maintained by Thorsten Leemhuis + <linux@leemhuis.info>. If you spot a typo or small mistake, feel free to + let him know directly and he'll fix it. For translation problems, please + contact with translators. You are free to do the same in a mostly informal + way if you want to contribute changes to the text, but for copyright + reasons please CC linux-doc@vger.kernel.org and "sign-off" your + contribution as Documentation/process/submitting-patches.rst outlines in + the section "Sign your work - the Developer's Certificate of Origin". +.. + This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top + of the file. If you want to distribute this text under CC-BY-4.0 only, + please use "The Linux kernel developers" for author attribution and link + this as source: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst +.. + Note: Only the content of this RST file as found in the Linux kernel sources + is available under CC-BY-4.0, as versions of this text that were processed + (for example by the kernel's build system) might contain content taken from + files which use a more restrictive license. diff --git a/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst b/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst new file mode 100644 index 000000000000..c0461ee855bc --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst @@ -0,0 +1,370 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) +.. ã€é‡åˆ†å‘ä¿¡æ¯å‚è§æœ¬æ–‡ä»¶ç»“尾】 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/reporting-regressions.rst + +:译者: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + + +============ +报告回归问题 +============ + +“*我们拒ç»å‡ºçŽ°å›žå½’*â€æ˜¯Linuxå†…æ ¸å¼€å‘的首è¦è§„则；Linuxçš„å‘起者和领军开å‘者Linus +Torvalds立下了æ¤è§„则并确ä¿å®ƒè¢«è½å®žã€‚ + +本文档æ述了这æ¡è§„则对用户的æ„义，以åŠLinuxå†…æ ¸å¼€å‘模型如何确ä¿è§£å†³æ‰€æœ‰è¢«æŠ¥å‘Š +çš„å›žå½’ï¼›å…³äºŽå†…æ ¸å¼€å‘者如何处ç†çš„æ–¹é¢å‚è§ Documentation/process/handling-regressions.rst 。 + + +本文é‡ç‚¹ï¼ˆäº¦å³â€œå¤ªé•¿ä¸çœ‹â€ï¼‰ +========================== + +#. 如果æŸç¨‹åºåœ¨åŽŸå…ˆçš„Linuxå†…æ ¸ä¸Šè¿è¡Œè‰¯å¥½ï¼Œä½†åœ¨è¾ƒæ–°ç‰ˆæœ¬ä¸Šæ•ˆæžœæ›´å·®ã€æˆ–è€…æ ¹æœ¬ä¸ + èƒ½ç”¨ï¼Œé‚£ä¹ˆä½ å°±ç¢°è§å›žå½’问题了。注æ„ï¼Œæ–°å†…æ ¸éœ€è¦ä½¿ç”¨ç±»ä¼¼é…置编译；更多相关细 + 节å‚è§ä¸‹æ–¹ã€‚ + +#. 按照 Documentation/translations/zh_CN/admin-guide/reporting-issues.rst ä¸ + æ‰€è¯´çš„æŠ¥å‘Šä½ çš„é—®é¢˜ï¼Œè¯¥æ–‡æ¡£å·²ç»åŒ…å«äº†æ‰€æœ‰å…³äºŽå›žå½’çš„é‡è¦æ–¹é¢ï¼Œä¸ºäº†æ–¹ä¾¿èµ·è§ä¹Ÿ + å¤åˆ¶åˆ°äº†ä¸‹é¢ã€‚两个é‡ç‚¹ï¼šåœ¨æŠ¥å‘Šä¸»é¢˜ä¸ä½¿ç”¨â€œ[REGRESSION]â€å¼€å¤´å¹¶æŠ„é€æˆ–转å‘到 + `回归邮件列表 <https://lore.kernel.org/regressions/>`_ + （regressions@lists.linux.dev）。 + +#. å¯é€‰ä½†æ˜¯å»ºè®®ï¼šåœ¨å‘é€æˆ–转å‘报告时，指明该回归å‘生的起点，以便Linuxå†…æ ¸å›žå½’ + 追踪机器人“regzbotâ€å¯ä»¥è¿½è¸ªæ¤é—®é¢˜:: + + #regzbot introduced v5.13..v5.14-rc1 + + +与用户相关的所有Linuxå†…æ ¸å›žå½’ç»†èŠ‚ +================================= + + +基本é‡ç‚¹ +-------- + + +什么是“回归â€ä»¥åŠä»€ä¹ˆæ˜¯â€œæ— 回归规则â€ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +如果æŸç¨‹åº/实例在原先的Linuxå†…æ ¸ä¸Šè¿è¡Œè‰¯å¥½ï¼Œä½†åœ¨è¾ƒæ–°ç‰ˆæœ¬ä¸Šæ•ˆæžœæ›´å·®ã€æˆ–è€…æ ¹æœ¬ +ä¸èƒ½ç”¨ï¼Œé‚£ä¹ˆä½ 就碰è§å›žå½’é—®é¢˜äº†ã€‚â€œæ— å›žå½’è§„åˆ™â€ä¸å…许出现这ç§æƒ…况。如果å¶ç„¶å‘ +生了，导致问题的开å‘者应当迅速修å¤é—®é¢˜ã€‚ + +也就是说，若Linux 5.13ä¸çš„WiFi驱动程åºè¿è¡Œè‰¯å¥½ï¼Œä½†æ˜¯åœ¨5.14版本上å´ä¸èƒ½ç”¨ã€é€Ÿ +度明显å˜æ…¢æˆ–出现错误，那就出现了回归。如果æŸæ£å¸¸å·¥ä½œçš„应用程åºçªç„¶åœ¨æ–°å†…æ ¸ä¸Š +出现ä¸ç¨³å®šï¼Œè¿™ä¹Ÿæ˜¯å›žå½’；这些问题å¯èƒ½æ˜¯ç”±äºŽprocfsã€sysfs或Linuxæ供给用户空间 +软件的许多其他接å£ä¹‹ä¸€çš„å˜åŒ–。但请记ä½ï¼Œå‰è¿°ä¾‹åä¸çš„5.14需è¦ä½¿ç”¨ç±»ä¼¼äºŽ5.13çš„ +é…置构建。这å¯ä»¥ç”¨ ``make olddefconfig`` 实现，详细解释è§ä¸‹ã€‚ + +注æ„本节第一å¥è¯ä¸çš„“实例â€ï¼šå³ä½¿å¼€å‘者需è¦éµå¾ªâ€œæ— 回归â€è§„则，但ä»å¯è‡ªç”±åœ°æ”¹ +å˜å†…æ ¸çš„ä»»ä½•æ–¹é¢ï¼Œç”šè‡³æ˜¯å¯¼å‡ºåˆ°ç”¨æˆ·ç©ºé—´çš„API或ABI，åªè¦åˆ«ç ´å现有的应用程åºæˆ– +用例。 + +还需注æ„ï¼Œâ€œæ— å›žå½’â€è§„则åªé™åˆ¶å†…æ ¸æ供给用户空间的接å£ã€‚它ä¸é€‚ç”¨äºŽå†…æ ¸å†…éƒ¨æŽ¥ +å£ï¼Œæ¯”如一些外部开å‘的驱动程åºç”¨æ¥æ’入钩ååˆ°å†…æ ¸çš„æ¨¡å—API。 + +如何报告回归？ +~~~~~~~~~~~~~~ + +åªéœ€æŒ‰ç…§ Documentation/translations/zh_CN/admin-guide/reporting-issues.rst ä¸ +æ‰€è¯´çš„æŠ¥å‘Šä½ çš„é—®é¢˜ï¼Œè¯¥æ–‡æ¡£å·²ç»åŒ…å«äº†è¦ç‚¹ã€‚下é¢å‡ 点概述了一下åªåœ¨å›žå½’ä¸é‡è¦çš„ +æ–¹é¢ï¼š + + * 在检查å¯åŠ 入讨论的现有报告时，别忘了æœç´¢ `Linux回归邮件列表 + <https://lore.kernel.org/regressions/>`_ å’Œ `regzbotç½‘é¡µç•Œé¢ + <https://linux-regtracking.leemhuis.info/regzbot/>`_ 。 + + * åœ¨æŠ¥å‘Šä¸»é¢˜çš„å¼€å¤´åŠ ä¸Šâ€œ[REGRESSION]â€ã€‚ + + * åœ¨ä½ çš„æŠ¥å‘Šä¸æ˜Žç¡®æœ€åŽä¸€ä¸ªæ£å¸¸å·¥ä½œçš„å†…æ ¸ç‰ˆæœ¬å’Œé¦–ä¸ªå‡ºé—®é¢˜çš„ç‰ˆæœ¬ã€‚å¦‚è‹¥å¯èƒ½ï¼Œ + 用二分法å°è¯•æ‰¾å‡ºå¯¼è‡´å›žå½’çš„å˜æ›´ï¼Œæ›´å¤šç»†èŠ‚è§ä¸‹ã€‚ + + * 记得把报告å‘到Linux回归邮件列表（regressions@lists.linux.dev）。 + + * 如果通过邮件报告回归，请抄é€å›žå½’列表。 + + * å¦‚æžœä½ ä½¿ç”¨æŸäº›ç¼ºé™·è¿½è¸ªå™¨æŠ¥å‘Šå›žå½’，请通过邮件转å‘å·²æ交的报告到回归列表， + 并抄é€ç»´æŠ¤è€…以åŠå‡ºé—®é¢˜çš„相关å系统的邮件列表。 + + 如果是稳定版或长期支æŒç‰ˆç³»åˆ—（如v5.15.3…v5.15.5ï¼‰çš„å›žå½’ï¼Œè¯·è®°å¾—æŠ„é€ + `Linux稳定版邮件列表 <https://lore.kernel.org/stable/>`_ （stable@vger.kernel.org）。 + + å¦‚æžœä½ æˆåŠŸåœ°æ‰§è¡Œäº†äºŒåˆ†ï¼Œè¯·æŠ„é€è‚‡äº‹æ交的信æ¯ä¸æ‰€æœ‰ç¾äº†â€œSigned-off-by:â€çš„人。 + +在抄é€ä½ 的报告到列表时，也请记得通知å‰è¿°çš„Linuxå†…æ ¸å›žå½’è¿½è¸ªæœºå™¨äººã€‚åªéœ€åœ¨é‚®ä»¶ +ä¸åŒ…å«å¦‚下片段:: + + #regzbot introduced: v5.13..v5.14-rc1 + +Regzbotä¼šå°±å°†ä½ çš„é‚®ä»¶è§†ä¸ºåœ¨æŸä¸ªç‰¹å®šç‰ˆæœ¬åŒºé—´çš„回归报告。上例ä¸å³linux v5.13ä» +然æ£å¸¸ï¼Œè€ŒLinux 5.14-rc1是首个您é‡åˆ°é—®é¢˜çš„ç‰ˆæœ¬ã€‚å¦‚æžœä½ æ‰§è¡Œäº†äºŒåˆ†ä»¥æŸ¥æ‰¾å¯¼è‡´å›ž +å½’çš„æ交，请使用指定肇事æ交的id代替:: + + #regzbot introduced: 1f2e3d4c5d + +æ·»åŠ è¿™æ ·çš„â€œregzbot命令â€å¯¹ä½ 是有好处的，它会确ä¿æŠ¥å‘Šä¸ä¼šè¢«å¿½ç•¥ã€‚å¦‚æžœä½ çœç•¥äº† +它，Linuxå†…æ ¸çš„å›žå½’è·Ÿè¸ªè€…ä¼šæŠŠä½ çš„å›žå½’å‘Šè¯‰regzbot，åªè¦ä½ å‘é€äº†ä¸€ä¸ªå‰¯æœ¬åˆ°å›žå½’ +邮件列表。但是回归跟踪者åªæœ‰ä¸€ä¸ªäººï¼Œæœ‰æ—¶ä¸å¾—ä¸ä¼‘æ¯æˆ–甚至å¶å°”享å—å¯ä»¥è¿œç¦»ç”µè„‘ +的时光（å¬èµ·æ¥å¾ˆç–¯ç‹‚ï¼‰ã€‚å› æ¤ï¼Œä¾èµ–æ¤äººæ‰‹åŠ¨å°†å›žå½’æ·»åŠ åˆ° `已追踪且尚未解决的 +Linuxå†…æ ¸å›žå½’åˆ—è¡¨ <https://linux-regtracking.leemhuis.info/regzbot/>`_ å’Œ +regzbotå‘é€çš„æ¯å‘¨å›žå½’报告，å¯èƒ½ä¼šå‡ºçŽ°å»¶è¿Ÿã€‚ è¿™æ ·çš„å»¶è¯¯ä¼šå¯¼è‡´Linus Torvalds +在决定“继ç»å¼€å‘还是å‘布新版本？â€æ—¶å¿½ç•¥ä¸¥é‡çš„回归。 + +真的修å¤äº†æ‰€æœ‰çš„回归å—？ +~~~~~~~~~~~~~~~~~~~~~~~~ + +å‡ ä¹Žæ‰€æœ‰éƒ½æ˜¯ï¼Œåªè¦å¼•èµ·é—®é¢˜çš„å˜æ›´ï¼ˆè‚‡äº‹æ交）被å¯é 定ä½ã€‚也有些回归å¯ä»¥ä¸ç”¨è¿™ +æ ·ï¼Œä½†é€šå¸¸æ˜¯å¿…é¡»çš„ã€‚ + +è°éœ€è¦æ‰¾å‡ºå›žå½’çš„æ ¹æœ¬åŽŸå› ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +å—å½±å“代ç 区域的开å‘者应该自行å°è¯•å®šä½é—®é¢˜æ‰€åœ¨ã€‚但仅é 他们的努力往往是ä¸å¯ +能åšåˆ°çš„，很多问题åªå‘生在开å‘è€…çš„æ— æ³•æŽ¥è§¦çš„å…¶ä»–ç‰¹å®šå¤–éƒ¨çŽ¯å¢ƒä¸â€”—例如特定的 +硬件平å°ã€å›ºä»¶ã€Linuxå‘行版ã€ç³»ç»Ÿçš„é…置或应用程åºã€‚这就是为什么最终往往是报 +告者定ä½è‚‡äº‹æ交；有时用户甚至需è¦å†è¿è¡Œé¢å¤–æµ‹è¯•ä»¥æŸ¥æ˜Žç¡®åˆ‡çš„æ ¹æœ¬åŽŸå› ã€‚å¼€å‘ +者应该æ供建议和å¯èƒ½çš„帮助，以使普通用户更容易完æˆè¯¥æµç¨‹ã€‚ + +如何找到罪é祸首？ +~~~~~~~~~~~~~~~~~~ + +如 Documentation/translations/zh_CN/admin-guide/reporting-issues.rst （简è¦ï¼‰ +å’Œ Documentation/translations/zh_CN/admin-guide/bug-bisect.rst （详细）ä¸æ‰€ +述，执行二分。å¬èµ·æ¥å·¥ä½œé‡å¾ˆå¤§ï¼Œä½†å¤§éƒ¨åˆ†æƒ…况下很快就能找到罪é祸首。如果这很 +困难或å¯é 地é‡çŽ°é—®é¢˜å¾ˆè€—时，请考虑与其他å—å½±å“的用户åˆä½œï¼Œä¸€èµ·ç¼©å°æœç´¢èŒƒå›´ã€‚ + +当出现回归时我å¯ä»¥å‘è°å¯»æ±‚建议？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +å‘é€é‚®ä»¶åˆ°å›žå½’邮件列表（regressions@lists.linux.dev）åŒæ—¶æŠ„é€Linuxå†…æ ¸çš„å›žå½’ +跟踪者（regressions@leemhuis.info）;如果问题需è¦ä¿å¯†å¤„ç†ï¼Œå¯ä»¥çœç•¥åˆ—表。 + + +关于回归的更多细节 +------------------ + + +â€œæ— å›žå½’è§„åˆ™â€çš„ç›®æ ‡æ˜¯ä»€ä¹ˆï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +用户应该放心å‡çº§å†…æ ¸ç‰ˆæœ¬ï¼Œè€Œä¸å¿…担心有程åºå¯èƒ½å´©æºƒã€‚这符åˆå†…æ ¸å¼€å‘者的利益， +å¯ä»¥ä½¿æ›´æ–°æœ‰å¸å¼•åŠ›ï¼šä»–们ä¸å¸Œæœ›ç”¨æˆ·åœç•™åœ¨åœæ¢ç»´æŠ¤æˆ–超过一年åŠçš„稳定/长期Linux +版本系列上。这也符åˆæ‰€æœ‰äººçš„åˆ©ç›Šï¼Œå› ä¸º `那些系列å¯èƒ½å«æœ‰å·²çŸ¥çš„缺陷ã€å®‰å…¨é—®é¢˜ +或其他åŽç»ç‰ˆæœ¬å·²ç»ä¿®å¤çš„问题 +<http://www.kroah.com/log/blog/2018/08/24/what-stable-kernel-should-i-use/>`_ 。 +æ¤å¤–ï¼Œå†…æ ¸å¼€å‘者希望使用户测试最新的预å‘行版或常规å‘行版å˜å¾—简å•è€Œæœ‰å¸å¼•åŠ›ã€‚ +è¿™åŒæ ·ç¬¦åˆæ‰€æœ‰äººçš„利益，如果新版本出æ¥åŽå¾ˆå¿«å°±æœ‰ç›¸å…³æŠ¥å‘Šï¼Œä¼šä½¿è¿½è¸ªå’Œä¿®å¤é—®é¢˜ +更容易。 + +实际ä¸â€œæ— 回归â€è§„则真的å¯è¡Œå—？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +è¿™ä¸æ˜¯å¥çŽ©ç¬‘è¯ï¼Œè¯·è§Linux创建者和主è¦å¼€å‘人员Linus Torvalds在邮件列表ä¸çš„许 +多å‘言，其ä¸ä¸€äº›åœ¨ Documentation/process/handling-regressions.rst ä¸è¢«å¼•ç”¨ã€‚ + +æ¤è§„则的例外情况æžä¸ºç½•è§ï¼›ä¹‹å‰å½“å¼€å‘者认为æŸä¸ªç‰¹å®šçš„情况有必è¦æ´å¼•ä¾‹å¤–时， +基本都被è¯æ˜Žé”™äº†ã€‚ + +è°æ¥ç¡®ä¿â€œæ— 回归â€è¢«è½å®žï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~ + +ç…§çœ‹å’Œæ”¯æ’‘æ ‘çš„å系统维护者应该关心这一点——例如，Linus Torvalds之于主线， +Greg Kroah-Hartmanç‰äººä¹‹äºŽå„ç§ç¨³å®š/长期系列。 + +他们都得到了别人的帮助，以确ä¿å›žå½’报告ä¸ä¼šè¢«é—æ¼ã€‚å…¶ä¸ä¹‹ä¸€æ˜¯Thorsten +Leemhuis，他目å‰æ‹…ä»»Linuxå†…æ ¸çš„â€œå›žå½’è·Ÿè¸ªè€…â€ï¼›ä¸ºäº†åšå¥½è¿™é¡¹å·¥ä½œï¼Œä»–使用了 +regzbot——Linuxå†…æ ¸å›žå½’è·Ÿè¸ªæœºå™¨äººã€‚æ‰€ä»¥è¿™å°±æ˜¯ä¸ºä»€ä¹ˆè¦æŠ„é€æˆ–转å‘ä½ çš„æŠ¥å‘Šåˆ° +回归邮件列表æ¥é€šçŸ¥è¿™äº›äººï¼Œå·²ç»æœ€å¥½åœ¨ä½ 的邮件ä¸åŒ…å«â€œregzbot命令â€æ¥ç«‹å³è¿½è¸ªå®ƒã€‚ + +回归通常多久能修å¤ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~ + +å¼€å‘者应该尽快修å¤ä»»ä½•è¢«æŠ¥å‘Šçš„回归，以æä¾›åŠæ—¶ä¸ºå—å½±å“的用户æ供解决方案，并 +防æ¢æ›´å¤šç”¨æˆ·é‡åˆ°é—®é¢˜ï¼›ç„¶è€Œï¼Œå¼€å‘人员需è¦èŠ±è¶³å¤Ÿçš„时间和注æ„力确ä¿å›žå½’ä¿®å¤ä¸ä¼š +é€ æˆé¢å¤–çš„æŸå®³ã€‚ + +å› æ¤ï¼Œç”案å–决于å„ç§å› ç´ ï¼Œå¦‚å›žå½’çš„å½±å“ã€å˜åœ¨æ—¶é•¿æˆ–出现于哪个Linux版本系列。 +但最终，大多数的回归应该在两周内修å¤ã€‚ + +当问题å¯ä»¥é€šè¿‡å‡çº§æŸäº›è½¯ä»¶è§£å†³æ—¶ï¼Œæ˜¯å›žå½’å—？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +基本都是。如果开å‘人员告诉您其他情况，请咨询上述回归跟踪者。 + +å½“æ–°å†…æ ¸å˜æ…¢æˆ–èƒ½è€—å¢žåŠ ï¼Œæ˜¯å›žå½’å—？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +是的，但有一些差别。在微型基准测试ä¸å˜æ…¢5%ä¸å¤ªå¯èƒ½è¢«è§†ä¸ºå›žå½’，除éžå®ƒä¹Ÿä¼šå¯¹ +广泛基准测试的结果产生超过1%çš„å½±å“。如果有疑问，请寻求建议。 + +当更新Linuxæ—¶å¤–éƒ¨å†…æ ¸æ¨¡å—崩溃了，是回归å—？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ä¸ï¼Œå› ä¸ºâ€œæ— å›žå½’â€è§„则仅é™äºŽLinuxå†…æ ¸æ供给用户空间的接å£å’ŒæœåŠ¡ã€‚å› æ¤ï¼Œå®ƒä¸åŒ…括 +构建或è¿è¡Œå¤–部开å‘çš„å†…æ ¸æ¨¡å—ï¼Œå› ä¸ºå®ƒä»¬åœ¨å†…æ ¸ç©ºé—´ä¸è¿è¡Œä¸ŽæŒ‚è¿›å†…æ ¸ä½¿ç”¨çš„å†…éƒ¨æŽ¥ +å£å¶å°”会å˜åŒ–。 + +如何处ç†å®‰å…¨ä¿®å¤å¼•èµ·çš„回归？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在æžä¸ºç½•è§çš„æƒ…å†µä¸‹ï¼Œå®‰å…¨é—®é¢˜æ— æ³•åœ¨ä¸å¼•èµ·å›žå½’的情况下修å¤ï¼›è¿™äº›ä¿®å¤éƒ½è¢«æ”¾å¼ƒäº†ï¼Œ +å› ä¸ºå®ƒä»¬ç»ˆç©¶ä¼šå¼•èµ·é—®é¢˜ã€‚å¹¸è¿çš„是这ç§ä¸¤éš¾å¢ƒåœ°åŸºæœ¬éƒ½å¯ä»¥é¿å…，å—å½±å“åŒºåŸŸçš„ä¸»è¦ +å¼€å‘者以åŠLinus Torvalds本人通常都会努力在ä¸å¼•å…¥å›žå½’的情况下解决安全问题。 + +å¦‚æžœä½ ä»ç„¶é¢ä¸´æ¤ç§æƒ…况，请查看邮件列表档案是å¦æœ‰äººå°½åŠ›é¿å…过回归。如果没有， +请报告它；如有疑问，请如上所述寻求建议。 + +当修å¤å›žå½’æ—¶ä¸å¯é¿å…会引入å¦ä¸€ä¸ªï¼Œå¦‚何处ç†ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +很é—憾这ç§äº‹ç¡®å®žä¼šå‡ºçŽ°ï¼Œä½†å¹¸è¿çš„是并ä¸ç»å¸¸å‡ºçŽ°ï¼›å¦‚æžœå‘生了，å—å½±å“代ç 区的资 +深开å‘者应当调查该问题以找到é¿å…回归的解决方法，至少é¿å…它们的影å“ã€‚å¦‚æžœä½ é‡ +åˆ°è¿™æ ·çš„æƒ…å†µï¼Œå¦‚ä¸Šæ‰€è¿°ï¼šæ£€æŸ¥ä¹‹å‰çš„讨论是å¦æœ‰äººå·²ç»å°½äº†æœ€å¤§åŠªåŠ›ï¼Œå¦‚有疑问请寻 +求建议。 + +å°æ示：如果人们在æ¯ä¸ªå¼€å‘周期ä¸å®šæœŸç»™å‡ºä¸»çº¿é¢„å‘布（å³v5.15-rc1或-rc3）以供 +测试，则å¯ä»¥é¿å…è¿™ç§æƒ…况。为了更好地解释，å¯ä»¥è®¾æƒ³ä¸€ä¸ªåœ¨Linux v5.14å’Œv5.15-rc1 +之间集æˆçš„更改，该更改导致了回归，但åŒæ—¶æ˜¯åº”用于5.15-rc1的其他改进的强ä¾èµ–。 +如果有人在5.15å‘布之å‰å°±å‘现并报告了这个问题，那么所有更改都å¯ä»¥ç›´æŽ¥æ’¤é”€ï¼Œä»Ž +è€Œè§£å†³å›žå½’é—®é¢˜ã€‚è€Œå°±åœ¨å‡ å¤©æˆ–å‡ å‘¨åŽï¼Œæ¤è§£å†³æ–¹æ¡ˆå˜æˆäº†ä¸å¯èƒ½ï¼Œå› 为一些软件å¯èƒ½ +å·²ç»å¼€å§‹ä¾èµ–于åŽç»æ›´æ”¹ä¹‹ä¸€ï¼šæ’¤é”€æ‰€æœ‰æ›´æ”¹å°†å¯¼è‡´ä¸Šè¿°ç”¨æˆ·è½¯ä»¶å‡ºçŽ°å›žå½’，这是ä¸å¯ +接å—的。 + +若我所ä¾èµ–的功能在数月å‰è¢«ç§»é™¤äº†ï¼Œæ˜¯å›žå½’å—？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +是的，但如å‰èŠ‚所述，通常很难修å¤æ¤ç±»å›žå½’ã€‚å› æ¤éœ€è¦é€æ¡ˆå¤„ç†ã€‚这也是定期测试主 +线预å‘布对所有人有好处的å¦ä¸€ä¸ªåŽŸå› 。 + +如果我似乎是唯一å—å½±å“的人，是å¦ä»é€‚ç”¨â€œæ— å›žå½’â€è§„则？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +适用，但仅é™äºŽå®žé™…使用：Linuxå¼€å‘人员希望能够自由地å–消那些åªèƒ½åœ¨é˜æ¥¼å’Œåšç‰© +馆ä¸æ‰¾åˆ°çš„硬件的支æŒã€‚ + +请注æ„，有时为了å–得进展，ä¸å¾—ä¸å‡ºçŽ°å›žå½’——åŽè€…也是防æ¢Linuxåœæ»žä¸å‰æ‰€å¿…需 +çš„ã€‚å› æ¤å¦‚果回归所影å“的用户很少，那么为了他们和其他人更大的利益，还是让事情 +过去å§ã€‚尤其是å˜åœ¨æŸç§è§„é¿å›žå½’的简å•æ–¹æ³•ï¼Œä¾‹å¦‚更新一些软件或者使用专门为æ¤ç›® +çš„åˆ›å»ºçš„å†…æ ¸å‚数。 + +回归规则是å¦ä¹Ÿé€‚用于stagingæ ‘ä¸çš„代ç ？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ä¸ï¼Œå‚è§ `适用于所有staging代ç é…置选项的帮助文本 +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/staging/Kconfig>`_ ， +其早已声明:: + + 请注æ„：这些驱动æ£åœ¨ç§¯æžå¼€å‘ä¸ï¼Œå¯èƒ½æ— 法æ£å¸¸å·¥ä½œï¼Œå¹¶å¯èƒ½åŒ…å«ä¼šåœ¨ä¸ä¹…çš„ + å°†æ¥å‘生å˜åŒ–的用户接å£ã€‚ + +虽然stagingå¼€å‘人员通常åšæŒâ€œæ— 回归â€çš„原则，但有时为了å–得进展也会è¿èƒŒå®ƒã€‚这就 +是为什么当stagingæ ‘çš„WiFi驱动被基本推倒é‡æ¥æ—¶ï¼Œæœ‰äº›ç”¨æˆ·ä¸å¾—ä¸å¤„ç†å›žå½’ï¼ˆé€šå¸¸å¯ +以忽略）。 + +为什么较新版本必须“使用相似é…置编译â€ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +å› ä¸ºLinuxå†…æ ¸å¼€å‘人员有时会集æˆå·²çŸ¥çš„会导致回归的å˜æ›´ï¼Œä½†ä½¿å®ƒä»¬æˆä¸ºå¯é€‰çš„，并 +åœ¨å†…æ ¸çš„é»˜è®¤é…置下ç¦ç”¨å®ƒä»¬ã€‚这一技巧å…许进æ¥ï¼Œå¦åˆ™â€œæ— 回归â€è§„则将导致åœæ»žã€‚ + +例如，试想一个新的å¯ä»¥é˜»æ¢æ¶æ„软件滥用æŸä¸ªå†…æ ¸çš„æŽ¥å£çš„安全特性，åŒæ—¶åˆéœ€è¦æ»¡è¶³ +å¦ä¸€ä¸ªå¾ˆç½•è§çš„应用程åºã€‚上述的方法å¯ä½¿ä¸¤æ–¹éƒ½æ»¡æ„：使用这些应用程åºçš„人å¯ä»¥å…³é— +新的安全功能，而其他ä¸ä¼šé‡åˆ°éº»çƒ¦çš„人å¯ä»¥å¯ç”¨å®ƒã€‚ + +å¦‚ä½•åˆ›å»ºä¸Žæ—§å†…æ ¸ç›¸ä¼¼çš„é…置？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ç”¨ä¸€ä¸ªå·²çŸ¥è‰¯å¥½çš„å†…æ ¸å¯åŠ¨æœºå™¨ï¼Œå¹¶ç”¨ ``make olddefconfig`` é…置新版的Linux。这 +ä¼šè®©å†…æ ¸çš„æž„å»ºè„šæœ¬ä»Žæ£åœ¨è¿è¡Œçš„å†…æ ¸ä¸æ‘˜å½•é…置文件（“.configâ€æ–‡ä»¶ï¼‰ï¼Œä½œä¸ºå³å°†ç¼– +译的新版本的基础é…置；åŒæ—¶å°†æ‰€æœ‰æ–°çš„é…置选项设为默认值，以ç¦ç”¨å¯èƒ½å¯¼è‡´å›žå½’çš„ +新功能。 + +å¦‚ä½•æŠ¥å‘Šåœ¨é¢„ç¼–è¯‘çš„æ™®é€šå†…æ ¸ä¸å‘现的回归？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +您需è¦ç¡®ä¿æ–°çš„å†…æ ¸æ˜¯ç”¨ä¸Žæ—§ç‰ˆç›¸ä¼¼çš„é…置编译（è§ä¸Šæ–‡ï¼‰ï¼Œå› ä¸ºé‚£äº›æž„å»ºå®ƒä»¬çš„äººå¯ +能å¯ç”¨äº†ä¸€äº›å·²çŸ¥çš„ä¸Žæ–°å†…æ ¸ä¸å…¼å®¹çš„特性。如有疑问，请å‘å†…æ ¸çš„æ供者报告问题并 +寻求建议。 + + +用“regzbotâ€è¿½è¸ªå›žå½’çš„æ›´å¤šä¿¡æ¯ +----------------------------- + +什么是回归追踪？为啥我需è¦å…³å¿ƒå®ƒï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +åƒâ€œæ— 回归â€è¿™æ ·çš„规则需è¦æœ‰äººæ¥ç¡®ä¿å®ƒä»¬è¢«éµå®ˆï¼Œå¦åˆ™ä¼šè¢«æœ‰æ„/æ— æ„æ‰“ç ´ã€‚åŽ†å²è¯ +明了这一点对于Linuxå†…æ ¸å¼€å‘也适用。这就是为什么Linuxå†…æ ¸çš„å›žå½’è·Ÿè¸ªè€…Thorsten +Leemhuis，，和å¦ä¸€äº›äººå°½åŠ›å…³æ³¨æ‰€æœ‰çš„回归直到他们解决。他们从未为æ¤èŽ·å¾—报酬， +å› æ¤è¿™é¡¹å·¥ä½œæ˜¯åœ¨å°½æœ€å¤§åŠªåŠ›çš„基础上完æˆçš„。 + +为什么/如何使用机器人追踪Linuxå†…æ ¸å›žå½’ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +由于Linuxå†…æ ¸å¼€å‘过程的分布å¼å’Œæ¾æ•£ç»“构，完全手动跟踪回归已ç»è¢«è¯æ˜Žæ˜¯ç›¸å½“å›°éš¾ +çš„ã€‚å› æ¤Linuxå†…æ ¸çš„å›žå½’è·Ÿè¸ªè€…å¼€å‘了regzbotæ¥ä¿ƒè¿›è¿™é¡¹å·¥ä½œï¼Œå…¶é•¿æœŸç›®æ ‡æ˜¯å°½å¯èƒ½ä¸º +所有相关人员自动化回归跟踪。 + +Regzbot通过监视跟踪的回归报告的回å¤æ¥å·¥ä½œã€‚æ¤å¤–，它还查找用“Link:â€æ ‡ç¾å¼•ç”¨è¿™ +些报告的补ä¸ï¼›å¯¹è¿™äº›è¡¥ä¸çš„回å¤ä¹Ÿä¼šè¢«è·Ÿè¸ªã€‚结åˆè¿™äº›æ•°æ®ï¼Œå¯ä»¥å¾ˆå¥½åœ°äº†è§£å½“å‰ä¿® +å¤è¿‡ç¨‹çš„状æ€ã€‚ + +如何查看regzbot当å‰è¿½è¸ªçš„回归？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +å‚è§ `regzbot在线 <https://linux-regtracking.leemhuis.info/regzbot/>`_ 。 + +何ç§é—®é¢˜å¯ä»¥ç”±regzbot追踪？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +该机器人åªä¸ºäº†è·Ÿè¸ªå›žå½’ï¼Œå› æ¤è¯·ä¸è¦è®©regzbot涉åŠå¸¸è§„问题。但是对于Linuxå†…æ ¸çš„ +回归跟踪者æ¥è¯´ï¼Œè®©regzbot跟踪严é‡é—®é¢˜ä¹Ÿå¯ä»¥ï¼Œå¦‚有关挂起ã€æŸåæ•°æ®æˆ–内部错误 +（Panicã€Oopsã€BUG（）ã€warning…）的报告。 + +如何修改被追踪回归的相关信æ¯ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在直接或间接回å¤æŠ¥å‘Šé‚®ä»¶æ—¶ä½¿ç”¨â€œregzbot命令â€å³å¯ã€‚最简å•çš„方法是：在“已å‘é€â€æ–‡ +件夹或邮件列表å˜æ¡£ä¸æ‰¾åˆ°æŠ¥å‘Šï¼Œç„¶åŽä½¿ç”¨é‚®ä»¶å®¢æˆ·ç«¯çš„“全部回å¤â€åŠŸèƒ½å¯¹å…¶è¿›è¡Œå›žå¤ã€‚ +在该邮件ä¸çš„独立段è½ä¸å¯ä½¿ç”¨ä»¥ä¸‹å‘½ä»¤ä¹‹ä¸€ï¼ˆå³ä½¿ç”¨ç©ºè¡Œå°†è¿™äº›å‘½ä»¤ä¸çš„一个或多个与 +其余邮件文本分隔开）。 + + * 更新回归引入起点，例如在执行二分之åŽ:: + + #regzbot introduced: 1f2e3d4c5d + + * è®¾ç½®æˆ–æ›´æ–°æ ‡é¢˜:: + + #regzbot title: foo + + * 监视讨论或bugzilla.kernel.org上有关讨论或修å¤çš„å·¥å•:: + + #regzbot monitor: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + #regzbot monitor: https://bugzilla.kernel.org/show_bug.cgi?id=123456789 + + * æ ‡è®°ä¸€ä¸ªæœ‰æ›´å¤šç›¸å…³ç»†èŠ‚çš„åœ°æ–¹ï¼Œä¾‹å¦‚æœ‰å…³ä½†ä¸»é¢˜ä¸åŒçš„邮件列表帖å或缺陷追踪器ä¸çš„å·¥å•:: + + #regzbot link: https://bugzilla.kernel.org/show_bug.cgi?id=123456789 + + * æ ‡è®°å›žå½’å·²å¤±æ•ˆ:: + + #regzbot invalid: wasn't a regression, problem has always existed + +Regzbot还支æŒå…¶ä»–一些主è¦ç”±å¼€å‘人员或回归追踪人员使用的命令。命令的更多细节请 +å‚考 `å…¥é—¨æŒ‡å— <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/getting_started.md>`_ +å’Œ `å‚考手册 <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/reference.md>`_ 。 + +.. + æ£æ–‡ç»“æŸ +.. + 如本文件开头所述，本文以GPL-2.0+或CC-BY-4.0许å¯å‘行。如您想仅在CC-BY-4.0许 + å¯ä¸‹é‡åˆ†å‘本文，请用“Linuxå†…æ ¸å¼€å‘者â€ä½œä¸ºä½œè€…，并用如下链接作为æ¥æºï¼š + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst +.. + 注æ„：本RST文件内容åªæœ‰åœ¨æ¥è‡ªLinuxå†…æ ¸æºä»£ç 时是使用CC-BY-4.0许å¯çš„ï¼Œå› ä¸ºç» + 过处ç†çš„版本（如ç»å†…æ ¸çš„æž„å»ºç³»ç»Ÿï¼‰å¯èƒ½åŒ…å«æ¥è‡ªä½¿ç”¨æ›´ä¸¥æ ¼è®¸å¯è¯çš„文件的内容。 diff --git a/Documentation/translations/zh_CN/core-api/cachetlb.rst b/Documentation/translations/zh_CN/core-api/cachetlb.rst index 6fee45fe5e80..b4a76ec75daa 100644 --- a/Documentation/translations/zh_CN/core-api/cachetlb.rst +++ b/Documentation/translations/zh_CN/core-api/cachetlb.rst @@ -5,6 +5,7 @@ :翻译: å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> :æ ¡è¯‘: @@ -278,6 +279,11 @@ HyperSparc cpuå°±æ˜¯è¿™æ ·ä¸€ä¸ªå…·æœ‰è¿™ç§å±žæ€§çš„cpu。 CPUä¸Šï¼Œå› ä¸ºå®ƒå°†cpuå˜å‚¨åˆ°é¡µé¢ä¸Šï¼Œä½¿å…¶å˜è„。åŒæ ·ï¼Œè¯·çœ‹ sparc64关于如何处ç†è¿™ä¸ªé—®é¢˜çš„例å。 + ``void flush_dcache_folio(struct folio *folio)`` + + 该函数的调用情形与flush_dcache_page()相åŒã€‚它å…许架构针对刷新整个 + folio页é¢è¿›è¡Œä¼˜åŒ–，而ä¸æ˜¯ä¸€æ¬¡åˆ·æ–°ä¸€é¡µã€‚ + ``void copy_to_user_page(struct vm_area_struct *vma, struct page *page, unsigned long user_vaddr, void *dst, void *src, int len)`` ``void copy_from_user_page(struct vm_area_struct *vma, struct page *page, diff --git a/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst b/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst index 85a264287426..4772a900c37a 100644 --- a/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst +++ b/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst @@ -4,6 +4,7 @@ :翻译: å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> :æ ¡è¯‘: @@ -15,12 +16,13 @@ å†…æ ¸ä¸çš„CPUçƒæ‹”æ’ ================= -:时间: 2016å¹´12月 +:时间: 2021å¹´9月 :作者: Sebastian Andrzej Siewior <bigeasy@linutronix.de>, - Rusty Russell <rusty@rustcorp.com.au>, - Srivatsa Vaddagiri <vatsa@in.ibm.com>, - Ashok Raj <ashok.raj@intel.com>, - Joel Schopp <jschopp@austin.ibm.com> + Rusty Russell <rusty@rustcorp.com.au>, + Srivatsa Vaddagiri <vatsa@in.ibm.com>, + Ashok Raj <ashok.raj@intel.com>, + Joel Schopp <jschopp@austin.ibm.com>, + Thomas Gleixner <tglx@linutronix.de> 简介 ==== @@ -139,7 +141,7 @@ CPUçš„çƒæ‹”æ’å作 下线情况 -------- -一旦CPU被逻辑关é—，注册的çƒæ’拔状æ€çš„清除回调将被调用，从 ``CPUHP_ONLINE`` 开始，在 +一旦CPU被逻辑关é—，注册的çƒæ’拔状æ€çš„清除回调将被调用，从 ``CPUHP_ONLINE`` 开始，到 ``CPUHP_OFFLINE`` 状æ€ç»“æŸã€‚这包括: * å¦‚æžœä»»åŠ¡å› æš‚åœæ“作而被冻结，那么 *cpuhp_tasks_frozen* 将被设置为true。 @@ -154,82 +156,399 @@ CPUçš„çƒæ‹”æ’å作 * 一旦所有的æœåŠ¡è¢«è¿ç§»ï¼Œå†…æ ¸ä¼šè°ƒç”¨ä¸€ä¸ªç‰¹å®šçš„ä¾‹ç¨‹ ``__cpu_disable()`` æ¥è¿›è¡Œç‰¹å®šçš„清 ç†ã€‚ -使用çƒæ’æ‹”API -------------- +CPUçƒæ’æ‹”API +============ + +CPUçƒæ‹”æ’状æ€æœº +--------------- + +CPUçƒæ’拔使用一个从CPUHP_OFFLINE到CPUHP_ONLINE的线性状æ€ç©ºé—´çš„普通状æ€æœºã€‚æ¯ä¸ªçŠ¶æ€éƒ½ +有一个startupå’Œteardown的回调。 + +当一个CPU上线时，将按顺åºè°ƒç”¨startup回调，直到达到CPUHP_ONLINE状æ€ã€‚当设置状æ€çš„回调 +æˆ–å°†å®žä¾‹æ·»åŠ åˆ°å¤šå®žä¾‹çŠ¶æ€æ—¶ï¼Œä¹Ÿå¯ä»¥è°ƒç”¨å®ƒä»¬ã€‚ + +当一个CPU下线时，将按相å的顺åºä¾æ¬¡è°ƒç”¨teardown回调，直到达到CPUHP_OFFLINE状æ€ã€‚å½“åˆ +除状æ€çš„回调或从多实例状æ€ä¸åˆ 除实例时，也å¯ä»¥è°ƒç”¨å®ƒä»¬ã€‚ + +如果æŸä¸ªä½¿ç”¨åœºæ™¯åªéœ€è¦ä¸€ä¸ªæ–¹å‘çš„çƒæ’æ‹”æ“作回调（CPU上线或CPU下线），则在设置状æ€æ—¶ï¼Œ +å¯ä»¥å°†å¦ä¸€ä¸ªä¸éœ€è¦çš„回调设置为NULL。 + +状æ€ç©ºé—´è¢«åˆ’分æˆä¸‰ä¸ªé˜¶æ®µ: + +* PREPARE阶段 + + PREPARE阶段涵盖了从CPUHP_OFFLINE到CPUHP_BRINGUP_CPU之间的状æ€ç©ºé—´ã€‚ + + 在该阶段ä¸ï¼Œstartup回调在CPU上线æ“作å¯åŠ¨CPU之å‰è¢«è°ƒç”¨ï¼Œteardown回调在CPU下线æ“作使 + CPU功能失效之åŽè¢«è°ƒç”¨ã€‚ + + 这些回调是在控制CPUä¸Šè°ƒç”¨çš„ï¼Œå› ä¸ºå®ƒä»¬æ˜¾ç„¶ä¸èƒ½åœ¨çƒæ’拔的CPU上è¿è¡Œï¼Œæ¤æ—¶çƒæ’拔的CPUè¦ + 么还没有å¯åŠ¨ï¼Œè¦ä¹ˆå·²ç»åŠŸèƒ½å¤±æ•ˆã€‚ + + startup回调用于设置CPUæˆåŠŸä¸Šçº¿æ‰€éœ€è¦çš„资æºã€‚teardown回调用于释放资æºæˆ–在çƒæ’拔的CPU + 功能失效åŽï¼Œå°†å¾…处ç†çš„工作转移到在线的CPU上。 + + å…许startup回调失败。如果回调失败，CPU上线æ“作被ä¸æ¢ï¼ŒCPUå°†å†æ¬¡è¢«é™åˆ°ä¹‹å‰çš„状æ€ï¼ˆé€š + 常是CPUHP_OFFLINE）。 + + 本阶段ä¸çš„teardown回调ä¸å…许失败。 + +* STARTING阶段 + + STARTING阶段涵盖了CPUHP_BRINGUP_CPU + 1到CPUHP_AP_ONLINE之间的状æ€ç©ºé—´ã€‚ + + 该阶段ä¸çš„startup回调是在早期CPU设置代ç ä¸çš„CPU上线æ“作期间，ç¦ç”¨ä¸æ–的情况下在çƒæ‹” + æ’çš„CPU上被调用。teardown回调是在CPU完全关é—å‰ä¸ä¹…çš„CPU下线æ“作期间，ç¦ç”¨ä¸æ–的情况 + 下在çƒæ‹”æ’çš„CPU上被调用。 + + 该阶段ä¸çš„回调ä¸å…许失败。 + + 回调用于低级别的硬件åˆå§‹åŒ–/å…³æœºå’Œæ ¸å¿ƒå系统。 + +* ONLINE阶段 + + ONLINE阶段涵盖了CPUHP_AP_ONLINE + 1到CPUHP_ONLINE之间的状æ€ç©ºé—´ã€‚ + + 该阶段ä¸çš„startup回调是在CPU上线时在çƒæ’拔的CPU上调用的。teardown回调是在CPUä¸‹çº¿æ“ + 作时在çƒæ’æ‹”CPU上调用的。 + + 回调是在æ¯ä¸ªCPUçƒæ’拔线程的上下文ä¸è°ƒç”¨çš„，该线程绑定在çƒæ’拔的CPU上。回调是在å¯ç”¨ + ä¸æ–和抢å 的情况下调用的。 + + å…许回调失败。如果回调失败，CPUçƒæ’æ‹”æ“作被ä¸æ¢ï¼ŒCPUå°†æ¢å¤åˆ°ä¹‹å‰çš„状æ€ã€‚ + +CPU 上线/下线æ“作 +----------------- + +一个æˆåŠŸçš„上线æ“作如下:: + + [CPUHP_OFFLINE] + [CPUHP_OFFLINE + 1]->startup() -> æˆåŠŸ + [CPUHP_OFFLINE + 2]->startup() -> æˆåŠŸ + [CPUHP_OFFLINE + 3] -> ç•¥è¿‡ï¼Œå› ä¸ºstartup == NULL + ... + [CPUHP_BRINGUP_CPU]->startup() -> æˆåŠŸ + === PREPAREé˜¶æ®µç»“æŸ + [CPUHP_BRINGUP_CPU + 1]->startup() -> æˆåŠŸ + ... + [CPUHP_AP_ONLINE]->startup() -> æˆåŠŸ + === STARTUPé˜¶æ®µç»“æŸ + [CPUHP_AP_ONLINE + 1]->startup() -> æˆåŠŸ + ... + [CPUHP_ONLINE - 1]->startup() -> æˆåŠŸ + [CPUHP_ONLINE] + +一个æˆåŠŸçš„下线æ“作如下:: + + [CPUHP_ONLINE] + [CPUHP_ONLINE - 1]->teardown() -> æˆåŠŸ + ... + [CPUHP_AP_ONLINE + 1]->teardown() -> æˆåŠŸ + === STARTUP阶段开始 + [CPUHP_AP_ONLINE]->teardown() -> æˆåŠŸ + ... + [CPUHP_BRINGUP_ONLINE - 1]->teardown() + ... + === PREPARE阶段开始 + [CPUHP_BRINGUP_CPU]->teardown() + [CPUHP_OFFLINE + 3]->teardown() + [CPUHP_OFFLINE + 2] -> ç•¥è¿‡ï¼Œå› ä¸ºteardown == NULL + [CPUHP_OFFLINE + 1]->teardown() + [CPUHP_OFFLINE] + +一个失败的上线æ“作如下:: + + [CPUHP_OFFLINE] + [CPUHP_OFFLINE + 1]->startup() -> æˆåŠŸ + [CPUHP_OFFLINE + 2]->startup() -> æˆåŠŸ + [CPUHP_OFFLINE + 3] -> ç•¥è¿‡ï¼Œå› ä¸ºstartup == NULL + ... + [CPUHP_BRINGUP_CPU]->startup() -> æˆåŠŸ + === PREPAREé˜¶æ®µç»“æŸ + [CPUHP_BRINGUP_CPU + 1]->startup() -> æˆåŠŸ + ... + [CPUHP_AP_ONLINE]->startup() -> æˆåŠŸ + === STARTUPé˜¶æ®µç»“æŸ + [CPUHP_AP_ONLINE + 1]->startup() -> æˆåŠŸ + --- + [CPUHP_AP_ONLINE + N]->startup() -> 失败 + [CPUHP_AP_ONLINE + (N - 1)]->teardown() + ... + [CPUHP_AP_ONLINE + 1]->teardown() + === STARTUP阶段开始 + [CPUHP_AP_ONLINE]->teardown() + ... + [CPUHP_BRINGUP_ONLINE - 1]->teardown() + ... + === PREPARE阶段开始 + [CPUHP_BRINGUP_CPU]->teardown() + [CPUHP_OFFLINE + 3]->teardown() + [CPUHP_OFFLINE + 2] -> ç•¥è¿‡ï¼Œå› ä¸ºteardown == NULL + [CPUHP_OFFLINE + 1]->teardown() + [CPUHP_OFFLINE] + +一个失败的下线æ“作如下:: + + [CPUHP_ONLINE] + [CPUHP_ONLINE - 1]->teardown() -> æˆåŠŸ + ... + [CPUHP_ONLINE - N]->teardown() -> 失败 + [CPUHP_ONLINE - (N - 1)]->startup() + ... + [CPUHP_ONLINE - 1]->startup() + [CPUHP_ONLINE] + +递归失败ä¸èƒ½è¢«åˆç†åœ°å¤„ç†ã€‚ +请看下é¢çš„例å，由于下线æ“作失败而导致的递归失败:: + + [CPUHP_ONLINE] + [CPUHP_ONLINE - 1]->teardown() -> æˆåŠŸ + ... + [CPUHP_ONLINE - N]->teardown() -> 失败 + [CPUHP_ONLINE - (N - 1)]->startup() -> æˆåŠŸ + [CPUHP_ONLINE - (N - 2)]->startup() -> 失败 + +CPUçƒæ’拔状æ€æœºåœ¨æ¤åœæ¢ï¼Œä¸”ä¸å†å°è¯•å›žæ»šï¼Œå› 为这å¯èƒ½ä¼šå¯¼è‡´æ»å¾ªçŽ¯:: + + [CPUHP_ONLINE - (N - 1)]->teardown() -> æˆåŠŸ + [CPUHP_ONLINE - N]->teardown() -> 失败 + [CPUHP_ONLINE - (N - 1)]->startup() -> æˆåŠŸ + [CPUHP_ONLINE - (N - 2)]->startup() -> 失败 + [CPUHP_ONLINE - (N - 1)]->teardown() -> æˆåŠŸ + [CPUHP_ONLINE - N]->teardown() -> 失败 + +周而å¤å§‹ï¼Œä¸æ–é‡å¤ã€‚在这ç§æƒ…况下，CPU留在该状æ€ä¸:: + + [CPUHP_ONLINE - (N - 1)] + +这至少å¯ä»¥è®©ç³»ç»Ÿå–得进展，让用户有机会进行调试，甚至解决这个问题。 + +分é…ä¸€ä¸ªçŠ¶æ€ +------------ + +有两ç§æ–¹å¼åˆ†é…一个CPUçƒæ’拔状æ€: + +* é™æ€åˆ†é… + + 当å系统或驱动程åºæœ‰ç›¸å¯¹äºŽå…¶ä»–CPUçƒæ’拔状æ€çš„排åºè¦æ±‚时，必须使用é™æ€åˆ†é…。例如， + 在CPU上线æ“作期间，PERFæ ¸å¿ƒstartup回调必须在PERF驱动startup回调之å‰è¢«è°ƒç”¨ã€‚在CPU + 下线æ“作ä¸ï¼Œé©±åŠ¨teardownå›žè°ƒå¿…é¡»åœ¨æ ¸å¿ƒteardown回调之å‰è°ƒç”¨ã€‚é™æ€åˆ†é…的状æ€ç”± + cpuhp_state枚举ä¸çš„常é‡æ述，å¯ä»¥åœ¨include/linux/cpuhotplug.hä¸æ‰¾åˆ°ã€‚ + + 在适当的ä½ç½®å°†çŠ¶æ€æ’入枚举ä¸ï¼Œè¿™æ ·å°±æ»¡è¶³äº†æŽ’åºè¦æ±‚。状æ€å¸¸é‡å¿…须被用于状æ€çš„设置 + 和移除。 + + 当状æ€å›žè°ƒä¸æ˜¯åœ¨è¿è¡Œæ—¶è®¾ç½®çš„，并且是kernel/cpu.cä¸CPUçƒæ’拔状æ€æ•°ç»„åˆå§‹åŒ–的一部分 + 时，也需è¦é™æ€åˆ†é…。 + +* 动æ€åˆ†é… + + 当对状æ€å›žè°ƒæ²¡æœ‰æŽ’åºè¦æ±‚时，动æ€åˆ†é…是首选方法。状æ€ç¼–å·ç”±setup函数分é…，并在æˆåŠŸ + åŽè¿”回给调用者。 + + åªæœ‰PREPAREå’ŒONLINE阶段æ供了一个动æ€åˆ†é…范围。STARTINGé˜¶æ®µåˆ™æ²¡æœ‰ï¼Œå› ä¸ºè¯¥éƒ¨åˆ†çš„å¤§å¤š + 数回调都有明确的排åºè¦æ±‚。 + +CPUçƒæ’拔状æ€çš„设置 +------------------- + +æ ¸å¿ƒä»£ç æ供了以下函数用æ¥è®¾ç½®çŠ¶æ€ï¼š + +* cpuhp_setup_state(state, name, startup, teardown) +* cpuhp_setup_state_nocalls(state, name, startup, teardown) +* cpuhp_setup_state_cpuslocked(state, name, startup, teardown) +* cpuhp_setup_state_nocalls_cpuslocked(state, name, startup, teardown) + +对于一个驱动程åºæˆ–å系统有多个实例，并且æ¯ä¸ªå®žä¾‹éƒ½éœ€è¦è°ƒç”¨ç›¸åŒçš„CPU hotplug状æ€å›ž +调的情况，CPU hotplugæ ¸å¿ƒæ供多实例支æŒã€‚与驱动程åºç‰¹å®šçš„实例列表相比，其优势在于 +与实例相关的函数完全针对CPU hotplugæ“作进行åºåˆ—åŒ–ï¼Œå¹¶åœ¨æ·»åŠ å’Œåˆ é™¤æ—¶æ供状æ€å›žè°ƒçš„ +自动调用。è¦è®¾ç½®è¿™æ ·ä¸€ä¸ªå¤šå®žä¾‹çŠ¶æ€ï¼Œå¯ä»¥ä½¿ç”¨ä»¥ä¸‹å‡½æ•°ï¼š + +* cpuhp_setup_state_multi(state, name, startup, teardown) + +@stateå‚æ•°è¦ä¹ˆæ˜¯é™æ€åˆ†é…的状æ€ï¼Œè¦ä¹ˆæ˜¯åŠ¨æ€åˆ†é…状æ€ï¼ˆPUHP_PREPARE_DYN，CPUHP_ONLINE_DYN） +的常é‡ä¹‹ä¸€ï¼Œ 具体å–决于应该分é…动æ€çŠ¶æ€çš„状æ€é˜¶æ®µï¼ˆPREPARE，ONLINE）。 + +@nameå‚数用于sysfs输出和检测。命å惯例是"subsys:mode"或"subsys/driver:mode"， +例如 "perf:mode"或"perf/x86:mode"。常è§çš„modeå称有： + +======== ============================================ +prepare 对应PREPARE阶段ä¸çš„çŠ¶æ€ + +dead 对应PREPARE阶段ä¸ä¸æä¾›startupå›žè°ƒçš„çŠ¶æ€ + +starting 对应STARTING阶段ä¸çš„çŠ¶æ€ + +dying 对应STARTING阶段ä¸ä¸æä¾›startupå›žè°ƒçš„çŠ¶æ€ + +online 对应ONLINE阶段ä¸çš„çŠ¶æ€ + +offline 对应ONLINE阶段ä¸ä¸æä¾›startupå›žè°ƒçš„çŠ¶æ€ +======== ============================================ + +由于@nameå‚æ•°åªç”¨äºŽsysfs和检测，如果其他modeæ述符比常è§çš„æ述符更好地æ述状æ€çš„性质， +也å¯ä»¥ä½¿ç”¨ã€‚ + +@nameå‚数的示例："perf/online", "perf/x86:prepare", "RCU/tree:dying", "sched/waitempty" + +@startupå‚数是一个指å‘回调的函数指针，在CPU上线æ“作时被调用。若应用ä¸éœ€è¦startup +回调，则将该指针设为NULL。 + +@teardownå‚数是一个指å‘回调的函数指针，在CPU下线æ“作时调用。若应用ä¸éœ€è¦teardown +回调，则将该指针设为NULL。 + +这些函数在处ç†å·²æ³¨å†Œå›žè°ƒçš„æ–¹å¼ä¸Šæœ‰æ‰€ä¸åŒ: + + * cpuhp_setup_state_nocalls(), cpuhp_setup_state_nocalls_cpuslocked()å’Œ + cpuhp_setup_state_multi()åªæ³¨å†Œå›žè°ƒã€‚ + + * cpuhp_setup_state()å’Œcpuhp_setup_state_cpuslocked()注册回调，并对当å‰çŠ¶æ€å¤§äºŽæ–° + 安装状æ€çš„所有在线CPU调用@startup回调（如果ä¸æ˜¯NULLï¼‰ã€‚æ ¹æ®çŠ¶æ€é˜¶æ®µï¼Œå›žè°ƒè¦ä¹ˆåœ¨ + 当å‰çš„CPU上调用（PREPARE阶段），è¦ä¹ˆåœ¨CPUçš„çƒæ’拔线程ä¸è°ƒç”¨æ¯ä¸ªåœ¨çº¿CPU（ONLINE阶段）。 + + 如果CPU N的回调失败，那么CPU 0...N-1çš„teardown回调被调用以回滚æ“作。状æ€è®¾ç½®å¤±è´¥ï¼Œ + 状æ€çš„回调没有被注册，在动æ€åˆ†é…的情况下，分é…的状æ€è¢«é‡Šæ”¾ã€‚ + +状æ€è®¾ç½®å’Œå›žè°ƒè°ƒç”¨æ˜¯é’ˆå¯¹CPUçƒæ‹”æ’æ“作进行åºåˆ—化的。如果设置函数必须从CPUçƒæ’拔的读 +é”定区域调用，那么必须使用_cpuslocked()å˜ä½“。这些函数ä¸èƒ½åœ¨CPUçƒæ‹”æ’回调ä¸ä½¿ç”¨ã€‚ + +函数返回值： + ======== ========================================================== + 0 é™æ€åˆ†é…的状æ€è®¾ç½®æˆåŠŸ + + >0 动æ€åˆ†é…的状æ€è®¾ç½®æˆåŠŸ + + 返回的数值是被分é…的状æ€ç¼–å·ã€‚如果状æ€å›žè°ƒåŽæ¥å¿…须被移除， + 例如模å—移除，那么这个数值必须由调用者ä¿å˜ï¼Œå¹¶ä½œä¸ºçŠ¶æ€ç§» + 除函数的@stateå‚数。对于多实例状æ€ï¼ŒåŠ¨æ€åˆ†é…的状æ€ç¼–å·ä¹Ÿ + 需è¦ä½œä¸ºå®žä¾‹æ·»åŠ /åˆ é™¤æ“作的@stateå‚数。 + + <0 æ“作失败 + ======== ========================================================== + +移除CPUçƒæ‹”æ’çŠ¶æ€ +----------------- + +为了移除一个之å‰è®¾ç½®å¥½çš„状æ€ï¼Œæ供了如下函数： + +* cpuhp_remove_state(state) +* cpuhp_remove_state_nocalls(state) +* cpuhp_remove_state_nocalls_cpuslocked(state) +* cpuhp_remove_multi_state(state) + +@stateå‚æ•°è¦ä¹ˆæ˜¯é™æ€åˆ†é…的状æ€ï¼Œè¦ä¹ˆæ˜¯ç”±cpuhp_setup_state*()在动æ€èŒƒå›´å†…åˆ†é… +的状æ€ç¼–å·ã€‚如果状æ€åœ¨åŠ¨æ€èŒƒå›´å†…，则状æ€ç¼–å·è¢«é‡Šæ”¾ï¼Œå¯å†æ¬¡è¿›è¡ŒåŠ¨æ€åˆ†é…。 + +这些函数在处ç†å·²æ³¨å†Œå›žè°ƒçš„æ–¹å¼ä¸Šæœ‰æ‰€ä¸åŒ: + + * cpuhp_remove_state_nocalls(), cpuhp_remove_state_nocalls_cpuslocked() + å’Œ cpuhp_remove_multi_state()åªåˆ 除回调。 + + * cpuhp_remove_state()åˆ é™¤å›žè°ƒï¼Œå¹¶è°ƒç”¨æ‰€æœ‰å½“å‰çŠ¶æ€å¤§äºŽè¢«åˆ 除状æ€çš„在线CPUçš„ + teardown回调（如果ä¸æ˜¯NULLï¼‰ã€‚æ ¹æ®çŠ¶æ€é˜¶æ®µï¼Œå›žè°ƒè¦ä¹ˆåœ¨å½“å‰çš„CPU上调用 + （PREPARE阶段），è¦ä¹ˆåœ¨CPUçš„çƒæ’拔线程ä¸è°ƒç”¨æ¯ä¸ªåœ¨çº¿CPU（ONLINE阶段）。 + + 为了完æˆç§»é™¤å·¥ä½œï¼Œteardown回调ä¸èƒ½å¤±è´¥ã€‚ + +状æ€ç§»é™¤å’Œå›žè°ƒè°ƒç”¨æ˜¯é’ˆå¯¹CPUçƒæ‹”æ’æ“作进行åºåˆ—化的。如果移除函数必须从CPU hotplug +读å–é”定区域调用，那么必须使用_cpuslocked()å˜ä½“。这些函数ä¸èƒ½ä»ŽCPUçƒæ’拔的回调ä¸ä½¿ç”¨ã€‚ + +如果一个多实例的状æ€è¢«ç§»é™¤ï¼Œé‚£ä¹ˆè°ƒç”¨è€…必须先移除所有的实例。 + +多实例状æ€å®žä¾‹ç®¡ç† +------------------ + +一旦多实例状æ€è¢«å»ºç«‹ï¼Œå®žä¾‹å°±å¯ä»¥è¢«æ·»åŠ 到状æ€ä¸ï¼š -一旦一个CPU下线或上线，就有å¯èƒ½æ”¶åˆ°é€šçŸ¥ã€‚这对æŸäº›éœ€è¦æ ¹æ®å¯ç”¨CPUæ•°é‡æ‰§è¡ŒæŸç§è®¾ç½®æˆ–清 -ç†åŠŸèƒ½çš„驱动程åºæ¥è¯´å¯èƒ½å¾ˆé‡è¦:: + * cpuhp_state_add_instance(state, node) + * cpuhp_state_add_instance_nocalls(state, node) - #include <linux/cpuhotplug.h> +@stateå‚数是一个é™æ€åˆ†é…的状æ€æˆ–ç”±cpuhp_setup_state_multi()在动æ€èŒƒå›´å†…分é…的状 +æ€ç¼–å·ã€‚ - ret = cpuhp_setup_state(CPUHP_AP_ONLINE_DYN, "X/Y:online", - Y_online, Y_prepare_down); +@nodeå‚数是一个指å‘hlist_node的指针，它被嵌入到实例的数æ®ç»“æž„ä¸ã€‚这个指针被交给 +多实例状æ€çš„回调，å¯ä»¥è¢«å›žè°ƒç”¨æ¥é€šè¿‡container_of()检索到实例。 -*X* 是å系统， *Y* 是特定的驱动程åºã€‚ *Y_online* 回调将在所有在线CPU的注册过程ä¸è¢«è°ƒç”¨ã€‚ -如果在线回调期间å‘生错误， *Y_prepare_down* 回调将在所有之å‰è°ƒç”¨è¿‡åœ¨çº¿å›žè°ƒçš„CPU上调 -用。注册完æˆåŽï¼Œä¸€æ—¦æœ‰CPU上线， *Y_online* 回调将被调用，当CPUå…³é—时， *Y_prepare_down* -将被调用。所有之å‰åœ¨ *Y_online* ä¸åˆ†é…的资æºéƒ½åº”该在 *Y_prepare_down* ä¸é‡Šæ”¾ã€‚如果在 -注册过程ä¸å‘生错误，返回值 *ret* 为负值。å¦åˆ™ä¼šè¿”回一个æ£å€¼ï¼Œå…¶ä¸åŒ…å«åŠ¨æ€åˆ†é…çŠ¶æ€ -（ *CPUHP_AP_ONLINE_DYN* ）的分é…çƒæ‹”æ’。对于预定义的状æ€ï¼Œå®ƒå°†è¿”回0。 +这些函数在处ç†å·²æ³¨å†Œå›žè°ƒçš„æ–¹å¼ä¸Šæœ‰æ‰€ä¸åŒ: -该回调å¯ä»¥é€šè¿‡è°ƒç”¨ ``cpuhp_remove_state()`` æ¥åˆ 除。如果是动æ€åˆ†é…çš„çŠ¶æ€ -（ *CPUHP_AP_ONLINE_DYN* ），则使用返回的状æ€ã€‚在移除çƒæ’拔状æ€çš„过程ä¸ï¼Œå°†è°ƒç”¨æ‹†è§£å›žè°ƒã€‚ + * cpuhp_state_add_instance_nocalls()åªå°†å®žä¾‹æ·»åŠ 到多实例状æ€çš„节点列表ä¸ã€‚ -多个实例 -~~~~~~~~ + * cpuhp_state_add_instance()为所有当å‰çŠ¶æ€å¤§äºŽ@state的在线CPUæ·»åŠ å®žä¾‹å¹¶è°ƒç”¨ä¸Ž + @state相关的startup回调（如果ä¸æ˜¯NULL）。该回调åªå¯¹å°†è¦æ·»åŠ 的实例进行调用。 + æ ¹æ®çŠ¶æ€é˜¶æ®µï¼Œå›žè°ƒè¦ä¹ˆåœ¨å½“å‰çš„CPU上调用（PREPARE阶段），è¦ä¹ˆåœ¨CPUçš„çƒæ’拔线 + 程ä¸è°ƒç”¨æ¯ä¸ªåœ¨çº¿CPU（ONLINE阶段）。 -如果一个驱动程åºæœ‰å¤šä¸ªå®žä¾‹ï¼Œå¹¶ä¸”æ¯ä¸ªå®žä¾‹éƒ½éœ€è¦ç‹¬ç«‹æ‰§è¡Œå›žè°ƒï¼Œé‚£ä¹ˆå¾ˆå¯èƒ½åº”该使用 -``multi-state`` 。首先需è¦æ³¨å†Œä¸€ä¸ªå¤šçŠ¶æ€çš„状æ€:: + 如果CPU N的回调失败，那么CPU 0 ... N-1çš„teardown回调被调用以回滚æ“作，该函数 + 失败，实例ä¸ä¼šè¢«æ·»åŠ 到多实例状æ€çš„节点列表ä¸ã€‚ - ret = cpuhp_setup_state_multi(CPUHP_AP_ONLINE_DYN, "X/Y:online, - Y_online, Y_prepare_down); - Y_hp_online = ret; +è¦ä»ŽçŠ¶æ€çš„节点列表ä¸åˆ 除一个实例，å¯ä»¥ä½¿ç”¨è¿™äº›å‡½æ•°: -``cpuhp_setup_state_multi()`` 的行为与 ``cpuhp_setup_state()`` 类似，åªæ˜¯å®ƒ -为多状æ€å‡†å¤‡äº†å›žè°ƒï¼Œä½†ä¸è°ƒç”¨å›žè°ƒã€‚这是一个一次性的设置。 -一旦分é…äº†ä¸€ä¸ªæ–°çš„å®žä¾‹ï¼Œä½ éœ€è¦æ³¨å†Œè¿™ä¸ªæ–°å®žä¾‹:: + * cpuhp_state_remove_instance(state, node) + * cpuhp_state_remove_instance_nocalls(state, node) - ret = cpuhp_state_add_instance(Y_hp_online, &d->node); +å‚数与上述cpuhp_state_add_instance*()å˜ä½“相åŒã€‚ -è¿™ä¸ªå‡½æ•°å°†æŠŠè¿™ä¸ªå®žä¾‹æ·»åŠ åˆ°ä½ å…ˆå‰åˆ†é…çš„ ``Y_hp_online`` 状æ€ï¼Œå¹¶åœ¨æ‰€æœ‰åœ¨çº¿çš„ -CPU上调用先å‰æ³¨å†Œçš„回调（ ``Y_online`` ）。 *node* å…ƒç´ æ˜¯ä½ çš„æ¯ä¸ªå®žä¾‹æ•°æ®ç»“æž„ -ä¸çš„一个 ``struct hlist_node`` æˆå‘˜ã€‚ +这些函数在处ç†å·²æ³¨å†Œå›žè°ƒçš„æ–¹å¼ä¸Šæœ‰æ‰€ä¸åŒ: -在移除该实例时:: + * cpuhp_state_remove_instance_nocalls()åªä»ŽçŠ¶æ€çš„节点列表ä¸åˆ 除实例。 - cpuhp_state_remove_instance(Y_hp_online, &d->node) + * cpuhp_state_remove_instance()åˆ é™¤å®žä¾‹å¹¶è°ƒç”¨ä¸Ž@state相关的回调（如果ä¸æ˜¯NULL）， + 用于所有当å‰çŠ¶æ€å¤§äºŽ@state的在线CPU。 该回调åªå¯¹å°†è¦è¢«ç§»é™¤çš„实例进行调用。 + æ ¹æ®çŠ¶æ€é˜¶æ®µï¼Œå›žè°ƒè¦ä¹ˆåœ¨å½“å‰çš„CPU上调用（PREPARE阶段），è¦ä¹ˆåœ¨CPUçš„çƒæ’æ‹” + 线程ä¸è°ƒç”¨æ¯ä¸ªåœ¨çº¿CPU（ONLINE阶段）。 -应该被调用，这将在所有在线CPU上调用拆分回调。 + 为了完æˆç§»é™¤å·¥ä½œï¼Œteardown回调ä¸èƒ½å¤±è´¥ã€‚ -手动设置 -~~~~~~~~ +èŠ‚ç‚¹åˆ—è¡¨çš„æ·»åŠ /åˆ é™¤æ“作和回调调用是针对CPUçƒæ‹”æ’æ“作进行åºåˆ—化。这些函数ä¸èƒ½åœ¨ +CPU hotplug回调和CPU hotplug读å–é”定区域内使用。 -通常情况下，在注册或移除状æ€æ—¶è°ƒç”¨setupå’Œteamdownå›žè°ƒæ˜¯å¾ˆæ–¹ä¾¿çš„ï¼Œå› ä¸ºé€šå¸¸åœ¨CPU上线 -（下线）和驱动的åˆå§‹è®¾ç½®ï¼ˆå…³é—）时需è¦æ‰§è¡Œè¯¥æ“作。然而，æ¯ä¸ªæ³¨å†Œå’Œåˆ 除功能也有一个 -_nocallsçš„åŽç¼€ï¼Œå¦‚æžœä¸å¸Œæœ›è°ƒç”¨å›žè°ƒï¼Œåˆ™ä¸è°ƒç”¨æ‰€æ供的回调。在手动设置（或关é—）期间， -应该使用 ``get_online_cpus()`` å’Œ ``put_online_cpus()`` 函数æ¥æŠ‘制CPUçƒæ’æ‹”æ“作。 +æ ·ä¾‹ +---- +在STARTING阶段设置和å–消é™æ€åˆ†é…的状æ€ï¼Œä»¥èŽ·å–上线和下线æ“作的通知:: -äº‹ä»¶çš„é¡ºåº ----------- + ret = cpuhp_setup_state(CPUHP_SUBSYS_STARTING, "subsys:starting", subsys_cpu_starting, subsys_cpu_dying); + if (ret < 0) + return ret; + .... + cpuhp_remove_state(CPUHP_SUBSYS_STARTING); -çƒæ’拔状æ€è¢«å®šä¹‰åœ¨ ``include/linux/cpuhotplug.h``: +在ONLINE阶段设置和å–消动æ€åˆ†é…的状æ€ï¼Œä»¥èŽ·å–下线æ“作的通知:: -* ``CPUHP_OFFLINE`` ... ``CPUHP_AP_OFFLINE`` 状æ€æ˜¯åœ¨CPUå¯åŠ¨å‰è°ƒç”¨çš„。 + state = cpuhp_setup_state(CPUHP_ONLINE_DYN, "subsys:offline", NULL, subsys_cpu_offline); + if (state < 0) + return state; + .... + cpuhp_remove_state(state); -* ``CPUHP_AP_OFFLINE`` ... ``CPUHP_AP_ONLINE`` 状æ€æ˜¯åœ¨CPU被å¯åŠ¨åŽè¢«è°ƒç”¨çš„。 - ä¸æ–是关é—的，调度程åºè¿˜æ²¡æœ‰åœ¨è¿™ä¸ªCPU上活动。从 ``CPUHP_AP_OFFLINE`` 开始， - å›žè°ƒè¢«è°ƒç”¨åˆ°ç›®æ ‡CPU上。 +在ONLINE阶段设置和å–消动æ€åˆ†é…的状æ€ï¼Œä»¥èŽ·å–有关上线æ“ä½œçš„é€šçŸ¥ï¼Œè€Œæ— éœ€è°ƒç”¨å›žè°ƒ:: -* ``CPUHP_AP_ONLINE_DYN`` å’Œ ``CPUHP_AP_ONLINE_DYN_END`` 之间的状æ€è¢«ä¿ç•™ - 给动æ€åˆ†é…。 + state = cpuhp_setup_state_nocalls(CPUHP_ONLINE_DYN, "subsys:online", subsys_cpu_online, NULL); + if (state < 0) + return state; + .... + cpuhp_remove_state_nocalls(state); -* 这些状æ€åœ¨CPUå…³é—时以相å的顺åºè°ƒç”¨ï¼Œä»Ž ``CPUHP_ONLINE`` 开始，在 ``CPUHP_OFFLINE`` - åœæ¢ã€‚这里的回调是在将被关é—çš„CPU上调用的，直到 ``CPUHP_AP_OFFLINE`` 。 +在ONLINE阶段设置ã€ä½¿ç”¨å’Œå–消动æ€åˆ†é…的多实例状æ€ï¼Œä»¥èŽ·å¾—上线和下线æ“作的通知:: -通过 ``CPUHP_AP_ONLINE_DYN`` 动æ€åˆ†é…的状æ€é€šå¸¸å·²ç»è¶³å¤Ÿäº†ã€‚然而，如果在å¯åŠ¨æˆ–å…³é— -期间需è¦æ›´æ—©çš„调用，那么应该获得一个显å¼çŠ¶æ€ã€‚如果çƒæ‹”æ’事件需è¦ç›¸å¯¹äºŽå¦ä¸€ä¸ªçƒæ‹”æ’事 -件的特定排åºï¼Œä¹Ÿå¯èƒ½éœ€è¦ä¸€ä¸ªæ˜¾å¼çŠ¶æ€ã€‚ + state = cpuhp_setup_state_multi(CPUHP_ONLINE_DYN, "subsys:online", subsys_cpu_online, subsys_cpu_offline); + if (state < 0) + return state; + .... + ret = cpuhp_state_add_instance(state, &inst1->node); + if (ret) + return ret; + .... + ret = cpuhp_state_add_instance(state, &inst2->node); + if (ret) + return ret; + .... + cpuhp_remove_instance(state, &inst1->node); + .... + cpuhp_remove_instance(state, &inst2->node); + .... + remove_multi_state(state); 测试çƒæ‹”æ’çŠ¶æ€ ============== diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst index 26d9913fc8b6..7ca44629860c 100644 --- a/Documentation/translations/zh_CN/core-api/index.rst +++ b/Documentation/translations/zh_CN/core-api/index.rst @@ -28,6 +28,7 @@ printk-basics printk-formats workqueue + watch_queue symbol-namespaces æ•°æ®ç»“æž„å’Œä½Žçº§å®žç”¨ç¨‹åº diff --git a/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst b/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst index 7d077742f758..9174fce12c1b 100644 --- a/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst +++ b/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst @@ -5,6 +5,7 @@ :翻译: å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> .. _cn_irq-domain.rst: @@ -52,8 +53,18 @@ irq_domain和一个hwirqå·ä½œä¸ºå‚数。 如果hwirqçš„æ˜ å°„è¿˜ä¸å˜åœ¨ï¼Œé‚ 一个新的Linux irq_desc，将其与hwirqå…³è”èµ·æ¥ï¼Œå¹¶è°ƒç”¨.map()å›žè°ƒï¼Œè¿™æ ·é©±åŠ¨ 程åºå°±å¯ä»¥æ‰§è¡Œä»»ä½•å¿…è¦çš„硬件设置。 -当接收到一个ä¸æ–时，应该使用irq_find_mapping()函数从hwirqå·ä¸æ‰¾åˆ° -Linux IRQå·ã€‚ +ä¸€æ—¦å»ºç«‹äº†æ˜ å°„ï¼Œå¯ä»¥é€šè¿‡å¤šç§æ–¹æ³•æ£€ç´¢æˆ–使用它： + +- irq_resolve_mapping()返回一个指å‘给定域和hwirqå·çš„irq_desc结构指针， + å¦‚æžœæ²¡æœ‰æ˜ å°„åˆ™è¿”å›žNULL。 + +- irq_find_mapping()返回给定域和hwirqçš„Linux IRQå·ï¼Œå¦‚æžœæ²¡æœ‰æ˜ å°„åˆ™è¿”å›ž0。 + +- irq_linear_revmap()现与irq_find_mapping()相åŒï¼Œå·²è¢«åºŸå¼ƒã€‚ + +- generic_handle_domain_irq()处ç†ä¸€ä¸ªç”±åŸŸå’Œhwirqå·æè¿°çš„ä¸æ–。 + +请注æ„，irq域的查找必须å‘生在与RCU读临界区兼容的上下文ä¸ã€‚ 在调用irq_find_mapping()之å‰ï¼Œè‡³å°‘è¦è°ƒç”¨ä¸€æ¬¡irq_create_mapping()函数， 以å…æ述符ä¸èƒ½è¢«åˆ†é…。 @@ -119,7 +130,8 @@ irq_domain_add_tree()å’Œirq_domain_create_tree()在功能上是ç‰ä»·çš„ï¼Œé™¤äº Linux IRQå·ç¼–å…¥ç¡¬ä»¶æœ¬èº«ï¼Œè¿™æ ·å°±ä¸éœ€è¦æ˜ 射了。 调用irq_create_direct_mapping() 会分é…一个Linux IRQå·ï¼Œå¹¶è°ƒç”¨.map()å›žè°ƒï¼Œè¿™æ ·é©±åŠ¨å°±å¯ä»¥å°†Linux IRQå·ç¼–入硬件ä¸ã€‚ -大多数驱动程åºä¸èƒ½ä½¿ç”¨è¿™ä¸ªæ˜ 射。 +大多数驱动程åºæ— 法使用æ¤æ˜ 射，现在它由CONFIG_IRQ_DOMAIN_NOMAP选项控制。 +请ä¸è¦å¼•å…¥æ¤API的新用户。 ä¼ ç»Ÿæ˜ å°„ç±»åž‹ ------------ @@ -128,7 +140,6 @@ Linux IRQå·ç¼–å…¥ç¡¬ä»¶æœ¬èº«ï¼Œè¿™æ ·å°±ä¸éœ€è¦æ˜ 射了。 调用irq_create irq_domain_add_simple() irq_domain_add_legacy() - irq_domain_add_legacy_isa() irq_domain_create_simple() irq_domain_create_legacy() @@ -137,6 +148,9 @@ Linux IRQå·ç¼–å…¥ç¡¬ä»¶æœ¬èº«ï¼Œè¿™æ ·å°±ä¸éœ€è¦æ˜ 射了。 调用irq_create 一组用于IRQå·çš„定义（#defineï¼‰ï¼Œè¿™äº›å®šä¹‰è¢«ä¼ é€’ç»™struct设备注册。 在这ç§æƒ…况下， ä¸èƒ½åŠ¨æ€åˆ†é…Linux IRQå·ï¼Œåº”è¯¥ä½¿ç”¨ä¼ ç»Ÿæ˜ å°„ã€‚ +顾åæ€ä¹‰ï¼Œ\*_legacy()系列函数已被废弃，åªæ˜¯ä¸ºäº†æ–¹ä¾¿å¯¹å¤è€å¹³å°çš„支æŒè€Œå˜åœ¨ã€‚ +ä¸åº”è¯¥å¢žåŠ æ–°çš„ç”¨æˆ·ã€‚å½“\*_simple()系列函数的使用导致é—留行为时，他们也是如æ¤ã€‚ + ä¼ ç»Ÿæ˜ å°„å‡è®¾å·²ç»ä¸ºæŽ§åˆ¶å™¨åˆ†é…了一个连ç»çš„IRQå·èŒƒå›´ï¼Œå¹¶ä¸”å¯ä»¥é€šè¿‡å‘hwirqå·æ·»åŠ 一 个固定的å移æ¥è®¡ç®—IRQå·ï¼Œå之亦然。 缺点是需è¦ä¸æ–控制器管ç†IRQ分é…，并且需è¦ä¸ºæ¯ 个hwirq分é…一个irq_desc，å³ä½¿å®ƒæ²¡æœ‰è¢«ä½¿ç”¨ã€‚ diff --git a/Documentation/translations/zh_CN/core-api/kernel-api.rst b/Documentation/translations/zh_CN/core-api/kernel-api.rst index e45fe80d1cd8..c22662679065 100644 --- a/Documentation/translations/zh_CN/core-api/kernel-api.rst +++ b/Documentation/translations/zh_CN/core-api/kernel-api.rst @@ -5,6 +5,7 @@ :翻译: å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> .. _cn_kernel-api.rst: @@ -224,7 +225,7 @@ kernel/kmod.c 模å—接å£æ”¯æŒ ------------ -更多信æ¯è¯·å‚考文件kernel/module.c。 +更多信æ¯è¯·å‚阅kernel/module/目录下的文件。 ç¡¬ä»¶æŽ¥å£ ======== @@ -282,6 +283,8 @@ kernel/acct.c 该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: +include/linux/bio.h + block/blk-core.c block/blk-core.c diff --git a/Documentation/translations/zh_CN/core-api/mm-api.rst b/Documentation/translations/zh_CN/core-api/mm-api.rst index 0ea43dc67953..a732b0eebf16 100644 --- a/Documentation/translations/zh_CN/core-api/mm-api.rst +++ b/Documentation/translations/zh_CN/core-api/mm-api.rst @@ -5,6 +5,7 @@ :翻译: å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> :æ ¡è¯‘: @@ -66,12 +67,24 @@ mm/vmalloc.c 该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: -mm/readahead.c +æ–‡ä»¶æ˜ å°„ +-------- mm/filemap.c +预读 +---- + +mm/readahead.c + +回写 +---- + mm/page-writeback.c +æˆªæ– +---- + mm/truncate.c include/linux/pagemap.h @@ -105,6 +118,14 @@ mm/mempolicy.c include/linux/mm_types.h +include/linux/mm_inline.h + +include/linux/page-flags.h + include/linux/mm.h +include/linux/page_ref.h + include/linux/mmzone.h + +mm/util.c diff --git a/Documentation/translations/zh_CN/core-api/printk-basics.rst b/Documentation/translations/zh_CN/core-api/printk-basics.rst index d574de3167c8..59c6efb3fc41 100644 --- a/Documentation/translations/zh_CN/core-api/printk-basics.rst +++ b/Documentation/translations/zh_CN/core-api/printk-basics.rst @@ -6,6 +6,7 @@ :翻译: å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> .. _cn_printk-basics.rst: @@ -107,6 +108,4 @@ pr_debug()å’Œpr_devel()，除éžå®šä¹‰äº† ``DEBUG`` (或者在pr_debug()çš„æƒ…å† è¯¥APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: -kernel/printk/printk.c - include/linux/printk.h diff --git a/Documentation/translations/zh_CN/core-api/printk-formats.rst b/Documentation/translations/zh_CN/core-api/printk-formats.rst index ce39c788cf5a..bd36d35eba4e 100644 --- a/Documentation/translations/zh_CN/core-api/printk-formats.rst +++ b/Documentation/translations/zh_CN/core-api/printk-formats.rst @@ -5,6 +5,7 @@ :翻译: å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> .. _cn_printk-formats.rst: @@ -548,7 +549,7 @@ nodemask_pr_args()æ¥æ–¹ä¾¿æ‰“å°cpumaskå’Œnodemask。 :: - %pGp referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff + %pGp 0x17ffffc0002036(referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff) %pGg GFP_USER|GFP_DMA32|GFP_NOWARN %pGv read|exec|mayread|maywrite|mayexec|denywrite diff --git a/Documentation/translations/zh_CN/core-api/symbol-namespaces.rst b/Documentation/translations/zh_CN/core-api/symbol-namespaces.rst index 6abf7ed534ca..bb16f0611046 100644 --- a/Documentation/translations/zh_CN/core-api/symbol-namespaces.rst +++ b/Documentation/translations/zh_CN/core-api/symbol-namespaces.rst @@ -52,7 +52,7 @@ 相应的 ksymtab æ¡ç›®ç»“构体 ``kernel_symbol`` 将有相应的æˆå‘˜ ``命å空间`` 集。 导出时未指明命å空间的符å·å°†æŒ‡å‘ ``NULL`` 。如果没有定义命å空间，则默认没有。 -``modpost`` å’Œkernel/module.c分别在构建时或模å—åŠ è½½æ—¶ä½¿ç”¨å称空间。 +``modpost`` å’Œkernel/module/main.c分别在构建时或模å—åŠ è½½æ—¶ä½¿ç”¨å称空间。 2.2 使用DEFAULT_SYMBOL_NAMESPACE定义 ==================================== diff --git a/Documentation/translations/zh_CN/core-api/watch_queue.rst b/Documentation/translations/zh_CN/core-api/watch_queue.rst new file mode 100644 index 000000000000..23b17ae2e4e2 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/watch_queue.rst @@ -0,0 +1,313 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/watch_queue.rst + +:翻译: + +周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> + +:æ ¡è¯‘: + +å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> +å´æƒ³æˆ Wu Xiangcheng <bobwxc@email.cn> + + +============ +通用通知机制 +============ + +é€šç”¨é€šçŸ¥æœºåˆ¶æ˜¯å»ºç«‹åœ¨æ ‡å‡†ç®¡é“驱动之上的，它å¯ä»¥æœ‰æ•ˆåœ°å°†æ¥è‡ªå†…æ ¸çš„é€šçŸ¥æ¶ˆæ¯æ‹¼æŽ¥åˆ°ç”¨ +户空间打开的管é“ä¸ã€‚è¿™å¯ä»¥ä¸Žä»¥ä¸‹æ–¹é¢ç»“åˆä½¿ç”¨:: + + * Key/keyring 通知 + +通知缓冲区å¯ä»¥é€šè¿‡ä»¥ä¸‹æ–¹å¼å¯ç”¨ï¼š + + “General setupâ€/“General notification queue†+ (CONFIG_WATCH_QUEUE) + +文档包å«ä»¥ä¸‹ç« 节： + +.. contents:: :local: + + +概述 +==== + +该设施以一ç§ç‰¹æ®Šæ¨¡å¼æ‰“开的管é“å½¢å¼å‡ºçŽ°ï¼Œç®¡é“的内部环形缓冲区用于ä¿å˜å†…æ ¸ç”Ÿæˆçš„消 +æ¯ã€‚然åŽé€šè¿‡read()读出这些消æ¯ã€‚在æ¤ç±»ç®¡é“上ç¦ç”¨æ‹¼æŽ¥ä»¥åŠç±»ä¼¼çš„æ“ä½œï¼Œå› ä¸ºå®ƒä»¬å¸Œæœ› +在æŸäº›æƒ…å†µä¸‹å°†å…¶æ·»åŠ çš„å†…å®¹è¿˜åŽŸåˆ°çŽ¯ä¸-è¿™å¯èƒ½æœ€ç»ˆä¼šä¸Žé€šçŸ¥æ¶ˆæ¯é‡å 。 + +管é“çš„æ‰€æœ‰è€…å¿…é¡»å‘Šè¯‰å†…æ ¸å®ƒæƒ³é€šè¿‡è¯¥ç®¡é“观察哪些æºã€‚åªæœ‰è¿žæŽ¥åˆ°è¯¥ç®¡é“上的æºæ‰ä¼šå°†æ¶ˆ +æ¯æ’入其ä¸ã€‚请注æ„，一个æºå¯èƒ½ç»‘定到多个管é“，并åŒæ—¶å°†æ¶ˆæ¯æ’入到所有管é“ä¸ã€‚ + +还å¯ä»¥å°†è¿‡æ»¤å™¨æ”¾ç½®åœ¨ç®¡é“上，以便在ä¸æ„Ÿå…´è¶£æ—¶å¯ä»¥å¿½ç•¥æŸäº›æºç±»åž‹å’Œå事件。 + +如果环ä¸æ²¡æœ‰å¯ç”¨çš„æ’槽，或者没有预分é…的消æ¯ç¼“冲区å¯ç”¨ï¼Œåˆ™å°†ä¸¢å¼ƒæ¶ˆæ¯ã€‚在这两ç§æƒ… +况下，read()都会在读å–缓冲区ä¸å½“å‰çš„最åŽä¸€æ¡æ¶ˆæ¯åŽï¼Œå°†WATCH_META_LOSS_NOTIFICATION +æ’入到输出缓冲区ä¸ã€‚ + +请注æ„，当生æˆä¸€ä¸ªé€šçŸ¥æ—¶ï¼Œå†…æ ¸ä¸ä¼šç‰å¾…消费者收集它，而是继ç»æ‰§è¡Œã€‚è¿™æ„味ç€å¯ä»¥åœ¨ +æŒæœ‰è‡ªæ—‹é”çš„åŒæ—¶ç”Ÿæˆé€šçŸ¥ï¼Œå¹¶ä¸”还å¯ä»¥ä¿æŠ¤å†…æ ¸ä¸è¢«ç”¨æˆ·ç©ºé—´æ•…éšœæ— é™æœŸåœ°é˜»ç¢ã€‚ + + +消æ¯ç»“æž„ +======== + +通知消æ¯ç”±ä¸€ä¸ªç®€çŸçš„头部开始:: + + struct watch_notification { + __u32 type:24; + __u32 subtype:8; + __u32 info; + }; + +“typeâ€è¡¨ç¤ºé€šçŸ¥è®°å½•çš„æ¥æºï¼Œâ€œsubtypeâ€è¡¨ç¤ºè¯¥æ¥æºçš„记录类型（è§ä¸‹æ–‡è§‚测æºç« 节）。该类 +型也å¯ä»¥æ˜¯â€œWATCH_TYPE_METAâ€ã€‚这是一个由观测队列本身在内部生æˆçš„特殊记录类型。有两 +个å类型： + + * WATCH_META_REMOVAL_NOTIFICATION + * WATCH_META_LOSS_NOTIFICATION + +ç¬¬ä¸€ä¸ªè¡¨ç¤ºå®‰è£…äº†è§‚å¯Ÿçš„å¯¹è±¡å·²è¢«åˆ é™¤æˆ–é”€æ¯ï¼Œç¬¬äºŒä¸ªè¡¨ç¤ºæŸäº›æ¶ˆæ¯å·²ä¸¢å¤±ã€‚ + +“infoâ€è¡¨ç¤ºä¸€ç³»åˆ—东西，包括： + + * 消æ¯çš„长度，以å—节为å•ä½ï¼ŒåŒ…括头（带有WATCH_INFO_LENGTH的掩ç ，并按 + WATCH_INFO_LENGTH__SHIFT移ä½ï¼‰ã€‚这表示记录的大å°ï¼Œå¯èƒ½åœ¨8到127å—节之间。 + + * 观测ID（带有WATCH_INFO_ID掩ç ，并按WATCH_INFO_ID__SHIFT移ä½ï¼‰ã€‚这表示观测的主 + å«ID，å¯èƒ½åœ¨0到255之间。多个观测组å¯ä»¥å…±äº«ä¸€ä¸ªé˜Ÿåˆ—，这æ供了一ç§åŒºåˆ†å®ƒä»¬çš„方法。 + + * 特定类型的å—段（WATCH_INFO_TYPE_INFO）。这是由通知生产者设置的，以指示类型和 + å类型的æŸäº›ç‰¹å®šå«ä¹‰ã€‚ + +除长度外，信æ¯ä¸çš„所有内容都å¯ä»¥ç”¨äºŽè¿‡æ»¤ã€‚ + +头部åŽé¢å¯ä»¥æœ‰è¡¥å……ä¿¡æ¯ã€‚æ¤æ ¼å¼æ˜¯ç”±ç±»åž‹å’Œå类型决定的。 + + +观测列表（通知æºï¼‰API +===================== + +“观测列表“是订阅通知æºçš„观测者的列表。列表å¯ä»¥é™„åŠ åˆ°å¯¹è±¡ï¼ˆæ¯”å¦‚é”®æˆ–è¶…çº§å—ï¼‰ï¼Œä¹Ÿå¯ +以是全局的（比如对于设备事件）。从用户空间的角度æ¥çœ‹ï¼Œä¸€ä¸ªéžå…¨å±€çš„观测列表通常是 +通过引用它所属的对象æ¥å¼•ç”¨çš„（比如使用KEYCTL_NOTIFY并给它一个密钥åºåˆ—å·æ¥è§‚测特定 +的密钥）。 + +为了管ç†è§‚测列表，æ供了以下函数： + + * :: + + void init_watch_list(struct watch_list *wlist, + void (*release_watch)(struct watch *wlist)); + + åˆå§‹åŒ–一个观测列表。 如果 ``release_watch`` ä¸æ˜¯NULL，那么这表示当watch_list对 + 象被销æ¯æ—¶ï¼Œåº”该调用函数æ¥ä¸¢å¼ƒè§‚测列表对被观测对象的任何引用。 + + * ``void remove_watch_list(struct watch_list *wlist);`` + + è¿™å°†åˆ é™¤è®¢é˜…watch_list的所有观测，并释放它们，然åŽé”€æ¯watch_list对象本身。 + + +观测队列（通知输出）API +======================= + +“观测队列â€æ˜¯ç”±åº”用程åºåˆ†é…的用以记录通知的缓冲区，其工作原ç†å®Œå…¨éšè—在管é“设备驱 +动ä¸ï¼Œä½†å¿…须获得对它的引用æ‰èƒ½è®¾ç½®è§‚测。å¯ä»¥é€šè¿‡ä»¥ä¸‹æ–¹å¼è¿›è¡Œç®¡ç†ï¼š + + * ``struct watch_queue *get_watch_queue(int fd);`` + + ç”±äºŽè§‚æµ‹é˜Ÿåˆ—åœ¨å†…æ ¸ä¸é€šè¿‡å®žçŽ°ç¼“冲区的管é“的文件æ述符表示，用户空间必须通过系 + ç»Ÿè°ƒç”¨ä¼ é€’è¯¥æ–‡ä»¶æ述符，这å¯ä»¥ç”¨äºŽä»Žç³»ç»Ÿè°ƒç”¨ä¸æŸ¥æ‰¾æŒ‡å‘观测队列的ä¸é€æ˜ŽæŒ‡é’ˆã€‚ + + * ``void put_watch_queue(struct watch_queue *wqueue);`` + + 该函数用以丢弃从 ``get_watch_queue()`` 获得的引用。 + + +观测订阅API +=========== + +“观测â€æ˜¯è§‚测列表上的订阅，表示观测队列，从而表示应写入通知记录的缓冲区。观测队列 +对象还å¯ä»¥æºå¸¦è¯¥å¯¹è±¡çš„过滤规则，由用户空间设置。watch结构体的æŸäº›éƒ¨åˆ†å¯ä»¥ç”±é©±åŠ¨ç¨‹ +åºè®¾ç½®:: + + struct watch { + union { + u32 info_id; /* 在infoå—段ä¸è¿›è¡ŒORè¿ç®—çš„ID */ + ... + }; + void *private; /* 被观测对象的ç§æœ‰æ•°æ® */ + u64 id; /* å†…éƒ¨æ ‡è¯†ç¬¦ */ + ... + }; + +``info_id`` 值是从用户空间获得并按WATCH_INFO_ID__SHIFT移ä½çš„8ä½æ•°å—。当通知写入关 +è”的观测队列缓冲区时，这将与struct watch_notification::infoçš„WATCH_INFO_IDå—段进 +行或è¿ç®—。 + +``private`` å—段是与watch_list相关è”的驱动程åºæ•°æ®ï¼Œå¹¶ç”± ``watch_list::release_watch()`` +函数清除。 + +``id`` å—段是æºçš„ID。使用ä¸åŒIDå‘布的通知将被忽略。 + +æ供以下函数æ¥ç®¡ç†è§‚测: + + * ``void init_watch(struct watch *watch, struct watch_queue *wqueue);`` + + åˆå§‹åŒ–一个观测对象，把它的指针设置到观察队列ä¸ï¼Œä½¿ç”¨é€‚当的é™åˆ¶æ¥é¿å…æ»é”。 + + * ``int add_watch_to_object(struct watch *watch, struct watch_list *wlist);`` + + 将观测订阅到观测列表（通知æºï¼‰ã€‚watch结构体ä¸çš„driver-settableå—段必须在调用 + 它之å‰è®¾ç½®ã€‚ + + * :: + + int remove_watch_from_object(struct watch_list *wlist, + struct watch_queue *wqueue, + u64 id, false); + + 从观测列表ä¸åˆ 除一个观测，该观测必须与指定的观测队列（``wqueue``ï¼‰å’Œå¯¹è±¡æ ‡è¯† + 符（``id``）匹é…。通知（``WATCH_META_REMOVAL_NOTIFICATION``）被å‘é€åˆ°è§‚测队列 + è¡¨ç¤ºè¯¥è§‚æµ‹å·²è¢«åˆ é™¤ã€‚ + + * ``int remove_watch_from_object(struct watch_list *wlist, NULL, 0, true);`` + + 从观测列表ä¸åˆ 除所有观测。预计这将被称为销æ¯å‰çš„å‡†å¤‡å·¥ä½œï¼Œå±Šæ—¶æ–°çš„è§‚æµ‹å°†æ— æ³• + 访问观测列表。通知（``WATCH_META_REMOVAL_NOTIFICATION``）被å‘é€åˆ°æ¯ä¸ªè®¢é˜…观测 + çš„è§‚æµ‹é˜Ÿåˆ—ï¼Œä»¥è¡¨æ˜Žè¯¥è§‚æµ‹å·²è¢«åˆ é™¤ã€‚ + + +通知å‘布API +=========== + +è¦å°†é€šçŸ¥å‘布到观测列表以便订阅的观测å¯ä»¥çœ‹åˆ°ï¼Œåº”使用以下函数:: + + void post_watch_notification(struct watch_list *wlist, + struct watch_notification *n, + const struct cred *cred, + u64 id); + +åº”é¢„å…ˆè®¾ç½®é€šçŸ¥æ ¼å¼ï¼Œå¹¶åº”ä¼ å…¥ä¸€ä¸ªæŒ‡å‘头部（``n``）的指针。通知å¯èƒ½å¤§äºŽæ¤å€¼ï¼Œå¹¶ä¸”缓 +冲槽为å•ä½çš„大å°åœ¨ ``n->info & WATCH_INFO_LENGTH`` ä¸æ³¨æ˜Žã€‚ + +``cred`` 结构体表示æºï¼ˆå¯¹è±¡ï¼‰çš„è¯ä¹¦ï¼Œå¹¶ä¼ 递给LSM，例如SELinux，以å…许或ç¦æ¢æ ¹æ®è¯¥é˜Ÿ +列（对象）的è¯ä¹¦åœ¨æ¯ä¸ªå•ç‹¬é˜Ÿåˆ—ä¸è®°å½•æ³¨é‡Šã€‚ + +``id`` 是æºå¯¹è±¡ID（如密钥上的åºåˆ—å·ï¼‰ã€‚åªæœ‰è®¾ç½®ç›¸åŒID的观测æ‰èƒ½çœ‹åˆ°è¿™ä¸ªé€šçŸ¥ã€‚ + + +è§‚æµ‹æº +====== + +任何特定的缓冲区都å¯ä»¥ä»Žå¤šä¸ªæºèŽ·å–ä¿¡æ¯ã€‚ 这些æºåŒ…括: + + * WATCH_TYPE_KEY_NOTIFY + + è¿™ç§ç±»åž‹çš„通知表示密钥和密钥环的å˜åŒ–，包括密钥环内容或密钥属性的å˜åŒ–。 + + 更多信æ¯è¯·å‚è§Documentation/security/keys/core.rst。 + + +事件过滤 +======== + +当创建观测队列åŽï¼Œæˆ‘们å¯ä»¥åº”用一组过滤器以é™åˆ¶æŽ¥æ”¶çš„事件:: + + struct watch_notification_filter filter = { + ... + }; + ioctl(fd, IOC_WATCH_QUEUE_SET_FILTER, &filter) + +过滤器的æ述的类型å˜é‡æ˜¯:: + + struct watch_notification_filter { + __u32 nr_filters; + __u32 __reserved; + struct watch_notification_type_filter filters[]; + }; + +å…¶ä¸â€œnr_filtersâ€è¡¨ç¤ºfilters[]数组ä¸è¿‡æ»¤å™¨çš„æ•°é‡ï¼Œè€Œâ€œ__reservedâ€åº”为0。 +“filterâ€æ•°ç»„æœ‰ä»¥ä¸‹ç±»åž‹çš„å…ƒç´ :: + + struct watch_notification_type_filter { + __u32 type; + __u32 info_filter; + __u32 info_mask; + __u32 subtype_filter[8]; + }; + +å…¶ä¸ï¼š + + * ``type`` 是过滤的事件类型，应类似于“WATCH_TYPE_KEY_NOTIFYâ€ã€‚ + + * ``info_filter`` 与 ``info_mask`` 充当通知记录的信æ¯å—段的过滤器，åªæœ‰åœ¨ä»¥ä¸‹æƒ… + 况，通知æ‰ä¼šå†™å…¥ç¼“冲区:: + + (watch.info & info_mask) == info_filter + + 例如，这å¯ä»¥ç”¨äºŽå¿½ç•¥ä¸åœ¨ä¸€ä¸ªæŒ‚è½½æ ‘ä¸Šçš„è§‚æµ‹ç‚¹çš„äº‹ä»¶ã€‚ + + * ``subtype_filter`` 是一个ä½æŽ©ç ，表示感兴趣的å类型。subtype_filter[0]çš„ + bit[0]对应å类型0，bit[1]对应å类型1，以æ¤ç±»æŽ¨ã€‚ + +è‹¥ioctl()çš„å‚数为NULL，则过滤器将被移除，并且æ¥è‡ªè§‚测æºçš„所有事件都将通过。 + + +用户空间代ç 示例 +================ + +缓冲区的创建如下所示:: + + pipe2(fds, O_TMPFILE); + ioctl(fds[1], IOC_WATCH_QUEUE_SET_SIZE, 256); + +它å¯ä»¥è¢«è®¾ç½®æˆæŽ¥æ”¶å¯†é’¥çŽ¯å˜åŒ–的通知:: + + keyctl(KEYCTL_WATCH_KEY, KEY_SPEC_SESSION_KEYRING, fds[1], 0x01); + +然åŽï¼Œè¿™äº›é€šçŸ¥å¯ä»¥è¢«å¦‚下方å¼æ‰€ä½¿ç”¨:: + + static void consumer(int rfd, struct watch_queue_buffer *buf) + { + unsigned char buffer[128]; + ssize_t buf_len; + + while (buf_len = read(rfd, buffer, sizeof(buffer)), + buf_len > 0 + ) { + void *p = buffer; + void *end = buffer + buf_len; + while (p < end) { + union { + struct watch_notification n; + unsigned char buf1[128]; + } n; + size_t largest, len; + + largest = end - p; + if (largest > 128) + largest = 128; + memcpy(&n, p, largest); + + len = (n->info & WATCH_INFO_LENGTH) >> + WATCH_INFO_LENGTH__SHIFT; + if (len == 0 || len > largest) + return; + + switch (n.n.type) { + case WATCH_TYPE_META: + got_meta(&n.n); + case WATCH_TYPE_KEY_NOTIFY: + saw_key_change(&n.n); + break; + } + + p += len; + } + } + } diff --git a/Documentation/translations/zh_CN/core-api/workqueue.rst b/Documentation/translations/zh_CN/core-api/workqueue.rst index e372fa5cf101..f6567cf9d3fb 100644 --- a/Documentation/translations/zh_CN/core-api/workqueue.rst +++ b/Documentation/translations/zh_CN/core-api/workqueue.rst @@ -6,6 +6,7 @@ :翻译: å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> .. _cn_workqueue.rst: @@ -178,10 +179,6 @@ workqueue将自动创建与属性相匹é…çš„åŽå¤‡å·¥ä½œè€…æ± ã€‚è°ƒèŠ‚å¹¶å‘æ° è¿™ä¸ªæ ‡å¿—å¯¹äºŽæœªç»‘å®šçš„wqæ¥è¯´æ˜¯æ²¡æœ‰æ„义的。 -请注æ„ï¼Œæ ‡å¿— ``WQ_NON_REENTRANT`` ä¸å†å˜åœ¨ï¼Œå› 为现在所有的工作 -队列都是ä¸å¯é€†çš„——任何工作项都ä¿è¯åœ¨ä»»ä½•æ—¶é—´å†…最多被整个系统的一 -个工作者执行。 - ``max_active`` -------------- @@ -328,6 +325,22 @@ And with cmwq with ``@max_active`` >= 3, :: å·¥ä½œé¡¹å‡½æ•°åœ¨å †æ ˆè¿½è¸ªä¸åº”该是微ä¸è¶³é“的。 +ä¸å¯é‡å…¥æ¡ä»¶ +============ + +工作队列ä¿è¯ï¼Œå¦‚果在工作项排队åŽæ»¡è¶³ä»¥ä¸‹æ¡ä»¶ï¼Œåˆ™å·¥ä½œé¡¹ä¸èƒ½é‡å…¥ï¼š + + + 1. 工作函数没有被改å˜ã€‚ + 2. 没有人将该工作项排到å¦ä¸€ä¸ªå·¥ä½œé˜Ÿåˆ—ä¸ã€‚ + 3. 该工作项尚未被é‡æ–°å¯åŠ¨ã€‚ + +æ¢è¨€ä¹‹ï¼Œå¦‚果上述æ¡ä»¶æˆç«‹ï¼Œåˆ™ä¿è¯åœ¨ä»»ä½•ç»™å®šæ—¶é—´æœ€å¤šç”±ä¸€ä¸ªç³»ç»ŸèŒƒå›´å†…的工作程åºæ‰§è¡Œ +该工作项。 + +请注æ„，在self函数ä¸å°†å·¥ä½œé¡¹é‡æ–°æŽ’队（到åŒä¸€é˜Ÿåˆ—）ä¸ä¼šç ´å这些æ¡ä»¶ï¼Œå› æ¤å¯ä»¥å®‰å…¨ +地执行æ¤æ“作。å¦åˆ™åœ¨ç ´å工作函数内部的æ¡ä»¶æ—¶éœ€è¦å°å¿ƒã€‚ + å†…æ ¸å†…è”文档å‚考 ================ diff --git a/Documentation/translations/zh_CN/core-api/xarray.rst b/Documentation/translations/zh_CN/core-api/xarray.rst index ff2d9bcb7c34..fb19324966ce 100644 --- a/Documentation/translations/zh_CN/core-api/xarray.rst +++ b/Documentation/translations/zh_CN/core-api/xarray.rst @@ -6,6 +6,7 @@ :翻译: å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> :æ ¡è¯‘: @@ -254,7 +255,8 @@ __xa_set_mark() å’Œ __xa_clear_mark() å‡½æ•°ä¹Ÿé€‚ç”¨äºŽä½ æŸ¥æ‰¾ä¸€ä¸ªæ¡ç›®å¹¶ 高级API是基于xa_state的。这是一个ä¸é€æ˜Žçš„æ•°æ®ç»“æž„ï¼Œä½ ä½¿ç”¨XA_STATE()å®åœ¨å †æ ˆä¸å£°æ˜Žã€‚这个å®åˆå§‹åŒ–了 xa_state，准备开始在XArrayä¸Šç§»åŠ¨ã€‚å®ƒè¢«ç”¨ä½œä¸€ä¸ªæ¸¸æ ‡æ¥ä¿æŒåœ¨XArrayä¸çš„ä½ç½®ï¼Œå¹¶è®©ä½ 把å„ç§æ“作组åˆåœ¨ä¸€ -起，而ä¸å¿…æ¯æ¬¡éƒ½ä»Žå¤´å¼€å§‹ã€‚ +起，而ä¸å¿…æ¯æ¬¡éƒ½ä»Žå¤´å¼€å§‹ã€‚xa_state的内容å—rcu_read_lock()或xas_lock()çš„ä¿æŠ¤ã€‚如果需è¦åˆ 除ä¿æŠ¤çŠ¶æ€ +å’Œæ ‘çš„è¿™äº›é”ä¸çš„ä»»ä½•ä¸€ä¸ªï¼Œä½ å¿…é¡»è°ƒç”¨xas_pause()以便将æ¥çš„调用ä¸ä¼šä¾èµ–于状æ€ä¸æœªå—ä¿æŠ¤çš„部分。 xa_state也被用æ¥å˜å‚¨é”™è¯¯(store errors)ã€‚ä½ å¯ä»¥è°ƒç”¨xas_error()æ¥æ£€ç´¢é”™è¯¯ã€‚所有的æ“作在进行之å‰éƒ½ 会检查xa_state是å¦å¤„于错误状æ€ï¼Œæ‰€ä»¥ä½ 没有必è¦åœ¨æ¯æ¬¡è°ƒç”¨ä¹‹åŽæ£€æŸ¥é”™è¯¯ï¼›ä½ å¯ä»¥è¿žç»è¿›è¡Œå¤šæ¬¡è°ƒç”¨ï¼Œåªåœ¨ diff --git a/Documentation/translations/zh_CN/dev-tools/kasan.rst b/Documentation/translations/zh_CN/dev-tools/kasan.rst index 23db9d419047..fe76cbe77ad6 100644 --- a/Documentation/translations/zh_CN/dev-tools/kasan.rst +++ b/Documentation/translations/zh_CN/dev-tools/kasan.rst @@ -11,34 +11,65 @@ 概述 ---- -KernelAddressSANitizer(KASAN)是一ç§åŠ¨æ€å†…å˜å®‰å…¨é”™è¯¯æ£€æµ‹å·¥å…·ï¼Œä¸»è¦åŠŸèƒ½æ˜¯ -检查内å˜è¶Šç•Œè®¿é—®å’Œä½¿ç”¨å·²é‡Šæ”¾å†…å˜çš„问题。KASAN有三ç§æ¨¡å¼: +Kernel Address SANitizer(KASAN)是一ç§åŠ¨æ€å†…å˜å®‰å…¨é”™è¯¯æ£€æµ‹å·¥å…·ï¼Œä¸»è¦åŠŸèƒ½æ˜¯ +检查内å˜è¶Šç•Œè®¿é—®å’Œä½¿ç”¨å·²é‡Šæ”¾å†…å˜çš„问题。 -1. 通用KASAN（与用户空间的ASan类似） -2. åŸºäºŽè½¯ä»¶æ ‡ç¾çš„KASAN（与用户空间的HWASan类似） -3. åŸºäºŽç¡¬ä»¶æ ‡ç¾çš„KASAN（基于硬件内å˜æ ‡ç¾ï¼‰ +KASAN有三ç§æ¨¡å¼: -由于通用KASAN的内å˜å¼€é”€è¾ƒå¤§ï¼Œé€šç”¨KASAN主è¦ç”¨äºŽè°ƒè¯•ã€‚åŸºäºŽè½¯ä»¶æ ‡ç¾çš„KASAN -å¯ç”¨äºŽdogfoodæµ‹è¯•ï¼Œå› ä¸ºå®ƒå…·æœ‰è¾ƒä½Žçš„å†…å˜å¼€é”€ï¼Œå¹¶å…许将其用于实际工作é‡ã€‚ -åŸºäºŽç¡¬ä»¶æ ‡ç¾çš„KASAN具有较低的内å˜å’Œæ€§èƒ½å¼€é”€ï¼Œå› æ¤å¯ç”¨äºŽç”Ÿäº§ã€‚åŒæ—¶å¯ç”¨äºŽ -检测现场内å˜é—®é¢˜æˆ–作为安全缓解措施。 +1. 通用KASAN +2. åŸºäºŽè½¯ä»¶æ ‡ç¾çš„KASAN +3. åŸºäºŽç¡¬ä»¶æ ‡ç¾çš„KASAN -软件KASAN模å¼ï¼ˆ#1å’Œ#2）使用编译时工具在æ¯æ¬¡å†…å˜è®¿é—®ä¹‹å‰æ’入有效性检查， -å› æ¤éœ€è¦ä¸€ä¸ªæ”¯æŒå®ƒçš„编译器版本。 +用CONFIG_KASAN_GENERICå¯ç”¨çš„通用KASAN，是用于调试的模å¼ï¼Œç±»ä¼¼äºŽç”¨æˆ·ç©º +é—´çš„ASan。这ç§æ¨¡å¼åœ¨è®¸å¤šCPU架构上都被支æŒï¼Œä½†å®ƒæœ‰æ˜Žæ˜¾çš„性能和内å˜å¼€é”€ã€‚ -通用KASAN在GCCå’ŒClangå—支æŒã€‚GCC需è¦8.3.0或更高版本。任何å—支æŒçš„Clang -版本都是兼容的，但从Clang 11æ‰å¼€å§‹æ”¯æŒæ£€æµ‹å…¨å±€å˜é‡çš„越界访问。 +åŸºäºŽè½¯ä»¶æ ‡ç¾çš„KASAN或SW_TAGS KASAN，通过CONFIG_KASAN_SW_TAGSå¯ç”¨ï¼Œ +å¯ä»¥ç”¨äºŽè°ƒè¯•å’Œè‡ªæˆ‘测试，类似于用户空间HWASan。这ç§æ¨¡å¼åªæ”¯æŒarm64，但其 +适度的内å˜å¼€é”€å…许在内å˜å—é™çš„设备上用真实的工作负载进行测试。 -åŸºäºŽè½¯ä»¶æ ‡ç¾çš„KASAN模å¼ä»…在Clangä¸å—支æŒã€‚ +åŸºäºŽç¡¬ä»¶æ ‡ç¾çš„KASAN或HW_TAGS KASAN，用CONFIG_KASAN_HW_TAGSå¯ç”¨ï¼Œè¢« +用作现场内å˜é”™è¯¯æ£€æµ‹å™¨æˆ–作为安全缓解的模å¼ã€‚è¿™ç§æ¨¡å¼åªåœ¨æ”¯æŒMTE（内å˜æ ‡ç¾ +扩展）的arm64 CPU上工作，但它的内å˜å’Œæ€§èƒ½å¼€é”€å¾ˆä½Žï¼Œå› æ¤å¯ä»¥åœ¨ç”Ÿäº§ä¸ä½¿ç”¨ã€‚ -硬件KASAN模å¼ï¼ˆ#3）ä¾èµ–硬件æ¥æ‰§è¡Œæ£€æŸ¥ï¼Œä½†ä»éœ€è¦æ”¯æŒå†…å˜æ ‡ç¾æŒ‡ä»¤çš„编译器 -版本。GCC 10+å’ŒClang 11+支æŒæ¤æ¨¡å¼ã€‚ +关于æ¯ç§KASAN模å¼çš„内å˜å’Œæ€§èƒ½å½±å“的细节，请å‚è§ç›¸åº”çš„Kconfig选项的æ述。 -两ç§è½¯ä»¶KASAN模å¼éƒ½é€‚用于SLUBå’ŒSLAB内å˜åˆ†é…å™¨ï¼Œè€ŒåŸºäºŽç¡¬ä»¶æ ‡ç¾çš„KASANç›®å‰ -仅支æŒSLUB。 +通用模å¼å’ŒåŸºäºŽè½¯ä»¶æ ‡ç¾çš„模å¼é€šå¸¸è¢«ç§°ä¸ºè½¯ä»¶æ¨¡å¼ã€‚åŸºäºŽè½¯ä»¶æ ‡ç¾çš„模å¼å’ŒåŸºäºŽ +ç¡¬ä»¶æ ‡ç¾çš„模å¼è¢«ç§°ä¸ºåŸºäºŽæ ‡ç¾çš„模å¼ã€‚ -ç›®å‰x86_64ã€armã€arm64ã€xtensaã€s390ã€riscv架构支æŒé€šç”¨KASAN模å¼ï¼Œä»… -arm64架构支æŒåŸºäºŽæ ‡ç¾çš„KASAN模å¼ã€‚ +æ”¯æŒ +---- + +体系架构 +~~~~~~~~ + +在x86_64ã€armã€arm64ã€powerpcã€riscvã€s390å’Œxtensa上支æŒé€šç”¨KASAN， +è€ŒåŸºäºŽæ ‡ç¾çš„KASAN模å¼åªåœ¨arm64上支æŒã€‚ + +编译器 +~~~~~~ + +软件KASAN模å¼ä½¿ç”¨ç¼–译时工具在æ¯ä¸ªå†…å˜è®¿é—®ä¹‹å‰æ’å…¥æœ‰æ•ˆæ€§æ£€æŸ¥ï¼Œå› æ¤éœ€è¦ä¸€ä¸ª +æ供支æŒçš„ç¼–è¯‘å™¨ç‰ˆæœ¬ã€‚åŸºäºŽç¡¬ä»¶æ ‡ç¾çš„模å¼ä¾é 硬件æ¥æ‰§è¡Œè¿™äº›æ£€æŸ¥ï¼Œä½†ä»ç„¶éœ€è¦ +一个支æŒå†…å˜æ ‡ç¾æŒ‡ä»¤çš„编译器版本。 + +通用KASAN需è¦GCC 8.3.0ç‰ˆæœ¬æˆ–æ›´é«˜ç‰ˆæœ¬ï¼Œæˆ–è€…å†…æ ¸æ”¯æŒçš„任何Clang版本。 + +åŸºäºŽè½¯ä»¶æ ‡ç¾çš„KASAN需è¦GCC 11+æˆ–è€…å†…æ ¸æ”¯æŒçš„任何Clang版本。 + +åŸºäºŽç¡¬ä»¶æ ‡ç¾çš„KASAN需è¦GCC 10+或Clang 12+。 + +内å˜ç±»åž‹ +~~~~~~~~ + +通用KASAN支æŒåœ¨æ‰€æœ‰çš„slabã€page_allocã€vmapã€vmallocã€å †æ ˆå’Œå…¨å±€å†…å˜ +ä¸æŸ¥æ‰¾é”™è¯¯ã€‚ + +åŸºäºŽè½¯ä»¶æ ‡ç¾çš„KASAN支æŒslabã€page_allocã€vmallocå’Œå †æ ˆå†…å˜ã€‚ + +åŸºäºŽç¡¬ä»¶æ ‡ç¾çš„KASAN支æŒslabã€page_allocå’Œä¸å¯æ‰§è¡Œçš„vmalloc内å˜ã€‚ + +对于slab，两ç§è½¯ä»¶KASAN模å¼éƒ½æ”¯æŒSLUBå’ŒSLAB分é…å™¨ï¼Œè€ŒåŸºäºŽç¡¬ä»¶æ ‡ç¾çš„ +KASANåªæ”¯æŒSLUB。 用法 ---- @@ -53,7 +84,7 @@ arm64架构支æŒåŸºäºŽæ ‡ç¾çš„KASAN模å¼ã€‚ 对于软件模å¼ï¼Œè¿˜å¯ä»¥åœ¨ ``CONFIG_KASAN_OUTLINE`` å’Œ ``CONFIG_KASAN_INLINE`` 之间进行选择。outlineå’Œinline是编译器æ’桩类型。å‰è€…产生较å°çš„二进制文件， -而åŽè€…å¿«1.1-2å€ã€‚ +而åŽè€…å¿«2å€ã€‚ è¦å°†å—å½±å“çš„slab对象的allocå’Œfreeå †æ ˆè·Ÿè¸ªåŒ…å«åˆ°æŠ¥å‘Šä¸ï¼Œè¯·å¯ç”¨ ``CONFIG_STACKTRACE`` 。è¦åŒ…括å—å½±å“物ç†é¡µé¢çš„分é…å’Œé‡Šæ”¾å †æ ˆè·Ÿè¸ªçš„è¯ï¼Œ @@ -172,21 +203,29 @@ KASANå—通用 ``panic_on_warn`` 命令行å‚æ•°çš„å½±å“。å¯ç”¨è¯¥åŠŸèƒ½åŽï¼ 默认情况下，KASANåªä¸ºç¬¬ä¸€æ¬¡æ— 效内å˜è®¿é—®æ‰“å°é”™è¯¯æŠ¥å‘Šã€‚使用 ``kasan_multi_shot`` ， KASAN会针对æ¯ä¸ªæ— 效访问打å°æŠ¥å‘Šã€‚这有效地ç¦ç”¨äº†KASAN报告的 ``panic_on_warn`` 。 +å¦å¤–，独立于 ``panic_on_warn`` , ``kasan.fault=`` 引导å‚æ•°å¯ä»¥ç”¨æ¥æŽ§åˆ¶æ慌和报 +告行为: + +- ``kasan.fault=report`` 或 ``=panic`` 控制是åªæ‰“å°KASAN报告还是åŒæ—¶ä½¿å†…æ ¸ææ…Œ + (默认: ``report`` )。å³ä½¿å¯ç”¨äº† ``kasan_multi_shot`` ，也会å‘ç”Ÿå†…æ ¸æ慌。 + åŸºäºŽç¡¬ä»¶æ ‡ç¾çš„KASAN模å¼ï¼ˆè¯·å‚阅下é¢æœ‰å…³å„ç§æ¨¡å¼çš„部分）旨在在生产ä¸ç”¨ä½œå®‰å…¨ç¼“解 -æŽªæ–½ã€‚å› æ¤ï¼Œå®ƒæ”¯æŒå…许ç¦ç”¨KASAN或控制其功能的引导å‚数。 +æŽªæ–½ã€‚å› æ¤ï¼Œå®ƒæ”¯æŒå…许ç¦ç”¨KASANæˆ–æŽ§åˆ¶å…¶åŠŸèƒ½çš„é™„åŠ å¼•å¯¼å‚数。 - ``kasan=off`` 或 ``=on`` 控制KASAN是å¦å¯ç”¨ (默认: ``on`` )。 -- ``kasan.mode=sync`` 或 ``=async`` 控制KASAN是å¦é…置为åŒæ¥æˆ–异æ¥æ‰§è¡Œæ¨¡å¼(默认: - ``sync`` )。åŒæ¥æ¨¡å¼ï¼šå½“æ ‡ç¾æ£€æŸ¥é”™è¯¯å‘生时，立å³æ£€æµ‹åˆ°é”™è¯¯è®¿é—®ã€‚异æ¥æ¨¡å¼ï¼š - å»¶è¿Ÿé”™è¯¯è®¿é—®æ£€æµ‹ã€‚å½“æ ‡ç¾æ£€æŸ¥é”™è¯¯å‘生时，信æ¯å˜å‚¨åœ¨ç¡¬ä»¶ä¸ï¼ˆåœ¨arm64çš„ +- ``kasan.mode=sync`` 〠``=async`` 或 ``=asymm`` 控制KASAN是å¦é…ç½® + 为åŒæ¥æˆ–异æ¥æ‰§è¡Œæ¨¡å¼(默认:``sync`` )。 + åŒæ¥æ¨¡å¼ï¼šå½“æ ‡ç¾æ£€æŸ¥é”™è¯¯å‘生时，立å³æ£€æµ‹åˆ°é”™è¯¯è®¿é—®ã€‚ + 异æ¥æ¨¡å¼ï¼šå»¶è¿Ÿé”™è¯¯è®¿é—®æ£€æµ‹ã€‚å½“æ ‡ç¾æ£€æŸ¥é”™è¯¯å‘生时，信æ¯å˜å‚¨åœ¨ç¡¬ä»¶ä¸ï¼ˆåœ¨arm64çš„ TFSR_EL1寄å˜å™¨ä¸ï¼‰ã€‚å†…æ ¸ä¼šå®šæœŸæ£€æŸ¥ç¡¬ä»¶ï¼Œå¹¶ä¸”ä»…åœ¨è¿™äº›æ£€æŸ¥æœŸé—´æŠ¥å‘Šæ ‡ç¾é”™è¯¯ã€‚ + éžå¯¹ç§°æ¨¡å¼ï¼šè¯»å–æ—¶åŒæ¥æ£€æµ‹ä¸è‰¯è®¿é—®ï¼Œå†™å…¥æ—¶å¼‚æ¥æ£€æµ‹ã€‚ + +- ``kasan.vmalloc=off`` 或 ``=on`` ç¦ç”¨æˆ–å¯ç”¨vmalloc分é…çš„æ ‡è®°ï¼ˆé»˜è®¤ï¼š``on`` ）。 - ``kasan.stacktrace=off`` 或 ``=on`` ç¦ç”¨æˆ–å¯ç”¨allocå’Œfreeå †æ ˆè·Ÿè¸ªæ”¶é›† (默认: ``on`` )。 -- ``kasan.fault=report`` 或 ``=panic`` 控制是åªæ‰“å°KASAN报告还是åŒæ—¶ä½¿å†…æ ¸ææ…Œ - (默认: ``report`` )。å³ä½¿å¯ç”¨äº† ``kasan_multi_shot`` ，也会å‘ç”Ÿå†…æ ¸æ慌。 实施细则 -------- @@ -244,7 +283,6 @@ KASAN会针对æ¯ä¸ªæ— 效访问打å°æŠ¥å‘Šã€‚这有效地ç¦ç”¨äº†KASAN报告ç åŸºäºŽè½¯ä»¶æ ‡ç¾çš„KASAN使用0xFF作为匹é…æ‰€æœ‰æŒ‡é’ˆæ ‡ç¾ï¼ˆä¸æ£€æŸ¥é€šè¿‡å¸¦æœ‰0xFFæŒ‡é’ˆæ ‡ç¾ çš„æŒ‡é’ˆè¿›è¡Œçš„è®¿é—®ï¼‰ã€‚å€¼0xFE当å‰ä¿ç•™ç”¨äºŽæ ‡è®°å·²é‡Šæ”¾çš„内å˜åŒºåŸŸã€‚ -åŸºäºŽè½¯ä»¶æ ‡ç¾çš„KASANç›®å‰ä»…支æŒå¯¹Slabå’Œpage_alloc内å˜è¿›è¡Œæ ‡è®°ã€‚ åŸºäºŽç¡¬ä»¶æ ‡ç¾çš„KASANæ¨¡å¼ ~~~~~~~~~~~~~~~~~~~~~~~ @@ -262,8 +300,6 @@ KASAN会针对æ¯ä¸ªæ— 效访问打å°æŠ¥å‘Šã€‚这有效地ç¦ç”¨äº†KASAN报告ç åŸºäºŽç¡¬ä»¶æ ‡ç¾çš„KASAN使用0xFF作为匹é…æ‰€æœ‰æŒ‡é’ˆæ ‡ç¾ï¼ˆä¸æ£€æŸ¥é€šè¿‡å¸¦æœ‰0xFFæŒ‡é’ˆæ ‡ç¾çš„ 指针进行的访问）。值0xFE当å‰ä¿ç•™ç”¨äºŽæ ‡è®°å·²é‡Šæ”¾çš„内å˜åŒºåŸŸã€‚ -åŸºäºŽç¡¬ä»¶æ ‡ç¾çš„KASANç›®å‰ä»…支æŒå¯¹Slabå’Œpage_alloc内å˜è¿›è¡Œæ ‡è®°ã€‚ - 如果硬件ä¸æ”¯æŒMTE（ARMv8.5之å‰ï¼‰ï¼Œåˆ™ä¸ä¼šå¯ç”¨åŸºäºŽç¡¬ä»¶æ ‡ç¾çš„KASAN。在这ç§æƒ…况下， 所有KASAN引导å‚数都将被忽略。 @@ -275,6 +311,8 @@ KASAN会针对æ¯ä¸ªæ— 效访问打å°æŠ¥å‘Šã€‚这有效地ç¦ç”¨äº†KASAN报告ç å½±åå†…å˜ -------- +本节的内容åªé€‚用于软件KASAN模å¼ã€‚ + å†…æ ¸å°†å†…å˜æ˜ 射到地å€ç©ºé—´çš„å‡ ä¸ªä¸åŒéƒ¨åˆ†ã€‚å†…æ ¸è™šæ‹Ÿåœ°å€çš„范围很大：没有足够的真实 内å˜æ¥æ”¯æŒå†…æ ¸å¯ä»¥è®¿é—®çš„æ¯ä¸ªåœ°å€çš„真实影ååŒºåŸŸã€‚å› æ¤ï¼ŒKASANåªä¸ºåœ°å€ç©ºé—´çš„æŸäº› éƒ¨åˆ†æ˜ å°„çœŸå®žçš„å½±å。 @@ -297,7 +335,7 @@ CONFIG_KASAN_VMALLOC ~~~~~~~~~~~~~~~~~~~~ 使用 ``CONFIG_KASAN_VMALLOC`` ，KASANå¯ä»¥ä»¥æ›´å¤§çš„内å˜ä½¿ç”¨ä¸ºä»£ä»·è¦†ç›–vmalloc -空间。目å‰ï¼Œè¿™åœ¨x86ã€riscvã€s390å’Œpowerpc上å—支æŒã€‚ +空间。目å‰ï¼Œè¿™åœ¨arm64ã€x86ã€riscvã€s390å’Œpowerpc上å—支æŒã€‚ 这通过连接到vmallocå’Œvmap并动æ€åˆ†é…真实的影å内å˜æ¥æ”¯æŒæ˜ 射。 @@ -349,10 +387,10 @@ KASAN连接到vmap基础架构以懒清ç†æœªä½¿ç”¨çš„å½±å内å˜ã€‚ ``kasan_disable_current()``/``kasan_enable_current()`` 部分注释这部分代ç 。 这也会ç¦ç”¨é€šè¿‡å‡½æ•°è°ƒç”¨å‘生的间接访问的报告。 -å¯¹äºŽåŸºäºŽæ ‡ç¾çš„KASAN模å¼ï¼ˆåŒ…括硬件模å¼ï¼‰ï¼Œè¦ç¦ç”¨è®¿é—®æ£€æŸ¥ï¼Œè¯·ä½¿ç”¨ -``kasan_reset_tag()`` 或 ``page_kasan_tag_reset()`` 。请注æ„，通过 -``page_kasan_tag_reset()`` 临时ç¦ç”¨è®¿é—®æ£€æŸ¥éœ€è¦é€šè¿‡ ``page_kasan_tag`` -/ ``page_kasan_tag_set`` ä¿å˜å’Œæ¢å¤æ¯é¡µKASANæ ‡ç¾ã€‚ +å¯¹äºŽåŸºäºŽæ ‡ç¾çš„KASAN模å¼ï¼Œè¦ç¦ç”¨è®¿é—®æ£€æŸ¥ï¼Œè¯·ä½¿ç”¨ ``kasan_reset_tag()`` 或 +``page_kasan_tag_reset()`` 。请注æ„，通过 ``page_kasan_tag_reset()`` +临时ç¦ç”¨è®¿é—®æ£€æŸ¥éœ€è¦é€šè¿‡ ``page_kasan_tag`` / ``page_kasan_tag_set`` ä¿ +å˜å’Œæ¢å¤æ¯é¡µKASANæ ‡ç¾ã€‚ 测试 ~~~~ @@ -381,11 +419,10 @@ KASAN连接到vmap基础架构以懒清ç†æœªä½¿ç”¨çš„å½±å内å˜ã€‚ 当由于缺少KASAN报告而导致测试失败时:: - # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:629 - Expected kasan_data->report_expected == kasan_data->report_found, but - kasan_data->report_expected == 1 - kasan_data->report_found == 0 - not ok 28 - kmalloc_double_kzfree + # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:974 + KASAN failure expected in "kfree_sensitive(ptr)", but none occurred + not ok 44 - kmalloc_double_kzfree + 最åŽæ‰“å°æ‰€æœ‰KASAN测试的累积状æ€ã€‚æˆåŠŸ:: diff --git a/Documentation/translations/zh_CN/dev-tools/sparse.rst b/Documentation/translations/zh_CN/dev-tools/sparse.rst index 556282437aad..0664c634bc4f 100644 --- a/Documentation/translations/zh_CN/dev-tools/sparse.rst +++ b/Documentation/translations/zh_CN/dev-tools/sparse.rst @@ -106,3 +106,5 @@ __releases - 指定的é”在函数进入时被æŒæœ‰ï¼Œä½†åœ¨é€€å‡ºæ—¶ä¸è¢«æŒ make çš„å¯é€‰å˜é‡ CHECKFLAGS å¯ä»¥ç”¨æ¥å‘ sparse å·¥å…·ä¼ é€’å‚数。编译系统会自 åŠ¨å‘ sparse å·¥å…·ä¼ é€’ -Wbitwise å‚数。 + +注æ„sparse定义了__CHECKER__预处ç†å™¨ç¬¦å·ã€‚
\ No newline at end of file diff --git a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst index b7a1d13da6c6..d6f2c65ed511 100644 --- a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst +++ b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst @@ -107,3 +107,28 @@ Documentation/dev-tools/kcov.rst æ˜¯èƒ½å¤Ÿæž„å»ºåœ¨å†…æ ¸ä¹‹ä¸ï¼Œç”¨äºŽåœ¨æ¯ä¸ 之åŽä½ 就能确ä¿è¿™äº›é”™è¯¯åœ¨æµ‹è¯•è¿‡ç¨‹ä¸éƒ½ä¸ä¼šå‘生了。 一些工具与KUnitå’Œkselftest集æˆï¼Œå¹¶ä¸”在检测到问题时会自动打æ–测试。 + +é™æ€åˆ†æžå·¥å…· +============ + +除了测试è¿è¡Œä¸çš„å†…æ ¸ï¼Œæˆ‘ä»¬è¿˜å¯ä»¥ä½¿ç”¨**é™æ€åˆ†æž**工具直接分æžå†…æ ¸çš„æºä»£ +ç （**在编译时**ï¼‰ã€‚å†…æ ¸ä¸å¸¸ç”¨çš„工具å…许人们检查整个æºä»£ç æ ‘æˆ–å…¶ä¸çš„特 +定文件。它们使得在开å‘过程ä¸æ›´å®¹æ˜“å‘现和修å¤é—®é¢˜ã€‚ + + Sparseå¯ä»¥é€šè¿‡æ‰§è¡Œç±»åž‹æ£€æŸ¥ã€é”检查ã€å€¼èŒƒå›´æ£€æŸ¥æ¥å¸®åŠ©æµ‹è¯•å†…æ ¸ï¼Œæ¤å¤–还 + å¯ä»¥åœ¨æ£€æŸ¥ä»£ç 时报告å„ç§é”™è¯¯å’Œè¦å‘Šã€‚关于如何使用它的细节，请å‚阅 + Documentation/translations/zh_CN/dev-tools/sparse.rst。 + + Smatch扩展了Sparse，并æ供了对编程逻辑错误的é¢å¤–检查，如开关è¯å¥ä¸ + 缺少æ–点，错误检查ä¸æœªä½¿ç”¨çš„返回值，忘记在错误路径的返回ä¸è®¾ç½®é”™è¯¯ä»£ + ç ç‰ã€‚Smatch也有针对更严é‡é—®é¢˜çš„测试，如整数溢出ã€ç©ºæŒ‡é’ˆè§£é™¤å¼•ç”¨å’Œå†… + å˜æ³„æ¼ã€‚è§é¡¹ç›®é¡µé¢http://smatch.sourceforge.net/。 + + Coccinelle是我们å¯ä»¥ä½¿ç”¨çš„å¦ä¸€ä¸ªé™æ€åˆ†æžå™¨ã€‚Coccinelleç»å¸¸è¢«ç”¨æ¥ + 帮助æºä»£ç çš„é‡æž„和并行演化，但它也å¯ä»¥å¸®åŠ©é¿å…常è§ä»£ç 模å¼ä¸å‡ºçŽ°çš„æŸ + 些错误。å¯ç”¨çš„测试类型包括API测试ã€å†…æ ¸è¿ä»£å™¨çš„æ£ç¡®ä½¿ç”¨æµ‹è¯•ã€è‡ªç”±æ“ + 作的åˆç†æ€§æ£€æŸ¥ã€é”定行为的分æžï¼Œä»¥åŠå·²çŸ¥çš„有助于ä¿æŒå†…æ ¸ä½¿ç”¨ä¸€è‡´æ€§çš„ + 进一æ¥æµ‹è¯•ã€‚详情请è§Documentation/dev-tools/coccinelle.rst。 + + ä¸è¿‡è¦æ³¨æ„的是，é™æ€åˆ†æžå·¥å…·å˜åœ¨**å‡é˜³æ€§**的问题。在试图修å¤é”™è¯¯å’Œè¦ + 告之å‰ï¼Œéœ€è¦ä»”细评估它们。 diff --git a/Documentation/translations/zh_CN/devicetree/index.rst b/Documentation/translations/zh_CN/devicetree/index.rst index 23d0b6fccd58..3fc355fe0037 100644 --- a/Documentation/translations/zh_CN/devicetree/index.rst +++ b/Documentation/translations/zh_CN/devicetree/index.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 .. include:: ../disclaimer-zh_CN.rst -:Original: Documentation/Devicetree/index.rst +:Original: Documentation/devicetree/index.rst :翻译: diff --git a/Documentation/translations/zh_CN/devicetree/of_unittest.rst b/Documentation/translations/zh_CN/devicetree/of_unittest.rst index abd94e771ef8..11eb08ca8866 100644 --- a/Documentation/translations/zh_CN/devicetree/of_unittest.rst +++ b/Documentation/translations/zh_CN/devicetree/of_unittest.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 .. include:: ../disclaimer-zh_CN.rst -:Original: Documentation/Devicetree/of_unittest.rst +:Original: Documentation/devicetree/of_unittest.rst :翻译: diff --git a/Documentation/translations/zh_CN/devicetree/usage-model.rst b/Documentation/translations/zh_CN/devicetree/usage-model.rst index accdc33475a0..c6aee82c7e6e 100644 --- a/Documentation/translations/zh_CN/devicetree/usage-model.rst +++ b/Documentation/translations/zh_CN/devicetree/usage-model.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 .. include:: ../disclaimer-zh_CN.rst -:Original: Documentation/Devicetree/usage-model.rst +:Original: Documentation/devicetree/usage-model.rst :翻译: diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst index 82ec84470c0b..ccfb9b8329c2 100644 --- a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst +++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst @@ -14,7 +14,7 @@ Linuxå†…æ ¸æºæ–‡ä»¶å¯ä»¥åŒ…å«kernel-docæ ¼å¼çš„ç»“æž„åŒ–æ–‡æ¡£æ³¨é‡Šï¼Œç”¨ä» å®žé™…æœ‰ç€æ˜Žæ˜¾çš„ä¸åŒã€‚å†…æ ¸æºåŒ…å«æˆåƒä¸Šä¸‡ä¸ªkernel-doc注释。请åšæŒéµå¾ª æ¤å¤„æè¿°çš„é£Žæ ¼ã€‚ -.. note:: kernel-docæ— æ³•åŒ…å«Rust代ç ：请å‚考 Documentation/rust/docs.rst 。 +.. note:: kernel-docæ— æ³•åŒ…å«Rust代ç ：请å‚考 Documentation/rust/general-information.rst 。 从注释ä¸æå–kernel-doc结构，并从ä¸ç”Ÿæˆé€‚当的 `Sphinx C 域`_ 函数和带有锚点的 类型æ述。这些注释将被过滤以生æˆç‰¹æ®Škernel-doc高亮和交å‰å¼•ç”¨ã€‚详è§ä¸‹æ–‡ã€‚ diff --git a/Documentation/translations/zh_CN/iio/iio_configfs.rst b/Documentation/translations/zh_CN/iio/iio_configfs.rst index d5460e951804..eccaf1c644b4 100644 --- a/Documentation/translations/zh_CN/iio/iio_configfs.rst +++ b/Documentation/translations/zh_CN/iio/iio_configfs.rst @@ -37,10 +37,10 @@ configfsè½»æ¾é…置的对象（例如：设备，触å‘器）。 3. 软件触å‘器 ============= -IIO默认configfs组之一是“触å‘器â€ç»„。 挂载configfsåŽå¯ä»¥è‡ªåŠ¨è®¿é—®å®ƒï¼Œå¹¶ä¸”å¯ +IIO默认configfs组之一是“触å‘器â€ç»„。挂载configfsåŽå¯ä»¥è‡ªåŠ¨è®¿é—®å®ƒï¼Œå¹¶ä¸”å¯ ä»¥åœ¨/config/iio/triggers下找到。 -IIO软件触å‘器为创建多ç§è§¦å‘器类型æ供了支æŒã€‚ 通常在include/linux/iio +IIO软件触å‘器为创建多ç§è§¦å‘器类型æ供了支æŒã€‚通常在include/linux/iio /sw_trigger.h：ä¸çš„接å£ä¸‹å°†æ–°çš„触å‘器类型实现为å•ç‹¬çš„å†…æ ¸æ¨¡å—： :: @@ -76,10 +76,10 @@ IIO软件触å‘器为创建多ç§è§¦å‘器类型æ供了支æŒã€‚ 通常在incl .ops = &iio_trig_sample_ops, }; -module_iio_sw_trigger_driver(iio_trig_sample); + module_iio_sw_trigger_driver(iio_trig_sample); -æ¯ç§è§¦å‘器类型在/config/iio/triggers下都有其自己的目录。 åŠ è½½iio-trig-sample -模å—将创建“ trig-sampleâ€è§¦å‘器类型目录/config/iio/triggers/trig-sample. +æ¯ç§è§¦å‘器类型在/config/iio/triggersä¸‹éƒ½æœ‰å…¶è‡ªå·±çš„ç›®å½•ã€‚åŠ è½½iio-trig-sample +模å—将创建“trig-sampleâ€è§¦å‘器类型目录/config/iio/triggers/trig-sample. 我们支æŒä»¥ä¸‹ä¸æ–æºï¼ˆè§¦å‘器类型） @@ -102,3 +102,5 @@ module_iio_sw_trigger_driver(iio_trig_sample); ---------------------------- "hrtimerâ€è§¦å‘器类型没有æ¥è‡ª/config dir的任何å¯é…置属性。 +它确实引入了触å‘目录的sampling_frequency属性。 +该属性以Hz为å•ä½è®¾ç½®è½®è¯¢é¢‘率，精度为mHz。
\ No newline at end of file diff --git a/Documentation/translations/zh_CN/kernel-hacking/hacking.rst b/Documentation/translations/zh_CN/kernel-hacking/hacking.rst index f2bc154c5bcc..9112949b993c 100644 --- a/Documentation/translations/zh_CN/kernel-hacking/hacking.rst +++ b/Documentation/translations/zh_CN/kernel-hacking/hacking.rst @@ -81,7 +81,7 @@ 过硬件ä¸æ–）的“软件ä¸æ–â€å°†è¿è¡Œï¼ˆ ``kernel/softirq.c`` ）。 æ¤å¤„完æˆäº†è®¸å¤šçœŸæ£çš„ä¸æ–处ç†å·¥ä½œã€‚在å‘SMP过渡的早期，åªæœ‰â€œbottom halvesä¸‹åŠ -部â€ï¼ˆBHsï¼‰æœºåˆ¶ï¼Œæ— æ³•åˆ©ç”¨å¤šä¸ªCPU的优势。在从那些一团糟的就电脑切æ¢è¿‡æ¥åŽä¸ä¹…， +部â€ï¼ˆBHsï¼‰æœºåˆ¶ï¼Œæ— æ³•åˆ©ç”¨å¤šä¸ªCPU的优势。在从那些一团糟的旧电脑切æ¢è¿‡æ¥åŽä¸ä¹…， 我们放弃了这个é™åˆ¶ï¼Œè½¬è€Œä½¿ç”¨â€œè½¯ä¸æ–â€ã€‚ ``include/linux/interrupt.h`` 列出了ä¸åŒçš„软ä¸æ–。定时器软ä¸æ–是一个éžå¸¸é‡è¦ @@ -95,8 +95,7 @@ .. warning:: - “taskletâ€è¿™ä¸ªåå—是误导性的：它们与“任务â€æ— 关，å¯èƒ½æ›´å¤šä¸Žå½“æ—¶ - 阿列克谢·库兹涅ä½å¤«äº«ç”¨çš„糟糕ä¼ç‰¹åŠ 有关。 + “taskletâ€è¿™ä¸ªåå—是误导性的：它们与“任务â€æ— 关。 ä½ å¯ä»¥ä½¿ç”¨ :c:func:`in_softirq()` å®ï¼ˆ ``include/linux/preempt.h`` ）æ¥ç¡®è®¤ 是å¦å¤„于软ä¸æ–（或å任务）ä¸ã€‚ @@ -247,7 +246,7 @@ Provide mechanism not policyâ€ã€‚ 与 :c:func:`put_user()` å’Œ :c:func:`get_user()` ä¸åŒï¼Œå®ƒä»¬è¿”回未å¤åˆ¶çš„ æ•°æ®é‡ï¼ˆå³0ä»ç„¶æ„味ç€æˆåŠŸï¼‰ã€‚ -ã€æ˜¯çš„ï¼Œè¿™ä¸ªæ„šè ¢çš„æŽ¥å£çœŸå¿ƒè®©æˆ‘尴尬。ç«çˆ†çš„å£æ°´ä»—大概æ¯å¹´éƒ½ä¼šå‘生。 +ã€æ˜¯çš„，这个讨厌的接å£çœŸå¿ƒè®©æˆ‘尴尬。ç«çˆ†çš„å£æ°´ä»—大概æ¯å¹´éƒ½ä¼šå‘生。 —— Rusty Russell】 这些函数å¯ä»¥éšå¼ç¡çœ 。它ä¸åº”该在用户上下文之外调用（没有æ„义）ã€è°ƒç”¨æ—¶ç¦ç”¨ä¸æ– @@ -538,9 +537,9 @@ Documentation/core-api/symbol-namespaces.rst 。 Linus和其他开å‘人员有时会更改开å‘å†…æ ¸ä¸çš„函数或结构体åç§°ï¼›è¿™æ ·åšä¸ä»…是为了 让æ¯ä¸ªäººéƒ½ä¿æŒè¦æƒ•ï¼Œè¿˜åæ˜ äº†ä¸€ä¸ªé‡å¤§çš„更改（例如，ä¸èƒ½å†åœ¨æ‰“å¼€ä¸æ–的情况下 -调用，或者执行é¢å¤–的检查，或者ä¸æ‰§è¡Œä»¥å‰æ•èŽ·çš„检查）。通常这会附带一个linux -å†…æ ¸é‚®ä»¶åˆ—è¡¨ä¸ç›¸å½“å…¨é¢çš„注释；请æœç´¢å˜æ¡£ä»¥æŸ¥çœ‹ã€‚简å•åœ°å¯¹æ–‡ä»¶è¿›è¡Œå…¨å±€æ›¿æ¢é€šå¸¸ -会让事情å˜å¾— **更糟** 。 +调用，或者执行é¢å¤–的检查，或者ä¸æ‰§è¡Œä»¥å‰æ•èŽ·çš„检查）。通常这会附带å‘é€ä¸€ä¸ª +相当全é¢çš„æ³¨é‡Šåˆ°ç›¸åº”çš„å†…æ ¸é‚®ä»¶åˆ—è¡¨ä¸ï¼›è¯·æœç´¢å˜æ¡£ä»¥æŸ¥çœ‹ã€‚简å•åœ°å¯¹æ–‡ä»¶è¿›è¡Œå…¨å±€ +替æ¢é€šå¸¸åªä¼šè®©äº‹æƒ…å˜å¾— **更糟** 。 åˆå§‹åŒ–结构体æˆå‘˜ ------------------ @@ -610,7 +609,7 @@ C++ ä¸ºäº†è®©ä½ çš„ä¸œè¥¿æ›´æ£å¼ã€è¡¥ä¸æ›´æ•´æ´ï¼Œè¿˜æœ‰ä¸€äº›å·¥ä½œè¦åšï¼š -- æžæ¸…æ¥šä½ åœ¨è°çš„地界儿上干活。查看æºæ–‡ä»¶çš„顶部〠``MAINTAINERS`` æ–‡ä»¶ä»¥åŠ +- æžæ¸…æ¥šä½ ä¿®æ”¹çš„ä»£ç 属于è°ã€‚查看æºæ–‡ä»¶çš„æ ¹ç›®å½•ã€ ``MAINTAINERS`` æ–‡ä»¶ä»¥åŠ ``CREDITS`` 文件的最åŽä¸€éƒ¨åˆ†ã€‚ä½ åº”è¯¥å’Œæ¤äººå调，确ä¿ä½ 没有é‡æ–°å‘明轮å， 或者å°è¯•ä¸€äº›å·²ç»è¢«æ‹’ç»çš„东西。 @@ -629,12 +628,12 @@ C++ “obj-$(CONFIG_xxx) += xxx.oâ€ã€‚è¯æ³•è®°å½•åœ¨ Documentation/kbuild/makefiles.rst 。 -- å¦‚æžœä½ åšäº†ä¸€äº›æœ‰æ„义的事情，那å¯ä»¥æŠŠè‡ªå·±æ”¾è¿› ``CREDITS`` ，通常ä¸æ¢ä¸€ä¸ª - æ–‡ä»¶ï¼ˆæ— è®ºå¦‚ä½•ä½ çš„åå—都应该在æºæ–‡ä»¶çš„顶部）。维护人员æ„味ç€æ‚¨å¸Œæœ›åœ¨å¯¹ - å系统进行更改时得到询问，并了解缺陷；这æ„味ç€å¯¹æŸéƒ¨åˆ†ä»£ç åšå‡ºæ›´å¤šæ‰¿è¯ºã€‚ +- å¦‚æžœä½ è®¤ä¸ºè‡ªå·±åšäº†ä¸€äº›æœ‰æ„义的事情，å¯ä»¥æŠŠè‡ªå·±æ”¾è¿› ``CREDITS`` ï¼Œé€šå¸¸ä¸ + æ¢ä¸€ä¸ªæ–‡ä»¶ï¼ˆæ— è®ºå¦‚ä½•ä½ çš„åå—都应该在æºæ–‡ä»¶çš„顶部）。 ``MAINTAINERS`` + æ„味ç€æ‚¨å¸Œæœ›åœ¨å¯¹å系统进行更改时得到询问，并了解缺陷；这æ„味ç€å¯¹æŸéƒ¨åˆ† + 代ç åšå‡ºæ›´å¤šæ‰¿è¯ºã€‚ -- 最åŽï¼Œåˆ«å¿˜è®°åŽ»é˜…读 Documentation/process/submitting-patches.rst ， - 也许还有 Documentation/process/submitting-drivers.rst 。 +- 最åŽï¼Œåˆ«å¿˜è®°åŽ»é˜…读 Documentation/process/submitting-patches.rst。 Kernel 仙女棒 =============== diff --git a/Documentation/translations/zh_CN/locking/index.rst b/Documentation/translations/zh_CN/locking/index.rst index 700df8a2bb70..f0b10707668d 100644 --- a/Documentation/translations/zh_CN/locking/index.rst +++ b/Documentation/translations/zh_CN/locking/index.rst @@ -14,17 +14,18 @@ .. toctree:: :maxdepth: 1 + mutex-design + spinlocks + TODOList: * locktypes * lockdep-design * lockstat * locktorture - * mutex-design * rt-mutex-design * rt-mutex * seqlock - * spinlocks * ww-mutex-design * preempt-locking * pi-futex diff --git a/Documentation/translations/zh_CN/locking/mutex-design.rst b/Documentation/translations/zh_CN/locking/mutex-design.rst new file mode 100644 index 000000000000..6aad54372a6c --- /dev/null +++ b/Documentation/translations/zh_CN/locking/mutex-design.rst @@ -0,0 +1,145 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/locking/mutex-design.rst + +:翻译: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> + +================ +通用互斥é”å系统 +================ + +:åˆç¨¿: + + Ingo Molnar <mingo@redhat.com> + +:æ›´æ–°: + + Davidlohr Bueso <davidlohr@hp.com> + +什么是互斥é”？ +-------------- + +在Linuxå†…æ ¸ä¸ï¼Œäº’æ–¥é”（mutexï¼‰æŒ‡çš„æ˜¯ä¸€ä¸ªç‰¹æ®Šçš„åŠ é”原è¯ï¼Œå®ƒåœ¨å…±äº«å†…å˜ç³»ç»Ÿä¸Š +强制ä¿è¯åºåˆ—化，而ä¸ä»…仅是指在å¦æœ¯ç•Œæˆ–类似的ç†è®ºæ•™ç§‘书ä¸å‡ºçŽ°çš„通用术è¯â€œç›¸äº’ +排斥â€ã€‚互斥é”是一ç§ç¡çœ é”，它的行为类似于二进制信å·é‡ï¼ˆsemaphores），在 +2006年被引入时[1]，作为åŽè€…的替代å“。这ç§æ–°çš„æ•°æ®ç»“æž„æ供了许多优点，包括更 +简å•çš„接å£ï¼Œä»¥åŠåœ¨å½“时更少的代ç é‡ï¼ˆè§ç¼ºé™·ï¼‰ã€‚ + +[1] https://lwn.net/Articles/164802/ + +实现 +---- + +互斥é”由“struct mutexâ€è¡¨ç¤ºï¼Œåœ¨include/linux/mutex.hä¸å®šä¹‰ï¼Œå¹¶åœ¨ +kernel/locking/mutex.cä¸å®žçŽ°ã€‚这些é”使用一个原åå˜é‡ï¼ˆ->owner）æ¥è·Ÿè¸ª +它们生命周期内的é”状æ€ã€‚å—段owner实际上包å«çš„是指å‘当å‰é”所有者的 +`struct task_struct *` æŒ‡é’ˆï¼Œå› æ¤å¦‚æžœæ— äººæŒæœ‰é”，则它的值为空（NULL）。 +由于task_struct的指针至少按L1_CACHE_BYTES对é½ï¼Œä½Žä½ï¼ˆ3）被用æ¥å˜å‚¨é¢å¤– +的状æ€ï¼ˆä¾‹å¦‚，ç‰å¾…者列表éžç©ºï¼‰ã€‚在其最基本的形å¼ä¸ï¼Œå®ƒè¿˜åŒ…括一个ç‰å¾…队列和 +一个确ä¿å¯¹å…¶åºåˆ—化访问的自旋é”。æ¤å¤–，CONFIG_MUTEX_SPIN_ON_OWNER=yçš„ +系统使用一个自旋MCSé”（->osq，译注：MCS是两个人åçš„åˆå¹¶ç¼©å†™ï¼‰ï¼Œåœ¨ä¸‹æ–‡çš„ +（ii）ä¸æ述。 + +准备获得一把自旋é”时，有三ç§å¯èƒ½ç»è¿‡çš„路径，å–决于é”的状æ€ï¼š + +(i) 快速路径：试图通过调用cmpxchg()修改é”的所有者为当å‰ä»»åŠ¡ï¼Œä»¥æ¤åŽŸå化地 + 获å–é”。这åªåœ¨æ— 竞争的情况下有效（cmpxchg()检查值是å¦ä¸º0，所以3ä¸ªçŠ¶æ€ + 比特必须为0）。如果é”处在竞争状æ€ï¼Œä»£ç 进入下一个å¯èƒ½çš„路径。 + +(ii) ä¸é€Ÿè·¯å¾„：也就是ä¹è§‚自旋，当é”的所有者æ£åœ¨è¿è¡Œå¹¶ä¸”没有其它优先级更高的 + 任务（need_resched，需è¦é‡æ–°è°ƒåº¦ï¼‰å‡†å¤‡è¿è¡Œæ—¶ï¼Œå½“å‰ä»»åŠ¡è¯•å›¾è‡ªæ—‹æ¥èŽ·å¾— + é”。原ç†æ˜¯ï¼Œå¦‚æžœé”的所有者æ£åœ¨è¿è¡Œï¼Œå®ƒå¾ˆå¯èƒ½ä¸ä¹…就会释放é”。互斥é”自旋体 + 使用MCSé”æŽ’é˜Ÿï¼Œè¿™æ ·åªæœ‰ä¸€ä¸ªè‡ªæ—‹ä½“å¯ä»¥ç«žäº‰äº’æ–¥é”。 + + MCSé”（由Mellor-Crummeyå’ŒScottæ出）是一个简å•çš„自旋é”，它具有一些 + ç†æƒ³çš„特性，比如公平，以åŠæ¯ä¸ªCPU在试图获得é”时在一个本地å˜é‡ä¸Šè‡ªæ—‹ã€‚ + 它é¿å…了常è§çš„“检测-设置â€è‡ªæ—‹é”实现导致的（CPUæ ¸é—´ï¼‰ç¼“å˜è¡Œå›žå¼¹ + （cacheline bouncing）这ç§æ˜‚贵的开销。一个类MCSé”是为实现ç¡çœ é”çš„ + ä¹è§‚自旋而专门定制的。这ç§å®šåˆ¶MCSé”的一个é‡è¦ç‰¹æ€§æ˜¯ï¼Œå®ƒæœ‰ä¸€ä¸ªé¢å¤–的属性， + 当自旋体需è¦é‡æ–°è°ƒåº¦æ—¶ï¼Œå®ƒä»¬èƒ½å¤Ÿé€€å‡ºMCS自旋é”队列。这进一æ¥æœ‰åŠ©äºŽé¿å… + 以下场景：需è¦é‡æ–°è°ƒåº¦çš„MCS自旋体将继ç»è‡ªæ—‹ç‰å¾…自旋体所有者，å³å°†èŽ·å¾— + MCSé”æ—¶å´ç›´æŽ¥è¿›å…¥æ…¢é€Ÿè·¯å¾„。 + +(iii) 慢速路径：最åŽçš„手段，如果ä»ç„¶æ— 法获得é”ï¼Œè¯¥ä»»åŠ¡ä¼šè¢«æ·»åŠ åˆ°ç‰å¾…队列ä¸ï¼Œ + ä¼‘çœ ç›´åˆ°è¢«è§£é”路径唤醒。在通常情况下，它以TASK_UNINTERRUPTIBLEçŠ¶æ€ + 阻塞。 + +虽然从形å¼ä¸Šçœ‹ï¼Œå†…æ ¸äº’æ–¥é”是å¯ç¡çœ çš„é”，路径(ii)使它实际上æˆä¸ºæ··åˆç±»åž‹ã€‚通过 +简å•åœ°ä¸ä¸æ–一个任务并忙ç€ç‰å¾…å‡ ä¸ªå‘¨æœŸï¼Œè€Œä¸æ˜¯ç«‹å³ç¡çœ ，这ç§é”å·²ç»è¢«è®¤ä¸ºæ˜¾è‘— +改善一些工作负载的性能。注æ„，这ç§æŠ€æœ¯ä¹Ÿè¢«ç”¨äºŽè¯»å†™ä¿¡å·é‡ï¼ˆrw-semaphores）。 + +è¯ä¹‰ +---- + +互斥é”å系统检查并强制执行以下规则: + + - æ¯æ¬¡åªæœ‰ä¸€ä¸ªä»»åŠ¡å¯ä»¥æŒæœ‰è¯¥äº’æ–¥é”。 + - åªæœ‰é”的所有者å¯ä»¥è§£é”该互斥é”。 + - ä¸å…许多次解é”。 + - ä¸å…è®¸é€’å½’åŠ é”/解é”。 + - 互斥é”åªèƒ½é€šè¿‡API进行åˆå§‹åŒ–（è§ä¸‹æ–‡ï¼‰ã€‚ + - 一个任务ä¸èƒ½åœ¨æŒæœ‰äº’æ–¥é”的情况下退出。 + - æŒæœ‰é”的内å˜åŒºåŸŸä¸å¾—被释放。 + - 被æŒæœ‰çš„é”ä¸èƒ½è¢«é‡æ–°åˆå§‹åŒ–。 + - 互斥é”ä¸èƒ½ç”¨äºŽç¡¬ä»¶æˆ–软件ä¸æ–上下文，如å°ä»»åŠ¡ï¼ˆtasklet）和定时器。 + +当CONFIG DEBUG_MUTEXES被å¯ç”¨æ—¶ï¼Œè¿™äº›è¯ä¹‰å°†è¢«å®Œå…¨å¼ºåˆ¶æ‰§è¡Œã€‚æ¤å¤–ï¼Œäº’æ–¥é” +调试代ç 还实现了一些其它特性，使é”的调试更容易ã€æ›´å¿«é€Ÿï¼š + + - 当打å°åˆ°è°ƒè¯•è¾“出时，总是使用互斥é”的符å·å称。 + - åŠ é”点跟踪，函数å符å·åŒ–查找，系统æŒæœ‰çš„全部é”的列表，打å°å‡ºå®ƒä»¬ã€‚ + - 所有者跟踪。 + - 检测自我递归的é”并打å°æ‰€æœ‰ç›¸å…³ä¿¡æ¯ã€‚ + - 检测多任务环形ä¾èµ–æ»é”，并打å°æ‰€æœ‰å—å½±å“çš„é”和任务（并且åªé™äºŽè¿™äº›ä»»åŠ¡ï¼‰ã€‚ + + +æŽ¥å£ +---- +é™æ€å®šä¹‰äº’æ–¥é”:: + + DEFINE_MUTEX(name); + +动æ€åˆå§‹åŒ–互斥é”:: + + mutex_init(mutex); + +以ä¸å¯ä¸æ–æ–¹å¼ï¼ˆuninterruptible）获å–互斥é”:: + + void mutex_lock(struct mutex *lock); + void mutex_lock_nested(struct mutex *lock, unsigned int subclass); + int mutex_trylock(struct mutex *lock); + +以å¯ä¸æ–æ–¹å¼ï¼ˆinterruptible）获å–互斥é”:: + + int mutex_lock_interruptible_nested(struct mutex *lock, + unsigned int subclass); + int mutex_lock_interruptible(struct mutex *lock); + +当原åå˜é‡å‡ä¸º0时，以å¯ä¸æ–æ–¹å¼ï¼ˆinterruptible）获å–互斥é”:: + + int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock); + +释放互斥é”:: + + void mutex_unlock(struct mutex *lock); + +检测是å¦å·²ç»èŽ·å–互斥é”:: + + int mutex_is_locked(struct mutex *lock); + +缺陷 +---- + +与它最åˆçš„设计和目的ä¸åŒï¼Œ'struct mutex' æ˜¯å†…æ ¸ä¸æœ€å¤§çš„é”之一。例如：在 +x86-64上它是32å—节，而 'struct semaphore' 是24å—节，rw_semaphore是 +40å—节。更大的结构体大å°æ„味ç€æ›´å¤šçš„CPU缓å˜å’Œå†…å˜å 用。 + + +ä½•æ—¶ä½¿ç”¨äº’æ–¥é” +-------------- + +总是优先选择互斥é”而ä¸æ˜¯ä»»ä½•å…¶å®ƒé”原è¯ï¼Œé™¤éžäº’æ–¥é”çš„ä¸¥æ ¼è¯ä¹‰ä¸åˆé€‚，和/或临界区 +阻æ¢é”被共享。 diff --git a/Documentation/translations/zh_CN/loongarch/introduction.rst b/Documentation/translations/zh_CN/loongarch/introduction.rst index e31a1a928c48..11686ee0caeb 100644 --- a/Documentation/translations/zh_CN/loongarch/introduction.rst +++ b/Documentation/translations/zh_CN/loongarch/introduction.rst @@ -46,10 +46,11 @@ LA64ä¸æ¯ä¸ªå¯„å˜å™¨ä¸º64ä½å®½ã€‚ ``$r0`` 的内容总是固定为0，而其ä ``$r23``-``$r31`` ``$s0``-``$s8`` é™æ€å¯„å˜å™¨ 是 ================= =============== =================== ========== -注æ„：``$r21``寄å˜å™¨åœ¨ELF psABIä¸ä¿ç•™æœªä½¿ç”¨ï¼Œä½†æ˜¯åœ¨Linuxå†…æ ¸ç”¨äºŽä¿å˜æ¯CPU -å˜é‡åŸºåœ°å€ã€‚该寄å˜å™¨æ²¡æœ‰ABI命å，ä¸è¿‡åœ¨å†…æ ¸ä¸ç§°ä¸º``$u0``。在一些é—留代ç -ä¸æœ‰æ—¶å¯èƒ½è§åˆ°``$v0``å’Œ``$v1``，它们是``$a0``å’Œ``$a1``的别å，属于已ç»åºŸå¼ƒ -的用法。 +.. note:: + 注æ„： ``$r21`` 寄å˜å™¨åœ¨ELF psABIä¸ä¿ç•™æœªä½¿ç”¨ï¼Œä½†æ˜¯åœ¨Linuxå†…æ ¸ç”¨äºŽä¿ + å˜æ¯CPUå˜é‡åŸºåœ°å€ã€‚该寄å˜å™¨æ²¡æœ‰ABI命å，ä¸è¿‡åœ¨å†…æ ¸ä¸ç§°ä¸º ``$u0`` 。在 + 一些é—留代ç ä¸æœ‰æ—¶å¯èƒ½è§åˆ° ``$v0`` å’Œ ``$v1`` ，它们是 ``$a0`` å’Œ + ``$a1`` 的别å，属于已ç»åºŸå¼ƒçš„用法。 浮点寄å˜å™¨ ---------- @@ -68,8 +69,9 @@ LA64ä¸æ¯ä¸ªå¯„å˜å™¨ä¸º64ä½å®½ã€‚ ``$r0`` 的内容总是固定为0，而其ä ``$f24``-``$f31`` ``$fs0``-``$fs7`` é™æ€å¯„å˜å™¨ 是 ================= ================== =================== ========== -注æ„：在一些é—留代ç ä¸æœ‰æ—¶å¯èƒ½è§åˆ° ``$v0`` å’Œ ``$v1`` ，它们是 ``$a0`` -å’Œ ``$a1`` 的别å，属于已ç»åºŸå¼ƒçš„用法。 +.. note:: + 注æ„：在一些é—留代ç ä¸æœ‰æ—¶å¯èƒ½è§åˆ° ``$v0`` å’Œ ``$v1`` ，它们是 + ``$a0`` å’Œ ``$a1`` 的别å，属于已ç»åºŸå¼ƒçš„用法。 å‘é‡å¯„å˜å™¨ diff --git a/Documentation/translations/zh_CN/loongarch/irq-chip-model.rst b/Documentation/translations/zh_CN/loongarch/irq-chip-model.rst index 2a4c3ad38be4..fb5d23b49ed5 100644 --- a/Documentation/translations/zh_CN/loongarch/irq-chip-model.rst +++ b/Documentation/translations/zh_CN/loongarch/irq-chip-model.rst @@ -147,9 +147,11 @@ PCH-LPC:: https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-7A1000-usermanual-2.00-EN.pdf (英文版) -注：CPUINTCå³ã€Šé¾™èŠ¯æž¶æž„å‚考手册å·ä¸€ã€‹ç¬¬7.4节所æè¿°çš„CSR.ECFG/CSR.ESTAT寄å˜å™¨åŠå…¶ä¸æ– -控制逻辑；LIOINTCå³ã€Šé¾™èŠ¯3A5000处ç†å™¨ä½¿ç”¨æ‰‹å†Œã€‹ç¬¬11.1节所æè¿°çš„â€œä¼ ç»ŸI/Oä¸æ–â€ï¼›EIOINTC -å³ã€Šé¾™èŠ¯3A5000处ç†å™¨ä½¿ç”¨æ‰‹å†Œã€‹ç¬¬11.2节所æ述的“扩展I/Oä¸æ–â€ï¼›HTVECINTCå³ã€Šé¾™èŠ¯3A5000 -处ç†å™¨ä½¿ç”¨æ‰‹å†Œã€‹ç¬¬14.3节所æ述的“HyperTransportä¸æ–â€ï¼›PCH-PIC/PCH-MSIå³ã€Šé¾™èŠ¯7A1000æ¡¥ -片用户手册》第5ç« æ‰€æ述的“ä¸æ–控制器â€ï¼›PCH-LPCå³ã€Šé¾™èŠ¯7A1000桥片用户手册》第24.3节所 -æ述的“LPCä¸æ–â€ã€‚ +.. note:: + - CPUINTC：å³ã€Šé¾™èŠ¯æž¶æž„å‚考手册å·ä¸€ã€‹ç¬¬7.4节所æè¿°çš„CSR.ECFG/CSR.ESTAT寄å˜å™¨åŠå…¶ + ä¸æ–控制逻辑； + - LIOINTC：å³ã€Šé¾™èŠ¯3A5000处ç†å™¨ä½¿ç”¨æ‰‹å†Œã€‹ç¬¬11.1节所æè¿°çš„â€œä¼ ç»ŸI/Oä¸æ–â€ï¼› + - EIOINTC：å³ã€Šé¾™èŠ¯3A5000处ç†å™¨ä½¿ç”¨æ‰‹å†Œã€‹ç¬¬11.2节所æ述的“扩展I/Oä¸æ–â€ï¼› + - HTVECINTC：å³ã€Šé¾™èŠ¯3A5000处ç†å™¨ä½¿ç”¨æ‰‹å†Œã€‹ç¬¬14.3节所æ述的“HyperTransportä¸æ–â€ï¼› + - PCH-PIC/PCH-MSI：å³ã€Šé¾™èŠ¯7A1000桥片用户手册》第5ç« æ‰€æ述的“ä¸æ–控制器â€ï¼› + - PCH-LPC：å³ã€Šé¾™èŠ¯7A1000桥片用户手册》第24.3节所æ述的“LPCä¸æ–â€ã€‚ diff --git a/Documentation/translations/zh_CN/process/5.Posting.rst b/Documentation/translations/zh_CN/process/5.Posting.rst index 4ee7de13f373..6a469e1c7deb 100644 --- a/Documentation/translations/zh_CN/process/5.Posting.rst +++ b/Documentation/translations/zh_CN/process/5.Posting.rst @@ -19,8 +19,7 @@ å†…æ ¸å¼€å‘社区已ç»å‘展出一套用于å‘布补ä¸çš„约定和过程；éµå¾ªè¿™äº›çº¦å®šå’Œè¿‡ç¨‹å°†ä½¿ å‚与其ä¸çš„æ¯ä¸ªäººçš„ç”Ÿæ´»æ›´åŠ è½»æ¾ã€‚本文档试图æè¿°è¿™äº›çº¦å®šçš„éƒ¨åˆ†ç»†èŠ‚ï¼›æ›´å¤šä¿¡æ¯ ä¹Ÿå¯åœ¨ä»¥ä¸‹æ–‡æ¡£ä¸æ‰¾åˆ° -:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`， -:ref:`Documentation/translations/zh_CN/process/submitting-drivers.rst <cn_submittingdrivers>` +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` å’Œ :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>`。 ä½•æ—¶å¯„é€ diff --git a/Documentation/translations/zh_CN/process/8.Conclusion.rst b/Documentation/translations/zh_CN/process/8.Conclusion.rst index 4707f0101964..643b88af97bb 100644 --- a/Documentation/translations/zh_CN/process/8.Conclusion.rst +++ b/Documentation/translations/zh_CN/process/8.Conclusion.rst @@ -19,7 +19,6 @@ :ref:`Documentation/translations/zh_CN/process/howto.rst <cn_process_howto>` 文件是一个é‡è¦çš„起点； :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` -å’Œ :ref:`Documentation/translations/zh_CN/process/submitting-drivers.rst <cn_submittingdrivers>` ä¹Ÿæ˜¯æ‰€æœ‰å†…æ ¸å¼€å‘äººå‘˜éƒ½åº”è¯¥é˜…è¯»çš„å†…å®¹ã€‚è®¸å¤šå†…éƒ¨å†…æ ¸API都是使用kerneldoc机制 记录的；“make htmldocsâ€æˆ–“make pdfdocsâ€å¯ç”¨äºŽä»¥HTML或PDFæ ¼å¼ç”Ÿæˆè¿™äº›æ–‡æ¡£ （尽管æŸäº›å‘行版æ供的tex版本会é‡åˆ°å†…部é™åˆ¶ï¼Œæ— 法æ£ç¡®å¤„ç†æ–‡æ¡£ï¼‰ã€‚ diff --git a/Documentation/translations/zh_CN/process/howto.rst b/Documentation/translations/zh_CN/process/howto.rst index 1334cdb32a3c..1455190dc087 100644 --- a/Documentation/translations/zh_CN/process/howto.rst +++ b/Documentation/translations/zh_CN/process/howto.rst @@ -96,7 +96,6 @@ Linuxå†…æ ¸ä»£ç ä¸åŒ…å«æœ‰å¤§é‡çš„文档。这些文档对于å¦ä¹ 如何与 的代ç 。 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` - :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` 这两份文档明确æ述如何创建和å‘é€è¡¥ä¸ï¼Œå…¶ä¸åŒ…括（但ä¸ä»…é™äºŽ)： - 邮件内容 diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst index 39e9c88fbaa6..a683dbea0c83 100644 --- a/Documentation/translations/zh_CN/process/index.rst +++ b/Documentation/translations/zh_CN/process/index.rst @@ -40,7 +40,6 @@ .. toctree:: :maxdepth: 1 - submitting-drivers submit-checklist stable-api-nonsense stable-kernel-rules diff --git a/Documentation/translations/zh_CN/process/submitting-drivers.rst b/Documentation/translations/zh_CN/process/submitting-drivers.rst deleted file mode 100644 index 98341e7cd812..000000000000 --- a/Documentation/translations/zh_CN/process/submitting-drivers.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. _cn_submittingdrivers: - -.. include:: ../disclaimer-zh_CN.rst - -:Original: :ref:`Documentation/process/submitting-drivers.rst - <submittingdrivers>` - -如果想评论或更新本文的内容，请直接è”ç³»åŽŸæ–‡æ¡£çš„ç»´æŠ¤è€…ã€‚å¦‚æžœä½ ä½¿ç”¨è‹±æ–‡ -交æµæœ‰å›°éš¾çš„è¯ï¼Œä¹Ÿå¯ä»¥å‘ä¸æ–‡ç‰ˆç»´æŠ¤è€…求助。如果本翻译更新ä¸åŠæ—¶æˆ–者翻 -译å˜åœ¨é—®é¢˜ï¼Œè¯·è”ç³»ä¸æ–‡ç‰ˆç»´æŠ¤è€…:: - - ä¸æ–‡ç‰ˆç»´æŠ¤è€…： æŽé˜³ Li Yang <leoyang.li@nxp.com> - ä¸æ–‡ç‰ˆç¿»è¯‘者： æŽé˜³ Li Yang <leoyang.li@nxp.com> - ä¸æ–‡ç‰ˆæ ¡è¯‘者： é™ˆç¦ Maggie Chen <chenqi@beyondsoft.com> - çŽ‹èª Wang Cong <xiyou.wangcong@gmail.com> - å¼ å· Zhang Wei <wezhang@outlook.com> - -å¦‚ä½•å‘ Linux å†…æ ¸æäº¤é©±åŠ¨ç¨‹åº -============================= - -这篇文档将会解释如何å‘ä¸åŒçš„å†…æ ¸æºç æ ‘æ交设备驱动程åºã€‚请注æ„ï¼Œå¦‚æžœä½ æ„Ÿ -兴趣的是显å¡é©±åŠ¨ç¨‹åºï¼Œä½ 也许应该访问 XFree86 项目(https://www.xfree86.org/) -å’Œï¼æˆ– X.org 项目 (https://x.org)。 - -å¦è¯·å‚阅 Documentation/translations/zh_CN/process/submitting-patches.rst 文档。 - - -分é…è®¾å¤‡å· ----------- - -å—设备和å—符设备的主设备å·ä¸Žä»Žè®¾å¤‡å·æ˜¯ç”± Linux 命åç¼–å·åˆ†é…æƒå¨ LANANA（ -现在是 Torben Mathiasen）负责分é…。申请的网å€æ˜¯ https://www.lanana.org/。 -å³ä½¿ä¸å‡†å¤‡æ交到主æµå†…æ ¸çš„è®¾å¤‡é©±åŠ¨ä¹Ÿéœ€è¦åœ¨è¿™é‡Œåˆ†é…设备å·ã€‚有关详细信æ¯ï¼Œ -请å‚阅 Documentation/admin-guide/devices.rst。 - -å¦‚æžœä½ ä½¿ç”¨çš„ä¸æ˜¯å·²ç»åˆ†é…的设备å·ï¼Œé‚£ä¹ˆå½“ä½ æ交设备驱动的时候，它将会被强 -制分é…一个新的设备å·ï¼Œå³ä¾¿è¿™ä¸ªè®¾å¤‡å·å’Œä½ 之å‰å‘给客户的截然ä¸åŒã€‚ - -设备驱动的æ交对象 ------------------- - -Linux 2.0: - æ¤å†…æ ¸æºç æ ‘ä¸æŽ¥å—新的驱动程åºã€‚ - -Linux 2.2: - æ¤å†…æ ¸æºç æ ‘ä¸æŽ¥å—新的驱动程åºã€‚ - -Linux 2.4: - 如果所属的代ç é¢†åŸŸåœ¨å†…æ ¸çš„ MAINTAINERS 文件ä¸åˆ—有一个总维护者， - 那么请将驱动程åºæ交给他。如果æ¤ç»´æŠ¤è€…æ²¡æœ‰å›žåº”æˆ–è€…ä½ æ‰¾ä¸åˆ°æ°å½“çš„ - 维护者，那么请è”ç³» Willy Tarreau <w@1wt.eu>。 - -Linux 2.6: - 除了éµå¾ªå’Œ 2.4 ç‰ˆå†…æ ¸åŒæ ·çš„è§„åˆ™å¤–ï¼Œä½ è¿˜éœ€è¦åœ¨ linux-kernel 邮件 - 列表上跟踪最新的 API å˜åŒ–ã€‚å‘ Linux 2.6 å†…æ ¸æ交驱动的顶级è”系人 - 是 Andrew Morton <akpm@linux-foundation.org>。 - -决定设备驱动能å¦è¢«æŽ¥å—çš„æ¡ä»¶ ----------------------------- - -许å¯ï¼š 代ç 必须使用 GNU 通用公开许å¯è¯ (GPL) æ交给 Linux，但是 - 我们并ä¸è¦æ±‚ GPL 是唯一的许å¯ã€‚ä½ æˆ–è®¸ä¼šå¸Œæœ›åŒæ—¶ä½¿ç”¨å¤šç§ - 许å¯è¯å‘布，如果希望驱动程åºå¯ä»¥è¢«å…¶ä»–å¼€æºç¤¾åŒºï¼ˆæ¯”如BSD） - 使用。请å‚考 include/linux/module.h 文件ä¸æ‰€åˆ—出的å¯è¢« - 接å—å…±å˜çš„许å¯ã€‚ - -版æƒï¼š 版æƒæ‰€æœ‰è€…å¿…é¡»åŒæ„使用 GPL 许å¯ã€‚最好æ交者和版æƒæ‰€æœ‰è€… - 是相åŒä¸ªäººæˆ–实体。å¦åˆ™ï¼Œå¿…需列出授æƒä½¿ç”¨ GPL 的版æƒæ‰€æœ‰ - 人或实体，以备验è¯ä¹‹éœ€ã€‚ - -接å£ï¼š å¦‚æžœä½ çš„é©±åŠ¨ç¨‹åºä½¿ç”¨çŽ°æˆçš„接å£å¹¶ä¸”和其他åŒç±»çš„驱动程åºè¡Œ - 为相似，而ä¸æ˜¯åŽ»å‘æ˜Žæ— è°“çš„æ–°æŽ¥å£ï¼Œé‚£ä¹ˆå®ƒå°†ä¼šæ›´å®¹æ˜“被接å—。 - å¦‚æžœä½ éœ€è¦ä¸€ä¸ª Linux å’Œ NT 的通用驱动接å£ï¼Œé‚£ä¹ˆè¯·åœ¨ç”¨ - 户空间实现它。 - -代ç ： 请使用 Documentation/process/coding-style.rst ä¸æ‰€æè¿°çš„ Linux 代ç 风 - æ ¼ã€‚å¦‚æžœä½ çš„æŸäº›ä»£ç 段（例如那些与 Windows 驱动程åºåŒ…å…± - 享的代ç 段）需è¦ä½¿ç”¨å…¶ä»–æ ¼å¼ï¼Œè€Œä½ å´åªå¸Œæœ›ç»´æŠ¤ä¸€ä»½ä»£ç ， - 那么请将它们很好地区分出æ¥ï¼Œå¹¶ä¸”æ³¨æ˜ŽåŽŸå› ã€‚ - -å¯ç§»æ¤æ€§ï¼š 请注æ„，指针并ä¸æ°¸è¿œæ˜¯ 32 ä½çš„，ä¸æ˜¯æ‰€æœ‰çš„è®¡ç®—æœºéƒ½ä½¿ç”¨å° - å°¾æ¨¡å¼ (little endian) å˜å‚¨æ•°æ®ï¼Œä¸æ˜¯æ‰€æœ‰çš„人都拥有浮点 - å•å…ƒï¼Œä¸è¦éšä¾¿åœ¨ä½ 的驱动程åºé‡ŒåµŒå…¥ x86 汇编指令。åªèƒ½åœ¨ - x86 上è¿è¡Œçš„驱动程åºä¸€èˆ¬æ˜¯ä¸å—æ¬¢è¿Žçš„ã€‚è™½ç„¶ä½ å¯èƒ½åªæœ‰ x86 - 硬件，很难测试驱动程åºåœ¨å…¶ä»–å¹³å°ä¸Šæ˜¯å¦å¯ç”¨ï¼Œä½†æ˜¯ç¡®ä¿ä»£ç - å¯ä»¥è¢«è½»æ¾åœ°ç§»æ¤å´æ˜¯å¾ˆç®€å•çš„。 - -清晰度： åšåˆ°æ‰€æœ‰äººéƒ½èƒ½ä¿®è¡¥è¿™ä¸ªé©±åŠ¨ç¨‹åºå°†ä¼šå¾ˆæœ‰å¥½å¤„ï¼Œå› ä¸ºè¿™æ ·ä½ å°† - 会直接收到修å¤çš„è¡¥ä¸è€Œä¸æ˜¯ bug æŠ¥å‘Šã€‚å¦‚æžœä½ æ交一个试图 - éšè—硬件工作机ç†çš„驱动程åºï¼Œé‚£ä¹ˆå®ƒå°†ä¼šè¢«æ‰”进废纸篓。 - -电æºç®¡ç†ï¼š å› ä¸º Linux æ£åœ¨è¢«å¾ˆå¤šç§»åŠ¨è®¾å¤‡å’Œæ¡Œé¢ç³»ç»Ÿä½¿ç”¨ï¼Œæ‰€ä»¥ä½ 的驱 - 动程åºä¹Ÿå¾ˆæœ‰å¯èƒ½è¢«ä½¿ç”¨åœ¨è¿™äº›è®¾å¤‡ä¸Šã€‚它应该支æŒæœ€åŸºæœ¬çš„电 - æºç®¡ç†ï¼Œå³åœ¨éœ€è¦çš„æƒ…å†µä¸‹å®žçŽ°ç³»ç»Ÿçº§ä¼‘çœ å’Œå”¤é†’è¦ç”¨åˆ°çš„ - .suspend å’Œ .resume å‡½æ•°ã€‚ä½ åº”è¯¥æ£€æŸ¥ä½ çš„é©±åŠ¨ç¨‹åºæ˜¯å¦èƒ½æ£ - 确地处ç†ä¼‘çœ ä¸Žå”¤é†’ï¼Œå¦‚æžœå®žåœ¨æ— æ³•ç¡®è®¤ï¼Œè¯·è‡³å°‘æŠŠ .suspend - 函数定义æˆè¿”回 -ENOSYSï¼ˆåŠŸèƒ½æœªå®žçŽ°ï¼‰é”™è¯¯ã€‚ä½ è¿˜åº”è¯¥å°è¯•ç¡® - ä¿ä½ 的驱动在什么都ä¸å¹²çš„情况下将耗电é™åˆ°æœ€ä½Žã€‚è¦èŽ·å¾—驱动 - 程åºæµ‹è¯•çš„指导，请å‚阅 - Documentation/power/drivers-testing.rst。有关驱动程åºç”µ - æºç®¡ç†é—®é¢˜ç›¸å¯¹å…¨é¢çš„概述，请å‚阅 - Documentation/driver-api/pm/devices.rst。 - -管ç†ï¼š 如果一个驱动程åºçš„作者还在进行有效的维护，那么通常除了那 - 些明显æ£ç¡®ä¸”ä¸éœ€è¦ä»»ä½•æ£€æŸ¥çš„è¡¥ä¸ä»¥å¤–，其他所有的补ä¸éƒ½ä¼š - 被转å‘ç»™ä½œè€…ã€‚å¦‚æžœä½ å¸Œæœ›æˆä¸ºé©±åŠ¨ç¨‹åºçš„è”系人和更新者，最 - 好在代ç 注释ä¸å†™æ˜Žå¹¶ä¸”在 MAINTAINERS 文件ä¸åŠ 入这个驱动 - 程åºçš„æ¡ç›®ã€‚ - -ä¸å½±å“设备驱动能å¦è¢«æŽ¥å—çš„æ¡ä»¶ ------------------------------- - -供应商： 由硬件供应商æ¥ç»´æŠ¤é©±åŠ¨ç¨‹åºé€šå¸¸æ˜¯ä¸€ä»¶å¥½äº‹ã€‚ä¸è¿‡ï¼Œå¦‚æžœæºç - æ ‘é‡Œå·²ç»æœ‰å…¶ä»–人æ供了å¯ç¨³å®šå·¥ä½œçš„驱动程åºï¼Œé‚£ä¹ˆè¯·ä¸è¦æœŸ - 望“我是供应商â€ä¼šæˆä¸ºå†…æ ¸æ”¹ç”¨ä½ çš„é©±åŠ¨ç¨‹åºçš„ç†ç”±ã€‚ç†æƒ³çš„情 - 况是：供应商与现有驱动程åºçš„作者åˆä½œï¼Œæž„建一个统一完美的 - 驱动程åºã€‚ - -作者： 驱动程åºæ˜¯ç”±å¤§çš„ Linux å…¬å¸ç ”å‘è¿˜æ˜¯ç”±ä½ ä¸ªäººç¼–å†™ï¼Œå¹¶ä¸å½± - å“其是å¦èƒ½è¢«å†…æ ¸æŽ¥å—ã€‚æ²¡æœ‰äººå¯¹å†…æ ¸æºç æ ‘äº«æœ‰ç‰¹æƒã€‚åªè¦ä½ - å……åˆ†äº†è§£å†…æ ¸ç¤¾åŒºï¼Œä½ å°±ä¼šå‘现这一点。 - - -资æºåˆ—表 --------- - -Linux å†…æ ¸ä¸»æºç æ ‘ï¼š - ftp.??.kernel.org:/pub/linux/kernel/... - ?? == ä½ çš„å›½å®¶ä»£ç ，例如 "cn"ã€"us"ã€"uk"ã€"fr" ç‰ç‰ - -Linux å†…æ ¸é‚®ä»¶åˆ—è¡¨ï¼š - linux-kernel@vger.kernel.org - [å¯é€šè¿‡å‘majordomo@vger.kernel.orgå‘邮件æ¥è®¢é˜…] - -Linux 设备驱动程åºï¼Œç¬¬ä¸‰ç‰ˆï¼ˆæŽ¢è®¨ 2.6.10 ç‰ˆå†…æ ¸ï¼‰ï¼š - https://lwn.net/Kernel/LDD3/ （å…费版） - -LWN.net: - æ¯å‘¨å†…æ ¸å¼€å‘æ´»åŠ¨æ‘˜è¦ - https://lwn.net/ - - 2.6 ç‰ˆä¸ API çš„å˜æ›´ï¼š - - https://lwn.net/Articles/2.6-kernel-api/ - - å°†æ—§ç‰ˆå†…æ ¸çš„é©±åŠ¨ç¨‹åºç§»æ¤åˆ° 2.6 版： - - https://lwn.net/Articles/driver-porting/ - -å†…æ ¸æ–°æ‰‹(KernelNewbies): - ä¸ºæ–°çš„å†…æ ¸å¼€å‘者æ供文档和帮助 - https://kernelnewbies.org/ - -Linux USB项目： - http://www.linux-usb.org/ - -å†™å†…æ ¸é©±åŠ¨çš„â€œä¸è¦â€ï¼ˆArjan van de Ven著）: - http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf - -å†…æ ¸æ¸…æ´å·¥ (Kernel Janitor): - https://kernelnewbies.org/KernelJanitors diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst index a9570165582a..ebb7f37575c1 100644 --- a/Documentation/translations/zh_CN/process/submitting-patches.rst +++ b/Documentation/translations/zh_CN/process/submitting-patches.rst @@ -23,9 +23,7 @@ 以下文档å«æœ‰å¤§é‡ç®€æ´çš„建议， 具体请è§ï¼š :ref:`Documentation/process <development_process_main>` åŒæ ·ï¼Œ:ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>` -给出在æ交代ç å‰éœ€è¦æ£€æŸ¥çš„é¡¹ç›®çš„åˆ—è¡¨ã€‚å¦‚æžœä½ åœ¨æ交一个驱动程åºï¼Œé‚£ä¹ˆ -åŒæ—¶é˜…读一下: -:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` +给出在æ交代ç å‰éœ€è¦æ£€æŸ¥çš„项目的列表。 å…¶ä¸è®¸å¤šæ¥éª¤æ述了Git版本控制系统的默认行为；如果您使用Gitæ¥å‡†å¤‡è¡¥ä¸ï¼Œ 您将å‘现它为您完æˆçš„大部分机械工作，尽管您ä»ç„¶éœ€è¦å‡†å¤‡å’Œè®°å½•ä¸€ç»„åˆç†çš„ diff --git a/Documentation/translations/zh_CN/riscv/index.rst b/Documentation/translations/zh_CN/riscv/index.rst index 614cde0c0997..131e405aa857 100644 --- a/Documentation/translations/zh_CN/riscv/index.rst +++ b/Documentation/translations/zh_CN/riscv/index.rst @@ -19,7 +19,6 @@ RISC-V 体系结构 boot-image-header vm-layout - pmu patch-acceptance diff --git a/Documentation/translations/zh_CN/riscv/pmu.rst b/Documentation/translations/zh_CN/riscv/pmu.rst deleted file mode 100644 index 7ec801026c4d..000000000000 --- a/Documentation/translations/zh_CN/riscv/pmu.rst +++ /dev/null @@ -1,235 +0,0 @@ -.. include:: ../disclaimer-zh_CN.rst - -:Original: Documentation/riscv/pmu.rst - -:翻译: - - å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> - -.. _cn_riscv_pmu: - -======================== -RISC-Vå¹³å°ä¸Šå¯¹PMUsçš„æ”¯æŒ -======================== - -Alan Kao <alankao@andestech.com>, Mar 2018 - -简介 ------------- - -截æ¢æœ¬æ–‡æ’°å†™æ—¶ï¼Œåœ¨The RISC-V ISA Privileged Version 1.10ä¸æ到的 perf_event -相关特性如下: -（详情请查阅手册） - -* [m|s]counteren -* mcycle[h], cycle[h] -* minstret[h], instret[h] -* mhpeventx, mhpcounterx[h] - -仅有以上这些功能，移æ¤perf需è¦åšå¾ˆå¤šå·¥ä½œï¼Œç©¶å…¶åŽŸå› 是缺少以下通用架构的性能 -监测特性: - -* å¯ç”¨/åœç”¨è®¡æ•°å™¨ - 在我们这里，计数器一直在自由è¿è¡Œã€‚ -* 计数器溢出引起的ä¸æ– - 规范ä¸æ²¡æœ‰è¿™ç§åŠŸèƒ½ã€‚ -* ä¸æ–指示器 - ä¸å¯èƒ½æ‰€æœ‰çš„计数器都有很多的ä¸æ–端å£ï¼Œæ‰€ä»¥éœ€è¦ä¸€ä¸ªä¸æ–指示器让软件æ¥åˆ¤æ– - 哪个计数器刚好溢出。 -* 写入计数器 - ç”±äºŽå†…æ ¸ä¸èƒ½ä¿®æ”¹è®¡æ•°å™¨ï¼Œæ‰€ä»¥ä¼šæœ‰ä¸€ä¸ªSBIæ¥æ”¯æŒè¿™ä¸ªåŠŸèƒ½[1]。 å¦å¤–，一些厂商 - 考虑实现M-S-Uåž‹å·æœºå™¨çš„硬件扩展æ¥ç›´æŽ¥å†™å…¥è®¡æ•°å™¨ã€‚ - -这篇文档旨在为开å‘者æä¾›ä¸€ä¸ªåœ¨å†…æ ¸ä¸æ”¯æŒPMU的简è¦æŒ‡å—。下é¢çš„ç« èŠ‚ç®€è¦è§£é‡Šäº† -perf' 机制和待办事项。 - -ä½ å¯ä»¥åœ¨è¿™é‡ŒæŸ¥çœ‹ä»¥å‰çš„讨论[1][2]。 å¦å¤–，查看附录ä¸çš„ç›¸å…³å†…æ ¸ç»“æž„ä½“å¯èƒ½ä¼šæœ‰ -帮助。 - - -1. åˆå§‹åŒ– ---------- - -*riscv_pmu* 是一个类型为 *struct riscv_pmu* 的全局指针，它包å«äº†æ ¹æ®perf内部 -约定的å„ç§æ–¹æ³•å’ŒPMU-specificå‚æ•°ã€‚äººä»¬åº”è¯¥å£°æ˜Žè¿™æ ·çš„å®žä¾‹æ¥ä»£è¡¨PMU。 默认情况 -下， *riscv_pmu* 指å‘一个常é‡ç»“构体 *riscv_base_pmu* ，它对基准QEMU模型有éžå¸¸ -基础的支æŒã€‚ - - -然åŽä»–/她å¯ä»¥å°†å®žä¾‹çš„指针分é…ç»™ *riscv_pmu* ï¼Œè¿™æ ·å°±å¯ä»¥åˆ©ç”¨å·²ç»å®žçŽ°çš„最å°é€» -辑，或者创建他/她自己的 *riscv_init_platform_pmu* 实现。 - -æ¢å¥è¯è¯´ï¼ŒçŽ°æœ‰çš„ *riscv_base_pmu* æºåªæ˜¯æ供了一个å‚考实现。 å¼€å‘者å¯ä»¥çµæ´»åœ° -决定多少部分å¯ç”¨ï¼Œåœ¨æœ€æžç«¯çš„情况下，他们å¯ä»¥æ ¹æ®è‡ªå·±çš„需è¦å®šåˆ¶æ¯ä¸€ä¸ªå‡½æ•°ã€‚ - - -2. Event Initialization ------------------------ - -当用户å¯åŠ¨perf命令æ¥ç›‘控一些事件时，首先会被用户空间的perf工具解释为多个 -*perf_event_open* 系统调用，然åŽè¿›ä¸€æ¥è°ƒç”¨ä¸Šä¸€æ¥åˆ†é…çš„ *event_init* æˆå‘˜å‡½æ•° -的主体。 在 *riscv_base_pmu* 的情况下，就是 *riscv_event_init* 。 - -该功能的主è¦ç›®çš„是将用户æ供的事件翻译æˆæ˜ 射图，从而å¯ä»¥ç›´æŽ¥å¯¹HW-related的控 -制寄å˜å™¨æˆ–计数器进行æ“作。该翻译基于 *riscv_pmu* ä¸æä¾›çš„æ˜ å°„å’Œæ–¹æ³•ã€‚ - -注æ„，有些功能也å¯ä»¥åœ¨è¿™ä¸ªé˜¶æ®µå®Œæˆ: - -(1) ä¸æ–设置，这个在下一节说； -(2) 特é™çº§è®¾ç½®(仅用户空间ã€ä»…å†…æ ¸ç©ºé—´ã€ä¸¤è€…都有)ï¼› -(3) æžæž„函数设置。 通常应用 *riscv_destroy_event* å³å¯ï¼› -(4) 对éžé‡‡æ ·äº‹ä»¶çš„调整，这将被函数应用，如 *perf_adjust_period* ，通常如下:: - - if (!is_sampling_event(event)) { - hwc->sample_period = x86_pmu.max_period; - hwc->last_period = hwc->sample_period; - local64_set(&hwc->period_left, hwc->sample_period); - } - - -在 *riscv_base_pmu* 的情况下，目å‰åªæ供了（3）。 - - -3. ä¸æ– -------- - -3.1. ä¸æ–åˆå§‹åŒ– - -è¿™ç§æƒ…况ç»å¸¸å‡ºçŽ°åœ¨ *event_init* 方案的开头。通常情况下，这应该是一个代ç 段，如:: - - int x86_reserve_hardware(void) - { - int err = 0; - - if (!atomic_inc_not_zero(&pmc_refcount)) { - mutex_lock(&pmc_reserve_mutex); - if (atomic_read(&pmc_refcount) == 0) { - if (!reserve_pmc_hardware()) - err = -EBUSY; - else - reserve_ds_buffers(); - } - if (!err) - atomic_inc(&pmc_refcount); - mutex_unlock(&pmc_reserve_mutex); - } - - return err; - } - -而神奇的是 *reserve_pmc_hardware* ，它通常åšåŽŸåæ“作，使实现的IRQå¯ä»¥ä»ŽæŸä¸ªå…¨å±€å‡½ -数指针访问。 而 *release_pmc_hardware* 的作用æ£å¥½ç›¸å，它用在上一节æåˆ°çš„äº‹ä»¶åˆ†é… -器ä¸ã€‚ - - (注：从所有架构的实现æ¥çœ‹ï¼Œ*reserve/release* 对总是IRQ设置，所以 *pmc_hardware* - 似乎有些误导。 它并ä¸å¤„ç†äº‹ä»¶å’Œç‰©ç†è®¡æ•°å™¨ä¹‹é—´çš„绑定，这一点将在下一节介ç»ã€‚) - -3.2. IRQ结构体 - -基本上，一个IRQè¿è¡Œä»¥ä¸‹ä¼ªä»£ç :: - - for each hardware counter that triggered this overflow - - get the event of this counter - - // following two steps are defined as *read()*, - // check the section Reading/Writing Counters for details. - count the delta value since previous interrupt - update the event->count (# event occurs) by adding delta, and - event->hw.period_left by subtracting delta - - if the event overflows - sample data - set the counter appropriately for the next overflow - - if the event overflows again - too frequently, throttle this event - fi - fi - - end for - - 然而截至目å‰ï¼Œæ²¡æœ‰ä¸€ä¸ªRISC-V的实现为perf设计了ä¸æ–，所以具体的实现è¦åœ¨æœªæ¥å®Œæˆã€‚ - -4. Reading/Writing 计数 ------------------------ - -它们看似差ä¸å¤šï¼Œä½†perf对待它们的æ€åº¦å´æˆªç„¶ä¸åŒã€‚ 对于读，在 *struct pmu* ä¸æœ‰ä¸€ä¸ª -*read* 接å£ï¼Œä½†å®ƒçš„作用ä¸ä»…仅是读。 æ ¹æ®ä¸Šä¸‹æ–‡ï¼Œ*read* 函数ä¸ä»…è¦è¯»å–计数器的内容 -（event->count），还è¦æ›´æ–°å·¦å‘¨æœŸåˆ°ä¸‹ä¸€ä¸ªä¸æ–（event->hw.period_left）。 - - 但 perf çš„æ ¸å¿ƒä¸éœ€è¦ç›´æŽ¥å†™è®¡æ•°å™¨ã€‚ 写计数器éšè—在以下两点的抽象化之åŽï¼Œ - 1） *pmu->start* ，从å—é¢ä¸Šçœ‹å°±æ˜¯å¼€å§‹è®¡æ•°ï¼Œæ‰€ä»¥å¿…须把计数器设置æˆä¸€ä¸ªåˆé€‚的值，以 - 便下一次ä¸æ–ï¼› - 2）在IRQ里é¢ï¼Œåº”该把计数器设置æˆåŒæ ·çš„åˆç†å€¼ã€‚ - -在RISC-Vä¸ï¼Œè¯»æ“作ä¸æ˜¯é—®é¢˜ï¼Œä½†å†™æ“作就需è¦è´¹äº›åŠ›æ°”äº†ï¼Œå› ä¸ºS模å¼ä¸å…许写计数器。 - - -5. add()/del()/start()/stop() ------------------------------ - -基本æ€æƒ³: add()/del() å‘PMUæ·»åŠ /åˆ é™¤äº‹ä»¶ï¼Œstart()/stop() å¯åŠ¨/åœæ¢PMUä¸æŸä¸ªäº‹ä»¶ -的计数器。 所有这些函数都使用相åŒçš„å‚æ•°: *struct perf_event *event* å’Œ *int flag* 。 - -把 perf 看作一个状æ€æœºï¼Œé‚£ä¹ˆä½ 会å‘现这些函数作为这些状æ€ä¹‹é—´çš„状æ€è½¬æ¢è¿‡ç¨‹ã€‚ -定义了三ç§çŠ¶æ€ï¼ˆevent->hw.state）: - -* PERF_HES_STOPPED: 计数åœæ¢ -* PERF_HES_UPTODATE: event->count是最新的 -* PERF_HES_ARCH: ä¾èµ–于体系结构的用法，。。。我们现在并ä¸éœ€è¦å®ƒã€‚ - -这些状æ€è½¬æ¢çš„æ£å¸¸æµç¨‹å¦‚下: - -* 用户å¯åŠ¨ä¸€ä¸ª perf 事件，导致调用 *event_init* 。 -* 当被上下文切æ¢è¿›æ¥çš„时候，*add* 会被 perf core è°ƒç”¨ï¼Œå¹¶å¸¦æœ‰ä¸€ä¸ªæ ‡å¿— PERF_EF_START， - ä¹Ÿå°±æ˜¯è¯´äº‹ä»¶è¢«æ·»åŠ åŽåº”该被å¯åŠ¨ã€‚ 在这个阶段，如果有的è¯ï¼Œä¸€èˆ¬äº‹ä»¶ä¼šè¢«ç»‘定到一个物 - ç†è®¡æ•°å™¨ä¸Šã€‚当状æ€å˜ä¸ºPERF_HES_STOPPEDå’ŒPERF_HES_UPTODATEï¼Œå› ä¸ºçŽ°åœ¨å·²ç»åœæ¢äº†, - （软件）事件计数ä¸éœ€è¦æ›´æ–°ã€‚ - - - 然åŽè°ƒç”¨ *start* ，并å¯ç”¨è®¡æ•°å™¨ã€‚ - 通过PERF_EF_RELOADæ ‡å¿—ï¼Œå®ƒå‘计数器写入一个适当的值（详细情况请å‚考上一节）。 - å¦‚æžœæ ‡å¿—ä¸åŒ…å«PERF_EF_RELOAD，则ä¸ä¼šå†™å…¥ä»»ä½•å†…容。 - 现在状æ€è¢«é‡ç½®ä¸ºnoneï¼Œå› ä¸ºå®ƒæ—¢æ²¡æœ‰åœæ¢ä¹Ÿæ²¡æœ‰æ›´æ–°ï¼ˆè®¡æ•°å·²ç»å¼€å§‹ï¼‰ã€‚ - -*当被上下文切æ¢å‡ºæ¥æ—¶è¢«è°ƒç”¨ã€‚ 然åŽï¼Œå®ƒæ£€æŸ¥å‡ºPMUä¸çš„所有事件，并调用 *stop* æ¥æ›´æ–°å®ƒä»¬ - 的计数。 - - - *stop* 被 *del* å’Œperfæ ¸å¿ƒè°ƒç”¨ï¼Œæ ‡å¿—ä¸ºPERF_EF_UPDATE，它ç»å¸¸ä»¥ç›¸åŒçš„逻辑和 *read* - 共用åŒä¸€ä¸ªå程åºã€‚ - 状æ€åˆä¸€æ¬¡å˜ä¸ºPERF_HES_STOPPEDå’ŒPERF_HES_UPTODATE。 - - - 这两对程åºçš„生命周期: *add* å’Œ *del* 在任务切æ¢æ—¶è¢«åå¤è°ƒç”¨ï¼›*start* å’Œ *stop* 在 - perfæ ¸å¿ƒéœ€è¦å¿«é€Ÿåœæ¢å’Œå¯åŠ¨æ—¶ä¹Ÿä¼šè¢«è°ƒç”¨ï¼Œæ¯”如在调整ä¸æ–周期时。 - -ç›®å‰çš„实现已ç»è¶³å¤Ÿäº†ï¼Œå°†æ¥å¯ä»¥å¾ˆå®¹æ˜“地扩展到功能。 - -A. 相关结构体 -------------- - -* struct pmu: include/linux/perf_event.h -* struct riscv_pmu: arch/riscv/include/asm/perf_event.h - - 两个结构体都被设计为åªè¯»ã€‚ - - *struct pmu* 定义了一些函数指针接å£ï¼Œå®ƒä»¬å¤§å¤šä»¥ *struct perf_event* 作为主å‚æ•°ï¼Œæ ¹æ® - perf的内部状æ€æœºå¤„ç†perf事件（详情请查看kernel/events/core.c）。 - - *struct riscv_pmu* 定义了PMU的具体å‚数。 命åéµå¾ªæ‰€æœ‰å…¶å®ƒæž¶æž„的惯例。 - -* struct perf_event: include/linux/perf_event.h -* struct hw_perf_event - - 表示 perf 事件的通用结构体，以åŠç¡¬ä»¶ç›¸å…³çš„细节。 - -* struct riscv_hw_events: arch/riscv/include/asm/perf_event.h - - ä¿å˜äº‹ä»¶çŠ¶æ€çš„结构有两个固定æˆå‘˜ã€‚ - 事件的数é‡å’Œäº‹ä»¶çš„数组。 - -å‚考文献 --------- - -[1] https://github.com/riscv/riscv-linux/pull/124 - -[2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA diff --git a/Documentation/translations/zh_CN/riscv/vm-layout.rst b/Documentation/translations/zh_CN/riscv/vm-layout.rst index 585cb89317a3..91884e2dfff8 100644 --- a/Documentation/translations/zh_CN/riscv/vm-layout.rst +++ b/Documentation/translations/zh_CN/riscv/vm-layout.rst @@ -6,6 +6,7 @@ :翻译: å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + Binbin Zhou <zhoubinbin@loongson.cn> ============================ RISC-V Linux上的虚拟内å˜å¸ƒå±€ @@ -65,3 +66,39 @@ RISC-V Linux Kernel SV39 ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | modules, BPF ffffffff80000000 | -2 GB | ffffffffffffffff | 2 GB | kernel __________________|____________|__________________|_________|____________________________________________________________ + + +RISC-V Linux Kernel SV48 +------------------------ + +:: + + ======================================================================================================================== + å¼€å§‹åœ°å€ | å移 | 结æŸåœ°å€ | å¤§å° | 虚拟内å˜åŒºåŸŸæè¿° + ======================================================================================================================== + | | | | + 0000000000000000 | 0 | 00007fffffffffff | 128 TB | 用户空间虚拟内å˜ï¼Œæ¯ä¸ªå†…å˜ç®¡ç†å™¨ä¸åŒ + __________________|____________|__________________|_________|___________________________________________________________ + | | | | + 0000800000000000 | +128 TB | ffff7fffffffffff | ~16M TB | ... 巨大的ã€å‡ 乎64ä½å®½çš„ç›´åˆ°å†…æ ¸æ˜ å°„çš„-128TB地方 + | | | | 开始å移的éžç»å…¸è™šæ‹Ÿå†…å˜åœ°å€ç©ºæ´žã€‚ + | | | | + __________________|____________|__________________|_________|___________________________________________________________ + | + | å†…æ ¸ç©ºé—´çš„è™šæ‹Ÿå†…å˜ï¼Œåœ¨æ‰€æœ‰è¿›ç¨‹ä¹‹é—´å…±äº«: + ____________________________________________________________|___________________________________________________________ + | | | | + ffff8d7ffee00000 | -114.5 TB | ffff8d7ffeffffff | 2 MB | fixmap + ffff8d7fff000000 | -114.5 TB | ffff8d7fffffffff | 16 MB | PCI io + ffff8d8000000000 | -114.5 TB | ffff8f7fffffffff | 2 TB | vmemmap + ffff8f8000000000 | -112.5 TB | ffffaf7fffffffff | 32 TB | vmalloc/ioremap space + ffffaf8000000000 | -80.5 TB | ffffef7fffffffff | 64 TB | ç›´æŽ¥æ˜ å°„æ‰€æœ‰ç‰©ç†å†…å˜ + ffffef8000000000 | -16.5 TB | fffffffeffffffff | 16.5 TB | kasan + __________________|____________|__________________|_________|____________________________________________________________ + | + | 从æ¤å¤„开始，与39-bit布局相åŒï¼š + ____________________________________________________________|____________________________________________________________ + | | | | + ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | modules, BPF + ffffffff80000000 | -2 GB | ffffffffffffffff | 2 GB | kernel + __________________|____________|__________________|_________|____________________________________________________________ diff --git a/Documentation/translations/zh_CN/scheduler/sched-stats.rst b/Documentation/translations/zh_CN/scheduler/sched-stats.rst index 1c68c3d1c283..c5e0be663837 100644 --- a/Documentation/translations/zh_CN/scheduler/sched-stats.rst +++ b/Documentation/translations/zh_CN/scheduler/sched-stats.rst @@ -57,8 +57,8 @@ cpu<N> 1 2 3 4 5 6 7 8 9 接下æ¥çš„三个统计数æ®æ述了调度延迟： - 7) 本处ç†å™¨è¿è¡Œä»»åŠ¡çš„总时间，å•ä½æ˜¯jiffies - 8) 本处ç†å™¨ä»»åŠ¡ç‰å¾…è¿è¡Œçš„时间，å•ä½æ˜¯jiffies + 7) 本处ç†å™¨è¿è¡Œä»»åŠ¡çš„总时间，å•ä½æ˜¯çº³ç§’ + 8) 本处ç†å™¨ä»»åŠ¡ç‰å¾…è¿è¡Œçš„时间，å•ä½æ˜¯çº³ç§’ 9) 本CPUè¿è¡Œäº†#个时间片 åŸŸç»Ÿè®¡æ•°æ® @@ -146,8 +146,8 @@ domain<N> <cpumask> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 schedstatsè¿˜æ·»åŠ äº†ä¸€ä¸ªæ–°çš„/proc/<pid>/schedstat文件，æ¥æ供一些进程级的 相åŒä¿¡æ¯ã€‚这个文件ä¸ï¼Œæœ‰ä¸‰ä¸ªå—段与该进程相关： - 1) 在CPU上è¿è¡ŒèŠ±è´¹çš„时间 - 2) 在è¿è¡Œé˜Ÿåˆ—上ç‰å¾…的时间 + 1) 在CPU上è¿è¡ŒèŠ±è´¹çš„时间(å•ä½æ˜¯çº³ç§’) + 2) 在è¿è¡Œé˜Ÿåˆ—上ç‰å¾…的时间(å•ä½æ˜¯çº³ç§’) 3) 在CPU上è¿è¡Œäº†#个时间片 å¯ä»¥å¾ˆå®¹æ˜“地编写一个程åºï¼Œåˆ©ç”¨è¿™äº›é¢å¤–çš„å—段æ¥æŠ¥å‘Šä¸€ä¸ªç‰¹å®šçš„进程或一组进程在 diff --git a/Documentation/translations/zh_CN/vm/free_page_reporting.rst b/Documentation/translations/zh_CN/vm/free_page_reporting.rst index 31d6c34b956b..14336a3aa5f4 100644 --- a/Documentation/translations/zh_CN/vm/free_page_reporting.rst +++ b/Documentation/translations/zh_CN/vm/free_page_reporting.rst @@ -1,6 +1,6 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: Documentation/vm/_free_page_reporting.rst +:Original: Documentation/vm/free_page_reporting.rst :翻译: diff --git a/Documentation/translations/zh_CN/vm/frontswap.rst b/Documentation/translations/zh_CN/vm/frontswap.rst index 3eb07870e2ef..98aa6f581ea7 100644 --- a/Documentation/translations/zh_CN/vm/frontswap.rst +++ b/Documentation/translations/zh_CN/vm/frontswap.rst @@ -1,4 +1,4 @@ -:Original: Documentation/vm/_free_page_reporting.rst +:Original: Documentation/vm/free_page_reporting.rst :翻译: diff --git a/Documentation/translations/zh_CN/vm/highmem.rst b/Documentation/translations/zh_CN/vm/highmem.rst index 018838e58c3e..200321774646 100644 --- a/Documentation/translations/zh_CN/vm/highmem.rst +++ b/Documentation/translations/zh_CN/vm/highmem.rst @@ -50,55 +50,55 @@ ä¸´æ—¶è™šæ‹Ÿæ˜ å°„ ============ -å†…æ ¸åŒ…å«å‡ ç§åˆ›å»ºä¸´æ—¶æ˜ 射的方法。: +å†…æ ¸åŒ…å«å‡ ç§åˆ›å»ºä¸´æ—¶æ˜ 射的方法。下é¢çš„列表按照使用的优先顺åºæ˜¾ç¤ºäº†å®ƒä»¬ã€‚ -* vmap(). è¿™å¯ä»¥ç”¨æ¥å°†å¤šä¸ªç‰©ç†é¡µé•¿æœŸæ˜ 射到一个连ç»çš„虚拟空间。它需è¦synchronization - æ¥è§£é™¤æ˜ 射。 +* kmap_local_page()。这个函数是用æ¥è¦æ±‚çŸæœŸæ˜ 射的。它å¯ä»¥ä»Žä»»ä½•ä¸Šä¸‹æ–‡ï¼ˆåŒ…括ä¸æ–）ä¸è°ƒç”¨ï¼Œ + ä½†æ˜¯æ˜ å°„åªèƒ½åœ¨èŽ·å–它们的上下文ä¸ä½¿ç”¨ã€‚ -* kmap(). è¿™å…许对å•ä¸ªé¡µé¢è¿›è¡ŒçŸæœŸæ˜ 射。它需è¦synchronization，但在一定程度上被摊销。 - 当以嵌套方å¼ä½¿ç”¨æ—¶ï¼Œå®ƒä¹Ÿå¾ˆå®¹æ˜“出现æ»é”ï¼Œå› æ¤ä¸å»ºè®®åœ¨æ–°ä»£ç ä¸ä½¿ç”¨å®ƒã€‚ + 在å¯è¡Œçš„情况下，这个函数应该比其他所有的函数优先使用。 -* kmap_atomic(). è¿™å…许对å•ä¸ªé¡µé¢è¿›è¡Œéžå¸¸çŸçš„æ—¶é—´æ˜ å°„ã€‚ç”±äºŽæ˜ å°„è¢«é™åˆ¶åœ¨å‘布它的CPU上， - 它表现得很好，但å‘å¸ƒä»»åŠ¡å› æ¤è¢«è¦æ±‚留在该CPU上直到它完æˆï¼Œä»¥å…其他任务å–ä»£å®ƒçš„æ˜ å°„ã€‚ - - kmap_atomic() 也å¯ä»¥ç”±ä¸æ–ä¸Šä¸‹æ–‡ä½¿ç”¨ï¼Œå› ä¸ºå®ƒä¸ç¡çœ ，而且调用者å¯èƒ½åœ¨è°ƒç”¨kunmap_atomic() - 之åŽæ‰ç¡çœ 。 - - å¯ä»¥å‡è®¾k[un]map_atomic()ä¸ä¼šå¤±è´¥ã€‚ + è¿™äº›æ˜ å°„æ˜¯çº¿ç¨‹æœ¬åœ°å’ŒCPU本地的，这æ„味ç€æ˜ å°„åªèƒ½ä»Žè¿™ä¸ªçº¿ç¨‹ä¸è®¿é—®ï¼Œå¹¶ä¸”å½“æ˜ å°„å¤„äºŽæ´»åŠ¨çŠ¶ + æ€æ—¶ï¼Œè¯¥çº¿ç¨‹ä¸ŽCPU绑定。å³ä½¿çº¿ç¨‹è¢«æŠ¢å äº†ï¼ˆå› ä¸ºæŠ¢å 永远ä¸ä¼šè¢«å‡½æ•°ç¦ç”¨ï¼‰ï¼ŒCPU也ä¸èƒ½é€šè¿‡ + CPU-hotplug从系统ä¸æ‹”å‡ºï¼Œç›´åˆ°æ˜ å°„è¢«å¤„ç†æŽ‰ã€‚ + 在本地的kmap区域ä¸é‡‡å–pagefaults是有效的，除éžèŽ·å–æœ¬åœ°æ˜ å°„çš„ä¸Šä¸‹æ–‡ç”±äºŽå…¶ä»–åŽŸå› ä¸å…许 + è¿™æ ·åšã€‚ -使用kmap_atomic -=============== + kmap_local_page()总是返回一个有效的虚拟地å€ï¼Œå¹¶ä¸”å‡å®škunmap_local()ä¸ä¼šå¤±è´¥ã€‚ -何时何地使用 kmap_atomic() 是很直接的。当代ç 想è¦è®¿é—®ä¸€ä¸ªå¯èƒ½ä»Žé«˜å†…å˜ï¼ˆè§__GFP_HIGHMEM） -分é…的页é¢çš„内容时，例如在页缓å˜ä¸çš„页é¢ï¼Œå°±ä¼šä½¿ç”¨å®ƒã€‚该API有两个函数，它们的使用方å¼ä¸Ž -下é¢ç±»ä¼¼:: + 嵌套kmap_local_page()å’Œkmap_atomic()æ˜ å°„åœ¨ä¸€å®šç¨‹åº¦ä¸Šæ˜¯å…许的（最多到KMAP_TYPE_NR）， + ä½†æ˜¯å®ƒä»¬çš„è°ƒç”¨å¿…é¡»ä¸¥æ ¼æŽ’åºï¼Œå› ä¸ºæ˜ å°„çš„å®žçŽ°æ˜¯åŸºäºŽå †æ ˆçš„ã€‚å…³äºŽå¦‚ä½•ç®¡ç†åµŒå¥—æ˜ å°„çš„ç»†èŠ‚ï¼Œ + 请å‚è§kmap_local_page() kdocs（包å«åœ¨ "函数 "部分）。 - /* 找到感兴趣的页é¢ã€‚ */ - struct page *page = find_get_page(mapping, offset); - - /* 获得对该页内容的访问æƒã€‚ */ - void *vaddr = kmap_atomic(page); +* kmap_atomic(). è¿™å…许对å•ä¸ªé¡µé¢è¿›è¡Œéžå¸¸çŸçš„æ—¶é—´æ˜ å°„ã€‚ç”±äºŽæ˜ å°„è¢«é™åˆ¶åœ¨å‘布它的CPU上， + 它表现得很好，但å‘å¸ƒçš„ä»»åŠ¡å› æ¤è¢«è¦æ±‚留在该CPU上直到它完æˆï¼Œä»¥å…其他任务å–ä»£å®ƒçš„æ˜ å°„ã€‚ - /* 对该页的内容åšä¸€äº›å¤„ç†ã€‚ */ - memset(vaddr, 0, PAGE_SIZE); + kmap_atomic()也å¯ä»¥è¢«ä¸æ–ä¸Šä¸‹æ–‡ä½¿ç”¨ï¼Œå› ä¸ºå®ƒä¸ç¡çœ ，调用者也å¯èƒ½åœ¨è°ƒç”¨kunmap_atomic() + åŽæ‰ç¡çœ 。 - /* 解除该页é¢çš„æ˜ å°„ã€‚ */ - kunmap_atomic(vaddr); + å†…æ ¸ä¸å¯¹kmap_atomic()çš„æ¯æ¬¡è°ƒç”¨éƒ½ä¼šåˆ›å»ºä¸€ä¸ªä¸å¯æŠ¢å 的段，并ç¦ç”¨ç¼ºé¡µå¼‚常。这å¯èƒ½æ˜¯ + 未预期延迟的æ¥æºä¹‹ä¸€ã€‚å› æ¤ç”¨æˆ·åº”该选择kmap_local_page()而ä¸æ˜¯kmap_atomic()。 -注æ„，kunmap_atomic()调用的是kmap_atomic()调用的结果而ä¸æ˜¯å‚数。 + å‡è®¾k[un]map_atomic()ä¸ä¼šå¤±è´¥ã€‚ -å¦‚æžœä½ éœ€è¦æ˜ 射两个页é¢ï¼Œå› ä¸ºä½ æƒ³ä»Žä¸€ä¸ªé¡µé¢å¤åˆ¶åˆ°å¦ä¸€ä¸ªé¡µé¢ï¼Œä½ 需è¦ä¿æŒkmap_atomic调用严 -æ ¼åµŒå¥—ï¼Œå¦‚:: +* kmap()。这应该被用æ¥å¯¹å•ä¸ªé¡µé¢è¿›è¡ŒçŸæ—¶é—´çš„æ˜ å°„ï¼Œå¯¹æŠ¢å 或è¿ç§»æ²¡æœ‰é™åˆ¶ã€‚它会带æ¥å¼€é”€ï¼Œ + å› ä¸ºæ˜ å°„ç©ºé—´æ˜¯å—é™åˆ¶çš„，并且å—到全局é”çš„ä¿æŠ¤ï¼Œä»¥å®žçŽ°åŒæ¥ã€‚当ä¸å†éœ€è¦æ˜ 射时，必须用 + kunmap()é‡Šæ”¾è¯¥é¡µè¢«æ˜ å°„çš„åœ°å€ã€‚ - vaddr1 = kmap_atomic(page1); - vaddr2 = kmap_atomic(page2); + æ˜ å°„å˜åŒ–必须广æ’到所有CPUï¼ˆæ ¸ï¼‰ä¸Šï¼Œkmap()还需è¦åœ¨kmapçš„æ± è¢«å›žç»•ï¼ˆTLB项用光了，需è¦ä»Žç¬¬ + 一项å¤ç”¨ï¼‰æ—¶è¿›è¡Œå…¨å±€TLBæ— æ•ˆåŒ–ï¼Œå½“æ˜ å°„ç©ºé—´è¢«å®Œå…¨åˆ©ç”¨æ—¶ï¼Œå®ƒå¯èƒ½ä¼šé˜»å¡žï¼Œç›´åˆ°æœ‰ä¸€ä¸ªå¯ç”¨çš„ + æ§½å‡ºçŽ°ã€‚å› æ¤ï¼Œkmap()åªèƒ½ä»Žå¯æŠ¢å 的上下文ä¸è°ƒç”¨ã€‚ - memcpy(vaddr1, vaddr2, PAGE_SIZE); + å¦‚æžœä¸€ä¸ªæ˜ å°„å¿…é¡»æŒç»ç›¸å¯¹è¾ƒé•¿çš„时间，上述所有的工作都是必è¦çš„ï¼Œä½†æ˜¯å†…æ ¸ä¸å¤§éƒ¨åˆ†çš„ + 高内å˜æ˜ 射都是çŸæš‚的，而且åªåœ¨ä¸€ä¸ªåœ°æ–¹ä½¿ç”¨ã€‚è¿™æ„味ç€åœ¨è¿™ç§æƒ…况下，kmap()çš„æˆæœ¬å¤§ + 多被浪费了。kmap()并ä¸æ˜¯ä¸ºé•¿æœŸæ˜ 射而设计的，但是它已ç»æœç€è¿™ä¸ªæ–¹å‘å‘展了，在较新 + 的代ç ä¸å¼ºçƒˆä¸é¼“励使用它，å‰é¢çš„函数集应该是首选。 - kunmap_atomic(vaddr2); - kunmap_atomic(vaddr1); + 在64ä½ç³»ç»Ÿä¸ï¼Œè°ƒç”¨kmap_local_page()ã€kmap_atomic()å’Œkmap()æ²¡æœ‰å®žé™…ä½œç”¨ï¼Œå› ä¸º64ä½ + 地å€ç©ºé—´è¶³ä»¥æ°¸ä¹…æ˜ å°„æ‰€æœ‰ç‰©ç†å†…å˜é¡µé¢ã€‚ +* vmap()。这å¯ä»¥ç”¨æ¥å°†å¤šä¸ªç‰©ç†é¡µé•¿æœŸæ˜ 射到一个连ç»çš„虚拟空间。它需è¦å…¨å±€åŒæ¥æ¥è§£é™¤ + æ˜ å°„ã€‚ ä¸´æ—¶æ˜ å°„çš„æˆæœ¬ ============== @@ -126,3 +126,12 @@ i386 PAE ä¸€èˆ¬çš„å»ºè®®æ˜¯ï¼Œä½ ä¸è¦åœ¨32ä½æœºå™¨ä¸Šä½¿ç”¨è¶…过8GiB的空间--尽管更多的空间å¯èƒ½å¯¹ä½ å’Œä½ çš„å·¥ä½œ é‡æœ‰ç”¨ï¼Œä½†ä½ å‡ ä¹Žæ˜¯é ä½ è‡ªå·±--ä¸è¦æŒ‡æœ›å†…æ ¸å¼€å‘者真的会很关心事情的进展情况。 + +函数 +==== + +该APIåœ¨ä»¥ä¸‹å†…æ ¸ä»£ç ä¸: + +include/linux/highmem.h + +include/linux/highmem-internal.h diff --git a/Documentation/translations/zh_CN/vm/index.rst b/Documentation/translations/zh_CN/vm/index.rst index a1c6d529b6ff..c77a56553845 100644 --- a/Documentation/translations/zh_CN/vm/index.rst +++ b/Documentation/translations/zh_CN/vm/index.rst @@ -12,11 +12,27 @@ Linux内å˜ç®¡ç†æ–‡æ¡£ ================= -这是一个关于Linux内å˜ç®¡ç†ï¼ˆmm）å系统内部的文档集，其ä¸æœ‰ä¸åŒå±‚次的细节，包括注释 -和邮件列表的回å¤ï¼Œç”¨äºŽé˜è¿°æ•°æ®ç»“æž„å’Œç®—æ³•çš„åŸºæœ¬æƒ…å†µã€‚å¦‚æžœä½ æ£åœ¨å¯»æ‰¾å…³äºŽç®€å•åˆ†é…内å˜çš„建 -议，请å‚阅(Documentation/translations/zh_CN/core-api/memory-allocation.rst)。 -对于控制和调整指å—，请å‚阅(Documentation/admin-guide/mm/index)。 -TODO:待引用文档集被翻译完毕åŽè¯·åŠæ—¶ä¿®æ”¹æ¤å¤„） +这是一份关于了解Linux的内å˜ç®¡ç†å系统的指å—ã€‚å¦‚æžœä½ æ£åœ¨å¯»æ‰¾å…³äºŽç®€å•åˆ†é…内å˜çš„ +建议，请å‚阅内å˜åˆ†é…æŒ‡å— +(Documentation/translations/zh_CN/core-api/memory-allocation.rst)。 +关于控制和调整的指å—，请看管ç†æŒ‡å— +(Documentation/translations/zh_CN/admin-guide/mm/index.rst)。 + + +.. toctree:: + :maxdepth: 1 + + highmem + +该处剩余文档待原始文档有内容åŽç¿»è¯‘。 + + +é—留文档 +======== + +这是一个关于Linux内å˜ç®¡ç†ï¼ˆMM）å系统内部的旧文档的集åˆï¼Œå…¶ä¸æœ‰ä¸åŒå±‚次的细节， +包括注释和邮件列表的回å¤ï¼Œç”¨äºŽé˜è¿°æ•°æ®ç»“构和算法的æ述。它应该被很好地整åˆåˆ°ä¸Šè¿° +结构化的文档ä¸ï¼Œå¦‚果它已ç»å®Œæˆäº†å®ƒçš„使命，å¯ä»¥åˆ 除。 .. toctree:: :maxdepth: 1 @@ -25,7 +41,6 @@ TODO:待引用文档集被翻译完毕åŽè¯·åŠæ—¶ä¿®æ”¹æ¤å¤„） balance damon/index free_page_reporting - highmem ksm frontswap hmm @@ -36,10 +51,12 @@ TODO:待引用文档集被翻译完毕åŽè¯·åŠæ—¶ä¿®æ”¹æ¤å¤„） numa overcommit-accounting page_frags + page_migration page_owner page_table_check remap_file_pages split_page_table_lock + vmalloced-kernel-stacks z3fold zsmalloc @@ -47,8 +64,6 @@ TODOLIST: * arch_pgtable_helpers * free_page_reporting * hugetlbfs_reserv -* page_migration * slub * transhuge * unevictable-lru -* vmalloced-kernel-stacks diff --git a/Documentation/translations/zh_CN/vm/page_frags.rst b/Documentation/translations/zh_CN/vm/page_frags.rst index ad27fed33634..38ecddb9e1c0 100644 --- a/Documentation/translations/zh_CN/vm/page_frags.rst +++ b/Documentation/translations/zh_CN/vm/page_frags.rst @@ -1,4 +1,4 @@ -:Original: Documentation/vm/page_frag.rst +:Original: Documentation/vm/page_frags.rst :翻译: diff --git a/Documentation/translations/zh_CN/vm/page_migration.rst b/Documentation/translations/zh_CN/vm/page_migration.rst new file mode 100644 index 000000000000..566880a41ea0 --- /dev/null +++ b/Documentation/translations/zh_CN/vm/page_migration.rst @@ -0,0 +1,228 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/vm/index.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +======== +页é¢è¿ç§» +======== + +页é¢è¿ç§»å…许在进程è¿è¡Œæ—¶åœ¨NUMA系统的节点之间移动页é¢çš„物ç†ä½ç½®ã€‚è¿™æ„味ç€è¿›ç¨‹æ‰€çœ‹åˆ°çš„虚拟地 +å€å¹¶æ²¡æœ‰æ”¹å˜ã€‚然而，系统会é‡æ–°å®‰æŽ’这些页é¢çš„物ç†ä½ç½®ã€‚ + +也å¯ä»¥å‚è§ :ref: `<异构内å˜ç®¡ç† (HMM)>` 以了解将页é¢è¿ç§»åˆ°è®¾å¤‡ç§æœ‰å†…å˜æˆ–从设备ç§æœ‰å†…å˜ä¸è¿ç§»ã€‚ + +页é¢è¿ç§»çš„主è¦ç›®çš„是通过将页é¢ç§»åˆ°è®¿é—®è¯¥å†…å˜çš„进程所è¿è¡Œçš„处ç†å™¨é™„è¿‘æ¥å‡å°‘内å˜è®¿é—®çš„延迟。 + +页é¢è¿ç§»å…许进程通过MF_MOVEå’ŒMF_MOVE_ALL选项手动é‡æ–°å®šä½å…¶é¡µé¢æ‰€åœ¨çš„节点，åŒæ—¶é€šè¿‡ +mbind()设置一个新的内å˜ç–略。一个进程的页é¢ä¹Ÿå¯ä»¥é€šè¿‡sys_migrate_pages()å‡½æ•°è°ƒç”¨ä»Žå¦ +一个进程é‡æ–°å®šä½ã€‚migrate_pages()函数调用接收两组节点，并将一个进程ä½äºŽæ—§èŠ‚点上的页é¢ç§» +åŠ¨åˆ°ç›®æ ‡èŠ‚ç‚¹ä¸Šã€‚é¡µé¢è¿ç§»åŠŸèƒ½ç”±Andi Kleençš„numactl包æä¾›(需è¦0.9.3以上的版本，其仓库 +地å€https://github.com/numactl/numactl.git)。numactlæ供了libnuma，它为页é¢è¿ç§» +æ供了与其他NUMA功能类似的接å£ã€‚执行 cat ``/proc/<pid>/numa_maps`` å…许轻æ¾æŸ¥çœ‹è¿› +程的页é¢ä½ç½®ã€‚å‚è§proc(5)手册ä¸çš„numa_maps文档。 + +如果调度程åºå°†ä¸€ä¸ªè¿›ç¨‹é‡æ–°å®‰ç½®åˆ°ä¸€ä¸ªé¥è¿œçš„节点上的处ç†å™¨ï¼Œæ‰‹åŠ¨è¿ç§»æ˜¯å¾ˆæœ‰ç”¨çš„。批é‡è°ƒåº¦ç¨‹åº +或管ç†å‘˜å¯ä»¥æ£€æµ‹åˆ°è¿™ç§æƒ…况，并将进程的页é¢ç§»åˆ°æ–°å¤„ç†å™¨é™„è¿‘ã€‚å†…æ ¸æœ¬èº«åªæ供手动的页è¿ç§»æ”¯æŒã€‚ +自动的页é¢è¿ç§»å¯ä»¥é€šè¿‡ç”¨æˆ·ç©ºé—´çš„进程移动页é¢æ¥å®žçŽ°ã€‚一个特殊的函数调用 "move_pages" å…许 +在一个进程ä¸ç§»åŠ¨å•ä¸ªé¡µé¢ã€‚例如，NUMA分æžå™¨å¯ä»¥èŽ·å¾—一个显示频ç¹çš„节点外访问的日志，并å¯ä»¥ä½¿ +用这个结果将页é¢ç§»åŠ¨åˆ°æ›´æœ‰åˆ©çš„ä½ç½®ã€‚ + +较大型的设备通常使用cpusets将系统分割æˆè‹¥å¹²ä¸ªèŠ‚点。Paul Jackson为cpusetsé…备了当任务被 +转移到å¦ä¸€ä¸ªcpuset时移动页é¢çš„能力(è§:ref:`CPUSETS <cpusets>`)。Cpusetså…许进程定 +ä½çš„自动化。如果一个任务被移到一个新的cpuset上，那么它的所有页é¢ä¹Ÿä¼šéšä¹‹ç§»åŠ¨ï¼Œè¿™æ ·è¿›ç¨‹çš„ +性能就ä¸ä¼šæ€¥å‰§ä¸‹é™ã€‚如果cpusetå…许的内å˜èŠ‚点å‘生å˜åŒ–，cpusetä¸çš„进程页也会被移动。 + +页é¢è¿ç§»å…许为所有è¿ç§»æŠ€æœ¯ä¿ç•™ä¸€ç»„节点ä¸é¡µé¢çš„相对ä½ç½®ï¼Œè¿™å°†ä¿ç•™ç”Ÿæˆçš„特定内å˜åˆ†é…模å¼å³ä½¿ +进程已被è¿ç§»ã€‚为了ä¿ç•™å†…å˜å»¶è¿Ÿï¼Œè¿™ä¸€ç‚¹æ˜¯å¿…è¦çš„。è¿ç§»åŽçš„进程将以类似的性能è¿è¡Œã€‚ + +页é¢è¿ç§»åˆ†å‡ 个æ¥éª¤è¿›è¡Œã€‚é¦–å…ˆä¸ºé‚£äº›è¯•å›¾ä»Žå†…æ ¸ä¸ä½¿ç”¨migrate_pages()的进程åšä¸€ä¸ªé«˜å±‚次的 +æ述（对于用户空间的使用，å¯ä»¥å‚考上é¢æ到的Andi Kleençš„numactl包），然åŽå¯¹ä½Žæ°´å¹³çš„细 +节工作åšä¸€ä¸ªä½Žæ°´å¹³æ述。 + +åœ¨å†…æ ¸ä¸ä½¿ç”¨ migrate_pages() +============================ + +1. 从LRUä¸ç§»é™¤é¡µé¢ã€‚ + + è¦è¿ç§»çš„页é¢åˆ—表是通过扫æ页é¢å¹¶æŠŠå®ƒä»¬ç§»åˆ°åˆ—表ä¸æ¥ç”Ÿæˆçš„。这是通过调用 isolate_lru_page() + æ¥å®Œæˆçš„。调用isolate_lru_page()å¢žåŠ äº†å¯¹è¯¥é¡µçš„å¼•ç”¨ï¼Œè¿™æ ·åœ¨é¡µé¢è¿ç§»å‘生时它就ä¸ä¼š + 消失。它还å¯ä»¥é˜²æ¢äº¤æ¢å™¨æˆ–其他扫æ器é‡åˆ°è¯¥é¡µã€‚ + + +2. 我们需è¦æœ‰ä¸€ä¸ªnew_page_t类型的函数，å¯ä»¥ä¼ 递给migrate_pages()。这个函数应该计算 + 出如何在给定的旧页é¢ä¸åˆ†é…æ£ç¡®çš„新页é¢ã€‚ + +3. migrate_pages()函数被调用，它试图进行è¿ç§»ã€‚它将调用该函数为æ¯ä¸ªè¢«è€ƒè™‘è¿ç§»çš„页é¢åˆ† + é…新的页é¢ã€‚ + +migrate_pages()如何工作 +======================= + +migrate_pages()对它的页é¢åˆ—表进行了多次处ç†ã€‚如果当时对一个页é¢çš„所有引用都å¯ä»¥è¢«ç§»é™¤ï¼Œ +那么这个页é¢å°±ä¼šè¢«ç§»åŠ¨ã€‚该页已ç»é€šè¿‡isolate_lru_page()从LRUä¸ç§»é™¤ï¼Œå¹¶ä¸”refcount被 +å¢žåŠ ï¼Œä»¥ä¾¿åœ¨é¡µé¢è¿ç§»å‘生时ä¸é‡Šæ”¾è¯¥é¡µã€‚ + +æ¥éª¤: + +1. é”定è¦è¿ç§»çš„页é¢ã€‚ + +2. ç¡®ä¿å›žå†™å·²ç»å®Œæˆã€‚ + +3. é”定我们è¦è¿ç§»åˆ°çš„新页é¢ã€‚é”定它是为了在è¿ç§»è¿‡ç¨‹ä¸ç«‹å³é˜»æ¢å¯¹è¿™ä¸ªï¼ˆå°šæœªæ›´æ–°çš„）页é¢çš„ + 访问。 + +4. 所有对该页的页表引用都被转æ¢ä¸ºè¿ç§»æ¡ç›®ã€‚这就å‡å°‘了一个页é¢çš„mapcount。如果产生的 + mapcountä¸æ˜¯é›¶ï¼Œé‚£ä¹ˆæˆ‘们就ä¸è¿ç§»è¯¥é¡µã€‚所有试图访问该页的用户空间进程现在将ç‰å¾…页 + é¢é”或者ç‰å¾…è¿ç§»é¡µè¡¨é¡¹è¢«ç§»é™¤ã€‚ + +5. i_pagesçš„é”被æŒæœ‰ã€‚è¿™å°†å¯¼è‡´æ‰€æœ‰è¯•å›¾é€šè¿‡æ˜ å°„è®¿é—®è¯¥é¡µçš„è¿›ç¨‹åœ¨è‡ªæ—‹é”上阻塞。 + +6. 检查该页的Refcount，如果还有引用，我们就退出。å¦åˆ™ï¼Œæˆ‘们知é“我们是唯一引用这个页 + é¢çš„人。 + +7. æ£€æŸ¥åŸºæ•°æ ‘ï¼Œå¦‚æžœå®ƒä¸åŒ…å«æŒ‡å‘这个页é¢çš„æŒ‡é’ˆï¼Œé‚£ä¹ˆæˆ‘ä»¬å°±é€€å‡ºï¼Œå› ä¸ºå…¶ä»–äººä¿®æ”¹äº†åŸºæ•°æ ‘ã€‚ + +8. 新的页é¢è¦ç”¨æ—§çš„页é¢çš„一些设置进行预处ç†ï¼Œè¿™æ ·è®¿é—®æ–°çš„页é¢å°±ä¼šå‘现一个具有æ£ç¡®è®¾ç½® + 的页é¢ã€‚ + +9. åŸºæ•°æ ‘è¢«æ”¹å˜ä»¥æŒ‡å‘新的页é¢ã€‚ + +10. æ—§é¡µçš„å¼•ç”¨è®¡æ•°è¢«åˆ é™¤ï¼Œå› ä¸ºåœ°å€ç©ºé—´çš„引用已ç»æ¶ˆå¤±ã€‚å¯¹æ–°é¡µçš„å¼•ç”¨è¢«å»ºç«‹ï¼Œå› ä¸ºæ–°é¡µè¢« + 地å€ç©ºé—´å¼•ç”¨ã€‚ + +11. i_pagesé”è¢«æ”¾å¼ƒã€‚è¿™æ ·ä¸€æ¥ï¼Œåœ¨æ˜ å°„ä¸çš„查找åˆå˜å¾—å¯èƒ½äº†ã€‚进程将从在é”上自旋到在 + 被é”的新页上ç¡çœ 。 + +12. 页é¢å†…容被å¤åˆ¶åˆ°æ–°çš„页é¢ä¸Šã€‚ + +13. 剩余的页é¢æ ‡å¿—被å¤åˆ¶åˆ°æ–°çš„页é¢ä¸Šã€‚ + +14. 旧的页é¢æ ‡å¿—被清除，以表明该页é¢ä¸å†æ供任何信æ¯ã€‚ + +15. 新页é¢ä¸Šçš„回写队列被触å‘了。 + +16. 如果è¿ç§»æ¡ç›®è¢«æ’入到页表ä¸ï¼Œé‚£ä¹ˆå°±ç”¨çœŸæ£çš„ptes替æ¢å®ƒä»¬ã€‚è¿™æ ·åšå°†ä½¿é‚£äº›å°šæœªç‰å¾…页 + é”的用户空间进程能够访问。 + +17. 页é¢é”从新旧页é¢ä¸Šè¢«æ’¤é”€ã€‚ç‰å¾…页é”的进程将é‡åšä»–们的缺页异常，并将到达新的页é¢ã€‚ + +18. 新的页é¢è¢«ç§»åˆ°LRUä¸ï¼Œå¯ä»¥è¢«äº¤æ¢å™¨ç‰å†æ¬¡æ‰«æ。 + +éžLRU页é¢è¿ç§» +============= + +尽管è¿ç§»æœ€åˆçš„目的是为了å‡å°‘NUMA的内å˜è®¿é—®å»¶è¿Ÿï¼Œä½†åŽ‹ç¼©ä¹Ÿä½¿ç”¨è¿ç§»æ¥åˆ›å»ºé«˜é˜¶é¡µé¢ã€‚ + +ç›®å‰å®žçŽ°çš„问题是，它被设计为åªè¿ç§»*LRU*页。然而，有一些潜在的éžLRU页é¢å¯ä»¥åœ¨é©±åŠ¨ä¸ +被è¿ç§»ï¼Œä¾‹å¦‚，zsmalloc，virtio-balloon页é¢ã€‚ + +对于virtio-balloon页é¢ï¼Œè¿ç§»ä»£ç 路径的æŸäº›éƒ¨åˆ†å·²ç»è¢«é’©ä½ï¼Œå¹¶æ·»åŠ 了virtio-balloon +的特定函数æ¥æ‹¦æˆªè¿ç§»é€»è¾‘。这对一个驱动æ¥è¯´å¤ªç‰¹æ®Šäº†ï¼Œæ‰€ä»¥å…¶ä»–想让自己的页é¢å¯ç§»åŠ¨çš„驱 +动就必须在è¿ç§»è·¯å¾„ä¸æ·»åŠ 自己的特定钩å。 + +为了克æœè¿™ä¸ªé—®é¢˜ï¼ŒVM支æŒéžLRU页é¢è¿ç§»ï¼Œå®ƒä¸ºéžLRUå¯ç§»åŠ¨é¡µé¢æ供了通用函数，而在è¿ç§» +路径ä¸æ²¡æœ‰ç‰¹å®šçš„驱动程åºé’©å。 + +如果一个驱动程åºæƒ³è®©å®ƒçš„页é¢å¯ç§»åŠ¨ï¼Œå®ƒåº”该定义三个函数，这些函数是 +struct address_space_operations的函数指针。 + +1. ``bool (*isolate_page) (struct page *page, isolate_mode_t mode);`` + + VM对驱动的isolate_page()函数的期望是，如果驱动æˆåŠŸéš”离了该页，则返回*true*。 + 返回trueåŽï¼ŒVMä¼šå°†è¯¥é¡µæ ‡è®°ä¸ºPG_isolatedï¼Œè¿™æ ·å¤šä¸ªCPU的并å‘隔离就会跳过该 + 页进行隔离。如果驱动程åºä¸èƒ½éš”离该页，它应该返回*false*。 + + 一旦页é¢è¢«æˆåŠŸéš”离，VM就会使用page.lruå—æ®µï¼Œå› æ¤é©±åŠ¨ç¨‹åºä¸åº”期望ä¿ç•™è¿™äº›å—段的值。 + +2. ``int (*migratepage) (struct address_space *mapping,`` +| ``struct page *newpage, struct page *oldpage, enum migrate_mode);`` + + 隔离åŽï¼Œè™šæ‹Ÿæœºç”¨éš”离的页é¢è°ƒç”¨é©±åŠ¨çš„migratepage()。migratepage()的功能是将旧页 + 的内容移动到新页，并设置struct page newpageçš„å—段。请记ä½ï¼Œå¦‚æžœä½ æˆåŠŸè¿ç§»äº†æ—§é¡µ + 并返回MIGRATEPAGE_SUCCESSï¼Œä½ åº”è¯¥é€šè¿‡page_lock下的__ClearPageMovable()å‘虚 + 拟机表明旧页ä¸å†å¯ç§»åŠ¨ã€‚如果驱动暂时ä¸èƒ½è¿ç§»è¯¥é¡µï¼Œé©±åŠ¨å¯ä»¥è¿”回-EAGAIN。在-EAGAIN + 时，VM会在çŸæ—¶é—´å†…é‡è¯•é¡µé¢è¿ç§»ï¼Œå› 为VMå°†-EAGAINç†è§£ä¸º "临时è¿ç§»å¤±è´¥"。在返回除 + -EAGAIN以外的任何错误时，VM将放弃页é¢è¿ç§»è€Œä¸é‡è¯•ã€‚ + + 在migratepage()函数ä¸ï¼Œé©±åŠ¨ç¨‹åºä¸åº”该接触page.lruå—段。 + +3. ``void (*putback_page)(struct page *);`` + + 如果在隔离页上è¿ç§»å¤±è´¥ï¼ŒVMåº”è¯¥å°†éš”ç¦»é¡µè¿”å›žç»™é©±åŠ¨ï¼Œå› æ¤VM用隔离页调用驱动的 + putback_page()。在这个函数ä¸ï¼Œé©±åŠ¨åº”该把隔离页放回自己的数æ®ç»“æž„ä¸ã€‚ + +éžLRUå¯ç§»åŠ¨é¡µæ ‡å¿— + + 有两个页é¢æ ‡å¿—用于支æŒéžLRUå¯ç§»åŠ¨é¡µé¢ã€‚ + + * PG_movable + + 驱动应该使用下é¢çš„函数æ¥ä½¿é¡µé¢åœ¨page_lock下å¯ç§»åŠ¨ã€‚:: + + void __SetPageMovable(struct page *page, struct address_space *mapping) + + 它需è¦address_spaceçš„å‚æ•°æ¥æ³¨å†Œå°†è¢«VM调用的migration family函数。确切地说， + PG_movableä¸æ˜¯struct page的一个真æ£çš„æ ‡å¿—ã€‚ç›¸å，VMå¤ç”¨äº†page->mapping的低 + ä½æ¥è¡¨ç¤ºå®ƒ:: + + #define PAGE_MAPPING_MOVABLE 0x2 + page->mapping = page->mapping | PAGE_MAPPING_MOVABLE; + + 所以驱动ä¸åº”该直接访问page->mapping。相å，驱动应该使用page_mapping()ï¼Œå®ƒå¯ + 以在页é¢é”下å±è”½æŽ‰page->mapping的低2ä½ï¼Œä»Žè€ŒèŽ·å¾—æ£ç¡®çš„struct address_space。 + + 对于éžLRUå¯ç§»åŠ¨é¡µé¢çš„测试，VM支æŒ__PageMovable()函数。然而，它并ä¸èƒ½ä¿è¯è¯†åˆ« + éžLRUå¯ç§»åŠ¨é¡µé¢ï¼Œå› 为page->mappingå—段与struct pageä¸çš„其他å˜é‡æ˜¯ç»Ÿä¸€çš„。如 + 果驱动程åºåœ¨è¢«è™šæ‹Ÿæœºéš”离åŽé‡Šæ”¾äº†é¡µé¢ï¼Œå°½ç®¡page->mapping设置了PAGE_MAPPING_MOVABLE， + 但它并没有一个稳定的值（看看__ClearPageMovable）。但是__PageMovable()在页 + é¢è¢«éš”离åŽï¼Œæ— 论页é¢æ˜¯LRU还是éžLRUå¯ç§»åŠ¨çš„ï¼Œè°ƒç”¨å®ƒå¼€é”€éƒ½å¾ˆä½Žï¼Œå› ä¸ºLRU页é¢åœ¨ + page->mappingä¸ä¸å¯èƒ½æœ‰PAGE_MAPPING_MOVABLE设置。在用pfn扫æä¸çš„lock_page() + 进行更大开销的检查æ¥é€‰æ‹©å—害者之å‰ï¼Œå®ƒä¹Ÿå¾ˆé€‚åˆåªæ˜¯çž¥ä¸€çœ¼æ¥æµ‹è¯•éžLRUå¯ç§»åŠ¨çš„页é¢ã€‚ + + 为了ä¿è¯éžLRUçš„å¯ç§»åŠ¨é¡µé¢ï¼ŒVMæ供了PageMovable()函数。与__PageMovable()ä¸ + åŒï¼ŒPageMovable()在lock_page()下验è¯page->mappingå’Œ + mapping->a_ops->isolate_page。lock_page()å¯ä»¥é˜²æ¢çªç„¶ç ´åpage->mapping。 + + 使用__SetPageMovable()的驱动应该在释放页é¢ä¹‹å‰é€šè¿‡page_lock()下的 + __ClearMovablePage()æ¸…é™¤è¯¥æ ‡å¿—ã€‚ + + * PG_isolated + + 为了防æ¢å‡ 个CPUåŒæ—¶è¿›è¡Œéš”离，VM在lock_page()下将隔离的页é¢æ ‡è®°ä¸ºPG_isolated。 + å› æ¤ï¼Œå¦‚果一个CPUé‡åˆ°PG_isolatedéžLRUå¯ç§»åŠ¨é¡µé¢ï¼Œå®ƒå¯ä»¥è·³è¿‡å®ƒã€‚驱动程åºä¸éœ€è¦ + æ“ä½œè¿™ä¸ªæ ‡å¿—ï¼Œå› ä¸ºVM会自动设置/清除它。请记ä½ï¼Œå¦‚果驱动程åºçœ‹åˆ°PG_isolated页， + è¿™æ„味ç€è¯¥é¡µå·²ç»è¢«VM隔离，所以它ä¸åº”该碰page.lruå—段。PG_isolatedæ ‡å¿—ä¸Ž + PG_reclaimæ ‡å¿—æ˜¯åŒä¹‰çš„，所以驱动程åºä¸åº”该为自己的目的使用PG_isolated。 + +监测è¿ç§» +======== + +以下事件（计数器）å¯ç”¨äºŽç›‘控页é¢è¿ç§»ã€‚ + +1. PGMIGRATE_SUCCESS: æ£å¸¸çš„页é¢è¿ç§»æˆåŠŸã€‚æ¯ä¸ªè®¡æ•°å™¨æ„味ç€ä¸€ä¸ªé¡µé¢è¢«è¿ç§»äº†ã€‚如果该 + 页是一个éžTHPå’Œéžhugetlbé¡µï¼Œé‚£ä¹ˆè¿™ä¸ªè®¡æ•°å™¨ä¼šå¢žåŠ 1。如果该页é¢æ˜¯ä¸€ä¸ªTHP或hugetlb + 页é¢ï¼Œé‚£ä¹ˆè¿™ä¸ªè®¡æ•°å™¨ä¼šéšç€THP或hugetlbå页é¢çš„æ•°é‡è€Œå¢žåŠ 。例如，è¿ç§»ä¸€ä¸ªæœ‰4KBå¤§å° + 的基础页（å页）的2MB THPï¼Œå°†å¯¼è‡´è¿™ä¸ªè®¡æ•°å™¨å¢žåŠ 512。 + +2. PGMIGRATE_FAIL: æ£å¸¸çš„页é¢è¿ç§»å¤±è´¥ã€‚与上é¢PGMIGRATE_SUCCESS的计数规则相åŒï¼šå¦‚ + 果是THP或hugetlb，这个计数将被å页的数é‡å¢žåŠ 。 + +3. THP_MIGRATION_SUCCESS: 一个THP被è¿ç§»è€Œæ²¡æœ‰è¢«åˆ†å‰²ã€‚ + +4. THP_MIGRATION_FAIL: 一个THPä¸èƒ½è¢«è¿ç§»ï¼Œä¹Ÿä¸èƒ½è¢«åˆ†å‰²ã€‚ + +5. THP_MIGRATION_SPLIT: 一个THP被è¿ç§»äº†ï¼Œä½†ä¸æ˜¯è¿™æ ·çš„：首先，这个THP必须被分割。 + 在拆分之åŽï¼Œå¯¹å®ƒçš„å页é¢è¿›è¡Œäº†è¿ç§»é‡è¯•ã€‚ + +THP_MIGRATION_* 事件也会更新相应的PGMIGRATE_SUCCESS或PGMIGRATE_FAIL事件。 +例如，一个THPè¿ç§»å¤±è´¥å°†å¯¼è‡´THP_MIGRATION_FAILå’ŒPGMIGRATE_FAILå¢žåŠ ã€‚ + +Christoph Lameter，2006å¹´5月8日。 + +Minchan Kim，2016å¹´3月28日。 diff --git a/Documentation/translations/zh_CN/vm/page_owner.rst b/Documentation/translations/zh_CN/vm/page_owner.rst index 9e951fabba9d..7bd740bc5bf4 100644 --- a/Documentation/translations/zh_CN/vm/page_owner.rst +++ b/Documentation/translations/zh_CN/vm/page_owner.rst @@ -96,21 +96,82 @@ page owner在默认情况下是ç¦ç”¨çš„ã€‚æ‰€ä»¥ï¼Œå¦‚æžœä½ æƒ³ä½¿ç”¨å®ƒï¼Œä½ é 默认情况下， ``page_owner_sort`` æ˜¯æ ¹æ®buf的时间æ¥æŽ’åºçš„ã€‚å¦‚æžœä½ æƒ³ 按buf的页数排åºï¼Œè¯·ä½¿ç”¨-må‚数。详细的å‚数是: - 基本函数: + 基本函数:: - Sort: + 排åº: -a 按内å˜åˆ†é…æ—¶é—´æŽ’åº -m 按总内å˜æŽ’åº -p 按pid排åºã€‚ -P 按tgid排åºã€‚ + -n 按任务命令å称排åºã€‚ -r 按内å˜é‡Šæ”¾æ—¶é—´æŽ’åºã€‚ -s æŒ‰å †æ ˆè·Ÿè¸ªæŽ’åºã€‚ -t 按时间排åºï¼ˆé»˜è®¤ï¼‰ã€‚ - - 其它函数: - - Cull: - -c é€šè¿‡æ¯”è¾ƒå †æ ˆè·Ÿè¸ªè€Œä¸æ˜¯æ€»å—æ¥è¿›è¡Œå‰”除。 - - Filter: + --sort <order> 指定排åºé¡ºåºã€‚排åºçš„è¯æ³•æ˜¯[+|-]key[,[+|-]key[,...]]。从 + **æ ‡å‡†æ ¼å¼æŒ‡å®šå™¨**那一节选择一个键。"+"是å¯é€‰çš„ï¼Œå› ä¸ºé»˜è®¤çš„æ–¹å‘是数å—或 + è¯æ³•çš„å¢žåŠ ã€‚å…许混åˆä½¿ç”¨ç¼©å†™å’Œå®Œæ•´æ ¼å¼çš„键。 + + 例å: + ./page_owner_sort <input> <output> --sort=n,+pid,-tgid + ./page_owner_sort <input> <output> --sort=at + + 其它函数:: + + 剔除: + --cull <rules> + 指定剔除规则。剔除的è¯æ³•æ˜¯key[,key[,...]]。从**æ ‡å‡†æ ¼å¼æŒ‡å®šå™¨** + 部分选择一个多å—æ¯é”®ã€‚ + <rules>是一个以逗å·åˆ†éš”的列表形å¼çš„å•ä¸€å‚数，它æ供了一ç§æŒ‡å®šå•ä¸ªå‰”除规则的 + 方法。 识别的关键å—在下é¢çš„**æ ‡å‡†æ ¼å¼æŒ‡å®šå™¨**部分有æ述。<规则>å¯ä»¥é€šè¿‡é”®çš„ + åºåˆ—k1,k2,...æ¥æŒ‡å®šï¼Œåœ¨ä¸‹é¢çš„æ ‡å‡†æŽ’åºé”®éƒ¨åˆ†æœ‰æ述。å…许混åˆä½¿ç”¨ç®€å†™å’Œå®Œæ•´å½¢ + å¼çš„键。 + + Examples: + ./page_owner_sort <input> <output> --cull=stacktrace + ./page_owner_sort <input> <output> --cull=st,pid,name + ./page_owner_sort <input> <output> --cull=n,f + + 过滤: -f 过滤掉内å˜å·²è¢«é‡Šæ”¾çš„å—çš„ä¿¡æ¯ã€‚ + + 选择: + --pid <pidlist> 按pid选择。这将选择进程IDå·å‡ºçŽ°åœ¨<pidlist>ä¸çš„å—。 + --tgid <tgidlist> 按tgid选择。这将选择其线程组IDå·å‡ºçŽ°åœ¨<tgidlist> + ä¸çš„å—。 + --name <cmdlist> 按任务命令å称选择。这将选择其任务命令å称出现在 + <cmdlist>ä¸çš„区å—。 + + <pidlist>, <tgidlist>, <cmdlist>是以逗å·åˆ†éš”的列表形å¼çš„å•ä¸ªå‚数， + 它æ供了一ç§æŒ‡å®šå•ä¸ªé€‰æ‹©è§„则的方法。 + + + 例å: + ./page_owner_sort <input> <output> --pid=1 + ./page_owner_sort <input> <output> --tgid=1,2,3 + ./page_owner_sort <input> <output> --name name1,name2 + +æ ‡å‡†æ ¼å¼æŒ‡å®šå™¨ +============== +:: + + --sort的选项: + + çŸé”® é•¿é”® æè¿° + p pid 进程ID + tg tgid 线程组ID + n name 任务命令å称 + st stacktrace 页é¢åˆ†é…çš„å †æ ˆè·Ÿè¸ª + T txt å—的全文 + ft free_ts 页é¢é‡Šæ”¾æ—¶çš„时间戳 + at alloc_ts 页é¢è¢«åˆ†é…时的时间戳 + ator allocator 页é¢çš„内å˜åˆ†é…器 + + --curl的选项: + + çŸé”® é•¿é”® æè¿° + p pid 进程ID + tg tgid 线程组ID + n name 任务命令å称 + f free 该页是å¦å·²ç»é‡Šæ”¾ + st stacktrace 页é¢åˆ†é…çš„å †æ ˆè·Ÿè¸ª + ator allocator 页é¢çš„内å˜åˆ†é…器 diff --git a/Documentation/translations/zh_CN/vm/vmalloced-kernel-stacks.rst b/Documentation/translations/zh_CN/vm/vmalloced-kernel-stacks.rst new file mode 100644 index 000000000000..ad23f274f6d7 --- /dev/null +++ b/Documentation/translations/zh_CN/vm/vmalloced-kernel-stacks.rst @@ -0,0 +1,133 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/vm/vmalloced-kernel-stacks.rst + +:翻译: + + å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯‘: + +==================== +支æŒè™šæ‹Ÿæ˜ å°„çš„å†…æ ¸æ ˆ +==================== + +:作者: Shuah Khan <skhan@linuxfoundation.org> + +.. contents:: :local: + +概览 +---- + +è¿™æ˜¯ä»‹ç» `è™šæ‹Ÿæ˜ å°„å†…æ ¸æ ˆåŠŸèƒ½ <https://lwn.net/Articles/694348/>` 的代ç +和原始补ä¸ç³»åˆ—çš„ä¿¡æ¯æ±‡æ€»ã€‚ + +简介 +---- + +å†…æ ¸å †æ ˆæº¢å‡ºé€šå¸¸éš¾ä»¥è°ƒè¯•ï¼Œå¹¶ä½¿å†…æ ¸å®¹æ˜“è¢«ï¼ˆæ¶æ„）利用。问题å¯èƒ½åœ¨ç¨åŽçš„时间出现，使其难以 +éš”ç¦»å’Œç©¶å…¶æ ¹æœ¬åŽŸå› ã€‚ + +带有ä¿æŠ¤é¡µçš„è™šæ‹Ÿæ˜ å°„å†…æ ¸å †æ ˆå¦‚æžœæº¢å‡ºï¼Œä¼šè¢«ç«‹å³æ•èŽ·ï¼Œè€Œä¸ä¼šæ”¾ä»»å…¶å¯¼è‡´éš¾ä»¥è¯Šæ–çš„æŸ +å。 + +HAVE_ARCH_VMAP_STACKå’ŒVMAP_STACKé…置选项能够支æŒå¸¦æœ‰ä¿æŠ¤é¡µçš„è™šæ‹Ÿæ˜ å°„å †æ ˆã€‚ +å½“å †æ ˆæº¢å‡ºæ—¶ï¼Œè¿™ä¸ªç‰¹æ€§ä¼šå¼•å‘å¯é 的异常。溢出åŽå †æ ˆè·Ÿè¸ªçš„å¯ç”¨æ€§ä»¥åŠå¯¹æº¢å‡ºæœ¬èº«çš„ +å“应å–决于架构。 + +.. note:: + 截至本文撰写时， arm64, powerpc, riscv, s390, um, å’Œ x86 支æŒVMAP_STACK。 + +HAVE_ARCH_VMAP_STACK +-------------------- + +能够支æŒè™šæ‹Ÿæ˜ å°„å†…æ ¸æ ˆçš„æž¶æž„åº”è¯¥å¯ç”¨è¿™ä¸ªboolé…置选项。è¦æ±‚是: + +- vmallocç©ºé—´å¿…é¡»å¤§åˆ°è¶³ä»¥å®¹çº³è®¸å¤šå†…æ ¸å †æ ˆã€‚è¿™å¯èƒ½æŽ’除了许多32ä½æž¶æž„。 +- vmallocç©ºé—´çš„å †æ ˆéœ€è¦å¯é 地工作。例如，如果vmapé¡µè¡¨æ˜¯æŒ‰éœ€åˆ›å»ºçš„ï¼Œå½“å †æ ˆæŒ‡å‘ + 具有未填充页表的虚拟地å€æ—¶ï¼Œè¿™ç§æœºåˆ¶éœ€è¦å·¥ä½œï¼Œæˆ–者架构代ç （switch_to()å’Œ + switch_mm()，很å¯èƒ½ï¼‰éœ€è¦ç¡®ä¿å †æ ˆçš„页表项在å¯èƒ½æœªå¡«å……çš„å †æ ˆä¸Šè¿è¡Œä¹‹å‰å·²ç»å¡« + 充。 +- å¦‚æžœå †æ ˆæº¢å‡ºåˆ°ä¸€ä¸ªä¿æŠ¤é¡µï¼Œå°±åº”该å‘生一些åˆç†çš„事情。“åˆç†â€çš„定义是çµæ´»çš„，但 + 在没有记录任何东西的情况下立å³é‡å¯æ˜¯ä¸å‹å¥½çš„。 + +VMAP_STACK +---------- + +VMAP_STACK boolé…置选项在å¯ç”¨æ—¶åˆ†é…è™šæ‹Ÿæ˜ å°„çš„ä»»åŠ¡æ ˆã€‚è¿™ä¸ªé€‰é¡¹ä¾èµ–于 +HAVE_ARCH_VMAP_STACK。 + +- å¦‚æžœä½ æƒ³ä½¿ç”¨å¸¦æœ‰ä¿æŠ¤é¡µçš„è™šæ‹Ÿæ˜ å°„çš„å†…æ ¸å †æ ˆï¼Œè¯·å¯ç”¨è¯¥é€‰é¡¹ã€‚è¿™å°†å¯¼è‡´å†…æ ¸æ ˆæº¢å‡º + 被立å³æ•èŽ·ï¼Œè€Œä¸æ˜¯éš¾ä»¥è¯Šæ–çš„æŸå。 + +.. note:: + + 使用KASAN的这个功能需è¦æž¶æž„支æŒç”¨çœŸå®žçš„å½±å内å˜æ¥æ”¯æŒè™šæ‹Ÿæ˜ 射，并且 + å¿…é¡»å¯ç”¨KASAN_VMALLOC。 + +.. note:: + + å¯ç”¨VMAP_STACKæ—¶ï¼Œæ— æ³•åœ¨å †æ ˆåˆ†é…çš„æ•°æ®ä¸Šè¿è¡ŒDMA。 + +å†…æ ¸é…置选项和ä¾èµ–性ä¸æ–å˜åŒ–。请å‚考最新的代ç 库: + +`Kconfig <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/Kconfig>` + +分é…方法 +-------- + +å½“ä¸€ä¸ªæ–°çš„å†…æ ¸çº¿ç¨‹è¢«åˆ›å»ºæ—¶ï¼Œçº¿ç¨‹å †æ ˆæ˜¯ç”±é¡µçº§åˆ†é…器分é…的虚拟连ç»çš„内å˜é¡µç»„æˆã€‚è¿™ +些页é¢è¢«æ˜ 射到有PAGE_KERNELä¿æŠ¤çš„è¿žç»çš„å†…æ ¸è™šæ‹Ÿç©ºé—´ã€‚ + +alloc_thread_stack_node()调用__vmalloc_node_range()æ¥åˆ†é…带有PAGE_KERNEL +ä¿æŠ¤çš„æ ˆã€‚ + +- 分é…çš„å †æ ˆè¢«ç¼“å˜èµ·æ¥ï¼Œä»¥åŽä¼šè¢«æ–°çš„线程é‡ç”¨ï¼Œæ‰€ä»¥åœ¨åˆ†é…/é‡Šæ”¾å †æ ˆç»™ä»»åŠ¡æ—¶ï¼Œè¦æ‰‹åŠ¨ + 进行memcgæ ¸ç®—ã€‚å› æ¤ï¼Œ__vmalloc_node_range被调用时没有__GFP_ACCOUNT。 +- vm_struct被缓å˜èµ·æ¥ï¼Œä»¥ä¾¿èƒ½å¤Ÿæ‰¾åˆ°åœ¨ä¸æ–上下文ä¸å¯åŠ¨çš„空闲线程。 free_thread_stack() + å¯ä»¥åœ¨ä¸æ–上下文ä¸è°ƒç”¨ã€‚ +- 在arm64上，所有VMAPçš„å †æ ˆéƒ½éœ€è¦æœ‰ç›¸åŒçš„对é½æ–¹å¼ï¼Œä»¥ç¡®ä¿VMAPçš„å †æ ˆæº¢å‡ºæ£€æµ‹æ£å¸¸ + 工作。架构特定的vmapå †æ ˆåˆ†é…器照顾到了这个细节。 +- 这并ä¸æ¶‰åŠä¸æ–å †æ ˆ--å‚è€ƒåŽŸå§‹è¡¥ä¸ + +çº¿ç¨‹æ ˆåˆ†é…是由clone()ã€fork()ã€vfork()ã€kernel_thread()通过kernel_clone() +å¯åŠ¨çš„。留点æ示在这，以便æœç´¢ä»£ç åº“ï¼Œäº†è§£çº¿ç¨‹æ ˆä½•æ—¶ä»¥åŠå¦‚何分é…。 + +大é‡çš„代ç 是在: +`kernel/fork.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/kernel/fork.c>`. + +task_structä¸çš„stack_vm_area指针å¯ä»¥è·Ÿè¸ªè™šæ‹Ÿåˆ†é…çš„å †æ ˆï¼Œä¸€ä¸ªéžç©ºçš„stack_vm_area +指针å¯ä»¥è¡¨æ˜Žè™šæ‹Ÿæ˜ å°„çš„å†…æ ¸å †æ ˆå·²ç»å¯ç”¨ã€‚ + +:: + + struct vm_struct *stack_vm_area; + +å †æ ˆæº¢å‡ºå¤„ç† +------------ + +å‰å®ˆæŠ¤é¡µå’ŒåŽå®ˆæŠ¤é¡µæœ‰åŠ©äºŽæ£€æµ‹å †æ ˆæº¢å‡ºã€‚å½“å †æ ˆæº¢å‡ºåˆ°å®ˆæŠ¤é¡µæ—¶ï¼Œå¤„ç†ç¨‹åºå¿…é¡»å°å¿ƒä¸è¦å† +æ¬¡æº¢å‡ºå †æ ˆã€‚å½“å¤„ç†ç¨‹åºè¢«è°ƒç”¨æ—¶ï¼Œå¾ˆå¯èƒ½åªç•™ä¸‹å¾ˆå°‘çš„å †æ ˆç©ºé—´ã€‚ + +在x86上，这是通过处ç†è¡¨æ˜Žå†…æ ¸å †æ ˆæº¢å‡ºçš„åŒå¼‚å¸¸å †æ ˆçš„ç¼ºé¡µå¼‚å¸¸æ¥å®žçŽ°çš„。 + +用守护页测试VMAPåˆ†é… +-------------------- + +我们如何确ä¿VMAP_STACK在分é…时确实有å‰å®ˆæŠ¤é¡µå’ŒåŽå®ˆæŠ¤é¡µçš„ä¿æŠ¤ï¼Ÿä¸‹é¢çš„ lkdtm 测试 +å¯ä»¥å¸®åŠ©æ£€æµ‹ä»»ä½•å›žå½’。 + +:: + + void lkdtm_STACK_GUARD_PAGE_LEADING() + void lkdtm_STACK_GUARD_PAGE_TRAILING() + +结论 +---- + +- vmallocedå †æ ˆçš„percpu缓å˜ä¼¼ä¹Žæ¯”é«˜é˜¶å †æ ˆåˆ†é…è¦å¿«ä¸€äº›ï¼Œè‡³å°‘在缓å˜å‘½ä¸æ—¶æ˜¯è¿™æ ·ã€‚ +- THREAD_INFO_IN_TASK完全摆脱了arch-specific thread_info，并简å•åœ°å°† + thread_info（仅包å«æ ‡å¿—）和'int cpu'嵌入task_structä¸ã€‚ +- 一旦任务æ»äº¡ï¼Œçº¿ç¨‹æ ˆå°±å¯ä»¥è¢«é‡Šæ”¾ï¼ˆæ— 需ç‰å¾…RCU），然åŽï¼Œå¦‚果使用vmappedæ ˆï¼Œå°± + å¯ä»¥å°†æ•´ä¸ªæ ˆç¼“å˜èµ·æ¥ï¼Œä»¥ä¾¿åœ¨åŒä¸€cpu上é‡å¤ä½¿ç”¨ã€‚ diff --git a/Documentation/translations/zh_CN/vm/zsmalloc.rst b/Documentation/translations/zh_CN/vm/zsmalloc.rst index 29e9c70a8eb6..45a9b7ab2a51 100644 --- a/Documentation/translations/zh_CN/vm/zsmalloc.rst +++ b/Documentation/translations/zh_CN/vm/zsmalloc.rst @@ -1,4 +1,4 @@ -:Original: Documentation/vm/zs_malloc.rst +:Original: Documentation/vm/zsmalloc.rst :翻译: diff --git a/Documentation/translations/zh_TW/process/5.Posting.rst b/Documentation/translations/zh_TW/process/5.Posting.rst index 5578bca403e6..280a8832ecc0 100644 --- a/Documentation/translations/zh_TW/process/5.Posting.rst +++ b/Documentation/translations/zh_TW/process/5.Posting.rst @@ -22,8 +22,7 @@ å…§æ ¸é–‹ç™¼ç¤¾å€å·²ç¶“發展出一套用於發布補ä¸çš„約定和éŽç¨‹ï¼›éµå¾ªé€™äº›ç´„定和éŽç¨‹å°‡ä½¿ åƒèˆ‡å…¶ä¸çš„æ¯å€‹äººçš„ç”Ÿæ´»æ›´åŠ è¼•é¬†ã€‚æœ¬æ–‡æª”è©¦åœ–æè¿°é€™äº›ç´„å®šçš„éƒ¨åˆ†ç´°ç¯€ï¼›æ›´å¤šä¿¡æ¯ ä¹Ÿå¯åœ¨ä»¥ä¸‹æ–‡æª”ä¸æ‰¾åˆ° -:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>`， -:ref:`Documentation/translations/zh_TW/process/submitting-drivers.rst <tw_submittingdrivers>` +:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` å’Œ :ref:`Documentation/translations/zh_TW/process/submit-checklist.rst <tw_submitchecklist>`。 何時郵寄 diff --git a/Documentation/translations/zh_TW/process/8.Conclusion.rst b/Documentation/translations/zh_TW/process/8.Conclusion.rst index 7572b17667d9..044fcc118bef 100644 --- a/Documentation/translations/zh_TW/process/8.Conclusion.rst +++ b/Documentation/translations/zh_TW/process/8.Conclusion.rst @@ -22,7 +22,6 @@ :ref:`Documentation/translations/zh_TW/process/howto.rst <tw_process_howto>` 文件是一個é‡è¦çš„起點； :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` -å’Œ :ref:`Documentation/translations/zh_TW/process/submitting-drivers.rst <tw_submittingdrivers>` ä¹Ÿæ˜¯æ‰€æœ‰å…§æ ¸é–‹ç™¼äººå“¡éƒ½æ‡‰è©²é–±è®€çš„å…§å®¹ã€‚è¨±å¤šå…§éƒ¨å…§æ ¸API都是使用kerneldoc機制 記錄的；「make htmldocsã€æˆ–「make pdfdocsã€å¯ç”¨æ–¼ä»¥HTML或PDFæ ¼å¼ç”Ÿæˆé€™äº›æ–‡æª” （儘管æŸäº›ç™¼è¡Œç‰ˆæ供的tex版本會é‡åˆ°å…§éƒ¨é™åˆ¶ï¼Œç„¡æ³•æ£ç¢ºè™•ç†æ–‡æª”）。 diff --git a/Documentation/translations/zh_TW/process/howto.rst b/Documentation/translations/zh_TW/process/howto.rst index 2043691b92e3..68ae4411285b 100644 --- a/Documentation/translations/zh_TW/process/howto.rst +++ b/Documentation/translations/zh_TW/process/howto.rst @@ -99,7 +99,6 @@ Linuxå…§æ ¸ä»£ç¢¼ä¸åŒ…å«æœ‰å¤§é‡çš„文檔。這些文檔å°æ–¼å¸ç¿’如何與 的代碼。 :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` - :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` 這兩份文檔明確æ述如何創建和發é€è£œä¸ï¼Œå…¶ä¸åŒ…括（但ä¸åƒ…é™æ–¼)： - 郵件內容 diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst index ec7ad14bfd13..c5c59b4fd595 100644 --- a/Documentation/translations/zh_TW/process/index.rst +++ b/Documentation/translations/zh_TW/process/index.rst @@ -43,7 +43,6 @@ .. toctree:: :maxdepth: 1 - submitting-drivers submit-checklist stable-api-nonsense stable-kernel-rules diff --git a/Documentation/translations/zh_TW/process/submitting-drivers.rst b/Documentation/translations/zh_TW/process/submitting-drivers.rst deleted file mode 100644 index 2fdd742318ba..000000000000 --- a/Documentation/translations/zh_TW/process/submitting-drivers.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. _tw_submittingdrivers: - -.. include:: ../disclaimer-zh_TW.rst - -:Original: :ref:`Documentation/process/submitting-drivers.rst - <submittingdrivers>` - -如果想評論或更新本文的內容，請直接è¯ç¹«åŽŸæ–‡æª”çš„ç¶è·è€…ã€‚å¦‚æžœä½ ä½¿ç”¨è‹±æ–‡ -交æµæœ‰å›°é›£çš„話，也å¯ä»¥å‘ä¸æ–‡ç‰ˆç¶è·è€…求助。如果本翻è¯æ›´æ–°ä¸åŠæ™‚或者翻 -è¯å˜åœ¨å•é¡Œï¼Œè«‹è¯ç¹«ä¸æ–‡ç‰ˆç¶è·è€…:: - - ä¸æ–‡ç‰ˆç¶è·è€…： æŽé™½ Li Yang <leoyang.li@nxp.com> - ä¸æ–‡ç‰ˆç¿»è¯è€…： æŽé™½ Li Yang <leoyang.li@nxp.com> - ä¸æ–‡ç‰ˆæ ¡è¯è€…： é™³ç¦ Maggie Chen <chenqi@beyondsoft.com> - çŽ‹è° Wang Cong <xiyou.wangcong@gmail.com> - å¼µå· Zhang Wei <wezhang@outlook.com> - 胡皓文 Hu Haowen <src.res@email.cn> - -å¦‚ä½•å‘ Linux å…§æ ¸æäº¤é©…å‹•ç¨‹åº -============================= - -這篇文檔將會解釋如何å‘ä¸åŒçš„å…§æ ¸æºç¢¼æ¨¹æ交è¨å‚™é©…動程åºã€‚請注æ„ï¼Œå¦‚æžœä½ æ„Ÿ -興趣的是顯å¡é©…動程åºï¼Œä½ ä¹Ÿè¨±æ‡‰è©²è¨ªå• XFree86 é …ç›®(https://www.xfree86.org/) -å’Œï¼æˆ– X.org é …ç›® (https://x.org)。 - -å¦è«‹åƒé–± Documentation/translations/zh_TW/process/submitting-patches.rst 文檔。 - - -分é…è¨å‚™è™Ÿ ----------- - -å¡Šè¨å‚™å’Œå—符è¨å‚™çš„主è¨å‚™è™Ÿèˆ‡å¾žè¨å‚™è™Ÿæ˜¯ç”± Linux 命å編號分é…æ¬Šå¨ LANANA（ -ç¾åœ¨æ˜¯ Torben Mathiasenï¼‰è² è²¬åˆ†é…。申請的網å€æ˜¯ https://www.lanana.org/。 -å³ä½¿ä¸æº–å‚™æ交到主æµå…§æ ¸çš„è¨å‚™é©…動也需è¦åœ¨é€™è£¡åˆ†é…è¨å‚™è™Ÿã€‚有關詳細信æ¯ï¼Œ -è«‹åƒé–± Documentation/admin-guide/devices.rst。 - -å¦‚æžœä½ ä½¿ç”¨çš„ä¸æ˜¯å·²ç¶“分é…çš„è¨å‚™è™Ÿï¼Œé‚£éº¼ç•¶ä½ æ交è¨å‚™é©…動的時候，它將會被強 -制分é…一個新的è¨å‚™è™Ÿï¼Œå³ä¾¿é€™å€‹è¨å‚™è™Ÿå’Œä½ 之å‰ç™¼çµ¦å®¢æˆ¶çš„截然ä¸åŒã€‚ - -è¨å‚™é©…å‹•çš„æ交å°è±¡ ------------------- - -Linux 2.0: - æ¤å…§æ ¸æºç¢¼æ¨¹ä¸æŽ¥å—新的驅動程åºã€‚ - -Linux 2.2: - æ¤å…§æ ¸æºç¢¼æ¨¹ä¸æŽ¥å—新的驅動程åºã€‚ - -Linux 2.4: - å¦‚æžœæ‰€å±¬çš„ä»£ç¢¼é ˜åŸŸåœ¨å…§æ ¸çš„ MAINTAINERS 文件ä¸åˆ—有一個總ç¶è·è€…， - 那麼請將驅動程åºæ交給他。如果æ¤ç¶è·è€…æ²’æœ‰å›žæ‡‰æˆ–è€…ä½ æ‰¾ä¸åˆ°æ°ç•¶çš„ - ç¶è·è€…，那麼請è¯ç¹« Willy Tarreau <w@1wt.eu>。 - -Linux 2.6: - 除了éµå¾ªå’Œ 2.4 ç‰ˆå…§æ ¸åŒæ¨£çš„è¦å‰‡å¤–ï¼Œä½ é‚„éœ€è¦åœ¨ linux-kernel 郵件 - 列表上跟蹤最新的 API è®ŠåŒ–ã€‚å‘ Linux 2.6 å…§æ ¸æäº¤é©…å‹•çš„é ‚ç´šè¯ç¹«äºº - 是 Andrew Morton <akpm@linux-foundation.org>。 - -決定è¨å‚™é©…動能å¦è¢«æŽ¥å—çš„æ¢ä»¶ ----------------------------- - -許å¯ï¼š ä»£ç¢¼å¿…é ˆä½¿ç”¨ GNU 通用公開許å¯è‰ (GPL) æ交給 Linux，但是 - 我們並ä¸è¦æ±‚ GPL 是唯一的許å¯ã€‚ä½ æˆ–è¨±æœƒå¸Œæœ›åŒæ™‚使用多種 - 許å¯è‰ç™¼å¸ƒï¼Œå¦‚果希望驅動程åºå¯ä»¥è¢«å…¶ä»–é–‹æºç¤¾å€ï¼ˆæ¯”如BSD） - 使用。請åƒè€ƒ include/linux/module.h 文件ä¸æ‰€åˆ—出的å¯è¢« - 接å—å…±å˜çš„許å¯ã€‚ - -版權： ç‰ˆæ¬Šæ‰€æœ‰è€…å¿…é ˆåŒæ„使用 GPL 許å¯ã€‚最好æ交者和版權所有者 - 是相åŒå€‹äººæˆ–實體。å¦å‰‡ï¼Œå¿…需列出授權使用 GPL 的版權所有 - 人或實體，以備驗è‰ä¹‹éœ€ã€‚ - -接å£ï¼š å¦‚æžœä½ çš„é©…å‹•ç¨‹åºä½¿ç”¨ç¾æˆçš„接å£ä¸¦ä¸”和其他åŒé¡žçš„驅動程åºè¡Œ - 爲相似，而ä¸æ˜¯åŽ»ç™¼æ˜Žç„¡è¬‚的新接å£ï¼Œé‚£éº¼å®ƒå°‡æœƒæ›´å®¹æ˜“被接å—。 - å¦‚æžœä½ éœ€è¦ä¸€å€‹ Linux å’Œ NT 的通用驅動接å£ï¼Œé‚£éº¼è«‹åœ¨ç”¨ - 戶空間實ç¾å®ƒã€‚ - -代碼： 請使用 Documentation/process/coding-style.rst ä¸æ‰€æè¿°çš„ Linux 代碼風 - æ ¼ã€‚å¦‚æžœä½ çš„æŸäº›ä»£ç¢¼æ®µï¼ˆä¾‹å¦‚那些與 Windows 驅動程åºåŒ…å…± - 享的代碼段）需è¦ä½¿ç”¨å…¶ä»–æ ¼å¼ï¼Œè€Œä½ å»åªå¸Œæœ›ç¶è·ä¸€ä»½ä»£ç¢¼ï¼Œ - 那麼請將它們很好地å€åˆ†å‡ºä¾†ï¼Œä¸¦ä¸”è¨»æ˜ŽåŽŸå› ã€‚ - -å¯ç§»æ¤æ€§ï¼š 請注æ„，指é‡ä¸¦ä¸æ°¸é 是 32 ä½çš„，ä¸æ˜¯æ‰€æœ‰çš„è¨ˆç®—æ©Ÿéƒ½ä½¿ç”¨å° - å°¾æ¨¡å¼ (little endian) å˜å„²æ•¸æ“šï¼Œä¸æ˜¯æ‰€æœ‰çš„人都æ“有浮點 - 單元，ä¸è¦éš¨ä¾¿åœ¨ä½ 的驅動程åºé‡ŒåµŒå…¥ x86 彙編指令。åªèƒ½åœ¨ - x86 上é‹è¡Œçš„驅動程åºä¸€èˆ¬æ˜¯ä¸å—æ¡è¿Žçš„ã€‚é›–ç„¶ä½ å¯èƒ½åªæœ‰ x86 - 硬體，很難測試驅動程åºåœ¨å…¶ä»–å¹³å°ä¸Šæ˜¯å¦å¯ç”¨ï¼Œä½†æ˜¯ç¢ºä¿ä»£ç¢¼ - å¯ä»¥è¢«è¼•é¬†åœ°ç§»æ¤å»æ˜¯å¾ˆç°¡å–®çš„。 - -清晰度： åšåˆ°æ‰€æœ‰äººéƒ½èƒ½ä¿®è£œé€™å€‹é©…動程åºå°‡æœƒå¾ˆæœ‰å¥½è™•ï¼Œå› çˆ²é€™æ¨£ä½ å°‡ - 會直接收到修復的補ä¸è€Œä¸æ˜¯ bug å ±å‘Šã€‚å¦‚æžœä½ æ交一個試圖 - éš±è—硬體工作機ç†çš„驅動程åºï¼Œé‚£éº¼å®ƒå°‡æœƒè¢«æ‰”進廢紙ç°ã€‚ - -é›»æºç®¡ç†ï¼š å› çˆ² Linux æ£åœ¨è¢«å¾ˆå¤šè¡Œå‹•è£ç½®å’Œæ¡Œé¢ç³»çµ±ä½¿ç”¨ï¼Œæ‰€ä»¥ä½ çš„é©… - 動程åºä¹Ÿå¾ˆæœ‰å¯èƒ½è¢«ä½¿ç”¨åœ¨é€™äº›è¨å‚™ä¸Šã€‚它應該支æŒæœ€åŸºæœ¬çš„é›» - æºç®¡ç†ï¼Œå³åœ¨éœ€è¦çš„情æ³ä¸‹å¯¦ç¾ç³»çµ±ç´šä¼‘çœ å’Œå–šé†’è¦ç”¨åˆ°çš„ - .suspend å’Œ .resume å‡½æ•¸ã€‚ä½ æ‡‰è©²æª¢æŸ¥ä½ çš„é©…å‹•ç¨‹åºæ˜¯å¦èƒ½æ£ - 確地處ç†ä¼‘çœ èˆ‡å–šé†’ï¼Œå¦‚æžœå¯¦åœ¨ç„¡æ³•ç¢ºèªï¼Œè«‹è‡³å°‘把 .suspend - 函數定義æˆè¿”回 -ENOSYS（功能未實ç¾ï¼‰éŒ¯èª¤ã€‚ä½ é‚„æ‡‰è©²å˜—è©¦ç¢º - ä¿ä½ 的驅動在什麼都ä¸ä¹¾çš„情æ³ä¸‹å°‡è€—é›»é™åˆ°æœ€ä½Žã€‚è¦ç²å¾—é©…å‹• - 程åºæ¸¬è©¦çš„指導，請åƒé–± - Documentation/power/drivers-testing.rst。有關驅動程åºé›» - æºç®¡ç†å•é¡Œç›¸å°å…¨é¢çš„概述，請åƒé–± - Documentation/driver-api/pm/devices.rst。 - -管ç†ï¼š 如果一個驅動程åºçš„作者還在進行有效的ç¶è·ï¼Œé‚£éº¼é€šå¸¸é™¤äº†é‚£ - 些明顯æ£ç¢ºä¸”ä¸éœ€è¦ä»»ä½•æª¢æŸ¥çš„補ä¸ä»¥å¤–，其他所有的補ä¸éƒ½æœƒ - è¢«è½‰ç™¼çµ¦ä½œè€…ã€‚å¦‚æžœä½ å¸Œæœ›æˆçˆ²é©…動程åºçš„è¯ç¹«äººå’Œæ›´æ–°è€…，最 - 好在代碼注釋ä¸å¯«æ˜Žä¸¦ä¸”在 MAINTAINERS 文件ä¸åŠ 入這個驅動 - 程åºçš„æ¢ç›®ã€‚ - -ä¸å½±éŸ¿è¨å‚™é©…動能å¦è¢«æŽ¥å—çš„æ¢ä»¶ ------------------------------- - -供應商： 由硬體供應商來ç¶è·é©…動程åºé€šå¸¸æ˜¯ä¸€ä»¶å¥½äº‹ã€‚ä¸éŽï¼Œå¦‚æžœæºç¢¼ - 樹里已經有其他人æ供了å¯ç©©å®šå·¥ä½œçš„驅動程åºï¼Œé‚£éº¼è«‹ä¸è¦æœŸ - 望「我是供應商ã€æœƒæˆçˆ²å…§æ ¸æ”¹ç”¨ä½ 的驅動程åºçš„ç†ç”±ã€‚ç†æƒ³çš„情 - æ³æ˜¯ï¼šä¾›æ‡‰å•†èˆ‡ç¾æœ‰é©…動程åºçš„作者åˆä½œï¼Œæ§‹å»ºä¸€å€‹çµ±ä¸€å®Œç¾Žçš„ - 驅動程åºã€‚ - -作者： 驅動程åºæ˜¯ç”±å¤§çš„ Linux å…¬å¸ç ”ç™¼é‚„æ˜¯ç”±ä½ å€‹äººç·¨å¯«ï¼Œä¸¦ä¸å½± - 響其是å¦èƒ½è¢«å…§æ ¸æŽ¥å—。沒有人å°å…§æ ¸æºç¢¼æ¨¹äº«æœ‰ç‰¹æ¬Šã€‚åªè¦ä½ - å……åˆ†äº†è§£å…§æ ¸ç¤¾å€ï¼Œä½ 就會發ç¾é€™ä¸€é»žã€‚ - - -資æºåˆ—表 --------- - -Linux å…§æ ¸ä¸»æºç¢¼æ¨¹ï¼š - ftp.??.kernel.org:/pub/linux/kernel/... - ?? == ä½ çš„åœ‹å®¶ä»£ç¢¼ï¼Œä¾‹å¦‚ "cn"ã€"us"ã€"uk"ã€"fr" ç‰ç‰ - -Linux å…§æ ¸éƒµä»¶åˆ—è¡¨ï¼š - linux-kernel@vger.kernel.org - [å¯é€šéŽå‘majordomo@vger.kernel.org發郵件來訂閱] - -Linux è¨å‚™é©…動程åºï¼Œç¬¬ä¸‰ç‰ˆï¼ˆæŽ¢è¨Ž 2.6.10 ç‰ˆå…§æ ¸ï¼‰ï¼š - https://lwn.net/Kernel/LDD3/ （å…費版） - -LWN.net: - æ¯å‘¨å…§æ ¸é–‹ç™¼æ´»å‹•æ‘˜è¦ - https://lwn.net/ - - 2.6 ç‰ˆä¸ API 的變更： - - https://lwn.net/Articles/2.6-kernel-api/ - - å°‡èˆŠç‰ˆå…§æ ¸çš„é©…å‹•ç¨‹åºç§»æ¤åˆ° 2.6 版： - - https://lwn.net/Articles/driver-porting/ - -å…§æ ¸æ–°æ‰‹(KernelNewbies): - çˆ²æ–°çš„å…§æ ¸é–‹ç™¼è€…æ供文檔和幫助 - https://kernelnewbies.org/ - -Linux USBé …ç›®ï¼š - http://www.linux-usb.org/ - -å¯«å…§æ ¸é©…å‹•çš„ã€Œä¸è¦ã€ï¼ˆArjan van de Ven著）: - http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf - -å…§æ ¸æ¸…æ½”å·¥ (Kernel Janitor): - https://kernelnewbies.org/KernelJanitors - diff --git a/Documentation/translations/zh_TW/process/submitting-patches.rst b/Documentation/translations/zh_TW/process/submitting-patches.rst index c4fd48f5bd8b..3f77ef5d48a0 100644 --- a/Documentation/translations/zh_TW/process/submitting-patches.rst +++ b/Documentation/translations/zh_TW/process/submitting-patches.rst @@ -26,9 +26,7 @@ 以下文檔å«æœ‰å¤§é‡ç°¡æ½”的建è°ï¼Œ 具體請見： :ref:`Documentation/process <development_process_main>` åŒæ¨£ï¼Œ:ref:`Documentation/translations/zh_TW/process/submit-checklist.rst <tw_submitchecklist>` -給出在æ交代碼å‰éœ€è¦æª¢æŸ¥çš„é …ç›®çš„åˆ—è¡¨ã€‚å¦‚æžœä½ åœ¨æ交一個驅動程åºï¼Œé‚£éº¼ -åŒæ™‚閱讀一下: -:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` +給出在æ交代碼å‰éœ€è¦æª¢æŸ¥çš„é …ç›®çš„åˆ—è¡¨ã€‚ å…¶ä¸è¨±å¤šæ¥é©Ÿæ述了Git版本控制系統的默èªè¡Œçˆ²ï¼›å¦‚果您使用Git來準備補ä¸ï¼Œ 您將發ç¾å®ƒçˆ²æ‚¨å®Œæˆçš„大部分機械工作，儘管您ä»ç„¶éœ€è¦æº–備和記錄一組åˆç†çš„ diff --git a/Documentation/virt/hyperv/clocks.rst b/Documentation/virt/hyperv/clocks.rst new file mode 100644 index 000000000000..2da2879fad52 --- /dev/null +++ b/Documentation/virt/hyperv/clocks.rst @@ -0,0 +1,73 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Clocks and Timers +================= + +arm64 +----- +On arm64, Hyper-V virtualizes the ARMv8 architectural system counter +and timer. Guest VMs use this virtualized hardware as the Linux +clocksource and clockevents via the standard arm_arch_timer.c +driver, just as they would on bare metal. Linux vDSO support for the +architectural system counter is functional in guest VMs on Hyper-V. +While Hyper-V also provides a synthetic system clock and four synthetic +per-CPU timers as described in the TLFS, they are not used by the +Linux kernel in a Hyper-V guest on arm64. However, older versions +of Hyper-V for arm64 only partially virtualize the ARMv8 +architectural timer, such that the timer does not generate +interrupts in the VM. Because of this limitation, running current +Linux kernel versions on these older Hyper-V versions requires an +out-of-tree patch to use the Hyper-V synthetic clocks/timers instead. + +x86/x64 +------- +On x86/x64, Hyper-V provides guest VMs with a synthetic system clock +and four synthetic per-CPU timers as described in the TLFS. Hyper-V +also provides access to the virtualized TSC via the RDTSC and +related instructions. These TSC instructions do not trap to +the hypervisor and so provide excellent performance in a VM. +Hyper-V performs TSC calibration, and provides the TSC frequency +to the guest VM via a synthetic MSR. Hyper-V initialization code +in Linux reads this MSR to get the frequency, so it skips TSC +calibration and sets tsc_reliable. Hyper-V provides virtualized +versions of the PIT (in Hyper-V Generation 1 VMs only), local +APIC timer, and RTC. Hyper-V does not provide a virtualized HPET in +guest VMs. + +The Hyper-V synthetic system clock can be read via a synthetic MSR, +but this access traps to the hypervisor. As a faster alternative, +the guest can configure a memory page to be shared between the guest +and the hypervisor. Hyper-V populates this memory page with a +64-bit scale value and offset value. To read the synthetic clock +value, the guest reads the TSC and then applies the scale and offset +as described in the Hyper-V TLFS. The resulting value advances +at a constant 10 MHz frequency. In the case of a live migration +to a host with a different TSC frequency, Hyper-V adjusts the +scale and offset values in the shared page so that the 10 MHz +frequency is maintained. + +Starting with Windows Server 2022 Hyper-V, Hyper-V uses hardware +support for TSC frequency scaling to enable live migration of VMs +across Hyper-V hosts where the TSC frequency may be different. +When a Linux guest detects that this Hyper-V functionality is +available, it prefers to use Linux's standard TSC-based clocksource. +Otherwise, it uses the clocksource for the Hyper-V synthetic system +clock implemented via the shared page (identified as +"hyperv_clocksource_tsc_page"). + +The Hyper-V synthetic system clock is available to user space via +vDSO, and gettimeofday() and related system calls can execute +entirely in user space. The vDSO is implemented by mapping the +shared page with scale and offset values into user space. User +space code performs the same algorithm of reading the TSC and +appying the scale and offset to get the constant 10 MHz clock. + +Linux clockevents are based on Hyper-V synthetic timer 0. While +Hyper-V offers 4 synthetic timers for each CPU, Linux only uses +timer 0. Interrupts from stimer0 are recorded on the "HVS" line in +/proc/interrupts. Clockevents based on the virtualized PIT and +local APIC timer also work, but the Hyper-V synthetic timer is +preferred. + +The driver for the Hyper-V synthetic system clock and timers is +drivers/clocksource/hyperv_timer.c. diff --git a/Documentation/virt/hyperv/index.rst b/Documentation/virt/hyperv/index.rst new file mode 100644 index 000000000000..4a7a1b738bbe --- /dev/null +++ b/Documentation/virt/hyperv/index.rst @@ -0,0 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================== +Hyper-V Enlightenments +====================== + +.. toctree:: + :maxdepth: 1 + + overview + vmbus + clocks diff --git a/Documentation/virt/hyperv/overview.rst b/Documentation/virt/hyperv/overview.rst new file mode 100644 index 000000000000..cd493332c88a --- /dev/null +++ b/Documentation/virt/hyperv/overview.rst @@ -0,0 +1,207 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Overview +======== +The Linux kernel contains a variety of code for running as a fully +enlightened guest on Microsoft's Hyper-V hypervisor. Hyper-V +consists primarily of a bare-metal hypervisor plus a virtual machine +management service running in the parent partition (roughly +equivalent to KVM and QEMU, for example). Guest VMs run in child +partitions. In this documentation, references to Hyper-V usually +encompass both the hypervisor and the VMM service without making a +distinction about which functionality is provided by which +component. + +Hyper-V runs on x86/x64 and arm64 architectures, and Linux guests +are supported on both. The functionality and behavior of Hyper-V is +generally the same on both architectures unless noted otherwise. + +Linux Guest Communication with Hyper-V +-------------------------------------- +Linux guests communicate with Hyper-V in four different ways: + +* Implicit traps: As defined by the x86/x64 or arm64 architecture, + some guest actions trap to Hyper-V. Hyper-V emulates the action and + returns control to the guest. This behavior is generally invisible + to the Linux kernel. + +* Explicit hypercalls: Linux makes an explicit function call to + Hyper-V, passing parameters. Hyper-V performs the requested action + and returns control to the caller. Parameters are passed in + processor registers or in memory shared between the Linux guest and + Hyper-V. On x86/x64, hypercalls use a Hyper-V specific calling + sequence. On arm64, hypercalls use the ARM standard SMCCC calling + sequence. + +* Synthetic register access: Hyper-V implements a variety of + synthetic registers. On x86/x64 these registers appear as MSRs in + the guest, and the Linux kernel can read or write these MSRs using + the normal mechanisms defined by the x86/x64 architecture. On + arm64, these synthetic registers must be accessed using explicit + hypercalls. + +* VMbus: VMbus is a higher-level software construct that is built on + the other 3 mechanisms. It is a message passing interface between + the Hyper-V host and the Linux guest. It uses memory that is shared + between Hyper-V and the guest, along with various signaling + mechanisms. + +The first three communication mechanisms are documented in the +`Hyper-V Top Level Functional Spec (TLFS)`_. The TLFS describes +general Hyper-V functionality and provides details on the hypercalls +and synthetic registers. The TLFS is currently written for the +x86/x64 architecture only. + +.. _Hyper-V Top Level Functional Spec (TLFS): https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/tlfs/tlfs + +VMbus is not documented. This documentation provides a high-level +overview of VMbus and how it works, but the details can be discerned +only from the code. + +Sharing Memory +-------------- +Many aspects are communication between Hyper-V and Linux are based +on sharing memory. Such sharing is generally accomplished as +follows: + +* Linux allocates memory from its physical address space using + standard Linux mechanisms. + +* Linux tells Hyper-V the guest physical address (GPA) of the + allocated memory. Many shared areas are kept to 1 page so that a + single GPA is sufficient. Larger shared areas require a list of + GPAs, which usually do not need to be contiguous in the guest + physical address space. How Hyper-V is told about the GPA or list + of GPAs varies. In some cases, a single GPA is written to a + synthetic register. In other cases, a GPA or list of GPAs is sent + in a VMbus message. + +* Hyper-V translates the GPAs into "real" physical memory addresses, + and creates a virtual mapping that it can use to access the memory. + +* Linux can later revoke sharing it has previously established by + telling Hyper-V to set the shared GPA to zero. + +Hyper-V operates with a page size of 4 Kbytes. GPAs communicated to +Hyper-V may be in the form of page numbers, and always describe a +range of 4 Kbytes. Since the Linux guest page size on x86/x64 is +also 4 Kbytes, the mapping from guest page to Hyper-V page is 1-to-1. +On arm64, Hyper-V supports guests with 4/16/64 Kbyte pages as +defined by the arm64 architecture. If Linux is using 16 or 64 +Kbyte pages, Linux code must be careful to communicate with Hyper-V +only in terms of 4 Kbyte pages. HV_HYP_PAGE_SIZE and related macros +are used in code that communicates with Hyper-V so that it works +correctly in all configurations. + +As described in the TLFS, a few memory pages shared between Hyper-V +and the Linux guest are "overlay" pages. With overlay pages, Linux +uses the usual approach of allocating guest memory and telling +Hyper-V the GPA of the allocated memory. But Hyper-V then replaces +that physical memory page with a page it has allocated, and the +original physical memory page is no longer accessible in the guest +VM. Linux may access the memory normally as if it were the memory +that it originally allocated. The "overlay" behavior is visible +only because the contents of the page (as seen by Linux) change at +the time that Linux originally establishes the sharing and the +overlay page is inserted. Similarly, the contents change if Linux +revokes the sharing, in which case Hyper-V removes the overlay page, +and the guest page originally allocated by Linux becomes visible +again. + +Before Linux does a kexec to a kdump kernel or any other kernel, +memory shared with Hyper-V should be revoked. Hyper-V could modify +a shared page or remove an overlay page after the new kernel is +using the page for a different purpose, corrupting the new kernel. +Hyper-V does not provide a single "set everything" operation to +guest VMs, so Linux code must individually revoke all sharing before +doing kexec. See hv_kexec_handler() and hv_crash_handler(). But +the crash/panic path still has holes in cleanup because some shared +pages are set using per-CPU synthetic registers and there's no +mechanism to revoke the shared pages for CPUs other than the CPU +running the panic path. + +CPU Management +-------------- +Hyper-V does not have a ability to hot-add or hot-remove a CPU +from a running VM. However, Windows Server 2019 Hyper-V and +earlier versions may provide guests with ACPI tables that indicate +more CPUs than are actually present in the VM. As is normal, Linux +treats these additional CPUs as potential hot-add CPUs, and reports +them as such even though Hyper-V will never actually hot-add them. +Starting in Windows Server 2022 Hyper-V, the ACPI tables reflect +only the CPUs actually present in the VM, so Linux does not report +any hot-add CPUs. + +A Linux guest CPU may be taken offline using the normal Linux +mechanisms, provided no VMbus channel interrupts are assigned to +the CPU. See the section on VMbus Interrupts for more details +on how VMbus channel interrupts can be re-assigned to permit +taking a CPU offline. + +32-bit and 64-bit +----------------- +On x86/x64, Hyper-V supports 32-bit and 64-bit guests, and Linux +will build and run in either version. While the 32-bit version is +expected to work, it is used rarely and may suffer from undetected +regressions. + +On arm64, Hyper-V supports only 64-bit guests. + +Endian-ness +----------- +All communication between Hyper-V and guest VMs uses Little-Endian +format on both x86/x64 and arm64. Big-endian format on arm64 is not +supported by Hyper-V, and Linux code does not use endian-ness macros +when accessing data shared with Hyper-V. + +Versioning +---------- +Current Linux kernels operate correctly with older versions of +Hyper-V back to Windows Server 2012 Hyper-V. Support for running +on the original Hyper-V release in Windows Server 2008/2008 R2 +has been removed. + +A Linux guest on Hyper-V outputs in dmesg the version of Hyper-V +it is running on. This version is in the form of a Windows build +number and is for display purposes only. Linux code does not +test this version number at runtime to determine available features +and functionality. Hyper-V indicates feature/function availability +via flags in synthetic MSRs that Hyper-V provides to the guest, +and the guest code tests these flags. + +VMbus has its own protocol version that is negotiated during the +initial VMbus connection from the guest to Hyper-V. This version +number is also output to dmesg during boot. This version number +is checked in a few places in the code to determine if specific +functionality is present. + +Furthermore, each synthetic device on VMbus also has a protocol +version that is separate from the VMbus protocol version. Device +drivers for these synthetic devices typically negotiate the device +protocol version, and may test that protocol version to determine +if specific device functionality is present. + +Code Packaging +-------------- +Hyper-V related code appears in the Linux kernel code tree in three +main areas: + +1. drivers/hv + +2. arch/x86/hyperv and arch/arm64/hyperv + +3. individual device driver areas such as drivers/scsi, drivers/net, + drivers/clocksource, etc. + +A few miscellaneous files appear elsewhere. See the full list under +"Hyper-V/Azure CORE AND DRIVERS" and "DRM DRIVER FOR HYPERV +SYNTHETIC VIDEO DEVICE" in the MAINTAINERS file. + +The code in #1 and #2 is built only when CONFIG_HYPERV is set. +Similarly, the code for most Hyper-V related drivers is built only +when CONFIG_HYPERV is set. + +Most Hyper-V related code in #1 and #3 can be built as a module. +The architecture specific code in #2 must be built-in. Also, +drivers/hv/hv_common.c is low-level code that is common across +architectures and must be built-in. diff --git a/Documentation/virt/hyperv/vmbus.rst b/Documentation/virt/hyperv/vmbus.rst new file mode 100644 index 000000000000..d2012d9022c5 --- /dev/null +++ b/Documentation/virt/hyperv/vmbus.rst @@ -0,0 +1,303 @@ +.. SPDX-License-Identifier: GPL-2.0 + +VMbus +===== +VMbus is a software construct provided by Hyper-V to guest VMs. It +consists of a control path and common facilities used by synthetic +devices that Hyper-V presents to guest VMs. The control path is +used to offer synthetic devices to the guest VM and, in some cases, +to rescind those devices. The common facilities include software +channels for communicating between the device driver in the guest VM +and the synthetic device implementation that is part of Hyper-V, and +signaling primitives to allow Hyper-V and the guest to interrupt +each other. + +VMbus is modeled in Linux as a bus, with the expected /sys/bus/vmbus +entry in a running Linux guest. The VMbus driver (drivers/hv/vmbus_drv.c) +establishes the VMbus control path with the Hyper-V host, then +registers itself as a Linux bus driver. It implements the standard +bus functions for adding and removing devices to/from the bus. + +Most synthetic devices offered by Hyper-V have a corresponding Linux +device driver. These devices include: + +* SCSI controller +* NIC +* Graphics frame buffer +* Keyboard +* Mouse +* PCI device pass-thru +* Heartbeat +* Time Sync +* Shutdown +* Memory balloon +* Key/Value Pair (KVP) exchange with Hyper-V +* Hyper-V online backup (a.k.a. VSS) + +Guest VMs may have multiple instances of the synthetic SCSI +controller, synthetic NIC, and PCI pass-thru devices. Other +synthetic devices are limited to a single instance per VM. Not +listed above are a small number of synthetic devices offered by +Hyper-V that are used only by Windows guests and for which Linux +does not have a driver. + +Hyper-V uses the terms "VSP" and "VSC" in describing synthetic +devices. "VSP" refers to the Hyper-V code that implements a +particular synthetic device, while "VSC" refers to the driver for +the device in the guest VM. For example, the Linux driver for the +synthetic NIC is referred to as "netvsc" and the Linux driver for +the synthetic SCSI controller is "storvsc". These drivers contain +functions with names like "storvsc_connect_to_vsp". + +VMbus channels +-------------- +An instance of a synthetic device uses VMbus channels to communicate +between the VSP and the VSC. Channels are bi-directional and used +for passing messages. Most synthetic devices use a single channel, +but the synthetic SCSI controller and synthetic NIC may use multiple +channels to achieve higher performance and greater parallelism. + +Each channel consists of two ring buffers. These are classic ring +buffers from a university data structures textbook. If the read +and writes pointers are equal, the ring buffer is considered to be +empty, so a full ring buffer always has at least one byte unused. +The "in" ring buffer is for messages from the Hyper-V host to the +guest, and the "out" ring buffer is for messages from the guest to +the Hyper-V host. In Linux, the "in" and "out" designations are as +viewed by the guest side. The ring buffers are memory that is +shared between the guest and the host, and they follow the standard +paradigm where the memory is allocated by the guest, with the list +of GPAs that make up the ring buffer communicated to the host. Each +ring buffer consists of a header page (4 Kbytes) with the read and +write indices and some control flags, followed by the memory for the +actual ring. The size of the ring is determined by the VSC in the +guest and is specific to each synthetic device. The list of GPAs +making up the ring is communicated to the Hyper-V host over the +VMbus control path as a GPA Descriptor List (GPADL). See function +vmbus_establish_gpadl(). + +Each ring buffer is mapped into contiguous Linux kernel virtual +space in three parts: 1) the 4 Kbyte header page, 2) the memory +that makes up the ring itself, and 3) a second mapping of the memory +that makes up the ring itself. Because (2) and (3) are contiguous +in kernel virtual space, the code that copies data to and from the +ring buffer need not be concerned with ring buffer wrap-around. +Once a copy operation has completed, the read or write index may +need to be reset to point back into the first mapping, but the +actual data copy does not need to be broken into two parts. This +approach also allows complex data structures to be easily accessed +directly in the ring without handling wrap-around. + +On arm64 with page sizes > 4 Kbytes, the header page must still be +passed to Hyper-V as a 4 Kbyte area. But the memory for the actual +ring must be aligned to PAGE_SIZE and have a size that is a multiple +of PAGE_SIZE so that the duplicate mapping trick can be done. Hence +a portion of the header page is unused and not communicated to +Hyper-V. This case is handled by vmbus_establish_gpadl(). + +Hyper-V enforces a limit on the aggregate amount of guest memory +that can be shared with the host via GPADLs. This limit ensures +that a rogue guest can't force the consumption of excessive host +resources. For Windows Server 2019 and later, this limit is +approximately 1280 Mbytes. For versions prior to Windows Server +2019, the limit is approximately 384 Mbytes. + +VMbus messages +-------------- +All VMbus messages have a standard header that includes the message +length, the offset of the message payload, some flags, and a +transactionID. The portion of the message after the header is +unique to each VSP/VSC pair. + +Messages follow one of two patterns: + +* Unidirectional: Either side sends a message and does not + expect a response message +* Request/response: One side (usually the guest) sends a message + and expects a response + +The transactionID (a.k.a. "requestID") is for matching requests & +responses. Some synthetic devices allow multiple requests to be in- +flight simultaneously, so the guest specifies a transactionID when +sending a request. Hyper-V sends back the same transactionID in the +matching response. + +Messages passed between the VSP and VSC are control messages. For +example, a message sent from the storvsc driver might be "execute +this SCSI command". If a message also implies some data transfer +between the guest and the Hyper-V host, the actual data to be +transferred may be embedded with the control message, or it may be +specified as a separate data buffer that the Hyper-V host will +access as a DMA operation. The former case is used when the size of +the data is small and the cost of copying the data to and from the +ring buffer is minimal. For example, time sync messages from the +Hyper-V host to the guest contain the actual time value. When the +data is larger, a separate data buffer is used. In this case, the +control message contains a list of GPAs that describe the data +buffer. For example, the storvsc driver uses this approach to +specify the data buffers to/from which disk I/O is done. + +Three functions exist to send VMbus messages: + +1. vmbus_sendpacket(): Control-only messages and messages with + embedded data -- no GPAs +2. vmbus_sendpacket_pagebuffer(): Message with list of GPAs + identifying data to transfer. An offset and length is + associated with each GPA so that multiple discontinuous areas + of guest memory can be targeted. +3. vmbus_sendpacket_mpb_desc(): Message with list of GPAs + identifying data to transfer. A single offset and length is + associated with a list of GPAs. The GPAs must describe a + single logical area of guest memory to be targeted. + +Historically, Linux guests have trusted Hyper-V to send well-formed +and valid messages, and Linux drivers for synthetic devices did not +fully validate messages. With the introduction of processor +technologies that fully encrypt guest memory and that allow the +guest to not trust the hypervisor (AMD SNP-SEV, Intel TDX), trusting +the Hyper-V host is no longer a valid assumption. The drivers for +VMbus synthetic devices are being updated to fully validate any +values read from memory that is shared with Hyper-V, which includes +messages from VMbus devices. To facilitate such validation, +messages read by the guest from the "in" ring buffer are copied to a +temporary buffer that is not shared with Hyper-V. Validation is +performed in this temporary buffer without the risk of Hyper-V +maliciously modifying the message after it is validated but before +it is used. + +VMbus interrupts +---------------- +VMbus provides a mechanism for the guest to interrupt the host when +the guest has queued new messages in a ring buffer. The host +expects that the guest will send an interrupt only when an "out" +ring buffer transitions from empty to non-empty. If the guest sends +interrupts at other times, the host deems such interrupts to be +unnecessary. If a guest sends an excessive number of unnecessary +interrupts, the host may throttle that guest by suspending its +execution for a few seconds to prevent a denial-of-service attack. + +Similarly, the host will interrupt the guest when it sends a new +message on the VMbus control path, or when a VMbus channel "in" ring +buffer transitions from empty to non-empty. Each CPU in the guest +may receive VMbus interrupts, so they are best modeled as per-CPU +interrupts in Linux. This model works well on arm64 where a single +per-CPU IRQ is allocated for VMbus. Since x86/x64 lacks support for +per-CPU IRQs, an x86 interrupt vector is statically allocated (see +HYPERVISOR_CALLBACK_VECTOR) across all CPUs and explicitly coded to +call the VMbus interrupt service routine. These interrupts are +visible in /proc/interrupts on the "HYP" line. + +The guest CPU that a VMbus channel will interrupt is selected by the +guest when the channel is created, and the host is informed of that +selection. VMbus devices are broadly grouped into two categories: + +1. "Slow" devices that need only one VMbus channel. The devices + (such as keyboard, mouse, heartbeat, and timesync) generate + relatively few interrupts. Their VMbus channels are all + assigned to interrupt the VMBUS_CONNECT_CPU, which is always + CPU 0. + +2. "High speed" devices that may use multiple VMbus channels for + higher parallelism and performance. These devices include the + synthetic SCSI controller and synthetic NIC. Their VMbus + channels interrupts are assigned to CPUs that are spread out + among the available CPUs in the VM so that interrupts on + multiple channels can be processed in parallel. + +The assignment of VMbus channel interrupts to CPUs is done in the +function init_vp_index(). This assignment is done outside of the +normal Linux interrupt affinity mechanism, so the interrupts are +neither "unmanaged" nor "managed" interrupts. + +The CPU that a VMbus channel will interrupt can be seen in +/sys/bus/vmbus/devices/<deviceGUID>/ channels/<channelRelID>/cpu. +When running on later versions of Hyper-V, the CPU can be changed +by writing a new value to this sysfs entry. Because the interrupt +assignment is done outside of the normal Linux affinity mechanism, +there are no entries in /proc/irq corresponding to individual +VMbus channel interrupts. + +An online CPU in a Linux guest may not be taken offline if it has +VMbus channel interrupts assigned to it. Any such channel +interrupts must first be manually reassigned to another CPU as +described above. When no channel interrupts are assigned to the +CPU, it can be taken offline. + +When a guest CPU receives a VMbus interrupt from the host, the +function vmbus_isr() handles the interrupt. It first checks for +channel interrupts by calling vmbus_chan_sched(), which looks at a +bitmap setup by the host to determine which channels have pending +interrupts on this CPU. If multiple channels have pending +interrupts for this CPU, they are processed sequentially. When all +channel interrupts have been processed, vmbus_isr() checks for and +processes any message received on the VMbus control path. + +The VMbus channel interrupt handling code is designed to work +correctly even if an interrupt is received on a CPU other than the +CPU assigned to the channel. Specifically, the code does not use +CPU-based exclusion for correctness. In normal operation, Hyper-V +will interrupt the assigned CPU. But when the CPU assigned to a +channel is being changed via sysfs, the guest doesn't know exactly +when Hyper-V will make the transition. The code must work correctly +even if there is a time lag before Hyper-V starts interrupting the +new CPU. See comments in target_cpu_store(). + +VMbus device creation/deletion +------------------------------ +Hyper-V and the Linux guest have a separate message-passing path +that is used for synthetic device creation and deletion. This +path does not use a VMbus channel. See vmbus_post_msg() and +vmbus_on_msg_dpc(). + +The first step is for the guest to connect to the generic +Hyper-V VMbus mechanism. As part of establishing this connection, +the guest and Hyper-V agree on a VMbus protocol version they will +use. This negotiation allows newer Linux kernels to run on older +Hyper-V versions, and vice versa. + +The guest then tells Hyper-V to "send offers". Hyper-V sends an +offer message to the guest for each synthetic device that the VM +is configured to have. Each VMbus device type has a fixed GUID +known as the "class ID", and each VMbus device instance is also +identified by a GUID. The offer message from Hyper-V contains +both GUIDs to uniquely (within the VM) identify the device. +There is one offer message for each device instance, so a VM with +two synthetic NICs will get two offers messages with the NIC +class ID. The ordering of offer messages can vary from boot-to-boot +and must not be assumed to be consistent in Linux code. Offer +messages may also arrive long after Linux has initially booted +because Hyper-V supports adding devices, such as synthetic NICs, +to running VMs. A new offer message is processed by +vmbus_process_offer(), which indirectly invokes vmbus_add_channel_work(). + +Upon receipt of an offer message, the guest identifies the device +type based on the class ID, and invokes the correct driver to set up +the device. Driver/device matching is performed using the standard +Linux mechanism. + +The device driver probe function opens the primary VMbus channel to +the corresponding VSP. It allocates guest memory for the channel +ring buffers and shares the ring buffer with the Hyper-V host by +giving the host a list of GPAs for the ring buffer memory. See +vmbus_establish_gpadl(). + +Once the ring buffer is set up, the device driver and VSP exchange +setup messages via the primary channel. These messages may include +negotiating the device protocol version to be used between the Linux +VSC and the VSP on the Hyper-V host. The setup messages may also +include creating additional VMbus channels, which are somewhat +mis-named as "sub-channels" since they are functionally +equivalent to the primary channel once they are created. + +Finally, the device driver may create entries in /dev as with +any device driver. + +The Hyper-V host can send a "rescind" message to the guest to +remove a device that was previously offered. Linux drivers must +handle such a rescind message at any time. Rescinding a device +invokes the device driver "remove" function to cleanly shut +down the device and remove it. Once a synthetic device is +rescinded, neither Hyper-V nor Linux retains any state about +its previous existence. Such a device might be re-added later, +in which case it is treated as an entirely new device. See +vmbus_onoffer_rescind(). diff --git a/Documentation/virt/index.rst b/Documentation/virt/index.rst index 492f0920b988..2f1cffa87b1b 100644 --- a/Documentation/virt/index.rst +++ b/Documentation/virt/index.rst @@ -14,6 +14,7 @@ Linux Virtualization Support ne_overview acrn/index coco/sev-guest + hyperv/index .. only:: html and subproject diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 11e00a46c610..dca926762f1f 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -4667,7 +4667,7 @@ encrypted VMs. Currently, this ioctl is used for issuing Secure Encrypted Virtualization (SEV) commands on AMD Processors. The SEV commands are defined in -Documentation/virt/kvm/amd-memory-encryption.rst. +Documentation/virt/kvm/x86/amd-memory-encryption.rst. 4.111 KVM_MEMORY_ENCRYPT_REG_REGION ----------------------------------- @@ -5657,7 +5657,8 @@ by a string of size ``name_size``. #define KVM_STATS_UNIT_BYTES (0x1 << KVM_STATS_UNIT_SHIFT) #define KVM_STATS_UNIT_SECONDS (0x2 << KVM_STATS_UNIT_SHIFT) #define KVM_STATS_UNIT_CYCLES (0x3 << KVM_STATS_UNIT_SHIFT) - #define KVM_STATS_UNIT_MAX KVM_STATS_UNIT_CYCLES + #define KVM_STATS_UNIT_BOOLEAN (0x4 << KVM_STATS_UNIT_SHIFT) + #define KVM_STATS_UNIT_MAX KVM_STATS_UNIT_BOOLEAN #define KVM_STATS_BASE_SHIFT 8 #define KVM_STATS_BASE_MASK (0xF << KVM_STATS_BASE_SHIFT) @@ -5702,14 +5703,13 @@ Bits 0-3 of ``flags`` encode the type: by the ``hist_param`` field. The range of the Nth bucket (1 <= N < ``size``) is [``hist_param``*(N-1), ``hist_param``*N), while the range of the last bucket is [``hist_param``*(``size``-1), +INF). (+INF means positive infinity - value.) The bucket value indicates how many samples fell in the bucket's range. + value.) * ``KVM_STATS_TYPE_LOG_HIST`` The statistic is reported as a logarithmic histogram. The number of buckets is specified by the ``size`` field. The range of the first bucket is [0, 1), while the range of the last bucket is [pow(2, ``size``-2), +INF). Otherwise, The Nth bucket (1 < N < ``size``) covers - [pow(2, N-2), pow(2, N-1)). The bucket value indicates how many samples fell - in the bucket's range. + [pow(2, N-2), pow(2, N-1)). Bits 4-7 of ``flags`` encode the unit: @@ -5724,6 +5724,15 @@ Bits 4-7 of ``flags`` encode the unit: It indicates that the statistics data is used to measure time or latency. * ``KVM_STATS_UNIT_CYCLES`` It indicates that the statistics data is used to measure CPU clock cycles. + * ``KVM_STATS_UNIT_BOOLEAN`` + It indicates that the statistic will always be either 0 or 1. Boolean + statistics of "peak" type will never go back from 1 to 0. Boolean + statistics can be linear histograms (with two buckets) but not logarithmic + histograms. + +Note that, in the case of histograms, the unit applies to the bucket +ranges, while the bucket value indicates how many samples fell in the +bucket's range. Bits 8-11 of ``flags``, together with ``exponent``, encode the scale of the unit: @@ -5746,7 +5755,7 @@ the corresponding statistics data. The ``bucket_size`` field is used as a parameter for histogram statistics data. It is only used by linear histogram statistics data, specifying the size of a -bucket. +bucket in the unit expressed by bits 4-11 of ``flags`` together with ``exponent``. The ``name`` field is the name string of the statistics data. The name string starts at the end of ``struct kvm_stats_desc``. The maximum length including @@ -7670,7 +7679,7 @@ architecture-specific interfaces. This capability and the architecture- specific interfaces must be consistent, i.e. if one says the feature is supported, than the other should as well and vice versa. For arm64 see Documentation/virt/kvm/devices/vcpu.rst "KVM_ARM_VCPU_PVTIME_CTRL". -For x86 see Documentation/virt/kvm/msr.rst "MSR_KVM_STEAL_TIME". +For x86 see Documentation/virt/kvm/x86/msr.rst "MSR_KVM_STEAL_TIME". 8.25 KVM_CAP_S390_DIAG318 ------------------------- diff --git a/Documentation/virt/kvm/arm/hyp-abi.rst b/Documentation/virt/kvm/arm/hyp-abi.rst index 4d43fbc25195..412b276449d3 100644 --- a/Documentation/virt/kvm/arm/hyp-abi.rst +++ b/Documentation/virt/kvm/arm/hyp-abi.rst @@ -60,12 +60,13 @@ these functions (see arch/arm{,64}/include/asm/virt.h): * :: - x0 = HVC_VHE_RESTART (arm64 only) + x0 = HVC_FINALISE_EL2 (arm64 only) - Attempt to upgrade the kernel's exception level from EL1 to EL2 by enabling - the VHE mode. This is conditioned by the CPU supporting VHE, the EL2 MMU - being off, and VHE not being disabled by any other means (command line - option, for example). + Finish configuring EL2 depending on the command-line options, + including an attempt to upgrade the kernel's exception level from + EL1 to EL2 by enabling the VHE mode. This is conditioned by the CPU + supporting VHE, the EL2 MMU being off, and VHE not being disabled by + any other means (command line option, for example). Any other value of r0/x0 triggers a hypervisor-specific handling, which is not documented here. diff --git a/Documentation/virt/kvm/s390/s390-pv-boot.rst b/Documentation/virt/kvm/s390/s390-pv-boot.rst index 73a6083cb5e7..96c48480a360 100644 --- a/Documentation/virt/kvm/s390/s390-pv-boot.rst +++ b/Documentation/virt/kvm/s390/s390-pv-boot.rst @@ -10,7 +10,7 @@ The memory of Protected Virtual Machines (PVMs) is not accessible to I/O or the hypervisor. In those cases where the hypervisor needs to access the memory of a PVM, that memory must be made accessible. Memory made accessible to the hypervisor will be encrypted. See -Documentation/virt/kvm/s390-pv.rst for details." +Documentation/virt/kvm/s390/s390-pv.rst for details." On IPL (boot) a small plaintext bootloader is started, which provides information about the encrypted components and necessary metadata to diff --git a/Documentation/virt/kvm/x86/hypercalls.rst b/Documentation/virt/kvm/x86/hypercalls.rst index e56fa8b9cfca..10db7924720f 100644 --- a/Documentation/virt/kvm/x86/hypercalls.rst +++ b/Documentation/virt/kvm/x86/hypercalls.rst @@ -22,7 +22,7 @@ S390: number in R1. For further information on the S390 diagnose call as supported by KVM, - refer to Documentation/virt/kvm/s390-diag.rst. + refer to Documentation/virt/kvm/s390/s390-diag.rst. PowerPC: It uses R3-R10 and hypercall number in R11. R4-R11 are used as output registers. diff --git a/Documentation/virt/uml/user_mode_linux_howto_v2.rst b/Documentation/virt/uml/user_mode_linux_howto_v2.rst index 863f67b72c05..af2a97429692 100644 --- a/Documentation/virt/uml/user_mode_linux_howto_v2.rst +++ b/Documentation/virt/uml/user_mode_linux_howto_v2.rst @@ -322,7 +322,7 @@ Shared Options * ``v6=[0,1]`` to specify if a v6 connection is desired for all transports which operate over IP. Additionally, for transports that have some differences in the way they operate over v4 and v6 (for example - EoL2TPv3), sets the correct mode of operation. In the absense of this + EoL2TPv3), sets the correct mode of operation. In the absence of this option, the socket type is determined based on what do the src and dst arguments resolve/parse to. diff --git a/Documentation/vm/hwpoison.rst b/Documentation/vm/hwpoison.rst index c742de1769d1..b9d5253c1305 100644 --- a/Documentation/vm/hwpoison.rst +++ b/Documentation/vm/hwpoison.rst @@ -120,7 +120,8 @@ Testing unpoison-pfn Software-unpoison page at PFN echoed into this file. This way a page can be reused again. This only works for Linux - injected failures, not for real memory failures. + injected failures, not for real memory failures. Once any hardware + memory failure happens, this feature is disabled. Note these injection interfaces are not stable and might change between kernel versions diff --git a/Documentation/vm/overcommit-accounting.rst b/Documentation/vm/overcommit-accounting.rst index 1addb0c374a4..a4895d6fc1c2 100644 --- a/Documentation/vm/overcommit-accounting.rst +++ b/Documentation/vm/overcommit-accounting.rst @@ -1,5 +1,3 @@ -.. _overcommit_accounting: - ===================== Overcommit Accounting ===================== diff --git a/Documentation/vm/page_migration.rst b/Documentation/vm/page_migration.rst index 8c5cb8147e55..11493bad7112 100644 --- a/Documentation/vm/page_migration.rst +++ b/Documentation/vm/page_migration.rst @@ -152,110 +152,15 @@ Steps: Non-LRU page migration ====================== -Although migration originally aimed for reducing the latency of memory accesses -for NUMA, compaction also uses migration to create high-order pages. +Although migration originally aimed for reducing the latency of memory +accesses for NUMA, compaction also uses migration to create high-order +pages. For compaction purposes, it is also useful to be able to move +non-LRU pages, such as zsmalloc and virtio-balloon pages. -Current problem of the implementation is that it is designed to migrate only -*LRU* pages. However, there are potential non-LRU pages which can be migrated -in drivers, for example, zsmalloc, virtio-balloon pages. - -For virtio-balloon pages, some parts of migration code path have been hooked -up and added virtio-balloon specific functions to intercept migration logics. -It's too specific to a driver so other drivers who want to make their pages -movable would have to add their own specific hooks in the migration path. - -To overcome the problem, VM supports non-LRU page migration which provides -generic functions for non-LRU movable pages without driver specific hooks -in the migration path. - -If a driver wants to make its pages movable, it should define three functions -which are function pointers of struct address_space_operations. - -1. ``bool (*isolate_page) (struct page *page, isolate_mode_t mode);`` - - What VM expects from isolate_page() function of driver is to return *true* - if driver isolates the page successfully. On returning true, VM marks the page - as PG_isolated so concurrent isolation in several CPUs skip the page - for isolation. If a driver cannot isolate the page, it should return *false*. - - Once page is successfully isolated, VM uses page.lru fields so driver - shouldn't expect to preserve values in those fields. - -2. ``int (*migratepage) (struct address_space *mapping,`` -| ``struct page *newpage, struct page *oldpage, enum migrate_mode);`` - - After isolation, VM calls migratepage() of driver with the isolated page. - The function of migratepage() is to move the contents of the old page to the - new page - and set up fields of struct page newpage. Keep in mind that you should - indicate to the VM the oldpage is no longer movable via __ClearPageMovable() - under page_lock if you migrated the oldpage successfully and returned - MIGRATEPAGE_SUCCESS. If driver cannot migrate the page at the moment, driver - can return -EAGAIN. On -EAGAIN, VM will retry page migration in a short time - because VM interprets -EAGAIN as "temporary migration failure". On returning - any error except -EAGAIN, VM will give up the page migration without - retrying. - - Driver shouldn't touch the page.lru field while in the migratepage() function. - -3. ``void (*putback_page)(struct page *);`` - - If migration fails on the isolated page, VM should return the isolated page - to the driver so VM calls the driver's putback_page() with the isolated page. - In this function, the driver should put the isolated page back into its own data - structure. - -Non-LRU movable page flags - - There are two page flags for supporting non-LRU movable page. - - * PG_movable - - Driver should use the function below to make page movable under page_lock:: - - void __SetPageMovable(struct page *page, struct address_space *mapping) - - It needs argument of address_space for registering migration - family functions which will be called by VM. Exactly speaking, - PG_movable is not a real flag of struct page. Rather, VM - reuses the page->mapping's lower bits to represent it:: - - #define PAGE_MAPPING_MOVABLE 0x2 - page->mapping = page->mapping | PAGE_MAPPING_MOVABLE; - - so driver shouldn't access page->mapping directly. Instead, driver should - use page_mapping() which masks off the low two bits of page->mapping under - page lock so it can get the right struct address_space. - - For testing of non-LRU movable pages, VM supports __PageMovable() function. - However, it doesn't guarantee to identify non-LRU movable pages because - the page->mapping field is unified with other variables in struct page. - If the driver releases the page after isolation by VM, page->mapping - doesn't have a stable value although it has PAGE_MAPPING_MOVABLE set - (look at __ClearPageMovable). But __PageMovable() is cheap to call whether - page is LRU or non-LRU movable once the page has been isolated because LRU - pages can never have PAGE_MAPPING_MOVABLE set in page->mapping. It is also - good for just peeking to test non-LRU movable pages before more expensive - checking with lock_page() in pfn scanning to select a victim. - - For guaranteeing non-LRU movable page, VM provides PageMovable() function. - Unlike __PageMovable(), PageMovable() validates page->mapping and - mapping->a_ops->isolate_page under lock_page(). The lock_page() prevents - sudden destroying of page->mapping. - - Drivers using __SetPageMovable() should clear the flag via - __ClearMovablePage() under page_lock() before the releasing the page. - - * PG_isolated - - To prevent concurrent isolation among several CPUs, VM marks isolated page - as PG_isolated under lock_page(). So if a CPU encounters PG_isolated - non-LRU movable page, it can skip it. Driver doesn't need to manipulate the - flag because VM will set/clear it automatically. Keep in mind that if the - driver sees a PG_isolated page, it means the page has been isolated by the - VM so it shouldn't touch the page.lru field. - The PG_isolated flag is aliased with the PG_reclaim flag so drivers - shouldn't use PG_isolated for its own purposes. +If a driver wants to make its pages movable, it should define a struct +movable_operations. It then needs to call __SetPageMovable() on each +page that it may be able to move. This uses the ``page->mapping`` field, +so this field is not available for the driver to use for other purposes. Monitoring Migration ===================== @@ -286,3 +191,5 @@ THP_MIGRATION_FAIL and PGMIGRATE_FAIL to increase. Christoph Lameter, May 8, 2006. Minchan Kim, Mar 28, 2016. + +.. kernel-doc:: include/linux/migrate.h diff --git a/Documentation/x86/orc-unwinder.rst b/Documentation/x86/orc-unwinder.rst index 9a66a88be765..cdb257015bd9 100644 --- a/Documentation/x86/orc-unwinder.rst +++ b/Documentation/x86/orc-unwinder.rst @@ -140,7 +140,7 @@ Unwinder implementation details Objtool generates the ORC data by integrating with the compile-time stack metadata validation feature, which is described in detail in -tools/objtool/Documentation/stack-validation.txt. After analyzing all +tools/objtool/Documentation/objtool.txt. After analyzing all the code paths of a .o file, it creates an array of orc_entry structs, and a parallel array of instruction addresses associated with those structs, and writes them to the .orc_unwind and .orc_unwind_ip sections diff --git a/Documentation/x86/x86_64/uefi.rst b/Documentation/x86/x86_64/uefi.rst index 3b894103a734..fbc30c9a071d 100644 --- a/Documentation/x86/x86_64/uefi.rst +++ b/Documentation/x86/x86_64/uefi.rst @@ -29,7 +29,7 @@ Mechanics be selected:: CONFIG_EFI=y - CONFIG_EFI_VARS=y or m # optional + CONFIG_EFIVAR_FS=y or m # optional - Create a VFAT partition on the disk - Copy the following to the VFAT partition: |